@marianmeres/stuic 3.86.0 → 3.88.0

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

@@ -0,0 +1,143 @@
+import type { Snippet } from "svelte";
+import type { DropdownMenuItem, DropdownMenuPosition } from "../DropdownMenu/DropdownMenu.svelte";
+import type { Props as AvatarProps } from "../Avatar/Avatar.svelte";
+/**
+ * Identity passed by the consumer. When `null` / `undefined`, the menu
+ * renders in unauthenticated mode. When provided, the menu renders the
+ * header tile (avatar + email) and the authenticated item set.
+ */
+export interface UserAvatarMenuIdentity {
+    /** Used for initials + auto-color hashing. Required when `identity` is set. */
+    email: string;
+    /** Optional display name (preferred over email in the header tile if present). */
+    name?: string;
+    /** Optional photo URL (forwarded to Avatar `src`). */
+    src?: string;
+    /** Optional role list — rendered under the email if `showRoles` is enabled. */
+    roles?: string[];
+}
+/**
+ * Standard built-in actions. Consumers wire these by passing handlers;
+ * omitting a handler hides the corresponding item.
+ *
+ * The component never navigates, logs out, or toggles theme on its own —
+ * it only invokes callbacks. The only built-in side effect is
+ * `ColorScheme.toggle()` inside the color-scheme item (see `colorScheme`).
+ */
+export interface UserAvatarMenuActions {
+    /** "View profile" item. Hidden when not provided. (Auth state only.) */
+    onProfile?: () => void;
+    /** "Settings" item. Hidden when not provided. (Auth state only.) */
+    onSettings?: () => void;
+    /** "Logout" item. Hidden when not provided. (Auth state only.) */
+    onLogout?: () => void;
+    /**
+     * "Login or register" item — combined affordance, typically wired to
+     * open a `LoginOrRegisterFormModal`. Hidden when not provided.
+     * (Unauth state only.) Independent of `onLogin` / `onRegister`; pass
+     * any combination of the three.
+     */
+    onLoginOrRegister?: () => void;
+    /** "Login" item. Hidden when not provided. (Unauth state only.) */
+    onLogin?: () => void;
+    /** "Register" item. Hidden when not provided. (Unauth state only.) */
+    onRegister?: () => void;
+}
+/**
+ * Labels for built-in items. All optional — defaults are English strings.
+ * Consumers running i18n pass already-translated strings here.
+ */
+export interface UserAvatarMenuLabels {
+    viewProfile?: string;
+    settings?: string;
+    logout?: string;
+    loginOrRegister?: string;
+    login?: string;
+    register?: string;
+    lightMode?: string;
+    darkMode?: string;
+    /** Trigger aria-label when authenticated. Default: "User menu". */
+    triggerAuthed?: string;
+    /** Trigger aria-label when unauthenticated. Default: "Sign in". */
+    triggerAnon?: string;
+}
+/**
+ * Color-scheme item config. Defaults to enabled.
+ * Pass `false` to disable; pass an object to customize.
+ */
+export type UserAvatarMenuColorScheme = boolean | {
+    enabled?: boolean;
+    /** Override the default `ColorScheme.toggle()` behavior. */
+    onToggle?: () => void;
+    /** Read current "is dark" state. Defaults to `ColorScheme.getValue() === "dark"`. */
+    isDark?: () => boolean;
+};
+export interface Props {
+    /** Current user. `null` / `undefined` → unauthenticated mode. */
+    identity?: UserAvatarMenuIdentity | null;
+    /** Action handlers (see `UserAvatarMenuActions`). */
+    actions?: UserAvatarMenuActions;
+    /** Translated / customized labels. */
+    labels?: UserAvatarMenuLabels;
+    /** Color-scheme toggle config. Default: enabled. */
+    colorScheme?: UserAvatarMenuColorScheme;
+    /** Render the identity header tile (avatar + email) in the dropdown. Default: `true`. */
+    showHeaderTile?: boolean;
+    /** Render roles under the email in the header tile. Default: `false`. */
+    showRoles?: boolean;
+    /**
+     * Extra items appended to the standard set (after Logout / Register).
+     * Use for app-specific actions ("Switch project", "Billing", etc.).
+     */
+    extraItems?: DropdownMenuItem[];
+    /**
+     * Full override. When provided, the standard item set is IGNORED and the
+     * component renders exactly these items. `identity` is still consulted for
+     * the trigger; everything else (`actions`, `labels`, `colorScheme`,
+     * `showHeaderTile`, `showRoles`) is not.
+     */
+    items?: DropdownMenuItem[];
+    /** Forwarded to the default `Avatar` trigger and header-tile avatar. */
+    avatar?: Partial<Omit<AvatarProps, "onclick" | "initials" | "src" | "el">>;
+    /** Forwarded to `DropdownMenu`. */
+    position?: DropdownMenuPosition;
+    offset?: string;
+    maxHeight?: string;
+    closeOnSelect?: boolean;
+    classDropdown?: string;
+    classTrigger?: string;
+    /** Bindable open state (forwarded to `DropdownMenu`). */
+    isOpen?: boolean;
+    /**
+     * Optional custom trigger snippet. Receives the same args as
+     * `DropdownMenu`'s `trigger` snippet — `isOpen`, `toggle`, `triggerProps`.
+     */
+    trigger?: Snippet<[
+        {
+            isOpen: boolean;
+            toggle: () => void;
+            triggerProps: {
+                id: string;
+                "aria-haspopup": "menu";
+                "aria-expanded": boolean;
+                "aria-controls": string;
+            };
+        }
+    ]>;
+    /**
+     * Optional custom header-tile snippet. Replaces the default
+     * avatar + email tile rendered at the top of the menu.
+     */
+    headerTile?: Snippet<[{
+        identity: UserAvatarMenuIdentity;
+    }]>;
+    /** Skip default styling. */
+    unstyled?: boolean;
+    /** Additional CSS classes on the wrapper. */
+    class?: string;
+    /** Bindable wrapper element. */
+    el?: HTMLDivElement;
+}
+declare const UserAvatarMenu: import("svelte").Component<Props, {}, "el" | "isOpen">;
+type UserAvatarMenu = ReturnType<typeof UserAvatarMenu>;
+export default UserAvatarMenu;

