@pilotiq/pilotiq 0.1.0

package/src/schema/Alert.test.ts

@@ -0,0 +1,63 @@
+import { describe, it, beforeEach } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { Alert } from './Alert.js'
+import { Action } from '../actions/Action.js'
+import { resolveSchema, _resetResolverRegistry } from './resolveSchema.js'
+
+beforeEach(() => _resetResolverRegistry())
+
+describe('Alert schema primitive', () => {
+  it('emits content + info default + no title key', () => {
+    const meta = Alert.make('Heads up').toMeta()
+    assert.equal(meta.type,      'alert')
+    assert.equal(meta.content,   'Heads up')
+    assert.equal(meta.alertType, 'info')
+    assert.equal('title' in meta, false)
+  })
+
+  it('honors warning / success / danger', () => {
+    assert.equal(Alert.make('a').warning().toMeta().alertType, 'warning')
+    assert.equal(Alert.make('a').success().toMeta().alertType, 'success')
+    assert.equal(Alert.make('a').danger().toMeta().alertType,  'danger')
+  })
+
+  it('emits title when set', () => {
+    const meta = Alert.make('body').title('Heads up').toMeta()
+    assert.equal(meta.title, 'Heads up')
+  })
+
+  it('actions(...) lands on _children and resolves into meta.children', async () => {
+    const upgrade = Action.make('upgrade').label('Upgrade').url('/billing')
+    const tree = [Alert.make('Free tier limits reached').warning().actions([upgrade])]
+    const out = await resolveSchema(tree)
+    assert.equal(out[0]!.type, 'alert')
+    const children = (out[0]!.children ?? []) as Array<{ type: string; name?: string }>
+    assert.equal(children.length, 1)
+    assert.equal(children[0]!.type, 'action')
+    assert.equal(children[0]!.name, 'upgrade')
+  })
+
+  it('actions visibility evaluates against the schema context', async () => {
+    const a = Action.make('admin-only').label('Admin').visible(({ user }) => Boolean(user))
+    const b = Action.make('always')    .label('Both' )
+    const tree = [Alert.make('hi').actions([a, b])]
+
+    // No user → admin-only action drops out.
+    const noUser = await resolveSchema(tree, {})
+    const noUserChildren = (noUser[0]!.children ?? []) as Array<{ name?: string }>
+    assert.equal(noUserChildren.length, 1)
+    assert.equal(noUserChildren[0]!.name, 'always')
+
+    // User present → both survive.
+    const withUser = await resolveSchema(tree, { user: { name: 'Sue' } })
+    const withUserChildren = (withUser[0]!.children ?? []) as Array<{ name?: string }>
+    assert.equal(withUserChildren.length, 2)
+  })
+
+  it('without actions(...) emits no children key', async () => {
+    const tree = [Alert.make('plain').info()]
+    const out = await resolveSchema(tree)
+    assert.equal('children' in out[0]!, false)
+  })
+})

package/src/schema/Alert.ts

@@ -0,0 +1,49 @@
+import { Element } from './Element.js'
+import type { Action } from '../actions/Action.js'
+
+export type AlertType = 'info' | 'warning' | 'success' | 'danger'
+
+export class Alert extends Element {
+  private _alertType: AlertType = 'info'
+  private _title?: string
+
+  private constructor(private content: string) {
+    super()
+  }
+
+  static make(content: string): Alert {
+    return new Alert(content)
+  }
+
+  alertType(t: AlertType): this { this._alertType = t; return this }
+  title(t: string): this { this._title = t; return this }
+
+  info(): this { return this.alertType('info') }
+  warning(): this { return this.alertType('warning') }
+  success(): this { return this.alertType('success') }
+  danger(): this { return this.alertType('danger') }
+
+  /**
+   * Action buttons rendered as a footer row below the alert body —
+   * matches the reference admin's `Callout` shape (in-callout CTAs like
+   * "Upgrade" or "Read changelog"). Same wiring as `Heading.actions(...)`
+   * and `EmptyState.footer(...)` — actions land on `_children` and the
+   * standard schema walker resolves them so `Action.evaluate(ctx)`
+   * (visibility / authorize) fires unchanged.
+   */
+  actions(actions: Action[]): this {
+    this._children = actions
+    return this
+  }
+
+  getType(): string { return 'alert' }
+
+  toMeta() {
+    return {
+      type: 'alert' as const,
+      content: this.content,
+      alertType: this._alertType,
+      ...(this._title ? { title: this._title } : {}),
+    }
+  }
+}

