@magicvr/schema-ui-protocol 0.2.1 → 0.2.3

package/protocol/conformance/static-data.js

@@ -0,0 +1,87 @@
+/**
+ * static-data fixture adapter (schema-ui-docs v2.7.0).
+ */
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function resolveRef(ref, datasources) {
+    if (!datasources || !Object.prototype.hasOwnProperty.call(datasources, ref)) {
+        return { ok: false, code: "STATIC_DATA_REF_INVALID" };
+    }
+    const ds = datasources[ref];
+    if (!isRecord(ds) || ds.source !== "static") {
+        return { ok: false, code: "STATIC_DATA_REF_INVALID" };
+    }
+    return { ok: true, value: ds.value };
+}
+function shapeOk(component, value, valueField) {
+    switch (component) {
+        case "table":
+        case "chart":
+            return Array.isArray(value);
+        case "text":
+            return (value === null ||
+                typeof value === "string" ||
+                typeof value === "number" ||
+                typeof value === "boolean");
+        case "statCard":
+            if (valueField !== undefined) {
+                // Already extracted field; null rejected.
+                return value !== null && value !== undefined && !Array.isArray(value) && typeof value !== "object";
+            }
+            // Bare static value for statCard: object ok if we will read field; null rejected.
+            if (value === null) {
+                return false;
+            }
+            return true;
+        default:
+            return true;
+    }
+}
+export function resolveStaticData(input) {
+    const { component, data, datasources, props } = input;
+    if (data.responseMapping !== undefined) {
+        return { ok: false, code: "STATIC_RESPONSE_MAPPING_NOT_ALLOWED" };
+    }
+    let value;
+    if (data.source === "static") {
+        value = data.value;
+    }
+    else if (data.source === "ref") {
+        if (typeof data.ref !== "string") {
+            return { ok: false, code: "STATIC_DATA_REF_INVALID" };
+        }
+        const resolved = resolveRef(data.ref, datasources);
+        if (!resolved.ok) {
+            return resolved;
+        }
+        value = resolved.value;
+        if (component === "statCard" && props?.valueField) {
+            if (!isRecord(value) || !Object.prototype.hasOwnProperty.call(value, props.valueField)) {
+                return { ok: false, code: "STATIC_DATA_SHAPE_MISMATCH" };
+            }
+            value = value[props.valueField];
+            if (!shapeOk(component, value, props.valueField)) {
+                return { ok: false, code: "STATIC_DATA_SHAPE_MISMATCH" };
+            }
+            return { ok: true, value, network: false };
+        }
+    }
+    else {
+        return { ok: false, code: "STATIC_DATA_SHAPE_MISMATCH" };
+    }
+    if (!shapeOk(component, value, props?.valueField)) {
+        return { ok: false, code: "STATIC_DATA_SHAPE_MISMATCH" };
+    }
+    // text rejects arrays
+    if (component === "text" && Array.isArray(value)) {
+        return { ok: false, code: "STATIC_DATA_SHAPE_MISMATCH" };
+    }
+    if (component === "statCard" && value === null) {
+        return { ok: false, code: "STATIC_DATA_SHAPE_MISMATCH" };
+    }
+    if (component === "table" && !Array.isArray(value)) {
+        return { ok: false, code: "STATIC_DATA_SHAPE_MISMATCH" };
+    }
+    return { ok: true, value, network: false };
+}

package/protocol/conformance/table-sort.js

