@magicvr/schema-ui-protocol 0.2.1 → 0.2.3

package/protocol/conformance/request-lifecycle.js

@@ -0,0 +1,57 @@
+/**
+ * request-lifecycle fixture adapter (latest-wins / hide-drop).
+ */
+export function runRequestLifecycle(initialState, events) {
+    let generation = 0;
+    let active = true;
+    let state = initialState;
+    let mounted = true;
+    /** Generations that were cancelled by hide (not reactivated by show). */
+    const cancelled = new Set();
+    const committed = [];
+    for (const event of events) {
+        switch (event.type) {
+            case "start": {
+                if (!mounted) {
+                    break;
+                }
+                generation += 1;
+                active = true;
+                break;
+            }
+            case "hide": {
+                cancelled.add(generation);
+                active = false;
+                break;
+            }
+            case "show": {
+                // Show does not reactivate a hidden in-flight generation.
+                active = true;
+                break;
+            }
+            case "unmount": {
+                mounted = false;
+                active = false;
+                break;
+            }
+            case "response": {
+                if (!mounted) {
+                    break;
+                }
+                if (cancelled.has(event.generation)) {
+                    break;
+                }
+                if (event.generation !== generation) {
+                    // Older generation ignored when a newer start exists.
+                    break;
+                }
+                state = event.state;
+                committed.push({ generation: event.generation, state: event.state });
+                break;
+            }
+            default:
+                break;
+        }
+    }
+    return { generation, active, state, committed };
+}

package/protocol/conformance/response-mapping.js

