chord-component
Version:
Lit-based web components for displaying musical chord diagrams and chord lists
360 lines (255 loc) • 9.09 kB
Markdown
Lit-based web components for displaying musical chord diagrams and chord lists across various string instruments.
- 🎸 Support for multiple instruments (Ukulele, Guitar, Mandolin)
- 🎵 Comprehensive chord library with major, minor, 7th, and extended chords
- ✏️ **Interactive chord editor** for creating custom fingerings
- 💾 **Persistent storage** with IndexedDB for user-defined chords
- 🎯 **High-position chord support** with automatic position markers
- 📱 Responsive design with container queries
- 🎨 Dark theme optimized
- ⚡ Built with Lit for fast, efficient rendering
- 🔧 TypeScript support with full type definitions
## Installation
```bash
npm install chord-component
```
## Quick Start
### Import and use in HTML
```html
<!DOCTYPE html>
<html>
<head>
<script type="module">
import 'chord-component';
</script>
</head>
<body>
<!-- Single chord diagram -->
<chord-diagram chord="C" instrument="Standard Ukulele"></chord-diagram>
<!-- Chord list -->
<chord-list
instrument="Standard Ukulele"
chords='["C", "F", "G", "Am"]'>
</chord-list>
</body>
</html>
```
```javascript
import 'chord-component/chord-diagram';
import 'chord-component/chord-list';
import 'chord-component/chord-editor';
```
```javascript
import {
instruments,
chordToNotes,
systemDefaultChords,
chordDataService, // Data management service
indexedDBService // IndexedDB wrapper
} from 'chord-component';
```
Displays a single chord diagram with fretboard visualization.
- **`chord`** (string, required): The chord name (e.g., "C", "Am7", "F#dim")
- **`instrument`** (string, optional): The instrument type (default: "Standard Ukulele")
#### Examples
```html
<!-- Basic usage -->
<chord-diagram chord="C"></chord-diagram>
<!-- Guitar chord -->
<chord-diagram chord="Em" instrument="Standard Guitar"></chord-diagram>
<!-- Complex chord -->
<chord-diagram chord="Cmaj7" instrument="Standard Ukulele"></chord-diagram>
```
Displays multiple chord diagrams in a responsive grid layout.
- **`instrument`** (string, optional): The instrument type (default: "Standard Ukulele")
- **`chords`** (string|array, required): JSON string or array of chord names
#### Examples
```html
<!-- Array of chords -->
<chord-list
instrument="Standard Ukulele"
chords='["C", "F", "G", "Am"]'>
</chord-list>
<!-- More complex chord progression -->
<chord-list
instrument="Standard Guitar"
chords='["Cmaj7", "Dm7", "G7", "Em7", "Am7"]'>
</chord-list>
```
**Interactive editor for creating and customizing chord diagrams.**
Create custom chord fingerings with visual and text-based editing. All custom chords are automatically saved to IndexedDB and persist across sessions.
- **`chord`** (string, required): The chord name to edit
- **`instrument`** (string, optional): The instrument type (default: "Standard Ukulele")
#### Events
- **`chord-saved`**: Fired when user saves a custom chord
- **`chord-reset`**: Fired when user resets to default
#### Examples
```html
<!-- Basic editor -->
<chord-editor chord="C" instrument="Standard Ukulele"></chord-editor>
<!-- Listen for save events -->
<script type="module">
const editor = document.querySelector('chord-editor');
editor.addEventListener('chord-saved', (e) => {
console.log('Saved:', e.detail.chord, e.detail.data);
});
</script>
```
- **Visual editing**: Click on diagram to add/remove finger positions
- **Text-based editing**: Edit finger and barre positions with input fields
- **Add buttons**: Quickly add new fingers or barres
- **View position control**: Adjust display window for high-position chords
- **Auto-save to IndexedDB**: Custom chords persist across sessions
- **Reset to default**: Revert to system defaults anytime
See [CHORD_EDITOR.md](./CHORD_EDITOR.md) for complete documentation.
```javascript
import { chordDataService } from 'chord-component';
// Programmatically save a custom chord
await chordDataService.saveUserChord('Standard Ukulele', 'C', {
fingers: [[4, 0], [3, 0], [2, 0], [1, 3]],
barres: []
});
// Get all user-defined chords
const userChords = await chordDataService.getAllUserChords();
// Delete a custom chord (revert to default)
await chordDataService.deleteUserChord('Standard Ukulele', 'C');
```
- **Standard Ukulele** (G-C-E-A tuning)
- **Baritone Ukulele** (D-G-B-E tuning)
- **5ths tuned Ukulele** (C-G-D-A tuning)
- **Standard Guitar** (E-A-D-G-B-E tuning)
- **Drop-D Guitar** (D-A-D-G-B-E tuning)
- **Standard Mandolin** (G-D-A-E tuning)
- **Major**: C, D, E, F, G, A, B
- **Minor**: Cm, Dm, Em, etc.
- **Dominant 7th**: C7, D7, G7, etc.
- **Major 7th**: Cmaj7, Fmaj7, etc.
- **Minor 7th**: Cm7, Am7, etc.
- **Diminished**: Cdim, F
- **Augmented**: Caug, etc.
- **Suspended**: Csus2, Csus4, etc.
- **Extended**: C9, C11, C13, etc.
- **Add chords**: Cadd9, etc.
```bash
git clone <repository-url>
cd chord-components
npm install
```
```bash
npm run dev
```
This starts a development server with the demo page at `http://localhost:5173/demo/`
```bash
npm run build
```
```bash
npm run lint
```
The easiest way to create custom chords is using the interactive `<chord-editor>` component:
```html
<chord-editor chord="Csus2" instrument="Standard Ukulele"></chord-editor>
```
Custom chords are automatically saved to IndexedDB and will be used by all `<chord-diagram>` components.
See the [interactive demo](./demo/editor.html) for hands-on examples.
```javascript
import { chordDataService } from 'chord-component';
// Save a custom chord
await chordDataService.saveUserChord('Standard Ukulele', 'Csus2', {
barres: [],
fingers: [[4, 0], [3, 2], [2, 3], [1, 0]]
});
// Get chord data (user override if exists, otherwise system default)
const chord = await chordDataService.getChord('Standard Ukulele', 'C');
```
You can also extend the system defaults (not recommended for user preferences):
```javascript
import { systemDefaultChords } from 'chord-component';
// Add to system defaults
systemDefaultChords["Standard Ukulele"]["Csus2"] = {
barres: [],
fingers: [[4, 0], [3, 2], [2, 3], [1, 0]]
};
```
The components use CSS custom properties for theming. You can override the default dark theme:
```css
chord-diagram {
--chord-bg-color:
--chord-text-color:
--chord-border-color:
}
```
The package exports several utility functions for working with music theory:
```javascript
import {
instruments, // Array of supported instruments
chordToNotes, // Convert chord name to note array
parseChords, // Parse chords from ChordPro notation
scaleTones, // Get notes in a scale
findBase // Find note index in chromatic scale
} from 'chord-component';
// Example usage
const chordData = chordToNotes("Cmaj7");
console.log(chordData); // { name: "Cmaj7", notes: ["C", "E", "G", "B"] }
```
The package includes services for managing chord data:
```javascript
import { chordDataService, indexedDBService } from 'chord-component';
// Chord Data Service
await chordDataService.getChordData('Standard Ukulele');
await chordDataService.saveUserChord(instrument, chord, data);
await chordDataService.getAllUserChords();
await chordDataService.clearCache();
// IndexedDB Service (low-level)
await indexedDBService.saveUserChord(instrument, chord, data);
await indexedDBService.getUserChord(instrument, chord);
```
See [DATA_SERVICE.md](./DATA_SERVICE.md) for complete API documentation.
Comprehensive guides for advanced features:
- **[CHORD_EDITOR.md](./CHORD_EDITOR.md)** - Complete chord editor documentation
- **[INTERACTIVE_EDITING.md](./INTERACTIVE_EDITING.md)** - Visual and text-based editing workflows
- **[VIEW_POSITION.md](./VIEW_POSITION.md)** - Understanding the display window system
- **[DATA_SERVICE.md](./DATA_SERVICE.md)** - Data caching and API integration
- **[POSITION_SUPPORT.md](./POSITION_SUPPORT.md)** - High-position chords and neck positions
Run the demo locally:
```bash
npm run dev
```
Then visit:
- `http://localhost:5173/demo/` - Chord diagram and list examples
- `http://localhost:5173/demo/editor.html` - Interactive chord editor
MIT
Contributions are welcome! Please feel free to submit issues and pull requests.
For questions and support, please open an issue on the GitHub repository.