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

package/autocomplete/behaviour.jsx

@@ -0,0 +1,423 @@
+// Ported from react-aria useAutocomplete (packages/react-aria/src/autocomplete/useAutocomplete.ts),
+// Apache-2.0, © Adobe.
+// Rivet:
+// - `useAutocomplete(props, state)` → `autocompleteProps(props, state)` (call during render, from `.tsx`:
+//   the returned bags hold inline-arrow handlers / accessors that resumed bindings and contexts capture).
+//   Hook-internal handlers are free functions `autocompleteChange` / `autocompleteKeyDown` /
+//   `autocompleteKeyUpCapture` / `autocompleteBlur` / `autocompleteFocus` / `autocompletePointerDown` /
+//   `autocompleteFocusIn` / `autocompleteBeforeInput` taking `(event, aria, state)`.
+// - `aria` = the per-instance serializable part (`AutocompleteAriaState`: collection id, `ref()`s, signals);
+//   upstream's refs (`timeout`, `delayNextActiveDescendant`, `queuedActiveDescendant`, `lastInputType`,
+//   `keyDownTarget`) are transient browser data in a module WeakMap keyed by it.
+// - `hasCollection` = the collection element is attached (`collectionRef()`), or, on the server, true (the
+//   wrapped collection renders after the input; React's server HTML lacks the attributes until hydration,
+//   a resumed page has no hydration — so the server writes the post-mount state). `shouldUseVirtualFocus`
+//   turns off when the attached collection is focusable itself (`tabindex`: no virtual focus support, e.g.
+//   Table), read at use time instead of the upstream callback-ref state update.
+// - React synthetic event APIs → native: `isPropagationStopped()` = `cancelBubble`, `isDefaultPrevented()` =
+//   `defaultPrevented`, `continuePropagation()` = not stopping (native events propagate unless stopped).
+// - virtual focus props (`onKeyDown`, `onBlur`, `onFocus`, `onPointerDown`, `aria-activedescendant`) are
+//   always passed; they no-op (`aria-activedescendant` undefined) while virtual focus is off or no collection
+//   is attached (upstream adds them conditionally per render).
+// - Deviation: the collection `focusin` listener → `collectionProps.onFocusIn`, the input `beforeinput`
+//   listener → `inputProps.onBeforeInput`, the document capture `keyup` listener is added on keydown and
+//   removed after the matching keyup (upstream: for the component's lifetime; it only acts on the keyup
+//   matching the last input keydown).
+import { signal } from "@rivetjs/reactivity";
+import { ref as createRef } from "@rivetjs/runtime/dom";
+import { CLEAR_FOCUS_EVENT, FOCUS_EVENT } from "../selection/selectable-collection.js";
+import { dispatchVirtualBlur, dispatchVirtualFocus, getVirtuallyFocusedElement, moveVirtualFocus } from "../selection/dom-utils.js";
+import { getInteractionModality, getPointerType } from "../interactions/focus-visible.jsx";
+import { getActiveElement, getEventTarget, getOwnerDocument } from "../utils/dom.js";
+import { isAndroid, isCtrlKeyPressed, isIOS } from "../platform/index.js";
+import { createMergedId } from "../slots/index.jsx";
+import { labelsProps } from "../label/behaviour.js";
+import { formatMessage } from "../_adapters/intl.js";
+import { strings as intlMessages } from "./intl.js";
+import { autocompleteInputValue, setAutocompleteInputValue, setFocusedNodeId, } from "../state/autocomplete.js";
+const transients = new WeakMap();
+function transient(aria) {
+    let t = transients.get(aria);
+    if (!t) {
+        t = { timeout: undefined, delayNextActiveDescendant: false, queuedActiveDescendant: null, lastInputType: "", keyDownTarget: null, keyUp: null };
+        transients.set(aria, t);
+    }
+    return t;
+}
+/** Whether a collection is connected (attached; true on the server). */
+export function autocompleteHasCollection(aria) {
+    return aria.collectionRef() != null || typeof document === "undefined";
+}
+/** Whether the input drives the collection with virtual focus (upstream `shouldUseVirtualFocus` state). */
+export function autocompleteShouldUseVirtualFocus(aria) {
+    if (!aria.virtualFocus)
+        return false;
+    // If useSelectableCollection isn't passed shouldUseVirtualFocus even when useAutocomplete provides it
+    // that means the collection doesn't support it (e.g. Table). If that is the case, we need to disable it here regardless
+    // of what the user's provided so that the input doesn't recieve the onKeyDown and autocomplete props.
+    const node = aria.collectionRef();
+    return !(node && node.getAttribute("tabindex") != null);
+}
+const virtualFocusActive = (aria) => autocompleteShouldUseVirtualFocus(aria) && autocompleteHasCollection(aria);
+/**
+ * Provides the behavior and accessibility implementation for an autocomplete component. An autocomplete
+ * combines a text input with a collection, allowing users to filter the collection's contents match a query.
+ */
+export function autocompleteProps(props, state) {
+    const { filter, disableAutoFocusFirst = false, disableVirtualFocus = false } = props;
+    // For mobile screen readers, we don't want virtual focus, instead opting to disable FocusScope's restoreFocus and manually
+    // moving focus back to the subtriggers
+    const isMobileScreenReader = getInteractionModality() === "virtual" && !!(isIOS() || isAndroid());
+    const aria = {
+        collectionId: createMergedId(),
+        inputRef: props.inputRef ?? createRef(),
+        collectionRef: props.collectionRef ?? createRef(),
+        virtualFocus: !isMobileScreenReader && !disableVirtualFocus,
+        autoFocusOnMount: signal(false),
+        disableAutoFocusFirst,
+    };
+    const collectionLabels = labelsProps(aria.collectionId.id, formatMessage(intlMessages, props.locale, "collectionLabel"), undefined);
+    // Only apply the autocomplete specific behaviors if the collection component wrapped by it is actually
+    // being filtered/allows filtering by the Autocomplete.
+    const inputProps = {
+        value: () => autocompleteInputValue(state),
+        onChange: (value) => autocompleteChange(value, aria, state),
+        onKeyDown: (e) => {
+            if (virtualFocusActive(aria))
+                autocompleteKeyDown(e, aria, state);
+        },
+        "aria-activedescendant": () => (virtualFocusActive(aria) ? (state.focusedNodeId() ?? undefined) : undefined),
+        onBlur: (e) => {
+            if (virtualFocusActive(aria))
+                autocompleteBlur(e, aria);
+        },
+        onFocus: (e) => {
+            if (virtualFocusActive(aria))
+                autocompleteFocus(e, aria);
+        },
+        onPointerDown: (e) => {
+            if (virtualFocusActive(aria))
+                autocompletePointerDown(e, aria, state);
+        },
+        onBeforeInput: (e) => autocompleteBeforeInput(e, aria),
+        enterKeyHint: "go",
+        // RA: `collectionId` merged into the collection's own id (mergeIds → idsUpdaterMap re-renders this hook). Rivet: the
+        // collection's `contextProps` switches `collectionId.current` to its own id while it renders — also on the server,
+        // before this attribute is written — else the rendered collection's id.
+        "aria-controls": () => (autocompleteHasCollection(aria) ? aria.collectionRef()?.id || aria.collectionId.current() : undefined),
+        // TODO: readd proper logic for completionMode = complete (aria-autocomplete: both)
+        "aria-autocomplete": "list",
+        // This disable's iOS's autocorrect suggestions, since the autocomplete provides its own suggestions.
+        autoCorrect: "off",
+        // This disable's the macOS Safari spell check auto corrections.
+        spellCheck: "false",
+        autoComplete: "off",
+    };
+    const collectionProps = {
+        ...collectionLabels,
+        id: aria.collectionId,
+        shouldUseVirtualFocus: () => autocompleteShouldUseVirtualFocus(aria),
+        disallowTypeAhead: () => autocompleteShouldUseVirtualFocus(aria),
+        autoFocus: () => (aria.autoFocusOnMount() ? "first" : false),
+        onFocusIn: (e) => autocompleteFocusIn(e, aria, state),
+    };
+    // Object-literal arrow (not a bare ternary branch) so the compiler captures it: ListBox keeps it in resumed state.
+    const collectionFilter = { filter: (nodeTextValue, node) => filter(nodeTextValue, autocompleteInputValue(state), node) };
+    return {
+        inputProps,
+        collectionProps,
+        collectionRef: aria.collectionRef,
+        inputRef: aria.inputRef,
+        filter: filter != null ? collectionFilter.filter : undefined,
+        aria,
+    };
+}
+/** Upstream `updateActiveDescendantEvent`: the collection's `focusin` (virtual focus moves to an item). */
+export function autocompleteFocusIn(e, aria, state) {
+    const t = transient(aria);
+    const input = aria.inputRef();
+    // Ensure input is focused if the user clicks on the collection directly.
+    // don't trigger on touch so that mobile keyboard doesnt appear when tapping on options
+    if (!e.isTrusted && autocompleteShouldUseVirtualFocus(aria) && input && getActiveElement(getOwnerDocument(input)) !== input && getPointerType() !== "touch") {
+        input.focus();
+    }
+    const target = getEventTarget(e);
+    if (e.isTrusted || !target || t.queuedActiveDescendant === target.id) {
+        return;
+    }
+    clearTimeout(t.timeout);
+    if (target !== aria.collectionRef()) {
+        if (t.delayNextActiveDescendant) {
+            t.queuedActiveDescendant = target.id;
+            t.timeout = setTimeout(() => {
+                setFocusedNodeId(state, target.id);
+            }, 500);
+        }
+        else {
+            t.queuedActiveDescendant = target.id;
+            setFocusedNodeId(state, target.id);
+        }
+    }
+    else if (t.queuedActiveDescendant && !getOwnerDocument(input).getElementById(t.queuedActiveDescendant)) {
+        // If we recieve a focus event refocusing the collection, either we have newly refocused the input and are waiting for the
+        // wrapped collection to refocus the previously focused node if any OR
+        // we are in a state where we've filtered to such a point that there aren't any matching items in the collection to focus.
+        // In this case we want to clear tracked item if any and clear active descendant
+        t.queuedActiveDescendant = null;
+        setFocusedNodeId(state, null);
+    }
+    t.delayNextActiveDescendant = false;
+}
+/** Upstream `focusFirstItem`. */
+export function autocompleteFocusFirstItem(aria) {
+    const collection = aria.collectionRef();
+    if (!collection) {
+        aria.autoFocusOnMount.set(true);
+        return;
+    }
+    transient(aria).delayNextActiveDescendant = true;
+    collection.dispatchEvent(new CustomEvent(FOCUS_EVENT, {
+        cancelable: true,
+        bubbles: true,
+        detail: {
+            focusStrategy: "first",
+        },
+    }));
+}
+/** Upstream `clearVirtualFocus`. */
+export function autocompleteClearVirtualFocus(aria, state, clearFocusKey) {
+    const t = transient(aria);
+    aria.autoFocusOnMount.set(false);
+    moveVirtualFocus(getActiveElement());
+    t.queuedActiveDescendant = null;
+    setFocusedNodeId(state, null);
+    const clearFocusEvent = new CustomEvent(CLEAR_FOCUS_EVENT, {
+        cancelable: true,
+        bubbles: true,
+        detail: {
+            clearFocusKey,
+        },
+    });
+    clearTimeout(t.timeout);
+    t.delayNextActiveDescendant = false;
+    aria.collectionRef()?.dispatchEvent(clearFocusEvent);
+}
+/** Upstream `useEvent(inputRef, 'beforeinput')`. */
+export function autocompleteBeforeInput(e, aria) {
+    transient(aria).lastInputType = e.inputType;
+}
+/** Upstream `onChange` (the input's text changed). */
+export function autocompleteChange(value, aria, state) {
+    const t = transient(aria);
+    const lastInputType = t.lastInputType;
+    // Tell wrapped collection to focus the first element in the list when typing forward and to clear focused key when modifying the text via
+    // copy paste/backspacing/undo/redo for screen reader announcements
+    if ((lastInputType === "insertText" ||
+        // IME composition (e.g. CJK input) reports 'insertCompositionText'/'insertFromComposition'
+        // instead of 'insertText'. Treat these as forward typing so the first item gets virtual focus.
+        lastInputType === "insertCompositionText" ||
+        lastInputType === "insertFromComposition") &&
+        !aria.disableAutoFocusFirst) {
+        autocompleteFocusFirstItem(aria);
+    }
+    else if (lastInputType && (lastInputType.includes("insert") || lastInputType.includes("delete") || lastInputType.includes("history"))) {
+        autocompleteClearVirtualFocus(aria, state, true);
+        // If onChange was triggered before the timeout actually updated the activedescendant, we need to fire
+        // our own dispatchVirtualFocus so focusVisible gets reapplied on the input
+        const input = aria.inputRef();
+        if (input && getVirtuallyFocusedElement(getOwnerDocument(input)) === input) {
+            dispatchVirtualFocus(input, null);
+        }
+    }
+    setAutocompleteInputValue(state, value);
+}
+/** Upstream `onKeyDown` (textfield specific keydown operations). */
+export function autocompleteKeyDown(e, aria, state) {
+    const t = transient(aria);
+    t.keyDownTarget = getEventTarget(e);
+    listenKeyUp(aria);
+    if (e.isComposing) {
+        return;
+    }
+    const input = aria.inputRef();
+    let focusedNodeId = t.queuedActiveDescendant;
+    if (focusedNodeId !== null && getOwnerDocument(input).getElementById(focusedNodeId) == null) {
+        // if the focused id doesn't exist in document, then we need to clear the tracked focused node, otherwise
+        // we will be attempting to fire key events on a non-existing node instead of trying to focus the newly swapped wrapped collection.
+        // This can happen if you are swapping out the Autocomplete wrapped collection component like in the docs search.
+        t.queuedActiveDescendant = null;
+        focusedNodeId = null;
+    }
+    switch (e.key) {
+        case "a":
+            if (isCtrlKeyPressed(e)) {
+                return;
+            }
+            break;
+        case "Escape":
+            // Early return for Escape here so it doesn't leak the Escape event from the simulated collection event below and
+            // close the dialog prematurely. Ideally that should be up to the discretion of the input element hence the check
+            // for isPropagationStopped
+            if (e.defaultPrevented) {
+                return;
+            }
+            break;
+        case " ":
+            // Space shouldn't trigger onAction so early return.
+            return;
+        case "Tab":
+            // Don't propogate Tab down to the collection, otherwise we will try to focus the collection via useSelectableCollection's Tab handler (aka shift tab logic)
+            // We want FocusScope to handle Tab if one exists (aka sub dialog), so special casepropogate
+            return;
+        case "Home":
+        case "End":
+        case "PageDown":
+        case "PageUp":
+        case "ArrowUp":
+        case "ArrowDown":
+        case "ArrowRight":
+        case "ArrowLeft": {
+            if ((e.key === "Home" || e.key === "End") && focusedNodeId == null && e.shiftKey) {
+                return;
+            }
+            // If there is text within the input field, we'll want continue propagating events down
+            // to the wrapped collection if there is a focused node so that a user can continue moving the
+            // virtual focus. However, if the user doesn't have a focus in the collection, just move the text
+            // cursor instead. They can move focus down into the collection via down/up arrow if need be
+            if (e.key === "ArrowRight" || e.key === "ArrowLeft") {
+                if (focusedNodeId == null) {
+                    if (!e.cancelBubble) {
+                        e.stopPropagation();
+                    }
+                    return;
+                }
+                break;
+            }
+            // Prevent these keys from moving the text cursor in the input
+            e.preventDefault();
+            // Move virtual focus into the wrapped collection
+            const focusCollection = new CustomEvent(FOCUS_EVENT, {
+                cancelable: true,
+                bubbles: true,
+            });
+            aria.collectionRef()?.dispatchEvent(focusCollection);
+            break;
+        }
+    }
+    // Emulate the keyboard events that happen in the input field in the wrapped collection. This is for triggering things like onAction via Enter
+    // or moving focus from one item to another. Stop propagation on the input event if it isn't already stopped so it doesn't leak out. For events
+    // like ESC, the dispatched event below will bubble out of the collection and be stopped if handled by useSelectableCollection, otherwise will bubble
+    // as expected
+    if (!e.cancelBubble) {
+        e.stopPropagation();
+    }
+    let shouldPerformDefaultAction = true;
+    const collection = aria.collectionRef();
+    if (collection != null) {
+        if (focusedNodeId == null) {
+            shouldPerformDefaultAction = collection.dispatchEvent(new KeyboardEvent(e.type, e)) || false;
+        }
+        else {
+            const item = getOwnerDocument(collection).getElementById(focusedNodeId);
+            if (item) {
+                shouldPerformDefaultAction = item.dispatchEvent(new KeyboardEvent(e.type, e)) || false;
+            }
+        }
+    }
+    if (shouldPerformDefaultAction) {
+        switch (e.key) {
+            case "ArrowLeft":
+            case "ArrowRight": {
+                // Clear the activedescendant so NVDA announcements aren't interrupted but retain the focused key in the collection so the
+                // user's keyboard navigation restarts from where they left off
+                autocompleteClearVirtualFocus(aria, state);
+                break;
+            }
+            case "Enter":
+                // Trigger click action on item when Enter key was pressed.
+                if (focusedNodeId != null) {
+                    const item = getOwnerDocument(collection).getElementById(focusedNodeId);
+                    item?.dispatchEvent(new PointerEvent("click", e));
+                }
+                break;
+        }
+    }
+    else {
+        // TODO: check if we can do this, want to stop textArea from using its default Enter behavior so items are properly triggered
+        e.preventDefault();
+    }
+}
+function listenKeyUp(aria) {
+    const t = transient(aria);
+    if (t.keyUp || typeof document === "undefined")
+        return;
+    const handler = (e) => autocompleteKeyUpCapture(e, aria);
+    t.keyUp = handler;
+    getOwnerDocument(aria.inputRef()).addEventListener("keyup", handler, true);
+}
+/** Upstream `onKeyUpCapture` (document capture listener). */
+export function autocompleteKeyUpCapture(e, aria) {
+    const t = transient(aria);
+    // Dispatch simulated key up events for things like triggering links in listbox
+    // Make sure to stop the propagation of the input keyup event so that the simulated keyup/down pair
+    // is detected by usePress instead of the original keyup originating from the input
+    if (getEventTarget(e) === t.keyDownTarget) {
+        e.stopImmediatePropagation();
+        if (t.keyUp)
+            getOwnerDocument(aria.inputRef()).removeEventListener("keyup", t.keyUp, true);
+        t.keyUp = null;
+        const focusedNodeId = t.queuedActiveDescendant;
+        if (focusedNodeId == null) {
+            aria.collectionRef()?.dispatchEvent(new KeyboardEvent(e.type, e));
+        }
+        else {
+            const item = getOwnerDocument(aria.inputRef()).getElementById(focusedNodeId);
+            item?.dispatchEvent(new KeyboardEvent(e.type, e));
+        }
+    }
+}
+// Be sure to clear/restore the virtual + collection focus when blurring/refocusing the field so we only show the
+// focus ring on the virtually focused collection when are actually interacting with the Autocomplete
+/** Upstream `onBlur`. */
+export function autocompleteBlur(e, aria) {
+    if (!e.isTrusted) {
+        return;
+    }
+    const queued = transient(aria).queuedActiveDescendant;
+    const lastFocusedNode = queued ? getOwnerDocument(aria.inputRef()).getElementById(queued) : null;
+    if (lastFocusedNode) {
+        dispatchVirtualBlur(lastFocusedNode, e.relatedTarget);
+    }
+}
+/** Upstream `onFocus`. */
+export function autocompleteFocus(e, aria) {
+    if (!e.isTrusted) {
+        return;
+    }
+    const queued = transient(aria).queuedActiveDescendant;
+    const curFocusedNode = queued ? getOwnerDocument(aria.inputRef()).getElementById(queued) : null;
+    if (curFocusedNode) {
+        const target = getEventTarget(e);
+        queueMicrotask(() => {
+            // instead of focusing the last focused node, just focus the collection instead and have the collection handle what item to focus via useSelectableCollection/Item
+            const collection = aria.collectionRef();
+            dispatchVirtualBlur(target, collection ?? null);
+            if (collection)
+                dispatchVirtualFocus(collection, target);
+        });
+    }
+}
+// Clicking back into the input can happen after focus moved elsewhere in the dialog, while
+// virtual focus is still on an option. Clear virtual focus on pointer down so mouse
+// interactions restore the input state before the click's focus handling runs.
+// Touch is excluded because touch interactions should not move focus back to the input.
+/** Upstream `onPointerDown`. */
+export function autocompletePointerDown(e, aria, state) {
+    const input = aria.inputRef();
+    if (e.button !== 0 || e.pointerType === "touch" || transient(aria).queuedActiveDescendant == null || input == null) {
+        return;
+    }
+    if (getEventTarget(e) === input) {
+        autocompleteClearVirtualFocus(aria, state);
+    }
+}

