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

package/a11y/live-announcer.d.ts

@@ -0,0 +1,53 @@
+export type AriaLivePoliteness = "off" | "polite" | "assertive";
+export interface LiveAnnouncerDefaultOptions {
+    /** Default politeness. */
+    politeness?: AriaLivePoliteness;
+    /** Default time (ms) after which the message is cleared. */
+    duration?: number;
+}
+export interface LiveAnnouncerOptions extends LiveAnnouncerDefaultOptions {
+    /** Use this element instead of creating one (LIVE_ANNOUNCER_ELEMENT_TOKEN). */
+    liveElement?: HTMLElement | null;
+    document?: Document;
+}
+/** Announces messages to screen readers through an aria-live region. */
+export declare class LiveAnnouncer {
+    private _liveElement;
+    private _document;
+    private _defaultOptions;
+    private _previousTimeout;
+    private _currentPromise;
+    private _currentResolve;
+    constructor(options?: LiveAnnouncerOptions);
+    /** Announce `message`; resolves once it is written to the live region. */
+    announce(message: string): Promise<void>;
+    announce(message: string, politeness?: AriaLivePoliteness): Promise<void>;
+    announce(message: string, duration?: number): Promise<void>;
+    announce(message: string, politeness?: AriaLivePoliteness, duration?: number): Promise<void>;
+    /** Clear the live region (a cleared region is not re-read on focus). */
+    clear(): void;
+    /** Remove the live element (ngOnDestroy). */
+    destroy(): void;
+    private _createLiveElement;
+    /** Modal dialogs hide the rest of the page from screen readers: make them own the live element. */
+    private _exposeAnnouncerToModals;
+}
+/** The shared LiveAnnouncer (created on first call). */
+export declare function getLiveAnnouncer(): LiveAnnouncer;
+/**
+ * The cdkAriaLive directive: announce the element's text content whenever it changes (not on
+ * attribute changes). Call `destroy()` on unmount.
+ */
+export declare class CdkAriaLive {
+    private _politeness;
+    private _previousAnnouncedText?;
+    private _observer;
+    /** Clear duration passed to the announcer. */
+    duration: number | undefined;
+    private readonly _element;
+    private readonly _liveAnnouncer;
+    constructor(element: HTMLElement, politeness?: AriaLivePoliteness, duration?: number, liveAnnouncer?: LiveAnnouncer);
+    get politeness(): AriaLivePoliteness;
+    set politeness(value: AriaLivePoliteness);
+    destroy(): void;
+}

package/a11y/live-announcer.js

