@pilotiq/pilotiq 0.24.1 → 0.24.3

package/src/react/PendingSuggestionsContext.tsx

@@ -1,172 +0,0 @@
-import React, { createContext, useContext, useMemo } from 'react'
-
-/**
- * One AI- (or extension-) sourced suggested field-value change. Sits in a
- * unified queue read by:
- *
- *   - the Tiptap `RichTextField` renderer — for `richtext` fields, the
- *     suggestion is mirrored into the editor's `AiSuggestion` extension as
- *     an inline diff with per-hunk Approve/Reject chips
- *   - `FieldShell`'s overlay slot — for any other field type, a registered
- *     overlay component renders a `currentValue` vs `suggestedValue` diff
- *     card below the input
- *   - aggregate "Pending suggestions" pills (e.g. in a chat sidebar) — read
- *     the full list to show counts + bulk approve / reject affordances
- *
- * The shape is intentionally generic — the `meta` bag carries field-type-
- * specific extras (e.g. `editorRange: { from, to }` for `richtext`).
- *
- * Pilotiq core does NOT push or apply suggestions itself. The provider
- * implementation + push paths live in plugin packages (e.g.
- * `@pilotiq-pro/ai`); core just owns the type, context, and hooks so any
- * field renderer can subscribe through one open-core seam.
- */
-/**
- * Where a suggestion came from. Lets aggregate consumers (pill UIs)
- * filter the shared queue by surface — e.g. a popover-chat scoped pill
- * shows only suggestions produced by its own session, while the
- * sidebar pill shows everything. Sparse on push; consumers treat
- * absence as "unknown origin, include in unfiltered views".
- */
-export interface PendingSuggestionOrigin {
-  /**
-   * Which UI surface initiated the agent run that produced this
-   * suggestion. `'field-action'` covers the `✦` per-field dropdown.
-   */
-  surface:    'sidebar' | 'popover' | 'field-action'
-  /**
-   * Stable id of the agent run / chat turn that produced this
-   * suggestion. Popover pills filter on this so they only see their
-   * own session's output even when the panel-wide queue holds many.
-   */
-  runId?:     string
-  /** Slug of the agent whose tool call produced the suggestion. */
-  agentSlug?: string
-}
-
-export interface PendingSuggestion {
-  /** Stable id; the producer is responsible for uniqueness. */
-  id:              string
-  /** Field name this suggestion targets. Matched verbatim in the renderer. */
-  fieldName:       string
-  /**
-   * Form scope. Multi-form pages (Plan #5 reactive fields) stamp the form's
-   * id here so a renderer in form A doesn't pick up a suggestion meant for
-   * form B. Optional — when both producer and consumer omit it, suggestions
-   * are global.
-   */
-  formId?:         string
-  /** Snapshot of the field's value at the time the suggestion was produced. */
-  currentValue:    unknown
-  /** Proposed replacement. */
-  suggestedValue:  unknown
-  /** Optional attribution surfaced on the diff overlay / inline chip. */
-  source?: {
-    agentSlug?:  string
-    agentLabel?: string
-  }
-  /**
-   * Provenance hint for cross-surface filtering. Sparse — pushed when
-   * the producer knows which agent run / chat surface it's running
-   * inside (e.g. the popover-chat tagging its turn id so its scoped
-   * pill can filter the shared queue). Aggregate consumers that don't
-   * care just leave the field unread.
-   */
-  origin?:         PendingSuggestionOrigin
-  /** Wallclock ms when produced. Producers fill this in on `push`. */
-  createdAt:       number
-  /** Field-type-specific extras (e.g. `editorRange: { from, to }`). Sparse. */
-  meta?:           Record<string, unknown>
-}
-
-export interface PendingSuggestionsApi {
-  /** Full list across every field + form. Aggregate consumers read this. */
-  list:        readonly PendingSuggestion[]
-  /** Add a suggestion to the queue. Returns the (possibly producer-supplied) id. */
-  push:        (suggestion: Omit<PendingSuggestion, 'createdAt'> & { createdAt?: number }) => string
-  /**
-   * Drop the suggestion from the queue. Used by both inline approval
-   * paths (where the renderer applies directly and just notifies the
-   * queue) AND by Reject. For aggregate consumers (e.g. a chat-pill
-   * "Approve all" button) that live outside the form's React tree, see
-   * `approve` below — it looks up a registered applier and calls it
-   * before dismissing.
-   */
-  dismiss:     (id: string) => void
-  /**
-   * Apply + dismiss. Resolves the suggestion's `(formId, fieldName)`
-   * pair against `PendingSuggestionApplierRegistry`; if an applier is
-   * registered (FieldShell + Tiptap bridge auto-register on mount),
-   * runs it and then dismisses. If no applier is registered (or the
-   * applier throws), falls through to a plain `dismiss` so the queue
-   * still clears — never strands an entry.
-   *
-   * Use this from cross-tree surfaces (chat-sidebar pending-pill).
-   * Inline surfaces (FieldShell overlay, Tiptap chip) apply via their
-   * own React-tree-local mutators and call `dismiss` directly.
-   */
-  approve:     (id: string) => void
-  /**
-   * Drop every suggestion matching the optional filter. With no filter,
-   * empties the entire queue.
-   */
-  dismissAll:  (filter?: { fieldName?: string; formId?: string }) => void
-  /**
-   * Apply + dismiss every suggestion matching the optional filter.
-   * Calls `approve(id)` per entry — same fall-through semantics if an
-   * applier is missing or throws.
-   */
-  approveAll:  (filter?: { fieldName?: string; formId?: string }) => void
-}
-
-const NOOP_API: PendingSuggestionsApi = Object.freeze({
-  list:       Object.freeze([]) as readonly PendingSuggestion[],
-  push:       () => '',
-  dismiss:    () => {},
-  approve:    () => {},
-  dismissAll: () => {},
-  approveAll: () => {},
-})
-
-/**
- * Context default is a no-op API — fields that subscribe in trees without a
- * real provider mounted (e.g. the marketing site's preview, headless tests)
- * see an empty list and no-op approval methods. Never throws.
- */
-export const PendingSuggestionsContext = createContext<PendingSuggestionsApi>(NOOP_API)
-
-/** Read the full queue + producer methods. Used by aggregate UIs. */
-export function usePendingSuggestions(): PendingSuggestionsApi {
-  return useContext(PendingSuggestionsContext)
-}
-
-/**
- * Subscribe a single field-renderer to its slice of the queue. Returns
- * `list` already filtered + a `dismiss` callback that the renderer wires
- * to its Approve / Reject buttons.
- *
- * Matching rules:
- *   - `s.fieldName === fieldName` (verbatim)
- *   - if both `formId` args are non-`undefined`, they must match; otherwise
- *     the entry passes (so global suggestions reach scoped readers and
- *     vice-versa)
- *
- * The list reference is stable across renders unless the underlying
- * filtered slice actually changes — useful for `useEffect` dependencies
- * in renderers that mirror suggestions into their own state.
- */
-export function usePendingSuggestionsForField(
-  fieldName: string,
-  formId?:   string,
-): {
-  list:    readonly PendingSuggestion[]
-  dismiss: (id: string) => void
-} {
-  const api = useContext(PendingSuggestionsContext)
-  const list = useMemo(() => api.list.filter(s => {
-    if (s.fieldName !== fieldName) return false
-    if (formId === undefined || s.formId === undefined) return true
-    return s.formId === formId
-  }), [api.list, fieldName, formId])
-  return { list, dismiss: api.dismiss }
-}