@@ -0,0 +1,170 @@
+/**
+ * response-mapping fixture adapter (schema-ui-docs v2.7.0 / ADR-0005).
+ */
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Own-property path walk; prototype properties do not count as present. */
+function getPath(root, path) {
+    if (path === "") {
+        return { found: true, value: root };
+    }
+    const parts = path.split(".");
+    let current = root;
+    for (const part of parts) {
+        if (!isRecord(current) || !Object.prototype.hasOwnProperty.call(current, part)) {
+            return { found: false, value: undefined };
+        }
+        current = current[part];
+    }
+    return { found: true, value: current };
+}
+function mappingIsEmptyObject(mapping) {
+    return isRecord(mapping) && Object.keys(mapping).length === 0;
+}
+function supportsMapping(component) {
+    return (component === "table" ||
+        component === "chart" ||
+        component === "formRecord" ||
+        component === "recordView");
+}
+function wireOk(value, wire) {
+    if (wire === undefined || value === null) {
+        return true;
+    }
+    switch (wire) {
+        case "string":
+            return typeof value === "string";
+        case "boolean":
+            return typeof value === "boolean";
+        case "array":
+            return Array.isArray(value);
+        case "number":
+            return typeof value === "number" && Number.isFinite(value);
+        default:
+            return true;
+    }
+}
+export function mapResponse(input) {
+    const component = input.component;
+    // Explicit null mapping invalid for any component that receives localMapping.
+    if (Object.prototype.hasOwnProperty.call(input, "localMapping") && input.localMapping === null) {
+        return { ok: false, code: "INVALID_RESPONSE_MAPPING", path: "localMapping" };
+    }
+    if (!supportsMapping(component)) {
+        if (Object.prototype.hasOwnProperty.call(input, "localMapping") ||
+            Object.prototype.hasOwnProperty.call(input, "datasourceMapping")) {
+            // text/statCard reject mapping support (path reported as localMapping per fixtures).
+            if (input.localMapping === null) {
+                return { ok: false, code: "INVALID_RESPONSE_MAPPING", path: "localMapping" };
+            }
+            return { ok: false, code: "RESPONSE_MAPPING_NOT_SUPPORTED", path: "localMapping" };
+        }
+    }
+    if (component === "formRecord" || component === "recordView") {
+        const mapping = input.responseMapping;
+        if (!isRecord(mapping) || mappingIsEmptyObject(mapping)) {
+            return { ok: false, code: "INVALID_RESPONSE_MAPPING", path: "responseMapping" };
+        }
+        const response = input.response;
+        const fieldWireTypes = input.fieldWireTypes ?? {};
+        const values = {};
+        const skipped = {};
+        for (const [target, path] of Object.entries(mapping)) {
+            if (typeof path !== "string") {
+                return { ok: false, code: "INVALID_RESPONSE_MAPPING", path: "responseMapping" };
+            }
+            const resolved = getPath(response, path);
+            if (!resolved.found) {
+                values[target] = null;
+                continue;
+            }
+            const wire = fieldWireTypes[target];
+            if (!wireOk(resolved.value, wire)) {
+                skipped[target] = "FIELD_WIRE_TYPE_MISMATCH";
+                continue;
+            }
+            values[target] = resolved.value;
+        }
+        if (Object.keys(skipped).length > 0) {
+            return { ok: true, values, skipped };
+        }
+        return { ok: true, values };
+    }
+    if (component === "chart") {
+        const response = input.response;
+        if (Array.isArray(response)) {
+            return { ok: true, data: { list: response } };
+        }
+        // fall through to mapping if present
+    }
+    // table (and chart with mapping)
+    let mapping;
+    const hasLocal = Object.prototype.hasOwnProperty.call(input, "localMapping");
+    const hasDs = Object.prototype.hasOwnProperty.call(input, "datasourceMapping");
+    if (hasLocal) {
+        if (!isRecord(input.localMapping)) {
+            return { ok: false, code: "INVALID_RESPONSE_MAPPING", path: "localMapping" };
+        }
+        if (mappingIsEmptyObject(input.localMapping)) {
+            return { ok: false, code: "INVALID_RESPONSE_MAPPING", path: "localMapping" };
+        }
+        mapping = input.localMapping;
+    }
+    else if (hasDs) {
+        mapping = input.datasourceMapping;
+    }
+    const response = input.response;
+    const paginationMode = input.paginationMode;
+    if (!mapping) {
+        // Default table mapping
+        if (component === "table") {
+            if (!isRecord(response)) {
+                return { ok: false, code: "INVALID_RESPONSE_MAPPING", path: "response" };
+            }
+            const list = response.list;
+            if (!Array.isArray(list)) {
+                return { ok: false, code: "RESPONSE_MAPPING_PATH_MISSING", path: "list" };
+            }
+            if (paginationMode === "server") {
+                if (typeof response.total !== "number") {
+                    return { ok: false, code: "RESPONSE_MAPPING_TYPE_MISMATCH", path: "total" };
+                }
+                return { ok: true, data: { list, total: response.total } };
+            }
+            return { ok: true, data: { list } };
+        }
+        if (component === "chart" && Array.isArray(response)) {
+            return { ok: true, data: { list: response } };
+        }
+    }
+    const listPath = mapping?.list;
+    if (typeof listPath !== "string") {
+        return { ok: false, code: "INVALID_RESPONSE_MAPPING", path: "localMapping" };
+    }
+    const listResolved = getPath(response, listPath);
+    if (!listResolved.found) {
+        return { ok: false, code: "RESPONSE_MAPPING_PATH_MISSING", path: listPath };
+    }
+    if (!Array.isArray(listResolved.value)) {
+        return { ok: false, code: "RESPONSE_MAPPING_TYPE_MISMATCH", path: listPath };
+    }
+    if (paginationMode === "server") {
+        const totalPath = mapping?.total;
+        if (typeof totalPath !== "string") {
+            return { ok: false, code: "INVALID_RESPONSE_MAPPING", path: "localMapping" };
+        }
+        const totalResolved = getPath(response, totalPath);
+        if (!totalResolved.found) {
+            return { ok: false, code: "RESPONSE_MAPPING_PATH_MISSING", path: totalPath };
+        }
+        if (typeof totalResolved.value !== "number") {
+            return { ok: false, code: "RESPONSE_MAPPING_TYPE_MISMATCH", path: totalPath };
+        }
+        return {
+            ok: true,
+            data: { list: listResolved.value, total: totalResolved.value },
+        };
+    }
+    return { ok: true, data: { list: listResolved.value } };
+}

package/protocol/conformance/runtime-defaults.js

