@makolabs/ripple 2.5.9 → 3.0.0

package/README.md

@@ -1,610 +1,521 @@
 # Ripple UI
 
-A modern, standardized Svelte 5 component library designed for simplicity, consistency, and AI-friendly usage patterns.
-
-## Key Features
-
-- **Standardized API** with consistent prop naming and patterns across components
-- **Enum-based properties** for predictable component customization
-- **Strong TypeScript support** with comprehensive type definitions
-- **Utility-first approach** built with TailwindCSS
-- **Accessible components** adhering to modern web standards
-- **Simplified component consumption** ideal for both human and AI developers
-
-## Getting started
-
-Install the project
+A Svelte 5 + TailwindCSS 4 component library for building data-dense product UIs (dashboards, admin tools, internal apps). Built on `tailwind-variants` with consistent naming, comprehensive TypeScript types, and per-prop JSDoc that lets LLMs and IDE tooltips answer "how do I use this?" without leaving the editor.
 
 ```shell
 npm i @makolabs/ripple
 ```
 
-## Usage
+---
 
-Import ripple UI components
+## Table of contents
 
-```svelte
-<script lang="ts">
-	import { Button, Card, Modal } from '@makolabs/ripple';
-</script>
+- [Quick start](#quick-start)
+- [Theme tokens](#theme-tokens)
+- [Component catalog](#component-catalog)
+- [Conventions](#conventions)
+- [Selected examples](#selected-examples)
+  - [Forms](#forms)
+  - [Tables + cells](#tables--cells)
+  - [Modals + dialogs](#modals--dialogs)
+  - [Filters](#filters)
+  - [Charts](#charts)
+- [Server-side helpers](#server-side-helpers)
+- [Testing](#testing)
+- [Troubleshooting](#troubleshooting)
+
+---
 
-<div class="px-12 pt-12">
-	<Card title="Hello World" color="warning">
-		<p>This is a card component</p>
-	</Card>
-</div>
+## Quick start
+
+### 1. Install
+
+```shell
+npm i @makolabs/ripple
 ```
 
-Paste the following CSS import code in `app.css`
+### 2. Wire up your CSS
+
+Tailwind 4 does not scan `node_modules` automatically. Add a `@source` directive plus the `@theme` color tokens to your `app.css`:
 
 ```css
