@keenmate/web-multiselect 2.0.0-rc09 → 2.0.0-rc11

package/dist/index.d.ts

@@ -1,10 +1,22 @@
 import { BlissElement } from '@keenmate/web-components-core';
+import { BreakpointMap } from '@keenmate/web-components-core';
+import { classifyDevice } from '@keenmate/web-components-core';
+import { configureBreakpoints } from '@keenmate/web-components-core';
+import { DeviceClass } from '@keenmate/web-components-core';
+import { ElementSize } from '@keenmate/web-components-core';
 import { EnvironmentSnapshot } from '@keenmate/web-components-core';
+import { getEnvironment } from '@keenmate/web-components-core';
 import { InputDef } from '@keenmate/web-components-core';
 import { Logger } from '@keenmate/web-components-core';
 import { LogLevelDesc } from '@keenmate/web-components-core';
+import { observeEnvironment } from '@keenmate/web-components-core';
+import { observeViewport } from '@keenmate/web-components-core';
+import { Orientation } from '@keenmate/web-components-core';
+import { OS } from '@keenmate/web-components-core';
 import { Placement } from '@keenmate/web-components-core/positioning';
+import { PointerType } from '@keenmate/web-components-core';
 import { PresentationContext } from '@keenmate/web-components-core';
+import { TABLET_MIN_SHORT_SIDE } from '@keenmate/web-components-core';
 
 /**
  * Action button configuration for dropdown actions (Select All, Clear All, custom actions)
@@ -82,14 +94,26 @@ export declare type BadgesPosition = 'top' | 'bottom' | 'left' | 'right';
  */
 export declare type BadgesThresholdMode = 'count' | 'partial';
 
+export { BreakpointMap }
+
+export { classifyDevice }
+
+export { configureBreakpoints }
+
 export declare const dataLogger: Logger;
 
+export { DeviceClass }
+
 /** Disable all logging (silent). */
 export declare function disableLogging(): void;
 
 /** Enable all logging (debug level). */
 export declare function enableLogging(): void;
 
+export { EnvironmentSnapshot }
+
+export { getEnvironment }
+
 export declare const initLogger: Logger;
 
 export declare const interactionLogger: Logger;
