@dloizides/ui-nav 1.15.0 → 1.16.0

package/CHANGELOG.md

@@ -1,6 +1,40 @@
 # Changelog
 
-## 1.14.0
+## 1.16.0
+
+- **Feature (docs-style sidebar rail — hover wash, tinted active pill, rotating chevron).**
+  The `Sidebar` / `NavExpandableItem` rows now read like the aml-screening docs navigation:
+  each row carries a PRIMARY-TINTED overlay whose opacity eases `0 → hover → active` as a
+  smooth ~160ms CSS cross-fade on web (gated by `prefers-reduced-motion`, omitted on native).
+  - **Hover** lights a row with a subtle brand wash (`HOVER_TINT_OPACITY` = 0.06); **active**
+    deepens it to a soft brand pill (`ACTIVE_TINT_OPACITY` = 0.14) over the transparent
+    left-accent gutter every leaf already reserved, so the active leaf shows a tinted pill + a
+    coloured left bar + brand-coloured label — no layout shift, all from `theme.palette.primary`.
+  - **Rotating chevron.** Expandable groups now get a built-in `SidebarChevron` (a `›` glyph
+    that rotates to `⌄` on expand, tweened on web) when the caller supplies no `renderChevron`.
+    A caller-supplied `renderChevron` still wins, so existing icon-set chevrons are unaffected.
+  - Row corner radius softened to `NAV_ROW_RADIUS` (8px) with the rounded overlay clipped to it.
+  - No public API change to existing props; hover uses RNW's `onHoverIn`/`onHoverOut` (no-op on
+    native). New exports: `SidebarChevron`, `NAV_ROW_RADIUS`, `ACTIVE_TINT_OPACITY`,
+    `HOVER_TINT_OPACITY`.
+
+- **Feature (desktop INLINE sidebar search — opt-in — with the ⌘K palette kept for mobile).**
+  The owner found the ⌘K command-palette popup inconvenient on desktop. `Sidebar` now accepts
+  an opt-in persistent inline search field at the top of the rail that narrows the nav list
+  LIVE as you type.
+  - **New `Sidebar` props (all additive, default OFF):** `enableInlineSearch` + a pre-localized
+    `search: SidebarSearchConfig` (`placeholder` / `hint` / `clearLabel` / `clearHint` /
+    `emptyText`), plus optional controlled `searchQuery` + `onSearchChange` (the sidebar owns the
+    state when omitted). With the flag off the render tree is byte-identical to 1.15 — the mobile
+    drawer, which should keep using the ⌘K palette, is untouched.
+  - **New exports:** `SidebarSearch` (the field), `filterNavItems` / `isFilterActive` /
+    `searchTokens` (the pure tree-prune, same all-tokens-must-match semantics as `filterCommands`
+    so inline + ⌘K rank identically), and `resolveSearchAffordance(viewport)` +
+    `DEFAULT_SEARCH_BREAKPOINT` — the pure `'inline'` (≥768px) vs `'palette'` (<768px) rule so a
+    shell can wire desktop-inline / mobile-palette from one function. The ⌘K hotkey
+    (`useCommandPaletteHotkey`) stays bound at every width.
+
+## 1.15.0
 
 - **Feature (an expandable nav group now ANIMATES its expand/collapse instead of snapping).**
   `NavExpandableItem` used to conditionally render its children (`{expanded ? … : null}`),

package/README.md

@@ -217,6 +217,37 @@ 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.
 
+### Search — desktop inline field · mobile ⌘K palette
+
+The rail can be searched two ways, chosen by viewport. `resolveSearchAffordance(viewport)`
+is the pure rule: `'inline'` at/above `DEFAULT_SEARCH_BREAKPOINT` (768px), `'palette'` below.
+
+- **Desktop (wide):** opt the `Sidebar` into a persistent inline field that narrows the nav
+  list live as you type. It is OFF by default — pass `enableInlineSearch` + pre-localized
+  `search` labels:
+
+  ```tsx
+  <Sidebar
+    items={items} pathname={p} onNavigate={go} title={t} regionLabel={r}
+    enableInlineSearch
+    search={{
+      placeholder: FM('nav.search'), hint: FM('nav.searchHint'),
+      clearLabel: FM('nav.clear'), clearHint: FM('nav.clearHint'),
+      emptyText: FM('nav.noMatches'),
+    }}
+  />
+  ```
+
+  The sidebar owns the query (uncontrolled) unless you pass `searchQuery` + `onSearchChange`.
+  Filtering is the pure `filterNavItems(items, query)` (all query tokens must match a label;
+  a matched group keeps its children, a group with a matched descendant is kept pruned to it).
+
+- **Mobile (narrow):** keep the ⌘K `CommandPalette` (a persistent field costs too much
+  vertical space). The `useCommandPaletteHotkey` shortcut stays bound at every width.
+
+So a shell renders `resolveSearchAffordance(width) === 'inline' ? <Sidebar enableInlineSearch …/>
+: <CommandPalette …/>` (or simply passes `enableInlineSearch` only on the full-rail branch).
+
 ### Role gating
 
 `accessibleNavItems(user, roleRouteTable, translate)` builds the `NavItem[]` a user's roles

