@ruhlab/string-instrument-components

v0.1.1

Published

10 days ago

String Instrument Components: framework-independent web components for tabs, chords, and scales.

Downloads

217

0High
0Medium
0Low

leoruhland

String Instrument Components

Framework-independent Web Components for tabs, chords, and scale fretboards.

<string-instrument-tab>
<string-instrument-chord>
<string-instrument-scale>

Built with Custom Elements + Shadow DOM + SVG.

Quick Start (CDN)

Use this exact ESM CDN entrypoint in any HTML page:

<!doctype html>
<html lang="en">
  <body>
    <string-instrument-scale
      instrument="guitar"
      root="C"
      scale="major"
      frets="12"
      ui="true"
    ></string-instrument-scale>

    <script type="module">
      import { defineStringInstrumentComponents } from "https://esm.sh/@ruhlab/string-instrument-components/dist/define.js";
      defineStringInstrumentComponents();
    </script>
  </body>
</html>

Install (Package)

bun add @ruhlab/string-instrument-components
# or
npm i @ruhlab/string-instrument-components

import { defineStringInstrumentComponents } from "@ruhlab/string-instrument-components/define";
defineStringInstrumentComponents();

Angular note: add CUSTOM_ELEMENTS_SCHEMA where needed.

Component Usage

Tab

<string-instrument-tab id="tab" instrument="guitar" ui="true"></string-instrument-tab>

<script type="module">
  const tab = document.getElementById("tab");
  tab.tab = {
    title: "Simple Riff",
    timeSignature: "4/4",
    measures: [
      {
        beats: 4,
        notes: [
          { string: 6, fret: 3, time: 0 },
          { string: 5, fret: 2, time: 1 }
        ]
      }
    ]
  };
</script>

Chord

<string-instrument-chord
  instrument="guitar"
  title="C Major"
  frets-to-show="5"
></string-instrument-chord>

Scale

<string-instrument-scale
  instrument="guitar"
  root="E"
  scale="minor-pentatonic"
  frets="12"
  notation="sharps"
></string-instrument-scale>

API Overview

`<string-instrument-tab>`

Attributes: instrument, tuning, measure-width, string-spacing, ui
Property: tab: TabDocument

`<string-instrument-chord>`

Attributes: instrument, tuning, title, diagram-width, string-spacing, fret-spacing, frets-to-show, ui
Property: chords: ChordDiagram[]

`<string-instrument-scale>`

Attributes: instrument, tuning, root, scale, frets, title, notation, fret-spacing, string-spacing, ui
Property: config: ScaleFretboardConfig

Built-In Instruments

guitar
bass
ukulele
bandolin

Custom tuning is also supported, for example: tuning="D,A,D,G,B,E".

Theming

string-instrument-tab,
string-instrument-chord,
string-instrument-scale {
  --sic-background: #f8fafc;
  --sic-surface: #ffffff;
  --sic-border: #d1d5db;
  --sic-text: #111827;
  --sic-muted-text: #6b7280;
  --sic-string-color: #9ca3af;
  --sic-fret-color: #d1d5db;
  --sic-nut-color: #6b7280;
  --sic-note-active: #111827;
  --sic-note-root: #111827;
  --sic-note-outside: #e5e7eb;
  --sic-note-outside-text: #6b7280;
}

Development

bun install
bun run typecheck
bun run build
bun test
bun run examples

Examples run at http://localhost:3000.

Exports

@ruhlab/string-instrument-components
@ruhlab/string-instrument-components/define
@ruhlab/string-instrument-components/components/string-instrument-tab
@ruhlab/string-instrument-components/components/string-instrument-chord
@ruhlab/string-instrument-components/components/string-instrument-scale

Docs

docs/README.md

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme