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

package/switch/index.jsx

@@ -0,0 +1,186 @@
+// Ported from react-aria-components `Switch` (packages/react-aria-components/src/Switch.tsx), Apache-2.0, © Adobe.
+// Switch, SwitchField and SwitchButton.
+// Rivet:
+// - render props are accessors (`{({ isSelected }) => …}`); `class` / `style` may be functions of them.
+// - `isSelected`: a plain value (controlled), a two-way Signal or an accessor; `isDisabled` may be an accessor.
+// - the native input sits in an inline-styled visually hidden span (RA `VisuallyHidden`).
+// - `ToggleStateContext` / `InternalSwitchContext` are resumable (`rv-toggle-state`, `rv-switch-internal`).
+// `render` (RAC DOMRenderProps): given, the attributes go to `render(attrs, <part>RenderProps)` instead of the default element (SwitchField `<div>`, SwitchButton / Switch `<label>` with the hidden input inside `children`). Deviations: `inputRef` is a Rivet `ref()` (or callback).
+import { liveAssign, liveOmit, liveOptions, liveWithoutData } from "../utils/live.jsx";
+import { createContext, untrack, useContext } from "@rivetjs/reactivity";
+import { read } from "../state/form-validation.js";
+import { createToggleState } from "../state/toggle.js";
+import { formValidationBehavior, formValidationErrors } from "../form/index.jsx";
+import { FieldErrorContext } from "../form/field-error.jsx";
+import { TextContext } from "../text/index.jsx";
+import { visuallyHidden } from "../a11y/index.js";
+import { useFocusRing } from "../focus/focus-ring.jsx";
+import { hoverProps } from "../interactions/hover.jsx";
+import { mergeInto, mergeProps } from "../interactions/merge-props.jsx";
+import {} from "../utils/render.js";
+import { globalDOMProps } from "../utils/dom-props.js";
+import { Provider, resumableContext, contextProps, renderProps, renderPropsOf, } from "../slots/index.jsx";
+import { mergeInputRefs } from "../checkbox/behaviour.jsx";
+import { switchProps } from "./behaviour.jsx";
+import { probeSlots, slotProbing } from "#server";
+/** RAC `SwitchContext`. */
+export const SwitchContext = resumableContext(createContext(null, { id: "rv-switch" }));
+/** RAC `SwitchFieldContext`. */
+export const SwitchFieldContext = resumableContext(createContext(null, { id: "rv-switch-field" }));
+/** RAC `ToggleStateContext`. */
+export const ToggleStateContext = resumableContext(createContext(null, { id: "rv-toggle-state" }));
+const InternalSwitchContext = resumableContext(createContext(null, { id: "rv-switch-internal" }));
+const DOM_OWNED = ["style", "onClick", "render"];
+/** State keys made accessors at the part boundary when live (live props P5; `isSelected` = controlled). */
+const LIVE_KEYS = [
+    "isDisabled",
+    "isReadOnly",
+    "isRequired",
+    "isInvalid",
+    "aria-label",
+    "aria-labelledby",
+    "aria-describedby",
+    "aria-details",
+    "aria-errormessage",
+    "aria-controls",
+];
+/**
+ * A switch allows a user to turn a setting on or off.
+ */
+export function Switch(props) {
+    const userInputRef = props.inputRef;
+    const otherProps = liveOmit(props, ["inputRef"]);
+    const [ctxMerged, ref] = contextProps(otherProps, props.ref, SwitchContext);
+    // Live props (P5): live state keys become accessors at the boundary (toggle state / attribute bags read them).
+    const merged = liveOptions(ctxMerged, LIVE_KEYS, ["isSelected"]);
+    const inputRef = mergeInputRefs(userInputRef, untrack(() => merged.inputRef));
+    const state = untrack(() => createToggleState(merged));
+    const aria = untrack(() => switchProps(liveAssign(liveWithoutData(merged), {
+        // Function children count as a label.
+        children: untrack(() => (typeof merged.children === "function" ? true : merged.children)),
+    }), state, inputRef));
+    const values = [
+        [ToggleStateContext, state],
+        [InternalSwitchContext, { ...aria, defaultClassName: "rv-Switch" }],
+    ];
+    const button = liveAssign(merged, { ref });
+    return (<Provider values={values}>
+      {
+        // Live props (P5): a direct call, not `<SwitchButton {...button} />` — on a resumed page a component spread of a
+        // live (forwarding) props object re-created this region when the button read a forwarded key (class) in a binding.
+        untrack(() => SwitchButton(button))}
+    </Provider>);
+}
+/**
+ * A switch allows a user to turn a setting on or off, with support for validation and help text.
+ */
+export function SwitchField(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 userInputRef = props.inputRef;
+    const otherProps = liveOmit(props, ["inputRef"]);
+    const [ctxMerged, ref] = contextProps(otherProps, props.ref, SwitchFieldContext);
+    const merged = liveOptions(ctxMerged, LIVE_KEYS, ["isSelected"]);
+    const validationBehavior = formValidationBehavior(merged.validationBehavior);
+    const inputRef = mergeInputRefs(userInputRef, untrack(() => merged.inputRef));
+    const state = untrack(() => createToggleState(merged));
+    const aria = untrack(() => switchProps(liveAssign(liveWithoutData(merged), {
+        children: untrack(() => (typeof merged.children === "function" ? true : merged.children)),
+        validationBehavior,
+        validationErrors: formValidationErrors(),
+    }), state, inputRef));
+    const { descriptionProps, errorMessageProps, isSelected, isDisabled, isReadOnly, isInvalid, validationDetails, validationErrors } = aria;
+    const requiredProp = untrack(() => merged.isRequired);
+    const isRequired = () => !!read(requiredProp);
+    const fieldValues = { isSelected, isDisabled, isReadOnly, isInvalid, isRequired, state };
+    const rp = renderPropsOf(merged, {
+        defaultClassName: "rv-SwitchField",
+        values: fieldValues,
+    });
+    const dom = globalDOMProps(merged, DOM_OWNED);
+    const slot = merged.slot || undefined;
+    // Object-literal function value (R2 makes it a resumable symbol; a plain local const arrow is not, and a
+    // provider entry holding one is dropped when a resumed region is re-created).
+    const fieldError = {
+        validation: () => ({ isInvalid: isInvalid(), validationErrors: validationErrors(), validationDetails: validationDetails() }),
+    };
+    const values = [
+        [ToggleStateContext, state],
+        [InternalSwitchContext, { ...aria, defaultClassName: "rv-SwitchButton", isRequired: requiredProp }],
+        [TextContext, { slots: { description: descriptionProps, errorMessage: errorMessageProps } }],
+        [FieldErrorContext, fieldError.validation],
+    ];
+    // Rivet (server): the input renders before the Description / FieldError: probe which slotted parts render (as
+    // CheckboxField), so the input's `aria-describedby` names the description the client render links (RA useSlotId).
+    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-selected": () => isSelected() || undefined,
+            "data-disabled": () => isDisabled() || undefined,
+            "data-readonly": () => isReadOnly() || undefined,
+            "data-invalid": () => isInvalid() || undefined,
+            "data-required": () => isRequired() || undefined,
+            children: () => <Provider values={values}>{rp.children()}</Provider>,
+        }, fieldValues);
+    return (<div {...dom} ref={ref} class={rp.class()} style={rp.style()} slot={slot} data-selected={isSelected() || undefined} data-disabled={isDisabled() || undefined} data-readonly={isReadOnly() || undefined} data-invalid={isInvalid() || undefined} data-required={isRequired() || undefined}>
+      <Provider values={values}>{rp.children()}</Provider>
+    </div>);
+}
+/**
+ * A switch button is the clickable area of a switch, including the indicator and label.
+ */
+export function SwitchButton(props) {
+    const { labelProps, inputProps, isSelected, isDisabled, isReadOnly, isPressed, isInvalid, inputRef, defaultClassName, isRequired } = useContext(InternalSwitchContext);
+    const buttonRef = props.ref;
+    const { isFocused, isFocusVisible, focusProps } = useFocusRing();
+    const isInteractionDisabled = () => isDisabled() || isReadOnly();
+    const state = useContext(ToggleStateContext);
+    const { onHoverStart, onHoverEnd, onHoverChange } = props;
+    const { hoverProps: hover, isHovered } = hoverProps({ onHoverStart, onHoverEnd, onHoverChange, isDisabled: isInteractionDisabled }, props);
+    const required = () => !!read(isRequired);
+    const buttonValues = { isSelected, isPressed, isHovered, isFocused, isFocusVisible, isDisabled, isReadOnly, isInvalid, isRequired: required, state };
+    const rp = renderPropsOf(props, {
+        defaultClassName,
+        values: buttonValues,
+    });
+    // `globalDOMProps` returns a fresh bag: merged into in place (static path).
+    const dom = mergeInto(globalDOMProps(props, DOM_OWNED), labelProps, hover);
+    const input = mergeProps(inputProps, focusProps);
+    const slot = props.slot || undefined;
+    if (props.render)
+        return props.render({
+            ...dom,
+            ref: buttonRef,
+            class: () => rp.class(),
+            style: () => rp.style(),
+            slot,
+            "data-selected": () => isSelected() || undefined,
+            "data-pressed": () => isPressed() || undefined,
+            "data-hovered": () => isHovered() || undefined,
+            "data-focused": () => isFocused() || undefined,
+            "data-focus-visible": () => isFocusVisible() || undefined,
+            "data-disabled": () => isDisabled() || undefined,
+            "data-readonly": () => isReadOnly() || undefined,
+            "data-invalid": () => isInvalid() || undefined,
+            "data-required": () => required() || undefined,
+            children: () => (<>
+            <span style={visuallyHidden}>
+              <input {...input} ref={inputRef}/>
+            </span>
+            {rp.children()}
+          </>),
+        }, buttonValues);
+    return (<label {...dom} ref={buttonRef} class={rp.class()} style={rp.style()} slot={slot} data-selected={isSelected() || undefined} data-pressed={isPressed() || undefined} data-hovered={isHovered() || undefined} data-focused={isFocused() || undefined} data-focus-visible={isFocusVisible() || undefined} data-disabled={isDisabled() || undefined} data-readonly={isReadOnly() || undefined} data-invalid={isInvalid() || undefined} data-required={required() || undefined}>
+      <span style={visuallyHidden}>
+        <input {...input} ref={inputRef}/>
+      </span>
+      {rp.children()}
+    </label>);
+}

