@dloizides/ui-nav 1.11.0 → 1.13.0

package/dist/index.d.mts

@@ -898,6 +898,116 @@ interface NavExpandableItemProps {
 }
 declare const NavExpandableItem: ({ item, pathname, onNavigate, navigateHint, expandHint, collapseHint, renderChevron, depth, }: NavExpandableItemProps) => React.ReactElement;
 
+/**
+ * Pure matching logic for the {@link CommandPalette}. Kept framework-free so the
+ * ranking/filtering is unit-testable without rendering: a command matches when
+ * every whitespace-separated token of the query appears (case-insensitively) in
+ * its haystack (label + hint + keywords). Requiring ALL tokens lets an operator
+ * narrow with "pay dash" the way a fuzzy launcher would, without a fuzzy lib.
+ */
+
+/** One actionable destination/command shown in the palette. */
+interface CommandItem {
+    /** Stable key + default testID. */
+    key: string;
+    /** Optional testID override (defaults to `key`). */
+    testID?: string;
+    /** Localized display label (what the operator reads). */
+    label: string;
+    /** Optional localized secondary line (e.g. the module it lives in). */
+    hint?: string;
+    /** Optional extra search terms not shown but matched (synonyms, route words). */
+    keywords?: readonly string[];
+    /** Invoked when the item is chosen (the consumer navigates / runs the action). */
+    onSelect: () => void;
+    /** Optional leading icon slot, same contract as `NavItem.renderIcon`. */
+    renderIcon?: (color: string, size: number) => React.ReactNode;
+}
+/**
+ * Filter `items` to those matching `query`. An empty/whitespace query returns
+ * the list unchanged (the palette opens showing everything). Order is preserved
+ * — the caller supplies items in a meaningful order (nav order).
+ */
+declare function filterCommands(items: readonly CommandItem[], query: string): CommandItem[];
+
+/**
+ * CommandPalette — the shared ⌘K launcher for `@dloizides/ui-nav`. An overlay
+ * (scrim + centred panel) with a search input over a keyboard-navigable list of
+ * {@link CommandItem}s — jump to any nav destination (or run any action) without
+ * hunting the rail. Web-first (RN-web), but degrades safely: when `open` is
+ * false it renders nothing.
+ *
+ * Package discipline (as the rest of ui-nav): NO FM / router / store / icon-set
+ * imports. Labels are pre-localized strings; icons are render slots; every colour
+ * comes from the `@dloizides/ui-feedback` UiProvider theme. The consumer owns the
+ * `open` state (pair with {@link useCommandPaletteHotkey}) and each item's
+ * `onSelect` (navigate / run) — the palette just closes after a choice.
+ */
+
+/** Pre-localized labels for the palette chrome. */
+interface CommandPaletteLabels {
+    /** Search input placeholder. */
+    placeholder: string;
+    /** Accessible name of the scrim (tap to close). */
+    closeLabel: string;
+    /** Accessible hint of the scrim (tap to close). */
+    closeHint: string;
+    /** Shown when the query matches nothing. */
+    emptyText: string;
+    /** Accessible label for the palette dialog landmark. */
+    regionLabel: string;
+}
+interface CommandPaletteProps {
+    /** Whether the palette overlay is shown. */
+    open: boolean;
+    /** The commands to search over, in a meaningful (nav) order. */
+    items: readonly CommandItem[];
+    /** Close the palette (scrim tap / Escape / after a selection). */
+    onClose: () => void;
+    /** Pre-localized chrome labels. */
+    labels: CommandPaletteLabels;
+    /** testID for the panel (defaults to `command-palette`). */
+    testID?: string;
+}
+/** The overlay palette. Renders null when closed. */
+declare const CommandPalette: ({ open, items, onClose, labels, testID }: CommandPaletteProps) => React.ReactElement | null;
+
+/**
+ * CommandPaletteTrigger — the VISIBLE, discoverable affordance that opens the
+ * {@link CommandPalette}. A ⌘K shortcut alone is invisible; a docs-style search
+ * pill (muted placeholder on the left, a keyboard-shortcut badge on the right)
+ * tells operators the palette exists and is one click away. Place it in a shell
+ * header / sidebar; wire `onPress` to the same open handler as the ⌘K hotkey.
+ *
+ * Self-contained on purpose: the shared icon set has no magnifier, so this uses
+ * text + a shortcut badge (the recognizable "Search … ⌘K" pattern) rather than a
+ * render-slot icon — one less thing every consumer must supply. Colours come from
+ * the `@dloizides/ui-feedback` UiProvider theme; the label/shortcut are
+ * pre-localized strings (package discipline: no FM/router imports).
+ */
+
+interface CommandPaletteTriggerProps {
+    /** Placeholder-style label, e.g. "Search". */
+    label: string;
+    /** a11y hint describing what activating it does. */
+    hint: string;
+    /** The shortcut badge text, e.g. "⌘K" (already chosen per-platform by the caller). */
+    shortcut: string;
+    /** Open the palette (same handler as the ⌘K hotkey). */
+    onPress: () => void;
+    /** testID for the trigger. */
+    testID: string;
+}
+/** The visible "Search … ⌘K" pill that opens the command palette. */
+declare const CommandPaletteTrigger: ({ label, hint, shortcut, onPress, testID, }: CommandPaletteTriggerProps) => React.ReactElement;
+
+/**
+ * Call `onOpen` when the operator presses ⌘K (macOS) or Ctrl-K (Windows/Linux),
+ * anywhere in the document. `enabled=false` unbinds (e.g. when the shell has no
+ * palette configured), so the shortcut never fires without a handler behind it.
+ */
+declare function useCommandPaletteHotkey(onOpen: () => void, enabled?: boolean): void;
+
 /**
  * Role-gated nav helpers — build a `NavItem[]` from a user's roles, reusing the
  * existing `resolveAccessibleRoutes` from `@dloizides/auth-web` (the same helper
@@ -1101,6 +1211,8 @@ declare const expandableStyles: {
         flexDirection: "row";
         alignItems: "center";
         paddingVertical: number;
+        borderLeftWidth: number;
+        borderLeftColor: string;
     };
     childItemText: {
         fontSize: number;
@@ -1114,6 +1226,7 @@ declare const expandableStyles: {
     };
     childrenContainer: {
         overflow: "hidden";
+        marginBottom: number;
     };
     header: {
         borderRadius: number;
@@ -1121,11 +1234,21 @@ declare const expandableStyles: {
         alignItems: "center";
         paddingVertical: number;
     };
+    sectionHeader: {
+        marginTop: number;
+    };
     headerText: {
         fontSize: number;
         fontWeight: "600";
         marginLeft: number;
     };
+    sectionHeaderText: {
+        fontSize: number;
+        fontWeight: "700";
+        marginLeft: number;
+        textTransform: "uppercase";
+        letterSpacing: number;
+    };
     iconWrapper: {
         width: number;
         alignItems: "center";
@@ -1138,4 +1261,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, 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 };
+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 };

package/dist/index.d.ts

@@ -898,6 +898,116 @@ interface NavExpandableItemProps {
 }
 declare const NavExpandableItem: ({ item, pathname, onNavigate, navigateHint, expandHint, collapseHint, renderChevron, depth, }: NavExpandableItemProps) => React.ReactElement;
 
+/**
+ * Pure matching logic for the {@link CommandPalette}. Kept framework-free so the
+ * ranking/filtering is unit-testable without rendering: a command matches when
+ * every whitespace-separated token of the query appears (case-insensitively) in
+ * its haystack (label + hint + keywords). Requiring ALL tokens lets an operator
+ * narrow with "pay dash" the way a fuzzy launcher would, without a fuzzy lib.
+ */
+
+/** One actionable destination/command shown in the palette. */
+interface CommandItem {
+    /** Stable key + default testID. */
+    key: string;
+    /** Optional testID override (defaults to `key`). */
+    testID?: string;
+    /** Localized display label (what the operator reads). */
+    label: string;
+    /** Optional localized secondary line (e.g. the module it lives in). */
+    hint?: string;
+    /** Optional extra search terms not shown but matched (synonyms, route words). */
+    keywords?: readonly string[];
+    /** Invoked when the item is chosen (the consumer navigates / runs the action). */
+    onSelect: () => void;
+    /** Optional leading icon slot, same contract as `NavItem.renderIcon`. */
+    renderIcon?: (color: string, size: number) => React.ReactNode;
+}
+/**
+ * Filter `items` to those matching `query`. An empty/whitespace query returns
+ * the list unchanged (the palette opens showing everything). Order is preserved
+ * — the caller supplies items in a meaningful order (nav order).
+ */
+declare function filterCommands(items: readonly CommandItem[], query: string): CommandItem[];
+
+/**
+ * CommandPalette — the shared ⌘K launcher for `@dloizides/ui-nav`. An overlay
+ * (scrim + centred panel) with a search input over a keyboard-navigable list of
+ * {@link CommandItem}s — jump to any nav destination (or run any action) without
+ * hunting the rail. Web-first (RN-web), but degrades safely: when `open` is
+ * false it renders nothing.
+ *
+ * Package discipline (as the rest of ui-nav): NO FM / router / store / icon-set
+ * imports. Labels are pre-localized strings; icons are render slots; every colour
+ * comes from the `@dloizides/ui-feedback` UiProvider theme. The consumer owns the
+ * `open` state (pair with {@link useCommandPaletteHotkey}) and each item's
+ * `onSelect` (navigate / run) — the palette just closes after a choice.
+ */
+
+/** Pre-localized labels for the palette chrome. */
+interface CommandPaletteLabels {
+    /** Search input placeholder. */
+    placeholder: string;
+    /** Accessible name of the scrim (tap to close). */
+    closeLabel: string;
+    /** Accessible hint of the scrim (tap to close). */
+    closeHint: string;
+    /** Shown when the query matches nothing. */
+    emptyText: string;
+    /** Accessible label for the palette dialog landmark. */
+    regionLabel: string;
+}
+interface CommandPaletteProps {
+    /** Whether the palette overlay is shown. */
+    open: boolean;
+    /** The commands to search over, in a meaningful (nav) order. */
+    items: readonly CommandItem[];
+    /** Close the palette (scrim tap / Escape / after a selection). */
+    onClose: () => void;
+    /** Pre-localized chrome labels. */
+    labels: CommandPaletteLabels;
+    /** testID for the panel (defaults to `command-palette`). */
+    testID?: string;
+}
+/** The overlay palette. Renders null when closed. */
+declare const CommandPalette: ({ open, items, onClose, labels, testID }: CommandPaletteProps) => React.ReactElement | null;
+
+/**
+ * CommandPaletteTrigger — the VISIBLE, discoverable affordance that opens the
+ * {@link CommandPalette}. A ⌘K shortcut alone is invisible; a docs-style search
+ * pill (muted placeholder on the left, a keyboard-shortcut badge on the right)
+ * tells operators the palette exists and is one click away. Place it in a shell
+ * header / sidebar; wire `onPress` to the same open handler as the ⌘K hotkey.
+ *
+ * Self-contained on purpose: the shared icon set has no magnifier, so this uses
+ * text + a shortcut badge (the recognizable "Search … ⌘K" pattern) rather than a
+ * render-slot icon — one less thing every consumer must supply. Colours come from
+ * the `@dloizides/ui-feedback` UiProvider theme; the label/shortcut are
+ * pre-localized strings (package discipline: no FM/router imports).
+ */
+
+interface CommandPaletteTriggerProps {
+    /** Placeholder-style label, e.g. "Search". */
+    label: string;
+    /** a11y hint describing what activating it does. */
+    hint: string;
+    /** The shortcut badge text, e.g. "⌘K" (already chosen per-platform by the caller). */
+    shortcut: string;
+    /** Open the palette (same handler as the ⌘K hotkey). */
+    onPress: () => void;
+    /** testID for the trigger. */
+    testID: string;
+}
+/** The visible "Search … ⌘K" pill that opens the command palette. */
+declare const CommandPaletteTrigger: ({ label, hint, shortcut, onPress, testID, }: CommandPaletteTriggerProps) => React.ReactElement;
+
+/**
+ * Call `onOpen` when the operator presses ⌘K (macOS) or Ctrl-K (Windows/Linux),
+ * anywhere in the document. `enabled=false` unbinds (e.g. when the shell has no
+ * palette configured), so the shortcut never fires without a handler behind it.
+ */
+declare function useCommandPaletteHotkey(onOpen: () => void, enabled?: boolean): void;
+
 /**
  * Role-gated nav helpers — build a `NavItem[]` from a user's roles, reusing the
  * existing `resolveAccessibleRoutes` from `@dloizides/auth-web` (the same helper
@@ -1101,6 +1211,8 @@ declare const expandableStyles: {
         flexDirection: "row";
         alignItems: "center";
         paddingVertical: number;
+        borderLeftWidth: number;
+        borderLeftColor: string;
     };
     childItemText: {
         fontSize: number;
@@ -1114,6 +1226,7 @@ declare const expandableStyles: {
     };
     childrenContainer: {
         overflow: "hidden";
+        marginBottom: number;
     };
     header: {
         borderRadius: number;
@@ -1121,11 +1234,21 @@ declare const expandableStyles: {
         alignItems: "center";
         paddingVertical: number;
     };
+    sectionHeader: {
+        marginTop: number;
+    };
     headerText: {
         fontSize: number;
         fontWeight: "600";
         marginLeft: number;
     };
+    sectionHeaderText: {
+        fontSize: number;
+        fontWeight: "700";
+        marginLeft: number;
+        textTransform: "uppercase";
+        letterSpacing: number;
+    };
     iconWrapper: {
         width: number;
         alignItems: "center";
@@ -1138,4 +1261,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, 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 };
+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 };