package/src/schema/Block.ts

@@ -0,0 +1,169 @@
+import type { Element, ElementMeta } from './Element.js'
+import type { LayoutContext, LayoutVisibilityRule } from './Element.js'
+
+/**
+ * Wire-format metadata for a single block type — what `BuilderField`
+ * ships to the client so the block-picker UI can render the
+ * `Add block` dropdown AND so the renderer can render a freshly-picked
+ * block's empty children without an extra server roundtrip.
+ *
+ * The per-row resolved schema lives on each `BuilderRowMeta`; this is
+ * the empty-row blueprint (`template`) used when the user picks the
+ * block from the dropdown. Resolved server-side once per block via
+ * `resolveBuilderRows` against `values: {}` so any inner-field
+ * `default()` surfaces.
+ */
+export interface BlockMeta {
+  name:      string
+  label:     string
+  icon?:     string
+  columns?:  number
+  maxItems?: number
+  template:  ElementMeta[]
+}
+
+/**
+ * Single block-type definition consumed by `BuilderField.blocks([…])`.
+ * Mirrors Filament's `Block` primitive: a name, a label, an optional
+ * icon, and an inner `schema()` rendered when a row of this type is
+ * created.
+ *
+ * Not an `Element` — `Block` is a schema-author primitive (like `Tab`,
+ * `Step`, `ListTab` minus the discriminator-driven layout role) held
+ * by `BuilderField` and looked up per-row by name. Resolving each
+ * row's children happens inside `resolveBuilderRows`, which calls
+ * `resolveSchema` against `block.getSchema()` with row-scoped values.
+ *
+ * @example
+ *   Block.make('heading')
+ *     .label('Heading')
+ *     .icon('heading')
+ *     .schema([
+ *       TextField.make('text').required(),
+ *       SelectField.make('level').options({ h1: 'H1', h2: 'H2' }),
+ *     ])
+ *     .columns(2)
+ *     .maxItems(1)  // only one Hero allowed per record
+ */
+export class Block {
+  readonly name: string
+
+  private _label?:        string
+  private _icon?:         string
+  private _columns?:      number
+  private _maxItems?:     number
+  private _schema:        Element[] = []
+  private _visibleRule?:  LayoutVisibilityRule
+
+  private constructor(name: string) {
+    this.name = name
+  }
+
+  static make(name: string): Block {
+    return new Block(name)
+  }
+
+  // ─── Builder ─────────────────────────────────────────
+
+  label(l: string): this { this._label = l; return this }
+
+  /**
+   * Icon shown next to the block label in the picker dropdown and
+   * (when `Builder.blockIcons()` is on) in each row's header. String-only
+   * — resolved through the icon registry, mirroring `Section.icon` /
+   * `Tab.icon`. Component-typed icons are reserved for top-level
+   * (Resource / Global / Page) bindings that own a manifest entry.
+   */
+  icon(name: string): this { this._icon = name; return this }
+
+  /** Inner form schema rendered when a row of this block type is added. */
+  schema(elements: Element[]): this { this._schema = elements; return this }
+
+  /** Grid column count for this block's inner schema. */
+  columns(n: number): this { this._columns = n; return this }
+
+  /**
+   * Cap on how many rows of THIS block type may appear in a single
+   * `BuilderField`. Validator + client-side gate (the picker greys out
+   * the option once the cap is hit). Useful for "exactly one Hero" or
+   * "at most three callouts".
+   */
+  maxItems(n: number): this { this._maxItems = n; return this }
+
+  /**
+   * Conditionally hide this block from the Builder's picker dropdown.
+   * Rule shape mirrors `Element.visible()`: a literal `boolean` or a
+   * callback receiving a `LayoutContext` (`{ record, values, user, $get,
+   * $set }`). Async callbacks are awaited.
+   *
+   * Hidden blocks disappear from the picker only — existing rows of a
+   * now-hidden block keep rendering with their full schema, so toggling
+   * visibility on a feature flag never silently destroys content.
+   *
+   * Throwing → fail closed (block stays hidden), parallel to
+   * `Element.evaluateVisibility`'s posture for layout rules.
+   */
+  visible(rule: LayoutVisibilityRule): this {
+    this._visibleRule = rule
+    return this
+  }
+
+  /** Inverse of `visible()`. `hidden(true)` is `visible(false)`. */
+  hidden(rule: LayoutVisibilityRule): this {
+    if (typeof rule === 'boolean') {
+      this._visibleRule = !rule
+    } else {
+      this._visibleRule = async (ctx) => !(await rule(ctx))
+    }
+    return this
+  }
+
+  hasVisibilityRule(): boolean { return this._visibleRule !== undefined }
+
+  /**
+   * Resolve the visibility rule against a context. Returns `true` when
+   * no rule is set; throwing rules return `false` and log a warning.
+   */
+  async evaluateVisibility(ctx: LayoutContext = {}): Promise<boolean> {
+    const rule = this._visibleRule
+    if (rule === undefined) return true
+    if (typeof rule === 'boolean') return rule
+    try {
+      return Boolean(await rule(ctx))
+    } catch (err) {
+      console.warn(`[pilotiq] visible() rule on Block "${this.name}" threw:`, err)
+      return false
+    }
+  }
+
+  // ─── Read-only access ────────────────────────────────
+
+  getLabel(): string {
+    return this._label ?? this.name.charAt(0).toUpperCase() + this.name.slice(1)
+  }
+  getIcon():     string | undefined  { return this._icon     }
+  getColumns():  number | undefined  { return this._columns  }
+  getMaxItems(): number | undefined  { return this._maxItems }
+  getSchema():   Element[]           { return this._schema   }
+
+  // ─── Wire format ─────────────────────────────────────
+
+  /**
+   * Bare picker meta. The `template` field is filled in by the resolver
+   * (it needs the surrounding `RenderContext` to walk the inner schema)
+   * — the no-arg `toMeta()` ships an empty array as a stable shape so
+   * non-resolver callers (e.g. unit tests, plain `Builder.toMeta()`)
+   * don't crash on a missing field.
+   */
+  toMeta(): BlockMeta {
+    const meta: BlockMeta = {
+      name:     this.name,
+      label:    this.getLabel(),
+      template: [],
+    }
+    if (this._icon     !== undefined) meta.icon     = this._icon
+    if (this._columns  !== undefined) meta.columns  = this._columns
+    if (this._maxItems !== undefined) meta.maxItems = this._maxItems
+    return meta
+  }
+}

