compote-ui 0.74.2 → 0.75.1

package/dist/index.d.ts

@@ -77,6 +77,8 @@ export { getLocalTimeZone, parseAbsolute, parseDateTime } from '@internationaliz
 export type { DateValue } from '@internationalized/date';
 export { Portal } from '@ark-ui/svelte/portal';
 export type { PortalProps } from '@ark-ui/svelte/portal';
+export { FormatByte, FormatNumber, FormatRelativeTime, FormatTime } from '@ark-ui/svelte/format';
+export type { FormatByteProps, FormatNumberProps, FormatRelativeTimeProps, FormatTimeProps } from '@ark-ui/svelte/format';
 export { createListCollection, createTreeCollection } from './utils/collections';
 export type { ListItem, TreeItem } from './utils/collections';
 export type { ListCollection, TreeCollection } from '@ark-ui/svelte/collection';

package/dist/index.js

@@ -59,6 +59,7 @@ export { default as TreeView } from './components/tree-view/tree-view.svelte';
 export { LocaleProvider, useLocaleContext } from '@ark-ui/svelte/locale';
 export { getLocalTimeZone, parseAbsolute, parseDateTime } from '@internationalized/date';
 export { Portal } from '@ark-ui/svelte/portal';
+export { FormatByte, FormatNumber, FormatRelativeTime, FormatTime } from '@ark-ui/svelte/format';
 export { createListCollection, createTreeCollection } from './utils/collections';
 export { PersistedState, Debounced } from 'runed';
 export { cn } from 'tailwind-variants';

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "compote-ui",
-	"version": "0.74.2",
+	"version": "0.75.1",
 	"license": "MIT",
 	"scripts": {
 		"dev": "vite dev --open",
@@ -65,25 +65,25 @@
 		"@sveltejs/package": "^2.5.8",
 		"@sveltejs/vite-plugin-svelte": "^7.3.0",
 		"@tailwindcss/vite": "^4.3.3",
-		"@tanstack/intent": "^0.3.7",
-		"@tanstack/svelte-table": "9.2.3",
+		"@tanstack/intent": "^0.4.0",
+		"@tanstack/svelte-table": "9.2.4",
 		"@types/node": "^22.20.0",
-		"eslint": "^10.9.1",
+		"eslint": "^10.10.0",
 		"eslint-config-prettier": "^10.1.8",
 		"eslint-plugin-svelte": "^3.23.0",
-		"globals": "^17.11.0",
+		"globals": "^17.12.0",
 		"prettier": "^3.9.6",
 		"prettier-plugin-svelte": "^4.1.1",
 		"prettier-plugin-tailwindcss": "^0.8.1",
 		"publint": "^0.3.24",
-		"svelte": "^5.56.10",
+		"svelte": "^5.57.0",
 		"svelte-check": "^4.7.6",
 		"tailwindcss": "^4.3.3",
 		"tw-animate-css": "^1.4.0",
 		"typescript": "^6.0.3",
-		"typescript-eslint": "^8.68.0",
+		"typescript-eslint": "^8.70.0",
 		"unplugin-icons": "^23.0.1",
-		"vite": "^8.2.2",
+		"vite": "^8.3.0",
 		"vitest": "^5"
 	},
 	"keywords": [
@@ -91,10 +91,10 @@
 		"tanstack-intent"
 	],
 	"dependencies": {
-		"@ark-ui/svelte": "^5.24.0",
+		"@ark-ui/svelte": "^5.24.1",
 		"@fontsource-variable/nunito-sans": "^5.2.7",
-		"@internationalized/date": "^3.12.3",
-		"@tanstack/svelte-virtual": "^3.13.36",
+		"@internationalized/date": "^3.12.4",
+		"@tanstack/svelte-virtual": "^3.13.37",
 		"runed": "^0.37.1",
 		"svelte-tel-input": "^4.3.2",
 		"tailwind-merge": "^3.6.0",

package/skills/component-usage/SKILL.md

@@ -8,7 +8,7 @@ description: >
 metadata:
   type: core
   library: compote-ui
-  library_version: '0.62.1'
+  library_version: '0.74.2'
 sources:
   - src/lib/index.ts
   - src/lib/utils/collections.ts
@@ -19,6 +19,17 @@ sources:
   - src/lib/components/file-upload/file-upload.svelte
   - src/lib/components/image-cropper/image-cropper.svelte
   - src/lib/utils/image-processing.ts
+  - src/lib/components/app-shell
+  - src/lib/components/nav-rail
+  - src/lib/components/badge/badge.svelte
+  - src/lib/components/table
+  - src/lib/components/qr-code/qr-code.svelte
+  - src/lib/components/progress
+  - src/lib/components/tags-input/tags-input.svelte
+  - src/lib/components/menu
+  - src/lib/components/popover
+  - src/lib/components/hover-card
+  - src/lib/components/tooltip
 ---
 
 # Compote UI — Component Usage
@@ -189,7 +200,7 @@ Correct:
 
 Icon-only controls need an accessible name.
 
-Source: `C:/Users/tihom/.claude/skills/compote-ui/references/button.md`
+Source: `references/buttons.md`
 
 ## References
 

package/skills/component-usage/references/component-export-map.md

@@ -3,19 +3,23 @@
 Root exports:
 
 - `Avatar`
+- `Badge`
 - `Button`, `LinkButton`
 - `Checkbox`, `CheckboxGroup`
 - `Combobox`
 - `DateField`, `DateRangeField`, `DateInput`, `DatePicker`
 - `AlertDialog`
 - `FileUploadDropzone`, `FileUpload`
-- `ImageCropper`, `ImageCropDialog`
+- `FormatByte`, `FormatNumber`, `FormatRelativeTime`, `FormatTime`
+- `ImageCropper`, `ImageCropDialog`, `ImageUpload`
 - `JsonTreeView`
 - `NumberInput`, `PasswordInput`, `PhoneInput`
+- `ProgressLinear`, `ProgressCircular`
 - `QrCode`
 - `Select`
 - `Splitter`
 - `Switch`
+- `TagsInput`
 - `Toggle`
 - `TreeView`
 - `LocaleProvider`, `useLocaleContext`
@@ -25,24 +29,27 @@ Root exports:
 
 Namespace exports:
 
+- `AppShell`
 - `Card`
 - `Collapsible`
 - `HoverCard`
 - `ScrollArea`
 - `Carousel`
 - `Dialog`
-- `DataTable`
-- `VirtualDataTable`
+- `DataTable` (subpath: `compote-ui/data-table`, not re-exported from root)
+- `VirtualDataTable` (subpath: `compote-ui/data-table/virtual`, not re-exported from root)
 - `Drawer`
+- `Field`
+- `Fieldset`
 - `Listbox`
+- `Menu`
+- `NavRail`
 - `Popover`
+- `Table`
 - `Tabs`
 - `Toast`
 - `ToggleGroup`
-- `Menu`
 - `Tooltip`
-- `Field`
-- `Fieldset`
 
 Utility exports:
 
@@ -52,3 +59,10 @@ Utility exports:
 - `processImage`
 - `createListCollection`
 - `createTreeCollection`
+- `toDateValue`, `dateValueToString`, `dateValueToDate`
+
+`DataTable` and `VirtualDataTable` are deliberately **not** root exports — they pull in the
+`@tanstack/svelte-table` (and, for the virtual variant, `@tanstack/svelte-virtual`) peer
+dependency, so importing them from the root package would force that peer on every consumer.
+Import them from the subpath instead: `import * as DataTable from 'compote-ui/data-table'`. See
+the `data-table` skill.

package/skills/component-usage/references/files-and-images.md

@@ -1,5 +1,54 @@
 # Files And Images
 
+## ImageUpload
+
+Single-image upload/replace/delete widget — a preview box with a corner `Menu` badge
+(click-triggered, works on touch) opening "Upload/Replace" and "Delete" actions. Selecting a file
+routes through `ImageCropDialog` automatically, so this is the easiest way to wire up an avatar or
+banner uploader — no manual dropzone/crop-dialog wiring needed.
+
+```svelte
+<script lang="ts">
+	let avatarUrl = $state<string | undefined>();
+
+	function handleChange(blob: Blob) {
+		const form = new FormData();
+		form.append('image', blob, 'avatar.webp');
+		fetch('/upload', { method: 'POST', body: form });
+	}
+</script>
+
+<ImageUpload
+	bind:value={avatarUrl}
+	aspectRatio={1}
+	onChange={handleChange}
+	onDelete={() => {
+		/* clear on server */
+	}}
+/>
+
+<!-- Square/banner variant: size + shape via class -->
+<ImageUpload
+	bind:value={bannerUrl}
+	shape="square"
+	class="aspect-video w-64"
+	aspectRatio={16 / 9}
+	uploadLabel="Upload banner"
+/>
+```
+
+Props: `value?: string` (bindable), `shape?: 'circle' | 'square'` (default `'circle'`),
+`class?: ClassValue` (default `'size-24'` — controls preview box sizing), `aspectRatio?: number`
+(passed to the crop dialog), `processOptions?: ProcessImageOptions`,
+`uploadLabel?`/`replaceLabel?`/`deleteLabel?: string`, `onChange: (blob: Blob) => void`,
+`onDelete: () => void`.
+
+`value` is updated internally to an object URL after a successful crop; the previous object URL is
+revoked automatically. Delete has **no built-in confirmation** — wrap `onDelete` in your own
+`AlertDialog` if you need one.
+
+## ImageCropDialog
+
 Use `ImageCropDialog` for the complete upload/crop flow.
 
 ```svelte

package/skills/component-usage/references/forms-and-inputs.md

@@ -1,5 +1,7 @@
 # Forms And Inputs
 
+## Field
+
 Use `Field.Root` to propagate `invalid`, `disabled`, `required`, and `readOnly` state.
 
 ```svelte
@@ -45,7 +47,23 @@ say), pass `hideMessageLine` to drop the spacer entirely:
 </Field.Root>
 ```
 
-List controls use `{ value, label }` items:
+`Field.Textarea` composes the same way as `Field.Input`:
+
+```svelte
+<Field.Root required>
+	<Field.Label>Bio</Field.Label>
+	<Field.Textarea bind:value={bio} rows={4} />
+	<Field.HelperText>Max 500 characters.</Field.HelperText>
+</Field.Root>
+```
+
+**Components that wrap their own control** — `PasswordInput`, `NumberInput`, `Select`, the date
+components — read `invalid`/`required`/`disabled`/`readOnly` from `Field.Root`'s context directly.
+Don't pass those props to both the field and the wrapped control.
+
+## Select
+
+Single-value dropdown using `{ value, label }` items:
 
 ```svelte
 <script lang="ts">
