compote-ui 0.62.1 → 0.62.2

package/README.md

@@ -26,6 +26,12 @@ yarn add compote-ui
 bun add compote-ui
 ```
 
+If you use an AI agent, run:
+
+```bash
+npx @tanstack/intent@latest install
+```
+
 ## Peer Dependencies
 
 Compote UI requires Svelte 5 or later:

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "compote-ui",
-	"version": "0.62.1",
+	"version": "0.62.2",
 	"license": "MIT",
 	"scripts": {
 		"dev": "vite dev --open",
@@ -19,7 +19,9 @@
 	"files": [
 		"dist",
 		"!dist/**/*.test.*",
-		"!dist/**/*.spec.*"
+		"!dist/**/*.spec.*",
+		"skills",
+		"!skills/_artifacts"
 	],
 	"sideEffects": [
 		"**/*.css"
@@ -62,6 +64,7 @@
 		"@sveltejs/package": "^2.5.8",
 		"@sveltejs/vite-plugin-svelte": "7.1.2",
 		"@tailwindcss/vite": "^4.3.1",
+		"@tanstack/intent": "^0.3.2",
 		"@tanstack/svelte-table": "^9.0.0-beta.17",
 		"@tanstack/svelte-virtual": "^3.13.29",
 		"@types/node": "^22.20.0",
@@ -83,7 +86,8 @@
 		"vite": "^8.0.16"
 	},
 	"keywords": [
-		"svelte"
+		"svelte",
+		"tanstack-intent"
 	],
 	"dependencies": {
 		"@ark-ui/svelte": "^5.22.1",
@@ -93,5 +97,11 @@
 		"svelte-tel-input": "^4.2.0",
 		"tailwind-merge": "^3.6.0",
 		"tailwind-variants": "^3.2.2"
+	},
+	"intent": {
+		"skills": [
+			"compote-ui",
+			"@tanstack/svelte-table"
+		]
 	}
 }

package/skills/component-usage/SKILL.md

@@ -0,0 +1,202 @@
+---
+name: component-usage
+description: >
+  Load when choosing or using compote-ui components and utilities from the root
+  package. Covers public exports, single components vs namespaced compound
+  components, forms, overlays, layout/display components, files/images, buttons,
+  collections, and common component usage mistakes.
+metadata:
+  type: core
+  library: compote-ui
+  library_version: '0.62.1'
+sources:
+  - src/lib/index.ts
+  - src/lib/utils/collections.ts
+  - src/lib/components/button/button.svelte
+  - src/lib/components/field/field.svelte
+  - src/lib/components/select/select.svelte
+  - src/lib/components/dialog/dialog-root.svelte
+  - src/lib/components/file-upload/file-upload.svelte
+  - src/lib/components/image-cropper/image-cropper.svelte
+  - src/lib/utils/image-processing.ts
+---
+
+# Compote UI — Component Usage
+
+Use root exports from `compote-ui` for ordinary components and namespaces for compound component families.
+
+## Setup
+
+```svelte
+<script lang="ts">
+	import { Button, Field, Select, Dialog, createListCollection } from 'compote-ui';
+
+	const fruits = [
+		{ value: 'apple', label: 'Apple' },
+		{ value: 'banana', label: 'Banana', disabled: true }
+	];
+
+	let name = $state('');
+	let fruit = $state<string | null>(null);
+	let open = $state(false);
+	const collection = createListCollection(fruits);
+</script>
+
+<Field.Root required>
+	<Field.Label>Name</Field.Label>
+	<Field.Input bind:value={name} />
+</Field.Root>
+
+<Select items={fruits} label="Fruit" bind:value={fruit} />
+
+<Button onclick={() => (open = true)}>Open</Button>
+<Dialog.Root bind:open>
+	<Dialog.Title>Selected fruit</Dialog.Title>
+	<p>{fruit}</p>
+</Dialog.Root>
+```
+
+## Core Patterns
+
+### Import compound components as namespaces
+
+```svelte
+<script lang="ts">
+	import { Card, Tabs, Menu } from 'compote-ui';
+</script>
+
+<Card.Root>
+	<Card.Header>
+		<Card.Title>Summary</Card.Title>
+	</Card.Header>
+	<Card.Content>
+		<Tabs.Root defaultValue="one">
+			<Tabs.List>
+				<Tabs.Trigger value="one">One</Tabs.Trigger>
+			</Tabs.List>
+			<Tabs.Content value="one">Content</Tabs.Content>
+		</Tabs.Root>
+	</Card.Content>
+</Card.Root>
+```
+
+### Use item shapes expected by collections
+
+```ts
+import { createListCollection, createTreeCollection } from 'compote-ui';
+
+const list = createListCollection([
+	{ value: 1, label: 'One' },
+	{ value: 2, label: 'Two', disabled: true }
+]);
+
+const tree = createTreeCollection([
+	{ value: 'src', label: 'src', children: [{ value: 'app', label: 'App.svelte' }] }
+]);
+```
+
+### Prefer wrappers before raw Ark UI primitives
+
+```svelte
+<script lang="ts">
+	import { Drawer } from 'compote-ui';
+</script>
+
+<Drawer.Root>
+	<Drawer.Trigger>Open</Drawer.Trigger>
+	<Drawer.Content>
+		<Drawer.Header>
+			<Drawer.Title>Edit record</Drawer.Title>
+		</Drawer.Header>
+		<Drawer.Body>Content</Drawer.Body>
+	</Drawer.Content>
+</Drawer.Root>
+```
+
+Use Ark UI directly only for advanced cases the wrapper does not model, such as nested splitters.
+
+## Common Mistakes
+
+### HIGH Importing compound parts as root exports
+
+Wrong:
+
+```svelte
+<script lang="ts">
+	import { DialogRoot, DialogTitle } from 'compote-ui';
+</script>
+```
+
+Correct:
+
+```svelte
+<script lang="ts">
+	import { Dialog } from 'compote-ui';
+</script>
+
+<Dialog.Root>
+	<Dialog.Title>Title</Dialog.Title>
+</Dialog.Root>
+```
+
+Compound components are exported as namespaces.
+
+Source: `src/lib/index.ts`
+
+### HIGH Using arbitrary item shapes
+
+Wrong:
+
+```svelte
+<script lang="ts">
+	const items = [{ id: 1, name: 'One' }];
+</script>
+
+<Select {items} bind:value />
+```
+
+Correct:
+
+```svelte
+<script lang="ts">
+	const items = [{ value: 1, label: 'One' }];
+</script>
+
+<Select {items} bind:value />
+```
+
+List-based components and collection helpers derive value and display text from `value` and `label`.
+
+Source: `src/lib/utils/collections.ts`, `src/lib/components/select/select.svelte`
+
+### MEDIUM Icon-only button without label
+
+Wrong:
+
+```svelte
+<Button size="icon">
+	<SettingsIcon />
+</Button>
+```
+
+Correct:
+
+```svelte
+<Button size="icon" aria-label="Settings">
+	<SettingsIcon class="size-4" />
+</Button>
+```
+
+Icon-only controls need an accessible name.
+
+Source: `C:/Users/tihom/.claude/skills/compote-ui/references/button.md`
+
+## References
+
+- [Buttons](references/buttons.md)
+- [Forms and inputs](references/forms-and-inputs.md)
+- [Overlays and floating UI](references/overlays-and-floating-ui.md)
+- [Layout and display](references/layout-and-display.md)
+- [Files and images](references/files-and-images.md)
+- [Interactive components](references/interactive-components.md)
+- [Component export map](references/component-export-map.md)

package/skills/component-usage/references/buttons.md

@@ -0,0 +1,27 @@
+# Buttons
+
+```svelte
+<Button>Default</Button>
+<Button variant="outline">Outline</Button>
+<Button variant="ghost">Ghost</Button>
+<Button size="sm">Small</Button>
+<Button size="lg">Large</Button>
+<Button size="icon" aria-label="Settings">
+	<SettingsIcon class="size-4" />
+</Button>
+<Button disabled>Disabled</Button>
+```
+
+`Button` props:
+
+- `variant?: 'default' | 'outline' | 'ghost'`
+- `size?: 'sm' | 'default' | 'lg' | 'icon' | 'icon-sm' | 'icon-lg'`
+- `class?: ClassValue`
+- standard button attributes such as `onclick`, `disabled`, `type`
+
+Use `LinkButton` for navigation links that should look like buttons:
+
+```svelte
+<LinkButton href="/dashboard">Dashboard</LinkButton>
+<LinkButton href="https://example.com" variant="outline" target="_blank">External</LinkButton>
+```

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

@@ -0,0 +1,54 @@
+# Component Export Map
+
+Root exports:
+
+- `Avatar`
+- `Button`, `LinkButton`
+- `Checkbox`, `CheckboxGroup`
+- `Combobox`
+- `DateField`, `DateRangeField`, `DateInput`, `DatePicker`
+- `AlertDialog`
+- `FileUploadDropzone`, `FileUpload`
+- `ImageCropper`, `ImageCropDialog`
+- `JsonTreeView`
+- `NumberInput`, `PasswordInput`, `PhoneInput`
+- `QrCode`
+- `Select`
+- `Splitter`
+- `Switch`
+- `Toggle`
+- `TreeView`
+- `LocaleProvider`, `useLocaleContext`
+- `Portal`
+- `PersistedState`, `Debounced`
+- `cn`
+
+Namespace exports:
+
+- `Card`
+- `Collapsible`
+- `HoverCard`
+- `ScrollArea`
+- `Carousel`
+- `Dialog`
+- `DataTable`
+- `VirtualDataTable`
+- `Drawer`
+- `Listbox`
+- `Popover`
+- `Tabs`
+- `Toast`
+- `ToggleGroup`
+- `Menu`
+- `Tooltip`
+- `Field`
+- `Fieldset`
+
+Utility exports:
+
+- `loadImage`
+- `fileToDataUrl`
+- `cropImage`
+- `processImage`
+- `createListCollection`
+- `createTreeCollection`

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

@@ -0,0 +1,75 @@
+# Files And Images
+
+Use `ImageCropDialog` for the complete upload/crop flow.
+
+```svelte
+<script lang="ts">
+	import { FileUploadDropzone, ImageCropDialog, fileToDataUrl } from 'compote-ui';
+
+	let cropOpen = $state(false);
+	let imageSrc = $state('');
+	let previewUrl = $state<string | undefined>();
+
+	async function handleFile(file: File) {
+		imageSrc = await fileToDataUrl(file);
+		cropOpen = true;
+	}
+
+	function handleConfirm(blob: Blob) {
+		cropOpen = false;
+		if (previewUrl) URL.revokeObjectURL(previewUrl);
+		previewUrl = URL.createObjectURL(blob);
+	}
+</script>
+
+<FileUploadDropzone
+	fileType="image"
+	onFileAccept={(details) => {
+		if (details.files[0]) handleFile(details.files[0]);
+	}}
+/>
+
+<ImageCropDialog
+	bind:open={cropOpen}
+	{imageSrc}
+	onConfirm={handleConfirm}
+	onCancel={() => (cropOpen = false)}
+/>
+```
+
+Image utilities are browser-only:
+
+```ts
+import { fileToDataUrl, processImage, cropImage } from 'compote-ui';
+```
+
+`ProcessImageOptions`:
+
+```ts
+type ProcessImageOptions = {
+	maxWidth?: number;
+	maxHeight?: number;
+	quality?: number;
+	format?: 'image/webp' | 'image/jpeg' | 'image/png';
+	trim?: boolean;
+	trimThreshold?: number;
+};
+```
+
+Prefer `getProcessedImage` over Ark UI display-resolution crop output:
+
+```svelte
+<script lang="ts">
+	let getProcessedImage = $state<((opts?: ProcessImageOptions) => Promise<Blob>) | undefined>();
+</script>
+
+<ImageCropper src={imageSrc} bind:getProcessedImage aspectRatio={1} />
+
+<Button
+	onclick={async () => {
+		const blob = await getProcessedImage?.({ maxWidth: 1200 });
+	}}
+>
+	Save
+</Button>
+```

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

@@ -0,0 +1,94 @@
+# Forms And Inputs
+
+Use `Field.Root` to propagate `invalid`, `disabled`, `required`, and `readOnly` state.
+
+```svelte
+<Field.Root required invalid={!email}>
+	<Field.Label>Email</Field.Label>
+	<Field.Input bind:value={email} type="email" />
+	<Field.ErrorText>Email is required.</Field.ErrorText>
+</Field.Root>
+```
+
+With a form adapter, `Field.Root` derives invalid/required state and renders the first error:
+
+```svelte
+<Field.Root {form} field="email" helperText="We'll never share your email.">
+	<Field.Label>Email</Field.Label>
+	<Field.Input bind:value={email} type="email" />
+</Field.Root>
+```
+
+List controls use `{ value, label }` items:
+
+```svelte
+<script lang="ts">
+	const items = [
+		{ value: 'apple', label: 'Apple' },
+		{ value: 'banana', label: 'Banana', disabled: true }
+	];
+
+	let value = $state<string | null>(null);
+</script>
+
+<Select {items} label="Fruit" bind:value placeholder="Select..." />
+<Combobox {items} label="Fruit" bind:value />
+```
+
+Use `DateField` as the default accessible date input:
+
+```svelte
+<script lang="ts">
+	import type { DateValue } from 'compote-ui';
+
+	let value = $state<DateValue | null>(null);
+</script>
+
+<DateField label="Date" bind:value />
+```
+
+Use `DateRangeField` for ranges:
+
+```svelte
+<script lang="ts">
+	import type { DateValue } from 'compote-ui';
+
+	let range = $state<DateValue[]>([]);
+</script>
+
+<DateRangeField label="Range" bind:value={range} />
+```
+
+Use `DateInput` when binding existing `string`, `Date`, or `DateValue` values without a calendar popup.
+
+`PhoneInput` stores E.164 values:
+
+```svelte
+<script lang="ts">
+	let phone = $state('');
+	let country = $state(null);
+	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:
+
+```svelte
+<Listbox.Root {items} bind:value={selected}>
+	<Listbox.Label>Pick items</Listbox.Label>
+	<Listbox.Input placeholder="Search..." />
+	<Listbox.Content>
+		{#snippet items({ items })}
+			{#each items as item (item.value)}
+				<Listbox.Item {item}>
+					<Listbox.ItemText>{item.label}</Listbox.ItemText>
+					<Listbox.ItemIndicator />
+				</Listbox.Item>
+			{/each}
+			<Listbox.Empty>No results</Listbox.Empty>
+		{/snippet}
+	</Listbox.Content>
+</Listbox.Root>
+```