package/src/schema/Breadcrumbs.ts

@@ -0,0 +1,40 @@
+import { Element } from './Element.js'
+
+/**
+ * Phase C — one rung in the breadcrumb chain. A trailing item without
+ * a `url` is rendered as the current page (unlinked, `aria-current="page"`).
+ */
+export interface BreadcrumbItem {
+  label: string
+  url?:  string
+}
+
+/**
+ * Phase C — server-resolved breadcrumb strip. Page-data builders
+ * prepend it ahead of any other top-of-page chrome (e.g. RelationTabs)
+ * so the renderer can paint:
+ *
+ *   Home / Posts / "Hello world" / Edit
+ *
+ * Users do not author this directly; the per-page-role builders in
+ * `pageData.ts` construct it via `Breadcrumbs.make([...])` after they've
+ * already loaded the parent / child records they need to derive titles.
+ */
+export class Breadcrumbs extends Element {
+  private constructor(private readonly _items: BreadcrumbItem[]) {
+    super()
+  }
+
+  static make(items: BreadcrumbItem[]): Breadcrumbs {
+    return new Breadcrumbs(items)
+  }
+
+  getType(): string { return 'breadcrumbs' }
+
+  toMeta() {
+    return {
+      type:  'breadcrumbs' as const,
+      items: this._items,
+    }
+  }
+}

