@pilotiq/pilotiq 0.23.1 → 0.24.2

package/src/schema/Text.ts

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

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

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

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

@@ -1,220 +0,0 @@
-import { Element } from './Element.js'
-import type { Action } from '../actions/Action.js'
-
-/**
- * Customizer for the wizard's built-in nav buttons (`submitAction`,
- * `nextAction`, `previousAction`). Pass an `Action` to replace the
- * default outright, or a function that receives the framework-built
- * default and returns a customized clone.
- *
- * Only chrome carries through to the renderer (label / icon / color /
- * size / outlined / iconOnly / tooltip / disabled rules). The button's
- * click behavior stays hardwired to advance / recede / submit-form —
- * dispatch overrides (`.handler()`, `.action()`, `.href()`) are
- * intentionally ignored so the wizard chrome never breaks navigation.
- */
-export type WizardActionCustomizer = Action | ((defaultAction: Action) => Action)
-
-/**
- * Context handed to `Step.beforeValidation` / `afterValidation` hooks.
- * Mirrors the shape used by Form lifecycle hooks (record + user; values
- * are passed positionally so handlers can mutate them in place).
- */
-export interface StepValidationContext {
-  record?: unknown
-  user?:   unknown
-}
-
-/**
- * Hook signature for `Step.beforeValidation` / `afterValidation`.
- * Throwing aborts the wizard advance with a 422 stamped under the
- * reserved `_step` error key — surface a user-facing message via the
- * thrown Error's `.message`.
- */
-export type StepValidationHook = (
-  values: Record<string, unknown>,
-  ctx:    StepValidationContext,
-) => void | Promise<void>
-
-/**
- * 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 _beforeValidation?: StepValidationHook
-  private _afterValidation?:  StepValidationHook
-
-  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
-  }
-
-  /**
-   * Runs on the server BEFORE the step's fields are validated when the
-   * user clicks Next. Use to mutate `values` in place (e.g. stamp a
-   * computed field needed by validators) or run an async availability
-   * check that should block advance. Throw an Error to halt — the
-   * thrown message lands under the reserved `_step` key in the 422
-   * response so the renderer can show it next to the Next button.
-   */
-  beforeValidation(fn: StepValidationHook): this { this._beforeValidation = fn; return this }
-
-  /**
-   * Runs on the server AFTER the step's validators pass and before the
-   * 200 advance response. Use for cross-field invariants, side-effects
-   * that should fire only on confirmed advance, or computed-field stamps
-   * that downstream steps will read. Throw to halt — same `_step` key
-   * convention as `beforeValidation`.
-   */
-  afterValidation(fn: StepValidationHook): this { this._afterValidation = fn; return this }
-
-  getBeforeValidation(): StepValidationHook | undefined { return this._beforeValidation }
-  getAfterValidation():  StepValidationHook | undefined { return this._afterValidation }
-
-  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 _persistStepInQueryString: string | undefined = undefined
-  private _submitAction?:   WizardActionCustomizer
-  private _nextAction?:     WizardActionCustomizer
-  private _previousAction?: WizardActionCustomizer
-
-  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 }
-
-  /**
-   * Sync the active step index to the URL as `?<key>=N` (1-based for
-   * human-friendly URLs). When set, the URL value wins over localStorage
-   * on initial mount, so deep-linking to a specific step works. Bare
-   * `persistStepInQueryString()` uses the default key `'step'`; pass a
-   * string to override (multi-wizard pages should use distinct keys to
-   * avoid collisions). Pass `false` to disable.
-   */
-  persistStepInQueryString(key: string | boolean = true): this {
-    if (key === false) { this._persistStepInQueryString = undefined; return this }
-    this._persistStepInQueryString = key === true ? 'step' : key
-    return this
-  }
-
-  /**
-   * Customize the chrome of the built-in Submit button shown on the
-   * wizard's final step. By default the wizard renders a hint pointing
-   * at the surrounding form's Save button — calling this method instead
-   * mounts a real `<button type="submit">` inside the wizard chrome so
-   * the wizard becomes self-contained. Pair with `CreatePage.getFormActions(R)`
-   * returning `[]` to suppress the page-level Save when you don't want
-   * two submits on the same page.
-   */
-  submitAction(action: WizardActionCustomizer): this {
-    this._submitAction = action
-    return this
-  }
-
-  /** Customize the chrome of the built-in Next button. */
-  nextAction(action: WizardActionCustomizer): this {
-    this._nextAction = action
-    return this
-  }
-
-  /** Customize the chrome of the built-in Back / Previous button. */
-  previousAction(action: WizardActionCustomizer): this {
-    this._previousAction = action
-    return this
-  }
-
-  getPersistStepInQueryString(): string | undefined { return this._persistStepInQueryString }
-  getSubmitAction():             WizardActionCustomizer | undefined { return this._submitAction }
-  getNextAction():               WizardActionCustomizer | undefined { return this._nextAction }
-  getPreviousAction():           WizardActionCustomizer | undefined { return this._previousAction }
-
-  getType(): string { return 'wizard' }
-
-  toMeta(): Record<string, unknown> {
-    return {
-      type:        'wizard' as const,
-      skippable:   this._skippable,
-      startOnStep: this._startOnStep,
-      persist:     this._persist,
-      ...(this._persistStepInQueryString
-        ? { persistStepInQueryString: this._persistStepInQueryString }
-        : {}),
-    }
-  }
-}