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

package/docs/components.md

@@ -0,0 +1,255 @@
+# Component Reference
+
+Complete reference for all svelte-ui components. The exported set is whatever
+`src/lib/index.ts` re-exports — this doc tracks it.
+
+Icons are **MDI via `unplugin-icons`** — there is **no `Icon` component**. You render an icon by
+importing an MDI component (`import IconHome from '~icons/mdi/home'`) and passing it into a
+component's `icon` **snippet**. See `docs/usage.md`.
+
+## Cross-cutting axes
+
+Most sizeable/themeable components share two props (defined in `types/variants.ts` /
+`types/sizes.ts`):
+
+- **`variant`** — color/style: `primary`, `secondary`, `danger`, `info`, `success`, `warning`,
+  `ghost`, `plain`. `plain` is borderless/transparent — for dense icon controls.
+- **`size`** — `sm` (24px), `md` (32px, **default**), `lg` (40px). Tied to the theme's
+  `--ui-height-sm` / `--ui-height` / `--ui-height-lg`.
+
+## Form Components
+
+### Button
+
+Flexible button/anchor component.
+
+- **Location**: `src/lib/components/Button.svelte`
+- **Axes**: `variant`, `size`
+- **Props**: `text`, `icon` (snippet), `href` (renders an `<a>`), `disabled`, `onclick`, `title`,
+  plus native button/anchor attributes
+- **Features**: icon-only sizing, themed tooltip driven from `title` (via `use:tooltip`),
+  TypeScript discriminated union for button-vs-anchor
+- **Accessibility**: ARIA attributes, focus-visible outlines
+
+### Input
+
+Text input with an icon slot, trailing actions, and validation.
+
+- **Location**: `src/lib/components/Input.svelte`
+- **Axes**: `size`
+- **Props**: `value` (bindable), `icon` (snippet), `iconPosition` (`'left' | 'right'`, default
+  `'right'`), `iconClickable`, `onIconClick`, `actions` (snippet — trailing controls inside the
+  frame), `validate`, `valid`/`touched` (bindable), plus native input attributes
+- **Note**: a single `icon` snippet positioned by `iconPosition` — there is no
+  `iconLeft`/`iconRight`.
+
+### Select
+
+Custom dropdown built on `Input` + `List`.
+
+- **Location**: `src/lib/components/Select.svelte`
+- **Axes**: `size`
+- **Props**: `options` (`{ value, label, ... }[]`), `value` (bindable), `multiSelect`,
+  `placeholder`, `itemSnippet`, plus API props (`url`, `searchParam`, `transform`, `debounceMs`,
+  `maxResults`, `headers`, `searchTerm`)
+- **Modes**: static `options` or search-as-you-type against `url`
+
+### List
+
+Standalone selectable list (Select's dropdown body).
+
+- **Location**: `src/lib/components/List.svelte`
+- **Axes**: `size`
+- **Props**: `options` (`{ value, label, ... }[]`), `value` (bindable), `multiSelect`,
+  `showCheckboxes`, `maxVisibleItems`, `itemSnippet`, plus the same API props as `Select`
+
+### TextArea
+
+Multi-line text input with optional auto-resize.
+
+- **Location**: `src/lib/components/TextArea.svelte`
+- **Axes**: `size`
+- **Props**: `value` (bindable), `minRows`, `maxRows`, `lineHeightRem`, `allowCopy` (built-in copy
+  control), `validate`, `valid`/`touched`, plus native textarea attributes
+- **Modes**: fixed height (`minRows === maxRows`) or auto-sizing
+
+### Checkbox
+
+Small themed checkbox (native control tinted via `accent-color`).
+
+- **Location**: `src/lib/components/Checkbox.svelte`
+- **Axes**: `size`
+- **Props**: `checked` (bindable), `indeterminate`, `disabled`, plus native input attributes
+
+### Rating
+
+Read-only star-rating display (5-star, from a 10-point average).
+
+- **Location**: `src/lib/components/Rating.svelte`
+- **Props**: `average` (number), `count` (number)
+
+## Specialized Input Components
+
+Thin wrappers over `Input`, each preconfigured with an MDI icon (rendered into Input's snippet).
+
+### PasswordInput
+
+- **Location**: `src/lib/components/PasswordInput.svelte`
+- **Features**: built-in visibility toggle (eye / eye-off MDI icons)
+
+### EmailInput
+
+- **Location**: `src/lib/components/EmailInput.svelte`
+- **Features**: email validation, envelope icon
+
+### SearchInput
+
+- **Location**: `src/lib/components/SearchInput.svelte`
+- **Features**: search (magnify) icon, clear button when typing
+
+### NumberInput
+
+- **Location**: `src/lib/components/NumberInput.svelte`
+- **Features**: number formatting and validation
+
+## Data Components
+
+These pair with the headless **`@spaethtech/svelte-ui/data`** layer (query-language parser/AST, `createGrid`,
+`DataSet`). See `docs/usage.md`.
+
+### DataTable
+
+Config-driven, responsive 12-column data table over a `DataGrid`.
+
+- **Location**: `src/lib/components/DataTable.svelte`
+- **Props**: `grid` (`DataGrid<T>` from `@spaethtech/svelte-ui/data`), `selectable`, `expandable`, `expanded`
+  (snippet), `rowActions` (`(row) => MenuItem[]`), `bulkActions`
+- **Features**: selectable + expandable rows, sortable headers, per-row & bulk action menus
+  (via `Menu`/`Popup`), paginated footer. A **compound component** — all controls are
+  `<Button variant="plain" size="sm">` / `<Select size="sm">` / `<Checkbox>`.
+
+### Query
+
+Filter bar over a `DataSet` — monospace input with `$column` + enum-value autocomplete and a help
+dialog.
+
+- **Location**: `src/lib/components/Query.svelte`
+- **Props**: `dataset` (`DataSet`), `placeholder`
+- **Note**: URL sync is intentionally not built in — observe `dataset.applied` and sync yourself.
+  Built on `Input` + `Button` + `Popup` + `Dialog`.
+
+## Overlays
+
+### Dialog
+
+**Pure modal shell** — the mechanics only, no imposed content. Put a `Card` (or anything) inside via
+`children`. For the common confirm pattern use `ConfirmDialog` (below).
+
+- **Location**: `src/lib/components/Dialog.svelte`
+- **Props**: `isOpen` (bindable), `width` (any CSS value — `'80%'`, `'80vw'`, `'400px'`; default
+  auto, capped at `min(32rem, …)`), `height` (any CSS value; default auto), `dismissible` (default
+  `true`), `onClose`, `class`, `children` (snippet). Extra attributes (e.g. `aria-label`) spread onto
+  the panel.
+- **Features**: portals to `<body>`, background scroll-lock (scrollbar-width compensated), backdrop
+  + Escape dismiss, **focus trap** (initial focus in, Tab wraps, focus restored on close),
+  `role="dialog"` + `aria-modal`.
+
+### ConfirmDialog
+
+The common title + message + Confirm/Cancel modal, composed from a `Card` on top of the `Dialog`
+shell.
+
+- **Location**: `src/lib/components/ConfirmDialog.svelte`
+- **Props**: `isOpen` (bindable), `title`, `message`, `confirmText`, `cancelText`, `onConfirm`,
+  `onCancel`, `variant` (`'normal' | 'danger'`), `size`, `showConfirm`, `showCancel`, `dismissible`,
+  `width`/`height` (forwarded to the shell), `children` (snippet — replaces `message` as the body).
+
+### Popup
+
+Interactive popover anchored to a trigger, rendered in the browser top layer (Popover API) so it's
+never clipped by overflow/stacking contexts. Placement via the shared `anchored` engine.
+
+- **Location**: `src/lib/components/Popup.svelte`
+- **Props**: `anchor` (trigger element), `open` (bindable), `side`, `align`, `boundary`
+  (`'viewport'` or an element/selector), `offset`, `matchWidth`, `onclose`, `children` (snippet)
+- **Features**: flips against the boundary, dismisses on Escape + outside pointerdown
+
+### Menu
+
+Keyboard-navigable action menu rendered inside a `Popup`.
+
+- **Location**: `src/lib/components/Menu.svelte`
+- **Props**: `anchor`, `open` (bindable), `items` (`MenuItem[]` from `@spaethtech/svelte-ui/data`), `side`,
+  `align`, `boundary`
+- **Features**: renders all items always and disables the invalid ones; aligns labels when any
+  item has an icon
+
+### tooltip (action)
+
+Themed tooltips as a Svelte action — `use:tooltip` — built on `anchored`. No global handler.
+
+- **Location**: `src/lib/positioning/tooltip.ts`
+- **Options** (`TooltipOptions`): `text` (defaults to the element's `title`, which is then
+  suppressed), `side` (default `top`), `align`, `offset`, `delay`, `disabled`
+- **Note**: `Button` feeds this from its `title`, so native `title` tooltips are replaced wherever
+  a Button is used. Mirrors text to `aria-label` when the element has no accessible name.
+
+## Positioning
+
+### anchored (engine)
+
+Shared placement engine — a Svelte action plus `computePlacement` / `resolveBoundary` — used by
+`Popup`, `Menu`, and `tooltip`.
+
+- **Location**: `src/lib/positioning/anchored.ts`
+- **Exports**: `anchored`, `computePlacement`, `resolveBoundary`, and the types `Side`, `Align`,
+  `Boundary`, `PlaceOptions`, `Placement`, `AnchoredParams`
+
+## Display / Theme
+
+### Badge
+
+Status indicator / label.
+
+- **Location**: `src/lib/components/Badge/Badge.svelte`
+- **Axes**: `size`
+- **Variants**: `default`, `primary`, `success`, `warning`, `danger`, `info`
+- **Props**: `text`, `variant`, `size`, `dismissible`, `rounded`, `children`; dispatches `dismiss`
+
+### NotesEditor
+
+- **Location**: `src/lib/components/NotesEditor.svelte`
+
+### ThemeSelector
+
+Theme switcher (Auto / Light / Dark), built on `Select`.
+
+- **Location**: `src/lib/components/ThemeSelector.svelte`
+- **Features**: applies `.theme-light` / `.theme-dark` to `<html>`/`<body>`, `auto` follows the
+  system preference, persists to `localStorage` (`svelte-ui-theme`)
+
+## Import Pattern
+
+```typescript
+import { Button, Input, Select, DataTable, tooltip } from "@spaethtech/svelte-ui";
+import { createGrid } from "@spaethtech/svelte-ui/data";
+import "@spaethtech/svelte-ui/theme.css"; // via @import in your app.css
+```
+
+## Component Structure
+
+### Colocated Components
+
+```
+src/lib/components/ComponentName/
+├── ComponentName.svelte      # Implementation
+├── ComponentName.spec.md     # Specification
+├── ComponentName.test.ts     # Tests
+└── index.ts                  # Export
+```
+
+### Simple Components
+
+```
+src/lib/components/ComponentName.svelte
+```

package/docs/examples.md

@@ -0,0 +1,323 @@
+# Demo Page Standards
+
+This document defines the unified format for all component demo pages in the svelte-ui library.
+The live demo runs at **http://localhost:5173** (`npm run dev`).
+
+## Current State Analysis
+
+### Consistent Elements Found:
+
+- **Back navigation** - Button linking to main page
+- **Theme selector** - ThemeSelector component in header
+- **Component sections** - Grouped examples (variants, sizes, states)
+- **Code examples** - TextArea components showing code snippets
+
+### Inconsistencies Found:
+
+- **Import patterns** - Mixed usage of imports
+- **Layout structure** - Different container classes and layouts
+- **Header positioning** - Theme selector and back button placement varies
+- **Section organization** - Inconsistent section naming and ordering
+- **Code formatting** - Different TextArea configurations
+- **Missing elements** - Some pages lack back buttons or theme selectors
+
+## Standard Template
+
+All demo pages should follow this structure:
+
+### File Location
+
+```
+src/routes/[component-name]/+page.svelte
+```
+
+### Standard Template Structure
+
+```svelte
+<script lang="ts">
+  // IMPORTS - Use consistent library imports
+  import { ComponentName, Button, ThemeSelector, TextArea } from "$lib/index.js";
+  // Icons are MDI via unplugin-icons — import the ones this page uses.
+  import IconArrowLeft from "~icons/mdi/arrow-left";
+
+  // DEMO STATE - Component-specific state variables
+  let demoState = $state("initial");
+
+  // DEMO DATA - Static data for examples
+  const exampleData = [
+    { id: "1", name: "Example 1" },
+    { id: "2", name: "Example 2" },
+  ];
+</script>
+
+<!-- PAGE CONTAINER -->
+<div class="p-8 max-w-4xl mx-auto space-y-8">
+  <!-- HEADER -->
+  <div class="flex items-center justify-between flex-col sm:flex-row gap-4 mb-6">
+    <Button href="/" variant="ghost" text="Back to Components">
+      {#snippet icon()}<IconArrowLeft />{/snippet}
+    </Button>
+    <ThemeSelector />
+  </div>
+
+  <!-- PAGE TITLE -->
+  <h1 class="text-3xl font-bold mb-8">ComponentName Component</h1>
+
+  <!-- SECTION: Basic Usage -->
+  <section>
+    <h2 class="text-2xl font-semibold mb-4">Basic Usage</h2>
+    <div class="mb-6">
+      <!-- Example components -->
+      <ComponentName prop="value" />
+    </div>
+
+    <TextArea
+      value={`import { ComponentName } from '@spaethtech/svelte-ui';
+
+<ComponentName prop="value" />`}
+      readonly
+      textareaClass="font-mono text-sm"
+    />
+  </section>
+
+  <!-- SECTION: Variants (if applicable) -->
+  <section>
+    <h2 class="text-2xl font-semibold mb-4">Variants</h2>
+    <div class="flex gap-4 flex-wrap mb-6">
+      <ComponentName variant="primary" />
+      <ComponentName variant="secondary" />
+    </div>
+
+    <TextArea
+      value={`<ComponentName variant="primary" />
+<ComponentName variant="secondary" />`}
+      readonly
+      textareaClass="font-mono text-sm"
+    />
+  </section>
+
+  <!-- SECTION: Sizes (if applicable) -->
+  <section>
+    <h2 class="text-2xl font-semibold mb-4">Sizes</h2>
+    <div class="flex items-center gap-2 mb-6">
+      <ComponentName size="sm" />
+      <ComponentName size="md" />
+      <ComponentName size="lg" />
+    </div>
+
+    <TextArea
+      value={`<ComponentName size="sm" />
+<ComponentName size="md" />
+<ComponentName size="lg" />`}
+      readonly
+      textareaClass="font-mono text-sm"
+    />
+  </section>
+
+  <!-- SECTION: Interactive Examples -->
+  <section>
+    <h2 class="text-2xl font-semibold mb-4">Interactive Examples</h2>
+    <div class="mb-6">
+      <ComponentName bind:value={demoState} />
+    </div>
+
+    <TextArea
+      value={`<script>
+  let value = $state('');
+</script>
+
+<ComponentName bind:value />`}
+      readonly
+      textareaClass="font-mono text-sm"
+    />
+  </section>
+
+  <!-- SECTION: Advanced Features (if applicable) -->
+  <section>
+    <h2 class="text-2xl font-semibold mb-4">Advanced Features</h2>
+    <div class="mb-6">
+      <!-- Advanced examples -->
+    </div>
+
+    <TextArea value={`<!-- Advanced usage code -->`} readonly textareaClass="font-mono text-sm" />
+  </section>
+</div>
+```
+
+## Required Elements
+
+### 1. Container Structure
+
+```svelte
+<div class="p-8 max-w-4xl mx-auto space-y-8">
+```
+
+- **Padding**: `p-8` for consistent spacing
+- **Max width**: `max-w-4xl` for readability
+- **Centering**: `mx-auto` to center content
+- **Spacing**: `space-y-8` between sections
+
+### 2. Header Layout
+
+```svelte
+<div class="flex items-center justify-between flex-col sm:flex-row gap-4 mb-6">
+  <Button href="/" variant="ghost" text="Back to Components">
+    {#snippet icon()}<IconArrowLeft />{/snippet}
+  </Button>
+  <ThemeSelector />
+</div>
+```
+
+- **Responsive**: Stacks on mobile (`flex-col sm:flex-row`)
+- **Back button**: Links to main page with consistent styling
+- **Theme selector**: Always in top-right area
+
+### 3. Page Title
+
+```svelte
+<h1 class="text-3xl font-bold mb-8">ComponentName Component</h1>
+```
+
+- **Size**: `text-3xl` for prominence
+- **Weight**: `font-bold` for emphasis
+- **Spacing**: `mb-8` for separation
+
+### 4. Section Structure
+
+```svelte
+<section>
+  <h2 class="text-2xl font-semibold mb-4">Section Name</h2>
+  <div class="mb-6">
+    <!-- Examples -->
+  </div>
+
+  <TextArea value={`code example`} readonly textareaClass="font-mono text-sm" />
+</section>
+```
+
+### 5. Code Examples
+
+- **Always include** corresponding code for each example
+- **Use TextArea** component for code display
+- **Readonly**: Always `readonly`
+- **Styling**: `textareaClass="font-mono text-sm"`
+- **Import format**: Use `'@spaethtech/svelte-ui'` (not internal paths)
+
+## Standard Sections (in order)
+
+1. **Basic Usage** - Simplest implementation
+2. **Variants** - Different visual styles (if applicable)
+3. **Sizes** - Different size options (if applicable)
+4. **States** - Disabled, loading, error states (if applicable)
+5. **Interactive Examples** - Functional examples with state
+6. **Advanced Features** - Complex usage patterns
+7. **Accessibility** - A11y features demonstration (if notable)
+
+## Import Standards
+
+### Consistent Library Imports
+
+```svelte
+import {(ComponentName, Button, ThemeSelector, TextArea)} from '$lib/index.js';
+```
+
+### MDI Icons (unplugin-icons)
+
+Icons are MDI components imported from `~icons/mdi/*` and rendered into a component's `icon`
+snippet — there is no `Icon` component.
+
+```svelte
+import IconArrowLeft from '~icons/mdi/arrow-left'; import IconPencil from '~icons/mdi/pencil';
+```
+
+### Code Example Imports
+
+In TextArea code examples, always show:
+
+```javascript
+import { ComponentName } from "@spaethtech/svelte-ui";
+```
+
+## Responsive Design
+
+### Container Breakpoints
+
+- **Mobile**: Full width with padding
+- **Desktop**: Max-width container centered
+
+### Header Layout
+
+- **Mobile**: Stack vertically (back button top, theme selector bottom)
+- **Desktop**: Horizontal layout (back button left, theme selector right)
+
+### Example Layout
+
+- **Flex wrapping**: Use `flex-wrap` for button/badge groups
+- **Grid layouts**: Use responsive grids for complex examples
+
+## Code Example Best Practices
+
+### 1. Realistic Examples
+
+- Use meaningful prop values
+- Show practical use cases
+- Include realistic data
+
+### 2. Progressive Complexity
+
+- Start with simplest usage
+- Build up to more complex examples
+- Show common patterns
+
+### 3. Complete Code Snippets
+
+- Include necessary imports
+- Show complete functional examples
+- Include state management when relevant
+
+### 4. Consistent Formatting
+
+- Use 2-space indentation
+- Keep lines under 80 characters when possible
+- Use clear prop names
+
+## Component-Specific Guidelines
+
+### Form Components
+
+- Show validation examples
+- Demonstrate error states
+- Include accessibility attributes
+
+### Interactive Components
+
+- Show event handling
+- Demonstrate state binding
+- Include keyboard navigation
+
+### Layout Components
+
+- Show responsive behavior
+- Demonstrate different content types
+- Include slot usage
+
+### Theme Integration
+
+- Show theme-aware styling
+- Demonstrate CSS variable usage
+- Include light/dark mode examples
+
+## Quality Checklist
+
+Before considering a demo page complete:
+
+- [ ] Header with back button and theme selector
+- [ ] Consistent import statements
+- [ ] All major features demonstrated
+- [ ] Code examples for every visual example
+- [ ] Responsive layout tested
+- [ ] Accessibility considerations shown
+- [ ] Error-free TypeScript
+- [ ] Consistent styling and spacing
+- [ ] Realistic example data
+- [ ] Progressive complexity in examples