+@import 'tailwindcss';
 @source '../node_modules/@makolabs/ripple';
 
 @theme {
-	/* Default (default) */
-	--color-default-50: oklch(0.984 0.003 247.858);
-	--color-default-100: oklch(0.96 0.006 247.858);
-	--color-default-200: oklch(0.91 0.008 247.858);
-	--color-default-300: oklch(0.85 0.01 247.858);
-	--color-default-400: oklch(0.76 0.012 247.858);
-	--color-default-500: oklch(0.65 0.015 247.858);
-	--color-default-600: oklch(0.54 0.018 247.858);
-	--color-default-700: oklch(0.45 0.015 247.858);
-	--color-default-800: oklch(0.35 0.012 247.858);
-	--color-default-900: oklch(0.25 0.01 247.858);
-	--color-default-950: oklch(0.15 0.008 247.858);
-
-	/* Primary (Blue) */
-	--color-primary-50: oklch(0.97 0.025 250);
-	--color-primary-100: oklch(0.94 0.035 250);
-	--color-primary-200: oklch(0.89 0.055 250);
-	--color-primary-300: oklch(0.82 0.075 250);
-	--color-primary-400: oklch(0.74 0.095 250);
+	/* Ripple expects 7 color scales — see "Theme tokens" below for the full set */
 	--color-primary-500: oklch(0.65 0.115 250);
-	--color-primary-600: oklch(0.55 0.125 250);
-	--color-primary-700: oklch(0.45 0.115 250);
-	--color-primary-800: oklch(0.35 0.095 250);
-	--color-primary-900: oklch(0.25 0.075 250);
-	--color-primary-950: oklch(0.15 0.055 250);
-
-	/* Secondary (Slate) */
-	--color-secondary-50: oklch(0.97 0.02 255);
-	--color-secondary-100: oklch(0.94 0.03 255);
-	--color-secondary-200: oklch(0.89 0.04 255);
-	--color-secondary-300: oklch(0.82 0.05 255);
-	--color-secondary-400: oklch(0.74 0.06 255);
-	--color-secondary-500: oklch(0.65 0.07 255);
-	--color-secondary-600: oklch(0.55 0.065 255);
-	--color-secondary-700: oklch(0.45 0.055 255);
-	--color-secondary-800: oklch(0.35 0.045 255);
-	--color-secondary-900: oklch(0.25 0.035 255);
-	--color-secondary-950: oklch(0.15 0.025 255);
-
-	/* Info (Sky) */
-	--color-info-50: oklch(0.97 0.025 220);
-	--color-info-100: oklch(0.94 0.04 220);
-	--color-info-200: oklch(0.89 0.06 220);
-	--color-info-300: oklch(0.82 0.085 220);
-	--color-info-400: oklch(0.74 0.105 220);
-	--color-info-500: oklch(0.65 0.125 220);
-	--color-info-600: oklch(0.55 0.115 220);
-	--color-info-700: oklch(0.45 0.105 220);
-	--color-info-800: oklch(0.35 0.085 220);
-	--color-info-900: oklch(0.25 0.065 220);
-	--color-info-950: oklch(0.15 0.045 220);
-
-	/* Success (Green) */
-	--color-success-50: oklch(0.97 0.025 145);
-	--color-success-100: oklch(0.94 0.04 145);
-	--color-success-200: oklch(0.89 0.06 145);
-	--color-success-300: oklch(0.82 0.08 145);
-	--color-success-400: oklch(0.74 0.1 145);
 	--color-success-500: oklch(0.65 0.12 145);
-	--color-success-600: oklch(0.55 0.11 145);
-	--color-success-700: oklch(0.45 0.1 145);
-	--color-success-800: oklch(0.35 0.08 145);
-	--color-success-900: oklch(0.25 0.06 145);
-	--color-success-950: oklch(0.15 0.04 145);
-
-	/* Warning (Yellow) */
-	--color-warning-50: oklch(0.97 0.025 90);
-	--color-warning-100: oklch(0.94 0.045 90);
-	--color-warning-200: oklch(0.89 0.065 90);
-	--color-warning-300: oklch(0.82 0.085 90);
-	--color-warning-400: oklch(0.74 0.105 90);
-	--color-warning-500: oklch(0.65 0.125 90);
-	--color-warning-600: oklch(0.55 0.115 90);
-	--color-warning-700: oklch(0.45 0.105 90);
-	--color-warning-800: oklch(0.35 0.085 90);
-	--color-warning-900: oklch(0.25 0.065 90);
-	--color-warning-950: oklch(0.15 0.045 90);
-
-	/* Danger (Red) */
-	--color-danger-50: oklch(0.97 0.025 25);
-	--color-danger-100: oklch(0.94 0.045 25);
-	--color-danger-200: oklch(0.89 0.065 25);
-	--color-danger-300: oklch(0.82 0.085 25);
-	--color-danger-400: oklch(0.74 0.105 25);
 	--color-danger-500: oklch(0.65 0.125 25);
-	--color-danger-600: oklch(0.55 0.115 25);
-	--color-danger-700: oklch(0.45 0.105 25);
-	--color-danger-800: oklch(0.35 0.085 25);
-	--color-danger-900: oklch(0.25 0.065 25);
-	--color-danger-950: oklch(0.15 0.045 25);
+	/* …etc */
 }
 ```
 
-## Design Philosophy
-
-Ripple UI was built with a focus on consistency and standardization. Every component follows the same patterns for customization:
-
-### Standardized Enums
+### 3. Use a component
 
-Components use standardized enums for colors, sizes, and variants:
-
-```typescript
-// Colors available for most components
-Color.DEFAULT; // 'default'
-Color.PRIMARY; // 'primary'
-Color.SECONDARY; // 'secondary'
-Color.INFO; // 'info'
-Color.SUCCESS; // 'success'
-Color.WARNING; // 'warning'
-Color.DANGER; // 'danger'
+```svelte
+<script lang="ts">
+	import { Button, Card } from '@makolabs/ripple';
+	let count = $state(0);
+</script>
 
-// Sizes available for most components
-Size.XS; // 'xs'
-Size.SM; // 'sm'
-Size.BASE; // 'base'
-Size.LG; // 'lg'
-Size.XL; // 'xl'
-Size.XXL; // '2xl'
+<Card title="Counter" color="primary">
+	<p>Clicks: {count}</p>
+	<Button onclick={() => count++}>Increment</Button>
+</Card>
 ```
 
