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

package/drag-drop/sorting/single-axis-sort-strategy.js

@@ -0,0 +1,343 @@
+import { moveItemInArray } from "../drag-utils.js";
+import { combineTransforms } from "../dom/styling.js";
+import { adjustDomRect, getMutableClientRect, isInsideClientRect } from "../dom/dom-rect.js";
+/**
+ * Strategy that only supports sorting along a single axis.
+ * Items are reordered using CSS transforms which allows for sorting to be animated.
+ * @docs-private
+ */
+export class SingleAxisSortStrategy {
+    /** Root element container of the drop list. */
+    _element;
+    /** Function used to determine if an item can be sorted into a specific index. */
+    _sortPredicate;
+    /** Cache of the dimensions of all the items inside the container. */
+    _itemPositions = [];
+    /**
+     * Draggable items that are currently active inside the container. Includes the items
+     * that were there at the start of the sequence, as well as any items that have been dragged
+     * in, but haven't been dropped yet.
+     */
+    _activeDraggables;
+    /** Direction in which the list is oriented. */
+    orientation = "vertical";
+    /** Layout direction of the drop list. */
+    direction = "ltr";
+    _dragDropRegistry;
+    constructor(_dragDropRegistry) {
+        this._dragDropRegistry = _dragDropRegistry;
+    }
+    /**
+     * Keeps track of the item that was last swapped with the dragged item, as well as what direction
+     * the pointer was moving in when the swap occurred and whether the user's pointer continued to
+     * overlap with the swapped item after the swapping occurred.
+     */
+    _previousSwap = {
+        drag: null,
+        delta: 0,
+        overlaps: false,
+    };
+    /**
+     * To be called when the drag sequence starts.
+     * @param items Items that are currently in the list.
+     */
+    start(items) {
+        this.withItems(items);
+    }
+    /**
+     * To be called when an item is being sorted.
+     * @param item Item to be sorted.
+     * @param pointerX Position of the item along the X axis.
+     * @param pointerY Position of the item along the Y axis.
+     * @param pointerDelta Direction in which the pointer is moving along each axis.
+     */
+    sort(item, pointerX, pointerY, pointerDelta) {
+        const siblings = this._itemPositions;
+        const newIndex = this._getItemIndexFromPointerPosition(item, pointerX, pointerY, pointerDelta);
+        if (newIndex === -1 && siblings.length > 0) {
+            return null;
+        }
+        const isHorizontal = this.orientation === "horizontal";
+        const currentIndex = siblings.findIndex((currentItem) => currentItem.drag === item);
+        const siblingAtNewPosition = siblings[newIndex];
+        const currentPosition = siblings[currentIndex].clientRect;
+        const newPosition = siblingAtNewPosition.clientRect;
+        const delta = currentIndex > newIndex ? 1 : -1;
+        // How many pixels the item's placeholder should be offset.
+        const itemOffset = this._getItemOffsetPx(currentPosition, newPosition, delta);
+        // How many pixels all the other items should be offset.
+        const siblingOffset = this._getSiblingOffsetPx(currentIndex, siblings, delta);
+        // Save the previous order of the items before moving the item to its new index.
+        // We use this to check whether an item has been moved as a result of the sorting.
+        const oldOrder = siblings.slice();
+        // Shuffle the array in place.
+        moveItemInArray(siblings, currentIndex, newIndex);
+        siblings.forEach((sibling, index) => {
+            // Don't do anything if the position hasn't changed.
+            if (oldOrder[index] === sibling) {
+                return;
+            }
+            const isDraggedItem = sibling.drag === item;
+            const offset = isDraggedItem ? itemOffset : siblingOffset;
+            const elementToOffset = isDraggedItem ? item.getPlaceholderElement() : sibling.drag.getRootElement();
+            // Update the offset to reflect the new position.
+            sibling.offset += offset;
+            const transformAmount = Math.round(sibling.offset * (1 / sibling.drag.scale));
+            // Since we're moving the items with a `transform`, we need to adjust their cached
+            // client rects to reflect their new position, as well as swap their positions in the cache.
+            // Note that we shouldn't use `getBoundingClientRect` here to update the cache, because the
+            // elements may be mid-animation which will give us a wrong result.
+            if (isHorizontal) {
+                // Round the transforms since some browsers will
+                // blur the elements, for sub-pixel transforms.
+                elementToOffset.style.transform = combineTransforms(`translate3d(${transformAmount}px, 0, 0)`, sibling.initialTransform);
+                adjustDomRect(sibling.clientRect, 0, offset);
+            }
+            else {
+                elementToOffset.style.transform = combineTransforms(`translate3d(0, ${transformAmount}px, 0)`, sibling.initialTransform);
+                adjustDomRect(sibling.clientRect, offset, 0);
+            }
+        });
+        // Note that it's important that we do this after the client rects have been adjusted.
+        this._previousSwap.overlaps = isInsideClientRect(newPosition, pointerX, pointerY);
+        this._previousSwap.drag = siblingAtNewPosition.drag;
+        this._previousSwap.delta = isHorizontal ? pointerDelta.x : pointerDelta.y;
+        return { previousIndex: currentIndex, currentIndex: newIndex };
+    }
+    /**
+     * Called when an item is being moved into the container.
+     * @param item Item that was moved into the container.
+     * @param pointerX Position of the item along the X axis.
+     * @param pointerY Position of the item along the Y axis.
+     * @param index Index at which the item entered. If omitted, the container will try to figure it
+     *   out automatically.
+     */
+    enter(item, pointerX, pointerY, index) {
+        const activeDraggables = this._activeDraggables;
+        const currentIndex = activeDraggables.indexOf(item);
+        const placeholder = item.getPlaceholderElement();
+        // Since the item may be in the `activeDraggables` already (e.g. if the user dragged it
+        // into another container and back again), we have to ensure that it isn't duplicated.
+        // Note that we need to run this early so the code further below isn't thrown off.
+        if (currentIndex > -1) {
+            activeDraggables.splice(currentIndex, 1);
+        }
+        const newIndex = index == null || index < 0
+            ? // We use the coordinates of where the item entered the drop
+                // zone to figure out at which index it should be inserted.
+                this._getItemIndexFromPointerPosition(item, pointerX, pointerY)
+            : index;
+        let newPositionReference = activeDraggables[newIndex];
+        // If the item at the new position is the same as the item that is being dragged,
+        // it means that we're trying to restore the item to its initial position. In this
+        // case we should use the next item from the list as the reference.
+        if (newPositionReference === item) {
+            newPositionReference = activeDraggables[newIndex + 1];
+        }
+        // If we didn't find a new position reference, it means that either the item didn't start off
+        // in this container, or that the item requested to be inserted at the end of the list.
+        if (!newPositionReference &&
+            (newIndex == null || newIndex === -1 || newIndex < activeDraggables.length - 1) &&
+            this._shouldEnterAsFirstChild(pointerX, pointerY)) {
+            newPositionReference = activeDraggables[0];
+        }
+        // Don't use items that are being dragged as a reference, because
+        // their element has been moved down to the bottom of the body.
+        if (newPositionReference && !this._dragDropRegistry.isDragging(newPositionReference)) {
+            const element = newPositionReference.getRootElement();
+            element.parentElement.insertBefore(placeholder, element);
+            activeDraggables.splice(newIndex, 0, item);
+        }
+        else {
+            this._element.appendChild(placeholder);
+            activeDraggables.push(item);
+        }
+        // The transform needs to be cleared so it doesn't throw off the measurements.
+        placeholder.style.transform = "";
+        // Note that usually `start` is called together with `enter` when an item goes into a new
+        // container. This will cache item positions, but we need to refresh them since the amount
+        // of items has changed.
+        this._cacheItemPositions();
+    }
+    /** Sets the items that are currently part of the list. */
+    withItems(items) {
+        this._activeDraggables = items.slice();
+        this._cacheItemPositions();
+    }
+    /** Assigns a sort predicate to the strategy. */
+    withSortPredicate(predicate) {
+        this._sortPredicate = predicate;
+    }
+    /** Resets the strategy to its initial state before dragging was started. */
+    reset() {
+        // TODO(crisbeto): may have to wait for the animations to finish.
+        this._activeDraggables?.forEach((item) => {
+            const rootElement = item.getRootElement();
+            if (rootElement) {
+                const initialTransform = this._itemPositions.find((p) => p.drag === item)?.initialTransform;
+                rootElement.style.transform = initialTransform || "";
+            }
+        });
+        this._itemPositions = [];
+        this._activeDraggables = [];
+        this._previousSwap.drag = null;
+        this._previousSwap.delta = 0;
+        this._previousSwap.overlaps = false;
+    }
+    /**
+     * Gets a snapshot of items currently in the list.
+     * Can include items that we dragged in from another list.
+     */
+    getActiveItemsSnapshot() {
+        return this._activeDraggables;
+    }
+    /** Gets the index of a specific item. */
+    getItemIndex(item) {
+        return this._getVisualItemPositions().findIndex((currentItem) => currentItem.drag === item);
+    }
+    /** Gets the item at a specific index. */
+    getItemAtIndex(index) {
+        return this._getVisualItemPositions()[index]?.drag || null;
+    }
+    /** Used to notify the strategy that the scroll position has changed. */
+    updateOnScroll(topDifference, leftDifference) {
+        // Since we know the amount that the user has scrolled we can shift all of the
+        // client rectangles ourselves. This is cheaper than re-measuring everything and
+        // we can avoid inconsistent behavior where we might be measuring the element before
+        // its position has changed.
+        this._itemPositions.forEach(({ clientRect }) => {
+            adjustDomRect(clientRect, topDifference, leftDifference);
+        });
+        // We need two loops for this, because we want all of the cached
+        // positions to be up-to-date before we re-sort the item.
+        this._itemPositions.forEach(({ drag }) => {
+            if (this._dragDropRegistry.isDragging(drag)) {
+                // We need to re-sort the item manually, because the pointer move
+                // events won't be dispatched while the user is scrolling.
+                drag._sortFromLastPointerPosition();
+            }
+        });
+    }
+    withElementContainer(container) {
+        this._element = container;
+    }
+    /** Refreshes the position cache of the items and sibling containers. */
+    _cacheItemPositions() {
+        const isHorizontal = this.orientation === "horizontal";
+        this._itemPositions = this._activeDraggables
+            .map((drag) => {
+            const elementToMeasure = drag.getVisibleElement();
+            return {
+                drag,
+                offset: 0,
+                initialTransform: elementToMeasure.style.transform || "",
+                clientRect: getMutableClientRect(elementToMeasure),
+            };
+        })
+            .sort((a, b) => {
+            return isHorizontal ? a.clientRect.left - b.clientRect.left : a.clientRect.top - b.clientRect.top;
+        });
+    }
+    _getVisualItemPositions() {
+        // Items are sorted always by top/left in the cache, however they flow differently in RTL.
+        // The rest of the logic still stands no matter what orientation we're in, however
+        // we need to invert the array when determining the index.
+        return this.orientation === "horizontal" && this.direction === "rtl" ? this._itemPositions.slice().reverse() : this._itemPositions;
+    }
+    /**
+     * Gets the offset in pixels by which the item that is being dragged should be moved.
+     * @param currentPosition Current position of the item.
+     * @param newPosition Position of the item where the current item should be moved.
+     * @param delta Direction in which the user is moving.
+     */
+    _getItemOffsetPx(currentPosition, newPosition, delta) {
+        const isHorizontal = this.orientation === "horizontal";
+        let itemOffset = isHorizontal ? newPosition.left - currentPosition.left : newPosition.top - currentPosition.top;
+        // Account for differences in the item width/height.
+        if (delta === -1) {
+            itemOffset += isHorizontal ? newPosition.width - currentPosition.width : newPosition.height - currentPosition.height;
+        }
+        return itemOffset;
+    }
+    /**
+     * Gets the offset in pixels by which the items that aren't being dragged should be moved.
+     * @param currentIndex Index of the item currently being dragged.
+     * @param siblings All of the items in the list.
+     * @param delta Direction in which the user is moving.
+     */
+    _getSiblingOffsetPx(currentIndex, siblings, delta) {
+        const isHorizontal = this.orientation === "horizontal";
+        const currentPosition = siblings[currentIndex].clientRect;
+        const immediateSibling = siblings[currentIndex + delta * -1];
+        let siblingOffset = currentPosition[isHorizontal ? "width" : "height"] * delta;
+        if (immediateSibling) {
+            const start = isHorizontal ? "left" : "top";
+            const end = isHorizontal ? "right" : "bottom";
+            // Get the spacing between the start of the current item and the end of the one immediately
+            // after it in the direction in which the user is dragging, or vice versa. We add it to the
+            // offset in order to push the element to where it will be when it's inline and is influenced
+            // by the `margin` of its siblings.
+            if (delta === -1) {
+                siblingOffset -= immediateSibling.clientRect[start] - currentPosition[end];
+            }
+            else {
+                siblingOffset += currentPosition[start] - immediateSibling.clientRect[end];
+            }
+        }
+        return siblingOffset;
+    }
+    /**
+     * Checks if pointer is entering in the first position
+     * @param pointerX Position of the user's pointer along the X axis.
+     * @param pointerY Position of the user's pointer along the Y axis.
+     */
+    _shouldEnterAsFirstChild(pointerX, pointerY) {
+        if (!this._activeDraggables.length) {
+            return false;
+        }
+        const itemPositions = this._itemPositions;
+        const isHorizontal = this.orientation === "horizontal";
+        // `itemPositions` are sorted by position while `activeDraggables` are sorted by child index
+        // check if container is using some sort of "reverse" ordering (eg: flex-direction: row-reverse)
+        const reversed = itemPositions[0].drag !== this._activeDraggables[0];
+        if (reversed) {
+            const lastItemRect = itemPositions[itemPositions.length - 1].clientRect;
+            return isHorizontal ? pointerX >= lastItemRect.right : pointerY >= lastItemRect.bottom;
+        }
+        else {
+            const firstItemRect = itemPositions[0].clientRect;
+            return isHorizontal ? pointerX <= firstItemRect.left : pointerY <= firstItemRect.top;
+        }
+    }
+    /**
+     * Gets the index of an item in the drop container, based on the position of the user's pointer.
+     * @param item Item that is being sorted.
+     * @param pointerX Position of the user's pointer along the X axis.
+     * @param pointerY Position of the user's pointer along the Y axis.
+     * @param delta Direction in which the user is moving their pointer.
+     */
+    _getItemIndexFromPointerPosition(item, pointerX, pointerY, delta) {
+        const isHorizontal = this.orientation === "horizontal";
+        const index = this._itemPositions.findIndex(({ drag, clientRect }) => {
+            // Skip the item itself.
+            if (drag === item) {
+                return false;
+            }
+            if (delta) {
+                const direction = isHorizontal ? delta.x : delta.y;
+                // If the user is still hovering over the same item as last time, their cursor hasn't left
+                // the item after we made the swap, and they didn't change the direction in which they're
+                // dragging, we don't consider it a direction swap.
+                if (drag === this._previousSwap.drag && this._previousSwap.overlaps && direction === this._previousSwap.delta) {
+                    return false;
+                }
+            }
+            return isHorizontal
+                ? // Round these down since most browsers report client rects with
+                    // sub-pixel precision, whereas the pointer coordinates are rounded to pixels.
+                    pointerX >= Math.floor(clientRect.left) && pointerX < Math.floor(clientRect.right)
+                : pointerY >= Math.floor(clientRect.top) && pointerY < Math.floor(clientRect.bottom);
+        });
+        return index === -1 || !this._sortPredicate(index, item) ? -1 : index;
+    }
+}

