@pilotiq/pilotiq 0.7.1 → 0.8.0

package/src/Pilotiq.ts

@@ -21,6 +21,11 @@ import {
   findDuplicateRightPanelId,
   type RightPanelContribution,
 } from './RightPanel.js'
+import type {
+  NavComponentProps,
+  HeaderComponentProps,
+  FooterComponentProps,
+} from './react/component-slots.js'
 
 export type PilotiqLayout = 'sidebar' | 'topbar'
 
@@ -240,6 +245,19 @@ export interface PilotiqConfig {
    * closest to the page tree (innermost wrap).
    */
   layoutProviders?: LayoutProviderComponent[]
+  /**
+   * Build-time component overrides for panel chrome slots. Registered
+   * via `Pilotiq.components({ nav })`. The Vite plugin harvests the
+   * actual React refs into `pages/(pilotiq)/_components.ts`; component
+   * refs never travel over the wire.
+   *
+   * v1 ships only the `nav` slot — full replacement of the sidebar's
+   * `<SidebarContent>` body and the topbar's `<nav>` element. Other
+   * slots (`header`, `footer`, …) will land when a concrete consumer
+   * asks; the shape is open-ended so additions don't break this
+   * surface.
+   */
+  components?:      ComponentSlots
   /**
    * AI suggestion mode — controls what happens when an AI agent calls a
    * write tool against a form field.
@@ -269,6 +287,42 @@ export type LayoutProviderComponent = React.ComponentType<{
   basePath?: string
 }>
 
+/**
+ * Chrome-slot overrides registered through `Pilotiq.components({ … })`.
+ *
+ * Three slots ship today:
+ *
+ * - `nav` — replaces the default nav tree (`<SidebarMenu>` body in
+ *   `SidebarLayout`, the `<nav>` cluster in `TopbarLayout`). Surrounding
+ *   chrome (branding header, render-hook splices, footer, sign-out
+ *   menu) stays.
+ * - `header` — replaces the whole `<header>` chrome bar. In
+ *   `SidebarLayout` that's the top bar with search / theme / bell /
+ *   user menu; in `TopbarLayout` that's the whole top region including
+ *   the brand cluster AND the nav (setting `header` makes `nav`
+ *   irrelevant in `TopbarLayout`). Render hooks that splice INSIDE the
+ *   default header (`panels::topbar.*`, `panels::user-menu.*`) don't
+ *   fire when the header is replaced — the surrounding container is
+ *   gone. The consumer reimplements the chrome controls they want
+ *   (import `<SearchTrigger>`, `<ThemeToggle>`, `<NotificationBell>`,
+ *   `<RightSidebarTrigger>`, `<UserMenu>` from `@pilotiq/pilotiq/react`).
+ * - `footer` — mounts a `<footer>` element BELOW the main content area
+ *   in both layouts (outside the scroll region). Separate from the
+ *   `panels::footer` render hook, which keeps firing inside the content
+ *   area for per-page trailing chrome.
+ *
+ * The shape is open-ended so additional slots can land without a
+ * breaking change when a concrete consumer asks for them.
+ */
+export interface ComponentSlots {
+  /** Component rendered in place of the default nav tree. */
+  nav?:    React.ComponentType<NavComponentProps>
+  /** Component rendered in place of the default `<header>` chrome. */
+  header?: React.ComponentType<HeaderComponentProps>
+  /** Component rendered as the panel footer, below the main content. */
+  footer?: React.ComponentType<FooterComponentProps>
+}
+
 export class Pilotiq {
   private config: PilotiqConfig
   private installedPlugins: PilotiqPlugin[] = []
@@ -776,6 +830,47 @@ export class Pilotiq {
     return this.config.layoutProviders ?? []
   }
 
+  /**
+   * Override one of pilotiq's built-in chrome slots with a custom React
+   * component. Calling twice merges — the latest registration wins per
+   * slot; unset keys preserve the prior value (so a plugin can override
+   * `nav` without clearing a host app's `footer`).
+   *
+   * Three slots ship today: `nav` (replaces the default nav tree),
+   * `header` (replaces the whole `<header>` chrome bar in both
+   * layouts — in `TopbarLayout` this subsumes the nav), and `footer`
+   * (mounts a `<footer>` below the main content area in both layouts).
+   * See {@link ComponentSlots} for the per-slot semantics and which
+   * render hooks compose vs. stop firing under each replacement.
+   *
+   * Component refs are harvested by the Vite plugin into
+   * `pages/(pilotiq)/_components.ts` — they never travel over the wire,
+   * so authoring inside the panel module (which is import-safe on both
+   * server and client) is the supported entry point.
+   *
+   * @example
+   * ```ts
+   * import { MyCustomSidebar } from './MyCustomSidebar.js'
+   *
+   * Pilotiq.make('Admin').components({ nav: MyCustomSidebar })
+   * ```
+   *
+   * The supplied component receives `{ navigation, basePath, currentPath }`
+   * — the same shape `panelInfo()` produces for the default renderers.
+   * Import `NavComponentProps` and `isNavItemActive` from
+   * `@pilotiq/pilotiq/react` to author a typed component that reuses
+   * the framework's longest-prefix active-link semantics.
+   */
+  components(slots: ComponentSlots): this {
+    this.config.components = { ...(this.config.components ?? {}), ...slots }
+    return this
+  }
+
+  /** @internal — read by the Vite plugin's `_components.ts` emitter. */
+  getComponentSlots(): Readonly<ComponentSlots> {
+    return this.config.components ?? {}
+  }
+
   /**
    * Set the panel-wide AI suggestion mode.
    *