Application Shell & Navigation
Relevant source files
The following files were used as context for generating this wiki page:
The Application Shell provides the foundational user interface and navigational structure for the Timesheet Zone web application. It is built using TanStack Router for file-based routing and organized around a central navigation bar that adapts based on user roles and screen dimensions.
The shell ensures a consistent layout across all authenticated and unauthenticated views, handling core concerns such as theme toggling, user identity display, and high-level routing logic.
Sources: packages/web/src/routes/__root.tsx:1-45, packages/web/README.md:1-25
Root Layout Architecture
The application uses a hierarchical routing structure defined in __root.tsx. The RootDocument provides the base HTML structure, including meta tags, global styles, and a hydration-safe theme initialization script. The RootLayout serves as the primary injection point for the application content via the TanStack Outlet component.
The diagram shows the hierarchical relationship of the root components in the application shell.
Sources: packages/web/src/routes/__root.tsx:11-50, packages/web/src/routeTree.gen.ts:1-100
Navigation Components
AppNavbar
The primary navigation interface is the AppNavbar. It contains the brand identity (Euricom logo), primary application links, administrative tools, and user profile actions.
The navigation is divided into several logical groups:
- Primary Navigation: Links for standard users including Time Entry, Timesheets, and Leave Overview.
- Admin Navigation: Restricted links for users with the
Adminrole, covering Customers, Users, Contracts, and Leave Types. - Utility Actions: Theme toggling (Sun/Moon) and the User Account menu.
| Component | Description | Access Level |
|---|---|---|
EuricomMark | SVG Brand logo linking to home. | Public |
primaryNavItems | Links to /time-entry, /timesheets, and /leave-overview. | Authenticated |
adminNavItems | Links to /admin/customers, /admin/users, etc. | Admin Only |
User Menu | Displays initials, name, and "Sign out" option. | Authenticated |
Sources: packages/web/src/components/app-navbar.tsx:28-40, packages/web/src/components/app-navbar.tsx:111-130, CHANGELOG.md:18-20
Responsive Behavior
The navigation shell implements responsive design patterns to ensure usability across device sizes. On wide screens, admin links are displayed individually in the navbar. On narrower screens (below the 2xl breakpoint), administrative links are collapsed into a "Settings" dropdown menu.
Logic flow for rendering the Admin navigation section based on user role and screen width.
Theme and Appearance
The shell manages the visual appearance of the application through a theme system that supports "light" and "dark" modes.
- Persistence: The theme preference is stored in
localStorage. - Initialization: To prevent "flash of unstyled content" (FOUC), a blocking script in the
<head>ofRootDocumentchecks for a stored theme or system preference before rendering. - Toggle: The
AppNavbarincludes a button that utilizes auseThemehook to switch modes and update the document class list.
Sources: packages/web/src/routes/__root.tsx:29-30, packages/web/src/components/app-navbar.tsx:195-207
Navigation Logic and Routing
Navigation is handled by TanStack Router's Link component, which provides type-safe routing. Active links are visually highlighted using conditional styling in the NavLink component, which checks if the current pathname matches or starts with the item's destination.
// Active link detection logic
const pathname = useLocation({ select: (state) => state.pathname });
const isActive = (to: string) => pathname === to || pathname.startsWith(to + '/');
Sources: packages/web/src/components/app-navbar.tsx:75-88, packages/web/src/components/app-navbar.tsx:107-109
Sidebar System
While the application currently prioritizes a top navbar (updated 2026-05-18), a comprehensive Sidebar system is available as a UI primitive. It follows the shadcn/ui pattern, providing components for structured vertical navigation.
| Sidebar Component | Purpose |
|---|---|
SidebarProvider | Context provider setting the default --sidebar-width (16rem). |
SidebarInset | Main content wrapper when a sidebar is present. |
SidebarMenuButton | Specialized button for menu items with active state support. |
Sources: packages/web/src/components/ui/sidebar.tsx:7-15, packages/web/src/components/ui/sidebar.tsx:78-100, CHANGELOG.md:18-20
Summary
The Application Shell & Navigation system provides a robust, responsive framework for the Timesheet Zone frontend. By centralizing layout, routing logic, and theme management within the __root layout and AppNavbar, the project maintains a consistent user experience while enforcing role-based access to administrative functionality.