@zakkster/lite-table 1.0.0 → 1.2.0

package/Table.d.ts

@@ -36,12 +36,38 @@ export interface ColumnDef<Row = any, Value = unknown> {
     pinnable?: boolean;
     hideable?: boolean;
     reorderable?: boolean;
+    /** M2: enable double-click / F2 cell editing for this column. Default false. */
+    editable?: boolean;
+    /** M2: enable the per-column filter input above this column. Default false. */
+    filterable?: boolean;
+    /** M2: custom filter predicate. Receives the column's value (post-accessor),
+     *  the current (trimmed) filter query string, and the full row. Return
+     *  true to keep the row in the result. Defaults to case-insensitive
+     *  substring match on the stringified value. */
+    filter?: (value: Value, query: string, row: Row) => boolean;
+    /** M2: placeholder text for the filter input. Default "Filter…". */
+    filterPlaceholder?: string;
+    /** M3: aggregate reducer for group-header + grand-total cells. One of the
+     *  built-in strings, or a custom `(rows, col) => value` function. `null`
+     *  or omitted means "no aggregate" -- the column shows blank in header
+     *  rows. Aggregates always fold over LEAF rows at every depth (safe
+     *  for non-associative reducers like median or last-value-wins). */
+    aggregate?: AggregateSpec<Row> | null;
+    /** M3: format the aggregate for display. Only affects rendered text --
+     *  `entry.aggregates.get(key)` still returns the raw value so consumers
+     *  can format independently for export etc. Errors are caught + logged. */
+    aggregateFormat?: (value: unknown, col: ColumnState<Row>, count: number) => string;
     /** Computed value override; if absent, `row[key]` is used. */
     accessor?: (row: Row) => Value;
     /** Sort comparator; default is null-safe number-or-string compare. */
     compare?: (a: Value, b: Value) => number;
 }
 