package/file-trigger/index.d.ts

@@ -0,0 +1,24 @@
+import type { Content } from "@rivetjs/runtime/jsx-runtime";
+import { type GlobalDOMAttributes } from "../utils/dom-props.js";
+import { type RefValue } from "../slots/index.jsx";
+export interface FileTriggerProps extends GlobalDOMAttributes<HTMLInputElement> {
+    /** Specifies what mime type of files are allowed. */
+    acceptedFileTypes?: ReadonlyArray<string>;
+    /** Whether multiple files can be selected. */
+    allowsMultiple?: boolean;
+    /** Specifies the use of a media capture mechanism to capture the media on the spot. */
+    defaultCamera?: "user" | "environment";
+    /** Handler when a user selects a file. */
+    onSelect?: (files: FileList | null) => void;
+    /** The children of the component. */
+    children?: Content;
+    /** Enables the selection of directories instead of individual files. */
+    acceptDirectory?: boolean;
+    /** Ref to the hidden `<input type="file">`. */
+    ref?: RefValue<HTMLInputElement>;
+}
+/**
+ * A FileTrigger allows a user to access the file system with any pressable React Aria or React
+ * Spectrum component, or custom components built with usePress.
+ */
+export declare function FileTrigger(props: FileTriggerProps): import("@rivetjs/runtime/jsx-runtime").CompiledElement;

