@pilotiq/pilotiq 0.24.1 → 0.24.2

package/src/Cluster.test.ts

@@ -1,283 +0,0 @@
-import { describe, it, beforeEach } from 'node:test'
-import assert from 'node:assert/strict'
-
-import { Router } from '@rudderjs/router'
-
-import { Cluster } from './Cluster.js'
-import { Pilotiq } from './Pilotiq.js'
-import { Resource } from './Resource.js'
-import { Global } from './Global.js'
-import { Page } from './Page.js'
-import { Form } from './elements/Form.js'
-import { Table } from './elements/Table.js'
-import { Heading } from './schema/Heading.js'
-import { resourceBasePath, globalBasePath, pageBasePath, clusterBasePath } from './clusterPaths.js'
-import { panelInfo } from './pageData.js'
-import { registerPilotiqRoutes } from './routes.js'
-
-class ContentCluster extends Cluster {
-  static override label = 'Content'
-  static override slug  = 'content'
-  static override icon  = 'folder'
-}
-
-class SettingsCluster extends Cluster {
-  static override label = 'Settings'
-  static override slug  = 'settings'
-}
-
-class ArticleResource extends Resource {
-  static override label = 'Articles'
-  static override slug  = 'articles'
-  static override cluster = ContentCluster
-
-  static override form(form: Form): Form { return form }
-  static override table(table: Table): Table { return table }
-}
-
-class TopLevelCategoryResource extends Resource {
-  static override label = 'Categories'
-  static override slug  = 'categories'
-
-  static override form(form: Form): Form { return form }
-  static override table(table: Table): Table { return table }
-}
-
-class BrandingGlobal extends Global {
-  static override label = 'Branding'
-  static override slug  = 'branding'
-  static override cluster = SettingsCluster
-}
-
-class AnalyticsPage extends Page {
-  static override slug  = 'analytics'
-  static override label = 'Analytics'
-  static override cluster = ContentCluster
-  static override schema() { return [Heading.make('Analytics')] }
-}
-
-describe('Cluster — class basics', () => {
-  it('default slug derives from label, kebab-cased', () => {
-    class TwoWordCluster extends Cluster {
-      static override label = 'My Cluster'
-    }
-    assert.equal(TwoWordCluster.getSlug(), 'my-cluster')
-  })
-
-  it('explicit slug wins over derived', () => {
-    assert.equal(ContentCluster.getSlug(), 'content')
-  })
-
-  it('navigationLabel falls through to label when unset', () => {
-    assert.equal(ContentCluster.getNavigationLabel(), 'Content')
-  })
-
-  it('navigationIcon falls through to icon when unset', () => {
-    assert.equal(ContentCluster.getNavigationIcon(), 'folder')
-  })
-
-  it('canAccess defaults to true', async () => {
-    assert.equal(await ContentCluster.canAccess(null), true)
-  })
-})
-
-describe('Cluster — URL helpers', () => {
-  it('resourceBasePath prefixes with cluster slug when set', () => {
-    assert.equal(resourceBasePath('/admin', ArticleResource), '/admin/content/articles')
-  })
-
-  it('resourceBasePath skips prefix for top-level resources', () => {
-    assert.equal(resourceBasePath('/admin', TopLevelCategoryResource), '/admin/categories')
-  })
-
-  it('globalBasePath prefixes with cluster slug when set', () => {
-    assert.equal(globalBasePath('/admin', BrandingGlobal), '/admin/settings/branding')
-  })
-
-  it('pageBasePath prefixes with cluster slug when set', () => {
-    assert.equal(pageBasePath('/admin', AnalyticsPage), '/admin/content/analytics')
-  })
-
-  it('clusterBasePath stays panel-base + cluster slug', () => {
-    assert.equal(clusterBasePath('/admin', ContentCluster), '/admin/content')
-  })
-})
-
-describe('Cluster — boot validation', () => {
-  let router: Router
-  beforeEach(() => { router = new Router() })
-
-  it('throws when a resource references an unregistered cluster', () => {
-    class OrphanCluster extends Cluster {
-      static override label = 'Orphan'
-      static override slug  = 'orphan'
-    }
-    class OrphanedResource extends Resource {
-      static override label = 'Orphans'
-      static override slug  = 'orphans'
-      static override cluster = OrphanCluster
-    }
-    const panel = Pilotiq.make('boot-orphan').path('/admin')
-      .resources([OrphanedResource])
-      // no .clusters() — OrphanCluster never registered
-
-    assert.throws(
-      () => registerPilotiqRoutes(router, panel),
-      /OrphanCluster.*not registered/,
-    )
-  })
-
-  it('throws on duplicate cluster slugs', () => {
-    class A extends Cluster { static override label = 'A'; static override slug = 'shared' }
-    class B extends Cluster { static override label = 'B'; static override slug = 'shared' }
-    const panel = Pilotiq.make('boot-dup').path('/admin').clusters([A, B])
-    assert.throws(
-      () => registerPilotiqRoutes(router, panel),
-      /share slug "shared"/,
-    )
-  })
-
-  it('throws on reserved cluster slugs', () => {
-    class BadCluster extends Cluster { static override label = '_x'; static override slug = '_secret' }
-    const panel = Pilotiq.make('boot-reserved').path('/admin').clusters([BadCluster])
-    assert.throws(
-      () => registerPilotiqRoutes(router, panel),
-      /reserved slug/,
-    )
-  })
-
-  it('throws when a top-level resource slug collides with a cluster slug', () => {
-    class ClashResource extends Resource {
-      static override label = 'Content'   // slug derives to 'content'
-    }
-    const panel = Pilotiq.make('boot-clash').path('/admin')
-      .clusters([ContentCluster])
-      .resources([ClashResource])
-    assert.throws(
-      () => registerPilotiqRoutes(router, panel),
-      /collides with a registered cluster slug/,
-    )
-  })
-
-  it('passes when wiring is consistent', () => {
-    const panel = Pilotiq.make('boot-ok').path('/admin')
-      .clusters([ContentCluster])
-      .resources([ArticleResource])
-    assert.doesNotThrow(() => registerPilotiqRoutes(router, panel))
-  })
-})
-
-describe('Cluster — route registration', () => {
-  it('mounts resource routes under the cluster prefix', () => {
-    const router = new Router()
-    const panel = Pilotiq.make('routes-cluster').path('/admin')
-      .clusters([ContentCluster])
-      .resources([ArticleResource])
-    registerPilotiqRoutes(router, panel)
-    const paths = router.list().map(r => `${r.method} ${r.path}`)
-    assert.ok(paths.includes('GET /admin/content/articles'))
-    assert.ok(paths.includes('GET /admin/content/articles/create'))
-    assert.ok(paths.includes('GET /admin/content/articles/:id'))
-    assert.ok(paths.includes('GET /admin/content/articles/:id/edit'))
-    assert.ok(paths.includes('POST /admin/content/articles/:id/delete'))
-  })
-
-  it('top-level resources stay unprefixed', () => {
-    const router = new Router()
-    const panel = Pilotiq.make('routes-mixed').path('/admin')
-      .clusters([ContentCluster])
-      .resources([ArticleResource, TopLevelCategoryResource])
-    registerPilotiqRoutes(router, panel)
-    const paths = router.list().map(r => `${r.method} ${r.path}`)
-    assert.ok(paths.includes('GET /admin/categories'))   // top-level
-    assert.ok(paths.includes('GET /admin/content/articles'))
-  })
-})
-
-describe('Cluster — panelInfo navigation tree', () => {
-  it('nests children under the cluster as a parent nav item', async () => {
-    const panel = Pilotiq.make('nav-cluster').path('/admin')
-      .clusters([ContentCluster])
-      .resources([ArticleResource])
-    const info = await panelInfo(panel)
-    const nav = info.navigation
-    const cluster = nav.find(n => n.name === 'ContentCluster')
-    assert.ok(cluster, 'cluster nav item should exist')
-    assert.equal(cluster!.label, 'Content')
-    assert.equal(cluster!.url, '/admin/content/articles')   // first child URL
-    assert.deepEqual(cluster!.children?.map(c => c.name), ['ArticleResource'])
-    // No top-level ArticleResource — it's nested under the cluster.
-    assert.equal(nav.find(n => n.name === 'ArticleResource'), undefined)
-  })
-
-  it('drops a cluster whose every child is gated by canAccess', async () => {
-    class HiddenResource extends Resource {
-      static override label = 'Hidden'
-      static override slug  = 'hidden'
-      static override cluster = ContentCluster
-      static override async canAccess() { return false }
-    }
-    const panel = Pilotiq.make('nav-empty-cluster').path('/admin')
-      .clusters([ContentCluster])
-      .resources([HiddenResource])
-    const info = await panelInfo(panel)
-    assert.equal(info.navigation.find(n => n.name === 'ContentCluster'), undefined)
-  })
-
-  it('cluster.canAccess(false) hides the cluster + every child', async () => {
-    class GatedCluster extends Cluster {
-      static override label = 'Gated'
-      static override slug  = 'gated'
-      static override async canAccess() { return false }
-    }
-    class GatedArticleResource extends Resource {
-      static override label = 'Articles'
-      static override slug  = 'gated-articles'
-      static override cluster = GatedCluster
-    }
-    const panel = Pilotiq.make('nav-gated').path('/admin')
-      .clusters([GatedCluster])
-      .resources([GatedArticleResource])
-    const info = await panelInfo(panel)
-    assert.equal(info.navigation.find(n => n.name === 'GatedCluster'), undefined)
-    assert.equal(info.navigation.find(n => n.name === 'GatedArticleResource'), undefined)
-  })
-
-  it('uses landingPage URL when set', async () => {
-    class HomePage extends Page {
-      static override slug    = 'home'
-      static override label   = 'Home'
-      static override cluster = ContentCluster
-      static override schema() { return [Heading.make('Home')] }
-    }
-    class CC extends ContentCluster {
-      static override landingPage = HomePage
-    }
-    class CCArticleResource extends Resource {
-      static override label   = 'Articles'
-      static override slug    = 'cc-articles'
-      static override cluster = CC
-    }
-    const panel = Pilotiq.make('nav-landing').path('/admin')
-      .clusters([CC])
-      .resources([CCArticleResource])
-      .pages([HomePage])
-    const info = await panelInfo(panel)
-    const cluster = info.navigation.find(n => n.name === 'CC')
-    assert.ok(cluster)
-    assert.equal(cluster!.url, '/admin/content/home')   // landingPage wins over first-child
-  })
-})
-
-describe('Cluster — global search URL', () => {
-  it('Resource.getGlobalSearchResultUrl threads cluster prefix', () => {
-    assert.equal(
-      ArticleResource.getGlobalSearchResultUrl({ id: '42' }, '/admin'),
-      '/admin/content/articles/42',
-    )
-    assert.equal(
-      TopLevelCategoryResource.getGlobalSearchResultUrl({ id: '7' }, '/admin'),
-      '/admin/categories/7',
-    )
-  })
-})

