@happyvertical/smrt-ui 0.51.39 → 0.53.0

package/dist/components/forms/ready-beep.js

@@ -0,0 +1,82 @@
+/**
+ * A short "ready" beep, made with the Web Audio API (no sound files).
+ *
+ * Browsers only start audio after a user gesture. A long press fires from a
+ * timer while the finger is still down, which on touch screens is not a
+ * gesture yet, so `playReadyBeep` resolves `false` when the audio could not
+ * start; the host plays it again from the release (`pointerup` is a gesture).
+ * `primeReadyBeep` creates the audio context early, from a gesture, so later
+ * beeps start immediately.
+ */
+let context = null;
+function audioContextCtor() {
+    if (typeof window === 'undefined')
+        return null;
+    const w = window;
+    return (w.AudioContext ??
+        w.webkitAudioContext ??
+        null);
+}
+function getContext() {
+    if (context)
+        return context;
+    const Ctor = audioContextCtor();
+    if (!Ctor)
+        return null;
+    try {
+        context = new Ctor();
+    }
+    catch {
+        context = null;
+    }
+    return context;
+}
+/** Create (or wake) the audio context; call from a user gesture. */
+export function primeReadyBeep() {
+    const ctx = getContext();
+    if (ctx && ctx.state === 'suspended') {
+        void ctx.resume().catch(() => undefined);
+    }
+}
+/**
+ * Play two quick rising tones (about 0.2s). Resolves `true` when it played,
+ * `false` when audio is unavailable or not allowed yet.
+ */
+export async function playReadyBeep(options = {}) {
+    const ctx = getContext();
+    if (!ctx)
+        return false;
+    try {
+        if (ctx.state === 'suspended')
+            await ctx.resume();
+    }
+    catch {
+        return false;
+    }
+    if (ctx.state !== 'running')
+        return false;
+    const volume = Math.max(0, Math.min(1, options.volume ?? 0.12));
+    const start = ctx.currentTime + 0.01;
+    const tones = [
+        [660, 0],
+        [990, 0.1],
+    ];
+    for (const [frequency, at] of tones) {
+        const oscillator = ctx.createOscillator();
+        const gain = ctx.createGain();
+        oscillator.type = 'sine';
+        oscillator.frequency.value = frequency;
+        gain.gain.setValueAtTime(0, start + at);
+        gain.gain.linearRampToValueAtTime(volume, start + at + 0.01);
+        gain.gain.exponentialRampToValueAtTime(0.0001, start + at + 0.09);
+        oscillator.connect(gain);
+        gain.connect(ctx.destination);
+        oscillator.start(start + at);
+        oscillator.stop(start + at + 0.1);
+    }
+    return true;
+}
+/** Tests: forget the shared audio context. */
+export function resetReadyBeepForTests() {
+    context = null;
+}

package/dist/components/forms/signature-pad-logic.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Pure input logic for `SignaturePad.svelte`: the pointer-type gate and the
+ * pointer-to-canvas coordinate mapping. Free of DOM and settings dependencies
+ * so both are testable without a browser. The component takes `stylusOnly` as a
+ * prop the caller resolves (from a tenant setting, a device profile, …) and
+ * never decides it itself.
+ *
+ * Ported from teamworks-os `signature-pad-logic.ts`, smrt#3290.
+ */
+/** `PointerEvent.pointerType`; browsers may report values beyond the three known ones. */
+export type SignaturePointerType = 'pen' | 'touch' | 'mouse' | (string & {});
+/**
+ * Paper and ink colours for the signature bitmap. A signature is document
+ * content, not chrome: it stays dark ink on white paper in every theme and
+ * colour scheme, so the exported PNG reads the same wherever it is shown.
+ */
+export declare const SIGNATURE_PAPER_COLOR = "#ffffff";
+export declare const SIGNATURE_INK_COLOR = "#111111";
+/**
+ * Whether a pointer of `pointerType` may draw a stroke.
+ *
+ * With `stylusOnly`, only `pen` is accepted: finger and mouse input are
+ * ignored outright, since nothing at the pointer-event level can tell a
+ * gloved finger from a stylus. Otherwise pen, touch and mouse are accepted.
+ * Unknown pointer types are rejected in both modes.
+ */
+export declare function isAcceptedPointerType(pointerType: SignaturePointerType, stylusOnly: boolean): boolean;
+/** The subset of `DOMRect` the coordinate mapping needs. */
+export interface CanvasDisplayRect {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}
+/**
+ * Maps viewport `clientX`/`clientY` (CSS pixels) to the canvas's backing-pixel
+ * space.
+ *
+ * The canvas has a fixed backing resolution but is displayed at `width: 100%`,
+ * so the raw `clientX - rect.left` offset is only right when the displayed size
+ * happens to equal the backing size; anywhere else the ink drifts from the
+ * stylus and clips near the edges. Scaling by `backing / displayed` keeps them
+ * aligned. A zero-size rect (not laid out yet) falls back to 1:1 instead of
+ * dividing by zero.
+ */
+export declare function mapPointerToCanvasPoint(clientX: number, clientY: number, rect: CanvasDisplayRect, canvasWidth: number, canvasHeight: number): {
+    x: number;
+    y: number;
+};
+//# sourceMappingURL=signature-pad-logic.d.ts.map

