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

package/search-field/index.jsx

@@ -0,0 +1,158 @@
+// Ported from react-aria-components SearchField (packages/react-aria-components/src/SearchField.tsx), Apache-2.0, © Adobe.
+// A search field allows a user to enter and clear a search query.
+// Rivet:
+// - composed from parts like RAC: `<SearchField><Label/><Input/><Button/><Text slot="description"/><FieldError/></SearchField>`;
+//   provides `LabelContext`, `InputContext`, `ButtonContext` (the clear button), `TextContext`
+//   (description / errorMessage slots), `GroupContext`, `FieldErrorContext`.
+// - merges `SearchFieldContext`, then `FieldInputContext` (an enclosing `<Autocomplete>`: value accessor,
+//   `onChange`, virtual-focus key handling, `aria-activedescendant` / `aria-controls` accessors, input ref).
+// - `value`: plain = controlled, Signal = two-way, accessor = controlled read live (`state/search-field.ts`).
+// - input bags hold accessors (`value`, `aria-invalid`, `aria-describedby`, `aria-labelledby`); render props
+//   are accessors (`class={({ isEmpty }) => (isEmpty() ? "empty" : "")}`), `state` is the SearchFieldState.
+// - description / error ids are slot ids (RA `useSlotId`): part of `aria-describedby` while that part renders (server: a slot
+//   probe, `probeSlots`, marks them before the input renders, as Select / TextField).
+// `render` (RAC DOMRenderProps): given, the attributes go to `render(attrs, SearchFieldRenderProps)` instead of the default `<div>`.
+import { isHidden } from "../collections/components.jsx";
+import { probeSlots, slotProbing } from "#server";
+import { createContext, untrack } from "@rivetjs/reactivity";
+import { ref as createRef } from "@rivetjs/runtime/dom";
+import { read } from "../state/form-validation.js";
+import { formValidationBehavior, formValidationErrors } from "../form/index.jsx";
+import { FieldErrorContext } from "../form/field-error.jsx";
+import { LabelContext } from "../label/index.jsx";
+import { InputContext } from "../input/index.jsx";
+import { TextContext } from "../text/index.jsx";
+import { ButtonContext } from "../button/index.jsx";
+import { GroupContext } from "../group/index.jsx";
+import { FieldInputContext } from "../autocomplete/contexts.js";
+import { useLocale } from "../i18n/index.js";
+import { dataBool } from "../utils/data-attrs.jsx";
+import {} from "../utils/render.js";
+import { globalDOMProps } from "../utils/dom-props.js";
+import { Provider, resumableContext, contextProps, createSlot, createSlotId, slotIdRef, } from "../slots/index.jsx";
+import { createSearchFieldState, searchFieldValue } from "../state/search-field.js";
+import { searchFieldProps } from "./behaviour.jsx";
+import { hasLive, liveOptions, liveWithoutData } from "../utils/live.jsx";
+import { renderPropsOf } from "../slots/index.jsx";
+/** RAC `SearchFieldContext`. */
+export const SearchFieldContext = resumableContext(createContext(null, { id: "rv-search-field" }));
+const OWNED = ["style", "render"];
+/** A search field allows a user to enter and clear a search query. */
+export function SearchField(props) {
+    // RAC createHideableComponent: nothing inside a parent's collection build pass.
+    if (isHidden())
+        return null;
+    // Live props (P5): live state / attribute keys become accessors at the boundary (as TextField), `value` is controlled
+    // (an accessor only when defined at creation); class / style / children from a live view; body untracked.
+    return untrack(() => searchField(props));
+}
+/** Live by default (LIVE-SWEEP): every attribute-like prop; read once: `id`, `name`, `aria-label` / `aria-labelledby`,
+ *  `autoFocus`, `defaultValue`, `validationBehavior`, `validate`, handlers. */
+const LIVE_KEYS = [
+    "isDisabled",
+    "isReadOnly",
+    "isRequired",
+    "isInvalid",
+    "type",
+    "placeholder",
+    "pattern",
+    "maxLength",
+    "minLength",
+    "autoComplete",
+    "autoCapitalize",
+    "autoCorrect",
+    "spellCheck",
+    "inputMode",
+    "enterKeyHint",
+    "form",
+    "excludeFromTabOrder",
+    "aria-describedby",
+    "aria-details",
+    "aria-errormessage",
+    "aria-controls",
+    "aria-activedescendant",
+    "aria-autocomplete",
+    "aria-haspopup",
+];
+function searchField(props) {
+    // Inside another field's server slot probe (`probeSlots`): this field's subtree holds none of that field's slots.
+    if (slotProbing)
+        return null;
+    const [own, ref] = contextProps(props, props.ref, SearchFieldContext);
+    const validationBehavior = formValidationBehavior(own.validationBehavior);
+    const [ctxMerged, fieldInputRef] = contextProps(own, undefined, FieldInputContext);
+    const merged = hasLive(ctxMerged) ? liveOptions(ctxMerged, LIVE_KEYS, ["value"]) : ctxMerged;
+    const inputRef = fieldInputRef ?? createRef();
+    const initialLabel = !merged["aria-label"] && !merged["aria-labelledby"];
+    const [labelRef, hasLabel] = createSlot(initialLabel);
+    const state = createSearchFieldState({ value: merged.value, defaultValue: merged.defaultValue, onChange: merged.onChange });
+    const { labelProps, inputProps, clearButtonProps, descriptionProps, errorMessageProps, ids, isInvalid, validationErrors, validationDetails } = searchFieldProps({
+        ...liveWithoutData(merged),
+        label: initialLabel,
+        validationBehavior,
+        validationErrors: formValidationErrors(),
+        locale: useLocale().locale,
+    }, state, inputRef);
+    // RA useSlotId: the description / error ids are described-by while their part renders.
+    const descriptionId = createSlotId(descriptionProps.id ?? (merged.id ? merged.id + "-description" : undefined));
+    // The error part renders while invalid: re-check its id when that changes.
+    const errorId = createSlotId(errorMessageProps.id, isInvalid);
+    const extraDescribedBy = merged["aria-describedby"];
+    const labelledBy = ids.fieldProps["aria-labelledby"];
+    const ownLabelledBy = merged["aria-labelledby"];
+    const input = {
+        ...inputProps,
+        "aria-labelledby": () => (!initialLabel || hasLabel() ? labelledBy : ownLabelledBy),
+        // Ids of the parts that render; server: marked by the slot probe below (a resumed page never re-renders).
+        "aria-describedby": () => [slotIdRef(descriptionId, false), slotIdRef(errorId, isInvalid()), read(extraDescribedBy)].filter(Boolean).join(" ") || undefined,
+        ref: inputRef,
+    };
+    const isEmpty = () => searchFieldValue(state) === "";
+    const disabledProp = merged.isDisabled;
+    const readOnlyProp = merged.isReadOnly;
+    const isDisabled = () => !!read(disabledProp);
+    const isReadOnly = () => !!read(readOnlyProp);
+    const requiredProp = merged.isRequired;
+    const isRequired = () => !!read(requiredProp);
+    const renderValues = { isEmpty, isDisabled, isInvalid, isReadOnly, isRequired, state };
+    const rp = renderPropsOf(merged, {
+        values: renderValues,
+        defaultClassName: "rv-SearchField",
+    });
+    // Object-literal function value (R2 resumable symbol, as TextField's): with a plain const arrow the FieldError of
+    // a resumed SearchField never saw the validation.
+    const fieldError = {
+        validation: () => ({ isInvalid: isInvalid(), validationErrors: validationErrors(), validationDetails: validationDetails() }),
+    };
+    const dom = globalDOMProps(merged, OWNED);
+    delete dom.id;
+    const slot = merged.slot || undefined;
+    const values = [
+        [LabelContext, { ...labelProps, ref: labelRef }],
+        [InputContext, input],
+        [ButtonContext, clearButtonProps],
+        [TextContext, { slots: { description: { id: descriptionId }, errorMessage: { id: errorId } } }],
+        [GroupContext, { isInvalid, isDisabled: disabledProp }],
+        [FieldErrorContext, fieldError.validation],
+    ];
+    // Rivet (server): the input renders before its Description / FieldError: probe which slotted parts render (as Select).
+    if (typeof document === "undefined")
+        probeSlots(values, () => rp.children());
+    if (merged.render)
+        return merged.render({
+            ...dom,
+            ref: ref,
+            class: () => rp.class(),
+            style: () => rp.style(),
+            slot,
+            "data-empty": () => dataBool(isEmpty()),
+            "data-disabled": () => dataBool(isDisabled()),
+            "data-invalid": () => dataBool(isInvalid()),
+            "data-readonly": () => dataBool(isReadOnly()),
+            "data-required": () => dataBool(isRequired()),
+            children: () => <Provider values={values}>{rp.children()}</Provider>,
+        }, renderValues);
+    return (<div {...dom} ref={ref} class={rp.class()} style={rp.style()} slot={slot} data-empty={dataBool(isEmpty())} data-disabled={dataBool(isDisabled())} data-invalid={dataBool(isInvalid())} data-readonly={dataBool(isReadOnly())} data-required={dataBool(isRequired())}>
+      <Provider values={values}>{rp.children()}</Provider>
+    </div>);
+}