@@ -0,0 +1,143 @@
+// LiveAnnouncer (one shared aria-live element, 100 ms delayed write so repeated messages are read,
+// optional clear duration, `aria-owns` exposure to open modals) and the cdkAriaLive directive.
+// Ported from Angular CDK a11y live-announcer (angular/components), MIT, © Google LLC.
+//
+// Rivet: a plain class; options replace the LIVE_ANNOUNCER_ELEMENT_TOKEN / _DEFAULT_OPTIONS tokens.
+// Deviation: messages are text only (Angular also accepts sanitized `SafeHtml`). The modal lookup
+// covers CDK overlay containers, Rivet modals (`[data-rv-overlay][aria-modal]`) and top-layer elements.
+// Browser only. For react-aria-style announcements use `@rivetjs/cdk/live-announcer`.
+import { hideVisually } from "./index.js";
+const g = { uniqueIds: 0 };
+/** Announces messages to screen readers through an aria-live region. */
+export class LiveAnnouncer {
+    _liveElement;
+    _document;
+    _defaultOptions;
+    _previousTimeout;
+    _currentPromise;
+    _currentResolve;
+    constructor(options = {}) {
+        this._document = options.document ?? document;
+        this._defaultOptions = options.politeness || options.duration != null ? { politeness: options.politeness, duration: options.duration } : null;
+        this._liveElement = options.liveElement || this._createLiveElement();
+    }
+    announce(message, ...args) {
+        const defaultOptions = this._defaultOptions;
+        let politeness;
+        let duration;
+        if (args.length === 1 && typeof args[0] === "number")
+            duration = args[0];
+        else
+            [politeness, duration] = args;
+        this.clear();
+        clearTimeout(this._previousTimeout);
+        if (!politeness)
+            politeness = defaultOptions && defaultOptions.politeness ? defaultOptions.politeness : "polite";
+        if (duration == null && defaultOptions)
+            duration = defaultOptions.duration;
+        this._liveElement.setAttribute("aria-live", politeness);
+        if (this._liveElement.id)
+            this._exposeAnnouncerToModals(this._liveElement.id);
+        // The 100 ms delay: some browser + screen reader pairs skip immediate or repeated identical writes.
+        if (!this._currentPromise)
+            this._currentPromise = new Promise((resolve) => (this._currentResolve = resolve));
+        clearTimeout(this._previousTimeout);
+        this._previousTimeout = setTimeout(() => {
+            this._liveElement.textContent = message;
+            if (typeof duration === "number")
+                this._previousTimeout = setTimeout(() => this.clear(), duration);
+            this._currentResolve?.();
+            this._currentPromise = this._currentResolve = undefined;
+        }, 100);
+        return this._currentPromise;
+    }
+    /** Clear the live region (a cleared region is not re-read on focus). */
+    clear() {
+        if (this._liveElement)
+            this._liveElement.textContent = "";
+    }
+    /** Remove the live element (ngOnDestroy). */
+    destroy() {
+        clearTimeout(this._previousTimeout);
+        this._liveElement?.remove();
+        this._liveElement = null;
+        this._currentResolve?.();
+        this._currentPromise = this._currentResolve = undefined;
+    }
+    _createLiveElement() {
+        const elementClass = "cdk-live-announcer-element";
+        const previousElements = this._document.getElementsByClassName(elementClass);
+        const liveEl = this._document.createElement("div");
+        // Remove stale containers (e.g. server-rendered).
+        for (let i = previousElements.length - 1; i >= 0; i--)
+            previousElements[i].remove();
+        liveEl.classList.add(elementClass, "cdk-visually-hidden");
+        hideVisually(liveEl);
+        liveEl.setAttribute("aria-atomic", "true");
+        liveEl.setAttribute("aria-live", "polite");
+        liveEl.id = `cdk-live-announcer-${g.uniqueIds++}`;
+        this._document.body.appendChild(liveEl);
+        return liveEl;
+    }
+    /** Modal dialogs hide the rest of the page from screen readers: make them own the live element. */
+    _exposeAnnouncerToModals(id) {
+        const modals = this._document.querySelectorAll('body > .cdk-overlay-container [aria-modal="true"], [data-rv-top-layer] [aria-modal="true"], [data-rv-top-layer][aria-modal="true"], [data-rv-overlay][aria-modal="true"]');
+        for (let i = 0; i < modals.length; i++) {
+            const modal = modals[i];
+            const ariaOwns = modal.getAttribute("aria-owns");
+            if (!ariaOwns)
+                modal.setAttribute("aria-owns", id);
+            else if (ariaOwns.indexOf(id) === -1)
+                modal.setAttribute("aria-owns", ariaOwns + " " + id);
+        }
+    }
+}
+let shared = null;
+/** The shared LiveAnnouncer (created on first call). */
+export function getLiveAnnouncer() {
+    return (shared ??= new LiveAnnouncer());
+}
+/**
+ * The cdkAriaLive directive: announce the element's text content whenever it changes (not on
+ * attribute changes). Call `destroy()` on unmount.
+ */
+export class CdkAriaLive {
+    _politeness = "polite";
+    _previousAnnouncedText;
+    _observer;
+    /** Clear duration passed to the announcer. */
+    duration;
+    _element;
+    _liveAnnouncer;
+    constructor(element, politeness = "polite", duration, liveAnnouncer = getLiveAnnouncer()) {
+        this._element = element;
+        this._liveAnnouncer = liveAnnouncer;
+        this.duration = duration;
+        this.politeness = politeness;
+    }
+    get politeness() {
+        return this._politeness;
+    }
+    set politeness(value) {
+        this._politeness = value === "off" || value === "assertive" ? value : "polite";
+        if (this._politeness === "off") {
+            this._observer?.disconnect();
+            this._observer = undefined;
+        }
+        else if (!this._observer) {
+            this._observer = new MutationObserver(() => {
+                const elementText = this._element.textContent;
+                if (elementText !== this._previousAnnouncedText) {
+                    void this._liveAnnouncer.announce(elementText ?? "", this._politeness, this.duration);
+                    this._previousAnnouncedText = elementText;
+                }
+            });
+            // ContentObserver: characterData + childList, subtree.
+            this._observer.observe(this._element, { characterData: true, childList: true, subtree: true });
+        }
+    }
+    destroy() {
+        this._observer?.disconnect();
+        this._observer = undefined;
+    }
+}

