@thomasfosterau/components 0.0.0 → 0.1.0

package/dist/data/index.d.ts

@@ -0,0 +1,35 @@
+/**
+ * data — the tables, lists and pagers an index page and a detail page are
+ * built from.
+ *
+ * Two shapes of list run through this family, and the split is worth stating
+ * once. `Table` and `ItemList` present a window a caller already chose:
+ * they never decide which rows exist, so they serve a server-paged collection
+ * of 40,000 as happily as a list of four. `DataGrid` is the other shape —
+ * it sorts, filters and pages a bounded set the page already holds, entirely
+ * on the client — and it composes the first two rather than duplicating them.
+ *
+ * Every optional prop in this family is declared `T | undefined`, not bare
+ * `T`: the workspace compiles with `exactOptionalPropertyTypes`, under which
+ * `prop?: T` rejects an explicitly passed `undefined`, and a caller
+ * forwarding its own optional prop straight through would not compile.
+ *
+ * @module
+ */
+export { default as DataGrid } from './DataGrid.svelte';
+export { default as DescriptionList } from './DescriptionList.svelte';
+export { default as DescriptionRow } from './DescriptionRow.svelte';
+export { default as DiffText } from './DiffText.svelte';
+export { default as ItemList } from './ItemList.svelte';
+export { default as LinkListItem } from './LinkListItem.svelte';
+export { default as Pagination } from './Pagination.svelte';
+export { default as PaginationFooter } from './PaginationFooter.svelte';
+export { default as ResultCount } from './ResultCount.svelte';
+export { default as Table } from './Table.svelte';
+export { default as TreeList } from './TreeList.svelte';
+export { default as TreeListItem } from './TreeListItem.svelte';
+export * from './description-context.ts';
+export * from './diff.ts';
+export * from './list-item.ts';
+export * from './pagination.ts';
+export * from './table-types.ts';

package/dist/data/index.js

@@ -0,0 +1,35 @@
+/**
+ * data — the tables, lists and pagers an index page and a detail page are
+ * built from.
+ *
+ * Two shapes of list run through this family, and the split is worth stating
+ * once. `Table` and `ItemList` present a window a caller already chose:
+ * they never decide which rows exist, so they serve a server-paged collection
+ * of 40,000 as happily as a list of four. `DataGrid` is the other shape —
+ * it sorts, filters and pages a bounded set the page already holds, entirely
+ * on the client — and it composes the first two rather than duplicating them.
+ *
+ * Every optional prop in this family is declared `T | undefined`, not bare
+ * `T`: the workspace compiles with `exactOptionalPropertyTypes`, under which
+ * `prop?: T` rejects an explicitly passed `undefined`, and a caller
+ * forwarding its own optional prop straight through would not compile.
+ *
+ * @module
+ */
+export { default as DataGrid } from './DataGrid.svelte';
+export { default as DescriptionList } from './DescriptionList.svelte';
+export { default as DescriptionRow } from './DescriptionRow.svelte';
+export { default as DiffText } from './DiffText.svelte';
+export { default as ItemList } from './ItemList.svelte';
+export { default as LinkListItem } from './LinkListItem.svelte';
+export { default as Pagination } from './Pagination.svelte';
+export { default as PaginationFooter } from './PaginationFooter.svelte';
+export { default as ResultCount } from './ResultCount.svelte';
+export { default as Table } from './Table.svelte';
+export { default as TreeList } from './TreeList.svelte';
+export { default as TreeListItem } from './TreeListItem.svelte';
+export * from "./description-context.js";
+export * from "./diff.js";
+export * from "./list-item.js";
+export * from "./pagination.js";
+export * from "./table-types.js";

