@skdx/react 0.28.0 → 0.29.0

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

@@ -17,35 +17,42 @@ export interface TreeSelectNode {
      * Human-readable text rendered as node content, matched by filter, shown by TreeSelectValue.
      * @default undefined — falls back to `value`.
      */
-    label?: string;
+    label?: string | undefined;
     /**
      * Excludes node from checking, cascade, navigation, and parent calculations;
      * inherited by the whole subtree.
      * @default false
      */
-    disabled?: boolean;
+    disabled?: boolean | undefined;
     /**
      * Child nodes. Empty or absent children makes this a leaf (not expandable).
      * @default undefined — a leaf.
      */
-    children?: TreeSelectNode[];
+    children?: TreeSelectNode[] | undefined;
     /**
      * Marks an unloaded branch as expandable before children arrive, giving
      * loadChildren something to run on; ignored once the node has children.
      * @default undefined — branch-ness decided by children alone.
      */
-    hasChildren?: boolean;
+    hasChildren?: boolean | undefined;
 }
-/**
- * Propagation direction when checking a node: both ways, down only, up only, or none. Meaningful only when multiple is set.
- */
+/** Propagation direction when checking a node — both ways, down only, up only, or none — meaningful only when multiple is set. */
 export type TreeSelectCheckStrategy = 'cascade' | 'descendants' | 'ancestors' | 'independent';
-/**
- * Which checked nodes appear in value: all, leaves only, or the shallowest node of each fully-checked subtree. Ignored where projection cannot be undone.
- */
+/** Which checked nodes appear in value — all, leaves only, or the shallowest node of each fully-checked subtree — ignored where projection cannot be undone. */
 export type TreeSelectValueStrategy = 'all' | 'leaf' | 'shallowest';
 /** Predicate deciding whether a node matches the current filter text. */
 export type TreeSelectFilter = (node: TreeSelectNode, inputValue: string) => boolean;
