Skip to main content

PRD: Overview Tab Nested Navigation

Issue: #258 (Enhancement)
Status: Draft
Created: 2025-11-01
Author: AI Assistant

Overview​

Restructure the page viewer tab navigation by nesting Explanation and Transcript tabs within the Overview tab, creating a more intuitive and organized user experience for viewing different types of page content.

Problem Statement​

Current State​

The page viewer has five root-level tabs:

  1. Overview - Page metadata, summary, and compliance summary
  2. Preview - PDF preview with annotations
  3. Compliance - Detailed compliance reports
  4. Details - AI-generated page explanation (issue #258)
  5. Raw Markdown - Raw page.md transcript

Current URL Pattern:

/projects/:planId/files/:fileId/pages/:pageNumber/:tab

Example:

https://test.m3.codeproof.app/projects/san-jose-multi-file3/files/1/pages/1/details
https://test.m3.codeproof.app/projects/san-jose-multi-file3/files/1/pages/1/raw-markdown

Problems​

  1. Flat Navigation: All tabs at the same level creates cognitive overhead
  2. Unclear Relationships: Details and Raw Markdown are both "text views" of the page, but their relationship to Overview is unclear
  3. Tab Clutter: Five root-level tabs feels crowded
  4. Naming Confusion:
    • "Details" doesn't clearly communicate its purpose (AI-generated explanation)
    • "Raw Markdown" is too technical for non-developer users
  5. Navigation Friction: Users must switch between root-level tabs to see different representations of the same page content

Solution​

Proposed Structure​

Root-Level Tabs (non-closeable):

  1. Overview - Contains nested sub-tabs (see below)
  2. Preview - PDF preview (unchanged)
  3. Compliance - Detailed compliance reports (unchanged)
  4. Dynamic tabs (closeable) - Individual compliance section reports

Nested Tabs within Overview (non-closeable):

  1. Explanation (default) - AI-generated page explanation
  2. Transcript - Raw page.md content
  3. Compliance - Compliance summary (existing overview content)

New URL Pattern​

/projects/:planId/files/:fileId/pages/:pageNumber/overview#subtab

Examples:

https://test.m3.codeproof.app/projects/san-jose-multi-file3/files/1/pages/1/overview#explanation
https://test.m3.codeproof.app/projects/san-jose-multi-file3/files/1/pages/1/overview#transcript
https://test.m3.codeproof.app/projects/san-jose-multi-file3/files/1/pages/1/overview#compliance
https://test.m3.codeproof.app/projects/san-jose-multi-file3/files/1/pages/1/overview (defaults to #explanation)

Why Fragments?

  • Semantically correct (fragments are for page sections)
  • Natural default behavior (no fragment = default tab)
  • Simpler implementation (no nested routing)
  • Browser history still works
  • Cleaner, more intuitive URLs

Legacy root-level URLs redirect to fragment-based equivalents:

  • /pages/1/details → /pages/1/overview#explanation
  • /pages/1/raw-markdown → /pages/1/overview#transcript
  • /pages/1/overview → /pages/1/overview (defaults to #explanation)

Visual Hierarchy​

┌─────────────────────────────────────────────────────────────┐
│ [Overview] [Preview] [Compliance] [Section 1234.5 ×]        │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  Page Title: Foundation Plan                                │
│  Page #: 1        Sheet ID: A-1.0                           │
│  Summary: Shows foundation layout and structural details... │
│                                                              │
│  ┌───────────────────────────────────────────────────────┐ │
│  │ [Explanation] [Transcript] [Compliance]               │ │
│  ├───────────────────────────────────────────────────────┤ │
│  │                                                        │ │
│  │  [Content based on selected sub-tab]                  │ │
│  │                                                        │ │
│  │  Explanation: AI-generated educational content        │ │
│  │  Transcript: Raw page.md text                         │ │
│  │  Compliance: Compliance summary (existing)            │ │
│  │                                                        │ │
│  └───────────────────────────────────────────────────────┘ │
│                                                              │
└─────────────────────────────────────────────────────────────┘

User Stories​

Story 1: View Nested Tabs in Overview​

As a project reviewer
I want to see Explanation, Transcript, and Compliance as nested tabs within Overview
So that I can easily navigate between different text representations of the page

Acceptance Criteria:

  • Overview tab contains a nested tab group
  • Nested tabs show: Explanation (default), Transcript, Compliance
  • Nested tabs are non-closeable
  • Explanation tab is selected by default when navigating to a page
  • Tab selection persists in URL and browser history
  • Back/forward navigation works correctly

Story 2: Renamed Tabs with Clear Purpose​

As a non-technical user
I want to see clear, descriptive tab names
So that I understand what content each tab contains

Acceptance Criteria:

  • "Details" is renamed to "Explanation"
  • "Raw Markdown" is renamed to "Transcript"
  • Tab names are visible and readable in the UI
  • Tooltips (optional) provide additional context

Story 3: Updated URL Structure​

As a user sharing links
I want to use URLs that reflect the nested structure
So that shared links navigate to the correct nested tab

Acceptance Criteria:

  • URLs follow pattern: /pages/:pageNumber/overview#subtab
  • Valid fragments: explanation, transcript, compliance
  • Default behavior: no fragment or invalid fragment shows explanation tab
  • Fragment changes update URL and browser history
  • Legacy URLs redirect correctly:
    • /pages/1/details → /pages/1/overview#explanation
    • /pages/1/raw-markdown → /pages/1/overview#transcript
    • /pages/1/overview → /pages/1/overview (defaults to explanation)

Story 4: Migrate Compliance Summary Content​

As a developer
I want to move the compliance summary section into the Compliance nested tab
So that the Overview tab structure is clean and organized

Acceptance Criteria:

  • Existing compliance summary section removed from Overview root
  • Compliance summary content rendered in Compliance nested tab
  • Styling and formatting preserved
  • Loading states preserved
  • Error handling preserved

Story 5: Preserve Root-Level Tab Behavior​

As a user
I want to see unchanged behavior for Preview and Compliance tabs
So that my existing workflows are not disrupted

Acceptance Criteria:

  • Preview tab remains at root level (unchanged)
  • Compliance tab remains at root level (unchanged)
  • Dynamic compliance report tabs remain closeable
  • Tab indices 0-2 remain non-closeable

Technical Scope​

Components to Modify​

  1. TabService (web-ng-m3/src/app/shared/tab.service.ts)

    • Remove Details and Raw Markdown from root tabs
    • Keep only: Overview, Preview, Compliance

  2. OverviewComponent (web-ng-m3/src/app/components/project/pages/overview/)

    • Add nested mat-tab-group
    • Create three nested tabs: Explanation, Transcript, Compliance
    • Subscribe to route.fragment for tab selection
    • Update URL fragment on tab change
    • Migrate compliance summary content to Compliance nested tab

  3. MainViewComponent (web-ng-m3/src/app/components/project/main-view/)

    • Add legacy URL redirect logic (details → overview#explanation, etc.)

Components to Reuse​

  1. DetailsComponent - Reused for Explanation nested tab
  2. RawMarkdownComponent - Reused for Transcript nested tab
  3. Existing compliance summary HTML - Moved to Compliance nested tab

Out of Scope​

  • Changes to Preview tab
  • Changes to Compliance tab (root-level)
  • Changes to dynamically added compliance report tabs
  • Changes to drawer/navigation sidebar
  • Backend API changes
  • Mobile responsiveness (handled by Material Design)
  • Nested routing configuration (using fragments instead)

Success Metrics​

User Experience​

  • Reduced Navigation Clicks: Users can view all page text content within Overview tab
  • Clearer Information Architecture: Nested tabs communicate content relationships
  • Improved Discoverability: Default to Explanation tab highlights AI-generated content

Technical Quality​

  • URL Consistency: All URLs follow nested pattern
  • Zero Broken Links: Legacy URLs redirect correctly
  • Preserved Functionality: All existing features work as before
  • Performance: No degradation in tab switching speed

Design Considerations​

Tab Naming Rationale​

Old NameNew NameRationale
DetailsExplanation"Explanation" clearly communicates AI-generated educational content
Raw MarkdownTranscript"Transcript" is more accessible and describes the content (extracted text)
(Compliance Summary Section)ComplianceNested tab name aligns with root-level Compliance tab

Default Tab Selection​

Explanation is the default nested tab because:

  1. It provides the most value to end users (AI-generated, beginner-friendly)
  2. Issue #258 positions it as a primary feature
  3. Compliance summary is still accessible, just one click away
  4. Transcript is for advanced/debugging use cases

URL Structure Philosophy​

URL Fragments (/overview#explanation) are preferred over path segments (/overview/explanation) or query params (/overview?tab=explanation) because:

  1. Semantically correct: Fragments are designed for in-page navigation
  2. Simpler routing: No nested routes needed - single route handles all cases
  3. Natural defaults: /overview works without fragment, defaults to first tab
  4. Browser history: Fragment changes still create history entries
  5. Less code: ~80% less routing configuration code
  6. Cleaner URLs: Clearly indicates UI state within the same view
  7. Standard pattern: Common for tab navigation in web apps

Migration Plan​

Phase 1: Frontend Updates (Week 1)​

  1. Update TabService (remove Details and Raw Markdown tabs)
  2. Modify OverviewComponent with nested tabs and fragment handling
  3. Add legacy URL redirects in MainViewComponent
  4. Update tab naming (Details → Explanation, Raw Markdown → Transcript)

Phase 2: Testing (Week 1)​

  1. Manual testing of all tab combinations
  2. Test URL navigation (direct, back/forward)
  3. Test legacy URL redirects
  4. Verify no regressions in Preview/Compliance tabs
  5. Cross-browser testing

Phase 3: Deployment (Week 2)​

  1. Deploy to test environment
  2. User acceptance testing
  3. Fix any issues
  4. Deploy to production
  5. Monitor for errors

Risks and Mitigations​

RiskImpactMitigation
Users bookmark legacy URLsMediumAdd permanent redirects
Nested routing breaks existing functionalityHighComprehensive testing, feature flags
URL structure confuses usersLowURLs are transparent and semantic
Performance degradationLowLazy-load tab content, use Angular best practices

Open Questions​

  1. Q: Should the root-level Overview tab be renamed to something else (e.g., "Page Info")?
    A: TBD - Gather user feedback during design review

  2. Q: Should we add tooltips to nested tabs?
    A: Optional enhancement - implement if user testing shows confusion

  3. Q: What happens if user navigates to /overview without a fragment?
    A: ✅ RESOLVED - Defaults to showing Explanation tab (no redirect needed)

Future Enhancements​

  1. Collapsible Page Metadata: Make page metadata (title, number, summary) collapsible to save vertical space
  2. Tab Icons: Add icons to nested tabs for visual clarity
  3. Keyboard Shortcuts: Add keyboard shortcuts for tab navigation
  4. Tab State Persistence: Remember user's last selected nested tab per page
  5. Mobile Optimization: Optimize nested tab UX for mobile devices

References​