@svadmin/surface 0.7.1 → 0.8.0

package/README.md

@@ -78,6 +78,17 @@ import {
 
 When rendered inside `AdminApp`, the renderer resolves the configured provider for each resource. A trusted host may instead pass `dataProvider`, which is still narrowed to `getList` and `getOne`.
 
+The renderer also follows the active `AdminApp` i18n locale. Built-in loading, empty, error, boolean, number, currency, percent, and date presentation updates automatically. A standalone host can pass `locale`, and can override individual built-in strings with `messages`. Business copy such as the surface title, widget titles, labels, and column headers remains part of the JSON spec; build or select a localized spec when the host locale changes.
+
+```svelte
+<SurfaceRenderer
+  {spec}
+  {policy}
+  locale="zh-CN"
+  messages={{ tableNoRecords: '没有符合条件的记录' }}
+/>
+```
+
 ## AI proposals
 
 The DOM-free root entry also exposes an opt-in Agent protocol. `buildSurfaceAgentPrompt()` constrains a model to return a proposal envelope and includes the host's widget/resource/field allowlists. `parseSurfaceAgentProposal()` parses and validates the complete `SurfaceSpec` against the same catalog and policy without querying a provider:

package/compatibility.json

@@ -1,5 +1,5 @@
 {
-  "surface": "0.7.x",
+  "surface": "0.8.x",
   "minimumSupported": {
     "@svadmin/core": "0.34.2",
     "@svadmin/ui": "0.40.6",

package/dist/catalog.d.ts

@@ -1,10 +1,13 @@
 import type { Component } from 'svelte';
 import type { JsonObject, SurfaceCatalog, SurfaceWidgetDataState, SurfaceWidgetDefinition } from './types.js';
+import type { SurfaceMessages } from './localization.js';
 export declare const DEFAULT_SURFACE_CATALOG_VERSION: "svadmin/v1";
 export interface SurfaceWidgetRendererProps {
     readonly widgetId: string;
     readonly props: JsonObject;
     readonly data: SurfaceWidgetDataState;
+    readonly locale?: string;
+    readonly messages?: SurfaceMessages;
 }
 export interface SurfaceWidgetRegistration extends SurfaceWidgetDefinition {
     readonly component: Component<SurfaceWidgetRendererProps>;

package/dist/components/BarChartWidget.svelte

@@ -7,16 +7,18 @@
   import Card from '@svadmin/ui/components/ui/card/card.svelte';
   import { barChartPropsSchema } from '../builtin-schemas.js';
   import type { SurfaceWidgetRendererProps } from '../catalog.js';
+  import { formatSurfaceMessage, resolveSurfaceMessages } from '../localization.js';
   import { asChartPoints, compactChartLabel } from '../widget-data.js';
 
-  let { props, data }: SurfaceWidgetRendererProps = $props();
+  let { props, data, locale = 'en-US', messages }: SurfaceWidgetRendererProps = $props();
+  const activeMessages = $derived(resolveSurfaceMessages(locale, messages));
 
   const chartProps = $derived(Value.Decode(barChartPropsSchema, props));
   const points = $derived(data.status === 'ready'
     ? asChartPoints(data.value, chartProps.labelField, chartProps.valueField)
     : null);
   const chartData = $derived(points?.ok
-    ? points.value.map((point) => ({ ...point, label: compactChartLabel(point.label, 12) }))
+    ? points.value.map((point) => ({ ...point, label: compactChartLabel(point.label, 12, locale) }))
     : []);
 </script>
 
@@ -26,9 +28,9 @@
   </CardHeader>
   <CardContent>
     {#if data.status === 'loading'}
-      <div class="chart-state chart-loading" role="status" aria-label="Loading {chartProps.title}"></div>
+      <div class="chart-state chart-loading" role="status" aria-label={formatSurfaceMessage(activeMessages.chartLoading, { title: chartProps.title })}></div>
     {:else if data.status === 'empty'}
-      <p class="chart-state" role="status">No chart data</p>
+      <p class="chart-state" role="status">{activeMessages.chartNoData}</p>
     {:else if data.status === 'error'}
       <p class="chart-state" role="alert">{data.error.message}</p>
     {:else if data.status === 'ready' && points?.ok}
@@ -36,7 +38,7 @@
         <BarChart data={chartData} showValues={chartProps.showValues ?? true} />
       </div>
     {:else}
-      <p class="chart-state" role="alert">{points && !points.ok ? points.message : 'Chart data is unavailable'}</p>
+      <p class="chart-state" role="alert">{points && !points.ok ? activeMessages.chartInvalidData : activeMessages.chartUnavailable}</p>
     {/if}
   </CardContent>
 </Card>

package/dist/components/LineChartWidget.svelte

@@ -7,16 +7,18 @@
   import Card from '@svadmin/ui/components/ui/card/card.svelte';
   import { lineChartPropsSchema } from '../builtin-schemas.js';
   import type { SurfaceWidgetRendererProps } from '../catalog.js';
+  import { formatSurfaceMessage, resolveSurfaceMessages } from '../localization.js';
   import { asChartPoints, compactChartLabel } from '../widget-data.js';
 
-  let { props, data }: SurfaceWidgetRendererProps = $props();
+  let { props, data, locale = 'en-US', messages }: SurfaceWidgetRendererProps = $props();
+  const activeMessages = $derived(resolveSurfaceMessages(locale, messages));
 
   const chartProps = $derived(Value.Decode(lineChartPropsSchema, props));
   const points = $derived(data.status === 'ready'
     ? asChartPoints(data.value, chartProps.labelField, chartProps.valueField)
     : null);
   const chartData = $derived(points?.ok
-    ? points.value.map((point) => ({ ...point, label: compactChartLabel(point.label, 8) }))
+    ? points.value.map((point) => ({ ...point, label: compactChartLabel(point.label, 8, locale) }))
     : []);
 </script>
 
@@ -26,9 +28,9 @@
   </CardHeader>
   <CardContent>
     {#if data.status === 'loading'}
-      <div class="chart-state chart-loading" role="status" aria-label="Loading {chartProps.title}"></div>
+      <div class="chart-state chart-loading" role="status" aria-label={formatSurfaceMessage(activeMessages.chartLoading, { title: chartProps.title })}></div>
     {:else if data.status === 'empty'}
-      <p class="chart-state" role="status">No chart data</p>
+      <p class="chart-state" role="status">{activeMessages.chartNoData}</p>
     {:else if data.status === 'error'}
       <p class="chart-state" role="alert">{data.error.message}</p>
     {:else if data.status === 'ready' && points?.ok}
@@ -40,7 +42,7 @@
         />
       </div>
     {:else}
-      <p class="chart-state" role="alert">{points && !points.ok ? points.message : 'Chart data is unavailable'}</p>
+      <p class="chart-state" role="alert">{points && !points.ok ? activeMessages.chartInvalidData : activeMessages.chartUnavailable}</p>
     {/if}
   </CardContent>
 </Card>

package/dist/components/MetricWidget.svelte

@@ -3,8 +3,10 @@
   import StatsCard from '@svadmin/ui/components/StatsCard.svelte';
   import { metricPropsSchema } from '../builtin-schemas.js';
   import type { SurfaceWidgetRendererProps } from '../catalog.js';
+  import { resolveSurfaceMessages } from '../localization.js';
 
-  let { widgetId, props, data }: SurfaceWidgetRendererProps = $props();
+  let { widgetId, props, data, locale = 'en-US', messages }: SurfaceWidgetRendererProps = $props();
+  const activeMessages = $derived(resolveSurfaceMessages(locale, messages));
 
   const metricProps = $derived(Value.Decode(metricPropsSchema, props));
   const formattedValue = $derived.by(() => {
@@ -12,15 +14,15 @@
     const value = data.value;
     if (typeof value !== 'number') return '—';
     if (metricProps.format === 'currency') {
-      return new Intl.NumberFormat('en-US', {
+      return new Intl.NumberFormat(locale, {
         style: 'currency',
         currency: metricProps.currency,
       }).format(value);
     }
     if (metricProps.format === 'percent') {
-      return new Intl.NumberFormat('en-US', { style: 'percent', maximumFractionDigits: 1 }).format(value);
+      return new Intl.NumberFormat(locale, { style: 'percent', maximumFractionDigits: 1 }).format(value);
     }
-    return new Intl.NumberFormat('en-US', { maximumFractionDigits: 2 }).format(value);
+    return new Intl.NumberFormat(locale, { maximumFractionDigits: 2 }).format(value);
   });
 </script>
 
@@ -36,7 +38,7 @@
   {:else}
     <div class="metric-state" role={data.status === 'error' ? 'alert' : 'status'}>
       <strong>{metricProps.label}</strong>
-      <span>{data.status === 'error' ? data.error.message : data.status === 'empty' ? 'No data' : 'Metric data is invalid'}</span>
+      <span>{data.status === 'error' ? data.error.message : data.status === 'empty' ? activeMessages.metricNoData : activeMessages.metricInvalidData}</span>
     </div>
   {/if}
 </article>

package/dist/components/ResourceTableWidget.svelte

@@ -12,9 +12,11 @@
   import Table from '@svadmin/ui/components/ui/table/table.svelte';
   import { resourceTablePropsSchema } from '../builtin-schemas.js';
   import type { SurfaceWidgetRendererProps } from '../catalog.js';
+  import { resolveSurfaceMessages } from '../localization.js';
   import { asRecordArray, displayTableValue } from '../widget-data.js';
 
-  let { props, data }: SurfaceWidgetRendererProps = $props();
+  let { props, data, locale = 'en-US', messages }: SurfaceWidgetRendererProps = $props();
+  const activeMessages = $derived(resolveSurfaceMessages(locale, messages));
 
   const tableProps = $derived(Value.Decode(resourceTablePropsSchema, props));
   const records = $derived(data.status === 'ready' ? asRecordArray(data.value) : null);
@@ -26,9 +28,9 @@
   </CardHeader>
   <CardContent>
     {#if data.status === 'loading'}
-      <div class="table-state table-loading" role="status">Loading table</div>
+      <div class="table-state table-loading" role="status">{activeMessages.tableLoading}</div>
     {:else if data.status === 'empty'}
-      <p class="table-state" role="status">{tableProps.emptyLabel ?? 'No records'}</p>
+      <p class="table-state" role="status">{tableProps.emptyLabel ?? activeMessages.tableNoRecords}</p>
     {:else if data.status === 'error'}
       <p class="table-state" role="alert">{data.error.message}</p>
     {:else if data.status === 'ready' && records?.ok}
@@ -45,7 +47,11 @@
             {#each records.value as record, index (index)}
               <TableRow>
                 {#each tableProps.columns as column (column.field)}
-                  <TableCell>{displayTableValue(record[column.field], column.format)}</TableCell>
+                  <TableCell>{displayTableValue(record[column.field], {
+                    format: column.format,
+                    locale,
+                    messages: activeMessages,
+                  })}</TableCell>
                 {/each}
               </TableRow>
             {/each}
@@ -53,7 +59,7 @@
         </Table>
       </div>
     {:else}
-      <p class="table-state" role="alert">{records && !records.ok ? records.message : 'Table data is unavailable'}</p>
+      <p class="table-state" role="alert">{records && !records.ok ? activeMessages.tableInvalidData : activeMessages.tableUnavailable}</p>
     {/if}
   </CardContent>
 </Card>

package/dist/components/SurfaceRenderer.svelte

@@ -1,10 +1,13 @@
 <script lang="ts">
   import { canAccessAsync, captureAdminContext } from '@svadmin/core';
+  import { useTranslation } from '@svadmin/core/i18n';
   import { untrack } from 'svelte';
   import { resolveSurfaceWidgetData } from '../binding.js';
   import { defaultSurfaceCatalog } from '../catalog.js';
   import type { SurfaceRenderCatalog } from '../catalog.js';
   import { loadSurfaceSource } from '../runtime.js';
+  import { resolveSurfaceMessages } from '../localization.js';
+  import type { SurfaceMessages } from '../localization.js';
   import type {
     SurfaceDataError,
     SurfaceDataProvider,
@@ -24,6 +27,8 @@
     readonly policy: SurfacePolicy;
     readonly catalog?: SurfaceRenderCatalog;
     readonly dataProvider?: SurfaceDataProvider;
+    readonly locale?: string;
+    readonly messages?: Partial<SurfaceMessages>;
     readonly class?: string;
     readonly onError?: (error: SurfaceRendererError) => void;
   }
@@ -33,11 +38,16 @@
     policy,
     catalog = defaultSurfaceCatalog,
     dataProvider,
+    locale,
+    messages,
     class: className = '',
     onError,
   }: SurfaceRendererProps = $props();
 
   const adminContext = captureAdminContext();
+  const i18n = useTranslation();
+  const activeLocale = $derived(locale ?? i18n.locale);
+  const activeMessages = $derived(resolveSurfaceMessages(activeLocale, messages));
   const validation = $derived(validateSurfaceSpec(spec, catalog, policy));
   const widgetRegistrations = $derived(new Map(catalog.widgets.map((widget) => [widget.type, widget])));
   const currentSpec = $derived(validation.ok ? validation.value : null);
@@ -63,7 +73,7 @@
   }
 
   function providerError(sourceId: string, failure: unknown): SurfaceSourceDataState {
-    const message = failure instanceof Error ? failure.message : 'Data provider is unavailable';
+    const message = failure instanceof Error ? failure.message : activeMessages.providerUnavailable;
     return {
       status: 'error',
       sourceId,
@@ -151,6 +161,8 @@
               widgetId={widget.id}
               props={widget.props}
               data={resolveSurfaceWidgetData(widget, sourceStates)}
+              locale={activeLocale}
+              messages={activeMessages}
             />
           {/if}
         </div>
@@ -159,7 +171,7 @@
   </section>
 {:else}
   <section class="surface-error {className}" role="alert" data-surface-error>
-    <h2>Surface could not be rendered</h2>
+    <h2>{activeMessages.renderErrorTitle}</h2>
     <ul>
       {#each validation.issues as issue, issueIndex (`${issue.code}:${issue.path}:${issueIndex}`)}
         <li><code>{issue.code}</code>: {issue.message}</li>

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

@@ -1,4 +1,5 @@
 import type { SurfaceRenderCatalog } from '../catalog.js';
+import type { SurfaceMessages } from '../localization.js';
 import type { SurfaceDataError, SurfaceDataProvider, SurfacePolicy, SurfaceValidationIssue } from '../types.js';
 export type SurfaceRendererError = {
     readonly type: 'validation';
@@ -12,6 +13,8 @@ export interface SurfaceRendererProps {
     readonly policy: SurfacePolicy;
     readonly catalog?: SurfaceRenderCatalog;
     readonly dataProvider?: SurfaceDataProvider;
+    readonly locale?: string;
+    readonly messages?: Partial<SurfaceMessages>;
     readonly class?: string;
     readonly onError?: (error: SurfaceRendererError) => void;
 }

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 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 type { SurfaceMessages } from './localization.js';
 export { SURFACE_AGENT_SCHEMA_VERSION, buildSurfaceAgentPrompt, parseSurfaceAgentProposal, } from './agent.js';
 export type { SurfaceAgentProposal, SurfaceAgentValidationResult, } from './agent.js';

package/dist/localization.d.ts

@@ -0,0 +1,18 @@
+export interface SurfaceMessages {
+    readonly renderErrorTitle: string;
+    readonly providerUnavailable: string;
+    readonly metricNoData: string;
+    readonly metricInvalidData: string;
+    readonly chartLoading: string;
+    readonly chartNoData: string;
+    readonly chartInvalidData: string;
+    readonly chartUnavailable: string;
+    readonly tableLoading: string;
+    readonly tableNoRecords: string;
+    readonly tableInvalidData: string;
+    readonly tableUnavailable: string;
+    readonly booleanTrue: string;
+    readonly booleanFalse: string;
+}
+export declare function resolveSurfaceMessages(locale: string, overrides?: Partial<SurfaceMessages>): SurfaceMessages;
+export declare function formatSurfaceMessage(template: string, params: Readonly<Record<string, string | number>>): string;

package/dist/localization.js

@@ -0,0 +1,45 @@
+const englishMessages = {
+    renderErrorTitle: 'Surface could not be rendered',
+    providerUnavailable: 'Data provider is unavailable',
+    metricNoData: 'No data',
+    metricInvalidData: 'Metric data is invalid',
+    chartLoading: 'Loading {title}',
+    chartNoData: 'No chart data',
+    chartInvalidData: 'Chart data is invalid',
+    chartUnavailable: 'Chart data is unavailable',
+    tableLoading: 'Loading table',
+    tableNoRecords: 'No records',
+    tableInvalidData: 'Table data is invalid',
+    tableUnavailable: 'Table data is unavailable',
+    booleanTrue: 'Yes',
+    booleanFalse: 'No',
+};
+const simplifiedChineseMessages = {
+    renderErrorTitle: '无法渲染 Surface',
+    providerUnavailable: '数据提供器不可用',
+    metricNoData: '暂无数据',
+    metricInvalidData: '指标数据无效',
+    chartLoading: '正在加载{title}',
+    chartNoData: '暂无图表数据',
+    chartInvalidData: '图表数据无效',
+    chartUnavailable: '图表数据不可用',
+    tableLoading: '正在加载表格',
+    tableNoRecords: '暂无记录',
+    tableInvalidData: '表格数据无效',
+    tableUnavailable: '表格数据不可用',
+    booleanTrue: '是',
+    booleanFalse: '否',
+};
+export function resolveSurfaceMessages(locale, overrides) {
+    const defaults = locale.toLowerCase().startsWith('zh')
+        ? simplifiedChineseMessages
+        : englishMessages;
+    return { ...defaults, ...overrides };
+}
+export function formatSurfaceMessage(template, params) {
+    let formattedMessage = template;
+    for (const [key, value] of Object.entries(params)) {
+        formattedMessage = formattedMessage.replaceAll(`{${key}}`, String(value));
+    }
+    return formattedMessage;
+}

package/dist/svelte.d.ts

@@ -1,4 +1,5 @@
 export { default as SurfaceRenderer } from './components/SurfaceRenderer.svelte';
 export type { SurfaceRendererError, SurfaceRendererProps, } from './components/SurfaceRenderer.svelte';
+export type { SurfaceMessages } from './localization.js';
 export { DEFAULT_SURFACE_CATALOG_VERSION, defaultSurfaceCatalog, defineSurfaceCatalog, } from './catalog.js';
 export type { SurfaceRenderCatalog, SurfaceWidgetRegistration, SurfaceWidgetRendererProps, } from './catalog.js';

package/dist/widget-data.d.ts

@@ -1,4 +1,5 @@
 import type { JsonObject, JsonValue } from './types.js';
+import type { SurfaceMessages } from './localization.js';
 export interface SurfaceChartPoint {
     readonly label: string;
     readonly value: number;
@@ -10,7 +11,12 @@ export type WidgetValueResult<T> = {
     readonly ok: false;
     readonly message: string;
 };
-export declare function compactChartLabel(label: string, maxLength: number): string;
+export declare function compactChartLabel(label: string, maxLength: number, locale?: string): string;
 export declare function asRecordArray(value: JsonValue): WidgetValueResult<readonly JsonObject[]>;
 export declare function asChartPoints(value: JsonValue, labelField: string, valueField: string): WidgetValueResult<readonly SurfaceChartPoint[]>;
-export declare function displayTableValue(value: JsonValue | undefined, format: string | undefined): string;
+export interface TableValueFormatOptions {
+    readonly format: string | undefined;
+    readonly locale: string;
+    readonly messages: SurfaceMessages;
+}
+export declare function displayTableValue(value: JsonValue | undefined, options: TableValueFormatOptions): string;

package/dist/widget-data.js

@@ -1,7 +1,13 @@
-export function compactChartLabel(label, maxLength) {
+export function compactChartLabel(label, maxLength, locale = 'en-US') {
     const isoDate = /^(?:\d{4})-(\d{2})-(\d{2})$/u.exec(label);
-    if (isoDate)
-        return `${Number(isoDate[1])}/${Number(isoDate[2])}`;
+    if (isoDate) {
+        const date = new Date(`${label}T00:00:00Z`);
+        return new Intl.DateTimeFormat(locale, {
+            month: 'numeric',
+            day: 'numeric',
+            timeZone: 'UTC',
+        }).format(date);
+    }
     const characters = [...label];
     return characters.length <= maxLength
         ? label
@@ -30,11 +36,26 @@ export function asChartPoints(value, labelField, valueField) {
     }
     return { ok: true, value: points };
 }
-export function displayTableValue(value, format) {
+function formatTableDate(value, locale) {
+    const date = new Date(typeof value === 'string' && /^\d{4}-\d{2}-\d{2}$/u.test(value)
+        ? `${value}T00:00:00Z`
+        : value);
+    return Number.isNaN(date.getTime())
+        ? null
+        : new Intl.DateTimeFormat(locale, { dateStyle: 'medium', timeZone: 'UTC' }).format(date);
+}
+export function displayTableValue(value, options) {
+    const { format, locale, messages } = options;
     if (value === undefined || value === null)
         return '—';
     if (format === 'boolean')
-        return value === true ? 'Yes' : value === false ? 'No' : '—';
+        return value === true ? messages.booleanTrue : value === false ? messages.booleanFalse : '—';
+    if (format === 'number' && typeof value === 'number') {
+        return new Intl.NumberFormat(locale, { maximumFractionDigits: 2 }).format(value);
+    }
+    if (format === 'date' && (typeof value === 'string' || typeof value === 'number')) {
+        return formatTableDate(value, locale) ?? String(value);
+    }
     if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean')
         return String(value);
     return JSON.stringify(value);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@svadmin/surface",
-  "version": "0.7.1",
+  "version": "0.8.0",
   "description": "Validated declarative surfaces for svadmin dashboards",
   "type": "module",
   "sideEffects": false,
@@ -25,8 +25,8 @@
     }
   },
   "peerDependencies": {
-    "@svadmin/core": ">=0.34.2 <0.48.0",
-    "@svadmin/ui": ">=0.40.6 <0.66.0",
+    "@svadmin/core": ">=0.34.2 <0.49.0",
+    "@svadmin/ui": ">=0.40.6 <0.68.0",
     "svelte": "^5.56.8"
   },
   "dependencies": {