@pilotiq/pilotiq 0.1.0

package/dist/schema/Section.js

@@ -0,0 +1,127 @@
+import { Element } from './Element.js';
+/**
+ * Container that groups related Elements (typically Fields) under a heading
+ * with optional description. Supports multi-column layouts and a collapsible
+ * disclosure pattern. Mirrors panels' `Section` element.
+ *
+ * Used inside Forms to group related inputs, but composes anywhere a
+ * container Element fits (e.g. inside a Card or another Section).
+ *
+ * Plan #8 polish: `icon / badge / aside / compact / persistCollapsed`.
+ */
+export class Section extends Element {
+    _title;
+    _description;
+    _icon;
+    _badge;
+    _columns = 1;
+    _collapsible = false;
+    _defaultCollapsed = false;
+    _aside = false;
+    _compact = false;
+    _dense = false;
+    _secondary = false;
+    _persistCollapsed = false;
+    _persistKey;
+    _afterHeader;
+    constructor(_title) {
+        super();
+        this._title = _title;
+    }
+    static make(title) {
+        return new Section(title);
+    }
+    description(d) { this._description = d; return this; }
+    /**
+     * Icon shown next to the section title. Resolved through the icon
+     * registry (`registerIcons({ name: Component })`) at render. Schema-time
+     * icons are string-only — component-typed icons are reserved for
+     * Resource/Global/Page where the Vite plugin can mint a manifest key.
+     */
+    icon(name) { this._icon = name; return this; }
+    /** Right-aligned pill in the section header. Pure cosmetic. */
+    badge(text) { this._badge = text; return this; }
+    /** Number of columns the section's children are laid out in. Defaults to 1. */
+    columns(n) { this._columns = n; return this; }
+    /** Allow the user to collapse this section. Off by default. */
+    collapsible(v = true) { this._collapsible = v; return this; }
+    /** Start collapsed (only meaningful when `collapsible` is true). */
+    defaultCollapsed(v = true) { this._defaultCollapsed = v; return this; }
+    /**
+     * Render this section as the right-rail aside when nested inside a
+     * `Split` parent. No-op outside a `Split`.
+     */
+    aside(v = true) { this._aside = v; return this; }
+    /** Tighter padding + smaller heading. Useful in dense settings pages. */
+    compact(v = true) { this._compact = v; return this; }
+    /**
+     * Tighter spacing between the section's children. Orthogonal to
+     * `compact()` (which trims the section's outer padding/heading):
+     * `dense()` shrinks the inner grid `gap` so a long form fits more
+     * fields per scroll. Compose both for a settings-page look.
+     */
+    dense(v = true) { this._dense = v; return this; }
+    /**
+     * Muted background variant — uses the `bg-muted/40` token instead of
+     * `bg-card`. Pairs well with sections that wrap secondary or auxiliary
+     * controls (e.g. an "Advanced settings" group inside a primary card).
+     */
+    secondary(v = true) { this._secondary = v; return this; }
+    /**
+     * Persist the open/closed state to localStorage so user choices survive
+     * navigation. Only meaningful when `collapsible` is true. The optional
+     * `key` overrides the auto-key (which is built from the page slug +
+     * section title at render time).
+     */
+    persistCollapsed(key) {
+        this._persistCollapsed = true;
+        if (key !== undefined)
+            this._persistKey = key;
+        return this;
+    }
+    /**
+     * Action buttons rendered to the right of the section header. v1
+     * accepts `Action[]` only — Element-typed children would require a
+     * second resolver pass; keeping the slot Action-only dodges the
+     * resolution question (Actions serialize via `toMeta()` and their
+     * visibility evaluates inside the standard resolver walk that
+     * `resolveSchema` runs against `getAfterHeader()`).
+     *
+     * Actions placed here keep their full chrome surface — `.color() /
+     * .icon() / .iconButton() / .visible() / .disabled()` all work the
+     * same as anywhere else.
+     */
+    afterHeader(actions) {
+        this._afterHeader = actions;
+        return this;
+    }
+    /** Read-only access for the resolver. */
+    getAfterHeader() { return this._afterHeader; }
+    /** Set the section's children. Any Element type is accepted. */
+    schema(elements) {
+        this._children = elements;
+        return this;
+    }
+    getType() { return 'section'; }
+    toMeta() {
+        return {
+            type: 'section',
+            ...(this._title ? { title: this._title } : {}),
+            ...(this._description ? { description: this._description } : {}),
+            ...(this._icon ? { icon: this._icon } : {}),
+            ...(this._badge ? { badge: this._badge } : {}),
+            columns: this._columns,
+            collapsible: this._collapsible,
+            ...(this._collapsible && this._defaultCollapsed ? { defaultCollapsed: true } : {}),
+            ...(this._collapsible && this._persistCollapsed ? {
+                persistCollapsed: true,
+                ...(this._persistKey ? { persistKey: this._persistKey } : {}),
+            } : {}),
+            ...(this._aside ? { aside: true } : {}),
+            ...(this._compact ? { compact: true } : {}),
+            ...(this._dense ? { dense: true } : {}),
+            ...(this._secondary ? { secondary: true } : {}),
+        };
+    }
+}
+//# sourceMappingURL=Section.js.map

