npm - @parent-tobias/chord-component - Versions diffs - 1.0.0 - Mend

@parent-tobias/chord-component 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (26) hide show

package/LICENSE +21 -0
package/README.md +359 -0
package/dist/chord-data-service.js +190 -0
package/dist/chord-diagram.js +181 -0
package/dist/chord-editor.js +691 -0
package/dist/chord-list.js +119 -0
package/dist/default-chords.js +322 -0
package/dist/index.js +26 -0
package/dist/indexed-db-service.js +228 -0
package/dist/music-utils.js +128 -0
package/dist/node_modules/@lit/reactive-element/css-tag.js +42 -0
package/dist/node_modules/@lit/reactive-element/decorators/base.js +9 -0
package/dist/node_modules/@lit/reactive-element/decorators/custom-element.js +13 -0
package/dist/node_modules/@lit/reactive-element/decorators/property.js +37 -0
package/dist/node_modules/@lit/reactive-element/decorators/query.js +20 -0
package/dist/node_modules/@lit/reactive-element/decorators/state.js +12 -0
package/dist/node_modules/@lit/reactive-element/reactive-element.js +251 -0
package/package.json +83 -0
package/src/chord-data-service.ts +275 -0
package/src/chord-diagram.ts +255 -0
package/src/chord-editor.ts +919 -0
package/src/chord-list.ts +145 -0
package/src/default-chords.ts +333 -0
package/src/index.ts +7 -0
package/src/indexed-db-service.ts +356 -0
package/src/music-utils.ts +216 -0

package/LICENSE ADDED Viewed

@@ -0,0 +1,21 @@
+MIT License
+Copyright (c) 2025 Tobias Padilla
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md ADDED Viewed

@@ -0,0 +1,359 @@
+# 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
+```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>
+```
+### Import specific components
+```javascript
+import 'chord-component/chord-diagram';
+import 'chord-component/chord-list';
+import 'chord-component/chord-editor';
+```
+### Import utilities and services
+```javascript
+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
+```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>
+```
+### `<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
+```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>
+```
+### `<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
+```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>
+```
+#### 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](./CHORD_EDITOR.md) for complete documentation.
+#### Creating Custom Chords
+```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');
+```
+## 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
+```bash
+git clone <repository-url>
+cd chord-components
+npm install
+```
+### Development Server
+```bash
+npm run dev
+```
+This starts a development server with the demo page at `http://localhost:5173/demo/`
+### Build
+```bash
+npm run build
+```
+### Lint
+```bash
+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:
+```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.
+#### Programmatic API
+```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');
+```
+#### Modifying System Defaults
+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]]
+};
+```
+### Styling
+The components use CSS custom properties for theming. You can override the default dark theme:
+```css
+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:
+```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"] }
+```
+### Data Management Services
+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.
+## 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
+## Demo
+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
+## 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.

package/dist/chord-data-service.js ADDED Viewed

