@thomasfosterau/components 0.0.0-stage → 0.1.0

package/dist/hotkeys/match.js

@@ -0,0 +1,133 @@
+/**
+ * Pure key-matching helpers for the hotkey registry. No Svelte, no DOM
+ * mutation — just functions over `KeyboardEvent`s, trigger grammars and the
+ * sequence buffer, so the matching rules stay testable and `HotkeyProvider`
+ * stays thin.
+ *
+ * Trigger model:
+ *
+ * - **Modifier chords** (`'$mod+k'`) — held together. `$mod` is ⌘ on macOS
+ *   and Ctrl elsewhere. Matched on their own; never buffered.
+ * - **Plain keys / sequences** (`'e'`, `'/'`, `['g', 'p']`) — pressed in
+ *   order with no modifier held. A plain single key is just a sequence of
+ *   length one, so matching is uniform.
+ *
+ * @module
+ */
+/** Sequence buffer entries expire after this many milliseconds. */
+export const SEQUENCE_TIMEOUT_MS = 1000;
+/** Whether the runtime platform treats `$mod` as ⌘ (macOS / iOS). */
+export function isApplePlatform() {
+    // `globalThis.navigator` rather than the bare identifier: on a runtime
+    // without one, a direct reference would throw before the guard could run.
+    if (typeof globalThis.navigator === 'undefined')
+        return false;
+    return /mac|iphone|ipad|ipod/i.test(globalThis.navigator.platform);
+}
+/**
+ * Whether a keyboard event's target is an editable surface — a form field or
+ * a contenteditable region (which covers a rich-text editor's root). Hotkeys
+ * without `allowInEditable` stay inert there so typing never fires actions.
+ */
+export function isEditableTarget(target) {
+    if (!(target instanceof HTMLElement))
+        return false;
+    return target.matches('input, textarea, select') || target.isContentEditable;
+}
+/** Whether a trigger is in the modifier-chord form (`'$mod+…'`). */
+function isModifierChord(trigger) {
+    return typeof trigger === 'string' && trigger.includes('+');
+}
+/** Normalise a plain-key trigger to its sequence form. `undefined` for a chord. */
+function asSequence(trigger) {
+    if (typeof trigger === 'string') {
+        return isModifierChord(trigger) ? undefined : [trigger];
+    }
+    return trigger;
+}
+/** Whether the event matches a `'$mod+key'` chord. */
+// Modifier matching is a flat run of guard comparisons (mod / alt / shift /
+// cross-platform exclusion); each early return is one rule of the chord
+// grammar, and extracting them would obscure the contract.
+function eventMatchesChord(event, chord) {
+    const parts = chord.split('+');
+    const key = parts.at(-1) ?? '';
+    // A plain array, not a `Set`: a chord carries at most three modifiers, so
+    // three `includes` scans beat building a hashed collection on every
+    // keystroke.
+    const modifiers = parts.slice(0, -1);
+    const wantsMod = modifiers.includes('$mod');
+    const wantsAlt = modifiers.includes('alt');
+    const wantsShift = modifiers.includes('shift');
+    const apple = isApplePlatform();
+    const modPressed = apple ? event.metaKey : event.ctrlKey;
+    // The non-$mod modifier must not also be held, so e.g. Ctrl+K on macOS
+    // doesn't trigger a ⌘K hotkey.
+    const otherModPressed = apple ? event.ctrlKey : event.metaKey;
+    if (wantsMod !== modPressed || otherModPressed)
+        return false;
+    if (wantsAlt !== event.altKey)
+        return false;
+    if (wantsShift && !event.shiftKey)
+        return false;
+    return event.key.toLowerCase() === key.toLowerCase();
+}
+/** Whether an event carries a chord modifier (⌘ / Ctrl / Alt). */
+export function hasChordModifier(event) {
+    return event.metaKey || event.ctrlKey || event.altKey;
+}
+/**
+ * Whether an event's key can participate in a sequence: a single printable
+ * character pressed without chord modifiers.
+ */
+export function isSequenceKey(event) {
+    return !hasChordModifier(event) && event.key.length === 1;
+}
+/**
+ * Find the action whose modifier chord matches the event. `actions` must
+ * already be in precedence order (page before global, later registrations
+ * first).
+ */
+export function matchChord(event, actions) {
+    return actions.find(({ action }) => typeof action.trigger === 'string' &&
+        action.trigger.includes('+') &&
+        eventMatchesChord(event, action.trigger))?.action;
+}
+// A single-pass scan that classifies every trigger as exact-match / prefix /
+// miss in one loop; splitting it into separate passes would be simpler per
+// function but iterate the registrations three times per keystroke.
+/**
+ * Match a candidate key buffer against the active plain-key triggers.
+ * `actions` must already be in precedence order.
+ */
+export function matchSequence(buffer, actions) {
+    return actions.reduce((match, { action }) => {
+        const trigger = action.trigger;
+        if (trigger === undefined)
+            return match;
+        const sequence = asSequence(trigger);
+        if (sequence === undefined)
+            return match;
+        if (sequence.length === buffer.length) {
+            return match.exact === undefined && sequence.every((key, i) => key === buffer[i])
+                ? { ...match, exact: action }
+                : match;
+        }
+        return sequence.length > buffer.length && buffer.every((key, i) => key === sequence[i])
+            ? { ...match, isPrefix: true }
+            : match;
+    }, { exact: undefined, isPrefix: false });
+}
+/** Project a trigger into its display form for help overlays and badges. */
+export function triggerDisplay(trigger) {
+    if (typeof trigger === 'string') {
+        if (isModifierChord(trigger)) {
+            return {
+                keys: trigger.split('+').map((part) => (part === '$mod' ? part : part.toUpperCase())),
+                sequential: false,
+            };
+        }
+        return { keys: [trigger.toUpperCase()], sequential: false };
+    }
+    return { keys: trigger.map((key) => key.toUpperCase()), sequential: true };
+}

