@keenmate/web-multiselect 1.10.0 → 1.11.0

package/README.md

@@ -7,6 +7,17 @@ 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).
@@ -20,15 +31,6 @@ A lightweight, accessible multiselect web component with typeahead search, RTL l
 - **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!
@@ -1662,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);
@@ -1788,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 |
@@ -1860,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" },

package/dist/index.d.ts

@@ -553,6 +553,7 @@ export declare class WebMultiSelect<T = any> {
     private isRTL;
     private effectiveBadgesPosition;
     private justClosedViaClick;
+    private positioningDriftWarned;
     private dropdownCleanup;
     private hintCleanup;
     private selectedPopoverCleanup;
@@ -665,6 +666,18 @@ 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;