@pilotiq/pilotiq 0.1.0

package/src/fields/RepeaterSimple.test.ts

@@ -0,0 +1,248 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { RepeaterField, type RepeaterFieldMeta } from './RepeaterField.js'
+import { TextField } from './TextField.js'
+import { resolveSchema } from '../schema/resolveSchema.js'
+import {
+  coerceFormValues,
+  unwrapSimpleRepeaters,
+  dispatchFormSubmit,
+} from '../elements/dispatchForm.js'
+import { Form } from '../elements/Form.js'
+import { validateSchema, isValid } from '../validation/index.js'
+
+function metaOf(m: unknown): RepeaterFieldMeta { return m as RepeaterFieldMeta }
+
+describe('Repeater.simple(field) — flat-array storage shape', () => {
+  describe('flag plumbing', () => {
+    it('isSimple() defaults false; simple() flips it true', () => {
+      const f = RepeaterField.make('tags')
+      assert.equal(f.isSimple(), false)
+      f.simple(TextField.make('tag'))
+      assert.equal(f.isSimple(), true)
+    })
+
+    it('simple() sets the inner schema to the single field', () => {
+      const inner = TextField.make('tag')
+      const f = RepeaterField.make('tags').simple(inner)
+      assert.deepEqual(f.getInnerSchema(), [inner])
+      assert.equal(f.getSimpleInnerField(), inner)
+    })
+
+    it('simple() replaces any prior schema()', () => {
+      const f = RepeaterField.make('tags')
+        .schema([TextField.make('a'), TextField.make('b')])
+        .simple(TextField.make('tag'))
+      assert.equal(f.getInnerSchema().length, 1)
+    })
+
+    it('emits meta.simple = true', () => {
+      const m = RepeaterField.make('tags').simple(TextField.make('tag')).toMeta()
+      assert.equal(m.simple, true)
+    })
+
+    it('non-simple repeaters omit meta.simple', () => {
+      const m = RepeaterField.make('items').schema([TextField.make('x')]).toMeta()
+      assert.equal('simple' in m, false)
+    })
+
+    it('getSimpleInnerField() returns undefined outside simple mode', () => {
+      const f = RepeaterField.make('items').schema([TextField.make('x')])
+      assert.equal(f.getSimpleInnerField(), undefined)
+    })
+  })
+
+  describe('resolve — wraps flat array entries inline', () => {
+    function makeRep() {
+      return RepeaterField.make('tags').simple(TextField.make('tag'))
+    }
+
+    it('flat record value [v1, v2] → row children mounted with right name', async () => {
+      const [raw] = await resolveSchema([makeRep()], {
+        values: { tags: ['red', 'green', 'blue'] },
+      })
+      const m = metaOf(raw)
+      assert.equal(m.rows.length, 3)
+      // Each row's first child is a TextField named 'tag'.
+      for (const row of m.rows) {
+        const child = row.children[0] as unknown as { name?: string }
+        assert.equal(child.name, 'tag')
+      }
+    })
+
+    it('already-wrapped value [{tag:v}] still works (idempotent)', async () => {
+      const [raw] = await resolveSchema([makeRep()], {
+        values: { tags: [{ tag: 'red' }, { tag: 'blue' }] },
+      })
+      const m = metaOf(raw)
+      assert.equal(m.rows.length, 2)
+    })
+
+    it('empty array → zero rows (defaultItems is not applied when an array exists)', async () => {
+      const [raw] = await resolveSchema([makeRep()], { values: { tags: [] } })
+      const m = metaOf(raw)
+      assert.equal(m.rows.length, 0)
+    })
+
+    it('no submitted value → defaultItems empty rows', async () => {
+      const [raw] = await resolveSchema([makeRep().defaultItems(2)])
+      const m = metaOf(raw)
+      assert.equal(m.rows.length, 2)
+    })
+  })
+
+  describe('coerce — produces wrapped shape, then unwrapSimpleRepeaters flattens', () => {
+    function makeRep() {
+      return RepeaterField.make('tags').simple(TextField.make('tag'))
+    }
+
+    it('flat-key form body folds + unwraps to flat array', () => {
+      const data = coerceFormValues([makeRep()], {
+        'tags.0.tag': 'red',
+        'tags.1.tag': 'green',
+      })
+      // Coerce alone produces wrapped shape:
+      assert.deepEqual(data['tags'], [{ tag: 'red' }, { tag: 'green' }])
+      // unwrapSimpleRepeaters flattens.
+      const out = unwrapSimpleRepeaters([makeRep()], data)
+      assert.deepEqual(out['tags'], ['red', 'green'])
+    })
+
+    it('JSON body with primitive entries is wrapped, then unwrapped', () => {
+      const data = coerceFormValues([makeRep()], {
+        tags: ['red', 'green', 'blue'],
+      })
+      const out = unwrapSimpleRepeaters([makeRep()], data)
+      assert.deepEqual(out['tags'], ['red', 'green', 'blue'])
+    })
+
+    it('drops trailing empty rows like a regular Repeater', () => {
+      const data = coerceFormValues([makeRep()], {
+        'tags.0.tag': 'red',
+        'tags.1.tag': '',
+      })
+      const out = unwrapSimpleRepeaters([makeRep()], data)
+      assert.deepEqual(out['tags'], ['red'])
+    })
+
+    it('dehydrated(false) removes the field entirely', () => {
+      const f = makeRep().dehydrated(false)
+      const data = coerceFormValues([f], { 'tags.0.tag': 'red' })
+      assert.equal('tags' in data, false)
+      const out = unwrapSimpleRepeaters([f], data)
+      assert.equal('tags' in out, false)
+    })
+
+    it('non-simple repeaters are untouched by unwrap', () => {
+      const f = RepeaterField.make('items').schema([
+        TextField.make('product'),
+      ])
+      const data = coerceFormValues([f], { 'items.0.product': 'A' })
+      const out = unwrapSimpleRepeaters([f], data)
+      assert.deepEqual(out['items'], [{ product: 'A' }])
+    })
+  })
+
+  describe('validation — runs against wrapped row shape transparently', () => {
+    function makeRep() {
+      return RepeaterField.make('tags').simple(
+        TextField.make('tag').required(),
+      )
+    }
+
+    it('flat array — required check fires on each empty row', async () => {
+      const errors = await validateSchema([makeRep()], {
+        tags: ['red', '', 'blue'],
+      })
+      assert.deepEqual(errors['tags.1.tag'], ['This field is required'])
+    })
+
+    it('all valid — no errors', async () => {
+      const errors = await validateSchema([makeRep()], {
+        tags: ['red', 'green'],
+      })
+      assert.equal(isValid(errors), true)
+    })
+
+    it('flat-key body folds + validates non-trailing empty rows', async () => {
+      // Trailing empty rows are trimmed by `foldFlatRepeaterRows` (same
+      // posture as a non-simple Repeater); a non-trailing empty row
+      // survives and fires the required check.
+      const errors = await validateSchema([makeRep()], {
+        'tags.0.tag': 'red',
+        'tags.1.tag': '',
+        'tags.2.tag': 'blue',
+      })
+      assert.deepEqual(errors['tags.1.tag'], ['This field is required'])
+    })
+
+    it('minItems / maxItems work', async () => {
+      const f = RepeaterField.make('tags')
+        .simple(TextField.make('tag'))
+        .minItems(2)
+      const errors = await validateSchema([f], { tags: ['only-one'] })
+      assert.deepEqual(errors['tags'], ['At least 2 items are required'])
+    })
+
+    it('distinct() works against flat values', async () => {
+      const f = RepeaterField.make('tags').simple(
+        TextField.make('tag').distinct(),
+      )
+      const errors = await validateSchema([f], {
+        tags: ['red', 'red', 'blue'],
+      })
+      assert.deepEqual(errors['tags.1.tag'], ['Must be unique'])
+    })
+  })
+
+  describe('end-to-end form submit — save() handler receives flat array', () => {
+    it('flat-key body → flat array delivered to save()', async () => {
+      let saved: unknown = null
+      const form = Form.make<unknown>().schema([
+        RepeaterField.make('tags').simple(TextField.make('tag')),
+      ]).save(async (data) => {
+        saved = data
+        return data
+      })
+
+      const result = await dispatchFormSubmit(form, {
+        'tags.0.tag': 'red',
+        'tags.1.tag': 'green',
+      }, { values: {} })
+      assert.equal(result.ok, true)
+      assert.deepEqual((saved as Record<string, unknown>)['tags'], ['red', 'green'])
+    })
+
+    it('JSON body with primitive array → flat array delivered to save()', async () => {
+      let saved: unknown = null
+      const form = Form.make<unknown>().schema([
+        RepeaterField.make('tags').simple(TextField.make('tag')),
+      ]).save(async (data) => {
+        saved = data
+        return data
+      })
+
+      const result = await dispatchFormSubmit(form, {
+        tags: ['red', 'green', 'blue'],
+      }, { values: {} })
+      assert.equal(result.ok, true)
+      assert.deepEqual((saved as Record<string, unknown>)['tags'], ['red', 'green', 'blue'])
+    })
+
+    it('validation errors short-circuit before unwrap (errors keyed normally)', async () => {
+      const form = Form.make<unknown>().schema([
+        RepeaterField.make('tags').simple(
+          TextField.make('tag').required(),
+        ),
+      ]).save(async (data) => data)
+
+      const result = await dispatchFormSubmit(form, {
+        tags: ['red', ''],
+      }, { values: {} })
+      assert.equal(result.ok, false)
+      if (result.ok) return
+      assert.deepEqual(result.errors['tags.1.tag'], ['This field is required'])
+    })
+  })
+})

