@cueplusplus/ui 0.13.0

package/dist/instruments/data-row.js

@@ -0,0 +1,151 @@
+"use client";
+import { cn } from "../lib/cn.js";
+import { activateRowFromClick, activateRowFromKeyDown, dataRowVariants } from "./_data-row.js";
+import * as React from "react";
+import { jsx } from "react/jsx-runtime";
+//#region src/instruments/data-row.tsx
+/**
+* The roles that carry `aria-expanded`, per ARIA 1.2's own "supported in roles"
+* list, filtered to the ones a row could plausibly be given.
+*
+* The absent case is the one that matters: no `role` at all. A `<div>` is
+* `generic`, `generic` supports only the globals, and every engine drops an
+* `aria-expanded` it finds there rather than exposing a state — so emitting it
+* anyway buys nothing and costs a critical axe violation.
+*/
+const ROLES_SUPPORTING_EXPANDED = /* @__PURE__ */ new Set([
+	"application",
+	"button",
+	"checkbox",
+	"columnheader",
+	"combobox",
+	"grid",
+	"gridcell",
+	"link",
+	"listbox",
+	"menuitem",
+	"menuitemcheckbox",
+	"menuitemradio",
+	"row",
+	"rowheader",
+	"searchbox",
+	"switch",
+	"tab",
+	"table",
+	"textbox",
+	"treeitem"
+]);
+/**
+* The dense interactive row, as one anatomy three surfaces share.
+*
+* `Ledger`, a grouped `Table` and `DataTree` are three drawings of the same row
+* model, and this is the model: a marker, a label, a description, tags, a
+* figure, and a trailing action cluster that is only there when you are looking
+* at the row. Composing them yourself — rather than passing a `columns` array —
+* is what keeps the primitive domain-neutral: a corpus of skills and a rig of
+* fixtures need the same six slots and completely different columns.
+*
+* The slots are thin: each is a `<span>` with a `data-slot`, the type and
+* truncation rule for its column, and nothing else. They may be used inside a
+* `DataTree` row and inside a `Table.Cell` too — `Table.Row` carries the same
+* `group/data-row` name, so `DataRow.Actions` reveals in the table idiom
+* without a second implementation.
+*
+* @example
+* <DataRow.Root interactive onActivate={() => open(skill)}>
+*   <DataRow.Marker><StatusDot tone="ok" /></DataRow.Marker>
+*   <DataRow.Label>{skill.name}</DataRow.Label>
+*   <DataRow.Meta>{skill.installs}</DataRow.Meta>
+* </DataRow.Root>
+*/
+const DataRow = {
+	Root: React.forwardRef(function DataRowRoot({ className, interactive = false, selected = false, disabled = false, onActivate, disclosure, onClick, onKeyDown, role, ...elementProps }, ref) {
+		const expandable = role !== void 0 && ROLES_SUPPORTING_EXPANDED.has(role);
+		const activate = React.useCallback(() => {
+			if (!disabled) onActivate?.();
+		}, [disabled, onActivate]);
+		const handleClick = React.useCallback((event) => {
+			onClick?.(event);
+			if (interactive) activateRowFromClick(event, activate);
+		}, [
+			activate,
+			interactive,
+			onClick
+		]);
+		const handleKeyDown = React.useCallback((event) => {
+			onKeyDown?.(event);
+			if (interactive) activateRowFromKeyDown(event, activate);
+		}, [
+			activate,
+			interactive,
+			onKeyDown
+		]);
+		return /* @__PURE__ */ jsx("div", {
+			ref,
+			...elementProps,
+			role,
+			"data-slot": "data-row",
+			"data-selected": selected ? "" : void 0,
+			"data-disabled": disabled ? "" : void 0,
+			"data-expanded": disclosure?.expanded === true ? "" : void 0,
+			tabIndex: interactive && !disabled ? 0 : void 0,
+			"aria-expanded": disclosure === void 0 || !expandable ? void 0 : disclosure.expanded,
+			"aria-controls": disclosure?.controls,
+			"aria-disabled": disabled ? true : void 0,
+			onClick: handleClick,
+			onKeyDown: handleKeyDown,
+			className: cn(dataRowVariants({ interactive }), className)
+		});
+	}),
+	Marker: React.forwardRef(function DataRowMarker({ className, ...elementProps }, ref) {
+		return /* @__PURE__ */ jsx("span", {
+			ref,
+			"data-slot": "data-row-marker",
+			className: cn("flex shrink-0 items-center", className),
+			...elementProps
+		});
+	}),
+	Label: React.forwardRef(function DataRowLabel({ className, ...elementProps }, ref) {
+		return /* @__PURE__ */ jsx("span", {
+			ref,
+			"data-slot": "data-row-label",
+			className: cn("min-w-0 truncate text-fg", className),
+			...elementProps
+		});
+	}),
+	Description: React.forwardRef(function DataRowDescription({ className, ...elementProps }, ref) {
+		return /* @__PURE__ */ jsx("span", {
+			ref,
+			"data-slot": "data-row-description",
+			className: cn("min-w-0 truncate text-(length:--cue-text-label) text-fg-muted", className),
+			...elementProps
+		});
+	}),
+	Tags: React.forwardRef(function DataRowTags({ className, ...elementProps }, ref) {
+		return /* @__PURE__ */ jsx("span", {
+			ref,
+			"data-slot": "data-row-tags",
+			className: cn("flex min-w-0 items-center gap-(--cue-space-1)", className),
+			...elementProps
+		});
+	}),
+	Meta: React.forwardRef(function DataRowMeta({ className, ...elementProps }, ref) {
+		return /* @__PURE__ */ jsx("span", {
+			ref,
+			"data-slot": "data-row-meta",
+			className: cn("shrink-0 tabular-nums text-fg-subtle", className),
+			...elementProps
+		});
+	}),
+	Actions: React.forwardRef(function DataRowActions({ className, ...elementProps }, ref) {
+		return /* @__PURE__ */ jsx("span", {
+			ref,
+			"data-slot": "data-row-actions",
+			"data-stop": "",
+			className: cn("invisible inline-flex shrink-0 items-center gap-(--cue-space-1) [&>*]:shrink-0", "group-hover/data-row:visible group-focus-within/data-row:visible group-data-[selected]/data-row:visible", "[@media(hover:none)]:visible", className),
+			...elementProps
+		});
+	})
+};
+//#endregion
+export { DataRow };

