compote-ui 0.62.1 → 0.62.2

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

@@ -0,0 +1,80 @@
+# Overlays And Floating UI
+
+`Dialog`, `Drawer`, `Menu`, `Popover`, `HoverCard`, `Tooltip`, and `Toast` are namespace exports.
+
+Dialog:
+
+```svelte
+<script lang="ts">
+	let open = $state(false);
+</script>
+
+<Dialog.Root bind:open>
+	<Dialog.Title>Confirm Action</Dialog.Title>
+	<Dialog.Description>This cannot be undone.</Dialog.Description>
+	<Dialog.Footer>
+		<Dialog.CloseTrigger>Cancel</Dialog.CloseTrigger>
+		<Button onclick={() => (open = false)}>Confirm</Button>
+	</Dialog.Footer>
+	<Dialog.CloseTrigger />
+</Dialog.Root>
+```
+
+Use `onOpenChange`, not `onClose`:
+
+```svelte
+<Dialog.Root
+	bind:open
+	onOpenChange={(details) => {
+		if (!details.open) handleClose();
+	}}
+>
+	<Dialog.Title>Title</Dialog.Title>
+</Dialog.Root>
+```
+
+Drawer content renders backdrop and positioner internally:
+
+```svelte
+<Drawer.Root bind:open>
+	<Drawer.Content>
+		<Drawer.CloseTrigger />
+		<Drawer.Header>
+			<Drawer.Title>Edit Record</Drawer.Title>
+		</Drawer.Header>
+		<Drawer.Body>Scrollable content</Drawer.Body>
+		<Drawer.Footer>
+			<Button variant="ghost" onclick={() => (open = false)}>Cancel</Button>
+			<Button>Save</Button>
+		</Drawer.Footer>
+	</Drawer.Content>
+</Drawer.Root>
+```
+
+AlertDialog is for confirmations:
+
+```svelte
+<AlertDialog
+	bind:open={deleteOpen}
+	title="Delete item?"
+	description="This action cannot be undone."
+	variant="destructive"
+	confirmLabel="Delete"
+	onConfirm={handleDelete}
+/>
+```
+
+Toast setup belongs in layout:
+
+```svelte
+<Toast.Toaster />
+```
+
+Then fire toasts anywhere:
+
+```ts
+import { toast } from 'compote-ui';
+
+toast.success('Saved');
+toast.error('Save failed', { description: 'Please try again.' });
+```

package/skills/data-table/SKILL.md

