@dloizides/ui-nav 1.7.0 → 1.8.0

package/ADOPTION.md

@@ -0,0 +1,83 @@
+# Adopting `@dloizides/ui-nav` ≥ 1.8.0 — per-portal migration map
+
+This is the map the migration agents follow to move each RN-web portal off its
+bespoke nav/shell onto the shared package. **Only STYLE varies per app** — layout
+structure and behaviour are shared. Nothing from the current shells is lost:
+everything is either a component, an optional prop, or a render slot.
+
+> Migrations are a **separate wave** — do NOT edit the apps as part of building the
+> package. This doc tells each app which `layout`, which slots, and which
+> components to use.
+
+## The one decision: which `layout`?
+
+| Portal | Current shell | `NavShell` `layout` | Notes |
+|--------|---------------|---------------------|-------|
+| **AML v2** (`consoleChrome` / AuthedShell / PublicShell) | top bar only (dark, radial glow) | `"top"` | `topBar.barTheme` = dark chrome; brand/user/language in `topBar.brand` / `topBar.right`; overflow "…" built-in |
+| **Agora** (`AdminShell`) | side rail + top bar (already `AppShell`) | `"side"` | `sideRail` = sections; `header` = `<Topbar logout=… />` |
+| **Zygos** (`ZygosShell`) | side rail + top bar (already `AppShell`) | `"side"` | as Agora, plus `Topbar.user` block |
+| **Kefi** (`DashboardShell` / `AppHeader` / `DashboardNav`) | top bar + coral pill strip | `"top"` | `header`/`topBar` = brand + account; put `<PillNav minItems={2} />` in the `nav` slot |
+| **Erevna** (`ProtectedLayout` + Sidebar/Topbar) | 3-tier rail + top bar | `"side"` **+** `sideRail.collapsed` | full rail → collapsed icon rail → drawer |
+| **Katalogos** | byte-identical to erevna | `"side"` **+** `sideRail.collapsed` | same as erevna |
+
+## Slot mapping (what fills each slot)
+
+### AML v2 — `layout="top"`
+- `topBar.items` ← `editionNavItems(visibleNavItems(isAdmin), selfHosted)` → `NavItem[]`
+  (keep the app-side edition/self-host filtering; pass the result).
+- `topBar.brand` ← the `ConsoleBrand` block (brand→marketing-vs-console-home routing
+  stays in the app; `brand` is a free-form node).
+- `topBar.right` ← `<ShellLanguageSwitcher />` + `<UserChip />` (or the "Sign in" pill
+  for anonymous `PublicShell`). Both are already `right`-slot nodes today.
+- `topBar.barTheme` ← the navy `useNavTheme()` clone (dark bar over light page).
+- `topBar.containerStyle` ← the 1180px cap + the radial-glow `appbarBarStyle` (a web
+  `background`/`backgroundImage` gradient cast through `ViewStyle`). **Style only.**
+- `topBar.overflowLabel` / `collapseBelow={760}` ← as today.
+- External-route split (`isExternalRoute` → `Linking.openURL` vs `router.navigate`)
+  stays in the app's `onNavigate`. `ToastHost` stays app-side (it is `@dloizides/ui-feedback`).
+
+### Agora / Zygos — `layout="side"`
+- `sideRail.items` ← the localized `NAV_SECTIONS` (`renderIcon` per item).
+- `sideRail.title` / `regionLabel` / `navigateHint` ← as today.
+- `header` ← `<Topbar logout={…} user={…?} />` (Zygos passes `user`; Agora does not).
+- `mobileMenu` ← the drawer open/close labels (Agora passes them; Zygos gets English defaults).
+- Nothing else changes — these already consume `AppShell` + `Sidebar` + `Topbar`.
+
+### Kefi — `layout="top"` + `nav` slot
+- `header` ← `<Topbar account={{ displayName, onLogout }} left={<Wordmark/>} logout={…} />`
+  (the rich `AccountState`; keep omitting tenant/plan to avoid the round-trip).
+- `nav` ← `<PillNav items={accessibleNavItems(user, postLoginRouteTable, FM)} minItems={2}
+  pathname={…} onNavigate={…} regionLabel={…} />` — this folds in the coral pills AND
+  the ≥2-dashboards rule (no more app-local `MIN_DASHBOARDS_FOR_NAV`).
+- `gate` / `state` / `banner` / `width` / `chromeAlignment` / `contentPadding` ← exactly
+  the `AppShell` props kefi already passes (unchanged).
+- Coral colour = theme `palette.primary`; pill radius/font = theme/`containerStyle`. **Style only.**
+
+### Erevna / Katalogos — `layout="side"` + `sideRail.collapsed`
+- `sideRail.items` ← `toNavItems(groupSidebarItems(moduleRegistry.getSidebarItemsForRoles(roles)))`
+  (role-gated, grouped/expandable — unchanged pipeline).
+- `sideRail.header` ← the Home shortcut; `sideRail.footer` ← `<DarkModeControl variant="segmented"
+  options={[Light, Dark, System]} value=… onChange={setDarkModePreference} />` + Logout
+  (replaces the bespoke `DarkModeToggle`). `sideRail.renderChevron` ← chevronUp/Down.
+- `sideRail.collapsed` ← `{ items, header, footer, range: { min, max } }` → the tablet
+  **collapsed icon rail** (replaces `MobileSidebarCollapsed`). Its footer can hold the
+  `DarkModeControl variant="cycle"` (replaces `MobileDarkModeButton`).
+- `header` ← `<Topbar left={<TenantLogo/>} language={…} notificationSlot={<SafeNotificationBell/>}
+  user={…} logout={…} account={…?} />`.
+- `mobileMenu` ← the drawer open/close labels (the phone drawer re-hosts the full rail).
+- `gate` (auth) / `banner` (`VerificationPendingBanner`) / `state` ← the `AppShell` props.
+- **Still app-side (not lost, not shared):** the `!isUser` role-conditional rail hide
+  (just pass no `sideRail` for plain users), the `SkipNavLink` (compose in `children`),
+  and — if the exact right-anchored mobile *account* drawer (user+dark+lang+account) is
+  wanted verbatim — keep `MobileTopbar` in the `header` slot; the shared left drawer
+  re-hosts the rail, which covers the section-navigation case.
+- **Style only:** scrim colour/opacity, slide offsets/durations, segmented-toggle
+  highlight, drawer panel colours → theme tokens / `containerStyle`.
+
+## Contract reminders (unchanged)
+
+- No FM / router / icon-set / store imports in the package. Labels are pre-localized
+  strings; icons are `renderIcon` render slots; every colour flows through the
+  `@dloizides/ui-feedback` `UiProvider` theme.
+- `Sidebar` / `Topbar` / `NavBar` / `Nav` / `AppShell` and the role helpers keep their
+  exact 1.7.0 signatures — migrate incrementally; a partial migration compiles.