package/autocomplete/contexts.d.ts

@@ -0,0 +1,54 @@
+import type { ContextValue, MergedId, SlottedContextValue } from "../slots/index.jsx";
+import type { Node } from "../collections/types.js";
+import type { MaybeAccessor } from "../interactions/utils.js";
+import type { AutocompleteState } from "../state/autocomplete.js";
+import type { AutocompleteProps } from "./behaviour.jsx";
+/** RAC `SelectableCollectionContextValue`: what an Autocomplete passes to the collection it filters. */
+export interface SelectableCollectionContextValue<T = unknown> {
+    /** Rivet: a `MergedId` (RA `useId` the collection's own id merges into, `contextProps`); a plain id string also works. */
+    id?: string | MergedId;
+    "aria-label"?: string;
+    "aria-labelledby"?: string;
+    "aria-describedby"?: string;
+    "aria-details"?: string;
+    /** Hides the nodes it returns false for (build mode: `collection.filter`; live mode: each item). */
+    filter?: (nodeTextValue: string, node: Node<T>) => boolean;
+    /** Whether the collection items should use virtual focus instead of being focused directly. */
+    shouldUseVirtualFocus?: MaybeAccessor<boolean | undefined>;
+    /** Whether typeahead is disabled. */
+    disallowTypeAhead?: MaybeAccessor<boolean | undefined>;
+    /** RA `autoFocus` (`"first"` once the collection mounts after a forward-typing filter). */
+    autoFocus?: MaybeAccessor<boolean | "first" | "last" | undefined>;
+    /** Rivet: RA's `focusin` listener on the collection element — put it on the collection's root. */
+    onFocusIn?: (event: FocusEvent) => void;
+}
+/** RAC `FieldInputContextValue`: what an Autocomplete / ComboBox passes to the input field it wraps. */
+export interface FieldInputContextValue {
+    id?: string;
+    /** The controlled text (accessor). */
+    value?: MaybeAccessor<string>;
+    onChange?: (value: string) => void;
+    onKeyDown?: (event: KeyboardEvent) => void;
+    onKeyUp?: (event: KeyboardEvent) => void;
+    onFocus?: (event: FocusEvent) => void;
+    onBlur?: (event: FocusEvent) => void;
+    onFocusChange?: (isFocused: boolean) => void;
+    onPointerDown?: (event: PointerEvent) => void;
+    /** Rivet: RA's `beforeinput` listener on the input (`useEvent`) — put it on the `<input>`. */
+    onBeforeInput?: (event: InputEvent) => void;
+    enterKeyHint?: "enter" | "done" | "go" | "next" | "previous" | "search" | "send";
+    "aria-controls"?: MaybeAccessor<string | undefined>;
+    "aria-autocomplete"?: "none" | "inline" | "list" | "both";
+    "aria-activedescendant"?: MaybeAccessor<string | undefined>;
+    spellCheck?: boolean | "true" | "false";
+    autoCorrect?: string;
+    autoComplete?: string;
+}
+/** Props for the nearest `<Autocomplete>` (slotted). */
+export declare const AutocompleteContext: import("@rivetjs/reactivity").Context<SlottedContextValue<Partial<AutocompleteProps<any>>>>;
+/** The state of the nearest `<Autocomplete>`. */
+export declare const AutocompleteStateContext: import("@rivetjs/reactivity").Context<AutocompleteState | null>;
+/** Collection props from the nearest `<Autocomplete>` (ListBox, Menu, GridList, TagGroup, Table merge it with `contextProps`). */
+export declare const SelectableCollectionContext: import("@rivetjs/reactivity").Context<ContextValue<SelectableCollectionContextValue<any>, HTMLElement>>;
+/** Input props from the nearest `<Autocomplete>` / `<ComboBox>` (SearchField, TextField merge it with `contextProps`). */
+export declare const FieldInputContext: import("@rivetjs/reactivity").Context<ContextValue<FieldInputContextValue, HTMLInputElement>>;

