@pilotiq/pilotiq 0.1.0

package/src/react/RenderHookSlot.tsx

@@ -0,0 +1,32 @@
+'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

@@ -0,0 +1,257 @@
+/**
+ * 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>
+  )
+}

package/src/react/RightSidebarContext.tsx

@@ -0,0 +1,211 @@
+/**
+ * Right-sidebar runtime state — open/close, active tab, current width.
+ *
+ * Shape mirrors the contract documented in `docs/plans/right-sidebar.md` so
+ * plugin bodies and the chrome read from the same surface. Values persist
+ * to localStorage under per-basePath keys so a multi-panel app (`/admin`
+ * + `/simple`) doesn't share state across mount points.
+ *
+ * The provider mounts inside `AppShell` only when `panel.rightSidebar` is
+ * present — plugin contributions render inside the chrome's body, so
+ * they're guaranteed to call `useRightSidebar()` under the provider.
+ *
+ * Programmatic open: any descendant of the provider (most useful: a render
+ * hook on the topbar) can flip open/active via the hook. The default
+ * `RightSidebarTrigger` uses this exact wiring; consumers that want a
+ * floating-button affordance can call `useRightSidebar()` and roll their own.
+ */
+import React, {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from 'react'
+import type { RightPanelMeta, RightSidebarMeta } from '../pageData.js'
+import { clampPanelWidth } from './useResizableWidth.js'
+
+export interface RightSidebarApi {
+  /** Whether the panel is currently open. */
+  open:          boolean
+  setOpen:       (v: boolean) => void
+  toggle:        () => void
+  /** Active tab's contribution id. `null` when no tab has been picked
+   *  (initial render of an empty-localStorage panel). */
+  activeId:      string | null
+  setActiveId:   (id: string) => void
+  /** Current panel width in px. */
+  width:         number
+  setWidth:      (px: number) => void
+  /** All visible contributions for the current panel. Sorted by the
+   *  server-side `panelInfo()` builder; the order is stable across
+   *  navigations. */
+  contributions: RightPanelMeta[]
+  /** Server-supplied min/max/default — exposed so the chrome's resize
+   *  handle clamps to the same range. */
+  bounds:        { min: number; max: number; default: number }
+}
+
+const Ctx = createContext<RightSidebarApi | null>(null)
+
+export interface RightSidebarProviderProps {
+  meta:     RightSidebarMeta
+  basePath: string
+  children: React.ReactNode
+}
+
+function storageKey(basePath: string, key: 'open' | 'activeId' | 'width'): string {
+  return `pilotiq.rightSidebar.${basePath}.${key}`
+}
+
+function readBool(key: string, fallback: boolean): boolean {
+  if (typeof window === 'undefined') return fallback
+  try {
+    const raw = window.localStorage?.getItem(key)
+    if (raw === 'true') return true
+    if (raw === 'false') return false
+    return fallback
+  } catch { return fallback }
+}
+
+function readString(key: string): string | null {
+  if (typeof window === 'undefined') return null
+  try {
+    const raw = window.localStorage?.getItem(key)
+    return raw ?? null
+  } catch { return null }
+}
+
+function writeString(key: string, value: string | null): void {
+  if (typeof window === 'undefined') return
+  try {
+    if (value === null) window.localStorage?.removeItem(key)
+    else                window.localStorage?.setItem(key, value)
+  } catch { /* private mode / quota — best-effort */ }
+}
+
+export function RightSidebarProvider({ meta, basePath, children }: RightSidebarProviderProps): React.ReactElement {
+  const openKey     = storageKey(basePath, 'open')
+  const activeKey   = storageKey(basePath, 'activeId')
+  const widthKey    = storageKey(basePath, 'width')
+
+  const fallbackId = meta.panels[0]?.id ?? null
+
+  const [open,     setOpenState]     = useState<boolean>(() => readBool(openKey, false))
+  const [activeId, setActiveIdState] = useState<string | null>(() => {
+    const stored = readString(activeKey)
+    if (stored && meta.panels.some(p => p.id === stored)) return stored
+    return fallbackId
+  })
+  const [width,    setWidthState]    = useState<number>(() => {
+    const stored = readString(widthKey)
+    return clampPanelWidth(stored ?? meta.defaultWidth, {
+      min: meta.minWidth,
+      max: meta.maxWidth,
+      defaultWidth: meta.defaultWidth,
+    })
+  })
+
+  // Re-validate `activeId` when the contribution set changes (e.g.,
+  // canAccess gating flipped after a route nav). If the stored id has
+  // disappeared, fall back to the first visible tab. Skip when nothing
+  // changed so we don't churn renders on every server data refresh.
+  const visibleIds = useMemo(() => meta.panels.map(p => p.id), [meta.panels])
+  const visibleIdsRef = useRef<string[]>(visibleIds)
+  useEffect(() => {
+    const prev = visibleIdsRef.current
+    visibleIdsRef.current = visibleIds
+    const stillValid = activeId !== null && visibleIds.includes(activeId)
+    if (stillValid) return
+    if (prev.length === visibleIds.length && prev.every((id, i) => id === visibleIds[i])) return
+    setActiveIdState(visibleIds[0] ?? null)
+  }, [visibleIds, activeId])
+
+  const setOpen = useCallback((v: boolean): void => {
+    setOpenState(v)
+    writeString(openKey, v ? 'true' : 'false')
+  }, [openKey])
+
+  const toggle = useCallback((): void => {
+    setOpenState((prev) => {
+      const next = !prev
+      writeString(openKey, next ? 'true' : 'false')
+      return next
+    })
+  }, [openKey])
+
+  const setActiveId = useCallback((id: string): void => {
+    setActiveIdState(id)
+    writeString(activeKey, id)
+    // Selecting a tab implies opening — matches VS Code behaviour.
+    setOpenState(true)
+    writeString(openKey, 'true')
+  }, [activeKey, openKey])
+
+  const setWidth = useCallback((px: number): void => {
+    const clamped = clampPanelWidth(px, {
+      min: meta.minWidth,
+      max: meta.maxWidth,
+      defaultWidth: meta.defaultWidth,
+    })
+    setWidthState(clamped)
+    writeString(widthKey, String(clamped))
+  }, [meta.minWidth, meta.maxWidth, meta.defaultWidth, widthKey])
+
+  // Mod-Shift-\ — VS Code's secondary side bar shortcut. Owned by core
+  // so plugins don't fight over the same key.
+  useEffect(() => {
+    if (typeof window === 'undefined') return
+    const onKey = (e: KeyboardEvent): void => {
+      if (e.code !== 'Backslash') return
+      if (!e.shiftKey) return
+      if (!(e.metaKey || e.ctrlKey)) return
+      e.preventDefault()
+      toggle()
+    }
+    window.addEventListener('keydown', onKey)
+    return () => window.removeEventListener('keydown', onKey)
+  }, [toggle])
+
+  const value = useMemo<RightSidebarApi>(() => ({
+    open,
+    setOpen,
+    toggle,
+    activeId,
+    setActiveId,
+    width,
+    setWidth,
+    contributions: meta.panels,
+    bounds: { min: meta.minWidth, max: meta.maxWidth, default: meta.defaultWidth },
+  }), [open, setOpen, toggle, activeId, setActiveId, width, setWidth, meta.panels, meta.minWidth, meta.maxWidth, meta.defaultWidth])
+
+  return <Ctx.Provider value={value}>{children}</Ctx.Provider>
+}
+
+/**
+ * Read the right-sidebar API. Throws when called outside a
+ * `RightSidebarProvider` — call it from inside a contribution's `render`
+ * body or any descendant component.
+ */
+export function useRightSidebar(): RightSidebarApi {
+  const v = useContext(Ctx)
+  if (v === null) {
+    throw new Error(
+      '[Pilotiq] useRightSidebar() called outside <RightSidebarProvider>. ' +
+      'The provider mounts only when `panel.rightSidebar` is present in meta — ' +
+      'either no contributions were registered, or the auth gate dropped them all.',
+    )
+  }
+  return v
+}
+
+/**
+ * Optional variant — returns `null` when no provider is mounted instead
+ * of throwing. Useful for chrome that wants to render only when the
+ * surface is active (e.g., the topbar trigger button).
+ */
+export function useRightSidebarOptional(): RightSidebarApi | null {
+  return useContext(Ctx)
+}

package/src/react/RightSidebarTrigger.tsx

@@ -0,0 +1,53 @@
+/**
+ * Right-sidebar toggle button.
+ *
+ * Mounts in the topbar's right cluster between `NotificationBell` and
+ * `UserMenu`. Renders nothing when no `<RightSidebarProvider>` is mounted
+ * (i.e., `panel.rightSidebar` was absent from `panelInfo()`), so layouts
+ * can include the trigger unconditionally and let it self-suppress.
+ *
+ * Icon swaps between open and closed states (matches the upstream
+ * `PanelRightOpen` / `PanelRightClose` Lucide pair). The keyboard
+ * shortcut (Mod-Shift-\) is owned by the provider — the button is just
+ * a click affordance.
+ */
+import React from 'react'
+import { PanelRightOpenIcon, PanelRightCloseIcon } from 'lucide-react'
+import { cn } from './utils.js'
+import { useRightSidebarOptional } from './RightSidebarContext.js'
+import { useIconFor } from './icon-context.js'
+
+export function RightSidebarTrigger(): React.ReactElement | null {
+  const sidebar = useRightSidebarOptional()
+  // When a single contribution is registered, prefer its icon on the
+  // trigger. With 2+, fall back to the generic panel icon — the per-tab
+  // icons live on the tab strip.
+  const single = sidebar && sidebar.contributions.length === 1
+    ? sidebar.contributions[0]
+    : undefined
+  const SingleIcon = useIconFor(single?.icon)
+
+  if (!sidebar) return null
+  if (sidebar.contributions.length === 0) return null
+
+  const open = sidebar.open
+  const Fallback = open ? PanelRightCloseIcon : PanelRightOpenIcon
+  const Icon = SingleIcon ?? Fallback
+
+  return (
+    <button
+      type="button"
+      onClick={sidebar.toggle}
+      className={cn(
+        'inline-flex size-8 items-center justify-center rounded-md text-muted-foreground transition-colors',
+        'hover:bg-accent hover:text-foreground',
+        open && 'bg-accent text-foreground',
+      )}
+      aria-label={open ? 'Close side panel' : 'Open side panel'}
+      aria-pressed={open}
+      title={open ? 'Close side panel (⌘⇧\\)' : 'Open side panel (⌘⇧\\)'}
+    >
+      <Icon className="size-4" aria-hidden="true" />
+    </button>
+  )
+}