portal-mojo 0.2.6 → 0.2.7

package/README.md

@@ -23,8 +23,8 @@ additional exports are required.
 |---|---|
 | `portal-mojo/client` | Typed django-mojo protocol layer: envelope unwrap at exactly one boundary (a failed save **rejects**), `start`/`size` paging, `'-field'` sort, Django lookups, the URL-synced `useTableParams` store (single source of truth for table state), TanStack Query hooks. Auth client: password / magic-link / passkey login, forgot/reset, cross-origin handoff (`?auth_code=` scrub-before-network), single-flight refresh + pre-request gate (synthetic-401 reject, `/api/token/refresh` recursion guard), `X-Mojo-UID` device header, `getAuthSnapshot`/`subscribeAuth` for React. Auth-challenged realtime transport: `RealtimeProvider`/`RealtimeClient`, refcounted topics, typed event projection, and a deterministic mock. Boot auth with `initAuth()`. The in-memory HTTP mock transport lives here too — it is the wire contract's executable spec and evolves in lockstep with the client (any seeded active user logs in with email + `"mojo"`). |
 | `portal-mojo/client/runtime` | Stable, narrow client boundary for first-party application runtime code. It omits eager mock-test controls; the mock transport itself loads on the first mock request. |
-| `portal-mojo/ui` | Mission-control UI: `ModelTable`, `FilterBar`/`FilterPills`, `SchemaForm`/`formModal`, `DetailView`, `RecordFeed`, `AttachmentQueue`/`UploadQueue`, `ImageEditor`/`imageEditorModal`, awaitable native-`<dialog>` `modal`, `toast`, `ThemeProvider`, `Guarded` (permission slot), `GroupSwitcher` (searchable tree selector), `RequiresGroup`, the sidebar engine (`registerMenus`/`setDefaultMenu` registry + `SidebarNav` — static or searchable accordion with a compact icon rail; global and group scopes are explicit), `Badge`/`MetricCard`/`Spark`, `fmt` formatter namespace. |
-| `portal-mojo/ui/shell` | Stable, narrow boundary for application-shell primitives: theme, guards, menus/sidebar, right panel, modal/toast hosts, password helpers, and formatters. |
+| `portal-mojo/ui` | Mission-control UI: `ModelTable`, `FilterBar`/`FilterPills`, `SchemaForm`/`formModal`, `DetailView`, `RecordFeed`, `AttachmentQueue`/`UploadQueue`, `ImageEditor`/`imageEditorModal`, awaitable native-`<dialog>` `modal`, `toast`, `ThemeProvider`, `UserMenu` (top-nav account menu), `Guarded` (permission slot), `GroupSwitcher` (searchable tree selector), `RequiresGroup`, the sidebar engine (`registerMenus`/`setDefaultMenu` registry + `SidebarNav` — static or searchable accordion with a compact icon rail; global and group scopes are explicit), `Badge`/`MetricCard`/`Spark`, `fmt` formatter namespace. |
+| `portal-mojo/ui/shell` | Stable, narrow boundary for application-shell primitives: theme, guards, menus/sidebar, right panel, account menu (`UserMenu`), modal/toast hosts, password helpers, and formatters. |
 | `portal-mojo/charts` | Dependency-free SVG charts: `SeriesChart` (line/bar/area, stacked bars, legend toggle, crosshair tooltip) and `MetricsChart` (granularity/range/type control bar for `/api/metrics/fetch`). |
 | `portal-mojo/admin/core` | Side-effect-light Admin contracts and host: `AdminSection`, the discriminated `AdminRoute` XOR, `adminSectionRoutes`, `adminSectionsMenu`, and `AdminLazyPage`. |
 | `portal-mojo/admin/registry` | Stable, narrow built-in `ADMIN_SECTIONS` roster for first-party hosts, without broad page barrels. It installs the optional Email→DNS adapter synchronously so communications routes work before DNS navigation. |

package/docs/README.md