package/dist/instruments/data-table.d.ts

@@ -0,0 +1,168 @@
+import * as React from "react";
+import { ColumnHelper, ReactTable, RowData, TableOptions, flexRender } from "@tanstack/react-table";
+//#region src/instruments/data-table.d.ts
+/**
+ * The console table recipe. Not a component — deliberately.
+ *
+ * A `<DataTable columns={…} data={…} />` monolith has to own the markup of
+ * every cell, every header and every empty state, and the first column that
+ * needs a `Chip` or a `TwoStepButton` in it starts a prop-drilling arms race
+ * that ends with a component nobody can read. TanStack v9's whole point is that
+ * the markup stays yours and only the *logic* is shared, so what this module
+ * ships is the wiring:
+ *
+ * - {@link cueTableFeatures} — one opt-in feature set, so v9 can tree-shake
+ *   everything the console does not use (grouping, faceting, pinning,
+ *   virtualised column sizing).
+ * - {@link useCueTable} — that feature set, pre-bound, with sensible console
+ *   defaults.
+ * - {@link createCueColumnHelper} — the column helper with the features
+ *   already applied, so column defs infer.
+ * - {@link DataTableToolbar} / {@link DataTablePagination} — the two pieces of
+ *   chrome every table needs and nobody enjoys writing twice.
+ *
+ * The rows render through the Phase 1 `Table`. There is a fully worked example
+ * in `test/instruments/data-table.test.tsx`.
+ *
+ * Ships from `@cueplusplus/ui/instruments/data-table`: `@tanstack/react-table`
+ * is an optional peer, and the core bundle must not require it.
+ */
+/**
+ * Sorting, column filtering, global filtering and pagination — and nothing
+ * else.
+ *
+ * Named functions are registered individually rather than by spreading the
+ * built-in registries, because spreading puts every sort and filter
+ * implementation in the bundle whether or not a column names one.
+ */
+declare const cueTableFeatures: {
+  columnFilteringFeature: import("@tanstack/react-table").TableFeature;
+  globalFilteringFeature: import("@tanstack/react-table").TableFeature;
+  rowPaginationFeature: import("@tanstack/react-table").TableFeature;
+  rowSortingFeature: import("@tanstack/react-table").TableFeature;
+  filteredRowModel: (table: import("@tanstack/react-table").Table<any, any>) => () => import("@tanstack/react-table").RowModel<any, any>;
+  paginatedRowModel: (table: import("@tanstack/react-table").Table<any, any>) => () => import("@tanstack/react-table").RowModel<any, any>;
+  sortedRowModel: (table: import("@tanstack/react-table").Table<any, any>) => () => import("@tanstack/react-table").RowModel<any, any>;
+  filterFns: {
+    includesString: import("@tanstack/react-table").CreatedFilterFn<any, any>;
+    inNumberRange: import("@tanstack/react-table").CreatedFilterFn<any, any>;
+  };
+  sortFns: {
+    alphanumeric: import("@tanstack/react-table").CreatedSortFn<any, any>;
+    basic: import("@tanstack/react-table").CreatedSortFn<any, any>;
+    datetime: import("@tanstack/react-table").CreatedSortFn<any, any>;
+    text: import("@tanstack/react-table").CreatedSortFn<any, any>;
+  };
+};
+/** The feature set every `useCueTable` instance carries. */
+type CueTableFeatures = typeof cueTableFeatures;
+/** A table instance produced by {@link useCueTable}. */
+type CueTable<TData extends RowData> = ReactTable<CueTableFeatures, TData>;
+/** Options for {@link useCueTable} — TanStack's, minus the features it supplies. */
+interface UseCueTableOptions<TData extends RowData> extends Omit<TableOptions<CueTableFeatures, TData>, "features"> {}
+/**
+ * A TanStack v9 table wired for the console.
+ *
+ * Adds one default on top of the feature set: `globalFilterFn: "includesString"`,
+ * which is what a single search box over a console table always means. Override
+ * it, or any other option, by passing it.
+ *
+ * @param options - Everything `useTable` takes except `features`.
+ * @returns The table instance, ready to render through `Table`.
+ * @example
+ * const table = useCueTable({ data, columns, state: { globalFilter }, onGlobalFilterChange });
+ */
+declare function useCueTable<TData extends RowData>(options: UseCueTableOptions<TData>): CueTable<TData>;
+/**
+ * A column helper with {@link cueTableFeatures} already bound.
+ *
+ * @returns TanStack's `accessor` / `display` / `group` / `columns` builders.
+ * @example
+ * const helper = createCueColumnHelper<Fixture>();
+ * const columns = [helper.accessor("name", { header: "Fixture" })];
+ */
+declare function createCueColumnHelper<TData extends RowData>(): ColumnHelper<CueTableFeatures, TData>;
+interface DataTableToolbarProps extends Omit<React.ComponentPropsWithoutRef<"div">, "onChange"> {
+  /** The current query. Pair it with `onValueChange` and the table's global filter. */
+  value?: string;
+  /** Fired on every keystroke in the search box. */
+  onValueChange?: (value: string) => void;
+  /** Placeholder for the search box. Defaults to `"Filter…"`. */
+  placeholder?: string;
+  /** Accessible name for the search box. Defaults to `"Filter rows"`. */
+  searchLabel?: string;
+  /** Rows currently matching. Shown as `count/total` when both are given. */
+  count?: number;
+  /** Rows before filtering. */
+  total?: number;
+  /** Trailing controls — a column picker, an export button. */
+  children?: React.ReactNode;
+}
+/**
+ * The strip above a table: one search box, a match count, your controls.
+ *
+ * The count is the part worth having as a component. "12/340" next to a filter
+ * box is the difference between "the table is empty" and "the filter is too
+ * tight", and it is the first thing left out of a hand-rolled toolbar.
+ *
+ * @example
+ * <DataTableToolbar value={q} onValueChange={setQ} count={table.getRowCount()} total={data.length}>
+ *   <Button variant="ghost" size="sm">Export</Button>
+ * </DataTableToolbar>
+ */
+declare const DataTableToolbar: React.ForwardRefExoticComponent<DataTableToolbarProps & React.RefAttributes<HTMLDivElement>>;
+/**
+ * The slice of a table instance the pager reads.
+ *
+ * Structural rather than generic so `DataTablePagination` never has to be
+ * parameterised by `TData` — and so a server-paginated table that is not a
+ * TanStack instance at all can still use the control by supplying these seven
+ * members.
+ */
+interface DataTablePager {
+  getPageCount: () => number;
+  getRowCount: () => number;
+  getCanPreviousPage: () => boolean;
+  getCanNextPage: () => boolean;
+  firstPage: () => void;
+  previousPage: () => void;
+  nextPage: () => void;
+  lastPage: () => void;
+  readonly state: {
+    readonly pagination?: {
+      readonly pageIndex: number;
+      readonly pageSize: number;
+    };
+  };
+}
+/** Names for the four pager buttons, for translation. */
+interface DataTablePaginationLabels {
+  first: string;
+  previous: string;
+  next: string;
+  last: string;
+}
+interface DataTablePaginationProps extends Omit<React.ComponentPropsWithoutRef<"div">, "children"> {
+  /** The table instance from {@link useCueTable}, or anything with the same seven members. */
+  table: DataTablePager;
+  /** Accessible names for the four buttons. */
+  labels?: Partial<DataTablePaginationLabels>;
+  /** Render the position readout. Defaults to `"2 / 7"`. */
+  formatPosition?: (page: number, pages: number) => string;
+  /** Render the row count. Defaults to `"340 rows"`. */
+  formatRowCount?: (rows: number) => string;
+}
+/**
+ * The pager: four buttons, the position, and the row count.
+ *
+ * First and last are present because a console table is often sorted to put the
+ * interesting row at one end, and stepping there one page at a time is not a
+ * navigation strategy. Every button is an `IconButton` with a real accessible
+ * name — an arrow glyph alone announces as nothing.
+ *
+ * @example
+ * <DataTablePagination table={table} />
+ */
+declare const DataTablePagination: React.ForwardRefExoticComponent<DataTablePaginationProps & React.RefAttributes<HTMLDivElement>>;
+//#endregion
+export { CueTable, CueTableFeatures, DataTablePager, DataTablePagination, DataTablePaginationLabels, DataTablePaginationProps, DataTableToolbar, DataTableToolbarProps, UseCueTableOptions, createCueColumnHelper, cueTableFeatures, flexRender, useCueTable };

