@notiqs/fretboard 0.1.0

package/README.md

@@ -0,0 +1,301 @@
+# @notiqs/fretboard
+
+A customizable, zero-dependency React fretboard component for guitar, bass, and string instruments. Dark-themed by default, fully styleable via CSS variables and class overrides.
+
+## Quick Start
+
+```bash
+npm install @notiqs/fretboard
+```
+
+```tsx
+import { Fretboard } from '@notiqs/fretboard'
+import '@notiqs/fretboard/styles.css'
+
+// C major scale on standard guitar (partial)
+const positions = [
+  { string: 0, fret: 0, note: 'E', isRoot: false },
+  { string: 0, fret: 1, note: 'F', isRoot: false },
+  { string: 0, fret: 3, note: 'G', isRoot: false },
+  { string: 1, fret: 0, note: 'B', isRoot: false },
+  { string: 1, fret: 1, note: 'C', isRoot: true },
+  // ...
+]
+
+<Fretboard
+  positions={positions}
+  tuning={[64, 59, 55, 50, 45, 40]}  // Standard guitar E-e (MIDI)
+  stringNames={['e', 'B', 'G', 'D', 'A', 'E']}
+  rootNote="C"
+/>
+```
+
+## Props Reference
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `positions` | `FretPosition[]` | *required* | Notes to display on the fretboard |
+| `tuning` | `number[]` | *required* | MIDI note numbers per string, top to bottom |
+| `stringNames` | `string[]` | *required* | Labels for each string |
+| `maxFrets` | `number` | `12` | Number of frets to render |
+| `startFret` | `number` | `0` | First fret to render (useful for position practice) |
+| `displayMode` | `'notes' \| 'intervals'` | `'notes'` | Show note names or interval labels |
+| `rootNote` | `string` | — | Root note for interval calculation and root highlighting |
+| `showFretNumbers` | `boolean` | `true` | Show fret number row below the fretboard |
+| `onNoteClick` | `(info: NoteClickInfo) => void` | — | Callback when a note marker is clicked |
+| `scrollToFret` | `number` | — | Auto-scroll to center this fret in the viewport |
+| `classNames` | `Partial<FretboardClassNames>` | — | Override classes for each selector |
+| `styles` | `Partial<FretboardStyles>` | — | Override inline styles for each selector |
+
+### FretPosition
+
+```ts
+interface FretPosition {
+  string: number        // String index (0 = highest pitch string)
+  fret: number          // Fret number (0 = open string)
+  note: string          // Note name, e.g. "C", "F#"
+  isRoot?: boolean      // Highlight as root note
+  category?: string     // Color category (see Categories)
+  displayOverride?: string  // Custom label (overrides note/interval)
+}
+```
+
+### NoteClickInfo
+
+```ts
+interface NoteClickInfo {
+  note: string
+  midi: number
+  stringIndex: number
+  fret: number
+  category?: string
+}
+```
+
+## Selectors
+
+Every element has a static class for easy CSS targeting. Use the `classNames` prop to append additional classes.
+
+| Selector | Static class | Description |
+|----------|-------------|-------------|
+| `root` | `.notiqs-fretboard-root` | Outermost scrollable container |
+| `stringRow` | `.notiqs-fretboard-stringRow` | One horizontal string row |
+| `stringName` | `.notiqs-fretboard-stringName` | String label (E, B, G...) |
+| `fretCell` | `.notiqs-fretboard-fretCell` | Individual fret cell |
+| `noteMarker` | `.notiqs-fretboard-noteMarker` | The note circle/pill |
+| `fretNumbers` | `.notiqs-fretboard-fretNumbers` | Fret number row container |
+| `fretNumber` | `.notiqs-fretboard-fretNumber` | Individual fret number |
+
+Fret cells also expose data attributes: `data-fret`, `data-open`, `data-has-note`.
+
+> **String wire:** The horizontal wire on each string is rendered as a CSS pseudo-element on `fretCell`. Customize it via the `--notiqs-wire-color` CSS variable rather than a `classNames` selector.
+Note markers expose: `data-category`, `data-root`.
+
+## CSS Variables
+
+Override these on `.notiqs-fretboard-root` (or any ancestor) to theme the fretboard.
+
+### Layout
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `--notiqs-cell-width` | `60px` | Width of each fret cell |
+| `--notiqs-cell-height` | `44px` | Height of each fret cell |
+| `--notiqs-cell-gap` | `2px` | Gap between cells |
+| `--notiqs-string-label-width` | `30px` | Width of string name column |
+| `--notiqs-note-size` | `34px` | Note marker width & height |
+| `--notiqs-note-radius` | `10px` | Note marker border radius |
+| `--notiqs-note-font-size` | `0.8rem` | Note marker font size |
+
+### Colors
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `--notiqs-cell-bg` | `#16162a` | Fret cell background |
+| `--notiqs-cell-bg-hover` | `#1e1e3a` | Fret cell hover background |
+| `--notiqs-cell-bg-open` | `#0d0d12` | Open string cell background |
+| `--notiqs-cell-border` | `#2a2a4a` | Fret line color |
+| `--notiqs-cell-border-open` | `#3a3a5a` | Nut (open fret) border |
+| `--notiqs-wire-color` | `linear-gradient(...)` | String wire gradient |
+| `--notiqs-text` | `#e8e8f0` | Primary text color |
+| `--notiqs-text-muted` | `#888` | Secondary text color |
+
+### Category Colors
+
+Each category has three tokens: base, dark (gradient end), and glow.
+
+| Category | Base | Dark | Glow |
+|----------|------|------|------|
+| `root` | `--notiqs-color-root` | `--notiqs-color-root-dark` | `--notiqs-color-root-glow` |
+| `third` | `--notiqs-color-third` | `--notiqs-color-third-dark` | `--notiqs-color-third-glow` |
+| `fifth` | `--notiqs-color-fifth` | `--notiqs-color-fifth-dark` | `--notiqs-color-fifth-glow` |
+| `seventh` | `--notiqs-color-seventh` | `--notiqs-color-seventh-dark` | `--notiqs-color-seventh-glow` |
+| `extension` | `--notiqs-color-extension` | `--notiqs-color-extension-dark` | `--notiqs-color-extension-glow` |
+| `other` | `--notiqs-color-other` | `--notiqs-color-other-dark` | `--notiqs-color-other-glow` |
+
+## Theming
+
+### Light Theme Override
+
+```css
+.notiqs-fretboard-root {
+  --notiqs-cell-bg: #f5f5f5;
+  --notiqs-cell-bg-hover: #e8e8e8;
+  --notiqs-cell-bg-open: #ffffff;
+  --notiqs-cell-border: #d0d0d0;
+  --notiqs-cell-border-open: #b0b0b0;
+  --notiqs-wire-color: linear-gradient(to right, #ccc 0%, #999 100%);
+  --notiqs-text: #1a1a1a;
+  --notiqs-text-muted: #666;
+}
+```
+
+### classNames Usage
+
+```tsx
+<Fretboard
+  positions={positions}
+  tuning={tuning}
+  stringNames={names}
+  classNames={{
+    root: 'my-fretboard',
+    noteMarker: 'my-note',
+    fretCell: 'my-cell',
+  }}
+/>
+```
+
+```css
+.my-fretboard { border: 1px solid #333; border-radius: 8px; padding: 12px; }
+.my-note { border-radius: 50%; }  /* circular markers */
+```
+
+### Inline Styles
+
+```tsx
+<Fretboard
+  positions={positions}
+  tuning={tuning}
+  stringNames={names}
+  styles={{
+    root: { maxHeight: 300, overflow: 'hidden' },
+    noteMarker: { borderRadius: '50%' },
+  }}
+/>
+```
+
+## Categories
+
+The built-in stylesheet provides colors for these `category` values:
+
+| Category | Color | Use case |
+|----------|-------|----------|
+| `root` | Violet | Root notes |
+| `third` | Pink | Major/minor thirds |
+| `fifth` | Teal | Perfect fifths |
+| `seventh` | Gold | Sevenths |
+| `extension` | Blue | 9ths, 11ths, 13ths |
+| `other` | Gray | 2nds, 4ths, 6ths |
+| `common` | Teal | Shared notes (scale comparison) |
+| `scaleA` | Blue | Scale A unique notes |
+| `scaleB` | Pink | Scale B unique notes |
+| `chord` | Teal | Chord tones |
+| `scale` | Blue | Non-chord scale notes |
+
+### Custom Categories
+
+Add your own categories via `data-category` CSS selectors:
+
+```css
+.notiqs-fretboard-noteMarker[data-category="myCustom"] {
+  background: linear-gradient(135deg, #ff6600 0%, #cc5200 100%);
+  box-shadow: 0 4px 12px rgba(255, 102, 0, 0.35);
+}
+```
+
+Then pass `category: 'myCustom'` in your `FretPosition` objects.
+
+## Recipes
+
+### Interval Mode
+
+```tsx
+<Fretboard
+  positions={positions}
+  tuning={[64, 59, 55, 50, 45, 40]}
+  stringNames={['e', 'B', 'G', 'D', 'A', 'E']}
+  rootNote="C"
+  displayMode="intervals"
+/>
+```
+
+Notes display as `R`, `b3`, `5`, `7`, etc. instead of note names.
+
+### Click Handling
+
+```tsx
+function MyApp() {
+  const handleClick = (info: NoteClickInfo) => {
+    console.log(`Clicked ${info.note} (MIDI ${info.midi}) on string ${info.stringIndex}, fret ${info.fret}`)
+    // Play audio, check quiz answer, etc.
+  }
+
+  return (
+    <Fretboard
+      positions={positions}
+      tuning={tuning}
+      stringNames={names}
+      onNoteClick={handleClick}
+    />
+  )
+}
+```
+
+### Bass Tuning
+
+```tsx
+// 4-string bass: G D A E
+<Fretboard positions={positions} tuning={[43, 38, 33, 28]} stringNames={['G', 'D', 'A', 'E']} rootNote="E" />
+
+// 5-string bass: G D A E B
+<Fretboard positions={positions} tuning={[43, 38, 33, 28, 23]} stringNames={['G', 'D', 'A', 'E', 'B']} rootNote="E" />
+```
+
+### Scroll to Fret / Position Practice
+
+```tsx
+<Fretboard positions={positions} tuning={tuning} stringNames={names} scrollToFret={7} />
+<Fretboard positions={positions} tuning={tuning} stringNames={names} startFret={5} maxFrets={8} />
+```
+
+### Display Override (Quiz Mode)
+
+```tsx
+const quizPositions = [
+  { string: 2, fret: 5, note: 'C', isRoot: true, displayOverride: '?', category: 'challenge' },
+]
+```
+
+## Exports
+
+```ts
+// Component
+export { Fretboard } from '@notiqs/fretboard'
+
+// Types
+export type {
+  FretboardProps,
+  FretPosition,
+  NoteClickInfo,
+  FretboardClassNames,
+  FretboardStyles,
+  FretboardSelector,
+} from '@notiqs/fretboard'
+
+// Utilities
+export { getNoteAtFret, getIntervalLabel, normalizeNote, midiToNoteName } from '@notiqs/fretboard'
+```
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,239 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  Fretboard: () => Fretboard,
+  getIntervalLabel: () => getIntervalLabel,
+  getNoteAtFret: () => getNoteAtFret,
+  midiToNoteName: () => midiToNoteName,
+  normalizeNote: () => normalizeNote
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/Fretboard.tsx
+var import_react = require("react");
+
+// src/utils.ts
+var NOTE_NAMES = ["C", "C#", "D", "D#", "E", "F", "F#", "G", "G#", "A", "A#", "B"];
+var ENHARMONIC_MAP = {
+  "Cb": "B",
+  "Db": "C#",
+  "Eb": "D#",
+  "Fb": "E",
+  "Gb": "F#",
+  "Ab": "G#",
+  "Bb": "A#",
+  "E#": "F",
+  "B#": "C",
+  "C##": "D",
+  "D##": "E",
+  "E##": "F#",
+  "F##": "G",
+  "G##": "A",
+  "A##": "B",
+  "B##": "C#",
+  "Cbb": "A#",
+  "Dbb": "C",
+  "Ebb": "D",
+  "Fbb": "D#",
+  "Gbb": "F",
+  "Abb": "G",
+  "Bbb": "A"
+};
+var INTERVAL_LABELS = ["R", "\u266D2", "2", "\u266D3", "3", "4", "\u266D5", "5", "\u266D6", "6", "\u266D7", "7"];
+function normalizeNote(note) {
+  const pitchClass = note.replace(/\d+$/, "");
+  return ENHARMONIC_MAP[pitchClass] || pitchClass;
+}
+function midiToNoteName(midi) {
+  return NOTE_NAMES[midi % 12];
+}
+function getNoteAtFret(stringMidi, fret) {
+  return midiToNoteName(stringMidi + fret);
+}
+function getIntervalLabel(note, rootNote) {
+  const noteNorm = normalizeNote(note);
+  const rootNorm = normalizeNote(rootNote);
+  const noteIndex = NOTE_NAMES.indexOf(noteNorm);
+  const rootIndex = NOTE_NAMES.indexOf(rootNorm);
+  if (noteIndex === -1 || rootIndex === -1) return note;
+  const semitones = (noteIndex - rootIndex + 12) % 12;
+  return INTERVAL_LABELS[semitones];
+}
+
+// src/Fretboard.tsx
+var import_jsx_runtime = require("react/jsx-runtime");
+var GLOW_COLORS = {
+  root: "var(--notiqs-color-root-glow)",
+  third: "var(--notiqs-color-third-glow)",
+  fifth: "var(--notiqs-color-fifth-glow)",
+  seventh: "var(--notiqs-color-seventh-glow)",
+  extension: "var(--notiqs-color-extension-glow)",
+  other: "var(--notiqs-color-other-glow)",
+  chord: "var(--notiqs-color-fifth-glow)",
+  common: "var(--notiqs-color-fifth-glow)",
+  scale: "var(--notiqs-color-extension-glow)",
+  scaleA: "var(--notiqs-color-extension-glow)",
+  scaleB: "var(--notiqs-color-third-glow)"
+};
+function getGlowColor(category, isRoot) {
+  if (isRoot) return GLOW_COLORS.root;
+  if (category && category in GLOW_COLORS) return GLOW_COLORS[category];
+  return GLOW_COLORS.root;
+}
+function cx(staticClass, consumerClass) {
+  return consumerClass ? `${staticClass} ${consumerClass}` : staticClass;
+}
+function Fretboard({
+  positions,
+  tuning,
+  stringNames,
+  maxFrets = 12,
+  startFret = 0,
+  displayMode = "notes",
+  rootNote,
+  showFretNumbers = true,
+  onNoteClick,
+  scrollToFret,
+  classNames,
+  styles
+}) {
+  const rootRef = (0, import_react.useRef)(null);
+  (0, import_react.useEffect)(() => {
+    if (scrollToFret === void 0 || !rootRef.current) return;
+    const container = rootRef.current;
+    const cell = container.querySelector(
+      `.notiqs-fretboard-fretCell[data-fret="${scrollToFret}"]`
+    );
+    if (cell) {
+      const cellCenter = cell.offsetLeft + cell.offsetWidth / 2;
+      const containerWidth = container.clientWidth;
+      requestAnimationFrame(() => {
+        container.scrollTo({
+          left: Math.max(0, cellCenter - containerWidth / 2),
+          behavior: "smooth"
+        });
+      });
+    }
+  }, [scrollToFret]);
+  const getPositionAt = (stringIndex, fret) => {
+    return positions.find((p) => p.string === stringIndex && p.fret === fret);
+  };
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(
+    "div",
+    {
+      ref: rootRef,
+      className: cx("notiqs-fretboard-root", classNames?.root),
+      style: styles?.root,
+      children: [
+        tuning.map((_, stringIndex) => /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(
+          "div",
+          {
+            className: cx("notiqs-fretboard-stringRow", classNames?.stringRow),
+            style: styles?.stringRow,
+            children: [
+              /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+                "span",
+                {
+                  className: cx("notiqs-fretboard-stringName", classNames?.stringName),
+                  style: styles?.stringName,
+                  children: stringNames[stringIndex]
+                }
+              ),
+              Array.from({ length: maxFrets - startFret + 1 }, (_2, i) => {
+                const fret = startFret + i;
+                const stringMidi = tuning[stringIndex];
+                const note = getNoteAtFret(stringMidi, fret);
+                const position = getPositionAt(stringIndex, fret);
+                const hasNote = !!position;
+                const isRoot = position?.isRoot ?? (!!rootNote && note === rootNote);
+                const midi = stringMidi + fret;
+                return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+                  "div",
+                  {
+                    "data-fret": fret,
+                    "data-open": fret === 0 || void 0,
+                    "data-has-note": hasNote || void 0,
+                    className: cx("notiqs-fretboard-fretCell", classNames?.fretCell),
+                    style: {
+                      cursor: hasNote && onNoteClick ? "pointer" : "default",
+                      ...styles?.fretCell
+                    },
+                    onClick: () => {
+                      if (hasNote && onNoteClick) {
+                        onNoteClick({ note, midi, stringIndex, fret, category: position?.category });
+                      }
+                    },
+                    children: hasNote && /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+                      "span",
+                      {
+                        "data-category": position?.category || void 0,
+                        "data-root": isRoot || void 0,
+                        className: cx("notiqs-fretboard-noteMarker", classNames?.noteMarker),
+                        style: {
+                          "--note-glow-color": getGlowColor(position?.category, isRoot),
+                          ...styles?.noteMarker
+                        },
+                        children: position?.displayOverride ?? (displayMode === "intervals" && rootNote ? getIntervalLabel(note, rootNote) : note)
+                      }
+                    )
+                  },
+                  fret
+                );
+              })
+            ]
+          },
+          stringIndex
+        )),
+        showFretNumbers && /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(
+          "div",
+          {
+            className: cx("notiqs-fretboard-fretNumbers", classNames?.fretNumbers),
+            style: styles?.fretNumbers,
+            children: [
+              /* @__PURE__ */ (0, import_jsx_runtime.jsx)("span", {}),
+              Array.from({ length: maxFrets - startFret + 1 }, (_, i) => {
+                const fret = startFret + i;
+                return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+                  "span",
+                  {
+                    className: cx("notiqs-fretboard-fretNumber", classNames?.fretNumber),
+                    style: styles?.fretNumber,
+                    children: fret
+                  },
+                  fret
+                );
+              })
+            ]
+          }
+        )
+      ]
+    }
+  );
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Fretboard,
+  getIntervalLabel,
+  getNoteAtFret,
+  midiToNoteName,
+  normalizeNote
+});

