@svadmin/surface 0.11.8 → 0.12.0

package/README.md

@@ -189,3 +189,18 @@ Limits are eight data sources, 24 widgets, 100 rows per page, eight filters, thr
 Actual OpenUI Lang parsing, nested interactive forms, registered business actions, server persistence, SSR/Lite rendering, arbitrary URLs, client aggregation, Canvas and iframe execution are not implemented. Aggregated metrics should come from a policy-authorized backend summary resource and bind through `resource-one`. The current UI contract remains read-only even though its definition can be edited.
 
 See `docs/architecture/openui-surface-phase2.md` for the original feature scope and `docs/architecture/surface-integration-provenance.md` for historical integration evidence. 中文指南见文档站的“声明式 Surface”。
+
+## json-render 适配
+
+Surface 可以接收 Vercel `json-render` 使用的标准扁平 `Spec`（`root` + `elements`），同时继续由 Surface 的 TypeBox Schema、组件目录和资源策略负责最终校验。协议入口提供 `jsonRenderSpecToSurfaceSpec` 和 `surfaceSpecToJsonRenderSpec`：前者只接受以 `surface` 为根、一级业务组件为子节点的受控子集，后者用于把已校验的 SurfaceSpec 输出为标准扁平 Spec。
+
+适配层不执行 json-render 的任意 action、脚本、URL 或嵌套组件树；业务数据查询仍经过 Surface DataProvider 和既有授权流程。项目业务契约继续使用 TypeBox，未引入 Zod 运行时依赖。本入口只提供格式互操作，不包含官方 json-render Catalog、流式编译器或渲染器集成。`binding` 和 `placement` 是适配器保留属性；导出包含这些业务属性的组件时会抛错，避免静默覆盖。
+
+```ts
+import { jsonRenderSpecToSurfaceSpec } from '@svadmin/surface';
+
+const result = jsonRenderSpecToSurfaceSpec(jsonRenderSpec, catalog, policy);
+if (result.ok) {
+  // 交给现有 SurfaceRenderer；此处仍是候选页面，不代表业务动作授权。
+}
+```

package/compatibility.json

