@svgrid/enterprise 1.2.0 → 2.0.0

package/src/edit-panel.test.ts

@@ -0,0 +1,213 @@
+import { describe, expect, it } from 'vitest'
+import type { EntitySchema, StandardSchemaV1 } from './schema'
+import {
+  buildInitialValues,
+  controlKind,
+  editMode,
+  rowId,
+  toSubmitValues,
+  validateAll,
+  toDateString,
+  toDateTimeString,
+  toNumberValue,
+  fromNumberValue,
+  toSliderValue,
+  toTags,
+} from './edit-panel'
+
+type Customer = {
+  id: string
+  name: string
+  age: number
+  active: boolean
+  tier: string
+  bio: string
+}
+
+const email: StandardSchemaV1<string, string> = {
+  '~standard': {
+    version: 1,
+    vendor: 'test',
+    validate: (v) =>
+      typeof v === 'string' && v.includes('@') ? { value: v } : { issues: [{ message: 'Invalid email' }] },
+  },
+}
+
+const schema: EntitySchema<Customer> = {
+  name: 'customers',
+  label: 'Customer',
+  fields: [
+    { field: 'id', type: 'text', primaryKey: true, readonly: true },
+    { field: 'name', type: 'text', required: true, validate: email },
+    { field: 'age', type: 'number', defaultValue: 18 },
+    { field: 'active', type: 'boolean' },
+    { field: 'tier', type: 'enum', options: [{ value: 'free', label: 'Free' }, { value: 'pro', label: 'Pro' }] },
+    { field: 'bio', type: 'json', input: { span: 2 } },
+  ],
+}
+
+describe('editMode', () => {
+  it('is create without a row, edit with one', () => {
+    expect(editMode(null)).toBe('create')
+    expect(editMode(undefined)).toBe('create')
+    expect(editMode({ id: '1' } as Customer)).toBe('edit')
+  })
+})
+
+describe('controlKind', () => {
+  it('maps editor types to controls', () => {
+    expect(controlKind({ editorType: 'checkbox' })).toBe('checkbox')
+    expect(controlKind({ editorType: 'number' })).toBe('number')
+    expect(controlKind({ editorType: 'date' })).toBe('date')
+    expect(controlKind({ editorType: 'datetime' })).toBe('datetime')
+    expect(controlKind({ editorType: 'select' })).toBe('select')
+    expect(controlKind({ editorType: 'list' })).toBe('select')
+    expect(controlKind({ editorType: 'textarea' })).toBe('textarea')
+    expect(controlKind({ editorType: 'text' })).toBe('text')
+    expect(controlKind({ editorType: 'autocomplete' })).toBe('text')
+  })
+})
+
+describe('buildInitialValues', () => {
+  it('seeds from defaults and type-appropriate empties in create mode', () => {
+    const v = buildInitialValues(schema, null)
+    expect(v).toEqual({ id: '', name: '', age: 18, active: false, tier: '', bio: '' })
+  })
+
+  it('seeds from the row in edit mode', () => {
+    const row: Customer = { id: '7', name: 'a@b.com', age: 40, active: true, tier: 'pro', bio: 'hi' }
+    expect(buildInitialValues(schema, row)).toEqual(row)
+  })
+})
+
+describe('validateAll', () => {
+  it('flags a required-but-empty field with a friendly message', async () => {
+    const errors = await validateAll(schema, buildInitialValues(schema, null))
+    expect(errors.name).toBe('Name is required')
+  })
+
+  it('runs the Standard Schema validator when a value is present', async () => {
+    const values = { ...buildInitialValues(schema, null), name: 'not-an-email' }
+    const errors = await validateAll(schema, values)
+    expect(errors.name).toBe('Invalid email')
+  })
+
+  it('passes a valid form (no readonly checks, no false positives)', async () => {
+    const values = { ...buildInitialValues(schema, null), name: 'a@b.com' }
+    expect(await validateAll(schema, values)).toEqual({})
+  })
+
+  it('never validates readonly fields', async () => {
+    // id is readonly + empty; must not produce an error even though it looks empty
+    const errors = await validateAll(schema, { ...buildInitialValues(schema, null), name: 'a@b.com' })
+    expect(errors.id).toBeUndefined()
+  })
+
+  it('merges schema-level cross-field errors', async () => {
+    const withCross: EntitySchema<Customer> = {
+      ...schema,
+      hooks: { validate: () => ({ name: 'blocked by rule', region: 'required together' }) },
+    }
+    // A per-field failure (missing name) is NOT overwritten by the cross-field rule,
+    // but a cross-field-only error (region) is surfaced.
+    const errors = await validateAll(withCross, buildInitialValues(withCross, null))
+    expect(errors.name).toBe('Name is required') // per-field wins
+    expect(errors.region).toBe('required together') // cross-field added
+  })
+})
+
+describe('built-in validation (no external lib)', () => {
+  type Row = { id: string; name: string; age: number; site: string; contact: string }
+  const s: EntitySchema<Row> = {
+    name: 'people',
+    idField: 'id',
+    fields: [
+      { field: 'id', type: 'text', primaryKey: true, readonly: true },
+      { field: 'name', type: 'text', minLength: 2, maxLength: 10 },
+      { field: 'age', type: 'number', min: 0, max: 120 },
+      { field: 'site', type: 'text', format: 'url' },
+      { field: 'contact', type: 'text', format: 'email' },
+    ],
+  }
+  const base = () => buildInitialValues(s, null)
+
+  it('rejects a non-numeric number and enforces min/max', async () => {
+    expect((await validateAll(s, { ...base(), age: 'abc' })).age).toMatch(/must be a number/)
+    expect((await validateAll(s, { ...base(), age: '-5' })).age).toMatch(/at least 0/)
+    expect((await validateAll(s, { ...base(), age: '200' })).age).toMatch(/at most 120/)
+    expect((await validateAll(s, { ...base(), age: '30' })).age).toBeUndefined()
+  })
+
+  it('enforces string length', async () => {
+    expect((await validateAll(s, { ...base(), name: 'x' })).name).toMatch(/at least 2/)
+    expect((await validateAll(s, { ...base(), name: 'x'.repeat(20) })).name).toMatch(/at most 10/)
+  })
+
+  it('validates email and url formats', async () => {
+    expect((await validateAll(s, { ...base(), contact: 'nope' })).contact).toMatch(/valid email/)
+    expect((await validateAll(s, { ...base(), contact: 'a@b.co' })).contact).toBeUndefined()
+    expect((await validateAll(s, { ...base(), site: 'ftp://x' })).site).toMatch(/valid URL/)
+    expect((await validateAll(s, { ...base(), site: 'https://x.io' })).site).toBeUndefined()
+  })
+
+  it('skips built-in checks when the value is empty (that is what required is for)', async () => {
+    expect((await validateAll(s, base())).age).toBeUndefined()
+    expect((await validateAll(s, base())).contact).toBeUndefined()
+  })
+})
+
+describe('toSubmitValues', () => {
+  it('omits readonly fields and coerces number + boolean', () => {
+    const values = { id: '7', name: 'a@b.com', age: '42', active: 'true', tier: 'pro', bio: 'x' }
+    const out = toSubmitValues(schema, values)
+    expect(out).toEqual({ name: 'a@b.com', age: 42, active: true, tier: 'pro', bio: 'x' })
+    expect('id' in out).toBe(false)
+  })
+
+  it('turns an empty number into null', () => {
+    const out = toSubmitValues(schema, { ...buildInitialValues(schema, null), age: '' })
+    expect(out.age).toBeNull()
+  })
+})
+
+describe('rowId', () => {
+  it('resolves the primary key as a string', () => {
+    expect(rowId(schema, { id: 99 } as unknown as Customer)).toBe('99')
+  })
+})
+
+describe('editor value coercion', () => {
+  it('formats a Date to a local yyyy-MM-dd (no UTC shift)', () => {
+    // Local midnight - toISOString would shift the day in negative-offset zones; local formatting must not.
+    const d = new Date(2024, 0, 2, 0, 0) // 2 Jan 2024, local
+    expect(toDateString(d)).toBe('2024-01-02')
+    expect(toDateString(null)).toBe('')
+  })
+
+  it('formats a Date to a local yyyy-MM-ddTHH:mm', () => {
+    expect(toDateTimeString(new Date(2024, 2, 4, 9, 5))).toBe('2024-03-04T09:05')
+    expect(toDateTimeString(null)).toBe('')
+  })
+
+  it('coerces numbers in/out with the empty-string convention', () => {
+    expect(toNumberValue(1200)).toBe(1200)
+    expect(toNumberValue('1200')).toBeNull() // strings are not numbers
+    expect(toNumberValue(NaN)).toBeNull()
+    expect(fromNumberValue(null)).toBe('')
+    expect(fromNumberValue(0)).toBe(0) // 0 is a real value, not empty
+  })
+
+  it('slider falls back to min when unset', () => {
+    expect(toSliderValue(42, 0)).toBe(42)
+    expect(toSliderValue('', 10)).toBe(10)
+    expect(toSliderValue(undefined, 5)).toBe(5)
+  })
+
+  it('coerces tags from arrays, comma strings, or empty', () => {
+    expect(toTags(['a', 'b'])).toEqual(['a', 'b'])
+    expect(toTags('a, b ,c')).toEqual(['a', 'b', 'c'])
+    expect(toTags('')).toEqual([])
+    expect(toTags(null)).toEqual([])
+    expect(toTags([1, 2])).toEqual(['1', '2'])
+  })
+})