package/dist/schema/Section.js.map

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

package/dist/schema/ServerDataElement.d.ts

@@ -0,0 +1,101 @@
+import { Element, type ElementMeta } from './Element.js';
+import type { RenderContext } from './resolveSchema.js';
+/**
+ * Element subclasses that compute their render-time payload from the
+ * server. Plan #15 widgets — `Stat / StatsOverview / Chart / Table /
+ * View` extend this. The contract is intentionally tiny:
+ *
+ *   - identity: every element carries an id (`Stat.make(id)` / inferred
+ *     class name fallback) so the polling endpoint can find it,
+ *   - hook:     `resolveServerData(ctx)` returns whatever JSON-clean
+ *     payload the renderer should consume,
+ *   - flags:    `poll(seconds)`, `lazy(bool=true)` shape the wire.
+ *
+ * `pageData.resolveServerDataElements` walks every page-data builder's
+ * tree, collects elements where `isServerDataElement()` is true, and
+ * runs `resolveServerData(ctx)` in parallel — except for lazy ones,
+ * which paint a skeleton client-side and fetch via the polling endpoint
+ * on mount. Results land on a single `_widgetData[id]` map alongside
+ * `schemaData` so the renderer can look up its payload by id.
+ *
+ * Subclasses don't need to call `super.toMeta()` — the resolver stamps
+ * `serverData / poll / lazy / id` onto the meta after the subclass's own
+ * `toMeta()` runs. This keeps subclass meta authoring focused on the
+ * widget's own surface (label, type, columns, …).
+ */
+export declare abstract class ServerDataElement extends Element {
+    protected _id?: string;
+    protected _poll?: number;
+    protected _lazy?: boolean;
+    protected _widgetUrl?: string;
+    /**
+     * Stable identifier. Required so the polling endpoint can find this
+     * element after re-walking the schema. Subclasses that use a fluent
+     * factory (`Chart.make('posts-chart')`) pass an explicit id; subclasses
+     * that don't (e.g. `View`, where the user extends with `class
+     * ContributionMap extends View {}`) fall back to the constructor's
+     * class name via `getId()`.
+     */
+    getId(): string;
+    /** Set an explicit id. Useful when two instances of the same subclass
+     *  appear on the same page (e.g. two `View.component(X)` widgets). */
+    id(value: string): this;
+    /** Polling interval in seconds. Number-only by design (cleaner than
+     *  Filament's '30s' string). Zero / negative / non-finite values are
+     *  ignored. */
+    poll(seconds: number): this;
+    getPoll(): number | undefined;
+    /**
+     * Opt out of (or back into) lazy loading. Default is lazy: the server
+     * paints a skeleton on first render and the client fetches the
+     * payload via the polling endpoint on mount. `lazy(false)` makes the
+     * server resolve `getServerData(ctx)` synchronously and ship the
+     * payload with the page.
+     */
+    lazy(value?: boolean): this;
+    /** True when this element should ship lazy (skeleton + first-paint
+     *  fetch). Default is true; unset === true. */
+    isLazy(): boolean;
+    /** Stamp the polling-endpoint URL. Called by `pageData.tagWidgetUrls`
+     *  during page-data builds — `${base}/_widget/:id` for panel-scope
+     *  dashboards and `${base}/${pageSlug}/_widget/:id` for custom-page
+     *  scope. The renderer reads `meta.widgetUrl` to fetch. */
+    withWidgetUrl(url: string): this;
+    getWidgetUrl(): string | undefined;
+    /** Discriminator that pageData / routes use to find server-data
+     *  elements without `instanceof` (Vite SSR module-cache duplication
+     *  trap — same posture as `findForms`). */
+    isServerDataElement(): true;
+    /**
+     * Compute this element's render-time payload. Receives the same
+     * `RenderContext` the resolver builds (record/user/values/$get/...).
+     * Implementations should return a JSON-clean value — the resolver
+     * stamps it under `_widgetData[id]` for the renderer to consume.
+     *
+     * May throw — `resolveServerDataElements` swallows the throw and
+     * stamps `_widgetData[id] = { error: '...' }` so a single failing
+     * widget doesn't blank the whole dashboard. The polling-endpoint
+     * path handles errors symmetrically.
+     */
+    abstract resolveServerData(ctx: RenderContext): Promise<unknown>;
+}
+/**
+ * Structural type guard — Vite SSR module-cache duplication breaks
+ * `instanceof` across module-graph entries (see
+ * `feedback_vite_ssr_module_dup_instanceof.md`). Matches the
+ * `findForms / findActions / isRepeaterField / isBuilderField` pattern.
+ */
+export declare function isServerDataElement(el: Element): el is ServerDataElement;
+/**
+ * Stamp `serverData / id / poll / lazy` onto an element's meta after
+ * subclass `toMeta()` runs. Called by `resolveSchema` for every
+ * `ServerDataElement`. Subclasses keep their `toMeta()` clean — they
+ * only emit their own surface (label, kind, columns, …).
+ *
+ * Only stamps `lazy: true` when explicit; undefined-default ships as
+ * `lazy: true` since the renderer treats absent as true. Keeps the wire
+ * compact for the synchronous case (`lazy(false)` → no key emitted, but
+ * `_widgetData[id]` already carries the payload).
+ */
+export declare function stampServerDataMeta(el: ServerDataElement, meta: ElementMeta): void;
+//# sourceMappingURL=ServerDataElement.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ServerDataElement.d.ts","sourceRoot":"","sources":["../../src/schema/ServerDataElement.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,KAAK,WAAW,EAAE,MAAM,cAAc,CAAA;AACxD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAEvD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,8BAAsB,iBAAkB,SAAQ,OAAO;IACrD,SAAS,CAAC,GAAG,CAAC,EAAE,MAAM,CAAA;IACtB,SAAS,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IAIxB,SAAS,CAAC,KAAK,CAAC,EAAE,OAAO,CAAA;IAKzB,SAAS,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;IAE7B;;;;;;;OAOG;IACH,KAAK,IAAI,MAAM;IAMf;0EACsE;IACtE,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAKvB;;mBAEe;IACf,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAK3B,OAAO,IAAI,MAAM,GAAG,SAAS;IAI7B;;;;;;OAMG;IACH,IAAI,CAAC,KAAK,GAAE,OAAc,GAAG,IAAI;IAKjC;mDAC+C;IAC/C,MAAM,IAAI,OAAO;IAIjB;;;+DAG2D;IAC3D,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAKhC,YAAY,IAAI,MAAM,GAAG,SAAS;IAIlC;;+CAE2C;IAE3C,mBAAmB,IAAI,IAAI;IAE3B;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,iBAAiB,CAAC,GAAG,EAAE,aAAa,GAAG,OAAO,CAAC,OAAO,CAAC;CACjE;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,OAAO,GAAG,EAAE,IAAI,iBAAiB,CAGxE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,iBAAiB,EAAE,IAAI,EAAE,WAAW,GAAG,IAAI,CAUlF"}

