@thomasfosterau/components 0.1.0 → 0.2.0

package/dist/formatting/Highlight.svelte.d.ts

@@ -2,6 +2,10 @@ interface Segment {
     text: string;
     match: boolean;
 }
+/**
+ * Split `text` into segments, each flagged `match` when it is a case-insensitive hit for one of `query`'s whitespace-separated tokens.
+ * A blank `query` or `text` returns the whole text as one unmatched segment.
+ */
 export declare function tokenise(text: string, query: string): Segment[];
 interface Props {
     /** The full text to render. */

package/dist/formatting/duration.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Lengths of time: the value type, its ISO 8601 form for `<time datetime>`,
+ * and a locale-aware formatter that `Duration` and `Countdown` share and an
+ * app can call in plain TypeScript.
+ *
+ * `formatDuration` uses `Intl.DurationFormat` where the runtime has it
+ * (Baseline 2025) and otherwise composes per-unit `Intl.NumberFormat` unit
+ * strings with an `Intl.ListFormat` of `type: 'unit'`, so the fallback is
+ * still localised, just less idiomatic.
+ *
+ * @module
+ */
+/** A length of time; any subset of fields. Mirrors `Intl.DurationFormat`'s input. */
+export interface DurationValue {
+    readonly years?: number | undefined;
+    readonly months?: number | undefined;
+    readonly weeks?: number | undefined;
+    readonly days?: number | undefined;
+    readonly hours?: number | undefined;
+    readonly minutes?: number | undefined;
+    readonly seconds?: number | undefined;
+    readonly milliseconds?: number | undefined;
+}
+/** How a duration is spelled: `'2 hours, 30 minutes'`, `'2 hr, 30 min'`, `'2h 30m'` or `'2:30:00'`. */
+export type DurationStyle = 'long' | 'short' | 'narrow' | 'digital';
+/**
+ * Split milliseconds into days, hours, minutes, seconds and milliseconds,
+ * leaving out the zero fields (`9_309_000` → `{ hours: 2, minutes: 35,
+ * seconds: 9 }`). Days are the largest unit: months and years have no fixed
+ * length. Negative input is treated as zero.
+ */
+export declare function durationFromMilliseconds(ms: number): DurationValue;
+/**
+ * The ISO 8601 duration string for `<time datetime>`: `{ hours: 2,
+ * minutes: 30 }` → `'PT2H30M'`. Milliseconds join the seconds as a
+ * fraction; an empty duration is `'PT0S'`.
+ */
+export declare function toIsoDuration(value: DurationValue): string;
+/**
+ * Format a duration for `locales` in `style`, through `Intl.DurationFormat`
+ * where available and a localised `NumberFormat` + `ListFormat` composition
+ * otherwise.
+ */
+export declare function formatDuration(value: DurationValue, locales?: string | readonly string[], style?: DurationStyle): string;

package/dist/formatting/duration.js

@@ -0,0 +1,125 @@
+/**
+ * Lengths of time: the value type, its ISO 8601 form for `<time datetime>`,
+ * and a locale-aware formatter that `Duration` and `Countdown` share and an
+ * app can call in plain TypeScript.
+ *
+ * `formatDuration` uses `Intl.DurationFormat` where the runtime has it
+ * (Baseline 2025) and otherwise composes per-unit `Intl.NumberFormat` unit
+ * strings with an `Intl.ListFormat` of `type: 'unit'`, so the fallback is
+ * still localised, just less idiomatic.
+ *
+ * @module
+ */
+/** The fields, largest first, with the `Intl` unit each formats as. */
+const FIELDS = [
+    { field: 'years', unit: 'year' },
+    { field: 'months', unit: 'month' },
+    { field: 'weeks', unit: 'week' },
+    { field: 'days', unit: 'day' },
+    { field: 'hours', unit: 'hour' },
+    { field: 'minutes', unit: 'minute' },
+    { field: 'seconds', unit: 'second' },
+    { field: 'milliseconds', unit: 'millisecond' },
+];
+const SECOND = 1000;
+const MINUTE = 60 * SECOND;
+const HOUR = 60 * MINUTE;
+const DAY = 24 * HOUR;
+/**
+ * Split milliseconds into days, hours, minutes, seconds and milliseconds,
+ * leaving out the zero fields (`9_309_000` → `{ hours: 2, minutes: 35,
+ * seconds: 9 }`). Days are the largest unit: months and years have no fixed
+ * length. Negative input is treated as zero.
+ */
+export function durationFromMilliseconds(ms) {
+    let rest = Math.max(0, Math.round(ms));
+    const parts = {};
+    for (const [field, size] of [
+        ['days', DAY],
+        ['hours', HOUR],
+        ['minutes', MINUTE],
+        ['seconds', SECOND],
+        ['milliseconds', 1],
+    ]) {
+        const count = Math.floor(rest / size);
+        rest -= count * size;
+        if (count > 0)
+            parts[field] = count;
+    }
+    return parts;
+}
+/**
+ * The ISO 8601 duration string for `<time datetime>`: `{ hours: 2,
+ * minutes: 30 }` → `'PT2H30M'`. Milliseconds join the seconds as a
+ * fraction; an empty duration is `'PT0S'`.
+ */
+export function toIsoDuration(value) {
+    const amount = (field) => value[field] ?? 0;
+    const date = [
+        amount('years') > 0 ? `${amount('years')}Y` : '',
+        amount('months') > 0 ? `${amount('months')}M` : '',
+        amount('weeks') > 0 ? `${amount('weeks')}W` : '',
+        amount('days') > 0 ? `${amount('days')}D` : '',
+    ].join('');
+    const seconds = amount('seconds') + amount('milliseconds') / 1000;
+    const time = [
+        amount('hours') > 0 ? `${amount('hours')}H` : '',
+        amount('minutes') > 0 ? `${amount('minutes')}M` : '',
+        seconds > 0 ? `${Number(seconds.toFixed(3))}S` : '',
+    ].join('');
+    if (date === '' && time === '')
+        return 'PT0S';
+    return `P${date}${time === '' ? '' : `T${time}`}`;
+}
+/** `Intl.DurationFormat` when the runtime has it. */
+function nativeDurationFormat() {
+    const intl = Intl;
+    return intl.DurationFormat;
+}
+/** `value` with the `undefined` and zero fields dropped, as `Intl.DurationFormat` wants. */
+function presentFields(value) {
+    return Object.fromEntries(FIELDS.filter(({ field }) => (value[field] ?? 0) !== 0).map(({ field }) => [
+        field,
+        value[field],
+    ]));
+}
+/** `H:MM:SS` from the hours, minutes and seconds, the larger units folded into hours. */
+function digital(value) {
+    const hours = (value.days ?? 0) * 24 + (value.hours ?? 0);
+    const pad = (n) => String(n).padStart(2, '0');
+    return `${hours}:${pad(value.minutes ?? 0)}:${pad(value.seconds ?? 0)}`;
+}
+/**
+ * Format a duration for `locales` in `style`, through `Intl.DurationFormat`
+ * where available and a localised `NumberFormat` + `ListFormat` composition
+ * otherwise.
+ */
+export function formatDuration(value, locales, style = 'short') {
+    const present = presentFields(value);
+    const Native = nativeDurationFormat();
+    if (Native !== undefined) {
+        return new Native(locales, { style }).format(present);
+    }
+    if (style === 'digital')
+        return digital(value);
+    const unitDisplay = style;
+    // A mutable copy: TS6's `Intl.ListFormat` (svelte-check) takes no readonly array.
+    const tags = typeof locales === 'object' ? [...locales] : locales;
+    const pieces = FIELDS.filter(({ field }) => present[field] !== undefined).map(({ field, unit }) => new Intl.NumberFormat(tags, {
+        style: 'unit',
+        unit,
+        unitDisplay,
+    }).format(present[field] ?? 0));
+    return new Intl.ListFormat(tags, {
+        type: 'unit',
+        style: style === 'long' ? 'long' : style === 'short' ? 'short' : 'narrow',
+    }).format(pieces.length === 0
+        ? [
+            new Intl.NumberFormat(tags, {
+                style: 'unit',
+                unit: 'second',
+                unitDisplay,
+            }).format(0),
+        ]
+        : pieces);
+}

package/dist/formatting/index.d.ts

@@ -4,7 +4,10 @@
  *
  * @module
  */
+export { default as Countdown } from './Countdown.svelte';
 export { default as DateTime } from './DateTime.svelte';
+export { default as Duration } from './Duration.svelte';
+export * from './duration.ts';
 export { default as NumberFormat } from './Number.svelte';
 export { default as FormatList } from './FormatList.svelte';
 export { default as RelativeTime } from './RelativeTime.svelte';

package/dist/formatting/index.js

@@ -4,7 +4,10 @@
  *
  * @module
  */
+export { default as Countdown } from './Countdown.svelte';
 export { default as DateTime } from './DateTime.svelte';
+export { default as Duration } from './Duration.svelte';
+export * from "./duration.js";
 // `NumberFormat`, not `Number`: a named export called `Number` would shadow
 // the global constructor for anyone importing it by that name.
 export { default as NumberFormat } from './Number.svelte';

package/dist/forms/EntityForm.svelte

@@ -34,6 +34,10 @@ Renders an `@thomasfosterau/effect-forms-svelte` `defineEntityForm` definition t
   enhancement); a SvelteKit app passes its `$app/forms`-backed `enhanceForm`,
   which this package cannot import.
 
