4f:I[707087,["/_next/static/immutable/chunks/3arlv5bvukoo2.js","/_next/static/immutable/chunks/39v64hmfyo-sr.js","/_next/static/immutable/chunks/2nvof3-29tvc3.js","/_next/static/immutable/chunks/3tjobt77z_9dj.js","/_next/static/immutable/chunks/04j_o97cgxn2x.js","/_next/static/immutable/chunks/3upr08c9vtj8w.js","/_next/static/immutable/chunks/1ww0328si-u8x.js","/_next/static/immutable/chunks/11mfl5ymqld9-.js","/_next/static/immutable/chunks/2xxcqy6ppds3l.js","/_next/static/immutable/chunks/3j06ow7w40nxu.js","/_next/static/immutable/chunks/31nn7jwsjvqii.js","/_next/static/immutable/chunks/43_s7jweyypoh.js","/_next/static/immutable/chunks/0p6vao205o1jc.js","/_next/static/immutable/chunks/1_kyvgkyokw92.js","/_next/static/immutable/chunks/1lo-zn37dolb5.js","/_next/static/immutable/chunks/1v8k6yxw1rg0u.js"],"RegistryDependencies"] 50:I[314491,["/_next/static/immutable/chunks/3arlv5bvukoo2.js","/_next/static/immutable/chunks/39v64hmfyo-sr.js","/_next/static/immutable/chunks/2nvof3-29tvc3.js","/_next/static/immutable/chunks/3tjobt77z_9dj.js","/_next/static/immutable/chunks/04j_o97cgxn2x.js","/_next/static/immutable/chunks/3upr08c9vtj8w.js","/_next/static/immutable/chunks/1ww0328si-u8x.js","/_next/static/immutable/chunks/11mfl5ymqld9-.js","/_next/static/immutable/chunks/2xxcqy6ppds3l.js","/_next/static/immutable/chunks/3j06ow7w40nxu.js","/_next/static/immutable/chunks/31nn7jwsjvqii.js","/_next/static/immutable/chunks/43_s7jweyypoh.js","/_next/static/immutable/chunks/0p6vao205o1jc.js","/_next/static/immutable/chunks/1_kyvgkyokw92.js","/_next/static/immutable/chunks/1lo-zn37dolb5.js","/_next/static/immutable/chunks/1v8k6yxw1rg0u.js"],"FilesView"] 51:T2485,"use client"; /** * The shared scale+opacity transition for floating surfaces — menus, selects, * pickers, popovers, tooltips, hover cards. One rung, one curve, one * geometry, so twelve panels stop each inventing their own. * * The name is a slight misnomer for the modal rung: a centred dialog is * anchored to nothing, and spends this same function with its own two * durations (`DURATIONS.base` in, `DURATIONS.exit` out) rather than the * anchored defaults. One geometry in one place was worth more than a synonym, * so the modal surfaces call `anchored` too and spell their rung at the call * site where the diff can see it. * * Two pieces that are deliberately kept separate: * * 1. `anchored()` — a css-only transition (scale + opacity, nothing else). It * never emits `transform-origin`. * 2. `originFor()` — a pure lookup the CALLER writes as a static inline * `style={{ transformOrigin }}`. Keeping the origin out of `css()` means it * is inspectable in DevTools, survives a future exit transition, and is * available to any CSS that wants to key off it — none of which is true * of a value smuggled into a per-frame transition string. * * Why scale + opacity and nothing else: a panel that also translated would * fight `anchor-position.ts`'s `position: fixed; left/top` writes on the same * element (that module owns those three properties and touches neither * `transform` nor `transform-origin`, so the two never collide as written). * The travel is not lost, it moves into the origin: growing from the panel * edge nearest the trigger reads as "this came out of that button" far more * clearly than four pixels of slide ever did. * * SSR: nothing here touches `window` at module scope. `prefersReducedMotion()` * does, but a transition body only ever runs in the browser. */ import type { Side, Align } from "../anchor-position"; import { DURATIONS, JS_EASINGS } from "./tokens"; import { PRESETS } from "./presets"; import { REDUCED_MOTION_QUERY } from "./media-query"; import type { TransitionSpec, TransitionDirection } from "./transitions"; /** Params for `anchored`. Every field is optional; the defaults ARE the * anchored rung, so `anchored(node, { side: resolvedSide })` is the whole * call site for eleven of the twelve panels. */ export interface AnchoredParams { /** The RESOLVED side the surface was placed on — `useAnchorPosition`'s * `onPlacement` value, never the requested one. Drives nothing but the * caller's own `transform-origin`; kept here so one params object feeds * both. Defaults to `"bottom"`, but callers always pass their own * requested side as the seed. */ side?: Side; /** Entrance duration (ms). Defaults to `DURATIONS.fast`. */ duration?: number; /** Exit duration (ms). Defaults to `DURATIONS.fast`. */ exitDuration?: number; /** Delay (ms), entrance only — an exit never waits. Defaults to 0. */ delay?: number; /** `false` drops the scale term, leaving an opacity-only fade (Tooltip). * Defaults to `true`. */ scale?: boolean; /** Direction override, read fresh on every call, for a caller driving ONE * bidirectional transition instance (which reports `direction: "both"`, * and cannot distinguish enter from leave). Unset, direction comes from * `options.direction`. */ entering?: boolean; } /** * One-shot read of the user's motion preference. * * Browser-only, and safe because of where it is called from: a transition body * never runs during SSR. NEVER call it at module scope, in a render path, or * inside a memo — for a live, reactive answer use `useReducedMotion()` from * `media-query.ts` instead. A listener would be pointless here: the value only * matters at the instant a one-shot transition starts, and a preference that * flips mid-flight should not retro-cancel an animation already on screen. * * `window.matchMedia` is resolved FRESH on every call, never memoised, for * the same reason `media-query.ts` documents at length: a test that overrides * `window.matchMedia` wholesale must be visible to the next call. */ export function prefersReducedMotion(): boolean { if (typeof window === "undefined" || typeof window.matchMedia !== "function") return false; return window.matchMedia(REDUCED_MOTION_QUERY).matches; } /** * Resolved side + alignment → the `transform-origin` keyword pair that puts * the growth origin on the panel edge NEAREST the anchor. * * The rule behind the twelve entries: the MAIN-axis keyword is the panel edge * facing the anchor (`bottom` → `top`, `top` → `bottom`, `left` → `right`, * `right` → `left`); the CROSS-axis keyword comes from `align` * (`start` → `left`/`top`, `center` → `center`, `end` → `right`/`bottom`). * Written out rather than computed so the table can be read against a design * doc at a glance. Output is always `" "`. * * Physical, never logical, and that is deliberate: `computePosition` is * physical throughout (`align: "start"` is `anchor.left`, unconditionally), * so a physical origin is the CONSISTENT choice under RTL rather than a bug. * `transform-origin` has no interoperable logical form anyway. */ const ORIGINS: Record> = { bottom: { start: "left top", center: "center top", end: "right top" }, top: { start: "left bottom", center: "center bottom", end: "right bottom" }, left: { start: "right top", center: "right center", end: "right bottom" }, right: { start: "left top", center: "left center", end: "left bottom" }, }; export function originFor(side: Side, align: Align = "center"): string { return ORIGINS[side][align]; } /** The entrance floor, read from the shared geometry table rather than * retyped, so a change to the creative direction's scale floor lands here * too. The `??` is type narrowing for `PresetGeometry.scale`'s optionality — * `PRESETS.scale` has always had one, and `anchored.test.tsx` asserts against * the table entry rather than the literal so a real removal fails loudly. */ const ENTER_FLOOR = PRESETS.scale.scale ?? 0.92; /** An exit travels HALF the delta of an entrance (0.96 against 0.92): * leaving is a smaller gesture than arriving, and a full-depth collapse on * dismiss reads as the panel being sucked away rather than simply closing. */ const EXIT_FLOOR = 1 - (1 - ENTER_FLOOR) / 2; /** * A css-only, direction-aware transition for an anchored floating surface. * Entrance: `JS_EASINGS.out` over `DURATIONS.fast`, growing from the scale * floor. Exit: `JS_EASINGS.in`, half the depth, and never delayed — a * dismissal that waits before starting reads as an unresponsive UI. * * Reduced motion collapses `duration` (and `delay`) to 0, which makes * `runTransition` skip `element.animate()` entirely rather than running a * zero-length animation — the same fast path `animate.test.ts` pins down. */ export function anchored( _node: Element, params: AnchoredParams = {}, options?: { direction: TransitionDirection } ): TransitionSpec { // `"both"` (one bidirectional transition instance) counts as entering: // it is the only direction the caller cannot resolve for us, and an // arrival curve is the more common perceived motion of the two when one // has to stand in for both. `params.entering` wins over // `options.direction` outright — a caller that passes it has better // information than the directive does. const entering = params.entering ?? options?.direction !== "out"; const reduced = prefersReducedMotion(); const duration = reduced ? 0 : entering ? (params.duration ?? DURATIONS.fast) : (params.exitDuration ?? DURATIONS.fast); const delay = reduced ? 0 : entering ? (params.delay ?? 0) : 0; const easing = entering ? JS_EASINGS.out : JS_EASINGS.in; const floor = params.scale === false ? 1 : entering ? ENTER_FLOOR : EXIT_FLOOR; return { delay, duration, easing, // `t` arrives ALREADY eased (the sampler evaluates `easing(i / n)` // before calling `css`), so this interpolates linearly in `t` exactly // like `transitions.ts` does. A floor of 1 emits no `transform` at all // rather than a no-op `scale(1)`, which keeps an opacity-only panel // from acquiring a compositing layer and a stacking context it never // asked for. css: (t) => floor === 1 ? `opacity: ${t}` : `opacity: ${t}; transform: scale(${floor + (1 - floor) * t})`, }; } /** The `data-state` values a transitioning surface reports. There is no * "closed": a closed surface is not in the DOM. Deliberately two values, not * three — a 150–300 ms entrance has nothing that needs to key off "opening", * and two values means one static attribute plus two one-line handlers * instead of four. * * The Svelte side pairs this type with a `markSurfaceState(event, state)` * helper that writes `data-state` IMPERATIVELY from a transition event * handler. That helper is NOT ported (divergence D-2): it exists solely * because Svelte marks a closing `{#if}` branch inert and its scheduler skips * inert effects, so a reactive attribute inside a closing block never reaches * the DOM. React re-renders an exiting surface normally, so a port writes * `data-state={presence.surfaceState}` as an ordinary attribute — same DOM, * same CSS hooks, same two values. */ export type SurfaceState = "open" | "closing"; 52:T24ee,"use client"; /** * The transition sampler — the one mechanism every `transition:`-driven * component in this library runs through, reproduced from the framework's own * `animate()` so the React port animates the SAME curve rather than a * hand-matched approximation of it. * * The decisive fact behind the whole design: a css-only transition is already * WAAPI. The framework samples `css(t, 1 - t)` at * `n = Math.ceil(duration / (1000 / 60))` points, converts each string to a * keyframe object and hands the array to `element.animate()`. Running that same * algorithm against the same `css()` produces a byte-identical keyframe array * and therefore a pixel-identical animation — fidelity is structural here, not * aspirational. It also inherits, free: the `duration: 0` fast path reduced * motion relies on, reversal from an in-flight position rather than a full * restart, and testability through an `Element.prototype.animate` stub. * * The curve lives entirely in the SAMPLE POSITIONS (`t = t1 + delta * * easing(i / n)`), never in a WAAPI `easing` option — which is exactly why * every `css(t, u)` in `transitions.ts` and `anchored.ts` interpolates * linearly in `t`: by the time `css` is called, `t` has already been eased. * * Two things the source has and this does not, both deliberate: * * - `tick`. `TransitionSpec` has no `tick` field (nothing in this library uses * one), so the per-frame JS loop and the `reset()` handle it exists for are * both gone with it. * - The `overflow: hidden` inline-style workaround for a Safari < 18 bug. It * triggers only when a sampled keyframe declares `overflow: hidden`, and no * `css()` in this package emits `overflow` at all — porting it would ship a * branch no test can reach. * * There is deliberately NO "the host cannot animate" `setTimeout` fallback: * the source has none, and inventing one would put an untested code path into * production. jsdom is handled by the `Element.prototype.animate` stub in * `test-setup.ts`, which is a hard requirement of this module's suite. * * SSR: nothing here touches a browser global at module scope. `runTransition` * itself is only ever called from a layout effect. */ import type { TransitionSpec } from "./transitions"; import { linear } from "./easing"; function noop(): void {} /** `float` and `offset` are special-cased in compliance with the spec, and a * custom property (`--x`) is never renamed — a `--`-prefixed key reaches * `element.animate()` exactly as written. Everything else is `kebab-case` → * `camelCase`. */ function cssPropertyToCamelcase(style: string): string { // in compliance with spec if (style === "float") return "cssFloat"; if (style === "offset") return "cssOffset"; // do not rename custom @properties if (style.startsWith("--")) return style; const parts = style.split("-"); if (parts.length === 1) return parts[0] ?? style; return ( (parts[0] ?? "") + parts .slice(1) .map((word) => (word[0] ?? "").toUpperCase() + word.slice(1)) .join("") ); } /** * One `css(t, u)` declaration string → one WAAPI keyframe object. * * Split on `;`, split each part at the FIRST `:`, and **break** — not * `continue` — on a malformed part: a declaration missing its value ends the * parse rather than being skipped, which is the source's behaviour and is what * keeps a trailing `;` harmless. */ export function cssToKeyframe(css: string): Keyframe { const keyframe: Keyframe = {}; const parts = css.split(";"); for (const part of parts) { const [property, value] = part.split(":"); if (!property || value === undefined) break; const formattedProperty = cssPropertyToCamelcase(property.trim()); keyframe[formattedProperty] = value.trim(); } return keyframe; } /** The handle one transition leg hands back. The counterpart of a running leg * is read (`t()`) and then torn down (`abort()`) by the leg that replaces it. */ export interface TransitionRun { /** Current eased position in `css()`'s own `t` space: `1 - to` before the * delay elapses, the interpolated position while the main animation runs, * and `to` once it has finished. Read by a reversing counterpart so a * reopen mid-close starts from where the close actually got to. */ t(): number; /** Cancel without finishing. Also nulls the animation's `effect` (a * Chromium leak) and replaces `onfinish` with a no-op, because a cancelled * animation can still fire `onfinish` in rare cases. */ abort(): void; /** Silence this run's `onFinish` without stopping it. Called on the * counterpart the instant a new leg starts, so a superseded leg cannot * unmount the node the new leg is animating back in. */ deactivate(): void; } /** * Runs one transition leg on `element`, from its current position to `to` * (`1` = visible, `0` = hidden), and calls `onFinish` when it lands. * * Order matters in five places, and every one of them is visible if broken: * * 1. `counterpart?.deactivate()` runs FIRST, before anything else. * 2. A falsy `spec.duration` finishes SYNCHRONOUSLY and never calls * `element.animate()` — the reduced-motion fast path, and the reason a * reduced-motion close completes inside the same layout effect, before * paint. * 3. A leading dummy animation is ALWAYS created, even at `delay: 0`. Its * keyframes pin the hidden state (`css(0, 1)`, twice) only for a fresh * intro, and are empty otherwise. Pinning is what stops a DELAYED entrance * painting one frame at rest first; keeping the dummy at `delay: 0` is what * defers the real keyframes until the DOM has updated. The consequence for * every caller: the main animation always starts ASYNCHRONOUSLY, in the * dummy's `onfinish`. * 4. Inside that `onfinish`: cancel the dummy, then READ `counterpart.t()`, * then abort the counterpart — the read strictly before the abort, or a * reversal restarts from the far end instead of from the in-flight * position. * 5. The sample loop runs `i = 0` to `i <= n` INCLUSIVE (n + 1 keyframes); * `n` must be an integer or the `to` value is missed entirely. */ export function runTransition( element: Element, spec: TransitionSpec, to: 0 | 1, counterpart: TransitionRun | undefined, onFinish: () => void ): TransitionRun { const isIntro = to === 1; counterpart?.deactivate(); if (!spec.duration) { onFinish(); return { abort: noop, deactivate: noop, t: () => to, }; } const { delay = 0, css, easing = linear } = spec; const dummyKeyframes: Keyframe[] = []; if (isIntro && counterpart === undefined) { const styles = cssToKeyframe(css(0, 1)); dummyKeyframes.push(styles, styles); } let getT = () => 1 - to; // Reassigned by `deactivate()`, exactly as the source reassigns its own // `on_finish` parameter. let finish = onFinish; // A dummy animation that lasts as long as the delay. In the common case // that it is `0` we keep it anyway, so the real CSS keyframes are not // created until the DOM has updated. `fill: "forwards"` prevents the // element rendering without styles applied. let animation = element.animate(dummyKeyframes, { duration: delay, fill: "forwards" }); animation.onfinish = () => { // Remove the dummy from the stack so it cannot conflict with the main // animation. animation.cancel(); // For bidirectional transitions we start from the CURRENT position // rather than doing a full intro/outro — hence the read before the abort. const t1 = counterpart?.t() ?? 1 - to; counterpart?.abort(); const delta = to - t1; const duration = spec.duration * Math.abs(delta); const keyframes: Keyframe[] = []; if (duration > 0) { // `n` must be an integer, or we risk missing the `to` value. const n = Math.ceil(duration / (1000 / 60)); for (let i = 0; i <= n; i += 1) { const t = t1 + delta * easing(i / n); keyframes.push(cssToKeyframe(css(t, 1 - t))); } getT = () => { // `currentTime` is `CSSNumberish | null`, not `number`: it is // `null` on an idle or cancelled animation, and a // `CSSNumericValue` on a timeline that reports progress rather // than milliseconds. Either one divided by `duration` is a // value `easing()` cannot use — `null` silently coerces to `0` // and a `CSSNumericValue` gives `NaN`, which `css(t, 1 - t)` // would then bake into every sampled keyframe as the literal // string "NaN" and the reversing leg would jump. A leg whose // clock cannot be read has made no progress worth honouring, // so it reports the position it started from. const time = animation.currentTime; if (typeof time !== "number" || !Number.isFinite(time)) return t1; return t1 + delta * easing(time / duration); }; } // No `easing` option and no `delay` option: the curve is already baked // into the sample positions above, and the delay was the dummy's job. animation = element.animate(keyframes, { duration, fill: "forwards" }); animation.onfinish = () => { getT = () => to; finish(); }; }; return { abort: () => { animation.cancel(); // Prevents a memory leak in Chromium. (animation as unknown as { effect: AnimationEffect | null }).effect = null; // Prevents `onfinish` firing after `cancel()`, which happens in // some rare cases. animation.onfinish = noop; }, deactivate: () => { finish = noop; }, t: () => getT(), }; } 53:T48c,"use client"; /** * The two curves `JS_EASINGS` names, inlined because the framework's easing * module cannot become a runtime dependency of this package (divergence D-7 in * the internals contract). Closed forms, copied byte-for-byte — do NOT "clean * up" the endpoint guards; they are the shape of the curve at exactly the * points `css()` is sampled at. * * Pure data-shaped functions: no side effects, no browser globals, safe to * import at module scope during SSR. */ /** Departure curve. `t === 0` is guarded so the curve starts at exactly 0 * rather than at `2 ** -10`. */ export function expoIn(t: number): number { return t === 0.0 ? t : Math.pow(2.0, 10.0 * (t - 1.0)); } /** Arrival curve. `t === 1` is guarded so the curve ends at exactly 1 rather * than at `1 - 2 ** -10`. */ export function expoOut(t: number): number { return t === 1.0 ? t : 1.0 - Math.pow(2.0, -10.0 * t); } /** The identity curve. Not referenced by `JS_EASINGS`; exported for a caller * that wants to opt a single transition out of easing entirely without * hand-rolling `(t) => t` at the call site. */ export const linear: (t: number) => number = (t) => t; 54:Tb2c,"use client"; /** * Optional tactile feedback via `navigator.vibrate` — a touch-only, opt-in * add-on (Pressable's `haptic` prop, StatusMorph's `haptic` prop). Nothing * here ever throws: the Vibration API is unsupported on most desktop * browsers and can be silently refused by a browser policy even where it * exists (Safari on iOS has never implemented it, for instance), and a * missing rumble is a non-event a user never notices — a thrown error * breaking the surrounding click handler very much would be. */ export const HAPTIC_PATTERNS = { light: 10, medium: 25, heavy: 50, success: [15, 60, 15], error: [60, 60, 60, 60, 60], } as const; export type HapticPattern = keyof typeof HAPTIC_PATTERNS; /** Whether this environment can even attempt a vibration. Checked before * `vibrate()` calls into the API, and exported separately so a component * can skip attaching pointer-tracking work entirely when it never could * fire (e.g. gating a touch-only listener without needing to wait for a * failed call to find that out). */ export function canVibrate(): boolean { return typeof navigator !== "undefined" && typeof navigator.vibrate === "function"; } /** A named pattern resolves to its numeric/array value; a raw number or * array passes straight through. Array patterns are copied out of the * frozen `HAPTIC_PATTERNS` tuple so the caller (and `navigator.vibrate`, * which mutates nothing but shouldn't be handed a `readonly` array either) * never holds a reference into shared, `as const` state. */ function resolvePattern(pattern: HapticPattern | number | number[]): number | number[] { if (typeof pattern !== "string") return pattern; const value = HAPTIC_PATTERNS[pattern]; return typeof value === "number" ? value : [...value]; } /** * Fire a vibration pattern. Returns whether the browser accepted the * request (`navigator.vibrate`'s own return value) — `false` for * "unsupported", "not called from a user gesture", "the tab is * backgrounded", or any other reason the platform declines. Never throws: * some browsers throw rather than return `false` for a policy refusal, so * the whole thing is wrapped rather than trusting the spec's "just returns * a boolean" description. The `!== false` coerces `navigator.vibrate`'s * result rather than returning it verbatim: lib.dom types the method as * always returning `boolean`, but that is a type-level promise the DOM spec * does not actually keep — a user agent is free to return `undefined`, and * without the coercion this function's own `boolean` return type would be a * runtime lie for a caller that checks `=== false`. */ export function vibrate(pattern: HapticPattern | number | number[]): boolean { try { if (!canVibrate()) return false; return navigator.vibrate(resolvePattern(pattern)) !== false; } catch { return false; } } 55:T23c5,"use client"; /** * The primitive every "reveal on scroll" / "notice when visible" component in * this family uses instead of hand-rolling its own IntersectionObserver. * Four components elsewhere in this library (blur-reveal, box-reveal, * line-reveal, number-ticker) each carry a near-identical * `new IntersectionObserver(...)` block, differing only in whether they * honour `once: false` and whether `root`/`rootMargin` are exposed at all — * this is the single, parameterized version those four independently * reinvented, written once for the ten components that need it here. * * Two layers, as everywhere in `internals/`: `observeInView(node, options)` is * the framework-free core (its own suite drives it directly against a * hand-built node, no React), and `useInView(node, options)` is the hook the * components use. */ import { useRef, useState } from "react"; import { useIsomorphicLayoutEffect } from "../dom/ssr"; import { useEventCallback } from "../dom/use-event-callback"; import { useLiveRef } from "../dom/use-live-ref"; export interface InViewOptions { /** Disconnect after the first time the node becomes visible. Default true. */ once?: boolean; /** IntersectionObserver threshold(s). Default 0.1. */ threshold?: number | number[]; /** IntersectionObserver rootMargin. Default "0px". */ rootMargin?: string; /** IntersectionObserver root. Default null (the viewport). */ root?: Element | Document | null; /** Called with the current intersecting state on every observer callback. */ onChange: (inView: boolean, entry?: IntersectionObserverEntry) => void; } /** What `observeInView` hands back. `update()` swaps the live options in * place; `destroy()` disconnects for good. */ export interface InViewHandle { update(options: InViewOptions): void; destroy(): void; } const DEFAULT_THRESHOLD = 0.1; const DEFAULT_ROOT_MARGIN = "0px"; function observerInit(options: InViewOptions): IntersectionObserverInit { return { threshold: options.threshold ?? DEFAULT_THRESHOLD, rootMargin: options.rootMargin ?? DEFAULT_ROOT_MARGIN, root: options.root ?? null, }; } /** Whether two option sets would produce the SAME IntersectionObserver * constructor arguments — the only thing that actually requires tearing * down and rebuilding the observer (see `update()` below). */ function sameObserverInit(a: InViewOptions, b: InViewOptions): boolean { const ia = observerInit(a); const ib = observerInit(b); return ( JSON.stringify(ia.threshold) === JSON.stringify(ib.threshold) && ia.rootMargin === ib.rootMargin && ia.root === ib.root ); } function noop(): void {} export function observeInView(node: Element, opts: InViewOptions): InViewHandle { if (typeof window === "undefined" || typeof IntersectionObserver === "undefined") { // SSR, or a browser old enough to lack IntersectionObserver entirely: // report visible immediately rather than leaving the caller's content // stuck in whatever "not yet revealed" state it renders by default — // failing visible beats failing invisible for a real reader on a real // page. There is nothing to tear down, so `update`/`destroy` are inert. opts.onChange(true); return { update: noop, destroy: noop }; } // The observer callback reads through `current`, not the `opts` closed // over above — so swapping in a new `onChange` (or flipping `once`) via // update() takes effect on the observer's NEXT fire without needing to // disconnect and recreate it. let current = opts; let observer: IntersectionObserver | undefined; // A real IntersectionObserver keeps no "have I already fired" state a // caller can inspect — disconnecting it just stops callbacks. So when // `once: true` has already delivered its one `onChange(true)` and // disconnected, that fact lives ONLY in this flag, not in the (now gone) // observer instance. Without it, a later `update()` that changes // threshold/rootMargin/root — a reactive prop on the consuming // component, not a static one — rebuilds a brand-new observer that knows // nothing about the earlier fire, re-observes the (already revealed) // node, and delivers a SECOND `onChange(true)` the moment it next // intersects. `firedOnce` survives every rebuild and makes `build()` a // no-op once set, so "once" really does mean once for the lifetime of // this handle. let firedOnce = false; function build(o: InViewOptions) { observer?.disconnect(); observer = undefined; if (firedOnce) return; observer = new IntersectionObserver((entries) => { for (const entry of entries) { current.onChange(entry.isIntersecting, entry); if (entry.isIntersecting && (current.once ?? true)) { firedOnce = true; observer?.disconnect(); observer = undefined; } } }, observerInit(o)); observer.observe(node); } build(current); return { update(newOpts: InViewOptions) { // threshold/rootMargin/root are the IntersectionObserver's own // constructor arguments — only changing one of those needs a real // new observer. `once`/`onChange` are read fresh off `current` // every fire, so they never trigger a rebuild: a component that // passes an inline `onChange` closure creates a new function // identity on every render, and re-observing for that alone would // throw away more than intended. When a rebuild IS needed after // `once: true` has already fired, `build()`'s own `firedOnce` // check (above) keeps it a no-op rather than re-observing and // risking a second `onChange(true)`. const needsRebuild = !sameObserverInit(current, newOpts); current = newOpts; if (needsRebuild) build(newOpts); }, destroy() { observer?.disconnect(); }, }; } export interface UseInViewOptions extends Omit { /** Optional here (it is required on the core): the hook already returns the * state, so a consumer only supplies this when it needs the entry itself. */ onChange?: InViewOptions["onChange"]; /** `false` observes nothing at all. Default true. */ enabled?: boolean; } /** * Returns whether `node` is currently intersecting, and forwards every * observer fire to `onChange`. * * Takes the NODE, not a ref (convention C-1): a node created by a conditional * or by a presence-gated subtree is still `null` when a `[]`-deps effect * fires, and that effect never re-runs. * * A LAYOUT effect, not a passive one: the no-IntersectionObserver branch calls * `onChange(true)` synchronously, and a passive effect would paint one frame * of hidden content before the fail-visible answer landed. Constructing the * observer costs nothing measurable. * * The dependency array is exactly the core's own rebuild rule: `threshold`, * `rootMargin` and `root` are the observer's constructor arguments and force a * new one; `once` and `onChange` are read live on every fire and must NOT — * an inline `onChange` closure changes identity every render, and re-observing * for that alone would throw away more than intended. `firedOnce` lives in a * ref so it survives a rebuild but not an unmount, matching the core handle's * per-instance lifetime. * * SSR: `false`, matching an un-run observer. A consumer that needs the * revealed state in the server HTML uses the `initial="visible"` pattern * `Reveal` already has. */ export function useInView(node: Element | null, options: UseInViewOptions = {}): boolean { const { once, threshold, rootMargin, root, enabled = true, onChange } = options; const [inView, setInView] = useState(false); const onceRef = useLiveRef(once); const handleChange = useEventCallback(onChange); const firedOnce = useRef(false); // `threshold` is legitimately an array, so its identity is not a usable // dependency; the core compares the same way, through JSON. const thresholdKey = JSON.stringify(threshold ?? DEFAULT_THRESHOLD); useIsomorphicLayoutEffect(() => { if (!node || !enabled) return; // The core's own post-fire rule, hoisted to hook scope so a rebuild // (a changed threshold/rootMargin/root) cannot re-observe an element // whose single `once` fire has already been delivered. if (firedOnce.current) return; const handle = observeInView(node, { // A getter, not a captured value: `once` is read off this object on // every fire, so flipping it takes effect without a rebuild. get once() { return onceRef.current; }, threshold, rootMargin, root, // Rest args, forwarded as received: the fail-visible branch calls // `onChange(true)` with ONE argument, and re-expanding it to // `(visible, entry)` would hand the consumer an explicit // `undefined` second argument the core never sent. onChange: (...args) => { const [visible] = args; setInView(visible); if (visible && (onceRef.current ?? true)) firedOnce.current = true; handleChange(...args); }, }); return () => { handle.destroy(); }; // eslint-disable-next-line react-hooks/exhaustive-deps -- `threshold` is // covered by `thresholdKey`; `once`/`onChange` are live by design. }, [node, enabled, thresholdKey, rootMargin, root]); return inView; } 56:T1334,"use client"; /** * Live `matchMedia` state as a hook. * * `useSyncExternalStore`, and this file is the archetype for choosing it: a * store React does not own, mutated outside React's knowledge, that must not * tear across a concurrent render — and whose `getServerSnapshot` returns * `fallback` for the server render AND the hydration render, which eliminates * the whole mismatch class rather than papering over it. A * `useState` + `useEffect` version reaches the same end state with one extra * committed frame and a real hydration mismatch the moment someone * "optimises" the initializer into a lazy `window.matchMedia` read. * * The Svelte source's `start()`/`stop()` pair has no counterpart here (D-4): it * exists only because that framework has no lifecycle-bound reactive * primitive, so the factory had to be constructible during SSR before any * effect ran. `useSyncExternalStore` IS that lifecycle, with the hydration * guarantee on top. The consuming pattern collapses from three lines to * `const reduced = useReducedMotion();`. * * `getSnapshot` is called by React on every render and again after every store * change, so it must not allocate: `window.matchMedia(query)` mints a NEW * `MediaQueryList` on each call, and one `useReducedMotion()` in a * scroll-driven tree turns that into garbage on every frame. The list is * therefore memoised per query, and dropped again on the two events that can * make a memoised one wrong: * * - `window.matchMedia` itself being replaced. The cache is keyed on the * current function as well as the query, which is what keeps the source's * own rationale intact: a test that overrides `matchMedia` wholesale * installs a different function, the key stops matching, and the very next * call resolves against the new implementation. * - A `change` event actually firing. A real `MediaQueryList.matches` is live * — the browser updates the object you already hold — but a stub that * captures `matches` at construction is not, and re-resolving once per real * preference change (a rare, user-driven event) costs nothing and makes the * hook correct against both. The subscription itself stays on the list it * was added to, so no listener is stranded. * * Between those, every render reuses one list. `matches` is a boolean, so * snapshot identity is a non-issue either way. */ import { useCallback, useSyncExternalStore } from "react"; export const REDUCED_MOTION_QUERY = "(prefers-reduced-motion: reduce)"; function canMatchMedia(): boolean { return typeof window !== "undefined" && typeof window.matchMedia === "function"; } /** The `window.matchMedia` the cache below was built against. A different * function means a different implementation, so the cache is dropped. */ let cachedImpl: typeof window.matchMedia | undefined; let cache = new Map(); /** * The `MediaQueryList` for `query`, allocated once per (implementation, query) * pair. Called through `window.` rather than a saved reference, because * `matchMedia` is a `Window` method and an unbound call throws in a real * browser; the saved reference is only ever compared, never invoked. */ function mediaQueryList(query: string): MediaQueryList { if (cachedImpl !== window.matchMedia) { cachedImpl = window.matchMedia; cache = new Map(); } const existing = cache.get(query); if (existing) return existing; const mql = window.matchMedia(query); cache.set(query, mql); return mql; } /** Drop one query's memoised list, so the next snapshot resolves a fresh one. */ function invalidate(query: string): void { cache.delete(query); } /** * `true` while `query` matches. `fallback` is the answer on the server, during * hydration, and on a host without `matchMedia` at all. */ export function useMediaQuery(query: string, fallback = false): boolean { const subscribe = useCallback( (onStoreChange: () => void) => { if (!canMatchMedia()) return () => {}; const mql = mediaQueryList(query); // Invalidate BEFORE waking React, so the snapshot it reads next is // resolved against the media state that just changed. const handleChange = () => { invalidate(query); onStoreChange(); }; mql.addEventListener("change", handleChange); return () => { mql.removeEventListener("change", handleChange); }; }, [query] ); const getSnapshot = useCallback(() => { if (!canMatchMedia()) return fallback; return mediaQueryList(query).matches; }, [query, fallback]); const getServerSnapshot = useCallback(() => fallback, [fallback]); return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot); } /** `useMediaQuery(REDUCED_MOTION_QUERY, false)` — reduced motion is never * assumed before the browser has actually been asked. */ export function useReducedMotion(): boolean { return useMediaQuery(REDUCED_MOTION_QUERY, false); } 57:T320a,"use client"; /** * Shared core: the framework-free state machine behind `usePresence` * (`./presence.ts`), split into its own module so a Vue package can drive * the identical mount/unmount clock. Tracked in `shared-cores.json` at the * repo root as a byte-identical file across every framework package this * library ships — see that manifest and `scripts/check-shared-cores.mjs` * for the identity/purity gate this file must keep passing. * * Framework-free means exactly that: no `import ... from "react"` (or * "svelte"/"vue"), no bundler env reads, no `window`/`document`/`navigator` * read at module scope. DOM types (`HTMLElement`, `Element`) are fine — they * come from `lib.dom.d.ts`, not from a framework — and so is calling into a * DOM API from inside a function, which only ever happens once a real node * is handed in through `register`. * * `presence.ts` carries the design rationale for the clock itself (why one * hook owns both directions, why grouping matters, the SSR story); this file * is the mechanism, with the framework-specific ref type swapped for * `PresenceRefCallback` so the same bytes work in every package. */ import { runTransition, type TransitionRun } from "./animate"; import type { TransitionFn, TransitionSpec } from "./transitions"; /** The three values `Presence` renders into `data-state`, because its source * renders three. An anchored surface renders `surfaceState`'s two instead — * the two vocabularies are not interchangeable (convention C-5). */ export type PresenceState = "opening" | "open" | "closing"; /** * A framework-free callback ref: called with the live node on attach, `null` * on detach, returning nothing. This is the shape every framework's own ref * callback type is compatible with — React's `RefCallback` * resolves to `(instance: HTMLElement | null) => void | (() => void)`, and a * function that always returns `void` satisfies that trivially — so each * package's wrapper can hand a slot's `ref` straight through with no cast. */ export type PresenceRefCallback = (node: HTMLElement | null) => void; /** Internal spelling of `register`'s second/third argument: a params value, or a * factory called with the direction at the instant the leg starts. */ export type ParamsOrFactory

= P | ((entering: boolean) => P); export interface PresenceCoreDeps { setMounted: (mounted: boolean) => void; setState: (state: PresenceState) => void; onEnterStart: () => void; onEnterEnd: () => void; onExitStart: () => void; onExitEnd: () => void; /** Read live at the moment an exit starts, never captured per render. */ inertRef: { readonly current: boolean }; } /** The key a single-element `register(transition, params)` call lands on. */ const DEFAULT_KEY = "default"; /** One animated element's seat on the shared clock. */ interface PresenceSlot { /** The live node, or `null` while detached. */ node: HTMLElement | null; /** Rewritten on EVERY render by `register`; called at the instant a leg * starts, which is the only moment `params` is ever read. */ buildSpec: ((node: Element, entering: boolean) => TransitionSpec) | null; /** The leg attached to this slot, kept as the counterpart a reversing leg * reads its start position from. Cleared when an ENTER finishes, kept when * an exit does — see `startSlot`. */ run: TransitionRun | undefined; /** Direction of the leg this slot last started; `null` before its first. */ legTo: 0 | 1 | null; /** Whether that leg has settled. */ finished: boolean; /** * A leg this slot was carrying when its node was detached, owed back to it * the moment a node reattaches. `null` whenever nothing is owed. * * React 19's StrictMode detaches and reattaches every ref on a host node's * mount (`attach` → `detach` → `attach`), and the detach lands AFTER the * layout effect that started the leg. Without this the aborted leg is lost * for good: the driver effect is keyed on `[open, mounted]`, neither of * which moves across a double-invoke, so nothing would ever start it again * and the entrance would stall at `"opening"` forever. */ pendingLeg: 0 | 1 | null; /** Cached for the life of the slot, so a caller never detaches and * reattaches the node just because its owning component re-rendered. */ ref: PresenceRefCallback; } /** * The framework-free state machine behind `usePresence`. Allocation-only, so * it is safe to build eagerly on first use: it installs no listener and * starts no timer until `sync()` is called from a layout effect. */ export function createPresenceCore(deps: PresenceCoreDeps) { const slots = new Map(); /** Direction of the leg currently in flight across the whole group, or * `null` once it has settled. One clock, shared by every slot. */ let leg: 0 | 1 | null = null; /** Suppresses `settle()` while `startLegs` is still handing legs out, so a * synchronous (duration 0) finish on the first slot cannot settle the group * before the rest have started. */ let starting = false; /** Whether the closing `inert` is currently applied, so a reversal clears * exactly what was set and a caller that opted out is never touched. */ let inertApplied = false; /** Reset by `teardown()`, so a remount is a fresh mount again — which is * what keeps the `appear` rule honest under StrictMode's double-invoke. */ let firstRun = true; function ensureSlot(key: string): PresenceSlot { const existing = slots.get(key); if (existing) return existing; const slot: PresenceSlot = { node: null, buildSpec: null, run: undefined, legTo: null, finished: false, pendingLeg: null, // Block body, never a concise arrow: a returned value would be read // as a cleanup function by a framework's ref-callback contract // (React 19's included — convention C-3), and this ref never means to // return one. ref: (node) => { if (node) { slot.node = node; // A leg was in flight when the previous node detached, so hand // it back — this is the only thing that restarts it. The common // case is StrictMode's mount-time detach/reattach, where the // detach lands after the layout effect that started the leg; // the resume is a no-op on a first attach, which is what keeps // the ordinary path (legs started by the driver effect) intact. const pending = slot.pendingLeg; slot.pendingLeg = null; if (pending !== null && leg === pending) startSlot(slot, pending); return; } // The node is leaving the DOM in this very commit; the animation // goes with it, so drop it rather than leaving a Chromium effect // leak behind, and forget the leg so a remount starts clean — // but remember an UNSETTLED leg, which a reattach owes back. slot.pendingLeg = leg !== null && !slot.finished ? leg : null; slot.run?.abort(); slot.run = undefined; slot.node = null; slot.legTo = null; slot.finished = false; }, }; slots.set(key, slot); return slot; } function register

( a: string | TransitionFn

, b?: TransitionFn

| ParamsOrFactory

, c?: ParamsOrFactory

): PresenceRefCallback { const keyed = typeof a === "string"; const slot = ensureSlot(keyed ? a : DEFAULT_KEY); const transition = (keyed ? b : a) as TransitionFn

; const params = (keyed ? c : b) as ParamsOrFactory

| undefined; // Stored, not called: `params` is read at leg start, never at render // time. A `params` that IS a function is therefore always the factory // form — no transition in this package takes a callable params value. slot.buildSpec = (node, entering) => { const resolved = typeof params === "function" ? (params as (entering: boolean) => P)(entering) : params; // A real "in"/"out", never the "both" a single bidirectional // directive reports, so a preset's own direction-dependent easing // default resolves correctly. return transition(node, resolved, { direction: entering ? "in" : "out" }); }; return slot.ref; } function startSlot(slot: PresenceSlot, to: 0 | 1): void { const node = slot.node; const buildSpec = slot.buildSpec; if (!node || !buildSpec) return; // Read BEFORE the bookkeeping below overwrites it: the in-flight leg is // this one's counterpart, and `runTransition` reads its position before // aborting it. const counterpart = slot.run; slot.legTo = to; slot.finished = false; slot.run = undefined; const handle: { current: TransitionRun | undefined } = { current: undefined }; const run = runTransition(node, buildSpec(node, to === 1), to, counterpart, () => { slot.finished = true; if (to === 1) { // On ENTER finish, abort: that removes `fill: forwards` so the // element falls back to its resting style, which is the visible // end state by construction. On EXIT finish, deliberately do NOT // — the node stays in the DOM until the owner processes // `mounted = false` one render later, and dropping fill-forwards // would flash it back to visible for a frame. handle.current?.abort(); slot.run = undefined; } settle(to); }); handle.current = run; // A duration-0 leg already finished synchronously inside the call above; // keeping its handle would hand a settled leg to the next one as a // counterpart. if (!slot.finished) slot.run = run; } function startLegs(to: 0 | 1): void { starting = true; try { for (const slot of slots.values()) { if (!slot.node) continue; if (slot.legTo === to) continue; startSlot(slot, to); } } finally { starting = false; } settle(to); } /** * The group settles only once EVERY attached node's leg has landed — the * source's own rule that a block is destroyed when its LAST transition * finishes, which is what makes a scrim/panel pair leave together instead of * one straggling. */ function settle(to: 0 | 1): void { if (starting) return; // A leg that has been superseded by a reversal must not settle the group. if (leg !== to) return; for (const slot of slots.values()) { if (!slot.node) continue; if (slot.legTo !== to || !slot.finished) return; } leg = null; if (to === 1) { deps.setState("open"); deps.onEnterEnd(); return; } deps.setMounted(false); // Reset to the same honest default `state` starts at: without this a // completed close would leave `state` sitting at "closing", so the next // open would create the node already carrying a stale value for one // render before the entrance corrected it. deps.setState("open"); deps.onExitEnd(); } function beginEnter(): void { leg = 1; if (inertApplied) { inertApplied = false; for (const slot of slots.values()) { slot.node?.toggleAttribute("inert", false); } } deps.setState("opening"); deps.onEnterStart(); } function beginExit(): void { leg = 0; // Fires at the dismiss instant, before the exit paints: a keyboard user // does not wait out the fade with focus stranded on ``. deps.onExitStart(); deps.setState("closing"); if (deps.inertRef.current) { inertApplied = true; for (const slot of slots.values()) { slot.node?.toggleAttribute("inert", true); } } } /** * The whole state machine, driven from one layout effect keyed on * `[open, mounted]`. Every registered node has already attached by the time * this runs: a child host node's ref attaches before an ancestor's layout * effect runs, children first. */ function sync(open: boolean, mounted: boolean, appear: boolean): void { const first = firstRun; firstRun = false; if (open) { if (!mounted) { // Fully closed. Announce the entrance and mount; the legs start on // the next pass, once the subtree has rendered and every // registered node has attached. Both passes land before paint. beginEnter(); deps.setMounted(true); return; } if (first && !appear) { // A local transition never plays on the initial render of the // block that owns it: an already-open mount paints at rest, with // `state` left at its "open" default and no callback fired. return; } if (leg !== 1) beginEnter(); startLegs(1); return; } if (!mounted) return; if (leg !== 0) beginExit(); startLegs(0); } /** Unmount. Aborts every in-flight leg and rewinds the machine, so a * StrictMode remount is indistinguishable from a fresh mount. */ function teardown(): void { for (const slot of slots.values()) { slot.run?.abort(); slot.run = undefined; slot.legTo = null; slot.finished = false; slot.pendingLeg = null; } leg = null; inertApplied = false; firstRun = true; } return { register, sync, teardown }; } 58:T1dd2,"use client"; /** * `usePresence` — the mount/unmount clock every transition-driven surface in * this package runs on. * * The framework this library ports from hands a conditional block's exit * animation to its own scheduler: the block stays alive until its LAST * transition finishes, and only then is it destroyed. React has no such thing * — a component that stops rendering a subtree removes it in the same commit — * so the clock has to be owned explicitly. This hook is that owner, and owning * it in one place rather than per component buys three things: * * - **Cleanup timing, for free.** Every effect cleanup inside the subtree — a * scroll lock's release, a dismissable layer's splice, a focus trap's destroy * path — lands at the instant the exit settles, exactly where the source's * outro-delayed `destroy()` put it. No other module needs a "delay my * teardown" mechanism. * - **Reversal.** ONE bidirectional leg per node, never a split in/out pair, so * a reopen mid-close resumes from the position the close actually reached * instead of snapping back to the far end. Reversal smoothing only exists for * a unified leg; having one hook own both directions makes that structural * rather than a convention a port could break. The node is never unmounted * during such a reversal — which is why `onEnterStart` is the hook a focus * trap re-arms from. * - **Grouping.** Several nodes can share one clock (a dialog's scrim and its * panel), so they leave together and the unmount is a tie rather than a * straggler. * * `register()` is called during render and returns a CACHED, identity-stable * ref callback, so React never detaches and reattaches an animated node. The * transition and its params are rewritten on every render into a per-key slot * and read at the instant a leg starts, never at render time. That is what lets * `params` take a `(entering: boolean) => P` factory, and the factory form is * the documented default: a single bidirectional transition cannot tell * entering from leaving on its own (its `direction` reports `"both"` on both * invocations, computed once for the life of the node), but `open` can — so the * factory is called with the answer, and `usePresence` passes a real * `"in"`/`"out"` down so a preset's own direction-dependent easing default * resolves correctly. * * Phase: layout effect throughout (contract §4). The source starts an intro * before paint; a passive effect would paint one frame at rest first, and a * reduced-motion close would cost an extra frame instead of settling inside the * same effect that started it. * * SSR: `mounted` starts at `open`, no leg ever runs, and nothing here reads a * browser global in a render path. A surface that is open on the server paints * at rest — which is also the client's behaviour on a first render, because * `appear` defaults to false. */ import { useState } from "react"; import type { RefCallback } from "react"; import { useConstant, useIsomorphicLayoutEffect } from "../dom/ssr"; import { useEventCallback } from "../dom/use-event-callback"; import { useLiveRef } from "../dom/use-live-ref"; import { createPresenceCore, type PresenceState } from "./presence-core"; import type { SurfaceState } from "./anchored"; import type { TransitionFn } from "./transitions"; export type { PresenceState }; export interface UsePresenceOptions { /** * Animate an entrance when `open` is ALREADY true on the very first render. * Default FALSE, reproducing two source rules that happen to agree: a LOCAL * transition never plays on the initial render of the block that owns it, * and hydration defaults intros off. A surface mounting for the first time * already open therefore paints visible with no intro. */ appear?: boolean; /** * Set `inert` on every attached node while closing, clear it on enter. * Default true — the source sets it itself, synchronously, immediately * before the exit starts, which is what keeps a closing panel from * answering a click. `false` is the explicit opt-out, and it means this * hook never touches `inert` at all. * * Written as the ATTRIBUTE, through `toggleAttribute`, never as the * `inert` IDL property — the one mechanism this package uses everywhere * (`useInertAttribute` is the same write behind a ref). The attribute is * what `:not([inert])` selectors and assistive technology key on, a real * browser reflects it to the IDL property for anything reading that * instead, and it is the only one of the two that exists under jsdom, so * the behaviour a test pins is the behaviour that ships. */ inert?: boolean; onEnterStart?: () => void; onEnterEnd?: () => void; /** Fires at the dismiss instant, before the exit paints. */ onExitStart?: () => void; onExitEnd?: () => void; } export interface PresenceHandle { /** Render the subtree while true. Stays true through the WHOLE exit. */ readonly mounted: boolean; /** Three values. For anything whose source renders three. */ readonly state: PresenceState; /** Two values — `state === "closing" ? "closing" : "open"`. THE value every * anchored surface renders into `data-state` (convention C-5). */ readonly surfaceState: SurfaceState; /** `=== open`. Pass to `active:` options and to params factories. */ readonly entering: boolean; /** Attach the single animated element. */ register

( transition: TransitionFn

, params?: P | ((entering: boolean) => P) ): RefCallback; /** Attach one of several elements sharing this clock (a dialog's scrim + * panel). The subtree unmounts only when EVERY keyed exit has finished. */ register

( key: string, transition: TransitionFn

, params?: P | ((entering: boolean) => P) ): RefCallback; } /** * Owns one surface's mount/unmount clock. `mounted` stays true through the * whole exit and goes false only once every registered node's leg has settled. */ export function usePresence(open: boolean, options: UsePresenceOptions = {}): PresenceHandle { const { appear = false, inert = true } = options; const [mounted, setMounted] = useState(open); const [state, setState] = useState("open"); const onEnterStart = useEventCallback(options.onEnterStart); const onEnterEnd = useEventCallback(options.onEnterEnd); const onExitStart = useEventCallback(options.onExitStart); const onExitEnd = useEventCallback(options.onExitEnd); const inertRef = useLiveRef(inert); const appearRef = useLiveRef(appear); // Every dependency below is identity-stable for the life of the component: // React's own setters, and the permanently-stable wrappers `useEventCallback` // and `useLiveRef` hand back. The factory allocates and nothing else. const core = useConstant(() => createPresenceCore({ setMounted, setState, onEnterStart, onEnterEnd, onExitStart, onExitEnd, inertRef, }) ); // `appear` is deliberately not a dependency: it only ever decides whether the // FIRST run animates, and it is read live so it cannot go stale either. useIsomorphicLayoutEffect(() => { core.sync(open, mounted, appearRef.current); }, [core, appearRef, open, mounted]); // Separate from the driver above precisely BECAUSE it has a cleanup: giving // the driver one would abort every leg on each reversal, which is the one // thing this hook exists to avoid. useIsomorphicLayoutEffect(() => core.teardown, [core]); return { mounted, state, surfaceState: state === "closing" ? "closing" : "open", entering: open, register: core.register, }; } 59:T9a0,"use client"; /** * The single source of preset GEOMETRY for the motion family — what moves, * and how far, for each named look. Two consumers read this table for two * different purposes: Reveal's CSS (hand-written rules keyed on * `data-preset`, built to match this table by hand) and `transitions.ts`'s * `preset()` (which reads this table directly at runtime to build a * `TransitionSpec`). Keeping the numbers in exactly one place is the * whole point of this file existing separately from `transitions.ts` — a * geometry change here is the one edit that keeps both in sync in theory, * even though Reveal's CSS side still has to be updated by hand (this * package ships no shared runtime stylesheet for motion; see `tokens.ts`'s * header comment for the same caveat applied to durations/easings). */ export type PresetName = | "fade" | "fade-up" | "fade-down" | "fade-left" | "fade-right" | "scale" | "blur" | "zoom"; /** Reveal never offers `blur`/`zoom` — a per-child `filter` is expensive * enough (forces paint, not just compositing) that the contract keeps it * opt-in to a single root (Presence), not something an arbitrary-length * list of children can each carry. */ export type RevealPresetName = Exclude; export const PRESET_NAMES: readonly PresetName[] = [ "fade", "fade-up", "fade-down", "fade-left", "fade-right", "scale", "blur", "zoom", ]; /** * `x`/`y`: the SIGN of the travel axis, multiplied by a caller-supplied * `distance` (px) at the consuming site — `1` and `-1`, never a raw pixel * value, so one `distance` prop scales every directional preset the same * way. `scale`/`blur`: the value at the HIDDEN end of the transition (t=0); * the visible end (t=1) is always the resting `scale(1)` / `blur(0)`. */ export interface PresetGeometry { x?: -1 | 1; y?: -1 | 1; scale?: number; blur?: number; } export const PRESETS: Record = { fade: {}, "fade-up": { y: 1 }, // hidden state sits BELOW rest (+y), travels up into place "fade-down": { y: -1 }, // hidden state sits ABOVE rest (-y), travels down into place "fade-left": { x: 1 }, "fade-right": { x: -1 }, scale: { scale: 0.92 }, // floor per the creative direction — never smaller blur: { blur: 8 }, // px; the one Reveal-excluded preset that is opacity+filter only zoom: { scale: 0.85, blur: 12 }, // Presence's deepest preset — scale floor + filter combined }; 5a:T97a,"use client"; /** * Trailing-edge rAF throttle, generalized from the hand-rolled * `if (id) cancelAnimationFrame(id); id = requestAnimationFrame(...)` pattern * already duplicated in this repo (GlowingEffect's pointer sampling). Magnetic * (pointermove) and ScrollProgress (scroll/resize) both need "run at most * once per frame, with the freshest data" — this is that primitive, pulled * out once instead of re-hand-rolled a third and fourth time. */ export interface RafThrottled { (...args: A): void; /** Cancel a pending (not-yet-run) frame. A safe no-op if none is pending. */ cancel(): void; } /** * Wraps `fn` so a burst of synchronous calls collapses into ONE * `requestAnimationFrame` callback, called with the LATEST call's * arguments — never the first. * * Deliberately does NOT cancel-and-reschedule on every call (the * `cancelAnimationFrame(frame); frame = requestAnimationFrame(...)` shape * some throttles use). That pattern resets the wait on every single call, * so a continuous stream faster than one call per frame — the ENTIRE * reason to throttle in the first place — would push the scheduled frame * back forever and `fn` would never run until the stream paused. Storing * the latest args and letting the frame ALREADY in flight pick them up * guarantees `fn` runs at most once per frame no matter the input rate, * and the one frame that does run always reflects where things ended up. * * Falls back to a synchronous call when `requestAnimationFrame` itself is * unavailable (checked per call, not once at creation, since every real * call site is browser-only by construction and this only matters for a * pathological/non-browser caller) — failing to run at all would be worse * than running un-throttled. */ export function rafThrottle (fn: (...args: A) => void): RafThrottled { let frame: number | undefined; let lastArgs: A; function throttled(...args: A): void { lastArgs = args; if (typeof requestAnimationFrame !== "function") { fn(...args); return; } if (frame !== undefined) return; frame = requestAnimationFrame(() => { frame = undefined; fn(...lastArgs); }); } throttled.cancel = () => { if (frame !== undefined) { if (typeof cancelAnimationFrame === "function") cancelAnimationFrame(frame); frame = undefined; } }; return throttled as RafThrottled ; } 5b:Ta95,"use client"; /** * Per-item delay arithmetic for a staggered entrance — the one formula * Reveal's per-child stagger and TextRoll's per-grapheme roll both build on, * so "stagger from the center" or "stagger from the last item" means the * same thing everywhere in this family. * * Deliberately pure: no DOM, no timers, no side effects. A caller is expected * to call this once per item and write the result into a CSS custom property * or a transition `delay` param — this file never schedules anything itself. */ export type StaggerFrom = "first" | "last" | "center" | number; /** How far item `index` sits from the stagger's origin, in item-steps * (not ms yet — `staggerDelay` multiplies this by the step). A numeric * `from` is honoured exactly as given, even outside `[0, count - 1]`: * clamping it would silently change what a caller asked for, and an * origin outside the list is a legitimate way to make one edge stagger in * later than the other. */ function distanceFromOrigin(index: number, count: number, from: StaggerFrom): number { if (from === "first") return index; if (from === "last") return count - 1 - index; if (from === "center") return Math.abs(index - (count - 1) / 2); return Math.abs(index - from); } /** * The delay (ms) item `index` of `count` should wait before starting its * own entrance, staggered by `step` ms per item away from `from`. * * `cap`, when given, is a TOTAL-delay ceiling reached by COMPRESSING the * step, never by clipping individual delays: `effStep = min(step, cap / * max(1, count - 1))`. A 40-item list at the usual 50ms/item step would * otherwise finish its LAST item's entrance 1950ms after the first one — * long enough to read as "the list is still loading", not "staggered". * Compressing the step instead keeps every item's delay proportional to * its distance from the origin (the ordering and relative spacing survive * intact), just packed into a shorter total window. The cap is computed * against `count - 1` regardless of `from` — exact for `"first"`/`"last"` * (whose maximum distance IS `count - 1`), and a safe (non-tight) bound * for `"center"` or a numeric origin inside the list, whose maximum * distance is smaller. An origin far outside the list can still exceed * the cap in absolute ms — a deliberate consequence of not clamping * `from` above, not a bug in the cap. */ export function staggerDelay( index: number, count: number, step: number, from: StaggerFrom = "first", cap?: number ): number { if (count <= 1) return 0; const effStep = cap === undefined ? step : Math.min(step, cap / Math.max(1, count - 1)); return distanceFromOrigin(index, count, from) * effStep; } 5c:T13d9,"use client"; /** * The shared motion vocabulary for the micro-interaction family: durations, * curves, and stagger steps every one of the ten components draws from * instead of re-typing its own numbers. * * This file has zero side effects and touches nothing browser-specific — it * is pure data, safe to import at module scope from anywhere, including * during SSR. It is also the ONLY place these numbers live as JS values: * every component that wants `--ft-ease-out` (or any other `--ft-*` var) * still has to type the identical literal into its own colocated `.css` as * that CSS custom property's fallback (this package ships no shared runtime * stylesheet for motion — see `tailwind.css`, which carries only the semantic * colour vocabulary). Nothing enforces that a component's CSS fallback * matches the value here; this file is the source of truth a component author * copies FROM, not a value CSS reads at runtime. Keep the two in sync by hand. * * The four curves intentionally read as this collection's own voice, not as * "the house curve" borrowed from anywhere else — `out`/`in` are chosen to * have exact JS equivalents in `./easing.js` (`expoOut`/`expoIn`, see * `JS_EASINGS` below) so a component that needs the SAME curve as both a CSS * string (`transition-timing-function`) and a JS easing function (a * transition spec's `easing` field) never has two numbers to keep in sync. * * One rule about WHERE a consumer may spend these numbers, written down here * rather than left as tribal knowledge held by whichever component happened * to get it right first: colour-only transitions (`color`, * `background-color`, `border-color`) are exempt from * `prefers-reduced-motion` gating — a colour change is not motion, and gating * it only makes a theme flip look broken for the users who asked for less * movement. `transform` / `opacity` / `filter` are NOT exempt and are always * declared inside `@media (prefers-reduced-motion: no-preference)`, with the * resting state as the ungated fallback. */ import { expoIn, expoOut } from "./easing"; /** Milliseconds. `micro` = a glyph-scale beat that only reads as a beat (a * stroke draw's lead-in, an icon cross-fade). `fast` = a reversible state * flip (press, dim). `base` = the default entrance. `exit` = the default * exit (shorter than an entrance — leaving reads faster than arriving). * `entrance` = a slower, deliberate reveal (Reveal's default). * * `micro` is deliberately the one rung with no JS consumer: its consumer is * the CSS mirror `--ft-duration-micro: 80ms`, spent by StatusMorph's check * and cross-stroke delays. It is listed here anyway because this file is the * source of truth a component author copies FROM — a rung that exists only * in CSS fallbacks would be exactly the drift this table is meant to stop. * There is one rung at this scale, not two: StatusMorph's paired `160ms` is * written as a literal on purpose rather than tokenised as a second rung. */ export const DURATIONS = { micro: 80, fast: 150, base: 300, exit: 200, entrance: 600, } as const; export type DurationToken = keyof typeof DURATIONS; /** CSS `cubic-bezier()` strings — for a component's own `.css` file, * never injected by this file. */ export const EASINGS = { out: "cubic-bezier(0.16, 1, 0.3, 1)", // arrivals ↔ expoOut in: "cubic-bezier(0.7, 0, 0.84, 0)", // departures ↔ expoIn inout: "cubic-bezier(0.4, 0, 0.2, 1)", // reversible state ↔ cubicInOut (approx) overshoot: "cubic-bezier(0.34, 1.56, 0.64, 1)", // StatusMorph check only ↔ backOut } as const; export type EasingToken = keyof typeof EASINGS; /** The same two arrival/departure curves as real JS functions, for * `transitions.ts`'s `preset()` — a `TransitionSpec.easing` field wants a * `(t: number) => number`, not a CSS string. Only `out`/`in` exist here: * `inout` never drives a JS-timed transition (it is CSS-only, for * hover/press states that have no discrete start/end), and `overshoot` has * exactly one consumer (StatusMorph's success check, which computes its own * `scale` pop rather than going through `preset()`). */ export const JS_EASINGS = { out: expoOut, in: expoIn } as const; /** Milliseconds per stagger step, before any compression cap is applied. * `char`/`charBlur` are TextRoll's per-grapheme step (plain vs. its * heavier blur variant); `word`/`line` are illustrative rungs for * pretext-driven text layout elsewhere in the library, kept here so a * future consumer doesn't invent a fifth number; `item` is Reveal's * per-child step. */ export const STAGGERS = { char: 15, charBlur: 20, word: 40, line: 150, item: 50 } as const; /** Total-delay compression caps (ms) — see `stagger.ts`'s `staggerDelay`. * `text` bounds TextRoll's per-grapheme roll; `item` bounds Reveal's * per-child stagger. A list long enough to blow past its step × count * without one of these would stop reading as "staggered" and start reading * as "the last item is stuck". */ export const STAGGER_CAPS = { text: 200, item: 600 } as const; 5d:T165e,"use client"; /** * CSS-only transition factories built from `presets.ts`'s geometry table. * Presence's whole "one transition handles both open and close" trick, and * StickyScroll's panel crossfade, are both built on this file. * * How the `easing` param actually reaches the screen is worth spelling out, * because it is easy to assume `css(t, u)` needs to apply the curve itself: * it does not. Whichever runtime plays the transition samples every keyframe * as `t = t1 + delta * easing(i / n)` BEFORE `css(t, 1 - t)` is ever called — * so the `t`/`u` a `css()` function receives are ALREADY eased, and the curve * lives entirely in the sample POSITIONS rather than in a WAAPI `easing` * option. `preset()` below does the same as the framework built-ins it * mirrors: `easing` is resolved once and returned as-is on the spec; `cssFor` * never touches it. */ import { DURATIONS, JS_EASINGS } from "./tokens"; import { PRESETS, type PresetName } from "./presets"; /** * One transition's timing plus its per-frame CSS. Structurally identical to * the `TransitionConfig` a framework transition runtime consumes, declared * locally so this shared core takes no dependency on any one framework's * types. The `tick` field is omitted: nothing in this library uses it. */ export interface TransitionSpec { delay: number; duration: number; easing: (t: number) => number; /** `t` runs 0 (hidden) → 1 (visible); `u = 1 - t`. Receives ALREADY-EASED * `t` — the sampler applies `easing` before calling this, which is why * `cssFor` interpolates linearly in `t`. See the file header. */ css: (t: number, u: number) => string; } export type TransitionDirection = "in" | "out" | "both"; /** A transition function's shape, preserved exactly — including the unused * first parameter, so the colocated test files transpose 1:1. */ export type TransitionFn