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

package/masonry/masonry-layout.d.ts

@@ -0,0 +1,57 @@
+import type { Key } from "../collections/index.js";
+import { LayoutInfo } from "../virtualizer/layout-info.js";
+import { Rect } from "../virtualizer/rect.js";
+import { Size } from "../virtualizer/size.js";
+import type { InvalidationContext } from "../virtualizer/types.js";
+import { WaterfallLayout } from "../virtualizer/waterfall-layout.js";
+import { type JustifiedLastRow } from "./justified.js";
+import { type Breakpoint, type Responsive } from "./layout.js";
+export interface MasonryLayoutOptions {
+    /** Breakpoints (columns + `[column, row]` gaps per container width). */
+    breakpoints: Breakpoint[];
+    /** px added to every item (captions). */
+    extra?: number;
+    /** Greedy reference width override. */
+    referenceWidth?: number | null;
+    /** Loader height in px. Default 48. */
+    loaderHeight?: number;
+    /** Justified rows instead of columns (unknown ratios count as 1; spans = weights). */
+    justified?: {
+        rowHeight: Responsive<number>;
+        tolerance?: number;
+        minRowHeight?: number;
+        maxRowHeight?: number;
+        lastRow?: JustifiedLastRow;
+    } | null;
+    /** Bumped by the component when live per-item inputs (spans, ratios) change: invalidates the layout. */
+    version?: number;
+}
+export declare class MasonryLayout<T extends object> extends WaterfallLayout<T, any> {
+    private infos;
+    private measured;
+    private size;
+    /** Last placement as rects in collection order (keyboard geometry). */
+    rects: {
+        key: Key;
+        rect: Rect;
+    }[];
+    private ratioOf;
+    private spanOf;
+    constructor(ratioOf: (item: T) => number | null, spanOf?: (item: T) => Responsive<number> | null | undefined);
+    shouldInvalidateLayoutOptions(next: MasonryLayoutOptions, prev: MasonryLayoutOptions): boolean;
+    /** Rects of `items` (key + value) at width `width` (keyboard geometry outside the window, tests). Pure. */
+    rectsFor(items: readonly {
+        key: Key;
+        value: T;
+    }[], width: number, options: MasonryLayoutOptions): {
+        key: Key;
+        rect: Rect;
+    }[];
+    private place;
+    update(context: InvalidationContext<MasonryLayoutOptions>): void;
+    getLayoutInfo(key: Key): LayoutInfo;
+    getContentSize(): Size;
+    getVisibleLayoutInfos(rect: Rect): LayoutInfo[];
+    updateItemSize(key: Key, size: Size): boolean;
+    getKeyRange(from: Key, to: Key): Key[];
+}

package/masonry/masonry-layout.js

