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

package/link/behaviour.d.ts

@@ -0,0 +1,41 @@
+import { type MaybeAccessor } from "../interactions/utils.js";
+import { type Router, type RouterOptions } from "../utils/links.jsx";
+import type { AriaLabelingProps, FocusableProps, LinkDOMProps, PressEvents } from "../utils/types.js";
+import { type PressOptions } from "../button/press.js";
+export type { PressEvent, PressEvents, PressOptions, PointerType } from "../button/press.js";
+/** RA `LinkProps` (link/useLink). */
+export interface AriaLinkBaseProps extends PressEvents, FocusableProps {
+}
+/** RA `AriaLinkProps`. */
+export interface AriaLinkProps extends AriaLinkBaseProps, LinkDOMProps, Omit<AriaLabelingProps, "aria-label" | "aria-labelledby"> {
+    "aria-label"?: MaybeAccessor<string | undefined>;
+    "aria-labelledby"?: MaybeAccessor<string | undefined>;
+    /** Indicates whether this element represents the current item within a container or set of related elements. */
+    "aria-current"?: MaybeAccessor<boolean | "true" | "false" | "page" | "step" | "location" | "date" | "time" | undefined>;
+}
+/** RA `AriaLinkOptions`. */
+export interface AriaLinkOptions extends AriaLinkProps {
+    /** Whether the link is disabled. */
+    isDisabled?: MaybeAccessor<boolean | undefined>;
+    /**
+     * The HTML element used to render the link, e.g. 'a', or 'span'.
+     * @default 'a'
+     */
+    elementType?: string;
+    id?: string;
+}
+/** Attribute value of an `aria-current` value (`false` / nullish → no attribute). */
+export declare const ariaCurrentAttr: (v: unknown) => string | undefined;
+/**
+ * RA `useLink` attributes (without handlers: wire `linkPointerDown` / `linkKeyDown` / `linkClick` / … as inline
+ * arrows): `role="link"` + tab stop for a non-anchor, the link DOM props (`href` mapped by the router's
+ * `useHref`), `aria-disabled`, `aria-current`, labelable props.
+ */
+export declare function linkProps(props: AriaLinkOptions, router?: Router): Record<string, unknown>;
+/** click: the press click (virtual clicks, `onClick`) then RA `handleLinkClick` (client router navigation). */
+export declare function linkClick(e: MouseEvent, o: PressOptions, router: Router | undefined, href: LinkDOMProps["href"], routerOptions?: RouterOptions): void;
+export declare const linkKeyDown: (e: KeyboardEvent, o: PressOptions) => void;
+export declare const linkPointerDown: (e: PointerEvent, o: PressOptions) => void;
+export declare const linkPointerUp: (e: PointerEvent, o: PressOptions) => void;
+export declare const linkMouseDown: (e: MouseEvent, o: PressOptions) => void;
+export declare const linkDragStart: (e: DragEvent, o: PressOptions) => void;

package/link/behaviour.js

