@dryui/ui 0.1.12 → 0.2.0

package/dist/index.js

@@ -74,6 +74,7 @@ export { DatePicker } from './date-picker/index.js';
 export { Calendar } from './calendar/index.js';
 export { DateRangePicker } from './date-range-picker/index.js';
 export { Listbox } from './listbox/index.js';
+export { LogoMark } from './logo-mark/index.js';
 export { PinInput } from './pin-input/index.js';
 export { RangeCalendar } from './range-calendar/index.js';
 export { Rating } from './rating/index.js';

package/dist/logo-mark/index.d.ts

@@ -0,0 +1,10 @@
+import type { HTMLAttributes } from 'svelte/elements';
+export interface LogoMarkProps extends HTMLAttributes<HTMLSpanElement> {
+    src?: string;
+    alt?: string;
+    fallback?: string;
+    size?: 'sm' | 'md' | 'lg';
+    shape?: 'square' | 'rounded' | 'circle';
+    color?: 'brand' | 'neutral' | 'error' | 'warning' | 'success' | 'info';
+}
+export { default as LogoMark } from './logo-mark.svelte';

package/dist/logo-mark/index.js

@@ -0,0 +1 @@
+export { default as LogoMark } from './logo-mark.svelte';

package/dist/logo-mark/logo-mark.svelte