package/src/fields/RowButton.test.ts

@@ -0,0 +1,149 @@
+import { describe, test } from 'node:test'
+import assert from 'node:assert/strict'
+import { RowButton } from './RowButton.js'
+import { Repeater } from './RepeaterField.js'
+import { Builder } from './BuilderField.js'
+import { Block } from '../schema/Block.js'
+import { TextField } from './TextField.js'
+
+describe('RowButton', () => {
+  test('toMeta() drops unset keys so renderer ?? doesn\'t clobber defaults', () => {
+    assert.deepEqual(RowButton.make().toMeta(), {})
+    assert.deepEqual(RowButton.make().label('Add line').toMeta(), { label: 'Add line' })
+  })
+
+  test('chained setters round-trip through toMeta()', () => {
+    const meta = RowButton.make()
+      .label('Remove forever')
+      .icon('trash')
+      .color('destructive')
+      .tooltip('This cannot be undone')
+      .toMeta()
+    assert.deepEqual(meta, {
+      label:   'Remove forever',
+      icon:    'trash',
+      color:   'destructive',
+      tooltip: 'This cannot be undone',
+    })
+  })
+
+  test('getters reflect what was set', () => {
+    const b = RowButton.make().icon('plus-circle').color('primary')
+    assert.equal(b.getIcon(), 'plus-circle')
+    assert.equal(b.getColor(), 'primary')
+    assert.equal(b.getLabel(), undefined)
+    assert.equal(b.getTooltip(), undefined)
+  })
+})
+
+describe('RepeaterField row-action customizers', () => {
+  test('non-customized field omits meta.buttons entirely', () => {
+    const meta = Repeater.make('items')
+      .schema([TextField.make('text')])
+      .toMeta() as { buttons?: unknown }
+    assert.equal(meta.buttons, undefined)
+  })
+
+  test('addAction / cloneAction / deleteAction emit per-slot meta', () => {
+    const meta = Repeater.make('items')
+      .schema([TextField.make('text')])
+      .addAction(RowButton.make().label('Add line item').icon('plus-circle'))
+      .cloneAction(RowButton.make().tooltip('Duplicate'))
+      .deleteAction(RowButton.make().color('destructive').label('Remove'))
+      .toMeta() as unknown as { buttons?: Record<string, Record<string, unknown>> }
+    assert.deepEqual(meta.buttons, {
+      add:    { label: 'Add line item', icon: 'plus-circle' },
+      clone:  { tooltip: 'Duplicate' },
+      delete: { color: 'destructive', label: 'Remove' },
+    })
+  })
+
+  test('all seven slots map to meta keys with the documented kind names', () => {
+    const meta = Repeater.make('items')
+      .schema([TextField.make('text')])
+      .addAction(RowButton.make().label('a'))
+      .cloneAction(RowButton.make().label('c'))
+      .deleteAction(RowButton.make().label('d'))
+      .moveUpAction(RowButton.make().label('u'))
+      .moveDownAction(RowButton.make().label('w'))
+      .reorderAction(RowButton.make().label('r'))
+      .collapseAction(RowButton.make().label('x'))
+      .toMeta() as { buttons?: Record<string, { label?: string }> }
+    assert.equal(meta.buttons?.add?.label,      'a')
+    assert.equal(meta.buttons?.clone?.label,    'c')
+    assert.equal(meta.buttons?.delete?.label,   'd')
+    assert.equal(meta.buttons?.moveUp?.label,   'u')
+    assert.equal(meta.buttons?.moveDown?.label, 'w')
+    assert.equal(meta.buttons?.reorder?.label,  'r')
+    assert.equal(meta.buttons?.collapse?.label, 'x')
+  })
+
+  test('addActionLabel and addAction.label coexist (renderer picks customizer)', () => {
+    // Field meta keeps both; the renderer's `buttons.add.label ?? addActionLabel`
+    // chain decides which wins. The wire format must carry both faithfully.
+    const meta = Repeater.make('items')
+      .schema([TextField.make('text')])
+      .addActionLabel('Old label')
+      .addAction(RowButton.make().label('New label'))
+      .toMeta() as { addActionLabel?: string; buttons?: { add?: { label?: string } } }
+    assert.equal(meta.addActionLabel, 'Old label')
+    assert.equal(meta.buttons?.add?.label, 'New label')
+  })
+
+  test('getButton(kind) returns the configured customizer or undefined', () => {
+    const r = Repeater.make('items')
+      .schema([TextField.make('text')])
+      .deleteAction(RowButton.make().color('destructive'))
+    assert.notEqual(r.getButton('delete'), undefined)
+    assert.equal(r.getButton('delete')!.getColor(), 'destructive')
+    assert.equal(r.getButton('clone'), undefined)
+  })
+})
+
+describe('BuilderField row-action customizers', () => {
+  test('non-customized field omits meta.buttons entirely', () => {
+    const meta = Builder.make('blocks')
+      .blocks([Block.make('hero').schema([TextField.make('title')])])
+      .toMeta() as { buttons?: unknown }
+    assert.equal(meta.buttons, undefined)
+  })
+
+  test('all seven setters land on meta.buttons under the same kind keys', () => {
+    const meta = Builder.make('blocks')
+      .blocks([Block.make('hero').schema([TextField.make('title')])])
+      .addAction(RowButton.make().label('Add block').icon('plus-circle'))
+      .cloneAction(RowButton.make().tooltip('Clone'))
+      .deleteAction(RowButton.make().color('destructive'))
+      .moveUpAction(RowButton.make().tooltip('Up'))
+      .moveDownAction(RowButton.make().tooltip('Down'))
+      .reorderAction(RowButton.make().tooltip('Drag'))
+      .collapseAction(RowButton.make().icon('chevrons-up-down'))
+      .toMeta() as unknown as { buttons?: Record<string, Record<string, unknown>> }
+    assert.deepEqual(meta.buttons, {
+      add:      { label: 'Add block', icon: 'plus-circle' },
+      clone:    { tooltip: 'Clone' },
+      delete:   { color: 'destructive' },
+      moveUp:   { tooltip: 'Up' },
+      moveDown: { tooltip: 'Down' },
+      reorder:  { tooltip: 'Drag' },
+      collapse: { icon: 'chevrons-up-down' },
+    })
+  })
+
+  test('shares the serializer with Repeater (same wire shape)', () => {
+    const overrides = {
+      add:    RowButton.make().label('+'),
+      delete: RowButton.make().color('destructive'),
+    }
+    const r = Repeater.make('items').schema([TextField.make('text')])
+      .addAction(overrides.add)
+      .deleteAction(overrides.delete)
+      .toMeta() as { buttons?: unknown }
+    const b = Builder.make('blocks')
+      .blocks([Block.make('hero').schema([TextField.make('title')])])
+      .addAction(overrides.add)
+      .deleteAction(overrides.delete)
+      .toMeta() as { buttons?: unknown }
+    assert.deepEqual(r.buttons, b.buttons)
+  })
+})

