@svgrid/grid 3.0.0 → 3.0.2

package/src/form-field.ts

@@ -1,127 +1,127 @@
-import type { Validator } from './validators'
-
-/**
- * Field descriptor for <SvForm> and the headless `createForm` core. Kept in a
- * plain `.ts` module so the core can import the type without pulling in the
- * `.svelte` component (which would create a `.svelte.ts` -> `.svelte` import
- * cycle Vite's dev import-analysis fails to resolve).
- */
-export type FormFieldType =
-  | 'text' | 'email' | 'tel' | 'textarea' | 'number' | 'password'
-  | 'select' | 'multiselect' | 'checkbox' | 'switch' | 'date' | 'color' | 'rating'
-  | 'radio' | 'slider' | 'tags' | 'phone' | 'country' | 'mask'
-  | 'datetime' | 'time' | 'daterange' | 'combobox' | 'file'
-  | 'array'
-
-export type FormField = {
-  name: string
-  label: string
-  type?: FormFieldType
-  required?: boolean
-  /** Show the field but block edits (still submitted, unlike hidden fields). */
-  readonly?: boolean
-  /** Helper text shown under the control (distinct from a validation error). */
-  help?: string
-  placeholder?: string
-  /**
-   * Options for select/combobox/radio/multiselect. A function makes them CASCADE:
-   * the list is derived from the current form values (e.g. cities for the picked
-   * country). Pair with `dependsOn` so the child clears when the parent changes.
-   */
-  options?:
-    | Array<{ value: string | number; label: string; color?: string }>
-    | ((values: Record<string, any>) => Array<{ value: string | number; label: string; color?: string }>)
-  /** Field name(s) this one depends on; when a parent changes, this field's value
-   *  is cleared (cascading selects). */
-  dependsOn?: string | string[]
-  /** Mask pattern for `type: 'mask'` (`#`=digit, `A`=letter, `*`=alnum). */
-  mask?: string
-  /** Numeric bounds for `type: 'number'` / `'slider'`. */
-  min?: number
-  max?: number
-  step?: number
-  precision?: number
-  /** Text affixes for `type: 'number'` (e.g. `$` / `%`). */
-  prefix?: string
-  suffix?: string
-  /** Remote option loader for `type: 'combobox'` (debounced typeahead). The
-   *  current form `values` are passed so it can depend on other fields. */
-  loadOptions?: (query: string, values: Record<string, any>) => Promise<Array<{ value: string | number; label: string }>>
-  /** File input hints for `type: 'file'`. */
-  accept?: string
-  multiple?: boolean
-  /**
-   * Derive this field's value from the other form values (e.g. a total). A
-   * computed field is read-only, recomputes reactively, is not user-validated,
-   * and its derived value is included in the submitted payload.
-   */
-  computed?: (values: Record<string, any>) => any
-  /** Declarative validation rules (see `rules` - email/pattern/min/compare...). */
-  rules?: ReadonlyArray<Validator>
-  /** Return an error message, or null/undefined when valid. */
-  validate?: (value: any, values: Record<string, any>) => string | null | undefined
-  /**
-   * Async validator (e.g. "is this username taken?"). Runs after the sync checks
-   * pass, debounced (`asyncDebounce`, default 300ms) and stale-guarded so only the
-   * latest result wins. While it runs, `form.isValidating(name)` is true and the
-   * field shows a checking indicator. Submit waits for all async validators.
-   */
-  asyncValidate?: (value: any, values: Record<string, any>) => Promise<string | null | undefined>
-  /** Debounce (ms) before `asyncValidate` runs on edit. Default 300. */
-  asyncDebounce?: number
-  /** Span full width in the grid. */
-  full?: boolean
-  /** Columns to span (generalizes `full`); `2`+ widens the field in a grid. */
-  span?: number
-  /**
-   * Show the field only when this is `true` / returns `true` (default: always).
-   * A field derived from other values, e.g. `visible: (v) => v.hasAddress`.
-   * Hidden fields are skipped in validation and excluded from the submitted values.
-   */
-  visible?: boolean | ((values: Record<string, any>) => boolean)
-  /** Disable the field, statically or derived from other values. */
-  disabled?: boolean | ((values: Record<string, any>) => boolean)
-  /**
-   * For `type: 'array'` - the fields of each repeatable item. The value is an
-   * array of item objects; each item's fields validate against that item (so
-   * cross-field rules within a row work). `required`/`minItems`/`maxItems` gate
-   * the array length.
-   */
-  itemFields?: ReadonlyArray<FormField>
-  /** Label for the "add item" button of an array field. Default "+ Add". */
-  addLabel?: string
-  /** Min / max item count for an array field. */
-  minItems?: number
-  maxItems?: number
-}
-
-/**
- * A group of fields rendered as a titled fieldset - and, when `<SvForm stepper>`
- * is set, as one step of a wizard. Use in place of a plain `FormField` inside the
- * `fields` array; the schema may freely mix flat fields and sections.
- */
-export type FormSection = {
-  section: string
-  description?: string
-  fields: ReadonlyArray<FormField>
-  /** Column count for this section's grid (defaults to the form's `columns`). */
-  columns?: number
-}
-
-/** An entry in a form schema: either a single field or a titled section/step. */
-export type FormEntry = FormField | FormSection
-
-/** Narrow a schema entry to a section (has a `fields` array). */
-export function isFormSection(e: FormEntry): e is FormSection {
-  return Array.isArray((e as FormSection).fields)
-}
-
-/** Flatten a mixed schema (fields + sections) to the flat list of fields. */
-export function flattenFields(entries: ReadonlyArray<FormEntry>): FormField[] {
-  const out: FormField[] = []
-  for (const e of entries) {
-    if (isFormSection(e)) out.push(...e.fields)
-    else out.push(e)
-  }
-  return out
-}
+import type { Validator } from './validators'
+
+/**
+ * Field descriptor for <SvForm> and the headless `createForm` core. Kept in a
+ * plain `.ts` module so the core can import the type without pulling in the
+ * `.svelte` component (which would create a `.svelte.ts` -> `.svelte` import
+ * cycle Vite's dev import-analysis fails to resolve).
+ */
+export type FormFieldType =
+  | 'text' | 'email' | 'tel' | 'textarea' | 'number' | 'password'
+  | 'select' | 'multiselect' | 'checkbox' | 'switch' | 'date' | 'color' | 'rating'
+  | 'radio' | 'slider' | 'tags' | 'phone' | 'country' | 'mask'
+  | 'datetime' | 'time' | 'daterange' | 'combobox' | 'file'
+  | 'array'
+
+export type FormField = {
+  name: string
+  label: string
+  type?: FormFieldType
+  required?: boolean
+  /** Show the field but block edits (still submitted, unlike hidden fields). */
+  readonly?: boolean
+  /** Helper text shown under the control (distinct from a validation error). */
+  help?: string
+  placeholder?: string
+  /**
+   * Options for select/combobox/radio/multiselect. A function makes them CASCADE:
+   * the list is derived from the current form values (e.g. cities for the picked
+   * country). Pair with `dependsOn` so the child clears when the parent changes.
+   */
+  options?:
+    | Array<{ value: string | number; label: string; color?: string }>
+    | ((values: Record<string, any>) => Array<{ value: string | number; label: string; color?: string }>)
+  /** Field name(s) this one depends on; when a parent changes, this field's value
+   *  is cleared (cascading selects). */
+  dependsOn?: string | string[]
+  /** Mask pattern for `type: 'mask'` (`#`=digit, `A`=letter, `*`=alnum). */
+  mask?: string
+  /** Numeric bounds for `type: 'number'` / `'slider'`. */
+  min?: number
+  max?: number
+  step?: number
+  precision?: number
+  /** Text affixes for `type: 'number'` (e.g. `$` / `%`). */
+  prefix?: string
+  suffix?: string
+  /** Remote option loader for `type: 'combobox'` (debounced typeahead). The
+   *  current form `values` are passed so it can depend on other fields. */
+  loadOptions?: (query: string, values: Record<string, any>) => Promise<Array<{ value: string | number; label: string }>>
+  /** File input hints for `type: 'file'`. */
+  accept?: string
+  multiple?: boolean
+  /**
+   * Derive this field's value from the other form values (e.g. a total). A
+   * computed field is read-only, recomputes reactively, is not user-validated,
+   * and its derived value is included in the submitted payload.
+   */
+  computed?: (values: Record<string, any>) => any
+  /** Declarative validation rules (see `rules` - email/pattern/min/compare...). */
+  rules?: ReadonlyArray<Validator>
+  /** Return an error message, or null/undefined when valid. */
+  validate?: (value: any, values: Record<string, any>) => string | null | undefined
+  /**
+   * Async validator (e.g. "is this username taken?"). Runs after the sync checks
+   * pass, debounced (`asyncDebounce`, default 300ms) and stale-guarded so only the
+   * latest result wins. While it runs, `form.isValidating(name)` is true and the
+   * field shows a checking indicator. Submit waits for all async validators.
+   */
+  asyncValidate?: (value: any, values: Record<string, any>) => Promise<string | null | undefined>
+  /** Debounce (ms) before `asyncValidate` runs on edit. Default 300. */
+  asyncDebounce?: number
+  /** Span full width in the grid. */
+  full?: boolean
+  /** Columns to span (generalizes `full`); `2`+ widens the field in a grid. */
+  span?: number
+  /**
+   * Show the field only when this is `true` / returns `true` (default: always).
+   * A field derived from other values, e.g. `visible: (v) => v.hasAddress`.
+   * Hidden fields are skipped in validation and excluded from the submitted values.
+   */
+  visible?: boolean | ((values: Record<string, any>) => boolean)
+  /** Disable the field, statically or derived from other values. */
+  disabled?: boolean | ((values: Record<string, any>) => boolean)
+  /**
+   * For `type: 'array'` - the fields of each repeatable item. The value is an
+   * array of item objects; each item's fields validate against that item (so
+   * cross-field rules within a row work). `required`/`minItems`/`maxItems` gate
+   * the array length.
+   */
+  itemFields?: ReadonlyArray<FormField>
+  /** Label for the "add item" button of an array field. Default "+ Add". */
+  addLabel?: string
+  /** Min / max item count for an array field. */
+  minItems?: number
+  maxItems?: number
+}
+
+/**
+ * A group of fields rendered as a titled fieldset - and, when `<SvForm stepper>`
+ * is set, as one step of a wizard. Use in place of a plain `FormField` inside the
+ * `fields` array; the schema may freely mix flat fields and sections.
+ */
+export type FormSection = {
+  section: string
+  description?: string
+  fields: ReadonlyArray<FormField>
+  /** Column count for this section's grid (defaults to the form's `columns`). */
+  columns?: number
+}
+
+/** An entry in a form schema: either a single field or a titled section/step. */
+export type FormEntry = FormField | FormSection
+
+/** Narrow a schema entry to a section (has a `fields` array). */
+export function isFormSection(e: FormEntry): e is FormSection {
+  return Array.isArray((e as FormSection).fields)
+}
+
+/** Flatten a mixed schema (fields + sections) to the flat list of fields. */
+export function flattenFields(entries: ReadonlyArray<FormEntry>): FormField[] {
+  const out: FormField[] = []
+  for (const e of entries) {
+    if (isFormSection(e)) out.push(...e.fields)
+    else out.push(e)
+  }
+  return out
+}

