cortena-ui 1.4.2 → 1.6.0

package/src/components/app-shell.tsx

@@ -0,0 +1,502 @@
+"use client";
+
+import { getMark } from "cortena-design/marks";
+import { CircleQuestionMark, LogOut, Monitor, Moon, Settings, Sun, User } from "lucide-react";
+import * as React from "react";
+import { Avatar, AvatarFallback, AvatarImage } from "@/components/avatar";
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuSeparator,
+  DropdownMenuTrigger,
+} from "@/components/dropdown-menu";
+import { type CortenaTheme, useCortenaTheme } from "@/hooks/use-cortena-theme";
+import { cn } from "@/lib/cn";
+
+/**
+ * AppShell — the chrome every Cortena extension wears, so that moving between
+ * two of them is moving between two screens of one product rather than between
+ * two applications (how-to-create-a-cortena-extension §9, audit rule P-10).
+ *
+ * Four things are fixed, and they are fixed because an extension that places
+ * them itself places them somewhere slightly different:
+ *
+ *   top left      the extension's name and its registered mark, 20px inside a
+ *                 32px square. The mark comes from `cortena-design/marks` by
+ *                 `extension.id` — the same file the Apps tile, the MCP app
+ *                 card, the agent pop-up pill and the favicon draw (§9.1), not
+ *                 an SVG in this app's web/public.
+ *   top right     the avatar menu. It is the ONLY settings entry point:
+ *                 Profile, Settings, Log out. Not a gear in a sidebar as well
+ *                 (§9.2).
+ *   bottom right  one fixed cluster, theme toggle then help button, left to
+ *                 right, 24px from both viewport edges, 40px each, 12px apart
+ *                 (§9.3). The agent pop-up pill stacks above it.
+ *   everywhere    the theme is `useCortenaTheme`, so the choice persists and a
+ *                 host `postMessage` still wins.
+ *
+ * The help panel itself is EXTBP-24 and does not exist yet, so `helpPanel` is a
+ * slot: pass a node or a render function and the shell owns the button, the
+ * open state and the corner. When HelpPanel ships, `help.source` is what it
+ * reads — the extension's functional document (§12) — and the default panel
+ * replaces the slot without a call-site change.
+ */
+
+/* ── the mark ────────────────────────────────────────────────────────────── */
+
+export interface BrandMarkProps extends Omit<React.ComponentProps<"span">, "children"> {
+  /** Registered mark id — what the extension puts in `x-cortena.icon`. */
+  id: string;
+  /** The extension name. Labels the mark, and supplies the fallback initial. */
+  name: string;
+  /** Rendered size of the glyph in pixels. 20 in the shell, 24 in the Apps tile, 16 on the pill. */
+  size?: number;
+  /** Set when the mark is decorative because the name is already beside it. */
+  decorative?: boolean;
+}
+
+/**
+ * The presentation attributes a mark's root may carry into the DOM.
+ *
+ * The same list cortena-design's `validateMarkup` enforces at build time,
+ * repeated here because this component spreads values that came from a
+ * package the consumer resolves — an older `cortena-design`, a patched one, a
+ * hand-edited `dist/marks.js` — straight onto an element.
+ */
+const MARK_ROOT_ATTRIBUTES: readonly string[] = [
+  "fill",
+  "stroke",
+  "stroke-width",
+  "stroke-linecap",
+  "stroke-linejoin",
+  "transform",
+  "opacity",
+];
+
+/** `root`, with anything outside the allow-list dropped. */
+function safeRootAttributes(root: Record<string, string> | undefined): Record<string, string> {
+  const safe: Record<string, string> = {};
+  for (const name of MARK_ROOT_ATTRIBUTES) {
+    const value = root?.[name];
+    if (typeof value === "string") {
+      safe[name] = value;
+    }
+  }
+  return safe;
+}
+
+/**
+ * The registered mark for `id`, or the extension's initial when nothing is
+ * registered. The fallback matters: an unregistered id used to render an empty
+ * box, which reads as a broken image rather than as "this extension has not
+ * registered a mark yet".
+ */
+function BrandMark({ className, id, name, size = 20, decorative, ...props }: BrandMarkProps) {
+  const mark = getMark(id);
+  const label = decorative ? undefined : name;
+  return (
+    <span
+      data-slot="brand-mark"
+      data-mark={mark ? mark.id : "fallback"}
+      className={cn("inline-flex shrink-0 items-center justify-center", className)}
+      style={{ width: size, height: size }}
+      {...props}
+    >
+      {mark ? (
+        <svg
+          viewBox={mark.viewBox}
+          width={size}
+          height={size}
+          role={decorative ? undefined : "img"}
+          aria-label={label}
+          aria-hidden={decorative ? true : undefined}
+          focusable="false"
+          // The body is generated by cortena-design's build from a file in this
+          // monorepo, where `validateMarkup` accepts an allow-list of elements
+          // and attributes — no <script>, <style>, <use>, <image> or
+          // <foreignObject>, no href and no on* handler — and paints only in
+          // currentColor. It is not user input, and it is not sanitised here:
+          // the guarantee is the build's, so a mark that would need sanitising
+          // fails `pnpm build` instead of being quietly cleaned up.
+          dangerouslySetInnerHTML={{ __html: mark.body }}
+          // `root` is filtered again on the way in. A consumer can be running
+          // against an older or hand-edited `cortena-design/marks`, and this
+          // spread is the one place its values reach the DOM as attributes.
+          {...safeRootAttributes(mark.root)}
+        />
+      ) : (
+        <span
+          aria-label={label}
+          aria-hidden={decorative ? true : undefined}
+          role={decorative ? undefined : "img"}
+          className={cn(
+            "font-display font-bold uppercase leading-none",
+            "text-[length:var(--ds-text-caption-lg)]",
+          )}
+        >
+          {name.trim().charAt(0) || "?"}
+        </span>
+      )}
+    </span>
+  );
+}
+
+/* ── bottom-right cluster ────────────────────────────────────────────────── */
+
+export interface BottomRightClusterProps extends React.ComponentProps<"div"> {
+  /** The agent pop-up pill (§17). Stacks above the row, never beside it. */
+  agentSlot?: React.ReactNode;
+}
+
+/**
+ * The one fixed container in the bottom-right corner. It exists so that no
+ * extension positions a floating control itself — that is how a third one
+ * appears and covers one of the first two.
+ */
+function BottomRightCluster({ className, agentSlot, children, ...props }: BottomRightClusterProps) {
+  return (
+    <div
+      data-slot="bottom-right-cluster"
+      className={cn("fixed right-6 bottom-6 z-40 flex flex-col items-end gap-3", className)}
+      {...props}
+    >
+      {agentSlot ? (
+        <div data-slot="bottom-right-cluster-agent" className="flex items-center justify-end">
+          {agentSlot}
+        </div>
+      ) : null}
+      <div data-slot="bottom-right-cluster-row" className="flex items-center gap-3">
+        {children}
+      </div>
+    </div>
+  );
+}
+
+/** The cluster's distance from both viewport edges (§9.3). `right-6` / `bottom-6`. */
+const CLUSTER_INSET = 24;
+/** What the help panel leaves between itself and the cluster. */
+const HELP_PANEL_GAP = 12;
+
+const clusterButtonClassName = [
+  "inline-flex size-10 shrink-0 items-center justify-center rounded-[var(--ds-radius-full)]",
+  "border border-[var(--ds-border)] bg-[var(--ds-card)] text-[color:var(--ds-foreground)]",
+  "shadow-[var(--ds-shadow-md)] outline-none",
+  "transition-colors duration-[var(--ds-duration-fast)] ease-[var(--ds-ease-out)]",
+  "hover:bg-[var(--ds-hover)]",
+  "focus-visible:ring-2 focus-visible:ring-[var(--ds-ring)] focus-visible:ring-offset-2",
+  "focus-visible:ring-offset-[var(--ds-background)]",
+].join(" ");
+
+/** light → dark → system → light. Three states, one control, no menu to open. */
+const THEME_ORDER: readonly CortenaTheme[] = ["light", "dark", "system"];
+
+const THEME_LABEL: Record<CortenaTheme, string> = {
+  light: "Light",
+  dark: "Dark",
+  system: "System",
+};
+
+export interface ThemeToggleProps extends Omit<React.ComponentProps<"button">, "onClick"> {
+  /** localStorage key, forwarded to `useCortenaTheme`. */
+  storageKey?: string;
+}
+
+/**
+ * The theme selector. It lives here rather than in the avatar menu because a
+ * user changing theme is usually reacting to the room they are in, and that is
+ * a one-tap decision, not a settings visit.
+ */
+function ThemeToggle({ className, storageKey, ...props }: ThemeToggleProps) {
+  const { theme, resolvedTheme, setTheme } = useCortenaTheme(
+    storageKey === undefined ? {} : { storageKey },
+  );
+  const next = THEME_ORDER[(THEME_ORDER.indexOf(theme) + 1) % THEME_ORDER.length] ?? "light";
+  const Icon = theme === "system" ? Monitor : theme === "dark" ? Moon : Sun;
+  return (
+    <button
+      type="button"
+      data-slot="theme-toggle"
+      data-theme-choice={theme}
+      data-theme-resolved={resolvedTheme}
+      aria-label={`Theme: ${THEME_LABEL[theme]}. Switch to ${THEME_LABEL[next].toLowerCase()}.`}
+      className={cn(clusterButtonClassName, className)}
+      onClick={() => setTheme(next)}
+      {...props}
+    >
+      <Icon className="size-5" aria-hidden />
+    </button>
+  );
+}
+
+/** The id the shell gives its help region, and the button's `aria-controls`. */
+export const HELP_PANEL_ID = "cortena-help-panel";
+
+export interface HelpButtonProps extends React.ComponentProps<"button"> {
+  /** Whether the panel it controls is open. */
+  open?: boolean;
+}
+
+/** The help affordance. Right of the theme toggle, always — order is fixed (§9.3). */
+function HelpButton({ className, open, ...props }: HelpButtonProps) {
+  return (
+    <button
+      type="button"
+      data-slot="help-button"
+      aria-label="Help"
+      aria-expanded={open}
+      // `aria-expanded` alone says "something is open" without saying what.
+      // A screen reader user then has to go and find it.
+      aria-controls={HELP_PANEL_ID}
+      data-open={open ? "" : undefined}
+      className={cn(clusterButtonClassName, open && "bg-[var(--ds-hover)]", className)}
+      {...props}
+    >
+      <CircleQuestionMark className="size-5" aria-hidden />
+    </button>
+  );
+}
+
+/* ── the shell ───────────────────────────────────────────────────────────── */
+
+export interface AppShellExtension {
+  /** Registered mark id, from `x-cortena.icon` in the OpenAPI document. */
+  id: string;
+  /** Display name. Also the first half of the document title, "<name> · Cortena". */
+  name: string;
+}
+
+export interface AppShellUser {
+  name: string;
+  avatarUrl?: string;
+}
+
+export interface AppShellHelp {
+  /**
+   * The extension's functional document — the thing the help panel answers
+   * from (§12). Giving that document a runtime consumer is the point: a stale
+   * doc becomes a visibly wrong help panel rather than a file nobody opens.
+   */
+  source: string;
+}
+
+export interface HelpPanelSlotProps {
+  open: boolean;
+  source?: string;
+  onClose: () => void;
+}
+
+export interface AppShellProps extends Omit<React.ComponentProps<"div">, "title"> {
+  extension: AppShellExtension;
+  user: AppShellUser;
+  /** Opens the extension's own settings route. The avatar menu is the only way in. */
+  onSettings?: () => void;
+  onProfile?: () => void;
+  onLogout?: () => void;
+  help?: AppShellHelp;
+  /**
+   * The help panel, until HelpPanel ships (EXTBP-24). A render function gets
+   * the open state and owns its own markup; a node is mounted in a right-hand
+   * region while open.
+   */
+  helpPanel?: React.ReactNode | ((props: HelpPanelSlotProps) => React.ReactNode);
+  /** The agent pop-up pill. Stacks above the bottom-right cluster. */
+  agentSlot?: React.ReactNode;
+  /** localStorage key for the theme choice, forwarded to `useCortenaTheme`. */
+  themeStorageKey?: string;
+}
+
+function AppShell({
+  className,
+  extension,
+  user,
+  onSettings,
+  onProfile,
+  onLogout,
+  help,
+  helpPanel,
+  agentSlot,
+  themeStorageKey,
+  children,
+  ...props
+}: AppShellProps) {
+  const [helpOpen, setHelpOpen] = React.useState(false);
+  const helpButtonRef = React.useRef<HTMLButtonElement>(null);
+  const closeHelp = React.useCallback(() => {
+    setHelpOpen(false);
+    // Focus goes back where it came from. A panel closed with Escape or its
+    // own X otherwise left focus on a removed node, which the browser resets
+    // to <body> — the next Tab starts from the top of the page, and a
+    // keyboard user has to walk the whole shell to get back.
+    helpButtonRef.current?.focus();
+  }, []);
+
+  /**
+   * The help panel stops 12px above the bottom-right cluster, so the button
+   * that opened it stays visible and clickable. The gap was hard-coded at
+   * 76px — one 40px control plus the two margins — and the cluster is not
+   * always that tall: the agent pop-up pill stacks ABOVE the row, which makes
+   * it 92px, and the panel then covered the pill it was sitting on.
+   */
+  const clusterRef = React.useRef<HTMLDivElement>(null);
+  const [clusterHeight, setClusterHeight] = React.useState(40);
+  React.useEffect(() => {
+    const el = clusterRef.current;
+    if (!el || typeof ResizeObserver === "undefined") {
+      return;
+    }
+    const measure = () => setClusterHeight(el.getBoundingClientRect().height);
+    measure();
+    const observer = new ResizeObserver(measure);
+    observer.observe(el);
+    return () => observer.disconnect();
+  }, [agentSlot, helpOpen]);
+  const hasHelp = help !== undefined || helpPanel !== undefined;
+  const panel =
+    typeof helpPanel === "function"
+      ? helpPanel({ open: helpOpen, source: help?.source, onClose: closeHelp })
+      : helpOpen
+        ? helpPanel
+        : null;
+
+  return (
+    <div
+      data-slot="app-shell"
+      className={cn(
+        "flex min-h-screen w-full flex-col bg-[var(--ds-background)] text-[color:var(--ds-foreground)]",
+        className,
+      )}
+      {...props}
+    >
+      <header
+        data-slot="app-shell-header"
+        className={cn(
+          "sticky top-0 z-30 flex h-16 w-full shrink-0 items-center justify-between gap-3",
+          "border-b border-[var(--ds-border-subtle)] bg-[var(--ds-background)] px-4 sm:px-6",
+        )}
+      >
+        <div data-slot="app-shell-brand" className="flex min-w-0 items-center gap-2.5">
+          <span
+            data-slot="app-shell-brand-square"
+            className={cn(
+              "flex size-8 shrink-0 items-center justify-center rounded-[var(--ds-radius-md)]",
+              "bg-[var(--ds-primary-soft)] text-[color:var(--ds-primary)]",
+            )}
+          >
+            <BrandMark id={extension.id} name={extension.name} size={20} decorative />
+          </span>
+          <span
+            data-slot="app-shell-brand-name"
+            className={cn(
+              "truncate font-display text-[length:var(--ds-text-body-md)] font-bold",
+              "leading-[var(--ds-text-body-md--line-height)] text-[color:var(--ds-foreground)]",
+            )}
+          >
+            {extension.name}
+          </span>
+        </div>
+
+        <DropdownMenu>
+          <DropdownMenuTrigger
+            data-slot="app-shell-avatar-trigger"
+            aria-label={`Account: ${user.name}`}
+            className={cn(
+              "flex shrink-0 items-center rounded-[var(--ds-radius-full)] outline-none",
+              "focus-visible:ring-2 focus-visible:ring-[var(--ds-ring)] focus-visible:ring-offset-2",
+              "focus-visible:ring-offset-[var(--ds-background)]",
+            )}
+          >
+            <Avatar>
+              {user.avatarUrl ? <AvatarImage src={user.avatarUrl} alt="" /> : null}
+              <AvatarFallback>{initials(user.name)}</AvatarFallback>
+            </Avatar>
+          </DropdownMenuTrigger>
+          {/* Profile, Settings, Log out. Nothing else, and no second settings
+              entry point anywhere in the extension (§9.2). */}
+          <DropdownMenuContent align="end" sideOffset={8} className="min-w-48">
+            <DropdownMenuItem
+              data-item="profile"
+              disabled={!onProfile}
+              onClick={onProfile}
+            >
+              <User /> Profile
+            </DropdownMenuItem>
+            <DropdownMenuItem
+              data-item="settings"
+              disabled={!onSettings}
+              onClick={onSettings}
+            >
+              <Settings /> Settings
+            </DropdownMenuItem>
+            <DropdownMenuSeparator />
+            <DropdownMenuItem
+              data-item="logout"
+              variant="destructive"
+              disabled={!onLogout}
+              onClick={onLogout}
+            >
+              <LogOut /> Log out
+            </DropdownMenuItem>
+          </DropdownMenuContent>
+        </DropdownMenu>
+      </header>
+
+      <main data-slot="app-shell-main" className="min-w-0 flex-1">
+        {children}
+      </main>
+
+      {panel ? (
+        <aside
+          id={HELP_PANEL_ID}
+          data-slot="app-shell-help-panel"
+          aria-label={`${extension.name} help`}
+          // Measured, not assumed: 24px of viewport margin, the cluster the
+          // panel must clear, and 12px between the two.
+          style={{ bottom: CLUSTER_INSET + clusterHeight + HELP_PANEL_GAP }}
+          className={cn(
+            // Anchored to the same corner. A panel that covers its own trigger
+            // leaves no way back except Escape.
+            "fixed top-6 right-6 z-40 flex w-[min(24rem,calc(100vw-3rem))] flex-col",
+            "overflow-hidden rounded-[var(--ds-radius-lg)] border border-[var(--ds-border)]",
+            "bg-[var(--ds-card)] shadow-[var(--ds-shadow-lg)]",
+          )}
+        >
+          {panel}
+        </aside>
+      ) : null}
+
+      <BottomRightCluster ref={clusterRef} agentSlot={agentSlot}>
+        <ThemeToggle storageKey={themeStorageKey} />
+        {hasHelp ? (
+          <HelpButton
+            ref={helpButtonRef}
+            open={helpOpen}
+            onClick={() => setHelpOpen((open) => !open)}
+          />
+        ) : null}
+      </BottomRightCluster>
+    </div>
+  );
+}
+
+/** One or two letters. Two words give two initials; anything else gives one. */
+function initials(name: string): string {
+  const words = name.trim().split(/\s+/).filter(Boolean);
+  if (words.length === 0) {
+    return "?";
+  }
+  const first = words[0]?.charAt(0) ?? "";
+  const last = words.length > 1 ? (words.at(-1)?.charAt(0) ?? "") : "";
+  return (first + last).toUpperCase();
+}
+
+/**
+ * `<title>` for an extension: the extension first, because that is what
+ * distinguishes one tab from another, and the product second so a row of tabs
+ * reads as one product (§9.5, audit rule P-38).
+ */
+function documentTitle(extensionName: string, page?: string): string {
+  return page ? `${page} · ${extensionName} · Cortena` : `${extensionName} · Cortena`;
+}
+
+export { AppShell, BottomRightCluster, BrandMark, HelpButton, ThemeToggle, documentTitle };