@pilotiq/pilotiq 0.1.0

package/src/react/Toaster.tsx

@@ -0,0 +1,158 @@
+import React, { createContext, useCallback, useContext, useEffect, useRef, useState } from 'react'
+import {
+  CheckCircle2Icon, AlertTriangleIcon, AlertCircleIcon, InfoIcon, XIcon,
+  type LucideIcon,
+} from 'lucide-react'
+import type { NotificationMeta, NotificationType } from '../notifications/Notification.js'
+import { NotificationActionStrip } from './NotificationActionStrip.js'
+
+interface ToasterContextValue {
+  /** Add a notification to the stack. The id is auto-generated when
+   * absent so the same `Notification.make().toMeta()` can be re-used. */
+  notify: (n: NotificationMeta | Omit<NotificationMeta, 'id'>) => void
+}
+
+const ToasterContext = createContext<ToasterContextValue>({ notify: () => {} })
+
+const TYPE_ICONS: Record<NotificationType, LucideIcon> = {
+  info:    InfoIcon,
+  success: CheckCircle2Icon,
+  warning: AlertTriangleIcon,
+  error:   AlertCircleIcon,
+}
+
+const TYPE_CLASSES: Record<NotificationType, string> = {
+  info:    'border-blue-200    bg-blue-50    text-blue-900    dark:border-blue-900    dark:bg-blue-950/40    dark:text-blue-100',
+  success: 'border-emerald-200 bg-emerald-50 text-emerald-900 dark:border-emerald-900 dark:bg-emerald-950/40 dark:text-emerald-100',
+  warning: 'border-amber-200   bg-amber-50   text-amber-900   dark:border-amber-900   dark:bg-amber-950/40   dark:text-amber-100',
+  error:   'border-red-200     bg-red-50     text-red-900     dark:border-red-900     dark:bg-red-950/40     dark:text-red-100',
+}
+
+const TYPE_ICON_CLASSES: Record<NotificationType, string> = {
+  info:    'text-blue-600    dark:text-blue-300',
+  success: 'text-emerald-600 dark:text-emerald-300',
+  warning: 'text-amber-600   dark:text-amber-300',
+  error:   'text-red-600     dark:text-red-300',
+}
+
+let _clientIdSeq = 0
+function clientId(): string {
+  _clientIdSeq += 1
+  return `c-${_clientIdSeq}`
+}
+
+interface ToastItemProps {
+  item:      NotificationMeta
+  onDismiss: () => void
+}
+
+function ToastItem({ item, onDismiss }: ToastItemProps) {
+  const Icon = TYPE_ICONS[item.type]
+  const cls  = TYPE_CLASSES[item.type]
+  const iconCls = TYPE_ICON_CLASSES[item.type]
+
+  // Auto-dismiss timer. Skip when duration === 0 (persistent until
+  // manually dismissed). Toasts with actions auto-extend to 0
+  // (persistent) — auto-dismissal would race the user's click.
+  useEffect(() => {
+    const hasActions = item.actions && item.actions.length > 0
+    const ms = item.duration ?? (hasActions ? 0 : 5000)
+    if (ms <= 0) return
+    const t = setTimeout(onDismiss, ms)
+    return () => clearTimeout(t)
+  }, [item.duration, item.actions, onDismiss])
+
+  return (
+    <div
+      role="status"
+      aria-live="polite"
+      className={`pointer-events-auto flex items-start gap-3 rounded-lg border px-4 py-3 shadow-lg ${cls}`}
+    >
+      <Icon className={`size-5 mt-0.5 shrink-0 ${iconCls}`} aria-hidden />
+      <div className="flex-1 min-w-0">
+        <p className="text-sm font-semibold leading-snug">{item.title}</p>
+        {item.body && (
+          <p className="text-xs leading-snug mt-0.5 opacity-90">{item.body}</p>
+        )}
+        {item.actions && item.actions.length > 0 && (
+          <NotificationActionStrip
+            actions={item.actions}
+            onAfterClick={onDismiss}
+          />
+        )}
+      </div>
+      <button
+        type="button"
+        aria-label="Dismiss"
+        onClick={onDismiss}
+        className="shrink-0 rounded p-0.5 opacity-60 hover:opacity-100 transition"
+      >
+        <XIcon className="size-4" />
+      </button>
+    </div>
+  )
+}
+
+/**
+ * Provider that mounts the toast stack and exposes `useToast()` to descendants.
+ * Wrap your app once near the root (the AppShell does this automatically).
+ *
+ * `initialNotifications` is the server-flashed list — the AppShell reads
+ * it from `viewProps.notifications` and forwards it here. They flash on
+ * first mount and then disappear; subsequent re-renders don't re-flash.
+ */
+export function ToasterProvider({
+  children,
+  initialNotifications,
+}: {
+  children:              React.ReactNode
+  initialNotifications?: NotificationMeta[]
+}) {
+  const [items, setItems] = useState<NotificationMeta[]>([])
+  // Ref instead of useState: React 18 Strict Mode (dev) intentionally
+  // runs effects twice on the same component instance to surface mount-
+  // time bugs. With a useState flag the second run sees the stale closure
+  // value (state setters are async; the second effect's closure was
+  // captured at the same render as the first), so it would re-add the
+  // notifications and the user gets duplicate toasts. A ref updates
+  // synchronously and is shared across both effect invocations of the
+  // same render.
+  const flashedRef = useRef(false)
+
+  // Flash server-provided notifications on first mount only.
+  useEffect(() => {
+    if (flashedRef.current) return
+    flashedRef.current = true
+    if (initialNotifications && initialNotifications.length > 0) {
+      setItems(prev => [...prev, ...initialNotifications])
+    }
+  }, [initialNotifications])
+
+  const notify = useCallback<ToasterContextValue['notify']>((n) => {
+    const id = (n as NotificationMeta).id ?? clientId()
+    setItems(prev => [...prev, { ...(n as NotificationMeta), id }])
+  }, [])
+
+  const dismiss = useCallback((id: string) => {
+    setItems(prev => prev.filter(x => x.id !== id))
+  }, [])
+
+  return (
+    <ToasterContext.Provider value={{ notify }}>
+      {children}
+      {/* Stack — fixed bottom-right, click-through unless toast hovered. */}
+      <div className="pointer-events-none fixed bottom-4 right-4 z-[100] flex w-[calc(100vw-2rem)] max-w-sm flex-col gap-2">
+        {items.map(item => (
+          <ToastItem key={item.id} item={item} onDismiss={() => dismiss(item.id)} />
+        ))}
+      </div>
+    </ToasterContext.Provider>
+  )
+}
+
+/** Programmatic notify hook for client-side triggers (form submits,
+ * client-only handlers, etc.). Falls through silently when no
+ * ToasterProvider is mounted. */
+export function useToast(): ToasterContextValue {
+  return useContext(ToasterContext)
+}

