@zakkster/lite-table 1.0.0 → 1.2.0

package/llms.txt

@@ -3,6 +3,17 @@
 Headless reactive data tables. CSS Grid. Zero-GC scrolling. Built on
 @zakkster/lite-signal, @zakkster/lite-virtual, @zakkster/lite-signal-dom.
 
+Feature milestones:
+  M1  (v1.0) headless core + DOM mount, virtualized rows on pooled slots,
+             sort, selection, resize, reorder, pin, flex.
+  M1.1 (v1.1) export (CSV / JSON), scope-dispose leak fix, sort-chain UX.
+  M2  (v1.1) cell editing, per-column filtering.
+  M3  (v1.2) row grouping (multi-level), per-column aggregation, sticky
+             group headers, sticky grand total.
+
+All feature additions are opt-in; the ungrouped / non-editing / non-filtering
+fast path is bit-identical to v1.0.
+
 ## Architecture invariants
 
 - No <table>. CSS Grid layout. role=grid / row / columnheader / gridcell.
@@ -130,10 +141,216 @@ TableCore methods (focus):
               rowStart, rowEnd, pageUp, pageDown
   skips hidden columns; follows current sort order
 
+TableCore methods (export, M1.1):
+  exportCsv(opts?) -> string
+    opts.rows: "visible"|"all"|"selected"|Array (default "visible")
+    opts.columns: "visible"|"all"|Array<key> (default "visible")
+    opts.delimiter: string (default ",")
+    opts.quote: string (default '"')
+    opts.headers: boolean (default true)
+    opts.newline: string (default "\r\n")
+    opts.bom: boolean (default false; UTF-8 BOM for Excel-on-Windows)
+    opts.formatter: (row, col) => unknown
+    RFC 4180 escaping; column accessor honored; numbers stringify naturally;
+    null/undefined become empty fields.
+
+  exportJson(opts?) -> string | object[]
+    opts.rows: same as exportCsv
+    opts.columns: same as exportCsv
+    opts.indent: number (default 0 = compact single-line)
+    opts.format: "string"|"array" (default "string"; "array" skips JSON.stringify)
+    opts.formatter: (row, col) => unknown
+    Fast path: columns:"all"+no formatter returns rows.slice() (shallow).
+
+  Paginated-getter pitfall: rows:"all" and rows:"selected" resolve against
+  rowsGetter(), which for a function-form rows IS the current page. To
+  export across the master, pass the master array:
+      table.exportCsv({rows: allRows})
+      table.exportCsv({rows: table.selectedRows(allRows)})
+
+TableCore filtering (M2):
+  Column opt-in: { key, filterable: true,
+                   filter?: (value, query, row) => boolean,
+                   filterPlaceholder?: string }
+
+  Default predicate: case-insensitive substring on stringified value.
+  Empty / whitespace-only query: filter is treated as inactive (predicate
+  not invoked).
+
+  Reactive surface:
+    columnFilters() -> ReadonlyMap<columnKey, queryString>
+    filteredRows()  -> Computed rows post-filter, pre-sort
+    visibleRows()   -> Computed rows post-filter AND post-sort
+
+  Methods:
+    setColumnFilter(key, value)   value=null/""/whitespace clears that column
+    clearColumnFilters()           no-op + no notify if already empty
+
+  Pipeline: rowsGetter -> filteredRows -> visibleRows -> exports/mount
+  Multiple active filters apply as AND.
+
+  DOM (when mounted): a .lt-filter-row is mounted between header + viewport
+  if any column is filterable. One <input> per filterable column, two-way
+  bound. Escape on input clears that column's filter. Sticky top.
+
+TableCore editing (M2):
+  Column opt-in: { key, editable: true }
+  Config: createTable({ ...,
+                        onCellEdit: ({row, columnKey, oldValue, newValue}) => ... })
+
+  lite-table does NOT mutate rows. onCellEdit is the consumer's write hook.
+
+  Reactive surface:
+    editingCell()  -> { rowId, columnKey } | null
+    editingDraft() -> current in-progress string
+
+  Methods:
+    startEdit(rowId, columnKey)    no-op on non-editable; auto-commits
+                                    in-flight on a different cell;
+                                    idempotent on the same cell.
+    commitEdit()                   reads editingDraft
+    commitEdit("explicit")         commits a specific value
+    cancelEdit()                   discard; no onCellEdit
+    isEditing(rowId, columnKey)    O(1) predicate
+
+  Commit-skip: onCellEdit is NOT called when the value is unchanged.
+    DOM edits produce string newValue; guard compares
+    String(oldValue) !== newValue (so 100 vs "100" is unchanged).
+    Explicit commitEdit(explicitValue) falls back to strict ===.
+    newValue is ALWAYS a string from the DOM path -- consumers
+    coerce in their handler (Number(newValue) / new Date(newValue) /
+    newValue === "true" / etc.).
+  Handler errors are caught + logged; subsequent edits work.
+
+  DOM keyboard (when mounted):
+    dblclick on editable cell -> startEdit
+    F2 / Enter on focused cell with editable column -> startEdit
+    Enter   -> commit + moveFocus down
+    Tab     -> commit + moveFocus right (Shift+Tab = left)
+    Escape  -> cancel + return focus to root
+    blur    -> commit
+
+  Edit state survives scroll: keyed on rowId, so contenteditable rebinds
+  when the row scrolls back into view. Draft preserved across scroll.
+
+TableCore grouping + aggregation (M3):
+  Config:
+    createTable({ ...,
+                  groupBy: "region" | ["region","status"] | null,
+                  initialCollapsedGroups: [["Europe"], ["Asia","Books"]],
+                  showGrandTotal: true })
+  Column opt-in for aggregates:
+    { key, aggregate: "sum"|"avg"|"min"|"max"|"count" | (rows,col)=>any,
+            aggregateFormat?: (value, col, count) => string }
+
+  Aggregates fold over LEAF rows at every depth. Safe default for reducers
+  that don't compose associatively (median, last-value-wins, distinct).
+  Nullish values are skipped for sum/avg/min/max; count is unconditional.
+  aggregateFormat is display-only; entry.aggregates.get(key) stays raw for
+  export. Errors in aggregateFormat are caught + logged.
+
+  Pipeline: rowsGetter -> filteredRows -> groupedRows -> visibleEntries
+  Sort applies WITHIN each leaf group. Groups themselves are sorted by
+  group key ascending; nulls bucket last. Filter runs BEFORE grouping so
+  empty groups vanish.
+
+  Reactive surface:
+    groupBy()           -> readonly string[]              -- [] = ungrouped
+    collapsedGroups()   -> ReadonlySet<string>            -- path-strings
+    groupedRows()       -> GroupNode[] | null             -- null when ungrouped
+    visibleEntries()    -> Entry[]                        -- interleaved rendering feed
+    entryCount()        -> number                         -- drives virtual axis
+    visibleRows()       -> Row[]                          -- DATA-ONLY, unchanged 1.1 contract
+    rowCount()          -> number                         -- DATA-ONLY, unchanged
+
+  Entry union:
+    { type: "data",         row }
+    { type: "group-header", depth, key, value, path, pathStr, count,
+                             aggregates, isCollapsed }
+    { type: "grand-total",  aggregates, count }
+
+  GroupNode:
+    { depth, key, value, path, pathStr, count,
+      aggregates: Map<colKey, any>,
+      subGroups: GroupNode[] | null,     -- internal nodes only
+      rows: Row[] | null                  -- leaf nodes only
+    }
+
+  Methods:
+    setGroupBy(v)                   idempotent; unknown keys dropped
+    toggleGroup(path)
+    expandGroup(path)               no-op if already expanded
+    collapseGroup(path)             no-op if already collapsed
+    expandAllGroups()               clears collapsed set
+    collapseAllGroups()             walks groupedRows() once
+    isGroupCollapsed(path)          O(1) predicate
+    groupAncestryAt(entryIndex)     GroupHeaderEntry[]; for sticky headers.
+                                    Returns strictly-shallower ancestors --
+                                    a depth-0 group-header at entryIndex
+                                    yields [], so sticky doesn't duplicate
+                                    the inline row.
+
+  Ungrouped fast path: when groupBy() is empty, groupedRows short-circuits
+  to null and visibleRows returns sort-applied rows directly. One extra
+  signal read of overhead vs 1.1.0.
+
+  DOM (when mounted):
+    Pool-rendered group header:
+      <div class="lt-row lt-row-group-header"
+           data-depth data-collapsed>
+        <div class="lt-cell" data-key>chevron + value + (N)</div>
+        <div class="lt-cell" data-key>aggregate or empty</div>
+        ...
+      </div>
+    Grand total (pool-rendered): same shape, class="lt-row lt-row-grand-total",
+    first cell reads "Total (N)".
+
+    Sticky group headers (always mounted; hidden when ungrouped):
+      viewport > .lt-sticky-groups   -- position:sticky; top:rowHeight;
+                                        height:0; z-index:2
+        > .lt-row-group-header.lt-sticky-group[data-depth][data-collapsed]
+          absolute; top:depth*rowHeight; grid layout inline
+      Note: sticky rows do NOT carry .lt-row so querySelectorAll(".lt-row")
+      still counts only pool slots.
+
+    Sticky grand total (always mounted; hidden when showGrandTotal is off):
+      viewport > .lt-sticky-grand-total   -- position:sticky; bottom:0;
+                                             height:0; z-index:2
+        > .lt-row-grand-total.lt-sticky-grand-total-row
+          absolute; top:-rowHeight to anchor bottom edge to container top
+
+    DOM order in viewport:
+      .lt-header (sticky top:0)
+      .lt-sticky-groups (sticky top:rowHeight, before inner)
+      .lt-inner (pool slots absolute translateY inside)
+      .lt-sticky-grand-total (sticky bottom:0, after inner)
+
+    Sticky ancestor source: axis.firstIndex() (from @zakkster/lite-virtual,
+    the pre-overscan first-visible entry). Using axis.start() would show
+    stale ancestors when scrolling across group boundaries because start
+    includes overscan slots ABOVE the viewport.
+
+    Click on sticky group row: same behavior as inline -- toggleGroup(path).
+    Click on grand-total row: ignored (no selection change).
+
+  Reactive column state carries over:
+    Sticky cells register the same colPlacement + pin effects that pool
+    cells do. Hiding the first-visible column moves the chevron+label to
+    the next; reordering keeps sticky + pool aligned; pin applies to sticky.
+
+  Zero-GC: 10k boundary scrolls, 100k rows, groupBy:"status",
+    showGrandTotal, sticky overlays active. signal-node delta 0,
+    link delta 2 (noise), pool delta 0. See bench/03-heap-grouped.js.
+
 TableCore lifecycle:
   dispose()                             releases all reactive nodes
   cellId(rowId, columnKey)              -> "lt_<rowId>__<columnKey>"
 