package/autocomplete/contexts.js

@@ -0,0 +1,28 @@
+// Ported from react-aria-components Autocomplete (packages/react-aria-components/src/Autocomplete.tsx:
+// `AutocompleteContext`, `AutocompleteStateContext`, `SelectableCollectionContext`, `FieldInputContext`),
+// Apache-2.0, © Adobe.
+// The contexts an `<Autocomplete>` (and ComboBox: FieldInputContext) provides: the wrapped input field
+// (SearchField / TextField) merges `FieldInputContext`, the wrapped collection (ListBox / Menu / GridList /
+// TagGroup / Table) merges `SelectableCollectionContext`.
+// Rivet:
+// - one tiny module (no component code): collections import it without pulling the Autocomplete in.
+// - `resumableContext` tokens (ids `rv-autocomplete`, `rv-autocomplete-state`, `rv-selectable-collection`,
+//   `rv-field-input`): values serialize (signals, `ref()`, strings, inline-arrow closures from `.tsx`).
+// - ACCESSOR RULE: state-dependent values are accessors read inside bindings / at event time:
+//   FieldInputContext `value`, `aria-activedescendant`, `aria-controls`; SelectableCollectionContext
+//   `shouldUseVirtualFocus`, `disallowTypeAhead`, `autoFocus`.
+// - Deviation: RA `useAutocomplete` adds a `focusin` listener on the collection element and a
+//   `beforeinput` listener on the input (`useEvent`); here they are props in the contexts —
+//   `SelectableCollectionContext.onFocusIn` (the collection puts it on its root element) and
+//   `FieldInputContext.onBeforeInput` (the field puts it on its `<input>`), so they resume as delegated
+//   handlers without an effect.
+import { createContext } from "@rivetjs/reactivity";
+import { resumableContext } from "@rivetjs/runtime/resume-format";
+/** Props for the nearest `<Autocomplete>` (slotted). */
+export const AutocompleteContext = resumableContext(createContext(null, { id: "rv-autocomplete" }));
+/** The state of the nearest `<Autocomplete>`. */
+export const AutocompleteStateContext = resumableContext(createContext(null, { id: "rv-autocomplete-state" }));
+/** Collection props from the nearest `<Autocomplete>` (ListBox, Menu, GridList, TagGroup, Table merge it with `contextProps`). */
+export const SelectableCollectionContext = resumableContext(createContext(null, { id: "rv-selectable-collection" }));
+/** Input props from the nearest `<Autocomplete>` / `<ComboBox>` (SearchField, TextField merge it with `contextProps`). */
+export const FieldInputContext = resumableContext(createContext(null, { id: "rv-field-input" }));