package/file-trigger/index.jsx

@@ -0,0 +1,41 @@
+// Ported from react-aria-components `FileTrigger` (packages/react-aria-components/src/FileTrigger.tsx), Apache-2.0, © Adobe.
+// A FileTrigger allows a user to access the file system with any pressable component (`Button`, `Link`,
+// `<Pressable>`, or custom components built with usePress): a `PressResponder` around the children opens a
+// hidden `<input type="file">` on press.
+// Rivet:
+// - `ref` goes to the hidden input (RAC `useObjectRef(ref)`); the press handler reads the input through a
+//   `ref()` (resumable): the user's `ref()` itself, else an own one merged with the user's ref (`mergeRefValues`).
+// - global DOM props (`data-*`, events, `dir`, …) land on the input, like upstream's `filterDOMProps(rest, { global: true })`.
+// - `onSelect` is an inline arrow / local const to resume.
+import { ref as createRef } from "@rivetjs/runtime/dom";
+import { globalDOMProps } from "../utils/dom-props.js";
+import { mergeRefValues } from "../slots/index.jsx";
+import { PressResponder } from "../interactions/pressable.jsx";
+import { Input } from "../input/index.jsx";
+/**
+ * A FileTrigger allows a user to access the file system with any pressable React Aria or React
+ * Spectrum component, or custom components built with usePress.
+ */
+export function FileTrigger(props) {
+    const { onSelect, acceptedFileTypes, allowsMultiple, defaultCamera, children, acceptDirectory } = props;
+    // A `ref()` from the user is used as is (readable at press time on a resumed page); other ref shapes merge.
+    const userRef = props.ref;
+    const signalRef = typeof userRef === "function" && "set" in userRef ? userRef : undefined;
+    const inputRef = signalRef ?? createRef();
+    const elementRef = signalRef ?? mergeRefValues(userRef, inputRef);
+    const domProps = globalDOMProps(props, ["onClick", "style"]);
+    const accept = acceptedFileTypes?.toString();
+    // Not in the JSX input typings: `capture` (media capture) and `webkitdirectory` (directory picker).
+    const extra = { capture: defaultCamera, webkitdirectory: acceptDirectory ? "" : undefined };
+    return (<>
+      <PressResponder onPress={() => {
+            const input = inputRef();
+            if (input?.value)
+                input.value = "";
+            input?.click();
+        }}>
+        {children}
+      </PressResponder>
+      <Input {...domProps} {...extra} class="" type="file" ref={elementRef} onClick={(e) => e.stopPropagation()} style={{ display: "none" }} accept={accept} onChange={(e) => onSelect?.(e.target.files)} multiple={allowsMultiple}/>
+    </>);
+}

