@svadmin/surface 0.18.1 → 0.19.0

package/README.md

@@ -146,9 +146,9 @@ Only fences tagged `surface` (```` ```surface ````) are treated as proposals; ev
 
 `buildSurfaceAgentPrompt()` and `parseSurfaceAgentProposal()` remain compatible with the legacy proposal-only `surface-agent/v1` envelope. The new message API uses `surface-agent/v2` with a structured `cannot-fulfill` alternative. `createSurfaceAgentStream()` buffers bounded text and validates at `finish()`; it does **not** render partial JSON or implement OpenUI Lang streaming.
 
-## Host-only record selection
+## Host-only interactions
 
-`SurfaceRenderer` stays read-only and executes nothing on its own. A host that wants a follow-up from a card registers `onInteraction`; only then does `resource-table` render a per-row select button:
+`SurfaceRenderer` stays read-only and executes nothing on its own. A host that wants a follow-up from a card registers `onInteraction`; only then do interactive widgets expose their affordances:
 
 ```svelte
 <SurfaceRenderer
@@ -156,18 +156,30 @@ Only fences tagged `surface` (```` ```surface ````) are treated as proposals; ev
   {policy}
   {dataProvider}
   onInteraction={(event) => {
-    if (event.type !== 'select-record') return;
-    // event.record only carries JSON-safe values from the widget's declared columns.
-    sendFollowUp(`继续分析 ${JSON.stringify(event.record)}`);
+    if (event.type === 'select-record') {
+      // event.record only carries JSON-safe values from the widget's declared columns.
+      sendFollowUp(`继续分析 ${JSON.stringify(event.record)}`);
+    } else {
+      // event.values are the widget's local field values, re-validated by the renderer.
+      sendFollowUp(`提交内容 ${JSON.stringify(event.values)}`);
+    }
   }}
 />
 ```
 
+Two event shapes exist, both scoped with `surfaceId`, `widgetId` and optional `sourceId`:
+
+| Event | Emitted by | Payload |
+| --- | --- | --- |
+| `select-record` | `resource-table` row select | `record`: detached copy projected from the widget's declared columns |
+| `submit-values` | widgets that call `onSubmitValues`, such as form widgets in a custom catalog | `values`: the widget's local values, re-validated and detached by the renderer |
+
 An interaction event is presentation data, not an authorization record:
 
 - The library never executes the follow-up, and `SurfaceSpec` gains no action, URL, event handler, or mutation field.
-- `record` is a detached copy projected from the widget's declared columns; undeclared fields are dropped, and values that are not JSON-safe (for example `Date`, `NaN`, or functions) are omitted instead of converted.
-- When nothing survives projection, no event is emitted. `projectInteractionRecord()` is exported for hosts and custom catalog widgets that need the same rule.
+- Undeclared record fields are dropped, and values that are not JSON-safe (for example `Date`, `NaN`, or functions) are omitted instead of converted.
+- Submitted values fail closed: dangerous keys such as `__proto__`, non-JSON values, and payloads above `SURFACE_INTERACTION_MAX_CHARACTERS` produce no event.
+- When nothing survives projection, no event is emitted. `projectInteractionRecord()` and `projectInteractionValues()` are exported for hosts and custom catalog widgets that need the same rules.
 
 ## Revisioned edits and explicit preview
 

package/compatibility.json

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

package/dist/catalog.d.ts

@@ -10,6 +10,8 @@ export interface SurfaceWidgetRendererProps {
     readonly messages?: SurfaceMessages;
     /** 宿主注册后，组件才渲染可选择行；组件自行按声明列投影记录。 */
     readonly onSelectRecord?: (record: JsonObject) => void;
+    /** 宿主注册后，组件才提供提交入口；值由渲染器重新校验后再交给宿主。 */
+    readonly onSubmitValues?: (values: JsonObject) => void;
 }
 export interface SurfaceWidgetRegistration extends SurfaceWidgetDefinition {
     readonly presentation?: 'surface-appearance/v1';

package/dist/components/SurfaceRenderer.svelte

@@ -5,7 +5,7 @@
   import { SvelteMap } from 'svelte/reactivity';
   import { resolveSurfaceSourceData } from '../binding.js';
   import { defaultSurfaceCatalog } from '../catalog.js';
-  import type { SurfaceInteractionEvent } from '../interactions.js';
+  import { projectInteractionValues, type SurfaceInteractionEvent } from '../interactions.js';
   import type { SurfaceRenderCatalog } from '../catalog.js';
   import { loadSurfaceSource } from '../runtime.js';
   import { resolveSurfaceMessages } from '../localization.js';
@@ -79,6 +79,17 @@
       ...(sourceId === undefined ? {} : { sourceId }),
     });
   }