@@ -0,0 +1,217 @@
+/**
+ * table-sort fixture adapter (ADR-0027 three-state sort + L2 validate).
+ */
+import { serializeQuery } from "./query-serialize.js";
+function parseVersion(version) {
+    const m = /^(\d+)\.(\d+)$/.exec(version);
+    if (!m) {
+        return null;
+    }
+    return [Number(m[1]), Number(m[2])];
+}
+function versionGte(version, min) {
+    const a = parseVersion(version);
+    const b = parseVersion(min);
+    if (!a || !b) {
+        return false;
+    }
+    if (a[0] !== b[0]) {
+        return a[0] > b[0];
+    }
+    return a[1] >= b[1];
+}
+function sortKeyOf(column) {
+    return column.sortField ?? column.field;
+}
+function knownSortKeys(table) {
+    const keys = new Set();
+    for (const column of table.columns) {
+        if (column.sortable) {
+            keys.add(sortKeyOf(column));
+        }
+    }
+    return keys;
+}
+function buildUrl(baseUrl, state) {
+    const pairs = [];
+    for (const [key, value] of Object.entries(state.filters)) {
+        pairs.push([key, value]);
+    }
+    pairs.push(["page", state.page]);
+    pairs.push(["pageSize", state.pageSize]);
+    if (state.sort) {
+        pairs.push(["sort", state.sort]);
+    }
+    const sources = [pairs];
+    const result = serializeQuery(baseUrl, sources);
+    if (!result.ok) {
+        throw new Error(result.code);
+    }
+    return result.url;
+}
+function validateSortTable(meta, table) {
+    const version = meta.protocolVersion ?? "0.0";
+    const caps = meta.requiredCapabilities ?? [];
+    const usesSort = table.columns.some((c) => c.sortable) || table.defaultSort !== undefined;
+    if (!usesSort) {
+        return null;
+    }
+    if (!versionGte(version, "2.5")) {
+        return {
+            ok: false,
+            code: "PROTOCOL_VERSION_TOO_LOW",
+            path: "meta.protocolVersion",
+            errors: [{ code: "PROTOCOL_VERSION_TOO_LOW", path: "meta.protocolVersion" }],
+        };
+    }
+    if (!caps.includes("table.sort")) {
+        return {
+            ok: false,
+            code: "CAPABILITY_REQUIRED",
+            path: "meta.requiredCapabilities",
+            errors: [{ code: "CAPABILITY_REQUIRED", path: "meta.requiredCapabilities" }],
+        };
+    }
+    const seen = new Set();
+    for (let i = 0; i < table.columns.length; i++) {
+        const column = table.columns[i];
+        if (!column.sortable) {
+            continue;
+        }
+        const key = sortKeyOf(column);
+        if (seen.has(key)) {
+            return {
+                ok: false,
+                code: "SORT_KEY_DUPLICATE",
+                path: `columns[${i}]`,
+                errors: [{ code: "SORT_KEY_DUPLICATE", path: `columns[${i}]` }],
+            };
+        }
+        seen.add(key);
+    }
+    return null;
+}
+export function runTableSort(input) {
+    const meta = input.meta ?? {};
+    const table = input.table;
+    const baseUrl = input.baseUrl ?? "/orders";
+    if (input.operation === "validate") {
+        const err = validateSortTable(meta, table);
+        if (err) {
+            return err;
+        }
+        return { ok: true };
+    }
+    // v2.4 compat: sort interaction disabled
+    const protocolSortInteraction = versionGte(meta.protocolVersion ?? "0.0", "2.5");
+    let state = input.state
+        ? {
+            filters: { ...(input.state.filters ?? {}) },
+            page: input.state.page ?? 1,
+            pageSize: input.state.pageSize ?? table.pagination?.pageSize ?? 20,
+            sort: input.state.sort ?? null,
+        }
+        : {
+            filters: {},
+            page: 1,
+            pageSize: table.pagination?.pageSize ?? 20,
+            sort: null,
+        };
+    let selection = input.selection
+        ? {
+            keys: [...(input.selection.keys ?? [])],
+            count: input.selection.count ?? 0,
+        }
+        : undefined;
+    const event = input.event;
+    const keys = knownSortKeys(table);
+    // Unknown current sort key blocks request
+    if (state.sort) {
+        const field = state.sort.split(":")[0] ?? "";
+        if (!keys.has(field)) {
+            return {
+                ok: false,
+                code: "TABLE_SORT_FIELD_UNKNOWN",
+                requestEmitted: false,
+                state,
+            };
+        }
+    }
+    let requestEmitted = false;
+    if (!protocolSortInteraction) {
+        if (event?.type === "clickSort") {
+            return {
+                ok: true,
+                protocolSortInteraction: false,
+                state,
+                url: buildUrl(baseUrl, state),
+            };
+        }
+    }
+    if (event?.type === "init") {
+        if (table.defaultSort) {
+            state = {
+                ...state,
+                sort: `${table.defaultSort.field}:${table.defaultSort.order}`,
+                page: 1,
+            };
+            requestEmitted = true;
+        }
+    }
+    else if (event?.type === "clickSort") {
+        const columnField = event.field;
+        const column = table.columns.find((c) => c.field === columnField);
+        if (!column || !column.sortable) {
+            requestEmitted = true;
+            return {
+                ok: true,
+                requestEmitted,
+                state,
+                url: buildUrl(baseUrl, state),
+                ...(selection ? { selection } : {}),
+            };
+        }
+        const key = sortKeyOf(column);
+        const current = state.sort;
+        let next;
+        if (current === `${key}:asc`) {
+            next = `${key}:desc`;
+        }
+        else if (current === `${key}:desc`) {
+            next = null;
+        }
+        else {
+            next = `${key}:asc`;
+        }
+        state = { ...state, sort: next, page: 1 };
+        requestEmitted = true;
+        if (selection) {
+            selection = { keys: [], count: 0 };
+        }
+    }
+    else if (event?.type === "submitSearch") {
+        state = {
+            ...state,
+            filters: { ...(event.filters ?? {}) },
+            page: 1,
+        };
+        requestEmitted = true;
+    }
+    else if (event == null) {
+        // no event — just evaluate current state (unknown sort already handled)
+        requestEmitted = false;
+    }
+    const result = {
+        ok: true,
+        requestEmitted,
+        state,
+        url: buildUrl(baseUrl, state),
+    };
+    if (selection) {
+        result.selection = selection;
+    }
+    if (!protocolSortInteraction) {
+        result.protocolSortInteraction = false;
+    }
+    return result;
+}