package/dist/index.d.cts

@@ -0,0 +1,44 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { CSSProperties } from 'react';
+
+interface FretPosition {
+    string: number;
+    fret: number;
+    note: string;
+    isRoot?: boolean;
+    category?: string;
+    displayOverride?: string;
+}
+interface NoteClickInfo {
+    note: string;
+    midi: number;
+    stringIndex: number;
+    fret: number;
+    category?: string;
+}
+type FretboardSelector = 'root' | 'stringRow' | 'stringName' | 'fretCell' | 'noteMarker' | 'fretNumbers' | 'fretNumber';
+type FretboardClassNames = Record<FretboardSelector, string>;
+type FretboardStyles = Record<FretboardSelector, CSSProperties>;
+interface FretboardProps {
+    positions: FretPosition[];
+    tuning: number[];
+    stringNames: string[];
+    maxFrets?: number;
+    startFret?: number;
+    displayMode?: 'notes' | 'intervals';
+    rootNote?: string;
+    showFretNumbers?: boolean;
+    onNoteClick?: (info: NoteClickInfo) => void;
+    scrollToFret?: number;
+    classNames?: Partial<FretboardClassNames>;
+    styles?: Partial<FretboardStyles>;
+}
+
+declare function Fretboard({ positions, tuning, stringNames, maxFrets, startFret, displayMode, rootNote, showFretNumbers, onNoteClick, scrollToFret, classNames, styles, }: FretboardProps): react_jsx_runtime.JSX.Element;
+
+declare function normalizeNote(note: string): string;
+declare function midiToNoteName(midi: number): string;
+declare function getNoteAtFret(stringMidi: number, fret: number): string;
+declare function getIntervalLabel(note: string, rootNote: string): string;
+
+export { type FretPosition, Fretboard, type FretboardClassNames, type FretboardProps, type FretboardSelector, type FretboardStyles, type NoteClickInfo, getIntervalLabel, getNoteAtFret, midiToNoteName, normalizeNote };