package/dist/index.d.mts

@@ -12,6 +12,45 @@ import { resolveAccessibleRoutes, RoleRouteTable, RoleRoute } from '@dloizides/a
  */
 declare function isRouteActive(pathname: string, route: string): boolean;
 
+/**
+ * SidebarSearch — the persistent, DESKTOP inline search field that lives at the
+ * top of the {@link Sidebar} and narrows the nav list live as the operator types.
+ * On a wide viewport a field is cheap and one keystroke filters the rail; on a
+ * narrow viewport the ⌘K {@link CommandPalette} is used instead (a persistent
+ * field would steal scarce vertical space) — see {@link resolveSearchAffordance}.
+ *
+ * Package discipline (as the rest of ui-nav): no FM / router / icon-set imports.
+ * The placeholder + a11y strings are pre-localized by the caller; every colour is
+ * read from the `@dloizides/ui-feedback` UiProvider theme. A clear ("✕") button
+ * appears once there is a query, wired to `onClear`.
+ */
+
+/** Pre-localized labels/strings for the inline search field. */
+interface SidebarSearchLabels {
+    /** Placeholder + accessible name of the input, e.g. "Search". */
+    placeholder: string;
+    /** a11y hint describing what typing does. */
+    hint: string;
+    /** Accessible name of the clear ("✕") button. */
+    clearLabel: string;
+    /** Accessible hint of the clear ("✕") button. */
+    clearHint: string;
+}
+interface SidebarSearchProps {
+    /** Current query value (controlled). */
+    value: string;
+    /** Called with the new query on every keystroke. */
+    onChangeText: (query: string) => void;
+    /** Clear the query (also called by the ✕ button). */
+    onClear: () => void;
+    /** Pre-localized chrome strings. */
+    labels: SidebarSearchLabels;
+    /** testID for the input (the clear button is `${testID}-clear`). */
+    testID: string;
+}
+/** 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.
  *
@@ -48,8 +87,19 @@ interface NavItem {
  * supplied `NavItem[]` (leaf + expandable), highlights the active route, and
  * exposes header/footer slots for app-specific chrome (title, dark-mode toggle,
  * logout, notification bell). Every colour is read from the UiProvider theme.
+ *
+ * Desktop inline search (v1.16, opt-in): pass `enableInlineSearch` + `search`
+ * labels and a persistent {@link SidebarSearch} field renders under the title and
+ * narrows the nav list live (via {@link filterNavItems}). It is OFF by default,
+ * so existing consumers — and the mobile drawer, which should use the ⌘K palette
+ * instead (see {@link resolveSearchAffordance}) — are byte-identical to before.
  */
 
