@dloizides/ui-nav 1.16.1 → 1.18.0

package/CHANGELOG.md

@@ -1,5 +1,59 @@
 # Changelog
 
+## 1.18.0
+
+Root-cause fix for sidebar leaf co-activation. Behavioral/additive — no breaking API.
+
+- **Fix (two sidebar leaves showed `aria-current="page"` at once).** On the live finreg
+  `/accounting/journals`, BOTH "Chart of Accounts" (route `/accounting`) and "Journals"
+  (route `/accounting/journals`) were marked active, because the active predicate was purely
+  prefix-based (`pathname === route || pathname.startsWith(route + '/')`) — a module-home leaf
+  routed at `/accounting` is a prefix of every `/accounting/*` sibling, so it co-activated on all
+  of them. (Second occurrence of this class; the first, CRM Contacts at `/crm`, was worked around
+  by moving the route.) Now resolution is **most-specific (longest) match wins**: among a nav
+  model's LEAF items, at most ONE is active for any path — the leaf whose route is the longest
+  prefix match. On `/accounting/journals` only Journals is active; on `/accounting` exactly only
+  Chart of Accounts is. For nav models with no parent/child route overlap (the common case)
+  behaviour is unchanged.
+  - **New export** `resolveActiveRoute(items, pathname)`: flattens the tree to its leaf routes and
+    returns the single longest matching route (honouring per-leaf `exact`), or `undefined`.
+  - `Sidebar` resolves the winning route once over the full leaf set and passes `activeRoute` to
+    each row; `NavExpandableItem` marks a leaf active iff `item.route === activeRoute` (falls back
+    to the per-item predicate when used standalone — backward compatible). Group HEADER expansion
+    (`hasActiveDescendant`) is a separate concern and is unchanged.
+  - The same winner-based resolution now backs `NavBar`, `PillNav`, `CollapsedRail` and
+    `NavOverflowMenu`, so the latent prefix co-activation cannot resurface in the horizontal navs.
+  - **Additive API**: new optional `NavItem.exact?: boolean` — a leaf active ONLY on its exact
+    path (never a nested one). A complementary escape hatch; the longest-match default is the real
+    fix, so no consumer needs to set it.
+  - `isRouteActive(pathname, route, exact?)` gains an optional third arg; the two-arg call is
+    unchanged.
+
+## 1.17.0
+
+Two live-defect fixes to the shared sidebar chrome. Behavioral/additive — no breaking API.
+
+- **Fix (two search bars on desktop → mutually exclusive by affordance).** 1.16.1 shipped the
+  desktop inline `SidebarSearch` field, but the ⌘K `CommandPaletteTrigger` could be present at
+  the same time, so a wide viewport showed BOTH. `Sidebar` now owns both affordances and renders
+  exactly ONE, chosen by its own viewport width via `resolveSearchAffordance`:
+  - inline affordance (≥768) → the inline field ONLY; the ⌘K trigger is suppressed.
+  - palette affordance (<768) → the ⌘K trigger ONLY; the inline field is suppressed.
+  - The ⌘K keyboard shortcut (`useCommandPaletteHotkey`) is untouched and stays bound at every width.
+  - **Additive API**: new `Sidebar.paletteTrigger?: SidebarPaletteTriggerConfig`
+    (`{ label, hint, shortcut, onOpen, testID? }`), forwarded from `NavShellSideRail.paletteTrigger`.
+    Consumers that wire neither, or only the inline field, are unchanged (the inline field simply
+    no longer renders below 768, where a persistent field would steal vertical space).
+
+- **Fix (hover wash never appeared on RN-web).** The nav rows were `TouchableOpacity`, which in
+  react-native-web has NO hover support and silently drops `onHoverIn`/`onHoverOut` — so the row's
+  `hovered` state never toggled and the primary-tinted overlay stayed at opacity 0. The leaf and
+  group-header rows in `NavExpandableItem` are now `Pressable`, whose `useHover` responder actually
+  drives `hovered`, lifting the token-tinted overlay to the hover wash (`HOVER_TINT_OPACITY`, ~160ms
+  reduced-motion-gated transition) — distinct from and lighter than the active tint. Token-only
+  (colours via the theme; no raw hex/rgb/hsl). aria wiring (`aria-current` / `aria-expanded`, which
+  `MobileDrawer` depends on) is preserved across the switch.
+
 ## 1.16.1
 
 - **Fix (NavShell forwards inline-search props to the inner `Sidebar`).** 1.16.0 added