package/dist/components/UserAvatarMenu/index.css

@@ -0,0 +1,95 @@
+.stuic-user-avatar-menu {
+	display: inline-flex;
+}
+
+/* Fixed dropdown width so every instance opens at the same size, regardless
+ * of content length. Override the var, or pass `classDropdown` (Tailwind
+ * class wins via tw-merge). Long emails/names/roles truncate against this
+ * bounded width. */
+.stuic-user-avatar-menu-dropdown {
+	width: var(--stuic-user-avatar-menu-dropdown-width, 16rem);
+}
+
+.stuic-user-avatar-menu-trigger {
+	display: inline-flex;
+	align-items: center;
+	justify-content: center;
+	background: transparent;
+	border: 0;
+	padding: 0;
+	margin: 0;
+	cursor: pointer;
+	border-radius: var(
+		--stuic-user-avatar-menu-trigger-radius,
+		var(--stuic-radius, var(--radius-md))
+	);
+	transition: opacity
+		var(--stuic-user-avatar-menu-transition, var(--stuic-transition, 150ms)) ease;
+}
+
+.stuic-user-avatar-menu-trigger:hover {
+	opacity: var(--stuic-user-avatar-menu-trigger-opacity-hover, 0.85);
+}
+
+.stuic-user-avatar-menu-trigger:focus-visible {
+	outline: 2px solid
+		var(
+			--stuic-user-avatar-menu-trigger-outline-color,
+			var(--stuic-color-primary, currentColor)
+		);
+	outline-offset: 2px;
+}
+
+.stuic-user-avatar-menu-header {
+	display: flex;
+	flex-direction: column;
+	align-items: center;
+	gap: var(--stuic-user-avatar-menu-header-gap, 0.5rem);
+	padding: var(--stuic-user-avatar-menu-header-padding, 0.75rem 0.5rem);
+	margin-bottom: var(--stuic-user-avatar-menu-header-margin-bottom, 0.25rem);
+	background: var(
+		--stuic-user-avatar-menu-header-bg,
+		var(--stuic-color-muted, transparent)
+	);
+	color: var(
+		--stuic-user-avatar-menu-header-color,
+		var(--stuic-color-muted-foreground, inherit)
+	);
+	border-radius: var(
+		--stuic-user-avatar-menu-header-radius,
+		var(--stuic-radius, var(--radius-md))
+	);
+	/* fill the dropdown's content width so children can truncate against a
+	 * known boundary (instead of growing to their intrinsic width) */
+	width: 100%;
+	min-width: 0;
+	overflow: hidden;
+}
+
+/* Direct text children of the header tile must each get the full row width
+ * so `text-overflow: ellipsis` has something to clip against (under
+ * align-items: center, children otherwise shrink to their intrinsic width). */
+.stuic-user-avatar-menu-header-email,
+.stuic-user-avatar-menu-header-roles {
+	display: block;
+	width: 100%;
+	min-width: 0;
+	text-align: center;
+	overflow: hidden;
+	text-overflow: ellipsis;
+	white-space: nowrap;
+}
+
+.stuic-user-avatar-menu-header-email {
+	font-size: var(--stuic-user-avatar-menu-header-email-font-size, inherit);
+	color: var(--stuic-user-avatar-menu-header-email-color, inherit);
+}
+
+.stuic-user-avatar-menu-header-roles {
+	font-size: var(--stuic-user-avatar-menu-header-roles-font-size, 0.75rem);
+	color: var(
+		--stuic-user-avatar-menu-header-roles-color,
+		var(--stuic-color-muted-foreground, currentColor)
+	);
+	opacity: var(--stuic-user-avatar-menu-header-roles-opacity, 0.7);
+}

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

