fancy-ui-react 0.2.0

package/dist/internals/motion/presets.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 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<PresetName, "blur" | "zoom">;
+export declare const PRESET_NAMES: readonly PresetName[];
+/**
+ * `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 declare const PRESETS: Record<PresetName, PresetGeometry>;

package/dist/internals/motion/presets.js

@@ -0,0 +1,19 @@
+"use client";
+const PRESETS = {
+  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
+};
+export {
+  PRESETS
+};

package/dist/internals/motion/raf.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Trailing-edge rAF throttle, generalized from the hand-rolled
+ * `if (id) cancelAnimationFrame(id); id = requestAnimationFrame(...)` pattern
+ * already duplicated in this library (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<A extends unknown[]> {
+    (...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 declare function rafThrottle<A extends unknown[]>(fn: (...args: A) => void): RafThrottled<A>;

package/dist/internals/motion/raf.js

@@ -0,0 +1,27 @@
+"use client";
+function rafThrottle(fn) {
+  let frame;
+  let lastArgs;
+  function throttled(...args) {
+    lastArgs = args;
+    if (typeof requestAnimationFrame !== "function") {
+      fn(...args);
+      return;
+    }
+    if (frame !== void 0) return;
+    frame = requestAnimationFrame(() => {
+      frame = void 0;
+      fn(...lastArgs);
+    });
+  }
+  throttled.cancel = () => {
+    if (frame !== void 0) {
+      if (typeof cancelAnimationFrame === "function") cancelAnimationFrame(frame);
+      frame = void 0;
+    }
+  };
+  return throttled;
+}
+export {
+  rafThrottle
+};

package/dist/internals/motion/stagger.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 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, no hook. A caller
+ * is expected to call this once per item straight from the render path 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;
+/**
+ * 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 declare function staggerDelay(index: number, count: number, step: number, from?: StaggerFrom, cap?: number): number;

package/dist/internals/motion/stagger.js

@@ -0,0 +1,15 @@
+"use client";
+function distanceFromOrigin(index, count, from) {
+  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);
+}
+function staggerDelay(index, count, step, from = "first", cap) {
+  if (count <= 1) return 0;
+  const effStep = cap === void 0 ? step : Math.min(step, cap / Math.max(1, count - 1));
+  return distanceFromOrigin(index, count, from) * effStep;
+}
+export {
+  staggerDelay
+};

package/dist/internals/motion/tokens.d.ts

@@ -0,0 +1,97 @@
+/**
+ * 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.js";
+/** 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 declare const DURATIONS: {
+    readonly micro: 80;
+    readonly fast: 150;
+    readonly base: 300;
+    readonly exit: 200;
+    readonly entrance: 600;
+};
+export type DurationToken = keyof typeof DURATIONS;
+/** CSS `cubic-bezier()` strings — for a component's own `.css` file,
+ * never injected by this file. */
+export declare const EASINGS: {
+    readonly out: "cubic-bezier(0.16, 1, 0.3, 1)";
+    readonly in: "cubic-bezier(0.7, 0, 0.84, 0)";
+    readonly inout: "cubic-bezier(0.4, 0, 0.2, 1)";
+    readonly overshoot: "cubic-bezier(0.34, 1.56, 0.64, 1)";
+};
+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 declare const JS_EASINGS: {
+    readonly out: typeof expoOut;
+    readonly in: typeof expoIn;
+};
+/** 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 declare const STAGGERS: {
+    readonly char: 15;
+    readonly charBlur: 20;
+    readonly word: 40;
+    readonly line: 150;
+    readonly item: 50;
+};
+/** 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 declare const STAGGER_CAPS: {
+    readonly text: 200;
+    readonly item: 600;
+};

package/dist/internals/motion/tokens.js

@@ -0,0 +1,18 @@
+"use client";
+import { expoIn, expoOut } from "./easing.js";
+const DURATIONS = {
+  micro: 80,
+  fast: 150,
+  base: 300,
+  exit: 200,
+  entrance: 600
+};
+const JS_EASINGS = { out: expoOut, in: expoIn };
+const STAGGERS = { char: 15 };
+const STAGGER_CAPS = { text: 200, item: 600 };
+export {
+  DURATIONS,
+  JS_EASINGS,
+  STAGGERS,
+  STAGGER_CAPS
+};

package/dist/internals/motion/transitions.d.ts

@@ -0,0 +1,66 @@
+/**
+ * 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. The sampler in `animate.ts` (`runTransition`) 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 { type PresetName } from "./presets.js";
+/**
+ * One transition's timing plus its per-frame CSS. Structurally identical to
+ * the framework `TransitionConfig` the Svelte side imports, declared locally
+ * so this package takes no runtime dependency on it. 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 existing test files transpose 1:1. */
+export type TransitionFn<P = unknown> = (node: Element, params?: P, options?: {
+    direction: TransitionDirection;
+}) => TransitionSpec;
+export interface PresetParams {
+    duration?: number;
+    delay?: number;
+    distance?: number;
+    /** A JS easing function — `(t: number) => number` — not a CSS string.
+     * Handed straight to `TransitionSpec.easing`; see the file header for
+     * why `cssFor` never has to apply it itself. */
+    easing?: (t: number) => number;
+}
+/**
+ * Returns a transition function for the named preset, ready to hand to
+ * `usePresence`. Resolution order for every param is caller-supplied
+ * `params` → this function's own defaults; `duration` defaults to
+ * `DURATIONS.base` and `distance` to 16px regardless of direction (a
+ * component that wants a shorter/half-distance EXIT, like Presence, passes
+ * those explicitly in its own `out`-side params — this factory does not
+ * guess at that asymmetry).
+ *
+ * `easing` is the one default that DOES read `options.direction`: with no
+ * explicit `params.easing`, an `"out"`-direction instance (an exit-only
+ * instance used on its own — StickyScroll's panel crossfade builds one
+ * `preset("fade")` and uses it as both the enter and the exit spec, two
+ * separate instances) defaults to `JS_EASINGS.in` (a departure curve);
+ * anything else (`"in"`, or the unified `"both"` a single two-way
+ * transition reports — Presence's case) defaults to `JS_EASINGS.out` (an
+ * arrival curve, the more common perceived motion of the two when only one
+ * curve is in play).
+ */
+export declare function preset(name: PresetName): TransitionFn<PresetParams>;

