@avament-pub/navbar-ui

Self-contained Avament navbar UI for React / Next.js apps — no @/ imports, no stores, no API calls. Host provides labels, routes, project data, and theme CSS.

| | | |---|---| | Package | @avament-pub/navbar-ui | | React | ≥ 18 (peer) | | Dependency | lucide-react | | License | MIT |

Table of contents

1. Install
2. Quick start
3. Layout structure
4. Feature flags
5. Project picker modes
6. Logo
7. Weather
8. Lang / theme
9. Host binding checklist
10. Host slots
11. RTL
12. Theming / CSS
13. Exports

1. Install

npm install @avament-pub/navbar-ui

yarn add @avament-pub/navbar-ui
pnpm add @avament-pub/navbar-ui

Requirements

• React 18+ / React DOM 18+
• Client component in Next.js App Router ("use client" is included in the bundle)

Optional (Next.js App Router):

transpilePackages: ["@avament-pub/navbar-ui"];

2. Quick start

import { Navbar } from "@avament-pub/navbar-ui";
import Link from "next/link";

<Navbar
  pathname={pathname}
  dir="ltr"
  labels={{ selectAProject: "Select a project", /* … */ }}
  routes={{
    home: "https://avament.com/home",
    settings: "/settings",
    support: "https://support.avament.com",
  }}
  logo={{ src: "/logos/main.svg", href: "https://avament.com/home" }}
  projectPicker={{
    mode: "interactive",
    selectedProjectId,
    selectedProjectName,
    projects,
    onSelect: handleProjectSelect,
  }}
  LinkComponent={Link}
/>

3. Layout structure

Main site and sub-sites share one bar structure. The package owns placement — hosts only wire props.

Desktop (fixed order):

| Left | Right | |------|-------| | Nav actions · optional beside picker · project picker | theme · language · trailingSlot · logo |

Weather renders centered in the bar (desktop) when features.weather is enabled on the main home layout.

Nav actions depend on layout + page:

| Mode | Left icons | |------|------------| | Main home (layout="default", /home) | Support · settings | | Main inner pages | Back · settings · home | | Sub-sites (layout="submodule") | Back · settings · home | | Submodule + features.support: true | Back · support · settings · home |

Optional beside project picker (left group, before picker):

1. moduleLabel — pill tag (e.g. "AVAMENT-Intern")
2. context — External / Internal segmented control
3. projectPickerLeadingSlot — any custom UI

// Main website (home)
<Navbar
  pathname="/home"
  isHomeLayout
  features={{ weather: true, support: true }}
  projectPicker={{ mode: "interactive", … }}
  weather={forecast}
  logo={logo}
  /* … */
/>

// Sub-site (ticket, check, …)
<Navbar
  layout="submodule"
  pathname={pathname}
  moduleLabel="AVAMENT-Intern"
  context={{
    value: visibility,
    onChange: setVisibility,
    options: [
      { value: "external", label: "External" },
      { value: "internal", label: "Internal" },
    ],
  }}
  projectPicker={{ mode: "interactive", … }}
  features={{ langTheme: true }}
  langTheme={{ language, onLanguageChange, theme, onThemeChange, isDarkMode }}
  trailingSlot={<CreateTicketButton />}
  onBack={() => {
    if (pathname === "/") window.location.href = routes.landing ?? "https://avament.com";
    else router.back();
  }}
  /* …labels, routes, logo, LinkComponent */
/>

trailingSlot: app-only actions before the logo (Create batch, Create ticket).

Use contextSlot or projectPickerLeadingSlot only when built-in options are not enough.

4. Feature flags

| Prop | Default | Effect | |------|---------|--------| | features.weather | false | Center weather strip (desktop, home layout) | | features.support | main home: yes; submodule: no (set true to show) | Headset support link in nav actions | | features.langTheme | false | Language + theme pickers (desktop) | | features.topicPill | false | Read-only topic pill | | features.actions | true | Settings / home / back icons |

5. Project picker modes

