@pilotiq/pilotiq 0.10.0 → 0.11.0

package/src/react/fields/RepeaterInput.tsx

@@ -3,7 +3,7 @@ import { PlusIcon } from 'lucide-react'
 import type { ElementMeta } from '../../schema/Element.js'
 import { Button } from '../ui/button.js'
 import { SchemaRenderer, dispatchHandlerAction } from '../SchemaRenderer.js'
-import { FormIdContext, useFormState } from '../FormStateContext.js'
+import { FormIdContext, useFormState, useRowBinding } from '../FormStateContext.js'
 import { findFieldMeta } from '../formStateHelpers.js'
 import { useNavigate } from '../navigate.js'
 import { useToast } from '../Toaster.js'
@@ -236,6 +236,75 @@ export function RepeaterInput({
     if (!metaRows) return
     setRows(prev => syncRowGates(prev, metaRows))
   }, [metaRows])
+  // Phase F.5 — row-array CRDT binding. `null` outside a collab room
+  // OR when the active binding doesn't implement F.5 row methods OR when
+  // this Repeater opted out via `.collab(false)`. The four row mutations
+  // (`addRow / cloneRow / removeRow / moveRow + DnD drop`) below call into
+  // it when present so peers see the same lifecycle events; absent =
+  // today's local-only behaviour, unchanged.
+  const rowBinding = useRowBinding(name)
+  // Phase F.5c — mirror row identities into the form's values map so dotted
+  // row-leaf consumers (`useFieldState('${name}.${i}.heading').textBinding`)
+  // can resolve the row's `__id` via `rowIdAtIndex(ctx.values, name, i)`.
+  // The renderer is the only source of truth for `(index → rowId)`; without
+  // this stamp the F.5c per-row Y.Text path stays null and row text fields
+  // never sync. Setting a `__id` key routes through `routeBindingWrite` →
+  // `parseRowFieldPath` which filters `__id` → no-op on the binding side
+  // (no Y.Text writes), so the only effect is a row in `valuesState`.
+  // `formStateForIds` mirrors `formState` below; we read via `useFormState()`
+  // here too instead of forward-referencing the later binding.
+  const formStateForIds = useFormState()
+  const ctxSetValue = formStateForIds?.setValue
+  useEffect(() => {
+    if (!ctxSetValue) return
+    for (let i = 0; i < rows.length; i++) {
+      const row = rows[i]
+      if (!row) continue
+      ctxSetValue(`${name}.${i}.__id`, row.id)
+    }
+  }, [rows, name, ctxSetValue])
+  // Phase F.5 — reconcile remote row events into the local `rows` state
+  // by `__id`. Local mutations also surface here (Yjs observers fire on
+  // local transactions); we dedupe by checking whether the rowId is
+  // already present in the current state. `template` seeds new rows so
+  // remote-added rows render with the same inner schema as locally-added
+  // ones.
+  useEffect(() => {
+    if (!rowBinding) return
+    const tpl = meta.template ?? []
+    return rowBinding.subscribe((event) => {
+      if (event.kind === 'add') {
+        setRows((prev) => {
+          if (prev.some(r => r.id === event.rowId)) return prev
+          const incoming: RowState = { id: event.rowId, children: tpl }
+          const next = prev.slice()
+          const at = Math.max(0, Math.min(event.index, next.length))
+          next.splice(at, 0, incoming)
+          return next
+        })
+        return
+      }
+      if (event.kind === 'remove') {
+        setRows((prev) => {
+          if (!prev.some(r => r.id === event.rowId)) return prev
+          return prev.filter(r => r.id !== event.rowId)
+        })
+        return
+      }
+      // move — recompute the local row order by lifting the row at `from`
+      // and re-inserting at `to`. No-op when local already matches.
+      setRows((prev) => {
+        const fromIdx = prev.findIndex(r => r.id === event.rowId)
+        if (fromIdx < 0) return prev
+        if (fromIdx === event.to) return prev
+        const next  = prev.slice()
+        const [moved] = next.splice(fromIdx, 1)
+        if (!moved) return prev
+        next.splice(event.to, 0, moved)
+        return next
+      })
+    })
+  }, [rowBinding, meta.template])
   const [collapsed, setCollapsed] = useState<Record<string, boolean>>(() =>
     accordion ? {} : initSeedCollapsed(initialRows, formId, name, defaultCollapsed, collapsible),
   )
