@pilotiq/pilotiq 0.23.1 → 0.24.2

package/src/schema/Block.ts

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

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

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

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

@@ -1,219 +0,0 @@
-/**
- * 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

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

package/src/schema/EmptyState.ts

@@ -1,63 +0,0 @@
-import { Element } from './Element.js'
-import type { Action } from '../actions/Action.js'
-
-/**
- * Schema-level empty-state primitive — distinct from `Table.emptyState`
- * (which is table-chrome). Use this when an entire page section, custom
- * page, or dashboard zone has nothing to show. Drops into any layout
- * the same way as `Heading` / `Text` / `Alert` do.
- *
- *   EmptyState.make('No reports yet')
- *     .description('Create your first report to get started.')
- *     .icon('file-text')
- *     .footer([Action::make('create').url('/admin/reports/create')])
- *
- * v1 ships heading + description + icon + footer + `contained()`. Per-
- * page-mode visibility, columnSpan etc. inherit from `Element`.
- */
-export class EmptyState extends Element {
-  private _description?: string
-  private _icon?:        string
-  private _contained:    boolean = true
-
-  private constructor(private heading: string) {
-    super()
-  }
-
-  static make(heading: string): EmptyState {
-    return new EmptyState(heading)
-  }
-
-  description(d: string): this { this._description = d; return this }
-  icon(name: string):     this { this._icon        = name; return this }
-
-  /**
-   * Disable the default card-styled wrapper (background + border +
-   * padding) — useful when nesting inside another container that
-   * already brings its own chrome. Default `true` (contained).
-   */
-  contained(v = true): this { this._contained = v; return this }
-
-  /**
-   * Action buttons rendered below the description. Same shape as
-   * `Heading.actions(...)` — actions land on `_children` and serialize
-   * through the standard schema walker so `Action.evaluate(ctx)` for
-   * visibility / authorize fires unchanged.
-   */
-  footer(actions: Action[]): this {
-    this._children = actions
-    return this
-  }
-
-  override getType(): string { return 'emptyState' }
-
-  override toMeta() {
-    return {
-      type:      'emptyState' as const,
-      heading:   this.heading,
-      contained: this._contained,
-      ...(this._description ? { description: this._description } : {}),
-      ...(this._icon        ? { icon:        this._icon        } : {}),
-    }
-  }
-}

package/src/schema/Fieldset.ts

@@ -1,43 +0,0 @@
-import { Element } from './Element.js'
-
-/**
- * Lightweight labeled container. Renders as `<fieldset><legend>` with a
- * thin border + small horizontal padding. Lighter than `Section` — no
- * description, no collapsible disclosure, no badge. Use when fields share
- * a topic but the page already has section-level chrome.
- *
- * Optional `.columns(n)` produces a multi-column layout the same way
- * `Section.columns()` does. Outside of forms, Fieldset still renders the
- * border + legend; the renderer treats `<legend>` as a small heading
- * regardless of context.
- */
-export class Fieldset extends Element {
-  private _columns: 1 | 2 | 3 = 1
-
-  private constructor(private _label: string) {
-    super()
-  }
-
-  static make(label: string): Fieldset {
-    return new Fieldset(label)
-  }
-
-  /** Number of columns the fieldset's children are laid out in. Default 1. */
-  columns(n: 1 | 2 | 3): this { this._columns = n; return this }
-
-  /** Set the children. Any Element type is accepted. */
-  schema(elements: Element[]): this {
-    this._children = elements
-    return this
-  }
-
-  getType(): string { return 'fieldset' }
-
-  toMeta(): Record<string, unknown> {
-    return {
-      type: 'fieldset' as const,
-      label: this._label,
-      columns: this._columns,
-    }
-  }
-}

package/src/schema/Grid.ts

@@ -1,43 +0,0 @@
-import { Element } from './Element.js'
-
-/**
- * Layout container that arranges its children in a column grid. Lighter than
- * `Section` — no title, no description, no collapsible disclosure. Use it
- * for ad-hoc multi-column layouts (e.g. side-by-side fields without a
- * surrounding form section).
- *
- * `columns` defaults to 2 and accepts any positive integer; the client
- * renderer is expected to clamp to a sensible max.
- */
-export class Grid extends Element {
-  private _columns = 2
-  private _gap?: number
-
-  private constructor() {
-    super()
-  }
-
-  static make(): Grid {
-    return new Grid()
-  }
-
-  columns(n: number): this { this._columns = n; return this }
-
-  /** Optional gap between cells (units interpreted by the client renderer). */
-  gap(n: number): this { this._gap = n; return this }
-
-  schema(elements: Element[]): this {
-    this._children = elements
-    return this
-  }
-
-  getType(): string { return 'grid' }
-
-  toMeta(): Record<string, unknown> {
-    return {
-      type: 'grid' as const,
-      columns: this._columns,
-      ...(this._gap !== undefined ? { gap: this._gap } : {}),
-    }
-  }
-}