@sharedex/ui 0.0.0-stage → 0.10.0

package/dist/transitions/progress.js

@@ -0,0 +1,109 @@
+// ---------------------------------------------------------------------------
+// The progress contract every CSS transition is written against. Pure strings.
+//
+//   --sx-p   0 = hidden, 1 = shown. A registered <number>, so it can be
+//            transitioned and it inherits into the content and the nodes.
+//
+// Who moves it depends on the host, named by `data-sx-tr-mode`:
+//   carousel  derived from the slot's `--sx-distance` (written every frame by
+//             the carousel): 1 at rest and for the card underneath, 0 for a
+//             card one step away. Dragging scrubs it.
+//   reveal    0, then 1 once its parent gets `data-sx-in` (IntersectionObserver).
+//             The parent is the `Reveal` (or `Reveal.Group`) element; the
+//             transition plays on the child, because a clip-path that starts at
+//             nothing (wipe, iris) would hide the observed element from the
+//             observer itself. A CSS transition on the property plays it, with
+//             the delay and duration from `--sx-tr-delay` / `--sx-tr-duration`.
+//
+//   reveal, trigger="scroll"
+//             follows the scroll instead: a native scroll-driven animation on
+//             the parent's view timeline (`--sx-tr-view`) moves --sx-p from 0
+//             (top edge entering) to 1 (centre at the viewport centre, or fully
+//             in with range "entry"). Without native support, or when an
+//             ancestor's `overflow: hidden` stops the timeline, `data-sx-scroll="js"`
+//             turns the animation off and a scroll listener writes --sx-p inline.
+//
+// Reduced motion: each effect's own CSS is wrapped in
+// `prefers-reduced-motion: no-preference`, so under `reduce` none of it
+// applies: a reveal is a short opacity fade, nodes are hidden, and a carousel
+// falls back to its layout's `reduced` (fade).
+// ---------------------------------------------------------------------------
+import { LAYER_ORDER } from "../backgrounds/runtime/rootCss.js";
+export const TRANSITION_BASE_CSS = `${LAYER_ORDER}
+@property --sx-p {
+  syntax: "<number>";
+  inherits: true;
+  initial-value: 1;
+}
+@layer components {
+  :where([data-sx-tr-mode="carousel"]) {
+    --sx-p: calc(1 - clamp(0, var(--sx-distance, 0), 1));
+  }
+  :where([data-sx-tr-mode="reveal"]) {
+    position: relative;
+    --sx-p: 0;
+    transition: --sx-p var(--sx-tr-duration, 0.9s) var(--sx-tr-ease, var(--ease-sx-out, cubic-bezier(0.22, 0.7, 0.2, 1))) var(--sx-tr-delay, 0s);
+  }
+  :where([data-sx-in] > [data-sx-tr-mode="reveal"]) {
+    --sx-p: 1;
+  }
+  :where([data-sx-reveal] > [data-sx-tr-mode="reveal"]) {
+    block-size: 100%;
+  }
+  :where([data-sx-reveal][data-sx-scrub]) {
+    view-timeline-name: --sx-tr-view;
+  }
+  :where([data-sx-tr-trigger="scroll"]) {
+    transition: none;
+    animation: sx-tr-scrub linear both;
+    animation-timeline: --sx-tr-view;
+    animation-range: entry 0% cover 50%;
+  }
+  :where([data-sx-tr-trigger="scroll"][data-sx-tr-range="entry"]) {
+    animation-range: entry 0% entry 100%;
+  }
+  :where([data-sx-tr-trigger="scroll"][data-sx-scroll="js"]) {
+    animation: none;
+  }
+  :where([data-sx-tr-node]) {
+    position: absolute;
+    pointer-events: none;
+  }
+  @media (prefers-reduced-motion: reduce) {
+    :where([data-sx-tr-mode="reveal"]) {
+      opacity: var(--sx-p);
+      transition-duration: 0.3s;
+    }
+    :where([data-sx-tr-node]) {
+      display: none;
+    }
+    :where([data-sx-tr-trigger="scroll"]) {
+      animation: none;
+      --sx-p: 1;
+    }
+  }
+}
+@keyframes sx-tr-scrub {
+  from { --sx-p: 0; }
+  to { --sx-p: 1; }
+}`;
+const clamp01 = (n) => (n <= 0 ? 0 : n >= 1 ? 1 : n);
+/**
+ * The JS twin of the native timeline, for the fallback: `top` / `height` of
+ * the box (getBoundingClientRect) and the viewport height, px. 0 when the top
+ * edge reaches the bottom of the viewport, matching `animation-range`:
+ * `entry 0% cover 50%` (cover) or `entry 0% entry 100%` (entry; a box taller
+ * than the viewport is "in" once it fills it). `insetTop` / `insetBottom` are
+ * the page's scroll-padding (a sticky header): a native view timeline leaves
+ * them out of the viewport, so the twin does too. Pure; tested.
+ */
+export function scrubProgress(top, height, viewport, range, insetTop = 0, insetBottom = 0) {
+    const bottom = viewport - insetBottom;
+    const view = bottom - insetTop;
+    const travel = range === "entry" ? Math.min(height, view) : view / 2 + height / 2;
+    return travel > 0 ? clamp01((bottom - top) / travel) : 1;
+}
+/** An effect's stylesheet as shipped: only applies when the user has not asked for reduced motion. */
+export function motionOnly(css) {
+    return `@media (prefers-reduced-motion: no-preference) {\n${css}\n}`;
+}

