@cosmicdrift/kumiko-bundled-features 0.1.0

package/src/auth-email-password/web/session.tsx

@@ -0,0 +1,171 @@
+// @runtime client
+// Session-State für den Browser-Renderer. Hält den aktuell eingeloggten
+// User (Profile + aktive Tenant-Zuordnung + Memberships), reagiert auf
+// Login/Logout/Switch-Tenant und refresh't die Daten automatisch.
+//
+// Warum Context + useReducer statt z.B. Zustand? Weil die State-Menge
+// klein ist (ein Handful Felder, ein paar Transitionen) und wir damit
+// eine Dependency weniger im Browser-Bundle haben. Die Consumer leben
+// unter `<SessionProvider>`; der `useSession()`-Hook liefert den State
+// und die Transitions.
+
+import { createContext, type ReactNode, useCallback, useContext, useEffect, useState } from "react";
+import {
+  type CurrentUserProfile,
+  fetchCurrentUser,
+  fetchTenants,
+  type LoginFailure,
+  type LoginRequest,
+  login as loginApi,
+  logout as logoutApi,
+  switchTenant as switchTenantApi,
+  type TenantSummary,
+} from "./auth-client";
+
+export type SessionStatus = "loading" | "unauthenticated" | "authenticated";
+
+export type SessionState = {
+  readonly status: SessionStatus;
+  readonly user: CurrentUserProfile | null;
+  readonly activeTenantId: string | null;
+  readonly tenants: readonly TenantSummary[];
+  /** Merged session-roles für den active tenant: globalRoles (z.B.
+   *  SystemAdmin) + membership-roles des activeTenant. Server hat sie
+   *  schon im JWT gemerged, aber das JWT ist HttpOnly + nicht JS-lesbar;
+   *  Client computed dieselbe merge-Logik aus user.globalRoles +
+   *  tenants[active].roles damit nav-filtering greift. Dedupliziert. */
+  readonly roles: readonly string[];
+};
+
+export type SessionApi = SessionState & {
+  readonly login: (req: LoginRequest) => Promise<{ ok: true } | { ok: false; error: LoginFailure }>;
+  readonly logout: () => Promise<void>;
+  readonly switchTenant: (tenantId: string) => Promise<void>;
+};
+
+const INITIAL: SessionState = {
+  status: "loading",
+  user: null,
+  activeTenantId: null,
+  tenants: [],
+  roles: [],
+};
+
+// Exported damit tests den merge-pfad direkt pinnen können — der hier
+// muss byte-identisch zum server-side merge in auth-routes.ts +
+// login.write.ts sein, sonst sieht der Client andere session-rollen
+// als der Server.
+export function computeActiveRoles(
+  user: CurrentUserProfile | null,
+  activeTenantId: string | null,
+  tenants: readonly TenantSummary[],
+): readonly string[] {
+  if (user === null) return [];
+  const membership =
+    activeTenantId !== null ? tenants.find((t) => t.tenantId === activeTenantId) : undefined;
+  const membershipRoles = membership?.roles ?? [];
+  // Set-Dedupe spiegelt server-side merge (auth-routes.ts switch-tenant +
+  // login.write.ts).
+  return Array.from(new Set([...user.globalRoles, ...membershipRoles]));
+}
+
+/** Internal — exposed for tests die einen Mock-SessionApi-Wert reinreichen
+ *  wollen, ohne durch SessionProvider's refresh-Lifecycle zu müssen. App-
+ *  Code nutzt SessionProvider + useSession; direkter Context-Zugriff ist
+ *  für Tests/Stories. */
+export const SessionContext = createContext<SessionApi | undefined>(undefined);
+
+// Eine Refresh-Runde: /auth/tenants → wenn 401 nicht-eingeloggt, sonst
+// parallel /user:me. Beides zusammen ergibt den vollen SessionState.
+async function refresh(): Promise<SessionState> {
+  const tenants = await fetchTenants();
+  if (tenants === null) {
+    return {
+      status: "unauthenticated",
+      user: null,
+      activeTenantId: null,
+      tenants: [],
+      roles: [],
+    };
+  }
+  const user = await fetchCurrentUser();
+  if (user === null) {
+    return {
+      status: "unauthenticated",
+      user: null,
+      activeTenantId: null,
+      tenants: [],
+      roles: [],
+    };
+  }
+  return {
+    status: "authenticated",
+    user,
+    activeTenantId: tenants.activeTenantId,
+    tenants: tenants.tenants,
+    roles: computeActiveRoles(user, tenants.activeTenantId, tenants.tenants),
+  };
+}
+
+export function SessionProvider({ children }: { readonly children: ReactNode }): ReactNode {
+  const [state, setState] = useState<SessionState>(INITIAL);
+
+  const doRefresh = useCallback(async () => {
+    const next = await refresh();
+    setState(next);
+  }, []);
+
+  useEffect(() => {
+    void doRefresh();
+  }, [doRefresh]);
+
+  const login = useCallback<SessionApi["login"]>(
+    async (req) => {
+      const res = await loginApi(req);
+      if (!res.ok) return { ok: false, error: res.error };
+      await doRefresh();
+      return { ok: true };
+    },
+    [doRefresh],
+  );
+
+  const logout = useCallback<SessionApi["logout"]>(async () => {
+    await logoutApi();
+    setState({
+      status: "unauthenticated",
+      user: null,
+      activeTenantId: null,
+      tenants: [],
+      roles: [],
+    });
+    // Hard-Reload: React-Tree, dispatcher-live-Caches, EventSource —
+    // alles fliegt auf Null. Nach Logout ist das der billigste Weg zu
+    // sauberer Ausgangslage, ohne dass wir jeden einzelnen Consumer
+    // per Context-Bust invalidieren müssen.
+    if (typeof window !== "undefined") {
+      window.location.reload();
+    }
+  }, []);
+
+  const switchTenant = useCallback<SessionApi["switchTenant"]>(async (tenantId) => {
+    await switchTenantApi(tenantId);
+    // Tenant-Wechsel rotiert JWT + Cookies. React-Tree enthält
+    // tenant-gebundene Caches (Queries, Live-Events) — simpler
+    // Reload ist konsistent mit dem Logout-Pfad und vermeidet
+    // halbe State-Übergänge.
+    if (typeof window !== "undefined") {
+      window.location.reload();
+    }
+  }, []);
+
+  const api: SessionApi = { ...state, login, logout, switchTenant };
+  return <SessionContext.Provider value={api}>{children}</SessionContext.Provider>;
+}
+
+export function useSession(): SessionApi {
+  const ctx = useContext(SessionContext);
+  if (ctx === undefined) {
+    throw new Error("useSession must be used inside <SessionProvider>");
+  }
+  return ctx;
+}