@@ -0,0 +1,247 @@
+---
+name: data-table
+description: >
+  Load when using compote-ui/data-table or compote-ui/data-table/virtual.
+  Covers TanStack Table v9 wrapper usage, createTable,
+  createDataTableColumnHelper, table columns, row selection, filters,
+  formatting, toolbars, virtualized imports, and optional peer dependencies.
+metadata:
+  type: composition
+  library: compote-ui
+  library_version: '0.62.1'
+requires:
+  - component-usage
+  - theming
+sources:
+  - package.json
+  - src/lib/components/data-table-v9/index.ts
+  - src/lib/components/data-table-v9/types.ts
+  - src/lib/components/data-table-v9/features.ts
+  - src/lib/components/data-table-v9/column-helper.ts
+  - src/lib/components/data-table-v9/create-table.svelte.ts
+  - src/lib/components/data-table-v9/data-table.svelte
+  - src/lib/components/data-table-v9/virtual/data-table-virtualized.svelte
+  - src/lib/components/data-table-v9/virtual/data-table-virtual-rows.svelte
+---
+
+This skill builds on component-usage and theming. Read those first for Compote namespace imports and theme token behavior.
+
+# Compote UI — Data Table
+
+Use `compote-ui/data-table` for regular tables and `compote-ui/data-table/virtual` for virtualized rows.
+
+## Integration Setup
+
+```bash
+bun add @tanstack/svelte-table
+```
+
+```svelte
+<script lang="ts">
+	import * as DataTable from 'compote-ui/data-table';
+
+	type Invoice = {
+		id: string;
+		customer: string;
+		total: number;
+		paid: boolean;
+	};
+
+	let invoices = $state<Invoice[]>([
+		{ id: 'inv_1', customer: 'Ada', total: 1200, paid: true },
+		{ id: 'inv_2', customer: 'Grace', total: 800, paid: false }
+	]);
+
+	const col = DataTable.createDataTableColumnHelper<Invoice>();
+	const columns = col.columns([
+		col.accessor('id', { header: 'ID', enableHiding: false }),
+		col.accessor('customer', { header: 'Customer', grow: true }),
+		col.accessor('total', { header: 'Total', type: 'currency', align: 'right' }),
+		col.accessor('paid', { header: 'Paid', type: 'boolean', align: 'center' })
+	]);
+
+	const table = DataTable.createTable({
+		get data() {
+			return invoices;
+		},
+		columns,
+		getRowId: (row) => row.id,
+		enableRowSelection: true
+	});
+</script>
+
+<DataTable.Toolbar>
+	<DataTable.Title>Invoices</DataTable.Title>
+	{#snippet center()}
+		<DataTable.Search {table} class="w-56" />
+	{/snippet}
+	{#snippet right()}
+		<DataTable.ColumnFilter {table} />
+		<DataTable.ColumnVisibility {table} />
+	{/snippet}
+</DataTable.Toolbar>
+
+<div class="h-96 min-h-0">
+	<DataTable.Root {table} caption="Invoices" />
+</div>
+```
+
+## Core Integration Patterns
+
+### Use accessorFn with an explicit id
+
+```ts
+const columns = col.columns([
+	col.accessorFn((row) => row.quantity * row.price, {
+		id: 'total',
+		header: 'Total',
+		type: 'currency',
+		align: 'right'
+	})
+]);
+```
+
+### Make runtime column changes reactive
+
+```ts
+const idCol = col.accessor('id', { header: 'ID', enableHiding: false });
+const totalCol = col.accessor('total', { header: 'Total', type: 'currency' });
+
+let columns = $state.raw([idCol]);
+
+const table = DataTable.createTable({
+	get data() {
+		return invoices;
+	},
+	get columns() {
+		return columns;
+	},
+	getRowId: (row) => row.id
+});
+
+function toggleTotal() {
+	columns = columns.includes(totalCol)
+		? columns.filter((column) => column !== totalCol)
+		: [...columns, totalCol];
+}
+```
+
+### Use virtual import for large row sets
+
+```bash
+bun add @tanstack/svelte-virtual
+```
+
+```svelte
+<script lang="ts">
+	import * as VirtualDataTable from 'compote-ui/data-table/virtual';
+
+	const table = VirtualDataTable.createTable({
+		get data() {
+			return rows;
+		},
+		columns,
+		getRowId: (row) => row.id,
+		enableRowSelection: true
+	});
+</script>
+
+<div class="h-96 min-h-0">
+	<VirtualDataTable.Root {table} caption="Large dataset" />
+</div>
+```
+
+## Common Mistakes
+
+### CRITICAL Missing id for accessorFn column
+
+Wrong:
+
+```ts
+col.accessorFn((row) => row.a + row.b, { header: 'Total' });
+```
+
+Correct:
+
+```ts
+col.accessorFn((row) => row.a + row.b, { id: 'total', header: 'Total' });
+```
+
+Accessor function columns cannot derive a stable column id from a key.
+
+Source: `src/lib/components/data-table-v9/create-table.svelte.ts`
+
+### HIGH Non-reactive reassigned columns
+
+Wrong:
+
+```ts
+let columns = $state([idCol, nameCol]);
+const table = DataTable.createTable({ data: rows, columns });
+```
+
+Correct:
+
+```ts
+let columns = $state.raw([idCol, nameCol]);
+const table = DataTable.createTable({
+	get data() {
+		return rows;
+	},
+	get columns() {
+		return columns;
+	}
+});
+```
+
+Reassigned columns must be passed through a getter and kept raw so identity checks keep working.
+
+Source: `src/routes/components/data-table-v9/+page.svelte`, `src/lib/components/data-table-v9/create-table.svelte.ts`
+
+### HIGH Rendering table without height constraint
+
+Wrong:
+
+```svelte
+<DataTable.Root {table} />
+```
+
+Correct:
+
+```svelte
+<div class="h-96 min-h-0">
+	<DataTable.Root {table} caption="Invoices" />
+</div>
+```
+
+`DataTable.Root` fills its container and uses internal scrolling.
+
+Source: `src/lib/components/data-table-v9/data-table.svelte`
+
+### HIGH Importing virtual table without optional peer
+
+Wrong:
+
+```ts
+import * as VirtualDataTable from 'compote-ui/data-table/virtual';
+```
+
+Correct:
+
+```bash
+bun add @tanstack/svelte-virtual
+```
+
+```ts
+import * as VirtualDataTable from 'compote-ui/data-table/virtual';
+```
+
+The virtual subpath imports `@tanstack/svelte-virtual`.
+
+Source: `package.json`, `src/lib/components/data-table-v9/virtual/data-table-virtual-rows.svelte`
+
+## References
+
+- [Column options](references/column-options.md)
+- [Table state and reactivity](references/table-state-and-reactivity.md)
+- [Virtual table](references/virtual-table.md)

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