package/dist/data/list-item.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The row shape an index page maps its data into before handing it to
+ * `ItemList`.
+ *
+ * A type, not a resource: the caller's own mappers turn a wire document into
+ * it, which is what keeps every API's shape out of this package. It lives in
+ * a `.ts` module rather than a `<script module>` block so a mapper — and the
+ * mapper's unit test — can import it without reaching through a component.
+ *
+ * Both optional members are declared `?: T | undefined` rather than bare
+ * `?: T`. The workspace compiles under `exactOptionalPropertyTypes`, where
+ * `{ subtitle: undefined }` is not the same thing as an absent key: with the
+ * narrow declaration every mapper reading a possibly-absent attribute has to
+ * spread the member conditionally, which is three lines and a comment at
+ * every call site. Widening it here is what removes them.
+ *
+ * @module
+ */
+/** One row of a `LinkListItem`-shaped list. */
+export interface LinkListItemData {
+    /** Stable identity — the list's `{#each}` key. */
+    readonly id: string;
+    /** Where the row's title links to; resolved through the components context. */
+    readonly href: string;
+    readonly title: string;
+    /** A line of context under the title — an owner, a parent, a date. */
+    readonly subtitle?: string | undefined;
+    /** Short markers rendered as badges (a visibility state, a kind). */
+    readonly badges?: readonly string[] | undefined;
+}

package/dist/data/list-item.js

@@ -0,0 +1,19 @@
+/**
+ * The row shape an index page maps its data into before handing it to
+ * `ItemList`.
+ *
+ * A type, not a resource: the caller's own mappers turn a wire document into
+ * it, which is what keeps every API's shape out of this package. It lives in
+ * a `.ts` module rather than a `<script module>` block so a mapper — and the
+ * mapper's unit test — can import it without reaching through a component.
+ *
+ * Both optional members are declared `?: T | undefined` rather than bare
+ * `?: T`. The workspace compiles under `exactOptionalPropertyTypes`, where
+ * `{ subtitle: undefined }` is not the same thing as an absent key: with the
+ * narrow declaration every mapper reading a possibly-absent attribute has to
+ * spread the member conditionally, which is three lines and a comment at
+ * every call site. Widening it here is what removes them.
+ *
+ * @module
+ */
+export {};

