@marianmeres/stuic 3.66.0 → 3.67.0

package/dist/components/Tree/README.md

@@ -0,0 +1,189 @@
+# Tree
+
+A generic hierarchical tree view with drag-and-drop reordering, keyboard navigation, expand/collapse state, optional `localStorage` persistence, and full ARIA `treeview` semantics.
+
+Backed by [`@marianmeres/tree`](https://www.npmjs.com/package/@marianmeres/tree) for the data model — pass `tree.toJSON().children` or any compatible `TreeNodeDTO[]`.
+
+## Usage
+
+### Basic
+
+```svelte
+<script lang="ts">
+	import { Tree } from "@marianmeres/stuic";
+
+	const items = [
+		{
+			id: "root",
+			value: "Projects",
+			children: [
+				{ id: "a", value: "Alpha", children: [] },
+				{ id: "b", value: "Beta", children: [] },
+			],
+		},
+	];
+</script>
+
+<Tree {items} activeId="a" onSelect={(item) => console.log(item.id)} />
+```
+
+### Drag & Drop
+
+```svelte
+<Tree
+	{items}
+	draggable
+	onMove={({ source, target, position }) => {
+		// Mutate your data to move `source` relative to `target`.
+		// Return `false` (or throw) to reject the move.
+		moveNode(source.id, target.id, position);
+	}}
+	isDraggable={(item) => !item.data?.locked}
+	isDropTarget={(item) => item.data?.acceptsChildren !== false}
+/>
+```
+
+`onMove` receives `{ source, target, position: "before" | "after" | "inside" }`. The component does **not** mutate items itself — you own the data. Return `false` or throw to reject.
+
+### Expansion Control
+
+Four priority tiers resolve a node's initial expansion state, highest wins:
+
+1. `localStorage` value (when `persistState={true}`)
+2. `expandedIds` prop (explicit initial set)
+3. Auto-expanded if any descendant is active
+4. `defaultExpanded` prop
+
+```svelte
+<Tree
+	{items}
+	defaultExpanded
+	persistState
+	storageKeyPrefix="my-app-tree"
+	onToggle={(item, expanded) => console.log(item.id, expanded)}
+/>
+```
+
+Collapsing a branch also collapses all of its descendants.
+
+### Custom Rendering
+
+```svelte
+<Tree {items}>
+	{#snippet renderIcon(item, depth, isExpanded)}
+		<MyIcon type={item.data.kind} />
+	{/snippet}
+	{#snippet renderItem(item, depth, isExpanded)}
+		<span class="font-medium">{item.value}</span>
+		{#if item.data?.count}
+			<span class="ml-auto text-xs opacity-60">{item.data.count}</span>
+		{/if}
+	{/snippet}
+</Tree>
+```
+
+## Props
+
+| Prop                | Type                                                 | Default           | Description                                                              |
+| ------------------- | ---------------------------------------------------- | ----------------- | ------------------------------------------------------------------------ |
+| `items`             | `TreeNodeDTO<T>[]`                                   | required          | Tree data (e.g. from `tree.toJSON().children`)                           |
+| `activeId`          | `string`                                             | -                 | ID of the currently active/selected node                                 |
+| `isActive`          | `(item) => boolean`                                  | -                 | Alternative to `activeId` for custom active detection                    |
+| `onSelect`          | `(item) => void`                                     | -                 | Called when a node is selected (click or Enter/Space)                    |
+| `onToggle`          | `(item, expanded) => void`                           | -                 | Called when a branch is expanded/collapsed                               |
+| `sort`              | `(a, b) => number`                                   | -                 | Per-level sort comparator                                                |
+| `defaultExpanded`   | `boolean`                                            | `false`           | Default expansion state for branches                                     |
+| `expandedIds`       | `Set<string>`                                        | -                 | Initially-expanded branch IDs                                            |
+| `persistState`      | `boolean`                                            | `false`           | Persist expand/collapse to `localStorage`                                |
+| `storageKeyPrefix`  | `string`                                             | `"stuic-tree"`    | Prefix used for `localStorage` keys                                      |
+| `draggable`         | `boolean`                                            | `false`           | Enable drag-and-drop reordering                                          |
+| `isDraggable`       | `(item) => boolean`                                  | -                 | Return `false` to block dragging a specific node                         |
+| `isDropTarget`      | `(item) => boolean`                                  | -                 | Return `false` to block dropping onto a specific node                    |
+| `onMove`            | `(event) => void \| false \| Promise<void \| false>` | -                 | Called when a valid drop happens; return `false` to reject               |
+| `onError`           | `(err) => void`                                      | -                 | Called when `onMove` throws                                              |
+| `dragExpandDelay`   | `number`                                             | `800`             | ms before auto-expanding a collapsed branch hovered during drag          |
+| `t`                 | `TranslateFn`                                        | built-in          | Optional translation function (used for drag-drop a11y announcements)    |
+| `getNodeLabel`      | `(item) => string`                                   | `String(v.value)` | String used in a11y announcements when a node is moved                   |
+| `renderItem`        | `Snippet<[item, depth, isExpanded]>`                 | -                 | Custom node label renderer                                               |
+| `renderIcon`        | `Snippet<[item, depth, isExpanded]>`                 | -                 | Custom node icon renderer                                                |
+| `unstyled`          | `boolean`                                            | `false`           | Skip default styling                                                     |
+| `class`             | `string`                                             | -                 | Classes for wrapper                                                      |
+| `classItem`         | `string`                                             | -                 | Classes for each item button                                             |
+| `classItemActive`   | `string`                                             | -                 | Extra classes when an item is active                                     |
+| `classIcon`         | `string`                                             | -                 | Classes for the icon wrapper                                             |
+| `classLabel`        | `string`                                             | -                 | Classes for the label wrapper                                            |
+| `classChevron`      | `string`                                             | -                 | Classes for the expand/collapse chevron                                  |
+| `classChildren`     | `string`                                             | -                 | Classes for the children container                                       |
+| `el`                | `HTMLElement`                                        | -                 | Bindable wrapper reference                                               |
+
+## Keyboard Navigation
+
+| Key                   | Action                                                                |
+| --------------------- | --------------------------------------------------------------------- |
+| `ArrowDown`           | Focus next visible node                                               |
+| `ArrowUp`             | Focus previous visible node                                           |
+| `ArrowRight`          | Expand a collapsed branch, or move to first child of an expanded one  |
+| `ArrowLeft`           | Collapse an expanded branch, or move to parent                        |
+| `Home`                | Focus first visible node                                              |
+| `End`                 | Focus last visible node                                               |
+| `Enter` / `Space`     | Toggle expansion (if branch) and fire `onSelect`                      |
+
+Focus follows the **roving tabindex** pattern: only the currently-focused node has `tabindex=0`, all others are `-1`.
+
+## Accessibility
+
+- Root has `role="tree"`; each node has `role="treeitem"`.
+- Branches have `aria-expanded`; active nodes have `aria-selected`; all nodes have `aria-level`.
+- Children wrappers have `role="group"`.
+- Successful `onMove` calls announce the change via a visually-hidden `aria-live="polite"` region. Translate via the `t` prop — keys: `move_before`, `move_after`, `move_inside` with `{source}` and `{target}` placeholders.
+
+### Drag-drop limitations
+
+HTML5 drag-and-drop is **mouse-only** and not keyboard accessible. Touch support is device-dependent and unreliable. If keyboard/touch reordering matters for your app, layer your own UI on top (e.g. a context menu with "Move up / Move down / Move into…" actions that call your move logic directly).
+
+## CSS Variables
+
+Override globally in `:root` or locally via `style=""`. Radius / border-width / transition use the standard STUIC fallback pattern and inherit from their shared structural tokens unless overridden.
+
+### Structure
+
+| Variable                           | Default                  | Description                       |
+| ---------------------------------- | ------------------------ | --------------------------------- |
+| `--stuic-tree-indent`              | `1.25rem`                | Indentation per depth level       |
+| `--stuic-tree-item-padding-x`      | `0.375rem`               | Item horizontal padding           |
+| `--stuic-tree-item-padding-y`      | `0.125rem`               | Item vertical padding             |
+| `--stuic-tree-item-height`         | `1.75rem`                | Item row height                   |
+| `--stuic-tree-item-font-size`      | `var(--text-sm)`         | Item font size                    |
+| `--stuic-tree-item-gap`            | `0.25rem`                | Gap between chevron, icon, label  |
+| `--stuic-tree-chevron-size`        | `14px`                   | Chevron icon size                 |
+| `--stuic-tree-chevron-opacity`     | `0.5`                    | Chevron opacity                   |
+| `--stuic-tree-icon-opacity`        | `0.7`                    | Icon opacity                      |
+| `--stuic-tree-item-radius`         | `var(--stuic-radius)`    | Item border radius                |
+| `--stuic-tree-transition`          | `var(--stuic-transition)`| Transition duration               |
+
+### Colors
+
+| Variable                             | Default                                | Description               |
+| ------------------------------------ | -------------------------------------- | ------------------------- |
+| `--stuic-tree-item-bg`               | `transparent`                          | Item background           |
+| `--stuic-tree-item-text`             | `inherit`                              | Item text color           |
+| `--stuic-tree-item-bg-hover`         | `rgb(0 0 0 / 0.06)`                    | Hover background          |
+| `--stuic-tree-item-bg-focus`         | `rgb(0 0 0 / 0.06)`                    | Keyboard-focus background |
+| `--stuic-tree-item-bg-active`        | `var(--stuic-color-primary)`           | Active/selected bg        |
+| `--stuic-tree-item-text-active`      | `var(--stuic-color-primary-foreground)`| Active/selected text      |
+
+### Drag & drop
+
+| Variable                                | Default                            | Description                     |
+| --------------------------------------- | ---------------------------------- | ------------------------------- |
+| `--stuic-tree-item-opacity-dragging`    | `0.4`                              | Opacity of the dragged item     |
+| `--stuic-tree-drop-indicator-color`     | `var(--stuic-color-primary)`       | Before/after drop line color    |
+| `--stuic-tree-drop-indicator-height`    | `2px`                              | Before/after drop line height   |
+| `--stuic-tree-item-bg-dragover`         | `rgb(0 0 0 / 0.04)`                | "Inside"-drop highlight         |
+
+## Limitations
+
+- **No multi-select / checkbox selection.** Single active node only.
+- **No lazy loading.** All nodes must be present in `items`.
+- **Expansion state is private.** Observe via `onToggle`; set initial via `expandedIds`. There is currently no way to read the full set of expanded IDs from outside.
+- **Drag-drop is mouse-only.** See the a11y section above.

package/dist/components/Tree/Tree.svelte

@@ -2,9 +2,31 @@
 	import type { HTMLAttributes } from "svelte/elements";
 	import type { TreeNodeDTO } from "@marianmeres/tree";
 	import type { Snippet } from "svelte";
+	import type { TranslateFn } from "../../types.js";
+	import { isPlainObject } from "../../utils/is-plain-object.js";
+	import { replaceMap } from "../../utils/replace-map.js";
 
 	export type TreeDropPosition = "before" | "after" | "inside";
 
+	function t_default(
+		k: string,
+		values: false | null | undefined | Record<string, string | number> = null,
+		fallback: string | boolean = "",
+		_i18nSpanWrap: boolean = true
+	) {
+		const m: Record<string, string> = {
+			move_before: "Moved {source} above {target}",
+			move_after: "Moved {source} below {target}",
+			move_inside: "Moved {source} into {target}",
+		};
+		let out = m[k] ?? fallback ?? k;
+		return isPlainObject(values)
+			? replaceMap(out, values as any, {
+					preSearchKeyTransform: (k) => `{${k}}`,
+				})
+			: out;
+	}
+
 	export interface TreeMoveEvent<T = unknown> {
 		/** The node being dragged */
 		source: TreeNodeDTO<T>;
@@ -72,6 +94,12 @@
 		/** Delay in ms before auto-expanding a collapsed branch on drag-over (default: 800) */
 		dragExpandDelay?: number;
 
+		/** Optional translate function (used for drag-drop screen reader announcements) */
+		t?: TranslateFn;
+
+		/** Derive a screen-reader label for a node. Defaults to `String(item.value)`. */
+		getNodeLabel?: (item: TreeNodeDTO<T>) => string;
+
 		/** Skip all default styling */
 		unstyled?: boolean;
 
@@ -128,6 +156,8 @@
 		onMove,
 		onError,
 		dragExpandDelay = 800,
+		t = t_default,
+		getNodeLabel = (item) => String(item.value),
 		unstyled = false,
 		class: classProp,
 		el = $bindable(),
@@ -310,8 +340,10 @@
 
 	function focusItem(id: string) {
 		focusedId = id;
-		// Focus the DOM element
-		const itemEl = el?.querySelector(`[data-tree-id="${id}"]`) as HTMLElement | null;
+		// Focus the DOM element. CSS.escape() protects against ids containing quotes/specials.
+		const itemEl = el?.querySelector(
+			`[data-tree-id="${CSS.escape(id)}"]`
+		) as HTMLElement | null;
 		itemEl?.focus();
 	}
 
@@ -409,6 +441,7 @@
 	let dropTargetId = $state<string | null>(null);
 	let dropPos = $state<TreeDropPosition | null>(null);
 	let dragExpandTimer: ReturnType<typeof setTimeout> | null = null;
+	let liveAnnouncement = $state("");
 
 	function findNodeById(nodeItems: TreeNode<T>[], id: string): TreeNode<T> | null {
 		for (const item of nodeItems) {
@@ -545,6 +578,14 @@
 			try {
 				const result = await onMove(event);
 				if (result === false) return;
+				liveAnnouncement = t(
+					`move_${event.position}`,
+					{
+						source: getNodeLabel(event.source),
+						target: getNodeLabel(event.target),
+					},
+					""
+				) as string;
 			} catch (err) {
 				onError?.(err);
 			}
@@ -658,4 +699,7 @@
 	{#each sortedItems(items) as item (item.id)}
 		{@render renderNode(item, 0)}
 	{/each}
+
+	<!-- Screen-reader-only live region for drag-drop move announcements -->
+	<div class="sr-only" aria-live="polite" aria-atomic="true">{liveAnnouncement}</div>
 </div>

package/dist/components/Tree/Tree.svelte.d.ts

@@ -1,6 +1,7 @@
 import type { HTMLAttributes } from "svelte/elements";
 import type { TreeNodeDTO } from "@marianmeres/tree";
 import type { Snippet } from "svelte";
+import type { TranslateFn } from "../../types.js";
 export type TreeDropPosition = "before" | "after" | "inside";
 export interface TreeMoveEvent<T = unknown> {
     /** The node being dragged */
@@ -47,6 +48,10 @@ export interface Props<T = unknown> extends Omit<HTMLAttributes<HTMLDivElement>,
     onError?: (error: unknown) => void;
     /** Delay in ms before auto-expanding a collapsed branch on drag-over (default: 800) */
     dragExpandDelay?: number;
+    /** Optional translate function (used for drag-drop screen reader announcements) */
+    t?: TranslateFn;
+    /** Derive a screen-reader label for a node. Defaults to `String(item.value)`. */
+    getNodeLabel?: (item: TreeNodeDTO<T>) => string;
     /** Skip all default styling */
     unstyled?: boolean;
     /** Classes for the wrapper element */

package/dist/utils/input-history.svelte.d.ts

@@ -14,6 +14,15 @@ export interface InputHistoryOptions {
 /**
  * A reactive input history manager with localStorage persistence and arrow key navigation.
  *
+ * @remarks
+ * Every constructed instance registers its storage key in a **process-wide static Set**
+ * (`InputHistory.#registeredKeys`). The Set grows as new instances are created and is
+ * only trimmed by `clearAllMatching(prefix)` / `clearAll()` — there is no per-instance
+ * deregistration. In practice this is fine: each entry is a short string and the cost
+ * is negligible. Typical lifecycle: create instances as users navigate, call
+ * `InputHistory.clearAllMatching("<app-prefix>")` on logout to wipe stored keys and
+ * clear the registry in one shot.
+ *
  * @example
  * ```ts
  * const history = new InputHistory({
@@ -34,6 +43,9 @@ export interface InputHistoryOptions {
  *
  * // Reset navigation when user starts typing
  * history.reset();
+ *
+ * // On logout (wipes localStorage + internal registry for matching keys):
+ * InputHistory.clearAllMatching("joy:");
  * ```
  */
 export declare class InputHistory {

package/dist/utils/input-history.svelte.js

@@ -2,6 +2,15 @@ import { localStorageState } from "./persistent-state.svelte.js";
 /**
  * A reactive input history manager with localStorage persistence and arrow key navigation.
  *
+ * @remarks
+ * Every constructed instance registers its storage key in a **process-wide static Set**
+ * (`InputHistory.#registeredKeys`). The Set grows as new instances are created and is
+ * only trimmed by `clearAllMatching(prefix)` / `clearAll()` — there is no per-instance
+ * deregistration. In practice this is fine: each entry is a short string and the cost
+ * is negligible. Typical lifecycle: create instances as users navigate, call
+ * `InputHistory.clearAllMatching("<app-prefix>")` on logout to wipe stored keys and
+ * clear the registry in one shot.
+ *
  * @example
  * ```ts
  * const history = new InputHistory({
@@ -22,6 +31,9 @@ import { localStorageState } from "./persistent-state.svelte.js";
  *
  * // Reset navigation when user starts typing
  * history.reset();
+ *
+ * // On logout (wipes localStorage + internal registry for matching keys):
+ * InputHistory.clearAllMatching("joy:");
  * ```
  */
 export class InputHistory {

package/dist/utils/observe-exists.svelte.d.ts

@@ -28,5 +28,6 @@ export declare function observeExists(selector: string, options?: Partial<{
 }>): {
     readonly current: boolean;
     disconnect(): void;
+    /** Re-run the selector check immediately and update `current`. */
     forceCheck(): void;
 };

package/dist/utils/observe-exists.svelte.js

@@ -42,13 +42,20 @@ export function observeExists(selector, options = {}) {
                     break;
                 }
             }
+            else if (mutation.type === "attributes") {
+                // an attribute changed on an existing element (e.g. class toggle) —
+                // may flip whether `selector` matches
+                shouldCheck = true;
+                break;
+            }
         }
         if (shouldCheck)
             current = check();
     });
-    // start observing now
+    // start observing now — include attributes so selectors like ".active" or
+    // "[data-busy]" react when classes/attrs toggle on existing elements
     clogDebug(`connecting...`);
-    observer.observe(rootElement, { childList: true, subtree: true });
+    observer.observe(rootElement, { childList: true, subtree: true, attributes: true });
     return {
         get current() {
             return current;
@@ -57,8 +64,9 @@ export function observeExists(selector, options = {}) {
             clogDebug(`disconnecting...`);
             observer.disconnect();
         },
+        /** Re-run the selector check immediately and update `current`. */
         forceCheck() {
-            check();
+            current = check();
         },
     };
 }

package/dist/utils/switch.svelte.d.ts

@@ -33,8 +33,20 @@ export declare class SwitchState<T> {
     #private;
     readonly key: string;
     readonly storageType: "memory" | "local" | "session";
+    /**
+     * One-shot callback fired the next time the switch transitions off (via `off()`,
+     * `toggle()` to off, or `reset()`). **Cleared after firing** — assign again before
+     * the next off-transition if you want it to fire repeatedly. Useful for "run X the
+     * next time this modal closes" patterns.
+     */
     onOff: ((data: T, self: SwitchState<T>) => void) | undefined | null;
     constructor(key: string, initial?: boolean | null, storageType?: "memory" | "local" | "session", initialData?: T | null);
+    /**
+     * @internal
+     * Low-level state setter. Prefer `on()`, `off()`, `toggle()`, or `reset()` — they
+     * cover every expected case. Kept public only because removing it would be a BC break;
+     * future code should treat this as private.
+     */
     __set(value: boolean | null, data?: T | null | undefined): void;
     on(data?: T | null | undefined): void;
     off(data?: T | null | undefined): void;

package/dist/utils/switch.svelte.js

@@ -43,6 +43,12 @@ export class SwitchState {
     // arbitrary data associated with the switch
     #data = $state(null);
     #storage;
+    /**
+     * One-shot callback fired the next time the switch transitions off (via `off()`,
+     * `toggle()` to off, or `reset()`). **Cleared after firing** — assign again before
+     * the next off-transition if you want it to fire repeatedly. Useful for "run X the
+     * next time this modal closes" patterns.
+     */
     onOff = null;
     constructor(key, initial = null, storageType = "memory", initialData = null) {
         this.key = key;
@@ -59,7 +65,12 @@ export class SwitchState {
             console.warn(`Unknown storageType "${this.storageType}"`);
         }
     }
-    // still public, but should not be used directly unless necessary for some reason
+    /**
+     * @internal
+     * Low-level state setter. Prefer `on()`, `off()`, `toggle()`, or `reset()` — they
+     * cover every expected case. Kept public only because removing it would be a BC break;
+     * future code should treat this as private.
+     */
     __set(value, data) {
         if (value !== null && typeof value !== "boolean")
             value = Boolean(value);

package/docs/architecture.md

@@ -112,7 +112,6 @@ Props → Component → Data Attributes → CSS Selectors
 | ------------------------------ | ----------------------------- |
 | `tailwind-merge`               | CSS class conflict resolution |
 | `runed`                        | Svelte 5 reactive utilities   |
-| `esm-env`                      | Environment detection         |
 | `@marianmeres/icons-fns`       | Icon SVG generation           |
 | `@marianmeres/item-collection` | Collection management         |
 | `@marianmeres/ticker`          | Animation timing              |

package/docs/testing.md

@@ -0,0 +1,72 @@
+# Testing
+
+STUIC has a **small, focused test suite** that's intentionally narrow. This doc explains what we test, what we don't, and how to add a new test.
+
+## Philosophy
+
+This is a component library. Most of its correctness guarantees come from:
+
+1. **TypeScript + `svelte-check`** — API contracts, prop types, snippet shapes.
+2. **`publint`** — package export hygiene.
+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.
+
+## What we test
+
+### ✅ High value
+
+- **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.
+
+### ⚠️ Maybe, if motivated by a regression
+
+- **Logic extracted from a `.svelte` into a sibling `_internal/*.ts`** — once extracted, same rules as utilities apply. (Examples that would be good candidates if we ever extract them: Tree's `calcDropPosition()` and `isDescendantOf()`, CronInput's `cronToHuman()` and `fieldsToExpression()`.)
+
+### ❌ 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.
+- **Coverage % targets**. They're the wrong goal for a component library.
+
+## Running tests
+
+```bash
+pnpm run test
+```
+
+Vitest is configured to run everything under `src/`. Tests live next to the code they test: `foo.ts` → `foo.test.ts`.
+
+## Writing a test
+
+Match the style of existing tests — plain `vitest` with `assert`, no test framework wrapper ceremony.
+
+```ts
+// src/lib/utils/my-thing.test.ts
+import { assert, test } from "vitest";
+import { myThing } from "./my-thing.js";
+
+test("myThing handles the empty case", () => {
+    assert.equal(myThing(""), null);
+});
+
+test("myThing handles the happy path", () => {
+    assert.equal(myThing("foo"), "FOO");
+});
+```
+
+For things that take a `TranslateFn`, inject an identity stub so the output is just the key:
+
+```ts
+import type { TranslateFn } from "$lib/types.js";
+const t: TranslateFn = (k) => k;
+```
+
+## When in doubt
+
+- **Logic in a `.ts` file with clear input/output?** Write a test.
+- **A regression just bit you in production?** Write a test for that specific case before fixing.
+- **Anything else?** Probably don't bother.