@cueplusplus/ui 0.13.0

package/dist/midi/_ruler.js

@@ -0,0 +1,105 @@
+import { DEFAULT_TIME_SIGNATURE, SIXTEENTH_BEATS, barBeats, beatsToMusical } from "./_time.js";
+//#region src/midi/_ruler.ts
+/**
+* Ruler arithmetic: how far apart the ticks go at a given zoom, and which of
+* them are actually on screen.
+*
+* Both halves are pure, and both are the part of a timeline that is easy to get
+* subtly wrong — a ruler that re-picks its interval one frame late flickers, and
+* a ruler that renders every tick of an eight-thousand-beat song locks the tab
+* on the first scroll.
+*
+* @internal `chooseInterval` and `rulerTicks` are re-exported from the `/midi`
+* barrel; the module itself is not public.
+*/
+/**
+* The pixel spacing a tick aims for: one centimetre at a nominal 96 DPI.
+*
+* A centimetre is the density a ruler stays *readable* at — close enough to
+* count by eye, far enough apart that the labels do not collide. Ported from
+* ableton-sync, which then multiplied the chosen interval by four "to make
+* markers 4x less dense", i.e. targeted 4 cm while claiming to target 1. The
+* multiplier is gone; callers who want a sparser ruler pass a bigger target.
+*/
+const TICK_TARGET_PX = 37.8;
+/** How far either side of the viewport ticks are still rendered, in px. */
+const DEFAULT_BUFFER_PX = 120;
+/**
+* How many beats apart the ticks should be at this zoom.
+*
+* The candidates are musical divisions only — sixteenth, eighth, quarter, half,
+* then the bar and multiples of it. A ruler that ticked every 3.7 beats because
+* that is what the arithmetic wanted would be unreadable; the whole point of a
+* musical ruler is that the numbers on it are numbers a musician counts in.
+*
+* @param pxPerBeat - Current zoom.
+* @param beatsPerBar - Length of a bar in quarter-note beats.
+* @param targetPx - Spacing to aim for. Defaults to {@link TICK_TARGET_PX}.
+* @returns The finest interval whose spacing reaches the target, or the coarsest
+*   candidate when even that does not — a ruler always ticks somewhere.
+*/
+function chooseInterval(pxPerBeat, beatsPerBar, targetPx = TICK_TARGET_PX) {
+	const bar = beatsPerBar > 0 ? beatsPerBar : barBeats();
+	const candidates = [
+		SIXTEENTH_BEATS,
+		.5,
+		1,
+		2,
+		bar,
+		bar * 2,
+		bar * 4,
+		bar * 8,
+		bar * 16,
+		bar * 32
+	].filter((value, index, all) => all.indexOf(value) === index).sort((a, b) => a - b);
+	const coarsest = candidates.at(-1);
+	return candidates.find((interval) => interval * pxPerBeat >= targetPx) ?? coarsest;
+}
+/**
+* The ticks worth rendering, and where they go.
+*
+* Culling is against a **pixel** buffer either side of the viewport, not a beat
+* buffer. The ported version kept fifty beats of margin, which at a tight zoom
+* is a thousand pixels of work nobody will scroll to and at a loose zoom is a
+* few pixels — the one thing a buffer must be is a constant amount of *screen*.
+*
+* @param options - Song length, zoom, and what is on screen.
+*/
+function rulerTicks(options) {
+	const { totalBeats, pxPerBeat, viewport, timeSignature = DEFAULT_TIME_SIGNATURE, targetPx = TICK_TARGET_PX, bufferPx = DEFAULT_BUFFER_PX } = options;
+	const bar = barBeats(timeSignature);
+	const interval = chooseInterval(pxPerBeat, bar, targetPx);
+	const width = Math.max(0, totalBeats * pxPerBeat);
+	const from = viewport === void 0 || pxPerBeat <= 0 ? 0 : Math.max(0, (viewport.offset - bufferPx) / pxPerBeat);
+	const to = viewport === void 0 || pxPerBeat <= 0 ? totalBeats : Math.min(totalBeats, (viewport.offset + viewport.width + bufferPx) / pxPerBeat);
+	const ticks = [];
+	const firstIndex = Math.max(0, Math.floor(from / interval));
+	const lastIndex = Math.floor(to / interval + EPSILON);
+	for (let index = firstIndex; index <= lastIndex; index += 1) {
+		const beat = round(index * interval);
+		const { bar: barNumber, beat: beatInBar, sixteenth } = beatsToMusical(beat, timeSignature);
+		const barStart = beat % bar === 0;
+		ticks.push({
+			beat,
+			left: beat * pxPerBeat,
+			bar: barNumber,
+			beatInBar,
+			sixteenth,
+			barStart,
+			label: barStart ? String(barNumber) : sixteenth === 0 ? String(beatInBar) : `${beatInBar}.${sixteenth}`
+		});
+	}
+	return {
+		interval,
+		width,
+		ticks
+	};
+}
+/** Slack for the "is the last tick exactly on the end?" comparison. */
+const EPSILON = 1e-9;
+/** Trim the float noise a multiplication by a fractional interval leaves. */
+function round(beats) {
+	return Math.round(beats * 1e6) / 1e6;
+}
+//#endregion
+export { TICK_TARGET_PX, chooseInterval, rulerTicks };