package/src/Cluster.ts

@@ -1,83 +0,0 @@
-import type { IconValue } from './icons/types.js'
-import type { NavigationBadgeColor, NavigationBadgeHandler } from './Resource.js'
-import type { Page } from './Page.js'
-
-/**
- * URL-prefix container that groups Resources, Globals, and custom Pages
- * under a shared slug and a single sidebar entry. Children opt in via
- * `static cluster = MyCluster`.
- */
-export abstract class Cluster {
-  /** Human-readable label for the cluster nav entry, e.g. `'Content'`. */
-  static label: string = 'Cluster'
-
-  /** URL slug. Derived from `label` when unset. */
-  static slug: string = ''
-
-  /** Sidebar / nav icon. String registry key or React component. See
-   * `Resource.icon` for the contract. */
-  static icon: IconValue = 'folder'
-
-  // ─── Navigation metadata ──────────────────────────
-  // Mirrors Resource's nav surface so clusters compose with
-  // `navigationGroup` (a Settings cluster sitting under a 'System'
-  // group, etc.) and `navigationParentItem` (a sub-cluster under a
-  // parent nav item).
-
-  /** Group label this cluster renders under in the sidebar. */
-  static navigationGroup: string | undefined = undefined
-
-  /** Sort key within a group. Lower sorts first. */
-  static navigationSort: number | undefined = undefined
-
-  /** Sidebar label override. `Cluster.label` still drives URL paths. */
-  static navigationLabel: string | undefined = undefined
-
-  /** Sidebar icon override. */
-  static navigationIcon: IconValue = undefined
-
-  /** Server-eval'd badge handler; rendered as a small pill next to the
-   * cluster label. Errors are swallowed by `panelInfo()` so a flaky
-   * count never blanks the page. The cluster's badge does NOT aggregate
-   * its children's badges — it's an independent handler. */
-  static navigationBadge: NavigationBadgeHandler | undefined = undefined
-
-  /** Pill color for the badge. */
-  static navigationBadgeColor: NavigationBadgeColor = 'default'
-
-  /** Class name of a parent nav item. */
-  static navigationParentItem: string | undefined = undefined
-
-  /**
-   * Optional landing page when the cluster nav entry is clicked. Must be
-   * a Page registered in `cfg.pages` whose `static cluster` points at
-   * this cluster. When unset, the cluster nav URL deep-links to the
-   * first accessible child (resource list / global edit / custom page).
-   */
-  static landingPage?: typeof Page
-
-  /**
-   * Coarse "should this cluster exist for this user" gate. Failing
-   * `canAccess` drops the cluster + every child from the nav tree and
-   * 403s every child route. Throws are treated as `false` (fail closed).
-   */
-  static async canAccess(_user: unknown): Promise<boolean> { return true }
-
-  /** URL slug, derived from `label` when not set explicitly. */
-  static getSlug(): string {
-    return this.slug || this.label.toLowerCase().replace(/\s+/g, '-')
-  }
-
-  /** Sidebar label: `navigationLabel` override falls through to `label`. */
-  static getNavigationLabel(): string {
-    return this.navigationLabel ?? this.label
-  }
-
-  /** Sidebar icon: `navigationIcon` override falls through to `icon`. */
-  static getNavigationIcon(): IconValue {
-    return this.navigationIcon ?? this.icon
-  }
-}
-
-/** Constructor type for `Cluster` subclasses. Used in panel registration. */
-export type ClusterClass = typeof Cluster

