@pilotiq/pilotiq 0.1.0

package/src/react/layouts/SidebarLayout.tsx

@@ -0,0 +1,239 @@
+import React from 'react'
+import {
+  Sidebar,
+  SidebarContent,
+  SidebarFooter,
+  SidebarGroup,
+  SidebarGroupContent,
+  SidebarGroupLabel,
+  SidebarHeader,
+  SidebarInset,
+  SidebarMenu,
+  SidebarMenuBadge,
+  SidebarMenuButton,
+  SidebarMenuItem,
+  SidebarMenuSub,
+  SidebarMenuSubButton,
+  SidebarMenuSubItem,
+  SidebarProvider,
+  SidebarRail,
+  SidebarTrigger,
+} from '../ui/sidebar.js'
+import { Separator } from '../ui/separator.js'
+import { ThemeToggle } from '../ThemeToggle.js'
+import { SearchTrigger } from '../SearchTrigger.js'
+import { UserMenu } from '../UserMenu.js'
+import { NotificationBell } from '../NotificationBell.js'
+import { RightSidebarTrigger } from '../RightSidebarTrigger.js'
+import { RenderHookSlot } from '../RenderHookSlot.js'
+import type { AppShellProps } from '../AppShell.js'
+import { useIconFor } from '../icon-context.js'
+import type { SerializedIcon } from '../../icons/types.js'
+import type { NavItem } from '../../pageData.js'
+import type { NavigationBadgeColor } from '../../Resource.js'
+import { cn } from '../utils.js'
+
+function NavIcon({ value }: { value: SerializedIcon | undefined }) {
+  const Icon = useIconFor(value)
+  if (!Icon) return null
+  return <Icon className="size-4" aria-hidden="true" />
+}
+
+/** Tailwind utility map shared with `ListTab.badgeColor` so badges read
+ *  consistently across the admin panel. */
+const BADGE_COLOR: Record<NavigationBadgeColor, string> = {
+  default:     'bg-muted text-muted-foreground',
+  primary:     'bg-primary/10 text-primary',
+  success:     'bg-emerald-500/10 text-emerald-600 dark:text-emerald-400',
+  warning:     'bg-amber-500/10  text-amber-600  dark:text-amber-400',
+  destructive: 'bg-red-500/10    text-red-600    dark:text-red-400',
+  info:        'bg-sky-500/10    text-sky-600    dark:text-sky-400',
+}
+
+function Badge({ value, color }: { value: string | undefined; color: NavigationBadgeColor | undefined }) {
+  if (value === undefined) return null
+  return (
+    <SidebarMenuBadge className={cn('px-1.5 rounded-md', BADGE_COLOR[color ?? 'default'])}>
+      {value}
+    </SidebarMenuBadge>
+  )
+}
+
+/**
+ * Active-link match is a longest-prefix walk. The dashboard URL (e.g.
+ * `/admin`) is a prefix of every other panel URL, so we only return
+ * "active" for it on an exact match. Otherwise we accept the URL as a
+ * prefix of `pathname` if it is followed by `/` or end-of-string —
+ * `/admin/users` should not light up `/admin/user`.
+ */
+function isActive(url: string, pathname: string | undefined, basePath: string): boolean {
+  if (!pathname) return false
+  if (url === basePath) return pathname === basePath
+  if (url === pathname) return true
+  return pathname.startsWith(url + '/')
+}
+
+/** Group nav items by `group`, preserving the order each group's first
+ *  member appeared in the (already-sorted) flat list. Items without a
+ *  group land in a leading unnamed bucket. */
+function groupItems(items: NavItem[]): Array<{ group: string | undefined; items: NavItem[] }> {
+  const order: Array<string | undefined> = []
+  const buckets = new Map<string | undefined, NavItem[]>()
+  for (const it of items) {
+    const key = it.group
+    if (!buckets.has(key)) {
+      buckets.set(key, [])
+      order.push(key)
+    }
+    buckets.get(key)!.push(it)
+  }
+  return order.map(g => ({ group: g, items: buckets.get(g)! }))
+}
+
+function NavTree({
+  items,
+  pathname,
+  basePath,
+}: {
+  items:     NavItem[]
+  pathname:  string | undefined
+  basePath:  string
+}) {
+  return (
+    <SidebarMenu>
+      {items.map(it => {
+        const active = isActive(it.url, pathname, basePath)
+        return (
+          <SidebarMenuItem key={it.name}>
+            <SidebarMenuButton
+              isActive={active}
+              render={<a href={it.url} />}
+              tooltip={it.label}
+            >
+              <NavIcon value={it.icon} />
+              <span>{it.label}</span>
+              <Badge value={it.badge} color={it.badgeColor} />
+            </SidebarMenuButton>
+            {it.children && it.children.length > 0 && (
+              <SidebarMenuSub>
+                {it.children.map(child => {
+                  const childActive = isActive(child.url, pathname, basePath)
+                  return (
+                    <SidebarMenuSubItem key={child.name}>
+                      <SidebarMenuSubButton
+                        isActive={childActive}
+                        render={<a href={child.url} />}
+                      >
+                        <NavIcon value={child.icon} />
+                        <span>{child.label}</span>
+                        <Badge value={child.badge} color={child.badgeColor} />
+                      </SidebarMenuSubButton>
+                    </SidebarMenuSubItem>
+                  )
+                })}
+              </SidebarMenuSub>
+            )}
+          </SidebarMenuItem>
+        )
+      })}
+    </SidebarMenu>
+  )
+}
+
+export function SidebarLayout({ panel, basePath, currentPath, children }: AppShellProps) {
+  const title = panel.branding?.title ?? panel.name
+  const groups = groupItems(panel.navigation ?? [])
+  const hooks = panel.renderHooks
+  const dn = panel.databaseNotifications
+  const bellInTopbar  = dn && dn.position === 'topbar'
+  const bellInSidebar = dn && dn.position === 'sidebar'
+
+  return (
+    <SidebarProvider>
+      <Sidebar variant="inset" collapsible="icon">
+        <SidebarHeader>
+          <RenderHookSlot name="panels::sidebar.start" hooks={hooks} />
+          <SidebarMenu>
+            <SidebarMenuItem>
+              <SidebarMenuButton size="lg" render={<a href={basePath} />} tooltip={title}>
+                <div className="flex aspect-square size-8 items-center justify-center rounded-lg bg-sidebar-primary text-sidebar-primary-foreground">
+                  {panel.branding?.logo
+                    ? <img src={panel.branding.logo} alt={title} className="size-4" />
+                    : <span className="text-xs font-bold">{title.charAt(0).toUpperCase()}</span>
+                  }
+                </div>
+                <div className="grid flex-1 text-start text-sm leading-tight">
+                  <span className="truncate font-semibold">{title}</span>
+                </div>
+              </SidebarMenuButton>
+            </SidebarMenuItem>
+          </SidebarMenu>
+        </SidebarHeader>
+
+        <SidebarContent>
+          <RenderHookSlot name="panels::sidebar.nav.start" hooks={hooks} />
+          {groups.map((g, idx) => (
+            <SidebarGroup key={g.group ?? `__top__${idx}`}>
+              {g.group !== undefined && <SidebarGroupLabel>{g.group}</SidebarGroupLabel>}
+              <SidebarGroupContent>
+                <NavTree items={g.items} pathname={currentPath} basePath={basePath} />
+              </SidebarGroupContent>
+            </SidebarGroup>
+          ))}
+          <RenderHookSlot name="panels::sidebar.nav.end" hooks={hooks} />
+        </SidebarContent>
+
+        <SidebarFooter>
+          <RenderHookSlot name="panels::sidebar.footer" hooks={hooks} />
+          {bellInSidebar && (
+            <SidebarMenu>
+              <SidebarMenuItem>
+                <div className="flex items-center justify-between px-2 py-1">
+                  <span className="text-xs text-muted-foreground">Notifications</span>
+                  <NotificationBell meta={dn} />
+                </div>
+              </SidebarMenuItem>
+            </SidebarMenu>
+          )}
+          {panel.themeEditor && (
+            <SidebarMenu>
+              <SidebarMenuItem>
+                <SidebarMenuButton render={<a href={`${basePath}/theme`} />} tooltip="Theme">
+                  <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"><circle cx="13.5" cy="6.5" r="2.5"/><path d="M17.5 10.5 19 12l-5.5 5.5"/><circle cx="8.5" cy="8.5" r="2.5"/><path d="M5 12 2.5 14.5 8 20l2.5-2.5"/><path d="m6 18 4-4"/></svg>
+                  <span>Theme</span>
+                </SidebarMenuButton>
+              </SidebarMenuItem>
+            </SidebarMenu>
+          )}
+        </SidebarFooter>
+        <SidebarRail />
+      </Sidebar>
+
+      <SidebarInset>
+        <header className="sticky top-0 z-10 flex h-14 shrink-0 items-center gap-2">
+          <div className="flex flex-1 items-center gap-2 px-3">
+            <SidebarTrigger />
+            <Separator orientation="vertical" className="me-2 data-[orientation=vertical]:h-4" />
+            <RenderHookSlot name="panels::topbar.start" hooks={hooks} />
+            <SearchTrigger />
+          </div>
+          <div className="flex items-center gap-1 px-3">
+            <ThemeToggle />
+            {bellInTopbar && <NotificationBell meta={dn} />}
+            <RightSidebarTrigger />
+            <UserMenu
+              userMenu={panel.userMenu}
+              before={<RenderHookSlot name="panels::user-menu.before" hooks={hooks} />}
+              after={<RenderHookSlot name="panels::user-menu.after"  hooks={hooks} />}
+            />
+            <RenderHookSlot name="panels::topbar.end" hooks={hooks} />
+          </div>
+        </header>
+        <div className="flex flex-1 flex-col px-4 pb-4">
+          {children}
+          <RenderHookSlot name="panels::footer" hooks={hooks} />
+        </div>
+      </SidebarInset>
+    </SidebarProvider>
+  )
+}

