@ssa-ui-kit/core 3.21.2 → 3.22.0

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

@@ -84,6 +84,20 @@ export type DropdownProps<P extends DropdownOptionProps> = {
      * @default 200
      */
     maxHeight?: number;
+    /**
+     * Width of the dropdown.
+     * Can be a number (pixels) or a string (any CSS value, e.g. `'100%'`).
+     *
+     * The value is applied to the positioning base; the toggle button is
+     * stretched to fill it, so a relative width like `'60%'` resolves against the
+     * surrounding container instead of compounding. It also clears the base's
+     * default `min-width` and the toggle's `max-width`, which would otherwise cap
+     * the value.
+     *
+     * Has no default: when omitted, the dropdown sizes itself to its content,
+     * matching the behaviour of previous versions.
+     */
+    width?: string | number;
 };
 /**
  * Context value shared with child DropdownOption components via MultipleDropdownContext

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

@@ -1,2 +1,41 @@
 import { WithNestedTableRowProps } from './types';
+/**
+ * WithNestedTableRow - Groups rows into one collapsible unit.
+ *
+ * Wrap a run of `NestedTableRow` children in it. **Position decides role**: the
+ * first child becomes the sub-header that carries the toggle, and the rest are
+ * the rows it shows and hides. Renders no markup of its own — it only supplies
+ * each child with the group's context — so it is safe between `TableBody` and
+ * the rows.
+ *
+ * A group containing a single row has nothing to toggle, so it renders no icon
+ * and ignores `defaultCollapsed` — otherwise it could start collapsed with no
+ * way to reopen it.
+ *
+ * @category Components
+ * @subcategory Data Display
+ *
+ * @example
+ * ```tsx
+ * // One group per team; each starts expanded
+ * {teams.map((team) => (
+ *   <WithNestedTableRow key={team.id}>
+ *     <NestedTableRow>
+ *       <NestedTableCell>{team.name}</NestedTableCell>
+ *     </NestedTableRow>
+ *     {team.members.map((member) => (
+ *       <NestedTableRow key={member.id}>
+ *         <NestedTableCell>{member.name}</NestedTableCell>
+ *       </NestedTableRow>
+ *     ))}
+ *   </WithNestedTableRow>
+ * ))}
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Collapse just this group, whatever the table default is
+ * <WithNestedTableRow defaultCollapsed>{rows}</WithNestedTableRow>
+ * ```
+ */
 export declare const WithNestedTableRow: ({ children, defaultCollapsed, }: WithNestedTableRowProps) => import("@emotion/react/jsx-runtime").JSX.Element[] | null | undefined;

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 {};