package/dist/schema/ServerDataElement.js

@@ -0,0 +1,135 @@
+import { Element } from './Element.js';
+/**
+ * Element subclasses that compute their render-time payload from the
+ * server. Plan #15 widgets — `Stat / StatsOverview / Chart / Table /
+ * View` extend this. The contract is intentionally tiny:
+ *
+ *   - identity: every element carries an id (`Stat.make(id)` / inferred
+ *     class name fallback) so the polling endpoint can find it,
+ *   - hook:     `resolveServerData(ctx)` returns whatever JSON-clean
+ *     payload the renderer should consume,
+ *   - flags:    `poll(seconds)`, `lazy(bool=true)` shape the wire.
+ *
+ * `pageData.resolveServerDataElements` walks every page-data builder's
+ * tree, collects elements where `isServerDataElement()` is true, and
+ * runs `resolveServerData(ctx)` in parallel — except for lazy ones,
+ * which paint a skeleton client-side and fetch via the polling endpoint
+ * on mount. Results land on a single `_widgetData[id]` map alongside
+ * `schemaData` so the renderer can look up its payload by id.
+ *
+ * Subclasses don't need to call `super.toMeta()` — the resolver stamps
+ * `serverData / poll / lazy / id` onto the meta after the subclass's own
+ * `toMeta()` runs. This keeps subclass meta authoring focused on the
+ * widget's own surface (label, type, columns, …).
+ */
+export class ServerDataElement extends Element {
+    _id;
+    _poll;
+    // Default lazy=true (matches Filament v5's `$isLazy = true` default).
+    // `undefined` is treated as `true` everywhere; explicit `false` opts
+    // out (synchronous server-side resolve, ships data on first paint).
+    _lazy;
+    // Polling-endpoint URL stamped by `pageData.tagWidgetUrls`. The
+    // renderer reads `meta.widgetUrl` to fetch lazy data on mount and to
+    // re-fetch on `poll(seconds)` ticks. Set server-side per page-data
+    // pass — the field never round-trips back from the client.
+    _widgetUrl;
+    /**
+     * Stable identifier. Required so the polling endpoint can find this
+     * element after re-walking the schema. Subclasses that use a fluent
+     * factory (`Chart.make('posts-chart')`) pass an explicit id; subclasses
+     * that don't (e.g. `View`, where the user extends with `class
+     * ContributionMap extends View {}`) fall back to the constructor's
+     * class name via `getId()`.
+     */
+    getId() {
+        if (this._id)
+            return this._id;
+        const ctor = this.constructor;
+        return ctor.name ?? 'widget';
+    }
+    /** Set an explicit id. Useful when two instances of the same subclass
+     *  appear on the same page (e.g. two `View.component(X)` widgets). */
+    id(value) {
+        this._id = value;
+        return this;
+    }
+    /** Polling interval in seconds. Number-only by design (cleaner than
+     *  Filament's '30s' string). Zero / negative / non-finite values are
+     *  ignored. */
+    poll(seconds) {
+        if (Number.isFinite(seconds) && seconds > 0)
+            this._poll = seconds;
+        return this;
+    }
+    getPoll() {
+        return this._poll;
+    }
+    /**
+     * Opt out of (or back into) lazy loading. Default is lazy: the server
+     * paints a skeleton on first render and the client fetches the
+     * payload via the polling endpoint on mount. `lazy(false)` makes the
+     * server resolve `getServerData(ctx)` synchronously and ship the
+     * payload with the page.
+     */
+    lazy(value = true) {
+        this._lazy = value;
+        return this;
+    }
+    /** True when this element should ship lazy (skeleton + first-paint
+     *  fetch). Default is true; unset === true. */
+    isLazy() {
+        return this._lazy !== false;
+    }
+    /** Stamp the polling-endpoint URL. Called by `pageData.tagWidgetUrls`
+     *  during page-data builds — `${base}/_widget/:id` for panel-scope
+     *  dashboards and `${base}/${pageSlug}/_widget/:id` for custom-page
+     *  scope. The renderer reads `meta.widgetUrl` to fetch. */
+    withWidgetUrl(url) {
+        this._widgetUrl = url;
+        return this;
+    }
+    getWidgetUrl() {
+        return this._widgetUrl;
+    }
+    /** Discriminator that pageData / routes use to find server-data
+     *  elements without `instanceof` (Vite SSR module-cache duplication
+     *  trap — same posture as `findForms`). */
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars -- structural marker
+    isServerDataElement() { return true; }
+}
+/**
+ * Structural type guard — Vite SSR module-cache duplication breaks
+ * `instanceof` across module-graph entries (see
+ * `feedback_vite_ssr_module_dup_instanceof.md`). Matches the
+ * `findForms / findActions / isRepeaterField / isBuilderField` pattern.
+ */
+export function isServerDataElement(el) {
+    const probe = el;
+    return typeof probe.isServerDataElement === 'function' && probe.isServerDataElement() === true;
+}
+/**
+ * Stamp `serverData / id / poll / lazy` onto an element's meta after
+ * subclass `toMeta()` runs. Called by `resolveSchema` for every
+ * `ServerDataElement`. Subclasses keep their `toMeta()` clean — they
+ * only emit their own surface (label, kind, columns, …).
+ *
+ * Only stamps `lazy: true` when explicit; undefined-default ships as
+ * `lazy: true` since the renderer treats absent as true. Keeps the wire
+ * compact for the synchronous case (`lazy(false)` → no key emitted, but
+ * `_widgetData[id]` already carries the payload).
+ */
+export function stampServerDataMeta(el, meta) {
+    meta['serverData'] = true;
+    meta['id'] = el.getId();
+    const poll = el.getPoll();
+    if (poll !== undefined)
+        meta['poll'] = poll;
+    // Always emit `lazy` so the renderer doesn't have to fall back through
+    // a default — explicit > implicit on the wire.
+    meta['lazy'] = el.isLazy();
+    const widgetUrl = el.getWidgetUrl();
+    if (widgetUrl !== undefined)
+        meta['widgetUrl'] = widgetUrl;
+}
+//# sourceMappingURL=ServerDataElement.js.map

