@thomasfosterau/components 0.0.0-stage → 0.1.0

package/dist/fields/Combobox.svelte

@@ -0,0 +1,222 @@
+<!-- @component
+A single-select typeahead over a static list or an asynchronous search, on bits-ui’s `Combobox`.
+-->
+<!--
+  Combobox — a single-select typeahead over a static list OR an asynchronous
+  search, on bits-ui's `Combobox`.
+
+  The previous generation of this component hand-rolled the APG combobox
+  pattern: an `<input role="combobox">`, a `<ul role="listbox">`, an
+  `activeIndex`, wrap-around arrow keys, Home/End, and a blur timeout to let a
+  pointerdown on an option land before the list closed. All of that is
+  bits-ui's here. What is NOT bits-ui's, and is what this file is actually
+  about, is the SEARCH LIFECYCLE.
+
+  The search lifecycle, in the order the problems bite:
+
+    debounce         a keystroke does not start a request; `debounceMs` of
+                     quiet does.
+    latest-wins      each request gets an `AbortController`, and starting a
+                     new one aborts the last. A superseded request is
+                     cancelled rather than merely ignored, so a slow first
+                     response cannot overwrite a fast second one.
+    stale-while-     the previous results stay on screen while the next
+      revalidate     request is in flight, with `pending` true. Clearing the
+                     list on every keystroke makes the dropdown strobe and
+                     costs the reader the thing they were about to pick.
+
+  ARIA contract: bits-ui gives the input `role="combobox"`,
+  `aria-autocomplete="list"`, `aria-expanded` and `aria-activedescendant`
+  pointing at the highlighted option; the panel is `role="listbox"` and each
+  row `role="option"` with `aria-selected`. The visible `<label>` names the
+  input through `for`/`id`; `errorMessage` is a `role="alert"` paragraph the
+  input is NOT described by, because a search failure is about the list rather
+  than about the value.
+
+  One behaviour is preserved from the hand-rolled version on purpose:
+  **Enter with nothing highlighted must not prevent a wrapping `<form>` from
+  submitting.** A search box that sits in a plain GET form has to keep working
+  when the list is empty or the reader never opened it. bits-ui's input
+  `preventDefault`s Enter whenever the panel is open, so the handler below
+  closes the panel first when nothing is highlighted: with the panel closed,
+  bits-ui treats Enter as an interaction key and returns without touching the
+  event, and the form submits. `highlighted` is tracked through the items'
+  own `onHighlight` / `onUnhighlight` callbacks, which is the only place
+  bits-ui surfaces it.
+
+  Note what that means in practice: bits-ui puts the cursor on the first
+  candidate as soon as typing produces one, so with matches on screen Enter
+  COMMITS. The fall-through happens where it matters — a query that matched
+  nothing, or a panel the reader never opened — which is exactly the case a
+  no-JS search form depends on.
+-->
+<script lang="ts" generics="T">import { Combobox } from "bits-ui";
+import { inputSize } from "./field-types.js";
+let { value = $bindable(), items, onSearch, debounceMs = 150, getId, getLabel, getBadge, label, placeholder, name, emptyLabel = "No matches", pendingLabel = "Searching…", errorMessage, id: idProp, describedBy = "", invalid = false, required = false, disabled = false, size = "md", class: className, item, footer, empty } = $props();
+const uid = $props.id();
+const inputId = $derived(idProp ?? uid);
+let query = $state("");
+let open = $state(false);
+let results = $state([]);
+let pending = $state(false);
+let searchError = $state();
+/** The id of the row bits-ui currently has under the cursor, if any. */
+let highlighted = $state();
+let timer;
+let inFlight;
+/** Static mode filters locally; async mode shows whatever last settled. */
+const visible = $derived.by(() => {
+	if (onSearch !== undefined) return results;
+	const all = items ?? [];
+	const needle = query.trim().toLowerCase();
+	if (needle === "") return all;
+	return all.filter((entry) => getLabel(entry).toLowerCase().includes(needle));
+});
+const selectedLabel = $derived.by(() => {
+	if (value === undefined || items === undefined) return undefined;
+	const match = items.find((entry) => getId(entry) === value);
+	return match === undefined ? undefined : getLabel(match);
+});
+const visibleError = $derived(errorMessage ?? searchError);
+const search = (text) => {
+	if (onSearch === undefined) return;
+	inFlight?.abort();
+	const own = new AbortController();
+	inFlight = own;
+	pending = true;
+	searchError = undefined;
+	void onSearch(text, own.signal).then((next) => {
+		// A superseded request must not write: `inFlight` is the identity
+		// check, `signal.aborted` catches the caller aborting its own work.
+		if (own.signal.aborted || inFlight !== own) return;
+		results = next;
+		pending = false;
+	}).catch((error) => {
+		if (own.signal.aborted || inFlight !== own) return;
+		pending = false;
+		searchError = error instanceof Error ? error.message : String(error);
+	});
+};
+const schedule = (text) => {
+	if (timer !== undefined) clearTimeout(timer);
+	timer = setTimeout(() => {
+		timer = undefined;
+		search(text);
+	}, debounceMs);
+};
+$effect(() => () => {
+	if (timer !== undefined) clearTimeout(timer);
+	inFlight?.abort();
+});
+const typed = (event) => {
+	query = event.currentTarget.value;
+	if (onSearch === undefined) {
+		open = true;
+		return;
+	}
+	if (query.trim() === "") {
+		if (timer !== undefined) clearTimeout(timer);
+		inFlight?.abort();
+		inFlight = undefined;
+		pending = false;
+		results = [];
+		open = false;
+		return;
+	}
+	open = true;
+	schedule(query);
+};
+const keydown = (event) => {
+	if (event.key !== "Enter" || highlighted !== undefined) return;
+	// Nothing to commit. Close first so bits-ui's own Enter branch takes the
+	// closed path, which returns without `preventDefault` — that is what lets
+	// a wrapping form submit.
+	open = false;
+};
+</script>
+
+<div class={['fieldset w-full', className]}>
+  <label class="label" for={inputId}>{label}</label>
+
+  <Combobox.Root
+    type="single"
+    bind:open
+    value={value ?? ''}
+    onValueChange={(next) => {
+      value = next === '' ? undefined : next;
+    }}
+    {disabled}
+    {required}
+  >
+    <Combobox.Input
+      id={inputId}
+      {...selectedLabel === undefined ? {} : { defaultValue: selectedLabel }}
+      {placeholder}
+      autocomplete="off"
+      aria-describedby={describedBy === '' ? undefined : describedBy}
+      aria-invalid={invalid ? 'true' : undefined}
+      oninput={typed}
+      onkeydown={keydown}
+      class={['input w-full', inputSize[size], invalid && 'input-error']}
+    />
+
+    <Combobox.Portal>
+      <Combobox.Content
+        sideOffset={4}
+        class="menu bg-base-100 rounded-box border-base-300 z-50 max-h-72 min-w-64 overflow-auto border p-2 shadow-md"
+      >
+        <Combobox.Viewport>
+          {#each visible as entry (getId(entry))}
+            {@const entryId = getId(entry)}
+            {@const badge = getBadge?.(entry)}
+            <Combobox.Item
+              value={entryId}
+              label={getLabel(entry)}
+              onHighlight={() => (highlighted = entryId)}
+              onUnhighlight={() => {
+                if (highlighted === entryId) highlighted = undefined;
+              }}
+              class="rounded-field data-highlighted:bg-base-200 data-disabled:opacity-50 flex cursor-pointer items-center justify-between gap-3 px-3 py-2"
+            >
+              {#if item}
+                {@render item(entry)}
+              {:else}
+                <span>{getLabel(entry)}</span>
+                {#if badge !== undefined}
+                  <span class="badge badge-ghost badge-sm">{badge}</span>
+                {/if}
+              {/if}
+            </Combobox.Item>
+          {/each}
+
+          {#if visible.length === 0}
+            {#if pending}
+              <p class="fieldset-label px-3 py-2">{pendingLabel}</p>
+            {:else if empty}
+              {@render empty({ query })}
+            {:else}
+              <p class="fieldset-label px-3 py-2">{emptyLabel}</p>
+            {/if}
+          {/if}
+
+          {#if footer}
+            {@render footer({ query, pending })}
+          {/if}
+        </Combobox.Viewport>
+      </Combobox.Content>
+    </Combobox.Portal>
+  </Combobox.Root>
+
+  <!--
+    The posted value is the id, not the typed text: bits-ui's own hidden input
+    is not used, because `name` here means "post the selection" and nothing
+    else about the widget should depend on it.
+  -->
+  {#if name !== undefined}
+    <input type="hidden" {name} value={value ?? ''} />
+  {/if}
+
+  {#if visibleError !== undefined}
+    <p class="text-error pt-1 text-sm" role="alert">{visibleError}</p>
+  {/if}
+</div>

package/dist/fields/Combobox.svelte.d.ts

@@ -0,0 +1,98 @@
+import { Combobox } from 'bits-ui';
+import type { Snippet } from 'svelte';
+import { type FieldSize } from './field-types.ts';
+declare function $$render<T>(): {
+    props: {
+        /** The selected item's id. */
+        value?: string | undefined;
+        /** A static list, filtered here by label. Ignored when `onSearch` is set. */
+        items?: readonly T[] | undefined;
+        /**
+         * Fetch matches for a query. Debounced by `debounceMs`; `signal` aborts
+         * when a newer query supersedes this one, so pass it to `fetch`.
+         */
+        onSearch?: ((query: string, signal: AbortSignal) => Promise<readonly T[]>) | undefined;
+        /**
+         * Quiet period before a search starts, in milliseconds.
+         * @defaultValue `150`
+         */
+        debounceMs?: number | undefined;
+        /** The item's stable id — what `value` holds and what the hidden input posts. */
+        getId: (item: T) => string;
+        /** The item's human-readable text. */
+        getLabel: (item: T) => string;
+        /** Optional short chip on the right of a row. */
+        getBadge?: ((item: T) => string | undefined) | undefined;
+        /** Visible label; names the input. */
+        label: string;
+        /** Placeholder in the input. */
+        placeholder?: string | undefined;
+        /** Posted field name. Set it to render a hidden input carrying the id. */
+        name?: string | undefined;
+        /**
+         * Shown when a settled search returned nothing.
+         * @defaultValue `'No matches'`
+         */
+        emptyLabel?: string | undefined;
+        /**
+         * Shown while the first search for a query is in flight.
+         * @defaultValue `'Searching…'`
+         */
+        pendingLabel?: string | undefined;
+        /** A caller-owned failure, rendered as an alert under the input. */
+        errorMessage?: string | undefined;
+        /** `FieldControl`: the input's id. */
+        id?: string | undefined;
+        /**
+         * `FieldControl`: ids for `aria-describedby`.
+         * @defaultValue `''`
+         */
+        describedBy?: string | undefined;
+        /** `FieldControl`: the field is in error. */
+        invalid?: boolean | undefined;
+        /** `FieldControl`: the field must be filled. */
+        required?: boolean | undefined;
+        /** Disables the input. */
+        disabled?: boolean | undefined;
+        /**
+         * daisyUI size step.
+         * @defaultValue `'md'`
+         */
+        size?: FieldSize | undefined;
+        /** Extra classes, merged last. */
+        class?: string | undefined;
+        /** Replace a row's contents. */
+        item?: Snippet<[T]> | undefined;
+        /** Rendered after the rows — a "create this" row, a "see all" link. */
+        footer?: Snippet<[{
+            query: string;
+            pending: boolean;
+        }]> | undefined;
+        /** Replaces `emptyLabel` when a settled search returned nothing. */
+        empty?: Snippet<[{
+            query: string;
+        }]> | undefined;
+    };
+    exports: {};
+    bindings: "value";
+    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(): "value";
+    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']>;
+}
+/** A single-select typeahead over a static list or an asynchronous search, on bits-ui’s `Combobox`. */
+declare const Combobox: $$IsomorphicComponent;
+type Combobox<T> = InstanceType<typeof Combobox<T>>;
+export default Combobox;

package/dist/fields/DateInput.svelte

@@ -0,0 +1,31 @@
+<!-- @component
+A native `<input type="date">` in daisyUI `input` styling, with `FieldControl` wiring.
+-->
+<!--
+  DateInput — the native `<input type="date">` in daisyUI `input` styling.
+
+  `value` holds the ISO calendar date (`YYYY-MM-DD`) the control speaks
+  natively, which is also the shape a JSON API's date fields take, so no
+  conversion sits between the two.
+
+  Native on purpose, and the reason is worth stating: bits-ui's `DateField`
+  is a segmented control with its own locale handling and its own keyboard
+  contract, which is the right answer when a design needs a calendar popover
+  and the wrong one for a single date on a form — the platform control is
+  keyboard-complete, localises itself, and on a phone opens the system date
+  picker that people already know.
+-->
+<script lang="ts">import { inputSize } from "./field-types.js";
+let { value = $bindable(""), min, max, size = "md", invalid = false, describedBy = "", class: className, ...rest } = $props();
+</script>
+
+<input
+  {...rest}
+  type="date"
+  bind:value
+  {min}
+  {max}
+  aria-invalid={invalid ? 'true' : undefined}
+  aria-describedby={describedBy === '' ? undefined : describedBy}
+  class={['input w-full', inputSize[size], invalid && 'input-error', className]}
+/>

package/dist/fields/DateInput.svelte.d.ts

@@ -0,0 +1,29 @@
+import type { HTMLInputAttributes } from 'svelte/elements';
+import { type FieldSize } from './field-types.ts';
+interface Props extends Omit<HTMLInputAttributes, 'type' | 'value' | 'size' | 'min' | 'max'> {
+    /**
+     * ISO calendar date, `YYYY-MM-DD`; empty when unset.
+     * @defaultValue `''`
+     */
+    value?: string | undefined;
+    /** Earliest selectable date, ISO. */
+    min?: string | undefined;
+    /** Latest selectable date, ISO. */
+    max?: string | undefined;
+    /**
+     * daisyUI size step.
+     * @defaultValue `'md'`
+     */
+    size?: FieldSize | undefined;
+    /** `FieldControl`: the field is in error — sets `aria-invalid` and the error style. */
+    invalid?: boolean | undefined;
+    /**
+     * `FieldControl`: space-separated ids for `aria-describedby`.
+     * @defaultValue `''`
+     */
+    describedBy?: string | undefined;
+}
+/** A native `<input type="date">` in daisyUI `input` styling, with `FieldControl` wiring. */
+declare const DateInput: import("svelte").Component<Props, {}, "value">;
+type DateInput = ReturnType<typeof DateInput>;
+export default DateInput;

package/dist/fields/FieldErrors.svelte

@@ -0,0 +1,30 @@
+<!-- @component
+The validation messages under one control: one `<p>` per message inside a single container.
+-->
+<!--
+  FieldErrors — the validation messages under one control: one `<p>` per
+  message inside a single container.
+
+  ARIA contract: the container is the live region (`role="alert"`), not each
+  paragraph — a field that fails three rules should interrupt the reader once
+  and then read all three, which is what one region holding three paragraphs
+  does and what three regions do not. It carries the `id` a control points
+  `aria-describedby` at, so the messages are also read on demand when focus
+  reaches the control.
+
+  Nothing is rendered while `errors` is empty. That is deliberate: a live
+  region has to be IN the document before its content changes for the change
+  to be announced, and inserting a populated region announces it, so the
+  cheapest correct thing is to mount it only when there is something to say.
+-->
+<script lang="ts">let { errors, id, class: className, ...rest } = $props();
+export {};
+</script>
+
+{#if errors.length > 0}
+  <div {...rest} {id} role="alert" class={className}>
+    {#each errors as message, index (index)}
+      <p class="fieldset-label text-error">{message}</p>
+    {/each}
+  </div>
+{/if}

package/dist/fields/FieldErrors.svelte.d.ts

@@ -0,0 +1,11 @@
+import type { HTMLAttributes } from 'svelte/elements';
+interface Props extends HTMLAttributes<HTMLDivElement> {
+    /** Messages to render, one paragraph each. */
+    errors: readonly string[];
+    /** The id a control's `aria-describedby` points at. */
+    id?: string | undefined;
+}
+/** The validation messages under one control: one `<p>` per message inside a single container. */
+declare const FieldErrors: import("svelte").Component<Props, {}, "">;
+type FieldErrors = ReturnType<typeof FieldErrors>;
+export default FieldErrors;

package/dist/fields/Fieldset.svelte

@@ -0,0 +1,48 @@
+<!-- @component
+The `FormField` frame — legend, hint, errors — for a group of controls rather than one.
+-->
+<!--
+  Fieldset — the same frame as `FormField`, for a GROUP of controls rather
+  than one.
+
+  A group of related checkboxes or radios is a `<fieldset>` with a `<legend>`,
+  not a label pointing at one input: there is no single control for a `for`
+  attribute to name, and the legend is what assistive technology repeats as it
+  moves between the members. So the hint and the errors hang off the
+  `<fieldset>` itself through `aria-describedby`. There is no `aria-invalid`:
+  the implicit `group` role does not support it, so the invalid state is a
+  `data-invalid` hook for styling and the error region is what announces it.
+
+  `CheckboxGroup` is built on this. `RadioGroup` is not — bits-ui's radio
+  group renders its own `role="radiogroup"` element, and a role inside a
+  `<fieldset>` would be named by nothing, so it names itself from a heading it
+  renders instead. That is the one place the two frames diverge.
+-->
+<script lang="ts">import FieldErrors from "./FieldErrors.svelte";
+let { legend, hint, errors = [], required = false, requiredLabel = "(required)", children, class: className, ...rest } = $props();
+const uid = $props.id();
+const hintId = `${uid}-hint`;
+const errorId = `${uid}-error`;
+const invalid = $derived(errors.length > 0);
+const describedBy = $derived([hint === undefined ? "" : hintId, invalid ? errorId : ""].filter((part) => part !== "").join(" "));
+</script>
+
+<fieldset
+  {...rest}
+  aria-describedby={describedBy === '' ? undefined : describedBy}
+  data-invalid={invalid ? '' : undefined}
+  class={['fieldset', className]}
+>
+  <legend class="fieldset-legend">
+    {legend}
+    {#if required}
+      <span class="text-error" aria-hidden="true">*</span>
+      <span class="sr-only">{requiredLabel}</span>
+    {/if}
+  </legend>
+  {@render children()}
+  {#if hint !== undefined}
+    <p class="fieldset-label" id={hintId}>{hint}</p>
+  {/if}
+  <FieldErrors {errors} id={errorId} />
+</fieldset>

package/dist/fields/Fieldset.svelte.d.ts

@@ -0,0 +1,26 @@
+import type { Snippet } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
+interface Props extends Omit<HTMLAttributes<HTMLFieldSetElement>, 'children'> {
+    /** The group's `<legend>`; names every control inside it. */
+    legend: string;
+    /** Guidance rendered under the legend. */
+    hint?: string | undefined;
+    /**
+     * Validation messages; any at all marks the group invalid.
+     * @defaultValue `[]`
+     */
+    errors?: readonly string[] | undefined;
+    /** Marks the group required and reads `requiredLabel` after the legend. */
+    required?: boolean | undefined;
+    /**
+     * Read out after the legend when `required`.
+     * @defaultValue `'(required)'`
+     */
+    requiredLabel?: string | undefined;
+    /** The grouped controls. */
+    children: Snippet<[]>;
+}
+/** The `FormField` frame — legend, hint, errors — for a group of controls rather than one. */
+declare const Fieldset: import("svelte").Component<Props, {}, "">;
+type Fieldset = ReturnType<typeof Fieldset>;
+export default Fieldset;

package/dist/fields/FileInput.svelte

@@ -0,0 +1,67 @@
+<!-- @component
+A native file input in daisyUI `file-input` styling, with the chosen `File` bindable and a client-side size cap.
+-->
+<!--
+  FileInput — a native `<input type="file">` in daisyUI `file-input` styling,
+  with the chosen `File` exposed as a bindable prop and a client-side size cap.
+
+  It does NOT upload anything. The transfer belongs to the caller — a form
+  POST, a direct-to-storage PUT, a resumable client — and a component every
+  page imports has no business carrying one. `ImageInput` and `VideoInput`
+  build on this: the selection and the messaging are shared, the transfer is
+  not.
+
+  `maxBytes` is enforced here as well as on the server because a file rejected
+  after the transfer is a uniquely expensive way to say no. An over-size file
+  is cleared from the control rather than left sitting in it, so what the
+  control shows and what `file` holds cannot disagree.
+
+  ARIA contract: a native file input. `aria-invalid` is set when the field is
+  invalid OR the chosen file was too large, and the too-large message is an
+  `alert` region the input's `aria-describedby` also points at, so the reason
+  is announced and is available again on focus.
+-->
+<script lang="ts">import FieldErrors from "./FieldErrors.svelte";
+import { fileInputSize } from "./field-types.js";
+let { file = $bindable(), accept, maxBytes, tooLargeMessage = "That file is too large.", onSelect, size = "md", invalid = false, describedBy = "", class: className, ...rest } = $props();
+const uid = $props.id();
+const tooLargeId = `${uid}-too-large`;
+let tooLarge = $state(false);
+const described = $derived([describedBy, tooLarge ? tooLargeId : ""].filter((part) => part !== "").join(" "));
+const choose = (control) => {
+	const chosen = control.files?.[0];
+	tooLarge = false;
+	if (chosen === undefined) {
+		file = undefined;
+		onSelect?.(undefined);
+		return;
+	}
+	if (maxBytes !== undefined && chosen.size > maxBytes) {
+		tooLarge = true;
+		// Clear the control too: leaving the name of a file that was refused
+		// showing in the field is how someone submits and wonders what happened.
+		control.value = "";
+		file = undefined;
+		onSelect?.(undefined);
+		return;
+	}
+	file = chosen;
+	onSelect?.(chosen);
+};
+</script>
+
+<input
+  {...rest}
+  type="file"
+  {accept}
+  onchange={(event) => choose(event.currentTarget)}
+  aria-invalid={invalid || tooLarge ? 'true' : undefined}
+  aria-describedby={described === '' ? undefined : described}
+  class={[
+    'file-input w-full',
+    fileInputSize[size],
+    (invalid || tooLarge) && 'file-input-error',
+    className,
+  ]}
+/>
+<FieldErrors errors={tooLarge ? [tooLargeMessage] : []} id={tooLargeId} />

package/dist/fields/FileInput.svelte.d.ts

@@ -0,0 +1,33 @@
+import type { HTMLInputAttributes } from 'svelte/elements';
+import { type FieldSize } from './field-types.ts';
+interface Props extends Omit<HTMLInputAttributes, 'type' | 'value' | 'files' | 'size'> {
+    /** The chosen file; `undefined` when the control is empty. */
+    file?: File | undefined;
+    /** `accept` attribute value. */
+    accept?: string | undefined;
+    /** Largest file to accept, in bytes. Omitted, there is no cap. */
+    maxBytes?: number | undefined;
+    /**
+     * Shown when the chosen file exceeds `maxBytes`.
+     * @defaultValue `'That file is too large.'`
+     */
+    tooLargeMessage?: string | undefined;
+    /** Called with the accepted file, or `undefined` when the choice cleared it. */
+    onSelect?: ((file: File | undefined) => void) | undefined;
+    /**
+     * daisyUI size step.
+     * @defaultValue `'md'`
+     */
+    size?: FieldSize | undefined;
+    /** `FieldControl`: the field is in error — sets `aria-invalid` and the error style. */
+    invalid?: boolean | undefined;
+    /**
+     * `FieldControl`: space-separated ids for `aria-describedby`.
+     * @defaultValue `''`
+     */
+    describedBy?: string | undefined;
+}
+/** A native file input in daisyUI `file-input` styling, with the chosen `File` bindable and a client-side size cap. */
+declare const FileInput: import("svelte").Component<Props, {}, "file">;
+type FileInput = ReturnType<typeof FileInput>;
+export default FileInput;

package/dist/fields/FormField.svelte

@@ -0,0 +1,54 @@
+<!-- @component
+The label, hint and errors frame around one control, handing it the `FieldControl` wiring.
+-->
+<!--
+  FormField — the label + hint + errors frame around one control.
+
+  The control is a snippet that receives a `FieldControl` (`id`,
+  `describedBy`, `invalid`, `required`) to spread onto the primitive, so the
+  label's `for`, the control's `aria-describedby` and `aria-invalid`, and the
+  error region's `role="alert"` all stay wired together from a single `id`.
+  Neither side has to know the other's markup, which is what lets a caller
+  drop any of the field primitives — or their own `<input>` — into the slot.
+
+  ARIA contract: `<label for>` names the control (so clicking the text focuses
+  it); `describedBy` lists the hint's id then the error region's id, in that
+  reading order, and is empty when there is neither; `invalid` is true exactly
+  when there is at least one error. The required marker is a `*` that is
+  `aria-hidden` beside a visually-hidden `requiredLabel`, both inside the
+  `<label>`, so the accessible name reads "Scientific name (required)" rather
+  than "Scientific name star".
+
+  `errors` is a LIST. A field that fails several rules says so; collapsing
+  them to the first message is a decision the call site should make, not one
+  this frame makes for it.
+-->
+<script lang="ts">import FieldErrors from "./FieldErrors.svelte";
+let { id: idProp, label, hint, errors = [], required = false, requiredLabel = "(required)", children, class: className, ...rest } = $props();
+const uid = $props.id();
+const id = $derived(idProp ?? uid);
+const hintId = $derived(`${id}-hint`);
+const errorId = $derived(`${id}-error`);
+const invalid = $derived(errors.length > 0);
+const control = $derived({
+	id,
+	describedBy: [hint === undefined ? "" : hintId, invalid ? errorId : ""].filter((part) => part !== "").join(" "),
+	invalid,
+	required
+});
+</script>
+
+<div {...rest} class={['fieldset', className]}>
+  <label class="label" for={id}>
+    <span>{label}</span>
+    {#if required}
+      <span class="text-error" aria-hidden="true">*</span>
+      <span class="sr-only">{requiredLabel}</span>
+    {/if}
+  </label>
+  {@render children(control)}
+  {#if hint !== undefined}
+    <p class="fieldset-label" id={hintId}>{hint}</p>
+  {/if}
+  <FieldErrors {errors} id={errorId} />
+</div>