@@ -0,0 +1,53 @@
+# Column Options
+
+Column helper:
+
+```ts
+const col = DataTable.createDataTableColumnHelper<Row>();
+```
+
+Accessors:
+
+```ts
+col.accessor('fieldName', { header: 'Field' });
+col.accessorFn((row) => row.a + row.b, { id: 'sum', header: 'Sum' });
+col.group('Group', [col.accessor('name', { header: 'Name' })]);
+col.columns([col.accessor('id', { header: 'ID' })]);
+```
+
+Common options:
+
+- `header: string`
+- `type?: 'text' | 'number' | 'currency' | 'percent' | 'boolean' | 'select' | 'url' | 'phone' | 'date' | 'time' | 'date-time'`
+- `align?: 'left' | 'center' | 'right'`
+- `size?: number`
+- `minSize?: number`
+- `maxSize?: number`
+- `enableResizing?: boolean`
+- `enableHiding?: boolean`
+- `enableSorting?: boolean`
+- `enableColumnFilter?: boolean`
+- `filterFn?: FilterFn | string`
+- `formatOptions?: Intl.NumberFormatOptions | Intl.DateTimeFormatOptions`
+- `formatLocale?: string`
+- `cell?: (value, row) => string | number | boolean | null | undefined`
+- `cellComponent?: Component`
+- `cellProps?: (value, row) => Record<string, unknown>`
+- `cellSnippet?: Snippet`
+- `pinned?: 'left' | 'right'`
+- `grow?: boolean`
+- `sum?: boolean`
+- `footer?: (values: unknown[]) => string | number | undefined`
+
+Type defaults:
+
+- `number`, `currency`: right aligned, size `120`
+- `percent`: right aligned, size `100`
+- `date`: center aligned, size `110`
+- `time`: center aligned, size `80`
+- `date-time`: center aligned, size `160`
+- `boolean`: center aligned, size `90`
+- `url`: center aligned, sorting disabled, size `60`
+- `phone`: left aligned, size `160`
+
+Use one `grow: true` column to absorb extra horizontal space.

package/skills/data-table/references/table-state-and-reactivity.md

@@ -0,0 +1,45 @@
+# Table State And Reactivity
+
+Use reactive getters for state that changes:
+
+```ts
+const table = DataTable.createTable({
+	get data() {
+		return rows;
+	},
+	get columns() {
+		return columns;
+	},
+	getRowId: (row) => row.id
+});
+```
+
+Use `$state.raw` for column arrays that are reassigned:
+
+```ts
+let columns = $state.raw([idCol, nameCol]);
+```
+
+Read table state:
+
+```ts
+const selected = $derived(table.getSelectedRowModel().rows.map((row) => row.original));
+const sorting = $derived(table.store.state.sorting);
+const filters = $derived(table.store.state.columnFilters);
+```
+
+Persist column visibility with the observer callback:
+
+```ts
+const table = DataTable.createTable({
+	get data() {
+		return rows;
+	},
+	columns,
+	onColumnVisibilityChange: (visibility) => {
+		localStorage.setItem('column-visibility', JSON.stringify(visibility));
+	}
+});
+```
+
+Initial `columnVisibility`, `columnSizing`, and `columnPinning` are computed when the table is created. Columns added later default to visible and use their own size.

package/skills/data-table/references/virtual-table.md

@@ -0,0 +1,44 @@
+# Virtual Table
+
+Use `compote-ui/data-table/virtual` for large row counts.
+
+```bash
+bun add @tanstack/svelte-virtual
+```
+
+```svelte
+<script lang="ts">
+	import * as VirtualDataTable from 'compote-ui/data-table/virtual';
+
+	const table = VirtualDataTable.createTable({
+		get data() {
+			return rows;
+		},
+		columns,
+		getRowId: (row) => row.id,
+		enableRowSelection: true
+	});
+</script>
+
+<VirtualDataTable.Toolbar>
+	<VirtualDataTable.Title>Large Table</VirtualDataTable.Title>
+	{#snippet center()}
+		<VirtualDataTable.Search {table} class="w-56" />
+	{/snippet}
+	{#snippet right()}
+		<VirtualDataTable.ColumnFilter {table} />
+		<VirtualDataTable.ColumnVisibility {table} />
+	{/snippet}
+</VirtualDataTable.Toolbar>
+
+<div class="h-96 min-h-0">
+	<VirtualDataTable.Root {table} caption="Large dataset" />
+</div>
+```
+
+Differences from regular table:
+
+- Import path is `compote-ui/data-table/virtual`.
+- Add the optional `@tanstack/svelte-virtual` peer.
+- Rows are absolutely positioned with transforms.
+- The table uses grid layout internally.

package/skills/getting-started/SKILL.md

