@pilotiq/pilotiq 0.7.1 → 0.8.0

package/src/react/component-slots.test.ts

@@ -0,0 +1,103 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+import { Pilotiq } from '../Pilotiq.js'
+import { isNavItemActive } from './component-slots.js'
+
+describe('Pilotiq.components({ nav, header, footer })', () => {
+  it('starts empty', () => {
+    const panel = Pilotiq.make('Admin')
+    assert.deepEqual(panel.getComponentSlots(), {})
+  })
+
+  it('stores a registered nav slot', () => {
+    const Nav = () => null
+    const panel = Pilotiq.make('Admin').components({ nav: Nav })
+    const slots = panel.getComponentSlots()
+    assert.equal(slots.nav, Nav)
+  })
+
+  it('stores a registered header slot', () => {
+    const Header = () => null
+    const panel = Pilotiq.make('Admin').components({ header: Header })
+    assert.equal(panel.getComponentSlots().header, Header)
+  })
+
+  it('stores a registered footer slot', () => {
+    const Footer = () => null
+    const panel = Pilotiq.make('Admin').components({ footer: Footer })
+    assert.equal(panel.getComponentSlots().footer, Footer)
+  })
+
+  it('merges across multiple calls — later wins per slot, unset keys preserved', () => {
+    const A = () => null
+    const B = () => null
+    const panel = Pilotiq.make('Admin')
+      .components({ nav: A })
+      .components({})            // empty object keeps existing
+      .components({ nav: B })    // overrides
+    assert.equal(panel.getComponentSlots().nav, B)
+  })
+
+  it('preserves unset slots when overriding only one slot', () => {
+    const Nav    = () => null
+    const Header = () => null
+    const Footer = () => null
+    const Nav2   = () => null
+    const panel = Pilotiq.make('Admin')
+      .components({ nav: Nav, header: Header, footer: Footer })
+      .components({ nav: Nav2 })     // only nav changes
+    const slots = panel.getComponentSlots()
+    assert.equal(slots.nav,    Nav2)
+    assert.equal(slots.header, Header)
+    assert.equal(slots.footer, Footer)
+  })
+
+  it('allows registering all three slots together', () => {
+    const Nav    = () => null
+    const Header = () => null
+    const Footer = () => null
+    const panel = Pilotiq.make('Admin')
+      .components({ nav: Nav, header: Header, footer: Footer })
+    const slots = panel.getComponentSlots()
+    assert.equal(slots.nav,    Nav)
+    assert.equal(slots.header, Header)
+    assert.equal(slots.footer, Footer)
+  })
+
+  it('survives plugin registration without interference', () => {
+    const Nav = () => null
+    const panel = Pilotiq.make('Admin')
+      .components({ nav: Nav })
+      .use({ name: 'noop', register() { /* no-op */ } })
+    assert.equal(panel.getComponentSlots().nav, Nav)
+  })
+})
+
+describe('isNavItemActive', () => {
+  const basePath = '/admin'
+
+  it('returns false when currentPath is undefined', () => {
+    assert.equal(isNavItemActive('/admin/users', undefined, basePath), false)
+  })
+
+  it('matches the dashboard URL only on exact equality', () => {
+    assert.equal(isNavItemActive(basePath, basePath, basePath), true)
+    // Dashboard URL is a prefix of every panel URL; it must NOT light up
+    // for non-root pages — otherwise it'd always read as active.
+    assert.equal(isNavItemActive(basePath, '/admin/users', basePath), false)
+  })
+
+  it('matches non-dashboard URLs on exact equality', () => {
+    assert.equal(isNavItemActive('/admin/users', '/admin/users', basePath), true)
+  })
+
+  it('matches non-dashboard URLs as a prefix followed by `/`', () => {
+    assert.equal(isNavItemActive('/admin/users', '/admin/users/42', basePath), true)
+    assert.equal(isNavItemActive('/admin/users', '/admin/users/42/edit', basePath), true)
+  })
+
+  it('does NOT match a sibling URL that shares a prefix without `/`', () => {
+    // `/admin/users` must not activate when on `/admin/user` (singular).
+    assert.equal(isNavItemActive('/admin/user', '/admin/users', basePath), false)
+  })
+})