package/src/auth-email-password/web/signup-complete-screen.tsx

@@ -0,0 +1,150 @@
+// @runtime client
+// SignupCompleteScreen — Magic-Link-Self-Signup, Step 2.
+//
+// Liest `?token=...` aus der URL, zeigt Form mit Password + Confirm.
+// Submit triggert /api/auth/signup-confirm — bei Erfolg setzt der
+// Server JWT + Cookies (Auto-Login!) und liefert tenantKey für den
+// Post-Signup-Redirect.
+//
+// Token-Quelle ist read-once: parseUrlToken im useState-Initializer.
+// Apps die einen anderen URL-Param nutzen, reichen `token` als Prop
+// durch.
+//
+// Nach success: redirect via window.location.assign zu loggedInHref.
+// Default-Pattern ist "/<tenantKey>/" — die App reicht ein Template
+// rein. Default-Template "/" wäre auch valide (App hat dann eigene
+// Routing-Logik die den eingeloggten User zur richtigen Page schickt).
+
+import { usePrimitives, useTranslation } from "@cosmicdrift/kumiko-renderer";
+import { type FormEvent, type ReactNode, useState } from "react";
+import { confirmSignup } from "./auth-client";
+import { AuthCard, authMutedLinkClass, parseUrlToken } from "./auth-form-primitives";
+
+export type SignupCompleteScreenProps = {
+  readonly title?: string;
+  /** Override für den Token aus der URL — Apps die per server-side-
+   *  Render einen Token reinreichen, brauchen das. Default: parsed aus
+   *  `?token=...` in der URL. */
+  readonly token?: string;
+  /** Where to send the user after successful activation. Default "/" —
+   *  Apps mit Multi-Tenant-Routing ersetzen das durch
+   *  `(data) => "/" + data.tenantKey + "/"`. Function-form, weil nur
+   *  nach success bekannt welcher tenantKey zugeteilt wurde. */
+  readonly loggedInHref?: string | ((args: { tenantKey: string }) => string);
+  /** href für "Schon einen Account?"-Link bei missing-token-Fall.
+   *  Default "/login". */
+  readonly loginHref?: string;
+};
+
+export function SignupCompleteScreen({
+  title,
+  token: tokenProp,
+  loggedInHref = "/",
+  loginHref = "/login",
+}: SignupCompleteScreenProps): ReactNode {
+  const t = useTranslation();
+  const { Form, Field, Input, Button, Banner } = usePrimitives();
+  const [token] = useState(() => tokenProp ?? parseUrlToken());
+  const [password, setPassword] = useState("");
+  const [confirmPassword, setConfirmPassword] = useState("");
+  const [submitting, setSubmitting] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  const doSubmit = async (): Promise<void> => {
+    setError(null);
+    if (password.length < 8) {
+      setError(t("auth.signupComplete.tooShort"));
+      return;
+    }
+    if (password !== confirmPassword) {
+      setError(t("auth.signupComplete.mismatch"));
+      return;
+    }
+    setSubmitting(true);
+    const res = await confirmSignup(token, password);
+    setSubmitting(false);
+    if (res.ok) {
+      // Auto-Login: Cookies sind via Set-Cookie schon im Browser. Wir
+      // schicken den User direkt zur eingeloggten Page.
+      const target =
+        typeof loggedInHref === "function"
+          ? loggedInHref({ tenantKey: res.data.tenantKey })
+          : loggedInHref;
+      window.location.assign(target);
+      return;
+    }
+    if (res.error.reason === "invalid_signup_token") {
+      setError(t("auth.errors.invalidSignupToken"));
+      return;
+    }
+    if (res.error.reason === "rate_limited") {
+      setError(t("auth.errors.rateLimited"));
+      return;
+    }
+    setError(t("auth.errors.unknownError"));
+  };
+
+  const onSubmit = (e?: FormEvent): void => {
+    e?.preventDefault();
+    void doSubmit();
+  };
+
+  const effectiveTitle = title ?? t("auth.signupComplete.title");
+
+  // Kein Token in der URL → klare Message statt Form ohne Token
+  // (würde nur invalidSignupToken zeigen, verwirrend).
+  if (token === "") {
+    return (
+      <AuthCard title={effectiveTitle}>
+        <div className="p-6 pt-0 flex flex-col gap-4">
+          <p className="text-sm text-muted-foreground">{t("auth.signupComplete.missingToken")}</p>
+          <a href={loginHref} className={authMutedLinkClass}>
+            {t("auth.signup.haveAccount")}
+          </a>
+        </div>
+      </AuthCard>
+    );
+  }
+
+  return (
+    <AuthCard title={effectiveTitle}>
+      <div className="p-6 pt-0 flex flex-col gap-4">
+        <p className="text-sm text-muted-foreground">{t("auth.signupComplete.intro")}</p>
+        <Form onSubmit={onSubmit}>
+          <Field id="signup-password" label={t("auth.signupComplete.password")} required>
+            <Input
+              kind="password"
+              id="signup-password"
+              name="signup-password"
+              value={password}
+              onChange={setPassword}
+              disabled={submitting}
+              required
+              autoComplete="new-password"
+            />
+          </Field>
+          <Field
+            id="signup-confirm-password"
+            label={t("auth.signupComplete.confirmPassword")}
+            required
+          >
+            <Input
+              kind="password"
+              id="signup-confirm-password"
+              name="signup-confirm-password"
+              value={confirmPassword}
+              onChange={setConfirmPassword}
+              disabled={submitting}
+              required
+              autoComplete="new-password"
+            />
+          </Field>
+          {error !== null && <Banner variant="error">{error}</Banner>}
+          <Button type="submit" loading={submitting} disabled={submitting}>
+            {submitting ? t("auth.signupComplete.submitting") : t("auth.signupComplete.submit")}
+          </Button>
+        </Form>
+      </div>
+    </AuthCard>
+  );
+}