@@ -0,0 +1,173 @@
+---
+name: getting-started
+description: >
+  Load when setting up compote-ui in a Svelte or SvelteKit app. Covers npm install,
+  bun add, importing tailwindcss before compote-ui/theme.css, first imports from
+  compote-ui, Toast.Toaster placement, Svelte 5 runes usage, and peer dependency basics.
+metadata:
+  type: lifecycle
+  library: compote-ui
+  library_version: '0.62.1'
+sources:
+  - package.json
+  - README.md
+  - CLAUDE.md
+  - AGENTS.md
+  - src/lib/index.ts
+  - src/routes/layout.css
+  - src/lib/theme.css
+---
+
+# Compote UI — Getting Started
+
+Use Svelte 5 runes, import Tailwind first, then import `compote-ui/theme.css`.
+
+## Setup
+
+```bash
+npm install compote-ui
+```
+
+```bash
+bun add compote-ui
+```
+
+```css
+@import 'tailwindcss';
+@import 'compote-ui/theme.css';
+```
+
+```svelte
+<script lang="ts">
+	import { Button, Card } from 'compote-ui';
+</script>
+
+<Card.Root>
+	<Card.Header>
+		<Card.Title>Account</Card.Title>
+		<Card.Description>Manage account settings.</Card.Description>
+	</Card.Header>
+	<Card.Content>
+		<Button>Save</Button>
+	</Card.Content>
+</Card.Root>
+```
+
+## Core Patterns
+
+### Use Svelte 5 bindings
+
+```svelte
+<script lang="ts">
+	import { Dialog, Button } from 'compote-ui';
+
+	let open = $state(false);
+</script>
+
+<Button onclick={() => (open = true)}>Open</Button>
+
+<Dialog.Root bind:open>
+	<Dialog.Title>Confirm</Dialog.Title>
+	<Dialog.Description>Confirm the action.</Dialog.Description>
+</Dialog.Root>
+```
+
+### Render toast output once
+
+```svelte
+<script lang="ts">
+	import { Toast } from 'compote-ui';
+
+	let { children } = $props();
+</script>
+
+<Toast.Toaster />
+{@render children()}
+```
+
+```ts
+import { toast } from 'compote-ui';
+
+toast.success('Saved');
+```
+
+### Add optional peers only when used
+
+```bash
+bun add @tanstack/svelte-table
+```
+
+```bash
+bun add @tanstack/svelte-virtual
+```
+
+Use `@tanstack/svelte-table` with `compote-ui/data-table`; add `@tanstack/svelte-virtual` only with `compote-ui/data-table/virtual`.
+
+## Common Mistakes
+
+### CRITICAL Missing theme CSS import
+
+Wrong:
+
+```css
+@import 'tailwindcss';
+```
+
+Correct:
+
+```css
+@import 'tailwindcss';
+@import 'compote-ui/theme.css';
+```
+
+Components rely on `theme.css` for Compote CSS variables and Tailwind token definitions.
+
+Source: `src/lib/theme.css`, `src/routes/layout.css`
+
+### HIGH Using Svelte legacy props
+
+Wrong:
+
+```svelte
+<script lang="ts">
+	export let open = false;
+	$: visible = open;
+</script>
+```
+
+Correct:
+
+```svelte
+<script lang="ts">
+	let { open = $bindable(false) } = $props();
+	const visible = $derived(open);
+</script>
+```
+
+The project uses Svelte 5 runes mode globally.
+
+Source: `CLAUDE.md`, `svelte.config.js`
+
+### MEDIUM Installing table peers for every app
+
+Wrong:
+
+```bash
+bun add compote-ui @tanstack/svelte-table @tanstack/svelte-virtual
+```
+
+Correct:
+
+```bash
+bun add compote-ui
+bun add @tanstack/svelte-table
+bun add @tanstack/svelte-virtual
+```
+
+Install TanStack peers only when the consuming app imports the matching data-table subpath.
+
+Source: `package.json`, `src/lib/index.ts`
+
+## References
+
+- [Install and peers](references/install-and-peers.md)

package/skills/getting-started/references/install-and-peers.md

@@ -0,0 +1,45 @@
+# Install And Peers
+
+Consumer apps may use either npm or bun:
+
+```bash
+npm install compote-ui
+```
+
+```bash
+bun add compote-ui
+```
+
+Repository development uses bun exclusively:
+
+```bash
+bun install
+bun run check
+bun run lint
+```
+
+Peer dependency guidance:
+
+- `svelte`: required, Svelte 5.
+- `@tanstack/svelte-table`: required only for `compote-ui/data-table`.
+- `@tanstack/svelte-virtual`: required only for `compote-ui/data-table/virtual`.
+
+Consumer stylesheet setup:
+
+```css
+@import 'tailwindcss';
+@import 'compote-ui/theme.css';
+```
+
+App-level toast setup:
+
+```svelte
+<script lang="ts">
+	import { Toast } from 'compote-ui';
+
+	let { children } = $props();
+</script>
+
+<Toast.Toaster />
+{@render children()}
+```