@@ -0,0 +1,159 @@
+import { LayoutInfo } from "../virtualizer/layout-info.js";
+import { Rect } from "../virtualizer/rect.js";
+import { Size } from "../virtualizer/size.js";
+import { WaterfallLayout } from "../virtualizer/waterfall-layout.js";
+import { rectsAt } from "./geometry.js";
+import { placeJustified } from "./justified.js";
+import { breakpointAt, columnWidth, placeColumns, referenceWidths, responsiveAt } from "./layout.js";
+export class MasonryLayout extends WaterfallLayout {
+    infos = new Map();
+    measured = new Map();
+    size = new Size();
+    /** Last placement as rects in collection order (keyboard geometry). */
+    rects = [];
+    ratioOf;
+    spanOf;
+    constructor(ratioOf, spanOf) {
+        super();
+        this.ratioOf = ratioOf;
+        this.spanOf = spanOf ?? (() => 1);
+    }
+    shouldInvalidateLayoutOptions(next, prev) {
+        return JSON.stringify(next) !== JSON.stringify(prev);
+    }
+    /** Rects of `items` (key + value) at width `width` (keyboard geometry outside the window, tests). Pure. */
+    rectsFor(items, width, options) {
+        const { rects } = this.place(items, width, options);
+        return items.map((item, i) => ({ key: item.key, rect: rects[i] }));
+    }
+    place(nodes, width, options) {
+        const breakpoints = options.breakpoints?.length ? options.breakpoints : [{ min: 0, columns: 2, gap: [16, 16] }];
+        const extra = options.extra ?? 0;
+        const b = breakpointAt(breakpoints, width);
+        const bp = breakpoints[b];
+        const [gapX, gapY] = bp.gap;
+        const n = options.justified ? 1 : bp.columns;
+        const w = Math.max(0, columnWidth(width, n, gapX));
+        const exact = new Uint8Array(nodes.length);
+        let rects;
+        if (options.justified) {
+            // Justified rows at the real width (client-only: no server picture to keep).
+            const aspects = new Float64Array(nodes.length);
+            nodes.forEach((node, i) => {
+                const ratio = node.value ? this.ratioOf(node.value) : null;
+                const weight = node.value ? responsiveAt(this.spanOf(node.value), bp.min, 1) : 1;
+                aspects[i] = (ratio ?? 1) * Math.max(0.01, Number(weight) || 1);
+                exact[i] = 1;
+            });
+            const j = options.justified;
+            const g = placeJustified(aspects, width, {
+                rowHeight: responsiveAt(j.rowHeight, bp.min, 240),
+                tolerance: j.tolerance,
+                minRowHeight: j.minRowHeight,
+                maxRowHeight: j.maxRowHeight,
+                lastRow: j.lastRow,
+                gap: bp.gap,
+            });
+            rects = rectsAt(g, width).map((r) => new Rect(r.x, r.y, r.width, r.height));
+        }
+        else {
+            const refW = columnWidth(referenceWidths(breakpoints, options.referenceWidth)[b], n, gapX);
+            const alpha = new Float64Array(nodes.length);
+            const beta = new Float64Array(nodes.length);
+            const span = new Uint16Array(nodes.length);
+            nodes.forEach((node, i) => {
+                const ratio = node.value ? this.ratioOf(node.value) : null;
+                const h = this.measured.get(node.key);
+                span[i] = Math.max(1, Math.floor(Number(node.value ? responsiveAt(this.spanOf(node.value), bp.min, 1) : 1)) || 1);
+                if (ratio) {
+                    alpha[i] = 1 / ratio;
+                    beta[i] = extra;
+                    exact[i] = 1;
+                }
+                else if (h != null)
+                    beta[i] = h;
+                else {
+                    alpha[i] = 1;
+                    beta[i] = extra;
+                }
+            });
+            const run = placeColumns({ alpha, beta, span }, n, refW, w, w, gapX, gapY);
+            rects = rectsAt(run.geometry, w).map((r) => new Rect(r.x, r.y, r.width, r.height));
+        }
+        return { rects, exact, columns: n };
+    }
+    update(context) {
+        const options = (context.layoutOptions ?? {});
+        const width = this.virtualizer.size.width;
+        if (context.sizeChanged)
+            this.measured.clear();
+        const collection = this.virtualizer.collection;
+        const nodes = [];
+        let loader = null;
+        for (const node of collection) {
+            if (node.type === "loader")
+                loader = node;
+            else if (node.type === "item")
+                nodes.push(node);
+        }
+        const { rects, exact, columns } = this.place(nodes, width, options);
+        this.numColumns = columns;
+        const infos = new Map();
+        const keyed = [];
+        let height = 0;
+        nodes.forEach((node, i) => {
+            const rect = rects[i];
+            const info = new LayoutInfo(node.type, node.key, rect);
+            info.estimatedSize = !exact[i] && !this.measured.has(node.key);
+            info.allowOverflow = true;
+            info.content = node;
+            infos.set(node.key, info);
+            keyed.push({ key: node.key, rect });
+            if (rect.maxY > height)
+                height = rect.maxY;
+        });
+        if (loader) {
+            const loaderHeight = loader.props?.isLoading ? (options.loaderHeight ?? 48) : 0;
+            const info = new LayoutInfo("loader", loader.key, new Rect(0, height, width, loaderHeight));
+            infos.set(loader.key, info);
+            height = info.rect.maxY;
+        }
+        this.infos = infos;
+        this.rects = keyed;
+        this.size = new Size(width, height);
+    }
+    getLayoutInfo(key) {
+        return this.infos.get(key);
+    }
+    getContentSize() {
+        return this.size;
+    }
+    getVisibleLayoutInfos(rect) {
+        const out = [];
+        for (const info of this.infos.values())
+            if (info.rect.intersects(rect) || this.virtualizer.isPersistedKey(info.key) || info.type === "loader")
+                out.push(info);
+        return out;
+    }
+    updateItemSize(key, size) {
+        const info = this.infos.get(key);
+        if (!info || !size || !info.estimatedSize)
+            return false;
+        if (this.measured.get(key) === size.height)
+            return false;
+        this.measured.set(key, size.height);
+        return true;
+    }
+    getKeyRange(from, to) {
+        const a = this.infos.get(from);
+        const b = this.infos.get(to);
+        if (!a || !b)
+            return [];
+        const rect = a.rect.union(b.rect);
+        const keys = [];
+        for (const info of this.infos.values())
+            if (info.type === "item" && rect.intersection(info.rect).area > info.rect.area / 2)
+                keys.push(info.key);
+        return keys;
+    }
+}