@@ -0,0 +1,58 @@
+// Ported from react-aria `useLink` (packages/react-aria/src/link/useLink.ts), Apache-2.0, © Adobe.
+// Rivet (naming convention): `useLink(props, ref)` → `linkProps(props, router)` (the attribute bag, no
+// closures, so a `.ts` module); the handlers are free functions `link<Event>(event, options, …)` called from
+// inline arrows (resumable) over THE press port (`../button/press.ts` → `../interactions/press.tsx`).
+// `isPressed` is not returned: the press handlers write `data-pressed` on the element.
+// - accessor rule: `aria-current` / `aria-label` / `aria-labelledby` may be accessors (kept as accessors in the
+//   bag: read them in bindings); `isDisabled` is read once (it picks the element: `<a>` vs `<span role=link>`).
+import { read } from "../interactions/utils.js";
+import { handleLinkClick, routerHref } from "../utils/links.jsx";
+import { pressClick, pressDragStart, pressKeyDown, pressMouseDown, pressPointerDown, pressPointerUp } from "../button/press.js";
+/** Attribute value of an `aria-current` value (`false` / nullish → no attribute). */
+export const ariaCurrentAttr = (v) => (v == null || v === false ? undefined : String(v));
+// An accessor stays the SAME function (a wrapper made in this `.ts` module would not resume): read it in a binding.
+const str = (v) => (typeof v === "function" ? v : ariaCurrentAttr(v));
+/**
+ * RA `useLink` attributes (without handlers: wire `linkPointerDown` / `linkKeyDown` / `linkClick` / … as inline
+ * arrows): `role="link"` + tab stop for a non-anchor, the link DOM props (`href` mapped by the router's
+ * `useHref`), `aria-disabled`, `aria-current`, labelable props.
+ */
+export function linkProps(props, router) {
+    const { elementType = "a" } = props;
+    const isDisabled = read(props.isDisabled);
+    const out = {};
+    if (elementType !== "a") {
+        out.role = "link";
+        out.tabIndex = !isDisabled ? 0 : undefined;
+    }
+    out.id = props.id;
+    out["aria-label"] = props["aria-label"];
+    out["aria-labelledby"] = props["aria-labelledby"];
+    out["aria-describedby"] = props["aria-describedby"];
+    out["aria-details"] = props["aria-details"];
+    // RA useLinkProps: the href stays on a disabled link's <span>.
+    if (props.href !== undefined)
+        out.href = routerHref(router, props.href);
+    out.hrefLang = props.hrefLang;
+    out.target = props.target;
+    out.rel = props.rel;
+    out.download = props.download === true ? "" : props.download || undefined;
+    out.ping = props.ping;
+    out.referrerPolicy = props.referrerPolicy;
+    if (props.autoFocus)
+        out.autoFocus = true;
+    out["aria-disabled"] = isDisabled ? "true" : undefined;
+    out["aria-current"] = str(props["aria-current"]);
+    return out;
+}
+/** click: the press click (virtual clicks, `onClick`) then RA `handleLinkClick` (client router navigation). */
+export function linkClick(e, o, router, href, routerOptions) {
+    pressClick(o, e);
+    if (router)
+        handleLinkClick(e, router, href, routerOptions);
+}
+export const linkKeyDown = (e, o) => pressKeyDown(o, e);
+export const linkPointerDown = (e, o) => pressPointerDown(o, e);
+export const linkPointerUp = (e, o) => pressPointerUp(o, e);
+export const linkMouseDown = (e, o) => pressMouseDown(o, e);
+export const linkDragStart = (e, o) => pressDragStart(o, e);

package/link/index.d.ts

@@ -0,0 +1,30 @@
+import { type DOMRenderProps } from "../utils/render.js";
+import { type GlobalDOMAttributes } from "../utils/dom-props.js";
+import { type ContextValue, type RefValue, type RenderProps, type SlotProps } from "../slots/index.jsx";
+import type { HoverEvents } from "../utils/types.js";
+import { type AriaLinkOptions } from "./behaviour.js";
+export { createRouter, openLink, routerHref, RouterContext, RouterProvider, shouldClientNavigate, useRouter, type Href, type LinkDOMProps, type Router, type RouterOptions, type RouterProviderProps, } from "./router.js";
+export type { PressEvent } from "./behaviour.js";
+export interface LinkRenderProps {
+    /** Whether the link is the current item within a list. `[data-current]` */
+    isCurrent: () => boolean;
+    /** Whether the link is currently hovered with a mouse. `[data-hovered]` */
+    isHovered: () => boolean;
+    /** Whether the link is currently in a pressed state. `[data-pressed]` */
+    isPressed: () => boolean;
+    /** Whether the link is focused, either via a mouse or keyboard. `[data-focused]` */
+    isFocused: () => boolean;
+    /** Whether the link is keyboard focused. `[data-focus-visible]` */
+    isFocusVisible: () => boolean;
+    /** Whether the link is disabled. `[data-disabled]` */
+    isDisabled: () => boolean;
+}
+export interface LinkProps extends Omit<AriaLinkOptions, "elementType">, HoverEvents, RenderProps<LinkRenderProps>, DOMRenderProps<"a", LinkRenderProps>, SlotProps, Omit<GlobalDOMAttributes<HTMLAnchorElement>, "onClick" | "style"> {
+    onKeyDown?: (e: KeyboardEvent) => void;
+    onKeyUp?: (e: KeyboardEvent) => void;
+    ref?: RefValue<HTMLAnchorElement | HTMLSpanElement>;
+}
+/** RAC `LinkContext` (Breadcrumb gives its Link `aria-current` / `isDisabled`). */
+export declare const LinkContext: import("@rivetjs/reactivity").Context<ContextValue<LinkProps, HTMLAnchorElement>>;
+/** A link to another page or resource (RAC `Link`). */
+export declare function Link(inProps: LinkProps): import("@rivetjs/runtime/jsx-runtime").CompiledElement;