package/src/react/RecordWrapperGate.tsx

@@ -1,58 +0,0 @@
-import { type ReactNode } from 'react'
-import { getRecordWrapper } from './RecordWrapperRegistry.js'
-import { parseRecordPageUrl } from './parseRecordEditUrl.js'
-import type { ResourceCollabConfig } from '../Resource.js'
-
-/** Per-resource collab opt-in keyed by URL slug (`R.getSlug()` for
- * non-clustered, `${cluster.slug}/${R.getSlug()}` for clustered). Built
- * server-side by `panelInfo()` as `recordCollab`. */
-export type RecordCollabMap = Record<string, ResourceCollabConfig>
-
-export interface RecordWrapperGateProps {
-  currentPath?: string
-  basePath:     string
-  /** Resource opt-in map. Absent means no resource opted in (or the
-   *  panel has no resources) — gate always passes through. */
-  recordCollab?: RecordCollabMap
-  children:     ReactNode
-}
-
-/**
- * Conditionally wraps the page tree with the plugin-registered
- * `RecordWrapper` when the current URL resolves to a record-bound page
- * AND the underlying resource has opted into collab on that page role.
- * Pass-through in every other case:
- *
- *   - no plugin registered a wrapper (`getRecordWrapper() === null`)
- *   - the URL isn't a record edit/view page
- *   - `currentPath` not yet known on the very first SSR render
- *   - the resource has not opted in via `static collab` (or has opted in
- *     but excluded the current page role)
- *
- * 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.
- *
- * v1 caveat: nested-relation edit URLs (`/articles/:parentId/comments/:childId/edit`)
- * have a dynamic-id segment baked into the URL slug, so they don't match
- * the resource-keyed `recordCollab` map and fall through to no-collab.
- * Collab on nested-relation edits is a follow-up.
- */
-export function RecordWrapperGate({ currentPath, basePath, recordCollab, children }: RecordWrapperGateProps) {
-  const Wrapper = getRecordWrapper()
-  if (!Wrapper || !currentPath) return <>{children}</>
-
-  const identity = parseRecordPageUrl(currentPath, basePath)
-  if (!identity) return <>{children}</>
-
-  const cfg = recordCollab?.[identity.resourceSlug]
-  if (!cfg) return <>{children}</>
-  if (!cfg.pages.includes(identity.role)) return <>{children}</>
-
-  return (
-    <Wrapper resourceSlug={identity.resourceSlug} recordId={identity.recordId}>
-      {children}
-    </Wrapper>
-  )
-}

