@thomasfosterau/components 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,43 @@
+import type { HTMLDataAttributes } from 'svelte/elements';
+interface Props extends Omit<HTMLDataAttributes, 'value'> {
+    /** The number to format; the raw value also goes in the `value` attribute. */
+    value: number | bigint;
+    /**
+     * Locale(s) for `Intl` formatting.
+     * @defaultValue the components context's `locale()`
+     */
+    locales?: string | readonly string[] | undefined;
+    /**
+     * `Intl.NumberFormat` `style`.
+     * @defaultValue `'decimal'`
+     */
+    style?: Intl.NumberFormatOptions['style'] | undefined;
+    /** The unit when `style` is `unit` (`kilometer`, `percent`). */
+    unit?: string | undefined;
+    /**
+     * `Intl.NumberFormat` `unitDisplay`.
+     * @defaultValue `'short'`
+     */
+    unitDisplay?: Intl.NumberFormatOptions['unitDisplay'] | undefined;
+    /** ISO 4217 code when `style` is `currency`. */
+    currency?: string | undefined;
+    /**
+     * `Intl.NumberFormat` `currencyDisplay`.
+     * @defaultValue `'symbol'`
+     */
+    currencyDisplay?: Intl.NumberFormatOptions['currencyDisplay'] | undefined;
+    /** `Intl.NumberFormat` `maximumFractionDigits`. */
+    maximumFractionDigits?: number | undefined;
+    /** `Intl.NumberFormat` `minimumFractionDigits`. */
+    minimumFractionDigits?: number | undefined;
+    /** `Intl.NumberFormat` `signDisplay`. */
+    signDisplay?: Intl.NumberFormatOptions['signDisplay'] | undefined;
+    /** `Intl.NumberFormat` `notation`. */
+    notation?: Intl.NumberFormatOptions['notation'] | undefined;
+    /** Raw `Intl.NumberFormatOptions`; wins over the individual style props when given. */
+    options?: Intl.NumberFormatOptions | undefined;
+}
+/** A `<data>` element whose text is the `Intl.NumberFormat` rendering and whose `value` attribute keeps the raw number. */
+declare const Number: import("svelte").Component<Props, {}, "">;
+type Number = ReturnType<typeof Number>;
+export default Number;

package/dist/formatting/RelativeTime.svelte

@@ -0,0 +1,69 @@
+<!-- @component
+"3 days ago" / "in 2 hours" via `Intl.RelativeTimeFormat`, in the largest unit whose magnitude is at least one.
+-->
+<!--
+  RelativeTime — "3 days ago" / "in 2 hours" via `Intl.RelativeTimeFormat`,
+  picking the largest unit (seconds → years) whose magnitude is at least one.
+
+  ARIA contract: none beyond native `<time>` semantics. The absolute instant
+  is never hidden — it is both the machine-readable `datetime` and the
+  human-readable `title`, so a reader who hovers (or a tool that reads
+  `title`) gets the precise moment the relative text is glossing over.
+-->
+<script lang="ts">import { getComponentsContext } from "../context.svelte.js";
+let { value, now, locales = getComponentsContext().locale(), numeric = "auto", style = "long", ...rest } = $props();
+const UNITS = [
+	{
+		unit: "year",
+		ms: 365.25 * 24 * 60 * 60 * 1e3
+	},
+	{
+		unit: "month",
+		ms: 30.44 * 24 * 60 * 60 * 1e3
+	},
+	{
+		unit: "week",
+		ms: 7 * 24 * 60 * 60 * 1e3
+	},
+	{
+		unit: "day",
+		ms: 24 * 60 * 60 * 1e3
+	},
+	{
+		unit: "hour",
+		ms: 60 * 60 * 1e3
+	},
+	{
+		unit: "minute",
+		ms: 60 * 1e3
+	},
+	{
+		unit: "second",
+		ms: 1e3
+	}
+];
+const instant = $derived(new Date(value));
+const reference = $derived(new Date(now ?? Date.now()));
+const diffMs = $derived(instant.getTime() - reference.getTime());
+// Largest unit whose magnitude rounds to at least one; falls back to
+// seconds for anything smaller (e.g. "0 seconds ago" / "in 0 seconds").
+const picked = $derived(UNITS.find((candidate) => Math.abs(diffMs) >= candidate.ms) ?? UNITS[UNITS.length - 1]);
+const roundedValue = $derived(Math.round(diffMs / picked.ms));
+// The formatter and the formatted string are separate `$derived` values so
+// constructing the (relatively expensive) `Intl.RelativeTimeFormat` is
+// skipped when only `value`/`now` change. See PERF-CPU-003 in
+// docs/specs/performance-invariants.md.
+const format = $derived(new Intl.RelativeTimeFormat(locales, {
+	numeric,
+	style
+}));
+const formatted = $derived(format.format(roundedValue, picked.unit));
+const iso = $derived(instant.toISOString());
+const absoluteFormat = $derived(new Intl.DateTimeFormat(locales, {
+	dateStyle: "full",
+	timeStyle: "short"
+}));
+const absolute = $derived(absoluteFormat.format(instant));
+</script>
+
+<time {...rest} datetime={iso} title={absolute}>{formatted}</time>

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

