chord-component

v0.1.2

Published

23 days ago

Lit-based web components for displaying musical chord diagrams and chord lists

Downloads

164

0High
0Medium
0Low

parent-tobias

lit web-components music chord diagram ukulele guitar mandolin chord-chart

chord-component

Lit-based web components for displaying musical chord diagrams and chord lists across various string instruments.

Features

🎸 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

npm install chord-component

Quick Start

Import and use in 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>

Import specific components

import 'chord-component/chord-diagram';
import 'chord-component/chord-list';
import 'chord-component/chord-editor';

Import utilities and services

import {
    instruments,
    chordToNotes,
    systemDefaultChords,
    chordDataService,  // Data management service
    indexedDBService   // IndexedDB wrapper
} from 'chord-component';

Components

`<chord-diagram>`

Displays a single chord diagram with fretboard visualization.

Attributes

chord (string, required): The chord name (e.g., "C", "Am7", "F#dim")
instrument (string, optional): The instrument type (default: "Standard Ukulele")

Examples

<!-- 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>

`<chord-list>`

Displays multiple chord diagrams in a responsive grid layout.

Attributes

instrument (string, optional): The instrument type (default: "Standard Ukulele")
chords (string|array, required): JSON string or array of chord names

Examples

<!-- 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>

`<chord-editor>` ✨ NEW

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.

Attributes

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

<!-- 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>

Features

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 for complete documentation.

Creating Custom Chords

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');

Supported Instruments

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)

Supported Chord Types

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#dim, etc.
Augmented: Caug, etc.
Suspended: Csus2, Csus4, etc.
Extended: C9, C11, C13, etc.
Add chords: Cadd9, etc.

Development

Setup

git clone <repository-url>
cd chord-components
npm install

Development Server

npm run dev

This starts a development server with the demo page at http://localhost:5173/demo/

Build

npm run build

Lint

npm run lint

Customization

Custom Chord Definitions

Using the Chord Editor (Recommended)

The easiest way to create custom chords is using the interactive <chord-editor> component:

<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 for hands-on examples.

Programmatic API

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');

Modifying System Defaults

You can also extend the system defaults (not recommended for user preferences):

import { systemDefaultChords } from 'chord-component';

// Add to system defaults
systemDefaultChords["Standard Ukulele"]["Csus2"] = {
    barres: [],
    fingers: [[4, 0], [3, 2], [2, 3], [1, 0]]
};

Styling

The components use CSS custom properties for theming. You can override the default dark theme:

chord-diagram {
    --chord-bg-color: #ffffff;
    --chord-text-color: #000000;
    --chord-border-color: #cccccc;
}

API Reference

Music Utilities

The package exports several utility functions for working with music theory:

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"] }

Data Management Services

The package includes services for managing chord data:

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 for complete API documentation.

Documentation

Comprehensive guides for advanced features:

CHORD_EDITOR.md - Complete chord editor documentation
INTERACTIVE_EDITING.md - Visual and text-based editing workflows
VIEW_POSITION.md - Understanding the display window system
DATA_SERVICE.md - Data caching and API integration
POSITION_SUPPORT.md - High-position chords and neck positions

Demo

Run the demo locally:

npm run dev

Then visit:

http://localhost:5173/demo/ - Chord diagram and list examples
http://localhost:5173/demo/editor.html - Interactive chord editor

License

MIT

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

Support

For questions and support, please open an issue on the GitHub repository.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

chord-component

Features

Installation

Quick Start

Import and use in HTML

Import specific components

Import utilities and services

Components

<chord-diagram>

Attributes

Examples

<chord-list>

Attributes

Examples

<chord-editor> ✨ NEW

Attributes

Events

Examples

Features

Creating Custom Chords

Supported Instruments

Supported Chord Types

Development

Setup

Development Server

Build

Lint

Customization

Custom Chord Definitions

Using the Chord Editor (Recommended)

Programmatic API

Modifying System Defaults

Styling

API Reference

Music Utilities

Data Management Services

Documentation

Demo

License

Contributing

Support

`<chord-diagram>`

`<chord-list>`

`<chord-editor>` ✨ NEW