package/src/react/RecordWrapperRegistry.ts

@@ -1,39 +0,0 @@
-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
-}

package/src/react/RenderHookSlot.tsx

@@ -1,32 +0,0 @@
-'use client'
-
-import React from 'react'
-import type { ElementMeta } from '../schema/Element.js'
-import type { RenderHookMap, RenderHookName } from '../RenderHook.js'
-import { SchemaRenderer } from './SchemaRenderer.js'
-
-/**
- * Mount point for a named render-hook slot. Reads pre-resolved
- * `ElementMeta[]` from the wire payload and walks them through the
- * existing `<SchemaRenderer>` so every Element type (Heading / Alert /
- * Form / Table / …) renders the same way it does in the main schema
- * tree.
- *
- * Renders `null` when no hooks were registered for the slot — every
- * supported chrome / page-role position mounts a `<RenderHookSlot>`
- * unconditionally, so the wire payload stays sparse on panels that
- * don't use render hooks.
- *
- *   <RenderHookSlot name="panels::topbar.start" hooks={panel.renderHooks} />
- */
-export function RenderHookSlot({
-  name,
-  hooks,
-}: {
-  name:  RenderHookName
-  hooks: RenderHookMap | undefined
-}) {
-  const elements = hooks?.[name]
-  if (!elements || elements.length === 0) return null
-  return <SchemaRenderer elements={elements as ElementMeta[]} />
-}

package/src/react/RightSidebar.tsx

