@veil-runtime/ui 0.0.0-stage → 0.3.0

package/dist/composition.js

@@ -0,0 +1,227 @@
+import { deriveUIField } from "./derive-input-fields.js";
+import { validateRichCapabilityInput, validateRichInputSchema, validateRichInputValue } from "./input-schema.js";
+import { assertBoundedData, assertSafeKey, copyData } from "./validation-safety.js";
+const builtins = new Set(["Stack", "Form", "Field", "Submit", "Text", "Status"]);
+const identifier = /^[A-Za-z][A-Za-z0-9._-]{0,127}$/;
+export function defineComposedApplication(definition) {
+    return definition;
+}
+export function validateComposedApplication(definition, customComponents = []) {
+    assertBoundedData(definition);
+    if (typeof definition.id !== "string" || !identifier.test(definition.id) || typeof definition.title !== "string" || !definition.title.trim())
+        throw new Error("Invalid application identity");
+    if (!definition.fields || typeof definition.fields !== "object" || Array.isArray(definition.fields))
+        throw new Error("Invalid field schema");
+    validateRichInputSchema(definition.fields);
+    for (const [name, field] of Object.entries(definition.fields)) {
+        if (!identifier.test(name) || typeof field.required !== "boolean" || typeof field.description !== "string")
+            throw new Error(`Invalid field contract: ${name}`);
+        if (field.enum !== undefined && (!Array.isArray(field.enum) || field.enum.length === 0 || new Set(field.enum).size !== field.enum.length))
+            throw new Error(`Invalid enum: ${name}`);
+        if (field.format !== undefined && !["date", "date-time", "multiline"].includes(field.format))
+            throw new Error(`Invalid format: ${name}`);
+        if (field.semantic !== undefined && field.semantic !== "currency")
+            throw new Error(`Invalid semantic: ${name}`);
+        if (field.currency !== undefined && (typeof field.currency !== "string" || !/^[A-Z]{3}$/.test(field.currency)))
+            throw new Error(`Invalid currency: ${name}`);
+        for (const key of ["minLength", "maxLength", "minItems", "maxItems"]) {
+            const value = field[key];
+            if (value !== undefined && (!Number.isSafeInteger(value) || value < 0))
+                throw new Error(`Invalid ${key}: ${name}`);
+        }
+        for (const key of ["minimum", "maximum"]) {
+            const value = field[key];
+            if (value !== undefined && (typeof value !== "number" || !Number.isFinite(value)))
+                throw new Error(`Invalid ${key}: ${name}`);
+        }
+    }
+    if (!Array.isArray(definition.actions) || new Set(definition.actions).size !== definition.actions.length || definition.actions.some((id) => typeof id !== "string" || !identifier.test(id)))
+        throw new Error("Invalid action list");
+    for (const name of customComponents) {
+        if (!identifier.test(name))
+            throw new Error(`Invalid component name: ${name}`);
+        assertSafeKey(name);
+    }
+    const known = new Set([...builtins, ...customComponents]);
+    if (known.size !== builtins.size + customComponents.length)
+        throw new Error("Component names must be unique and cannot replace built-ins");
+    const fields = new Set();
+    const actions = new Set();
+    function visit(node, insideForm) {
+        if (!node || typeof node !== "object" || !known.has(node.component))
+            throw new Error(`Unknown component: ${String(node?.component)}`);
+        if (node.children !== undefined && !Array.isArray(node.children))
+            throw new Error("Component children must be an array");
+        if (node.component === "Form" && insideForm)
+            throw new Error("Nested forms are unsupported");
+        if (node.component === "Field") {
+            if (!insideForm || !node.field || !Object.hasOwn(definition.fields, node.field) || fields.has(node.field))
+                throw new Error(`Invalid or duplicate field: ${node.field}`);
+            const type = definition.fields[node.field]?.type;
+            if (type === "object" || type === "array")
+                throw new Error(`Structured field requires a custom component: ${node.field}`);
+            fields.add(node.field);
+        }
+        else if (node.field !== undefined)
+            throw new Error("Only Field nodes accept a field binding");
+        if (node.component === "Submit") {
+            if (!insideForm || !node.action || !definition.actions.includes(node.action) || actions.has(node.action))
+                throw new Error(`Invalid or duplicate action: ${node.action}`);
+            actions.add(node.action);
+        }
+        else if (node.action !== undefined)
+            throw new Error("Only Submit nodes accept an action");
+        if (node.text !== undefined && (typeof node.text !== "string" || node.text.length > 4096))
+            throw new Error("Invalid component text");
+        if (node.component === "Field" || node.component === "Submit" || node.component === "Text" || node.component === "Status") {
+            if (node.children?.length)
+                throw new Error(`${node.component} cannot contain children`);
+        }
+        for (const child of node.children ?? [])
+            visit(child, insideForm || node.component === "Form");
+    }
+    visit(definition.screen, false);
+    if (fields.size !== Object.keys(definition.fields).length || actions.size !== definition.actions.length)
+        throw new Error("All fields and actions must appear in the screen");
+    if (definition.initialState !== undefined) {
+        if (!definition.initialState || typeof definition.initialState !== "object" || Array.isArray(definition.initialState))
+            throw new Error("Invalid initial state");
+        for (const [key, value] of Object.entries(definition.initialState)) {
+            const field = Object.hasOwn(definition.fields, key) ? definition.fields[key] : undefined;
+            if (!field)
+                throw new Error(`Unknown initial field: ${key}`);
+            validateRichInputValue(value, { ...field, required: false }, key);
+        }
+    }
+}
+export function createCompositionController(definition, handlers, customComponents = []) {
+    validateComposedApplication(definition, customComponents);
+    const source = copyData(definition);
+    for (const action of source.actions)
+        if (!Object.hasOwn(handlers, action) || typeof handlers[action] !== "function")
+            throw new Error(`Missing action handler: ${action}`);
+    const listeners = new Set();
+    const values = Object.fromEntries(Object.keys(source.fields).map((name) => [name, source.initialState && Object.hasOwn(source.initialState, name) ? source.initialState[name] : (source.fields[name]?.type === "boolean" ? false : "")]));
+    let errors = {};
+    let status = "idle";
+    let message = "";
+    let disposed = false;
+    const snapshot = () => copyData({ values, errors, status, message });
+    const assertSnapshot = (nextValues, nextErrors, nextStatus, nextMessage) => {
+        assertBoundedData({ values: nextValues, errors: nextErrors, status: nextStatus, message: nextMessage });
+    };
+    const errorBudget = Object.fromEntries(Object.entries(source.fields).map(([name, field]) => [name, `Check ${deriveUIField(name, field).label}`]));
+    const assertValuesResource = (nextValues) => {
+        assertSnapshot(nextValues, errorBudget, "error", "Unable to save. Please try again.");
+    };
+    assertValuesResource(values);
+    const emit = () => { for (const listener of listeners) {
+        try {
+            listener(snapshot());
+        }
+        catch { /* Host listener failures cannot change the transaction. */ }
+    } };
+    return {
+        get definition() { return copyData(source); },
+        snapshot,
+        field(name) {
+            const field = Object.hasOwn(source.fields, name) ? source.fields[name] : undefined;
+            if (!field)
+                throw new Error(`Unknown field: ${name}`);
+            return deriveUIField(name, field);
+        },
+        setField(name, value) {
+            if (disposed)
+                return;
+            const field = Object.hasOwn(source.fields, name) ? source.fields[name] : undefined;
+            if (!field)
+                throw new Error(`Unknown field: ${name}`);
+            if (status === "submitting")
+                return;
+            assertBoundedData(value);
+            const nextValues = { ...values, [name]: copyData(value) };
+            const next = { ...errors };
+            try {
+                validateRichInputValue(value, field, name);
+                delete next[name];
+            }
+            catch {
+                next[name] = `Check ${deriveUIField(name, field).label}`;
+            }
+            assertValuesResource(nextValues);
+            Object.assign(values, nextValues);
+            errors = next;
+            status = "idle";
+            message = "";
+            emit();
+        },
+        async submit(action) {
+            if (disposed)
+                return false;
+            if (!source.actions.includes(action))
+                throw new Error(`Unknown action: ${action}`);
+            if (status === "submitting")
+                return false;
+            const next = {};
+            for (const [name, field] of Object.entries(source.fields)) {
+                try {
+                    validateRichInputValue(values[name], field, name);
+                }
+                catch {
+                    next[name] = `Check ${deriveUIField(name, field).label}`;
+                }
+            }
+            assertSnapshot(values, next, Object.keys(next).length ? "error" : "submitting", Object.keys(next).length ? "Review the highlighted fields." : "Submitting…");
+            errors = next;
+            if (Object.keys(next).length) {
+                status = "error";
+                message = "Review the highlighted fields.";
+                emit();
+                return false;
+            }
+            const input = copyData(values);
+            validateRichCapabilityInput(source.fields, input);
+            status = "submitting";
+            message = "Submitting…";
+            emit();
+            try {
+                const result = await handlers[action](input);
+                if (disposed)
+                    return false;
+                assertBoundedData(result);
+                if (!result || typeof result !== "object" || Object.keys(result).length !== 1 || (result.ok !== true && result.ok !== false))
+                    throw new Error("Invalid action result");
+                if (!result.ok)
+                    throw new Error("Action failed");
+                assertSnapshot(values, errors, "success", "Saved successfully.");
+                status = "success";
+                message = "Saved successfully.";
+                emit();
+                return true;
+            }
+            catch {
+                if (disposed)
+                    return false;
+                assertSnapshot(values, errors, "error", "Unable to save. Please try again.");
+                status = "error";
+                message = "Unable to save. Please try again.";
+                emit();
+                return false;
+            }
+        },
+        subscribe(listener) {
+            if (disposed)
+                throw new Error("Composition controller is disposed");
+            listeners.add(listener);
+            try {
+                listener(snapshot());
+            }
+            catch (error) {
+                listeners.delete(listener);
+                throw error;
+            }
+            return () => { listeners.delete(listener); };
+        },
+        dispose() { disposed = true; listeners.clear(); },
+    };
+}