@@ -0,0 +1 @@
+export { default as UserAvatarMenu, type Props as UserAvatarMenuProps, type UserAvatarMenuIdentity, type UserAvatarMenuActions, type UserAvatarMenuLabels, type UserAvatarMenuColorScheme, } from "./UserAvatarMenu.svelte";

package/dist/components/UserAvatarMenu/index.js

@@ -0,0 +1 @@
+export { default as UserAvatarMenu, } from "./UserAvatarMenu.svelte";

package/dist/icons/index.d.ts

@@ -40,11 +40,14 @@ export { iconLucideGripHorizontal as iconGripHorizontal } from "@marianmeres/ico
 export { iconLucideGripVertical as iconGripVertical } from "@marianmeres/icons-fns/lucide/iconLucideGripVertical.js";
 export { iconLucideLanguages as iconLanguages } from "@marianmeres/icons-fns/lucide/iconLucideLanguages.js";
 export { iconLucideList as iconList } from "@marianmeres/icons-fns/lucide/iconLucideList.js";
+export { iconLucideLogOut as iconLogOut } from "@marianmeres/icons-fns/lucide/iconLucideLogOut.js";
 export { iconLucideMenu as iconMenu } from "@marianmeres/icons-fns/lucide/iconLucideMenu.js";
+export { iconLucideMoon as iconMoon } from "@marianmeres/icons-fns/lucide/iconLucideMoon.js";
 export { iconLucideSearch as iconSearch } from "@marianmeres/icons-fns/lucide/iconLucideSearch.js";
 export { iconLucideSlidersHorizontal as iconSlidersHorizontal } from "@marianmeres/icons-fns/lucide/iconLucideSlidersHorizontal.js";
 export { iconLucideSettings as iconSettings } from "@marianmeres/icons-fns/lucide/iconLucideSettings.js";
 export { iconLucideSquare as iconSquare } from "@marianmeres/icons-fns/lucide/iconLucideSquare.js";
