@pilotiq/pilotiq 0.13.0 → 0.14.0

package/src/pageData.test.ts

@@ -83,6 +83,73 @@ describe('applyFillPipeline', () => {
     const values = await applyFillPipeline(form, { id: 1 })
     assert.deepEqual(values, { id: 1, async: true })
   })
+
+  it('parses JSON-string values on Repeater slots into arrays', async () => {
+    const form = Form.make().schema([
+      TextField.make('title'),
+      Repeater.make('metadata').schema([TextField.make('heading')]),
+    ])
+    const record = {
+      id: 1,
+      title: 'Hello',
+      metadata: '[{"__id":"row-1","heading":"a"},{"__id":"row-2","heading":"b"}]',
+    }
+    const values = await applyFillPipeline(form, record)
+    assert.deepEqual(values['metadata'], [
+      { __id: 'row-1', heading: 'a' },
+      { __id: 'row-2', heading: 'b' },
+    ])
+    assert.equal(values['title'], 'Hello')
+  })
+
+  it('parses JSON-string values on Builder slots into arrays', async () => {
+    const form = Form.make().schema([
+      Builder.make('content').blocks([
+        Block.make('heading').schema([TextField.make('text')]),
+      ]),
+    ])
+    const record = {
+      content: '[{"__id":"row-1","type":"heading","data":{"text":"hi"}}]',
+    }
+    const values = await applyFillPipeline(form, record)
+    assert.deepEqual(values['content'], [
+      { __id: 'row-1', type: 'heading', data: { text: 'hi' } },
+    ])
+  })
+
+  it('leaves non-JSON strings on array-field slots untouched', async () => {
+    const form = Form.make().schema([
+      Repeater.make('tags').schema([TextField.make('label')]),
+    ])
+    const record = { tags: 'not-json' }
+    const values = await applyFillPipeline(form, record)
+    assert.equal(values['tags'], 'not-json')
+  })
+
+  it('leaves JSON strings that deserialize to non-arrays untouched', async () => {
+    const form = Form.make().schema([
+      Repeater.make('tags').schema([TextField.make('label')]),
+    ])
+    const record = { tags: '{"not":"an-array"}' }
+    const values = await applyFillPipeline(form, record)
+    assert.equal(values['tags'], '{"not":"an-array"}')
+  })
+
+  it('passes through already-parsed arrays unchanged', async () => {
+    const form = Form.make().schema([
+      Repeater.make('metadata').schema([TextField.make('heading')]),
+    ])
+    const rows = [{ __id: 'row-1', heading: 'a' }]
+    const values = await applyFillPipeline(form, { metadata: rows })
+    assert.equal(values['metadata'], rows)
+  })
+
+  it('ignores top-level non-array fields whose value happens to be a JSON-string', async () => {
+    const form = Form.make().schema([TextField.make('title')])
+    const record = { title: '[1,2,3]' }
+    const values = await applyFillPipeline(form, record)
+    assert.equal(values['title'], '[1,2,3]')
+  })
 })
 
 describe('resolveActiveTab', () => {
@@ -1339,3 +1406,45 @@ describe('panelInfo — recordCollab map (resource collab opt-in)', () => {
     })
   })
 })