@@ -51,6 +51,7 @@ everything: run the showcase (`npm run dev:showcase`) → **Develop → Componen
 | [image-editor.md](image-editor.md) | Full-resolution crop/transform/filter composition, bounded history, PNG Blob results, modal helper, and ImageField pre-upload editing |
 | [loading.md](loading.md) | `Spinner`, `busy()`/`busyWhile()` blocking overlay, `ViewLoader`, `InlineLoader`, `Busy` — the anti-flash delay rule and skeleton-vs-loader guidance |
 | [popover.md](popover.md) | Anchored top-layer popover shell — placement, reposition, outside/Escape close, the dialog stacking story |
+| [user-menu.md](user-menu.md) | Top-nav account menu — avatar trigger, identity header, theme control, app items, pending Sign out, signed-out matrix, keyboard map |
 | [taginput.md](taginput.md) | Chip/tag entry — CSV wire shape, keyboard matrix, validation + inline errors |
 | [combobox.md](combobox.md) | The house autocomplete — options with descriptions/meta, commit-only change pipeline, allowCustom, ARIA |
 | [location-address.md](location-address.md) | Six-endpoint LocationClient, private provider sessions, stale guards, controlled AddressField, atomic form patching |

package/docs/user-menu.md

@@ -0,0 +1,131 @@
+# UserMenu — the top-nav account menu
+
+```ts
+import { UserMenu, type UserMenuItem } from 'portal-mojo/ui';
+// also on the narrow shell boundary:
+import { UserMenu, type UserMenuItem } from 'portal-mojo/ui/shell';
+```
+
+The shared identity menu for every django-mojo portal's top bar — replaces
+hand-rolled "user chips" and the separate theme-cycle button. Ported from
+web-mojo's TopNav user dropdown (`src/core/views/navigation/TopNav.js`:
+avatar-or-icon trigger, end-aligned dropdown, divider rows) and
+`PortalApp._injectThemeToggleItems` (theme choice sits just above the
+trailing logout); the theme dialog becomes an inline Light/Dark/System
+segmented control.
+
+```tsx
+<header className="topnav">
+    <h2 className="topnav-title">Dashboard</h2>
+    <div className="topnav-right">
+        <UserMenu
+            authMode="inapp"
+            items={[
+                { label: 'My profile', icon: 'bi-person', to: '/profile' },
+                { label: 'Leave organization', icon: 'bi-box-arrow-left', danger: true, divider: true, onSelect: leave },
+            ]}
+            onSignOut={async () => { await revokeServerSession(); logout(); }}
+        />
+    </div>
+</header>
+```
+
+Live demo: showcase → Components → Overlays → **UserMenu**.
+
+## Props
+
+| Prop | Type | Notes |
+|---|---|---|
+| `items?` | `UserMenuItem[]` | App entries, rendered between the theme control and Sign out. |
+| `children?` | `ReactNode` | Rendered after `items`, above Sign out. Elements with `role="menuitem"` (and `tabIndex={-1}`, class `user-menu-item` for the look) join arrow-key navigation, and clicking one closes the menu. |
+| `authMode?` | `'inapp' \| 'hosted'` | Signed-out affordance (see matrix). The app knows its mode — the toolkit never imports app config. Unknown values warn once and render the signed-out chip. |
+| `onSignOut?` | `() => void \| Promise<void>` | Replaces the default `logout()`. Sign out shows a pending state ("Signing out…", spinner, `aria-busy`) until it settles; repeat clicks are ignored. A rejection toasts `Sign out failed: <message>` and leaves the menu open for a retry. |
+| `size?` | `'sm' \| 'md'` | Trigger density: 24px vs 28px avatar. Default `md`; unknown values warn once and fall back. |
+| `className?` | `string` | Appended to the trigger (or the signed-out element). |
+
+```ts
+interface UserMenuItem {
+    label: string;
+    icon?: string;          // bootstrap-icons class, e.g. 'bi-person'
+    to?: string;            // react-router <Link> destination
+    onSelect?: () => void;  // runs after the menu closes (also for `to` items)
+    danger?: boolean;       // danger tone
+    divider?: boolean;      // separator line ABOVE this item
+}
+```
+
+`divider` is a flag on the following item, not a standalone row (web-mojo's
+`{divider: true}` rows map to `divider: true` on the next entry).
+
+## Anatomy
+
+- **Trigger** — `<button>` with avatar (image, or `fmt.initials(name)` while
+  loading / without one / after an image error), display name, caret.
+  `aria-haspopup="menu"`, `aria-expanded`, `aria-controls` (while open), and
+  `aria-label="Account menu: <name>"` so the avatar-only phone trigger keeps
+  an accessible name. Under **720px** the name and caret hide.
+- **Popover** (`placement="bottom-end"`, 280px, clamped to the viewport):
+  identity header (42px avatar, name, email, `is_superuser` → "System admin"
+  chip), then the `role="menu"` list: Theme (three `menuitemradio`s wired to
+  `useTheme().setPref`), items, children, Sign out (danger tone).
+- Name = `me.display_name || me.email || token email || '…'`.
+
+## Wire contract
+
+- Identity: `useMe()` → `GET /api/user/me` (cache key `['me', uid]`, the row
+  is sanitized so `avatar` is `{id} | null`).
+- Avatar: when `me.avatar?.id` is set, `mojoCall('/api/fileman/file/<id>')`
+  runs **only while mounted** (AbortController on unmount/id change; failures
+  silent). The image is `thumbnail ?? url`, each through `safePreviewUrl`
+  (`ui/safe-url.ts`, shared with FileField): same-origin `/paths` or
+  credential-free `http(s)` only.
+- Sign out: `onSignOut()` or `logout()` (client-side; django-mojo has no
+  logout endpoint).
+
+## Invariants
+
+- The avatar URL is a **capability**: it lives in component state only and
+  is never written into any Query cache (the `me` cache holds `{id}` by
+  design). A previous identity's image can never render for the next
+  (state is keyed by avatar id).
+- No avatar request while signed out or when `avatar` is null.
+- Popover is controlled; outside-mousedown closes without moving focus.
+- Tokens only — `apps/portal/src/theme/user-menu.css`; both themes from the
+  token swap. Reuses `.seg`/`.seg-btn`, `.chip-primary`, `.spin`,
+  `.btn-primary`/`.btn-compact`, `.chip-muted`.
+
+## Signed-out matrix
+
+`useAuthSnapshot().authenticated === false` renders no menu:
+
+| `authMode` | Renders |
+|---|---|
+| `'inapp'` | `<Link to="/auth/login">` Sign in button |
+| `'hosted'` and `hostedAuthUrl()` resolves | Sign in button → `redirectToHostedAuth()` |
+| `'hosted'` with no API origin, or omitted | muted "Signed out" chip |
+
+## Keyboard
+
+| Where | Key | Effect |
+|---|---|---|
+| Trigger | Enter / Space / click | Toggle; on open focus the first item |
+| Trigger | ↓ / ↑ | Open (or enter the open menu) on the first / last item |
+| Menu | ↓ / ↑ | Next / previous item (wraps; includes the theme radios) |
+| Menu | Home / End | First / last item |
+| Theme control | ← / → | Previous / next theme option (wraps) |
+| Menu | Enter / Space | Activate (Space also activates `to` links) |
+| Menu | Escape | Close, focus back to the trigger (first Escape only closes the menu inside a modal) |
+| Menu | Tab / Shift+Tab | Close; focus continues from the trigger |
+
+Selecting an item or a `role="menuitem"` child closes the menu and returns
+focus to the trigger before `onSelect` runs (so dialogs opened from
+`onSelect` restore focus to a live element). A successful Sign out closes the
+menu. Theme picks apply immediately and keep the menu open.
+
+## Pitfalls
+
+- Needs a router context (items with `to`, and the in-app Sign in link) and
+  `ThemeProvider` for the theme control; `ToastHost` for the failure toast.
+- Don't also render a theme toggle button in the same bar — the menu owns it.
+- `onSignOut` that never settles leaves Sign out pending; resolve or reject.
+- Apps must ship `theme/user-menu.css` (the package ships no CSS).

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "portal-mojo",
-    "version": "0.2.6",
+    "version": "0.2.7",
     "description": "React portal toolkit for django-mojo — typed client + params store, mission-control UI, dependency-free SVG charts, admin section bundles.",
     "type": "module",
     "license": "Apache-2.0",