package/accordion/index.d.ts

@@ -0,0 +1,2 @@
+export * from "../disclosure/index.jsx";
+export { allowsMultiple, isKeyExpanded, registerDisclosure, setExpandedKeys, toggleKey, unregisterDisclosure, type DisclosureGroupProps as DisclosureGroupStateProps, } from "../state/disclosure.js";

package/accordion/index.jsx

@@ -0,0 +1,10 @@
+// `@rivetjs/cdk/accordion`: the Angular CDK accordion (angular/components src/cdk/accordion, MIT, © Google LLC)
+// merged into the RAC Disclosure parts (user decision 2026-10-06). One implementation lives in
+// `../disclosure/`; the Angular extras are on the same parts:
+// - CdkAccordion `multi` → DisclosureGroup / createDisclosureGroupState `allowsMultipleExpanded` (boolean or Signal);
+// - CdkAccordion `openAll()` / `closeAll()` → `openAll(state)` / `closeAll(state)` on a group state passed via
+//   `<DisclosureGroup state>` (disabled disclosures keep their state);
+// - CdkAccordionItem `(opened)` / `(closed)` / `(destroyed)` → Disclosure `onOpened` / `onClosed` / `onDestroyed`;
+// - CdkAccordionItem `expanded` / `disabled` / `(expandedChange)` → RAC `isExpanded` / `isDisabled` / `onExpandedChange`.
+export * from "../disclosure/index.jsx";
+export { allowsMultiple, isKeyExpanded, registerDisclosure, setExpandedKeys, toggleKey, unregisterDisclosure, } from "../state/disclosure.js";

package/announcer/index.d.ts

@@ -0,0 +1,8 @@
+/** Polite + assertive live regions (empty, visually hidden). */
+export declare function Announcer(props: {
+    class?: string;
+}): import("@rivetjs/runtime/jsx-runtime").CompiledElement;
+/** react-aria live announcer regions (assertive + polite logs), visually hidden. */
+export declare function LiveAnnouncerRegions(props: {
+    class?: string;
+}): import("@rivetjs/runtime/jsx-runtime").CompiledElement;

package/announcer/index.jsx

@@ -0,0 +1,22 @@
+// Server-rendered live regions, so they exist before the first announcement (screen readers ignore
+// regions created together with their content). Place once in the root layout.
+// - `<Announcer/>`: regions of `announce()` from `@rivetjs/cdk/a11y` (Angular LiveAnnouncer style).
+// - `<LiveAnnouncerRegions/>`: regions adopted by `announce()` from `@rivetjs/cdk/live-announcer`
+//   (react-aria style: `role="log"`, one node per message).
+// Hidden by inline styles (`visuallyHidden`); `class` adds a class of your own.
+import { visuallyHidden } from "../a11y/index.js";
+/** Polite + assertive live regions (empty, visually hidden). */
+export function Announcer(props) {
+    const hidden = props.class;
+    return (<div data-rv-announcers="">
+      <div data-rv-announcer="polite" aria-live="polite" aria-atomic="true" class={hidden} style={visuallyHidden}></div>
+      <div data-rv-announcer="assertive" aria-live="assertive" aria-atomic="true" class={hidden} style={visuallyHidden}></div>
+    </div>);
+}
+/** react-aria live announcer regions (assertive + polite logs), visually hidden. */
+export function LiveAnnouncerRegions(props) {
+    return (<div data-live-announcer="true" class={props.class} style={visuallyHidden}>
+      <div role="log" aria-live="assertive" aria-relevant="additions"></div>
+      <div role="log" aria-live="polite" aria-relevant="additions"></div>
+    </div>);
+}