@@ -1,5 +1,5 @@
 {
-  "surface": "0.11.x",
+  "surface": "0.12.x",
   "minimumSupported": {
     "@svadmin/core": "0.53.0",
     "@svadmin/ui": "0.73.0",

package/dist/index.d.ts

@@ -10,3 +10,5 @@ export { SURFACE_EDIT_SCHEMA_VERSION, SURFACE_EDIT_LIMITS, createSurfaceRevision
 export type { SurfaceEditOperation, SurfaceEditProposal, SurfaceEditIssue, SurfaceRevision, SurfaceRevisionResult, } from './edits.js';
 export { svarGridPropsSchema, svarGridDefinition } from './svar-schema.js';
 export type { SvarGridProps } from './svar-schema.js';
+export { jsonRenderSurfaceRootPropsSchema, jsonRenderUiElementSchema, jsonRenderSpecSchema, jsonRenderSpecToSurfaceSpec, surfaceSpecToJsonRenderSpec, } from './json-render.js';
+export type { JsonRenderSurfaceElement, JsonRenderSurfaceSpec, JsonRenderSurfaceResult, } from './json-render.js';

package/dist/index.js

@@ -5,3 +5,4 @@ export { SURFACE_AGENT_LIMITS, SURFACE_AGENT_RESPONSE_SCHEMA_VERSION, SURFACE_CA
 export { SURFACE_EDIT_SCHEMA_VERSION, SURFACE_EDIT_LIMITS, createSurfaceRevision, applySurfaceEditProposal, createSurfaceEditSchema, buildSurfaceEditMessages, } from './edits.js';
 // 只导出 JSON schema，不将可选 SVAR 渲染器加载到协议入口。
 export { svarGridPropsSchema, svarGridDefinition } from './svar-schema.js';
+export { jsonRenderSurfaceRootPropsSchema, jsonRenderUiElementSchema, jsonRenderSpecSchema, jsonRenderSpecToSurfaceSpec, surfaceSpecToJsonRenderSpec, } from './json-render.js';

package/dist/json-render.d.ts

@@ -0,0 +1,68 @@
+import { type Static } from '@sinclair/typebox';
+import type { SurfaceCatalog, SurfacePolicy, SurfaceSpec } from './types.js';
+/** json-render 的标准扁平 Spec 子集；业务字段仍由 Surface 的 TypeBox 契约校验。 */
+export declare const jsonRenderSurfaceRootPropsSchema: import("@sinclair/typebox").TObject<{
+    layout: import("@sinclair/typebox").TObject<{
+        type: import("@sinclair/typebox").TLiteral<"grid">;
+        columns: import("@sinclair/typebox").TLiteral<12>;
+        gap: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"sm">, import("@sinclair/typebox").TLiteral<"md">, import("@sinclair/typebox").TLiteral<"lg">]>>;
+    }>;
+    title: import("@sinclair/typebox").TString;
+    catalogVersion: import("@sinclair/typebox").TString;
+    surfaceId: import("@sinclair/typebox").TString;
+    dataSources: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TObject<{
+        id: import("@sinclair/typebox").TString;
+        type: import("@sinclair/typebox").TLiteral<"resource-list">;
+        resource: import("@sinclair/typebox").TString;
+        pageSize: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TInteger>;
+        sorters: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
+            field: import("@sinclair/typebox").TString;
+            order: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"asc">, import("@sinclair/typebox").TLiteral<"desc">]>;
+        }>>>;
+        filters: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TObject<{
+            field: import("@sinclair/typebox").TString;
+            operator: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"eq">, import("@sinclair/typebox").TLiteral<"ne">, import("@sinclair/typebox").TLiteral<"lt">, import("@sinclair/typebox").TLiteral<"lte">, import("@sinclair/typebox").TLiteral<"gt">, import("@sinclair/typebox").TLiteral<"gte">, import("@sinclair/typebox").TLiteral<"contains">, import("@sinclair/typebox").TLiteral<"startswith">, import("@sinclair/typebox").TLiteral<"endswith">]>;
+            value: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TString, import("@sinclair/typebox").TNumber, import("@sinclair/typebox").TBoolean, import("@sinclair/typebox").TNull]>;
+        }>, import("@sinclair/typebox").TObject<{
+            field: import("@sinclair/typebox").TString;
+            operator: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"in">, import("@sinclair/typebox").TLiteral<"nin">]>;
+            value: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TString, import("@sinclair/typebox").TNumber, import("@sinclair/typebox").TBoolean, import("@sinclair/typebox").TNull]>>;
+        }>, import("@sinclair/typebox").TObject<{
+            field: import("@sinclair/typebox").TString;
+            operator: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"null">, import("@sinclair/typebox").TLiteral<"nnull">]>;
+        }>]>>>;
+    }>, import("@sinclair/typebox").TObject<{
+        id: import("@sinclair/typebox").TString;
+        type: import("@sinclair/typebox").TLiteral<"resource-one">;
+        resource: import("@sinclair/typebox").TString;
+        recordId: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TString, import("@sinclair/typebox").TNumber]>;
+    }>]>>;
+}>;
+export declare const jsonRenderUiElementSchema: import("@sinclair/typebox").TObject<{
+    type: import("@sinclair/typebox").TString;
+    props: import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TUnknown>;
+    children: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>>;
+}>;
+export declare const jsonRenderSpecSchema: import("@sinclair/typebox").TObject<{
+    root: import("@sinclair/typebox").TString;
+    elements: import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TObject<{
+        type: import("@sinclair/typebox").TString;
+        props: import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TUnknown>;
+        children: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>>;
+    }>>;
+}>;
+export type JsonRenderSurfaceElement = Static<typeof jsonRenderUiElementSchema>;
+export type JsonRenderSurfaceSpec = Static<typeof jsonRenderSpecSchema>;
+export type JsonRenderSurfaceResult = {
+    readonly ok: true;
+    readonly value: SurfaceSpec;
+} | {
+    readonly ok: false;
+    readonly issues: readonly {
+        readonly path: string;
+        readonly message: string;
+    }[];
+};
+export declare function jsonRenderSpecToSurfaceSpec(input: unknown, catalog: SurfaceCatalog, policy: SurfacePolicy): JsonRenderSurfaceResult;
+/** 将已校验的 SurfaceSpec 编码为 json-render 的标准扁平 Spec。 */
+export declare function surfaceSpecToJsonRenderSpec(spec: SurfaceSpec): JsonRenderSurfaceSpec;

package/dist/json-render.js

