@5voltfx/design-system 0.1.1 → 0.2.0

package/dist/components/_shared/useDetentTravel.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Ease-out-back with a deliberately low overshoot. The small bounce is what
+ * reads as *mechanical* — a cursor dropping into a notch — rather than bouncy.
+ * Copied from the design artboards; do not retune without redrawing them.
+ *
+ * @param {number} x - Normalized time, 0…1.
+ * @returns {number}
+ */
+export function easeBack(x: number): number;
+/**
+ * @typedef {object} DetentTravel
+ * @property {number} pos - Continuous travel, 0…count-1. Quantized to
+ *   quarter detents while dragging.
+ * @property {number} station - Committed integer station index.
+ * @property {boolean} dragging
+ * @property {boolean} settling - True while the release animation runs.
+ * @property {(i: number, ms?: number) => void} goTo - Animate to a station.
+ * @property {(delta: number) => void} step - Move by whole stations.
+ * @property {(raw: number) => void} track - Feed raw travel during a drag.
+ * @property {() => void} begin - Start a drag.
+ * @property {() => void} release - Settle to the nearest station.
+ */
+/**
+ * The detent state machine shared by every slide-rule navigation.
+ *
+ * Travel is quantized to quarter-pitch detents *while dragging*, so the
+ * mechanism visibly ratchets between stations, but releasing always settles
+ * onto a station — navigation never rests in a null state. `onChange` fires
+ * once, on arrival, and never mid-drag.
+ *
+ * @param {object} options
+ * @param {number} options.count - Number of stations.
+ * @param {number} [options.value] - Controlled station index.
+ * @param {number} [options.defaultValue] - Initial station (uncontrolled).
+ * @param {(station: number) => void} [options.onChange] - Fires on commit.
+ * @param {number} [options.subdivisions] - Detents per station gap.
+ * @param {number} [options.settleMs] - Release animation duration.
+ * @param {() => void} [options.onDetentCross] - Fires per detent crossed
+ *   while dragging; drives the pawl kick and any tick feedback.
+ * @returns {DetentTravel}
+ */
+export function useDetentTravel({ count, value, defaultValue, onChange, subdivisions, settleMs, onDetentCross, }?: {
+    count: number;
+    value?: number | undefined;
+    defaultValue?: number | undefined;
+    onChange?: ((station: number) => void) | undefined;
+    subdivisions?: number | undefined;
+    settleMs?: number | undefined;
+    onDetentCross?: (() => void) | undefined;
+}): DetentTravel;
+export type DetentTravel = {
+    /**
+     * - Continuous travel, 0…count-1. Quantized to
+     * quarter detents while dragging.
+     */
+    pos: number;
+    /**
+     * - Committed integer station index.
+     */
+    station: number;
+    dragging: boolean;
+    /**
+     * - True while the release animation runs.
+     */
+    settling: boolean;
+    /**
+     * - Animate to a station.
+     */
+    goTo: (i: number, ms?: number) => void;
+    /**
+     * - Move by whole stations.
+     */
+    step: (delta: number) => void;
+    /**
+     * - Feed raw travel during a drag.
+     */
+    track: (raw: number) => void;
+    /**
+     * - Start a drag.
+     */
+    begin: () => void;
+    /**
+     * - Settle to the nearest station.
+     */
+    release: () => void;
+};
+//# sourceMappingURL=useDetentTravel.d.ts.map

package/dist/components/_shared/useDetentTravel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useDetentTravel.d.ts","sourceRoot":"","sources":["../../../src/components/_shared/useDetentTravel.js"],"names":[],"mappings":"AAGA;;;;;;;GAOG;AACH,4BAHW,MAAM,GACJ,MAAM,CAMlB;AAID;;;;;;;;;;;;GAYG;AAEH;;;;;;;;;;;;;;;;;;GAkBG;AACH,mHAVG;IAAwB,KAAK,EAArB,MAAM;IACW,KAAK;IACL,YAAY;IACO,QAAQ,cAAlC,MAAM,KAAK,IAAI;IACR,YAAY;IACZ,QAAQ;IACJ,aAAa,UAA5B,IAAI;CAElB,GAAU,YAAY,CA4IxB;;;;;;SAzKa,MAAM;;;;aAEN,MAAM;cACN,OAAO;;;;cACP,OAAO;;;;UACP,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,KAAK,IAAI;;;;UAChC,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI;;;;WACvB,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI;;;;WACrB,MAAM,IAAI;;;;aACV,MAAM,IAAI"}