package/autocomplete/index.d.ts

@@ -0,0 +1,12 @@
+import type { Content } from "@rivetjs/runtime/jsx-runtime";
+import { type SlotProps } from "../slots/index.jsx";
+import { type AriaAutocompleteProps } from "./behaviour.jsx";
+export { AutocompleteContext, AutocompleteStateContext, FieldInputContext, SelectableCollectionContext, type FieldInputContextValue, type SelectableCollectionContextValue, } from "./contexts.js";
+export type { AutocompleteState } from "../state/autocomplete.js";
+export type { AriaAutocompleteProps } from "./behaviour.jsx";
+export interface AutocompleteProps<T = object> extends AriaAutocompleteProps<T>, SlotProps {
+    /** The children wrapped by the autocomplete. Consists of at least an input element and a collection element to filter. */
+    children?: Content;
+}
+/** An autocomplete allows users to search or filter a list of suggestions. */
+export declare function Autocomplete<T>(props: AutocompleteProps<T>): import("@rivetjs/runtime/jsx-runtime").CompiledElement;

package/autocomplete/index.jsx

@@ -0,0 +1,31 @@
+import { provide } from "@rivetjs/reactivity";
+import { probeCollection } from "../collections/components.jsx";
+import { useLocale } from "../i18n/index.js";
+import { mergeProps } from "../interactions/merge-props.jsx";
+import { Provider, removeDataAttributes, slottedContext } from "../slots/index.jsx";
+import { createAutocompleteState } from "../state/autocomplete.js";
+import { autocompleteProps } from "./behaviour.jsx";
+import { AutocompleteContext, AutocompleteStateContext, FieldInputContext, SelectableCollectionContext } from "./contexts.js";
+import { liveOptions } from "../utils/live.jsx";
+export { AutocompleteContext, AutocompleteStateContext, FieldInputContext, SelectableCollectionContext, } from "./contexts.js";
+/** An autocomplete allows users to search or filter a list of suggestions. */
+export function Autocomplete(props) {
+    const ctx = slottedContext(AutocompleteContext, props.slot);
+    props = mergeProps(ctx ?? {}, props);
+    // Live props: a controlled `inputValue={text()}` stays live (accessor; `controllable` reads it, never writes it).
+    const state = createAutocompleteState(liveOptions(props, [], ["inputValue"]));
+    const { inputProps, collectionProps, collectionRef, inputRef, filter } = autocompleteProps({ ...removeDataAttributes(props), filter: props.filter, disableAutoFocusFirst: props.disableAutoFocusFirst, locale: useLocale().locale }, state);
+    const children = props.children;
+    const collection = { ...collectionProps, filter, ref: collectionRef };
+    // Rivet (server): the collection's own id (RA mergeIds, applied after React's first render) is merged before the
+    // input's `aria-controls` is written — the resumed page never re-renders (collections/ `probeCollection`).
+    if (typeof document === "undefined")
+        provide(SelectableCollectionContext, collection, () => probeCollection(children));
+    return (<Provider values={[
+            [AutocompleteStateContext, state],
+            [FieldInputContext, { ...inputProps, ref: inputRef }],
+            [SelectableCollectionContext, collection],
+        ]}>
+      {children}
+    </Provider>);
+}

