@marianmeres/stuic 3.170.0 → 3.172.0

package/dist/components/Input/_internal/FieldDateShell.svelte

@@ -0,0 +1,327 @@
+<!--
+	Internal: the field scaffolding shared by FieldDate and FieldDateRange — the
+	InputWrap shell, the trigger button (icon + formatted value / placeholder + a
+	trailing × that clears), the hidden inputs that carry the ISO value(s) into
+	FormData (the first one runs the `validate` action), and the picker's two
+	homes: inline inside the field (`embedded`) or a native <dialog> opened by the
+	trigger. The picker itself is the `children` snippet; the owning field decides
+	what it is and what it means.
+
+	WHY hidden inputs: the visible trigger is a <button>, so nothing would be
+	submitted otherwise — and a hidden input is barred from native constraint
+	validation, which is why `required` / min / max are enforced by the owning
+	field's customValidator (same as FieldPhoneNumber / FieldCountry / …).
+-->
+<script lang="ts" module>
+	import type { Snippet } from "svelte";
+	import type { ValidateOptions } from "../../../actions/validate.svelte.js";
+	import type { THC } from "../../Thc/Thc.svelte";
+	import type { InputWrapClassProps } from "../types.js";
+
+	type SnippetWithId = Snippet<[{ id: string }]>;
+
+	/** One hidden `<input>` the field submits. The first one carries the `validate` action. */
+	export interface FieldDateHiddenInput {
+		name?: string;
+		value: string;
+	}
+
+	export interface Props extends InputWrapClassProps {
+		id: string;
+		label?: SnippetWithId | THC;
+		description?: SnippetWithId | THC;
+		labelAfter?: SnippetWithId | THC;
+		below?: SnippetWithId | THC;
+		class?: string;
+		style?: string;
+		renderSize?: "sm" | "md" | "lg" | string;
+		required?: boolean;
+		disabled?: boolean;
+		tabindex?: number;
+		labelLeft?: boolean;
+		labelLeftWidth?: "normal" | "wide";
+		labelLeftBreakpoint?: number;
+		/** Formatted value shown in the trigger (`""` = empty → placeholder) */
+		display: string;
+		placeholder: string;
+		/** Show the trailing × while there is a value */
+		clearable: boolean;
+		clearLabel: string;
+		/** Render the picker inline inside the field instead of trigger + dialog */
+		embedded: boolean;
+		inputs: FieldDateHiddenInput[];
+		validate?: boolean | Omit<ValidateOptions, "setValidationResult">;
+		dialogTitle: string;
+		closeLabel: string;
+		noScrollLock?: boolean;
+		/** Classes for the trigger button */
+		classInput?: string;
+		/** Classes for the dialog box */
+		classDialog?: string;
+		/** The first hidden input (bindable) */
+		input?: HTMLInputElement;
+		onOpen?: () => void;
+		onClose?: () => void;
+		onClear: () => void;
+		/** The picker */
+		children: Snippet;
+	}
+</script>
+
+<script lang="ts">
+	import {
+		validate as validateAction,
+		type ValidationResult,
+	} from "../../../actions/validate.svelte.js";
+	import { iconCalendar, iconX } from "../../../icons/index.js";
+	import { twMerge } from "../../../utils/tw-merge.js";
+	import Button from "../../Button/Button.svelte";
+	import ModalDialog from "../../ModalDialog/ModalDialog.svelte";
+	import InputWrap from "./InputWrap.svelte";
+
+	let {
+		id,
+		label = "",
+		description,
+		labelAfter,
+		below,
+		class: classProp,
+		style,
+		renderSize = "md",
+		required = false,
+		disabled = false,
+		tabindex = 0,
+		labelLeft = false,
+		labelLeftWidth = "normal",
+		labelLeftBreakpoint = 480,
+		classLabel,
+		classLabelBox,
+		classInputBox,
+		classInputBoxWrap,
+		classInputBoxWrapInvalid,
+		classDescBox,
+		classDescBoxToggle,
+		classBelowBox,
+		classValidationBox,
+		display,
+		placeholder,
+		clearable,
+		clearLabel,
+		embedded,
+		inputs,
+		// Renamed local binding to avoid collision with `export function validate()` below.
+		validate: validateProp,
+		dialogTitle,
+		closeLabel,
+		noScrollLock = false,
+		classInput,
+		classDialog,
+		input = $bindable(),
+		onOpen,
+		onClose,
+		onClear,
+		children,
+	}: Props = $props();
+
+	let validation: ValidationResult | undefined = $state();
+	const setValidationResult = (res: ValidationResult) => (validation = res);
+	let _doValidate: (() => void) | undefined = $state();
+
+	// Internal refs; the public `input` bindable is a write-out mirror.
+	let hiddenEl: HTMLInputElement | undefined = $state();
+	let triggerEl: HTMLButtonElement | undefined = $state();
+	let embeddedEl: HTMLDivElement | undefined = $state();
+	let dialog: ModalDialog | undefined = $state();
+
+	$effect(() => {
+		input = hiddenEl;
+	});
+
+	let isOpen = $derived(!embedded && !!dialog?.visibility().visible);
+
+	/** Trigger validation now. Renders the inline message if invalid. */
+	export function validate(): ValidationResult | undefined {
+		_doValidate?.();
+		return validation;
+	}
+
+	/** Clear the inline validation message and reset `setCustomValidity`. */
+	export function clearValidation(): void {
+		validation = undefined;
+		hiddenEl?.setCustomValidity?.("");
+	}
+
+	/** Current validation state, or undefined if validator has never run. */
+	export function getValidation(): ValidationResult | undefined {
+		return validation;
+	}
+
+	/** Focus the trigger (dialog mode) or the picker's tabbable day (embedded). */
+	export function focus(): void {
+		if (embedded) embeddedEl?.querySelector<HTMLElement>('[tabindex="0"]')?.focus?.();
+		else triggerEl?.focus?.();
+	}
+
+	/** Scroll the field into view. Defaults to smooth + center. */
+	export function scrollIntoView(opts?: ScrollIntoViewOptions): void {
+		(embedded ? embeddedEl : triggerEl)?.scrollIntoView?.({
+			behavior: "smooth",
+			block: "center",
+			...opts,
+		});
+	}
+
+	/** Re-run validation the way a user edit would (the action listens on `change`). */
+	export function dispatchChange(): void {
+		hiddenEl?.dispatchEvent(new Event("change", { bubbles: true }));
+	}
+
+	/** Open the picker dialog (no-op when `embedded` or `disabled`). */
+	export function open(): void {
+		if (embedded || disabled) return;
+		dialog?.open(triggerEl ?? null);
+		onOpen?.();
+	}
+
+	/** Close the picker dialog. */
+	export function close(): void {
+		dialog?.close();
+	}
+
+	/** Whether the picker dialog is currently open. */
+	export function isDialogOpen(): boolean {
+		return isOpen;
+	}
+
+	function clear() {
+		onClear();
+		triggerEl?.focus?.();
+	}
+</script>
+
+<InputWrap
+	{description}
+	class={classProp}
+	size={renderSize}
+	{id}
+	{label}
+	{labelAfter}
+	{below}
+	{required}
+	{disabled}
+	{labelLeft}
+	{labelLeftWidth}
+	{labelLeftBreakpoint}
+	{classLabel}
+	{classLabelBox}
+	{classInputBox}
+	{classInputBoxWrap}
+	{classInputBoxWrapInvalid}
+	{classDescBox}
+	{classDescBoxToggle}
+	{classBelowBox}
+	{classValidationBox}
+	{validation}
+	{style}
+>
+	{#if embedded}
+		<div bind:this={embeddedEl} class="stuic-field-date-embedded" data-size={renderSize}>
+			{@render children()}
+		</div>
+	{:else}
+		<button
+			bind:this={triggerEl}
+			type="button"
+			{id}
+			class={twMerge("stuic-field-date-trigger", classInput)}
+			data-size={renderSize}
+			data-empty={display ? undefined : ""}
+			aria-haspopup="dialog"
+			aria-expanded={isOpen}
+			{disabled}
+			{tabindex}
+			onclick={open}
+		>
+			<span class="stuic-field-date-trigger-icon" aria-hidden="true">
+				{@html iconCalendar({ size: 18 })}
+			</span>
+			<span class="stuic-field-date-trigger-label">{display || placeholder}</span>
+		</button>
+	{/if}
+
+	{#snippet inputAfter()}
+		{#if !embedded && clearable && display && !disabled}
+			<div class="flex items-center pr-1">
+				<Button
+					iconButton
+					variant="ghost"
+					roundedFull
+					type="button"
+					size={renderSize === "lg" ? "md" : "sm"}
+					class="stuic-field-date-clear"
+					aria-label={clearLabel}
+					tooltip={clearLabel}
+					onclick={clear}
+				>
+					{@html iconX({ size: 16 })}
+				</Button>
+			</div>
+		{/if}
+	{/snippet}
+
+	{#each inputs as h, i (i)}
+		{#if i === 0}
+			<input
+				bind:this={hiddenEl}
+				type="hidden"
+				id={embedded ? id : undefined}
+				name={h.name}
+				value={h.value}
+				use:validateAction={() => ({
+					enabled: validateProp !== false,
+					...(typeof validateProp === "boolean" ? {} : validateProp),
+					setValidationResult,
+					setDoValidate: (fn) => (_doValidate = fn),
+				})}
+				{required}
+				{disabled}
+			/>
+		{:else}
+			<input type="hidden" name={h.name} value={h.value} {disabled} />
+		{/if}
+	{/each}
+</InputWrap>
+
+{#if !embedded}
+	<ModalDialog
+		bind:this={dialog}
+		ariaLabelledby="{id}-dialog-title"
+		noAutoFocus
+		{noScrollLock}
+		preClose={() => {
+			onClose?.();
+		}}
+		class="bg-transparent shadow-none pointer-events-none size-auto max-w-full"
+	>
+		<div class={twMerge("stuic-field-date-dialog pointer-events-auto", classDialog)}>
+			<div class="stuic-field-date-dialog-header">
+				<span id="{id}-dialog-title" class="stuic-field-date-dialog-title"
+					>{dialogTitle}</span
+				>
+				<Button
+					x
+					size="sm"
+					variant="ghost"
+					roundedFull
+					type="button"
+					aria-label={closeLabel}
+					tooltip={closeLabel}
+					onclick={close}
+				/>
+			</div>
+			<div class="stuic-field-date-dialog-body">
+				{@render children()}
+			</div>
+		</div>
+	</ModalDialog>
+{/if}

package/dist/components/Input/_internal/FieldDateShell.svelte.d.ts

@@ -0,0 +1,66 @@
+import type { Snippet } from "svelte";
+import type { ValidateOptions } from "../../../actions/validate.svelte.js";
+import type { THC } from "../../Thc/Thc.svelte";
+import type { InputWrapClassProps } from "../types.js";
+type SnippetWithId = Snippet<[{
+    id: string;
+}]>;
+/** One hidden `<input>` the field submits. The first one carries the `validate` action. */
+export interface FieldDateHiddenInput {
+    name?: string;
+    value: string;
+}
+export interface Props extends InputWrapClassProps {
+    id: string;
+    label?: SnippetWithId | THC;
+    description?: SnippetWithId | THC;
+    labelAfter?: SnippetWithId | THC;
+    below?: SnippetWithId | THC;
+    class?: string;
+    style?: string;
+    renderSize?: "sm" | "md" | "lg" | string;
+    required?: boolean;
+    disabled?: boolean;
+    tabindex?: number;
+    labelLeft?: boolean;
+    labelLeftWidth?: "normal" | "wide";
+    labelLeftBreakpoint?: number;
+    /** Formatted value shown in the trigger (`""` = empty → placeholder) */
+    display: string;
+    placeholder: string;
+    /** Show the trailing × while there is a value */
+    clearable: boolean;
+    clearLabel: string;
+    /** Render the picker inline inside the field instead of trigger + dialog */
+    embedded: boolean;
+    inputs: FieldDateHiddenInput[];
+    validate?: boolean | Omit<ValidateOptions, "setValidationResult">;
+    dialogTitle: string;
+    closeLabel: string;
+    noScrollLock?: boolean;
+    /** Classes for the trigger button */
+    classInput?: string;
+    /** Classes for the dialog box */
+    classDialog?: string;
+    /** The first hidden input (bindable) */
+    input?: HTMLInputElement;
+    onOpen?: () => void;
+    onClose?: () => void;
+    onClear: () => void;
+    /** The picker */
+    children: Snippet;
+}
+import { type ValidationResult } from "../../../actions/validate.svelte.js";
+declare const FieldDateShell: import("svelte").Component<Props, {
+    validate: () => ValidationResult | undefined;
+    clearValidation: () => void;
+    getValidation: () => ValidationResult | undefined;
+    focus: () => void;
+    scrollIntoView: (opts?: ScrollIntoViewOptions) => void;
+    dispatchChange: () => void;
+    open: () => void;
+    close: () => void;
+    isDialogOpen: () => boolean;
+}, "input">;
+type FieldDateShell = ReturnType<typeof FieldDateShell>;
+export default FieldDateShell;

package/dist/components/Input/index.css

@@ -83,6 +83,12 @@
 	--stuic-field-options-optgroup-text: var(--stuic-color-muted-foreground);
 	/* FieldOptions `chips` display mode */
 	--stuic-field-options-chips-gap: 0.25rem;
+
+	/* FieldDate / FieldDateRange specific */
+	--stuic-field-date-icon-text: var(--stuic-color-muted-foreground);
+	--stuic-field-date-placeholder-text: var(--stuic-input-placeholder);
+	--stuic-field-date-embedded-padding: 0.5rem;
+	--stuic-field-date-dialog-padding: 1rem;
 }
 
 @layer components {
@@ -810,3 +816,116 @@
 		}
 	}
 }
+
+/* ============================================================================
+   FIELD DATE / FIELD DATE RANGE
+   The trigger is a <button> (so no iOS zoom guard needed); it takes the input
+   size tokens so the field lines up with its siblings.
+   ============================================================================ */
+
+@layer components {
+	.stuic-field-date-trigger {
+		display: flex;
+		flex: 1 1 0%;
+		min-width: 0;
+		width: 100%;
+		align-items: center;
+		gap: 0.5rem;
+		margin: 0;
+		border: 0;
+		background: transparent;
+		text-align: start;
+		font-family: var(--stuic-input-font-family);
+		color: var(--stuic-input-text);
+		letter-spacing: -0.025em;
+		border-radius: var(--stuic-input-radius, var(--stuic-radius));
+		cursor: pointer;
+	}
+
+	/* InputWrap already shows the ring via `.input-wrap:focus-within` */
+	.stuic-field-date-trigger:focus,
+	.stuic-field-date-trigger:focus-visible {
+		outline: none;
+		box-shadow: none;
+	}
+
+	.stuic-field-date-trigger:disabled {
+		cursor: not-allowed;
+	}
+
+	.stuic-field-date-trigger[data-size="sm"] {
+		padding: var(--stuic-input-padding-y-sm) var(--stuic-input-padding-x-sm);
+		font-size: var(--stuic-input-font-size-sm);
+		min-height: var(--stuic-input-min-height-sm);
+	}
+
+	.stuic-field-date-trigger[data-size="md"],
+	.stuic-field-date-trigger:not([data-size]) {
+		padding: var(--stuic-input-padding-y-md) var(--stuic-input-padding-x-md);
+		font-size: var(--stuic-input-font-size-md);
+		min-height: var(--stuic-input-min-height-md);
+	}
+
+	.stuic-field-date-trigger[data-size="lg"] {
+		padding: var(--stuic-input-padding-y-lg) var(--stuic-input-padding-x-lg);
+		font-size: var(--stuic-input-font-size-lg);
+		min-height: var(--stuic-input-min-height-lg);
+	}
+
+	.stuic-field-date-trigger-icon {
+		display: inline-flex;
+		flex-shrink: 0;
+		color: var(--stuic-field-date-icon-text);
+	}
+
+	.stuic-field-date-trigger-label {
+		flex: 1;
+		min-width: 0;
+		overflow: hidden;
+		text-overflow: ellipsis;
+		white-space: nowrap;
+	}
+
+	.stuic-field-date-trigger[data-empty] .stuic-field-date-trigger-label {
+		color: var(--stuic-field-date-placeholder-text);
+	}
+
+	/* `embedded`: the calendar lives inside the input card */
+	.stuic-field-date-embedded {
+		flex: 1 1 0%;
+		min-width: 0;
+		display: flex;
+		justify-content: center;
+		padding: var(--stuic-field-date-embedded-padding);
+		overflow-x: auto;
+	}
+
+	/* the picker dialog card (inside a transparent, click-through ModalDialog box) */
+	.stuic-field-date-dialog {
+		background: var(--stuic-modal-dialog-bg);
+		color: var(--stuic-modal-dialog-text);
+		border-radius: var(--stuic-field-date-dialog-radius, var(--stuic-radius-container));
+		box-shadow: var(--stuic-field-date-dialog-shadow, var(--stuic-shadow-dialog));
+		padding: var(--stuic-field-date-dialog-padding);
+		max-width: 100%;
+	}
+
+	.stuic-field-date-dialog-header {
+		display: flex;
+		align-items: center;
+		justify-content: space-between;
+		gap: 0.5rem;
+		margin-bottom: 0.5rem;
+	}
+
+	.stuic-field-date-dialog-title {
+		font-weight: var(--font-weight-semibold);
+	}
+
+	.stuic-field-date-dialog-body {
+		display: flex;
+		justify-content: center;
+		max-width: 100%;
+		overflow-x: auto;
+	}
+}

package/dist/components/Input/index.d.ts

@@ -21,3 +21,5 @@ export { default as FieldObject, type Props as FieldObjectProps, } from "./Field
 export { default as FieldPhoneNumber, type Props as FieldPhoneNumberProps, } from "./FieldPhoneNumber.svelte";
 export { default as FieldCountry, type Props as FieldCountryProps, } from "./FieldCountry.svelte";
 export { validatePhoneNumber } from "./phone-validation.js";
+export { default as FieldDate, type Props as FieldDateProps, type FieldDateCalendarProps, } from "./FieldDate.svelte";
+export { default as FieldDateRange, type Props as FieldDateRangeProps, type FieldDateRangeValue, } from "./FieldDateRange.svelte";

package/dist/components/Input/index.js

@@ -21,3 +21,5 @@ export { default as FieldObject, } from "./FieldObject.svelte";
 export { default as FieldPhoneNumber, } from "./FieldPhoneNumber.svelte";
 export { default as FieldCountry, } from "./FieldCountry.svelte";
 export { validatePhoneNumber } from "./phone-validation.js";
+export { default as FieldDate, } from "./FieldDate.svelte";
+export { default as FieldDateRange, } from "./FieldDateRange.svelte";

package/dist/components/ModalDialog/ModalDialog.fixture.svelte

@@ -1,5 +1,5 @@
 <script lang="ts">
-	// Conventions escape hatch (docs/component-testing/02-test-conventions.md):
+	// Conventions escape hatch (docs/testing-components.md):
 	// ModalDialog is imperative-only (open()/close() via a ref; no bindable
 	// `visible` prop), so a `.svelte.test.ts` file can't drive it directly. This
 	// fixture holds the `bind:this` ref and exposes an opener button that calls

package/dist/components/SlidingPanels/SlidingPanels.fixture.svelte

@@ -1,7 +1,7 @@
 <script lang="ts">
 	import SlidingPanels from "./SlidingPanels.svelte";
 
-	// Conventions escape hatch (docs/component-testing/02-test-conventions.md):
+	// Conventions escape hatch (docs/testing-components.md):
 	// SlidingPanels exposes the panel content via snippets that receive an
 	// imperative `show(panel)` fn. A `.svelte.test.ts` file can't host markup that
 	// wires snippet args to a button, so we compose the real component here and

package/dist/icons/index.d.ts

@@ -31,6 +31,7 @@ export { iconLucideTrendingDown as iconTrendingDown } from "@marianmeres/icons-f
 export { iconLucideTrendingUp as iconTrendingUp } from "@marianmeres/icons-fns/lucide/iconLucideTrendingUp.js";
 export { iconLucideZoomIn as iconZoomIn } from "@marianmeres/icons-fns/lucide/iconLucideZoomIn.js";
 export { iconLucideZoomOut as iconZoomOut } from "@marianmeres/icons-fns/lucide/iconLucideZoomOut.js";
+export { iconLucideCalendar as iconCalendar } from "@marianmeres/icons-fns/lucide/iconLucideCalendar.js";
 export { iconLucideCheck as iconCheck } from "@marianmeres/icons-fns/lucide/iconLucideCheck.js";
 export { iconLucideChevronDown as iconChevronDown } from "@marianmeres/icons-fns/lucide/iconLucideChevronDown.js";
 export { iconLucideChevronLeft as iconChevronLeft } from "@marianmeres/icons-fns/lucide/iconLucideChevronLeft.js";

package/dist/icons/index.js

@@ -36,6 +36,7 @@ export { iconLucideTrendingUp as iconTrendingUp } from "@marianmeres/icons-fns/l
 export { iconLucideZoomIn as iconZoomIn } from "@marianmeres/icons-fns/lucide/iconLucideZoomIn.js";
 export { iconLucideZoomOut as iconZoomOut } from "@marianmeres/icons-fns/lucide/iconLucideZoomOut.js";
 // UI Control Icons (Lucide)
+export { iconLucideCalendar as iconCalendar } from "@marianmeres/icons-fns/lucide/iconLucideCalendar.js";
 export { iconLucideCheck as iconCheck } from "@marianmeres/icons-fns/lucide/iconLucideCheck.js";
 export { iconLucideChevronDown as iconChevronDown } from "@marianmeres/icons-fns/lucide/iconLucideChevronDown.js";
 export { iconLucideChevronLeft as iconChevronLeft } from "@marianmeres/icons-fns/lucide/iconLucideChevronLeft.js";

package/dist/index.css

@@ -63,6 +63,7 @@ In practice:
 @import "./components/Breadcrumbs/index.css";
 @import "./components/Button/index.css";
 @import "./components/ButtonGroupRadio/index.css";
+@import "./components/Calendar/index.css";
 @import "./components/Collapsible/index.css";
 @import "./components/Cart/index.css";
 @import "./components/Card/index.css";

package/dist/index.d.ts

@@ -32,6 +32,7 @@ export * from "./components/Book/index.js";
 export * from "./components/Breadcrumbs/index.js";
 export * from "./components/Button/index.js";
 export * from "./components/ButtonGroupRadio/index.js";
+export * from "./components/Calendar/index.js";
 export * from "./components/Cart/index.js";
 export * from "./components/Card/index.js";
 export * from "./components/Carousel/index.js";

package/dist/index.js

@@ -33,6 +33,7 @@ export * from "./components/Book/index.js";
 export * from "./components/Breadcrumbs/index.js";
 export * from "./components/Button/index.js";
 export * from "./components/ButtonGroupRadio/index.js";
+export * from "./components/Calendar/index.js";
 export * from "./components/Cart/index.js";
 export * from "./components/Card/index.js";
 export * from "./components/Carousel/index.js";

package/docs/_archive/README.md

@@ -0,0 +1,10 @@
+# Archived docs
+
+Documents kept for provenance only. **Nothing here is current guidance** — do not follow it, and do
+not update it. If something here turns out to still be true and useful, promote it back into `docs/`
+rather than citing it from live code.
+
+| Archived                                     | Why                                                                                                                                                                                                                                                                           |
+| -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`component-testing/`](./component-testing/) | Planning set for introducing real-browser component tests (2026-06). The work is done and shipped; the roadmap, coverage tiers, CI plan and `PROGRESS.md` tracker are history. The one living piece was promoted to [`docs/testing-components.md`](../testing-components.md). |
+| [`upgrading.md`](./upgrading.md)             | One-time upgrade note for consumers moving off **v3.66.1**. The library is far past that; the deltas it lists are long since absorbed.                                                                                                                                        |

package/docs/{component-testing → _archive/component-testing}/00-overview-and-roadmap.md

@@ -7,6 +7,8 @@ vitest-browser-svelte docs. Planning artifact; no code was changed.
 
 # @marianmeres/stuic — Component Testing: Overview & Roadmap
 
+> **ARCHIVED — historical, not current guidance.** See [`docs/_archive/README.md`](../README.md) for why.
+
 > **Verdict:** the proposed stack — Vitest Browser Mode + `vitest-browser-svelte` + Playwright/Chromium
 > — is the right default for _this_ library, where the value being shipped is precisely the DOM/layout/
 > focus/positioning behavior that the current node/server-build test setup **cannot exercise at all**.
@@ -24,13 +26,13 @@ vitest-browser-svelte docs. Planning artifact; no code was changed.
 > node with the very server-build error this effort exists to escape.
 >
 > Read order: this file → [`01-framework-setup`](./01-framework-setup.md) for the exact config →
-> [`02-test-conventions`](./02-test-conventions.md) for how to write a test → then work
+> [`02-test-conventions`](../../testing-components.md) for how to write a test → then work
 > [`PROGRESS.md`](./PROGRESS.md) top-down. [`03`](./03-component-coverage-roadmap.md) ranks all 74
 > components; [`04`](./04-hard-cases-and-e2e.md) handles the hard 30; [`05`](./05-ci.md) is CI.
 
 ## A note on `docs/testing.md` (this is a partial reversal — by design)
 
-[`docs/testing.md`](../testing.md) records a deliberate decision **not** to test component rendering
+[`docs/testing.md`](../../testing.md) records a deliberate decision **not** to test component rendering
 ("50+ components × prop combos = slow suite, tiny yield; rendering is gated by svelte-check + publint +
 build"). That reasoning holds for _"does it render"_ and we keep it. What changes: browser mode lets
 us test _"does it **behave**"_ — events, two-way binding, aria/disabled/active state, focus traps,
@@ -45,7 +47,7 @@ explicit sprint task so the docs don't contradict each other.
 | 1    | Upgrade vitest 3→4, verify 9 suites green                           | [01](./01-framework-setup.md)            | high  | S      | med  | Gating prerequisite; nothing installs without it             |
 | 2    | Add `projects` split (node `server` + browser `client`) + Chromium  | [01](./01-framework-setup.md)            | high  | S      | med  | The harness; routes by `*.svelte.test.ts` filename           |
 | 3    | Separator smoke test — prove client build + `$effect` actually run  | [01](./01-framework-setup.md)            | high  | S      | med  | Disproves/confirms the documented server-build blocker       |
-| 4    | Reconcile `docs/testing.md` (behavior ✅, rendering still ❌)       | [02](./02-test-conventions.md)           | med   | S      | low  | Keep docs internally consistent before scaling               |
+| 4    | Reconcile `docs/testing.md` (behavior ✅, rendering still ❌)       | [02](../../testing-components.md)        | med   | S      | low  | Keep docs internally consistent before scaling               |
 | 5    | Button — flagship; sets every assertion pattern                     | [03](./03-component-coverage-roadmap.md) | high  | S      | low  | Most-used primitive; template for the rest                   |
 | 6    | Pill, Switch — events + binding patterns                            | [03](./03-component-coverage-roadmap.md) | high  | S      | low  | Cover dismiss/toggle/bind once, reuse everywhere             |
 | 7    | Spinner, Skeleton, DismissibleMessage, Avatar, Progress             | [03](./03-component-coverage-roadmap.md) | high  | S      | low  | Deterministic, high-traffic; quick wins                      |
@@ -68,7 +70,7 @@ Branch: `feat/component-testing`. One commit per task.
 chromium`, fix the test scripts, and land the Separator smoke test. Unblocks all component tests
    and proves the server-build blocker is gone. Detail in [01](./01-framework-setup.md).
 3. **Reconcile `docs/testing.md` (#4)** — small doc edit so the philosophy matches reality.
-4. **Button (#5)** — establishes the assertion vocabulary ([02](./02-test-conventions.md)) every later
+4. **Button (#5)** — establishes the assertion vocabulary ([02](../../testing-components.md)) every later
    test reuses. Highest-leverage single component.
 5. **Pill → Switch → Spinner → Skeleton → DismissibleMessage → Avatar → Progress (#6, #7)** — the easy
    tier, one commit each; fast, deterministic, high-traffic coverage.
@@ -105,7 +107,7 @@ flowchart TD
 ## Completeness check
 
 - **Snippet-heavy components** (Button needs `children`): the `createRawSnippet` pattern is settled in
-  [02](./02-test-conventions.md); first real exercise is Button — watch for friction and codify a shared
+  [02](../../testing-components.md); first real exercise is Button — watch for friction and codify a shared
   helper home then.
 - **SvelteKit-plugin-in-browser-mode** is the top unknown; the Separator smoke test (task 2) is the
   designated early canary, with a documented fallback (plain `svelte()` plugin for the client project).
@@ -114,6 +116,6 @@ flowchart TD
 - Not yet scoped: a dedicated `playwright.config.ts` for the standalone E2E layer — intentionally
   deferred to its own future initiative ([04](./04-hard-cases-and-e2e.md)).
 
-Source documents: [`01-framework-setup`](./01-framework-setup.md), [`02-test-conventions`](./02-test-conventions.md),
+Source documents: [`01-framework-setup`](./01-framework-setup.md), [`02-test-conventions`](../../testing-components.md),
 [`03-component-coverage-roadmap`](./03-component-coverage-roadmap.md), [`04-hard-cases-and-e2e`](./04-hard-cases-and-e2e.md),
 [`05-ci`](./05-ci.md).