@keenmate/web-multiselect 1.10.0 → 1.12.0-rc01

package/README.md

@@ -7,27 +7,27 @@ 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.
+## What's New in v1.12.0-rc01
+
+- **Dark mode now responds to framework theme classes** — `data-bs-theme="dark"` (Bootstrap 5.3+), `.dark` (Tailwind), and `data-theme="dark"` on any ancestor flip the component to dark, even on apps that flip classes without declaring `color-scheme`. Your own `--base-*` overrides on `:root` flow through unchanged — the component picks the dark branch of its built-in fallbacks without clobbering your theme. Symmetric `light` selectors let you force one widget back to light on a dark page. Per-instance `<web-multiselect data-theme="dark">` works as the highest-priority escape hatch.
+- **CSS cascade layers (`@layer variables, component, overrides`)** — every internal rule lives in a named layer, so consumer CSS in the light DOM can override any component rule without `!important` or specificity arms races. Document any unlayered rule in your app's CSS and it wins automatically.
+- **CSS file structure refactored into canonical Tier 1+2+3** — `controls.css` for input chrome, `floating.css` for dropdown/hint/tooltip/popover, `states.css` for block-level state modifiers, `badges.css` / `count-display.css` for the two display modes, etc. Each file now owns one logical concern; the old mixed-bag `input-dropdown.css`, `tooltips-popover.css`, `badges-display.css` are gone. Only affects deep CSS imports; bundle output unchanged.
+- **CSS source files no longer have underscore prefix** — `_variables.css` → `variables.css`, etc. The underscore was a leftover SASS partial convention; these are plain CSS modules.
+- **BEM-aligned class names** — `.ms-wrapper` → `.ms__wrapper`, `.ms-debug-info` → `.ms__debug-info`, `.ms-debug-stats` → `.ms__debug-stats`. The wrapper class is internal layout chrome; debug classes are dev-only. See CHANGELOG migration table if you'd styled any of these externally.
+- **Debug panel now fully themeable** — 11 new `--ms-debug-*` variables (was hardcoded hex literals).
+- **`"./manifest"` short-import** — `import manifest from '@keenmate/web-multiselect/manifest'` for tooling that reads the variable catalog.
+- **`test/AUDIT.md`** — living compliance tracker against the BlissFramework web-component guidelines (CSS structure, base variables, color scheme).
+
+## 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.
 
 ## Features
 
@@ -1662,8 +1662,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);
@@ -1730,6 +1731,31 @@ You can customize the component using CSS variables even with just a `<script>`
 </style>
 ```
 
+### Dark mode — supported signals
+
+Since v1.12.0 the multiselect honors **five different signals** for switching to dark mode. Pick whichever fits your app; you don't need to wire them all up.
+
+| # | Signal | Set by | Example |
+|---|--------|--------|---------|
+| 1 | OS preference + page `color-scheme` | App author | `html { color-scheme: light dark }` — multiselect picks the OS branch automatically. |
+| 2 | Page-level `color-scheme: dark` | App author | `body { color-scheme: dark }` — flips every multiselect on the page to dark. |
+| 3 | Framework data-attribute on ancestor | Bootstrap, Pure Admin, custom apps | `<html data-bs-theme="dark">` or `<div data-theme="dark">…</div>` |
+| 4 | Framework class on ancestor | Tailwind, hand-rolled toggles | `<html class="dark">` |
+| 5 | Per-instance attribute on host | App author, for one widget | `<web-multiselect data-theme="dark">` |
+
+**Precedence** (highest wins): per-instance (#5) → framework ancestor (#3, #4) → page color-scheme (#1, #2).
+
+#### Forcing a single widget back to light
+
+If your page is dark but you want one multiselect to render light:
+
+```html
+<!-- on a body { color-scheme: dark } page -->
+<web-multiselect data-theme="light"></web-multiselect>
+```
+
+This works for any of signals #3–#5. The symmetric `data-theme="light"`, `data-bs-theme="light"`, `.light` selectors restore the light palette inside the affected scope.
+
 ### Available CSS Variables
 
 The component exposes **150+ CSS custom properties** defined at the `:host` level, making them inspectable and overridable. Below are the **50+ most commonly customized variables** organized by category.
@@ -1756,7 +1782,7 @@ All CSS custom properties are now defined at the `:host` level in the compiled C
 ```
 
 For the complete list of all available CSS variables, see:
