@svgrid/enterprise 1.2.0 → 2.0.0

package/src/schema-designer.test.ts

@@ -0,0 +1,121 @@
+import { describe, expect, it } from 'vitest'
+import type { EntitySchema } from './schema'
+import {
+  addField,
+  blankField,
+  isSchemaValid,
+  moveField,
+  removeField,
+  sampleRows,
+  updateField,
+  validateSchema,
+} from './schema-designer'
+
+function base(): EntitySchema {
+  return {
+    name: 'customers',
+    idField: 'id',
+    fields: [
+      { field: 'id', type: 'text', primaryKey: true, readonly: true },
+      { field: 'name', type: 'text' },
+      { field: 'tier', type: 'enum', options: [{ value: 'free', label: 'Free' }] },
+    ],
+  }
+}
+
+describe('blankField / addField', () => {
+  it('adds a uniquely named blank field', () => {
+    const s = addField(base())
+    expect(s.fields).toHaveLength(4)
+    const added = s.fields[3]!
+    expect(added.type).toBe('text')
+    expect(base().fields.map((f) => f.field)).not.toContain(added.field)
+  })
+
+  it('avoids name collisions', () => {
+    const s: EntitySchema = { name: 't', fields: [{ field: 'field1', type: 'text' }] }
+    expect(blankField(s).field).not.toBe('field1')
+  })
+})
+
+describe('removeField', () => {
+  it('removes and clears idField if it pointed there', () => {
+    const s = removeField(base(), 'id')
+    expect(s.fields.map((f) => f.field)).toEqual(['name', 'tier'])
+    expect(s.idField).toBeUndefined()
+  })
+})
+
+describe('updateField', () => {
+  it('patches a field', () => {
+    const s = updateField(base(), 'name', { label: 'Full Name', required: true })
+    const f = s.fields.find((x) => x.field === 'name')!
+    expect(f.label).toBe('Full Name')
+    expect(f.required).toBe(true)
+  })
+
+  it('enforces a single primary key', () => {
+    const s = updateField(base(), 'name', { primaryKey: true })
+    expect(s.fields.find((f) => f.field === 'id')!.primaryKey).toBe(false)
+    expect(s.fields.find((f) => f.field === 'name')!.primaryKey).toBe(true)
+  })
+
+  it('drops options when a field leaves the enum type', () => {
+    const s = updateField(base(), 'tier', { type: 'text' })
+    expect(s.fields.find((f) => f.field === 'tier')!.options).toBeUndefined()
+  })
+})
+
+describe('moveField', () => {
+  it('reorders and is a no-op at the ends', () => {
+    expect(moveField(base(), 'name', -1).fields.map((f) => f.field)).toEqual(['name', 'id', 'tier'])
+    expect(moveField(base(), 'id', -1).fields.map((f) => f.field)).toEqual(['id', 'name', 'tier'])
+  })
+})
+
+describe('validateSchema', () => {
+  it('is clean for a well-formed schema', () => {
+    expect(validateSchema(base())).toEqual([])
+    expect(isSchemaValid(base())).toBe(true)
+  })
+
+  it('errors on duplicate names', () => {
+    const s: EntitySchema = {
+      name: 't',
+      idField: 'id',
+      fields: [{ field: 'id', type: 'text' }, { field: 'id', type: 'number' }],
+    }
+    expect(validateSchema(s).some((i) => i.level === 'error' && /Duplicate/.test(i.message))).toBe(true)
+  })
+
+  it('errors when no primary key resolves', () => {
+    const s: EntitySchema = { name: 't', fields: [{ field: 'x', type: 'text' }] }
+    expect(isSchemaValid(s)).toBe(false)
+    expect(validateSchema(s).some((i) => /primary key/.test(i.message))).toBe(true)
+  })
+
+  it('warns on an enum with no options and an incomplete relation', () => {
+    const s: EntitySchema = {
+      name: 't',
+      idField: 'id',
+      fields: [
+        { field: 'id', type: 'text', primaryKey: true },
+        { field: 'k', type: 'enum' },
+        { field: 'r', type: 'relation' },
+      ],
+    }
+    const warnings = validateSchema(s).filter((i) => i.level === 'warning')
+    expect(warnings.map((w) => w.field).sort()).toEqual(['k', 'r'])
+  })
+})
+
+describe('sampleRows', () => {
+  it('produces deterministic, type-appropriate sample data', () => {
+    const rows = sampleRows(base(), 2)
+    expect(rows).toHaveLength(2)
+    expect(rows[0]!.tier).toBe('free') // first enum option
+    expect(typeof rows[0]!.name).toBe('string')
+    // deterministic: same input, same output
+    expect(sampleRows(base(), 2)).toEqual(rows)
+  })
+})

