@skdx/react 0.26.0

package/dist/tree-select/types.d.cts

@@ -0,0 +1,360 @@
+import type * as React from 'react';
+import type { TreeCheckedState } from '../tree/types.cjs';
+import type { PopperContentProps } from '../utils/popper.cjs';
+import type { PortalProps } from '../utils/portal.cjs';
+import type { PrimitivePropsWithRef } from '../utils/primitive.cjs';
+import type { InteractOutsideEvent } from '../utils/useDismiss.cjs';
+import type { TreeSelectFlatNode, TreeSelectIndex } from './collection.cjs';
+/**
+ * One node of a {@link TreeSelect}'s `collection`. Plain data, not elements:
+ * cascading check state, `valueStrategy` projection, and filtering all need to
+ * see branches that are collapsed (and therefore unmounted), which a
+ * children-based tree cannot offer.
+ */
+export interface TreeSelectNode {
+    /** Unique identifier across the whole collection — what lands in `value`, and what every callback names. */
+    value: string;
+    /**
+     * Human-readable text: rendered as the node's content, matched by `filter`, and shown by `TreeSelectValue`.
+     * @default undefined — falls back to `value`.
+     */
+    label?: string;
+    /**
+     * Excludes this node from checking, cascade propagation, keyboard
+     * navigation, and its parent's checked-ness calculation. Inherited by the
+     * whole subtree — a disabled branch cannot be toggled through its children.
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * Child nodes. A node with an empty (or absent) `children` is a leaf: it is
+     * not expandable and reports no `aria-expanded`.
+     * @default undefined — a leaf.
+     */
+    children?: TreeSelectNode[];
+}
+/**
+ * Whether checking a node propagates through its subtree. `'cascade'` makes
+ * the tree a tri-state checkbox tree: checking a parent checks every enabled
+ * descendant, and a partially-checked parent reports `aria-checked="mixed"`.
+ * `'independent'` disables propagation entirely — each node stands alone.
+ *
+ * Only meaningful while `multiple` is set; a single-select tree has one
+ * checked node by definition and never cascades.
+ */
+export type TreeSelectCheckStrategy = 'cascade' | 'independent';
+/**
+ * Which of the checked nodes are actually emitted in `value`.
+ *
+ * - `'all'` — every checked node, parents and descendants alike.
+ * - `'leaf'` — only checked leaves; branches are dropped.
+ * - `'shallowest'` — only the topmost fully-checked node of each branch,
+ *   collapsing a fully-checked subtree to the single node that implies it.
+ *
+ * Ignored (treated as `'all'`) under `checkStrategy="independent"`, where no
+ * node implies any other and dropping one would silently lose a selection.
+ */
+export type TreeSelectValueStrategy = 'all' | 'leaf' | 'shallowest';
+/** Predicate deciding whether a node matches the current filter text. */
+export type TreeSelectFilter = (node: TreeSelectNode, inputValue: string) => boolean;
+/** @internal Shared state distributed from {@link TreeSelect} to its parts via context. Not part of the public API. */
+export interface TreeSelectContextValue {
+    collection: readonly TreeSelectNode[];
+    index: TreeSelectIndex;
+    /** Every node value in collection pre-order. */
+    order: readonly string[];
+    /** The emitted value: the checked set projected through `valueStrategy`. */
+    value: readonly string[];
+    multiple: boolean;
+    /** Whether checking actually propagates: `checkStrategy === 'cascade'` *and* `multiple`. */
+    cascade: boolean;
+    disabled: boolean;
+    readOnly: boolean;
+    /** A node's tri-state value, derived from its enabled leaf descendants under `cascade`. */
+    checkStateOf: (value: string) => TreeCheckedState;
+    /** Toggles a node (respecting `checkStrategy`), emits the projected value, and closes when `closeOnSelect`. */
+    commit: (value: string) => void;
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+    /** Effective expanded ids — the caller's expansion plus, while filtering, the ancestors of every match. */
+    expandedIds: string[];
+    expanded: ReadonlySet<string>;
+    setExpanded: (value: string, expand: boolean) => void;
+    /** Adapter turning the composed `Tree`'s whole-array expansion callback back into a single-node change. */
+    onTreeExpandedIdsChange: (ids: string[]) => void;
+    /** Values whose check state is fully `true`, handed to the composed `Tree` as its `selectedIds`. */
+    selectedIds: string[];
+    /** Whether a node survives the current filter (always `true` when not filtering). */
+    isVisible: (value: string) => boolean;
+    /** Visible, expanded nodes in navigation order. */
+    flat: readonly TreeSelectFlatNode[];
+    flatMap: ReadonlyMap<string, TreeSelectFlatNode>;
+    activeValue: string | null;
+    setActiveValue: (value: string | null) => void;
+    /** DOM id of a node's `treeitem`, for `aria-activedescendant`. */
+    itemId: (value: string) => string;
+    treeId: string;
+    contentId: string;
+    triggerRef: React.RefObject<HTMLButtonElement | null>;
+    contentRef: React.RefObject<HTMLDivElement | null>;
+    inputRef: React.RefObject<HTMLInputElement | null>;
+    /** Whether a `TreeSelectInput` is mounted — it takes DOM focus, and with it `aria-activedescendant`, off the trigger. */
+    hasInput: boolean;
+    setHasInput: (hasInput: boolean) => void;
+    inputValue: string;
+    onInputValueChange: (value: string) => void;
+    /** A node's `label`, or its `value` when it has none. */
+    getLabel: (value: string) => string;
+    /** The shared keydown handler both `TreeSelectTrigger` and `TreeSelectInput` delegate to. */
+    onNavigationKeyDown: (event: React.KeyboardEvent<HTMLElement>, options: {
+        typeahead: boolean;
+        selectOnSpace: boolean;
+    }) => void;
+}
+/** @internal Per-node state distributed from {@link TreeSelectItem} to `TreeSelectItemIndicator` via context. Not part of the public API. */
+export interface TreeSelectItemContextValue {
+    value: string;
+    checkState: TreeCheckedState;
+    disabled: boolean;
+    expanded: boolean;
+    hasChildren: boolean;
+    /** Whether this node is the virtually-focused one named by `aria-activedescendant`. */
+    active: boolean;
+}
+/** Props for the {@link TreeSelect} root. */
+export interface TreeSelectProps {
+    /**
+     * The `TreeSelectTrigger`/`TreeSelectPortal` parts, rendered as children — `TreeSelect` itself renders no DOM.
+     * @default undefined — renders nothing without children.
+     */
+    children?: React.ReactNode;
+    /**
+     * The hierarchical data the popup's tree is built from. Node `value`s must be
+     * unique across the whole collection — every callback, `value` entry and DOM
+     * id is keyed by them.
+     */
+    collection: readonly TreeSelectNode[];
+    /**
+     * Checked node values, for controlled usage — always an array, whether or not
+     * `multiple`, and always in the shape `valueStrategy` describes. Pair with
+     * `onValueChange`.
+     * @default undefined — uncontrolled, tracks its own checked set internally.
+     */
+    value?: string[];
+    /**
+     * Initially checked node values, for uncontrolled usage. Same shape as `value`.
+     * @default [] — nothing checked.
+     */
+    defaultValue?: string[];
+    /**
+     * Fires with the whole new value whenever the checked set changes, controlled
+     * or not — projected through `valueStrategy`, not the node that was toggled.
+     * @default undefined — no-op if omitted.
+     */
+    onValueChange?: (value: string[]) => void;
+    /**
+     * Allows more than one node to be checked: the tree gets
+     * `aria-multiselectable`, activating a node toggles it rather than replacing
+     * the selection, and `checkStrategy` starts to mean something.
+     * @default false
+     */
+    multiple?: boolean;
+    /**
+     * Whether checking a node propagates through its subtree — see
+     * {@link TreeSelectCheckStrategy}. Ignored unless `multiple`.
+     * @default 'cascade' — checking a parent checks its whole enabled subtree, and a partially-checked parent reports `aria-checked="mixed"`.
+     */
+    checkStrategy?: TreeSelectCheckStrategy;
+    /**
+     * Which checked nodes appear in the emitted `value` — see
+     * {@link TreeSelectValueStrategy}. Ignored under
+     * `checkStrategy="independent"`.
+     * @default 'all' — every checked node, which is the most faithful round-trip but the most verbose payload; `'shallowest'` is usually what an API wants.
+     */
+    valueStrategy?: TreeSelectValueStrategy;
+    /**
+     * Expanded node values, for controlled usage. Pair with `onExpandedChange`.
+     * While filtering, the ancestors of every match are expanded *on top of* this
+     * value without being written back to it.
+     * @default undefined — uncontrolled, tracks its own expanded set internally.
+     */
+    expandedValue?: string[];
+    /**
+     * Initially expanded node values, for uncontrolled usage.
+     * @default [] — every branch collapsed.
+     */
+    defaultExpandedValue?: string[];
+    /**
+     * Fires with the new expanded set whenever a branch is expanded or collapsed,
+     * controlled or not. Never fires for the transient expansion filtering adds.
+     * @default undefined — no-op if omitted.
+     */
+    onExpandedChange?: (expandedValue: string[]) => void;
+    /**
+     * Whether the popup is open, for controlled usage. Pair with `onOpenChange`.
+     * @default undefined — uncontrolled, tracks its own open state internally.
+     */
+    open?: boolean;
+    /**
+     * Initial open state, for uncontrolled usage.
+     * @default false
+     */
+    defaultOpen?: boolean;
+    /**
+     * Fires with the new open state whenever it changes, controlled or not.
+     * @default undefined — no-op if omitted.
+     */
+    onOpenChange?: (open: boolean) => void;
+    /**
+     * Fires with the new open state once the change has finished on screen —
+     * after `TreeSelectContent`'s enter or exit animation ends, or as soon as it
+     * has settled when the popup declares no animation. Use it for work that must
+     * not race the transition; use `onOpenChange` for work that must not wait for it.
+     * @default undefined — no-op if omitted.
+     */
+    onOpenChangeComplete?: (open: boolean) => void;
+    /**
+     * The `TreeSelectInput`'s filter text, for controlled usage. Pair with `onInputValueChange`.
+     * @default undefined — uncontrolled, tracks its own filter text internally.
+     */
+    inputValue?: string;
+    /**
+     * Initial filter text, for uncontrolled usage.
+     * @default '' — unfiltered.
+     */
+    defaultInputValue?: string;
+    /**
+     * Fires with the new filter text as the user types, controlled or not.
+     * @default undefined — no-op if omitted.
+     */
+    onInputValueChange?: (inputValue: string) => void;
+    /**
+     * Decides whether a node matches the filter text. A match keeps its whole
+     * ancestor chain visible (a matched leaf under a hidden parent would be
+     * unreachable) and its whole subtree visible.
+     * @default defaultTreeSelectFilter — case-insensitive substring match on `label ?? value`.
+     */
+    filter?: TreeSelectFilter;
+    /**
+     * Blocks the whole control: the trigger is a disabled `<button>`, the popup
+     * cannot open, and no key changes anything.
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * Lets the user open, navigate and read the tree but never change the value —
+     * unlike `disabled`, which also removes it from the tab order.
+     * @default false
+     */
+    readOnly?: boolean;
+    /**
+     * Closes the popup as soon as a node is checked, returning focus to the trigger.
+     * @default !multiple — a single-select answer is complete on the first pick; a multi-select one is not.
+     */
+    closeOnSelect?: boolean;
+    /**
+     * Formats the message announced (through the shared `LiveAnnouncer`) each
+     * time the number of filter matches changes while the popup is open —
+     * filtering is silent for screen-reader users otherwise. Return an empty
+     * string to announce nothing.
+     * @default defaultGetMatchCountLabel — e.g. `"3 matches available"`
+     */
+    getMatchCountLabel?: (count: number) => string;
+}
+/** Props for {@link TreeSelectTrigger}, the `role="combobox"` button that opens the popup. */
+export interface TreeSelectTriggerProps extends PrimitivePropsWithRef<'button'> {
+}
+/** Props for {@link TreeSelectValue}, the trigger's read-out of the current selection. */
+export interface TreeSelectValueProps extends PrimitivePropsWithRef<'span'> {
+    /**
+     * Stand-in content rendered while nothing at all is checked.
+     * @default undefined — renders nothing when empty.
+     */
+    placeholder?: React.ReactNode;
+}
+/** Props for {@link TreeSelectPortal}, which teleports the popup to `document.body` while open. */
+export interface TreeSelectPortalProps extends PortalProps {
+    /**
+     * Render (and mount `TreeSelectContent`) even while closed, instead of
+     * unmounting. Useful for animation libraries that need the outgoing content
+     * present in the DOM during an exit transition.
+     * @default false
+     */
+    forceMount?: boolean;
+}
+/**
+ * Props for {@link TreeSelectContent}, the popup panel. Extends
+ * {@link PopperContentProps} (`side`, `align`, `sideOffset`, `alignOffset`,
+ * `avoidCollisions`, `collisionPadding`) for floating-ui positioning relative
+ * to the trigger — note `TreeSelectContent` defaults `side` to `'bottom'`,
+ * `align` to `'start'`, and `sideOffset` to `4`, instead of the popper base
+ * defaults (`'bottom'` / `'center'` / `0`).
+ */
+export interface TreeSelectContentProps extends PopperContentProps {
+    /**
+     * Keep this popup mounted even while closed, instead of unmounting it.
+     * @default false
+     */
+    forceMount?: boolean;
+    /**
+     * Fires on Escape while the popup is open, before it closes. Call
+     * `event.preventDefault()` to keep it open.
+     * @default undefined — no-op if omitted.
+     */
+    onEscapeKeyDown?: (event: KeyboardEvent) => void;
+    /**
+     * Fires on a pointer-down outside the popup and trigger. `preventDefault()` keeps it open.
+     * @default undefined — no-op if omitted.
+     */
+    onPointerDownOutside?: (event: PointerEvent) => void;
+    /**
+     * Fires when focus moves outside the popup and trigger, carrying a
+     * cancelable stand-in for the uncancelable `focusin`. `preventDefault()`
+     * keeps it open.
+     * @default undefined — no-op if omitted.
+     */
+    onFocusOutside?: (event: CustomEvent<FocusEvent>) => void;
+    /**
+     * Fires for *either* kind of outside interaction, immediately before the
+     * specific handler and with the same event — so one `preventDefault()`
+     * vetoes both paths.
+     * @default undefined — no-op if omitted.
+     */
+    onInteractOutside?: (event: InteractOutsideEvent) => void;
+}
+/** Props for {@link TreeSelectTree}, the `role="tree"` inside the popup. */
+export interface TreeSelectTreeProps extends Omit<PrimitivePropsWithRef<'div'>, 'children' | 'defaultValue'> {
+    /**
+     * Renders a node's content — the label, and anything beside it such as a
+     * `TreeItemIndicator` chevron or a `TreeSelectItemIndicator` checkmark. The
+     * returned nodes render *inside* the node's `treeitem`, so both indicators
+     * find their context there.
+     * @default undefined — renders the node's `label ?? value` as plain text.
+     */
+    renderLabel?: (node: TreeSelectNode) => React.ReactNode;
+}
+/** Props for a single {@link TreeSelectItem} node. Normally rendered for you by `TreeSelectTree`. */
+export interface TreeSelectItemProps extends Omit<PrimitivePropsWithRef<'div'>, 'children'> {
+    /** The collection node this row stands for. */
+    node: TreeSelectNode;
+    /**
+     * The row's content — the label, plus any indicators.
+     * @default undefined — renders an empty row.
+     */
+    children?: React.ReactNode;
+}
+/** Props for {@link TreeSelectItemIndicator}, the checkmark shown on a checked (or partially checked) node. */
+export interface TreeSelectItemIndicatorProps extends PrimitivePropsWithRef<'span'> {
+    /**
+     * Render even while the node is unchecked, instead of returning `null` —
+     * for animating the check in and out, or for reserving its space.
+     * @default false
+     */
+    forceMount?: boolean;
+}
+/** Props for {@link TreeSelectEmpty}, shown in place of the tree when the filter matches nothing. */
+export interface TreeSelectEmptyProps extends PrimitivePropsWithRef<'div'> {
+}
+/** Props for {@link TreeSelectInput}, the optional filter text field inside the popup. */
+export interface TreeSelectInputProps extends Omit<PrimitivePropsWithRef<'input'>, 'value' | 'defaultValue'> {
+}