-- [_variables.css](./src/css/_variables.css) - All 150+ CSS custom properties at `:host` level
+- [variables.css](./src/css/variables.css) - All 150+ CSS custom properties at `:host` level
 
 #### Colors
 
@@ -1788,7 +1814,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 +1886,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 |
@@ -1890,6 +1916,25 @@ For the complete list of all available CSS variables, see:
 | `--ms-shadow-xl` | (box shadow) | Extra large shadow |
 | `--ms-disabled-opacity` | `0.5` | Opacity for disabled state |
 
+### Cascade layers / override contract
+
+Since v1.12.0, the component's internal CSS is organized into named `@layer`s:
+
+```css
+@layer variables, component, overrides;
+```
+
+This gives consumers a predictable escape hatch when they need to override a rule from outside the shadow DOM (e.g. via `web-multiselect ::part(...)` or descendant selectors that reach into composed light DOM):
+
+| Where your rule lives | Wins against |
+|---|---|
+| Unlayered consumer rule | Every internal layer (no `!important` needed) |
+| Consumer `@layer overrides` block | Component's `overrides` layer if loaded later in the stylesheet stack |
+| `:root { --base-* }` declaration | Component's `variables` layer trivially |
+| `web-multiselect { --ms-* }` element selector | Same as above, with higher specificity |
+
+In practice you rarely need to think about layers — variables-first theming (`--ms-*` and `--base-*` overrides) covers ~95% of customization. Layers exist for the residual 5% where you need to flip a property the variable system doesn't expose.
+
 ### Advanced: Direct CSS Import
 
 For users who want to import the raw CSS source files:
@@ -1899,8 +1944,8 @@ For users who want to import the raw CSS source files:
 @import '@keenmate/web-multiselect/css';
 
 /* Or import individual partials */
-@import '@keenmate/web-multiselect/src/css/_variables.css';
-@import '@keenmate/web-multiselect/src/css/_base.css';
+@import '@keenmate/web-multiselect/src/css/variables.css';
+@import '@keenmate/web-multiselect/src/css/base.css';
 /* ... etc */
 ```
 

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" },
@@ -387,6 +390,18 @@
     { "name": "ms-scrollbar-thumb-bg-hover", "category": "scrollbar", "usage": "Scrollbar thumb hover background" },
     { "name": "ms-scrollbar-thumb-border-radius", "category": "scrollbar", "usage": "Scrollbar thumb border radius" },
 
+    { "name": "ms-debug-bg", "category": "debug", "usage": "Debug panel background" },
+    { "name": "ms-debug-border-color", "category": "debug", "usage": "Debug panel border" },
+    { "name": "ms-debug-text-color", "category": "debug", "usage": "Debug panel text" },
+    { "name": "ms-debug-border-radius", "category": "debug", "usage": "Debug panel corner radius" },
+    { "name": "ms-debug-summary-color", "category": "debug", "usage": "Debug section heading color" },
+    { "name": "ms-debug-summary-bg-hover", "category": "debug", "usage": "Debug section heading hover background" },
+    { "name": "ms-debug-summary-outline-color", "category": "debug", "usage": "Debug section heading focus outline" },
+    { "name": "ms-debug-summary-border-radius", "category": "debug", "usage": "Debug section heading corner radius" },
+    { "name": "ms-debug-stats-bg", "category": "debug", "usage": "Debug stats nested panel background" },
+    { "name": "ms-debug-stats-border-radius", "category": "debug", "usage": "Debug stats nested panel corner radius" },
+    { "name": "ms-debug-bullet-color", "category": "debug", "usage": "Debug stat bullet marker color" },
+
     { "name": "ms-transform-center-y", "category": "transform", "usage": "Center Y transform" },
     { "name": "ms-transform-rotate-180", "category": "transform", "usage": "180 degree rotation" },
     { "name": "ms-transform-scale-hover", "category": "transform", "usage": "Hover scale transform" },

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;