@better-forge/ui 0.0.0-stage → 0.1.1

package/src/shell/AdminShell.tsx

@@ -0,0 +1,256 @@
+import { Fragment, Suspense, useCallback, useEffect, useRef, useState, type RefObject } from 'react'
+import { Outlet, NavLink, useNavigate, useLocation, Link } from 'react-router-dom'
+import { api, clearSession, getCurrentUser } from '../api/client'
+import { LoadingState } from '../components/ui/StateViews'
+import { WhatsNew, markWhatsNewSeen, pendingWhatsNew } from '../components/WhatsNew'
+import { useDarkMode } from '../hooks/useDarkMode'
+import { useDatePrefs } from '../lib/dateFormat'
+
+export interface NavItem {
+  to: string
+  label: string
+  icon: string
+  /** The lowest role that sees the item (see `roleRank`). */
+  minRole: string
+}
+
+export interface NavSection { label: string; items: NavItem[] }
+
+/** A link below the sections that leaves the interface (the public page, the documentation). */
+export interface ExternalLink { label: string; icon: string; href: () => string }
+
+export interface AdminShellConfig {
+  sections: NavSection[]
+  /** Roles from the lowest to the highest rank: a user sees an item when their rank reaches the item's `minRole`. */
+  roleRank: Readonly<Record<string, number>>
+  brand: { iconUrl: string; name: string; title: string; subtitle: string }
+  /** The page the first item leads to: it is highlighted only when it is exactly the current one. */
+  homePath: string
+  settingsPath: string
+  loginPath: string
+  externalLinks: readonly ExternalLink[]
+  /** The release notes shown once to a user who last saw an older version. */
+  whatsNew: { changelog: string; version: string; docsUrl: string }
+}
+
+const ICON_STYLE = { fontSize: '20px' }
+
+function Brand({ brand }: { brand: AdminShellConfig['brand'] }) {
+  return (
+    <div className="flex items-center gap-3 min-w-0">
+      <img src={brand.iconUrl} alt={brand.name} style={{ width: '40px', height: '40px', objectFit: 'contain', flexShrink: 0 }} />
+      <div className="min-w-0">
+        <p className="font-headline font-bold text-base leading-none" style={{ color: 'var(--m3-on-surface)' }}>
+          {brand.title}
+        </p>
+        <p className="text-xs leading-none mt-1" style={{ color: 'var(--m3-secondary)' }}>
+          {brand.subtitle}
+        </p>
+      </div>
+    </div>
+  )
+}
+
+interface NavContentProps {
+  config: AdminShellConfig
+  sections: NavSection[]
+  isDark: boolean
+  onToggleDark: () => void
+  onLogout: () => void
+}
+
+/** Section links plus the Settings / theme / logout footer, shared by the desktop sidebar and the mobile drawer. */
+function NavContent({ config, sections, isDark, onToggleDark, onLogout }: NavContentProps) {
+  return (
+    <>
+      <nav aria-label="Main" className="flex-1 px-3 overflow-y-auto pb-2">
+        {sections.map((section, si) => (
+          <div key={section.label} className={si > 0 ? 'mt-4' : ''}>
+            <p
+              className="px-4 pb-1 font-mono uppercase tracking-widest"
+              style={{ fontSize: '10px', color: 'var(--m3-outline)', letterSpacing: '0.1em' }}
+            >
+              {section.label}
+            </p>
+            <div className="space-y-0.5">
+              {section.items.map((item) => (
+                <NavLink key={item.to} to={item.to} end={item.to === config.homePath} className="admin-nav-item">
+                  {({ isActive }) => (
+                    <>
+                      <span
+                        aria-hidden="true" className="material-symbols-outlined flex-shrink-0"
+                        style={{ ...ICON_STYLE, fontVariationSettings: isActive ? "'FILL' 1" : "'FILL' 0" }}
+                      >
+                        {item.icon}
+                      </span>
+                      <span className="font-sans">{item.label}</span>
+                    </>
+                  )}
+                </NavLink>
+              ))}
+            </div>
+          </div>
+        ))}
+      </nav>
+
+      <div className="px-3 pb-4 pt-4 space-y-0.5" style={{ borderTop: '1px solid var(--m3-outline-variant)' }}>
+        {config.externalLinks.map((link) => (
+          <a key={link.label} href={link.href()} target="_blank" rel="noopener" className="admin-nav-item">
+            <span aria-hidden="true" className="material-symbols-outlined flex-shrink-0" style={ICON_STYLE}>{link.icon}</span>
+            <span className="font-sans">{link.label}</span>
+          </a>
+        ))}
+
+        <Link to={config.settingsPath} className="admin-nav-item">
+          <span aria-hidden="true" className="material-symbols-outlined flex-shrink-0" style={ICON_STYLE}>manage_accounts</span>
+          <span className="font-sans">Settings</span>
+        </Link>
+
+        <button type="button" onClick={onToggleDark} className="admin-nav-item">
+          <span aria-hidden="true" className="material-symbols-outlined flex-shrink-0" style={ICON_STYLE}>
+            {isDark ? 'light_mode' : 'dark_mode'}
+          </span>
+          <span className="font-sans">{isDark ? 'Light Mode' : 'Dark Mode'}</span>
+        </button>
+
+        <button type="button" onClick={onLogout} className="admin-nav-item admin-nav-danger">
+          <span aria-hidden="true" className="material-symbols-outlined flex-shrink-0" style={ICON_STYLE}>logout</span>
+          <span className="font-sans">Logout</span>
+        </button>
+      </div>
+    </>
+  )
+}
+
+interface MobileDrawerProps extends NavContentProps {
+  onClose: () => void
+  returnFocusRef: RefObject<HTMLButtonElement | null>
+}
+
+function MobileDrawer({ onClose, returnFocusRef, ...nav }: MobileDrawerProps) {
+  const closeRef = useRef<HTMLButtonElement>(null)
+
+  useEffect(() => {
+    closeRef.current?.focus()
+    const returnTo = returnFocusRef.current
+    const onKeyDown = (event: KeyboardEvent) => { if (event.key === 'Escape') onClose() }
+    document.addEventListener('keydown', onKeyDown)
+    return () => {
+      document.removeEventListener('keydown', onKeyDown)
+      returnTo?.focus()
+    }
+  }, [onClose, returnFocusRef])
+
+  return (
+    <div className="md:hidden fixed inset-0 z-50">
+      <div data-testid="nav-drawer-overlay" className="admin-drawer-overlay absolute inset-0" style={{ background: 'rgba(0,0,0,0.55)' }} onClick={onClose} />
+      <div
+        id="admin-nav-drawer"
+        role="dialog"
+        aria-modal="true"
+        aria-label="Navigation"
+        className="admin-drawer-panel absolute inset-y-0 left-0 flex flex-col w-72 max-w-[85vw]"
+        style={{ background: 'var(--m3-surface-container-low)', boxShadow: '0 8px 32px rgba(0,0,0,0.18)' }}
+      >
+        <div className="flex items-center justify-between gap-2 px-4 pt-4 mb-4">
+          <Brand brand={nav.config.brand} />
+          <button ref={closeRef} type="button" onClick={onClose} aria-label="Close navigation" className="btn-icon">
+            <span aria-hidden="true" className="material-symbols-outlined">close</span>
+          </button>
+        </div>
+        <NavContent {...nav} />
+      </div>
+    </div>
+  )
+}
+
+/**
+ * The signed-in shell of an admin interface: a sidebar (a drawer on a phone) with the sections the user's role may see,
+ * the footer links, the theme switch and logout, and the page below it. The sections, roles, brand and links are the
+ * application's; the page is whatever the router renders in the `Outlet`.
+ */
+export function createAdminShell(config: AdminShellConfig) {
+  return function AdminShell() {
+    const navigate = useNavigate()
+    const location = useLocation()
+    const [isDark, toggleDark] = useDarkMode()
+    const datePrefs = useDatePrefs()
+    const currentUser = getCurrentUser()
+    const userRank = config.roleRank[currentUser?.role ?? ''] ?? 0
+    // The drawer remembers the path it was opened on, so navigating anywhere closes it without an effect.
+    const [drawerPath, setDrawerPath] = useState<string | null>(null)
+    const drawerOpen = drawerPath === location.pathname
+    const menuButtonRef = useRef<HTMLButtonElement>(null)
+    const closeDrawer = useCallback(() => setDrawerPath(null), [])
+
+    const navSections = config.sections
+      .map((section) => ({
+        ...section,
+        items: section.items.filter((item) => userRank >= (config.roleRank[item.minRole] ?? 99)),
+      }))
+      .filter((section) => section.items.length > 0)
+
+    const { changelog, version, docsUrl } = config.whatsNew
+    const userId = currentUser?.userId
+    const [whatsNew, setWhatsNew] = useState(() => userId !== undefined ? pendingWhatsNew(userId, changelog, version) : [])
+    const closeWhatsNew = useCallback(() => {
+      setWhatsNew([])
+      if (userId !== undefined) markWhatsNewSeen(userId, version)
+    }, [userId, version])
+
+    async function handleLogout() {
+      try { await api.post('/auth/logout') } catch { /* local logout still proceeds */ }
+      clearSession()
+      navigate(config.loginPath)
+    }
+
+    const nav: NavContentProps = { config, sections: navSections, isDark, onToggleDark: toggleDark, onLogout: () => void handleLogout() }
+
+    return (
+      <div className="flex flex-col md:flex-row h-screen" style={{ background: 'var(--m3-surface-container-low)' }}>
+        {/* Mobile top bar */}
+        <header
+          className="md:hidden flex items-center justify-between gap-3 px-4 py-3 flex-shrink-0"
+          style={{ background: 'var(--m3-surface-container-low)', borderBottom: '1px solid var(--m3-outline-variant)' }}
+        >
+          <Brand brand={config.brand} />
+          <button
+            ref={menuButtonRef}
+            type="button"
+            onClick={() => setDrawerPath(location.pathname)}
+            aria-label="Open navigation"
+            aria-expanded={drawerOpen}
+            aria-controls="admin-nav-drawer"
+            className="btn-icon"
+          >
+            <span aria-hidden="true" className="material-symbols-outlined">menu</span>
+          </button>
+        </header>
+
+        {whatsNew.length > 0 && <WhatsNew releases={whatsNew} docsUrl={docsUrl} onClose={closeWhatsNew} />}
+
+        {drawerOpen && <MobileDrawer {...nav} onClose={closeDrawer} returnFocusRef={menuButtonRef} />}
+
+        {/* Sidebar */}
+        <aside
+          className="hidden md:flex flex-col h-screen w-64 sticky top-0 flex-shrink-0"
+          style={{ background: 'var(--m3-surface-container-low)' }}
+        >
+          <div className="mb-6 px-4 pt-5">
+            <Brand brand={config.brand} />
+          </div>
+          <NavContent {...nav} />
+        </aside>
+
+        {/* Main */}
+        <main className="flex-1 min-h-0 min-w-0 overflow-auto" style={{ background: 'var(--m3-surface-container-low)' }}>
+          {/* Lazy pages suspend here, not above the shell, so the menu stays while a page's code is fetched. */}
+          <Suspense fallback={<LoadingState />}>
+            {/* Remount the page when the date format changes so every formatted date is recomputed. */}
+            <Fragment key={`${datePrefs.date}-${datePrefs.time}`}><Outlet /></Fragment>
+          </Suspense>
+        </main>
+      </div>
+    )
+  }
+}