+
+  function valuesSubmitted(surfaceId: string, widgetId: string, sourceId: string | undefined, values: JsonObject): void {
+    if (!onInteraction) return;
+    // 组件值同样属于不可信输入：重新校验并深拷贝后才交给宿主。
+    const projected = projectInteractionValues(values);
+    if (projected === null) return;
+    onInteraction({
+      type: 'submit-values', surfaceId, widgetId, values: projected,
+      ...(sourceId === undefined ? {} : { sourceId }),
+    });
+  }
   const widgetRegistrations = $derived(new Map(catalog.widgets.map((widget) => [widget.type, widget])));
   const sourceStates = new SvelteMap<string, SurfaceSourceDataState>();
   let destroyed = false;
@@ -197,6 +208,7 @@
                 locale={activeLocale} messages={activeMessages}
                 {...(onInteraction === undefined ? {} : {
                   onSelectRecord: (record: JsonObject) => recordSelected(validation.value.surfaceId, widget.id, widget.binding?.sourceId, record),
+                  onSubmitValues: (values: JsonObject) => valuesSubmitted(validation.value.surfaceId, widget.id, widget.binding?.sourceId, values),
                 })} />
             {/if}
           </div>

package/dist/components/SurfaceRenderer.svelte.d.ts

@@ -1,4 +1,4 @@
-import type { SurfaceInteractionEvent } from '../interactions.js';
+import { type SurfaceInteractionEvent } from '../interactions.js';
 import type { SurfaceRenderCatalog } from '../catalog.js';
 import type { SurfaceMessages } from '../localization.js';
 import type { SurfaceDataError, SurfaceDataProvider, SurfacePolicy, SurfaceValidationIssue } from '../types.js';

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 export { SURFACE_LIMITS, SURFACE_SCHEMA_VERSION } from './types.js';
 export type { JsonObject, JsonPrimitive, JsonValue, ResourceListDataSource, ResourceListSource, ResourceOneDataSource, ResourceOneSource, SurfaceBinding, SurfaceCatalog, SurfaceCatalogDataKind, SurfaceDataError, SurfaceDataProvider, SurfaceDataSource, SurfaceFilter, SurfaceGridLayout, SurfaceGridSpan, SurfacePolicy, SurfaceResourcePolicy, SurfaceSort, SurfaceSpec, SurfaceValidationCode, SurfaceValidationIssue, SurfaceValidationResult, SurfaceWidget, SurfaceWidgetDataState, SurfaceWidgetDefinition, } from './types.js';
 export { validateSurfaceSpec } from './validation.js';
-export { projectInteractionRecord } from './interactions.js';
+export { SURFACE_INTERACTION_MAX_CHARACTERS, projectInteractionRecord, projectInteractionValues } from './interactions.js';
 export type { SurfaceInteraction, SurfaceInteractionEvent } from './interactions.js';
 export type { SurfaceMessages } from './localization.js';
 export { SURFACE_AGENT_SCHEMA_VERSION, buildSurfaceAgentPrompt, buildSurfaceAgentMessages, parseSurfaceAgentProposal, parseSurfaceAgentResponse, createSurfaceAgentStream, } from './agent.js';

package/dist/index.js

@@ -1,6 +1,6 @@
 export { SURFACE_LIMITS, SURFACE_SCHEMA_VERSION } from './types.js';
 export { validateSurfaceSpec } from './validation.js';