@@ -0,0 +1,154 @@
+<script lang="ts">
+	import type { HTMLAttributes } from 'svelte/elements';
+
+	interface Props extends HTMLAttributes<HTMLSpanElement> {
+		src?: string;
+		alt?: string;
+		fallback?: string;
+		size?: 'sm' | 'md' | 'lg';
+		shape?: 'square' | 'rounded' | 'circle';
+		color?: 'brand' | 'neutral' | 'error' | 'warning' | 'success' | 'info';
+	}
+
+	let {
+		src,
+		alt = '',
+		fallback,
+		size = 'md',
+		shape = 'rounded',
+		color = 'neutral',
+		class: className,
+		...rest
+	}: Props = $props();
+
+	let failedSrc = $state<string | null>(null);
+	const showImage = $derived(Boolean(src) && src !== failedSrc);
+
+	function handleError() {
+		failedSrc = src ?? null;
+	}
+
+	function getFallbackText(): string {
+		const source = (fallback ?? alt).trim();
+		if (!source) return '';
+
+		const compact = source.replace(/[^\p{L}\p{N}]+/gu, '');
+		const characters = Array.from(compact || source);
+		return characters.slice(0, 2).join('').toUpperCase();
+	}
+</script>
+
+<span
+	role="img"
+	aria-label={alt}
+	data-logo-mark
+	data-size={size}
+	data-shape={shape}
+	data-color={color}
+	class={className}
+	{...rest}
+>
+	{#if showImage}
+		<img {src} {alt} onerror={handleError} />
+	{:else}
+		<span aria-hidden="true">{getFallbackText()}</span>
+	{/if}
+</span>
+
+<style>
+	[data-logo-mark] {
+		--dry-logo-mark-size: 32px;
+		--dry-logo-mark-radius: var(--dry-radius-md);
+		--dry-logo-mark-bg: var(--dry-color-fill);
+		--dry-logo-mark-color: var(--dry-color-text-weak);
+
+		display: inline-grid;
+		place-items: center;
+		aspect-ratio: 1;
+		height: var(--dry-logo-mark-size);
+		border-radius: var(--dry-logo-mark-radius);
+		background: var(--dry-logo-mark-bg);
+		color: var(--dry-logo-mark-color);
+		font-family: var(--dry-font-sans);
+		font-size: var(--dry-logo-mark-font-size, var(--dry-type-small-size, var(--dry-text-sm-size)));
+		font-weight: 600;
+		line-height: 1;
+		overflow: hidden;
+		user-select: none;
+	}
+
+	[data-logo-mark] img {
+		width: 100%;
+		height: 100%;
+		object-fit: cover;
+		border-radius: inherit;
+	}
+
+	[data-logo-mark] > span {
+		display: grid;
+		place-items: center;
+	}
+
+	/* -- Shapes ------------------------------------------------------------- */
+
+	[data-shape='square'] {
+		--dry-logo-mark-radius: var(--dry-radius-sm);
+	}
+
+	[data-shape='rounded'] {
+		--dry-logo-mark-radius: var(--dry-radius-md);
+	}
+
+	[data-shape='circle'] {
+		--dry-logo-mark-radius: var(--dry-radius-full);
+	}
+
+	/* -- Sizes -------------------------------------------------------------- */
+
+	[data-size='sm'] {
+		--dry-logo-mark-size: 24px;
+		--dry-logo-mark-font-size: var(--dry-type-tiny-size, var(--dry-text-xs-size));
+	}
+
+	[data-size='md'] {
+		--dry-logo-mark-size: 32px;
+		--dry-logo-mark-font-size: var(--dry-type-small-size, var(--dry-text-sm-size));
+	}
+
+	[data-size='lg'] {
+		--dry-logo-mark-size: 40px;
+		--dry-logo-mark-font-size: var(--dry-type-small-size, var(--dry-text-base-size));
+	}
+
+	/* -- Colors ------------------------------------------------------------- */
+
+	[data-color='neutral'] {
+		--dry-logo-mark-bg: var(--dry-color-fill);
+		--dry-logo-mark-color: var(--dry-color-text-weak);
+	}
+
+	[data-color='brand'] {
+		--dry-logo-mark-bg: var(--dry-color-fill-brand-weak);
+		--dry-logo-mark-color: var(--dry-color-text-brand);
+	}
+
+	[data-color='error'] {
+		--dry-logo-mark-bg: var(--dry-color-fill-error-weak);
+		--dry-logo-mark-color: var(--dry-color-text-error);
+	}
+
+	[data-color='warning'] {
+		--dry-logo-mark-bg: var(--dry-color-fill-warning-weak);
+		--dry-logo-mark-color: var(--dry-color-text-warning);
+	}
+
+	[data-color='success'] {
+		--dry-logo-mark-bg: var(--dry-color-fill-success-weak);
+		--dry-logo-mark-color: var(--dry-color-text-success);
+	}
+
+	[data-color='info'] {
+		--dry-logo-mark-bg: var(--dry-color-fill-info-weak);
+		--dry-logo-mark-color: var(--dry-color-text-info);
+	}
+</style>

package/dist/logo-mark/logo-mark.svelte.d.ts

@@ -0,0 +1,12 @@
+import type { HTMLAttributes } from 'svelte/elements';
+interface Props extends HTMLAttributes<HTMLSpanElement> {
+    src?: string;
+    alt?: string;
+    fallback?: string;
+    size?: 'sm' | 'md' | 'lg';
+    shape?: 'square' | 'rounded' | 'circle';
+    color?: 'brand' | 'neutral' | 'error' | 'warning' | 'success' | 'info';
+}
+declare const LogoMark: import("svelte").Component<Props, {}, "">;
+type LogoMark = ReturnType<typeof LogoMark>;
+export default LogoMark;

package/dist/map/map-marker.svelte

@@ -1,6 +1,6 @@
 <script lang="ts">
 	import type { Snippet } from 'svelte';
-	import { onDestroy } from 'svelte';
+	import { onDestroy, untrack } from 'svelte';
 	import { getMapCtx, setMarkerCtx } from './context.svelte.js';
 	import type { LngLat, MapMarkerInstance, MarkerOptions } from '@dryui/primitives';
 
@@ -30,9 +30,10 @@
 	$effect(() => {
 		if (!ctx.loaded || !ctx.map || !ctx.lib) return;
 
-		if (markerInstance) {
-			markerInstance.remove();
-			markerInstance = null;
+		// Remove previous marker without tracking markerInstance as a dependency
+		const prev = untrack(() => markerInstance);
+		if (prev) {
+			prev.remove();
 		}
 
 		const opts: MarkerOptions = {};

package/dist/map/map-popup.svelte

@@ -1,6 +1,6 @@
 <script lang="ts">
 	import type { Snippet } from 'svelte';
-	import { onDestroy } from 'svelte';
+	import { onDestroy, untrack } from 'svelte';
 	import { getMapCtx, getMarkerCtx } from './context.svelte.js';
 	import type { MapPopupInstance, PopupOptions } from '@dryui/primitives';
 
@@ -29,9 +29,10 @@
 	$effect(() => {
 		if (!mapCtx.loaded || !mapCtx.map || !mapCtx.lib || !markerCtx.marker || !contentEl) return;
 
-		if (popupInstance) {
-			popupInstance.remove();
-			popupInstance = null;
+		// Remove previous popup without tracking popupInstance as a dependency
+		const prev = untrack(() => popupInstance);
+		if (prev) {
+			prev.remove();
 		}
 
 		try {

package/dist/pin-input/pin-input-root.svelte

@@ -47,11 +47,10 @@
 	const isDisabled = $derived(disabled || formCtx?.disabled || false);
 	const hasError = $derived(formCtx?.hasError || false);
 
-	let inputEl: HTMLInputElement | undefined = $state();
+	let inputEl: HTMLInputElement | undefined;
 	let isFocused = $state(false);
 	let mirrorSelectionStart = $state<number | null>(null);
 	let mirrorSelectionEnd = $state<number | null>(null);
-	let completeFired = $state(false);
 
 	const validationRegex = $derived(pattern ?? (type === 'numeric' ? /^\d+$/ : /^[a-zA-Z0-9]+$/));
 
@@ -98,24 +97,28 @@
 		mirrorSelectionEnd = inputEl.selectionEnd;
 	}
 
-	$effect(() => {
-		const handler = () => {
-			if (document.activeElement === inputEl) {
-				syncSelection();
+	function captureInput(node: HTMLInputElement) {
+		inputEl = node;
+		return () => {
+			if (inputEl === node) {
+				inputEl = undefined;
 			}
 		};
-		document.addEventListener('selectionchange', handler);
-		return () => document.removeEventListener('selectionchange', handler);
-	});
+	}
 
-	$effect(() => {
-		if (value.length < length) {
-			completeFired = false;
+	function maybeFireComplete(previousValue: string, nextValue: string) {
+		if (nextValue.length !== length) return;
+		if (previousValue.length === length && previousValue === nextValue) return;
+
+		oncomplete?.(nextValue);
+		if (blurOnComplete) {
+			inputEl?.blur();
 		}
-	});
+	}
 
 	function handleInput(e: Event) {
 		const input = e.target as HTMLInputElement;
+		const previousValue = value;
 		let newValue = input.value;
 
 		newValue = newValue
@@ -126,18 +129,12 @@
 		newValue = newValue.slice(0, length);
 		value = newValue;
 		syncSelection();
-
-		if (newValue.length === length && !completeFired) {
-			completeFired = true;
-			oncomplete?.(newValue);
-			if (blurOnComplete) {
-				inputEl?.blur();
-			}
-		}
+		maybeFireComplete(previousValue, newValue);
 	}
 
 	function handlePaste(e: ClipboardEvent) {
 		e.preventDefault();
+		const previousValue = value;
 		let pasted = e.clipboardData?.getData('text') ?? '';
 		if (pasteTransformer) {
 			pasted = pasteTransformer(pasted);
@@ -166,13 +163,7 @@
 			syncSelection();
 		});
 
-		if (newValue.length === length && !completeFired) {
-			completeFired = true;
-			oncomplete?.(newValue);
-			if (blurOnComplete) {
-				inputEl?.blur();
-			}
-		}
+		maybeFireComplete(previousValue, newValue);
 	}
 
 	function handleFocus() {
@@ -212,13 +203,10 @@
 	const sizeAttr = $derived(`data-pin-input-${size}`);
 </script>
 
-<!-- svelte-ignore a11y_role_supports_aria_props -->
 <div
 	role="group"
 	aria-label="PIN input"
 	aria-describedby={formCtx?.describedBy}
-	aria-invalid={hasError || undefined}
-	aria-errormessage={formCtx?.errorMessageId}
 	data-pin-input-root
 	data-disabled={isDisabled || undefined}
 	data-error={hasError || undefined}
@@ -230,7 +218,7 @@
 	{...rest}
 >
 	<input
-		bind:this={inputEl}
+		{@attach captureInput}
 		type="text"
 		inputmode={type === 'numeric' ? 'numeric' : 'text'}
 		autocomplete="one-time-code"
@@ -238,6 +226,9 @@
 		{value}
 		id={formCtx?.id}
 		aria-label="PIN input"
+		aria-describedby={formCtx?.describedBy}
+		aria-invalid={hasError || undefined}
+		aria-errormessage={formCtx?.errorMessageId}
 		aria-required={formCtx?.required || undefined}
 		disabled={isDisabled}
 		spellcheck={false}
@@ -247,6 +238,8 @@
 		onfocus={handleFocus}
 		onblur={handleBlur}
 		onkeydown={handleKeydown}
+		onkeyup={syncSelection}
+		onselect={syncSelection}
 	/>
 
 	{#if userChildren}

package/dist/select/select-root.svelte

@@ -2,6 +2,12 @@
 	import type { Snippet } from 'svelte';
 	import { generateFormId } from '@dryui/primitives';
 	import { setSelectCtx } from './context.svelte.js';
+	import SelectTrigger from './select-trigger.svelte';
+	import SelectValue from './select-value.svelte';
+	import SelectContent from './select-content.svelte';
+	import SelectItem from './select-item.svelte';
+
+	type SelectOption = { value: string; label: string };
 
 	interface Props {
 		open?: boolean;
@@ -9,7 +15,9 @@
 		disabled?: boolean;
 		name?: string;
 		class?: string;
-		children: Snippet;
+		options?: Array<string | SelectOption>;
+		placeholder?: string;
+		children?: Snippet;
 	}
 
 	let {
@@ -18,9 +26,15 @@
 		disabled = false,
 		name,
 		class: className,
+		options,
+		placeholder,
 		children
 	}: Props = $props();
 
+	const normalizedOptions = $derived(
+		options?.map((opt) => (typeof opt === 'string' ? { value: opt, label: opt } : opt))
+	);
+
 	const triggerId = generateFormId('select-trigger');
 	const contentId = generateFormId('select-content');
 
@@ -59,7 +73,18 @@
 </script>
 
 <div data-select-wrapper class={className}>
-	{@render children()}
+	{#if normalizedOptions && !children}
+		<SelectTrigger>
+			<SelectValue {placeholder} />
+		</SelectTrigger>
+		<SelectContent>
+			{#each normalizedOptions as opt (opt.value)}
+				<SelectItem value={opt.value}>{opt.label}</SelectItem>
+			{/each}
+		</SelectContent>
+	{:else if children}
+		{@render children()}
+	{/if}
 
 	{#if name}
 		<input type="hidden" {name} {value} disabled={disabled || undefined} />

package/dist/select/select-root.svelte.d.ts

@@ -5,7 +5,9 @@ interface Props {
 	disabled?: boolean;
 	name?: string;
 	class?: string;
-	children: Snippet;
+	options?: Array<string | { value: string; label: string }>;
+	placeholder?: string;
+	children?: Snippet;
 }
 declare const SelectRoot: import('svelte').Component<Props, {}, 'value' | 'open'>;
 type SelectRoot = ReturnType<typeof SelectRoot>;

package/dist/time-input/time-input.svelte

@@ -1,8 +1,12 @@
 <script lang="ts">
-	import { untrack } from 'svelte';
 	import { getFormControlCtx } from '@dryui/primitives';
 	import { Select } from '../select/index.js';
 
+	type TimeParts = {
+		hour: string;
+		minute: string;
+	};
+
 	interface Props {
 		value?: string;
 		disabled?: boolean;
@@ -23,43 +27,46 @@
 
 	const ctx = getFormControlCtx();
 	const isDisabled = $derived(disabled || ctx?.disabled || false);
+	const hasError = $derived(ctx?.hasError || false);
+	const describedBy = $derived(ctx?.describedBy);
+	const errorMessageId = $derived(ctx?.hasError ? ctx?.errorMessageId : undefined);
 
-	let hourStr = $state('');
-	let minuteStr = $state('');
-	let updating = false;
-
-	// Parse incoming value into hour/minute (only reacts to value changes)
-	$effect(() => {
-		if (updating) return;
-		const parts = value.split(':');
-		const h = parts[0] ?? '';
-		const m = parts[1] ?? '';
-		untrack(() => {
-			if (h !== hourStr) hourStr = h;
-			if (m !== minuteStr) minuteStr = m;
-		});
-	});
+	function parseTime(nextValue: string): TimeParts {
+		const [hour = '', minute = ''] = nextValue.split(':');
+		return { hour, minute };
+	}
+
+	let draftHour = $state('');
+	let draftMinute = $state('');
 
-	// Reconstruct value when selects change (only reacts to hourStr/minuteStr)
-	$effect(() => {
-		const h = hourStr;
-		const m = minuteStr;
-		if (h && m) {
-			const newVal = `${h}:${m}`;
-			untrack(() => {
-				if (newVal !== value) {
-					updating = true;
-					value = newVal;
-					updating = false;
-				}
-			});
+	const parsedValue = $derived.by(() => parseTime(value));
+	const hourStr = $derived(value ? parsedValue.hour : draftHour);
+	const minuteStr = $derived(value ? parsedValue.minute : draftMinute);
+
+	function setTime(nextHour: string, nextMinute: string) {
+		draftHour = nextHour;
+		draftMinute = nextMinute;
+
+		if (nextHour && nextMinute) {
+			value = `${nextHour}:${nextMinute}`;
+			draftHour = '';
+			draftMinute = '';
+			return;
 		}
-	});
 
-	// Generate hour options 00-23
+		value = '';
+	}
+
+	function setHour(nextHour: string) {
+		setTime(nextHour, minuteStr);
+	}
+
+	function setMinute(nextMinute: string) {
+		setTime(hourStr, nextMinute);
+	}
+
 	const hours = Array.from({ length: 24 }, (_, i) => String(i).padStart(2, '0'));
 
-	// Generate minute options based on step
 	const minutes = $derived.by(() => {
 		const stepMinutes = step && step >= 60 ? Math.floor(step / 60) : 1;
 		const count = Math.floor(60 / stepMinutes);
@@ -75,12 +82,16 @@
 	data-time-input-wrapper
 	data-disabled={isDisabled || undefined}
 	id={ctx?.id}
-	aria-describedby={[ctx?.describedBy, ctx?.hasError ? ctx?.errorMessageId : undefined].filter(Boolean).join(' ') || undefined}
-	aria-invalid={ctx?.hasError || undefined}
 	class={className}
 >
-	<Select.Root bind:value={hourStr} disabled={isDisabled}>
-		<Select.Trigger {size} aria-label="Hour">
+	<Select.Root bind:value={() => hourStr, setHour} disabled={isDisabled}>
+		<Select.Trigger
+			{size}
+			aria-label="Hour"
+			aria-describedby={describedBy}
+			aria-invalid={hasError || undefined}
+			aria-errormessage={errorMessageId}
+		>
 			<span data-time-display data-placeholder={!hourStr ? '' : undefined}>
 				{hourStr || 'HH'}
 			</span>
@@ -94,8 +105,14 @@
 
 	<span data-time-separator>:</span>
 
-	<Select.Root bind:value={minuteStr} disabled={isDisabled}>
-		<Select.Trigger {size} aria-label="Minute">
+	<Select.Root bind:value={() => minuteStr, setMinute} disabled={isDisabled}>
+		<Select.Trigger
+			{size}
+			aria-label="Minute"
+			aria-describedby={describedBy}
+			aria-invalid={hasError || undefined}
+			aria-errormessage={errorMessageId}
+		>
 			<span data-time-display data-placeholder={!minuteStr ? '' : undefined}>
 				{minuteStr || 'MM'}
 			</span>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dryui/ui",
-  "version": "0.1.12",
+  "version": "0.2.0",
   "author": "Rob Balfre",
   "license": "MIT",
   "repository": {
@@ -401,6 +401,11 @@
       "svelte": "./dist/listbox/index.js",
       "default": "./dist/listbox/index.js"
     },
+    "./logo-mark": {
+      "types": "./dist/logo-mark/index.d.ts",
+      "svelte": "./dist/logo-mark/index.js",
+      "default": "./dist/logo-mark/index.js"
+    },
     "./map": {
       "types": "./dist/map/index.d.ts",
       "svelte": "./dist/map/index.js",
@@ -1141,6 +1146,11 @@
         "svelte": "./dist/listbox/index.js",
         "default": "./dist/listbox/index.js"
       },
+      "./logo-mark": {
+        "types": "./dist/logo-mark/index.d.ts",
+        "svelte": "./dist/logo-mark/index.js",
+        "default": "./dist/logo-mark/index.js"
+      },
       "./map": {
         "types": "./dist/map/index.d.ts",
         "svelte": "./dist/map/index.js",
@@ -1504,7 +1514,7 @@
     "thumbnail:create": "bun scripts/create-thumbnail.ts"
   },
   "dependencies": {
-    "@dryui/primitives": "^0.1.12"
+    "@dryui/primitives": "^0.2.0"
   },
   "peerDependencies": {
     "svelte": "^5.55.1"

package/skills/dryui/SKILL.md

@@ -31,6 +31,8 @@ Most DryUI components are compound — they require `<Card.Root>`, not `<Card>`.
 <!-- Right --> <Card.Root>content</Card.Root>
 ```
 
+Compound components include Accordion, Alert, AlertDialog, Breadcrumb, Calendar, Card, Carousel, Chart, ChipGroup, Collapsible, ColorPicker, Combobox, CommandPalette, ContextMenu, DataGrid, DateField, DatePicker, DateRangePicker, DescriptionList, Dialog, DragAndDrop, Drawer, DropdownMenu, Field, Fieldset, FileSelect, FileUpload, FlipCard, FloatButton, HoverCard, InputGroup, LinkPreview, List, Listbox, Map, MegaMenu, Menubar, MultiSelectCombobox, NavigationMenu, NotificationCenter, OptionSwatchGroup, Pagination, PinInput, Popover, RadioGroup, RangeCalendar, RichTextEditor, SegmentedControl, Select, Sidebar, Splitter, StarRating, Stepper, Table, TableOfContents, Tabs, TagsInput, Timeline, Toast, ToggleGroup, Toolbar, Tooltip, Tour, Transfer, Tree and Typography.
+
 The test: every compound component in your markup uses `.Root`, and its parts are wrapped inside it. See `rules/compound-components.md` for the full list and parts reference.
 
 ## 3. Let the Theme Do Its Job
@@ -112,13 +114,20 @@ The test: search your markup for raw `<input`, `<select>`, `<dialog>`, `<button>
 - Codex: `$skill-installer install https://github.com/rob-balfre/dryui/tree/main/packages/ui/skills/dryui` then `codex mcp add dryui -- npx -y @dryui/mcp`
 - Copilot/Cursor/Windsurf: `npx degit rob-balfre/dryui/packages/ui/skills/dryui .agents/skills/dryui` + add MCP config (see https://dryui.dev/tools)
 
-**3. Run the install planner** — it detects your project and returns a tailored step-by-step plan:
+**3. Bootstrap the project** — `init` detects your project state and applies whatever is missing:
 
 ```
-npx -y @dryui/cli install --toon
+npx -y @dryui/cli init
 ```
 
-Execute each `"pending"` step. Then verify: `npx -y @dryui/cli detect --toon` — output should show `project: ready`.
+**New project from scratch?** Pass a directory name to scaffold SvelteKit + DryUI in one step:
+
+```
+npx -y @dryui/cli init my-app
+cd my-app && npm run dev
+```
+
+This works for greenfield (empty directory), brownfield (existing non-SvelteKit project), and existing SvelteKit projects. Verify: `npx -y @dryui/cli detect --toon` — output should show `project: ready`.
 
 ### Manual setup
 
@@ -146,6 +155,13 @@ Always verify with `info`, but these are the most common mistakes:
 
 Use these to look up APIs, discover components, plan setup, and validate code.
 
+### Recommended workflow
+
+1. `compose` or `info` before writing components so you confirm kind, required parts, bindables, and canonical usage.
+2. Build the route or component with raw CSS grid, `Container` for constrained width, and `@container` for responsive layout.
+3. `review` or `doctor` after implementation to catch composition drift, layout violations, and accessibility regressions.
+4. Never guess component shape from memory. DryUI is intentionally strict, and the lookup cost is lower than rework.
+
 ### MCP tools (preferred)
 
 | Workflow | Tools |
@@ -160,6 +176,7 @@ Use these to look up APIs, discover components, plan setup, and validate code.
 All commands support `--toon` for token-optimized agent output and `--full` to disable truncation.
 
 ```bash
+bunx @dryui/cli init [path] [--pm bun]   # Bootstrap SvelteKit + DryUI project
 bunx @dryui/cli info <component> --toon  # Look up component API
 bunx @dryui/cli compose "date input" --toon  # Composition guidance
 bunx @dryui/cli detect [path] --toon     # Check project setup

package/skills/dryui/rules/composition.md

@@ -402,13 +402,62 @@ Call `compose` with any recipe name to get a full working snippet.
 | `data-table-with-actions` | Table with header actions | Table, Badge, Avatar, Button           |
 | `checkout-flow`           | Multi-step checkout       | Stepper, Card, Field, RadioGroup       |
 | `hotel-listing-card`      | Product/listing card      | Card, Image, Badge, Button, Text       |
-| `stat-card-grid`          | KPI dashboard cards       | Grid, StatCard, Chart, Sparkline       |
+| `stat-card-grid`          | KPI dashboard cards       | StatCard, Chart, Sparkline, Container  |
 | `settings-page`           | Settings with tabs        | Tabs, Card, Field, Input, Select       |
 | `form-with-validation`    | Form with error handling  | Card, Field, Label, Input, Field.Error |
-| `sidebar-layout`          | Page with sidebar nav     | Grid, Sidebar, PageHeader              |
-| `dashboard-page`          | Full dashboard layout     | Grid, Sidebar, StatCard, Chart, Table  |
+| `sidebar-layout`          | Page with sidebar nav     | Sidebar, PageHeader, Container         |
+| `dashboard-page`          | Full dashboard layout     | Sidebar, StatCard, Chart, Table        |
 | `user-profile-card`       | User info card            | Card, Avatar, Text, Badge, Button      |
 | `notification-list`       | Notification feed         | Card, Avatar, Text, Badge              |
 | `command-bar`             | Command palette trigger   | CommandPalette, Hotkey                 |
 | `file-upload-form`        | File upload with progress | Card, FileUpload, Progress, Button     |
 | `pricing-table`           | Pricing comparison        | Card, Text, Button, Badge              |
+
+## State-heavy form flows
+
+DryUI is a presentation and accessibility system, not a workflow engine. For dependent-field planners, approvals, and booking-style state machines:
+
+- Normalize route/session state in script before rendering DryUI inputs.
+- Reset dependent `Select.Root` values when their parent choice changes; do not rely on stale child state surviving domain changes.
+- Use raw CSS grid to lay out planner sections, and keep orchestration logic in route-level stores or derived state.
+- Run `compose` or `info` before introducing a new field shape, then run `review` or `doctor` after the flow is wired.
+
+```svelte
+<script lang="ts">
+  let country = $state('');
+  let airport = $state('');
+
+  const airportOptions = $derived(getAirports(country));
+
+  $effect(() => {
+    if (!airportOptions.some((option) => option.value === airport)) {
+      airport = '';
+    }
+  });
+</script>
+
+<div class="planner">
+  <Field.Root>
+    <Label>Country</Label>
+    <Select.Root bind:value={country}>
+      <Select.Trigger><Select.Value placeholder="Choose country" /></Select.Trigger>
+      <Select.Content>{/* items */}</Select.Content>
+    </Select.Root>
+  </Field.Root>
+
+  <Field.Root>
+    <Label>Airport</Label>
+    <Select.Root bind:value={airport} disabled={!country}>
+      <Select.Trigger><Select.Value placeholder="Choose airport" /></Select.Trigger>
+      <Select.Content>{/* filtered items */}</Select.Content>
+    </Select.Root>
+  </Field.Root>
+</div>
+
+<style>
+  .planner {
+    display: grid;
+    gap: var(--dry-space-4);
+  }
+</style>
+```