@pilotiq/pilotiq 0.1.0

package/dist/schema/Block.js

@@ -0,0 +1,136 @@
+/**
+ * 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 {
+    name;
+    _label;
+    _icon;
+    _columns;
+    _maxItems;
+    _schema = [];
+    _visibleRule;
+    constructor(name) {
+        this.name = name;
+    }
+    static make(name) {
+        return new Block(name);
+    }
+    // ─── Builder ─────────────────────────────────────────
+    label(l) { 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) { this._icon = name; return this; }
+    /** Inner form schema rendered when a row of this block type is added. */
+    schema(elements) { this._schema = elements; return this; }
+    /** Grid column count for this block's inner schema. */
+    columns(n) { 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) { 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) {
+        this._visibleRule = rule;
+        return this;
+    }
+    /** Inverse of `visible()`. `hidden(true)` is `visible(false)`. */
+    hidden(rule) {
+        if (typeof rule === 'boolean') {
+            this._visibleRule = !rule;
+        }
+        else {
+            this._visibleRule = async (ctx) => !(await rule(ctx));
+        }
+        return this;
+    }
+    hasVisibilityRule() { 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 = {}) {
+        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() {
+        return this._label ?? this.name.charAt(0).toUpperCase() + this.name.slice(1);
+    }
+    getIcon() { return this._icon; }
+    getColumns() { return this._columns; }
+    getMaxItems() { return this._maxItems; }
+    getSchema() { 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() {
+        const meta = {
+            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;
+    }
+}
+//# sourceMappingURL=Block.js.map

package/dist/schema/Block.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Block.js","sourceRoot":"","sources":["../../src/schema/Block.ts"],"names":[],"mappings":"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"}

package/dist/schema/Breadcrumbs.d.ts

@@ -0,0 +1,31 @@
+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 declare class Breadcrumbs extends Element {
+    private readonly _items;
+    private constructor();
+    static make(items: BreadcrumbItem[]): Breadcrumbs;
+    getType(): string;
+    toMeta(): {
+        type: "breadcrumbs";
+        items: BreadcrumbItem[];
+    };
+}
+//# sourceMappingURL=Breadcrumbs.d.ts.map

package/dist/schema/Breadcrumbs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Breadcrumbs.d.ts","sourceRoot":"","sources":["../../src/schema/Breadcrumbs.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAEtC;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAA;IACb,GAAG,CAAC,EAAG,MAAM,CAAA;CACd;AAED;;;;;;;;;;GAUG;AACH,qBAAa,WAAY,SAAQ,OAAO;IAClB,OAAO,CAAC,QAAQ,CAAC,MAAM;IAA3C,OAAO;IAIP,MAAM,CAAC,IAAI,CAAC,KAAK,EAAE,cAAc,EAAE,GAAG,WAAW;IAIjD,OAAO,IAAI,MAAM;IAEjB,MAAM;;;;CAMP"}

package/dist/schema/Breadcrumbs.js

@@ -0,0 +1,30 @@
+import { Element } from './Element.js';
+/**
+ * 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 {
+    _items;
+    constructor(_items) {
+        super();
+        this._items = _items;
+    }
+    static make(items) {
+        return new Breadcrumbs(items);
+    }
+    getType() { return 'breadcrumbs'; }
+    toMeta() {
+        return {
+            type: 'breadcrumbs',
+            items: this._items,
+        };
+    }
+}
+//# sourceMappingURL=Breadcrumbs.js.map

package/dist/schema/Breadcrumbs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Breadcrumbs.js","sourceRoot":"","sources":["../../src/schema/Breadcrumbs.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAWtC;;;;;;;;;;GAUG;AACH,MAAM,OAAO,WAAY,SAAQ,OAAO;IACD;IAArC,YAAqC,MAAwB;QAC3D,KAAK,EAAE,CAAA;QAD4B,WAAM,GAAN,MAAM,CAAkB;IAE7D,CAAC;IAED,MAAM,CAAC,IAAI,CAAC,KAAuB;QACjC,OAAO,IAAI,WAAW,CAAC,KAAK,CAAC,CAAA;IAC/B,CAAC;IAED,OAAO,KAAa,OAAO,aAAa,CAAA,CAAC,CAAC;IAE1C,MAAM;QACJ,OAAO;YACL,IAAI,EAAG,aAAsB;YAC7B,KAAK,EAAE,IAAI,CAAC,MAAM;SACnB,CAAA;IACH,CAAC;CACF"}

package/dist/schema/Card.d.ts

@@ -0,0 +1,17 @@
+import { Element } from './Element.js';
+export declare class Card extends Element {
+    private _title?;
+    private _description?;
+    private constructor();
+    static make(title?: string): Card;
+    description(d: string): 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;
+    getType(): string;
+    toMeta(): Record<string, unknown>;
+}
+//# sourceMappingURL=Card.d.ts.map

package/dist/schema/Card.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Card.d.ts","sourceRoot":"","sources":["../../src/schema/Card.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAEtC,qBAAa,IAAK,SAAQ,OAAO;IAGX,OAAO,CAAC,MAAM,CAAC;IAFnC,OAAO,CAAC,YAAY,CAAC,CAAQ;IAE7B,OAAO;IAIP,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI;IAIjC,WAAW,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI;IAE5B;;;;OAIG;IACH,MAAM,CAAC,QAAQ,EAAE,OAAO,EAAE,GAAG,IAAI;IAKjC,OAAO,IAAI,MAAM;IAEjB,MAAM,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAOlC"}

package/dist/schema/Card.js

@@ -0,0 +1,31 @@
+import { Element } from './Element.js';
+export class Card extends Element {
+    _title;
+    _description;
+    constructor(_title) {
+        super();
+        this._title = _title;
+    }
+    static make(title) {
+        return new Card(title);
+    }
+    description(d) { 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) {
+        this._children = elements;
+        return this;
+    }
+    getType() { return 'card'; }
+    toMeta() {
+        return {
+            type: 'card',
+            ...(this._title ? { title: this._title } : {}),
+            ...(this._description ? { description: this._description } : {}),
+        };
+    }
+}
+//# sourceMappingURL=Card.js.map

package/dist/schema/Card.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Card.js","sourceRoot":"","sources":["../../src/schema/Card.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAEtC,MAAM,OAAO,IAAK,SAAQ,OAAO;IAGH;IAFpB,YAAY,CAAS;IAE7B,YAA4B,MAAe;QACzC,KAAK,EAAE,CAAA;QADmB,WAAM,GAAN,MAAM,CAAS;IAE3C,CAAC;IAED,MAAM,CAAC,IAAI,CAAC,KAAc;QACxB,OAAO,IAAI,IAAI,CAAC,KAAK,CAAC,CAAA;IACxB,CAAC;IAED,WAAW,CAAC,CAAS,IAAU,IAAI,CAAC,YAAY,GAAG,CAAC,CAAC,CAAC,OAAO,IAAI,CAAA,CAAC,CAAC;IAEnE;;;;OAIG;IACH,MAAM,CAAC,QAAmB;QACxB,IAAI,CAAC,SAAS,GAAG,QAAQ,CAAA;QACzB,OAAO,IAAI,CAAA;IACb,CAAC;IAED,OAAO,KAAa,OAAO,MAAM,CAAA,CAAC,CAAC;IAEnC,MAAM;QACJ,OAAO;YACL,IAAI,EAAE,MAAe;YACrB,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC9C,GAAG,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,IAAI,CAAC,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACjE,CAAA;IACH,CAAC;CACF"}

package/dist/schema/Divider.d.ts

@@ -0,0 +1,12 @@
+import { Element } from './Element.js';
+export declare class Divider extends Element {
+    private _label?;
+    private constructor();
+    static make(label?: string): Divider;
+    getType(): string;
+    toMeta(): {
+        label?: string;
+        type: "divider";
+    };
+}
+//# sourceMappingURL=Divider.d.ts.map

package/dist/schema/Divider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Divider.d.ts","sourceRoot":"","sources":["../../src/schema/Divider.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAEtC,qBAAa,OAAQ,SAAQ,OAAO;IACd,OAAO,CAAC,MAAM,CAAC;IAAnC,OAAO;IAIP,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO;IAIpC,OAAO,IAAI,MAAM;IAEjB,MAAM;;;;CAMP"}

package/dist/schema/Divider.js

@@ -0,0 +1,19 @@
+import { Element } from './Element.js';
+export class Divider extends Element {
+    _label;
+    constructor(_label) {
+        super();
+        this._label = _label;
+    }
+    static make(label) {
+        return new Divider(label);
+    }
+    getType() { return 'divider'; }
+    toMeta() {
+        return {
+            type: 'divider',
+            ...(this._label ? { label: this._label } : {}),
+        };
+    }
+}
+//# sourceMappingURL=Divider.js.map

package/dist/schema/Divider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Divider.js","sourceRoot":"","sources":["../../src/schema/Divider.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAEtC,MAAM,OAAO,OAAQ,SAAQ,OAAO;IACN;IAA5B,YAA4B,MAAe;QACzC,KAAK,EAAE,CAAA;QADmB,WAAM,GAAN,MAAM,CAAS;IAE3C,CAAC;IAED,MAAM,CAAC,IAAI,CAAC,KAAc;QACxB,OAAO,IAAI,OAAO,CAAC,KAAK,CAAC,CAAA;IAC3B,CAAC;IAED,OAAO,KAAa,OAAO,SAAS,CAAA,CAAC,CAAC;IAEtC,MAAM;QACJ,OAAO;YACL,IAAI,EAAE,SAAkB;YACxB,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC/C,CAAA;IACH,CAAC;CACF"}

package/dist/schema/Element.d.ts

@@ -0,0 +1,150 @@
+/**
+ * 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 declare abstract class Element {
+    protected _children?: Element[];
+    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;
+    /**
+     * 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;
+    /**
+     * Inverse of `visible()`. `hidden(true)` is the same as `visible(false)`;
+     * `hidden(fn)` shows the element when `fn` returns `false`.
+     */
+    hidden(rule: LayoutVisibilityRule): this;
+    hasVisibilityRule(): boolean;
+    getVisibilityRule(): LayoutVisibilityRule | undefined;
+    /**
+     * 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.
+     */
+    evaluateVisibility(ctx?: LayoutContext): Promise<boolean>;
+    /**
+     * 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;
+    /** Start at column `n` (1-indexed) inside a parent grid. */
+    columnStart(n: number): this;
+    /** CSS `order` for reordering siblings on small viewports. */
+    columnOrder(n: number): 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;
+}
+/**
+ * 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;
+};
+//# sourceMappingURL=Element.d.ts.map

package/dist/schema/Element.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Element.d.ts","sourceRoot":"","sources":["../../src/schema/Element.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAChC,IAAI,CAAC,EAAI,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAA;IAClC,IAAI,CAAC,EAAI,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,IAAI,CAAA;IAC/C,IAAI,CAAC,EAAI,OAAO,CAAA;IAChB;;;;;;OAMG;IACH,GAAG,CAAC,EAAE;QACJ,KAAK,EAAE,MAAM,CAAA;QACb,IAAI,EAAG,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAA;QAChC,IAAI,EAAG,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,IAAI,CAAA;QAC7C;;;;;;WAMG;QACH,SAAS,CAAC,EAAE,MAAM,CAAA;KACnB,CAAA;CACF;AAED;;;;;;;;;;GAUG;AACH,MAAM,MAAM,oBAAoB,GAC5B,OAAO,GACP,CAAC,CAAC,GAAG,EAAE,aAAa,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC,CAAA;AAExD;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,UAAU,CAAC,EAAG,MAAM,CAAA;IACpB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAED;;;;;;;;;;;GAWG;AACH,8BAAsB,OAAO;IAC3B,SAAS,CAAC,SAAS,CAAC,EAAE,OAAO,EAAE,CAAA;IAG/B,SAAS,CAAC,YAAY,CAAC,EAAE,oBAAoB,CAAA;IAC7C,SAAS,CAAC,WAAW,CAAC,EAAG,MAAM,CAAA;IAC/B,SAAS,CAAC,YAAY,CAAC,EAAE,MAAM,CAAA;IAC/B,SAAS,CAAC,YAAY,CAAC,EAAE,MAAM,CAAA;IAE/B,0EAA0E;IAC1E,QAAQ,CAAC,OAAO,IAAI,MAAM;IAE1B;;;;;;;OAOG;IACH,QAAQ,CAAC,MAAM,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAE7E;;;OAGG;IACH,WAAW,IAAI,OAAO,EAAE,GAAG,SAAS;IAMpC;;;;;;;;;OASG;IACH,OAAO,CAAC,IAAI,EAAE,oBAAoB,GAAG,IAAI;IAKzC;;;OAGG;IACH,MAAM,CAAC,IAAI,EAAE,oBAAoB,GAAG,IAAI;IASxC,iBAAiB,IAAI,OAAO;IAI5B,iBAAiB,IAAI,oBAAoB,GAAG,SAAS;IAIrD;;;;;OAKG;IACG,kBAAkB,CAAC,GAAG,GAAE,aAAkB,GAAG,OAAO,CAAC,OAAO,CAAC;IAcnE;;;;;;OAMG;IACH,UAAU,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI;IAK3B,4DAA4D;IAC5D,WAAW,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI;IAK5B,8DAA8D;IAC9D,WAAW,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI;IAK5B;;;;OAIG;IACH,oBAAoB,IAAI,iBAAiB,GAAG,SAAS;CAYtD;AAED;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG;IAClD,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,CAAC,EAAE,WAAW,EAAE,CAAA;IACxB,6EAA6E;IAC7E,OAAO,CAAC,EAAE,iBAAiB,CAAA;CAC5B,CAAA"}

package/dist/schema/Element.js

@@ -0,0 +1,124 @@
+/**
+ * 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 class Element {
+    _children;
+    // ─── Plan #8 layout-level state ───────────────────────
+    _visibleRule;
+    _columnSpan;
+    _columnStart;
+    _columnOrder;
+    /**
+     * Children of a container element, or `undefined` for leaves. The resolver
+     * walks this to build the nested meta tree.
+     */
+    getChildren() {
+        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) {
+        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) {
+        if (typeof rule === 'boolean') {
+            this._visibleRule = !rule;
+        }
+        else {
+            this._visibleRule = async (ctx) => !(await rule(ctx));
+        }
+        return this;
+    }
+    hasVisibilityRule() {
+        return this._visibleRule !== undefined;
+    }
+    getVisibilityRule() {
+        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 = {}) {
+        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) {
+        this._columnSpan = n;
+        return this;
+    }
+    /** Start at column `n` (1-indexed) inside a parent grid. */
+    columnStart(n) {
+        this._columnStart = n;
+        return this;
+    }
+    /** CSS `order` for reordering siblings on small viewports. */
+    columnOrder(n) {
+        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() {
+        if (this._columnSpan === undefined &&
+            this._columnStart === undefined &&
+            this._columnOrder === undefined) {
+            return undefined;
+        }
+        const out = {};
+        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;
+    }
+}
+//# sourceMappingURL=Element.js.map

package/dist/schema/Element.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Element.js","sourceRoot":"","sources":["../../src/schema/Element.ts"],"names":[],"mappings":"AAgEA;;;;;;;;;;;GAWG;AACH,MAAM,OAAgB,OAAO;IACjB,SAAS,CAAY;IAE/B,yDAAyD;IAC/C,YAAY,CAAuB;IACnC,WAAW,CAAU;IACrB,YAAY,CAAS;IACrB,YAAY,CAAS;IAe/B;;;OAGG;IACH,WAAW;QACT,OAAO,IAAI,CAAC,SAAS,CAAA;IACvB,CAAC;IAED,yDAAyD;IAEzD;;;;;;;;;OASG;IACH,OAAO,CAAC,IAA0B;QAChC,IAAI,CAAC,YAAY,GAAG,IAAI,CAAA;QACxB,OAAO,IAAI,CAAA;IACb,CAAC;IAED;;;OAGG;IACH,MAAM,CAAC,IAA0B;QAC/B,IAAI,OAAO,IAAI,KAAK,SAAS,EAAE,CAAC;YAC9B,IAAI,CAAC,YAAY,GAAG,CAAC,IAAI,CAAA;QAC3B,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,YAAY,GAAG,KAAK,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,IAAI,CAAC,GAAG,CAAC,CAAC,CAAA;QACvD,CAAC;QACD,OAAO,IAAI,CAAA;IACb,CAAC;IAED,iBAAiB;QACf,OAAO,IAAI,CAAC,YAAY,KAAK,SAAS,CAAA;IACxC,CAAC;IAED,iBAAiB;QACf,OAAO,IAAI,CAAC,YAAY,CAAA;IAC1B,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,kBAAkB,CAAC,MAAqB,EAAE;QAC9C,MAAM,IAAI,GAAG,IAAI,CAAC,YAAY,CAAA;QAC9B,IAAI,IAAI,KAAK,SAAS;YAAE,OAAO,IAAI,CAAA;QACnC,IAAI,OAAO,IAAI,KAAK,SAAS;YAAE,OAAO,IAAI,CAAA;QAC1C,IAAI,CAAC;YACH,OAAO,OAAO,CAAC,MAAM,IAAI,CAAC,GAAG,CAAC,CAAC,CAAA;QACjC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,CAAC,IAAI,CAAC,+BAA+B,IAAI,CAAC,OAAO,EAAE,SAAS,EAAE,GAAG,CAAC,CAAA;YACzE,OAAO,KAAK,CAAA;QACd,CAAC;IACH,CAAC;IAED,yDAAyD;IAEzD;;;;;;OAMG;IACH,UAAU,CAAC,CAAS;QAClB,IAAI,CAAC,WAAW,GAAG,CAAC,CAAA;QACpB,OAAO,IAAI,CAAA;IACb,CAAC;IAED,4DAA4D;IAC5D,WAAW,CAAC,CAAS;QACnB,IAAI,CAAC,YAAY,GAAG,CAAC,CAAA;QACrB,OAAO,IAAI,CAAA;IACb,CAAC;IAED,8DAA8D;IAC9D,WAAW,CAAC,CAAS;QACnB,IAAI,CAAC,YAAY,GAAG,CAAC,CAAA;QACrB,OAAO,IAAI,CAAA;IACb,CAAC;IAED;;;;OAIG;IACH,oBAAoB;QAClB,IAAI,IAAI,CAAC,WAAW,KAAM,SAAS;YAC/B,IAAI,CAAC,YAAY,KAAK,SAAS;YAC/B,IAAI,CAAC,YAAY,KAAK,SAAS,EAAE,CAAC;YACpC,OAAO,SAAS,CAAA;QAClB,CAAC;QACD,MAAM,GAAG,GAAsB,EAAE,CAAA;QACjC,IAAI,IAAI,CAAC,WAAW,KAAM,SAAS;YAAE,GAAG,CAAC,UAAU,GAAI,IAAI,CAAC,WAAW,CAAA;QACvE,IAAI,IAAI,CAAC,YAAY,KAAK,SAAS;YAAE,GAAG,CAAC,WAAW,GAAG,IAAI,CAAC,YAAY,CAAA;QACxE,IAAI,IAAI,CAAC,YAAY,KAAK,SAAS;YAAE,GAAG,CAAC,WAAW,GAAG,IAAI,CAAC,YAAY,CAAA;QACxE,OAAO,GAAG,CAAA;IACZ,CAAC;CACF"}

package/dist/schema/EmptyState.d.ts

@@ -0,0 +1,48 @@
+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 declare class EmptyState extends Element {
+    private heading;
+    private _description?;
+    private _icon?;
+    private _contained;
+    private constructor();
+    static make(heading: string): EmptyState;
+    description(d: string): this;
+    icon(name: string): 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?: boolean): 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;
+    getType(): string;
+    toMeta(): {
+        icon?: string;
+        description?: string;
+        type: "emptyState";
+        heading: string;
+        contained: boolean;
+    };
+}
+//# sourceMappingURL=EmptyState.d.ts.map

package/dist/schema/EmptyState.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EmptyState.d.ts","sourceRoot":"","sources":["../../src/schema/EmptyState.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AACtC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAA;AAElD;;;;;;;;;;;;;GAaG;AACH,qBAAa,UAAW,SAAQ,OAAO;IAKjB,OAAO,CAAC,OAAO;IAJnC,OAAO,CAAC,YAAY,CAAC,CAAQ;IAC7B,OAAO,CAAC,KAAK,CAAC,CAAe;IAC7B,OAAO,CAAC,UAAU,CAAmB;IAErC,OAAO;IAIP,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU;IAIxC,WAAW,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI;IAC5B,IAAI,CAAC,IAAI,EAAE,MAAM,GAAO,IAAI;IAE5B;;;;OAIG;IACH,SAAS,CAAC,CAAC,UAAO,GAAG,IAAI;IAEzB;;;;;OAKG;IACH,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI;IAKtB,OAAO,IAAI,MAAM;IAEjB,MAAM;;;;;;;CAShB"}