@pilotiq/pilotiq 0.1.0

package/src/schema/Text.ts

@@ -0,0 +1,58 @@
+import { Element } from './Element.js'
+import type { BadgeColor } from '../columns/BadgeColumn.js'
+
+export type TextColor =
+  | 'default'
+  | 'muted'
+  | 'primary'
+  | 'destructive'
+  | 'success'
+  | 'warning'
+  | 'info'
+
+export type TextSize   = 'xs' | 'sm' | 'base' | 'lg' | 'xl'
+export type TextWeight = 'normal' | 'medium' | 'semibold' | 'bold'
+
+export class Text extends Element {
+  private _color?:  TextColor
+  private _size?:   TextSize
+  private _weight?: TextWeight
+  private _badge        = false
+  private _badgeColor?: BadgeColor
+
+  private constructor(private content: string) {
+    super()
+  }
+
+  static make(content: string): Text {
+    return new Text(content)
+  }
+
+  color(c: TextColor): this   { this._color = c; return this }
+  size(s: TextSize): this     { this._size = s; return this }
+  weight(w: TextWeight): this { this._weight = w; return this }
+
+  /** Render the content as a pill/badge instead of plain text.
+   *  Pair with `.badgeColor()` for tinted variants. */
+  badge(v = true): this { this._badge = v; return this }
+
+  badgeColor(c: BadgeColor): this {
+    this._badgeColor = c
+    this._badge = true
+    return this
+  }
+
+  getType(): string { return 'text' }
+
+  toMeta() {
+    return {
+      type:    'text' as const,
+      content: this.content,
+      ...(this._color       ? { color:      this._color }       : {}),
+      ...(this._size        ? { size:       this._size }        : {}),
+      ...(this._weight      ? { weight:     this._weight }      : {}),
+      ...(this._badge       ? { badge:      true }              : {}),
+      ...(this._badgeColor  ? { badgeColor: this._badgeColor }  : {}),
+    }
+  }
+}

package/src/schema/UnorderedList.ts

@@ -0,0 +1,49 @@
+import { Element } from './Element.js'
+import type { TextColor, TextSize, TextWeight } from './Text.js'
+
+/**
+ * Read-only bullet list prime — sibling of `Heading / Text / Alert / Divider`.
+ *
+ * Items are plain strings stamped at schema build time. For dynamic data,
+ * compose with Resource state in your schema callback (the items array
+ * accepts the result of any expression).
+ *
+ * Cosmetic chrome mirrors `Text` — `color / size / weight` flow through to
+ * each `<li>` so the list reads consistently against neighbouring text in
+ * a detail view.
+ */
+export class UnorderedList extends Element {
+  private _items: string[]
+  private _color?:  TextColor
+  private _size?:   TextSize
+  private _weight?: TextWeight
+
+  private constructor(items: string[]) {
+    super()
+    this._items = items
+  }
+
+  /** Create a list. Pass the items inline or via `.items()` later. */
+  static make(items: string[] = []): UnorderedList {
+    return new UnorderedList(items)
+  }
+
+  /** Replace the items array. Last call wins. */
+  items(items: string[]): this { this._items = items; return this }
+
+  color(c: TextColor): this   { this._color = c; return this }
+  size(s: TextSize): this     { this._size = s; return this }
+  weight(w: TextWeight): this { this._weight = w; return this }
+
+  getType(): string { return 'unorderedList' }
+
+  toMeta() {
+    return {
+      type:  'unorderedList' as const,
+      items: this._items,
+      ...(this._color  ? { color:  this._color  } : {}),
+      ...(this._size   ? { size:   this._size   } : {}),
+      ...(this._weight ? { weight: this._weight } : {}),
+    }
+  }
+}

package/src/schema/View.test.ts

