@toa.io/extensions.configuration 1.0.0-alpha.273 → 1.0.0-alpha.274

package/ui/.agents/skills/shadcn-svelte/rules/forms.md

@@ -0,0 +1,234 @@
+# Forms & Inputs
+
+## Contents
+
+- Forms use Field.FieldGroup + Field.Field
+- InputGroup requires InputGroup.Input/InputGroup.Textarea
+- Buttons inside inputs use InputGroup.Root + InputGroup.Addon
+- Option sets (2–7 choices) use ToggleGroup.Root + ToggleGroup.Item
+- Field.FieldSet + Field.FieldLegend for grouping related fields
+- Field validation and disabled states
+
+---
+
+## Forms use Field.FieldGroup + Field.Field
+
+Always use `Field.FieldGroup` + `Field.Field` — never raw `div` with `space-y-*`:
+
+```svelte
+<script lang="ts">
+  import * as Field from "$lib/components/ui/field";
+  import { Input } from "$lib/components/ui/input";
+</script>
+
+<Field.FieldGroup>
+  <Field.Field>
+    <Field.FieldLabel for="email">Email</Field.FieldLabel>
+    <Input id="email" type="email" />
+  </Field.Field>
+  <Field.Field>
+    <Field.FieldLabel for="password">Password</Field.FieldLabel>
+    <Input id="password" type="password" />
+  </Field.Field>
+</Field.FieldGroup>
+```
+
+Use `Field` with `orientation="horizontal"` for settings pages. Use `Field.FieldLabel` with `class="sr-only"` for visually hidden labels.
+
+**Choosing form controls:**
+
+- Simple text input → `Input`
+- Dropdown with predefined options → `Select`
+- Searchable dropdown → `Combobox`
+- Native HTML select (no JS) → `native-select`
+- Boolean toggle → `Switch` (for settings) or `Checkbox` (for forms)
+- Single choice from few options → `RadioGroup`
+- Toggle between 2–5 options → `ToggleGroup.Root` + `ToggleGroup.Item`
+- OTP/verification code → `InputOTP`
+- Multi-line text → `Textarea`
+
+---
+
+## InputGroup requires InputGroup.Input/InputGroup.Textarea
+
+Never use raw `Input` or `Textarea` inside an `InputGroup.Root`.
+
+**Incorrect:**
+
+```svelte
+<script lang="ts">
+  import * as InputGroup from "$lib/components/ui/input-group";
+  import { Input } from "$lib/components/ui/input";
+</script>
+
+<InputGroup.Root>
+  <Input placeholder="Search..." />
+</InputGroup.Root>
+```
+
+**Correct:**
+
+```svelte
+<script lang="ts">
+  import * as InputGroup from "$lib/components/ui/input-group";
+</script>
+
+<InputGroup.Root>
+  <InputGroup.Input placeholder="Search..." />
+</InputGroup.Root>
+```
+
+---
+
+## Buttons inside inputs use InputGroup.Root + InputGroup.Addon
+
+Never place a `Button` directly inside or adjacent to an `Input` with custom positioning.
+
+**Incorrect:**
+
+```svelte
+<script lang="ts">
+  import { Input } from "$lib/components/ui/input";
+  import { Button } from "$lib/components/ui/button";
+  import SearchIcon from "@lucide/svelte/icons/search";
+</script>
+
+<div class="relative">
+  <Input placeholder="Search..." class="pr-10" />
+  <Button class="absolute top-0 right-0" size="icon">
+    <SearchIcon />
+  </Button>
+</div>
+```
+
+**Correct:**
+
+```svelte
+<script lang="ts">
+  import * as InputGroup from "$lib/components/ui/input-group";
+  import { Button } from "$lib/components/ui/button";
+  import SearchIcon from "@lucide/svelte/icons/search";
+</script>
+
+<InputGroup.Root>
+  <InputGroup.Input placeholder="Search..." />
+  <InputGroup.Addon>
+    <Button size="icon">
+      <SearchIcon data-icon="inline-start" />
+    </Button>
+  </InputGroup.Addon>
+</InputGroup.Root>
+```
+
+---
+
+## Option sets (2–7 choices) use ToggleGroup.Root + ToggleGroup.Item
+
+Don't manually loop `Button` components with active state.
+
+**Incorrect:**
+
+```svelte
+<script lang="ts">
+  import { Button } from "$lib/components/ui/button";
+  let selected = $state("daily");
+</script>
+
+<div class="flex gap-2">
+  {#each ["daily", "weekly", "monthly"] as option (option)}
+    <Button
+      variant={selected === option ? "default" : "outline"}
+      onclick={() => (selected = option)}
+    >
+      {option}
+    </Button>
+  {/each}
+</div>
+```
+
+**Correct:**
+
+```svelte
+<script lang="ts">
+  import * as ToggleGroup from "$lib/components/ui/toggle-group";
+  let selected = $state("daily");
+</script>
+
+<ToggleGroup.Root bind:value={selected} spacing={2}>
+  <ToggleGroup.Item value="daily">Daily</ToggleGroup.Item>
+  <ToggleGroup.Item value="weekly">Weekly</ToggleGroup.Item>
+  <ToggleGroup.Item value="monthly">Monthly</ToggleGroup.Item>
+</ToggleGroup.Root>
+```
+
+Combine with `Field` for labelled toggle groups:
+
+```svelte
+<script lang="ts">
+  import * as Field from "$lib/components/ui/field";
+  import * as ToggleGroup from "$lib/components/ui/toggle-group";
+</script>
+
+<Field.Field orientation="horizontal">
+  <Field.FieldTitle id="theme-label">Theme</Field.FieldTitle>
+  <ToggleGroup.Root aria-labelledby="theme-label" spacing={2}>
+    <ToggleGroup.Item value="light">Light</ToggleGroup.Item>
+    <ToggleGroup.Item value="dark">Dark</ToggleGroup.Item>
+    <ToggleGroup.Item value="system">System</ToggleGroup.Item>
+  </ToggleGroup.Root>
+</Field.Field>
+```
+
+---
+
+## Field.FieldSet + Field.FieldLegend for grouping related fields
+
+Use `Field.FieldSet` + `Field.FieldLegend` for related checkboxes, radios, or switches — not `div` with a heading:
+
+```svelte
+<script lang="ts">
+  import * as Field from "$lib/components/ui/field";
+  import { Checkbox } from "$lib/components/ui/checkbox";
+</script>
+
+<Field.FieldSet>
+  <Field.FieldLegend variant="label">Preferences</Field.FieldLegend>
+  <Field.FieldDescription>Select all that apply.</Field.FieldDescription>
+  <Field.FieldGroup class="gap-3">
+    <Field.Field orientation="horizontal">
+      <Checkbox id="dark" />
+      <Field.FieldLabel for="dark" class="font-normal"
+        >Dark mode</Field.FieldLabel
+      >
+    </Field.Field>
+  </Field.FieldGroup>
+</Field.FieldSet>
+```
+
+---
+
+## Field validation and disabled states
+
+Both attributes are needed — `data-invalid`/`data-disabled` styles the field (label, description), while `aria-invalid`/`disabled` styles the control.
+
+```svelte
+<script lang="ts">
+  import * as Field from "$lib/components/ui/field";
+  import { Input } from "$lib/components/ui/input";
+</script>
+
+<!-- Invalid. -->
+<Field.Field data-invalid>
+  <Field.FieldLabel for="email">Email</Field.FieldLabel>
+  <Input id="email" aria-invalid />
+  <Field.FieldDescription>Invalid email address.</Field.FieldDescription>
+</Field.Field>
+
+<!-- Disabled. -->
+<Field.Field data-disabled>
+  <Field.FieldLabel for="email">Email</Field.FieldLabel>
+  <Input id="email" disabled />
+</Field.Field>
+```
+
+Works for all controls: `Input`, `Textarea`, `Select`, `Checkbox`, `RadioGroupItem`, `Switch`, `Slider`, `NativeSelect`, `InputOTP`.