+  Note: v1.1.0 fixed a latent leak in dispose() (handles were called,
+  not freed). After dispose() every reactive node the table allocated
+  returns to the registry pool. 50 createTable+dispose cycles round-trip
+  cleanly with activeNodes flat.
+
 ### mountTable(host, table, options?) -> TableMount
 
 options: { injectStyles?=true, initialViewportHeight?=480 }
@@ -163,20 +380,63 @@ Header:  <div class="lt-header" role="row" aria-rowindex="1">
              <span class="lt-header-resize"></span>  <!-- if resizable -->
            </div> ...
          </div>
+Filters (M2; mounted only when any column has filterable: true):
+         <div class="lt-filter-row" role="row" aria-rowindex="2">
+           <div class="lt-filter-cell" data-key data-pin
+                style="grid-column; left|right (if pinned)">
+             <input class="lt-filter-input"
+                    aria-label="Filter <header>"
+                    placeholder="Filter…">
+             <!-- empty cells for non-filterable columns -->
+           </div> ...
+         </div>
 Body:    <div class="lt-viewport"><div class="lt-inner">
-           <div class="lt-row [lt-row-alt] [is-selected]"
+           <div class="lt-row [lt-row-alt] [is-selected]
+                       [lt-row-group-header] [lt-row-grand-total]
+                       [data-depth data-collapsed]"        <!-- M3 header/total attrs -->
                 role="row"
                 aria-rowindex aria-selected
                 style="transform: translateY(<i*rowHeight>px)">