package/dist/components/_shared/usePointerDrag.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Pointer dragging that does not break clicks on nested elements.
+ *
+ * Deliberately avoids `setPointerCapture`: capturing on a container (the
+ * slide, the disc) redirects the subsequent `click` away from the station link
+ * inside it, so nav items stop responding. Window-level listeners plus a small
+ * movement threshold give the same drag behaviour and leave `click` intact.
+ * `pointerdown` is likewise never `preventDefault`ed, because that suppresses
+ * focus.
+ *
+ * @param {import("react").RefObject<Element>} ref - The drag handle.
+ * @param {object} handlers
+ * @param {(e: PointerEvent) => void} [handlers.onBegin]
+ * @param {(e: PointerEvent) => void} [handlers.onMove] - Only after threshold.
+ * @param {(e: PointerEvent, wasTap: boolean) => void} [handlers.onEnd]
+ * @param {number} [handlers.threshold] - Pixels of travel before a drag starts.
+ */
+export function usePointerDrag(ref: import("react").RefObject<Element>, { onBegin, onMove, onEnd, threshold }?: {
+    onBegin?: ((e: PointerEvent) => void) | undefined;
+    onMove?: ((e: PointerEvent) => void) | undefined;
+    onEnd?: ((e: PointerEvent, wasTap: boolean) => void) | undefined;
+    threshold?: number | undefined;
+}): void;
+//# sourceMappingURL=usePointerDrag.d.ts.map

package/dist/components/_shared/usePointerDrag.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usePointerDrag.d.ts","sourceRoot":"","sources":["../../../src/components/_shared/usePointerDrag.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;GAgBG;AACH,oCAPW,OAAO,OAAO,EAAE,SAAS,CAAC,OAAO,CAAC,0CAE1C;IAA6C,OAAO,QAAxC,YAAY,KAAK,IAAI;IACY,MAAM,QAAvC,YAAY,KAAK,IAAI;IAC6B,KAAK,QAAvD,YAAY,UAAU,OAAO,KAAK,IAAI;IACxB,SAAS;CACrC,QA4CA"}

package/dist/components/_shared/useReducedMotion.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Tracks `prefers-reduced-motion: reduce`, live.
+ *
+ * @returns {boolean} True when the user has asked for reduced motion.
+ */
+export function useReducedMotion(): boolean;
+//# sourceMappingURL=useReducedMotion.d.ts.map

package/dist/components/_shared/useReducedMotion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useReducedMotion.d.ts","sourceRoot":"","sources":["../../../src/components/_shared/useReducedMotion.js"],"names":[],"mappings":"AAcA;;;;GAIG;AACH,oCAFa,OAAO,CAInB"}

package/dist/components/_shared/validateStationCount.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Clamps a station count to the range the slide-rule navigations stay legible
+ * in, warning once per render in development. Never throws — a nav that
+ * renders too many items is a design problem, not a crash.
+ *
+ * @param {number} n - Requested station count.
+ * @param {string} component - Component name, for the warning.
+ * @returns {number} The count to actually render.
+ */
+export function validateStationCount(n: number, component: string): number;
+export const MIN_STATIONS: 2;
+export const MAX_STATIONS: 8;
+//# sourceMappingURL=validateStationCount.d.ts.map

package/dist/components/_shared/validateStationCount.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validateStationCount.d.ts","sourceRoot":"","sources":["../../../src/components/_shared/validateStationCount.js"],"names":[],"mappings":"AAOA;;;;;;;;GAQG;AACH,wCAJW,MAAM,aACN,MAAM,GACJ,MAAM,CAmBlB;AAjCD,2BAA4B,CAAC,CAAC;AAC9B,2BAA4B,CAAC,CAAC"}