@fairgarden/design 0.1.0-alpha.0 → 0.1.0-alpha.2

package/foundations/outline-morph/morphEngine.d.ts

@@ -0,0 +1,219 @@
+/** The attribute the popup carries while the overlay draws its frame. */
+export declare const OUTLINE_MORPH_ATTRIBUTE = "data-outline-morph";
+/**
+ * The app-wide (and per-subtree) switch: `none` on the trigger or the popup
+ * (inherited, so `:root` turns every morph off) leaves every popup its own
+ * open and close. Read at each open and close.
+ */
+export declare const OUTLINE_MORPH_PROPERTY = "--fgd-outline-morph";
+/**
+ * The popup's attribute while an open waits for its placement (a frame or
+ * two, at most PLACEMENT_FRAMES): the foundation's CSS holds the popup
+ * clipped away meanwhile (still focusable, as Base UI moves focus in during
+ * the wait), a discrete hold, so it never paints unclipped before the morph
+ * starts [D196]. A timeout removes it and the popup shows at once.
+ */
+export declare const OUTLINE_MORPH_PENDING_ATTRIBUTE = "data-outline-morph-pending";
+/** Durations in ms: `open` grows the outline into the frame, `close` is the faster way back. */
+export type OutlineMorphDuration = {
+    open: number;
+    close: number;
+};
+/**
+ * How the trigger draws its focus ring, so the engine knows when it shows:
+ * - `focus-visible`: on the trigger itself while it matches `:focus-visible`
+ *   (buttons, menu triggers, the Select trigger). Focus moves into the popup
+ *   while it is open and comes back on close.
+ * - `focus-within`: on the trigger (a field's box) whenever anything inside
+ *   it holds focus, pointer focus included (Combobox, Autocomplete, Search:
+ *   `:has(:focus)` or `data-focused`). Focus stays in the input while the
+ *   popup is open, so the ring stays drawn and a close lands on it.
+ */
+export type OutlineMorphRing = 'focus-visible' | 'focus-within';
+/**
+ * Whether the morph may run now: Web Animations, motion allowed, no forced
+ * colors, not printing. Read at each open, so a preference change applies
+ * to the next one.
+ */
+export declare function canOutlineMorph(): boolean;
+/**
+ * The controller behind `useOutlineMorph`. Elements arrive through the ref
+ * callbacks; `update` receives the open state in a layout effect, so both
+ * directions start in the commit that changes the popup, before it paints.
+ */
+export declare class OutlineMorphController {
+    /** Explicit durations (the hook's `duration` option); otherwise the tokens are read at each open and close. */
+    duration: OutlineMorphDuration | undefined;
+    ring: OutlineMorphRing;
+    /** A modal surface (a dialog, a sheet): the `-surface` durations. */
+    surface: boolean;
+    /** The timing of the running morph, read from the trigger when it started. */
+    private timing;
+    /** Every trigger attached (a popup may have several); `source` is the one this open came from. */
+    private sources;
+    private source;
+    private target;
+    private frame;
+    /** The popup's own tail (an adopter's arrow) and the cap that stands in for it while the morph runs. */
+    private tailSource;
+    private tail;
+    private tailAnimation;
+    private tailFlight;
+    private phase;
+    private open;
+    /** Whether the morph was on at the last update (a popup mounting before its open reaches us is held if so). */
+    private enabled;
+    private anticipateFrame;
+    /**
+     * Where a pending open starts (viewport coordinates), the share of the
+     * open duration it runs, and, for a fresh open, the ring it started from.
+     */
+    private pending;
+    private flight;
+    private frameAnimation;
+    private targetAnimation;
+    /** The popup's own frame, read while it shows (its border is the face while the morph runs). */
+    private targetFrame;
+    private placementObserver;
+    private placementFrame;
+    private placementTries;
+    private trackFrame;
+    private settleObserver;
+    private settleTimer;
+    /** A trigger: its focus ring (or edge) is where the morph starts and lands. */
+    readonly sourceRef: (element: HTMLElement | null) => void;
+    /** The popup: its border box and radius are the frame the morph grows into. */
+    readonly targetRef: (element: HTMLElement | null) => void;
+    /** The popup's own tail, if it has one: the cap draws its copy while the morph runs [§9.17]. */
+    readonly tailSourceRef: (element: HTMLElement | null) => void;
+    /** The tail cap, the overlay's tail, rendered after the frame in the same container. */
+    readonly tailRef: (element: HTMLElement | null) => void;
+    /** The overlay frame, a sibling of the popup inside its positioned container. */
+    readonly frameRef: (element: HTMLElement | null) => void;
+    /**
+     * A popup mounted before its open reaches the controller (its owner's
+     * open state can land a commit after Base UI's): held as a pending open
+     * would be, if the morph would run, so it never paints unclipped first.
+     * The open claims the hold; if none comes within two frames, it goes.
+     */
+    private anticipate;
+    /**
+     * The trigger this open belongs to: the only one attached, else the one
+     * marked open (Base UI's `aria-expanded` / `data-popup-open`), else the
+     * one holding focus, else the last attached. Detached ones are dropped.
+     */
+    private pickSource;
+    /**
+     * The popup or the frame detached: once the commit is over, a running
+     * morph stops if it is still gone. A ref that is only reattached (a
+     * merged ref's new identity, React's development double mount) comes
+     * back within the same commit, and a pending open keeps waiting for it.
+     */
+    private detachSoon;
+    /** The popup's positioned container, which also holds the frame. */
+    private get container();
+    /**
+     * A length token's px value: a plain length as is, else resolved on the
+     * trigger itself (`resolveOn`), else through the frame's own
+     * `outline-offset` (the frame is ours, hidden while idle, and its CSS
+     * never sets that property), since a custom property's computed value
+     * keeps `calc()` and font-relative units unresolved.
+     */
+    private readonly resolveLength;
+    /**
+     * Receives the open state, and whether the morph is on, after each commit.
+     * Off (`enabled` false) stops a running morph, so the change the commit
+     * carries happens the popup's own way.
+     */
+    update(open: boolean, enabled: boolean): void;
+    /** Clears everything: animations, observers, the frame and the popup's attribute. */
+    stop(): void;
+    private startOpen;
+    private startClose;
+    /**
+     * Which ring a close lands on. A field that draws its ring on any focus
+     * (`focus-within`) keeps it while focus stays in it. Otherwise focus comes
+     * back to the trigger when the popup hides, with a ring if the focus inside
+     * the popup shows one (the browser carries it over) or if the popup was
+     * closed from the keyboard.
+     */
+    private closingRing;
+    /**
+     * The ring a running close lands on now: drawn once the trigger draws it;
+     * the planned one while focus stays in the trigger or the popup (on its
+     * way back); none once focus has gone elsewhere (an outside press).
+     */
+    private liveRing;
+    /** Starts a pending open once the popup is placed and laid out. Returns whether it started. */
+    private tryStart;
+    /**
+     * The box fixed elements are laid out in: a modal layer's own box (fixed,
+     * inset 0: the viewport less a reserved scrollbar gutter), else the
+     * root's client box.
+     */
+    private viewport;
+    /** The system ring's weight, `--fgd-focus-width` (2 px): a frame's weight where neither end has one. */
+    private defaultWeight;
+    private readTargetFrame;
+    /** The frame's box now, mid-animation, in viewport coordinates. */
+    private currentBox;
+    /** How far the running animation has come (eased, 0–1); 1 when none runs. */
+    private progress;
+    /**
+     * Animates the frame and the popup's clip from one box to the other
+     * (viewport coordinates, converted to the container's) on one timing.
+     * The popup's border takes its face (its attribute) while the frame draws
+     * the edge.
+     */
+    private run;
+    /**
+     * Re-measures the end the morph travels to every frame while it runs; if
+     * it moved (a scroll, a resize, the popup settling its size) or a close's
+     * ring changed (focus came back, or left), both animations take new
+     * keyframes at their current time.
+     */
+    private track;
+    /**
+     * The open lands: in one task the popup's clip and attribute go (its own
+     * border shows) and the frame hides, so nothing changes on screen.
+     */
+    private handOff;
+    /**
+     * The popup's own tail as the cap copies it, in the container's
+     * coordinates, or null (no tail, or not laid out). Its box is exact for
+     * the quarter turns a tail takes. The edge it sits on is read from where
+     * it lies against the popup (so logical sides need no direction rule).
+     */
+    private readTail;
+    /**
+     * Places the cap on the tail (custom properties only), in whole pixels
+     * from the container's corner: the tail's box is laid out, so it paints
+     * snapped to the pixel grid, and a fractional translation would paint the
+     * cap's stroke softer than the tail it hands off to.
+     */
+    private placeTail;
+    /**
+     * The tail cap: a copy of the popup's tail above the frame, shown only on
+     * the trigger side of the frame's trigger-facing inner edge, so it grows
+     * out of that edge as the frame arrives, tip first and always attached,
+     * and is whole exactly as the frame lands; a close retracts it into the
+     * edge. Its stroke takes the frame's color on the same timing, its face
+     * the popup's. Nothing fades.
+     */
+    private startTail;
+    /**
+     * The close lands on the trigger. The frame and the popup's clip hold
+     * their end state until the popup's container hides, which takes the
+     * frame with it in the frame focus returns (so the ring shows at once);
+     * then everything clears. A container that never hides clears after
+     * SETTLE_MS.
+     */
+    private landClose;
+    /** While an open waits for the popup's placement: try now, then watch its container and the popup, and poll a few frames. */
+    private watchPlacement;
+    private cancelPlacement;
+    private cancelTrack;
+    private cancelSettle;
+    private cancelAnimations;
+}
+//# sourceMappingURL=morphEngine.d.ts.map

package/foundations/outline-morph/morphEngine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"morphEngine.d.ts","sourceRoot":"","sources":["../../src/foundations/outline-morph/morphEngine.ts"],"names":[],"mappings":"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"}