@pilotiq/pilotiq 0.23.1 → 0.24.2

package/src/schema/Stat.test.ts

@@ -1,118 +0,0 @@
-/**
- * Plan #15 Phase B — `Stat` value-object surface tests.
- */
-
-import { describe, it } from 'node:test'
-import assert from 'node:assert/strict'
-
-import { Stat } from './Stat.js'
-
-describe('Stat fluent surface', () => {
-  it('Stat.make(label) returns an instance whose meta carries the label', () => {
-    const meta = Stat.make('Users').toMeta()
-    assert.equal(meta.label, 'Users')
-  })
-
-  it('omits unset optional keys (compact wire)', () => {
-    const meta = Stat.make('Users').toMeta()
-    assert.deepEqual(Object.keys(meta).sort(), ['label'])
-  })
-
-  it('value(n) emits a numeric value', () => {
-    const meta = Stat.make('Users').value(42).toMeta()
-    assert.equal(meta.value, 42)
-  })
-
-  it('value(string) emits a string value (e.g. preformatted currency)', () => {
-    const meta = Stat.make('Revenue').value('$1,234').toMeta()
-    assert.equal(meta.value, '$1,234')
-  })
-
-  it('value(undefined) round-trips as null (renderer placeholder)', () => {
-    const meta = Stat.make('Users').value(undefined).toMeta()
-    assert.equal(meta.value, null)
-  })
-
-  it('value(null) emits null', () => {
-    const meta = Stat.make('Users').value(null).toMeta()
-    assert.equal(meta.value, null)
-  })
-
-  it('description() emits the supplementary line', () => {
-    const meta = Stat.make('Users').description('+12%').toMeta()
-    assert.equal(meta.description, '+12%')
-  })
-
-  it('descriptionIcon(name) defaults to position=after', () => {
-    const meta = Stat.make('Users').descriptionIcon('trending-up').toMeta()
-    assert.deepEqual(meta.descriptionIcon, { name: 'trending-up', position: 'after' })
-  })
-
-  it('descriptionIcon(name, "before") preserves the position', () => {
-    const meta = Stat.make('Users').descriptionIcon('trending-up', 'before').toMeta()
-    assert.deepEqual(meta.descriptionIcon, { name: 'trending-up', position: 'before' })
-  })
-
-  it('icon(name) emits the main icon', () => {
-    const meta = Stat.make('Users').icon('users').toMeta()
-    assert.equal(meta.icon, 'users')
-  })
-
-  it('color(c) emits the color preset', () => {
-    const meta = Stat.make('Users').color('success').toMeta()
-    assert.equal(meta.color, 'success')
-  })
-
-  it('chart([…]) emits a copy of the array (no aliasing)', () => {
-    const series = [1, 2, 3]
-    const stat   = Stat.make('Users').chart(series)
-    series.push(99)
-    assert.deepEqual(stat.toMeta().chart, [1, 2, 3])
-  })
-
-  it('url(href) emits the URL', () => {
-    const meta = Stat.make('Users').url('/admin/users').toMeta()
-    assert.equal(meta.url, '/admin/users')
-  })
-
-  it('openUrlInNewTab() defaults to true', () => {
-    const meta = Stat.make('Users').url('/x').openUrlInNewTab().toMeta()
-    assert.equal(meta.openInNewTab, true)
-  })
-
-  it('openUrlInNewTab(false) opts back out', () => {
-    const meta = Stat.make('Users').url('/x').openUrlInNewTab(false).toMeta()
-    assert.equal(meta.openInNewTab, false)
-  })
-
-  it('extraAttributes spreads onto meta as-is', () => {
-    const meta = Stat.make('Users').extraAttributes({ 'data-id': '1', 'aria-label': 'Users' }).toMeta()
-    assert.deepEqual(meta.extraAttributes, { 'data-id': '1', 'aria-label': 'Users' })
-  })
-
-  it('chained setters compose into a single meta', () => {
-    const meta = Stat.make('Users')
-      .value(1234)
-      .description('+12%')
-      .descriptionIcon('trending-up', 'before')
-      .icon('users')
-      .color('primary')
-      .chart([1, 2, 3, 4, 5])
-      .url('/admin/users')
-      .openUrlInNewTab()
-      .extraAttributes({ 'data-test': 'users-stat' })
-      .toMeta()
-    assert.deepEqual(meta, {
-      label: 'Users',
-      value: 1234,
-      description: '+12%',
-      descriptionIcon: { name: 'trending-up', position: 'before' },
-      icon: 'users',
-      color: 'primary',
-      chart: [1, 2, 3, 4, 5],
-      url: '/admin/users',
-      openInNewTab: true,
-      extraAttributes: { 'data-test': 'users-stat' },
-    })
-  })
-})

