# Two-Level Navigation: System Nav + Course Workspace ## Context OBEsoft-v2 is a single-page OBE accreditation tool (PHP + SQLite backend, vanilla JS frontend, no build step). Today it has **one flat sidebar with 16 tabs** that mixes two unrelated concerns: system administration (All Courses, Setup, Administration) and per-course work (COs, Marks, Attainment). Which course you are editing is chosen from a small `` is populated once at `initApp` and never refreshed, so a newly created category doesn't appear until reload. 6. **Accessibility debt**: there is no `:focus-visible`, no `aria-current`, no `role="progressbar"` anywhere in the app. ~10 lines to add, and this refactor is the natural moment. --- ## The Nav Registry New file `public/assets/js/nav-registry.js` — pure data and pure functions. **No DOM access, no fetch, no top-level reference to anything in `app.js`** (it loads first). ```js const NAV_GROUPS = [ { id: "overview", level: "system", label: null }, { id: "courseMgmt", level: "system", label: "Course Management" }, { id: "sysadmin", level: "system", label: "Accreditation & System" }, { id: "account", level: "system", label: "Account & Access" }, { id: "workspace", level: "course", label: null }, { id: "planning", level: "course", label: "Curriculum & Planning" }, { id: "evaluation", level: "course", label: "Evaluation & Results" }, { id: "accredit", level: "course", label: "Accreditation & System" } ]; ``` Item fields: `id` (stable; also the `#tab-` suffix and the `data-tab` value, so the existing `[data-tab]` broadcast keeps working untouched) · `path` (hash slug, deliberately decoupled from `id` so `archive` can live at the friendly `#/courses`) · `type` (`"page"` default, or `"action"`) · `roles` (null = everyone) · `render` (**a thunk, never a bare reference** — see Risks) · `async` · `complete` (predicate) · `derived` (readout; excluded from the readiness denominator) · `weight`. ```js const NAV_ITEMS = [ /* ---------- LEVEL 1: SYSTEM ---------- */ { id:"dashboard", path:"dashboard", level:"system", group:"overview", label:"Dashboard", icon:"bi-speedometer2", roles:null, async:true, render: () => renderSystemDashboard() }, { id:"archive", path:"courses", level:"system", group:"courseMgmt", label:"All Courses", icon:"bi-journals", roles:null, async:true, render: () => renderArchiveTab() }, { id:"newcourse", type:"action", level:"system", group:"courseMgmt", label:"Add New Course", icon:"bi-journal-plus", roles:null, action: () => bootstrap.Modal .getOrCreateInstance(document.getElementById("newCourseModal")).show() }, { id:"categories", path:"categories", level:"system", group:"courseMgmt", label:"Categories", icon:"bi-tags", roles:["admin","manager"], // categories.manage async:true, render: () => renderCategoriesTab() }, { id:"data", path:"data", level:"system", group:"sysadmin", label:"Data & Backup", icon:"bi-database-down", roles:["admin","manager"], render: () => renderData() }, { id:"setup", path:"setup", level:"system", group:"sysadmin", label:"Setup", icon:"bi-sliders", roles:["admin","manager"], render: () => renderSetup() }, { id:"about", path:"about", level:"system", group:"sysadmin", label:"About", icon:"bi-award", roles:null, render: () => renderAbout() }, { id:"admin", path:"admin", level:"system", group:"account", label:"Administration", icon:"bi-shield-lock", roles:["admin","manager"], async:true, render: () => renderAdminTab() }, { id:"activity", path:"activity", level:"system", group:"account", label:"Activity Log", icon:"bi-clock-history", roles:["admin","manager"], async:true, render: () => renderActivityTab() }, /* ---------- LEVEL 2: COURSE WORKSPACE ---------- */ { id:"course", path:"overview", level:"course", group:"workspace", label:"Course Overview", icon:"bi-info-circle", roles:null, weight:1, render: () => renderCourse(), complete: c => Boolean((c.code||"").trim() && (c.title||"").trim() && (c.data.outline.prepared||"").trim() && (c.data.outline.synopsis||"").trim()) }, { id:"cos", path:"cos", level:"course", group:"planning", label:"COs & Mapping", icon:"bi-diagram-3", roles:null, weight:2, render: () => renderCos(), complete: c => c.cos.length > 0 && c.cos.every(co => (co.desc||"").trim() && Object.values(co.po || {}).some(v => +v > 0)) }, { id:"tla", path:"tla", level:"course", group:"planning", label:"T&L Plan", icon:"bi-calendar3", roles:null, weight:1, render: () => renderTla(), complete: c => tlaPlanStatus(c).complete }, { id:"assess", path:"assess", level:"course", group:"planning", label:"Assessments", icon:"bi-card-checklist", roles:null, weight:2, render: () => renderAssess(), complete: c => c.assessments.length > 0 && c.assessments.every(a => a.items.length > 0) && Math.abs(c.assessments.reduce((s,a)=>s+(+a.weightPct||0),0) - 100) < 0.5 }, { id:"ca", path:"ca", level:"course", group:"planning", label:"CA (Alignment)", icon:"bi-percent", roles:null, weight:1, render: () => renderCa(), complete: c => { const its = c.assessments.flatMap(a => a.items); return its.length > 0 && its.every(it => c.cos.some(co => co.id === it.coId)); } }, { id:"marks", path:"marks", level:"course", group:"evaluation", label:"Students & Marks", icon:"bi-table", roles:null, weight:2, render: () => renderMarks(), complete: c => c.students.length > 0 && c.students.every(s => c.marks[s.id] && Object.keys(c.marks[s.id]).length > 0) }, { id:"attain", path:"attain", level:"course", group:"evaluation", label:"Attainment", icon:"bi-graph-up-arrow", roles:null, derived:true, render: () => renderAttain(), complete: c => computeAttainment(c).coResults.length > 0 }, { id:"cqi", path:"cqi", level:"course", group:"evaluation", label:"CQI Pipeline", icon:"bi-arrow-repeat", roles:null, weight:1, render: () => renderCqi(), // VERIFIED field paths — app.js:1656 and app.js:1660 complete: c => Boolean((c.data.cqi.lowAnalysis?.notes || "").trim() && (c.data.cqi.effective || "").trim()) }, /* NOTE: this id MUST stay "docs" — style.css:489 has `section#tab-docs { display:block !important }` inside @media print. */ { id:"docs", path:"docs", level:"course", group:"accredit", label:"Documents", icon:"bi-file-earmark-text", roles:null, derived:true, subs:["outline","attain"], subDefault:"outline", render: () => renderDocs(), complete: c => c.cos.length > 0 && (c.data.outline.synopsis||"").trim() } ]; ``` Lookups: `navById(id)`, `navByPath(level, path)`, `navAllowed(item)` (true when `!state.auth.enabled` for legacy single-user mode, else `item.roles.some(r => userRoles.includes(r))`), `navGateState(item)` returning `"visible" | "restricted" | "hidden"`, `navItemsFor(level)`. > **On "Restricted":** the backend sends roles only, and course access is binary — so today *no* item > should render locked; every gated item is `gate:"hide"`. Build `gate:"lock"` + `.is-restricted` > styling anyway (~8 lines); it is the one-line-per-item change needed the day the backend starts > sending a permission list. Document it as deliberately unused. --- ## Routing New file `public/assets/js/router.js`. Binds nothing at load; `Router.start()` is called from `initApp`. ```js const Router = { current: { itemId: null, courseId: null, sub: null }, navToken: 0, parse(hash) { const seg = String(hash||"").replace(/^#\/?/, "").split("/").filter(Boolean); if (!seg.length) return null; if (seg[0] === "course") { if (!seg[1]) return { bad: "nocourse" }; const item = navByPath("course", seg[2] || "overview"); return item ? { itemId:item.id, courseId:seg[1], sub:seg[3]||null } : { bad:"nopath" }; } const item = navByPath("system", seg[0]); return item ? { itemId:item.id, courseId:null, sub:null } : { bad:"nopath" }; }, build(itemId, { courseId, sub } = {}) { const it = navById(itemId); if (!it) return "#/dashboard"; if (it.level === "system") return `#/${it.path}`; const cid = courseId || state.activeCourseId; return `#/course/${encodeURIComponent(cid)}/${it.path}${sub ? "/" + sub : ""}`; }, go(itemId, opts) { this._set(this.build(itemId, opts), false); }, replace(itemId, opts) { this._set(this.build(itemId, opts), true); }, _set(hash, replace) { if (window.location.hash === hash) { this.apply(); return; } // hashchange won't fire if (replace) window.location.replace(location.pathname + location.search + hash); else window.location.hash = hash; }, start() { window.addEventListener("hashchange", () => this.apply()); this.apply(); }, async apply() { /* below */ } }; ``` **`Router.apply()` — resolve, guard, activate:** 1. `const r = Router.parse(location.hash)` 2. `!r` → `replace("dashboard")` 3. `r.bad === "nopath"` → toast "That page doesn't exist." + `replace("dashboard")` 4. `r.bad === "nocourse"` → `replace("archive")` 5. `navGateState(item) === "hidden"` → toast "You don't have access to that page." + `replace("dashboard")` 6. **Course guard** when `item.level === "course"`: - no `courseId` → `replace("archive")` - course not in `state.courses` → `await API.getCourse(r.courseId)` (**the first real caller of this existing method at `api.js:294`**). Success → `state.courses.push(ensureCourseData(fetched))`. `null` (403 and 404 both return null today) → toast "You don't have access to that course. Request access from All Courses." + `replace("archive")`, return. - `state.activeCourseId = r.courseId` 7. **Sub-route**: if `item.subs`, `state.activeDoc = item.subs.includes(r.sub) ? r.sub : item.subDefault` 8. Dedupe against `Router.current` (prevents a double render on the same-hash `_set` path) 9. `Router.current = r; state.activeTab = item.id;` 10. `await navActivate(item, r.courseId, state.activeDoc)` **Coexistence with the auth query params.** `URLSearchParams(location.search)` is unaffected by the hash, so `initApp:340-341` and `showAuthGate:165-168` need **zero** changes. One fix: `clearUrlState` (`app.js:182`) does `replaceState({}, "", location.pathname)`, which silently drops the hash — change to `location.pathname + location.hash`. `Router.start()` can't run while the gate is up, because `initApp` already returns at line 344 first. **`showTab` becomes a one-line shim** delegating to `Router.go`, so **none of the 58 existing call sites across 6 files need editing**. Same for `showTabMobile` and `switchCourse`. All real work moves into `navActivate`. --- ## Sidebar Context Swap **One tree, re-rendered** — not two parallel trees toggled with CSS, which would duplicate `data-tab` attributes and break the broadcast. `navRenderSidebar(mode, courseId)` replaces `innerHTML` of `#sidebarNav` and `#mobileNav`, and shows/hides `#sidebarCourseContext` / `#mobileCourseContext`. One loop, two skins (`NAV_SKINS.desktop` reuses `.sidebar-link` / `.sidebar-category-header` / `.sidebar-nav-list`; `NAV_SKINS.mobile` reuses the existing `.nav-pills` + `.mobile-offcanvas .nav-link` styling). `href` = `Router.build(item.id, {courseId})`. Action items (`newcourse`) render as `