package/src/schema-designer.ts

@@ -0,0 +1,142 @@
+/**
+ * Schema-designer logic. The testable core behind `SvSchemaDesigner.svelte`:
+ * immutable operations that edit an `EntitySchema` (add / remove / reorder /
+ * retype fields, set the primary key), validation of the schema being designed,
+ * and sample-row generation for the live grid preview.
+ *
+ * Pure (no Svelte, no DOM), mirroring the pivot-designer / edit-panel split.
+ * Every mutation returns a NEW schema so Svelte reactivity and undo stay simple.
+ */
+import type { EntityField, EntityFieldType, EntitySchema } from './schema'
+import { resolveIdField } from './schema'
+import { generateRows } from './studio/sample-data'
+
+/** All field types the designer offers, in menu order. */
+export const FIELD_TYPES: ReadonlyArray<EntityFieldType> = [
+  'text',
+  'number',
+  'boolean',
+  'date',
+  'dateString',
+  'datetime',
+  'enum',
+  'relation',
+  'json',
+]
+
+/** A fresh field with a name unique within the schema. */
+export function blankField(schema: EntitySchema): EntityField {
+  const taken = new Set(schema.fields.map((f) => f.field))
+  let n = schema.fields.length + 1
+  let name = `field${n}`
+  while (taken.has(name)) name = `field${++n}`
+  return { field: name, type: 'text' }
+}
+
+/** Append a field (a blank one when none is given). */
+export function addField(schema: EntitySchema, field?: EntityField): EntitySchema {
+  return { ...schema, fields: [...schema.fields, field ?? blankField(schema)] }
+}
+
+/** Remove a field by name. Clears `idField` if it pointed at the removed field. */
+export function removeField(schema: EntitySchema, fieldName: string): EntitySchema {
+  const fields = schema.fields.filter((f) => f.field !== fieldName)
+  const idField = schema.idField === fieldName ? undefined : schema.idField
+  return { ...schema, fields, idField }
+}
+
+/**
+ * Patch a field by name. Setting `primaryKey: true` clears it on every other
+ * field (a schema has at most one). Switching `type` drops now-irrelevant
+ * `options` (leaving enum) / `relation` (leaving relation).
+ */
+export function updateField(
+  schema: EntitySchema,
+  fieldName: string,
+  patch: Partial<EntityField>,
+): EntitySchema {
+  const makesPrimary = patch.primaryKey === true
+  const fields = schema.fields.map((f) => {
+    if (f.field !== fieldName) {
+      return makesPrimary && f.primaryKey ? { ...f, primaryKey: false } : f
+    }
+    let next: EntityField = { ...f, ...patch }
+    if (patch.type && patch.type !== f.type) {
+      if (patch.type !== 'enum') delete next.options
+      if (patch.type !== 'relation') delete next.relation
+    }
+    return next
+  })
+  return { ...schema, fields }
+}
+
+/** Move a field one slot up (`-1`) or down (`+1`). No-op at the ends. */
+export function moveField(schema: EntitySchema, fieldName: string, dir: -1 | 1): EntitySchema {
+  const i = schema.fields.findIndex((f) => f.field === fieldName)
+  const j = i + dir
+  if (i < 0 || j < 0 || j >= schema.fields.length) return schema
+  const fields = [...schema.fields]
+  const a = fields[i]!
+  const b = fields[j]!
+  fields[i] = b
+  fields[j] = a
+  return { ...schema, fields }
+}
+
+export type SchemaIssueLevel = 'error' | 'warning'
+export type SchemaIssue = { level: SchemaIssueLevel; message: string; field?: string }
+
+/**
+ * Validate the schema under construction. Errors block code generation;
+ * warnings are advisory. Covers: at least one field, unique field names, a
+ * resolvable primary key, enums with options, and complete relations.
+ */
+export function validateSchema(schema: EntitySchema): SchemaIssue[] {
+  const issues: SchemaIssue[] = []
+
+  if (schema.fields.length === 0) {
+    issues.push({ level: 'error', message: 'Add at least one field.' })
+  }
+
+  const seen = new Set<string>()
+  for (const f of schema.fields) {
+    if (!f.field.trim()) {
+      issues.push({ level: 'error', message: 'A field has an empty name.' })
+    } else if (seen.has(f.field)) {
+      issues.push({ level: 'error', message: `Duplicate field name "${f.field}".`, field: f.field })
+    }
+    seen.add(f.field)
+
+    if (f.type === 'enum' && (!f.options || f.options.length === 0)) {
+      issues.push({ level: 'warning', message: `Enum "${f.field}" has no options.`, field: f.field })
+    }
+    if (f.type === 'relation' && (!f.relation?.entity || !f.relation?.labelField)) {
+      issues.push({
+        level: 'warning',
+        message: `Relation "${f.field}" needs a related entity and label field.`,
+        field: f.field,
+      })
+    }
+  }
+
+  try {
+    resolveIdField(schema)
+  } catch {
+    issues.push({
+      level: 'error',
+      message: 'No primary key: flag a field as primary key, set idField, or name a field "id".',
+    })
+  }
+
+  return issues
+}
+
+/** True when the schema has no error-level issues (warnings are allowed). */
+export function isSchemaValid(schema: EntitySchema): boolean {
+  return !validateSchema(schema).some((i) => i.level === 'error')
+}
+
+/** Deterministic, realistic sample rows for the designer's grid preview. */
+export function sampleRows(schema: EntitySchema, count = 3): Array<Record<string, unknown>> {
+  return generateRows(schema.fields, count)
+}

