@veil-runtime/ui 0.1.0 → 0.3.0

package/dist/dom.js

@@ -0,0 +1,554 @@
+import { createInterfaceController, resolveInterfaceBinding } from "./interface.js";
+import { registerInterfaceRenderer } from "./interface-transaction.js";
+let instance = 0;
+const mounted = new WeakMap();
+/** Mount one composed screen. Caller owns the controller, mount point, and disposal. */
+export function mountComposedApplication(target, controller, components = {}) {
+    const definition = controller.definition;
+    const id = `veil-composed-${++instance}`;
+    const updates = [];
+    const cleanup = [];
+    let active = true;
+    const element = (tag, className) => {
+        const result = document.createElement(tag);
+        result.className = className;
+        return result;
+    };
+    function render(node) {
+        const children = () => (node.children ?? []).map(render);
+        if (node.component === "Stack") {
+            const stack = element("div", "veil-stack");
+            stack.style.display = "grid";
+            stack.style.gap = "1rem";
+            stack.append(...children());
+            return stack;
+        }
+        if (node.component === "Form") {
+            const form = document.createElement("form");
+            form.noValidate = true;
+            form.style.display = "grid";
+            form.style.gap = "1rem";
+            const onSubmit = (event) => {
+                event.preventDefault();
+                if (!active)
+                    return;
+                const submitter = event.submitter;
+                const action = submitter?.form === form ? submitter.dataset["veilAction"] : form.querySelector('button[type="submit"][data-veil-action]')?.dataset["veilAction"];
+                if (action)
+                    void controller.submit(action).then((ok) => {
+                        if (!ok && active)
+                            form.querySelector('[aria-invalid="true"]')?.focus();
+                    }).catch(() => { });
+            };
+            form.addEventListener("submit", onSubmit);
+            cleanup.push(() => form.removeEventListener("submit", onSubmit));
+            form.append(...children());
+            return form;
+        }
+        if (node.component === "Text") {
+            const text = element("p", "veil-text");
+            text.textContent = node.text ?? "";
+            return text;
+        }
+        if (node.component === "Status") {
+            const status = element("p", "veil-status");
+            status.setAttribute("role", "status");
+            status.setAttribute("aria-live", "polite");
+            updates.push((state) => { status.textContent = state.message; status.dataset["status"] = state.status; });
+            return status;
+        }
+        if (node.component === "Field") {
+            const name = node.field;
+            const field = controller.field(name);
+            const wrapper = element("div", "veil-field");
+            wrapper.style.display = "grid";
+            wrapper.style.gap = "0.35rem";
+            const label = document.createElement("label");
+            const inputId = `${id}-control-${name}`;
+            const errorId = `${id}-error-${name}`;
+            label.htmlFor = inputId;
+            label.textContent = node.text ?? field.label;
+            if (field.required)
+                label.textContent += " *";
+            const input = field.type === "select" ? document.createElement("select") : field.type === "textarea" ? document.createElement("textarea") : document.createElement("input");
+            input.id = inputId;
+            input.name = name;
+            input.style.boxSizing = "border-box";
+            input.style.width = "100%";
+            input.style.minHeight = "2.75rem";
+            input.style.fontSize = "1rem";
+            input.setAttribute("aria-describedby", errorId);
+            if (field.required)
+                input.setAttribute("aria-required", "true");
+            if (input instanceof HTMLInputElement) {
+                input.type = field.type === "checkbox" ? "checkbox" : field.type === "number" || field.type === "currency" ? "number" : field.type === "date" ? "date" : field.type === "email" ? "email" : "text";
+                if (field.type === "number" || field.type === "currency")
+                    input.step = field.authoritativeType === "integer" ? "1" : "any";
+                if (field.minimum !== undefined)
+                    input.min = String(field.minimum);
+                if (field.maximum !== undefined)
+                    input.max = String(field.maximum);
+            }
+            if (input instanceof HTMLSelectElement) {
+                const empty = document.createElement("option");
+                empty.value = "";
+                empty.textContent = "Select…";
+                input.append(empty);
+                for (const option of field.options ?? []) {
+                    const choice = document.createElement("option");
+                    choice.value = String(option);
+                    choice.textContent = String(option);
+                    input.append(choice);
+                }
+            }
+            const current = controller.snapshot().values[name];
+            if (input instanceof HTMLInputElement && input.type === "checkbox")
+                input.checked = current === true;
+            else
+                input.value = current === undefined || current === null ? "" : String(current);
+            const update = () => {
+                if (!active)
+                    return;
+                let value = input.value;
+                if (input instanceof HTMLInputElement && input.type === "checkbox")
+                    value = input.checked;
+                else if (input.value !== "" && (field.authoritativeType === "number" || field.authoritativeType === "integer")) {
+                    const parsed = Number(input.value);
+                    value = Number.isFinite(parsed) ? parsed : input.value;
+                }
+                else if (input.value !== "" && field.options && field.authoritativeType === "boolean")
+                    value = input.value === "true";
+                controller.setField(name, value);
+            };
+            input.addEventListener("input", update);
+            input.addEventListener("change", update);
+            cleanup.push(() => { input.removeEventListener("input", update); input.removeEventListener("change", update); });
+            const error = element("small", "veil-error");
+            error.id = errorId;
+            updates.push((state) => {
+                const currentValue = state.values[name];
+                if (input instanceof HTMLInputElement && input.type === "checkbox")
+                    input.checked = currentValue === true;
+                else {
+                    const display = currentValue === undefined || currentValue === null ? "" : String(currentValue);
+                    const sameNumber = input instanceof HTMLInputElement && input.type === "number" && input.value !== "" && typeof currentValue === "number" && Number(input.value) === currentValue;
+                    if (!sameNumber && input.value !== display)
+                        input.value = display;
+                }
+                error.textContent = state.errors[name] ?? "";
+                input.setAttribute("aria-invalid", state.errors[name] ? "true" : "false");
+                input.disabled = state.status === "submitting";
+            });
+            wrapper.append(label, input, error);
+            return wrapper;
+        }
+        if (node.component === "Submit") {
+            const button = document.createElement("button");
+            button.type = "submit";
+            button.dataset["veilAction"] = node.action;
+            button.textContent = node.text ?? "Submit";
+            button.style.minHeight = "2.75rem";
+            button.style.fontSize = "1rem";
+            updates.push((state) => { button.disabled = state.status === "submitting"; });
+            return button;
+        }
+        const custom = Object.hasOwn(components, node.component) ? components[node.component] : undefined;
+        if (!custom)
+            throw new Error(`Unknown component: ${node.component}`);
+        const result = custom(node, { controller, renderChildren: children });
+        if (!(result instanceof HTMLElement))
+            throw new Error(`Component ${node.component} must return an HTMLElement`);
+        return result;
+    }
+    const screen = render(definition.screen);
+    screen.style.maxWidth = "36rem";
+    screen.style.width = "100%";
+    screen.style.boxSizing = "border-box";
+    const unsubscribe = controller.subscribe((state) => { if (active)
+        for (const update of updates)
+            update(state); });
+    mounted.get(target)?.();
+    target.replaceChildren(screen);
+    const dispose = () => {
+        if (!active)
+            return;
+        active = false;
+        unsubscribe();
+        for (const remove of cleanup)
+            remove();
+        if (screen.parentNode === target)
+            target.removeChild(screen);
+        if (mounted.get(target) === dispose)
+            mounted.delete(target);
+    };
+    mounted.set(target, dispose);
+    return dispose;
+}
+/** Own a controller and one DOM mount with a single teardown. Component factories remain trusted host code. */
+export function createMountedInterface(target, definition, options = {}) {
+    const components = options.components ?? {};
+    const controller = createInterfaceController(definition, {
+        components: Object.keys(components),
+        ...(options.allowedActions ? { allowedActions: options.allowedActions } : {}),
+        ...(options.onEvent ? { onEvent: options.onEvent } : {}),
+        ...(options.onError ? { onError: options.onError } : {}),
+    });
+    let unmount;
+    try {
+        unmount = mountInterface(target, controller, components, options.onError);
+    }
+    catch (error) {
+        controller.dispose();
+        throw error;
+    }
+    let disposed = false;
+    const disposeController = controller.dispose.bind(controller);
+    return Object.assign(controller, {
+        unmount,
+        dispose() { if (disposed)
+            return; disposed = true; unmount(); disposeController(); },
+    });
+}
+/** Mount a framework-neutral interface. The caller owns and disposes the controller separately. */
+export function mountInterface(target, controller, components = {}, onError) {
+    let active = true;
+    let root;
+    let unregister;
+    const reported = new WeakSet();
+    const report = (error) => {
+        if (error !== null && typeof error === "object") {
+            if (reported.has(error))
+                return;
+            reported.add(error);
+        }
+        try {
+            onError?.(error);
+        }
+        catch { /* Reporting cannot interrupt a transaction. */ }
+    };
+    const domId = `veil-interface-${++instance}`;
+    const make = (tag, className) => { const el = document.createElement(tag); el.className = className; return el; };
+    const display = (value) => value === undefined || value === null ? "" : typeof value === "object" ? JSON.stringify(value) : String(value);
+    const resolveText = (node, snapshot) => typeof node.text === "string" ? node.text : node.text ? display(resolveInterfaceBinding(snapshot, node.text)) : "";
+    const visible = (node, snapshot) => !node.visible || resolveInterfaceBinding(snapshot, node.visible.binding) === node.visible.equals;
+    function create(node, snapshot, candidate = false) {
+        const children = [];
+        let element;
+        let dispose = () => { };
+        let updateCustom;
+        let live = true;
+        const lifetime = new AbortController();
+        if (node.component === "Stack" || node.component === "Row")
+            element = make("div", `veil-interface-${node.component.toLowerCase()}`);
+        else if (node.component === "Text")
+            element = make("p", "veil-interface-text");
+        else if (node.component === "Heading")
+            element = make("h2", "veil-interface-heading");
+        else if (node.component === "Status") {
+            element = make("p", "veil-interface-status");
+            element.setAttribute("role", "status");
+            element.setAttribute("aria-live", "polite");
+        }
+        else if (node.component === "Button") {
+            const button = document.createElement("button");
+            button.type = "button";
+            button.className = "veil-interface-button";
+            const click = () => { if (active && live) {
+                try {
+                    controller.dispatch(node.action, node.key);
+                }
+                catch (error) {
+                    report(error);
+                }
+            } };
+            button.addEventListener("click", click);
+            dispose = () => button.removeEventListener("click", click);
+            element = button;
+        }
+        else if (node.component === "Input") {
+            const wrapper = make("div", "veil-interface-input");
+            const label = document.createElement("label");
+            const input = document.createElement("input");
+            input.id = `${domId}-${node.key}`;
+            label.htmlFor = input.id;
+            input.type = node.inputType ?? "text";
+            input.style.boxSizing = "border-box";
+            input.style.maxWidth = "100%";
+            input.style.minWidth = "0";
+            const change = () => {
+                if (!active || !live)
+                    return;
+                const value = input.type === "checkbox" ? input.checked : input.type === "number" && input.value !== "" ? Number(input.value) : input.value;
+                try {
+                    controller.setState(node.binding.path, value);
+                }
+                catch (error) {
+                    const accepted = resolveInterfaceBinding(controller.snapshot(), node.binding);
+                    if (input.type === "checkbox")
+                        input.checked = accepted === true;
+                    else
+                        input.value = display(accepted);
+                    report(error);
+                }
+            };
+            input.addEventListener("input", change);
+            input.addEventListener("change", change);
+            dispose = () => { input.removeEventListener("input", change); input.removeEventListener("change", change); };
+            wrapper.append(label, input);
+            element = wrapper;
+        }
+        else if (node.component === "Table") {
+            element = make("table", "veil-interface-table");
+            element.style.display = "block";
+            element.style.maxWidth = "100%";
+            element.style.overflowX = "auto";
+        }
+        else if (node.component === "List")
+            element = make("ul", "veil-interface-list");
+        else {
+            const custom = Object.hasOwn(components, node.component) ? components[node.component] : undefined;
+            if (!custom)
+                throw new Error(`Unknown component: ${node.component}`);
+            let created;
+            let renderedChildren = false;
+            try {
+                created = custom(node, { snapshot, signal: lifetime.signal, renderChildren: () => {
+                        if (renderedChildren)
+                            throw new Error("renderChildren may be called once");
+                        renderedChildren = true;
+                        for (const child of node.children ?? [])
+                            children.push(create(child, snapshot, candidate));
+                        return children.map((child) => child.element);
+                    } });
+            }
+            catch (error) {
+                lifetime.abort();
+                for (const child of children)
+                    destroy(child);
+                throw error;
+            }
+            if (!created || typeof created !== "object") {
+                lifetime.abort();
+                for (const child of children)
+                    destroy(child);
+                throw new Error(`Component ${node.component} must return an HTMLElement`);
+            }
+            const instance = created instanceof HTMLElement ? { element: created } : created;
+            element = instance.element;
+            updateCustom = instance.update;
+            dispose = () => instance.dispose?.();
+            if (!(element instanceof HTMLElement)) {
+                lifetime.abort();
+                for (const child of children)
+                    destroy(child);
+                throw new Error(`Component ${node.component} must return an HTMLElement`);
+            }
+        }
+        const result = { node, element, children, dispose: () => { live = false; lifetime.abort(); dispose(); }, updateCustom, visibleDisplay: element.style.display, live: true };
+        if (node.component === "Stack" || node.component === "Row") {
+            element.style.display = node.component === "Stack" ? "grid" : "flex";
+            element.style.gap = "0.75rem";
+            element.style.minWidth = "0";
+            if (node.component === "Stack")
+                element.style.gridTemplateColumns = "minmax(0, 1fr)";
+            if (node.component === "Row")
+                element.style.flexWrap = "wrap";
+            try {
+                for (const child of node.children ?? [])
+                    children.push(create(child, snapshot, candidate));
+            }
+            catch (error) {
+                for (const child of children)
+                    destroy(child);
+                throw error;
+            }
+            element.append(...children.map((child) => child.element));
+        }
+        result.visibleDisplay = element.style.display;
+        update(result, snapshot);
+        if (candidate && updateCustom) {
+            try {
+                updateCustom(node, snapshot);
+            }
+            catch (error) {
+                destroy(result);
+                throw error;
+            }
+        }
+        return result;
+    }
+    function update(rendered, snapshot) {
+        const { node, element } = rendered;
+        const isVisible = visible(node, snapshot);
+        element.hidden = !isVisible;
+        element.style.display = isVisible ? rendered.visibleDisplay : "none";
+        if (node.ariaLabel)
+            element.setAttribute("aria-label", node.ariaLabel);
+        else
+            element.removeAttribute("aria-label");
+        if (["Text", "Heading", "Status", "Button"].includes(node.component))
+            element.textContent = resolveText(node, snapshot);
+        if (node.component === "List") {
+            const items = resolveInterfaceBinding(snapshot, node.binding);
+            if (items !== undefined && (!Array.isArray(items) || items.length > 100))
+                throw new Error("List item limit exceeded");
+            const entries = (items ?? []).map((item) => { const li = document.createElement("li"); li.textContent = display(item); return li; });
+            element.replaceChildren(...entries);
+        }
+        if (node.component === "Input") {
+            const label = element.querySelector("label");
+            const input = element.querySelector("input");
+            label.textContent = node.label ?? "";
+            const value = resolveInterfaceBinding(snapshot, node.binding);
+            if (input.type === "checkbox")
+                input.checked = value === true;
+            else {
+                const shown = display(value);
+                const sameNumber = input.type === "number" && input.value !== "" && typeof value === "number" && Number(input.value) === value;
+                if (!sameNumber && input.value !== shown)
+                    input.value = shown;
+            }
+            if (node.ariaLabel)
+                input.setAttribute("aria-label", node.ariaLabel);
+            else
+                input.removeAttribute("aria-label");
+        }
+        if (node.component === "Table") {
+            const rows = resolveInterfaceBinding(snapshot, node.binding);
+            if (rows !== undefined && (!Array.isArray(rows) || rows.length > 100))
+                throw new Error("Table row limit exceeded");
+            const head = document.createElement("thead");
+            const header = document.createElement("tr");
+            for (const col of node.columns ?? []) {
+                const cell = document.createElement("th");
+                cell.scope = "col";
+                cell.textContent = col.label;
+                header.append(cell);
+            }
+            head.append(header);
+            const body = document.createElement("tbody");
+            for (const row of rows ?? []) {
+                if (!row || typeof row !== "object" || Array.isArray(row))
+                    throw new Error("Invalid table row");
+                const tr = document.createElement("tr");
+                for (const col of node.columns ?? []) {
+                    const cell = document.createElement("td");
+                    cell.textContent = display(Object.hasOwn(row, col.key) ? row[col.key] : undefined);
+                    tr.append(cell);
+                }
+                body.append(tr);
+            }
+            element.replaceChildren(head, body);
+        }
+    }
+    function destroy(rendered) {
+        if (!rendered.live)
+            return;
+        rendered.live = false;
+        try {
+            rendered.dispose();
+        }
+        catch (error) {
+            report(error);
+        }
+        for (const child of rendered.children)
+            destroy(child);
+    }
+    // Allocate every new subtree before changing the mounted tree. A failed factory leaves it intact.
+    function prepare(previous, node, snapshot, staged) {
+        const same = previous.node.key === node.key && previous.node.component === node.component &&
+            (node.component !== "Button" || previous.node.action === node.action) &&
+            (node.component !== "Input" || (previous.node.binding?.path === node.binding?.path && previous.node.inputType === node.inputType)) &&
+            ["Stack", "Row", "Text", "Heading", "Status", "Input", "Button", "Table", "List"].includes(node.component);
+        if (!same) {
+            const next = create(node, snapshot, true);
+            staged.push(next);
+            return () => { previous.element.replaceWith(next.element); destroy(previous); return next; };
+        }
+        const prior = node.component === "Stack" || node.component === "Row" ? new Map(previous.children.map((child) => [child.node.key, child])) : undefined;
+        const childPlans = (node.children ?? []).map((child) => {
+            const old = prior?.get(child.key);
+            if (old) {
+                prior.delete(child.key);
+                return prepare(old, child, snapshot, staged);
+            }
+            const next = create(child, snapshot, true);
+            staged.push(next);
+            return () => next;
+        });
+        return () => {
+            previous.node = node;
+            update(previous, snapshot);
+            if (node.component === "Stack" || node.component === "Row") {
+                const children = childPlans.map((plan) => plan());
+                previous.children = children;
+                for (let index = 0; index < children.length; index++) {
+                    const desired = children[index].element;
+                    if (previous.element.children[index] !== desired)
+                        previous.element.insertBefore(desired, previous.element.children[index] ?? null);
+                }
+                while (previous.element.children.length > children.length)
+                    previous.element.lastElementChild?.remove();
+                for (const removed of prior.values())
+                    destroy(removed);
+            }
+            return previous;
+        };
+    }
+    try {
+        const first = controller.snapshot();
+        root = create(first.definition.screen, first);
+        unregister = registerInterfaceRenderer(controller, (snapshot) => {
+            const staged = [];
+            try {
+                const commit = prepare(root, snapshot.definition.screen, snapshot, staged);
+                return { commit: () => {
+                        if (!active) {
+                            for (const node of staged)
+                                destroy(node);
+                            return;
+                        }
+                        const focused = root?.element.contains(document.activeElement) ? document.activeElement : undefined;
+                        const selection = focused instanceof HTMLInputElement || focused instanceof HTMLTextAreaElement ? { start: focused.selectionStart, end: focused.selectionEnd, direction: focused.selectionDirection } : undefined;
+                        root = commit();
+                        if (focused?.isConnected && document.activeElement !== focused) {
+                            focused.focus({ preventScroll: true });
+                            if (selection && selection.start !== null && selection.end !== null && (focused instanceof HTMLInputElement || focused instanceof HTMLTextAreaElement))
+                                focused.setSelectionRange(selection.start, selection.end, selection.direction ?? undefined);
+                        }
+                    }, discard: () => { for (const node of staged)
+                        destroy(node); } };
+            }
+            catch (error) {
+                for (const node of staged)
+                    destroy(node);
+                report(error);
+                throw error;
+            }
+        });
+        mounted.get(target)?.();
+        target.replaceChildren(root.element);
+    }
+    catch (error) {
+        unregister?.();
+        if (root)
+            destroy(root);
+        active = false;
+        throw error;
+    }
+    const dispose = () => {
+        if (!active)
+            return;
+        active = false;
+        unregister?.();
+        if (root) {
+            destroy(root);
+            if (root.element.parentNode === target)
+                target.removeChild(root.element);
+        }
+        if (mounted.get(target) === dispose)
+            mounted.delete(target);
+    };
+    mounted.set(target, dispose);
+    return dispose;
+}