package/dist/internals/motion/transitions.js

@@ -0,0 +1,41 @@
+"use client";
+import { DURATIONS, JS_EASINGS } from "./tokens.js";
+import { PRESETS } from "./presets.js";
+const DEFAULT_DISTANCE = 16;
+function cssFor(name, t, u, distance) {
+  const geometry = PRESETS[name];
+  const declarations = [`opacity: ${t}`];
+  const transformTerms = [];
+  if (geometry.x !== void 0 || geometry.y !== void 0) {
+    const dx = (geometry.x ?? 0) * distance * u;
+    const dy = (geometry.y ?? 0) * distance * u;
+    transformTerms.push(`translate(${dx}px, ${dy}px)`);
+  }
+  if (geometry.scale !== void 0) {
+    transformTerms.push(`scale(${geometry.scale + (1 - geometry.scale) * t})`);
+  }
+  if (transformTerms.length > 0) {
+    declarations.push(`transform: ${transformTerms.join(" ")}`);
+  }
+  if (geometry.blur !== void 0) {
+    declarations.push(`filter: blur(${geometry.blur * u}px)`);
+  }
+  return declarations.join("; ");
+}
+function preset(name) {
+  return (_node, params = {}, options) => {
+    const duration = params.duration ?? DURATIONS.base;
+    const delay = params.delay ?? 0;
+    const distance = params.distance ?? DEFAULT_DISTANCE;
+    const easing = params.easing ?? (options?.direction === "out" ? JS_EASINGS.in : JS_EASINGS.out);
+    return {
+      delay,
+      duration,
+      easing,
+      css: (t, u) => cssFor(name, t, u, distance)
+    };
+  };
+}
+export {
+  preset
+};

