@dloizides/ui-nav 1.7.0 → 1.8.0

package/dist/index.d.mts

@@ -1,5 +1,6 @@
 import React from 'react';
 import { ViewStyle } from 'react-native';
+import { UiTheme } from '@dloizides/ui-feedback';
 import { DropdownVariant } from '@dloizides/ui-layout';
 import { resolveAccessibleRoutes, RoleRouteTable, RoleRoute } from '@dloizides/auth-web';
 
@@ -209,8 +210,23 @@ interface NavBarProps {
     overflowHint?: string;
     /** Extra container style overrides. */
     containerStyle?: ViewStyle | ViewStyle[];
+    /**
+     * Optional CHROME theme override — re-provisions the `@dloizides/ui-feedback`
+     * theme for the bar ONLY, so the top bar can be dark while the page below keeps
+     * the light workspace theme (the AML v1-console "dark appbar over light content"
+     * pattern). The live `t` (+ `navigate`) from the surrounding provider are
+     * re-passed, so nav labels keep localizing. Omit for a bar that shares the page
+     * theme. Style-only: every colour still flows through the theme — no per-app fork.
+     */
+    barTheme?: UiTheme;
 }
-declare const NavBar: ({ items, pathname, onNavigate, regionLabel, navigateHint, brand, right, menuLabel, menuHint, renderMenuIcon, collapseBelow, overflowLabel, overflowHint, containerStyle, }: NavBarProps) => React.ReactElement;
+/**
+ * `NavBar` — the horizontal top bar. When `barTheme` is supplied it re-provisions
+ * the `@dloizides/ui-feedback` theme around the bar (dark bar over a light page),
+ * re-passing the live `t` / `navigate` so labels keep localizing; otherwise it
+ * renders directly against the surrounding theme (byte-identical to before).
+ */
+declare const NavBar: ({ barTheme, ...props }: NavBarProps) => React.ReactElement;
 
 /**
  * `Nav` — ONE component that renders EITHER the horizontal top bar (`NavBar`) or the
@@ -242,76 +258,24 @@ type NavProps = ({
 declare const Nav: (props: NavProps) => React.ReactElement;
 
 /**
- * NavBarLink — a SINGLE horizontal `NavBar` link, extracted so each link owns its
- * own hover/focus state (React hooks can't be per-item inside a map otherwise).
- *
- * It renders the v1 `.gn-links a` affordance, THEME-DRIVEN (no hard-coded colours
- * beyond white ink on the accent pill):
- *   - rest    → muted text (`colors.rest`), no background
- *   - hover   → text brightens to full contrast (`colors.hoverText`) + a subtle
- *               rounded-pill background (`colors.hoverBg`, e.g. v1 `#16223a`)
- *   - active  → solid accent pill (`colors.activeBg`) with white ink + aria-current
- *   - focus   → a themed keyboard focus ring (`colors.ring`)
- * Hover/focus are WEB-only (react-native-web fires `onHoverIn/Out`); on native
- * those handlers never fire, so the link stays at its rest style.
+ * AppShell content-body helpers — the page-state cards (loading / error /
+ * forbidden) and the precedence rule that picks what renders inside the content
+ * column. Split out of `AppShell` so the shell file stays focused on layout /
+ * responsive composition. Colours are routed through the `@dloizides/ui-feedback`
+ * theme, same as the rest of `@dloizides/ui-nav`.
  */
 
