@marianmeres/stuic 3.170.0 → 3.172.0

package/docs/{component-testing → _archive/component-testing}/01-framework-setup.md

@@ -7,6 +7,8 @@ Planning artifact; no code was changed.
 
 # Framework Setup
 
+> **ARCHIVED — historical, not current guidance.** See [`docs/_archive/README.md`](../README.md) for why.
+
 > This is the infrastructure dimension: the one-time work that turns "no DOM, no `$effect`"
 > into a working browser test harness. The single most important takeaway: **a Vitest
 > `projects` split routed by filename** (`*.test.ts` → fast node, `*.svelte.test.ts` → real
@@ -18,7 +20,7 @@ Planning artifact; no code was changed.
 
 - **Package manager:** pnpm. **Svelte:** 5.56.2. **SvelteKit:** 2.63.0 (adapter-auto). **Vitest:** 3.2.6.
 - **Test config:** none dedicated. Vitest is configured only implicitly through
-  [`vite.config.ts`](../../vite.config.ts) (`plugins: [tailwindcss(), sveltekit()]`), and the
+  [`vite.config.ts`](../../../vite.config.ts) (`plugins: [tailwindcss(), sveltekit()]`), and the
   script is `"test": "vitest --dir src/"`.
 - **What runs today:** 9 suites / ~59 tests, all **node environment, pure logic** — validation
   helpers, stack classes (`NotificationsStack`, `AlertConfirmPromptStack`), `tr`, `replace-map`,
@@ -70,7 +72,7 @@ do **not** need `@testing-library/svelte` or `@testing-library/jest-dom` — `vi
 
 ## Step 3 — The `projects` config
 
-Add a `test` block to [`vite.config.ts`](../../vite.config.ts) (keep the file; just extend it).
+Add a `test` block to [`vite.config.ts`](../../../vite.config.ts) (keep the file; just extend it).
 Verified against the live Vitest 4 docs (`provider: playwright()` is an imported **function**, not
 the old `'playwright'` string; `instances` is required):
 

package/docs/{component-testing → _archive/component-testing}/03-component-coverage-roadmap.md

@@ -7,6 +7,8 @@ Planning artifact; no code was changed.
 
 # Component Coverage Roadmap
 
+> **ARCHIVED — historical, not current guidance.** See [`docs/_archive/README.md`](../README.md) for why.
+
 > The library has **74 components** (≈105 `.svelte` files incl. sub-components). Roughly **26 are
 > "easy"** (deterministic prop→DOM, no portals/traps), **23 "medium"** (actions, focus jumps, layout
 > reads), **30 "hard/E2E-only"** (portals, focus traps, anchor positioning, drag, Milkdown). The plan:
@@ -82,7 +84,7 @@ E2E. [04](./04-hard-cases-and-e2e.md) draws that line.
 - **One component per commit**, message like `test(Button): browser-mode coverage`.
 - Each commit: write `ComponentName.svelte.test.ts`, run `pnpm test` (both projects green), tick the
   row in [`PROGRESS.md`](./PROGRESS.md), commit.
-- Don't chase coverage %. Stop at the behavior contracts in [02](./02-test-conventions.md)'s checklist.
+- Don't chase coverage %. Stop at the behavior contracts in [02](../../testing-components.md)'s checklist.
 
 ## Open questions / decisions needed
 

package/docs/{component-testing → _archive/component-testing}/04-hard-cases-and-e2e.md

@@ -6,6 +6,8 @@ Claims verified against src/lib at commit cc9958b. Planning artifact; no code wa
 
 # Hard Cases & E2E Strategy
 
+> **ARCHIVED — historical, not current guidance.** See [`docs/_archive/README.md`](../README.md) for why.
+
 > ~30 of the 74 components are "hard". But "hard" splits two ways: **most are hard for _jsdom_ yet
 > perfectly testable in Vitest browser mode** (focus traps, anchor positioning, ResizeObserver — all
 > work in a real Chromium); only **drag-heavy and Milkdown-class** components genuinely need a
@@ -32,7 +34,7 @@ candidates, both verified to exist:
 
 ### Candidate A (recommended) — anchor-position viewport clamping
 
-- **Code:** [`src/lib/utils/anchor-position.ts`](../../src/lib/utils/anchor-position.ts), consumed by
+- **Code:** [`src/lib/utils/anchor-position.ts`](../../../src/lib/utils/anchor-position.ts), consumed by
   `DropdownMenu/DropdownMenu.svelte` (and others).
 - **Why:** this is precisely what regressed in `9d8c974` _"clamp anchor-positioned annotations to
   viewport on all paths"_ and `8c52afe`. A test here has immediate, proven value and prevents
@@ -45,7 +47,7 @@ candidates, both verified to exist:
 
 ### Candidate B (alternative) — focus trap
 
-- **Code:** [`src/lib/actions/focus-trap.ts`](../../src/lib/actions/focus-trap.ts), used by
+- **Code:** [`src/lib/actions/focus-trap.ts`](../../../src/lib/actions/focus-trap.ts), used by
   `ModalDialog`, `Backdrop`, `Drawer`.
 - **Why:** Tab/Shift-Tab cycling and `returnFocus`-on-teardown are core a11y contracts that node
   cannot exercise at all.
@@ -59,7 +61,7 @@ candidates, both verified to exist:
 ## Portals & focus traps (browser-mode, later sprint)
 
 `Modal`, `ModalDialog`, `Backdrop`, `Drawer`, `AlertConfirmPrompt` — all use
-[`focus-trap.ts`](../../src/lib/actions/focus-trap.ts), scroll-lock, and an Escape-key stack. These
+[`focus-trap.ts`](../../../src/lib/actions/focus-trap.ts), scroll-lock, and an Escape-key stack. These
 are testable in browser mode (open → focus trapped → Escape closes → backdrop click closes →
 `returnFocus`). The stack/queue _logic_ is already unit-tested (`AlertConfirmPromptStack`,
 `NotificationsStack`); browser tests add the DOM-interaction layer. Higher effort, real value —

package/docs/{component-testing → _archive/component-testing}/05-ci.md

@@ -6,6 +6,8 @@ Claims verified against the repo at commit cc9958b. Planning artifact; no code w
 
 # CI — GitHub Actions
 
+> **ARCHIVED — historical, not current guidance.** See [`docs/_archive/README.md`](../README.md) for why.
+
 > The repo is on GitHub (`github.com/marianmeres/stuic`) and publishes to npm, so CI pays off: it
 > runs the tests automatically on every push/PR in a clean machine, catching regressions **before**
 > a broken release reaches npm. The plan: **one ~30-line workflow** that installs Chromium and runs

package/docs/{component-testing → _archive/component-testing}/PROGRESS.md

@@ -1,5 +1,7 @@
 # Implementation Progress — Component Testing
 
+> **ARCHIVED — historical, not current guidance.** See [`docs/_archive/README.md`](../README.md) for why.
+
 Living tracker for acting on [`00-overview-and-roadmap.md`](./00-overview-and-roadmap.md).
 A fresh conversation should read this file first, then the relevant `NN-*.md` section.
 
@@ -17,7 +19,7 @@ Branch: `feat/component-testing`
 | --- | ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- | ------ | --------- |
 | 1   | Upgrade vitest 3→4; confirm 9 existing node suites still green                                                            | [01](./01-framework-setup.md) Step 1        | ✅     | `71e47e2` |
 | 2   | Browser harness: add deps, `projects` config split, `playwright install chromium`, fix test scripts, Separator smoke test | [01](./01-framework-setup.md) Steps 2–5     | ✅     | `980b323` |
-| 3   | Reconcile [`docs/testing.md`](../testing.md) — add the browser-behavior layer                                             | [02](./02-test-conventions.md)              | ✅     | `977c431` |
+| 3   | Reconcile [`docs/testing.md`](../../testing.md) — add the browser-behavior layer                                          | [02](../../testing-components.md)           | ✅     | `977c431` |
 | 4   | **Button** — flagship; establish assertion patterns                                                                       | [03](./03-component-coverage-roadmap.md) #1 | ✅     | `9485e97` |
 | 5   | **Pill** — intent/active/dismissible event                                                                                | [03](./03-component-coverage-roadmap.md) #2 | ✅     | `2992faf` |
 | 6   | **Switch** — checked binding, toggle, disabled                                                                            | [03](./03-component-coverage-roadmap.md) #3 | ✅     | `6aa1771` |

package/docs/_archive/component-testing/README.md

@@ -0,0 +1,28 @@
+# Component Testing — archived plan
+
+> **ARCHIVED — historical, not current guidance.** See [`docs/_archive/README.md`](../README.md) for why.
+
+> **Archived.** This was the planning set that introduced real-browser component tests to STUIC
+> (Vitest 4 Browser Mode + `vitest-browser-svelte` + Playwright/Chromium), produced 2026-06-08
+> against the codebase at commit `cc9958b`. The plan was executed: the harness, the project split,
+> CI, and the component suite all shipped, and `PROGRESS.md` is closed out apart from two
+> deliberately deferred items.
+>
+> **For how to write a component test today, read
+> [`docs/testing-components.md`](../../testing-components.md)** — the conventions doc was promoted
+> out of this set and is the live reference. Everything below is provenance: why the stack was
+> chosen, what the tiers were, and how the sprint ran.
+
+## Documents
+
+| #   | Doc                                                              | Scope               | Headline                                                                                        |
+| --- | ---------------------------------------------------------------- | ------------------- | ----------------------------------------------------------------------------------------------- |
+| 00  | [overview-and-roadmap](./00-overview-and-roadmap.md)             | synthesis + roadmap | The stack is the right default; the vitest 3→4 upgrade was the gating prerequisite.             |
+| 01  | [framework-setup](./01-framework-setup.md)                       | infra               | Upgrade vitest 4, add a `projects` split (node `server` + browser `client`), route by filename. |
+| 03  | [component-coverage-roadmap](./03-component-coverage-roadmap.md) | inventory + tiers   | 74 components split easy / medium / hard; easy tier first, one commit each.                     |
+| 04  | [hard-cases-and-e2e](./04-hard-cases-and-e2e.md)                 | hard cases          | Most "hard" components are fine in browser mode; only drag/Milkdown need standalone E2E.        |
+| 05  | [ci](./05-ci.md)                                                 | CI                  | One ~30-line GitHub Actions workflow that installs Chromium and runs `pnpm test`.               |
+|     | [PROGRESS.md](./PROGRESS.md)                                     | tracker             | Execution log — what was built, in which commit.                                                |
+
+Doc 02 (test conventions) is **not** here; it lives at
+[`docs/testing-components.md`](../../testing-components.md).

package/docs/{upgrading.md → _archive/upgrading.md}

@@ -1,5 +1,7 @@
 # Upgrading STUIC
 
+> **ARCHIVED — historical, not current guidance.** See [`docs/_archive/README.md`](./README.md) for why.
+
 Notes for coding agents (and humans) maintaining a project that consumes `@marianmeres/stuic`. This doc describes the deltas introduced on top of **v3.66.1** — grouped by what a consumer actually cares about, not by commit.
 
 ## TL;DR

package/docs/architecture.md

@@ -36,19 +36,24 @@ Layer 4: Internal Vars        (--_bg, --_text, --_border)
 
 ```
 src/lib/
-├── components/           # 57 component directories
+├── components/           # 75 component directories
 │   └── {Name}/
 │       ├── {Name}.svelte     # Main component
 │       ├── index.ts          # Exports
 │       ├── index.css         # CSS tokens (if styled)
 │       └── README.md         # Documentation
 │
-├── actions/              # 15 Svelte actions
+├── actions/              # 16 Svelte actions
 │   ├── *.svelte.ts           # Reactive actions
 │   ├── *.ts                  # Traditional actions
 │   └── index.ts              # Barrel export
 │
-├── utils/                # 45 utility modules
+├── attachments/          # {@attach} DOM helpers (preferred over new actions)
+│   ├── auto-height.ts
+│   ├── long-press.ts
+│   └── index.ts              # Barrel export
+│
+├── utils/                # 55 utility modules (48 re-exported from the barrel)
 │   ├── *.svelte.ts           # Reactive utilities
 │   ├── *.ts                  # Pure functions
 │   └── index.ts              # Barrel export
@@ -58,6 +63,8 @@ src/lib/
 ├── css/                  # CSS-only presets (classes + tokens, no JS)
 │   └── frame.css             # Ratio-locked frame (letterbox)
 │
+├── types.ts              # Shared public types (DataAttributes, TranslateFn, …)
+├── mcp.ts                # MCP tool definitions (@marianmeres/mcp-server discovery)
 ├── index.css             # CENTRALIZED CSS imports
 └── index.ts              # Main barrel export
 ```
@@ -87,7 +94,7 @@ src/lib/
 **DO NOT** use `import './index.css'` inside component `.svelte` files.
 
 **Exception — subpath-export components.** A component whose peer dependencies are
-declared _optional_ (`MarkdownEditor`, `CommentInput`) is kept off the root barrel and
+declared _optional_ (`MarkdownEditor`, `CommentInput`, `TrendChart`) is kept off the root barrel and
 shipped behind its own subpath export, so those peers never enter the entry graph of
 consumers who don't use it. Such a component imports its own `index.css` locally and is
 **not** `@import`-ed into `src/lib/index.css` — centralizing it would ship the styles to
@@ -145,7 +152,7 @@ Props → Component → Data Attributes → CSS Selectors
 | ------------------------------------------ | --------------------------------------------------------------------------- |
 | `src/lib/index.css`                        | CSS entry point (import this)                                               |
 | `src/lib/index.ts`                         | JS entry point (barrel export)                                              |
-| `@marianmeres/design-tokens/css/stone.css` | Default theme (42 themes available)                                         |
+| `@marianmeres/design-tokens/css/stone.css` | Default theme (54 themes available)                                         |
 | `src/lib/utils/tw-merge.ts`                | Tailwind class merging                                                      |
 | `src/lib/utils/design-tokens.ts`           | Theme types (`ThemeSchema`, `ColorPair`, etc.) and CSS generation functions |
 
@@ -173,14 +180,15 @@ Theme CSS files are provided by the `@marianmeres/design-tokens` package (a regu
 "./phone-validation": Phone validation helpers
 "./markdown-editor":  MarkdownEditor  — optional peer deps, local CSS
 "./comment-input":    CommentInput    — optional peer deps, local CSS
+"./trend-chart":      TrendChart      — optional peer deps, local CSS
 ```
 
-The last two are deliberately **off** the main entry: they reach `@milkdown/*` and
-`@codemirror/*`, which are optional peers. A consumer that has not installed those
-peers gets a hard bundler error (rolldown reports every named import from the
-unresolved stub as `MISSING_EXPORT`) if the root barrel can reach them — even though
-the editor backends sit behind `await import()`, because the specifiers are static
-literals that a bundler must still resolve at build time.
+The last three are deliberately **off** the main entry: they reach `@milkdown/*`,
+`@codemirror/*` and `@marianmeres/trend-chart`, which are optional peers. A consumer
+that has not installed those peers gets a hard bundler error (rolldown reports every
+named import from the unresolved stub as `MISSING_EXPORT`) if the root barrel can reach
+them — even though the editor backends sit behind `await import()`, because the
+specifiers are static literals that a bundler must still resolve at build time.
 
 ---
 

package/docs/domains/actions.md

@@ -2,7 +2,7 @@
 
 ## Overview
 
-15 Svelte actions (directives) for reusable DOM behavior.
+16 Svelte actions (directives) for reusable DOM behavior.
 
 ---
 
@@ -18,6 +18,7 @@
 | `fileDropzone`            | Drag-and-drop file handling                                   | `file-dropzone.svelte.ts`            |
 | `highlightDragover`       | Visual feedback on drag-over                                  | `highlight-dragover.svelte.ts`       |
 | `resizableWidth`          | Draggable width resizing                                      | `resizable-width.svelte.ts`          |
+| `draggable`               | Pointer-delta drag handle (consumer owns the movement)        | `draggable.svelte.ts`                |
 | `trim`                    | Auto-trim whitespace from input                               | `trim.svelte.ts`                     |
 | `typeahead`               | Advanced autocomplete behavior                                | `typeahead.svelte.ts`                |
 | `onSubmitValidityCheck`   | Form submit validation                                        | `on-submit-validity-check.svelte.ts` |
@@ -120,8 +121,8 @@ Per the HTML spec, `<input type="hidden">` is _barred from constraint
 validation_ — `validity.valueMissing` stays `false` regardless of the
 `required` attribute, and native browser submit blocking is skipped. Several
 STUIC field components (`FieldPhoneNumber`, `FieldCountry`, `FieldObject`,
-`FieldAssets`, `FieldInputLocalized`, `FieldKeyValues`, `FieldLikeButton`)
-use a hidden input to participate in `FormData`, so they each enforce
+`FieldAssets`, `FieldInputLocalized`, `FieldKeyValues`, `FieldLikeButton`,
+`FieldDate`, `FieldDateRange`) use a hidden input to participate in `FormData`, so they each enforce
 `required` themselves inside their `customValidator`:
 
 ```ts

package/docs/domains/components.md

@@ -2,7 +2,7 @@
 
 ## Overview
 
-74 Svelte 5 component directories with consistent API patterns. All use runes-based reactivity.
+75 Svelte 5 component directories with consistent API patterns. All use runes-based reactivity.
 
 ## Component Categories
 
@@ -58,22 +58,24 @@
 
 ### Form
 
-| Component                                     | Purpose                                                                     |
-| --------------------------------------------- | --------------------------------------------------------------------------- |
-| Input (FieldInput, FieldSelect, etc.)         | Form fields                                                                 |
-| FieldMoney                                    | Money input storing integer minor units (e.g. cents)                        |
-| FieldPhoneNumber                              | International phone input with country picker                               |
-| FieldObject                                   | Dual-mode JSON object editor (pretty-print/raw)                             |
-| CronInput                                     | Cron expression editor with presets and validation                          |
-| Fieldset                                      | Field grouping with legend                                                  |
-| FieldKeyValues                                | Key-value pair editor                                                       |
-| FieldsBuilder                                 | Field-definition list editor ("what properties does a thing have?")         |
-| FieldAssets                                   | File/asset management                                                       |
-| LoginForm, LoginFormModal                     | Standalone login form with optional modal variant                           |
-| RegisterForm                                  | Standalone registration form with declarative extra fields                  |
-| LoginOrRegisterForm, LoginOrRegisterFormModal | Composite login/register/verify form (3 modes, shared social-logins)        |
-| EmailVerifyForm                               | Post-registration email-verify form (OtpInput + resend cooldown)            |
-| OtpInput                                      | Generic N-slot one-time-code input (numeric/alphanumeric, paste-distribute) |
+| Component                                     | Purpose                                                                                    |
+| --------------------------------------------- | ------------------------------------------------------------------------------------------ |
+| Input (FieldInput, FieldSelect, etc.)         | Form fields                                                                                |
+| FieldMoney                                    | Money input storing integer minor units (e.g. cents)                                       |
+| Calendar                                      | Month grid for single-date / range picking: keyboard grid, min/max, dropdown caption, i18n |
+| FieldDate, FieldDateRange                     | Date / date-range fields around Calendar: trigger + dialog or embedded; ISO hidden inputs  |
+| FieldPhoneNumber                              | International phone input with country picker                                              |
+| FieldObject                                   | Dual-mode JSON object editor (pretty-print/raw)                                            |
+| CronInput                                     | Cron expression editor with presets and validation                                         |
+| Fieldset                                      | Field grouping with legend                                                                 |
+| FieldKeyValues                                | Key-value pair editor                                                                      |
+| FieldsBuilder                                 | Field-definition list editor ("what properties does a thing have?")                        |
+| FieldAssets                                   | File/asset management                                                                      |
+| LoginForm, LoginFormModal                     | Standalone login form with optional modal variant                                          |
+| RegisterForm                                  | Standalone registration form with declarative extra fields                                 |
+| LoginOrRegisterForm, LoginOrRegisterFormModal | Composite login/register/verify form (3 modes, shared social-logins)                       |
+| EmailVerifyForm                               | Post-registration email-verify form (OtpInput + resend cooldown)                           |
+| OtpInput                                      | Generic N-slot one-time-code input (numeric/alphanumeric, paste-distribute)                |
 
 ### Display
 
@@ -150,7 +152,7 @@ Use `validate={false}` to bypass stuic's validation entirely.
 
 > **Why default-on?** Hidden-input field components (`FieldPhoneNumber`,
 > `FieldCountry`, `FieldObject`, `FieldAssets`, `FieldInputLocalized`,
-> `FieldKeyValues`, `FieldLikeButton`) _must_ be default-on because hidden
+> `FieldKeyValues`, `FieldLikeButton`, `FieldDate`, `FieldDateRange`) _must_ be default-on because hidden
 > inputs are excluded from native browser constraint validation — without the
 > stuic action enforcing `required` in a `customValidator`, the attribute is a
 > silent no-op. Plain-input field components were harmonized to the same
@@ -161,7 +163,8 @@ Use `validate={false}` to bypass stuic's validation entirely.
 Available on `FieldInput`, `FieldMoney`, `FieldTextarea`, `FieldCheckbox`,
 `FieldSelect`, `FieldFile`, `FieldObject`, `FieldAssets`, `FieldInputLocalized`,
 `FieldKeyValues`, `FieldPhoneNumber`, `FieldCountry`, `FieldLikeButton`,
-`FieldRadios`, `FieldSwitch`, `FieldOptions`, and `Switch`:
+`FieldRadios`, `FieldSwitch`, `FieldOptions`, `FieldDate`, `FieldDateRange`, and
+`Switch`:
 
 | Method                  | Returns                         | Purpose                                                       |
 | ----------------------- | ------------------------------- | ------------------------------------------------------------- |

package/docs/domains/utils.md

@@ -2,7 +2,8 @@
 
 ## Overview
 
-45 utility modules for common tasks. Organized by category.
+55 utility modules for common tasks (48 re-exported from the package barrel; the rest
+are library-internal). Organized by category.
 
 ---
 

package/docs/maybe-todo.md

@@ -24,12 +24,12 @@ Checked first, to avoid false positives:
 
 ## Tier 1 — staples nearly every comparable library ships
 
-1. **Date picker / Calendar** — the single biggest gap. No calendar grid, no date-range
-   picker anywhere in the lib (only native `type="date"` via `FieldInput`).
-   `@marianmeres/calendar-utils` already does the date math, so this is mostly UI work.
-   A `FieldDate` / `FieldDateRange` would slot naturally next to `FieldMoney` /
-   `FieldPhoneNumber`. Most work of anything on this list, but also the absence
-   consumers will actually notice.
+1. ~~**Date picker / Calendar**~~ — ✅ shipped (see `src/lib/components/Calendar/` and
+   `FieldDate` / `FieldDateRange` in `Input/`): `Calendar` is the month grid (single /
+   range, APG keyboard grid, min/max/blackouts, dropdown caption, multiple months, week
+   numbers, `renderDay`, Intl names + `t` texts with Slovak bundled), built on
+   `@marianmeres/calendar-utils`; the fields wrap it as trigger + dialog or embedded, with
+   ISO `YYYY-MM-DD` hidden inputs and the usual validate API.
 2. ~~**Breadcrumbs**~~ — ✅ shipped (see `src/lib/components/Breadcrumbs/`):
    APG nav/ol trail, collapsible long trails, schema.org `BreadcrumbList` JSON-LD
    helpers (`breadcrumbsJsonLd` / `breadcrumbsJsonLdScript` + inline `jsonLd` prop).

package/docs/tasks.md

@@ -149,7 +149,9 @@ For consumers creating their own theme outside the library.
 ```ts
 import type { ThemeSchema } from "@marianmeres/stuic";
 import { generateThemeCss } from "@marianmeres/stuic";