package/src/schema/Card.ts

@@ -0,0 +1,35 @@
+import { Element } from './Element.js'
+
+export class Card extends Element {
+  private _description?: string
+
+  private constructor(private _title?: string) {
+    super()
+  }
+
+  static make(title?: string): Card {
+    return new Card(title)
+  }
+
+  description(d: string): this { this._description = d; return this }
+
+  /**
+   * Set the child elements of this card. Children can be any Element —
+   * Fields, other display elements, Actions, etc. Resolved recursively
+   * by `resolveSchema()` and attached to meta as `meta.children`.
+   */
+  schema(elements: Element[]): this {
+    this._children = elements
+    return this
+  }
+
+  getType(): string { return 'card' }
+
+  toMeta(): Record<string, unknown> {
+    return {
+      type: 'card' as const,
+      ...(this._title ? { title: this._title } : {}),
+      ...(this._description ? { description: this._description } : {}),
+    }
+  }
+}

package/src/schema/Divider.ts

@@ -0,0 +1,20 @@
+import { Element } from './Element.js'
+
+export class Divider extends Element {
+  private constructor(private _label?: string) {
+    super()
+  }
+
+  static make(label?: string): Divider {
+    return new Divider(label)
+  }
+
+  getType(): string { return 'divider' }
+
+  toMeta() {
+    return {
+      type: 'divider' as const,
+      ...(this._label ? { label: this._label } : {}),
+    }
+  }
+}

package/src/schema/Element.ts

