@pilotiq/pilotiq 0.13.0 → 0.14.0

package/src/react/fields/repeaterReconcile.test.ts

@@ -0,0 +1,114 @@
+import { describe, it, before, after, beforeEach } from 'node:test'
+import assert from 'node:assert/strict'
+
+import {
+  computeReconcilePlan,
+  markSubmitForReconcile,
+  consumeReconcileFlag,
+} from './repeaterReconcile.js'
+
+describe('computeReconcilePlan', () => {
+  it('returns empty plan when current and authoritative match', () => {
+    const plan = computeReconcilePlan({
+      current:       ['a', 'b', 'c'],
+      authoritative: ['a', 'b', 'c'],
+    })
+    assert.deepEqual(plan.toRemove, [])
+    assert.deepEqual(plan.toAdd,    [])
+  })
+
+  it('flags orphan CRDT rows as toRemove (PK-switch happy path)', () => {
+    // Submitting tab reloaded — server returned the new DB PK; CRDT
+    // still carries the renderer-minted UUID from the just-saved row.
+    const plan = computeReconcilePlan({
+      current:       ['uuid-foo', '42'],
+      authoritative: ['42'],
+    })
+    assert.deepEqual(plan.toRemove, ['uuid-foo'])
+    assert.deepEqual(plan.toAdd,    [])
+  })
+
+  it('flags missing CRDT rows as toAdd (raw-SQL-seeded record)', () => {
+    // First peer to open a record whose DB rows weren't seeded into the
+    // Y.Doc (no `seedRowArraysFromRecord` coverage for relationship-
+    // backed fields). Reconciler ensures CRDT mirrors initialRows.
+    const plan = computeReconcilePlan({
+      current:       [],
+      authoritative: ['42', '43'],
+    })
+    assert.deepEqual(plan.toRemove, [])
+    assert.deepEqual(plan.toAdd,    ['42', '43'])
+  })
+
+  it('handles both directions in a single pass', () => {
+    const plan = computeReconcilePlan({
+      current:       ['uuid-foo', 'uuid-bar', '42'],
+      authoritative: ['42', '43'],
+    })
+    assert.deepEqual(plan.toRemove, ['uuid-foo', 'uuid-bar'])
+    assert.deepEqual(plan.toAdd,    ['43'])
+  })
+
+  it('preserves order from inputs in toRemove / toAdd', () => {
+    const plan = computeReconcilePlan({
+      current:       ['z', 'a', 'm'],
+      authoritative: ['a', 'b', 'c'],
+    })
+    // toRemove walks current in order; toAdd walks authoritative in order.
+    // Order-stability matters because reconciler applies them sequentially
+    // and we want deterministic test snapshots.
+    assert.deepEqual(plan.toRemove, ['z', 'm'])
+    assert.deepEqual(plan.toAdd,    ['b', 'c'])
+  })
+})
+
+describe('markSubmitForReconcile / consumeReconcileFlag', () => {
+  // Minimal in-memory sessionStorage stub — Node lacks one, and we
+  // want to avoid bringing in jsdom for a flag-roundtrip test.
+  const realSessionStorage = (globalThis as { sessionStorage?: Storage }).sessionStorage
+  const store: Map<string, string> = new Map()
+
+  before(() => {
+    ;(globalThis as { sessionStorage?: Storage }).sessionStorage = {
+      get length() { return store.size },
+      key:        (i: number) => Array.from(store.keys())[i] ?? null,
+      getItem:    (k: string) => store.has(k) ? store.get(k)! : null,
+      setItem:    (k: string, v: string) => { store.set(k, v) },
+      removeItem: (k: string) => { store.delete(k) },
+      clear:      () => { store.clear() },
+    } as Storage
+  })
+
+  after(() => {
+    if (realSessionStorage === undefined) {
+      delete (globalThis as { sessionStorage?: Storage }).sessionStorage
+    } else {
+      (globalThis as { sessionStorage?: Storage }).sessionStorage = realSessionStorage
+    }
+  })
+
+  beforeEach(() => { store.clear() })
+
+  it('returns false when no flag has been set', () => {
+    assert.equal(consumeReconcileFlag('form-1'), false)
+  })
+
+  it('round-trips a flag and clears on first consume', () => {
+    markSubmitForReconcile('form-1')
+    assert.equal(consumeReconcileFlag('form-1'), true)
+    // Second read: flag was cleared on the first consume.
+    assert.equal(consumeReconcileFlag('form-1'), false)
+  })
+
+  it('scopes the flag per formId', () => {
+    markSubmitForReconcile('form-1')
+    assert.equal(consumeReconcileFlag('form-2'), false)
+    assert.equal(consumeReconcileFlag('form-1'), true)
+  })
+
+  it('no-ops on empty formId (mark and consume both)', () => {
+    markSubmitForReconcile('')
+    assert.equal(store.size, 0)
+    assert.equal(consumeReconcileFlag(''), false)
+  })
+})