package/src/react/layouts/TopbarLayout.tsx

@@ -0,0 +1,245 @@
+import React from 'react'
+import { Separator } from '../ui/separator.js'
+import { ThemeToggle } from '../ThemeToggle.js'
+import { SearchTrigger } from '../SearchTrigger.js'
+import { UserMenu } from '../UserMenu.js'
+import { NotificationBell } from '../NotificationBell.js'
+import { RightSidebarTrigger } from '../RightSidebarTrigger.js'
+import { RenderHookSlot } from '../RenderHookSlot.js'
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuTrigger,
+} from '../ui/dropdown-menu.js'
+import type { AppShellProps } from '../AppShell.js'
+import { useIconFor } from '../icon-context.js'
+import type { SerializedIcon } from '../../icons/types.js'
+import type { NavItem } from '../../pageData.js'
+import type { NavigationBadgeColor } from '../../Resource.js'
+import { cn } from '../utils.js'
+
+function NavIcon({ value }: { value: SerializedIcon | undefined }) {
+  const Icon = useIconFor(value)
+  if (!Icon) return null
+  return <Icon className="size-4" aria-hidden="true" />
+}
+
+const BADGE_COLOR: Record<NavigationBadgeColor, string> = {
+  default:     'bg-muted text-muted-foreground',
+  primary:     'bg-primary/10 text-primary',
+  success:     'bg-emerald-500/10 text-emerald-600 dark:text-emerald-400',
+  warning:     'bg-amber-500/10  text-amber-600  dark:text-amber-400',
+  destructive: 'bg-red-500/10    text-red-600    dark:text-red-400',
+  info:        'bg-sky-500/10    text-sky-600    dark:text-sky-400',
+}
+
+function Badge({ value, color }: { value: string | undefined; color: NavigationBadgeColor | undefined }) {
+  if (value === undefined) return null
+  return (
+    <span className={cn('ms-1 inline-flex items-center justify-center rounded-md px-1.5 text-xs', BADGE_COLOR[color ?? 'default'])}>
+      {value}
+    </span>
+  )
+}
+
+function isActive(url: string, pathname: string | undefined, basePath: string): boolean {
+  if (!pathname) return false
+  if (url === basePath) return pathname === basePath
+  if (url === pathname) return true
+  return pathname.startsWith(url + '/')
+}
+
+const linkBase =
+  'flex items-center gap-1.5 px-3 py-1.5 rounded-md text-sm whitespace-nowrap transition-colors'
+const linkIdle =
+  'text-muted-foreground hover:bg-accent hover:text-accent-foreground'
+const linkActive =
+  'bg-accent text-accent-foreground'
+
+/** Bare item: a single nav link with no children. */
+function FlatLink({ item, pathname, basePath }: { item: NavItem; pathname: string | undefined; basePath: string }) {
+  return (
+    <a
+      href={item.url}
+      className={cn(linkBase, isActive(item.url, pathname, basePath) ? linkActive : linkIdle)}
+    >
+      <NavIcon value={item.icon} />
+      <span>{item.label}</span>
+      <Badge value={item.badge} color={item.badgeColor} />
+    </a>
+  )
+}
+
+/**
+ * Item with children: render as a dropdown trigger; the parent's own URL
+ * becomes the first menu entry so users can still navigate to it.
+ */
+function ParentDropdown({ item, pathname, basePath }: { item: NavItem; pathname: string | undefined; basePath: string }) {
+  return (
+    <DropdownMenu>
+      <DropdownMenuTrigger
+        className={cn(linkBase, isActive(item.url, pathname, basePath) ? linkActive : linkIdle)}
+      >
+        <NavIcon value={item.icon} />
+        <span>{item.label}</span>
+        <Badge value={item.badge} color={item.badgeColor} />
+      </DropdownMenuTrigger>
+      <DropdownMenuContent align="start">
+        <DropdownMenuItem render={<a href={item.url} />}>
+          <NavIcon value={item.icon} />
+          <span>{item.label}</span>
+        </DropdownMenuItem>
+        {item.children!.map(c => (
+          <DropdownMenuItem key={c.name} render={<a href={c.url} />}>
+            <NavIcon value={c.icon} />
+            <span>{c.label}</span>
+            <Badge value={c.badge} color={c.badgeColor} />
+          </DropdownMenuItem>
+        ))}
+      </DropdownMenuContent>
+    </DropdownMenu>
+  )
+}
+
+/**
+ * Group dropdown: the group label triggers the menu; every member
+ * (and its children) renders as menu items.
+ */
+function GroupDropdown({
+  label,
+  items,
+  pathname,
+  basePath,
+}: {
+  label:    string
+  items:    NavItem[]
+  pathname: string | undefined
+  basePath: string
+}) {
+  const anyActive = items.some(it =>
+    isActive(it.url, pathname, basePath) ||
+    it.children?.some(c => isActive(c.url, pathname, basePath)),
+  )
+  return (
+    <DropdownMenu>
+      <DropdownMenuTrigger className={cn(linkBase, anyActive ? linkActive : linkIdle)}>
+        <span>{label}</span>
+      </DropdownMenuTrigger>
+      <DropdownMenuContent align="start">
+        {items.flatMap(it => {
+          const self = (
+            <DropdownMenuItem key={it.name} render={<a href={it.url} />}>
+              <NavIcon value={it.icon} />
+              <span>{it.label}</span>
+              <Badge value={it.badge} color={it.badgeColor} />
+            </DropdownMenuItem>
+          )
+          if (!it.children || it.children.length === 0) return [self]
+          return [
+            self,
+            ...it.children.map(c => (
+              <DropdownMenuItem key={`${it.name}/${c.name}`} render={<a href={c.url} />} className="ps-6">
+                <NavIcon value={c.icon} />
+                <span>{c.label}</span>
+                <Badge value={c.badge} color={c.badgeColor} />
+              </DropdownMenuItem>
+            )),
+          ]
+        })}
+      </DropdownMenuContent>
+    </DropdownMenu>
+  )
+}
+
+function groupItems(items: NavItem[]): Array<{ group: string | undefined; items: NavItem[] }> {
+  const order: Array<string | undefined> = []
+  const buckets = new Map<string | undefined, NavItem[]>()
+  for (const it of items) {
+    const key = it.group
+    if (!buckets.has(key)) {
+      buckets.set(key, [])
+      order.push(key)
+    }
+    buckets.get(key)!.push(it)
+  }
+  return order.map(g => ({ group: g, items: buckets.get(g)! }))
+}
+
+export function TopbarLayout({ panel, basePath, currentPath, children }: AppShellProps) {
+  const title = panel.branding?.title ?? panel.name
+  const groups = groupItems(panel.navigation ?? [])
+  const hooks = panel.renderHooks
+  // Topbar layout treats `position: 'sidebar'` as a fallback to topbar —
+  // no sidebar exists in this layout, so the bell rides in the topbar
+  // chrome regardless of the configured position.
+  const dn = panel.databaseNotifications
+
+  return (
+    <div className="flex flex-col h-screen bg-background text-foreground overflow-hidden">
+      <header className="h-14 shrink-0 border-b bg-card flex items-center gap-4 px-6">
+        <div className="flex items-center gap-2 me-2">
+          {panel.branding?.logo
+            ? <>
+                <img src={panel.branding.logo} alt={title} className="h-6 w-6" />
+                <span className="text-sm font-semibold">{title}</span>
+              </>
+            : <span className="text-sm font-semibold">{title}</span>
+          }
+        </div>
+        <Separator orientation="vertical" className="h-4" />
+        <RenderHookSlot name="panels::topbar.start" hooks={hooks} />
+        <nav className="flex items-center gap-1 flex-1 overflow-x-auto">
+          <a
+            href={basePath}
+            className={cn(linkBase, currentPath === basePath ? linkActive : linkIdle)}
+          >
+            Dashboard
+          </a>
+          {groups.map((g, idx) => {
+            if (g.group === undefined) {
+              return g.items.map(it => (
+                it.children && it.children.length > 0
+                  ? <ParentDropdown key={it.name} item={it} pathname={currentPath} basePath={basePath} />
+                  : <FlatLink     key={it.name} item={it} pathname={currentPath} basePath={basePath} />
+              ))
+            }
+            return (
+              <GroupDropdown
+                key={`${g.group}__${idx}`}
+                label={g.group}
+                items={g.items}
+                pathname={currentPath}
+                basePath={basePath}
+              />
+            )
+          })}
+          {panel.themeEditor && (
+            <a
+              href={`${basePath}/theme`}
+              className={cn(linkBase, currentPath === `${basePath}/theme` ? linkActive : linkIdle)}
+            >
+              Theme
+            </a>
+          )}
+        </nav>
+        <SearchTrigger />
+        <ThemeToggle />
+        {dn && <NotificationBell meta={dn} />}
+        <RightSidebarTrigger />
+        <UserMenu
+          userMenu={panel.userMenu}
+          before={<RenderHookSlot name="panels::user-menu.before" hooks={hooks} />}
+          after={<RenderHookSlot name="panels::user-menu.after"  hooks={hooks} />}
+        />
+        <RenderHookSlot name="panels::topbar.end" hooks={hooks} />
+      </header>
+      <div className="flex flex-1 overflow-hidden">
+        <main className="flex-1 overflow-y-auto p-6">
+          {children}
+          <RenderHookSlot name="panels::footer" hooks={hooks} />
+        </main>
+      </div>
+    </div>
+  )
+}