package/src/react/component-slots.ts

@@ -0,0 +1,116 @@
+import type * as React from 'react'
+import type { NavItem } from '../pageData.js'
+
+/**
+ * Props passed to a component registered at `Pilotiq.components({ nav })`.
+ *
+ * The component owns the entire nav region — for `SidebarLayout` that
+ * means the `<SidebarContent>` body (the panel chrome's header / footer
+ * still render); for `TopbarLayout` that means the `<nav>` element
+ * between the brand cluster and the right-side controls.
+ *
+ * `navigation` is the pre-grouped, pre-sorted tree built by
+ * `panelInfo()` — same shape the default renderers consume — so a
+ * custom nav can opt into the framework's `navigationGroup` / `sort` /
+ * badge metadata for free, or ignore it and walk a custom tree.
+ */
+export interface NavComponentProps {
+  /**
+   * Pre-grouped navigation items. May be empty when nothing the user
+   * can access is registered. Items with `children` represent nested
+   * sub-navigation (the default sidebar renders these under
+   * `SidebarMenuSub`).
+   */
+  navigation: NavItem[]
+  /** Panel base path (e.g. `/admin`). */
+  basePath:   string
+  /** Current request pathname — undefined when not in a request scope
+   *  (e.g. unit-testing the layout standalone). */
+  currentPath?: string
+}
+
+/**
+ * Props passed to a component registered at `Pilotiq.components({ header })`.
+ *
+ * The component owns the entire `<header>` chrome bar — in `SidebarLayout`
+ * that's the top bar above the main content (sidebar trigger, search,
+ * theme toggle, bell, user menu); in `TopbarLayout` that's the *whole*
+ * topbar including the brand cluster and the nav region. Setting `header`
+ * on `TopbarLayout` makes the `nav` slot irrelevant for that layout —
+ * the consumer's header owns everything between page edges.
+ *
+ * Render hooks that splice INSIDE the default header
+ * (`panels::topbar.start`, `panels::topbar.end`, `panels::user-menu.before`,
+ * `panels::user-menu.after`) don't fire when the header is replaced —
+ * the surrounding container is gone, so there's nowhere to splice into.
+ * Hooks rooted outside the header (`panels::sidebar.start` / `.footer`,
+ * `panels::sidebar.nav.start` / `.end`, `panels::footer`) keep firing.
+ *
+ * Shape mirrors `NavComponentProps` so a header that wants to render
+ * the nav inline (the TopbarLayout case) can do so without juggling a
+ * second slot.
+ */
+export interface HeaderComponentProps {
+  /**
+   * Pre-grouped navigation items — same tree the `nav` slot receives.
+   * Header consumers that want to mount the topbar nav inline read
+   * this; sidebar-layout consumers can ignore it.
+   */
+  navigation: NavItem[]
+  /** Panel base path (e.g. `/admin`). */
+  basePath:   string
+  /** Current request pathname — undefined when not in a request scope. */
+  currentPath?: string
+}
+
+/**
+ * Props passed to a component registered at `Pilotiq.components({ footer })`.
+ *
+ * The component mounts as a `<footer>` element BELOW the main content
+ * area — outside the scrolling region in both layouts. It is a separate
+ * surface from the `panels::footer` render hook, which continues to
+ * fire INSIDE the main content area (use the hook to append per-page
+ * trailing chrome; use this slot for site-chrome that frames every
+ * page like a status bar or copyright row).
+ */
+export interface FooterComponentProps {
+  /** Panel base path (e.g. `/admin`). */
+  basePath:   string
+  /** Current request pathname — undefined when not in a request scope. */
+  currentPath?: string
+}
+
+/**
+ * Registry of build-time component overrides registered through
+ * `Pilotiq.components({ nav, header, footer, … })`. The Vite plugin
+ * harvests the actual React refs into `pages/(pilotiq)/_components.ts`
+ * and forwards them to `<AppShell>`; component refs never travel over
+ * the wire.
+ *
+ * The shape is open-ended so additional slots can land without a
+ * breaking change when a concrete consumer asks for them.
+ */
+export interface ComponentSlotRegistry {
+  nav?:    React.ComponentType<NavComponentProps>
+  header?: React.ComponentType<HeaderComponentProps>
+  footer?: React.ComponentType<FooterComponentProps>
+}
+
+/**
+ * Active-link match identical to the default sidebar's. Exported so
+ * custom nav components can reuse the framework's longest-prefix
+ * semantics: the dashboard URL (`basePath`) only matches on exact
+ * equality — otherwise it would light up on every panel page — and
+ * non-dashboard URLs match as a prefix followed by `/` or end-of-string
+ * so `/admin/users` doesn't activate `/admin/user`.
+ */
+export function isNavItemActive(
+  url:        string,
+  currentPath: string | undefined,
+  basePath:   string,
+): boolean {
+  if (!currentPath) return false
+  if (url === basePath) return currentPath === basePath
+  if (url === currentPath) return true
+  return currentPath.startsWith(url + '/')
+}