+export { iconLucideSun as iconSun } from "@marianmeres/icons-fns/lucide/iconLucideSun.js";
 export { iconLucideUser as iconUser } from "@marianmeres/icons-fns/lucide/iconLucideUser.js";
 export { iconLucideX as iconX } from "@marianmeres/icons-fns/lucide/iconLucideX.js";
 export { iconLucidePencil as iconPencil } from "@marianmeres/icons-fns/lucide/iconLucidePencil.js";

package/dist/icons/index.js

@@ -45,11 +45,14 @@ export { iconLucideGripHorizontal as iconGripHorizontal } from "@marianmeres/ico
 export { iconLucideGripVertical as iconGripVertical } from "@marianmeres/icons-fns/lucide/iconLucideGripVertical.js";
 export { iconLucideLanguages as iconLanguages } from "@marianmeres/icons-fns/lucide/iconLucideLanguages.js";
 export { iconLucideList as iconList } from "@marianmeres/icons-fns/lucide/iconLucideList.js";
+export { iconLucideLogOut as iconLogOut } from "@marianmeres/icons-fns/lucide/iconLucideLogOut.js";
 export { iconLucideMenu as iconMenu } from "@marianmeres/icons-fns/lucide/iconLucideMenu.js";
+export { iconLucideMoon as iconMoon } from "@marianmeres/icons-fns/lucide/iconLucideMoon.js";
 export { iconLucideSearch as iconSearch } from "@marianmeres/icons-fns/lucide/iconLucideSearch.js";
 export { iconLucideSlidersHorizontal as iconSlidersHorizontal } from "@marianmeres/icons-fns/lucide/iconLucideSlidersHorizontal.js";
 export { iconLucideSettings as iconSettings } from "@marianmeres/icons-fns/lucide/iconLucideSettings.js";
 export { iconLucideSquare as iconSquare } from "@marianmeres/icons-fns/lucide/iconLucideSquare.js";
+export { iconLucideSun as iconSun } from "@marianmeres/icons-fns/lucide/iconLucideSun.js";
 export { iconLucideUser as iconUser } from "@marianmeres/icons-fns/lucide/iconLucideUser.js";
 export { iconLucideX as iconX } from "@marianmeres/icons-fns/lucide/iconLucideX.js";
 export { iconLucidePencil as iconPencil } from "@marianmeres/icons-fns/lucide/iconLucidePencil.js";

package/dist/index.css

@@ -95,6 +95,7 @@ In practice:
 @import "./components/ThemePreview/index.css";
 @import "./components/Tree/index.css";
 @import "./components/TwCheck/index.css";
+@import "./components/UserAvatarMenu/index.css";
 @import "./components/WithSidePanel/index.css";
 @import "./components/X/index.css";
 

package/dist/index.d.ts

@@ -74,6 +74,7 @@ export * from "./components/ThemePreview/index.js";
 export * from "./components/Tree/index.js";
 export * from "./components/TwCheck/index.js";
 export * from "./components/TypeaheadInput/index.js";
+export * from "./components/UserAvatarMenu/index.js";
 export * from "./components/WithSidePanel/index.js";
 export * from "./components/X/index.js";
 export * from "./utils/index.js";

package/dist/index.js

@@ -75,6 +75,7 @@ export * from "./components/ThemePreview/index.js";
 export * from "./components/Tree/index.js";
 export * from "./components/TwCheck/index.js";
 export * from "./components/TypeaheadInput/index.js";
+export * from "./components/UserAvatarMenu/index.js";
 export * from "./components/WithSidePanel/index.js";
 export * from "./components/X/index.js";
 // utils

package/dist/utils/index.d.ts

@@ -41,3 +41,4 @@ export * from "./tr.js";
 export * from "./tw-merge.js";
 export * from "./ucfirst.js";
 export * from "./unaccent.js";
+export * from "./validate-fields.js";

package/dist/utils/index.js

@@ -41,3 +41,4 @@ export * from "./tr.js";
 export * from "./tw-merge.js";
 export * from "./ucfirst.js";
 export * from "./unaccent.js";
+export * from "./validate-fields.js";

package/dist/utils/validate-fields.d.ts