-             <div class="lt-cell" role="gridcell"
+             <div class="lt-cell [is-focused] [is-editing]"
+                  role="gridcell"
                   id="lt_<rowId>__<columnKey>"
                   aria-colindex
                   data-pin
+                  [data-editable="true"]
+                  [contenteditable="true"]   <!-- only the active edit cell -->
                   style="grid-column; left|right (if pinned)">text</div>
              ...
            </div> ...
          </div></div>
 
+Sticky overlays (M3; direct children of .lt-viewport):
+         <div class="lt-sticky-groups" aria-hidden="true"
+              style="position:sticky; top:<rowHeight>px;
+                     height:0; z-index:2">
+           <div class="lt-row-group-header lt-sticky-group"
+                data-depth data-collapsed
+                style="position:absolute; top:<depth*rowHeight>px;
+                       height:<rowHeight>px;
+                       display:grid; grid-template-columns:var(--lt-cols)">
+             <div class="lt-cell" data-key>chevron + value + (N)</div>
+             ...
+           </div> ...
+         </div>
+         <div class="lt-sticky-grand-total" aria-hidden="true"
+              style="position:sticky; bottom:0; height:0; z-index:2">
+           <div class="lt-row-grand-total lt-sticky-grand-total-row"
+                style="position:absolute; top:-<rowHeight>px;
+                       height:<rowHeight>px;
+                       display:grid; grid-template-columns:var(--lt-cols)">
+             <div class="lt-cell" data-key>Total (N) / aggregate</div>
+             ...
+           </div>
+         </div>
+
+Sticky rows deliberately do NOT carry the base .lt-row class so consumers'
+querySelectorAll(".lt-row") still counts only pool slots (backwards-compatible
+with 1.0/1.1 code that inspects the DOM this way).
+
 ## Keyboard
 
 ArrowUp/Down/Left/Right    move focus (skips hidden cols)