package/masonry/masonry.css

@@ -0,0 +1,29 @@
+/* @rivetjs/cdk/masonry.css — optional, perf only (layout is identical without it).
+   Registers the Masonry / Bento grid custom properties as inherited lengths so a server-rendered page computes each
+   masked column width once on the grid; unregistered, every item re-parses the clamp() token stream (~3x slower style
+   recalc for 1k items). Components register the same names from JS when they render on the client. 12 breakpoints (justified: rowHeight keys + up to 7 tolerance splits). */
+@property --rv-mw { syntax: "<length>"; inherits: true; initial-value: 0px; }
+@property --rv-m0 { syntax: "<length>"; inherits: true; initial-value: 0px; }
+@property --rv-w0 { syntax: "<length>"; inherits: true; initial-value: 0px; }
+@property --rv-m1 { syntax: "<length>"; inherits: true; initial-value: 0px; }
+@property --rv-w1 { syntax: "<length>"; inherits: true; initial-value: 0px; }
+@property --rv-m2 { syntax: "<length>"; inherits: true; initial-value: 0px; }
+@property --rv-w2 { syntax: "<length>"; inherits: true; initial-value: 0px; }
+@property --rv-m3 { syntax: "<length>"; inherits: true; initial-value: 0px; }
+@property --rv-w3 { syntax: "<length>"; inherits: true; initial-value: 0px; }
+@property --rv-m4 { syntax: "<length>"; inherits: true; initial-value: 0px; }
+@property --rv-w4 { syntax: "<length>"; inherits: true; initial-value: 0px; }
+@property --rv-m5 { syntax: "<length>"; inherits: true; initial-value: 0px; }
+@property --rv-w5 { syntax: "<length>"; inherits: true; initial-value: 0px; }
+@property --rv-m6 { syntax: "<length>"; inherits: true; initial-value: 0px; }
+@property --rv-w6 { syntax: "<length>"; inherits: true; initial-value: 0px; }
+@property --rv-m7 { syntax: "<length>"; inherits: true; initial-value: 0px; }
+@property --rv-w7 { syntax: "<length>"; inherits: true; initial-value: 0px; }
+@property --rv-m8 { syntax: "<length>"; inherits: true; initial-value: 0px; }
+@property --rv-w8 { syntax: "<length>"; inherits: true; initial-value: 0px; }
+@property --rv-m9 { syntax: "<length>"; inherits: true; initial-value: 0px; }
+@property --rv-w9 { syntax: "<length>"; inherits: true; initial-value: 0px; }
+@property --rv-m10 { syntax: "<length>"; inherits: true; initial-value: 0px; }
+@property --rv-w10 { syntax: "<length>"; inherits: true; initial-value: 0px; }
+@property --rv-m11 { syntax: "<length>"; inherits: true; initial-value: 0px; }
+@property --rv-w11 { syntax: "<length>"; inherits: true; initial-value: 0px; }

