@keenmate/web-multiselect 1.9.0 → 1.11.0

package/README.md

@@ -7,6 +7,30 @@ 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.11.0
+
+- **OS-aware light/dark defaults via `light-dark()`** — set `color-scheme: dark` on your page (`:root`, `body`, etc.) and the multiselect picks readable dark text/background colors automatically. No more enumerating ~15 `--base-*` overrides just to get usable defaults on a dark theme.
+- **Drift-detection warning for positioning edge cases** — if an exotic ancestor CSS property (e.g. `contain: paint`, or `container-type` in certain shadow-DOM layouts) makes the dropdown land somewhere other than where the library told the browser to put it, a `console.warn` fires once with the likely culprit element and an actionable fix suggestion.
+- **Dropdown no longer stranded to the side when an ancestor uses `container-type`** — Floating UI was walking up to a `container-type: inline-size` ancestor (notably pure-admin's `.pa-layout__main`), but the browser wouldn't actually anchor the fixed panel there. The library now uses a custom `getOffsetParent` that only walks up properties browsers reliably honor for fixed positioning.
+- **Dropdown no longer opens shifted to the side of its input** — when the dropdown's natural content was wider than the input, Floating UI's `shift()` middleware was measuring the unclamped panel and pushing it left, then the subsequent width clamp left it stranded next to the input. Panel sizing now happens before positioning. Same fix applies to the selected-items popover.
+- **`--base-*` taxonomy aligned with KeenMate cross-component naming** (theming change — see CHANGELOG migration table): `--base-primary-bg` → `--base-hover-bg`, `--base-primary-bg-hover` → `--base-active-bg`. `--base-dropdown-bg` and `--base-tooltip-bg` continue to work; new chain fallbacks to `--base-elevated-bg` / `--base-inverse-bg`.
+- **Option hover stays visible on dark themes** — `--ms-primary-bg` now mixes 8% of the text color into the main background by default, so the hover is always a visible step toward the text. No more invisible hover when the consumer forgets to override `--base-hover-bg`.
+- **New `examples-positioning.html`** — walks through baseline / transformed-ancestor / container-type / drift-detection scenarios.
+- **New dark-mode e2e suite** — 4 specs verifying WCAG-AA option contrast on a dark page across fully-themed, minimal-override, and pure OS-inheritance configurations.
+
+## 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.
+
 ## Features
 
 - 📝 **Declarative HTML** - Use standard `<option>` and `<optgroup>` elements - no JavaScript required for simple cases!
@@ -1640,8 +1664,9 @@ KeenMate components support a **two-layer theming architecture**:
 :root {
   /* Base layer - single source of truth */
   --base-accent-color: #3b82f6;
-  --base-primary-bg: #ffffff;
-  --base-text-primary: #111827;
+  --base-main-bg: #ffffff;
+  --base-hover-bg: #f3f4f6;
+  --base-text-color-1: #111827;
 
   /* Components reference base layer */
   --ms-accent-color: var(--base-accent-color);
@@ -1766,7 +1791,7 @@ For the complete list of all available CSS variables, see:
 
 | Variable | Default | Description |
 |----------|---------|-------------|
-| `--ms-dropdown-bg` | `var(--base-dropdown-bg, #ffffff)` | Dropdown background |
+| `--ms-dropdown-bg` | `var(--base-dropdown-bg, var(--base-elevated-bg, light-dark(#ffffff, #1a1a1a)))` | Dropdown background (auto-adapts to OS dark mode) |
 | `--ms-dropdown-border` | `var(--ms-border-color)` | Dropdown border color |
 | `--ms-dropdown-shadow` | (box shadow) | Dropdown shadow |
 | `--ms-dropdown-max-height` | `20rem` | Max height of dropdown |
@@ -1791,7 +1816,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 |
@@ -1836,7 +1863,7 @@ For the complete list of all available CSS variables, see:
 
 | Variable | Default | Description |
 |----------|---------|-------------|
-| `--ms-tooltip-bg` | `var(--base-tooltip-bg, #333333)` | Tooltip background color |
+| `--ms-tooltip-bg` | `var(--base-tooltip-bg, var(--base-inverse-bg, light-dark(#333333, #f5f5f5)))` | Tooltip background (auto-adapts to OS dark mode) |
 | `--ms-tooltip-color` | `var(--ms-tooltip-text-color)` | Tooltip text color |
 | `--ms-tooltip-padding` | `0.5rem 0.75rem` | Tooltip padding |
 | `--ms-tooltip-border-radius` | `0.375rem` | Tooltip border radius |

package/component-variables.manifest.json

@@ -14,7 +14,8 @@
     { "name": "base-text-color-4", "required": false, "usage": "Quaternary text (placeholders)" },
     { "name": "base-text-color-on-accent", "required": false, "usage": "Text on accent backgrounds (badges, checkboxes)" },
     { "name": "base-main-bg", "required": true, "usage": "Primary background, hint background, actions background" },
-    { "name": "base-hover-bg", "required": false, "usage": "Hover states for options, badges, buttons" },
+    { "name": "base-hover-bg", "required": false, "usage": "Hover background (drives --ms-primary-bg: option hover/focus, action-button hover, counter hover)" },
+    { "name": "base-active-bg", "required": false, "usage": "Active/pressed background (drives --ms-primary-bg-hover: selected-active, counter badge)" },
     { "name": "base-disabled-bg", "required": false, "usage": "Disabled/readonly surface backgrounds" },
     { "name": "base-border-color", "required": true, "usage": "Input, dropdown, action button borders" },
     { "name": "base-border", "required": false, "usage": "Full border shorthand" },
@@ -25,10 +26,12 @@
     { "name": "base-input-border-focus", "required": false, "usage": "Input border when focused" },
     { "name": "base-input-placeholder-color", "required": false, "usage": "Placeholder text color" },
     { "name": "base-input-bg-disabled", "required": false, "usage": "Disabled input background" },
-    { "name": "base-dropdown-bg", "required": false, "usage": "Dropdown and popover backgrounds" },
+    { "name": "base-dropdown-bg", "required": false, "usage": "Dropdown and popover backgrounds (primary; falls back to base-elevated-bg)" },
+    { "name": "base-elevated-bg", "required": false, "usage": "Elevated surface (fallback for dropdown and popover backgrounds)" },
     { "name": "base-dropdown-border", "required": false, "usage": "Dropdown border" },
     { "name": "base-dropdown-box-shadow", "required": false, "usage": "Dropdown shadow" },
-    { "name": "base-tooltip-bg", "required": false, "usage": "Tooltip background" },
+    { "name": "base-tooltip-bg", "required": false, "usage": "Tooltip background (primary; falls back to base-inverse-bg)" },
+    { "name": "base-inverse-bg", "required": false, "usage": "Inverse surface (fallback for tooltip background)" },
     { "name": "base-tooltip-text-color", "required": false, "usage": "Tooltip text color" },
     { "name": "base-font-family", "required": false, "usage": "All text in component" },
     { "name": "base-font-size-2xs", "required": false, "usage": "Smallest text (multiplier)" },
@@ -69,8 +72,8 @@
     { "name": "ms-text-primary", "category": "text", "usage": "Legacy alias for text-color-1" },
     { "name": "ms-text-secondary", "category": "text", "usage": "Legacy alias for text-color-3" },
 
-    { "name": "ms-primary-bg", "category": "surface", "usage": "Primary background color" },
-    { "name": "ms-primary-bg-hover", "category": "surface", "usage": "Primary background hover" },
+    { "name": "ms-primary-bg", "category": "surface", "usage": "Hover/focus background (options, action buttons, counter); reads --base-hover-bg" },
+    { "name": "ms-primary-bg-hover", "category": "surface", "usage": "Active/stronger background (counter badge text); reads --base-active-bg" },
 
     { "name": "ms-border-color", "category": "border", "usage": "Default border color" },
     { "name": "ms-border", "category": "border", "usage": "Full border shorthand" },
@@ -270,10 +273,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 +310,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 +345,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;
@@ -543,6 +553,7 @@ export declare class WebMultiSelect<T = any> {
     private isRTL;
     private effectiveBadgesPosition;
     private justClosedViaClick;
+    private positioningDriftWarned;
     private dropdownCleanup;
     private hintCleanup;
     private selectedPopoverCleanup;
@@ -638,7 +649,7 @@ export declare class WebMultiSelect<T = any> {
     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.
@@ -655,9 +666,30 @@ export declare class WebMultiSelect<T = any> {
      * compute then lock the resulting placement, optionally clamp by dropdownMin/MaxWidth.
      */
     private anchorFloatingPanel;
+    /**
+     * Sanity-check that the browser placed the panel where we told it to. With `position: fixed`
+     * and no transformed/perspective/filter ancestor, `left: ${x}px` must render at viewport-x = x.
+     * If the rendered position drifts, the consumer has an ancestor that establishes a fixed
+     * containing block but isn't on our reliable-anchors list (likely `contain: paint|layout|strict`
+     * or `container-type` — which the spec says creates a CB but the browser's actual behavior
+     * varies across shadow-DOM scenarios). We can't fix it from inside the library, but we can
+     * surface a clear warning so the developer knows where to look.
+     *
+     * Fires at most once per multiselect instance to avoid flooding the console during autoUpdate.
+     */
+    private verifyPanelLanded;
     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;