@pilotiq/pilotiq 0.1.0

package/src/schema/Stat.ts

@@ -0,0 +1,154 @@
+/**
+ * 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

@@ -0,0 +1,141 @@
+/**
+ * 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

@@ -0,0 +1,119 @@
+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

@@ -0,0 +1,35 @@
+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 } : {}),
+    }
+  }
+}