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

package/tag-group/behaviour.d.ts

@@ -0,0 +1,59 @@
+import type { Direction, Key } from "../collections/types.js";
+import { ListKeyboardDelegate } from "../selection/list-keyboard-delegate.js";
+import { type AriaGridListItemOptions, type AriaGridListOptions, type GridListItemAria, type GridListStateLike } from "../grid-list/behaviour.js";
+export interface AriaTagGroupOptions extends AriaGridListOptions {
+    /** Handler that is called when a user deletes a tag. */
+    onRemove?: ((keys: Set<Key>) => void) | undefined;
+}
+/** The gridList options useTagGroup forces (react-aria `useGridList({...props, shouldFocusWrap, linkBehavior, keyboardNavigationBehavior})`). */
+export declare function tagGroupOptions<O extends AriaGridListOptions>(props: O): O;
+/** react-aria useTagGroup's default keyboard delegate: horizontal list navigation (RTL aware). */
+export declare function tagGroupKeyboardDelegate(state: GridListStateLike<any>, el: HTMLElement, direction: Direction): ListKeyboardDelegate<unknown>;
+/**
+ * Attributes of the tag grid element (react-aria `useTagGroup` gridProps): the gridList attributes plus
+ * role `grid` (`group` while empty), `aria-atomic`, `aria-relevant`, `aria-live` (polite while focus is
+ * within). Reads state: bind values as accessors.
+ */
+export declare function tagGroupProps(props: AriaTagGroupOptions, state: GridListStateLike<any>, isFocusWithin: boolean): Record<string, unknown>;
+export interface AriaTagOptions extends AriaGridListItemOptions {
+    /** Handler that is called when a user deletes a tag (the TagGroup's `onRemove`). */
+    onRemove?: ((keys: Set<Key>) => void) | undefined;
+    /** Id of the remove button (react-aria `useId()` in useTag). */
+    removeButtonId: string;
+    "aria-label"?: string | undefined;
+    "aria-errormessage"?: string | undefined;
+}
+export interface TagAria extends Omit<GridListItemAria, "descriptionProps"> {
+    /** Props for the tag remove button (a Button's props). */
+    removeButtonProps: {
+        "aria-label": string;
+        "aria-labelledby": string;
+        isDisabled: boolean;
+        id: string;
+    };
+    /** Whether the tag can be removed. */
+    allowsRemoving: boolean;
+}
+/**
+ * Provides the behavior and accessibility implementation for a tag (react-aria `useTag`): row
+ * attributes (gridList item + roving tabIndex: every enabled tag is tabbable until one is focused),
+ * grid cell attributes, the remove button's props. Reads state: bind values as accessors. Wire the
+ * `gridListItem<Event>` handlers on the row, with `tagKeyDown` for keydown and `tagFocus` / `tagBlur`.
+ */
+export declare function tagProps(props: AriaTagOptions, state: GridListStateLike<any>): TagAria;
+/** keydown on the tag row: gridList item keys, then Delete / Backspace remove (repeats allowed). */
+export declare function tagKeyDown(e: KeyboardEvent & {
+    currentTarget: EventTarget | null;
+}, props: AriaTagOptions, state: GridListStateLike<any>): void;
+/** The remove button's press (react-aria useTag `removeButtonProps.onPress`). */
+export declare function tagRemove(props: Pick<AriaTagOptions, "onRemove" | "node">): void;
+/** The tag's own focus events (react-aria useFocusable on the row: target is the row). */
+export interface TagFocusEvents {
+    onFocus?: ((e: FocusEvent) => void) | undefined;
+    onBlur?: ((e: FocusEvent) => void) | undefined;
+    onFocusChange?: ((isFocused: boolean) => void) | undefined;
+}
+/** focus on the tag row: item focus events + the remove description (keyboard / virtual modality). */
+export declare function tagFocus(e: FocusEvent, props: Pick<AriaTagOptions, "onRemove" | "locale"> & TagFocusEvents): void;
+/** blur on the tag row. */
+export declare function tagBlur(e: FocusEvent, props: TagFocusEvents): void;

package/tag-group/behaviour.js