package/dist/hotkeys/registry.svelte.d.ts

@@ -0,0 +1,55 @@
+/**
+ * The reactive hotkey / command registry.
+ *
+ * One instance lives in the app's Svelte context. The root layout registers
+ * `global` actions; pages register `page` actions that are torn down when the
+ * page unmounts. The registry is the single source of truth for three
+ * consumers:
+ *
+ * - `HotkeyProvider` — matches keyboard events against active triggers.
+ * - `CommandPalette` — lists palette-visible actions.
+ * - `HotkeyHelpDialog` — lists actions that carry triggers.
+ *
+ * Role gating happens here: actions registered with `requiresAdmin` are
+ * dropped from every read surface when the viewer is not an administrator, so
+ * non-admin users never see (or can fire) them.
+ *
+ * @module
+ */
+import type { CommandAction, HotkeyScope, RegisteredAction } from './types.ts';
+/** What `createHotkeyRegistry` needs from the app: the admin check and the dev flag. */
+export interface HotkeyRegistryOptions {
+    /** Whether the current viewer is an administrator. Read lazily so it can be reactive. */
+    isAdmin: () => boolean;
+    /**
+     * Whether this is a dev build. When true, registering a batch whose trigger
+     * shadows an existing one logs a console warning. An app wires this to its
+     * bundler's dev flag (SvelteKit's `$app/environment` `dev`); defaults to
+     * `false`.
+     */
+    dev?: boolean | undefined;
+}
+/** The reactive set of registered hotkey actions that `HotkeyProvider`, `CommandPalette` and `HotkeyHelpDialog` read; page registrations win over global ones. */
+export declare class HotkeyRegistry {
+    #private;
+    /** Whether the command palette is open. Bound by `CommandPalette`. */
+    paletteOpen: boolean;
+    /** Whether the hotkey help overlay is open. Bound by `HotkeyHelpDialog`. */
+    helpOpen: boolean;
+    constructor(options: HotkeyRegistryOptions);
+    /**
+     * Register a batch of actions under a scope. Returns an unregister
+     * function; callers are expected to invoke it on unmount (the
+     * `registerHotkeys` helper wires this to `$effect` cleanup).
+     */
+    register(scope: HotkeyScope, actions: readonly CommandAction[]): () => void;
+    /**
+     * Role-filtered active registrations in match-precedence order: page scope
+     * before global, later registrations first within a scope.
+     */
+    readonly active: readonly RegisteredAction[];
+    /** Active actions that should appear in the command palette, in registration order. */
+    readonly paletteActions: readonly RegisteredAction[];
+    /** Active actions that carry a keyboard trigger, for the help overlay. */
+    readonly hotkeys: readonly RegisteredAction[];
+}

package/dist/hotkeys/registry.svelte.js