package/link/index.jsx

@@ -0,0 +1,179 @@
+// Ported from react-aria-components `Link` (packages/react-aria-components/src/Link.tsx), Apache-2.0, © Adobe.
+// A link to another page or resource: `<a href>`, or `<span role="link">` without `href` / when disabled; THE
+// usePress port (press.ts), hover / focus ring (`../utils/data-attrs.tsx`), client routing through
+// `RouterProvider` (re-exported from `./router.ts` = `../utils/links.tsx`, one router for `@rivetjs/cdk/link`
+// and `@rivetjs/cdk/links`).
+// Rivet:
+// - render props are accessors (`class={({ isPressed }) => (isPressed() ? "on" : "")}`); the interaction states
+//   are signals only when a `class` / `style` / `children` function asks for them. `data-hovered` /
+//   `data-pressed` / `data-focused` / `data-focus-visible` are written by the handlers on the element (zero
+//   cost before interaction; a plain link loads no JS until it is hovered, focused or pressed).
+// - accessor rule: `aria-current`, `aria-label`, `aria-labelledby` may be accessors (read in bindings);
+//   an accessor `isDisabled` re-creates the link when it flips (it picks `<a>` vs `<span>`, like RAC re-render).
+// - `class` = RAC `className` (default `rv-Link`).
+// `render` (RAC DOMRenderProps): given, the attributes object goes to `render(attrs, LinkRenderProps)` instead of the default `<a>` / `<span role="link">`.
+import { createContext, signal, untrack, useContext } from "@rivetjs/reactivity";
+import {} from "../utils/render.js";
+import { globalDOMProps } from "../utils/dom-props.js";
+import { dataBool, mergeFocusableContext, readAttrs, focusStateIn, hoverStateOver } from "../utils/data-attrs.jsx";
+import { keyboardKeyDown, keyboardKeyUp } from "../interactions/keyboard.jsx";
+import { read } from "../interactions/utils.js";
+import { contextProps, mergeRefValues, renderProps as resolveRenderProps, resumableContext, } from "../slots/index.jsx";
+import { FocusableContext } from "../focus/focusable.jsx";
+import { useRouter } from "./router.js";
+import { linkClick, linkKeyDown, linkMouseDown, linkPointerDown, linkPointerUp, linkProps as ariaLinkProps, ariaCurrentAttr, } from "./behaviour.js";
+import { hasLive, liveOptions } from "../utils/live.jsx";
+import { liveRenderProps } from "../slots/index.jsx";
+export { createRouter, openLink, routerHref, RouterContext, RouterProvider, shouldClientNavigate, useRouter, } from "./router.js";
+/** Global DOM events / props the link handles itself (`onClick` is a press option, called by usePress). */
+const OWNED = ["onClick", "onPointerDown", "onPointerUp", "onMouseDown", "onPointerEnter", "onPointerLeave", "onPointerOver", "style"];
+/** RAC `LinkContext` (Breadcrumb gives its Link `aria-current` / `isDisabled`). */
+export const LinkContext = resumableContext(createContext(null, { id: "rv-link" }));
+const isFn = (v) => typeof v === "function";
+const isCurrentValue = (v) => !!v && v !== "false";
+/** A link to another page or resource (RAC `Link`). */
+export function Link(inProps) {
+    // Live props (P5): `isDisabled` becomes an accessor (the element switch below), class / style / children from a live
+    // view; the rest of the body is read once (untracked).
+    return untrack(() => link(inProps));
+}
+function link(inProps) {
+    let [props, ref] = contextProps(inProps, inProps.ref, LinkContext);
+    if (hasLive(props))
+        props = liveOptions(props, ["isDisabled"]);
+    // RA useLink → useFocusable: FocusableContext (TooltipTrigger) props / handlers / ref reach the link element.
+    const [focusableMerged, focusableRef, focusAttrs] = mergeFocusableContext(props, useContext(FocusableContext), !!read(props.isDisabled));
+    props = focusableMerged;
+    ref = mergeRefValues(ref, focusableRef);
+    const isDisabled = props.isDisabled;
+    // An accessor `isDisabled` switches the element: re-create the link when it flips (RAC re-renders).
+    if (isFn(isDisabled))
+        return <>{() => relink(props, ref, focusAttrs, isDisabled)}</>;
+    return renderLink(props, ref, focusAttrs, !!isDisabled);
+}
+// Tracks only the accessor; the link itself renders untracked (a component body).
+function relink(props, ref, focusAttrs, isDisabled) {
+    const disabled = !!isDisabled();
+    return untrack(() => renderLink(props, ref, focusAttrs, disabled));
+}
+function renderLink(props, ref, focusAttrs, isDisabled) {
+    const router = useRouter();
+    const isAnchor = !!props.href && !isDisabled;
+    const { onPointerDown, onPointerUp, onMouseDown, onKeyDown, onKeyUp, onPointerEnter, onPointerLeave, onPointerOver, href, routerOptions } = props;
+    const wantsStates = isFn(props.class) || isFn(props.style) || isFn(props.children);
+    const hovered = wantsStates ? signal(false) : undefined;
+    const pressed = wantsStates ? signal(false) : undefined;
+    const focused = wantsStates ? signal(false) : undefined;
+    const focusVisible = wantsStates ? signal(false) : undefined;
+    const userPressChange = props.onPressChange;
+    // An object literal of this module (R2): its arrow resumes; the press callbacks are the caller's.
+    // Locals first: a closure / literal capturing `props` would serialize the whole props object (children included).
+    const { onPress, onPressStart, onPressEnd, onPressUp, onClick } = props;
+    const press = {
+        onPress,
+        onPressStart,
+        onPressEnd,
+        onPressUp,
+        onClick,
+        isDisabled,
+        onPressChange: (isPressed) => {
+            pressed?.set(isPressed);
+            userPressChange?.(isPressed);
+        },
+    };
+    const interaction = {
+        isDisabled,
+        onHoverStart: props.onHoverStart,
+        onHoverEnd: props.onHoverEnd,
+        onHoverChange: props.onHoverChange,
+        onFocus: props.onFocus,
+        onBlur: props.onBlur,
+        onFocusChange: props.onFocusChange,
+        states: wantsStates ? { isHovered: hovered, isFocused: focused, isFocusVisible: focusVisible } : undefined,
+    };
+    const current = props["aria-current"];
+    const values = {
+        isCurrent: () => isCurrentValue(read(current)),
+        isDisabled: () => isDisabled,
+        isPressed: () => !!pressed?.(),
+        isHovered: () => !!hovered?.(),
+        isFocused: () => !!focused?.(),
+        isFocusVisible: () => !!focusVisible?.(),
+    };
+    const rp = resolveRenderProps({ class: props.class, style: props.style, children: props.children, values, defaultClassName: "rv-Link" }, hasLive(props) ? liveRenderProps(props) : undefined);
+    const aria = ariaLinkProps({ ...props, isDisabled, elementType: isAnchor ? "a" : "span" }, router);
+    const slot = props.slot || undefined;
+    const label = aria["aria-label"];
+    const labelledBy = aria["aria-labelledby"];
+    const ariaCurrent = aria["aria-current"];
+    // Read every prop up front: an element with a spread resumes as one binding over all its attributes.
+    const dom = globalDOMProps(props, OWNED);
+    for (const key of ["href", "hrefLang", "target", "rel", "download", "ping", "referrerPolicy", "autoFocus"])
+        if (aria[key] !== undefined)
+            dom[key.toLowerCase()] = aria[key];
+    const handlers = {
+        onPointerDown: (event) => {
+            linkPointerDown(event, press);
+            onPointerDown?.(event);
+        },
+        onPointerUp: (event) => {
+            linkPointerUp(event, press);
+            onPointerUp?.(event);
+        },
+        onMouseDown: (event) => {
+            linkMouseDown(event, press);
+            onMouseDown?.(event);
+        },
+        onKeyDown: (event) => {
+            linkKeyDown(event, press);
+            if (onKeyDown)
+                keyboardKeyDown({ onKeyDown }, event);
+        },
+        onKeyUp: (event) => (onKeyUp ? keyboardKeyUp({ onKeyUp }, event) : undefined),
+        onClick: (event) => linkClick(event, press, router, href, routerOptions),
+        onPointerOver: (event) => {
+            // The user's pointerover first: React Aria starts the hover on pointerenter, after it.
+            onPointerOver?.(event);
+            hoverStateOver(interaction, event);
+        },
+        // A user enter / leave binds natively (conditional object literals: resumable inline arrows).
+        ...(onPointerEnter ? { onPointerEnter: (event) => onPointerEnter(event) } : {}),
+        ...(onPointerLeave ? { onPointerLeave: (event) => onPointerLeave(event) } : {}),
+        onFocusIn: (event) => focusStateIn(interaction, event),
+    };
+    if (props.render) {
+        // Reactive attributes are accessors: the spread reads them inside its one effect.
+        const common = {
+            ...dom,
+            ...focusAttrs,
+            ...handlers,
+            ref: ref,
+            id: aria.id,
+            slot,
+            class: () => rp.class(),
+            style: () => rp.style(),
+            "aria-label": () => read(label),
+            "aria-labelledby": () => read(labelledBy),
+            "aria-describedby": aria["aria-describedby"],
+            "aria-details": aria["aria-details"],
+            "aria-current": () => ariaCurrentAttr(read(ariaCurrent)),
+            "data-current": () => dataBool(values.isCurrent()),
+            children: () => rp.children(),
+        };
+        const attrs = isAnchor
+            ? common
+            : {
+                ...common,
+                role: "link",
+                tabindex: aria.tabIndex,
+                "aria-disabled": aria["aria-disabled"],
+                "data-disabled": dataBool(isDisabled),
+            };
+        return props.render(attrs, values);
+    }
+    return isAnchor ? (<a {...dom} {...readAttrs(focusAttrs)} {...handlers} ref={ref} id={aria.id} slot={slot} class={rp.class()} style={rp.style()} aria-label={read(label)} aria-labelledby={read(labelledBy)} aria-describedby={aria["aria-describedby"]} aria-details={aria["aria-details"]} aria-current={ariaCurrentAttr(read(ariaCurrent))} data-current={dataBool(values.isCurrent())}>
+      {rp.children()}
+    </a>) : (<span {...dom} {...readAttrs(focusAttrs)} {...handlers} ref={ref} id={aria.id} role="link" tabIndex={aria.tabIndex} slot={slot} class={rp.class()} style={rp.style()} aria-label={read(label)} aria-labelledby={read(labelledBy)} aria-describedby={aria["aria-describedby"]} aria-details={aria["aria-details"]} aria-disabled={aria["aria-disabled"]} aria-current={ariaCurrentAttr(read(ariaCurrent))} data-current={dataBool(values.isCurrent())} data-disabled={dataBool(isDisabled)}>
+      {rp.children()}
+    </span>);
+}

