@dorsk/tsumikit 0.23.0 → 0.25.0

package/README.md

@@ -57,15 +57,91 @@ import { Button, Field, Input, Modal, ThemePicker } from '@dorsk/tsumikit';
 
 ## Theming
 
-- 17 themes ship (dark, light, sepia, **colorblind** — Okabe-Ito —, plus mocha,
-  dracula, nord, tokyonight, gruvbox, solarized, rosepine, onedark, everforest,
-  monokai, amoled, highcontrast).
-- A new theme = one entry in `THEMES` (`stores/theme.svelte.ts`) + one
-  `[data-theme="id"]` block in `variables.css`. Nothing else changes.
+- 23 themes ship (light, highcontrast, gruvboxlight, solarizedlight,
+  everforestlight, rosepinedawn, latte, nordlight, tokyoday, kanagawalotus,
+  sepia, dark, **colorblind** — Okabe-Ito —, mocha, dracula, nord, tokyonight,
+  gruvbox, solarized, rosepine, onedark, everforest, monokai, amoled).
 - `<ThemePicker />` and `<FontScalePicker />` wire the stores to the UI. Theme
   is persisted to `localStorage` and applied with no flash (head snippet in
   `app.html`) and updates the mobile `<meta name="theme-color">`.
 
+### Stylesheets
+
+`@dorsk/tsumikit/styles/app.css` is a shell over five files you can import
+individually, in this order:
+
+```css
+@import '@dorsk/tsumikit/styles/tokens.css';
+@import '@dorsk/tsumikit/styles/themes.css'; /* optional */
+@import '@dorsk/tsumikit/styles/reset.css';
+@import '@dorsk/tsumikit/styles/utilities.css';
+@import '@dorsk/tsumikit/styles/syntax.css';
+@import './brand.css';
+```
+
+| export | contents |
+| --- | --- |
+| `styles/tokens.css` | `:root` only — every token the kit reads (`--c-*` palette, `--bg`/`--text`/`--accent` aliases, type scale, spacing, radii, shadows, fonts, `--control-height`, …). Theme-less. |
+| `styles/themes.css` | the built-in `[data-theme="id"]` blocks, one per `THEMES` entry. |
+| `styles/reset.css` | reset + element defaults. |
+| `styles/utilities.css` | `.container`, `.stack`, `.row`, `.sr-only`, icon sizing, … |
+| `styles/syntax.css` | highlight.js / Prism class → `--syn-*` mapping. |
+
+`styles/variables.css` = `tokens.css` + `themes.css` (kept for compatibility).
+Nothing is wrapped in `@layer`: kit rules are unlayered so component-scoped
+styles cascade exactly as before, and a consumer stylesheet imported **after**
+the kit wins on source order at equal specificity. Do not put brand overrides
+inside a `@layer` of your own — layered rules lose to the kit's unlayered ones.
+
+### Your own theme, without vendoring
+
+```ts
+// +layout.ts (or any module that runs before first render)
+import { theme } from '@dorsk/tsumikit';
+theme.register({ id: 'kusaritoi', label: 'Kusaritoi', icon: '鎖', themeColor: '#2a2a2a', mode: 'dark' });
+theme.setDefault('kusaritoi');
+```
+
+```css
+/* brand.css — imported after the kit stylesheet(s) */
+@import url('https://fonts.googleapis.com/css2?family=JetBrains+Mono&display=swap');
+:root { --font-mono: 'JetBrains Mono', ui-monospace, monospace; }
+
+[data-theme='kusaritoi'] {
+  color-scheme: dark;
+  --c-bg: #2a2a2a;         --c-bg-elev: #323232;    --c-bg-elev-2: #3a3a3a;
+  --c-surface: #323232;    --c-border: #484848;     --c-border-strong: #585858;
+  --c-text: #e8e8e8;       --c-text-muted: #b0b0b0; --c-text-faint: #808080;
+  --c-accent: #5ac8c8;     --c-accent-ink: #0d1f1f; --c-accent-dim: #3a8a8a;
+  --c-blue: #5a9fd4;       --c-amber: #d9a543;      --c-red: #e06060;
+  --c-green: #6abf69;      --c-violet: #b48ef0;     --c-gold: #d9a543;
+  --c-teal: #5ac8c8;
+  --shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.4);
+  --shadow-md: 0 6px 20px rgba(0, 0, 0, 0.5);
+  --shadow-lg: 0 12px 40px rgba(0, 0, 0, 0.6);
+  --mach-bg-sl: 45% 24%;   --mach-fg-sl: 70% 82%;   --mach-border-sl: 45% 40%;
+}
+```
+
+Contract for a `[data-theme='x']` block: all nineteen `--c-*` palette tokens,
+`--shadow-sm|md|lg`, `--mach-bg-sl|fg-sl|border-sl`, and `color-scheme: light`
+for a light theme (`:root` defaults to dark, so dark themes may omit it).
+`--md-code-bg` is optional (derives from `--c-blue`). Everything else (`--bg`,
+`--text`, `--syn-*`, …) is an alias in `tokens.css` and follows automatically.
+
+- `theme.register(def | def[])` appends to `theme.all` (built-ins first); an
+  entry with a built-in `id` replaces that built-in. `icon` and `themeColor` are
+  optional. `ThemePicker` reads `theme.all`, so registered themes appear at once.
+- `theme.setDefault(id)` is the theme used when `localStorage` holds nothing
+  valid — set the same id as `data-theme` in your `app.html` so the no-flash
+  snippet and the store agree. A persisted id that only becomes valid after
+  `register()` is picked up as soon as it is registered.
+- Only the palette or only the fonts? Import `tokens.css` + your `brand.css`
+  and skip `themes.css`; or import the full `app.css` and override `:root`
+  tokens after it. Never copy the kit files.
+- Adding a built-in theme to the kit = one entry in `THEMES`
+  (`stores/theme.svelte.ts`) + one block in `styles/themes.css`.
+
 ## Components
 
 **Atoms:** Text, Heading, Button, Input, Textarea, Select, Switch, Checkbox,
