@nexub/react 6.2.0 → 6.3.0

package/accessibility.json

@@ -1,5 +1,5 @@
 {
-  "version": "6.2.0",
+  "version": "6.3.0",
   "standard": "WCAG 2.2 Level AA",
   "method": {
     "automated": "axe-core rules tagged wcag2a, wcag2aa, wcag21a, wcag21aa and wcag22aa, run on every Storybook story in light and dark, and on open popups (menus, listboxes, dialogs), on every pull request; a new violation fails the build.",
@@ -1204,6 +1204,24 @@
       "keyboard": [],
       "screenReader": []
     },
+    {
+      "slug": "tree-view",
+      "name": "Tree View",
+      "package": "@nexub/react",
+      "automated": "pass",
+      "exceptions": [],
+      "keyboard": [
+        "ArrowDown / ArrowUp: Next or previous visible item.",
+        "ArrowRight: Opens a closed item, or moves to its first child. Mirrored in RTL.",
+        "ArrowLeft: Closes an open item, or moves to its parent. Mirrored in RTL.",
+        "Home / End: First or last visible item.",
+        "Enter / Space: Selects the item, or toggles its checkbox.",
+        "Type a letter: Moves to the next item starting with the typed text."
+      ],
+      "screenReader": [
+        "The tree is one tab stop (roving tabindex); it returns to the last focused or the selected item."
+      ]
+    },
     {
       "slug": "activity-feed",
       "name": "ActivityFeed",

package/dist/components/DataTable/DataTable.d.ts

@@ -1,5 +1,5 @@
 import * as React from 'react';
-import { type ColumnDef, type RowSelectionState, type RowData, type VisibilityState, type ColumnSizingState, type ColumnOrderState, type ColumnPinningState } from '@tanstack/react-table';
+import { type ColumnDef, type RowSelectionState, type RowData, type VisibilityState, type ColumnSizingState, type ColumnOrderState, type ColumnPinningState, type ExpandedState } from '@tanstack/react-table';
 declare module '@tanstack/react-table' {
     interface ColumnMeta<TData extends RowData, TValue> {
         /** Horizontal alignment of the header and cells. Use 'end' for numbers. @default 'start' */
@@ -75,5 +75,14 @@ export interface DataTableProps<TData> extends React.HTMLAttributes<HTMLDivEleme
     pagination?: {
         pageSize?: number;
     };
+    /**
+     * Nested rows (a tree table): return a row's children. The first column gets
+     * an expand toggle and indents each level. Sorting sorts within each level.
+     */
+    getSubRows?: (row: TData, index: number) => TData[] | undefined;
+    /** Expanded rows by id, or `true` for all. */
+    expanded?: ExpandedState;
+    defaultExpanded?: ExpandedState;
+    onExpandedChange?: (expanded: ExpandedState) => void;
 }
-export declare function DataTable<TData>({ columns, data, enableSorting, enableRowSelection, selectionColumn, rowSelection: rowSelectionProp, onRowSelectionChange, getRowId, bulkActions, density: densityProp, defaultDensity, onDensityChange, columnVisibility: columnVisibilityProp, onColumnVisibilityChange, viewOptions, toolbar, enableColumnResizing, columnSizing: columnSizingProp, onColumnSizingChange, enableColumnReordering, columnOrder: columnOrderProp, onColumnOrderChange, columnPinning: columnPinningProp, onColumnPinningChange, maxHeight, grid, rowWindow, pagination, caption, captionHidden, className, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, ...props }: DataTableProps<TData>): React.JSX.Element;
+export declare function DataTable<TData>({ columns, data, enableSorting, enableRowSelection, selectionColumn, rowSelection: rowSelectionProp, onRowSelectionChange, getRowId, bulkActions, density: densityProp, defaultDensity, onDensityChange, columnVisibility: columnVisibilityProp, onColumnVisibilityChange, viewOptions, toolbar, enableColumnResizing, columnSizing: columnSizingProp, onColumnSizingChange, enableColumnReordering, columnOrder: columnOrderProp, onColumnOrderChange, columnPinning: columnPinningProp, onColumnPinningChange, maxHeight, grid, rowWindow, pagination, getSubRows, expanded: expandedProp, defaultExpanded, onExpandedChange, caption, captionHidden, className, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, ...props }: DataTableProps<TData>): React.JSX.Element;

package/dist/components/DataTable/DataTable.js

@@ -7,9 +7,10 @@ import {
   getSortedRowModel,
   getFilteredRowModel,
   getPaginationRowModel,
+  getExpandedRowModel,
   flexRender
 } from "@tanstack/react-table";
-import { ArrowUp, ArrowDown, ChevronsUpDown, SlidersHorizontal, X } from "@nexub/icons";
+import { ArrowUp, ArrowDown, ChevronDown, ChevronRight, ChevronsUpDown, SlidersHorizontal, X } from "@nexub/icons";
 import { cn } from "../../utils/cn.js";
 import { disabledContainer, pressable } from "../../utils/control.js";
 import { floatingSurface } from "../../utils/surface.js";
@@ -102,6 +103,34 @@ const useAllRows = (count) => ({
   before: 0,
   after: 0
 });
+function TreeCell({
+  row,
+  expandLabel,
+  collapseLabel,
+  children
+}) {
+  const open = row.getIsExpanded();
+  const ref = React.useCallback(
+    (el) => {
+      if (el) el.style.paddingInlineStart = `${row.depth * 1.5}rem`;
+    },
+    [row.depth]
+  );
+  return /* @__PURE__ */ jsxs("div", { ref, className: "flex items-center gap-1", children: [
+    row.getCanExpand() ? /* @__PURE__ */ jsx(
+      "button",
+      {
+        type: "button",
+        "aria-expanded": open,
+        "aria-label": open ? collapseLabel : expandLabel,
+        onClick: row.toggleExpanded,
+        className: "-ms-1 inline-flex size-6 shrink-0 items-center justify-center rounded-shape-min text-[var(--color-on-surface-variant)] hover:bg-[var(--color-surface-container-high)]",
+        children: open ? /* @__PURE__ */ jsx(ChevronDown, { size: "xs", "aria-hidden": "true" }) : /* @__PURE__ */ jsx(ChevronRight, { size: "xs", "aria-hidden": "true", className: "rtl:-scale-x-100" })
+      }
+    ) : /* @__PURE__ */ jsx("span", { className: "-ms-1 size-6 shrink-0", "aria-hidden": "true" }),
+    children
+  ] });
+}
 const px = (n) => typeof n === "number" ? `${n}px` : n;
 const apply = (u, prev) => typeof u === "function" ? u(prev) : u;
 const columnLabel = (c) => typeof c.columnDef.header === "string" ? c.columnDef.header : c.id;
@@ -134,6 +163,10 @@ function DataTable({
   grid = false,
   rowWindow,
   pagination,
+  getSubRows,
+  expanded: expandedProp,
+  defaultExpanded,
+  onExpandedChange,
   caption,
   captionHidden = false,
   className,
@@ -174,6 +207,11 @@ function DataTable({
     defaultValue: {},
     onChange: onColumnPinningChange
   });
+  const [expanded = {}, setExpanded] = useControllableState({
+    value: expandedProp,
+    defaultValue: defaultExpanded ?? {},
+    onChange: onExpandedChange
+  });
   const [announcement, setAnnouncement] = React.useState("");
   const tableRef = React.useRef(null);
   const gridNav = React.useMemo(() => createGridNavigation(dir), [dir]);
@@ -223,9 +261,12 @@ function DataTable({
       columnVisibility,
       columnSizing,
       columnOrder,
-      columnPinning
+      columnPinning,
+      expanded: getSubRows ? expanded : void 0
     }),
     [
+      getSubRows,
+      expanded,
       enableSorting,
       sorting,
       enableRowSelection,
@@ -257,6 +298,12 @@ function DataTable({
     getSortedRowModel: enableSorting ? getSortedRowModel() : void 0,
     getFilteredRowModel: getFilteredRowModel(),
     getPaginationRowModel: pagination ? getPaginationRowModel() : void 0,
+    getSubRows,
+    getExpandedRowModel: getSubRows ? getExpandedRowModel() : void 0,
+    onExpandedChange: getSubRows ? (u) => setExpanded(apply(u, expanded)) : void 0,
+    // With pages, count top-level rows so a parent and its children stay together
+    // (TanStack then expands inside the page model; without pages it must not).
+    paginateExpandedRows: !pagination,
     enableRowSelection,
     manualPagination: false
   });
@@ -466,7 +513,7 @@ function DataTable({
                   "data-index": i,
                   "aria-rowindex": rowWin.virtual ? i + 2 : void 0,
                   "data-state": enableRowSelection && row.getIsSelected() ? "selected" : void 0,
-                  children: row.getVisibleCells().map((cell) => /* @__PURE__ */ jsx(
+                  children: row.getVisibleCells().map((cell, _i, cells) => /* @__PURE__ */ jsx(
                     TableCell,
                     {
                       ref: pinned || enableColumnResizing ? placeCell(cell.column) : void 0,
@@ -476,7 +523,7 @@ function DataTable({
                         pinClass(cell.column),
                         enableColumnResizing && "truncate"
                       ),
-                      children: flexRender(cell.column.columnDef.cell, cell.getContext())
+                      children: getSubRows && cell === cells.find((c) => c.column.id !== "__select") ? /* @__PURE__ */ jsx(TreeCell, { row, expandLabel: messages.expandRow, collapseLabel: messages.collapseRow, children: flexRender(cell.column.columnDef.cell, cell.getContext()) }) : flexRender(cell.column.columnDef.cell, cell.getContext())
                     },
                     cell.id
                   ))

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

@@ -0,0 +1,38 @@
+import * as React from 'react';
+export interface TreeNode {
+    id: string;
+    label: React.ReactNode;
+    /** Text for type-ahead when `label` isn't a string. */
+    textValue?: string;
+    icon?: React.ReactNode;
+    children?: TreeNode[];
+    /** Children exist but aren't loaded yet: expanding calls `onLoadChildren`. */
+    hasChildren?: boolean;
+    disabled?: boolean;
+}
+export interface TreeViewProps {
+    nodes: TreeNode[];
+    'aria-label'?: string;
+    'aria-labelledby'?: string;
+    expanded?: string[];
+    defaultExpanded?: string[];
+    onExpandedChange?: (ids: string[]) => void;
+    /** Single selection (ignored when `checkable`). */
+    selected?: string | null;
+    defaultSelected?: string | null;
+    onSelectedChange?: (id: string | null) => void;
+    /** Checkboxes with tri-state parents; `checked` lists every checked id, parents included. */
+    checkable?: boolean;
+    checked?: string[];
+    defaultChecked?: string[];
+    onCheckedChange?: (ids: string[]) => void;
+    /** Load a `hasChildren` node's children, then pass them in through `nodes`. */
+    onLoadChildren?: (node: TreeNode) => Promise<unknown>;
+    className?: string;
+}
+/**
+ * A hierarchy people can browse with the keyboard (ARIA tree): Arrow keys move
+ * and expand, Home/End jump, typing finds an item. Optional lazy children and
+ * tri-state checkboxes.
+ */
+export declare function TreeView({ nodes, expanded: expandedProp, defaultExpanded, onExpandedChange, selected: selectedProp, defaultSelected, onSelectedChange, checkable, checked: checkedProp, defaultChecked, onCheckedChange, onLoadChildren, className, ...aria }: TreeViewProps): React.JSX.Element;

package/dist/components/TreeView/TreeView.js

@@ -0,0 +1,253 @@
+"use client";
+import { jsx, jsxs } from "react/jsx-runtime";
+import * as React from "react";
+import { Check, ChevronRight, Minus } from "@nexub/icons";
+import { cn } from "../../utils/cn.js";
+import { useControllableState } from "../../hooks/useControllableState.js";
+import { Spinner } from "../Spinner/Spinner.js";
+const hasKids = (n) => Boolean(n.children?.length || n.hasChildren && !n.children);
+const text = (n) => n.textValue ?? (typeof n.label === "string" ? n.label : "");
+const descendants = (n) => (n.children ?? []).flatMap((c) => [c.id, ...descendants(c)]);
+function TreeView({
+  nodes,
+  expanded: expandedProp,
+  defaultExpanded,
+  onExpandedChange,
+  selected: selectedProp,
+  defaultSelected,
+  onSelectedChange,
+  checkable = false,
+  checked: checkedProp,
+  defaultChecked,
+  onCheckedChange,
+  onLoadChildren,
+  className,
+  ...aria
+}) {
+  const [expanded = [], setExpanded] = useControllableState({
+    value: expandedProp,
+    defaultValue: defaultExpanded ?? [],
+    onChange: onExpandedChange
+  });
+  const [selected = null, setSelected] = useControllableState({
+    value: selectedProp,
+    defaultValue: defaultSelected ?? null,
+    onChange: onSelectedChange
+  });
+  const [checked = [], setChecked] = useControllableState({
+    value: checkedProp,
+    defaultValue: defaultChecked ?? [],
+    onChange: onCheckedChange
+  });
+  const [loading, setLoading] = React.useState(null);
+  const [focused, setFocused] = React.useState(null);
+  const refs = React.useRef(/* @__PURE__ */ new Map());
+  const typed = React.useRef({ text: "", at: 0 });
+  const open = React.useMemo(() => new Set(expanded), [expanded]);
+  const checkedSet = React.useMemo(() => new Set(checked), [checked]);
+  const { all, visible } = React.useMemo(() => {
+    const all2 = /* @__PURE__ */ new Map();
+    const visible2 = [];
+    const walk = (list, level, parent, shown) => {
+      for (const node of list) {
+        const flat = { node, level, parent };
+        all2.set(node.id, flat);
+        if (shown) visible2.push(flat);
+        if (node.children) walk(node.children, level + 1, node.id, shown && open.has(node.id));
+      }
+    };
+    walk(nodes, 1, null, true);
+    return { all: all2, visible: visible2 };
+  }, [nodes, open]);
+  const tabStop = focused && visible.some((f) => f.node.id === focused) && focused || selected && visible.some((f) => f.node.id === selected) && selected || visible[0]?.node.id;
+  const focus = (id) => {
+    if (!id) return;
+    setFocused(id);
+    refs.current.get(id)?.focus();
+  };
+  const toggle = async (node, to = !open.has(node.id)) => {
+    if (!hasKids(node) || to === open.has(node.id)) return;
+    setExpanded(to ? [...expanded, node.id] : expanded.filter((id) => id !== node.id));
+    if (to && node.hasChildren && !node.children && onLoadChildren) {
+      setLoading(node.id);
+      try {
+        await onLoadChildren(node);
+      } finally {
+        setLoading((id) => id === node.id ? null : id);
+      }
+    }
+  };
+  const toggleCheck = (node) => {
+    const next = new Set(checkedSet);
+    const on = !next.has(node.id);
+    for (const id of [node.id, ...descendants(node)]) {
+      if (on) next.add(id);
+      else next.delete(id);
+    }
+    for (let p = all.get(node.id)?.parent; p; p = all.get(p)?.parent ?? null) {
+      const kids = all.get(p).node.children ?? [];
+      if (kids.every((k) => next.has(k.id))) next.add(p);
+      else next.delete(p);
+    }
+    setChecked([...next]);
+  };
+  const activate = (node) => {
+    if (node.disabled) return;
+    if (checkable) toggleCheck(node);
+    else setSelected(node.id);
+  };
+  const onKeyDown = (e, flat) => {
+    const { node } = flat;
+    const i = visible.findIndex((f) => f.node.id === node.id);
+    const rtl = getComputedStyle(e.currentTarget).direction === "rtl";
+    const flip = { ArrowLeft: "ArrowRight", ArrowRight: "ArrowLeft" };
+    const key = rtl ? flip[e.key] ?? e.key : e.key;
+    let handled = true;
+    switch (key) {
+      case "ArrowDown":
+        focus(visible[i + 1]?.node.id);
+        break;
+      case "ArrowUp":
+        focus(visible[i - 1]?.node.id);
+        break;
+      case "Home":
+        focus(visible[0]?.node.id);
+        break;
+      case "End":
+        focus(visible.at(-1)?.node.id);
+        break;
+      case "ArrowRight":
+        if (hasKids(node) && !open.has(node.id)) void toggle(node, true);
+        else if (open.has(node.id)) focus(node.children?.[0]?.id);
+        break;
+      case "ArrowLeft":
+        if (open.has(node.id)) void toggle(node, false);
+        else focus(flat.parent ?? void 0);
+        break;
+      case "Enter":
+      case " ":
+        activate(node);
+        break;
+      default: {
+        handled = false;
+        if (e.key.length !== 1 || e.ctrlKey || e.metaKey || e.altKey) break;
+        const now = Date.now();
+        const t = typed.current;
+        t.text = (now - t.at > 500 ? "" : t.text) + e.key.toLowerCase();
+        t.at = now;
+        const order = [...visible.slice(i + 1), ...visible.slice(0, i + 1)];
+        const hit = order.find((f) => text(f.node).toLowerCase().startsWith(t.text));
+        if (hit) {
+          focus(hit.node.id);
+          handled = true;
+        }
+      }
+    }
+    if (handled) {
+      e.preventDefault();
+      e.stopPropagation();
+    }
+  };
+  const render = (list, level, parent) => list.map((node, index) => {
+    const kids = hasKids(node);
+    const isOpen = open.has(node.id);
+    const isChecked = checkedSet.has(node.id);
+    const mixed = !isChecked && descendants(node).some((id) => checkedSet.has(id));
+    const flat = { node, level, parent };
+    return /* @__PURE__ */ jsxs(
+      "li",
+      {
+        ref: (el) => {
+          if (el) refs.current.set(node.id, el);
+          else refs.current.delete(node.id);
+        },
+        role: "treeitem",
+        "aria-level": level,
+        "aria-setsize": list.length,
+        "aria-posinset": index + 1,
+        "aria-expanded": kids ? isOpen : void 0,
+        "aria-selected": checkable ? void 0 : selected === node.id,
+        "aria-checked": checkable ? mixed ? "mixed" : isChecked : void 0,
+        "aria-disabled": node.disabled || void 0,
+        "aria-busy": loading === node.id || void 0,
+        tabIndex: tabStop === node.id ? 0 : -1,
+        onKeyDown: (e) => onKeyDown(e, flat),
+        onFocus: (e) => {
+          if (e.target === e.currentTarget) setFocused(node.id);
+        },
+        className: "outline-none [&:focus-visible>div]:outline [&:focus-visible>div]:outline-2 [&:focus-visible>div]:-outline-offset-2 [&:focus-visible>div]:outline-[var(--color-primary)]",
+        children: [
+          /* @__PURE__ */ jsxs(
+            "div",
+            {
+              ref: (el) => {
+                if (el) el.style.paddingInlineStart = `${(level - 1) * 1.25 + 0.25}rem`;
+              },
+              onClick: () => {
+                focus(node.id);
+                if (kids && !checkable) void toggle(node);
+                activate(node);
+              },
+              className: cn(
+                "flex min-h-control-sm cursor-default items-center gap-1.5 rounded-shape-control pe-2 text-body-md text-[var(--color-on-surface)]",
+                "hover:bg-[var(--color-surface-container-high)]",
+                !checkable && selected === node.id && "bg-[var(--color-secondary-container)] text-[var(--color-on-secondary-container)] hover:bg-[var(--color-secondary-container)]",
+                node.disabled && "cursor-not-allowed text-[var(--color-text-disabled)] hover:bg-transparent"
+              ),
+              children: [
+                /* @__PURE__ */ jsx(
+                  "span",
+                  {
+                    "aria-hidden": "true",
+                    onClick: (e) => {
+                      if (!kids) return;
+                      e.stopPropagation();
+                      focus(node.id);
+                      void toggle(node);
+                    },
+                    className: "inline-flex size-5 shrink-0 items-center justify-center text-[var(--color-on-surface-variant)]",
+                    children: loading === node.id ? /* @__PURE__ */ jsx(Spinner, { size: "xs" }) : kids ? /* @__PURE__ */ jsx(
+                      ChevronRight,
+                      {
+                        size: "xs",
+                        className: cn("transition-transform rtl:-scale-x-100", isOpen && "rotate-90 rtl:-rotate-90")
+                      }
+                    ) : null
+                  }
+                ),
+                checkable && /* @__PURE__ */ jsx(
+                  "span",
+                  {
+                    "aria-hidden": "true",
+                    className: cn(
+                      "inline-flex size-4 shrink-0 items-center justify-center rounded-[4px] border-2",
+                      isChecked || mixed ? "border-[var(--color-primary)] bg-[var(--color-primary)] text-[var(--color-on-primary)]" : "border-[var(--color-outline)]"
+                    ),
+                    children: isChecked ? /* @__PURE__ */ jsx(Check, { size: "xs" }) : mixed ? /* @__PURE__ */ jsx(Minus, { size: "xs" }) : null
+                  }
+                ),
+                node.icon && /* @__PURE__ */ jsx("span", { "aria-hidden": "true", className: "inline-flex shrink-0 text-[var(--color-on-surface-variant)]", children: node.icon }),
+                /* @__PURE__ */ jsx("span", { className: "truncate", children: node.label })
+              ]
+            }
+          ),
+          kids && isOpen && node.children && /* @__PURE__ */ jsx("ul", { role: "group", className: "m-0 list-none p-0", children: render(node.children, level + 1, node.id) })
+        ]
+      },
+      node.id
+    );
+  });
+  return /* @__PURE__ */ jsx(
+    "ul",
+    {
+      role: "tree",
+      "aria-multiselectable": checkable || void 0,
+      className: cn("m-0 flex list-none flex-col p-0", className),
+      ...aria,
+      children: render(nodes, 1, null)
+    }
+  );
+}
+export {
+  TreeView
+};

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

@@ -0,0 +1,2 @@
+export { TreeView } from './TreeView.js';
+export type { TreeViewProps, TreeNode } from './TreeView.js';

package/dist/components/TreeView/index.js

@@ -0,0 +1,4 @@
+import { TreeView } from "./TreeView.js";
+export {
+  TreeView
+};

package/dist/index.d.ts

@@ -226,6 +226,8 @@ export { DateTimePicker } from './components/DateTimePicker/index.js';
 export type { DateTimePickerProps } from './components/DateTimePicker/index.js';
 export { EventCalendar } from './components/EventCalendar/index.js';
 export type { EventCalendarProps, EventCalendarView, CalendarEvent, EventTone } from './components/EventCalendar/index.js';
+export { TreeView } from './components/TreeView/index.js';
+export type { TreeViewProps, TreeNode } from './components/TreeView/index.js';
 export type { OTPInputProps } from './components/OTPInput/index.js';
 export { DatePicker } from './components/DatePicker/index.js';
 export type { DatePickerProps } from './components/DatePicker/index.js';

package/dist/index.js

@@ -127,6 +127,7 @@ import { InlineEdit } from "./components/InlineEdit/index.js";
 import { TimePicker } from "./components/TimePicker/index.js";
 import { DateTimePicker } from "./components/DateTimePicker/index.js";
 import { EventCalendar } from "./components/EventCalendar/index.js";
+import { TreeView } from "./components/TreeView/index.js";
 import { DatePicker } from "./components/DatePicker/index.js";
 import { DateRangePicker } from "./components/DateRangePicker/index.js";
 import { todayIn } from "./components/DateRangePicker/index.js";
@@ -281,6 +282,7 @@ export {
   Tooltip,
   Provider as TooltipProvider,
   TopNav,
+  TreeView,
   VisuallyHidden,
   addonVariants,
   alertVariants,