@@ -185,14 +445,26 @@ Ctrl+Home/End              grid corners (0,0) / (last,last)
 PageUp/PageDown            +/- floor(viewportHeight / rowHeight)
 Space                      selectRow(focused.rowId, "set")
 Ctrl+A                     selectAll()
-Escape                     clearSelection()
+Escape                     clearSelection() (when not editing)
+F2 / Enter (on editable)   startEdit(focused) (M2)
+Dblclick on editable cell  startEdit (M2)
 Click cell                 selectRow(set) + focus
 Shift+click                selectRow(range)
 Ctrl/Cmd+click             selectRow(toggle)
 Drag header                reorder
 Drag right edge of header  resize
 Click header               toggleSort
+(while editing):
+  Enter                    commitEdit + moveFocus("down")
+  Tab / Shift+Tab          commitEdit + moveFocus("right"/"left")
+  Escape                   cancelEdit + return focus to root
+  blur                     commitEdit
+(on a filter input):
+  Escape                   setColumnFilter(key, "")
 Shift+click header         toggleSort additive
+Click group-header row     toggleGroup(entry.path) (M3, inline OR sticky)
+Click grand-total row      ignored (M3)
+Arrow-up/down              stays inside data rows -- skips headers (M3)
 
 ## Performance
 
@@ -222,13 +494,23 @@ Classes for styling:
   .lt-header-cell.is-drop-before / .is-drop-after
   .lt-header-resize:hover / .is-active
 
+M3 grouping / total classes:
+  .lt-row-group-header               pool-rendered group header
+  .lt-row-group-header[data-depth]   0 / 1 / 2 / 3 / 4 -> indent
+  .lt-row-group-header[data-collapsed="true"|"false"]
+  .lt-row-grand-total                pool-rendered grand total
+  .lt-sticky-groups                  sticky-header container (viewport child)
+  .lt-sticky-group                   sticky group-header row inside container
+  .lt-sticky-grand-total             sticky grand-total container
+  .lt-sticky-grand-total-row         sticky grand-total row inside container
+
 ## Files
 