package/menu/behaviour.d.ts

@@ -0,0 +1,205 @@
+import { type FocusStrategy, type Key } from "../_adapters/collections.js";
+import { type PressEvent } from "../_adapters/interactions.js";
+import { type Router } from "../utils/links.jsx";
+import { type MenuState, type MenuTriggerState, type MenuTriggerType, type SubmenuTriggerState } from "../state/menu.js";
+export { getItemId } from "../state/list.js";
+export { submenuId } from "../state/menu.js";
+export interface AriaMenuTriggerProps {
+    /** The type of menu that the menu trigger opens. */
+    type?: "menu" | "listbox";
+    /** Whether menu trigger is disabled. */
+    isDisabled?: boolean;
+    /** How menu is triggered. */
+    trigger?: MenuTriggerType;
+    /** Rivet: locale of the long-press description (RA: useLocalizedStringFormatter). */
+    locale?: string;
+}
+export interface MenuTriggerAria {
+    /** Props for the menu trigger element (AriaButtonProps: pass to a Button / its ButtonContext). */
+    menuTriggerProps: Record<string, unknown>;
+    /** Props for the menu. */
+    menuProps: {
+        id: string;
+        "aria-labelledby": string;
+        autoFocus: () => FocusStrategy | true;
+        onClose: () => void;
+    };
+    /** Rivet: the long-press description to render once (`<span id hidden>{text}</span>`), when `trigger="longPress"`. */
+    longPressDescription?: {
+        id: string;
+        text: string;
+    };
+}
+/** Keys the trigger may handle (`data-rk`: a cold key does not scroll while the handler loads). */
+export declare const menuTriggerKeys: (trigger?: MenuTriggerType) => string;
+/** The trigger's keyboard shortcuts (useKeyboard `shortcuts`); returns whether the key was handled. */
+export declare function menuTriggerKeyDown(e: KeyboardEvent, props: AriaMenuTriggerProps, state: MenuTriggerState): boolean;
+/** `onPressStart` of a "press" trigger: open on mouse / pen down (touch and keyboard wait). */
+export declare function menuTriggerPressStart(e: PressEvent, props: AriaMenuTriggerProps, state: MenuTriggerState): void;
+/** `onPress` of a "press" trigger: touch toggles on press up. */
+export declare function menuTriggerPress(e: PressEvent, props: AriaMenuTriggerProps, state: MenuTriggerState): void;
+/** useLongPress `onLongPressStart` of a "longPress" trigger. */
+export declare const menuTriggerLongPressStart: (_e: unknown, _props: AriaMenuTriggerProps, state: MenuTriggerState) => void;
+/** useLongPress `onLongPress` of a "longPress" trigger. */
+export declare const menuTriggerLongPress: (_e: unknown, _props: AriaMenuTriggerProps, state: MenuTriggerState) => void;
+/** useMenuTrigger's `onContextMenu` (from useContextMenu): anchor at the pointer, open. */
+export declare function menuTriggerContextMenuOpen(target: Element, x: number, y: number, state: MenuTriggerState): void;
+/** Stop the outside right-click closer (call when a context menu closes). */
+export declare const menuTriggerContextMenuClosed: (state: MenuTriggerState) => void;
+/** `contextmenu` on a "contextMenu" trigger (useContextMenu onContextMenu). */
+export declare function menuTriggerContextMenu(e: MouseEvent, props: AriaMenuTriggerProps, state: MenuTriggerState): void;
+/** `keydown` on a "contextMenu" trigger: macOS Ctrl+Enter workaround (useContextMenu). */
+export declare function menuTriggerContextMenuKeyDown(e: KeyboardEvent, props: AriaMenuTriggerProps, state: MenuTriggerState): void;
+/** iOS long press on a "contextMenu" trigger (iOS fires no contextmenu event). */
+export declare function menuTriggerContextMenuLongPress(e: {
+    target: Element;
+    x: number;
+    y: number;
+}, _props: AriaMenuTriggerProps, state: MenuTriggerState): void;
+/** Whether the context-menu trigger uses the iOS long-press path. */
+export declare const contextMenuUsesLongPress: () => boolean;
+/**
+ * Provides the behavior and accessibility implementation for a menu trigger (react-aria `useMenuTrigger`).
+ * The press / keyboard / context-menu handlers are inline arrows over the exported free functions.
+ */
+export declare function menuTriggerProps(props: AriaMenuTriggerProps, state: MenuTriggerState): MenuTriggerAria;
+export interface AriaMenuOptions {
+    "aria-label"?: string;
+    "aria-labelledby"?: string;
+    "aria-describedby"?: string;
+    id?: string;
+    /** Whether pressing the escape key should clear selection in the menu or not. @default 'clearSelection' */
+    escapeKeyBehavior?: "clearSelection" | "none";
+    onKeyDown?: (e: KeyboardEvent) => void;
+    onKeyUp?: (e: KeyboardEvent) => void;
+    /** Rivet: the router links in the menu navigate with (RA `useRouter()`); default native. */
+    router?: Router;
+}
+/** Keys the menu may handle (`data-rk`). */
+export declare const menuKeys: (state: MenuState) => string;
+/** Event types the menu element handles (wire each to `menuEvent`). */
+export declare const MENU_EVENTS: readonly ["keydown", "keyup", "pointerdown", "pointerup", "pointercancel", "click", "mousedown", "pointerover", "pointerout", "focusin", "focusout", "dragstart", "scroll"];
+/**
+ * Attributes of the menu element (useMenu `menuProps` without handlers: wire `MENU_EVENTS` to
+ * `menuEvent`). Accessors bind.
+ */
+export declare function menuProps(props: AriaMenuOptions, state: MenuState): Record<string, unknown>;
+/**
+ * useMenuItem's `onClick` body: item `onAction` → menu `onAction`, link navigation through the router,
+ * then the close rule. `interaction` = how the item was activated.
+ */
+export declare function menuItemClick(state: MenuState, root: HTMLElement, item: HTMLElement, e: Event, router?: Router): void;
+/**
+ * Attach the safe-triangle pointer tracking (useSafelyMouseToSubmenu) for an open submenu: call from
+ * the submenu popover's open path with the parent menu and submenu elements; returns the cleanup.
+ */
+export declare function menuSubmenuOpened(sub: SubmenuTriggerState, parentMenu: HTMLElement | null, submenu: HTMLElement | null, options?: {
+    isDisabled?: boolean;
+    preventPointerDown?: boolean;
+}): () => void;
+/** The submenu closed: stop its safe-triangle tracking. */
+export declare const menuSubmenuClosed: (sub: SubmenuTriggerState) => void;
+/** Keydown of a submenu trigger item (useSubmenuTrigger `submenuTriggerKeyboardProps`); true when handled. */
+export declare function submenuTriggerKeyDown(e: KeyboardEvent, item: HTMLElement, sub: SubmenuTriggerState, isDisabled?: boolean): boolean;
+/**
+ * Keydown on a submenu (useSubmenuTrigger `submenuProps` keyboard): ArrowLeft (ltr) / ArrowRight (rtl) /
+ * Escape close this level and focus its trigger item. True when handled.
+ */
+export declare function submenuKeyDown(e: KeyboardEvent, menu: HTMLElement, state: MenuState): boolean;
+/**
+ * `react-aria-focus` on the menu (useSelectableCollection, virtual focus from an Autocomplete input): the
+ * menu takes virtual focus; `focusStrategy: "first"` focuses the first item once the items update.
+ */
+export declare function menuVirtualFocus(e: Event, state: MenuState): void;
+/** `react-aria-clear-focus` on the menu (virtual focus): drop virtual focus, optionally the focused key. */
+export declare function menuClearVirtualFocus(e: Event, state: MenuState): void;
+/**
+ * The menu's items changed (filtered / loaded; call from a client effect): with a pending "virtual focus
+ * first" request, focus the first item, or clear the active descendant when nothing is focusable
+ * (useSelectableCollection's collection-update effect).
+ */
+export declare function menuCollectionUpdated(state: MenuState, root: HTMLElement): void;
+/**
+ * The menu element's delegated handler: useMenu (useSelectableList) + every item's useMenuItem /
+ * useSubmenuTrigger. Wire `MENU_EVENTS` as `on…={(e) => menuEvent(e, props, state)}`.
+ */
+export declare function menuEvent(event: Event, props: AriaMenuOptions, state: MenuState, root?: HTMLElement): void;
+/** Focus the menu per its `autoFocus` (react-aria useSelectableList `autoFocus`): call when it opens. */
+export declare function menuAutoFocus(state: MenuState, menu: HTMLElement, autoFocus: boolean | FocusStrategy | null | undefined): void;
+export interface AriaMenuItemProps {
+    /** The unique key for the menu item. */
+    key: Key;
+    /** Whether the menu item is disabled (RAC MenuItem `isDisabled`; also `disabledKeys`). */
+    isDisabled?: boolean;
+    "aria-label"?: string;
+    "aria-describedby"?: string;
+    /** What kind of popup the item opens (submenu triggers). */
+    "aria-haspopup"?: "menu" | "dialog";
+    "aria-expanded"?: () => boolean;
+    "aria-controls"?: () => string | undefined;
+    /** Rivet: whether a label / description / keyboard shortcut element is rendered (RA `useSlotId`). */
+    hasLabel?: boolean;
+    hasDescription?: boolean;
+    hasKeyboardShortcut?: boolean;
+}
+export interface MenuItemAria {
+    menuItemProps: Record<string, unknown>;
+    labelProps: {
+        id: string;
+    };
+    descriptionProps: {
+        id: string;
+    };
+    keyboardShortcutProps: {
+        id: string;
+    };
+}
+/** Item attributes (useMenuItem `menuItemProps` without handlers: the menu's `menuEvent` handles them). */
+export declare function menuItemProps(props: AriaMenuItemProps, state: MenuState, selectionMode?: string): MenuItemAria;
+export interface AriaMenuSectionProps {
+    /** Whether the section has a heading (RA `heading`). */
+    heading?: boolean;
+    /** An accessibility label for the section. Required if `heading` is not present. */
+    "aria-label"?: string;
+    /** Rivet: id of the heading (RA useId), derived from the section key. */
+    headingId: string;
+}
+/** useMenuSection: `{ itemProps, headingProps, groupProps }`. */
+export declare function menuSectionProps(props: AriaMenuSectionProps): {
+    itemProps: {
+        role: "presentation";
+    };
+    headingProps: Record<string, unknown>;
+    groupProps: Record<string, unknown>;
+};
+export interface AriaSubmenuTriggerProps {
+    /** Whether the submenu trigger is disabled. */
+    isDisabled?: boolean;
+    /** The type of the contents that the submenu trigger opens. */
+    type?: "dialog" | "menu";
+    /** The delay time in milliseconds for the submenu to appear after hovering over the trigger. @default 200 */
+    delay?: number;
+    /** Rivet: the parent menu's state (ids). */
+    parent: MenuState;
+}
+/** useSubmenuTrigger: `{ submenuTriggerProps, submenuProps, popoverProps }` (handlers: `menuEvent` + `submenuKeyDown`). */
+export declare function submenuTriggerProps(props: AriaSubmenuTriggerProps, state: SubmenuTriggerState): {
+    submenuTriggerProps: {
+        id: string;
+        "aria-controls": () => string | undefined;
+        "aria-haspopup": "dialog" | "menu" | undefined;
+        "aria-expanded": () => boolean;
+        isOpen: () => boolean;
+    };
+    submenuProps: {
+        onClose?: (() => void) | undefined;
+        autoFocus?: (() => FocusStrategy | undefined) | undefined;
+        id: string;
+        "aria-labelledby": string;
+        submenuLevel: number;
+    };
+    popoverProps: {
+        isNonModal: boolean;
+        shouldCloseOnInteractOutside: (target: Element) => boolean;
+    };
+};