{"id":32746763,"url":"https://github.com/parent-tobias/chord-component","last_synced_at":"2026-05-12T23:36:46.965Z","repository":{"id":319497776,"uuid":"1074297289","full_name":"parent-tobias/chord-component","owner":"parent-tobias","description":"A lit-based custom web component for displaying SVG chords via a simple interface","archived":false,"fork":false,"pushed_at":"2026-02-07T19:08:59.000Z","size":19206,"stargazers_count":2,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-26T21:09:27.923Z","etag":null,"topics":["guitar-chords","music-theory","ukulele-chords","web-components"],"latest_commit_sha":null,"homepage":"https://parent-tobias.github.io/chord-component/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/parent-tobias.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-11T14:22:45.000Z","updated_at":"2026-02-23T23:30:33.000Z","dependencies_parsed_at":"2025-10-19T09:12:42.299Z","dependency_job_id":"f6667dd4-829f-480e-96d7-e3d1cdb7834d","html_url":"https://github.com/parent-tobias/chord-component","commit_stats":null,"previous_names":["parent-tobias/chord-component"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/parent-tobias/chord-component","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/parent-tobias%2Fchord-component","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/parent-tobias%2Fchord-component/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/parent-tobias%2Fchord-component/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/parent-tobias%2Fchord-component/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/parent-tobias","download_url":"https://codeload.github.com/parent-tobias/chord-component/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/parent-tobias%2Fchord-component/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32961785,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-12T23:30:32.555Z","status":"ssl_error","status_checked_at":"2026-05-12T23:30:18.191Z","response_time":102,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["guitar-chords","music-theory","ukulele-chords","web-components"],"created_at":"2025-11-03T19:00:39.099Z","updated_at":"2026-05-12T23:36:46.952Z","avatar_url":"https://github.com/parent-tobias.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# chord-component\n\nLit-based web components for displaying musical chord diagrams and chord lists across various string instruments.\n\n## Features\n\n- Support for multiple instruments (Ukulele, Guitar, Mandolin) plus custom instrument registration\n- Comprehensive chord library with major, minor, 7th, and extended chords\n- Interactive chord editor for creating custom fingerings\n- Persistent storage with IndexedDB for user-defined chords\n- High-position chord support with automatic position markers\n- JS-only properties for passing chord data directly (no JSON-in-attributes)\n- Responsive design with container queries\n- Dark theme optimized\n- Built with Lit for fast, efficient rendering\n- TypeScript support with full type definitions\n\n## Installation\n\n```bash\nnpm install @parent-tobias/chord-component\n```\n\n## Quick Start\n\n### Import and use in HTML\n\n```html\n\u003c!DOCTYPE html\u003e\n\u003chtml\u003e\n\u003chead\u003e\n    \u003cscript type=\"module\"\u003e\n        import '@parent-tobias/chord-component';\n    \u003c/script\u003e\n\u003c/head\u003e\n\u003cbody\u003e\n    \u003c!-- Single chord diagram --\u003e\n    \u003cchord-diagram chord=\"C\" instrument=\"ukulele\"\u003e\u003c/chord-diagram\u003e\n\n    \u003c!-- Chord list --\u003e\n    \u003cchord-list\n        instrument=\"ukulele\"\n        chords='[\"C\", \"F\", \"G\", \"Am\"]'\u003e\n    \u003c/chord-list\u003e\n\u003c/body\u003e\n\u003c/html\u003e\n```\n\n### Import specific components\n\n```javascript\nimport '@parent-tobias/chord-component/chord-diagram';\nimport '@parent-tobias/chord-component/chord-list';\nimport '@parent-tobias/chord-component/chord-editor';\n```\n\n### Import utilities and services\n\n```javascript\nimport {\n    instruments,\n    getInstrument,       // Look up instrument by ID\n    registerInstrument,  // Register custom instruments\n    chordToNotes,\n    systemDefaultChords,\n    chordDataService,\n    indexedDBService\n} from '@parent-tobias/chord-component';\n```\n\n## Components\n\n### `\u003cchord-diagram\u003e`\n\nDisplays a single chord diagram with fretboard visualization.\n\n#### Attributes\n\n- **`chord`** (string): The chord name (e.g., \"C\", \"Am7\", \"F#dim\")\n- **`instrument`** (string): Instrument ID (default: `\"ukulele\"`)\n\n#### JS Properties\n\n- **`chordFingers`** (Finger[]): Set via JS to provide finger data directly, bypassing chord name lookup.\n- **`chordBarres`** (Barre[]): Set via JS to provide barre data directly, bypassing chord name lookup.\n\nThese properties are not available as HTML attributes \u0026mdash; they are set via JavaScript only, avoiding the JSON-in-attributes anti-pattern.\n\n#### Examples\n\n```html\n\u003c!-- Basic usage --\u003e\n\u003cchord-diagram chord=\"C\"\u003e\u003c/chord-diagram\u003e\n\n\u003c!-- Guitar chord --\u003e\n\u003cchord-diagram chord=\"Em\" instrument=\"guitar\"\u003e\u003c/chord-diagram\u003e\n\n\u003c!-- Complex chord --\u003e\n\u003cchord-diagram chord=\"Cmaj7\" instrument=\"ukulele\"\u003e\u003c/chord-diagram\u003e\n```\n\n```javascript\n// Direct data via JS properties (e.g., displaying a chord variation)\nconst el = document.querySelector('chord-diagram');\nel.chordFingers = [[1, 2], [2, 1]];\nel.chordBarres = [];\n```\n\n### `\u003cchord-list\u003e`\n\nDisplays multiple chord diagrams in a responsive grid layout.\n\n#### Attributes\n\n- **`instrument`** (string): Instrument ID (default: `\"ukulele\"`)\n- **`chords`** (string|array): JSON string or array of chord names\n\n#### Examples\n\n```html\n\u003cchord-list\n    instrument=\"ukulele\"\n    chords='[\"C\", \"F\", \"G\", \"Am\"]'\u003e\n\u003c/chord-list\u003e\n\n\u003cchord-list\n    instrument=\"guitar\"\n    chords='[\"Cmaj7\", \"Dm7\", \"G7\", \"Em7\", \"Am7\"]'\u003e\n\u003c/chord-list\u003e\n```\n\n### `\u003cchord-editor\u003e`\n\nInteractive editor for creating and customizing chord diagrams. Custom chords are automatically saved to IndexedDB and persist across sessions.\n\n#### Attributes\n\n- **`chord`** (string): The chord name to edit\n- **`instrument`** (string): Instrument ID (default: `\"ukulele\"`)\n\n#### Events\n\n- **`chord-changed`**: Fired on every edit (finger/barre add, remove, or update). Detail: `{ fingers, barres }`\n- **`chord-saved`**: Fired when user saves a custom chord. Detail: `{ instrument, chord, data }`\n- **`chord-reset`**: Fired when user resets to default. Detail: `{ instrument, chord }`\n\n#### Examples\n\n```html\n\u003cchord-editor chord=\"C\" instrument=\"ukulele\"\u003e\u003c/chord-editor\u003e\n\n\u003cscript type=\"module\"\u003e\n    const editor = document.querySelector('chord-editor');\n\n    // Live preview on every edit\n    editor.addEventListener('chord-changed', (e) =\u003e {\n        console.log('Editing:', e.detail.fingers, e.detail.barres);\n    });\n\n    editor.addEventListener('chord-saved', (e) =\u003e {\n        console.log('Saved:', e.detail.chord, e.detail.data);\n    });\n\u003c/script\u003e\n```\n\n#### Features\n\n- **Visual editing**: Click on diagram to add/remove finger positions\n- **Text-based editing**: Edit finger and barre positions with input fields\n- **Add buttons**: Quickly add new fingers or barres\n- **View position control**: Adjust display window for high-position chords\n- **Auto-save to IndexedDB**: Custom chords persist across sessions\n- **Reset to default**: Revert to system defaults anytime\n\nSee [CHORD_EDITOR.md](./CHORD_EDITOR.md) for complete documentation.\n\n## Built-in Instrument IDs\n\n| ID | Name | Tuning |\n|----|------|--------|\n| `ukulele` | Standard Ukulele | G-C-E-A |\n| `baritone-ukulele` | Baritone Ukulele | D-G-B-E |\n| `ukulele-5ths` | 5ths tuned Ukulele | C-G-D-A |\n| `guitar` | Standard Guitar | E-A-D-G-B-E |\n| `guitar-drop-d` | Drop-D Guitar | D-A-D-G-B-E |\n| `mandolin` | Standard Mandolin | G-D-A-E |\n\n### Custom Instruments\n\nRegister custom instruments at runtime with `registerInstrument`:\n\n```javascript\nimport { registerInstrument } from '@parent-tobias/chord-component';\n\nregisterInstrument('dulcimer', {\n    name: 'Mountain Dulcimer',\n    strings: ['D', 'A', 'D'],\n    frets: 13\n});\n```\n\nThen use the ID in any component:\n\n```html\n\u003cchord-diagram chord=\"Gm7\" instrument=\"dulcimer\"\u003e\u003c/chord-diagram\u003e\n```\n\n## Supported Chord Types\n\n- **Major**: C, D, E, F, G, A, B\n- **Minor**: Cm, Dm, Em, etc.\n- **Dominant 7th**: C7, D7, G7, etc.\n- **Major 7th**: Cmaj7, Fmaj7, etc.\n- **Minor 7th**: Cm7, Am7, etc.\n- **Diminished**: Cdim, F#dim, etc.\n- **Augmented**: Caug, etc.\n- **Suspended**: Csus2, Csus4, etc.\n- **Extended**: C9, C11, C13, etc.\n- **Add chords**: Cadd9, etc.\n\n## Customization\n\n### Using the Chord Editor (Recommended)\n\n```html\n\u003cchord-editor chord=\"Csus2\" instrument=\"ukulele\"\u003e\u003c/chord-editor\u003e\n```\n\nCustom chords are automatically saved to IndexedDB and will be used by all `\u003cchord-diagram\u003e` components.\n\n### Programmatic API\n\n```javascript\nimport { chordDataService } from '@parent-tobias/chord-component';\n\n// Save a custom chord\nawait chordDataService.saveUserChord('ukulele', 'Csus2', {\n    barres: [],\n    fingers: [[4, 0], [3, 2], [2, 3], [1, 0]]\n});\n\n// Get chord data (user override if exists, otherwise system default)\nconst chord = await chordDataService.getChord('ukulele', 'C');\n\n// Get all user-defined chords\nconst userChords = await chordDataService.getAllUserChords();\n\n// Delete a custom chord (revert to default)\nawait chordDataService.deleteUserChord('ukulele', 'C');\n```\n\n### Styling\n\nThe components use Shadow DOM. You can style the host element:\n\n```css\nchord-diagram {\n    --chord-bg-color: #ffffff;\n    --chord-text-color: #000000;\n    --chord-border-color: #cccccc;\n}\n```\n\n## API Reference\n\n### Music Utilities\n\n```javascript\nimport {\n    instruments,        // Array of all registered instruments\n    getInstrument,     // Look up instrument by ID\n    registerInstrument,// Register a custom instrument\n    chordToNotes,      // Convert chord name to note array\n    parseChords,       // Parse chords from ChordPro notation\n    scaleTones,        // Get notes in a scale\n    findBase           // Find note index in chromatic scale\n} from '@parent-tobias/chord-component';\n\nconst chordData = chordToNotes(\"Cmaj7\");\n// { name: \"Cmaj7\", notes: [\"C\", \"E\", \"G\", \"B\"] }\n\nconst uke = getInstrument(\"ukulele\");\n// { id: \"ukulele\", name: \"Standard Ukulele\", strings: [\"G\",\"C\",\"E\",\"A\"], frets: 19 }\n```\n\n### Data Management Services\n\n```javascript\nimport { chordDataService, indexedDBService } from '@parent-tobias/chord-component';\n\n// Chord Data Service\nawait chordDataService.getChordData('ukulele');\nawait chordDataService.saveUserChord('ukulele', 'C', data);\nawait chordDataService.getAllUserChords();\nawait chordDataService.clearCache();\n\n// IndexedDB Service (low-level)\nawait indexedDBService.saveUserChord('ukulele', 'C', data);\nawait indexedDBService.getUserChord('ukulele', 'C');\n```\n\nSee [DATA_SERVICE.md](./DATA_SERVICE.md) for complete API documentation.\n\n## Upgrading from v1.x to v2.0\n\nv2.0 is a **breaking change**. The main changes:\n\n### 1. Instrument attributes use short IDs instead of display names\n\n```html\n\u003c!-- v1.x --\u003e\n\u003cchord-diagram chord=\"C\" instrument=\"Standard Ukulele\"\u003e\u003c/chord-diagram\u003e\n\n\u003c!-- v2.0 --\u003e\n\u003cchord-diagram chord=\"C\" instrument=\"ukulele\"\u003e\u003c/chord-diagram\u003e\n```\n\n**ID mapping:**\n\n| v1.x (display name) | v2.0 (ID) |\n|---|---|\n| `Standard Ukulele` | `ukulele` |\n| `Baritone Ukulele` | `baritone-ukulele` |\n| `5ths tuned Ukulele` | `ukulele-5ths` |\n| `Standard Guitar` | `guitar` |\n| `Drop-D Guitar` | `guitar-drop-d` |\n| `Standard Mandolin` | `mandolin` |\n\n### 2. Service calls use IDs\n\n```javascript\n// v1.x\nawait chordDataService.saveUserChord('Standard Ukulele', 'C', data);\n\n// v2.0\nawait chordDataService.saveUserChord('ukulele', 'C', data);\n```\n\n### 3. IndexedDB data is not migrated\n\nUser-saved chords from v1.x were stored under display-name keys and will not be found by v2.0. Users will need to re-enter any custom chord fingerings.\n\n### 4. New features (non-breaking)\n\n- **`registerInstrument(id, config)`** \u0026mdash; register custom instruments at runtime\n- **`getInstrument(id)`** \u0026mdash; look up instrument by ID\n- **`chord-changed` event** on `\u003cchord-editor\u003e` \u0026mdash; fires on every edit\n- **`chordFingers` / `chordBarres` JS properties** on `\u003cchord-diagram\u003e` \u0026mdash; pass chord data directly without JSON attributes\n\n## Development\n\n### Setup\n\n```bash\ngit clone https://github.com/parent-tobias/chord-component.git\ncd chord-components\nnpm install\n```\n\n### Development Server\n\n```bash\nnpm run dev\n```\n\nStarts a dev server at `http://localhost:5173/demo/`\n\n### Build\n\n```bash\nnpm run build\n```\n\n## Documentation\n\n- **[CHORD_EDITOR.md](./CHORD_EDITOR.md)** - Complete chord editor documentation\n- **[INTERACTIVE_EDITING.md](./INTERACTIVE_EDITING.md)** - Visual and text-based editing workflows\n- **[VIEW_POSITION.md](./VIEW_POSITION.md)** - Understanding the display window system\n- **[DATA_SERVICE.md](./DATA_SERVICE.md)** - Data caching and API integration\n- **[POSITION_SUPPORT.md](./POSITION_SUPPORT.md)** - High-position chords and neck positions\n\n## Demo\n\n```bash\nnpm run dev\n```\n\n- `http://localhost:5173/demo/` - Chord diagram and list examples\n- `http://localhost:5173/demo/editor.html` - Interactive chord editor\n\n## License\n\nMIT\n\n## Contributing\n\nContributions are welcome! Please feel free to submit issues and pull requests.\n\n## Support\n\nFor questions and support, please open an issue on the [GitHub repository](https://github.com/parent-tobias/chord-component/issues).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fparent-tobias%2Fchord-component","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fparent-tobias%2Fchord-component","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fparent-tobias%2Fchord-component/lists"}