package/dist/transitions/registry.d.ts

@@ -0,0 +1,5 @@
+import type { TransitionMeta } from "./types.js";
+export declare const TRANSITION_EFFECTS: readonly TransitionMeta[];
+export declare const TRANSITION_IDS: ReadonlySet<string>;
+/** A transition's metadata. Throws on an unknown id (a programming error, caught by the tests). */
+export declare function metaOf(id: string): TransitionMeta;

package/dist/transitions/registry.js

@@ -0,0 +1,67 @@
+// ---------------------------------------------------------------------------
+// Every transition's metadata, from the Transition Effects Atlas. The docs read
+// it (and the builder will, later). Factories live in the barrel; this file
+// imports none of them. Keep it in step with test/fixtures/transitions-atlas.mjs.
+// ---------------------------------------------------------------------------
+const stageLook = (id, label, group, description) => ({ id, label, kind: "stage", modes: ["carousel"], group, tier: "all", description });
+const both = (id, label, group, description, tier = "all") => ({ id, label, kind: "css", modes: ["carousel", "reveal"], group, tier, description });
+const shader = (id, label, description) => ({
+    id, label, kind: "webgl", modes: ["carousel", "reveal"], group: "shader", tier: "mid", description,
+});
+export const TRANSITION_EFFECTS = [
+    stageLook("fade", "Fade", "cfree", "The next card fades in over the current one."),
+    stageLook("cube", "Cube", "cfree", "The cards are faces of a cube that turns."),
+    stageLook("flip", "Flip", "cfree", "The card flips over; the next one is on its back."),
+    stageLook("cards", "Cards", "cfree", "The top card is swiped aside and slips under a fanned deck."),
+    stageLook("creative", "Creative", "cfree", "You set where the leaving and coming cards sit."),
+    stageLook("push", "Push", "cfree", "The next card slides in and covers the old one, which drifts back."),
+    stageLook("cardStack", "Card stack", "cpaid", "A neat pile peeking out above; the top card slides off."),
+    stageLook("tinder", "Swipe cards", "cpaid", "The top card is thrown off with a turn and uncovers the next."),
+    // CSS transitions (Phase 2): play in a one-card carousel and in a Reveal
+    both("wipe", "Wipe", "mask", "A straight edge sweeps across and uncovers the content."),
+    both("iris", "Iris", "mask", "A circle grows from the tap point (or the centre)."),
+    both("diagonal", "Diagonal wipe", "mask", "A slanted edge sweeps across."),
+    both("splitCurtain", "Split curtain", "mask", "Opens from the middle; in a reveal, two coloured panels part."),
+    both("colorBlock", "Colour block", "mask", "A solid block sweeps across, the content swaps behind it, the block leaves."),
+    both("gradientMask", "Gradient mask", "mask", "A soft edge sweeps across instead of a hard one."),
+    both("blurSharp", "Blur to sharp", "mask", "Comes into focus as it fades in.", "mid"),
+    both("pixelGrid", "Pixel grid", "mask", "Pixels cover the old content in random order, then clear on the new."),
+    both("shutters", "Shutters", "cpaid", "Strips open like window blinds."),
+    both("slicer", "Slicer", "cpaid", "The picture slides in as slices from alternate sides (needs an image)."),
+    both("fadeUp", "Fade up", "scroll", "Fades in while moving a short way into place."),
+    both("blurFade", "Blur fade", "scroll", "Fades in, rises a little and comes into focus."),
+    both("zoomOut", "Zoom out", "scroll", "The content settles from a zoom inside its frame."),
+    // Phase 3: shapes (one clip-path polygon) and paint
+    both("blinds", "Blinds", "mask", "Strips open from their centres in a wave across the box."),
+    both("randomGrid", "Random grid", "mask", "Cells of a grid open in random order."),
+    both("columnWave", "Column wave", "mask", "Columns rise from one edge in a wave."),
+    both("ink", "Ink", "mask", "Brush strokes paint over, the content swaps, the strokes wipe away (or your own sprite)."),
+    both("gooey", "Gooey", "mask", "Liquid blobs melt together over the old content, then shrink away.", "mid"),
+    // Phase 4: shader transitions between two pictures (Carousel.Shader, <Reveal image>)
+    shader("displacement", "Displacement", "Both pictures drift along a noise (or your own) map while they cross."),
+    shader("stretchWarp", "Stretch warp", "The new picture pushes in, stretched and repeated, and squashes the old one."),
+    shader("pixelDissolve", "Pixel dissolve", "Coarsens into blocks that switch in random order, then sharpens again."),
+    shader("noiseBurn", "Noise burn", "The old picture burns away along a glowing noise edge."),
+    shader("ripple", "Ripple", "A water ring spreads from the tap point and leaves the new picture behind it."),
+    shader("chromaticShift", "Chromatic shift", "The colour channels split apart while the pictures slide and cross."),
+    shader("liquidMorph", "Liquid morph", "The pictures flow into each other along a liquid noise."),
+    shader("crossZoom", "Cross zoom", "A zoom blur rushes into the centre and out on the new picture."),
+    shader("swirl", "Swirl", "The middle twists like a whirlpool while the pictures swap."),
+    shader("dreamy", "Dreamy", "Soft waves ripple across while the pictures cross, with a brief glow."),
+    shader("directionalWarp", "Directional warp", "A soft edge sweeps across; the old picture shrinks away, the new one grows in."),
+    shader("morph", "Morph", "Each pixel flows towards where its colour sits in the other picture."),
+    shader("gridFlip", "Grid flip", "Tiles turn over one after another and show the new picture on their backs."),
+    // Phase 5: heavy WebGL
+    {
+        id: "pageCurl", label: "Page curl", kind: "webgl", modes: ["carousel"], group: "shader", tier: "high",
+        description: "The page lifts from its corner, curls over a cylinder and turns away; its back shows as paper.",
+    },
+];
+export const TRANSITION_IDS = new Set(TRANSITION_EFFECTS.map((m) => m.id));
+/** A transition's metadata. Throws on an unknown id (a programming error, caught by the tests). */
+export function metaOf(id) {
+    const meta = TRANSITION_EFFECTS.find((m) => m.id === id);
+    if (!meta)
+        throw new Error(`[@sharedex/ui] unknown transition "${id}"`);
+    return meta;
+}