@@ -269,6 +338,7 @@ export function RepeaterInput({
       children: meta.template ?? [],
     }
     setRows(prev => [...prev, newRow])
+    rowBinding?.add(newRow.id, {})
     if (accordion) {
       // New row should be the only one open — the user just asked for it.
       setAccordionOpenId(newRow.id)
@@ -284,6 +354,7 @@ export function RepeaterInput({
   const removeRow = (id: string): void => {
     if (atMin) return
     setRows(prev => prev.filter(r => r.id !== id))
+    rowBinding?.remove(id)
     if (accordion) {
       if (accordionOpenId === id) {
         setAccordionOpenId(null)
@@ -300,12 +371,14 @@ export function RepeaterInput({
 
   const cloneRow = (id: string): void => {
     if (atMax) return
+    let cloneId: string | null = null
     setRows(prev => {
       const idx = prev.findIndex(r => r.id === id)
       if (idx < 0) return prev
       const source = prev[idx]!
+      cloneId = generateRowId()
       const clone: RowState = {
-        id:       generateRowId(),
+        id:       cloneId,
         children: source.children,
         ...(source.itemLabel !== undefined ? { itemLabel: source.itemLabel } : {}),
       }
@@ -313,26 +386,38 @@ export function RepeaterInput({
       next.splice(idx + 1, 0, clone)
       return next
     })
+    // F.5 — register the clone's stable id on the binding. Per-field
+    // clone-of-source values flow through `setRow` on the user's next
+    // edit; v1 doesn't lift the source row's values onto the clone (the
+    // binding's empty seed combined with the DOM's defaultValue-copied
+    // inputs gives the local user the right visual state).
+    if (cloneId !== null) rowBinding?.add(cloneId, {})
   }
 
   const moveRow = (id: string, dir: -1 | 1): void => {
+    let newOrder: string[] | null = null
     setRows(prev => {
       const idx = prev.findIndex(r => r.id === id)
       if (idx < 0) return prev
       // Skip past hidden neighbours so reorder operates between visible
       // rows. Hidden rows hold their absolute slot — the visible row hops
       // over them.
+      let next: RowState[]
       if (dir === -1) {
         let target = idx - 1
         while (target >= 0 && prev[target]?.hidden) target--
         if (target < 0) return prev
-        return reorderRows(prev, idx, target)
+        next = reorderRows(prev, idx, target)
+      } else {
+        let target = idx + 1
+        while (target < prev.length && prev[target]?.hidden) target++
+        if (target >= prev.length) return prev
+        next = reorderRows(prev, idx, target + 1)
       }
-      let target = idx + 1
-      while (target < prev.length && prev[target]?.hidden) target++
-      if (target >= prev.length) return prev
-      return reorderRows(prev, idx, target + 1)
+      if (next !== prev) newOrder = next.map(r => r.id)
+      return next
     })
+    if (newOrder !== null) rowBinding?.reorder(newOrder)
   }
 
   // ── DnD state ───────────────────────────────────────────
@@ -345,11 +430,15 @@ export function RepeaterInput({
   } = useRowReorderDnd({
     enabled: reorderable && !disabled,
     onDrop: (fromId, at) => {
+      let newOrder: string[] | null = null
       setRows(prev => {
         const fromIdx = prev.findIndex(r => r.id === fromId)
         if (fromIdx < 0) return prev
-        return reorderRows(prev, fromIdx, at)
+        const next = reorderRows(prev, fromIdx, at)
+        if (next !== prev) newOrder = next.map(r => r.id)
+        return next
       })
+      if (newOrder !== null) rowBinding?.reorder(newOrder)
     },
   })
 

package/src/react/formStateHelpers.test.ts

@@ -3,12 +3,19 @@ import assert from 'node:assert/strict'
 
 import {
   collectFieldDefaults,
+  collectRowArrayFieldNames,
+  collectRowTextLeavesByArray,
+  fieldOptsOutOfCollab,
   findFieldMeta,
   parseFormDataToNested,
+  parseRowFieldPath,
   readNestedValue,
+  routeBindingWrite,
+  rowIdAtIndex,
   writeNestedValue,
 } from './formStateHelpers.js'
 import type { ElementMeta } from '../schema/Element.js'
+import type { FormCollabBinding } from './FormCollabBindingRegistry.js'
 
 const field = (name: string, defaultValue?: unknown): ElementMeta => ({
   type:      'field',
@@ -293,3 +300,308 @@ describe('readNestedValue', () => {
     assert.equal(readNestedValue(root as Record<string, unknown>, 'name.length'), undefined)
   })
 })
+
+describe('parseRowFieldPath', () => {
+  it('parses Repeater row leaves (3-segment dotted)', () => {
+    assert.deepEqual(parseRowFieldPath('tags.0.label'), {
+      arrayName: 'tags', index: 0, fieldName: 'label',
+    })
+  })
+
+  it('parses Builder row leaves (4-segment with data wrapper)', () => {
+    assert.deepEqual(parseRowFieldPath('blocks.0.data.body'), {
+      arrayName: 'blocks', index: 0, fieldName: 'body',
+    })
+  })
+
+  it('rejects top-level names', () => {
+    assert.equal(parseRowFieldPath('title'), null)
+  })
+
+  it('rejects reserved row-metadata leaves (__id, type)', () => {
+    assert.equal(parseRowFieldPath('tags.0.__id'), null)
+    assert.equal(parseRowFieldPath('blocks.0.type'), null)
+  })
+
+  it('rejects non-integer indices', () => {
+    assert.equal(parseRowFieldPath('tags.NaN.label'), null)
+    assert.equal(parseRowFieldPath('tags.-1.label'), null)
+  })
+
+  it('rejects nested-Repeater paths (deferred to a future phase)', () => {
+    assert.equal(parseRowFieldPath('articles.0.comments.1.body'), null)
+  })
+
+  it('rejects 4-segment paths that lack the literal "data" wrapper', () => {
+    assert.equal(parseRowFieldPath('blocks.0.notdata.body'), null)
+  })
+})
+
+describe('rowIdAtIndex', () => {
+  it('reads the dotted __id at the given index', () => {
+    const values = { 'tags.0.__id': 'row-abc', 'tags.0.label': 'a' }
+    assert.equal(rowIdAtIndex(values, 'tags', 0), 'row-abc')
+  })
+
+  it('returns null when the row hasn\'t been stamped', () => {
+    assert.equal(rowIdAtIndex({}, 'tags', 0), null)
+  })
+
+  it('returns null when __id is not a non-empty string', () => {
+    assert.equal(rowIdAtIndex({ 'tags.0.__id': '' }, 'tags', 0), null)
+    assert.equal(rowIdAtIndex({ 'tags.0.__id': 123 }, 'tags', 0), null)
+  })
+})
+
+describe('collectRowArrayFieldNames', () => {
+  const arrayField = (name: string, fieldType: 'repeater' | 'builder', collab?: boolean): ElementMeta => ({
+    type:      'field',
+    fieldType,
+    name,
+    label:     name,
+    required:  false,
+    disabled:  false,
+    ...(collab === false ? { collab: false } : {}),
+  } as ElementMeta)
+
+  it('returns top-level Repeater and Builder field names', () => {
+    const meta = formMeta([
+      field('title'),
+      arrayField('tags',   'repeater'),
+      arrayField('blocks', 'builder'),
+    ])
+    assert.deepEqual(collectRowArrayFieldNames(meta), ['tags', 'blocks'])
+  })
+
+  it('walks into layout containers', () => {
+    const meta = formMeta([
+      {
+        type:     'section',
+        children: [arrayField('tags', 'repeater')],
+      } as ElementMeta,
+    ])
+    assert.deepEqual(collectRowArrayFieldNames(meta), ['tags'])
+  })
+
+  it('skips fields opted out via .collab(false)', () => {
+    const meta = formMeta([
+      arrayField('private', 'repeater', false),
+      arrayField('shared',  'repeater'),
+    ])
+    assert.deepEqual(collectRowArrayFieldNames(meta), ['shared'])
+  })
+
+  it('does not descend into inner row schemas', () => {
+    const meta = formMeta([
+      {
+        ...arrayField('outer', 'repeater'),
+        children: [arrayField('inner', 'repeater')],
+      } as ElementMeta,
+    ])
+    assert.deepEqual(collectRowArrayFieldNames(meta), ['outer'])
+  })
+})
+
+describe('routeBindingWrite', () => {
+  interface RecordedCall {
+    kind: 'set' | 'setRow' | 'addRow' | 'removeRow' | 'reorderRows'
+    args: unknown[]
+  }
+
+  function stub(opts: { withSetRow?: boolean } = {}): { binding: FormCollabBinding; calls: RecordedCall[] } {
+    const calls: RecordedCall[] = []
+    const binding: FormCollabBinding = {
+      get:       () => ({}),
+      set:       (...args) => { calls.push({ kind: 'set',    args }) },
+      subscribe: () => () => {},
+      destroy:   () => {},
+      ...(opts.withSetRow ? {
+        setRow: (...args: unknown[]) => { calls.push({ kind: 'setRow', args }) },
+      } : {}),
+    } as FormCollabBinding
+    return { binding, calls }
+  }
+
+  const formMetaWithRepeater = formMeta([
+    field('title'),
+    {
+      type:      'field',
+      fieldType: 'repeater',
+      name:      'tags',
+    } as ElementMeta,
+  ])
+
+  it('routes top-level names through binding.set', () => {
+    const { binding, calls } = stub()
+    routeBindingWrite(binding, formMetaWithRepeater, {}, 'title', 'Hello')
+    assert.deepEqual(calls, [{ kind: 'set', args: ['title', 'Hello'] }])
+  })
+
+  it('routes row leaves through binding.setRow when implemented', () => {
+    const { binding, calls } = stub({ withSetRow: true })
+    const values = { 'tags.0.__id': 'row-a' }
+    routeBindingWrite(binding, formMetaWithRepeater, values, 'tags.0.label', 'Hi')
+    assert.deepEqual(calls, [{ kind: 'setRow', args: ['tags', 'row-a', 'label', 'Hi'] }])
+  })
+
+  it('drops row-leaf writes when the binding lacks setRow (pre-F.5)', () => {
+    const { binding, calls } = stub()
+    const values = { 'tags.0.__id': 'row-a' }
+    routeBindingWrite(binding, formMetaWithRepeater, values, 'tags.0.label', 'Hi')
+    assert.deepEqual(calls, [])
+  })
+
+  it('drops row-leaf writes when the row hasn\'t been stamped with __id yet', () => {
+    const { binding, calls } = stub({ withSetRow: true })
+    routeBindingWrite(binding, formMetaWithRepeater, {}, 'tags.0.label', 'Hi')
+    assert.deepEqual(calls, [])
+  })
+
+  it('skips fields opted out via .collab(false)', () => {
+    const optedOut = formMeta([
+      { ...field('private'), collab: false } as ElementMeta,
+    ])
+    const { binding, calls } = stub()
+    routeBindingWrite(binding, optedOut, {}, 'private', 'sensitive')
+    assert.deepEqual(calls, [])
+  })
+
+  it('is a no-op when no binding is registered', () => {
+    // No throw, no work — same posture as the v1 binding-absent path.
+    assert.doesNotThrow(() => routeBindingWrite(null, formMetaWithRepeater, {}, 'title', 'x'))
+  })
+
+  it('does NOT call setRow for nested-Repeater paths (out of scope v1)', () => {
+    const { binding, calls } = stub({ withSetRow: true })
+    const values = {
+      'articles.0.__id':      'a-1',
+      'articles.0.comments.0.__id':  'c-1',
+    }
+    routeBindingWrite(binding, formMetaWithRepeater, values, 'articles.0.comments.0.body', 'oops')
+    assert.deepEqual(calls, [])
+  })
+
+  it('handles Builder row leaves through the data wrapper', () => {
+    const builderMeta = formMeta([
+      { type: 'field', fieldType: 'builder', name: 'blocks' } as ElementMeta,
+    ])
+    const { binding, calls } = stub({ withSetRow: true })
+    const values = { 'blocks.0.__id': 'blk-1' }
+    routeBindingWrite(binding, builderMeta, values, 'blocks.0.data.body', 'Lorem')
+    assert.deepEqual(calls, [{ kind: 'setRow', args: ['blocks', 'blk-1', 'body', 'Lorem'] }])
+  })
+})
+
+describe('collectRowTextLeavesByArray', () => {
+  const textField = (name: string, fieldType: string = 'text', collab?: boolean): ElementMeta => ({
+    type:      'field',
+    fieldType,
+    name,
+    label:     name,
+    required:  false,
+    disabled:  false,
+    ...(collab === false ? { collab: false } : {}),
+  } as ElementMeta)
+
+  // Repeater meta carries the row schema under `template` (`children` is
+  // the per-resolved-row child list, not the field-level template). Tests
+  // must mirror what `RepeaterField.toMeta()` actually emits.
+  const repeater = (name: string, template: ElementMeta[], collab?: boolean): ElementMeta => ({
+    type:      'field',
+    fieldType: 'repeater',
+    name,
+    label:     name,
+    required:  false,
+    disabled:  false,
+    template,
+    ...(collab === false ? { collab: false } : {}),
+  } as ElementMeta)
+
+  it('collects text-shaped inner-field names per Repeater', () => {
+    const meta = formMeta([
+      repeater('tags', [
+        textField('label', 'text'),
+        textField('summary', 'textarea'),
+        textField('count', 'number'),
+      ]),
+    ])
+    const out = collectRowTextLeavesByArray(meta)
+    assert.equal(out.size, 1)
+    assert.deepEqual([...out.get('tags')!].sort(), ['label', 'summary'])
+  })
+
+  it('walks Builder block templates', () => {
+    const meta = formMeta([
+      {
+        type:      'field',
+        fieldType: 'builder',
+        name:      'blocks',
+        children:  [],
+        blocks: [
+          { name: 'heading',   template: [textField('text', 'text')] },
+          { name: 'paragraph', template: [textField('body', 'markdown')] },
+        ],
+      } as unknown as ElementMeta,
+    ])
+    const out = collectRowTextLeavesByArray(meta)
+    assert.deepEqual([...out.get('blocks')!].sort(), ['body', 'text'])
+  })
+
+  it('skips opted-out inner fields', () => {
+    const meta = formMeta([
+      repeater('tags', [
+        textField('label',  'text'),
+        textField('private', 'text', false),   // .collab(false)
+      ]),
+    ])
+    const out = collectRowTextLeavesByArray(meta)
+    assert.deepEqual([...out.get('tags')!], ['label'])
+  })
+
+  it('omits opted-out top-level arrays', () => {
+    const meta = formMeta([
+      repeater('public',  [textField('a', 'text')]),
+      repeater('private', [textField('b', 'text')], false),
+    ])
+    const out = collectRowTextLeavesByArray(meta)
+    assert.equal(out.has('public'),  true)
+    assert.equal(out.has('private'), false)
+  })
+
+  it('stops at nested array boundaries (no 5+ segment dotted paths)', () => {
+    const meta = formMeta([
+      repeater('outer', [
+        textField('outerLabel', 'text'),
+        repeater('inner', [textField('innerLabel', 'text')]),
+      ]),
+    ])
+    const out = collectRowTextLeavesByArray(meta)
+    assert.deepEqual([...out.get('outer')!], ['outerLabel'])
+    assert.equal(out.has('inner'), false, 'nested Repeater not surfaced as a top-level array')
+  })
+
+  it('returns empty map when no Repeater/Builder has text leaves', () => {
+    const meta = formMeta([
+      textField('top', 'text'),
+      repeater('numbers', [textField('count', 'number')]),
+    ])
+    const out = collectRowTextLeavesByArray(meta)
+    assert.equal(out.size, 0)
+  })
+})
+
+describe('fieldOptsOutOfCollab', () => {
+  it('returns true only when the field carries an explicit collab=false', () => {
+    const meta = formMeta([
+      { ...field('shared') } as ElementMeta,
+      { ...field('hidden'), collab: false } as ElementMeta,
+    ])
+    assert.equal(fieldOptsOutOfCollab(meta, 'shared'), false)
+    assert.equal(fieldOptsOutOfCollab(meta, 'hidden'), true)
+  })
+
+  it('returns false when the field is absent', () => {
+    const meta = formMeta([field('present')])
+    assert.equal(fieldOptsOutOfCollab(meta, 'ghost'), false)
+  })
+})