package/dist/derive-input-fields.d.ts

@@ -0,0 +1,4 @@
+import type { UIField } from "./capability-view.js";
+import type { RichCapabilityInputField, RichCapabilityInputSchema } from "./input-schema.js";
+export declare function deriveUIField(name: string, field: RichCapabilityInputField): UIField;
+export declare function deriveUIFields(schema: RichCapabilityInputSchema): UIField[];

package/dist/derive-input-fields.js

@@ -0,0 +1,63 @@
+function humanise(value) {
+    return value.replace(/[._-]+/g, " ").replace(/([a-z])([A-Z])/g, "$1 $2")
+        .replace(/\b\w/g, (character) => character.toUpperCase());
+}
+function interaction(field) {
+    if (field.enum)
+        return "select";
+    if (field.type === "object")
+        return "object";
+    if (field.type === "array")
+        return "array";
+    if (field.format === "date")
+        return "date";
+    if (field.format === "date-time")
+        return "datetime";
+    if (field.format === "multiline")
+        return "textarea";
+    if (field.semantic === "currency")
+        return "currency";
+    if (field.type === "number" || field.type === "integer")
+        return "number";
+    if (field.type === "boolean")
+        return "checkbox";
+    return "text";
+}
+export function deriveUIField(name, field) {
+    return {
+        name,
+        label: humanise(name),
+        type: interaction(field),
+        required: field.required,
+        description: field.description,
+        authoritativeType: field.type,
+        ...(field.enum ? { options: [...field.enum] } : {}),
+        ...(field.format ? { format: field.format } : {}),
+        ...(field.semantic ? { semantic: field.semantic, currency: field.currency } : {}),
+        ...(field.minLength !== undefined ? { minLength: field.minLength } : {}),
+        ...(field.maxLength !== undefined ? { maxLength: field.maxLength } : {}),
+        ...(field.minimum !== undefined ? { minimum: field.minimum } : {}),
+        ...(field.maximum !== undefined ? { maximum: field.maximum } : {}),
+        ...(field.minItems !== undefined ? { minItems: field.minItems } : {}),
+        ...(field.maxItems !== undefined ? { maxItems: field.maxItems } : {}),
+        ...(field.fields ? {
+            fields: Object.entries(field.fields).map(([child, definition]) => deriveUIField(child, definition)),
+        } : {}),
+        ...(field.items ? { item: deriveUIField("item", field.items) } : {}),
+        derivation: {
+            source: "authoritative-input-schema",
+            reason: field.enum
+                ? "finite-enum"
+                : field.type === "object"
+                    ? "nested-object"
+                    : field.type === "array"
+                        ? "structured-array"
+                        : field.semantic === "currency"
+                            ? "currency-semantic"
+                            : field.format ?? "primitive-type",
+        },
+    };
+}
+export function deriveUIFields(schema) {
+    return Object.entries(schema).map(([name, field]) => deriveUIField(name, field));
+}