package/src/schema/Stat.ts

@@ -1,154 +0,0 @@
-/**
- * Plan #15 Phase B — `Stat` is the fluent value object emitted by
- * `StatsOverview.getStats(ctx)`. It does NOT extend Element — it has no
- * place in the schema tree on its own. `StatsOverview.resolveServerData`
- * collects the array of Stats and ships them as JSON-clean
- * `StatMeta[]` payloads under `_widgetData[id]`.
- *
- *   Stat.make('Users')
- *     .value(await User.query().count())
- *     .description('+12% this month')
- *     .descriptionIcon('trending-up', 'before')
- *     .icon('users')
- *     .color('success')
- *     .chart([12, 4, 8, 15, 22, 18, 30])      // sparkline
- *     .url('/admin/users').openUrlInNewTab()
- *
- * Surface mirrors Filament v5's `Stat` 1:1, modulo TS naming
- * (`openUrlInNewTab(true)` not `->openUrlInNewTab()`).
- */
-
-/** Color preset. Mirrors `TabBadgeColor` so a "Users · 5,234" stat can
- *  be tinted with the same palette as the rest of the panel chrome. */
-export type StatColor =
-  | 'default'
-  | 'primary'
-  | 'success'
-  | 'warning'
-  | 'destructive'
-  | 'info'
-
-/** Position for the optional `descriptionIcon`. Matches Filament's
- *  `IconPosition::Before / After` enum values. */
-export type StatDescriptionIconPosition = 'before' | 'after'
-
-export interface StatDescriptionIcon {
-  name:     string
-  position: StatDescriptionIconPosition
-}
-
-/**
- * JSON-clean payload shape — what `StatsOverview.resolveServerData`
- * emits and the renderer consumes. Optional keys are omitted when the
- * fluent setter wasn't called (smaller wire, simpler renderer
- * branching).
- */
-export interface StatMeta {
-  label: string
-  value?: string | number | null
-  description?: string
-  descriptionIcon?: StatDescriptionIcon
-  icon?: string
-  color?: StatColor
-  chart?: number[]
-  url?: string
-  openInNewTab?: boolean
-  extraAttributes?: Record<string, unknown>
-}
-
-export class Stat {
-  protected _value?:           string | number | null
-  protected _description?:     string
-  protected _descriptionIcon?: StatDescriptionIcon
-  protected _icon?:            string
-  protected _color?:           StatColor
-  protected _chart?:           number[]
-  protected _url?:             string
-  protected _openInNewTab?:    boolean
-  protected _extraAttributes?: Record<string, unknown>
-
-  protected constructor(protected _label: string) {}
-
-  /** Factory. The single positional arg is the stat's *label*
-   *  (e.g. 'Users') — the value is set fluently via `.value(...)`. */
-  static make(label: string): Stat {
-    return new Stat(label)
-  }
-
-  /** Main number / string. `null` and `undefined` round-trip as `null`
-   *  so the renderer can show a placeholder ("—") for "not yet
-   *  computed" / "not applicable" without an extra sentinel. */
-  value(v: string | number | null | undefined): this {
-    this._value = v ?? null
-    return this
-  }
-
-  /** Supplementary line below the value (e.g. '+12% this month'). */
-  description(t: string): this {
-    this._description = t
-    return this
-  }
-
-  /** Tiny icon glued to the description. Position defaults to `'after'`
-   *  (matches Filament v5's `IconPosition::After`). */
-  descriptionIcon(name: string, position: StatDescriptionIconPosition = 'after'): this {
-    this._descriptionIcon = { name, position }
-    return this
-  }
-
-  /** Main icon shown in the card chrome. String key into the panel's
-   *  icon registry — same lookup as `Resource.icon`. */
-  icon(name: string): this {
-    this._icon = name
-    return this
-  }
-
-  /** Color tint for the value + icon. */
-  color(c: StatColor): this {
-    this._color = c
-    return this
-  }
-
-  /** Inline-SVG sparkline data. Array of raw numbers — the renderer
-   *  draws a path scaled to the card. No chart-lib dep. */
-  chart(values: number[]): this {
-    this._chart = [...values]
-    return this
-  }
-
-  /** Wrap the card in an `<a href>`. */
-  url(href: string): this {
-    this._url = href
-    return this
-  }
-
-  /** When `.url()` is set, open it in a new tab. */
-  openUrlInNewTab(value: boolean = true): this {
-    this._openInNewTab = value
-    return this
-  }
-
-  /** Extra HTML attributes spread onto the card root. JSON-clean only —
-   *  values must serialize. */
-  extraAttributes(attrs: Record<string, unknown>): this {
-    this._extraAttributes = { ...attrs }
-    return this
-  }
-
-  /** Serialize to the wire shape. Stats are ferried through
-   *  `_widgetData` so this is a plain JSON object — no children, no
-   *  `type` discriminator (the parent `StatsOverview` carries that). */
-  toMeta(): StatMeta {
-    const out: StatMeta = { label: this._label }
-    if (this._value           !== undefined) out.value           = this._value
-    if (this._description     !== undefined) out.description     = this._description
-    if (this._descriptionIcon !== undefined) out.descriptionIcon = this._descriptionIcon
-    if (this._icon            !== undefined) out.icon            = this._icon
-    if (this._color           !== undefined) out.color           = this._color
-    if (this._chart           !== undefined) out.chart           = this._chart
-    if (this._url             !== undefined) out.url             = this._url
-    if (this._openInNewTab    !== undefined) out.openInNewTab    = this._openInNewTab
-    if (this._extraAttributes !== undefined) out.extraAttributes = this._extraAttributes
-    return out
-  }
-}