+
+describe('panelInfo — pageCollab map (custom-page collab opt-in)', () => {
+  it('absent when no page opts in', async () => {
+    class Analytics extends Page {
+      static override slug  = 'analytics'
+      static override label = 'Analytics'
+    }
+    const info = await panelInfo(Pilotiq.make('T').path('/admin').pages([Analytics]))
+    assert.equal((info as { pageCollab?: unknown }).pageCollab, undefined)
+  })
+
+  it('emits an entry per opted-in custom page keyed by URL slug', async () => {
+    class Settings extends Page {
+      static override slug   = 'settings'
+      static override label  = 'Settings'
+      static override collab = { room: 'settings-general' }
+    }
+    class Analytics extends Page {
+      static override slug  = 'analytics'
+      static override label = 'Analytics'
+      // No collab — should NOT appear in the map.
+    }
+    const info = await panelInfo(Pilotiq.make('T').path('/admin').pages([Settings, Analytics]))
+    const map = (info as { pageCollab?: Record<string, unknown> }).pageCollab
+    assert.deepEqual(map, {
+      settings: { room: 'settings-general', presence: true },
+    })
+  })
+
+  it('object form can suppress presence', async () => {
+    class Settings extends Page {
+      static override slug   = 'settings'
+      static override label  = 'Settings'
+      static override collab = { room: 'settings', presence: false }
+    }
+    const info = await panelInfo(Pilotiq.make('T').path('/admin').pages([Settings]))
+    const map = (info as { pageCollab?: Record<string, unknown> }).pageCollab
+    assert.deepEqual(map, {
+      settings: { room: 'settings', presence: false },
+    })
+  })
+})

package/src/pageData.ts