package/dist/transitions/reveal/Reveal.d.ts

@@ -0,0 +1,71 @@
+import { type ElementType, type ReactNode } from "react";
+import type { CssTransition, ShaderTransition } from "../types.js";
+import { type ScrubRange } from "../progress.js";
+import { useInView } from "./inView.js";
+export { useInView };
+interface Timing {
+    /** Seconds before it starts once in view. Default `0`. */
+    readonly delay?: number;
+    /** Seconds it takes. Default `0.9`. */
+    readonly duration?: number;
+    /** Play once (default) or every time it comes back into view. */
+    readonly once?: boolean;
+    /** How much of it must be on screen before it plays, 0–1. Default `0.2`. */
+    readonly threshold?: number;
+}
+export interface RevealProps extends Timing {
+    /**
+     * Any CSS transition (`fadeUp()`, `wipe()`, `iris()` …), or a shader
+     * transition (`noiseBurn()` …), which draws `image` from nothing.
+     */
+    readonly effect: CssTransition | ShaderTransition;
+    /**
+     * What drives it.
+     * - `"enter"` (default): plays once (`duration`, `delay`) when it enters the screen.
+     * - `"scroll"`: follows the scroll position, forwards and back (`once`,
+     *   `delay`, `duration`, `threshold` do not apply).
+     */
+    readonly trigger?: "enter" | "scroll";
+    /**
+     * With `trigger="scroll"`: where it is fully shown. `"cover"` (default): once
+     * its centre reaches the middle of the viewport. `"entry"`: as soon as it is
+     * fully in view.
+     */
+    readonly range?: ScrubRange;
+    /**
+     * The picture for transitions that draw one: `slicer`, and every shader
+     * transition (same origin, or served with CORS). With a shader the Reveal
+     * needs a size (`className="aspect-video"`); children sit on top of the picture.
+     */
+    readonly image?: string;
+    /** The element to render. Default `div`. */
+    readonly as?: ElementType;
+    readonly className?: string;
+    readonly children?: ReactNode;
+}
+/**
+ * Plays a transition on its content once it scrolls into view (or as it
+ * scrolls, with `trigger="scroll"`). See `CssReveal` above; a shader effect
+ * draws `image` instead.
+ */
+declare function RevealRoot(props: RevealProps): import("react").JSX.Element;
+export interface RevealGroupProps extends Timing {
+    readonly effect: CssTransition;
+    /** Seconds between one child and the next. Default `0.08`. */
+    readonly stagger?: number;
+    /** The group element. Default `div`. */
+    readonly as?: ElementType;
+    /** The element wrapped around each child. Default `div`. */
+    readonly itemAs?: ElementType;
+    readonly className?: string;
+    readonly itemClassName?: string;
+    readonly children?: ReactNode;
+}
+/**
+ * Reveals its children one after another, `stagger` seconds apart, when the
+ * group enters the screen. Each child is wrapped in one element (`itemAs`)
+ * that plays the transition, so put grid / flex classes on the group and
+ * sizing classes on `itemClassName`.
+ */
+declare function RevealGroup({ effect, stagger, delay, duration, as: Tag, itemAs: Item, className, itemClassName, children, once, threshold, }: RevealGroupProps): import("react").JSX.Element;
+export { RevealRoot, RevealGroup };