package/dist/index.d.ts

@@ -16,3 +16,5 @@ export * from "./presentation-context.js";
 export * from "./presentation-composition.js";
 export * from "./execution-request.js";
 export * from "./format-semantic-value.js";
+export * from "./composition.js";
+export * from "./interface.js";

package/dist/index.js

@@ -16,3 +16,5 @@ export * from "./presentation-context.js";
 export * from "./presentation-composition.js";
 export * from "./execution-request.js";
 export * from "./format-semantic-value.js";
+export * from "./composition.js";
+export * from "./interface.js";

package/dist/input-schema.d.ts

@@ -1,7 +1,9 @@
-import type { CapabilityInputField } from "@veil-runtime/core";
 export type RichStringFormat = "date" | "date-time" | "multiline";
-export interface RichCapabilityInputField extends CapabilityInputField {
+/** The shared field shape is structural so composition needs no Core installation. */
+export interface RichCapabilityInputField {
     type: "string" | "number" | "integer" | "boolean" | "object" | "array";
+    required: boolean;
+    description: string;
     enum?: Array<string | number | boolean>;
     format?: RichStringFormat;
     semantic?: "currency";

package/dist/interface-transaction.d.ts

@@ -0,0 +1,9 @@
+/** Internal bridge between a neutral controller and any mounted renderers. */
+export interface PreparedInterfaceRender {
+    commit(): void;
+    discard(): void;
+}
+export type InterfaceRenderParticipant<T> = (candidate: T) => PreparedInterfaceRender;
+export declare function attachInterfaceRenderers<T>(controller: object, participants: Set<InterfaceRenderParticipant<T>>): void;
+export declare function detachInterfaceRenderers(controller: object): void;
+export declare function registerInterfaceRenderer<T>(controller: object, renderer: InterfaceRenderParticipant<T>): () => void;

package/dist/interface-transaction.js

@@ -0,0 +1,14 @@
+const renderers = new WeakMap();
+export function attachInterfaceRenderers(controller, participants) {
+    renderers.set(controller, participants);
+}
+export function detachInterfaceRenderers(controller) {
+    renderers.delete(controller);
+}
+export function registerInterfaceRenderer(controller, renderer) {
+    const participants = renderers.get(controller);
+    if (!participants)
+        throw new Error("Interface controller is disposed or unsupported");
+    participants.add(renderer);
+    return () => { participants.delete(renderer); };
+}