package/src/react/fields/repeaterReconcile.ts

@@ -0,0 +1,104 @@
+/**
+ * Phase A of the `Repeater.relationship` PK-switch reconciliation
+ * (see `pilotiq-pro/docs/plans/repeater-relationship-pk-switch.md`).
+ *
+ * When a parent form submit creates new relationship-backed rows, the
+ * server assigns each child a DB primary key — but the row's `__id` in
+ * the row CRDT is still the renderer-minted UUID from the local session.
+ * After redirect, the submitting tab's pageData carries `__id = String(pk)`
+ * while CRDT still has the UUID, so the renderer ends up showing the
+ * same row twice (DB PK from initialRows + orphan UUID from CRDT).
+ *
+ * Phase A fix: the submitting tab marks itself for a one-shot CRDT
+ * reconcile on the next mount via a per-formId sessionStorage flag.
+ * `RepeaterInput` / `BuilderInput` read the flag on mount and, when set,
+ * snapshot the row CRDT after a short settle (waiting for WS sync) and
+ * reconcile against `initialRows` — removing orphan CRDT rows not in
+ * the form's authoritative data, and adding missing CRDT rows (rare,
+ * happens when the row was DB-seeded outside the collab session).
+ *
+ * The flag is scoped per-tab via sessionStorage, so other peers' tabs
+ * never run the reconciler — preserving their in-flight edits.
+ *
+ * Phase B (server-side rename via the @rudderjs/sync Y.Doc seam) will
+ * extend this to other peers without requiring them to reload.
+ */
+
+const STORAGE_PREFIX = 'pilotiq.repeaterReconcile.'
+
+function storageKey(formId: string): string {
+  return STORAGE_PREFIX + formId
+}
+
+/**
+ * Called by `FormRenderer` on submit success. Records that this tab
+ * has just persisted the form, so the next mount of any Repeater /
+ * Builder under the same form runs the PK-switch reconciler. No-op
+ * when `formId` is empty or `sessionStorage` is unavailable (SSR).
+ */
+export function markSubmitForReconcile(formId: string): void {
+  if (!formId) return
+  if (typeof sessionStorage === 'undefined') return
+  try {
+    sessionStorage.setItem(storageKey(formId), '1')
+  } catch {
+    // Quota exceeded / disabled — silently skip. Reconciliation is
+    // an optimization, not a correctness requirement.
+  }
+}
+
+/**
+ * Called by `RepeaterInput` / `BuilderInput` on mount. Returns `true`
+ * iff the form was just submitted in this tab AND clears the flag so
+ * subsequent mounts no-op. Idempotent across multiple Repeater/Builder
+ * fields on the same form — the FIRST reader clears the flag, so
+ * siblings see `false`. To avoid that, both fields call this helper at
+ * the same mount tick — for v1 we accept the limitation: only the first
+ * Repeater on the form runs the reconciler; siblings don't.
+ *
+ * If a future need surfaces (multiple relationship-backed Repeaters on
+ * the same form), switch to a per-field flag keyed by `formId.fieldName`
+ * or have the FormRenderer dispatch a custom event instead.
+ */
+export function consumeReconcileFlag(formId: string): boolean {
+  if (!formId) return false
+  if (typeof sessionStorage === 'undefined') return false
+  try {
+    const v = sessionStorage.getItem(storageKey(formId))
+    if (v !== '1') return false
+    sessionStorage.removeItem(storageKey(formId))
+    return true
+  } catch {
+    return false
+  }
+}
+
+export interface ReconcileInputs {
+  /** Current CRDT row id order (post-WS-sync). */
+  current:        readonly string[]
+  /** Authoritative row id list from server-rendered initialRows. */
+  authoritative:  readonly string[]
+}
+
+export interface ReconcilePlan {
+  /** Row ids present in CRDT but not in initialRows — orphan UUIDs. */
+  toRemove: string[]
+  /** Row ids present in initialRows but not in CRDT — DB rows not yet
+   *  in the room (rare; only happens when DB was seeded outside collab). */
+  toAdd:    string[]
+}
+
+/**
+ * Pure helper: compute the symmetric difference. Exported separately so
+ * unit tests don't need a DOM / sessionStorage shim to verify the
+ * reconciliation arithmetic.
+ */
+export function computeReconcilePlan({ current, authoritative }: ReconcileInputs): ReconcilePlan {
+  const currentSet = new Set(current)
+  const authSet    = new Set(authoritative)
+  const toRemove: string[] = []
+  const toAdd:    string[] = []
+  for (const id of current)       if (!authSet.has(id))    toRemove.push(id)
+  for (const id of authoritative) if (!currentSet.has(id)) toAdd.push(id)
+  return { toRemove, toAdd }
+}