-export { projectInteractionRecord } from './interactions.js';
+export { SURFACE_INTERACTION_MAX_CHARACTERS, projectInteractionRecord, projectInteractionValues } from './interactions.js';
 export { SURFACE_AGENT_SCHEMA_VERSION, buildSurfaceAgentPrompt, buildSurfaceAgentMessages, parseSurfaceAgentProposal, parseSurfaceAgentResponse, createSurfaceAgentStream, } from './agent.js';
 export { SURFACE_AGENT_FENCE_TAG, splitSurfaceAgentText, } from './agent-text.js';
 export { SURFACE_AGENT_LIMITS, SURFACE_AGENT_RESPONSE_SCHEMA_VERSION, SURFACE_CATALOG_SCHEMA_VERSION, createSurfaceCatalogManifest, createSurfaceAgentResponseSchema, selectSurfaceCatalog, } from './agent-contract.js';

package/dist/interactions.d.ts

@@ -1,17 +1,31 @@
 import type { JsonObject } from './types.js';
 /**
- * 用户在界面上主动触发的只读选择，不是 action、mutation 或授权凭据。
+ * 用户在界面上主动触发的只读交互，不是 action、mutation 或授权凭据。
  * 宿主自行决定是否把它变成后续操作（例如追加一条用户消息）。
  */
-export interface SurfaceInteraction {
+export type SurfaceInteraction = {
     readonly type: 'select-record';
     /** 只包含声明列的 JSON 安全值；不完整，也不能当作授权记录。 */
     readonly record: JsonObject;
-}
+} | {
+    readonly type: 'submit-values';
+    /** 组件本地收集的字段值；宿主必须重新校验，不能当作已授权输入。 */
+    readonly values: JsonObject;
+};
 /** 渲染器补齐作用域后交给宿主的事件；宿主不得把这些字段写回渲染器。 */
-export interface SurfaceInteractionEvent extends SurfaceInteraction {
+export type SurfaceInteractionEvent = SurfaceInteraction & {
     readonly surfaceId: string;
     readonly widgetId: string;
     readonly sourceId?: string;
-}
+};
+/** 组件一次回传的最大字符数；超过时失败关闭而不是截断。 */
+export declare const SURFACE_INTERACTION_MAX_CHARACTERS = 16384;
 export declare function projectInteractionRecord(record: JsonObject, fields: readonly string[]): JsonObject | null;
+/**
+ * 校验并深拷贝组件提交的字段值。只接受 JSON 安全值；危险键（如 `__proto__`）、
+ * 非 JSON 值和超过字符上限的内容一律失败关闭，调用方不应发出事件。
+ *
+ * @param values 组件本地状态，例如表单字段。
+ * @returns 独立副本，或 `null`。
+ */
+export declare function projectInteractionValues(values: JsonObject): JsonObject | null;

package/dist/interactions.js

@@ -1,4 +1,6 @@
 import { isJsonValue, jsonValueIssue } from './json.js';
+/** 组件一次回传的最大字符数；超过时失败关闭而不是截断。 */
+export const SURFACE_INTERACTION_MAX_CHARACTERS = 16_384;
 /**
  * 只投影声明过的列，并跳过无法安全序列化的值（如 Date、函数、循环引用）。
  * 嵌套对象和数组会深拷贝，宿主后续修改不会写回渲染器缓存。
@@ -42,3 +44,25 @@ export function projectInteractionRecord(record, fields) {
     }
     return included === 0 ? null : projected;
 }
+/**
+ * 校验并深拷贝组件提交的字段值。只接受 JSON 安全值；危险键（如 `__proto__`）、
+ * 非 JSON 值和超过字符上限的内容一律失败关闭，调用方不应发出事件。
+ *
+ * @param values 组件本地状态，例如表单字段。
+ * @returns 独立副本，或 `null`。
+ */
+export function projectInteractionValues(values) {
+    if (jsonValueIssue(values) !== null)
+        return null;
+    const detached = detachJsonValue(values);
+    if (detached === null || typeof detached !== 'object' || Array.isArray(detached))
+        return null;
+    let serialized;
+    try {
+        serialized = JSON.stringify(detached);
+    }
+    catch {
+        return null;
+    }
+    return serialized.length > SURFACE_INTERACTION_MAX_CHARACTERS ? null : detached;
+}

package/package.json

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