package/src/shell/guards.tsx

@@ -0,0 +1,88 @@
+import { useEffect, useState, type ReactNode } from 'react'
+import { Navigate } from 'react-router-dom'
+import { api, clearSession, getCurrentUser, mustChangePassword, setSession, type AuthUser } from '../api/client'
+import { uiConfig } from '../config'
+import { navigation } from '../navigation'
+
+/** Sends a first visit to the setup page, while the application has no administrator yet. */
+export function SetupGate({ children }: { children: ReactNode }) {
+  const [state, setState] = useState<'loading' | 'setup' | 'ready'>('loading')
+
+  useEffect(() => {
+    fetch(`${uiConfig().apiBase}/setup/status`)
+      .then((r) => r.json())
+      .then((data: { needsSetup: boolean }) => {
+        setState(data.needsSetup ? 'setup' : 'ready')
+      })
+      .catch(() => setState('ready'))
+  }, [])
+
+  if (state === 'loading') {
+    return (
+      <div className="min-h-screen flex items-center justify-center" style={{ background: 'var(--m3-surface)' }}>
+        <div className="flex flex-col items-center gap-4">
+          <div
+            className="w-10 h-10 rounded-2xl flex items-center justify-center"
+            style={{ background: 'var(--m3-primary-fixed)' }}
+          >
+            <svg width="20" height="20" viewBox="0 0 20 20" fill="none">
+              <circle cx="10" cy="10" r="3.5" fill="var(--m3-primary)" />
+              <circle cx="10" cy="10" r="8.5" stroke="var(--m3-primary)" strokeWidth="1.2" strokeOpacity="0.35" fill="none" />
+            </svg>
+          </div>
+          <span className="font-sans text-sm" style={{ color: 'var(--m3-secondary)' }}>Starting…</span>
+        </div>
+      </div>
+    )
+  }
+
+  if (state === 'setup') return <Navigate to={`${uiConfig().basePath}/setup`} replace />
+  return <>{children}</>
+}
+
+/**
+ * Renders its children for a signed-in user. Someone who is not signed in goes to the sign-in page; someone the
+ * application sends elsewhere (`redirectAfterSignIn`) leaves the interface for that address.
+ */
+export function RequireAuth({ children }: { children: ReactNode }) {
+  const [state, setState] = useState<'checking' | 'authenticated' | 'anonymous' | 'elsewhere'>('checking')
+  const [elsewhere, setElsewhere] = useState<string | null>(null)
+
+  useEffect(() => {
+    api.get<AuthUser>('/auth/session')
+      .then((user) => {
+        setSession(user)
+        const target = uiConfig().redirectAfterSignIn?.(user) ?? null
+        setElsewhere(target)
+        setState(target ? 'elsewhere' : 'authenticated')
+      })
+      .catch(() => { clearSession(); setState('anonymous') })
+  }, [])
+
+  useEffect(() => {
+    if (state === 'elsewhere' && elsewhere) navigation.assign(elsewhere)
+  }, [state, elsewhere])
+
+  if (state === 'checking' || state === 'elsewhere') return null
+  if (state === 'anonymous') return <Navigate to={`${uiConfig().basePath}/login`} replace />
+  return <>{children}</>
+}
+
+/** Keeps a user who has to replace a temporary password on the page where they do it. */
+export function RequirePasswordChanged({ children }: { children: ReactNode }) {
+  if (mustChangePassword()) return <Navigate to={`${uiConfig().basePath}/change-password`} replace />
+  return <>{children}</>
+}
+
+/**
+ * A guard for pages that need a role: a user whose rank is below the page's goes to the home page of their role.
+ * `roleRank` lists the roles by rank (higher sees more); a role it does not know ranks lowest.
+ */
+export function createRoleGuard(options: { roleRank: Readonly<Record<string, number>>; homeOf: (role?: string) => string }) {
+  return function RequireRole({ minRole, children }: { minRole: string; children: ReactNode }) {
+    const user = getCurrentUser()
+    const rank = options.roleRank[user?.role ?? ''] ?? 0
+    if (rank < (options.roleRank[minRole] ?? 99)) return <Navigate to={options.homeOf(user?.role)} replace />
+    return <>{children}</>
+  }
+}