@poodle64/ui 2026.10.17 → 2026.10.18

package/README.md

@@ -47,22 +47,25 @@ src/lib/
 dist/                    generated by `pnpm build` (@sveltejs/package); never edit
 ```
 
-**Primitives** (26 — battle-tested implementations pulled from whichever app had
+**Primitives** (27 — battle-tested implementations pulled from whichever app had
 them first, not an invented "ideal" list): `alert`, `alert-dialog`, `avatar`,
 `badge`, `button`, `card`, `checkbox`, `command`, `data-table`, `dialog`,
 `dropdown-menu`, `input`, `input-group`, `label`, `password-input`, `popover`,
-`progress`, `select`, `separator`, `skeleton`, `sonner`, `switch`, `table`,
-`tabs`, `textarea`, `tooltip`.
+`progress`, `select`, `separator`, `sheet`, `skeleton`, `sonner`, `switch`,
+`table`, `tabs`, `textarea`, `tooltip`.
 
 `avatar` is root, image and fallback only; the group and badge variants in the
 upstream registry had no consumer in any surveyed app. It is here because
 `AppShell`'s `identity` slot needs one, and a consumer filling a slot the shell
 itself defines should not have to keep a private copy of a primitive to do it.
 
-Not yet included: `sheet` — no app's `ui/` has vendored it yet. Add it here
-(`pnpm dlx shadcn-svelte@latest add <name>` inside `packages/ui`, or hand-port from
-a sibling app once one adopts it) the first time a converging app actually needs it;
-do not invent it speculatively.
+`sheet` is shadcn's API (`Sheet.Root`, `Trigger`, `Content side=…`, `Header`,
+`Title`, `Description`, `Footer`, `Close`) plus `Sheet.Body`, the part that
+scrolls between a fixed header and footer. It is a panel over the page, for a
+task beside what you are reading (comments on a chapter, a cited record on a
+phone); it is never a second navigation column, which the shell has no slot
+for. It stands on the kit's hairline depth, not a shadow, and inside an
+element's `<Overlays>` it portals into the shadow root like the dialogue does.
 
 **Deliberately not here: `chart` and `form`.** Two apps keep local copies of each,
 and both stay local for reasons that are about coupling rather than effort.
@@ -89,7 +92,12 @@ rather than rebuilding it:
 
 | Import                                          | What it is                                                                                                                                                                                                                                                                                                                                                              |
 | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `page-header`                                   | The only page-title pattern: optional `breadcrumbs` and `icon` snippets, eyebrow, an optional title, one clamped subtitle, an `info` tooltip, a `meta` row and an `actions` slot. Omit `title` for a header that is a breadcrumb bar.                                                                                                                                   |
+| `page-header`                                   | The only page-title pattern: optional `breadcrumbs` (the trail's items, or a snippet) and `icon`, eyebrow, an optional title, one clamped subtitle, an `info` tooltip, a `meta` row and an `actions` slot. Omit `title` for a header that is a breadcrumb bar.                                                                                                                                   |
+| `breadcrumbs`                                   | The trail: `items` of `{ label, href? }`, a named landmark, chevrons, each step truncating rather than wrapping. PageHeader draws it from `breadcrumbs={[…]}`. See [The page](#the-page-container-sections-and-the-type-scale). |
+| `page-container`                                | A route's page at the one rhythm: header, sections and panels 1.5rem apart, filling the content box. |
+| `page-section`                                  | A section of a page: `title` at `level` 2 or 3, an optional `description`, `count` and `actions`, and its content at one distance below. |
+| `document-reader`                               | A document to read: PageHeader, the body (`html` the app sanitised, or `children`) in `.ds-prose` at the reading measure, and a contents list from its own headings. See [A document to read](#a-document-to-read). |
+| `content-skeleton`                              | A region loading, shaped like what replaces it: `rows`, `tiles` or `prose`. A whole page waiting is LoadingState. |
 | `panel`                                         | The generic titled card, and the settings section: optional icon, a clamped one-line `subtitle` or a wrapping `description`, trailing `action`s, a body that can opt out of padding or scroll inside the card (`scroll`), an optional `footer` strip for Save/Cancel, and `tone="destructive"` for a danger zone. There is no `SettingsSection`; see [The settings destination](#the-settings-destination). |
 | `list-toolbar`                                  | The bar above a list, on the page ground: title, count, icon actions named by their tooltips, one labelled action. The Ledger and the RecordList draw theirs with it. |
 | `record-list`                                   | The ledger's look for a list that is not money. See [Lists that are not money](#lists-that-are-not-money). |
@@ -534,9 +542,13 @@ Two things worth knowing before you set it:
   replaces. An app running `padded={false}` and its own page padding gets the cap
   flush, which is usually what it wanted.
 
-Set it in the layout, not the page. A page reaching for `measure` is the habit
-this replaces; a route group that genuinely differs (a docs section inside an
-app of dashboards) gets its own layout, which is where a shared decision belongs.
+A route declares it in its load data and the app's frame passes it on: the
+stamped frame renders `measure={page.data.measure ?? 'wide'}`, and a route group
+returns `{ measure: 'page' }` from its `+layout.ts`, one route from its
+`+page.ts`. Three apps had each written a table of path regexes mapping routes
+to tiers in their frame (22 rows in one); route data puts the decision on the
+route it belongs to, and SvelteKit merges a layout's answer into every page
+under it. `padded` travels the same way.
 
 #### A block inside the page: `.ds-measure`
 
@@ -562,6 +574,77 @@ paragraphs ~207px away from their own label. Both halves are gated in
 on the page's own left edge, and it follows a retune of
 `--ds-shell-measure-prose`.
 
+### The page: container, sections and the type scale
+
+```svelte
+<PageContainer>
+	<PageHeader
+		title="Allowances"
+		breadcrumbs={[{ label: 'Library', href: '/library' }, { label: 'Pay and conditions' }]}
+	/>
+	<PageSection title="Recently changed" count={4} description="Clauses amended this quarter.">
+		{#snippet actions()}<Button variant="outline" size="sm">Compare</Button>{/snippet}
+		<RecordList … />
+	</PageSection>
+</PageContainer>
+```
+
+A step with an `href` is a way back; the last step without one is where you are
+(`aria-current="page"`). The trail is a `<nav aria-label="Breadcrumb">`, which
+none of the three hand-written copies had.
+
+The type scale, by role. An app sets none of these; a route sets no size of its
+own and composes the component that owns the role:
+
+| Role | Utility | Size | Face | Owned by |
+| --- | --- | --- | --- | --- |
+| Page title | `text-display` | 1.75rem | display, semibold | PageHeader |
+| Section | `text-section` | 1.25rem | display, semibold | PageSection `level={2}` |
+| Panel title, subsection | `text-body` | 0.9375rem | body, semibold | Panel, PageSection `level={3}` |
+| Readout | `text-stat` | 1.0625rem | body | StatList |
+| Reading text | `text-base` | 1rem | body | DocumentReader |
+| Body | `text-sm` | 0.875rem | body | the default |
+| Facts, captions | `text-xs` | 0.75rem | body, muted | PageHeader `meta` |
+| Column head | `text-2xs`, uppercase, `tracking-eyebrow` | 0.6875rem | body, medium | tables, nav groups |
+
+PageSection has no uppercase-kicker form. One app had five recipes for a
+section heading, three of them small caps; small caps over content is a column
+head, and as a heading it is the generated-UI tell `eyebrow` warns about.
+
+### A document to read
+
+```svelte
+<DocumentReader
+	title={doc.title}
+	breadcrumbs={[{ label: 'Research notes', href: '/research' }, { label: doc.title }]}
+	html={sanitised}
+	{loading}
+	{error}
+	{onRetry}
+>
+	{#snippet meta()}<span>12 min read</span>{/snippet}
+	{#snippet footer()}<a href={next.href}>Next: {next.title}</a>{/snippet}
+</DocumentReader>
+```
+
+The body is the app's HTML, already sanitised, for the reason `.ds-prose` gives;
+strip the body's own leading `# Title`, since the header carries it. The
+contents list is the body's `h2` and `h3`, shown once there are two; a heading
+without an id gets one from its text. From a reader 64rem wide the list stands
+beside the body and stays in view; narrower, it folds into an "On this page"
+disclosure above it. That is a container query on the reader, so a route at
+`measure="page"` or wider shows it beside the body on a laptop. A link scrolls
+to its heading and moves focus there, without the URL fragment, which cannot
+reach into a shadow root.
+
+`aside` adds to that column, under the contents, and follows the body on a
+narrower reader: a library document's catalogue facts belong there, and
+DocumentDetail stays the record for a document with no body to read. The column
+is held while the body loads, so a structured document does not move sideways
+as it arrives; a body with fewer than two headings and no `aside` gives the room
+back. With a `title`, `loading` keeps the header and draws the body as a
+`prose` ContentSkeleton; without one it is LoadingState.
+
 ### The content texture
 
 The house atmosphere — a faint dot-grid floor with a soft accent vignette in the

package/dist/components/feedback/report-widget.svelte

@@ -33,10 +33,13 @@
 	let {
 		/** Where the report POSTs. The app's own route, defaulting to the one every household app serves. */
 		endpoint = '/api/feedback',
+		/** Who reads a report, as "the <team> team". The app's own name, never an internal one. */
+		team = 'support',
 		/** Fired with the id the endpoint returned, once, on the success leg. */
 		onSubmitted
 	}: {
 		endpoint?: string;
+		team?: string;
 		onSubmitted?: (id: string) => void;
 	} = $props();
 
@@ -129,7 +132,7 @@
 <AppDialog
 	bind:open
 	title="Report a problem"
-	subtitle="Describe what happened and the household team will take a look."
+	subtitle="Describe what happened and the {team} team will take a look."
 	size="sm"
 	onOpenChange={(next) => !next && reset()}
 >

package/dist/components/feedback/report-widget.svelte.d.ts

@@ -1,5 +1,6 @@
 type $$ComponentProps = {
     endpoint?: string;
+    team?: string;
     onSubmitted?: (id: string) => void;
 };
 declare const ReportWidget: import("svelte").Component<$$ComponentProps, {}, "">;

package/dist/components/ui/app-identity/app-identity.svelte

@@ -143,6 +143,11 @@
 		if (onSwitchTheme) onSwitchTheme();
 		else toggleMode();
 	}
+
+	// Each name once: the identity provider repeats a name for every binding
+	// that grants it, and a repeated key throws in the list below, which took
+	// one app's whole account menu down with it.
+	const held = $derived([...new Set(entitlements)]);
 </script>
 
 <DropdownMenu.Root>
@@ -193,9 +198,9 @@
 					</span>
 				{/if}
 			</div>
-			{#if entitlements.length}
+			{#if held.length}
 				<div class="flex flex-wrap gap-1 px-2 pb-2">
-					{#each entitlements as e (e)}
+					{#each held as e (e)}
 						<span class="bg-surface-2 text-muted-foreground font-mono rounded px-1.5 py-px text-[10px]">
 							{e}
 						</span>

package/dist/components/ui/app-shell/texture.d.ts

@@ -12,8 +12,8 @@
  * it is a coin toss with a stylesheet.
  *
  * So it moves onto the shell, where there is exactly one place to say it and no
- * per-route decision left to get wrong. `none` is the default, so a shell that
- * never mentions it renders byte-identically.
+ * per-route decision left to get wrong. `grid` is the default: an opt-in house
+ * style measured who remembered it, not what the house looks like.
  *
  * It is one texture, not a menu. Both apps wanted the same picture, and the
  * axes they actually differed on — how dark the dots are, how the vignette is
@@ -24,9 +24,9 @@
  * remains.
  */
 /**
- * - `grid` — the house atmosphere: a dot-grid floor plus a corner vignette.
- * - `none` — no texture. The default, so omitting `texture` changes nothing.
+ * - `grid` — the house atmosphere: a dot-grid floor plus a corner vignette. The default.
+ * - `none` — no texture: the region exactly as it rendered before the feature.
  */
 export type ShellTexture = 'none' | 'grid';
-/** Every texture, the untextured default first — the order it is documented in. */
+/** Every texture, the untextured form first — the order it is documented in. */
 export declare const SHELL_TEXTURES: readonly ["none", "grid"];

package/dist/components/ui/app-shell/texture.js

@@ -12,8 +12,8 @@
  * it is a coin toss with a stylesheet.
  *
  * So it moves onto the shell, where there is exactly one place to say it and no
- * per-route decision left to get wrong. `none` is the default, so a shell that
- * never mentions it renders byte-identically.
+ * per-route decision left to get wrong. `grid` is the default: an opt-in house
+ * style measured who remembered it, not what the house looks like.
  *
  * It is one texture, not a menu. Both apps wanted the same picture, and the
  * axes they actually differed on — how dark the dots are, how the vignette is
@@ -23,5 +23,5 @@
  * second name in this union: set the grid ink to `transparent` and the vignette
  * remains.
  */
-/** Every texture, the untextured default first — the order it is documented in. */
+/** Every texture, the untextured form first — the order it is documented in. */
 export const SHELL_TEXTURES = ['none', 'grid'];

package/dist/components/ui/breadcrumbs/breadcrumbs.svelte

@@ -0,0 +1,70 @@
+<script lang="ts" module>
+	/** One step of the trail. With `href` it is a way back; without, it is where you are. */
+	export type BreadcrumbItem = { label: string; href?: string };
+</script>
+
+<script lang="ts">
+	/**
+	 * Where you are, as a trail of the routes above it. Three apps had written
+	 * this by hand (one copy three times, one as a 28-call-site wrapper, one with
+	 * slash separators), and none named the landmark, so a screen reader met an
+	 * unlabelled list of links.
+	 *
+	 * The links are plain `<a href>`: SvelteKit routes them client-side, so a
+	 * package with no router of its own can still render the app's routes, as
+	 * AppNav does for `NavItem.href`.
+	 *
+	 * The trail never wraps. Each step truncates instead: an ancestor at 40% of
+	 * its container (the viewport when there is none) up to 32rem, and three
+	 * times as readily as where you are, so on a phone one long collection name
+	 * gives way while short steps and the current one stay whole, and on a
+	 * laptop it shows in full. Not a percentage: PageHeader's title column is
+	 * as wide as its content, so 40% of it would truncate at any width.
+	 */
+	import type { HTMLAttributes } from 'svelte/elements';
+	import ChevronRight from '@lucide/svelte/icons/chevron-right';
+	import { cn, type WithElementRef } from '../../../utils.js';
+
+	let {
+		items,
+		label = 'Breadcrumb',
+		ref = $bindable(null),
+		class: className,
+		...restProps
+	}: WithElementRef<HTMLAttributes<HTMLElement>> & {
+		items: BreadcrumbItem[];
+		/** The landmark's accessible name. */
+		label?: string;
+	} = $props();
+</script>
+
+<nav
+	bind:this={ref}
+	aria-label={label}
+	data-slot="breadcrumbs"
+	class={cn('text-muted-foreground min-w-0 text-sm', className)}
+	{...restProps}
+>
+	<ol class="flex min-w-0 items-center gap-1.5">
+		{#each items as item, i (i)}
+			{@const last = i === items.length - 1}
+			<li class={cn('flex min-w-0 items-center gap-1.5', !last && 'max-w-[min(40cqi,32rem)] shrink-[3]')}>
+				{#if i > 0}
+					<ChevronRight class="size-3.5 shrink-0 opacity-60" aria-hidden="true" />
+				{/if}
+				{#if item.href}
+					<a
+						href={item.href}
+						class="hover:text-foreground focus-visible:ring-ring/50 min-w-0 truncate rounded-sm underline-offset-4 outline-none hover:underline focus-visible:ring-3"
+						>{item.label}</a
+					>
+				{:else}
+					<span
+						class="text-foreground min-w-0 truncate"
+						aria-current={last ? 'page' : undefined}>{item.label}</span
+					>
+				{/if}
+			</li>
+		{/each}
+	</ol>
+</nav>

package/dist/components/ui/breadcrumbs/breadcrumbs.svelte.d.ts

@@ -0,0 +1,32 @@
+/** One step of the trail. With `href` it is a way back; without, it is where you are. */
+export type BreadcrumbItem = {
+    label: string;
+    href?: string;
+};
+/**
+     * Where you are, as a trail of the routes above it. Three apps had written
+     * this by hand (one copy three times, one as a 28-call-site wrapper, one with
+     * slash separators), and none named the landmark, so a screen reader met an
+     * unlabelled list of links.
+     *
+     * The links are plain `<a href>`: SvelteKit routes them client-side, so a
+     * package with no router of its own can still render the app's routes, as
+     * AppNav does for `NavItem.href`.
+     *
+     * The trail never wraps. Each step truncates instead: an ancestor at 40% of
+     * its container (the viewport when there is none) up to 32rem, and three
+     * times as readily as where you are, so on a phone one long collection name
+     * gives way while short steps and the current one stay whole, and on a
+     * laptop it shows in full. Not a percentage: PageHeader's title column is
+     * as wide as its content, so 40% of it would truncate at any width.
+     */
+import type { HTMLAttributes } from 'svelte/elements';
+import { type WithElementRef } from '../../../utils.js';
+type $$ComponentProps = WithElementRef<HTMLAttributes<HTMLElement>> & {
+    items: BreadcrumbItem[];
+    /** The landmark's accessible name. */
+    label?: string;
+};
+declare const Breadcrumbs: import("svelte").Component<$$ComponentProps, {}, "ref">;
+type Breadcrumbs = ReturnType<typeof Breadcrumbs>;
+export default Breadcrumbs;

package/dist/components/ui/breadcrumbs/index.d.ts

@@ -0,0 +1,2 @@
+export { default as Breadcrumbs, type BreadcrumbItem } from './breadcrumbs.svelte';
+export { default } from './breadcrumbs.svelte';

package/dist/components/ui/breadcrumbs/index.js

@@ -0,0 +1,2 @@
+export { default as Breadcrumbs } from './breadcrumbs.svelte';
+export { default } from './breadcrumbs.svelte';

package/dist/components/ui/content-skeleton/content-skeleton.svelte

@@ -0,0 +1,94 @@
+<script lang="ts" module>
+	export type ContentSkeletonShape = 'rows' | 'tiles' | 'prose';
+</script>
+
+<script lang="ts">
+	/**
+	 * A region of a page while its data loads, drawn in the shape of what will
+	 * replace it: `rows` for a RecordList or a table, `tiles` for StatCards or a
+	 * card grid, `prose` for a document body. The page renders its PageHeader
+	 * for real and this in place of the region; a whole page still waiting on
+	 * everything is LoadingState's (`sveltekit-ui-patterns.md` §Loading).
+	 *
+	 * Each shape is sized to the component it stands in for (a RecordList row is
+	 * 2.5rem of text in 0.625rem of padding, a StatCard a label, a display
+	 * figure and a line), so the swap moves nothing. One app had five sizes of
+	 * bare Skeleton box for this, none matching what loaded.
+	 */
+	import type { HTMLAttributes } from 'svelte/elements';
+	import { cn, type WithElementRef } from '../../../utils.js';
+	import Skeleton from '../skeleton/skeleton.svelte';
+
+	let {
+		shape = 'rows',
+		count,
+		label = 'Loading…',
+		ref = $bindable(null),
+		class: className,
+		...restProps
+	}: WithElementRef<HTMLAttributes<HTMLDivElement>> & {
+		shape?: ContentSkeletonShape;
+		/** Rows, tiles, or paragraphs. Defaults to 5, 4 and 3. */
+		count?: number;
+		/** What a screen reader hears while it stands. */
+		label?: string;
+	} = $props();
+
+	const n = $derived(count ?? { rows: 5, tiles: 4, prose: 3 }[shape]);
+	// Varied, but fixed: a skeleton that changed width on every render would
+	// read as motion.
+	const TITLE = ['w-2/5', 'w-3/5', 'w-1/2', 'w-2/3', 'w-1/3'];
+	const NOTE = ['w-1/4', 'w-1/3', 'w-1/5', 'w-2/5'];
+	const LAST_LINE = ['w-3/5', 'w-2/5', 'w-4/5'];
+</script>
+
+<div
+	bind:this={ref}
+	role="status"
+	aria-live="polite"
+	aria-busy="true"
+	data-slot="content-skeleton"
+	data-shape={shape}
+	class={cn('@container min-w-0', className)}
+	{...restProps}
+>
+	<span class="sr-only">{label}</span>
+	{#if shape === 'rows'}
+		<div class="bg-card border-border ds-edge divide-border divide-y rounded-lg border" aria-hidden="true">
+			{#each { length: n }, i (i)}
+				<div class="flex flex-col gap-1 px-3 py-2.5">
+					<div class="flex h-5 items-center">
+						<Skeleton class={cn('h-3.5', TITLE[i % TITLE.length])} />
+					</div>
+					<div class="flex h-4 items-center">
+						<Skeleton class={cn('h-3', NOTE[i % NOTE.length])} />
+					</div>
+				</div>
+			{/each}
+		</div>
+	{:else if shape === 'tiles'}
+		<div class="grid grid-cols-1 gap-4 @sm:grid-cols-2 @3xl:grid-cols-3 @5xl:grid-cols-4" aria-hidden="true">
+			{#each { length: n }, i (i)}
+				<div class="bg-card border-border ds-edge flex flex-col gap-1.5 rounded-lg border p-4">
+					<div class="flex h-4 items-center"><Skeleton class="h-2.5 w-1/3" /></div>
+					<div class="flex h-[2.125rem] items-center"><Skeleton class="h-6 w-1/2" /></div>
+					<div class="flex h-4 items-center">
+						<Skeleton class={cn('h-3', NOTE[i % NOTE.length])} />
+					</div>
+				</div>
+			{/each}
+		</div>
+	{:else}
+		<div class="ds-measure flex flex-col gap-5" data-measure="prose" aria-hidden="true">
+			{#each { length: n }, i (i)}
+				<div class="flex flex-col">
+					{#each { length: 4 }, line (line)}
+						<div class="flex h-6 items-center">
+							<Skeleton class={cn('h-3.5', line === 3 ? LAST_LINE[i % LAST_LINE.length] : 'w-full')} />
+						</div>
+					{/each}
+				</div>
+			{/each}
+		</div>
+	{/if}
+</div>

package/dist/components/ui/content-skeleton/content-skeleton.svelte.d.ts

@@ -0,0 +1,25 @@
+export type ContentSkeletonShape = 'rows' | 'tiles' | 'prose';
+/**
+     * A region of a page while its data loads, drawn in the shape of what will
+     * replace it: `rows` for a RecordList or a table, `tiles` for StatCards or a
+     * card grid, `prose` for a document body. The page renders its PageHeader
+     * for real and this in place of the region; a whole page still waiting on
+     * everything is LoadingState's (`sveltekit-ui-patterns.md` §Loading).
+     *
+     * Each shape is sized to the component it stands in for (a RecordList row is
+     * 2.5rem of text in 0.625rem of padding, a StatCard a label, a display
+     * figure and a line), so the swap moves nothing. One app had five sizes of
+     * bare Skeleton box for this, none matching what loaded.
+     */
+import type { HTMLAttributes } from 'svelte/elements';
+import { type WithElementRef } from '../../../utils.js';
+type $$ComponentProps = WithElementRef<HTMLAttributes<HTMLDivElement>> & {
+    shape?: ContentSkeletonShape;
+    /** Rows, tiles, or paragraphs. Defaults to 5, 4 and 3. */
+    count?: number;
+    /** What a screen reader hears while it stands. */
+    label?: string;
+};
+declare const ContentSkeleton: import("svelte").Component<$$ComponentProps, {}, "ref">;
+type ContentSkeleton = ReturnType<typeof ContentSkeleton>;
+export default ContentSkeleton;

package/dist/components/ui/content-skeleton/index.d.ts

@@ -0,0 +1,2 @@
+export { default as ContentSkeleton, type ContentSkeletonShape } from './content-skeleton.svelte';
+export { default } from './content-skeleton.svelte';

package/dist/components/ui/content-skeleton/index.js

@@ -0,0 +1,2 @@
+export { default as ContentSkeleton } from './content-skeleton.svelte';
+export { default } from './content-skeleton.svelte';