package/dist/midi/_time.d.ts

@@ -0,0 +1,107 @@
+//#region src/midi/_time.d.ts
+/**
+ * Musical time: turning a position in beats into the `bars.beats.sixteenths`
+ * a transport displays, and back.
+ *
+ * One convention runs through the whole module and is worth stating once: a
+ * **beat is a quarter note**. That is what every DAW's API reports a song
+ * position in, so it is the unit this system stores and passes around. What the
+ * *display* counts is a different thing — in 6/8 a bar is three quarter notes
+ * but the transport shows six beats — and reconciling those two is precisely
+ * what this module is for.
+ *
+ * The ported implementation assumed 4/4 throughout (`beatsPerBar = numerator`),
+ * which is right for four-four and silently wrong for everything else. Here the
+ * denominator is honoured: {@link barBeats} and {@link beatBeats} answer "how
+ * many quarter notes" and every conversion goes through them.
+ *
+ * @internal Not part of the public API surface beyond the `/midi` barrel.
+ */
+/** How a bar is divided. */
+interface TimeSignature {
+  /** Beats per bar — the top number. */
+  numerator: number;
+  /** Which note gets the beat — the bottom number. */
+  denominator: number;
+}
+/** Four-four, because most of the world is. */
+declare const DEFAULT_TIME_SIGNATURE: TimeSignature;
+/** A sixteenth note, in quarter-note beats. The finest grid this notation shows. */
+declare const SIXTEENTH_BEATS = 0.25;
+/**
+ * The highest bar the field will count to.
+ *
+ * Ported from the original's three-digit bars field. It is a display limit, not
+ * a musical one: 999 bars is over half an hour at 120 BPM, and a four-digit
+ * segment would cost the width the readout needs.
+ */
+declare const MAX_BAR = 999;
+/** A position, as a transport spells it. */
+interface MusicalTime {
+  /** Bar number, counting from 1. */
+  bar: number;
+  /** Beat within the bar, counting from 1. */
+  beat: number;
+  /** Sixteenth within the beat, counting from 0. */
+  sixteenth: number;
+}
+/** Which part of the notation an edit is aimed at. */
+type MusicalSegment = "bars" | "beats" | "sixteenths";
+/** How many quarter-note beats a bar of this signature lasts. */
+declare function barBeats(signature?: TimeSignature): number;
+/** How many quarter-note beats one displayed beat of this signature lasts. */
+declare function beatBeats(signature?: TimeSignature): number;
+/** How many sixteenth notes fit in one displayed beat of this signature. */
+declare function sixteenthsPerBeat(signature?: TimeSignature): number;
+/**
+ * A position in quarter-note beats, spelled out.
+ *
+ * Quantised to the sixteenth grid on the way in, because the notation has three
+ * segments and no fourth: reporting `1.1.0` for a position that is actually a
+ * thirty-second late would be a lie the field could not correct.
+ *
+ * @param beats - Position in quarter-note beats. Negative clamps to the start.
+ * @param signature - The signature in force.
+ */
+declare function beatsToMusical(beats: number, signature?: TimeSignature): MusicalTime;
+/**
+ * A spelled-out position back in quarter-note beats.
+ *
+ * @param time - The position as the transport spells it.
+ * @param signature - The signature in force.
+ */
+declare function musicalToBeats(time: MusicalTime, signature?: TimeSignature): number;
+/** The transport's own notation: `002.1.1`, bars padded to three digits. */
+declare function formatMusicalTime(time: MusicalTime): string;
+/**
+ * Nudge one segment, carrying into the ones above it.
+ *
+ * Done in sixteenths rather than by mutating the segment, which is what makes
+ * the carry fall out for free: the fourth beat of a bar plus one beat is the
+ * first beat of the next bar because that is what the arithmetic says, not
+ * because three nested `if` statements said so (the ported version needed
+ * eight branches for this, one per overflow case, and had no way to express
+ * "one bar" in a signature where a bar is not four beats).
+ *
+ * @param beats - Current position in quarter-note beats.
+ * @param segment - Which segment the caller is stepping.
+ * @param delta - How many of that segment, positive or negative.
+ * @param signature - The signature in force.
+ * @returns The new position, never below zero and never past {@link MAX_BAR}.
+ */
+declare function stepMusicalTime(beats: number, segment: MusicalSegment, delta: number, signature?: TimeSignature): number;
+/**
+ * Set one segment to a typed value, leaving the others alone.
+ *
+ * Each segment is clamped to what it can hold — bars to 1…{@link MAX_BAR},
+ * beats to the signature's count, sixteenths to the beat's — so a typo produces
+ * a legal position rather than a rejected keystroke.
+ *
+ * @param beats - Current position in quarter-note beats.
+ * @param segment - Which segment the caller typed into.
+ * @param value - What they typed.
+ * @param signature - The signature in force.
+ */
+declare function setMusicalSegment(beats: number, segment: MusicalSegment, value: number, signature?: TimeSignature): number;
+//#endregion
+export { DEFAULT_TIME_SIGNATURE, MAX_BAR, MusicalSegment, MusicalTime, SIXTEENTH_BEATS, TimeSignature, barBeats, beatBeats, beatsToMusical, formatMusicalTime, musicalToBeats, setMusicalSegment, sixteenthsPerBeat, stepMusicalTime };

