@thomasfosterau/components 0.0.0 → 0.2.0

package/dist/fields/segmented-field.d.ts

@@ -0,0 +1,128 @@
+/**
+ * What `DateField` and `TimeField` share when handing their props to bits-ui:
+ * the props themselves, and the split between the bits-ui root and the
+ * segment group `SegmentGroup` renders.
+ *
+ * @module
+ */
+import type { CalendarDateTime, DateValue, Time, ZonedDateTime } from '@internationalized/date';
+import type { HTMLAttributes } from 'svelte/elements';
+import type { FieldSize } from './field-types.ts';
+/** A time of day, alone or on a date: what a `TimeField` holds. */
+export type TimeValue = Time | CalendarDateTime | ZonedDateTime;
+/** The props `DateField` and `TimeField` share: everything but the value, its bounds and the granularity. */
+export interface SegmentedFieldProps extends Omit<HTMLAttributes<HTMLDivElement>, 'placeholder' | 'children' | 'id'> {
+    /** Force a 12- or 24-hour clock; omitted, the locale's. */
+    hourCycle?: 12 | 24 | undefined;
+    /** Form field name: bits-ui renders a hidden input with the ISO value. */
+    name?: string | undefined;
+    /** BCP 47 locale(s); the first is used. Falls back to the context's `locale()`. */
+    locales?: string | readonly string[] | undefined;
+    /**
+     * No interaction at all.
+     * @defaultValue `false`
+     */
+    disabled?: boolean | undefined;
+    /**
+     * Focusable and read out, but the value cannot change.
+     * @defaultValue `false`
+     */
+    readonly?: boolean | undefined;
+    /** @defaultValue `'md'` */
+    size?: FieldSize | undefined;
+    /** `FieldControl`: the segment group's `id`. */
+    id?: string | undefined;
+    /** `FieldControl`: the visible label's id; the group and each segment are `aria-labelledby` it. */
+    labelId?: string | undefined;
+    /**
+     * `FieldControl`: space-separated ids for the group's `aria-describedby`.
+     * @defaultValue `''`
+     */
+    describedBy?: string | undefined;
+    /**
+     * `FieldControl`: the field is in error — `aria-invalid` and the error border.
+     * @defaultValue `false`
+     */
+    invalid?: boolean | undefined;
+    /**
+     * `FieldControl`: a value is required for the form to submit.
+     * @defaultValue `false`
+     */
+    required?: boolean | undefined;
+}
+/** What `SegmentGroup` renders the group with. */
+export interface SegmentGroupOptions {
+    readonly id: string | undefined;
+    readonly name: string | undefined;
+    readonly labelId: string | undefined;
+    readonly describedBy: string;
+    readonly invalid: boolean;
+    readonly disabled: boolean;
+    readonly size: FieldSize;
+    /** The caller's remaining attributes, spread onto the group. */
+    readonly attributes: Record<string, unknown>;
+}
+/**
+ * Split the shared props into the bits-ui root's options (defaults applied,
+ * unset options dropped) and the segment group's. One function, so
+ * `DateField` and `TimeField` cannot disagree about a default.
+ */
+export declare function segmentedField(props: SegmentedFieldProps, contextLocale: string | readonly string[] | undefined): {
+    readonly root: Record<string, unknown>;
+    readonly group: SegmentGroupOptions;
+};
+/** The props `DatePicker` and `DateRangePicker` add to the segmented field: the calendar popover's. */
+export interface PickerProps {
+    /** Whether the calendar popover is open. Bindable. */
+    open?: boolean | undefined;
+    /** Days that cannot be chosen at all; rendered disabled. */
+    isDateDisabled?: ((date: DateValue) => boolean) | undefined;
+    /** Days shown but marked unavailable: booked, frost, closed. */
+    isDateUnavailable?: ((date: DateValue) => boolean) | undefined;
+    /** 0 = Sunday … 6 = Saturday; omitted, the locale's own week start. */
+    weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6 | undefined;
+    /**
+     * Months shown side by side in the popover.
+     * @defaultValue `1`
+     */
+    numberOfMonths?: number | undefined;
+    /**
+     * Accessible name of the calendar trigger button.
+     * @defaultValue `'Choose date'`
+     */
+    triggerLabel?: string | undefined;
+    /**
+     * Accessible name of the popover's calendar.
+     * @defaultValue `'Calendar'`
+     */
+    calendarLabel?: string | undefined;
+    /**
+     * Accessible name of the previous-month button.
+     * @defaultValue `'Previous month'`
+     */
+    previousLabel?: string | undefined;
+    /**
+     * Accessible name of the next-month button.
+     * @defaultValue `'Next month'`
+     */
+    nextLabel?: string | undefined;
+}
+/** What `pickerField` hands a picker: the bits-ui root's options, the segment group's, and the popover's labels. */
+export interface PickerField {
+    readonly root: Record<string, unknown>;
+    readonly group: SegmentGroupOptions;
+    readonly triggerLabel: string;
+    readonly calendarLabel: string;
+    readonly months: {
+        readonly locale: string;
+        readonly previousLabel: string;
+        readonly nextLabel: string;
+    };
+}
+/**
+ * Split a picker's props (the segmented field's plus the popover's) into
+ * what the bits-ui root, `SegmentGroup` and `PickerPopover` take, defaults
+ * applied. One function, so `DatePicker` and `DateRangePicker` cannot
+ * disagree about a default.
+ */
+export declare function pickerField(props: SegmentedFieldProps & Omit<PickerProps, 'open'>, contextLocale: string | readonly string[] | undefined): PickerField;

