@marianmeres/stuic 3.86.0 → 3.88.0

package/dist/components/UserAvatarMenu/README.md

@@ -0,0 +1,188 @@
+# UserAvatarMenu
+
+A thin, opinionated wrapper around [`Avatar`](../Avatar/) + [`DropdownMenu`](../DropdownMenu/) for the common "user avatar in the header that opens a small menu" pattern. Renders sensibly in both authenticated and unauthenticated states from the same trigger position.
+
+The component composes existing primitives and adds convention, not behavior. It owns **no** auth state, router, or i18n — consumers pass in the user (or `null`) and the handlers.
+
+## Usage
+
+### Minimal — logged in
+
+```svelte
+<UserAvatarMenu
+	identity={{ email: user.email }}
+	actions={{
+		onProfile: () => goto("/me"),
+		onLogout: () => goto("/logout"),
+	}}
+/>
+```
+
+### Minimal — logged out
+
+```svelte
+<UserAvatarMenu
+	actions={{
+		onLogin: () => openLoginModal(),
+		onRegister: () => openRegisterModal(),
+	}}
+/>
+```
+
+### Full (i18n + extras)
+
+```svelte
+<UserAvatarMenu
+	identity={{
+		email: user.email,
+		roles: user.roles,
+	}}
+	showRoles
+	actions={{
+		onProfile: () => goto("/account/profile"),
+		onLogout: () => goto("/logout"),
+	}}
+	labels={{
+		viewProfile: t.raw("dd_view_profile"),
+		logout: t.raw("dd_logout"),
+		lightMode: t.raw("dd_light_mode"),
+		darkMode: t.raw("dd_dark_mode"),
+	}}
+	avatar={{ class: "size-[60px]", padding: "10px" }}
+	classDropdown="min-w-56 rounded-lg border-primary border-3 border-solid"
+/>
+```
+
+## Props
+
+| Prop             | Type                                          | Default | Description                                                                                 |
+| ---------------- | --------------------------------------------- | ------- | ------------------------------------------------------------------------------------------- |
+| `identity`       | `UserAvatarMenuIdentity \| null`              | `null`  | Current user. `null` / `undefined` → unauthenticated mode.                                  |
+| `actions`        | `UserAvatarMenuActions`                       | `{}`    | Handlers: `onProfile`, `onSettings`, `onLogout`, `onLogin`, `onRegister`. Missing → hidden. |
+| `labels`         | `UserAvatarMenuLabels`                        | English | Translated strings for built-in items.                                                      |
+| `colorScheme`    | `boolean \| { enabled?; onToggle?; isDark? }` | `true`  | Built-in dark/light toggle. `false` to disable. Object form overrides toggle / read.        |
+| `showHeaderTile` | `boolean`                                     | `true`  | Render the avatar + email header tile when authenticated.                                   |
+| `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 the item list. Trigger + dropdown shell still render.                      |
+| `avatar`         | `Partial<AvatarProps>`                        | —       | Forwarded to the default trigger Avatar (and the header-tile Avatar).                       |
+| `position`       | `DropdownMenuPosition`                        | —       | Forwarded to `DropdownMenu`.                                                                |
+| `offset`         | `string`                                      | —       | Forwarded.                                                                                  |
+| `maxHeight`      | `string`                                      | —       | Forwarded.                                                                                  |
+| `closeOnSelect`  | `boolean`                                     | —       | Forwarded.                                                                                  |
+| `classDropdown`  | `string`                                      | —       | Forwarded.                                                                                  |
+| `classTrigger`   | `string`                                      | —       | Class merged onto the default trigger `<button>`.                                           |
+| `isOpen`         | `boolean`                                     | `false` | Bindable open state.                                                                        |
+| `trigger`        | `Snippet<[{ isOpen; toggle; triggerProps }]>` | —       | Custom trigger snippet; fully replaces the default.                                         |
+| `headerTile`     | `Snippet<[{ identity }]>`                     | —       | Custom header-tile snippet; replaces the default avatar+email tile inside the dropdown.     |
+| `unstyled`       | `boolean`                                     | `false` | Skip default styling.                                                                       |
+| `class`          | `string`                                      | —       | Wrapper classes.                                                                            |
+| `el`             | `HTMLDivElement`                              | —       | Bindable wrapper element.                                                                   |
+
+### `UserAvatarMenuIdentity`
+
+```ts
+interface UserAvatarMenuIdentity {
+	email: string;
+	name?: string;
+	src?: string; // photo URL
+	roles?: string[];
+}
+```
+
+### `UserAvatarMenuActions`
+
+All handlers are optional. **Omitting a handler hides the corresponding item.** The three unauth handlers (`onLoginOrRegister`, `onLogin`, `onRegister`) are independent — pass any combination.
+
+| Handler             | Item              | Visible in      |
+| ------------------- | ----------------- | --------------- |
+| `onProfile`         | View profile      | Authenticated   |
+| `onSettings`        | Settings          | Authenticated   |
+| `onLogout`          | Logout            | Authenticated   |
+| `onLoginOrRegister` | Login or register | Unauthenticated |
+| `onLogin`           | Login             | Unauthenticated |
+| `onRegister`        | Register          | Unauthenticated |
+
+### `UserAvatarMenuLabels`
+
+```ts
+interface UserAvatarMenuLabels {
+	viewProfile?: string; // "View profile"
+	settings?: string; // "Settings"
+	logout?: string; // "Logout"
+	loginOrRegister?: string; // "Login or register"
+	login?: string; // "Login"
+	register?: string; // "Register"
+	lightMode?: string; // "Light mode"
+	darkMode?: string; // "Dark mode"
+	triggerAuthed?: string; // "User menu"  (aria-label)
+	triggerAnon?: string; // "Sign in"    (aria-label)
+}
+```
+
+## Default item order
+
+Predictable so consumers can reason about position when adding `extraItems`.
+
+### Authenticated
+
+1. Header tile (when `showHeaderTile !== false`)
+2. View profile (when `actions.onProfile`)
+3. Settings (when `actions.onSettings`)
+4. Color scheme toggle (when `colorScheme !== false`) — sun/moon icon, label flips
+5. Divider (when there was at least one item above **and** `actions.onLogout`)
+6. Logout (when `actions.onLogout`) — with `iconLogOut`
+7. `extraItems` (appended)
+
+### Unauthenticated
+
+1. Login or register (when `actions.onLoginOrRegister`) — the typical case, wire to a `LoginOrRegisterFormModal`
+2. Login (when `actions.onLogin`)
+3. Register (when `actions.onRegister`)
+4. Color scheme toggle
+5. `extraItems`
+
+No header tile in unauth mode.
+
+### `items` override
+
+When `items` is passed, the entire default set is bypassed. The trigger + shell still render.
+
+## Opinionated decisions
+
+- **Color scheme is the one built-in side effect.** The component calls `ColorScheme.toggle()` and re-reads `ColorScheme.getValue()` on select. Label/icon flip without consumer involvement. Opt out with `colorScheme={false}`, or override via the object form: `colorScheme={{ onToggle, isDark }}`.
+- **English defaults.** Pass `labels` for i18n. The component never imports an i18n library; consumers pass already-translated strings.
+- **No auth ownership.** No state observation, no log-out call, no router. All side effects are consumer callbacks.
+- **No modal triggering.** "Login" doesn't open a `LoginOrRegisterFormModal` — that's your `onLogin` handler.
+- **Trigger is just `Avatar`.** No wrapper element by default. In unauth mode `Avatar` falls back to `iconUser`. Use the `trigger` snippet for full control.
+
+## CSS Tokens
+
+Prefix: `--stuic-user-avatar-menu-*`
+
+| Token                                             | Default                               |
+| ------------------------------------------------- | ------------------------------------- |
+| `--stuic-user-avatar-menu-dropdown-width`         | `16rem`                               |
+| `--stuic-user-avatar-menu-trigger-radius`         | `var(--stuic-radius)`                 |
+| `--stuic-user-avatar-menu-trigger-opacity-hover`  | `0.85`                                |
+| `--stuic-user-avatar-menu-trigger-outline-color`  | `var(--stuic-color-primary)`          |
+| `--stuic-user-avatar-menu-transition`             | `var(--stuic-transition)`             |
+| `--stuic-user-avatar-menu-header-gap`             | `0.5rem`                              |
+| `--stuic-user-avatar-menu-header-padding`         | `0.75rem 0.5rem`                      |
+| `--stuic-user-avatar-menu-header-margin-bottom`   | `0.25rem`                             |
+| `--stuic-user-avatar-menu-header-bg`              | `var(--stuic-color-muted)`            |
+| `--stuic-user-avatar-menu-header-color`           | `var(--stuic-color-muted-foreground)` |
+| `--stuic-user-avatar-menu-header-radius`          | `var(--stuic-radius)`                 |
+| `--stuic-user-avatar-menu-header-email-font-size` | `inherit`                             |
+| `--stuic-user-avatar-menu-header-email-color`     | `inherit`                             |
+| `--stuic-user-avatar-menu-header-roles-font-size` | `0.75rem`                             |
+| `--stuic-user-avatar-menu-header-roles-color`     | `var(--stuic-color-muted-foreground)` |
+| `--stuic-user-avatar-menu-header-roles-opacity`   | `0.7`                                 |
+
+The dropdown has a fixed `width` so every instance opens at the same size, regardless of content. Long emails/names truncate with `text-overflow: ellipsis` against that fixed width. Override `--stuic-user-avatar-menu-dropdown-width` (or pass `classDropdown="!w-72"` for one-off overrides).
+
+## See also
+
+- [`Avatar`](../Avatar/) — trigger / header-tile primitive
+- [`DropdownMenu`](../DropdownMenu/) — menu shell (item shapes, position values, search)
+- [`ColorScheme`](../ColorScheme/) — class used by the built-in toggle

package/dist/components/UserAvatarMenu/UserAvatarMenu.svelte

@@ -0,0 +1,416 @@
+<script lang="ts" module>
+	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;
+	}
+</script>
+
+<script lang="ts">
+	import { twMerge } from "../../utils/tw-merge.js";
+	import { iconLogOut, iconMoon, iconSun } from "../../icons/index.js";
+	import Avatar from "../Avatar/Avatar.svelte";
+	import DropdownMenu from "../DropdownMenu/DropdownMenu.svelte";
+	import { ColorScheme } from "../ColorScheme/index.js";
+
+	let {
+		identity = null,
+		actions = {},
+		labels = {},
+		colorScheme = true,
+		showHeaderTile = true,
+		showRoles = false,
+		extraItems,
+		items: itemsOverride,
+		avatar: avatarOverrides,
+		position,
+		offset,
+		maxHeight,
+		closeOnSelect,
+		classDropdown,
+		classTrigger,
+		isOpen = $bindable(false),
+		trigger,
+		headerTile,
+		unstyled = false,
+		class: classProp,
+		el = $bindable(),
+	}: Props = $props();
+
+	const isAuthed = $derived(!!identity);
+
+	// Color-scheme config normalization
+	const cs = $derived(
+		typeof colorScheme === "object" && colorScheme !== null ? colorScheme : {}
+	);
+	const csEnabled = $derived(
+		colorScheme === false ? false : cs.enabled !== false /* default true */
+	);
+
+	function readIsDark(): boolean {
+		return cs.isDark ? cs.isDark() : ColorScheme.getValue() === "dark";
+	}
+
+	let isDark = $state(false);
+	$effect(() => {
+		if (csEnabled) isDark = readIsDark();
+	});
+
+	function toggleColorScheme() {
+		if (cs.onToggle) {
+			cs.onToggle();
+		} else {
+			ColorScheme.toggle();
+		}
+		isDark = readIsDark();
+	}
+
+	// Default labels (English)
+	const L = $derived({
+		viewProfile: labels.viewProfile ?? "View profile",
+		settings: labels.settings ?? "Settings",
+		logout: labels.logout ?? "Logout",
+		loginOrRegister: labels.loginOrRegister ?? "Login or register",
+		login: labels.login ?? "Login",
+		register: labels.register ?? "Register",
+		lightMode: labels.lightMode ?? "Light mode",
+		darkMode: labels.darkMode ?? "Dark mode",
+		triggerAuthed: labels.triggerAuthed ?? "User menu",
+		triggerAnon: labels.triggerAnon ?? "Sign in",
+	});
+
+	function buildColorSchemeItem(): DropdownMenuItem {
+		return {
+			type: "action",
+			id: "color-scheme",
+			label: isDark ? L.lightMode : L.darkMode,
+			contentBefore: {
+				html: isDark ? iconSun({ size: 16 }) : iconMoon({ size: 16 }),
+			},
+			onSelect: toggleColorScheme,
+		};
+	}
+
+	const computedItems = $derived.by((): DropdownMenuItem[] => {
+		if (itemsOverride) return itemsOverride;
+
+		const out: DropdownMenuItem[] = [];
+
+		if (isAuthed) {
+			if (showHeaderTile) {
+				out.push({
+					type: "custom",
+					id: "header-tile",
+					content: { snippet: renderHeaderTile },
+				});
+			}
+
+			let renderedAny = false;
+			if (actions.onProfile) {
+				out.push({
+					type: "action",
+					id: "profile",
+					label: L.viewProfile,
+					onSelect: actions.onProfile,
+				});
+				renderedAny = true;
+			}
+			if (actions.onSettings) {
+				out.push({
+					type: "action",
+					id: "settings",
+					label: L.settings,
+					onSelect: actions.onSettings,
+				});
+				renderedAny = true;
+			}
+			if (csEnabled) {
+				out.push(buildColorSchemeItem());
+				renderedAny = true;
+			}
+
+			if (renderedAny && actions.onLogout) {
+				out.push({ type: "divider", id: "div-logout" });
+			}
+
+			if (actions.onLogout) {
+				out.push({
+					type: "action",
+					id: "logout",
+					label: L.logout,
+					contentBefore: { html: iconLogOut({ size: 16 }) },
+					onSelect: actions.onLogout,
+				});
+			}
+		} else {
+			if (actions.onLoginOrRegister) {
+				out.push({
+					type: "action",
+					id: "login-or-register",
+					label: L.loginOrRegister,
+					onSelect: actions.onLoginOrRegister,
+				});
+			}
+			if (actions.onLogin) {
+				out.push({
+					type: "action",
+					id: "login",
+					label: L.login,
+					onSelect: actions.onLogin,
+				});
+			}
+			if (actions.onRegister) {
+				out.push({
+					type: "action",
+					id: "register",
+					label: L.register,
+					onSelect: actions.onRegister,
+				});
+			}
+			if (csEnabled) out.push(buildColorSchemeItem());
+		}
+
+		if (extraItems?.length) out.push(...extraItems);
+		return out;
+	});
+
+	const wrapperClass = $derived(
+		twMerge(!unstyled && "stuic-user-avatar-menu", classProp)
+	);
+</script>
+
+{#snippet defaultHeaderTile()}
+	{#if identity}
+		<div class={!unstyled ? "stuic-user-avatar-menu-header" : undefined}>
+			<Avatar
+				initials={identity.email}
+				initialsLength={1}
+				autoColor
+				hashSource={identity.email}
+				src={identity.src}
+				onclick={actions.onProfile}
+				{...avatarOverrides}
+			/>
+			<div class={!unstyled ? "stuic-user-avatar-menu-header-email" : undefined}>
+				{identity.name ?? identity.email}
+			</div>
+			{#if showRoles && identity.roles?.length}
+				<div class={!unstyled ? "stuic-user-avatar-menu-header-roles" : undefined}>
+					{identity.roles.join(", ")}
+				</div>
+			{/if}
+		</div>
+	{/if}
+{/snippet}
+
+{#snippet renderHeaderTile(_args: Record<string, any>)}
+	{#if identity}
+		{#if headerTile}
+			{@render headerTile({ identity })}
+		{:else}
+			{@render defaultHeaderTile()}
+		{/if}
+	{/if}
+{/snippet}
+
+{#snippet defaultTrigger({
+	toggle,
+	triggerProps,
+}: {
+	isOpen: boolean;
+	toggle: () => void;
+	triggerProps: Record<string, any>;
+})}
+	<button
+		type="button"
+		onclick={toggle}
+		aria-label={isAuthed ? L.triggerAuthed : L.triggerAnon}
+		class={twMerge(!unstyled && "stuic-user-avatar-menu-trigger", classTrigger)}
+		{...triggerProps}
+	>
+		{#if isAuthed && identity}
+			<Avatar
+				initials={identity.email}
+				initialsLength={1}
+				autoColor
+				hashSource={identity.email}
+				src={identity.src}
+				{...avatarOverrides}
+			/>
+		{:else}
+			<Avatar {...avatarOverrides} />
+		{/if}
+	</button>
+{/snippet}
+
+<div bind:this={el} class={wrapperClass}>
+	<DropdownMenu
+		items={computedItems}
+		bind:isOpen
+		{position}
+		{offset}
+		{maxHeight}
+		{closeOnSelect}
+		classDropdown={twMerge(!unstyled && "stuic-user-avatar-menu-dropdown", classDropdown)}
+		{unstyled}
+		trigger={trigger ?? defaultTrigger}
+	/>
+</div>