@happyvertical/smrt-ui 0.57.20 → 0.57.22

package/AGENTS.md

@@ -49,14 +49,16 @@ components are exempt — they *are* the primitives.
 | `./feedback` | `Alert`, `ToastViewport`, `Modal`, `Drawer`/`Sheet`, `ConfirmDialog`, `LoadingOverlay`, `Progress`, `Meter`, `Spinner`, phone surfaces `PhoneSheet` / `WorkingStrip` and the `swipeDismiss` action |
 | `./data` | `CollectionToolbar`, `CollectionList`/`ContentList`, `DataTable` (footer rows and column `summaries`: [agents/data-table.md](agents/data-table.md)) and their types — a **component barrel**: it re-exports `.svelte` files, so a plain Node `import()` of it throws `ERR_UNKNOWN_FILE_EXTENSION` |
 | `./data-surface` | **Svelte-free**: registry contracts and shared protocol limits (`DATA_SURFACE_MAX_REQUEST_BYTES`, `DATA_SURFACE_IDENTIFIER_MAX_LENGTH`, …). Server adapters must import these from here, not from `./data` — a server entry that reaches the barrel breaks the `smrt` CLI's plain-Node `.smrt/register.js` load (issue #2924) |
+| `./display` | `DocumentViewer` (touch PDF/image viewer reading through an injected `fetch`; pdf.js is an optional peer loaded lazily by `createPdfJsOpener()`), `CurrencyDisplay`, `DateDisplay`, `StatusBadge`, `Icon`; also re-exported from `.` |
 | `./layout` | `Container`, `Grid`, `Header`, `Footer`, `PageHeader`, `EmptyState`, … |
 | `./charts` | Pure `Chart` renderer (`bar`, `line`, `table`, `pie`, `stat`), structural `ChartData`, and minor-unit number formatting; `./charts/format` is Svelte-free |
 | `./calendar` | `CalendarView` (time-zone-aware month/week grids + phone agenda) and its Svelte-free date model (`toEntries`, `layoutMonth`, `layoutWeek`, `dateKeyInZone`, …); deprecated `Calendar`, `DayView` |
 | `./chat` | `MessageBubble`, `ReactionPicker`, `TypingIndicator` |