package/src/schema.test.ts

@@ -0,0 +1,268 @@
+import { describe, expect, it } from 'vitest'
+import {
+  applyComputed,
+  resolveIdField,
+  schemaToColumns,
+  schemaToFormFields,
+  titleCase,
+  validateEntity,
+  validateField,
+  type EntitySchema,
+  type StandardSchemaV1,
+} from './schema'
+
+/** Index a list by `field`, asserting presence (keeps tests strict-null clean). */
+function byField<T extends { field?: string }>(arr: readonly T[]): (f: string) => T {
+  const m = new Map(arr.map((x) => [x.field, x]))
+  return (f) => {
+    const v = m.get(f)
+    if (!v) throw new Error(`no field "${f}"`)
+    return v
+  }
+}
+
+type Customer = {
+  id: string
+  firstName: string
+  age: number
+  active: boolean
+  tier: string
+  secret: string
+  companyId: string
+}
+
+const schema: EntitySchema<Customer> = {
+  name: 'customers',
+  fields: [
+    { field: 'id', type: 'text', primaryKey: true, readonly: true },
+    { field: 'firstName', type: 'text', required: true },
+    { field: 'age', type: 'number' },
+    { field: 'active', type: 'boolean' },
+    { field: 'tier', type: 'enum', options: [{ value: 'free', label: 'Free' }, { value: 'pro', label: 'Pro' }] },
+    { field: 'secret', type: 'text', hidden: { grid: true } },
+    { field: 'companyId', type: 'relation', relation: { entity: 'companies', labelField: 'name' } },
+  ],
+}
+
+describe('titleCase', () => {
+  it('humanizes snake, kebab, and camel case', () => {
+    expect(titleCase('first_name')).toBe('First Name')
+    expect(titleCase('first-name')).toBe('First Name')
+    expect(titleCase('firstName')).toBe('First Name')
+    expect(titleCase('companyId')).toBe('Company Id')
+  })
+})
+
+describe('resolveIdField', () => {
+  it('prefers explicit idField', () => {
+    expect(resolveIdField({ ...schema, idField: 'firstName' })).toBe('firstName')
+  })
+  it('falls back to the single primaryKey flag', () => {
+    expect(resolveIdField(schema)).toBe('id')
+  })
+  it('falls back to a field named id', () => {
+    const s: EntitySchema = { name: 't', fields: [{ field: 'id', type: 'text' }, { field: 'x', type: 'text' }] }
+    expect(resolveIdField(s)).toBe('id')
+  })
+  it('throws on multiple primary keys', () => {
+    const s: EntitySchema = {
+      name: 't',
+      fields: [{ field: 'a', type: 'text', primaryKey: true }, { field: 'b', type: 'text', primaryKey: true }],
+    }
+    expect(() => resolveIdField(s)).toThrow(/multiple fields set primaryKey/)
+  })
+  it('throws when no key resolves', () => {
+    const s: EntitySchema = { name: 't', fields: [{ field: 'x', type: 'text' }] }
+    expect(() => resolveIdField(s)).toThrow(/no primary key/)
+  })
+})
+
+describe('schemaToColumns', () => {
+  const cols = schemaToColumns(schema)
+  const col = byField(cols)
+
+  it('drops grid-hidden fields', () => {
+    expect(cols.find((c) => c.field === 'secret')).toBeUndefined()
+    expect(cols).toHaveLength(6)
+  })
+
+  it('maps types to cellDataType / editorType', () => {
+    expect(col('age').cellDataType).toBe('number')
+    expect(col('active').cellDataType).toBe('boolean')
+    expect(col('age').editorType).toBe('number')
+    expect(col('tier').editorType).toBe('select')
+  })
+
+  it('marks readonly fields non-editable and carries enum options through', () => {
+    expect(col('id').editable).toBe(false)
+    expect(col('firstName').editable).toBe(true)
+    expect(col('tier').editorOptions).toEqual([
+      { value: 'free', label: 'Free' },
+      { value: 'pro', label: 'Pro' },
+    ])
+  })
+
+  it('derives a title-cased header from the field', () => {
+    expect(col('firstName').header).toBe('First Name')
+  })
+
+  it('merges the column escape hatch last (explicit wins)', () => {
+    const s: EntitySchema<Customer> = {
+      name: 'c',
+      idField: 'id',
+      fields: [{ field: 'age', type: 'number', column: { header: 'Years', editable: false } }],
+    }
+    const only = schemaToColumns(s)[0]
+    expect(only?.header).toBe('Years')
+    expect(only?.editable).toBe(false)
+  })
+})
+
+describe('schemaToFormFields', () => {
+  const fields = schemaToFormFields(schema)
+  const ff = byField(fields)
+
+  it('keeps fields that are only hidden from the grid', () => {
+    // `secret` is hidden:{grid:true} so it stays in the form
+    expect(fields.find((f) => f.field === 'secret')).toBeDefined()
+  })
+
+  it('forces the primary key read-only and non-required', () => {
+    expect(ff('id').readonly).toBe(true)
+    expect(ff('id').required).toBe(false)
+  })
+
+  it('carries required, options, and relation through', () => {
+    expect(ff('firstName').required).toBe(true)
+    expect(ff('tier').options).toHaveLength(2)
+    expect(ff('companyId').relation).toEqual({ entity: 'companies', labelField: 'name' })
+  })
+
+  it('carries a form-only editor override (phone/mask) into the descriptor', () => {
+    const s: EntitySchema = {
+      name: 'm', idField: 'id',
+      fields: [
+        { field: 'id', type: 'text', primaryKey: true },
+        { field: 'phone', type: 'text', input: { editorType: 'phone' } },
+        { field: 'code', type: 'text', input: { editorType: 'mask', mask: '(999) 000-0000' } },
+        { field: 'score', type: 'number', input: { editorType: 'slider' } },
+      ],
+    }
+    const f = byField(schemaToFormFields(s))
+    expect(f('phone').editorType).toBe('phone')
+    expect(f('code').editorType).toBe('mask')
+    expect(f('code').mask).toBe('(999) 000-0000')
+    expect(f('score').editorType).toBe('slider')
+  })
+
+  it('degrades form-only editors to a safe grid cell editor (columns stay valid)', () => {
+    const s: EntitySchema = {
+      name: 'm', idField: 'id',
+      fields: [
+        { field: 'id', type: 'text', primaryKey: true },
+        { field: 'phone', type: 'text', input: { editorType: 'phone' } },
+        { field: 'score', type: 'number', input: { editorType: 'slider' } },
+      ],
+    }
+    const col = (name: string) => schemaToColumns(s).find((c) => c.field === name)!
+    expect(col('phone').editorType).toBe('text')   // phone/country/mask -> text in the grid
+    expect(col('score').editorType).toBe('number') // slider -> number in the grid
+  })
+
+  it('threads an upload config through to the form descriptor', () => {
+    const s: EntitySchema = {
+      name: 'm', idField: 'id',
+      fields: [
+        { field: 'id', type: 'text', primaryKey: true },
+        { field: 'avatar', type: 'text', upload: { image: true, accept: 'image/*' } },
+      ],
+    }
+    expect(byField(schemaToFormFields(s))('avatar').upload).toEqual({ image: true, accept: 'image/*' })
+  })
+})
+
+describe('validateField', () => {
+  // Hand-rolled Standard Schema validator (no Zod dependency in the test).
+  const nonEmpty: StandardSchemaV1<string, string> = {
+    '~standard': {
+      version: 1,
+      vendor: 'test',
+      validate: (v) =>
+        typeof v === 'string' && v.length > 0
+          ? { value: v }
+          : { issues: [{ message: 'Required' }] },
+    },
+  }
+
+  it('returns null when there is no validator', async () => {
+    expect(await validateField({}, 'anything')).toBeNull()
+  })
+  it('returns null on a valid value', async () => {
+    expect(await validateField({ validate: nonEmpty }, 'ok')).toBeNull()
+  })
+  it('returns the first issue message on an invalid value', async () => {
+    expect(await validateField({ validate: nonEmpty }, '')).toBe('Required')
+  })
+})
+
+describe('computed fields', () => {
+  type Line = { id: string; qty: number; price: number; total: number }
+  const lineSchema: EntitySchema<Line> = {
+    name: 'lines',
+    fields: [
+      { field: 'id', type: 'text', primaryKey: true, readonly: true },
+      { field: 'qty', type: 'number', required: true },
+      { field: 'price', type: 'number', required: true },
+      { field: 'total', type: 'number', computed: (r) => Number(r.qty) * Number(r.price) },
+    ],
+  }
+
+  it('materializes computed values onto a row', () => {
+    const out = applyComputed(lineSchema, { id: '1', qty: 3, price: 10, total: 0 })
+    expect(out.total).toBe(30)
+  })
+
+  it('returns the same row object when there are no computed fields', () => {
+    const row = { id: '1', qty: 3, price: 10, total: 0 }
+    expect(applyComputed({ ...lineSchema, fields: lineSchema.fields.slice(0, 3) }, row)).toBe(row)
+  })
+
+  it('renders a computed field read-only in the grid and form', () => {
+    const col = schemaToColumns(lineSchema).find((c) => c.field === 'total')!
+    expect(col.editable).toBe(false)
+    const ff = schemaToFormFields(lineSchema).find((f) => f.field === 'total')!
+    expect(ff.readonly).toBe(true)
+    expect(typeof ff.computed).toBe('function')
+  })
+
+  it('wires a computed field to the grid value accessor (fieldFn), so it sorts/filters client-side', () => {
+    const col = schemaToColumns(lineSchema).find((c) => c.field === 'total')!
+    expect(typeof col.fieldFn).toBe('function')
+    expect(col.fieldFn!({ id: '1', qty: 4, price: 25, total: 0 })).toBe(100)
+  })
+})
+
+describe('validateEntity (schema-level cross-field)', () => {
+  type Range = { id: string; start: number; end: number }
+  const rangeSchema: EntitySchema<Range> = {
+    name: 'ranges',
+    fields: [
+      { field: 'id', type: 'text', primaryKey: true },
+      { field: 'start', type: 'number' },
+      { field: 'end', type: 'number' },
+    ],
+    hooks: {
+      validate: (v) => (Number(v.end) <= Number(v.start) ? { end: 'End must be after start' } : null),
+    },
+  }
+
+  it('returns {} when there is no validate hook', async () => {
+    expect(await validateEntity({ ...rangeSchema, hooks: undefined }, {})).toEqual({})
+  })
+  it('returns errors from the hook', async () => {
+    expect(await validateEntity(rangeSchema, { start: 5, end: 2 })).toEqual({ end: 'End must be after start' })
+  })
+  it('returns {} when valid', async () => {
+    expect(await validateEntity(rangeSchema, { start: 1, end: 9 })).toEqual({})
+  })
+})