Skip to main content

UX Specification: Global Navigation & Scope Switcher (v1.1)

This document defines the persistent global navigation chassis for Evalium. It ensures a consistent "Entry Point" into functional hubs and manages the organizational context (multi-tenancy) through a unified scope switcher.

1) Architecture: The "Sandwich" Layout​

To maximize screen real estate for data-dense tables while providing contextual support, Evalium uses a three-column sandwich architecture:

  1. Left (Persistent Sidebar): Global Navigation + Scope Switcher. "Where am I going?"
  2. Center (Fluid Workspace): The StandardHub or Builder content. "What am I doing?"
  3. Right (Context Drawer): The ContextDrawer driven by DrawerCoordinator. "Who/What is this reference?"

2) The Global Sidebar (GlobalNav)​

The sidebar is a "Fixed-Rail" navigation component located on the far left.

2.1 Top Section: Scope Switcher (OrgSwitcher)​

This is the most critical component for multi-tenant data isolation. It allows users to set their "Working Context" once for the entire session.

  • Interaction: A dropdown (Bits UI Select) showing the current active scope.
  • Modes:
    • "All Organizations" (Global): Sets X-Org-Scope: all. User sees aggregated data across the tenant.
    • "Specific Org" (Silo): Sets X-Org-Id: <uuid>. User sees only data belonging to that unit.
  • Behavior:
    • Changing the scope should trigger a data refresh of the current page.
    • Selection must persist across navigations (Session/Cookie-backed).
    • Visual cue: If scope is "All," use a distinct "Global" icon (e.g., Earth); if specific, use a "Silo" icon (e.g., Building).

2.2 Center Section: Primary Workspaces​

Links are grouped logically to reduce cognitive load for SMB users.

  • Dashboard: Root entry point (nav_dashboard).
  • Content: Grouped links for Questions, Passages, and Evaluations.
  • Delivery: Direct link to Assignments.
  • Insights: Direct link to Reporting.
  • Admin: Grouped links for Users, Groups, Roles, and Sign-In Security.

2.3 Bottom Section: System & Profile​

  • Settings: Tenant-level configuration.
  • User Profile: Identity management and Logout (nav_logout).

3) Breadcrumb Trail (NavBreadcrumbs)​

Breadcrumbs are required for every primary page shell (StandardHub). They provide the "Depth" navigation to complement the sidebar's "Width."

3.1 Contract (MUST)​

  • Placement: Always in the top-left of the fluid workspace header, above the <h1> title.
  • Structure: Root / Hub / Sub-Feature / [Entity]
    • Example: Dashboard / Questions / Geography MCQ / Version 2
  • i18n: Every static label in the trail MUST be localized. Entity names (like Question Stems) are rendered as provided.
  • Behavior: Clicking a crumb performs a standard navigation. The current page crumb is rendered as plain text (non-clickable).

4) Interaction Rules​

4.1 Visual Hierarchy​

  • Active State: The sidebar must clearly highlight the active route using high-contrast markers or background shifts.
  • Hover Intent: Sidebar links should show a tooltip or expanded label if the rail is collapsed (Tier B/C devices).

4.2 Mobility (Task-Tiers)​

  • Tier A (Mobile): The persistent left sidebar is hidden. A top-right Menu button opens navigation in a right-side sheet/dialog. Scope switcher stays in this menu.
  • Tier B/C (Tablet/Desktop): Full sidebar is shown.

4.3 Collapsible Group Default​

  • Navigation parent groups (Content, Delivery, Insights, Admin) are collapsible.
  • Default: only the group containing the current route is expanded on load.
  • When route changes, open state should follow the active section and collapse others by default.

5) Implementation Status (2026-03-05)​

  • AppShell uses grid layout (Sidebar + Main + Drawer host).
  • OrgSwitcher is implemented with local Bits Select wrapper.
  • Org scope state maps to request headers (X-Tenant-Id, X-Org-Id, X-Org-Scope) via shared scope state/contract headers.
  • NavBreadcrumbs is integrated into page shell (AppShell and StandardHub surfaces).
  • Sidebar labels resolve from i18n navigation keys.
  • Mobile menu uses dialog sheet and does not compete with drawer z-order.

Open implementation notes:

  • Passages and Reporting remain disabled placeholders until those page surfaces are wired.