@pilotiq/pilotiq 0.1.0

package/src/schema/TableWidget.test.ts

@@ -0,0 +1,297 @@
+/**
+ * Plan #15 Phase D — `TableWidget` element tests.
+ */
+
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { Column } from '../Column.js'
+import { TableWidget } from './TableWidget.js'
+import { resolveSchema, type RenderContext } from './resolveSchema.js'
+import { isServerDataElement } from './ServerDataElement.js'
+import type { ModelLike, ModelQuery } from '../orm/modelDefaults.js'
+
+// ─── Test stubs ──────────────────────────────────────────────
+
+class StubQuery implements ModelQuery {
+  public readonly ops: Array<{ op: string; args: unknown[] }> = []
+  constructor(private readonly rows: unknown[], private readonly total = rows.length) {}
+  where(): this { this.ops.push({ op: 'where', args: [...arguments] }); return this }
+  orWhere(): this { this.ops.push({ op: 'orWhere', args: [...arguments] }); return this }
+  orderBy(column: string, direction?: 'ASC' | 'DESC'): this {
+    this.ops.push({ op: 'orderBy', args: [column, direction] })
+    return this
+  }
+  async paginate(page: number, perPage?: number): Promise<{ data: unknown[]; total: number }> {
+    this.ops.push({ op: 'paginate', args: [page, perPage] })
+    return { data: this.rows, total: this.total }
+  }
+}
+
+function stubModel(rows: unknown[]): ModelLike {
+  return {
+    async find()    { return undefined },
+    async create()  { return undefined },
+    async update()  { return undefined },
+    async delete()  { return undefined },
+    query() { return new StubQuery(rows) },
+  }
+}
+
+// ─── Tests ──────────────────────────────────────────────────
+
+describe('TableWidget element', () => {
+  describe('factory + identity', () => {
+    it('TableWidget.make() returns an instance', () => {
+      const w = TableWidget.make('recent')
+      assert.ok(w instanceof TableWidget)
+      assert.equal(w.getType(), 'tableWidget')
+    })
+
+    it('falls back to subclass class name when no id passed', () => {
+      class RecentPosts extends TableWidget {}
+      assert.equal(RecentPosts.make().getId(), 'RecentPosts')
+    })
+
+    it('explicit id wins over class name', () => {
+      class RecentPosts extends TableWidget {}
+      assert.equal(RecentPosts.make('explicit').getId(), 'explicit')
+    })
+
+    it('is a ServerDataElement', () => {
+      assert.equal(isServerDataElement(TableWidget.make('a')), true)
+    })
+
+    it('lazy default = true (inherited)', () => {
+      assert.equal(TableWidget.make('a').isLazy(), true)
+    })
+  })
+
+  describe('label / viewAllUrl', () => {
+    it('instance label setter wins over static', () => {
+      class Static extends TableWidget {
+        static override label = 'Static label'
+      }
+      const w = Static.make().label('Instance label')
+      assert.equal(w.getLabel(), 'Instance label')
+    })
+
+    it('static label is the fallback', () => {
+      class Static extends TableWidget {
+        static override label = 'Static label'
+      }
+      assert.equal(Static.make().getLabel(), 'Static label')
+    })
+
+    it('returns undefined when neither set', () => {
+      assert.equal(TableWidget.make('a').getLabel(), undefined)
+    })
+
+    it('viewAllUrl: instance wins over static', () => {
+      class Static extends TableWidget {
+        static override viewAllUrl = '/static'
+      }
+      assert.equal(Static.make().viewAllUrl('/instance').getViewAllUrl(), '/instance')
+    })
+
+    it('viewAllUrl: static is the fallback', () => {
+      class Static extends TableWidget {
+        static override viewAllUrl = '/static'
+      }
+      assert.equal(Static.make().getViewAllUrl(), '/static')
+    })
+  })
+
+  describe('columns', () => {
+    it('instance columns wins over static factory', () => {
+      class Static extends TableWidget {
+        static override columns = () => [Column.make('static')]
+      }
+      const w = Static.make().columns([Column.make('instance')])
+      assert.equal(w.getColumns().length, 1)
+      assert.equal(w.getColumns()[0]!.name, 'instance')
+    })
+
+    it('static columns() factory is the fallback', () => {
+      class Static extends TableWidget {
+        static override columns = () => [Column.make('a'), Column.make('b')]
+      }
+      const cols = Static.make().getColumns()
+      assert.equal(cols.length, 2)
+      assert.equal(cols[0]!.name, 'a')
+    })
+
+    it('returns [] when no columns configured', () => {
+      assert.deepEqual(TableWidget.make('a').getColumns(), [])
+    })
+  })
+
+  describe('toMeta()', () => {
+    it('emits type=tableWidget with empty columns by default', async () => {
+      const [meta] = await resolveSchema([TableWidget.make('a')])
+      assert.equal(meta!.type, 'tableWidget')
+      assert.deepEqual(meta!['columns'], [])
+    })
+
+    it('serializes columns inline (not as children)', async () => {
+      const [meta] = await resolveSchema([
+        TableWidget.make('a').columns([Column.make('title').label('Title')]),
+      ])
+      assert.equal(Array.isArray(meta!['columns']), true)
+      assert.equal((meta!['columns'] as unknown[]).length, 1)
+      assert.equal(((meta!['columns'] as Array<{ name: string; label: string }>)[0])!.label, 'Title')
+      assert.equal(meta!.children, undefined)
+    })
+
+    it('emits label + viewAllUrl when set', async () => {
+      const [meta] = await resolveSchema([
+        TableWidget.make('a').label('Recent').viewAllUrl('/all'),
+      ])
+      assert.equal(meta!['label'], 'Recent')
+      assert.equal(meta!['viewAllUrl'], '/all')
+    })
+
+    it('omits label + viewAllUrl when unset', async () => {
+      const [meta] = await resolveSchema([TableWidget.make('a')])
+      assert.equal(meta!['label'], undefined)
+      assert.equal(meta!['viewAllUrl'], undefined)
+    })
+
+    it('serverData wire-shape stamps land on top', async () => {
+      class W extends TableWidget {}
+      const w = W.make().poll(60).lazy(false)
+      const [meta] = await resolveSchema([w])
+      assert.equal(meta!['serverData'], true)
+      assert.equal(meta!['id'], 'W')
+      assert.equal(meta!['poll'], 60)
+      assert.equal(meta!['lazy'], false)
+    })
+  })
+
+  describe('resolveServerData() — fluent records', () => {
+    it('runs the instance .records(fn) hook', async () => {
+      const w = TableWidget.make('a').records(async () => ({
+        rows:  [{ id: 1, title: 'Hello' }],
+        total: 1,
+      }))
+      const data = await w.resolveServerData({} as RenderContext)
+      assert.deepEqual(data, { rows: [{ id: 1, title: 'Hello' }], total: 1 })
+    })
+
+    it('omits total when records() did', async () => {
+      const w = TableWidget.make('a').records(async () => ({ rows: [{ id: 1 }] }))
+      const data = await w.resolveServerData({} as RenderContext)
+      assert.deepEqual(data, { rows: [{ id: 1 }] })
+    })
+
+    it('passes the render context to records()', async () => {
+      let received: unknown = null
+      const w = TableWidget.make('a').records(async (ctx) => {
+        received = ctx
+        return { rows: [] }
+      })
+      await w.resolveServerData({ user: { id: 1 } } as RenderContext)
+      assert.deepEqual(received, { user: { id: 1 } })
+    })
+  })
+
+  describe('resolveServerData() — subclass records', () => {
+    it('subclass static records() runs when no instance setter', async () => {
+      class Sub extends TableWidget {
+        static override async records() {
+          return { rows: [{ id: 1 }], total: 1 }
+        }
+      }
+      const data = await Sub.make().resolveServerData({} as RenderContext)
+      assert.deepEqual(data, { rows: [{ id: 1 }], total: 1 })
+    })
+
+    it('instance .records() overrides static records()', async () => {
+      class Sub extends TableWidget {
+        static override async records() {
+          return { rows: [{ id: 'static' }] }
+        }
+      }
+      const w = Sub.make().records(async () => ({ rows: [{ id: 'instance' }] }))
+      const data = await w.resolveServerData({} as RenderContext)
+      assert.deepEqual(data, { rows: [{ id: 'instance' }] })
+    })
+  })
+
+  describe('resolveServerData() — model + query', () => {
+    it('default model path uses paginate(1, 5)', async () => {
+      const M = stubModel([{ id: 1 }, { id: 2 }])
+      const w = TableWidget.make('a').model(M)
+      const data = await w.resolveServerData({} as RenderContext)
+      assert.deepEqual(data.rows, [{ id: 1 }, { id: 2 }])
+      assert.equal(data.total, 2)
+    })
+
+    it('custom .query(fn) drives the model query', async () => {
+      const M = stubModel([{ id: 1 }])
+      let saw: ModelQuery | undefined
+      const w = TableWidget.make('a').model(M).query(async (q) => {
+        saw = q
+        return q.orderBy('id', 'DESC').paginate(1, 3)
+      })
+      await w.resolveServerData({} as RenderContext)
+      const ops = (saw as unknown as StubQuery).ops
+      assert.equal(ops[0]!.op, 'orderBy')
+      assert.equal(ops[1]!.op, 'paginate')
+      assert.deepEqual(ops[1]!.args, [1, 3])
+    })
+
+    it('static query() on subclass is honored when instance has none', async () => {
+      const M = stubModel([{ id: 99 }])
+      class Sub extends TableWidget {
+        static override model = M
+        static override query = async (q: ModelQuery) =>
+          q.orderBy('createdAt', 'DESC').paginate(1, 7)
+      }
+      const w = Sub.make()
+      const data = await w.resolveServerData({} as RenderContext)
+      assert.deepEqual(data.rows, [{ id: 99 }])
+    })
+
+    it('throws when no records source is configured', async () => {
+      await assert.rejects(
+        () => TableWidget.make('a').resolveServerData({} as RenderContext),
+        /no rows source/,
+      )
+    })
+  })
+
+  describe('resolveServerData() — formatStateUsing per row', () => {
+    it('runs server-side formatters and stamps row._formatted', async () => {
+      const w = TableWidget.make('a')
+        .columns([
+          Column.make('title').formatStateUsing((value) => `> ${value}`),
+          Column.make('plain'),
+        ])
+        .records(async () => ({
+          rows: [{ title: 'Hello', plain: 'untouched' }],
+        }))
+      const data = await w.resolveServerData({} as RenderContext)
+      const row = data.rows[0]!
+      assert.deepEqual(row['_formatted'], { title: '> Hello' })
+      assert.equal(row['plain'], 'untouched')
+    })
+
+    it('skipped entirely when no column has a formatter', async () => {
+      const w = TableWidget.make('a')
+        .columns([Column.make('title')])
+        .records(async () => ({ rows: [{ title: 'Hello' }] }))
+      const data = await w.resolveServerData({} as RenderContext)
+      assert.equal(data.rows[0]!['_formatted'], undefined)
+    })
+
+    it('throwing formatter falls back silently', async () => {
+      const w = TableWidget.make('a')
+        .columns([Column.make('title').formatStateUsing(() => { throw new Error('boom') })])
+        .records(async () => ({ rows: [{ title: 'Hello' }] }))
+      const data = await w.resolveServerData({} as RenderContext)
+      // No `title` key on `_formatted` — renderer falls back to raw value.
+      assert.deepEqual(data.rows[0]!['_formatted'], {})
+    })
+  })
+})