package/dist/components/forms/signature-pad-logic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"signature-pad-logic.d.ts","sourceRoot":"","sources":["../../../src/components/forms/signature-pad-logic.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,0FAA0F;AAC1F,MAAM,MAAM,oBAAoB,GAAG,KAAK,GAAG,OAAO,GAAG,OAAO,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;AAE7E;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,YAAY,CAAC;AAC/C,eAAO,MAAM,mBAAmB,YAAY,CAAC;AAE7C;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,WAAW,EAAE,oBAAoB,EACjC,UAAU,EAAE,OAAO,GAClB,OAAO,CAKT;AAED,4DAA4D;AAC5D,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,iBAAiB,EACvB,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,GACnB;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,CAO1B"}

package/dist/components/forms/signature-pad-logic.js

@@ -0,0 +1,48 @@
+/**
+ * Pure input logic for `SignaturePad.svelte`: the pointer-type gate and the
+ * pointer-to-canvas coordinate mapping. Free of DOM and settings dependencies
+ * so both are testable without a browser. The component takes `stylusOnly` as a
+ * prop the caller resolves (from a tenant setting, a device profile, …) and
+ * never decides it itself.
+ *
+ * Ported from teamworks-os `signature-pad-logic.ts`, smrt#3290.
+ */
+/**
+ * Paper and ink colours for the signature bitmap. A signature is document
+ * content, not chrome: it stays dark ink on white paper in every theme and
+ * colour scheme, so the exported PNG reads the same wherever it is shown.
+ */
+export const SIGNATURE_PAPER_COLOR = '#ffffff';
+export const SIGNATURE_INK_COLOR = '#111111';
+/**
+ * Whether a pointer of `pointerType` may draw a stroke.
+ *
+ * With `stylusOnly`, only `pen` is accepted: finger and mouse input are
+ * ignored outright, since nothing at the pointer-event level can tell a
+ * gloved finger from a stylus. Otherwise pen, touch and mouse are accepted.
+ * Unknown pointer types are rejected in both modes.
+ */
+export function isAcceptedPointerType(pointerType, stylusOnly) {
+    if (stylusOnly)
+        return pointerType === 'pen';
+    return (pointerType === 'pen' || pointerType === 'touch' || pointerType === 'mouse');
+}
+/**
+ * Maps viewport `clientX`/`clientY` (CSS pixels) to the canvas's backing-pixel
+ * space.
+ *
+ * The canvas has a fixed backing resolution but is displayed at `width: 100%`,
+ * so the raw `clientX - rect.left` offset is only right when the displayed size
+ * happens to equal the backing size; anywhere else the ink drifts from the
+ * stylus and clips near the edges. Scaling by `backing / displayed` keeps them
+ * aligned. A zero-size rect (not laid out yet) falls back to 1:1 instead of
+ * dividing by zero.
+ */
+export function mapPointerToCanvasPoint(clientX, clientY, rect, canvasWidth, canvasHeight) {
+    const scaleX = rect.width > 0 ? canvasWidth / rect.width : 1;
+    const scaleY = rect.height > 0 ? canvasHeight / rect.height : 1;
+    return {
+        x: (clientX - rect.left) * scaleX,
+        y: (clientY - rect.top) * scaleY,
+    };
+}

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