@@ -0,0 +1,72 @@
+import type { ValidationResult } from "../actions/validate.svelte.js";
+/**
+ * Minimal shape any STUIC field component implements once it exposes the
+ * imperative validate API. Form-level helpers and consumer aggregators consume
+ * this — they don't care what specific field type they're dealing with.
+ *
+ * Every STUIC `Field*` component (FieldInput, FieldPhoneNumber, FieldCountry,
+ * FieldSelect, FieldCheckbox, FieldTextarea, FieldFile, FieldObject,
+ * FieldAssets, FieldInputLocalized, FieldKeyValues, FieldLikeButton,
+ * FieldRadios, FieldSwitch) satisfies this interface via `export function`.
+ */
+export interface ValidatableField {
+    /** Run the validator now. Renders the inline error if invalid. */
+    validate(): ValidationResult | undefined;
+    /** Reset the inline error and clear `el.setCustomValidity`. */
+    clearValidation?(): void;
+    /** Current validation state, or undefined if validator has never run. */
+    getValidation?(): ValidationResult | undefined;
+    /** Focus the visible interactive element. */
+    focus?(): void;
+    /** Scroll the field into view. Defaults to smooth + center. */
+    scrollIntoView?(opts?: ScrollIntoViewOptions): void;
+}
+type FieldArg = ValidatableField | undefined | null;
+/**
+ * Run `validate()` on every provided field. Returns `true` if all are valid.
+ *
+ * `undefined` / `null` entries are skipped so callers can spread conditional
+ * refs without filtering first.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   let nameField = $state();
+ *   let emailField = $state();
+ *
+ *   function handleSubmit() {
+ *     if (!validateAllFields([nameField, emailField])) {
+ *       scrollToFirstInvalidField([nameField, emailField]);
+ *       return;
+ *     }
+ *     // ...submit
+ *   }
+ * </script>
+ * ```
+ */
+export declare function validateAllFields(fields: FieldArg[]): boolean;
+/**
+ * Return the first field whose current validation state is invalid, or
+ * `undefined` if all are valid (or never validated).
+ *
+ * Reads cached state via `getValidation()` — call `validateAllFields()` first
+ * if you need fresh results.
+ */
+export declare function findFirstInvalidField(fields: FieldArg[]): ValidatableField | undefined;
+/**
+ * Scroll the first invalid field into view and (by default) focus it.
+ * Returns `true` if a field was scrolled, `false` if all were valid.
+ *
+ * Call **after** `validateAllFields()` — this reads cached validation state.
+ *
+ * @param fields - Field refs (in display order — first match wins)
+ * @param opts.focus - Whether to also call `focus()` on the field. Default true.
+ * @param opts.behavior - ScrollIntoView behavior. Default `"smooth"`.
+ * @param opts.block - ScrollIntoView block alignment. Default `"center"`.
+ */
+export declare function scrollToFirstInvalidField(fields: FieldArg[], opts?: {
+    focus?: boolean;
+    behavior?: ScrollBehavior;
+    block?: ScrollLogicalPosition;
+}): boolean;
+export {};

package/dist/utils/validate-fields.js

