@keenmate/web-multiselect 2.2.0-rc02 → 2.2.0

package/README.md

@@ -21,22 +21,15 @@ Reads `--base-*` variables from the page if [`@keenmate/theme-designer`](https:/
 - Custom rendering callbacks for options, badges, and group headers.
 - Form integration via standard hidden inputs (FormData-compatible).
 
-## What's New in v2.2.0-rc02
-
-- **`custom-styles` attribute — style shadow-DOM internals with zero JavaScript** — The existing `customStylesCallback` was the only way to inject custom CSS into the component's shadow root, which locked out consumers who can't reach into script: static HTML pages, server-rendered markup, no-build sites. The new `custom-styles` attribute takes raw CSS as a string (`<web-multiselect custom-styles=".ms__badge { font-weight: bold; }">`) and injects it verbatim — selectors and all — into the same replaceable style slot at the top of the shadow root that the callback uses, so you can restyle badges, options, and your own custom-rendered content declaratively. It's reactive (changing or removing the attribute re-applies or clears the slot), mirrored by a `customStyles` property, and flows through the same dev-mode `--ms-*` lint. When both are set, `customStylesCallback` still wins — the attribute is the static fallback. Demonstrated no-JS on the Custom Rendering page (CR09) and the Basic Usage declarative card.
-
-- **Single-select no longer holds a stale multi-selection when seeded with several values** — `parseInitialSelection()` used to add every seeded value to the selection unconditionally, so a `multiple="false"` picker could hold — and highlight — multiple rows at once. It surfaced both from a declarative `initial-values="a,b,c"` on a single-select and, more visibly, from flipping `multiple` from `true` to `false` at runtime while items were selected: the reinit reseeds the live selection into the fresh single-select and left the extra rows highlighted. The picker now trims the seed to the first value when it isn't in multiple mode, so exactly one row stays selected.
-
-- **Async-search dropdown no longer runs off the bottom of the viewport** — An async `searchCallback` that seeds no options anchors its panel while it's still empty or showing the loader — short enough to fit below the input, so with the default `lock-placement` it froze its placement to `bottom`. When results arrived the panel grew to full height but stayed pinned below the input, overflowing the bottom edge instead of flipping up into the free space, because `renderDropdown()` rewrote the list without re-anchoring. `performAsyncSearch()` now calls a new `repositionDropdown()` after results render, tearing down and recreating the Floating-UI anchor so the flip-on-first-compute re-evaluates against the panel's real height, then re-freezes. Scoped to the async path only — locally filtered dropdowns open already populated and are unaffected.
-
-## What's New in v2.2.0-rc01
-
-- **Tree cascade is now the default — check a branch, check its subtree** — In a multi-select tree, `checkbox-mode` now defaults to `cascade` (previously `independent`), so ticking a branch selects its whole subtree and branches render a tristate (checked / indeterminate / unchecked) box — what most tree-select UIs do. The emitted selection follows `cascade-select-policy` (default `rolled-up`: a fully-checked subtree collapses to its root value). This is a behavior change for existing tree consumers — set `checkbox-mode="independent"` to keep the old per-node toggling. Flat and single-select lists are unaffected, since there's no subtree to cascade into.
-- **Per-group select-all in flat grouped lists — `group-select-mode="cascade"`** — A new attribute puts a tristate checkbox on each group header in a flat, multi-select, grouped list; clicking it checks or unchecks all of that group's currently-visible members. The group name itself is never a selected value — `getValue()`, badges, and form output carry member values only — a partially-selected group reads indeterminate, and a header toggle fires a single `change`. Disabled members are excluded from the select-all. Default `none` leaves headers inert, as before.
-- **Per-group selected counts + one shared count formatter** — Every group header now shows a count of that group's selected members, rendered as the same small chip as the in-input `[N]` counter (not a new badge style). A new `getCountLabelCallback((selected, total) => string)` formats both the in-input counter and the group chip together so they always read the same way — default `[3]`, or return `` `${s}/${t}` `` for an "x / y of total" style, where `total` is the whole option list for the counter and the group's member count for a header.
-- **Order the selected items — `selected-order`** — Control the sequence chosen items appear in across badges, partial "+N more", and the selected-items popover: `as-selected` (default), `label-asc` / `label-desc`, `member` (by a `selected-order-member` property or `getSelectedOrderCallback`), or `custom` (a comparator). It's display-only — `getValue()`, form output, and `getSelected()` keep insertion order — and because the ordering runs in one shared place, the partial "+N more" split and its remove button always act on the items sorted *after* the visible slice.
-- **Every render callback now receives a context** — `renderGroupLabelContentCallback` gains a second `GroupLabelRenderContext` argument (the group's members and selection, e.g. `selectedCount`), and `renderSelectedItemContentCallback` / `renderSelectedContentCallback` now also receive a context carrying the presentation (`isFullscreen` / `isModal`) — matching the option and badge callbacks. Everything is additive, so existing one-argument callbacks keep working; branch on `isFullscreen` to render leaner content in the phone overlay.
-- **Fixes — selection preservation, hidden search field, "+N more" ✕** — Changing a cosmetic attribute (`badges-display-mode` / `badges-position`) no longer wipes the current selection (it's applied in place, and genuine rebuilds now preserve the runtime selection); `search-input-mode="hidden"` no longer collapses the input row, so the toggle stays at the trailing edge; and the "+N more" badge's ✕ now removes exactly the hidden items instead of silently opening the popover.
+## What's New in v2.2.0
+
+- **Standardized callback context — one typed contract for action-button and display callbacks** — The action-button callbacks used to receive the untyped picker instance, and the display `get*` callbacks (badge display/class/tooltip, remove-button tooltip, selected-item class, option tooltip) got only the item. They now receive a typed second argument: a new `ActionContext<T>` (extends `PresentationContext`, carrying component state, the host element, and a `MultiSelectController<T>` imperative facade) for `getIsVisible`/`getIsDisabled`/`getText`/`getClass`/`getTooltip`/`onClick`, and the same `BadgeContentRenderContext` / `OptionContentRenderContext` their `render*` twin already gets for the display siblings. Everything is additive — existing one-argument callbacks keep working — and `ActionContext`, `MultiSelectController`, `MultiSelectKeyboardController`, and `ActionButton` are now exported from the package entry.
+- **`custom-styles` attribute — style shadow-DOM internals with zero JavaScript** — The only way to inject custom CSS into the shadow root used to be `customStylesCallback`, which locked out static HTML, server-rendered markup, and no-build sites. The new `custom-styles` attribute takes raw CSS as a string and injects it verbatim into the same replaceable style slot the callback uses, so you can restyle badges, options, and your own custom-rendered content declaratively. It's reactive, mirrored by a `customStyles` property, and flows through the same dev-mode `--ms-*` lint; when both are set, `customStylesCallback` still wins.
+- **Tree cascade by default, plus per-group select-all** — In a multi-select tree, `checkbox-mode` now defaults to `cascade`: ticking a branch selects its whole subtree, branches render tristate, and the emitted value follows `cascade-select-policy` (default `rolled-up`). This is a behavior change for existing tree consumers — set `checkbox-mode="independent"` to keep per-node toggling. Flat grouped lists get the parallel `group-select-mode="cascade"`, a tristate select-all checkbox on each group header (member values only — the group name is never a value).
+- **Per-group selected counts + one shared count formatter** — Every group header now shows a count of that group's selected members, rendered as the same small chip as the in-input `[N]` counter. A new `getCountLabelCallback((selected, total) => string)` formats both places together so they always read the same way — default `[3]`, or return `` `${s}/${t}` `` for an x-of-total style.
+- **Order the selected items — `selected-order`** — Control the sequence chosen items appear in across badges, the partial "+N more" split, and the popover: `as-selected` (default), `label-asc`/`label-desc`, `member` (via `selected-order-member` or `getSelectedOrderCallback`), or `custom` (a comparator). Display-only — `getValue()`, form output, and `getSelected()` keep insertion order.
+- **Every render callback now carries the presentation context** — `renderSelectedItemContentCallback`, `renderSelectedContentCallback`, and `renderGroupLabelContentCallback` now receive a second context argument (matching the option and badge callbacks), so any custom renderer can branch on `isFullscreen`/`isModal` to render leaner content in the phone overlay. The context render-type interfaces are exported from the package entry, and it's additive — one-argument callbacks are unaffected.
+- **Fixes — selection & layout robustness** — Single-select no longer keeps a stale multi-selection when seeded with several values; an async `searchCallback` dropdown no longer overflows the viewport when results grow after it opens near the bottom; changing a cosmetic attribute (`badges-display-mode`/`badges-position`) no longer wipes the selection; `search-input-mode="hidden"` no longer collapses the input row; and the "+N more" badge's ✕ now removes the hidden items instead of silently opening the popover.
 
 ## Demos & docs
 

package/custom-elements.json

@@ -925,6 +925,13 @@
                   "type": {
                     "text": "T"
                   }
+                },
+                {
+                  "name": "context",
+                  "optional": true,
+                  "type": {
+                    "text": "BadgeContentRenderContext"
+                  }
                 }
               ],
               "description": "Badge display falls back to the regular display value rather than '[N/A]', so consumers can override badge\ntext independently. Doesn't fit the extractField shape (no tuple/member layer of its own)."
@@ -2091,6 +2098,36 @@
               },
               "description": "Lazily build (and cache) the imperative facade passed to `keydownCallback`. Bound to the\nsame private actions the built-in key handling uses, so consumer shortcuts behave identically."
             },