-| `./forms` | Provider-free fields, choice controls, sliders/ranges, combobox/listbox/multiselect/tags, date/time/file controls, `CameraCapture`/`SignaturePad` capture, plus the transport-neutral control interaction registry |
+| `./forms` | Provider-free fields, choice controls, sliders/ranges, combobox/listbox/multiselect/tags, date/time/file controls, `CameraCapture`/`SignaturePad` capture, `NumericKeypad` (quantity/money keypad; money as integer minor units via the Svelte-free `numeric-keypad-logic.ts`), plus the transport-neutral control interaction registry |
 | `.` permissions | `PermissionCheck` and the domain-agnostic `PermissionPicker` for grouped, searchable native role-grant forms over host-supplied catalog records |
 | `./form-retry` | **Svelte-free** form retry (#3291): submission key, in-flight refusal, conditional reset, opt-in restore-after-reload, browser `runOnce()` digest. Also re-exported from `./forms`. Framework-free TS typed structurally against SvelteKit's `SubmitFunction` — never import `@sveltejs/kit` here. Guide: `docs/content/form-retry.md` |
 | `./i18n` | i18n **client**: `useI18n`, `<Trans>`, `defineMessages`, `renderTemplate` (no `smrt-languages` import — the server resolver stays in `smrt-svelte/i18n/server`) |
+| `./analytics` | Optional provider-neutral Svelte context for static shared component outcomes; noop without a host sink. No Matomo dependency. Browser provider lives in smrt-analytics. |
 | `./registry` | `ModuleUIRegistry` for cross-package component discovery |
 | `./theme` | deprecated compatibility path forwarding to the canonical theme system |
 | `./themes` | canonical `ThemeProvider`, context, preset token system (material/glass/studio/smrt/happyvertical), and CSS generation |
@@ -181,6 +183,15 @@ other text pairing clears WCAG AA in both schemes.
   their form's reset (`attachFormResetListener`), even while `disabled`;
   otherwise the UI shows a file the next submit no longer posts.
 
+- **Touch viewers and keypads (#3463).** `DocumentViewer` never puts the API
+  URL in an `<img>`/`<iframe>`: it reads through `fetch` and shows blobs, and
+  revokes them on cleanup. `pdfjs-dist` is an *optional peer*: only
+  `display/pdf-opener.ts` imports it (dynamically, itself loaded lazily), so a
+  missing engine shows the `unsupported` state and nothing else breaks. Keep
+  zoom/scale rules in `document-viewer-logic.ts`. `NumericKeypad` money mode is
+  integer minor units end to end (string math, never floats); entry rules stay
+  in `numeric-keypad-logic.ts`. Keys use `max(4rem, --smrt-touch-target-min)`.
+
 - **i18n split**: the client (here) is dependency-free; the Node-only server
   resolver (`buildI18nSnapshot`, → `@happyvertical/smrt-languages`) stays in
   `@happyvertical/smrt-svelte/i18n/server`. Package string catalogs register via

package/README.md

@@ -36,6 +36,7 @@ pnpm add @happyvertical/smrt-ui
 | Choices | `Checkbox`, `RadioGroup`/`Radio`, `Switch`, `Toggle`, `ToggleButton`, `SegmentedControl` |
 | Values and files | `Slider`, `RangeSlider`, `DatePicker`, `TimePicker`, `FilePicker` |
 | Capture | `CameraCapture`, `SignaturePad` |
+| Touch entry and viewing | `NumericKeypad` (`/forms`), `DocumentViewer` (`/display`) |
 | Actions and display | `Button`, `Dropdown`/`Menu`, `Badge`, `Chip`, `Avatar`, `Card`, `Skeleton`, `Tooltip`, `Tree` |
 | Disclosure and overlays | `Popover`, `Disclosure`, `Accordion`/`AccordionItem`, `Modal`, `Drawer`/`Sheet`, `PhoneSheet`, `ConfirmDialog` |
 | Feedback | `Alert`, `ToastViewport`, `Progress`, `Meter`, `Spinner`, `LoadingOverlay`, `WorkingStrip` |
@@ -657,6 +658,96 @@ least `--smrt-touch-target-min` (48px by default; see
 Both register with an enclosing `Form`'s interaction registry as non-readable,
 non-writable `file` controls.
 
+## Touch keypad and document viewer
+
+Two controls for gloved, tablet-first use. Every key and control is at least
+4rem square (or `--smrt-touch-target-min`, whichever is larger).
+
+### NumericKeypad
+
+```svelte
+<script lang="ts">
+  import { NumericKeypad } from '@happyvertical/smrt-ui/forms';
+  let price = $state('');
+</script>
+
+<NumericKeypad
+  bind:value={price}
+  mode="money"
+  currency="CAD"
+  prefix="$"
+  min={0.01}
+  onSubmit={({ minorUnits }) => save(minorUnits)}
+  name="price"
+/>
+```
+
+`value` is the typed text (`"12.5"`; a number is accepted). A 3x4 grid holds
+the digits, a decimal point (only when `maxDecimals` > 0) and backspace; Clear
+sits beside the display and the confirm key (text `submitLabel`) appears when
+`onSubmit` is given. `onChange` / `onSubmit` receive `{ text, number,
+minorUnits, valid }`. A value outside `min` / `max` shows an error and blocks
+confirm; `clampToMax` refuses a press that would exceed `max`. `maxLength`
+caps the typed text (default 12).
+
+`mode="money"` keeps integer minor units: the decimals allowed follow the
+currency's ISO 4217 exponent (`currency`, or `minorUnitExponent`), `minorUnits`
+is computed by string arithmetic and never a float, and a `name` posts the
+integer minor units (in `number` mode it posts the typed text).
+Money amounts beyond JavaScript's safe integer minor-unit range are invalid
+and cannot be confirmed, including when `maxLength` is increased. The pure
+helpers `textToMinorUnits()`, `minorUnitsToText()`, `minorUnitExponent()`,
+`applyKeypadKey()` and `validateKeypadEntry()` are exported from `/forms`.
+
+Hardware keys work while focus is inside the keypad: digits, `.` or `,` for the
+point, Backspace, Delete (clear) and Enter (confirm, when the keypad itself has
+focus). The root is a `group`, the display is a polite live `output`, and every
+key has an `aria-label`. This is a quantity/money pad, not a PIN pad: the typed
+value is shown as text. Text comes from `ui.numeric_keypad.*` and `labels`.
+
+### DocumentViewer
+
+```svelte
+<script lang="ts">
+  import { DocumentViewer, createPdfJsOpener } from '@happyvertical/smrt-ui/display';
+  import workerSrc from 'pdfjs-dist/legacy/build/pdf.worker.min.mjs?url';
+  // Literal imports here let YOUR bundler include pdf.js.
+  const openPdf = createPdfJsOpener({
+    workerSrc,
+    loadLibrary: () => import('pdfjs-dist/legacy/build/pdf.mjs'),
+  });
+</script>
+
+<DocumentViewer src="/api/prints/42/file" mimeType="application/pdf"
+  label="Bracket, rev C" fetch={authedFetch} {openPdf} />
+```
+
+The file is read through `fetch` (default: the global one; inject the app's
+authenticated fetch) and shown from a blob. It never sets `<img src>` or
+`<iframe src>` to `src`, so it works in an embedded WebView that only
+authenticates through the app's own fetch and has no built-in PDF viewer. Blob
+URLs are revoked on cleanup. `mimeType` may be omitted, then the response's
+Content-Type decides. Controls: previous / next with "Page N of M", zoom out /
+Fit / zoom in (1, 1.5, 2, 3, 4, 5), and a two-finger pinch; a zoomed document
+scrolls inside its sheet. States (the root's `data-state`): `loading`,
+`ready`, `failed` (with "Try again"), and `unsupported` (an unknown type, or no
+PDF engine). Text comes from `ui.document_viewer.*` and `labels`.
+
+**PDFs** are drawn by an `OpenPdf` (`(bytes) => Promise<PdfDocument>` where a
+`PdfDocument` is `{ pages, renderPage(page, canvas, cssWidth), destroy() }`).
+Inject your own, or omit it for the default, `createPdfJsOpener()`, which
+uses `pdfjs-dist`'s legacy build. `pdfjs-dist` is an **optional peer
+dependency**: install it only if you show PDFs; images need nothing. It is
+loaded on the first PDF, and if it is missing the viewer shows `unsupported`.
+The default opener loads it through a variable specifier so an app without
+pdfjs-dist still builds; that means a bundler does not include pdf.js by default.
+An app that wants it bundled passes `loadLibrary` (as above) and `workerSrc`.
+Pass `workerSrc` (a URL such as Vite's `?url` import of
+`pdf.worker.min.mjs`) to render off the main thread; without it the worker
+module is imported and runs on the main thread, which needs no bundler URL
+handling. The canvas is capped at 4096 x 4096 device pixels; zooming past it
+enlarges on screen instead.
+
 ## DataTable controller
 
 `DataTable` can share one headless `DataTableController` between rendered

package/dist/analytics/index.d.ts

@@ -0,0 +1,17 @@
+/** Static standard outcomes and engagement; never includes component data. */
+export type StandardAnalyticsEvent = 'planner_opened' | 'planner_cookbook_applied' | 'project_question_answered' | 'project_decision_resolved' | 'project_preview_opened' | 'project_preview_approved' | 'project_preview_rejected';
+/** Optional private receipt identity, used only for in-memory duplicate suppression. */
+export interface AnalyticsEmissionOptions {
+    dedupeKey?: string;
+}
+export type AnalyticsSink = (name: string, options?: AnalyticsEmissionOptions) => unknown;
+/** Install once during the host root component's initialization. No SSR globals. */
+export declare function setAnalyticsContext(sink: AnalyticsSink): void;
+/** Capture during component initialization; absent configuration is a noop. */
+export declare function getAnalyticsContext(): AnalyticsSink;
+/** Observe only persisted status changes; initial/historical rows are not events. */
+export declare function createAnalyticsTransitions(emit: (name: StandardAnalyticsEvent) => unknown): (rows: readonly {
+    id: string;
+    status: string;
+}[], from: string, outcomes: Readonly<Record<string, StandardAnalyticsEvent>>) => void;
+//# sourceMappingURL=index.d.ts.map

package/dist/analytics/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/analytics/index.ts"],"names":[],"mappings":"AAEA,8EAA8E;AAC9E,MAAM,MAAM,sBAAsB,GAC9B,gBAAgB,GAChB,0BAA0B,GAC1B,2BAA2B,GAC3B,2BAA2B,GAC3B,wBAAwB,GACxB,0BAA0B,GAC1B,0BAA0B,CAAC;AAC/B,wFAAwF;AACxF,MAAM,WAAW,wBAAwB;IACvC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AACD,MAAM,MAAM,aAAa,GAAG,CAC1B,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,wBAAwB,KAC/B,OAAO,CAAC;AAIb,oFAAoF;AACpF,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,aAAa,GAAG,IAAI,CAE7D;AACD,+EAA+E;AAC/E,wBAAgB,mBAAmB,IAAI,aAAa,CASnD;AAED,qFAAqF;AACrF,wBAAgB,0BAA0B,CACxC,IAAI,EAAE,CAAC,IAAI,EAAE,sBAAsB,KAAK,OAAO,IAI7C,MAAM,SAAS;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,EAAE,EAC/C,MAAM,MAAM,EACZ,UAAU,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAAC,UAmB7D"}

package/dist/analytics/index.js

@@ -0,0 +1,43 @@
+import { getContext, setContext } from 'svelte';
+const KEY = Symbol.for('@happyvertical/smrt-ui/analytics');
+const noop = () => { };
+/** Install once during the host root component's initialization. No SSR globals. */
+export function setAnalyticsContext(sink) {
+    setContext(KEY, sink);
+}
+/** Capture during component initialization; absent configuration is a noop. */
+export function getAnalyticsContext() {
+    const sink = getContext(KEY) ?? noop;
+    return (name, options) => {
+        try {
+            Promise.resolve(sink(name, options)).catch(() => { });
+        }
+        catch {
+            /* analytics never breaks UI */
+        }
+    };
+}
+/** Observe only persisted status changes; initial/historical rows are not events. */
+export function createAnalyticsTransitions(emit) {
+    const seen = new Map();
+    return (rows, from, outcomes) => {
+        const present = new Set(rows.map((row) => row.id));
+        for (const id of seen.keys()) {
+            if (!present.has(id))
+                seen.delete(id);
+        }
+        for (const row of rows) {
+            const previous = seen.get(row.id);
+            seen.set(row.id, row.status);
+            const outcome = outcomes[row.status];
+            if (previous === from && outcome) {
+                try {
+                    Promise.resolve(emit(outcome)).catch(() => { });
+                }
+                catch {
+                    /* no UI failures */
+                }
+            }
+        }
+    };
+}

package/dist/components/display/DocumentViewer.svelte

@@ -0,0 +1,443 @@
+<!--
+  A PDF or picture, readable on a touch screen (smrt#3463).
+
+  The file is read through `fetch` (inject the app's own authenticated one) and
+  shown from a blob: never an <img src> or <iframe src> on the API, because an
+  embedded WebView may only authenticate through the app's fetch and often has
+  no built-in PDF viewer. A PDF is drawn page by page onto a canvas by an
+  `OpenPdf` (default: pdf.js through `createPdfJsOpener()`, an optional peer
+  dependency; images need nothing).
+
+  Controls are at least 4rem: previous / next with "Page N of M", zoom out /
+  Fit / zoom in (1, 1.5, 2, 3, 4, 5), and a two-finger pinch does the same. A
+  zoomed document scrolls inside its sheet. States: loading, failed (with
+  Try again), unsupported type, and unsupported engine.
+
+  Ported from teamworks-os `PrintViewer.svelte`.
+-->
+<script lang="ts">
+import { M, useI18n } from '../../i18n/index.js';
+import { renderTemplate } from '../../i18n/render.js';
+import {
+  clampPage,
+  clampPinchScale,
+  commitPinchZoom,
+  isImageType,
+  isPdfType,
+  MAX_ZOOM,
+  MIN_ZOOM,
+  stepZoom,
+} from './document-viewer-logic.js';
+import {
+  type OpenPdf,
+  type PdfDocument,
+  PdfEngineUnavailableError,
+} from './pdf-types.js';
+import type { DocumentViewerLabels } from './types.js';
+
+export interface Props {
+  /** URL of the file; read with `fetch`. */
+  src: string;
+  /** `application/pdf` or `image/*`. Omitted, the response's Content-Type decides. */
+  mimeType?: string;
+  /** Names the document for assistive technology (the image alt, the page canvas). */
+  label: string;
+  /** Reads the file; inject the app's authenticated fetch. Default: global `fetch`. */
+  fetch?: typeof globalThis.fetch;
+  /** Opens PDF bytes. Default: pdf.js via `createPdfJsOpener()`. */
+  openPdf?: OpenPdf;
+  /** Text overrides; defaults come from the `ui` i18n catalog. */
+  labels?: Partial<DocumentViewerLabels>;
+  /** DOM id of the component root. */
+  id?: string;
+  /** CSS class to apply to the component root. */
+  class?: string;
+}
+
+let {
+  src,
+  mimeType,
+  label,
+  fetch: fetchImpl,
+  openPdf,
+  labels,
+  id,
+  class: className = '',
+}: Props = $props();
+
+const { t } = useI18n();
+const text = $derived<DocumentViewerLabels>({
+  region: t(M['ui.document_viewer.region']),
+  pages: t(M['ui.document_viewer.pages']),
+  zoom: t(M['ui.document_viewer.zoom']),
+  previousPage: t(M['ui.document_viewer.previous_page']),
+  nextPage: t(M['ui.document_viewer.next_page']),
+  pageOf: t(M['ui.document_viewer.page_of']),
+  pageLabel: t(M['ui.document_viewer.page_label']),
+  zoomOut: t(M['ui.document_viewer.zoom_out']),
+  zoomIn: t(M['ui.document_viewer.zoom_in']),
+  fit: t(M['ui.document_viewer.fit']),
+  loading: t(M['ui.document_viewer.loading']),
+  failed: t(M['ui.document_viewer.failed']),
+  retry: t(M['ui.document_viewer.retry']),
+  unsupported: t(M['ui.document_viewer.unsupported']),
+  ...labels,
+});
+
+type Status = 'loading' | 'ready' | 'failed' | 'unsupported';
+
+let status = $state<Status>('loading');
+let kind = $state<'pdf' | 'image' | null>(null);
+let imageUrl = $state<string | null>(null);
+let pdf = $state.raw<PdfDocument | null>(null);
+let page = $state(1);
+let zoom = $state(MIN_ZOOM);
+/** Live scale while two fingers pinch; committed to `zoom` when they lift. */
+let pinchScale = $state(1);
+let attempt = $state(0);
+let width = $state(0);
+let canvas = $state<HTMLCanvasElement | null>(null);
+
+function kindOf(type: string | null | undefined): 'pdf' | 'image' | null {
+  if (!type) return null;
+  if (isPdfType(type)) return 'pdf';
+  if (isImageType(type)) return 'image';
+  return null;
+}
+
+async function defaultOpenPdf(bytes: Uint8Array): Promise<PdfDocument> {
+  // Loaded on demand so a consumer without pdfjs-dist never pulls it in.
+  try {
+    const { createPdfJsOpener } = await import('./pdf-opener.js');
+    openerFallback ??= createPdfJsOpener();
+  } catch (error) {
+    throw new PdfEngineUnavailableError(
+      error instanceof Error ? error.message : undefined,
+    );
+  }
+  return openerFallback(bytes);
+}
+let openerFallback: OpenPdf | undefined;
+
+// Read the file whenever the source (or a retry) changes; release the last one.
+$effect(() => {
+  const href = src;
+  const declared = mimeType;
+  const reader = fetchImpl ?? globalThis.fetch.bind(globalThis);
+  const open = openPdf ?? defaultOpenPdf;
+  void attempt;
+  let live = true;
+  let url: string | null = null;
+  let opened: PdfDocument | null = null;
+  status = 'loading';
+  imageUrl = null;
+  pdf = null;
+  kind = kindOf(declared);
+  page = 1;
+  zoom = MIN_ZOOM;
+  pinchScale = 1;
+  if (declared !== undefined && kindOf(declared) === null) {
+    status = 'unsupported';
+    return;
+  }
+  void (async () => {
+    try {
+      const response = await reader(href, {
+        credentials: 'same-origin',
+        cache: 'no-store',
+      });
+      if (!response.ok) throw new Error(String(response.status));
+      const resolved =
+        kindOf(declared) ?? kindOf(response.headers?.get('content-type'));
+      if (!live) return;
+      if (resolved === null) {
+        status = 'unsupported';
+        return;
+      }
+      kind = resolved;
+      if (resolved === 'pdf') {
+        const bytes = new Uint8Array(await response.arrayBuffer());
+        if (!live) return;
+        opened = await open(bytes);
+        if (!live) {
+          void opened.destroy();
+          opened = null;
+          return;
+        }
+        pdf = opened;
+      } else {
+        const blob = await response.blob();
+        if (!live) return;
+        url = URL.createObjectURL(blob);
+        imageUrl = url;
+      }
+      status = 'ready';
+    } catch (error) {
+      if (!live) return;
+      status =
+        error instanceof PdfEngineUnavailableError ? 'unsupported' : 'failed';
+    }
+  })();
+  return () => {
+    live = false;
+    if (url) URL.revokeObjectURL(url);
+    if (opened) void opened.destroy();
+  };
+});
+
+// Draw the page at the sheet's width times the zoom.
+$effect(() => {
+  const doc = pdf;
+  const target = canvas;
+  const at = page;
+  const cssWidth = (width || 800) * zoom;
+  if (!doc || !target) return;
+  doc.renderPage(at, target, cssWidth).catch(() => {
+    if (pdf === doc) status = 'failed';
+  });
+});
+
+function step(delta: number): void {
+  if (!pdf) return;
+  page = clampPage(page, delta, pdf.pages);
+}
+
+// Pinch: two pointers on the sheet; the distance between them scales the file.
+const pointers = new Map<number, { x: number; y: number }>();
+let pinchStart = 0;
+function distance(): number {
+  const [a, b] = [...pointers.values()];
+  return a && b ? Math.hypot(a.x - b.x, a.y - b.y) : 0;
+}
+function pointerDown(event: PointerEvent): void {
+  pointers.set(event.pointerId, { x: event.clientX, y: event.clientY });
+  // Keep receiving moves when a finger drifts outside the sheet.
+  (event.currentTarget as HTMLElement | null)?.setPointerCapture?.(
+    event.pointerId,
+  );
+  if (pointers.size === 2) pinchStart = distance();
+}
+function pointerMove(event: PointerEvent): void {
+  if (!pointers.has(event.pointerId)) return;
+  pointers.set(event.pointerId, { x: event.clientX, y: event.clientY });
+  if (pointers.size === 2 && pinchStart > 0) {
+    pinchScale = clampPinchScale(zoom, distance() / pinchStart);
+  }
+}
+function pointerUp(event: PointerEvent): void {
+  pointers.delete(event.pointerId);
+  if (pointers.size < 2 && pinchStart > 0) {
+    zoom = commitPinchZoom(zoom, pinchScale);
+    pinchScale = 1;
+    pinchStart = 0;
+  }
+}
+</script>
+
+<div
+  id={id}
+  class="document-viewer {className}"
+  role="group"
+  aria-label={label}
+  data-state={status}
+  data-kind={kind ?? undefined}
+  data-smrt-component="DocumentViewer"
+>
+  <div class="controls" data-smrt-part="controls">
+    {#if pdf && pdf.pages > 1}
+      <div class="group" role="group" aria-label={text.pages}>
+        <button
+          type="button"
+          class="ctl"
+          data-smrt-part="control"
+          data-control="previous"
+          aria-label={text.previousPage}
+          disabled={page <= 1}
+          onclick={() => step(-1)}
+        >
+          <span aria-hidden="true">◀</span>
+        </button>
+        <span class="where" data-smrt-part="page-indicator" aria-live="polite">
+          {renderTemplate(text.pageOf, { page, pages: pdf.pages })}
+        </span>
+        <button
+          type="button"
+          class="ctl"
+          data-smrt-part="control"
+          data-control="next"
+          aria-label={text.nextPage}
+          disabled={page >= pdf.pages}
+          onclick={() => step(1)}
+        >
+          <span aria-hidden="true">▶</span>
+        </button>
+      </div>
+    {/if}
+    {#if status === 'ready'}
+      <div class="group" role="group" aria-label={text.zoom}>
+        <button
+          type="button"
+          class="ctl"
+          data-smrt-part="control"
+          data-control="zoom-out"
+          aria-label={text.zoomOut}
+          disabled={zoom <= MIN_ZOOM}
+          onclick={() => (zoom = stepZoom(zoom, -1))}
+        >
+          <span aria-hidden="true">−</span>
+        </button>
+        <button
+          type="button"
+          class="ctl fit"
+          data-smrt-part="control"
+          data-control="fit"
+          disabled={zoom === MIN_ZOOM}
+          onclick={() => (zoom = MIN_ZOOM)}
+        >
+          {text.fit}
+        </button>
+        <button
+          type="button"
+          class="ctl"
+          data-smrt-part="control"
+          data-control="zoom-in"
+          aria-label={text.zoomIn}
+          disabled={zoom >= MAX_ZOOM}
+          onclick={() => (zoom = stepZoom(zoom, 1))}
+        >
+          <span aria-hidden="true">+</span>
+        </button>
+      </div>
+    {/if}
+  </div>
+
+  <!-- svelte-ignore a11y_no_static_element_interactions (pinch is a shortcut; zoom out / Fit / zoom in are the controls) -->
+  <div
+    class="sheet"
+    data-smrt-part="sheet"
+    data-zoom={zoom}
+    bind:clientWidth={width}
+    onpointerdown={pointerDown}
+    onpointermove={pointerMove}
+    onpointerup={pointerUp}
+    onpointercancel={pointerUp}
+  >
+    {#if status === 'loading'}
+      <p class="hold" data-smrt-part="loading" role="status">{text.loading}</p>
+    {:else if status === 'failed'}
+      <div class="hold" data-smrt-part="failed">
+        <p role="alert">{text.failed}</p>
+        <button
+          type="button"
+          class="ctl retry"
+          data-smrt-part="control"
+          data-control="retry"
+          onclick={() => (attempt += 1)}
+        >
+          {text.retry}
+        </button>
+      </div>
+    {:else if status === 'unsupported'}
+      <p class="hold" data-smrt-part="unsupported" role="status">{text.unsupported}</p>
+    {:else if kind === 'pdf'}
+      <canvas
+        bind:this={canvas}
+        aria-label={renderTemplate(text.pageLabel, { label, page })}
+        style:transform={pinchScale === 1 ? null : `scale(${pinchScale})`}
+      ></canvas>
+    {:else if kind === 'image' && imageUrl}
+      <img
+        src={imageUrl}
+        alt={label}
+        style:width="{zoom * 100}%"
+        style:transform={pinchScale === 1 ? null : `scale(${pinchScale})`}
+      />
+    {/if}
+  </div>
+</div>
+
+<style>
+@layer smrt.reset, smrt.structure, smrt.theme;
+@layer smrt.theme {
+  .document-viewer {
+    display: grid;
+    gap: var(--smrt-spacing-3);
+    color: var(--smrt-color-on-surface);
+  }
+  .controls {
+    display: flex;
+    flex-wrap: wrap;
+    justify-content: space-between;
+    gap: var(--smrt-spacing-3);
+  }
+  .group {
+    display: flex;
+    align-items: center;
+    gap: var(--smrt-spacing-2);
+  }
+  /* Glove-size: at least 4rem square, whatever the density token says. */
+  .ctl {
+    min-width: max(4rem, var(--smrt-touch-target-min));
+    min-height: max(4rem, var(--smrt-touch-target-min));
+    padding: 0 var(--smrt-spacing-4);
+    border: var(--smrt-hairline-strong);
+    border-radius: var(--smrt-radius-medium);
+    background: var(--smrt-color-surface-container-highest);
+    color: var(--smrt-color-on-surface);
+    font: var(--smrt-typography-headline-large-font);
+    cursor: pointer;
+    touch-action: manipulation;
+  }
+  .ctl.fit,
+  .ctl.retry {
+    font: var(--smrt-typography-title-large-font);
+  }
+  .ctl:focus-visible {
+    outline: var(--smrt-focus-ring-width) solid var(--smrt-focus-ring-color);
+    outline-offset: var(--smrt-focus-ring-offset);
+  }
+  .ctl:disabled {
+    opacity: 0.5;
+    cursor: not-allowed;
+  }
+  .where {
+    min-width: 8rem;
+    text-align: center;
+    font: var(--smrt-typography-title-large-font);
+  }
+  /* The document's own sheet: scrolls when zoomed past its width. Paper stays
+     light in every scheme (a document is content, not chrome). */
+  .sheet {
+    display: grid;
+    justify-items: start;
+    align-items: start;
+    min-height: 24rem;
+    max-height: 70vh;
+    overflow: auto;
+    border: var(--smrt-hairline-strong);
+    border-radius: var(--smrt-radius-small);
+    background: var(--smrt-color-surface-container-lowest);
+    touch-action: pan-x pan-y;
+  }
+  canvas,
+  img {
+    display: block;
+    transform-origin: 0 0;
+  }
+  img {
+    max-width: none;
+    height: auto;
+  }
+  .hold {
+    display: grid;
+    gap: var(--smrt-spacing-4);
+    place-items: center;
+    align-self: center;
+    justify-self: center;
+    margin: 0;
+    padding: var(--smrt-spacing-8);
+    text-align: center;
+    font: var(--smrt-typography-title-large-font);
+  }
+}
+</style>

package/dist/components/display/DocumentViewer.svelte.d.ts

@@ -0,0 +1,24 @@
+import { type OpenPdf } from './pdf-types.js';
+import type { DocumentViewerLabels } from './types.js';
+export interface Props {
+    /** URL of the file; read with `fetch`. */
+    src: string;
+    /** `application/pdf` or `image/*`. Omitted, the response's Content-Type decides. */
+    mimeType?: string;
+    /** Names the document for assistive technology (the image alt, the page canvas). */
+    label: string;
+    /** Reads the file; inject the app's authenticated fetch. Default: global `fetch`. */
+    fetch?: typeof globalThis.fetch;
+    /** Opens PDF bytes. Default: pdf.js via `createPdfJsOpener()`. */
+    openPdf?: OpenPdf;
+    /** Text overrides; defaults come from the `ui` i18n catalog. */
+    labels?: Partial<DocumentViewerLabels>;
+    /** DOM id of the component root. */
+    id?: string;
+    /** CSS class to apply to the component root. */
+    class?: string;
+}
+declare const DocumentViewer: import("svelte").Component<Props, {}, "">;
+type DocumentViewer = ReturnType<typeof DocumentViewer>;
+export default DocumentViewer;
+//# sourceMappingURL=DocumentViewer.svelte.d.ts.map

package/dist/components/display/DocumentViewer.svelte.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DocumentViewer.svelte.d.ts","sourceRoot":"","sources":["../../../src/components/display/DocumentViewer.svelte.ts"],"names":[],"mappings":"AAeA,OAAO,EACL,KAAK,OAAO,EAGb,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAGvD,MAAM,WAAW,KAAK;IACpB,0CAA0C;IAC1C,GAAG,EAAE,MAAM,CAAC;IACZ,oFAAoF;IACpF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,oFAAoF;IACpF,KAAK,EAAE,MAAM,CAAC;IACd,qFAAqF;IACrF,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;IAChC,kEAAkE;IAClE,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,gEAAgE;IAChE,MAAM,CAAC,EAAE,OAAO,CAAC,oBAAoB,CAAC,CAAC;IACvC,oCAAoC;IACpC,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,gDAAgD;IAChD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAsPD,QAAA,MAAM,cAAc,2CAAwC,CAAC;AAC7D,KAAK,cAAc,GAAG,UAAU,CAAC,OAAO,cAAc,CAAC,CAAC;AACxD,eAAe,cAAc,CAAC"}