package/src/auth-email-password/web/signup-screen.tsx

@@ -0,0 +1,130 @@
+// @runtime client
+// SignupScreen — Magic-Link-Self-Signup, Step 1.
+//
+// Form mit Email-Input. Submit triggert /api/auth/signup-request
+// (silent-success, kein account-enumeration). UI zeigt unconditional
+// ein "Mail unterwegs"-Confirm mit Resend-Button — auch wenn die Email
+// schon registriert ist (Server schickt dann dieselbe Mail mit dem
+// existing Token aus Redis = idempotent).
+//
+// App ist verantwortlich, den Screen unter einer URL zu mounten (z.B.
+// /signup) und ihn anonymous reachable zu machen (AuthPathGate VOR
+// AuthGate). Apex-Marketing kann via Link "Kostenlos starten" auf den
+// /signup-Pfad routen.
+
+import { usePrimitives, useTranslation } from "@cosmicdrift/kumiko-renderer";
+import { type FormEvent, type ReactNode, useState } from "react";
+import { requestSignup } from "./auth-client";
+import { AuthCard, authMutedLinkClass } from "./auth-form-primitives";
+
+export type SignupScreenProps = {
+  readonly title?: string;
+  readonly subtitle?: ReactNode;
+  /** href für den "Bereits einen Account?"-Link. App-spezifisch — Default
+   *  "/login". */
+  readonly loginHref?: string;
+};
+
+export function SignupScreen({
+  title,
+  subtitle,
+  loginHref = "/login",
+}: SignupScreenProps): ReactNode {
+  const t = useTranslation();
+  const { Form, Field, Input, Button, Banner } = usePrimitives();
+  const [email, setEmail] = useState("");
+  const [submitting, setSubmitting] = useState(false);
+  const [done, setDone] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  const doSubmit = async (): Promise<void> => {
+    setSubmitting(true);
+    setError(null);
+    try {
+      const res = await requestSignup(email);
+      if (res.ok) {
+        setDone(true);
+      } else if (res.error.reason === "rate_limited") {
+        const minutes =
+          res.error.retryAfterSeconds !== undefined
+            ? Math.ceil(res.error.retryAfterSeconds / 60)
+            : undefined;
+        setError(
+          minutes !== undefined
+            ? t("auth.errors.accountLockedRetry", { minutes })
+            : t("auth.errors.rateLimited"),
+        );
+      } else {
+        setError(t("auth.errors.unknownError"));
+      }
+    } catch {
+      setError(t("auth.errors.unknownError"));
+    } finally {
+      setSubmitting(false);
+    }
+  };
+
+  const onSubmit = (e?: FormEvent): void => {
+    e?.preventDefault();
+    void doSubmit();
+  };
+
+  const onResend = async (): Promise<void> => {
+    // Resend nutzt den gleichen Endpunkt — Server returnt den existing
+    // Token aus Redis und schickt eine zweite Mail mit dem GLEICHEN
+    // Activation-Link (alte Mail bleibt also gültig).
+    setSubmitting(true);
+    setError(null);
+    try {
+      await requestSignup(email);
+    } finally {
+      setSubmitting(false);
+    }
+  };
+
+  const effectiveTitle = title ?? t("auth.signup.title");
+
+  return (
+    <AuthCard title={effectiveTitle} subtitle={subtitle}>
+      {done ? (
+        <div className="p-6 pt-0 flex flex-col gap-4">
+          <Banner variant="info">
+            <p className="font-medium text-foreground">{t("auth.signup.successTitle")}</p>
+            <p className="mt-1">{t("auth.signup.successBody")}</p>
+          </Banner>
+          <Button variant="secondary" onClick={onResend} disabled={submitting}>
+            {t("auth.signup.resend")}
+          </Button>
+          <a href={loginHref} className={authMutedLinkClass}>
+            {t("auth.signup.haveAccount")}
+          </a>
+        </div>
+      ) : (
+        <div className="p-6 pt-0 flex flex-col gap-4">
+          <p className="text-sm text-muted-foreground">{t("auth.signup.intro")}</p>
+          <Form onSubmit={onSubmit}>
+            <Field id="signup-email" label={t("auth.signup.email")} required>
+              <Input
+                kind="email"
+                id="signup-email"
+                name="signup-email"
+                value={email}
+                onChange={setEmail}
+                disabled={submitting}
+                required
+                autoComplete="email"
+              />
+            </Field>
+            {error !== null && <Banner variant="error">{error}</Banner>}
+            <Button type="submit" loading={submitting} disabled={submitting}>
+              {submitting ? t("auth.signup.submitting") : t("auth.signup.submit")}
+            </Button>
+          </Form>
+          <a href={loginHref} className={`${authMutedLinkClass} self-center`}>
+            {t("auth.signup.haveAccount")}
+          </a>
+        </div>
+      )}
+    </AuthCard>
+  );
+}