@@ -0,0 +1,26 @@
+import type { HTMLTimeAttributes } from 'svelte/elements';
+interface Props extends HTMLTimeAttributes {
+    /** The instant: a `Date`, epoch milliseconds or an ISO string. */
+    value: Date | number | string;
+    /** The instant "now" is measured from; defaults to the current wall clock at render. */
+    now?: Date | number | undefined;
+    /**
+     * Locale(s) for `Intl` formatting.
+     * @defaultValue the components context's `locale()`
+     */
+    locales?: string | readonly string[] | undefined;
+    /**
+     * `Intl.RelativeTimeFormat` `numeric`; `auto` allows "yesterday".
+     * @defaultValue `'auto'`
+     */
+    numeric?: Intl.RelativeTimeFormatOptions['numeric'] | undefined;
+    /**
+     * `Intl.RelativeTimeFormat` `style`.
+     * @defaultValue `'long'`
+     */
+    style?: Intl.RelativeTimeFormatOptions['style'] | undefined;
+}
+/** "3 days ago" / "in 2 hours" via `Intl.RelativeTimeFormat`, in the largest unit whose magnitude is at least one. */
+declare const RelativeTime: import("svelte").Component<Props, {}, "">;
+type RelativeTime = ReturnType<typeof RelativeTime>;
+export default RelativeTime;

package/dist/formatting/Year.svelte

@@ -0,0 +1,39 @@
+<!-- @component
+A `<time>` element carrying just a year, for dates whose precision really is a year.
+-->
+<!--
+  Year — a `<time>` element carrying just a year: `datetime="1925"`, and
+  `Intl.DateTimeFormat`'s locale rendering of the year (with its era, when
+  asked) as the text. For publication dates, lifespans and anything else whose
+  precision really is a year.
+
+  ARIA contract: none beyond the native `<time>` semantics. `datetime` is a
+  valid HTML year string (four or more digits), so the value stays
+  machine-readable at the precision it actually has rather than claiming a
+  midnight-on-1-January instant.
+
+  A `number` is a CALENDAR YEAR (`1925`), not an epoch timestamp — that is
+  what a caller holding "the year" has. A `Date` or string is read as an
+  instant and its UTC year is taken, so a date at midnight UTC never renders
+  as the previous year in a timezone west of Greenwich. Years before 1 CE have
+  no HTML year string, so for those `datetime` falls back to the ISO instant.
+-->
+<script lang="ts">import { getComponentsContext } from "../context.svelte.js";
+let { value, locales = getComponentsContext().locale(), era, representation = "numeric", ...rest } = $props();
+const instant = $derived.by(() => {
+	if (typeof value !== "number") return new Date(value);
+	const date = new Date(Date.UTC(2e3, 0, 1));
+	date.setUTCFullYear(value);
+	return date;
+});
+const format = $derived(new Intl.DateTimeFormat(locales, {
+	year: representation,
+	era,
+	timeZone: "UTC"
+}));
+const formatted = $derived(format.format(instant));
+const year = $derived(instant.getUTCFullYear());
+const datetime = $derived(year >= 1 ? String(year).padStart(4, "0") : instant.toISOString());
+</script>
+
+<time {...rest} {datetime}>{formatted}</time>

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