package/src/react/UserMenu.tsx

@@ -0,0 +1,196 @@
+'use client'
+
+import React from 'react'
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuLabel,
+  DropdownMenuSeparator,
+  DropdownMenuTrigger,
+} from './ui/dropdown-menu.js'
+import { useIconFor } from './icon-context.js'
+import type { UserMenuMeta } from '../pageData.js'
+
+/**
+ * Top-right user dropdown — avatar / initials trigger that opens to
+ * the configured user-menu items + a separator + the optional sign-out
+ * entry. Renders nothing when `userMenu` is null (no logged-in user).
+ *
+ * Sign-out renders as a `<form>` so CSRF middleware downstream can
+ * verify the request. `method: 'GET'` falls back to a plain `<a>`-style
+ * link when the app's logout endpoint is purely redirect-based.
+ */
+export function UserMenu({
+  userMenu,
+  before,
+  after,
+}: {
+  userMenu: UserMenuMeta | null | undefined
+  /** Render-hook slot mounted at the top of the dropdown (above the
+   *  user-identity label). Pass `<RenderHookSlot
+   *  name="panels::user-menu.before" />`. */
+  before?:  React.ReactNode
+  /** Render-hook slot mounted at the bottom of the dropdown (above the
+   *  sign-out separator when present). Pass `<RenderHookSlot
+   *  name="panels::user-menu.after" />`. */
+  after?:   React.ReactNode
+}) {
+  if (!userMenu) return null
+  const { user, items, signOut } = userMenu
+
+  const displayName = user.name ?? user.email ?? 'Account'
+  const initials = computeInitials(user.name ?? user.email)
+
+  const avatarProps: { avatar?: string; initials: string; alt: string } = { initials, alt: displayName }
+  if (user.avatar !== undefined) avatarProps.avatar = user.avatar
+
+  return (
+    <DropdownMenu>
+      <DropdownMenuTrigger
+        className="inline-flex items-center gap-2 rounded-md p-1 text-sm hover:bg-accent hover:text-accent-foreground transition-colors focus:outline-none"
+        aria-label="User menu"
+      >
+        <Avatar {...avatarProps} />
+      </DropdownMenuTrigger>
+      <DropdownMenuContent align="end" className="min-w-56">
+        {before}
+        <DropdownMenuLabel className="flex flex-col gap-0.5">
+          {user.name && <span className="font-medium">{user.name}</span>}
+          {user.email && (
+            <span className="text-xs text-muted-foreground truncate">{user.email}</span>
+          )}
+          {!user.name && !user.email && (
+            <span className="font-medium">Account</span>
+          )}
+        </DropdownMenuLabel>
+        {items.length > 0 && <DropdownMenuSeparator />}
+        {items.map(item => (
+          <UserMenuItemRow key={item.name} item={item} />
+        ))}
+        {after}
+        {signOut && (
+          <>
+            <DropdownMenuSeparator />
+            <SignOutItem signOut={signOut} />
+          </>
+        )}
+      </DropdownMenuContent>
+    </DropdownMenu>
+  )
+}
+
+function UserMenuItemRow({ item }: { item: NonNullable<UserMenuMeta['items']>[number] }) {
+  const Icon = useIconFor(item.icon)
+  const destructive = item.color === 'destructive'
+  const target  = item.openInNewTab ? '_blank' : undefined
+  const rel     = item.openInNewTab ? 'noopener noreferrer' : undefined
+
+  // No URL → render as a plain disabled-looking row (rare; usually
+  // every item has a destination). Items without a URL still appear
+  // for consumers who want a label-only entry (e.g. environment hint).
+  if (!item.url) {
+    return (
+      <DropdownMenuItem destructive={destructive} disabled>
+        {Icon && <Icon aria-hidden="true" />}
+        <span>{item.label}</span>
+      </DropdownMenuItem>
+    )
+  }
+
+  return (
+    <DropdownMenuItem
+      destructive={destructive}
+      render={<a href={item.url} target={target} rel={rel} />}
+    >
+      {Icon && <Icon aria-hidden="true" />}
+      <span>{item.label}</span>
+    </DropdownMenuItem>
+  )
+}
+
+function SignOutItem({ signOut }: { signOut: NonNullable<UserMenuMeta['signOut']> }) {
+  const formRef = React.useRef<HTMLFormElement | null>(null)
+
+  if (signOut.method === 'GET') {
+    return (
+      <DropdownMenuItem destructive render={<a href={signOut.url} />}>
+        <SignOutIcon />
+        <span>{signOut.label}</span>
+      </DropdownMenuItem>
+    )
+  }
+  // POST: render a hidden form alongside the menu item; the item's
+  // click submits it. CSRF middleware sees a real POST navigation.
+  // `closeOnClick: false` is unnecessary — Base UI closes after the
+  // click handler runs, but the synchronous `requestSubmit()` triggers
+  // a full-page navigation which trumps the close animation.
+  return (
+    <>
+      <form ref={formRef} method="post" action={signOut.url} className="hidden" />
+      <DropdownMenuItem
+        destructive
+        onClick={() => formRef.current?.requestSubmit()}
+      >
+        <SignOutIcon />
+        <span>{signOut.label}</span>
+      </DropdownMenuItem>
+    </>
+  )
+}
+
+function Avatar({ avatar, initials, alt }: { avatar?: string; initials: string; alt: string }) {
+  if (avatar) {
+    return (
+      <img
+        src={avatar}
+        alt={alt}
+        className="size-7 rounded-full object-cover"
+      />
+    )
+  }
+  return (
+    <span
+      aria-hidden="true"
+      className="inline-flex size-7 items-center justify-center rounded-full bg-primary text-primary-foreground text-xs font-medium"
+    >
+      {initials}
+    </span>
+  )
+}
+
+function SignOutIcon() {
+  return (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      width="16"
+      height="16"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+    >
+      <path d="M9 21H5a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2h4" />
+      <polyline points="16 17 21 12 16 7" />
+      <line x1="21" x2="9" y1="12" y2="12" />
+    </svg>
+  )
+}
+
+function computeInitials(source: string | undefined): string {
+  if (!source) return '?'
+  const trimmed = source.trim()
+  if (!trimmed) return '?'
+  // Email → first two letters of the local-part.
+  if (trimmed.includes('@')) {
+    return trimmed.slice(0, 2).toUpperCase()
+  }
+  // Name → first letter of the first two whitespace-split tokens.
+  const parts = trimmed.split(/\s+/).filter(Boolean)
+  if (parts.length === 0) return '?'
+  if (parts.length === 1) return parts[0]!.slice(0, 2).toUpperCase()
+  return (parts[0]!.charAt(0) + parts[1]!.charAt(0)).toUpperCase()
+}

