@dloizides/ui-nav 1.2.0 → 1.4.0

package/CHANGELOG.md

@@ -1,22 +1,63 @@
-# Changelog
-
-## 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
-slots), `Topbar` (logo/language/notification/user/account/logout slots), and the
-`accessibleNavItems` / `roleRoutesToNavItems` role-gating helpers (reusing
-`resolveAccessibleRoutes` from `@dloizides/auth-web`). Chrome + metrics ported verbatim from
-the byte-identical erevna-web / katalogos-web nav twins; every colour reads from the
-`@dloizides/ui-feedback` UiProvider theme.
+# Changelog
+
+## 1.4.0
+
+Add an optional **`sidebar`** slot to `AppShell` — the back-office layout.
+
+`AppShell` could only stack vertically (header → nav strip → banner → scrolling content),
+so a product with a persistent LEFT RAIL (Agora's merchant admin: products / categories /
+coupons / settings) had to hand-compose `Topbar` + `Sidebar` + a `ScrollView` row and give
+up the shell's auth gate and loading/error/forbidden state cards. Supplying `sidebar` now
+lays the body out as a ROW — the rail on the left, the width-disciplined scrolling content
+column on the right — while every existing feature (gate, state cards, `width`,
+`chromeAlignment`) keeps working.
+
+The new region is exposed as `` `${testID}${APP_SHELL_SUFFIX.sidebar}` `` (`-sidebar`).
+
+**Backwards compatible.** Omit `sidebar` and the render tree is byte-identical to 1.3.0 —
+erevna / katalogos / kefi / aml-v2 are untouched. Pinned by a test asserting no `-sidebar`
+region exists when the slot is omitted.
+
+## 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
+slots), `Topbar` (logo/language/notification/user/account/logout slots), and the
+`accessibleNavItems` / `roleRoutesToNavItems` role-gating helpers (reusing
+`resolveAccessibleRoutes` from `@dloizides/auth-web`). Chrome + metrics ported verbatim from
+the byte-identical erevna-web / katalogos-web nav twins; every colour reads from the
+`@dloizides/ui-feedback` UiProvider theme.

package/README.md

@@ -74,8 +74,21 @@ import { NavBar, type NavItem } from '@dloizides/ui-nav';
 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. Active links expose
-`aria-current="page"`; the container is a `role="navigation"` landmark.
+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
 

package/dist/index.d.mts