package/dist/transitions/reveal/Reveal.js

@@ -0,0 +1,154 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Children, useMemo, useRef } from "react";
+import { TransitionNodes, TransitionStyle, transitionStyle, useTransition } from "../hosts/shared.js";
+import { ShaderStage } from "../hosts/ShaderStage.js";
+import { scrubProgress } from "../progress.js";
+import { useScrubFallback } from "../scroll/useScrub.js";
+import { onFrame } from "../../backgrounds/runtime/clock.js";
+import { useInView } from "./inView.js";
+export { useInView };
+/**
+ * `trigger="scroll"` without a working native view timeline: the shared
+ * fallback (`scroll/useScrub.ts`) writes the inner element's `--sx-p` from the
+ * outer element's position.
+ */
+function useScrollScrub(outerRef, innerRef, enabled, range) {
+    useScrubFallback(outerRef, () => {
+        const outer = outerRef.current;
+        const inner = innerRef.current;
+        if (!outer || !inner)
+            return [];
+        return [
+            {
+                el: inner,
+                progress: (v) => scrubProgress(outer.getBoundingClientRect().top, outer.offsetHeight, v.height, range, v.insetTop, v.insetBottom),
+            },
+        ];
+    }, { enabled, reduced: 1 }, [innerRef, range]);
+}
+function timingVars({ delay, duration }) {
+    const vars = {};
+    // rounded: a stagger sums floats (0.05 + 0.1 = 0.15000000000000002)
+    if (delay !== undefined)
+        vars["--sx-tr-delay"] = `${Number(delay.toFixed(3))}s`;
+    if (duration !== undefined)
+        vars["--sx-tr-duration"] = `${Number(duration.toFixed(3))}s`;
+    return vars;
+}
+/**
+ * Plays a transition on its content once it scrolls into view.
+ *
+ * ```tsx
+ * <Reveal effect={fadeUp()}><h2>Our work</h2></Reveal>
+ * <Reveal effect={wipe({ from: "start" })} delay={0.2}><img … /></Reveal>
+ * ```
+ *
+ * Renders `as` (observed; gets `data-sx-in` once in view) around one `div`
+ * that plays the transition (`data-sx-tr`, `data-sx-tr-mode="reveal"`): its CSS
+ * moves `--sx-p` from 0 to 1 when the parent is in view. Under reduced motion
+ * it is a short opacity fade. Before hydration the content is hidden (it is in
+ * the HTML, so search engines still read it).
+ */
+function CssReveal({ effect, image, as: Tag = "div", className, children, once = true, threshold = 0.2, trigger = "enter", range = "cover", ...timing }) {
+    const ref = useRef(null);
+    const inner = useRef(null);
+    const transition = useTransition(effect);
+    const scroll = trigger === "scroll";
+    useInView(ref, "data-sx-in", once, threshold, !scroll);
+    useScrollScrub(ref, inner, scroll, range);
+    // Two elements: the observer watches the outer one, the transition plays on
+    // the inner one. Watching the inner one fails for clip effects: at p = 0 its
+    // own clip-path leaves no visible area, so it never counts as on screen.
+    // The scroll trigger reads the outer one's view timeline the same way.
+    return (_jsxs(Tag, { ref: ref, "data-sx-reveal": "", "data-sx-scrub": scroll ? "" : undefined, className: className, children: [_jsx(TransitionStyle, { transition: transition }), _jsxs("div", { ref: inner, "data-sx-tr": transition.id, "data-sx-tr-mode": "reveal", "data-sx-tr-trigger": scroll ? "scroll" : undefined, "data-sx-tr-range": scroll && range !== "cover" ? range : undefined, style: { ...transitionStyle(transition, image), ...(scroll ? undefined : timingVars(timing)) }, children: [children, _jsx(TransitionNodes, { transition: transition, image: image })] })] }));
+}
+const clamp01 = (n) => (n <= 0 ? 0 : n >= 1 ? 1 : n);
+/** A shader reveal stops following --sx-p after this long even if it never lands (its CSS never loaded). */
+const FOLLOW_LIMIT_MS = 60000;
+/**
+ * A shader transition in a Reveal: the inner element moves `--sx-p` exactly
+ * as for a CSS transition (time or scroll); a canvas reads it while it may be
+ * moving and draws `image` coming in from nothing.
+ */
+function ShaderReveal({ effect, image, as: Tag = "div", className, children, once = true, threshold = 0.2, trigger = "enter", range = "cover", ...timing }) {
+    const ref = useRef(null);
+    const inner = useRef(null);
+    const scroll = trigger === "scroll";
+    useInView(ref, "data-sx-in", once, threshold, !scroll);
+    useScrollScrub(ref, inner, scroll, range);
+    const picture = useRef(image);
+    picture.current = image;
+    const driver = useMemo(() => {
+        // 1 before mount (the server render): the fallback shows the picture, which CSS hides until it plays
+        const progress = () => {
+            const el = inner.current;
+            return el ? Number.parseFloat(getComputedStyle(el).getPropertyValue("--sx-p")) : 1;
+        };
+        return {
+            read() {
+                // reduced motion: the base CSS fades the whole element; the picture is simply there
+                const still = !inner.current || matchMedia("(prefers-reduced-motion: reduce)").matches;
+                const p = still ? 1 : progress();
+                return { from: undefined, to: picture.current, progress: Number.isFinite(p) ? clamp01(p) : 0, ahead: [] };
+            },
+            watch(changed) {
+                if (scroll)
+                    return onFrame(() => changed());
+                // enter: --sx-p is a CSS transition (its duration may come from any
+                // stylesheet), so follow it from each change of data-sx-in until it
+                // lands where that attribute sends it
+                const outer = ref.current;
+                let stop = null;
+                let since = 0;
+                const landed = () => {
+                    const p = progress();
+                    return !Number.isFinite(p) || p === (outer?.hasAttribute("data-sx-in") ? 1 : 0);
+                };
+                const follow = () => {
+                    since = performance.now();
+                    stop ?? (stop = onFrame((_, now) => {
+                        changed();
+                        if (landed() || now - since > FOLLOW_LIMIT_MS) {
+                            stop?.();
+                            stop = null;
+                        }
+                    }));
+                };
+                const mo = new MutationObserver(follow);
+                if (outer)
+                    mo.observe(outer, { attributes: true, attributeFilter: ["data-sx-in"] });
+                follow();
+                return () => {
+                    mo.disconnect();
+                    stop?.();
+                };
+            },
+        };
+    }, [scroll]);
+    return (_jsxs(Tag, { ref: ref, "data-sx-reveal": "", "data-sx-scrub": scroll ? "" : undefined, className: className, children: [_jsx(TransitionStyle, { transition: effect }), _jsxs("div", { ref: inner, "data-sx-tr": effect.id, "data-sx-tr-mode": "reveal", "data-sx-tr-trigger": scroll ? "scroll" : undefined, "data-sx-tr-range": scroll && range !== "cover" ? range : undefined, style: scroll ? undefined : timingVars(timing), children: [_jsx(ShaderStage, { effect: effect, driver: driver, mode: "reveal", version: image }), children === undefined || children === null ? null : _jsx("div", { "data-sx-tr-over": "", style: { position: "relative" }, children: children })] })] }));
+}
+/**
+ * Plays a transition on its content once it scrolls into view (or as it
+ * scrolls, with `trigger="scroll"`). See `CssReveal` above; a shader effect
+ * draws `image` instead.
+ */
+function RevealRoot(props) {
+    const { effect } = props;
+    return effect.kind === "webgl" ? _jsx(ShaderReveal, { ...props, effect: effect }) : _jsx(CssReveal, { ...props, effect: effect });
+}
+/**
+ * Reveals its children one after another, `stagger` seconds apart, when the
+ * group enters the screen. Each child is wrapped in one element (`itemAs`)
+ * that plays the transition, so put grid / flex classes on the group and
+ * sizing classes on `itemClassName`.
+ */
+function RevealGroup({ effect, stagger = 0.08, delay = 0, duration, as: Tag = "div", itemAs: Item = "div", className, itemClassName, children, once = true, threshold = 0.2, }) {
+    const ref = useRef(null);
+    const transition = useTransition(effect);
+    useInView(ref, "data-sx-in", once, threshold);
+    const base = transitionStyle(transition, undefined);
+    return (_jsxs(Tag, { ref: ref, className: className, children: [_jsx(TransitionStyle, { transition: transition }), Children.toArray(children).map((child, i) => (_jsxs(Item, { "data-sx-tr": transition.id, "data-sx-tr-mode": "reveal", className: itemClassName, style: { ...base, ...timingVars({ delay: delay + i * stagger, duration }) }, children: [child, _jsx(TransitionNodes, { transition: transition })] }, i)))] }));
+}
+// The parts. `Reveal` (with `Reveal.Group`) is assembled in ./index.tsx, outside this client module.
+export { RevealRoot, RevealGroup };