package/dist/derive-output-view.d.ts

@@ -0,0 +1,26 @@
+import { type CapabilityOutputSchema } from "./output-schema.js";
+import type { UIDetailField, UIAggregateMetric, UIAction, UITableColumn, CapabilityView } from "./capability-view.js";
+type CapabilityViewTimeSeries = NonNullable<CapabilityView["timeSeries"]>;
+export interface DerivedOutputView {
+    surface: "form" | "table" | "detail" | "aggregate" | "time-series" | "category-series";
+    derivation: {
+        source: "input-schema" | "output-schema";
+        reason: "no-output-schema" | "single-top-level-array-of-objects" | "flat-output-object" | "structured-output-object" | "authoritative-aggregate-object" | "authoritative-time-series" | "authoritative-category-series";
+    };
+    table?: {
+        dataPath: string;
+        columns: UITableColumn[];
+        actions?: UIAction[];
+    };
+    detail?: {
+        fields: UIDetailField[];
+        actions?: UIAction[];
+    };
+    aggregate?: {
+        metrics: UIAggregateMetric[];
+    };
+    timeSeries?: CapabilityViewTimeSeries;
+    categorySeries?: NonNullable<CapabilityView["categorySeries"]>;
+}
+export declare function deriveOutputView(schema?: CapabilityOutputSchema): DerivedOutputView;
+export {};