+  **Form-level messages.** The store's root errors and the caller's
+  `messages` (a failure the store never saw, such as a server action's
+  `fail(500, { message })`) share one `FormErrors` block, store errors first.
+
   Every string that is not the definition's own (labels, submit labels and
   option labels are its message thunks) is a prop with an English default.
 -->
@@ -45,7 +49,7 @@ import TextInput from "../fields/TextInput.svelte";
 import Textarea from "../fields/Textarea.svelte";
 import FormActions from "./FormActions.svelte";
 import FormErrors from "./FormErrors.svelte";
-let { definition, mode, cancelHref, action, initial = {}, initialRows = {}, fieldProps = {}, enhance = (form) => form.props, cancelLabel = "Cancel", pendingLabel = "Saving…", selectPlaceholder = "Choose…", requiredLabel, class: className, ...rest } = $props();
+let { definition, mode, cancelHref, action, initial = {}, initialRows = {}, fieldProps = {}, enhance = (form) => form.props, cancelLabel = "Cancel", pendingLabel = "Saving…", selectPlaceholder = "Choose…", requiredLabel, messages, class: className, ...rest } = $props();
 // Configure-once, at mount (see the header): these reads are deliberately
 // not reactive.
 // svelte-ignore state_referenced_locally
@@ -56,20 +60,21 @@ const configured = {
 	initialRows
 };
 const baseDefaults = configured.mode === "create" ? configured.definition.createDefaults : configured.definition.updateDefaults;
