@svgrid/grid 1.2.34 → 2.0.1

package/src/editor-contract.ts

@@ -2,15 +2,19 @@
  * The shared "editor contract" for the SvGrid UI kit.
  *
  * Every value-bearing editor (inputs, selects, pickers) accepts this common set
- * of props so forms, validation and accessibility behave IDENTICALLY across the
- * kit - the same spirit as the grid's headless core, applied to the editors.
- * Components spread their own `value` / options / behavior on top of this base.
+ * of props so forms, validation, accessibility, direction (RTL) and localization
+ * behave IDENTICALLY across the kit - the same spirit as the grid's headless
+ * core, applied to the editors. Components spread their own `value` / options /
+ * behavior on top of this base.
  *
  * Framework-free (no Svelte, no DOM) so it can be unit-tested and reused.
  */
 
 export type EditorSize = 'sm' | 'md' | 'lg'
 
+/** Text direction. `'auto'` defers to the surrounding document/CSS. */
+export type EditorDir = 'ltr' | 'rtl' | 'auto'
+
 /** Props shared by every value-bearing editor in the kit. */
 export type SvEditorProps = {
   /** Disable interaction + form submission. */
@@ -23,26 +27,72 @@ export type SvEditorProps = {
   invalid?: boolean
   /** Error message; when set it is announced via `aria-describedby` and shown. */
   error?: string
+  /** Visible field label, rendered above the control and wired via `for`/`id`. */
+  label?: string
+  /** Helper text shown under the control and announced via `aria-describedby`. */
+  hint?: string
   /** Control size / density. */
   size?: EditorSize
+  /**
+   * Text direction. `'rtl'` mirrors layout for Arabic/Hebrew/etc.; `'auto'` (the
+   * default) inherits from the surrounding document so a page-level `dir` wins.
+   */
+  dir?: EditorDir
   /** Form field name; the editor emits a hidden input carrying its value. */
   name?: string
-  /** Root/control element id (the error-text id derives from it). */
+  /** Root/control element id (the label/hint/error ids derive from it). */
   id?: string
-  /** Accessible name when there is no visible `<label>`. */
+  /** Accessible name when there is no visible `label`. */
   ariaLabel?: string
 }
 
+/**
+ * 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).
+ */
+export type EditorInteraction<V = unknown> = {
+  /** Commit the current value and stop editing (Enter, option pick, blur-commit). */
+  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
+  /** Ask the surrounding popover/panel to close without committing. */
+  onRequestClose?: () => void
+  /** True while mounted inside a grid cell (lets an editor tune autofocus etc.). */
+  inCell?: boolean
+}
+
 /** Stable DOM id for an editor's error text, for `aria-describedby` wiring. */
 export const editorErrorId = (id?: string): string | undefined => (id ? `${id}__error` : undefined)
 
+/** Stable DOM id for an editor's hint text, for `aria-describedby` wiring. */
+export const editorHintId = (id?: string): string | undefined => (id ? `${id}__hint` : undefined)
+
+let _autoId = 0
+/**
+ * Generate a stable-per-instance element id. Call ONCE per component instance
+ * (e.g. `const uid = provided ?? nextEditorId()`) so label/hint/error wiring
+ * always has an anchor even when the consumer passes no `id`.
+ */
+export const nextEditorId = (prefix = 'sv-ed'): string => `${prefix}-${_autoId++}`
+
 /** A subset of {@link SvEditorProps} that drives ARIA on the focusable control. */
-export type EditorAriaState = Pick<SvEditorProps, 'id' | 'invalid' | 'required' | 'error' | 'ariaLabel'>
+export type EditorAriaState = Pick<
+  SvEditorProps,
+  'id' | 'invalid' | 'required' | 'error' | 'hint' | 'ariaLabel'
+>
 
 /**
  * ARIA attributes for the focusable control of an editor, derived from its state.
  * Spread onto the input/button/combobox:
- * `<input {...editorAria({ id, invalid, required, error, ariaLabel })} />`
+ * `<input {...editorAria({ id, invalid, required, error, hint, ariaLabel })} />`
+ *
+ * `aria-describedby` points at the error text (when invalid) and/or the hint
+ * text - both ids derive from `id`, so pass a stable `id` (see {@link nextEditorId}).
  * Undefined values are omitted by Svelte, so unset props add no attributes.
  */
 export function editorAria(state: EditorAriaState): {
@@ -51,10 +101,39 @@ export function editorAria(state: EditorAriaState): {
   'aria-describedby': string | undefined
   'aria-label': string | undefined
 } {
+  const described = [
+    state.error ? editorErrorId(state.id) : undefined,
+    state.hint ? editorHintId(state.id) : undefined,
+  ].filter(Boolean)
   return {
     'aria-invalid': state.invalid ? 'true' : undefined,
     'aria-required': state.required ? 'true' : undefined,
-    'aria-describedby': state.error ? editorErrorId(state.id) : undefined,
+    'aria-describedby': described.length ? described.join(' ') : undefined,
     'aria-label': state.ariaLabel,
   }
 }
+
+/**
+ * Merge a component's default message strings with a consumer's `messages`
+ * override, so every editor can be fully localized from the outside.
+ *
+ * ```ts
+ * const M = { clear: 'Clear', noResults: 'No results' }
+ * const messages = resolveMessages(M, props.messages) // Partial override
+ * ```
+ *
+ * Undefined/empty overrides fall back to the default, so a partial `messages`
+ * object only replaces the keys it sets.
+ */
+export function resolveMessages<T extends Record<string, string>>(
+  defaults: T,
+  overrides?: Partial<T> | null,
+): T {
+  if (!overrides) return defaults
+  const out = { ...defaults }
+  for (const k in overrides) {
+    const v = overrides[k]
+    if (v != null && v !== '') out[k] = v as T[Extract<keyof T, string>]
+  }
+  return out
+}

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

@@ -0,0 +1,98 @@
+/**
+ * Integration test for the cell-editor registry wiring in SvGrid.svelte: a
+ * component registered via `registerCellEditor` is actually mounted when a cell
+ * of that custom `editorType` starts editing.
+ */
+import { afterEach, describe, expect, it } from 'vitest'
+import { mount, unmount } from 'svelte'
+import SvGrid from './SvGrid.svelte'
+import SvRating from './SvRating.svelte'
+import {
+  registerCellEditor,
+  unregisterCellEditor,
+  createCoreRowModel,
+  createFilteredRowModel,
+  createPaginatedRowModel,
+  createSortedRowModel,
+  sortFns,
+  tableFeatures,
+  columnFilteringFeature,
+  rowSortingFeature,
+} from './index'
+import type { ColumnDef, SvGridApi } from './index'
+
+type Row = { id: number; name: string; score: number }
+
+const features = tableFeatures({ columnFilteringFeature, rowSortingFeature })
+const rows: Row[] = [
+  { id: 1, name: 'Ada', score: 3 },
+  { id: 2, name: 'Alan', score: 5 },
+]
+const cols: ColumnDef<typeof features, Row>[] = [
+  { field: 'name', header: 'Name', width: 200, editorType: 'text' },
+  // Custom editor type resolved through the registry:
+  { field: 'score', header: 'Score', width: 160, editorType: 'stars' },
+]
+
+const tick = () => new Promise<void>((r) => queueMicrotask(r))
+
+function mountGrid() {
+  return new Promise<{ api: SvGridApi<typeof features, Row>; target: HTMLElement; destroy: () => void }>(
+    (res, rej) => {
+      const target = document.createElement('div')
+      document.body.appendChild(target)
+      const app = mount(SvGrid, {
+        target,
+        props: {
+          data: rows,
+          columns: cols,
+          features,
+          _rowModels: {
+            coreRowModel: createCoreRowModel(),
+            filteredRowModel: createFilteredRowModel(),
+            sortedRowModel: createSortedRowModel(sortFns),
+            paginatedRowModel: createPaginatedRowModel(),
+          },
+          rowHeight: 36,
+          containerHeight: 300,
+          virtualization: false,
+          enableInlineEditing: true,
+          onApiReady(api: SvGridApi<typeof features, Row>) {
+            res({ api, target, destroy: () => { unmount(app); target.remove() } })
+          },
+        } as any,
+      })
+      queueMicrotask(() => rej.length && undefined)
+    },
+  )
+}
+
+afterEach(() => {
+  unregisterCellEditor('stars')
+})
+
+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) => ({
+        value: ctx.value,
+        onChange: (v: number) => ctx.onCommit(v),
+      }),
+    })
+
+    const { api, target, destroy } = await mountGrid()
+    try {
+      api.startEditing(0, 'score')
+      await tick()
+      await tick()
+      // The registered SvRating editor is mounted in the editing overlay.
+      const rating = target.querySelector('.sv-rating')
+      expect(rating).not.toBeNull()
+      void committed
+    } finally {
+      destroy()
+    }
+  })
+})

