@keenmate/web-multiselect 2.0.0-rc06 → 2.0.0-rc08

package/dist/index.d.ts

@@ -4,6 +4,7 @@ import { InputDef } from '@keenmate/web-components-core';
 import { Logger } from '@keenmate/web-components-core';
 import { LogLevelDesc } from '@keenmate/web-components-core';
 import { Placement } from '@keenmate/web-components-core/positioning';
+import { PresentationContext } from '@keenmate/web-components-core';
 
 /**
  * Action button configuration for dropdown actions (Select All, Clear All, custom actions)
@@ -59,7 +60,7 @@ declare type ActionsPosition = 'top' | 'bottom';
 /**
  * Context provided to renderBadgeContentCallback
  */
-declare interface BadgeContentRenderContext {
+declare interface BadgeContentRenderContext extends PresentationContext {
     /** Current badges display mode */
     displayMode: BadgesDisplayMode;
     /** Whether the badge is being rendered in the selected items popover */
@@ -387,6 +388,17 @@ declare interface MultiSelectConfig<T = any> {
      * - `navigate` — keep all options visible and jump focus to matches
      */
     searchMode?: SearchMode;
+    /**
+     * Show a clickable mode toggle in the phone fullscreen overlay's search header that
+     * flips `searchMode` between `filter` and `navigate` live (no reopen). Default `false`.
+     *
+     * The overlay has room for the affordance and touch users can't reach the desktop
+     * `Ctrl`+`Arrow` match-stepping, so this exposes both modes on the device where it
+     * matters most. The toggle sits at the leading edge of the search field; its icon
+     * reflects the current mode (magnifier = navigate, funnel = filter). No effect in the
+     * floating presentation or when search is disabled/hidden.
+     */
+    isSearchModeToggleShown?: boolean;
     /**
      * Layout mode for the action buttons. Default: `nowrap`.
      *
@@ -463,6 +475,15 @@ declare interface MultiSelectConfig<T = any> {
     searchCallback?: ((searchTerm: string, signal?: AbortSignal) => Promise<T[]>) | null;
     /** Callback to add a new option when isAddNewAllowed is true */
     addNewCallback?: ((value: string) => T | Promise<T>) | null;
+    /**
+     * Intercept keyboard input before the built-in handling. Runs on every keydown (open or
+     * closed) with a {@link MultiSelectKeydownContext} carrying the event, current state, and a
+     * {@link MultiSelectKeyboardController}. Return `true` to mark the key fully handled — the
+     * component then runs none of its own key logic (you own `preventDefault`); return
+     * `false`/`undefined` to fall through to the defaults. Use it to remap keys (Vim `j`/`k`),
+     * add shortcuts (Ctrl+A → select all), or suppress a default. Property-only.
+     */
+    keydownCallback?: ((context: MultiSelectKeydownContext<T>) => boolean | void) | null;
     /** Event handler: an option was selected (fire-and-forget; return value ignored). Mirrors the bubbling `select` CustomEvent on the element. */
     onSelect?: ((option: T) => void) | null;
     /** Event handler: an option was deselected (fire-and-forget). Mirrors the bubbling `deselect` CustomEvent on the element. */
@@ -602,6 +623,71 @@ declare type MultiSelectEvents = {
     change: MultiSelectEventDetail;
 };
 
+/**
+ * Imperative facade handed to `keydownCallback` so a consumer can drive the picker without
+ * reaching into internals. Every method mirrors a built-in keyboard action.
+ */
+declare interface MultiSelectKeyboardController<T = any> {
+    /** Move focus to the next / previous option. */
+    focusNext(): void;
+    focusPrevious(): void;
+    /** Move focus to the first / last option. */
+    focusFirst(): void;
+    focusLast(): void;
+    /** Move focus by a page (10 rows). */
+    focusPageUp(): void;
+    focusPageDown(): void;
+    /** Navigate-mode only: jump focus to the next / previous match. */
+    focusNextMatch(): void;
+    focusPreviousMatch(): void;
+    /** Focus a specific index in the filtered list (ignored if out of range). */
+    focusIndex(index: number): void;
+    /** Toggle the currently focused option (no-op if nothing is focused). */
+    toggleFocused(): void;
+    /** Toggle a specific option by its value (select ⇄ deselect). */
+    toggleValue(value: string | number): void;
+    /** Select a specific option by its value (no-op if already selected). */
+    selectValue(value: string | number): void;
+    /** Deselect a specific option by its value (no-op if not selected). */
+    deselectValue(value: string | number): void;
+    /** Open / close the dropdown. */
+    open(): void;
+    close(): void;
+    /** Set the search box text (runs the search). */
+    setSearch(term: string): void;
+    /** Clear the search box and reset the visible list. */
+    clearSearch(): void;
+}
+
+/**
+ * Context passed to `keydownCallback`, which runs before all built-in keyboard handling.
+ * Return `true` to mark the key fully handled (the component then runs none of its own
+ * key logic — you own `preventDefault`); return `false`/`undefined` to fall through to the
+ * defaults. Mirrors the veto-hook shape used across KM components.
+ */
+declare interface MultiSelectKeydownContext<T = any> {
+    /** The raw keyboard event — call `preventDefault()` yourself if you handle the key. */
+    event: KeyboardEvent;
+    /** `event.key`, for convenience. */
+    key: string;
+    /** Whether the dropdown is currently open. */
+    isOpen: boolean;
+    /** How the open panel is presented (`floating` / `fullscreen`). */
+    presentation: 'floating' | 'fullscreen';
+    /** The current search term. */
+    searchTerm: string;
+    /** Index of the focused option in the filtered list (`-1` when nothing is focused). */
+    focusedIndex: number;
+    /** The focused option object, or `null`. */
+    focusedOption: T | null;
+    /** The options currently visible (after filtering). */
+    filteredOptions: ReadonlyArray<T>;
+    /** The currently selected values. */
+    selectedValues: ReadonlyArray<string>;
+    /** Imperative actions mirroring the built-in keyboard behavior. */
+    controller: MultiSelectKeyboardController<T>;
+}
+
 /**
  * Legacy interface for backward reference
  * Note: New code should use generic types with member/callback properties
@@ -647,9 +733,15 @@ export declare interface MultiSelectOptions extends MultiSelectConfig<MultiSelec
 declare type NodeId = string | number;
 
 /**
- * Context provided to renderOptionContentCallback
+ * Context provided to renderOptionContentCallback.
+ *
+ * Extends the shared {@link PresentationContext} from `@keenmate/web-components-core`, so it
+ * also carries `presentation` (`'floating' | 'modal' | 'fullscreen'` — this component only ever
+ * emits `floating`/`fullscreen`), `isFullscreen`, and `isModal`. Branch on `isFullscreen` to
+ * render leaner content in the phone overlay. Reactive: swapping presentation re-renders and
+ * re-invokes the callback with the new value.
  */
-declare interface OptionContentRenderContext {
+declare interface OptionContentRenderContext extends PresentationContext {
     /** Index of the option in the filtered list */
     index: number;
     /** Whether the option is currently selected */
@@ -761,6 +853,7 @@ export declare class WebMultiSelect<T = any> {
     private cascadeCheckedAtoms;
     private hiddenInputs;
     private focusedIndex;
+    private keyboardController;
     private matchingIndices;
     private searchTerm;
     private isLoading;
@@ -778,6 +871,7 @@ export declare class WebMultiSelect<T = any> {
     private fullscreenHeader;
     private fullscreenSearchInput;
     private fullscreenSearchClear;
+    private fullscreenModeToggle;
     private fullscreenNav;
     private fullscreenNavCount;
     private fullscreenNavPrev;
@@ -999,6 +1093,16 @@ export declare class WebMultiSelect<T = any> {
      * search is unusable → the search placeholder.
      */
     private getPlaceholderText;
+    /**
+     * The search field placeholder. An explicit `searchPlaceholder` always wins and stays
+     * fixed. Otherwise the default is "Search..." — except when the in-overlay mode toggle
+     * is enabled (`isSearchModeToggleShown`), where it becomes mode-aware so the field labels
+     * the current behavior: "Search…" in navigate mode, "Filter…" in filter mode. Refreshed
+     * on a live mode switch (see setSearchModeLive → refreshSearchPlaceholder).
+     */
+    private getSearchPlaceholder;
+    /** Re-apply the (possibly mode-aware) placeholder to the live inputs after a mode switch. */
+    private refreshSearchPlaceholder;
     private renderBadges;
     private attachEvents;
     private handleSearch;
@@ -1040,6 +1144,12 @@ export declare class WebMultiSelect<T = any> {
     private focusPageDown;
     private focusNextMatch;
     private focusPreviousMatch;
+    /** Lazily build (and cache) the imperative facade passed to `keydownCallback`. Bound to the
+     *  same private actions the built-in key handling uses, so consumer shortcuts behave identically. */
+    private getKeyboardController;
+    /** Clear the search box (both the main input and the fullscreen search) and reset the visible
+     *  list. Shared by Escape and the keyboard controller. */
+    private clearSearch;
     private scrollToFocused;
     private toggleOption;
     /**
@@ -1199,6 +1309,26 @@ export declare class WebMultiSelect<T = any> {
      * header survives re-renders.
      */
     private buildFullscreenHeader;
+    /** Build the navigate-mode match navigator (count + prev/next) and append it to the
+     *  fullscreen header, once. No-op if already built or the header isn't present. The
+     *  nav wraps onto its own full-width row under the search box (header is flex-wrap;
+     *  the nav takes 100% basis). */
+    private ensureFullscreenNav;
+    /** Remove the match navigator (switching to filter mode, which has no jump UI). */
+    private removeFullscreenNav;
+    /** Flip searchMode filter<->navigate from the in-overlay toggle. */
+    private toggleSearchModeLive;
+    /**
+     * Switch searchMode in place — the overlay's toggle path. The `search-mode` attribute
+     * is reinit-on-change (it rebuilds and closes the overlay); this instead mutates the
+     * live config, adds/removes the match navigator to match, and re-projects the current
+     * term under the new mode (filter narrows the list / navigate keeps all + highlights),
+     * all without tearing the open sheet down. Focus stays on the search field.
+     */
+    private setSearchModeLive;
+    /** Sync the mode toggle's icon (via data-mode) and labels with the current searchMode.
+     *  No-op when the toggle isn't built (opt-out, floating panel, or search hidden). */
+    private updateFullscreenModeToggle;
     /**
      * Sync the fullscreen match navigator (navigate mode only) with the current search
      * state: hide it until there's a term, then show "N of M" while a match is focused