@svadmin/surface 0.1.0

package/README.md

@@ -0,0 +1,123 @@
+# @svadmin/surface
+
+`@svadmin/surface` renders a small, versioned JSON contract as a trusted Svelte dashboard. It is an optional browser package and does not change the public contract of `@svadmin/core`.
+
+The MVP supports Svelte 5 + Vite, a fixed 12-column grid, four built-in widgets, read-only `DataProvider` queries, explicit access checks, field projection, and manual host refresh.
+
+## Install
+
+```bash
+bun add @svadmin/surface @svadmin/core @svadmin/ui @tanstack/svelte-query svelte zod
+```
+
+Import protocol types and validation from the DOM-free root entry. Import rendering code from the Svelte subpath.
+
+```ts
+import { validateSurfaceSpec, type SurfacePolicy, type SurfaceSpec } from '@svadmin/surface';
+import {
+  DEFAULT_SURFACE_CATALOG_VERSION,
+  SurfaceRenderer,
+  defaultSurfaceCatalog,
+  defineSurfaceCatalog,
+} from '@svadmin/surface/svelte';
+```
+
+## Minimal example
+
+```svelte
+<script lang="ts">
+  import type { SurfacePolicy, SurfaceSpec } from '@svadmin/surface';
+  import {
+    DEFAULT_SURFACE_CATALOG_VERSION,
+    SurfaceRenderer,
+  } from '@svadmin/surface/svelte';
+
+  const policy = {
+    resources: {
+      products: {
+        readFields: ['id', 'name', 'stock'],
+        sortFields: ['stock'],
+        maxPageSize: 25,
+      },
+    },
+  } satisfies SurfacePolicy;
+
+  const spec = {
+    schemaVersion: 'surface/v1',
+    catalogVersion: DEFAULT_SURFACE_CATALOG_VERSION,
+    surfaceId: 'inventory',
+    title: 'Inventory',
+    layout: { type: 'grid', columns: 12, gap: 'md' },
+    dataSources: [
+      { id: 'products', type: 'resource-list', resource: 'products', pageSize: 10 },
+    ],
+    widgets: [
+      {
+        id: 'count',
+        type: 'metric',
+        props: { label: 'Products', format: 'number' },
+        binding: { sourceId: 'products', pointer: '/total' },
+        placement: { columnSpan: 3 },
+      },
+      {
+        id: 'stock',
+        type: 'bar-chart',
+        props: { title: 'Stock', labelField: 'name', valueField: 'stock' },
+        binding: { sourceId: 'products', pointer: '/items' },
+        placement: { columnSpan: 9 },
+      },
+    ],
+  } satisfies SurfaceSpec;
+
+  let renderer = $state<{ refresh(sourceId?: string): Promise<void> }>();
+</script>
+
+<button type="button" onclick={() => renderer?.refresh()}>Refresh</button>
+<SurfaceRenderer bind:this={renderer} {spec} {policy} />
+```
+
+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`.
+
+## Built-in catalog
+
+| Type | Binding | Purpose |
+| --- | --- | --- |
+| `metric` | `/total` on `resource-list`, or one readable field on `resource-one` | Numeric KPI |
+| `resource-table` | `/items` | Read-only table, at most eight columns |
+| `bar-chart` | `/items` | Zero-dependency SVG bar chart |
+| `line-chart` | `/items` | Zero-dependency SVG line chart |
+
+The catalog version is `svadmin/v1`. `catalogVersion` must match exactly.
+
+Custom catalogs are trusted runtime configuration. Every registration must use a strict Zod v4 object schema and a trusted Svelte component. Item widgets that read record fields must expose those fields through `getReferencedFields`; validation then checks them against `SurfacePolicy.readFields`.
+
+```ts
+const catalog = defineSurfaceCatalog({
+  version: 'acme/v1',
+  widgets: [{
+    type: 'status-list',
+    dataKind: 'items',
+    propsSchema: z.object({ statusField: z.string() }).strict(),
+    getReferencedFields: (props) => [props.statusField as string],
+    component: StatusList,
+  }],
+});
+```
+
+## Security boundary
+
+Surface specs are untrusted data. The renderer validates the whole document before sending any query. It rejects unknown components and sources, duplicate or overlong IDs, invalid props, dangerous pointers, mismatched versions, policy violations, and configured limits.
+
+Specs cannot contain HTML, Svelte, JavaScript, event handlers, Tailwind classes, style declarations, colors, URLs, SQL, provider selection, `meta`, arbitrary requests, or mutation actions. Provider records are projected to `readFields`, and selected values containing `Date`, `File`, `BigInt`, functions, cycles, `NaN`, or infinities fail instead of being converted.
+
+The browser access-control check is display gating only. The backend must independently authorize every request and must not trust the spec, policy, or projected fields received from a browser.
+
+MVP limits are eight data sources, 24 widgets, 100 rows per page, eight filters, three sorters, 64-character IDs, 64 levels of JSON nesting, and 10,000 JSON nodes. A source is loaded once and shared. Generation checks discard stale responses.
+
+Supported Core/UI ranges and the minimum packed-consumer matrix are published in `compatibility.json`.
+
+## Out of scope for v1
+
+SSR/Lite, Agent generation, storage, revisions, JSON Patch, actions, mutations, automatic refresh, arbitrary URLs, client aggregation, Canvas, and iframe rendering are intentionally absent. Aggregated metrics should come from a backend summary resource and bind through `resource-one`.
+
+中文指南见文档站的“声明式 Surface”。

package/compatibility.json

@@ -0,0 +1,22 @@
+{
+  "surface": "0.1.x",
+  "minimumSupported": {
+    "@svadmin/core": "0.34.2",
+    "@svadmin/ui": "0.40.6",
+    "svelte": "5.56.8"
+  },
+  "testedCombinations": [
+    {
+      "name": "minimum-supported",
+      "core": "0.34.2",
+      "ui": "0.40.6",
+      "svelte": "5.56.8"
+    },
+    {
+      "name": "workspace-packed",
+      "core": "workspace tarball",
+      "ui": "workspace tarball",
+      "svelte": "workspace override"
+    }
+  ]
+}

package/dist/binding.d.ts

@@ -0,0 +1,2 @@
+import type { SurfaceSourceDataState, SurfaceWidget, SurfaceWidgetDataState } from './types.js';
+export declare function resolveSurfaceWidgetData(widget: SurfaceWidget, sourceStates: Readonly<Record<string, SurfaceSourceDataState>>): SurfaceWidgetDataState;

package/dist/binding.js

@@ -0,0 +1,55 @@
+import { decodedJsonPointerToken } from './json.js';
+function readJsonPointer(root, pointer) {
+    if (pointer === '')
+        return root;
+    if (!pointer.startsWith('/'))
+        return undefined;
+    let current = root;
+    for (const encodedToken of pointer.slice(1).split('/')) {
+        const token = decodedJsonPointerToken(encodedToken);
+        if (token === null || current === null || typeof current !== 'object')
+            return undefined;
+        if (Array.isArray(current)) {
+            if (!/^(?:0|[1-9][0-9]*)$/u.test(token))
+                return undefined;
+            const index = Number(token);
+            if (index >= current.length)
+                return undefined;
+            current = current[index];
+            continue;
+        }
+        const objectValue = current;
+        if (!Object.hasOwn(objectValue, token))
+            return undefined;
+        current = objectValue[token];
+    }
+    return current;
+}
+function missingPointerState(sourceId) {
+    return {
+        status: 'error',
+        sourceId,
+        error: {
+            code: 'binding_pointer_not_found',
+            sourceId,
+            message: 'The validated binding pointer was not found in the provider result',
+        },
+    };
+}
+export function resolveSurfaceWidgetData(widget, sourceStates) {
+    if (!widget.binding)
+        return { status: 'unbound' };
+    const sourceId = widget.binding.sourceId;
+    const sourceState = Object.hasOwn(sourceStates, sourceId) ? sourceStates[sourceId] : undefined;
+    if (!sourceState)
+        return { status: 'loading', sourceId };
+    if (sourceState.status !== 'ready')
+        return sourceState;
+    const value = readJsonPointer(sourceState.value, widget.binding.pointer ?? '');
+    if (value === undefined)
+        return missingPointerState(sourceId);
+    if (value === null || (Array.isArray(value) && value.length === 0)) {
+        return { status: 'empty', sourceId };
+    }
+    return { status: 'ready', sourceId, value };
+}

package/dist/builtin-schemas.d.ts

@@ -0,0 +1,42 @@
+import { z } from 'zod';
+export declare const metricPropsSchema: z.ZodObject<{
+    label: z.ZodString;
+    format: z.ZodEnum<{
+        number: "number";
+        currency: "currency";
+        percent: "percent";
+    }>;
+    currency: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export declare const resourceTablePropsSchema: z.ZodObject<{
+    title: z.ZodString;
+    emptyLabel: z.ZodOptional<z.ZodString>;
+    columns: z.ZodArray<z.ZodObject<{
+        field: z.ZodString;
+        label: z.ZodString;
+        format: z.ZodOptional<z.ZodEnum<{
+            number: "number";
+            boolean: "boolean";
+            text: "text";
+            date: "date";
+        }>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export declare const barChartPropsSchema: z.ZodObject<{
+    title: z.ZodString;
+    labelField: z.ZodString;
+    valueField: z.ZodString;
+    showValues: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+export declare const lineChartPropsSchema: z.ZodObject<{
+    title: z.ZodString;
+    labelField: z.ZodString;
+    valueField: z.ZodString;
+    showDots: z.ZodOptional<z.ZodBoolean>;
+    fill: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+export type MetricProps = z.infer<typeof metricPropsSchema>;
+export type ResourceTableProps = z.infer<typeof resourceTablePropsSchema>;
+export type BarChartProps = z.infer<typeof barChartPropsSchema>;
+export type LineChartProps = z.infer<typeof lineChartPropsSchema>;

package/dist/builtin-schemas.js

@@ -0,0 +1,37 @@
+import { z } from 'zod';
+const catalogFieldSchema = z.string().min(1).max(64).regex(/^[A-Za-z][A-Za-z0-9_-]*$/u);
+export const metricPropsSchema = z.object({
+    label: z.string().min(1).max(80),
+    format: z.enum(['number', 'currency', 'percent']),
+    currency: z.string().regex(/^[A-Z]{3}$/u).optional(),
+    description: z.string().min(1).max(160).optional(),
+}).strict().superRefine((props, context) => {
+    if (props.format === 'currency' && !props.currency) {
+        context.addIssue({ code: 'custom', path: ['currency'], message: 'Currency format requires an ISO currency code' });
+    }
+    if (props.format !== 'currency' && props.currency) {
+        context.addIssue({ code: 'custom', path: ['currency'], message: 'Currency is only valid with currency format' });
+    }
+});
+export const resourceTablePropsSchema = z.object({
+    title: z.string().min(1).max(80),
+    emptyLabel: z.string().min(1).max(80).optional(),
+    columns: z.array(z.object({
+        field: catalogFieldSchema,
+        label: z.string().min(1).max(60),
+        format: z.enum(['text', 'number', 'date', 'boolean']).optional(),
+    }).strict()).min(1).max(8),
+}).strict();
+export const barChartPropsSchema = z.object({
+    title: z.string().min(1).max(80),
+    labelField: catalogFieldSchema,
+    valueField: catalogFieldSchema,
+    showValues: z.boolean().optional(),
+}).strict();
+export const lineChartPropsSchema = z.object({
+    title: z.string().min(1).max(80),
+    labelField: catalogFieldSchema,
+    valueField: catalogFieldSchema,
+    showDots: z.boolean().optional(),
+    fill: z.boolean().optional(),
+}).strict();

package/dist/catalog.d.ts

@@ -0,0 +1,79 @@
+import type { Component } from 'svelte';
+import type { JsonObject, SurfaceCatalog, SurfaceWidgetDataState, SurfaceWidgetDefinition } from './types.js';
+export declare const DEFAULT_SURFACE_CATALOG_VERSION: "svadmin/v1";
+export interface SurfaceWidgetRendererProps {
+    readonly widgetId: string;
+    readonly props: JsonObject;
+    readonly data: SurfaceWidgetDataState;
+}
+export interface SurfaceWidgetRegistration extends SurfaceWidgetDefinition {
+    readonly component: Component<SurfaceWidgetRendererProps>;
+}
+export interface SurfaceRenderCatalog extends SurfaceCatalog {
+    readonly widgets: readonly SurfaceWidgetRegistration[];
+}
+export declare function defineSurfaceCatalog<const TCatalog extends SurfaceRenderCatalog>(catalog: TCatalog): TCatalog;
+declare function tableFields(props: JsonObject): readonly string[];
+declare function barChartFields(props: JsonObject): readonly string[];
+declare function lineChartFields(props: JsonObject): readonly string[];
+export declare const defaultSurfaceCatalog: {
+    readonly version: "svadmin/v1";
+    readonly widgets: readonly [{
+        readonly type: "metric";
+        readonly dataKind: "scalar";
+        readonly propsSchema: import("zod").ZodObject<{
+            label: import("zod").ZodString;
+            format: import("zod").ZodEnum<{
+                number: "number";
+                currency: "currency";
+                percent: "percent";
+            }>;
+            currency: import("zod").ZodOptional<import("zod").ZodString>;
+            description: import("zod").ZodOptional<import("zod").ZodString>;
+        }, import("zod/v4/core").$strict>;
+        readonly component: Component<SurfaceWidgetRendererProps, {}, "">;
+    }, {
+        readonly type: "resource-table";
+        readonly dataKind: "items";
+        readonly propsSchema: import("zod").ZodObject<{
+            title: import("zod").ZodString;
+            emptyLabel: import("zod").ZodOptional<import("zod").ZodString>;
+            columns: import("zod").ZodArray<import("zod").ZodObject<{
+                field: import("zod").ZodString;
+                label: import("zod").ZodString;
+                format: import("zod").ZodOptional<import("zod").ZodEnum<{
+                    number: "number";
+                    boolean: "boolean";
+                    text: "text";
+                    date: "date";
+                }>>;
+            }, import("zod/v4/core").$strict>>;
+        }, import("zod/v4/core").$strict>;
+        readonly getReferencedFields: typeof tableFields;
+        readonly component: Component<SurfaceWidgetRendererProps, {}, "">;
+    }, {
+        readonly type: "bar-chart";
+        readonly dataKind: "items";
+        readonly propsSchema: import("zod").ZodObject<{
+            title: import("zod").ZodString;
+            labelField: import("zod").ZodString;
+            valueField: import("zod").ZodString;
+            showValues: import("zod").ZodOptional<import("zod").ZodBoolean>;
+        }, import("zod/v4/core").$strict>;
+        readonly getReferencedFields: typeof barChartFields;
+        readonly component: Component<SurfaceWidgetRendererProps, {}, "">;
+    }, {
+        readonly type: "line-chart";
+        readonly dataKind: "items";
+        readonly propsSchema: import("zod").ZodObject<{
+            title: import("zod").ZodString;
+            labelField: import("zod").ZodString;
+            valueField: import("zod").ZodString;
+            showDots: import("zod").ZodOptional<import("zod").ZodBoolean>;
+            fill: import("zod").ZodOptional<import("zod").ZodBoolean>;
+        }, import("zod/v4/core").$strict>;
+        readonly getReferencedFields: typeof lineChartFields;
+        readonly component: Component<SurfaceWidgetRendererProps, {}, "">;
+    }];
+};
+export {};

package/dist/catalog.js

@@ -0,0 +1,60 @@
+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';
+export function defineSurfaceCatalog(catalog) {
+    if (catalog.version.length === 0)
+        throw new Error('Surface catalog version must not be empty');
+    const widgetTypes = new Set();
+    for (const widget of catalog.widgets) {
+        if (widgetTypes.has(widget.type))
+            throw new Error(`Duplicate surface widget type "${widget.type}"`);
+        widgetTypes.add(widget.type);
+    }
+    return catalog;
+}
+function tableFields(props) {
+    return resourceTablePropsSchema.parse(props).columns.map((column) => column.field);
+}
+function barChartFields(props) {
+    const chartProps = barChartPropsSchema.parse(props);
+    return [chartProps.labelField, chartProps.valueField];
+}
+function lineChartFields(props) {
+    const chartProps = lineChartPropsSchema.parse(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,
+        },
+    ],
+});

package/dist/components/BarChartWidget.svelte

@@ -0,0 +1,70 @@
+<script lang="ts">
+  import BarChart from '@svadmin/ui/components/charts/BarChart.svelte';
+  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';
+  import Card from '@svadmin/ui/components/ui/card/card.svelte';
+  import { barChartPropsSchema } from '../builtin-schemas.js';
+  import type { SurfaceWidgetRendererProps } from '../catalog.js';
+  import { asChartPoints, compactChartLabel } from '../widget-data.js';
+
+  let { props, data }: SurfaceWidgetRendererProps = $props();
+
+  const chartProps = $derived(barChartPropsSchema.parse(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) }))
+    : []);
+</script>
+
+<Card>
+  <CardHeader>
+    <CardTitle>{chartProps.title}</CardTitle>
+  </CardHeader>
+  <CardContent>
+    {#if data.status === 'loading'}
+      <div class="chart-state chart-loading" role="status" aria-label="Loading {chartProps.title}"></div>
+    {:else if data.status === 'empty'}
+      <p class="chart-state" role="status">No chart data</p>
+    {:else if data.status === 'error'}
+      <p class="chart-state" role="alert">{data.error.message}</p>
+    {:else if data.status === 'ready' && points?.ok}
+      <div class="chart-frame" role="img" aria-label={chartProps.title}>
+        <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>
+    {/if}
+  </CardContent>
+</Card>
+
+<style>
+  .chart-state {
+    display: grid;
+    min-height: 12rem;
+    margin: 0;
+    place-items: center;
+    color: var(--muted-foreground);
+  }
+
+  .chart-frame :global(svg) {
+    min-width: 0 !important;
+  }
+
+  .chart-loading {
+    border-radius: 0.5rem;
+    background: linear-gradient(90deg, var(--muted), var(--card), var(--muted));
+    background-size: 200% 100%;
+    animation: surface-pulse 1.5s ease-in-out infinite;
+  }
+
+  @keyframes surface-pulse {
+    to { background-position: -200% 0; }
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    .chart-loading { animation: none; }
+  }
+</style>

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

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

package/dist/components/LineChartWidget.svelte

@@ -0,0 +1,74 @@
+<script lang="ts">
+  import LineChart from '@svadmin/ui/components/charts/LineChart.svelte';
+  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';
+  import Card from '@svadmin/ui/components/ui/card/card.svelte';
+  import { lineChartPropsSchema } from '../builtin-schemas.js';
+  import type { SurfaceWidgetRendererProps } from '../catalog.js';
+  import { asChartPoints, compactChartLabel } from '../widget-data.js';
+
+  let { props, data }: SurfaceWidgetRendererProps = $props();
+
+  const chartProps = $derived(lineChartPropsSchema.parse(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) }))
+    : []);
+</script>
+
+<Card>
+  <CardHeader>
+    <CardTitle>{chartProps.title}</CardTitle>
+  </CardHeader>
+  <CardContent>
+    {#if data.status === 'loading'}
+      <div class="chart-state chart-loading" role="status" aria-label="Loading {chartProps.title}"></div>
+    {:else if data.status === 'empty'}
+      <p class="chart-state" role="status">No chart data</p>
+    {:else if data.status === 'error'}
+      <p class="chart-state" role="alert">{data.error.message}</p>
+    {:else if data.status === 'ready' && points?.ok}
+      <div class="chart-frame" role="img" aria-label={chartProps.title}>
+        <LineChart
+          data={chartData}
+          showDots={chartProps.showDots ?? true}
+          fill={chartProps.fill ?? true}
+        />
+      </div>
+    {:else}
+      <p class="chart-state" role="alert">{points && !points.ok ? points.message : 'Chart data is unavailable'}</p>
+    {/if}
+  </CardContent>
+</Card>
+
+<style>
+  .chart-state {
+    display: grid;
+    min-height: 12rem;
+    margin: 0;
+    place-items: center;
+    color: var(--muted-foreground);
+  }
+
+  .chart-frame :global(svg) {
+    min-width: 0 !important;
+  }
+
+  .chart-loading {
+    border-radius: 0.5rem;
+    background: linear-gradient(90deg, var(--muted), var(--card), var(--muted));
+    background-size: 200% 100%;
+    animation: surface-pulse 1.5s ease-in-out infinite;
+  }
+
+  @keyframes surface-pulse {
+    to { background-position: -200% 0; }
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    .chart-loading { animation: none; }
+  }
+</style>

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

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

package/dist/components/MetricWidget.svelte

@@ -0,0 +1,72 @@
+<script lang="ts">
+  import StatsCard from '@svadmin/ui/components/StatsCard.svelte';
+  import { metricPropsSchema } from '../builtin-schemas.js';
+  import type { SurfaceWidgetRendererProps } from '../catalog.js';
+
+  let { widgetId, props, data }: SurfaceWidgetRendererProps = $props();
+
+  const metricProps = $derived(metricPropsSchema.parse(props));
+  const formattedValue = $derived.by(() => {
+    if (data.status !== 'ready') return '—';
+    const value = data.value;
+    if (typeof value !== 'number') return '—';
+    if (metricProps.format === 'currency') {
+      return new Intl.NumberFormat('en-US', {
+        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('en-US', { maximumFractionDigits: 2 }).format(value);
+  });
+</script>
+
+<article 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 />
+  {:else if data.status === 'ready' && typeof data.value === 'number'}
+    <StatsCard label={metricProps.label} value={formattedValue} />
+    {#if metricProps.description}
+      <p class="metric-description">{metricProps.description}</p>
+    {/if}
+  {: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>
+    </div>
+  {/if}
+</article>
+
+<style>
+  .visually-hidden {
+    position: absolute;
+    width: 1px;
+    height: 1px;
+    padding: 0;
+    margin: -1px;
+    overflow: hidden;
+    clip: rect(0, 0, 0, 0);
+    white-space: nowrap;
+    border: 0;
+  }
+
+  .metric-description {
+    margin: 0.5rem 0 0;
+    color: var(--muted-foreground);
+    font-size: 0.8125rem;
+  }
+
+  .metric-state {
+    display: grid;
+    gap: 0.35rem;
+    min-height: 6rem;
+    padding: 1.25rem;
+    border: 1px solid var(--border);
+    border-radius: 0.75rem;
+    background: var(--card);
+    color: var(--muted-foreground);
+  }
+</style>

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

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