@@ -0,0 +1,75 @@
+/**
+ * runtime-defaults fixture adapter (schema-ui-docs v2.7.0).
+ */
+export function applyRuntimeDefaults(input) {
+    const kind = input.kind;
+    if (kind === "requestConfig") {
+        const requiresNetwork = input.requiresNetwork === true;
+        const baseURL = input.baseURL;
+        if (requiresNetwork && (baseURL === undefined || baseURL === null || baseURL === "")) {
+            return { ok: false, code: "MISSING_BASE_URL" };
+        }
+        return { ok: true };
+    }
+    if (kind === "defaults") {
+        const target = input.target;
+        const value = (input.value ?? {});
+        if (target === "dataRef") {
+            return {
+                ok: true,
+                value: {
+                    ...value,
+                    method: value.method ?? "GET",
+                },
+            };
+        }
+        if (target === "uploadAction") {
+            return {
+                ok: true,
+                value: {
+                    ...value,
+                    method: value.method ?? "POST",
+                    retryPolicy: value.retryPolicy ?? "never",
+                    fieldName: value.fieldName ?? "file",
+                    multiple: value.multiple ?? false,
+                },
+            };
+        }
+        return { ok: false, code: "INVALID_DEFAULTS_TARGET" };
+    }
+    if (kind === "component") {
+        const type = input.type;
+        const installed = new Set(input.installedTypes ?? []);
+        if (!installed.has(type)) {
+            return { ok: false, code: "UNKNOWN_COMPONENT_TYPE" };
+        }
+        const requiredProps = input.requiredProps ?? [];
+        const props = input.props ?? {};
+        for (const prop of requiredProps) {
+            if (!Object.prototype.hasOwnProperty.call(props, prop)) {
+                return { ok: false, code: "INVALID_COMPONENT", path: `props.${prop}` };
+            }
+        }
+        return { ok: true };
+    }
+    if (kind === "formFieldInit") {
+        const fields = input.fields ?? [];
+        const recordValues = input.recordValues ?? {};
+        const reactionWrites = input.reactionWrites ?? [];
+        const values = {};
+        for (const field of fields) {
+            const name = field.field;
+            if (field.defaultValue !== undefined) {
+                values[name] = field.defaultValue;
+            }
+        }
+        for (const [key, value] of Object.entries(recordValues)) {
+            values[key] = value;
+        }
+        for (const write of reactionWrites) {
+            values[write.field] = write.value;
+        }
+        return { ok: true, values };
+    }
+    return { ok: false, code: "UNKNOWN_KIND" };
+}

package/protocol/conformance/runtime-schema-validate.js

@@ -0,0 +1,82 @@
+/**
+ * Browser-safe structural validation for vendored page/node/action/reaction
+ * schemas. Mirrors `protocol/conformance/schema-validate.ts` but imports the
+ * pinned `docs/schemas/*.json` at build time (Vite `@schemas` alias) instead of
+ * reading them from disk, so the runtime loader can enforce D-VAL in the
+ * browser. The schema set is identical, so runtime and test-time validators
+ * stay aligned and neither redefines upstream node/page semantics.
+ */
+import Ajv from "ajv";
+import actionSchema from "@schemas/action.schema.json";
+import nodeSchema from "@schemas/node.schema.json";
+import pageSchema from "@schemas/page.schema.json";
+import reactionSchema from "@schemas/reaction.schema.json";
+let cached = null;
+function buildValidators() {
+    const ajv = new Ajv({
+        allErrors: true,
+        strict: false,
+        validateSchema: false,
+    });
+    // Register by both $id and the relative filenames used in $ref so cross-schema
+    // references (page -> node -> reaction) resolve exactly like schema-validate.ts.
+    // GOAL-018 local extension: custom nodes carry a top-level component key.
+    // The extension is applied at validation time so the upstream-pinned
+    // node.schema.json artifact (I-PROTO-004, schema-ui-docs@2.9.0) stays
+    // byte-identical — this is NOT an upstream protocol change.
+    // The upstream node.schema.json types do not know the local extension;
+    // cast through unknown to keep the spread clean (local-only addition).
+    const extendedNodeSchema = {
+        ...nodeSchema,
+        properties: {
+            ...(nodeSchema.properties ?? {}),
+            component: {
+                type: "string",
+                description: "GOAL-018 local extension: custom node component key (renderer custom-components registry)",
+            },
+        },
+    };
+    ajv.addSchema(extendedNodeSchema);
+    ajv.addSchema(extendedNodeSchema, "node.schema.json");
+    ajv.addSchema(pageSchema);
+    ajv.addSchema(pageSchema, "page.schema.json");
+    ajv.addSchema(actionSchema);
+    ajv.addSchema(actionSchema, "action.schema.json");
+    ajv.addSchema(reactionSchema);
+    ajv.addSchema(reactionSchema, "reaction.schema.json");
+    return {
+        node: ajv.getSchema(nodeSchema.$id) ?? ajv.compile(nodeSchema),
+        page: ajv.getSchema(pageSchema.$id) ?? ajv.compile(pageSchema),
+        action: ajv.getSchema(actionSchema.$id) ?? ajv.compile(actionSchema),
+        reaction: ajv.getSchema(reactionSchema.$id) ?? ajv.compile(reactionSchema),
+    };
+}
+function getValidators() {
+    if (!cached) {
+        cached = buildValidators();
+    }
+    return cached;
+}
+function mapErrors(errors) {
+    if (!errors) {
+        return [];
+    }
+    return errors.map((error) => ({
+        path: error.instancePath || "/",
+        message: error.message ?? "invalid",
+        keyword: error.keyword,
+    }));
+}
+/**
+ * Structural validation of a fetched page document against the pinned page/node
+ * schemas. `ok: false` means the document must fail closed and never reach the
+ * renderer.
+ */
+export function validatePageDocument(document) {
+    const validate = getValidators().page;
+    const ok = validate(document);
+    return {
+        ok,
+        errors: ok ? [] : mapErrors(validate.errors),
+    };
+}