package/src/ui/FileField.tsx

@@ -7,6 +7,7 @@ import { useUploadQueue } from './UploadQueue';
 import { fileRelationId } from './field-wire';
 import { toast } from './toast';
 import { imageEditorModal, type ImageEditorModalOptions } from './image-editor';
+import { safePreviewUrl } from './safe-url';
 
 export type FileFieldState = 'keep' | 'clear' | 'replacement-in-progress' | 'replacement-failed'
     | 'completed-awaiting-attach' | 'attach-failed' | 'edit-pending' | 'edit-ready' | 'edit-failed';
@@ -53,16 +54,6 @@ export function reconcileFileOwnerResult(expected: number | null, result: FileFi
 
 interface PreviewRow { url?: unknown; thumbnail?: unknown; filename?: unknown }
 
-function safePreviewUrl(value: unknown): string | null {
-    if (typeof value !== 'string' || value.trim() !== value || !value || value.startsWith('//')) return null;
-    if (value.startsWith('/')) return /[\r\n\\]/.test(value) ? null : value;
-    try {
-        const url = new URL(value);
-        return (url.protocol === 'http:' || url.protocol === 'https:') && !url.username && !url.password
-            ? value : null;
-    } catch { return null; }
-}
-
 /**
  * Controlled django-mojo File relation editor. Browser File values, object
  * URLs, upload tasks, and stored preview capabilities stay component-local.

package/src/ui/UserMenu.tsx

@@ -0,0 +1,401 @@
+// UserMenu — the shared top-nav identity/account menu. Successor to the
+// hand-rolled "user chip" every portal carried, and the React port of
+// web-mojo's TopNav user dropdown (src/core/views/navigation/TopNav.js —
+// avatar-or-icon trigger, `dropdown-menu-end` items, divider rows) plus
+// PortalApp._injectThemeToggleItems (theme choice injected just above the
+// trailing logout). Here the theme choice is an inline Light/Dark/System
+// segmented control instead of a separate settings dialog.
+//
+// Identity comes from `useMe()`; the avatar capability (URL) is fetched from
+// `/api/fileman/file/<id>` ONLY while mounted and kept in component state —
+// never written into a Query cache (the `me` row is sanitized to `{id}` by
+// design). Same contract as FileField's stored preview.
+import {
+    useCallback,
+    useEffect,
+    useId,
+    useRef,
+    useState,
+    type KeyboardEvent,
+    type MouseEvent,
+    type ReactNode,
+} from 'react';
+import { Link } from 'react-router-dom';
+import { mojoCall } from '../client/client';
+import { hostedAuthUrl, logout, redirectToHostedAuth } from '../client/auth';
+import { useAuthSnapshot, useMe } from '../client/me';
+import { initials } from './format';
+import { Popover } from './Popover';
+import { safePreviewUrl } from './safe-url';
+import { useTheme, type ThemePref } from './ThemeProvider';
+import { toast } from './toast';
+import { warnOnce } from './warn-once';
+
+/** One app-supplied entry in the account menu. */
+export interface UserMenuItem {
+    label: string;
+    /** Bootstrap-icons class, e.g. `'bi-person'`. */
+    icon?: string;
+    /** Router destination — renders a react-router `<Link>`. */
+    to?: string;
+    /** Called after the menu closes (also called for `to` items). */
+    onSelect?: () => void;
+    /** Danger tone (destructive actions). */
+    danger?: boolean;
+    /** Draw a separator line ABOVE this item. */
+    divider?: boolean;
+}
+
+export type UserMenuAuthMode = 'inapp' | 'hosted';
+export type UserMenuSize = 'sm' | 'md';
+
+export interface UserMenuProps {
+    /** App items, rendered between the theme control and Sign out. */
+    items?: UserMenuItem[];
+    /** Extra content rendered above Sign out (after `items`). Elements with
+     *  `role="menuitem"` join arrow-key navigation and close the menu on click. */
+    children?: ReactNode;
+    /** Signed-out affordance: 'inapp' → Link to /auth/login; 'hosted' →
+     *  button calling redirectToHostedAuth(); omitted → "Signed out" chip. */
+    authMode?: UserMenuAuthMode;
+    /** Replaces the default `logout()`. A pending state shows while it runs;
+     *  a rejection toasts and leaves the menu open for a retry. */
+    onSignOut?: () => void | Promise<void>;
+    /** Trigger density (default 'md'). */
+    size?: UserMenuSize;
+    className?: string;
+}
+
+const SIZES: readonly UserMenuSize[] = ['sm', 'md'];
+const AUTH_MODES: readonly UserMenuAuthMode[] = ['inapp', 'hosted'];
+
+const THEMES: { value: ThemePref; label: string; icon: string }[] = [
+    { value: 'light', label: 'Light', icon: 'bi-sun' },
+    { value: 'dark', label: 'Dark', icon: 'bi-moon-stars' },
+    { value: 'system', label: 'System', icon: 'bi-circle-half' },
+];
+
+const ITEM_SELECTOR = '[role="menuitem"], [role="menuitemradio"], [role="menuitemcheckbox"]';
+
+function cx(...parts: (string | false | null | undefined)[]): string {
+    return parts.filter(Boolean).join(' ');
+}
+
+function Avatar({ src, name, className, onError }: {
+    src: string | null;
+    name: string;
+    className: string;
+    onError: () => void;
+}) {
+    return (
+        <span className={cx('user-menu-avatar', className)} aria-hidden="true">
+            {src
+                ? <img src={src} alt="" referrerPolicy="no-referrer" onError={onError} />
+                : initials(name)}
+        </span>
+    );
+}
+
+/** Stored avatar capability for `avatarId`, fetched while mounted only. */
+function useAvatarUrl(avatarId: number | null): [string | null, () => void] {
+    const [fetched, setFetched] = useState<{ id: number; src: string | null } | null>(null);
+    const [failedSrc, setFailedSrc] = useState<string | null>(null);
+
+    useEffect(() => {
+        if (avatarId == null) return;
+        const controller = new AbortController();
+        let live = true;
+        void mojoCall(`/api/fileman/file/${avatarId}`, { signal: controller.signal }).then((envelope) => {
+            if (!live || controller.signal.aborted) return;
+            const row = (envelope.data ?? {}) as { url?: unknown; thumbnail?: unknown };
+            setFetched({ id: avatarId, src: safePreviewUrl(row.thumbnail) ?? safePreviewUrl(row.url) });
+        }, () => { /* capability and failure remain local and silent */ });
+        return () => { live = false; controller.abort(); };
+    }, [avatarId]);
+
+    // Derived, so a previous identity's image never shows for the next one.
+    const src = avatarId != null && fetched?.id === avatarId ? fetched.src : null;
+    const onError = useCallback(() => setFailedSrc(src), [src]);
+    return [src && src !== failedSrc ? src : null, onError];
+}
+
+export function UserMenu({
+    items,
+    children,
+    authMode,
+    onSignOut,
+    size = 'md',
+    className,
+}: UserMenuProps) {
+    const auth = useAuthSnapshot();
+    const { data: me } = useMe();
+    const { pref, setPref } = useTheme();
+
+    const [open, setOpen] = useState(false);
+    const [signingOut, setSigningOut] = useState(false);
+    const triggerRef = useRef<HTMLButtonElement>(null);
+    const menuRef = useRef<HTMLDivElement>(null);
+    const focusOnOpen = useRef<'first' | 'last'>('first');
+    const mounted = useRef(true);
+    useEffect(() => {
+        mounted.current = true;
+        return () => { mounted.current = false; };
+    }, []);
+
+    const uid = useId();
+    const menuId = `${uid}-menu`;
+    const triggerId = `${uid}-trigger`;
+
+    let density = size;
+    if (!SIZES.includes(density)) {
+        warnOnce(`UserMenu: unknown size "${String(size)}" — falling back to "md"`);
+        density = 'md';
+    }
+    if (authMode !== undefined && !AUTH_MODES.includes(authMode)) {
+        warnOnce(`UserMenu: unknown authMode "${String(authMode)}" — rendering the signed-out chip`);
+    }
+
+    const [avatarSrc, onAvatarError] = useAvatarUrl(auth.authenticated ? me?.avatar?.id ?? null : null);
+    const menuOpen = open && auth.authenticated;
+
+    // Move focus into the menu once it is shown (Popover never moves focus).
+    useEffect(() => {
+        if (!menuOpen) return;
+        const nodes = menuItems(menuRef.current);
+        (focusOnOpen.current === 'last' ? nodes[nodes.length - 1] : nodes[0])?.focus();
+    }, [menuOpen]);
+
+    const close = useCallback((refocus: boolean) => {
+        setOpen(false);
+        if (refocus) triggerRef.current?.focus();
+    }, []);
+
+    // ── Signed out ───────────────────────────────────────────────────
+    if (!auth.authenticated) {
+        if (authMode === 'inapp') {
+            return (
+                <Link className={cx('btn btn-primary btn-compact', className)} to="/auth/login">
+                    <i className="bi bi-box-arrow-in-right" /> Sign in
+                </Link>
+            );
+        }
+        if (authMode === 'hosted' && hostedAuthUrl()) {
+            return (
+                <button type="button" className={cx('btn btn-primary btn-compact', className)} onClick={() => redirectToHostedAuth()}>
+                    <i className="bi bi-box-arrow-in-right" /> Sign in
+                </button>
+            );
+        }
+        return (
+            <span className={cx('chip chip-muted', className)}>
+                <i className="bi bi-person-slash" /> Signed out
+            </span>
+        );
+    }
+
+    const name = me?.display_name || me?.email || auth.email || '…';
+    const email = me?.email || auth.email || null;
+
+    const toggle = () => {
+        focusOnOpen.current = 'first';
+        setOpen((v) => !v);
+    };
+
+    const onTriggerKey = (event: KeyboardEvent<HTMLButtonElement>) => {
+        if (event.key !== 'ArrowDown' && event.key !== 'ArrowUp') return;
+        event.preventDefault();
+        focusOnOpen.current = event.key === 'ArrowUp' ? 'last' : 'first';
+        if (menuOpen) {
+            const nodes = menuItems(menuRef.current);
+            (event.key === 'ArrowUp' ? nodes[nodes.length - 1] : nodes[0])?.focus();
+        } else {
+            setOpen(true);
+        }
+    };
+
+    const onMenuKey = (event: KeyboardEvent<HTMLDivElement>) => {
+        const nodes = menuItems(menuRef.current);
+        if (nodes.length === 0) return;
+        const target = event.target as HTMLElement;
+        const index = nodes.indexOf(target);
+        const focusAt = (i: number) => nodes[(i + nodes.length) % nodes.length]?.focus();
+        switch (event.key) {
+            case 'ArrowDown':
+                event.preventDefault();
+                focusAt(index < 0 ? 0 : index + 1);
+                break;
+            case 'ArrowUp':
+                event.preventDefault();
+                focusAt(index < 0 ? nodes.length - 1 : index - 1);
+                break;
+            case 'Home':
+                event.preventDefault();
+                focusAt(0);
+                break;
+            case 'End':
+                event.preventDefault();
+                focusAt(nodes.length - 1);
+                break;
+            case 'ArrowLeft':
+            case 'ArrowRight': {
+                // Within the theme segmented control only.
+                if (target.getAttribute('role') !== 'menuitemradio') break;
+                const radios = Array.from(target.parentElement?.querySelectorAll<HTMLElement>('[role="menuitemradio"]') ?? []);
+                const at = radios.indexOf(target);
+                if (at < 0) break;
+                event.preventDefault();
+                const step = event.key === 'ArrowRight' ? 1 : -1;
+                radios[(at + step + radios.length) % radios.length]?.focus();
+                break;
+            }
+            case ' ':
+                // Buttons activate natively; a Link only activates on Enter.
+                if (target.tagName === 'A') {
+                    event.preventDefault();
+                    target.click();
+                }
+                break;
+            case 'Tab':
+                // Close and hand focus back to the trigger; the Tab default
+                // action then moves on from there (Shift+Tab goes back).
+                close(true);
+                break;
+            default:
+                break;
+        }
+    };
+
+    const select = (item: UserMenuItem) => {
+        close(true);
+        item.onSelect?.();
+    };
+
+    // Children: any role=menuitem click closes the menu (close-on-select).
+    const onChildrenClick = (event: MouseEvent<HTMLDivElement>) => {
+        if ((event.target as HTMLElement).closest(ITEM_SELECTOR)) close(true);
+    };
+
+    const signOut = async () => {
+        if (signingOut) return;
+        setSigningOut(true);
+        try {
+            if (onSignOut) await onSignOut();
+            else logout();
+            if (mounted.current) setOpen(false);
+        } catch (error) {
+            const message = error instanceof Error && error.message ? error.message : 'unknown error';
+            toast.error(`Sign out failed: ${message}`);
+        } finally {
+            if (mounted.current) setSigningOut(false);
+        }
+    };
+
+    return (
+        <>
+            <button
+                ref={triggerRef}
+                id={triggerId}
+                type="button"
+                className={cx('user-menu-trigger', `user-menu-${density}`, menuOpen && 'is-open', className)}
+                aria-haspopup="menu"
+                aria-expanded={menuOpen}
+                aria-controls={menuOpen ? menuId : undefined}
+                aria-label={`Account menu: ${name}`}
+                onClick={toggle}
+                onKeyDown={onTriggerKey}
+            >
+                <Avatar src={avatarSrc} name={name} className="user-menu-avatar-trigger" onError={onAvatarError} />
+                <span className="user-menu-name">{name}</span>
+                <i className="bi bi-chevron-down user-menu-caret" aria-hidden="true" />
+            </button>
+            <Popover
+                anchorRef={triggerRef}
+                open={menuOpen}
+                onClose={() => setOpen(false)}
+                placement="bottom-end"
+                role="none"
+                className="user-menu-pop"
+            >
+                <div className="user-menu-identity">
+                    <Avatar src={avatarSrc} name={name} className="user-menu-avatar-lg" onError={onAvatarError} />
+                    <div className="user-menu-who">
+                        <div className="user-menu-who-name">{name}</div>
+                        {email && <div className="user-menu-who-email">{email}</div>}
+                        {me?.is_superuser && (
+                            <span className="chip chip-primary user-menu-tag">
+                                <i className="bi bi-shield-lock" /> System admin
+                            </span>
+                        )}
+                    </div>
+                </div>
+                <div
+                    ref={menuRef}
+                    id={menuId}
+                    role="menu"
+                    aria-labelledby={triggerId}
+                    className="user-menu"
+                    onKeyDown={onMenuKey}
+                >
+                    <div className="user-menu-theme" role="group" aria-label="Theme">
+                        <span className="user-menu-theme-label" aria-hidden="true">Theme</span>
+                        <div className="seg user-menu-seg">
+                            {THEMES.map((theme) => (
+                                <button
+                                    key={theme.value}
+                                    type="button"
+                                    role="menuitemradio"
+                                    aria-checked={pref === theme.value}
+                                    tabIndex={-1}
+                                    className={cx('seg-btn', pref === theme.value && 'seg-active')}
+                                    onClick={() => setPref(theme.value)}
+                                >
+                                    <i className={`bi ${theme.icon}`} aria-hidden="true" /> {theme.label}
+                                </button>
+                            ))}
+                        </div>
+                    </div>
+                    {items && items.length > 0 && <div className="user-menu-sep" role="separator" />}
+                    {items?.map((item, i) => {
+                        const cls = cx('user-menu-item', item.danger && 'is-danger');
+                        const body = (
+                            <>
+                                <i className={`bi ${item.icon ?? 'bi-dot'}`} aria-hidden="true" />
+                                <span>{item.label}</span>
+                            </>
+                        );
+                        return (
+                            <div key={`${i}:${item.label}`} role="none" className="user-menu-row">
+                                {item.divider && i > 0 && <div className="user-menu-sep" role="separator" />}
+                                {item.to != null
+                                    ? <Link role="menuitem" tabIndex={-1} className={cls} to={item.to} onClick={() => select(item)}>{body}</Link>
+                                    : <button type="button" role="menuitem" tabIndex={-1} className={cls} onClick={() => select(item)}>{body}</button>}
+                            </div>
+                        );
+                    })}
+                    {children != null && children !== false && (
+                        <div role="none" className="user-menu-slot" onClick={onChildrenClick}>{children}</div>
+                    )}
+                    <div className="user-menu-sep" role="separator" />
+                    <button
+                        type="button"
+                        role="menuitem"
+                        tabIndex={-1}
+                        className="user-menu-item is-danger"
+                        aria-disabled={signingOut || undefined}
+                        aria-busy={signingOut || undefined}
+                        onClick={() => { void signOut(); }}
+                    >
+                        <i className={signingOut ? 'bi bi-arrow-repeat spin' : 'bi bi-box-arrow-right'} aria-hidden="true" />
+                        <span>{signingOut ? 'Signing out…' : 'Sign out'}</span>
+                    </button>
+                </div>
+            </Popover>
+        </>
+    );
+}
+
+function menuItems(root: HTMLElement | null): HTMLElement[] {
+    if (!root) return [];
+    return Array.from(root.querySelectorAll<HTMLElement>(ITEM_SELECTOR))
+        .filter((el) => !(el as HTMLButtonElement).disabled);
+}

package/src/ui/index.ts

@@ -35,6 +35,7 @@ export * from './RouteError';
 export * from './route-error';
 export * from './password';
 export * from './Popover';
+export * from './UserMenu';
 export * from './TagInput';
 export * from './toast';
 export * from './FileDrop';

package/src/ui/safe-url.ts

@@ -0,0 +1,14 @@
+// Shared guard for server-issued preview capabilities (fileman File `url` /
+// `thumbnail`). Accepts only same-origin absolute paths or credential-free
+// http(s) URLs — never `javascript:`, `data:`, protocol-relative `//host`, or
+// values with stray whitespace/CR/LF/backslashes. Callers keep the result in
+// component-local state; it must never be written into a Query cache.
+export function safePreviewUrl(value: unknown): string | null {
+    if (typeof value !== 'string' || value.trim() !== value || !value || value.startsWith('//')) return null;
+    if (value.startsWith('/')) return /[\r\n\\]/.test(value) ? null : value;
+    try {
+        const url = new URL(value);
+        return (url.protocol === 'http:' || url.protocol === 'https:') && !url.username && !url.password
+            ? value : null;
+    } catch { return null; }
+}

package/src/ui/shell.ts

@@ -4,6 +4,7 @@ export * from './Guarded';
 export * from './menu-registry';
 export * from './SidebarNav';
 export * from './RightPanel';
+export * from './UserMenu';
 export * from './RouteError';
 export * from './route-error';
 export * from './modal';