@thomasfosterau/components 0.0.0 → 0.1.0

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,47 @@
+<!-- @component
+Label/value pairs as a `grid`, a bordered `card`, `divided` rows or `inline` pairs.
+-->
+<!--
+  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.
+
+  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"
+};
+// 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 or `inline` pairs. */
+declare const DescriptionList: import("svelte").Component<Props, {}, "">;
+type DescriptionList = ReturnType<typeof DescriptionList>;
+export default DescriptionList;

package/dist/data/DescriptionRow.svelte

@@ -0,0 +1,55 @@
+<!-- @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` variant's `<dt>` and `<dd>` are siblings of every other row's,
+  directly in the list's two-column grid: 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'}
+    {@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>

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

@@ -0,0 +1,21 @@
+import type { Snippet } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
+import type { HeadingLevel } from '../ui/tones.ts';
+interface Props extends Omit<HTMLAttributes<HTMLDivElement>, 'title' | 'children'> {
+    /** Where the title links to; resolved through the components context. */
+    href: string;
+    /** The linked title; rendered as a heading when `headingLevel` is set. */
+    title: string;
+    /** A line of context under the title — an owner, a parent, a date. */
+    subtitle?: string | undefined;
+    /** Short markers rendered as badges. */
+    badges?: readonly string[] | undefined;
+    /** Render the title as a real heading at this level. */
+    headingLevel?: HeadingLevel | undefined;
+    /** Extra detail under the subtitle — formatted dates, counts, a second link. */
+    meta?: Snippet<[]> | undefined;
+}
+/** The row body most lists want: a linked title, a line of context under it, and short badges. */
+declare const LinkListItem: import("svelte").Component<Props, {}, "">;
+type LinkListItem = ReturnType<typeof LinkListItem>;
+export default LinkListItem;

package/dist/data/Pagination.svelte

@@ -0,0 +1,136 @@
+<!-- @component
+Offset-based page navigation: numbered links with gaps or a bare Previous/Next pair, as links (`href`) or callbacks (`onPage`).
+-->
+<!--
+  Pagination — one component for the five pagers the four apps had grown:
+  numbered page links with gaps, a bare Previous/Next pair, the link form and
+  the callback form.
+
+  Two axes, and that is the whole design. `variant` chooses how much is
+  drawn — `window` renders first / last / the current page's neighbours,
+  `prevNext` renders the two arms and nothing else, which is what a listing
+  that only knows "there is more" can honestly offer. `href` versus `onPage`
+  chooses what the controls ARE: given `href` they are real links, which keeps
+  Ctrl-click, middle-click and "copy link address" and works with no
+  JavaScript at all; given `onPage` they are buttons, for a pager over state
+  the URL does not carry. `href` wins when both are passed.
+
+  ARIA contract: a `<nav>` named by `label`, holding a list of controls. The
+  arms carry `rel="prev"` / `rel="next"`. An unavailable arm is an
+  `aria-disabled` `<span>` — never a link to nowhere, and never removed, since
+  a pager whose Previous disappears on page one slides Next under the reader's
+  cursor. The current page is a `<span>` with `aria-current="page"` rather
+  than a link to where you already are; every numbered control is named
+  "Page 8" through `pageLabel`, because a bare digit is not an accessible
+  name; and the gap marker is `aria-hidden`, because "…" is not information.
+
+  In `window` mode a single page renders nothing at all — there is nothing to
+  navigate — unless `showRange` asked for the range line, which is a fact
+  about the result and still true. In `prevNext` mode both arms stay, disabled:
+  that variant is drawn by a caller that wants its control bar to hold place.
+-->
+<script lang="ts">import { ChevronLeft, ChevronRight } from "@lucide/svelte";
+import { getComponentsContext } from "../context.svelte.js";
+import { buttonSize } from "../ui/tones.js";
+import { pageWindow } from "./pagination.js";
+let { offset, limit, total, variant = "window", href, onPage, siblings = 1, label = "Pagination", previousLabel = "Previous", nextLabel = "Next", pageLabel = (page) => `Page ${page}`, size = "sm", showRange = false, rangeLabel, statusLabel, locales = getComponentsContext().locale(), class: className, ...rest } = $props();
+const context = getComponentsContext();
+const view = $derived(pageWindow({
+	offset,
+	limit
+}, total, siblings));
+// The formatter and the formatted string are separate `$derived`s so the
+// (relatively expensive) `Intl.NumberFormat` is not rebuilt when only the
+// offset moves. Counts are quantities and get grouped; the page NUMBERS
+// below are identifiers and stay bare.
+const counts = $derived(new Intl.NumberFormat(locales));
+const rangeText = $derived(rangeLabel === undefined ? `Showing ${counts.format(view.from)}–${counts.format(view.to)} of ${counts.format(total)}` : rangeLabel(view.from, view.to, total));
+/** A target offset's href, resolved through the context. */
+const linkTo = (target) => href === undefined ? undefined : context.href(href(target));
+const itemClass = $derived(["btn join-item", buttonSize[size]]);
+const inertClass = $derived(["btn btn-disabled join-item", buttonSize[size]]);
+</script>
+
+{#snippet armBody(text: string, leading: boolean)}
+  {#if leading}<ChevronLeft class="size-4" aria-hidden="true" />{/if}
+  <span>{text}</span>
+  {#if !leading}<ChevronRight class="size-4" aria-hidden="true" />{/if}
+{/snippet}
+
+{#snippet arm(target: number | undefined, text: string, rel: 'prev' | 'next', leading: boolean)}
+  <li>
+    {#if target === undefined}
+      <span class={inertClass} aria-disabled="true">{@render armBody(text, leading)}</span>
+    {:else if href !== undefined}
+      <a href={linkTo(target)} {rel} class={itemClass}>{@render armBody(text, leading)}</a>
+    {:else}
+      <button
+        type="button"
+        class={itemClass}
+        onclick={() => {
+          onPage?.(target);
+        }}
+      >
+        {@render armBody(text, leading)}
+      </button>
+    {/if}
+  </li>
+{/snippet}
+
+{#if variant === 'prevNext' || view.pageCount > 1}
+  <nav
+    {...rest}
+    aria-label={label}
+    class={['flex flex-col items-center gap-2 sm:flex-row sm:justify-between', className]}
+  >
+    {#if showRange}
+      <p class="text-base-content/70 text-sm tabular-nums">{rangeText}</p>
+    {/if}
+    <ul class="join">
+      {@render arm(view.previous, previousLabel, 'prev', true)}
+      {#if variant === 'prevNext'}
+        {#if statusLabel !== undefined}
+          <li>
+            <span class={['btn btn-ghost join-item pointer-events-none', buttonSize[size]]}>
+              {statusLabel(view.page, view.pageCount)}
+            </span>
+          </li>
+        {/if}
+      {:else}
+        {#each view.items as item (item.kind === 'page' ? item.page : `gap-${item.after}`)}
+          <li>
+            {#if item.kind === 'gap'}
+              <span class={inertClass} aria-hidden="true">…</span>
+            {:else if item.current}
+              <span class={['btn btn-active join-item', buttonSize[size]]} aria-current="page">
+                <span class="sr-only">{pageLabel(item.page)}</span>
+                <span aria-hidden="true">{item.page}</span>
+              </span>
+            {:else if href !== undefined}
+              <a href={linkTo(item.offset)} class={itemClass} aria-label={pageLabel(item.page)}>
+                <span aria-hidden="true">{item.page}</span>
+              </a>
+            {:else}
+              <button
+                type="button"
+                class={itemClass}
+                aria-label={pageLabel(item.page)}
+                onclick={() => {
+                  onPage?.(item.offset);
+                }}
+              >
+                <span aria-hidden="true">{item.page}</span>
+              </button>
+            {/if}
+          </li>
+        {/each}
+      {/if}
+      {@render arm(view.next, nextLabel, 'next', false)}
+    </ul>
+  </nav>
+{:else if showRange}
+  <!-- One page, so there is nothing to navigate — but the range line is a
+       fact about the result, not about the pager, and stays. A <nav> around
+       it alone would be a landmark with no controls in it. -->
+  <p {...rest} class={['text-base-content/70 text-sm tabular-nums', className]}>{rangeText}</p>
+{/if}