package/search-field/intl.d.ts

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

package/search-field/intl.js

@@ -0,0 +1,36 @@
+export const strings = {
+    "ar-AE": { "Clear search": "مسح البحث" },
+    "bg-BG": { "Clear search": "Изчистване на търсене" },
+    "cs-CZ": { "Clear search": "Vymazat hledání" },
+    "da-DK": { "Clear search": "Ryd søgning" },
+    "de-DE": { "Clear search": "Suche zurücksetzen" },
+    "el-GR": { "Clear search": "Απαλοιφή αναζήτησης" },
+    "en-US": { "Clear search": "Clear search" },
+    "es-ES": { "Clear search": "Borrar búsqueda" },
+    "et-EE": { "Clear search": "Tühjenda otsing" },
+    "fi-FI": { "Clear search": "Tyhjennä haku" },
+    "fr-FR": { "Clear search": "Effacer la recherche" },
+    "he-IL": { "Clear search": "נקה חיפוש" },
+    "hr-HR": { "Clear search": "Obriši pretragu" },
+    "hu-HU": { "Clear search": "Keresés törlése" },
+    "it-IT": { "Clear search": "Cancella ricerca" },
+    "ja-JP": { "Clear search": "検索をクリア" },
+    "ko-KR": { "Clear search": "검색 지우기" },
+    "lt-LT": { "Clear search": "Išvalyti iešką" },
+    "lv-LV": { "Clear search": "Notīrīt meklēšanu" },
+    "nb-NO": { "Clear search": "Tøm søk" },
+    "nl-NL": { "Clear search": "Zoekactie wissen" },
+    "pl-PL": { "Clear search": "Wyczyść zawartość wyszukiwania" },
+    "pt-BR": { "Clear search": "Limpar pesquisa" },
+    "pt-PT": { "Clear search": "Limpar pesquisa" },
+    "ro-RO": { "Clear search": "Ştergeţi căutarea" },
+    "ru-RU": { "Clear search": "Очистить поиск" },
+    "sk-SK": { "Clear search": "Vymazať vyhľadávanie" },
+    "sl-SI": { "Clear search": "Počisti iskanje" },
+    "sr-SP": { "Clear search": "Obriši pretragu" },
+    "sv-SE": { "Clear search": "Rensa sökning" },
+    "tr-TR": { "Clear search": "Aramayı temizle" },
+    "uk-UA": { "Clear search": "Очистити пошук" },
+    "zh-CN": { "Clear search": "清除搜索" },
+    "zh-TW": { "Clear search": "清除搜尋條件" },
+};