+/** How the popup draws the hierarchy — one indented tree, or one tree per open level side by side. */
+export type TreeSelectLayout = 'tree' | 'columns';
+/** @internal One showing column: the branch it belongs to plus the rows TreeSelectTree renders for it. */
+export interface TreeSelectColumnView {
+    /** The branch whose children this column lists, or `null` for the root column. */
+    parent: string | null;
+    rows: readonly {
+        value: string;
+        depth: number;
+    }[];
+}
 /** @internal Shared state distributed from TreeSelect to its parts via context. */
 export interface TreeSelectContextValue {
     collection: readonly TreeSelectNode[];
@@ -77,6 +84,14 @@ export interface TreeSelectContextValue {
     expandOnClick: boolean;
     /** Whether a node survives the current filter (always true when not filtering). */
     isVisible: (value: string) => boolean;
+    /** The layout actually drawn: `'tree'` while a filter narrows a `'columns'` popup. */
+    layout: TreeSelectLayout;
+    /** The showing columns left to right; empty unless the effective layout is `'columns'`. */
+    columns: readonly TreeSelectColumnView[];
+    /** DOM id of a column's tree; column 0 keeps `treeId` so the tree layout is unaffected. */
+    columnTreeId: (columnIndex: number) => string;
+    /** DOM id of the tree holding the active node, which `aria-controls` must name. */
+    activeTreeId: string;
     /** Visible, expanded nodes in navigation order. */
     flat: readonly TreeSelectFlatNode[];
     flatMap: ReadonlyMap<string, TreeSelectFlatNode>;
@@ -100,12 +115,7 @@ export interface TreeSelectContextValue {
         typeahead: boolean;
         selectOnSpace: boolean;
     }) => void;
-    /**
-     * Node values `TreeSelectTree` actually renders when its `rows` prop windows
-     * the collection below what `flat` considers visible; `null` when unrestricted.
-     * Keyboard navigation and the initial active node are drawn from this set so
-     * `aria-activedescendant` never names a node with no rendered treeitem.
-     */
+    /** Node values `TreeSelectTree` actually renders when `rows` windows the collection, or `null` when unrestricted; navigation draws from this set. */
     visibleRowValues: ReadonlySet<string> | null;
     /** Reported by TreeSelectTree whenever its `rows` prop changes. */
     setVisibleRowValues: (values: ReadonlySet<string> | null) => void;
@@ -120,16 +130,13 @@ export interface TreeSelectItemContextValue {
     /** Whether this node is the virtually-focused one named by aria-activedescendant. */
     active: boolean;
 }
-/**
- * Props for the TreeSelect root. Standard attributes land on the derived
- * TreeSelectTrigger. TreeSelect itself renders no DOM.
- */
+/** Props for the TreeSelect root; standard attributes land on the derived TreeSelectTrigger, since TreeSelect itself renders no DOM. */
 export interface TreeSelectProps extends PassThroughProps {
     /**
      * The TreeSelectTrigger/TreeSelectPortal parts, rendered as children.
      * @default undefined — renders nothing without children.
      */
-    children?: React.ReactNode;
+    children?: React.ReactNode | undefined;
     /**
      * Hierarchical data the tree is built from; node values must be unique across the whole collection.
      */
@@ -138,152 +145,162 @@ export interface TreeSelectProps extends PassThroughProps {
      * Controlled checked node values, always in the shape valueStrategy describes. Pair with onValueChange.
      * @default undefined — uncontrolled.
      */
-    value?: string[];
+    value?: string[] | undefined;
     /**
      * Initially checked node values for uncontrolled usage.
      * @default [] — nothing checked.
      */
-    defaultValue?: string[];
+    defaultValue?: string[] | undefined;
     /**
      * Fires with the new value whenever the checked set changes, projected through valueStrategy.
      * @default undefined — no-op if omitted.
      */
-    onValueChange?: (value: string[]) => void;
+    onValueChange?: ((value: string[]) => void) | undefined;
     /**
      * Allows more than one node to be checked; tree gets aria-multiselectable and checkStrategy becomes meaningful.
      * @default false
      */
-    multiple?: boolean;
+    multiple?: boolean | undefined;
     /**
      * Whether and in which direction checking propagates; see TreeSelectCheckStrategy. Ignored unless multiple.
      * @default 'cascade'
      */
-    checkStrategy?: TreeSelectCheckStrategy;
+    checkStrategy?: TreeSelectCheckStrategy | undefined;
     /**
      * Which checked nodes appear in the emitted value; see TreeSelectValueStrategy. Ignored where checkStrategy lacks the direction to rebuild.
      * @default 'all'
      */
-    valueStrategy?: TreeSelectValueStrategy;
+    valueStrategy?: TreeSelectValueStrategy | undefined;
     /**
      * Controlled expanded node ids, paired with onExpandedChange; while filtering, ancestors of every match are expanded on top of this value.
      * @default undefined — uncontrolled.
      */
-    expandedIds?: string[];
+    expanded?: string[] | undefined;
     /**
      * Initially expanded node values for uncontrolled usage.
      * @default [] — every branch collapsed.
      */
-    defaultExpandedIds?: string[];
+    defaultExpanded?: string[] | undefined;
     /**
      * Fires with the new expanded set whenever a branch expands or collapses, never for filter-driven expansion.
      * @default undefined — no-op if omitted.
      */
-    onExpandedChange?: (expandedIds: string[]) => void;
+    onExpandedChange?: ((expanded: string[]) => void) | undefined;
     /**
      * Whether the popup is open for controlled usage. Pair with onOpenChange.
      * @default undefined — uncontrolled, tracks its own open state internally.
      */
-    open?: boolean;
+    open?: boolean | undefined;
     /**
      * Initial open state for uncontrolled usage.
      * @default false
      */
-    defaultOpen?: boolean;
+    defaultOpen?: boolean | undefined;
     /**
      * Fires with the new open state whenever it changes, controlled or not.
      * @default undefined — no-op if omitted.
      */
-    onOpenChange?: (open: boolean) => void;
+    onOpenChange?: ((open: boolean) => void) | undefined;
     /**
      * Fires once the open state change finishes on screen, after animation ends or immediately if none.
      * @default undefined — no-op if omitted.
      */
-    onOpenChangeComplete?: (open: boolean) => void;
+    onOpenChangeComplete?: ((open: boolean) => void) | undefined;
     /**
      * The TreeSelectInput's filter text for controlled usage. Pair with onInputValueChange.
      * @default undefined — uncontrolled, tracks its own filter text internally.
      */
-    inputValue?: string;
+    inputValue?: string | undefined;
     /**
      * Initial filter text for uncontrolled usage.
      * @default '' — unfiltered.
      */
-    defaultInputValue?: string;
+    defaultInputValue?: string | undefined;
     /**
      * Fires with the new filter text as the user types, controlled or not.
      * @default undefined — no-op if omitted.
      */
-    onInputValueChange?: (inputValue: string) => void;
+    onInputValueChange?: ((inputValue: string) => void) | undefined;
     /**
      * Decides whether a node matches the filter; matches keep their ancestor chain and subtree visible.
      * @default defaultTreeSelectFilter
      */
-    filter?: TreeSelectFilter;
+    filter?: TreeSelectFilter | undefined;
     /**
      * Blocks the whole control; trigger is disabled and no key changes anything.
      * @default false
      */
-    disabled?: boolean;
+    disabled?: boolean | undefined;
     /**
      * Form field name; each selected node value submits separately under this name.
      * @default undefined — submits nothing.
      */
-    name?: string;
+    name?: string | undefined;
     /**
      * Id of the form the submitted entries belong to, for a TreeSelect not a DOM descendant of it.
      * @default undefined — entries belong to the nearest ancestor form.
      */
-    form?: string;
+    form?: string | undefined;
     /**
      * Lets the user open and navigate the tree without changing the value, unlike disabled which also removes from the tab order.
      * @default false
      */
-    readOnly?: boolean;
+    readOnly?: boolean | undefined;
     /**
      * Closes the popup as soon as a node is checked, returning focus to trigger.
      * @default !multiple
      */
-    closeOnSelect?: boolean;
+    closeOnSelect?: boolean | undefined;
     /**
      * Loads a node's children the first time it expands, for non-materialized collection. Mark branches with hasChildren; does not run while filtering.
      * @default undefined — collection is complete as given.
      */
-    loadChildren?: (nodeValue: string) => void | Promise<void>;
+    loadChildren?: ((nodeValue: string) => void | Promise<void>) | undefined;
     /**
      * Formats the announced message each time filter matches change while the popup is open.
      * @default defaultGetMatchCountLabel
      */
-    getMatchCountLabel?: (count: number) => string;
+    getMatchCountLabel?: ((count: number) => string) | undefined;
     /**
      * Supplies the label for a value whose node is not in collection, consulted by TreeSelectValue before the raw-value fallback.
      * @default undefined — unknown value renders as itself.
      */
-    getValueLabel?: (value: string) => string;
+    getValueLabel?: ((value: string) => string) | undefined;
     /**
-     * Whether clicking a branch row toggles its expansion as well as checking it; ArrowRight/ArrowLeft are unaffected either way.
+     * Whether clicking a branch row toggles its expansion as well as checking it; ArrowRight/ArrowLeft are unaffected either way. Ignored (treated as true) under `layout="columns"`, where the row is the only thing that opens a column.
      * @default false
      */
-    expandOnClick?: boolean;
+    expandOnClick?: boolean | undefined;
+    /**
+     * How the popup presents the hierarchy: one indented tree, or one tree per open level side by side. A non-empty filter draws `'columns'` as a tree.
+     * @default 'tree'
+     */
+    layout?: TreeSelectLayout | undefined;
     /**
      * Renders a node's content when deriving anatomy, forwarded to TreeSelectTree; ignored under full manual composition.
      * @default undefined — renders each node's label ?? value as plain text.
      */
-    renderNode?: (node: TreeSelectNode) => React.ReactNode;
+    renderNode?: ((node: TreeSelectNode) => React.ReactNode) | undefined;
     /**
      * Placeholder for the derived trigger while nothing is checked, read only while deriving anatomy.
      * @default undefined
      */
-    placeholder?: string;
+    placeholder?: string | undefined;
     /**
      * Empty-state message shown when no node matches the filter; only read while deriving anatomy.
      * @default 'No matches'
      */
-    emptyMessage?: string;
+    emptyMessage?: string | undefined;
     /**
      * Accessible name for derived components; only read while deriving anatomy. Falls back to placeholder.
      * @default undefined — if neither is set, no attribute is emitted.
      */
-    'aria-label'?: string;
+    'aria-label'?: string | undefined;
+    /**
+     * Size rung the skin scales the panel by, fed to the derived Content.
+     * @default undefined — the skin's own default size.
+     */
+    size?: 'sm' | 'lg' | (string & {}) | undefined;
 }
 /** Props for {@link TreeSelectTrigger}, the `role="combobox"` button that opens the popup. */
 export interface TreeSelectTriggerProps extends PrimitivePropsWithRef<'button'> {
@@ -294,7 +311,7 @@ export interface TreeSelectValueProps extends PrimitivePropsWithRef<'span'> {
      * Stand-in content rendered while nothing is checked.
      * @default undefined
      */
-    placeholder?: React.ReactNode;
+    placeholder?: React.ReactNode | undefined;
 }
 /** Props for TreeSelectPortal, which teleports the popup to document.body while open. */
 export interface TreeSelectPortalProps extends PortalProps {
@@ -302,51 +319,56 @@ export interface TreeSelectPortalProps extends PortalProps {
      * Renders and mounts TreeSelectContent even while closed, for animation libraries needing the outgoing content during exit.
      * @default false
      */
-    forceMount?: boolean;
+    forceMount?: boolean | undefined;
 }
-/**
- * Props for TreeSelectContent, the popup panel; extends PopperContentProps (side, align, sideOffset, alignOffset, avoidCollisions, collisionPadding).
- */
+/** Props for TreeSelectContent, the popup panel; extends PopperContentProps (side, align, sideOffset, alignOffset, avoidCollisions, collisionPadding). */
 export interface TreeSelectContentProps extends PopperContentProps {
     /**
      * Mounts this popup even while closed, instead of unmounting it.
      * @default false
      */
-    forceMount?: boolean;
+    forceMount?: boolean | undefined;
     /**
      * Fires on Escape while the popup is open, before it closes; call preventDefault() to keep it open.
      * @default undefined — no-op if omitted.
      */
-    onEscapeKeyDown?: (event: KeyboardEvent) => void;
+    onEscapeKeyDown?: ((event: KeyboardEvent) => void) | undefined;
     /**
      * Fires on a pointer-down outside the popup and trigger; call preventDefault() to keep it open.
      * @default undefined — no-op if omitted.
      */
-    onPointerDownOutside?: (event: PointerEvent) => void;
+    onPointerDownOutside?: ((event: PointerEvent) => void) | undefined;
     /**
      * Fires when focus moves outside the popup and trigger; call preventDefault() to keep open.
      * @default undefined — no-op if omitted.
      */
-    onFocusOutside?: (event: CustomEvent<FocusEvent>) => void;
+    onFocusOutside?: ((event: CustomEvent<FocusEvent>) => void) | undefined;
     /**
      * Fires for either kind of outside interaction, before the specific handler with the same event.
      * @default undefined — no-op if omitted.
      */
-    onInteractOutside?: (event: InteractOutsideEvent) => void;
+    onInteractOutside?: ((event: InteractOutsideEvent) => void) | undefined;
+    /**
+     * Size rung the skin scales the panel by, mirrored to `data-size`.
+     * @default undefined — the skin's own default size.
+     */
+    size?: 'sm' | 'lg' | (string & {}) | undefined;
 }
 /** Props for TreeSelectTree, the role="tree" inside the popup. */
-export interface TreeSelectTreeProps extends Omit<PrimitivePropsWithRef<'div'>, 'children' | 'defaultValue'> {
+export interface TreeSelectTreeProps extends Omit<PrimitivePropsWithRef<'div'>, 'children' | 'defaultValue' | 'ref'> {
     /**
      * Renders a node's content (label, indicators); returned nodes render inside the node's treeitem.
      * @default undefined — renders the node's label ?? value as plain text.
      */
-    renderLabel?: (node: TreeSelectNode) => React.ReactNode;
+    renderLabel?: ((node: TreeSelectNode) => React.ReactNode) | undefined;
     /**
      * Renders exactly this row set instead of the whole collection; rows render flat as { value, depth } pairs with row.depth supplying aria-level.
      * @default undefined — renders every visible node from collection, nested.
      */
-    rows?: readonly Pick<TreeSelectFlatNode, 'value' | 'depth'>[];
+    rows?: readonly Pick<TreeSelectFlatNode, 'value' | 'depth'>[] | undefined;
 }
+/** Props for TreeSelectColumns, the `role="presentation"` track holding one tree per open level. */
+export type TreeSelectColumnsProps = Omit<PrimitivePropsWithRef<'div'>, 'defaultValue'>;
 /** Props for a single TreeSelectItem node. Normally rendered by TreeSelectTree. */
 export interface TreeSelectItemProps extends Omit<PrimitivePropsWithRef<'div'>, 'children'> {
     /** The collection node this row stands for. */
@@ -355,7 +377,7 @@ export interface TreeSelectItemProps extends Omit<PrimitivePropsWithRef<'div'>,
      * The row's content — the label, plus any indicators.
      * @default undefined
      */
-    children?: React.ReactNode;
+    children?: React.ReactNode | undefined;
 }
 /** Props for TreeSelectItemIndicator, the checkmark shown on checked or partially-checked nodes. */
 export interface TreeSelectItemIndicatorProps extends PrimitivePropsWithRef<'span'> {
@@ -363,7 +385,7 @@ export interface TreeSelectItemIndicatorProps extends PrimitivePropsWithRef<'spa
      * Renders even while the node is unchecked, for animating the check or reserving its space.
      * @default false
      */
-    forceMount?: boolean;
+    forceMount?: boolean | undefined;
 }
 /** Props for TreeSelectEmpty, shown in place of the tree when the filter matches nothing. */
 export interface TreeSelectEmptyProps extends PrimitivePropsWithRef<'div'> {