@pilotiq/pilotiq 0.7.2 → 0.8.0

package/src/react/AppShell.tsx

@@ -10,10 +10,12 @@ import type { RightPanelRegistry } from './right-panel-registry.js'
 import { RightPanelRegistryProvider } from './right-panel-registry.js'
 import { RightSidebarProvider, useRightSidebarOptional } from './RightSidebarContext.js'
 import { RightSidebar } from './RightSidebar.js'
+import { RecordWrapperGate } from './RecordWrapperGate.js'
 import { useIsMobile } from './hooks/use-mobile.js'
 import type { NavItem, UserMenuMeta, DatabaseNotificationsMeta, RightSidebarMeta } from '../pageData.js'
 import type { RenderHookMap } from '../RenderHook.js'
 import { RenderHookSlot } from './RenderHookSlot.js'
+import type { ComponentSlotRegistry } from './component-slots.js'
 
 export interface AppShellProps {
   panel: {
@@ -73,6 +75,13 @@ export interface AppShellProps {
    * default — chrome renders without any extra wrapping.
    */
   layoutProviderRegistry?: ReadonlyArray<React.ComponentType<{ children: React.ReactNode; basePath?: string }>>
+  /**
+   * Build-time chrome-slot overrides from the Vite plugin. Populated
+   * when the panel module calls `Pilotiq.components({ nav, … })`.
+   * Sparse `{}` is the no-op default. Currently only `nav` is honored;
+   * additional slots will land as concrete consumers ask.
+   */
+  componentSlotRegistry?: ComponentSlotRegistry
   children: React.ReactNode
 }
 
@@ -110,12 +119,29 @@ export function AppShell({ layout = 'sidebar', notifications, componentRegistry,
   const hooks = props.panel.renderHooks
   const rightSidebarMeta = props.panel.rightSidebar
 
+  // Record-scoped wrapper (collab room, audit trail, …) — pass-through
+  // when no plugin registered a wrapper or when the URL isn't a
+  // record-edit page. Wrapping `children` before forwarding to `Layout`
+  // mounts the wrapper around the page content area only, leaving the
+  // sidebar / topbar chrome outside.
+  const layoutProps = {
+    ...props,
+    children: (
+      <RecordWrapperGate
+        basePath={props.basePath}
+        {...(props.currentPath !== undefined ? { currentPath: props.currentPath } : {})}
+      >
+        {props.children}
+      </RecordWrapperGate>
+    ),
+  }
+
   const inner = (
     <ToasterProvider {...toasterProps}>
       <CommandPaletteProvider setOpen={setPaletteOpen}>
         <RenderHookSlot name="panels::body.start" hooks={hooks} />
         <RightSidebarLayoutFrame>
-          <Layout {...props} />
+          <Layout {...layoutProps} />
         </RightSidebarLayoutFrame>
         <RenderHookSlot name="panels::body.end" hooks={hooks} />
         <CommandPalette {...paletteProps} />

package/src/react/CollabExtensionFactoryRegistry.ts

@@ -0,0 +1,55 @@
+/**
+ * Module-level registry slot for the Tiptap extension factory that turns
+ * a collab room into editor-attachable extensions (`Collaboration` +
+ * `CollaborationCursor`).
+ *
+ * Wiring posture (mirrors `PendingSuggestionOverlayRegistry`):
+ *   - `@pilotiq-pro/collab`'s plugin calls `registerCollabExtensions(...)`
+ *     once at boot from inside `register(panel)`. The factory closes over
+ *     the `@tiptap/extension-collaboration` + `-cursor` imports, so pilotiq
+ *     core (and `@pilotiq/tiptap`) never carry those as peer deps.
+ *   - `@pilotiq/tiptap`'s `TiptapEditor` calls `getCollabExtensions()` at
+ *     mount; if non-null AND a `useCollabRoom()` value is present, it calls
+ *     the factory and spreads the returned array into the editor's
+ *     `extensions` slot. If either is missing, plain Tiptap + History runs.
+ *
+ * `unknown[]` return type is deliberate — pilotiq core has zero `@tiptap/*`
+ * imports and treats the returned values as opaque editor-extension refs.
+ * The Tiptap host trusts them and spreads them in.
+ */
+export interface CollabExtensionFactoryArgs {
+  /** `Y.Doc` for the surrounding record. Opaque to pilotiq core. */
+  ydoc:      unknown
+  /** `WebsocketProvider` for the same room. Opaque to pilotiq core. */
+  provider:  unknown
+  /**
+   * Field name — becomes the `Y.XmlFragment` selector
+   * (`Collaboration.configure({ field: fieldName })`) so multiple
+   * collab editors on the same record write to distinct fragments
+   * inside one shared ydoc.
+   */
+  fieldName: string
+  /** Presence info forwarded to `CollaborationCursor`. Sparse. */
+  user?: {
+    name?:  string
+    color?: string
+  }
+}
+
+export type CollabExtensionFactory = (args: CollabExtensionFactoryArgs) => unknown[]
+
+let _factory: CollabExtensionFactory | null = null
+
+/**
+ * Register the factory that builds collab extensions for one field +
+ * room. Called once at boot by `@pilotiq-pro/collab`'s plugin. No-op when
+ * no plugin registers — Tiptap renderers fall back to plain editing.
+ */
+export function registerCollabExtensions(factory: CollabExtensionFactory): void {
+  _factory = factory
+}
+
+/** Returns the registered factory, or `null`. */
+export function getCollabExtensions(): CollabExtensionFactory | null {
+  return _factory
+}

package/src/react/CollabRoomContext.ts

@@ -0,0 +1,42 @@
+import { createContext, useContext } from 'react'
+
+/**
+ * Per-record realtime-collab room — a Y.Doc plus its WebsocketProvider,
+ * shared across every collaborative field in the same form. Mirrors the
+ * Tiptap "Collaborative Fields" pattern: one ydoc per record, each editor
+ * scopes itself to its own `Y.XmlFragment` via the field's `name`.
+ *
+ * Pilotiq core does NOT instantiate the room — implementation lives in
+ * `@pilotiq-pro/collab`, which mounts the context with real Yjs values
+ * via `<RecordCollabRoom>`. Core just owns the shape so any field
+ * renderer (Tiptap, in-house, third-party) can subscribe through one
+ * open-core seam without taking a hard peer dep on Yjs.
+ *
+ * `ydoc` and `provider` are typed `unknown` deliberately — the consumer
+ * (typically `@pilotiq/tiptap`) hands them straight to a registered
+ * `CollabExtensionFactory` and never touches them directly, so pilotiq
+ * core stays Yjs-free.
+ */
+export interface CollabRoom {
+  /** `Y.Doc` instance. Opaque to pilotiq core. */
+  ydoc:      unknown
+  /** `WebsocketProvider` instance. Opaque to pilotiq core. */
+  provider:  unknown
+  /** Presence info for cursors / avatars. Forwarded to the extension factory. */
+  user?: {
+    name?:  string
+    color?: string
+  }
+}
+
+/**
+ * `null` default — fields read the context, and a null result means
+ * "no collab room mounted, fall back to local-only editing." This is
+ * the 99% case (collab plugin not installed).
+ */
+export const CollabRoomContext = createContext<CollabRoom | null>(null)
+
+/** Read the active collab room for the surrounding record, or `null`. */
+export function useCollabRoom(): CollabRoom | null {
+  return useContext(CollabRoomContext)
+}

package/src/react/FormCollabBindingRegistry.ts

@@ -0,0 +1,72 @@
+import type { CollabRoom } from './CollabRoomContext.js'
+
+/**
+ * Binding contract that a collab plugin returns from
+ * `registerFormCollabBinding` — wraps a single form's value map in a
+ * shared CRDT type (typically a `Y.Map` on the surrounding record's
+ * `Y.Doc`) so every field on the form syncs across clients.
+ *
+ * Pilotiq's `FormStateProvider` calls into this contract when a
+ * `<RecordCollabRoom>` is mounted up-tree:
+ *
+ *   - `get()` is read once on mount to overlay any already-synced
+ *     state on top of the form's SSR-rendered defaults.
+ *   - `set(name, v)` is called from `setValue` after the local React
+ *     state update — every controlled field's edit lands in the CRDT.
+ *   - `subscribe(fn)` registers a listener that fires when REMOTE
+ *     changes land; `fn(snapshot)` receives the full updated map.
+ *     The provider re-applies this snapshot onto its React state.
+ *   - `destroy()` is called on unmount — gives the plugin a chance to
+ *     remove its CRDT observer.
+ *
+ * `unknown` payloads keep pilotiq core Yjs-free; the binding owns its
+ * own type knowledge. Same posture as `CollabExtensionFactory`.
+ */
+export interface FormCollabBinding {
+  /** Snapshot of the current synced values. Called once on mount. */
+  get():        Record<string, unknown>
+  /** Write the local edit to the CRDT. Triggers a broadcast to peers. */
+  set(name: string, value: unknown): void
+  /** Subscribe to remote changes. Returns an unsubscribe function. */
+  subscribe(fn: (snapshot: Record<string, unknown>) => void): () => void
+  /** Cleanup hook called when the form unmounts. */
+  destroy():    void
+}
+
+export interface FormCollabBindingFactoryArgs {
+  /** Active collab room — provides `ydoc`, `provider`, `user`. Opaque to pilotiq core. */
+  room:    CollabRoom
+  /**
+   * Form identifier — used by the binding to partition CRDT state when
+   * multiple forms render against the same room (e.g. a record page that
+   * shows a primary form plus a side-mounted action form). Most pages
+   * only have one form, so most bindings use this as the `Y.Map` name.
+   */
+  formId:  string
+  /**
+   * Initial values from pilotiq's normal SSR resolution. The binding
+   * uses these to perform the idempotent "first-load seed" (`!ymap.has(k)`
+   * gated write) so the first client to open a record populates the
+   * Y.Map with the DB-derived defaults; subsequent clients find the
+   * map already populated and skip.
+   */
+  initial: Record<string, unknown>
+}
+
+export type FormCollabBindingFactory = (args: FormCollabBindingFactoryArgs) => FormCollabBinding
+
+let _factory: FormCollabBindingFactory | null = null
+
+/**
+ * Register the form-level CRDT binding factory. Called once at boot by
+ * `@pilotiq-pro/collab`'s plugin. No-op when no plugin registers —
+ * `FormStateProvider` falls back to its plain local-state path.
+ */
+export function registerFormCollabBinding(factory: FormCollabBindingFactory): void {
+  _factory = factory
+}
+
+/** Returns the registered binding factory, or `null`. */
+export function getFormCollabBinding(): FormCollabBindingFactory | null {
+  return _factory
+}

package/src/react/RecordWrapperGate.tsx

@@ -0,0 +1,40 @@
+import { type ReactNode } from 'react'
+import { getRecordWrapper } from './RecordWrapperRegistry.js'
+import { parseRecordEditUrl } from './parseRecordEditUrl.js'
+
+export interface RecordWrapperGateProps {
+  currentPath?: string
+  basePath:     string
+  children:     ReactNode
+}
+
+/**
+ * Conditionally wraps the page tree with the plugin-registered
+ * `RecordWrapper` when the current URL resolves to a record-bound edit
+ * page. Pass-through in every other case:
+ *
+ *   - no plugin registered a wrapper (`getRecordWrapper() === null`)
+ *   - the URL isn't a record-edit URL (list / create / view / dashboard / …)
+ *   - `currentPath` not yet known on the very first SSR render
+ *
+ * Mounted once inside `AppShell` around the page content area so
+ * record-scoped plugins (collab room, audit trail, …) get one
+ * lifetimed mount per record-view-or-edit without each plugin having
+ * to thread URL parsing into its own provider.
+ *
+ * Scope limited to `/edit` URLs in v1; view-page support (read-only
+ * collab cursors on `ViewPage`) is a follow-up.
+ */
+export function RecordWrapperGate({ currentPath, basePath, children }: RecordWrapperGateProps) {
+  const Wrapper = getRecordWrapper()
+  if (!Wrapper || !currentPath) return <>{children}</>
+
+  const identity = parseRecordEditUrl(currentPath, basePath)
+  if (!identity) return <>{children}</>
+
+  return (
+    <Wrapper resourceSlug={identity.resourceSlug} recordId={identity.recordId}>
+      {children}
+    </Wrapper>
+  )
+}

package/src/react/RecordWrapperRegistry.ts

@@ -0,0 +1,39 @@
+import type { ComponentType, ReactNode } from 'react'
+
+/**
+ * Props the page-record wrapper receives from `RecordWrapperGate` when
+ * the current URL resolves to a record-bound edit page (`${base}/.../:id/edit`).
+ *
+ * The wrapper is responsible for whatever record-scoped context the
+ * plugin owns — `@pilotiq-pro/collab` mounts a `<RecordCollabRoom>`
+ * here so every collab field inside the page shares one Y.Doc + WS
+ * connection. Other plugins could mount per-record presence, audit
+ * logging, or anything else that's record-bound rather than panel-bound.
+ *
+ * `resourceSlug` is the slash-joined slug-path (cluster-prefixed for
+ * clustered resources, parent-prefixed for nested-relation edits) so
+ * two URLs that target different records always produce distinct
+ * wrapper keys / room names.
+ */
+export interface RecordWrapperProps {
+  resourceSlug: string
+  recordId:     string
+  children:     ReactNode
+}
+
+let _component: ComponentType<RecordWrapperProps> | null = null
+
+/**
+ * Register a component that wraps the page tree on every record-edit
+ * route. Called once at boot by a plugin (e.g. `@pilotiq-pro/collab`).
+ * No-op when no plugin registers — `RecordWrapperGate` passes through
+ * unchanged.
+ */
+export function registerRecordWrapper(C: ComponentType<RecordWrapperProps>): void {
+  _component = C
+}
+
+/** Returns the registered wrapper component, or `null`. */
+export function getRecordWrapper(): ComponentType<RecordWrapperProps> | null {
+  return _component
+}