package/src/grid-icons.test.ts

@@ -0,0 +1,46 @@
+/**
+ * The icon catalogue as data: the name list and the glyph table have to agree
+ * with each other and with the filter-operator catalogue.
+ *
+ * The third test here is the one that earns its keep. Operator icons are
+ * data-driven (`filterOperatorOptions[].iconName`), and an operator naming an
+ * icon the grid has no case for renders an empty box rather than failing -
+ * which is exactly how `op-between` shipped blank. `GridIconName` makes that a
+ * compile error now, and this makes it a test failure too, so it also catches
+ * an operator added through a path that skips type-checking.
+ */
+import { describe, expect, it } from 'vitest'
+import { GRID_ICON_GLYPHS, GRID_ICON_NAMES, type GridIconName } from './grid-icons'
+import { filterOperatorOptions } from './filter-operators'
+
+describe('grid icon catalogue', () => {
+  it('lists every name exactly once', () => {
+    const dupes = GRID_ICON_NAMES.filter((n, i) => GRID_ICON_NAMES.indexOf(n) !== i)
+    expect(dupes, `duplicated icon names: ${dupes.join(', ')}`).toEqual([])
+  })
+
+  it('only maps glyphs for names in the catalogue', () => {
+    const orphans = Object.keys(GRID_ICON_GLYPHS).filter(
+      (k) => !GRID_ICON_NAMES.includes(k as GridIconName),
+    )
+    expect(orphans, `glyphs for unknown icons: ${orphans.join(', ')}`).toEqual([])
+  })
+
+  it('has a name for every filter operator icon', () => {
+    const missing = filterOperatorOptions
+      .map((o) => o.iconName)
+      .filter((n) => !GRID_ICON_NAMES.includes(n))
+    expect(missing, `operators naming an icon the grid cannot draw: ${missing.join(', ')}`).toEqual(
+      [],
+    )
+  })
+
+  it('keeps the pin icons separate from the operator icons they look like', () => {
+    // Pin used to render `op-startsWith` / `op-greaterThan` / `x` directly, so
+    // overriding a filter operator silently repainted the pin menu. Same
+    // default glyphs, different names.
+    for (const name of ['pin-left', 'pin-right', 'unpin'] as const) {
+      expect(GRID_ICON_NAMES).toContain(name)
+    }
+  })
+})

