@marianmeres/stuic 3.113.0 → 3.115.0

package/docs/component-testing/README.md

@@ -0,0 +1,38 @@
+<!--
+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.

package/docs/testing.md

@@ -11,7 +11,12 @@ This is a component library. Most of its correctness guarantees come from:
 3. **The build** — every component compiles, every export resolves.
 4. **Manual/visual review** — styling, animation, keyboard interaction, a11y cues.
 
-Unit tests are for what those tools can't see: **pure deterministic logic where a regression silently corrupts data**. We explicitly don't try to test everything.
+Tests are for what those tools can't see. There are **two layers**, split by filename:
+
+- **`*.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.
 
 ## What we test
 
@@ -20,6 +25,7 @@ Unit tests are for what those tools can't see: **pure deterministic logic where
 - **Validation helpers** — `validateEmail`, `validateAddress`, `validateCustomerForm`, `validateLoginForm`, `validatePhoneNumber`, `addressesEqual`.
 - **State-machine classes** — `NotificationsStack`, `AlertConfirmPromptStack`, `SwitchState`, `InputHistory`. Tri-state transitions, dedupe, ordering, cleanup semantics.
 - **Pure utilities** — `replace-map`, `tr`, `storage-abstraction`, and anything else with non-trivial input/output logic.
+- **Component behavior** (browser mode, `*.svelte.test.ts`) — prop→DOM/`aria` contracts, events firing, `bind:` updates, focus traps, viewport-clamped positioning. One component at a time, asserting contracts a consumer relies on — not every prop permutation.
 
 ### ⚠️ Maybe, if motivated by a regression
 
@@ -27,18 +33,23 @@ Unit tests are for what those tools can't see: **pure deterministic logic where
 
 ### ❌ We don't test
 
-- **Full component rendering** via `@testing-library/svelte`. 50+ components × prop combinations = slow suite with tiny yield. Rendering is already gated by `svelte-check` + `publint` + the build.
-- **Visual regression**. That's a separate project (Playwright + screenshot diffing) — not part of `vitest --dir src/`.
-- **Interactive behavior** (keyboard nav, drag-drop, scroll snap) unless the underlying math is extracted to a pure function.
+- **Exhaustive prop-matrix / "does it render" tests.** 50+ components × every prop combination = slow suite with tiny yield. Rendering is already gated by `svelte-check` + `publint` + the build; the browser layer asserts _behavior contracts_, not coverage of every permutation.
+- **Visual regression**. A separate concern (Vitest's `toMatchScreenshot` / screenshot diffing) — deferred, not part of `pnpm test` today.
+- **Heavy gestures & 3rd-party editors** (drag-drop reorder, file drop, Milkdown/CodeMirror) — deferred to a future standalone Playwright **E2E** layer, not the in-repo browser project. Extract and node-test their pure logic where practical.
 - **Coverage % targets**. They're the wrong goal for a component library.
 
 ## Running tests
 
 ```bash
-pnpm run test
+pnpm test          # both projects (node + browser), one-shot
+pnpm test:watch    # watch mode
+pnpm test:ui       # Vitest UI (handy for the browser project)
 ```
 
-Vitest is configured to run everything under `src/`. Tests live next to the code they test: `foo.ts` → `foo.test.ts`.
+Vitest runs **two projects**, routed by filename: a node project for `*.test.ts` and a real-browser
+(Chromium, via Playwright) project for `*.svelte.test.ts`. Tests live next to the code they test:
+`foo.ts` → `foo.test.ts`; `Foo.svelte` → `Foo.svelte.test.ts`. The browser binary is installed once
+with `pnpm exec playwright install chromium`.
 
 ## Writing a test
 
@@ -65,8 +76,16 @@ import type { TranslateFn } from "$lib/types.js";
 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.
+
 ## When in doubt
 
-- **Logic in a `.ts` file with clear input/output?** Write a test.
+- **Logic in a `.ts` file with clear input/output?** Write a `*.test.ts`.
+- **A component behavior that's a real contract** (event fires, value binds, focus traps, position
+  clamps)? Write a `*.svelte.test.ts`.
 - **A regression just bit you in production?** Write a test for that specific case before fixing.
-- **Anything else?** Probably don't bother.
+- **"Does it render with these 12 props?"** Probably don't bother — the build already covers that.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@marianmeres/stuic",
-	"version": "3.113.0",
+	"version": "3.115.0",
 	"scripts": {
 		"dev": "vite dev",
 		"build": "vite build && pnpm run prepack",
@@ -13,7 +13,9 @@
 		"check:watch": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json --watch",
 		"format": "prettier --write .",
 		"lint": "eslint . && prettier --check .",
-		"test": "vitest --dir src/",
+		"test": "vitest run",
+		"test:watch": "vitest",
+		"test:ui": "vitest --ui",
 		"svelte-check": "svelte-check",
 		"svelte-package": "svelte-package",
 		"rp": "pnpm run build && ./release.sh patch",
@@ -145,9 +147,11 @@
 		"@tailwindcss/typography": "^0.5.19",
 		"@tailwindcss/vite": "^4.3.0",
 		"@types/node": "^25.9.2",
+		"@vitest/browser-playwright": "^4.1.8",
 		"dotenv": "^16.6.1",
 		"eslint": "^9.39.4",
 		"globals": "^16.5.0",
+		"playwright": "^1.60.0",
 		"prettier": "^3.8.3",
 		"prettier-plugin-svelte": "^3.5.2",
 		"publint": "^0.3.21",
@@ -158,7 +162,8 @@
 		"typescript": "^5.9.3",
 		"typescript-eslint": "^8.60.1",
 		"vite": "^7.3.5",
-		"vitest": "^3.2.6"
+		"vitest": "^4.1.8",
+		"vitest-browser-svelte": "^2.1.1"
 	},
 	"dependencies": {
 		"@marianmeres/clog": "^3.21.0",