Ekklesia/surfaces/shell/src/browser/ShellLayout.tsx

import { designToken } from "@ekklesia/design-tokens";
import {
  type KeyboardEvent,
  type ReactElement,
  type ReactNode,
  type RefObject,
  useCallback,
  useEffect,
  useLayoutEffect,
  useRef,
  useState,
  useSyncExternalStore,
} from "react";
import type { DashboardRoute } from "../dashboard-routes.js";
import type { DashboardNavigation, EkklesiaHostConfig } from "../host-protocol.js";
import { AccountMenu } from "./AccountMenu.js";
import { DevicePanel } from "./DevicePanel.js";
import type { HostHistory } from "./host-history.js";
import type { HostViewport } from "./host-viewport.js";
import { useNavTooltip } from "./NavTooltip.js";
import {
  controlHeight,
  NavigationList,
  type NavigationPresentation,
  ShellBrand,
} from "./ShellNavigation.js";
import { ShellIcon } from "./shell-icons.js";
import { SHELL_STYLESHEET } from "./shell-styles.js";
import type { SidebarMode, SidebarPreference } from "./sidebar-preference.js";

const SIDEBAR_NAV_ID = "ekklesia-sidebar-navigation";
const DRAWER_ID = "ekklesia-navigation-drawer";
const DRAWER_NAV_ID = "ekklesia-drawer-navigation";
const SIDEBAR_WIDTH: Record<SidebarMode, string> = { collapsed: "4.5rem", expanded: "16rem" };

const FOCUSABLE =
  'a[href], button:not([disabled]), input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])';

export interface ShellLayoutProps {
  readonly config: EkklesiaHostConfig;
  readonly history: HostHistory;
  readonly navigation: DashboardNavigation;
  readonly route: DashboardRoute;
  readonly viewport: HostViewport;
  readonly sidebarPreference: SidebarPreference;
  readonly mainRef: RefObject<HTMLElement | null>;
  readonly pageTitle: string | undefined;
  readonly onSignOut: () => void;
  readonly children: ReactNode;
}

function SidebarToggle(props: {
  readonly mode: SidebarMode;
  readonly onToggle: () => void;
}): ReactElement {
  const label = props.mode === "expanded" ? "Collapse navigation" : "Expand navigation";
  const { tooltip, triggerProps } = useNavTooltip(label, props.mode === "collapsed");
  return (
    <>
      <button
        aria-controls={SIDEBAR_NAV_ID}
        aria-expanded={props.mode === "expanded"}
        aria-label={label}
        className="ek-button ek-focusable ek-button--quiet ek-icon-button"
        data-testid="sidebar-toggle"
        onClick={props.onToggle}
        style={{ minHeight: controlHeight({ collapsed: false, compact: false }) }}
        type="button"
        {...triggerProps}
      >
        <ShellIcon name={props.mode === "expanded" ? "collapseSidebar" : "expandSidebar"} />
      </button>
      {tooltip}
    </>
  );
}

/**
 * The desktop and tablet sidebar (DESIGN.md §4.2): identity at the top, the navigation, and the
 * account area anchored at the bottom. Collapsed, it is icons only, each named by a tooltip.
 */
function Sidebar(props: {
  readonly config: EkklesiaHostConfig;
  readonly history: HostHistory;
  readonly navigation: DashboardNavigation;
  readonly route: DashboardRoute;
  readonly mode: SidebarMode;
  readonly onToggle: () => void;
  readonly onSignOut: () => void;
}): ReactElement {
  const presentation: NavigationPresentation = {
    collapsed: props.mode === "collapsed",
    compact: false,
  };
  return (
    <aside
      className="ek-shell-sidebar"
      data-sidebar={props.mode}
      data-testid="host-sidebar"
      style={{ width: SIDEBAR_WIDTH[props.mode] }}
    >
      <div className="ek-shell-sidebar__top">
        <ShellBrand collapsed={presentation.collapsed} />
        <SidebarToggle mode={props.mode} onToggle={props.onToggle} />
      </div>
      <div className="ek-shell-sidebar__scroll">
        <NavigationList
          history={props.history}
          id={SIDEBAR_NAV_ID}
          navigation={props.navigation}
          presentation={presentation}
          route={props.route}
        />
        {/* The transitional device panel (ADR 0036) needs room for its form; collapsed, expanding
            the sidebar reveals it. Stage 1 moves it to Settings → Displays. */}
        {presentation.collapsed ? undefined : <DevicePanel config={props.config} />}
      </div>
      <div className="ek-shell-sidebar__bottom">
        <AccountMenu onSignOut={props.onSignOut} presentation={presentation} />
      </div>
    </aside>
  );
}