package/dist/index.d.ts

@@ -0,0 +1,44 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { CSSProperties } from 'react';
+
+interface FretPosition {
+    string: number;
+    fret: number;
+    note: string;
+    isRoot?: boolean;
+    category?: string;
+    displayOverride?: string;
+}
+interface NoteClickInfo {
+    note: string;
+    midi: number;
+    stringIndex: number;
+    fret: number;
+    category?: string;
+}
+type FretboardSelector = 'root' | 'stringRow' | 'stringName' | 'fretCell' | 'noteMarker' | 'fretNumbers' | 'fretNumber';
+type FretboardClassNames = Record<FretboardSelector, string>;
+type FretboardStyles = Record<FretboardSelector, CSSProperties>;
+interface FretboardProps {
+    positions: FretPosition[];
+    tuning: number[];
+    stringNames: string[];
+    maxFrets?: number;
+    startFret?: number;
+    displayMode?: 'notes' | 'intervals';
+    rootNote?: string;
+    showFretNumbers?: boolean;
+    onNoteClick?: (info: NoteClickInfo) => void;
+    scrollToFret?: number;
+    classNames?: Partial<FretboardClassNames>;
+    styles?: Partial<FretboardStyles>;
+}
+
+declare function Fretboard({ positions, tuning, stringNames, maxFrets, startFret, displayMode, rootNote, showFretNumbers, onNoteClick, scrollToFret, classNames, styles, }: FretboardProps): react_jsx_runtime.JSX.Element;
+
+declare function normalizeNote(note: string): string;
+declare function midiToNoteName(midi: number): string;
+declare function getNoteAtFret(stringMidi: number, fret: number): string;
+declare function getIntervalLabel(note: string, rootNote: string): string;
+
+export { type FretPosition, Fretboard, type FretboardClassNames, type FretboardProps, type FretboardSelector, type FretboardStyles, type NoteClickInfo, getIntervalLabel, getNoteAtFret, midiToNoteName, normalizeNote };