package/dist/fields/segmented-field.js

@@ -0,0 +1,52 @@
+/**
+ * What `DateField` and `TimeField` share when handing their props to bits-ui:
+ * the props themselves, and the split between the bits-ui root and the
+ * segment group `SegmentGroup` renders.
+ *
+ * @module
+ */
+import { definedProps, firstLocale } from "./calendar-props.js";
+/**
+ * Split the shared props into the bits-ui root's options (defaults applied,
+ * unset options dropped) and the segment group's. One function, so
+ * `DateField` and `TimeField` cannot disagree about a default.
+ */
+export function segmentedField(props, contextLocale) {
+    const { hourCycle, name, locales = contextLocale, disabled = false, readonly = false, size = 'md', id, labelId, describedBy = '', invalid = false, required = false, ...attributes } = props;
+    return {
+        root: {
+            ...definedProps({ hourCycle, locale: firstLocale(locales) }),
+            disabled,
+            readonly,
+            required,
+        },
+        group: { id, name, labelId, describedBy, invalid, disabled, size, attributes },
+    };
+}
+/**
+ * Split a picker's props (the segmented field's plus the popover's) into
+ * what the bits-ui root, `SegmentGroup` and `PickerPopover` take, defaults
+ * applied. One function, so `DatePicker` and `DateRangePicker` cannot
+ * disagree about a default.
+ */
+export function pickerField(props, contextLocale) {
+    const { isDateDisabled, isDateUnavailable, weekStartsOn, numberOfMonths = 1, triggerLabel = 'Choose date', calendarLabel = 'Calendar', previousLabel = 'Previous month', nextLabel = 'Next month', ...fieldProps } = props;
+    const field = segmentedField(fieldProps, contextLocale);
+    return {
+        root: {
+            ...field.root,
+            ...definedProps({ isDateDisabled, isDateUnavailable, weekStartsOn }),
+            numberOfMonths,
+            calendarLabel,
+            weekdayFormat: 'short',
+        },
+        group: field.group,
+        triggerLabel,
+        calendarLabel,
+        months: {
+            locale: firstLocale(fieldProps.locales ?? contextLocale) ?? 'en',
+            previousLabel,
+            nextLabel,
+        },
+    };
+}