@@ -58,48 +76,137 @@ List controls use `{ value, label }` items:
 </script>
 
 <Select {items} label="Fruit" bind:value placeholder="Select..." />
-<Combobox {items} label="Fruit" bind:value />
 ```
 
-Use `DateField` as the default accessible date input:
+### Form submission (hidden select)
+
+`Select` renders Ark UI's `Select.HiddenSelect` — a real visually-hidden `<select>`. Pass `name`
+and the value is serialized by `FormData`, so it works with native forms, SvelteKit form actions,
+and remote `form()` functions.
 
 ```svelte
-<script lang="ts">
-	import type { DateValue } from 'compote-ui';
+<form {...createPost}>
+	<Select {items} label="Fruit" name="fruit" />
+	<Select items={amounts} label="Amount" name="n:amount" />
+</form>
+```
 
-	let value = $state<DateValue | null>(null);
-</script>
+- **Nothing selected omits the key entirely** — the hidden select sits at `selectedIndex: -1`, so
+  the field is absent from `FormData` (`undefined`, not `''`). Pair it with `v.optional(...)`.
+- **Numbers need the `n:` name prefix** (e.g. `name="n:amount"`) — values are otherwise strings;
+  SvelteKit resolves coercion from the field name, not the element type.
+- **`form.fields.x.value()` is stale on the client** — SvelteKit syncs field state from `input`
+  events, and the Ark trigger sets the value programmatically without firing one. Use `bind:value`
+  for client-side reads.
+- **No progressive enhancement** — the hidden select is `tabIndex: -1` and the trigger is
+  JS-driven.
+
+## Combobox
+
+Searchable select with optional multi-select and client-side filtering.
+
+```svelte
+<Combobox items={langs} label="Language" bind:value={lang} placeholder="Choose..." />
+<Combobox items={langs} label="Languages" bind:value={langs} multiple placeholder="Choose..." />
+<Combobox items={results} label="User" bind:value={userId} loading={fetching} />
+```
+
+## Checkbox / CheckboxGroup
 
-<DateField label="Date" bind:value />
+```svelte
+<Checkbox label="I agree to the terms" bind:checked />
+
+<!-- Helper text below the label -->
+<Checkbox label="Subscribe to newsletter" bind:checked>Receive weekly digest emails.</Checkbox>
 ```
 
-Use `DateRangeField` for ranges:
+`CheckboxGroup` renders a set of checkboxes from `{ value, label }` items and binds an array:
 
 ```svelte
 <script lang="ts">
