@musodojo/music-theory-data 20.1.3 → 20.2.0

package/README.md

@@ -6,15 +6,14 @@ more.**
 
 [![npm version](https://img.shields.io/npm/v/@musodojo/music-theory-data.svg)](https://www.npmjs.com/package/@musodojo/music-theory-data)
 [![npm downloads](https://img.shields.io/npm/dw/@musodojo/music-theory-data.svg)](https://www.npmjs.com/package/@musodojo/music-theory-data)
-
 [![JSR score](https://jsr.io/badges/@musodojo/music-theory-data)](https://jsr.io/@musodojo/music-theory-data)
 
 ## Community & Support
 
 Have a question, a suggestion, or want to report a bug? Get in touch!
 
-- **💬 Discord Server:** Connect with other developers and music
-  enthusiasts in the [`#music-theory-data` channel.](https://discord.gg/3Tt4SXG5QC)
+- **💬 Discord Server:** Connect with other developers and music enthusiasts in
+  the [`#music-theory-data` channel.](https://discord.gg/3Tt4SXG5QC)
 - **📢 Ask a Question or Share an Idea:** Use
   [GitHub Discussions](https://github.com/conor-dowdall/music-theory-data/discussions).
 - **🐞 Report a Bug or Flaw in the Data:** Open a
@@ -47,6 +46,7 @@ intervals, integer notations, and common names.
 
 ```ts
 // src/data/note-collections/diatonic-modes.ts
+// @ts-ignore
 const ionian: ModalScaleCollection = {
   category: "scale",
   rotation: 0,
@@ -87,16 +87,18 @@ const ionian: ModalScaleCollection = {
 ### Practical Utility Functions
 
 Helpers for common tasks like generating note names from a root note and a set
-of intervals.
+of intervals. For the full implementation details, refer to the source file.
 
 ```ts
-// src/utils/note-names.ts
 export function getNoteNamesFromRootAndIntervals(
+  // @ts-ignore
   rootNote: RootNote,
   intervals: readonly Interval[],
-  options: TransformIntervalsOptions = {}
+  options: TransformIntervalsOptions = {},
 ): NoteName[] {
-  //...
+  // This is a simplified representation for documentation purposes.
+  // The actual implementation is in src/utils/note-names.ts
+  return [];
 }
 ```
 
@@ -142,7 +144,7 @@ import * as music_theory_data from "jsr:@musodojo/music-theory-data";
 // Get the notes of A Harmonic Minor
 const notes1 = music_theory_data.getNoteNamesFromRootAndCollectionKey(
   "A",
-  "harmonicMinor"
+  "harmonicMinor",
 );
 console.log(notes1);
 // ["A", "B", "C", "D", "E", "F", "G♯", "A"]
@@ -150,7 +152,7 @@ console.log(notes1);
 // Automatically knows whether to use flats or sharps
 const notes2 = music_theory_data.getNoteNamesFromRootAndCollectionKey(
   "F",
-  "ionian"
+  "ionian",
 );
 console.log(notes2);
 //  ["F", "G", "A", "B♭", "C", "D", "E", "F"];

package/package.json

@@ -1,10 +1,15 @@
 {
   "name": "@musodojo/music-theory-data",
-  "version": "20.1.3",
-  "description": "The musician-friendly TypeScript library for modes, scales, chords, and more.",
+  "version": "20.2.0",
+  "description": "The musician-friendly TypeScript library for scales, modes, chords, and arpeggios.",
   "keywords": [
     "music",
-    "theory"
+    "theory",
+    "enharmonic",
+    "scale",
+    "mode",
+    "chord",
+    "arpeggio"
   ],
   "license": "CC0-1.0",
   "author": "Conor Dowdall",

package/src/utils/colors.ts

@@ -0,0 +1,57 @@
+/**
+ * Parses a hex color string and returns its RGB components.
+ * Supports 3-digit (#RGB) and 6-digit (#RRGGBB) formats.
+ * @param hex The hex color string.
+ * @returns An array [r, g, b] or null if the format is invalid.
+ */
+export function parseHexColor(hex: string): [number, number, number] | null {
+  const hexRegex = /^#?([a-f\d]{2})([a-f\d]{2})([a-f\d]{2})$/i;
+  const shorthandHexRegex = /^#?([a-f\d])([a-f\d])([a-f\d])$/i;
+
+  // Expand shorthand form (e.g. "03F") to full form (e.g. "0033FF")
+  const fullHex = hex.replace(
+    shorthandHexRegex,
+    (_, r, g, b) => r + r + g + g + b + b,
+  );
+
+  const result = hexRegex.exec(fullHex);
+  return result
+    ? [
+      parseInt(result[1], 16),
+      parseInt(result[2], 16),
+      parseInt(result[3], 16),
+    ]
+    : null;
+}
+
+/**
+ * Calculates whether black or white text has a better contrast ratio against a given background color.
+ * @param {string} color - The background color in hex format, e.g. "#E21C48"
+ * @returns {'black' | 'white'} - The color that provides better contrast.
+ */
+export function getContrastColor(color: string): "black" | "white" {
+  // For now, we only support hex colors as that's what's in the library.
+  // This can be expanded to support rgb(), hsl(), and color keywords if needed.
+  const rgb = parseHexColor(color);
+  if (!rgb) {
+    return "black"; // Default to black if color parsing fails
+  }
+
+  const [r, g, b] = rgb;
+
+  // Formula for relative luminance (from WCAG)
+  // https://www.w3.org/TR/WCAG20/#relativeluminancedef
+  const getLuminance = (c: number) => {
+    const sRGB = c / 255;
+    return sRGB <= 0.03928
+      ? sRGB / 12.92
+      : Math.pow((sRGB + 0.055) / 1.055, 2.4);
+  };
+
+  const luminance = 0.2126 * getLuminance(r) +
+    0.7152 * getLuminance(g) +
+    0.0722 * getLuminance(b);
+
+  // Use a threshold of 0.179 as recommended by WCAG for contrast
+  return luminance > 0.179 ? "black" : "white";
+}

package/src/utils/mod.ts

@@ -1,3 +1,4 @@
+export * from "./colors.ts";
 export * from "./chords.ts";
 export * from "./intervals.ts";
 export * from "./midi-note-sequences.ts";