Background

There's a complicated issue related to deployment, references, Windows not being able to handle symlinks, etc. that is causing an issue. This ticket aims to solve that issue through package bundling and rearchitecture of the projects file structure.

Acceptance Criteria

• The project file structure is rearchitected to meet the needs of the bundler and deployment
• Package bundling is added to compile the GDJ JS files into one JS file in the root
  • This was abandoned, for now
• Local testing works without the need for manual intervention on *nix and Windows
• Demo deployment works
  • demo-hosting.yml GitHub Action/workflow is updated as needed
• GitHub NPM package building works
  • release-package.yml GitHub Action/workflow is updated as needed
  • This was abandoned, for now
• All documentation references to file paths are updated
  • Most of the documentation that would be impacted has not yet been merged into development or main or it was created as part of this issue
• Build documentation is updated

Approach

• Try using webpack.js.org for bundling src/*.js files into one guitar-diagrams.js file in the root
  • This may be a solution, but it was too complicated to go straight to this
• Reference the src/*.js files from the docs/examples/index.html file
  • Consider moving examples/ out of docs/ if this helps
• Update GitHub Actions as needed
• Test locally, with deployment, with demo hosting, and with Windows

Notes

There is some overlap with the code pushed in this issue and the code that would be pushed in #30, specifically in the code-owner-docs.md file.

Background

When a background color is specified, it becomes apparent that there is no padding around the diagram (see example 5):

Diagram padding should be an option for users in case they want to have a nice uniform padding around the diagram elements.

Acceptance Criteria

• Users can specify diagram padding for even spacing around the elements
• The padding is correctly calculated based on label spacing/location

Approach

• TBD

Notes

TBD

Background

It's not yet decided if there will be an official site for this (e.g., guitardiagramsjs.dev or whatever), but if there will be, this ticket is for that work.

Acceptance Criteria

• A domain name is chosen and purchased
• A platform is chosen
• A hosting service is chosen
• The site is built

Notes

Consider adding a sandbox, like JSfiddle or like Eloquent Javascript.

Background

See this video at 1:35 for an explanation of the builder pattern. Essentially, it may simplify the way that the library is called for configuring a drawing. For example, this:

let gdj2 = new GuitarDiagramsJS();
gdj2.config.canvasID = 'diagram-2-canvas';
gdj2.config.stringNamesEnabled = true;
gdj2.addCanvas('diagram-2');
gdj2.drawNeck();
gdj2.addMarker(1, 1, '1', GuitarDiagramsJS.Shape.Square); // add a square marker on string 1, fret 1, text '1'
gdj2.addMarker(2, 2, '2', GuitarDiagramsJS.Shape.Triangle); // add a triangle marker on string 2, fret 2, text '2'
gdj2.addMarker(3, 3, '3', GuitarDiagramsJS.Shape.Diamond); // add a diamond marker on string 3, fret 3, text '3'
gdj2.addMarker(4, 4, '4'); // add a default (circle) marker on string 4, fret 4, text '4'
gdj2.addMarker(5, 0, '0'); // add a default (circle) marker on string 5, fret 0, text '0'
gdj2.addMarker(6, 0, 'X'); // add a default (circle) marker on string 6, fret 0, text 'X'
gdj2.addMarker(3, 1); // add a default (circle) marker on string 3, fret 1, text empty

...might become simpler like this:

let gdj2 = new GuitarDiagramsJS();
gdj2.config.setCanvasID('diagram-2-canvas')
    .setStringNamesEnabled(true);
gdj2.addCanvas('diagram-2')
    .drawNeck()
    .addMarker(1, 1, '1', GuitarDiagramsJS.Shape.Square)
    .addMarker(2, 2, '2', GuitarDiagramsJS.Shape.Triangle)
    .addMarker(3, 3, '3', GuitarDiagramsJS.Shape.Diamond)
    .addMarker(4, 4, '4')
    .addMarker(5, 0, '0')
    .addMarker(6, 0, 'X')
    .addMarker(3, 1);

Acceptance Criteria

• Determine if a builder pattern would improve the user experience or developer experience
• If the previous step determines that the builder pattern is desired, implement the builder pattern ❓

Approach

• TBD

Notes

TBD

Background

Currently, markers have the properties to allow for customizing the visuals (font size, color, etc.), but those are not exposed to the end-user API as marker creation is abstracted. The app needs a way for user's to specify marker-specific configurations, both globally (for all) and individually (per marker).

Acceptance Criteria

• Users can specify customized visuals for markers both individually and globally
• The following fields are available for customization:
  • color fill
  • color stroke
  • color font

Approach

• Consider exposing marker creation, then add to marker object, or...
• Pass optional parameters (or config object) to the marker during creation

Notes

TBD

Background

Formatting/style presets could be a handy feature for site builders to choose predefined themes, like black and white.

Acceptance Criteria

• Formatting styles are defined
• Site builders can easily apply a style to a diagram
  • ...or to all diagrams, if #7 is implemented

Approach

• Use an enum for style names
• Pass the enum to the method that will apply the styles
• Should this be an instance method (gdj1.setTheme(GDJTheme.Dark);) or a static method (GDJ.SetTheme(gdj1, GDJTheme.Dark);)?

Notes

TBD

Background

In addition to the image save control, GDJ should have another control that allows the user to change the orientation (horizontal, vertical).

Acceptance Criteria

• A new control button is added that toggles the orientation and redraws the diagram
• [Optional] The orientation control should be individually enable-able
  • ...and so should the image download button
  • ...and all controls should be bulk-enable-able ❌
    • Come back to this one later in #7

Approach

• TBD

Notes

TBD

Background

To ensure code quality and standards, linting should be performed on the codebase.

Acceptance Criteria

• Upon creating a PR, linting should be performed against the codebase for the following languages:
  • JavaScript (library) ✅
  • Markdown (library) ✅
  • HTML (examples) ✅
  • CSS (examples) ✅
• If linting fails, then the PR cannot be merged ✅

Approach

• Use GitHub Actions

Notes

References

• https://binary-studio.com/blog/2021/12/21/lint-your-project-with-github-actions/
• https://dev.to/juniordevforlife/how-i-automatically-lint-and-test-my-vue-project-on-push-in-github-4nnh
• https://www.freecodecamp.org/news/github-super-linter/

Background

Left-handed players would like a mirrored diagram, so this should be an option when creating diagrams. It would also be great if there was an option to flip all the diagrams on a page or per diagram.

Acceptance Criteria

• Creators can specify that the diagram should be mirrored for vertical or horizontal diagrams
• If global diagram controls become a feature (#7), then global mirroring should be an option for left-handed players to flip all the diagrams on a page

Approach

• TBD

Notes

TBD

Background

Scaling is done via the this.#scale() function, but when and where to do this is complicated. Because of (apparent) limitations with canvas, the entire canvas cannot be scaled without redrawing, but redrawing requires scaling everything.

Questions

• Should scaling be done each time a variable is referenced and assigned?
• Should scaling be done when a variable is used?
• Is there a better approach to scaling the entire diagram?

Acceptance Criteria

• Users can effectively scale the entire diagram by specifying one scaling factor config variable ✅

Approach

• Check for missed or double scaling
• See #7 as well

Background

Some chords implement barre shapes where a single finger spans multiple strings, such as a root 6 major chord:

Acceptance Criteria

• A special type of marker can be added that specifies a fret and strings and renders as a barred shape across multiple strings on a single fret

Approach

• TBD

Notes

TBD

Background

When viewing the examples page on a mobile device, it's apparent that the 50/50 columns are not working for that narrow display. See the example screenshot below:

Steps to Reproduce

View https://demo.kcarlile.com/guitar-diagrams-js/ on a phone's browser or in a browser with the width set to a mobile size.

Acceptance Criteria

• The examples page is readable with responsive columns on mobile browsers without breaking the experience for fullsize browsers

Approach

• Using Bootstrap's classes, try changing <div class="col-6">...</div><div class="col-6">...</div> to something like <div class="col-md-6">...</div><div class="col-md-6">...</div>

Notes

• See Bootstrap's columns and breakpoint docs

Background

The drawing will disappear from the canvas if a tab is left without focus for too long. This could be related to Chrome dumping memory for that tab, but the rest of the page remains fine, so it's not like what I've seen with YouTube pages sitting for too long when Chrome dumps the memory for them. In that case, the entire page refreshes upon re-focus.

Acceptance Criteria

• The cause of the disappearing drawing is determined
• A workaround, fix, or documentation solution is determined and implemented

Approach

• TBD

Notes

TBD

Background

The README.md file for the project should include a section with links to sites that are using Guitar Diagrams JS and a mechanism for site builders to submit their own site for inclusion.

Acceptance Criteria

• README.md has a section for linked sites as examples of using GDJ
• The section also includes instructions for how to submit one's site for inclusion in this list

Approach

• TBD

Notes

TBD

Background

Guitar Diagram JS should be productized and ready for use by the community. This includes packaging, documentation, properly commented code, etc.

Issues in this pseudo-epic

• #3
• #12
• #11
• #10
• #9

Acceptance Criteria

• A license is specified ✅
  • GNU General Public License v3.0 added: https://github.com/KCarlile/guitar-diagrams-js/blob/main/LICENSE
• Contribution instructions are provided ✅
  • docs/CONTRIBUTING.md
• Branch protection is configured ✅
• Anything else needed for configuration is complete in the GitHub repo ✅
  • docs/CODE_OF_CONDUCT.md

Approach

• TBD

Notes

TBD

Background

For open position chords or open position scales, users may need to denote the option for an open string (0) or muted string (X), so the platform should support those use cases. Examples:

Am chord

X0   0
------
    1
------
  22
------

C major scale

X 000X
------
    1
------
  22
------
 33
------

Acceptance Criteria

• 0-fret markers are working ✅
• 0-fret markers can be 0 for open or X for muted ✅
  • Alternately, any character can be added to the marker just like any other fret in case someone wants to use scale tones instead of fret numbers ⚠️
  • Going with this option as it makes more sense for flexibility

Approach

• TBD

Notes

TBD

Background

End-users may wish to have some control over the display of the diagrams, such as flipping all on a page to left-handed diagrams (see #5). This should be exposed via an optional page configuration block with buttons.

Acceptance Criteria

• A mechanism to enable global (page-level) configuration options exists
• ...with configurations for which options are available
• ...that could include:
  • Scaling (#4)
  • Mirroring (#5)
  • Colors/contrast ❓
  • Others ❓

Approach

• Consider how the canvas is rendered via JS function and use that for specifying there the global controls should be assigned
• Does this require a higher-level or global diagram object to store all the diagrams on a page? That is, instead of this:

  let gdj1 = new GuitarDiagramsJS();
  let gdj2 = new GuitarDiagramsJS();

  ...should it be more like this?

  let gdj = new GuitarDiagramsJS();
  let gdj1 = gdj.newDiagram();
  let gdj2 = gdj.newDiagram();

  • Better idea: make a GuitarDiargramsCollection object and add gdj objects to it, then have that object render the controls. This avoids the extra layer of overhead when users don't want the global options.

Notes

TBD

Background

Create a new documentation file for code owners to outline operational information, such as GitHubActions, deployment processes, hosting, etc.

Acceptance Criteria

• A new MD file exists for documenting code owner information and tasks and exists at docs/code-owner-docs.md
• GitHub Actions are documented
  • Name, purpose, when they run, config, etc.
• Release process is documented
• Demo hosting and deployment process is documented

Approach

• TBD

Notes

See #40 where most of this was already handled.

Background

It's easy enough to right-click on a canvas and download the image, but it would be great if users could optionally specify a button to initiate the image download.

Acceptance Criteria

• A configurable mechanism exists to render a button to download the image ✅

Approach

• TBD

Notes

TBD

Background

Guitar Diagram JS should be productized and ready for use by the community. This includes packaging, documentation, properly commented code, etc.

Issues in this pseudo-epic

• #3
• #12
• #11
• #10
• #9

Acceptance Criteria

• Comments are cleaned up ✅
• Any missing comments are added ✅

Approach

• TBD

Notes

TBD

Background

Guitar Diagram JS should be productized and ready for use by the community. This includes packaging, documentation, properly commented code, etc.

Issues in this pseudo-epic

• #3
• #12
• #11
• #10
• #9

Acceptance Criteria

• Demos are included ✅
  • Demos are hosted ✅
    • Consider implementing #14 as part of this to automate it ✅

Approach

• TBD

Notes

TBD

Background

It seems that the last fret is getting cutoff when string names are enabled. On the examples page, the blank fretboard (example 1) renders correctly, but any other diagrams with string names enabled appears to have the last fret cutoff.

Acceptance Criteria

• All frets appear (including the last one) even when string names are enabled (and all other variations of config) ✅

Approach

• Check to make sure the last fret is being drawn properly
• Check to make sure that the calculated fretboard height is correct when string names are enabled

Notes

TBD

Background

Toggling the orientation button results in the string names reversing under some circumstances. Toggle back and forth to see this bug appear. This happens on the examples page and the testing page.

Acceptance Criteria

• Togging the orientation doesn't alter the string name ordering

Approach

• TBD

Notes

This is related to #36

Background

NPM package building and publishing isn't working correctly, so it should be removed for now as fixing it is proving more difficult than it's worth at this point.

.github/workflows/release-package.yml seems to be working, but following the instructions on published packages page results in errors that the package cannot be found.

There may be remnants of Node left even after this ticket is completed as there are two aspects of Node/NPM: package building and package distribution. Distribution is what is broken, so package building Node code may be left behind.

Acceptance Criteria

• NPM functionality is disabled
  • Node package building functionality may be left in place (i.e., there may be reason to leave package.json and other NPM-related files in place for building and code aggregation/minification reasons)
• NPM references in documentation and examples have been removed
• Any other references to Node/NPM are removed from user-facing content
• NPM packages are deleted from GitHub
• A follow-up ticket exists to re-add this functionality (working) at a later date
  • #65 created

Approach

• Disable .github/workflows/release-package.yml and add a comment that it has been disabled
  • ...but don't remove it as it may be used later
• Update documentation and examples to remove references to Node packages
• Check for other references
• Clean up anything else related to Node/NPM

Notes

• Workflow disabled in GitHub UI
• stash-64-npm branch created to save NPM files for later
• Files changed:
  • ...

Background

Guitar Diagram JS should be productized and ready for use by the community. This includes packaging, documentation, properly commented code, etc.

Issues in this pseudo-epic

• #3
• #12
• #11
• #10
• #9

Acceptance Criteria

• The library is properly packaged for distribution ✅

Approach

• TBD

Notes

TBD

Background

Users may want to add a chord name or scale name as a label to a diagram, so the app should allow for that with configurable settings.

Acceptance Criteria

• Users can enable a feature to add diagram label/title text
• Configurable options should include:
  • Text
    • Static members may be needed for special characters
    • Some regex-type language may be needed for complicated chord names
  • Font
  • Font size
  • Font color
  • Alignment
    • Left, center, right

Approach

• TBD

Notes

TBD

Background

As Chad saw when trying to run the examples page after checking it out on Windows, symlinks are causing a problem in Windows.

Acceptance Criteria

• Determine how to resolve the symlink issue on Windows
• Implement the fix

Approach

• TBD

Notes

TBD

Background

The GuitarDiagramsJS class has a public method called addCanvas(paramParentElementID) that is used for adding the new HTML5 canvas element to a parent element for drawing the diagram. The name of this method is not clear in terms of what it does or how it should be used.

Acceptance Criteria

• GuitarDiagramsJS.addCanvas(paramParentElementID) is renamed to something that more clearly states the purpose
• Any documentation is updated to reflect the name change

Approach

• TBD

Notes

TBD

Background

Guitar Diagram JS should be productized and ready for use by the community. This includes packaging, documentation, properly commented code, etc.

Issues in this pseudo-epic

• #3
• #12
• #11
• #10
• #9

Acceptance Criteria

• API documentation is available on docs/api-docs.md

• API docs are available for all public functions/methods and members

• Coverage should include (this can be the outline format):

  • guitar-diagrams.js
    • public members
    • public methods/functions
  • guitar-diagrams-config.js
    • public members
    • public methods/functions
  • guitar-diagrams-marker.js
    • public members
    • public methods/functions

• Each section should be listed alphabetically and grouped by type (method, config value)

• Fields for each type should include:

  Field name	Description	Contents	Notes	Presence
  Name	Name of the constructor, member, property, or method	Text		✅Constructor ✅Member ✅Property ✅Method
  Description	Name of the constructor, member, property, or method	Text		✅Constructor ✅Member ✅Property ✅Method
  Parameters	Type and description of the parameter(s).	Text	None if empty	✅Constructor ✅Member ✅Property (set only) ✅Method
  Return Value	Type and description of the return value.	Text	None if empty	❌Constructor ❓Member ✅Property (get only) ❓Method
  Example	Code sample of how to use this API item.	Code		❓Constructor (not for default) ✅Member ✅Property ✅Method
  Notes	Any additional commentary about the API item.	Text	Optional field to be added as needed.	❓Constructor ❓Member ❓Property ❓Method

  Key: ✅Yes, required. ❓Optional. ❌ No, not necessary.

• Remaining documentation has been reviewed and approved (or edited and approved)

  • README.md - general project introduction
  • docs/examples/index.md - documentation home page
  • docs/examples/index.html - Examples HTML page
  • docs/examples/code-owner-docs.md - code owner documentation page

Formatting Template

The formatting template exists between the next two HRs.

class-name.js Class

class-name.js Constructors

Constructor(s) in class-name.js go here...

class-name.js Public Properties

Properties in class-name.js go here...

propertyName (get)

Property definition....

• Parameters: None
• Return Value: {type} Description of return value.
• Default Value: {type} 'value'

Example:

console.log('Canvas ID: ' + gdj1.config.canvasID);

propertyName (set)

Property definition....

• Parameters: {type} Description.
• Return Value: None
• Default Value: {type} value

Example:

some.code = 'example';

class-name.js Public Methods

methodName

Description of method....

• Parameters: {type} Description of parameter.
• Return Value: {type} Description of return value. (Or None)

Example:

gdj5.someMethod('someValue);

Approach

• Determine the best format for API docs: table or headings (see examples below), or propose a better implementation
• Add API documentation for each JS file's public members and methods to the file docs/api-docs.md (formerly docs/index.md)

Notes

Notes for Chad

For each JS file, document the following:

• Public members: variables that do not start with #
• Public properties: get/set-type methods
• Public methods: functions that do not start with #

You can ignore:

• Private members (starts with #)
• Private methods (starts with #)
• Constructors (except for the default constructor in guitar-diagrams.js)

Be sure to reference default values for any properties by looking at the matching private member (e.g., get someValue() or set someValue(paramSomeValue) would have a private member named #someValue with a default value.

Background

The demo site should be automatically pushed to demo.kcarlile.com when a new release is cut.

Acceptance Criteria

• When a tag is applied to main (when a release is cut), the docs/examples/ directory should be pushed to demo.kcarlile.com/guitar-diagrams-js/ via GitHub Actions ✅

Approach

• Create symlinks for local references
• Create GitHub Action to copy the files to demo.kcarlile.com/guitar-diagrams-js/
  • Add step to overwrite the symlinks with actual files

Notes

Consider pushing to FlashChord.com as well. (Maybe later.)

Background

Node/NPM infrastructure was removed in #64, but it is something we want, so this ticket is to reinstate that code and get it working. The stash-64-npm branch has the last committed state of those files and #64 has the files removed/affected by this.

There may be remnants of Node left even after #64 is completed as there are two aspects of Node/NPM: package building and package distribution. Distribution is what was broken.

Acceptance Criteria

• Node/NPM package building works
• NPM distribution works

Approach

• Reinstate the code removed in #64 from the stash-64-npm branch
• Figure out how to make NPM distribution work successfully, either through GitHub or npmjs.com

Notes

• TBD

Background

Some configuration options remain hard-coded, but they should all be configurable by the user.

Acceptance Criteria

• All options that should configurable are identified and made configurable via this.#config.* ❌

Approach

• TBD

Notes

TBD