package/src/react/WidgetDataContext.tsx

@@ -0,0 +1,157 @@
+import React, { createContext, useCallback, useContext, useEffect, useRef, useState } from 'react'
+
+/**
+ * Plan #15 — runtime-side context for the per-widget data map shipped
+ * alongside `schemaData`. SchemaRenderer wraps its children in
+ * `WidgetDataProvider` so widget renderers can look up their initial
+ * payload by id (`useInitialWidgetData(id)`) and run polling fetches
+ * (`useWidgetData(meta)`).
+ *
+ * The "initial payload" is whatever the server stamped under
+ * `_widgetData[id]`:
+ *   - lazy widgets stamp `null` (renderer renders skeleton + fetches),
+ *   - eager widgets stamp the resolved payload directly,
+ *   - per-widget hook errors stamp `{ error: '<message>' }`.
+ *
+ * `useWidgetData(meta)` is the high-level hook that owns:
+ *   - reading the initial payload,
+ *   - kicking off the lazy-mount fetch when the initial is `null`,
+ *   - setInterval polling when `meta.poll` is set,
+ *   - pause polling while the document is hidden,
+ *   - latest-wins race handling so a slow request can't overwrite a
+ *     fresh one (mirrors the form-state seq pattern).
+ */
+
+type WidgetDataMap = Record<string, unknown>
+
+const WidgetDataContext = createContext<WidgetDataMap>({})
+
+export interface WidgetDataProviderProps {
+  data?:    WidgetDataMap
+  children: React.ReactNode
+}
+
+export function WidgetDataProvider({ data, children }: WidgetDataProviderProps) {
+  return (
+    <WidgetDataContext.Provider value={data ?? {}}>
+      {children}
+    </WidgetDataContext.Provider>
+  )
+}
+
+/** Read the server-stamped initial payload for one widget. Returns
+ *  `undefined` outside a provider — callers fall back to lazy-loading. */
+export function useInitialWidgetData(id: string): unknown {
+  return useContext(WidgetDataContext)[id]
+}
+
+/** Wire-shape of the polling-endpoint response. */
+interface WidgetFetchResponse {
+  ok:         true
+  data:       unknown
+  timestamp?: number
+}
+
+interface WidgetFetchFailure {
+  ok:     false
+  error?: string
+  status?: number
+}
+
+export interface WidgetState {
+  /** Resolved payload — same shape as whatever `getStats` / `getData`
+   *  returned. `null` means "not yet loaded" (still in skeleton). */
+  data:      unknown
+  /** Latest error message from the polling endpoint. Cleared on a
+   *  successful fetch. */
+  error:     string | null
+  /** Convenience flag for skeleton rendering — true while we have no
+   *  data and no error yet. */
+  isLoading: boolean
+  /** Manual re-fetch (used by per-widget filter dropdowns later). */
+  refetch:   (filter?: string) => void
+}
+
+export interface WidgetMetaLike {
+  id?:        unknown
+  lazy?:      unknown
+  poll?:      unknown
+  widgetUrl?: unknown
+}
+
+/**
+ * Manage one widget's data lifecycle from `meta`.
+ *
+ * - Initial paint: read `_widgetData[id]` from context.
+ * - Lazy mount fetch: when initial is `null` and we have a `widgetUrl`,
+ *   fire a one-shot POST.
+ * - Polling: when `meta.poll` is set, setInterval at that cadence.
+ *   Skip ticks while `document.visibilityState !== 'visible'` so an
+ *   inactive tab doesn't hammer the server.
+ * - Latest-wins: each fetch increments `seqRef`; stale responses drop.
+ */
+export function useWidgetData(meta: WidgetMetaLike): WidgetState {
+  const id    = String(meta.id ?? '')
+  const lazy  = Boolean(meta.lazy)
+  const poll  = typeof meta.poll      === 'number' ? meta.poll      : undefined
+  const url   = typeof meta.widgetUrl === 'string' ? meta.widgetUrl : undefined
+
+  const initial = useInitialWidgetData(id)
+  // Treat the server-stamped error sentinel as a recoverable error
+  // rather than rendered data: the client can re-fetch and the error
+  // banner clears.
+  const initialError =
+    initial && typeof initial === 'object' && initial !== null && 'error' in initial
+      ? String((initial as { error: unknown }).error)
+      : null
+
+  const [data,  setData]  = useState<unknown>(initialError ? null : initial)
+  const [error, setError] = useState<string | null>(initialError)
+  const seqRef = useRef(0)
+
+  const fetchOnce = useCallback(async (filter?: string) => {
+    if (!url) return
+    const seq = ++seqRef.current
+    try {
+      const res  = await fetch(url, {
+        method:  'POST',
+        headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
+        body:    JSON.stringify(filter !== undefined ? { filter } : {}),
+      })
+      const json = await res.json() as WidgetFetchResponse | WidgetFetchFailure
+      if (seq !== seqRef.current) return // raced — drop stale response
+      if (json.ok) {
+        setData(json.data)
+        setError(null)
+      } else {
+        setError(json.error ?? `Request failed with status ${res.status}`)
+      }
+    } catch (e) {
+      if (seq !== seqRef.current) return
+      setError(e instanceof Error ? e.message : 'Widget failed to load')
+    }
+  }, [url])
+
+  // Lazy first-paint fetch.
+  useEffect(() => {
+    if (lazy && data === null && url && !error) fetchOnce()
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- run once on mount
+  }, [])
+
+  // Polling — re-fetch on the configured interval, paused when tab hidden.
+  useEffect(() => {
+    if (!poll || !url) return
+    const handle = window.setInterval(() => {
+      if (typeof document !== 'undefined' && document.visibilityState !== 'visible') return
+      fetchOnce()
+    }, poll * 1000)
+    return () => window.clearInterval(handle)
+  }, [poll, url, fetchOnce])
+
+  return {
+    data,
+    error,
+    isLoading: data === null && !error,
+    refetch:   fetchOnce,
+  }
+}