@@ -256,6 +280,17 @@ declare interface MultiSelectConfig<T = any> {
     renderOptionContentCallback?: (item: T, context: OptionContentRenderContext) => string | HTMLElement;
     /** Custom renderer for badge content (main badges area) - return HTML string or HTMLElement */
     renderBadgeContentCallback?: (item: T, context: BadgeContentRenderContext) => string | HTMLElement;
+    /**
+     * Custom renderer for the WHOLE badge (main badges area) — return HTML string or HTMLElement
+     * for the entire pill/card, not just its content. Unlike renderBadgeContentCallback (which fills
+     * the built-in pill), this replaces the badge markup entirely. The component wraps your output in
+     * a `.ms__badge.ms__badge--custom` element carrying `data-value`, and delegates removal to any
+     * element inside it with `data-action="remove"` (or the built-in `.ms__badge-remove` class) — so
+     * put a remove control in your markup and the component handles the deselect. Falls back to the
+     * default pill for a given item if the callback returns null/empty. Main badges area only (the
+     * selected-items popover keeps using renderSelectedItemContentCallback).
+     */
+    renderBadgeCallback?: (item: T, context: BadgeContentRenderContext) => string | HTMLElement | null | undefined;
     /** Custom renderer for selected item content in popover - return HTML string or HTMLElement */
     renderSelectedItemContentCallback?: (item: T) => string | HTMLElement;
     /** Callback to add custom CSS classes to selected items in popover - return string or array of class names */
@@ -301,6 +336,21 @@ declare interface MultiSelectConfig<T = any> {
     isAddNewAllowed?: boolean;
     /** Show count badge next to toggle icon (internal: isCounterShown) */
     isCounterShown?: boolean;
+    /**
+     * Show an inline clear (✕) button inside the input that wipes the whole selection.
+     * Appears only while something is selected (and the control is enabled). Clicking it
+     * clears the selection and any search text, fires `change`, and refocuses the input.
+     * Default `false`. (internal: isClearShown)
+     */
+    isClearShown?: boolean;
+    /**
+     * Allow the selected-items popover to open. Defaults to `true`. The popover is triggered by
+     * the count / compact / "+X more" badge and by the in-input counter (`isCounterShown`). Set
+     * to `false` when you render your own selection UI (e.g. an external container fed by the
+     * `change` event) — the badge and counter still show the count, but clicking them does nothing
+     * and they lose the pointer cursor. (internal: isSelectedPopoverEnabled)
+     */
+    isSelectedPopoverEnabled?: boolean;
     /**
      * Make badges display each option's `fullTitleMember` / `getFullTitleCallback` value
      * instead of its display value. Falls back to the display value for options without a
@@ -581,6 +631,15 @@ export declare class MultiSelectElement<T = any> extends BlissElement<MultiSelec
      * set before the dropdown can open.
      */
     protected environmentChanged(env: EnvironmentSnapshot): void;
+    /**
+     * This element's own border box changed (core §12.9 `resized`). Overriding the
+     * hook opts us into a shared page-wide ResizeObserver, subscribed on connect and
+     * dropped on disconnect. Unlike `environmentChanged`/`viewportChanged` (the
+     * WINDOW), this is our OWN box — a picker in a 400px sidebar on a 2560px monitor
+     * reflows on its width, not the viewport's. We only act when `collapse-badges-
+     * below` is set; otherwise it's a cheap no-op.
+     */
+    protected resized({ width }: ElementSize): void;
     /** Form field name (mirrors the `name` attribute → `formFieldId`). */
     get name(): string | null;
     set name(value: string | null);
@@ -601,6 +660,15 @@ export declare class MultiSelectElement<T = any> extends BlissElement<MultiSelec
     showMessage(content: string | HTMLElement, opts?: MessageOptions): void;
     /** Dismiss the transient message shown by {@link showMessage}, if any. */
     hideMessage(): void;
+    /** Open the dropdown. */
+    open(): void;
+    /** Close the dropdown. */
+    close(): void;
+    /** Toggle the dropdown open/closed. */
+    toggle(): void;
+    /** Whether the dropdown is currently open. Assigning opens/closes it. */
+    get isOpen(): boolean;
+    set isOpen(value: boolean);
     destroy(): void;
 }
 
@@ -732,6 +800,10 @@ export declare interface MultiSelectOptions extends MultiSelectConfig<MultiSelec
  */
 declare type NodeId = string | number;
 
+export { observeEnvironment }
+
+export { observeViewport }
+
 /**
  * Context provided to renderOptionContentCallback.
  *
@@ -783,6 +855,10 @@ export declare const OPTIONS_FORMATS: readonly ["json", "csv", "plain"];
 
 export declare type OptionsFormat = (typeof OPTIONS_FORMATS)[number];
 
+export { Orientation }
+
+export { OS }
+
 export declare interface ParsedOptions {
     /** Parsed options: objects for `json`/`csv`, `[value, label]` tuples for `plain`. */
     options: unknown[];
@@ -809,6 +885,8 @@ declare interface ParseOptionsOptions {
     rowSplitter?: string;
 }
 
+export { PointerType }
+
 /**
  * Search input display mode
  */
@@ -831,6 +909,8 @@ export declare function setCategoryLevel(category: string, level: LogLevelDesc):
 /** Set the same level on every category. */
 export declare function setLogLevel(level: LogLevelDesc): void;
 
+export { TABLET_MIN_SHORT_SIDE }
+
 export declare const uiLogger: Logger;
 
 /**
@@ -839,10 +919,10 @@ export declare const uiLogger: Logger;
 export declare type ValueFormat = 'json' | 'csv' | 'array';
 
 export declare class WebMultiSelect<T = any> {
+    #private;
     private element;
     private instanceId;
     private options;
-    private isOpen;
     private selectedValues;
     private selectedOptions;
     private allOptions;
@@ -867,6 +947,7 @@ export declare class WebMultiSelect<T = any> {
     private justClosedViaClick;
     private justOpenedViaClick;
     private positioningDriftWarned;
+    private fullscreenContainingBlockWarned;
     private presentationMode;
     private fullscreenHeader;
     private fullscreenSearchInput;
@@ -897,10 +978,12 @@ export declare class WebMultiSelect<T = any> {
     private selectedPopoverVirtualScroll;
     private selectedPopoverContainer;
     private input;
+    private inputWrapper;
     private dropdown;
     private dropdownInner;
     private badgesContainer;
     private counter;
+    private clearButton;
     private hint?;
     private selectedPopover;
     private documentKeydownHandler;
@@ -1048,6 +1131,24 @@ export declare class WebMultiSelect<T = any> {
      */
     private hasGroups;
     private renderDropdown;
+    /**
+     * Round the OUTER corners of the row at the very top and the row at the very
+     * bottom of the list so a focused/selected row's background — and crucially its
+     * focus `outline`, which traces the row's OWN box and follows its border-radius
+     * but NOT an ancestor's overflow clip — curves with the panel instead of poking a
+     * square corner past it.
+     *
+     * Keyed off DOM order, not option index, so grouping works: when grouped the top
+     * row is a `.ms__group-label` (not the first option, which sits below it), so we
+     * round whichever element is physically first/last. VirtualScroll renders rows in
+     * index order into one innerHTML, so DOM order == visual order there too.
+     *
+     * Logical corners (`border-start-*` / `border-end-*`) so it mirrors in RTL. A
+     * space-taking vertical scrollbar occupies the inline-END gutter, so the END-side
+     * corners stay square then (the panel's rounded end corner is the scrollbar
+     * track's). The radius is 0 in the fullscreen sheet (that scope zeroes the var).
+     */
+    private applyEdgeOptionRadii;
     /**
      * Render dropdown with virtual scrolling
      */
@@ -1174,14 +1275,33 @@ export declare class WebMultiSelect<T = any> {
     private deselectOption;
     private selectAll;
     clearAll(): void;
+    /**
+     * Inline clear (✕) handler: wipe the whole selection and any search text, then
+     * restore focus to the input. clearAll() → commit() → renderBadges() already
+     * refreshes this button's visibility (it hides once nothing is selected).
+     */
+    private clearClick;
+    /**
+     * Show the inline clear (✕) only when it is opted in (isClearShown), something is
+     * selected, and the control is enabled. Called from renderBadges() so it tracks
+     * every selection change. Uses inline display like the counter / fullscreen clear.
+     */
+    private updateClearButton;
     /**
      * Re-render and fire callbacks after a selection state change.
      * `added` / `removed` drive per-item select/deselect callbacks.
      * `onChange` fires once if anything actually changed.
      */
     private commit;
-    private open;
-    private close;
+    /** Open the dropdown (no-op if already open, or if there is nothing to show). */
+    open(): void;
+    /** Close the dropdown (no-op if already closed). */
+    close(): void;
+    /** Toggle the dropdown open/closed. */
+    toggle(): void;
+    /** Whether the dropdown is currently open. Assigning opens/closes it. */
+    get isOpen(): boolean;
+    set isOpen(value: boolean);
     /**
      * Anchor a floating panel (dropdown or selected-items popover) below/above the input with
      * placement-locking and width-syncing. Returns the `autoUpdate` cleanup.
@@ -1199,6 +1319,23 @@ export declare class WebMultiSelect<T = any> {
      * owns the measurement + culprit-finding + CB-CSS diagnostic (`detectFixedDrift`).
      */
     private warnDrift;
+    /**
+     * Fullscreen counterpart of {@link warnDrift}. The overlay is a `position: fixed`,
+     * full-viewport sheet — but if an ancestor of the host establishes a fixed-positioning
+     * containing block (`transform` / `perspective` / `filter` / `backdrop-filter` / a
+     * qualifying `will-change`), the browser anchors the sheet to THAT ancestor's box instead
+     * of the viewport, so it no longer covers the screen (offset, clipped, or mis-sized).
+     *
+     * Unlike the floating path — where core measures real drift after positioning — nothing
+     * anchors the sheet, so there's no drift to observe. Instead we ask core's shared
+     * heuristic (`getFixedPositionOffsetParent`, the same one that feeds the floating platform)
+     * whether the sheet's true offset parent is the viewport (`window`) or an element. An
+     * element means it WILL be mis-anchored; warn once, pointing at the culprit. We only check
+     * the reliably-honoured properties core lists (transform family) — `contain` /
+     * `container-type` are omitted because browsers don't honour them for fixed positioning,
+     * so they don't actually break the sheet.
+     */
+    private warnFullscreenContainingBlock;
     private positionDropdown;
     /**
      * Switch how the open panels are presented. 'floating' anchors them to the input
@@ -1364,6 +1501,20 @@ export declare class WebMultiSelect<T = any> {
     private hideSelectedPopover;
     private renderSelectedPopover;
     private renderSelectedPopoverVirtual;
+    /**
+     * Coerce a render-callback result to an HTML string. Callbacks may return a string
+     * (HTML) or an HTMLElement (serialized via `outerHTML`); null/undefined → ''. Used by
+     * every "return string | HTMLElement" content callback that builds into an innerHTML
+     * string. (DOM sinks that hold a live node instead — the reveal/message panels — use
+     * textContent/appendChild directly and intentionally don't go through here.)
+     */
+    private toHtml;
+    /**
+     * Normalize a class callback result (`string | string[] | null`) to a single
+     * space-joined string with falsy entries dropped — e.g. `['a', '', 'b'] → "a b"`,
+     * `null → ""`. Callers add their own leading space / base class as needed.
+     */
+    private classSuffix;
     /**
      * Render a removable badge for a selected option (used by the badges/partial display modes
      * and by the selected-items popover).