@svgrid/grid 2.2.31 → 2.2.33

package/src/core.ts

@@ -45,6 +45,11 @@ export type CellSpanParams<TData extends RowData = RowData> = {
   value: unknown
 }
 
+/** The raw option list a column's `editorOptions` can supply. */
+export type EditorOptionSource = ReadonlyArray<
+  string | number | { value: string | number; label?: string; color?: string }
+>
+
 /** Params passed to a column's `valueParser(...)` on edit commit. */
 export type ValueParserParams<TData extends RowData = RowData> = {
   /** The value after built-in per-`editorType` coercion. */
@@ -172,6 +177,16 @@ export function applyGroupAggregate<TData extends RowData>(
   }
 }
 
+/**
+ * A column definition.
+ *
+ * `TFeatures` is a phantom parameter - it is threaded through nested
+ * `columns` groups but no member depends on it, so `{}`, `TableFeatures` and
+ * `typeof features` are all interchangeable here. It is deliberately left
+ * WITHOUT a default: `ColumnDef<Row>` would otherwise bind `Row` to this slot
+ * and silently type your data as `RowData`, losing every field-name check.
+ * Prefer {@link GridColumns} / {@link GridColumnDef} for the common case.
+ */
 export type ColumnDef<TFeatures extends TableFeatures, TData extends RowData> = {
   id?: string
   field?: keyof TData & string
@@ -336,16 +351,20 @@ export type ColumnDef<TFeatures extends TableFeatures, TData extends RowData> =
    *
    * Pass a function `(row) => options` for row-dependent (cascading)
    * options - e.g. City options that depend on Country in the same row.
+   *
+   * Either form may return a **Promise**, for options that come from the
+   * server. While it resolves, the editor shows a loading state and the cell
+   * renders its raw value.
+   *
+   * Results are cached so reopening an editor does not refetch: a static source
+   * per column, a per-row source per row AND per that row's data - so a cascade
+   * reloads by itself when the cell it depends on is edited. Call
+   * `api.refreshEditorOptions(columnId?)` when the list changes server-side.
    */
   editorOptions?:
-    | ReadonlyArray<
-        string | number | { value: string | number; label?: string; color?: string }
-      >
-    | ((
-        row: TData,
-      ) => ReadonlyArray<
-        string | number | { value: string | number; label?: string; color?: string }
-      >)
+    | EditorOptionSource
+    | Promise<EditorOptionSource>
+    | ((row: TData) => EditorOptionSource | Promise<EditorOptionSource>)
   /** When true, list/chips allow multiple selections. Cell value becomes an array. */
   editorMultiple?: boolean
   /** Separator used when joining array values for the readonly cell display. Defaults to ', '. */
@@ -409,6 +428,23 @@ export type ColumnDef<TFeatures extends TableFeatures, TData extends RowData> =
     | ((ctx: CellContext<TData>) => string | ReadonlyArray<string> | Record<string, boolean> | undefined | null)
 }
 
+/**
+ * A column definition keyed only by your row type - the ergonomic form of
+ * {@link ColumnDef}, whose first parameter is a phantom feature bag that is
+ * almost always `{}`.
+ *
+ * ```ts
+ * const columns: GridColumns<Person> = [{ field: 'firstName', header: 'Name' }]
+ * ```
+ *
+ * Interchangeable with `ColumnDef<{}, TData>` and `ColumnDef<typeof features,
+ * TData>` in both directions, so it mixes freely with existing code.
+ */
+export type GridColumnDef<TData extends RowData = RowData> = ColumnDef<TableFeatures, TData>
+
+/** An array of {@link GridColumnDef} - what you pass to `<SvGrid columns={...}>`. */
+export type GridColumns<TData extends RowData = RowData> = Array<GridColumnDef<TData>>
+
 export type Column<TData extends RowData> = {
   id: string
   columnDef: ColumnDef<any, TData>
@@ -647,6 +683,119 @@ export function createGroupedRowModel<TData extends RowData>(): RowModelFactory<
     return buildGroups(rows, 0, 0, 'group')
   }
 }
