@ssa-ui-kit/core 3.21.3 → 3.22.0

package/dist/components/NestedTable/components/NestedTable.d.ts

@@ -1,4 +1,61 @@
 import { PropsWithChildren, TableHTMLAttributes } from 'react';
 import { CommonProps } from '../../../types/emotion';
 import { NestedTableContextType } from '../types';
+/**
+ * NestedTable - Table whose rows collapse into expandable groups.
+ *
+ * Renders a `Table` and provides the context the nested row components read, so
+ * every piece below must live inside it.
+ *
+ * ### Structure
+ * ```
+ * NestedTable                     — provides icons + default collapsed state
+ * └── TableBody
+ *     └── WithNestedTableRow      — one collapsible group
+ *         ├── NestedTableRow      — first child: the sub-header that toggles
+ *         │   └── NestedTableCell
+ *         └── NestedTableRow      — remaining children: the collapsible rows
+ *             └── NestedTableCell
+ * ```
+ *
+ * Each `WithNestedTableRow` is one group. Use as many as you need, and give the
+ * header row its own `WithNestedTableRow` with `isHeader` on the row.
+ *
+ * ### Collapsing is CSS, not unmounting
+ * Collapsed rows stay in the DOM at zero height with `visibility: hidden`, which
+ * is what makes the transition animate. They remain findable by queries and by
+ * `Ctrl+F`, so do not rely on collapse to hide sensitive content.
+ *
+ * @category Components
+ * @subcategory Data Display
+ *
+ * @example
+ * ```tsx
+ * <NestedTable>
+ *   <TableBody>
+ *     <WithNestedTableRow>
+ *       <NestedTableRow>
+ *         <NestedTableCell>Engineering</NestedTableCell>
+ *         <NestedTableCell>24</NestedTableCell>
+ *       </NestedTableRow>
+ *       <NestedTableRow>
+ *         <NestedTableCell>Platform</NestedTableCell>
+ *         <NestedTableCell>9</NestedTableCell>
+ *       </NestedTableRow>
+ *     </WithNestedTableRow>
+ *   </TableBody>
+ * </NestedTable>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Start collapsed, with custom toggle icons
+ * <NestedTable
+ *   defaultCollapsed
+ *   collapsedIconName="carrot-right"
+ *   expandedIconName="carrot-down">
+ *   {groups}
+ * </NestedTable>
+ * ```
+ */
 export declare const NestedTable: ({ children, collapsedIconName, expandedIconName, defaultCollapsed, ...rest }: PropsWithChildren & NestedTableContextType & CommonProps & TableHTMLAttributes<HTMLTableElement>) => import("@emotion/react/jsx-runtime").JSX.Element;

package/dist/components/NestedTable/components/NestedTableCell.d.ts

@@ -1,3 +1,36 @@
 import { HTMLAttributes } from 'react';
 import { CommonProps } from '../../../types/emotion';
+/**
+ * NestedTableCell - Cell for a `NestedTableRow`.
+ *
+ * Use instead of `TableCell` inside a nested table: it reads the group's
+ * collapsed state and animates its own height, which a plain `TableCell` will
+ * not do. Must be rendered inside `WithNestedTableRow`.
+ *
+ * ### Children are wrapped in a div
+ * The cell renders its children inside a `Wrapper`, and the collapse transition
+ * animates that inner element rather than the `td`. Two consequences: a `& div`
+ * selector in your `css` will hit the wrapper, and content that must fill the
+ * cell should stretch the wrapper rather than the cell itself.
+ *
+ * Borders and background are cleared so the group reads as one block; the row
+ * supplies the shading.
+ *
+ * @category Components
+ * @subcategory Data Display
+ *
+ * @example
+ * ```tsx
+ * <NestedTableRow>
+ *   <NestedTableCell>Platform</NestedTableCell>
+ *   <NestedTableCell>9</NestedTableCell>
+ * </NestedTableRow>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Header cells render as `th`
+ * <NestedTableCell as="th">Headcount</NestedTableCell>
+ * ```
+ */
 export declare const NestedTableCell: ({ children, ...props }: React.PropsWithChildren<HTMLAttributes<HTMLTableCellElement>> & CommonProps) => import("@emotion/react/jsx-runtime").JSX.Element;