package/CHANGELOG.md

@@ -1,5 +1,63 @@
 # Changelog
 
+## 1.8.0
+
+The navigation shell becomes the ONE shell for every portal: a first-class
+**top | side | both** layout, plus the capabilities harvested from every RN-web
+portal's bespoke nav/shell so nothing is lost when they migrate. Purely additive —
+`Sidebar`, `Topbar`, `NavBar`, `Nav`, `AppShell`, and the role helpers keep their
+exact signatures; every new prop/component is optional.
+
+**`NavShell` — top bar, side rail, or BOTH.** One component owns the whole page
+composition, chosen by a single `layout` prop (`'top' | 'side' | 'both'`). It wires
+a top bar into `AppShell`'s `header` slot and a side rail into its `sidebar` slot,
+and inherits every `AppShell` capability (auth gate, loading/error/forbidden state
+cards, width policy, banner, the responsive hamburger + overlay drawer). `'both'`
+is the AML-console shape — a top bar (brand / global links + overflow "…" / user)
+AND a side rail (sections) together — now first-class instead of hand-wired. The
+top bar is built from a `topBar` config (a `NavBar`), the side rail from a
+`sideRail` config (a `Sidebar`); an explicit `header` node overrides the built top
+bar for apps that want a structured `Topbar`.
+
+**Three-tier responsive rail (`AppShell.collapsedSidebar`).** Opts the `sidebar`
+layout into the erevna/katalogos scheme: the full rail on desktop, an intermediate
+persistent **collapsed (icon-only) rail** on a tablet band, and the overlay drawer
+on a phone. Supply a `collapsedSidebar` node (and optionally `collapsedRailRange`,
+default `{ min: 768, max: 1024 }`) — omit it and the layout stays the unchanged
+two-tier scheme. New `CollapsedRail` component renders an icon-only rail from the
+same `NavItem[]` (icon or first-letter glyph fallback, header/footer slots). New
+`resolveRailMode` pure resolver + `RAIL_FULL_BREAKPOINT` / `DEFAULT_COLLAPSED_RAIL_MAX`.
+`NavShell.sideRail.collapsed` builds it config-driven. New testID suffix
+`-collapsed-sidebar`.
+
+**`NavBar.barTheme` — dark bar over a light page.** An optional chrome-theme
+override re-provisions the `@dloizides/ui-feedback` theme for the bar only (the AML
+v1-console dark appbar over light content), re-passing the live `t` / `navigate` so
+labels keep localizing. Forwarded via `NavShell.topBar.barTheme`. Style-only —
+colours still flow through the theme. (Custom appbar backgrounds like AML's radial
+glow stay expressible via `containerStyle`.)
+
+**`PillNav` — coral cross-navigation (kefi).** A row of fully-rounded pills from a
+`NavItem[]`, the active one wearing the accent (theme `palette.primary` = kefi's
+coral). Folds in kefi's **visibility rule**: hides (renders `null`) unless there
+are at least `minItems` entries (default 1; kefi passes 2).
+
+**`DarkModeControl` — 3-way colour scheme (erevna/katalogos).** A controlled
+Light / Dark / System control in two variants: `"segmented"` (a highlighted
+segment row) and `"cycle"` (an icon+label button that advances to the next option
+on press). Value-agnostic string options, pre-localized labels/hints.
+
+**Refactor (no behaviour change).** `AppShell`'s page-state cards moved to
+`appShellContent.tsx` (`useContentBody` / `ShellMessage` / `ShellState`) to keep
+`AppShell` focused on layout; the shell's render tree is unchanged.
+
+New exports: `NavShell` (+ `NavShellProps` / `NavShellLayout` / `NavShellTopBar` /
+`NavShellSideRail` / `NavShellCollapsedRail`), `CollapsedRail` (+ `CollapsedRailProps`),
+`PillNav` (+ `PillNavProps`), `DarkModeControl` (+ `DarkModeControlProps` /
+`DarkModeOption` / `DarkModeVariant`), `resolveRailMode` (+ `RailMode` /
+`CollapsedRailRange` / `ResolveRailModeArgs`), `RAIL_FULL_BREAKPOINT`,
+`DEFAULT_COLLAPSED_RAIL_MAX`, `pillNavStyles`, `darkModeStyles`, `collapsedRailStyles`.
+
 ## 1.7.0
 
 Two additive navigation capabilities on the horizontal bar, plus a unifying component.