package/dist/midi/_time.js

@@ -0,0 +1,130 @@
+//#region src/midi/_time.ts
+/** Four-four, because most of the world is. */
+const DEFAULT_TIME_SIGNATURE = {
+	numerator: 4,
+	denominator: 4
+};
+/** A sixteenth note, in quarter-note beats. The finest grid this notation shows. */
+const SIXTEENTH_BEATS = .25;
+/**
+* The highest bar the field will count to.
+*
+* Ported from the original's three-digit bars field. It is a display limit, not
+* a musical one: 999 bars is over half an hour at 120 BPM, and a four-digit
+* segment would cost the width the readout needs.
+*/
+const MAX_BAR = 999;
+/** How many quarter-note beats a bar of this signature lasts. */
+function barBeats(signature = DEFAULT_TIME_SIGNATURE) {
+	return signature.numerator * beatBeats(signature);
+}
+/** How many quarter-note beats one displayed beat of this signature lasts. */
+function beatBeats(signature = DEFAULT_TIME_SIGNATURE) {
+	return 4 / signature.denominator;
+}
+/** How many sixteenth notes fit in one displayed beat of this signature. */
+function sixteenthsPerBeat(signature = DEFAULT_TIME_SIGNATURE) {
+	return beatBeats(signature) / SIXTEENTH_BEATS;
+}
+/**
+* A position in quarter-note beats, spelled out.
+*
+* Quantised to the sixteenth grid on the way in, because the notation has three
+* segments and no fourth: reporting `1.1.0` for a position that is actually a
+* thirty-second late would be a lie the field could not correct.
+*
+* @param beats - Position in quarter-note beats. Negative clamps to the start.
+* @param signature - The signature in force.
+*/
+function beatsToMusical(beats, signature = DEFAULT_TIME_SIGNATURE) {
+	const grid = quantise(beats);
+	const bar = Math.floor(grid / barBeats(signature));
+	const inBar = grid - bar * barBeats(signature);
+	const beat = Math.floor(inBar / beatBeats(signature));
+	const inBeat = inBar - beat * beatBeats(signature);
+	return {
+		bar: bar + 1,
+		beat: beat + 1,
+		sixteenth: Math.round(inBeat / SIXTEENTH_BEATS)
+	};
+}
+/**
+* A spelled-out position back in quarter-note beats.
+*
+* @param time - The position as the transport spells it.
+* @param signature - The signature in force.
+*/
+function musicalToBeats(time, signature = DEFAULT_TIME_SIGNATURE) {
+	return round((time.bar - 1) * barBeats(signature) + (time.beat - 1) * beatBeats(signature) + time.sixteenth * SIXTEENTH_BEATS);
+}
+/** The transport's own notation: `002.1.1`, bars padded to three digits. */
+function formatMusicalTime(time) {
+	return `${String(time.bar).padStart(3, "0")}.${time.beat}.${time.sixteenth}`;
+}
+/**
+* Nudge one segment, carrying into the ones above it.
+*
+* Done in sixteenths rather than by mutating the segment, which is what makes
+* the carry fall out for free: the fourth beat of a bar plus one beat is the
+* first beat of the next bar because that is what the arithmetic says, not
+* because three nested `if` statements said so (the ported version needed
+* eight branches for this, one per overflow case, and had no way to express
+* "one bar" in a signature where a bar is not four beats).
+*
+* @param beats - Current position in quarter-note beats.
+* @param segment - Which segment the caller is stepping.
+* @param delta - How many of that segment, positive or negative.
+* @param signature - The signature in force.
+* @returns The new position, never below zero and never past {@link MAX_BAR}.
+*/
+function stepMusicalTime(beats, segment, delta, signature = DEFAULT_TIME_SIGNATURE) {
+	const step = segmentBeats(segment, signature);
+	return clampToTransport(quantise(beats) + delta * step, signature);
+}
+/**
+* Set one segment to a typed value, leaving the others alone.
+*
+* Each segment is clamped to what it can hold — bars to 1…{@link MAX_BAR},
+* beats to the signature's count, sixteenths to the beat's — so a typo produces
+* a legal position rather than a rejected keystroke.
+*
+* @param beats - Current position in quarter-note beats.
+* @param segment - Which segment the caller typed into.
+* @param value - What they typed.
+* @param signature - The signature in force.
+*/
+function setMusicalSegment(beats, segment, value, signature = DEFAULT_TIME_SIGNATURE) {
+	return clampToTransport(musicalToBeats({
+		...beatsToMusical(beats, signature),
+		...segment === "bars" ? { bar: clamp(value, 1, 999) } : null,
+		...segment === "beats" ? { beat: clamp(value, 1, signature.numerator) } : null,
+		...segment === "sixteenths" ? { sixteenth: clamp(value, 0, sixteenthsPerBeat(signature) - 1) } : null
+	}, signature), signature);
+}
+/** How many quarter-note beats one step of a segment is worth. */
+function segmentBeats(segment, signature) {
+	if (segment === "bars") return barBeats(signature);
+	if (segment === "beats") return beatBeats(signature);
+	return SIXTEENTH_BEATS;
+}
+/** Snap to the sixteenth grid and drop the float noise a division leaves. */
+function quantise(beats) {
+	if (!Number.isFinite(beats) || beats <= 0) return 0;
+	return round(Math.round(beats / SIXTEENTH_BEATS) * SIXTEENTH_BEATS);
+}
+/** Keep a position inside the transport's range. */
+function clampToTransport(beats, signature) {
+	const last = 999 * barBeats(signature) - SIXTEENTH_BEATS;
+	return Math.min(last, Math.max(0, round(beats)));
+}
+/** Trim the float noise repeated addition accumulates. */
+function round(beats) {
+	return Math.round(beats * 1e6) / 1e6;
+}
+/** Clamp an integer segment, tolerating a typo that is not a number at all. */
+function clamp(value, low, high) {
+	if (!Number.isFinite(value)) return low;
+	return Math.min(high, Math.max(low, Math.round(value)));
+}
+//#endregion
+export { DEFAULT_TIME_SIGNATURE, MAX_BAR, SIXTEENTH_BEATS, barBeats, beatBeats, beatsToMusical, formatMusicalTime, musicalToBeats, setMusicalSegment, sixteenthsPerBeat, stepMusicalTime };

