nuxt-ui-tools 1.16.10 → 1.17.0

package/dist/runtime/table/components/table/table-tree-header.vue

@@ -0,0 +1,66 @@
+<script setup>
+import { computed } from "vue";
+import { useUiToolsLocale } from "#ui-tools/i18n";
+import { useTableInternals } from "../../composables/use-table-internals";
+import TableSelectionControl from "./table-selection-control.vue";
+const { t } = useUiToolsLocale();
+const { selection, tree } = useTableInternals();
+const state = computed(() => tree.expansion.state.value);
+const label = computed(
+  () => state.value.allExpanded ? t("table.tree.collapseAll") : t("table.tree.expandAll")
+);
+const checkState = computed(
+  () => selection.allSelected.value ? true : selection.partiallySelected.value ? "indeterminate" : false
+);
+function toggle() {
+  if (state.value.allExpanded) tree.expansion.collapseAll();
+  else tree.expansion.expandAll();
+}
+</script>
+
+<template>
+  <div class="nut-dl-tree-head">
+    <span class="nut-dl-tree__node">
+      <button
+        v-if="state.branchCount > 0"
+        type="button"
+        class="nut-dl-tree__toggle"
+        :aria-label="label"
+        :title="label"
+        @click="toggle"
+      >
+        <svg viewBox="0 0 24 24" width="12" height="12" fill="none" aria-hidden="true">
+          <path
+            v-if="state.allExpanded"
+            d="m7 20 5-5 5 5M7 4l5 5 5-5"
+            stroke="currentColor"
+            stroke-width="2.5"
+            stroke-linecap="round"
+            stroke-linejoin="round"
+          />
+          <path
+            v-else
+            d="m7 15 5 5 5-5M7 9l5-5 5 5"
+            stroke="currentColor"
+            stroke-width="2.5"
+            stroke-linecap="round"
+            stroke-linejoin="round"
+          />
+        </svg>
+      </button>
+      <span v-else class="nut-dl-tree__slot" aria-hidden="true" />
+    </span>
+    <span class="nut-dl-tree__check">
+      <TableSelectionControl
+        v-if="selection.selectionEnabled.value"
+        :model-value="checkState"
+        :ariaLabel="t('table.tree.selectAll')"
+        @toggle="selection.toggleAllRows({ selected: !selection.allSelected.value })"
+      />
+    </span>
+  </div>
+</template>
+
+<style>
+.nut-dl-tree-head{align-items:center;display:flex;height:100%}
+</style>

package/dist/runtime/table/components/table/table-tree-header.vue.d.ts

@@ -0,0 +1,3 @@
+declare const __VLS_export: import("vue").DefineComponent<{}, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/runtime/table/composables/use-table-api.d.ts

@@ -8,12 +8,14 @@ import type { useTableLayout } from './use-table-layout.js';
 import type { useTablePagination } from './use-table-pagination.js';
 import type { useTableSelection } from './use-table-selection.js';
 import type { useTableState } from './use-table-state.js';