@@ -0,0 +1,112 @@
+import { ListKeyboardDelegate } from "../selection/list-keyboard-delegate.js";
+import { hasFocusedKey, isFocusedKey } from "../selection/keyed.js";
+import { keyboardKeyDown } from "../interactions/keyboard.jsx";
+import { getInteractionModality } from "../interactions/focus-visible.jsx";
+import { useDescription } from "../utils/index.js";
+import { formatMessage } from "../_adapters/intl.js";
+import { gridListItemKeyDown, gridListItemProps, gridListProps, } from "../grid-list/behaviour.js";
+import { strings as intlMessages } from "./intl.js";
+/** The gridList options useTagGroup forces (react-aria `useGridList({...props, shouldFocusWrap, linkBehavior, keyboardNavigationBehavior})`). */
+export function tagGroupOptions(props) {
+    return { ...props, shouldFocusWrap: true, linkBehavior: "override", keyboardNavigationBehavior: "tab" };
+}
+/** react-aria useTagGroup's default keyboard delegate: horizontal list navigation (RTL aware). */
+export function tagGroupKeyboardDelegate(state, el, direction) {
+    return new ListKeyboardDelegate({
+        collection: state.collection,
+        ref: el,
+        orientation: "horizontal",
+        direction,
+        disabledKeys: state.disabledKeys,
+        disabledBehavior: state.selectionManager.disabledBehavior,
+    });
+}
+/**
+ * Attributes of the tag grid element (react-aria `useTagGroup` gridProps): the gridList attributes plus
+ * role `grid` (`group` while empty), `aria-atomic`, `aria-relevant`, `aria-live` (polite while focus is
+ * within). Reads state: bind values as accessors.
+ */
+export function tagGroupProps(props, state, isFocusWithin) {
+    const { gridProps } = gridListProps(tagGroupOptions(props), state);
+    return {
+        ...gridProps,
+        role: state.collection.size ? "grid" : "group",
+        "aria-atomic": false,
+        "aria-relevant": "additions",
+        "aria-live": isFocusWithin ? "polite" : "off",
+    };
+}
+const tagDisabled = (props, state) => state.disabledKeys.has(props.node.key) || !!props.node.props?.isDisabled;
+/**
+ * Provides the behavior and accessibility implementation for a tag (react-aria `useTag`): row
+ * attributes (gridList item + roving tabIndex: every enabled tag is tabbable until one is focused),
+ * grid cell attributes, the remove button's props. Reads state: bind values as accessors. Wire the
+ * `gridListItem<Event>` handlers on the row, with `tagKeyDown` for keydown and `tagFocus` / `tagBlur`.
+ */
+export function tagProps(props, state) {
+    const { rowProps, gridCellProps, descriptionProps: _, ...states } = gridListItemProps(props, state);
+    const isDisabled = tagDisabled(props, state);
+    // Rivet: keyed reads (`selection/keyed.ts`): a focus move re-runs the two tags involved, not every tag.
+    const manager = state.selectionManager;
+    const keyed = manager.selectionState;
+    const isItemFocused = keyed ? isFocusedKey(keyed, props.node.key) : props.node.key === manager.focusedKey;
+    const isFocused = keyed ? hasFocusedKey(keyed) : manager.focusedKey != null;
+    return {
+        removeButtonProps: {
+            "aria-label": formatMessage(intlMessages, props.locale, "removeButtonLabel"),
+            "aria-labelledby": `${props.removeButtonId} ${rowProps.id}`,
+            isDisabled,
+            id: props.removeButtonId,
+        },
+        rowProps: { ...rowProps, tabIndex: !isDisabled && (isItemFocused || !isFocused) ? 0 : -1 },
+        gridCellProps: { ...gridCellProps, "aria-errormessage": props["aria-errormessage"], "aria-label": props["aria-label"] },
+        ...states,
+        allowsRemoving: !!props.onRemove,
+    };
+}
+/** react-aria useTag's Delete / Backspace shortcut: the selection when this tag is selected, else this tag. */
+function removeKeys(props, state) {
+    const manager = state.selectionManager;
+    const key = props.node.key;
+    return manager.isSelected(key) ? new Set(manager.selectedKeys) : new Set([key]);
+}
+/** keydown on the tag row: gridList item keys, then Delete / Backspace remove (repeats allowed). */
+export function tagKeyDown(e, props, state) {
+    gridListItemKeyDown(e, props, state);
+    const onRemove = props.onRemove;
+    if (!onRemove || tagDisabled(props, state))
+        return;
+    keyboardKeyDown({
+        shortcuts: { Delete: () => onRemove(removeKeys(props, state)), Backspace: () => onRemove(removeKeys(props, state)) },
+        allowRepeats: true,
+    }, e);
+}
+/** The remove button's press (react-aria useTag `removeButtonProps.onPress`). */
+export function tagRemove(props) {
+    props.onRemove?.(new Set([props.node.key]));
+}
+const cleanups = new WeakMap();
+/** focus on the tag row: item focus events + the remove description (keyboard / virtual modality). */
+export function tagFocus(e, props) {
+    const row = e.currentTarget;
+    if (e.target !== row)
+        return;
+    props.onFocus?.(e);
+    props.onFocusChange?.(true);
+    let modality = getInteractionModality();
+    if (modality === "virtual" && typeof window !== "undefined" && "ontouchstart" in window)
+        modality = "pointer";
+    const description = props.onRemove && (modality === "keyboard" || modality === "virtual") ? formatMessage(intlMessages, props.locale, "removeDescription") : "";
+    cleanups.get(row)?.();
+    cleanups.set(row, useDescription(row, description));
+}
+/** blur on the tag row. */
+export function tagBlur(e, props) {
+    const row = e.currentTarget;
+    if (e.target !== row)
+        return;
+    cleanups.get(row)?.();
+    cleanups.delete(row);
+    props.onBlur?.(e);
+    props.onFocusChange?.(false);
+}

