@marianmeres/stuic 3.87.0 → 3.89.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/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  |
@@ -901,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                                               |
@@ -916,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/package.json

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