+export type TreeRowModelOptions = {
+  /** Field holding each row's parent id. Rows with no parent are roots. */
+  parentField: string
+  /** Field holding the row's own id. Defaults to `'id'`. */
+  idField?: string
+}
+
+/**
+ * Client-side tree data: nest the grid's own flat rows into a parent/child
+ * hierarchy that `createExpandedRowModel` then walks.
+ *
+ * This works on the rows the grid already built rather than on raw data, so
+ * tree rows keep their cells, editing, selection and formatting - they are real
+ * data rows that happen to have children, not synthetic banners like grouping's.
+ * That is also why the model is parent-id based: nested source arrays never
+ * become rows (the grid only builds rows for `data`), so nested input is
+ * flattened first with {@link flattenTreeData}. One code path, no duplicated
+ * row construction.
+ *
+ * Rows are tagged `__treeRow` so `isGroupRow` does not mistake an expandable
+ * data row for a full-width group banner.
+ */
+export function createTreeRowModel<TData extends RowData>(
+  options: TreeRowModelOptions,
+): RowModelFactory<TData> {
+  const { parentField, idField = 'id' } = options
+  return ({ table, rows }) => {
+    if (!rows.length) return rows
+    const keyOf = (row: Row<TData>) => (row.original as any)?.[idField]
+    const parentOf = (row: Row<TData>) => (row.original as any)?.[parentField]
+
+    const present = new Set<unknown>()
+    for (const row of rows) present.add(keyOf(row))
+
+    const childrenByParent = new Map<unknown, Array<Row<TData>>>()
+    const roots: Array<Row<TData>> = []
+    for (const row of rows) {
+      const parent = parentOf(row)
+      // A row whose parent is absent (filtered out, or never existed) becomes a
+      // root rather than disappearing - silently dropping rows is worse than a
+      // shallower tree. Self-parenting is treated the same way.
+      if (parent == null || parent === keyOf(row) || !present.has(parent)) {
+        roots.push(row)
+        continue
+      }
+      const list = childrenByParent.get(parent) ?? []
+      list.push(row)
+      childrenByParent.set(parent, list)
+    }
+
+    // Guards a cycle in the parent chain from recursing forever.
+    const seen = new Set<unknown>()
+    const build = (row: Row<TData>, depth: number): Row<TData> => {
+      const key = keyOf(row)
+      const id = row.id
+      if (seen.has(key)) {
+        return { ...row, depth, subRows: [], getCanExpand: () => false } as Row<TData>
+      }
+      seen.add(key)
+      const subRows = (childrenByParent.get(key) ?? []).map((child) => build(child, depth + 1))
+      return {
+        ...row,
+        depth,
+        subRows,
+        leafCount: subRows.reduce((n, sub) => n + 1 + (sub.leafCount ?? 0), 0),
+        __treeRow: true,
+        getCanExpand: () => subRows.length > 0,
+        getIsExpanded: () => Boolean((table.getState().expanded ?? {})[id]),
+        toggleExpanded: () => {
+          table.setExpanded((prev) => ({ ...prev, [id]: !prev[id] }))
+        },
+      } as Row<TData>
+    }
+
+    return roots.map((root) => build(root, 0))
+  }
+}
+
+export type FlattenTreeOptions = {
+  /** Field holding an array of child objects. */
+  childrenField: string
+  /** Field holding each object's id. Defaults to `'id'`. */
+  idField?: string
+  /** Field to WRITE the resolved parent id onto. Defaults to `'__parentId'`. */
+  parentField?: string
+}
+
+/**
+ * Flatten nested tree data into the flat parent-id shape `createTreeRowModel`
+ * consumes, stamping each child with its parent's id.
+ *
+ * Children are emitted directly after their parent so the natural order already
+ * matches the rendered tree. The `childrenField` array is left on the objects
+ * (harmless, and callers often still want it); only the parent link is added.
+ */
+export function flattenTreeData<T extends RowData>(
+  data: ReadonlyArray<T>,
+  options: FlattenTreeOptions,
+): T[] {
+  const { childrenField, idField = 'id', parentField = '__parentId' } = options
+  const out: T[] = []
+  const walk = (nodes: ReadonlyArray<T>, parentId: unknown) => {
+    for (const node of nodes) {
+      const flat = { ...node, [parentField]: parentId } as T
+      out.push(flat)
+      const kids = (node as any)[childrenField]
+      if (Array.isArray(kids) && kids.length) walk(kids as ReadonlyArray<T>, (node as any)[idField])
+    }
+  }
+  walk(data, null)
+  return out
+}
+
 export function createExpandedRowModel<TData extends RowData>(): RowModelFactory<TData> {
   return ({ table, rows }) => {
     const expanded: ExpandedState = table.getState().expanded ?? {}

package/src/createMenu.svelte.ts

@@ -66,7 +66,6 @@ export type MenuItemProps = {
   onclick: () => void
 }
 
-let uid = 0
 
 export function createMenu(config: MenuConfig) {
   const items = () => config.items()

package/src/editing.test.ts

@@ -154,7 +154,7 @@ describe('isCellEditable', () => {
       data: [{ a: 'hello' }],
     })
     ed.isCellEditable(ctx.allColumns[0], ctx.allRows[0])
-    const cc = spy.mock.calls[0][0]
+    const cc = spy.mock.calls[0]![0]
     expect(cc.getValue()).toBe('hello')
     expect(cc.cell.getValue()).toBe('hello')
     expect(cc.cell.getContext()).toBe(cc)

package/src/editing.ts

@@ -2,126 +2,23 @@
 // reading/writing controller state via the `ctx` handle; the reactive core
 // ($state/$derived/$effect) stays in the controller.
 import {
-  applyExcelFilter,
-  normalizeForFilter,
-  createColumnVirtualizer,
-  createCoreRowModel,
-  createExpandedRowModel,
-  createFilteredRowModel,
-  createGroupedRowModel,
-  createPaginatedRowModel,
-  createSvelteVirtualizer,
-  createSortedRowModel,
-  createSvGrid,
-  filterFns,
-  getGridCellA11yProps,
-  getGridCellDomId,
-  getGridHeaderA11yProps,
-  getGridRootA11yProps,
-  getGridRowA11yProps,
   parseEditorValue,
-  normalizeEditorOptions,
-  sortFns,
-  tableFeatures,
-  rowSortingFeature,
-  columnFilteringFeature,
-  columnGroupingFeature,
   type CellContext,
-  type EditorContext,
-  type CellEditorOption,
   type CellEditorType,
-  type CellFormatter,
-  type CellFormatConfig,
   type Column,
-  type ColumnDef,
   type Row,
   type RowData,
-  type SvGridApi,
   type TableFeatures,
 } from "./index";
 import "./sv-grid-scrollbar";
-import type { Snippet } from "svelte";
-import { getKeyboardIntent, getNextActiveCell } from "./keyboard";
+import { getNextActiveCell } from "./keyboard";
 import {
-  formatNumericWithConfig,
-  getDateFormatter,
-  resolveDatePattern,
-} from "./cell-formatting";
-import {
-  RenderSnippetConfig,
-  RenderComponentConfig,
-} from "./render-component";
-import { buildFillPattern } from "./fill-patterns";
-import { buildSparkline, toSparklineValues } from "./sparkline";
-import {
-  resolveCellFormat,
-  computeColumnStat,
-  formatsNeedingStats,
-  type ColumnStat,
-  type ResolvedCellFormat,
-} from "./conditional-formatting";
-import SvGridDropdown from "./SvGridDropdown.svelte";
-import type {
-  Props,
-  SelectionPoint,
-  SelectionRange,
-  CellEditState,
-  FilterOperator,
-  FilterOption,
-  MenuPosition,
-} from "./SvGrid.types";
-import {
-  cfTextStyle,
-  fmtStat,
   getCellKey,
-  resolveClassList,
-  toDateInputValue,
-  toDateTimeLocalInputValue,
-  getEditableInputValue,
-  getEditorInputType,
   toValueArray,
-  getOptionLabel,
-  getOptionColor,
-  colorfulChipStyle,
-  getEditorClass,
-  asDate,
-  clampMenuX,
-  cssEscape,
-  rawToNumber,
-  formatFacetNumber,
-  formatFacetDate,
 } from "./SvGrid.helpers";
-import { createSelection } from "./selection";
-import { createColumns } from "./columns";
-import { createGridApi } from "./build-api";
-import { createClipboard } from "./clipboard";
-import {
-  filterOperatorOptions,
-  fallbackOperatorOption,
-  TEXT_OPERATORS,
-  NUMBER_OPERATORS,
-  DATE_OPERATORS,
-  CHECKBOX_OPERATORS,
-  operatorOption,
-  operatorsForColumn,
-  defaultOperatorFor,
-  operatorLabelFor,
-} from "./filter-operators";
-import {
-  type FacetBucket,
-  isBucketableColumn,
-  buildBuckets,
-  isInBucket,
-} from "./facet-buckets";
 import {
   getColumnBaseValue,
   isGroupRow,
-  toolPanelHeaderLabel,
-  formatSummaryNumeric,
-  getColumnAlign,
-  getPinnedCellValue,
-  getColumnAccessorValue,
-  columnDefMatchesId,
 } from "./cell-values";
 
 type HistoryStep = {
@@ -224,7 +121,7 @@ export function createEditing<
     ) {
       return false;
     }
-    if (editorType === "number" && !/[0-9.+\-]/.test(char)) return false;
+    if (editorType === "number" && !/[0-9.+-]/.test(char)) return false;
     ctx.editorSelectAll = false;
     ctx.editingCell = {
       rowId: row.id,

package/src/editor-contract.ts

@@ -68,16 +68,23 @@ export type SvEditorProps = {
  * The interaction surface an editor exposes when embedded as a grid cell editor.
  * Standalone usage ignores these; the grid supplies them so every editor shares
  * one commit / cancel / move contract (Enter commits, Escape cancels, Tab moves)
- * instead of each cell-editor re-implementing key handling. Consumed in Phase 2
- * (the editor registry).
+ * instead of each cell-editor re-implementing key handling.
+ *
+ * `CellEditorContext` (editor-registry.ts) extends this type, so what the grid
+ * hands a registered editor and what this contract promises are the same thing
+ * by construction rather than by convention.
  */
 export type EditorInteraction<V = unknown> = {
-  /** Commit the current value and stop editing (Enter, option pick, blur-commit). */
-  onCommit?: (value: V) => void
+  /**
+   * Commit the value and stop editing (Enter, option pick, blur-commit).
+   * The argument is optional: an editor that has been reporting through
+   * `onChange` can just call `onCommit()` to commit what the grid already has.
+   */
+  onCommit?: (value?: V) => void
   /** Abandon the edit and restore the previous value (Escape). */
   onCancel?: () => void
   /** Commit, then move to the adjacent cell (Tab = 1, Shift+Tab = -1). */
-  onCommitAndMove?: (value: V, direction: 1 | -1) => void
+  onCommitAndMove?: (value: V | undefined, direction: 1 | -1) => void
   /** Ask the surrounding popover/panel to close without committing. */
   onRequestClose?: () => void
   /** True while mounted inside a grid cell (lets an editor tune autofocus etc.). */

package/src/editor-registry.grid.test.ts

@@ -73,7 +73,6 @@ afterEach(() => {
 
 describe('registry wiring in SvGrid', () => {
   it('mounts a registered component when a custom-editorType cell edits', async () => {
-    let committed: unknown = undefined
     registerCellEditor('stars', {
       component: SvRating,
       props: (ctx) => ({
@@ -90,7 +89,54 @@ describe('registry wiring in SvGrid', () => {
       // The registered SvRating editor is mounted in the editing overlay.
       const rating = target.querySelector('.sv-rating')
       expect(rating).not.toBeNull()
-      void committed
+    } finally {
+      destroy()
+    }
+  })
+
+  it('hands the editor the full EditorInteraction contract, not a subset', async () => {
+    // The contract type used to be documented but never supplied: the registry
+    // passed only value/onChange/onCommit/onCancel, so an editor written against
+    // `EditorInteraction` (Tab-to-move, dismiss-without-commit, in-cell tuning)
+    // silently got undefined for half of it.
+    let seen: Record<string, unknown> = {}
+    registerCellEditor('stars', {
+      component: SvRating,
+      props: (ctx) => {
+        seen = ctx as unknown as Record<string, unknown>
+        return { value: ctx.value }
+      },
+    })
+
+    const { api, target, destroy } = await mountGrid()
+    try {
+      api.startEditing(0, 'score')
+      await tick()
+      await tick()
+      expect(typeof seen.onCommit).toBe('function')
+      expect(typeof seen.onCancel).toBe('function')
+      expect(typeof seen.onChange).toBe('function')
+      expect(typeof seen.onCommitAndMove).toBe('function')
+      expect(typeof seen.onRequestClose).toBe('function')
+      expect(seen.inCell).toBe(true)
+      expect(seen.rowId).toBeTruthy()
+      expect(seen.columnId).toBe('score')
+      void target
+    } finally {
+      destroy()
+    }
+  })
+
+  it('defaults to passing the whole contract when a registration has no props mapping', async () => {
+    // A registration with no `props` should still work for a contract-aware
+    // editor - that is the point of the default mapping.
+    registerCellEditor('stars', SvRating)
+    const { api, target, destroy } = await mountGrid()
+    try {
+      api.startEditing(0, 'score')
+      await tick()
+      await tick()
+      expect(target.querySelector('.sv-rating')).not.toBeNull()
     } finally {
       destroy()
     }

package/src/editor-registry.test.ts

@@ -15,6 +15,8 @@ import {
 const Fake = (() => {}) as unknown as Component<any>
 const Fake2 = (() => {}) as unknown as Component<any>
 
+// onCommitAndMove / onRequestClose / inCell are deliberately left off: the
+// tests below assert that defaultEditorProps maps them to undefined.
 function ctx(overrides: Partial<CellEditorContext> = {}): CellEditorContext {
   return {
     value: 42,
@@ -24,7 +26,7 @@ function ctx(overrides: Partial<CellEditorContext> = {}): CellEditorContext {
     onCommit: () => {},
     onCancel: () => {},
     ...overrides,
-  }
+  } as CellEditorContext
 }
 
 afterEach(() => {

package/src/editor-registry.ts

@@ -20,9 +20,20 @@
  * mounting.
  */
 import type { Component } from 'svelte'
+import type { EditorInteraction } from './editor-contract'
 
-/** Context the grid hands a cell editor when it mounts one for an edit. */
-export type CellEditorContext<T = unknown> = {
+/**
+ * Context the grid hands a cell editor when it mounts one for an edit.
+ *
+ * Extends {@link EditorInteraction} - the shared commit / cancel / move contract
+ * the `Sv*` editors are written against - and narrows the parts the grid always
+ * supplies, so a registered component and a built-in editor speak the same
+ * language. `onCommitAndMove`, `onRequestClose` and `inCell` come from the
+ * contract and are always populated by the grid.
+ */
+export type CellEditorContext<T = unknown> = Required<
+  Pick<EditorInteraction<T>, 'onCommit' | 'onCancel' | 'onCommitAndMove' | 'onRequestClose' | 'inCell'>
+> & {
   /** The value currently being edited. */
   value: T
   /** Id of the row being edited. */
@@ -31,10 +42,6 @@ export type CellEditorContext<T = unknown> = {
   columnId: string
   /** Update the in-progress value WITHOUT ending the edit. */
   onChange: (value: T) => void
-  /** Commit the value and stop editing (optionally pass a final value). */
-  onCommit: (value?: T) => void
-  /** Discard changes and stop editing (returns focus to the grid). */
-  onCancel: () => void
 }
 
 /** How a registered component is mounted and wired for a cell edit. */
@@ -87,13 +94,22 @@ export function registeredCellEditorTypes(): string[] {
   return [...registry.keys()]
 }
 
-/** The default context → props mapping used when a registration has no `props`. */
+/**
+ * The default context → props mapping used when a registration has no `props`.
+ * Passes the whole {@link EditorInteraction} surface, so an editor written
+ * against the shared contract works when registered with no mapping at all.
+ * Svelte ignores props a component doesn't declare, so the extra keys are inert
+ * for a simple editor that only wants `value` + `onCommit`.
+ */
 export function defaultEditorProps(ctx: CellEditorContext): Record<string, unknown> {
   return {
     value: ctx.value,
     onChange: ctx.onChange,
     onCommit: ctx.onCommit,
     onCancel: ctx.onCancel,
+    onCommitAndMove: ctx.onCommitAndMove,
+    onRequestClose: ctx.onRequestClose,
+    inCell: ctx.inCell,
   }
 }
 

package/src/export-format.ts

@@ -521,6 +521,9 @@ const XML_ESCAPE: Record<string, string> = {
 }
 function xmlText(value: unknown): string {
   const s = value == null ? '' : value instanceof Date ? value.toISOString() : String(value)
+  // Stripping control characters is the point: XML 1.0 forbids them outright,
+  // so a stray \x00 from a data source would produce an unopenable file.
+  // eslint-disable-next-line no-control-regex
   return s.replace(/[\x00-\x08\x0B\x0C\x0E-\x1F]/g, '').replace(/[&<>"']/g, (c) => XML_ESCAPE[c]!)
 }
 /** Coerce a field name into a valid XML element name. */