+/** M3: aggregate spec on a column. */
+export type AggregateSpec<Row = any> =
+    | "sum" | "avg" | "min" | "max" | "count"
+    | ((rows: readonly Row[], col: ColumnState<Row>) => unknown);
+
 /** Live reactive state for a column, exposed on `table.columns[i]`. */
 export interface ColumnState<Row = any> {
     readonly key: string;
@@ -53,6 +79,11 @@ export interface ColumnState<Row = any> {
     readonly pinnable: boolean;
     readonly hideable: boolean;
     readonly reorderable: boolean;
+    /** M2 */
+    readonly editable: boolean;
+    readonly filterable: boolean;
+    readonly filter: ((value: unknown, query: string, row: Row) => boolean) | null;
+    readonly filterPlaceholder: string | null;
     readonly minWidth: number;
     readonly maxWidth: number;
     readonly width: Signal<number>;
@@ -68,6 +99,34 @@ export interface FocusedCell {
     columnKey: string;
 }
 
+/** M2: cell currently being edited. Keyed on row identity so the edit
+ *  state survives slot recycling / scroll / sort / filter -- same model
+ *  as `FocusedCell`. */
+export interface EditingCell {
+    rowId: string | number;
+    columnKey: string;
+}
+
+/** M2: payload passed to `onCellEdit` on commit.
+ *
+ *  `newValue` is `string` when the commit came from the DOM editing path
+ *  (double-click / F2 → contenteditable → Enter / Tab / blur). The
+ *  consumer is responsible for coercion when editing typed columns. When
+ *  the consumer calls `commitEdit(explicitValue)` with a non-string,
+ *  `newValue` carries that value through unchanged (typed as unknown).
+ *  `oldValue` is whatever the cell holds pre-edit (post-accessor).
+ *
+ *  The unchanged-guard compares `String(oldValue) !== newValue` for string
+ *  `newValue`s -- so a no-op Enter on a numeric column doesn't fire this
+ *  handler. For non-string explicit values it falls back to strict
+ *  equality. */
+export interface CellEditPayload<Row = any> {
+    row: Row;
+    columnKey: string;
+    oldValue: unknown;
+    newValue: string | unknown;
+}
+
 export interface SortEntry {
     key: string;
     dir: SortDir;
@@ -102,6 +161,117 @@ export interface CreateTableConfig<Row = any> {
     overscan?: number;
     initialFocus?: FocusedCell | null;
     initialSort?: readonly SortEntry[];
+    /** M2: commit hook for cell edits. Receives the row + column key + old +
+     *  new value. The table does NOT mutate rows itself; consumer is
+     *  responsible for the data write (in-memory mutation, backend POST,
+     *  optimistic update, etc.). Skipped when newValue === oldValue.
+     *  Errors thrown by the handler are caught + logged. */
+    onCellEdit?: (payload: CellEditPayload<Row>) => void | Promise<unknown>;
+
+    /** M3: group rows by one or more column keys. `null` (default) or an
+     *  empty array = no grouping. A bare string is normalized to `[string]`.
+     *  Unknown column keys are silently dropped so persisted state that
+     *  outlives a column config survives without crashes. */
+    groupBy?: string | readonly string[] | null;
+    /** M3: pre-seed the collapsed set. Each entry is a group path -- e.g.
+     *  `[["Europe"], ["Asia", "Books"]]`. Unknown paths become no-ops when
+     *  their groups don't exist. */
+    initialCollapsedGroups?: readonly (readonly string[])[];
+    /** M3: append a grand-total entry at the tail of `visibleEntries` when
+     *  any column has an `aggregate` spec. Grand-total aggregates fold
+     *  over `filteredRows()` and are stable across collapse operations. */
+    showGrandTotal?: boolean;
+}
+
+// --- M3: grouping + aggregation types ---------------------------------------
+
+/** One node in the grouped-rows tree. Leaf nodes have `rows` populated and
+ *  `subGroups: null`; internal nodes have `subGroups` populated and
+ *  `rows: null`. Aggregates always fold over leaf rows recursively. */
+export interface GroupNode<Row = any> {
+    readonly depth: number;
+    /** The column key this depth groups on. */
+    readonly key: string;
+    /** The group's identifying value (post-`accessor`). `null` for the
+     *  null / undefined bucket. */
+    readonly value: unknown;
+    /** Path of ancestor values including this node. e.g. `["Europe", "Books"]`. */
+    readonly path: readonly string[];
+    /** Stringified path (U+001F separator) -- the storage key for the
+     *  collapsed-groups Set. */
+    readonly pathStr: string;
+    /** Recursive leaf-row count. */
+    readonly count: number;
+    readonly aggregates: ReadonlyMap<string, unknown>;
+    readonly subGroups: readonly GroupNode<Row>[] | null;
+    readonly rows: readonly Row[] | null;
+}
+
+/** A row in `visibleEntries`. The mount layer dispatches per-slot rendering
+ *  on `type`. */
+export type Entry<Row = any> = DataEntry<Row> | GroupHeaderEntry | GrandTotalEntry;
+
+export interface DataEntry<Row = any> {
+    readonly type: "data";
+    readonly row: Row;
+}
+export interface GroupHeaderEntry {
+    readonly type: "group-header";
+    readonly depth: number;
+    readonly key: string;
+    readonly value: unknown;
+    readonly path: readonly string[];
+    readonly pathStr: string;
+    readonly count: number;
+    readonly aggregates: ReadonlyMap<string, unknown>;
+    readonly isCollapsed: boolean;
+}
+export interface GrandTotalEntry {
+    readonly type: "grand-total";
+    readonly aggregates: ReadonlyMap<string, unknown>;
+    readonly count: number;
+}
+
+// --- Export option types ----------------------------------------------------
+
+/** Row source for export.
+ *
+ *  - `"visible"` (default): the current post-sort view that the user sees.
+ *  - `"all"`: the original master `rows` array, ignoring sort.
+ *  - `"selected"`: the current selection materialized against the master
+ *    array (so the export order matches insertion order, not the sorted
+ *    order the user is looking at). Pass an explicit array if you want
+ *    a different source.
+ *  - Array: an explicit row array (e.g. a paginated page snapshot).
+ */
+export type ExportRowsSource<Row = any> = "visible" | "all" | "selected" | readonly Row[];
+
+/** Column projection for export.
+ *
+ *  - `"visible"` (default): column order matches the current visible order
+ *    and skips hidden columns.
+ *  - `"all"`: all declared columns in declaration order, including hidden.
+ *  - Array: explicit list of column keys (projection + ordering).
+ */
+export type ExportColumnsSelector = "visible" | "all" | readonly string[];
+
+export interface ExportCsvOptions<Row = any> {
+    rows?: ExportRowsSource<Row>;
+    columns?: ExportColumnsSelector;
+    delimiter?: string;
+    quote?: string;
+    headers?: boolean;
+    newline?: string;
+    bom?: boolean;
+    formatter?: (row: Row, col: ColumnState<Row>) => unknown;
+}
+
+export interface ExportJsonOptions<Row = any> {
+    rows?: ExportRowsSource<Row>;
+    columns?: ExportColumnsSelector;
+    indent?: number;
+    format?: "string" | "array";
+    formatter?: (row: Row, col: ColumnState<Row>) => unknown;
 }
 
 // --- Headless core ----------------------------------------------------------
@@ -116,9 +286,35 @@ export interface TableCore<Row = any> {
 
     // ---- Reactive: data ----
     rowsGetter(): readonly Row[];
+    /** M2: filtered rows BEFORE sort. `visibleRows` reads from this; consumers
+     *  can read it directly when they want filter-aware row materializers
+     *  (e.g. count of pre-sort matches, export of filtered-but-not-sorted). */
+    readonly filteredRows: Computed<readonly Row[]>;
     readonly visibleRows: Computed<readonly Row[]>;
     readonly rowCount: Computed<number>;
 
+    // ---- Reactive: grouping + aggregation (M3) ----
+    /** Current grouping keys. Empty array = no grouping (fast path).
+     *  Assign via `setGroupBy`; the raw signal is exposed for read-only
+     *  access + persistence with `@zakkster/lite-persist`. */
+    readonly groupBy: Signal<readonly string[]>;
+    /** Set of collapsed group path-strings (U+001F separator). Mutated via
+     *  `toggleGroup`, `collapseGroup`, `expandGroup`, `collapseAllGroups`,
+     *  `expandAllGroups`. `isGroupCollapsed(path)` is the O(1) predicate. */
+    readonly collapsedGroups: Signal<ReadonlySet<string>>;
+    /** Grouped tree of `filteredRows`, sorted within leaves per `sortChain`.
+     *  `null` when `groupBy` is empty -- consumers can branch on this to
+     *  render a flat list without walking the tree. */
+    readonly groupedRows: Computed<readonly GroupNode<Row>[] | null>;
+    /** Flat interleaved list of `{type: "data" | "group-header" | "grand-total"}`
+     *  entries. Drives the mount layer's slot rendering. Length matches
+     *  `entryCount()`. */
+    readonly visibleEntries: Computed<readonly Entry<Row>[]>;
+    /** Total entry count including group headers + grand total. Drives the
+     *  virtual axis in the mount layer -- `rowCount` (data-only) is kept
+     *  as a separate consumer stat. */
+    readonly entryCount: Computed<number>;
+
     // ---- Reactive: columns ----
     readonly columnOrder: Signal<readonly string[]>;
     readonly visibleColumns: Computed<readonly ColumnState<Row>[]>;
@@ -133,8 +329,12 @@ export interface TableCore<Row = any> {
     readonly leftOffsets: Computed<Map<string, number>>;
     readonly rightOffsets: Computed<Map<string, number>>;
 
-    // ---- Reactive: sort / focus / selection ----
+    // ---- Reactive: sort / filter / focus / selection / editing ----
     readonly sortChain: Signal<readonly SortEntry[]>;
+    /** M2: per-column filter state. Map<columnKey, queryString>. Mutated
+     *  via `setColumnFilter` -- direct .set on the signal works but always
+     *  pass a fresh Map (Object.is-equal mutations would not notify). */
+    readonly columnFilters: Signal<ReadonlyMap<string, string>>;
     readonly focusedCell: Signal<FocusedCell | null>;
     /** Predicate-based selection state. Reading `.set.has(id)` directly is
      *  wrong in all-mode -- use `isSelected(id)` for membership. */
@@ -143,6 +343,14 @@ export interface TableCore<Row = any> {
     /** Reactive O(1) selected count. In all-mode this is
      *  `rowCount() - blacklist.size`; otherwise `whitelist.size`. */
     readonly selectedCount: Computed<number>;
+    /** M2: current cell being edited, or null. Keyed on row identity so it
+     *  survives scroll / sort / filter / slot recycling. */
+    readonly editingCell: Signal<EditingCell | null>;
+    /** M2: in-progress edit value (the contenteditable's textContent).
+     *  mountTable writes to this from `input` events; consumers can also
+     *  set it programmatically to drive an external input. `commitEdit`
+     *  without an explicit value reads this. */
+    readonly editingDraft: Signal<string>;
 
     // ---- Methods: sort ----
     setSort(key: string, dir: SortDir | null): void;
@@ -178,6 +386,55 @@ export interface TableCore<Row = any> {
     setColumnOrder(keys: readonly string[]): void;
     moveColumn(fromKey: string, toKey: string, opts?: { before?: boolean }): void;
 
+    // ---- Methods: filters (M2) ----
+    /** Set or clear a column's filter. Pass `null`/`undefined`/`""` to clear.
+     *  No-op on non-filterable or unknown columns. */
+    setColumnFilter(key: string, value: string | null | undefined): void;
+    /** Clear all filters. No-op + no notify if the filter map is already empty. */
+    clearColumnFilters(): void;
+
+    // ---- Methods: grouping (M3) ----
+    /** Set the grouping keys. Accepts a bare string, a string[], or
+     *  null/empty (no grouping). Unknown column keys are silently dropped.
+     *  Idempotent -- setting the same effective value is a no-op that
+     *  doesn't churn the signal. */
+    setGroupBy(v: string | readonly string[] | null): void;
+    /** Flip the collapsed state for the given group path. */
+    toggleGroup(path: readonly string[]): void;
+    /** Expand a specific group (no-op if already expanded). */
+    expandGroup(path: readonly string[]): void;
+    /** Collapse a specific group (no-op if already collapsed). */
+    collapseGroup(path: readonly string[]): void;
+    /** Expand every group -- clears the collapsed set. */
+    expandAllGroups(): void;
+    /** Collapse every group in the current tree. Walks `groupedRows()` once. */
+    collapseAllGroups(): void;
+    /** O(1) predicate: is this exact group path currently collapsed? */
+    isGroupCollapsed(path: readonly string[]): boolean;
+    /** Given an entry index (typically `axis.start()`), return the group
+     *  headers that CONTAIN it -- one per depth level, deepest last.
+     *  Used by consumers implementing sticky group headers. Returns [] for
+     *  the ungrouped fast path or when the target is above the first header. */
+    groupAncestryAt(entryIndex: number): readonly GroupHeaderEntry[];
+
+    // ---- Methods: editing (M2) ----
+    /** Start editing the (rowId, columnKey) cell. No-op on non-editable
+     *  columns. Auto-commits any in-flight edit of a different cell. Idempotent
+     *  on the same cell (does not re-seed the draft). */
+    startEdit(rowId: string | number, columnKey: string): void;
+    /** Commit the in-flight edit. With no argument, reads from `editingDraft`.
+     *  Fires `onCellEdit` only when `newValue !== oldValue`. Clears edit state. */
+    commitEdit(value?: string): void;
+    /** Discard the in-flight edit without firing `onCellEdit`. */
+    cancelEdit(): void;
+    /** O(1) predicate. */
+    isEditing(rowId: string | number, columnKey: string): boolean;
+
+    // ---- Methods: export ----
+    exportCsv(opts?: ExportCsvOptions<Row>): string;
+    exportJson(opts?: ExportJsonOptions<Row> & { format?: "string" }): string;
+    exportJson<R = Row>(opts: ExportJsonOptions<Row> & { format: "array" }): object[];
+
     // ---- Methods: focus ----
     moveFocus(direction: FocusDirection, opts?: { pageSize?: number }): void;