@thomasfosterau/components 0.0.0 → 0.2.0

package/dist/data/DataGrid.svelte

@@ -0,0 +1,150 @@
+<!-- @component
+A `Table` with client-side sorting, filtering across every column and paging, for a list that is already entirely in hand.
+-->
+<!--
+  DataGrid — the three controls a reader wants over a list that is already
+  entirely in hand: sort a column, filter across every column, page through
+  the result.
+
+  It draws no table of its own. The rows go through `Table` and the pager
+  through `Pagination`, so the cell markup, the empty state, the sort control
+  and the disabled-arm rule all have exactly one implementation, and this file
+  is the decisions rather than the markup.
+
+  **Client-side, and that is the constraint.** Every derivation below runs
+  over the whole `rows` array on every keystroke, so this is for a bounded set
+  the page already holds — a vocabulary, an account's devices, a taxon's
+  synonyms. A collection the API pages belongs on `Table` + `PaginationFooter`,
+  where the server does the work; pointing this at one would silently sort and
+  filter the current page only, which reads as data loss rather than as a
+  limitation.
+
+  ARIA contract: the `Table`'s and the `Pagination`'s. The filter is a
+  `<input type="search">` with a real label (visually hidden, because the
+  control sits in a toolbar where a visible label would be the only one), and
+  the rows-per-page `<select>` is named by `rowsPerPageLabel`.
+-->
+<script lang="ts" generics="T">import { getComponentsContext } from "../context.svelte.js";
+import Pagination from "./Pagination.svelte";
+import Table from "./Table.svelte";
+let { rows, columns, rowKey, filterable = false, paginated = true, pageSize = 10, pageSizeOptions = [
+	10,
+	25,
+	50,
+	100
+], caption, captionHidden, size, zebra, pinRows, sort = $bindable(undefined), onSelect, emptyMessage, emptyState, filterLabel = "Search", filterPlaceholder = "Search…", rowsPerPageLabel = "Rows per page", showingLabel = (start, end, total) => `Showing ${start} to ${end} of ${total}`, pageOfLabel = (page, pages) => `Page ${page} of ${pages}`, previousLabel = "Previous", nextLabel = "Next", paginationLabel = "Pagination", sortLabel, locales = getComponentsContext().locale(), class: className, ...rest } = $props();
+let filter = $state("");
+// 0 is "the reader has not chosen": the `pageSize` prop stays authoritative
+// until they pick from the menu, so a page that changes the prop is honoured
+// rather than overridden by state seeded once at mount.
+let chosenSize = $state(0);
+let page = $state(0);
+const limit = $derived(chosenSize === 0 ? pageSize : chosenSize);
+const filtered = $derived.by(() => {
+	const needle = filter.trim().toLowerCase();
+	if (needle === "") return rows;
+	// The filter searches the column's VALUE, not its rendered cell: a cell
+	// may be a badge or a link, and a reader typing what they can see is
+	// typing the value either way.
+	return rows.filter((row) => columns.some((column) => String(column.value(row)).toLowerCase().includes(needle)));
+});
+const sorted = $derived.by(() => {
+	const active = sort;
+	if (active === undefined) return filtered;
+	const column = columns.find((candidate) => candidate.key === active.key);
+	if (column === undefined) return filtered;
+	const direction = active.direction === "asc" ? 1 : -1;
+	// `localeCompare` in the active locale, so a Swedish reader gets Swedish
+	// collation rather than code-point order; numbers compare numerically,
+	// because "10" sorts before "9" as a string and that is always wrong.
+	return filtered.toSorted((left, right) => {
+		const a = column.value(left);
+		const b = column.value(right);
+		if (typeof a === "number" && typeof b === "number") return (a - b) * direction;
+		return String(a).localeCompare(String(b), locales) * direction;
+	});
+});
+const total = $derived(sorted.length);
+const pageCount = $derived(paginated ? Math.max(1, Math.ceil(total / limit)) : 1);
+// A filter that shrinks the result out from under the current page would
+// otherwise leave the reader looking at an empty body with rows they cannot
+// reach. Clamping in a derivation rather than in the filter's handler keeps
+// it true however the page count changed — including a `rows` prop that
+// shrank without anyone typing.
+const current = $derived(Math.min(page, pageCount - 1));
+const visible = $derived(paginated ? sorted.slice(current * limit, current * limit + limit) : sorted);
+const from = $derived(total === 0 ? 0 : current * limit + 1);
+const to = $derived(Math.min((current + 1) * limit, total));
+</script>
+
+<div {...rest} class={['space-y-3', className]}>
+  {#if filterable}
+    <label class="input input-sm w-full max-w-xs">
+      <span class="sr-only">{filterLabel}</span>
+      <input
+        type="search"
+        bind:value={filter}
+        oninput={() => {
+          page = 0;
+        }}
+        placeholder={filterPlaceholder}
+        aria-label={filterLabel}
+      />
+    </label>
+  {/if}
+
+  <Table
+    rows={visible}
+    {columns}
+    {rowKey}
+    {caption}
+    {captionHidden}
+    {size}
+    {zebra}
+    {pinRows}
+    {onSelect}
+    {emptyMessage}
+    {emptyState}
+    {sortLabel}
+    bind:sort
+    onSort={() => {
+      // A new sort re-orders the whole result, so the reader's place in the
+      // old order means nothing; page 1 is the only honest answer.
+      page = 0;
+    }}
+  />
+
+  {#if paginated && total > 0}
+    <div class="flex flex-wrap items-center justify-between gap-3">
+      <div class="flex items-center gap-2">
+        <p class="text-base-content/70 text-sm tabular-nums">{showingLabel(from, to, total)}</p>
+        <select
+          class="select select-sm w-auto"
+          aria-label={rowsPerPageLabel}
+          value={limit}
+          onchange={(event) => {
+            chosenSize = Number(event.currentTarget.value);
+            page = 0;
+          }}
+        >
+          {#each pageSizeOptions as option (option)}
+            <option value={option}>{option}</option>
+          {/each}
+        </select>
+      </div>
+      <Pagination
+        offset={current * limit}
+        {limit}
+        {total}
+        variant="prevNext"
+        label={paginationLabel}
+        {previousLabel}
+        {nextLabel}
+        statusLabel={pageOfLabel}
+        onPage={(offset) => {
+          page = Math.floor(offset / limit);
+        }}
+      />
+    </div>
+  {/if}
+</div>

package/dist/data/DataGrid.svelte.d.ts

@@ -0,0 +1,118 @@
+import type { Snippet } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
+import type { Size } from '../ui/tones.ts';
+import type { SortState, TableColumn } from './table-types.ts';
+declare function $$render<T>(): {
+    props: Omit<HTMLAttributes<HTMLDivElement>, "children"> & {
+        /** Every row; sorting, filtering and paging happen here. */
+        rows: readonly T[];
+        /** Column definitions: header, cell renderer, sort key. */
+        columns: readonly TableColumn<T>[];
+        /** Stable identity per row — the `{#each}` key. */
+        rowKey: (row: T) => string;
+        /** Offer the filter box. */
+        filterable?: boolean | undefined;
+        /**
+         * Offer the pager; every row renders when false.
+         * @defaultValue `true`
+         */
+        paginated?: boolean | undefined;
+        /**
+         * Rows per page until the reader picks another size.
+         * @defaultValue `10`
+         */
+        pageSize?: number | undefined;
+        /**
+         * The choices offered in the rows-per-page select.
+         * @defaultValue `[10, 25, 50, 100]`
+         */
+        pageSizeOptions?: readonly number[] | undefined;
+        /** The table's accessible name, rendered as its `<caption>`. */
+        caption?: string | undefined;
+        /** Keep the caption for assistive technology only. */
+        captionHidden?: boolean | undefined;
+        /** daisyUI size step. */
+        size?: Size | undefined;
+        /** Stripe alternate rows. */
+        zebra?: boolean | undefined;
+        /** Stick the header row while the body scrolls; see `Table`. */
+        pinRows?: boolean | undefined;
+        /** Which column starts sorted. Bindable; `undefined` is the caller's order. */
+        sort?: SortState | undefined;
+        /** Makes every row activatable by pointer and keyboard; see `Table`. */
+        onSelect?: ((row: T) => void) | undefined;
+        /** The line shown when no row matches. */
+        emptyMessage?: string | undefined;
+        /** Richer empty state, in place of `emptyMessage`. */
+        emptyState?: Snippet<[]> | undefined;
+        /**
+         * Accessible name of the filter box.
+         * @defaultValue `'Search'`
+         */
+        filterLabel?: string | undefined;
+        /**
+         * Placeholder in the filter box.
+         * @defaultValue `'Search…'`
+         */
+        filterPlaceholder?: string | undefined;
+        /**
+         * Label of the rows-per-page select.
+         * @defaultValue `'Rows per page'`
+         */
+        rowsPerPageLabel?: string | undefined;
+        /**
+         * The range line under the table.
+         * @defaultValue `"Showing <start> to <end> of <total>"`
+         */
+        showingLabel?: ((start: number, end: number, total: number) => string) | undefined;
+        /**
+         * The page status between the pager arms.
+         * @defaultValue `"Page <page> of <pages>"`
+         */
+        pageOfLabel?: ((page: number, pages: number) => string) | undefined;
+        /**
+         * Text of the previous-page control.
+         * @defaultValue `'Previous'`
+         */
+        previousLabel?: string | undefined;
+        /**
+         * Text of the next-page control.
+         * @defaultValue `'Next'`
+         */
+        nextLabel?: string | undefined;
+        /**
+         * Accessible name of the pager landmark.
+         * @defaultValue `'Pagination'`
+         */
+        paginationLabel?: string | undefined;
+        /** How a sortable column’s button is named; see `Table`. */
+        sortLabel?: ((column: TableColumn<T>) => string) | undefined;
+        /**
+         * Locale(s) for `Intl` formatting.
+         * @defaultValue the components context's `locale()`
+         */
+        locales?: string | readonly string[] | undefined;
+    };
+    exports: {};
+    bindings: "sort";
+    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(): "sort";
+    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 `Table` with client-side sorting, filtering across every column and paging, for a list that is already entirely in hand. */
+declare const DataGrid: $$IsomorphicComponent;
+type DataGrid<T> = InstanceType<typeof DataGrid<T>>;
+export default DataGrid;

package/dist/data/DescriptionList.svelte

@@ -0,0 +1,53 @@
+<!-- @component
+Label/value pairs as a `grid`, a bordered `card`, `divided` rows, `inline` pairs, or `bare` pairs in a layout the caller supplies.
+-->
+<!--
+  DescriptionList — label / value pairs, in the four shapes a detail page
+  wants them: a two-column `grid`, a bordered `card` with the labels in a
+  fixed gutter, `divided` rows, or `inline` pairs running across a line —
+  or `bare`, which adds no layout of its own: the `<dl>` takes only the
+  caller's `class` (say `grid grid-cols-[auto_1fr] gap-x-4`) and every
+  row's `<dt>`/`<dd>` is a direct child of it, so a consumer-owned grid can
+  mix `DescriptionRow`s with its own `<dt>`/`<dd>` pairs and keep its columns.
+
+  One component rather than the two the apps had. They had split it by how the
+  VALUE arrives — one took rows as strings, the other took them as markup —
+  which meant a page needing a formatted date in one row and a string in the
+  next had to choose a component per list. Here the value is a prop or a
+  snippet on the ROW, so both live in one list.
+
+  `mono` marks the values that are identifiers (a formula, an InChIKey, a
+  DOI) rather than sentences: those want a fixed-width face and a
+  break-anywhere rule, and the ones that are prose do not.
+
+  ARIA contract: a real `<dl>` of `<dt>`/`<dd>` pairs, which is what makes the
+  label / value association exist at all — a screen reader reads a `<dd>` as
+  the definition of the `<dt>` before it. The variant reaches the rows through
+  context (see `description-context.ts`), never through a class on the list
+  that the rows would have to guess at.
+-->
+<script lang="ts">import { setDescriptionListStyle } from "./description-context.js";
+let { variant = "grid", mono = false, showEmpty = false, emptyLabel = "unrecorded", children, class: className, ...rest } = $props();
+// Literal lookup table: Tailwind reads the class names out of the source,
+// so a template string would emit no CSS at all.
+const listClass = {
+	grid: "grid grid-cols-1 gap-3 sm:grid-cols-2",
+	card: "card card-border card-body bg-base-100 grid grid-cols-1 gap-x-6 gap-y-3 sm:grid-cols-[12rem_1fr]",
+	divided: "divide-base-300 divide-y",
+	inline: "flex flex-wrap gap-x-6 gap-y-2",
+	// The caller's `class` is the whole layout.
+	bare: ""
+};
+// A getter, not a snapshot: the rows re-read it, so a list whose `variant`
+// changes re-styles the rows it already mounted.
+setDescriptionListStyle(() => ({
+	variant,
+	mono,
+	showEmpty,
+	emptyLabel
+}));
+</script>
+
+<dl {...rest} class={[listClass[variant], className]}>
+  {@render children()}
+</dl>

package/dist/data/DescriptionList.svelte.d.ts

@@ -0,0 +1,26 @@
+import type { Snippet } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
+import { type DescriptionListStyle } from './description-context.ts';
+type Variant = DescriptionListStyle['variant'];
+interface Props extends HTMLAttributes<HTMLElement> {
+    /**
+     * The layout.
+     * @defaultValue `'grid'`
+     */
+    variant?: Variant | undefined;
+    /** Render values in a fixed-width face that breaks anywhere. */
+    mono?: boolean | undefined;
+    /** Render rows whose value is empty, rather than dropping them. */
+    showEmpty?: boolean | undefined;
+    /**
+     * What an empty value reads as when `showEmpty`.
+     * @defaultValue `'unrecorded'`
+     */
+    emptyLabel?: string | undefined;
+    /** The rows — `DescriptionRow`s, or any other `<dt>`/`<dd>` pairs. */
+    children: Snippet<[]>;
+}
+/** Label/value pairs as a `grid`, a bordered `card`, `divided` rows, `inline` pairs, or `bare` pairs in a layout the caller supplies. */
+declare const DescriptionList: import("svelte").Component<Props, {}, "">;
+type DescriptionList = ReturnType<typeof DescriptionList>;
+export default DescriptionList;

package/dist/data/DescriptionRow.svelte

@@ -0,0 +1,56 @@
+<!-- @component
+One label and its value inside a `DescriptionList`.
+-->
+<!--
+  DescriptionRow — one label and its value inside a `DescriptionList`.
+
+  A row with nothing in it renders NOTHING. An empty `<dd>` is a worse answer
+  than an absent row: it claims the page looked and found a blank, where the
+  absent row claims nothing at all. `showEmpty` is for the lists where the
+  absence is the point — a specimen record whose empty fields are what the
+  reader is checking — and it renders `emptyLabel` in the value's place.
+  Both settings come from the enclosing list by default and can be overridden
+  per row.
+
+  The `card` and `bare` variants' `<dt>` and `<dd>` are siblings of every
+  other row's, directly in the `<dl>` (the list's own two-column grid for
+  `card`, whatever layout the caller gave it for `bare`): a wrapper would
+  break the alignment the grid exists for. Every other variant wraps the
+  pair, so the two stay together when the rows wrap.
+
+  ARIA contract: the `<dt>`/`<dd>` pairing is the whole contract — nothing is
+  added to it, and nothing needs to be.
+-->
+<script lang="ts">import { getDescriptionListStyle } from "./description-context.js";
+let { label, value, children, valueClass, labelClass, showEmpty, emptyLabel } = $props();
+const style = getDescriptionListStyle();
+const hasValue = $derived(children !== undefined || value !== undefined && String(value).trim() !== "");
+const visible = $derived(hasValue || (showEmpty ?? style().showEmpty));
+const placeholder = $derived(emptyLabel ?? style().emptyLabel);
+const dtClass = $derived(["text-base-content/60 text-sm", labelClass]);
+const ddClass = $derived([
+	"text-sm",
+	style().mono && "font-mono break-all",
+	!hasValue && "text-base-content/50 italic",
+	valueClass
+]);
+</script>
+
+{#snippet pair()}
+  <dt class={dtClass}>{label}</dt>
+  <dd class={ddClass}>
+    {#if children}{@render children()}{:else if hasValue}{value}{:else}{placeholder}{/if}
+  </dd>
+{/snippet}
+
+{#if visible}
+  {#if style().variant === 'card' || style().variant === 'bare'}
+    {@render pair()}
+  {:else if style().variant === 'inline'}
+    <div class="flex items-baseline gap-2">{@render pair()}</div>
+  {:else if style().variant === 'divided'}
+    <div class="flex flex-col gap-0.5 py-2 sm:flex-row sm:gap-4">{@render pair()}</div>
+  {:else}
+    <div class="flex flex-col gap-0.5">{@render pair()}</div>
+  {/if}
+{/if}

package/dist/data/DescriptionRow.svelte.d.ts

@@ -0,0 +1,21 @@
+import type { Snippet } from 'svelte';
+interface Props {
+    /** The term, rendered as the `<dt>`. */
+    label: string;
+    /** The value as text. Ignored when `children` is given. */
+    value?: string | number | undefined;
+    /** The value as markup — a formatted date, a link, a badge. */
+    children?: Snippet<[]> | undefined;
+    /** Extra classes on the `<dd>`. */
+    valueClass?: string | undefined;
+    /** Extra classes on the `<dt>`. */
+    labelClass?: string | undefined;
+    /** Override the list's `showEmpty` for this row. */
+    showEmpty?: boolean | undefined;
+    /** Override the list's `emptyLabel` for this row. */
+    emptyLabel?: string | undefined;
+}
+/** One label and its value inside a `DescriptionList`. */
+declare const DescriptionRow: import("svelte").Component<Props, {}, "">;
+type DescriptionRow = ReturnType<typeof DescriptionRow>;
+export default DescriptionRow;

package/dist/data/DiffText.svelte

@@ -0,0 +1,29 @@
+<!-- @component
+A word-level diff rendered inline: inserted runs in `<ins>`, deleted runs in `<del>`, unchanged runs plain.
+-->
+<!--
+  DiffText — a word-level diff rendered inline: inserted runs in `<ins>`,
+  deleted runs in `<del>`, unchanged runs plain.
+
+  ARIA contract: `<ins>` and `<del>` are the contract. They are what carries
+  "added" and "removed" into the accessibility tree and into a copy of the
+  page; the colour and the strike-through are the sighted reader's copy of
+  the same information, never the only copy. Support for announcing the two
+  elements is uneven across screen readers, so `insertLabel` / `deleteLabel`
+  add a visually hidden word before a run when the diff is the point of the
+  page rather than a detail on it — off by default, because a forty-segment
+  diff with a prefix on every run is unreadable.
+
+  `separator` sits BETWEEN segments rather than inside them: a word-level
+  diff needs the space and a character-level one must not have it, and only
+  the caller knows which it produced. That is also why the template below is
+  written without line breaks between the runs — a newline in the markup is a
+  space in the output, and it would make the choice for them.
+-->
+<script lang="ts">import VisuallyHidden from "../ui/VisuallyHidden.svelte";
+let { segments, separator = " ", insertLabel, deleteLabel, class: className, ...rest } = $props();
+</script>
+
+{#snippet run(segment: DiffSegment)}{#if segment.kind === 'insert'}<ins class="bg-success/20 text-success-content decoration-success underline">{#if insertLabel !== undefined}<VisuallyHidden>{insertLabel}</VisuallyHidden>{/if}{segment.text}</ins>{:else if segment.kind === 'delete'}<del class="bg-error/20 text-error-content">{#if deleteLabel !== undefined}<VisuallyHidden>{deleteLabel}</VisuallyHidden>{/if}{segment.text}</del>{:else}{segment.text}{/if}{/snippet}
+
+<p {...rest} class={['leading-7', className]}>{#each segments as segment, index (index)}{#if index > 0}{separator}{/if}{@render run(segment)}{/each}</p>

package/dist/data/DiffText.svelte.d.ts

@@ -0,0 +1,19 @@
+import type { HTMLAttributes } from 'svelte/elements';
+import type { DiffSegment } from './diff.ts';
+interface Props extends Omit<HTMLAttributes<HTMLParagraphElement>, 'children'> {
+    /** The diff, in reading order. */
+    segments: readonly DiffSegment[];
+    /**
+     * Rendered between segments — a space for a word-level diff.
+     * @defaultValue `' '`
+     */
+    separator?: string | undefined;
+    /** A visually hidden word before each inserted run. */
+    insertLabel?: string | undefined;
+    /** A visually hidden word before each deleted run. */
+    deleteLabel?: string | undefined;
+}
+/** A word-level diff rendered inline: inserted runs in `<ins>`, deleted runs in `<del>`, unchanged runs plain. */
+declare const DiffText: import("svelte").Component<Props, {}, "">;
+type DiffText = ReturnType<typeof DiffText>;
+export default DiffText;

package/dist/data/ItemList.svelte

@@ -0,0 +1,80 @@
+<!-- @component
+A list in one of four shapes — `compact` links, `stacked` rows, a `grid` or `cards` — with an optional feed mode for windowed streams.
+-->
+<!--
+  ItemList — the list every index page and detail section renders, in the four
+  shapes those pages actually use: a `compact` run of links, `stacked` rows
+  divided by rules, a responsive `grid`, or a grid of `cards`.
+
+  The row body is the caller's, through the `item` snippet, because row shape
+  varies per resource type; what this owns is the container, the keying and
+  the empty state — so an empty list cannot be forgotten in one page out of
+  twenty.
+
+  ARIA contract, two modes:
+
+  - Default: a plain `<ul>` of `<li>`s. The list structure is the semantics —
+    a screen reader announces "list, 12 items" — and nothing is added to it.
+  - `feed`: the ARIA feed pattern, for a stream whose items load as the
+    reader scrolls. The container takes `role="feed"`, an accessible name from
+    `label`, and `aria-busy` while more is loading; each item is an `<article>`
+    carrying `aria-posinset` / `aria-setsize`, so "article 7 of 40" is
+    announced even though only 20 are in the DOM, and `tabindex="-1"` so the
+    reader's Page Down lands somewhere.
+
+    Feed mode renders `<div role="feed">` with `<article>` children rather
+    than a list, deliberately: `feed` is not a role HTML permits on `<ul>`,
+    and forcing `role="article"` onto each `<li>` would throw away the list
+    semantics to get there. A feed is not a list, and the markup says so.
+-->
+<script lang="ts" generics="T">let { items, variant = "compact", getKey, item, empty, emptyMessage = "Nothing here yet.", feed = false, label, busy = false, class: className, ...rest } = $props();
+// Literal lookup tables: Tailwind only generates the classes it can read
+// verbatim in the source, so these can never become template strings.
+const containerClass = {
+	compact: "space-y-1",
+	stacked: "divide-base-300 divide-y",
+	grid: "grid grid-cols-1 gap-3 sm:grid-cols-2",
+	cards: "grid grid-cols-1 gap-4 sm:grid-cols-2"
+};
+const itemClass = {
+	compact: "",
+	stacked: "py-3",
+	grid: "",
+	cards: "card card-border bg-base-100 p-4 shadow-sm"
+};
+const setSize = $derived(items.length);
+export {};
+</script>
+
+{#if items.length === 0}
+  {#if empty}
+    {@render empty()}
+  {:else}
+    <p class="text-base-content/70 text-sm leading-6">{emptyMessage}</p>
+  {/if}
+{:else if feed}
+  <div
+    {...rest}
+    role="feed"
+    aria-label={label}
+    aria-busy={busy}
+    class={[containerClass[variant], className]}
+  >
+    {#each items as entry, index (getKey(entry, index))}
+      <article
+        aria-posinset={index + 1}
+        aria-setsize={setSize}
+        tabindex="-1"
+        class={itemClass[variant]}
+      >
+        {@render item(entry, index)}
+      </article>
+    {/each}
+  </div>
+{:else}
+  <ul {...rest} aria-label={label} class={[containerClass[variant], className]}>
+    {#each items as entry, index (getKey(entry, index))}
+      <li class={itemClass[variant]}>{@render item(entry, index)}</li>
+    {/each}
+  </ul>
+{/if}

package/dist/data/ItemList.svelte.d.ts

@@ -0,0 +1,52 @@
+import type { Snippet } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
+declare function $$render<T>(): {
+    props: Omit<HTMLAttributes<HTMLElement>, "children"> & {
+        /** The items, each rendered by the `item` snippet. */
+        items: readonly T[];
+        /**
+         * The layout.
+         * @defaultValue `'compact'`
+         */
+        variant?: ("grid" | "compact" | "stacked" | "cards") | undefined;
+        /** Stable identity per item — the `{#each}` key. */
+        getKey: (item: T, index: number) => string;
+        /** One row's body. */
+        item: Snippet<[T, number]>;
+        /** Rendered in place of the list when there is nothing in it. */
+        empty?: Snippet<[]> | undefined;
+        /**
+         * The line shown when there is nothing and no `empty` snippet.
+         * @defaultValue `'Nothing here yet.'`
+         */
+        emptyMessage?: string | undefined;
+        /** Render as an ARIA feed. */
+        feed?: boolean | undefined;
+        /** The feed's accessible name. Required in `feed` mode to name the region. */
+        label?: string | undefined;
+        /** More items are loading — `aria-busy` on the feed. */
+        busy?: boolean | undefined;
+    };
+    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']>;
+}
+/** A list in one of four shapes — `compact` links, `stacked` rows, a `grid` or `cards` — with an optional feed mode for windowed streams. */
+declare const ItemList: $$IsomorphicComponent;
+type ItemList<T> = InstanceType<typeof ItemList<T>>;
+export default ItemList;

package/dist/data/LinkListItem.svelte

@@ -0,0 +1,46 @@
+<!-- @component
+The row body most lists want: a linked title, a line of context under it, and short badges.
+-->
+<!--
+  LinkListItem — the row body most lists want: a linked title, a line of
+  context under it, and short markers.
+
+  It renders the body only, never the `<li>` or the `<article>` around it,
+  because the container is `ItemList`'s decision (a list item in one mode, a
+  feed article in the other) and a component that rendered both would have to
+  know which.
+
+  ARIA contract: the title is a real link, resolved through the components
+  context, and it is the row's only interactive element — the subtitle and
+  the badges are text beside it, not a second target. `headingLevel` promotes
+  the title to a real heading for a list of sections a reader navigates by
+  headings; by default it is not one, because twenty `<h3>`s in a filter
+  result is worse for navigation than none.
+-->
+<script lang="ts">import Badge from "../ui/Badge.svelte";
+import Link from "../ui/Link.svelte";
+let { href, title, subtitle, badges, headingLevel, meta, class: className, ...rest } = $props();
+</script>
+
+<div {...rest} class={['flex flex-col gap-1', className]}>
+  {#if headingLevel === undefined}
+    <Link {href} variant="muted" class="font-medium">{title}</Link>
+  {:else}
+    <svelte:element this={`h${headingLevel}`} class="text-base font-medium">
+      <Link {href} variant="muted">{title}</Link>
+    </svelte:element>
+  {/if}
+  {#if subtitle !== undefined}
+    <p class="text-base-content/70 text-sm">{subtitle}</p>
+  {/if}
+  {#if meta}
+    <div class="text-base-content/60 text-sm">{@render meta()}</div>
+  {/if}
+  {#if badges !== undefined && badges.length > 0}
+    <div class="flex flex-wrap gap-1">
+      {#each badges as badge (badge)}
+        <Badge variant="outline" size="sm">{badge}</Badge>
+      {/each}
+    </div>
+  {/if}
+</div>