@@ -0,0 +1,110 @@
+/**
+ * The reactive hotkey / command registry.
+ *
+ * One instance lives in the app's Svelte context. The root layout registers
+ * `global` actions; pages register `page` actions that are torn down when the
+ * page unmounts. The registry is the single source of truth for three
+ * consumers:
+ *
+ * - `HotkeyProvider` — matches keyboard events against active triggers.
+ * - `CommandPalette` — lists palette-visible actions.
+ * - `HotkeyHelpDialog` — lists actions that carry triggers.
+ *
+ * Role gating happens here: actions registered with `requiresAdmin` are
+ * dropped from every read surface when the viewer is not an administrator, so
+ * non-admin users never see (or can fire) them.
+ *
+ * @module
+ */
+/**
+ * Whether two triggers denote the same keystroke. A structural comparison
+ * rather than a JSON round-trip: a chord is a string and a sequence is an
+ * array, so the two forms never collide.
+ */
+function sameTrigger(self, that) {
+    return typeof self === 'string' || typeof that === 'string'
+        ? self === that
+        : self.length === that.length && self.every((key, index) => key === that[index]);
+}
+/** A trigger rendered for the dev warning below. */
+function formatTrigger(trigger) {
+    return typeof trigger === 'string' ? `"${trigger}"` : `["${trigger.join('", "')}"]`;
+}
+/** Dev-only console warning when a new registration shadows an existing trigger. */
+function warnOnTriggerConflicts(added, existing) {
+    for (const entry of added) {
+        const trigger = entry.action.trigger;
+        if (trigger === undefined)
+            continue;
+        const conflict = existing.find((other) => other.action.trigger !== undefined && sameTrigger(other.action.trigger, trigger));
+        if (conflict) {
+            // A dev-build diagnostic: it has to reach the browser console the
+            // developer is looking at, which is why this is the one `console` call
+            // in the package.
+            console.warn(`[hotkeys] Trigger ${formatTrigger(trigger)} of "${entry.action.id}" ` +
+                `shadows "${conflict.action.id}" (${conflict.scope}). ` +
+                `Page-scope and later registrations win.`);
+        }
+    }
+}
+/** Page scope sorts before global scope. */
+const scopeRank = (entry) => (entry.scope === 'page' ? 0 : 1);
+/**
+ * Match precedence: page scope first, then the most recent registration.
+ * A plain comparator — the composed `Order` this was ported from is the only
+ * thing that changed.
+ */
+const byMatchPrecedence = (a, b) => scopeRank(a) - scopeRank(b) || b.order - a.order;
+/** Ascending registration order (earlier registrations first). */
+const byOrder = (a, b) => a.order - b.order;
+/** The reactive set of registered hotkey actions that `HotkeyProvider`, `CommandPalette` and `HotkeyHelpDialog` read; page registrations win over global ones. */
+export class HotkeyRegistry {
+    #registrations = $state([]);
+    #nextOrder = 0;
+    #isAdmin;
+    #dev;
+    /** Whether the command palette is open. Bound by `CommandPalette`. */
+    paletteOpen = $state(false);
+    /** Whether the hotkey help overlay is open. Bound by `HotkeyHelpDialog`. */
+    helpOpen = $state(false);
+    constructor(options) {
+        this.#isAdmin = options.isAdmin;
+        this.#dev = options.dev ?? false;
+    }
+    /**
+     * Register a batch of actions under a scope. Returns an unregister
+     * function; callers are expected to invoke it on unmount (the
+     * `registerHotkeys` helper wires this to `$effect` cleanup).
+     */
+    register(scope, actions) {
+        const added = actions.map((action) => ({ scope, action, order: this.#nextOrder++ }));
+        if (this.#dev)
+            warnOnTriggerConflicts(added, this.#registrations);
+        this.#registrations = [...this.#registrations, ...added];
+        return () => {
+            // Remove by the stable monotonic `order`, NOT object identity. `$state`
+            // deep-proxies `#registrations`, so entries read back here are proxies
+            // that never `===` the raw objects captured in `added` — a `Set(added)`
+            // membership test would match nothing and remove nothing, leaking the
+            // batch. `registerHotkeys` wires this closure to `$effect` cleanup, so
+            // every reactive re-registration would otherwise accumulate duplicates.
+            const orders = new Set(added.map((entry) => entry.order));
+            this.#registrations = this.#registrations.filter((entry) => !orders.has(entry.order));
+        };
+    }
+    /**
+     * Role-filtered active registrations in match-precedence order: page scope
+     * before global, later registrations first within a scope.
+     */
+    active = $derived(this.#registrations
+        .filter((entry) => !entry.action.requiresAdmin || this.#isAdmin())
+        .toSorted(byMatchPrecedence));
+    /** Active actions that should appear in the command palette, in registration order. */
+    paletteActions = $derived(this.#registrations
+        .filter((entry) => (!entry.action.requiresAdmin || this.#isAdmin()) && entry.action.paletteVisible !== false)
+        .toSorted(byOrder));
+    /** Active actions that carry a keyboard trigger, for the help overlay. */
+    hotkeys = $derived(this.#registrations
+        .filter((entry) => (!entry.action.requiresAdmin || this.#isAdmin()) && entry.action.trigger !== undefined)
+        .toSorted(byOrder));
+}

package/dist/hotkeys/types.d.ts

@@ -0,0 +1,72 @@
+/**
+ * The registration contract shared by the hotkey registry and the command
+ * palette.
+ *
+ * A {@link CommandAction} is the unit of both systems: a labelled, runnable
+ * action that may carry a keyboard trigger (making it a hotkey) and may
+ * appear in the command palette (making it discoverable). Pages and the
+ * global shell register actions through the registry; the palette and the
+ * help overlay read the same registrations back, so there is exactly one
+ * source of truth for "what can the viewer do right now".
+ *
+ * Every optional member is declared `T | undefined`: the workspace compiles
+ * with `exactOptionalPropertyTypes`, and these objects are written as plain
+ * literals by application code that forwards its own optional values.
+ *
+ * @module
+ */
+/**
+ * A single-keystroke trigger.
+ *
+ * Grammar: zero or more `+`-separated modifiers followed by a key, e.g.
+ * `'$mod+k'`, `'/'`, `'?'`, `'e'`. `$mod` resolves to ⌘ on macOS and Ctrl
+ * elsewhere. Shift is never written explicitly — shifted characters (like
+ * `?`) already arrive shifted in `KeyboardEvent.key`.
+ */
+export type HotkeyChord = string;
+/**
+ * A multi-keystroke trigger pressed in order, e.g. `['g', 'p']`. Only plain
+ * (unmodified) printable keys participate in sequences.
+ */
+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. */
+export type CommandActionGroup = 'actions' | 'navigation';
+/**
+ * Where a registration lives. Page registrations are torn down when the
+ * registering page unmounts and win over global registrations on trigger
+ * conflicts.
+ */
+export type HotkeyScope = 'global' | 'page';
+/** One action the hotkey registry and the command palette offer: an id, a label, what it runs and, optionally, its trigger. */
+export interface CommandAction {
+    /** Stable unique id, e.g. `'nav.posts'`, `'posts.create'`. */
+    id: string;
+    /** Human-readable label. An i18n app resolves its message at registration. */
+    label: string;
+    /** What runs on activation (navigate, focus, open a dialog, …). */
+    run: () => void | Promise<void>;
+    /** Palette section. */
+    group: CommandActionGroup;
+    /** Optional keyboard trigger. Actions without one are palette-only. */
+    trigger?: HotkeyTrigger | undefined;
+    /**
+     * When true the registry drops the action entirely for non-admin viewers —
+     * it neither fires as a hotkey nor appears in the palette.
+     */
+    requiresAdmin?: boolean | undefined;
+    /** Set false to keep an action hotkey-only (hidden from the palette). */
+    paletteVisible?: boolean | undefined;
+    /**
+     * Allow the trigger to fire while focus is inside an editable element
+     * (input / textarea / contenteditable). Reserved for the palette opener;
+     * everything else stays inert while typing.
+     */
+    allowInEditable?: boolean | undefined;
+}
+/** A registration entry: an action plus the scope it was registered under. */
+export interface RegisteredAction {
+    scope: HotkeyScope;
+    action: CommandAction;
+}

package/dist/hotkeys/types.js

@@ -0,0 +1,18 @@
+/**
+ * The registration contract shared by the hotkey registry and the command
+ * palette.
+ *
+ * A {@link CommandAction} is the unit of both systems: a labelled, runnable
+ * action that may carry a keyboard trigger (making it a hotkey) and may
+ * appear in the command palette (making it discoverable). Pages and the
+ * global shell register actions through the registry; the palette and the
+ * help overlay read the same registrations back, so there is exactly one
+ * source of truth for "what can the viewer do right now".
+ *
+ * Every optional member is declared `T | undefined`: the workspace compiles
+ * with `exactOptionalPropertyTypes`, and these objects are written as plain
+ * literals by application code that forwards its own optional values.
+ *
+ * @module
+ */
+export {};

package/dist/index.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Accessible Svelte 5 UI primitives.
+ *
+ * Everything exported here is app-agnostic: it takes props and snippets,
+ * spreads the native attributes of the element it renders, reads no global
+ * state, and gets every user-facing string from a prop with an English
+ * default. Styling is daisyUI semantic classes over the tokens in
+ * `./theme.css`, which ships beside this barrel as the package's
+ * `./theme.css` export. The one injected dependency is
+ * {@link ComponentsContext}: locale, href resolution, navigation and the
+ * current-page check.
+ *
+ * The heavier families — `citations`, `canvas`, `charts`, `tips`, `seo` —
+ * 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
+ * `@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.
+ *
+ * @module @thomasfosterau/components
+ */
+export * from './context.svelte.ts';
+export * from './ui/index.ts';
+export * from './feedback/index.ts';
+export * from './layout/index.ts';
+export * from './fields/index.ts';
+export * from './forms/index.ts';
+export * from './data/index.ts';
+export * from './infobox/index.ts';
+export * from './formatting/index.ts';
+export * from './links/index.ts';
+export * from './media/index.ts';
+export * from './hotkeys/index.ts';
+export * from './search/index.ts';

package/dist/index.js

@@ -0,0 +1,36 @@
+/**
+ * Accessible Svelte 5 UI primitives.
+ *
+ * Everything exported here is app-agnostic: it takes props and snippets,
+ * spreads the native attributes of the element it renders, reads no global
+ * state, and gets every user-facing string from a prop with an English
+ * default. Styling is daisyUI semantic classes over the tokens in
+ * `./theme.css`, which ships beside this barrel as the package's
+ * `./theme.css` export. The one injected dependency is
+ * {@link ComponentsContext}: locale, href resolution, navigation and the
+ * current-page check.
+ *
+ * The heavier families — `citations`, `canvas`, `charts`, `tips`, `seo` —
+ * 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
+ * `@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.
+ *
+ * @module @thomasfosterau/components
+ */
+export * from "./context.svelte.js";
+export * from "./ui/index.js";
+export * from "./feedback/index.js";
+export * from "./layout/index.js";
+export * from "./fields/index.js";
+export * from "./forms/index.js";
+export * from "./data/index.js";
+export * from "./infobox/index.js";
+export * from "./formatting/index.js";
+export * from "./links/index.js";
+export * from "./media/index.js";
+export * from "./hotkeys/index.js";
+export * from "./search/index.js";

package/dist/infobox/Infobox.svelte

@@ -0,0 +1,79 @@
+<!-- @component
+The summary rail beside an entity page’s prose: an optional header and image above a body of labelled facts.
+-->
+<!--
+  Infobox — the summary rail beside an entity page's prose: an optional
+  header, an optional image, and a body of labelled facts.
+
+  Two ways to fill it, both live at once. The composable path — `children`
+  taking `InfoboxSection`/`InfoboxRow` (or anything else):
+  a page builds bespoke markup, one piece of markup per concern, and a fix
+  to row layout lands once because there is only one row layout. `rows` renders through the SAME `InfoboxSection`/
+  `InfoboxRow`/`InfoboxImage` primitives `children` would use — never a
+  second copy of the markup — so both paths stay in lock step. Both are
+  accepted together: `rows` first, then `children` below them.
+
+  `float`: floats the box to the right of the article's prose; instead give it its own grid column in the
+  page layout and never float it. Off by default, since a grid-column aside
+  is the more common shape here, and opt-in per page with `float`.
+
+  ARIA contract: `aria-label={title ?? label}` names the region — a real
+  `title` is more specific than the generic default, so it wins.
+  `data-testid="infobox"` is kept for e2e parity with the source apps.
+-->
+<script lang="ts">import Link from "../ui/Link.svelte";
+import InfoboxHeader from "./InfoboxHeader.svelte";
+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();
+const presentRows = $derived((rows ?? []).filter(infoboxRowIsPresent));
+const imageRows = $derived(presentRows.filter((row) => row.kind === "image"));
+const bodyRows = $derived(presentRows.filter((row) => row.kind !== "image"));
+</script>
+
+<aside
+  {...rest}
+  data-testid="infobox"
+  aria-label={title ?? label}
+  class={[
+    'card card-border bg-base-100 shadow-sm',
+    float && 'float-right mb-4 ml-4 w-full sm:w-80',
+    className,
+  ]}
+>
+  {#if title !== undefined}
+    <InfoboxHeader {title} {subtitle} />
+  {/if}
+  {#if image !== undefined}
+    <InfoboxImage {...image} />
+  {/if}
+  {#each imageRows as row (row.src)}
+    <InfoboxImage {...row} />
+  {/each}
+  {#if bodyRows.length > 0}
+    <InfoboxSection>
+      {#each bodyRows as row (row.label)}
+        {#if row.kind === 'fact'}
+          <InfoboxRow label={row.label} value={row.value} />
+        {:else if row.kind === 'link'}
+          <InfoboxRow label={row.label} value={row.text} href={row.href} external={row.external} />
+        {:else if row.kind === 'links'}
+          <InfoboxRow label={row.label}>
+            <ul class="flex flex-col gap-1">
+              {#each row.links ?? [] as link (link.href)}
+                <li><Link href={link.href}>{link.label}</Link></li>
+              {/each}
+            </ul>
+          </InfoboxRow>
+        {:else if row.kind === 'custom'}
+          <InfoboxRow label={row.label}>
+            {@render row.content()}
+          </InfoboxRow>
+        {/if}
+      {/each}
+    </InfoboxSection>
+  {/if}
+  {@render children?.()}
+</aside>

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

@@ -0,0 +1,26 @@
+import type { Snippet } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
+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;
+    /**
+     * Accessible name for the region when there is no `title`.
+     * @defaultValue `'Key facts'`
+     */
+    label?: string | undefined;
+    /** Renders an `InfoboxImage` above the body. */
+    image?: InfoboxImageSpec | undefined;
+    /** Rendered through the primitives below, inside one `InfoboxSection`. */
+    rows?: readonly Row[] | undefined;
+    /** float-right rail; off renders in normal flow (a grid column). */
+    float?: boolean | undefined;
+    /** Extra composed markup — `InfoboxSection`/`InfoboxRow`, or anything else. Rendered after `rows`. */
+    children?: Snippet<[]> | undefined;
+}
+/** The summary rail beside an entity page’s prose: an optional header and image above a body of labelled facts. */
+declare const Infobox: import("svelte").Component<Props, {}, "">;
+type Infobox = ReturnType<typeof Infobox>;
+export default Infobox;

package/dist/infobox/InfoboxHeader.svelte

@@ -0,0 +1,27 @@
+<!-- @component
+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.
+-->
+<script lang="ts">let { title, subtitle, class: className, ...rest } = $props();
+export {};
+</script>
+
+<div
+  {...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>
+  {#if subtitle !== undefined && subtitle !== ""}
+    <p class="text-base-content/60 mt-1 text-center text-sm select-none">
+      {subtitle}
+    </p>
+  {/if}
+</div>

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

@@ -0,0 +1,11 @@
+import type { HTMLAttributes } from "svelte/elements";
+interface Props extends HTMLAttributes<HTMLDivElement> {
+    /** The infobox heading text. */
+    title: string;
+    /** A line under the heading. */
+    subtitle?: string | undefined;
+}
+/** The title block at the top of an `Infobox`. */
+declare const InfoboxHeader: import("svelte").Component<Props, {}, "">;
+type InfoboxHeader = ReturnType<typeof InfoboxHeader>;
+export default InfoboxHeader;

package/dist/infobox/InfoboxImage.svelte

@@ -0,0 +1,38 @@
+<!-- @component
+The picture at the top of an `Infobox`, with its caption.
+-->
+<!--
+  InfoboxImage — the picture at the top of an `Infobox`, with its caption.
+
+  `width`/`height` are passed through so the browser can reserve the box
+  before the bytes arrive — the difference between a page that settles and
+  one that jumps under the reader's eye — but only reserve that space when
+  BOTH are present; the caller supplies them together or not at all.
+
+  `eager` (default off: an infobox usually sits beside the prose rather than
+  above it, so its picture is rarely the first thing painted) sets
+  `loading="eager"` and `fetchpriority="high"` together.
+-->
+<script lang="ts">let { src, alt, caption, width, height, eager = false, class: className, ...rest } = $props();
+const loading = $derived(eager ? "eager" : "lazy");
+const fetchpriority = $derived(eager ? "high" : undefined);
+export {};
+</script>
+
+<figure class="border-base-300 border-b">
+  <img
+    {...rest}
+    {src}
+    {alt}
+    {width}
+    {height}
+    {loading}
+    {fetchpriority}
+    class={['h-auto w-full', className]}
+  />
+  {#if caption !== undefined && caption !== ''}
+    <figcaption class="text-base-content/60 px-4 py-2 text-center text-xs italic">
+      {caption}
+    </figcaption>
+  {/if}
+</figure>