+            {
+              "kind": "method",
+              "name": "hostEl",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "HTMLElement"
+                }
+              },
+              "description": "The host custom element — `this.element` is the internal `.ms` mount (inside the shadow\nroot), so the host is its root node's `host` when shadowed, else the mount itself. Used as\nthe ActionContext escape hatch (and where a wrapper hangs a server bridge)."
+            },
+            {
+              "kind": "method",
+              "name": "buildActionContext",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "ActionContext<T>"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "button",
+                  "type": {
+                    "text": "ActionButton<T>"
+                  }
+                }
+              ],
+              "description": "Build the ActionContext passed (as the additive 2nd arg) to every action-button\ncallback and the `onClick` event: a snapshot of live state plus the shared controller."
+            },
             {
               "kind": "method",
               "name": "clearSearch",
@@ -3032,6 +3069,25 @@
               ],
               "description": "Normalize a class callback result (`string | string[] | null`) to a single\nspace-joined string with falsy entries dropped — e.g. `['a', '', 'b'] → \"a b\"`,\n`null → \"\"`. Callers add their own leading space / base class as needed."
             },
+            {
+              "kind": "method",
+              "name": "badgeRenderContext",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "BadgeContentRenderContext"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "isInPopover",
+                  "type": {
+                    "text": "boolean"
+                  }
+                }
+              ],
+              "description": "Build the BadgeContentRenderContext handed to the sibling `get*` callbacks\n(badge display / class / tooltip), so they see the same context the `render*` badge\ncallbacks get: `displayMode`, `isInPopover`, plus the shared presentation fields."
+            },
             {
               "kind": "method",
               "name": "renderBadgeHTML",
@@ -3242,6 +3298,13 @@
                   "type": {
                     "text": "T"
                   }
+                },
+                {
+                  "name": "context",
+                  "optional": true,
+                  "type": {
+                    "text": "BadgeContentRenderContext"
+                  }
                 }
               ],
               "description": "Build the badge-text tooltip content (callback overrides; default = displayValue + optional subtitle on next line)."