@@ -0,0 +1,219 @@
+/**
+ * Context passed to layout-level `visible / hidden` rules. Mirrors
+ * `ConditionContext` in `fields/Field.ts` (same shape) so authors can
+ * destructure identically: `visible(({ $get }) => $get('kind') === 'a')`.
+ *
+ * Defined here (rather than importing from Field) so `Element` stays the
+ * lowest-dependency module in the schema folder — Field already imports
+ * from Element, not the other way around.
+ */
+export interface LayoutContext {
+  record?: unknown
+  values?: Record<string, unknown>
+  $get?:   (name: string) => unknown
+  $set?:   (name: string, value: unknown) => void
+  user?:   unknown
+  /**
+   * Plan #14 — present only when this layout element is being resolved
+   * inside a Repeater row. `row.index` is the row's position; `row.$get
+   * / $set` are row-local. `ctx.values` is automatically scoped to the
+   * row when present, so most callbacks just destructure `values`; `row`
+   * is the explicit access path.
+   */
+  row?: {
+    index: number
+    $get:  (name: string) => unknown
+    $set:  (name: string, value: unknown) => void
+    /**
+     * Present only when the row lives inside a `BuilderField` — the row's
+     * block name (the `type` discriminator). Lets a single `itemHidden` /
+     * `itemCanDelete` / `itemCanClone` / `itemCanReorder` rule branch by
+     * block without checking `values` shape. Always `undefined` for
+     * `RepeaterField` rows (which are homogeneous).
+     */
+    blockType?: string
+  }
+}
+
+/**
+ * Layout-level visibility rule. Either a literal `boolean` (useful for
+ * one-off feature flags) or a callback receiving a `LayoutContext`.
+ * Callbacks may be async — the resolver awaits before deciding.
+ *
+ * Plan #8 adds this to every `Element` subclass except `Field` and
+ * `Action`, which already own their own visibility paths
+ * (`showWhen / hideWhen / hideFromMode` on Field; `.visible / .hidden` on
+ * Action). The resolver only consults `_visibleRule` for layout
+ * elements — see `resolveSchema.ts` for the gating logic.
+ */
+export type LayoutVisibilityRule =
+  | boolean
+  | ((ctx: LayoutContext) => boolean | Promise<boolean>)
+
+/**
+ * Positional control inside a `Grid` / `Split` parent. Emitted under
+ * `meta._layout` and mapped to Tailwind utility classes (`col-span-*`,
+ * `col-start-*`, `order-*`) by the renderer. Outside a grid/split the
+ * keys are still emitted but the renderer ignores them.
+ */
+export interface LayoutPositioning {
+  columnSpan?:  number
+  columnStart?: number
+  columnOrder?: number
+}
+
+/**
+ * Base class for everything that can appear in a schema tree.
+ *
+ * `Field` (form input), `Action` (handler), and the display elements
+ * (Text, Heading, Card, Section, Stat, ...) all extend this class. Container
+ * elements populate `_children` to nest other Elements; leaves leave it
+ * undefined.
+ *
+ * The contract is intentionally tiny — `getType()` to identify, `toMeta()`
+ * to serialize. Everything else (visibility flags, validation, persistence)
+ * is layered on by specialized subclasses (Phase 1.2+).
+ */
+export abstract class Element {
+  protected _children?: Element[]
+
+  // ─── Plan #8 layout-level state ───────────────────────
+  protected _visibleRule?: LayoutVisibilityRule
+  protected _columnSpan?:  number
+  protected _columnStart?: number
+  protected _columnOrder?: number
+
+  /** Discriminator string. Used by the resolver and the client renderer. */
+  abstract getType(): string
+
+  /**
+   * Serialize this element's own state (excluding children) to a JSON-safe
+   * object. Children are handled by the resolver — do NOT inline them here.
+   *
+   * May return a Promise — reactive Field subclasses (Plan #5) compute
+   * dependent options asynchronously by awaiting a user-supplied function.
+   * The resolver awaits before merging children meta.
+   */
+  abstract toMeta(): Record<string, unknown> | Promise<Record<string, unknown>>
+
+  /**
+   * Children of a container element, or `undefined` for leaves. The resolver
+   * walks this to build the nested meta tree.
+   */
+  getChildren(): Element[] | undefined {
+    return this._children
+  }
+
+  // ─── Layout visibility (Plan #8) ──────────────────────
+
+  /**
+   * Show this element only when the predicate returns `true` (or is set
+   * to `true` literally). Throwing predicates fail closed (treated as
+   * `false`). The resolver evaluates this per resolve cycle and drops
+   * the element from the meta tree when it returns false. Plan #8.
+   *
+   * Field subclasses use the existing `showWhen / hideWhen` API — this
+   * setter on a Field is a no-op (Field's own visibility logic wins).
+   * Action subclasses use the existing `.visible / .hidden` API.
+   */
+  visible(rule: LayoutVisibilityRule): this {
+    this._visibleRule = rule
+    return this
+  }
+
+  /**
+   * Inverse of `visible()`. `hidden(true)` is the same as `visible(false)`;
+   * `hidden(fn)` shows the element when `fn` returns `false`.
+   */
+  hidden(rule: LayoutVisibilityRule): this {
+    if (typeof rule === 'boolean') {
+      this._visibleRule = !rule
+    } else {
+      this._visibleRule = async (ctx) => !(await rule(ctx))
+    }
+    return this
+  }
+
+  hasVisibilityRule(): boolean {
+    return this._visibleRule !== undefined
+  }
+
+  getVisibilityRule(): LayoutVisibilityRule | undefined {
+    return this._visibleRule
+  }
+
+  /**
+   * Resolve the visibility rule against a context. Returns `true` when no
+   * rule is set. Async — callbacks may return a Promise. Throwing
+   * callbacks resolve to `false` and log a warning, mirroring
+   * `Action.evaluate`'s fail-closed posture.
+   */
+  async evaluateVisibility(ctx: LayoutContext = {}): Promise<boolean> {
+    const rule = this._visibleRule
+    if (rule === undefined) return true
+    if (typeof rule === 'boolean') return rule
+    try {
+      return Boolean(await rule(ctx))
+    } catch (err) {
+      console.warn(`[pilotiq] visible() rule on ${this.getType()} threw:`, err)
+      return false
+    }
+  }
+
+  // ─── Layout positioning (Plan #8) ─────────────────────
+
+  /**
+   * Span `n` columns inside a parent `Grid` or `Split`. No-op when the
+   * element isn't inside a grid container — the meta still emits the
+   * hint, the renderer simply ignores it. Tailwind only generates
+   * `col-span-1..N` for the parent's column count, so values larger
+   * than the parent count are clamped at render.
+   */
+  columnSpan(n: number): this {
+    this._columnSpan = n
+    return this
+  }
+
+  /** Start at column `n` (1-indexed) inside a parent grid. */
+  columnStart(n: number): this {
+    this._columnStart = n
+    return this
+  }
+
+  /** CSS `order` for reordering siblings on small viewports. */
+  columnOrder(n: number): this {
+    this._columnOrder = n
+    return this
+  }
+
+  /**
+   * Build the layout-positioning bag. Returns `undefined` when no
+   * positioning method has been called — keeps `_layout` off the meta
+   * for the common case where authors don't customize.
+   */
+  getLayoutPositioning(): LayoutPositioning | undefined {
+    if (this._columnSpan  === undefined &&
+        this._columnStart === undefined &&
+        this._columnOrder === undefined) {
+      return undefined
+    }
+    const out: LayoutPositioning = {}
+    if (this._columnSpan  !== undefined) out.columnSpan  = this._columnSpan
+    if (this._columnStart !== undefined) out.columnStart = this._columnStart
+    if (this._columnOrder !== undefined) out.columnOrder = this._columnOrder
+    return out
+  }
+}
+
+/**
+ * Resolved metadata — JSON-serializable, sent to the client via viewProps.
+ *
+ * `type` is the discriminator from `Element.getType()`. `children` (when
+ * present) is the resolved meta tree of the element's children.
+ */
+export type ElementMeta = Record<string, unknown> & {
+  type: string
+  children?: ElementMeta[]
+  /** Plan #8 — emitted only when the element used `columnSpan/Start/Order`. */
+  _layout?: LayoutPositioning
+}

