@svadmin/surface 0.17.0 → 0.18.1

package/README.md

@@ -146,6 +146,29 @@ 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
+
+`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:
+
+```svelte
+<SurfaceRenderer
+  {spec}
+  {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)}`);
+  }}
+/>
+```
+
+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.
+
 ## Revisioned edits and explicit preview
 
 `createSurfaceRevision()` creates a validated immutable snapshot. `buildSurfaceEditMessages()` describes the current revision, catalog and allowed operations. `applySurfaceEditProposal()` validates a complete `surface-edit/v1` transaction and returns a new candidate revision without mutating the old one. Operations cover title/layout, widget/source upsert/removal and complete widget reordering by stable ID. Stale `baseRevision`, unknown IDs, invalid props, denied fields and broken final references reject the whole transaction.

package/compatibility.json

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

package/dist/catalog.d.ts

@@ -8,6 +8,8 @@ export interface SurfaceWidgetRendererProps {
     readonly data: SurfaceWidgetDataState;
     readonly locale?: string;
     readonly messages?: SurfaceMessages;
+    /** 宿主注册后，组件才渲染可选择行；组件自行按声明列投影记录。 */
+    readonly onSelectRecord?: (record: JsonObject) => void;
 }
 export interface SurfaceWidgetRegistration extends SurfaceWidgetDefinition {
     readonly presentation?: 'surface-appearance/v1';

package/dist/components/ResourceTableWidget.svelte

@@ -14,15 +14,27 @@
   import Table from '@svadmin/ui/components/ui/table/table.svelte';
   import { styledResourceTablePropsSchema as resourceTablePropsSchema } from '../builtin-schemas.js';
   import type { SurfaceWidgetRendererProps } from '../catalog.js';
+  import { projectInteractionRecord } from '../interactions.js';
   import { resolveSurfaceMessages, surfaceErrorMessage } from '../localization.js';
   import { asRecordArray, displayTableValue } from '../widget-data.js';
+  import type { JsonObject } from '../types.js';
 
-  let { props, data, locale = 'en-US', messages }: SurfaceWidgetRendererProps = $props();
+  let { props, data, locale = 'en-US', messages, onSelectRecord }: SurfaceWidgetRendererProps = $props();
   const activeMessages = $derived(resolveSurfaceMessages(locale, messages));
 
   const tableProps = $derived(Value.Decode(resourceTablePropsSchema, props));
   const tableClasses = $derived(surfaceTable());
   const records = $derived(data.status === 'ready' ? asRecordArray(data.value) : null);
+  const fields = $derived(tableProps.columns.map((column) => column.field));
+  const selectable = $derived(onSelectRecord !== undefined);
+  const selectLabel = $derived(activeMessages.tableSelect ?? 'Select');
+
+  // 只有宿主注册交互时才发出事件；投影后没有任何可交付字段就保持静默。
+  function selectRecord(record: JsonObject): void {
+    if (!onSelectRecord) return;
+    const projected = projectInteractionRecord(record, fields);
+    if (projected !== null) onSelectRecord(projected);
+  }
 </script>
 
 <Card class={tableClasses?.root}>
@@ -44,6 +56,9 @@
               {#each tableProps.columns as column (column.field)}
                 <TableHead class={tableClasses?.head} scope="col">{column.label}</TableHead>
               {/each}
+              {#if selectable}
+                <TableHead class={tableClasses?.head} scope="col">{selectLabel}</TableHead>
+              {/if}
             </TableRow>
           </TableHeader>
           <TableBody>
@@ -56,6 +71,13 @@
                     messages: activeMessages,
                   })}</TableCell>
                 {/each}