@@ -0,0 +1,21 @@
+import type { HTMLTimeAttributes } from 'svelte/elements';
+interface Props extends HTMLTimeAttributes {
+    /** A calendar year, or an instant (its UTC year is used). */
+    value: Date | number | string;
+    /**
+     * Locale(s) for `Intl` formatting.
+     * @defaultValue the components context's `locale()`
+     */
+    locales?: string | readonly string[] | undefined;
+    /** Append the era: `1925 AD`. */
+    era?: Intl.DateTimeFormatOptions['era'] | undefined;
+    /**
+     * Four digits or two.
+     * @defaultValue `'numeric'`
+     */
+    representation?: 'numeric' | '2-digit' | undefined;
+}
+/** A `<time>` element carrying just a year, for dates whose precision really is a year. */
+declare const Year: import("svelte").Component<Props, {}, "">;
+type Year = ReturnType<typeof Year>;
+export default Year;

package/dist/formatting/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * formatting — locale-aware rendering of dates, numbers, lists and search
+ * highlights. See the package README for the family reference.
+ *
+ * @module
+ */
+export { default as DateTime } from './DateTime.svelte';
+export { default as NumberFormat } from './Number.svelte';
+export { default as FormatList } from './FormatList.svelte';
+export { default as RelativeTime } from './RelativeTime.svelte';
+export { default as Year } from './Year.svelte';
+export { default as Highlight, tokenise } from './Highlight.svelte';

package/dist/formatting/index.js

@@ -0,0 +1,14 @@
+/**
+ * formatting — locale-aware rendering of dates, numbers, lists and search
+ * highlights. See the package README for the family reference.
+ *
+ * @module
+ */
+export { default as DateTime } from './DateTime.svelte';
+// `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';
+export { default as FormatList } from './FormatList.svelte';
+export { default as RelativeTime } from './RelativeTime.svelte';
+export { default as Year } from './Year.svelte';
+export { default as Highlight, tokenise } from './Highlight.svelte';

package/dist/forms/EntityForm.svelte