package/src/react/index.ts

@@ -78,6 +78,16 @@ export {
   RecordWrapperGate,
   type RecordWrapperGateProps,
 } from './RecordWrapperGate.js'
+export {
+  registerCustomPageWrapper,
+  getCustomPageWrapper,
+  type CustomPageWrapperProps,
+} from './CustomPageWrapperRegistry.js'
+export {
+  CustomPageWrapperGate,
+  type CustomPageWrapperGateProps,
+  type PageCollabMap,
+} from './CustomPageWrapperGate.js'
 export {
   parseRecordPageUrl,
   parseRecordEditUrl,

package/src/react/schemaRenderer/form/FormRenderer.tsx

@@ -6,6 +6,7 @@ import { useCollabRoom } from '../../CollabRoomContext.js'
 import { getFormCollabBinding } from '../../FormCollabBindingRegistry.js'
 import { useNavigate } from '../../navigate.js'
 import { useToast } from '../../Toaster.js'
+import { markSubmitForReconcile } from '../../fields/repeaterReconcile.js'
 import { renderField } from './renderField.js'
 
 // ─── Form ───────────────────────────────────────────────────
@@ -111,6 +112,15 @@ export function FormRenderer({
       }
 
       // Success — drain notifications and SPA-navigate to the redirect.
+      //
+      // Before navigating, mark this tab for the relationship-backed
+      // Repeater/Builder PK-switch reconciler. The next mount of any
+      // child Repeater/Builder under this formId will run a one-shot
+      // CRDT reconcile to drop orphan UUIDs whose rows just persisted
+      // under a fresh DB PK. See
+      // `pilotiq-pro/docs/plans/repeater-relationship-pk-switch.md`
+      // (Phase A).
+      markSubmitForReconcile(formId)
       const notifs = (data as { notifications?: NotificationMeta[] }).notifications
       if (notifs && notifs.length > 0) for (const n of notifs) notify(n)
       const redirect = String((data as { redirect?: string }).redirect ?? '')