package/src/schema/EmptyState.test.ts

@@ -0,0 +1,37 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { EmptyState } from './EmptyState.js'
+import { Action } from '../actions/Action.js'
+
+describe('EmptyState schema primitive', () => {
+  it('emits heading + contained:true by default', () => {
+    const meta = EmptyState.make('No reports yet').toMeta()
+    assert.equal(meta.type,      'emptyState')
+    assert.equal(meta.heading,   'No reports yet')
+    assert.equal(meta.contained, true)
+    assert.equal('description' in meta, false)
+    assert.equal('icon'        in meta, false)
+  })
+
+  it('emits description / icon when set', () => {
+    const meta = EmptyState.make('Empty')
+      .description('Add your first item')
+      .icon('file-text')
+      .toMeta()
+    assert.equal(meta.description, 'Add your first item')
+    assert.equal(meta.icon,        'file-text')
+  })
+
+  it('contained(false) flips the wrapper flag', () => {
+    const meta = EmptyState.make('Empty').contained(false).toMeta()
+    assert.equal(meta.contained, false)
+  })
+
+  it('footer(actions) lands on the children pipe (resolved by walker)', () => {
+    const create = Action.make('create').label('Create')
+    const empty  = EmptyState.make('No rows').footer([create])
+    // _children is the pre-resolve slot the schema walker reads.
+    assert.equal(Array.isArray(empty['_children' as keyof typeof empty]), true)
+  })
+})