+                {#if selectable}
+                  <TableCell class={tableClasses?.cell}>
+                    <button type="button" class="surface-record-select" aria-label="{tableProps.title}: {selectLabel} {index + 1}" onclick={() => selectRecord(record)}>
+                      {selectLabel}
+                    </button>
+                  </TableCell>
+                {/if}
               </TableRow>
             {/each}
           </TableBody>
@@ -68,6 +90,20 @@
 </Card>
 
 <style>
+  .surface-record-select {
+    padding: 0.125rem 0.5rem;
+    border: 1px solid var(--border);
+    border-radius: 0.375rem;
+    background: var(--background);
+    color: var(--foreground);
+    font: inherit;
+    font-size: 0.75rem;
+    cursor: pointer;
+  }
+
+  .surface-record-select:hover { background: var(--accent); }
+  .surface-record-select:focus-visible { outline: 2px solid var(--ring); outline-offset: 2px; }
+
   .table-state {
     display: grid;
     min-height: var(--svadmin-table-state-height, 8rem);

package/dist/components/SurfaceRenderer.svelte

@@ -5,6 +5,7 @@
   import { SvelteMap } from 'svelte/reactivity';
   import { resolveSurfaceSourceData } from '../binding.js';
   import { defaultSurfaceCatalog } from '../catalog.js';
+  import type { SurfaceInteractionEvent } from '../interactions.js';
   import type { SurfaceRenderCatalog } from '../catalog.js';
   import { loadSurfaceSource } from '../runtime.js';
   import { resolveSurfaceMessages } from '../localization.js';
@@ -44,11 +45,13 @@
     readonly messages?: Partial<SurfaceMessages>;
     readonly class?: string;
     readonly onError?: (error: SurfaceRendererError) => void;
+    /** 宿主注册后，只读组件才发出选择事件；库本身不执行任何后续操作。 */
+    readonly onInteraction?: (event: SurfaceInteractionEvent) => void;
   }
 
   let {
     spec, policy, catalog = defaultSurfaceCatalog, dataProvider, scopeKey = '', dataScopeKey,
-    locale, messages, class: className = '', onError,
+    locale, messages, class: className = '', onError, onInteraction,
   }: SurfaceRendererProps = $props();
 
   const adminContext = captureAdminContext();
@@ -68,6 +71,14 @@
       : { ...data, error: { ...data.error, message } };
   }
   const validation = $derived(validateSurfaceSpec(spec, catalog, policy));
+
+  function recordSelected(surfaceId: string, widgetId: string, sourceId: string | undefined, record: JsonObject): void {
+    if (!onInteraction) return;
+    onInteraction({
+      type: 'select-record', surfaceId, widgetId, record,
+      ...(sourceId === undefined ? {} : { sourceId }),
+    });
+  }
   const widgetRegistrations = $derived(new Map(catalog.widgets.map((widget) => [widget.type, widget])));
   const sourceStates = new SvelteMap<string, SurfaceSourceDataState>();
   let destroyed = false;