package/dist/data/pagination.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Offset / limit pagination arithmetic, and the href that carries it.
+ *
+ * Pure functions, deliberately: the window a pager renders (first page, last
+ * page, the current page's neighbours, the gaps between them) is arithmetic
+ * with a dozen edge cases — an offset past the end, a zero limit, a total of
+ * zero — and arithmetic is far cheaper to pin in a unit test than in a
+ * rendered component. `Pagination` is then markup over {@link pageWindow}.
+ *
+ * Ported from an Effect implementation with `Option` replaced by
+ * `undefined` and the query Schema left behind in the app that needs it:
+ * decoding an app's own URL is the app's job, and a component library that
+ * owned it would drag a validation library onto every consumer's page.
+ *
+ * @module
+ */
+/** The JSON:API offset query parameter — the default {@link pageHref} writes. */
+export declare const PAGE_OFFSET_PARAM = "page[offset]";
+/** The JSON:API limit query parameter — the default {@link pageHref} writes. */
+export declare const PAGE_LIMIT_PARAM = "page[limit]";
+/** A resolved page position. */
+export interface Page {
+    readonly offset: number;
+    readonly limit: number;
+}
+/** The query-parameter names {@link pageHref} writes the position into. */
+export interface PageParamNames {
+    readonly offset?: string | undefined;
+    readonly limit?: string | undefined;
+}
+/**
+ * Build the href for `page` from `base` (a path, optionally with a query
+ * string and a fragment).
+ *
+ * Every other query parameter is preserved and the page parameters are
+ * replaced — paging through a filtered list that silently dropped the filter
+ * is the bug this shape exists to prevent. A relative `base` yields a
+ * relative href: the absolute origin below is a parsing scaffold, never part
+ * of the result.
+ */
+export declare function pageHref(base: string, page: Page, names?: PageParamNames): string;
+/** One entry in a rendered page window: a page link, or the gap before one. */
+export type PageWindowItem = {
+    readonly kind: 'page';
+    /** 1-based page number, as rendered. */
+    readonly page: number;
+    /** The offset that page starts at. */
+    readonly offset: number;
+    readonly current: boolean;
+} | {
+    readonly kind: 'gap'; /** The page number the gap follows. */
+    readonly after: number;
+};
+/** Everything a pager needs to draw itself, from one position and a total. */
+export interface PageWindow {
+    /** 1-based current page. */
+    readonly page: number;
+    /** Total pages; at least 1, even with no rows. */
+    readonly pageCount: number;
+    /** 1-based index of the first row shown, or 0 when there are no rows. */
+    readonly from: number;
+    /** 1-based index of the last row shown, or 0 when there are no rows. */
+    readonly to: number;
+    /** Offset of the previous page, or `undefined` on the first. */
+    readonly previous: number | undefined;
+    /** Offset of the next page, or `undefined` on the last. */
+    readonly next: number | undefined;
+    /** First page, last page, and `siblings` pages either side of the current. */
+    readonly items: readonly PageWindowItem[];
+}
+/**
+ * Compute the window of page links to render around `page`: the first and
+ * last pages always, plus `siblings` pages either side of the current one,
+ * with a gap marker wherever the sequence skips.
+ *
+ * Tolerant by construction — a zero or negative limit, a negative offset and
+ * an offset past the end all resolve to a real page rather than throwing,
+ * because every one of them arrives from a hand-edited URL sooner or later
+ * and a 500 is a worse answer than the first page.
+ */
+export declare function pageWindow(page: Page, total: number, siblings?: number): PageWindow;

package/dist/data/pagination.js

@@ -0,0 +1,79 @@
+/**
+ * Offset / limit pagination arithmetic, and the href that carries it.
+ *
+ * Pure functions, deliberately: the window a pager renders (first page, last
+ * page, the current page's neighbours, the gaps between them) is arithmetic
+ * with a dozen edge cases — an offset past the end, a zero limit, a total of
+ * zero — and arithmetic is far cheaper to pin in a unit test than in a
+ * rendered component. `Pagination` is then markup over {@link pageWindow}.
+ *
+ * Ported from an Effect implementation with `Option` replaced by
+ * `undefined` and the query Schema left behind in the app that needs it:
+ * decoding an app's own URL is the app's job, and a component library that
+ * owned it would drag a validation library onto every consumer's page.
+ *
+ * @module
+ */
+/** The JSON:API offset query parameter — the default {@link pageHref} writes. */
+export const PAGE_OFFSET_PARAM = 'page[offset]';
+/** The JSON:API limit query parameter — the default {@link pageHref} writes. */
+export const PAGE_LIMIT_PARAM = 'page[limit]';
+/**
+ * Build the href for `page` from `base` (a path, optionally with a query
+ * string and a fragment).
+ *
+ * Every other query parameter is preserved and the page parameters are
+ * replaced — paging through a filtered list that silently dropped the filter
+ * is the bug this shape exists to prevent. A relative `base` yields a
+ * relative href: the absolute origin below is a parsing scaffold, never part
+ * of the result.
+ */
+export function pageHref(base, page, names = {}) {
+    const url = new URL(base, 'http://pagination.invalid');
+    url.searchParams.set(names.offset ?? PAGE_OFFSET_PARAM, String(page.offset));
+    url.searchParams.set(names.limit ?? PAGE_LIMIT_PARAM, String(page.limit));
+    return `${url.pathname}${url.search}${url.hash}`;
+}
+/**
+ * Compute the window of page links to render around `page`: the first and
+ * last pages always, plus `siblings` pages either side of the current one,
+ * with a gap marker wherever the sequence skips.
+ *
+ * Tolerant by construction — a zero or negative limit, a negative offset and
+ * an offset past the end all resolve to a real page rather than throwing,
+ * because every one of them arrives from a hand-edited URL sooner or later
+ * and a 500 is a worse answer than the first page.
+ */
+export function pageWindow(page, total, siblings = 1) {
+    const limit = Math.max(1, Math.floor(page.limit));
+    const offset = Math.max(0, Math.floor(page.offset));
+    const rows = Math.max(0, total);
+    const pageCount = Math.max(1, Math.ceil(rows / limit));
+    const current = Math.min(pageCount, Math.floor(offset / limit) + 1);
+    const wanted = [];
+    const want = (n) => {
+        if (n >= 1 && n <= pageCount && !wanted.includes(n))
+            wanted.push(n);
+    };
+    want(1);
+    for (let n = current - siblings; n <= current + siblings; n += 1)
+        want(n);
+    want(pageCount);
+    wanted.sort((left, right) => left - right);
+    const items = [];
+    for (const [index, n] of wanted.entries()) {
+        const previous = index > 0 ? wanted[index - 1] : undefined;
+        if (previous !== undefined && n - previous > 1)
+            items.push({ kind: 'gap', after: previous });
+        items.push({ kind: 'page', page: n, offset: (n - 1) * limit, current: n === current });
+    }
+    return {
+        page: current,
+        pageCount,
+        from: rows > 0 ? (current - 1) * limit + 1 : 0,
+        to: rows > 0 ? Math.min(rows, current * limit) : 0,
+        previous: current > 1 ? (current - 2) * limit : undefined,
+        next: current < pageCount ? current * limit : undefined,
+        items,
+    };
+}

package/dist/data/table-types.d.ts

@@ -0,0 +1,64 @@
+/**
+ * The column spec `Table` and `DataGrid` share.
+ *
+ * Declarative data rather than a table engine. The apps this is consolidated
+ * from were built on `@tanstack/svelte-table` — a column helper, a
+ * `createTable` instance, four row-model factories and a `FlexRender`
+ * indirection — which is ~40 kB of client JavaScript for tables whose whole
+ * job is to show rows, sort one column and page. The spec below is data, and
+ * the sorting / filtering / paging live in `DataGrid`'s own derivations.
+ * Reach for an engine again when something needs column resizing, grouping
+ * or virtualisation; none of those are on the map.
+ *
+ * @module
+ */
+import type { Snippet } from 'svelte';
+/**
+ * One column of a table.
+ *
+ * `value` is required and does triple duty: it is the cell's text, the key
+ * the column sorts on, and the corpus `DataGrid`'s filter searches. One
+ * accessor for all three is what stops a grid that sorts a column by one
+ * thing and shows another — the failure mode of a spec where they are
+ * separate. `cell` layers richer markup (a link, a badge, a formatted date)
+ * over that same value.
+ */
+export interface TableColumn<T> {
+    /** Stable id — the `{#each}` key and the sort state's handle. */
+    readonly key: string;
+    /** The `<th>` text, already in the caller's language. */
+    readonly header: string;
+    /** The cell's text, its sort key, and what a filter matches against. */
+    readonly value: (row: T) => string | number;
+    /** Richer cell markup; `value`'s result is rendered when omitted. */
+    readonly cell?: Snippet<[T]> | undefined;
+    /** Whether the header offers a sort control on this column. */
+    readonly sortable?: boolean | undefined;
+    /** Right-align numeric columns. */
+    readonly align?: 'start' | 'end' | undefined;
+    /** Extra classes on this column's header and body cells. */
+    readonly class?: string | undefined;
+}
+/**
+ * Which column a table is sorted by, and which way.
+ *
+ * Unsorted is `undefined`, not a `SortState` with an empty key: "no column"
+ * is the absence of a sort, and modelling it as a sentinel key means every
+ * reader of the state has to know the sentinel.
+ */
+export interface SortState {
+    /** The `key` of the sorted {@link TableColumn}. */
+    readonly key: string;
+    readonly direction: 'asc' | 'desc';
+}
+/**
+ * The next state in the three-step cycle a sortable header runs:
+ * unsorted → ascending → descending → unsorted.
+ *
+ * A pure function rather than a method on the component so `DataGrid` and a
+ * server-sorted caller cycle identically, and so the cycle is unit-testable
+ * without a DOM.
+ */
+export declare function nextSortState(current: SortState | undefined, key: string): SortState | undefined;
+/** What a column's `<th>` announces in `aria-sort`. */
+export declare function columnAriaSort(sort: SortState | undefined, key: string): 'ascending' | 'descending' | 'none';

package/dist/data/table-types.js

@@ -0,0 +1,35 @@
+/**
+ * The column spec `Table` and `DataGrid` share.
+ *
+ * Declarative data rather than a table engine. The apps this is consolidated
+ * from were built on `@tanstack/svelte-table` — a column helper, a
+ * `createTable` instance, four row-model factories and a `FlexRender`
+ * indirection — which is ~40 kB of client JavaScript for tables whose whole
+ * job is to show rows, sort one column and page. The spec below is data, and
+ * the sorting / filtering / paging live in `DataGrid`'s own derivations.
+ * Reach for an engine again when something needs column resizing, grouping
+ * or virtualisation; none of those are on the map.
+ *
+ * @module
+ */
+/**
+ * The next state in the three-step cycle a sortable header runs:
+ * unsorted → ascending → descending → unsorted.
+ *
+ * A pure function rather than a method on the component so `DataGrid` and a
+ * server-sorted caller cycle identically, and so the cycle is unit-testable
+ * without a DOM.
+ */
+export function nextSortState(current, key) {
+    if (current === undefined || current.key !== key)
+        return { key, direction: 'asc' };
+    if (current.direction === 'asc')
+        return { key, direction: 'desc' };
+    return undefined;
+}
+/** What a column's `<th>` announces in `aria-sort`. */
+export function columnAriaSort(sort, key) {
+    if (sort === undefined || sort.key !== key)
+        return 'none';
+    return sort.direction === 'asc' ? 'ascending' : 'descending';
+}

package/dist/feedback/ConfirmDialog.svelte

@@ -0,0 +1,79 @@
+<!-- @component
+A destructive action behind a modal confirmation, run either as a callback (`onConfirm`) or as a progressive-enhancement POST (`form`).
+-->
+<!--
+  ConfirmDialog — a destructive action behind a modal confirmation, in the two
+  shapes the app repos actually needed.
+
+  **Callback mode** (`onConfirm`) is the client-side one: the promise runs,
+  the confirm button goes busy, a rejection is shown inside the still-open
+  dialog so the reader can retry or cancel, and a resolution closes it and
+  optionally navigates through the components context.
+
+  **Form mode** (`form`) is the progressive-enhancement one: the confirm
+  button is a real `type="submit"` inside a real `<form method="POST">`, so
+  the action posts and the server redirects even with scripting off. The SvelteKit `enhance` action is passed IN by the
+  app (`enhance: (node) => enhance(node)`); importing `$app/forms` here would
+  tie this package to SvelteKit. It is applied as an attachment, so a caller
+  that omits it simply gets the unenhanced form.
+
+  Pass exactly one of the two. With neither, the confirm button does nothing
+  — there is no action to take.
+
+  ARIA contract: `Dialog`'s, plus a failure surfaced as an `Alert` with
+  `live="assertive"` inside the dialog (the reader pressed confirm and
+  nothing visible happened, so the reason has to interrupt). Both buttons are
+  `disabled` while the callback is in flight and the confirm button swaps its
+  text to `pendingLabel` rather than emptying itself, so its accessible name
+  never disappears mid-press.
+-->
+<script lang="ts">import { getComponentsContext } from "../context.svelte.js";
+import Alert from "../ui/Alert.svelte";
+import Button from "../ui/Button.svelte";
+import Dialog from "./Dialog.svelte";
+let { open = $bindable(false), title, description, confirmLabel = "Delete", cancelLabel = "Cancel", pendingLabel = "Working…", failureMessage = "That didn’t work. Try again.", closeLabel = "Close", tone = "error", size = "md", onConfirm, form, redirectTo, class: className, trigger, children } = $props();
+const context = getComponentsContext();
+let pending = $state(false);
+let errorMessage = $state(undefined);
+const confirm = async () => {
+	if (onConfirm === undefined) return;
+	pending = true;
+	errorMessage = undefined;
+	try {
+		await onConfirm();
+		open = false;
+		if (redirectTo !== undefined) await context.navigate(context.href(redirectTo));
+	} catch (error) {
+		errorMessage = error instanceof Error ? error.message : failureMessage;
+	} finally {
+		pending = false;
+	}
+};
+/** The app's `enhance`, as an attachment so omitting it is a no-op. */
+const enhanceForm = (node) => form?.enhance?.(node);
+</script>
+
+<Dialog bind:open {title} {description} {closeLabel} {size} class={className} {trigger}>
+  {#if children}
+    {@render children()}
+  {/if}
+  {#if errorMessage !== undefined}
+    <Alert tone="error" live="assertive">{errorMessage}</Alert>
+  {/if}
+
+  {#snippet actions({ close })}
+    <Button variant="ghost" disabled={pending} onclick={close}>{cancelLabel}</Button>
+    {#if form === undefined}
+      <Button {tone} loading={pending} onclick={confirm}>
+        {pending ? pendingLabel : confirmLabel}
+      </Button>
+    {:else}
+      <form method={form.method ?? 'POST'} action={form.action} {@attach enhanceForm}>
+        {#each Object.entries(form.fields ?? {}) as [name, value] (name)}
+          <input type="hidden" {name} {value} />
+        {/each}
+        <Button {tone} type="submit">{confirmLabel}</Button>
+      </form>
+    {/if}
+  {/snippet}
+</Dialog>

package/dist/feedback/ConfirmDialog.svelte.d.ts

@@ -0,0 +1,82 @@
+import type { Snippet } from 'svelte';
+import type { Tone } from '../ui/tones.ts';
+import type { DialogSize } from './sizes.ts';
+/** A progressive-enhancement POST: the confirm button submits this form. */
+export interface ConfirmForm {
+    /** The form's `action` — a SvelteKit named action (`?/delete`) or a path. */
+    readonly action: string;
+    /** Always `POST`; spelled out because a destructive GET is a bug. */
+    readonly method?: 'POST' | undefined;
+    /**
+     * Extra fields to post, rendered as hidden inputs INSIDE the form. They
+     * live here rather than in `children` because `children` renders in the
+     * dialog body, which is outside the form element.
+     */
+    readonly fields?: Readonly<Record<string, string>> | undefined;
+    /**
+     * The app's own `use:enhance`, applied to the `<form>` element. Returns
+     * its teardown, if it has one. Omit for a plain, unenhanced POST.
+     */
+    readonly enhance?: ((form: HTMLFormElement) => void | (() => void)) | undefined;
+}
+interface Props {
+    /** Whether the dialog is shown. Bindable. */
+    open?: boolean | undefined;
+    /** Heading — the dialog's accessible name. */
+    title: string;
+    /** What confirming does, in the reader's terms. */
+    description?: string | undefined;
+    /**
+     * Text of the confirm button.
+     * @defaultValue `'Delete'`
+     */
+    confirmLabel?: string | undefined;
+    /**
+     * Text of the cancel button.
+     * @defaultValue `'Cancel'`
+     */
+    cancelLabel?: string | undefined;
+    /**
+     * The confirm button's text while the callback is in flight.
+     * @defaultValue `'Working…'`
+     */
+    pendingLabel?: string | undefined;
+    /**
+     * Shown when the callback rejects with something that is not an `Error`.
+     * @defaultValue `'That didn’t work. Try again.'`
+     */
+    failureMessage?: string | undefined;
+    /**
+     * Accessible name of the corner close button.
+     * @defaultValue `'Close'`
+     */
+    closeLabel?: string | undefined;
+    /**
+     * Colour of the confirm button.
+     * @defaultValue `'error'`
+     */
+    tone?: Tone | undefined;
+    /**
+     * Width of the dialog.
+     * @defaultValue `'md'`
+     */
+    size?: DialogSize | undefined;
+    /** Client-side confirmation. Mutually exclusive with `form`. */
+    onConfirm?: (() => Promise<unknown>) | undefined;
+    /** Progressive-enhancement POST. Mutually exclusive with `onConfirm`. */
+    form?: ConfirmForm | undefined;
+    /** Navigated to through the components context once `onConfirm` resolves. */
+    redirectTo?: string | undefined;
+    /** Extra classes, merged last. */
+    class?: string | undefined;
+    /** The opening control — the caller's own element, spreading `props`. */
+    trigger?: Snippet<[{
+        props: Record<string, unknown>;
+    }]> | undefined;
+    /** Extra body content: a list of what will be destroyed, a reason field. */
+    children?: Snippet<[]> | undefined;
+}
+/** A destructive action behind a modal confirmation, run either as a callback (`onConfirm`) or as a progressive-enhancement POST (`form`). */
+declare const ConfirmDialog: import("svelte").Component<Props, {}, "open">;
+type ConfirmDialog = ReturnType<typeof ConfirmDialog>;
+export default ConfirmDialog;

package/dist/feedback/Dialog.svelte

@@ -0,0 +1,77 @@
+<!-- @component
+A modal on bits-ui’s `Dialog`, wearing daisyUI’s `modal-box`.
+-->
+<!--
+  Dialog — a modal on bits-ui's `Dialog`, wearing daisyUI's `modal-box`.
+
+  ARIA contract: everything that makes a modal a modal is bits-ui's — the
+  focus trap, the initial focus move, `aria-modal`, the `aria-labelledby` /
+  `aria-describedby` wiring to `Dialog.Title` and `Dialog.Description`,
+  Escape and outside-click dismissal, the scroll lock, and returning focus
+  to whatever opened it. None of that is re-implemented here, because the
+  hand-rolled version is the one that is always subtly wrong: the native
+  `<dialog>` the app repos used gets the trap right but leaves the title
+  wiring and the focus return to the call site, and every call site did it
+  differently.
+
+  `title` is required: a dialog with no accessible name is announced as
+  "dialog" and nothing else. `description` is optional but is what turns
+  "Delete garden?" into a sentence an assistive-technology user can act on.
+
+  `trigger` receives the props to spread, so an existing `Button` keeps its
+  own markup and its own accessible name; `actions` receives `close`, so the
+  action row's buttons can dismiss without reaching for the bindable `open`.
+-->
+<script lang="ts">import { X } from "@lucide/svelte";
+import { Dialog } from "bits-ui";
+import Button from "../ui/Button.svelte";
+import VisuallyHidden from "../ui/VisuallyHidden.svelte";
+import { dialogSize } from "./sizes.js";
+let { open = $bindable(false), title, description, closeLabel = "Close", size = "md", class: className, trigger, actions, children } = $props();
+const close = () => {
+	open = false;
+};
+</script>
+
+<Dialog.Root bind:open>
+  {#if trigger}
+    <Dialog.Trigger>
+      {#snippet child({ props })}
+        {@render trigger({ props })}
+      {/snippet}
+    </Dialog.Trigger>
+  {/if}
+  <Dialog.Portal>
+    <!-- daisyUI's `modal-backdrop` is a child of an open `.modal`; this is
+         the same scrim as an element bits-ui can animate and dismiss from. -->
+    <Dialog.Overlay class="bg-base-300/60 fixed inset-0 z-40" />
+    <Dialog.Content
+      class={[
+        'modal-box fixed top-1/2 left-1/2 z-50 max-h-[calc(100svh-2rem)] w-[calc(100vw-2rem)] -translate-x-1/2 -translate-y-1/2',
+        dialogSize[size],
+        className,
+      ]}
+    >
+      <div class="flex items-start justify-between gap-4">
+        <Dialog.Title class="text-lg font-semibold">{title}</Dialog.Title>
+        <Dialog.Close>
+          {#snippet child({ props })}
+            <Button {...props} variant="ghost" size="sm" class="btn-square -mt-1 -mr-1">
+              <X class="size-4" aria-hidden="true" />
+              <VisuallyHidden>{closeLabel}</VisuallyHidden>
+            </Button>
+          {/snippet}
+        </Dialog.Close>
+      </div>
+      {#if description !== undefined}
+        <Dialog.Description class="text-base-content/70 mt-1 text-sm leading-6">
+          {description}
+        </Dialog.Description>
+      {/if}
+      <div class="py-4">{@render children()}</div>
+      {#if actions}
+        <div class="modal-action">{@render actions({ close })}</div>
+      {/if}
+    </Dialog.Content>
+  </Dialog.Portal>
+</Dialog.Root>

package/dist/feedback/Dialog.svelte.d.ts

@@ -0,0 +1,37 @@
+import { Dialog } from 'bits-ui';
+import type { Snippet } from 'svelte';
+import { type DialogSize } from './sizes.ts';
+interface Props {
+    /** Whether the dialog is shown. Bindable. */
+    open?: boolean | undefined;
+    /** Heading — the dialog's accessible name. */
+    title: string;
+    /** Supporting line under the heading — the accessible description. */
+    description?: string | undefined;
+    /**
+     * Accessible name of the corner close button.
+     * @defaultValue `'Close'`
+     */
+    closeLabel?: string | undefined;
+    /**
+     * Width step of the `modal-box`.
+     * @defaultValue `'md'`
+     */
+    size?: DialogSize | undefined;
+    /** Extra classes on the `modal-box`. */
+    class?: string | undefined;
+    /** The opening control — the caller's own element, spreading `props`. */
+    trigger?: Snippet<[{
+        props: Record<string, unknown>;
+    }]> | undefined;
+    /** Buttons for the `modal-action` row. */
+    actions?: Snippet<[{
+        close: () => void;
+    }]> | undefined;
+    /** The dialog body, under the title and description. */
+    children: Snippet<[]>;
+}
+/** A modal on bits-ui’s `Dialog`, wearing daisyUI’s `modal-box`. */
+declare const Dialog: import("svelte").Component<Props, {}, "open">;
+type Dialog = ReturnType<typeof Dialog>;
+export default Dialog;