package/dist/index.d.mts

@@ -5,12 +5,71 @@ import { DropdownVariant } from '@dloizides/ui-layout';
 import { resolveAccessibleRoutes, RoleRouteTable, RoleRoute } from '@dloizides/auth-web';
 
 /**
- * Active-route matcher shared by the sidebar entries. Ported verbatim from the
- * twin app sidebars: an item is active when the current pathname equals its
- * route or is nested under it (`/foo` matches `/foo` and `/foo/bar`, but `/`
- * only matches `/`).
+ * Public prop types for the `@dloizides/ui-nav` config-driven navigation shell.
+ *
+ * The rendering chrome (sidebar + topbar) was byte-identical across erevna-web
+ * and katalogos-web; only the *item data* (which routes, how they group) differs
+ * per app. So this package renders a caller-supplied `NavItem[]` — labels are
+ * pre-localized strings and icons are render slots, keeping the package free of
+ * any app's i18n helper, icon set, router, or store.
  */
-declare function isRouteActive(pathname: string, route: string): boolean;
+
+/** One navigation entry. Labels are already localized by the caller. */
+interface NavItem {
+    /** Stable key + default testID. */
+    key: string;
+    /** Localized display label. */
+    label: string;
+    /** Route/path this item navigates to (passed back to `onNavigate`). */
+    route: string;
+    /** Optional testID override (defaults to `key`). */
+    testID?: string;
+    /**
+     * Optional leading icon. Receives the resolved foreground colour and a size,
+     * so the app supplies its own icon component without this package importing
+     * an icon set.
+     */
+    renderIcon?: (color: string, size: number) => React.ReactNode;
+    /** Optional nested items — rendered as an expandable section. */
+    children?: NavItem[];
+    /**
+     * Opt this leaf out of prefix matching: when `true` it is active ONLY when the
+     * pathname equals its route exactly (never for a nested `route/child` path). A
+     * complementary escape hatch — the default most-specific/longest-match resolution
+     * (see `resolveActiveRoute`) already prevents a module-home leaf like `/accounting`
+     * from co-activating with `/accounting/journals`, so most consumers never need
+     * this. Reach for it only when a leaf must NEVER light up on any descendant path
+     * even when no longer sibling route exists.
+     */
+    exact?: boolean;
+}
+
+/**
+ * Active-route matching for the nav shells.
+ *
+ * `isRouteActive` is the low-level per-route predicate (prefix-based, ported
+ * verbatim from the twin app sidebars): a route is active when the current
+ * pathname equals it or is nested under it (`/foo` matches `/foo` and `/foo/bar`,
+ * but `/` only matches `/`). With `exact`, only an exact path matches.
+ *
+ * `resolveActiveRoute` is the CROSS-ITEM resolver that fixes the sidebar
+ * co-activation bug: because a module-home leaf (`/accounting`) is a prefix of
+ * every sibling (`/accounting/journals`), the naive per-item predicate lights up
+ * BOTH on `/accounting/journals`. `resolveActiveRoute` instead returns the ONE
+ * most-specific (longest) leaf route that matches — so at most one leaf is ever
+ * active, the longest wins on nested paths, and the module-home leaf is active
+ * only on its own exact path. For a nav model with no parent/child route overlap
+ * (the common case) this is identical to the old behaviour.
+ */
+
+declare function isRouteActive(pathname: string, route: string, exact?: boolean): boolean;
+/**
+ * The single active leaf route for `pathname`: the LONGEST leaf route that
+ * matches (most-specific wins). Returns `undefined` when no leaf matches. Marking
+ * a leaf active iff `item.route === resolveActiveRoute(items, pathname)` guarantees
+ * at most one active leaf — the whack-a-mole prefix co-activation fix.
+ */
+declare function resolveActiveRoute(items: NavItem[], pathname: string): string | undefined;
 
 /**
  * SidebarSearch — the persistent, DESKTOP inline search field that lives at the
@@ -51,36 +110,6 @@ interface SidebarSearchProps {
 /** The inline sidebar search field (desktop) with a clear button. */
 declare const SidebarSearch: ({ value, onChangeText, onClear, labels, testID, }: SidebarSearchProps) => React.ReactElement;
 
