@rivetjs/cdk 0.0.0-stage → 0.1.0-alpha.0

package/shared-element-transition/index.jsx

@@ -0,0 +1,182 @@
+// Ported from react-spectrum packages/react-aria-components/src/SharedElementTransition.tsx, Apache-2.0, © Adobe.
+// `SharedElementTransition` is a scope of named snapshots; a `SharedElement` that stops being visible (or
+// unmounts) stores its rect and the computed values of its `transition-property` properties there, and the
+// next instance of the same name that becomes visible starts from them (translate = rect delta, other
+// properties = previous computed values), so CSS transitions animate it from the old place to the new one.
+// Rivet:
+// - React's layout effect (cleanup snapshots, setup consumes, microtask decides exiting) → one effect per
+//   element on `isVisible` plus a per-scope microtask that runs snapshots, then consumers, then the
+//   "was my snapshot consumed?" checks. Bindings update synchronously, so that order holds whichever
+//   element's effect ran first; React gets it from running every cleanup before every setup.
+// - Resumed pages: nothing runs before the first change of `isVisible`. Then the resumed regions re-create
+//   their elements: `_serverBranch()` tells a re-created element whether the server rendered it, so the
+//   previously visible one still snapshots (from its own re-created element, at the server one's place)
+//   and the newly visible one animates from it.
+// - Render props are accessors (`isEntering()`, `isExiting()`), read inside bindings (Rivet convention);
+//   `class` / `style` / `children` may be functions of them. No `render` prop (RAC DOMRenderProps).
+// - Server: no effect; the element renders without `data-entering` / `data-exiting`.
+import { effect, onCleanup, signal, untrack, useContext } from "@rivetjs/reactivity";
+import { Show, _serverBranch, ref } from "@rivetjs/runtime/dom";
+import { renderSlot } from "@rivetjs/runtime/slot";
+import { globalDOMProps } from "@rivetjs/cdk/dom-props";
+import { SharedElementContext } from "./transition.jsx";
+export { SharedElementContext, SharedElementTransition } from "./transition.jsx";
+// Per-scope work of one flush, run in one microtask: snapshots, then consumers, then exit checks.
+const queues = new WeakMap();
+function schedule(scope, phase, task) {
+    let queue = queues.get(scope);
+    if (!queue) {
+        queues.set(scope, (queue = [[], [], []]));
+        queueMicrotask(() => {
+            queues.delete(scope);
+            for (const tasks of queue)
+                for (const run of tasks)
+                    run();
+        });
+    }
+    queue[phase].push(task);
+}
+const styleOf = (element) => element.style;
+/** On hide / unmount: the rect and computed values of the transitioning properties (RAC effect cleanup). */
+function takeSnapshot(scope, name, element) {
+    if (element && element.isConnected && !element.hasAttribute("data-exiting")) {
+        const style = getComputedStyle(element);
+        if (style.transitionProperty !== "none") {
+            const transitionProperty = style.transitionProperty.split(/\s*,\s*/);
+            scope[name] = {
+                rect: element.getBoundingClientRect(),
+                style: transitionProperty.map((p) => [p, style[p]]),
+            };
+        }
+    }
+}
+/**
+ * An element that animates between its old and new position when moving between parents.
+ */
+export function SharedElement(props) {
+    const scope = useContext(SharedElementContext);
+    if (!scope) {
+        throw new Error("<SharedElement> must be rendered inside a <SharedElementTransition>");
+    }
+    const { name, isVisible = true, children, class: className, style } = props;
+    const dom = globalDOMProps(props);
+    const idProp = props.id;
+    const visible = typeof isVisible === "function" ? isVisible : () => isVisible;
+    const client = typeof requestAnimationFrame === "function";
+    // A resumed page re-creating the server-rendered region starts from what the server rendered.
+    const server = _serverBranch();
+    const wasVisible = server !== undefined ? server === 0 : undefined;
+    const state = signal((wasVisible ?? untrack(visible)) ? "visible" : "hidden");
+    const element = ref();
+    const values = {
+        isEntering: () => client && state() === "entering",
+        isExiting: () => client && state() === "exiting",
+    };
+    if (client) {
+        let previous = wasVisible;
+        let frame = null;
+        // Runs of the effect: a task queued by an earlier run (React: its captured element) does nothing.
+        let run = 0;
+        effect(() => {
+            const isShown = visible();
+            untrack(() => {
+                const current = ++run;
+                const before = previous;
+                previous = isShown;
+                if (frame != null)
+                    (cancelAnimationFrame(frame), (frame = null));
+                // Re-created on a resumed page with the visibility the server rendered: nothing changed.
+                if (before === isShown)
+                    return;
+                const rendered = state() !== "hidden";
+                if (isShown && !rendered)
+                    state.set("visible");
+                // The previous run's cleanup: snapshot the element it rendered (none while hidden).
+                if (before !== undefined && rendered)
+                    schedule(scope, 0, () => takeSnapshot(scope, name, element()));
+                if (isShown)
+                    schedule(scope, 1, () => {
+                        if (current !== run)
+                            return;
+                        const el = element();
+                        const prevSnapshot = scope[name];
+                        if (el && prevSnapshot) {
+                            // Element is transitioning from a previous instance.
+                            state.set("visible");
+                            const animations = el.getAnimations();
+                            const elStyle = styleOf(el);
+                            // Set properties to animate from.
+                            const restore = prevSnapshot.style.map(([property, prevValue]) => {
+                                const value = elStyle[property];
+                                if (property === "translate") {
+                                    const prevRect = prevSnapshot.rect;
+                                    const currentItem = el.getBoundingClientRect();
+                                    const deltaX = prevRect.left - currentItem.left;
+                                    const deltaY = prevRect.top - currentItem.top;
+                                    el.style.translate = `${deltaX}px ${deltaY}px`;
+                                }
+                                else {
+                                    elStyle[property] = prevValue;
+                                }
+                                return [property, value];
+                            });
+                            // Cancel any new animations triggered by these properties.
+                            for (const a of el.getAnimations()) {
+                                if (!animations.includes(a))
+                                    a.cancel();
+                            }
+                            // Remove overrides after one frame to animate to the current values.
+                            frame = requestAnimationFrame(() => {
+                                frame = null;
+                                for (const [property, value] of restore)
+                                    elStyle[property] = value;
+                            });
+                            delete scope[name];
+                        }
+                        else if (el && !prevSnapshot) {
+                            // No previous instance exists, apply the entering state.
+                            state.set("entering");
+                            frame = requestAnimationFrame(() => {
+                                frame = null;
+                                state.set("visible");
+                            });
+                        }
+                    });
+                else
+                    schedule(scope, 2, () => {
+                        if (current !== run)
+                            return;
+                        const el = element();
+                        if (!el)
+                            return;
+                        // After every consumer ran: a snapshot still there was not taken by a new instance, so exit.
+                        if (scope[name]) {
+                            delete scope[name];
+                            state.set("exiting");
+                            Promise.all(el.getAnimations().map((a) => a.finished))
+                                .then(() => !visible() && state() === "exiting" && state.set("hidden"))
+                                .catch(() => { });
+                        }
+                        else {
+                            // Snapshot was consumed by another instance, unmount.
+                            state.set("hidden");
+                        }
+                    });
+            });
+        });
+        // Unmount: store a snapshot for the instance that replaces this one.
+        onCleanup(() => {
+            if (frame != null)
+                cancelAnimationFrame(frame);
+            takeSnapshot(scope, name, untrack(element));
+        });
+    }
+    // Keyed by an object per instance: a re-created (resumed) region builds its own element instead of
+    // adopting the server one, whose bindings belong to the server render.
+    const instance = {};
+    return (<Show when={() => (visible() || (client && state() !== "hidden")) && instance} keyed>
+      {() => (<div {...dom} id={idProp} ref={element} class={typeof className === "function" ? className(values) : className} style={typeof style === "function" ? style(values) : style} data-entering={values.isEntering() ? "true" : undefined} data-exiting={values.isExiting() ? "true" : undefined}>
+          {renderSlot(children, values)}
+        </div>)}
+    </Show>);
+}