package/src/schema/TableWidget.ts

@@ -0,0 +1,289 @@
+import { ServerDataElement } from './ServerDataElement.js'
+import type { RenderContext } from './resolveSchema.js'
+import { Column, type ColumnMeta } from '../Column.js'
+import {
+  type ModelLike,
+  type ModelQuery,
+} from '../orm/modelDefaults.js'
+
+/**
+ * Plan #15 Phase D — `TableWidget` is the slim-table dashboard widget.
+ * Mirrors Filament's `Filament\Widgets\TableWidget`: a dashboard tile
+ * that surfaces a small list of records (e.g. "5 newest posts") without
+ * the full Resource list-page chrome (no filters, no bulk actions, no
+ * pagination, no search).
+ *
+ * Distinct from the schema-element `Table` (`elements/Table.ts`) — that
+ * one drives Resource list pages and carries the full surface. The
+ * widget renders a stripped-down `<table>` paint and reads its rows from
+ * `_widgetData[id]`.
+ *
+ * **Subclass form** (primary):
+ *
+ *   import { TableWidget } from '@pilotiq/pilotiq'
+ *   import { TextColumn } from '@pilotiq/pilotiq/columns'
+ *   import { Post } from '#models'
+ *
+ *   export class RecentPosts extends TableWidget {
+ *     static override label = 'Recent posts'
+ *     static override model = Post
+ *     static override viewAllUrl = '/admin/posts'
+ *     static override async query(q) {
+ *       return q.orderBy('createdAt', 'desc').paginate(1, 5)
+ *     }
+ *     static override columns() {
+ *       return [
+ *         TextColumn.make('title').limit(40),
+ *         TextColumn.make('createdAt').dateTime(),
+ *       ]
+ *     }
+ *   }
+ *
+ * **Fluent form** — useful for one-off cases:
+ *
+ *   TableWidget.make('recent-posts')
+ *     .label('Recent posts')
+ *     .columns([Column.make('title')])
+ *     .records(async () => ({ rows: [{ title: 'Hi' }], total: 1 }))
+ *     .viewAllUrl('/admin/posts')
+ *
+ * Wire-shape:
+ *   meta:           { type: 'tableWidget', label?, viewAllUrl?, columns: ColumnMeta[],
+ *                     serverData, id, lazy[, poll] }
+ *   _widgetData[id]: { rows: Record<string, unknown>[]; total?: number }
+ *
+ * Lazy default = true (inherited from `ServerDataElement`).
+ */
+
+/** Result returned by `records()` — rows plus optional total. The total
+ *  is informational only in v1 (no pagination in the slim renderer);
+ *  reserved for future "View all (24)" badge sugar. */
+export interface TableWidgetRecordsResult {
+  rows:   Record<string, unknown>[]
+  total?: number
+}
+
+export type TableWidgetRecordsHandler = (
+  ctx: RenderContext,
+) => TableWidgetRecordsResult | Promise<TableWidgetRecordsResult>
+
+/**
+ * Subclass-form `query(q)` hook — receives a `ModelQuery` from
+ * `static model.query()` and returns a `Promise<{ data, total }>`. The
+ * `paginate()` call lives inside the hook so users control limit (e.g.
+ * `q.orderBy(...).paginate(1, 5)` for "5 newest").
+ *
+ * Returning the bare query (without `paginate()`) is a programming error
+ * — the widget needs an awaited result, not another query builder.
+ */
+export type TableWidgetQueryHandler = (
+  q: ModelQuery,
+) => Promise<{ data: unknown[]; total: number }>
+
+export interface TableWidgetPayload {
+  rows:   Record<string, unknown>[]
+  total?: number
+}
+
+export class TableWidget extends ServerDataElement {
+  // ─── Subclass-time defaults ──────────────────────────────
+  /** Heading rendered above the table. Falls back to the class name when
+   *  unset and `viewAllUrl` is set (the link needs visible chrome). */
+  static label?: string
+  /** Optional ORM model — when set, default `records()` does
+   *  `M.query()` then runs the configured `query()` hook (which must
+   *  paginate to bound the row count). */
+  static model?: ModelLike
+  /** Optional "View all →" link href shown in the widget header. */
+  static viewAllUrl?: string
+  /** Subclass-form column factory. Called once per resolve; instance
+   *  setter wins. */
+  static columns?: () => Column[]
+  /** Subclass-form query hook (model-driven path). Falls back to a
+   *  bare `paginate(1, 5)` when unset. */
+  static query?: TableWidgetQueryHandler
+  /** Subclass-form full-records override. When set, takes precedence
+   *  over `model + query`. */
+  static records?: TableWidgetRecordsHandler
+
+  // ─── Instance state (fluent overrides) ──────────────────
+  private _label?:       string
+  private _model?:       ModelLike
+  private _viewAllUrl?:  string
+  private _columns?:     Column[]
+  private _query?:       TableWidgetQueryHandler
+  private _records?:     TableWidgetRecordsHandler
+
+  constructor(id?: string) {
+    super()
+    if (id) this._id = id
+  }
+
+  static make(this: new (id?: string) => TableWidget, id?: string): TableWidget {
+    return new this(id)
+  }
+
+  // ─── Fluent setters ──────────────────────────────────────
+
+  /** Heading rendered above the table. */
+  label(text: string): this {
+    this._label = text
+    return this
+  }
+
+  /** Bind a `ModelLike` for the default model-driven records loader. */
+  model(M: ModelLike): this {
+    this._model = M
+    return this
+  }
+
+  /** Custom query hook — receives `M.query()` and must return a
+   *  `paginate()` promise. Composes with `.model(M)`. */
+  query(fn: TableWidgetQueryHandler): this {
+    this._query = fn
+    return this
+  }
+
+  /** Full records override — fully replaces the `model + query` path. */
+  records(fn: TableWidgetRecordsHandler): this {
+    this._records = fn
+    return this
+  }
+
+  /** Column children. The renderer reads label / format / columnType /
+   *  formatter from each column's resolved meta — same shape as the
+   *  Resource list table. Columns are serialized inline under
+   *  `meta.columns` (not under `meta.children`) so the resolver doesn't
+   *  treat them as standalone nodes. */
+  columns(cols: Column[]): this {
+    this._columns = cols
+    return this
+  }
+
+  /** "View all →" link href. */
+  viewAllUrl(href: string): this {
+    this._viewAllUrl = href
+    return this
+  }
+
+  // ─── Getters ─────────────────────────────────────────────
+
+  /** Effective label. Instance setter wins; static is the fallback. */
+  getLabel(): string | undefined {
+    if (this._label !== undefined) return this._label
+    const ctor = this.constructor as { label?: string }
+    return ctor.label
+  }
+
+  /** Effective viewAllUrl. */
+  getViewAllUrl(): string | undefined {
+    if (this._viewAllUrl !== undefined) return this._viewAllUrl
+    const ctor = this.constructor as { viewAllUrl?: string }
+    return ctor.viewAllUrl
+  }
+
+  /** Effective model. */
+  getModel(): ModelLike | undefined {
+    if (this._model !== undefined) return this._model
+    const ctor = this.constructor as { model?: ModelLike }
+    return ctor.model
+  }
+
+  /** Effective columns. Instance setter wins; static factory is the
+   *  fallback. Empty array when neither is set. */
+  getColumns(): Column[] {
+    if (this._columns !== undefined) return this._columns
+    const ctor = this.constructor as { columns?: () => Column[] }
+    if (typeof ctor.columns === 'function') {
+      const out = ctor.columns()
+      this._columns = out
+      return out
+    }
+    return []
+  }
+
+  override getType(): string { return 'tableWidget' }
+
+  override toMeta(): Record<string, unknown> {
+    const meta: Record<string, unknown> = { type: 'tableWidget' as const }
+    const label = this.getLabel()
+    if (label !== undefined) meta['label'] = label
+    const url = this.getViewAllUrl()
+    if (url !== undefined) meta['viewAllUrl'] = url
+    meta['columns'] = this.getColumns().map(c => c.toMeta() as ColumnMeta)
+    return meta
+  }
+
+  // ─── Server-data resolve ────────────────────────────────
+
+  /**
+   * Run the configured row loader. Falls back through:
+   *   1. instance `.records(fn)` setter,
+   *   2. subclass `static records(ctx)`,
+   *   3. instance `.model(M) + .query(fn)`,
+   *   4. subclass `static model + static query?(q)`,
+   *   5. error — at least one path must be configured.
+   *
+   * The default `query` hook (when only `model` is set) is
+   * `q => q.paginate(1, 5)`. Override on the subclass for "10 newest"
+   * etc.
+   */
+  async resolveServerData(ctx: RenderContext): Promise<TableWidgetPayload> {
+    let payload: TableWidgetPayload
+
+    if (this._records) {
+      payload = this.normalizeResult(await this._records(ctx))
+    } else {
+      const ctor = this.constructor as { records?: TableWidgetRecordsHandler }
+      if (ctor.records) {
+        payload = this.normalizeResult(await ctor.records(ctx))
+      } else {
+        const M = this.getModel()
+        if (!M) {
+          throw new Error(
+            `[Pilotiq] TableWidget "${this.getId()}" has no rows source — call .records(fn), ` +
+            `.model(M).query(fn), or set static model / records / columns on the subclass.`,
+          )
+        }
+        const q  = M.query()
+        const fn = this._query ?? (this.constructor as { query?: TableWidgetQueryHandler }).query ?? defaultQueryHook
+        const result = await fn(q)
+        payload = result.total !== undefined
+          ? { rows: (result.data as Record<string, unknown>[]) ?? [], total: result.total }
+          : { rows: (result.data as Record<string, unknown>[]) ?? [] }
+      }
+    }
+
+    // Per-row server-side `formatStateUsing` — same convention as the
+    // full `Table` (`row._formatted[colName]`). Skipped when no column
+    // has a formatter so we don't allocate per-row in the common case.
+    const columnsWithFormatter = this.getColumns().filter(c => c.hasFormatter())
+    if (columnsWithFormatter.length > 0) {
+      payload.rows = payload.rows.map(row => {
+        const formatted: Record<string, string> = {}
+        for (const col of columnsWithFormatter) {
+          const fn = col.getFormatStateHandler()
+          if (!fn) continue
+          try { formatted[col.name] = fn(row[col.name], row) }
+          catch { /* fall back to raw value in renderer */ }
+        }
+        return { ...row, _formatted: formatted }
+      })
+    }
+
+    return payload
+  }
+
+  private normalizeResult(r: TableWidgetRecordsResult): TableWidgetPayload {
+    return r.total !== undefined
+      ? { rows: r.rows, total: r.total }
+      : { rows: r.rows }
+  }
+}
+
+/** Default query hook — paginate to the first 5 rows. Users override on
+ *  the subclass (`static async query(q) { return q.orderBy(...).paginate(1, 10) }`)
+ *  or via the instance setter for limits / sorts. */
+function defaultQueryHook(q: ModelQuery): Promise<{ data: unknown[]; total: number }> {
+  return q.paginate(1, 5)
+}

