@svadmin/surface 0.8.19 → 0.10.0

package/dist/catalog.js

@@ -3,8 +3,8 @@ import BarChartWidget from './components/BarChartWidget.svelte';
 import LineChartWidget from './components/LineChartWidget.svelte';
 import MetricWidget from './components/MetricWidget.svelte';
 import ResourceTableWidget from './components/ResourceTableWidget.svelte';
-import { barChartPropsSchema, lineChartPropsSchema, metricPropsSchema, resourceTablePropsSchema, } from './builtin-schemas.js';
-export const DEFAULT_SURFACE_CATALOG_VERSION = 'svadmin/v1';
+import { defaultSurfaceDefinitions, styledSurfaceDefinitions } from './builtin-definitions.js';
+export { DEFAULT_SURFACE_CATALOG_VERSION, STYLED_SURFACE_CATALOG_VERSION } from './builtin-definitions.js';
 export function defineSurfaceCatalog(catalog) {
     if (catalog.version.length === 0)
         throw new Error('Surface catalog version must not be empty');
@@ -13,49 +13,25 @@ export function defineSurfaceCatalog(catalog) {
         if (widgetTypes.has(widget.type))
             throw new Error(`Duplicate surface widget type "${widget.type}"`);
         widgetTypes.add(widget.type);
+        if ((widget.examples?.length ?? 0) > 3)
+            throw new Error('Catalog examples are limited to three per widget');
+        for (const example of widget.examples ?? []) {
+            if (!Value.Check(widget.propsSchema, example))
+                throw new Error('Invalid catalog example for ' + widget.type);
+        }
     }
     return catalog;
 }