package/src/auth-email-password/web/tenant-switcher.tsx

@@ -0,0 +1,116 @@
+// @runtime client
+// TenantSwitcher — kleines Dropdown, zeigt den aktiven Tenant und
+// erlaubt Wechsel zu anderen Memberships. Auf Radix-DropdownMenu für
+// konsistentes Verhalten (Click-outside/Escape/Keyboard-Nav).
+//
+// Rendert NICHT wenn kein User eingeloggt ist und auch NICHT wenn der
+// User nur einen Tenant hat (Single-Tenant-Apps brauchen keinen
+// Switcher).
+//
+// Der Display-Name kommt aus einem optionalen `tenantName`-Prop
+// oder fallback zum ID-Hash. Design-Entscheidung: der TenantSwitcher
+// holt NICHT selbst tenant:query:me — das würde Round-Trips pro Mount
+// kosten und bräuchte Query-Caching-Infrastruktur. Stattdessen reicht
+// der Host den Resolver rein (kommt z.B. aus einer useTenantNames()-
+// Hook die einmalig am App-Boot geladen wird).
+
+import { useTranslation } from "@cosmicdrift/kumiko-renderer";
+import {
+  cn,
+  DropdownMenu,
+  DropdownMenuCheckboxItem,
+  DropdownMenuContent,
+  DropdownMenuLabel,
+  DropdownMenuTrigger,
+} from "@cosmicdrift/kumiko-renderer-web";
+import { Building2, ChevronDown } from "lucide-react";
+import { type ReactNode, useCallback, useState } from "react";
+import { useSession } from "./session";
+
+export type TenantSwitcherProps = {
+  /** Optional: liefert einen menschenlesbaren Namen pro Tenant-ID.
+   *  Default: die ID wird direkt angezeigt (kurze UUID genügt für
+   *  Dev-Umgebungen). Für prod sollte der Host z.B. die Tenant-Namen
+   *  beim Login cachen und hier durchreichen. */
+  readonly tenantName?: (tenantId: string) => string;
+};
+
+export function TenantSwitcher({ tenantName }: TenantSwitcherProps): ReactNode {
+  const t = useTranslation();
+  const { user, tenants, activeTenantId, switchTenant } = useSession();
+  const [switching, setSwitching] = useState<string | null>(null);
+
+  const handleSwitch = useCallback(
+    async (tenantId: string) => {
+      if (tenantId === activeTenantId) return;
+      setSwitching(tenantId);
+      try {
+        await switchTenant(tenantId);
+      } finally {
+        // In der Praxis führt switchTenant zu einem full-page reload,
+        // also sehen wir den cleared-state nie — das `finally` ist nur
+        // für den Edge-Case dass switchTenant throwt, damit die UI
+        // nicht mit dem Spinner hängen bleibt.
+        setSwitching(null);
+      }
+    },
+    [activeTenantId, switchTenant],
+  );
+
+  const nameOf = (tenantId: string): string =>
+    tenantName !== undefined ? tenantName(tenantId) : tenantId.slice(0, 8);
+
+  // Rendering-Gate: kein User → nix; nur ein Tenant → auch nix
+  // (Single-Tenant-Apps brauchen keinen Switcher).
+  if (user === null || tenants.length <= 1) return null;
+
+  const activeLabel =
+    activeTenantId !== null ? nameOf(activeTenantId) : t("auth.tenant.switcher.none");
+
+  return (
+    <DropdownMenu>
+      <DropdownMenuTrigger asChild>
+        {/* kumiko-lint-ignore primitives-discipline radix-asChild braucht DOM-Element als Trigger; Native kriegt eigene .native.tsx-Variante mit ActionSheet */}
+        <button
+          type="button"
+          className={cn(
+            "inline-flex items-center gap-2 rounded-md border border-input bg-background px-2 py-1 text-sm",
+            "hover:bg-accent hover:text-accent-foreground",
+            "focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring",
+          )}
+        >
+          <Building2 className="h-3.5 w-3.5 text-muted-foreground" />
+          <span className="max-w-[14ch] truncate">{activeLabel}</span>
+          <ChevronDown className="h-3 w-3 text-muted-foreground" />
+        </button>
+      </DropdownMenuTrigger>
+      <DropdownMenuContent align="end" className="min-w-[14rem]">
+        <DropdownMenuLabel>{t("auth.tenant.switcher.label")}</DropdownMenuLabel>
+        {tenants.map((membership) => {
+          const isActive = membership.tenantId === activeTenantId;
+          const isSwitching = switching === membership.tenantId;
+          return (
+            <DropdownMenuCheckboxItem
+              key={membership.tenantId}
+              checked={isActive}
+              disabled={isSwitching}
+              onSelect={(e) => {
+                e.preventDefault();
+                void handleSwitch(membership.tenantId);
+              }}
+            >
+              <div className="flex flex-col items-start min-w-0">
+                <span className="truncate font-medium">{nameOf(membership.tenantId)}</span>
+                {membership.roles.length > 0 && (
+                  <span className="text-xs text-muted-foreground truncate">
+                    {membership.roles.join(", ")}
+                  </span>
+                )}
+              </div>
+            </DropdownMenuCheckboxItem>
+          );
+        })}
+      </DropdownMenuContent>
+    </DropdownMenu>
+  );
+}

