@helloimjolopez-pathway/pathway-components 0.0.0-stage → 0.1.1

package/components/nav-shell/nav-shell.jsx

@@ -0,0 +1,252 @@
+/**
+ * NavShell, Pathway Design System
+ *
+ * Composes TopNav + SideNav + Shell.Main into the application frame that wraps
+ * every Amplify page. Not a Figma component set (the shell has no Figma node of
+ * its own); it is a layout composition of TopNav, SideNav, and PageTemplate.
+ *
+ * Spec:  components/nav-shell/nav-shell-spec.md
+ * Figma: TopNav 40007067:6508, SideNav.Container 40004059:1375,
+ *        ScreenTemplate (set) 40009709:26016
+ */
+
+import React, { useState, useEffect, useCallback } from "react";
+import TopNav, { DEFAULT_MODULES } from "../top-nav/top-nav.jsx";
+import { SideNav } from "../sidenav/sidenav.jsx";
+
+// ─── CONSTANTS ────────────────────────────────────────────────────────────────
+const TOPNAV_H = 60; // px — spec §9.3 rule 1
+
+// SideNav widths via contextual tokens (same source as sidenav.jsx L.navW/L.navWcol)
+const CL = (p) => `var(--contextual-layout-units-${p})`;
+const SIDENAV_W_EXP = CL("sidenav-width-expanded");
+const SIDENAV_W_COL = CL("sidenav-width-collapsed");
+
+// ─── HOOK: responsive breakpoint ─────────────────────────────────────────────
+function useBreakpoint() {
+  const get = () => {
+    if (typeof window === "undefined") return "desktop";
+    if (window.innerWidth < 768)  return "mobile";
+    if (window.innerWidth < 1024) return "tablet";
+    return "desktop";
+  };
+  const [bp, setBp] = useState(get);
+  useEffect(() => {
+    const h = () => setBp(get());
+    window.addEventListener("resize", h, { passive: true });
+    return () => window.removeEventListener("resize", h);
+  }, []);
+  return bp;
+}
+
+// ─── COMPONENT ────────────────────────────────────────────────────────────────
+
+/**
+ * NavShell — the fixed application frame.
+ *
+ * Layout zones (always present):
+ *   TopNav     fixed, full width, 60px tall, z-index 100
+ *   SideNav    fixed, left edge, top 60px → bottom, push layout
+ *   Shell.Main scrollable content area, margin-left = SideNav width
+ *
+ * Desktop:  SideNav 240px expanded | 84px collapsed, user toggles
+ * Tablet:   SideNav always 84px rail, toggle locked
+ * Mobile:   SideNav hidden, slides in as 240px overlay on hamburger tap
+ *
+ * Props (TopNav pass-through):
+ *   modules          Array<{id, label, icon}> — all modules (default: DEFAULT_MODULES)
+ *   activeModuleId   string — which module is active
+ *   org              {id, name, campus, initials, logoUrl?}
+ *   orgs             Array<org> — OrgSwitcher dropdown list
+ *   user             {name, initials, email}
+ *   onModuleSelect   (id) => void
+ *   onOrgSelect      (id) => void
+ *
+ * Props (SideNav pass-through):
+ *   navItems         Array<SideNavItem> — flat nav items (use this OR navSections)
+ *   navSections      Array<{label, items}> — sectioned nav items
+ *   activeNavId      string — current page id
+ *   onNavigate       (id) => void
+ *   navHeaderEnd     ReactNode — slot after collapse toggle in nav header
+ *   navChildren      ReactNode — slot inside scroll area, after items
+ *   navFooter        ReactNode — slot pinned below scroll area
+ *
+ * Props (shell):
+ *   defaultCollapsed boolean — initial desktop collapse state (default false)
+ *   children         ReactNode — page content (renders inside Shell.Main)
+ */
+export function NavShell({
+  // TopNav
+  modules         = DEFAULT_MODULES,
+  activeModuleId  = "home",
+  org,
+  orgs,
+  user,
+  onModuleSelect,
+  onOrgSelect,
+
+  // SideNav
+  navItems,
+  navSections,
+  activeNavId,
+  onNavigate,
+  navHeaderEnd = null,
+  navChildren  = null,
+  navFooter    = null,
+
+  // Shell
+  defaultCollapsed = false,
+  children,
+}) {
+  const breakpoint = useBreakpoint();
+  const isMobile   = breakpoint === "mobile";
+  const isTablet   = breakpoint === "tablet";
+
+  // Desktop collapse state (controlled within NavShell)
+  const [collapsed,  setCollapsed]  = useState(defaultCollapsed);
+  // Mobile overlay open state
+  const [mobileOpen, setMobileOpen] = useState(false);
+
+  // Tablet: rail (84px) is fixed, no user toggle
+  // Mobile:  always "collapsed" visually (but managed separately via mobileOpen)
+  // Desktop: user-controlled
+  const effectiveCollapsed = isTablet || isMobile ? true : collapsed;
+
+  // Shell.Main margin-left: matches current SideNav width for push layout.
+  // Mobile: no margin (SideNav is an overlay).
+  const mainMarginLeft = isMobile
+    ? 0
+    : effectiveCollapsed ? SIDENAV_W_COL : SIDENAV_W_EXP;
+
+  const handleCollapseChange = useCallback((next) => {
+    if (!isTablet && !isMobile) setCollapsed(next);
+  }, [isTablet, isMobile]);
+
+  // TopNav calls this when hamburger (mobile) or collapse button (desktop) is tapped
+  const handleSideNavToggle = useCallback(() => {
+    if (isMobile) setMobileOpen(o => !o);
+    else if (!isTablet) setCollapsed(c => !c);
+  }, [isMobile, isTablet]);
+
+  // Close mobile overlay on Escape — spec §8 mobile hamburger rules
+  useEffect(() => {
+    if (!mobileOpen) return;
+    const h = (e) => { if (e.key === "Escape") setMobileOpen(false); };
+    document.addEventListener("keydown", h);
+    return () => document.removeEventListener("keydown", h);
+  }, [mobileOpen]);
+
+  // Also close mobile overlay when breakpoint changes away from mobile
+  useEffect(() => {
+    if (!isMobile) setMobileOpen(false);
+  }, [isMobile]);
+
+  // ── Render ─────────────────────────────────────────────────────────────────
+
+  return (
+    <>
+      {/* Skip navigation — first focusable element, WCAG 2.4.1 */}
+      <a
+        href="#main-content"
+        style={{
+          position: "absolute", top: -48, left: 8, zIndex: 300,
+          background: "var(--semantic-color-fill-action-primary-strong-rest)",
+          color:      "var(--semantic-color-foreground-action-ghost-rest)",
+          padding: "8px 12px", borderRadius: 6,
+          fontSize: 14, fontWeight: 500, textDecoration: "none",
+          transition: "top var(--motion-duration-2) var(--motion-easing-standard)",
+        }}
+        onFocus={(e) => { e.currentTarget.style.top = "8px"; }}
+        onBlur={(e)  => { e.currentTarget.style.top = "-48px"; }}
+      >
+        Skip to content
+      </a>
+
+      {/* ── TopNav: position fixed, full width, 60px ─────────────────────── */}
+      <TopNav
+        modules={modules}
+        activeModuleId={activeModuleId}
+        org={org}
+        orgs={orgs}
+        user={user}
+        breakpoint={breakpoint}
+        onModuleSelect={onModuleSelect}
+        onOrgSelect={onOrgSelect}
+        onSideNavToggle={handleSideNavToggle}
+      />
+
+      {/* ── Mobile scrim — darkens content while SideNav overlay is open ─── */}
+      {isMobile && mobileOpen && (
+        <div
+          aria-hidden="true"
+          onClick={() => setMobileOpen(false)}
+          style={{
+            position: "fixed", inset: 0, top: TOPNAV_H,
+            background: "rgba(0,0,0,0.32)",
+            zIndex: 49,
+          }}
+        />
+      )}
+
+      {/* ── SideNav container ────────────────────────────────────────────── */}
+      {/* Position: fixed so it stays below TopNav while the content scrolls.
+          On mobile: width controls the overlay reveal (0 → 240px); the SideNav
+          itself renders inside a clipping container and slides in from the left.
+          On desktop/tablet: overflow hidden so the SideNav's own width transition
+          stays within the container; no width needed here. */}
+      <div
+        aria-hidden={isMobile && !mobileOpen}
+        style={{
+          position: "fixed",
+          top: TOPNAV_H,
+          left: 0,
+          bottom: 0,
+          zIndex: isMobile ? 51 : 10,
+          overflow: "hidden",
+          // Mobile: clipping container, SideNav slides in via its own width
+          ...(isMobile && {
+            width: mobileOpen
+              ? SIDENAV_W_EXP
+              : 0,
+            transition: `width var(--motion-duration-6) var(--motion-easing-emphasized)`,
+          }),
+        }}
+      >
+        <SideNav
+          items={navItems}
+          sections={navSections}
+          activeId={activeNavId}
+          onNavigate={onNavigate}
+          collapsed={effectiveCollapsed}
+          onCollapseChange={handleCollapseChange}
+          hideCollapseButton={isTablet}
+          headerEnd={navHeaderEnd}
+          footer={navFooter}
+        >
+          {navChildren}
+        </SideNav>
+      </div>
+
+      {/* ── Shell.Main: scrollable content area ─────────────────────────── */}
+      {/* margin-left matches the SideNav width and transitions simultaneously.
+          spec §9.3 rule 3: never overflow hidden here. */}
+      <main
+        id="main-content"
+        role="main"
+        style={{
+          marginTop: TOPNAV_H,
+          marginLeft: mainMarginLeft,
+          minHeight: `calc(100vh - ${TOPNAV_H}px)`,
+          overflowY: "auto",
+          overflowX: "hidden",
+          background: "var(--semantic-color-fill-surface-canvas)",
+          transition: `margin-left var(--motion-duration-6) var(--motion-easing-emphasized)`,
+        }}
+      >
+        {children}
+      </main>
+    </>
+  );
+}
+
+export default NavShell;