package/tag-group/index.d.ts

@@ -0,0 +1,138 @@
+import { type Signal } from "@rivetjs/reactivity";
+import { type CollectionProps } from "../collections/components.jsx";
+import { type ListState } from "../collections/list-state.js";
+import type { DisabledBehavior, Key, Node, Selection, SelectionBehavior, SelectionMode } from "../collections/types.js";
+import { type DOMRenderProps } from "../utils/render.js";
+import { type GlobalDOMAttributes } from "../utils/dom-props.js";
+import { type LinkDOMProps } from "../utils/links.jsx";
+import type { HoverEvents } from "../utils/types.js";
+import type { PressEvents } from "../interactions/press.jsx";
+import { type ContextValue, type RefValue, type RenderProps, type SlotProps, type StyleRenderProps } from "../slots/index.jsx";
+import { type GridListShared } from "../grid-list/behaviour.js";
+export type { Key, Selection, SelectionMode, SelectionBehavior } from "../collections/types.js";
+export type { ListState } from "../collections/list-state.js";
+export interface TagGroupProps extends SlotProps, DOMRenderProps<"div", undefined>, Omit<GlobalDOMAttributes<HTMLDivElement>, "style"> {
+    /** The element's unique identifier. */
+    id?: string;
+    "aria-label"?: string;
+    "aria-labelledby"?: string;
+    "aria-describedby"?: string;
+    "aria-details"?: string;
+    /** The type of selection that is allowed in the collection. */
+    selectionMode?: SelectionMode;
+    /** How multiple selection should behave in the collection. Default "toggle". */
+    selectionBehavior?: SelectionBehavior;
+    /** The currently selected keys: a signal (two-way) or a value (controlled). */
+    selectedKeys?: Signal<Selection> | "all" | Iterable<Key>;
+    /** The initial selected keys in the collection (uncontrolled). */
+    defaultSelectedKeys?: "all" | Iterable<Key>;
+    /** Handler that is called when the selection changes. */
+    onSelectionChange?: (keys: Selection) => void;
+    /** The item keys that are disabled. These items cannot be selected, focused, or otherwise interacted with. */
+    disabledKeys?: Iterable<Key>;
+    /** Whether `disabledKeys` applies to all interactions, or only selection. Default "all". */
+    disabledBehavior?: DisabledBehavior;
+    /** Whether the collection allows empty selection. */
+    disallowEmptySelection?: boolean;
+    /** Whether `onSelectionChange` fires even if the new set of keys is the same as the last. */
+    allowDuplicateSelectionEvents?: boolean;
+    /** Whether selection should occur on press up instead of press down. */
+    shouldSelectOnPressUp?: boolean;
+    /** Handler that is called when a user deletes a tag. */
+    onRemove?: (keys: Set<Key>) => void;
+    /** Handler that is called when a user performs an action on an item. */
+    onAction?: (key: Key) => void;
+    /** Whether pressing the escape key should clear selection in the TagGroup or not. Default "clearSelection". */
+    escapeKeyBehavior?: "clearSelection" | "none";
+    /** The CSS class of the element. @default "rv-TagGroup" */
+    class?: string;
+    style?: StyleRenderProps<never>["style"];
+    /** The label, TagList, description / error message Text parts. */
+    children?: unknown;
+    ref?: RefValue<HTMLDivElement>;
+}
+/** RAC `TagGroupContext`. */
+export declare const TagGroupContext: import("@rivetjs/reactivity").Context<ContextValue<TagGroupProps, HTMLDivElement>>;
+/** What a TagGroup provides its TagList / Tags (Rivet: RAC `ListStateContext` + `TagListContext` gridProps + `hookData`). */
+export interface TagGroupInternal {
+    state: ListState;
+    shared: GridListShared;
+    locale: string;
+    direction: "ltr" | "rtl";
+    /** The grid's labelling (react-aria useField / useLabel), read at render time. */
+    labelledBy: () => string | undefined;
+    describedBy: () => string | undefined;
+    ariaLabel: string | undefined;
+    ariaDetails: string | undefined;
+    escapeKeyBehavior: "clearSelection" | "none" | undefined;
+    onRemove: ((keys: Set<Key>) => void) | undefined;
+    /** Autocomplete filter (SelectableCollectionContext): tags it returns false for do not render. */
+    filter?: ((textValue: string, node: Node<any>) => boolean) | undefined;
+}
+/** The TagGroup a TagList / Tag renders in (null outside one). */
+export declare const TagGroupInternalContext: import("@rivetjs/reactivity").Context<TagGroupInternal | null>;
+/** A tag group is a focusable list of labels, categories, keywords, filters, or other items, with support for keyboard navigation, selection, and removal (RAC `TagGroup`). */
+export declare function TagGroup(inProps: TagGroupProps): import("@rivetjs/runtime/jsx-runtime").CompiledElement;
+/** RAC `TagListRenderProps` (accessors: call them inside bindings). */
+export interface TagListRenderProps {
+    /** Whether the tag list has no items and should display its empty state. @selector [data-empty] */
+    isEmpty: () => boolean;
+    /** Whether the tag list is currently focused. @selector [data-focused] */
+    isFocused: () => boolean;
+    /** Whether the tag list is currently keyboard focused. @selector [data-focus-visible] */
+    isFocusVisible: () => boolean;
+    /** State of the TagGroup. */
+    state: ListState;
+}
+export interface TagListProps<T = object> extends Omit<CollectionProps<T>, "disabledKeys">, StyleRenderProps<TagListRenderProps>, DOMRenderProps<"div", TagListRenderProps>, Omit<GlobalDOMAttributes<HTMLDivElement>, "style"> {
+    /** Provides content to display when there are no items in the tag list. */
+    renderEmptyState?: (props: TagListRenderProps) => unknown;
+    ref?: RefValue<HTMLDivElement>;
+}
+/** RAC `TagListContext` (the TagList's own props; RAC also passes useTagGroup's gridProps through it). */
+export declare const TagListContext: import("@rivetjs/reactivity").Context<ContextValue<TagListProps<any>, HTMLDivElement>>;
+/** A tag list is a container for tags within a TagGroup (RAC `TagList`). */
+export declare function TagList<T extends object>(inProps: TagListProps<T>): import("@rivetjs/runtime/jsx-runtime").CompiledElement;
+/** RAC `TagRenderProps` (accessors: call them inside bindings). */
+export interface TagRenderProps {
+    /** The unique id of the tag. */
+    id: Key;
+    /** @selector [data-hovered] */
+    isHovered: () => boolean;
+    /** @selector [data-pressed] */
+    isPressed: () => boolean;
+    /** @selector [data-selected] */
+    isSelected: () => boolean;
+    /** @selector [data-focused] */
+    isFocused: () => boolean;
+    /** @selector [data-focus-visible] */
+    isFocusVisible: () => boolean;
+    /** @selector [data-disabled] */
+    isDisabled: () => boolean;
+    /** @selector [data-selection-mode="single | multiple"] */
+    selectionMode: SelectionMode;
+    selectionBehavior: () => SelectionBehavior;
+    /** Whether the tag group allows items to be removed. @selector [data-allows-removing] */
+    allowsRemoving: boolean;
+    /** State of the TagGroup. */
+    state: ListState;
+}
+export interface TagProps extends RenderProps<TagRenderProps>, DOMRenderProps<"div", TagRenderProps>, LinkDOMProps, HoverEvents, PressEvents, Omit<GlobalDOMAttributes<HTMLDivElement>, "onClick" | "style"> {
+    /** A unique id for the tag. */
+    id?: Key;
+    /** A string representation of the tags's contents, used for accessibility. Required if children is not a plain text string. */
+    textValue?: string;
+    /** Whether the tag is disabled. */
+    isDisabled?: boolean;
+    /** Handler that is called when a user performs an action on the item. */
+    onAction?: () => void;
+    /** Handler that is called when the tag receives focus. */
+    onFocus?: (e: FocusEvent) => void;
+    /** Handler that is called when the tag loses focus. */
+    onBlur?: (e: FocusEvent) => void;
+    /** Handler that is called when the tag's focus status changes. */
+    onFocusChange?: (isFocused: boolean) => void;
+    ref?: RefValue<HTMLDivElement>;
+}
+/** A Tag is an individual item within a TagList (RAC `Tag`). */
+export declare const Tag: (props: TagProps) => unknown;