@fiestaboard/ui 2.0.3 → 2.1.1

package/dist/components/board/board-display.d.ts

@@ -1,4 +1,61 @@
 import { type DeviceType } from "../../lib/board-dimensions";
+/**
+ * Named flap cadences, in milliseconds per character step.
+ *
+ * Presets rather than a bare number because "how fast does the board flip" is a
+ * product decision with a handful of good answers, and the FiestaBoard app may
+ * expose it as a user setting — a name survives a settings screen, `92` does
+ * not. They are named for what they do on screen, with one exception:
+ * `hardware` is the only value actually derived from the device, so it is the
+ * only one that claims to be. Anything else goes through the `{ durationMs }`
+ * escape hatch.
+ */
+export declare const FLAP_SPEED_PRESETS: {
+    /**
+     * 16ms — the hardware cadence (60 RPM × 62 flaps ≈ 16.1ms/flap). Roughly one
+     * frame per glyph at 60Hz: the cascade strobes and is unreadable until it
+     * settles. Offered because it is the honest hardware figure, not because it
+     * is a good default.
+     */
+    readonly hardware: 16;
+    /** 48ms — quicker than default; glyphs are still resolvable mid-cascade. */
+    readonly quick: 48;
+    /** 80ms — the default, and what FiestaBoard has always shipped. */
+    readonly standard: 80;
+    /** 130ms — a slow, deliberate flip for large or ambient displays. */
+    readonly relaxed: 130;
+};
+export type FlapSpeedPreset = keyof typeof FLAP_SPEED_PRESETS;
+/** A named cadence, or an explicit per-step duration in milliseconds. */
+export type FlapSpeed = FlapSpeedPreset | {
+    readonly durationMs: number;
+};
+/** Resolve a {@link FlapSpeed} to a whole number of milliseconds per step. */
+export declare function resolveFlapSpeed(speed: FlapSpeed): number;
+export interface FlapTiming {
+    /** Total duration of one character step. */
+    stepMs: number;
+    /** Top leaf falls over `[0, topMs)`. */
+    topMs: number;
+    /** Bottom leaf rises over `[bottomDelayMs, stepMs)`. */
+    bottomMs: number;
+    bottomDelayMs: number;
+}
+/**
+ * Split a step into its two leaf phases.
+ *
+ * The leaf that falls *is* the leaf that lands, so exactly one leaf may be in
+ * motion at any instant: the top runs `[0, topMs)`, the bottom runs
+ * `[topMs, stepMs)`, and the two tile the step exactly. Before issue #177 the
+ * bottom leaf started at 0.35 × step while the top ran for 0.55 × step, so both
+ * leaves moved for 20% of every step and the tile visibly split open at the
+ * midpoint — something a physical module cannot do. Handing off at the instant
+ * the top leaf lands is the whole fix.
+ *
+ * `bottomMs` is `stepMs - topMs` rather than a second rounding, so odd step
+ * durations still tile exactly instead of leaving a 1ms gap or overlap.
+ */
+export declare function deriveFlapTiming(stepMs: number): FlapTiming;
 export interface BoardDisplayProps {
     message: string | null;
     isLoading?: boolean;
@@ -22,9 +79,15 @@ export interface BoardDisplayProps {
      *  draw surface's hit-testing to reject them one by one. */
     emitCellMetadata?: boolean;
     /** Run the split-flap animation. In the app this is wired to the user's
-     *  board-animation setting and reduce-motion preference; when false, tiles
-     *  snap straight to their target characters. */
+     *  board-animation setting; when false, tiles snap straight to their target
+     *  characters. `prefers-reduced-motion: reduce` forces the same behaviour
+     *  regardless of this prop — see the reduced-motion note in BoardDisplay. */
     animationsEnabled?: boolean;
+    /** How fast a tile advances one character: a named cadence
+     *  (`"standard"` — the default 80ms — `"quick"`, `"relaxed"`, or the
+     *  hardware's own `"hardware"`), or `{ durationMs }` for anything else.
+     *  Drives the leaf animations and the loading cadence together. */
+    flapSpeed?: FlapSpeed;
     /** Accessible label while `isLoading` is true. */
     loadingLabel?: string;
     /** Accessible label when the board has no message. */
@@ -32,4 +95,4 @@ export interface BoardDisplayProps {
     /** Builds the accessible label for a shown message (color markup already stripped). */
     messageLabel?: (message: string) => string;
 }
-export declare const BoardDisplay: import("react").MemoExoticComponent<({ message, isLoading, size, className, boardType, deviceType, isStatic, notesWide, notesTall, emitCellMetadata, animationsEnabled, loadingLabel, emptyLabel, messageLabel, }: BoardDisplayProps) => import("react").JSX.Element>;
+export declare const BoardDisplay: import("react").MemoExoticComponent<({ message, isLoading, size, className, boardType, deviceType, isStatic, notesWide, notesTall, emitCellMetadata, animationsEnabled, flapSpeed, loadingLabel, emptyLabel, messageLabel, }: BoardDisplayProps) => import("react").JSX.Element>;