package/announcer/live-announcer.d.ts

@@ -0,0 +1,15 @@
+export type Assertiveness = "assertive" | "polite";
+type Message = string | {
+    "aria-labelledby": string;
+};
+/** Test hook: announce synchronously on creation (the original checks for a jest / act environment). */
+export declare const announcerOptions: {
+    immediate: boolean;
+};
+/** Announce `message` with screen reader technology (assertive by default; removed after `timeout` ms). */
+export declare function announce(message: Message, assertiveness?: Assertiveness, timeout?: number): void;
+/** Stop queued announcements (one politeness, or both when omitted). */
+export declare function clearAnnouncer(assertiveness?: Assertiveness): void;
+/** Remove the announcer from the DOM. */
+export declare function destroyAnnouncer(): void;
+export {};

package/announcer/live-announcer.js

@@ -0,0 +1,123 @@
+// Live announcer: screen reader announcements through assertive / polite `role="log"` live regions,
+// each message its own node (removed after `timeout`), `aria-labelledby` messages, clear / destroy.
+// Ported from @react-aria/live-announcer (react-spectrum), Apache-2.0, © Adobe.
+//
+// Deviation: the regions are created on the first `announce()` (no import-time globals). A
+// server-rendered `<LiveAnnouncerRegions/>` (`@rivetjs/cdk/announcer`) is adopted when present, so
+// even the first message is announced without the original's 100 ms creation delay.
+// For the Angular-style single-message region (politeness default "polite"), see `announce` in
+// `@rivetjs/cdk/a11y`.
+const LIVEREGION_TIMEOUT_DELAY = 7000;
+class LiveAnnouncer {
+    node = null;
+    assertiveLog = null;
+    politeLog = null;
+    adopted = false;
+    constructor() {
+        if (typeof document === "undefined")
+            return;
+        const existing = document.querySelector("[data-live-announcer]");
+        if (existing) {
+            this.node = existing;
+            this.adopted = true;
+            this.assertiveLog = existing.querySelector('[aria-live="assertive"]');
+            this.politeLog = existing.querySelector('[aria-live="polite"]');
+            return;
+        }
+        this.node = document.createElement("div");
+        this.node.dataset.liveAnnouncer = "true";
+        // VisuallyHidden.
+        Object.assign(this.node.style, {
+            border: "0",
+            clip: "rect(0 0 0 0)",
+            clipPath: "inset(50%)",
+            height: "1px",
+            margin: "-1px",
+            overflow: "hidden",
+            padding: "0",
+            position: "absolute",
+            width: "1px",
+            whiteSpace: "nowrap",
+        });
+        this.assertiveLog = this.createLog("assertive");
+        this.node.appendChild(this.assertiveLog);
+        this.politeLog = this.createLog("polite");
+        this.node.appendChild(this.politeLog);
+        document.body.prepend(this.node);
+    }
+    isAttached() {
+        return !!this.node?.isConnected;
+    }
+    createLog(ariaLive) {
+        const node = document.createElement("div");
+        node.setAttribute("role", "log");
+        node.setAttribute("aria-live", ariaLive);
+        node.setAttribute("aria-relevant", "additions");
+        return node;
+    }
+    destroy() {
+        if (!this.node)
+            return;
+        if (this.adopted)
+            this.clear();
+        else
+            this.node.remove();
+        this.node = null;
+    }
+    announce(message, assertiveness = "assertive", timeout = LIVEREGION_TIMEOUT_DELAY) {
+        if (!this.node)
+            return;
+        const node = document.createElement("div");
+        if (typeof message === "object") {
+            // aria-labelledby is read only with an appropriate role, such as img.
+            node.setAttribute("role", "img");
+            node.setAttribute("aria-labelledby", message["aria-labelledby"]);
+        }
+        else
+            node.textContent = message;
+        if (assertiveness === "assertive")
+            this.assertiveLog?.appendChild(node);
+        else
+            this.politeLog?.appendChild(node);
+        if (message !== "")
+            setTimeout(() => node.remove(), timeout);
+    }
+    clear(assertiveness) {
+        if (!this.node)
+            return;
+        if ((!assertiveness || assertiveness === "assertive") && this.assertiveLog)
+            this.assertiveLog.innerHTML = "";
+        if ((!assertiveness || assertiveness === "polite") && this.politeLog)
+            this.politeLog.innerHTML = "";
+    }
+}
+let liveAnnouncer = null;
+/** Test hook: announce synchronously on creation (the original checks for a jest / act environment). */
+export const announcerOptions = { immediate: false };
+/** Announce `message` with screen reader technology (assertive by default; removed after `timeout` ms). */
+export function announce(message, assertiveness = "assertive", timeout = LIVEREGION_TIMEOUT_DELAY) {
+    if (!liveAnnouncer) {
+        liveAnnouncer = new LiveAnnouncer();
+        // Safari skips messages added right after the regions: wait 100 ms for created ones.
+        if (!liveAnnouncer.adopted && !announcerOptions.immediate)
+            setTimeout(() => {
+                if (liveAnnouncer?.isAttached())
+                    liveAnnouncer.announce(message, assertiveness, timeout);
+            }, 100);
+        else
+            liveAnnouncer.announce(message, assertiveness, timeout);
+    }
+    else
+        liveAnnouncer.announce(message, assertiveness, timeout);
+}
+/** Stop queued announcements (one politeness, or both when omitted). */
+export function clearAnnouncer(assertiveness) {
+    liveAnnouncer?.clear(assertiveness);
+}
+/** Remove the announcer from the DOM. */
+export function destroyAnnouncer() {
+    if (liveAnnouncer) {
+        liveAnnouncer.destroy();
+        liveAnnouncer = null;
+    }
+}