package/dist/instruments/data-table.js

@@ -0,0 +1,212 @@
+"use client";
+import { cn } from "../lib/cn.js";
+import { IconButton } from "../primitives/icon-button.js";
+import { SearchInput } from "../forms/search-input.js";
+import { ChevronLeftGlyph, ChevronRightGlyph, ChevronsLeftGlyph, ChevronsRightGlyph } from "./_glyphs.js";
+import * as React from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { columnFilteringFeature, createColumnHelper, createFilteredRowModel, createPaginatedRowModel, createSortedRowModel, filterFn_inNumberRange, filterFn_includesString, flexRender, globalFilteringFeature, rowPaginationFeature, rowSortingFeature, sortFn_alphanumeric, sortFn_basic, sortFn_datetime, sortFn_text, tableFeatures, useTable } from "@tanstack/react-table";
+//#region src/instruments/data-table.tsx
+/**
+* The console table recipe. Not a component — deliberately.
+*
+* A `<DataTable columns={…} data={…} />` monolith has to own the markup of
+* every cell, every header and every empty state, and the first column that
+* needs a `Chip` or a `TwoStepButton` in it starts a prop-drilling arms race
+* that ends with a component nobody can read. TanStack v9's whole point is that
+* the markup stays yours and only the *logic* is shared, so what this module
+* ships is the wiring:
+*
+* - {@link cueTableFeatures} — one opt-in feature set, so v9 can tree-shake
+*   everything the console does not use (grouping, faceting, pinning,
+*   virtualised column sizing).
+* - {@link useCueTable} — that feature set, pre-bound, with sensible console
+*   defaults.
+* - {@link createCueColumnHelper} — the column helper with the features
+*   already applied, so column defs infer.
+* - {@link DataTableToolbar} / {@link DataTablePagination} — the two pieces of
+*   chrome every table needs and nobody enjoys writing twice.
+*
+* The rows render through the Phase 1 `Table`. There is a fully worked example
+* in `test/instruments/data-table.test.tsx`.
+*
+* Ships from `@cueplusplus/ui/instruments/data-table`: `@tanstack/react-table`
+* is an optional peer, and the core bundle must not require it.
+*/
+/**
+* Sorting, column filtering, global filtering and pagination — and nothing
+* else.
+*
+* Named functions are registered individually rather than by spreading the
+* built-in registries, because spreading puts every sort and filter
+* implementation in the bundle whether or not a column names one.
+*/
+const cueTableFeatures = tableFeatures({
+	columnFilteringFeature,
+	globalFilteringFeature,
+	rowPaginationFeature,
+	rowSortingFeature,
+	filteredRowModel: createFilteredRowModel(),
+	paginatedRowModel: createPaginatedRowModel(),
+	sortedRowModel: createSortedRowModel(),
+	filterFns: {
+		includesString: filterFn_includesString,
+		inNumberRange: filterFn_inNumberRange
+	},
+	sortFns: {
+		alphanumeric: sortFn_alphanumeric,
+		basic: sortFn_basic,
+		datetime: sortFn_datetime,
+		text: sortFn_text
+	}
+});
+/**
+* A TanStack v9 table wired for the console.
+*
+* Adds one default on top of the feature set: `globalFilterFn: "includesString"`,
+* which is what a single search box over a console table always means. Override
+* it, or any other option, by passing it.
+*
+* @param options - Everything `useTable` takes except `features`.
+* @returns The table instance, ready to render through `Table`.
+* @example
+* const table = useCueTable({ data, columns, state: { globalFilter }, onGlobalFilterChange });
+*/
+function useCueTable(options) {
+	return useTable({
+		features: cueTableFeatures,
+		globalFilterFn: "includesString",
+		...options
+	});
+}
+/**
+* A column helper with {@link cueTableFeatures} already bound.
+*
+* @returns TanStack's `accessor` / `display` / `group` / `columns` builders.
+* @example
+* const helper = createCueColumnHelper<Fixture>();
+* const columns = [helper.accessor("name", { header: "Fixture" })];
+*/
+function createCueColumnHelper() {
+	return createColumnHelper();
+}
+/**
+* The strip above a table: one search box, a match count, your controls.
+*
+* The count is the part worth having as a component. "12/340" next to a filter
+* box is the difference between "the table is empty" and "the filter is too
+* tight", and it is the first thing left out of a hand-rolled toolbar.
+*
+* @example
+* <DataTableToolbar value={q} onValueChange={setQ} count={table.getRowCount()} total={data.length}>
+*   <Button variant="ghost" size="sm">Export</Button>
+* </DataTableToolbar>
+*/
+const DataTableToolbar = React.forwardRef(function DataTableToolbar({ className, value, onValueChange, placeholder = "Filter…", searchLabel = "Filter rows", count, total, children, ...elementProps }, ref) {
+	return /* @__PURE__ */ jsxs("div", {
+		ref,
+		"data-slot": "data-table-toolbar",
+		className: cn("flex min-w-0 items-center gap-(--cue-space-3) py-(--cue-space-3)", className),
+		...elementProps,
+		children: [
+			/* @__PURE__ */ jsx(SearchInput, {
+				size: "sm",
+				"aria-label": searchLabel,
+				placeholder,
+				value,
+				onValueChange,
+				className: "max-w-[16rem] min-w-0 flex-1"
+			}),
+			count === void 0 || total === void 0 ? null : /* @__PURE__ */ jsx("span", {
+				"data-slot": "data-table-count",
+				className: "shrink-0 font-mono text-(length:--cue-text-label) tabular-nums text-fg-subtle",
+				children: `${count}/${total}`
+			}),
+			children === void 0 ? null : /* @__PURE__ */ jsx("span", {
+				className: "ml-auto flex shrink-0 items-center gap-(--cue-space-2)",
+				children
+			})
+		]
+	});
+});
+const DEFAULT_PAGER_LABELS = {
+	first: "First page",
+	previous: "Previous page",
+	next: "Next page",
+	last: "Last page"
+};
+/**
+* The pager: four buttons, the position, and the row count.
+*
+* First and last are present because a console table is often sorted to put the
+* interesting row at one end, and stepping there one page at a time is not a
+* navigation strategy. Every button is an `IconButton` with a real accessible
+* name — an arrow glyph alone announces as nothing.
+*
+* @example
+* <DataTablePagination table={table} />
+*/
+const DataTablePagination = React.forwardRef(function DataTablePagination({ className, table, labels, formatPosition = (page, pages) => `${page} / ${pages}`, formatRowCount = (rows) => `${rows} row${rows === 1 ? "" : "s"}`, ...elementProps }, ref) {
+	const names = {
+		...DEFAULT_PAGER_LABELS,
+		...labels
+	};
+	const pages = Math.max(1, table.getPageCount());
+	const page = (table.state.pagination?.pageIndex ?? 0) + 1;
+	const canPrevious = table.getCanPreviousPage();
+	const canNext = table.getCanNextPage();
+	return /* @__PURE__ */ jsxs("div", {
+		ref,
+		"data-slot": "data-table-pagination",
+		className: cn("flex min-w-0 items-center gap-(--cue-space-3) py-(--cue-space-3) font-mono text-(length:--cue-text-label) text-fg-subtle", className),
+		...elementProps,
+		children: [/* @__PURE__ */ jsx("span", {
+			"data-slot": "data-table-rows",
+			className: "tabular-nums",
+			children: formatRowCount(table.getRowCount())
+		}), /* @__PURE__ */ jsxs("span", {
+			className: "ml-auto flex items-center gap-(--cue-space-1)",
+			children: [
+				/* @__PURE__ */ jsx(IconButton, {
+					size: "sm",
+					variant: "ghost",
+					"aria-label": names.first,
+					icon: ChevronsLeftGlyph,
+					disabled: !canPrevious,
+					onClick: () => table.firstPage()
+				}),
+				/* @__PURE__ */ jsx(IconButton, {
+					size: "sm",
+					variant: "ghost",
+					"aria-label": names.previous,
+					icon: ChevronLeftGlyph,
+					disabled: !canPrevious,
+					onClick: () => table.previousPage()
+				}),
+				/* @__PURE__ */ jsx("span", {
+					"data-slot": "data-table-position",
+					className: "px-(--cue-space-3) tabular-nums text-fg",
+					children: formatPosition(page, pages)
+				}),
+				/* @__PURE__ */ jsx(IconButton, {
+					size: "sm",
+					variant: "ghost",
+					"aria-label": names.next,
+					icon: ChevronRightGlyph,
+					disabled: !canNext,
+					onClick: () => table.nextPage()
+				}),
+				/* @__PURE__ */ jsx(IconButton, {
+					size: "sm",
+					variant: "ghost",
+					"aria-label": names.last,
+					icon: ChevronsRightGlyph,
+					disabled: !canNext,
+					onClick: () => table.lastPage()
+				})
+			]
+		})]
+	});
+});
+//#endregion
+export { DataTablePagination, DataTableToolbar, createCueColumnHelper, cueTableFeatures, flexRender, useCueTable };