package/shared-element-transition/transition.d.ts

@@ -0,0 +1,19 @@
+import type { Content, Slot } from "@rivetjs/runtime/jsx-runtime";
+export interface Snapshot {
+    rect: DOMRect;
+    style: [string, string][];
+}
+/** Snapshots by name (RAC: a ref object). Plain data on the server, so a resumed page re-provides the same object to every re-created element. */
+export type SharedElementScope = {
+    [name: string]: Snapshot;
+};
+/** RAC `SharedElementContext`. */
+export declare const SharedElementContext: import("@rivetjs/reactivity").Context<SharedElementScope | null>;
+export interface SharedElementTransitionProps {
+    /** Plain JSX children are lazy (rendered inside the scope); a function `{() => …}` works too. */
+    children?: Content | Slot;
+}
+/**
+ * A scope for SharedElements, which animate between parents.
+ */
+export declare function SharedElementTransition(props: SharedElementTransitionProps): import("@rivetjs/runtime/jsx-runtime").CompiledElement;

package/shared-element-transition/transition.jsx

@@ -0,0 +1,20 @@
+// Ported from react-spectrum packages/react-aria-components/src/SharedElementTransition.tsx, Apache-2.0, © Adobe.
+// The scope half (`SharedElementContext`, `SharedElementTransition`), apart from `SharedElement` (./index.tsx):
+// Tabs / RadioGroup provide a scope on every page, so their chunks carry these few bytes and never the
+// SharedElement code (that one loads with the first SelectionIndicator that changes).
+import { createContext } from "@rivetjs/reactivity";
+import { Provider } from "@rivetjs/runtime/dom";
+import { resumableContext } from "@rivetjs/runtime/resume-format";
+import { renderSlot } from "@rivetjs/runtime/slot";
+/** RAC `SharedElementContext`. */
+export const SharedElementContext = resumableContext(createContext(null, { id: "rv-shared-element" }));
+/**
+ * A scope for SharedElements, which animate between parents.
+ */
+export function SharedElementTransition(props) {
+    const scope = {};
+    const children = props.children;
+    return (<Provider token={SharedElementContext} value={scope}>
+      {renderSlot(children)}
+    </Provider>);
+}