package/dist/schema/ServerDataElement.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ServerDataElement.js","sourceRoot":"","sources":["../../src/schema/ServerDataElement.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAoB,MAAM,cAAc,CAAA;AAGxD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,OAAgB,iBAAkB,SAAQ,OAAO;IAC3C,GAAG,CAAS;IACZ,KAAK,CAAS;IACxB,sEAAsE;IACtE,qEAAqE;IACrE,oEAAoE;IAC1D,KAAK,CAAU;IACzB,gEAAgE;IAChE,qEAAqE;IACrE,mEAAmE;IACnE,2DAA2D;IACjD,UAAU,CAAS;IAE7B;;;;;;;OAOG;IACH,KAAK;QACH,IAAI,IAAI,CAAC,GAAG;YAAE,OAAO,IAAI,CAAC,GAAG,CAAA;QAC7B,MAAM,IAAI,GAAG,IAAI,CAAC,WAAgC,CAAA;QAClD,OAAO,IAAI,CAAC,IAAI,IAAI,QAAQ,CAAA;IAC9B,CAAC;IAED;0EACsE;IACtE,EAAE,CAAC,KAAa;QACd,IAAI,CAAC,GAAG,GAAG,KAAK,CAAA;QAChB,OAAO,IAAI,CAAA;IACb,CAAC;IAED;;mBAEe;IACf,IAAI,CAAC,OAAe;QAClB,IAAI,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,OAAO,GAAG,CAAC;YAAE,IAAI,CAAC,KAAK,GAAG,OAAO,CAAA;QACjE,OAAO,IAAI,CAAA;IACb,CAAC;IAED,OAAO;QACL,OAAO,IAAI,CAAC,KAAK,CAAA;IACnB,CAAC;IAED;;;;;;OAMG;IACH,IAAI,CAAC,QAAiB,IAAI;QACxB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAA;QAClB,OAAO,IAAI,CAAA;IACb,CAAC;IAED;mDAC+C;IAC/C,MAAM;QACJ,OAAO,IAAI,CAAC,KAAK,KAAK,KAAK,CAAA;IAC7B,CAAC;IAED;;;+DAG2D;IAC3D,aAAa,CAAC,GAAW;QACvB,IAAI,CAAC,UAAU,GAAG,GAAG,CAAA;QACrB,OAAO,IAAI,CAAA;IACb,CAAC;IAED,YAAY;QACV,OAAO,IAAI,CAAC,UAAU,CAAA;IACxB,CAAC;IAED;;+CAE2C;IAC3C,kFAAkF;IAClF,mBAAmB,KAAW,OAAO,IAAI,CAAA,CAAC,CAAC;CAc5C;AAED;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CAAC,EAAW;IAC7C,MAAM,KAAK,GAAG,EAAwD,CAAA;IACtE,OAAO,OAAO,KAAK,CAAC,mBAAmB,KAAK,UAAU,IAAI,KAAK,CAAC,mBAAmB,EAAE,KAAK,IAAI,CAAA;AAChG,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,mBAAmB,CAAC,EAAqB,EAAE,IAAiB;IAC1E,IAAI,CAAC,YAAY,CAAC,GAAG,IAAI,CAAA;IACzB,IAAI,CAAC,IAAI,CAAC,GAAW,EAAE,CAAC,KAAK,EAAE,CAAA;IAC/B,MAAM,IAAI,GAAG,EAAE,CAAC,OAAO,EAAE,CAAA;IACzB,IAAI,IAAI,KAAK,SAAS;QAAE,IAAI,CAAC,MAAM,CAAC,GAAG,IAAI,CAAA;IAC3C,uEAAuE;IACvE,+CAA+C;IAC/C,IAAI,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,MAAM,EAAE,CAAA;IAC1B,MAAM,SAAS,GAAG,EAAE,CAAC,YAAY,EAAE,CAAA;IACnC,IAAI,SAAS,KAAK,SAAS;QAAE,IAAI,CAAC,WAAW,CAAC,GAAG,SAAS,CAAA;AAC5D,CAAC"}