@@ -0,0 +1,117 @@
+import { Type } from '@sinclair/typebox';
+import { Value } from '@sinclair/typebox/value';
+import { validateSurfaceSpec } from './validation.js';
+import { jsonPointer } from './json.js';
+import { parseSurfaceJson } from './wire.js';
+import { surfaceSpecSchema, surfaceWidgetSchema } from './schema.js';
+/** json-render 的标准扁平 Spec 子集；业务字段仍由 Surface 的 TypeBox 契约校验。 */
+export const jsonRenderSurfaceRootPropsSchema = Type.Omit(surfaceSpecSchema, ['schemaVersion', 'widgets']);
+export const jsonRenderUiElementSchema = Type.Object({
+    type: Type.String({ minLength: 1 }),
+    props: Type.Record(Type.String(), Type.Unknown()),
+    children: Type.Optional(Type.Array(Type.String({ minLength: 1 }))),
+}, { additionalProperties: false });
+export const jsonRenderSpecSchema = Type.Object({
+    root: Type.String({ minLength: 1 }),
+    elements: Type.Record(Type.String({ minLength: 1 }), jsonRenderUiElementSchema),
+}, { additionalProperties: false });
+function issue(path, message) {
+    return { path, message };
+}
+/**
+ * 将 json-render Spec 转换为受 Surface 权限、目录和 TypeBox 规则保护的 SurfaceSpec。
+ * 只接受 root 类型为 surface 的子集，避免把任意 json-render 组件树当作业务页面执行。
+ */
+function readSurfaceRoot(candidate) {
+    const root = candidate.elements[candidate.root];
+    if (!root || root.type !== 'surface')
+        return { error: 'json-render root must reference a surface element' };
+    if (!Value.Check(jsonRenderSurfaceRootPropsSchema, root.props))
+        return { error: 'Invalid surface root properties' };
+    return root;
+}
+function readWidgetElement(element, id) {
+    if (element.type === 'surface')
+        return { error: 'Nested surface elements are not supported' };
+    if (element.children?.length)
+        return { error: 'Widget children are not supported' };
+    const binding = element.props['binding'];
+    const placement = element.props['placement'];
+    if (binding !== undefined && !Value.Check(surfaceWidgetSchema.properties.binding, binding))
+        return { error: 'Invalid widget binding' };
+    if (placement !== undefined && !Value.Check(surfaceWidgetSchema.properties.placement, placement))
+        return { error: 'Invalid widget placement' };
+    const props = { ...element.props };
+    delete props['binding'];
+    delete props['placement'];
+    return { id, type: element.type, props,
+        ...(binding === undefined ? {} : { binding }),
+        ...(placement === undefined ? {} : { placement }),
+    };
+}
+function parseJsonRenderSpec(input) {
+    const parsed = parseSurfaceJson(input);
+    if (!parsed.ok)
+        return { error: parsed.issues[0]?.message ?? 'Invalid JSON', path: parsed.issues[0]?.path ?? '' };
+    if (!Value.Check(jsonRenderSpecSchema, parsed.value))
+        return { error: 'Invalid json-render spec' };
+    return parsed.value;
+}
+export function jsonRenderSpecToSurfaceSpec(input, catalog, policy) {
+    const parsed = parseJsonRenderSpec(input);
+    if ('error' in parsed)
+        return { ok: false, issues: [issue(parsed.path ?? '', parsed.error)] };
+    const root = readSurfaceRoot(parsed);
+    if ('error' in root)
+        return { ok: false, issues: [issue('/root', root.error)] };
+    const children = root.children ?? [];
+    const widgets = [];
+    for (const childId of children) {
+        const element = parsed.elements[childId];
+        if (!element)
+            return { ok: false, issues: [issue(jsonPointer(['elements', childId]), 'Missing child element')] };
+        const widget = readWidgetElement(element, childId);
+        if ('error' in widget)
+            return { ok: false, issues: [issue(jsonPointer(['elements', childId]), widget.error)] };
+        widgets.push(widget);
+    }
+    if (new Set(children).size !== children.length || Object.keys(parsed.elements).length !== children.length + 1)
+        return { ok: false, issues: [issue('/elements', 'Every element must occur exactly once in the surface tree')] };
+    const surface = { schemaVersion: 'surface/v1', ...root.props, widgets };
+    const validation = validateSurfaceSpec(surface, catalog, policy);
+    return validation.ok ? validation : { ok: false, issues: validation.issues.map(({ path, message }) => ({ path, message })) };
+}
+/** 将已校验的 SurfaceSpec 编码为 json-render 的标准扁平 Spec。 */
+export function surfaceSpecToJsonRenderSpec(spec) {
+    const root = '__svadmin_surface_root';
+    if (spec.widgets.some(widget => widget.id === root)) {
+        throw new Error('Surface widget id is reserved by the json-render adapter');
+    }
+    const elements = {
+        [root]: {
+            type: 'surface',
+            props: {
+                catalogVersion: spec.catalogVersion,
+                surfaceId: spec.surfaceId,
+                title: spec.title,
+                layout: spec.layout,
+                dataSources: spec.dataSources,
+            },
+            children: spec.widgets.map(widget => widget.id),
+        },
+    };
+    for (const widget of spec.widgets) {
+        if (Object.hasOwn(widget.props, 'binding') || Object.hasOwn(widget.props, 'placement')) {
+            throw new Error('Widget props binding and placement are reserved by the json-render adapter');
+        }
+        elements[widget.id] = {
+            type: widget.type,
+            props: {
+                ...widget.props,
+                ...(widget.binding ? { binding: widget.binding } : {}),
+                ...(widget.placement ? { placement: widget.placement } : {}),
+            },
+        };
+    }
+    return { root, elements };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@svadmin/surface",
-  "version": "0.11.8",
+  "version": "0.12.0",
   "description": "Validated declarative surfaces for svadmin dashboards",
   "type": "module",
   "sideEffects": [