@svgrid/grid 2.2.27 → 2.2.28

package/src/editor-contract.ts

@@ -1,157 +1,157 @@
-/**
- * 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, 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'
-
-/**
- * A small action button rendered inside a framed field (via `SvField`'s
- * `actions`) - the generalized form of the clear / reveal buttons, for a lookup,
- * a generate, a copy, etc. `icon` is a Svelte snippet; when absent the `label`
- * text is shown. (Type-only Svelte import, so this module stays runtime-free.)
- */
-export type EditorAction = {
-  /** Accessible name + tooltip for the button. */
-  label: string
-  /** Invoked when the button is pressed. */
-  onClick: () => void
-  /** Optional icon snippet; falls back to the `label` text. */
-  icon?: import('svelte').Snippet
-  disabled?: boolean
-}
-
-/** 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. */
-  disabled?: boolean
-  /** Read-only: the value is shown but not editable. */
-  readonly?: boolean
-  /** Required for validation (adds `aria-required` + participates in validity). */
-  required?: boolean
-  /** Marks the control invalid (`aria-invalid` + error styling). */
-  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 label/hint/error ids derive from it). */
-  id?: string
-  /** Accessible name when there is no visible `label`. */
-  ariaLabel?: string
-  /** Busy state - shows a spinner (e.g. while an async value/validation resolves). */
-  loading?: boolean
-}
-
-/**
- * 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' | '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, 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): {
-  'aria-invalid': 'true' | undefined
-  'aria-required': 'true' | undefined
-  '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': 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
-}
+/**
+ * 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, 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'
+
+/**
+ * A small action button rendered inside a framed field (via `SvField`'s
+ * `actions`) - the generalized form of the clear / reveal buttons, for a lookup,
+ * a generate, a copy, etc. `icon` is a Svelte snippet; when absent the `label`
+ * text is shown. (Type-only Svelte import, so this module stays runtime-free.)
+ */
+export type EditorAction = {
+  /** Accessible name + tooltip for the button. */
+  label: string
+  /** Invoked when the button is pressed. */
+  onClick: () => void
+  /** Optional icon snippet; falls back to the `label` text. */
+  icon?: import('svelte').Snippet
+  disabled?: boolean
+}
+
+/** 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. */
+  disabled?: boolean
+  /** Read-only: the value is shown but not editable. */
+  readonly?: boolean
+  /** Required for validation (adds `aria-required` + participates in validity). */
+  required?: boolean
+  /** Marks the control invalid (`aria-invalid` + error styling). */
+  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 label/hint/error ids derive from it). */
+  id?: string
+  /** Accessible name when there is no visible `label`. */
+  ariaLabel?: string
+  /** Busy state - shows a spinner (e.g. while an async value/validation resolves). */
+  loading?: boolean
+}
+
+/**
+ * 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' | '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, 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): {
+  'aria-invalid': 'true' | undefined
+  'aria-required': 'true' | undefined
+  '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': 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/export-data-api.test.ts

@@ -1,126 +1,126 @@
-/**
- * The free CSV / TSV / JSON export + copy-to-clipboard now on the grid API.
- * Mounts a real <SvGrid /> and drives api.exportCsv/exportTsv/exportJson/
- * copyToClipboard with download:false so nothing hits the DOM download path.
- */
-import { afterEach, describe, expect, it, vi } from 'vitest'
-import { mount, unmount } from 'svelte'
-import SvGrid from './SvGrid.svelte'
-import {
-  columnFilteringFeature,
-  rowSelectionFeature,
-  rowSortingFeature,
-  tableFeatures,
-} from './index'
-import type { ColumnDef, SvGridApi } from './index'
-
-type Row = { id: number; name: string; price: number; when: string }
-const rows: Row[] = [
-  { id: 1, name: 'ACME, Inc', price: 1234.5, when: '2026-03-04' },
-  { id: 2, name: 'Globex', price: 20, when: '2026-06-01' },
-]
-const columns: ColumnDef<any, Row>[] = [
-  { field: 'name', header: 'Company', width: 180 },
-  { field: 'price', header: 'Price', width: 120, align: 'right', format: { type: 'currency', currency: 'USD' } },
-  { field: 'when', header: 'Date', width: 120 }, // plain string, no format (deterministic)
-]
-
-const features = tableFeatures({ columnFilteringFeature, rowSortingFeature, rowSelectionFeature })
-
-function mountGrid(): Promise<{ api: SvGridApi<any, Row>; destroy: () => void }> {
-  return new Promise((resolve, reject) => {
-    const target = document.createElement('div')
-    document.body.appendChild(target)
-    let done = false
-    const app = mount(SvGrid, {
-      target,
-      props: {
-        data: rows.map((r) => ({ ...r })),
-        columns: columns.map((c) => ({ ...c })),
-        features,
-        getRowId: (r: Row) => String(r.id),
-        rowHeight: 34,
-        containerHeight: 400,
-        virtualization: false,
-        onApiReady(api: SvGridApi<any, Row>) {
-          done = true
-          resolve({ api, destroy: () => { unmount(app); target.remove() } })
-        },
-      } as any,
-    })
-    queueMicrotask(() => { if (!done) reject(new Error('onApiReady never fired')) })
-  })
-}
-
-let cleanup: (() => void) | null = null
-afterEach(() => { cleanup?.(); cleanup = null; vi.restoreAllMocks() })
-
-describe('free grid export: exportCsv', () => {
-  it('serializes visible rows with faithful formatted values + a BOM header', async () => {
-    const { api, destroy } = await mountGrid()
-    cleanup = destroy
-    const csv = await api.exportCsv({ download: false })
-    const lines = csv.replace(/^/, '').split('\r\n')
-    expect(lines[0]).toBe('Company,Price,Date')
-    // Formatted as on screen; the comma in "ACME, Inc" AND in "$1,234.50" both
-    // force RFC-4180 quoting.
-    expect(lines[1]).toBe('"ACME, Inc","$1,234.50",2026-03-04')
-    expect(csv.startsWith('')).toBe(true)
-  })
-
-  it('rawValues:true writes the underlying numbers/strings', async () => {
-    const { api, destroy } = await mountGrid()
-    cleanup = destroy
-    const csv = await api.exportCsv({ download: false, rawValues: true, bom: false })
-    const lines = csv.split('\r\n')
-    expect(lines[1]).toBe('"ACME, Inc",1234.5,2026-03-04')
-  })
-
-  it('honors a column subset in the given order', async () => {
-    const { api, destroy } = await mountGrid()
-    cleanup = destroy
-    const csv = await api.exportCsv({ download: false, bom: false, columns: ['when', 'name'] })
-    expect(csv.split('\r\n')[0]).toBe('Date,Company')
-  })
-})
-
-describe('free grid export: exportTsv / exportJson', () => {
-  it('exportTsv is tab-delimited', async () => {
-    const { api, destroy } = await mountGrid()
-    cleanup = destroy
-    const tsv = await api.exportTsv({ download: false, bom: false })
-    expect(tsv.split('\r\n')[0]).toBe('Company\tPrice\tDate')
-  })
-
-  it('exportJson emits an array of formatted records', async () => {
-    const { api, destroy } = await mountGrid()
-    cleanup = destroy
-    const json = JSON.parse(await api.exportJson({ download: false }))
-    expect(json).toHaveLength(2)
-    expect(json[0]).toEqual({ name: 'ACME, Inc', price: '$1,234.50', when: '2026-03-04' })
-  })
-})
-
-describe('free grid export: copyToClipboard', () => {
-  it('writes TSV to the clipboard by default', async () => {
-    const writeText = vi.fn().mockResolvedValue(undefined)
-    vi.stubGlobal('navigator', { clipboard: { writeText } })
-    const { api, destroy } = await mountGrid()
-    cleanup = destroy
-    const text = await api.copyToClipboard()
-    expect(writeText).toHaveBeenCalledOnce()
-    expect(text.split('\r\n')[0]).toBe('Company\tPrice\tDate')
-    expect(text.startsWith('')).toBe(false) // no BOM on clipboard
-  })
-
-  it('can copy a Markdown table', async () => {
-    const writeText = vi.fn().mockResolvedValue(undefined)
-    vi.stubGlobal('navigator', { clipboard: { writeText } })
-    const { api, destroy } = await mountGrid()
-    cleanup = destroy
-    const md = await api.copyToClipboard({ format: 'markdown' })
-    const lines = md.split('\n')
-    expect(lines[0]).toBe('| Company | Price | Date |')
-    expect(lines[1]).toBe('| --- | ---: | --- |') // Price is right-aligned
-  })
-})
+/**
+ * The free CSV / TSV / JSON export + copy-to-clipboard now on the grid API.
+ * Mounts a real <SvGrid /> and drives api.exportCsv/exportTsv/exportJson/
+ * copyToClipboard with download:false so nothing hits the DOM download path.
+ */
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { mount, unmount } from 'svelte'
+import SvGrid from './SvGrid.svelte'
+import {
+  columnFilteringFeature,
+  rowSelectionFeature,
+  rowSortingFeature,
+  tableFeatures,
+} from './index'
+import type { ColumnDef, SvGridApi } from './index'
+
+type Row = { id: number; name: string; price: number; when: string }
+const rows: Row[] = [
+  { id: 1, name: 'ACME, Inc', price: 1234.5, when: '2026-03-04' },
+  { id: 2, name: 'Globex', price: 20, when: '2026-06-01' },
+]
+const columns: ColumnDef<any, Row>[] = [
+  { field: 'name', header: 'Company', width: 180 },
+  { field: 'price', header: 'Price', width: 120, align: 'right', format: { type: 'currency', currency: 'USD' } },
+  { field: 'when', header: 'Date', width: 120 }, // plain string, no format (deterministic)
+]
+
+const features = tableFeatures({ columnFilteringFeature, rowSortingFeature, rowSelectionFeature })
+
+function mountGrid(): Promise<{ api: SvGridApi<any, Row>; destroy: () => void }> {
+  return new Promise((resolve, reject) => {
+    const target = document.createElement('div')
+    document.body.appendChild(target)
+    let done = false
+    const app = mount(SvGrid, {
+      target,
+      props: {
+        data: rows.map((r) => ({ ...r })),
+        columns: columns.map((c) => ({ ...c })),
+        features,
+        getRowId: (r: Row) => String(r.id),
+        rowHeight: 34,
+        containerHeight: 400,
+        virtualization: false,
+        onApiReady(api: SvGridApi<any, Row>) {
+          done = true
+          resolve({ api, destroy: () => { unmount(app); target.remove() } })
+        },
+      } as any,
+    })
+    queueMicrotask(() => { if (!done) reject(new Error('onApiReady never fired')) })
+  })
+}
+
+let cleanup: (() => void) | null = null
+afterEach(() => { cleanup?.(); cleanup = null; vi.restoreAllMocks() })
+
+describe('free grid export: exportCsv', () => {
+  it('serializes visible rows with faithful formatted values + a BOM header', async () => {
+    const { api, destroy } = await mountGrid()
+    cleanup = destroy
+    const csv = await api.exportCsv({ download: false })
+    const lines = csv.replace(/^/, '').split('\r\n')
+    expect(lines[0]).toBe('Company,Price,Date')
+    // Formatted as on screen; the comma in "ACME, Inc" AND in "$1,234.50" both
+    // force RFC-4180 quoting.
+    expect(lines[1]).toBe('"ACME, Inc","$1,234.50",2026-03-04')
+    expect(csv.startsWith('')).toBe(true)
+  })
+
+  it('rawValues:true writes the underlying numbers/strings', async () => {
+    const { api, destroy } = await mountGrid()
+    cleanup = destroy
+    const csv = await api.exportCsv({ download: false, rawValues: true, bom: false })
+    const lines = csv.split('\r\n')
+    expect(lines[1]).toBe('"ACME, Inc",1234.5,2026-03-04')
+  })
+
+  it('honors a column subset in the given order', async () => {
+    const { api, destroy } = await mountGrid()
+    cleanup = destroy
+    const csv = await api.exportCsv({ download: false, bom: false, columns: ['when', 'name'] })
+    expect(csv.split('\r\n')[0]).toBe('Date,Company')
+  })
+})
+
+describe('free grid export: exportTsv / exportJson', () => {
+  it('exportTsv is tab-delimited', async () => {
+    const { api, destroy } = await mountGrid()
+    cleanup = destroy
+    const tsv = await api.exportTsv({ download: false, bom: false })
+    expect(tsv.split('\r\n')[0]).toBe('Company\tPrice\tDate')
+  })
+
+  it('exportJson emits an array of formatted records', async () => {
+    const { api, destroy } = await mountGrid()
+    cleanup = destroy
+    const json = JSON.parse(await api.exportJson({ download: false }))
+    expect(json).toHaveLength(2)
+    expect(json[0]).toEqual({ name: 'ACME, Inc', price: '$1,234.50', when: '2026-03-04' })
+  })
+})
+
+describe('free grid export: copyToClipboard', () => {
+  it('writes TSV to the clipboard by default', async () => {
+    const writeText = vi.fn().mockResolvedValue(undefined)
+    vi.stubGlobal('navigator', { clipboard: { writeText } })
+    const { api, destroy } = await mountGrid()
+    cleanup = destroy
+    const text = await api.copyToClipboard()
+    expect(writeText).toHaveBeenCalledOnce()
+    expect(text.split('\r\n')[0]).toBe('Company\tPrice\tDate')
+    expect(text.startsWith('')).toBe(false) // no BOM on clipboard
+  })
+
+  it('can copy a Markdown table', async () => {
+    const writeText = vi.fn().mockResolvedValue(undefined)
+    vi.stubGlobal('navigator', { clipboard: { writeText } })
+    const { api, destroy } = await mountGrid()
+    cleanup = destroy
+    const md = await api.copyToClipboard({ format: 'markdown' })
+    const lines = md.split('\n')
+    expect(lines[0]).toBe('| Company | Price | Date |')
+    expect(lines[1]).toBe('| --- | ---: | --- |') // Price is right-aligned
+  })
+})