@@ -0,0 +1,73 @@
+/**
+ * Run `validate()` on every provided field. Returns `true` if all are valid.
+ *
+ * `undefined` / `null` entries are skipped so callers can spread conditional
+ * refs without filtering first.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   let nameField = $state();
+ *   let emailField = $state();
+ *
+ *   function handleSubmit() {
+ *     if (!validateAllFields([nameField, emailField])) {
+ *       scrollToFirstInvalidField([nameField, emailField]);
+ *       return;
+ *     }
+ *     // ...submit
+ *   }
+ * </script>
+ * ```
+ */
+export function validateAllFields(fields) {
+    let allValid = true;
+    for (const f of fields) {
+        if (!f)
+            continue;
+        const res = f.validate();
+        if (res && !res.valid)
+            allValid = false;
+    }
+    return allValid;
+}
+/**
+ * Return the first field whose current validation state is invalid, or
+ * `undefined` if all are valid (or never validated).
+ *
+ * Reads cached state via `getValidation()` — call `validateAllFields()` first
+ * if you need fresh results.
+ */
+export function findFirstInvalidField(fields) {
+    for (const f of fields) {
+        if (!f)
+            continue;
+        const v = f.getValidation?.();
+        if (v && !v.valid)
+            return f;
+    }
+    return undefined;
+}
+/**
+ * Scroll the first invalid field into view and (by default) focus it.
+ * Returns `true` if a field was scrolled, `false` if all were valid.
+ *
+ * Call **after** `validateAllFields()` — this reads cached validation state.
+ *
+ * @param fields - Field refs (in display order — first match wins)
+ * @param opts.focus - Whether to also call `focus()` on the field. Default true.
+ * @param opts.behavior - ScrollIntoView behavior. Default `"smooth"`.
+ * @param opts.block - ScrollIntoView block alignment. Default `"center"`.
+ */
+export function scrollToFirstInvalidField(fields, opts) {
+    const field = findFirstInvalidField(fields);
+    if (!field)
+        return false;
+    field.scrollIntoView?.({
+        behavior: opts?.behavior ?? "smooth",
+        block: opts?.block ?? "center",
+    });
+    if (opts?.focus !== false)
+        field.focus?.();
+    return true;
+}

package/docs/domains/actions.md

@@ -64,6 +64,80 @@ Actions using `$effect()` accept a function returning options:
 />
 ```
 
+### Imperative validate() trigger
+
+The `validate` action only runs `_doValidate` in response to user-driven DOM
+events (`change`, first `blur`). On a pristine, never-touched field the inline
+validation message never mounts — which silently breaks any flow that
+pre-populates errors via `customValidator` on a fresh form.
+
+Pass a `setDoValidate` callback to capture a reference to the action's internal
+validator function and trigger it imperatively (e.g., from a submit handler):
+
+```svelte
+<script>
+	let doValidate: (() => void) | undefined = $state();
+
+	function handleSubmit() {
+		// Force every "sleeping" field's validator to run, rendering inline
+		// errors even on fields the user never touched.
+		doValidate?.();
+		// ...check validationResult.valid here, or use validateAllFields().
+	}
+</script>
+
+<input
+	required
+	use:validate={() => ({
+		enabled: true,
+		setValidationResult: (res) => (validationResult = res),
+		setDoValidate: (fn) => (doValidate = fn),
+	})}
+/>
+```
+
+> **You generally don't write this by hand.** Every STUIC `Field*` component
+> already wires `setDoValidate` internally and exposes the result as
+> `export function validate()` on its component reference. See the
+> [Components domain doc](./components.md#imperative-validate-api) for the
+> per-field method list and the [validate-fields utility](./utils.md) for
+> `validateAllFields()` / `scrollToFirstInvalidField()` aggregators.
+
+### Pristine forms and external errors
+
+A common trap: setting an `errors` prop on a brand-new form and expecting the
+inline messages to render. They won't — the `validate` action's
+`customValidator` is only invoked on user events. Two fixes:
+
+1. **Wrap the form in `<form use:onSubmitValidityCheck>`** and listen for
+   `submit_valid` / `submit_invalid` (works for native submit flows).
+2. **Call the field component's imperative `validate()` from your submit
+   handler** (works for any flow — wizards, multi-step, custom CTAs).
+
+### Hidden inputs and `required`
+
+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
+`required` themselves inside their `customValidator`:
+
+```ts
+customValidator(val, ctx, el) {
+    if (required && (val == null || val === "")) {
+        return "This field requires attention. Please review and try again.";
+    }
+    return userValidator?.(val, ctx, el) || "";
+}
+```
+
+This means `<FieldCountry required />` and `<FieldPhoneNumber required />`
+correctly fail validation when empty — both through the imperative
+`validate()` path and via `use:onSubmitValidityCheck`. Without this wrap
+they'd silently accept empty values.
+
 ### File Dropzone
 
 ```svelte