-### Consistent Props Pattern
-
-All components follow a consistent props pattern with predictable naming:
-
-- `color`: Component color theme (using the Color enum)
-- `size`: Component size (using the Size enum)
-- `class`: Custom CSS classes for the component
-- Event handlers with `on` prefix (e.g., `onclick`, `onchange`)
-- Element-specific class props named with component + 'class' (e.g., `titleclass`, `bodyclass`)
+That's it — no provider component, no global CSS reset, no theme context.
+
+---
+
+## Theme tokens
+
+Ripple components use seven semantic color scales. Each scale needs steps `50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 950`.
+
+| Scale       | Use for                                    | Example component |
+| ----------- | ------------------------------------------ | ----------------- |
+| `default`   | Neutral text, borders, surfaces            | Disabled buttons  |
+| `primary`   | Brand color, primary actions, focus rings  | "Save" button     |
+| `secondary` | Alternate brand color (counter to primary) | Sidebar accent    |
+| `info`      | Informational tints (often blue/cyan)      | Alert (info)      |
+| `success`   | Success states, positive metrics           | Alert (success)   |
+| `warning`   | Caution, pending states (yellow/amber)     | Alert (warning)   |
+| `danger`    | Destructive actions, errors (red)          | Delete button     |
+
+A complete `@theme` block with all seven scales is in [`docs/THEME.md`](docs/THEME.md) (or copy-paste from this README's git history). Pick any palette — Ripple just consumes the token names.
+
+---
+
+## Component catalog
+
+All components are exported from the package root: `import { Component } from '@makolabs/ripple'`. Per-prop JSDoc with `@example` blocks is on every type, so IDE tooltips and AI assistants give you the right signature immediately.
+
+### Forms
+
+| Component          | Use for                                           |
+| ------------------ | ------------------------------------------------- |
+| `Input`            | Single-line text/email/number/etc.                |
+| `Textarea`         | Multi-line text with autoGrow + character counter |
+| `Checkbox`         | Boolean selection ("I accept the terms")          |
+| `Toggle`           | Boolean switch (on/off settings)                  |
+| `RadioGroup`       | Pick one from a short list                        |
+| `Select`           | Single/multi-select dropdown with optional search |
+| `ComboBox`         | Searchable select with free-typing + filter       |
+| `SegmentedControl` | Compact pill-style picker (2-5 options)           |
+| `MarketSelector`   | Specialised SegmentedControl with country flags   |
+| `Slider`           | Numeric or range slider, with optional ticks      |
+| `NumberInput`      | Number input with currency/unit dropdown          |
+| `Tags`             | List of short string tags with autocomplete       |
+| `DatePicker`       | Single date picker with calendar popover          |
+| `DateRange`        | Two-date (from/to) picker                         |
+| `Calendar`         | Standalone month-view calendar (single + range)   |
+| `Form`             | sveltekit-superforms wrapper                      |
+
+### Layout
+
+| Component                         | Use for                                                             |
+| --------------------------------- | ------------------------------------------------------------------- |
+| `Card`                            | Generic bordered container                                          |
+| `MetricCard`                      | KPI-focused card (big number + optional progress)                   |
+| `RankedCard`                      | Leaderboard-style ranked list                                       |
+| `Table`                           | Data table with sorting/selection/pagination                        |
+| `Cells`                           | Pre-built cell renderers (`Cells.Currency`, `Cells.DateCell`, etc.) |
+| `TabGroup` + `TabContent` + `Tab` | Tabbed panels                                                       |
+| `Navbar`                          | Top navigation bar                                                  |
+| `Sidebar`                         | Left rail navigation, collapsible                                   |
+| `ActivityList`                    | Feed of recent events / audit trail                                 |
+| `Pipeline`                        | Chevron stage bar (sales pipeline, funnel)                          |
+| `Stepper`                         | Multi-step form wizard                                              |
+| `PageHeader`                      | Title + subtitle + breadcrumbs + actions                            |
+| `Breadcrumbs`                     | Hierarchical link trail                                             |
+
+### Elements
+
+| Component     | Use for                                  |
+| ------------- | ---------------------------------------- |
+| `Button`      | Buttons + anchor links (set `href`)      |
+| `Badge`       | Pills for statuses, counts, tags         |
+| `Alert`       | Inline page-level banner                 |
+| `Accordion`   | Collapsible section                      |
+| `Spinner`     | Indeterminate loading indicator          |
+| `Skeleton`    | Layout-preserving content placeholder    |
+| `Progress`    | Linear progress bar (single + segmented) |
+| `EmptyState`  | Centered "nothing here" placeholder      |
+| `Tooltip`     | Hover/focus-triggered text label         |
+| `Popover`     | Generic anchored floating panel          |
+| `Dropdown`    | Action menu attached to a trigger        |
+| `ContextMenu` | Right-click / long-press menu            |
+| `Pagination`  | Page navigation controls                 |
+
+### Overlays
+
+| Component             | Use for                              |
+| --------------------- | ------------------------------------ |
+| `Modal`               | Centered overlay dialog              |
+| `Drawer`              | Side-anchored sliding panel          |
+| `ConfirmDialog`       | "Are you sure?" wrapper around Modal |
+| `Toaster` + `toast()` | Transient notifications              |
+
+### Filters
+
+| Component          | Use for                                                |
+| ------------------ | ------------------------------------------------------ |
+| `CompactFilters`   | Collapsible filter bar with chip-summary mode          |
+| `FilterPopover`    | Per-group dropdown pills (status, priority, dates)     |
+| `FilterBar`        | Chip-based add/remove filters with "+ Add filter" menu |
+| `syncFiltersToUrl` | Two-way bind selections to URL query params            |
+
+### Charts
+
+| Component | Use for                                                                           |
+| --------- | --------------------------------------------------------------------------------- |
+| `Chart`   | ECharts wrapper — line, bar, stacked-bar, horizontal-bar, area, pie, donut, mixed |
+
+### File handling
+
+| Component / helper   | Use for                                                      |
+| -------------------- | ------------------------------------------------------------ |
+| `FileUpload`         | Drag-and-drop with single + multi-file + rich-mode progress  |
+| `FilesPreview`       | List of uploaded files with delete                           |
+| `FileBrowser`        | Browse/select files on remote storage (S3, GDrive)           |
+| `S3Adapter`          | Storage adapter for S3-compatible backends (DO Spaces, etc.) |
+| `GoogleDriveAdapter` | Storage adapter for Google Drive                             |
+| `createS3Handlers`   | Server-side route handlers (`@makolabs/ripple/server`)       |
+
+### AI / Chat
+
+| Component         | Use for                                        |
+| ----------------- | ---------------------------------------------- |
+| `AIChatInterface` | Full chat UI with streaming + thinking content |
+| `MermaidRenderer` | Render Mermaid diagrams from chat output       |
+| `CodeRenderer`    | Syntax-highlighted code blocks                 |
+
+### User management
+
+| Component        | Use for                                                  |
+| ---------------- | -------------------------------------------------------- |
+| `UserManagement` | All-in-one user dashboard (table + modals + permissions) |
+| `UserTable`      | Just the user table                                      |
+| `UserModal`      | Create/edit user form                                    |
+| `UserViewModal`  | Read-only user details                                   |
+
+### Helpers + variant utilities
+
+| Helper                                                                                                                                                                                                                               | Purpose                                                                     |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------- |
+| `cn`                                                                                                                                                                                                                                 | `twMerge(clsx(…))` — conditional class composition                          |
+| `tv`                                                                                                                                                                                                                                 | `tailwind-variants` factory pre-configured with `twMerge`                   |
+| `buildTestId`                                                                                                                                                                                                                        | Compose `data-testid` strings consistently                                  |
+| `buttonVariants`, `badge`, `modal`, `drawer`, `breadcrumbs`, `card`, `metricCard`, `rankedCard`, `activityList`, `slider`, `segmentedTrack`, `dropdownMenu`, `selectTV`, `pipelineVariants`, `spinnerVariants`, `emptyStateVariants` | Raw `tv()` outputs for consumers who want the styling without the component |
+
+---
+
+## Conventions
+
+Knowing five rules unlocks every component.
+
+### 1. `Color` and `Size` enums
+
+```ts
+import { Color, Size } from '@makolabs/ripple';
+
+Color.DEFAULT |
+	Color.PRIMARY |
+	Color.SECONDARY |
+	Color.INFO |
+	Color.SUCCESS |
+	Color.WARNING |
+	Color.DANGER;
+
+Size.XS | Size.SM | Size.MD | Size.LG | Size.XL | Size.XXL;
+```
 
-## Component Variants
+You can also pass the string literal (`color="primary"`, `size="md"`) — both are accepted because the enum values are plain strings.
 
-Most components in Ripple UI support variants to customize their appearance. Here are some examples:
+A few components narrow `Size` to the variants their visual design supports (e.g. `Tooltip` uses `'sm' | 'md' | 'lg'`). The narrowed types are exported from the same package.
 
-### Button Variants
+### 2. Event handler naming
 
-Buttons come with different variants, colors, sizes, and shapes:
+All component event-handler props are **lowercase `on`-prefixed** (Svelte 5 convention):
 
 ```svelte
-<script lang="ts">
-	import { Button, Color, Size } from '@makolabs/ripple';
-</script>
+<Button onclick={save}>Save</Button>
+<Modal onclose={() => (open = false)}>…</Modal>
+<TabGroup onchange={(value) => goto(value)} />
+<Slider oninput={(v) => (rate = v)} />
+```
 
-<!-- Different button variants -->
-<Button variant="solid" color={Color.PRIMARY}>Solid Button</Button>
-<Button variant="outline" color={Color.SECONDARY}>Outline Button</Button>
-<Button variant="ghost" color={Color.DANGER}>Ghost Button</Button>
-<Button variant="link" color={Color.INFO}>Link Button</Button>
-
-<!-- Button with onclick handler -->
-<Button color={Color.SUCCESS} onclick={() => console.log('Button clicked')}>Click Me</Button>
-
-<!-- Button as link -->
-<Button href="https://example.com" target="_blank" color={Color.PRIMARY}>Visit Website</Button>
-
-<!-- Button sizes -->
-<Button size={Size.XS}>Extra Small</Button>
-<Button size={Size.SM}>Small</Button>
-<Button size={Size.BASE}>Base</Button>
-<Button size={Size.LG}>Large</Button>
-<Button size={Size.XL}>Extra Large</Button>
-<Button size={Size.XXL}>2X Large</Button>
-
-<!-- Button variants with different colors -->
-<Button variant="solid" color={Color.PRIMARY}>Primary Solid</Button>
-<Button variant="solid" color={Color.DANGER}>Danger Solid</Button>
-<Button variant="outline" color={Color.SUCCESS}>Success Outline</Button>
-<Button variant="ghost" color={Color.WARNING}>Warning Ghost</Button>
-<Button variant="link" color={Color.INFO}>Info Link</Button>
+Inside components, the lowercase prop is often aliased to a camelCase local for readability:
+
+```ts
+let { onclose: onClose = () => {}, ...rest } = $props();
 ```
 
-### Modal Variants
+### 3. Class props
 
-Modals with different sizes and custom content:
+The root container takes `class?: ClassValue`. Sub-element class props use camelCase with a `Class` suffix:
 
 ```svelte
-<script lang="ts">
-	import { Modal, Button, Size } from '@makolabs/ripple';
-	let isOpen = false;
-</script>
+<Modal
+	class="max-w-2xl"
+	titleClass="text-lg font-bold"
+	bodyClass="p-6"
+	footerClass="bg-default-50"
+/>
+```
 
-<Button onclick={() => (isOpen = true)}>Open Modal</Button>
+`ClassValue` accepts strings, arrays, and conditional objects (like `clsx`).
 
-<!-- Basic modal -->
-<Modal open={isOpen} title="Basic Modal" size={Size.BASE} onClose={() => (isOpen = false)}>
-	<p>Modal content goes here</p>
-</Modal>
+### 4. Snippets, not slots
 
-<!-- Modal with different size -->
-<Modal open={isOpen} title="Large Modal" size={Size.XL} onClose={() => (isOpen = false)}>
-	<p>This modal is larger and provides more content space</p>
-</Modal>
+Ripple is Svelte 5 — no `<slot>` tags anywhere. All content projection uses snippets:
 
-<!-- Modal with custom header and footer -->
-<Modal open={isOpen} onClose={() => (isOpen = false)} size={Size.BASE}>
-	<svelte:fragment slot="header">
-		<div class="flex items-center">
-			<svg
-				xmlns="http://www.w3.org/2000/svg"
-				width="24"
-				height="24"
-				fill="currentColor"
-				viewBox="0 0 16 16"
-			>
-				<path d="M13 16h-1v-4h-1m1-4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" />
-			</svg>
-			<h3 class="text-lg font-medium">Custom Header</h3>
-		</div>
-	</svelte:fragment>
-
-	<p>Modal with custom header and footer</p>
-
-	<svelte:fragment slot="footer">
-		<div class="flex justify-end space-x-2">
-			<Button variant="outline" onclick={() => (isOpen = false)}>Cancel</Button>
-			<Button color={Color.PRIMARY}>Save Changes</Button>
-		</div>
-	</svelte:fragment>
+```svelte
+<Modal bind:open title="Edit profile">
+	<ProfileForm />
+
+	{#snippet footer()}
+		<ModalFooter align="end">
+			<Button variant="outline" onclick={() => (open = false)}>Cancel</Button>
+			<Button onclick={save}>Save</Button>
+		</ModalFooter>
+	{/snippet}
 </Modal>
-
-<!-- TODO: Remove position prop from Modal component in future versions -->
 ```
 
-### Drawer Component
-
-Drawers can slide in from different edges of the screen:
+Snippets can also receive arguments — useful for per-row renderers in `Table`, per-step content in `Stepper`, etc.
 
-```svelte
-<script lang="ts">
-	import { Drawer, Button } from '@makolabs/ripple';
-	let isDrawerOpen = false;
-</script>
+### 5. `testId` everywhere
 
-<Button onclick={() => (isDrawerOpen = true)}>Open Drawer</Button>
+Every public component accepts an optional `testId?: string` and emits `data-testid` attributes scoped to its parts (`data-testid="modal-dialog"`, `data-testid="my-prefix-modal-body"` when `testId="my-prefix"`). Use it for E2E tests.
 
-<Drawer open={isDrawerOpen} position="right" onClose={() => (isDrawerOpen = false)}>
-	<div class="p-4">
-		<h3 class="mb-4 text-lg font-medium">Drawer Title</h3>
-		<p class="mb-4">This is a drawer that slides in from the side of the screen.</p>
-		<Button onclick={() => (isDrawerOpen = false)}>Close Drawer</Button>
-	</div>
-</Drawer>
-```
+---
 
-### PageHeader Component
+## Selected examples
 
-A component for consistent page headers:
+### Forms
 
 ```svelte
 <script lang="ts">
-	import { PageHeader, Button, Color } from '@makolabs/ripple';
-
-	const breadcrumbs = [
-		{ label: 'Dashboard', href: '#' },
-		{ label: 'Projects', href: '#' },
-		{ label: 'Current Project' }
-	];
+	import { Form, Input, Textarea, RadioGroup, Button } from '@makolabs/ripple';
+	import { superForm } from 'sveltekit-superforms';
+	export let data;
+	const form = superForm(data.form);
 </script>
 
-<PageHeader
-	title="Project Dashboard"
-	description="View and manage your project details"
-	{breadcrumbs}
->
-	<svelte:fragment slot="actions">
-		<Button color={Color.PRIMARY}>New Project</Button>
-	</svelte:fragment>
-</PageHeader>
-```
-
-### Card Variants
+<Form {form} method="POST">
+	<Input name="email" type="email" label="Email" required />
 
-Cards can be customized with different styles:
+	<RadioGroup
+		name="plan"
+		label="Plan"
+		options={[
+			{ value: 'free', label: 'Free' },
+			{ value: 'pro', label: 'Pro', description: '$10/mo' }
+		]}
+	/>
 
-```svelte
-<script lang="ts">
-	import { Card, StatsCard, Color } from '@makolabs/ripple';
-</script>
+	<Textarea name="notes" label="Notes" rows={3} maxLength={500} showCount />
 
-<Card title="Basic Card" color={Color.PRIMARY}>
-  <p>Card content goes here</p>
-</Card>
-
-<StatsCard
-  label="Monthly Sales"
-  value="$865,000"
-  previousValue="$750,000"
-  previousValuePrefix="vs"
-  trend={15.3}
-  color={Color.SUCCESS}
-  chartData={[20, 25, 30, 22, 35, 40, 38, 45, 50]}
-  icon={
-    <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" fill="currentColor" viewBox="0 0 16 16">
-      <path d="M13 16h-1v-4h-1m1-4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" />
-    </svg>
-  }
-/>
+	<Button type="submit">Save</Button>
+</Form>
 ```
 
-### Table Component
+### Tables + cells
 
-Tables for displaying structured data with pagination and sorting:
+`Cells` is a namespace import of pre-built snippets — `Currency`, `Email`, `DateCell`, `Time`, `PhoneNumber`, `Percentage`, `Status`. Hand them to `column.cell` to skip the boilerplate:
 
 ```svelte
 <script lang="ts">
-	import { Table, Color, Size } from '@makolabs/ripple';
+	import { Table, Cells } from '@makolabs/ripple';
+	import type { TableColumn } from '@makolabs/ripple';
 
-	let data = [
-		{ id: 1, name: 'John Doe', email: 'john@example.com', status: 'Active' },
-		{ id: 2, name: 'Jane Smith', email: 'jane@example.com', status: 'Inactive' },
-		{ id: 3, name: 'Robert Johnson', email: 'robert@example.com', status: 'Active' }
-	];
+	type User = { id: string; name: string; email: string; createdAt: string; lastSpent: number };
 
-	const columns = [
-		{ key: 'name', label: 'Name', sortable: true },
-		{ key: 'email', label: 'Email', sortable: true },
-		{ key: 'status', label: 'Status' }
+	const columns: TableColumn<User>[] = [
+		{ key: 'name', header: 'Name', sortable: true },
+		{ key: 'email', header: 'Email', cell: Cells.Email },
+		{ key: 'createdAt', header: 'Joined', cell: Cells.DateCell, align: 'right' },
+		{ key: 'lastSpent', header: 'Last spent', cell: Cells.Currency, align: 'right' }
 	];
-
-	let selected = [];
-	let sort = { column: 'name', direction: 'asc' };
 </script>
 
 <Table
-	{data}
 	{columns}
-	color={Color.PRIMARY}
-	size={Size.BASE}
-	pageSize={10}
-	selectable={true}
-	bind:selected
-	bind:sort
-	striped={true}
+	data={users}
+	{loading}
+	pageSize={25}
+	title="Customers"
+	onrowclick={(user) => goto(`/users/${user.id}`)}
 />
 ```
 
-### Tab Component
+### Modals + dialogs
 
-Tabs for organizing content into different views:
+Three flavours: `Modal` (general), `ConfirmDialog` (yes/no), `Drawer` (side panel).
 
 ```svelte
 <script lang="ts">
-	import { TabGroup, TabContent, Color, Size } from '@makolabs/ripple';
-
-	const tabs = [
-		{ value: 'overview', label: 'Overview' },
-		{ value: 'details', label: 'Details' },
-		{ value: 'settings', label: 'Settings' }
-	];
-
-	let activeTab = 'overview';
-
-	function handleTabChange(value) {
-		console.log(`Tab changed to ${value}`);
+	import { ConfirmDialog, Button, Color } from '@makolabs/ripple';
+	let open = $state(false);
+	async function deleteAccount() {
+		await api.deleteAccount();
+		// dialog auto-closes when onconfirm resolves
 	}
 </script>
 
-<TabGroup
-	{tabs}
-	bind:selected={activeTab}
-	onchange={handleTabChange}
-	color={Color.PRIMARY}
-	size={Size.BASE}
->
-	<TabContent value="overview" persisted>
-		<p>Overview content here</p>
-	</TabContent>
-
-	<TabContent value="details" persisted>
-		<p>Details content here</p>
-	</TabContent>
-
-	<TabContent value="settings" persisted>
-		<p>Settings content here</p>
-	</TabContent>
-</TabGroup>
-```
-
-### Badge Component
-
-Badges for displaying statuses and counts:
-
-```svelte
-<script lang="ts">
-	import { Badge, Color, Size } from '@makolabs/ripple';
-</script>
+<Button color={Color.DANGER} variant="outline" onclick={() => (open = true)}>Delete account</Button>
 
-<Badge color={Color.PRIMARY} size={Size.BASE}>New</Badge>
-<Badge color={Color.SUCCESS}>Success</Badge>
-<Badge color={Color.WARNING}>Warning</Badge>
-<Badge color={Color.DANGER}>43</Badge>
+<ConfirmDialog
+	bind:open
+	title="Delete your account?"
+	message="This permanently removes your account, files, and history. This cannot be undone."
+	confirmLabel="Delete forever"
+	confirmColor={Color.DANGER}
+	onconfirm={deleteAccount}
+/>
 ```
 
-### Select Component
+### Filters
 
-Dropdown selector for choosing from a list of options:
+`FilterPopover` for per-group dropdowns, `FilterBar` for add-as-needed chips, `CompactFilters` for collapsed-by-default detail panels. All three take the same `filterGroups` shape, including date-range groups and URL syncing:
 
 ```svelte
 <script lang="ts">
-	import { Select, Size } from '@makolabs/ripple';
+	import { FilterPopover, syncFiltersToUrl } from '@makolabs/ripple';
+	import type { FilterGroup, FilterSelectionValue } from '@makolabs/ripple';
 
-	const items = [
-		{ label: 'Option 1', value: 'option1' },
-		{ label: 'Option 2', value: 'option2' },
-		{ label: 'Option 3', value: 'option3', disabled: true },
-		{ label: 'Option 4', value: 'option4' }
-	];
-
-	let selected = 'option1';
-
-	function handleSelect(event) {
-		console.log('Selected:', event.value);
-	}
-</script>
-
-<Select {items} bind:value={selected} class="w-64" size={Size.BASE} onselect={handleSelect} />
-```
-
-### Dropdown Component
-
-Menu dropdown for actions and navigation:
-
-```svelte
-<script lang="ts">
-	import { Dropdown, Size } from '@makolabs/ripple';
-	import FluentChevronDown16Filled from '$icons/FluentChevronDown16Filled.svelte';
+	let selections = $state<Record<string, FilterSelectionValue>>({
+		status: 'all',
+		created: null
+	});
 
-	const sections = [
+	const filterGroups: FilterGroup[] = [
 		{
-			items: [
-				{
-					label: 'Edit',
-					icon: FluentPen16Filled,
-					onclick: () => console.log('Edit clicked')
-				},
-				{
-					label: 'Duplicate',
-					icon: FluentPenSparkle24Filled,
-					onclick: () => console.log('Duplicate clicked')
-				}
+			key: 'status',
+			label: 'Status',
+			tabs: [
+				{ value: 'all', label: 'All', count: 1247 },
+				{ value: 'active', label: 'Active', count: 823 },
+				{ value: 'archived', label: 'Archived', count: 112 }
 			]
 		},
-		{
-			items: [
-				{
-					label: 'Delete',
-					icon: FluentDelete24Filled,
-					onclick: () => console.log('Delete clicked')
-				}
-			]
-		}
+		{ key: 'created', label: 'Created', dateRange: true } // built-in calendar + presets
 	];
+
+	syncFiltersToUrl(
+		() => selections,
+		(v) => (selections = v),
+		{ dateRangeKeys: ['created'] }
+	);
 </script>
 
-<Dropdown {sections} label="Actions" size={Size.BASE} icon={FluentChevronDown16Filled} />
+<FilterPopover {filterGroups} bind:selections />
 ```
 
-## Component Composition
-
-Ripple UI components are designed to work together seamlessly:
+### Charts
 
 ```svelte
 <script lang="ts">
-	import { Card, TabGroup, TabContent, Button, Color, Size } from '@makolabs/ripple';
+	import { Chart, ChartColor } from '@makolabs/ripple';
 
-	const tabs = [
-		{ value: 'overview', label: 'Overview' },
-		{ value: 'details', label: 'Details' },
-		{ value: 'settings', label: 'Settings' }
+	const data = [
+		{ month: '2026-01', netCash: 250000 },
+		{ month: '2026-02', netCash: -120000 },
+		{ month: '2026-03', netCash: 60000 }
 	];
-
-	let activeTab = 'overview';
 </script>
 
-<Card title="Project Information" color={Color.PRIMARY}>
-	<TabGroup {tabs} bind:selected={activeTab} color={Color.INFO} size={Size.BASE}>
-		<TabContent value="overview">
-			<p>Project overview content here...</p>
-			<Button variant="solid" color={Color.SUCCESS} size={Size.SM}>Take Action</Button>
-		</TabContent>
-
-		<TabContent value="details">
-			<p>Project details content here...</p>
-		</TabContent>
-
-		<TabContent value="settings">
-			<p>Project settings content here...</p>
-		</TabContent>
-	</TabGroup>
-</Card>
+<Chart
+	{data}
+	config={{
+		xAxis: { dataKey: 'month' },
+		yAxis: [
+			{
+				dataKey: 'netCash',
+				label: 'Net cash (CHF)',
+				format: (v) => `CHF ${(v / 1000).toFixed(0)}K`
+			}
+		],
+		series: [
+			{
+				dataKey: 'netCash',
+				name: 'Monthly Net Value',
+				type: 'bar',
+				color: ChartColor.HEALTH
+			}
+		]
+	}}
+	height="320px"
+/>
 ```
 
-## Latest Updates
+---
 
-Ripple UI now exports all components from a central entry point, making it easier to import components:
+## Server-side helpers
 
-```svelte
-<script lang="ts">
-	import { Button, Modal, Card, Table, Select, Dropdown } from '@makolabs/ripple';
-</script>
+Some components have a server-side companion. Import from `@makolabs/ripple/server`:
+
+```ts
+// src/routes/api/s3/list/+server.ts
+import { createS3Handlers } from '@makolabs/ripple/server';
+import { env } from '$env/dynamic/private';
+
+const s3 = createS3Handlers({
+	bucket: env.S3_BUCKET,
+	region: env.S3_REGION,
+	accessKeyId: env.S3_ACCESS_KEY_ID,
+	secretAccessKey: env.S3_SECRET_ACCESS_KEY,
+	endpoint: env.S3_ENDPOINT // optional, e.g. for DigitalOcean Spaces
+});
+
+export const GET = ({ request }) => s3.list(request);
 ```
 
-You can still import specific component types when needed:
+Add the matching `download` route at `src/routes/api/s3/download/+server.ts` (`s3.download`). The client `S3Adapter` calls both endpoints — see the `FileBrowser` example below.
 
 ```svelte
 <script lang="ts">
-	import { Button, type ButtonProps } from '@makolabs/ripple';
-
-	// Create a custom button with specific props
-	const myButton: ButtonProps = {
-		variant: 'outline',
-		color: 'primary',
-		size: 'lg',
-		rounded: 'xl'
-	};
+	import { FileBrowser, S3Adapter } from '@makolabs/ripple';
+	const adapter = new S3Adapter({ basePath: 'imports/' });
 </script>
 
-<Button {...myButton}>Custom Button</Button>
+<FileBrowser {adapter} />
 ```
 
-## Testing
-
-Ripple UI uses [Vitest](https://vitest.dev/) for unit and component testing. The test suite includes tests for core library components using Svelte 5's native testing APIs.
-
-### Running Tests Locally
-
-Run all tests once:
-
-```bash
-npm run test:unit -- --run
-```
+---
 
-Run tests in watch mode (for development):
+## Testing
 
-```bash
-npm run test:unit
-```
+Ripple uses Vitest with two workspace projects:
 
-Run all tests (unit + e2e):
+- **client** — jsdom environment, runs `*.svelte.{test,spec}.{js,ts}`
+- **server** — node environment, runs other `*.{test,spec}.{js,ts}`
 
 ```bash
-npm test
+npm test               # run all tests
+npm run test:unit      # watch mode
+npx vitest run path/to/file.test.ts   # single test
 ```
 
-### Writing Tests
+### Component test pattern
 
-Component tests use Svelte 5's `mount` and `unmount` APIs for testing components. Here's an example test for a Button component:
+Svelte 5 snippets can't be passed as props from JS, so each tested component has a TestWrapper that takes scalar props and renders snippets internally:
 
-```typescript
-import { flushSync, mount, unmount } from 'svelte';
+```ts
+// Button.svelte.test.ts
+import { mount, unmount } from 'svelte';
 import { expect, test } from 'vitest';
 import ButtonTestWrapper from './ButtonTestWrapper.svelte';
 
-test('renders as a button with slot content and respects disabled prop', () => {
+test('renders disabled button with text', () => {
 	const component = mount(ButtonTestWrapper, {
 		target: document.body,
-		props: {
-			disabled: true,
-			text: 'Click me'
-		}
+		props: { disabled: true, text: 'Click me' }
 	});
 
 	const btn = document.body.querySelector('button') as HTMLButtonElement;
-	expect(btn).toBeTruthy();
 	expect(btn.disabled).toBe(true);
 	expect(btn.textContent).toContain('Click me');
 
@@ -612,44 +523,39 @@ test('renders as a button with slot content and respects disabled prop', () => {
 });
 ```
 
-For components with snippet props (like `children` or `footer`), create a test wrapper component that accepts simple props and renders them as slots.
-
-### Test Configuration
+Use `flushSync()` from `svelte` after programmatic interactions that trigger reactive updates.
 
-Tests are configured using Vitest workspaces in `vite.config.ts`:
+---
 
-- **Client tests**: Run in jsdom environment, include files matching `src/**/*.svelte.{test,spec}.{js,ts}`
-- **Server tests**: Run in node environment, include files matching `src/**/*.{test,spec}.{js,ts}` (excluding `.svelte` tests)
-
-The setup file `vitest-setup-client.ts` includes:
+## Troubleshooting
 
-- `@testing-library/jest-dom` matchers for enhanced assertions
-- `matchMedia` mock for jsdom compatibility with Svelte 5
+### Components render without color
 
-### Continuous Integration
+Tailwind 4 doesn't ship the color tokens Ripple uses. Add the `@theme` block to your `app.css` (see [Theme tokens](#theme-tokens)).
 
-For CI environments (GitHub Actions, etc.), use:
+### Component classes missing in production
 
-```yaml
-- name: Install dependencies
-  run: npm ci
+Tailwind 4 doesn't scan `node_modules` automatically. Add to `app.css`:
 
-- name: Run tests
-  run: npm run test:unit -- --run
+```css
+@source '../node_modules/@makolabs/ripple';
 ```
 
-## Troubleshooting
+### `import 'foo' with `…/$lib/foo.ts'` doesn't resolve
 
-### Missing color tokens (components render without color)
+This codebase uses `moduleResolution: 'nodenext'` — local imports must use `.js` extensions even when importing `.ts` files:
 
-Ripple UI uses custom color tokens (e.g. `primary`, `secondary`, `danger`) that must be defined in your app's CSS. If components appear unstyled or use fallback colors, add the `@theme` block with all required color token definitions to your `app.css`. See the full token list in the [Usage](#usage) section above.
+```ts
+import { cn } from '$lib/helper/cls.js'; // ✅
+import { cn } from '$lib/helper/cls'; // ❌
+```
 
-### TailwindCSS 4 `@source` configuration
+### Storybook
 
-TailwindCSS 4 does not automatically scan `node_modules` for class names. You must add the following directive to your `app.css` so that Tailwind generates the utility classes used by Ripple UI components:
+The repo includes Storybook (`npm run storybook`, port 6006) with stories for every component and every interesting prop combination. Browse it for live examples beyond what's in this README.
 
-```css
-@source '../node_modules/@makolabs/ripple';
-```
+---
+
+## License
 
-Without this, component styles that rely on Tailwind utilities will be missing from your build output.
+MIT.