package/autocomplete/behaviour.d.ts

@@ -0,0 +1,94 @@
+import { type Signal } from "@rivetjs/reactivity";
+import type { Ref } from "@rivetjs/runtime/jsx-runtime";
+import type { Node } from "../collections/types.js";
+import { type MergedId } from "../slots/index.jsx";
+import { type AutocompleteState, type AutocompleteStateProps } from "../state/autocomplete.js";
+import type { FieldInputContextValue, SelectableCollectionContextValue } from "./contexts.js";
+export interface AriaAutocompleteProps<T> extends AutocompleteStateProps {
+    /**
+     * An optional filter function used to determine if a option should be included in the autocomplete list.
+     * Include this if the items you are providing to your wrapped collection aren't filtered by default.
+     */
+    filter?: (textValue: string, inputValue: string, node: Node<T>) => boolean;
+    /**
+     * Whether or not to focus the first item in the collection after a filter is performed. Note this is only
+     * applicable if virtual focus behavior is not turned off via `disableVirtualFocus`.
+     *
+     * @default false
+     */
+    disableAutoFocusFirst?: boolean;
+    /**
+     * Whether the autocomplete should disable virtual focus, instead making the wrapped collection directly tabbable.
+     *
+     * @default false
+     */
+    disableVirtualFocus?: boolean;
+}
+/** RAC `AutocompleteProps`. */
+export interface AutocompleteProps<T = object> extends AriaAutocompleteProps<T> {
+    /** The children wrapped by the autocomplete. Consists of at least an input element and a collection element to filter. */
+    children?: unknown;
+    slot?: string | null;
+}
+export interface AriaAutocompleteOptions<T> extends Omit<AriaAutocompleteProps<T>, "children"> {
+    /** The ref for the wrapped input element (default: a new `ref()`). */
+    inputRef?: Ref<HTMLInputElement>;
+    /** The ref for the wrapped collection element (default: a new `ref()`). */
+    collectionRef?: Ref<HTMLElement>;
+    /** Locale of the default collection label (default "en-US"). */
+    locale?: string;
+}
+/** Per-instance serializable data of `autocompleteProps` (ids, refs, signals). */
+export interface AutocompleteAriaState {
+    /** The collection id (RA `useId`), merged into the collection's own id when it has one (RA `mergeIds`). */
+    readonly collectionId: MergedId;
+    readonly inputRef: Ref<HTMLInputElement>;
+    readonly collectionRef: Ref<HTMLElement>;
+    /** Upstream `shouldUseVirtualFocus` state (initial value). */
+    readonly virtualFocus: boolean;
+    readonly autoFocusOnMount: Signal<boolean>;
+    readonly disableAutoFocusFirst: boolean;
+}
+export interface AutocompleteAria<T> {
+    /** Props for the autocomplete input element (`FieldInputContext`). */
+    inputProps: FieldInputContextValue;
+    /** Props for the collection (`SelectableCollectionContext`). */
+    collectionProps: SelectableCollectionContextValue<T>;
+    /** Ref to attach to the wrapped collection. */
+    collectionRef: Ref<HTMLElement>;
+    /** Ref to attach to the wrapped input. */
+    inputRef: Ref<HTMLInputElement>;
+    /** A filter function that returns if the provided collection node should be filtered out of the collection. */
+    filter?: (nodeTextValue: string, node: Node<T>) => boolean;
+    /** @internal the per-instance data the handlers take. */
+    aria: AutocompleteAriaState;
+}
+/** Whether a collection is connected (attached; true on the server). */
+export declare function autocompleteHasCollection(aria: AutocompleteAriaState): boolean;
+/** Whether the input drives the collection with virtual focus (upstream `shouldUseVirtualFocus` state). */
+export declare function autocompleteShouldUseVirtualFocus(aria: AutocompleteAriaState): boolean;
+/**
+ * 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 declare function autocompleteProps<T>(props: AriaAutocompleteOptions<T>, state: AutocompleteState): AutocompleteAria<T>;
+/** Upstream `updateActiveDescendantEvent`: the collection's `focusin` (virtual focus moves to an item). */
+export declare function autocompleteFocusIn(e: Event, aria: AutocompleteAriaState, state: AutocompleteState): void;
+/** Upstream `focusFirstItem`. */
+export declare function autocompleteFocusFirstItem(aria: AutocompleteAriaState): void;
+/** Upstream `clearVirtualFocus`. */
+export declare function autocompleteClearVirtualFocus(aria: AutocompleteAriaState, state: AutocompleteState, clearFocusKey?: boolean): void;
+/** Upstream `useEvent(inputRef, 'beforeinput')`. */
+export declare function autocompleteBeforeInput(e: InputEvent, aria: AutocompleteAriaState): void;
+/** Upstream `onChange` (the input's text changed). */
+export declare function autocompleteChange(value: string, aria: AutocompleteAriaState, state: AutocompleteState): void;
+/** Upstream `onKeyDown` (textfield specific keydown operations). */
+export declare function autocompleteKeyDown(e: KeyboardEvent, aria: AutocompleteAriaState, state: AutocompleteState): void;
+/** Upstream `onKeyUpCapture` (document capture listener). */
+export declare function autocompleteKeyUpCapture(e: KeyboardEvent, aria: AutocompleteAriaState): void;
+/** Upstream `onBlur`. */
+export declare function autocompleteBlur(e: FocusEvent, aria: AutocompleteAriaState): void;
+/** Upstream `onFocus`. */
+export declare function autocompleteFocus(e: FocusEvent, aria: AutocompleteAriaState): void;
+/** Upstream `onPointerDown`. */
+export declare function autocompletePointerDown(e: PointerEvent, aria: AutocompleteAriaState, state: AutocompleteState): void;