package/autocomplete/intl.d.ts

@@ -0,0 +1,2 @@
+import type { LocalizedStrings } from "../_adapters/intl.js";
+export declare const strings: LocalizedStrings;

package/autocomplete/intl.js

@@ -0,0 +1,36 @@
+export const strings = {
+    "ar-AE": { collectionLabel: "مقترحات" },
+    "bg-BG": { collectionLabel: "Предложения" },
+    "cs-CZ": { collectionLabel: "Návrhy" },
+    "da-DK": { collectionLabel: "Forslag" },
+    "de-DE": { collectionLabel: "Empfehlungen" },
+    "el-GR": { collectionLabel: "Προτάσεις" },
+    "en-US": { collectionLabel: "Suggestions" },
+    "es-ES": { collectionLabel: "Sugerencias" },
+    "et-EE": { collectionLabel: "Soovitused" },
+    "fi-FI": { collectionLabel: "Ehdotukset" },
+    "fr-FR": { collectionLabel: "Suggestions" },
+    "he-IL": { collectionLabel: "הצעות" },
+    "hr-HR": { collectionLabel: "Prijedlozi" },
+    "hu-HU": { collectionLabel: "Javaslatok" },
+    "it-IT": { collectionLabel: "Suggerimenti" },
+    "ja-JP": { collectionLabel: "候補" },
+    "ko-KR": { collectionLabel: "제안" },
+    "lt-LT": { collectionLabel: "Pasiūlymai" },
+    "lv-LV": { collectionLabel: "Ieteikumi" },
+    "nb-NO": { collectionLabel: "Forslag" },
+    "nl-NL": { collectionLabel: "Suggesties" },
+    "pl-PL": { collectionLabel: "Sugestie" },
+    "pt-BR": { collectionLabel: "Sugestões" },
+    "pt-PT": { collectionLabel: "Sugestões" },
+    "ro-RO": { collectionLabel: "Sugestii" },
+    "ru-RU": { collectionLabel: "Предложения" },
+    "sk-SK": { collectionLabel: "Návrhy" },
+    "sl-SI": { collectionLabel: "Predlogi" },
+    "sr-SP": { collectionLabel: "Predlozi" },
+    "sv-SE": { collectionLabel: "Förslag" },
+    "tr-TR": { collectionLabel: "Öneriler" },
+    "uk-UA": { collectionLabel: "Пропозиції" },
+    "zh-CN": { collectionLabel: "建议" },
+    "zh-TW": { collectionLabel: "建議" },
+};

