@keenmate/web-multiselect 1.8.6 → 1.10.0

package/README.md

@@ -7,6 +7,28 @@ A lightweight, accessible multiselect web component with typeahead search, RTL l
 
 > **⚠️ Security Notice:** This component intentionally allows raw HTML in rendering callbacks to give developers full control over content display. If you display user-generated content, you must sanitize it yourself. See [HTML Injection (XSS) Notice](#html-injection-xss-notice) for the complete list of affected callbacks.
 
+## What's New in v1.10.0
+
+- **`data-options` attribute on `<web-multiselect>`** — set options declaratively from HTML, no JS bootstrap required (works alongside `initial-values` for pure-HTML / server-rendered / SharePoint workbench scenarios).
+- **`form.reset()` now clears the selection** — the element is now form-associated (`static formAssociated = true` + `ElementInternals` + `formResetCallback()`).
+- **Dropdown / hint / selected popover no longer clipped inside scrollable ancestors** — Floating UI now uses `strategy: 'fixed'` for all three panels, so they escape `overflow: hidden|auto|scroll` containers (e.g. SharePoint Framework workbenches).
+- **`initial-values` now works when options arrive after init** — values are reconciled on every `options` mutation, not just at construction.
+- **Remove / close (×) buttons render as SVG masks** — pixel-centered regardless of font; color still flows through the existing `--ms-*-color` variables via `currentColor`; three new `--ms-*-icon-size` variables for theming.
+- **Keyboard navigation now keeps working after a mouse click on an option** — previously, clicking an option moved focus from the search input to the option's checkbox (knocking the `keydown` listener offline) *and* left `focusedIndex` at its pre-click value, so subsequent ArrowDown / ArrowUp / Enter went nowhere visible. Click now anchors `focusedIndex` to the clicked option and refocuses the search input, so arrow keys continue from where you clicked and Enter toggles the option under the cursor.
+- **Count-clear / popover-close hover backdrop now matches the rest of the component** — was a circle (`border-radius: 50%`), now a small rounded rectangle (`--ms-border-radius-sm`) consistent with every other interactive element. Themes that prefer the circle can set `--ms-count-clear-border-radius` and `--ms-selected-popover-close-border-radius` back to `50%`.
+- **Keyboard `Enter` respects disabled options** — previously only the click handler did.
+- **End-to-end test suite** — 114 Playwright specs across 19 fixture pages (`npm run test:e2e`).
+- **`THEMING.md`** — new reference cataloguing every theme-able component state and the CSS variables that drive it.
+
+## What's New in v1.9.0
+
+- **Live attribute / callback updates no longer rebuild the DOM** — `updateOptions(partial)` merges in place; selection state, scroll position, focus, and tooltips are preserved across attribute changes.
+- **9 previously-dead per-component CSS override hooks are now wired** — `--ms-hint-border-color`, `--ms-dropdown-border-color`, `--ms-actions-border-color`, `--ms-group-border-color`, `--ms-badge-counter-border-color`, `--ms-selected-popover-border-color`, `--ms-selected-popover-header-border-color`, `--ms-option-outline-color-focused`, `--ms-option-border-matched-color`.
+- **`selectAll` / `clearAll` now fire per-item `selectCallback` / `deselectCallback`** — consumers wiring per-item analytics or side effects no longer silently miss bulk operations.
+- **New `Tooltip` class** consolidating three previous tooltip implementations; fixes a handle leak and a popover-vs-main-container collision.
+- **`--base-primary-bg` theming variable** — `--ms-primary-bg` reads it first, then `--base-main-bg`, then a hardcoded default.
+- Plus many fixes across custom action buttons, grouped-option focus, badge cursors, focus rings, and logging.
+
 ## Features
 
 - 📝 **Declarative HTML** - Use standard `<option>` and `<optgroup>` elements - no JavaScript required for simple cases!
@@ -327,11 +349,15 @@ multiselect.addNewCallback = async (value) => {
 
 - **↑ ↓** - Navigate up/down through options
 - **Ctrl+↑ Ctrl+↓** - Jump between matched items (navigate mode only)
-- **Enter** - Select focused option
+- **Page Up / Page Down** - Move focus by 10 options at a time
+- **Home / End** - Jump to first / last option
+- **Enter** - Select focused option (or add new entry when `allow-add-new="true"` and the search has text)
 - **Escape** - Close popover → Clear search → Close dropdown (priority order)
 - **Tab** - Close dropdown and move to next field
 - **Type** - Filter options by search term
 
+> 💡 To surface these shortcuts to your users, set the `search-hint` attribute — the hint floats above the input when focused. Example: `<web-multiselect search-mode="navigate" search-hint="Ctrl/Cmd + ↓ / ↑ to jump between matches">`.
+
 ## Advanced Features
 
 ### Rich Content with Icons
@@ -1787,7 +1813,9 @@ For the complete list of all available CSS variables, see:
 | `--ms-badge-font-size` | `0.75rem` | Badge font size |
 | `--ms-badge-border-radius` | `0.375rem` | Badge border radius |
 | `--ms-badge-remove-bg` | `var(--ms-accent-color)` | Remove button background |
-| `--ms-badge-remove-color` | `var(--ms-text-color-on-accent)` | Remove button color |
+| `--ms-badge-remove-color` | `var(--ms-text-color-on-accent)` | Remove button (X) color — applied to the SVG via `currentColor` |
+| `--ms-badge-remove-icon-size` | `calc(1.0 * var(--ms-rem))` | Size of the X glyph inside the remove button |
+| `--ms-icon-remove` | (inline SVG `url(...)`) | The X mask SVG; override to swap the glyph shape (alpha-only — color comes from `--ms-badge-remove-color`) |
 | `--ms-badge-counter-text-bg` | `var(--ms-primary-bg)` | BadgeCounter text background ("+X more") |
 | `--ms-badge-counter-text-color` | `var(--ms-text-color-3)` | BadgeCounter text color |
 | `--ms-badge-counter-remove-bg` | `var(--ms-text-color-3)` | BadgeCounter remove button background |

package/component-variables.manifest.json

@@ -270,10 +270,11 @@
     { "name": "ms-badge-remove-bg", "category": "badge", "usage": "Badge remove button background" },
     { "name": "ms-badge-remove-color", "category": "badge", "usage": "Badge remove button color" },
     { "name": "ms-badge-remove-border", "category": "badge", "usage": "Badge remove button border" },
-    { "name": "ms-badge-remove-font-size", "category": "badge", "usage": "Badge remove button font size" },
+    { "name": "ms-badge-remove-font-size", "category": "badge", "usage": "Badge remove button font size (unused since 1.10.0 — kept for backward-compat)" },
+    { "name": "ms-badge-remove-icon-size", "category": "badge", "usage": "Badge remove X icon size (mask SVG)" },
     { "name": "ms-badge-remove-bg-hover", "category": "badge", "usage": "Badge remove button hover background" },
     { "name": "ms-badge-remove-box-shadow-focus", "category": "badge", "usage": "Badge remove button focus shadow" },
-    { "name": "ms-icon-remove", "category": "badge", "usage": "Remove icon character" },
+    { "name": "ms-icon-remove", "category": "badge", "usage": "Remove icon as CSS url() to a mask-friendly SVG; color comes from currentColor" },
     { "name": "ms-badge-counter-bg", "category": "badge", "usage": "Counter badge background" },
     { "name": "ms-badge-counter-border", "category": "badge", "usage": "Counter badge border" },
     { "name": "ms-badge-counter-border-color", "category": "badge", "usage": "Counter badge border color" },
@@ -306,11 +307,12 @@
     { "name": "ms-count-clear-size", "category": "count", "usage": "Count clear button size" },
     { "name": "ms-count-clear-bg", "category": "count", "usage": "Count clear button background" },
     { "name": "ms-count-clear-color", "category": "count", "usage": "Count clear button color" },
-    { "name": "ms-count-clear-font-size", "category": "count", "usage": "Count clear button font size" },
+    { "name": "ms-count-clear-font-size", "category": "count", "usage": "Count clear button font size (unused since 1.10.0 — kept for backward-compat)" },
+    { "name": "ms-count-clear-icon-size", "category": "count", "usage": "Count clear X icon size (mask SVG)" },
     { "name": "ms-count-clear-border-radius", "category": "count", "usage": "Count clear button border radius" },
     { "name": "ms-count-clear-bg-hover", "category": "count", "usage": "Count clear button hover background" },
     { "name": "ms-count-clear-color-hover", "category": "count", "usage": "Count clear button hover color" },
-    { "name": "ms-icon-clear", "category": "count", "usage": "Clear icon character" },
+    { "name": "ms-icon-clear", "category": "count", "usage": "Clear icon as CSS url() to a mask-friendly SVG; defaults to var(--ms-icon-remove)" },
 
     { "name": "ms-tooltip-bg", "category": "tooltip", "usage": "Tooltip background" },
     { "name": "ms-tooltip-text-color", "category": "tooltip", "usage": "Tooltip text color" },
@@ -340,7 +342,8 @@
     { "name": "ms-popover-close-size", "category": "popover", "usage": "Popover close button size" },
     { "name": "ms-selected-popover-close-bg", "category": "popover", "usage": "Popover close button background" },
     { "name": "ms-selected-popover-close-color", "category": "popover", "usage": "Popover close button color" },
-    { "name": "ms-selected-popover-close-font-size", "category": "popover", "usage": "Popover close button font size" },
+    { "name": "ms-selected-popover-close-font-size", "category": "popover", "usage": "Popover close button font size (unused since 1.10.0 — kept for backward-compat)" },
+    { "name": "ms-selected-popover-close-icon-size", "category": "popover", "usage": "Popover close X icon size (mask SVG)" },
     { "name": "ms-selected-popover-close-border-radius", "category": "popover", "usage": "Popover close button border radius" },
     { "name": "ms-selected-popover-close-bg-hover", "category": "popover", "usage": "Popover close button hover background" },
     { "name": "ms-selected-popover-close-color-hover", "category": "popover", "usage": "Popover close button hover color" },

package/dist/index.d.ts

@@ -194,7 +194,7 @@ declare interface MultiSelectConfig<T = any> {
     isVirtualScrollEnabled?: boolean;
     /** Vertical alignment of checkboxes relative to option content */
     checkboxAlign?: 'top' | 'center' | 'bottom';
-    /** Hint text shown above the input when focused */
+    /** Hint text shown above the input while the dropdown is open. */
     searchHint?: string;
     /** Placeholder text for the search input */
     searchPlaceholder?: string;
@@ -269,9 +269,11 @@ declare interface MultiSelectConfig<T = any> {
 }
 
 export declare class MultiSelectElement<T = any> extends BaseElement {
+    static formAssociated: boolean;
     private picker?;
     private containerElement?;
     private shadow;
+    private internals?;
     private _options?;
     private _valueMember?;
     private _getValueCallback?;
@@ -309,6 +311,14 @@ export declare class MultiSelectElement<T = any> extends BaseElement {
     private _changeCallback?;
     static get observedAttributes(): string[];
     constructor();
+    /**
+     * Called by the browser when the surrounding <form> is reset. Clears the
+     * picker's selection so the multiselect actually participates in the
+     * standard reset lifecycle. (Before form-association, reset was a no-op
+     * because the hidden inputs were re-stamped from internal state on every
+     * render.)
+     */
+    formResetCallback(): void;
     connectedCallback(): void;
     disconnectedCallback(): void;
     attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
@@ -321,8 +331,19 @@ export declare class MultiSelectElement<T = any> extends BaseElement {
      */
     private parseDeclarativeOptions;
     private _declarativeSelectedValues?;
+    /** Parse all observed attributes via ATTRIBUTE_TABLE into a partial config object. */
+    private parseAttributesFromTable;
     private initializePicker;
     private reinitialize;
+    /**
+     * Apply a partial config update to the live picker. Falls back to a full reinit if the
+     * picker can't apply the change in place (e.g. adding/removing the `searchHint` element).
+     * No-op if the picker hasn't been initialized yet — the next `initializePicker` will pick
+     * up the new programmatic state.
+     */
+    private updatePicker;
+    /** Normalize the picker's getValue() return into the array form expected by event detail. */
+    private collectSelectedValues;
     get options(): T[] | undefined;
     set options(value: T[] | undefined);
     set valueMember(value: string | null);
@@ -492,9 +513,10 @@ export declare type SearchInputMode = 'normal' | 'readonly' | 'hidden';
 export declare type SearchMode = 'filter' | 'navigate';
 
 /**
- * Set log level for a specific category
- * @param category Category logger to configure (e.g., 'MULTISELECT:UI')
- * @param level Log level to set ('trace' | 'debug' | 'info' | 'warn' | 'error' | 'silent')
+ * Set log level for a specific category. Accepts either the full prefixed name
+ * (e.g. `MULTISELECT:UI`) or the bare suffix (`UI`) for convenience.
+ * @param category Category logger name; bare names (UI/DATA/INIT/INTERACTION) are normalized to the prefixed form.
+ * @param level Log level ('trace' | 'debug' | 'info' | 'warn' | 'error' | 'silent')
  */
 export declare function setCategoryLevel(category: string, level: string): void;
 
@@ -534,12 +556,7 @@ export declare class WebMultiSelect<T = any> {
     private dropdownCleanup;
     private hintCleanup;
     private selectedPopoverCleanup;
-    private badgeTooltips;
-    private badgeTooltipCleanups;
-    private badgeTooltipShowTimeouts;
-    private badgeTooltipHideTimeouts;
-    private actionButtonTooltips;
-    private actionButtonTooltipCleanups;
+    private tooltips;
     private virtualScroll;
     private optionsContainer;
     private selectedPopoverVirtualScroll;
@@ -554,41 +571,31 @@ export declare class WebMultiSelect<T = any> {
     private documentKeydownHandler;
     private documentClickHandler;
     /**
-     * Extract value/ID from item
-     * Precedence: tuple[0] -> valueMember -> getValueCallback -> '[N/A]'
+     * Generic field extractor with the precedence:
+     *   tuple short-circuit -> member property -> callback -> fallback
+     *
+     * Tuple handling:
+     *   - `tupleIndex` (0 | 1): for `[key, value]` items, return that slot.
+     *   - `tupleSkip: true`: for any tuple, skip directly to fallback (used for icon/subtitle/group/disabled —
+     *     fields that don't make sense on a 2-element array).
+     *   - neither: tuples flow through the member/callback/fallback chain as if they were objects.
+     *
+     * `transform` is applied to tuple-slot and member-property reads (not to callback returns or the fallback),
+     * so e.g. you can pass `String` to coerce numeric members to strings while letting a typed callback return its
+     * own type unchanged.
      */
+    private extractField;
     private getItemValue;
-    /**
-     * Extract display value from item
-     * Precedence: tuple[1] -> displayValueMember -> getDisplayValueCallback -> '[N/A]'
-     */
     private getItemDisplayValue;
     /**
-     * Extract badge display value from item
-     * Precedence: getBadgeDisplayCallback -> getItemDisplayValue()
-     * This allows customizing badge text separately from dropdown display text
+     * Badge display falls back to the regular display value rather than '[N/A]', so consumers can override badge
+     * text independently. Doesn't fit the extractField shape (no tuple/member layer of its own).
      */
     private getItemBadgeDisplayValue;
-    /**
-     * Extract search value from item
-     * Precedence: searchValueMember -> getSearchValueCallback -> displayValue
-     */
     private getItemSearchValue;
-    /**
-     * Extract icon from item
-     */
     private getItemIcon;
-    /**
-     * Extract subtitle from item
-     */
     private getItemSubtitle;
-    /**
-     * Extract group from item
-     */
     private getItemGroup;
-    /**
-     * Extract disabled state from item
-     */
     private getItemDisabled;
     constructor(element: HTMLElement, options?: Partial<MultiSelectConfig<T>>);
     private init;
@@ -607,6 +614,11 @@ export declare class WebMultiSelect<T = any> {
      * Render dropdown with virtual scrolling
      */
     private renderDropdownVirtual;
+    /**
+     * Render the Select All / Clear All / custom action buttons row.
+     * Returns the empty string if multiple-select is off or no buttons are configured.
+     */
+    private renderActionsHTML;
     private renderOption;
     private highlightMatch;
     private groupOptions;
@@ -617,52 +629,113 @@ export declare class WebMultiSelect<T = any> {
     private handleDropdownClick;
     private handleBadgeClick;
     private handleClickOutside;
+    /**
+     * Move focus by computing a new index from (current, total).
+     * Returning -1 from `compute` is a no-op (used for empty list / no match).
+     */
+    private focusBy;
     private focusNext;
     private focusPrevious;
     private focusFirst;
     private focusLast;
-    private focusNextMatch;
-    private focusPreviousMatch;
     private focusPageUp;
     private focusPageDown;
+    private focusNextMatch;
+    private focusPreviousMatch;
     private scrollToFocused;
     private toggleOption;
     private handleAddNew;
     private selectOption;
     private deselectOption;
     private selectAll;
-    private clearAll;
+    clearAll(): void;
+    /**
+     * Re-render and fire callbacks after a selection state change.
+     * `added` / `removed` drive per-item select/deselect callbacks.
+     * `changeCallback` fires once if anything actually changed.
+     */
+    private commit;
     private open;
     private close;
+    /**
+     * Anchor a floating panel (dropdown or selected-items popover) below/above the input with
+     * placement-locking and width-syncing. Returns the `autoUpdate` cleanup.
+     *
+     * Both panels share: anchor on input, sync width, default to 'bottom-start', flip on first
+     * compute then lock the resulting placement, optionally clamp by dropdownMin/MaxWidth.
+     */
+    private anchorFloatingPanel;
     private positionDropdown;
     private positionHint;
     private parseInitialSelection;
+    /**
+     * Resolve any `selectedValues` entries that don't yet have a matching
+     * `selectedOptions` object by looking them up in the current `allOptions`.
+     * Idempotent; safe to call after init *and* after `options` is replaced
+     * (e.g., async fetch, `searchCallback` result, or late `element.options =`
+     * assignment). Without this, `initial-values` declared before options
+     * arrive ends up with phantom values that `getValue()` can never report.
+     */
+    private reconcileSelectedOptions;
     private toggleSelectedPopover;
     private showPopover;
     private hideSelectedPopover;
     private renderSelectedPopover;
     private renderSelectedPopoverVirtual;
-    private renderBadgeForPopover;
+    /**
+     * Render a removable badge for a selected option (used by the badges/partial display modes
+     * and by the selected-items popover).
+     *
+     * - In the popover, `renderSelectedItemContentCallback` and `getSelectedItemClassCallback` win
+     *   over the regular badge callbacks; that's how consumers customize popover items independently.
+     * - The `data-value` and aria-label both go through `getItemBadgeDisplayValue` so badge text and
+     *   accessible name stay in sync.
+     */
+    private renderBadgeHTML;
     private handleSelectedPopoverClick;
     private positionSelectedPopover;
     private updateHiddenInput;
     private getFormValue;
     getSelected(): T[];
     setSelected(values: (string | number)[]): void;
+    /**
+     * Merge a partial config update into the live picker without tearing down the DOM.
+     *
+     * Handles the cheap structural toggles inline (no-checkboxes class, badges-position class,
+     * input placeholder, search-input mode) and re-renders dropdown + badges + hidden inputs.
+     *
+     * Returns `true` if the change could be applied in place. Returns `false` for changes that
+     * truly require rebuilding the DOM scaffolding (currently: adding/removing the `searchHint`
+     * element, since it's only created in `buildHTML` if a hint string was provided). The caller
+     * should fall back to destroy + re-init in that case.
+     */
+    updateOptions(partial: Partial<MultiSelectConfig<T>>): boolean;
     get selectedItem(): T | null;
     get selectedValue(): string | number | (string | number)[] | null;
     getValue(): string | number | (string | number)[] | null;
+    /**
+     * Create or replace a tracked tooltip with the given id. Replacing destroys the old one,
+     * which is the normal flow when re-rendering badges/actions.
+     */
+    private spawnTooltip;
+    private destroyAllTooltips;
+    /** Build the badge-text tooltip content (callback overrides; default = displayValue + optional subtitle on next line). */
+    private buildBadgeTooltipContent;
+    /** Build the remove-button tooltip text (callback > format string with {0} > "Remove {name}"). */
+    private buildRemoveButtonTooltipText;
     private attachBadgeTooltips;
-    private createTooltipForElement;
-    private createRemoveButtonTooltip;
-    private positionBadgeTooltip;
-    private cleanupBadgeTooltip;
-    private destroyAllBadgeTooltips;
     private attachActionButtonTooltips;
-    private createActionButtonTooltip;
-    private positionActionButtonTooltip;
-    private cleanupActionButtonTooltip;
+    /**
+     * Destroy only the action-button tooltips. Called from `renderDropdown`/`renderDropdownVirtual`
+     * before rebuilding the actions row, so per-button tooltip state doesn't leak.
+     */
     private destroyAllActionButtonTooltips;
+    /**
+     * Destroy main-badges-container tooltips. Called before re-rendering the badges container.
+     * Popover tooltips (prefixed `popover-`) survive — they're owned by the popover lifecycle and
+     * cleaned up in `hideSelectedPopover`. Action-button tooltips (prefixed `action-`) survive too.
+     */
+    private destroyAllBadgeTooltips;
     destroy(): void;
 }