package/dist/transitions/reveal/Reveal.schema.d.ts

@@ -0,0 +1,2 @@
+/** `<Reveal>`'s props as a section reveal: the transition it plays and when. */
+export declare const REVEAL_SCHEMA: import("../../schema/types.js").Schema;

package/dist/transitions/reveal/Reveal.schema.js

@@ -0,0 +1,37 @@
+import { defineSchema } from "../../schema/define.js";
+/** `<Reveal>`'s props as a section reveal: the transition it plays and when. */
+export const REVEAL_SCHEMA = defineSchema()({
+    id: "reveal",
+    family: "reveal",
+    factory: "Reveal",
+    fields: {
+        effect: { kind: "effect", label: "Effect", family: "transition", mode: "reveal", required: true },
+        trigger: {
+            kind: "choice",
+            label: "Plays",
+            values: ["enter", "scroll"],
+            labels: { enter: "Once, when it comes into view", scroll: "With the scroll, forwards and back" },
+            default: "enter",
+        },
+        range: {
+            kind: "choice",
+            label: "Fully shown",
+            values: ["cover", "entry"],
+            labels: { cover: "When its centre reaches the middle", entry: "As soon as it is fully in view" },
+            default: "cover",
+            help: "When it plays with the scroll.",
+        },
+        image: {
+            kind: "text",
+            label: "Picture",
+            url: true,
+            autoNote: "none",
+            help: "Slicer and the shader looks draw a picture; the section's content sits on top.",
+        },
+        delay: { kind: "number", label: "Delay", min: 0, max: 3, step: 0.05, unit: "s", default: 0 },
+        duration: { kind: "number", label: "Duration", min: 0.1, max: 4, step: 0.05, unit: "s", default: 0.9 },
+        once: { kind: "boolean", label: "Only the first time", default: true, help: "Off: plays every time it comes back into view." },
+        threshold: { kind: "number", label: "In view", min: 0, max: 1, step: 0.05, default: 0.2, help: "How much must be on screen before it plays.", advanced: true },
+    },
+    code: ["as", "className", "children"],
+});