package/src/auth-email-password/web/use-shell-user.ts

@@ -0,0 +1,34 @@
+// @runtime client
+// Liest den eingeloggten User + die Rollen aus dem aktiven Tenant aus
+// der Session. Der Hook ist die Standard-Brücke zwischen Session-State
+// und Layout-Komponenten (WorkspaceShell.user, DefaultAppShell-Gates,
+// custom permission checks).
+//
+// Returns undefined solange:
+//   - die Session lädt (status="loading")
+//   - der User unauthenticated ist
+//   - der activeTenantId in der tenants-Liste fehlt (defensiver Pfad —
+//     sollte nicht passieren, schadet aber nicht zu prüfen)
+//
+// WorkspaceShell + DefaultAppShell akzeptieren undefined als "keine
+// Workspaces sichtbar", was im Loading-/Logged-Out-Fall die richtige UX
+// ist. Apps die mehr brauchen (Loading-Indicator etc.) prüfen
+// useSession().status direkt.
+
+import { useMemo } from "react";
+import { useSession } from "./session";
+
+export type ShellUser = {
+  readonly id: string;
+  readonly roles: readonly string[];
+};
+
+export function useShellUser(): ShellUser | undefined {
+  const session = useSession();
+  return useMemo(() => {
+    if (session.status !== "authenticated" || session.user === null) return undefined;
+    const activeTenant = session.tenants.find((t) => t.tenantId === session.activeTenantId);
+    if (activeTenant === undefined) return undefined;
+    return { id: session.user.id, roles: activeTenant.roles };
+  }, [session.status, session.user, session.activeTenantId, session.tenants]);
+}