package/protocol/conformance/schema-validate.js

@@ -0,0 +1,119 @@
+/**
+ * Structural validation entry for vendored node/page/action/reaction schemas.
+ * Uses Ajv draft-07 against pinned schema-ui-docs@2.7.0 artifacts in docs/schemas/.
+ */
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import Ajv from "ajv";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const SCHEMAS_DIR = join(__dirname, "../../../../../docs/schemas");
+function loadSchema(name) {
+    const bytes = readFileSync(join(SCHEMAS_DIR, name), "utf8");
+    return JSON.parse(bytes);
+}
+let cached = null;
+function buildValidators() {
+    const ajv = new Ajv({
+        allErrors: true,
+        strict: false,
+        validateSchema: false,
+    });
+    const node = loadSchema("node.schema.json");
+    const page = loadSchema("page.schema.json");
+    const action = loadSchema("action.schema.json");
+    const reaction = loadSchema("reaction.schema.json");
+    // Register by both $id and relative filenames used in $ref.
+    ajv.addSchema(node);
+    ajv.addSchema(node, "node.schema.json");
+    ajv.addSchema(page);
+    ajv.addSchema(page, "page.schema.json");
+    ajv.addSchema(action);
+    ajv.addSchema(action, "action.schema.json");
+    ajv.addSchema(reaction);
+    ajv.addSchema(reaction, "reaction.schema.json");
+    return {
+        node: ajv.getSchema(node.$id) ?? ajv.compile(node),
+        page: ajv.getSchema(page.$id) ?? ajv.compile(page),
+        action: ajv.getSchema(action.$id) ?? ajv.compile(action),
+        reaction: ajv.getSchema(reaction.$id) ?? ajv.compile(reaction),
+    };
+}
+function getValidators() {
+    if (!cached) {
+        cached = { validators: buildValidators() };
+    }
+    return cached.validators;
+}
+function mapErrors(errors) {
+    if (!errors) {
+        return [];
+    }
+    return errors.map((error) => ({
+        path: error.instancePath || "/",
+        message: error.message ?? "invalid",
+        keyword: error.keyword,
+    }));
+}
+export function validateAgainstSchema(kind, document) {
+    const validate = getValidators()[kind];
+    const ok = validate(document);
+    return {
+        ok,
+        errors: ok ? [] : mapErrors(validate.errors),
+    };
+}
+/** Minimal valid page document using §5 whitelist types (for structural smoke). */
+export function sampleWhitelistedPage() {
+    return {
+        meta: {
+            pageId: "sample-form",
+            title: "Sample Form",
+            protocolVersion: "2.7",
+            requiredCapabilities: ["form.controls.extended", "form.controls.advanced"],
+        },
+        body: {
+            type: "form",
+            props: {
+                fields: [
+                    { type: "input", field: "name", label: "Name" },
+                    { type: "textarea", field: "notes", label: "Notes" },
+                ],
+            },
+            children: [
+                {
+                    type: "section",
+                    props: { title: "Details" },
+                    children: [
+                        { type: "text", props: { content: "Hello" } },
+                        {
+                            type: "table",
+                            props: {
+                                columns: [{ field: "id", label: "ID" }],
+                            },
+                        },
+                        {
+                            type: "actionButton",
+                            props: { label: "Save" },
+                        },
+                        {
+                            type: "recordView",
+                            props: { title: "Record" },
+                        },
+                    ],
+                },
+                {
+                    type: "grid",
+                    children: [{ type: "text", props: { content: "Cell" } }],
+                },
+                {
+                    type: "tabs",
+                    props: {
+                        items: [{ key: "a", label: "A" }],
+                    },
+                    children: [{ type: "text", props: { content: "Tab A" } }],
+                },
+            ],
+        },
+    };
+}