package/dist/components/NestedTable/components/NestedTableRow.d.ts

@@ -1,4 +1,48 @@
 import { HTMLAttributes } from 'react';
+/**
+ * NestedTableRow - One row inside a `WithNestedTableRow` group.
+ *
+ * Must be rendered inside `WithNestedTableRow`; it reads that group's context to
+ * know whether it is the sub-header and whether the group is collapsed.
+ *
+ * ### It prepends a cell for you
+ * The row renders a narrow toggle cell **before** your children, so a row with
+ * two `NestedTableCell` children occupies **three** columns. Size the header and
+ * `colSpan` values accordingly — this is the usual cause of a nested table
+ * whose columns look off by one.
+ *
+ * ### First child in the group is the toggle
+ * The first `NestedTableRow` in a `WithNestedTableRow` is the sub-header: it is
+ * shaded, its cells are bold, it shows the toggle icon, and clicking anywhere on
+ * it collapses or expands the rest of the group. Later rows are the collapsible
+ * body. A group holding only one row shows no toggle and never collapses.
+ *
+ * @category Components
+ * @subcategory Data Display
+ *
+ * @example
+ * ```tsx
+ * <WithNestedTableRow>
+ *   <NestedTableRow>
+ *     <NestedTableCell>Engineering</NestedTableCell>
+ *   </NestedTableRow>
+ *   <NestedTableRow>
+ *     <NestedTableCell>Platform</NestedTableCell>
+ *   </NestedTableRow>
+ * </WithNestedTableRow>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Header row: renders the leading cell as an empty `th`
+ * <WithNestedTableRow>
+ *   <NestedTableRow isHeader>
+ *     <NestedTableCell as="th">Team</NestedTableCell>
+ *     <NestedTableCell as="th">Headcount</NestedTableCell>
+ *   </NestedTableRow>
+ * </WithNestedTableRow>
+ * ```
+ */
 export declare const NestedTableRow: ({ children, isHeader, ...props }: React.PropsWithChildren<{
     isHeader?: boolean;
 } & HTMLAttributes<HTMLTableRowElement>>) => import("@emotion/react/jsx-runtime").JSX.Element;

package/dist/components/NestedTable/types.d.ts