package/dist/midi/index.d.ts

@@ -0,0 +1,9 @@
+import { BLACK_KEY_PX, KeyboardLayout, MIDI_NOTES, NOTE_NAMES, NoteRange, OCTAVE_PX, PianoKey, WHITE_KEY_PX, isBlackKey, keyboardLayout, keyboardWindow, noteAtOffset, noteName } from "./_notes.js";
+import { DEFAULT_TIME_SIGNATURE, MAX_BAR, MusicalSegment, MusicalTime, SIXTEENTH_BEATS, TimeSignature, barBeats, beatBeats, beatsToMusical, formatMusicalTime, musicalToBeats, setMusicalSegment, sixteenthsPerBeat, stepMusicalTime } from "./_time.js";
+import { RulerTick, RulerTicks, RulerTicksOptions, RulerViewport, TICK_TARGET_PX, chooseInterval, rulerTicks } from "./_ruler.js";
+import { MusicalTimeInput, MusicalTimeInputProps } from "./musical-time-input.js";
+import { PianoKeyboard, PianoKeyboardProps } from "./piano-keyboard.js";
+import { SPECTRUM_WIDTH, SpectrumMode, SpectrumVisualizer, SpectrumVisualizerProps } from "./spectrum-visualizer.js";
+import { ThresholdRail, ThresholdRailProps, ThresholdTone } from "./threshold-rail.js";
+import { LoopRegion, RulerMarker, TimelineRuler, TimelineRulerProps } from "./timeline-ruler.js";
+export { BLACK_KEY_PX, DEFAULT_TIME_SIGNATURE, type KeyboardLayout, type LoopRegion, MAX_BAR, MIDI_NOTES, type MusicalSegment, type MusicalTime, MusicalTimeInput, type MusicalTimeInputProps, NOTE_NAMES, type NoteRange, OCTAVE_PX, type PianoKey, PianoKeyboard, type PianoKeyboardProps, type RulerMarker, type RulerTick, type RulerTicks, type RulerTicksOptions, type RulerViewport, SIXTEENTH_BEATS, SPECTRUM_WIDTH, type SpectrumMode, SpectrumVisualizer, type SpectrumVisualizerProps, TICK_TARGET_PX, ThresholdRail, type ThresholdRailProps, type ThresholdTone, type TimeSignature, TimelineRuler, type TimelineRulerProps, WHITE_KEY_PX, barBeats, beatBeats, beatsToMusical, chooseInterval, formatMusicalTime, isBlackKey, keyboardLayout, keyboardWindow, musicalToBeats, noteAtOffset, noteName, rulerTicks, setMusicalSegment, sixteenthsPerBeat, stepMusicalTime };