@@ -154,10 +154,17 @@ declare const Topbar: ({ left, language, notificationSlot, user, account, logout
  * 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 `@dloizides/ui-feedback` UiProvider
- * theme. This is purely additive — `Sidebar`/`Topbar` are unchanged.
+ * slots, and every colour is read from the theme. This is purely additive —
+ * `Sidebar`/`Topbar` are unchanged.
  */
 
 interface NavBarProps {
@@ -211,6 +218,13 @@ declare function useContentMaxWidth(width: AppShellWidth): number | 'full';
  * (pending spinner / redirect-when-unauthenticated) and page state cards
  * (loading / error / forbidden).
  *
+ * A BACK-OFFICE variant is supported via the optional `sidebar` slot (added for
+ * Agora's merchant admin): supply a `<Sidebar>` and the body below the header /
+ * nav / banner becomes a ROW — a persistent left rail beside the scrolling
+ * content column — instead of the default single vertical stack. Omit `sidebar`
+ * and the render tree is byte-identical to before, so every existing consumer
+ * (erevna / katalogos / kefi) is untouched.
+ *
  * Contract discipline (same as the rest of `@dloizides/ui-nav`): NO FM, router,
  * or store imports. The app passes wired elements, pre-localized strings, and
  * callbacks; every colour is routed through the `@dloizides/ui-feedback` theme.
@@ -226,6 +240,13 @@ interface AppShellProps {
     header: React.ReactNode;
     /** Per-app nav region (kefi coral pills / erevna sidebar+drawer). */
     nav?: React.ReactNode;
+    /**
+     * Optional persistent LEFT RAIL (a `<Sidebar>`), for back-office surfaces. When
+     * supplied, the region below header/nav/banner lays out as a row: the rail on the
+     * left, the scrolling content column on the right. Omit for the default vertical
+     * stack — the tree is then byte-identical to the pre-`sidebar` AppShell.
+     */
+    sidebar?: React.ReactNode;
     /** Banner slot (e.g. verification-pending). */
     banner?: React.ReactNode;
     /** Content-width policy. Defaults to full-bleed. */
@@ -254,7 +275,7 @@ interface AppShellProps {
     testID: string;
     children: React.ReactNode;
 }
-declare const AppShell: ({ header, nav, banner, width, contentPadding, chromeAlignment, gate, state, testID, children, }: AppShellProps) => React.ReactElement | null;
+declare const AppShell: ({ header, nav, sidebar, banner, width, contentPadding, chromeAlignment, gate, state, testID, children, }: AppShellProps) => React.ReactElement | null;
 
 /**
  * Default testIDs for `@dloizides/ui-nav`. Kept as a small central map (mirrors
@@ -282,6 +303,8 @@ declare const APP_SHELL_SUFFIX: {
     readonly content: "-content";
     readonly header: "-header";
     readonly nav: "-nav";
+    /** The persistent left rail of the back-office layout (only when `sidebar` is supplied). */
+    readonly sidebar: "-sidebar";
     readonly banner: "-banner";
     readonly pending: "-pending";
     readonly loading: "-loading";

package/dist/index.d.ts

@@ -154,10 +154,17 @@ declare const Topbar: ({ left, language, notificationSlot, user, account, logout
  * 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 `@dloizides/ui-feedback` UiProvider
- * theme. This is purely additive — `Sidebar`/`Topbar` are unchanged.
+ * slots, and every colour is read from the theme. This is purely additive —
+ * `Sidebar`/`Topbar` are unchanged.
  */
 
 interface NavBarProps {
@@ -211,6 +218,13 @@ declare function useContentMaxWidth(width: AppShellWidth): number | 'full';
  * (pending spinner / redirect-when-unauthenticated) and page state cards
  * (loading / error / forbidden).
  *
+ * A BACK-OFFICE variant is supported via the optional `sidebar` slot (added for
+ * Agora's merchant admin): supply a `<Sidebar>` and the body below the header /
+ * nav / banner becomes a ROW — a persistent left rail beside the scrolling
+ * content column — instead of the default single vertical stack. Omit `sidebar`
+ * and the render tree is byte-identical to before, so every existing consumer
+ * (erevna / katalogos / kefi) is untouched.
+ *
  * Contract discipline (same as the rest of `@dloizides/ui-nav`): NO FM, router,
  * or store imports. The app passes wired elements, pre-localized strings, and
  * callbacks; every colour is routed through the `@dloizides/ui-feedback` theme.
@@ -226,6 +240,13 @@ interface AppShellProps {
     header: React.ReactNode;
     /** Per-app nav region (kefi coral pills / erevna sidebar+drawer). */
     nav?: React.ReactNode;
+    /**
+     * Optional persistent LEFT RAIL (a `<Sidebar>`), for back-office surfaces. When
+     * supplied, the region below header/nav/banner lays out as a row: the rail on the
+     * left, the scrolling content column on the right. Omit for the default vertical
+     * stack — the tree is then byte-identical to the pre-`sidebar` AppShell.
+     */
+    sidebar?: React.ReactNode;
     /** Banner slot (e.g. verification-pending). */
     banner?: React.ReactNode;
     /** Content-width policy. Defaults to full-bleed. */
@@ -254,7 +275,7 @@ interface AppShellProps {
     testID: string;
     children: React.ReactNode;
 }
-declare const AppShell: ({ header, nav, banner, width, contentPadding, chromeAlignment, gate, state, testID, children, }: AppShellProps) => React.ReactElement | null;
+declare const AppShell: ({ header, nav, sidebar, banner, width, contentPadding, chromeAlignment, gate, state, testID, children, }: AppShellProps) => React.ReactElement | null;
 
 /**
  * Default testIDs for `@dloizides/ui-nav`. Kept as a small central map (mirrors
@@ -282,6 +303,8 @@ declare const APP_SHELL_SUFFIX: {
     readonly content: "-content";
     readonly header: "-header";
     readonly nav: "-nav";
+    /** The persistent left rail of the back-office layout (only when `sidebar` is supplied). */
+    readonly sidebar: "-sidebar";
     readonly banner: "-banner";
     readonly pending: "-pending";
     readonly loading: "-loading";