-import stone from "@marianmeres/stuic/themes/stone";
+// Built-in theme schemas live in design-tokens, not in stuic. stuic depends on it,
+// but add it to your own package.json if you import from it directly.
+import { stone } from "@marianmeres/design-tokens/themes";
 import { writeFileSync } from "node:fs";
 
 const myTheme: ThemeSchema = {
@@ -166,7 +168,9 @@ const myTheme: ThemeSchema = {
 	dark: stone.dark,
 };
 
-writeFileSync("src/theme.css", generateThemeCss(myTheme));
+// generateThemeCss(schema, prefix, options?) — the "stuic-" prefix is what the
+// library's own CSS reads (--stuic-color-primary, …), so it is not optional.
+writeFileSync("src/theme.css", generateThemeCss(myTheme, "stuic-"));
 ```
 
 ### Checklist
@@ -179,20 +183,26 @@ writeFileSync("src/theme.css", generateThemeCss(myTheme));
 
 ## Test Changes
 
+The repo uses **pnpm**.
+
 ### Steps
 
-1. Run `npm run build` - Check for errors
-2. Run `npm run check` - TypeScript validation
-3. Run `npm run dev` - Start dev server
-4. Test in browser (http://localhost:8886)
-5. Test light mode
-6. Test dark mode (add `class="dark"` to `<html>`)
-7. Test that `--stuic-color-primary` changes cascade
+1. Run `pnpm run build` - Check for errors
+2. Run `pnpm run check` - TypeScript validation (`svelte-check`)
+3. Run `pnpm run lint` - ESLint + Prettier
+4. Run `pnpm test` - Node + browser suites (see [Testing](./testing.md))
+5. Run `pnpm run dev` - Start dev server
+6. Test in browser (http://localhost:8886)
+7. Test light mode
+8. Test dark mode (add `class="dark"` to `<html>`)
+9. Test that `--stuic-color-primary` changes cascade
 
 ### Checklist
 
 - [ ] No build errors
 - [ ] No TypeScript errors
+- [ ] Lint clean
+- [ ] Tests green
 - [ ] Component renders correctly
 - [ ] Light mode works
 - [ ] Dark mode works

package/docs/{component-testing/02-test-conventions.md → testing-components.md}

@@ -1,45 +1,30 @@
-<!--
-GENERATED ANALYSIS — @marianmeres/stuic real-browser component testing
-Produced 2026-06-08 by multi-agent research → adversarial verify → synthesize.
-Claims verified against the codebase at commit cc9958b and the live
-vitest-browser-svelte docs. Planning artifact; no code was changed.
--->
+# Component Test Conventions
 
-# Test Conventions
+How to write a STUIC browser component test, and — just as important — **what is worth asserting**.
 
-> How to write a STUIC browser component test, and — just as important — **what is worth
-> asserting**. The headline: test _behavior the build can't see_ (events fire, bindings update,
+> The headline: test _behavior the build can't see_ (events fire, bindings update,
 > aria/disabled/active states, computed layout), not "does it render" (already gated by
 > `svelte-check` + `publint` + the build). Use `render()` → locators → `expect.element`. In Svelte 5
 > events are props, so you assert them with spies; snippet children come from `createRawSnippet`.
 
-## Reconciling with `docs/testing.md`
+Companion to [`testing.md`](./testing.md), which covers the suite as a whole (both layers, what we
+test and what we deliberately don't). This document is the how-to for the browser layer only.
 
-[`docs/testing.md`](../testing.md) currently states the library **deliberately does not** test full
-component rendering ("50+ components × prop combinations = slow suite with tiny yield... Rendering is
-already gated by svelte-check + publint + the build") and treats interactive/visual behavior as
-out of scope.
+## The line this layer does and doesn't cross
 
-That reasoning was **correct for what it described and is not actually reversed here** — it just
-predates a capability we didn't have:
+"Does it render / compile / export" is still low-yield and still covered by `svelte-check` +
+`publint` + the build. We do **not** write tests for that.
 
-- "Does it render / compile / export" → still low-yield, still covered by `svelte-check` + `publint` +
-  build. We will **not** write tests for that.
-- "Does it _behave_" — click handlers, two-way `bind:`, `aria-*`/`disabled`/`active` state, focus
-  traps, viewport-clamped anchor positioning (cf. the recent `9d8c974` annotation-clamp fix) — was
-  **previously impossible** (node/server build, no DOM, no `$effect`). Browser mode makes it possible,
-  and _this_ is the high-yield target.
-
-**Task in the roadmap:** update `docs/testing.md` to add this browser-test layer so the docs aren't
-self-contradictory — promote "interactive behavior" from ❌ to ✅-when-it's-a-real-contract, and point
-to this directory. (See [`PROGRESS.md`](./PROGRESS.md), sprint task.)
+"Does it _behave_" — click handlers, two-way `bind:`, `aria-*`/`disabled`/`active` state, focus
+traps, viewport-clamped anchor positioning — was impossible before browser mode (node/server build,
+no DOM, no `$effect`). That is the high-yield target, and the whole reason this layer exists.
 
 ## File naming & location
 
 - One test per component, **co-located** next to the `.svelte` file (matches the existing co-located
   style, e.g. `Input/phone-validation.test.ts`).
 - Name it `ComponentName.svelte.test.ts` — the `.svelte.test.ts` suffix is what routes it into the
-  browser `client` project (see [01](./01-framework-setup.md)). A plain `*.test.ts` next to a
+  browser `client` project (see [`_archive/component-testing/01-framework-setup.md`](./_archive/component-testing/01-framework-setup.md)). A plain `*.test.ts` next to a
   component stays in the fast node project (correct for extracted pure logic like `_internal/*.ts`).
 
 ## The canonical test
@@ -142,8 +127,22 @@ Rely on `expect.element` retries and awaited locator actions — **never fixed `
 reactivity resolves through the retry loop; only assertions on _external_ universal state living in a
 `*.svelte.ts` module may need `flushSync()` from `svelte`.
 
-## Open questions / decisions needed
+## Shared helpers
+
+There is deliberately **no shared test-util module**. The one recurring helper — a `text()` snippet
+factory for `children` — is three lines, so each test file declares its own copy rather than
+importing across the tree:
+
+```ts
+const text = (s: string) =>
+	createRawSnippet(() => ({ render: () => `<span>${s}</span>` }));
+```
+
+Revisit only if a genuinely non-trivial helper shows up.
+
+## Where this came from
 
-- **Shared test utilities** — agree on one home for the `text()` snippet helper and any future
-  fixtures (suggest `src/lib/test-utils/` or `src/test-helpers.ts`), so it's not redefined per file.
-  Decide when the second snippet-needing component lands.
+The plan that produced this layer (roadmap, framework setup, coverage tiers, CI, and the completed
+progress tracker) is archived under
+[`_archive/component-testing/`](./_archive/component-testing/). It is history, not guidance — this
+file is the live convention.

package/docs/testing.md

@@ -16,7 +16,7 @@ Tests are for what those tools can't see. There are **two layers**, split by fil
 - **`*.test.ts` — node, fast.** Pure deterministic logic where a regression silently corrupts data.
 - **`*.svelte.test.ts` — real browser (Chromium).** Component _behavior_ the build can't see: events firing, two-way `bind:`, `aria`/`disabled`/`active` state, focus traps, computed layout/positioning.
 
-We still explicitly don't try to test everything. The browser layer targets **behavior contracts**, not "does it render" — see [`component-testing/`](./component-testing/) for the strategy, roadmap, and how-to.
+We still explicitly don't try to test everything. The browser layer targets **behavior contracts**, not "does it render" — see [`testing-components.md`](./testing-components.md) for the how-to and the "what to assert" checklist.
 
 ## What we test
 
@@ -79,8 +79,8 @@ const t: TranslateFn = (k) => k;
 For **component** tests (`*.svelte.test.ts`), the patterns differ — `render()` from
 `vitest-browser-svelte`, locators, and the retry-able `expect.element`; events are props (assert with
 spies); snippet children come from `createRawSnippet`. See
-[`component-testing/02-test-conventions.md`](./component-testing/02-test-conventions.md) for the full
-how-to and the "what to assert" checklist.
+[`testing-components.md`](./testing-components.md) for the full how-to and the "what to assert"
+checklist.
 
 ## When in doubt
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@marianmeres/stuic",
-	"version": "3.170.0",
+	"version": "3.172.0",
 	"packageManager": "pnpm@11.5.0",
 	"scripts": {
 		"dev": "vite dev",
@@ -183,6 +183,7 @@
 		"vitest-browser-svelte": "^2.2.1"
 	},
 	"dependencies": {
+		"@marianmeres/calendar-utils": "^2.0.0",
 		"@marianmeres/clog": "^3.21.0",
 		"@marianmeres/countries": "^1.1.0",
 		"@marianmeres/cron-parser": "^1.0.1",

package/docs/component-testing/README.md

@@ -1,38 +0,0 @@
-<!--
-GENERATED ANALYSIS — @marianmeres/stuic real-browser component testing
-Produced 2026-06-08 by multi-agent research → adversarial verify → synthesize.
-Claims verified against the codebase at commit cc9958b and the live Vitest 4 /
-vitest-browser-svelte docs. Planning artifact; no code was changed.
--->
-
-# Component Testing — @marianmeres/stuic
-
-This directory holds the plan for introducing **real-browser component tests** to STUIC
-(Vitest 4 Browser Mode + `vitest-browser-svelte` + Playwright/Chromium). It was produced
-2026-06-08 from a research pass over the codebase and the current Svelte/Vitest ecosystem.
-It is a **planning artifact — no code has been changed**; every claim is verified against the
-repo at commit `cc9958b` or against the live docs cited in each section.
-
-**Start here:** [`00-overview-and-roadmap.md`](./00-overview-and-roadmap.md). Then track and
-resume execution from [`PROGRESS.md`](./PROGRESS.md).
-
-## Documents
-
-| #   | Doc                                                              | Scope               | Headline                                                                                             |
-| --- | ---------------------------------------------------------------- | ------------------- | ---------------------------------------------------------------------------------------------------- |
-| 00  | [overview-and-roadmap](./00-overview-and-roadmap.md)             | synthesis + roadmap | The stack is the right default; vitest 3→4 upgrade is the gating prerequisite.                       |
-| 01  | [framework-setup](./01-framework-setup.md)                       | infra               | Upgrade vitest 4, add a `projects` split (node `server` + browser `client`), route by filename.      |
-| 02  | [test-conventions](./02-test-conventions.md)                     | how-to              | `render()` + locators + `expect.element`; events are props (spies); snippets via `createRawSnippet`. |
-| 03  | [component-coverage-roadmap](./03-component-coverage-roadmap.md) | what to cover       | 74 components tiered; warm up on Button/Pill/Switch, one commit per component.                       |
-| 04  | [hard-cases-and-e2e](./04-hard-cases-and-e2e.md)                 | the hard 30         | Portals/focus-traps/anchor-positioning: one "hard proof" now; standalone Playwright E2E deferred.    |
-| 05  | [ci](./05-ci.md)                                                 | automation          | One ~30-line GitHub Actions workflow; install Chromium, run `pnpm test`.                             |
-
-## How it was produced
-
-Five parallel research agents (test-infra audit, full component inventory, multistep-format
-extraction, two independent web-research angles on the stack) → synthesis → live-docs
-verification of the exact Vitest 4 config syntax → this plan.
-
-> Nothing here is decided beyond the four clarifying answers recorded in
-> [`PROGRESS.md`](./PROGRESS.md) → Decisions log. Each doc's "Open questions / decisions needed"
-> lists what still needs a call.