package/dist/midi/index.js

@@ -0,0 +1,9 @@
+import { BLACK_KEY_PX, MIDI_NOTES, NOTE_NAMES, OCTAVE_PX, WHITE_KEY_PX, isBlackKey, keyboardLayout, keyboardWindow, noteAtOffset, noteName } from "./_notes.js";
+import { DEFAULT_TIME_SIGNATURE, MAX_BAR, SIXTEENTH_BEATS, barBeats, beatBeats, beatsToMusical, formatMusicalTime, musicalToBeats, setMusicalSegment, sixteenthsPerBeat, stepMusicalTime } from "./_time.js";
+import { TICK_TARGET_PX, chooseInterval, rulerTicks } from "./_ruler.js";
+import { MusicalTimeInput } from "./musical-time-input.js";
+import { PianoKeyboard } from "./piano-keyboard.js";
+import { SPECTRUM_WIDTH, SpectrumVisualizer } from "./spectrum-visualizer.js";
+import { ThresholdRail } from "./threshold-rail.js";
+import { TimelineRuler } from "./timeline-ruler.js";
+export { BLACK_KEY_PX, DEFAULT_TIME_SIGNATURE, MAX_BAR, MIDI_NOTES, MusicalTimeInput, NOTE_NAMES, OCTAVE_PX, PianoKeyboard, SIXTEENTH_BEATS, SPECTRUM_WIDTH, SpectrumVisualizer, TICK_TARGET_PX, ThresholdRail, TimelineRuler, WHITE_KEY_PX, barBeats, beatBeats, beatsToMusical, chooseInterval, formatMusicalTime, isBlackKey, keyboardLayout, keyboardWindow, musicalToBeats, noteAtOffset, noteName, rulerTicks, setMusicalSegment, sixteenthsPerBeat, stepMusicalTime };

