@keyfunc/keybricks-ds 1.0.4 → 2.3.1

package/components/data/Spreadsheet.vue

@@ -4,7 +4,8 @@ import Icon from '../icons/Icon.vue'
 import IconButton from '../buttons/IconButton.vue'
 import KSelect from '../forms/Select.vue'
 // Excel-style spreadsheet: toolbar, formula bar (name box + fx), frozen lettered/numbered headers, click + shift-click range selection, double-click editing, =SUM()/AVERAGE() formulas, sheet tabs, Sum/Avg/Count status bar.
-const props = defineProps({ data: { type: Array, default: () => [] }, rows: Number, cols: Number, colWidths: { type: Array, default: () => [] }, defaultColWidth: { type: Number, default: 92 }, currency: { type: String, default: '$' }, defaultActive: { type: String, default: 'A1' }, sheets: { type: Array, default: () => ['Sheet1'] }, toolbar: { type: Boolean, default: true }, formulaBar: { type: Boolean, default: true }, statusBar: { type: Boolean, default: true }, height: [Number, String], style: Object })
+const props = defineProps({ data: { type: Array, default: () => [] }, rows: Number, cols: Number, colWidths: { type: Array, default: () => [] }, defaultColWidth: { type: Number, default: 92 }, currency: { type: String, default: '$' }, defaultActive: { type: String, default: 'A1' }, sheets: { type: Array, default: () => ['Sheet1'] }, toolbar: { type: Boolean, default: true }, formulaBar: { type: Boolean, default: true }, statusBar: { type: Boolean, default: true }, height: [Number, String], size: { type: String, default: 'sm' }, style: Object })
+// A size region that defaults to sm: a spreadsheet is the densest surface in the system — 24px toolbar controls, 12px text, 28px cells.
 const emit = defineEmits(['change'])
 
 const colName = (i) => { let s = ''; i++; while (i > 0) { s = String.fromCharCode(64 + ((i - 1) % 26 + 1)) + s; i = Math.floor((i - 1) / 26) } return s }