package/dist/internals/motion/types.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Type-only aggregate of the shared unions component prop interfaces need to
+ * reference. Re-exported from the package barrel as
+ * `export type * from "./internals/motion/types.js"` (the barrel's edit, not
+ * this file's) so a component's own `<ComponentName>Props` can `import type`
+ * these from one place instead of reaching into individual foundation files
+ * — and, per the common contract, so a component's `index.ts` barrel never
+ * has to re-export a type itself (which would risk a name collision across
+ * the ten components' barrels).
+ *
+ * `verbatimModuleSyntax` (this package's tsconfig) means every line here is
+ * `export type` and compiles to nothing at runtime — this module has zero
+ * JS output, by design.
+ */
+export type { PresetName, RevealPresetName } from "./presets.js";
+export type { StaggerFrom } from "./stagger.js";
+export type { HapticPattern } from "./haptics.js";

package/dist/internals/relative-time.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Locale-aware relative timestamps ("5 minutes ago", "in 2 hours") built on
+ * `Intl.RelativeTimeFormat`. Pure and dependency-free: pass `now` to make the
+ * output deterministic in tests.
+ */
+export interface RelativeTimeOptions {
+    /** BCP 47 tag. Defaults to the runtime locale. */
+    locale?: string;
+    /**
+     * Epoch ms to measure against. Defaults to `Date.now()`. A non-finite
+     * value (the `useNow` "clock not started" sentinel) yields `""`.
+     */
+    now?: number;
+    /** Defaults to `"auto"`, which yields idiomatic words ("now", "yesterday"). */
+    numeric?: "auto" | "always";
+}
+/**
+ * Format `date` relative to `now`. Past dates read "5 minutes ago", future
+ * dates "in 2 hours".
+ *
+ * Under `numeric: "auto"` anything inside the last (or next) 45 seconds is
+ * reported as the locale's zero-word — "now" in English — rather than an exact
+ * second count. Pass `numeric: "always"` to get "10 seconds ago" instead.
+ */
+export declare function formatRelativeTime(date: number | Date, opts?: RelativeTimeOptions): string;

package/dist/internals/relative-time.js

@@ -0,0 +1,46 @@
+"use client";
+const SECOND = 1e3;
+const MINUTE = 60 * SECOND;
+const HOUR = 60 * MINUTE;
+const DAY = 24 * HOUR;
+const WEEK = 7 * DAY;
+const MONTH = 30.436875 * DAY;
+const YEAR = 365.2425 * DAY;
+const BUCKETS = [
+  [45 * SECOND, SECOND, "second"],
+  [45 * MINUTE, MINUTE, "minute"],
+  [22 * HOUR, HOUR, "hour"],
+  [7 * DAY, DAY, "day"],
+  [4 * WEEK, WEEK, "week"],
+  [11 * MONTH, MONTH, "month"],
+  [Infinity, YEAR, "year"]
+];
+const formatters = /* @__PURE__ */ new Map();
+function formatter(locale, numeric) {
+  const key = `${locale ?? ""}|${numeric}`;
+  let rtf = formatters.get(key);
+  if (!rtf) {
+    rtf = new Intl.RelativeTimeFormat(locale, { numeric });
+    formatters.set(key, rtf);
+  }
+  return rtf;
+}
+function formatRelativeTime(date, opts = {}) {
+  const target = date instanceof Date ? date.getTime() : date;
+  if (!Number.isFinite(target)) return "";
+  const now = opts.now ?? Date.now();
+  if (!Number.isFinite(now)) return "";
+  const numeric = opts.numeric ?? "auto";
+  const rtf = formatter(opts.locale, numeric);
+  const diff = target - now;
+  const abs = Math.abs(diff);
+  for (const [limit, step, unit] of BUCKETS) {
+    if (abs >= limit) continue;
+    const value = unit === "second" && numeric === "auto" ? 0 : Math.round(diff / step);
+    return rtf.format(value, unit);
+  }
+  return "";
+}
+export {
+  formatRelativeTime
+};

package/dist/internals/scroll-lock.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Acquires the scroll lock and returns a function that releases this
+ * specific acquisition. Safe to call from SSR (returns a no-op release).
+ * The returned function is idempotent — calling it more than once only
+ * decrements the shared count on its first call.
+ */
+export declare function lockScroll(): () => void;
+/**
+ * Acquires the scroll lock while mounted and `enabled` (default true).
+ *
+ * TIMING RULE FOR PORTS: call it INSIDE the presence-mounted subtree — the
+ * panel component that `usePresence` keeps alive through the exit — and do
+ * NOT pass `open`. Release timing is the whole point: an effect keyed on
+ * `open` releases the instant `open` flips, leaving the page scrollable under
+ * a scrim that is still on screen. Mounting scope is what holds the lock for
+ * the length of the fade instead. `enabled` exists only for non-animated
+ * surfaces (a `duration: 0` drawer, a reduced-motion path).
+ *
+ * Goes on the PANEL, never the scrim — the panel is the component that
+ * already carries the portal, the focus trap and the dismissable layer.
+ *
+ * Reference-counted through `lockScroll()`, so nesting is unchanged, and a
+ * layout effect rather than a passive one: a lock applied after paint is a
+ * visible one-frame scroll jump on a long page.
+ */
+export declare function useScrollLock(enabled?: boolean): void;

package/dist/internals/scroll-lock.js

@@ -0,0 +1,65 @@
+"use client";
+import { useIsomorphicLayoutEffect } from "./dom/ssr.js";
+let lockCount = 0;
+let saved = null;
+function lockScroll() {
+  if (typeof document === "undefined") {
+    return () => {
+    };
+  }
+  if (lockCount === 0) {
+    const body = document.body;
+    const root = document.documentElement;
+    const scrollbarGutter = window.innerWidth - root.clientWidth;
+    const currentPaddingRight = parseFloat(getComputedStyle(body).paddingRight) || 0;
+    saved = {
+      scrollY: window.scrollY,
+      bodyPosition: body.style.position,
+      bodyTop: body.style.top,
+      bodyLeft: body.style.left,
+      bodyRight: body.style.right,
+      bodyWidth: body.style.width,
+      bodyOverflow: body.style.overflow,
+      bodyPaddingRight: body.style.paddingRight
+    };
+    body.style.position = "fixed";
+    body.style.top = `-${saved.scrollY}px`;
+    body.style.left = "0";
+    body.style.right = "0";
+    body.style.width = "100%";
+    body.style.overflow = "hidden";
+    if (scrollbarGutter > 0) {
+      body.style.paddingRight = `${currentPaddingRight + scrollbarGutter}px`;
+    }
+  }
+  lockCount += 1;
+  let released = false;
+  return function release() {
+    if (released) return;
+    released = true;
+    lockCount -= 1;
+    if (lockCount > 0) return;
+    const body = document.body;
+    const state = saved;
+    saved = null;
+    if (!state) return;
+    body.style.position = state.bodyPosition;
+    body.style.top = state.bodyTop;
+    body.style.left = state.bodyLeft;
+    body.style.right = state.bodyRight;
+    body.style.width = state.bodyWidth;
+    body.style.overflow = state.bodyOverflow;
+    body.style.paddingRight = state.bodyPaddingRight;
+    window.scrollTo(0, state.scrollY);
+  };
+}
+function useScrollLock(enabled = true) {
+  useIsomorphicLayoutEffect(() => {
+    if (!enabled) return;
+    return lockScroll();
+  }, [enabled]);
+}
+export {
+  lockScroll,
+  useScrollLock
+};

package/dist/internals/use-anchor-position.d.ts

@@ -0,0 +1,54 @@
+import type { Align, Side } from "./anchor-position.js";
+import type { ElementRef } from "./dom/types.js";
+export interface UseAnchorPositionOptions {
+    /**
+     * The anchor. A node, a ref, or a getter for a moving/virtual target —
+     * the getter form is what a context-menu-style caller with no real
+     * element to point at reaches for.
+     */
+    anchor: ElementRef<HTMLElement> | HTMLElement | null | (() => HTMLElement | null);
+    /** Side of the anchor to place the element on. Defaults to "bottom". */
+    side?: Side;
+    /** Alignment along the cross axis of `side`. Defaults to "center". */
+    align?: Align;
+    /** Gap in pixels between the anchor and the element. Defaults to the core's 8. */
+    offset?: number;
+    /** Stop positioning without unmounting. Default true. */
+    enabled?: boolean;
+    /**
+     * An opaque value the caller bumps to force a recompute when something the
+     * geometry depends on moved but no option did — a context menu's pointer
+     * coordinates, which slide the same virtual anchor element to a new place.
+     */
+    recomputeKey?: string | number;
+    /**
+     * Fires on first placement, then only when the resolved side or align
+     * actually changes. Most consumers want the RETURN VALUE instead; this is
+     * for the caller that has to publish the placement somewhere other than
+     * its own render — a submenu telling its parent context which way it
+     * opened.
+     */
+    onPlacement?: (side: Side, align: Align) => void;
+}
+export interface ResolvedPlacement {
+    readonly side: Side;
+    readonly align: Align;
+}
+/**
+ * Positions `node` with `position: fixed` against a live anchor, and returns
+ * the placement as ACTUALLY resolved — flipped and/or clamped.
+ *
+ * The element comes in as the NODE, never a ref (convention C-1): every
+ * anchored surface is conditionally rendered, so a `useRef` read inside a
+ * `[]`-deps effect would still be null when that effect fires and the
+ * position would never be applied.
+ *
+ * The initial value is the REQUESTED side and align, not a hardcoded
+ * "bottom"/"center" — seeding with anything else shows as a one-frame
+ * transform-origin jump on every open, when only a real flip may move the
+ * origin.
+ *
+ * SSR-safe: nothing runs. The element renders unpositioned, exactly as under
+ * an un-run Svelte action.
+ */
+export declare function useAnchorPosition(node: HTMLElement | null, options: UseAnchorPositionOptions): ResolvedPlacement;