@@ -0,0 +1,177 @@
+<!-- @component
+Renders an `@thomasfosterau/effect-forms-svelte` `defineEntityForm` definition through this library’s field primitives.
+-->
+<!--
+  EntityForm — the generic renderer for an `@thomasfosterau/effect-forms-svelte`
+  `defineEntityForm` definition: it walks `definition.entriesFor(mode)` and
+  renders each entry through this library's field primitives —
+  `FormField` + `TextInput` / `DateInput` / `Textarea` / `Select` for scalars
+  and selects, and the entry's own component for a bespoke widget (a picker,
+  a contributor list), bridged through the widget contract below.
+
+  The one component of this package that touches Effect, which is why it is a
+  separate entry point (`@thomasfosterau/components/entity-form`) with
+  `@thomasfosterau/effect-forms-svelte` an OPTIONAL peer: a consumer that
+  never imports this entry never installs the form library or `effect`. The
+  renderer itself imports only the store (`createForm`) and types.
+
+  **Seeding.** `definition`, `mode`, `initial` and `initialRows` configure the
+  store ONCE, at mount: a form never changes entity or mode mid-flight, and an
+  edit page's values must land in the SSR HTML. There is no `$effect`
+  re-seeding, so a value typed before hydration is never wiped by a late seed.
+  A create form whose command carries a client id gets one minted here, once
+  per mount, so a retried submission stays idempotent.
+
+  **The widget contract.** A widget entry receives, in this order: its
+  definition's `props()`, then the caller's `fieldProps[key]`, then the bridge
+  — `name`, `value`, `onChange`, `errors`. The bridge is spread LAST, so
+  neither of the first two can sever the store binding. A `value` widget
+  bridges a string field of the store; a `rows` widget bridges a row list held
+  here and serialises it itself (its own hidden input).
+
+  **Submission.** `enhance(form)` supplies the spreadable `<form>` attributes.
+  It defaults to the store's own `form.props` (POST + its progressive
+  enhancement); a SvelteKit app passes its `$app/forms`-backed `enhanceForm`,
+  which this package cannot import.
+
+  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.
+-->
+<script lang="ts">import { createForm } from "@thomasfosterau/effect-forms-svelte";
+import DateInput from "../fields/DateInput.svelte";
+import FormField from "../fields/FormField.svelte";
+import Select from "../fields/Select.svelte";
+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();
+// Configure-once, at mount (see the header): these reads are deliberately
+// not reactive.
+// svelte-ignore state_referenced_locally
+const configured = {
+	definition,
+	mode,
+	initial,
+	initialRows
+};
+const baseDefaults = configured.mode === "create" ? configured.definition.createDefaults : configured.definition.updateDefaults;
+const defaults = {
+	...baseDefaults,
+	...configured.initial
+};
+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.
+const handle = (key) => form.field(key);
+const getField = (key) => handle(key).value ?? "";
+const setField = (key, next) => {
+	handle(key).value = next;
+};
+let rows = $state(Object.fromEntries(entries.filter((entry) => entry._tag === "widget" && entry.bridge === "rows").map((entry) => [entry.key, [...configured.initialRows[entry.key] ?? []]])));
+const bridge = (entry) => entry.bridge === "rows" ? {
+	name: entry.key,
+	value: rows[entry.key] ?? [],
+	onChange: (next) => {
+		rows[entry.key] = next;
+	},
+	errors: handle(entry.key).visibleErrors
+} : {
+	name: entry.key,
+	value: getField(entry.key),
+	onChange: (next) => setField(entry.key, next),
+	errors: handle(entry.key).visibleErrors
+};
+const selectOptions = (entry) => (configured.definition.fieldFor(entry.key).options ?? []).map((value) => ({
+	value,
+	label: entry.options.optionLabels[value]?.() ?? value
+}));
+const inputMode = (entry) => entry.options.inputmode ?? (configured.definition.fieldFor(entry.key).kind === "number" ? "numeric" : undefined);
+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 ?? []);
+const fieldId = (key) => `entity-form-${key}`;
+</script>
+
+<form {...rest} {...enhance(form)} {action} class={['space-y-4', className]}>
+  {#if showHiddenId}
+    <input type="hidden" name="id" value={getField('id')} />
+  {/if}
+
+  <FormErrors messages={rootErrors} />
+
+  {#each entries as entry (entry.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}
+      >
+        {#snippet children(control)}
+          <Select
+            {...control}
+            name={entry.key}
+            options={selectOptions(entry)}
+            placeholder={selectPlaceholder}
+            bind:value={() => getField(entry.key), (next: string) => setField(entry.key, next)}
+          />
+        {/snippet}
+      </FormField>
+    {:else}
+      <FormField
+        id={fieldId(entry.key)}
+        label={entry.options.label()}
+        required={entry.options.required === true}
+        errors={handle(entry.key).visibleErrors}
+        {requiredLabel}
+      >
+        {#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}
+        {/snippet}
+      </FormField>
+    {/if}
+  {/each}
+
+  <FormActions
+    {submitLabel}
+    {pendingLabel}
+    pending={form.submitting}
+    disabled={gated}
+    {cancelHref}
+    {cancelLabel}
+  />
+</form>

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

@@ -0,0 +1,57 @@
+import { createForm, type EntityFormDefinition } from '@thomasfosterau/effect-forms-svelte';
+import type { HTMLFormAttributes } from 'svelte/elements';
+type Store = ReturnType<typeof createForm>;
+interface Props extends Omit<HTMLFormAttributes, 'action' | 'method' | 'children'> {
+    /** The form definition from `defineEntityForm`. */
+    definition: EntityFormDefinition;
+    /** Which of the definition’s entry sets to render. */
+    mode: 'create' | 'update';
+    /** Where Cancel goes. Omitted renders no cancel link. */
+    cancelHref?: string | undefined;
+    /** A named action (`?/addItem`). Omitted posts to the page's default action. */
+    action?: string | undefined;
+    /**
+     * All-string initial values: an edit page's current values, or a create page's pre-filled FK.
+     * @defaultValue `{}`
+     */
+    initial?: Readonly<Record<string, string>> | undefined;
+    /**
+     * Initial rows per `rows` widget key (a contributor list's current credits).
+     * @defaultValue `{}`
+     */
+    initialRows?: Readonly<Record<string, readonly unknown[]>> | undefined;
+    /**
+     * Render-time extra props per widget key (a picker's load-resolved `options`).
+     * @defaultValue `{}`
+     */
+    fieldProps?: Readonly<Record<string, Readonly<Record<string, unknown>>>> | undefined;
+    /**
+     * The spreadable `<form>` attributes for this store.
+     * @defaultValue the store's own `form.props`
+     */
+    enhance?: ((form: Store) => Record<string | symbol, unknown>) | undefined;
+    /**
+     * Text of the cancel link.
+     * @defaultValue `'Cancel'`
+     */
+    cancelLabel?: string | undefined;
+    /**
+     * Submit button text while the form is submitting.
+     * @defaultValue `'Saving…'`
+     */
+    pendingLabel?: string | undefined;
+    /**
+     * The empty option of a select entry.
+     * @defaultValue `'Choose…'`
+     */
+    selectPlaceholder?: string | undefined;
+    /**
+     * Read out after a required field’s label.
+     * @defaultValue `'(required)'` (from `FormField`)
+     */
+    requiredLabel?: string | undefined;
+}
+/** Renders an `@thomasfosterau/effect-forms-svelte` `defineEntityForm` definition through this library’s field primitives. */
+declare const EntityForm: import("svelte").Component<Props, {}, "">;
+type EntityForm = ReturnType<typeof EntityForm>;
+export default EntityForm;

package/dist/forms/FormActions.svelte

@@ -0,0 +1,29 @@
+<!-- @component
+The submit and cancel row that closes a form.
+-->
+<!--
+  FormActions — the submit / cancel row that closes a form.
+
+  ARIA contract: the submit control is a real `type="submit"` button, so
+  Enter in any field still submits the form. While `pending` it is disabled
+  AND `aria-busy="true"` (disabled alone says "you may not"; busy says "it is
+  already happening") and its label swaps to `pendingLabel` — the button
+  keeps a name throughout, which a spinner-only state would not.
+
+  Cancel is a LINK, not a button: it navigates away, and a reader should be
+  able to see where to before they commit to it.
+-->
+<script lang="ts">import Button from "../ui/Button.svelte";
+import LinkButton from "../ui/LinkButton.svelte";
+let { submitLabel = "Save", pendingLabel = "Saving…", pending = false, disabled = false, tone = "primary", cancelHref, cancelLabel = "Cancel", children, class: className, ...rest } = $props();
+</script>
+
+<div {...rest} class={['flex flex-wrap items-center gap-3 pt-2', className]}>
+  <Button type="submit" {tone} loading={pending} {disabled}>
+    {pending ? pendingLabel : submitLabel}
+  </Button>
+  {#if cancelHref !== undefined}
+    <LinkButton href={cancelHref} variant="ghost" disabled={pending}>{cancelLabel}</LinkButton>
+  {/if}
+  {@render children?.()}
+</div>

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

@@ -0,0 +1,37 @@
+import type { Snippet } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
+import type { Tone } from '../ui/tones.ts';
+interface Props extends Omit<HTMLAttributes<HTMLDivElement>, 'children'> {
+    /**
+     * Idle label of the submit button.
+     * @defaultValue `'Save'`
+     */
+    submitLabel?: string | undefined;
+    /**
+     * Label while the form is in flight.
+     * @defaultValue `'Saving…'`
+     */
+    pendingLabel?: string | undefined;
+    /** The form is being submitted. */
+    pending?: boolean | undefined;
+    /** Extra disable condition — a required picker still empty, say. */
+    disabled?: boolean | undefined;
+    /**
+     * Colour of the submit button.
+     * @defaultValue `'primary'`
+     */
+    tone?: Tone | undefined;
+    /** Where cancel goes. Omit for a form with no cancel affordance. */
+    cancelHref?: string | undefined;
+    /**
+     * Text of the cancel control.
+     * @defaultValue `'Cancel'`
+     */
+    cancelLabel?: string | undefined;
+    /** Extra controls, rendered after cancel. */
+    children?: Snippet<[]> | undefined;
+}
+/** The submit and cancel row that closes a form. */
+declare const FormActions: import("svelte").Component<Props, {}, "">;
+type FormActions = ReturnType<typeof FormActions>;
+export default FormActions;

package/dist/forms/FormErrors.svelte

@@ -0,0 +1,21 @@
+<!-- @component
+The whole-form messages that belong to the submission rather than to any one field.
+-->
+<!--
+  FormErrors — the whole-form messages: the ones that belong to the
+  submission rather than to any one field ("That name is already taken",
+  "Your session expired").
+
+  ARIA contract: one `Alert` per message, each `live="assertive"`. Assertive
+  is right here and would be wrong for page furniture: these appear in
+  response to something the reader just did, and the next thing they will do
+  is try again. Nothing is rendered while the list is empty, so the alert is
+  inserted — and therefore announced — exactly when there is something to say.
+-->
+<script lang="ts">import Alert from "../ui/Alert.svelte";
+let { messages, tone = "error", class: className } = $props();
+</script>
+
+{#each messages ?? [] as message, index (index)}
+  <Alert {tone} live="assertive" class={className}>{message}</Alert>
+{/each}

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

@@ -0,0 +1,16 @@
+import type { StatusTone } from '../ui/tones.ts';
+interface Props {
+    /** Whole-form messages. */
+    messages?: readonly string[] | undefined;
+    /**
+     * Colour of the alert.
+     * @defaultValue `'error'`
+     */
+    tone?: StatusTone | undefined;
+    /** Extra classes, merged last. */
+    class?: string | undefined;
+}
+/** The whole-form messages that belong to the submission rather than to any one field. */
+declare const FormErrors: import("svelte").Component<Props, {}, "">;
+type FormErrors = ReturnType<typeof FormErrors>;
+export default FormErrors;

package/dist/forms/HiddenField.svelte

@@ -0,0 +1,22 @@
+<!-- @component
+A fixed value posted with the form and never edited.
+-->
+<!--
+  HiddenField — a fixed value posted with the form and never edited: the
+  parent id a create form hangs its row off, a command discriminator, a
+  redirect target.
+
+  It is a component rather than a bare `<input type="hidden">` so that a form
+  described declaratively (a list of fields) can include one without dropping
+  out of that description, and so the value passes through one place that
+  stringifies it.
+
+  ARIA contract: none, deliberately — a hidden input is not in the
+  accessibility tree, and anything a reader needs to KNOW about does not
+  belong in one.
+-->
+<script lang="ts">let { name, value, ...rest } = $props();
+export {};
+</script>
+
+<input {...rest} type="hidden" {name} value={String(value)} />

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

@@ -0,0 +1,11 @@
+import type { HTMLInputAttributes } from 'svelte/elements';
+interface Props extends Omit<HTMLInputAttributes, 'type' | 'value'> {
+    /** The posted field name. */
+    name: string;
+    /** The posted value. */
+    value: string | number;
+}
+/** A fixed value posted with the form and never edited. */
+declare const HiddenField: import("svelte").Component<Props, {}, "">;
+type HiddenField = ReturnType<typeof HiddenField>;
+export default HiddenField;

package/dist/forms/SearchForm.svelte

@@ -0,0 +1,43 @@
+<!-- @component
+The site search box: a `<search>` landmark around a GET form that works without JavaScript.
+-->
+<!--
+  SearchForm — the site search box: a `<search>` landmark around a GET form
+  that works with no JavaScript at all.
+
+  Method GET on purpose. A search is a request for a REPRESENTATION, so its
+  result should be a URL people can bookmark, share and go back to; a POST
+  would make the results page un-linkable and re-submit on refresh.
+
+  ARIA contract: `<search>` is the landmark (so "go to search" reaches it
+  without an `aria-label` per instance), the visible label is visually hidden
+  but real — `for`/`id`, not a `placeholder`, which disappears the moment
+  someone types and is not a name at all — and the submit button carries its
+  own text rather than an icon alone.
+
+  `action` resolves through the components context, so an app with a base path
+  or a locale prefix gets the right URL without this file knowing about either.
+-->
+<script lang="ts">import { getComponentsContext } from "../context.svelte.js";
+import Button from "../ui/Button.svelte";
+let { action, name = "q", value = $bindable(""), label = "Search", submitLabel = "Search", placeholder, required = true, class: className, ...rest } = $props();
+const context = getComponentsContext();
+const resolved = $derived(context.href(action));
+const uid = $props.id();
+</script>
+
+<search class={['block', className]}>
+  <form {...rest} action={resolved} method="get" class="join w-full">
+    <label class="sr-only" for={uid}>{label}</label>
+    <input
+      id={uid}
+      class="input join-item w-full"
+      type="search"
+      {name}
+      {placeholder}
+      {required}
+      bind:value
+    />
+    <Button type="submit" tone="primary" class="join-item">{submitLabel}</Button>
+  </form>
+</search>