create-astram-app 0.1.2 → 0.2.0

package/template/frontend/src/auth/AuthContext.jsx

@@ -0,0 +1,338 @@
+/**
+ * AuthContext — the web app's session state + wiring of @astram/frontend-core's
+ * platform-agnostic auth logic to the WEB platform adapters (fetch + localStorage).
+ *
+ * The LOGIC (how login/refresh/logout talk to the framework API) lives in
+ * @astram/frontend-core — this file only injects the browser's fetch client +
+ * localStorage, holds the React state, and exposes `useAuth()` to the views. A future
+ * mobile app has its own AuthContext that injects RN adapters into the SAME shared
+ * services.
+ */
+
+import { createContext, useContext, useEffect, useMemo, useRef, useState } from 'react';
+import { createShieldClient, systemClock } from '@astram/sdk';
+import {
+  createAccountService,
+  createAuditService,
+  createAuthService,
+  createIdentityService,
+  isAuthenticated,
+  principalOf,
+} from '@astram/frontend-core';
+import { createWebHttpClient } from '../platform/httpClient';
+import { createWebSessionStore } from '../platform/sessionStore';
+import { createWebShieldTransport } from '../platform/shieldTransport';
+
+const AuthContext = createContext(null);
+
+export function AuthProvider({ children }) {
+  // Whether the current session is server-side-restricted to re-securing the account
+  // (recovery-code login → `mustReenroll`). Held in a ref so the http-client interceptor
+  // (built once, below) can flip it without being re-created; mirrored into React state
+  // so the router re-renders. Until a fresh device is confirmed, the app forces the
+  // re-enroll screen (§4). Set on either (a) a `mfaRecoveryUsed:true` login result, or
+  // (b) the app-wide 403 `reenrollment_required` interceptor catching a blocked request.
+  const [mustReenroll, setMustReenroll] = useState(false);
+  const reenrollRef = useRef(false);
+  const markReenroll = () => {
+    if (reenrollRef.current) return; // already flagged — avoid redundant re-renders
+    reenrollRef.current = true;
+    setMustReenroll(true);
+  };
+  const clearReenroll = () => {
+    reenrollRef.current = false;
+    setMustReenroll(false);
+  };
+
+  // The CURRENT access token, read by the shield transport's `getToken` getter. A ref
+  // (not a captured value) so the transport — built ONCE below — always reads the LIVE
+  // token across login/refresh/logout without needing to be reconstructed (mirrors
+  // `reenrollRef` above for the identical reason).
+  const tokenRef = useRef(null);
+
+  // Build the shared services from the injected web platform adapters (once). The
+  // LOGIC is @astram/frontend-core; only the http client + storage are web-specific here.
+  const services = useRef(null);
+  if (!services.current) {
+    // The http client gets an app-wide interceptor: a 403 whose body is EXACTLY
+    // `{ error: 'reenrollment_required' }` (the enforced-re-enroll gate, §4) flips the
+    // app into the forced re-enroll flow. Matched narrowly so a future permission-deny
+    // 403 never triggers it.
+    const http = createWebHttpClient({ onReenrollRequired: () => markReenroll() });
+    const store = createWebSessionStore();
+    services.current = {
+      auth: createAuthService(http),
+      identity: createIdentityService(http),
+      audit: createAuditService(http),
+      account: createAccountService(http),
+      // The @astram/sdk ShieldClient (Phase E slice 1) — a UX-convenience projection of
+      // the caller's OWN coarse grants, fetched once per session via `getAuthFacts`.
+      // NEVER the security boundary: the server's decide() on every @Classified route
+      // is the real enforcement (see shieldTransport.js's header doc). `getToken` reads
+      // `tokenRef.current` (not a closed-over value) so the SAME client instance always
+      // sees the CURRENT token across a refresh, without being rebuilt.
+      shield: createShieldClient({
+        transport: createWebShieldTransport({ http, getToken: () => tokenRef.current }),
+        clock: systemClock,
+        scheduler: { sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)) },
+      }),
+      store,
+    };
+  }
+  const { auth, identity, audit, account, shield, store } = services.current;
+
+  const [state, setState] = useState(() => store.load()); // SessionState | null
+  // The signed-in user's DISPLAY profile (name/email/company/roles) from GET /auth/me.
+  // Resolved server-side to NAMES (never UUIDs). null until fetched / when unavailable.
+  const [profile, setProfile] = useState(null);
+
+  // The caller's authorization-fact projection (Phase E slice 1) — `null` until fetched
+  // at least once for this session. Fail-closed: `useCan` treats `null` (not yet known)
+  // exactly like "the fact is absent" — hide/disable until a projection is in hand,
+  // never optimistically show.
+  const [authFacts, setAuthFacts] = useState(null);
+
+  // Keep `tokenRef` in lockstep with the persisted session's access token so the shield
+  // transport (built once, above) always reads the CURRENT token.
+  tokenRef.current = state?.tokens?.accessToken ?? null;
+
+  const persist = (value) => {
+    setState(value);
+    store.save(value);
+  };
+
+  // Fetch the display profile for the current access token. Best-effort: on any
+  // non-ok (401/404/501/unreachable) we simply clear it and the UI falls back to the
+  // interim identity hint — the profile is enrichment, never a gate.
+  const loadProfile = async (accessToken) => {
+    if (!accessToken) {
+      setProfile(null);
+      return;
+    }
+    const r = await auth.me(accessToken);
+    setProfile(r.ok ? r.profile : null);
+  };
+
+  // Re-fetch the display profile for the CURRENT session's token. Exposed via
+  // useAuth() so a self-service edit (PATCH /account/profile) can refresh the
+  // header/user card in place after a successful save. Best-effort like loadProfile.
+  const refreshProfile = async () => {
+    await loadProfile(state?.tokens?.accessToken);
+  };
+
+  // Fetch the caller's OWN authorization-fact projection. Called on login/mount, AND
+  // (Phase E slice 2 — ADR-0011 frontend twin) repeatedly via the focus + interval
+  // effect below, so a mid-session permission-version BUMP is picked up without a
+  // manual reload: `shield.getAuthFacts` re-checks staleness (via the transport's
+  // `currentVersion()` probe) on EVERY call and only refetches the full projection when
+  // the version actually moved — a poll that finds nothing stale costs one cheap
+  // version-probe request. `shield.getAuthFacts` is ITSELF fail-closed by construction:
+  // no transport / a terminal deny / a transient outage all resolve to a projection with
+  // NO allowed facts, or the last-good one held stale (see shieldTransport.js +
+  // client.ts's `fetchAndCacheProjection`) — never throws, so this never needs a
+  // try/catch to stay safe, and (no-flicker) `authFacts` is only ever set to a
+  // RESOLVED projection, never reset to `null` mid-poll. `principalId` absent (no
+  // session yet) → skip, leaving `authFacts` at its fail-closed `null` (useCan
+  // hides/denies until known).
+  const refreshAuthFacts = async (principalId) => {
+    if (!principalId) {
+      setAuthFacts(null);
+      return;
+    }
+    const projection = await shield.getAuthFacts(principalId);
+    setAuthFacts(projection);
+  };
+
+  // The shared post-authentication work: persist the session + fetch the display
+  // profile + the auth-facts projection. Both a plain login and an MFA-completed login
+  // end here, so the session is established identically regardless of which path
+  // authenticated the user.
+  const establishSession = async (session, tokens, identityHint) => {
+    // Keep the identity hint the user signed in with as an interim label; the real
+    // display profile is fetched from /auth/me right after (names, never UUIDs).
+    persist({ session, tokens, identityHint });
+    await Promise.all([
+      loadProfile(tokens?.accessToken),
+      refreshAuthFacts(session?.principalId ?? null),
+    ]);
+  };
+
+  const login = async (identityHint, password) => {
+    const r = await auth.login(identityHint, password);
+    if (r.ok === true) {
+      await establishSession(r.session, r.tokens, identityHint);
+    }
+    return r; // { ok:true } | { ok:'mfa', challengeToken } | { ok:false, error }
+  };
+
+  // Complete a pending MFA challenge (the second step after login returned
+  // { ok:'mfa', challengeToken }). `factor` is the second-factor kind ('totp' by
+  // default, or 'recovery_code' when the user signs in with a saved recovery code).
+  // `identityHint` is threaded through from the login step so the same interim label
+  // is kept when the session is established. On success the session is established
+  // exactly as a plain login would.
+  //
+  // NOTE (bug fix): the caller used to pass `identityHint` in the `factor` slot, so a
+  // TOTP verify sent `factor: <username>` — the recovery-code work needs a real
+  // `factor`, so it is now the third positional arg (default 'totp') and identityHint
+  // is fourth. When the login was completed with a recovery code the server returns
+  // `mfaRecoveryUsed:true`; we surface it AND flip the app into the forced re-enroll
+  // flow immediately (the enforcement gate would 403 the very next request anyway).
+  const completeMfa = async (challengeToken, code, factor = 'totp', identityHint) => {
+    const r = await auth.completeMfa(challengeToken, code, factor);
+    if (r.ok === true) {
+      await establishSession(r.session, r.tokens, identityHint);
+      if (r.mfaRecoveryUsed === true) markReenroll();
+      return { ok: true, mfaRecoveryUsed: r.mfaRecoveryUsed === true };
+    }
+    return r; // { ok:false, error }
+  };
+
+  const logout = async () => {
+    const sessionId = state?.session?.sessionId;
+    persist(null); // clear locally first — the UI must never wait on the server
+    setProfile(null);
+    setAuthFacts(null); // fail-closed: no session -> no cached facts to (mis)trust
+    clearReenroll(); // a fresh sign-in starts unrestricted
+    await auth.logout(sessionId);
+  };
+
+  // On mount (e.g. a page refresh that rehydrated a persisted session), fetch the
+  // profile + the auth-facts projection once for the stored session. Runs only when we
+  // have a token but haven't fetched yet (profile === null / authFacts === null).
+  useEffect(() => {
+    const token = state?.tokens?.accessToken;
+    if (token && profile === null) void loadProfile(token);
+    if (token && authFacts === null) void refreshAuthFacts(principalOf(state));
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  // Phase E slice 2 (ADR-0011 frontend twin) — POKE `getAuthFacts` periodically + on
+  // window focus so the SDK's own version-staleness check (client.ts's
+  // `isProjectionFresh`, driven by shieldTransport's `currentVersion()`) actually RUNS.
+  // The SDK does NOT poll itself; without a repeated caller a mid-session permission
+  // change (or a version bump from any cause) would sit unnoticed until the next
+  // full page reload. This does NOT replace the login/mount fetches above — it adds a
+  // focus listener + a light interval on top, and fires regardless of `authFacts`
+  // being null-or-not (the whole point is to re-check an already-fetched, possibly now
+  // STALE projection — the mount effect's `authFacts === null` guard only covers the
+  // "never fetched yet" case).
+  //
+  // No-flicker: `refreshAuthFacts` only calls `setAuthFacts` on a resolved projection —
+  // it never resets to `null` first. `shield.getAuthFacts` is itself fail-closed and
+  // NEVER throws (see the refreshAuthFacts doc above): a transient version-probe/fetch
+  // failure resolves the last-good (now-marked-stale-internally) or empty projection,
+  // never a rejected promise — so there is nothing here to catch, and the UI never
+  // blanks out mid-poll.
+  useEffect(() => {
+    const token = state?.tokens?.accessToken;
+    if (!token) return undefined; // not authenticated — nothing to keep fresh
+
+    const principalId = principalOf(state);
+    const poke = () => {
+      if (principalId) void refreshAuthFacts(principalId);
+    };
+
+    const onFocus = () => poke();
+    window.addEventListener('focus', onFocus);
+
+    const POLL_MS = 60_000; // cheap: each tick is one version-probe request unless stale
+    const intervalId = setInterval(poke, POLL_MS);
+
+    return () => {
+      window.removeEventListener('focus', onFocus);
+      clearInterval(intervalId);
+    };
+    // Re-armed whenever the token/principal changes (login/logout/refresh) so a stale
+    // closure never keeps polling for a signed-out or since-replaced session.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [state?.tokens?.accessToken, state?.session?.principalId]);
+
+  const value = useMemo(
+    () => ({
+      session: state?.session ?? null,
+      tokens: state?.tokens ?? null,
+      // The human-readable label the user signed in with (never the raw UUID).
+      identityHint: state?.identityHint ?? null,
+      // The signed-in user's display profile (name/email/company/roles) or null.
+      profile,
+      // Re-fetch the display profile for the current token (used after a self-service
+      // profile edit so the header/user card reflects the new name/email at once).
+      refreshProfile,
+      isAuthenticated: isAuthenticated(state),
+      // True while the current session is restricted to re-securing the account
+      // (recovery-code login). The router forces the re-enroll screen until cleared.
+      mustReenroll,
+      // Clear the restriction — called by the re-enroll screen after a device confirm
+      // succeeds (the server has already flipped the bound claim; this releases the UI).
+      clearReenroll,
+      login,
+      // Complete a pending MFA challenge (second factor) — same session-establish
+      // path as login. Consumed by the Login page's MFA code step.
+      completeMfa,
+      logout,
+      // The shared auth service — exposed so the PUBLIC pre-auth pages
+      // (ForgotPassword / ResetPassword) can call requestReset / resetPassword
+      // through the SAME injected web http client (no bespoke client per page).
+      auth,
+      // The shared identity service (for protected calls) — same injected client.
+      identity,
+      // The shared audit-log service (audit viewer) — same injected web http client.
+      audit,
+      // The shared self-scoped account service (change-password today; profile/MFA
+      // later) — same injected web http client.
+      account,
+      // The @astram/sdk ShieldClient (Phase E slice 1) — exposed for any page that needs
+      // direct access (e.g. a forced re-fetch). Most call sites should prefer `useCan`.
+      shield,
+      // The caller's raw auth-facts projection, or `null` before the first fetch
+      // resolves. Most call sites should prefer `useCan(key)` below; exposed for
+      // completeness / debugging.
+      authFacts,
+      // `can(permissionKey)` — is the given permission key present as an ALLOWED fact in
+      // the current projection? FAIL-CLOSED: an absent fact, OR no projection fetched
+      // yet (`authFacts === null`), both read as `false` (can't) — never optimistically
+      // `true`. This is a UX convenience only: hides/disables nav + page gates; it is
+      // NEVER the security boundary — the server's decide() on every @Classified route
+      // is the real enforcement (see shieldTransport.js's header doc).
+      can: (permissionKey) =>
+        Boolean(
+          authFacts?.facts?.some((f) => f.action === permissionKey && f.allowed === true),
+        ),
+    }),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [state, auth, identity, audit, account, shield, profile, mustReenroll, authFacts],
+  );
+
+  return <AuthContext.Provider value={value}>{children}</AuthContext.Provider>;
+}
+
+// Colocating the consumer hook with its Provider is the standard React pattern;
+// the fast-refresh "only export components" rule is advisory here (moving useAuth
+// to its own file would churn 19 import sites for no runtime benefit).
+// eslint-disable-next-line react-refresh/only-export-components
+export function useAuth() {
+  const ctx = useContext(AuthContext);
+  if (!ctx) throw new Error('useAuth must be used within <AuthProvider>');
+  return ctx;
+}
+
+/**
+ * `useCan(permissionKey)` — Phase E slice 1: is the given permission key an ALLOWED
+ * fact in the caller's current auth-facts projection? Reads `can` off `useAuth()`, so
+ * it always sees the LATEST projection (re-renders when it changes).
+ *
+ * FAIL-CLOSED: `false` whenever the key is absent from the projection OR no projection
+ * has been fetched yet (loading) — never optimistically `true`. This is a UX
+ * convenience ONLY (hide/disable nav + page gates); it is NEVER the security boundary —
+ * a tampered/stale answer here just means the user sees an action they can't use, and
+ * the server's decide() on the underlying @Classified route still 403s it.
+ *
+ * @param {string} permissionKey
+ * @returns {boolean}
+ */
+// eslint-disable-next-line react-refresh/only-export-components
+export function useCan(permissionKey) {
+  const { can } = useAuth();
+  return can(permissionKey);
+}

package/template/frontend/src/components/ConfirmDialog.jsx

@@ -0,0 +1,92 @@
+/**
+ * ConfirmDialog — a small, themed confirm gate for SENSITIVE / irreversible actions
+ * (disable 2FA, revoke, delete, …). Built on the shadcn AlertDialog primitive
+ * (`alert-dialog.tsx`) — the semantic confirm role — so it inherits the app's dialog
+ * theming in both light and dark and announces as an alert dialog to assistive tech.
+ * The action fires ONLY from the confirm handler — never on the initial click.
+ *
+ * Controlled: the parent owns `open` + the busy state. While `busy` is true both
+ * buttons are disabled so a slow request can't be double-fired or cancelled mid-flight.
+ * `children` renders BETWEEN the message and the buttons (e.g. a required code input),
+ * so the confirm can gather one last piece of input before committing.
+ */
+import { Loader2 } from 'lucide-react';
+import { cn } from '@/lib/utils';
+import { buttonVariants } from '@/components/ui/button';
+import {
+  AlertDialog,
+  AlertDialogCancel,
+  AlertDialogContent,
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogHeader,
+  AlertDialogTitle,
+} from '@/components/ui/alert-dialog';
+
+export default function ConfirmDialog({
+  open,
+  title = 'Are you sure?',
+  message,
+  confirmLabel = 'Confirm',
+  cancelLabel = 'Cancel',
+  destructive = false,
+  busy = false,
+  onConfirm,
+  onCancel,
+  children,
+}) {
+  return (
+    <AlertDialog
+      open={open}
+      onOpenChange={(next) => {
+        // Only allow closing via the dialog's own affordances when we're not mid-request.
+        if (!next && !busy) onCancel?.();
+      }}
+    >
+      <AlertDialogContent>
+        {/* A form wrapper so pressing Enter in a child input submits (fires onConfirm),
+            matching native dialog behavior. The confirm button is type="submit". */}
+        <form
+          onSubmit={(e) => {
+            e.preventDefault();
+            if (!busy) onConfirm?.();
+          }}
+        >
+          <AlertDialogHeader>
+            <AlertDialogTitle>{title}</AlertDialogTitle>
+            {message && <AlertDialogDescription>{message}</AlertDialogDescription>}
+          </AlertDialogHeader>
+
+          {/* Space the child input from the header above and the buttons below
+              so the field isn't flush against the footer. */}
+          {children && <div className="mt-4 mb-6">{children}</div>}
+
+          <AlertDialogFooter className="mt-4">
+            <AlertDialogCancel
+              type="button"
+              onClick={onCancel}
+              disabled={busy}
+              className="w-full sm:w-auto"
+            >
+              {cancelLabel}
+            </AlertDialogCancel>
+            {/* Use a plain submit button (not AlertDialogAction) so the confirm fires
+                via the form's onSubmit and busy-guard, not an auto-close. Styled with
+                buttonVariants so it reads as a real destructive-capable primary. */}
+            <button
+              type="submit"
+              disabled={busy}
+              className={cn(
+                buttonVariants({ variant: destructive ? 'destructive' : 'default' }),
+                'w-full sm:w-auto',
+              )}
+            >
+              {busy && <Loader2 className="size-4 animate-spin" />}
+              {confirmLabel}
+            </button>
+          </AlertDialogFooter>
+        </form>
+      </AlertDialogContent>
+    </AlertDialog>
+  );
+}

package/template/frontend/src/components/EntityFormModal.jsx

@@ -0,0 +1,154 @@
+/**
+ * EntityFormModal — the routed-modal overlay for the identity Add/Edit forms. Built on
+ * the shadcn Dialog primitive (`dialog.tsx`) so it inherits the app's light/dark
+ * theming, focus trap, and Escape-to-close.
+ *
+ * This is the "routed-modal" pattern: the modal is rendered by an Add/Edit CHILD ROUTE
+ * (e.g. /companies/add, /companies/edit/:uuid) under the list's layout, so the URL is
+ * bookmarkable and the back button closes it — while looking like a lightweight overlay.
+ * The list stays mounted behind it.
+ *
+ * The `children` are the form fields; the form wrapper submits on Enter (the primary is
+ * `type="submit"`), matching native dialog behavior. `busy` disables both buttons so a
+ * slow request can't be double-fired or cancelled mid-flight.
+ *
+ * Props:
+ *   title        — dialog heading
+ *   description  — optional sub-line
+ *   open         — controlled open state (the child route passes `true`)
+ *   onClose      — () => void   (Escape / scrim / Cancel → typically navigate(-1))
+ *   onSubmit     — () => void   (fired by Enter or the primary button; the parent runs the API)
+ *   submitLabel  — primary button label (default "Save")
+ *   cancelLabel  — ghost cancel label (default "Cancel")
+ *   busy         — request in flight → buttons disabled
+ *   error        — an error string shown above the buttons
+ *   contentClassName — optional override for the dialog width (default a compact form);
+ *                      wider forms (e.g. the user edit page with its assignments editor)
+ *                      pass a roomier max-width.
+ *   expandable   — show the OCA-style expand/collapse (full-screen) toggle in the header
+ *                  (default true). Full-screen is the natural escape for the roomier
+ *                  assignments modal; small forms keep it but it's harmless.
+ *   children     — the form fields
+ *
+ * Overflow containment: the DialogContent is a CSS grid, and the form → body chain all
+ * carry `min-w-0` so a wide descendant (the assignments posting table) can shrink below
+ * its content width — which lets that table's own `overflow-x-auto` wrapper scroll it
+ * INSIDE the modal instead of forcing the modal past its `max-w`. The body also scrolls
+ * vertically (`overflow-y-auto` + a max-height) so a tall assignments editor never spills.
+ *
+ * Full-screen: the expand toggle flips a local `expanded` flag; when set, the content
+ * overrides its centered/bounded classes to fill the viewport (`inset-0 w-screen h-screen
+ * max-w-none rounded-none`, no translate) — the OCA `.dsa-modal--full` treatment.
+ */
+import { useState } from 'react';
+import { Loader2, Maximize2, Minimize2 } from 'lucide-react';
+import { cn } from '@/lib/utils';
+import { Button } from '@/components/ui/button';
+import { Alert, AlertDescription } from '@/components/ui/alert';
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from '@/components/ui/dialog';
+
+export default function EntityFormModal({
+  title,
+  description,
+  open,
+  onClose,
+  onSubmit,
+  submitLabel = 'Save',
+  cancelLabel = 'Cancel',
+  busy = false,
+  error = '',
+  contentClassName = 'sm:max-w-md',
+  expandable = true,
+  children,
+}) {
+  const [expanded, setExpanded] = useState(false);
+
+  return (
+    <Dialog
+      open={open}
+      onOpenChange={(next) => {
+        // Close only via the dialog's own affordances, and never mid-request.
+        if (!next && !busy) onClose?.();
+      }}
+    >
+      <DialogContent
+        showCloseButton={!busy}
+        className={cn(
+          // `min-w-0` lets the grid's content track shrink below a wide child's
+          // intrinsic width (the grid min-width:auto trap), so the inner posting
+          // table's overflow-x-auto is what absorbs extra width — the modal never
+          // exceeds its max-width. `overflow-hidden` clips any residual bleed.
+          'flex max-h-[calc(100vh-4rem)] min-w-0 flex-col overflow-hidden',
+          expanded
+            ? // OCA `.dsa-modal--full`: fill the viewport, square corners, no offset.
+              'inset-0 h-screen max-h-screen w-screen max-w-none translate-x-0 translate-y-0 rounded-none sm:max-w-none'
+            : contentClassName,
+        )}
+      >
+        {/* A form wrapper so Enter in any field submits (fires onSubmit); the primary
+            button is type="submit". `min-w-0` + flex-col so the body can scroll and the
+            wide posting table shrinks rather than stretching the modal. */}
+        <form
+          onSubmit={(e) => {
+            e.preventDefault();
+            if (!busy) onSubmit?.();
+          }}
+          className="flex min-w-0 flex-1 flex-col overflow-hidden"
+        >
+          <DialogHeader>
+            <DialogTitle>{title}</DialogTitle>
+            {description && <DialogDescription>{description}</DialogDescription>}
+          </DialogHeader>
+
+          {/* Scrollable body: `min-w-0` propagates the shrink to children; `overflow-y-auto`
+              keeps a tall assignments editor inside the modal. */}
+          <div className="mt-4 mb-6 min-w-0 flex-1 space-y-4 overflow-y-auto">
+            {children}
+            {error && (
+              <Alert variant="destructive">
+                <AlertDescription>{error}</AlertDescription>
+              </Alert>
+            )}
+          </div>
+
+          <DialogFooter>
+            <Button
+              type="button"
+              variant="ghost"
+              onClick={onClose}
+              disabled={busy}
+              className="w-full sm:w-auto"
+            >
+              {cancelLabel}
+            </Button>
+            <Button type="submit" disabled={busy} className="w-full sm:w-auto">
+              {busy && <Loader2 className="size-4 animate-spin" />}
+              {submitLabel}
+            </Button>
+          </DialogFooter>
+        </form>
+
+        {/* Expand / collapse (full-screen) toggle — sits to the LEFT of the Dialog's own
+            close X (which is `absolute top-4 right-4`). OCA's modal expand affordance. */}
+        {expandable && (
+          <button
+            type="button"
+            onClick={() => setExpanded((v) => !v)}
+            aria-label={expanded ? 'Exit full screen' : 'Expand to full screen'}
+            title={expanded ? 'Exit full screen' : 'Expand to full screen'}
+            className="ring-offset-background focus:ring-ring absolute top-4 right-11 rounded-xs opacity-70 transition-opacity hover:opacity-100 focus:ring-2 focus:ring-offset-2 focus:outline-hidden disabled:pointer-events-none"
+          >
+            {expanded ? <Minimize2 className="size-4" /> : <Maximize2 className="size-4" />}
+          </button>
+        )}
+      </DialogContent>
+    </Dialog>
+  );
+}