-function tableFields(props) {
-    return Value.Decode(resourceTablePropsSchema, props).columns.map((column) => column.field);
+const components = {
+    metric: MetricWidget, 'resource-table': ResourceTableWidget, 'bar-chart': BarChartWidget, 'line-chart': LineChartWidget,
+};
+function rendered(definitions) {
+    return defineSurfaceCatalog({ ...definitions, widgets: definitions.widgets.map((widget) => {
+            const component = components[widget.type];
+            if (!component)
+                throw new Error(`Missing built-in component: ${widget.type}`);
+            return { ...widget, component };
+        }) });
 }
-function barChartFields(props) {
-    const chartProps = Value.Decode(barChartPropsSchema, props);
-    return [chartProps.labelField, chartProps.valueField];
-}
-function lineChartFields(props) {
-    const chartProps = Value.Decode(lineChartPropsSchema, props);
-    return [chartProps.labelField, chartProps.valueField];
-}
-export const defaultSurfaceCatalog = defineSurfaceCatalog({
-    version: DEFAULT_SURFACE_CATALOG_VERSION,
-    widgets: [
-        {
-            type: 'metric',
-            dataKind: 'scalar',
-            propsSchema: metricPropsSchema,
-            component: MetricWidget,
-        },
-        {
-            type: 'resource-table',
-            dataKind: 'items',
-            propsSchema: resourceTablePropsSchema,
-            getReferencedFields: tableFields,
-            component: ResourceTableWidget,
-        },
-        {
-            type: 'bar-chart',
-            dataKind: 'items',
-            propsSchema: barChartPropsSchema,
-            getReferencedFields: barChartFields,
-            component: BarChartWidget,
-        },
-        {
-            type: 'line-chart',
-            dataKind: 'items',
-            propsSchema: lineChartPropsSchema,
-            getReferencedFields: lineChartFields,
-            component: LineChartWidget,
-        },
-    ],
-});
+export const defaultSurfaceCatalog = rendered(defaultSurfaceDefinitions);
+export const styledSurfaceCatalog = rendered(styledSurfaceDefinitions);

package/dist/components/ActivityFeedWidget.svelte

@@ -0,0 +1,34 @@
+<script lang="ts">
+  import { Value } from '@sinclair/typebox/value';
+  import ActivityFeed from '@svadmin/ui/components/ActivityFeed.svelte';
+  import { activityFeedPropsSchema } from '../business-definitions.js';
+  import { asSurfaceActivities } from '../business-data.js';
+  import type { SurfaceWidgetRendererProps } from '../catalog.js';
+  import { surfaceMetric } from '../recipes.js';
+  import { formatSurfaceMessage, resolveSurfaceMessages } from '../localization.js';
+
+  let { props, data, locale = 'en-US', messages }: SurfaceWidgetRendererProps = $props();
+  const baseProps = $derived(Object.fromEntries(Object.entries(props).filter(([key]) => key !== 'appearance')));
+  const p = $derived(Value.Decode(activityFeedPropsSchema, baseProps));
+  const appearance = $derived(typeof props['appearance'] === 'object' && props['appearance'] !== null ? props['appearance'] as { tone?: typeof p.tone; density?: typeof p.density } : undefined);
+  const tone = $derived(appearance?.tone ?? p.tone ?? 'neutral');
+  const density = $derived(appearance?.density ?? p.density ?? 'comfortable');
+  const classes = $derived(surfaceMetric({ tone, density }));
+  const text = $derived(resolveSurfaceMessages(locale, messages));
+  const activities = $derived(data.status === 'ready' ? asSurfaceActivities(data.value, p, text.activityUnknownActor) : null);
+</script>
+
+<section class={classes.root + ' ' + classes.card} aria-label={p.title} data-surface-business="activity-feed" data-surface-density={density}>
+  {#if data.status === 'loading'}
+    <p role="status">{text.activityLoading}</p>
+  {:else if data.status === 'empty'}
+    <p role="status">{text.activityEmpty}</p>
+  {:else if data.status === 'error'}
+    <p role="alert">{text.activityUnavailable}</p>
+  {:else if activities?.ok}
+    <ActivityFeed activities={activities.value} allowComment={false} title={p.title} emptyLabel={text.activityEmpty}
+      countLabel={formatSurfaceMessage(text.activityCount, { count: activities.value.length })} />
+  {:else}
+    <p role="alert">{text.activityInvalidData}</p>
+  {/if}
+</section>

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

@@ -0,0 +1,4 @@
+import type { SurfaceWidgetRendererProps } from '../catalog.js';
+declare const ActivityFeedWidget: import("svelte").Component<SurfaceWidgetRendererProps, {}, "">;
+type ActivityFeedWidget = ReturnType<typeof ActivityFeedWidget>;
+export default ActivityFeedWidget;

package/dist/components/MetricWidget.svelte

@@ -1,7 +1,9 @@
 <script lang="ts">
   import { Value } from '@sinclair/typebox/value';
+  import { surfaceMetric } from '../recipes.js';
+  import '../styles.css';
   import StatsCard from '@svadmin/ui/components/StatsCard.svelte';
-  import { metricPropsSchema } from '../builtin-schemas.js';
+  import { styledMetricPropsSchema as metricPropsSchema } from '../builtin-schemas.js';
   import type { SurfaceWidgetRendererProps } from '../catalog.js';
   import { resolveSurfaceMessages } from '../localization.js';
 
@@ -9,6 +11,8 @@
   const activeMessages = $derived(resolveSurfaceMessages(locale, messages));
 
   const metricProps = $derived(Value.Decode(metricPropsSchema, props));
+  const metricClasses = $derived(metricProps.tone !== undefined || metricProps.density !== undefined
+    ? surfaceMetric({ tone: metricProps.tone, density: metricProps.density }) : undefined);
   const formattedValue = $derived.by(() => {
     if (data.status !== 'ready') return '—';
     const value = data.value;
@@ -26,17 +30,17 @@
   });
 </script>
 
-<article aria-labelledby="{widgetId}-label" aria-busy={data.status === 'loading'}>
+<article class={metricClasses?.root} data-surface-tone={metricProps.tone} data-surface-density={metricProps.density} aria-labelledby="{widgetId}-label" aria-busy={data.status === 'loading'}>
   <span id="{widgetId}-label" class="visually-hidden">{metricProps.label}</span>
   {#if data.status === 'loading'}
-    <StatsCard label={metricProps.label} value="" loading />
+    <StatsCard class={metricClasses?.card ?? ''} label={metricProps.label} value="" loading />
   {:else if data.status === 'ready' && typeof data.value === 'number'}
-    <StatsCard label={metricProps.label} value={formattedValue} />
+    <StatsCard class={metricClasses?.card ?? ''} label={metricProps.label} value={formattedValue} />
     {#if metricProps.description}
-      <p class="metric-description">{metricProps.description}</p>
+      <p class={"metric-description " + (metricClasses?.description ?? "")}>{metricProps.description}</p>
     {/if}
   {:else}
-    <div class="metric-state" role={data.status === 'error' ? 'alert' : 'status'}>
+    <div class={"metric-state " + (metricClasses?.state ?? "")} role={data.status === 'error' ? 'alert' : 'status'}>
       <strong>{metricProps.label}</strong>
       <span>{data.status === 'error' ? data.error.message : data.status === 'empty' ? activeMessages.metricNoData : activeMessages.metricInvalidData}</span>
     </div>
@@ -65,9 +69,10 @@
   .metric-state {
     display: grid;
     gap: 0.35rem;
-    min-height: 6rem;
-    padding: 1.25rem;
+    min-height: var(--svadmin-metric-state-height, 6rem);
+    padding: var(--svadmin-metric-state-padding, 1.25rem);
     border: 1px solid var(--border);
+    border-inline-start: var(--svadmin-metric-state-border-width, 1px) solid var(--svadmin-metric-state-accent, var(--border));
     border-radius: 0.75rem;
     background: var(--card);
     color: var(--muted-foreground);

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

@@ -1,3 +1,4 @@
+import '../styles.css';
 import type { SurfaceWidgetRendererProps } from '../catalog.js';
 declare const MetricWidget: import("svelte").Component<SurfaceWidgetRendererProps, {}, "">;
 type MetricWidget = ReturnType<typeof MetricWidget>;

package/dist/components/ResourceDetailWidget.svelte

@@ -0,0 +1,56 @@
+<script lang="ts">
+  import { Value } from '@sinclair/typebox/value';
+  import Card from '@svadmin/ui/components/ui/card/card.svelte';
+  import CardHeader from '@svadmin/ui/components/ui/card/card-header.svelte';
+  import CardTitle from '@svadmin/ui/components/ui/card/card-title.svelte';
+  import CardContent from '@svadmin/ui/components/ui/card/card-content.svelte';
+  import { resourceDetailPropsSchema } from '../business-definitions.js';
+  import type { SurfaceWidgetRendererProps } from '../catalog.js';
+  import type { JsonObject } from '../types.js';
+  import { surfaceMetric } from '../recipes.js';
+  import { resolveSurfaceMessages } from '../localization.js';
+  import { displayTableValue } from '../widget-data.js';
+
+  let { props, data, locale = 'en-US', messages }: SurfaceWidgetRendererProps = $props();
+  const baseProps = $derived(Object.fromEntries(Object.entries(props).filter(([key]) => key !== 'appearance')));
+  const p = $derived(Value.Decode(resourceDetailPropsSchema, baseProps));
+  const appearance = $derived(typeof props['appearance'] === 'object' && props['appearance'] !== null ? props['appearance'] as { tone?: typeof p.tone; density?: typeof p.density } : undefined);
+  const tone = $derived(appearance?.tone ?? p.tone ?? 'neutral');
+  const density = $derived(appearance?.density ?? p.density ?? 'comfortable');
+  const classes = $derived(surfaceMetric({ tone, density }));
+  const text = $derived(resolveSurfaceMessages(locale, messages));
+  const record = $derived(data.status === 'ready' && data.value !== null && typeof data.value === 'object' && !Array.isArray(data.value)
+    ? data.value as JsonObject : null);
+</script>
+
+<Card class={classes.root + ' ' + classes.card} data-surface-business="resource-detail" data-surface-density={density}>
+  <CardHeader><CardTitle>{p.title}</CardTitle></CardHeader>
+  <CardContent>
+    {#if data.status === 'loading'}
+      <p role="status">{text.detailLoading}</p>
+    {:else if data.status === 'empty'}
+      <p role="status">{text.detailEmpty}</p>
+    {:else if data.status === 'error'}
+      <p role="alert">{text.detailUnavailable}</p>
+    {:else if record}
+      <dl aria-label={p.title} data-density={density}>
+        {#each p.fields as item, index (`${index}:${item.field}`)}
+          <div>
+            <dt>{item.label}</dt>
+            <dd>{displayTableValue(record[item.field], { format: item.format, locale, messages: text })}</dd>
+          </div>
+        {/each}
+      </dl>
+    {:else}
+      <p role="alert">{text.detailInvalidData}</p>
+    {/if}
+  </CardContent>
+</Card>
+
+<style>
+  dl { display: grid; gap: 1rem; margin: 0; grid-template-columns: repeat(auto-fit, minmax(min(100%, 12rem), 1fr)); }
+  dl > div { min-width: 0; }
+  dt { color: var(--muted-foreground); font-size: .8125rem; }
+  dd { margin: .25rem 0 0; color: var(--foreground); overflow-wrap: anywhere; font-variant-numeric: tabular-nums; }
+  dl[data-density='compact'] { gap: .5rem; }
+</style>

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

@@ -0,0 +1,4 @@
+import type { SurfaceWidgetRendererProps } from '../catalog.js';
+declare const ResourceDetailWidget: import("svelte").Component<SurfaceWidgetRendererProps, {}, "">;
+type ResourceDetailWidget = ReturnType<typeof ResourceDetailWidget>;
+export default ResourceDetailWidget;

package/dist/components/ResourceFormBody.svelte

@@ -0,0 +1,97 @@
+<script lang="ts">
+  import { onDestroy, untrack } from 'svelte';
+  import { Value } from '@sinclair/typebox/value';
+  import JsonSchemaForm from '@svadmin/ui/components/JsonSchemaForm.svelte';
+  import { createSurfaceFormController, type SurfaceWorkflowClientState } from '../workflows/client.js';
+  import type { SurfaceWorkflowHost } from '../workflows/context.js';
+  import type { SurfaceActionDescriptor } from '../workflows/types.js';
+  import type { JsonObject } from '../types.js';
+  import { editorClasses, editorButtonClasses } from '../styles/editor.js';
+  import '../styles/editor.css';
+  let { widgetId, host, action, title, locale }: {
+    widgetId: string; host: SurfaceWorkflowHost; action: SurfaceActionDescriptor; title: string; locale: string;
+  } = $props();
+  const instanceId = $props.id();
+  let value = $state<Record<string, unknown>>({});
+  let formState = $state<SurfaceWorkflowClientState>({ busy: false });
+  let errors = $state<string[]>([]);
+  const schema = $derived(JSON.parse(JSON.stringify(action.inputSchema)));
+  const zh = $derived(locale.startsWith('zh'));
+  const labels = $derived(zh ? {
+    submit: '提交操作提案', confirm: '确认这些参数', execute: '执行已批准操作', refresh: '查询状态', reject: '取消提案', reset: '开始新操作',
+    disabled: '预览模式：业务操作尚未启用', pending: '等待确认或独立审批', approved: '已批准，尚未执行',
+    executing: '正在执行，请勿重复提交', succeeded: '操作已完成', indeterminate: '结果不明确，需要服务端核对，禁止直接重试', rejected: '提案已取消',
+    error: '操作未完成。请先查询状态，避免重复执行。', args: '待确认参数',
+  } : {
+    submit: 'Propose action', confirm: 'Confirm these arguments', execute: 'Execute approved action', refresh: 'Check status', reject: 'Cancel proposal', reset: 'Start another action',
+    disabled: 'Preview mode: business actions are disabled', pending: 'Waiting for confirmation or independent approval', approved: 'Approved; not yet executed',
+    executing: 'Executing; do not submit again', succeeded: 'Action completed', indeterminate: 'Outcome unknown; server reconciliation is required before retry', rejected: 'Proposal cancelled',
+    error: 'Operation did not complete. Check status before retrying.', args: 'Arguments to confirm',
+  });
+  const scope = $derived(host.getScope());
+  const controller = untrack(() => createSurfaceFormController({ action, getScope: host.getScope,
+    onState: (next) => { formState = next; }, onCommitted: host.committed }));
+  let identity: readonly unknown[] = [];
+  $effect.pre(() => {
+    const next = [scope.scopeKey, scope.surfaceId, scope.revision, scope.transport, scope.enabled];
+    untrack(() => {
+      if (identity.length && next.some((part, index) => part !== identity[index])) {
+        controller.reset();
+        value = {};
+        errors = [];
+      }
+      identity = next;
+    });
+  });
+  onDestroy(() => controller.dispose());
+  async function submit(input: Record<string, unknown>) {
+    // Optional cleared fields may be undefined in a bound form; omission is the
+    // wire representation. The server repeats JSON and schema validation.
+    const args: unknown = JSON.parse(JSON.stringify(input));
+    if (!Value.Check(action.inputSchema, args)) {
+      errors = [...Value.Errors(action.inputSchema, args)].slice(0, 12).map((error) => `${error.path}: ${error.message}`);
+      return;
+    }
+    errors = [];
+    await controller.submit(args as JsonObject);
+  }
+</script>
+
+<section class="svadmin-surface-editor {editorClasses.comfortable}" aria-labelledby="{instanceId}-form-title" aria-busy={formState.busy}>
+  <h3 id="{instanceId}-form-title">{title}</h3>
+  {#if !scope.enabled}<p role="status">{labels.disabled}</p>{/if}
+  {#if errors.length}
+    <div role="alert"><ul>{#each errors as error, index (`${index}:${error}`)}<li>{error}</li>{/each}</ul></div>
+  {/if}
+  <fieldset disabled={!scope.enabled || formState.busy || !!formState.proposal} class="form-fields">
+    <JsonSchemaForm {schema} {locale} bind:value onsubmit={submit} submitText={labels.submit} idPrefix={`surface-${widgetId}-${instanceId}`} />
+  </fieldset>
+  {#if formState.error}<p role="alert">{labels.error}</p>{/if}
+  {#if formState.proposal}
+    {@const p = formState.proposal}
+    <section aria-label={p.actionLabel}>
+      <p role="status" data-workflow-status={p.status}>{labels[p.status]}</p>
+      <strong>{p.actionLabel}</strong>
+      <details><summary>{labels.args}</summary><pre>{JSON.stringify(p.args, null, 2)}</pre></details>
+      <div data-part="actions">
+        {#if p.status === 'pending' && p.approval === 'confirm'}
+          <button class={editorButtonClasses.secondary} disabled={formState.busy || !scope.enabled} onclick={() => controller.confirm()}>{labels.confirm}</button>
+        {/if}
+        {#if p.status === 'approved'}
+          <button class={editorButtonClasses.primary} disabled={formState.busy || !scope.enabled} onclick={() => controller.execute()}>{labels.execute}</button>
+        {/if}
+        <button class={editorButtonClasses.secondary} disabled={formState.busy || !scope.enabled} onclick={() => controller.refresh()}>{labels.refresh}</button>
+        {#if p.status === 'pending' || p.status === 'approved'}
+          <button class={editorButtonClasses.secondary} disabled={formState.busy || !scope.enabled} onclick={() => controller.reject()}>{labels.reject}</button>
+        {:else if p.status === 'succeeded' || p.status === 'rejected'}
+          <button class={editorButtonClasses.secondary} disabled={formState.busy} onclick={() => controller.reset()}>{labels.reset}</button>
+        {/if}
+      </div>
+    </section>
+  {/if}
+</section>
+
+<style>
+  .form-fields { border: 0; padding: 0; margin: 0; min-width: 0; }
+  pre { white-space: pre-wrap; overflow-wrap: anywhere; max-height: 16rem; overflow: auto; }
+</style>

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

@@ -0,0 +1,13 @@
+import type { SurfaceWorkflowHost } from '../workflows/context.js';
+import type { SurfaceActionDescriptor } from '../workflows/types.js';
+import '../styles/editor.css';
+type $$ComponentProps = {
+    widgetId: string;
+    host: SurfaceWorkflowHost;
+    action: SurfaceActionDescriptor;
+    title: string;
+    locale: string;
+};
+declare const ResourceFormBody: import("svelte").Component<$$ComponentProps, {}, "">;
+type ResourceFormBody = ReturnType<typeof ResourceFormBody>;
+export default ResourceFormBody;

package/dist/components/ResourceFormWidget.svelte

@@ -0,0 +1,19 @@
+<script lang="ts">
+  import type { SurfaceWidgetRendererProps } from '../catalog.js';
+  import { getSurfaceWorkflowHost } from '../workflows/context.js';
+  import ResourceFormBody from './ResourceFormBody.svelte';
+  let { widgetId, props, locale = 'en-US' }: SurfaceWidgetRendererProps = $props();
+  const host = getSurfaceWorkflowHost();
+  const action = $derived(host?.getAction(String(props['actionId'])));
+  const zh = $derived(locale.startsWith('zh'));
+</script>
+
+{#if host && action}
+  {#key `${action.id}:${action.version}`}
+    <ResourceFormBody {widgetId} {host} {action} title={typeof props['title'] === 'string' ? props['title'] : action.label} {locale} />
+  {/key}
+{:else}
+  <section role="status" data-surface-form-unavailable>
+    {zh ? '该表单尚未连接到已授权的业务操作。' : 'This form is not connected to an authorized business action.'}
+  </section>
+{/if}

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

@@ -0,0 +1,4 @@
+import type { SurfaceWidgetRendererProps } from '../catalog.js';
+declare const ResourceFormWidget: import("svelte").Component<SurfaceWidgetRendererProps, {}, "">;
+type ResourceFormWidget = ReturnType<typeof ResourceFormWidget>;
+export default ResourceFormWidget;

package/dist/components/ResourceTableWidget.svelte

@@ -1,5 +1,7 @@
 <script lang="ts">
   import { Value } from '@sinclair/typebox/value';
+  import { surfaceTable } from '../recipes.js';
+  import '../styles.css';
   import CardContent from '@svadmin/ui/components/ui/card/card-content.svelte';
   import CardHeader from '@svadmin/ui/components/ui/card/card-header.svelte';
   import CardTitle from '@svadmin/ui/components/ui/card/card-title.svelte';
@@ -10,7 +12,7 @@
   import TableHeader from '@svadmin/ui/components/ui/table/table-header.svelte';
   import TableRow from '@svadmin/ui/components/ui/table/table-row.svelte';
   import Table from '@svadmin/ui/components/ui/table/table.svelte';
-  import { resourceTablePropsSchema } from '../builtin-schemas.js';
+  import { styledResourceTablePropsSchema as resourceTablePropsSchema } from '../builtin-schemas.js';
   import type { SurfaceWidgetRendererProps } from '../catalog.js';
   import { resolveSurfaceMessages } from '../localization.js';
   import { asRecordArray, displayTableValue } from '../widget-data.js';
@@ -19,27 +21,28 @@
   const activeMessages = $derived(resolveSurfaceMessages(locale, messages));
 
   const tableProps = $derived(Value.Decode(resourceTablePropsSchema, props));
+  const tableClasses = $derived(tableProps.density === undefined ? undefined : surfaceTable({ density: tableProps.density }));
   const records = $derived(data.status === 'ready' ? asRecordArray(data.value) : null);
 </script>
 
-<Card>
-  <CardHeader>
+<Card class={tableClasses?.root} data-surface-density={tableProps.density}>
+  <CardHeader class={tableClasses?.header}>
     <CardTitle>{tableProps.title}</CardTitle>
   </CardHeader>
-  <CardContent>
+  <CardContent class={tableClasses?.content}>
     {#if data.status === 'loading'}
-      <div class="table-state table-loading" role="status">{activeMessages.tableLoading}</div>
+      <div class={"table-state table-loading " + (tableClasses?.state ?? "")} role="status">{activeMessages.tableLoading}</div>
     {:else if data.status === 'empty'}
-      <p class="table-state" role="status">{tableProps.emptyLabel ?? activeMessages.tableNoRecords}</p>
+      <p class={"table-state " + (tableClasses?.state ?? "")} role="status">{tableProps.emptyLabel ?? activeMessages.tableNoRecords}</p>
     {:else if data.status === 'error'}
-      <p class="table-state" role="alert">{data.error.message}</p>
+      <p class={"table-state " + (tableClasses?.state ?? "")} role="alert">{data.error.message}</p>
     {:else if data.status === 'ready' && records?.ok}
       <div class="surface-table">
-        <Table aria-label={tableProps.title}>
+        <Table density={tableProps.density ?? "comfortable"} aria-label={tableProps.title}>
           <TableHeader>
             <TableRow>
               {#each tableProps.columns as column (column.field)}
-                <TableHead scope="col">{column.label}</TableHead>
+                <TableHead class={tableClasses?.head} scope="col">{column.label}</TableHead>
               {/each}
             </TableRow>
           </TableHeader>
@@ -47,7 +50,7 @@
             {#each records.value as record, index (index)}
               <TableRow>
                 {#each tableProps.columns as column (column.field)}
-                  <TableCell>{displayTableValue(record[column.field], {
+                  <TableCell class={tableClasses?.cell}>{displayTableValue(record[column.field], {
                     format: column.format,
                     locale,
                     messages: activeMessages,
@@ -59,7 +62,7 @@
         </Table>
       </div>
     {:else}
-      <p class="table-state" role="alert">{records && !records.ok ? activeMessages.tableInvalidData : activeMessages.tableUnavailable}</p>
+      <p class={"table-state " + (tableClasses?.state ?? "")} role="alert">{records && !records.ok ? activeMessages.tableInvalidData : activeMessages.tableUnavailable}</p>
     {/if}
   </CardContent>
 </Card>
@@ -67,7 +70,7 @@
 <style>
   .table-state {
     display: grid;
-    min-height: 8rem;
+    min-height: var(--svadmin-table-state-height, 8rem);
     margin: 0;
     place-items: center;
     color: var(--muted-foreground);

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

@@ -1,3 +1,4 @@
+import '../styles.css';
 import type { SurfaceWidgetRendererProps } from '../catalog.js';
 declare const ResourceTableWidget: import("svelte").Component<SurfaceWidgetRendererProps, {}, "">;
 type ResourceTableWidget = ReturnType<typeof ResourceTableWidget>;

package/dist/components/SurfaceEditPreview.svelte

@@ -0,0 +1,107 @@
+<script lang="ts">
+  import { useTranslation } from '@svadmin/core/i18n';
+  import { applySurfaceEditProposal } from '../edits.js';
+  import type { SurfaceRevision } from '../edits.js';
+  import { defaultSurfaceCatalog } from '../catalog.js';
+  import type { SurfaceRenderCatalog } from '../catalog.js';
+  import type { SurfaceDataProvider, SurfacePolicy } from '../types.js';
+  import SurfaceRenderer from './SurfaceRenderer.svelte';
+  import { editorClasses, editorButtonClasses } from '../styles/editor.js';
+  import '../styles/editor.css';
+
+  export interface SurfaceEditPreviewProps {
+    readonly revision: SurfaceRevision;
+    readonly proposal?: unknown;
+    readonly streaming?: boolean;
+    readonly policy: SurfacePolicy;
+    readonly catalog?: SurfaceRenderCatalog;
+    readonly dataProvider?: SurfaceDataProvider;
+    readonly scopeKey?: string;
+    readonly locale?: string;
+    readonly density?: 'compact' | 'comfortable';
+    /** 用户确认后返回候选快照。宿主负责持久化 CAS 与服务端授权。 */
+    readonly onApply?: (candidate: SurfaceRevision) => void | Promise<void>;
+  }
+
+  let {
+    revision, proposal, streaming = false, policy, catalog = defaultSurfaceCatalog,
+    dataProvider, scopeKey = '', locale, density = 'comfortable', onApply,
+  }: SurfaceEditPreviewProps = $props();
+  const i18n = useTranslation();
+  const activeLocale = $derived(locale ?? i18n.locale);
+  const labels = $derived(activeLocale.startsWith('zh') ? {
+    title: '界面修改提案', current: '当前版本', preview: '预览修改', back: '返回当前',
+    apply: '确认应用', loading: '正在接收提案；当前界面保持不变', empty: '尚无修改提案',
+    invalid: '提案未通过校验，不能应用', ready: '提案已校验，尚未应用',
+    previewing: '正在预览，尚未应用', applying: '正在应用', failed: '应用失败，请重新确认后重试',
+    readonly: '当前宿主未配置应用操作',
+  } : {
+    title: 'Surface edit proposal', current: 'Current revision', preview: 'Preview changes', back: 'Back to current',
+    apply: 'Apply changes', loading: 'Receiving proposal; current surface is unchanged', empty: 'No edit proposal',
+    invalid: 'Proposal is invalid and cannot be applied', ready: 'Validated proposal; not applied',
+    previewing: 'Preview only; not applied', applying: 'Applying changes', failed: 'Application failed; confirm again to retry',
+    readonly: 'No apply handler is configured',
+  });
+  const candidate = $derived(streaming || proposal === undefined || proposal === null || proposal === ''
+    ? null : applySurfaceEditProposal(revision, proposal, catalog, policy));
+  const candidateKey = $derived(candidate?.ok ? JSON.stringify([scopeKey, candidate.value]) : '');
+  let selectedPreview = $state('');
+  let applying = $state(false);
+  let failureKey = $state('');
+  const previewing = $derived(candidateKey !== '' && selectedPreview === candidateKey && !streaming);
+  const visibleSpec = $derived(previewing && candidate?.ok ? candidate.value.spec : revision.spec);
+  const status = $derived(streaming ? labels.loading : applying ? labels.applying : candidate === null
+    ? labels.empty : !candidate.ok ? labels.invalid : previewing ? labels.previewing : labels.ready);
+
+  async function apply(): Promise<void> {
+    if (streaming || applying || !onApply) return;
+    // 点击时使用最新 revision/policy 重新校验，不复用旧预览作为权限凭据。
+    const latest = applySurfaceEditProposal(revision, proposal, catalog, policy);
+    if (!latest.ok) return;
+    const submittedKey = candidateKey;
+    applying = true;
+    failureKey = '';
+    try {
+      await onApply(latest.value);
+      selectedPreview = '';
+    } catch {
+      failureKey = submittedKey;
+    } finally {
+      applying = false;
+    }
+  }
+</script>
+
+<section class="svadmin-surface-editor {editorClasses[density]}" aria-label={labels.title} data-density={density}>
+  <div data-part="toolbar">
+    <div>
+      <h3 data-part="title">{labels.title}</h3>
+      <p data-part="status" role="status" aria-live="polite">{status} · {labels.current} {revision.revision}</p>
+    </div>
+    <div data-part="actions">
+      <button type="button" class={editorButtonClasses.secondary}
+        disabled={streaming || applying || !candidate?.ok} aria-pressed={previewing}
+        onclick={() => { selectedPreview = previewing ? '' : candidateKey; }}
+      >{previewing ? labels.back : labels.preview}</button>
+      <button type="button" class={editorButtonClasses.primary}
+        disabled={streaming || applying || !candidate?.ok || !onApply}
+        title={onApply ? undefined : labels.readonly} onclick={apply}
+      >{applying ? labels.applying : labels.apply}</button>
+    </div>
+  </div>
+  {#if candidate && !candidate.ok}
+    <div data-part="error" role="alert">
+      {labels.invalid}
+      <ul>{#each candidate.issues as issue, index (`${issue.code}:${issue.path}:${index}`)}
+        <li><code>{issue.code}</code>: {issue.message}</li>
+      {/each}</ul>
+    </div>
+  {/if}
+  {#if failureKey !== '' && failureKey === candidateKey}
+    <div data-part="error" role="alert">{labels.failed}</div>
+  {/if}
+  <div data-part="viewport" data-preview={previewing}>
+    <SurfaceRenderer spec={visibleSpec} {policy} {catalog} {scopeKey} locale={activeLocale}
+      {...(dataProvider === undefined ? {} : { dataProvider })} />
+  </div>
+</section>

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

@@ -0,0 +1,20 @@
+import type { SurfaceRevision } from '../edits.js';
+import type { SurfaceRenderCatalog } from '../catalog.js';
+import type { SurfaceDataProvider, SurfacePolicy } from '../types.js';
+import '../styles/editor.css';
+export interface SurfaceEditPreviewProps {
+    readonly revision: SurfaceRevision;
+    readonly proposal?: unknown;
+    readonly streaming?: boolean;
+    readonly policy: SurfacePolicy;
+    readonly catalog?: SurfaceRenderCatalog;
+    readonly dataProvider?: SurfaceDataProvider;
+    readonly scopeKey?: string;
+    readonly locale?: string;
+    readonly density?: 'compact' | 'comfortable';
+    /** 用户确认后返回候选快照。宿主负责持久化 CAS 与服务端授权。 */
+    readonly onApply?: (candidate: SurfaceRevision) => void | Promise<void>;
+}
+declare const SurfaceEditPreview: import("svelte").Component<SurfaceEditPreviewProps, {}, "">;
+type SurfaceEditPreview = ReturnType<typeof SurfaceEditPreview>;
+export default SurfaceEditPreview;