+import type { useTableTree } from './use-table-tree.js';
 export interface UseTableApiParams<TSchema = TableSchemaView> {
     runtimeSchema: ComputedRef<TableSchemaView>;
     publicSchema: ComputedRef<TSchema>;
     layout: ReturnType<typeof useTableLayout>;
     state: ReturnType<typeof useTableState>;
     selection: ReturnType<typeof useTableSelection>;
+    tree: ReturnType<typeof useTableTree>;
     controls: ReturnType<typeof useTableControls>;
     columns: ReturnType<typeof useTableColumns>;
     filters: ReturnType<typeof useTableFilters>;

package/dist/runtime/table/composables/use-table-api.js

@@ -85,6 +85,7 @@ export function useTableApi(params) {
     all() {
       reset.query();
       selection.clear();
+      params.tree.expansion.reset();
     },
     query() {
       const { defaultLayout } = params.runtimeSchema.value;
@@ -101,6 +102,7 @@ export function useTableApi(params) {
   };
   return {
     data,
+    expansion: params.tree.expansion,
     filters,
     layout: layoutApi,
     pagination,

package/dist/runtime/table/composables/use-table-internals.d.ts

@@ -593,6 +593,22 @@ declare function createTableInternals<TSchema>(options: {
         toggleSorting: (key: string) => void;
         visibleOrderedColumns: import("vue").ComputedRef<import("../utils/index.js").TableRuntimeColumn[]>;
     };
+    tree: {
+        enabled: import("vue").ComputedRef<boolean>;
+        expansion: import("../types/index.js").TableExpansionApi;
+        index: import("vue").ComputedRef<import("../types/index.js").TableTreeIndex>;
+        isExpanded: (rowId: string) => boolean;
+        isOnPath: (rowId: string) => boolean;
+        isSelectable: (node: import("../types/index.js").TableTreeNode) => boolean;
+        lightLineage: (rowId?: string) => void;
+        litUntil: (groupId: string) => number;
+        motionOf: (rowId: string) => import("../types/index.js").TableTreeMotion | undefined;
+        nodeOf: (rowId: string) => import("../types/index.js").TableTreeNode | undefined;
+        selectable: import("vue").ComputedRef<"all" | "roots">;
+        toggleRow: (rowId: string) => void;
+        visibleNodes: import("vue").ComputedRef<import("../types/index.js").TableTreeNode[]>;
+        visibleRows: import("vue").ComputedRef<object[]>;
+    };
 };
 declare function provideTableInternals(internals: TableInternals): void;
 declare function useProvideTableInternals<TSchema>(options: {
@@ -1189,6 +1205,22 @@ declare function useProvideTableInternals<TSchema>(options: {
         toggleSorting: (key: string) => void;
         visibleOrderedColumns: import("vue").ComputedRef<import("../utils/index.js").TableRuntimeColumn[]>;
     };
+    tree: {
+        enabled: import("vue").ComputedRef<boolean>;
+        expansion: import("../types/index.js").TableExpansionApi;
+        index: import("vue").ComputedRef<import("../types/index.js").TableTreeIndex>;
+        isExpanded: (rowId: string) => boolean;
+        isOnPath: (rowId: string) => boolean;
+        isSelectable: (node: import("../types/index.js").TableTreeNode) => boolean;
+        lightLineage: (rowId?: string) => void;
+        litUntil: (groupId: string) => number;
+        motionOf: (rowId: string) => import("../types/index.js").TableTreeMotion | undefined;
+        nodeOf: (rowId: string) => import("../types/index.js").TableTreeNode | undefined;
+        selectable: import("vue").ComputedRef<"all" | "roots">;
+        toggleRow: (rowId: string) => void;
+        visibleNodes: import("vue").ComputedRef<import("../types/index.js").TableTreeNode[]>;
+        visibleRows: import("vue").ComputedRef<object[]>;
+    };
 };
 declare function useTableInternals(): {
     actions: {
@@ -1782,6 +1814,22 @@ declare function useTableInternals(): {
         toggleSorting: (key: string) => void;
         visibleOrderedColumns: import("vue").ComputedRef<import("../utils/index.js").TableRuntimeColumn[]>;
     };
+    tree: {
+        enabled: import("vue").ComputedRef<boolean>;
+        expansion: import("../types/index.js").TableExpansionApi;
+        index: import("vue").ComputedRef<import("../types/index.js").TableTreeIndex>;
+        isExpanded: (rowId: string) => boolean;
+        isOnPath: (rowId: string) => boolean;
+        isSelectable: (node: import("../types/index.js").TableTreeNode) => boolean;
+        lightLineage: (rowId?: string) => void;
+        litUntil: (groupId: string) => number;
+        motionOf: (rowId: string) => import("../types/index.js").TableTreeMotion | undefined;
+        nodeOf: (rowId: string) => import("../types/index.js").TableTreeNode | undefined;
+        selectable: import("vue").ComputedRef<"all" | "roots">;
+        toggleRow: (rowId: string) => void;
+        visibleNodes: import("vue").ComputedRef<import("../types/index.js").TableTreeNode[]>;
+        visibleRows: import("vue").ComputedRef<object[]>;
+    };
 };
 export type TableInternals = ReturnType<typeof createTableInternals>;
 export { createTableInternals, provideTableInternals, useProvideTableInternals, useTableInternals };

package/dist/runtime/table/composables/use-table-internals.js

@@ -14,6 +14,7 @@ import { useTableSelection } from "./use-table-selection.js";
 import { useTableStartup } from "./use-table-startup.js";
 import { useTableState } from "./use-table-state.js";
 import { useTableSummaries } from "./use-table-summaries.js";
+import { useTableTree } from "./use-table-tree.js";
 function createTableInternals(options) {
   const publicSchema = computed(() => resolveSchemaSource({ schema: options.rawSchema }));
   const schema = computed(() => publicSchema.value);
@@ -29,10 +30,15 @@ function createTableInternals(options) {
     startup,
     state
   });
-  const selection = useTableSelection({
+  const tree = useTableTree({
     queryContent,
     schema
   });
+  const selection = useTableSelection({
+    queryContent,
+    schema,
+    tree
+  });
   const controls = useTableControls({
     layout,
     schema
@@ -55,7 +61,8 @@ function createTableInternals(options) {
     selection,
     state,
     tableApi,
-    tableLayout: controls.tableLayout
+    tableLayout: controls.tableLayout,
+    tree
   });
   const summaries = useTableSummaries({
     queryContent,
@@ -79,7 +86,8 @@ function createTableInternals(options) {
     queryContent,
     runtimeSchema: schema,
     selection,
-    state
+    state,
+    tree
   });
   if (!tableApi.value) {
     throw new Error("Failed to initialize table API");
@@ -106,7 +114,8 @@ function createTableInternals(options) {
     startup,
     summaries,
     tableApi: tableApi.value,
-    tableColumns
+    tableColumns,
+    tree
   };
 }
 const TABLE_INTERNALS_KEY = Symbol("nuxt-ui-tools.table.internals");

package/dist/runtime/table/composables/use-table-selection.d.ts

@@ -1,9 +1,11 @@
 import type { ComputedRef } from 'vue';
 import type { GenericObject, TableSchemaView } from '../types/index.js';
 import type { useTableData } from './use-table-data.js';
+import type { useTableTree } from './use-table-tree.js';
 export interface UseTableSelectionParams {
     schema: ComputedRef<TableSchemaView>;
     queryContent: ReturnType<typeof useTableData>;
+    tree: ReturnType<typeof useTableTree>;
 }
 export declare function useTableSelection(options: UseTableSelectionParams): {
     allSelected: ComputedRef<boolean>;

package/dist/runtime/table/composables/use-table-selection.js

@@ -1,10 +1,16 @@
 import { computed, ref, watch } from "vue";
-import { hasConfiguredTableActions, resolveTableRowId } from "../utils/index.js";
+import { flattenTreeRows, hasConfiguredTableActions, resolveTableRowId } from "../utils/index.js";
 export function useTableSelection(options) {
   const selectedKeys = ref([]);
   const bulkScope = ref("selection");
   const lastTouchedRowId = ref(null);
-  const pageRows = computed(() => options.queryContent.data.value.rows);
+  function withTreeRows(rows) {
+    const childrenPath = options.schema.value.table?.tree?.children;
+    return childrenPath && options.tree.selectable.value === "all" ? flattenTreeRows(rows, childrenPath) : rows;
+  }
+  const pageRows = computed(
+    () => withTreeRows(options.queryContent.data.value.rows)
+  );
   const selectionEnabled = computed(() => {
     const mode = options.schema.value.table?.selection ?? options.schema.value.selection?.mode ?? "auto";
     if (mode !== "auto") {
@@ -19,7 +25,7 @@ export function useTableSelection(options) {
     return options.schema.value.selection?.scope ?? "all";
   });
   const selectionRows = computed(
-    () => selectionScope.value === "all" ? options.queryContent.selectableRows.value : pageRows.value
+    () => selectionScope.value === "all" ? withTreeRows(options.queryContent.selectableRows.value) : pageRows.value
   );
   const pageRowIds = computed(() => pageRows.value.map((row, index) => getRowId({ index, row })));
   const scopeRowIds = computed(
@@ -111,15 +117,18 @@ export function useTableSelection(options) {
     }
     lastTouchedRowId.value = params.rowId;
   }
+  const rangeRowIds = computed(
+    () => options.tree.enabled.value ? options.tree.visibleNodes.value.filter((node) => options.tree.isSelectable(node)).map((node) => node.id) : scopeRowIds.value
+  );
   function getRangeRowIds(params) {
-    const anchorIndex = scopeRowIds.value.indexOf(params.anchorRowId);
-    const targetIndex = scopeRowIds.value.indexOf(params.targetRowId);
+    const anchorIndex = rangeRowIds.value.indexOf(params.anchorRowId);
+    const targetIndex = rangeRowIds.value.indexOf(params.targetRowId);
     if (anchorIndex === -1 || targetIndex === -1) {
       return [params.targetRowId];
     }
     const start = Math.min(anchorIndex, targetIndex);
     const end = Math.max(anchorIndex, targetIndex);
-    return scopeRowIds.value.slice(start, end + 1);
+    return rangeRowIds.value.slice(start, end + 1);
   }
   watch(
     scopeRowIds,

package/dist/runtime/table/composables/use-table-tree.d.ts

@@ -0,0 +1,36 @@
+import type { ComputedRef } from 'vue';
+import type { TableExpansionApi, TableSchemaView, TableTreeIndex, TableTreeMotion, TableTreeNode } from '../types/index.js';
+import type { UseTableDataReturn } from './use-table-data.js';
+export interface UseTableTreeParams {
+    schema: ComputedRef<TableSchemaView>;
+    queryContent: Pick<UseTableDataReturn, 'data'>;
+}
+/**
+ * Owns tree rows: which rows are open, the flat list of rows that are on screen, and the motion
+ * of a branch opening or closing.
+ *
+ * Expansion is a baseline plus per-row overrides rather than a set of open ids. The baseline is
+ * the schema's `defaultExpanded` (or what `expandAll` / `collapseAll` last chose), so rows that
+ * load later, such as the next cursor page, follow it without being enumerated; an override only
+ * exists for a row someone actually toggled, and is dropped again if it matches the baseline.
+ *
+ * TanStack's expanded row model is deliberately not used: it materialises every descendant before
+ * the virtualizer sees a row. The nested source rows stay as they are, `visibleNodes` flattens
+ * only what is open, and that list is what the renderer virtualizes.
+ */
+export declare function useTableTree(params: UseTableTreeParams): {
+    enabled: ComputedRef<boolean>;
+    expansion: TableExpansionApi;
+    index: ComputedRef<TableTreeIndex>;
+    isExpanded: (rowId: string) => boolean;
+    isOnPath: (rowId: string) => boolean;
+    isSelectable: (node: TableTreeNode) => boolean;
+    lightLineage: (rowId?: string) => void;
+    litUntil: (groupId: string) => number;
+    motionOf: (rowId: string) => TableTreeMotion | undefined;
+    nodeOf: (rowId: string) => TableTreeNode | undefined;
+    selectable: ComputedRef<"all" | "roots">;
+    toggleRow: (rowId: string) => void;
+    visibleNodes: ComputedRef<TableTreeNode[]>;
+    visibleRows: ComputedRef<object[]>;
+};

package/dist/runtime/table/composables/use-table-tree.js

@@ -0,0 +1,199 @@
+import { usePreferredReducedMotion } from "@vueuse/core";
+import { computed, onScopeDispose, reactive, ref, shallowRef } from "vue";
+import { resolveTableRowId } from "../utils/rows.js";
+import {
+  buildTableTree,
+  flattenVisibleTree,
+  getTreeLineage,
+  getVisibleDescendants,
+  isOpenByDefault
+} from "../utils/tree.js";
+const CONCEAL_MS = 120;
+const REVEAL_MS = 190;
+const STAGGER_MS = 24;
+const MOTION_ROW_LIMIT = 24;
+const STAGGER_ROW_LIMIT = 8;
+const EMPTY_INDEX = {
+  branches: [],
+  byId: /* @__PURE__ */ new Map(),
+  duplicateIds: [],
+  maxDepth: 0,
+  roots: []
+};
+export function useTableTree(params) {
+  const reducedMotion = usePreferredReducedMotion();
+  const config = computed(() => params.schema.value.table?.tree);
+  const enabled = computed(() => Boolean(config.value));
+  const defaultExpanded = computed(() => config.value?.defaultExpanded ?? false);
+  const selectable = computed(() => config.value?.selectable ?? "all");
+  const index = computed(() => {
+    const tree = config.value;
+    if (!tree) return EMPTY_INDEX;
+    const built = buildTableTree({
+      childrenPath: tree.children,
+      getRowId: (row, position) => String(resolveTableRowId({ index: position, row, rowKey: params.schema.value.rowKey })),
+      rows: params.queryContent.data.value.rows
+    });
+    if (built.duplicateIds.length && process.env.NODE_ENV !== "production")
+      console.warn(
+        `[nuxt-ui-tools] Tree rows must have unique ids across the whole tree; left out duplicates of: ${built.duplicateIds.slice(0, 5).join(", ")}`
+      );
+    return built;
+  });
+  const baseline = ref(null);
+  const overrides = reactive(/* @__PURE__ */ new Map());
+  const closing = reactive(/* @__PURE__ */ new Set());
+  function openByDefault(node) {
+    return isOpenByDefault(baseline.value ?? defaultExpanded.value, node.depth);
+  }
+  function isNodeOpen(node) {
+    return node.hasChildren && (overrides.get(node.id) ?? openByDefault(node));
+  }
+  function setNodeOpen(node, open) {
+    if (!node.hasChildren) return;
+    if (open === openByDefault(node)) overrides.delete(node.id);
+    else overrides.set(node.id, open);
+  }
+  function isExpanded(rowId) {
+    const node = index.value.byId.get(rowId);
+    return node !== void 0 && isNodeOpen(node) && !closing.has(rowId);
+  }
+  function nodeOf(rowId) {
+    return index.value.byId.get(rowId);
+  }
+  function isSelectable(node) {
+    return selectable.value === "all" || node.depth === 0;
+  }
+  function setExpanded(rowIds, open) {
+    for (const rowId of rowIds) {
+      const node = index.value.byId.get(rowId);
+      if (node) setNodeOpen(node, open);
+    }
+  }
+  function setAll(open) {
+    settle();
+    baseline.value = open;
+    overrides.clear();
+  }
+  const visibleNodes = computed(() => flattenVisibleTree(index.value.roots, isNodeOpen));
+  const visibleRows = computed(() => visibleNodes.value.map((node) => node.row));
+  const motion = shallowRef(null);
+  let timer;
+  let closingNode;
+  function motionOf(rowId) {
+    return motion.value?.get(rowId);
+  }
+  function playMotion(kind, branch) {
+    const rows = getVisibleDescendants(visibleNodes.value, branch, MOTION_ROW_LIMIT);
+    motion.value = new Map(
+      rows.map((node, order) => [
+        node.id,
+        { kind, order: Math.min(order, STAGGER_ROW_LIMIT) }
+      ])
+    );
+    return rows.length;
+  }
+  function settle() {
+    clearTimeout(timer);
+    if (closingNode) {
+      setNodeOpen(closingNode, false);
+      closing.delete(closingNode.id);
+      closingNode = void 0;
+    }
+    motion.value = null;
+  }
+  function toggleRow(rowId) {
+    const node = index.value.byId.get(rowId);
+    if (!node?.hasChildren) return;
+    if (closingNode === node) {
+      clearTimeout(timer);
+      closing.delete(rowId);
+      closingNode = void 0;
+      motion.value = null;
+      return;
+    }
+    settle();
+    const open = isNodeOpen(node);
+    if (reducedMotion.value === "reduce") {
+      setNodeOpen(node, !open);
+      return;
+    }
+    if (!open) {
+      setNodeOpen(node, true);
+      const revealed = playMotion("enter", node);
+      timer = setTimeout(
+        () => motion.value = null,
+        REVEAL_MS + Math.min(revealed, STAGGER_ROW_LIMIT) * STAGGER_MS
+      );
+      return;
+    }
+    if (!playMotion("leave", node)) {
+      setNodeOpen(node, false);
+      return;
+    }
+    closingNode = node;
+    closing.add(rowId);
+    timer = setTimeout(settle, CONCEAL_MS);
+  }
+  onScopeDispose(() => clearTimeout(timer));
+  const flatIndexById = computed(
+    () => new Map(visibleNodes.value.map((node, position) => [node.id, position]))
+  );
+  const litUntilByGroup = reactive(/* @__PURE__ */ new Map());
+  const onPath = reactive(/* @__PURE__ */ new Set());
+  function lightLineage(rowId) {
+    const node = rowId === void 0 ? void 0 : index.value.byId.get(rowId);
+    const lineage = node ? getTreeLineage(node).map((entry) => entry.id) : [];
+    const groups = lineage.slice(0, -1);
+    for (const group of litUntilByGroup.keys())
+      if (!groups.includes(group)) litUntilByGroup.delete(group);
+    for (const group of onPath) if (!groups.includes(group)) onPath.delete(group);
+    for (const [position, group] of groups.entries()) {
+      const child = lineage[position + 1];
+      litUntilByGroup.set(group, child === void 0 ? -1 : flatIndexById.value.get(child) ?? -1);
+      onPath.add(group);
+    }
+  }
+  function litUntil(groupId) {
+    return litUntilByGroup.get(groupId) ?? -1;
+  }
+  function isOnPath(rowId) {
+    return onPath.has(rowId);
+  }
+  const expansion = {
+    collapse: (rowIds) => setExpanded(rowIds, false),
+    collapseAll: () => setAll(false),
+    expand: (rowIds) => setExpanded(rowIds, true),
+    expandAll: () => setAll(true),
+    isExpanded,
+    reset: () => setAll(null),
+    state: computed(() => {
+      const { branches } = index.value;
+      const expandedKeys = branches.filter(isNodeOpen).map((node) => node.id);
+      return {
+        allExpanded: branches.length > 0 && expandedKeys.length === branches.length,
+        branchCount: branches.length,
+        enabled: enabled.value,
+        expandedCount: expandedKeys.length,
+        expandedKeys
+      };
+    }),
+    toggle: ({ expanded, rowId }) => setExpanded([rowId], expanded ?? !isExpanded(rowId))
+  };
+  return {
+    enabled,
+    expansion,
+    index,
+    isExpanded,
+    isOnPath,
+    isSelectable,
+    lightLineage,
+    litUntil,
+    motionOf,
+    nodeOf,
+    selectable,
+    toggleRow,
+    visibleNodes,
+    visibleRows
+  };
+}

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

@@ -10,4 +10,5 @@ export type * from './schema';
 export type * from './source';
 export type * from './state';
 export type * from './table-api';
+export type * from './tree';
 export type * from './utils';

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

@@ -1,4 +1,5 @@
 import type { TableColumnCollection, TableSummaryRequest, TableSummaryScope, TableSummaryValue } from './columns.js';
+import type { TableTreeSchema } from './tree.js';
 import type { GenericObject, TableDefaultSort, TableGridSortOption, TableLayout, TableRowRenderParams, RenderableType, TableSortKey, TableTextValue } from './utils.js';
 export interface TablePersistenceOptions {
     state?: boolean;
@@ -53,8 +54,8 @@ export interface TableGridSchema<TRow extends GenericObject = GenericObject, TCo
 export interface TableTableSchema<TRow extends GenericObject = GenericObject, TContext extends GenericObject = GenericObject, TPageContext extends GenericObject = GenericObject, TSortKey extends string = TableSortKey<TRow>, TData = unknown> {
     enabled?: boolean | string | (() => boolean | string);
     columns?: TableColumnCollection<TRow, TContext, TPageContext, string, TSortKey, TData>;
-    treeMode?: boolean;
-    childrenKey?: TableSortKey<TRow>;
+    /** Lets rows hold child rows that open beneath them. See `TableTreeSchema`. */
+    tree?: TableTreeSchema<TRow>;
     defaultSorting?: TableDefaultSort<TSortKey>;
     selection?: boolean | 'auto';
     summaries?: TableSummariesSchema<TRow>;

package/dist/runtime/table/types/table-api.d.ts

@@ -3,6 +3,7 @@ import type { useTableData } from '../composables/use-table-data.js';
 import type { useTablePagination } from '../composables/use-table-pagination.js';
 import type { TableFilterState } from './query-state.js';
 import type { TableSchemaView } from './schema.js';
+import type { TableExpansionApi } from './tree.js';
 import type { ExtractTableContextData, ExtractTablePageContextData, ExtractTableRow, TableLayout, TablePaginationState, TableSortingDirection, TableSortingRule } from './utils.js';
 export interface PublicTableQueryState {
     layout: TableLayout;
@@ -143,6 +144,11 @@ export interface TableApi<TSchema = TableSchemaView> {
         }) => void;
         isSelected: (rowId: string) => boolean;
     };
+    /**
+     * Open and close tree rows. With no `table.tree` in the schema, `state.enabled` is `false` and
+     * nothing here has an effect.
+     */
+    expansion: TableExpansionApi;
     reset: {
         query: () => void;
         all: () => void;

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