package/select/behaviour.d.ts

@@ -0,0 +1,188 @@
+import { type Signal } from "@rivetjs/reactivity";
+import { type Key, type Selection } from "../_adapters/collections.js";
+import { type FocusStrategy, type SelectionMode, type SelectState } from "../state/select.js";
+type AnySelect = SelectState<SelectionMode>;
+/** Part ids (useSelect: trigger = field, value = SelectValue, listbox = the menu). */
+export declare const triggerId: (state: {
+    id: string;
+}) => string;
+export declare const labelId: (state: {
+    id: string;
+}) => string;
+export declare const valueId: (state: {
+    id: string;
+}) => string;
+export declare const listId: (state: {
+    id: string;
+}) => string;
+export declare const popoverId: (state: {
+    id: string;
+}) => string;
+export declare const hiddenId: (state: {
+    id: string;
+}) => string;
+/** Props of `selectProps` (react-aria `AriaSelectOptions`: the labelling part). */
+export interface SelectAriaProps {
+    /** Visible label (RA `label`): whether a label element labels the trigger. */
+    label?: unknown;
+    /** Description (RA `description`): reserves the description id. */
+    description?: unknown;
+    "aria-label"?: string | undefined;
+    "aria-labelledby"?: string | undefined;
+    "aria-describedby"?: string | undefined;
+}
+/**
+ * `isDisabled` for attribute / context bags (live props P5): the live accessor when the select's `isDisabled` is one
+ * (a returned arrow: resumable), else the creation value.
+ */
+export declare function selectDisabled(state: SelectState<SelectionMode>): boolean | (() => boolean);
+/** `data-required` for a spread / render bag: an accessor when live (returned arrow), else the value. */
+export declare function selectRequiredAttr(state: SelectState<SelectionMode>): "true" | undefined | (() => "true" | undefined);
+/** `data-disabled` for a spread / render bag: an accessor when live (returned arrow), else the value. */
+export declare function selectDisabledAttr(state: SelectState<SelectionMode>): "true" | undefined | (() => "true" | undefined);
+/**
+ * react-aria `useSelect` attribute bags (same keys as RA). Ids and ARIA attributes only: the handlers
+ * are the exported free functions (`selectTriggerKeyDown`, `selectListEvent`, …), attached as inline
+ * arrows so they resume. Reactive values are accessors (`triggerProps["aria-expanded"]()`).
+ */
+export declare function selectProps(props: SelectAriaProps, state: AnySelect): {
+    ids: import("../label/behaviour.js").FieldIds;
+    labelProps: {
+        id: string;
+    };
+    triggerProps: {
+        id: string;
+        "aria-haspopup": "listbox";
+        "aria-expanded": () => "true" | "false";
+        "aria-controls": () => string | undefined;
+        "aria-label": string | undefined;
+        "aria-labelledby": string;
+        isDisabled: boolean | (() => boolean);
+    };
+    valueProps: {
+        id: string;
+    };
+    menuProps: {
+        id: string;
+        "aria-labelledby": string | undefined;
+        autoFocus: () => true | FocusStrategy;
+        shouldSelectOnPressUp: boolean;
+        shouldFocusOnHover: boolean;
+        disallowEmptySelection: boolean;
+        linkBehavior: "selection";
+    };
+    descriptionProps: {
+        id: string | undefined;
+    };
+    errorMessageProps: {
+        id: string;
+    };
+    hiddenSelectProps: {
+        isDisabled: boolean | (() => boolean);
+        name: string | undefined;
+        form: string | undefined;
+        state: AnySelect;
+    };
+};
+/** Keys the closed trigger handles (`data-rk`: a cold arrow key does not scroll the page while code loads). */
+export declare const TRIGGER_KEYS = "Enter Space ArrowDown ArrowUp ArrowLeft ArrowRight";
+/** Field callbacks of useSelect (`onFocus`, `onBlur`, `onFocusChange`, `onKeyDown`, `onKeyUp`). */
+export interface SelectCallbacks {
+    onFocus?: ((event: FocusEvent) => void) | undefined;
+    onBlur?: ((event: FocusEvent) => void) | undefined;
+    onFocusChange?: ((isFocused: boolean) => void) | undefined;
+    onKeyDown?: ((event: KeyboardEvent) => void) | undefined;
+    onKeyUp?: ((event: KeyboardEvent) => void) | undefined;
+}
+/**
+ * The listbox selection is the select value (useSelectState `selectedKeys: convertValue(value)`). The list's
+ * selection state is controlled (the ListBox never writes it): this writes the value's keys into its signal
+ * (a serializable state; a derived signal is not). Run from an effect while the popover content renders (the
+ * menu opened however: trigger, `isOpen`, `openSelect`; a value written outside while open) and after each
+ * listbox selection change. `keys`: pass `selectedKeys(state)` read in the effect to track the value.
+ */
+export declare function syncListSelection(state: AnySelect, listKeys: Signal<Selection>, keys?: readonly Key[]): void;
+/** useMenuTrigger `state.open(focusStrategy)` / `state.toggle(focusStrategy)`. */
+export declare function selectOpen(state: AnySelect, focusStrategy: FocusStrategy | null, toggle?: boolean): void;
+/**
+ * useTypeSelect `onKeyDownCapture` of a parts-form trigger (`<Button>`), on the Select root: a Space continuing a
+ * search is consumed before the Button's press sees it (RA: capture handler + stopPropagation on the trigger).
+ */
+export declare function selectTriggerKeyDownCapture(state: AnySelect, event: KeyboardEvent): void;
+export declare function selectTriggerKeyDown(state: AnySelect, event: KeyboardEvent & {
+    currentTarget: HTMLElement;
+}, callbacks?: SelectCallbacks): void;
+/** keyup on the trigger: Space activation is ours (no native click). */
+export declare function selectTriggerKeyUp(state: AnySelect, event: KeyboardEvent, callbacks?: SelectCallbacks): void;
+/** pointerdown on the trigger: mouse / pen open on press start (useMenuTrigger `onPressStart`). */
+export declare function selectTriggerPointerDown(state: AnySelect, event: PointerEvent & {
+    currentTarget: HTMLElement;
+}): void;
+/**
+ * useMenuTrigger `onPressStart` (RAC parts: the `<Button>` of a Select gets it through `ButtonContext`): mouse / pen
+ * open on press start (focus the trigger first so FocusScope restores it), a virtual press opens on the first item.
+ */
+export declare function selectTriggerPressStart(state: AnySelect, event: {
+    pointerType: string;
+    target: EventTarget | null;
+}): void;
+/** useMenuTrigger `onPress`: touch toggles on press up. */
+export declare function selectTriggerPress(state: AnySelect, event: {
+    pointerType: string;
+    target: EventTarget | null;
+}): void;
+/** mousedown on the trigger: preventFocusOnPress (the pointerdown handler focused it already). */
+export declare function selectTriggerMouseDown(event: MouseEvent): void;
+/** click on the trigger: touch toggles (press up), screen reader clicks open on the first item. */
+export declare function selectTriggerClick(state: AnySelect, event: MouseEvent & {
+    currentTarget: HTMLElement;
+}): void;
+/** focus on the trigger (useSelect `onFocus`). */
+export declare function selectTriggerFocus(state: AnySelect, event: FocusEvent, callbacks?: SelectCallbacks): void;
+/** blur on the trigger (useSelect `onBlur`): not while the menu is open (focus moved into it). */
+export declare function selectTriggerBlur(state: AnySelect, event: FocusEvent, callbacks?: SelectCallbacks): void;
+/** click on the label: focus the trigger and show its focus ring. */
+export declare function selectLabelClick(state: AnySelect, event: MouseEvent & {
+    currentTarget: HTMLElement;
+}): void;
+/** focusin / focusout on the Select root (useFocusRing `within`). */
+export declare function selectFocusWithin(state: AnySelect, event: FocusEvent & {
+    currentTarget: HTMLElement;
+}): void;
+/**
+ * useSelect `menuProps.onBlur` (the ListBox's `onBlur`: focus left the listbox element). Focus moving inside the
+ * popover or back to the select (closing restores focus to the trigger, FocusScope `restoreFocus`) is not the
+ * select losing focus — one focus / blur pair per focus, as upstream where the unmounted menu never blurs. Focus
+ * to nowhere (the listbox removed on close, an option removed, a click on a non-focusable part) is checked once
+ * focus settles.
+ */
+export declare function selectListBlur(state: AnySelect, event: FocusEvent, callbacks?: SelectCallbacks): void;
+/**
+ * useSelectState's listbox `onSelectionChange`: set the value, mirror it into the list selection (controlled),
+ * close when `shouldCloseOnSelect`, and commit validation against the hidden field. `root`: an element of the
+ * select (its document holds the hidden field); without it only the state commits.
+ */
+export declare function selectListChange(state: AnySelect, listKeys: Signal<Selection>, keys: Selection, root: Element | null | undefined): void;
+/** Commit the validation (`validationState.commitValidation()`) against the hidden native field. */
+export declare function commitSelect(state: AnySelect, doc: Document): void;
+/** Write the value into the hidden field now (its bindings flush later) so native validity is current. */
+export declare function syncHiddenField(state: AnySelect, field: HTMLSelectElement | HTMLInputElement): void;
+/** change / input on the hidden <select> (browser autofill): set the value; `change` commits validation. */
+export declare function hiddenSelectChange(state: AnySelect, event: Event & {
+    currentTarget: HTMLSelectElement;
+}): void;
+/** invalid on the hidden field (submit / checkValidity): commit, focus the trigger, no browser bubble. */
+export declare function hiddenSelectInvalid(state: AnySelect, event: Event & {
+    currentTarget: HTMLElement;
+}): void;
+/** useFormReset: a form reset restores the default value. */
+export declare function hiddenSelectReset(state: AnySelect, field: HTMLSelectElement | HTMLInputElement): void;
+/** Removes `keys` from the value (single: clears it when the key matches); `onChange`, commits validation. */
+export declare function removeSelected(state: AnySelect, keys: Key | Iterable<Key>, event?: Event): void;
+/** Clears the value (single: `null`, multiple: `[]`); `onChange`, commits validation. */
+export declare function clearSelection(state: AnySelect, event?: Event): void;
+/** Toggles `key` (single: selects it, or clears when it is the value); `onChange`, commits validation. */
+export declare function toggleSelected(state: AnySelect, key: Key, event?: Event): void;
+/** Whether `key` is part of the value (binding accessor: hidden options, `selected`). */
+export declare const isValueKey: (state: AnySelect, key: Key) => boolean;
+export {};