@@ -183,7 +194,10 @@
             {#if WidgetComponent}
               <WidgetComponent widgetId={widget.id} props={semantic ? withoutSurfaceAppearance(widget.props) : widget.props}
                 data={presentSurfaceData(resolveSurfaceSourceData(widget, widget.binding ? sourceStates.get(widget.binding.sourceId) : undefined))}
-                locale={activeLocale} messages={activeMessages} />
+                locale={activeLocale} messages={activeMessages}
+                {...(onInteraction === undefined ? {} : {
+                  onSelectRecord: (record: JsonObject) => recordSelected(validation.value.surfaceId, widget.id, widget.binding?.sourceId, record),
+                })} />
             {/if}
           </div>
         {/each}

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

@@ -1,3 +1,4 @@
+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';
@@ -22,6 +23,8 @@ export interface SurfaceRendererProps {
     readonly messages?: Partial<SurfaceMessages>;
     readonly class?: string;
     readonly onError?: (error: SurfaceRendererError) => void;
+    /** 宿主注册后，只读组件才发出选择事件；库本身不执行任何后续操作。 */
+    readonly onInteraction?: (event: SurfaceInteractionEvent) => void;
 }
 declare const SurfaceRenderer: import("svelte").Component<SurfaceRendererProps, {
     refresh: (sourceId?: string) => Promise<void>;

package/dist/index.d.ts

@@ -1,6 +1,8 @@
 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 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';
 export { SURFACE_AGENT_FENCE_TAG, splitSurfaceAgentText, } from './agent-text.js';

package/dist/index.js

@@ -1,5 +1,6 @@
 export { SURFACE_LIMITS, SURFACE_SCHEMA_VERSION } from './types.js';
 export { validateSurfaceSpec } from './validation.js';
+export { projectInteractionRecord } 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

@@ -0,0 +1,17 @@
+import type { JsonObject } from './types.js';
+/**
+ * 用户在界面上主动触发的只读选择，不是 action、mutation 或授权凭据。
+ * 宿主自行决定是否把它变成后续操作（例如追加一条用户消息）。
+ */
+export interface SurfaceInteraction {
+    readonly type: 'select-record';
+    /** 只包含声明列的 JSON 安全值；不完整，也不能当作授权记录。 */
+    readonly record: JsonObject;
+}
+/** 渲染器补齐作用域后交给宿主的事件；宿主不得把这些字段写回渲染器。 */
+export interface SurfaceInteractionEvent extends SurfaceInteraction {
+    readonly surfaceId: string;
+    readonly widgetId: string;
+    readonly sourceId?: string;
+}
+export declare function projectInteractionRecord(record: JsonObject, fields: readonly string[]): JsonObject | null;

package/dist/interactions.js

@@ -0,0 +1,44 @@
+import { isJsonValue, jsonValueIssue } from './json.js';
+/**
+ * 只投影声明过的列，并跳过无法安全序列化的值（如 Date、函数、循环引用）。
+ * 嵌套对象和数组会深拷贝，宿主后续修改不会写回渲染器缓存。
+ * 返回 `null` 表示没有任何可交付字段，调用方不应发出事件。
+ *
+ * @param record 数据提供器返回的记录。
+ * @param fields 组件声明并已通过 policy 校验的字段。
+ * @returns 新的 JSON 对象，或 `null`。
+ */
+const dangerousKeys = new Set(['__proto__', 'constructor', 'prototype']);
+function detachJsonValue(value) {
+    if (typeof value !== 'object' || value === null)
+        return value;
+    if (Array.isArray(value))
+        return value.map((item) => detachJsonValue(item));
+    const copy = {};
+    for (const key of Object.keys(value)) {
+        if (dangerousKeys.has(key))
+            continue;
+        const descriptor = Object.getOwnPropertyDescriptor(value, key);
+        if (!descriptor || !('value' in descriptor))
+            continue;
+        const nested = descriptor.value;
+        if (!isJsonValue(nested))
+            continue;
+        copy[key] = detachJsonValue(nested);
+    }
+    return copy;
+}
+export function projectInteractionRecord(record, fields) {
+    const projected = {};
+    let included = 0;
+    for (const field of fields) {
+        if (dangerousKeys.has(field) || !Object.hasOwn(record, field))
+            continue;
+        const value = record[field];
+        if (value === undefined || jsonValueIssue(value) !== null)
+            continue;
+        projected[field] = detachJsonValue(value);
+        included += 1;
+    }
+    return included === 0 ? null : projected;
+}

package/dist/localization.d.ts

@@ -15,6 +15,7 @@ export interface SurfaceMessages {
     readonly tableInvalidData: string;
     readonly tableUnavailable: string;
     readonly tableEngineUnavailable: string;
+    readonly tableSelect?: string;
     readonly detailLoading?: string;
     readonly detailEmpty?: string;
     readonly detailUnavailable?: string;

package/dist/localization.js

@@ -14,6 +14,7 @@ const englishMessages = {
     tableInvalidData: 'Table data is invalid',
     tableUnavailable: 'Table data is unavailable',
     tableEngineUnavailable: 'The host has not configured the SVAR engine',
+    tableSelect: 'Select',
     detailLoading: 'Loading record',
     detailEmpty: 'No record',
     detailUnavailable: 'Record is unavailable',
@@ -43,6 +44,7 @@ const simplifiedChineseMessages = {
     tableInvalidData: '表格数据无效',
     tableUnavailable: '表格数据不可用',
     tableEngineUnavailable: '宿主尚未配置 SVAR 引擎',
+    tableSelect: '选择',
     detailLoading: '正在加载记录',
     detailEmpty: '暂无记录',
     detailUnavailable: '记录不可用',

package/package.json

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