docs(18): capture phase context

2026-05-17 15:05:13 +02:00 · 2026-05-17 15:05:13 +02:00 · 4b8149028d
commit 4b8149028d
parent dfd61528d4
2 changed files with 240 additions and 0 deletions
--- a/.planning/phases/18-app-shell-navigation/18-CONTEXT.md
+++ b/.planning/phases/18-app-shell-navigation/18-CONTEXT.md
@ -0,0 +1,118 @@
+# Phase 18: App Shell & Navigation - Context
+
+**Gathered:** 2026-05-17
+**Status:** Ready for planning
+
+<domain>
+## Phase Boundary
+
+Redesign the authenticated app shell to match the Figma design: full rebuild of the sidebar (new HTML structure, section labels, updated nav items, collapse toggle) and addition of a new per-page top header bar (breadcrumb, search placeholder, bell placeholder, inbox placeholder, avatar dropdown).
+
+Every authenticated page is affected — changes to `AppLayout` propagate to all routes.
+
+</domain>
+
+<decisions>
+## Implementation Decisions
+
+### Figma Source
+- **D-01:** Figma file: `https://www.figma.com/design/6z32tx1YhL3nJHlX6M4IA2/XTABLO-Design--bbellev---copie-?node-id=11013-36540` — primary design reference.
+- **D-02:** Screenshots are in `screenshots/` at the repo root (Homepage.png, Board.png, and others). Planner/executor MUST read relevant screenshots before making visual decisions.
+
+### Top Header Bar (NAV-02)
+- **D-03:** The top header bar spans the full content area (right of sidebar). It has three zones:
+  - **Left:** Breadcrumb path (e.g., "Dashboard" or "Dashboard > Project Details")
+  - **Center:** Search input — **visual placeholder only** (no backend wiring in Phase 18)
+  - **Right:** Notification bell (placeholder), Inbox button (placeholder), user avatar
+- **D-04:** The breadcrumb is passed via new params added to `AppLayout`. Add `pageTitle string` and a breadcrumb slice (e.g., `[]BreadcrumbItem{label, href}`) to the `AppLayout` signature. Every handler call site sets its own breadcrumb.
+- **D-05:** `AppLayout` also gets a `headerActions templ.Component` slot for per-page contextual action buttons. Phase 18 renders this empty (or nil). Downstream phases (19–22) fill in page-specific actions.
+- **D-06:** Clicking the avatar opens an HTMX/Alpine-style dropdown containing:
+  - Workspace name + member count section
+  - Members list (user avatar, name, email)
+  - Separator
+  - Settings link → `/settings` (stub page; the settings page itself is out of scope for Phase 18)
+  - Log out button (red text, posts to `/logout`)
+  - **No theme toggle buttons**
+  - Reference HTML from JS app was provided — adapt visually to Go design system tokens, not copy verbatim.
+
+### Sidebar Rebuild (NAV-01)
+- **D-07:** Full HTML/CSS rebuild to Figma spec. The existing sidebar structure from Phase 15 is replaced, not patched. The design system (CSS token vocabulary) is updated to reflect any new visual decisions made during the rebuild.
+- **D-08:** Nav item mapping — match Figma labels exactly where possible:
+  - **GENERAL section label** above: Home (`/`), My Tasks (`/tasks`), Projects (`/tablos`), Events (`/planning`), Team Members (placeholder — no route yet, render as non-interactive or link to `#`)
+  - **PROJECTS section label** above: tablo list (existing `SidebarProjectsSection`)
+  - Items that have no matching Figma equivalent (chat, files global nav) are removed from the primary nav items list; they remain accessible within tablo detail pages.
+- **D-09:** Sidebar collapse toggle is implemented using JavaScript (no server round-trip). Clicking the collapse button toggles an `is-collapsed` CSS class on the sidebar. In collapsed state: hide labels and section headers, show icons only. **State is NOT persisted** — resets on page reload. (Persistence is a v5.0 candidate per RESP-01.)
+
+### Claude's Discretion
+- Avatar dropdown implementation mechanism (HTMX `hx-on::click` + hidden div toggle, `<details>/<summary>`, or small inline JS) — choose the simplest reliable approach that doesn't require Alpine.js.
+- Exact CSS class naming for the new header bar components — follow the existing `.dashboard-*` / `.sidebar-*` token naming convention.
+- Whether `BreadcrumbItem` is a struct or a simple string slice — choose what keeps call sites clean.
+
+</decisions>
+
+<canonical_refs>
+## Canonical References
+
+**Downstream agents MUST read these before planning or implementing.**
+
+### Design References
+- `screenshots/Homepage.png` — Figma homepage screenshot showing full sidebar + header bar layout
+- `screenshots/Board.png` — Figma board/tablo detail screenshot showing breadcrumb ("Dashboard > Project Details") and header bar with avatar
+- Figma URL: `https://www.figma.com/design/6z32tx1YhL3nJHlX6M4IA2/XTABLO-Design--bbellev---copie-?node-id=11013-36540` — primary design source (read screenshots if Figma not accessible)
+
+### Existing Shell Code
+- `backend/templates/app_layout.templ` — current `AppLayout`, `DashboardSidebar`, `SidebarNavItemRow`, `SidebarProjectsSection`, `SidebarOrganizationFooter` components to be rebuilt/replaced
+- `backend/static/tailwind.css` — CSS token vocabulary and existing `.dashboard-*`, `.sidebar-*`, `.organization-*` styles (lines 3276–3530 are the relevant sidebar/shell block)
+
+### Requirements
+- `.planning/REQUIREMENTS.md` — NAV-01 and NAV-02 requirements
+- `.planning/ROADMAP.md` — Phase 18 success criteria
+
+</canonical_refs>
+
+<code_context>
+## Existing Code Insights
+
+### Reusable Assets
+- `backend/internal/web/ui/` — existing templ component library (button, badge, modal, card, etc.). Use these for any new interactive elements in the header dropdown.
+- `backend/internal/web/ui/csrf_field.templ` — `ui.CSRFField(csrfToken)` already used in logout form; reuse in any new forms.
+- `backend/templates/app_layout.templ` — all nav icon SVGs (`SidebarNavIcon`) are already implemented; reuse for the rebuilt sidebar.
+- `backend/internal/auth/` — `auth.User` struct provides `Email` field used for avatar initial and org footer.
+
+### Established Patterns
+- `AppLayout` is the single authenticated shell — all authenticated handlers call it. Adding params here requires updating every handler call site.
+- Active path is currently a string passed as `activePath`; sidebar uses `sidebarNavItemClass(item.Active)` — this pattern continues.
+- HTMX is loaded via `<script src="/static/htmx.min.js" defer>` — available for any header interactivity.
+- CSS uses design token vars (`var(--color-*)`, `var(--shadow-*)`) throughout — new styles must use tokens, not raw hex values.
+
+### Integration Points
+- Every authenticated handler in `backend/internal/web/` renders `AppLayout(...)` — all call sites need `pageTitle` and `breadcrumb` params added.
+- The logout form currently lives in `SidebarOrganizationFooter`; it moves to the avatar dropdown in the header. The POST `/logout` route stays unchanged.
+- `backend/static/tailwind.css` — new CSS classes for header bar components go here (or in `backend/internal/web/ui/app.css` if that's the pattern for component-level styles; check which file the Phase 15 sidebar styles live in).
+
+</code_context>
+
+<specifics>
+## Specific Ideas
+
+- Avatar dropdown visual reference: user provided HTML from the existing JS app. Key elements to adapt: workspace name + member count row, members list section, settings link (`/settings`), logout button (red). No theme toggle. Adapt to Go design system tokens — don't copy Tailwind class names verbatim.
+- The collapse button exists in CSS (`.sidebar-collapse-button`) but was never wired — this is the place to connect it.
+- Team Members nav item: render as non-interactive (greyed out) or `href="#"` since the page doesn't exist in v4.0.
+
+</specifics>
+
+<deferred>
+## Deferred Ideas
+
+- **Sidebar collapse persistence via cookie** — user chose no persistence for Phase 18. v5.0 candidate (RESP-01).
+- **Sidebar responsive collapse on mobile** — v5.0 candidate (RESP-01).
+- **Search functionality** — placeholder only in Phase 18; search is its own future phase.
+- **Notifications / Inbox** — placeholder only; not wired in Phase 18.
+- **Settings page** (`/settings`) — avatar dropdown links to it as a stub; full settings is a future phase.
+
+</deferred>
+
+---
+
+*Phase: 18-App Shell & Navigation*
+*Context gathered: 2026-05-17*
--- a/.planning/phases/18-app-shell-navigation/18-DISCUSSION-LOG.md
+++ b/.planning/phases/18-app-shell-navigation/18-DISCUSSION-LOG.md
@ -0,0 +1,122 @@
+# Phase 18: App Shell & Navigation - Discussion Log
+
+> **Audit trail only.** Do not use as input to planning, research, or execution agents.
+> Decisions are captured in CONTEXT.md — this log preserves the alternatives considered.
+
+**Date:** 2026-05-17
+**Phase:** 18-App Shell & Navigation
+**Areas discussed:** Figma source, Header bar design, Sidebar changes scope
+
+---
+
+## Figma Source
+
+| Option | Description | Selected |
+|--------|-------------|----------|
+| I have a Figma file/link to share | User has both Figma and screenshots | ✓ |
+| I'll describe from memory | No live Figma access | |
+| Screenshots only | Exported screens only | |
+
+**User's choice:** Has both a Figma file and screenshots.
+
+| Option | Description | Selected |
+|--------|-------------|----------|
+| I'll paste the Figma URL now | Figma: https://www.figma.com/design/6z32tx1YhL3nJHlX6M4IA2/XTABLO-Design--bbellev---copie-?node-id=11013-36540 | ✓ |
+| Screenshots in the repo | screenshots/ folder at repo root | ✓ |
+| I'll attach separately | Provide at plan time | |
+
+**User's choice:** Both — Figma URL provided + screenshots/ folder confirmed at repo root.
+
+---
+
+## Header Bar Design
+
+| Option | Description | Selected |
+|--------|-------------|----------|
+| Visual placeholders only | Search + bell = static HTML, no backend | ✓ |
+| Search functional | Wire search to tablo filtering | |
+| Both functional | Wire search + notifications | |
+
+**User's choice:** Visual placeholders only for search and notifications.
+
+---
+
+| Option | Description | Selected |
+|--------|-------------|----------|
+| Add params to AppLayout | Add `pageTitle string` + `breadcrumb []BreadcrumbItem` | ✓ |
+| Use a struct for layout params | Bundle all layout data into `AppLayoutParams` | |
+| Each page renders its own header | Pages include header component directly | |
+
+**User's choice:** Add params to AppLayout.
+
+---
+
+| Option | Description | Selected |
+|--------|-------------|----------|
+| Open dropdown with logout | Small dropdown with settings + logout | ✓ (with specifics) |
+| Link to account/settings | Navigate to profile page | |
+| Non-interactive | Avatar static, logout stays in sidebar | |
+
+**User's choice:** Open dropdown. User provided reference HTML from JS app with specific content:
+- Workspace name + member count row
+- Members list (avatar, name, email)
+- Settings link → `/settings`
+- Logout button (red)
+- **No theme toggle buttons**
+
+---
+
+| Option | Description | Selected |
+|--------|-------------|----------|
+| Global bar only | Top bar = breadcrumb + placeholders + avatar | |
+| Include per-page action slots now | AppLayout gets `headerActions templ.Component` slot | ✓ |
+
+**User's choice:** Include per-page action slots now so downstream phases can fill them in.
+
+---
+
+## Sidebar Changes Scope
+
+| Option | Description | Selected |
+|--------|-------------|----------|
+| Nav items + labels change, structure stays | Update nav list, adjust CSS tokens | |
+| Full rebuild to Figma spec | New HTML structure from scratch | ✓ |
+| CSS-only tweaks | Colors/spacing only | |
+
+**User's choice:** Full rebuild to Figma spec, AND adapt the design system accordingly to keep solid foundations.
+
+---
+
+| Option | Description | Selected |
+|--------|-------------|----------|
+| Match Figma labels exactly | Home/My Tasks/Projects/Events/Team Members | ✓ |
+| Keep Go app routes, update labels only | Rename existing items | |
+| I'll specify the exact mapping | Freeform | |
+
+**User's choice:** Match Figma labels exactly where possible.
+
+---
+
+| Option | Description | Selected |
+|--------|-------------|----------|
+| No — static sidebar only | Skip collapse | |
+| Yes — with cookie persistence | Collapse + persist state | |
+| Yes — without persistence | Collapse, resets on reload | ✓ |
+
+**User's choice:** Implement collapse toggle without persistence (reset on reload).
+
+---
+
+## Claude's Discretion
+
+- Avatar dropdown implementation mechanism (HTMX toggle, `<details>`, inline JS)
+- Exact CSS class naming for new header bar components
+- Whether `BreadcrumbItem` is a struct or string slice
+
+## Deferred Ideas
+
+- Sidebar collapse with cookie persistence → v5.0 (RESP-01)
+- Sidebar responsive/mobile collapse → v5.0 (RESP-01)
+- Search functionality → future phase
+- Notifications / Inbox → future phase
+- Settings page full implementation → future phase