@pilotiq/pilotiq 0.24.1 → 0.24.2

package/src/schema/TableWidget.test.ts

@@ -1,297 +0,0 @@
-/**
- * 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(...args: unknown[]): this { this.ops.push({ op: 'where', args }); return this }
-  orWhere(...args: unknown[]): this { this.ops.push({ op: 'orWhere', args }); 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

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

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