Navigation & Layout

Relevant source files

The following files were used as context for generating this wiki page:

• src/components/BottomNav.tsx
• src/components/Sidebar.tsx
• src/app/(app)/layout.tsx
• ios-shell/www/app.js
• e2e/specs/07-mobile-responsive.spec.ts
• src/lib/modules/registry.ts

Navigation in Hearth adapts to the user's device type and configured modules. The system uses a responsive design that provides a persistent sidebar for desktop viewports and a bottom navigation bar with an overflow "More" menu for mobile devices. Both interfaces dynamically filter navigation items based on the household's enabled modules and feature configurations.

Sources: src/components/Sidebar.tsx:32-34, src/components/BottomNav.tsx:43-45, e2e/specs/07-mobile-responsive.spec.ts:133-135

Core Navigation Structure

The application organizes navigation items into three primary functional groups: Dashboard, Modules, and Tools. This grouping ensures consistent categorization across all UI implementations.

Component Architecture

The navigation system relies on several key components and logic handlers:

• Sidebar: Displays as a vertical column on screens wider than the md breakpoint (768px). It organizes items into labeled sections.
• BottomNav: Acts as the primary navigation for mobile devices. It promotes four high-frequency destinations and places all other items into a "More" dialog.
• getNavItems: A utility function that returns the list of accessible routes based on enabledModules and chatConfigured status.
• isActive: A helper function that determines the active state of a link by comparing the current pathname with the link's href.

Sources: src/components/Sidebar.tsx:11-34, src/components/BottomNav.tsx:43-70, e2e/specs/07-mobile-responsive.spec.ts:133-138

Desktop Layout (Sidebar)

On desktop viewports, the Sidebar component provides quick access to all system areas. It is hidden on small screens using Tailwind's hidden md:flex classes.

Mobile Navigation & Responsiveness

Hearth implements a specialized mobile navigation strategy to maintain usability on small screens. The BottomNav component ensures that critical actions remain within thumb reach.

Primary Mobile Destinations

The mobile bar promotes a fixed set of high-frequency links:

1. Dashboard: The central overview.
2. Contracts: Always-on household records.
3. Warranties: Always-on product records.
4. Documents: Direct access to the document explorer and Inbox.

Sources: src/components/BottomNav.tsx:21-26

The "More" Menu

Destinations not included in the primary bar are moved to an overflow sheet. This includes optional modules like Travel, Home, and Wealth, as well as secondary tools like Spending and the AI Assistant.

Responsive Header and Actions

Lists and detail pages adjust their headers for mobile viewports. On mobile, list-page headings occupy their own line, while "Export" actions move into an overflow menu (vertical ellipsis) to prevent horizontal overflow.

Sources: e2e/specs/07-mobile-responsive.spec.ts:168-185

Module-Based Navigation Filtering

Navigation is dynamic; it reacts to the ModuleEnablement table. When a module is disabled, its corresponding navigation entry is hidden from all menus, though the data remains in the database.

Group	Nav Item	Required Condition
Dashboard	Dashboard	Always On
Modules	Contracts	Always On
Modules	Warranties	Always On
Modules	Travel	TRAVEL module enabled
Modules	Home	HOME module enabled
Modules	Vehicles	VEHICLES module enabled
Modules	Wealth	WEALTH module enabled
Tools	Documents	Always On
Tools	Assistant	AI Assistant configured

Sources: src/lib/modules/registry.ts, src/components/Sidebar.tsx:35-37, src/lib/help/faq.ts:25-28

Document Inbox Integration

The navigation system integrates real-time feedback for the document management system. Both the Sidebar and BottomNav display an InboxCountBadge on the Documents link if there are unfiled documents.

• Logic: The count represents items in the inboxDocument table with a NEEDS_REVIEW status.
• Accessibility: The link's aria-label is dynamically updated to include the inbox count (e.g., "Documents, 5 in Inbox").

Sources: src/components/Sidebar.tsx:98-103, src/components/BottomNav.tsx:103-107, e2e/specs/07-mobile-responsive.spec.ts:316-335

Native Shell Navigation (Capacitor)

The mobile shell (ios-shell/www/app.js) implements a "Standalone" mode that replicates the web application's navigation structure for offline use. It uses a custom render() function to swap view content based on the state.route variable.

State Route	View Title	Description
dashboard	Dashboard	Main landing with attention items.
records	[Type Label]	Filtered list of records (e.g., Contracts).
documents	Documents	Local document storage explorer.
more	More	Grid of enabled modules and tools.
search	Search	Global search for local records.

Sources: ios-shell/www/app.js:525-560, ios-shell/www/app.js:585-610

The navigation and layout system prioritizes access to household records while maintaining a clean interface through device-specific components and conditional rendering based on household configuration.