package/dist/fields/slider-keys.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The Page Up / Page Down arithmetic behind `Slider`, which bits-ui 2.20's
+ * thumb keyboard handler does not cover. Pure, so the component's key handler
+ * stays a dispatch and the arithmetic is testable on its own.
+ *
+ * @module
+ */
+/** The scale a slider moves over: its bounds and its step (a number, or explicit snap points). */
+export interface SliderScale {
+    readonly min: number;
+    readonly max: number;
+    readonly step: number | readonly number[];
+}
+/**
+ * The value one page away from `current` in `direction` (`1` up, `-1` down):
+ * a tenth of the scale, rounded to whole steps and never less than one. For
+ * snap points, a tenth of the points, never less than one.
+ */
+export declare function pageStep(current: number, direction: 1 | -1, scale: SliderScale): number;
+/** Clamp `next` for thumb `index` between its neighbours (or the scale's ends), so thumbs never cross. */
+export declare function clampToNeighbours(values: readonly number[], index: number, next: number, scale: SliderScale): number;

package/dist/fields/slider-keys.js

@@ -0,0 +1,37 @@
+/**
+ * The Page Up / Page Down arithmetic behind `Slider`, which bits-ui 2.20's
+ * thumb keyboard handler does not cover. Pure, so the component's key handler
+ * stays a dispatch and the arithmetic is testable on its own.
+ *
+ * @module
+ */
+/** Index of the snap point nearest `value`. */
+function nearestIndex(points, value) {
+    let best = 0;
+    points.forEach((point, index) => {
+        if (Math.abs(point - value) < Math.abs((points[best] ?? point) - value))
+            best = index;
+    });
+    return best;
+}
+/**
+ * The value one page away from `current` in `direction` (`1` up, `-1` down):
+ * a tenth of the scale, rounded to whole steps and never less than one. For
+ * snap points, a tenth of the points, never less than one.
+ */
+export function pageStep(current, direction, scale) {
+    const { min, max, step } = scale;
+    if (typeof step === 'number') {
+        return current + direction * step * Math.max(1, Math.round((max - min) / 10 / step));
+    }
+    const points = [...step].sort((a, b) => a - b);
+    const jump = Math.max(1, Math.round(points.length / 10));
+    const target = Math.min(points.length - 1, Math.max(0, nearestIndex(points, current) + direction * jump));
+    return points[target] ?? current;
+}
+/** Clamp `next` for thumb `index` between its neighbours (or the scale's ends), so thumbs never cross. */
+export function clampToNeighbours(values, index, next, scale) {
+    const lower = values[index - 1] ?? scale.min;
+    const upper = values[index + 1] ?? scale.max;
+    return Math.min(upper, Math.max(lower, next));
+}

package/dist/formatting/Countdown.svelte