package/flip/index.d.ts

@@ -0,0 +1,59 @@
+/** A box: start-edge `x` (left in LTR, right in RTL), `y`, size; relative to a container. */
+export interface Box {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface FlipItem {
+    el: HTMLElement;
+    from: Box;
+    to: Box;
+    /** The element's own `transform` the offset composes with (default: its inline `transform` at the start). */
+    base?: string;
+    /** Final inline styles (`transform` / `width` / `height`) at the end instead of the ones it had at the start. */
+    final?: () => Readonly<Record<string, string>> | undefined;
+}
+/** A moved item as a driver sees it: the inverted offset (`dx` / `dy`, screen px), its `base` transform, `resize`. */
+export interface FlipMove extends FlipItem {
+    dx: number;
+    dy: number;
+    base: string;
+    resize: boolean;
+}
+/** One running FLIP: `render(t)` writes every item at progress `t` (0 → 1, may overshoot); `done()` when settled. */
+export interface FlipRun {
+    items: readonly FlipMove[];
+    render(t: number): void;
+    done(): void;
+}
+/** Drives a FLIP's progress; returns `stop` (no write: the core commits the final boxes). */
+export interface FlipDriver {
+    play(run: FlipRun): () => void;
+}
+export interface FlipOptions {
+    /** Visible band of the container (container y coordinates): items outside it before and after jump. */
+    viewport?: readonly [number, number];
+    /** Boxes are start-edge in RTL (x from the right). */
+    rtl?: boolean;
+    /** Default: `motion1dDriver()`. */
+    driver?: FlipDriver;
+}
+/** Whether FLIP animations run here: `motion !== false` and no `prefers-reduced-motion: reduce` (false on the server). */
+export declare function flipAllowed(motion: unknown): boolean;
+/** Read phase: the current (visual) boxes of `els` relative to `relativeTo`. */
+export declare function captureBoxes(els: Iterable<HTMLElement>, relativeTo: HTMLElement, rtl?: boolean): Map<HTMLElement, Box>;
+/** Visual boxes of the elements whose FLIP on `container` is still running (empty otherwise). */
+export declare function animatingBoxes(container: HTMLElement, rtl?: boolean): Map<HTMLElement, Box>;
+/** Stops the FLIP running on `container` (its items take their final boxes). */
+export declare function stopFlip(container: HTMLElement): void;
+/** House motion driver (Motion1D; `duration` in embla units, default 25; `friction` default 0.68). */
+export declare function motion1dDriver(options?: {
+    duration?: number;
+    friction?: number;
+}): FlipDriver;
+/**
+ * Write phase: animate `items` on `container` from `from` to `to`. Unchanged items (< 0.5 px) and items outside
+ * `viewport` before and after are skipped. Returns `stop` (final boxes at once).
+ */
+export declare function playFlip(container: HTMLElement, items: Iterable<FlipItem>, options?: FlipOptions): () => void;

package/flip/index.js

@@ -0,0 +1,124 @@
+// Rivet-authored (not a port): the shared FLIP core (extracted from `@rivetjs/cdk/masonry` in motion plan T11; used by
+// masonry relayouts and `@rivetjs/motion/layout`). Elements that changed box start at the old one and travel to the new:
+// - First: `captureBoxes` (one rect read per element, start-edge x relative to a container) or boxes the caller knows;
+// - Last: the new boxes (callers with a pure geometry pass them, nothing read after the writes);
+// - Invert + Play: per frame `transform: translate(…)` for moved elements, `width` / `height` px for resized ones; at
+//   the end the overrides go away (or the item's `final` styles land) and the CSS layout stays.
+// The default driver is the house motion (`../motion` Motion1D: embla's scroll body, the feel of carousels / sheets /
+// sliders); a `FlipDriver` swaps it (a spring, WAAPI). Elements outside `viewport` before and after jump. A new
+// `playFlip` on the same container during a running one stops it first (callers start from `animatingBoxes`); a
+// container unmounted mid-animation stops on its next frame. Browser-only closures, never serialized.
+import { Motion1D } from "../motion/Motion1D.js";
+const running = new WeakMap();
+/** Whether FLIP animations run here: `motion !== false` and no `prefers-reduced-motion: reduce` (false on the server). */
+export function flipAllowed(motion) {
+    if (motion === false || typeof window === "undefined")
+        return false;
+    return !window.matchMedia?.("(prefers-reduced-motion: reduce)").matches;
+}
+const boxOf = (el, g, rtl) => {
+    const r = el.getBoundingClientRect();
+    return { x: rtl ? g.right - r.right : r.left - g.left, y: r.top - g.top, width: r.width, height: r.height };
+};
+/** Read phase: the current (visual) boxes of `els` relative to `relativeTo`. */
+export function captureBoxes(els, relativeTo, rtl) {
+    const g = relativeTo.getBoundingClientRect();
+    const boxes = new Map();
+    for (const el of els)
+        boxes.set(el, boxOf(el, g, rtl));
+    return boxes;
+}
+/** Visual boxes of the elements whose FLIP on `container` is still running (empty otherwise). */
+export function animatingBoxes(container, rtl) {
+    const run = running.get(container);
+    return run
+        ? captureBoxes(run.els.filter((el) => el.isConnected), container, rtl)
+        : new Map();
+}
+/** Stops the FLIP running on `container` (its items take their final boxes). */
+export function stopFlip(container) {
+    running.get(container)?.stop();
+}
+/** House motion driver (Motion1D; `duration` in embla units, default 25; `friction` default 0.68). */
+export function motion1dDriver(options) {
+    return {
+        play(run) {
+            const motion = Motion1D({
+                value: 0,
+                duration: options?.duration ?? 25,
+                friction: options?.friction ?? 0.68,
+                render: (v) => run.render(Math.min(1, v / 1000)),
+                onSettle: () => run.done(),
+            });
+            motion.to(1000);
+            return () => motion.stop();
+        },
+    };
+}
+/**
+ * Write phase: animate `items` on `container` from `from` to `to`. Unchanged items (< 0.5 px) and items outside
+ * `viewport` before and after are skipped. Returns `stop` (final boxes at once).
+ */
+export function playFlip(container, items, options) {
+    running.get(container)?.stop();
+    const viewport = options?.viewport;
+    const visible = (r) => !viewport || (r.y + r.height > viewport[0] && r.y < viewport[1]);
+    const moves = [];
+    for (const item of items) {
+        const { el, from, to } = item;
+        const dx = from.x - to.x;
+        const dy = from.y - to.y;
+        const resize = Math.abs(from.width - to.width) > 0.5 || Math.abs(from.height - to.height) > 0.5;
+        if (Math.abs(dx) < 0.5 && Math.abs(dy) < 0.5 && !resize)
+            continue;
+        if (!visible(from) && !visible(to))
+            continue;
+        const s = el.style;
+        moves.push({ ...item, dx: options?.rtl ? -dx : dx, dy, resize, width: s.width, height: s.height, base: item.base ?? s.transform });
+    }
+    if (!moves.length)
+        return () => { };
+    let halt = () => { };
+    const render = (t) => {
+        // Unmounted mid-animation (no effect needed, so server-placed grids still boot nothing): stop, write nothing.
+        if (!container.isConnected) {
+            halt();
+            if (running.get(container) === entry)
+                running.delete(container);
+            return;
+        }
+        for (const m of moves) {
+            const s = m.el.style;
+            const fin = t >= 1 && m.final ? m.final() : undefined;
+            if (fin) {
+                s.transform = fin.transform ?? "";
+                s.width = fin.width ?? "";
+                s.height = fin.height ?? "";
+                continue;
+            }
+            // Elements placed by their own `transform`: the offset composes with it.
+            s.transform = t >= 1 ? m.base : `translate(${m.dx * (1 - t)}px, ${m.dy * (1 - t)}px)${m.base ? " " + m.base : ""}`;
+            if (m.resize) {
+                if (t >= 1) {
+                    s.width = m.width;
+                    s.height = m.height;
+                }
+                else {
+                    s.width = `${m.from.width + (m.to.width - m.from.width) * t}px`;
+                    s.height = `${m.from.height + (m.to.height - m.from.height) * t}px`;
+                }
+            }
+        }
+    };
+    const stop = () => {
+        halt();
+        render(1);
+        if (running.get(container) === entry)
+            running.delete(container);
+    };
+    const entry = { stop, els: moves.map((m) => m.el) };
+    render(0);
+    running.set(container, entry);
+    halt = (options?.driver ?? motion1dDriver()).play({ items: moves, render, done: stop });
+    return stop;
+}

package/focus/focus-ring.d.ts

@@ -0,0 +1,42 @@
+export interface AriaFocusRingProps {
+    /** Show the ring when something inside the element has focus (true) or only the element itself (default false). */
+    within?: boolean;
+    /** The element is a text input (only Tab / Escape make focus visible). */
+    isTextInput?: boolean;
+    /** The element will be auto focused. */
+    autoFocus?: boolean;
+}
+export interface FocusRingAria {
+    /** Whether the element is focused (signal). */
+    isFocused: () => boolean;
+    /** Whether keyboard focus should be visible (signal). */
+    isFocusVisible: () => boolean;
+    /** Handlers for the element with the focus ring. */
+    focusProps: Record<string, unknown>;
+}
+interface Ring {
+    props: AriaFocusRingProps;
+    focused: {
+        (): boolean;
+        set(v: boolean): unknown;
+    };
+    visible: {
+        set(v: boolean): unknown;
+    };
+    state: {
+        isFocused: boolean;
+        isFocusVisible: boolean;
+        unsubscribe: (() => void) | null;
+    };
+}
+/** @internal focus-change handler of useFocusRing. */
+export declare function focusRingChange(ring: Ring, isFocused: boolean, target: Element | null): void;
+/** @internal */
+export declare function focusRingFocus(ring: Ring, e: FocusEvent): void;
+/** @internal focusin handler of a non-`within` ring: the element's own focus, its blur bound until it fires. */
+export declare function focusRingIn(ring: Ring, e: FocusEvent): void;
+/** @internal */
+export declare function focusRingBlur(ring: Ring, e: FocusEvent): void;
+/** Whether a focus ring should be shown (keyboard focus only). */
+export declare function useFocusRing(props?: AriaFocusRingProps): FocusRingAria;
+export {};