package/dist/midi/musical-time-input.d.ts

@@ -0,0 +1,48 @@
+import { FormControlSize } from "../forms/_chassis.js";
+import { TimeSignature } from "./_time.js";
+import * as React from "react";
+//#region src/midi/musical-time-input.d.ts
+interface MusicalTimeInputProps extends Omit<React.ComponentPropsWithoutRef<"div">, "onChange" | "defaultValue"> {
+  /** The position, in quarter-note beats. Always controlled. */
+  value: number;
+  /** Called with the new position after every edit. */
+  onChange: (beats: number) => void;
+  /** The signature the display counts in. Defaults to 4/4. */
+  timeSignature?: TimeSignature;
+  /** Rung of the control ladder. Defaults to `"md"`. */
+  size?: FormControlSize;
+  /** Print the total in beats after the segments. Defaults to `true`. */
+  total?: boolean;
+  /** Refuse every edit. */
+  disabled?: boolean;
+  /** Accessible name for the field as a whole. Defaults to `"Musical time"`. */
+  label?: string;
+}
+/**
+ * `bars.beats.sixteenths` — a position in a song, typed the way a song is
+ * counted.
+ *
+ * A number field would ask for 4.25 and mean "bar 2, beat 1, one sixteenth in",
+ * which is a conversion the musician has to do in their head every time. This
+ * field does it instead: three segments, each one stepping in its own musical
+ * unit, and the carry between them handled by the arithmetic rather than by the
+ * typist (bar 1 beat 4 plus one beat is bar 2 beat 1).
+ *
+ * Three interactions, because the three are used at different moments: **arrows**
+ * for a nudge while listening, **scroll** for a sweep, and **typing** for a
+ * position read off a cue sheet. Tab moves between the segments on its own — the
+ * ported version intercepted Tab to reimplement the focus order the browser
+ * already had, which broke Shift+Tab out of the field entirely.
+ *
+ * The scroll gesture is bound natively rather than through React's `onWheel`,
+ * because React attaches wheel listeners passively at the root: `preventDefault`
+ * there is a no-op and the page scrolls away underneath the edit.
+ *
+ * @example
+ * <MusicalTimeInput value={beats} onChange={setBeats} />
+ * @example
+ * <MusicalTimeInput value={beats} onChange={setBeats} timeSignature={{ numerator: 6, denominator: 8 }} />
+ */
+declare const MusicalTimeInput: React.ForwardRefExoticComponent<MusicalTimeInputProps & React.RefAttributes<HTMLDivElement>>;
+//#endregion
+export { MusicalTimeInput, MusicalTimeInputProps };

package/dist/midi/musical-time-input.js