package/src/react/fields/BuilderInput.tsx

@@ -20,6 +20,18 @@ import {
   DEFAULT_CLONE,
   DEFAULT_DELETE,
 } from './rowChromeButton.js'
+import {
+  generateRowId, makeAccordionStorage, makeCollapsedStorage,
+} from './rowState.js'
+import { useRowReorderDnd } from './useRowReorderDnd.js'
+
+const collapsedStorage = makeCollapsedStorage('builder')
+const accordionStorage = makeAccordionStorage('builder')
+const initSeedCollapsed          = collapsedStorage.seed
+const writeCollapsedToStorage    = collapsedStorage.write
+const deleteCollapsedFromStorage = collapsedStorage.remove
+const readAccordionFromStorage   = accordionStorage.read
+const writeAccordionToStorage    = accordionStorage.write
 
 interface BlockShape {
   name:      string
@@ -288,42 +300,23 @@ export function BuilderInput({
   }
 
   // ── DnD state (skipped when buttonsOnly) ────────────────
-  const [dragId, setDragId] = useState<string | null>(null)
-  const [dropAt, setDropAt] = useState<number | null>(null)
-  const dndEnabled = reorderable && !buttonsOnly
-
-  const onRowDragStart = (id: string) => (e: React.DragEvent<HTMLDivElement>): void => {
-    if (!dndEnabled || disabled) return
-    setDragId(id)
-    e.dataTransfer.effectAllowed = 'move'
-    try { e.dataTransfer.setData('text/plain', id) } catch { /* IE quirk */ }
-  }
-
-  const onRowDragOver = (idx: number) => (e: React.DragEvent<HTMLDivElement>): void => {
-    if (!dndEnabled || disabled || dragId === null) return
-    e.preventDefault()
-    e.dataTransfer.dropEffect = 'move'
-    const rect      = e.currentTarget.getBoundingClientRect()
-    const aboveHalf = e.clientY < rect.top + rect.height / 2
-    setDropAt(aboveHalf ? idx : idx + 1)
-  }
-
-  const onRowDrop = (e: React.DragEvent<HTMLDivElement>): void => {
-    if (!dndEnabled || disabled || dragId === null || dropAt === null) {
-      setDragId(null); setDropAt(null); return
-    }
-    e.preventDefault()
-    setRows(prev => {
-      const fromIdx = prev.findIndex(r => r.id === dragId)
-      if (fromIdx < 0) return prev
-      return reorderRows(prev, fromIdx, dropAt)
-    })
-    setDragId(null); setDropAt(null)
-  }
-
-  const onRowDragEnd = (): void => {
-    setDragId(null); setDropAt(null)
-  }
+  const dndEnabled = reorderable && !buttonsOnly && !disabled
+  const {
+    dragId, dropAt,
+    onDragStart: onRowDragStart,
+    onDragOver:  onRowDragOver,
+    onDrop:      onRowDrop,
+    onDragEnd:   onRowDragEnd,
+  } = useRowReorderDnd({
+    enabled: dndEnabled,
+    onDrop: (fromId, at) => {
+      setRows(prev => {
+        const fromIdx = prev.findIndex(r => r.id === fromId)
+        if (fromIdx < 0) return prev
+        return reorderRows(prev, fromIdx, at)
+      })
+    },
+  })
 
   // ── Inner-field live re-resolve (mirrors RepeaterInput) ─
   const formState = useFormState()
@@ -949,84 +942,3 @@ function prefixFieldNames(el: ElementMeta, prefix: string): ElementMeta {
   return el
 }
 
-let _rowSeqFallback = 0
-function generateRowId(): string {
-  type CryptoLike = { randomUUID?: () => string }
-  const c = (globalThis as { crypto?: CryptoLike }).crypto
-  if (c?.randomUUID) return c.randomUUID()
-  return `row-${Date.now()}-${++_rowSeqFallback}`
-}
-
-function collapsedStorageKey(formId: string, name: string, rowId: string): string {
-  return `pilotiq.builder.${formId}.${name}.${rowId}`
-}
-
-function initSeedCollapsed(
-  rows:         RowState[],
-  formId:       string,
-  name:         string,
-  defaultValue: boolean,
-  collapsible:  boolean,
-): Record<string, boolean> {
-  if (!collapsible) return {}
-  const out: Record<string, boolean> = {}
-  for (const row of rows) {
-    out[row.id] = readCollapsedFromStorage(formId, name, row.id, defaultValue)
-  }
-  return out
-}
-
-function readCollapsedFromStorage(
-  formId:       string,
-  name:         string,
-  rowId:        string,
-  defaultValue: boolean,
-): boolean {
-  if (typeof window === 'undefined') return defaultValue
-  try {
-    const raw = window.localStorage.getItem(collapsedStorageKey(formId, name, rowId))
-    if (raw === null) return defaultValue
-    return raw === 'true'
-  } catch { return defaultValue }
-}
-
-function writeCollapsedToStorage(
-  formId: string,
-  name:   string,
-  rowId:  string,
-  value:  boolean,
-): void {
-  if (typeof window === 'undefined') return
-  try {
-    window.localStorage.setItem(collapsedStorageKey(formId, name, rowId), String(value))
-  } catch { /* quota exceeded; silent */ }
-}
-
-function deleteCollapsedFromStorage(formId: string, name: string, rowId: string): void {
-  if (typeof window === 'undefined') return
-  try { window.localStorage.removeItem(collapsedStorageKey(formId, name, rowId)) } catch { /* */ }
-}
-
-function accordionStorageKey(formId: string, name: string): string {
-  return `pilotiq.builder.${formId}.${name}.accordion`
-}
-
-/**
- * Read the persisted accordion-open row id. Mirror of
- * `RepeaterInput.readAccordionFromStorage` — `undefined` = no value
- * stored, `''` = explicitly all-collapsed, anything else = open row id.
- */
-function readAccordionFromStorage(formId: string, name: string): string | undefined {
-  if (typeof window === 'undefined') return undefined
-  try {
-    const raw = window.localStorage.getItem(accordionStorageKey(formId, name))
-    return raw === null ? undefined : raw
-  } catch { return undefined }
-}
-
-function writeAccordionToStorage(formId: string, name: string, openId: string | null): void {
-  if (typeof window === 'undefined') return
-  try {
-    window.localStorage.setItem(accordionStorageKey(formId, name), openId ?? '')
-  } catch { /* quota exceeded — fall back to in-memory only */ }
-}

package/src/react/fields/MarkdownInput.tsx

@@ -296,7 +296,6 @@ export function MarkdownInput({
           <div
             className="prose prose-sm dark:prose-invert max-w-none px-3 py-2"
             style={taStyle}
-            // eslint-disable-next-line react/no-danger
             dangerouslySetInnerHTML={{ __html: previewHtml || '<p class="text-muted-foreground italic">Nothing to preview</p>' }}
           />
         </>

package/src/react/fields/RepeaterInput.tsx

@@ -20,6 +20,18 @@ import {
   DEFAULT_DELETE,
 } from './rowChromeButton.js'
 import { syncRowGates } from './syncRowGates.js'
+import {
+  generateRowId, makeAccordionStorage, makeCollapsedStorage,
+} from './rowState.js'
+import { useRowReorderDnd } from './useRowReorderDnd.js'
+
+const collapsedStorage = makeCollapsedStorage('repeater')
+const accordionStorage = makeAccordionStorage('repeater')
+const initSeedCollapsed          = collapsedStorage.seed
+const writeCollapsedToStorage    = collapsedStorage.write
+const deleteCollapsedFromStorage = collapsedStorage.remove
+const readAccordionFromStorage   = accordionStorage.read
+const writeAccordionToStorage    = accordionStorage.write
 
 /**
  * Pure reorder helper — used by both the HTML5 DnD path and the
@@ -324,49 +336,22 @@ export function RepeaterInput({
   }
 
   // ── DnD state ───────────────────────────────────────────
-  // dragId  — the row being dragged, or null when no drag is active.
-  // dropAt  — the boundary slot the cursor is currently over
-  //           (range 0..rows.length); null when not over a valid drop target.
-  const [dragId, setDragId] = useState<string | null>(null)
-  const [dropAt, setDropAt] = useState<number | null>(null)
-
-  // Generic on `HTMLElement` so the same handlers wire onto a `<div>`
-  // row (card / grid layouts) AND a `<tr>` row (table layout). Concrete
-  // refinement happens at the consumer's prop boundary.
-  const onRowDragStart = (id: string) => (e: React.DragEvent<HTMLElement>): void => {
-    if (!reorderable || disabled) return
-    setDragId(id)
-    // dataTransfer needs *something* to register the drag in Firefox.
-    e.dataTransfer.effectAllowed = 'move'
-    try { e.dataTransfer.setData('text/plain', id) } catch { /* IE quirk; ignore */ }
-  }
-
-  const onRowDragOver = (idx: number) => (e: React.DragEvent<HTMLElement>): void => {
-    if (!reorderable || disabled || dragId === null) return
-    e.preventDefault()
-    e.dataTransfer.dropEffect = 'move'
-    // Drop above this row when cursor is in its top half, below when in its bottom half.
-    const rect      = e.currentTarget.getBoundingClientRect()
-    const aboveHalf = e.clientY < rect.top + rect.height / 2
-    setDropAt(aboveHalf ? idx : idx + 1)
-  }
-
-  const onRowDrop = (e: React.DragEvent<HTMLElement>): void => {
-    if (!reorderable || disabled || dragId === null || dropAt === null) {
-      setDragId(null); setDropAt(null); return
-    }
-    e.preventDefault()
-    setRows(prev => {
-      const fromIdx = prev.findIndex(r => r.id === dragId)
-      if (fromIdx < 0) return prev
-      return reorderRows(prev, fromIdx, dropAt)
-    })
-    setDragId(null); setDropAt(null)
-  }
-
-  const onRowDragEnd = (): void => {
-    setDragId(null); setDropAt(null)
-  }
+  const {
+    dragId, dropAt,
+    onDragStart: onRowDragStart,
+    onDragOver:  onRowDragOver,
+    onDrop:      onRowDrop,
+    onDragEnd:   onRowDragEnd,
+  } = useRowReorderDnd({
+    enabled: reorderable && !disabled,
+    onDrop: (fromId, at) => {
+      setRows(prev => {
+        const fromIdx = prev.findIndex(r => r.id === fromId)
+        if (fromIdx < 0) return prev
+        return reorderRows(prev, fromIdx, at)
+      })
+    },
+  })
 
   // ── Inner-field live re-resolve (Plan #14 v1.1) ─────────────
   // Inner Repeater inputs are uncontrolled (so reorder/clone preserves
@@ -487,7 +472,6 @@ export function RepeaterInput({
       <RepeaterTableLayout
         rows={rows}
         name={name}
-        formId={formId}
         disabled={disabled}
         columns={tableColumns}
         addLabel={addLabel}
@@ -939,7 +923,7 @@ function DropIndicator(): React.ReactElement {
  * stays stable across rows even when individual buttons disable.
  */
 function RepeaterTableLayout({
-  rows, name, formId: _formId, disabled, columns, addLabel, buttons, atMin, atMax,
+  rows, name, disabled, columns, addLabel, buttons, atMin, atMax,
   reorderable, cloneable,
   firstVisibleIdx, lastVisibleIdx, hasVisibleRow,
   dragId,
@@ -949,7 +933,6 @@ function RepeaterTableLayout({
 }: {
   rows:              RowState[]
   name:              string
-  formId:            string
   disabled:          boolean
   columns:           TableColumnShape[]
   addLabel:          string
@@ -1265,88 +1248,4 @@ function prefixFieldNames(el: ElementMeta, prefix: string): ElementMeta {
   return el
 }
 
-let _rowSeqFallback = 0
-function generateRowId(): string {
-  type CryptoLike = { randomUUID?: () => string }
-  const c = (globalThis as { crypto?: CryptoLike }).crypto
-  if (c?.randomUUID) return c.randomUUID()
-  return `row-${Date.now()}-${++_rowSeqFallback}`
-}
-
-function collapsedStorageKey(formId: string, name: string, rowId: string): string {
-  return `pilotiq.repeater.${formId}.${name}.${rowId}`
-}
-
-function initSeedCollapsed(
-  rows:         RowState[],
-  formId:       string,
-  name:         string,
-  defaultValue: boolean,
-  collapsible:  boolean,
-): Record<string, boolean> {
-  if (!collapsible) return {}
-  const out: Record<string, boolean> = {}
-  for (const row of rows) {
-    out[row.id] = readCollapsedFromStorage(formId, name, row.id, defaultValue)
-  }
-  return out
-}
-
-function readCollapsedFromStorage(
-  formId:       string,
-  name:         string,
-  rowId:        string,
-  defaultValue: boolean,
-): boolean {
-  if (typeof window === 'undefined') return defaultValue
-  try {
-    const raw = window.localStorage.getItem(collapsedStorageKey(formId, name, rowId))
-    if (raw === null) return defaultValue
-    return raw === 'true'
-  } catch { return defaultValue }
-}
-
-function writeCollapsedToStorage(
-  formId: string,
-  name:   string,
-  rowId:  string,
-  value:  boolean,
-): void {
-  if (typeof window === 'undefined') return
-  try {
-    window.localStorage.setItem(collapsedStorageKey(formId, name, rowId), String(value))
-  } catch { /* quota exceeded — fall back to in-memory only */ }
-}
-
-function deleteCollapsedFromStorage(formId: string, name: string, rowId: string): void {
-  if (typeof window === 'undefined') return
-  try {
-    window.localStorage.removeItem(collapsedStorageKey(formId, name, rowId))
-  } catch { /* ignore */ }
-}
-
-function accordionStorageKey(formId: string, name: string): string {
-  return `pilotiq.repeater.${formId}.${name}.accordion`
-}
-
-/**
- * Read the persisted accordion-open row id. Returns `undefined` when no
- * value is stored (so the caller can fall back to the default-open
- * heuristic). Returns `''` when the user explicitly closed every row —
- * the caller maps that to `null` openId.
- */
-function readAccordionFromStorage(formId: string, name: string): string | undefined {
-  if (typeof window === 'undefined') return undefined
-  try {
-    const raw = window.localStorage.getItem(accordionStorageKey(formId, name))
-    return raw === null ? undefined : raw
-  } catch { return undefined }
-}
-
-function writeAccordionToStorage(formId: string, name: string, openId: string | null): void {
-  if (typeof window === 'undefined') return
-  try {
-    window.localStorage.setItem(accordionStorageKey(formId, name), openId ?? '')
-  } catch { /* quota exceeded — fall back to in-memory only */ }
-}