package/src/auth-email-password/web/user-menu.tsx

@@ -0,0 +1,89 @@
+// @runtime client
+// UserMenu — Avatar-Dropdown in der Topbar/Sidebar. Zeigt Name/Email
+// des aktuellen Users + Logout-Button. Auf Radix-DropdownMenu, damit
+// Click-outside, Escape, Focus-Management, Keyboard-Nav (↑↓/Home/End)
+// und ARIA-Roles aus der Kiste funktionieren.
+//
+// Rendert NICHTS wenn kein User eingeloggt ist — Hosts dürfen das
+// Component außerhalb des AuthGate einhängen ohne dass ein harter
+// Fehler entsteht.
+
+import { useTranslation } from "@cosmicdrift/kumiko-renderer";
+import {
+  cn,
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuLabel,
+  DropdownMenuSeparator,
+  DropdownMenuTrigger,
+} from "@cosmicdrift/kumiko-renderer-web";
+import { ChevronDown, LogOut } from "lucide-react";
+import type { ReactNode } from "react";
+import { useSession } from "./session";
+
+export type UserMenuProps = {
+  /** Zusätzliche Menu-Items über dem Logout. Per-item class/behaviour
+   *  controlliert der Caller — wir packen nur den Frame drumrum. */
+  readonly children?: ReactNode;
+};
+
+function initials(value: string): string {
+  // Vor- und Nachname falls Displayname einen Spacebar hat, sonst
+  // erste zwei Chars der Email-Lokalseite. Deterministisch,
+  // damit der Avatar-Content nicht bei jedem Re-Render flattert.
+  const trimmed = value.trim();
+  if (trimmed.length === 0) return "?";
+  const parts = trimmed.split(/\s+/);
+  if (parts.length >= 2) {
+    return (parts[0]?.[0] ?? "").concat(parts[1]?.[0] ?? "").toUpperCase();
+  }
+  return trimmed.slice(0, 2).toUpperCase();
+}
+
+export function UserMenu({ children }: UserMenuProps): ReactNode {
+  const t = useTranslation();
+  const { user, logout } = useSession();
+
+  if (user === null) return null;
+
+  const displayName = user.displayName.length > 0 ? user.displayName : user.email;
+  const avatarText = initials(displayName);
+
+  return (
+    <DropdownMenu>
+      <DropdownMenuTrigger asChild>
+        {/* kumiko-lint-ignore primitives-discipline radix-asChild braucht DOM-Element als Trigger; Native kriegt eigene .native.tsx-Variante mit ActionSheet */}
+        <button
+          type="button"
+          className={cn(
+            "inline-flex items-center gap-2 rounded-md px-2 py-1 text-sm",
+            "text-foreground hover:bg-accent hover:text-accent-foreground",
+            "focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring",
+          )}
+        >
+          <span
+            aria-hidden="true"
+            className="inline-flex h-7 w-7 items-center justify-center rounded-full bg-muted text-xs font-medium text-muted-foreground"
+          >
+            {avatarText}
+          </span>
+          <span className="hidden sm:inline max-w-[12ch] truncate">{displayName}</span>
+          <ChevronDown className="h-3 w-3 text-muted-foreground" />
+        </button>
+      </DropdownMenuTrigger>
+      <DropdownMenuContent align="end" aria-label={t("auth.user.menu.label")}>
+        <DropdownMenuLabel className="text-xs">
+          <div className="font-medium text-foreground truncate">{displayName}</div>
+          <div className="truncate">{user.email}</div>
+        </DropdownMenuLabel>
+        <DropdownMenuSeparator />
+        {children}
+        <DropdownMenuItem onSelect={() => void logout()}>
+          <LogOut className="h-4 w-4" />
+          <span>{t("auth.user.menu.logout")}</span>
+        </DropdownMenuItem>
+      </DropdownMenuContent>
+    </DropdownMenu>
+  );
+}