package/protocol/conformance/search-table.js

@@ -0,0 +1,107 @@
+/**
+ * search-table fixture adapter — four-layer query merge + selection events.
+ */
+import { serializeQuery } from "./query-serialize.js";
+function isScalarKey(value) {
+    return (typeof value === "string" ||
+        typeof value === "number" ||
+        typeof value === "boolean");
+}
+function dedupeKeys(keys) {
+    const seen = new Set();
+    const out = [];
+    for (const key of keys) {
+        if (!isScalarKey(key)) {
+            continue;
+        }
+        const token = `${typeof key}:${String(key)}`;
+        if (seen.has(token)) {
+            continue;
+        }
+        seen.add(token);
+        out.push(key);
+    }
+    return out;
+}
+function buildUrl(baseUrl, staticParams, state) {
+    const sources = [];
+    const staticPairs = Object.entries(staticParams);
+    if (staticPairs.length > 0) {
+        sources.push(staticPairs);
+    }
+    const statePairs = [];
+    for (const [key, value] of Object.entries(state.filters)) {
+        statePairs.push([key, value]);
+    }
+    statePairs.push(["page", state.page]);
+    statePairs.push(["pageSize", state.pageSize]);
+    if (state.sort !== null && state.sort !== undefined) {
+        statePairs.push(["sort", state.sort]);
+    }
+    sources.push(statePairs);
+    const result = serializeQuery(baseUrl, sources);
+    if (!result.ok) {
+        throw new Error(result.code);
+    }
+    return result.url;
+}
+export function runSearchTable(input) {
+    const baseUrl = input.baseUrl;
+    const staticParams = input.staticParams ?? {};
+    let state = {
+        filters: { ...(input.state?.filters ?? {}) },
+        page: input.state?.page ?? 1,
+        pageSize: input.state?.pageSize ?? 20,
+        sort: input.state?.sort ?? null,
+    };
+    let selection = input.selection
+        ? {
+            keys: [...(input.selection.keys ?? [])],
+            count: input.selection.count ?? 0,
+        }
+        : undefined;
+    const event = input.event;
+    const selectionEvent = input.selectionEvent;
+    if (event) {
+        switch (event.type) {
+            case "submitSearch": {
+                state = {
+                    ...state,
+                    filters: { ...(event.filters ?? {}) },
+                    page: 1,
+                };
+                if (selection) {
+                    selection = { keys: [], count: 0 };
+                }
+                break;
+            }
+            case "clearSearch": {
+                state = { ...state, filters: {}, page: 1 };
+                break;
+            }
+            case "changePage": {
+                state = { ...state, page: event.page };
+                if (selection) {
+                    selection = { keys: [], count: 0 };
+                }
+                break;
+            }
+            case "changeSort": {
+                state = { ...state, sort: event.sort, page: 1 };
+                break;
+            }
+            default:
+                break;
+        }
+    }
+    if (selectionEvent?.type === "setKeys") {
+        const keys = dedupeKeys(selectionEvent.keys ?? []);
+        selection = { keys, count: keys.length };
+    }
+    const url = buildUrl(baseUrl, staticParams, state);
+    const result = { state, url };
+    if (selection !== undefined || input.selection !== undefined || selectionEvent) {
+        result.selection = selection ?? { keys: [], count: 0 };
+    }
+    return result;
+}