@keenmate/web-multiselect 1.11.0 → 1.12.0-rc01

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.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.
@@ -18,19 +29,6 @@ A lightweight, accessible multiselect web component with typeahead search, RTL l
 - **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!
@@ -1733,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.
@@ -1759,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
 
@@ -1893,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:
@@ -1902,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

@@ -390,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" },