/**
 * The phone navigation (DESIGN.md §4.6): the same hierarchy, current page, and account area as the
 * sidebar, in a modal drawer.
 *
 * It is a real modal: `role="dialog"` with `aria-modal`, the page behind it `inert`, and Tab and
 * Shift+Tab kept inside it here as well, for a browser that does not yet honour `inert`. Opening
 * moves focus to its close button; Escape, the close button, and the backdrop dismiss it and the
 * layout returns focus to the trigger.
 */
function NavigationDrawer(props: {
  readonly config: EkklesiaHostConfig;
  readonly history: HostHistory;
  readonly navigation: DashboardNavigation;
  readonly route: DashboardRoute;
  readonly onDismiss: () => void;
  readonly onNavigate: () => void;
  readonly onSignOut: () => void;
}): ReactElement {
  const panelRef = useRef<HTMLDivElement>(null);
  const closeRef = useRef<HTMLButtonElement>(null);
  const presentation: NavigationPresentation = { collapsed: false, compact: true };

  useEffect(() => {
    closeRef.current?.focus();
  }, []);

  const onKeyDown = (event: KeyboardEvent<HTMLDivElement>): void => {
    if (event.key === "Escape") {
      event.preventDefault();
      props.onDismiss();
      return;
    }
    if (event.key !== "Tab" || !panelRef.current) {
      return;
    }
    const focusable = [...panelRef.current.querySelectorAll<HTMLElement>(FOCUSABLE)];
    const first = focusable[0];
    const last = focusable.at(-1);
    const active = panelRef.current.ownerDocument.activeElement;
    if (event.shiftKey && (active === first || !panelRef.current.contains(active))) {
      event.preventDefault();
      last?.focus();
    } else if (!event.shiftKey && (active === last || !panelRef.current.contains(active))) {
      event.preventDefault();
      first?.focus();
    }
  };

  return (
    <>
      <div
        aria-hidden="true"
        className="ek-shell-drawer-backdrop"
        data-testid="navigation-drawer-backdrop"
        onClick={props.onDismiss}
      />
      <div
        aria-label="Navigation"
        aria-modal="true"
        className="ek-shell-drawer"
        data-testid="navigation-drawer"
        id={DRAWER_ID}
        onKeyDown={onKeyDown}
        ref={panelRef}
        role="dialog"
      >
        <div className="ek-shell-sidebar__top">
          <ShellBrand collapsed={false} />
          <button
            aria-label="Close navigation"
            className="ek-button ek-focusable ek-button--quiet ek-icon-button"
            data-testid="navigation-drawer-close"
            onClick={props.onDismiss}
            ref={closeRef}
            style={{
              minHeight: controlHeight(presentation),
              minWidth: controlHeight(presentation),
            }}
            type="button"
          >
            <ShellIcon name="closeNavigation" />
          </button>
        </div>
        <div className="ek-shell-sidebar__scroll">
          <NavigationList
            history={props.history}
            id={DRAWER_NAV_ID}
            navigation={props.navigation}
            onNavigate={props.onNavigate}
            presentation={presentation}
            route={props.route}
          />
          <DevicePanel config={props.config} />
        </div>
        <div className="ek-shell-sidebar__bottom">
          <AccountMenu onSignOut={props.onSignOut} presentation={presentation} />
        </div>
      </div>
    </>
  );
}

function routeKey(route: DashboardRoute): string {
  return route.kind === "module" ? `module:${route.moduleId}` : route.kind;
}

/**
 * The authenticated Dashboard's frame (ADR 0058): a collapsible sidebar on wide screens, a drawer
 * on phones, and the page.
 *
 * The page's `<main>` keeps one position in the tree whichever layout is showing, so changing
 * layout — rotating a tablet, resizing a window — never remounts the open module. The route comes
 * from the URL (ADR 0057) and the desktop mode from the sidebar preference, so neither is touched by
 * a layout change; only an open drawer is dropped, and focus that was inside it lands on the page.
 * There is no application top bar: on a phone the one control above the page is the menu trigger.
 */