-/** Theme-resolved colours a link needs, computed once by `NavBar`. */
-interface NavBarLinkColors {
-    /** Muted link text at rest. */
-    rest: string;
-    /** Brightened link text on hover. */
-    hoverText: string;
-    /** Subtle hover-pill background. */
-    hoverBg: string;
-    /** Active-pill background (accent). */
-    activeBg: string;
-    /** Focus-ring colour. */
-    ring: string;
+/** A titled message card (error / forbidden). Colours come from the theme. */
+interface ShellMessage {
+    titleText: string;
+    messageText: string;
 }
-
-/**
- * NavOverflowMenu — the "More ▾" trigger + dropdown that holds the `NavBar` items
- * which don't fit inline (the priority+ overflow set).
- *
- * It REUSES the shared `@dloizides/ui-layout` `ModalDropdown` — the exact component
- * every other menu in the app uses — so the overflow menu is portalled, keyboard
- * navigable, dismissed on outside-click / Escape, and opens on click, looking
- * identical to the rest of the app's menus. The overflow entries are the same
- * `NavItem`s (label + route + active state); selecting one navigates via the same
- * `onNavigate` the inline links use.
- *
- * The trigger is a rounded pill matching a `NavBarLink`: muted at rest, and — when
- * the ACTIVE route lives in the overflow set — it wears the accent pill so the
- * active item stays visibly reachable behind the "…". The dropdown marks that same
- * item selected (its `value` is the active overflow route). a11y: `ModalDropdown`
- * owns the trigger's `role="button"` + `aria-expanded` + caller-supplied label/hint,
- * and gives the options keyboard navigation.
- *
- * Contract discipline (as the rest of `@dloizides/ui-nav`): no FM / router / icon
- * set / store; the label + hint are pre-localized strings from the caller and every
- * colour comes from the theme (via the `NavBarLinkColors` the `NavBar` computed).
- */
-
-interface NavOverflowMenuProps {
-    /** The items that spilled out of the inline row. */
-    items: NavItem[];
-    /** Current active route/path — decides the active-pill + selected option. */
-    pathname: string;
-    /** Navigation callback — receives the chosen item's `route`. */
-    onNavigate: (route: string) => void;
-    /** Theme-resolved link colours (same set the inline links use). */
-    colors: NavBarLinkColors;
-    /** Localized visible + accessible label for the trigger (e.g. "More"). */
-    label: string;
-    /** Localized accessibility hint for the trigger. */
-    hint: string;
-    /** testID for the trigger (options default to `` `${testID}-option-${route}` ``). */
-    testID: string;
-    /** Force a dropdown variant (default: responsive — inline menu on desktop). */
-    variant?: DropdownVariant;
+/** Page-state model — a loading spinner card, or a titled error / forbidden card. */
+interface ShellState {
+    loading?: boolean;
+    error?: ShellMessage | null;
+    forbidden?: ShellMessage | null;
 }
-declare const NavOverflowMenu: ({ items, pathname, onNavigate, colors, label, hint, testID, variant, }: NavOverflowMenuProps) => React.ReactElement;
 
 /**
  * MobileDrawer — the below-the-breakpoint face of `AppShell`'s back-office
@@ -340,6 +304,50 @@ interface DrawerLabels {
     closeHint: string;
 }
 
+/**
+ * Rail responsive mode — the pure (viewport → which rail face) rule behind
+ * `AppShell`'s optional THREE-tier layout, split out so it is directly
+ * unit-testable.
+ *
+ * Two-tier (default, back-compat): a persistent full rail at/above
+ * {@link RAIL_FULL_BREAKPOINT}, an overlay drawer below it. This is what every
+ * existing `AppShell` `sidebar` consumer already gets.
+ *
+ * Three-tier (opt-in — supply a `collapsedSidebar`): a persistent full rail on
+ * desktop, an intermediate persistent COLLAPSED (icon-only) rail on tablet, and
+ * the overlay drawer on a phone — the erevna / katalogos responsive scheme.
+ */
+/** At/above this viewport width the persistent FULL rail shows (two-tier boundary). */
+declare const RAIL_FULL_BREAKPOINT = 768;
+/** Default upper bound of the collapsed-rail band (full rail at/above this). */
+declare const DEFAULT_COLLAPSED_RAIL_MAX = 1024;
+/** Which face the rail takes at a given viewport. */
+type RailMode = 'none' | 'full' | 'collapsed' | 'drawer';
+/**
+ * Viewport band in which the intermediate COLLAPSED icon-rail shows: `[min, max)`.
+ * At/above `max` the full rail shows; below `min` the overlay drawer shows.
+ */
+interface CollapsedRailRange {
+    min: number;
+    max: number;
+}
+interface ResolveRailModeArgs {
+    viewport: number;
+    /** Whether a `sidebar` (full rail) node was supplied at all. */
+    hasSidebar: boolean;
+    /** Whether an intermediate `collapsedSidebar` node was supplied (enables 3-tier). */
+    hasCollapsed: boolean;
+    /** The collapsed-rail band; only consulted in 3-tier mode. */
+    range: CollapsedRailRange;
+}
+/**
+ * Resolve the rail mode. No sidebar ⇒ `'none'`. With a `collapsedSidebar`
+ * (3-tier): full at/above `range.max`, collapsed in `[range.min, range.max)`,
+ * drawer below `range.min`. Without one (2-tier, unchanged): full at/above
+ * {@link RAIL_FULL_BREAKPOINT}, drawer below.
+ */
+declare function resolveRailMode({ viewport, hasSidebar, hasCollapsed, range }: ResolveRailModeArgs): RailMode;
+
 /** Content-width policy: a capped column, optionally wider past a viewport breakpoint, or full-bleed. */
 type AppShellWidth = {
     max: number;
@@ -375,11 +383,6 @@ declare function useContentMaxWidth(width: AppShellWidth): number | 'full';
  * callbacks; every colour is routed through the `@dloizides/ui-feedback` theme.
  */
 
-/** A titled message card (error / forbidden). Colours come from the theme. */
-interface ShellMessage {
-    titleText: string;
-    messageText: string;
-}
 interface AppShellProps {
     /** App-supplied wired header (Topbar / AppHeader), rendered full-bleed. */
     header: React.ReactNode;
@@ -396,6 +399,21 @@ interface AppShellProps {
      * takes the full width. Desktop (≥768px) is unchanged. No effect without `sidebar`.
      */
     sidebar?: React.ReactNode;
+    /**
+     * Optional intermediate COLLAPSED (icon-only) rail — opts the `sidebar` layout
+     * into a THREE-tier responsive scheme (erevna / katalogos): the full `sidebar`
+     * on desktop, this collapsed rail on a tablet-width band, and the overlay drawer
+     * (hosting the full `sidebar`) on a phone. Omit it and the layout stays the
+     * unchanged two-tier scheme (full rail ≥768px, drawer below). No effect without
+     * `sidebar`. Exposed as `${testID}${APP_SHELL_SUFFIX.collapsedSidebar}`.
+     */
+    collapsedSidebar?: React.ReactNode;
+    /**
+     * The viewport band `[min, max)` in which `collapsedSidebar` shows: at/above
+     * `max` the full rail shows, below `min` the drawer shows. Defaults to
+     * `{ min: 768, max: 1024 }`. Only consulted when `collapsedSidebar` is supplied.
+     */
+    collapsedRailRange?: CollapsedRailRange;
     /**
      * Pre-localized labels for the mobile nav drawer (only used in the `sidebar`
      * layout, below the breakpoint): the hamburger's open label/hint and the scrim's
@@ -421,16 +439,360 @@ interface AppShellProps {
         onRedirect: () => void;
     };
     /** Page state — loading spinner card, or a titled error / forbidden card. */
-    state?: {
-        loading?: boolean;
-        error?: ShellMessage | null;
-        forbidden?: ShellMessage | null;
-    };
+    state?: ShellState;
     /** Root testID; the content region is exposed as `${testID}-content`. */
     testID: string;
     children: React.ReactNode;
 }
-declare const AppShell: ({ header, nav, sidebar, mobileMenu, banner, width, contentPadding, chromeAlignment, gate, state, testID, children, }: AppShellProps) => React.ReactElement | null;
+declare const AppShell: ({ header, nav, sidebar, collapsedSidebar, collapsedRailRange, mobileMenu, banner, width, contentPadding, chromeAlignment, gate, state, testID, children, }: AppShellProps) => React.ReactElement | null;
+
+/**
+ * NavShell — the ONE first-class navigation shell that renders a **top bar**, a
+ * **side rail**, or **BOTH together**, chosen by a single `layout` prop
+ * (`'top' | 'side' | 'both'`). It is the shell-level answer to `Nav`'s
+ * single-axis question: where `Nav` returns one element (a `NavBar` OR a
+ * `Sidebar`), `NavShell` owns the whole page composition — it wires a top bar
+ * into `AppShell`'s `header` slot and a side rail into `AppShell`'s `sidebar`
+ * slot, and inherits every `AppShell` capability (auth gate, loading / error /
+ * forbidden state cards, width discipline, banner, the responsive
+ * hamburger + overlay drawer for the rail).
+ *
+ *   layout="top"   → a horizontal top bar only (brand + links + overflow "…" + right).
+ *   layout="side"  → a header + a persistent left rail of sections (the erevna / katalogos shape).
+ *   layout="both"  → a top bar (brand / global links + overflow "…" / user) AND a side rail
+ *                    (sections), together — the AML-console shape, now first-class.
+ *
+ * "both" is inherently a shell composition (a top region + a side region + a
+ * content column), which a single-element `Nav` cannot own; `NavShell` is that
+ * composition, so no app hand-wires `Topbar` + `Sidebar` + a `ScrollView` row
+ * again. Customizability is STYLE-only: every colour flows through the
+ * `@dloizides/ui-feedback` UiProvider theme, and brand / user / language /
+ * notification / section content are render slots. Structure + behaviour are
+ * shared.
+ *
+ * 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.
+ */
+
+/** Which regions the shell renders: a top bar, a side rail, or both together. */
+type NavShellLayout = 'top' | 'side' | 'both';
+/**
+ * Config for the TOP bar (rendered as a `NavBar` in `AppShell`'s header slot).
+ * Used when `layout` is `'top'` or `'both'`. Every field is optional except the
+ * items — an empty `items` array renders a bar with just the brand + right slots
+ * (a plain top bar with no nav links), which is the natural `'side'`-mode header.
+ */
+interface NavShellTopBar {
+    /** Top-bar nav entries (global links). Empty ⇒ brand + right only. */
+    items: NavItem[];
+    /** Left slot — typically the tenant brand / logo. */
+    brand?: React.ReactNode;
+    /** Right slot — free-form (language toggle, notification bell, user chip, logout). */
+    right?: React.ReactNode;
+    /** Collapse the links behind a hamburger below this viewport width (default 760). */
+    collapseBelow?: number;
+    /** Localized visible + accessible label for the "More ▾" overflow trigger (default "More"). */
+    overflowLabel?: string;
+    /** Localized accessibility hint for the overflow trigger. */
+    overflowHint?: string;
+    /** 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 responsive toggle; defaults to ☰. */
+    renderMenuIcon?: (color: string, open: boolean) => React.ReactNode;
+    /**
+     * Extra container style overrides (e.g. an app-specific appbar background —
+     * including a web `background`/`backgroundImage` gradient cast through
+     * `ViewStyle`, the AML radial-glow appbar). Style-only.
+     */
+    containerStyle?: ViewStyle | ViewStyle[];
+    /**
+     * Optional CHROME theme override for the top bar only (dark bar over a light
+     * page). Forwarded to `NavBar.barTheme`. Style-only — see `NavBar`.
+     */
+    barTheme?: UiTheme;
+}
+/**
+ * Config for the intermediate COLLAPSED (icon-only) rail — opts the side layout
+ * into a THREE-tier responsive scheme (full rail → collapsed rail → drawer). When
+ * present, NavShell builds a `<CollapsedRail>` and hands it to `AppShell` for the
+ * tablet band; omit it and the layout stays two-tier.
+ */
+interface NavShellCollapsedRail {
+    /** Items for the icon rail. Defaults to the full rail's `items`. */
+    items?: NavItem[];
+    /** Optional header slot (e.g. a home shortcut). */
+    header?: React.ReactNode;
+    /** Optional footer slot (dark-mode toggle, logout). */
+    footer?: React.ReactNode;
+    /** The `[min, max)` viewport band for the collapsed rail (default `{ min: 768, max: 1024 }`). */
+    range?: CollapsedRailRange;
+}
+/**
+ * Config for the SIDE rail (rendered as a `Sidebar` in `AppShell`'s sidebar
+ * slot). Used when `layout` is `'side'` or `'both'`.
+ */
+interface NavShellSideRail {
+    /** Side-rail nav entries (sections — leaf + expandable). */
+    items: NavItem[];
+    /** Localized menu title (heading). */
+    title: string;
+    /** Optional header slot rendered above the items (e.g. a Home shortcut). */
+    header?: React.ReactNode;
+    /** Optional footer slot rendered after a flex spacer (dark-mode toggle, logout). */
+    footer?: React.ReactNode;
+    /** a11y hint shown when an expandable section is collapsed. */
+    expandHint?: string;
+    /** a11y hint shown when an expandable section is expanded. */
+    collapseHint?: string;
+    /** Optional chevron renderer for expandable sections. */
+    renderChevron?: (expanded: boolean, color: string, size: number) => React.ReactNode;
+    /** Extra container style overrides. */
+    containerStyle?: ViewStyle | ViewStyle[];
+    /** Optional collapsed (icon-only) rail config → the intermediate tablet tier. */
+    collapsed?: NavShellCollapsedRail;
+}
+/**
+ * `AppShell` props NavShell forwards straight through. It composes the `header`
+ * and `sidebar` (+ `collapsedSidebar`) regions itself, so those are handled here;
+ * everything else — including the optional `nav` strip (e.g. a `PillNav`), the
+ * auth gate, state cards, banner, and width policy — passes through untouched.
+ */
+type ForwardedShellProps = Omit<AppShellProps, 'header' | 'sidebar' | 'children'>;
+interface NavShellProps extends ForwardedShellProps {
+    /** Which regions to render: a top bar, a side rail, or both. */
+    layout: NavShellLayout;
+    /** Current active route/path — drives active highlighting on both regions. */
+    pathname: string;
+    /** Navigation callback — receives a `NavItem.route`. */
+    onNavigate: (route: string) => void;
+    /** Localized accessibility label for the navigation landmark(s). */
+    regionLabel: string;
+    /** a11y hint for a nav item, given its label. Defaults to the label. */
+    navigateHint?: (label: string) => string;
+    /**
+     * Top-bar config → a `NavBar` in the header slot. Required for `'top'` /
+     * `'both'`; ignored for `'side'` unless supplied (a `'side'` app may still pass
+     * a `topBar` with empty `items` for its brand + user header).
+     */
+    topBar?: NavShellTopBar;
+    /**
+     * Escape hatch: a ready-made header node (e.g. an app-composed `<Topbar>`).
+     * When supplied it REPLACES the `topBar`-built `NavBar` — used by `'side'`
+     * apps that want the structured `Topbar` (language / notification / user
+     * slots) instead of a `NavBar` header.
+     */
+    header?: React.ReactNode;
+    /**
+     * Side-rail config → a `Sidebar` in the sidebar slot. Required for `'side'` /
+     * `'both'`; ignored for `'top'`.
+     */
+    sideRail?: NavShellSideRail;
+    children: React.ReactNode;
+}
+declare const NavShell: ({ layout, pathname, onNavigate, regionLabel, navigateHint, topBar, header, sideRail, children, collapsedSidebar: collapsedSidebarProp, collapsedRailRange: collapsedRailRangeProp, ...shellProps }: NavShellProps) => React.ReactElement | null;
+
+/**
+ * CollapsedRail — the icon-only vertical rail for the intermediate (tablet) tier
+ * of `AppShell`'s three-tier responsive layout (the erevna / katalogos collapsed
+ * rail). It renders the SAME caller-supplied `NavItem[]` as `Sidebar`, but as a
+ * narrow strip of icon buttons: each item shows its `renderIcon` (or a first-letter
+ * glyph fallback), labelled for assistive tech, with the active route highlighted.
+ * Optional `header` / `footer` slots carry app chrome (a home shortcut, a
+ * dark-mode toggle, logout) top and bottom.
+ *
+ * A collapsed rail cannot expand a section inline, so pressing ANY item — leaf or
+ * parent — navigates to its `route`; an app that wants a parent to open the full
+ * drawer instead can special-case that in its `onNavigate`.
+ *
+ * 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` theme.
+ */
+
+interface CollapsedRailProps {
+    /** Nav entries — the same role-filtered `NavItem[]` the full `Sidebar` renders. */
+    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 an item, given its label. Defaults to the label. */
+    navigateHint?: (label: string) => string;
+    /** Optional header slot rendered above the items (e.g. a home shortcut). */
+    header?: React.ReactNode;
+    /** Optional footer slot rendered after a flex spacer (dark-mode toggle, logout). */
+    footer?: React.ReactNode;
+    /** Extra container style overrides. */
+    containerStyle?: ViewStyle | ViewStyle[];
+}
+declare const CollapsedRail: ({ items, pathname, onNavigate, regionLabel, navigateHint, header, footer, containerStyle, }: CollapsedRailProps) => React.ReactElement;
+
+/**
+ * PillNav — a horizontal row of fully-rounded "pills", the cross-navigation
+ * switcher promoted from kefi's coral dashboard nav. It renders the same
+ * caller-supplied `NavItem[]` as the other nav components, as pills that wrap,
+ * with the active route wearing the accent pill.
+ *
+ * It also folds in kefi's **visibility rule**: the whole nav hides (renders
+ * `null`) unless there are at least `minItems` entries — a single destination is
+ * not worth a switcher. Default `minItems` is 1 (always show when there is at
+ * least one item); kefi passes `2`.
+ *
+ * "Coral pills" is STYLE, not structure: the accent colour is the theme
+ * `palette.primary` (kefi's coral), the resting pill is `surfaceElevated`, and
+ * `containerStyle` / theme tokens carry any per-app tweak — no layout fork.
+ *
+ * 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` theme.
+ */
+
+interface PillNavProps {
+    /** Nav entries — the cross-navigation destinations. */
+    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 pill, given its label. Defaults to the label. */
+    navigateHint?: (label: string) => string;
+    /**
+     * Hide the whole switcher unless there are at least this many items. Default 1
+     * (show when non-empty); kefi passes 2 (a lone dashboard needs no switcher).
+     */
+    minItems?: number;
+    /** Extra container style overrides. */
+    containerStyle?: ViewStyle | ViewStyle[];
+}
+declare const PillNav: ({ items, pathname, onNavigate, regionLabel, navigateHint, minItems, containerStyle, }: PillNavProps) => React.ReactElement | null;
+
+/**
+ * DarkModeControl — the shared colour-scheme control promoted from erevna /
+ * katalogos (their Light / Dark / System toggle + the icon-only "cycle" button).
+ * It is a CONTROLLED component: the app owns the current `value` and applies the
+ * chosen scheme; this component only renders the choices and reports changes.
+ *
+ * Two variants encode the two behaviours the apps shipped:
+ *   - `"segmented"` (default): a row of segments (Light / Dark / System), the
+ *     active one highlighted — the desktop control.
+ *   - `"cycle"`: a single icon+label button that advances to the NEXT option on
+ *     each press (wrapping) — the compact mobile control.
+ *
+ * The options are pre-localized (`label` + `hint`) and value-agnostic (a string),
+ * so the app maps its own `DarkModePreference` enum to strings without this
+ * package importing it. Every colour flows through the `@dloizides/ui-feedback`
+ * theme; STYLE is the only per-app variation.
+ */
+
+/** Which control shape to render. */
+type DarkModeVariant = 'segmented' | 'cycle';
+/** One pre-localized colour-scheme choice (e.g. Light / Dark / System). */
+interface DarkModeOption {
+    /** App-defined value (its own preference enum mapped to a string). */
+    value: string;
+    /** Localized visible + accessible label. */
+    label: string;
+    /** Localized accessibility hint. */
+    hint: string;
+    /** Optional leading icon. Receives the resolved colour + size. */
+    renderIcon?: (color: string, size: number) => React.ReactNode;
+}
+interface DarkModeControlProps {
+    /** Current selected value — must match one of `options[].value`. */
+    value: string;
+    /** The pre-localized choices (typically Light / Dark / System). */
+    options: DarkModeOption[];
+    /** Change callback — receives the newly-selected value. */
+    onChange: (value: string) => void;
+    /** Localized accessibility label for the control group. */
+    regionLabel: string;
+    /** Control shape — a segmented row (default) or a single cycling button. */
+    variant?: DarkModeVariant;
+    /** testID for the control; segments are `${testID}-${value}`. */
+    testID?: string;
+    /** Extra container style overrides. */
+    containerStyle?: ViewStyle | ViewStyle[];
+}
+declare const DarkModeControl: ({ value, options, onChange, regionLabel, variant, testID, containerStyle, }: DarkModeControlProps) => React.ReactElement | null;
+
+/**
+ * NavBarLink — a SINGLE horizontal `NavBar` link, extracted so each link owns its
+ * own hover/focus state (React hooks can't be per-item inside a map otherwise).
+ *
+ * It renders the v1 `.gn-links a` affordance, THEME-DRIVEN (no hard-coded colours
+ * beyond white ink on the accent pill):
+ *   - rest    → muted text (`colors.rest`), no background
+ *   - hover   → text brightens to full contrast (`colors.hoverText`) + a subtle
+ *               rounded-pill background (`colors.hoverBg`, e.g. v1 `#16223a`)
+ *   - active  → solid accent pill (`colors.activeBg`) with white ink + aria-current
+ *   - focus   → a themed keyboard focus ring (`colors.ring`)
+ * Hover/focus are WEB-only (react-native-web fires `onHoverIn/Out`); on native
+ * those handlers never fire, so the link stays at its rest style.
+ */
+
+/** Theme-resolved colours a link needs, computed once by `NavBar`. */
+interface NavBarLinkColors {
+    /** Muted link text at rest. */
+    rest: string;
+    /** Brightened link text on hover. */
+    hoverText: string;
+    /** Subtle hover-pill background. */
+    hoverBg: string;
+    /** Active-pill background (accent). */
+    activeBg: string;
+    /** Focus-ring colour. */
+    ring: string;
+}
+
+/**
+ * NavOverflowMenu — the "More ▾" trigger + dropdown that holds the `NavBar` items
+ * which don't fit inline (the priority+ overflow set).
+ *
+ * It REUSES the shared `@dloizides/ui-layout` `ModalDropdown` — the exact component
+ * every other menu in the app uses — so the overflow menu is portalled, keyboard
+ * navigable, dismissed on outside-click / Escape, and opens on click, looking
+ * identical to the rest of the app's menus. The overflow entries are the same
+ * `NavItem`s (label + route + active state); selecting one navigates via the same
+ * `onNavigate` the inline links use.
+ *
+ * The trigger is a rounded pill matching a `NavBarLink`: muted at rest, and — when
+ * the ACTIVE route lives in the overflow set — it wears the accent pill so the
+ * active item stays visibly reachable behind the "…". The dropdown marks that same
+ * item selected (its `value` is the active overflow route). a11y: `ModalDropdown`
+ * owns the trigger's `role="button"` + `aria-expanded` + caller-supplied label/hint,
+ * and gives the options keyboard navigation.
+ *
+ * Contract discipline (as the rest of `@dloizides/ui-nav`): no FM / router / icon
+ * set / store; the label + hint are pre-localized strings from the caller and every
+ * colour comes from the theme (via the `NavBarLinkColors` the `NavBar` computed).
+ */
+
+interface NavOverflowMenuProps {
+    /** The items that spilled out of the inline row. */
+    items: NavItem[];
+    /** Current active route/path — decides the active-pill + selected option. */
+    pathname: string;
+    /** Navigation callback — receives the chosen item's `route`. */
+    onNavigate: (route: string) => void;
+    /** Theme-resolved link colours (same set the inline links use). */
+    colors: NavBarLinkColors;
+    /** Localized visible + accessible label for the trigger (e.g. "More"). */
+    label: string;
+    /** Localized accessibility hint for the trigger. */
+    hint: string;
+    /** testID for the trigger (options default to `` `${testID}-option-${route}` ``). */
+    testID: string;
+    /** Force a dropdown variant (default: responsive — inline menu on desktop). */
+    variant?: DropdownVariant;
+}
+declare const NavOverflowMenu: ({ items, pathname, onNavigate, colors, label, hint, testID, variant, }: NavOverflowMenuProps) => React.ReactElement;
 
 /**
  * Default testIDs for `@dloizides/ui-nav`. Kept as a small central map (mirrors
@@ -462,6 +824,8 @@ declare const APP_SHELL_SUFFIX: {
     readonly nav: "-nav";
     /** The persistent left rail of the back-office layout (only when `sidebar` is supplied). */
     readonly sidebar: "-sidebar";
+    /** The intermediate persistent COLLAPSED (icon-only) rail (3-tier layout, tablet band). */
+    readonly collapsedSidebar: "-collapsed-sidebar";
     /** Mobile hamburger that opens the nav drawer (back-office layout, below the breakpoint). */
     readonly menuToggle: "-menu-toggle";
     /** The mobile nav drawer panel (holds the `sidebar` slot when opened on a narrow viewport). */
@@ -605,6 +969,96 @@ declare const navStyles: {
         fontWeight: "700";
     };
 };
+declare const pillNavStyles: {
+    container: {
+        flexDirection: "row";
+        flexWrap: "wrap";
+        alignItems: "center";
+        columnGap: number;
+        rowGap: number;
+        paddingVertical: number;
+    };
+    pill: {
+        paddingHorizontal: number;
+        paddingVertical: number;
+        borderRadius: number;
+        minHeight: number;
+        flexDirection: "row";
+        alignItems: "center";
+        columnGap: number;
+        justifyContent: "center";
+    };
+    pillText: {
+        fontSize: number;
+        fontWeight: "600";
+    };
+};
+declare const darkModeStyles: {
+    segmentRow: {
+        flexDirection: "row";
+        alignItems: "center";
+        borderWidth: number;
+        borderRadius: number;
+        overflow: "hidden";
+        alignSelf: "flex-start";
+    };
+    segment: {
+        paddingHorizontal: number;
+        paddingVertical: number;
+        minHeight: number;
+        flexDirection: "row";
+        alignItems: "center";
+        columnGap: number;
+        justifyContent: "center";
+    };
+    segmentText: {
+        fontSize: number;
+        fontWeight: "600";
+    };
+    cycle: {
+        paddingHorizontal: number;
+        paddingVertical: number;
+        minHeight: number;
+        minWidth: number;
+        borderRadius: number;
+        flexDirection: "row";
+        alignItems: "center";
+        columnGap: number;
+        justifyContent: "center";
+    };
+    cycleText: {
+        fontSize: number;
+        fontWeight: "600";
+    };
+};
+declare const collapsedRailStyles: {
+    container: {
+        width: number;
+        paddingTop: number;
+        paddingHorizontal: number;
+        borderRightWidth: number;
+        height: "100%";
+        alignItems: "center";
+    };
+    item: {
+        width: number;
+        height: number;
+        marginVertical: number;
+        borderRadius: number;
+        alignItems: "center";
+        justifyContent: "center";
+    };
+    glyph: {
+        fontSize: number;
+        fontWeight: "700";
+    };
+    spacer: {
+        flex: number;
+    };
+    slot: {
+        alignItems: "center";
+    };
+};
 declare const expandableStyles: {
     childItem: {
         borderRadius: number;
@@ -648,4 +1102,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_LINK_GAP, NAV_TEST_IDS, Nav, NavBar, type NavBarProps, NavExpandableItem, type NavExpandableItemProps, type NavItem, type NavOrientation, NavOverflowMenu, type NavOverflowMenuProps, type NavProps, 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, CollapsedRail, type CollapsedRailProps, type CollapsedRailRange, DEFAULT_COLLAPSED_RAIL_MAX, DarkModeControl, type DarkModeControlProps, type DarkModeOption, type DarkModeVariant, NAV_ICON_SIZE, NAV_LINK_GAP, NAV_TEST_IDS, Nav, NavBar, type NavBarProps, NavExpandableItem, type NavExpandableItemProps, type NavItem, type NavOrientation, NavOverflowMenu, type NavOverflowMenuProps, type NavProps, NavShell, type NavShellCollapsedRail, type NavShellLayout, type NavShellProps, type NavShellSideRail, type NavShellTopBar, type NavUser, PillNav, type PillNavProps, RAIL_FULL_BREAKPOINT, type RailMode, type ResolveRailModeArgs, type ShellMessage, Sidebar, type SidebarProps, Topbar, type TopbarAction, type TopbarProps, type TopbarUser, accessibleNavItems, collapsedRailStyles, darkModeStyles, expandableStyles, isRouteActive, navStyles, pillNavStyles, resolveContentMaxWidth, resolveRailMode, roleRoutesToNavItems, useContentMaxWidth };