package/src/schema/StatsOverview.test.ts

@@ -1,141 +0,0 @@
-/**
- * Plan #15 Phase B — `StatsOverview` element tests.
- */
-
-import { describe, it } from 'node:test'
-import assert from 'node:assert/strict'
-
-import { Stat } from './Stat.js'
-import { StatsOverview } from './StatsOverview.js'
-import { resolveSchema, type RenderContext } from './resolveSchema.js'
-import { isServerDataElement } from './ServerDataElement.js'
-
-describe('StatsOverview element', () => {
-  describe('factory + identity', () => {
-    it('StatsOverview.make() returns an instance', () => {
-      const w = StatsOverview.make('overview')
-      assert.ok(w instanceof StatsOverview)
-      assert.equal(w.getType(), 'stats')
-    })
-
-    it('falls back to subclass class name when no id passed', () => {
-      class UsersStats extends StatsOverview {}
-      assert.equal(UsersStats.make().getId(), 'UsersStats')
-    })
-
-    it('explicit id wins over class name', () => {
-      class UsersStats extends StatsOverview {}
-      assert.equal(UsersStats.make('explicit').getId(), 'explicit')
-    })
-
-    it('is a ServerDataElement', () => {
-      assert.equal(isServerDataElement(StatsOverview.make('a')), true)
-    })
-
-    it('lazy default = true (inherited)', () => {
-      assert.equal(StatsOverview.make('a').isLazy(), true)
-    })
-  })
-
-  describe('columns()', () => {
-    it('instance setter wins over static', () => {
-      class StaticCols extends StatsOverview {
-        static override columns = 2
-      }
-      const w = StaticCols.make().columns(4)
-      assert.equal(w.getColumns(), 4)
-    })
-
-    it('static columns is the fallback', () => {
-      class StaticCols extends StatsOverview {
-        static override columns = 3
-      }
-      assert.equal(StaticCols.make().getColumns(), 3)
-    })
-
-    it('returns undefined when neither set', () => {
-      assert.equal(StatsOverview.make('a').getColumns(), undefined)
-    })
-  })
-
-  describe('toMeta()', () => {
-    it('emits type=stats', async () => {
-      const [meta] = await resolveSchema([StatsOverview.make('a')])
-      assert.equal(meta!.type, 'stats')
-    })
-
-    it('omits columns when neither static nor instance set', async () => {
-      const [meta] = await resolveSchema([StatsOverview.make('a')])
-      assert.equal(meta!['columns'], undefined)
-    })
-
-    it('emits columns when set on the instance', async () => {
-      const [meta] = await resolveSchema([StatsOverview.make('a').columns(4)])
-      assert.equal(meta!['columns'], 4)
-    })
-
-    it('emits columns when set as a static on the subclass', async () => {
-      class S extends StatsOverview {
-        static override columns = 2
-      }
-      const [meta] = await resolveSchema([S.make()])
-      assert.equal(meta!['columns'], 2)
-    })
-
-    it('serverData wire-shape stamps land on top', async () => {
-      class S extends StatsOverview {}
-      const w = S.make().poll(60).lazy(false)
-      const [meta] = await resolveSchema([w])
-      assert.equal(meta!['serverData'], true)
-      assert.equal(meta!['id'], 'S')
-      assert.equal(meta!['poll'], 60)
-      assert.equal(meta!['lazy'], false)
-    })
-  })
-
-  describe('resolveServerData()', () => {
-    it('runs the static getStats() hook and serializes Stat[] into StatMeta[]', async () => {
-      class UsersStats extends StatsOverview {
-        static override async getStats() {
-          return [
-            Stat.make('Users').value(42).color('success'),
-            Stat.make('Sessions').value(7),
-          ]
-        }
-      }
-      const data = await UsersStats.make().resolveServerData({} as RenderContext)
-      assert.deepEqual(data, {
-        stats: [
-          { label: 'Users', value: 42, color: 'success' },
-          { label: 'Sessions', value: 7 },
-        ],
-      })
-    })
-
-    it('passes the render context to getStats', async () => {
-      let received: unknown = null
-      class CtxStats extends StatsOverview {
-        static override async getStats(ctx: RenderContext) {
-          received = ctx
-          return []
-        }
-      }
-      await CtxStats.make().resolveServerData({ user: { id: 1 } } as RenderContext)
-      assert.deepEqual(received, { user: { id: 1 } })
-    })
-
-    it('fluent .getStatsHandler(fn) overrides the static', async () => {
-      class StaticStats extends StatsOverview {
-        static override async getStats() { return [Stat.make('Static').value(1)] }
-      }
-      const w = StaticStats.make().getStatsHandler(async () => [Stat.make('Instance').value(2)])
-      const data = await w.resolveServerData({} as RenderContext)
-      assert.deepEqual(data, { stats: [{ label: 'Instance', value: 2 }] })
-    })
-
-    it('returns { stats: [] } when no hook is configured', async () => {
-      const data = await StatsOverview.make('empty').resolveServerData({} as RenderContext)
-      assert.deepEqual(data, { stats: [] })
-    })
-  })
-})