package/src/editor-registry.test.ts

@@ -0,0 +1,86 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import type { Component } from 'svelte'
+import {
+  registerCellEditor,
+  getCellEditor,
+  hasCellEditor,
+  unregisterCellEditor,
+  registeredCellEditorTypes,
+  defaultEditorProps,
+  resolveEditorProps,
+  type CellEditorContext,
+} from './editor-registry'
+
+// A stand-in component (the registry never invokes it; the grid mounts it).
+const Fake = (() => {}) as unknown as Component<any>
+const Fake2 = (() => {}) as unknown as Component<any>
+
+function ctx(overrides: Partial<CellEditorContext> = {}): CellEditorContext {
+  return {
+    value: 42,
+    rowId: 'r1',
+    columnId: 'score',
+    onChange: () => {},
+    onCommit: () => {},
+    onCancel: () => {},
+    ...overrides,
+  }
+}
+
+afterEach(() => {
+  for (const t of registeredCellEditorTypes()) unregisterCellEditor(t)
+})
+
+describe('editor-registry', () => {
+  it('registers a bare component with the default mapping', () => {
+    registerCellEditor('stars', Fake)
+    expect(hasCellEditor('stars')).toBe(true)
+    const reg = getCellEditor('stars')!
+    expect(reg.component).toBe(Fake)
+    expect(reg.props).toBeUndefined()
+  })
+
+  it('registers a full registration with custom prop mapping', () => {
+    const props = (c: CellEditorContext) => ({ v: c.value })
+    registerCellEditor('slider', { component: Fake, props, autoOpen: true })
+    const reg = getCellEditor('slider')!
+    expect(reg.component).toBe(Fake)
+    expect(reg.autoOpen).toBe(true)
+    expect(reg.props).toBe(props)
+  })
+
+  it('re-registering replaces the previous entry', () => {
+    registerCellEditor('x', Fake)
+    registerCellEditor('x', Fake2)
+    expect(getCellEditor('x')!.component).toBe(Fake2)
+  })
+
+  it('unregister + registeredCellEditorTypes reflect the map', () => {
+    registerCellEditor('a', Fake)
+    registerCellEditor('b', Fake)
+    expect(registeredCellEditorTypes().sort()).toEqual(['a', 'b'])
+    unregisterCellEditor('a')
+    expect(hasCellEditor('a')).toBe(false)
+    expect(registeredCellEditorTypes()).toEqual(['b'])
+  })
+
+  it('getCellEditor returns undefined for unknown types', () => {
+    expect(getCellEditor('nope')).toBeUndefined()
+  })
+
+  it('defaultEditorProps maps value + the three callbacks', () => {
+    const onChange = vi.fn(), onCommit = vi.fn(), onCancel = vi.fn()
+    const props = defaultEditorProps(ctx({ onChange, onCommit, onCancel }))
+    expect(props).toEqual({ value: 42, onChange, onCommit, onCancel })
+  })
+
+  it('resolveEditorProps uses the custom mapping when present, else default', () => {
+    registerCellEditor('custom', { component: Fake, props: (c) => ({ only: c.value }) })
+    expect(resolveEditorProps(getCellEditor('custom')!, ctx())).toEqual({ only: 42 })
+
+    registerCellEditor('plain', Fake)
+    const props = resolveEditorProps(getCellEditor('plain')!, ctx())
+    expect(props.value).toBe(42)
+    expect(typeof props.onCommit).toBe('function')
+  })
+})

