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

package/grid-list/behaviour.d.ts

@@ -0,0 +1,242 @@
+import type { Collection, DisabledBehavior, Direction, FocusStrategy, Key, KeyboardDelegate, LayoutDelegate, Node, Selection } from "../collections/types.js";
+import type { MultipleSelectionManager } from "../selection/manager.js";
+import { type ListState } from "../collections/list-state.js";
+import { type TreeState } from "../collections/tree-state.js";
+import { type SelectableItemStates } from "../selection/selectable-item.js";
+import { type RefLike } from "../selection/utils.js";
+import { type Router } from "../utils/links.jsx";
+import { type AriaGridSelectionCheckboxProps, type GridSelectionCheckboxProps } from "../grid/behaviour.js";
+/** Data shared between useGridList, useGridListItem and useGridListSelectionCheckbox (react-aria `listMap` value). */
+export interface GridListShared {
+    id: string;
+    onAction?: ((key: Key) => void) | undefined;
+    linkBehavior?: "action" | "selection" | "override" | undefined;
+    keyboardNavigationBehavior: "arrow" | "tab";
+    shouldSelectOnPressUp?: boolean | undefined;
+}
+/**
+ * A react-stately ListState / TreeState as the gridlist hooks read it. Build one per event with
+ * `listStateView` / `treeStateView` (Rivet: collection + SelectionManager are class instances).
+ */
+export interface GridListStateLike<T = unknown> {
+    readonly collection: Collection<Node<T>>;
+    readonly selectionManager: MultipleSelectionManager;
+    readonly disabledKeys: Set<Key>;
+    /** TreeState only: the expanded keys. */
+    readonly expandedKeys?: Set<Key> | undefined;
+    /** TreeState only: toggles the expanded state of a key. */
+    readonly toggleKey?: ((key: Key) => void) | undefined;
+    /** Rivet: the data `useGridList` shares with its items (react-aria `listMap.get(state)`). */
+    readonly list?: GridListShared | undefined;
+}
+/** react-aria `listMap`: shared gridlist data per (long-lived) state object. */
+export declare const listMap: WeakMap<object, GridListShared>;
+/** The row id of `key` (`<list id>-<normalized key>`). */
+export declare function getRowId(state: GridListStateLike<any>, key: Key): string;
+/** Strips whitespace from string keys (ids must not contain spaces). */
+export declare function normalizeKey(key: Key): string;
+/**
+ * A gridlist view over a serializable `@rivetjs/cdk/collections/list-state` state (reads state).
+ * `root`: the grid element of a live collection (default: the element with id `state.id`).
+ */
+export declare function listStateView<T>(state: ListState<T>, list?: GridListShared, root?: Element | null): GridListStateLike<T>;
+/** A gridlist view over a serializable `@rivetjs/cdk/collections/tree-state` state (reads state). */
+export declare function treeStateView<T>(state: TreeState<T>, list?: GridListShared): GridListStateLike<T>;
+export interface AriaGridListOptions {
+    /** The element's unique identifier (row ids derive from it). */
+    id?: string | undefined;
+    "aria-label"?: string | undefined;
+    "aria-labelledby"?: string | undefined;
+    "aria-describedby"?: string | undefined;
+    "aria-details"?: string | undefined;
+    /** Whether to auto focus the gridlist or an option. */
+    autoFocus?: boolean | FocusStrategy | undefined;
+    /** Handler that is called when a user performs an action on an item. */
+    onAction?: ((key: Key) => void) | undefined;
+    /** Whether `disabledKeys` applies to all interactions, or only selection. Default "all". */
+    disabledBehavior?: DisabledBehavior | undefined;
+    /** Whether selection should occur on press up instead of press down. */
+    shouldSelectOnPressUp?: boolean | undefined;
+    /** Whether keyboard navigation to focusable elements within items is via arrow keys or Tab. Default "arrow". */
+    keyboardNavigationBehavior?: "arrow" | "tab" | undefined;
+    /** Whether pressing Escape clears the selection. Default "clearSelection". */
+    escapeKeyBehavior?: "clearSelection" | "none" | undefined;
+    /** Whether the list uses virtual scrolling. */
+    isVirtualized?: boolean | undefined;
+    /** Whether typeahead navigation is disabled. */
+    disallowTypeAhead?: boolean | undefined;
+    /** An optional keyboard delegate implementation for type to select. */
+    keyboardDelegate?: KeyboardDelegate | undefined;
+    /** A delegate object that provides layout information for items (default: the DOM). */
+    layoutDelegate?: LayoutDelegate | undefined;
+    /** Whether focus should wrap around when the end/start is reached. */
+    shouldFocusWrap?: boolean | undefined;
+    /** The behavior of links in the collection. Default "action". */
+    linkBehavior?: "action" | "selection" | "override" | undefined;
+    /** @private Which item to focus when tabbing into the collection. */
+    UNSTABLE_focusOnEntry?: "first" | "last" | undefined;
+    /** Rivet: the list element (handlers default to `event.currentTarget`). */
+    ref?: RefLike;
+    /** Rivet: reading direction (default: computed from the element). */
+    direction?: Direction | undefined;
+    /** Rivet: typeahead collator locale (default: document language). */
+    locale?: string | undefined;
+    /** Rivet: list orientation for the keyboard delegate (RAC GridList `orientation`). */
+    orientation?: "vertical" | "horizontal" | undefined;
+    /** Rivet: id of the hidden highlight-selection description element (react-aria `useDescription`). */
+    descriptionId?: string | undefined;
+    /** Rivet: text of announced rows (react-aria `useGridSelectionAnnouncement` `getRowText`). */
+    getRowText?: ((key: Key) => string) | undefined;
+}
+export interface GridListAria {
+    /** Props for the grid element. */
+    gridProps: Record<string, unknown>;
+}
+/** The data `useGridList` shares with its items. Call once per list (component body); pass to the views. */
+export declare function gridListShared(props: AriaGridListOptions): GridListShared;
+type Ev<E extends Event> = E & {
+    currentTarget: EventTarget | null;
+};
+/**
+ * Text of the hidden highlight-selection description element (react-aria
+ * `useHighlightSelectionDescription`; render `<div id={descriptionId} hidden>{text}</div>` when set).
+ */
+export declare function gridListHighlightDescription(props: AriaGridListOptions, state: GridListStateLike<any>): string | undefined;
+/** keydown (capture) on the grid element. */
+export declare const gridListKeyDownCapture: (e: Ev<KeyboardEvent>, props: AriaGridListOptions, state: GridListStateLike<any>) => boolean;
+/** keydown on the grid element (row navigation, typeahead, select all, Escape, Tab out). */
+export declare const gridListKeyDown: (e: Ev<KeyboardEvent>, props: AriaGridListOptions, state: GridListStateLike<any>) => boolean;
+/** focusin on the grid element. */
+export declare const gridListFocus: (e: Ev<FocusEvent>, props: AriaGridListOptions, state: GridListStateLike<any>) => void;
+/** focusout on the grid element. */
+export declare const gridListBlur: (e: Ev<FocusEvent>, props: AriaGridListOptions, state: GridListStateLike<any>) => void;
+/** mousedown on the grid element. */
+export declare const gridListMouseDown: (e: Ev<MouseEvent>, props: AriaGridListOptions, state: GridListStateLike<any>) => void;
+/**
+ * react-aria's `autoFocus` mount effect (useSelectableCollection): call once the grid element
+ * (`props.ref`) is connected, e.g. from a `clientEffect`; returns false while it still waits for items.
+ */
+export declare function gridListAutoFocus(props: AriaGridListOptions, state: GridListStateLike<any>): boolean;
+/**
+ * Provides the behavior and accessibility implementation for a list component with interactive
+ * children (react-aria `useGridList` → `gridListProps`). Returns the grid element's attributes
+ * (bind values as accessors); wire the `gridList<Event>(event, props, state)` handlers on the same
+ * element. `state.list` (or `listMap`) must carry the `gridListShared(props)` data.
+ */
+export declare function gridListProps(props: AriaGridListOptions, state: GridListStateLike<any>, hasTabbableChild?: boolean): GridListAria;
+export interface AriaGridListItemOptions {
+    /** The node of the row. */
+    node: Node<unknown>;
+    /** Whether the list row is contained in a virtual scroller. */
+    isVirtualized?: boolean | undefined;
+    /** Whether selection should occur on press up instead of press down. */
+    shouldSelectOnPressUp?: boolean | undefined;
+    /** Whether this item has children, even if not loaded yet. */
+    hasChildItems?: boolean | undefined;
+    /** Whether the row or its first focusable child element should be focused when the row is focused. Default "row". */
+    focusMode?: "child" | "row" | undefined;
+    /** Whether the row supports arrow key navigation even when the collection uses Tab navigation. */
+    allowsArrowNavigation?: boolean | undefined;
+    /** Rivet: the row element (handlers default to `event.currentTarget`). */
+    ref?: RefLike;
+    /** Rivet: reading direction (default: computed from the row). */
+    direction?: Direction | undefined;
+    /** Rivet: id of the row's description element (react-aria `useSlotId`; set when a description slot renders). */
+    descriptionId?: string | undefined;
+    /** Rivet: router for synthetic link attributes (RouterContext value). */
+    router?: Router | undefined;
+    /** Rivet: locale of the selection announcement. */
+    locale?: string | undefined;
+    /** Rivet: text of announced rows (default: the node's textValue). */
+    getRowText?: ((key: Key) => string) | undefined;
+}
+export interface GridListItemAria extends SelectableItemStates {
+    /** Props for the list row element. */
+    rowProps: Record<string, unknown>;
+    /** Props for the grid cell element within the list row. */
+    gridCellProps: Record<string, unknown>;
+    /** Props for the list item description element, if any. */
+    descriptionProps: Record<string, unknown>;
+}
+/** Focus the row (focusMode "child": its first tabbable child) — react-aria's item `focus()`. */
+export declare function focusRow(props: AriaGridListItemOptions, row: HTMLElement | null): void;
+/**
+ * keydown (capture) on the row: Left / Right move between focusable children (arrow
+ * keyboardNavigationBehavior, RTL aware) and back to the row; tree expand / collapse; Up / Down
+ * from a child are re-dispatched from the row's parent so row navigation handles them. Wire it
+ * when `keyboardNavigationBehavior === "arrow"` or `allowsArrowNavigation`.
+ */
+export declare function gridListItemKeyDownCapture(e: Ev<KeyboardEvent>, props: AriaGridListItemOptions, state: GridListStateLike<any>): void;
+/**
+ * keydown on the row: Tab navigation between children ("tab" behavior), tree expansion keys, then
+ * the selectable item's Space / Enter press unless propagation was stopped.
+ */
+export declare function gridListItemKeyDown(e: Ev<KeyboardEvent>, props: AriaGridListItemOptions, state: GridListStateLike<any>): void;
+/** keyup on the row (keyboard press end). */
+export declare const gridListItemKeyUp: (e: Ev<KeyboardEvent>, props: AriaGridListItemOptions, state: GridListStateLike<any>) => void;
+/**
+ * focusin on the row: a focused child makes the row the focused key (unless focus is visible:
+ * keyboard users return to the previously focused row); focusMode "child" moves focus from the row
+ * to its first tabbable child.
+ */
+export declare function gridListItemFocus(e: Ev<FocusEvent>, props: AriaGridListItemOptions, state: GridListStateLike<any>): void;
+/** pointerdown on the row. */
+export declare const gridListItemPointerDown: (e: Ev<PointerEvent>, props: AriaGridListItemOptions, state: GridListStateLike<any>) => void;
+/** pointerup on the row. */
+export declare const gridListItemPointerUp: (e: Ev<PointerEvent>, props: AriaGridListItemOptions, state: GridListStateLike<any>) => void;
+/** pointercancel / pointerleave on the row. */
+export declare const gridListItemPointerCancel: (e: Ev<PointerEvent>, props: AriaGridListItemOptions, state: GridListStateLike<any>) => void;
+/** click on the row (the press). */
+export declare const gridListItemClick: (e: Ev<MouseEvent>, props: AriaGridListItemOptions, state: GridListStateLike<any>) => void;
+/** dblclick on the row (secondary action with selectionBehavior "replace"). */
+export declare const gridListItemDoubleClick: (e: Ev<MouseEvent>, props: AriaGridListItemOptions, state: GridListStateLike<any>) => void;
+/** dragstart on the row. */
+export declare const gridListItemDragStart: (e: Ev<DragEvent>, props: AriaGridListItemOptions, state: GridListStateLike<any>) => void;
+/**
+ * Provides the behavior and accessibility implementation for a row in a grid list (react-aria
+ * `useGridListItem` → `gridListItemProps`): row / grid cell / description attributes + item states
+ * (reads state: bind as accessors). Wire `gridListItem<Event>(event, props, state)` on the row;
+ * `gridListItemKeyDownCapture` only when `keyboardNavigationBehavior === "arrow"` or `allowsArrowNavigation`.
+ */
+export declare function gridListItemProps(props: AriaGridListItemOptions, state: GridListStateLike<any>): GridListItemAria;
+export interface AriaGridListSectionProps {
+    /** An accessibility label for the section. Required if `heading` is not present. */
+    "aria-label"?: string | undefined;
+    /** Rivet: id of the section heading (react-aria `useSlotId`; omit when no header renders). */
+    headingId?: string | undefined;
+}
+export interface GridListSectionAria {
+    /** Props for the wrapper list item. */
+    rowProps: Record<string, unknown>;
+    /** Props for the heading element, if any. */
+    rowHeaderProps: Record<string, unknown>;
+    /** Props for the grid's row group element. */
+    rowGroupProps: Record<string, unknown>;
+}
+/** Provides the behavior and accessibility implementation for a section in a grid list (react-aria `useGridListSection` → `gridListSectionProps`). */
+export declare function gridListSectionProps(props: AriaGridListSectionProps, _state?: GridListStateLike<any>): GridListSectionAria;
+export interface GridSelectionCheckboxAria {
+    /** Props for the row selection checkbox element (RAC Checkbox props; `onChange` → `gridListSelectionCheckboxChange`). */
+    checkboxProps: GridSelectionCheckboxProps & {
+        "aria-labelledby": string;
+    };
+}
+/**
+ * Provides the behavior and accessibility implementation for a selection checkbox in a grid list
+ * (react-aria `useGridListSelectionCheckbox` → `gridListSelectionCheckboxProps`). Reads state.
+ */
+export declare function gridListSelectionCheckboxProps(props: AriaGridSelectionCheckboxProps, state: GridListStateLike<any>): GridSelectionCheckboxAria;
+/** The selection checkbox `onChange`: toggles the row's selection (announced). */
+export declare function gridListSelectionCheckboxChange(isSelected: boolean, props: AriaGridSelectionCheckboxProps & {
+    getRowText?: (key: Key) => string;
+}, state: GridListStateLike<any>): void;
+export type { AriaGridSelectionCheckboxProps };
+export type { Selection };
+/**
+ * After the rendered items changed (live mode): react-stately `useFocusedKeyReset` (a removed focused
+ * item hands the focused key to the next / previous enabled item of the previous collection) + the
+ * react-aria focus effects that follow it (useSelectableItem focuses the new focused row;
+ * useSelectableCollection focuses the collection when the focused key became null). `previous` is the
+ * snapshot returned by the last call; call from a client effect after the DOM updated.
+ */
+export declare function gridListItemsChanged<T>(state: ListState<T>, root: HTMLElement, previous: Collection<Node<T>> | undefined): Collection<Node<T>>;