package/src/grid-icons.ts

@@ -0,0 +1,184 @@
+/**
+ * Grid chrome icons. Every glyph `<SvGrid>` draws for its own UI - sort
+ * indicators, the filter funnel, expanders, the pager arrows, tool-panel
+ * buttons - has a name here, and the `icons` prop replaces any subset of them.
+ *
+ * This mirrors `grid-messages.ts`: a name-keyed map with built-in defaults,
+ * where an unset name keeps the default. A partial map is all a consumer ever
+ * needs, so `icons` is safe to pass without knowing the full catalogue. That
+ * matters more than it looks - a single catch-all snippet would make the
+ * consumer responsible for every name the grid can ask for, and missing one
+ * renders an empty box. The `op-between` comment in SvGrid.svelte records what
+ * that looks like when it ships.
+ *
+ * Deliberately NOT in here:
+ *   - the scrollbar stepper arrows. `sv-grid-scrollbar.ts` is a custom element
+ *     that builds its SVG with `createElementNS` inside a shadow root, on
+ *     purpose, so it stays compatible with strict CSP / Trusted Types. A Svelte
+ *     snippet cannot render there. Theme it with the `--sg-scrollbar-*` tokens.
+ *   - the checkbox tick and its indeterminate dash. Both are `::after`
+ *     pseudo-elements drawn from borders (SvGrid.css), a form-control
+ *     affordance rather than an icon, and they render once per visible row.
+ *   - conditional formatting's `iconSet`. Those are value-driven data glyphs a
+ *     consumer already chooses; a different concept that shares the word.
+ */
+import type { Snippet } from 'svelte'
+
+/**
+ * Every icon `<SvGrid>` draws for its own chrome. Pass any subset of these to
+ * the `icons` prop to swap the built-in glyph for your own markup.
+ */
+export type GridIconName =
+  // ---- Header + column menu ----
+  | 'sort'
+  | 'sort-asc'
+  | 'sort-desc'
+  | 'filter'
+  | 'menu'
+  | 'group'
+  | 'x'
+  | 'chevron-down'
+  | 'chevron-right'
+  | 'autosize'
+  | 'columns'
+  | 'reset'
+  // ---- Filter operators (mirror `iconName` in filter-operators.ts) ----
+  | 'op-contains'
+  | 'op-notContains'
+  | 'op-equals'
+  | 'op-notEquals'
+  | 'op-startsWith'
+  | 'op-endsWith'
+  | 'op-regex'
+  | 'op-in'
+  | 'op-notIn'
+  | 'op-greaterThan'
+  | 'op-lessThan'
+  | 'op-between'
+  | 'op-isBlank'
+  | 'op-isNotBlank'
+  // ---- Pinning. Their defaults borrow the operator glyphs above, but they get
+  // their own names so overriding a filter operator does not silently repaint
+  // the pin menu. ----
+  | 'pin-left'
+  | 'pin-right'
+  | 'unpin'
+  // ---- Toolbar + overlays ----
+  | 'search'
+  | 'tool-panel'
+  | 'chart'
+  | 'advanced-filter'
+  | 'column-group-caret'
+  // ---- Glyph icons: the built-in is a character, not a path ----
+  | 'close'
+  | 'clear'
+  | 'remove'
+  | 'row-number'
+  | 'pinned-row-top'
+  | 'pinned-row-bottom'
+  | 'find-prev'
+  | 'find-next'
+  | 'move-up'
+  | 'move-down'
+  | 'group-add'
+  | 'page-first'
+  | 'page-prev'
+  | 'page-next'
+  | 'page-last'
+  | 'page-size-caret'
+  | 'drag-handle'
+  | 'breadcrumb-separator'
+
+/**
+ * Consumer icon overrides, keyed by name. Any subset; names you leave out keep
+ * their built-in glyph, so `icons` never has to be exhaustive.
+ */
+export type GridIcons = Partial<Record<GridIconName, Snippet>>
+
+/**
+ * Icons whose built-in form is a character rather than an SVG path. Kept as
+ * data so `<SvGrid>`, its footer and the standalone `SvRowGroupPanel` render
+ * the same defaults instead of three copies drifting apart.
+ *
+ * Each is the exact character that shipped inline before, so a grid that sets
+ * no `icons` renders byte-for-byte what it always did.
+ */
+export const GRID_ICON_GLYPHS: Partial<Record<GridIconName, string>> = {
+  close: '✕', // multiplication X
+  clear: '✕',
+  remove: '×', // multiplication sign
+  'row-number': '#',
+  'pinned-row-top': '↑', // upwards arrow
+  'pinned-row-bottom': '↓', // downwards arrow
+  'find-prev': '↑',
+  'find-next': '↓',
+  'move-up': '↑',
+  'move-down': '↓',
+  'group-add': '⊞', // squared plus
+  'page-first': '⇤', // leftwards arrow to bar
+  'page-prev': '‹', // single left-pointing angle quote
+  'page-next': '›', // single right-pointing angle quote
+  'page-last': '⇥', // rightwards arrow to bar
+  'page-size-caret': '▾', // black down-pointing small triangle
+  'drag-handle': '⠿', // braille pattern dots-123456, the grip
+  'breadcrumb-separator': '›',
+}
+
+/**
+ * Every icon name, in catalogue order. Exported for tests and docs generation;
+ * the grid itself never reads it, so it costs a consumer's bundle nothing.
+ */
+export const GRID_ICON_NAMES: ReadonlyArray<GridIconName> = [
+  'sort',
+  'sort-asc',
+  'sort-desc',
+  'filter',
+  'menu',
+  'group',
+  'x',
+  'chevron-down',
+  'chevron-right',
+  'autosize',
+  'columns',
+  'reset',
+  'op-contains',
+  'op-notContains',
+  'op-equals',
+  'op-notEquals',
+  'op-startsWith',
+  'op-endsWith',
+  'op-regex',
+  'op-in',
+  'op-notIn',
+  'op-greaterThan',
+  'op-lessThan',
+  'op-between',
+  'op-isBlank',
+  'op-isNotBlank',
+  'pin-left',
+  'pin-right',
+  'unpin',
+  'search',
+  'tool-panel',
+  'chart',
+  'advanced-filter',
+  'column-group-caret',
+  'close',
+  'clear',
+  'remove',
+  'row-number',
+  'pinned-row-top',
+  'pinned-row-bottom',
+  'find-prev',
+  'find-next',
+  'move-up',
+  'move-down',
+  'group-add',
+  'page-first',
+  'page-prev',
+  'page-next',
+  'page-last',
+  'page-size-caret',
+  'drag-handle',
+  'breadcrumb-separator',
+]