package/dist/schema/Split.d.ts

@@ -0,0 +1,31 @@
+import { Element } from './Element.js';
+export type SplitFrom = 'left' | 'right';
+/**
+ * Two-column layout — main + aside. Renders as a stacked flex on small
+ * viewports and a horizontal flex on `@md` (container query). Children
+ * tagged with `.aside()` (e.g. `Section.aside()`) become the right-rail
+ * (or left, when `from('left')`); without explicit markers, the second
+ * child is treated as the aside.
+ *
+ * The renderer picks the aside-styled width from a small palette of
+ * shadcn-flavoured sidebar widths (~20rem). The main child grows to
+ * fill the remaining space.
+ *
+ * Useful for settings pages with a navigation card on the side, or for
+ * resource forms where the primary content is a long article body and
+ * the aside holds publish controls.
+ */
+export declare class Split extends Element {
+    private _from;
+    private _gap;
+    private constructor();
+    static make(): Split;
+    /** Which side the aside child sits on. Defaults to `'right'`. */
+    from(side: SplitFrom): this;
+    /** Gap between main and aside (Tailwind spacing scale). Default 6 (24px). */
+    gap(n: number): this;
+    schema(elements: Element[]): this;
+    getType(): string;
+    toMeta(): Record<string, unknown>;
+}
+//# sourceMappingURL=Split.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Split.d.ts","sourceRoot":"","sources":["../../src/schema/Split.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAEtC,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,OAAO,CAAA;AAExC;;;;;;;;;;;;;;GAcG;AACH,qBAAa,KAAM,SAAQ,OAAO;IAChC,OAAO,CAAC,KAAK,CAAqB;IAClC,OAAO,CAAC,IAAI,CAAI;IAEhB,OAAO;IAEP,MAAM,CAAC,IAAI,IAAI,KAAK;IAIpB,iEAAiE;IACjE,IAAI,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI;IAE3B,6EAA6E;IAC7E,GAAG,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI;IAEpB,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/Split.js

