@pilotiq/pilotiq 0.23.1 → 0.24.2

package/src/RenderHook.test.ts

@@ -1,252 +0,0 @@
-import { describe, it } from 'node:test'
-import assert from 'node:assert/strict'
-
-import { Pilotiq } from './Pilotiq.js'
-import { Resource } from './Resource.js'
-import { Page } from './Page.js'
-import { Heading } from './schema/Heading.js'
-import { Alert } from './schema/Alert.js'
-import { Form } from './elements/Form.js'
-import {
-  resolveRenderHooks,
-  CHROME_HOOK_NAMES,
-  type RenderHookContext,
-} from './RenderHook.js'
-import { panelInfo } from './pageData.js'
-
-class ArticleResource extends Resource {
-  static override label = 'Articles'
-  static override slug  = 'articles'
-  static override form() { return Form.make().schema([]) }
-}
-
-class OtherResource extends Resource {
-  static override label = 'Other'
-  static override slug  = 'other'
-  static override form() { return Form.make().schema([]) }
-}
-
-class HelpPage extends Page {
-  static override slug   = 'help'
-  static override label  = 'Help'
-  static override schema() { return [] }
-}
-
-const baseCtx: RenderHookContext = {
-  user:     null,
-  basePath: '/admin',
-  url:      '/admin',
-}
-
-describe('Pilotiq.renderHook()', () => {
-  it('appends entries in registration order', () => {
-    const panel = Pilotiq.make('admin')
-      .renderHook('panels::topbar.start', () => [Heading.make('A')])
-      .renderHook('panels::topbar.start', () => [Heading.make('B')])
-
-    const cfg = panel.getConfig()
-    assert.equal(cfg.renderHooks?.length, 2)
-    assert.equal(cfg.renderHooks?.[0]?.name, 'panels::topbar.start')
-    assert.equal(cfg.renderHooks?.[1]?.name, 'panels::topbar.start')
-  })
-
-  it('stores optional scope on the entry', () => {
-    const panel = Pilotiq.make('admin')
-      .renderHook('panels::topbar.start', () => [Heading.make('Scoped')], { resource: ArticleResource })
-
-    const cfg = panel.getConfig()
-    assert.equal(cfg.renderHooks?.[0]?.scope?.resource, ArticleResource)
-  })
-})
-
-describe('resolveRenderHooks()', () => {
-  it('returns an empty map when no entries match', async () => {
-    const panel = Pilotiq.make('admin')
-    const out = await resolveRenderHooks(
-      panel.getConfig().renderHooks ?? [],
-      ['panels::topbar.start'],
-      baseCtx,
-    )
-    assert.deepEqual(out, {})
-  })
-
-  it('returns ElementMeta[] keyed by hook name', async () => {
-    const panel = Pilotiq.make('admin')
-      .renderHook('panels::topbar.start', () => [Heading.make('Hello')])
-
-    const out = await resolveRenderHooks(
-      panel.getConfig().renderHooks!,
-      ['panels::topbar.start'],
-      baseCtx,
-    )
-
-    const slot = out['panels::topbar.start']
-    assert.ok(slot, 'slot present')
-    assert.equal(slot.length, 1)
-    assert.equal(slot[0]?.['type'], 'heading')
-  })
-
-  it('concats multiple hooks at the same slot in registration order', async () => {
-    const panel = Pilotiq.make('admin')
-      .renderHook('panels::body.start', () => [Heading.make('A')])
-      .renderHook('panels::body.start', () => [Heading.make('B')])
-
-    const out = await resolveRenderHooks(
-      panel.getConfig().renderHooks!,
-      ['panels::body.start'],
-      baseCtx,
-    )
-    const slot = out['panels::body.start']
-    assert.equal(slot?.length, 2)
-    assert.equal(slot?.[0]?.['content'], 'A')
-    assert.equal(slot?.[1]?.['content'], 'B')
-  })
-
-  it('drops entries whose function throws (fail closed) and keeps siblings', async () => {
-    const panel = Pilotiq.make('admin')
-      .renderHook('panels::body.start', () => { throw new Error('boom') })
-      .renderHook('panels::body.start', () => [Heading.make('Survivor')])
-
-    const out = await resolveRenderHooks(
-      panel.getConfig().renderHooks!,
-      ['panels::body.start'],
-      baseCtx,
-    )
-    assert.equal(out['panels::body.start']?.length, 1)
-    assert.equal(out['panels::body.start']?.[0]?.['content'], 'Survivor')
-  })
-
-  it('respects scope.resource — fires only when ctx.resource matches', async () => {
-    const panel = Pilotiq.make('admin')
-      .renderHook('panels::topbar.start', () => [Heading.make('ArticlesOnly')], { resource: ArticleResource })
-      .renderHook('panels::topbar.start', () => [Heading.make('Always')])
-
-    const onArticles = await resolveRenderHooks(
-      panel.getConfig().renderHooks!,
-      ['panels::topbar.start'],
-      { ...baseCtx, resource: ArticleResource },
-    )
-    assert.equal(onArticles['panels::topbar.start']?.length, 2)
-
-    const onOther = await resolveRenderHooks(
-      panel.getConfig().renderHooks!,
-      ['panels::topbar.start'],
-      { ...baseCtx, resource: OtherResource },
-    )
-    assert.equal(onOther['panels::topbar.start']?.length, 1)
-    assert.equal(onOther['panels::topbar.start']?.[0]?.['content'], 'Always')
-  })
-
-  it('respects scope.page', async () => {
-    const panel = Pilotiq.make('admin')
-      .renderHook('panels::page.start', () => [Heading.make('HelpOnly')], { page: HelpPage })
-
-    const onHelp = await resolveRenderHooks(
-      panel.getConfig().renderHooks!,
-      ['panels::page.start'],
-      { ...baseCtx, page: HelpPage },
-    )
-    assert.equal(onHelp['panels::page.start']?.length, 1)
-
-    const offHelp = await resolveRenderHooks(
-      panel.getConfig().renderHooks!,
-      ['panels::page.start'],
-      baseCtx,
-    )
-    assert.deepEqual(offHelp, {})
-  })
-
-  it('passes the resolved user into the hook callback', async () => {
-    const calls: unknown[] = []
-    const panel = Pilotiq.make('admin')
-      .renderHook('panels::topbar.start', (ctx) => {
-        calls.push(ctx.user)
-        return [Heading.make('seen')]
-      })
-
-    await resolveRenderHooks(
-      panel.getConfig().renderHooks!,
-      ['panels::topbar.start'],
-      { ...baseCtx, user: { name: 'Bob' } },
-    )
-    assert.deepEqual(calls, [{ name: 'Bob' }])
-  })
-
-  it('only resolves slots in the requested name list', async () => {
-    const panel = Pilotiq.make('admin')
-      .renderHook('panels::topbar.start', () => [Heading.make('top')])
-      .renderHook('panels::body.start',   () => [Heading.make('body')])
-
-    const out = await resolveRenderHooks(
-      panel.getConfig().renderHooks!,
-      ['panels::topbar.start'],
-      baseCtx,
-    )
-    assert.ok(out['panels::topbar.start'])
-    assert.equal(out['panels::body.start'], undefined)
-  })
-
-  it('CHROME_HOOK_NAMES covers every chrome slot expected by the layouts', () => {
-    // Snapshot test — if a layout starts mounting a new slot, this list
-    // must extend OR the slot must move into PAGE_HOOK_NAMES.
-    assert.ok(CHROME_HOOK_NAMES.includes('panels::body.start'))
-    assert.ok(CHROME_HOOK_NAMES.includes('panels::body.end'))
-    assert.ok(CHROME_HOOK_NAMES.includes('panels::topbar.start'))
-    assert.ok(CHROME_HOOK_NAMES.includes('panels::topbar.end'))
-    assert.ok(CHROME_HOOK_NAMES.includes('panels::sidebar.start'))
-    assert.ok(CHROME_HOOK_NAMES.includes('panels::sidebar.nav.start'))
-    assert.ok(CHROME_HOOK_NAMES.includes('panels::sidebar.nav.end'))
-    assert.ok(CHROME_HOOK_NAMES.includes('panels::sidebar.footer'))
-    assert.ok(CHROME_HOOK_NAMES.includes('panels::user-menu.before'))
-    assert.ok(CHROME_HOOK_NAMES.includes('panels::user-menu.after'))
-    assert.ok(CHROME_HOOK_NAMES.includes('panels::footer'))
-  })
-})
-
-describe('panelInfo() chrome render-hook resolution', () => {
-  it('omits panel.renderHooks when no entries match', async () => {
-    const panel = Pilotiq.make('admin')
-    const info = await panelInfo(panel)
-    assert.equal((info as { renderHooks?: unknown }).renderHooks, undefined)
-  })
-
-  it('attaches resolved chrome slots to panel.renderHooks', async () => {
-    const panel = Pilotiq.make('admin')
-      .renderHook('panels::topbar.start', () => [Alert.make('warn').warning()])
-
-    const info = await panelInfo(panel)
-    const hooks = (info as { renderHooks?: Record<string, unknown[]> }).renderHooks
-    assert.ok(hooks)
-    assert.ok(hooks['panels::topbar.start'])
-    assert.equal(hooks['panels::topbar.start']!.length, 1)
-  })
-
-  it('skips page-role hooks during chrome resolution', async () => {
-    const panel = Pilotiq.make('admin')
-      .renderHook('panels::resource.pages.list-records.table.before', () => [Heading.make('list')])
-      .renderHook('panels::topbar.start', () => [Heading.make('chrome')])
-
-    const info = await panelInfo(panel)
-    const hooks = (info as { renderHooks?: Record<string, unknown[]> }).renderHooks
-    assert.ok(hooks)
-    assert.ok(hooks['panels::topbar.start'])
-    assert.equal(hooks['panels::resource.pages.list-records.table.before'], undefined)
-  })
-
-  it('threads route.resource into the hook context for scoping', async () => {
-    const seen: Array<{ name: string }> = []
-    const panel = Pilotiq.make('admin')
-      .renderHook('panels::topbar.start', (ctx) => {
-        if (ctx.resource) seen.push({ name: ctx.resource.name })
-        return [Heading.make('x')]
-      }, { resource: ArticleResource })
-
-    await panelInfo(panel, undefined, { resource: ArticleResource })
-    assert.equal(seen.length, 1)
-    assert.equal(seen[0]?.name, 'ArticleResource')
-
-    seen.length = 0
-    await panelInfo(panel, undefined, { resource: OtherResource })
-    assert.equal(seen.length, 0)
-  })
-})