@@ -1,257 +0,0 @@
-/**
- * Right-sidebar chrome — outer panel that hosts plugin contributions.
- *
- * Mounted by `AppShell` only when `panel.rightSidebar` is present in the
- * server-built meta. Reads runtime state (open / activeId / width) from
- * `useRightSidebar()` and resolves each contribution's body via
- * `useRightPanelComponent(id)` (Phase B's `_components.ts` manifest).
- *
- * Desktop: right-docked `position: fixed` rail with a 4px left-edge resize
- * handle. The companion `<RightSidebarSpacer>` reserves layout width on
- * the host so content compresses instead of clipping under the rail.
- *
- * Mobile (< md breakpoint): collapses to an overlay `<Sheet>` — no resize
- * handle, fixed width.
- *
- * Tab strip: hidden when only one contribution is registered (single-tab
- * UX matches VS Code's "Outline / etc." behaviour). Tabs persist active
- * selection through the provider's localStorage round-trip.
- */
-import React from 'react'
-import { XIcon } from 'lucide-react'
-import { cn } from './utils.js'
-import { useRightSidebar } from './RightSidebarContext.js'
-import { useRightPanelComponent } from './right-panel-registry.js'
-import { useIconFor } from './icon-context.js'
-import { useIsMobile } from './hooks/use-mobile.js'
-import {
-  Sheet,
-  SheetContent,
-  SheetHeader,
-  SheetTitle,
-} from './ui/sheet.js'
-import type { SerializedIcon } from '../icons/types.js'
-import type { RightPanelMeta } from '../pageData.js'
-
-export interface RightSidebarProps {
-  basePath: string
-  /** Live pathname — re-renders the panel body on SPA nav so consumers
-   *  can react to which page the user is on. */
-  currentPath?: string
-}
-
-function PanelIcon({ value }: { value: SerializedIcon | undefined }) {
-  const Icon = useIconFor(value)
-  if (!Icon) return null
-  return <Icon className="size-4" aria-hidden="true" />
-}
-
-function PanelBody({
-  contribution,
-  basePath,
-  currentPath,
-}: {
-  contribution: RightPanelMeta
-  basePath:     string
-  currentPath?: string
-}) {
-  const Component = useRightPanelComponent(contribution.id)
-  if (!Component) {
-    return (
-      <div className="p-4 text-sm text-destructive">
-        <p className="font-medium">Right panel not registered</p>
-        <p className="mt-1 text-muted-foreground">
-          No client component is bound to <code className="rounded bg-muted px-1">{contribution.id}</code>.
-          The Vite plugin&apos;s <code className="rounded bg-muted px-1">_components.ts</code> manifest is missing this entry —
-          extract the <code className="rounded bg-muted px-1">render</code> reference to a named export.
-        </p>
-      </div>
-    )
-  }
-  // Component reads its own context as needed; we forward the well-known
-  // RightPanelProps (basePath / currentPath / activeId) defined in
-  // `RightPanel.ts` so plugin authors don't have to plumb it themselves.
-  // `currentPath` is conditionally spread so an absent value does not
-  // collide with the prop's `undefined`-disallowed (exactOptional) shape.
-  const props: { basePath: string; activeId: string; currentPath?: string } = {
-    basePath,
-    activeId: contribution.id,
-  }
-  if (currentPath !== undefined) props.currentPath = currentPath
-  return <Component {...props} />
-}
-
-function TabStrip({
-  contributions,
-  activeId,
-  setActiveId,
-}: {
-  contributions: RightPanelMeta[]
-  activeId:      string | null
-  setActiveId:   (id: string) => void
-}) {
-  if (contributions.length < 2) return null
-  return (
-    <div role="tablist" className="flex items-center gap-0 border-b bg-muted/30 px-1">
-      {contributions.map((c) => {
-        const active = c.id === activeId
-        return (
-          <button
-            key={c.id}
-            type="button"
-            role="tab"
-            aria-selected={active}
-            onClick={() => setActiveId(c.id)}
-            className={cn(
-              'inline-flex items-center gap-1.5 rounded-t-md border-b-2 px-3 py-2 text-xs font-medium transition-colors',
-              active
-                ? 'border-primary text-foreground'
-                : 'border-transparent text-muted-foreground hover:text-foreground',
-            )}
-          >
-            <PanelIcon value={c.icon} />
-            <span>{c.label}</span>
-          </button>
-        )
-      })}
-    </div>
-  )
-}
-
-function PanelHeader({
-  active,
-  onClose,
-  hideTabs,
-}: {
-  active:   RightPanelMeta | undefined
-  onClose:  () => void
-  hideTabs: boolean
-}) {
-  return (
-    <div className="flex h-11 shrink-0 items-center gap-2 border-b px-3">
-      {hideTabs && active && (
-        <>
-          <PanelIcon value={active.icon} />
-          <span className="text-sm font-medium">{active.label}</span>
-        </>
-      )}
-      <button
-        type="button"
-        onClick={onClose}
-        className={cn(
-          'ms-auto inline-flex size-7 items-center justify-center rounded-md text-muted-foreground transition-colors',
-          'hover:bg-accent hover:text-foreground',
-        )}
-        aria-label="Close right sidebar"
-      >
-        <XIcon className="size-4" aria-hidden="true" />
-      </button>
-    </div>
-  )
-}
-
-/**
- * Outer chrome. Renders a fixed-position rail on desktop and a Sheet on
- * mobile. Reads its open / width / active state from the surrounding
- * `RightSidebarProvider`.
- */
-export function RightSidebar({ basePath, currentPath }: RightSidebarProps): React.ReactElement | null {
-  const sidebar  = useRightSidebar()
-  const isMobile = useIsMobile()
-
-  // Drag-resize: the provider owns width state + per-basePath
-  // localStorage persistence, so the chrome just listens at the document
-  // level and forwards each delta into `sidebar.setWidth`.
-  const onPointerDown = (e: React.PointerEvent<HTMLElement>): void => {
-    e.preventDefault()
-    const startX     = e.clientX
-    const startWidth = sidebar.width
-    const onMove = (ev: PointerEvent): void => {
-      const delta = startX - ev.clientX
-      sidebar.setWidth(startWidth + delta)
-    }
-    const onUp = (): void => {
-      document.removeEventListener('pointermove', onMove)
-      document.removeEventListener('pointerup',   onUp)
-    }
-    document.addEventListener('pointermove', onMove)
-    document.addEventListener('pointerup',   onUp)
-  }
-
-  const active = sidebar.contributions.find((c) => c.id === sidebar.activeId)
-              ?? sidebar.contributions[0]
-  const hideTabs = sidebar.contributions.length < 2
-
-  if (!sidebar.open) return null
-
-  if (isMobile) {
-    return (
-      <Sheet open={sidebar.open} onOpenChange={sidebar.setOpen}>
-        <SheetContent
-          side="right"
-          className="flex w-[min(20rem,calc(100vw-3rem))] flex-col p-0"
-          showCloseButton={false}
-        >
-          <SheetHeader className="border-b">
-            <SheetTitle>{active?.label ?? 'Side panel'}</SheetTitle>
-          </SheetHeader>
-          <TabStrip
-            contributions={sidebar.contributions}
-            activeId={sidebar.activeId}
-            setActiveId={sidebar.setActiveId}
-          />
-          <div className="flex-1 overflow-y-auto">
-            {active && (
-              <PanelBody
-                contribution={active}
-                basePath={basePath}
-                {...(currentPath !== undefined ? { currentPath } : {})}
-              />
-            )}
-          </div>
-        </SheetContent>
-      </Sheet>
-    )
-  }
-
-  return (
-    <aside
-      data-pilotiq-right-sidebar=""
-      style={{ width: sidebar.width }}
-      className={cn(
-        'fixed inset-y-0 end-0 z-30 flex flex-col border-s bg-background shadow-sm',
-      )}
-      role="complementary"
-      aria-label={active?.label ?? 'Side panel'}
-    >
-      {/* Left-edge resize handle. Thin strip; 4px wide hit area, 1px
-          highlight band on hover. Pointer events live at document level
-          inside the handler so leaving the strip doesn't end the drag. */}
-      <div
-        role="separator"
-        aria-orientation="vertical"
-        aria-label="Resize side panel"
-        onPointerDown={onPointerDown}
-        className={cn(
-          'absolute inset-y-0 start-0 w-1 cursor-ew-resize',
-          'hover:bg-border/80',
-        )}
-      />
-      <PanelHeader active={active} onClose={() => sidebar.setOpen(false)} hideTabs={hideTabs} />
-      <TabStrip
-        contributions={sidebar.contributions}
-        activeId={sidebar.activeId}
-        setActiveId={sidebar.setActiveId}
-      />
-      <div className="flex-1 overflow-y-auto">
-        {active && (
-          <PanelBody
-            contribution={active}
-            basePath={basePath}
-            {...(currentPath !== undefined ? { currentPath } : {})}
-          />
-        )}
-      </div>
-    </aside>
-  )
-}