@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.

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):

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

Nav actions depend on layout + page:

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

5. Project picker modes

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

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.

Support create dialog (features.supportCreate): theme CSS is injected automatically when you import from @avament-pub/navbar-ui. Optional manual import: @avament-pub/navbar-ui/styles.css. Host apps should define --surface-color, --text-primary-color, --input-border-color, and related tokens (see protocol/ticket apps).

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,
};