package/skills/component-usage/references/interactive-components.md

@@ -0,0 +1,33 @@
+# Interactive Components
+
+Use `Toggle` for one standalone binary action:
+
+```svelte
+<script lang="ts">
+	let favorite = $state(false);
+</script>
+
+<Toggle bind:pressed={favorite} aria-label="Toggle favorite">Favorite</Toggle>
+```
+
+Use `ToggleGroup` for toolbar-style groups:
+
+```svelte
+<script lang="ts">
+	let alignment = $state(['left']);
+</script>
+
+<ToggleGroup.Root bind:value={alignment} icon>
+	<ToggleGroup.Item value="left">
+		<AlignLeft />
+	</ToggleGroup.Item>
+	<ToggleGroup.Item value="center">
+		<AlignCenter />
+	</ToggleGroup.Item>
+	<ToggleGroup.Item value="right">
+		<AlignRight />
+	</ToggleGroup.Item>
+</ToggleGroup.Root>
+```
+
+`Toggle` defaults to `variant="ghost"`. `ToggleGroup` defaults to `variant="outline"`.

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

@@ -0,0 +1,82 @@
+# Layout And Display
+
+Tabs:
+
+```svelte
+<Tabs.Root bind:value={tab} defaultValue="account">
+	<Tabs.List>
+		<Tabs.Trigger value="account">Account</Tabs.Trigger>
+		<Tabs.Trigger value="settings">Settings</Tabs.Trigger>
+		<Tabs.Indicator />
+	</Tabs.List>
+	<Tabs.Content value="account">Account content</Tabs.Content>
+	<Tabs.Content value="settings">Settings content</Tabs.Content>
+</Tabs.Root>
+```
+
+Splitter fills its container:
+
+```svelte
+<div class="h-64">
+	{#snippet left()}
+		<div class="p-3">Left</div>
+	{/snippet}
+	{#snippet right()}
+		<div class="p-3">Right</div>
+	{/snippet}
+
+	<Splitter
+		panels={[
+			{ id: 'left', minSize: 20, content: left },
+			{ id: 'right', minSize: 20, content: right }
+		]}
+	/>
+</div>
+```
+
+For nested splitters, use Ark UI directly with one shared registry:
+
+```svelte
+<script lang="ts">
+	import { Splitter } from '@ark-ui/svelte/splitter';
+
+	const registry = Splitter.createRegistry();
+</script>
+```
+
+ScrollArea needs explicit size:
+
+```svelte
+<ScrollArea.Root class="h-80 w-56">
+	<ScrollArea.Viewport>
+		<ScrollArea.Content class="p-3">Content</ScrollArea.Content>
+	</ScrollArea.Viewport>
+	<ScrollArea.Scrollbar orientation="vertical">
+		<ScrollArea.Thumb />
+	</ScrollArea.Scrollbar>
+</ScrollArea.Root>
+```
+
+Vertical Carousel needs explicit height:
+
+```svelte
+<Carousel.Root orientation="vertical" class="h-[512px]" slideCount={images.length}>
+	<Carousel.Control>
+		<Carousel.ItemGroup>
+			{#each images as image, index (image.src)}
+				<Carousel.Item {index}>
+					<img src={image.src} alt={image.alt} class="h-full w-full object-cover" />
+				</Carousel.Item>
+			{/each}
+		</Carousel.ItemGroup>
+	</Carousel.Control>
+</Carousel.Root>
+```
+
+TreeView fills its container:
+
+```svelte
+<div class="h-80 rounded border">
+	<TreeView {items} label="Files" bind:selectedValue={selected} />
+</div>
+```