@@ -3268,6 +3331,13 @@
                   "type": {
                     "text": "T"
                   }
+                },
+                {
+                  "name": "context",
+                  "optional": true,
+                  "type": {
+                    "text": "BadgeContentRenderContext"
+                  }
                 }
               ],
               "description": "Build the remove-button tooltip text (callback > format string with {0} > \"Remove {name}\")."
@@ -3306,6 +3376,13 @@
                   "type": {
                     "text": "T"
                   }
+                },
+                {
+                  "name": "context",
+                  "optional": true,
+                  "type": {
+                    "text": "OptionContentRenderContext"
+                  }
                 }
               ],
               "description": "Build the option tooltip content (callback overrides; default = displayValue + optional subtitle on next line)."

package/dist/index.d.ts

@@ -22,7 +22,7 @@ import { TABLET_MIN_SHORT_SIDE } from '@keenmate/web-components-core';
  * Action button configuration for dropdown actions (Select All, Clear All, custom actions)
  * @template T The type of data items
  */
-declare interface ActionButton<T = any> {
+export declare interface ActionButton<T = any> {
     /** Action identifier ('select-all', 'clear-all', or 'custom' for custom actions) */
     action: 'select-all' | 'clear-all' | 'custom';
     /** Button text label */
@@ -42,18 +42,53 @@ declare interface ActionButton<T = any> {
     isVisible?: boolean;
     /** Static disabled state - set to true to disable button */
     isDisabled?: boolean;
-    /** Custom click handler (required for 'custom' action) */
-    onClick?: (multiselect: any) => void | Promise<void>;
-    /** Dynamic visibility callback - return false to hide button (takes priority over isVisible) */
-    getIsVisibleCallback?: (multiselect: any) => boolean;
-    /** Dynamic disabled state callback - return true to disable button (takes priority over isDisabled) */
-    getIsDisabledCallback?: (multiselect: any) => boolean;
-    /** Dynamic text callback - return button text (takes priority over text) */
-    getTextCallback?: (multiselect: any) => string;
-    /** Dynamic CSS class callback - return class name(s) (takes priority over cssClass) */
-    getClassCallback?: (multiselect: any) => string | string[];
-    /** Dynamic tooltip callback - return tooltip text (takes priority over tooltip) */
-    getTooltipCallback?: (multiselect: any) => string;
+    /**
+     * Custom click handler (required for 'custom' action). The 1st arg is the live picker
+     * instance (as before); the additive 2nd arg is a typed {@link ActionContext} (state +
+     * controller). One-argument handlers keep working.
+     */
+    onClick?: (multiselect: any, context?: ActionContext<T>) => void | Promise<void>;
+    /** Dynamic visibility callback - return false to hide button (takes priority over isVisible). Additive 2nd arg: {@link ActionContext}. */
+    getIsVisibleCallback?: (multiselect: any, context?: ActionContext<T>) => boolean;
+    /** Dynamic disabled state callback - return true to disable button (takes priority over isDisabled). Additive 2nd arg: {@link ActionContext}. */
+    getIsDisabledCallback?: (multiselect: any, context?: ActionContext<T>) => boolean;
+    /** Dynamic text callback - return button text (takes priority over text). Additive 2nd arg: {@link ActionContext}. */
+    getTextCallback?: (multiselect: any, context?: ActionContext<T>) => string;
+    /** Dynamic CSS class callback - return class name(s) (takes priority over cssClass). Additive 2nd arg: {@link ActionContext}. */
+    getClassCallback?: (multiselect: any, context?: ActionContext<T>) => string | string[];
+    /** Dynamic tooltip callback - return tooltip text (takes priority over tooltip). Additive 2nd arg: {@link ActionContext}. */
+    getTooltipCallback?: (multiselect: any, context?: ActionContext<T>) => string;
+}
+
+/**
+ * Context handed (as the additive 2nd argument) to the action-button callbacks —
+ * {@link ActionButton.getTextCallback} / `getIsVisibleCallback` / `getIsDisabledCallback` /
+ * `getClassCallback` / `getTooltipCallback` — and to the `onClick` event. A typed snapshot of
+ * live state plus a {@link MultiSelectController} facade, replacing reliance on the untyped picker
+ * instance passed as the first argument. Extends {@link PresentationContext}, so a callback can
+ * branch on how the panel is presented (floating vs fullscreen), consistent with the render callbacks.
+ */
+export declare interface ActionContext<T = any> extends PresentationContext {
+    /** The action button config entry this callback belongs to. */
+    button: ActionButton<T>;
+    /** Currently selected scalar values. */
+    selectedValues: (string | number)[];
+    /** Currently selected option objects, in selection order. */
+    selectedOptions: T[];
+    /** All available options (post assignment). */
+    options: ReadonlyArray<T>;
+    /** `selectedOptions.length` — convenience. */
+    selectedCount: number;
+    /** `options.length` — convenience (the Select-All denominator). */
+    optionCount: number;
+    /** Whether the dropdown is currently open. */
+    isOpen: boolean;
+    /** The current search term. */
+    searchTerm: string;
+    /** Imperative facade — drive the picker (selection / dropdown / search / messages). */
+    controller: MultiSelectController<T>;
+    /** Escape hatch: the host custom element, for anything not on the controller. */
+    element: HTMLElement & Record<string, any>;
 }
 
 /** Horizontal arrangement of buttons within an action row. `stretch` = full-width (default). */
@@ -218,8 +253,15 @@ declare interface MultiSelectConfig<T = any> {
     displayValueMember?: string;
     /** Callback to extract display value from item */
     getDisplayValueCallback?: (item: T) => string;
-    /** Callback to customize badge display text (defaults to display value if not provided) */
-    getBadgeDisplayCallback?: (item: T) => string;
+    /**
+     * Callback to customize badge display text (defaults to display value if not provided).
+     * The second argument is additive: when the value is computed while rendering a specific
+     * badge/popover item it receives that item's {@link BadgeContentRenderContext} (`displayMode`,
+     * `isInPopover`, and the shared presentation fields); it is **absent** when the value is needed
+     * outside a render (e.g. selected-order sorting, the counter chip's title), so one-argument
+     * callbacks keep working. Treat `context` as optional.
+     */
+    getBadgeDisplayCallback?: (item: T, context?: BadgeContentRenderContext) => string;
     /**
      * Order of the CURRENTLY-SELECTED items *where they are displayed* — badges, partial mode
      * (i.e. which items sit behind the "+N more" badge), and the selected-items popover. This is a
@@ -248,8 +290,13 @@ declare interface MultiSelectConfig<T = any> {
     fullTitleMember?: string;
     /** Callback to extract the full title from an item (takes precedence over `fullTitleMember`). */
     getFullTitleCallback?: (item: T) => string;
-    /** Callback to add custom CSS classes to badges - return string or array of class names */
-    getBadgeClassCallback?: (item: T) => string | string[];
+    /**
+     * Callback to add custom CSS classes to badges - return string or array of class names.
+     * Additive 2nd arg: receives the badge's {@link BadgeContentRenderContext} when invoked during
+     * a badge render (the same context {@link renderBadgeContentCallback} gets), so classes can react
+     * to `displayMode` / `isInPopover` / presentation. Optional — one-argument callbacks keep working.
+     */
+    getBadgeClassCallback?: (item: T, context?: BadgeContentRenderContext) => string | string[];
     /** Callback to inject custom CSS into Shadow DOM - return CSS string for styling custom classes */
     customStylesCallback?: () => string;
     /**
@@ -369,8 +416,13 @@ declare interface MultiSelectConfig<T = any> {
      * presentation fields. The second argument is additive; one-argument callbacks keep working.
      */
     renderSelectedItemContentCallback?: (item: T, context: BadgeContentRenderContext) => string | HTMLElement;
-    /** Callback to add custom CSS classes to selected items in popover - return string or array of class names */
-    getSelectedItemClassCallback?: (item: T) => string | string[];
+    /**
+     * Callback to add custom CSS classes to selected items in popover - return string or array of
+     * class names. Additive 2nd arg: receives the {@link BadgeContentRenderContext} for the popover
+     * item (`isInPopover` is `true`) — the same context {@link renderSelectedItemContentCallback}
+     * gets. Optional — one-argument callbacks keep working.
+     */
+    getSelectedItemClassCallback?: (item: T, context?: BadgeContentRenderContext) => string | string[];
     /**
      * Custom renderer for the selected item display in single-select mode — return plain text (it
      * becomes the input value). Receives a {@link SelectedContentRenderContext} (2nd arg) carrying
@@ -694,10 +746,17 @@ declare interface MultiSelectConfig<T = any> {
     getCountLabelCallback?: ((selected: number, total: number) => string) | null;
     /** Enable tooltips on selected item badges (internal: isBadgeTooltipsEnabled) */
     isBadgeTooltipsEnabled?: boolean;
-    /** Callback to generate custom tooltip content for a badge */
-    getBadgeTooltipCallback?: ((item: T) => string | HTMLElement) | null;
-    /** Callback to generate custom tooltip text for a remove button */
-    getRemoveButtonTooltipCallback?: ((item: T) => string) | null;
+    /**
+     * Callback to generate custom tooltip content for a badge. Additive 2nd arg: receives the
+     * badge's {@link BadgeContentRenderContext} (`displayMode` / `isInPopover` / presentation), the
+     * same context {@link renderBadgeContentCallback} gets. Optional — one-argument callbacks keep working.
+     */
+    getBadgeTooltipCallback?: ((item: T, context?: BadgeContentRenderContext) => string | HTMLElement) | null;
+    /**
+     * Callback to generate custom tooltip text for a remove button. Additive 2nd arg: the badge's
+     * {@link BadgeContentRenderContext}. Optional — one-argument callbacks keep working.
+     */
+    getRemoveButtonTooltipCallback?: ((item: T, context?: BadgeContentRenderContext) => string) | null;
     /** Format string for remove button tooltip text. Use {0} as placeholder for item name. Default: "Remove {0}" */
     removeButtonTooltipText?: string;
     /**
@@ -713,8 +772,14 @@ declare interface MultiSelectConfig<T = any> {
     badgeTooltipOffset?: number;
     /** Enable tooltips on dropdown options (internal: isOptionTooltipsEnabled) */
     isOptionTooltipsEnabled?: boolean;
-    /** Callback to generate custom tooltip content for a dropdown option. Default: display value, plus subtitle on the next line when present. */
-    getOptionTooltipCallback?: ((item: T) => string | HTMLElement) | null;
+    /**
+     * Callback to generate custom tooltip content for a dropdown option. Default: display value, plus
+     * subtitle on the next line when present. Additive 2nd arg: receives the row's
+     * {@link OptionContentRenderContext} (`index`, `isSelected`, `isFocused`, `isMatched`,
+     * `isDisabled`, presentation), the same context {@link renderOptionContentCallback} gets, so an
+     * option tooltip can match how the row itself was rendered. Optional — one-argument callbacks keep working.
+     */
+    getOptionTooltipCallback?: ((item: T, context?: OptionContentRenderContext) => string | HTMLElement) | null;
     /**
      * Option tooltip placement (Floating UI `Placement`). Default `top-start`
      * (anchored to the row's start edge, so it doesn't center on a full-width row).
@@ -736,6 +801,46 @@ declare interface MultiSelectConfig<T = any> {
     hostElement?: HTMLElement;
 }
 
+/**
+ * Imperative facade for driving a live picker from a callback without reaching into internals.
+ * Shared base of the callback controllers: {@link MultiSelectKeyboardController} (handed to
+ * `keydownCallback`) extends it with focus-navigation, and {@link ActionContext} exposes it to
+ * the action-button callbacks. Every method mirrors a public element method.
+ */
+export declare interface MultiSelectController<T = any> {
+    /** The selected option objects, in selection order (mirrors `el.getSelected()`). */
+    getSelected(): T[];
+    /** The selection as returned to forms/consumers — scalar or array per `multiple` (mirrors `el.getValue()`). */
+    getValue(): string | number | (string | number)[] | null;
+    /** All available options (post assignment, pre-filter). */
+    getOptions(): ReadonlyArray<T>;
+    /** Replace the selection. Silent by default; pass `{ notify: true }` to emit ONE aggregate `change`. */
+    setSelected(values: (string | number)[], opts?: {
+        notify?: boolean;
+    }): void;
+    /** Select every selectable option. */
+    selectAll(): void;
+    /** Clear the whole selection. */
+    clearAll(): void;
+    /** Toggle a single option by its value (select ⇄ deselect). */
+    toggleValue(value: string | number): void;
+    open(): void;
+    close(): void;
+    toggle(): void;
+    /** Set the search box text (runs the search, exactly as if typed). */
+    search(term: string): void;
+    /** Clear the search box and restore the full list (does not touch the selection). */
+    clearSearch(): void;
+    /** Scroll a specific option / group / index into view. */
+    scrollToValue(value: string | number): void;
+    scrollToGroup(group: string): void;
+    scrollToIndex(index: number): void;
+    /** Surface a transient message ("toast"), visible even in the fullscreen overlay. */
+    showMessage(content: string | HTMLElement, opts?: MessageOptions): void;
+    /** Dismiss the transient message, if any. */
+    hideMessage(): void;
+}
+
 export declare class MultiSelectElement<T = any> extends BlissElement<MultiSelectEvents> {
     #private;
     static formAssociated: boolean;
@@ -902,10 +1007,11 @@ declare type MultiSelectEvents = {
 };
 
 /**
- * Imperative facade handed to `keydownCallback` so a consumer can drive the picker without
- * reaching into internals. Every method mirrors a built-in keyboard action.
+ * Imperative facade handed to `keydownCallback`: the shared {@link MultiSelectController} plus the
+ * focus-navigation methods that only make sense mid-keystroke. Every method mirrors a built-in
+ * keyboard action.
  */
-declare interface MultiSelectKeyboardController<T = any> {
+export declare interface MultiSelectKeyboardController<T = any> extends MultiSelectController<T> {
     /** Move focus to the next / previous option. */
     focusNext(): void;
     focusPrevious(): void;
@@ -922,19 +1028,12 @@ declare interface MultiSelectKeyboardController<T = any> {
     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). */
+    /** @deprecated Alias of {@link MultiSelectController.search}. */
     setSearch(term: string): void;
-    /** Clear the search box and reset the visible list. */
-    clearSearch(): void;
 }
 
 /**
@@ -1541,6 +1640,17 @@ export declare class WebMultiSelect<T = any> {
     /** 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;
+    /**
+     * The host custom element — `this.element` is the internal `.ms` mount (inside the shadow
+     * root), so the host is its root node's `host` when shadowed, else the mount itself. Used as
+     * the {@link ActionContext} escape hatch (and where a wrapper hangs a server bridge).
+     */
+    private hostEl;
+    /**
+     * Build the {@link ActionContext} passed (as the additive 2nd arg) to every action-button
+     * callback and the `onClick` event: a snapshot of live state plus the shared controller.
+     */
+    private buildActionContext;
     /** Clear the search box (both the main input and the fullscreen search) and reset the visible
      *  list. Shared by Escape and the keyboard controller. */
     /**
@@ -1909,6 +2019,12 @@ export declare class WebMultiSelect<T = any> {
      * `null → ""`. Callers add their own leading space / base class as needed.
      */
     private classSuffix;
+    /**
+     * Build the {@link BadgeContentRenderContext} handed to the sibling `get*` callbacks
+     * (badge display / class / tooltip), so they see the same context the `render*` badge
+     * callbacks get: `displayMode`, `isInPopover`, plus the shared presentation fields.
+     */
+    private badgeRenderContext;
     /**
      * Render a removable badge for a selected option (used by the badges/partial display modes
      * and by the selected-items popover).