@marianmeres/stuic 3.86.0 → 3.88.0

package/docs/domains/components.md

@@ -72,6 +72,7 @@
 | Component       | Purpose                                                             |
 | --------------- | ------------------------------------------------------------------- |
 | Avatar          | User avatars with fallback                                          |
+| UserAvatarMenu  | Avatar trigger + dropdown menu with header tile, color-scheme toggle, authed/unauthed states |
 | Pill            | Inline rounded badge/tag/chip (intent + variant + size, dismissible, dot, polymorphic span/a/button) |
 | KbdShortcut     | Keyboard shortcut hints                                             |
 | Carousel        | Image/content slider with snap, keyboard nav, wheel scroll, arrows  |
@@ -102,6 +103,137 @@
 
 ---
 
+## Imperative validate API
+
+Every `Field*` component that uses the `validate` action exposes a small
+imperative API on its component reference, accessed via `bind:this`. Form
+components (`LoginForm`, `RegisterForm`, `LoginOrRegisterForm`,
+`EmailVerifyForm`) compose those into form-level `validate()` /
+`scrollToFirstError()`.
+
+### Why
+
+The `validate` action only runs on user-driven DOM events (`change`, first
+`blur`). On a pristine, never-touched field the inline `validation-box` never
+mounts — which silently breaks any flow that pre-populates errors via
+`customValidator` on a fresh form. The imperative API lets a submit handler
+force every "sleeping" field's validator to run, rendering inline errors all
+at once — no synthetic `change` events, no DOM lookups, no id-format coupling.
+
+### The `validate` prop — defaults & opt-out
+
+All field components that use the `validate` action treat the prop with one
+consistent rule:
+
+| `validate` value          | Action                                                     |
+| ------------------------- | ---------------------------------------------------------- |
+| (omitted) / `undefined`   | **Enabled** with default options (the common case)         |
+| `true`                    | Enabled with default options (explicit; same as omitting)  |
+| `false`                   | **Disabled** — no validation, `validate()` becomes a no-op |
+| `{ customValidator, ... }`| Enabled, with `ValidateOptions` overrides applied          |
+
+So `<FieldInput required />` works as expected — required is enforced, and a
+failed `validate()` (imperative or event-driven) renders the inline error.
+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
+> 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
+> default to keep the rule uniform: "`required` means required."
+
+### Per-field methods
+
+Available on `FieldInput`, `FieldTextarea`, `FieldCheckbox`, `FieldSelect`,
+`FieldFile`, `FieldObject`, `FieldAssets`, `FieldInputLocalized`,
+`FieldKeyValues`, `FieldPhoneNumber`, `FieldCountry`, `FieldLikeButton`,
+`FieldRadios`, `FieldSwitch`, `FieldOptions`, and `Switch`:
+
+| Method                                        | Returns                          | Purpose                                                            |
+| --------------------------------------------- | -------------------------------- | ------------------------------------------------------------------ |
+| `validate()`                                  | `ValidationResult \| undefined`  | Run the validator now. Renders the inline message if invalid.       |
+| `clearValidation()`                           | `void`                           | Clear the inline message and `setCustomValidity`.                   |
+| `getValidation()`                             | `ValidationResult \| undefined`  | Read cached state (no re-run).                                      |
+| `focus()`                                     | `void`                           | Focus the visible interactive element.                              |
+| `scrollIntoView(opts?)`                       | `void`                           | Scroll the field into view. Defaults to `smooth` + `center`.        |
+
+```svelte
+<script>
+	let nameField = $state<FieldInput>();
+
+	function checkName() {
+		const result = nameField?.validate();
+		if (result && !result.valid) {
+			console.warn("Name invalid:", result.message);
+		}
+	}
+</script>
+
+<FieldInput bind:this={nameField} bind:value={name} label="Name" required />
+<Button onclick={checkName}>Check now</Button>
+```
+
+### Form-level methods
+
+`LoginForm`, `RegisterForm`, `LoginOrRegisterForm`, and `EmailVerifyForm` each
+expose:
+
+| Method                              | Returns   | Purpose                                                              |
+| ----------------------------------- | --------- | -------------------------------------------------------------------- |
+| `validate()`                        | `boolean` | Run every inner field's validator. `true` if all valid.              |
+| `scrollToFirstError(opts?)`         | `boolean` | Scroll the first invalid field into view + focus it. Call after `validate()`. |
+
+```svelte
+<script>
+	let loginForm = $state<LoginForm>();
+
+	async function handleCustomSubmit() {
+		if (!loginForm?.validate()) {
+			loginForm?.scrollToFirstError();
+			return;
+		}
+		await api.login(/* ... */);
+	}
+</script>
+
+<LoginForm bind:this={loginForm} onSubmit={handleCustomSubmit} />
+<Button onclick={handleCustomSubmit}>Submit from outside</Button>
+```
+
+### Pristine-form errors pattern
+
+The trap: an external `errors` prop wired into each field's `customValidator`
+won't render until the user touches the field. Pair the existing prop with
+an imperative `validate()` call from your submit handler:
+
+```svelte
+<FieldInput
+	bind:this={nameField}
+	bind:value={address.name}
+	required
+	validate={{
+		customValidator() {
+			return externalErrors.find((e) => e.field === "name")?.message || "";
+		},
+	}}
+/>
+
+<!-- in your submit handler -->
+<script>
+	function handleContinue() {
+		if (!validateAllFields([nameField, /* ... */])) return;
+		// ...submit
+	}
+</script>
+```
+
+For aggregation across many fields, see
+[validate-fields utilities](./utils.md#field-validation-aggregators).
+
+---
+
 ## LoginForm
 
 Standalone login form with optional modal variant. Supports social logins, forgot password, remember me, client+server validation, i18n, and notifications integration.
@@ -770,6 +902,63 @@ Prefix: `--stuic-tree-*`
 
 ---
 
+## UserAvatarMenu
+
+Thin opinionated wrapper around `Avatar` + `DropdownMenu` for the common "user avatar in the header opens a small menu" pattern. Renders in both authenticated (header tile, View profile, color-scheme toggle, Logout) and unauthenticated (Login, Register) states from the same trigger position. Color scheme is the one built-in side effect; everything else is consumer callbacks.
+
+### Exports
+
+| Export                       | Kind      | Description                                |
+| ---------------------------- | --------- | ------------------------------------------ |
+| `UserAvatarMenu`             | component | Main component                             |
+| `UserAvatarMenuProps`        | type      | Props type                                 |
+| `UserAvatarMenuIdentity`     | type      | `{ email, name?, src?, roles? }`           |
+| `UserAvatarMenuActions`      | type      | `{ onProfile?, onSettings?, onLogout?, onLoginOrRegister?, onLogin?, onRegister? }` |
+| `UserAvatarMenuLabels`       | type      | Label overrides (all optional, English defaults) |
+| `UserAvatarMenuColorScheme`  | type      | `boolean \| { enabled?, onToggle?, isDark? }` |
+
+### Key Props
+
+| Prop             | Type                                          | Default | Description                                                                            |
+| ---------------- | --------------------------------------------- | ------- | -------------------------------------------------------------------------------------- |
+| `identity`       | `UserAvatarMenuIdentity \| null`              | `null`  | Current user. `null` / `undefined` → unauthenticated mode.                             |
+| `actions`        | `UserAvatarMenuActions`                       | `{}`    | Handlers; missing → corresponding item hidden.                                         |
+| `labels`         | `UserAvatarMenuLabels`                        | English | Translated strings for built-in items.                                                 |
+| `colorScheme`    | `boolean \| { enabled?, onToggle?, isDark? }` | `true`  | Built-in dark/light toggle. `false` to disable.                                        |
+| `showHeaderTile` | `boolean`                                     | `true`  | Render avatar+email tile inside the dropdown (auth only).                              |
+| `showRoles`      | `boolean`                                     | `false` | Render `identity.roles` under the email in the header tile.                            |
+| `extraItems`     | `DropdownMenuItem[]`                          | —       | Appended to the standard item set.                                                     |
+| `items`          | `DropdownMenuItem[]`                          | —       | Full override of items (trigger + shell still render).                                 |
+| `avatar`         | `Partial<AvatarProps>`                        | —       | Forwarded to the default trigger Avatar (and header-tile Avatar).                      |
+| `position`       | `DropdownMenuPosition`                        | —       | Forwarded to `DropdownMenu`.                                                           |
+| `classDropdown`  | `string`                                      | —       | Forwarded.                                                                             |
+| `classTrigger`   | `string`                                      | —       | Class merged onto the default trigger `<button>`.                                      |
+| `trigger`        | `Snippet<[{ isOpen, toggle, triggerProps }]>` | —       | Custom trigger snippet (replaces default Avatar trigger).                              |
+| `headerTile`     | `Snippet<[{ identity }]>`                     | —       | Custom header-tile snippet (replaces default avatar+email tile).                       |
+| `isOpen`         | `boolean`                                     | `false` | Bindable open state.                                                                   |
+
+### Default item order
+
+**Authenticated:** header tile → View profile → Settings → Color scheme → Divider → Logout → `extraItems`. Each rendered only if its precondition (handler present, etc.) holds.
+
+**Unauthenticated:** Login or register → Login → Register → Color scheme → `extraItems`. Each rendered only if the corresponding handler is provided. The three are independent — pass any combination. The combined `onLoginOrRegister` (typically opening a `LoginOrRegisterFormModal`) is the most common variant. No header tile.
+
+### Opinionated decisions
+
+- Color scheme is the only built-in side effect (`ColorScheme.toggle()` + re-read on select). Opt out with `colorScheme={false}`.
+- English label defaults; consumers pass `labels` for i18n. No i18n library imported.
+- No auth state ownership, no router, no modal triggering — all consumer callbacks.
+
+### CSS Tokens
+
+Prefix: `--stuic-user-avatar-menu-*`
+
+`dropdown-width` (16rem), `trigger-radius`, `trigger-opacity-hover`, `trigger-outline-color`, `transition`, `header-gap`, `header-padding`, `header-margin-bottom`, `header-bg`, `header-color`, `header-radius`, `header-email-font-size`, `header-email-color`, `header-roles-font-size`, `header-roles-color`, `header-roles-opacity`
+
+The dropdown has a fixed `width` so every instance opens identically — short and long content alike. Email, name, and roles truncate with `text-overflow: ellipsis`. Header tile defaults: `--stuic-color-muted` bg + `--stuic-color-muted-foreground` text.
+
+---
+
 ## Key Files
 
 | File                          | Purpose                                               |
@@ -785,4 +974,5 @@ Prefix: `--stuic-tree-*`
 | src/lib/components/Checkout/  | E-commerce checkout flow (14 exported sub-components) |
 | src/lib/components/Card/      | Card with image/title/footer variants                 |
 | src/lib/components/Tree/      | Hierarchical tree with drag-and-drop                  |
+| src/lib/components/UserAvatarMenu/ | Avatar trigger + dropdown for user menu          |
 | src/lib/index.ts              | All component exports                                 |

package/docs/domains/utils.md

@@ -173,6 +173,43 @@ storage.get("user"); // { name: 'John' }
 | `generateCssTokens`  | Convert token schema to CSS  |
 | `toCssString`        | Format tokens as CSS string  |
 
+---
+
+## Field Validation Aggregators
+
+Helpers for orchestrating `validate()` across multiple `Field*` components.
+Pair with the per-field imperative API documented in the
+[Components domain](./components.md#imperative-validate-api).
+
+| Util                          | Purpose                                                      |
+| ----------------------------- | ------------------------------------------------------------ |
+| `validateAllFields`           | Run `validate()` on every provided field ref. Returns `true` if all valid. |
+| `findFirstInvalidField`       | Return the first ref whose cached `getValidation()` is invalid. |
+| `scrollToFirstInvalidField`   | Scroll the first invalid field into view + focus (call after `validateAllFields`). |
+| `ValidatableField` (interface)| Minimal shape every STUIC `Field*` satisfies — your own components can too. |
+
+```ts
+import {
+	scrollToFirstInvalidField,
+	validateAllFields,
+} from "@marianmeres/stuic";
+
+let nameField = $state<FieldInput>();
+let emailField = $state<FieldInput>();
+let countryField = $state<FieldCountry>();
+
+function handleContinue() {
+	const allValid = validateAllFields([nameField, emailField, countryField]);
+	if (!allValid) {
+		scrollToFirstInvalidField([nameField, emailField, countryField]);
+		return;
+	}
+	// ...submit
+}
+```
+
+`undefined` / `null` entries are skipped so callers can spread conditional refs
+without filtering first.
 
 ---
 
@@ -184,4 +221,5 @@ storage.get("user"); // { name: 'John' }
 | src/lib/utils/tw-merge.ts                | Critical for class merging                |
 | src/lib/utils/persistent-state.svelte.ts | Reactive storage pattern (runes-based)    |
 | src/lib/utils/storage-abstraction.ts     | Non-reactive storage (localStorage, etc.) |
+| src/lib/utils/validate-fields.ts         | Form-level validation aggregators         |
 | src/lib/utils/design-tokens.ts           | Re-exports from `@marianmeres/design-tokens` |

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@marianmeres/stuic",
-	"version": "3.86.0",
+	"version": "3.88.0",
 	"scripts": {
 		"dev": "vite dev",
 		"build": "vite build && pnpm run prepack",