package/ui/.agents/skills/shadcn-svelte/rules/icons.md

@@ -0,0 +1,107 @@
+# Icons
+
+**Always use the project's configured `iconLibrary` for imports.** Check the `iconLibrary` field in `components.json`: `lucide` → `@lucide/svelte`, `tabler` → `@tabler/icons-svelte`, etc. Never assume `@lucide/svelte`.
+
+---
+
+## Icons in Button use data-icon attribute
+
+Add `data-icon="inline-start"` (prefix) or `data-icon="inline-end"` (suffix) to the icon. No sizing classes on the icon.
+
+**Incorrect:**
+
+```svelte
+<script lang="ts">
+  import { Button } from "$lib/components/ui/button";
+  import SearchIcon from "@lucide/svelte/icons/search";
+</script>
+
+<Button>
+  <SearchIcon class="mr-2 size-4" />
+  Search
+</Button>
+```
+
+**Correct:**
+
+```svelte
+<script lang="ts">
+  import { Button } from "$lib/components/ui/button";
+  import SearchIcon from "@lucide/svelte/icons/search";
+  import ArrowRightIcon from "@lucide/svelte/icons/arrow-right";
+</script>
+
+<Button>
+  <SearchIcon data-icon="inline-start" />
+  Search
+</Button>
+
+<Button>
+  Next
+  <ArrowRightIcon data-icon="inline-end" />
+</Button>
+```
+
+---
+
+## No sizing classes on icons inside components
+
+Components handle icon sizing via CSS. Don't add `size-4`, `w-4 h-4`, or other sizing classes to icons inside `<Button>`, `DropdownMenu.Item`, `Alert.Root`, `Sidebar.*`, or other shadcn-svelte components — unless the user explicitly asks for custom icon sizes.
+
+**Incorrect:**
+
+```svelte
+<script lang="ts">
+  import { Button } from "$lib/components/ui/button";
+  import SearchIcon from "@lucide/svelte/icons/search";
+</script>
+
+<Button>
+  <SearchIcon class="size-4" data-icon="inline-start" />
+  Search
+</Button>
+```
+
+**Correct:**
+
+```svelte
+<script lang="ts">
+  import { Button } from "$lib/components/ui/button";
+  import SearchIcon from "@lucide/svelte/icons/search";
+</script>
+
+<Button>
+  <SearchIcon data-icon="inline-start" />
+  Search
+</Button>
+```
+
+The same applies to icons inside `DropdownMenu.Item`, sidebar items, and other menu rows — no extra sizing classes on the icon component.
+
+---
+
+## Pass icons as components, not string keys
+
+Use a component reference, not a string key to a lookup map.
+
+**Incorrect:**
+
+```svelte
+<!-- String key lookup — avoid -->
+<DynamicIcon name="check" />
+```
+
+**Correct:**
+
+```svelte
+<script lang="ts">
+  import type { Component } from "svelte";
+  import CheckIcon from "@lucide/svelte/icons/check";
+
+  let { Icon }: { Icon: Component } = $props();
+</script>
+
+<Icon />
+
+<!-- <StatusBadge Icon={CheckIcon} /> -->
+```