| Mode | UI | |------|-----| | interactive | Dropdown with chevron, clickable | | readonly | Label only — no chevron, not clickable | | hidden | Not rendered |

projectPicker={{
  mode: "readonly",
  selectedProjectId: "uuid",
  selectedProjectName: "Project Alpha",
}}

6. Logo

Static:

logo={{ src: "/logos/check.svg", href: "https://check.avament.com", alt: "Check" }}

Dynamic:

logo={{
  resolve: ({ pathname }) => ({
    src: pathname.startsWith("/check") ? "/logos/check.svg" : "/logos/main.svg",
    href: pathname === "/home" ? "https://avament.com/landing" : "https://avament.com/home",
  }),
}}

7. Weather

Host fetches data; UI only renders:

features={{ weather: true }}
weather={{
  days: forecast.days,
  locationLabel: forecast.locationLabel,
  timezone: forecast.timezone,
  locale: "de",
}}

8. Lang / theme

Controlled pickers — host persists changes:

features={{ langTheme: true }}
langTheme={{
  language: "de",
  onLanguageChange: (lang) => updateSettings({ language: lang }),
  theme: "dark",
  onThemeChange: (theme) => updateSettings({ theme }),
  isDarkMode: true,
}}

9. Host binding checklist

1. Pass labels from your i18n (t() → object). See REQUIRED_NAVBAR_LABEL_KEYS / OPTIONAL_NAVBAR_LABEL_KEYS exports.
2. Wire projectPicker.onSelect → your auth / project-switch flow.
3. Pass navigationBlocked when unsaved/import/edit guards are active.
4. Provide LinkComponent (Next.js Link) or use onNavigate with your router.
5. Implement onBack for back-button behavior.
6. Include theme CSS (see Theming / CSS).

10. Host slots

| Prop | Use | |------|-----| | moduleLabel | Built-in pill beside project picker | | context | Built-in External / Internal segmented control | | projectPickerLeadingSlot | Custom UI beside project picker | | trailingSlot | App actions before logo (Create ticket, etc.) |

11. RTL

Pass dir="rtl" when the app locale is Arabic (or any RTL language):

<Navbar dir={locale === "ar" ? "rtl" : "ltr"} /* … */ />

The package mirrors the bar automatically:

• Left group (actions + project picker) → visual right
• Right group (lang/theme + logo) → visual left
• Weather stays centered
• Dropdowns align to the trigger’s inline-start edge
• Back arrow icon flips in RTL

Project picker text and menus inherit dir from the navbar. Weather temperatures stay dir="ltr" for numeric readability.

12. Theming / CSS

This package uses host-provided Tailwind theme utilities. Your app must define:

• bg-theme, border-theme, surface-theme, text-theme-primary
• hover:bg-input-theme, bg-theme-surface, border-theme-border
• --input-border-color CSS variable
• animate-project-picker-pulse keyframe animation
• shadow-glass, shadow-glass-dark (optional, for dropdowns/popovers)

Without these classes the navbar will render but look unstyled.

13. Exports

// Components
export { Navbar, NavDropdown, WeatherForecastWidget, ProjectPicker, LangPicker, ThemePicker, NavbarSegmentedControl };

// Constants
export { NAV_ICON_SIZE, navIconButtonClass, navIconButtonClassNoMargin, DEFAULT_LANGUAGE_OPTIONS };
export { REQUIRED_NAVBAR_LABEL_KEYS, OPTIONAL_NAVBAR_LABEL_KEYS };

// Types
export type {
  NavbarProps,
  NavbarLayout,
  NavbarContextControl,
  NavbarContextOption,
  NavbarFeatures,
  NavbarRoutes,
  NavbarLabels,
  NavbarLogoConfig,
  NavbarProject,
  NavbarProjectPicker,
  NavbarWeather,
  NavbarWeatherDay,
  NavbarLangTheme,
  NavbarTheme,
  NavbarLinkComponent,
  ProjectPickerMode,
};