-/**
- * Public prop types for the `@dloizides/ui-nav` config-driven navigation shell.
- *
- * The rendering chrome (sidebar + topbar) was byte-identical across erevna-web
- * and katalogos-web; only the *item data* (which routes, how they group) differs
- * per app. So this package renders a caller-supplied `NavItem[]` — labels are
- * pre-localized strings and icons are render slots, keeping the package free of
- * any app's i18n helper, icon set, router, or store.
- */
-
-/** One navigation entry. Labels are already localized by the caller. */
-interface NavItem {
-    /** Stable key + default testID. */
-    key: string;
-    /** Localized display label. */
-    label: string;
-    /** Route/path this item navigates to (passed back to `onNavigate`). */
-    route: string;
-    /** Optional testID override (defaults to `key`). */
-    testID?: string;
-    /**
-     * Optional leading icon. Receives the resolved foreground colour and a size,
-     * so the app supplies its own icon component without this package importing
-     * an icon set.
-     */
-    renderIcon?: (color: string, size: number) => React.ReactNode;
-    /** Optional nested items — rendered as an expandable section. */
-    children?: NavItem[];
-}
-
 /**
  * Sidebar — the config-driven left navigation shell promoted from the
  * byte-identical erevna-web / katalogos-web `Sidebar`. It renders a caller
@@ -100,6 +129,24 @@ interface SidebarSearchConfig extends SidebarSearchLabels {
     /** Shown in place of the list when the query matches nothing. */
     emptyText: string;
 }