package/src/schema/StatsOverview.ts

@@ -1,119 +0,0 @@
-import { ServerDataElement } from './ServerDataElement.js'
-import type { RenderContext } from './resolveSchema.js'
-import { Stat, type StatMeta } from './Stat.js'
-
-/**
- * Plan #15 Phase B — `StatsOverview` is the KPI-card row widget.
- * Subclasses return an array of `Stat`s from `getStats(ctx)`; the
- * resolver lays them out as a grid of cards.
- *
- * Subclass form (primary):
- *
- *   import { StatsOverview, Stat } from '@pilotiq/pilotiq'
- *
- *   export class UsersStats extends StatsOverview {
- *     static override columns = 3
- *     static override async getStats(ctx) {
- *       return [
- *         Stat.make('Users').value(await User.query().count()).color('success'),
- *         Stat.make('Active sessions').value(await Session.query().active().count()),
- *         Stat.make('Revenue (MTD)').value('$' + total).icon('dollar-sign'),
- *       ]
- *     }
- *   }
- *
- *   // Page.schema()
- *   UsersStats.make()
- *
- * Fluent form (one-off — no subclass):
- *
- *   StatsOverview.make('quick-kpis')
- *     .columns(2)
- *     .getStatsHandler(async () => [Stat.make('Foo').value(1)])
- *
- * Wire-shape:
- *   meta:       { type: 'stats', columns?, serverData, id, lazy[, poll] }
- *   _widgetData[id]: { stats: StatMeta[] }
- *
- * Lazy default = true (inherited from `ServerDataElement`).
- */
-
-export type StatsHandler = (ctx: RenderContext) => Stat[] | Promise<Stat[]>
-
-export interface StatsOverviewPayload {
-  stats: StatMeta[]
-}
-
-export class StatsOverview extends ServerDataElement {
-  /** Subclass-time defaults — read by `make()`-built instances unless
-   *  the fluent setter overrides. Mirrors the `View.componentName /
-   *  getData` precedent. */
-  static columns?: number
-  static getStats?: StatsHandler
-
-  // ─── Instance state (fluent overrides) ─────────────────────
-  private _columns?:   number
-  private _getStats?:  StatsHandler
-
-  // Public for subclass `new this(id)` (matches `View`).
-  constructor(id?: string) {
-    super()
-    if (id) this._id = id
-  }
-
-  static make(this: new (id?: string) => StatsOverview, id?: string): StatsOverview {
-    return new this(id)
-  }
-
-  /** Cards-per-row. Falls back to the static `columns` if the fluent
-   *  setter wasn't called; renderer defaults further to a sensible
-   *  number when neither is set. */
-  columns(n: number): this {
-    this._columns = n
-    return this
-  }
-
-  /** Override the data hook. Useful for the fluent (no-subclass) form;
-   *  for the subclass form prefer `static override async getStats(...)`. */
-  getStatsHandler(fn: StatsHandler): this {
-    this._getStats = fn
-    return this
-  }
-
-  getType(): string { return 'stats' }
-
-  /** Effective columns count. Instance setter wins; static is the
-   *  fallback. Returns `undefined` when neither is set. */
-  getColumns(): number | undefined {
-    if (this._columns !== undefined) return this._columns
-    const ctor = this.constructor as { columns?: number }
-    return ctor.columns
-  }
-
-  toMeta(): Record<string, unknown> {
-    const meta: Record<string, unknown> = { type: 'stats' as const }
-    const cols = this.getColumns()
-    if (cols !== undefined) meta['columns'] = cols
-    return meta
-  }
-
-  /**
-   * Run the configured stats hook. Falls back through:
-   *   1. instance setter (`overview.getStatsHandler(fn)`),
-   *   2. static method on the subclass (`static async getStats(ctx) {…}`),
-   *   3. empty list (`{ stats: [] }`).
-   *
-   * Resolved Stat objects are serialized to JSON-clean `StatMeta`s here
-   * so the renderer doesn't need to know about the `Stat` class.
-   */
-  async resolveServerData(ctx: RenderContext): Promise<StatsOverviewPayload> {
-    let stats: Stat[] = []
-    if (this._getStats) {
-      stats = await this._getStats(ctx)
-    } else {
-      const ctor = this.constructor as { getStats?: StatsHandler }
-      if (ctor.getStats) stats = await ctor.getStats(ctx)
-    }
-    return { stats: stats.map(s => s.toMeta()) }
-  }
-}

package/src/schema/StyleTag.ts

@@ -1,35 +0,0 @@
-import { Element } from './Element.js'
-
-/**
- * Head-safe element — emits an inline `<style>` block inside the panel's
- * `<head>`. Use for CSS-variable overrides, conditional theming, or
- * per-tenant brand colors that need to ship with the SSR document so
- * there's no FOUC.
- *
- * For external stylesheets reach for `LinkTag.make({ rel: 'stylesheet',
- * href: '...' })` instead.
- *
- * @example
- *   Pilotiq.renderHook('panels::styles', ({ user }) => [
- *     StyleTag.make(`
- *       :root { --pilotiq-brand: ${tenantBrand(user)} }
- *     `),
- *   ])
- */
-export class StyleTag extends Element {
-  private constructor(private css: string, private nonce?: string) { super() }
-
-  static make(css: string, opts?: { nonce?: string }): StyleTag {
-    return new StyleTag(css, opts?.nonce)
-  }
-
-  getType(): string { return 'style' }
-
-  toMeta() {
-    return {
-      type: 'style' as const,
-      css:  this.css,
-      ...(this.nonce ? { nonce: this.nonce } : {}),
-    }
-  }
-}