@@ -0,0 +1,190 @@
+import { indexedDBService as t } from "./indexed-db-service.js";
+import { systemDefaultChords as c } from "./default-chords.js";
+class i {
+  constructor() {
+    this.useRemoteAPI = !1, this.apiEndpoint = "";
+  }
+  /**
+   * Configure the service to use a remote API endpoint
+   */
+  configureAPI(a) {
+    this.apiEndpoint = a, this.useRemoteAPI = !0;
+  }
+  /**
+   * Disable remote API and use local data
+   */
+  disableAPI() {
+    this.useRemoteAPI = !1;
+  }
+  /**
+   * Get chord data for a specific instrument
+   * This method implements the fallback chain: IndexedDB -> API -> Local
+   */
+  async getChordData(a) {
+    try {
+      const e = await t.getChordData(a);
+      if (e && e.chords)
+        return console.log(`[ChordDataService] Loaded ${a} from IndexedDB cache`), {
+          data: e.chords,
+          source: { type: "indexeddb", timestamp: e.timestamp }
+        };
+    } catch (e) {
+      console.warn("[ChordDataService] IndexedDB error, falling back:", e);
+    }
+    if (this.useRemoteAPI && this.apiEndpoint)
+      try {
+        const e = await this.fetchFromAPI(a);
+        if (e)
+          return console.log(`[ChordDataService] Loaded ${a} from remote API`), await this.cacheChordData(a, e), {
+            data: e,
+            source: { type: "api", timestamp: Date.now() }
+          };
+      } catch (e) {
+        console.warn("[ChordDataService] API fetch error, falling back to local:", e);
+      }
+    console.log(`[ChordDataService] Loaded ${a} from local defaults`);
+    const r = c[a] || {};
+    return await this.cacheChordData(a, r), {
+      data: r,
+      source: { type: "local", timestamp: Date.now() }
+    };
+  }
+  /**
+   * Fetch chord data from remote API
+   * This is a placeholder that can be implemented when API is ready
+   */
+  async fetchFromAPI(a) {
+    if (!this.apiEndpoint)
+      return null;
+    try {
+      const r = `${this.apiEndpoint}?instrument=${encodeURIComponent(a)}`, e = await fetch(r);
+      if (!e.ok)
+        throw new Error(`API request failed: ${e.status} ${e.statusText}`);
+      const s = await e.json();
+      return s.chords || s;
+    } catch (r) {
+      return console.error("[ChordDataService] API fetch error:", r), null;
+    }
+  }
+  /**
+   * Cache chord data in IndexedDB
+   */
+  async cacheChordData(a, r) {
+    try {
+      await t.setChordData(a, r), console.log(`[ChordDataService] Cached ${a} in IndexedDB`);
+    } catch (e) {
+      console.warn("[ChordDataService] Failed to cache in IndexedDB:", e);
+    }
+  }
+  /**
+   * Get all available instruments from local defaults
+   * In the future, this could also query the API
+   */
+  getAvailableInstruments() {
+    return Object.keys(c);
+  }
+  /**
+   * Clear all cached data from IndexedDB
+   */
+  async clearCache() {
+    await t.clearAll(), console.log("[ChordDataService] Cache cleared");
+  }
+  /**
+   * Force refresh data from source (API or local) and update cache
+   */
+  async refreshData(a) {
+    if (this.useRemoteAPI && this.apiEndpoint)
+      try {
+        const e = await this.fetchFromAPI(a);
+        if (e)
+          return await this.cacheChordData(a, e), {
+            data: e,
+            source: { type: "api", timestamp: Date.now() }
+          };
+      } catch (e) {
+        console.warn("[ChordDataService] Refresh from API failed:", e);
+      }
+    const r = c[a] || {};
+    return await this.cacheChordData(a, r), {
+      data: r,
+      source: { type: "local", timestamp: Date.now() }
+    };
+  }
+  /**
+   * Check if a specific chord exists for an instrument
+   */
+  async hasChord(a, r) {
+    const e = await this.getChordData(a);
+    return r in e.data;
+  }
+  /**
+   * Get data for a specific chord
+   * @param instrument - The instrument name
+   * @param chordName - The chord name
+   * @param preferUser - If true, returns user override if it exists; if false, returns system default only
+   */
+  async getChord(a, r, e = !0) {
+    if (e)
+      try {
+        const o = await t.getUserChord(a, r);
+        if (o)
+          return {
+            fingers: o.fingers,
+            barres: o.barres,
+            position: o.position
+          };
+      } catch (o) {
+        console.warn("[ChordDataService] Failed to get user chord:", o);
+      }
+    return (await this.getChordData(a)).data[r] || null;
+  }
+  /**
+   * Save a user-defined chord override
+   */
+  async saveUserChord(a, r, e) {
+    await t.saveUserChord(a, r, e), console.log(`[ChordDataService] Saved user chord: ${a} - ${r}`);
+  }
+  /**
+   * Delete a user-defined chord override (revert to system default)
+   */
+  async deleteUserChord(a, r) {
+    await t.deleteUserChord(a, r), console.log(`[ChordDataService] Deleted user chord: ${a} - ${r}`);
+  }
+  /**
+   * Get all user-defined chords for an instrument
+   */
+  async getUserChordsByInstrument(a) {
+    return (await t.getUserChordsByInstrument(a)).map((e) => ({
+      chordName: e.chordName,
+      data: {
+        fingers: e.fingers,
+        barres: e.barres,
+        position: e.position
+      }
+    }));
+  }
+  /**
+   * Get all user-defined chords across all instruments
+   */
+  async getAllUserChords() {
+    return (await t.getAllUserChords()).map((r) => ({
+      instrument: r.instrument,
+      chordName: r.chordName,
+      data: {
+        fingers: r.fingers,
+        barres: r.barres,
+        position: r.position
+      }
+    }));
+  }
+  /**
+   * Clear all user-defined chord overrides
+   */
+  async clearUserChords() {
+    await t.clearUserChords(), console.log("[ChordDataService] Cleared all user chords");
+  }
+}
+const l = new i();
+export {
+  l as chordDataService
+};