package/src/schema/Tabs.ts

@@ -0,0 +1,79 @@
+import { Element } from './Element.js'
+
+/**
+ * Single tab within a `Tabs` container. Holds a label, optional icon/badge,
+ * and a list of child Elements. Resolves to its own meta entry inside the
+ * parent's children array.
+ */
+export class Tab extends Element {
+  private _icon?: string
+  private _badge?: string
+
+  private constructor(private _label: string) {
+    super()
+  }
+
+  static make(label: string): Tab {
+    return new Tab(label)
+  }
+
+  icon(i: string): this { this._icon = i; return this }
+  badge(b: string): this { this._badge = b; return this }
+
+  schema(elements: Element[]): this {
+    this._children = elements
+    return this
+  }
+
+  getType(): string { return 'tab' }
+
+  toMeta(): Record<string, unknown> {
+    return {
+      type: 'tab' as const,
+      label: this._label,
+      ...(this._icon  ? { icon:  this._icon  } : {}),
+      ...(this._badge ? { badge: this._badge } : {}),
+    }
+  }
+}
+
+export type TabsVariant = 'pills' | 'underline'
+
+/**
+ * Multi-tab container. Children are `Tab` instances; each Tab has its own
+ * children rendered when its tab is active. Mirrors panels' `Tabs` element
+ * for the static case (model-backed and array-backed Tabs are a future
+ * extension).
+ */
+export class Tabs extends Element {
+  private _variant: TabsVariant = 'pills'
+
+  private constructor() {
+    super()
+  }
+
+  static make(): Tabs {
+    return new Tabs()
+  }
+
+  /** Set the tab list. Each entry is a `Tab` instance with its own schema. */
+  tabs(tabs: Tab[]): this {
+    this._children = tabs
+    return this
+  }
+
+  /**
+   * Visual style. `'pills'` (default) — shadcn pill background with sliding
+   * indicator. `'underline'` — bottom border on active tab.
+   */
+  variant(v: TabsVariant): this {
+    this._variant = v
+    return this
+  }
+
+  getType(): string { return 'tabs' }
+
+  toMeta(): Record<string, unknown> {
+    return { type: 'tabs' as const, variant: this._variant }
+  }
+}