@svgrid/grid 2.6.21 → 2.7.0

package/src/editor-block-prop.test.ts

@@ -0,0 +1,132 @@
+/**
+ * `block` is declared once, in `SvEditorProps`, and its doc comment states the
+ * contract: "in a form grid a row of inputs each stopping at a different width
+ * reads as broken."
+ *
+ * Nine editors accepted the prop by type and did nothing with it. `<SvForm>`
+ * mounts five of them, so the Edit-fields drawer came out with a full-width
+ * text box above a 200px select above a 240px date picker - the exact thing the
+ * doc comment warns about, shipped.
+ *
+ * A type that promises something no code honours is worse than no type: it
+ * reads as done. This walks the source instead of trusting the declaration, so
+ * the next editor added to the kit either honours `block` or is listed here as
+ * a deliberate exemption.
+ */
+import { describe, expect, it } from 'vitest'
+import { readFileSync, readdirSync } from 'node:fs'
+import { join } from 'node:path'
+
+const SRC = join(import.meta.dirname, '.')
+
+/**
+ * Controls whose width is their content, where stretching to 100% would be
+ * wrong rather than merely unusual: a checkbox is a 16px box with a label
+ * beside it, a rating is five stars, a switch is a switch. Widening them puts
+ * the control at one end of an empty row.
+ */
+const INTRINSIC = new Set([
+  'SvCheckBox',
+  'SvSwitchButton',
+  'SvToggleButton',
+  'SvButtonGroup',
+  'SvRadioGroup',
+  'SvRating',
+  'SvOtpInput',
+  'SvFileUpload',
+  'SvSlider',
+  'SvColorInput',
+])
+
+function editorsDeclaringBlock(): string[] {
+  return readdirSync(SRC)
+    .filter((f) => f.startsWith('Sv') && f.endsWith('.svelte'))
+    .filter((f) => {
+      const src = readFileSync(join(SRC, f), 'utf8')
+      if (!src.includes('SvEditorProps')) return false
+      // A `Pick<SvEditorProps, ...>` that leaves 'block' out has opted out at
+      // the type level, which is a legitimate (and checkable) choice.
+      const pick = /Pick<\s*SvEditorProps,\s*([^>]+)>/.exec(src)
+      if (pick) return (pick[1] ?? '').includes("'block'")
+      return true
+    })
+    .map((f) => f.replace('.svelte', ''))
+}
+
+describe('the block prop is honoured wherever it is declared', () => {
+  const declaring = editorsDeclaringBlock().filter((n) => !INTRINSIC.has(n))
+
+  it('finds the editor kit (guards against the walker silently matching nothing)', () => {
+    expect(declaring.length).toBeGreaterThan(10)
+    expect(declaring).toContain('SvDropDownList')
+    expect(declaring).toContain('SvDateTimePicker')
+  })
+
+  it.each(declaring)('%s reads the prop and applies it to a width', (name) => {
+    const src = readFileSync(join(SRC, `${name}.svelte`), 'utf8')
+
+    // Declared but never destructured is the failure mode that shipped: the
+    // component compiles, the consumer passes `block`, nothing happens.
+    expect(src, `${name} never destructures block`).toMatch(/\bblock = false\b|\bblock,/)
+
+    // And destructured but never used is the same bug one step later.
+    const applied =
+      /class:is-block=\{block\}/.test(src) ||
+      /class:sv-[a-z]+--block=\{block\}/.test(src) ||
+      /\{block\}/.test(src)
+    expect(applied, `${name} destructures block but never applies it`).toBe(true)
+  })
+})
+
+/**
+ * Every `<SvXxx ... />` in a Svelte source, with its props.
+ *
+ * Not a regex: props routinely contain `>`, in arrow functions like
+ * `onChange={(m) => o.onChange(m)}`. A `[^>]*?` walker stops at the first one
+ * and silently skips the tag - which here quietly excused SvComboBox,
+ * SvMaskedInput and SvPhoneInput from the check, three of the controls this
+ * test exists to cover. So brace depth is tracked instead.
+ */
+function selfClosingTags(src: string): Array<{ name: string; props: string }> {
+  const out: Array<{ name: string; props: string }> = []
+  const open = /<(Sv[A-Za-z]+)(?=[\s/>])/g
+  let m: RegExpExecArray | null
+  while ((m = open.exec(src))) {
+    let i = m.index + m[0].length
+    let depth = 0
+    for (; i < src.length; i++) {
+      const c = src[i]
+      if (c === '{') depth++
+      else if (c === '}') depth--
+      else if (depth === 0 && c === '/' && src[i + 1] === '>') {
+        out.push({ name: m[1]!, props: src.slice(m.index + m[0].length, i) })
+        break
+      } else if (depth === 0 && c === '>') break // an open tag, not self-closing
+    }
+  }
+  return out
+}
+
+describe('<SvForm> passes block to every control it mounts', () => {
+  // The components above can honour block perfectly and the form still look
+  // ragged, because the form is what decides to pass it. That is precisely how
+  // this bug survived: SvNumberInput, SvPasswordInput, SvMaskedInput and
+  // SvPhoneInput were passed `block` and the rest were not.
+  const form = readFileSync(join(SRC, 'SvForm.svelte'), 'utf8')
+  const honours = new Set(editorsDeclaringBlock())
+  const controls = selfClosingTags(form).filter(
+    (c) => honours.has(c.name) && !INTRINSIC.has(c.name),
+  )
+
+  it('finds the control snippet', () => {
+    // Every control that CAN fill its row must be seen by this walker. The
+    // three `=>`-carrying tags above are the reason this number is asserted.
+    expect(controls.length).toBeGreaterThanOrEqual(11)
+    for (const expected of ['SvDropDownList', 'SvComboBox', 'SvMaskedInput', 'SvPhoneInput'])
+      expect(controls.map((c) => c.name)).toContain(expected)
+  })
+
+  it.each(controls.map((c) => [c.name, c.props]))('%s is mounted block', (name, props) => {
+    expect(props, `<${name}> in SvForm is missing block`).toMatch(/(^|\s)block(\s|$|=)/)
+  })
+})

package/src/editor-contract.ts

@@ -1,171 +1,171 @@
-/**
- * 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.
- */
-
-/** How much room a cell editor asks for, so the grid can size its overlay. */
-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
-  /**
-   * Fill the container instead of the control's own default width. A default
-   * width is right for a control sitting on its own; in a form grid a row of
-   * inputs each stopping at a different width reads as broken.
-   */
-  block?: 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.
- *
- * `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 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 | 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.). */
-  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.
+ */
+
+/** How much room a cell editor asks for, so the grid can size its overlay. */
+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
+  /**
+   * Fill the container instead of the control's own default width. A default
+   * width is right for a control sitting on its own; in a form grid a row of
+   * inputs each stopping at a different width reads as broken.
+   */
+  block?: 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.
+ *
+ * `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 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 | 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.). */
+  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
+}