package/dist/index.js

@@ -0,0 +1,208 @@
+// src/Fretboard.tsx
+import { useRef, useEffect } from "react";
+
+// src/utils.ts
+var NOTE_NAMES = ["C", "C#", "D", "D#", "E", "F", "F#", "G", "G#", "A", "A#", "B"];
+var ENHARMONIC_MAP = {
+  "Cb": "B",
+  "Db": "C#",
+  "Eb": "D#",
+  "Fb": "E",
+  "Gb": "F#",
+  "Ab": "G#",
+  "Bb": "A#",
+  "E#": "F",
+  "B#": "C",
+  "C##": "D",
+  "D##": "E",
+  "E##": "F#",
+  "F##": "G",
+  "G##": "A",
+  "A##": "B",
+  "B##": "C#",
+  "Cbb": "A#",
+  "Dbb": "C",
+  "Ebb": "D",
+  "Fbb": "D#",
+  "Gbb": "F",
+  "Abb": "G",
+  "Bbb": "A"
+};
+var INTERVAL_LABELS = ["R", "\u266D2", "2", "\u266D3", "3", "4", "\u266D5", "5", "\u266D6", "6", "\u266D7", "7"];
+function normalizeNote(note) {
+  const pitchClass = note.replace(/\d+$/, "");
+  return ENHARMONIC_MAP[pitchClass] || pitchClass;
+}
+function midiToNoteName(midi) {
+  return NOTE_NAMES[midi % 12];
+}
+function getNoteAtFret(stringMidi, fret) {
+  return midiToNoteName(stringMidi + fret);
+}
+function getIntervalLabel(note, rootNote) {
+  const noteNorm = normalizeNote(note);
+  const rootNorm = normalizeNote(rootNote);
+  const noteIndex = NOTE_NAMES.indexOf(noteNorm);
+  const rootIndex = NOTE_NAMES.indexOf(rootNorm);
+  if (noteIndex === -1 || rootIndex === -1) return note;
+  const semitones = (noteIndex - rootIndex + 12) % 12;
+  return INTERVAL_LABELS[semitones];
+}
+
+// src/Fretboard.tsx
+import { jsx, jsxs } from "react/jsx-runtime";
+var GLOW_COLORS = {
+  root: "var(--notiqs-color-root-glow)",
+  third: "var(--notiqs-color-third-glow)",
+  fifth: "var(--notiqs-color-fifth-glow)",
+  seventh: "var(--notiqs-color-seventh-glow)",
+  extension: "var(--notiqs-color-extension-glow)",
+  other: "var(--notiqs-color-other-glow)",
+  chord: "var(--notiqs-color-fifth-glow)",
+  common: "var(--notiqs-color-fifth-glow)",
+  scale: "var(--notiqs-color-extension-glow)",
+  scaleA: "var(--notiqs-color-extension-glow)",
+  scaleB: "var(--notiqs-color-third-glow)"
+};
+function getGlowColor(category, isRoot) {
+  if (isRoot) return GLOW_COLORS.root;
+  if (category && category in GLOW_COLORS) return GLOW_COLORS[category];
+  return GLOW_COLORS.root;
+}
+function cx(staticClass, consumerClass) {
+  return consumerClass ? `${staticClass} ${consumerClass}` : staticClass;
+}
+function Fretboard({
+  positions,
+  tuning,
+  stringNames,
+  maxFrets = 12,
+  startFret = 0,
+  displayMode = "notes",
+  rootNote,
+  showFretNumbers = true,
+  onNoteClick,
+  scrollToFret,
+  classNames,
+  styles
+}) {
+  const rootRef = useRef(null);
+  useEffect(() => {
+    if (scrollToFret === void 0 || !rootRef.current) return;
+    const container = rootRef.current;
+    const cell = container.querySelector(
+      `.notiqs-fretboard-fretCell[data-fret="${scrollToFret}"]`
+    );
+    if (cell) {
+      const cellCenter = cell.offsetLeft + cell.offsetWidth / 2;
+      const containerWidth = container.clientWidth;
+      requestAnimationFrame(() => {
+        container.scrollTo({
+          left: Math.max(0, cellCenter - containerWidth / 2),
+          behavior: "smooth"
+        });
+      });
+    }
+  }, [scrollToFret]);
+  const getPositionAt = (stringIndex, fret) => {
+    return positions.find((p) => p.string === stringIndex && p.fret === fret);
+  };
+  return /* @__PURE__ */ jsxs(
+    "div",
+    {
+      ref: rootRef,
+      className: cx("notiqs-fretboard-root", classNames?.root),
+      style: styles?.root,
+      children: [
+        tuning.map((_, stringIndex) => /* @__PURE__ */ jsxs(
+          "div",
+          {
+            className: cx("notiqs-fretboard-stringRow", classNames?.stringRow),
+            style: styles?.stringRow,
+            children: [
+              /* @__PURE__ */ jsx(
+                "span",
+                {
+                  className: cx("notiqs-fretboard-stringName", classNames?.stringName),
+                  style: styles?.stringName,
+                  children: stringNames[stringIndex]
+                }
+              ),
+              Array.from({ length: maxFrets - startFret + 1 }, (_2, i) => {
+                const fret = startFret + i;
+                const stringMidi = tuning[stringIndex];
+                const note = getNoteAtFret(stringMidi, fret);
+                const position = getPositionAt(stringIndex, fret);
+                const hasNote = !!position;
+                const isRoot = position?.isRoot ?? (!!rootNote && note === rootNote);
+                const midi = stringMidi + fret;
+                return /* @__PURE__ */ jsx(
+                  "div",
+                  {
+                    "data-fret": fret,
+                    "data-open": fret === 0 || void 0,
+                    "data-has-note": hasNote || void 0,
+                    className: cx("notiqs-fretboard-fretCell", classNames?.fretCell),
+                    style: {
+                      cursor: hasNote && onNoteClick ? "pointer" : "default",
+                      ...styles?.fretCell
+                    },
+                    onClick: () => {
+                      if (hasNote && onNoteClick) {
+                        onNoteClick({ note, midi, stringIndex, fret, category: position?.category });
+                      }
+                    },
+                    children: hasNote && /* @__PURE__ */ jsx(
+                      "span",
+                      {
+                        "data-category": position?.category || void 0,
+                        "data-root": isRoot || void 0,
+                        className: cx("notiqs-fretboard-noteMarker", classNames?.noteMarker),
+                        style: {
+                          "--note-glow-color": getGlowColor(position?.category, isRoot),
+                          ...styles?.noteMarker
+                        },
+                        children: position?.displayOverride ?? (displayMode === "intervals" && rootNote ? getIntervalLabel(note, rootNote) : note)
+                      }
+                    )
+                  },
+                  fret
+                );
+              })
+            ]
+          },
+          stringIndex
+        )),
+        showFretNumbers && /* @__PURE__ */ jsxs(
+          "div",
+          {
+            className: cx("notiqs-fretboard-fretNumbers", classNames?.fretNumbers),
+            style: styles?.fretNumbers,
+            children: [
+              /* @__PURE__ */ jsx("span", {}),
+              Array.from({ length: maxFrets - startFret + 1 }, (_, i) => {
+                const fret = startFret + i;
+                return /* @__PURE__ */ jsx(
+                  "span",
+                  {
+                    className: cx("notiqs-fretboard-fretNumber", classNames?.fretNumber),
+                    style: styles?.fretNumber,
+                    children: fret
+                  },
+                  fret
+                );
+              })
+            ]
+          }
+        )
+      ]
+    }
+  );
+}
+export {
+  Fretboard,
+  getIntervalLabel,
+  getNoteAtFret,
+  midiToNoteName,
+  normalizeNote
+};