package/table/behaviour.d.ts

@@ -0,0 +1,181 @@
+import type { Key, KeyboardDelegate, LayoutDelegate } from "../collections/types.js";
+import type { GridNode } from "../collections/grid.js";
+import type { TableState } from "../state/table.js";
+import { gridKeyboardDelegate, gridRowGroupProps, type GridAria, type GridCellProps, type GridProps, type GridRowAria, type GridRowGroupAria, type GridRowProps, type GridSelectionCheckboxProps, type GridShared } from "../grid/behaviour.js";
+import { type Router } from "../utils/links.jsx";
+export { gridRowGroupProps as tableRowGroupProps };
+export type { GridRowGroupAria as TableRowGroupAria };
+/** A react-stately `TableState` view as the table hooks read it (grid shared data + grid id ride on it). */
+export type TableStateLike<T = unknown> = TableState<T> & {
+    /** `../grid/behaviour.ts` `gridShared(props)` (react-aria `gridMap`). */
+    grid?: GridShared | undefined;
+    /** The table's id (react-aria `gridIds`). */
+    gridId?: string | undefined;
+};
+/** react-aria `gridIds`: the table id per (long-lived) state object (fallback of `state.gridId`). */
+export declare const gridIds: WeakMap<object, string>;
+/** Strips whitespace from string keys (ids must not contain spaces). */
+export declare function normalizeKey(key: Key): string;
+/** The id of a column header (`<grid id>-<column key>`). */
+export declare function getColumnHeaderId(state: TableStateLike<any>, columnKey: Key): string;
+/** The id of a cell (`<grid id>-<row key>-<column key>`). */
+export declare function getCellId(state: TableStateLike<any>, rowKey: Key, columnKey: Key): string;
+/** A row is labelled by its row header cells. */
+export declare function getRowLabelledBy(state: TableStateLike<any>, rowKey: Key): string;
+export interface AriaTableProps extends GridProps {
+    /** The layout object for the table (keyboard delegate page navigation). */
+    layoutDelegate?: LayoutDelegate | undefined;
+    /** Rivet: id of the hidden sort description element (react-aria `useDescription`). */
+    sortDescriptionId?: string | undefined;
+}
+/**
+ * The keyboard delegate `useTable` builds (react-aria memoizes it; Rivet builds it per event):
+ * `props.keyboardDelegate`, else a `TableKeyboardDelegate` over the table element's DOM layout.
+ */
+export declare function tableKeyboardDelegate<T>(props: AriaTableProps, state: TableStateLike<T>, element: HTMLElement | null): KeyboardDelegate;
+/** The sort description of the table (`"sorted by column X in ascending order"`), or undefined. */
+export declare function tableSortDescription(props: {
+    locale?: string | undefined;
+}, state: TableStateLike<any>): string | undefined;
+/**
+ * Provides the behavior and accessibility implementation for a table component (react-aria
+ * `useTable` → `tableProps`): `gridProps` of `../grid/behaviour.ts` + treegrid role, virtualized row
+ * count including header rows, the sort description. Reads state: bind as accessors. Wire the grid
+ * handlers (`gridKeyDown` …) with `keyboardDelegate: tableKeyboardDelegate(…)` — `table<Event>` below.
+ */
+export declare function tableProps<T>(props: AriaTableProps, state: TableStateLike<T>, hasTabbableChild?: boolean): GridAria;
+/** The grid handler props of `tableProps`: `props` with the table keyboard delegate for the element. */
+export declare function tableGridProps<T>(props: AriaTableProps, state: TableStateLike<T>, element: HTMLElement | null): GridProps;
+export interface AriaTableColumnHeaderProps<T> {
+    /** An object representing the column header. */
+    node: GridNode<T>;
+    /** Whether the column header is contained in a virtual scroller. */
+    isVirtualized?: boolean | undefined;
+    /** Whether the column header or its first focusable child is focused. Default "child". */
+    focusMode?: "child" | "cell" | undefined;
+    /** Whether the column header supports arrow key navigation with tab keyboard navigation. */
+    allowsArrowNavigation?: boolean | undefined;
+    /** Rivet: id of the hidden "sortable column" description element (react-aria `useDescription`). */
+    descriptionId?: string | undefined;
+    /** Rivet: locale of the strings. */
+    locale?: string | undefined;
+}
+export interface TableColumnHeaderAria {
+    /** Props for the column header element. */
+    columnHeaderProps: Record<string, unknown>;
+    /** Whether the column is currently in a pressed state. */
+    isPressed: boolean;
+}
+/** The "sortable column" description of a column header (Android adds the sort order), or undefined. */
+export declare function tableColumnSortableDescription<T>(props: AriaTableColumnHeaderProps<T>, state: TableStateLike<T>): string | undefined;
+/** Whether the column header press sorts (react-aria `usePress({ isDisabled })`). */
+export declare function tableColumnHeaderPressable<T>(props: AriaTableColumnHeaderProps<T>, state: TableStateLike<T>): boolean;
+/**
+ * Provides the behavior and accessibility implementation for a column header in a table (react-aria
+ * `useTableColumnHeader` → `tableColumnHeaderProps`). Reads state: bind as accessors. Wire the
+ * `gridCell<Event>` handlers (focusMode "child") and a press (`../interactions/press.tsx`) calling
+ * `tableColumnHeaderPress` when `tableColumnHeaderPressable`.
+ */
+export declare function tableColumnHeaderProps<T>(props: AriaTableColumnHeaderProps<T>, state: TableStateLike<T>): TableColumnHeaderAria;
+/**
+ * The column header press: `state.sort(column)`, then the sort announcement (react-aria announces
+ * the changed sort description, assertive, 500 ms).
+ */
+export declare function tableColumnHeaderPress<T>(props: AriaTableColumnHeaderProps<T>, state: TableStateLike<T>, sort: (key: Key) => void, read: () => TableStateLike<T>): void;
+/**
+ * react-aria's effect: an empty table drops a focused column header key. Call at the end of
+ * handlers that may empty the collection (and on render: no-op unless focused).
+ */
+export declare function tableColumnHeaderResetFocus<T>(props: AriaTableColumnHeaderProps<T>, state: TableStateLike<T>): void;
+/** RAC Button props of the treegrid expand button (`Button slot="chevron"`; `onPress` → `tableRowExpandPress`). */
+export interface TableExpandButtonProps {
+    isDisabled?: boolean | undefined;
+    excludeFromTabOrder?: boolean | undefined;
+    preventFocusOnPress?: boolean | undefined;
+    "data-react-aria-prevent-focus"?: boolean | undefined;
+    "aria-label"?: string | undefined;
+    "aria-labelledby"?: string | undefined;
+    id?: string | undefined;
+}
+export interface TableRowAria extends Omit<GridRowAria, "rowProps"> {
+    /** Props for the table row element. */
+    rowProps: Record<string, unknown>;
+    /** Props for the treegrid expand button (empty unless the table has a tree column). */
+    expandButtonProps: TableExpandButtonProps;
+}
+export interface TableRowProps<T> extends GridRowProps<T> {
+    /** Rivet: id of the expand button (react-aria `useLabels` generates one when labelled by others). */
+    expandButtonId?: string | undefined;
+    /** Rivet: the router of the synthetic link attributes (react-aria `useSyntheticLinkProps` reads it from context). */
+    router?: Router | undefined;
+}
+/**
+ * Provides the behavior and accessibility implementation for a row in a table (react-aria
+ * `useTableRow` → `tableRowProps`): `gridRowProps` + virtualized aria-rowindex, treegrid
+ * expansion attributes, synthetic link attributes, aria-labelledby (row header cells), the expand
+ * button props. Reads state: bind as accessors. Wire the `gridRow<Event>` handlers and
+ * `tableRowKeyDown` (treegrid expansion keys) on the row.
+ */
+export declare function tableRowProps<T>(props: TableRowProps<T>, state: TableStateLike<T>, locale?: string): TableRowAria;
+/** keydown on a treegrid row: expand / collapse (RTL aware), collapse on a leaf moves to the parent. */
+export declare function tableRowKeyDown<T>(e: KeyboardEvent, props: TableRowProps<T>, state: TableStateLike<T>): void;
+/** The expand button's `onPress` (react-aria `expandButtonProps.onPress`). */
+export declare function tableRowExpandPress<T>(props: TableRowProps<T>, state: TableStateLike<T>): void;
+export interface TableHeaderRowAria {
+    /** Props for the grid row element. */
+    rowProps: Record<string, unknown>;
+}
+/** Provides the behavior and accessibility implementation for a header row in a table (react-aria `useTableHeaderRow`). */
+export declare function tableHeaderRowProps<T>(props: {
+    node: GridNode<T>;
+    isVirtualized?: boolean | undefined;
+}, state: TableStateLike<T>): TableHeaderRowAria;
+export interface AriaTableCellProps extends GridCellProps {
+}
+export interface TableCellAria {
+    /** Props for the table cell element. */
+    gridCellProps: Record<string, unknown>;
+    /** Whether the cell is currently in a pressed state. */
+    isPressed: boolean;
+}
+/**
+ * Provides the behavior and accessibility implementation for a cell in a table (react-aria
+ * `useTableCell` → `tableCellProps`): `gridCellProps`, row header cells get role rowheader + the id
+ * rows are labelled by. Reads state. Wire the `gridCell<Event>` handlers.
+ */
+export declare function tableCellProps<T>(props: AriaTableCellProps, state: TableStateLike<T>): TableCellAria;
+export interface AriaTableSelectionCheckboxProps {
+    /** A unique key for the checkbox. */
+    key: Key;
+    /** Rivet: checkbox id (react-aria generates one). */
+    id?: string | undefined;
+    /** Rivet: locale of the strings. */
+    locale?: string | undefined;
+}
+export interface TableSelectionCheckboxAria {
+    /** Props for the row selection checkbox element (`onChange` → `tableSelectionCheckboxChange`). */
+    checkboxProps: GridSelectionCheckboxProps & {
+        "aria-labelledby": string;
+    };
+}
+/** Provides the behavior and accessibility implementation for a row selection checkbox in a table (react-aria `useTableSelectionCheckbox`). */
+export declare function tableSelectionCheckboxProps<T>(props: AriaTableSelectionCheckboxProps, state: TableStateLike<T>): TableSelectionCheckboxAria;
+/** The row selection checkbox's `onChange`: toggles the row's selection. */
+export declare function tableSelectionCheckboxChange<T>(_isSelected: boolean, props: {
+    key: Key;
+}, state: TableStateLike<T>): void;
+export interface TableSelectAllCheckboxAria {
+    /** Props for the select all checkbox element (`onChange` → `tableSelectAllCheckboxChange`). */
+    checkboxProps: {
+        "aria-label": string;
+        isSelected: boolean;
+        isDisabled: boolean;
+        isIndeterminate: boolean;
+    };
+}
+/** Provides the behavior and accessibility implementation for the select all checkbox in a table (react-aria `useTableSelectAllCheckbox`). */
+export declare function tableSelectAllCheckboxProps<T>(state: TableStateLike<T>, locale?: string): TableSelectAllCheckboxAria;
+/** The select all checkbox's `onChange`. */
+export declare function tableSelectAllCheckboxChange<T>(state: TableStateLike<T>): void;
+export type { GridRowGroupAria };
+export { gridKeyboardDelegate };