package/src/fields/RowButton.ts

@@ -0,0 +1,125 @@
+/**
+ * Chrome customizer for the built-in per-row buttons rendered by
+ * `RepeaterField` and `BuilderField`. Mirrors Filament's
+ * `addAction / cloneAction / deleteAction / moveUpAction / moveDownAction /
+ *  reorderAction / collapseAction` ergonomic — swap the icon, label, color,
+ * or tooltip without rewriting the renderer.
+ *
+ * Intentionally NOT an `Action`. The pilotiq `Action` primitive carries
+ * dispatch modes (handler / href / submit / modal / form-field), visibility
+ * rules, and a per-row dispatch URL — none of which apply here. The
+ * built-in buttons own their behavior; the customizer is chrome only.
+ *
+ * Icons are string-only and resolved through the runtime icon registry
+ * (`registerIcons({ … })` → `getIcon(name)`), the same posture as
+ * `Block.icon()` and `Section.icon()`. Component-typed icons stay reserved
+ * for top-level Resource / Global / Page bindings that own a manifest entry.
+ *
+ * @example
+ *   Repeater.make('items')
+ *     .schema([…])
+ *     .addAction(RowButton.make().label('Add line item').icon('plus-circle'))
+ *     .deleteAction(RowButton.make().tooltip('Remove this line').color('destructive'))
+ *     .cloneAction(RowButton.make().icon('files'))
+ */
+
+export type RowButtonColor =
+  | 'foreground'
+  | 'destructive'
+  | 'primary'
+  | 'success'
+  | 'warning'
+  | 'info'
+  | 'muted'
+
+export interface RowButtonMeta {
+  label?:   string
+  icon?:    string
+  color?:   RowButtonColor
+  tooltip?: string
+}
+
+export class RowButton {
+  private _label?:   string
+  private _icon?:    string
+  private _color?:   RowButtonColor
+  private _tooltip?: string
+
+  private constructor() {}
+
+  static make(): RowButton {
+    return new RowButton()
+  }
+
+  /**
+   * Override the button's visible label. Today only the bottom Add button
+   * renders a label; icon-only row buttons (clone / delete / move /
+   * collapse / reorder grip) read this for `aria-label` so screen readers
+   * still pick up custom wording.
+   */
+  label(s: string): this { this._label = s; return this }
+
+  /**
+   * Override the button's icon. Pass a registry key — the renderer resolves
+   * via `getIcon(name)` against the runtime registry populated by
+   * `registerIcons({ … })`. Falls back to the slot's default Lucide icon
+   * when the key isn't registered.
+   */
+  icon(name: string): this { this._icon = name; return this }
+
+  /**
+   * Override the button's foreground color. Maps to a small palette of
+   * Tailwind class pairs picked at render — keeps the customizer JSON-safe
+   * and matches `Action.color()`'s tokens.
+   */
+  color(c: RowButtonColor): this { this._color = c; return this }
+
+  /**
+   * Override the hover tooltip. Defaults: `'Drag to reorder'` on the
+   * grip, `'Move up' / 'Move down'` on the arrows, `'Duplicate row'` on
+   * the clone button, `'Remove row'` on the trash, `'Expand' / 'Collapse'`
+   * on the chevron.
+   */
+  tooltip(s: string): this { this._tooltip = s; return this }
+
+  // ─── Read-only access ────────────────────────────────
+
+  getLabel():   string | undefined        { return this._label   }
+  getIcon():    string | undefined        { return this._icon    }
+  getColor():   RowButtonColor | undefined { return this._color  }
+  getTooltip(): string | undefined        { return this._tooltip }
+
+  // ─── Wire format ─────────────────────────────────────
+
+  /**
+   * Serialize to a flat JSON-safe meta. Drops keys the user never set so
+   * the renderer can `??` against its built-in defaults without clobbering
+   * them with `undefined`.
+   */
+  toMeta(): RowButtonMeta {
+    const meta: RowButtonMeta = {}
+    if (this._label   !== undefined) meta.label   = this._label
+    if (this._icon    !== undefined) meta.icon    = this._icon
+    if (this._color   !== undefined) meta.color   = this._color
+    if (this._tooltip !== undefined) meta.tooltip = this._tooltip
+    return meta
+  }
+}
+
+/**
+ * Slot id for one of the seven built-in row chrome buttons. The renderer
+ * looks these up in `meta.buttons[kind]` to merge customizer overrides
+ * onto its hardcoded defaults.
+ */
+export type RowButtonKind =
+  | 'add'
+  | 'clone'
+  | 'delete'
+  | 'moveUp'
+  | 'moveDown'
+  | 'reorder'
+  | 'collapse'
+
+export type RowButtonsMeta = {
+  [K in RowButtonKind]?: RowButtonMeta
+}