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

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 />
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spaethtech/svelte-ui",
-  "version": "0.3.0",
+  "version": "0.3.1-dev.10.ff03a8d",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/spaethtech/svelte-ui.git"
@@ -33,7 +33,11 @@
   "files": [
     "dist",
     "!dist/**/*.test.*",
-    "!dist/**/*.spec.*"
+    "!dist/**/*.spec.*",
+    "CLAUDE.md",
+    "docs",
+    ".claude/skills/themes",
+    ".claude/skills/svelte-ui"
   ],
   "sideEffects": [
     "**/*.css"