@@ -50,24 +51,24 @@ function commit(r, c, text) { const cell = cells.value[r][c]; delete cell.f; if
 function setFlag(k) { const on = !cur.value[k]; for (let r = lo.value.r; r <= hi.value.r; r++) for (let c = lo.value.c; c <= hi.value.c; c++) cells.value[r][c][k] = on }
 function setType(label) { const t = { Automatic: undefined, Number: 'number', Currency: 'currency', Percent: 'percent' }[label]; for (let r = lo.value.r; r <= hi.value.r; r++) for (let c = lo.value.c; c <= hi.value.c; c++) { if (t) cells.value[r][c].t = t; else delete cells.value[r][c].t } }
 const gridCols = computed(() => ['46px', ...Array.from({ length: nC }, (_, c) => (props.colWidths[c] || props.defaultColWidth) + 'px')].join(' '))
-const hdr = { position: 'sticky', top: 0, zIndex: 3, background: 'var(--bg-inset)', borderRight: '1px solid var(--border-control)', borderBottom: '1px solid var(--border-control)', display: 'flex', alignItems: 'center', justifyContent: 'center', fontFamily: 'var(--font-sans)', fontWeight: 'var(--weight-medium)', fontSize: 'var(--text-xs)', color: 'var(--text-secondary)', height: '26px', boxSizing: 'border-box', userSelect: 'none' }
+const hdr = { position: 'sticky', top: 0, zIndex: 3, background: 'var(--bg-inset)', borderRight: '1px solid var(--border-control)', borderBottom: '1px solid var(--border-control)', display: 'flex', alignItems: 'center', justifyContent: 'center', fontFamily: 'var(--font-sans)', fontWeight: 'var(--weight-medium)', fontSize: 'var(--text-xs)', letterSpacing: 'var(--tracking-xs)', color: 'var(--text-secondary)', height: '26px', boxSizing: 'border-box', userSelect: 'none' }
 const hl = { background: 'var(--soft-bg)', color: 'var(--action-primary)' }
 </script>
 <template>
-  <div :style="{ border: '1px solid var(--border-control)', borderRadius: 'var(--radius-lg)', overflow: 'hidden', background: 'var(--bg-surface)', boxSizing: 'border-box', ...style }">
-    <div v-if="toolbar" style="height:36px;display:flex;align-items:center;gap:2px;padding:0 8px;border-bottom:1px solid var(--border-subtle)">
-      <IconButton icon="undo-2" size="sm" muted label="Undo" /><IconButton icon="redo-2" size="sm" muted label="Redo" />
+  <div :data-size="size" :style="{ border: '1px solid var(--border-control)', borderRadius: 'var(--radius-lg)', overflow: 'hidden', background: 'var(--bg-surface)', boxSizing: 'border-box', ...style }">
+    <div v-if="toolbar" style="height:var(--bar-card-h);display:flex;align-items:center;gap:2px;padding:0 var(--edge-pad);box-sizing:border-box;border-bottom:1px solid var(--border-subtle)">
+      <IconButton icon="undo-2" muted label="Undo" /><IconButton icon="redo-2" muted label="Redo" />
       <span style="width:1px;height:16px;background:var(--border-control);margin:0 6px" />
-      <button type="button" @click="setFlag('b')" :style="{ width: '24px', height: '24px', border: 'none', borderRadius: 'var(--radius-sm)', cursor: 'pointer', background: cur.b ? 'var(--bg-active)' : 'transparent', color: 'var(--text-body)', fontWeight: 700 }">B</button>
-      <button type="button" @click="setFlag('i')" :style="{ width: '24px', height: '24px', border: 'none', borderRadius: 'var(--radius-sm)', cursor: 'pointer', background: cur.i ? 'var(--bg-active)' : 'transparent', color: 'var(--text-body)', fontStyle: 'italic' }">I</button>
-      <button type="button" @click="setFlag('u')" :style="{ width: '24px', height: '24px', border: 'none', borderRadius: 'var(--radius-sm)', cursor: 'pointer', background: cur.u ? 'var(--bg-active)' : 'transparent', color: 'var(--text-body)', textDecoration: 'underline' }">U</button>
+      <button type="button" :data-wash="cur.b ? undefined : ''" @click="setFlag('b')" :style="{ width: 'var(--control-h)', height: 'var(--control-h)', border: 'none', borderRadius: 'var(--radius-md)', cursor: 'pointer', fontFamily: 'var(--font-sans)', fontSize: 'var(--control-text)', background: cur.b ? 'var(--bg-active)' : 'var(--wash, transparent)', color: 'var(--text-body)', fontWeight: 700 }">B</button>
+      <button type="button" :data-wash="cur.i ? undefined : ''" @click="setFlag('i')" :style="{ width: 'var(--control-h)', height: 'var(--control-h)', border: 'none', borderRadius: 'var(--radius-md)', cursor: 'pointer', fontFamily: 'var(--font-sans)', fontSize: 'var(--control-text)', background: cur.i ? 'var(--bg-active)' : 'var(--wash, transparent)', color: 'var(--text-body)', fontStyle: 'italic' }">I</button>
+      <button type="button" :data-wash="cur.u ? undefined : ''" @click="setFlag('u')" :style="{ width: 'var(--control-h)', height: 'var(--control-h)', border: 'none', borderRadius: 'var(--radius-md)', cursor: 'pointer', fontFamily: 'var(--font-sans)', fontSize: 'var(--control-text)', background: cur.u ? 'var(--bg-active)' : 'var(--wash, transparent)', color: 'var(--text-body)', textDecoration: 'underline' }">U</button>
       <span style="width:1px;height:16px;background:var(--border-control);margin:0 6px" />
-      <KSelect size="sm" :options="['Automatic','Number','Currency','Percent']" :model-value="{ number: 'Number', currency: 'Currency', percent: 'Percent' }[cur.t] || 'Automatic'" @update:modelValue="setType" style="width:110px" />
+      <KSelect :options="['Automatic','Number','Currency','Percent']" :model-value="{ number: 'Number', currency: 'Currency', percent: 'Percent' }[cur.t] || 'Automatic'" @update:modelValue="setType" style="width:110px" />
     </div>
-    <div v-if="formulaBar" style="height:32px;display:flex;align-items:center;border-bottom:1px solid var(--border-control)">
-      <span style="width:72px;align-self:stretch;display:flex;align-items:center;justify-content:center;border-right:1px solid var(--border-control);font-family:var(--font-mono);font-size:var(--text-xs);color:var(--text-heading)">{{ multi ? colName(lo.c) + (lo.r + 1) + ':' + colName(hi.c) + (hi.r + 1) : colName(active.c) + (active.r + 1) }}</span>
-      <span style="padding:0 10px;font-family:var(--font-mono);font-size:var(--text-xs);font-style:italic;color:var(--text-muted);border-right:1px solid var(--border-subtle);align-self:stretch;display:flex;align-items:center">fx</span>
-      <input :value="editing === 'fx' ? draft : rawOf(cur)" @focus="editing = 'fx'; draft = rawOf(cur)" @input="draft = $event.target.value" @blur="editing === 'fx' && (commit(active.r, active.c, draft), editing = null)" @keydown.enter="$event.target.blur()" @keydown.esc="editing = null; $event.target.blur()" style="flex:1;border:none;outline:none;background:transparent;padding:0 10px;font-family:var(--font-mono);font-size:var(--text-xs);color:var(--text-primary)" />
+    <div v-if="formulaBar" style="height:var(--bar-h);display:flex;align-items:center;border-bottom:1px solid var(--border-control)">
+      <span style="width:72px;align-self:stretch;display:flex;align-items:center;justify-content:center;border-right:1px solid var(--border-control);font-family:var(--font-sans);font-variant-numeric:tabular-nums;font-size:var(--text-xs);color:var(--text-heading)">{{ multi ? colName(lo.c) + (lo.r + 1) + ':' + colName(hi.c) + (hi.r + 1) : colName(active.c) + (active.r + 1) }}</span>
+      <span style="padding:0 10px;font-family:var(--font-sans);font-variant-numeric:tabular-nums;font-size:var(--text-xs);font-style:italic;color:var(--text-muted);border-right:1px solid var(--border-subtle);align-self:stretch;display:flex;align-items:center">fx</span>
+      <input :value="editing === 'fx' ? draft : rawOf(cur)" @focus="editing = 'fx'; draft = rawOf(cur)" @input="draft = $event.target.value" @blur="editing === 'fx' && (commit(active.r, active.c, draft), editing = null)" @keydown.enter="$event.target.blur()" @keydown.esc="editing = null; $event.target.blur()" style="flex:1;border:none;outline:none;background:transparent;padding:0 10px;font-family:var(--font-sans);font-variant-numeric:tabular-nums;font-size:var(--text-xs);color:var(--text-primary)" />
     </div>
     <div :style="{ overflow: 'auto', maxHeight: typeof height === 'number' ? height + 'px' : height }">
       <div :style="{ display: 'grid', gridTemplateColumns: gridCols, width: 'fit-content' }">
@@ -76,7 +77,7 @@ const hl = { background: 'var(--soft-bg)', color: 'var(--action-primary)' }
         <template v-for="(row, r) in cells" :key="r">
           <span :style="{ ...hdr, position: 'sticky', left: 0, top: 'auto', zIndex: 2, height: '28px', ...(r >= lo.r && r <= hi.r ? hl : null) }">{{ r + 1 }}</span>
           <span v-for="(cell, c) in row" :key="r + ',' + c" @mousedown="pick(r, c, $event)" @dblclick="editing = { r, c }; draft = rawOf(cell)"
-            :style="{ position: 'relative', height: '28px', boxSizing: 'border-box', borderRight: '1px solid var(--border-subtle)', borderBottom: '1px solid var(--border-subtle)', display: 'flex', alignItems: 'center', justifyContent: cell.align || (typeof evalCell(cells, cell) === 'number' ? 'flex-end' : 'flex-start'), padding: '0 8px', cursor: 'cell', background: inRange(r, c) && !(active.r === r && active.c === c) ? 'var(--soft-bg)' : 'var(--bg-surface)', boxShadow: active.r === r && active.c === c ? 'inset 0 0 0 2px var(--action-primary)' : 'none', fontFamily: typeof evalCell(cells, cell) === 'number' ? 'var(--font-mono)' : 'var(--font-sans)', fontSize: typeof evalCell(cells, cell) === 'number' ? '11.5px' : 'var(--text-sm)', color: evalCell(cells, cell) === '#ERROR' ? 'var(--danger)' : 'var(--text-primary)', fontWeight: cell.b ? 600 : 'var(--weight-regular)', fontStyle: cell.i ? 'italic' : 'normal', textDecoration: cell.u ? 'underline' : 'none', whiteSpace: 'nowrap', overflow: 'hidden', userSelect: 'none' }">
+            :style="{ position: 'relative', height: '28px', boxSizing: 'border-box', borderRight: '1px solid var(--border-subtle)', borderBottom: '1px solid var(--border-subtle)', display: 'flex', alignItems: 'center', justifyContent: cell.align || (typeof evalCell(cells, cell) === 'number' ? 'flex-end' : 'flex-start'), padding: '0 8px', cursor: 'cell', background: inRange(r, c) && !(active.r === r && active.c === c) ? 'var(--soft-bg)' : 'var(--bg-surface)', boxShadow: active.r === r && active.c === c ? 'inset 0 0 0 2px var(--action-primary)' : 'none', fontFamily: 'var(--font-sans)', fontVariantNumeric: typeof evalCell(cells, cell) === 'number' ? 'tabular-nums' : 'normal', fontSize: 'var(--control-text)', fontVariantNumeric: 'tabular-nums', color: evalCell(cells, cell) === '#ERROR' ? 'var(--danger)' : 'var(--text-primary)', fontWeight: cell.b ? 600 : 'var(--weight-regular)', fontStyle: cell.i ? 'italic' : 'normal', textDecoration: cell.u ? 'underline' : 'none', whiteSpace: 'nowrap', overflow: 'hidden', userSelect: 'none' }">
             <input v-if="editing && editing !== 'fx' && editing.r === r && editing.c === c" autofocus :value="draft" @input="draft = $event.target.value" @blur="commit(r, c, draft); editing = null" @keydown.enter="$event.target.blur()" @keydown.esc="editing = null" style="position:absolute;inset:0;border:none;outline:none;padding:0 8px;font:inherit;background:var(--bg-surface);color:var(--text-primary)" />
             <template v-else>{{ fmt(evalCell(cells, cell), cell.t, currency) }}</template>
             <span v-if="active.r === r && active.c === c && !editing" style="position:absolute;right:-3px;bottom:-3px;width:6px;height:6px;background:var(--action-primary);border:1px solid var(--bg-surface);cursor:crosshair;z-index:2" />
@@ -84,12 +85,12 @@ const hl = { background: 'var(--soft-bg)', color: 'var(--action-primary)' }
         </template>
       </div>
     </div>
-    <div v-if="statusBar" style="height:32px;display:flex;align-items:center;justify-content:space-between;border-top:1px solid var(--border-control);background:var(--bg-inset);padding-right:12px">
+    <div v-if="statusBar" style="height:var(--bar-h);display:flex;align-items:center;justify-content:space-between;border-top:1px solid var(--border-control);background:var(--bg-inset);padding-right:12px">
       <div style="display:flex;align-self:stretch;align-items:stretch">
-        <button v-for="s in sheets" :key="s" type="button" @click="sheet = s" :style="{ border: 'none', borderRight: '1px solid var(--border-subtle)', padding: '0 16px', cursor: 'pointer', background: sheet === s ? 'var(--bg-surface)' : 'transparent', color: sheet === s ? 'var(--text-heading)' : 'var(--text-secondary)', fontFamily: 'var(--font-sans)', fontWeight: sheet === s ? 'var(--weight-medium)' : 'var(--weight-regular)', fontSize: 'var(--text-sm)', boxShadow: sheet === s ? 'inset 0 2px 0 var(--action-primary)' : 'none' }">{{ s }}</button>
-        <span style="display:flex;align-items:center;padding:0 6px"><IconButton icon="plus" size="xs" muted label="Add sheet" /></span>
+        <button v-for="s in sheets" :key="s" type="button" :data-ink="sheet === s ? undefined : ''" @click="sheet = s" :style="{ border: 'none', borderRight: '1px solid var(--border-subtle)', padding: '0 16px', cursor: 'pointer', background: sheet === s ? 'var(--bg-surface)' : 'transparent', color: sheet === s ? 'var(--text-heading)' : 'var(--ink, var(--text-secondary))', fontFamily: 'var(--font-sans)', fontWeight: sheet === s ? 'var(--weight-medium)' : 'var(--weight-regular)', fontSize: 'var(--control-text)', boxShadow: sheet === s ? 'inset 0 2px 0 var(--action-primary)' : 'none' }">{{ s }}</button>
+        <span style="display:flex;align-items:center;padding:0 6px"><IconButton icon="plus" muted label="Add sheet" /></span>
       </div>
-      <span style="font-family:var(--font-mono);font-size:var(--text-xs);color:var(--text-secondary)">{{ stats ? 'Sum ' + fmt(stats.sum, cur.t, currency) + '   Avg ' + fmt(stats.avg, cur.t, currency) + '   Count ' + stats.count : '100%' }}</span>
+      <span style="font-family:var(--font-sans);font-variant-numeric:tabular-nums;font-size:var(--text-xs);color:var(--text-secondary)">{{ stats ? 'Sum ' + fmt(stats.sum, cur.t, currency) + '   Avg ' + fmt(stats.avg, cur.t, currency) + '   Count ' + stats.count : '100%' }}</span>
     </div>
   </div>
 </template>

package/components/data/Table.d.ts

@@ -0,0 +1,101 @@
+import * as React from "react";
+/**
+ * Hairline table — --bg-table-header header tint, one step below --bg-app so it reads on grey pages; one rule weight (--border-subtle) for header rule and row separators alike.
+ * The table is a size region: rows are the tier's bar height (sm 36 · md 40 · lg 48), cells and header share the tier's control text (header in weight 600, text-secondary, sentence case), and every control rendered inside a cell takes the same tier.
+ * @startingPoint section="Data" subtitle="Comparison / preview tables with code/amount cells" viewport="700x300"
+ */
+/** Field name on the row, or an accessor (row, index) => value. */
+export type DataTableAccessor<T> = string | ((row: any, index: number) => T);
+/** A status mark beside the title: "favorite" draws a filled 14px star in --warning; an object draws a 14px outline Icon. */
+export type DataTableTitleMark = "favorite" | { icon: string; color?: string; label: string } | null | undefined;
+/**
+ * Two-line title cell — the name column of a document list.
+ * Left to right: IconTile (kind "row", tinted by hue) · title over description · sm ⋯ IconButton.
+ * md: 32px tile r8 · 12px tile→text · title 14/20 --text-heading · description 12/16 --text-secondary (13/18 CJK) · 2px between · 10px row padding → 58px row.
+ * sm: 28px tile · 8px · 12/16 title · 2px · 8px padding → 50px.  lg: 40px tile r10 · 12px · 14/20 title · 4px · 14px padding → 68px.
+ * Each field defaults to the row key of the same name (icon, hue, description, mark).
+ */
+export interface DataTableTwoLine {
+  icon?: DataTableAccessor<string | null | undefined>;
+  /** source | join | transform | merge | output | neutral (default neutral — the grey folder tile) */
+  hue?: DataTableAccessor<"source" | "join" | "transform" | "merge" | "output" | "neutral" | null | undefined>;
+  description?: DataTableAccessor<React.ReactNode>;
+  mark?: DataTableAccessor<DataTableTitleMark>;
+  /** Trailing ⋯ button (default true). Fires the table's onRowMore. */
+  more?: boolean;
+}
+export interface DataTableSort { key: string; direction: "asc" | "desc"; }
+export interface DataTableLabels { sortAsc?: string; sortDesc?: string; sortClear?: string; more?: string; expand?: string; collapse?: string; }
+export interface DataTableColumn {
+  key: string;
+  label: string;
+  width?: number | string;
+  /** Lower bound while resizing (default 48) */
+  minWidth?: number;
+  /** Tabular figures for amounts and IDs (UI font, the row's size and colour). */
+  mono?: boolean;
+  /** Config code (ALL_CAPS_SNAKE) shown as a code chip: Menlo --text-code (12px, 11px in sm) on --bg-inset. */
+  code?: boolean;
+  /** Two-line title cell (see DataTableTwoLine); `true` reads icon/hue/description/mark from the row. Give the column a width; when the table is tight it shrinks to minWidth (default 180), and text truncates to whatever width it gets. */
+  twoLine?: boolean | DataTableTwoLine;
+  /** Header sort button: muted sm IconButton at the header cell's right end (in line with a two-line row's ⋯), shown on hover (arrow-up), kept while sorted (arrow-up / arrow-down, label --text-heading). Click cycles ascending → descending → none. Omit on action columns. */
+  sortable?: boolean;
+  /** Custom comparison for this column (ascending order). Default: numbers (commas allowed) numerically, text by locale with numeric collation, empty values last. */
+  compare?: (a: any, b: any, rowA: any, rowB: any) => number;
+  align?: "left" | "right" | "center";
+  render?: (value: any, row: any, index: number) => React.ReactNode;
+}
+export interface DataTableProps {
+  columns?: DataTableColumn[];
+  rows?: Record<string, any>[];
+  /** Size tier of the table region: sm 36px rows / 12px text, 13px in CJK (dense grids, preview drawers) · md 40px / 14px (default) · lg 48px / 14px. Omit to inherit the enclosing region. */
+  size?: "sm" | "md" | "lg";
+  /** Alias of size="sm", kept for 1.x callers */
+  dense?: boolean;
+  /** Leading checkbox column */
+  selectable?: boolean;
+  selected?: number[];
+  /** onToggle("all"|rowIndex, checked) */
+  onToggle?: (which: number | "all", checked: boolean) => void;
+  headerBorder?: boolean;
+  /** Draws its own rounded card frame (border-card, radius-lg) and drops the header-top and last-row rules that would double it. Use instead of wrapping the table in a bordered div. */
+  bordered?: boolean;
+  /** For a table placed flush inside a container that already has a border (Card pad={false}): drops only the header's top rule. */
+  framed?: boolean;
+  /** Short divider between header cells; hover darkens it, drag sets that column's width. Uses table-layout: fixed. */
+  resizable?: boolean;
+  /** Controlled widths by column key (px). Omit to let the table keep them locally. */
+  columnWidths?: Record<string, number>;
+  /** Fires on every drag frame with the new px width. Vue: `@column-resize`. */
+  onColumnResize?: (key: string, width: number) => void;
+  /** ⋯ in a twoLine cell was clicked. Vue: `@row-more`. */
+  onRowMore?: (row: any, index: number, event: React.MouseEvent) => void;
+  /** Opens a row from its twoLine cell: the icon tile and the title get a hand cursor and call this on click (the title also on Enter / Space). Vue: `@row-open`. */
+  onRowOpen?: (row: any, index: number, event: React.SyntheticEvent) => void;
+  /** Tree rows: a row nests through `children` (or sets `hasChildren: true` to show the arrow before its children are loaded). The twoLine column indents 24px per level and shows an expand arrow (chevron-right, turned down when open). Sorting reorders siblings only. Selection and event indices are depth-first over every row, so they never move. */
+  tree?: boolean;
+  /** Row field that identifies a row in expandedKeys (default "id"; falls back to the row's index). */
+  rowKey?: string;
+  /** Controlled expanded rows (keys from rowKey). Omit to let the table keep them. Vue: `v-model:expandedKeys`. */
+  expandedKeys?: (string | number)[];
+  /** Initially expanded rows when uncontrolled. */
+  defaultExpandedKeys?: (string | number)[];
+  /** An arrow was clicked: the row, whether it is now expanded, and the next key list. Load `children` here for `hasChildren` rows. Vue: `@expand-change`. */
+  onExpandChange?: (row: any, expanded: boolean, expandedKeys: (string | number)[]) => void;
+  /** Every word the table draws itself (English by default). The sort tooltip names the next step: unsorted → sortAsc, ascending → sortDesc, descending → sortClear. */
+  labels?: DataTableLabels;
+  /** Controlled sort state (one column at a time); null = unsorted. Omit to let the table keep it. Vue: `v-model:sort`. */
+  sort?: DataTableSort | null;
+  /** Initial sort when uncontrolled. */
+  defaultSort?: DataTableSort | null;
+  /** Fires with the next state: { key, direction: "asc" } → "desc" → null; a different column starts at "asc". Vue: `@sort-change`. */
+  onSortChange?: (sort: DataTableSort | null) => void;
+  /** Rows are already ordered (server-side sorting): the table shows the sort state but does not reorder. */
+  manualSort?: boolean;
+  /** Rendered inside the table (full-width cell) when rows is empty — an EmptyState or a muted line. Vue: `#empty` slot. */
+  empty?: React.ReactNode;
+  style?: React.CSSProperties;
+}
+export declare function Table(props: DataTableProps): JSX.Element;
+/** @deprecated renamed to Table in 1.0.6 — still exported in 2.x, removed in 3.0 */
+export declare const DataTable: typeof Table;

package/components/data/Table.jsx

@@ -0,0 +1,223 @@
+import React from "react";
+import { Checkbox } from "../forms/Checkbox.jsx";
+import { IconTile } from "../display/Badge.jsx";
+import { IconButton } from "../buttons/IconButton.jsx";
+import { Icon } from "../icons/Icon.jsx";
+
+/* Selection checkbox: sits in the first column's leading padding, not in a column of its own, so the gap to the
+   first column's text equals the edge padding (16px; 12px in sm) whatever the table width or column widths (a separate column took a share
+   of any spare width). */
+const CHECK_PAD = "calc(var(--edge-pad) * 2 + var(--check-size))";
+/* Config-code chip (`code: true` columns): Menlo at --text-code on the inset fill — the one place the code font appears in a table.
+   Only text and numbers get the chip; an element in the cell (a Skeleton while loading, a link) renders as is. */
+const codeChip = { fontFamily: "var(--font-mono)", fontSize: "var(--text-code)", lineHeight: "var(--leading-code)", letterSpacing: 0, background: "var(--bg-inset)", border: "1px solid var(--border-subtle)", borderRadius: 4, padding: "1px 6px", color: "var(--text-primary)", whiteSpace: "nowrap" };
+const checkSlot = { position: "absolute", left: "var(--edge-pad)", top: 0, bottom: 0, display: "flex", alignItems: "center" };
+
+/* Two-line title cell (`twoLine` column): icon tile · title over description · trailing ⋯. Every measure is a --title-cell-* tier token:
+   md 32px tile (r8) · 12px to the text · 14px title / 12px description · 2px between · 10px row padding → 58px row. */
+const T_TILE = { width: "var(--title-cell-tile)", height: "var(--title-cell-tile)", borderRadius: "var(--title-cell-tile-r)" };
+const T_ICON = { width: "var(--title-cell-icon)", height: "var(--title-cell-icon)" };
+const T_ONE = { overflow: "hidden", textOverflow: "ellipsis", whiteSpace: "nowrap", minWidth: 0 };
+const T_TITLE = { ...T_ONE, fontFamily: "var(--font-sans)", fontWeight: "var(--weight-regular)", fontSize: "var(--control-text)", lineHeight: "var(--control-leading)", letterSpacing: "var(--control-tracking)", color: "var(--text-heading)" };
+const T_DESC = { ...T_ONE, fontFamily: "var(--font-sans)", fontSize: "var(--text-xs)", lineHeight: "var(--leading-xs)", letterSpacing: "var(--tracking-xs)", color: "var(--text-secondary)" };
+const STAR_FILLED = "M11.525 2.295a.53.53 0 0 1 .95 0l2.31 4.679a2.123 2.123 0 0 0 1.595 1.16l5.166.756a.53.53 0 0 1 .294.904l-3.736 3.638a2.123 2.123 0 0 0-.611 1.878l.882 5.14a.53.53 0 0 1-.771.56l-4.618-2.428a2.122 2.122 0 0 0-1.973 0L6.396 21.01a.53.53 0 0 1-.77-.56l.881-5.139a2.122 2.122 0 0 0-.611-1.879L2.16 9.795a.53.53 0 0 1 .294-.906l5.165-.755a2.122 2.122 0 0 0 1.597-1.16z";
+// field name (string) or accessor (row, index) => value
+const pick = (a, r, ri) => typeof a === "function" ? a(r, ri) : a != null ? r[a] : undefined;
+/* Sorting: one column at a time. Click cycles ascending → descending → none; another column starts at ascending.
+   The tooltip names the next step. Rows are reordered here unless manualSort (server-side: rows arrive ordered). */
+// the label is capped at the declared width minus the button (28) and its gap (4), so a long label truncates and the cell never
+// shrinks below label + button — the button is never pushed out
+const SORT_BTN = 32;
+const isEmpty = (v) => v == null || v === "" || v === "–";
+/* Every word the table draws itself. Pass `labels` to translate; missing keys fall back to these. The sort tooltip names the NEXT step:
+   unsorted → sortAsc, ascending → sortDesc, descending → sortClear. */
+const DEFAULT_LABELS = { sortAsc: "Sort ascending", sortDesc: "Sort descending", sortClear: "Clear sorting", more: "More actions", expand: "Expand", collapse: "Collapse" };
+const sortLabel = (L, sorted) => sorted === "asc" ? L.sortDesc : sorted === "desc" ? L.sortClear : L.sortAsc;
+/* Tree (`tree` on the table, `children` on a row): the twoLine column indents 24px per level and reserves a 20px arrow slot + 4px,
+   so a child's arrow sits exactly under its parent's tile. */
+const TREE_INDENT = 24, TREE_TOGGLE = 20;
+/* Builds the visible rows. index = depth-first position over EVERY row (expanded or not) — for a flat table that is the position in
+   `rows`. It is assigned before sorting, so selection, onRowMore and onRowOpen indices never move when the user sorts or expands.
+   Sorting reorders siblings only; children stay under their parent. */
+function buildView(rows, { tree, rowKey, expanded, col, dir, manualSort }) {
+  const idx = new Map(); let n = 0;
+  const number = (list) => list.forEach((r) => { idx.set(r, n++); if (tree && Array.isArray(r.children)) number(r.children); });
+  number(rows);
+  const cmp = col && !manualSort ? (a, b) => {
+    const va = a[col.key], vb = b[col.key], ea = isEmpty(va), eb = isEmpty(vb);
+    if (ea || eb) return ea && eb ? idx.get(a) - idx.get(b) : ea ? 1 : -1; // empty values last in both directions
+    return (col.compare ? col.compare(va, vb, a, b) : compareValues(va, vb)) * dir || idx.get(a) - idx.get(b);
+  } : null;
+  const out = [];
+  const walk = (list, level) => (cmp ? list.slice().sort(cmp) : list).forEach((r) => {
+    const ri = idx.get(r), key = r[rowKey] != null ? r[rowKey] : String(ri);
+    const kids = !!tree && ((Array.isArray(r.children) && r.children.length > 0) || !!r.hasChildren);
+    const open = kids && expanded.has(key);
+    out.push({ r, ri, key, level, kids, open });
+    if (open && Array.isArray(r.children)) walk(r.children, level + 1);
+  });
+  walk(rows, 0);
+  return { list: out, total: n };
+}
+const nextSort = (cur, key) => !cur || cur.key !== key ? { key, direction: "asc" } : cur.direction === "asc" ? { key, direction: "desc" } : null;
+const num = (v) => typeof v === "number" ? v : typeof v === "string" && /^\s*-?[\d,]+(\.\d+)?\s*$/.test(v) ? parseFloat(v.replace(/,/g, "")) : NaN;
+function compareValues(a, b) {
+  const ea = a == null || a === "" || a === "–", eb = b == null || b === "" || b === "–";
+  if (ea || eb) return ea && eb ? 0 : ea ? 1 : -1;
+  const na = num(a), nb = num(b);
+  if (!isNaN(na) && !isNaN(nb)) return na - nb;
+  return String(a).localeCompare(String(b), undefined, { numeric: true, sensitivity: "base" });
+}
+function TitleMark({ m }) {
+  if (m === "favorite") return <svg width="14" height="14" viewBox="0 0 24 24" fill="currentColor" stroke="currentColor" strokeWidth="2" strokeLinejoin="round" role="img" aria-label="Favorite" style={{ display: "block", flexShrink: 0, color: "var(--warning)" }}><path d={STAR_FILLED} /></svg>;
+  return <span role="img" aria-label={m.label} style={{ display: "inline-flex", flexShrink: 0, color: m.color || "var(--text-muted)" }}><Icon name={m.icon} size={14} /></span>;
+}
+function TreeToggle({ open, label, onClick }) {
+  const [hover, setHover] = React.useState(false);
+  return (
+    <button type="button" aria-expanded={open} aria-label={label} title={label} onClick={(e) => { e.stopPropagation(); onClick(); }} onMouseEnter={() => setHover(true)} onMouseLeave={() => setHover(false)}
+      style={{ width: TREE_TOGGLE, height: TREE_TOGGLE, padding: 0, border: "none", borderRadius: "var(--radius-sm)", display: "inline-flex", alignItems: "center", justifyContent: "center", cursor: "pointer", background: hover ? "var(--overlay-hover)" : "transparent", color: hover ? "var(--text-body)" : "var(--text-muted)", transition: "var(--t-hover)" }}>
+      <Icon name="chevron-right" size={16} style={{ width: "var(--control-icon)", height: "var(--control-icon)", transform: open ? "rotate(90deg)" : "none", transition: "transform .15s ease" }} />
+    </button>
+  );
+}
+function TitleCell({ c, item, onRowMore, onRowOpen, labels, tree, onToggleRow }) {
+  const { r, ri } = item;
+  const o = c.twoLine === true ? {} : c.twoLine;
+  const icon = pick(o.icon ?? "icon", r, ri), hue = pick(o.hue ?? "hue", r, ri), desc = pick(o.description ?? "description", r, ri), mark = pick(o.mark ?? "mark", r, ri);
+  // onRowOpen: the tile and the title open the row (hand cursor); the title is also reachable by keyboard (Enter / Space)
+  const open = onRowOpen ? (e) => onRowOpen(r, ri, e) : null;
+  return (
+    <div style={{ display: "flex", alignItems: "center", minWidth: c.minWidth ?? 180, ...(tree ? { paddingLeft: item.level * TREE_INDENT } : null) }}>
+      {tree ? <span style={{ width: TREE_TOGGLE, flexShrink: 0, marginRight: TREE_INDENT - TREE_TOGGLE, display: "inline-flex" }}>{item.kids ? <TreeToggle open={item.open} label={item.open ? labels.collapse : labels.expand} onClick={() => onToggleRow(item)} /> : null}</span> : null}
+      <div style={{ display: "flex", alignItems: "center", gap: "var(--title-cell-tile-gap)", flex: 1, minWidth: 0 }}>
+        {icon ? <span onClick={open || undefined} style={{ display: "inline-flex", flexShrink: 0, cursor: open ? "pointer" : undefined }}><IconTile icon={icon} hue={hue || "neutral"} kind="row" style={T_TILE} iconStyle={T_ICON} /></span> : null}
+        <div style={{ display: "flex", flexDirection: "column", gap: "var(--title-cell-gap)", flex: 1, minWidth: 0 }}>
+          <div style={{ display: "flex", alignItems: "center", gap: 4, minWidth: 0 }}>
+            <span style={{ ...T_TITLE, ...(open ? { cursor: "pointer" } : null) }} {...(open ? { role: "button", tabIndex: 0, onClick: open, onKeyDown: (e) => { if (e.key === "Enter" || e.key === " ") { e.preventDefault(); open(e); } } } : null)}>{c.render ? c.render(r[c.key], r, ri) : r[c.key]}</span>
+            {mark ? <TitleMark m={mark} /> : null}
+          </div>
+          {desc ? <span style={T_DESC}>{desc}</span> : null}
+        </div>
+        {o.more !== false ? <IconButton icon="ellipsis" size="sm" muted label={labels.more} title={labels.more} onClick={(e) => { if (e && e.stopPropagation) e.stopPropagation(); if (onRowMore) onRowMore(r, ri, e); }} /> : null}
+      </div>
+    </div>
+  );
+}
+
+/**
+ * Keybricks table. columns: [{key,label,width,minWidth,mono,code,twoLine,sortable,compare,align,render}].
+ * sortable — hover the header for a muted sm sort button at the cell's right end (in line with a two-line row's ⋯; arrow-up); click: ascending → descending → none.
+ *            While sorted the button stays and the label turns --text-heading. One column at a time. sort / onSortChange control it
+ *            (defaultSort to seed it uncontrolled); compare(a, b, rowA, rowB) overrides the default comparison; manualSort keeps rows as given.
+ * twoLine  — the name column of a document list: icon tile, title over a description, optional mark ("favorite" = filled star), trailing ⋯
+ *            (onRowMore(row, index, event)); onRowOpen(row, index, event) makes the tile and the title open the row (hand cursor, Enter / Space on the title).
+ *            tree — rows nest through `children` (or `hasChildren` for rows you load on demand); the twoLine column indents 24px per level with an
+ *            expand arrow; expandedKeys / defaultExpandedKeys / onExpandChange(row, expanded, keys); rowKey names the key field (default "id").
+ * labels   — { sortAsc, sortDesc, sortClear, more, expand, collapse } for every word the table draws (English by default).
+ *            Give it a width; it shrinks to minWidth (default 180) before the other columns give way, and title and description truncate to whatever it gets. Row grows to 58px in md (50 sm · 68 lg).
+ * The table is a size region: `size` ("sm" | "md" | "lg", default inherit → md) sets its rows, header, cell padding and every
+ * control inside the cells from the tier tokens — rows are the tier's bar height (sm 36 · md 40 · lg 48), cells read the tier's
+ * control text, header cells are the same size in weight 600 / text-secondary, sentence case, no letter-spacing.
+ * `dense` is kept as an alias of size="sm" (the data-preview drawer).
+ * Every rule in the table is one weight (--border-subtle); the header is set apart by its --bg-table-header tint, never by a heavier line.
+ * bordered  — the table draws its own rounded card frame (border-card, radius-lg) and drops the edge rules that would double it.
+ * framed    — the table sits flush inside a container that already has a border (Card pad={false}); drops only the header's top rule.
+ * resizable — a short divider between header cells (hover darkens it, cursor col-resize); drag to set that column's width.
+ *             Widths live in local state unless you pass columnWidths/onColumnResize to control them. Min width = column.minWidth ?? 48.
+ */
+export function Table({ columns = [], rows = [], size, dense, selectable, selected = [], onToggle, headerBorder = true, bordered, framed, resizable, columnWidths, onColumnResize, onRowMore, onRowOpen, sort, defaultSort = null, onSortChange, manualSort, tree, rowKey = "id", expandedKeys, defaultExpandedKeys, onExpandChange, labels, empty, style }) {
+  const L = { ...DEFAULT_LABELS, ...labels };
+  const [localExp, setLocalExp] = React.useState(defaultExpandedKeys || []);
+  const expKeys = expandedKeys !== undefined ? expandedKeys : localExp;
+  const [localSort, setLocalSort] = React.useState(defaultSort);
+  const sortState = sort !== undefined ? sort : localSort;
+  const [hotTh, setHotTh] = React.useState(null); // header under the pointer or holding focus
+  const cycleSort = (key) => { const n = nextSort(sortState, key); if (sort === undefined) setLocalSort(n); if (onSortChange) onSortChange(n); };
+  const { list: view, total } = React.useMemo(() => buildView(rows, {
+    tree, rowKey, expanded: new Set(expKeys), manualSort,
+    col: sortState && columns.find((x) => x.key === sortState.key), dir: sortState && sortState.direction === "desc" ? -1 : 1,
+  }), [rows, columns, sortState, manualSort, tree, rowKey, expKeys]);
+  const toggleRow = (item) => {
+    const next = item.open ? expKeys.filter((k) => k !== item.key) : [...expKeys, item.key];
+    if (expandedKeys === undefined) setLocalExp(next);
+    if (onExpandChange) onExpandChange(item.r, !item.open, next);
+  };
+  const tier = size || (dense ? "sm" : undefined);
+  const flushTop = bordered || framed;
+  const colCount = columns.length || 1;
+  const [localW, setLocalW] = React.useState({});
+  const [drag, setDrag] = React.useState(null); // key being dragged
+  const [hot, setHot] = React.useState(null); // key whose handle is hovered
+  const thRefs = React.useRef({});
+  const widths = columnWidths || localW;
+  const widthOf = (c) => widths[c.key] ?? c.width;
+
+  const startDrag = (e, c) => {
+    e.preventDefault();
+    const th = thRefs.current[c.key];
+    const startX = e.clientX, startW = th ? th.getBoundingClientRect().width : (parseFloat(widthOf(c)) || 120);
+    const min = c.minWidth ?? 48;
+    setDrag(c.key);
+    const move = (ev) => {
+      const w = Math.max(min, Math.round(startW + ev.clientX - startX));
+      if (onColumnResize) onColumnResize(c.key, w); else setLocalW((s) => ({ ...s, [c.key]: w }));
+    };
+    const up = () => { setDrag(null); window.removeEventListener("mousemove", move); window.removeEventListener("mouseup", up); document.body.style.cursor = ""; document.body.style.userSelect = ""; };
+    document.body.style.cursor = "col-resize"; document.body.style.userSelect = "none";
+    window.addEventListener("mousemove", move); window.addEventListener("mouseup", up);
+  };
+
+  // `mono` columns (codes, IDs, amounts) use the UI font with tabular figures; the monospace font is for code only
+  const cellFont = (c) => c.mono
+    ? { fontFamily: "var(--font-sans)", fontSize: "var(--control-text)", lineHeight: "var(--control-leading)", letterSpacing: "var(--control-tracking)", fontVariantNumeric: "tabular-nums", color: "var(--text-primary)" }
+    : { fontFamily: "var(--font-sans)", fontSize: "var(--control-text)", lineHeight: "var(--control-leading)", letterSpacing: "var(--control-tracking)", color: "var(--text-primary)" };
+  // first and last cells keep the card's edge padding; every other cell the tier's cell padding
+  const cellPad = (i) => ({ ...(i === 0 && selectable ? { position: "relative" } : null), paddingTop: 0, paddingBottom: 0, paddingLeft: i === 0 ? (selectable ? CHECK_PAD : "var(--edge-pad)") : "var(--cell-px)", paddingRight: i === columns.length - 1 ? "var(--edge-pad)" : "var(--cell-px)" });
+
+  const table = (
+    <table data-size={tier} style={{ width: "100%", borderCollapse: "collapse", tableLayout: resizable ? "fixed" : "auto", ...(bordered ? null : style) }}>
+      <thead>
+        <tr style={{ background: "var(--bg-table-header)", borderTop: headerBorder && !flushTop ? "1px solid var(--border-subtle)" : "none", borderBottom: headerBorder ? "1px solid var(--border-subtle)" : "none", height: "var(--bar-h)" }}>
+          {columns.map((c, i) => {
+            const last = i === columns.length - 1;
+            const active = drag === c.key, lit = active || hot === c.key;
+            const sorted = sortState && sortState.key === c.key ? sortState.direction : null;
+            const showSort = c.sortable && (sorted || hotTh === c.key);
+            return (
+              <th key={c.key} ref={(el) => { thRefs.current[c.key] = el; }} aria-sort={c.sortable ? (sorted === "asc" ? "ascending" : sorted === "desc" ? "descending" : "none") : undefined}
+                onMouseEnter={c.sortable ? () => setHotTh(c.key) : undefined} onMouseLeave={c.sortable ? () => setHotTh(null) : undefined} onFocus={c.sortable ? () => setHotTh(c.key) : undefined} onBlur={c.sortable ? () => setHotTh(null) : undefined}
+                style={{ position: "relative", textAlign: c.align || "left", ...cellPad(i), width: widthOf(c), fontFamily: "var(--font-sans)", fontWeight: "var(--weight-semibold)", fontSize: "var(--control-text)", lineHeight: "var(--control-leading)", letterSpacing: "var(--control-tracking)", color: sorted ? "var(--text-heading)" : "var(--text-secondary)", whiteSpace: "nowrap", overflow: "hidden", textOverflow: "ellipsis" }}>
+                {selectable && i === 0 ? <span style={checkSlot}><Checkbox checked={total > 0 && selected.length === total} indeterminate={selected.length > 0 && selected.length < total} onChange={(v) => onToggle && onToggle("all", v)} /></span> : null}
+                {c.sortable ? (
+                  <span style={{ display: "flex", alignItems: "center", gap: 4 }}>
+                    <span style={{ overflow: "hidden", textOverflow: "ellipsis", whiteSpace: "nowrap", minWidth: 0, ...(c.align === "right" ? { marginLeft: "auto" } : c.align === "center" ? { margin: "0 auto" } : null), ...(typeof widthOf(c) === "number" ? { maxWidth: widthOf(c) - SORT_BTN } : null) }}>{c.label}</span>
+                    <IconButton icon={sorted === "desc" ? "arrow-down" : "arrow-up"} size="sm" muted label={sortLabel(L, sorted)} title={sortLabel(L, sorted)} onClick={() => cycleSort(c.key)} style={{ opacity: showSort ? 1 : 0, ...(c.align === "right" ? null : { marginLeft: "auto" }) }} />
+                  </span>
+                ) : c.label}
+                {resizable && !last ? (
+                  <span aria-hidden="true" onMouseDown={(e) => startDrag(e, c)} onMouseEnter={() => setHot(c.key)} onMouseLeave={() => setHot(null)}
+                    style={{ position: "absolute", top: 0, right: -5, width: 11, height: "100%", cursor: "col-resize", display: "flex", alignItems: "center", justifyContent: "center", zIndex: 1 }}>
+                    <span style={{ width: active ? 2 : 1, height: "50%", background: lit ? "var(--action-primary)" : "var(--border-split)", borderRadius: 1, transition: "var(--t-hover)" }}></span>
+                  </span>
+                ) : null}
+              </th>
+            );
+          })}
+        </tr>
+      </thead>
+      <tbody>
+        {view.map((item, pos) => { const { r, ri } = item; return (
+          <tr key={item.key} data-row="" aria-level={tree ? item.level + 1 : undefined} aria-expanded={item.kids ? item.open : undefined} style={{ height: "var(--bar-h)", background: "var(--row-wash, transparent)", transition: "var(--t-hover)", borderBottom: bordered && pos === view.length - 1 ? "none" : "1px solid var(--border-subtle)" }}>
+            {columns.map((c, i) => (
+              <td key={c.key} style={{ ...cellPad(i), ...(c.twoLine ? { paddingTop: "var(--title-cell-py)", paddingBottom: "var(--title-cell-py)", maxWidth: 0 } : null), textAlign: c.align || "left", whiteSpace: "nowrap", ...(resizable ? { overflow: "hidden", textOverflow: "ellipsis" } : null), ...cellFont(c) }}>{selectable && i === 0 ? <span style={checkSlot}><Checkbox checked={selected.includes(ri)} onChange={(v) => onToggle && onToggle(ri, v)} /></span> : null}{c.twoLine ? <TitleCell c={c} item={item} onRowMore={onRowMore} onRowOpen={onRowOpen} labels={L} tree={tree && c === columns.find((x) => x.twoLine)} onToggleRow={toggleRow} /> : (c.code && (typeof r[c.key] === "string" || typeof r[c.key] === "number") && r[c.key] !== "") ? <code style={codeChip}>{c.render ? c.render(r[c.key], r, ri) : r[c.key]}</code> : c.render ? c.render(r[c.key], r, ri) : r[c.key]}</td>
+            ))}
+          </tr>
+        ); })}
+        {rows.length === 0 && empty ? <tr><td colSpan={colCount} style={{ padding: 0 }}>{empty}</td></tr> : null}
+      </tbody>
+    </table>
+  );
+  if (!bordered) return table;
+  return <div data-size={tier} style={{ background: "var(--bg-surface)", border: "1px solid var(--border-card)", borderRadius: "var(--radius-lg)", overflow: "hidden", ...style }}>{table}</div>;
+}