export function ShellLayout(props: ShellLayoutProps): ReactElement {
  const { viewport, sidebarPreference, mainRef, route } = props;
  const subscribe = useCallback((listener: () => void) => viewport.subscribe(listener), [viewport]);
  const readCompact = useCallback(() => viewport.isCompact(), [viewport]);
  const compact = useSyncExternalStore(subscribe, readCompact, readCompact);
  const [mode, setMode] = useState<SidebarMode>(() => sidebarPreference.read() ?? "expanded");
  const [drawerOpen, setDrawerOpen] = useState(false);
  const pendingFocus = useRef<"trigger" | "main" | undefined>(undefined);
  const triggerRef = useRef<HTMLButtonElement>(null);
  const previousCompact = useRef(compact);
  const previousRoute = useRef(routeKey(route));

  const toggleMode = (): void => {
    const next: SidebarMode = mode === "expanded" ? "collapsed" : "expanded";
    setMode(next);
    sidebarPreference.write(next);
  };

  const closeDrawer = useCallback((focus: "trigger" | "main") => {
    pendingFocus.current = focus;
    setDrawerOpen(false);
  }, []);

  // A layout change drops an open drawer. Focus inside a drawer or sidebar that just went away
  // would otherwise fall to the document; it lands on the page instead.
  useLayoutEffect(() => {
    if (previousCompact.current === compact) {
      return;
    }
    previousCompact.current = compact;
    if (drawerOpen) {
      closeDrawer("main");
      return;
    }
    const owner = mainRef.current?.ownerDocument;
    if (owner && (owner.activeElement === null || owner.activeElement === owner.body)) {
      mainRef.current?.focus();
    }
  }, [closeDrawer, compact, drawerOpen, mainRef]);

  // Back and Forward close the drawer too; the shell moves focus to the new page itself.
  useEffect(() => {
    const key = routeKey(route);
    if (previousRoute.current !== key) {
      previousRoute.current = key;
      setDrawerOpen(false);
    }
  }, [route]);

  useEffect(() => {
    if (drawerOpen || pendingFocus.current === undefined) {
      return;
    }
    const target = pendingFocus.current === "trigger" ? triggerRef.current : mainRef.current;
    pendingFocus.current = undefined;
    target?.focus();
  }, [drawerOpen, mainRef]);

  const showDrawer = compact && drawerOpen;
  const pageInert = showDrawer ? true : undefined;

  return (
    <div
      data-layout={compact ? "compact" : "wide"}
      data-testid="host-shell"
      style={{
        display: compact ? "block" : "grid",
        gridTemplateColumns: compact ? undefined : "auto minmax(0, 1fr)",
        minHeight: "100vh",
        minWidth: 0,
        width: "100%",
      }}
    >
      <style>{SHELL_STYLESHEET}</style>
      {compact ? undefined : (
        <Sidebar
          config={props.config}
          history={props.history}
          mode={mode}
          navigation={props.navigation}
          onSignOut={props.onSignOut}
          onToggle={toggleMode}
          route={route}
        />
      )}
      <div style={{ minWidth: 0 }}>
        {compact ? (
          <div className="ek-shell-mobile-bar" inert={pageInert}>
            <button
              aria-controls={DRAWER_ID}
              aria-expanded={showDrawer}
              aria-label="Open navigation"
              className="ek-button ek-focusable ek-button--quiet ek-icon-button"
              data-testid="mobile-navigation-trigger"
              onClick={() => setDrawerOpen(true)}
              ref={triggerRef}
              style={{
                minHeight: controlHeight({ collapsed: false, compact: true }),
                minWidth: controlHeight({ collapsed: false, compact: true }),
              }}
              type="button"
            >
              <ShellIcon name="openNavigation" size={24} />
            </button>
          </div>
        ) : undefined}
        <main
          aria-label={props.pageTitle}
          data-testid="host-main-region"
          inert={pageInert}
          ref={mainRef}
          style={{
            boxSizing: "border-box",
            minWidth: 0,
            // A programmatic focus target after a page change (never in the tab order).
            outline: "none",
            overflowX: "auto",
            padding: designToken("spacing.xl"),
          }}
          tabIndex={-1}
        >
          {props.children}
        </main>
      </div>
      {showDrawer ? (
        <NavigationDrawer
          config={props.config}
          history={props.history}
          navigation={props.navigation}
          onDismiss={() => closeDrawer("trigger")}
          onNavigate={() => closeDrawer("main")}
          onSignOut={props.onSignOut}
          route={route}
        />
      ) : undefined}
    </div>
  );
}