@@ -0,0 +1,111 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { View } from './View.js'
+import { resolveSchema, type RenderContext } from './resolveSchema.js'
+import { isServerDataElement } from './ServerDataElement.js'
+
+describe('View element', () => {
+  describe('factory + identity', () => {
+    it('View.make() returns a View instance', () => {
+      const v = View.make('foo')
+      assert.ok(v instanceof View)
+      assert.equal(v.getType(), 'view')
+    })
+
+    it('falls back to subclass class name when no id passed', () => {
+      class ContributionMap extends View {}
+      const v = ContributionMap.make()
+      assert.equal(v.getId(), 'ContributionMap')
+    })
+
+    it('explicit id wins over class name', () => {
+      class ContributionMap extends View {}
+      const v = ContributionMap.make('explicit-id')
+      assert.equal(v.getId(), 'explicit-id')
+    })
+
+    it('is a ServerDataElement', () => {
+      assert.equal(isServerDataElement(View.make('a')), true)
+    })
+  })
+
+  describe('component lookup name', () => {
+    it('uses the static componentName from the subclass', () => {
+      class ContributionMap extends View {
+        static override componentName = 'CalendarHeatmap'
+      }
+      assert.equal(ContributionMap.make().getComponentName(), 'CalendarHeatmap')
+    })
+
+    it('fluent .component(name) overrides the static', () => {
+      class ContributionMap extends View {
+        static override componentName = 'CalendarHeatmap'
+      }
+      const v = ContributionMap.make().component('OtherComponent')
+      assert.equal(v.getComponentName(), 'OtherComponent')
+    })
+
+    it('falls back to id when no componentName is set', () => {
+      const v = View.make('my-widget')
+      assert.equal(v.getComponentName(), 'my-widget')
+    })
+  })
+
+  describe('toMeta()', () => {
+    it('emits type and component', async () => {
+      class ContributionMap extends View {
+        static override componentName = 'CalendarHeatmap'
+      }
+      const [meta] = await resolveSchema([ContributionMap.make()])
+      assert.equal(meta!.type, 'view')
+      assert.equal(meta!['component'], 'CalendarHeatmap')
+    })
+
+    it('serverData wire-shape stamps land on top', async () => {
+      class ContributionMap extends View {
+        static override componentName = 'CalendarHeatmap'
+      }
+      const v = ContributionMap.make().poll(60).lazy(false)
+      const [meta] = await resolveSchema([v])
+      assert.equal(meta!['serverData'], true)
+      assert.equal(meta!['id'], 'ContributionMap')
+      assert.equal(meta!['poll'], 60)
+      assert.equal(meta!['lazy'], false)
+    })
+  })
+
+  describe('resolveServerData()', () => {
+    it('runs the static getData hook', async () => {
+      class StatsView extends View {
+        static override async getData() { return { total: 42 } }
+      }
+      const v = StatsView.make()
+      const data = await v.resolveServerData({} as RenderContext)
+      assert.deepEqual(data, { total: 42 })
+    })
+
+    it('passes the render context', async () => {
+      let received: unknown = null
+      class StatsView extends View {
+        static override async getData(ctx: RenderContext) { received = ctx; return null }
+      }
+      await StatsView.make().resolveServerData({ user: { id: 1 } } as RenderContext)
+      assert.deepEqual(received, { user: { id: 1 } })
+    })
+
+    it('fluent .getDataHandler(fn) overrides the static', async () => {
+      class StatsView extends View {
+        static override async getData() { return 'static' }
+      }
+      const v = StatsView.make().getDataHandler(async () => 'instance')
+      const data = await v.resolveServerData({} as RenderContext)
+      assert.equal(data, 'instance')
+    })
+
+    it('returns null when no hook is configured', async () => {
+      const v = View.make('empty')
+      assert.equal(await v.resolveServerData({} as RenderContext), null)
+    })
+  })
+})

package/src/schema/View.ts