package/src/edit-panel.ts

@@ -0,0 +1,228 @@
+/**
+ * Edit-panel logic. The testable core behind `SvGridEditPanel.svelte`: build a
+ * form's initial values from a schema + row, resolve which control renders each
+ * field, validate the whole form, and produce the payload to submit through a
+ * `ServerController`'s `createRow` / `updateRow`. Keeping this pure (no Svelte,
+ * no DOM) mirrors the pivot designer split and lets it be unit-tested.
+ */
+import type { RowData } from '@svgrid/grid'
+import {
+  resolveIdField,
+  schemaToFormFields,
+  validateEntity,
+  validateField,
+  type EntitySchema,
+  type FormFieldDescriptor,
+} from './schema'
+
+export type EditMode = 'create' | 'edit'
+
+/** The native control a field renders as. */
+export type ControlKind =
+  | 'text'
+  | 'number'
+  | 'date'
+  | 'datetime'
+  | 'time'
+  | 'checkbox'
+  | 'select'
+  | 'textarea'
+
+/** Create mode when there's no row to edit, edit mode otherwise. */
+export function editMode<TData extends RowData>(row: TData | null | undefined): EditMode {
+  return row == null ? 'create' : 'edit'
+}
+
+/** Map a field's editor type to the control the panel renders. */
+export function controlKind(field: Pick<FormFieldDescriptor, 'editorType'>): ControlKind {
+  switch (field.editorType) {
+    case 'checkbox':
+      return 'checkbox'
+    case 'number':
+      return 'number'
+    case 'date':
+      return 'date'
+    case 'datetime':
+      return 'datetime'
+    case 'time':
+      return 'time'
+    case 'textarea':
+      return 'textarea'
+    case 'select':
+    case 'rich-select':
+    case 'list':
+    case 'chips':
+      return 'select'
+    default:
+      return 'text'
+  }
+}
+
+function emptyFor(field: FormFieldDescriptor): unknown {
+  return field.type === 'boolean' ? false : ''
+}
+
+// --- Editor value coercion --------------------------------------------------
+// Pure conversions between the form's stored value and the shape each rich
+// editor's `value` / `onChange` expects. Kept here (not inline in the .svelte)
+// so the tricky bits - local date formatting, number <-> '' , tag arrays - are
+// unit-testable without a DOM.
+
+const _p2 = (n: number) => String(n).padStart(2, '0')
+
+/** A `Date` -> a **local** `yyyy-MM-dd` string (matches the native date input; no UTC shift). */
+export function toDateString(d: Date | null | undefined): string {
+  return d ? `${d.getFullYear()}-${_p2(d.getMonth() + 1)}-${_p2(d.getDate())}` : ''
+}
+
+/** A `Date` -> a **local** `yyyy-MM-ddTHH:mm` string (matches `datetime-local`; no UTC shift). */
+export function toDateTimeString(d: Date | null | undefined): string {
+  return d ? `${toDateString(d)}T${_p2(d.getHours())}:${_p2(d.getMinutes())}` : ''
+}
+
+/** Stored value -> `SvNumberInput.value` (number | null); non-numbers become null. */
+export function toNumberValue(raw: unknown): number | null {
+  return typeof raw === 'number' && Number.isFinite(raw) ? raw : null
+}
+
+/** `SvNumberInput.onChange` payload -> stored value; null becomes '' (the empty convention). */
+export function fromNumberValue(v: number | null): number | '' {
+  return v == null ? '' : v
+}
+
+/** Stored value -> `SvSlider.value`; falls back to `min` when unset. */
+export function toSliderValue(raw: unknown, min: number): number {
+  return typeof raw === 'number' && Number.isFinite(raw) ? raw : min
+}
+
+/** Stored value -> `SvTagsInput.value` (string[]); splits a comma string, else wraps. */
+export function toTags(raw: unknown): string[] {
+  if (Array.isArray(raw)) return raw.map((t) => String(t))
+  if (raw == null || raw === '') return []
+  return String(raw).split(',').map((s) => s.trim()).filter(Boolean)
+}
+
+function isEmpty(value: unknown): boolean {
+  return value == null || value === ''
+}
+
+const EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/
+const URL_RE = /^https?:\/\/.+/
+
+/**
+ * Built-in validation from the field's own constraints - number validity,
+ * min/max, length, email/url format, regex - so forms validate out of the box
+ * without any external library. Returns the first violation, or null.
+ */
+export function builtInError(field: FormFieldDescriptor, value: unknown): string | null {
+  if (isEmpty(value)) return null
+  if (field.type === 'number') {
+    const n = Number(value)
+    if (!Number.isFinite(n)) return `${field.label} must be a number`
+    if (field.min != null && n < field.min) return `${field.label} must be at least ${field.min}`
+    if (field.max != null && n > field.max) return `${field.label} must be at most ${field.max}`
+    return null
+  }
+  const s = String(value)
+  if (field.minLength != null && s.length < field.minLength) {
+    return `${field.label} must be at least ${field.minLength} characters`
+  }
+  if (field.maxLength != null && s.length > field.maxLength) {
+    return `${field.label} must be at most ${field.maxLength} characters`
+  }
+  if (field.format === 'email' && !EMAIL_RE.test(s)) return `${field.label} must be a valid email`
+  if (field.format === 'url' && !URL_RE.test(s)) return `${field.label} must be a valid URL`
+  if (field.pattern && !new RegExp(field.pattern).test(s)) return `${field.label} is not in the right format`
+  return null
+}
+
+/**
+ * Seed the form's editable state. Uses the row's value when editing, else the
+ * field's `defaultValue`, else a type-appropriate empty. Covers every field the
+ * form shows (`schemaToFormFields`), including the read-only primary key so it
+ * can be displayed.
+ */
+export function buildInitialValues<TData extends RowData>(
+  schema: EntitySchema<TData>,
+  row: TData | null | undefined,
+): Record<string, unknown> {
+  const values: Record<string, unknown> = {}
+  const source = (row ?? null) as RowData | null
+  for (const f of schemaToFormFields(schema)) {
+    if (source && f.field in source) values[f.field] = source[f.field]
+    else if (f.defaultValue !== undefined) values[f.field] = f.defaultValue
+    else values[f.field] = emptyFor(f)
+  }
+  return values
+}
+
+/**
+ * Validate every editable field: required-but-empty first, then the field's
+ * Standard Schema validator (if any), then the schema-level cross-field
+ * `hooks.validate` (e.g. "end date must be after start date"). Returns a
+ * `{ field: message }` map with only the failing fields, so an empty object
+ * means the form is valid. Per-field errors take precedence over cross-field.
+ */
+export async function validateAll<TData extends RowData>(
+  schema: EntitySchema<TData>,
+  values: Record<string, unknown>,
+): Promise<Record<string, string>> {
+  const errors: Record<string, string> = {}
+  for (const f of schemaToFormFields(schema)) {
+    if (f.readonly) continue
+    const value = values[f.field]
+    if (f.required && f.type !== 'boolean' && isEmpty(value)) {
+      errors[f.field] = `${f.label} is required`
+      continue
+    }
+    const builtIn = builtInError(f, value)
+    if (builtIn) {
+      errors[f.field] = builtIn
+      continue
+    }
+    if (!isEmpty(value)) {
+      const msg = await validateField(f, value)
+      if (msg) errors[f.field] = msg
+    }
+  }
+  // Cross-field rules run last, and never overwrite a per-field error.
+  const crossField = await validateEntity(schema, values as Partial<TData>)
+  for (const [field, message] of Object.entries(crossField)) {
+    if (!errors[field]) errors[field] = message
+  }
+  return errors
+}
+
+function coerceOut(field: FormFieldDescriptor, value: unknown): unknown {
+  if (field.type === 'number') {
+    if (isEmpty(value)) return null
+    const n = Number(value)
+    return Number.isFinite(n) ? n : null
+  }
+  if (field.type === 'boolean') return value === true || value === 'true'
+  return value
+}
+
+/**
+ * Build the payload to send to `createRow` / `updateRow`. Read-only fields
+ * (including the primary key) are never submitted; the id for an update is
+ * resolved separately via `rowId`. Values are coerced back to their runtime
+ * type (number strings to numbers, checkbox state to booleans).
+ */
+export function toSubmitValues<TData extends RowData>(
+  schema: EntitySchema<TData>,
+  values: Record<string, unknown>,
+): Partial<TData> {
+  const out: Record<string, unknown> = {}
+  for (const f of schemaToFormFields(schema)) {
+    if (f.readonly) continue
+    out[f.field] = coerceOut(f, values[f.field])
+  }
+  return out as Partial<TData>
+}
+
+/** The stable id of the row being edited, as a string (for `updateRow`). */
+export function rowId<TData extends RowData>(schema: EntitySchema<TData>, row: TData): string {
+  const idField = resolveIdField(schema)
+  return String((row as RowData)[idField])
+}