+const mintedId = configured.mode === "create" && configured.definition.clientId ? { id: crypto.randomUUID() } : undefined;
 const defaults = {
 	...baseDefaults,
-	...configured.initial
+	...configured.initial,
+	...mintedId
 };
-if (configured.mode === "create" && configured.definition.clientId) {
-	defaults["id"] = crypto.randomUUID();
-}
 const form = createForm({
 	schema: configured.mode === "create" ? configured.definition.createInput : configured.definition.updateInput,
 	defaults
 });
 const entries = configured.definition.entriesFor(configured.mode);
-// `defineEntityForm` validated every entry key against the derived
-// all-string input schema, which the path-typed accessor cannot see.
+// SAFETY: `defineEntityForm` validated every entry key against the derived
+// all-string input schema. The definition types that schema `Schema.Top`,
+// whose path-typed accessor admits no key (`never`), so the key is asserted
+// into it and the handle typed by this function's own return type.
 const handle = (key) => form.field(key);
 const getField = (key) => handle(key).value ?? "";
 const setField = (key, next) => {
@@ -97,10 +102,47 @@ const inputMode = (entry) => entry.options.inputmode ?? (configured.definition.f
 const showHiddenId = configured.mode === "update" || configured.definition.clientId;
 const submitLabel = $derived(mode === "create" ? definition.submit.create() : definition.submit.update());
 const gated = $derived(entries.some((entry) => entry._tag === "widget" && entry.options.gate === true && getField(entry.key) === ""));
-const rootErrors = $derived(form.errors._errors ?? []);
+// The empty path is the form's own (non-field) messages.
+// The caller's `messages` (a server fault with no form state) follow them.
+const rootErrors = $derived([...form.errorsAt([]), ...messages ?? []]);
 const fieldId = (key) => `entity-form-${key}`;
+// The `FormField` wrapper is the same for a select and a scalar entry.
+const fieldAttrs = (entry) => ({
+	id: fieldId(entry.key),
+	label: entry.options.label(),
+	required: entry.options.required === true,
+	errors: handle(entry.key).visibleErrors,
+	requiredLabel
+});
 </script>
 
+<!-- A scalar entry's control: a textarea, a date input or a text input. -->
+{#snippet scalarInput(entry: ScalarEntry, control: FieldControl)}
+  {#if entry.multiline}
+    <Textarea
+      {...control}
+      name={entry.key}
+      placeholder={entry.options.placeholder?.()}
+      bind:value={() => getField(entry.key), (next: string) => setField(entry.key, next)}
+    />
+  {:else if entry.options.type === 'date'}
+    <DateInput
+      {...control}
+      name={entry.key}
+      bind:value={() => getField(entry.key), (next: string) => setField(entry.key, next)}
+    />
+  {:else}
+    <TextInput
+      {...control}
+      name={entry.key}
+      type={entry.options.type === 'url' ? 'url' : 'text'}
+      inputmode={inputMode(entry)}
+      placeholder={entry.options.placeholder?.()}
+      bind:value={() => getField(entry.key), (next: string) => setField(entry.key, next)}
+    />
+  {/if}
+{/snippet}
+
 <form {...rest} {...enhance(form)} {action} class={['space-y-4', className]}>
   {#if showHiddenId}
     <input type="hidden" name="id" value={getField('id')} />
@@ -112,13 +154,7 @@ const fieldId = (key) => `entity-form-${key}`;
     {#if entry._tag === 'widget'}
       <entry.component {...entry.props()} {...fieldProps[entry.key] ?? {}} {...bridge(entry)} />
     {:else if entry._tag === 'select'}
-      <FormField
-        id={fieldId(entry.key)}
-        label={entry.options.label()}
-        required={entry.options.required === true}
-        errors={handle(entry.key).visibleErrors}
-        {requiredLabel}
-      >
+      <FormField {...fieldAttrs(entry)}>
         {#snippet children(control)}
           <Select
             {...control}
@@ -130,37 +166,9 @@ const fieldId = (key) => `entity-form-${key}`;
         {/snippet}
       </FormField>
     {:else}
-      <FormField
-        id={fieldId(entry.key)}
-        label={entry.options.label()}
-        required={entry.options.required === true}
-        errors={handle(entry.key).visibleErrors}
-        {requiredLabel}
-      >
+      <FormField {...fieldAttrs(entry)}>
         {#snippet children(control)}
-          {#if entry.multiline}
-            <Textarea
-              {...control}
-              name={entry.key}
-              placeholder={entry.options.placeholder?.()}
-              bind:value={() => getField(entry.key), (next: string) => setField(entry.key, next)}
-            />
-          {:else if entry.options.type === 'date'}
-            <DateInput
-              {...control}
-              name={entry.key}
-              bind:value={() => getField(entry.key), (next: string) => setField(entry.key, next)}
-            />
-          {:else}
-            <TextInput
-              {...control}
-              name={entry.key}
-              type={entry.options.type === 'url' ? 'url' : 'text'}
-              inputmode={inputMode(entry)}
-              placeholder={entry.options.placeholder?.()}
-              bind:value={() => getField(entry.key), (next: string) => setField(entry.key, next)}
-            />
-          {/if}
+          {@render scalarInput(entry, control)}
         {/snippet}
       </FormField>
     {/if}

package/dist/forms/EntityForm.svelte.d.ts

@@ -1,6 +1,8 @@
-import { createForm, type EntityFormDefinition } from '@thomasfosterau/effect-forms-svelte';
+import { createForm, type EntityFormDefinition, type WidgetEntry } from '@thomasfosterau/effect-forms-svelte';
 import type { HTMLFormAttributes } from 'svelte/elements';
 type Store = ReturnType<typeof createForm>;
+/** The props a widget entry receives: its definition's `props()` shape, owned by the form library. */
+type WidgetProps = ReturnType<WidgetEntry['props']>;
 interface Props extends Omit<HTMLFormAttributes, 'action' | 'method' | 'children'> {
     /** The form definition from `defineEntityForm`. */
     definition: EntityFormDefinition;
@@ -24,12 +26,12 @@ interface Props extends Omit<HTMLFormAttributes, 'action' | 'method' | 'children
      * Render-time extra props per widget key (a picker's load-resolved `options`).
      * @defaultValue `{}`
      */
-    fieldProps?: Readonly<Record<string, Readonly<Record<string, unknown>>>> | undefined;
+    fieldProps?: Readonly<Record<string, Readonly<WidgetProps>>> | undefined;
     /**
      * The spreadable `<form>` attributes for this store.
      * @defaultValue the store's own `form.props`
      */
-    enhance?: ((form: Store) => Record<string | symbol, unknown>) | undefined;
+    enhance?: ((form: Store) => Store['props']) | undefined;
     /**
      * Text of the cancel link.
      * @defaultValue `'Cancel'`
@@ -50,6 +52,13 @@ interface Props extends Omit<HTMLFormAttributes, 'action' | 'method' | 'children
      * @defaultValue `'(required)'` (from `FormField`)
      */
     requiredLabel?: string | undefined;
+    /**
+     * Form-level messages from outside the store — a server action's failure
+     * message that carries no form state (`page.form?.message`, wrapped in an
+     * array). Rendered in the same `FormErrors` block as the store's own root
+     * errors, after them, one `role="alert"` each. The text is shown as given.
+     */
+    messages?: readonly string[] | undefined;
 }
 /** Renders an `@thomasfosterau/effect-forms-svelte` `defineEntityForm` definition through this library’s field primitives. */
 declare const EntityForm: import("svelte").Component<Props, {}, "">;

package/dist/hotkeys/index.d.ts

@@ -12,6 +12,11 @@
  * registered, and the two components take their own chrome copy
  * (`title`, `closeLabel`, `commandLabel`, …) with English defaults.
  *
+ * The family is re-exported from the root barrel and is also its own entry,
+ * `@thomasfosterau/components/hotkeys`, so a consumer can
+ * `import('@thomasfosterau/components/hotkeys')` to load `HotkeyHelpDialog`
+ * lazily, on the first `?`, instead of in its entry chunk.
+ *
  * @module
  */
 export { HotkeyRegistryMissing, createHotkeyRegistry, getHotkeyRegistry, registerHotkeys, tryGetHotkeyRegistry, } from './context.svelte.ts';

package/dist/hotkeys/index.js

@@ -12,6 +12,11 @@
  * registered, and the two components take their own chrome copy
  * (`title`, `closeLabel`, `commandLabel`, …) with English defaults.
  *
+ * The family is re-exported from the root barrel and is also its own entry,
+ * `@thomasfosterau/components/hotkeys`, so a consumer can
+ * `import('@thomasfosterau/components/hotkeys')` to load `HotkeyHelpDialog`
+ * lazily, on the first `?`, instead of in its entry chunk.
+ *
  * @module
  */
 export { HotkeyRegistryMissing, createHotkeyRegistry, getHotkeyRegistry, registerHotkeys, tryGetHotkeyRegistry, } from "./context.svelte.js";

package/dist/hotkeys/match.js

@@ -101,22 +101,24 @@ export function matchChord(event, actions) {
  * `actions` must already be in precedence order.
  */
 export function matchSequence(buffer, actions) {
-    return actions.reduce((match, { action }) => {
+    let exact;
+    let isPrefix = false;
+    for (const { action } of actions) {
         const trigger = action.trigger;
         if (trigger === undefined)
-            return match;
+            continue;
         const sequence = asSequence(trigger);
         if (sequence === undefined)
-            return match;
+            continue;
         if (sequence.length === buffer.length) {
-            return match.exact === undefined && sequence.every((key, i) => key === buffer[i])
-                ? { ...match, exact: action }
-                : match;
+            if (exact === undefined && sequence.every((key, i) => key === buffer[i]))
+                exact = action;
         }
-        return sequence.length > buffer.length && buffer.every((key, i) => key === sequence[i])
-            ? { ...match, isPrefix: true }
-            : match;
-    }, { exact: undefined, isPrefix: false });
+        else if (sequence.length > buffer.length && buffer.every((key, i) => key === sequence[i])) {
+            isPrefix = true;
+        }
+    }
+    return { exact, isPrefix };
 }
 /** Project a trigger into its display form for help overlays and badges. */
 export function triggerDisplay(trigger) {

package/dist/hotkeys/types.d.ts

@@ -31,10 +31,10 @@ export type HotkeyChord = string;
 export type HotkeySequence = readonly string[];
 /** A hotkey trigger: a chord pressed together (`'$mod+k'`) or a sequence pressed in turn (`['g', 'p']`). */
 export type HotkeyTrigger = HotkeyChord | HotkeySequence;
-/** Palette grouping. Drives section headings and ordering. */
+/** The command-palette section a `CommandAction` is listed under. Drives section headings and ordering. */
 export type CommandActionGroup = 'actions' | 'navigation';
 /**
- * Where a registration lives. Page registrations are torn down when the
+ * Where a hotkey registration lives: `global` for the app shell, `page` for the mounted page. Page registrations are torn down when the
  * registering page unmounts and win over global registrations on trigger
  * conflicts.
  */
@@ -67,6 +67,8 @@ export interface CommandAction {
 }
 /** A registration entry: an action plus the scope it was registered under. */
 export interface RegisteredAction {
+    /** The scope it was registered under. */
     scope: HotkeyScope;
+    /** The action as registered. */
     action: CommandAction;
 }

package/dist/index.d.ts

@@ -14,7 +14,8 @@
  * are separate entry points (`@thomasfosterau/components/<family>`), as is
  * `EntityForm` (`@thomasfosterau/components/entity-form`, which needs the
  * optional peer `@thomasfosterau/effect-forms-svelte`); none is re-exported
- * here. The maps family lives one package over, in
+ * here. `hotkeys` is both: re-exported here and its own
+ * `@thomasfosterau/components/hotkeys` entry, for a lazily loaded help dialog. The maps family lives one package over, in
  * `@thomasfosterau/components-mapbox`: its behaviour needs a specific
  * third-party engine (`mapbox-gl`), and a component that needs one lives in
  * its own package so this one stays free of it.

package/dist/index.js

@@ -14,7 +14,8 @@
  * are separate entry points (`@thomasfosterau/components/<family>`), as is
  * `EntityForm` (`@thomasfosterau/components/entity-form`, which needs the
  * optional peer `@thomasfosterau/effect-forms-svelte`); none is re-exported
- * here. The maps family lives one package over, in
+ * here. `hotkeys` is both: re-exported here and its own
+ * `@thomasfosterau/components/hotkeys` entry, for a lazily loaded help dialog. The maps family lives one package over, in
  * `@thomasfosterau/components-mapbox`: its behaviour needs a specific
  * third-party engine (`mapbox-gl`), and a component that needs one lives in
  * its own package so this one stays free of it.

package/dist/infobox/Infobox.svelte

@@ -27,7 +27,7 @@ import InfoboxImage from "./InfoboxImage.svelte";
 import InfoboxRow from "./InfoboxRow.svelte";
 import InfoboxSection from "./InfoboxSection.svelte";
 import { infoboxRowIsPresent } from "./types.js";
-let { title, subtitle, label = "Key facts", image, rows, float = false, children, class: className, ...rest } = $props();
+let { title, subtitle, headingLevel, label = "Key facts", image, rows, float = false, children, class: className, ...rest } = $props();
 const presentRows = $derived((rows ?? []).filter(infoboxRowIsPresent));
 const imageRows = $derived(presentRows.filter((row) => row.kind === "image"));
 const bodyRows = $derived(presentRows.filter((row) => row.kind !== "image"));
@@ -44,7 +44,7 @@ const bodyRows = $derived(presentRows.filter((row) => row.kind !== "image"));
   ]}
 >
   {#if title !== undefined}
-    <InfoboxHeader {title} {subtitle} />
+    <InfoboxHeader {title} {subtitle} {headingLevel} />
   {/if}
   {#if image !== undefined}
     <InfoboxImage {...image} />

package/dist/infobox/Infobox.svelte.d.ts

@@ -1,11 +1,18 @@
 import type { Snippet } from 'svelte';
 import type { HTMLAttributes } from 'svelte/elements';
+import type { HeadingLevel } from '../ui/tones.ts';
 import { type InfoboxImageSpec, type InfoboxRowSpec as Row } from './types.ts';
 interface Props extends Omit<HTMLAttributes<HTMLElement>, 'children' | 'title'> {
     /** Heading of the rail; also its accessible name. */
     title?: string | undefined;
     /** A line under the title. */
     subtitle?: string | undefined;
+    /**
+     * The title's heading level (`InfoboxHeader`'s). Keep the default beside
+     * prose; raise it when the box is a section of the page in its own right.
+     * @defaultValue `3`
+     */
+    headingLevel?: Exclude<HeadingLevel, 1> | undefined;
     /**
      * Accessible name for the region when there is no `title`.
      * @defaultValue `'Key facts'`

package/dist/infobox/InfoboxHeader.svelte

@@ -4,13 +4,19 @@ The title block at the top of an `Infobox`.
 <!--
   InfoboxHeader — the title block at the top of an `Infobox`.
 
-  An `h3` rather than an `h2`: the box sits beside an article's prose, and
-  its title names the summary, not a section of the document. Promoting it
-  to the level a real section heading would use puts a phantom entry in the
-  page's outline between two real ones — the box is deliberately outside
-  the outline.
+  An `h3` by default rather than an `h2`: the box sits beside an article's
+  prose, and its title names the summary, not a section of the document.
+  Promoting it to the level a real section heading would use puts a phantom
+  entry in the page's outline between two real ones — the box is
+  deliberately outside the outline.
+
+  `headingLevel` raises (or lowers) it for a page that uses the box as a
+  section in its own right, where `h3` would skip a level (`h1` → `h3`) or
+  read as a sub-heading of the section before it. Only the tag changes; the
+  classes are the same at every level. `1` is excluded: the box never titles
+  the page.
 -->
-<script lang="ts">let { title, subtitle, class: className, ...rest } = $props();
+<script lang="ts">let { title, subtitle, headingLevel = 3, class: className, ...rest } = $props();
 export {};
 </script>
 
@@ -18,7 +24,9 @@ export {};
   {...rest}
   class={["border-base-300 bg-base-300 border-b px-4 py-3", className]}
 >
-  <h3 class="text-center text-lg font-bold select-none">{title}</h3>
+  <svelte:element this={`h${headingLevel}`} class="text-center text-lg font-bold select-none">
+    {title}
+  </svelte:element>
   {#if subtitle !== undefined && subtitle !== ""}
     <p class="text-base-content/60 mt-1 text-center text-sm select-none">
       {subtitle}

package/dist/infobox/InfoboxHeader.svelte.d.ts

@@ -1,9 +1,16 @@
 import type { HTMLAttributes } from "svelte/elements";
+import type { HeadingLevel } from "../ui/tones.ts";
 interface Props extends HTMLAttributes<HTMLDivElement> {
     /** The infobox heading text. */
     title: string;
     /** A line under the heading. */
     subtitle?: string | undefined;
+    /**
+     * The heading's level. Keep the default when the box sits beside prose;
+     * raise it to the page's section level when the box is a section itself.
+     * @defaultValue `3`
+     */
+    headingLevel?: Exclude<HeadingLevel, 1> | undefined;
 }
 /** The title block at the top of an `Infobox`. */
 declare const InfoboxHeader: import("svelte").Component<Props, {}, "">;

package/dist/infobox/types.d.ts

@@ -23,14 +23,14 @@ export interface InfoboxImageSpec {
      */
     readonly eager?: boolean | undefined;
 }
-/** A single identifying fact (e.g. publication year, ISBN, page count). */
+/** An `Infobox` row holding a single identifying fact (e.g. publication year, ISBN, page count). */
 export interface InfoboxFactRow {
     readonly kind: 'fact';
     readonly label: string;
     /** `undefined` or an empty string skips the row. */
     readonly value: string | number | undefined;
 }
-/** A single named link, rendered as one row with its own visible text. */
+/** An `Infobox` row holding a single named link, with its own visible text. */
 export interface InfoboxLinkRow {
     readonly kind: 'link';
     readonly label: string;
@@ -45,7 +45,7 @@ export interface InfoboxLinkEntry {
     readonly label: string;
     readonly href: string;
 }
-/** A named outbound relationship rendered as one or more links. */
+/** An `Infobox` row for a named outbound relationship, rendered as one or more links. */
 export interface InfoboxLinksRow {
     readonly kind: 'links';
     readonly label: string;
@@ -53,7 +53,7 @@ export interface InfoboxLinksRow {
     readonly links: readonly InfoboxLinkEntry[] | undefined;
 }
 /**
- * A hero/identifying image row. Renders above the `<dl>` as an
+ * An `Infobox` row for the hero/identifying image. Renders above the `<dl>` as an
  * `InfoboxImage`, not as a `dt`/`dd` pair — the same shape `Infobox`'s own
  * `image` prop takes, offered as a row for the callers who build the whole
  * infobox from one `rows` array.
@@ -61,7 +61,7 @@ export interface InfoboxLinksRow {
 export interface InfoboxImageRow extends InfoboxImageSpec {
     readonly kind: 'image';
 }
-/** A row whose value is arbitrary markup (a badge, a formatted quantity). */
+/** An `Infobox` row whose value is arbitrary markup (a badge, a formatted quantity). */
 export interface InfoboxCustomRow {
     readonly kind: 'custom';
     readonly label: string;