@@ -0,0 +1,127 @@
+import { ServerDataElement } from './ServerDataElement.js'
+import type { RenderContext } from './resolveSchema.js'
+
+/**
+ * Plan #15 — `View` is the escape-hatch widget. Drops down to a
+ * user-supplied React component, optionally fed by a server-side
+ * `getData(ctx)` hook. Useful when the built-in widgets (Stat / Chart /
+ * Table) don't fit — calendar heatmaps, custom map embeds, anything
+ * one-off enough to not warrant a new built-in.
+ *
+ * Two usage patterns:
+ *
+ * **Subclass form** — extend `View` so the component reference + data
+ * hook both live as statics on a stable class:
+ *
+ *   import { View } from '@pilotiq/pilotiq'
+ *   export class ContributionMap extends View {
+ *     static columnSpan = 3
+ *     static componentName = 'CalendarHeatmap'
+ *     static async getData(ctx) {
+ *       return { days: await Activity.query().last(365).countByDay() }
+ *     }
+ *   }
+ *
+ *   // bootstrap/providers.ts
+ *   registerWidgetComponents({ CalendarHeatmap })
+ *
+ *   // Page.schema()
+ *   ContributionMap.make()
+ *
+ * **Fluent form** — for one-off cases where a subclass is overkill:
+ *
+ *   View.make('contribs')
+ *     .component('CalendarHeatmap')
+ *     .getData(async () => ({ days: ... }))
+ *
+ * The component receives `{ data }` as its sole prop (resolved from
+ * `getData / resolveServerData`). Components are looked up at render
+ * through the `widgets/registry` (see `registerWidgetComponents`).
+ */
+
+export type ViewDataHandler = (ctx: RenderContext) => unknown | Promise<unknown>
+
+export class View extends ServerDataElement {
+  /**
+   * Component name used to look up the registered React component at
+   * render time. Subclasses set this as a static; the fluent form sets
+   * it via `.component(name)`.
+   *
+   * (Despite the name, this is a *string key* into the runtime registry,
+   * not a component reference itself — keeps `View` shippable through
+   * `viewProps` and avoids the `_components.ts` manifest walker.)
+   */
+  static componentName?: string
+
+  /** Subclass-time getData hook. The fluent setter overrides this. */
+  static getData?: ViewDataHandler
+
+  // ─── Instance state (fluent overrides) ────────────────────
+  private _componentName?: string
+  private _getData?:       ViewDataHandler
+
+  // Public for `make()`'s `new this(id)` factory call from subclasses —
+  // a protected ctor here breaks `class Foo extends View {}; Foo.make()`
+  // because the typeof Foo signature wouldn't satisfy `new (id?) => View`.
+  constructor(id?: string) {
+    super()
+    if (id) this._id = id
+  }
+
+  /**
+   * Factory. Optional id — when omitted, `getId()` falls back to the
+   * subclass's class name (e.g. `ContributionMap`). Pass an explicit id
+   * when two instances of the same subclass appear on the same page,
+   * or for the bare `View.make('foo')` fluent form (no subclass to
+   * derive a name from).
+   */
+  static make(this: new (id?: string) => View, id?: string): View {
+    return new this(id)
+  }
+
+  /** Set / override the registered component name. */
+  component(name: string): this {
+    this._componentName = name
+    return this
+  }
+
+  /** Set / override the data handler. */
+  getDataHandler(fn: ViewDataHandler): this {
+    this._getData = fn
+    return this
+  }
+
+  getType(): string { return 'view' }
+
+  /** Resolve the effective component name (instance > static > fallback to id). */
+  getComponentName(): string {
+    if (this._componentName) return this._componentName
+    const ctor = this.constructor as { componentName?: string }
+    if (ctor.componentName) return ctor.componentName
+    // Last resort — use the element's id so a subclass that forgets to
+    // declare a `componentName` static still has a deterministic lookup
+    // key. The renderer surfaces a "component not registered" error
+    // when the registry doesn't carry it.
+    return this.getId()
+  }
+
+  toMeta(): Record<string, unknown> {
+    return {
+      type:      'view' as const,
+      component: this.getComponentName(),
+    }
+  }
+
+  /**
+   * Run the configured `getData(ctx)`. Falls back through:
+   *   1. instance setter (`view.getDataHandler(fn)`),
+   *   2. static method on the subclass (`static async getData(ctx) {…}`),
+   *   3. `null` (View renders the component with `data: null`).
+   */
+  async resolveServerData(ctx: RenderContext): Promise<unknown> {
+    if (this._getData) return this._getData(ctx)
+    const ctor = this.constructor as { getData?: ViewDataHandler }
+    if (ctor.getData) return ctor.getData(ctx)
+    return null
+  }
+}

