@happyvertical/smrt-svelte 0.55.6 → 0.55.8

package/dist/components/overview/types.d.ts

@@ -0,0 +1,235 @@
+import type { Component } from 'svelte';
+/**
+ * Types of the customizable overview surface (#3727): the declarative overview
+ * data model, the widget contract, and the page-load contract, plus their
+ * limits. Shared by the Svelte-free `./overview/server` entry and the
+ * component barrel.
+ */
+/** Narrowest and widest a widget can be, in grid columns. */
+export declare const OVERVIEW_MIN_SPAN = 1;
+export declare const OVERVIEW_MAX_SPAN = 4;
+/** Default cap on widgets in one overview. */
+export declare const OVERVIEW_DEFAULT_MAX_WIDGETS = 24;
+/** Widget ids: short, URL-safe, stable. */
+export declare const OVERVIEW_ID_PATTERN: RegExp;
+/** Overview (page) ids may be dotted or scoped, e.g. `events.home`. */
+export declare const OVERVIEW_PAGE_ID_PATTERN: RegExp;
+/** Widget type ids: lowercase kebab, so they are safe in selectors and keys. */
+export declare const WIDGET_TYPE_PATTERN: RegExp;
+/** An option value is a JSON primitive: options are flat data, never code. */
+export type OverviewOptionValue = string | number | boolean | null;
+export type OverviewOptions = Record<string, OverviewOptionValue>;
+/**
+ * One widget on an overview. `version` is the widget type's option-schema
+ * version the options were written against (absent means 1).
+ */
+export interface OverviewWidget {
+    id: string;
+    type: string;
+    /** Column span, 1 to 4. */
+    span: number;
+    options: OverviewOptions;
+    version?: number;
+}
+/** The resolved, declarative overview: an ordered list of widgets. */
+export interface OverviewDocument {
+    widgets: OverviewWidget[];
+}
+/** A change to a widget that exists in the base document. */
+export interface OverviewWidgetPatch {
+    span?: number;
+    options?: OverviewOptions;
+    version?: number;
+}
+/**
+ * The sparse, JSON-serializable delta a host stores (tenant default or user
+ * override) on top of the page's default document. Unknown ids are ignored
+ * on read, so a default that ships later still appears.
+ */
+export interface OverviewOverride {
+    version: 1;
+    /** Widget ids in display order; unlisted widgets keep their slots. */
+    order?: string[];
+    /** Ids of base widgets the user removed. */
+    removed?: string[];
+    /** Widgets the user added (ids never collide with the base). */
+    added?: OverviewWidget[];
+    /** Span and option changes to base widgets, by id. */
+    changed?: Record<string, OverviewWidgetPatch>;
+}
+/** What a page declares: which widgets may appear and the default layout. */
+export interface OverviewDefinition {
+    /** Stable id of this overview (e.g. `events.home`). */
+    id: string;
+    /** Widget types allowed here. Omit to allow every registered type. */
+    allowed?: readonly string[];
+    /**
+     * Models the overview may read. When set, a `model` option outside the list
+     * is invalid. Confines data sources on top of the loader's own authorization.
+     */
+    models?: readonly string[];
+    /** The default arrangement. */
+    defaults: readonly OverviewWidget[];
+    /** Cap on widgets (default {@link OVERVIEW_DEFAULT_MAX_WIDGETS}). */
+    maxWidgets?: number;
+}
+export type OverviewIssueCode = 'malformed' | 'duplicate_id' | 'unknown_type' | 'type_not_allowed' | 'too_many' | 'invalid_span' | 'invalid_options' | 'future_version' | 'migration_failed';
+/** A widget (or override entry) that was dropped or rejected, and why. */
+export interface OverviewIssue {
+    widgetId: string | null;
+    type: string | null;
+    code: OverviewIssueCode;
+    /** Developer-facing detail; not localized. */
+    message: string;
+    /** Option-level problems when `code` is `invalid_options`. */
+    options?: WidgetOptionIssue[];
+}
+export type WidgetOptionType = 'text' | 'markdown' | 'identifier' | 'model' | 'integer' | 'number' | 'boolean' | 'enum';
+export interface WidgetOptionChoice {
+    value: string;
+    /** Label text or an i18n key. */
+    label: string;
+}
+/**
+ * One option of a widget. The shape mirrors the generated screens' field
+ * (`name`/`label`/`help`/`required`) so the option editor reads like any other
+ * generated form.
+ */
+export interface WidgetOptionField {
+    key: string;
+    type: WidgetOptionType;
+    /** Label text or an i18n key. */
+    label: string;
+    /** Help text or an i18n key. */
+    help?: string;
+    required?: boolean;
+    default?: OverviewOptionValue;
+    /** `integer` and `number` bounds. */
+    min?: number;
+    max?: number;
+    /** `text`, `markdown`: maximum length (defaults 200 and 10000). */
+    maxLength?: number;
+    /** `enum`: the closed set of values. */
+    choices?: readonly WidgetOptionChoice[];
+}
+export type WidgetOptionIssueCode = 'required' | 'invalid_type' | 'too_long' | 'out_of_range' | 'not_in_choices' | 'invalid_format' | 'not_allowed' | 'unknown_option';
+export interface WidgetOptionIssue {
+    key: string;
+    code: WidgetOptionIssueCode;
+}
+export type WidgetOptionsResult = {
+    ok: true;
+    options: OverviewOptions;
+} | {
+    ok: false;
+    issues: WidgetOptionIssue[];
+};
+/** Extra confinement applied while validating options. */
+export interface WidgetOptionsContext {
+    /** Models a `model` option may name; omit for no list. */
+    models?: readonly string[];
+}
+/** Where a widget's data stands in the grid. */
+export type WidgetStatus = 'ready' | 'loading' | 'error';
+/**
+ * Props every widget component receives. The grid mounts a component only
+ * when its data is ready (it draws loading and error states itself), so
+ * `data` is whatever the widget's `load` returned, or `undefined` for a
+ * widget without a loader. Treat `data` as untrusted shape: check it.
+ */
+export interface WidgetComponentProps<Data = unknown> {
+    id: string;
+    options: OverviewOptions;
+    data: Data | undefined;
+    span: number;
+    /** Heading shown by the frame (the `title` option, else the type title). */
+    title: string;
+    /** BCP-47 locale for number formatting. */
+    locale: string;
+    /** The host's renderer for icon names that are not built in. */
+    iconComponent?: Component<{
+        name: string;
+        size?: number;
+    }>;
+}
+/**
+ * Context a widget `load` runs with. The host builds it inside the page's
+ * server load from the request principal: the user's permissions, the
+ * tenant-scoped collections, the locale. Index keys carry host capabilities
+ * (for example a permission-checked `db` or `fetch`).
+ */
+export interface WidgetLoadContext {
+    /** The overview being loaded. */
+    overviewId: string;
+    /** Aborts when the load times out or the request ends. */
+    signal?: AbortSignal;
+    locale?: string;
+    [capability: string]: unknown;
+}
+/**
+ * Server loader of one widget. Receives validated options only, and the
+ * request's context. Must return JSON-serializable data and must authorize
+ * through `ctx` (never trust the option values for access).
+ */
+export type WidgetLoad<Data = unknown, Ctx extends WidgetLoadContext = WidgetLoadContext> = (options: OverviewOptions, ctx: Ctx) => Data | Promise<Data>;
+/** Upgrades stored options from an older schema version to the current one. */
+export type WidgetMigrate = (options: Record<string, unknown>, fromVersion: number) => Record<string, unknown> | null;
+/** A module (or component) a lazy widget resolves to. */
+export type WidgetComponentModule<Data> = Component<WidgetComponentProps<Data>> | {
+    default: Component<WidgetComponentProps<Data>>;
+};
+/** What `registerWidget` takes. */
+export interface WidgetDefinition<Data = unknown> {
+    /** Lowercase kebab id, e.g. `metric`. */
+    type: string;
+    /** Title text or an i18n key. */
+    title: string;
+    /** Short description or an i18n key (shown in the add list). */
+    description?: string;
+    /** Shell icon name drawn in the add list. */
+    icon?: string;
+    /** Option-schema version, a positive integer (default 1). */
+    version?: number;
+    /** The widget's options, as fields. */
+    options: readonly WidgetOptionField[];
+    /** Renders the widget. */
+    component?: Component<WidgetComponentProps<Data>>;
+    /**
+     * Resolves the component lazily (dynamic import by export ref). A page
+     * resolves these before rendering with `resolveWidgetComponents`.
+     */
+    loadComponent?: () => Promise<WidgetComponentModule<Data>>;
+    /** Server loader; absent for widgets that render from options alone. */
+    load?: WidgetLoad<Data>;
+    /** Overview ids this widget may appear in; omit for any. */
+    allowedIn?: readonly string[];
+    /** Upgrades options stored at an older version. */
+    migrate?: WidgetMigrate;
+    /** Span a new widget starts with (default 1). */
+    defaultSpan?: number;
+    minSpan?: number;
+    maxSpan?: number;
+}
+/** A registered definition with every default filled in. */
+export interface RegisteredWidget<Data = unknown> extends Omit<WidgetDefinition<Data>, 'version' | 'defaultSpan'> {
+    version: number;
+    defaultSpan: number;
+    minSpan: number;
+    maxSpan: number;
+}
+export type LoadedWidgetErrorCode = 'load_failed' | 'timeout' | 'invalid_data';
+/** A widget with its loaded data. JSON-serializable. */
+export interface LoadedWidget extends OverviewWidget {
+    status: 'ready' | 'error';
+    data?: unknown;
+    error?: {
+        code: LoadedWidgetErrorCode;
+    };
+}
+/** What a page's server load returns for the client to render. */
+export interface LoadedOverview {
+    overviewId: string;
+    widgets: LoadedWidget[];
+    issues: OverviewIssue[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/components/overview/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/components/overview/types.ts"],"names":[],"mappings":"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"}

package/dist/components/overview/types.js

@@ -0,0 +1,17 @@
+/**
+ * Types of the customizable overview surface (#3727): the declarative overview
+ * data model, the widget contract, and the page-load contract, plus their
+ * limits. Shared by the Svelte-free `./overview/server` entry and the
+ * component barrel.
+ */
+/** Narrowest and widest a widget can be, in grid columns. */
+export const OVERVIEW_MIN_SPAN = 1;
+export const OVERVIEW_MAX_SPAN = 4;
+/** Default cap on widgets in one overview. */
+export const OVERVIEW_DEFAULT_MAX_WIDGETS = 24;
+/** Widget ids: short, URL-safe, stable. */
+export const OVERVIEW_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/;
+/** Overview (page) ids may be dotted or scoped, e.g. `events.home`. */
+export const OVERVIEW_PAGE_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,95}$/;
+/** Widget type ids: lowercase kebab, so they are safe in selectors and keys. */
+export const WIDGET_TYPE_PATTERN = /^[a-z][a-z0-9-]{0,31}$/;

package/dist/components/overview/widgets/ChartWidget.svelte

@@ -0,0 +1,111 @@
+<script lang="ts">
+/**
+ * Chart widget (#3727): bars or a line over labelled values, drawn from the
+ * loaded data. Every chart carries its numbers as text (bar values inline, a
+ * visually hidden table for the line) so it is readable without sight.
+ */
+import { useI18n } from '@happyvertical/smrt-ui/i18n';
+import { M } from '../../../i18n/strings.overview.js';
+import { formatWidgetValue } from '../format.js';
+import type { WidgetComponentProps } from '../types.js';
+import { type ChartWidgetData, isRecord } from './data.js';
+
+let { options, data, title, locale }: WidgetComponentProps<ChartWidgetData> =
+  $props();
+
+const { t } = useI18n();
+const MAX_POINTS = 60;
+
+const chart = $derived(isRecord(data) ? data : null);
+const points = $derived.by(() => {
+  if (!chart || !Array.isArray(chart.points)) return [];
+  const out: { label: string; value: number }[] = [];
+  for (const point of chart.points.slice(0, MAX_POINTS)) {
+    if (
+      isRecord(point) &&
+      typeof point.label === 'string' &&
+      typeof point.value === 'number' &&
+      Number.isFinite(point.value)
+    ) {
+      out.push({ label: point.label, value: point.value });
+    }
+  }
+  return out;
+});
+const style = $derived(options.style === 'line' ? 'line' : 'bar');
+const fmt = (value: number): string =>
+  formatWidgetValue(value, {
+    format: chart?.format ?? 'integer',
+    currency: chart?.currency,
+    locale,
+  });
+const max = $derived(Math.max(0, ...points.map((point) => point.value)));
+const min = $derived(Math.min(0, ...points.map((point) => point.value)));
+const span = $derived(max - min || 1);
+const polyline = $derived(
+  points
+    .map((point, index) => {
+      const x = points.length === 1 ? 50 : (index / (points.length - 1)) * 100;
+      const y = 36 - ((point.value - min) / span) * 32;
+      return `${x.toFixed(2)},${y.toFixed(2)}`;
+    })
+    .join(' '),
+);
+const summary = $derived(
+  `${title}. ${t(M['ui.overview.chart.summary'], { count: points.length })}`,
+);
+</script>
+
+{#if points.length === 0}
+  <p class="smrt-chart__empty">{t(M['ui.overview.no_data'])}</p>
+{:else if style === 'line'}
+  <div class="smrt-chart">
+    <svg class="smrt-chart__line" viewBox="0 0 100 40" preserveAspectRatio="none" role="img" aria-label={summary}>
+      <polyline points={polyline} fill="none" stroke="currentColor" stroke-width="2" vector-effect="non-scaling-stroke" />
+    </svg>
+    <p class="smrt-chart__axis" aria-hidden="true">
+      <span>{points[0].label}</span>
+      <span>{points[points.length - 1].label}</span>
+    </p>
+    <table class="smrt-chart__table">
+      <caption>{t(M['ui.overview.chart.table'])}</caption>
+      <thead>
+        <tr>
+          <th scope="col">{t(M['ui.overview.chart.label_column'])}</th>
+          <th scope="col">{t(M['ui.overview.chart.value_column'])}</th>
+        </tr>
+      </thead>
+      <tbody>
+        {#each points as point, index (index)}
+          <tr><th scope="row">{point.label}</th><td>{fmt(point.value)}</td></tr>
+        {/each}
+      </tbody>
+    </table>
+  </div>
+{:else}
+  <ul class="smrt-chart__bars" aria-label={summary}>
+    {#each points as point, index (index)}
+      <li class="smrt-chart__row">
+        <span class="smrt-chart__label">{point.label}</span>
+        <span class="smrt-chart__track" aria-hidden="true">
+          <span class="smrt-chart__bar" style:inline-size="{max > 0 ? (Math.max(0, point.value) / max) * 100 : 0}%"></span>
+        </span>
+        <span class="smrt-chart__value">{fmt(point.value)}</span>
+      </li>
+    {/each}
+  </ul>
+{/if}
+
+<style>
+  .smrt-chart { display: grid; gap: var(--smrt-spacing-1); color: var(--smrt-color-primary); }
+  .smrt-chart__line { inline-size: 100%; block-size: 7rem; overflow: visible; }
+  .smrt-chart__axis { display: flex; justify-content: space-between; margin: 0; color: var(--smrt-color-on-surface-variant); font-size: var(--smrt-typography-label-large-size, 0.75rem); }
+  .smrt-chart__bars { display: grid; gap: var(--smrt-spacing-2); margin: 0; padding: 0; list-style: none; }
+  .smrt-chart__row { display: grid; grid-template-columns: minmax(4rem, 30%) minmax(0, 1fr) auto; align-items: center; gap: var(--smrt-spacing-2); font-size: var(--smrt-typography-body-medium-size, 0.875rem); color: var(--smrt-color-on-surface); }
+  .smrt-chart__label { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+  .smrt-chart__track { display: block; block-size: 0.625rem; border-radius: var(--smrt-radius-full, 9999px); background: var(--smrt-color-surface-container-high); overflow: hidden; }
+  .smrt-chart__bar { display: block; block-size: 100%; border-radius: inherit; background: var(--smrt-color-primary); }
+  .smrt-chart__value { font-variant-numeric: tabular-nums; color: var(--smrt-color-on-surface-variant); }
+  .smrt-chart__empty { margin: 0; color: var(--smrt-color-on-surface-variant); }
+  .smrt-chart__table { position: absolute; inline-size: 1px; block-size: 1px; overflow: hidden; clip: rect(0 0 0 0); clip-path: inset(50%); white-space: nowrap; }
+</style>

package/dist/components/overview/widgets/ChartWidget.svelte.d.ts

@@ -0,0 +1,6 @@
+import type { WidgetComponentProps } from '../types.js';
+import { type ChartWidgetData } from './data.js';
+declare const ChartWidget: import("svelte").Component<WidgetComponentProps<ChartWidgetData>, {}, "">;
+type ChartWidget = ReturnType<typeof ChartWidget>;
+export default ChartWidget;
+//# sourceMappingURL=ChartWidget.svelte.d.ts.map

package/dist/components/overview/widgets/ChartWidget.svelte.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ChartWidget.svelte.d.ts","sourceRoot":"","sources":["../../../../src/components/overview/widgets/ChartWidget.svelte.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACxD,OAAO,EAAE,KAAK,eAAe,EAAY,MAAM,WAAW,CAAC;AAoG3D,QAAA,MAAM,WAAW,2EAAwC,CAAC;AAC1D,KAAK,WAAW,GAAG,UAAU,CAAC,OAAO,WAAW,CAAC,CAAC;AAClD,eAAe,WAAW,CAAC"}

package/dist/components/overview/widgets/MetricWidget.svelte

@@ -0,0 +1,86 @@
+<script lang="ts">
+/**
+ * Metric widget (#3727): one number with an optional caption and change. It
+ * renders from the loaded data only; the loader decides what the number means.
+ */
+import { useI18n } from '@happyvertical/smrt-ui/i18n';
+import { M } from '../../../i18n/strings.overview.js';
+import { formatWidgetValue } from '../format.js';
+import { safeHref } from '../markdown.js';
+import type { WidgetComponentProps } from '../types.js';
+import { isRecord, type MetricWidgetData } from './data.js';
+
+let { data, locale }: WidgetComponentProps<MetricWidgetData> = $props();
+
+const { t } = useI18n();
+const metric = $derived(isRecord(data) ? data : null);
+const valid = $derived(
+  metric !== null &&
+    typeof metric.value === 'number' &&
+    Number.isFinite(metric.value),
+);
+const text = $derived(
+  valid && metric
+    ? formatWidgetValue(metric.value, {
+        format: metric.format,
+        currency: metric.currency,
+        locale,
+      })
+    : '',
+);
+const change = $derived(
+  metric && typeof metric.change === 'number' && Number.isFinite(metric.change)
+    ? metric.change
+    : null,
+);
+const changeText = $derived(
+  change === null || change === 0
+    ? ''
+    : t(
+        M[
+          change > 0
+            ? 'ui.overview.metric.change_up'
+            : 'ui.overview.metric.change_down'
+        ],
+        {
+          value: formatWidgetValue(Math.abs(change) / 100, {
+            format: 'percent',
+            locale,
+          }),
+        },
+      ),
+);
+const href = $derived(
+  metric && typeof metric.href === 'string' ? safeHref(metric.href) : null,
+);
+</script>
+
+{#if valid && metric}
+  <div class="smrt-metric">
+    {#if href}
+      <a class="smrt-metric__value" {href}>{text}</a>
+    {:else}
+      <p class="smrt-metric__value">{text}</p>
+    {/if}
+    {#if typeof metric.label === 'string' && metric.label}
+      <p class="smrt-metric__label">{metric.label}</p>
+    {/if}
+    {#if changeText}
+      <p class="smrt-metric__change" data-direction={(change ?? 0) > 0 ? 'up' : 'down'}>
+        <span aria-hidden="true">{(change ?? 0) > 0 ? '▲' : '▼'}</span>
+        {changeText}
+      </p>
+    {/if}
+  </div>
+{:else}
+  <p class="smrt-metric__label">{t(M['ui.overview.no_data'])}</p>
+{/if}
+
+<style>
+  .smrt-metric { display: grid; gap: var(--smrt-spacing-1); }
+  .smrt-metric__value { margin: 0; color: var(--smrt-color-on-surface); font-size: var(--smrt-typography-display-small-size, 2rem); font-weight: var(--smrt-typography-weight-medium, 500); line-height: 1.1; text-decoration: none; font-variant-numeric: tabular-nums; }
+  a.smrt-metric__value:hover { text-decoration: underline; }
+  a.smrt-metric__value:focus-visible { outline: 2px solid var(--smrt-color-primary); outline-offset: 2px; border-radius: var(--smrt-radius-small, 0.25rem); }
+  .smrt-metric__label { margin: 0; color: var(--smrt-color-on-surface-variant); font-size: var(--smrt-typography-body-medium-size, 0.875rem); }
+  .smrt-metric__change { margin: 0; color: var(--smrt-color-on-surface-variant); font-size: var(--smrt-typography-label-large-size, 0.875rem); }
+</style>

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

@@ -0,0 +1,6 @@
+import type { WidgetComponentProps } from '../types.js';
+import { type MetricWidgetData } from './data.js';
+declare const MetricWidget: import("svelte").Component<WidgetComponentProps<MetricWidgetData>, {}, "">;
+type MetricWidget = ReturnType<typeof MetricWidget>;
+export default MetricWidget;
+//# sourceMappingURL=MetricWidget.svelte.d.ts.map

package/dist/components/overview/widgets/MetricWidget.svelte.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MetricWidget.svelte.d.ts","sourceRoot":"","sources":["../../../../src/components/overview/widgets/MetricWidget.svelte.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACxD,OAAO,EAAY,KAAK,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAiF5D,QAAA,MAAM,YAAY,4EAAwC,CAAC;AAC3D,KAAK,YAAY,GAAG,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC;AACpD,eAAe,YAAY,CAAC"}

package/dist/components/overview/widgets/NoteWidget.svelte

@@ -0,0 +1,61 @@
+<script lang="ts">
+/**
+ * Note widget (#3727): sanitized Markdown from the `body` option. It renders
+ * a parsed node tree as Svelte elements, never `{@html}`, so stored text
+ * cannot inject markup or an unsafe link.
+ */
+import { useI18n } from '@happyvertical/smrt-ui/i18n';
+import { M } from '../../../i18n/strings.overview.js';
+import { type InlineNode, parseMarkdown } from '../markdown.js';
+import type { WidgetComponentProps } from '../types.js';
+
+let { options }: WidgetComponentProps = $props();
+
+const { t } = useI18n();
+const blocks = $derived(
+  parseMarkdown(typeof options.body === 'string' ? options.body : ''),
+);
+</script>
+
+{#snippet inline(nodes: InlineNode[])}
+  {#each nodes as node, index (index)}
+    {#if node.type === 'text'}{node.text}{:else if node.type === 'code'}<code>{node.text}</code>{:else if node.type === 'strong'}<strong>{@render inline(node.children)}</strong>{:else if node.type === 'em'}<em>{@render inline(node.children)}</em>{:else if node.type === 'link'}<a href={node.href} rel="noopener noreferrer">{@render inline(node.children)}</a>{/if}
+  {/each}
+{/snippet}
+
+{#if blocks.length === 0}
+  <p class="smrt-note__empty">{t(M['ui.overview.no_data'])}</p>
+{:else}
+  <div class="smrt-note">
+    {#each blocks as block, index (index)}
+      {#if block.type === 'heading'}
+        <p class="smrt-note__heading" data-level={block.level}><strong>{@render inline(block.children)}</strong></p>
+      {:else if block.type === 'paragraph'}
+        <p>{@render inline(block.children)}</p>
+      {:else if block.type === 'quote'}
+        <blockquote>{@render inline(block.children)}</blockquote>
+      {:else if block.type === 'list'}
+        {#if block.ordered}
+          <ol>{#each block.items as item, i (i)}<li>{@render inline(item)}</li>{/each}</ol>
+        {:else}
+          <ul>{#each block.items as item, i (i)}<li>{@render inline(item)}</li>{/each}</ul>
+        {/if}
+      {:else if block.type === 'code'}
+        <pre><code>{block.text}</code></pre>
+      {/if}
+    {/each}
+  </div>
+{/if}
+
+<style>
+  .smrt-note { display: grid; gap: var(--smrt-spacing-2); color: var(--smrt-color-on-surface); font-size: var(--smrt-typography-body-medium-size, 0.875rem); overflow-wrap: anywhere; }
+  .smrt-note p, .smrt-note ul, .smrt-note ol, .smrt-note blockquote, .smrt-note pre { margin: 0; }
+  .smrt-note ul, .smrt-note ol { padding-inline-start: var(--smrt-spacing-5, 1.25rem); }
+  .smrt-note blockquote { padding-inline-start: var(--smrt-spacing-3); border-inline-start: 3px solid var(--smrt-color-outline-variant); color: var(--smrt-color-on-surface-variant); }
+  .smrt-note pre { overflow-x: auto; padding: var(--smrt-spacing-2); border-radius: var(--smrt-radius-small, 0.25rem); background: var(--smrt-color-surface-container); }
+  .smrt-note code { font-family: var(--smrt-font-family-mono, ui-monospace, monospace); }
+  .smrt-note a { color: var(--smrt-color-primary); }
+  .smrt-note__heading[data-level='1'] { font-size: var(--smrt-typography-title-large-size, 1.25rem); }
+  .smrt-note__heading[data-level='2'] { font-size: var(--smrt-typography-title-medium-size, 1.125rem); }
+  .smrt-note__empty { margin: 0; color: var(--smrt-color-on-surface-variant); }
+</style>

package/dist/components/overview/widgets/NoteWidget.svelte.d.ts

@@ -0,0 +1,5 @@
+import type { WidgetComponentProps } from '../types.js';
+declare const NoteWidget: import("svelte").Component<WidgetComponentProps<unknown>, {}, "">;
+type NoteWidget = ReturnType<typeof NoteWidget>;
+export default NoteWidget;
+//# sourceMappingURL=NoteWidget.svelte.d.ts.map

package/dist/components/overview/widgets/NoteWidget.svelte.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"NoteWidget.svelte.d.ts","sourceRoot":"","sources":["../../../../src/components/overview/widgets/NoteWidget.svelte.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAmDxD,QAAA,MAAM,UAAU,mEAAwC,CAAC;AACzD,KAAK,UAAU,GAAG,UAAU,CAAC,OAAO,UAAU,CAAC,CAAC;AAChD,eAAe,UAAU,CAAC"}

package/dist/components/overview/widgets/RecordListWidget.svelte

@@ -0,0 +1,91 @@
+<script lang="ts">
+/**
+ * Record list widget (#3727): the rows a loader chose, each optionally a
+ * link. The loader owns which field is the title and which records the viewer
+ * may see; the widget only draws what it is given.
+ */
+import { useI18n } from '@happyvertical/smrt-ui/i18n';
+import { M } from '../../../i18n/strings.overview.js';
+import { safeHref } from '../markdown.js';
+import type { WidgetComponentProps } from '../types.js';
+import { isRecord, type RecordListWidgetData } from './data.js';
+
+let { data, locale }: WidgetComponentProps<RecordListWidgetData> = $props();
+
+const { t } = useI18n();
+const MAX_ROWS = 50;
+
+interface Row {
+  id: string;
+  title: string;
+  subtitle?: string;
+  meta?: string;
+  href: string | null;
+}
+
+const rows = $derived.by((): Row[] => {
+  if (!isRecord(data) || !Array.isArray(data.rows)) return [];
+  const out: Row[] = [];
+  for (const row of data.rows.slice(0, MAX_ROWS)) {
+    if (!isRecord(row) || typeof row.title !== 'string') continue;
+    out.push({
+      id: typeof row.id === 'string' ? row.id : String(out.length),
+      title: row.title,
+      subtitle: typeof row.subtitle === 'string' ? row.subtitle : undefined,
+      meta: typeof row.meta === 'string' ? row.meta : undefined,
+      href: typeof row.href === 'string' ? safeHref(row.href) : null,
+    });
+  }
+  return out;
+});
+const total = $derived(
+  isRecord(data) && typeof data.total === 'number' && data.total > rows.length
+    ? data.total
+    : null,
+);
+const viewAll = $derived(
+  isRecord(data) && typeof data.href === 'string' ? safeHref(data.href) : null,
+);
+</script>
+
+{#if rows.length === 0}
+  <p class="smrt-records__empty">{t(M['ui.overview.records.empty'])}</p>
+{:else}
+  <ul class="smrt-records">
+    {#each rows as row (row.id)}
+      <li class="smrt-records__row">
+        <span class="smrt-records__main">
+          {#if row.href}
+            <a class="smrt-records__title" href={row.href}>{row.title}</a>
+          {:else}
+            <span class="smrt-records__title">{row.title}</span>
+          {/if}
+          {#if row.subtitle}<span class="smrt-records__sub">{row.subtitle}</span>{/if}
+        </span>
+        {#if row.meta}<span class="smrt-records__meta">{row.meta}</span>{/if}
+      </li>
+    {/each}
+  </ul>
+{/if}
+{#if total !== null || viewAll}
+  <p class="smrt-records__foot">
+    {#if total !== null}
+      <span>{t(M['ui.overview.records.total'], { count: new Intl.NumberFormat(locale).format(total) })}</span>
+    {/if}
+    {#if viewAll}<a href={viewAll}>{t(M['ui.overview.records.view_all'])}</a>{/if}
+  </p>
+{/if}
+
+<style>
+  .smrt-records { display: grid; margin: 0; padding: 0; list-style: none; }
+  .smrt-records__row { display: flex; align-items: baseline; justify-content: space-between; gap: var(--smrt-spacing-3); padding: var(--smrt-spacing-2) 0; border-block-end: 1px solid var(--smrt-color-outline-variant); }
+  .smrt-records__row:last-child { border-block-end: 0; }
+  .smrt-records__main { display: grid; min-inline-size: 0; }
+  .smrt-records__title { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; color: var(--smrt-color-on-surface); font-weight: var(--smrt-typography-weight-medium, 500); text-decoration: none; }
+  a.smrt-records__title:hover { text-decoration: underline; }
+  .smrt-records__sub, .smrt-records__meta { color: var(--smrt-color-on-surface-variant); font-size: var(--smrt-typography-body-medium-size, 0.875rem); }
+  .smrt-records__meta { flex: 0 0 auto; font-variant-numeric: tabular-nums; }
+  .smrt-records__foot { display: flex; justify-content: space-between; gap: var(--smrt-spacing-3); margin: var(--smrt-spacing-2) 0 0; color: var(--smrt-color-on-surface-variant); font-size: var(--smrt-typography-body-medium-size, 0.875rem); }
+  .smrt-records__foot a { color: var(--smrt-color-primary); }
+  .smrt-records__empty { margin: 0; color: var(--smrt-color-on-surface-variant); }
+</style>

package/dist/components/overview/widgets/RecordListWidget.svelte.d.ts

@@ -0,0 +1,6 @@
+import type { WidgetComponentProps } from '../types.js';
+import { type RecordListWidgetData } from './data.js';
+declare const RecordListWidget: import("svelte").Component<WidgetComponentProps<RecordListWidgetData>, {}, "">;
+type RecordListWidget = ReturnType<typeof RecordListWidget>;
+export default RecordListWidget;
+//# sourceMappingURL=RecordListWidget.svelte.d.ts.map

package/dist/components/overview/widgets/RecordListWidget.svelte.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RecordListWidget.svelte.d.ts","sourceRoot":"","sources":["../../../../src/components/overview/widgets/RecordListWidget.svelte.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACxD,OAAO,EAAY,KAAK,oBAAoB,EAAE,MAAM,WAAW,CAAC;AAgFhE,QAAA,MAAM,gBAAgB,gFAAwC,CAAC;AAC/D,KAAK,gBAAgB,GAAG,UAAU,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAC5D,eAAe,gBAAgB,CAAC"}