@@ -0,0 +1,41 @@
+import { Element } from './Element.js';
+/**
+ * Two-column layout — main + aside. Renders as a stacked flex on small
+ * viewports and a horizontal flex on `@md` (container query). Children
+ * tagged with `.aside()` (e.g. `Section.aside()`) become the right-rail
+ * (or left, when `from('left')`); without explicit markers, the second
+ * child is treated as the aside.
+ *
+ * The renderer picks the aside-styled width from a small palette of
+ * shadcn-flavoured sidebar widths (~20rem). The main child grows to
+ * fill the remaining space.
+ *
+ * Useful for settings pages with a navigation card on the side, or for
+ * resource forms where the primary content is a long article body and
+ * the aside holds publish controls.
+ */
+export class Split extends Element {
+    _from = 'right';
+    _gap = 6;
+    constructor() { super(); }
+    static make() {
+        return new Split();
+    }
+    /** Which side the aside child sits on. Defaults to `'right'`. */
+    from(side) { this._from = side; return this; }
+    /** Gap between main and aside (Tailwind spacing scale). Default 6 (24px). */
+    gap(n) { this._gap = n; return this; }
+    schema(elements) {
+        this._children = elements;
+        return this;
+    }
+    getType() { return 'split'; }
+    toMeta() {
+        return {
+            type: 'split',
+            from: this._from,
+            gap: this._gap,
+        };
+    }
+}
+//# sourceMappingURL=Split.js.map