package/src/schema/Wizard.ts

@@ -0,0 +1,108 @@
+import { Element } from './Element.js'
+
+/**
+ * Single step inside a `Wizard`. Holds a label, optional icon/description,
+ * and a list of child Elements. Children resolve unconditionally on every
+ * Wizard render so cross-step `$get` (Plan #5) sees values from every step,
+ * but the renderer only paints the *active* step's children.
+ */
+export class Step extends Element {
+  private _icon?: string
+  private _description?: string
+
+  private constructor(private _label: string) {
+    super()
+  }
+
+  static make(label: string): Step {
+    return new Step(label)
+  }
+
+  /** Icon shown next to the step label (registry key). */
+  icon(name: string): this { this._icon = name; return this }
+
+  /** Optional helper text rendered under the step label inside the indicator. */
+  description(d: string): this { this._description = d; return this }
+
+  /** Set the step's children. Any Element type is accepted. */
+  schema(elements: Element[]): this {
+    this._children = elements
+    return this
+  }
+
+  getType(): string { return 'step' }
+
+  toMeta(): Record<string, unknown> {
+    return {
+      type:  'step' as const,
+      label: this._label,
+      ...(this._icon        ? { icon:        this._icon        } : {}),
+      ...(this._description ? { description: this._description } : {}),
+    }
+  }
+}
+
+/**
+ * Multi-step form layout. Wraps a list of `Step` containers with an
+ * indicator strip + Back / Next chrome. Submit semantics are unchanged
+ * — the surrounding `Form`'s Save fires only when the user is on the
+ * final step (the Next button mutates to "Save" or the page-level
+ * action becomes visible — see SchemaRenderer's WizardRenderer).
+ *
+ * Validation: on Next click, the client POSTs `{ step, values }` to the
+ * Form's `wizardUrl` (when set — Plan #8 step 7 wires the endpoint).
+ * 200 → advance; 422 → stamp inline errors. When `wizardUrl` is absent
+ * (e.g. forms without per-step validation), Next advances immediately.
+ *
+ * Cross-step `$get`: every Step's children are resolved on each
+ * RenderContext, so a step-2 `Section.visible(({ $get }) => $get('emailFromStep0'))`
+ * works. Inactive steps are hidden client-side via `display: none`,
+ * which keeps controlled inputs in the DOM and preserves their values.
+ */
+export class Wizard extends Element {
+  private _skippable = false
+  private _startOnStep = 0
+  private _persist = true
+
+  private constructor() { super() }
+
+  static make(): Wizard {
+    return new Wizard()
+  }
+
+  /** Set the step list. Each entry is a `Step` instance with its own schema. */
+  steps(steps: Step[]): this {
+    this._children = steps
+    return this
+  }
+
+  /**
+   * Allow the user to click any step indicator to jump there. When `true`,
+   * jumping forward still validates intermediate steps in order. When
+   * `false` (default), step indicators ahead of the current step are
+   * disabled.
+   */
+  skippable(v = true): this { this._skippable = v; return this }
+
+  /** Initial step index. Default 0. */
+  startOnStep(n: number): this { this._startOnStep = n; return this }
+
+  /**
+   * Persist the active step to localStorage so refresh / SPA-nav keeps
+   * the user on the same step. Default `true`. Disable for ephemeral
+   * Wizards (e.g. inline modal flows) where you'd rather always start
+   * fresh.
+   */
+  persist(v: boolean): this { this._persist = v; return this }
+
+  getType(): string { return 'wizard' }
+
+  toMeta(): Record<string, unknown> {
+    return {
+      type:        'wizard' as const,
+      skippable:   this._skippable,
+      startOnStep: this._startOnStep,
+      persist:     this._persist,
+    }
+  }
+}