package/src/react/navigate.tsx

@@ -0,0 +1,37 @@
+import { createContext, useContext, type ReactNode } from 'react'
+
+export type NavigateFn = (url: string) => void | Promise<void>
+
+const NavigateContext = createContext<NavigateFn | null>(null)
+
+/**
+ * Provides an SPA navigation function to pilotiq components — `FilterSelect`
+ * uses it so changing a filter doesn't full-reload the page (the surrounding
+ * `<FilterPopover>` would unmount on reload, defeating "stay open across
+ * filter changes").
+ *
+ * The auto-generated Vike `+Layout.tsx` wires this with `navigate` from
+ * `vike/client/router`. Pilotiq itself does NOT import vike — keeps the
+ * package framework-agnostic for future non-vike consumers.
+ */
+export function NavigateProvider({
+  navigate,
+  children,
+}: {
+  navigate: NavigateFn
+  children: ReactNode
+}) {
+  return <NavigateContext.Provider value={navigate}>{children}</NavigateContext.Provider>
+}
+
+/**
+ * Returns a navigate fn. Falls back to `window.location.href = url` (full
+ * reload) when no provider is mounted, so callers don't have to branch.
+ */
+export function useNavigate(): NavigateFn {
+  const ctx = useContext(NavigateContext)
+  if (ctx) return ctx
+  return (url: string) => {
+    if (typeof window !== 'undefined') window.location.href = url
+  }
+}