@@ -0,0 +1,110 @@
+<!-- @component
+The time left until an instant, ticking every second in daisyUI's `countdown` digits, read out coarsely and announced once at zero.
+-->
+<!--
+  Countdown — a seed-swap opening, an auction close, a watering timer.
+
+  ARIA contract (the part that matters): a `role="timer"` named by `label`.
+  A second-by-second announcement is unusable, so the ticking digits are
+  `aria-hidden`, and what assistive technology reads is a separate
+  visually hidden text at a coarse granularity that changes far less often:
+  whole minutes under an hour ("4 minutes"), whole hours above it ("2
+  days, 4 hours"). The granularity is fixed, not a prop. `role="timer"` is
+  implicitly `aria-live="off"`, so even that is read on demand, not pushed.
+  At zero a polite `role="status"` announces `completeLabel` once. With
+  `prefers-reduced-motion: reduce` the digit roll does not animate
+  (WCAG 2.2.2).
+
+  The clock starts in an `$effect`, never at module load (`sideEffects:
+  false`), and stops on destroy or at zero. The first render uses the
+  current time, and the client re-syncs after mount. An `until` already in
+  the past renders the complete state without calling `onComplete`: that
+  only fires when the countdown is seen reaching zero.
+-->
+<script lang="ts">import { getComponentsContext } from "../context.svelte.js";
+import { formatDuration } from "./duration.js";
+let { until, label, largestUnit = "days", display = "digits", completeLabel = "Time is up", onComplete, locales = getComponentsContext().locale(), class: className, ...rest } = $props();
+const SECOND = 1e3;
+const MINUTE = 60 * SECOND;
+const HOUR = 60 * MINUTE;
+const DAY = 24 * HOUR;
+const SIZES = {
+	days: DAY,
+	hours: HOUR,
+	minutes: MINUTE,
+	seconds: SECOND
+};
+const ORDER = [
+	"days",
+	"hours",
+	"minutes",
+	"seconds"
+];
+let now = $state(Date.now());
+const target = $derived(new Date(until).getTime());
+const remaining = $derived(Math.max(0, target - now));
+const complete = $derived(remaining === 0);
+/** The units shown, from `largestUnit` down to seconds, each with its count. */
+const parts = $derived.by(() => {
+	let rest = Math.ceil(remaining / SECOND) * SECOND;
+	return ORDER.slice(ORDER.indexOf(largestUnit)).map((unit) => {
+		const count = Math.floor(rest / SIZES[unit]);
+		rest -= count * SIZES[unit];
+		return {
+			unit,
+			count
+		};
+	});
+});
+/** The spoken, coarse rendering: minutes under an hour, hours above. */
+const spoken = $derived.by(() => {
+	if (remaining >= HOUR) {
+		const days = Math.floor(remaining / DAY);
+		const hours = Math.floor(remaining % DAY / HOUR);
+		const value = days > 0 ? {
+			days,
+			hours
+		} : { hours };
+		return formatDuration(value, locales, "long");
+	}
+	return formatDuration({ minutes: Math.ceil(remaining / MINUTE) }, locales, "long");
+});
+const text = $derived(formatDuration(Object.fromEntries(parts.map(({ unit, count }) => [unit, count])), locales, "short"));
+/** The narrow unit label after each digit group ("d", "h", "m", "s" in English). */
+const unitLabel = (unit, count) => new Intl.NumberFormat(locales, {
+	style: "unit",
+	unit: unit.slice(0, -1),
+	unitDisplay: "narrow"
+}).formatToParts(count).filter((part) => part.type === "unit").map((part) => part.value).join("");
+$effect(() => {
+	now = Date.now();
+	if (target <= now) return;
+	let done = false;
+	const timer = setInterval(() => {
+		now = Date.now();
+		if (!done && now >= target) {
+			done = true;
+			clearInterval(timer);
+			onComplete?.();
+		}
+	}, SECOND);
+	return () => clearInterval(timer);
+});
+</script>
+
+<span {...rest} role="timer" aria-label={label} class={['inline-flex flex-wrap items-baseline gap-2', className]}>
+  <span aria-hidden="true">{label}</span>
+  <span aria-hidden="true" class="inline-flex items-baseline gap-1 font-mono tabular-nums">
+    {#if display === 'digits'}
+      {#each parts as { unit, count } (unit)}
+        <span class="countdown motion-reduce:*:before:transition-none"
+          ><span style:--value={count} style:--digits={unit === largestUnit ? undefined : 2}>{count}</span></span
+        >{unitLabel(unit, count)}
+      {/each}
+    {:else}
+      {text}
+    {/if}
+  </span>
+  <span class="sr-only">{complete ? '' : spoken}</span>
+  <span role="status" class="sr-only">{complete ? completeLabel : ''}</span>
+</span>

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

@@ -0,0 +1,35 @@
+import type { HTMLAttributes } from 'svelte/elements';
+/** The largest unit a `Countdown` shows. */
+type CountdownUnit = 'days' | 'hours' | 'minutes';
+interface Props extends Omit<HTMLAttributes<HTMLSpanElement>, 'children'> {
+    /** The instant counted down to: a `Date`, epoch milliseconds or an ISO string. */
+    until: Date | number | string;
+    /** Accessible name and visible lead-in, e.g. `'Seed swap opens in'`. */
+    label: string;
+    /**
+     * Largest unit shown; larger amounts fold into it (50 hours with `'hours'`).
+     * @defaultValue `'days'`
+     */
+    largestUnit?: CountdownUnit | undefined;
+    /**
+     * daisyUI digit roll, or formatted text.
+     * @defaultValue `'digits'`
+     */
+    display?: 'digits' | 'text' | undefined;
+    /**
+     * Announced once at zero.
+     * @defaultValue `'Time is up'`
+     */
+    completeLabel?: string | undefined;
+    /** Called once when the countdown is seen reaching zero. */
+    onComplete?: (() => void) | undefined;
+    /**
+     * Locale(s) for the unit words.
+     * @defaultValue the components context's `locale()`
+     */
+    locales?: string | readonly string[] | undefined;
+}
+/** The time left until an instant, ticking every second in daisyUI's `countdown` digits, read out coarsely and announced once at zero. */
+declare const Countdown: import("svelte").Component<Props, {}, "">;
+type Countdown = ReturnType<typeof Countdown>;
+export default Countdown;

package/dist/formatting/DateTime.svelte

@@ -0,0 +1,35 @@
+<!-- @component
+A `<time>` element with the ISO instant in `datetime` and the `Intl.DateTimeFormat` rendering as its text.
+-->
+<!--
+  DateTime — a `<time>` element carrying the ISO instant in `datetime` and
+  `Intl.DateTimeFormat`'s locale rendering as its text.
+
+  ARIA contract: none beyond the native `<time>` semantics — the `datetime`
+  attribute is what makes the value machine-readable; a screen reader still
+  announces the formatted text content (or the `children` snippet, when
+  given), never the ISO string.
+
+  `options` (raw `Intl.DateTimeFormatOptions`) wins over `dateStyle`/
+  `timeStyle` when both are supplied, so a caller that needs a field-level
+  combination (`{ year: 'numeric', month: 'long' }`) isn't stuck with the
+  coarse style presets.
+-->
+<script lang="ts">import { getComponentsContext } from "../context.svelte.js";
+let { value, locales = getComponentsContext().locale(), dateStyle = "medium", timeStyle, options, children, ...rest } = $props();
+const instant = $derived(new Date(value));
+// The formatter and the formatted string are separate `$derived` values so
+// constructing the (relatively expensive) `Intl.DateTimeFormat` is skipped
+// when only `value` changes, not when locale/options change. See
+// PERF-CPU-003 in docs/specs/performance-invariants.md.
+const format = $derived(new Intl.DateTimeFormat(locales, options ?? {
+	dateStyle,
+	timeStyle
+}));
+const formatted = $derived(format.format(instant));
+const iso = $derived(instant.toISOString());
+</script>
+
+<time {...rest} datetime={iso}>
+  {#if children}{@render children()}{:else}{formatted}{/if}
+</time>

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

@@ -0,0 +1,26 @@
+import type { Snippet } from 'svelte';
+import type { HTMLTimeAttributes } from 'svelte/elements';
+interface Props extends Omit<HTMLTimeAttributes, 'children'> {
+    /** The instant: a `Date`, epoch milliseconds or an ISO string. */
+    value: Date | number | string;
+    /**
+     * Locale(s) for `Intl` formatting.
+     * @defaultValue the components context's `locale()`
+     */
+    locales?: string | readonly string[] | undefined;
+    /**
+     * `Intl.DateTimeFormat` `dateStyle`.
+     * @defaultValue `'medium'`
+     */
+    dateStyle?: Intl.DateTimeFormatOptions['dateStyle'] | undefined;
+    /** `Intl.DateTimeFormat` `timeStyle`; omitted, no time is shown. */
+    timeStyle?: Intl.DateTimeFormatOptions['timeStyle'] | undefined;
+    /** Raw `Intl.DateTimeFormatOptions`; wins over `dateStyle`/`timeStyle` when given. */
+    options?: Intl.DateTimeFormatOptions | undefined;
+    /** Replaces the formatted text; the `datetime` attribute stays machine-readable. */
+    children?: Snippet<[]> | undefined;
+}
+/** A `<time>` element with the ISO instant in `datetime` and the `Intl.DateTimeFormat` rendering as its text. */
+declare const DateTime: import("svelte").Component<Props, {}, "">;
+type DateTime = ReturnType<typeof DateTime>;
+export default DateTime;

package/dist/formatting/Duration.svelte

@@ -0,0 +1,18 @@
+<!-- @component
+A length of time ("2 hr, 30 min") in a `<time>` element whose `datetime` is the ISO 8601 duration.
+-->
+<!--
+  Duration — the length-of-time counterpart of `DateTime` (an instant) and
+  `RelativeTime` (an instant relative to now), formatted by
+  `formatDuration` (see `duration.ts`).
+
+  ARIA contract: none beyond the native `<time>`. Its `datetime` holds the
+  HTML duration string (`PT2H30M`), the content the localised text.
+-->
+<script lang="ts">import { getComponentsContext } from "../context.svelte.js";
+import { durationFromMilliseconds, formatDuration, toIsoDuration } from "./duration.js";
+let { value, style = "short", locales = getComponentsContext().locale(), ...rest } = $props();
+const duration = $derived(typeof value === "number" ? durationFromMilliseconds(value) : value);
+</script>
+
+<time {...rest} datetime={toIsoDuration(duration)}>{formatDuration(duration, locales, style)}</time>

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

@@ -0,0 +1,20 @@
+import type { HTMLTimeAttributes } from 'svelte/elements';
+import { type DurationStyle, type DurationValue } from './duration.ts';
+interface Props extends Omit<HTMLTimeAttributes, 'children'> {
+    /** A `DurationValue`, or milliseconds. */
+    value: DurationValue | number;
+    /**
+     * How it is spelled.
+     * @defaultValue `'short'`
+     */
+    style?: DurationStyle | undefined;
+    /**
+     * Locale(s) for `Intl` formatting.
+     * @defaultValue the components context's `locale()`
+     */
+    locales?: string | readonly string[] | undefined;
+}
+/** A length of time ("2 hr, 30 min") in a `<time>` element whose `datetime` is the ISO 8601 duration. */
+declare const Duration: import("svelte").Component<Props, {}, "">;
+type Duration = ReturnType<typeof Duration>;
+export default Duration;

package/dist/formatting/FormatList.svelte

@@ -0,0 +1,31 @@
+<!-- @component
+Renders `items` through `Intl.ListFormat`, with each item drawn by the `children` snippet and the joining words from the locale.
+-->
+<!--
+  FormatList<T> — renders `items` through `Intl.ListFormat`, letting the
+  `children` snippet render each element while literal text ("and", ", ")
+  comes from the locale's own conjunction/disjunction rules.
+
+  No wrapping element of its own — it emits `children(item)` and text nodes
+  in sequence, so the caller controls the surrounding markup entirely.
+-->
+<script lang="ts" generics="T">import { getComponentsContext } from "../context.svelte.js";
+let { items, style = "long", type = "conjunction", locales = getComponentsContext().locale(), children } = $props();
+const format = $derived(new Intl.ListFormat(locales, {
+	style,
+	type
+}));
+// `Intl.ListFormat` only formats strings, so format the items' *indices*
+// and map each "element" part back to the real item by index — that way
+// the snippet gets the original `T`, not its stringified form.
+const indices = $derived(items.map((_, index) => index.toString()));
+const parts = $derived(format.formatToParts(indices));
+</script>
+
+{#each parts as part, i (i)}
+  {#if part.type === 'element'}
+    {@render children(items[Number.parseInt(part.value, 10)] as T)}
+  {:else}
+    {part.value}
+  {/if}
+{/each}

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

@@ -0,0 +1,46 @@
+import type { Snippet } from 'svelte';
+declare function $$render<T>(): {
+    props: {
+        /** The items to join, each rendered by `children`. */
+        items: readonly T[];
+        /**
+         * `Intl.ListFormat` style.
+         * @defaultValue `'long'`
+         */
+        style?: Intl.ListFormatOptions["style"] | undefined;
+        /**
+         * `Intl.ListFormat` type.
+         * @defaultValue `'conjunction'`
+         */
+        type?: Intl.ListFormatOptions["type"] | undefined;
+        /**
+         * Locale(s) for `Intl` formatting.
+         * @defaultValue the components context's `locale()`
+         */
+        locales?: string | readonly string[] | undefined;
+        /** Renders one item. */
+        children: Snippet<[T]>;
+    };
+    exports: {};
+    bindings: "";
+    slots: {};
+    events: {};
+};
+declare class __sveltets_Render<T> {
+    props(): ReturnType<typeof $$render<T>>['props'];
+    events(): ReturnType<typeof $$render<T>>['events'];
+    slots(): ReturnType<typeof $$render<T>>['slots'];
+    bindings(): "";
+    exports(): {};
+}
+interface $$IsomorphicComponent {
+    new <T>(options: import('svelte').ComponentConstructorOptions<ReturnType<__sveltets_Render<T>['props']>>): import('svelte').SvelteComponent<ReturnType<__sveltets_Render<T>['props']>, ReturnType<__sveltets_Render<T>['events']>, ReturnType<__sveltets_Render<T>['slots']>> & {
+        $$bindings?: ReturnType<__sveltets_Render<T>['bindings']>;
+    } & ReturnType<__sveltets_Render<T>['exports']>;
+    <T>(internal: unknown, props: ReturnType<__sveltets_Render<T>['props']> & {}): ReturnType<__sveltets_Render<T>['exports']>;
+    z_$$bindings?: ReturnType<__sveltets_Render<any>['bindings']>;
+}
+/** Renders `items` through `Intl.ListFormat`, with each item drawn by the `children` snippet and the joining words from the locale. */
+declare const FormatList: $$IsomorphicComponent;
+type FormatList<T> = InstanceType<typeof FormatList<T>>;
+export default FormatList;

package/dist/formatting/Highlight.svelte

@@ -0,0 +1,51 @@
+<!-- @component
+Best-effort client-side highlighting of query tokens in a search result.
+-->
+<!--
+  Highlight — best-effort client-side token highlight for search results.
+
+  Splits `query` on whitespace, escapes regex metacharacters, and wraps
+  case-insensitive matches in `<mark>`. Intentionally naive: no stemming, no
+  FTS-aware tokenisation, no diacritic folding — the authoritative match is
+  whatever server-side search produced; this is a UX nicety, and its highlights should not be read as
+  "this is exactly what full-text search matched".
+-->
+<script lang="ts" module>function escapeRegex(value) {
+	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+* 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 function tokenise(text, query) {
+	const tokens = query.trim().split(/\s+/).filter((token) => token.length > 0).map(escapeRegex);
+	if (tokens.length === 0 || text.length === 0) {
+		return [{
+			text,
+			match: false
+		}];
+	}
+	// `String.prototype.split` with a single capturing group interleaves the
+	// captured matches into the result at odd indices: [before, match,
+	// between, match, …]. Read `match` from that index parity rather than
+	// re-testing each segment — testing each part against a *global* regex
+	// would leave `lastIndex` advanced on non-matching segments, which can
+	// misclassify later segments and drop highlights. Map first (parity is
+	// meaningful on the raw split array), then filter empties.
+	const pattern = new RegExp(`(${tokens.join("|")})`, "gi");
+	return text.split(pattern).map((part, index) => ({
+		text: part,
+		match: index % 2 === 1
+	})).filter((segment) => segment.text.length > 0);
+}
+</script>
+
+<script lang="ts">const { text, query } = $props();
+const segments = $derived(tokenise(text, query));
+</script>
+
+{#each segments as segment, i (i)}
+  {#if segment.match}
+    <mark class="bg-warning/30 text-base-content rounded-sm px-0.5">{segment.text}</mark>
+  {:else}{segment.text}{/if}
+{/each}

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

@@ -0,0 +1,19 @@
+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. */
+    text: string;
+    /** The user's search query. Tokens are highlighted within `text`. */
+    query: string;
+}
+/** Best-effort client-side highlighting of query tokens in a search result. */
+declare const Highlight: import("svelte").Component<Props, {}, "">;
+type Highlight = ReturnType<typeof Highlight>;
+export default Highlight;