+/** Inline-search chrome strings — the field labels plus the no-match empty text. */
+interface SidebarSearchConfig extends SidebarSearchLabels {
+    /** Shown in place of the list when the query matches nothing. */
+    emptyText: string;
+}
 interface SidebarProps {
     /** Nav entries — already role-filtered / grouped by the app. */
     items: NavItem[];
@@ -69,6 +119,18 @@ interface SidebarProps {
     collapseHint?: string;
     /** Optional chevron renderer for expandable sections. */
     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.
+     */
+    enableInlineSearch?: boolean;
+    /** Pre-localized inline-search strings — required for `enableInlineSearch`. */
+    search?: SidebarSearchConfig;
+    /** Controlled search query (optional — the sidebar owns the state when omitted). */
+    searchQuery?: string;
+    /** Called on each query change (with either controlled or internal state). */
+    onSearchChange?: (query: string) => void;
     /** 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). */
@@ -76,7 +138,85 @@ interface SidebarProps {
     /** Extra container style overrides. */
     containerStyle?: ViewStyle | ViewStyle[];
 }
-declare const Sidebar: ({ items, pathname, onNavigate, title, regionLabel, navigateHint, expandHint, collapseHint, renderChevron, header, footer, containerStyle, }: SidebarProps) => React.ReactElement;
+declare const Sidebar: ({ items, pathname, onNavigate, title, regionLabel, navigateHint, expandHint, collapseHint, renderChevron, enableInlineSearch, search, searchQuery, onSearchChange, header, footer, containerStyle, }: SidebarProps) => React.ReactElement;
+
+/**
+ * SidebarChevron — the built-in disclosure caret for an expandable sidebar
+ * group. A single "›" glyph that ROTATES from pointing-right (collapsed) to
+ * pointing-down (expanded); on web the rotation is a smooth CSS transform tween
+ * (reduced-motion snaps). Used as the DEFAULT when a `Sidebar`/`NavExpandableItem`
+ * caller supplies no `renderChevron`, so grouped rails get an animated caret for
+ * free while callers keep the option to render their own icon set.
+ *
+ * Package discipline: no icon-set import (the glyph is a plain character); the
+ * colour is passed in from the theme by the caller.
+ */
+
+interface SidebarChevronProps {
+    /** Whether the section is expanded (rotates the caret down). */
+    expanded: boolean;
+    /** Resolved caret colour (from the theme). */
+    color: string;
+    /** Caret font size (px). */
+    size: number;
+}
+/** The default animated disclosure caret for expandable sidebar sections. */
+declare const SidebarChevron: ({ expanded, color, size }: SidebarChevronProps) => React.ReactElement;
+
+/**
+ * Pure tree-filter for the desktop inline sidebar search. Kept framework-free so
+ * the narrowing is unit-testable without rendering. Given a `NavItem[]` tree and
+ * a query, it returns a PRUNED tree: a leaf survives when every whitespace-token
+ * of the query appears (case-insensitively) in its label; a group survives when
+ * it matches itself (kept with ALL its children, so the whole section stays
+ * browsable) OR when any descendant survives (kept with only the surviving
+ * descendants, so ancestors of a match are never orphaned). An empty/whitespace
+ * query returns the tree unchanged — the sidebar shows everything.
+ *
+ * Requiring ALL tokens lets an operator narrow with "pay dash" the way a fuzzy
+ * launcher would, matching the {@link filterCommands} palette semantics so the
+ * inline field and the ⌘K palette rank identically.
+ */
+
+/** Split a raw query into lower-cased match tokens (empty ⇒ no filtering). */
+declare function searchTokens(query: string): string[];
+/**
+ * Prune `items` to those matching `query`. Empty query ⇒ a shallow clone of the
+ * input (unchanged). A matching group keeps all its children; a non-matching
+ * group is kept only if it has surviving descendants (and then carries only
+ * those). Order is preserved.
+ */
+declare function filterNavItems(items: readonly NavItem[], query: string): NavItem[];
+/** True when the query is non-empty (filtering is active) — drives the empty state. */
+declare function isFilterActive(query: string): boolean;
+
+/**
+ * The desktop-vs-mobile search decision, split out as a pure rule so it is
+ * directly unit-testable. On a WIDE viewport a persistent inline field lives at
+ * the top of the sidebar (space is cheap, one keystroke narrows the rail); on a
+ * NARROW viewport a persistent field would steal scarce vertical space, so the
+ * ⌘K command palette is the search affordance instead. The ⌘K hotkey itself
+ * stays bound at every width (see {@link useCommandPaletteHotkey}); this rule
+ * only decides which VISIBLE affordance the shell renders.
+ *
+ * Expressed as a string union (not a `const enum`) to match the package's other
+ * public mode types ({@link RailMode}, {@link NavShellLayout}) and to stay safe
+ * for the Babel/Expo `isolatedModules` builds of the seven consuming portals,
+ * which cannot read a `declare const enum` across the package boundary.
+ */
+/** Which search affordance the shell shows at a given viewport. */
+type SearchAffordance = 'inline' | 'palette';
+/**
+ * Viewport width (px) at/above which the inline field shows. Mirrors the nav
+ * shell's {@link RAIL_FULL_BREAKPOINT} / {@link MOBILE_BREAKPOINT} so the inline
+ * field appears exactly where the persistent full rail does.
+ */
+declare const DEFAULT_SEARCH_BREAKPOINT = 768;
+/**
+ * Resolve the affordance: `'inline'` at/above `breakpoint`, `'palette'` below.
+ * `breakpoint` defaults to {@link DEFAULT_SEARCH_BREAKPOINT}.
+ */
+declare function resolveSearchAffordance(viewport: number, breakpoint?: number): SearchAffordance;
 
 /**
  * Topbar — the config-driven top navigation bar promoted from the byte-identical
@@ -880,6 +1020,14 @@ declare const APP_SHELL_SUFFIX: {
  * or an expandable section (toggles nested children). Ported from the twin
  * erevna/katalogos `Sidebar/NavExpandableItem`, made config-driven: labels are
  * pre-localized strings, icons are render slots, colours come from `useUi`.
+ *
+ * Docs-sidebar polish (v1.16): each row carries a PRIMARY-TINTED overlay whose
+ * opacity eases 0 → hover → active (a smooth ~160ms cross-fade on web, gated by
+ * reduced motion), over the transparent left-accent gutter every leaf reserves —
+ * so the active leaf reads as a tinted pill with a coloured left bar, and any row
+ * lights up subtly on hover, matching the aml-screening docs rail. Expandable
+ * groups get a built-in rotating {@link SidebarChevron} when the caller supplies
+ * no `renderChevron`.
  */
 
 interface NavExpandableItemProps {
@@ -892,7 +1040,11 @@ interface NavExpandableItemProps {
     expandHint: string;
     /** a11y hint shown when the section is expanded (press collapses). */
     collapseHint: string;
-    /** Optional chevron icon renderer for expandable sections. */
+    /**
+     * Optional chevron icon renderer for expandable sections. When omitted, a
+     * built-in rotating {@link SidebarChevron} is drawn — so grouped rails animate
+     * their disclosure caret without the caller supplying an icon set.
+     */
     renderChevron?: (expanded: boolean, color: string, size: number) => React.ReactNode;
     depth?: number;
 }
@@ -1029,6 +1181,15 @@ declare function roleRoutesToNavItems(routes: RoleRoute[], translate: (key: stri
 declare function accessibleNavItems(user: NavUser, table: RoleRouteTable, translate: (key: string) => string): NavItem[];
 
 declare const ACTIVE_BORDER_RADIUS = 4;
+/** Corner radius (px) of a sidebar row's hover/active pill — the docs-rail softness. */
+declare const NAV_ROW_RADIUS = 8;
+/**
+ * Opacity of the primary-tinted overlay behind the ACTIVE sidebar leaf — a soft
+ * brand pill (the aml-screening docs `.active` fill, flattened from its gradient).
+ */
+declare const ACTIVE_TINT_OPACITY = 0.14;
+/** Opacity of the same overlay on HOVER — the subtle docs-rail hover wash. */
+declare const HOVER_TINT_OPACITY = 0.06;
 /**
  * Horizontal gap (px) between adjacent inline items in the `NavBar` links row.
  * Single source of truth: it is both the row's `columnGap` AND the gap the
@@ -1059,6 +1220,11 @@ declare const navStyles: {
     sidebarSpacer: {
         flex: number;
     };
+    sidebarEmpty: {
+        fontSize: number;
+        paddingVertical: number;
+        paddingHorizontal: number;
+    };
     topbarContainer: {
         height: number;
         paddingHorizontal: number;
@@ -1207,6 +1373,8 @@ declare const collapsedRailStyles: {
 };
 declare const expandableStyles: {
     childItem: {
+        position: "relative";
+        overflow: "hidden";
         borderRadius: number;
         flexDirection: "row";
         alignItems: "center";
@@ -1228,7 +1396,18 @@ declare const expandableStyles: {
         overflow: "hidden";
         marginBottom: number;
     };
+    tintOverlay: {
+        position: "absolute";
+        top: number;
+        left: number;
+        right: number;
+        bottom: number;
+        borderRadius: number;
+        pointerEvents: "none";
+    };
     header: {
+        position: "relative";
+        overflow: "hidden";
         borderRadius: number;
         flexDirection: "row";
         alignItems: "center";
@@ -1261,4 +1440,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, CollapsedRail, type CollapsedRailProps, type CollapsedRailRange, type CommandItem, CommandPalette, type CommandPaletteLabels, type CommandPaletteProps, CommandPaletteTrigger, type CommandPaletteTriggerProps, 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, filterCommands, isRouteActive, navStyles, pillNavStyles, resolveContentMaxWidth, resolveRailMode, roleRoutesToNavItems, 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 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 };

package/dist/index.d.ts

@@ -12,6 +12,45 @@ import { resolveAccessibleRoutes, RoleRouteTable, RoleRoute } from '@dloizides/a
  */
 declare function isRouteActive(pathname: string, route: string): boolean;
 
+/**
+ * SidebarSearch — the persistent, DESKTOP inline search field that lives at the
+ * top of the {@link Sidebar} and narrows the nav list live as the operator types.
+ * On a wide viewport a field is cheap and one keystroke filters the rail; on a
+ * narrow viewport the ⌘K {@link CommandPalette} is used instead (a persistent
+ * field would steal scarce vertical space) — see {@link resolveSearchAffordance}.
+ *
+ * Package discipline (as the rest of ui-nav): no FM / router / icon-set imports.
+ * The placeholder + a11y strings are pre-localized by the caller; every colour is
+ * read from the `@dloizides/ui-feedback` UiProvider theme. A clear ("✕") button
+ * appears once there is a query, wired to `onClear`.
+ */
+
+/** Pre-localized labels/strings for the inline search field. */
+interface SidebarSearchLabels {
+    /** Placeholder + accessible name of the input, e.g. "Search". */
+    placeholder: string;
+    /** a11y hint describing what typing does. */
+    hint: string;
+    /** Accessible name of the clear ("✕") button. */
+    clearLabel: string;
+    /** Accessible hint of the clear ("✕") button. */
+    clearHint: string;
+}
+interface SidebarSearchProps {
+    /** Current query value (controlled). */
+    value: string;
+    /** Called with the new query on every keystroke. */
+    onChangeText: (query: string) => void;
+    /** Clear the query (also called by the ✕ button). */
+    onClear: () => void;
+    /** Pre-localized chrome strings. */
+    labels: SidebarSearchLabels;
+    /** testID for the input (the clear button is `${testID}-clear`). */
+    testID: string;
+}
+/** 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.
  *
@@ -48,8 +87,19 @@ interface NavItem {
  * supplied `NavItem[]` (leaf + expandable), highlights the active route, and
  * exposes header/footer slots for app-specific chrome (title, dark-mode toggle,
  * logout, notification bell). Every colour is read from the UiProvider theme.
+ *
+ * Desktop inline search (v1.16, opt-in): pass `enableInlineSearch` + `search`
+ * labels and a persistent {@link SidebarSearch} field renders under the title and
+ * narrows the nav list live (via {@link filterNavItems}). It is OFF by default,
+ * so existing consumers — and the mobile drawer, which should use the ⌘K palette
+ * instead (see {@link resolveSearchAffordance}) — are byte-identical to before.
  */
 
+/** Inline-search chrome strings — the field labels plus the no-match empty text. */
+interface SidebarSearchConfig extends SidebarSearchLabels {
+    /** Shown in place of the list when the query matches nothing. */
+    emptyText: string;
+}
 interface SidebarProps {
     /** Nav entries — already role-filtered / grouped by the app. */
     items: NavItem[];
@@ -69,6 +119,18 @@ interface SidebarProps {
     collapseHint?: string;
     /** Optional chevron renderer for expandable sections. */
     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.
+     */
+    enableInlineSearch?: boolean;
+    /** Pre-localized inline-search strings — required for `enableInlineSearch`. */
+    search?: SidebarSearchConfig;
+    /** Controlled search query (optional — the sidebar owns the state when omitted). */
+    searchQuery?: string;
+    /** Called on each query change (with either controlled or internal state). */
+    onSearchChange?: (query: string) => void;
     /** 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). */
@@ -76,7 +138,85 @@ interface SidebarProps {
     /** Extra container style overrides. */
     containerStyle?: ViewStyle | ViewStyle[];
 }
-declare const Sidebar: ({ items, pathname, onNavigate, title, regionLabel, navigateHint, expandHint, collapseHint, renderChevron, header, footer, containerStyle, }: SidebarProps) => React.ReactElement;
+declare const Sidebar: ({ items, pathname, onNavigate, title, regionLabel, navigateHint, expandHint, collapseHint, renderChevron, enableInlineSearch, search, searchQuery, onSearchChange, header, footer, containerStyle, }: SidebarProps) => React.ReactElement;
+
+/**
+ * SidebarChevron — the built-in disclosure caret for an expandable sidebar
+ * group. A single "›" glyph that ROTATES from pointing-right (collapsed) to
+ * pointing-down (expanded); on web the rotation is a smooth CSS transform tween
+ * (reduced-motion snaps). Used as the DEFAULT when a `Sidebar`/`NavExpandableItem`
+ * caller supplies no `renderChevron`, so grouped rails get an animated caret for
+ * free while callers keep the option to render their own icon set.
+ *
+ * Package discipline: no icon-set import (the glyph is a plain character); the
+ * colour is passed in from the theme by the caller.
+ */
+
+interface SidebarChevronProps {
+    /** Whether the section is expanded (rotates the caret down). */
+    expanded: boolean;
+    /** Resolved caret colour (from the theme). */
+    color: string;
+    /** Caret font size (px). */
+    size: number;
+}
+/** The default animated disclosure caret for expandable sidebar sections. */
+declare const SidebarChevron: ({ expanded, color, size }: SidebarChevronProps) => React.ReactElement;
+
+/**
+ * Pure tree-filter for the desktop inline sidebar search. Kept framework-free so
+ * the narrowing is unit-testable without rendering. Given a `NavItem[]` tree and
+ * a query, it returns a PRUNED tree: a leaf survives when every whitespace-token
+ * of the query appears (case-insensitively) in its label; a group survives when
+ * it matches itself (kept with ALL its children, so the whole section stays
+ * browsable) OR when any descendant survives (kept with only the surviving
+ * descendants, so ancestors of a match are never orphaned). An empty/whitespace
+ * query returns the tree unchanged — the sidebar shows everything.
+ *
+ * Requiring ALL tokens lets an operator narrow with "pay dash" the way a fuzzy
+ * launcher would, matching the {@link filterCommands} palette semantics so the
+ * inline field and the ⌘K palette rank identically.
+ */
+
+/** Split a raw query into lower-cased match tokens (empty ⇒ no filtering). */
+declare function searchTokens(query: string): string[];
+/**
+ * Prune `items` to those matching `query`. Empty query ⇒ a shallow clone of the
+ * input (unchanged). A matching group keeps all its children; a non-matching
+ * group is kept only if it has surviving descendants (and then carries only
+ * those). Order is preserved.
+ */
+declare function filterNavItems(items: readonly NavItem[], query: string): NavItem[];
+/** True when the query is non-empty (filtering is active) — drives the empty state. */
+declare function isFilterActive(query: string): boolean;
+
+/**
+ * The desktop-vs-mobile search decision, split out as a pure rule so it is
+ * directly unit-testable. On a WIDE viewport a persistent inline field lives at
+ * the top of the sidebar (space is cheap, one keystroke narrows the rail); on a
+ * NARROW viewport a persistent field would steal scarce vertical space, so the
+ * ⌘K command palette is the search affordance instead. The ⌘K hotkey itself
+ * stays bound at every width (see {@link useCommandPaletteHotkey}); this rule
+ * only decides which VISIBLE affordance the shell renders.
+ *
+ * Expressed as a string union (not a `const enum`) to match the package's other
+ * public mode types ({@link RailMode}, {@link NavShellLayout}) and to stay safe
+ * for the Babel/Expo `isolatedModules` builds of the seven consuming portals,
+ * which cannot read a `declare const enum` across the package boundary.
+ */
+/** Which search affordance the shell shows at a given viewport. */
+type SearchAffordance = 'inline' | 'palette';
+/**
+ * Viewport width (px) at/above which the inline field shows. Mirrors the nav
+ * shell's {@link RAIL_FULL_BREAKPOINT} / {@link MOBILE_BREAKPOINT} so the inline
+ * field appears exactly where the persistent full rail does.
+ */
+declare const DEFAULT_SEARCH_BREAKPOINT = 768;
+/**
+ * Resolve the affordance: `'inline'` at/above `breakpoint`, `'palette'` below.
+ * `breakpoint` defaults to {@link DEFAULT_SEARCH_BREAKPOINT}.
+ */
+declare function resolveSearchAffordance(viewport: number, breakpoint?: number): SearchAffordance;
 
 /**
  * Topbar — the config-driven top navigation bar promoted from the byte-identical
@@ -880,6 +1020,14 @@ declare const APP_SHELL_SUFFIX: {
  * or an expandable section (toggles nested children). Ported from the twin
  * erevna/katalogos `Sidebar/NavExpandableItem`, made config-driven: labels are
  * pre-localized strings, icons are render slots, colours come from `useUi`.
+ *
+ * Docs-sidebar polish (v1.16): each row carries a PRIMARY-TINTED overlay whose
+ * opacity eases 0 → hover → active (a smooth ~160ms cross-fade on web, gated by
+ * reduced motion), over the transparent left-accent gutter every leaf reserves —
+ * so the active leaf reads as a tinted pill with a coloured left bar, and any row
+ * lights up subtly on hover, matching the aml-screening docs rail. Expandable
+ * groups get a built-in rotating {@link SidebarChevron} when the caller supplies
+ * no `renderChevron`.
  */
 
 interface NavExpandableItemProps {
@@ -892,7 +1040,11 @@ interface NavExpandableItemProps {
     expandHint: string;
     /** a11y hint shown when the section is expanded (press collapses). */
     collapseHint: string;
-    /** Optional chevron icon renderer for expandable sections. */
+    /**
+     * Optional chevron icon renderer for expandable sections. When omitted, a
+     * built-in rotating {@link SidebarChevron} is drawn — so grouped rails animate
+     * their disclosure caret without the caller supplying an icon set.
+     */
     renderChevron?: (expanded: boolean, color: string, size: number) => React.ReactNode;
     depth?: number;
 }
@@ -1029,6 +1181,15 @@ declare function roleRoutesToNavItems(routes: RoleRoute[], translate: (key: stri
 declare function accessibleNavItems(user: NavUser, table: RoleRouteTable, translate: (key: string) => string): NavItem[];
 
 declare const ACTIVE_BORDER_RADIUS = 4;
+/** Corner radius (px) of a sidebar row's hover/active pill — the docs-rail softness. */
+declare const NAV_ROW_RADIUS = 8;
+/**
+ * Opacity of the primary-tinted overlay behind the ACTIVE sidebar leaf — a soft
+ * brand pill (the aml-screening docs `.active` fill, flattened from its gradient).
+ */
+declare const ACTIVE_TINT_OPACITY = 0.14;
+/** Opacity of the same overlay on HOVER — the subtle docs-rail hover wash. */
+declare const HOVER_TINT_OPACITY = 0.06;
 /**
  * Horizontal gap (px) between adjacent inline items in the `NavBar` links row.
  * Single source of truth: it is both the row's `columnGap` AND the gap the
@@ -1059,6 +1220,11 @@ declare const navStyles: {
     sidebarSpacer: {
         flex: number;
     };
+    sidebarEmpty: {
+        fontSize: number;
+        paddingVertical: number;
+        paddingHorizontal: number;
+    };
     topbarContainer: {
         height: number;
         paddingHorizontal: number;
@@ -1207,6 +1373,8 @@ declare const collapsedRailStyles: {
 };
 declare const expandableStyles: {
     childItem: {
+        position: "relative";
+        overflow: "hidden";
         borderRadius: number;
         flexDirection: "row";
         alignItems: "center";
@@ -1228,7 +1396,18 @@ declare const expandableStyles: {
         overflow: "hidden";
         marginBottom: number;
     };
+    tintOverlay: {
+        position: "absolute";
+        top: number;
+        left: number;
+        right: number;
+        bottom: number;
+        borderRadius: number;
+        pointerEvents: "none";
+    };
     header: {
+        position: "relative";
+        overflow: "hidden";
         borderRadius: number;
         flexDirection: "row";
         alignItems: "center";
@@ -1261,4 +1440,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, CollapsedRail, type CollapsedRailProps, type CollapsedRailRange, type CommandItem, CommandPalette, type CommandPaletteLabels, type CommandPaletteProps, CommandPaletteTrigger, type CommandPaletteTriggerProps, 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, filterCommands, isRouteActive, navStyles, pillNavStyles, resolveContentMaxWidth, resolveRailMode, roleRoutesToNavItems, 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 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 };