-	import type { DateValue } from 'compote-ui';
+	const items = [
+		{ value: 'svelte', label: 'Svelte' },
+		{ value: 'react', label: 'React' }
+	];
+	let selected = $state(['svelte']);
+</script>
+
+<CheckboxGroup {items} bind:value={selected} orientation="vertical" />
+```
+
+## TagsInput
+
+Free-text tag entry — type a value and press `Enter`/`,` to add it, click the `×` to remove it.
+`value` is a plain `string[]`.
 
-	let range = $state<DateValue[]>([]);
+```svelte
+<script lang="ts">
+	let value = $state(['Svelte', 'React']); // predefined tags
 </script>
 
-<DateRangeField label="Range" bind:value={range} />
+<TagsInput label="Frameworks" bind:value placeholder="Add a tag" />
+```
+
+If selection must be restricted to a fixed set (pick-only, no free text), use `Combobox` with
+`multiple` instead — `TagsInput` accepts arbitrary typed text.
+
+## Switch
+
+```svelte
+<Switch label="Dark mode" bind:checked={darkMode} />
+```
+
+`labelSpacer` adds vertical space to align a labelless switch with adjacent labeled fields.
+
+## NumberInput
+
+```svelte
+<NumberInput label="Quantity" bind:value={qty} min={0} max={100} step={1} />
+<NumberInput
+	label="Price"
+	bind:value={price}
+	formatOptions={{ style: 'currency', currency: 'USD' }}
+/>
+```
+
+Props: `value?: number | null` (bindable), `label?`, `readonly?`, `layout?: 'vertical' | 'horizontal'`,
+plus Ark UI NumberInput props (`min`, `max`, `step`, `formatOptions`, `locale`).
+
+## PasswordInput
+
+Password field with a built-in show/hide toggle. The underlying `<input>` is a real DOM input —
+pass `name` and it's included in `FormData` directly, no hidden input needed.
+
+```svelte
+<form method="post">
+	<PasswordInput label="Password" name="password" required />
+	<button type="submit">Sign in</button>
+</form>
 ```
 
-Use `DateInput` when binding existing `string`, `Date`, or `DateValue` values without a calendar popup.
+## PhoneInput
 
-`PhoneInput` stores E.164 values:
+International phone input wrapping `svelte-tel-input`. `value` is always E.164
+(e.g. `+12015550123`); `country` is an ISO 3166-1 alpha-2 code.
 
 ```svelte
 <script lang="ts">
 	let phone = $state('');
-	let country = $state(null);
+	let country = $state<CountryCode | null>('US');
 	let valid = $state(false);
 </script>
 
 <PhoneInput label="Phone" bind:value={phone} bind:country bind:valid />
 ```
 
-`Listbox.Content` exposes filtered `items` and grouped `group` snippet data:
+`options?: TelInputOptions` (from `svelte-tel-input/types`) configures parsing/validation:
+`autoPlaceholder`, `spaces`, `validateOn`, `allowedCountries`, `lockCountry`. The country picker is
+an Ark UI `Select` (not a native `<select>`) with no search/filter yet.
+
+## Listbox
+
+`Listbox.Content` exposes filtered `items` and grouped `group` snippet data. `Listbox.Input`
+auto-wires filter state via context — no props needed.
 
 ```svelte
 <Listbox.Root {items} bind:value={selected}>
