@adminiumjs/widgets 0.1.0-rc.1

package/dist/registry/shared-config.d.ts

@@ -0,0 +1,146 @@
+import { z } from 'zod';
+/**
+ * Shared config carried by every widget (04-widget-registry.md §2.1, verbatim;
+ * annex "Conventions" — the annex field `dataSource` is implemented as
+ * `binding`, see 04 Open decisions #1). Every widget's `configSchema` is an
+ * `.extend()` of this schema.
+ */
+export declare const widgetSharedConfigSchema: z.ZodObject<{
+    title: z.ZodOptional<z.ZodString>;
+    subtitle: z.ZodOptional<z.ZodString>;
+    icon: z.ZodOptional<z.ZodString>;
+    href: z.ZodOptional<z.ZodString>;
+    binding: z.ZodOptional<z.ZodObject<{
+        kind: z.ZodDefault<z.ZodLiteral<"table-query">>;
+        connectionId: z.ZodString;
+        source: z.ZodObject<{
+            schema: z.ZodOptional<z.ZodString>;
+            name: z.ZodString;
+            type: z.ZodDefault<z.ZodEnum<{
+                table: "table";
+                view: "view";
+            }>>;
+        }, z.core.$strip>;
+        shape: z.ZodEnum<{
+            "single-metric": "single-metric";
+            "metric+delta": "metric+delta";
+            timeseries: "timeseries";
+            "multi-timeseries": "multi-timeseries";
+            categorical: "categorical";
+            "record-list": "record-list";
+            record: "record";
+            matrix: "matrix";
+            "hierarchy/tree": "hierarchy/tree";
+            "calendar-events": "calendar-events";
+            "geo-points": "geo-points";
+            flows: "flows";
+            ohlc: "ohlc";
+            distribution: "distribution";
+            "boolean-map": "boolean-map";
+            stream: "stream";
+            "form-state": "form-state";
+            static: "static";
+        }>;
+        select: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        aggregations: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            fn: z.ZodEnum<{
+                count: "count";
+                sum: "sum";
+                avg: "avg";
+                min: "min";
+                max: "max";
+                count_distinct: "count_distinct";
+                percentile: "percentile";
+            }>;
+            column: z.ZodOptional<z.ZodString>;
+            p: z.ZodOptional<z.ZodNumber>;
+            alias: z.ZodString;
+        }, z.core.$strip>>>;
+        groupBy: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        bucket: z.ZodOptional<z.ZodObject<{
+            column: z.ZodString;
+            unit: z.ZodEnum<{
+                hour: "hour";
+                day: "day";
+                week: "week";
+                month: "month";
+                quarter: "quarter";
+                year: "year";
+            }>;
+        }, z.core.$strip>>;
+        filters: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            column: z.ZodString;
+            op: z.ZodEnum<{
+                eq: "eq";
+                neq: "neq";
+                gt: "gt";
+                gte: "gte";
+                lt: "lt";
+                lte: "lte";
+                in: "in";
+                like: "like";
+                ilike: "ilike";
+                is_null: "is_null";
+                not_null: "not_null";
+                between: "between";
+            }>;
+            value: z.ZodOptional<z.ZodUnknown>;
+            param: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
+        window: z.ZodOptional<z.ZodObject<{
+            column: z.ZodString;
+            last: z.ZodNumber;
+            unit: z.ZodEnum<{
+                hour: "hour";
+                day: "day";
+                week: "week";
+                month: "month";
+                quarter: "quarter";
+                year: "year";
+            }>;
+            compareToPrior: z.ZodDefault<z.ZodBoolean>;
+        }, z.core.$strip>>;
+        orderBy: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            column: z.ZodString;
+            dir: z.ZodEnum<{
+                asc: "asc";
+                desc: "desc";
+            }>;
+        }, z.core.$strip>>>;
+        limit: z.ZodOptional<z.ZodNumber>;
+        cursor: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    refreshInterval: z.ZodOptional<z.ZodNumber>;
+    emptyState: z.ZodOptional<z.ZodObject<{
+        icon: z.ZodOptional<z.ZodString>;
+        titleKey: z.ZodOptional<z.ZodString>;
+        bodyKey: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    permissions: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    tone: z.ZodOptional<z.ZodEnum<{
+        accent: "accent";
+        pos: "pos";
+        warn: "warn";
+        danger: "danger";
+        info: "info";
+        muted: "muted";
+    }>>;
+    format: z.ZodOptional<z.ZodObject<{
+        locale: z.ZodOptional<z.ZodString>;
+        currency: z.ZodOptional<z.ZodString>;
+        number: z.ZodOptional<z.ZodEnum<{
+            percent: "percent";
+            plain: "plain";
+            compact: "compact";
+        }>>;
+        date: z.ZodOptional<z.ZodEnum<{
+            relative: "relative";
+            short: "short";
+            long: "long";
+        }>>;
+        referenceTime: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    testId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type WidgetSharedConfig = z.infer<typeof widgetSharedConfigSchema>;
+//# sourceMappingURL=shared-config.d.ts.map

package/dist/registry/shared-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared-config.d.ts","sourceRoot":"","sources":["../../src/registry/shared-config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA+BnC,CAAC;AAEH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC"}

package/dist/registry/shared-config.js

@@ -0,0 +1,41 @@
+import { z } from 'zod';
+import { queryDescriptorSchema } from '../page-config/index.js';
+/**
+ * Shared config carried by every widget (04-widget-registry.md §2.1, verbatim;
+ * annex "Conventions" — the annex field `dataSource` is implemented as
+ * `binding`, see 04 Open decisions #1). Every widget's `configSchema` is an
+ * `.extend()` of this schema.
+ */
+export const widgetSharedConfigSchema = z.object({
+    title: z.string().optional(),
+    subtitle: z.string().optional(),
+    icon: z.string().optional(), // lucide-react icon name
+    href: z.string().optional(), // drill-through route
+    binding: queryDescriptorSchema.optional(), // 04 §5; absent → demoData(seed)
+    refreshInterval: z.number().int().min(5).max(86_400).optional(), // seconds
+    emptyState: z
+        .object({
+        icon: z.string().optional(),
+        titleKey: z.string().optional(),
+        bodyKey: z.string().optional(),
+    })
+        .optional(),
+    permissions: z.array(z.string()).optional(), // role ids that may see this instance
+    tone: z.enum(['accent', 'pos', 'warn', 'danger', 'info', 'muted']).optional(),
+    format: z
+        .object({
+        locale: z.string().optional(), // per-widget override, else app locale
+        currency: z.string().optional(),
+        number: z.enum(['plain', 'compact', 'percent']).optional(),
+        date: z.enum(['relative', 'short', 'long']).optional(),
+        /**
+         * Reference clock (epoch ms) for relative timestamps. Widgets that render
+         * "3h ago"-style times use it as `now` when set, else the wall clock —
+         * pinning it makes demo/VRT captures byte-deterministic (04-T17).
+         */
+        referenceTime: z.number().int().optional(),
+    })
+        .optional(),
+    testId: z.string().optional(),
+});
+//# sourceMappingURL=shared-config.js.map

package/dist/registry/shared-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared-config.js","sourceRoot":"","sources":["../../src/registry/shared-config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAEhE;;;;;GAKG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC/C,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC5B,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC/B,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,EAAE,yBAAyB;IACtD,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,EAAE,sBAAsB;IACnD,OAAO,EAAE,qBAAqB,CAAC,QAAQ,EAAE,EAAE,iCAAiC;IAC5E,eAAe,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,QAAQ,EAAE,EAAE,UAAU;IAC3E,UAAU,EAAE,CAAC;SACV,MAAM,CAAC;QACN,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;QAC3B,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;QAC/B,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;KAC/B,CAAC;SACD,QAAQ,EAAE;IACb,WAAW,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE,EAAE,sCAAsC;IACnF,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,QAAQ,EAAE;IAC7E,MAAM,EAAE,CAAC;SACN,MAAM,CAAC;QACN,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,EAAE,uCAAuC;QACtE,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;QAC/B,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC,CAAC,QAAQ,EAAE;QAC1D,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,UAAU,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC,QAAQ,EAAE;QACtD;;;;WAIG;QACH,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE;KAC3C,CAAC;SACD,QAAQ,EAAE;IACb,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CAC9B,CAAC,CAAC"}

package/dist/registry/types.d.ts

@@ -0,0 +1,94 @@
+import type { ComponentType, LazyExoticComponent } from 'react';
+import { z } from 'zod';
+import type { DataShape } from '../page-config/index.js';
+/**
+ * Widget registry core types — workplan/04-widget-registry.md §2.1, verbatim.
+ * A widget is one React component + one Zod config schema + one data-contract
+ * declaration + default grid sizing, registered exactly once in a typed map.
+ * Visual variants are config, never new registry ids.
+ */
+/** The thirteen widget families (04 §2.4). */
+export type WidgetFamily = 'kpi' | 'charts' | 'tables' | 'feeds' | 'calendar' | 'boards' | 'geo' | 'media' | 'communication' | 'forms' | 'chrome' | 'system' | 'domain';
+export declare const WIDGET_FAMILIES: readonly ["kpi", "charts", "tables", "feeds", "calendar", "boards", "geo", "media", "communication", "forms", "chrome", "system", "domain"];
+export interface WidgetSizing {
+    minW: number;
+    minH: number;
+    defaultW: number;
+    defaultH: number;
+}
+/** WidgetFrame loading silhouette variants (04 §2.1 / §4). */
+export type WidgetSkeleton = 'card' | 'chart' | 'table' | 'list' | 'block';
+/** Grid placement class (04 §2.1). */
+export type WidgetPlacement = 'grid' | 'inline' | 'overlay' | 'page';
+export interface WidgetCapabilities {
+    exportPng?: boolean;
+    exportCsv?: boolean;
+    realtime?: boolean;
+    editsData?: boolean;
+}
+export interface WidgetDefinition<S extends z.ZodType = z.ZodType> {
+    id: string;
+    family: WidgetFamily;
+    component: LazyExoticComponent<ComponentType<WidgetProps<z.infer<S>>>>;
+    configSchema: S;
+    dataContract: DataShape | DataShape[];
+    sizing: WidgetSizing;
+    placement: WidgetPlacement;
+    skeleton: WidgetSkeleton;
+    capabilities?: WidgetCapabilities;
+    demoData: (seed: number) => unknown;
+    descriptionKey: string;
+}
+export interface WidgetProps<C> {
+    config: C;
+    data: unknown;
+    instanceId: string;
+    onEvent: (e: WidgetEvent) => void | Promise<unknown>;
+}
+/**
+ * Events a widget component may emit through `onEvent`. The host (dashboard
+ * shell / PageRenderer) interprets them — widgets never navigate or mutate
+ * directly.
+ */
+export type WidgetEvent = 
+/** Drill-through navigation to a route (config.href or a computed link). */
+{
+    type: 'drill-through';
+    href: string;
+}
+/** Open a single record (row click in data-grid, card click in kanban…). */
+ | {
+    type: 'record-open';
+    connectionId?: string | undefined;
+    table: string;
+    recordId: string | number;
+    /**
+     * Instance id of a sibling widget this selection pairs with — the host
+     * MAY focus/scroll it to the same record (annex §7 `map-bubble.linkedList`
+     * names a `ranked-entity-list`). Widgets never talk to each other, so the
+     * pairing rides on the event and the host decides what to do with it;
+     * absent → an unpaired open, which every existing host already handles.
+     */
+    linkedInstanceId?: string | undefined;
+}
+/**
+ * Mutation *intent* — widgets with `capabilities.editsData` describe the
+ * change; the host runs it through the CRUD API (with undo + audit).
+ */
+ | {
+    type: 'mutate';
+    intent: 'insert' | 'update' | 'delete';
+    connectionId?: string | undefined;
+    table: string;
+    recordId?: string | number | undefined;
+    values?: Record<string, unknown> | undefined;
+};
+/**
+ * Identity helper that erases the config-schema type parameter so concrete
+ * definitions (whose components are typed against their own config) can live
+ * in heterogeneous `WidgetDefinition[]` family arrays. React component props
+ * are contravariant, so this cast is the sanctioned single point of erasure —
+ * `validateInstanceConfig` re-establishes safety at the config boundary.
+ */
+export declare function defineWidget<S extends z.ZodType>(definition: WidgetDefinition<S>): WidgetDefinition;
+//# sourceMappingURL=types.d.ts.map

package/dist/registry/types.d.ts.map

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

package/dist/registry/types.js

@@ -0,0 +1,27 @@
+import { z } from 'zod';
+export const WIDGET_FAMILIES = [
+    'kpi',
+    'charts',
+    'tables',
+    'feeds',
+    'calendar',
+    'boards',
+    'geo',
+    'media',
+    'communication',
+    'forms',
+    'chrome',
+    'system',
+    'domain',
+];
+/**
+ * Identity helper that erases the config-schema type parameter so concrete
+ * definitions (whose components are typed against their own config) can live
+ * in heterogeneous `WidgetDefinition[]` family arrays. React component props
+ * are contravariant, so this cast is the sanctioned single point of erasure —
+ * `validateInstanceConfig` re-establishes safety at the config boundary.
+ */
+export function defineWidget(definition) {
+    return definition;
+}
+//# sourceMappingURL=types.js.map

package/dist/registry/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/registry/types.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AA2BxB,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,KAAK;IACL,QAAQ;IACR,QAAQ;IACR,OAAO;IACP,UAAU;IACV,QAAQ;IACR,KAAK;IACL,OAAO;IACP,eAAe;IACf,OAAO;IACP,QAAQ;IACR,QAAQ;IACR,QAAQ;CACkC,CAAC;AAsF7C;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAAsB,UAA+B;IAC/E,OAAO,UAAyC,CAAC;AACnD,CAAC"}

package/dist/registry/widget-missing.d.ts

@@ -0,0 +1,150 @@
+import { z } from 'zod';
+import type { WidgetDefinition } from './types.js';
+/** Registry id of the unknown-widget fallback (04 §2.2). */
+export declare const WIDGET_MISSING_ID = "widget-missing";
+export declare const widgetMissingConfigSchema: z.ZodObject<{
+    title: z.ZodOptional<z.ZodString>;
+    subtitle: z.ZodOptional<z.ZodString>;
+    icon: z.ZodOptional<z.ZodString>;
+    href: z.ZodOptional<z.ZodString>;
+    binding: z.ZodOptional<z.ZodObject<{
+        kind: z.ZodDefault<z.ZodLiteral<"table-query">>;
+        connectionId: z.ZodString;
+        source: z.ZodObject<{
+            schema: z.ZodOptional<z.ZodString>;
+            name: z.ZodString;
+            type: z.ZodDefault<z.ZodEnum<{
+                table: "table";
+                view: "view";
+            }>>;
+        }, z.core.$strip>;
+        shape: z.ZodEnum<{
+            "single-metric": "single-metric";
+            "metric+delta": "metric+delta";
+            timeseries: "timeseries";
+            "multi-timeseries": "multi-timeseries";
+            categorical: "categorical";
+            "record-list": "record-list";
+            record: "record";
+            matrix: "matrix";
+            "hierarchy/tree": "hierarchy/tree";
+            "calendar-events": "calendar-events";
+            "geo-points": "geo-points";
+            flows: "flows";
+            ohlc: "ohlc";
+            distribution: "distribution";
+            "boolean-map": "boolean-map";
+            stream: "stream";
+            "form-state": "form-state";
+            static: "static";
+        }>;
+        select: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        aggregations: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            fn: z.ZodEnum<{
+                count: "count";
+                sum: "sum";
+                avg: "avg";
+                min: "min";
+                max: "max";
+                count_distinct: "count_distinct";
+                percentile: "percentile";
+            }>;
+            column: z.ZodOptional<z.ZodString>;
+            p: z.ZodOptional<z.ZodNumber>;
+            alias: z.ZodString;
+        }, z.core.$strip>>>;
+        groupBy: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        bucket: z.ZodOptional<z.ZodObject<{
+            column: z.ZodString;
+            unit: z.ZodEnum<{
+                hour: "hour";
+                day: "day";
+                week: "week";
+                month: "month";
+                quarter: "quarter";
+                year: "year";
+            }>;
+        }, z.core.$strip>>;
+        filters: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            column: z.ZodString;
+            op: z.ZodEnum<{
+                eq: "eq";
+                neq: "neq";
+                gt: "gt";
+                gte: "gte";
+                lt: "lt";
+                lte: "lte";
+                in: "in";
+                like: "like";
+                ilike: "ilike";
+                is_null: "is_null";
+                not_null: "not_null";
+                between: "between";
+            }>;
+            value: z.ZodOptional<z.ZodUnknown>;
+            param: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
+        window: z.ZodOptional<z.ZodObject<{
+            column: z.ZodString;
+            last: z.ZodNumber;
+            unit: z.ZodEnum<{
+                hour: "hour";
+                day: "day";
+                week: "week";
+                month: "month";
+                quarter: "quarter";
+                year: "year";
+            }>;
+            compareToPrior: z.ZodDefault<z.ZodBoolean>;
+        }, z.core.$strip>>;
+        orderBy: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            column: z.ZodString;
+            dir: z.ZodEnum<{
+                asc: "asc";
+                desc: "desc";
+            }>;
+        }, z.core.$strip>>>;
+        limit: z.ZodOptional<z.ZodNumber>;
+        cursor: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    refreshInterval: z.ZodOptional<z.ZodNumber>;
+    emptyState: z.ZodOptional<z.ZodObject<{
+        icon: z.ZodOptional<z.ZodString>;
+        titleKey: z.ZodOptional<z.ZodString>;
+        bodyKey: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    permissions: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    tone: z.ZodOptional<z.ZodEnum<{
+        accent: "accent";
+        pos: "pos";
+        warn: "warn";
+        danger: "danger";
+        info: "info";
+        muted: "muted";
+    }>>;
+    format: z.ZodOptional<z.ZodObject<{
+        locale: z.ZodOptional<z.ZodString>;
+        currency: z.ZodOptional<z.ZodString>;
+        number: z.ZodOptional<z.ZodEnum<{
+            percent: "percent";
+            plain: "plain";
+            compact: "compact";
+        }>>;
+        date: z.ZodOptional<z.ZodEnum<{
+            relative: "relative";
+            short: "short";
+            long: "long";
+        }>>;
+        referenceTime: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    testId: z.ZodOptional<z.ZodString>;
+    missingId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * The `widget-missing` fallback definition — a `system`-family card naming the
+ * missing id. Rendered whenever a stored page config references a registry id
+ * that is not installed; it must never crash a dashboard (04 §2.2). Lazy like
+ * every other widget so registry metadata stays free of component code.
+ */
+export declare const widgetMissingDefinition: WidgetDefinition;
+//# sourceMappingURL=widget-missing.d.ts.map

package/dist/registry/widget-missing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"widget-missing.d.ts","sourceRoot":"","sources":["../../src/registry/widget-missing.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEnD,4DAA4D;AAC5D,eAAO,MAAM,iBAAiB,mBAAmB,CAAC;AAElD,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAEpC,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,EAAE,gBAWpC,CAAC"}

package/dist/registry/widget-missing.js

@@ -0,0 +1,28 @@
+import { lazy } from 'react';
+import { z } from 'zod';
+import { widgetSharedConfigSchema } from './shared-config.js';
+import { defineWidget } from './types.js';
+/** Registry id of the unknown-widget fallback (04 §2.2). */
+export const WIDGET_MISSING_ID = 'widget-missing';
+export const widgetMissingConfigSchema = widgetSharedConfigSchema.extend({
+    missingId: z.string().optional(),
+});
+/**
+ * The `widget-missing` fallback definition — a `system`-family card naming the
+ * missing id. Rendered whenever a stored page config references a registry id
+ * that is not installed; it must never crash a dashboard (04 §2.2). Lazy like
+ * every other widget so registry metadata stays free of component code.
+ */
+export const widgetMissingDefinition = defineWidget({
+    id: WIDGET_MISSING_ID,
+    family: 'system',
+    component: lazy(() => import('./WidgetMissingCard.js')),
+    configSchema: widgetMissingConfigSchema,
+    dataContract: 'static',
+    sizing: { minW: 3, minH: 2, defaultW: 3, defaultH: 3 },
+    placement: 'grid',
+    skeleton: 'card',
+    demoData: () => null,
+    descriptionKey: 'widgets.system.widgetMissing.description',
+});
+//# sourceMappingURL=widget-missing.js.map

package/dist/registry/widget-missing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"widget-missing.js","sourceRoot":"","sources":["../../src/registry/widget-missing.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC;AAC7B,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,wBAAwB,EAAE,MAAM,oBAAoB,CAAC;AAC9D,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAG1C,4DAA4D;AAC5D,MAAM,CAAC,MAAM,iBAAiB,GAAG,gBAAgB,CAAC;AAElD,MAAM,CAAC,MAAM,yBAAyB,GAAG,wBAAwB,CAAC,MAAM,CAAC;IACvE,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CACjC,CAAC,CAAC;AAEH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAqB,YAAY,CAAC;IACpE,EAAE,EAAE,iBAAiB;IACrB,MAAM,EAAE,QAAQ;IAChB,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,wBAAwB,CAAC,CAAC;IACvD,YAAY,EAAE,yBAAyB;IACvC,YAAY,EAAE,QAAQ;IACtB,MAAM,EAAE,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE;IACtD,SAAS,EAAE,MAAM;IACjB,QAAQ,EAAE,MAAM;IAChB,QAAQ,EAAE,GAAG,EAAE,CAAC,IAAI;IACpB,cAAc,EAAE,0CAA0C;CAC3D,CAAC,CAAC"}

package/dist/templates/compose.d.ts

@@ -0,0 +1,127 @@
+/**
+ * `composeTemplate` — the page-template composition engine (04-widget-registry.md
+ * §10, task 04-T07).
+ *
+ * Fills each manifest slot with the highest-scoring **accepted** candidate,
+ * repeating slots take the top-N, unfilled *optional* slots are dropped or
+ * empty-stated, and composition fails only when a slot marked `required: true`
+ * is unfillable — which surfaces as a Studio warning rather than an exception,
+ * matching the `buildDashboardEnvelope` → `null` + caller-records-a-warning
+ * idiom already used by `@adminium/engine/generate`.
+ *
+ * WHAT THIS IS NOT: the return value is an **in-memory intermediate**. Nothing
+ * here persists, and nothing here builds the stored envelope — the Engine wraps
+ * `ComposedPage` into `v`/`kind`/`id`/`template`/`title`/`source`/`nav`/`access`/
+ * `config` (01-architecture.md §6.1) with `layout` under `config.layout` and
+ * `toolbar`/`overlays` in the template's config body. Keeping the wrap out of
+ * this package is what lets `@adminium/widgets` stay free of engine imports.
+ *
+ * DETERMINISM: generation output is content-hashed (`generated_hash`, H5), so a
+ * re-run over an unchanged schema must produce a byte-identical page. Every
+ * ordering decision below is therefore total — candidate ties break on widget id
+ * then on the caller's original array index, never on `Array.prototype.sort`
+ * stability alone.
+ */
+import { type PageLayout } from '../page-config/layout.js';
+import type { DataShape } from '../page-config/data-shapes.js';
+import { type PageTemplate, type TemplateSlot } from './template-schema.js';
+/** Registry id of the widget used for `fallback: 'empty-state'` slots (annex §12). */
+export declare const EMPTY_STATE_WIDGET_ID = "empty-state";
+/** The envelope `kind` the Engine should wrap a composed template into. */
+export type ComposedPageKind = 'page' | 'dashboard';
+export declare function templateKind(templateId: string): ComposedPageKind;
+/**
+ * One ranked widget the Engine's candidate rules (04-T08/T15) emitted for this
+ * page. `shape` is the contract the candidate's binding produces — it is what a
+ * slot's `accepts.shapes` matches on; `widget` is what `accepts.widgets` matches
+ * on. `config` is passed through verbatim into the layout item (it already
+ * carries `title` + `binding`, exactly as `@adminium/engine/generate` builds
+ * them today).
+ */
+export interface TemplateCandidate {
+    /** Registry id — must be a registered widget (`ctx.isRegistered` enforces it). */
+    widget: string;
+    /** The data-contract shape this candidate's binding produces (04 §3). */
+    shape: DataShape;
+    /** Higher wins. Ties break deterministically on widget id, then input order. */
+    score: number;
+    /** Stored instance config (`title`, `binding`, widget-specific keys). */
+    config?: Record<string, unknown>;
+    /** Stable instance id; defaults to `<slot>-<n>` when omitted. */
+    instanceId?: string;
+}
+export type ComposeWarningCode = 
+/** No manifest is registered under the requested id. */
+'unknown-template'
+/** A `required: true` slot had no accepted candidate — composition failed. */
+ | 'required-slot-unfillable'
+/** An optional slot had no accepted candidate and was dropped. */
+ | 'optional-slot-omitted'
+/** An optional slot wanted `fallback: 'empty-state'` but `empty-state` is not registered yet. */
+ | 'empty-state-unavailable'
+/** A candidate named a widget id the registry does not know — dropped before matching. */
+ | 'candidate-unregistered'
+/** A `chrome.toolbar` / `chrome.overlays` id is not registered yet — dropped from the output. */
+ | 'chrome-widget-unregistered'
+/** The composed layout failed `pageLayoutSchema` — a manifest geometry bug. */
+ | 'invalid-layout';
+/** A structured, localizable-by-code warning the Studio surfaces on a generation run. */
+export interface ComposeWarning {
+    code: ComposeWarningCode;
+    templateId: string;
+    slot?: string;
+    widgetId?: string;
+    message: string;
+}
+/**
+ * The in-memory intermediate (04 §10). `type` is the envelope `kind` the Engine
+ * must wrap this into (09 §3.2).
+ */
+export interface ComposedPage {
+    type: ComposedPageKind;
+    template: string;
+    templateVersion: number;
+    layout: PageLayout;
+    toolbar: string[];
+    overlays: string[];
+}
+export interface ComposeResult {
+    /** `null` ⇔ a `required` slot was unfillable (or the template id is unknown). */
+    page: ComposedPage | null;
+    warnings: readonly ComposeWarning[];
+}
+export interface ComposeContext {
+    /**
+     * Live registry membership test. Supplying it is what keeps an unregistered id
+     * — a manifest slot allow-listing a widget whose family has not shipped, or a
+     * chrome id from a future wave — out of the generated page. Omitted ⇒ every id
+     * is treated as registered (useful in unit tests with synthetic candidates).
+     */
+    isRegistered?: (widgetId: string) => boolean;
+    /** Override the manifest source (marketplace templates, tests). */
+    templates?: ReadonlyMap<string, PageTemplate>;
+    /** Instance-id generator; defaults to `<slot>-<n>` (1-based) unless the candidate names one. */
+    makeInstanceId?: (slot: string, index: number, candidate: TemplateCandidate) => string;
+}
+/** Does `slot.accepts` admit this candidate? (04 §10 — shape contract OR id allowlist.) */
+export declare function slotAccepts(slot: TemplateSlot, candidate: TemplateCandidate): boolean;
+/**
+ * Geometry of the n-th instance of a (possibly repeating) slot. `flow: 'row'`
+ * tiles along x and wraps to a new band once the 12-column grid is full;
+ * `flow: 'column'` stacks along y. A non-repeating slot always yields `area`.
+ */
+export declare function slotInstanceArea(slot: TemplateSlot, index: number): {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+};
+/**
+ * Compose a page from a template manifest + the ranked candidates the Engine's
+ * rules emitted for it.
+ *
+ * @param template  A registered template id, or a parsed manifest (marketplace / test).
+ * @param candidates Ranked candidates; each is placed into at most one slot.
+ */
+export declare function composeTemplate(template: string | PageTemplate, candidates: readonly TemplateCandidate[], ctx?: ComposeContext): ComposeResult;
+//# sourceMappingURL=compose.d.ts.map

package/dist/templates/compose.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compose.d.ts","sourceRoot":"","sources":["../../src/templates/compose.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,OAAO,EAAqC,KAAK,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAC9F,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,+BAA+B,CAAC;AAG/D,OAAO,EAAgB,KAAK,YAAY,EAAE,KAAK,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAE1F,sFAAsF;AACtF,eAAO,MAAM,qBAAqB,gBAAgB,CAAC;AAYnD,2EAA2E;AAC3E,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,WAAW,CAAC;AAEpD,wBAAgB,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,gBAAgB,CAEjE;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,iBAAiB;IAChC,kFAAkF;IAClF,MAAM,EAAE,MAAM,CAAC;IACf,yEAAyE;IACzE,KAAK,EAAE,SAAS,CAAC;IACjB,gFAAgF;IAChF,KAAK,EAAE,MAAM,CAAC;IACd,yEAAyE;IACzE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,iEAAiE;IACjE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,MAAM,kBAAkB;AAC5B,wDAAwD;AACtD,kBAAkB;AACpB,8EAA8E;GAC5E,0BAA0B;AAC5B,kEAAkE;GAChE,uBAAuB;AACzB,iGAAiG;GAC/F,yBAAyB;AAC3B,0FAA0F;GACxF,wBAAwB;AAC1B,iGAAiG;GAC/F,4BAA4B;AAC9B,+EAA+E;GAC7E,gBAAgB,CAAC;AAErB,yFAAyF;AACzF,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,kBAAkB,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,gBAAgB,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,eAAe,EAAE,MAAM,CAAC;IACxB,MAAM,EAAE,UAAU,CAAC;IACnB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,MAAM,WAAW,aAAa;IAC5B,iFAAiF;IACjF,IAAI,EAAE,YAAY,GAAG,IAAI,CAAC;IAC1B,QAAQ,EAAE,SAAS,cAAc,EAAE,CAAC;CACrC;AAED,MAAM,WAAW,cAAc;IAC7B;;;;;OAKG;IACH,YAAY,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC;IAC7C,mEAAmE;IACnE,SAAS,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IAC9C,gGAAgG;IAChG,cAAc,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,iBAAiB,KAAK,MAAM,CAAC;CACxF;AAED,2FAA2F;AAC3F,wBAAgB,WAAW,CAAC,IAAI,EAAE,YAAY,EAAE,SAAS,EAAE,iBAAiB,GAAG,OAAO,CAIrF;AAiBD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,YAAY,EAClB,KAAK,EAAE,MAAM,GACZ;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,CAWhD;AAqCD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,GAAG,YAAY,EAC/B,UAAU,EAAE,SAAS,iBAAiB,EAAE,EACxC,GAAG,GAAE,cAAmB,GACvB,aAAa,CAsHf"}