package/src/react/registry.ts

@@ -0,0 +1,48 @@
+import type { ComponentType } from 'react'
+import type { ElementMeta } from '../schema/Element.js'
+
+/**
+ * Props every registered field renderer receives. The renderer owns how it
+ * wires the input value into form POST — typically via a hidden `<input>`.
+ *
+ * Kept narrow on purpose: the renderer reads everything else (rules, options,
+ * etc.) off `el` directly. Adding more discrete props here forces every
+ * registered renderer to accept them whether it cares or not.
+ */
+export interface FieldRendererProps {
+  el:            ElementMeta
+  name:          string
+  defaultValue:  unknown
+  required:      boolean
+  disabled:      boolean
+  placeholder:   string | undefined
+}
+
+const renderers = new Map<string, ComponentType<FieldRendererProps>>()
+
+/**
+ * Register a custom React component to render a `fieldType`. Used by external
+ * packages (e.g. `@pilotiq/tiptap`) to plug in input UIs without forcing
+ * pilotiq core to import their dependencies.
+ *
+ * Built-in field types (`text`, `textarea`, `select`, `toggle`, `date`, …)
+ * are handled by SchemaRenderer's internal switch and don't need to register.
+ * Calling `registerFieldRenderer` for a built-in fieldType wins — the registry
+ * is checked first.
+ *
+ * Call once at app boot (client-side). Re-calling with the same fieldType
+ * overwrites the previous registration, which is convenient for HMR.
+ */
+export function registerFieldRenderer(
+  fieldType: string,
+  Component: ComponentType<FieldRendererProps>,
+): void {
+  renderers.set(fieldType, Component)
+}
+
+/** Look up a registered renderer. Returns undefined for unregistered types. */
+export function getFieldRenderer(
+  fieldType: string,
+): ComponentType<FieldRendererProps> | undefined {
+  return renderers.get(fieldType)
+}