@@ -0,0 +1,154 @@
+"use client";
+import { cn } from "../lib/cn.js";
+import { bareControlClasses, controlGroupFocusClasses, controlVariants } from "../forms/_chassis.js";
+import { DEFAULT_TIME_SIGNATURE, beatsToMusical, setMusicalSegment, stepMusicalTime } from "./_time.js";
+import * as React from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+//#region src/midi/musical-time-input.tsx
+/** The three segments, in reading order, with the width each needs. */
+const SEGMENTS = [
+	{
+		segment: "bars",
+		label: "Bars",
+		width: "w-[3ch]"
+	},
+	{
+		segment: "beats",
+		label: "Beats",
+		width: "w-[2ch]"
+	},
+	{
+		segment: "sixteenths",
+		label: "Sixteenths",
+		width: "w-[2ch]"
+	}
+];
+/** What a segment shows when it is not being typed into. */
+function segmentText(time, segment) {
+	if (segment === "bars") return String(time.bar).padStart(3, "0");
+	if (segment === "beats") return String(time.beat);
+	return String(time.sixteenth);
+}
+/**
+* `bars.beats.sixteenths` — a position in a song, typed the way a song is
+* counted.
+*
+* A number field would ask for 4.25 and mean "bar 2, beat 1, one sixteenth in",
+* which is a conversion the musician has to do in their head every time. This
+* field does it instead: three segments, each one stepping in its own musical
+* unit, and the carry between them handled by the arithmetic rather than by the
+* typist (bar 1 beat 4 plus one beat is bar 2 beat 1).
+*
+* Three interactions, because the three are used at different moments: **arrows**
+* for a nudge while listening, **scroll** for a sweep, and **typing** for a
+* position read off a cue sheet. Tab moves between the segments on its own — the
+* ported version intercepted Tab to reimplement the focus order the browser
+* already had, which broke Shift+Tab out of the field entirely.
+*
+* The scroll gesture is bound natively rather than through React's `onWheel`,
+* because React attaches wheel listeners passively at the root: `preventDefault`
+* there is a no-op and the page scrolls away underneath the edit.
+*
+* @example
+* <MusicalTimeInput value={beats} onChange={setBeats} />
+* @example
+* <MusicalTimeInput value={beats} onChange={setBeats} timeSignature={{ numerator: 6, denominator: 8 }} />
+*/
+const MusicalTimeInput = React.forwardRef(function MusicalTimeInput({ className, value, onChange, timeSignature = DEFAULT_TIME_SIGNATURE, size = "md", total = true, disabled = false, label = "Musical time", ...elementProps }, ref) {
+	/** The segment being typed into, and the raw text in it. */
+	const [draft, setDraft] = React.useState(null);
+	const time = beatsToMusical(value, timeSignature);
+	const step = React.useCallback((segment, delta) => {
+		if (disabled) return;
+		const next = stepMusicalTime(value, segment, delta, timeSignature);
+		if (next !== value) onChange(next);
+	}, [
+		disabled,
+		onChange,
+		timeSignature,
+		value
+	]);
+	const type = (segment, text) => {
+		if (disabled) return;
+		setDraft({
+			segment,
+			text
+		});
+		const parsed = Number.parseInt(text, 10);
+		if (Number.isNaN(parsed)) return;
+		const next = setMusicalSegment(value, segment, parsed, timeSignature);
+		if (next !== value) onChange(next);
+	};
+	return /* @__PURE__ */ jsxs("div", {
+		ref,
+		role: "group",
+		"aria-label": label,
+		"data-slot": "musical-time-input",
+		className: cn(controlVariants({ size }), "inline-flex w-auto items-center gap-px", controlGroupFocusClasses, disabled && "opacity-40", className),
+		...elementProps,
+		children: [SEGMENTS.map(({ segment, label: segmentLabel, width }, index) => /* @__PURE__ */ jsxs(React.Fragment, { children: [index === 0 ? null : /* @__PURE__ */ jsx("span", {
+			"aria-hidden": "true",
+			"data-slot": "musical-time-separator",
+			className: "text-fg-subtle",
+			children: "."
+		}), /* @__PURE__ */ jsx(TimeSegmentField, {
+			segment,
+			label: segmentLabel,
+			width,
+			disabled,
+			text: draft?.segment === segment ? draft.text : segmentText(time, segment),
+			onStep: step,
+			onType: type,
+			onSettle: () => setDraft(null)
+		})] }, segment)), total ? /* @__PURE__ */ jsx("span", {
+			"data-slot": "musical-time-total",
+			className: "ml-(--cue-space-2) text-(length:--cue-text-micro) text-fg-subtle tabular-nums",
+			children: `${value.toFixed(2)} beats`
+		}) : null]
+	});
+});
+/** One segment of the notation: a text box that also steps. */
+function TimeSegmentField({ segment, label, width, text, disabled, onStep, onType, onSettle }) {
+	const ref = React.useRef(null);
+	const stepRef = React.useRef(onStep);
+	stepRef.current = onStep;
+	React.useEffect(() => {
+		const element = ref.current;
+		if (element === null || disabled) return;
+		const onWheel = (event) => {
+			if (event.deltaY === 0) return;
+			event.preventDefault();
+			stepRef.current(segment, event.deltaY < 0 ? 1 : -1);
+		};
+		element.addEventListener("wheel", onWheel, { passive: false });
+		return () => element.removeEventListener("wheel", onWheel);
+	}, [disabled, segment]);
+	return /* @__PURE__ */ jsx("input", {
+		ref,
+		type: "text",
+		inputMode: "numeric",
+		autoComplete: "off",
+		"data-slot": "musical-time-segment",
+		"data-segment": segment,
+		"aria-label": label,
+		value: text,
+		disabled,
+		onChange: (event) => onType(segment, event.currentTarget.value),
+		onBlur: onSettle,
+		onKeyDown: (event) => {
+			if (event.key === "ArrowUp") {
+				event.preventDefault();
+				onStep(segment, 1);
+			} else if (event.key === "ArrowDown") {
+				event.preventDefault();
+				onStep(segment, -1);
+			} else if (event.key === "Enter") {
+				event.preventDefault();
+				onSettle();
+			}
+		},
+		className: cn(bareControlClasses, width, "flex-none text-center tabular-nums")
+	});
+}
+//#endregion
+export { MusicalTimeInput };

