@dloizides/ui-nav 1.1.1 → 1.3.0

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # Changelog
 
+## 1.3.0
+
+Give the `NavBar` the v1 `.gn-links` look + a full accessibility pass (and extend the
+same a11y bar to `Sidebar`/`Topbar`).
+
+**Look & hover (NavBar).** Each link is a rounded-pill target with the v1 hover
+affordance — muted at rest, and on HOVER the text brightens to full contrast while a
+subtle rounded-pill background appears; the ACTIVE link is a solid accent pill. All
+theme-driven (rest = `textSecondary`, hover text = `text`, hover bg = `surfaceElevated`,
+active/ring = `palette.primary`). Hover/focus are web-only (`onHoverIn/Out`, `onFocus/Blur`
+via `Pressable`); native stays at the rest style. The hover cross-fade is cheap CSS and is
+disabled under `prefers-reduced-motion: reduce` (new `useReducedMotion`). Backwards
+compatible — the hover pill is the default (aml-v2 is the only `NavBar` consumer) and the
+brand/right slots, responsive hamburger collapse, and `containerStyle` width behaviour are
+unchanged.
+
+**Accessibility.** NavBar toggle now carries `aria-controls` pointing at the collapsible
+links region (id via `nativeID`), keeps `aria-expanded`, and gains a themed keyboard focus
+ring; links keep `aria-current="page"` + `role="link"` and gain a focus ring; link/toggle
+touch targets are now ≥44×44. `Sidebar` leaves gain `aria-current="page"` + a focus ring;
+`Topbar` action buttons gain a focus ring (new internal `FocusableTouchable`). Focus rings
+never remove the outline without a themed replacement.
+
+## 1.2.0
+
+Add `NavBar` — a config-driven **horizontal top navigation bar**, the top-bar
+counterpart to `Sidebar`. It renders the same caller-supplied `NavItem[]` as inline
+links across the top (brand left slot + inline links + free-form right slot), with
+an active-link highlight (`aria-current="page"`) and a responsive collapse to a
+hamburger toggle below a configurable breakpoint (`collapseBelow`, default `760`) —
+mirroring the v1 AML console `.global-nav`. Theme-driven (UiProvider colours),
+`role="navigation"` landmark, keyboard-operable links. Purely additive: `Sidebar`,
+`Topbar`, `AppShell`, and the role-gating helpers are unchanged. New `NAV_TEST_IDS`
+entries `navBarToggle` / `navBarLinks`.
+
 ## 1.0.0
 
 Initial release. `Sidebar` (leaf + expandable items, active-route highlight, header/footer

package/README.md

@@ -46,6 +46,50 @@ const items: NavItem[] = buildItems(); // your role-filtered / grouped items
 />
 ```
 
+### Horizontal top bar (`NavBar`)
+
+Prefer the nav links **on top** (a horizontal menu bar) instead of the left rail?
+`NavBar` renders the SAME `NavItem[]` model horizontally — brand slot on the left,
+inline links, a free-form right slot (auth / user / logout) — and collapses the
+links behind a hamburger below a configurable breakpoint (default `760`, matching
+the v1 AML console `.global-nav`). It is purely additive; `Sidebar` is unchanged.
+
+```tsx
+import { NavBar, type NavItem } from '@dloizides/ui-nav';
+
+<NavBar
+  items={items}                              // same role-filtered NavItem[] as Sidebar
+  pathname={usePathname()}
+  onNavigate={(route) => router.push(route)}
+  regionLabel={FM('accessibility.navigationRegion')}
+  navigateHint={(label) => FM('menu.navigateToHint', label)}
+  brand={<BrandLogo />}                       // left slot
+  right={<AuthLink />}                         // right slot (auth / user / logout)
+  menuLabel={FM('menu.toggle')}               // a11y label for the hamburger
+  menuHint={FM('menu.toggleHint')}
+  collapseBelow={760}                          // hamburger under this viewport width
+/>
+```
+
+An app that renders a `Sidebar` today switches to a top bar by swapping the
+`Sidebar` element for `NavBar` (same `items` / `pathname` / `onNavigate`) — e.g.
+the AML v2 app drops `NavBar` into the `AppShell` `header` (or `nav`) slot so its
+links sit across the top like the rest of the console.
+
+Each link is a rounded-pill target with the v1 `.gn-links` affordance: muted at
+rest, brightening its text + showing a subtle pill background on **hover**, and a
+solid accent pill when **active**. All colours are theme-driven (rest =
+`textSecondary`, hover text = `text`, hover bg = `surfaceElevated`, active/ring =
+`palette.primary`); hover/focus are web-only and the hover cross-fade honours
+`prefers-reduced-motion`.
+
+**Accessibility.** The container is a `role="navigation"` landmark named by
+`regionLabel`; active links expose `aria-current="page"` + `role="link"`; the
+responsive hamburger carries `role="button"`, `aria-expanded`, and `aria-controls`
+pointing at the collapsible links region; every link/toggle is keyboard-operable
+(Enter/Space) with a themed focus ring and a ≥44×44 touch target. `Sidebar` leaves
+carry `aria-current="page"` and `Topbar` buttons a focus ring under the same bar.
+
 ### Role gating
 
 `accessibleNavItems(user, roleRouteTable, translate)` builds the `NavItem[]` a user's roles

package/dist/index.d.mts

@@ -145,6 +145,56 @@ interface TopbarProps {
 }
 declare const Topbar: ({ left, language, notificationSlot, user, account, logout, containerStyle, }: TopbarProps) => React.ReactElement;
 
+/**
+ * NavBar — the config-driven HORIZONTAL top navigation bar. It is the top-bar
+ * counterpart to `Sidebar`: it renders the SAME caller-supplied `NavItem[]`
+ * (already role-filtered / localized by the app) as inline links across the top
+ * instead of a left rail, with an optional brand slot on the left and a free-form
+ * right slot (auth link / user / logout). Below a configurable breakpoint it
+ * collapses the links behind a hamburger toggle — mirroring the v1 AML console's
+ * responsive `.global-nav`.
+ *
+ * Look + feel: each link is a rounded-pill target with the v1 `.gn-links a`
+ * affordance — muted at rest, brightening text + a subtle pill background on
+ * HOVER, and a solid accent pill when ACTIVE. All colours are THEME-DRIVEN from
+ * the `@dloizides/ui-feedback` UiProvider (rest=`textSecondary`, hover text=`text`,
+ * hover bg=`surfaceElevated`, active=`palette.primary`, ring=`palette.primary`).
+ * Hover/focus are web-only (react-native-web); native stays at the rest style.
+ *
+ * Contract discipline (same as the rest of `@dloizides/ui-nav`): NO FM, router,
+ * icon set, or store imports. Labels are pre-localized strings, icons are render
+ * slots, and every colour is read from the theme. This is purely additive —
+ * `Sidebar`/`Topbar` are unchanged.
+ */
+
+interface NavBarProps {
+    /** Nav entries — already role-filtered / grouped by the app. */
+    items: NavItem[];
+    /** Current active route/path. */
+    pathname: string;
+    /** Navigation callback — receives a `NavItem.route`. */
+    onNavigate: (route: string) => void;
+    /** Localized accessibility label for the navigation landmark. */
+    regionLabel: string;
+    /** a11y hint for a link, given its label. Defaults to the label. */
+    navigateHint?: (label: string) => string;
+    /** Left slot — typically the brand / tenant logo. */
+    brand?: React.ReactNode;
+    /** Right slot — free-form (auth link, user block, logout). */
+    right?: React.ReactNode;
+    /** Localized accessibility label for the responsive menu toggle. */
+    menuLabel?: string;
+    /** Localized accessibility hint for the responsive menu toggle. */
+    menuHint?: string;
+    /** Optional custom glyph renderer for the toggle; defaults to ☰. */
+    renderMenuIcon?: (color: string, open: boolean) => React.ReactNode;
+    /** Collapse the links behind a hamburger below this viewport width (default 760). */
+    collapseBelow?: number;
+    /** Extra container style overrides. */
+    containerStyle?: ViewStyle | ViewStyle[];
+}
+declare const NavBar: ({ items, pathname, onNavigate, regionLabel, navigateHint, brand, right, menuLabel, menuHint, renderMenuIcon, collapseBelow, containerStyle, }: NavBarProps) => React.ReactElement;
+
 /** Content-width policy: a capped column, optionally wider past a viewport breakpoint, or full-bleed. */
 type AppShellWidth = {
     max: number;
@@ -229,6 +279,10 @@ declare const NAV_TEST_IDS: {
     readonly accountPlan: "topbar-account-plan";
     /** default testID for the rich header's upgrade action (overridable per-action). */
     readonly accountUpgrade: "topbar-account-upgrade";
+    /** responsive hamburger toggle in the horizontal NavBar (shown below the breakpoint). */
+    readonly navBarToggle: "navbar-toggle";
+    /** links container in the horizontal NavBar. */
+    readonly navBarLinks: "navbar-links";
 };
 /** Suffixes appended to an `AppShell`'s required `testID` to name its regions. */
 declare const APP_SHELL_SUFFIX: {
@@ -408,4 +462,4 @@ declare const NAV_ICON_SIZE = 14;
 /** Chevron icon size for expandable sections. */
 declare const CHEVRON_ICON_SIZE = 12;
 
-export { ACTIVE_BORDER_RADIUS, APP_SHELL_SUFFIX, type AccountPlan, type AccountState, AppShell, type AppShellProps, type AppShellWidth, BASE_INDENT, CHEVRON_ICON_SIZE, NAV_ICON_SIZE, NAV_TEST_IDS, NavExpandableItem, type NavExpandableItemProps, type NavItem, type NavUser, type ShellMessage, Sidebar, type SidebarProps, Topbar, type TopbarAction, type TopbarProps, type TopbarUser, accessibleNavItems, expandableStyles, isRouteActive, navStyles, resolveContentMaxWidth, roleRoutesToNavItems, useContentMaxWidth };
+export { ACTIVE_BORDER_RADIUS, APP_SHELL_SUFFIX, type AccountPlan, type AccountState, AppShell, type AppShellProps, type AppShellWidth, BASE_INDENT, CHEVRON_ICON_SIZE, NAV_ICON_SIZE, NAV_TEST_IDS, NavBar, type NavBarProps, NavExpandableItem, type NavExpandableItemProps, type NavItem, type NavUser, type ShellMessage, Sidebar, type SidebarProps, Topbar, type TopbarAction, type TopbarProps, type TopbarUser, accessibleNavItems, expandableStyles, isRouteActive, navStyles, resolveContentMaxWidth, roleRoutesToNavItems, useContentMaxWidth };

package/dist/index.d.ts

@@ -145,6 +145,56 @@ interface TopbarProps {
 }
 declare const Topbar: ({ left, language, notificationSlot, user, account, logout, containerStyle, }: TopbarProps) => React.ReactElement;
 
+/**
+ * NavBar — the config-driven HORIZONTAL top navigation bar. It is the top-bar
+ * counterpart to `Sidebar`: it renders the SAME caller-supplied `NavItem[]`
+ * (already role-filtered / localized by the app) as inline links across the top
+ * instead of a left rail, with an optional brand slot on the left and a free-form
+ * right slot (auth link / user / logout). Below a configurable breakpoint it
+ * collapses the links behind a hamburger toggle — mirroring the v1 AML console's
+ * responsive `.global-nav`.
+ *
+ * Look + feel: each link is a rounded-pill target with the v1 `.gn-links a`
+ * affordance — muted at rest, brightening text + a subtle pill background on
+ * HOVER, and a solid accent pill when ACTIVE. All colours are THEME-DRIVEN from
+ * the `@dloizides/ui-feedback` UiProvider (rest=`textSecondary`, hover text=`text`,
+ * hover bg=`surfaceElevated`, active=`palette.primary`, ring=`palette.primary`).
+ * Hover/focus are web-only (react-native-web); native stays at the rest style.
+ *
+ * Contract discipline (same as the rest of `@dloizides/ui-nav`): NO FM, router,
+ * icon set, or store imports. Labels are pre-localized strings, icons are render
+ * slots, and every colour is read from the theme. This is purely additive —
+ * `Sidebar`/`Topbar` are unchanged.
+ */
+
+interface NavBarProps {
+    /** Nav entries — already role-filtered / grouped by the app. */
+    items: NavItem[];
+    /** Current active route/path. */
+    pathname: string;
+    /** Navigation callback — receives a `NavItem.route`. */
+    onNavigate: (route: string) => void;
+    /** Localized accessibility label for the navigation landmark. */
+    regionLabel: string;
+    /** a11y hint for a link, given its label. Defaults to the label. */
+    navigateHint?: (label: string) => string;
+    /** Left slot — typically the brand / tenant logo. */
+    brand?: React.ReactNode;
+    /** Right slot — free-form (auth link, user block, logout). */
+    right?: React.ReactNode;
+    /** Localized accessibility label for the responsive menu toggle. */
+    menuLabel?: string;
+    /** Localized accessibility hint for the responsive menu toggle. */
+    menuHint?: string;
+    /** Optional custom glyph renderer for the toggle; defaults to ☰. */
+    renderMenuIcon?: (color: string, open: boolean) => React.ReactNode;
+    /** Collapse the links behind a hamburger below this viewport width (default 760). */
+    collapseBelow?: number;
+    /** Extra container style overrides. */
+    containerStyle?: ViewStyle | ViewStyle[];
+}
+declare const NavBar: ({ items, pathname, onNavigate, regionLabel, navigateHint, brand, right, menuLabel, menuHint, renderMenuIcon, collapseBelow, containerStyle, }: NavBarProps) => React.ReactElement;
+
 /** Content-width policy: a capped column, optionally wider past a viewport breakpoint, or full-bleed. */
 type AppShellWidth = {
     max: number;
@@ -229,6 +279,10 @@ declare const NAV_TEST_IDS: {
     readonly accountPlan: "topbar-account-plan";
     /** default testID for the rich header's upgrade action (overridable per-action). */
     readonly accountUpgrade: "topbar-account-upgrade";
+    /** responsive hamburger toggle in the horizontal NavBar (shown below the breakpoint). */
+    readonly navBarToggle: "navbar-toggle";
+    /** links container in the horizontal NavBar. */
+    readonly navBarLinks: "navbar-links";
 };
 /** Suffixes appended to an `AppShell`'s required `testID` to name its regions. */
 declare const APP_SHELL_SUFFIX: {
@@ -408,4 +462,4 @@ declare const NAV_ICON_SIZE = 14;
 /** Chevron icon size for expandable sections. */
 declare const CHEVRON_ICON_SIZE = 12;
 
-export { ACTIVE_BORDER_RADIUS, APP_SHELL_SUFFIX, type AccountPlan, type AccountState, AppShell, type AppShellProps, type AppShellWidth, BASE_INDENT, CHEVRON_ICON_SIZE, NAV_ICON_SIZE, NAV_TEST_IDS, NavExpandableItem, type NavExpandableItemProps, type NavItem, type NavUser, type ShellMessage, Sidebar, type SidebarProps, Topbar, type TopbarAction, type TopbarProps, type TopbarUser, accessibleNavItems, expandableStyles, isRouteActive, navStyles, resolveContentMaxWidth, roleRoutesToNavItems, useContentMaxWidth };
+export { ACTIVE_BORDER_RADIUS, APP_SHELL_SUFFIX, type AccountPlan, type AccountState, AppShell, type AppShellProps, type AppShellWidth, BASE_INDENT, CHEVRON_ICON_SIZE, NAV_ICON_SIZE, NAV_TEST_IDS, NavBar, type NavBarProps, NavExpandableItem, type NavExpandableItemProps, type NavItem, type NavUser, type ShellMessage, Sidebar, type SidebarProps, Topbar, type TopbarAction, type TopbarProps, type TopbarUser, accessibleNavItems, expandableStyles, isRouteActive, navStyles, resolveContentMaxWidth, roleRoutesToNavItems, useContentMaxWidth };