package/ui/.agents/skills/shadcn-svelte/rules/styling.md

@@ -0,0 +1,195 @@
+# Styling & Customization
+
+See [customization.md](../customization.md) for theming, CSS variables, and adding custom colors.
+
+## Contents
+
+- Semantic colors
+- Built-in variants first
+- class for layout only
+- No space-x-_ / space-y-_
+- Prefer size-_ over w-_ h-\* when equal
+- Prefer truncate shorthand
+- No manual dark: color overrides
+- Use cn() for conditional classes
+- No manual z-index on overlay components
+
+---
+
+## Semantic colors
+
+**Incorrect:**
+
+```svelte
+<div class="bg-blue-500 text-white">
+  <p class="text-gray-600">Secondary text</p>
+</div>
+```
+
+**Correct:**
+
+```svelte
+<div class="bg-primary text-primary-foreground">
+  <p class="text-muted-foreground">Secondary text</p>
+</div>
+```
+
+---
+
+## No raw color values for status/state indicators
+
+For positive, negative, or status indicators, use Badge variants, semantic tokens like `text-destructive`, or define custom CSS variables — don't reach for raw Tailwind colors.
+
+**Incorrect:**
+
+```svelte
+<span class="text-emerald-600">+20.1%</span>
+<span class="text-green-500">Active</span>
+<span class="text-red-600">-3.2%</span>
+```
+
+**Correct:**
+
+```svelte
+<script lang="ts">
+  import { Badge } from "$lib/components/ui/badge";
+</script>
+
+<Badge variant="secondary">+20.1%</Badge>
+<Badge>Active</Badge>
+<span class="text-destructive">-3.2%</span>
+```
+
+If you need a success/positive color that doesn't exist as a semantic token, use a Badge variant or ask the user about adding a custom CSS variable to the theme (see [customization.md](../customization.md)).
+
+---
+
+## Built-in variants first
+
+**Incorrect:**
+
+```svelte
+<script lang="ts">
+  import { Button } from "$lib/components/ui/button";
+</script>
+
+<Button class="border-input hover:bg-accent border bg-transparent"
+  >Click me</Button
+>
+```
+
+**Correct:**
+
+```svelte
+<script lang="ts">
+  import { Button } from "$lib/components/ui/button";
+</script>
+
+<Button variant="outline">Click me</Button>
+```
+
+---
+
+## class for layout only
+
+Use `class` for layout (e.g. `max-w-md`, `mx-auto`, `mt-4`), **not** for overriding component colors or typography. To change colors, use semantic tokens, built-in variants, or CSS variables.
+
+**Incorrect:**
+
+```svelte
+<script lang="ts">
+  import * as Card from "$lib/components/ui/card";
+</script>
+
+<Card.Root class="bg-blue-100 font-bold text-blue-900">
+  <Card.Content>Dashboard</Card.Content>
+</Card.Root>
+```
+
+**Correct:**
+
+```svelte
+<script lang="ts">
+  import * as Card from "$lib/components/ui/card";
+</script>
+
+<Card.Root class="mx-auto max-w-md">
+  <Card.Content>Dashboard</Card.Content>
+</Card.Root>
+```
+
+To customize a component's appearance, prefer these approaches in order:
+
+1. **Built-in variants** — `variant="outline"`, `variant="destructive"`, etc.
+2. **Semantic color tokens** — `bg-primary`, `text-muted-foreground`.
+3. **CSS variables** — define custom colors in the global CSS file (see [customization.md](../customization.md)).
+
+---
+
+## No space-x-_ / space-y-_
+
+Use `gap-*` instead. `space-y-4` → `flex flex-col gap-4`. `space-x-2` → `flex gap-2`.
+
+```svelte
+<script lang="ts">
+  import { Input } from "$lib/components/ui/input";
+  import { Button } from "$lib/components/ui/button";
+</script>
+
+<div class="flex flex-col gap-4">
+  <Input />
+  <Input />
+  <Button>Submit</Button>
+</div>
+```
+
+---
+
+## Prefer size-_ over w-_ h-\* when equal
+
+`size-10` not `w-10 h-10`. Applies to icons, avatars, skeletons, etc.
+
+---
+
+## Prefer truncate shorthand
+
+`truncate` not `overflow-hidden text-ellipsis whitespace-nowrap`.
+
+---
+
+## No manual dark: color overrides
+
+Use semantic tokens — they handle light/dark via CSS variables. `bg-background text-foreground` not `bg-white dark:bg-gray-950`.
+
+---
+
+## Use cn() for conditional classes
+
+Use the `cn()` utility from the project for conditional or merged class names. Don't write manual ternaries in `class` strings.
+
+**Incorrect:**
+
+```svelte
+<script lang="ts">
+  let isActive = $state(false);
+</script>
+
+<div class={`flex items-center ${isActive ? "bg-primary text-primary-foreground" : "bg-muted"}`}>
+```
+
+**Correct:**
+
+```svelte
+<script lang="ts">
+  import { cn } from "$lib/utils";
+  let isActive = $state(false);
+</script>
+
+<div class={cn("flex items-center", isActive ? "bg-primary text-primary-foreground" : "bg-muted")}>
+```
+
+---
+
+## No manual z-index on overlay components
+
+`Dialog`, `Sheet`, `Drawer`, `AlertDialog`, `DropdownMenu`, `Popover`, `Tooltip`, `HoverCard` handle their own stacking. Never add `z-50` or `z-[999]`.

