@veil-runtime/ui 0.1.0 → 0.4.0

package/dist/interface.d.ts

@@ -0,0 +1,261 @@
+export type InterfaceValue = string | number | boolean | null;
+export interface InterfaceBinding {
+    source: "data" | "state";
+    path: string;
+}
+export interface InterfaceCondition {
+    binding: InterfaceBinding;
+    equals: InterfaceValue;
+}
+export type InterfaceConditionExpression = InterfaceCondition | {
+    binding: InterfaceBinding;
+    operator: "ne" | "lt" | "lte" | "gt" | "gte";
+    value: InterfaceValue;
+} | {
+    all: InterfaceConditionExpression[];
+} | {
+    any: InterfaceConditionExpression[];
+} | {
+    not: InterfaceConditionExpression;
+};
+export interface InterfaceValidation {
+    required?: boolean;
+    minLength?: number;
+    maxLength?: number;
+    min?: number;
+    max?: number;
+}
+export interface InterfaceOption {
+    value: string;
+    label: string;
+}
+export interface InterfaceColumn {
+    key: string;
+    label: string;
+}
+export interface InterfaceNode {
+    key: string;
+    component: string;
+    children?: InterfaceNode[];
+    text?: string | InterfaceBinding;
+    binding?: InterfaceBinding;
+    visible?: InterfaceConditionExpression;
+    disabled?: InterfaceConditionExpression;
+    validation?: InterfaceValidation;
+    options?: InterfaceOption[];
+    validate?: boolean;
+    action?: string;
+    label?: string;
+    inputType?: "text" | "number" | "checkbox";
+    columns?: InterfaceColumn[];
+    ariaLabel?: string;
+}
+export interface InterfaceDefinition {
+    id: string;
+    screen: InterfaceNode;
+    actions?: string[];
+    data?: Record<string, unknown>;
+    state?: Record<string, unknown>;
+}
+/** Use `satisfies BuiltinInterfaceDefinition` for compile-time checks on JSON-only built-in screens. */
+type BuiltinBase = Pick<InterfaceNode, "key" | "visible" | "ariaLabel">;
+export type BuiltinInterfaceNode = (BuiltinBase & {
+    component: "Stack" | "Row";
+    children?: BuiltinInterfaceNode[];
+}) | (BuiltinBase & {
+    component: "Text" | "Status";
+    text?: string | InterfaceBinding;
+}) | (BuiltinBase & {
+    component: "Heading";
+    text: string | InterfaceBinding;
+}) | (BuiltinBase & {
+    component: "Input";
+    label: string;
+    binding: InterfaceBinding & {
+        source: "state";
+    };
+    inputType?: "text" | "number" | "checkbox";
+    validation?: InterfaceValidation;
+}) | (BuiltinBase & {
+    component: "Textarea";
+    label: string;
+    binding: InterfaceBinding & {
+        source: "state";
+    };
+    validation?: InterfaceValidation;
+}) | (BuiltinBase & {
+    component: "Select";
+    label: string;
+    binding: InterfaceBinding & {
+        source: "state";
+    };
+    options: InterfaceOption[];
+    validation?: InterfaceValidation;
+}) | (BuiltinBase & {
+    component: "Button";
+    text: string | InterfaceBinding;
+    action: string;
+    disabled?: InterfaceConditionExpression;
+    validate?: boolean;
+}) | (BuiltinBase & {
+    component: "Table";
+    binding: InterfaceBinding;
+    columns: InterfaceColumn[];
+}) | (BuiltinBase & {
+    component: "List";
+    binding: InterfaceBinding;
+});
+export type BuiltinInterfaceDefinition = Omit<InterfaceDefinition, "screen"> & {
+    screen: BuiltinInterfaceNode;
+};
+export interface InterfaceEvent {
+    action: string;
+    source: string;
+    state: Record<string, unknown>;
+    revision: number;
+}
+export interface InterfaceSnapshot {
+    definition: InterfaceDefinition;
+    data: Record<string, unknown>;
+    state: Record<string, unknown>;
+    revision: number;
+}
+export interface InterfaceController {
+    snapshot(): InterfaceSnapshot;
+    updateData(data: Record<string, unknown>, expectedRevision?: number): boolean;
+    updateDefinition(definition: InterfaceDefinition, expectedRevision?: number): boolean;
+    setState(path: string, value: InterfaceValue): void;
+    dispatch(action: string, source: string): void;
+    subscribe(listener: (snapshot: InterfaceSnapshot) => void): () => void;
+    dispose(): void;
+}
+/** JSON-safe description of the built-in vocabulary. Host extensions are trusted code and are never advertised here. */
+export declare function getInterfaceCapabilities(): {
+    version: number;
+    components: {
+        readonly Stack: {
+            readonly properties: readonly ["key", "component", "visible", "ariaLabel", "children"];
+            readonly required: readonly [];
+            readonly children: true;
+            readonly event: null;
+        };
+        readonly Row: {
+            readonly properties: readonly ["key", "component", "visible", "ariaLabel", "children"];
+            readonly required: readonly [];
+            readonly children: true;
+            readonly event: null;
+        };
+        readonly Text: {
+            readonly properties: readonly ["key", "component", "visible", "ariaLabel", "text"];
+            readonly required: readonly [];
+            readonly children: false;
+            readonly event: null;
+        };
+        readonly Heading: {
+            readonly properties: readonly ["key", "component", "visible", "ariaLabel", "text"];
+            readonly required: readonly ["text"];
+            readonly children: false;
+            readonly event: null;
+        };
+        readonly Status: {
+            readonly properties: readonly ["key", "component", "visible", "ariaLabel", "text"];
+            readonly required: readonly [];
+            readonly children: false;
+            readonly event: null;
+        };
+        readonly Input: {
+            readonly properties: readonly ["key", "component", "visible", "ariaLabel", "label", "binding", "inputType", "validation"];
+            readonly required: readonly ["label", "binding"];
+            readonly children: false;
+            readonly event: "state change";
+        };
+        readonly Textarea: {
+            readonly properties: readonly ["key", "component", "visible", "ariaLabel", "label", "binding", "validation"];
+            readonly required: readonly ["label", "binding"];
+            readonly children: false;
+            readonly event: "state change";
+        };
+        readonly Select: {
+            readonly properties: readonly ["key", "component", "visible", "ariaLabel", "label", "binding", "validation", "options"];
+            readonly required: readonly ["label", "binding", "options"];
+            readonly children: false;
+            readonly event: "state change";
+        };
+        readonly Button: {
+            readonly properties: readonly ["key", "component", "visible", "ariaLabel", "text", "action", "disabled", "validate"];
+            readonly required: readonly ["text", "action"];
+            readonly children: false;
+            readonly event: "action";
+        };
+        readonly Table: {
+            readonly properties: readonly ["key", "component", "visible", "ariaLabel", "binding", "columns"];
+            readonly required: readonly ["binding", "columns"];
+            readonly children: false;
+            readonly event: null;
+        };
+        readonly List: {
+            readonly properties: readonly ["key", "component", "visible", "ariaLabel", "binding"];
+            readonly required: readonly ["binding"];
+            readonly children: false;
+            readonly event: null;
+        };
+    };
+    bindings: {
+        sources: string[];
+        path: string;
+        missing: string;
+        visibility: string;
+    };
+    propertyTypes: {
+        key: string;
+        component: string;
+        children: string;
+        text: string;
+        binding: string;
+        visible: string;
+        disabled: string;
+        validation: string;
+        validate: string;
+        options: string;
+        action: string;
+        label: string;
+        inputType: string[];
+        columns: string;
+        ariaLabel: string;
+    };
+    events: {
+        action: {
+            fields: string[];
+            declaration: string;
+        };
+        state: {
+            type: string;
+            source: string;
+        };
+    };
+    limits: {
+        treeDepth: number;
+        nodes: number;
+        textLength: number;
+        tableRows: number;
+        tableColumns: number;
+        listItems: number;
+        transportBytes: number;
+    };
+};
+export declare function defineInterface<const T extends InterfaceDefinition>(definition: T): T;
+/** Validate untrusted structured data before creating a controller or mounting it. */
+export declare function validateInterfaceDefinition(value: unknown, components?: readonly string[]): asserts value is InterfaceDefinition;
+export declare function createInterfaceController(definition: InterfaceDefinition, options?: {
+    components?: readonly string[];
+    allowedActions?: readonly string[];
+    onEvent?: (event: InterfaceEvent) => void | Promise<void>;
+    onError?: (error: unknown) => void;
+}): InterfaceController;
+export declare function resolveInterfaceBinding(snapshot: InterfaceSnapshot, bindingValue: InterfaceBinding): unknown;
+/** Evaluate a validated condition without coercion or side effects. Missing numeric values never match. */
+export declare function evaluateInterfaceCondition(condition: InterfaceConditionExpression, snapshot: Pick<InterfaceSnapshot, "data" | "state">): boolean;
+export declare function isInterfaceField(node: Pick<InterfaceNode, "component">): boolean;
+/** Errors are recomputed from accepted state; hidden fields are excluded, including hidden ancestors. */
+export declare function getInterfaceValidation(snapshot: Pick<InterfaceSnapshot, "definition" | "data" | "state">): Record<string, string>;
+export {};