@@ -118,3 +225,90 @@ Use `DateInput` when binding existing `string`, `Date`, or `DateValue` values wi
 	</Listbox.Content>
 </Listbox.Root>
 ```
+
+## Date components
+
+`DateField`, `DateRangeField`, `DateInput`, and `DatePicker` all accept
+`DateValue | string | Date | null` for `value`/`defaultValue` — bind directly to DB values, no
+`parseDate`/`.toString()` conversion needed. The bound value round-trips in the same shape given
+(string in → string out, `Date` in → `Date` out); if it starts `null`, changes emit as a string.
+`DateRangeField` uses the same notation on separate `start`/`end` props instead of an array `value`.
+
+`locale`/`timeZone` default to the nearest `LocaleProvider` / the user's local zone. For UTC values
+from a DB (`timestamptz`), bind the ISO string with its offset and leave `timeZone` unset — the
+component displays local time and emits UTC back.
+
+String auto-detection (space separator and bare `+00` offset are normalized):
+
+- `"2024-01-15"` → date-only → emits `"2024-01-15"`
+- `"2024-01-15T10:30:00"` → naive datetime → emits the same shape
+- `"2024-01-15T10:30:00Z"` / `"...+02:00"` → zoned, displayed local, emits UTC absolute string
+
+A zoned value at time granularity would render a trailing timezone segment (`GMT+2`); all three
+segmented components hide it by default — pass `hideTimeZone={false}` to show it.
+
+### Form submission (ISO hidden inputs)
+
+Give any date component a `name` and it renders a hidden input carrying a canonical **ISO
+string**, never the locale-formatted display value.
+
+```svelte
+<DateField label="Date" bind:value name="start_date" />
+```
+
+`DateRangeField` is the exception — one field name can't carry two dates, so `name="stay"` is
+shorthand for **two** hidden inputs, `stayStart`/`stayEnd`. Use `startName`/`endName` to name each
+side outright. An unpicked end date submits as `''`, not an absent key.
+
+```ts
+// +page.server.ts
+const start = formData.get('stayStart'); // '2025-06-01'
+const end = formData.get('stayEnd'); // '', if not picked yet
+```
+
+**With SvelteKit remote functions:** bind strings, not `DateValue` — `query`/`command` args are
+serialized with devalue, which doesn't handle `@internationalized/date` instances. Binding a DB
+string keeps the value serializable end to end. `form.fields.x.value()` also goes stale here (the
+component sets the hidden input's value programmatically without firing `input`) — read from
+`bind:` instead. For full `form` integration (repopulation after a failed submit, `aria-invalid`),
+render the hidden inputs yourself with `.as('hidden', value)` rather than relying on `name`.
+
+### DateField ← recommended primary component
+
+Segmented date input (separate day/month/year fields) with an optional calendar popup — no format
+ambiguity, keyboard-incrementable segments, proper ARIA labels.
+
+```svelte
+<DateField label="Date" bind:value {min} {max} />
+<DateField label="Updated at" granularity="minute" bind:value={row.updated_at} />
+```
+
+### DateRangeField
+
+Two segment groups wired to a shared calendar, bound separately via `bind:start`/`bind:end`.
+
+```svelte
+<DateRangeField label="Stay" bind:start bind:end />
+```
+
+`end` is ignored while `start` is empty — zag reads the range positionally.
+
+### DateInput
+
+Segmented input **without** a calendar popup — compact, keyboard-only entry.
+
+```svelte
+<DateInput label="Date & time" bind:value={row.updated_at} granularity="minute" />
+```
+
+For a nullable string column that starts empty, initialize as `''` (not `null`) so the value stays
+serializable as a string.
+
+### DatePicker
+
+Free-text input with a calendar popup — simpler, less accessible than `DateField`. Prefer
+`DateField` for most cases.
+
+```svelte
+<DatePicker label="Date" bind:value placeholder="MM/DD/YYYY" />
+```

package/skills/component-usage/references/layout-and-display.md

@@ -1,6 +1,177 @@
 # Layout And Display
 
-Tabs:
+## AppShell
+
+Page-scaffolding layout with five **optional** regions on a CSS grid. Render only the regions
+you need — an omitted one collapses to zero width/height, no config flag needed.
+
+```svelte
+<AppShell.Root>
+	<AppShell.Header>Header</AppShell.Header>
+	<AppShell.Navbar>Navbar</AppShell.Navbar>
+	<AppShell.Main>Main content (scrolls independently)</AppShell.Main>
+	<AppShell.Aside>Aside</AppShell.Aside>
+	<AppShell.Footer>Footer</AppShell.Footer>
+</AppShell.Root>
+```
+
+- Sizing is done via the `class` prop (no size props): `<AppShell.Navbar class="w-80">`.
+- Full height by default (`h-dvh`); override with `<AppShell.Root class="h-full">` when nesting.
+- `AppShell.Main` scrolls independently — header/navbar/aside/footer stay put.
+- Use `AppShell.Section grow` inside `Navbar`/`Aside` for a scrolling area between pinned
+  top/bottom sections (e.g. logo + scrolling nav links + user menu).
+- Desktop-first, no built-in mobile logic — add your own responsive classes.
+
+## NavRail
+
+A collapsed icon rail that **expands on hover** (overlay mode), meant to sit inside
+`AppShell.Navbar`. It floats over content and widens on hover/focus/pin — nothing else reflows.
+
+```svelte
+<AppShell.Navbar class="w-16">
+	<NavRail.Root bind:expanded>
+		<AppShell.Section grow class="space-y-1 p-2">
+			<NavRail.Item label="Dashboard" active onclick={() => goto('/dashboard')}>
+				{#snippet icon()}<PhStar />{/snippet}
+			</NavRail.Item>
+		</AppShell.Section>
+	</NavRail.Root>
+</AppShell.Navbar>
+```
+
+- `NavRail.Root`: `expanded?: boolean` (bindable) pins it open.
+- `NavRail.Item`: renders `<a>` when `href` is set, else `<button>`. Pass `icon` as a snippet;
+  `label` fades in on expand.
+- The `AppShell.Navbar` placeholder must reserve the collapsed width (`class="w-16"`).
+
+## Badge
+
+Plain presentational `<span>` for status labels, counts, or tags — no Ark UI primitive.
+
+```svelte
+<Badge>Draft</Badge>
+<Badge color="success" variant="solid">Verified</Badge>
+<Badge color="danger" variant="outline">Failed</Badge>
+
+<Badge color="success" variant="solid">
+	{#snippet icon()}<PhCheck />{/snippet}
+	Verified
+</Badge>
+```
+
+`Badge` props: `variant?: 'solid' | 'subtle' | 'outline'` (default `'subtle'`),
+`color?: 'neutral' | 'primary' | 'danger' | 'warning' | 'success' | 'info'` (default `'neutral'`),
+`icon?: Snippet`, `class?: ClassValue`.
+
+## Card
+
+Namespaced presentational component for grouping content.
+
+```svelte
+<Card.Root>
+	<Card.Header>
+		<Card.Title>Card Title</Card.Title>
+		<Card.Description>Card Description</Card.Description>
+	</Card.Header>
+	<Card.Content>
+		<p>Card content goes here.</p>
+	</Card.Content>
+	<Card.Footer>
+		<Button variant="outline">Cancel</Button>
+		<Button>Confirm</Button>
+	</Card.Footer>
+</Card.Root>
+```
+
+All sub-components (`Root`, `Header`, `Title`, `Description`, `Content`, `Footer`) accept `class`.
+
+## Table
+
+Plain presentational table primitive — no data model, no column defs, no sorting/filtering.
+
+**Table vs DataTable.** Use `DataTable` (see the `data-table` skill) when you need sorting,
+filtering, column visibility/resizing/pinning, row selection, or virtualization. Use `Table` for
+static rows, cells built from arbitrary markup, or tables inside dialogs where selection state
+lives in the consumer. Both share cell metrics and surface tokens, so they stay visually
+consistent.
+
+```svelte
+<div class="max-h-64 overflow-auto rounded-lg border border-surface-3">
+	<Table.Root class="table-fixed">
+		<Table.Header>
+			<Table.Row>
+				<Table.Head class="w-24">SKU</Table.Head>
+				<Table.Head>Item</Table.Head>
+				<Table.Head class="text-right">Qty</Table.Head>
+			</Table.Row>
+		</Table.Header>
+		<Table.Body>
+			{#each items as item (item.id)}
+				<Table.Row selected={selectedIds[item.id]}>
+					<Table.Cell>{item.sku || '-'}</Table.Cell>
+					<Table.Cell class="truncate">{item.name}</Table.Cell>
+					<Table.Cell class="text-right">{item.quantity}</Table.Cell>
+				</Table.Row>
+			{/each}
+		</Table.Body>
+	</Table.Root>
+</div>
+```
+
+`Table.Root` has no border, rounding, background, or scroll container by default — wrap it
+yourself. Add `table-fixed` when setting explicit column widths or using `truncate` on cells.
+Alignment is via utility classes (`text-right`) on `Table.Head`/`Table.Cell`, not props.
+
+## QrCode
+
+Single-file wrapper rendering an SVG QR code from any string value.
+
+```svelte
+<QrCode value="https://example.com" />
+<QrCode value="https://example.com" size="lg" class="text-primary" />
+```
+
+Props: `value: string`, `size?: 'sm' | 'md' | 'lg' | 'xl'` (default `'md'`),
+`encoding?: QrCodeGenerateOptions`, `class?: string`. Color follows the CSS `color` property — use
+a `text-*` class.
+
+## Progress
+
+Two wrappers around Ark UI Progress: `ProgressLinear` (bar) and `ProgressCircular` (ring). Both
+are determinate by default; pass `value={null}` for an indeterminate animated state.
+
+```svelte
+<ProgressLinear value={60} label="Uploading" showValueText />
+<ProgressCircular value={60} showValueText size="lg" />
+<ProgressLinear value={null} label="Loading…" />
+```
+
+Shared props: `value?: number | null` (bindable, `null` = indeterminate), `min`/`max` (default
+`0`/`100`), `label?: string`, `showValueText?: boolean`,
+`variant?: 'primary' | 'success' | 'danger' | 'warning' | 'info'`, `formatOptions?: NumberFormatOptions`.
+`ProgressLinear` adds `size?: 'sm' | 'md' | 'lg'`. `ProgressCircular` adds `size?: 'sm' | 'md' | 'lg' | number`
+and `thickness?: number`.
+
+## Format
+
+Unstyled formatting components re-exported directly from Ark UI (no compote wrapper) — they
+render plain text via `Intl`, so there's nothing to theme. Locale comes from the nearest
+`LocaleProvider` (defaults to browser locale). None of them accept `class` since they render bare
+text nodes — wrap in a `<span>` to style the surrounding text.
+
+```svelte
+<FormatRelativeTime value={someDate} />
+<FormatByte value={1536} />
+<FormatNumber value={1234.5} style="currency" currency="EUR" />
+<FormatTime value={someDate} format="24h" />
+```
+
+- `FormatRelativeTime` — `value: Date` + `Intl.RelativeTimeFormatOptions` (`style`, `numeric`).
+- `FormatByte` — `value: number` (bytes) + `unit?`, `unitDisplay?`, `unitSystem?: 'decimal' | 'binary'`.
+- `FormatNumber` — `value: number` + `Intl.NumberFormatOptions` (`style`, `currency`, etc.).
+- `FormatTime` — `value: string | Date` + `format?: '12h' | '24h'`, `withSeconds?: boolean`.
+
+## Tabs
 
 ```svelte
 <Tabs.Root bind:value={tab} defaultValue="account">
@@ -14,6 +185,10 @@ Tabs:
 </Tabs.Root>
 ```
 
+`Tabs.Indicator` must be inside `Tabs.List`, after the triggers.
+
+## Splitter
+
 Splitter fills its container:
 
 ```svelte
@@ -34,7 +209,11 @@ Splitter fills its container:
 </div>
 ```
 
-For nested splitters, use Ark UI directly with one shared registry:
+**Limitation — no nesting.** The `<Splitter>` wrapper doesn't support nesting: Ark UI requires both
+outer and inner `Splitter.Root` to share one `registry` instance, but the wrapper has no way to
+pass it into a `content` snippet. Use Ark UI primitives directly, calling
+`Splitter.createRegistry()` **once** and passing the same `{registry}` to every `Splitter.Root` in
+the tree:
 
 ```svelte
 <script lang="ts">
@@ -42,8 +221,43 @@ For nested splitters, use Ark UI directly with one shared registry:
 
 	const registry = Splitter.createRegistry();
 </script>
+
+<Splitter.Root {registry} orientation="horizontal" panels={[{ id: 'left' }, { id: 'right' }]}>
+	<Splitter.Panel id="left" class="overflow-auto p-2">Left</Splitter.Panel>
+	<Splitter.ResizeTrigger id="left:right" aria-label="Resize left and right" />
+	<Splitter.Panel id="right" class="overflow-auto">
+		<!-- Nested vertical splitter reuses the same registry -->
+		<Splitter.Root {registry} orientation="vertical" panels={[{ id: 'top' }, { id: 'bottom' }]}>
+			<Splitter.Panel id="top" class="overflow-auto p-2">Top</Splitter.Panel>
+			<Splitter.ResizeTrigger id="top:bottom" aria-label="Resize top and bottom" />
+			<Splitter.Panel id="bottom" class="overflow-auto p-2">Bottom</Splitter.Panel>
+		</Splitter.Root>
+	</Splitter.Panel>
+</Splitter.Root>
 ```
 
+The `ResizeTrigger` `id` must follow the `"panelA:panelB"` format matching adjacent panel ids.
+
+## Collapsible
+
+```svelte
+<Collapsible.Root>
+	<Collapsible.Trigger>
+		Section title
+		<Collapsible.Indicator />
+	</Collapsible.Trigger>
+	<Collapsible.Content>
+		<p class="px-3 py-2.5">Hidden content here.</p>
+	</Collapsible.Content>
+</Collapsible.Root>
+```
+
+`Collapsible.Indicator` rotates 90deg on `data-[state=open]` (defaults to a caret-right icon).
+Pass `defaultOpen`, `disabled`, `collapsedHeight` (partial-collapse mode), or `bind:open` to
+`Collapsible.Root`.
+
+## ScrollArea
+
 ScrollArea needs explicit size:
 
 ```svelte
@@ -57,6 +271,8 @@ ScrollArea needs explicit size:
 </ScrollArea.Root>
 ```
 
+## Carousel
+
 Vertical Carousel needs explicit height:
 
 ```svelte
@@ -70,9 +286,19 @@ Vertical Carousel needs explicit height:
 			{/each}
 		</Carousel.ItemGroup>
 	</Carousel.Control>
+	<Carousel.IndicatorGroup>
+		{#each images as _, index (index)}
+			<Carousel.Indicator {index} />
+		{/each}
+	</Carousel.IndicatorGroup>
 </Carousel.Root>
 ```
 
+`Carousel.Indicator` renders a dot by default; pass `thumbnail` plus children for a thumbnail
+indicator.
+
+## TreeView
+
 TreeView fills its container:
 
 ```svelte
@@ -80,3 +306,20 @@ TreeView fills its container:
 	<TreeView {items} label="Files" bind:selectedValue={selected} />
 </div>
 ```
+
+`selectionMode="multiple"` adds `bind:checkedValue` for checkbox selection. `TreeItem.icon` takes
+an Iconify icon name (e.g. `"ph:folder""`) — requires `@iconify/svelte` in the consumer app.
+
+## JsonTreeView
+
+JSON/object inspector — renders nested objects, arrays, primitives, Dates, regexes, errors, maps,
+and sets with keyboard navigation.
+
+```svelte
+<div class="max-h-96 rounded border p-2">
+	<JsonTreeView data={payload} defaultExpandedDepth={2} />
+</div>
+```
+
+Wrap in a constrained container (`max-h-*`) for large payloads. Pass a `renderValue` snippet for
+custom value rendering (e.g. turning emails into `mailto:` links).

package/skills/component-usage/references/overlays-and-floating-ui.md

@@ -1,8 +1,9 @@
 # Overlays And Floating UI
 
 `Dialog`, `Drawer`, `Menu`, `Popover`, `HoverCard`, `Tooltip`, and `Toast` are namespace exports.
+`AlertDialog` is a single component, not a namespace.
 
-Dialog:
+## Dialog
 
 ```svelte
 <script lang="ts">
@@ -20,7 +21,7 @@ Dialog:
 </Dialog.Root>
 ```
 
-Use `onOpenChange`, not `onClose`:
+Use `onOpenChange`, not `onClose` — `Dialog` has no `onClose` prop:
 
 ```svelte
 <Dialog.Root
@@ -33,7 +34,19 @@ Use `onOpenChange`, not `onClose`:
 </Dialog.Root>
 ```
 
-Drawer content renders backdrop and positioner internally:
+`Dialog.CloseTrigger` with no children renders an absolute-positioned X icon in the corner
+automatically — no separate placement needed. With children, it renders as an inline button (for
+`Dialog.Footer`). `contentClass` sets dialog width (e.g. `contentClass="max-w-4xl"`).
+
+**Stacking:** z-index defaults to `50`. Set the `--layer-index` CSS variable on the dialog's
+container to offset it (e.g. `style="--layer-index: 10"` → z-index 60) — use this when a dialog
+must appear above another fixed element like a drawer.
+
+## Drawer
+
+Slide-in panel anchored to a viewport edge, with swipe-to-dismiss and snap points.
+`Drawer.Content` renders the backdrop and positioner internally — compose only
+`Header`/`Body`/`Footer`.
 
 ```svelte
 <Drawer.Root bind:open>
@@ -51,7 +64,30 @@ Drawer content renders backdrop and positioner internally:
 </Drawer.Root>
 ```
 
-AlertDialog is for confirmations:
+`swipeDirection?: 'up' | 'down' | 'start' | 'end'` (default `'down'`) controls which edge it slides
+from: `'down'` = bottom sheet (default), `'up'` = top, `'start'` = left (LTR), `'end'` = right
+(LTR). `Drawer.Body` scrolls internally via `ScrollArea` — no fixed height needed. Safe to open a
+`Dialog` from inside a `Drawer` (it portals above it, same z-index, stacked by DOM order).
+
+Sizing and styling overrides:
+
+```svelte
+<!-- Custom height (bottom/top drawers, default 96svh) -->
+<Drawer.Content maxHeight="50vh">...</Drawer.Content>
+
+<!-- Custom width (side drawers, default 25rem) -->
+<Drawer.Content maxWidth="32rem">...</Drawer.Content>
+
+<!-- Custom backdrop/positioner classes (power users) -->
+<Drawer.Content backdropClass="bg-black/80" positionerClass="items-center">...</Drawer.Content>
+```
+
+`Drawer.Grabber`/`Drawer.GrabberIndicator` render a drag handle (top edge for bottom/top drawers,
+open edge for side drawers) — repositions automatically per `swipeDirection`.
+
+## AlertDialog
+
+For confirmations — built-in confirm/cancel buttons, no custom body.
 
 ```svelte
 <AlertDialog
@@ -64,10 +100,139 @@ AlertDialog is for confirmations:
 />
 ```
 
-Toast setup belongs in layout:
+Props: `open` (bindable), `title`, `description?: string | string[]`,
+`variant?: 'default' | 'destructive'`, `confirmLabel?`, `cancelLabel?`, `onConfirm?`, `onCancel?`.
+
+## Menu
+
+Composable dropdown with items, groups, checkboxes, radio items, context trigger, and submenus.
+
+```svelte
+<Menu.Root>
+	<Menu.Trigger variant="outline">
+		Options
+		<Menu.Indicator />
+	</Menu.Trigger>
+	<Menu.Content>
+		<Menu.Item value="new">New File</Menu.Item>
+		<Menu.Item value="save">Save</Menu.Item>
+		<Menu.Separator />
+		<Menu.Item value="quit" disabled>Quit</Menu.Item>
+	</Menu.Content>
+</Menu.Root>
+```
+
+Groups, checkboxes, and radio items:
+
+```svelte
+<Menu.Content>
+	<Menu.ItemGroup>
+		<Menu.ItemGroupLabel>View</Menu.ItemGroupLabel>
+		<Menu.CheckboxItem value="sidebar" checked={sidebar} onCheckedChange={(v) => (sidebar = v)}>
+			Show Sidebar
+		</Menu.CheckboxItem>
+	</Menu.ItemGroup>
+	<Menu.RadioItemGroup value={theme} onValueChange={(d) => (theme = d.value)}>
+		<Menu.RadioItem value="light">Light</Menu.RadioItem>
+		<Menu.RadioItem value="dark">Dark</Menu.RadioItem>
+	</Menu.RadioItemGroup>
+</Menu.Content>
+```
+
+Right-click context menu — use `Menu.ContextTrigger` instead of `Menu.Trigger`:
+
+```svelte
+<Menu.Root>
+	<Menu.ContextTrigger>
+		<div class="rounded border p-8 text-center">Right-click here</div>
+	</Menu.ContextTrigger>
+	<Menu.Content>
+		<Menu.Item value="copy">Copy</Menu.Item>
+	</Menu.Content>
+</Menu.Root>
+```
+
+Submenu — nest a `Menu.Root` after a `Menu.TriggerItem`:
+
+```svelte
+<Menu.Content>
+	<Menu.TriggerItem>Export as...</Menu.TriggerItem>
+	<Menu.Root>
+		<Menu.Content>
+			<Menu.Item value="pdf">PDF</Menu.Item>
+			<Menu.Item value="csv">CSV</Menu.Item>
+		</Menu.Content>
+	</Menu.Root>
+</Menu.Content>
+```
+
+## Popover
+
+Composable floating panel anchored to a trigger.
+
+```svelte
+<Popover.Root>
+	<Popover.Trigger>
+		<Button>Open Popover</Button>
+	</Popover.Trigger>
+	<Popover.Content>
+		<Popover.Title>Popover Title</Popover.Title>
+		<Popover.Description>Content here.</Popover.Description>
+		<Popover.CloseTrigger />
+	</Popover.Content>
+</Popover.Root>
+```
+
+`Popover.Content` accepts `showArrow?: boolean` (default `true`). Control placement via
+`<Popover.Root positioning={{ placement: 'right' }}>`.
+
+## HoverCard
+
+Floating card that opens on **hover**, not click — key difference from `Popover`. Use `asChild` on
+the trigger to render any element (e.g. a link) instead of the default button.
+
+```svelte
+<HoverCard.Root>
+	<p>
+		Liked by
+		<HoverCard.Trigger>
+			{#snippet asChild(props)}
+				<a href="/profile" {...props()} class="font-medium text-primary underline"> @sarah_chen </a>
+			{/snippet}
+		</HoverCard.Trigger>
+	</p>
+	<HoverCard.Content>
+		<p class="text-sm text-ink">Bio text here.</p>
+	</HoverCard.Content>
+</HoverCard.Root>
+```
+
+`openDelay?: number` (default `600`), `closeDelay?: number` (default `300`) on `HoverCard.Root`.
+
+## Tooltip
+
+Namespace export wrapping Ark UI Tooltip — short text hint shown on hover/focus.
+
+```svelte
+<Tooltip.Root>
+	<Tooltip.Trigger>
+		<Button variant="ghost" size="icon" aria-label="Info"><PhInfo /></Button>
+	</Tooltip.Trigger>
+	<Tooltip.Content>More information</Tooltip.Content>
+</Tooltip.Root>
+```
+
+Prefer `Tooltip` over `HoverCard` for a single line of supplementary text; use `HoverCard` for
+richer content (profile previews, formatted descriptions).
+
+## Toast
+
+Toaster setup belongs once in the root layout:
 
 ```svelte
+<!-- +layout.svelte -->
 <Toast.Toaster />
+{@render children()}
 ```
 
 Then fire toasts anywhere:
@@ -77,4 +242,32 @@ import { toast } from 'compote-ui';
 
 toast.success('Saved');
 toast.error('Save failed', { description: 'Please try again.' });
+toast.promise(saveData(), {
+	loading: { title: 'Saving…' },
+	success: { title: 'Saved' },
+	error: { title: 'Save failed' }
+});
 ```
+
+Shorthand helpers: `toast.info()`, `toast.success()`, `toast.warning()`, `toast.error()`,
+`toast.loading()` — first arg is the title, second an optional options object; each returns the
+toast `id` usable with `toast.update(id, options)` / `toast.dismiss(id)`. `loading` shows a
+spinner and does not auto-dismiss. `toast.create(options)` remains available for full control.
+
+Action button (e.g. Undo):
+
+```ts
+toast.create({
+	title: 'File deleted',
+	type: 'info',
+	action: { label: 'Undo', onClick: () => restore() }
+});
+```
+
+`toast.create()` options: `title: string`, `description?: string`,
+`type?: 'info' | 'success' | 'error' | 'warning' | 'loading'`, `duration?: number` (ms, overrides
+the toaster default for this toast), `action?: { label: string; onClick: () => void }`.
+
+`Toast.Toaster` props: `class?: ClassValue`, `toaster?: CreateToasterReturn` (a custom instance
+from `createToaster()` for a different `placement`/`max`/`duration` — defaults to the shared
+`toast` singleton). Default placement is `bottom-end`; timers pause while the tab is hidden.

package/skills/data-table/SKILL.md

@@ -8,7 +8,7 @@ description: >
 metadata:
   type: composition
   library: compote-ui
-  library_version: '0.62.1'
+  library_version: '0.74.2'
 requires:
   - component-usage
   - theming

package/skills/data-table/references/column-options.md

@@ -18,7 +18,7 @@ col.columns([col.accessor('id', { header: 'ID' })]);
 Common options:
 
 - `header: string`
-- `type?: 'text' | 'number' | 'currency' | 'percent' | 'boolean' | 'select' | 'url' | 'phone' | 'date' | 'time' | 'date-time'`
+- `type?: 'text' | 'number' | 'currency' | 'percent' | 'boolean' | 'select' | 'url' | 'phone' | 'date' | 'time' | 'date-time' | 'action'`
 - `align?: 'left' | 'center' | 'right'`
 - `size?: number`
 - `minSize?: number`
@@ -34,7 +34,9 @@ Common options:
 - `cellComponent?: Component`
 - `cellProps?: (value, row) => Record<string, unknown>`
 - `cellSnippet?: Snippet`
-- `pinned?: 'left' | 'right'`
+- `pinned?: 'left' | 'right'` — sticky during horizontal scroll. Inside a `col.group(...)`, pinning
+  a member column also pins the group header fragment above it, so the label stays visible while
+  the rest of that group scrolls.
 - `grow?: boolean`
 - `sum?: boolean`
 - `footer?: (values: unknown[]) => string | number | undefined`
@@ -49,5 +51,77 @@ Type defaults:
 - `boolean`: center aligned, size `90`
 - `url`: center aligned, sorting disabled, size `60`
 - `phone`: left aligned, size `160`
+- `action`: center aligned, size `60`, sorting/hiding/column-filter all disabled — layout-only,
+  carries no value to format or filter. Supply a `cellComponent`/`cellSnippet` for the row action
+  buttons; the defaults keep the actions column out of the column-visibility menu and filter
+  toolbar automatically.
 
 Use one `grow: true` column to absorb extra horizontal space.
+
+## Locale for number/currency/percent
+
+Priority: `formatLocale` prop → `useLocaleContext().locale` → browser default. Wrap the app in
+`<LocaleProvider locale="sr-RS">` to set the context locale for every formatted column.
+
+## Custom cellComponent
+
+```svelte
+<!-- PriceCell.svelte -->
+<script lang="ts">
+	let { value, prices }: { value: number; prices: { vendor: string; price: number }[] } = $props();
+</script>
+
+<span>{value}</span>
+```
+
+```ts
+col.accessorFn((row) => Math.min(...row.prices.map((p) => p.price)), {
+	id: 'minPrice',
+	header: 'Best Price',
+	type: 'currency',
+	align: 'right',
+	cellComponent: PriceCell,
+	cellProps: (value, row) => ({ value, prices: row.prices })
+});
+```
+
+## Row height and cell alignment
+
+Body cells are fixed at `h-9` (36px), matching the header, with content vertically centered — any
+control up to 36px tall (every `Button` `icon-xs`/`icon-sm`/`icon`/`icon-lg` size) fits without
+changing row height. Do **not** add negative margins (e.g. `-my-1`) to cell components to
+compensate for row growth — in the virtualized table that fights the virtualizer's 37px row
+estimate. Cells are `truncate` (single-line, `overflow: hidden`), so give action columns a little
+extra `size` if a focus ring on a control near the edge gets clipped.
+
+## DataTable.Search
+
+Global filter input searching across all text columns, debounced (default 300ms).
+
+- `table: DataTableInstance<T>` — required
+- `placeholder?: string` (default `'Search...'`)
+- `class?: ClassValue`
+- `debounceMs?: number` (default `300`)
+
+Text/number columns stay searchable even when the first row's value is `null`/`undefined`;
+booleans and object-valued columns are excluded from global search. Also available as
+`VirtualDataTable.Search` for the virtualized variant.
+
+## DataTable.Root props
+
+`table: DataTableInstance<T>` (required), `caption?: string` (sr-only `<caption>`),
+`emptyMessage?: string` (default `'No rows found'`), `class?: ClassValue`,
+`onRowClick?: (details: { row: T; event: MouseEvent }) => void`,
+`onRowDoubleClick?: (details: { row: T; event: MouseEvent }) => void` — `row` is `row.original`.
+Clicks on the row-selection checkbox and url-cell buttons do **not** trigger either handler.
+`VirtualDataTable.Root` shares the same props.
+
+```svelte
+<DataTable.Root
+	{table}
+	onRowDoubleClick={({ row, event }) => {
+		if (event.ctrlKey || event.metaKey) openInNewTab(row.id);
+		else navigateTo(row.id);
+	}}
+/>
+```

package/skills/getting-started/SKILL.md

@@ -7,7 +7,7 @@ description: >
 metadata:
   type: lifecycle
   library: compote-ui
-  library_version: '0.62.1'
+  library_version: '0.74.2'
 sources:
   - package.json
   - README.md

package/skills/production-checklist/SKILL.md

@@ -8,7 +8,7 @@ description: >
 metadata:
   type: lifecycle
   library: compote-ui
-  library_version: '0.62.1'
+  library_version: '0.74.2'
 requires:
   - getting-started
   - component-usage

package/skills/theming/SKILL.md

@@ -7,7 +7,7 @@ description: >
 metadata:
   type: core
   library: compote-ui
-  library_version: '0.62.1'
+  library_version: '0.74.2'
 sources:
   - src/lib/theme.css
   - src/routes/layout.css