package/dist/derive-output-view.js

@@ -0,0 +1,97 @@
+import { getOutputSchemaFields, isAggregateOutputSchema, } from "./output-schema.js";
+function humanise(value) {
+    return value
+        .replace(/[._-]+/g, " ")
+        .replace(/([a-z])([A-Z])/g, "$1 $2")
+        .replace(/\b\w/g, (character) => character.toUpperCase());
+}
+function deriveTableColumns(item) {
+    if (item.type !== "object" ||
+        !item.fields) {
+        return [];
+    }
+    return Object.keys(item.fields).map((key) => ({
+        key,
+        label: humanise(key),
+    }));
+}
+function deriveDetailFields(schema) {
+    return Object.entries(getOutputSchemaFields(schema)).map(([key, definition]) => ({
+        key,
+        label: humanise(key),
+        ...(definition.semantic && definition.semantic !== "time-series" && definition.semantic !== "category-series" ? { semantic: definition.semantic } : {}),
+        ...(definition.currency ? { currency: definition.currency } : {}),
+    }));
+}
+export function deriveOutputView(schema) {
+    if (!schema) {
+        return {
+            surface: "form",
+            derivation: { source: "input-schema", reason: "no-output-schema" },
+        };
+    }
+    if (isAggregateOutputSchema(schema)) {
+        return {
+            surface: "aggregate",
+            derivation: { source: "output-schema", reason: "authoritative-aggregate-object" },
+            aggregate: {
+                metrics: Object.entries(schema.fields).map(([key, definition]) => ({
+                    key,
+                    label: humanise(key),
+                    authoritativeType: definition.type,
+                    semantic: definition.semantic,
+                    ...(definition.currency ? { currency: definition.currency } : {}),
+                    derivation: { source: "authoritative-output-schema", reason: "metric-semantics" },
+                })),
+            },
+        };
+    }
+    const entries = Object.entries(getOutputSchemaFields(schema));
+    const categorySeries = entries.filter(([, definition]) => definition.semantic === "category-series");
+    if (categorySeries.length === 1) {
+        const [dataPath, collection] = categorySeries[0], itemFields = Object.entries(collection.items.fields), [dimensionKey, dimension] = itemFields.find(([, field]) => field.role === "dimension"), [measureKey, measure] = itemFields.find(([, field]) => field.role === "measure");
+        return { surface: "category-series", derivation: { source: "output-schema", reason: "authoritative-category-series" }, categorySeries: { dataPath, visualization: "bar", ordering: "source-order", dimension: { key: dimensionKey, label: humanise(dimensionKey), type: "string", ...(dimension.enum ? { enum: dimension.enum } : {}), role: "dimension" }, measure: { key: measureKey, label: humanise(measureKey), type: measure.type, semantic: measure.semantic, ...(measure.currency ? { currency: measure.currency } : {}), role: "measure" }, derivation: { source: "authoritative-output-schema", reason: "categorical-dimension-with-numeric-measure" } } };
+    }
+    const timeSeries = entries.filter(([, definition]) => definition.semantic === "time-series");
+    if (timeSeries.length === 1) {
+        const [dataPath, collection] = timeSeries[0];
+        const itemFields = Object.entries(collection.items.fields);
+        const [dimensionKey, dimension] = itemFields.find(([, field]) => field.role === "dimension");
+        const [measureKey, measure] = itemFields.find(([, field]) => field.role === "measure");
+        return { surface: "time-series", derivation: { source: "output-schema", reason: "authoritative-time-series" }, timeSeries: { dataPath, visualization: "line", dimension: { key: dimensionKey, label: humanise(dimensionKey), type: "string", format: dimension.format, role: "dimension" }, measure: { key: measureKey, label: humanise(measureKey), type: measure.type, semantic: measure.semantic, ...(measure.currency ? { currency: measure.currency } : {}), role: "measure" }, derivation: { source: "authoritative-output-schema", reason: "temporal-dimension-with-numeric-measure" } } };
+    }
+    // A single top-level array of objects naturally maps to a table.
+    if (entries.length === 1) {
+        const [key, definition] = entries[0];
+        if (definition.type === "array" &&
+            definition.items?.type === "object") {
+            return {
+                surface: "table",
+                derivation: { source: "output-schema", reason: "single-top-level-array-of-objects" },
+                table: {
+                    dataPath: key,
+                    columns: deriveTableColumns(definition.items),
+                },
+            };
+        }
+    }
+    // A flat object naturally maps to a detail surface.
+    const isFlatObject = entries.every(([, definition]) => definition.type !== "array" &&
+        definition.type !== "object");
+    if (isFlatObject) {
+        return {
+            surface: "detail",
+            derivation: { source: "output-schema", reason: "flat-output-object" },
+            detail: {
+                fields: deriveDetailFields(schema),
+            },
+        };
+    }
+    return {
+        surface: "detail",
+        derivation: { source: "output-schema", reason: "structured-output-object" },
+        detail: {
+            fields: deriveDetailFields(schema),
+        },
+    };
+}