package/dist/schema/Split.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Split.js","sourceRoot":"","sources":["../../src/schema/Split.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAItC;;;;;;;;;;;;;;GAcG;AACH,MAAM,OAAO,KAAM,SAAQ,OAAO;IACxB,KAAK,GAAc,OAAO,CAAA;IAC1B,IAAI,GAAG,CAAC,CAAA;IAEhB,gBAAwB,KAAK,EAAE,CAAA,CAAC,CAAC;IAEjC,MAAM,CAAC,IAAI;QACT,OAAO,IAAI,KAAK,EAAE,CAAA;IACpB,CAAC;IAED,iEAAiE;IACjE,IAAI,CAAC,IAAe,IAAU,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,CAAC,OAAO,IAAI,CAAA,CAAC,CAAC;IAE9D,6EAA6E;IAC7E,GAAG,CAAC,CAAS,IAAU,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,OAAO,IAAI,CAAA,CAAC,CAAC;IAEnD,MAAM,CAAC,QAAmB;QACxB,IAAI,CAAC,SAAS,GAAG,QAAQ,CAAA;QACzB,OAAO,IAAI,CAAA;IACb,CAAC;IAED,OAAO,KAAa,OAAO,OAAO,CAAA,CAAC,CAAC;IAEpC,MAAM;QACJ,OAAO;YACL,IAAI,EAAE,OAAgB;YACtB,IAAI,EAAE,IAAI,CAAC,KAAK;YAChB,GAAG,EAAG,IAAI,CAAC,IAAI;SAChB,CAAA;IACH,CAAC;CACF"}