-Table.js          single-file ESM source
+Table.js          single-file ESM source (~3100 lines)
 Table.d.ts        type declarations
-demo/index.html   QA demo with controls for all M1 features
+demo/index.html   QA demo with controls for all M1 / M2 / M3 features
 demo/serve.js     zero-dep static server (npm run demo)
-test/*.test.js    node:test suite (npm test, 110 tests across 9 files)
+test/*.test.js    node:test suite (npm test, 257 tests across 14 files)
 bench/*.js        benchmarks vs clusterize.js + naive virtual (npm run bench)
 llms.txt          this file
 README.md         human docs with Mermaid diagrams + bench numbers
@@ -248,6 +530,9 @@ Headline:
   - 10K boundary scrolls: signal nodes delta 0, signal links delta 0,
                           DOM pool delta 0, process heap noise floor
   - mount 1M rows:       ~56ms, 24-element pool, constant vs dataset size
+  - 10K boundary scrolls in a GROUPED 100k-row table with sticky group
+    headers + sticky grand total active: signal nodes delta 0, link
+    delta 2 (noise), pool delta 0. See bench/03-heap-grouped.js.
 
 The reactive graph and DOM pool are stable across all steady-state ops.
 Allocations happen only during mount and on demand (column reorder may

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zakkster/lite-table",
-  "version": "1.0.0",
-  "description": "Headless reactive data tables on @zakkster/lite-signal. CSS Grid (no <table>), pooled slots that never reparent, aria-activedescendant focus model. Zero-GC scroll path on @zakkster/lite-virtual.",
+  "version": "1.2.0",
+  "description": "Headless reactive data tables on @zakkster/lite-signal. CSS Grid (no <table>), pooled slots that never reparent, aria-activedescendant focus model. Zero-GC scroll path on @zakkster/lite-virtual. Grouping, aggregation, sticky group headers, and grand totals in v1.2.",
   "sideEffects": false,
   "keywords": [
     "table",
@@ -16,7 +16,9 @@
     "lite-virtual",
     "aria",
     "a11y",
-    "admin"
+    "admin",
+    "grouping",
+    "aggregation"
   ],
   "type": "module",
   "main": "./Table.js",
@@ -24,8 +26,10 @@
   "types": "./Table.d.ts",
   "exports": {
     ".": {
+      "node": "./Table.js",
+      "import": "./Table.js",
       "types": "./Table.d.ts",
-      "import": "./Table.js"
+      "default": "./Table.js"
     }
   },
   "files": [
@@ -42,24 +46,26 @@
     "bench": "node --expose-gc --max-old-space-size=4096 bench/run.js"
   },
   "peerDependencies": {
-    "@zakkster/lite-signal": "^1.2.0",
+    "@zakkster/lite-signal": "^1.2.1",
     "@zakkster/lite-signal-dom": "^1.0.1",
     "@zakkster/lite-virtual": "^1.1.0"
   },
   "devDependencies": {
+    "@playwright/test": "^1.60.0",
     "clusterize.js": "^1.0.0",
-    "happy-dom": "^15.11.7"
+    "happy-dom": "^15.11.7",
+    "playwright": "^1.60.0"
   },
   "engines": {
     "node": ">=20"
   },
-  "homepage": "https://github.com/PeshoVurtoleta/lite-signal#readme",
+  "homepage": "https://github.com/PeshoVurtoleta/lite-table#readme",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/PeshoVurtoleta/lite-signal.git"
+    "url": "git+https://github.com/PeshoVurtoleta/lite-table.git"
   },
   "bugs": {
-    "url": "https://github.com/PeshoVurtoleta/lite-signal/issues",
+    "url": "https://github.com/PeshoVurtoleta/lite-table/issues",
     "email": "shinikchiev@yahoo.com"
   },
   "funding": {