package/link/router.d.ts

@@ -0,0 +1 @@
+export { createRouter, getSyntheticLinkProps, handleLinkClick, isOpeningLink, linkState, openLink, openSyntheticLink, routerHref, routerOpen, RouterContext, RouterProvider, shouldClientNavigate, syntheticLinkAttrs, useLinkProps, useRouter, useSyntheticLinkProps, type Href, type LinkDOMProps, type Modifiers, type Router, type RouterOptions, type RouterProviderProps, } from "../utils/links.jsx";

package/link/router.js

@@ -0,0 +1,5 @@
+// Client-side routing for links and link items. The implementation lives in `../utils/links.tsx`
+// (`@rivetjs/cdk/links`, ported from react-aria utils/openLink.tsx); this module only re-exports it so
+// `@rivetjs/cdk/link` and `@rivetjs/cdk/links` share ONE `RouterContext` / `RouterProvider` / `openLink`
+// and one `linkState.isOpening` flag (read by usePress and focus-visible).
+export { createRouter, getSyntheticLinkProps, handleLinkClick, isOpeningLink, linkState, openLink, openSyntheticLink, routerHref, routerOpen, RouterContext, RouterProvider, shouldClientNavigate, syntheticLinkAttrs, useLinkProps, useRouter, useSyntheticLinkProps, } from "../utils/links.jsx";