package/dist/transitions/reveal/ScrollDistort.d.ts

@@ -0,0 +1,26 @@
+import { type RevealProps } from "./Reveal.js";
+export interface ScrollDistortProps extends Omit<RevealProps, "effect" | "image"> {
+    /** The picture (same origin, or served with CORS). */
+    readonly image: string;
+    /** How far it bends per unit of scroll speed. Default `1`; `0` keeps only the reveal. */
+    readonly strength?: number;
+}
+/**
+ * A picture that rises in behind a wavy edge as it enters the screen, then
+ * bends with the scroll speed: the faster the page scrolls, the more its
+ * middle lags behind, settling flat when scrolling stops.
+ *
+ * ```tsx
+ * <ScrollDistort image="/project.jpg" className="aspect-[4/3]">
+ *   <h3>Project title</h3>
+ * </ScrollDistort>
+ * ```
+ *
+ * A `Reveal` underneath, so `trigger`, `delay`, `duration`, `once` and the rest
+ * work the same; give it a size. High tier: on weaker devices or without
+ * WebGL the picture plays `zoomOut()` instead; under reduced motion it fades
+ * in and never bends. Each one is a
+ * WebGL context while on screen (handed back 3 s after it leaves), so a long
+ * gallery is fine as long as only a handful show at once.
+ */
+export declare function ScrollDistort({ image, strength, ...props }: ScrollDistortProps): import("react").JSX.Element;

