@spaethtech/svelte-ui 0.1.10 → 0.3.1-dev.10.ff03a8d

package/docs/themes.md

@@ -0,0 +1,170 @@
+# CSS Variables Reference
+
+This document describes the CSS variables in the svelte-ui theme. The source of truth is
+`src/lib/theme.css` (shipped as `@spaethtech/svelte-ui/theme.css`); this doc mirrors it. Every token is
+**`--ui-*`-prefixed** — there are no unprefixed tokens and no per-component tokens.
+
+## Overview
+
+The library themes via CSS custom properties. There are **two themes only — light (default) and
+dark**. Dark follows the system preference automatically (`@media (prefers-color-scheme: dark)`);
+force either with the `.theme-light` / `.theme-dark` classes (see `ThemeSelector`).
+
+Consumers import the theme right after Tailwind:
+
+```css
+@import "tailwindcss";
+@import "@spaethtech/svelte-ui/theme.css";
+```
+
+## Palette — `--ui-color-*`
+
+### Core
+
+- `--ui-color-background` — main background for pages and containers
+- `--ui-color-text` — primary text color
+
+### Semantic
+
+- `--ui-color-primary` — primary brand color (blue)
+- `--ui-color-secondary` — secondary brand color (cyan)
+- `--ui-color-success` — success state (green)
+- `--ui-color-warning` — warning state (amber)
+- `--ui-color-error` — error/danger state (red) — the `danger` variant maps here
+- `--ui-color-info` — informational state (sky blue)
+
+## Interactive-surface tints — `--ui-accent` + hover / surface / active
+
+One shared tint language for every hover, section band, and pressed surface. Three steps of the
+**same** mix, from lightest to strongest:
+
+- `--ui-color-hover` — **4%** — row / option / ghost-button hover
+- `--ui-color-surface` — **8%** — header / footer / section bands (a notch darker than hover)
+- `--ui-color-active` — **12%** — pressed / held
+
+Each is `color-mix(in srgb, var(--ui-accent) N%, transparent)`. The **percentages are
+theme-independent** (identical in light and dark) — only the accent color flips.
+
+- `--ui-accent` — the color the tints mix from. **Defaults to `var(--ui-color-text)`**, so out of
+  the box these are neutral grey tints. Point it at a semantic color to tint a surface (this is how
+  a component `variant` colors its whole surface). Overriding `--ui-accent` requires the `.ui-accent`
+  re-mix class — see [Applying a theme](#theme-application) and the themes skill.
+
+## Border & radius — `--ui-border-*`
+
+- `--ui-border-radius` — `0.375rem` — corner radius for every surface (Card, Input, DataTable…)
+- `--ui-border-color` — `color-mix(in srgb, var(--ui-color-secondary) 30%, transparent)` — soft
+  internal divider (row separators, section splits)
+- `--ui-border-color-strong` — `var(--ui-color-secondary)` — prominent outer edge (Card frame,
+  Input, DataTable outer)
+- `--ui-border-color-strong-hover` — `color-mix(in srgb, var(--ui-color-secondary) 80%, black)` —
+  darker edge on hover for interactive controls
+
+## Sizing — the `size` axis (`sm` / `md` / `lg`)
+
+### Control heights
+
+- `--ui-height-sm` — `1.5rem` / 24px (`sm`)
+- `--ui-height` — `2rem` / 32px (`md`, **default**)
+- `--ui-height-lg` — `2.5rem` / 40px (`lg`)
+- `--ui-height-touch` — `2.75rem` / 44px — explicit touch target (WCAG/Apple min), **not** the `lg` size
+
+### Text
+
+- `--ui-text-sm` — `0.75rem` / 12px · `--ui-text` — `0.875rem` / 14px (default) · `--ui-text-lg` — `1rem` / 16px
+
+### Inline icons
+
+- `--ui-icon-sm` — `0.875rem` / 14px · `--ui-icon` — `1rem` / 16px (default) · `--ui-icon-lg` — `1.25rem` / 20px
+
+> Per-component **padding / gap** is NOT a token — each component maps the `size` prop to Tailwind
+> class maps (`Record<Size, string>`) internally. (The old `--ui-padding*` and `--ui-border` width
+> tokens were removed.)
+
+## Breakpoints (in `@theme`)
+
+Narrow-mobile tiers and an ultrawide tier on top of Tailwind's defaults, so `DataTable` column
+placements can target the full range:
+`4xs` 320px · `3xs` 360px · `2xs` 420px · `xs` 480px · `3xl` 1920px.
+
+## Theme values
+
+### Light (default)
+
+```css
+--ui-color-background: #ffffff;
+--ui-color-text: #111827;
+--ui-color-primary: #1d4ed8;
+--ui-color-secondary: #0891b2;
+--ui-color-success: #059669;
+--ui-color-warning: #d97706;
+--ui-color-error: #dc2626;
+--ui-color-info: #0ea5e9;
+```
+
+### Dark
+
+```css
+--ui-color-background: #111827;
+--ui-color-text: #f9fafb;
+--ui-color-primary: #2563eb;
+--ui-color-secondary: #06b6d4;
+--ui-color-success: #10b981;
+--ui-color-warning: #f59e0b;
+--ui-color-error: #ef4444;
+--ui-color-info: #06b6d4;
+```
+
+The sizing/text/icon tokens are theme-independent. The interactive tints use the same percentages
+in both themes — only `--ui-color-text` (hence `--ui-accent`) flips.
+
+## Usage in components
+
+Components reference these via Tailwind's arbitrary-value syntax:
+
+```svelte
+<!-- Text / background -->
+<div class="text-[var(--ui-color-text)] bg-[var(--ui-color-background)]">...</div>
+
+<!-- Border (color + radius tokens) -->
+<div
+  class="border [border-color:var(--ui-border-color-strong)] [border-radius:var(--ui-border-radius)]"
+>
+  ...
+</div>
+
+<!-- Hover / section / pressed surfaces — use the shared tints, not ad-hoc color-mix -->
+<div
+  class="[background-color:var(--ui-color-surface)] hover:[background-color:var(--ui-color-hover)]"
+>
+  ...
+</div>
+```
+
+For muted text or faint dividers, mix the text color: `color-mix(in srgb, var(--ui-color-text) 60%, transparent)`.
+
+## Theme application
+
+Precedence:
+
+1. Forced theme via `.theme-light` / `.theme-dark` — set on **`<html>`** by `ThemeSelector` and by
+   the pre-hydration script in `app.html`. A switcher **must** target `<html>` (documentElement),
+   never `<body>` — putting it on `<body>` leaves `<html>` on the system path and freezes the
+   accent-derived tints to the wrong theme.
+2. System preference via `@media (prefers-color-scheme: dark)`.
+3. Default light values.
+
+`ThemeSelector` manages switching (Auto / Light / Dark) and persists the choice in `localStorage`
+under `svelte-ui-theme`.
+
+**Scoped / inverse surfaces:** because the theme classes are ordinary CSS, apply one to any
+container to re-theme just that subtree — e.g. `class="theme-dark"` on a dark header sitting on a
+light page, so the components inside resolve light-on-dark and stay visible. This works because the
+tint tokens are re-defined per theme scope; see the themes skill.
+
+## Building a custom theme
+
+This page documents the token _surface_. For the authoring side — swapping palette/sizing, tinting
+by variant (`--ui-accent` + `.ui-accent`), scoping/inverse surfaces, the custom-property freeze
+rule, the self-reference trap, and bridging to another design system (DaisyUI, shadcn, …) — see the
+themes skill: [`.claude/skills/themes/SKILL.md`](../.claude/skills/themes/SKILL.md).

package/docs/usage.md

@@ -0,0 +1,450 @@
+# Usage Examples
+
+Common usage patterns for svelte-ui components. For the full, live gallery, run the demo and
+browse every component at **http://localhost:5173**.
+
+## Installation
+
+Published to npm:
+
+```bash
+npm install @spaethtech/svelte-ui
+```
+
+During active co-development you can instead link a local checkout with a `file:` dependency:
+
+```jsonc
+// package.json
+"dependencies": {
+  "@spaethtech/svelte-ui": "file:../svelte-ui"
+}
+```
+
+Peer dependencies:
+
+```bash
+npm install svelte@^5 tailwindcss@^4 unplugin-icons@^23 @iconify-json/mdi@^1
+```
+
+## Setup
+
+**1. Vite — add the icon resolver** (`vite.config.ts`):
+
+```ts
+import Icons from "unplugin-icons/vite";
+
+export default defineConfig({
+  plugins: [/* sveltekit(), tailwindcss(), */ Icons({ compiler: "svelte" })],
+});
+```
+
+**2. CSS — import Tailwind + the theme and scan the dist** (`app.css`, Tailwind v4):
+
+```css
+@import "tailwindcss";
+@import "@spaethtech/svelte-ui/theme.css";
+
+/* Generate the utility classes the components use (path relative to this file). */
+@source "../node_modules/@spaethtech/svelte-ui/dist";
+```
+
+## Basic Import
+
+```svelte
+<script>
+  import { Button, Input, Select } from "@spaethtech/svelte-ui";
+</script>
+```
+
+## Icons
+
+There is **no `Icon` component**. Import an MDI icon component from `~icons/mdi/*` and render it
+into a component's `icon` snippet — the library sizes and colors it:
+
+```svelte
+<script>
+  import { Button, Input } from "@spaethtech/svelte-ui";
+  import IconHome from "~icons/mdi/home";
+  import IconSearch from "~icons/mdi/magnify";
+</script>
+
+<Button title="Home">{#snippet icon()}<IconHome />{/snippet}</Button>
+
+<Input placeholder="Search…">
+  {#snippet icon()}<IconSearch />{/snippet}
+</Input>
+```
+
+## Component Examples
+
+### Button
+
+```svelte
+<script>
+  import { Button } from "@spaethtech/svelte-ui";
+  import IconContentSave from "~icons/mdi/content-save";
+  import IconPencil from "~icons/mdi/pencil";
+  import IconDelete from "~icons/mdi/delete";
+</script>
+
+<!-- Text button -->
+<Button text="Click me" variant="primary" onclick={() => alert("Clicked!")} />
+
+<!-- Button with icon -->
+<Button text="Save" variant="success">
+  {#snippet icon()}<IconContentSave />{/snippet}
+</Button>
+
+<!-- Icon-only button (title → themed tooltip + aria-label) -->
+<Button title="Edit" variant="plain" size="sm">
+  {#snippet icon()}<IconPencil />{/snippet}
+</Button>
+
+<!-- Button as link -->
+<Button href="/home" text="Home" variant="ghost" />
+
+<!-- Danger -->
+<Button text="Delete" variant="danger">
+  {#snippet icon()}<IconDelete />{/snippet}
+</Button>
+```
+
+### Input
+
+```svelte
+<script>
+  import { Input } from "@spaethtech/svelte-ui";
+  import IconAccount from "~icons/mdi/account";
+
+  let username = $state("");
+  let validated = $state("");
+</script>
+
+<!-- Basic -->
+<Input bind:value={username} placeholder="Username" />
+
+<!-- With a leading icon -->
+<Input bind:value={username} placeholder="Enter username" iconPosition="left">
+  {#snippet icon()}<IconAccount />{/snippet}
+</Input>
+
+<!-- With validation -->
+<Input
+  bind:value={validated}
+  validate={(v) => (v.length >= 3 ? true : "Minimum 3 characters")}
+  placeholder="Validated input"
+/>
+
+<!-- Clickable trailing icon -->
+<Input bind:value={username} iconClickable onIconClick={() => console.log("clicked")}>
+  {#snippet icon()}<IconAccount />{/snippet}
+</Input>
+```
+
+### Select
+
+```svelte
+<script>
+  import { Select } from "@spaethtech/svelte-ui";
+
+  let selected = $state("");
+  const options = [
+    { value: "1", label: "Option 1" },
+    { value: "2", label: "Option 2" },
+    { value: "3", label: "Option 3" },
+  ];
+</script>
+
+<!-- Static select -->
+<Select bind:value={selected} {options} placeholder="Choose option" />
+
+<!-- API-driven select with search -->
+<Select
+  bind:value={selected}
+  url="/api/items"
+  searchParam="q"
+  placeholder="Search items..."
+  transform={(data) => data.results.map((r) => ({ value: r.id, label: r.name }))}
+/>
+
+<!-- Custom item rendering -->
+<Select bind:value={selected} {options}>
+  {#snippet itemSnippet(option)}
+    <div class="flex items-center gap-2">
+      <span class="font-bold">{option.value}</span>
+      <span>{option.label}</span>
+    </div>
+  {/snippet}
+</Select>
+```
+
+### List
+
+```svelte
+<script>
+  import { List } from "@spaethtech/svelte-ui";
+
+  let selected = $state([]);
+  const options = [
+    { value: "1", label: "Item 1" },
+    { value: "2", label: "Item 2" },
+    { value: "3", label: "Item 3" },
+  ];
+</script>
+
+<!-- Single select -->
+<List bind:value={selected} {options} />
+
+<!-- Multi-select with checkboxes -->
+<List bind:value={selected} {options} multiSelect showCheckboxes />
+```
+
+### Checkbox
+
+```svelte
+<script>
+  import { Checkbox } from "@spaethtech/svelte-ui";
+  let checked = $state(false);
+</script>
+
+<Checkbox bind:checked />
+<Checkbox checked indeterminate />
+<Checkbox disabled />
+```
+
+### ConfirmDialog
+
+The common title + message + Confirm/Cancel modal (composed from a `Card` on the `Dialog` shell).
+
+```svelte
+<script>
+  import { ConfirmDialog, Button } from "@spaethtech/svelte-ui";
+
+  let showConfirm = $state(false);
+  let showDanger = $state(false);
+</script>
+
+<!-- Basic confirmation -->
+<Button text="Show Dialog" onclick={() => (showConfirm = true)} />
+<ConfirmDialog
+  bind:isOpen={showConfirm}
+  title="Confirm Action"
+  message="Are you sure you want to proceed?"
+  onConfirm={() => console.log("Confirmed")}
+/>
+
+<!-- Danger + must-decide (no backdrop/Escape dismiss) -->
+<ConfirmDialog
+  bind:isOpen={showDanger}
+  title="Delete Item"
+  message="This action cannot be undone!"
+  variant="danger"
+  confirmText="Delete"
+  dismissible={false}
+  onConfirm={() => console.log("Deleted")}
+/>
+```
+
+### Dialog (shell)
+
+A pure modal shell — you supply the content. Use it for anything beyond the confirm pattern; size it
+with `width` / `height` (any CSS value).
+
+```svelte
+<script>
+  import { Dialog, Card, CardHeader, CardFooter, Button, Input } from "@spaethtech/svelte-ui";
+
+  let open = $state(false);
+</script>
+
+<Button text="Open" onclick={() => (open = true)} />
+
+<Dialog bind:isOpen={open} width="80vw" height="60vh">
+  <Card class="w-full h-full flex flex-col">
+    <CardHeader><h3 class="text-lg font-medium">Custom modal</h3></CardHeader>
+    <div class="flex-1 overflow-auto space-y-2">
+      <p>You own the Card — control its separator, variant, sizing, and body.</p>
+      <Input placeholder="Enter value" />
+    </div>
+    <CardFooter separator={false}>
+      <Button text="Close" variant="secondary" onclick={() => (open = false)} />
+    </CardFooter>
+  </Card>
+</Dialog>
+```
+
+### Badge
+
+```svelte
+<script>
+  import { Badge } from "@spaethtech/svelte-ui";
+  import IconCheck from "~icons/mdi/check";
+
+  let showBadge = $state(true);
+</script>
+
+<!-- Basic badges -->
+<Badge text="New" variant="primary" />
+<Badge text="Beta" variant="warning" size="sm" />
+<Badge text="v1.0.0" variant="success" size="lg" />
+
+<!-- Dismissible -->
+{#if showBadge}
+  <Badge text="Alert" variant="danger" dismissible on:dismiss={() => (showBadge = false)} />
+{/if}
+
+<!-- Custom content -->
+<Badge variant="success">
+  <IconCheck />
+  <span>Verified</span>
+</Badge>
+```
+
+### TextArea
+
+```svelte
+<script>
+  import { TextArea } from "@spaethtech/svelte-ui";
+
+  let notes = $state("");
+  let code = $state("");
+</script>
+
+<!-- Auto-resizing -->
+<TextArea bind:value={notes} placeholder="Enter notes..." minRows={3} maxRows={10} />
+
+<!-- Fixed height -->
+<TextArea bind:value={code} minRows={5} maxRows={5} placeholder="Paste code here..." />
+
+<!-- Read-only with copy control -->
+<TextArea value="Read-only content" readonly allowCopy />
+```
+
+### Specialized Inputs
+
+```svelte
+<script>
+  import { PasswordInput, EmailInput, SearchInput, NumberInput } from "@spaethtech/svelte-ui";
+
+  let password = $state("");
+  let email = $state("");
+  let search = $state("");
+  let quantity = $state(1);
+</script>
+
+<PasswordInput bind:value={password} placeholder="Enter password" />
+<EmailInput bind:value={email} required placeholder="user@example.com" />
+<SearchInput bind:value={search} placeholder="Search..." />
+<NumberInput bind:value={quantity} min={1} max={100} />
+```
+
+### Tooltips (use:tooltip action)
+
+There is no `Tooltip` component — tooltips are a Svelte action built on the `anchored` engine.
+
+```svelte
+<script>
+  import { Button, tooltip } from "@spaethtech/svelte-ui";
+</script>
+
+<!-- Button drives the action from its `title` automatically -->
+<Button title="Delete" variant="danger" />
+
+<!-- Apply the action directly to any element -->
+<span use:tooltip={{ text: "Any element", side: "top" }}>hover me</span>
+
+<!-- Falls back to the element's native title (which it then suppresses) -->
+<a href="/help" title="Get help" use:tooltip>?</a>
+```
+
+### Popup & Menu
+
+```svelte
+<script>
+  import { Popup, Menu, Button } from "@spaethtech/svelte-ui";
+  import IconPencil from "~icons/mdi/pencil";
+  import IconDelete from "~icons/mdi/delete";
+
+  let trigger = $state();
+  let popupOpen = $state(false);
+  let menuOpen = $state(false);
+
+  const items = [
+    { label: "Edit", icon: IconPencil, onclick: () => console.log("edit") },
+    { label: "Delete", icon: IconDelete, onclick: () => console.log("delete") },
+  ];
+</script>
+
+<!-- Popover (arbitrary content) -->
+<Button bind:element={trigger} text="Open" onclick={() => (popupOpen = !popupOpen)} />
+<Popup anchor={trigger} bind:open={popupOpen} side="bottom" align="start">
+  <div class="p-3">…your content…</div>
+</Popup>
+
+<!-- Action menu -->
+<Button bind:element={trigger} text="Actions" onclick={() => (menuOpen = !menuOpen)} />
+<Menu anchor={trigger} bind:open={menuOpen} {items} align="end" />
+```
+
+### DataTable & Query (@spaethtech/svelte-ui/data)
+
+The data components are driven by the headless layer. Build a grid with `createGrid` and a filter
+bar with `Query` over a `DataSet`.
+
+```svelte
+<script>
+  import { DataTable, Query } from "@spaethtech/svelte-ui";
+  import { createGrid } from "@spaethtech/svelte-ui/data";
+  import IconPencil from "~icons/mdi/pencil";
+
+  const grid = createGrid({
+    columns: [
+      { id: "name", label: "Name" },
+      { id: "email", label: "Email" },
+      { id: "status", label: "Status", sortKey: "status" },
+    ],
+    fetch: (request) => /* a reactive query returning { rows, total } */ myQuery(request),
+  });
+</script>
+
+<DataTable
+  {grid}
+  selectable
+  rowActions={(row) => [{ label: "Edit", icon: IconPencil, onclick: () => edit(row) }]}
+/>
+```
+
+See the live demo for the full DataTable + Query walkthrough — http://localhost:5173.
+
+## Theme Integration
+
+### Using CSS Variables
+
+```svelte
+<style>
+  .custom-component {
+    background: var(--ui-color-background);
+    color: var(--ui-color-text);
+    height: var(--ui-height);
+  }
+
+  .custom-button {
+    background: var(--ui-color-primary);
+    &:hover {
+      background: color-mix(in srgb, var(--ui-color-primary), black 12%);
+    }
+  }
+  /* For neutral surfaces (rows, ghost buttons, section bands) use the shared tints instead:
+     var(--ui-color-hover) / var(--ui-color-surface) / var(--ui-color-active). */
+</style>
+```
+
+### Theme Selector
+
+```svelte
+<script>
+  import { ThemeSelector } from "@spaethtech/svelte-ui";
+</script>
+
+<ThemeSelector />
+```