package/listbox/behaviour.d.ts

@@ -0,0 +1,175 @@
+import { type Signal } from "@rivetjs/reactivity";
+import type { Collection, FocusStrategy, Key, KeyboardDelegate, Node, Orientation, SelectionBehavior } from "../collections/types.js";
+import { type ListState } from "../collections/list-state.js";
+import { SelectionManager } from "../selection/manager.js";
+import { type AriaSelectableCollectionOptions, type LinkBehavior } from "../selection/selectable-collection.js";
+import { type MaybeAccessor } from "../interactions/utils.js";
+import type { Router } from "../utils/links.jsx";
+export type { LinkBehavior };
+/** Data a listbox shares with its options (react-aria `listData`). Plain data + signals + resumable functions. */
+export interface ListData {
+    id: string;
+    shouldSelectOnPressUp?: boolean | undefined;
+    shouldFocusOnHover?: boolean | undefined;
+    /** May be an accessor (Autocomplete): read at event time / in bindings. */
+    shouldUseVirtualFocus?: MaybeAccessor<boolean | undefined>;
+    isVirtualized?: boolean | undefined;
+    onAction?: ((key: Key) => void) | undefined;
+    linkBehavior: LinkBehavior;
+    /** useListBox listData `UNSTABLE_itemBehavior` ("action": items with an action never select). */
+    UNSTABLE_itemBehavior?: "action" | undefined;
+    /** Rivet: the option under a mouse pointer (`data-hovered`). */
+    hoveredKey: Signal<Key | null>;
+    /** Rivet: the pressed option (`data-pressed`). */
+    pressedKey: Signal<Key | null>;
+    /** Rivet: whether focus is keyboard-visible (useFocusRing's `isFocusVisible`). */
+    focusVisible: Signal<boolean>;
+    /** Rivet: whether the listbox element itself has focus (root useFocusRing). */
+    isFocused: Signal<boolean>;
+    /** The router link options open through (react-aria `useRouter()`, `RouterContext`). */
+    router?: Router | undefined;
+    /** Rivet (RAC SelectableCollectionContext `filter`): live options hide themselves when it rejects them. */
+    filter?: ((textValue: string, node: Node<unknown>) => boolean) | undefined;
+}
+/** react-aria `getItemId`: the option element id. */
+export declare function getItemId(listId: string, itemKey: Key): string;
+/** react-aria `AriaListBoxOptions` (labeling, selection behaviour, focus and keyboard options). */
+export interface AriaListBoxOptions {
+    id?: string | undefined;
+    "aria-label"?: string | undefined;
+    "aria-labelledby"?: string | undefined;
+    "aria-describedby"?: string | undefined;
+    "aria-details"?: string | undefined;
+    /** Whether the listbox (or the first / last option) receives focus on mount (may be an accessor). */
+    autoFocus?: MaybeAccessor<boolean | FocusStrategy | undefined>;
+    /** Whether focus wraps around at the ends. */
+    shouldFocusWrap?: boolean | undefined;
+    /** Whether Escape clears the selection. @default "clearSelection" */
+    escapeKeyBehavior?: "clearSelection" | "none" | undefined;
+    /** How multiple selection behaves. @default "toggle" */
+    selectionBehavior?: SelectionBehavior | undefined;
+    /** Select on press up instead of press down. */
+    shouldSelectOnPressUp?: boolean | undefined;
+    /** Whether options receive focus on hover. */
+    shouldFocusOnHover?: boolean | undefined;
+    /** Handler that is called when a user performs an action on an option. */
+    onAction?: ((key: Key) => void) | undefined;
+    /** Whether the listbox uses virtual focus (aria-activedescendant); may be an accessor. */
+    shouldUseVirtualFocus?: MaybeAccessor<boolean | undefined>;
+    /** Whether typeahead is disabled (may be an accessor). */
+    disallowTypeAhead?: MaybeAccessor<boolean | undefined>;
+    /** The behavior of links in the collection. */
+    linkBehavior?: LinkBehavior | undefined;
+    /** @private RAC: items with an action are actions only (ComboBox). */
+    UNSTABLE_itemBehavior?: "action" | undefined;
+    /** The primary orientation of the options. @default "vertical" */
+    orientation?: Orientation | undefined;
+    /** Layout of the options. @default "stack" */
+    layout?: "stack" | "grid" | undefined;
+    /** Whether the options are contained in a virtual scroller. */
+    isVirtualized?: boolean | undefined;
+    /** An optional keyboard delegate (default: a ListKeyboardDelegate over the collection). */
+    keyboardDelegate?: KeyboardDelegate | undefined;
+    /** Focus events of the listbox (useFocusWithin). */
+    onFocus?: ((e: FocusEvent) => void) | undefined;
+    onBlur?: ((e: FocusEvent) => void) | undefined;
+    onFocusChange?: ((isFocused: boolean) => void) | undefined;
+}
+/** What the delegated handlers read: the options + the shared list data + the collection accessor. */
+export interface ListBoxBehaviourProps extends AriaListBoxOptions {
+    data: ListData;
+    /** A built collection (Select / ComboBox / filtered); default: the rendered options. */
+    collection?: (() => Collection<Node<unknown>>) | null | undefined;
+}
+/** react-aria useListBox's `linkBehavior` default: "action" with replace, "override" otherwise (toggle cannot be "action"). */
+export declare function listBoxLinkBehavior(selectionBehavior: SelectionBehavior | undefined, linkBehavior?: LinkBehavior): LinkBehavior;
+/** Creates the shared list data (react-aria `listData.set(state, …)`). */
+export declare function createListData(props: AriaListBoxOptions, id: string, filter?: ListData["filter"], router?: Router): ListData;
+/**
+ * react-aria `useListBox` attributes (`listBoxProps` without handlers: wire `listBox<Event>` on the element) and
+ * `labelProps` (for a visible label element: `<span id>`). `tabIndex` and `aria-multiselectable` are accessors.
+ */
+export declare function listBoxProps(props: AriaListBoxOptions & {
+    label?: unknown;
+}, state: ListState, data: ListData): {
+    listBoxProps: Record<string, unknown>;
+    labelProps: Record<string, unknown>;
+};
+/** react-aria `useListBoxSection`: props for the section's `<section>` (groupProps) and its heading. */
+export declare function listBoxSectionProps(props: {
+    heading?: string | undefined;
+    "aria-label"?: string | undefined;
+}): {
+    itemProps: Record<string, unknown>;
+    headingProps: Record<string, unknown>;
+    groupProps: Record<string, unknown>;
+};
+/**
+ * A selection manager reading only one option (option bindings: no collection walk per binding). Takes plain data
+ * (a resumable binding must not capture the node instance). Memoized per selection state, key and `isDisabled`.
+ */
+export declare function nodeSelectionManager(state: ListState, key: Key, isDisabled?: boolean): SelectionManager;
+/** react-aria `useOption` attributes and states (accessors: read inside bindings). */
+export declare function optionProps(props: {
+    key: Key;
+    isDisabled?: boolean | undefined;
+    /** The item's `isDisabled` prop (an accessor stays live: read at use, live props P5). */
+    itemIsDisabled?: boolean | (() => boolean | undefined) | undefined;
+    hasAction?: boolean | undefined;
+    "aria-label"?: string | undefined;
+    labelId?: () => string | undefined;
+    descriptionId?: () => string | undefined;
+}, state: ListState, data: ListData): {
+    optionProps: Record<string, unknown>;
+    isSelected: () => boolean;
+    isDisabled: () => boolean;
+    isFocused: () => boolean;
+    isFocusVisible: () => boolean;
+    isPressed: () => boolean;
+    isHovered: () => boolean;
+    allowsSelection: () => boolean;
+    hasAction: () => boolean;
+};
+type Ev<E extends Event = Event> = E & {
+    currentTarget: EventTarget | null;
+};
+/** react-aria useSelectableList options for this listbox (per event: manager + keyboard delegate over the current collection). */
+export declare function listBoxCollectionOptions(props: ListBoxBehaviourProps, state: ListState, root: HTMLElement): AriaSelectableCollectionOptions;
+/** keydown (capture) on the listbox element: typeahead Space (useTypeSelect). */
+export declare function listBoxKeyDownCapture(e: Ev<KeyboardEvent>, props: ListBoxBehaviourProps, state: ListState): void;
+/** keydown on the listbox element: option Space / Enter press (useSelectableItem), then navigation (useSelectableCollection). */
+export declare function listBoxKeyDown(e: Ev<KeyboardEvent>, props: ListBoxBehaviourProps, state: ListState): void;
+/** keyup on the listbox element: option keyboard press end. */
+export declare function listBoxKeyUp(e: Ev<KeyboardEvent>, props: ListBoxBehaviourProps, state: ListState): void;
+/** pointerdown on the listbox element: option press start. */
+export declare function listBoxPointerDown(e: Ev<PointerEvent>, props: ListBoxBehaviourProps, state: ListState): void;
+/** pointerup on the listbox element: option press up. */
+export declare function listBoxPointerUp(e: Ev<PointerEvent>, props: ListBoxBehaviourProps, state: ListState): void;
+/** pointercancel on the listbox element. */
+export declare function listBoxPointerCancel(e: Ev<PointerEvent>, props: ListBoxBehaviourProps, state: ListState): void;
+/** click on the listbox element: the option press (pointer and virtual clicks). */
+export declare function listBoxClick(e: Ev<MouseEvent>, props: ListBoxBehaviourProps, state: ListState): void;
+/** dblclick on the listbox element: secondary action with `selectionBehavior="replace"`. */
+export declare function listBoxDoubleClick(e: Ev<MouseEvent>, props: ListBoxBehaviourProps, state: ListState): void;
+/** dragstart on the listbox element. */
+export declare function listBoxDragStart(e: Ev<DragEvent>, props: ListBoxBehaviourProps, state: ListState): void;
+/** mousedown on the listbox element (scrollbar clicks do not focus). */
+export declare function listBoxMouseDown(e: Ev<MouseEvent>, props: ListBoxBehaviourProps, state: ListState): void;
+/** focusin on the listbox element: option focus (useSelectableItem), collection focus, focus-within, root focus ring. */
+export declare function listBoxFocusIn(e: Ev<FocusEvent>, props: ListBoxBehaviourProps, state: ListState): void;
+/** focusout on the listbox element. */
+export declare function listBoxFocusOut(e: Ev<FocusEvent>, props: ListBoxBehaviourProps, state: ListState): void;
+/** `react-aria-focus` (virtual focus from an Autocomplete input). */
+export declare function listBoxVirtualFocus(e: Ev<CustomEvent<{
+    focusStrategy?: FocusStrategy;
+}>>, props: ListBoxBehaviourProps, state: ListState): void;
+/** `react-aria-clear-focus` (virtual focus cleared by an Autocomplete input). */
+export declare function listBoxClearVirtualFocus(e: Ev<CustomEvent<{
+    clearFocusKey?: boolean;
+}>>, props: ListBoxBehaviourProps, state: ListState): void;
+/** pointerover on the listbox element: option hover start (useHover; `shouldFocusOnHover` focuses it). */
+export declare function listBoxPointerOver(e: Ev<PointerEvent>, props: ListBoxBehaviourProps, state: ListState): void;
+/** pointerout on the listbox element: option hover end when the pointer leaves it. */
+export declare function listBoxPointerOut(e: Ev<PointerEvent>, props: ListBoxBehaviourProps, _state: ListState): void;
+/** Auto focus once the listbox element is connected (react-aria useSelectableCollection's mount effect). */
+export declare function listBoxAutoFocus(root: HTMLElement, props: ListBoxBehaviourProps, state: ListState): void;