package/bidi/bidi-dir.d.ts

@@ -0,0 +1,23 @@
+import type { Content } from "@rivetjs/runtime/jsx-runtime";
+import { type Direction } from "./index.js";
+export interface DirProps {
+    /** `"ltr"`, `"rtl"` or `"auto"` (case-insensitive); an accessor for a changing value. */
+    dir: string | (() => string);
+    /**
+     * Angular `(dirChange)`: called when the normalized direction changes after the first render.
+     * Client-rendered trees only — on a resumed page no component code runs, so read the
+     * `Directionality` signal (`injectDirectionality().valueSignal`) in a binding instead.
+     */
+    onDirChange?: (dir: Direction) => void;
+    /** Element to render (default `div`). */
+    as?: "div" | "span" | "section";
+    class?: string;
+    id?: string;
+    /**
+     * Content. Plain JSX children are lazy (a compiler slot rendered inside the provider), so
+     * descendants that read the `Directionality` (`injectDirectionality()`) see it; a render function
+     * `{() => <Child />}` works too.
+     */
+    children?: Content | (() => Content);
+}
+export declare function Dir(props: DirProps): import("@rivetjs/runtime/jsx-runtime").CompiledElement;

package/bidi/bidi-dir.jsx

@@ -0,0 +1,36 @@
+import { Provider } from "@rivetjs/runtime/dom";
+import { computed, effect, untrack } from "@rivetjs/reactivity";
+import { _resolveDirectionality, DirectionalityContext } from "./index.js";
+import { renderSlot } from "@rivetjs/runtime/slot";
+export function Dir(props) {
+    const source = props.dir;
+    const rawDir = typeof source === "function" ? source : () => source;
+    const valueSignal = computed(() => _resolveDirectionality(rawDir()));
+    const state = { valueSignal, rawDir };
+    const onDirChange = props.onDirChange;
+    if (onDirChange) {
+        let previous = untrack(valueSignal);
+        effect(() => {
+            const next = valueSignal();
+            if (next !== previous) {
+                previous = next;
+                untrack(() => onDirChange(next));
+            }
+        });
+    }
+    const children = props.children;
+    const content = (<Provider token={DirectionalityContext} value={state}>
+      {renderSlot(children)}
+    </Provider>);
+    if (props.as === "span")
+        return (<span id={props.id} class={props.class} dir={rawDir()}>
+        {content}
+      </span>);
+    if (props.as === "section")
+        return (<section id={props.id} class={props.class} dir={rawDir()}>
+        {content}
+      </section>);
+    return (<div id={props.id} class={props.class} dir={rawDir()}>
+      {content}
+    </div>);
+}