package/dist/instruments/data-tree.d.ts

@@ -0,0 +1,126 @@
+import * as React from "react";
+//#region src/instruments/data-tree.d.ts
+/** What a row knows about itself when its content is a function. */
+interface DataTreeRowState {
+  /** Depth from the roots; `0` for a root. */
+  level: number;
+  /** Whether the node declares children at all. */
+  hasChildren: boolean;
+  /** Whether those children are currently shown. */
+  expanded: boolean;
+  /** Whether this row is the selected one. */
+  selected: boolean;
+}
+/** One node of the tree: an identity, a row's worth of content, and children. */
+interface DataTreeItem {
+  /** Stable identity: what selection, expansion and focus are keyed on. */
+  id: string;
+  /**
+   * The row's content — normally `DataRow` slots, in the same order and with
+   * the same tracks as the other idioms drawing this dataset.
+   *
+   * A function receives the row's own state, for the cases where the content
+   * differs by it: a count that only shows while a node is folded, a different
+   * marker for an expanded parent.
+   */
+  row: React.ReactNode | ((state: DataTreeRowState) => React.ReactNode);
+  /**
+   * Nested nodes. An empty array still makes the row a parent — an empty folder
+   * is a folder, and `aria-expanded` on it is the truth.
+   */
+  children?: readonly DataTreeItem[];
+  /** Grey the row out; it stays reachable by keyboard but cannot be selected. */
+  disabled?: boolean;
+}
+interface DataTreeProps extends Omit<React.ComponentPropsWithoutRef<"div">, "onSelect"> {
+  /** The roots, in display order. */
+  items: readonly DataTreeItem[];
+  /** Expanded ids when controlled. Pass with `onExpandedChange`. */
+  expanded?: readonly string[];
+  /** Initially expanded ids when uncontrolled. */
+  defaultExpanded?: readonly string[];
+  /** Called with the whole next expanded set whenever a row is folded or unfolded. */
+  onExpandedChange?: (expanded: string[]) => void;
+  /** Selected id when controlled. Pass with `onSelect`. */
+  selected?: string | null;
+  /** Initially selected id when uncontrolled. */
+  defaultSelected?: string | null;
+  /** Called with the id of the row the user selected. */
+  onSelect?: (id: string) => void;
+  /**
+   * Draw the depth guides. Defaults to `true`.
+   *
+   * Roots never draw one — there is no ancestor to draw — so a flat tree draws
+   * none at all whatever this is set to.
+   */
+  guides?: boolean;
+  /** Accessible name for the tree. Required in practice — name what it lists. */
+  "aria-label"?: string;
+}
+/**
+ * A hierarchy of multi-column rows: the tree idiom over the `DataRow` anatomy.
+ *
+ * ## The ARIA pattern, chosen before the component was written
+ *
+ * `role="treegrid"` is **rejected** for this foundation. It is the semantically
+ * exact answer — tabular *and* hierarchical — and it is the one with the worst
+ * real-world assistive-technology record: Adrian Roselli's survey of expando
+ * tables calls its support poor and notes that the APG's own worked example
+ * carries unresolved issues; fancytree's maintainer describes treegrid support
+ * as unproven ground; MUI X shipped hierarchical rows with no `aria-level` /
+ * `aria-expanded` / `aria-setsize` at all and retrofitted them later. Treegrid
+ * earns its cost when cells are individually interactive or editable, because
+ * then a reader genuinely needs two-dimensional cell navigation. This surface is
+ * read-and-navigate: you move down rows, fold a branch, and open the thing a row
+ * names.
+ *
+ * So the pattern is `role="tree"` with `role="treeitem"` rows — VS Code's
+ * choice and Carbon's, and the best-supported composite pattern in ARIA:
+ *
+ * - A **flat DOM** with `aria-level` / `aria-posinset` / `aria-setsize` per row
+ *   rather than nested `role="group"` wrappers.
+ * - **Roving tabindex**: the tree is one Tab stop and the arrows move inside it.
+ * - The **APG tree keyboard map**: Up/Down between visible rows, Home/End to the
+ *   ends, Right to unfold then to descend, Left to fold then to ascend,
+ *   Enter/Space to select.
+ * - Expansion lives on the **row**, as `aria-expanded` on the `treeitem` — that
+ *   is what tree semantics mean by a parent, and it is why the chevron here is
+ *   `role="presentation"` rather than a button. (The other half of this trade
+ *   is `Table.GroupRow`, where the table's semantics own the grouping and a real
+ *   `<button aria-expanded>` owns the disclosure. Two patterns, each internally
+ *   consistent; what would be wrong is half of each.)
+ *
+ * **The documented trade**: columns are not independently navigable. A row's
+ * multi-column content lives *inside* the treeitem, so a screen-reader user
+ * hears the row as one string rather than moving cell to cell through it. For a
+ * dense browse-and-open surface that is the better bargain — `tree` works today
+ * on every screen reader, `treegrid` does not — but a surface whose cells are
+ * genuinely editable has outgrown this component and wants a real treegrid from
+ * a library that maintains one.
+ *
+ * ## Everything else
+ *
+ * Rows are the `DataRow` chassis: same padding, same hairline, same hover wash,
+ * same inset focus ring, same `group/data-row`, so `DataRow.Actions` reveals in
+ * a tree exactly as it does in a ledger. The row element itself is the
+ * treeitem — one element owns focus, expansion, selection and the click reading
+ * — and the caller's `DataRow.*` slots are its content.
+ *
+ * A tree whose items declare no children anywhere is a flat list: no chevrons,
+ * no spacer column where a chevron would be, no guides, and `aria-expanded` on
+ * nothing. A leaf row that carried `aria-expanded="false"` would tell a screen
+ * reader it has children it does not have.
+ *
+ * @example
+ * <DataTree
+ *   aria-label="Patch"
+ *   items={nodes}
+ *   defaultExpanded={["inputs"]}
+ *   selected={selected}
+ *   onSelect={setSelected}
+ *   className="[--cue-data-row-cols:1fr_8rem_auto]"
+ * />
+ */
+declare const DataTree: React.ForwardRefExoticComponent<DataTreeProps & React.RefAttributes<HTMLDivElement>>;
+//#endregion
+export { DataTree, DataTreeItem, DataTreeProps, DataTreeRowState };