nuxt-ui-tools 1.16.9 → 1.17.0

package/dist/runtime/table/types/tree.d.ts

@@ -0,0 +1,100 @@
+import type { ComputedRef } from 'vue';
+import type { GenericObject } from './utils.js';
+/**
+ * Keys of a row that hold an array of child rows.
+ *
+ * A row type with no such key (or an untyped one) falls back to `string`, so the option never
+ * becomes unusable.
+ */
+export type TableChildrenKey<TRow extends GenericObject> = [ChildrenKeys<TRow>] extends [never] ? string : ChildrenKeys<TRow>;
+type ChildrenKeys<TRow extends GenericObject> = {
+    [TKey in keyof TRow & string]-?: NonNullable<TRow[TKey]> extends readonly GenericObject[] ? TKey : never;
+}[keyof TRow & string];
+/**
+ * Turns the table into a tree: a row can hold child rows that open beneath it.
+ *
+ * The children travel with their parent in the source payload. Row ids (`rowKey`) must be unique
+ * across the whole tree, not only among siblings. Pagination, sorting, filters, search and
+ * summaries act on the top-level rows; a search or filter field may reach into the children with a
+ * dotted path such as `creditNotes.number`, which keeps the parent row.
+ *
+ * @example
+ * ```ts
+ * table: {
+ *   tree: { children: 'creditNotes', defaultExpanded: false },
+ * }
+ * ```
+ */
+export interface TableTreeSchema<TRow extends GenericObject = GenericObject> {
+    /** Key of each row that holds its child rows. A row with no children shows no chevron. */
+    children: TableChildrenKey<TRow>;
+    /**
+     * Which branches start open. `true` opens every branch, a number opens that many levels
+     * (`1` opens the top-level rows), `false` (the default) opens none. A branch the user or
+     * `table.expansion` has toggled keeps that state.
+     */
+    defaultExpanded?: boolean | number;
+    /**
+     * Which rows can be selected when the table has selection. `'all'` (the default) lets every row
+     * carry a checkbox, children included, each one independent of its parent; `'roots'` limits the
+     * checkboxes to the top-level rows. A row without a checkbox keeps its width, so nothing moves.
+     */
+    selectable?: 'all' | 'roots';
+}
+/** One loaded row with its place in the tree, resolved once per data change. */
+export interface TableTreeNode {
+    readonly id: string;
+    readonly row: GenericObject;
+    /** Top-level rows are depth `0`. */
+    readonly depth: number;
+    readonly parent: TableTreeNode | null;
+    /** Position of the top-level row this node sits under. */
+    readonly rootIndex: number;
+    readonly childNodes: readonly TableTreeNode[];
+    readonly hasChildren: boolean;
+    /** No later sibling follows: the rail stops at this row's elbow. */
+    readonly isLast: boolean;
+}
+/** The motion a row plays while a branch opens or closes. */
+export interface TableTreeMotion {
+    kind: 'enter' | 'leave';
+    /** Position in the stagger, so rows arrive one after another instead of all at once. */
+    order: number;
+}
+export interface TableTreeIndex {
+    readonly roots: readonly TableTreeNode[];
+    readonly byId: ReadonlyMap<string, TableTreeNode>;
+    /** Every node that has children. */
+    readonly branches: readonly TableTreeNode[];
+    readonly maxDepth: number;
+    /** Ids met more than once; the later rows are left out of the tree. */
+    readonly duplicateIds: readonly string[];
+}
+export interface TableExpansionState {
+    /** Whether the schema configured `table.tree`. */
+    enabled: boolean;
+    /** Ids of the loaded rows that are open right now, defaults included. */
+    expandedKeys: string[];
+    expandedCount: number;
+    /** Loaded rows that have children. */
+    branchCount: number;
+    allExpanded: boolean;
+}
+export interface TableExpansionApi {
+    state: ComputedRef<TableExpansionState>;
+    isExpanded: (rowId: string) => boolean;
+    /** Opens the given rows; ids without children are ignored. */
+    expand: (rowIds: string[]) => void;
+    collapse: (rowIds: string[]) => void;
+    /** Flips a row, or sets it when `expanded` is given. */
+    toggle: (options: {
+        rowId: string;
+        expanded?: boolean;
+    }) => void;
+    /** Opens every loaded branch, and every branch that loads later, until collapsed again. */
+    expandAll: () => void;
+    collapseAll: () => void;
+    /** Returns every branch to the schema's `defaultExpanded`. */
+    reset: () => void;
+}
+export {};

