feat: add clickable breadcrumbs and contextual help system

[AlexVOiceover]

Overview

Replaces static view headers with clickable breadcrumb navigation, providing users with clear navigation context and the ability to jump back to previous levels.

---

Changes

Breadcrumb Navigation

• Created Breadcrumb.svelte component with context-aware navigation logic
• Replaced page titles with clickable breadcrumb paths (Dashboard → Categories → Response)
• Integrated with existing app state management using setViewName and setList contexts
• Styled breadcrumbs to match header design with title-sized text

Navigation Paths Supported

• Dashboard (always visible as starting point)
• Dashboard → Actions/Resources/Responses (for list views)
• Dashboard → Category Name (for question lists)
• Dashboard → Category → Response (for response details)
• Dashboard → Email Preview (for email view)

Layout Updates

• Simplified ViewHeader component by removing redundant title display
• Added breadcrumb-specific CSS classes in app.css
• Ensured breadcrumbs are always visible (minimum shows current page)

---

Closes #51

[claude]

Claude encountered an error —— View job

---

Claude Code is reviewing the pull request…

Todo List:

• Read project conventions from CLAUDE.md
• Review breadcrumb navigation implementation
• Review help system components and architecture
• Check security considerations
• Assess performance implications
• Check test coverage
• Provide comprehensive feedback

[claude]

Claude finished @AlexVOiceover's task —— View job

---

Code Review: Breadcrumb Navigation and Help System

Overview

This PR successfully implements a breadcrumb navigation system and contextual help feature. The code is well-structured and follows most project conventions, though there are some areas for improvement.

✅ Strengths

Code Quality & Architecture

• Clean component design: The Breadcrumb.svelte, HelpButton.svelte, and HelpModal.svelte components are well-separated with clear responsibilities
• Context-based state management: Proper use of Svelte context API aligns with the project's architecture patterns
• TypeScript usage: Strong typing with proper interfaces and type definitions
• Accessibility features: Good implementation of ARIA labels, focus management, and keyboard navigation

User Experience

• Intuitive navigation: Breadcrumbs provide clear visual hierarchy and navigation paths
• Context-aware help: Help content dynamically adjusts based on the current view
• Responsive design: Proper styling with TailwindCSS classes that adapt to different screen sizes

⚠️ Areas for Improvement

1. Security Considerations

Issue: The help content is loaded from a static JSON file without validation

// src/lib/services/helpContent.ts:11
const response = await fetch('/help/content/help-content.json');

Recommendation: Add content validation to prevent potential XSS if the JSON file is compromised:

function validateHelpContent(content: unknown): HelpContentMap {
  // Add validation logic here
  // Ensure all text fields are properly sanitized
  return content as HelpContentMap;
}

2. Performance Optimizations

Issue: The breadcrumb items are recalculated on every render

// src/lib/components/ui/Breadcrumb.svelte:18
const breadcrumbItems = $derived(() => {
  // Complex logic recalculated each time
});

Recommendation: Consider memoizing the breadcrumb calculation or using a more efficient derivation pattern since the app state changes infrequently.

3. Focus Management Bug

Issue: The HelpModal uses document.body.inert which affects the entire page

// src/lib/components/ui/HelpModal.svelte:20
document.body.inert = true;

Recommendation: Use the modal's parent container or create a specific overlay:

const modalContainer = dialog.parentElement;
if (modalContainer) {
  // Set siblings as inert, not the entire body
  Array.from(modalContainer.children).forEach(child => {
    if (child !== dialog) child.inert = true;
  });
}

4. Missing Error Boundaries

Issue: No error handling for failed help content loads

// src/lib/components/ui/HelpButton.svelte:73
try {
  helpContent = await getHelpContent(context as HelpContextKey);
  showHelpModal = true;
} catch (error) {
  console.error('Failed to load help content:', error);
  // No user feedback
}

Recommendation: Add user-friendly error messaging:

} catch (error) {
  console.error('Failed to load help content:', error);
  // Show a toast or inline error message
  helpContent = {
    title: 'Help Unavailable',
    sections: [{
      text: 'Unable to load help content. Please try again later.'
    }]
  };
  showHelpModal = true;
}

5. Test Coverage

Critical Gap: No tests were added for the new components. The project requires 80% coverage for critical paths.

Required Tests:

• Breadcrumb.svelte: Test navigation logic and different view states
• HelpButton.svelte: Test context detection and modal triggering
• HelpModal.svelte: Test focus trap and keyboard navigation
• helpContent.ts: Test loading, caching, and fallback behavior

Example test structure:

// src/lib/components/ui/Breadcrumb.test.ts
import { describe, test, expect } from 'vitest';
import { render, screen } from '@testing-library/svelte';
import Breadcrumb from './Breadcrumb.svelte';

describe('Breadcrumb', () => {
  test('shows Dashboard as first breadcrumb', () => {
    // Test implementation
  });
  
  test('navigates correctly when clicking breadcrumb links', () => {
    // Test implementation
  });
});

🐛 Potential Bugs

Edge Cases

1. Race condition in HelpModal: If the modal is closed quickly after opening, the focus restoration might fail
2. Missing null check: In Breadcrumb.svelte:23, accessing app.list.category.format without checking if category exists
3. Tooltip conflict: The HelpButton uses a Tooltip which might interfere with the modal's focus management

📋 Checklist Review

Based on project standards:

• ✅ Code style and formatting
• ✅ Naming conventions (PascalCase components, camelCase functions)
• ✅ Architecture patterns (context-based state)
• ⚠️ Error handling (needs improvement)
• ❌ Test coverage (missing)
• ✅ Documentation (inline comments could be better)
• ✅ Accessibility (WCAG 2.2 AA compliant with minor fixes needed)

Recommendations

1. Add comprehensive tests for all new components
2. Implement proper error boundaries for the help system
3. Fix the focus management to avoid affecting the entire document
4. Add loading states for better UX when fetching help content
5. Consider lazy loading the help content to improve initial load performance

The implementation is solid overall, but addressing these issues will ensure the feature is production-ready and maintains the high quality standards of the project.

[claude]

Claude finished @AlexVOiceover's task —— View job

---

Code Review: Breadcrumb Navigation and Help System

Overview

This PR implements a breadcrumb navigation system and contextual help feature. The implementation follows most project conventions and shows thoughtful design, though there are several areas that need attention before merging.

✅ Strengths

Code Architecture & Patterns

• Clean component separation: Breadcrumb.svelte, HelpButton.svelte, and HelpModal.svelte follow SRP
• Context-based state management: Proper use of Svelte contexts aligns with project architecture (getApp, setViewName, setList)
• TypeScript implementation: Strong typing with interfaces and proper type imports
• Follows naming conventions: PascalCase for components, camelCase for functions and variables

User Experience

• Clear navigation hierarchy: Breadcrumbs provide intuitive navigation paths
• Context-aware help: Help content dynamically adjusts based on current view
• Professional help content: Well-written, comprehensive help text for all sections
• Responsive design: Proper use of TailwindCSS classes

⚠️ Critical Issues

1. Missing Test Coverage

Issue: No tests were added for any of the new components, violating the 80% coverage requirement for critical paths.

Required tests:

// src/lib/components/ui/Breadcrumb.test.ts
describe('Breadcrumb', () => {
  test('renders Dashboard as first item')
  test('navigates correctly on click')
  test('shows correct path for each view state')
  test('handles null category gracefully')
})

// src/lib/components/ui/HelpButton.test.ts
describe('HelpButton', () => {
  test('opens modal on click')
  test('shows loading state')
  test('handles loading errors')
  test('determines correct context')
})

// src/lib/components/ui/HelpModal.test.ts
describe('HelpModal', () => {
  test('focus trap works correctly')
  test('closes on Escape key')
  test('restores focus on close')
  test('renders help content correctly')
})

2. Security Vulnerabilities

Issue: Help content loaded from JSON without validation

// src/lib/services/helpContent.ts:11
const response = await fetch('/help/content/help-content.json');
helpContentCache = await response.json(); // No validation

Fix: Add content validation

function validateHelpContent(content: unknown): HelpContentMap {
  // Validate structure and sanitize text fields
  // Prevent XSS if JSON is compromised
  return content as HelpContentMap;
}

helpContentCache = validateHelpContent(await response.json());

3. Focus Management Bug

Issue: Using document.body.inert = true affects entire page unnecessarily

// src/lib/components/ui/HelpModal.svelte:20
document.body.inert = true; // Too broad

Fix: Target modal siblings only

const modalBackdrop = dialog.closest('.modal');
if (modalBackdrop?.parentElement) {
  Array.from(modalBackdrop.parentElement.children).forEach(child => {
    if (child !== modalBackdrop) child.inert = true;
  });
}

4. Potential Runtime Error

Issue: Accessing category without null check

// src/lib/components/ui/Breadcrumb.svelte:22
const categoryFormat = app.list.category?.format;
// Later at line 36:
if (listTable === 'questions' && categoryFormat) { // Good
// But potential issues if category object structure changes

Recommendation: Add defensive checks throughout

🔧 Performance Considerations

Optimization Opportunities

1. Breadcrumb recalculation: The breadcrumbItems derivation runs on every render. Consider memoization since app state changes infrequently.

2. Help content caching: Good use of module-level cache, but consider localStorage for persistence across sessions.

3. Modal rendering: Currently renders conditionally. Consider portal approach for better performance.

📝 Code Quality Issues

Minor Improvements

1. Error handling: Help loading errors only log to console - add user feedback
2. Loading state: Consider skeleton loader instead of "..." text
3. Accessibility: Add aria-current="page" to current breadcrumb item
4. CSS organization: Breadcrumb styles well-organized in app.css

✅ Compliance Assessment

Based on project standards:

• ✅ Code style and formatting - Follows conventions
• ✅ Naming conventions - PascalCase components, camelCase functions
• ✅ Architecture patterns - Context-based state management
• ⚠️ Error handling - Needs user feedback for failures
• ❌ Test coverage - No tests provided
• ✅ Documentation - Code is self-documenting
• ⚠️ Accessibility - Minor improvements needed

Recommendations Before Merge

1. Add comprehensive test suite for all new components
2. Fix security vulnerability in help content loading
3. Improve focus management in modal
4. Add error boundaries with user feedback
5. Consider adding loading skeletons for better UX

The implementation shows good understanding of the codebase and follows most conventions. However, the missing tests and security concerns must be addressed before merging.

Todo List:

• Read project conventions from CLAUDE.md
• Review breadcrumb navigation implementation
• Review help system components and architecture
• Check security considerations
• Assess performance implications
• Check test coverage
• Provide comprehensive feedback