package/dist/styles.css

@@ -0,0 +1,202 @@
+/* @notiqs/fretboard — Default Stylesheet */
+
+.notiqs-fretboard-root {
+  --notiqs-cell-width: 60px;
+  --notiqs-cell-height: 44px;
+  --notiqs-cell-gap: 2px;
+  --notiqs-string-label-width: 30px;
+  --notiqs-note-size: 34px;
+  --notiqs-note-radius: 10px;
+  --notiqs-note-font-size: 0.8rem;
+
+  --notiqs-cell-bg: #16162a;
+  --notiqs-cell-bg-hover: #1e1e3a;
+  --notiqs-cell-bg-open: #0d0d12;
+  --notiqs-cell-border: #2a2a4a;
+  --notiqs-cell-border-open: #3a3a5a;
+  --notiqs-wire-color: linear-gradient(to right, #2a2a4a 0%, #3a3a5a 100%);
+  --notiqs-text: #e8e8f0;
+  --notiqs-text-muted: #888;
+
+  --notiqs-color-root: #9d6eff;
+  --notiqs-color-root-dark: #7c4ddb;
+  --notiqs-color-root-glow: rgba(157, 110, 255, 0.35);
+  --notiqs-color-third: #ff6eb4;
+  --notiqs-color-third-dark: #e8459a;
+  --notiqs-color-third-glow: rgba(255, 110, 180, 0.35);
+  --notiqs-color-fifth: #20c997;
+  --notiqs-color-fifth-dark: #2ba89a;
+  --notiqs-color-fifth-glow: rgba(32, 201, 151, 0.35);
+  --notiqs-color-seventh: #d4a030;
+  --notiqs-color-seventh-dark: #b88a28;
+  --notiqs-color-seventh-glow: rgba(212, 160, 48, 0.35);
+  --notiqs-color-extension: #5b9bd5;
+  --notiqs-color-extension-dark: #4a8fd4;
+  --notiqs-color-extension-glow: rgba(91, 155, 213, 0.35);
+  --notiqs-color-other: #3a3a5a;
+  --notiqs-color-other-dark: #2a2a4a;
+  --notiqs-color-other-glow: rgba(50, 50, 74, 0.3);
+}
+
+.notiqs-fretboard-root {
+  display: flex;
+  flex-direction: column;
+  gap: var(--notiqs-cell-gap);
+  overflow-x: auto;
+  padding-bottom: 1rem;
+}
+
+.notiqs-fretboard-stringRow {
+  display: flex;
+  align-items: center;
+  gap: var(--notiqs-cell-gap);
+}
+
+.notiqs-fretboard-stringName {
+  width: var(--notiqs-string-label-width);
+  text-align: center;
+  flex-shrink: 0;
+  font-weight: 700;
+  color: var(--notiqs-text-muted);
+  font-size: 0.875rem;
+}
+
+.notiqs-fretboard-fretCell {
+  width: var(--notiqs-cell-width);
+  height: var(--notiqs-cell-height);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  background: var(--notiqs-cell-bg);
+  border-right: 2px solid var(--notiqs-cell-border);
+  position: relative;
+  flex-shrink: 0;
+  transition: background-color 0.2s;
+}
+
+.notiqs-fretboard-fretCell:hover {
+  background: var(--notiqs-cell-bg-hover);
+}
+
+.notiqs-fretboard-fretCell[data-open="true"] {
+  background: var(--notiqs-cell-bg-open);
+  border-right: 4px solid var(--notiqs-cell-border-open);
+}
+
+/* String wire */
+.notiqs-fretboard-fretCell::after {
+  content: '';
+  position: absolute;
+  top: 50%;
+  left: 0;
+  right: 0;
+  height: 2px;
+  background: var(--notiqs-wire-color);
+  transform: translateY(-50%);
+  z-index: 0;
+  border-radius: 1px;
+}
+
+/* Note Marker — default (root color) */
+.notiqs-fretboard-noteMarker {
+  position: relative;
+  z-index: 1;
+  width: var(--notiqs-note-size);
+  height: var(--notiqs-note-size);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  background: linear-gradient(135deg, var(--notiqs-color-root) 0%, var(--notiqs-color-root-dark) 100%);
+  color: white;
+  border-radius: var(--notiqs-note-radius);
+  font-weight: 600;
+  font-size: var(--notiqs-note-font-size);
+  box-shadow: 0 4px 12px var(--notiqs-color-root-glow);
+  transition: transform 0.2s cubic-bezier(0.34, 1.56, 0.64, 1),
+              box-shadow 0.25s ease, filter 0.2s ease;
+}
+
+.notiqs-fretboard-fretCell[data-has-note="true"]:hover .notiqs-fretboard-noteMarker {
+  transform: scale(1.25) translateY(-3px);
+  filter: brightness(1.2);
+  box-shadow:
+    0 8px 24px var(--note-glow-color, var(--notiqs-color-root-glow)),
+    0 4px 8px rgba(0,0,0,0.4),
+    0 0 20px var(--note-glow-color, var(--notiqs-color-root-glow));
+}
+
+.notiqs-fretboard-fretCell[data-has-note="true"]:active .notiqs-fretboard-noteMarker {
+  transform: scale(1.15) translateY(-1px);
+}
+
+/* Category Colors */
+.notiqs-fretboard-noteMarker[data-root="true"],
+.notiqs-fretboard-noteMarker[data-category="root"] {
+  background: linear-gradient(135deg, var(--notiqs-color-root) 0%, var(--notiqs-color-root-dark) 100%);
+  box-shadow: 0 4px 12px var(--notiqs-color-root-glow);
+}
+
+.notiqs-fretboard-noteMarker[data-category="third"] {
+  background: linear-gradient(135deg, var(--notiqs-color-third) 0%, var(--notiqs-color-third-dark) 100%);
+  box-shadow: 0 4px 12px var(--notiqs-color-third-glow);
+}
+
+.notiqs-fretboard-noteMarker[data-category="fifth"],
+.notiqs-fretboard-noteMarker[data-category="chord"],
+.notiqs-fretboard-noteMarker[data-category="common"] {
+  background: linear-gradient(135deg, var(--notiqs-color-fifth) 0%, var(--notiqs-color-fifth-dark) 100%);
+  box-shadow: 0 4px 12px var(--notiqs-color-fifth-glow);
+}
+
+.notiqs-fretboard-noteMarker[data-category="seventh"] {
+  background: linear-gradient(135deg, var(--notiqs-color-seventh) 0%, var(--notiqs-color-seventh-dark) 100%);
+  box-shadow: 0 4px 12px var(--notiqs-color-seventh-glow);
+}
+
+.notiqs-fretboard-noteMarker[data-category="extension"],
+.notiqs-fretboard-noteMarker[data-category="scale"],
+.notiqs-fretboard-noteMarker[data-category="scaleA"] {
+  background: linear-gradient(135deg, var(--notiqs-color-extension) 0%, var(--notiqs-color-extension-dark) 100%);
+  box-shadow: 0 4px 12px var(--notiqs-color-extension-glow);
+}
+
+.notiqs-fretboard-noteMarker[data-category="scaleB"] {
+  background: linear-gradient(135deg, var(--notiqs-color-third) 0%, var(--notiqs-color-third-dark) 100%);
+  box-shadow: 0 4px 12px var(--notiqs-color-third-glow);
+}
+
+.notiqs-fretboard-noteMarker[data-category="other"] {
+  background: linear-gradient(135deg, var(--notiqs-color-other) 0%, var(--notiqs-color-other-dark) 100%);
+  box-shadow: 0 4px 12px var(--notiqs-color-other-glow);
+}
+
+/* Fret Numbers */
+.notiqs-fretboard-fretNumbers {
+  display: flex;
+  gap: var(--notiqs-cell-gap);
+  margin-top: 0.5rem;
+}
+
+.notiqs-fretboard-fretNumbers > span:first-child {
+  width: var(--notiqs-string-label-width);
+  flex-shrink: 0;
+}
+
+.notiqs-fretboard-fretNumber {
+  width: var(--notiqs-cell-width);
+  text-align: center;
+  flex-shrink: 0;
+  font-size: 0.875rem;
+  color: var(--notiqs-text-muted);
+}
+
+/* Responsive */
+@media (max-width: 768px) {
+  .notiqs-fretboard-root {
+    --notiqs-cell-width: 48px;
+    --notiqs-cell-height: 38px;
+    --notiqs-note-size: 28px;
+    --notiqs-note-radius: 8px;
+    --notiqs-note-font-size: 0.75rem;
+  }
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@notiqs/fretboard",
+  "version": "0.1.0",
+  "description": "A customizable React fretboard component for guitar, bass, and string instruments",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./styles.css": "./dist/styles.css"
+  },
+  "files": ["dist", "README.md"],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0"
+  },
+  "devDependencies": {
+    "react": "^19.2.0",
+    "tsup": "^8.4.0",
+    "typescript": "~5.9.3"
+  },
+  "keywords": ["react", "fretboard", "guitar", "bass", "music", "music-theory", "visualization", "component"],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nahularenas/Notiqs",
+    "directory": "packages/fretboard"
+  }
+}