package/src/editor-registry.ts

@@ -0,0 +1,106 @@
+/**
+ * editor-registry - the extension point that opens up the grid's cell editors.
+ *
+ * Historically SvGrid rendered cell editors through a fixed `{#if editorType ===
+ * ...}` chain over a closed `CellEditorType` union. This registry lets any
+ * component - a built-in `Sv*` editor or one you author - be mounted for a
+ * column by name, wired to one uniform in-cell contract (change / commit /
+ * cancel). Register once at module load:
+ *
+ * ```ts
+ * import { registerCellEditor } from '@svgrid/grid'
+ * import StarRating from './StarRating.svelte'
+ * registerCellEditor('stars', StarRating)
+ * // then: columns = [{ field: 'score', editorType: 'stars' }]
+ * ```
+ *
+ * The registered component receives the {@link CellEditorContext} as props
+ * (value + onChange/onCommit/onCancel), or a custom mapping via `props`.
+ * Framework-light: this file only holds the Map + helpers; the grid does the
+ * mounting.
+ */
+import type { Component } from 'svelte'
+
+/** Context the grid hands a cell editor when it mounts one for an edit. */
+export type CellEditorContext<T = unknown> = {
+  /** The value currently being edited. */
+  value: T
+  /** Id of the row being edited. */
+  rowId: string
+  /** Id of the column being edited. */
+  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. */
+export type CellEditorRegistration = {
+  /** The Svelte component to mount in the editing cell. */
+  component: Component<any>
+  /**
+   * Map the editing context to the component's props. Defaults to
+   * {@link defaultEditorProps} (value + onChange/onCommit/onCancel).
+   */
+  props?: (ctx: CellEditorContext) => Record<string, unknown>
+  /** Hint that the editor should open its popover immediately on mount. */
+  autoOpen?: boolean
+}
+
+const registry = new Map<string, CellEditorRegistration>()
+
+/**
+ * Register a cell editor under `type`. Pass a component (uses the default prop
+ * mapping) or a full {@link CellEditorRegistration} for custom prop mapping.
+ * Re-registering the same type replaces it.
+ */
+export function registerCellEditor(
+  type: string,
+  registration: CellEditorRegistration | Component<any>,
+): void {
+  registry.set(
+    type,
+    typeof registration === 'function' ? { component: registration } : registration,
+  )
+}
+
+/** Look up a registered cell editor by type. */
+export function getCellEditor(type: string): CellEditorRegistration | undefined {
+  return registry.get(type)
+}
+
+/** Whether a custom editor is registered for `type`. */
+export function hasCellEditor(type: string): boolean {
+  return registry.has(type)
+}
+
+/** Remove a registered cell editor. */
+export function unregisterCellEditor(type: string): void {
+  registry.delete(type)
+}
+
+/** All registered custom editor type names. */
+export function registeredCellEditorTypes(): string[] {
+  return [...registry.keys()]
+}
+
+/** The default context → props mapping used when a registration has no `props`. */
+export function defaultEditorProps(ctx: CellEditorContext): Record<string, unknown> {
+  return {
+    value: ctx.value,
+    onChange: ctx.onChange,
+    onCommit: ctx.onCommit,
+    onCancel: ctx.onCancel,
+  }
+}
+
+/** Resolve the props to spread onto a registered editor for a given context. */
+export function resolveEditorProps(
+  registration: CellEditorRegistration,
+  ctx: CellEditorContext,
+): Record<string, unknown> {
+  return registration.props ? registration.props(ctx) : defaultEditorProps(ctx)
+}

package/src/editors/cell-editors.ts

@@ -1,4 +1,6 @@
-export type CellEditorType =
+import { hasCellEditor } from '../editor-registry'
+
+export type CellEditorType =
   | 'text'
   | 'number'
   | 'date'
@@ -18,6 +20,10 @@
   | 'textarea'
   | 'color'
   | 'rating'
+  // Any other string names a CUSTOM editor registered via `registerCellEditor`.
+  // `(string & {})` keeps the literals above autocompleting while allowing
+  // arbitrary custom type names.
+  | (string & {})
 
 /** Normalized option used by list/chips editors. The optional `color`
  *  paints the chip - both in the in-cell readonly chips render and in
@@ -118,6 +124,9 @@ export function parseEditorValue(
   if (type === 'textarea') {
     return String(value ?? '')
   }
+  // Custom registered editors own their value shape (like list/chips), so pass
+  // whatever the editor committed through unchanged instead of stringifying it.
+  if (hasCellEditor(type)) return value
   if (type === 'list' || type === 'chips') {
     // The editor manages the value shape: a scalar for single-select, an
     // array for multi-select. Trust what the editor handed us, just coerce

package/src/fuzzy.test.ts

@@ -0,0 +1,40 @@
+import { describe, expect, it } from 'vitest'
+import { fuzzyScore, fuzzyMatch } from './fuzzy'
+
+describe('fuzzyScore', () => {
+  it('matches a subsequence, rejects a non-subsequence', () => {
+    expect(fuzzyScore('New invoice', 'ni')).not.toBeNull()
+    expect(fuzzyScore('New invoice', 'niv')).not.toBeNull()
+    expect(fuzzyScore('New invoice', 'xyz')).toBeNull()
+    expect(fuzzyScore('New invoice', 'ivn')).toBeNull() // out of order
+  })
+
+  it('is case-insensitive and returns 0 for an empty query', () => {
+    expect(fuzzyMatch('Export CSV', 'EXPORT')).toBe(true)
+    expect(fuzzyScore('anything', '')).toBe(0)
+  })
+
+  it('scores a contiguous / prefix match higher than a scattered one', () => {
+    const prefix = fuzzyScore('Settings', 'set')!
+    const scattered = fuzzyScore('Silent tester', 'set')!
+    expect(prefix).toBeGreaterThan(scattered)
+  })
+
+  it('rewards word-boundary starts', () => {
+    const boundary = fuzzyScore('Open file', 'of')! // O..f (word starts)
+    const inner = fuzzyScore('Profile', 'of')! // ...of.. inside a word
+    expect(boundary).toBeGreaterThan(inner)
+  })
+
+  it('filters a list to matches only', () => {
+    const cmds = ['New invoice', 'New order', 'Export invoices', 'Delete invoice']
+    const ranked = cmds
+      .map((c) => ({ c, s: fuzzyScore(c, 'inv') }))
+      .filter((x) => x.s !== null)
+      .sort((a, b) => b.s! - a.s!)
+      .map((x) => x.c)
+    expect(ranked).toHaveLength(3) // "New order" has no 'inv' subsequence
+    expect(ranked).not.toContain('New order')
+    expect(ranked).toContain('New invoice')
+  })
+})

package/src/fuzzy.ts

@@ -0,0 +1,39 @@
+/**
+ * fuzzy - a tiny subsequence fuzzy matcher for command palettes / quick filters.
+ * `fuzzyScore(text, query)` returns a score (higher = better) when every query
+ * character appears in order in `text`, or `null` when it doesn't. Contiguous
+ * runs, word-boundary starts and early matches score higher. Case-insensitive,
+ * pure, dependency-free.
+ */
+const BOUNDARY = /[\s\-_/.]/
+
+export function fuzzyScore(text: string, query: string): number | null {
+  const q = query.trim().toLowerCase()
+  if (!q) return 0
+  const t = text.toLowerCase()
+  let from = 0
+  let score = 0
+  let run = 0
+  let prev = -2
+  for (const ch of q) {
+    const idx = t.indexOf(ch, from)
+    if (idx < 0) return null
+    if (idx === prev + 1) {
+      run += 1
+      score += 5 + run * 2 // contiguous run
+    } else {
+      run = 0
+      score += 1
+    }
+    if (idx === 0 || BOUNDARY.test(t[idx - 1] ?? '')) score += 8 // word start
+    score += Math.max(0, 3 - Math.floor(idx / 4)) // earliness
+    prev = idx
+    from = idx + 1
+  }
+  return score
+}
+
+/** Whether `query` fuzzy-matches `text`. */
+export function fuzzyMatch(text: string, query: string): boolean {
+  return fuzzyScore(text, query) !== null
+}

package/src/grid-select.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, it } from 'vitest'
+import { filterGridRows } from './grid-select'
+
+const rows = [
+  { id: 1, name: 'Ada Lovelace', email: 'ada@x.io' },
+  { id: 2, name: 'Alan Turing', email: 'alan@x.io' },
+  { id: 3, name: 'Grace Hopper', email: 'grace@x.io' },
+]
+
+describe('filterGridRows', () => {
+  it('returns every row for a blank query', () => {
+    expect(filterGridRows(rows, ['name', 'email'], '')).toHaveLength(3)
+    expect(filterGridRows(rows, ['name'], '   ')).toHaveLength(3)
+  })
+
+  it('matches a substring in any of the given fields (case-insensitive)', () => {
+    expect(filterGridRows(rows, ['name', 'email'], 'grace').map((r) => r.id)).toEqual([3])
+    expect(filterGridRows(rows, ['name', 'email'], 'ALAN').map((r) => r.id)).toEqual([2])
+    // "a" appears in every name -> all 3
+    expect(filterGridRows(rows, ['name'], 'a')).toHaveLength(3)
+  })
+
+  it('only searches the fields it is given', () => {
+    // 'x.io' is in email but we only search name -> no matches
+    expect(filterGridRows(rows, ['name'], 'x.io')).toHaveLength(0)
+    expect(filterGridRows(rows, ['email'], 'x.io')).toHaveLength(3)
+  })
+})

package/src/grid-select.ts

@@ -0,0 +1,20 @@
+/**
+ * grid-select - pure helper behind <SvGridSelect>: filter option rows by a
+ * free-text query across a set of fields (case-insensitive substring match).
+ * Framework-free + pure so it is unit-tested directly.
+ */
+export type Row = Record<string, unknown>
+
+/** Rows where ANY of `fields` contains `query` (case-insensitive). Blank query
+ *  returns every row. */
+export function filterGridRows<T extends Row>(
+  rows: ReadonlyArray<T>,
+  fields: ReadonlyArray<string>,
+  query: string,
+): T[] {
+  const q = query.trim().toLowerCase()
+  if (!q) return [...rows]
+  return rows.filter((row) =>
+    fields.some((f) => String(row[f] ?? '').toLowerCase().includes(q)),
+  )
+}