package/protocol/conformance/upload-orchestration.js

@@ -0,0 +1,174 @@
+/**
+ * Upload orchestration (schema-ui-docs@2.7.0 · docs/07-actions-contract.md §7
+ * + ADR-0012). I-PROTO-FULL-001 D-UPLOAD include.
+ *
+ * Client contract:
+ *   - one multipart request per file (fieldName default "file"; method POST
+ *     default, PUT allowed)
+ *   - constraints (multiple / maxSize / accept) are checked BEFORE any
+ *     request; any violation rejects the whole batch atomically
+ *   - accept tokens: ".ext" matches the file extension case-insensitively,
+ *     "type/*" matches the MIME main type, other tokens match MIME exactly
+ *     (case-insensitive)
+ *   - serial uploads in selection order; any failure stops the batch and no
+ *     partial field value is committed
+ *   - field value: url (priority) or id; multiple → array in selection order
+ *   - retryPolicy idempotent → Idempotency-Key header "{invocationId}:{index}"
+ */
+const PROTOCOL_URL_RE = /^\/(?!\/)[^\s\\]*$/;
+const RETRY_POLICIES = new Set(["never", "idempotent"]);
+function fail(code, fileIndex, requests) {
+    return { ok: false, code, fileIndex, requests, fieldValue: null };
+}
+function responseFieldValue(response) {
+    if (typeof response.url === "string" && response.url !== "") {
+        return response.url;
+    }
+    if (typeof response.id === "string" && response.id !== "") {
+        return response.id;
+    }
+    return null;
+}
+/** accept token matching (ADR-0012 D2): ".ext", "type/*", exact MIME. */
+export function acceptTokenMatches(token, file) {
+    const trimmed = token.trim();
+    if (trimmed === "") {
+        return false;
+    }
+    if (trimmed.startsWith(".")) {
+        const dot = file.name.lastIndexOf(".");
+        if (dot < 0 || dot === file.name.length - 1) {
+            return false;
+        }
+        return file.name.slice(dot).toLowerCase() === trimmed.toLowerCase();
+    }
+    if (trimmed.endsWith("/*")) {
+        const main = trimmed.slice(0, trimmed.length - 2);
+        return file.type.toLowerCase().startsWith(`${main.toLowerCase()}/`);
+    }
+    return file.type.toLowerCase() === trimmed.toLowerCase();
+}
+/** Client-side constraints (ADR-0012 D2); returns the first violation. */
+export function validateUploadSelection(action, files) {
+    const maxIndex = action.multiple === true ? files.length : Math.min(files.length, 1);
+    if (action.multiple !== true && files.length > 1) {
+        return { ok: false, code: "MULTIPLE_FILES_NOT_ALLOWED", fileIndex: 1 };
+    }
+    for (let index = 0; index < maxIndex; index += 1) {
+        const file = files[index];
+        if (typeof action.maxSize === "number" && action.maxSize >= 0 && file.size > action.maxSize) {
+            return { ok: false, code: "FILE_TOO_LARGE", fileIndex: index };
+        }
+        if (typeof action.accept === "string" && action.accept.trim() !== "") {
+            const tokens = action.accept.split(",").map((token) => token.trim()).filter((token) => token !== "");
+            const matched = tokens.some((token) => acceptTokenMatches(token, file));
+            if (!matched) {
+                return { ok: false, code: "UNSUPPORTED_FILE_TYPE", fileIndex: index };
+            }
+        }
+    }
+    return { ok: true };
+}
+/** Builds the per-file multipart request descriptors (pre-request). */
+export function buildUploadRequests(action, files, invocationId) {
+    if (typeof action.url !== "string" || !PROTOCOL_URL_RE.test(action.url)) {
+        return fail("INVALID_PROTOCOL_URL", 0, []);
+    }
+    const retryPolicy = action.retryPolicy ?? "never";
+    if (!RETRY_POLICIES.has(retryPolicy)) {
+        return fail("INVALID_RETRY_POLICY", 0, []);
+    }
+    if (retryPolicy === "idempotent" && (typeof invocationId !== "string" || invocationId === "")) {
+        return fail("MISSING_INVOCATION_ID", 0, []);
+    }
+    const fieldName = typeof action.fieldName === "string" && action.fieldName !== "" ? action.fieldName : "file";
+    const method = action.method === "PUT" ? "PUT" : "POST";
+    const requests = files.map((file, index) => ({
+        method,
+        url: action.url,
+        part: { name: fieldName, fileName: file.name, contentId: file.contentId },
+        ...(retryPolicy === "idempotent"
+            ? { headers: { "Idempotency-Key": `${invocationId}:${index}` } }
+            : {}),
+    }));
+    return { ok: true, requests };
+}
+/**
+ * Fixture-driven orchestration: replays pre-recorded transport results
+ * (`conformance/fixtures/uploads/cases.json` contract).
+ */
+export function runUploadBatch(input) {
+    const validation = validateUploadSelection(input.action, input.files);
+    if (!validation.ok) {
+        return fail(validation.code, validation.fileIndex, []);
+    }
+    const built = buildUploadRequests(input.action, input.files, input.invocationId);
+    if (!built.ok) {
+        return built;
+    }
+    const requests = built.requests;
+    const values = [];
+    const results = input.results ?? [];
+    for (let index = 0; index < requests.length; index += 1) {
+        const result = results[index];
+        if (result === undefined || result.type === "failure") {
+            return fail("UPLOAD_REQUEST_FAILED", index, requests.slice(0, index + 1));
+        }
+        const value = responseFieldValue(result.response);
+        if (value === null) {
+            return fail("INVALID_UPLOAD_RESPONSE", index, requests.slice(0, index + 1));
+        }
+        values.push(value);
+    }
+    return {
+        ok: true,
+        requests,
+        fieldValue: input.action.multiple === true ? values : (values[0] ?? null),
+    };
+}
+/**
+ * Real transport orchestration used by the Renderer's upload control: the
+ * same constraints and request shape, executed against a live fetch with
+ * multipart FormData carrying the actual file bytes (ADR-0012 D4).
+ */
+export async function uploadFilesWithFetch(action, files, fetcher, invocationId) {
+    const validation = validateUploadSelection(action, files);
+    if (!validation.ok) {
+        return fail(validation.code, validation.fileIndex, []);
+    }
+    const built = buildUploadRequests(action, files, invocationId);
+    if (!built.ok) {
+        return built;
+    }
+    const requests = built.requests;
+    const values = [];
+    for (let index = 0; index < requests.length; index += 1) {
+        const request = requests[index];
+        const file = files[index];
+        const form = new FormData();
+        form.append(request.part.name, file.blob, file.name);
+        const response = await fetcher(request.url, {
+            method: request.method,
+            ...(request.headers === undefined ? {} : { headers: request.headers }),
+            body: form,
+        });
+        if (!response.ok) {
+            return fail("UPLOAD_REQUEST_FAILED", index, requests.slice(0, index + 1));
+        }
+        const payload = await response.json();
+        const record = (typeof payload === "object" && payload !== null ? payload : {});
+        const value = responseFieldValue({
+            url: typeof record.url === "string" ? record.url : undefined,
+            id: typeof record.id === "string" ? record.id : undefined,
+        });
+        if (value === null) {
+            return fail("INVALID_UPLOAD_RESPONSE", index, requests.slice(0, index + 1));
+        }
+        values.push(value);
+    }
+    return {
+        ok: true,
+        requests,
+        fieldValue: action.multiple === true ? values : (values[0] ?? null),
+    };
+}

