tonal-guitar 0.2.0 → 0.3.0

package/README.md

@@ -733,6 +733,12 @@ The package exports these TypeScript interfaces:
 - `AsciiTabOptions` — options for `toAsciiTab`
 - `KeyAnalysis` — result of `analyzeInKey`
 
+## Development
+
+To author new shapes visually instead of hand-writing `src/data/*.ts`, run `npm run workbench` to start the local Shape Workbench — a Vite + React app (Board → Editor → Export) for building and editing scale/chord shapes on a virtual fretboard. Exporting from the app writes a changeset to `.workbench/changeset.json`.
+
+Run `npm run shapes:merge -- .workbench/changeset.json` to land that changeset into `src/data/` and `src/index.ts`. Pass `--dry-run` to preview the resulting diff without writing, or `--check` to validate the changeset (e.g. in CI) without merging.
+
 ## Related
 
 - [@tonaljs/scale](https://github.com/tonaljs/tonal/tree/main/packages/scale) — scale definitions and lookups

package/dist/chord-types.d.mts

@@ -0,0 +1,233 @@
+/**
+ * Canonical chord-type table.
+ *
+ * One row per `chordType` key registered in the chord-shape registry
+ * (`src/data/*.ts`), carrying everything a consumer needs to name, display
+ * and resolve that quality without reaching into the registry itself.
+ *
+ * ## Purity contract
+ *
+ * This module has **no imports** — not from `./shape`, `./data`, `./build` or
+ * `./index`, and not from Tonal. Importing it (directly, or through the
+ * `tonal-guitar/chord-types` package subpath) registers **zero** shapes and
+ * runs no side effects, so a consumer that only wants the vocabulary never
+ * pays for the 132-shape registry. `src/chord-types.test.ts` enforces this
+ * both statically (reading this file's text) and at runtime.
+ *
+ * ## Row fields
+ *
+ * | Field            | Meaning                                                                     |
+ * | ---------------- | --------------------------------------------------------------------------- |
+ * | `id`             | The registry `chordType` key, verbatim (`"6/9"`, `"mMaj7"`, `"add9"`).      |
+ * | `tonalCanonical` | `ChordType.get(id).aliases[0]` — what Tonal canonicalises this quality to.  |
+ * | `label`          | Human label for pickers (`"Major 7"`, `"Sus 4"`, `"Six-nine"`).             |
+ * | `glyph`          | Lead-sheet suffix (`""`, `"-7"`, `"△7"`, `"ø7"`, `"°7"`).                   |
+ * | `intervals`      | `ChordType.get(id).intervals`, in Tonal's compound-interval vocabulary.     |
+ *
+ * ## Alias divergences (the reason `tonalCanonical` exists)
+ *
+ * For 22 of the 25 rows `tonalCanonical === id`. Three diverge, and a
+ * consumer that canonicalises a chord symbol through Tonal before querying
+ * the registry silently finds nothing for them unless it bridges back:
+ *
+ * | `id`    | `tonalCanonical` |
+ * | ------- | ---------------- |
+ * | `add9`  | `Madd9`          |
+ * | `6/9`   | `6add9`          |
+ * | `mMaj7` | `m/ma7`          |
+ *
+ * ## `aug7` is deliberately absent
+ *
+ * `aug7` and `7#5` are the same Tonal chord — identical intervals
+ * (`1P 3M 5A 7m`) and overlapping `detect` aliases. The registry indexes
+ * chord types by exact string with no alias resolution, and registers `7#5`
+ * only (see `src/data/extended-chords.ts`'s "Interop divergence catalog"), so
+ * `chordShapes.query({ chordType: "aug7" })` returns nothing by design. Giving
+ * `aug7` its own row here would break the table's central invariant — every
+ * `id` is voiceable and every registered key is in the table — so callers that
+ * see `aug7` should map it onto the `7#5` row.
+ */
+/** One canonical chord type. */
+interface ChordTypeEntry {
+    /** Registry `chordType` key, verbatim. */
+    readonly id: string;
+    /** `ChordType.get(id).aliases[0]` — Tonal's canonical spelling. */
+    readonly tonalCanonical: string;
+    /** Human label for pickers. */
+    readonly label: string;
+    /** Lead-sheet suffix glyph. */
+    readonly glyph: string;
+    /** `ChordType.get(id).intervals`, Tonal compound-interval vocabulary. */
+    readonly intervals: readonly string[];
+}
+/**
+ * The 25 registered chord types, in picker order (triads and sevenths first,
+ * then suspensions, altered dominants and extensions).
+ */
+declare const CHORD_TYPE_TABLE: readonly [{
+    readonly id: "M";
+    readonly tonalCanonical: "M";
+    readonly label: "Major";
+    readonly glyph: "";
+    readonly intervals: readonly ["1P", "3M", "5P"];
+}, {
+    readonly id: "m";
+    readonly tonalCanonical: "m";
+    readonly label: "Minor";
+    readonly glyph: "-";
+    readonly intervals: readonly ["1P", "3m", "5P"];
+}, {
+    readonly id: "7";
+    readonly tonalCanonical: "7";
+    readonly label: "Dominant 7";
+    readonly glyph: "7";
+    readonly intervals: readonly ["1P", "3M", "5P", "7m"];
+}, {
+    readonly id: "maj7";
+    readonly tonalCanonical: "maj7";
+    readonly label: "Major 7";
+    readonly glyph: "△7";
+    readonly intervals: readonly ["1P", "3M", "5P", "7M"];
+}, {
+    readonly id: "m7";
+    readonly tonalCanonical: "m7";
+    readonly label: "Minor 7";
+    readonly glyph: "-7";
+    readonly intervals: readonly ["1P", "3m", "5P", "7m"];
+}, {
+    readonly id: "m7b5";
+    readonly tonalCanonical: "m7b5";
+    readonly label: "Minor 7b5";
+    readonly glyph: "ø7";
+    readonly intervals: readonly ["1P", "3m", "5d", "7m"];
+}, {
+    readonly id: "dim";
+    readonly tonalCanonical: "dim";
+    readonly label: "Diminished";
+    readonly glyph: "°";
+    readonly intervals: readonly ["1P", "3m", "5d"];
+}, {
+    readonly id: "sus2";
+    readonly tonalCanonical: "sus2";
+    readonly label: "Sus 2";
+    readonly glyph: "sus2";
+    readonly intervals: readonly ["1P", "2M", "5P"];
+}, {
+    readonly id: "sus4";
+    readonly tonalCanonical: "sus4";
+    readonly label: "Sus 4";
+    readonly glyph: "sus4";
+    readonly intervals: readonly ["1P", "4P", "5P"];
+}, {
+    readonly id: "aug";
+    readonly tonalCanonical: "aug";
+    readonly label: "Augmented";
+    readonly glyph: "+";
+    readonly intervals: readonly ["1P", "3M", "5A"];
+}, {
+    readonly id: "7#5";
+    readonly tonalCanonical: "7#5";
+    readonly label: "Dominant 7#5";
+    readonly glyph: "7#5";
+    readonly intervals: readonly ["1P", "3M", "5A", "7m"];
+}, {
+    readonly id: "7sus4";
+    readonly tonalCanonical: "7sus4";
+    readonly label: "Dominant 7 Sus 4";
+    readonly glyph: "7sus4";
+    readonly intervals: readonly ["1P", "4P", "5P", "7m"];
+}, {
+    readonly id: "7b5";
+    readonly tonalCanonical: "7b5";
+    readonly label: "Dominant 7b5";
+    readonly glyph: "7b5";
+    readonly intervals: readonly ["1P", "3M", "5d", "7m"];
+}, {
+    readonly id: "13";
+    readonly tonalCanonical: "13";
+    readonly label: "Thirteenth";
+    readonly glyph: "13";
+    readonly intervals: readonly ["1P", "3M", "5P", "7m", "9M", "13M"];
+}, {
+    readonly id: "mMaj7";
+    readonly tonalCanonical: "m/ma7";
+    readonly label: "Minor Major 7";
+    readonly glyph: "-△7";
+    readonly intervals: readonly ["1P", "3m", "5P", "7M"];
+}, {
+    readonly id: "maj9";
+    readonly tonalCanonical: "maj9";
+    readonly label: "Major 9";
+    readonly glyph: "△9";
+    readonly intervals: readonly ["1P", "3M", "5P", "7M", "9M"];
+}, {
+    readonly id: "m9";
+    readonly tonalCanonical: "m9";
+    readonly label: "Minor 9";
+    readonly glyph: "-9";
+    readonly intervals: readonly ["1P", "3m", "5P", "7m", "9M"];
+}, {
+    readonly id: "m6";
+    readonly tonalCanonical: "m6";
+    readonly label: "Minor 6";
+    readonly glyph: "-6";
+    readonly intervals: readonly ["1P", "3m", "5P", "6M"];
+}, {
+    readonly id: "dim7";
+    readonly tonalCanonical: "dim7";
+    readonly label: "Diminished 7";
+    readonly glyph: "°7";
+    readonly intervals: readonly ["1P", "3m", "5d", "7d"];
+}, {
+    readonly id: "add9";
+    readonly tonalCanonical: "Madd9";
+    readonly label: "Add 9";
+    readonly glyph: "add9";
+    readonly intervals: readonly ["1P", "3M", "5P", "9M"];
+}, {
+    readonly id: "9";
+    readonly tonalCanonical: "9";
+    readonly label: "Dominant 9";
+    readonly glyph: "9";
+    readonly intervals: readonly ["1P", "3M", "5P", "7m", "9M"];
+}, {
+    readonly id: "7b9";
+    readonly tonalCanonical: "7b9";
+    readonly label: "Dominant 7b9";
+    readonly glyph: "7b9";
+    readonly intervals: readonly ["1P", "3M", "5P", "7m", "9m"];
+}, {
+    readonly id: "7#9";
+    readonly tonalCanonical: "7#9";
+    readonly label: "Dominant 7#9";
+    readonly glyph: "7#9";
+    readonly intervals: readonly ["1P", "3M", "5P", "7m", "9A"];
+}, {
+    readonly id: "6/9";
+    readonly tonalCanonical: "6add9";
+    readonly label: "Six-nine";
+    readonly glyph: "6/9";
+    readonly intervals: readonly ["1P", "3M", "5P", "6M", "9M"];
+}, {
+    readonly id: "6";
+    readonly tonalCanonical: "6";
+    readonly label: "Major 6";
+    readonly glyph: "6";
+    readonly intervals: readonly ["1P", "3M", "5P", "6M"];
+}];
+/** One row of {@link CHORD_TYPE_TABLE}, with literal field types. */
+type ChordTypeRow = (typeof CHORD_TYPE_TABLE)[number];
+/** Literal union of every registered `chordType` key. */
+type ChordTypeKey = ChordTypeRow["id"];
+/**
+ * Every registered `chordType` key, in {@link CHORD_TYPE_TABLE} order, as a
+ * literal tuple (so consumers can feed it to `z.enum` or index a
+ * `Record<ChordTypeKey, …>` without widening to `string[]`).
+ *
+ * Written out rather than derived so it stays a tuple; `chord-types.test.ts`
+ * asserts it equals `CHORD_TYPE_TABLE.map((row) => row.id)` element for
+ * element, so the two can never drift.
+ */
+declare const CHORD_TYPE_KEYS: readonly ["M", "m", "7", "maj7", "m7", "m7b5", "dim", "sus2", "sus4", "aug", "7#5", "7sus4", "7b5", "13", "mMaj7", "maj9", "m9", "m6", "dim7", "add9", "9", "7b9", "7#9", "6/9", "6"];
+
+export { CHORD_TYPE_KEYS, CHORD_TYPE_TABLE, type ChordTypeEntry, type ChordTypeKey, type ChordTypeRow };

package/dist/chord-types.d.ts

@@ -0,0 +1,233 @@
+/**
+ * Canonical chord-type table.
+ *
+ * One row per `chordType` key registered in the chord-shape registry
+ * (`src/data/*.ts`), carrying everything a consumer needs to name, display
+ * and resolve that quality without reaching into the registry itself.
+ *
+ * ## Purity contract
+ *
+ * This module has **no imports** — not from `./shape`, `./data`, `./build` or
+ * `./index`, and not from Tonal. Importing it (directly, or through the
+ * `tonal-guitar/chord-types` package subpath) registers **zero** shapes and
+ * runs no side effects, so a consumer that only wants the vocabulary never
+ * pays for the 132-shape registry. `src/chord-types.test.ts` enforces this
+ * both statically (reading this file's text) and at runtime.
+ *
+ * ## Row fields
+ *
+ * | Field            | Meaning                                                                     |
+ * | ---------------- | --------------------------------------------------------------------------- |
+ * | `id`             | The registry `chordType` key, verbatim (`"6/9"`, `"mMaj7"`, `"add9"`).      |
+ * | `tonalCanonical` | `ChordType.get(id).aliases[0]` — what Tonal canonicalises this quality to.  |
+ * | `label`          | Human label for pickers (`"Major 7"`, `"Sus 4"`, `"Six-nine"`).             |
+ * | `glyph`          | Lead-sheet suffix (`""`, `"-7"`, `"△7"`, `"ø7"`, `"°7"`).                   |
+ * | `intervals`      | `ChordType.get(id).intervals`, in Tonal's compound-interval vocabulary.     |
+ *
+ * ## Alias divergences (the reason `tonalCanonical` exists)
+ *
+ * For 22 of the 25 rows `tonalCanonical === id`. Three diverge, and a
+ * consumer that canonicalises a chord symbol through Tonal before querying
+ * the registry silently finds nothing for them unless it bridges back:
+ *
+ * | `id`    | `tonalCanonical` |
+ * | ------- | ---------------- |
+ * | `add9`  | `Madd9`          |
+ * | `6/9`   | `6add9`          |
+ * | `mMaj7` | `m/ma7`          |
+ *
+ * ## `aug7` is deliberately absent
+ *
+ * `aug7` and `7#5` are the same Tonal chord — identical intervals
+ * (`1P 3M 5A 7m`) and overlapping `detect` aliases. The registry indexes
+ * chord types by exact string with no alias resolution, and registers `7#5`
+ * only (see `src/data/extended-chords.ts`'s "Interop divergence catalog"), so
+ * `chordShapes.query({ chordType: "aug7" })` returns nothing by design. Giving
+ * `aug7` its own row here would break the table's central invariant — every
+ * `id` is voiceable and every registered key is in the table — so callers that
+ * see `aug7` should map it onto the `7#5` row.
+ */
+/** One canonical chord type. */
+interface ChordTypeEntry {
+    /** Registry `chordType` key, verbatim. */
+    readonly id: string;
+    /** `ChordType.get(id).aliases[0]` — Tonal's canonical spelling. */
+    readonly tonalCanonical: string;
+    /** Human label for pickers. */
+    readonly label: string;
+    /** Lead-sheet suffix glyph. */
+    readonly glyph: string;
+    /** `ChordType.get(id).intervals`, Tonal compound-interval vocabulary. */
+    readonly intervals: readonly string[];
+}
+/**
+ * The 25 registered chord types, in picker order (triads and sevenths first,
+ * then suspensions, altered dominants and extensions).
+ */
+declare const CHORD_TYPE_TABLE: readonly [{
+    readonly id: "M";
+    readonly tonalCanonical: "M";
+    readonly label: "Major";
+    readonly glyph: "";
+    readonly intervals: readonly ["1P", "3M", "5P"];
+}, {
+    readonly id: "m";
+    readonly tonalCanonical: "m";
+    readonly label: "Minor";
+    readonly glyph: "-";
+    readonly intervals: readonly ["1P", "3m", "5P"];
+}, {
+    readonly id: "7";
+    readonly tonalCanonical: "7";
+    readonly label: "Dominant 7";
+    readonly glyph: "7";
+    readonly intervals: readonly ["1P", "3M", "5P", "7m"];
+}, {
+    readonly id: "maj7";
+    readonly tonalCanonical: "maj7";
+    readonly label: "Major 7";
+    readonly glyph: "△7";
+    readonly intervals: readonly ["1P", "3M", "5P", "7M"];
+}, {
+    readonly id: "m7";
+    readonly tonalCanonical: "m7";
+    readonly label: "Minor 7";
+    readonly glyph: "-7";
+    readonly intervals: readonly ["1P", "3m", "5P", "7m"];
+}, {
+    readonly id: "m7b5";
+    readonly tonalCanonical: "m7b5";
+    readonly label: "Minor 7b5";
+    readonly glyph: "ø7";
+    readonly intervals: readonly ["1P", "3m", "5d", "7m"];
+}, {
+    readonly id: "dim";
+    readonly tonalCanonical: "dim";
+    readonly label: "Diminished";
+    readonly glyph: "°";
+    readonly intervals: readonly ["1P", "3m", "5d"];
+}, {
+    readonly id: "sus2";
+    readonly tonalCanonical: "sus2";
+    readonly label: "Sus 2";
+    readonly glyph: "sus2";
+    readonly intervals: readonly ["1P", "2M", "5P"];
+}, {
+    readonly id: "sus4";
+    readonly tonalCanonical: "sus4";
+    readonly label: "Sus 4";
+    readonly glyph: "sus4";
+    readonly intervals: readonly ["1P", "4P", "5P"];
+}, {
+    readonly id: "aug";
+    readonly tonalCanonical: "aug";
+    readonly label: "Augmented";
+    readonly glyph: "+";
+    readonly intervals: readonly ["1P", "3M", "5A"];
+}, {
+    readonly id: "7#5";
+    readonly tonalCanonical: "7#5";
+    readonly label: "Dominant 7#5";
+    readonly glyph: "7#5";
+    readonly intervals: readonly ["1P", "3M", "5A", "7m"];
+}, {
+    readonly id: "7sus4";
+    readonly tonalCanonical: "7sus4";
+    readonly label: "Dominant 7 Sus 4";
+    readonly glyph: "7sus4";
+    readonly intervals: readonly ["1P", "4P", "5P", "7m"];
+}, {
+    readonly id: "7b5";
+    readonly tonalCanonical: "7b5";
+    readonly label: "Dominant 7b5";
+    readonly glyph: "7b5";
+    readonly intervals: readonly ["1P", "3M", "5d", "7m"];
+}, {
+    readonly id: "13";
+    readonly tonalCanonical: "13";
+    readonly label: "Thirteenth";
+    readonly glyph: "13";
+    readonly intervals: readonly ["1P", "3M", "5P", "7m", "9M", "13M"];
+}, {
+    readonly id: "mMaj7";
+    readonly tonalCanonical: "m/ma7";
+    readonly label: "Minor Major 7";
+    readonly glyph: "-△7";
+    readonly intervals: readonly ["1P", "3m", "5P", "7M"];
+}, {
+    readonly id: "maj9";
+    readonly tonalCanonical: "maj9";
+    readonly label: "Major 9";
+    readonly glyph: "△9";
+    readonly intervals: readonly ["1P", "3M", "5P", "7M", "9M"];
+}, {
+    readonly id: "m9";
+    readonly tonalCanonical: "m9";
+    readonly label: "Minor 9";
+    readonly glyph: "-9";
+    readonly intervals: readonly ["1P", "3m", "5P", "7m", "9M"];
+}, {
+    readonly id: "m6";
+    readonly tonalCanonical: "m6";
+    readonly label: "Minor 6";
+    readonly glyph: "-6";
+    readonly intervals: readonly ["1P", "3m", "5P", "6M"];
+}, {
+    readonly id: "dim7";
+    readonly tonalCanonical: "dim7";
+    readonly label: "Diminished 7";
+    readonly glyph: "°7";
+    readonly intervals: readonly ["1P", "3m", "5d", "7d"];
+}, {
+    readonly id: "add9";
+    readonly tonalCanonical: "Madd9";
+    readonly label: "Add 9";
+    readonly glyph: "add9";
+    readonly intervals: readonly ["1P", "3M", "5P", "9M"];
+}, {
+    readonly id: "9";
+    readonly tonalCanonical: "9";
+    readonly label: "Dominant 9";
+    readonly glyph: "9";
+    readonly intervals: readonly ["1P", "3M", "5P", "7m", "9M"];
+}, {
+    readonly id: "7b9";
+    readonly tonalCanonical: "7b9";
+    readonly label: "Dominant 7b9";
+    readonly glyph: "7b9";
+    readonly intervals: readonly ["1P", "3M", "5P", "7m", "9m"];
+}, {
+    readonly id: "7#9";
+    readonly tonalCanonical: "7#9";
+    readonly label: "Dominant 7#9";
+    readonly glyph: "7#9";
+    readonly intervals: readonly ["1P", "3M", "5P", "7m", "9A"];
+}, {
+    readonly id: "6/9";
+    readonly tonalCanonical: "6add9";
+    readonly label: "Six-nine";
+    readonly glyph: "6/9";
+    readonly intervals: readonly ["1P", "3M", "5P", "6M", "9M"];
+}, {
+    readonly id: "6";
+    readonly tonalCanonical: "6";
+    readonly label: "Major 6";
+    readonly glyph: "6";
+    readonly intervals: readonly ["1P", "3M", "5P", "6M"];
+}];
+/** One row of {@link CHORD_TYPE_TABLE}, with literal field types. */
+type ChordTypeRow = (typeof CHORD_TYPE_TABLE)[number];
+/** Literal union of every registered `chordType` key. */
+type ChordTypeKey = ChordTypeRow["id"];
+/**
+ * Every registered `chordType` key, in {@link CHORD_TYPE_TABLE} order, as a
+ * literal tuple (so consumers can feed it to `z.enum` or index a
+ * `Record<ChordTypeKey, …>` without widening to `string[]`).
+ *
+ * Written out rather than derived so it stays a tuple; `chord-types.test.ts`
+ * asserts it equals `CHORD_TYPE_TABLE.map((row) => row.id)` element for
+ * element, so the two can never drift.
+ */
+declare const CHORD_TYPE_KEYS: readonly ["M", "m", "7", "maj7", "m7", "m7b5", "dim", "sus2", "sus4", "aug", "7#5", "7sus4", "7b5", "13", "mMaj7", "maj9", "m9", "m6", "dim7", "add9", "9", "7b9", "7#9", "6/9", "6"];
+
+export { CHORD_TYPE_KEYS, CHORD_TYPE_TABLE, type ChordTypeEntry, type ChordTypeKey, type ChordTypeRow };