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

package/_adapters/selection.d.ts

@@ -0,0 +1,109 @@
+import { SelectionManager, type FocusStrategy, type Key, type KeyboardDelegate, type MultipleSelectionState, type Orientation } from "./collections.js";
+import { type PressEvent } from "./interactions.js";
+export type LinkBehavior = "action" | "selection" | "override" | "none";
+/** Static (serializable) options of a selectable collection + its items. */
+export interface SelectableOptions {
+    /** react-aria `autoFocus` (applied by the opener, e.g. a menu trigger: see `autoFocusCollection`). */
+    shouldFocusWrap?: boolean;
+    disallowEmptySelection?: boolean;
+    disallowSelectAll?: boolean;
+    escapeKeyBehavior?: "clearSelection" | "none";
+    /** Default: `selectionBehavior === "replace"`. */
+    selectOnFocus?: boolean;
+    disallowTypeAhead?: boolean;
+    shouldUseVirtualFocus?: boolean;
+    allowsTabNavigation?: boolean;
+    linkBehavior?: LinkBehavior;
+    orientation?: Orientation;
+    layout?: "stack" | "grid";
+    shouldSelectOnPressUp?: boolean;
+    allowsDifferentPressOrigin?: boolean;
+    shouldFocusOnHover?: boolean;
+}
+/** A selectable collection: its selection state, static options and action callback. */
+export interface SelectableCollection extends MultipleSelectionState {
+    readonly options: SelectableOptions;
+    /** RAC `onAction(key)` (resumable function prop). */
+    readonly onAction?: ((key: Key) => void) | undefined;
+    /** Sections with their own selection (RAC `MenuSection selectionMode`), by section key. */
+    readonly groups?: Readonly<Record<string, MultipleSelectionState>> | undefined;
+}
+/** The manager selecting `key`: its section's own (GroupSelectionManager) or the collection's. */
+export declare function groupManager(list: SelectableCollection, root: HTMLElement, manager: SelectionManager, key: Key): SelectionManager;
+/** Extra press callbacks of an item kind (menu items close the menu on press up, …). */
+export interface ItemPressHooks {
+    onPressStart?(list: SelectableCollection, key: Key, e: PressEvent, root: HTMLElement): void;
+    onPressUp?(list: SelectableCollection, key: Key, e: PressEvent, root: HTMLElement): void;
+    onPress?(list: SelectableCollection, key: Key, e: PressEvent, root: HTMLElement): void;
+    /** Keydown on an item, before the collection handles it; return true when handled. */
+    onKeyDown?(list: SelectableCollection, key: Key, e: KeyboardEvent, root: HTMLElement): boolean | void;
+    /** Called after the item performed its action (menu: close). */
+    onAction?(list: SelectableCollection, key: Key, root: HTMLElement): void;
+}
+/** Selection manager over the rendered collection under `root`. */
+export declare const managerOf: (list: MultipleSelectionState, root: HTMLElement) => SelectionManager;
+/** Keyboard delegate of `root` (useSelectableList's default `ListKeyboardDelegate`). */
+export declare function delegateOf(list: SelectableCollection, root: HTMLElement, manager: SelectionManager): KeyboardDelegate;
+/**
+ * Apply the focused key to the DOM: focus the item (or move virtual focus to it) and scroll it into
+ * view after keyboard navigation. Call at the end of a handler that may have changed the focused key.
+ */
+export declare function syncFocus(list: SelectableCollection, root: HTMLElement, previous: Key | null, force?: boolean): void;
+export { typeSelectKeyDown, _resetTypeSelect } from "./type-select.js";
+/**
+ * Collection keydown: arrows (orientation, RTL), Home / End (Ctrl: global), PageUp / PageDown,
+ * Ctrl/Cmd+A, Escape (clear selection), Tab (leave the collection), Shift extends, the platform's
+ * non-contiguous modifier moves focus without selecting. Returns true when handled.
+ */
+export declare function collectionNavigate(list: SelectableCollection, root: HTMLElement, manager: SelectionManager, delegate: KeyboardDelegate, e: KeyboardEvent): boolean;
+/** Keys a collection's keydown may handle (`data-rk`: held while the handler chunk loads). */
+export declare function collectionKeys(options: SelectableOptions): string;
+/** The item element an event happened in (an own `[data-key]` of `root`, not a section). */
+export declare function itemOf(root: Element, target: EventTarget | null): HTMLElement | null;
+interface ItemModel {
+    key: Key;
+    isDisabled: boolean;
+    allowsSelection: boolean;
+    allowsActions: boolean;
+    hasPrimaryAction: boolean;
+    hasSecondaryAction: boolean;
+    hasAction: boolean;
+    hasLinkAction: boolean;
+    longPressEnabled: boolean;
+}
+/** RAC item state flags of `key` for custom markup (`allowsSelection`, `hasAction`). */
+export declare function itemStates(list: SelectableCollection, root: HTMLElement, key: Key): Pick<ItemModel, "allowsSelection" | "hasAction" | "isDisabled">;
+type Ev<E extends Event> = E & {
+    currentTarget: HTMLElement;
+};
+/** keydown on the collection root (items + collection + typeahead). `root` defaults to currentTarget. */
+export declare function collectionKeyDown(list: SelectableCollection, e: Ev<KeyboardEvent>, root?: HTMLElement, hooks?: ItemPressHooks): boolean;
+/** keyup on the collection root: completes a keyboard press. */
+export declare function collectionKeyUp(list: SelectableCollection, e: Ev<KeyboardEvent>, root?: HTMLElement, hooks?: ItemPressHooks): void;
+/** pointerdown on the collection root. */
+export declare function collectionPointerDown(list: SelectableCollection, e: Ev<PointerEvent>, root?: HTMLElement, hooks?: ItemPressHooks): void;
+/** pointerup on the collection root (press up anywhere in it; press when it ends on the pressed item). */
+export declare function collectionPointerUp(list: SelectableCollection, e: Ev<PointerEvent>, root?: HTMLElement, hooks?: ItemPressHooks): void;
+/** pointercancel on the collection root. */
+export declare function collectionPointerCancel(list: SelectableCollection): void;
+/** click on the collection root: virtual clicks (screen readers) press; link clicks are ours to open. */
+export declare function collectionClick(list: SelectableCollection, e: Ev<MouseEvent>, root?: HTMLElement, hooks?: ItemPressHooks): void;
+/** dblclick on the collection root: the secondary action (selectionBehavior "replace"). */
+export declare function collectionDoubleClick(list: SelectableCollection, e: Ev<MouseEvent>, root?: HTMLElement, hooks?: ItemPressHooks): void;
+/** mousedown on the collection root: keep DOM focus where it is for virtual focus / disabled items / scrollbars. */
+export declare function collectionMouseDown(list: SelectableCollection, e: Ev<MouseEvent>, root?: HTMLElement): void;
+/** dragstart on the collection root: no native drag while a touch long press selects. */
+export declare function collectionDragStart(list: SelectableCollection, e: Event): void;
+/** pointerover on the collection root: `shouldFocusOnHover` (menus, pickers) focuses the hovered item. */
+export declare function collectionPointerOver(list: SelectableCollection, e: Ev<PointerEvent>, root?: HTMLElement): void;
+/** scroll on the collection root (remembered, restored when focus re-enters). */
+export declare function collectionScroll(list: SelectableCollection, e: Ev<Event>): void;
+/** focusin on the collection root: item focus → focused key; entering → first / last / selected item. */
+export declare function collectionFocusIn(list: SelectableCollection, e: Ev<FocusEvent>, root?: HTMLElement): void;
+/** focusout on the collection root: leaving the collection clears `isFocused`. */
+export declare function collectionFocusOut(list: SelectableCollection, e: Ev<FocusEvent>, root?: HTMLElement): void;
+/**
+ * Focus the collection per a focus strategy (react-aria `autoFocus`): the first selected selectable
+ * item, else the first / last item, else the collection itself (non-virtual).
+ */
+export declare function autoFocusCollection(list: SelectableCollection, root: HTMLElement, strategy: boolean | FocusStrategy): void;