@ssa-ui-kit/core 3.21.2 → 3.22.0

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

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

@@ -0,0 +1,42 @@
+import { AnyTreeItem, TreeItem, TreeLevel } from './types';
+export interface TreeIndexEntry<TMeta> {
+    item: AnyTreeItem<TMeta>;
+    level: TreeLevel;
+    parentId: string | null;
+    childIds: string[];
+}
+export interface TreeIndex<TMeta> {
+    byId: Map<string, TreeIndexEntry<TMeta>>;
+    /** Top-level ids, in order. */
+    rootIds: string[];
+}
+/** Left offsets per level, taken from the design (Level 1 / 2 / 3). */
+export declare const LEVEL_INDENT: Record<TreeLevel, number>;
+export declare const getIndent: (level: TreeLevel, indent?: number) => number;
+/**
+ * Flattens the tree into an id-keyed map once per `items` change, so that
+ * ancestor lookups, sibling collapsing and keyboard navigation are all O(1)
+ * rather than repeated walks.
+ */
+export declare const buildTreeIndex: <TMeta>(items: TreeItem<TMeta>[]) => TreeIndex<TMeta>;
+/** Ids of every ancestor of `id`, nearest first. Unknown ids yield `[]`. */
+export declare const getAncestorIds: <TMeta>(index: TreeIndex<TMeta>, id: string) => string[];
+/**
+ * Ids that should be emphasised as "on the way to" the selection — every
+ * ancestor of every selected node.
+ */
+export declare const getSelectedPathIds: <TMeta>(index: TreeIndex<TMeta>, selectedIds: string[]) => Set<string>;
+/**
+ * The ids a user can currently move focus to: every node whose ancestors are
+ * all expanded, in render order, skipping disabled rows.
+ */
+export declare const getVisibleIds: <TMeta>(index: TreeIndex<TMeta>, expandedIds: string[]) => string[];
+/**
+ * Union of two id lists, order-preserving and duplicate-free.
+ *
+ * Returns `current` untouched when it already covers `added`, so a caller can
+ * use the identity of the result to decide whether anything changed. The check
+ * is membership, not size: `current` may itself carry duplicates, and
+ * comparing a deduped Set against its raw length would then hide the merge.
+ */
+export declare const mergeIds: (current: string[], added: string[]) => string[];

package/dist/components/Wrapper/Wrapper.d.ts

@@ -1,4 +1,10 @@
 import { CommonProps } from '../../types/emotion';
+/** Flex container direction (maps to CSS flex-direction) */
+export type WrapperDirection = 'row' | 'row-reverse' | 'column' | 'column-reverse';
+/** Cross-axis alignment (maps to CSS align-items) */
+export type WrapperAlignItems = 'flex-start' | 'center' | 'flex-end' | 'stretch' | 'baseline' | 'start' | 'end' | 'self-start' | 'self-end' | 'normal';
+/** Main-axis alignment (maps to CSS justify-content) */
+export type WrapperJustifyContent = 'flex-start' | 'flex-end' | 'center' | 'space-between' | 'space-around' | 'space-evenly' | 'start' | 'end' | 'left' | 'right' | 'normal';
 /**
  * Wrapper - Flexible flexbox container component
  *
@@ -49,12 +55,6 @@ import { CommonProps } from '../../types/emotion';
  * </Wrapper>
  * ```
  */
-/** Flex container direction (maps to CSS flex-direction) */
-export type WrapperDirection = 'row' | 'row-reverse' | 'column' | 'column-reverse';
-/** Cross-axis alignment (maps to CSS align-items) */
-export type WrapperAlignItems = 'flex-start' | 'center' | 'flex-end' | 'stretch' | 'baseline' | 'start' | 'end' | 'self-start' | 'self-end' | 'normal';
-/** Main-axis alignment (maps to CSS justify-content) */
-export type WrapperJustifyContent = 'flex-start' | 'flex-end' | 'center' | 'space-between' | 'space-around' | 'space-evenly' | 'start' | 'end' | 'left' | 'right' | 'normal';
 declare const Wrapper: import("@emotion/styled").StyledComponent<{
     theme?: import("@emotion/react").Theme;
     as?: React.ElementType;

package/dist/components/index.d.ts

@@ -107,6 +107,7 @@ export type * from './ResponsiveImage/types';
 export { default as NavBar } from './NavBar';
 export * from './NavBar';
 export * from './CollapsibleNavBar';
+export * from './TreeView';
 export { default as Tab } from './Tab';
 export { default as TabBar } from './TabBar';
 export * from './TabBar';