@@ -11,4 +11,45 @@ export interface RangeSliderValue {
 export interface SegmentedControlOption extends ControlOption {
     icon?: string;
 }
+/** What `CameraCapture` and `SignaturePad` hand to `onCapture`. */
+export interface CaptureResult {
+    /** The encoded image (JPEG/PNG/WebP for photos, PNG for signatures). */
+    blob: Blob;
+    /** The same image as a `data:` URL, convenient for an inline preview. */
+    dataUrl: string;
+}
+/** Rendered states of `CameraCapture`, exposed as its `data-state` attribute. */
+export type CameraCaptureState = 'off' | 'starting' | 'streaming' | 'reviewing' | 'committed' | 'permission-denied' | 'no-camera' | 'unsupported' | 'error' | 'fallback';
+/** Text overrides for `CameraCapture`; defaults come from the `ui` i18n catalog. */
+export interface CameraCaptureLabels {
+    region: string;
+    preview: string;
+    starting: string;
+    off: string;
+    unsupported: string;
+    permissionDenied: string;
+    noCamera: string;
+    error: string;
+    retry: string;
+    capture: string;
+    retake: string;
+    usePhoto: string;
+    reviewAlt: string;
+    committedAlt: string;
+    committed: string;
+    choosePhoto: string;
+}
+/** Rendered states of `SignaturePad`, exposed as its `data-state` attribute. */
+export type SignaturePadState = 'empty' | 'signed' | 'committed';
+/** Text overrides for `SignaturePad`; defaults come from the `ui` i18n catalog. */
+export interface SignaturePadLabels {
+    region: string;
+    canvasEmpty: string;
+    canvasSigned: string;
+    hintAny: string;
+    hintStylus: string;
+    clear: string;
+    useSignature: string;
+    committed: string;
+}
 //# sourceMappingURL=types.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/components/forms/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAE9D,MAAM,WAAW,SAAS;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,sBAAuB,SAAQ,aAAa;IAC3D,IAAI,CAAC,EAAE,MAAM,CAAC;CACf"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/components/forms/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAE9D,MAAM,WAAW,SAAS;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,sBAAuB,SAAQ,aAAa;IAC3D,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,mEAAmE;AACnE,MAAM,WAAW,aAAa;IAC5B,wEAAwE;IACxE,IAAI,EAAE,IAAI,CAAC;IACX,yEAAyE;IACzE,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,iFAAiF;AACjF,MAAM,MAAM,kBAAkB,GAC1B,KAAK,GACL,UAAU,GACV,WAAW,GACX,WAAW,GACX,WAAW,GACX,mBAAmB,GACnB,WAAW,GACX,aAAa,GACb,OAAO,GACP,UAAU,CAAC;AAEf,oFAAoF;AACpF,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;IACZ,WAAW,EAAE,MAAM,CAAC;IACpB,gBAAgB,EAAE,MAAM,CAAC;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,gFAAgF;AAChF,MAAM,MAAM,iBAAiB,GAAG,OAAO,GAAG,QAAQ,GAAG,WAAW,CAAC;AAEjE,mFAAmF;AACnF,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;CACnB"}

package/dist/components/layout/PageHeader.svelte

@@ -1,41 +1,107 @@
 <script lang="ts">
 /**
- * PageHeader - Standard page header with optional back navigation
- * refactored for Material 3
+ * PageHeader - one header per page: an ancestors-only breadcrumb row, the
+ * page title (`<h1>`), and the page's own actions, right-aligned.
  *
- * Provides consistent page header layout with title, optional back link,
- * and slot for action buttons.
+ * Page-header contract (shared with AdminShell in smrt-svelte/workspace):
+ * - `crumbs` are the page's ancestors only, never the page itself; none on
+ *   section homes. Inside a shell that sets `setPageHeaderContext()`, pages
+ *   pass only `parents` (ancestors the nav doesn't know, e.g. the article
+ *   above its video) and the shell adds the rest; the shell also hears the
+ *   title (for its phone top bar). smrt-svelte's `shellPageTrailFor()`
+ *   computes such a trail from a nav.
+ * - The crumb row carries `data-shell-breadcrumbs` and the title
+ *   `data-shell-page-title`: on phones AdminShell hides the crumbs and
+ *   visually hides the title, because its phone top bar shows the back arrow
+ *   and the title instead.
+ * - No in-page back link: the crumbs (and the phone top bar) are the way
+ *   back. `backHref` is kept only for pages outside such a shell.
+ * - An editable title (`titleField`, e.g. an article's headline) renders
+ *   inside the `<h1>`, so the heading is still the page's title in the
+ *   outline and is named by the field's value, while the field keeps its own
+ *   label. Such a heading has no `data-shell-page-title`: it stays visible on
+ *   phones, because it is the input. Pass the live value as `title` so the
+ *   shell (the phone top bar) follows along as the person types.
  */
 import type { Snippet } from 'svelte';
 import { ripple } from '../../actions/ripple.js';
 import { Icon } from '../display/index.js';
+import {
+  getPageHeaderContext,
+  type PageHeaderCrumb,
+} from './page-header-context.js';
 
 export interface Props {
   /** Page title */
   title: string;
   /** Optional subtitle/description */
   subtitle?: string;
-  /** Back navigation URL */
+  /**
+   * All ancestors of this page, outermost first (never the page itself).
+   * Overrides the shell's trail; usually pass `parents` instead.
+   */
+  crumbs?: readonly PageHeaderCrumb[];
+  /** Ancestors past the shell's nav, outermost first. */
+  parents?: readonly PageHeaderCrumb[];
+  /** Shorter title for the shell (e.g. its phone top bar); default `title`. */
+  shortTitle?: string;
+  /** Accessible name of the breadcrumb nav. */
+  crumbsLabel?: string;
+  /**
+   * Back navigation URL.
+   * @deprecated Use `crumbs`; inside AdminShell the phone top bar goes back.
+   */
   backHref?: string;
   /** Back link label */
   backLabel?: string;
-  /** Slot for action buttons */
+  /**
+   * An editable title rendered inside the `<h1>` in place of `title`'s text
+   * (a labelled text field styled as the heading). `title` still names the
+   * page for the shell; keep it in sync with the field's value.
+   */
+  titleField?: Snippet;
+  /** Slot for action buttons (right-aligned beside the title) */
   actions?: Snippet;
-  /** Slot for additional content below title */
+  /** Small line under the title (status, dates, counts) */
+  meta?: Snippet;
+  /** Slot for additional content below the title row (e.g. page tabs) */
   children?: Snippet;
 }
 
 const {
   title,
   subtitle,
+  crumbs,
+  parents = [],
+  shortTitle,
+  crumbsLabel = 'Breadcrumb',
   backHref,
   backLabel = 'Back',
+  titleField,
   actions,
+  meta,
   children,
 }: Props = $props();
+
+const shell = getPageHeaderContext();
+const trail = $derived<readonly PageHeaderCrumb[]>(
+  crumbs ?? (shell ? shell.crumbs(parents) : parents),
+);
+
+$effect(() => shell?.report?.({ title: shortTitle ?? title, parents }));
 </script>
 
-<header class="page-header">
+<header class="page-header" data-page-header>
+  {#if trail.length > 0}
+    <nav class="page-crumbs" aria-label={crumbsLabel} data-shell-breadcrumbs>
+      <ol>
+        {#each trail as crumb, index (`${index}:${crumb.href}`)}
+          <li><a href={crumb.href}>{crumb.label}</a></li>
+        {/each}
+      </ol>
+    </nav>
+  {/if}
+
   <div class="header-main">
     <div class="header-content">
       {#if backHref}
@@ -44,10 +110,19 @@ const {
           <span>{backLabel}</span>
         </a>
       {/if}
-      <h1 class="page-title">{title}</h1>
+      {#if titleField}
+        <h1 class="page-title page-title-field" data-page-title-field>
+          {@render titleField()}
+        </h1>
+      {:else}
+        <h1 class="page-title" data-shell-page-title>{title}</h1>
+      {/if}
       {#if subtitle}
         <p class="page-subtitle">{subtitle}</p>
       {/if}
+      {#if meta}
+        <div class="page-meta">{@render meta()}</div>
+      {/if}
     </div>
 
     {#if actions}
@@ -58,7 +133,7 @@ const {
   </div>
 
   {#if children}
-    <div class="header-extra">
+    <div class="header-extra" data-page-header-extra>
       {@render children()}
     </div>
   {/if}
@@ -66,15 +141,60 @@ const {
 
 <style>
   .page-header {
-    margin-bottom: 2rem;
-    padding-top: 1rem;
+    margin-bottom: 1.5rem;
+  }
+
+  .page-crumbs {
+    margin-bottom: var(--smrt-spacing-1, 4px);
+    color: var(--smrt-color-on-surface-variant);
+    font: var(--smrt-typography-body-small-font);
+    font-size: 0.84rem;
+  }
+
+  .page-crumbs ol {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    gap: 0.35rem;
+    margin: 0;
+    padding: 0;
+    list-style: none;
+  }
+
+  .page-crumbs li {
+    display: flex;
+    align-items: center;
+    min-width: 0;
+  }
+
+  .page-crumbs li + li::before {
+    content: '/';
+    margin-inline-end: 0.35rem;
+    color: var(--smrt-color-outline);
+  }
+
+  .page-crumbs a {
+    color: inherit;
+    text-decoration: none;
+    overflow-wrap: anywhere;
+  }
+
+  .page-crumbs a:hover {
+    color: var(--smrt-color-primary);
+    text-decoration: underline;
+  }
+
+  .page-crumbs a:focus-visible {
+    outline: 2px solid var(--smrt-color-primary);
+    outline-offset: 2px;
+    border-radius: var(--smrt-radius-sm, 4px);
   }
 
   .header-main {
     display: flex;
     justify-content: space-between;
     align-items: flex-start;
-    gap: 1.5rem;
+    gap: 0.75rem 1.5rem;
     flex-wrap: wrap;
   }
 
@@ -83,7 +203,7 @@ const {
     flex-direction: column;
     gap: var(--smrt-spacing-1, 4px);
     flex: 1;
-    min-width: 200px;
+    min-width: min(100%, 200px);
   }
 
   .back-link {
@@ -109,13 +229,26 @@ const {
     color: var(--smrt-color-on-surface);
     margin: 0;
     letter-spacing: -0.5px;
+    overflow-wrap: anywhere;
+  }
+
+  .page-title-field {
+    min-width: 0;
   }
 
   .page-subtitle {
     font: var(--smrt-typography-body-medium-font);
     color: var(--smrt-color-on-surface-variant);
     margin: 0;
-    margin-top: var(--smrt-spacing-1, 4px);
+  }
+
+  .page-meta {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    gap: 0.5rem;
+    font: var(--smrt-typography-body-small-font);
+    color: var(--smrt-color-on-surface-variant);
   }
 
   .header-actions {
@@ -123,9 +256,10 @@ const {
     gap: 0.75rem;
     align-items: center;
     flex-wrap: wrap;
+    margin-inline-start: auto;
   }
 
   .header-extra {
-    margin-top: 1.5rem;
+    margin-top: 1rem;
   }
-</style>
+</style>

package/dist/components/layout/PageHeader.svelte.d.ts

@@ -1,23 +1,63 @@
 /**
- * PageHeader - Standard page header with optional back navigation
- * refactored for Material 3
+ * PageHeader - one header per page: an ancestors-only breadcrumb row, the
+ * page title (`<h1>`), and the page's own actions, right-aligned.
  *
- * Provides consistent page header layout with title, optional back link,
- * and slot for action buttons.
+ * Page-header contract (shared with AdminShell in smrt-svelte/workspace):
+ * - `crumbs` are the page's ancestors only, never the page itself; none on
+ *   section homes. Inside a shell that sets `setPageHeaderContext()`, pages
+ *   pass only `parents` (ancestors the nav doesn't know, e.g. the article
+ *   above its video) and the shell adds the rest; the shell also hears the
+ *   title (for its phone top bar). smrt-svelte's `shellPageTrailFor()`
+ *   computes such a trail from a nav.
+ * - The crumb row carries `data-shell-breadcrumbs` and the title
+ *   `data-shell-page-title`: on phones AdminShell hides the crumbs and
+ *   visually hides the title, because its phone top bar shows the back arrow
+ *   and the title instead.
+ * - No in-page back link: the crumbs (and the phone top bar) are the way
+ *   back. `backHref` is kept only for pages outside such a shell.
+ * - An editable title (`titleField`, e.g. an article's headline) renders
+ *   inside the `<h1>`, so the heading is still the page's title in the
+ *   outline and is named by the field's value, while the field keeps its own
+ *   label. Such a heading has no `data-shell-page-title`: it stays visible on
+ *   phones, because it is the input. Pass the live value as `title` so the
+ *   shell (the phone top bar) follows along as the person types.
  */
 import type { Snippet } from 'svelte';
+import { type PageHeaderCrumb } from './page-header-context.js';
 export interface Props {
     /** Page title */
     title: string;
     /** Optional subtitle/description */
     subtitle?: string;
-    /** Back navigation URL */
+    /**
+     * All ancestors of this page, outermost first (never the page itself).
+     * Overrides the shell's trail; usually pass `parents` instead.
+     */
+    crumbs?: readonly PageHeaderCrumb[];
+    /** Ancestors past the shell's nav, outermost first. */
+    parents?: readonly PageHeaderCrumb[];
+    /** Shorter title for the shell (e.g. its phone top bar); default `title`. */
+    shortTitle?: string;
+    /** Accessible name of the breadcrumb nav. */
+    crumbsLabel?: string;
+    /**
+     * Back navigation URL.
+     * @deprecated Use `crumbs`; inside AdminShell the phone top bar goes back.
+     */
     backHref?: string;
     /** Back link label */
     backLabel?: string;
-    /** Slot for action buttons */
+    /**
+     * An editable title rendered inside the `<h1>` in place of `title`'s text
+     * (a labelled text field styled as the heading). `title` still names the
+     * page for the shell; keep it in sync with the field's value.
+     */
+    titleField?: Snippet;
+    /** Slot for action buttons (right-aligned beside the title) */
     actions?: Snippet;
-    /** Slot for additional content below title */
+    /** Small line under the title (status, dates, counts) */
+    meta?: Snippet;
+    /** Slot for additional content below the title row (e.g. page tabs) */
     children?: Snippet;
 }
 declare const PageHeader: import("svelte").Component<Props, {}, "">;

package/dist/components/layout/PageHeader.svelte.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PageHeader.svelte.d.ts","sourceRoot":"","sources":["../../../src/components/layout/PageHeader.svelte.ts"],"names":[],"mappings":"AAGA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AAKtC,MAAM,WAAW,KAAK;IACpB,iBAAiB;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,oCAAoC;IACpC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,0BAA0B;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,sBAAsB;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,8BAA8B;IAC9B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,8CAA8C;IAC9C,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAkDD,QAAA,MAAM,UAAU,2CAAwC,CAAC;AACzD,KAAK,UAAU,GAAG,UAAU,CAAC,OAAO,UAAU,CAAC,CAAC;AAChD,eAAe,UAAU,CAAC"}
+{"version":3,"file":"PageHeader.svelte.d.ts","sourceRoot":"","sources":["../../../src/components/layout/PageHeader.svelte.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AAGtC,OAAO,EAEL,KAAK,eAAe,EACrB,MAAM,0BAA0B,CAAC;AAGlC,MAAM,WAAW,KAAK;IACpB,iBAAiB;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,oCAAoC;IACpC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,MAAM,CAAC,EAAE,SAAS,eAAe,EAAE,CAAC;IACpC,uDAAuD;IACvD,OAAO,CAAC,EAAE,SAAS,eAAe,EAAE,CAAC;IACrC,6EAA6E;IAC7E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,6CAA6C;IAC7C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,sBAAsB;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,+DAA+D;IAC/D,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,yDAAyD;IACzD,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,uEAAuE;IACvE,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAoFD,QAAA,MAAM,UAAU,2CAAwC,CAAC;AACzD,KAAK,UAAU,GAAG,UAAU,CAAC,OAAO,UAAU,CAAC,CAAC;AAChD,eAAe,UAAU,CAAC"}

package/dist/components/layout/__tests__/PageHeader.test.js

@@ -5,7 +5,7 @@
  * title, optional subtitle, optional back link, and actions/children snippets.
  */
 import { render, screen } from '@testing-library/svelte';
-import { createRawSnippet } from 'svelte';
+import { createRawSnippet, flushSync } from 'svelte';
 import { describe, expect, it } from 'vitest';
 import { expectNoA11yViolations } from '../../../test-support/a11y';
 import PageHeader from '../PageHeader.svelte';
@@ -66,6 +66,92 @@ describe('PageHeader', () => {
         render(PageHeader, { props: { title: 'Detail' } });
         expect(screen.queryByRole('link')).not.toBeInTheDocument();
     });
+    it('renders ancestors-only crumbs above the title', () => {
+        render(PageHeader, {
+            props: {
+                title: 'Fair opens Friday',
+                crumbs: [
+                    { label: 'Alpha Times', href: '/sites/alpha' },
+                    { label: 'Content', href: '/sites/alpha/articles' },
+                ],
+            },
+        });
+        const nav = screen.getByRole('navigation', { name: 'Breadcrumb' });
+        expect(nav).toHaveAttribute('data-shell-breadcrumbs');
+        const links = nav.querySelectorAll('a');
+        expect([...links].map((a) => a.textContent)).toEqual([
+            'Alpha Times',
+            'Content',
+        ]);
+        // The current page is the heading, not a crumb.
+        expect(nav).not.toHaveTextContent('Fair opens Friday');
+        expect(screen.getByRole('heading', { level: 1, name: 'Fair opens Friday' })).toHaveAttribute('data-shell-page-title');
+    });
+    it('renders no crumb row without ancestors', () => {
+        render(PageHeader, { props: { title: 'Content', crumbs: [] } });
+        expect(screen.queryByRole('navigation')).not.toBeInTheDocument();
+    });
+    it('renders the meta snippet under the title', () => {
+        render(PageHeader, {
+            props: { title: 'Detail', meta: snippet('<span>Draft</span>') },
+        });
+        expect(screen.getByText('Draft')).toBeInTheDocument();
+    });
+    it('takes its trail from the shell and reports its title', () => {
+        const reports = [];
+        const context = new Map([
+            [
+                Symbol.for('smrt-ui.page-header'),
+                {
+                    crumbs: (parents) => [
+                        { label: 'Alpha Times', href: '/sites/alpha' },
+                        ...parents,
+                    ],
+                    report: (page) => {
+                        reports.push(page);
+                        return undefined;
+                    },
+                },
+            ],
+        ]);
+        render(PageHeader, {
+            props: {
+                title: 'Create video',
+                parents: [{ label: 'Videos', href: '/sites/alpha/articles/a1/videos' }],
+            },
+            context,
+        });
+        const nav = screen.getByRole('navigation', { name: 'Breadcrumb' });
+        expect([...nav.querySelectorAll('a')].map((a) => a.textContent)).toEqual([
+            'Alpha Times',
+            'Videos',
+        ]);
+        flushSync();
+        expect(reports).toEqual([
+            {
+                title: 'Create video',
+                parents: [{ label: 'Videos', href: '/sites/alpha/articles/a1/videos' }],
+            },
+        ]);
+    });
+    it('renders an editable title inside the h1 and keeps it visible on phones', async () => {
+        const { container } = render(PageHeader, {
+            props: {
+                title: 'Council passes budget',
+                titleField: snippet('<input name="title" aria-label="Title" value="Council passes budget" />'),
+            },
+        });
+        const heading = screen.getByRole('heading', { level: 1 });
+        const field = screen.getByRole('textbox', { name: 'Title' });
+        expect(heading).toContainElement(field);
+        // The heading is named by the field's value; the field keeps its label.
+        expect(heading).toHaveAccessibleName('Council passes budget');
+        // No data-shell-page-title: the shell must not hide the input on phones.
+        expect(heading).not.toHaveAttribute('data-shell-page-title');
+        expect(heading).toHaveAttribute('data-page-title-field');
+        expect(container.querySelectorAll('h1')).toHaveLength(1);
+        await expectNoA11yViolations(container);
+    });
     it('is axe-clean with subtitle, back link, and actions', async () => {
         const { container } = render(PageHeader, {
             props: {