package/dist/dom.d.ts

@@ -0,0 +1,31 @@
+import type { ComponentNode, CompositionController } from "./composition.js";
+import { type InterfaceController, type InterfaceDefinition, type InterfaceEvent, type InterfaceNode, type InterfaceSnapshot } from "./interface.js";
+export type DOMComponent = (node: Readonly<ComponentNode>, context: {
+    controller: CompositionController;
+    renderChildren: () => HTMLElement[];
+}) => HTMLElement;
+export type DOMComponentRegistry = Readonly<Record<string, DOMComponent>>;
+/** Mount one composed screen. Caller owns the controller, mount point, and disposal. */
+export declare function mountComposedApplication(target: HTMLElement, controller: CompositionController, components?: DOMComponentRegistry): () => void;
+export interface InterfaceDOMComponentInstance {
+    element: HTMLElement;
+    update?: (node: Readonly<InterfaceNode>, snapshot: InterfaceSnapshot) => void;
+    dispose?: () => void;
+}
+export type InterfaceDOMComponent = (node: Readonly<InterfaceNode>, context: {
+    renderChildren: () => HTMLElement[];
+    snapshot: InterfaceSnapshot;
+    signal: AbortSignal;
+}) => HTMLElement | InterfaceDOMComponentInstance;
+export type InterfaceDOMRegistry = Readonly<Record<string, InterfaceDOMComponent>>;
+/** Own a controller and one DOM mount with a single teardown. Component factories remain trusted host code. */
+export declare function createMountedInterface(target: HTMLElement, definition: InterfaceDefinition, options?: {
+    components?: InterfaceDOMRegistry;
+    allowedActions?: readonly string[];
+    onEvent?: (event: InterfaceEvent) => void | Promise<void>;
+    onError?: (error: unknown) => void;
+}): InterfaceController & {
+    unmount(): void;
+};
+/** Mount a framework-neutral interface. The caller owns and disposes the controller separately. */
+export declare function mountInterface(target: HTMLElement, controller: InterfaceController, components?: InterfaceDOMRegistry, onError?: (error: unknown) => void): () => void;