package/README.md

@@ -101,6 +101,89 @@ import { Nav, type NavItem } from '@dloizides/ui-nav';
 
 `Nav` is purely additive: `Sidebar` / `Topbar` / `NavBar` stay exported and unchanged.
 
+### One shell, three layouts — top | side | **both** (`NavShell`)
+
+Where `Nav` answers the single-axis question (a `NavBar` **or** a `Sidebar`),
+`NavShell` owns the whole page composition and renders a **top bar**, a **side
+rail**, or **BOTH together**, chosen by a single `layout` prop. It wires a top bar
+into `AppShell`'s `header` slot and a side rail into its `sidebar` slot, and
+inherits every `AppShell` capability (auth gate, loading/error/forbidden state
+cards, width policy, banner, the responsive hamburger + overlay drawer).
+
+```tsx
+import { NavShell, type NavItem } from '@dloizides/ui-nav';
+
+// layout="both" — a top bar (brand / global links + overflow "…" / user) AND a
+// side rail (sections) together (the AML-console shape), now first-class.
+<NavShell
+  layout="both"
+  pathname={usePathname()}
+  onNavigate={(route) => router.push(route)}
+  regionLabel={FM('a11y.nav')}
+  topBar={{
+    items: globalItems,                 // top links (overflow-capable)
+    brand: <BrandLogo />,
+    right: <><LanguageSwitcher /><UserChip /></>,
+    overflowLabel: FM('menu.more'),
+    barTheme: darkChromeTheme,          // optional: dark bar over a light page
+  }}
+  sideRail={{
+    items: sectionItems,                // side sections (leaf + expandable)
+    title: FM('menu.title'),
+    footer: <><DarkModeControl … /><LogoutButton /></>,
+    collapsed: { range: { min: 768, max: 1024 } },   // optional 3-tier icon rail
+  }}
+  gate={{ pending, authenticated, onRedirect: () => router.push('/login') }}
+  state={{ loading, error, forbidden }}
+  width={{ max: 1180, wideMax: 1400, wideMinViewport: 1600 }}
+  testID="app-shell"
+>
+  <PageContent />
+</NavShell>
+```
+
+- `layout="top"` → a top bar only (`topBar`); no rail.
+- `layout="side"` → a header + a persistent left rail of sections (`sideRail`); pass a
+  structured `<Topbar>` as `header` for the language/notification/user slots.
+- `layout="both"` → both, together.
+
+`NavShell` composes existing components, so it stays purely additive — `AppShell`,
+`NavBar`, and `Sidebar` are unchanged.
+
+### Three-tier responsive rail (`AppShell.collapsedSidebar` / `CollapsedRail`)
+
+Supply a `collapsedSidebar` (or `NavShell`'s `sideRail.collapsed`) to opt the rail
+into the erevna/katalogos scheme: the full rail on desktop, an intermediate
+persistent **collapsed (icon-only) rail** on a tablet band `[min, max)` (default
+`{ min: 768, max: 1024 }`), and the overlay drawer on a phone. Omit it and the
+layout stays the unchanged two-tier scheme (full rail ≥768px, drawer below).
+`CollapsedRail` renders the icon rail from the same `NavItem[]` (each item's
+`renderIcon`, or a first-letter glyph fallback), with header/footer slots. The pure
+`resolveRailMode` decides the tier and is directly unit-testable.
+
+### Dark bar over a light page (`NavBar.barTheme`)
+
+Pass `barTheme` (a `UiTheme`) to re-provision the theme for the bar **only** — a
+dark appbar above a light workspace (the AML v1 console). The live `t` / `navigate`
+are re-passed so labels keep localizing; every colour still flows through the theme
+(style-only). Custom appbar backgrounds (e.g. a radial-glow gradient) stay
+expressible via `containerStyle`.
+
+### Cross-navigation pills (`PillNav`)
+
+A row of fully-rounded pills from a `NavItem[]` — kefi's coral dashboard switcher.
+The active pill wears the accent (theme `palette.primary`). Folds in kefi's rule:
+it hides (renders `null`) unless there are at least `minItems` entries (default 1;
+kefi passes `2`). Drop it into `AppShell`/`NavShell`'s `nav` slot.
+
+### Colour-scheme control (`DarkModeControl`)
+
+A controlled Light / Dark / System control (erevna/katalogos), in two variants:
+`"segmented"` (a highlighted segment row) and `"cycle"` (an icon+label button that
+advances to the next option per press). Options are pre-localized and value-agnostic
+(strings), so map your own preference enum without this package importing it. Put it
+in a `Sidebar`/`CollapsedRail` footer or a `NavBar` right slot.
+
 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