package/dist/schema/Stat.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Plan #15 Phase B — `Stat` is the fluent value object emitted by
+ * `StatsOverview.getStats(ctx)`. It does NOT extend Element — it has no
+ * place in the schema tree on its own. `StatsOverview.resolveServerData`
+ * collects the array of Stats and ships them as JSON-clean
+ * `StatMeta[]` payloads under `_widgetData[id]`.
+ *
+ *   Stat.make('Users')
+ *     .value(await User.query().count())
+ *     .description('+12% this month')
+ *     .descriptionIcon('trending-up', 'before')
+ *     .icon('users')
+ *     .color('success')
+ *     .chart([12, 4, 8, 15, 22, 18, 30])      // sparkline
+ *     .url('/admin/users').openUrlInNewTab()
+ *
+ * Surface mirrors Filament v5's `Stat` 1:1, modulo TS naming
+ * (`openUrlInNewTab(true)` not `->openUrlInNewTab()`).
+ */
+/** Color preset. Mirrors `TabBadgeColor` so a "Users · 5,234" stat can
+ *  be tinted with the same palette as the rest of the panel chrome. */
+export type StatColor = 'default' | 'primary' | 'success' | 'warning' | 'destructive' | 'info';
+/** Position for the optional `descriptionIcon`. Matches Filament's
+ *  `IconPosition::Before / After` enum values. */
+export type StatDescriptionIconPosition = 'before' | 'after';
+export interface StatDescriptionIcon {
+    name: string;
+    position: StatDescriptionIconPosition;
+}
+/**
+ * JSON-clean payload shape — what `StatsOverview.resolveServerData`
+ * emits and the renderer consumes. Optional keys are omitted when the
+ * fluent setter wasn't called (smaller wire, simpler renderer
+ * branching).
+ */
+export interface StatMeta {
+    label: string;
+    value?: string | number | null;
+    description?: string;
+    descriptionIcon?: StatDescriptionIcon;
+    icon?: string;
+    color?: StatColor;
+    chart?: number[];
+    url?: string;
+    openInNewTab?: boolean;
+    extraAttributes?: Record<string, unknown>;
+}
+export declare class Stat {
+    protected _label: string;
+    protected _value?: string | number | null;
+    protected _description?: string;
+    protected _descriptionIcon?: StatDescriptionIcon;
+    protected _icon?: string;
+    protected _color?: StatColor;
+    protected _chart?: number[];
+    protected _url?: string;
+    protected _openInNewTab?: boolean;
+    protected _extraAttributes?: Record<string, unknown>;
+    protected constructor(_label: string);
+    /** Factory. The single positional arg is the stat's *label*
+     *  (e.g. 'Users') — the value is set fluently via `.value(...)`. */
+    static make(label: string): Stat;
+    /** Main number / string. `null` and `undefined` round-trip as `null`
+     *  so the renderer can show a placeholder ("—") for "not yet
+     *  computed" / "not applicable" without an extra sentinel. */
+    value(v: string | number | null | undefined): this;
+    /** Supplementary line below the value (e.g. '+12% this month'). */
+    description(t: string): this;
+    /** Tiny icon glued to the description. Position defaults to `'after'`
+     *  (matches Filament v5's `IconPosition::After`). */
+    descriptionIcon(name: string, position?: StatDescriptionIconPosition): this;
+    /** Main icon shown in the card chrome. String key into the panel's
+     *  icon registry — same lookup as `Resource.icon`. */
+    icon(name: string): this;
+    /** Color tint for the value + icon. */
+    color(c: StatColor): this;
+    /** Inline-SVG sparkline data. Array of raw numbers — the renderer
+     *  draws a path scaled to the card. No chart-lib dep. */
+    chart(values: number[]): this;
+    /** Wrap the card in an `<a href>`. */
+    url(href: string): this;
+    /** When `.url()` is set, open it in a new tab. */
+    openUrlInNewTab(value?: boolean): this;
+    /** Extra HTML attributes spread onto the card root. JSON-clean only —
+     *  values must serialize. */
+    extraAttributes(attrs: Record<string, unknown>): this;
+    /** Serialize to the wire shape. Stats are ferried through
+     *  `_widgetData` so this is a plain JSON object — no children, no
+     *  `type` discriminator (the parent `StatsOverview` carries that). */
+    toMeta(): StatMeta;
+}
+//# sourceMappingURL=Stat.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Stat.d.ts","sourceRoot":"","sources":["../../src/schema/Stat.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH;uEACuE;AACvE,MAAM,MAAM,SAAS,GACjB,SAAS,GACT,SAAS,GACT,SAAS,GACT,SAAS,GACT,aAAa,GACb,MAAM,CAAA;AAEV;kDACkD;AAClD,MAAM,MAAM,2BAA2B,GAAG,QAAQ,GAAG,OAAO,CAAA;AAE5D,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAM,MAAM,CAAA;IAChB,QAAQ,EAAE,2BAA2B,CAAA;CACtC;AAED;;;;;GAKG;AACH,MAAM,WAAW,QAAQ;IACvB,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAA;IAC9B,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,eAAe,CAAC,EAAE,mBAAmB,CAAA;IACrC,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,KAAK,CAAC,EAAE,SAAS,CAAA;IACjB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;IAChB,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,YAAY,CAAC,EAAE,OAAO,CAAA;IACtB,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAC1C;AAED,qBAAa,IAAI;IAWO,SAAS,CAAC,MAAM,EAAE,MAAM;IAV9C,SAAS,CAAC,MAAM,CAAC,EAAY,MAAM,GAAG,MAAM,GAAG,IAAI,CAAA;IACnD,SAAS,CAAC,YAAY,CAAC,EAAM,MAAM,CAAA;IACnC,SAAS,CAAC,gBAAgB,CAAC,EAAE,mBAAmB,CAAA;IAChD,SAAS,CAAC,KAAK,CAAC,EAAa,MAAM,CAAA;IACnC,SAAS,CAAC,MAAM,CAAC,EAAY,SAAS,CAAA;IACtC,SAAS,CAAC,MAAM,CAAC,EAAY,MAAM,EAAE,CAAA;IACrC,SAAS,CAAC,IAAI,CAAC,EAAc,MAAM,CAAA;IACnC,SAAS,CAAC,aAAa,CAAC,EAAK,OAAO,CAAA;IACpC,SAAS,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAEpD,SAAS,aAAuB,MAAM,EAAE,MAAM;IAE9C;wEACoE;IACpE,MAAM,CAAC,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAIhC;;kEAE8D;IAC9D,KAAK,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,IAAI;IAKlD,mEAAmE;IACnE,WAAW,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI;IAK5B;yDACqD;IACrD,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,GAAE,2BAAqC,GAAG,IAAI;IAKpF;0DACsD;IACtD,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAKxB,uCAAuC;IACvC,KAAK,CAAC,CAAC,EAAE,SAAS,GAAG,IAAI;IAKzB;6DACyD;IACzD,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,IAAI;IAK7B,sCAAsC;IACtC,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAKvB,kDAAkD;IAClD,eAAe,CAAC,KAAK,GAAE,OAAc,GAAG,IAAI;IAK5C;iCAC6B;IAC7B,eAAe,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAKrD;;0EAEsE;IACtE,MAAM,IAAI,QAAQ;CAanB"}