package/protocol/conformance/version-negotiate.js

@@ -0,0 +1,155 @@
+/**
+ * version-negotiation fixture adapter (strict version + capability check).
+ */
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isVersionString(value) {
+    return typeof value === "string" && /^[0-9]+\.[0-9]+$/.test(value);
+}
+/** Capability id pattern from page.schema.json (lowercase dotted; v2.8 allows segment hyphens). */
+function isCapabilityId(value) {
+    return typeof value === "string" && /^[a-z][a-z0-9-]*(\.[a-z][a-z0-9-]*)*$/.test(value);
+}
+function pageVersionOf(pageMeta) {
+    if (!isRecord(pageMeta)) {
+        return null;
+    }
+    return pageMeta.protocolVersion ?? null;
+}
+export function negotiateVersion(input) {
+    const pageMeta = input.pageMeta;
+    const rendererSupport = input.rendererSupport;
+    const pageVersionHint = pageVersionOf(pageMeta);
+    if (!isRecord(rendererSupport)) {
+        return {
+            accepted: false,
+            code: "INVALID_RENDERER_SUPPORT",
+            pageVersion: isVersionString(pageVersionHint) ? pageVersionHint : pageVersionHint,
+            supportedVersions: [],
+            missingCapabilities: [],
+        };
+    }
+    const supportedVersionsRaw = rendererSupport.supportedVersions;
+    const supportedVersions = Array.isArray(supportedVersionsRaw)
+        ? supportedVersionsRaw
+        : [];
+    const versionsInvalid = !Array.isArray(supportedVersionsRaw) ||
+        supportedVersions.length === 0 ||
+        supportedVersions.some((v) => !isVersionString(v)) ||
+        new Set(supportedVersions).size !== supportedVersions.length;
+    // Parse page meta early so invalid renderer still reports pageVersion when present.
+    let pageVersion = null;
+    let required = [];
+    if (isRecord(pageMeta)) {
+        if (Object.prototype.hasOwnProperty.call(pageMeta, "protocolVersion")) {
+            pageVersion = pageMeta.protocolVersion;
+        }
+        if (pageMeta.requiredCapabilities !== undefined) {
+            if (!Array.isArray(pageMeta.requiredCapabilities) ||
+                pageMeta.requiredCapabilities.some((c) => typeof c !== "string") ||
+                pageMeta.requiredCapabilities.some((c) => !isCapabilityId(c)) ||
+                new Set(pageMeta.requiredCapabilities).size !==
+                    pageMeta.requiredCapabilities.length) {
+                // INVALID_REQUIRED_CAPABILITIES takes precedence over invalid renderer caps
+                // when both could apply (see fixture order).
+                if (!versionsInvalid || true) {
+                    // Still need version string validation path below for missing version.
+                }
+            }
+        }
+    }
+    if (versionsInvalid) {
+        return {
+            accepted: false,
+            code: "INVALID_RENDERER_SUPPORT",
+            pageVersion: isVersionString(pageVersion)
+                ? pageVersion
+                : isVersionString(pageVersionHint)
+                    ? pageVersionHint
+                    : pageVersionHint,
+            supportedVersions: supportedVersions,
+            missingCapabilities: [],
+        };
+    }
+    const supportedVersionsList = supportedVersions;
+    const supportedCapabilities = Array.isArray(rendererSupport.supportedCapabilities)
+        ? rendererSupport.supportedCapabilities
+        : [];
+    if (!isRecord(pageMeta)) {
+        return {
+            accepted: false,
+            code: "MISSING_PROTOCOL_VERSION",
+            pageVersion: null,
+            supportedVersions: supportedVersionsList,
+            missingCapabilities: [],
+        };
+    }
+    if (!Object.prototype.hasOwnProperty.call(pageMeta, "protocolVersion")) {
+        return {
+            accepted: false,
+            code: "MISSING_PROTOCOL_VERSION",
+            pageVersion: null,
+            supportedVersions: supportedVersionsList,
+            missingCapabilities: [],
+        };
+    }
+    if (!isVersionString(pageVersion)) {
+        return {
+            accepted: false,
+            code: "INVALID_PROTOCOL_VERSION",
+            pageVersion,
+            supportedVersions: supportedVersionsList,
+            missingCapabilities: [],
+        };
+    }
+    if (pageMeta.requiredCapabilities !== undefined) {
+        const caps = pageMeta.requiredCapabilities;
+        if (!Array.isArray(caps) ||
+            caps.some((c) => typeof c !== "string") ||
+            caps.some((c) => !isCapabilityId(c)) ||
+            new Set(caps).size !== caps.length) {
+            return {
+                accepted: false,
+                code: "INVALID_REQUIRED_CAPABILITIES",
+                pageVersion,
+                supportedVersions: supportedVersionsList,
+                missingCapabilities: [],
+            };
+        }
+        required = caps;
+    }
+    // Renderer capability list validation is secondary; fixtures primarily care about required.
+    if (Array.isArray(rendererSupport.supportedCapabilities) &&
+        (new Set(supportedCapabilities).size !== supportedCapabilities.length ||
+            supportedCapabilities.some((c) => !isCapabilityId(c)))) {
+        // If required caps were valid we already passed; invalid renderer caps alone
+        // may still be INVALID_RENDERER_SUPPORT in some suites — not present in current set.
+    }
+    if (!supportedVersionsList.includes(pageVersion)) {
+        return {
+            accepted: false,
+            code: "UNSUPPORTED_PROTOCOL_VERSION",
+            pageVersion,
+            supportedVersions: supportedVersionsList,
+            missingCapabilities: [],
+        };
+    }
+    const missing = required.filter((cap) => !supportedCapabilities.includes(cap));
+    if (missing.length > 0) {
+        return {
+            accepted: false,
+            code: "MISSING_REQUIRED_CAPABILITY",
+            pageVersion,
+            supportedVersions: supportedVersionsList,
+            missingCapabilities: missing,
+        };
+    }
+    return {
+        accepted: true,
+        code: "OK",
+        pageVersion,
+        supportedVersions: supportedVersionsList,
+        missingCapabilities: [],
+    };
+}

package/protocol/index.d.ts

@@ -4,5 +4,5 @@
  * 协议面：app-manifest 协商/校验/路由 + 页面文档加载/校验管线。
  * 打包：apps/web Vite lib mode（vite.lib.config.ts）+ tsc declaration。
  */
-export * from "./app-manifest";
-export * from "./load-page";
+export * from "./app-manifest.js";
+export * from "./load-page.js";

package/protocol/index.js

@@ -0,0 +1,8 @@
+/**
+ * @magicvr/schema-ui-protocol 聚合导出（试点 v0.1.0 · GOAL-004 S2）。
+ *
+ * 协议面：app-manifest 协商/校验/路由 + 页面文档加载/校验管线。
+ * 打包：apps/web Vite lib mode（vite.lib.config.ts）+ tsc declaration。
+ */
+export * from "./app-manifest.js";
+export * from "./load-page.js";