@@ -1,8 +1,17 @@
 import { Dispatch, SetStateAction } from 'react';
 import { IconProps } from '../Icon/types';
 export type NestedTableContextType = {
+    /** Toggle icon shown while a group is collapsed. @default 'carrot-up' */
     collapsedIconName?: IconProps['name'];
+    /** Toggle icon shown while a group is expanded. @default 'carrot-down' */
     expandedIconName?: IconProps['name'];
+    /**
+     * Whether groups start collapsed. Applies to every group in the table; a
+     * single `WithNestedTableRow` can override it. Groups holding one row ignore
+     * it, since they have no toggle to reopen with.
+     *
+     * @default false
+     */
     defaultCollapsed?: boolean;
 };
 export type NestedTableRowContextType = {
@@ -12,6 +21,14 @@ export type NestedTableRowContextType = {
     setIsCollapsed: Dispatch<SetStateAction<boolean>>;
 };
 export type WithNestedTableRowProps = {
+    /**
+     * The group's rows. The first element becomes the sub-header that toggles the
+     * group; the rest collapse under it.
+     */
     children: React.ReactNode | React.ReactNode[];
+    /**
+     * Overrides the table-level `defaultCollapsed` for this group only. Ignored
+     * when the group holds a single row.
+     */
     defaultCollapsed?: boolean;
 };

package/dist/components/TableRow/TableRow.d.ts

@@ -1,3 +1,54 @@
 import { TableRowProps } from './types';
+/**
+ * TableRow - Table row component for table data
+ *
+ * A styled tr element that represents a single row in a table. Used within
+ * TableHead or TableBody sections. Supports disabled state for non-interactive
+ * rows. Works with TableCell or TableCellHeader components.
+ *
+ * @category Components
+ * @subcategory Data Display
+ *
+ * @example
+ * ```tsx
+ * // Basic table row in body
+ * <TableBody>
+ *   <TableRow>
+ *     <TableCell>John Doe</TableCell>
+ *     <TableCell>john@example.com</TableCell>
+ *     <TableCell>Admin</TableCell>
+ *   </TableRow>
+ * </TableBody>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Table row with click handler
+ * <TableRow onClick={() => handleRowClick(item)}>
+ *   <TableCell>{item.name}</TableCell>
+ *   <TableCell>{item.email}</TableCell>
+ * </TableRow>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Disabled table row (aria-disabled is automatically set)
+ * <TableRow disabled>
+ *   <TableCell>Disabled Row</TableCell>
+ * </TableRow>
+ * ```
+ *
+ * @see {@link Table} - Parent table component
+ * @see {@link TableHead} - Header section (use TableCellHeader in rows)
+ * @see {@link TableBody} - Body section (use TableCell in rows)
+ * @see {@link TableCell} - Data cell component
+ * @see {@link TableCellHeader} - Header cell component
+ *
+ * @accessibility
+ * - Semantic HTML tr element
+ * - Automatically sets aria-disabled when disabled is true
+ * - Keyboard accessible when clickable
+ * - Proper table structure for screen readers
+ */
 declare const TableRow: import("react").ForwardRefExoticComponent<TableRowProps & import("react").RefAttributes<HTMLTableRowElement>>;
 export default TableRow;

package/dist/components/Tooltip/Tooltip.d.ts

@@ -11,13 +11,17 @@ import { TooltipProps } from './types';
  * positioning with auto-adjustment, and customizable appearance with size
  * variants and optional arrows.
  *
+ * Note that the tooltip opens on **click** by default. For the usual hover
+ * behaviour pass `enableHover enableClick={false}`, as every example below and
+ * every call site in the kit does.
+ *
  * @category Components
  * @subcategory Overlay
  *
  * @example
  * ```tsx
  * // Basic tooltip on hover
- * <Tooltip>
+ * <Tooltip enableHover enableClick={false}>
  *   <TooltipTrigger>
  *     <Button>Hover me</Button>
  *   </TooltipTrigger>
@@ -28,7 +32,7 @@ import { TooltipProps } from './types';
  * @example
  * ```tsx
  * // Tooltip with custom placement
- * <Tooltip placement="bottom" size="large">
+ * <Tooltip enableHover enableClick={false} placement="bottom" size="large">
  *   <TooltipTrigger>
  *     <Icon name="info" />
  *   </TooltipTrigger>
@@ -43,8 +47,8 @@ import { TooltipProps } from './types';
  *
  * @example
  * ```tsx
- * // Click-to-open tooltip
- * <Tooltip enableClick enableHover={false}>
+ * // Click-to-open tooltip — this is the default interaction
+ * <Tooltip>
  *   <TooltipTrigger>
  *     <Button>Click for info</Button>
  *   </TooltipTrigger>
@@ -55,7 +59,7 @@ import { TooltipProps } from './types';
  * @example
  * ```tsx
  * // Dark surface, no shadow
- * <Tooltip color="dark" hasShadow={false}>
+ * <Tooltip enableHover enableClick={false} color="dark" hasShadow={false}>
  *   <TooltipTrigger>
  *     <Button>Hover me</Button>
  *   </TooltipTrigger>
@@ -68,7 +72,7 @@ import { TooltipProps } from './types';
  * @example
  * ```tsx
  * // Tooltip without arrow
- * <Tooltip hasArrow={false}>
+ * <Tooltip enableHover enableClick={false} hasArrow={false}>
  *   <TooltipTrigger>
  *     <span>?</span>
  *   </TooltipTrigger>

package/dist/components/Tooltip/types.d.ts

@@ -30,7 +30,7 @@ export type TooltipColor = FloatingSurfaceColor;
  *
  * @example
  * ```tsx
- * <Tooltip placement="top">
+ * <Tooltip enableHover enableClick={false} placement="top">
  *   <TooltipTrigger>
  *     <Button>Hover me</Button>
  *   </TooltipTrigger>
@@ -50,13 +50,22 @@ export interface TooltipProps extends CommonProps {
      */
     placement?: Placement;
     /**
-     * Enable tooltip on hover interaction
-     * @default true
+     * Enable tooltip on hover interaction.
+     *
+     * Off by default — despite the component's name, the tooltip opens on click
+     * unless this is set. Pass `enableHover enableClick={false}` for the usual
+     * hover-only behaviour; every call site in the kit does.
+     *
+     * @default false
      */
     enableHover?: boolean;
     /**
-     * Enable tooltip on click interaction
-     * @default false
+     * Enable tooltip on click interaction.
+     *
+     * On by default. Set it to `false` alongside `enableHover` when a click on
+     * the trigger has to do something else, such as selecting an item.
+     *
+     * @default true
      */
     enableClick?: boolean;
     /**
@@ -89,8 +98,12 @@ export interface TooltipProps extends CommonProps {
      */
     hoverCloseDelay?: number;
     /**
-     * Size variant of the tooltip content
-     * @default 'medium'
+     * Size variant of the tooltip content.
+     *
+     * Note that `small` is 8px type — intended for dense chart labels rather
+     * than prose. Use `medium` (12px) or `large` (14px) for readable text.
+     *
+     * @default 'small'
      */
     size?: TooltipSize;
     /**

package/dist/components/TooltipContent/TooltipContent.d.ts

@@ -3,9 +3,13 @@ import { TooltipContentProps } from '../Tooltip/types';
  * TooltipContent - Content container for tooltip display
  *
  * Renders the actual tooltip content that appears when the trigger is activated.
- * Uses Floating Portal for proper z-index stacking and FloatingFocusManager for
- * keyboard accessibility. Automatically positions based on Floating UI context
- * and respects size variants and arrow configuration.
+ * Automatically positions based on Floating UI context and respects size
+ * variants and arrow configuration. Uses FloatingFocusManager for keyboard
+ * accessibility.
+ *
+ * Renders in a Floating Portal to escape any ancestor's `overflow` clipping.
+ * Note that the portal by itself does not lift the tooltip above positioned
+ * siblings -- the surface carries its own z-index for that.
  *
  * Only renders when tooltip is open (isOpen is true). Supports custom styling
  * and can contain any React content.

package/dist/components/TreeView/TreeView.d.ts

@@ -0,0 +1,62 @@
+import { TreeViewProps } from './types';
+/**
+ * TreeView — a nestable list of rows, up to three levels deep.
+ *
+ * Domain-free by design: it knows about expansion, selection, indentation and
+ * keyboard navigation, and nothing about routing or files. Give it `items`,
+ * and hand it a `renderItem` when the row needs to be something other than a
+ * plain label — a `NavLink`, a row with a size column, a checkbox.
+ *
+ * The fourth level is a **type error**, not a runtime check: `items` is typed
+ * one level at a time, so an over-deep tree fails at the call site.
+ *
+ * Expansion and selection both follow the kit's controllable pattern
+ * (`expandedIds` / `defaultExpandedIds` / `onExpandedIdsChange`, and the same
+ * trio for selection). Selection is always an array, even in the default
+ * `single` mode, so moving to multi-select later costs nothing.
+ *
+ * ## Styling
+ *
+ * Every part carries a stable class — `ssa-tree`, `ssa-tree__group`,
+ * `ssa-tree__item` (plus `--level-1|2|3`, `--selected`, `--expanded`),
+ * `ssa-tree__row`, `ssa-tree__icon`, `ssa-tree__label`, `ssa-tree__toggle`.
+ * Target those from the `css` prop rather than the DOM shape; a single node
+ * can also carry its own `css`.
+ *
+ * @example
+ * ```tsx
+ * <TreeView
+ *   items={[
+ *     {
+ *       id: 'education',
+ *       label: 'Education',
+ *       iconName: 'education',
+ *       items: [
+ *         { id: 'courses', label: 'Courses' },
+ *         { id: 'exams', label: 'Exams' },
+ *       ],
+ *     },
+ *     { id: 'employee', label: 'Employee', iconName: 'user' },
+ *   ]}
+ *   defaultSelectedIds={['exams']}
+ *   onSelectedIdsChange={(ids) => console.log(ids)}
+ * />
+ * ```
+ *
+ * @example Routing rows, with selection owned by the router
+ * ```tsx
+ * <TreeView
+ *   items={items}
+ *   semantics="list"
+ *   selectedIds={[currentRouteId]}
+ *   renderItem={({ item, itemProps, icon, hasItems, isExpanded, toggleProps }) => (
+ *     <NavLink to={item.meta.path} {...itemProps}>
+ *       {icon}
+ *       <span>{item.label}</span>
+ *       {hasItems && <button {...toggleProps}>{isExpanded ? '−' : '+'}</button>}
+ *     </NavLink>
+ *   )}
+ * />
+ * ```
+ */
+export declare const TreeView: <TMeta>(props: TreeViewProps<TMeta>) => import("@emotion/react/jsx-runtime").JSX.Element;

package/dist/components/TreeView/TreeViewItem.d.ts

@@ -0,0 +1,32 @@
+import { AnyTreeItem, TreeItemRenderProps, TreeLevel, TreeViewProps } from './types';
+import { TreeIndex } from './utils';
+/**
+ * Everything the recursive rows share. Passed down as a prop rather than
+ * through React context: the tree is at most three levels deep, so threading
+ * it is cheaper than a provider and keeps the data flow readable.
+ */
+export interface TreeItemContext<TMeta> {
+    treeId: string;
+    index: TreeIndex<TMeta>;
+    expandedSet: Set<string>;
+    selectedSet: Set<string>;
+    selectedPath: Set<string>;
+    toggle: (id: string) => void;
+    select: (item: AnyTreeItem<TMeta>) => void;
+    focusedId: string | null;
+    registerItem: (id: string, element: HTMLLIElement | null) => void;
+    onItemKeyDown: (event: React.KeyboardEvent, id: string) => void;
+    theme: NonNullable<TreeViewProps['theme']>;
+    activeColor?: string;
+    semantics: NonNullable<TreeViewProps['semantics']>;
+    toggleOnItemClick: boolean;
+    reserveIconSpace: boolean;
+    indent?: number;
+    renderItem?: (props: TreeItemRenderProps<TMeta>) => React.ReactNode;
+}
+export declare const TreeViewItem: <TMeta>({ item, level, index: position, context, }: {
+    item: AnyTreeItem<TMeta>;
+    level: TreeLevel;
+    index: number;
+    context: TreeItemContext<TMeta>;
+}) => import("@emotion/react/jsx-runtime").JSX.Element;

package/dist/components/TreeView/index.d.ts

@@ -0,0 +1,2 @@
+export { TreeView } from './TreeView';
+export type { TreeViewProps, TreeItem, TreeItemLevel2, TreeItemLevel3, TreeItemBase, AnyTreeItem, TreeItemRenderProps, TreeLevel, } from './types';

package/dist/components/TreeView/styles.d.ts

@@ -0,0 +1,18 @@
+import { CSSObject } from '@emotion/react';
+import { TreeLevel, TreeViewProps } from './types';
+type TreeTheme = NonNullable<TreeViewProps['theme']>;
+export declare const ICON_SIZE = 24;
+export declare const TOGGLE_SIZE = 20;
+export declare const root: import("@emotion/react").SerializedStyles;
+export declare const group: import("@emotion/react").SerializedStyles;
+export declare const item: import("@emotion/react").SerializedStyles;
+export declare const row: (navTheme: TreeTheme, level: TreeLevel, indent: number, state: {
+    isSelected: boolean;
+    isEngaged: boolean;
+    isDisabled: boolean;
+    activeColor?: string;
+}) => CSSObject;
+export declare const icon: import("@emotion/react").SerializedStyles;
+export declare const label: import("@emotion/react").SerializedStyles;
+export declare const toggle: (isExpanded: boolean) => import("@emotion/react").SerializedStyles;
+export {};

package/dist/components/TreeView/types.d.ts

@@ -0,0 +1,162 @@
+import { CSSObject, Interpolation, Theme } from '@emotion/react';
+import { MapIconsType } from '../Icon/types';
+/**
+ * Fields shared by every node, at any level.
+ *
+ * `TMeta` is the consumer's own payload — a route path for navigation, a file
+ * size and mime type for a file tree. It travels untouched to `renderItem`,
+ * which is what keeps `TreeView` free of any domain knowledge.
+ */
+export interface TreeItemBase<TMeta = unknown> {
+    /**
+     * Stable identity. Expansion and selection are both expressed as arrays of
+     * these, so an id that changes between renders will drop the node's state.
+     */
+    id: string;
+    label: React.ReactNode;
+    /** Kit icon rendered before the label. Ignored when `icon` is set. */
+    iconName?: keyof MapIconsType;
+    /** Arbitrary icon element, for glyphs the kit doesn't ship. Wins over `iconName`. */
+    icon?: React.ReactNode;
+    /** Blocks selection, expansion and keyboard focus, and dims the row. */
+    disabled?: boolean;
+    /** Styles for this row only, merged after the theme defaults. */
+    css?: CSSObject;
+    meta?: TMeta;
+}
+/**
+ * A third-level node. `items?: never` is what caps the tree at three levels:
+ * a fourth is a type error at the call site rather than a runtime surprise.
+ */
+export interface TreeItemLevel3<TMeta = unknown> extends TreeItemBase<TMeta> {
+    items?: never;
+}
+/** A second-level node. Its children are the deepest the tree allows. */
+export interface TreeItemLevel2<TMeta = unknown> extends TreeItemBase<TMeta> {
+    items?: TreeItemLevel3<TMeta>[];
+}
+/** A top-level node. `items` is optional, so a flat one-level list is valid. */
+export interface TreeItem<TMeta = unknown> extends TreeItemBase<TMeta> {
+    items?: TreeItemLevel2<TMeta>[];
+}
+/** Any node, whatever its depth — what `renderItem` and the callbacks receive. */
+export type AnyTreeItem<TMeta = unknown> = TreeItem<TMeta> | TreeItemLevel2<TMeta> | TreeItemLevel3<TMeta>;
+/** A node's depth, 1-based. Three is the maximum the tree accepts. */
+export type TreeLevel = 1 | 2 | 3;
+/**
+ * Everything a custom row needs to render itself and stay in sync.
+ *
+ * Spread `itemProps` on whatever element you make interactive (a `NavLink`, a
+ * `button`, a `div`) and `toggleProps` on the expand/collapse control. The
+ * surrounding `li`, its ARIA and its keyboard handling belong to `TreeView` —
+ * a custom row never has to reproduce them.
+ */
+export interface TreeItemRenderProps<TMeta = unknown> {
+    item: AnyTreeItem<TMeta>;
+    level: TreeLevel;
+    /** Position among siblings, zero-based. */
+    index: number;
+    isSelected: boolean;
+    isExpanded: boolean;
+    /**
+     * True when the node is an ancestor of a selected node. The design keeps
+     * levels 1 and 2 emphasised while the selected level 3 row is blue, and this
+     * is the flag that drives it.
+     */
+    isInSelectedPath: boolean;
+    hasItems: boolean;
+    isDisabled: boolean;
+    /** Selects the node, honouring `selectionMode`. No-op when disabled. */
+    select: () => void;
+    /** Expands or collapses the node, honouring `expandMode`. No-op without children. */
+    toggle: () => void;
+    /** Spread on the interactive row element. */
+    itemProps: React.HTMLAttributes<HTMLElement>;
+    /** Spread on the expand/collapse control. Empty object when `hasItems` is false. */
+    toggleProps: React.ButtonHTMLAttributes<HTMLButtonElement>;
+    /** The node's icon, already built and themed — `null` when it has none. */
+    icon: React.ReactNode;
+}
+/**
+ * Props for {@link TreeView}. `TMeta` is the payload carried on each node and
+ * handed back to `renderItem` and the selection callback.
+ */
+export interface TreeViewProps<TMeta = unknown> {
+    /**
+     * The tree. Three levels deep at most — the fourth is rejected by the type,
+     * and `items` is optional at every level, so a one-level list is valid.
+     */
+    items: TreeItem<TMeta>[];
+    /** Ids of expanded nodes. Pass to control expansion yourself. */
+    expandedIds?: string[];
+    /** Ids expanded on mount, when expansion is uncontrolled. */
+    defaultExpandedIds?: string[];
+    onExpandedIdsChange?: (ids: string[]) => void;
+    /**
+     * `single` collapses siblings when a node expands, accordion-style.
+     * @default 'multiple'
+     */
+    expandMode?: 'multiple' | 'single';
+    /**
+     * Ids of selected nodes. Always an array, even in `single` mode — which is
+     * what lets a consumer move to multi-select later without an API change.
+     */
+    selectedIds?: string[];
+    defaultSelectedIds?: string[];
+    /** Receives the full next selection, plus the node that was acted on. */
+    onSelectedIdsChange?: (ids: string[], item: AnyTreeItem<TMeta>) => void;
+    /**
+     * `single` replaces the selection on click, `multiple` toggles membership.
+     * @default 'single'
+     */
+    selectionMode?: 'single' | 'multiple';
+    /** Replaces the row's interior. The `li`, ARIA and keyboard stay with `TreeView`. */
+    renderItem?: (props: TreeItemRenderProps<TMeta>) => React.ReactNode;
+    /**
+     * Colour set. `dark` is for sidebars such as `CollapsibleNavBar`'s default theme.
+     * @default 'light'
+     */
+    theme?: 'light' | 'dark';
+    /**
+     * Overrides the selected row's colour (and the chevron and icon on it), for
+     * a consumer whose accent isn't the theme's own. Everything else — rest,
+     * hover, the engaged path — still comes from `theme`.
+     */
+    activeColor?: string;
+    /**
+     * `tree` gives a real `role="tree"` with roving focus and arrow-key
+     * navigation — right for a file tree. `list` gives nested `ul`/`li` with
+     * disclosure buttons, which is the correct pattern for a navigation menu of
+     * links and leaves focus order to the browser.
+     * @default 'tree'
+     */
+    semantics?: 'tree' | 'list';
+    /**
+     * Whether clicking anywhere on a parent row toggles it, rather than only the
+     * chevron.
+     * @default true
+     */
+    toggleOnItemClick?: boolean;
+    /**
+     * Expand the ancestors of selected nodes, on mount and whenever the
+     * selection moves. Ignored while expansion is controlled.
+     * @default true
+     */
+    autoExpandSelected?: boolean;
+    /**
+     * Keep the icon column even on rows without an icon, so labels stay aligned
+     * with their icon-bearing siblings. Off by default: a tree whose rows have
+     * no icons at all would otherwise carry an empty column.
+     * @default false
+     */
+    reserveIconSpace?: boolean;
+    /**
+     * Left offset per level, in px. Defaults to the design's 0 / 24 / 40; a
+     * number here makes the steps linear instead (`(level - 1) * indent`).
+     */
+    indent?: number;
+    /** Accessible name for the tree. */
+    'aria-label'?: string;
+    className?: string;
+    css?: Interpolation<Theme>;
+}

package/dist/components/TreeView/useTreeViewState.d.ts

@@ -0,0 +1,21 @@
+import { AnyTreeItem, TreeViewProps } from './types';
+import { TreeIndex } from './utils';
+export interface UseTreeViewStateOptions<TMeta> extends Pick<TreeViewProps<TMeta>, 'expandedIds' | 'defaultExpandedIds' | 'onExpandedIdsChange' | 'expandMode' | 'selectedIds' | 'defaultSelectedIds' | 'onSelectedIdsChange' | 'selectionMode' | 'autoExpandSelected'> {
+    index: TreeIndex<TMeta>;
+    /** Presence of the prop, not its value — see `useControllableState`. */
+    isExpansionControlled: boolean;
+    isSelectionControlled: boolean;
+}
+/**
+ * Expansion and selection for `TreeView`, both controllable through the kit's
+ * `value` / `defaultValue` / `onChange` trio.
+ */
+export declare const useTreeViewState: <TMeta>({ index, isExpansionControlled, expandedIds, defaultExpandedIds, onExpandedIdsChange, expandMode, isSelectionControlled, selectedIds, defaultSelectedIds, onSelectedIdsChange, selectionMode, autoExpandSelected, }: UseTreeViewStateOptions<TMeta>) => {
+    expanded: string[];
+    expandedSet: Set<string>;
+    selectedSet: Set<string>;
+    selectedPath: Set<string>;
+    setExpanded: (next: string[]) => void;
+    toggle: (id: string) => void;
+    select: (item: AnyTreeItem<TMeta>) => void;
+};