\n\t\n\n```\n\nThat's it — no provider component, no global CSS reset, no theme context.\n\n---\n\n## Theme tokens\n\nRipple components use seven semantic color scales. Each scale needs steps `50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 950`.\n\n| Scale | Use for | Example component |\n| ----------- | ------------------------------------------ | ----------------- |\n| `default` | Neutral text, borders, surfaces | Disabled buttons |\n| `primary` | Brand color, primary actions, focus rings | \"Save\" button |\n| `secondary` | Alternate brand color (counter to primary) | Sidebar accent |\n| `info` | Informational tints (often blue/cyan) | Alert (info) |\n| `success` | Success states, positive metrics | Alert (success) |\n| `warning` | Caution, pending states (yellow/amber) | Alert (warning) |\n| `danger` | Destructive actions, errors (red) | Delete button |\n\nA 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.\n\n---\n\n## Component catalog\n\nAll 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.\n\n### Forms\n\n| Component | Use for |\n| ------------------ | ------------------------------------------------- |\n| `Input` | Single-line text/email/number/etc. |\n| `Textarea` | Multi-line text with autoGrow + character counter |\n| `Checkbox` | Boolean selection (\"I accept the terms\") |\n| `Toggle` | Boolean switch (on/off settings) |\n| `RadioGroup` | Pick one from a short list |\n| `Select` | Single/multi-select dropdown with optional search |\n| `ComboBox` | Searchable select with free-typing + filter |\n| `SegmentedControl` | Compact pill-style picker (2-5 options) |\n| `MarketSelector` | Specialised SegmentedControl with country flags |\n| `Slider` | Numeric or range slider, with optional ticks |\n| `NumberInput` | Number input with currency/unit dropdown |\n| `Tags` | List of short string tags with autocomplete |\n| `DatePicker` | Single date picker with calendar popover |\n| `DateRange` | Two-date (from/to) picker |\n| `Calendar` | Standalone month-view calendar (single + range) |\n| `Form` | sveltekit-superforms wrapper |\n\n### Layout\n\n| Component | Use for |\n| --------------------------------- | ------------------------------------------------------------------- |\n| `Card` | Generic bordered container |\n| `MetricCard` | KPI-focused card (big number + optional progress) |\n| `RankedCard` | Leaderboard-style ranked list |\n| `Table` | Data table with sorting/selection/pagination |\n| `Cells` | Pre-built cell renderers (`Cells.Currency`, `Cells.DateCell`, etc.) |\n| `TabGroup` + `TabContent` + `Tab` | Tabbed panels |\n| `Navbar` | Top navigation bar |\n| `Sidebar` | Left rail navigation, collapsible |\n| `ActivityList` | Feed of recent events / audit trail |\n| `Pipeline` | Chevron stage bar (sales pipeline, funnel) |\n| `Stepper` | Multi-step form wizard |\n| `PageHeader` | Title + subtitle + breadcrumbs + actions |\n| `Breadcrumbs` | Hierarchical link trail |\n\n### Elements\n\n| Component | Use for |\n| ------------- | ---------------------------------------- |\n| `Button` | Buttons + anchor links (set `href`) |\n| `Badge` | Pills for statuses, counts, tags |\n| `Alert` | Inline page-level banner |\n| `Accordion` | Collapsible section |\n| `Spinner` | Indeterminate loading indicator |\n| `Skeleton` | Layout-preserving content placeholder |\n| `Progress` | Linear progress bar (single + segmented) |\n| `EmptyState` | Centered \"nothing here\" placeholder |\n| `Tooltip` | Hover/focus-triggered text label |\n| `Popover` | Generic anchored floating panel |\n| `Dropdown` | Action menu attached to a trigger |\n| `ContextMenu` | Right-click / long-press menu |\n| `Pagination` | Page navigation controls |\n\n### Overlays\n\n| Component | Use for |\n| --------------------- | ------------------------------------ |\n| `Modal` | Centered overlay dialog |\n| `Drawer` | Side-anchored sliding panel |\n| `ConfirmDialog` | \"Are you sure?\" wrapper around Modal |\n| `Toaster` + `toast()` | Transient notifications |\n\n### Filters\n\n| Component | Use for |\n| ------------------ | ------------------------------------------------------ |\n| `CompactFilters` | Collapsible filter bar with chip-summary mode |\n| `FilterPopover` | Per-group dropdown pills (status, priority, dates) |\n| `FilterBar` | Chip-based add/remove filters with \"+ Add filter\" menu |\n| `syncFiltersToUrl` | Two-way bind selections to URL query params |\n\n### Charts\n\n| Component | Use for |\n| --------- | --------------------------------------------------------------------------------- |\n| `Chart` | ECharts wrapper — line, bar, stacked-bar, horizontal-bar, area, pie, donut, mixed |\n\n### File handling\n\n| Component / helper | Use for |\n| -------------------- | ------------------------------------------------------------ |\n| `FileUpload` | Drag-and-drop with single + multi-file + rich-mode progress |\n| `FilesPreview` | List of uploaded files with delete |\n| `FileBrowser` | Browse/select files on remote storage (S3, GDrive) |\n| `S3Adapter` | Storage adapter for S3-compatible backends (DO Spaces, etc.) |\n| `GoogleDriveAdapter` | Storage adapter for Google Drive |\n| `createS3Handlers` | Server-side route handlers (`@makolabs/ripple/server`) |\n\n### AI / Chat\n\n| Component | Use for |\n| ----------------- | ---------------------------------------------- |\n| `AIChatInterface` | Full chat UI with streaming + thinking content |\n| `MermaidRenderer` | Render Mermaid diagrams from chat output |\n| `CodeRenderer` | Syntax-highlighted code blocks |\n\n### User management\n\n| Component | Use for |\n| ---------------- | -------------------------------------------------------- |\n| `UserManagement` | All-in-one user dashboard (table + modals + permissions) |\n| `UserTable` | Just the user table |\n| `UserModal` | Create/edit user form |\n| `UserViewModal` | Read-only user details |\n\n### Helpers + variant utilities\n\n| Helper | Purpose |\n| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------- |\n| `cn` | `twMerge(clsx(…))` — conditional class composition |\n| `tv` | `tailwind-variants` factory pre-configured with `twMerge` |\n| `buildTestId` | Compose `data-testid` strings consistently |\n| `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 |\n\n---\n\n## Conventions\n\nKnowing five rules unlocks every component.\n\n### 1. `Color` and `Size` enums\n\n```ts\nimport { Color, Size } from '@makolabs/ripple';\n\nColor.DEFAULT |\n\tColor.PRIMARY |\n\tColor.SECONDARY |\n\tColor.INFO |\n\tColor.SUCCESS |\n\tColor.WARNING |\n\tColor.DANGER;\n\nSize.XS | Size.SM | Size.MD | Size.LG | Size.XL | Size.XXL;\n```\n\nYou can also pass the string literal (`color=\"primary\"`, `size=\"md\"`) — both are accepted because the enum values are plain strings.\n\nA 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.\n\n### 2. Event handler naming\n\nAll component event-handler props are **lowercase `on`-prefixed** (Svelte 5 convention):\n\n```svelte\n\n (open = false)}>…\n goto(value)} />\n (rate = v)} />\n```\n\nInside components, the lowercase prop is often aliased to a camelCase local for readability:\n\n```ts\nlet { onclose: onClose = () => {}, ...rest } = $props();\n```\n\n### 3. Class props\n\nThe root container takes `class?: ClassValue`. Sub-element class props use camelCase with a `Class` suffix:\n\n```svelte\n\n```\n\n`ClassValue` accepts strings, arrays, and conditional objects (like `clsx`).\n\n### 4. Snippets, not slots\n\nRipple is Svelte 5 — no `` tags anywhere. All content projection uses snippets:\n\n```svelte\n\n\t\n\n\t{#snippet footer()}\n\t\t\n\t\t\t\n\t\t\t\n\t\t\n\t{/snippet}\n\n```\n\nSnippets can also receive arguments — useful for per-row renderers in `Table`, per-step content in `Stepper`, etc.\n\n### 5. `testId` everywhere\n\nEvery 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.\n\n---\n\n## Selected examples\n\n### Forms\n\n```svelte\n\n\n\n```\n\n### Tables + cells\n\n`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:\n\n```svelte\n\n\n goto(`/users/${user.id}`)}\n/>\n```\n\n### Modals + dialogs\n\nThree flavours: `Modal` (general), `ConfirmDialog` (yes/no), `Drawer` (side panel).\n\n```svelte\n\n\n\n\n\n```\n\n### Filters\n\n`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:\n\n```svelte\n\n\n\n```\n\n### Charts\n\n```svelte\n\n\n `CHF ${(v / 1000).toFixed(0)}K`\n\t\t\t}\n\t\t],\n\t\tseries: [\n\t\t\t{\n\t\t\t\tdataKey: 'netCash',\n\t\t\t\tname: 'Monthly Net Value',\n\t\t\t\ttype: 'bar',\n\t\t\t\tcolor: ChartColor.HEALTH\n\t\t\t}\n\t\t]\n\t}}\n\theight=\"320px\"\n/>\n```\n\n---\n\n## Server-side helpers\n\nSome components have a server-side companion. Import from `@makolabs/ripple/server`:\n\n```ts\n// src/routes/api/s3/list/+server.ts\nimport { createS3Handlers } from '@makolabs/ripple/server';\nimport { env } from '$env/dynamic/private';\n\nconst s3 = createS3Handlers({\n\tbucket: env.S3_BUCKET,\n\tregion: env.S3_REGION,\n\taccessKeyId: env.S3_ACCESS_KEY_ID,\n\tsecretAccessKey: env.S3_SECRET_ACCESS_KEY,\n\tendpoint: env.S3_ENDPOINT // optional, e.g. for DigitalOcean Spaces\n});\n\nexport const GET = ({ request }) => s3.list(request);\n```\n\nAdd 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.\n\n```svelte\n\n\n\n```\n\n---\n\n## Testing\n\nRipple uses Vitest with two workspace projects:\n\n- **client** — jsdom environment, runs `*.svelte.{test,spec}.{js,ts}`\n- **server** — node environment, runs other `*.{test,spec}.{js,ts}`\n\n```bash\nnpm test # run all tests\nnpm run test:unit # watch mode\nnpx vitest run path/to/file.test.ts # single test\n```\n\n### Component test pattern\n\nSvelte 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:\n\n```ts\n// Button.svelte.test.ts\nimport { mount, unmount } from 'svelte';\nimport { expect, test } from 'vitest';\nimport ButtonTestWrapper from './ButtonTestWrapper.svelte';\n\ntest('renders disabled button with text', () => {\n\tconst component = mount(ButtonTestWrapper, {\n\t\ttarget: document.body,\n\t\tprops: { disabled: true, text: 'Click me' }\n\t});\n\n\tconst btn = document.body.querySelector('button') as HTMLButtonElement;\n\texpect(btn.disabled).toBe(true);\n\texpect(btn.textContent).toContain('Click me');\n\n\tunmount(component);\n});\n```\n\nUse `flushSync()` from `svelte` after programmatic interactions that trigger reactive updates.\n\n---\n\n## Troubleshooting\n\n### Components render without color\n\nTailwind 4 doesn't ship the color tokens Ripple uses. Add the `@theme` block to your `app.css` (see [Theme tokens](#theme-tokens)).\n\n### Component classes missing in production\n\nTailwind 4 doesn't scan `node_modules` automatically. Add to `app.css`:\n\n```css\n@source '../node_modules/@makolabs/ripple';\n```\n\n### `import 'foo' with `…/$lib/foo.ts'` doesn't resolve\n\nThis codebase uses `moduleResolution: 'nodenext'` — local imports must use `.js` extensions even when importing `.ts` files:\n\n```ts\nimport { cn } from '$lib/helper/cls.js'; // ✅\nimport { cn } from '$lib/helper/cls'; // ❌\n```\n\n### Storybook\n\nThe 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.\n\n---\n\n## License\n\nMIT.\n","readmeFilename":"README.md"}