package/src/react/right-panel-registry.tsx

@@ -0,0 +1,47 @@
+import React, { createContext, useContext, type ComponentType } from 'react'
+import type { RightPanelProps } from '../RightPanel.js'
+
+/**
+ * Build-time right-panel manifest. Maps each registered contribution's
+ * `id` (e.g. `'ai.chat'`) to the React component the user passed as
+ * `render`. The Pilotiq Vite plugin emits this map by walking every
+ * panel's `cfg.rightPanels` and stamping `_rightPanels[c.id] = c.render`
+ * into `pages/(pilotiq)/_components.ts`.
+ *
+ * The body component never crosses the wire — only its tab-strip meta
+ * does (`RightPanelMeta`). The chrome (Phase C) calls
+ * `getRightPanelComponent(id)` to resolve a `RightPanelMeta.id` into
+ * the actual component at mount time.
+ *
+ * Sparse: when a panel has no contributions, the registry is `{}` and
+ * the chrome never mounts (server-side `RightSidebarMeta` is also
+ * absent in that case — defense in depth).
+ */
+export type RightPanelRegistry = Record<string, ComponentType<RightPanelProps>>
+
+const Ctx = createContext<RightPanelRegistry | undefined>(undefined)
+
+export function RightPanelRegistryProvider({
+  value,
+  children,
+}: {
+  value: RightPanelRegistry | undefined
+  children: React.ReactNode
+}) {
+  return <Ctx.Provider value={value}>{children}</Ctx.Provider>
+}
+
+/** Read the full registry (for chrome that wants to enumerate). */
+export function useRightPanelRegistry(): RightPanelRegistry | undefined {
+  return useContext(Ctx)
+}
+
+/**
+ * Look up a single registered body component by `id`. Returns
+ * `undefined` when the registry is missing or the id was never
+ * registered — the caller paints its own missing-component fallback.
+ */
+export function useRightPanelComponent(id: string): ComponentType<RightPanelProps> | undefined {
+  const registry = useContext(Ctx)
+  return registry?.[id]
+}