+/**
+ * The ⌘K command-palette trigger the sidebar renders as its NARROW-viewport search
+ * affordance (a persistent inline field would steal scarce vertical space on mobile
+ * — see {@link resolveSearchAffordance}). Pre-localized strings + the open handler;
+ * wire `onOpen` to the same handler as the ⌘K hotkey ({@link useCommandPaletteHotkey}).
+ */
+interface SidebarPaletteTriggerConfig {
+    /** Placeholder-style label, e.g. "Search". */
+    label: string;
+    /** a11y hint describing what activating it does. */
+    hint: string;
+    /** The shortcut badge text, e.g. "⌘K". */
+    shortcut: string;
+    /** Open the palette (same handler as the ⌘K hotkey). */
+    onOpen: () => void;
+    /** testID for the trigger. Defaults to `sidebar-command-palette-trigger`. */
+    testID?: string;
+}
 interface SidebarProps {
     /** Nav entries — already role-filtered / grouped by the app. */
     items: NavItem[];
@@ -121,12 +168,21 @@ interface SidebarProps {
     renderChevron?: (expanded: boolean, color: string, size: number) => React.ReactNode;
     /**
      * Opt into the persistent inline search field (desktop). Requires `search`
-     * labels; when omitted the sidebar renders exactly as before. Prefer this on
-     * the wide/full rail and the ⌘K palette on the mobile drawer.
+     * labels; when omitted the sidebar renders exactly as before. The field shows
+     * ONLY at the inline affordance (viewport ≥ 768, {@link resolveSearchAffordance});
+     * on a narrow viewport the ⌘K `paletteTrigger` is the search affordance instead.
      */
     enableInlineSearch?: boolean;
     /** Pre-localized inline-search strings — required for `enableInlineSearch`. */
     search?: SidebarSearchConfig;
+    /**
+     * Opt into the ⌘K {@link CommandPaletteTrigger} as the NARROW-viewport search
+     * affordance. Rendered ONLY at the palette affordance (viewport < 768); on a wide
+     * viewport it is suppressed so the inline field and the trigger are never both
+     * shown — they are mutually exclusive by affordance. The ⌘K hotkey stays bound at
+     * every width independently ({@link useCommandPaletteHotkey}).
+     */
+    paletteTrigger?: SidebarPaletteTriggerConfig;
     /** Controlled search query (optional — the sidebar owns the state when omitted). */
     searchQuery?: string;
     /** Called on each query change (with either controlled or internal state). */
@@ -138,7 +194,7 @@ interface SidebarProps {
     /** Extra container style overrides. */
     containerStyle?: ViewStyle | ViewStyle[];
 }
-declare const Sidebar: ({ items, pathname, onNavigate, title, regionLabel, navigateHint, expandHint, collapseHint, renderChevron, enableInlineSearch, search, searchQuery, onSearchChange, header, footer, containerStyle, }: SidebarProps) => React.ReactElement;
+declare const Sidebar: ({ items, pathname, onNavigate, title, regionLabel, navigateHint, expandHint, collapseHint, renderChevron, enableInlineSearch, search, paletteTrigger, searchQuery, onSearchChange, header, footer, containerStyle, }: SidebarProps) => React.ReactElement;
 
 /**
  * SidebarChevron — the built-in disclosure caret for an expandable sidebar
@@ -737,6 +793,12 @@ interface NavShellSideRail {
     enableInlineSearch?: boolean;
     /** Pre-localized inline-search strings — required for `enableInlineSearch`. Forwarded to `Sidebar.search`. */
     search?: SidebarSearchConfig;
+    /**
+     * Opt the inner `Sidebar` into the ⌘K palette trigger as its narrow-viewport
+     * search affordance. Mutually exclusive with the inline field by viewport width
+     * (never both shown). Forwarded to `Sidebar.paletteTrigger`.
+     */
+    paletteTrigger?: SidebarPaletteTriggerConfig;
     /** Controlled search query (optional — the Sidebar owns the state when omitted). Forwarded to `Sidebar.searchQuery`. */
     searchQuery?: string;
     /** Called on each query change (controlled or internal). Forwarded to `Sidebar.onSearchChange`. */
@@ -1047,6 +1109,15 @@ interface NavExpandableItemProps {
     item: NavItem;
     pathname: string;
     onNavigate: (route: string) => void;
+    /**
+     * The single winning active leaf route for the whole nav model, resolved once by
+     * the parent via `resolveActiveRoute` (most-specific/longest match wins). A leaf
+     * is active iff `item.route === activeRoute`, so at most one leaf ever carries
+     * `aria-current="page"` — the fix for `/accounting` co-activating with
+     * `/accounting/journals`. When omitted (standalone use) each leaf falls back to
+     * the per-item prefix predicate, preserving the pre-1.18 behaviour.
+     */
+    activeRoute?: string;
     /** a11y hint for a leaf item, given its label. */
     navigateHint: (label: string) => string;
     /** a11y hint shown when the section is collapsed (press expands). */
@@ -1061,7 +1132,7 @@ interface NavExpandableItemProps {
     renderChevron?: (expanded: boolean, color: string, size: number) => React.ReactNode;
     depth?: number;
 }
-declare const NavExpandableItem: ({ item, pathname, onNavigate, navigateHint, expandHint, collapseHint, renderChevron, depth, }: NavExpandableItemProps) => React.ReactElement;
+declare const NavExpandableItem: ({ item, pathname, onNavigate, navigateHint, expandHint, collapseHint, renderChevron, activeRoute, depth, }: NavExpandableItemProps) => React.ReactElement;
 
 /**
  * Pure matching logic for the {@link CommandPalette}. Kept framework-free so the
@@ -1233,6 +1304,9 @@ declare const navStyles: {
     sidebarSpacer: {
         flex: number;
     };
+    sidebarTriggerSlot: {
+        marginBottom: number;
+    };
     sidebarEmpty: {
         fontSize: number;
         paddingVertical: number;
@@ -1453,4 +1527,4 @@ declare const NAV_ICON_SIZE = 14;
 /** Chevron icon size for expandable sections. */
 declare const CHEVRON_ICON_SIZE = 12;
 
-export { ACTIVE_BORDER_RADIUS, ACTIVE_TINT_OPACITY, APP_SHELL_SUFFIX, type AccountPlan, type AccountState, AppShell, type AppShellProps, type AppShellWidth, BASE_INDENT, CHEVRON_ICON_SIZE, CollapsedRail, type CollapsedRailProps, type CollapsedRailRange, type CommandItem, CommandPalette, type CommandPaletteLabels, type CommandPaletteProps, CommandPaletteTrigger, type CommandPaletteTriggerProps, DEFAULT_COLLAPSED_RAIL_MAX, DEFAULT_SEARCH_BREAKPOINT, DarkModeControl, type DarkModeControlProps, type DarkModeOption, type DarkModeVariant, HOVER_TINT_OPACITY, NAV_ICON_SIZE, NAV_LINK_GAP, NAV_ROW_RADIUS, 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 SearchAffordance, type ShellMessage, Sidebar, SidebarChevron, type SidebarChevronProps, type SidebarProps, SidebarSearch, type SidebarSearchConfig, type SidebarSearchLabels, type SidebarSearchProps, Topbar, type TopbarAction, type TopbarProps, type TopbarUser, accessibleNavItems, collapsedRailStyles, darkModeStyles, expandableStyles, filterCommands, filterNavItems, isFilterActive, isRouteActive, navStyles, pillNavStyles, resolveContentMaxWidth, resolveRailMode, resolveSearchAffordance, roleRoutesToNavItems, searchTokens, useCommandPaletteHotkey, useContentMaxWidth };
+export { ACTIVE_BORDER_RADIUS, ACTIVE_TINT_OPACITY, APP_SHELL_SUFFIX, type AccountPlan, type AccountState, AppShell, type AppShellProps, type AppShellWidth, BASE_INDENT, CHEVRON_ICON_SIZE, CollapsedRail, type CollapsedRailProps, type CollapsedRailRange, type CommandItem, CommandPalette, type CommandPaletteLabels, type CommandPaletteProps, CommandPaletteTrigger, type CommandPaletteTriggerProps, DEFAULT_COLLAPSED_RAIL_MAX, DEFAULT_SEARCH_BREAKPOINT, DarkModeControl, type DarkModeControlProps, type DarkModeOption, type DarkModeVariant, HOVER_TINT_OPACITY, NAV_ICON_SIZE, NAV_LINK_GAP, NAV_ROW_RADIUS, 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 SearchAffordance, type ShellMessage, Sidebar, SidebarChevron, type SidebarChevronProps, type SidebarPaletteTriggerConfig, type SidebarProps, SidebarSearch, type SidebarSearchConfig, type SidebarSearchLabels, type SidebarSearchProps, Topbar, type TopbarAction, type TopbarProps, type TopbarUser, accessibleNavItems, collapsedRailStyles, darkModeStyles, expandableStyles, filterCommands, filterNavItems, isFilterActive, isRouteActive, navStyles, pillNavStyles, resolveActiveRoute, resolveContentMaxWidth, resolveRailMode, resolveSearchAffordance, roleRoutesToNavItems, searchTokens, useCommandPaletteHotkey, useContentMaxWidth };

package/dist/index.d.ts

@@ -5,12 +5,71 @@ import { DropdownVariant } from '@dloizides/ui-layout';
 import { resolveAccessibleRoutes, RoleRouteTable, RoleRoute } from '@dloizides/auth-web';
 
 /**
- * Active-route matcher shared by the sidebar entries. Ported verbatim from the
- * twin app sidebars: an item is active when the current pathname equals its
- * route or is nested under it (`/foo` matches `/foo` and `/foo/bar`, but `/`
- * only matches `/`).
+ * Public prop types for the `@dloizides/ui-nav` config-driven navigation shell.
+ *
+ * The rendering chrome (sidebar + topbar) was byte-identical across erevna-web
+ * and katalogos-web; only the *item data* (which routes, how they group) differs
+ * per app. So this package renders a caller-supplied `NavItem[]` — labels are
+ * pre-localized strings and icons are render slots, keeping the package free of
+ * any app's i18n helper, icon set, router, or store.
  */
-declare function isRouteActive(pathname: string, route: string): boolean;
+
+/** One navigation entry. Labels are already localized by the caller. */
+interface NavItem {
+    /** Stable key + default testID. */
+    key: string;
+    /** Localized display label. */
+    label: string;
+    /** Route/path this item navigates to (passed back to `onNavigate`). */
+    route: string;
+    /** Optional testID override (defaults to `key`). */
+    testID?: string;
+    /**
+     * Optional leading icon. Receives the resolved foreground colour and a size,
+     * so the app supplies its own icon component without this package importing
+     * an icon set.
+     */
+    renderIcon?: (color: string, size: number) => React.ReactNode;
+    /** Optional nested items — rendered as an expandable section. */
+    children?: NavItem[];
+    /**
+     * Opt this leaf out of prefix matching: when `true` it is active ONLY when the
+     * pathname equals its route exactly (never for a nested `route/child` path). A
+     * complementary escape hatch — the default most-specific/longest-match resolution
+     * (see `resolveActiveRoute`) already prevents a module-home leaf like `/accounting`
+     * from co-activating with `/accounting/journals`, so most consumers never need
+     * this. Reach for it only when a leaf must NEVER light up on any descendant path
+     * even when no longer sibling route exists.
+     */
+    exact?: boolean;
+}
+
+/**
+ * Active-route matching for the nav shells.
+ *
+ * `isRouteActive` is the low-level per-route predicate (prefix-based, ported
+ * verbatim from the twin app sidebars): a route is active when the current
+ * pathname equals it or is nested under it (`/foo` matches `/foo` and `/foo/bar`,
+ * but `/` only matches `/`). With `exact`, only an exact path matches.
+ *
+ * `resolveActiveRoute` is the CROSS-ITEM resolver that fixes the sidebar
+ * co-activation bug: because a module-home leaf (`/accounting`) is a prefix of
+ * every sibling (`/accounting/journals`), the naive per-item predicate lights up
+ * BOTH on `/accounting/journals`. `resolveActiveRoute` instead returns the ONE
+ * most-specific (longest) leaf route that matches — so at most one leaf is ever
+ * active, the longest wins on nested paths, and the module-home leaf is active
+ * only on its own exact path. For a nav model with no parent/child route overlap
+ * (the common case) this is identical to the old behaviour.
+ */
+
+declare function isRouteActive(pathname: string, route: string, exact?: boolean): boolean;
+/**
+ * The single active leaf route for `pathname`: the LONGEST leaf route that
+ * matches (most-specific wins). Returns `undefined` when no leaf matches. Marking
+ * a leaf active iff `item.route === resolveActiveRoute(items, pathname)` guarantees
+ * at most one active leaf — the whack-a-mole prefix co-activation fix.
+ */
+declare function resolveActiveRoute(items: NavItem[], pathname: string): string | undefined;
 
 /**
  * SidebarSearch — the persistent, DESKTOP inline search field that lives at the
@@ -51,36 +110,6 @@ interface SidebarSearchProps {
 /** The inline sidebar search field (desktop) with a clear button. */
 declare const SidebarSearch: ({ value, onChangeText, onClear, labels, testID, }: SidebarSearchProps) => React.ReactElement;
 
-/**
- * Public prop types for the `@dloizides/ui-nav` config-driven navigation shell.
- *
- * The rendering chrome (sidebar + topbar) was byte-identical across erevna-web
- * and katalogos-web; only the *item data* (which routes, how they group) differs
- * per app. So this package renders a caller-supplied `NavItem[]` — labels are
- * pre-localized strings and icons are render slots, keeping the package free of
- * any app's i18n helper, icon set, router, or store.
- */
-
-/** One navigation entry. Labels are already localized by the caller. */
-interface NavItem {
-    /** Stable key + default testID. */
-    key: string;
-    /** Localized display label. */
-    label: string;
-    /** Route/path this item navigates to (passed back to `onNavigate`). */
-    route: string;
-    /** Optional testID override (defaults to `key`). */
-    testID?: string;
-    /**
-     * Optional leading icon. Receives the resolved foreground colour and a size,
-     * so the app supplies its own icon component without this package importing
-     * an icon set.
-     */
-    renderIcon?: (color: string, size: number) => React.ReactNode;
-    /** Optional nested items — rendered as an expandable section. */
-    children?: NavItem[];
-}
-
 /**
  * Sidebar — the config-driven left navigation shell promoted from the
  * byte-identical erevna-web / katalogos-web `Sidebar`. It renders a caller
@@ -100,6 +129,24 @@ interface SidebarSearchConfig extends SidebarSearchLabels {
     /** Shown in place of the list when the query matches nothing. */
     emptyText: string;
 }
+/**
+ * The ⌘K command-palette trigger the sidebar renders as its NARROW-viewport search
+ * affordance (a persistent inline field would steal scarce vertical space on mobile
+ * — see {@link resolveSearchAffordance}). Pre-localized strings + the open handler;
+ * wire `onOpen` to the same handler as the ⌘K hotkey ({@link useCommandPaletteHotkey}).
+ */
+interface SidebarPaletteTriggerConfig {
+    /** Placeholder-style label, e.g. "Search". */
+    label: string;
+    /** a11y hint describing what activating it does. */
+    hint: string;
+    /** The shortcut badge text, e.g. "⌘K". */
+    shortcut: string;
+    /** Open the palette (same handler as the ⌘K hotkey). */
+    onOpen: () => void;
+    /** testID for the trigger. Defaults to `sidebar-command-palette-trigger`. */
+    testID?: string;
+}
 interface SidebarProps {
     /** Nav entries — already role-filtered / grouped by the app. */
     items: NavItem[];
@@ -121,12 +168,21 @@ interface SidebarProps {
     renderChevron?: (expanded: boolean, color: string, size: number) => React.ReactNode;
     /**
      * Opt into the persistent inline search field (desktop). Requires `search`
-     * labels; when omitted the sidebar renders exactly as before. Prefer this on
-     * the wide/full rail and the ⌘K palette on the mobile drawer.
+     * labels; when omitted the sidebar renders exactly as before. The field shows
+     * ONLY at the inline affordance (viewport ≥ 768, {@link resolveSearchAffordance});
+     * on a narrow viewport the ⌘K `paletteTrigger` is the search affordance instead.
      */
     enableInlineSearch?: boolean;
     /** Pre-localized inline-search strings — required for `enableInlineSearch`. */
     search?: SidebarSearchConfig;
+    /**
+     * Opt into the ⌘K {@link CommandPaletteTrigger} as the NARROW-viewport search
+     * affordance. Rendered ONLY at the palette affordance (viewport < 768); on a wide
+     * viewport it is suppressed so the inline field and the trigger are never both
+     * shown — they are mutually exclusive by affordance. The ⌘K hotkey stays bound at
+     * every width independently ({@link useCommandPaletteHotkey}).
+     */
+    paletteTrigger?: SidebarPaletteTriggerConfig;
     /** Controlled search query (optional — the sidebar owns the state when omitted). */
     searchQuery?: string;
     /** Called on each query change (with either controlled or internal state). */
@@ -138,7 +194,7 @@ interface SidebarProps {
     /** Extra container style overrides. */
     containerStyle?: ViewStyle | ViewStyle[];
 }
-declare const Sidebar: ({ items, pathname, onNavigate, title, regionLabel, navigateHint, expandHint, collapseHint, renderChevron, enableInlineSearch, search, searchQuery, onSearchChange, header, footer, containerStyle, }: SidebarProps) => React.ReactElement;
+declare const Sidebar: ({ items, pathname, onNavigate, title, regionLabel, navigateHint, expandHint, collapseHint, renderChevron, enableInlineSearch, search, paletteTrigger, searchQuery, onSearchChange, header, footer, containerStyle, }: SidebarProps) => React.ReactElement;
 
 /**
  * SidebarChevron — the built-in disclosure caret for an expandable sidebar
@@ -737,6 +793,12 @@ interface NavShellSideRail {
     enableInlineSearch?: boolean;
     /** Pre-localized inline-search strings — required for `enableInlineSearch`. Forwarded to `Sidebar.search`. */
     search?: SidebarSearchConfig;
+    /**
+     * Opt the inner `Sidebar` into the ⌘K palette trigger as its narrow-viewport
+     * search affordance. Mutually exclusive with the inline field by viewport width
+     * (never both shown). Forwarded to `Sidebar.paletteTrigger`.
+     */
+    paletteTrigger?: SidebarPaletteTriggerConfig;
     /** Controlled search query (optional — the Sidebar owns the state when omitted). Forwarded to `Sidebar.searchQuery`. */
     searchQuery?: string;
     /** Called on each query change (controlled or internal). Forwarded to `Sidebar.onSearchChange`. */
@@ -1047,6 +1109,15 @@ interface NavExpandableItemProps {
     item: NavItem;
     pathname: string;
     onNavigate: (route: string) => void;
+    /**
+     * The single winning active leaf route for the whole nav model, resolved once by
+     * the parent via `resolveActiveRoute` (most-specific/longest match wins). A leaf
+     * is active iff `item.route === activeRoute`, so at most one leaf ever carries
+     * `aria-current="page"` — the fix for `/accounting` co-activating with
+     * `/accounting/journals`. When omitted (standalone use) each leaf falls back to
+     * the per-item prefix predicate, preserving the pre-1.18 behaviour.
+     */
+    activeRoute?: string;
     /** a11y hint for a leaf item, given its label. */
     navigateHint: (label: string) => string;
     /** a11y hint shown when the section is collapsed (press expands). */
@@ -1061,7 +1132,7 @@ interface NavExpandableItemProps {
     renderChevron?: (expanded: boolean, color: string, size: number) => React.ReactNode;
     depth?: number;
 }
-declare const NavExpandableItem: ({ item, pathname, onNavigate, navigateHint, expandHint, collapseHint, renderChevron, depth, }: NavExpandableItemProps) => React.ReactElement;
+declare const NavExpandableItem: ({ item, pathname, onNavigate, navigateHint, expandHint, collapseHint, renderChevron, activeRoute, depth, }: NavExpandableItemProps) => React.ReactElement;
 
 /**
  * Pure matching logic for the {@link CommandPalette}. Kept framework-free so the
@@ -1233,6 +1304,9 @@ declare const navStyles: {
     sidebarSpacer: {
         flex: number;
     };
+    sidebarTriggerSlot: {
+        marginBottom: number;
+    };
     sidebarEmpty: {
         fontSize: number;
         paddingVertical: number;
@@ -1453,4 +1527,4 @@ declare const NAV_ICON_SIZE = 14;
 /** Chevron icon size for expandable sections. */
 declare const CHEVRON_ICON_SIZE = 12;
 
-export { ACTIVE_BORDER_RADIUS, ACTIVE_TINT_OPACITY, APP_SHELL_SUFFIX, type AccountPlan, type AccountState, AppShell, type AppShellProps, type AppShellWidth, BASE_INDENT, CHEVRON_ICON_SIZE, CollapsedRail, type CollapsedRailProps, type CollapsedRailRange, type CommandItem, CommandPalette, type CommandPaletteLabels, type CommandPaletteProps, CommandPaletteTrigger, type CommandPaletteTriggerProps, DEFAULT_COLLAPSED_RAIL_MAX, DEFAULT_SEARCH_BREAKPOINT, DarkModeControl, type DarkModeControlProps, type DarkModeOption, type DarkModeVariant, HOVER_TINT_OPACITY, NAV_ICON_SIZE, NAV_LINK_GAP, NAV_ROW_RADIUS, 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 SearchAffordance, type ShellMessage, Sidebar, SidebarChevron, type SidebarChevronProps, type SidebarProps, SidebarSearch, type SidebarSearchConfig, type SidebarSearchLabels, type SidebarSearchProps, Topbar, type TopbarAction, type TopbarProps, type TopbarUser, accessibleNavItems, collapsedRailStyles, darkModeStyles, expandableStyles, filterCommands, filterNavItems, isFilterActive, isRouteActive, navStyles, pillNavStyles, resolveContentMaxWidth, resolveRailMode, resolveSearchAffordance, roleRoutesToNavItems, searchTokens, useCommandPaletteHotkey, useContentMaxWidth };
+export { ACTIVE_BORDER_RADIUS, ACTIVE_TINT_OPACITY, APP_SHELL_SUFFIX, type AccountPlan, type AccountState, AppShell, type AppShellProps, type AppShellWidth, BASE_INDENT, CHEVRON_ICON_SIZE, CollapsedRail, type CollapsedRailProps, type CollapsedRailRange, type CommandItem, CommandPalette, type CommandPaletteLabels, type CommandPaletteProps, CommandPaletteTrigger, type CommandPaletteTriggerProps, DEFAULT_COLLAPSED_RAIL_MAX, DEFAULT_SEARCH_BREAKPOINT, DarkModeControl, type DarkModeControlProps, type DarkModeOption, type DarkModeVariant, HOVER_TINT_OPACITY, NAV_ICON_SIZE, NAV_LINK_GAP, NAV_ROW_RADIUS, 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 SearchAffordance, type ShellMessage, Sidebar, SidebarChevron, type SidebarChevronProps, type SidebarPaletteTriggerConfig, type SidebarProps, SidebarSearch, type SidebarSearchConfig, type SidebarSearchLabels, type SidebarSearchProps, Topbar, type TopbarAction, type TopbarProps, type TopbarUser, accessibleNavItems, collapsedRailStyles, darkModeStyles, expandableStyles, filterCommands, filterNavItems, isFilterActive, isRouteActive, navStyles, pillNavStyles, resolveActiveRoute, resolveContentMaxWidth, resolveRailMode, resolveSearchAffordance, roleRoutesToNavItems, searchTokens, useCommandPaletteHotkey, useContentMaxWidth };