package/src/export-conditional.test.ts

@@ -0,0 +1,60 @@
+import { describe, expect, it } from 'vitest'
+import { buildConditionalResolver } from './export-conditional'
+import type { ConditionalFormat } from '@svgrid/grid/format'
+
+type Row = { name: string; score: number }
+const cols = [{ field: 'name' }, { field: 'score' }]
+const rows: Row[] = [
+  { name: 'A', score: 10 },
+  { name: 'B', score: 90 },
+  { name: 'C', score: 50 },
+]
+
+describe('buildConditionalResolver', () => {
+  it('is a no-op with no formats', () => {
+    const r = buildConditionalResolver(cols, rows, undefined)
+    expect(r(0, 1)).toBeUndefined()
+  })
+
+  it('resolves a color scale (with per-column stats) only on its columns', () => {
+    const formats: ConditionalFormat<Row>[] = [
+      { type: 'colorScale', columns: ['score'], min: '#ff0000', max: '#00ff00' },
+    ]
+    const r = buildConditionalResolver(cols, rows, formats)
+    expect(r(1, 1)?.fill).toBeTruthy() // high score -> greenish
+    expect(r(1, 1)?.color).toBeTruthy() // contrast text auto-picked
+    expect(r(0, 0)).toBeUndefined() // name column untouched
+  })
+
+  it('applies a predicate rule with background + bold', () => {
+    const formats: ConditionalFormat<Row>[] = [
+      {
+        type: 'rule',
+        columns: ['score'],
+        when: ({ value }) => Number(value) >= 90,
+        background: '#dcfce7',
+        fontWeight: 'bold',
+      },
+    ]
+    const r = buildConditionalResolver(cols, rows, formats)
+    expect(r(1, 1)).toMatchObject({ fill: '#dcfce7', bold: true })
+    expect(r(0, 1)).toBeUndefined() // score 10 doesn't match
+  })
+
+  it('emits an icon-set glyph', () => {
+    const formats: ConditionalFormat<Row>[] = [
+      { type: 'iconSet', columns: ['score'], thresholds: [33, 66] },
+    ]
+    const r = buildConditionalResolver(cols, rows, formats)
+    expect(r(1, 1)?.icon).toBeTruthy() // high bucket
+    expect(r(0, 1)?.icon).toBeTruthy() // low bucket
+  })
+
+  it('degrades a data bar to a light fill', () => {
+    const formats: ConditionalFormat<Row>[] = [
+      { type: 'dataBar', columns: ['score'], color: '#3b82f6' },
+    ]
+    const r = buildConditionalResolver(cols, rows, formats)
+    expect(r(1, 1)?.fill).toMatch(/^#/) // a lightened fill
+  })
+})

package/src/export-conditional.ts

@@ -0,0 +1,94 @@
+/**
+ * Carry the grid's conditional formatting (color scales, data bars, icon sets,
+ * predicate rules) into the styled export formats - PDF, xlsx, HTML, and the
+ * print view. The grid's engine (`resolveCellFormat`) is pure and reused here
+ * via the Svelte-free `@svgrid/grid/format` subpath; this module turns a
+ * `ResolvedCellFormat` into the primitives the exporters can render:
+ * `{ fill, color, bold, icon }`.
+ *
+ * Data formats (csv / tsv / json / xml / md) are unstyled, so conditional
+ * formatting is ignored there. Data bars can't render as partial-width bars in
+ * a spreadsheet cell / PDF cell, so they degrade to a light fill of the bar
+ * color; icon sets prepend the icon glyph to the cell text.
+ */
+import {
+  computeColumnStat,
+  formatsNeedingStats,
+  resolveCellFormat,
+  type ColumnStat,
+  type ConditionalFormat,
+  type ResolvedCellFormat,
+} from '@svgrid/grid/format'
+import type { RowData } from '@svgrid/grid'
+import type { ExportColumn } from './export'
+
+/** The visual primitives an exporter can apply to one cell. */
+export type ExportCellVisual = {
+  fill?: string
+  color?: string
+  bold?: boolean
+  /** Icon-set glyph to prepend to the cell text. */
+  icon?: string
+}
+
+export type ExportCellVisualFn = (rowIdx: number, colIdx: number) => ExportCellVisual | undefined
+
+/** Lighten a hex color toward white by `amt` (0..1). Returns input if unparseable. */
+function mixWhite(hex: string, amt: number): string {
+  const m = /^#?([0-9a-f]{6})$/i.exec(hex.trim())
+  if (!m) return hex
+  const int = parseInt(m[1]!, 16)
+  const ch = [(int >> 16) & 255, (int >> 8) & 255, int & 255]
+  return (
+    '#' +
+    ch.map((c) => Math.round(c + (255 - c) * amt).toString(16).padStart(2, '0')).join('')
+  )
+}
+
+function toVisual(resolved: ResolvedCellFormat): ExportCellVisual | undefined {
+  const v: ExportCellVisual = {}
+  if (resolved.background) v.fill = resolved.background
+  // Data bar -> a light fill of the bar color (no partial-width bars in cells).
+  if (!v.fill && resolved.dataBar) v.fill = mixWhite(resolved.dataBar.color, 0.72)
+  if (resolved.color && resolved.color !== 'transparent') v.color = resolved.color
+  if (
+    resolved.fontWeight === 'bold' ||
+    (typeof resolved.fontWeight === 'number' && resolved.fontWeight >= 600)
+  ) {
+    v.bold = true
+  }
+  if (resolved.icon) v.icon = resolved.icon
+  return Object.keys(v).length > 0 ? v : undefined
+}
+
+/**
+ * Precompute per-column stats (for color scales / data bars) and return a
+ * `(rowIdx, colIdx) => ExportCellVisual | undefined` lookup over the given
+ * rows + columns. Returns a no-op when there are no formats.
+ */
+export function buildConditionalResolver<TData extends RowData>(
+  cols: ReadonlyArray<ExportColumn<TData>>,
+  rows: ReadonlyArray<TData>,
+  formats: ReadonlyArray<ConditionalFormat<TData>> | undefined,
+): ExportCellVisualFn {
+  if (!formats || formats.length === 0) return () => undefined
+
+  const stats = new Map<string, ColumnStat | null>()
+  if (formatsNeedingStats(formats)) {
+    for (const c of cols) {
+      stats.set(
+        c.field,
+        computeColumnStat(rows.map((r) => (r as Record<string, unknown>)[c.field])),
+      )
+    }
+  }
+
+  return (rowIdx, colIdx) => {
+    const col = cols[colIdx]
+    const row = rows[rowIdx]
+    if (!col || !row) return undefined
+    const raw = (row as Record<string, unknown>)[col.field]
+    const resolved = resolveCellFormat(raw, row, col.field, formats, stats.get(col.field) ?? null)
+    return toVisual(resolved)
+  }
+}