package/src/RenderHook.ts

@@ -1,242 +0,0 @@
-/**
- * Render hooks — named slots scattered through the panel chrome where
- * apps can inject arbitrary `Element[]` (or async resolvers) without
- * forking AppShell / layouts / page renderers.
- *
- * The closed name union is the v1 contract: extending it requires
- * editing this file. Deliberate — keeps autocomplete useful and prevents
- * typos from silently no-op'ing. Loosens to a `string` overload only
- * when a real consumer needs custom names.
- *
- * Scope semantics:
- *   - No scope → runs at every site of the named slot.
- *   - With scope → at least one of `scope.resource` / `scope.page` /
- *     `scope.global` must reference-equal the active route's identifier.
- *
- * Plan: docs/plans/render-hooks.md
- */
-import type { Element, ElementMeta } from './schema/Element.js'
-import type { ResourceClass } from './Resource.js'
-import type { GlobalClass } from './Global.js'
-import type { Page } from './Page.js'
-import { resolveSchema, type RenderContext } from './schema/resolveSchema.js'
-
-/**
- * Closed union of every render-hook slot pilotiq's chrome and page-role
- * renderers mount. Names ported verbatim from Filament's literal hook
- * names so user docs / community snippets transfer 1:1.
- */
-export type RenderHookName =
-  // ─── Chrome — head ──────────────────────────────────
-  | 'panels::head.start'
-  | 'panels::head.end'
-  | 'panels::scripts'
-  | 'panels::styles'
-  // ─── Chrome — body ──────────────────────────────────
-  | 'panels::body.start'
-  | 'panels::body.end'
-  // ─── Chrome — topbar ────────────────────────────────
-  | 'panels::topbar.start'
-  | 'panels::topbar.end'
-  // ─── Chrome — sidebar ───────────────────────────────
-  | 'panels::sidebar.start'
-  | 'panels::sidebar.nav.start'
-  | 'panels::sidebar.nav.end'
-  | 'panels::sidebar.footer'
-  // ─── Chrome — user menu ─────────────────────────────
-  | 'panels::user-menu.before'
-  | 'panels::user-menu.after'
-  // ─── Chrome — page footer ───────────────────────────
-  | 'panels::footer'
-  // ─── Page-level ─────────────────────────────────────
-  | 'panels::page.start'
-  | 'panels::page.end'
-  | 'panels::resource.pages.list-records.table.before'
-  | 'panels::resource.pages.list-records.table.after'
-  | 'panels::resource.pages.list-records.tabs.end'
-  | 'panels::resource.pages.list-records.header.actions.before'
-  | 'panels::resource.pages.list-records.header.actions.after'
-  | 'panels::resource.pages.create-record.form.before'
-  | 'panels::resource.pages.create-record.form.after'
-  | 'panels::resource.pages.create-record.header.actions.before'
-  | 'panels::resource.pages.create-record.header.actions.after'
-  | 'panels::resource.pages.edit-record.form.before'
-  | 'panels::resource.pages.edit-record.form.after'
-  | 'panels::resource.pages.edit-record.header.actions.before'
-  | 'panels::resource.pages.edit-record.header.actions.after'
-  | 'panels::resource.pages.view-record.start'
-  | 'panels::resource.pages.view-record.end'
-  | 'panels::resource.pages.view-record.header.actions.before'
-  | 'panels::resource.pages.view-record.header.actions.after'
-  | 'panels::global-search.results.before'
-  | 'panels::global-search.results.after'
-
-/**
- * Chrome slots resolved once per `panelInfo()` call and shipped under
- * `panel.renderHooks`. Page-role hooks ride on the per-builder
- * `viewProps.renderHooks` slot to keep `panelInfo()`'s payload from
- * ballooning when only a list-page hook fires.
- */
-export const CHROME_HOOK_NAMES = [
-  'panels::head.start',
-  'panels::head.end',
-  'panels::scripts',
-  'panels::styles',
-  'panels::body.start',
-  'panels::body.end',
-  'panels::topbar.start',
-  'panels::topbar.end',
-  'panels::sidebar.start',
-  'panels::sidebar.nav.start',
-  'panels::sidebar.nav.end',
-  'panels::sidebar.footer',
-  'panels::user-menu.before',
-  'panels::user-menu.after',
-  'panels::footer',
-] as const satisfies readonly RenderHookName[]
-
-/** Page-role slot names that the per-page-role builders own. */
-export const PAGE_HOOK_NAMES = [
-  'panels::page.start',
-  'panels::page.end',
-  'panels::resource.pages.list-records.table.before',
-  'panels::resource.pages.list-records.table.after',
-  'panels::resource.pages.list-records.tabs.end',
-  'panels::resource.pages.list-records.header.actions.before',
-  'panels::resource.pages.list-records.header.actions.after',
-  'panels::resource.pages.create-record.form.before',
-  'panels::resource.pages.create-record.form.after',
-  'panels::resource.pages.create-record.header.actions.before',
-  'panels::resource.pages.create-record.header.actions.after',
-  'panels::resource.pages.edit-record.form.before',
-  'panels::resource.pages.edit-record.form.after',
-  'panels::resource.pages.edit-record.header.actions.before',
-  'panels::resource.pages.edit-record.header.actions.after',
-  'panels::resource.pages.view-record.start',
-  'panels::resource.pages.view-record.end',
-  'panels::resource.pages.view-record.header.actions.before',
-  'panels::resource.pages.view-record.header.actions.after',
-  'panels::global-search.results.before',
-  'panels::global-search.results.after',
-] as const satisfies readonly RenderHookName[]
-
-/**
- * Context passed to every render-hook callback. `user` is the resolved
- * `Pilotiq.user(req => …)` return value (or `null`). `resource` /
- * `page` / `global` carry whichever class is active for the request, so
- * a generic chrome hook can branch on the route without registering a
- * scoped hook for every Resource.
- */
-export interface RenderHookContext {
-  user:      unknown
-  basePath:  string
-  url:       string
-  resource?: ResourceClass
-  page?:     typeof Page
-  global?:   GlobalClass
-  recordId?: string
-}
-
-/** Hook callback. Returns the elements to mount at the slot. */
-export type RenderHookFn = (ctx: RenderHookContext) => Element[] | Promise<Element[]>
-
-/**
- * Filter the slot to only fire when the active route matches one of the
- * scope keys (OR within the object). Omit to run everywhere.
- */
-export interface RenderHookScope {
-  resource?: ResourceClass
-  page?:     typeof Page
-  global?:   GlobalClass
-}
-
-/** Internal storage shape — one entry per `Pilotiq.renderHook()` call. */
-export interface RenderHookEntry {
-  name:   RenderHookName
-  fn:     RenderHookFn
-  scope?: RenderHookScope
-}
-
-/**
- * Wire shape shipped to the renderer. Sparse — only names that produced
- * non-empty content land in the map. The renderer mounts a slot at
- * every supported position; missing keys render nothing.
- */
-export type RenderHookMap = Partial<Record<RenderHookName, ElementMeta[]>>
-
-/**
- * Decide whether a hook entry should fire for the current context.
- * Scope is OR'd within the object; an empty / missing scope always
- * matches.
- */
-function scopeMatches(entry: RenderHookEntry, ctx: RenderHookContext): boolean {
-  const scope = entry.scope
-  if (!scope || (!scope.resource && !scope.page && !scope.global)) return true
-  if (scope.resource && ctx.resource === scope.resource) return true
-  if (scope.page     && ctx.page     === scope.page)     return true
-  if (scope.global   && ctx.global   === scope.global)   return true
-  return false
-}
-
-/**
- * Resolve a set of render-hook names against the panel's registered
- * entries. Returns a sparse map — names with no matching entries are
- * omitted from the result.
- *
- * Throwing hooks fail closed: their slot's contribution drops; other
- * hooks at the same slot still ship. Same posture as `Resource.canAccess`
- * and `navigationBadge()`.
- */
-export async function resolveRenderHooks(
-  entries: readonly RenderHookEntry[],
-  names: readonly RenderHookName[],
-  ctx: RenderHookContext,
-): Promise<RenderHookMap> {
-  if (entries.length === 0 || names.length === 0) return {}
-
-  const wanted = new Set<RenderHookName>(names)
-  const matching = entries.filter(e => wanted.has(e.name) && scopeMatches(e, ctx))
-  if (matching.length === 0) return {}
-
-  // Resolve each entry's `fn` in parallel. Errors swallow per-entry —
-  // one flaky hook doesn't blank the page.
-  const resolved = await Promise.all(
-    matching.map(async entry => {
-      try {
-        const els = await entry.fn(ctx)
-        return { name: entry.name, els: Array.isArray(els) ? els : [] }
-      } catch (err) {
-        console.warn(`[pilotiq] render hook ${entry.name} threw:`, err)
-        return { name: entry.name, els: [] as Element[] }
-      }
-    }),
-  )
-
-  // Bucket by name, preserving registration order (matching is in the
-  // order entries were registered; the `filter` above is stable).
-  const buckets = new Map<RenderHookName, Element[]>()
-  for (const r of resolved) {
-    if (r.els.length === 0) continue
-    const cur = buckets.get(r.name)
-    if (cur) cur.push(...r.els)
-    else     buckets.set(r.name, [...r.els])
-  }
-  if (buckets.size === 0) return {}
-
-  // Walk every bucket through the schema resolver so the wire shape
-  // matches every other Element[] payload — nested visibility, async
-  // toMeta(), etc. all just work. `RenderContext.user` is duck-typed
-  // (`name`/`email`/...); pilotiq treats user as opaque so cast through.
-  const renderCtx: RenderContext = {}
-  if (ctx.user !== null && typeof ctx.user === 'object') {
-    renderCtx.user = ctx.user as { name?: string; email?: string; [key: string]: unknown }
-  }
-  const out: RenderHookMap = {}
-  await Promise.all(
-    [...buckets.entries()].map(async ([name, els]) => {
-      const metas = await resolveSchema(els, renderCtx)
-      if (metas.length > 0) out[name] = metas
-    }),
-  )
-  return out
-}