package/sheet-motion/index.d.ts

@@ -0,0 +1,82 @@
+export type SheetPlacement = "top" | "bottom" | "left" | "right";
+/** A snap point: a fraction (0…1) of the viewport along the sheet's axis, or a CSS length (`px`, `rem`, `em`, `vh` / `dvh` / `svh` / `lvh`, `vw` / `dvw` / `svw` / `lvw`, `%` of the viewport). */
+export type SheetSnapPoint = number | string;
+/** Pixels a pointer moves before a drag is decided. */
+export declare const SHEET_AXIS_LOCK = 6;
+/** Pointer-to-sheet ratio past the drag limits. */
+export declare const SHEET_RUBBER_BAND = 0.2;
+/** Default dismiss threshold (fraction of the remaining distance to the closed edge). */
+export declare const SHEET_CLOSE_THRESHOLD = 0.25;
+export interface SheetMotionOptions {
+    /** The edge the sheet is attached to. @default "bottom" */
+    placement?: SheetPlacement;
+    /** Closes the sheet (called once a dismiss has animated off-screen). */
+    close: () => void;
+    /** Whether a drag may dismiss the sheet. @default true */
+    dismissible?: boolean;
+    /** Snap points, smallest first. */
+    snapPoints?: readonly SheetSnapPoint[];
+    /** The snap point index the sheet rests at when attached (read once). @default 0 */
+    activeSnapIndex?: number;
+    /** A release landed on a snap point (called on release, before the settle animation). */
+    onSnap?: (index: number) => void;
+    /** Dismiss threshold. @default 0.25 */
+    closeThreshold?: number;
+    /** Snap to the neighbouring point only (never skip points). @default false */
+    sequential?: boolean;
+    /** Only drags that start inside an element matching this selector move the sheet (e.g. `[data-slot="sheet-handle"]`). */
+    handle?: string;
+    /** The backdrop: its `--sheet-backdrop-opacity` variable (0…1) follows the drag (style it: `opacity: var(--sheet-backdrop-opacity, 1)`; removed again at rest without snap points). */
+    backdrop?: HTMLElement | null;
+    /** With snap points: the index from which the backdrop is fully opaque (fades in between the previous point and it). @default the last index */
+    fadeFromIndex?: number;
+    /** Every drag frame: the pointer event and the dragged fraction (`offset / size`, 0 = fully shown). */
+    onDrag?: (event: PointerEvent, percentageDragged: number) => void;
+    /** Pointer released after a drag: whether the sheet stays open. */
+    onRelease?: (event: PointerEvent, open: boolean) => void;
+    /** Every rendered frame: the shown fraction (1 = fully shown, 0 = off-screen); drives background scaling / nesting. */
+    onProgress?: (shown: number) => void;
+    /** A drag / snap / dismiss animation settled (`open`: the sheet rests open). */
+    onSettle?: (open: boolean) => void;
+    /** Turns off the animations (on top of `prefers-reduced-motion`). */
+    reduceMotion?: () => boolean;
+    /** `touch-action` set inline on the sheet (behaviour-critical) while attached. @default "none" (vertical), "pan-y" (horizontal); with `handle`: unchanged */
+    touchAction?: string;
+    /**
+     * Overdrag bleed: while the sheet is dragged past fully shown (rubber band), a child `[data-sheet-bleed]` with the
+     * sheet's background (`background: inherit`) fills the space between its attached edge and the viewport edge, so the
+     * surface stays attached (vaul's `::after`). Off for a sheet that floats away from the edge (detached).
+     * @default true
+     */
+    bleed?: boolean;
+}
+export interface SheetMotionController {
+    /** Animates (or `jump`s) to snap point `index` (-1 = fully shown when there are no snap points). */
+    snapTo: (index: number, jump?: boolean) => void;
+    /** Animates the sheet off-screen and calls `close()` when it settles. */
+    dismiss: () => void;
+    /** The current offset (px towards the closed edge). */
+    offset: () => number;
+    /** The snap point index the sheet rests at / animates to (-1 without snap points). */
+    index: () => number;
+    /** Removes the listeners and stops the motion (inline styles stay when dismissed, so an exit animation continues from there). */
+    destroy: () => void;
+}
+/** Visible size (px) of a snap point on a sheet whose axis is `vertical`, in a `width` × `height` viewport (`rem` / `em` from `rootFontSize`). */
+export declare function snapPointSize(point: SheetSnapPoint, viewport: {
+    width: number;
+    height: number;
+}, vertical: boolean, rootFontSize?: number): number;
+/** Whether the axis of `placement` is vertical. */
+export declare const isVerticalSheet: (placement: SheetPlacement) => boolean;
+/**
+ * The resting `transform` of a sheet at snap point `point` as a CSS expression (first render, before any measurement):
+ * `translateY(max(0px, calc(100% - 50dvh)))` for a bottom sheet at `0.5`. `undefined` when there is no point.
+ */
+export declare function snapPointTransform(placement: SheetPlacement, point: SheetSnapPoint | undefined): string | undefined;
+/** Backdrop opacity at `offset` for snap offsets `offsets` (descending visibility order = ascending index) and `fadeFrom`. */
+export declare function sheetBackdropOpacity(offset: number, size: number, offsets: readonly number[], fadeFrom: number): number;
+/** Where the sheet goes for an undamped pointer offset `raw`: `raw` within `limits`, `SHEET_RUBBER_BAND` of the overshoot past them. */
+export declare function rubberBand(raw: number, limits: readonly [number, number]): number;
+/** Attaches drag / snap motion to an open sheet element; returns its controller. */
+export declare function sheetMotion(sheet: HTMLElement, options: SheetMotionOptions): SheetMotionController;