package/dist/runtime/table/utils/columns/defs.js

@@ -12,7 +12,9 @@ import {
   ROW_ACTIONS_COLUMN_ID,
   ROW_ACTIONS_COLUMN_WIDTH,
   SELECT_COLUMN_ID,
-  SELECT_COLUMN_WIDTH
+  SELECT_COLUMN_WIDTH,
+  TREE_COLUMN_ID,
+  TREE_COLUMN_WIDTH
 } from "./types.js";
 const LABEL_CHAR_WIDTH = 7.2;
 const LABEL_CHROME_WIDTH = 64;
@@ -21,7 +23,22 @@ function headerFloor(label, sortable) {
 }
 export function createColumnDefs(options) {
   const defs = [];
-  if (options.params.selection.selectionEnabled.value) {
+  if (options.params.tree.enabled.value) {
+    defs.push({
+      enableResizing: false,
+      id: TREE_COLUMN_ID,
+      maxSize: MAX_COLUMN_SIZE,
+      meta: {
+        canHide: false,
+        internal: "tree",
+        label: "",
+        render: () => null,
+        sortable: false
+      },
+      minSize: TREE_COLUMN_WIDTH,
+      size: TREE_COLUMN_WIDTH
+    });
+  } else if (options.params.selection.selectionEnabled.value) {
     const selection = createSelectionColumn({ params: options.params });
     defs.push({
       enableResizing: false,

package/dist/runtime/table/utils/columns/types.d.ts

@@ -1,9 +1,13 @@
 import type { ComputedRef, ShallowRef } from 'vue';
 import type { UseTableDataReturn } from '../../composables/use-table-data.js';
 import type { useTableState } from '../../composables/use-table-state.js';
+import type { useTableTree } from '../../composables/use-table-tree.js';
 import type { TableApi, TableColumnAlign, TableColumnPinned, GenericObject, TableLayout, TableSchemaView, TableRuntimeRecord, TableColumnSkeleton } from '../../types/index.js';
 export declare const SELECT_COLUMN_ID = "__select";
 export declare const SELECT_COLUMN_WIDTH = 44;
+export declare const TREE_COLUMN_ID = "__tree";
+/** The control column at depth zero; it grows from here by one gutter per level of depth. */
+export declare const TREE_COLUMN_WIDTH: number;
 export declare const ROW_ACTIONS_COLUMN_ID = "__row-actions";
 export declare const ROW_ACTIONS_COLUMN_WIDTH = 56;
 export type SchemaTableColumn = NonNullable<NonNullable<TableSchemaView['table']>['columns']>[number];
@@ -74,6 +78,7 @@ export interface UseTableColumnsParams {
     selection: TableColumnsSelectionState;
     tableLayout: ComputedRef<TableLayout>;
     tableApi: ShallowRef<TableApi<unknown> | null>;
+    tree: ReturnType<typeof useTableTree>;
 }
 export interface TableColumnRenderParams {
     column: SchemaTableColumn;
@@ -89,7 +94,7 @@ export interface TableCellRenderContext {
     tableApi: TableApi<unknown>;
     layout: TableLayout;
 }
-export type DataListColumnInternalKind = 'selection' | 'actions';
+export type DataListColumnInternalKind = 'selection' | 'tree' | 'actions';
 export interface DataListColumnMeta {
     label: string;
     icon?: string;

package/dist/runtime/table/utils/columns/types.js

@@ -1,5 +1,12 @@
+import { TREE_CHECK_WIDTH, TREE_LEAD, getTreeColumnWidth } from "../tree.js";
 export const SELECT_COLUMN_ID = "__select";
 export const SELECT_COLUMN_WIDTH = 44;
+export const TREE_COLUMN_ID = "__tree";
+export const TREE_COLUMN_WIDTH = getTreeColumnWidth({
+  check: TREE_CHECK_WIDTH.md,
+  lead: TREE_LEAD,
+  maxDepth: 0
+});
 export const ROW_ACTIONS_COLUMN_ID = "__row-actions";
 export const ROW_ACTIONS_COLUMN_WIDTH = 56;
 export const DEFAULT_COLUMN_SIZE = 150;

package/dist/runtime/table/utils/index.d.ts

@@ -13,4 +13,5 @@ export * from './resolved-filters.js';
 export * from './rows.js';
 export * from './schema.js';
 export * from './source-request.js';
+export * from './tree.js';
 export { tableSource } from './builders/table-source.js';

package/dist/runtime/table/utils/index.js

@@ -13,4 +13,5 @@ export * from "./resolved-filters.js";
 export * from "./rows.js";
 export * from "./schema.js";
 export * from "./source-request.js";
+export * from "./tree.js";
 export { tableSource } from "./builders/table-source.js";

package/dist/runtime/table/utils/tree.d.ts

@@ -0,0 +1,64 @@
+import type { GenericObject, TableTreeIndex, TableTreeNode } from '../types/index.js';
+/** Pixels one level of the tree adds: one rail gutter. The renderer hands the same number to CSS. */
+export declare const TREE_GUTTER_WIDTH = 16;
+/** The chevron's footprint, which a childless row keeps free so its rail lines up. */
+export declare const TREE_TOGGLE_WIDTH = 16;
+/** Between the chevron and the checkbox. */
+export declare const TREE_GAP = 6;
+/** Least space before the first gutter; the table's own left gutter wins when it is wider. */
+export declare const TREE_LEAD = 6;
+/** Clear space after the checkbox of the deepest row, so it never meets the column's edge. */
+export declare const TREE_TRAIL = 6;
+/** Width of a Nuxt UI checkbox box at each control size, which the tree cell always reserves. */
+export declare const TREE_CHECK_WIDTH: {
+    readonly lg: 18;
+    readonly md: 16;
+    readonly sm: 14;
+    readonly xl: 20;
+    readonly xs: 12;
+};
+/**
+ * The control column's width: lead, one gutter per level of the deepest loaded row, the chevron,
+ * the checkbox and a little room after it. Every row shares it, so the first data column starts at
+ * the same x on all of them and indentation happens inside the cell.
+ */
+export declare function getTreeColumnWidth(params: {
+    lead: number;
+    maxDepth: number;
+    check: number;
+}): number;
+/** Every row under `rows`, the rows themselves first, however deep and whether open or not. */
+export declare function flattenTreeRows(rows: readonly GenericObject[], childrenPath: string): GenericObject[];
+/**
+ * Indexes the loaded rows once per data change: every node knows its depth, its parent and its
+ * children, so toggling a branch never walks the source again. A node holds no per-row arrays,
+ * which keeps the index linear however deep the tree goes.
+ *
+ * Built with an explicit stack, so a deep tree cannot overflow the call stack, and the nested
+ * source rows are left untouched: nothing is copied, mapped or tagged.
+ */
+export declare function buildTableTree(params: {
+    rows: readonly GenericObject[];
+    childrenPath: string;
+    getRowId: (row: GenericObject, index: number) => string;
+}): TableTreeIndex;
+/** The rows from the top level down to `node`, inclusive. */
+export declare function getTreeLineage(node: TableTreeNode): TableTreeNode[];
+/**
+ * One flag per gutter between the top level and the row's own: whether the ancestor that gutter
+ * belongs to still has a sibling below, so its rail runs through the row. A rail is only drawn
+ * through a row where the answer is yes, which is what stops a branch at its last child.
+ */
+export declare function getTreeRails(node: TableTreeNode): boolean[];
+/**
+ * The rows that are on screen: every top-level row, then the children of each open branch.
+ *
+ * This replaces TanStack's expanded row model on purpose. That model materialises every
+ * descendant before the virtualizer sees a row; here only the visible rows exist, so closed
+ * branches cost nothing however large they are.
+ */
+export declare function flattenVisibleTree(roots: readonly TableTreeNode[], isExpanded: (node: TableTreeNode) => boolean): TableTreeNode[];
+/** The rows currently showing beneath `branch`, which follow it contiguously in `visible`. */
+export declare function getVisibleDescendants(visible: readonly TableTreeNode[], branch: TableTreeNode, limit?: number): TableTreeNode[];
+/** Whether `branch` starts open under a `defaultExpanded` setting. */
+export declare function isOpenByDefault(defaultExpanded: boolean | number, depth: number): boolean;

package/dist/runtime/table/utils/tree.js

@@ -0,0 +1,112 @@
+import { isObject } from "../../shared/utils/predicate.js";
+import { getTableRowValue } from "./rows.js";
+export const TREE_GUTTER_WIDTH = 16;
+export const TREE_TOGGLE_WIDTH = 16;
+export const TREE_GAP = 6;
+export const TREE_LEAD = 6;
+export const TREE_TRAIL = 6;
+export const TREE_CHECK_WIDTH = { lg: 18, md: 16, sm: 14, xl: 20, xs: 12 };
+export function getTreeColumnWidth(params) {
+  return params.lead + params.maxDepth * TREE_GUTTER_WIDTH + TREE_TOGGLE_WIDTH + TREE_GAP + params.check + TREE_TRAIL;
+}
+export function flattenTreeRows(rows, childrenPath) {
+  const flat = [];
+  const seen = /* @__PURE__ */ new Set();
+  const stack = [...rows].reverse();
+  for (let row = stack.pop(); row; row = stack.pop()) {
+    if (seen.has(row)) continue;
+    seen.add(row);
+    flat.push(row);
+    const children = readChildren(row, childrenPath);
+    for (let position = children.length - 1; position >= 0; position -= 1) {
+      const child = children[position];
+      if (child) stack.push(child);
+    }
+  }
+  return flat;
+}
+function readChildren(row, childrenPath) {
+  const value = getTableRowValue({ path: childrenPath, row });
+  if (!Array.isArray(value)) return [];
+  const children = [];
+  for (const item of value) if (isObject(item)) children.push(item);
+  return children;
+}
+export function buildTableTree(params) {
+  const byId = /* @__PURE__ */ new Map();
+  const branches = [];
+  const duplicateIds = [];
+  const roots = [];
+  let maxDepth = 0;
+  const stack = [{ parent: null, rows: params.rows }];
+  for (let frame = stack.pop(); frame; frame = stack.pop()) {
+    const depth = frame.parent ? frame.parent.depth + 1 : 0;
+    const siblings = frame.parent ? frame.parent.childNodes : roots;
+    const created = [];
+    const rootIndexBase = frame.parent?.rootIndex;
+    for (const [index, row] of frame.rows.entries()) {
+      const id = params.getRowId(row, index);
+      if (byId.has(id)) {
+        duplicateIds.push(id);
+        continue;
+      }
+      const children = readChildren(row, params.childrenPath);
+      const node = {
+        childNodes: [],
+        depth,
+        hasChildren: children.length > 0,
+        id,
+        isLast: index === frame.rows.length - 1,
+        parent: frame.parent,
+        rootIndex: rootIndexBase ?? index,
+        row
+      };
+      byId.set(id, node);
+      created.push({ children, node });
+      siblings.push(node);
+      if (depth > maxDepth) maxDepth = depth;
+      if (node.hasChildren) branches.push(node);
+    }
+    for (let position = created.length - 1; position >= 0; position -= 1) {
+      const entry = created[position];
+      if (entry?.node.hasChildren) stack.push({ parent: entry.node, rows: entry.children });
+    }
+  }
+  return { branches, byId, duplicateIds, maxDepth, roots };
+}
+export function getTreeLineage(node) {
+  const lineage = [];
+  for (let current = node; current; current = current.parent)
+    lineage.unshift(current);
+  return lineage;
+}
+export function getTreeRails(node) {
+  return getTreeLineage(node).slice(1, -1).map((ancestor) => !ancestor.isLast);
+}
+export function flattenVisibleTree(roots, isExpanded) {
+  const visible = [];
+  const stack = [...roots].reverse();
+  for (let node = stack.pop(); node; node = stack.pop()) {
+    visible.push(node);
+    if (!node.hasChildren || !isExpanded(node)) continue;
+    for (let position = node.childNodes.length - 1; position >= 0; position -= 1) {
+      const child = node.childNodes[position];
+      if (child) stack.push(child);
+    }
+  }
+  return visible;
+}
+export function getVisibleDescendants(visible, branch, limit = Number.POSITIVE_INFINITY) {
+  const start = visible.indexOf(branch);
+  if (start === -1) return [];
+  const descendants = [];
+  for (let index = start + 1; index < visible.length && descendants.length < limit; index += 1) {
+    const node = visible[index];
+    if (!node || node.depth <= branch.depth) break;
+    descendants.push(node);
+  }
+  return descendants;
+}
+export function isOpenByDefault(defaultExpanded, depth) {
+  return defaultExpanded === true || defaultExpanded !== false && depth < defaultExpanded;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nuxt-ui-tools",
-  "version": "1.16.9",
+  "version": "1.17.0",
   "description": "Nuxt module and runtime toolkit for UI-heavy Nuxt applications",
   "homepage": "https://github.com/ChronicStone/nuxt-ui-tools#readme",
   "bugs": "https://github.com/ChronicStone/nuxt-ui-tools/issues",