@@ -78,7 +154,8 @@ any custom SVG).
 
 **Molecules:** Field, IconButton, SelectButton, Toggle, OptionButton, Modal,
 Popover, Menu, Tabs, RadioGroup, Tooltip, Accordion, CopyButton, FileButton,
-Dropzone, CodeBlock, Callout, EmptyState, Toaster, ThemePicker, FontScalePicker.
+Dropzone, CodeBlock, Callout, EmptyState, ConfirmModal, Pagination, Toaster,
+ThemePicker, FontScalePicker, SectionHeader, KeyValue, LoadMore.
 
 **Organisms:** DataTable (generic `<T>`, typed columns + cell snippets;
 `layout="fixed"` makes column widths authoritative, `Column.truncate` /
@@ -113,6 +190,32 @@ edge-to-edge sections — inside AppShell's main column use `size="none"` instea
 Children can bleed to the column edge with
 `margin-inline: calc(-1 * var(--container-gutter))`.
 
+### ResizablePanel
+
+Inline by default: `panel` shares the row with `children` on its `side`, drag the
+edge or use the arrow keys/Home/End on the separator, collapse it with the edge
+chevron; `width`/`minWidth`/`maxWidth` (px numbers or CSS lengths such as
+`'12rem'`) and `widthKey` persist the width. `mode="overlay"` turns it into a
+fixed non-modal drawer (`role="dialog"`) on the viewport edge: `bind:open`,
+`onclose` fires on Escape, scrim click or the edge control, `scrim={false}` drops
+the dim backdrop, `fullWidthBelow="960px"` makes the drawer span the viewport (no
+handle, no scrim) on small screens, and `clampToViewport` (default true) keeps a
+stored width inside a shrunken window. `children` is optional in overlay mode.
+
+```svelte
+<ResizablePanel mode="overlay" side="right" label="Conversation" bind:open
+  width={720} minWidth={360} maxWidth="90vw" widthKey="conv-w" fullWidthBelow="960px">
+  {#snippet panel()}…{/snippet}
+</ResizablePanel>
+```
+
+`Scrim` (`onclose`, `hideBelow`, `z`, `label`) is the drawer's backdrop atom,
+exported for custom overlays: click or Escape (document-level) calls `onclose`.
+`resizeHandle` is the shared drag action behind every grip: `use:resizeHandle={{
+side, min, max, step, onwidth, oncommit, onreset, onactive, measure }}` gives
+any element pointer-capture + rAF-coalesced dragging, arrow/Home/End keys and
+double-click reset; the width defaults to the element's parent box.
+
 ### Stacked distribution + legend
 
 `SegmentedProgress mode="stacked"` turns the bar into one shared track whose slice
@@ -153,6 +256,71 @@ is a live region — `role="status"`, or `role="alert"` when `tone="danger"`.
 </Callout>
 ```
 
+### Modal, ConfirmModal & Pagination
+
+`Modal` opens on mount by default; pass `bind:open` instead to keep it mounted
+and drive `showModal()`/`close()` from state (closing writes `open = false`).
+`tone="danger" | "warn" | "info"` adds a title glyph and a 3px top border;
+`busy` makes the body inert, shows a spinner by the title and disables Escape,
+backdrop and the close button. The `footer` snippet is a right-aligned flex row
+(`justify-content: flex-end; gap: var(--sp-2)`).
+
+`ConfirmModal` wraps it as a yes/no dialog: `title`, `message` (or `children`),
+`confirmLabel`/`cancelLabel`, `tone="primary" | "danger" | "warn"`, `busy`,
+`onconfirm`, `oncancel`. An async `onconfirm` keeps the dialog busy until it
+settles, closes only on success and shows a rejection's message (`role="alert"`)
+under the body. `Button` accepts `tone="danger"` as an alias of
+`variant="danger"` so the tone axis works alone.
+
+```svelte
+<ConfirmModal bind:open title="Delete library?" tone="danger" confirmLabel="Delete"
+  onconfirm={() => api.deleteLibrary(id)} />
+```
+
+`Pagination` renders `<nav aria-label>` with prev/next IconButtons, numbered
+pages (`aria-current="page"`), ellipses and an optional `showRange` readout.
+Page mode: `bind:page` + `pageCount`. Offset mode: `bind:offset` + `limit` +
+`total` (page and count are derived, `offset` is written back). `onchange(page)`,
+`siblings` (1), `showEdges` (true), `size="sm" | "md"`, `label`. Under 24rem of
+container width it collapses to prev / "3 / 12" / next.
+
+```svelte
+<Pagination bind:offset limit={20} total={412} showRange onchange={load} />
+```
+
+### SectionHeader, Card header/footer, KeyValue, LoadMore
+
+`SectionHeader` is the one "title + meta + right-aligned actions" row:
+`title` (or `label`), `level` 1–4 (default 2), `size`, `subtitle`, `icon`,
+`count` (faint tabular figure after the title), `tone`, `hue` (0–360 swatch
+chip), `uppercase` (eyebrow group label), `divider`, `sticky` (pins at
+`--sticky-offset` / `--header-h` and publishes `--section-header-h` on its
+parent), `collapsible` + `bind:open` (title becomes a disclosure button with
+`aria-expanded`; `children` render beneath while open), `actions` snippet.
+
+`Card` gains `header` / `footer` snippets rendered outside the padded body
+behind a divider, `title` / `subtitle` / `actions` sugar that renders a
+`SectionHeader` in the header slot, and `gap` to stack children as a flex
+column. A Card without any of these renders exactly as before.
+
+`KeyValue` renders `rows: { label, value: string | number | Snippet, mono?,
+tone?, hint? }[]` as a semantic `<dl>` grid; `columns` 1 | 2, `dense`, `align`
+start | end. `LoadMore` is the tri-state list footer: `state` idle | loading |
+error | done, `onload`, `label`, `loadingLabel`, `errorLabel`, `retryLabel`,
+`doneLabel`, `pill` for the compact "load older" chip.
+
+```svelte
+<Card title="Recent sessions" subtitle="last 24h">
+  {#snippet actions()}<Link href="/sessions">View all</Link>{/snippet}
+  <KeyValue rows={[{ label: 'Running', value: 3, tone: 'ok' }, { label: 'Host', value: 'sakura', mono: true }]} />
+  {#snippet footer()}<LoadMore state={more} onload={loadMore} />{/snippet}
+</Card>
+
+<SectionHeader label="Blocked" count={4} uppercase hue={12} collapsible bind:open>
+  …group rows…
+</SectionHeader>
+```
+
 ## Container queries
 
 AppShell's `main` and `sidebar` are query containers (`container-name: main` /

package/dist/components/atoms/Button.svelte

@@ -112,7 +112,7 @@
 	class:btn-grow={grow}
 	class:btn-primary={variant === 'primary'}
 	class:btn-ghost={variant === 'ghost'}
-	class:btn-danger={variant === 'danger'}
+	class:btn-danger={variant === 'danger' || (tone === 'danger' && variant === 'default')}
 	class:btn-sm={size === 'sm'}
 	class:btn-lg={size === 'lg'}
 	class:btn-control={control}

package/dist/components/atoms/Card.svelte

@@ -13,7 +13,12 @@
 	// keeps them on the plain border colour. `stackY`/`stackX` set the per-layer
 	// vertical / horizontal offset in px (vertical spacing stays even across the
 	// 3 borders); horizontal defaults to a tiny 2px peek.
+	//
+	// `header`/`footer` snippets (or the `title`/`subtitle`/`actions` sugar,
+	// which renders a SectionHeader) sit outside the padded body behind a
+	// divider; `gap` stacks children as a flex column without a wrapper.
 	import type { Snippet } from 'svelte';
+	import SectionHeader from '../molecules/SectionHeader.svelte';
 
 	type Tone = 'neutral' | 'ok' | 'warn' | 'danger' | 'info';
 
@@ -27,8 +32,14 @@
 		stackTone = 'neutral',
 		stackY = 8,
 		stackX = 2,
+		title,
+		subtitle,
+		gap,
 		class: klass = '',
 		style = '',
+		header,
+		footer,
+		actions,
 		children,
 		...rest
 	}: {
@@ -41,8 +52,14 @@
 		stackTone?: Tone;
 		stackY?: number;
 		stackX?: number;
+		title?: string;
+		subtitle?: string;
+		gap?: string;
 		class?: string;
 		style?: string;
+		header?: Snippet;
+		footer?: Snippet;
+		actions?: Snippet;
 		children?: Snippet;
 		[key: string]: unknown;
 	} = $props();
@@ -50,6 +67,7 @@
 	let stackStyle = $derived(
 		stacked ? `--stack-y:${stackY}px;--stack-x:${stackX}px;` : ''
 	);
+	const framed = $derived(!!(header || footer || title));
 </script>
 
 <svelte:element
@@ -71,18 +89,55 @@
 	class:stack-warn={stacked && stackTone === 'warn'}
 	class:stack-danger={stacked && stackTone === 'danger'}
 	class:stack-info={stacked && stackTone === 'info'}
+	class:card-framed={framed}
+	class:card-gap={!framed && gap !== undefined}
+	style:--card-gap={gap}
 	style={`${stackStyle}${style}`}
 	{...rest}
 >
-	{@render children?.()}
+	{#if framed}
+		{#if title}
+			<div class="card-head">
+				<SectionHeader {title} {subtitle} {actions} level={3} size="md" />
+			</div>
+		{:else if header}
+			<div class="card-head">{@render header()}</div>
+		{/if}
+		<div class="card-body" class:card-gap={gap !== undefined}>{@render children?.()}</div>
+		{#if footer}
+			<div class="card-foot">{@render footer()}</div>
+		{/if}
+	{:else}
+		{@render children?.()}
+	{/if}
 </svelte:element>
 
 <style>
 	.card {
+		--card-pad: var(--sp-4);
 		background: var(--bg-elevated);
 		border: 1px solid var(--border);
 		border-radius: var(--r-lg);
-		padding: var(--sp-4);
+		padding: var(--card-pad);
+	}
+	.card-gap {
+		display: flex;
+		flex-direction: column;
+		gap: var(--card-gap);
+	}
+	.card-framed {
+		padding: 0;
+	}
+	.card-head,
+	.card-body,
+	.card-foot {
+		padding: var(--card-pad);
+	}
+	.card-head {
+		border-bottom: 1px solid var(--border);
+	}
+	.card-foot {
+		border-top: 1px solid var(--border);
 	}
 	/* Theme-aware surface shade, selected by prop so it adapts across themes
 	   instead of being overridden with app-level :global hacks. `base` is the
@@ -94,14 +149,22 @@
 		background: var(--bg-elevated-2);
 	}
 	.pad-none {
+		--card-pad: 0;
 		padding: 0;
 	}
 	.pad-sm {
+		--card-pad: var(--sp-2);
 		padding: var(--sp-2);
 	}
 	.pad-lg {
+		--card-pad: var(--sp-6);
 		padding: var(--sp-6);
 	}
+	.card-framed.pad-none,
+	.card-framed.pad-sm,
+	.card-framed.pad-lg {
+		padding: 0;
+	}
 	.card-tap {
 		cursor: pointer;
 		transition:

package/dist/components/atoms/Card.svelte.d.ts

@@ -10,8 +10,14 @@ type $$ComponentProps = {
     stackTone?: Tone;
     stackY?: number;
     stackX?: number;
+    title?: string;
+    subtitle?: string;
+    gap?: string;
     class?: string;
     style?: string;
+    header?: Snippet;
+    footer?: Snippet;
+    actions?: Snippet;
     children?: Snippet;
     [key: string]: unknown;
 };

package/dist/components/atoms/Scrim.svelte

@@ -0,0 +1,81 @@
+<script lang="ts">
+	import { browser } from '../../env';
+
+	let {
+		onclose,
+		hideBelow,
+		z = 'var(--z-drawer)',
+		label = 'Close'
+	}: {
+		/** Called on click anywhere on the scrim and on Escape (document-level). */
+		onclose?: () => void;
+		/** Viewport width (CSS length) under which the scrim is not rendered,
+		 *  for overlays that go full-bleed on small screens. */
+		hideBelow?: string;
+		/** z-index; defaults to the drawer layer. */
+		z?: string | number;
+		/** Accessible name of the click target. */
+		label?: string;
+	} = $props();
+
+	let hidden = $state(false);
+
+	$effect(() => {
+		if (!browser || !hideBelow) {
+			hidden = false;
+			return;
+		}
+		const query = matchMedia(`(max-width: ${hideBelow})`);
+		const sync = () => {
+			hidden = query.matches;
+		};
+		sync();
+		query.addEventListener('change', sync);
+		return () => query.removeEventListener('change', sync);
+	});
+
+	$effect(() => {
+		if (!browser) return;
+		const onKeydown = (event: KeyboardEvent) => {
+			if (event.key !== 'Escape' || event.defaultPrevented) return;
+			event.preventDefault();
+			onclose?.();
+		};
+		document.addEventListener('keydown', onKeydown);
+		return () => document.removeEventListener('keydown', onKeydown);
+	});
+</script>
+
+{#if !hidden}
+	<button
+		type="button"
+		class="scrim"
+		style:z-index={z}
+		aria-label={label}
+		tabindex="-1"
+		onclick={() => onclose?.()}
+		data-tsu="Scrim"
+	></button>
+{/if}
+
+<style>
+	.scrim {
+		position: fixed;
+		inset: 0;
+		padding: 0;
+		border: 0;
+		background: color-mix(in srgb, var(--bg) 45%, transparent);
+		cursor: default;
+		animation: scrim-fade 0.18s var(--ease);
+	}
+	@keyframes scrim-fade {
+		from {
+			opacity: 0;
+		}
+	}
+	@media (prefers-reduced-motion: reduce) {
+		.scrim {
+			animation: none;
+		}
+	}
+</style>

package/dist/components/atoms/Scrim.svelte.d.ts

@@ -0,0 +1,14 @@
+type $$ComponentProps = {
+    /** Called on click anywhere on the scrim and on Escape (document-level). */
+    onclose?: () => void;
+    /** Viewport width (CSS length) under which the scrim is not rendered,
+     *  for overlays that go full-bleed on small screens. */
+    hideBelow?: string;
+    /** z-index; defaults to the drawer layer. */
+    z?: string | number;
+    /** Accessible name of the click target. */
+    label?: string;
+};
+declare const Scrim: import("svelte").Component<$$ComponentProps, {}, "">;
+type Scrim = ReturnType<typeof Scrim>;
+export default Scrim;