zds-pickers 4.2.0 → 4.3.0

package/dist/index.js

@@ -2,6 +2,7 @@ export * from './utils';
 export * from './midi/ccValues';
 export * from './midi/export';
 export * from './other/DefaultTooltip';
+export * from './other/noteNames';
 export * from './other/OctavePlayer';
 export * from './other/SvgText';
 export * from './pickers/CCPicker';

package/dist/other/SvgText.js

@@ -1,6 +1,35 @@
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 const MEASUREMENT_ELEMENT_ID = '__react_svg_text_measurement_id';
+/**
+ * The only computed properties that affect measured text geometry. Copying
+ * the full computed style (~300 properties) onto the measurement node per
+ * instance forced a style flush that dominated initial render in hosts
+ * with many SvgText instances.
+ */
+const FONT_PROPERTIES = [
+    'font-family',
+    'font-feature-settings',
+    'font-kerning',
+    'font-size',
+    'font-stretch',
+    'font-style',
+    'font-variant',
+    'font-weight',
+    'letter-spacing',
+    'text-transform',
+    'word-spacing',
+];
+const fontSignature = (style) => FONT_PROPERTIES.map(key => style.getPropertyValue(key)).join('|');
+/**
+ * Word widths only depend on the word and the font it renders in, so they
+ * are cached module-wide by font signature. Text that repeats across
+ * instances (labels, numbers) measures once per font, ever.
+ */
+const fontMetricsCache = new Map();
+const __resetFontMetricsCacheForTests = () => {
+    fontMetricsCache.clear();
+};
 const calculateWordsByLines = (text, wordWidths, maxWidth, maxHeight) => {
     const { lineHeight, spaceWidth, wordsWithComputedWidth } = wordWidths;
     return text.split(/\s+/).reduce((result, word) => {
@@ -27,19 +56,39 @@ const calculateWordsByLines = (text, wordWidths, maxWidth, maxHeight) => {
 };
 const calculateWordWidths = (style, textNode, text) => {
     if (style && textNode) {
-        // biome-ignore lint/complexity/noForEach: <explanation>
-        Array.from(style).forEach(key => textNode.style.setProperty(key, style.getPropertyValue(key), style.getPropertyPriority(key)));
+        const signature = fontSignature(style);
+        let metrics = fontMetricsCache.get(signature);
         const wordArray = [...new Set(String(text).split(/\s+/))];
-        const wordsWithComputedWidth = wordArray.reduce((wordMap, word) => {
-            textNode.textContent = word;
-            // biome-ignore lint/performance/noAccumulatingSpread: <explanation>
-            return { ...wordMap, [word]: textNode.getBBox().width };
-        }, {});
-        textNode.textContent = '\u00A0';
-        const spaceWidth = textNode?.getComputedTextLength?.() || 8;
-        const lineHeight = textNode.getBBox().height;
-        textNode.setAttribute('style', '');
-        return { wordsWithComputedWidth, spaceWidth, lineHeight };
+        const knownWidths = metrics?.widths;
+        const missingWords = knownWidths
+            ? wordArray.filter(word => !knownWidths.has(word))
+            : wordArray;
+        if (!metrics || missingWords.length) {
+            for (const key of FONT_PROPERTIES) {
+                textNode.style.setProperty(key, style.getPropertyValue(key), style.getPropertyPriority(key));
+            }
+            if (!metrics) {
+                textNode.textContent = '\u00A0';
+                const spaceWidth = textNode?.getComputedTextLength?.() || 8;
+                const lineHeight = textNode.getBBox().height;
+                metrics = { widths: new Map(), spaceWidth, lineHeight };
+                fontMetricsCache.set(signature, metrics);
+            }
+            for (const word of missingWords) {
+                textNode.textContent = word;
+                metrics.widths.set(word, textNode.getBBox().width);
+            }
+            textNode.setAttribute('style', '');
+        }
+        const wordsWithComputedWidth = {};
+        for (const word of wordArray) {
+            wordsWithComputedWidth[word] = metrics.widths.get(word) ?? 0;
+        }
+        return {
+            wordsWithComputedWidth,
+            spaceWidth: metrics.spaceWidth,
+            lineHeight: metrics.lineHeight,
+        };
     }
     return undefined;
 };
@@ -67,14 +116,28 @@ const SvgText = (props) => {
         if (el === null) {
             const svg = document.createElementNS('http://www.w3.org/2000/svg', 'svg');
             svg.setAttribute('id', MEASUREMENT_ELEMENT_ID);
+            svg.setAttribute('aria-hidden', 'true');
+            // Rendered but invisible: getBBox returns zeros under display:none,
+            // so park it offscreen instead. Being outside any host SVG also
+            // keeps per-word getBBox from forcing layout of live content.
+            svg.style.position = 'fixed';
+            svg.style.left = '-9999px';
+            svg.style.top = '0';
+            const textEl = document.createElementNS('http://www.w3.org/2000/svg', 'text');
+            svg.appendChild(textEl);
             document.body.appendChild(svg);
-            svg.appendChild(document.createElementNS('http://www.w3.org/2000/svg', 'text'));
-            measureRef.current = svg;
-            return () => {
-                document.body.removeChild(svg);
-            };
+            // Measure against the <text> child — pointing at the <svg> container
+            // made every measurement return the svg's own box.
+            measureRef.current = textEl;
+            // Deliberately no cleanup: the element is a shared singleton and
+            // other mounted instances may still hold it as their measure target.
+            return;
         }
-        measureRef.current = el;
+        // Hosts may provide either the <text> itself or a container around one.
+        measureRef.current =
+            el.tagName.toLowerCase() === 'text'
+                ? el
+                : (el.querySelector('text') ?? el);
     }, []);
     useEffect(() => {
         const wordWithWidths = calculateWordWidths(style, measureRef.current, text);
@@ -105,4 +168,4 @@ const SvgText = (props) => {
         // textAnchor={textAnchor}
         transform: transform, ...rest, children: _jsxs(_Fragment, { children: [displayedLines.map((line, idx) => (_jsx("tspan", { dx: x + dx, dy: idx === 0 ? startDy + dy : wordWidths?.lineHeight || 0, x: 0, children: line.words.join(' ') }, idx))), textLines.length && displayedLines.length !== textLines.length && (_jsxs(_Fragment, { children: [_jsx("tspan", { children: "..." }), _jsx("title", { children: text })] }))] }) }));
 };
-export { SvgText, MEASUREMENT_ELEMENT_ID };
+export { __resetFontMetricsCacheForTests, calculateWordsByLines, calculateWordWidths, MEASUREMENT_ELEMENT_ID, SvgText, };

package/dist/other/noteNames.js

@@ -0,0 +1,22 @@
+import { Midi, Note } from 'tonal';
+const { midiToNoteName } = Midi;
+/**
+ * Rewrites ASCII accidentals in a note name to their Unicode glyphs, so
+ * labels read as `D♭` / `F♯` rather than `Db` / `F#`.
+ */
+const formatPitchName = (name) => name.replace(/([A-G])b/g, '$1♭').replace(/([A-G])#/g, '$1♯');
+/**
+ * Pitch class (no octave) for a MIDI note, as a display label.
+ *
+ * `noteLabels`, when supplied, is a chroma-indexed array of names — index 0 is
+ * C, index 1 is C♯/D♭, and so on. It lets a caller impose key-aware spelling
+ * (a scale may legitimately need both B♭ and F♯), which a single sharps/flats
+ * flag cannot express. Missing entries fall back to the default flat spelling.
+ */
+const pitchClassLabel = (midiNumber, noteLabels) => noteLabels?.[((midiNumber % 12) + 12) % 12] ??
+    formatPitchName(Note.pitchClass(Note.fromMidi(midiNumber) ?? ''));
+/**
+ * Note name with octave for a MIDI note, flats by default (`70` → `B♭4`).
+ */
+const midiNoteLabel = (note) => formatPitchName(midiToNoteName(note, { sharps: false }));
+export { formatPitchName, midiNoteLabel, pitchClassLabel };

package/dist/pickers/KeyPicker.js

@@ -1,15 +1,18 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import classNames from 'classnames';
-import { useCallback } from 'react';
+import { useCallback, useMemo } from 'react';
 import { Note } from 'tonal';
 import { OctavePlayer } from '../other/OctavePlayer';
+import { pitchClassLabel } from '../other/noteNames';
 import { noSelection } from './Select';
-const formatPitchName = (pitchClass) => pitchClass.replace(/([A-G])b/g, '$1\u266D');
 const NATURAL_LABEL_NUDGE_LEFT = new Set(['C', 'F']);
 const NATURAL_LABEL_NUDGE_RIGHT = new Set(['E', 'B']);
-const noteNameLabelRenderer = ({ isAccidental, isActive, midiNumber, }) => {
+const makeNoteNameLabelRenderer = (noteLabels) => ({ isAccidental, isActive, midiNumber }) => {
+    // Nudge classes key off the natural letter, which never varies with the
+    // caller's spelling choice, so they read the default name rather than the
+    // (possibly overridden) label.
     const pitchClass = Note.pitchClass(Note.fromMidi(midiNumber) ?? '');
-    const pitchName = formatPitchName(pitchClass);
+    const pitchName = pitchClassLabel(midiNumber, noteLabels);
     if (!pitchName)
         return null;
     return (_jsx("div", { className: classNames('ReactPiano__NoteLabel', 'ReactPiano__NoteLabel--noteName', {
@@ -21,7 +24,8 @@ const noteNameLabelRenderer = ({ isAccidental, isActive, midiNumber, }) => {
         }), children: pitchName }));
 };
 const KeyPicker = (props) => {
-    const { value, onChange, disabled = false, height = 100, showNoteNames = false, width = 300, octave = 4, ...rest } = props;
+    const { value, onChange, disabled = false, height = 100, noteLabels, showNoteNames = false, width = 300, octave = 4, ...rest } = props;
+    const renderNoteLabel = useMemo(() => makeNoteNameLabelRenderer(noteLabels), [noteLabels]);
     const handleKeyClick = useCallback((note) => {
         if (disabled)
             return;
@@ -32,6 +36,6 @@ const KeyPicker = (props) => {
     const octaveStart = 60 + (octave - 4) * 12;
     const octaveEnd = octaveStart + 11;
     const shouldHighlight = value !== noSelection && value >= octaveStart && value <= octaveEnd;
-    return (_jsx(OctavePlayer, { ...rest, className: showNoteNames ? 'ReactPiano--showNoteNames' : undefined, selectedNotes: shouldHighlight ? [value] : [], disabled: disabled, height: height, renderNoteLabel: showNoteNames ? noteNameLabelRenderer : undefined, width: width, octave: octave, onClick: handleKeyClick, instrumentName: "acoustic_grand_piano" }));
+    return (_jsx(OctavePlayer, { ...rest, className: showNoteNames ? 'ReactPiano--showNoteNames' : undefined, selectedNotes: shouldHighlight ? [value] : [], disabled: disabled, height: height, renderNoteLabel: showNoteNames ? renderNoteLabel : undefined, width: width, octave: octave, onClick: handleKeyClick, instrumentName: "acoustic_grand_piano" }));
 };
 export { KeyPicker };

package/dist/pickers/NotePicker.js

@@ -1,11 +1,10 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { forwardRef, useCallback, useMemo } from 'react';
-import { Midi } from 'tonal';
 import { emptyMapping } from 'zds-mappings';
 import useStateWithDynamicDefault from '../hooks/useStateWithDynamicDefault';
+import { midiNoteLabel } from '../other/noteNames';
 import { assertRange } from '../utils';
 import { Select } from './Select';
-const { midiToNoteName } = Midi;
 const formattedMapEntry = ({ note, name }) => `${note} ${name.length ? '-' : ''} ${name}`;
 const formattedListEntry = (label, idx) => ({
     label,
@@ -16,12 +15,7 @@ const NotePicker = forwardRef((props, ref) => {
     const options = useMemo(() => {
         if (isMelodicMode) {
             return emptyMapping()
-                .map(({ note }) => {
-                const midiNoteName = midiToNoteName(note, { sharps: false })
-                    .replace('b', '♭')
-                    .replace('#', '♯');
-                return `${midiNoteName} (#${note})`;
-            })
+                .map(({ note }) => `${midiNoteLabel(note)} (#${note})`)
                 .map(formattedListEntry);
         }
         return (mapping || emptyMapping())

package/dist/types/index.d.ts

@@ -2,6 +2,7 @@ export * from './utils';
 export * from './midi/ccValues';
 export * from './midi/export';
 export * from './other/DefaultTooltip';
+export * from './other/noteNames';
 export * from './other/OctavePlayer';
 export * from './other/SvgText';
 export * from './pickers/CCPicker';

package/dist/types/other/SvgText.d.ts

@@ -1,14 +1,17 @@
 declare const MEASUREMENT_ELEMENT_ID = "__react_svg_text_measurement_id";
+declare const __resetFontMetricsCacheForTests: () => void;
 type WordsByLine = {
     words: string[];
     width: number;
     showLine: boolean;
 };
+declare const calculateWordsByLines: (text: string, wordWidths: WordWidths, maxWidth: number, maxHeight: number) => WordsByLine[];
 type WordWidths = {
     wordsWithComputedWidth: Record<string, number>;
     spaceWidth: number;
     lineHeight: number;
 };
+declare const calculateWordWidths: (style?: CSSStyleDeclaration, textNode?: SVGGraphicsElement | null, text?: string) => WordWidths | undefined;
 type TextProps = Partial<HTMLOrSVGElement> & {
     className?: string;
     dx?: number;
@@ -23,5 +26,5 @@ type TextProps = Partial<HTMLOrSVGElement> & {
     y?: number;
 };
 declare const SvgText: (props: TextProps) => import("react/jsx-runtime").JSX.Element;
-export { SvgText, MEASUREMENT_ELEMENT_ID };
+export { __resetFontMetricsCacheForTests, calculateWordsByLines, calculateWordWidths, MEASUREMENT_ELEMENT_ID, SvgText, };
 export type { TextProps, WordWidths, WordsByLine };

package/dist/types/other/noteNames.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Rewrites ASCII accidentals in a note name to their Unicode glyphs, so
+ * labels read as `D♭` / `F♯` rather than `Db` / `F#`.
+ */
+declare const formatPitchName: (name: string) => string;
+/**
+ * Pitch class (no octave) for a MIDI note, as a display label.
+ *
+ * `noteLabels`, when supplied, is a chroma-indexed array of names — index 0 is
+ * C, index 1 is C♯/D♭, and so on. It lets a caller impose key-aware spelling
+ * (a scale may legitimately need both B♭ and F♯), which a single sharps/flats
+ * flag cannot express. Missing entries fall back to the default flat spelling.
+ */
+declare const pitchClassLabel: (midiNumber: number, noteLabels?: readonly string[]) => string;
+/**
+ * Note name with octave for a MIDI note, flats by default (`70` → `B♭4`).
+ */
+declare const midiNoteLabel: (note: number) => string;
+export { formatPitchName, midiNoteLabel, pitchClassLabel };

package/dist/types/pickers/KeyPicker.d.ts

@@ -4,6 +4,12 @@ type KeyPickerProps = Omit<PianoProviderProps, 'className' | 'instrumentName' |
     onChange: (value: number) => void;
     disabled?: boolean;
     height?: number;
+    /**
+     * Chroma-indexed note names (index 0 = C) overriding the default flat
+     * spelling — lets a caller label keys for a specific key/scale, where both
+     * sharps and flats can be correct at once. Missing entries fall back.
+     */
+    noteLabels?: readonly string[];
     showNoteNames?: boolean;
     width?: number;
     octave?: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zds-pickers",
-  "version": "4.2.0",
+  "version": "4.3.0",
   "main": "./dist/index.cjs.js",
   "module": "./dist/index.es.js",
   "types": "./dist/types/index.d.ts",