package/dist/midi/piano-keyboard.d.ts

@@ -0,0 +1,50 @@
+import { NoteRange } from "./_notes.js";
+import * as React from "react";
+//#region src/midi/piano-keyboard.d.ts
+interface PianoKeyboardProps extends Omit<React.ComponentPropsWithoutRef<"div">, "children" | "onChange"> {
+  /** The selected range. Use with `onRangeChange` for a controlled widget. */
+  range?: NoteRange;
+  /** Initial range for an uncontrolled widget. Defaults to C2–C4. */
+  defaultRange?: NoteRange;
+  /** Called with the range each edit produces. */
+  onRangeChange?: (range: NoteRange) => void;
+  /** How many octaves to draw. Defaults to `3`. */
+  octaves?: number;
+  /** Notes sounding right now, painted solid. */
+  highlight?: readonly number[];
+  /** White-key height in px at the 16px root, emitted as `rem`. Defaults to `48`. */
+  keyHeight?: number;
+  /** What the range is *of*. Names the group and both markers. Defaults to `"Note range"`. */
+  label?: string;
+  /** Print the range and its size under the board. Defaults to `true`. */
+  readout?: boolean;
+  /** Refuse every edit. The board still draws. */
+  disabled?: boolean;
+}
+/**
+ * A piano keyboard as a range control: drag the markers, or arrow the edges.
+ *
+ * Ported from ableton-sync's note-range picker, geometry intact — 16px whites,
+ * 10px blacks over the seams — and rebuilt around three things the original did
+ * not have:
+ *
+ * 1. **The edges are sliders.** The port moved its markers with `mousedown` and
+ *    a window listener, which means no keyboard, no screen reader and no touch.
+ *    Here each marker is a `role="slider"` announcing its note by name, so
+ *    "set the low end to C2" is reachable without a pointer.
+ * 2. **The board holds still while you drag.** The window is centred on the
+ *    selection, so moving an edge moves the window, which moves the note under
+ *    the cursor — the port's markers slid away from the pointer mid-drag. The
+ *    window is frozen for the length of a gesture instead.
+ * 3. **It is drawn in console materials, not in white and black.** A photo of a
+ *    piano inverts in a light theme; a `surface-3` white key and a
+ *    `--cue-data-ground` black key read the same in both. The information — what
+ *    is in range, what is sounding — is carried by the accent, which is the only
+ *    thing here that a theme is allowed to move.
+ *
+ * @example
+ * <PianoKeyboard range={range} onRangeChange={setRange} highlight={sounding} />
+ */
+declare const PianoKeyboard: React.ForwardRefExoticComponent<PianoKeyboardProps & React.RefAttributes<HTMLDivElement>>;
+//#endregion
+export { PianoKeyboard, PianoKeyboardProps };