package/dist/transitions/reveal/ScrollDistort.js

@@ -0,0 +1,27 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useMemo } from "react";
+import { RevealRoot } from "./Reveal.js";
+import { scrollDistort } from "../effects/shader/scrollDistort.js";
+/**
+ * A picture that rises in behind a wavy edge as it enters the screen, then
+ * bends with the scroll speed: the faster the page scrolls, the more its
+ * middle lags behind, settling flat when scrolling stops.
+ *
+ * ```tsx
+ * <ScrollDistort image="/project.jpg" className="aspect-[4/3]">
+ *   <h3>Project title</h3>
+ * </ScrollDistort>
+ * ```
+ *
+ * A `Reveal` underneath, so `trigger`, `delay`, `duration`, `once` and the rest
+ * work the same; give it a size. High tier: on weaker devices or without
+ * WebGL the picture plays `zoomOut()` instead; under reduced motion it fades
+ * in and never bends. Each one is a
+ * WebGL context while on screen (handed back 3 s after it leaves), so a long
+ * gallery is fine as long as only a handful show at once.
+ */
+export function ScrollDistort({ image, strength = 1, ...props }) {
+    const effect = useMemo(() => scrollDistort({ strength }), [strength]);
+    return _jsx(RevealRoot, { ...props, effect: effect, image: image });
+}

package/dist/transitions/reveal/inView.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Sets `attr` on `el` while it is in view (or forever after the first time,
+ * with `once`). A DOM attribute, not React state: CSS does the rest.
+ */
+export declare function useInView(ref: React.RefObject<HTMLElement | null>, attr: string, once: boolean, threshold: number, enabled?: boolean): void;

package/dist/transitions/reveal/inView.js

@@ -0,0 +1,31 @@
+"use client";
+import { useEffect } from "react";
+/**
+ * Sets `attr` on `el` while it is in view (or forever after the first time,
+ * with `once`). A DOM attribute, not React state: CSS does the rest.
+ */
+export function useInView(ref, attr, once, threshold, enabled = true) {
+    useEffect(() => {
+        const el = ref.current;
+        if (!el || !enabled)
+            return;
+        if (typeof IntersectionObserver === "undefined") {
+            el.setAttribute(attr, "");
+            return;
+        }
+        const io = new IntersectionObserver((entries) => {
+            for (const entry of entries) {
+                if (entry.isIntersecting) {
+                    el.setAttribute(attr, "");
+                    if (once)
+                        io.unobserve(el); // fire once: scrolling back up does not replay it
+                }
+                else if (!once) {
+                    el.removeAttribute(attr);
+                }
+            }
+        }, { threshold });
+        io.observe(el);
+        return () => io.disconnect();
+    }, [ref, attr, once, threshold, enabled]);
+}

package/dist/transitions/reveal/index.d.ts

@@ -0,0 +1,7 @@
+import { RevealGroup, type RevealProps } from "./Reveal.js";
+declare function RevealPart(props: RevealProps): import("react").JSX.Element;
+/** `<Reveal>` plays a transition once its content scrolls into view; `<Reveal.Group>` staggers children. */
+export declare const Reveal: typeof RevealPart & {
+    Group: typeof RevealGroup;
+};
+export {};

package/dist/transitions/reveal/index.js

