ui/_docs/02_document/modules/src__components__Header.md

Module: src/components/Header.tsx

Source: src/components/Header.tsx (133 lines) Topo batch: B4 (depends on B3: auth/AuthContext, components/FlightContext, components/HelpModal, types/index)

Purpose

The persistent top navigation bar of the authenticated SPA. Combines five concerns into one component: brand mark, currently-selected-flight dropdown, top-level navigation links (permission-gated), session info (user email + Logout), language toggle (EN ↔ UA), and a ? button that opens HelpModal. Also renders a duplicate bottom-nav on the mobile breakpoint. Replaces the legacy WPF top ribbon + window chrome (_docs/legacy/wpf-era.md §4 / §"What survived").

Public interface

export default function Header(): JSX.Element

No props — Header reads everything it needs from AuthContext, FlightContext, and react-i18next. Mounted exactly once in App.tsx above the protected route tree.

Internal logic

• Local state:

  • showDropdown: boolean — flight selector open/closed.
  • filter: string — text filter for the flight selector list.
  • showHelp: boolean — controls the HelpModal open prop.
  • dropdownRef: RefObject<HTMLDivElement> — used to detect outside clicks.

• Outside-click effect: registers a mousedown listener on document while mounted; if the event target is not inside dropdownRef.current, closes the dropdown. Listener is removed on unmount. (Always-on, even while the dropdown is closed — cheap, but not the most surgical pattern; flag to consider gating on showDropdown in Step 8.)

• Filtered flights: flights.filter(f => f.name.toLowerCase().includes(filter.toLowerCase())) — case-insensitive substring match on the flight name. Empty filter shows everything.

• Logout: await logout(); navigate('/login'). Always navigates, even if logout() throws (it never does — AuthContext.logout swallows network errors by design).

• Language toggle: i18n.changeLanguage(i18n.language === 'en' ? 'ua' : 'en'). Same two-language assumption as HelpModal (treats every non-'ua' value as English-equivalent). The toggle button label is the target language ("UA" while EN is active, "EN" while UA is active).

• Permission-gated nav (navItems):

  to	label key	perm
  /flights	nav.flights	FL
  /annotations	nav.annotations	ANN
  /dataset	nav.dataset	DATASET
  /admin	nav.admin	ADM

  Settings (/settings) is always rendered — no permission gate. Filter applied via navItems.filter(n => hasPermission(n.perm)).

• Layout: a single <header> containing brand → flight dropdown → primary nav (hidden sm:flex) → spacer (flex-1) → user email (hidden sm:block) → language toggle → ? → ⚙ (settings link) → logout button. A second <nav> element below is sm:hidden and positions itself fixed at the bottom of the viewport — the mobile nav. Both navs share the same filter logic.

Dependencies

• Internal:
  • ../auth/AuthContext — useAuth (user, logout, hasPermission).
  • ./FlightContext — useFlight (flights, selectedFlight, selectFlight).
  • ./HelpModal — opens on ? click.
  • ../types — Flight type for the dropdown row.
• External: react-router-dom (NavLink, useNavigate), react-i18next (useTranslation), react (useState, useRef, useEffect).

Consumers (intra-repo)

• src/App.tsx — mounted inside ProtectedRoute → FlightProvider.

No other intra-repo consumer; Header is a top-level chrome component.

Data models

The navItems array is a module-private literal of { to: string; label: string; perm: string }. The filtered flights list is Flight[] (from types/index.ts).

Configuration

• i18n keys consumed: nav.flights, nav.annotations, nav.dataset, nav.admin, nav.logout. (Verified to exist in src/i18n/en.json.) The filter placeholder ("Filter…") and the empty-state ("— Select Flight —", "No flights") are hardcoded strings — flag for Step 4.
• Tailwind tokens: bg-az-header, border-az-border, bg-az-panel, text-az-text, text-az-muted, text-az-orange, text-az-red, bg-az-bg. Defined in src/index.css.
• Breakpoint: sm: from Tailwind defaults to 640px — matches the responsive-breakpoint spec in _docs/ui_design/README.md.
• Permission strings: FL, ANN, DATASET, ADM. Backend-defined by the admin/ service; treated as opaque strings here.

External integrations

None directly. Triggers logout() which calls POST /api/admin/auth/logout inside AuthContext, and selectFlight() which calls PUT /api/annotations/settings/user inside FlightContext.

Security

• hasPermission(perm) is client-side advisory — a user with the /admin route URL can navigate there without going through the nav link. The backend admin/ service is the authority. Document in security_approach.md (Step 6).
• The flight-selector dropdown displays every flight returned by GET /api/flights?pageSize=1000 — there is no permission check here. If flights/ ever returns flights the user should not see, this component would leak them. Trust the backend filter.
• user?.email is rendered raw in the header — React JSX-escapes it, so XSS via a malicious email is not possible at this layer, but validate that the admin/ service enforces email format.

Tests

None.

Notes / open questions

• Outside-click listener is always attached — slightly wasteful when the dropdown is closed. Gating on showDropdown would also remove a closure capture. Defer to Step 8.
• Dropdown is not keyboard-accessible: no role="combobox", no aria-expanded, no Esc-to-close, focus does not move into the filter input on open beyond autoFocus (which works only the first time the input mounts). Flag against _docs/ui_design/README.md keyboard shortcuts for Step 4.
• Mobile bottom nav duplicates navItems twice in source — DRY win by extracting a <NavSet items={...}/> subcomponent, but a deferral candidate.
• Hardcoded English strings ("AZAION", "— Select Flight —", "Filter...", "No flights"). Brand mark is intentional; the others are content and should move to nav.* keys. Step 4 candidate.
• /settings link is unguarded by hasPermission. Per _docs/ui_design/README.md settings page is available to every authenticated user — confirmed intent.
• new Date(f.createdDate).toLocaleDateString() uses the browser's default locale, not i18n.language. Mild inconsistency; Step 8 cosmetic.
• flights cache truncation: the dropdown shows at most 1000 flights because of the hardcoded pageSize=1000 in FlightContext. Documented as a flag there; Header inherits the limitation.