package/src/Column.test.ts

@@ -1,199 +0,0 @@
-import { describe, it } from 'node:test'
-import assert from 'node:assert/strict'
-
-import { Column } from './Column.js'
-import { resolveSchema } from './schema/resolveSchema.js'
-
-describe('Column', () => {
-  it('toMeta emits type=column with name + label + flags', () => {
-    const meta = Column.make('title').label('Title').sortable().searchable().toMeta()
-    assert.deepEqual(meta, {
-      type:       'column',
-      name:       'title',
-      label:      'Title',
-      sortable:   true,
-      searchable: true,
-    })
-  })
-
-  it('label defaults to capitalized name when not set', () => {
-    const meta = Column.make('createdAt').toMeta()
-    assert.equal(meta.label, 'CreatedAt')
-  })
-
-  it('sortable / searchable default to false', () => {
-    const meta = Column.make('x').toMeta()
-    assert.equal(meta.sortable, false)
-    assert.equal(meta.searchable, false)
-  })
-
-  it('joins the resolver tree as a leaf Element', async () => {
-    const result = await resolveSchema([Column.make('title')])
-    assert.equal(result.length, 1)
-    assert.equal(result[0]!.type, 'column')
-    assert.equal('children' in result[0]!, false)
-  })
-
-  describe('layout & cosmetics', () => {
-    it('alignment / width / default / tooltip / wrap / lineClamp / weight / color round-trip', () => {
-      const meta = Column.make('a')
-        .alignment('center')
-        .width('120px')
-        .default('—')
-        .tooltip('Help')
-        .wrap()
-        .lineClamp(2)
-        .weight('semibold')
-        .color('muted')
-        .toMeta()
-      assert.equal(meta.alignment, 'center')
-      assert.equal(meta.width,     '120px')
-      assert.equal(meta.default,   '—')
-      assert.equal(meta.tooltip,   'Help')
-      assert.equal(meta.wrap,      true)
-      assert.equal(meta.lineClamp, 2)
-      assert.equal(meta.weight,    'semibold')
-      assert.equal(meta.color,     'muted')
-    })
-
-    it('placeholder() is an alias for default()', () => {
-      const meta = Column.make('a').placeholder('—').toMeta()
-      assert.equal(meta.default, '—')
-    })
-
-    it('cosmetic builders are absent from meta when not called', () => {
-      const meta = Column.make('a').toMeta()
-      assert.equal(meta.alignment, undefined)
-      assert.equal(meta.width,     undefined)
-      assert.equal(meta.tooltip,   undefined)
-      assert.equal(meta.wrap,      undefined)
-      assert.equal(meta.color,     undefined)
-    })
-  })
-
-  describe('built-in formatters', () => {
-    it('dateTime() with default pattern', () => {
-      const meta = Column.make('createdAt').dateTime().toMeta()
-      assert.deepEqual(meta.format, { kind: 'dateTime' })
-    })
-
-    it('dateTime("PPpp")', () => {
-      const meta = Column.make('createdAt').dateTime('PPpp').toMeta()
-      assert.deepEqual(meta.format, { kind: 'dateTime', pattern: 'PPpp' })
-    })
-
-    it('since() emits kind:since', () => {
-      const meta = Column.make('createdAt').since().toMeta()
-      assert.deepEqual(meta.format, { kind: 'since' })
-    })
-
-    it('money(currency) emits kind:money + currency', () => {
-      const meta = Column.make('amount').money('EUR').toMeta()
-      assert.deepEqual(meta.format, { kind: 'money', currency: 'EUR' })
-    })
-
-    it('numeric({decimals}) emits kind:numeric + decimals', () => {
-      const meta = Column.make('x').numeric({ decimals: 2 }).toMeta()
-      assert.deepEqual(meta.format, { kind: 'numeric', decimals: 2 })
-    })
-
-    it('limit(n) emits kind:limit + chars', () => {
-      const meta = Column.make('body').limit(40).toMeta()
-      assert.deepEqual(meta.format, { kind: 'limit', chars: 40 })
-    })
-
-    it('formatStateUsing stamps hasFormatter:true on meta', () => {
-      const col = Column.make('priority').formatStateUsing((v) => `${v}!`)
-      const meta = col.toMeta()
-      assert.equal(meta.hasFormatter, true)
-      assert.equal(col.hasFormatter(), true)
-      assert.equal(typeof col.getFormatStateHandler(), 'function')
-    })
-  })
-
-  describe('recordUrl per-column override / opt-out', () => {
-    it('absent by default — column inherits the table-level recordUrl', () => {
-      const col = Column.make('title')
-      const meta = col.toMeta()
-      assert.equal(meta.recordUrl, undefined)
-      assert.equal(col.isRecordUrlDisabled(), false)
-      assert.equal(col.hasRecordUrlHandler(), false)
-    })
-
-    it('recordUrl(false) emits recordUrl:false on meta', () => {
-      const col = Column.make('actions').recordUrl(false)
-      const meta = col.toMeta()
-      assert.equal(meta.recordUrl, false)
-      assert.equal(col.isRecordUrlDisabled(), true)
-      assert.equal(col.hasRecordUrlHandler(), false)
-    })
-
-    it('recordUrl(fn) emits recordUrl:true on meta and exposes the handler', () => {
-      const col = Column.make('title').recordUrl((r) => `/posts/${(r as { id?: string }).id}`)
-      const meta = col.toMeta()
-      assert.equal(meta.recordUrl, true)
-      assert.equal(col.hasRecordUrlHandler(), true)
-      assert.equal(col.isRecordUrlDisabled(), false)
-      assert.equal(typeof col.getRecordUrlHandler(), 'function')
-    })
-  })
-
-  describe('beforeStateUpdated / afterStateUpdated accessors', () => {
-    it('return undefined when no hooks are set', () => {
-      const col = Column.make('title')
-      assert.equal(col.getBeforeStateUpdated(), undefined)
-      assert.equal(col.getAfterStateUpdated(),  undefined)
-    })
-
-    it('return the registered hook function', () => {
-      const before = async () => {}
-      const after  = () => {}
-      const col = Column.make('title').beforeStateUpdated(before).afterStateUpdated(after)
-      assert.equal(col.getBeforeStateUpdated(), before)
-      assert.equal(col.getAfterStateUpdated(),  after)
-    })
-
-    it('hooks are not serialized into the wire shape', () => {
-      const col = Column.make('title').beforeStateUpdated(() => {}).afterStateUpdated(() => {})
-      const meta = col.toMeta()
-      assert.equal((meta as Record<string, unknown>)['beforeStateUpdated'], undefined)
-      assert.equal((meta as Record<string, unknown>)['afterStateUpdated'],  undefined)
-    })
-  })
-
-  describe('toggleable() user-visibility chrome', () => {
-    it('isToggleable + getToggleableConfig default to false / undefined', () => {
-      const col = Column.make('email')
-      assert.equal(col.isToggleable(),         false)
-      assert.equal(col.getToggleableConfig(),  undefined)
-    })
-
-    it('bare toggleable() opts in with defaults (visible by default)', () => {
-      const col = Column.make('email').toggleable()
-      assert.equal(col.isToggleable(), true)
-      assert.deepEqual(col.getToggleableConfig(), {})
-      const meta = col.toMeta() as Record<string, unknown>
-      assert.deepEqual(meta['toggleable'], {})
-    })
-
-    it('toggleable({ initiallyHidden: true }) starts off-screen', () => {
-      const col = Column.make('internalId').toggleable({ initiallyHidden: true })
-      const cfg = col.getToggleableConfig()
-      assert.equal(cfg?.initiallyHidden, true)
-      const meta = col.toMeta() as Record<string, unknown>
-      assert.deepEqual(meta['toggleable'], { initiallyHidden: true })
-    })
-
-    it('toggleable(false) explicitly opts back out', () => {
-      const col = Column.make('email').toggleable().toggleable(false)
-      assert.equal(col.isToggleable(), false)
-      const meta = col.toMeta() as Record<string, unknown>
-      assert.equal(meta['toggleable'], undefined)
-    })
-
-    it('omits the meta key when not opted in (sparse wire shape)', () => {
-      const meta = Column.make('plain').toMeta() as Record<string, unknown>
-      assert.equal('toggleable' in meta, false)
-    })
-  })
-})