@@ -0,0 +1,11 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+// A plain module (no "use client"). Attached inside the client module, `Reveal.Group` reached a Server Component
+// as part of an opaque client reference and was undefined there; a property can't be added to that reference
+// from the server either. So `Reveal` is a thin component here that renders the client one, with `Group`
+// attached: it works the same from a Server Component and from client code (found by the Next.js end-to-end check).
+import { RevealGroup, RevealRoot } from "./Reveal.js";
+function RevealPart(props) {
+    return _jsx(RevealRoot, { ...props });
+}
+/** `<Reveal>` plays a transition once its content scrolls into view; `<Reveal.Group>` staggers children. */
+export const Reveal = Object.assign(RevealPart, { Group: RevealGroup });

package/dist/transitions/scroll/Curtain.d.ts

@@ -0,0 +1,31 @@
+import { type ElementType, type ReactNode } from "react";
+export interface CurtainProps {
+    /** The sections, in order. Each one after the first waits underneath the one before. */
+    readonly children?: ReactNode;
+    /** The element to render. Default `div`. */
+    readonly as?: ElementType;
+    readonly className?: string;
+    /** Classes for the wrapper around each section (give it a background if your sections have none). */
+    readonly panelClassName?: string;
+}
+/**
+ * Sections that uncover each other like a curtain: the current one scrolls
+ * away and the next one is already in place underneath, standing still.
+ * With a footer as the last child it is the "fixed footer reveal".
+ *
+ * ```tsx
+ * <Curtain>
+ *   <Hero.Root … />
+ *   <Services.Root … />
+ *   <footer>…</footer>
+ * </Curtain>
+ * ```
+ *
+ * Pure CSS (`position: sticky`, no JavaScript while scrolling): every section
+ * after the first sticks to the bottom of the screen under the one before it.
+ * So each covering section needs a background (the panels default to
+ * `--color-sx-secondary`), works best at one screen tall or less, and must not
+ * sit inside an `overflow: hidden` parent (sticky stops there; `overflow: clip`
+ * is fine). A section taller than the screen is uncovered from its top.
+ */
+export declare function Curtain({ children, as: Tag, className, panelClassName }: CurtainProps): import("react").JSX.Element;

package/dist/transitions/scroll/Curtain.js

@@ -0,0 +1,46 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Children, useEffect, useRef } from "react";
+import { PartStyle } from "../hosts/shared.js";
+import { CURTAIN_CSS } from "./css.js";
+/**
+ * Sections that uncover each other like a curtain: the current one scrolls
+ * away and the next one is already in place underneath, standing still.
+ * With a footer as the last child it is the "fixed footer reveal".
+ *
+ * ```tsx
+ * <Curtain>
+ *   <Hero.Root … />
+ *   <Services.Root … />
+ *   <footer>…</footer>
+ * </Curtain>
+ * ```
+ *
+ * Pure CSS (`position: sticky`, no JavaScript while scrolling): every section
+ * after the first sticks to the bottom of the screen under the one before it.
+ * So each covering section needs a background (the panels default to
+ * `--color-sx-secondary`), works best at one screen tall or less, and must not
+ * sit inside an `overflow: hidden` parent (sticky stops there; `overflow: clip`
+ * is fine). A section taller than the screen is uncovered from its top.
+ */
+export function Curtain({ children, as: Tag = "div", className, panelClassName }) {
+    const ref = useRef(null);
+    const items = Children.toArray(children);
+    // Each panel's height, for the ones taller than the screen (CSS cannot read it).
+    useEffect(() => {
+        const root = ref.current;
+        if (!root || typeof ResizeObserver === "undefined")
+            return;
+        const panels = [...root.querySelectorAll(":scope > [data-sx-curtain-panel]")];
+        const ro = new ResizeObserver((entries) => {
+            for (const e of entries)
+                e.target.style.setProperty("--sx-curtain-h", `${Math.round(e.borderBoxSize[0]?.blockSize ?? e.target.offsetHeight)}px`);
+        });
+        for (const p of panels)
+            ro.observe(p);
+        return () => ro.disconnect();
+    }, [items.length]);
+    return (_jsxs(Tag, { ref: ref, "data-sx-curtain": "", className: className, children: [_jsx(PartStyle, { id: "curtain", css: CURTAIN_CSS }), items.map((child, i) => (
+            // earlier panels above later ones: the one leaving covers the one it uncovers
+            _jsx("div", { "data-sx-curtain-panel": "", className: panelClassName, style: { zIndex: items.length - i }, children: child }, i)))] }));
+}