@@ -27,6 +27,7 @@ export {
   applyRelationshipBuilderFill,
   applyRelationshipRepeaterFill,
   callPageSchema,
+  normalizeArrayFieldStrings,
   resolveServerDataElements,
   tagActionDispatch,
   tagCellEditUrls,

package/src/react/AppShell.tsx

@@ -11,6 +11,7 @@ import { RightPanelRegistryProvider } from './right-panel-registry.js'
 import { RightSidebarProvider, useRightSidebarOptional } from './RightSidebarContext.js'
 import { RightSidebar } from './RightSidebar.js'
 import { RecordWrapperGate, type RecordCollabMap } from './RecordWrapperGate.js'
+import { CustomPageWrapperGate, type PageCollabMap } from './CustomPageWrapperGate.js'
 import { useIsMobile } from './hooks/use-mobile.js'
 import type { NavItem, UserMenuMeta, DatabaseNotificationsMeta, RightSidebarMeta } from '../pageData.js'
 import type { RenderHookMap } from '../RenderHook.js'
@@ -39,6 +40,10 @@ export interface AppShellProps {
      *  decide whether to mount the plugin-registered RecordWrapper on
      *  a record edit/view URL. Absent when no resource opted in. */
     recordCollab?: RecordCollabMap
+    /** Per-custom-page collab opt-in map — read by `CustomPageWrapperGate`
+     *  to decide whether to mount the plugin-registered CustomPageWrapper
+     *  on a custom-page URL. Absent when no page opted in. */
+    pageCollab?: PageCollabMap
     /** Pre-resolved render-hook slots for the panel chrome (body /
      *  topbar / sidebar / user-menu / footer / head). Sparse map —
      *  slots with no registered entries are absent. Built by
@@ -137,7 +142,13 @@ export function AppShell({ layout = 'sidebar', notifications, componentRegistry,
         {...(props.currentPath !== undefined ? { currentPath: props.currentPath } : {})}
         {...(props.panel.recordCollab !== undefined ? { recordCollab: props.panel.recordCollab } : {})}
       >
-        {props.children}
+        <CustomPageWrapperGate
+          basePath={props.basePath}
+          {...(props.currentPath !== undefined ? { currentPath: props.currentPath } : {})}
+          {...(props.panel.pageCollab !== undefined ? { pageCollab: props.panel.pageCollab } : {})}
+        >
+          {props.children}
+        </CustomPageWrapperGate>
       </RecordWrapperGate>
     ),
   }

package/src/react/CustomPageWrapperGate.tsx

@@ -0,0 +1,69 @@
+import { type ReactNode } from 'react'
+import { getCustomPageWrapper } from './CustomPageWrapperRegistry.js'
+import type { PageCollabConfig } from '../Page.js'
+
+/** Per-custom-page collab opt-in keyed by URL slug (`P.getSlug()` for
+ * non-clustered, `${cluster.slug}/${P.getSlug()}` for clustered). Built
+ * server-side by `panelInfo()` as `pageCollab`. */
+export type PageCollabMap = Record<string, PageCollabConfig>
+
+export interface CustomPageWrapperGateProps {
+  currentPath?: string
+  basePath:     string
+  /** Per-page opt-in map. Absent means no custom page opted in — gate
+   *  always passes through. */
+  pageCollab?: PageCollabMap
+  children:    ReactNode
+}
+
+/**
+ * Strip `basePath` from `currentPath` and return the remaining slash-
+ * joined tail. Returns `null` when the path is empty / doesn't start
+ * with `basePath` / has no tail. Mirrors `parseRecordPageUrl`'s
+ * normalization (trailing slash on either side is tolerated).
+ */
+function pageSlugFromUrl(currentPath: string, basePath: string): string | null {
+  if (!currentPath) return null
+  const trimmedPath = currentPath.replace(/\/+$/, '')
+  const trimmedBase = basePath.replace(/\/+$/, '')
+
+  if (trimmedBase !== '' && !trimmedPath.startsWith(trimmedBase)) return null
+
+  const tail = trimmedPath.slice(trimmedBase.length).replace(/^\/+/, '')
+  if (tail.length === 0) return null
+  return tail
+}
+
+/**
+ * Conditionally wraps the page tree with the plugin-registered
+ * `CustomPageWrapper` when the current URL resolves to a custom page
+ * (a `Page` subclass with `static collab = { room: '…' }`).
+ * Pass-through in every other case:
+ *
+ *   - no plugin registered a wrapper (`getCustomPageWrapper() === null`)
+ *   - `currentPath` not yet known on the very first SSR render
+ *   - `pageCollab` map absent (no page opted in)
+ *   - the URL tail doesn't match any registered page slug (resource
+ *     list/edit/view pages, dashboard, theme editor, etc.)
+ *
+ * Mounted inside `AppShell` around the page content area, beside
+ * `RecordWrapperGate`. The two gates are mutually exclusive in
+ * practice — record routes have 3+ segments ending in /edit or /view,
+ * custom-page routes are 1-2 segments matching a registered page slug.
+ */
+export function CustomPageWrapperGate({ currentPath, basePath, pageCollab, children }: CustomPageWrapperGateProps) {
+  const Wrapper = getCustomPageWrapper()
+  if (!Wrapper || !currentPath || !pageCollab) return <>{children}</>
+
+  const slug = pageSlugFromUrl(currentPath, basePath)
+  if (!slug) return <>{children}</>
+
+  const cfg = pageCollab[slug]
+  if (!cfg) return <>{children}</>
+
+  return (
+    <Wrapper pageSlug={slug} room={cfg.room} presence={cfg.presence}>
+      {children}
+    </Wrapper>
+  )
+}

package/src/react/CustomPageWrapperRegistry.ts

@@ -0,0 +1,45 @@
+import type { ComponentType, ReactNode } from 'react'
+
+/**
+ * Props the custom-page wrapper receives from `CustomPageWrapperGate`
+ * when the current URL resolves to an opted-in custom page (a `Page`
+ * subclass with `static collab = { room: '…' }`).
+ *
+ * The wrapper owns whatever page-scoped context the plugin provides —
+ * `@pilotiq-pro/collab` mounts a collab room here so every collab
+ * field inside the page tree shares one Y.Doc + WS connection. Other
+ * plugins could mount per-page presence, audit logging, etc.
+ *
+ * `pageSlug` is the gate's URL slug (cluster-prefixed for clustered
+ * pages). `room` is the literal `room` value the page declared on
+ * `static collab` — opaque to pilotiq; the plugin is free to namespace
+ * it internally before opening the WS.
+ */
+export interface CustomPageWrapperProps {
+  pageSlug: string
+  room:     string
+  presence: boolean
+  children: ReactNode
+}
+
+let _component: ComponentType<CustomPageWrapperProps> | null = null
+
+/**
+ * Register a component that wraps the page tree on every opted-in
+ * custom-page route. Called once at boot by a plugin (e.g.
+ * `@pilotiq-pro/collab`). No-op when no plugin registers —
+ * `CustomPageWrapperGate` passes through unchanged.
+ */
+export function registerCustomPageWrapper(C: ComponentType<CustomPageWrapperProps>): void {
+  _component = C
+}
+
+/** Returns the registered wrapper component, or `null`. */
+export function getCustomPageWrapper(): ComponentType<CustomPageWrapperProps> | null {
+  return _component
+}
+
+/** Test-only — drops any registered wrapper so tests stay isolated. */
+export function _resetCustomPageWrapper(): void {
+  _component = null
+}

package/src/react/FormCollabBindingRegistry.ts

@@ -101,6 +101,18 @@ export interface FormCollabBinding {
    * renderer's optimistic update converge).
    */
   subscribeRows?(arrayName: string, fn: (event: RowsEvent) => void): () => void
+
+  /**
+   * Snapshot the current row id order for an array. Unlike `subscribeRows`,
+   * which only fires on delta events, this returns whatever is in the CRDT
+   * right now — used by the renderer's mount-time reconciler to detect
+   * orphaned rows (CRDT carries a UUID forward after the parent save
+   * switched the row's `__id` to a DB PK; see
+   * `docs/plans/repeater-relationship-pk-switch.md` Phase A).
+   *
+   * Empty array when the binding has no state for `arrayName` yet.
+   */
+  getRowOrder?(arrayName: string): string[]
 }
 
 /**
@@ -134,6 +146,11 @@ export interface RowBindingApi {
    *  rowId presence in its current state. Optional on the underlying
    *  contract — `null` when the binding lacks `subscribeRows`. */
   subscribe(fn: (event: RowsEvent) => void): () => void
+  /** Snapshot the array's current row id order. Empty array when the
+   *  binding has no state yet OR when the underlying binding doesn't
+   *  implement `getRowOrder` (in which case mount-time reconciliation
+   *  no-ops). */
+  current(): string[]
 }
 
 /**

package/src/react/FormStateContext.tsx

@@ -265,7 +265,7 @@ export function FormStateProvider({
     // binding that has addRow but not reorderRows) skip the stash — the
     // contract says all three or nothing.
     if (binding.addRow && binding.removeRow && binding.reorderRows) {
-      const { addRow, removeRow, reorderRows, subscribeRows } = binding
+      const { addRow, removeRow, reorderRows, subscribeRows, getRowOrder } = binding
       const arrayNames = collectRowArrayFieldNames(formMetaRef.current)
       if (arrayNames.length > 0) {
         const rowStash = new Map<string, RowBindingApi>()
@@ -281,6 +281,13 @@ export function FormStateProvider({
             subscribe: subscribeRows
               ? (fn) => subscribeRows.call(binding, arrayName, fn)
               : () => () => {},
+            // `getRowOrder` is optional — bindings that ship row CRUD
+            // without a snapshot read (test stubs, older plugins) get a
+            // `[]` substitute. The renderer's reconciler treats empty as
+            // "no orphans known" and no-ops, which is the safest fallback.
+            current: getRowOrder
+              ? () => getRowOrder.call(binding, arrayName)
+              : () => [],
           })
         }
         setRowBindings(rowStash)

package/src/react/fields/BuilderInput.tsx

@@ -9,6 +9,7 @@ import { RowCoordsContext } from '../RowCoordsContext.js'
 import { useIconFor } from '../icon-context.js'
 import { reorderRows, ExtraActionStrip, buildGridContainer } from './RepeaterInput.js'
 import { syncRowGates } from './syncRowGates.js'
+import { consumeReconcileFlag, computeReconcilePlan } from './repeaterReconcile.js'
 import type { RowButtonsMeta } from '../../fields/RowButton.js'
 import {
   RowChromeIconButton,
@@ -252,6 +253,31 @@ export function BuilderInput({
       })
     })
   }, [rowBinding, blocksByName, meta.blocks])
+
+  // Phase A reconciliation for `Builder.relationship` PK-switch — mirrors
+  // the effect in `RepeaterInput`. See its comment + the plan doc:
+  // `pilotiq-pro/docs/plans/repeater-relationship-pk-switch.md`.
+  useEffect(() => {
+    if (!rowBinding) return
+    if (!consumeReconcileFlag(formId)) return
+    const timer = setTimeout(() => {
+      const plan = computeReconcilePlan({
+        current:       rowBinding.current(),
+        authoritative: initialRows.map(r => r.id),
+      })
+      for (const id of plan.toRemove) rowBinding.remove(id)
+      // For Builder, the row carries a block `type` discriminator; seed
+      // it on the add path so peers' picker dropdowns see the right
+      // block (matches the existing add path in `addBlock`). The block
+      // type comes from initialRows when the row is server-rendered.
+      for (const id of plan.toAdd) {
+        const row = initialRows.find(r => r.id === id)
+        rowBinding.add(id, row?.type ? { type: row.type } : {})
+      }
+    }, 1500)
+    return () => clearTimeout(timer)
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [rowBinding, formId])
   const [collapsed, setCollapsed] = useState<Record<string, boolean>>(() =>
     accordion ? {} : initSeedCollapsed(initialRows, formId, name, defaultCollapsed, collapsible),
   )
@@ -361,26 +387,23 @@ export function BuilderInput({
   }
 
   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
-      let next: RowState[]
-      if (dir === -1) {
-        let target = idx - 1
-        while (target >= 0 && prev[target]?.hidden) target--
-        if (target < 0) return prev
-        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)
-      }
-      if (next !== prev) newOrder = next.map(r => r.id)
-      return next
-    })
-    if (newOrder !== null) rowBinding?.reorder(newOrder)
+    const idx = rows.findIndex(r => r.id === id)
+    if (idx < 0) return
+    let next: RowState[]
+    if (dir === -1) {
+      let target = idx - 1
+      while (target >= 0 && rows[target]?.hidden) target--
+      if (target < 0) return
+      next = reorderRows(rows, idx, target)
+    } else {
+      let target = idx + 1
+      while (target < rows.length && rows[target]?.hidden) target++
+      if (target >= rows.length) return
+      next = reorderRows(rows, idx, target + 1)
+    }
+    if (next === rows) return
+    setRows(next)
+    rowBinding?.reorder(next.map(r => r.id))
   }
 
   // ── DnD state (skipped when buttonsOnly) ────────────────
@@ -394,15 +417,16 @@ export function BuilderInput({
   } = useRowReorderDnd({
     enabled: dndEnabled,
     onDrop: (fromId, at) => {
-      let newOrder: string[] | null = null
-      setRows(prev => {
-        const fromIdx = prev.findIndex(r => r.id === fromId)
-        if (fromIdx < 0) return prev
-        const next = reorderRows(prev, fromIdx, at)
-        if (next !== prev) newOrder = next.map(r => r.id)
-        return next
-      })
-      if (newOrder !== null) rowBinding?.reorder(newOrder)
+      // See RepeaterInput's matching onDrop comment — closure-mutation
+      // through setRows's updater is unreliable when other state updates
+      // are batched (useRowReorderDnd nulls dragId/dropAt right before
+      // calling this).
+      const fromIdx = rows.findIndex(r => r.id === fromId)
+      if (fromIdx < 0) return
+      const next = reorderRows(rows, fromIdx, at)
+      if (next === rows) return
+      setRows(next)
+      rowBinding?.reorder(next.map(r => r.id))
     },
   })
 

package/src/react/fields/RepeaterInput.tsx

@@ -21,6 +21,7 @@ import {
   DEFAULT_DELETE,
 } from './rowChromeButton.js'
 import { syncRowGates } from './syncRowGates.js'
+import { consumeReconcileFlag, computeReconcilePlan } from './repeaterReconcile.js'
 import {
   generateRowId, makeAccordionStorage, makeCollapsedStorage,
 } from './rowState.js'
@@ -304,6 +305,37 @@ export function RepeaterInput({
       })
     })
   }, [rowBinding, meta.template])
+
+  // Phase A reconciliation for `Repeater.relationship` PK-switch — when
+  // the surrounding form just submitted in this tab AND we're inside a
+  // collab room with a row binding, snapshot the CRDT order after a
+  // short settle (long enough for WS sync to deliver any persisted
+  // state) and reconcile against `initialRows`. Drops orphan UUIDs
+  // whose rows just persisted under a fresh DB PK; idempotent + no-op
+  // for non-relationship Repeaters where `__id` stays UUID across
+  // save+reload. Plan:
+  // `pilotiq-pro/docs/plans/repeater-relationship-pk-switch.md`.
+  useEffect(() => {
+    if (!rowBinding) return
+    if (!consumeReconcileFlag(formId)) return
+    // Give WS sync time to deliver any persisted rows before reading
+    // current(). 1500ms is conservative; typical sync settles in <300ms.
+    // The reconciler is one-shot per submit, so we accept the brief
+    // visual flicker over a tighter timer that might fire pre-sync.
+    const timer = setTimeout(() => {
+      const plan = computeReconcilePlan({
+        current:       rowBinding.current(),
+        authoritative: initialRows.map(r => r.id),
+      })
+      for (const id of plan.toRemove) rowBinding.remove(id)
+      for (const id of plan.toAdd)    rowBinding.add(id, {})
+    }, 1500)
+    return () => clearTimeout(timer)
+    // initialRows is a stable useMemo([]) ref so it's safe to omit. We
+    // intentionally key only on rowBinding + formId — the reconciler is
+    // tied to the submit lifecycle, not to row-state changes.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [rowBinding, formId])
   const [collapsed, setCollapsed] = useState<Record<string, boolean>>(() =>
     accordion ? {} : initSeedCollapsed(initialRows, formId, name, defaultCollapsed, collapsible),
   )
@@ -394,29 +426,26 @@ export function RepeaterInput({
   }
 
   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
-        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)
-      }
-      if (next !== prev) newOrder = next.map(r => r.id)
-      return next
-    })
-    if (newOrder !== null) rowBinding?.reorder(newOrder)
+    const idx = rows.findIndex(r => r.id === id)
+    if (idx < 0) return
+    // 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 && rows[target]?.hidden) target--
+      if (target < 0) return
+      next = reorderRows(rows, idx, target)
+    } else {
+      let target = idx + 1
+      while (target < rows.length && rows[target]?.hidden) target++
+      if (target >= rows.length) return
+      next = reorderRows(rows, idx, target + 1)
+    }
+    if (next === rows) return
+    setRows(next)
+    rowBinding?.reorder(next.map(r => r.id))
   }
 
   // ── DnD state ───────────────────────────────────────────
@@ -429,15 +458,20 @@ 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
-        const next = reorderRows(prev, fromIdx, at)
-        if (next !== prev) newOrder = next.map(r => r.id)
-        return next
-      })
-      if (newOrder !== null) rowBinding?.reorder(newOrder)
+      // Compute next from the current `rows` directly. The previous
+      // setRows(updater) + closure-mutation pattern relied on React
+      // running the updater synchronously inside setState — which only
+      // happens when no other update is queued. `useRowReorderDnd`'s
+      // handleDrop sets dragId/dropAt to null right before calling
+      // this callback, so the updater runs in commit phase and the
+      // outer `newOrder` stayed null past the `if` check, silently
+      // skipping the rowBinding.reorder broadcast.
+      const fromIdx = rows.findIndex(r => r.id === fromId)
+      if (fromIdx < 0) return
+      const next = reorderRows(rows, fromIdx, at)
+      if (next === rows) return
+      setRows(next)
+      rowBinding?.reorder(next.map(r => r.id))
     },
   })