package/ui/.agents/skills/svas/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: svas
+description: >
+  Async Svelte stores (svas): fetching, caching, revalidation, persistence.
+  Use when UI presents data from the API.
+---
+
+# svas — Svelte Async Stores
+
+Stores that fetch lazily, cache, revalidate, and persist. Every store emits one of three types:
+
+```ts
+type Maybe<T, E extends Error = Error> = null | T | E
+//   null  → no data yet (loading / cleared / not fetched)
+//   T     → resolved value
+//   E     → fetch error (errors are values, never thrown)
+```
+
+```ts
+import {
+  value, values, collection,           // stores
+  ok, ensure, having, awaited, once,   // guards & awaiting
+  combined, sync, Async,               // compose & render
+  type Maybe
+} from 'svas'
+```
+
+## Shared lifecycle
+
+Every store fetches on **first subscribe**, then auto-revalidates. Common options:
+
+| Option | Meaning |
+|--------|---------|
+| `get` | fetcher returning `Promise<T \| Error>` |
+| `revalidate` | ms before re-fetch (default `300_000`; `Infinity` disables) |
+| `persist` | mirror into local storage under this key |
+| `session` | use `sessionStorage` instead of `localStorage` |
+| `stale` | keep previous value visible while revalidating (default `false`) |
+| `bind` | `Readable<unknown \| null>` — reset/clear store when bound store is `null` (tie data to a user) |
+| `default` | initial value when nothing is persisted |
+
+## Stores
+
+All stores implements Readable interface from svelte/store.
+
+Use `persist` whenever it makes sense to persist the data, it will vastly speed up the initial load.
+If store contains user-bound data, use `bind` to reset the store when the user is logged out.
+
+### `value<T>` — one async value
+
+`Writable<T | null>`. For single fetched values, auth tokens, transient UI flags.
+
+```ts
+const me = value<User>({ get: () => api.me(), persist: 'user' })
+const seen = value<number>({ persist: 'seen', default: 0 }) // transient/local-only
+```
+
+Methods: `set(v)`, `update(fn)`, `extract(): T | null` (sync read), `sync()` (revalidate if stale).
+
+### `values<T>` — keyed cache
+
+A map of independent `Readable<Maybe<T>>` lifecycles, one per key.
+
+```ts
+const products = values<Product>({ get: (id) => api.product(id), stale: true, persist: 'products' })
+
+const one = products.get('42')      // Readable<Maybe<Product>>, fetches if missing
+products.set('42', next)            // write by key
+products.extract('42')              // Product | null, sync
+```
+
+Methods: `get(key, { fetch? })` · `set(key, v, { stash? })` · `reset(key)` (restore stashed value) · `extract(key)` · `delete(key)` · `clear()`.
+
+Extra options: `permanent` (don't revalidate persisted entries on startup). `stash: true` on `set` remembers the prior persisted value so `reset(key)` can roll back — use for optimistic updates.
+
+### `collection<T>` — list of `Identifiable` items
+
+`Readable<Maybe<T[]>>`. Items must have `{ id: string }`. Pass a `values` store to also observe items individually via `get(id)`.
+
+```ts
+const todos = collection<Todo>({
+  get: () => api.todos(),
+  values: values<Todo>(), // enables todos.get(id) / extract(id)
+  stale: true, 
+  persist: 'todos', 
+  bind: session
+})
+```
+
+Methods: `subscribe` · `add(item)` · `set(item, { add? })` (replace by id; `add` inserts if absent) · `update(id, fn, opts?)` · `delete(id)` · `replace(items)` · `get(id)`/`extract(id)` (require `values`) · `sync(): this` · `fetch(): Promise<this>`.
+
+Mutations mirror into the `values` store, so components subscribed via `get(id)` update without re-fetching.
+
+## Guards & extraction
+
+Never use `?.` on a `Maybe<T>` — an `Error` has no domain properties. Narrow first.
+
+```ts
+ok($store)          // boolean type guard: narrows Maybe<T> → T (excludes null | Error)
+ensure(store)       // sync read, THROWS if null/Error — use when value must exist now (e.g. unsafe net requests in response to user action)
+store.extract(key?) // sync read, T | null (ignores errors) — never throws
+```
+
+```ts
+if (ok($todos)) $todos.length        // typed as T
+items.filter((i) => ok(i.account) && !i.account.deleted)   // ✅ guard before access
+```
+
+## Awaiting
+
+```ts
+await having(store)   // first non-null value; REJECTS on Error — services needing auth
+await awaited(store)  // first non-null value; returns Error as a value (never rejects)
+await once(store, (v) => v === 'ready')   // first value satisfying a condition
+```
+
+## Compose & render
+
+### `<Async>` — render a `Maybe`
+
+```svelte
+<Async store={todos}>
+  {#snippet awaited(todos)}
+    <!-- here todos are T[] -->
+    {#each todos as t}<Row {t} />{/each}
+  {/snippet}
+  {#snippet waiting()}<Spinner />{/snippet}   <!-- optional; default loader otherwise -->
+  {#snippet error(e)}<Err {e} />{/snippet}    <!-- optional; default error UI otherwise -->
+</Async>
+```
+
+Props: `store` (required), `awaited` snippet (required), optional `waiting` / `error` snippets, `silent` (suppress default loader/error chrome). Combine with `combined` to await several at once.
+
+### `combined(...stores)`
+
+One `Maybe` from many: tuple when **all** resolve, first `Error`, else `null`. Spreadable.
+
+```svelte
+<Async store={combined(account, todos)}>
+  {#snippet awaited([account, todos])}
+    <!-- here account is U and todos is T[] -->
+    <Profile {account} />
+    {#each todos as t}<Row {t} />{/each}
+  {/snippet}
+</Async>
+```
+
+### `sync(store, item, { delete? })`
+
+Conflict-free update.
+
+T must implement interface Comparable { id: string; _version: number;_deleted?: number | null }
+
+Merge a versioned item into a `collection` or `value`, respecting `_version`; removes on `_deleted` (unless `delete: false`). For applying server/realtime events.
+
+```ts
+events.on('todos.sync', (todo) => sync(todos, todo))
+```
+
+## Rules
+
+- **Errors are values** — fetchers and services return `T | Error`; check `instanceof Error`, never `try/catch` for expected failures.
+- **Guard before access** — `ok()`/`ensure()`/`extract()`, never `?.` on `Maybe<T>`.
+- **One store per source** — derive everything else; don't duplicate fetched data into local state.
+- **Lazy by design** — a store does nothing until subscribed; `$store`, `<Async>`, `get`, `having`, or `.subscribe` triggers it.
+
+## Advanced
+
+For derived `Maybe` stores with live subscriptions/cleanup, realtime event wiring, linked/enriched entities, and optimistic update patterns, see [references/patterns.md](references/patterns.md).