@dloizides/ui-nav 1.16.0 → 1.17.0

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # Changelog
 
+## 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
+  desktop inline search to `Sidebar` (`enableInlineSearch`, `search`, controlled
+  `searchQuery` / `onSearchChange`), but all seven portals consume the higher-level
+  `NavShell` (via `sideRail`), which did **not** forward those props — so inline search was
+  unreachable by every real consumer. `NavShellSideRail` now carries the same four fields
+  (`enableInlineSearch?`, `search?: SidebarSearchConfig`, `searchQuery?`, `onSearchChange?`)
+  and threads them onto the `<Sidebar>` it builds. Desktop-vs-mobile resolution is unchanged
+  (inline ≥768, ⌘K palette <768 via `resolveSearchAffordance`).
+  - **Purely additive / backward compatible**: with the fields unset, `NavShell` renders
+    exactly as 1.16.0. No breaking change; no styling touched.
+
 ## 1.16.0
 
 - **Feature (docs-style sidebar rail — hover wash, tinted active pill, rotating chevron).**

package/dist/index.d.mts

@@ -100,6 +100,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 +139,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 +165,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
@@ -728,6 +755,25 @@ interface NavShellSideRail {
     containerStyle?: ViewStyle | ViewStyle[];
     /** Optional collapsed (icon-only) rail config → the intermediate tablet tier. */
     collapsed?: NavShellCollapsedRail;
+    /**
+     * Opt the inner `Sidebar` into its persistent desktop inline-search field.
+     * Requires `search` labels; when omitted the rail renders exactly as before.
+     * The ⌘K palette remains the search affordance on narrow viewports
+     * (see {@link resolveSearchAffordance}). Forwarded to `Sidebar.enableInlineSearch`.
+     */
+    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`. */
+    onSearchChange?: (query: string) => void;
 }
 /**
  * `AppShell` props NavShell forwards straight through. It composes the `header`
@@ -1220,6 +1266,9 @@ declare const navStyles: {
     sidebarSpacer: {
         flex: number;
     };
+    sidebarTriggerSlot: {
+        marginBottom: number;
+    };
     sidebarEmpty: {
         fontSize: number;
         paddingVertical: number;
@@ -1440,4 +1489,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, resolveContentMaxWidth, resolveRailMode, resolveSearchAffordance, roleRoutesToNavItems, searchTokens, useCommandPaletteHotkey, useContentMaxWidth };

package/dist/index.d.ts

@@ -100,6 +100,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 +139,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 +165,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
@@ -728,6 +755,25 @@ interface NavShellSideRail {
     containerStyle?: ViewStyle | ViewStyle[];
     /** Optional collapsed (icon-only) rail config → the intermediate tablet tier. */
     collapsed?: NavShellCollapsedRail;
+    /**
+     * Opt the inner `Sidebar` into its persistent desktop inline-search field.
+     * Requires `search` labels; when omitted the rail renders exactly as before.
+     * The ⌘K palette remains the search affordance on narrow viewports
+     * (see {@link resolveSearchAffordance}). Forwarded to `Sidebar.enableInlineSearch`.
+     */
+    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`. */
+    onSearchChange?: (query: string) => void;
 }
 /**
  * `AppShell` props NavShell forwards straight through. It composes the `header`
@@ -1220,6 +1266,9 @@ declare const navStyles: {
     sidebarSpacer: {
         flex: number;
     };
+    sidebarTriggerSlot: {
+        marginBottom: number;
+    };
     sidebarEmpty: {
         fontSize: number;
         paddingVertical: number;
@@ -1440,4 +1489,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, resolveContentMaxWidth, resolveRailMode, resolveSearchAffordance, roleRoutesToNavItems, searchTokens, useCommandPaletteHotkey, useContentMaxWidth };