@keenmate/web-multiselect 1.12.0-rc02 → 1.12.0-rc03

package/docs/theming.md

@@ -0,0 +1,388 @@
+# Theming
+
+`@keenmate/web-multiselect` is styled entirely through CSS custom properties. The component uses Shadow DOM for encapsulation, but every visible color, size, and effect is exposed as a `--ms-*` variable that you can override from the light DOM.
+
+For interactive theme exploration, use the [KeenMate Theme Designer](https://theme-designer.keenmate.dev).
+
+## Sizing
+
+The component uses `--ms-rem` as a base unit for proportional scaling. Default is `10px`, meaning `calc(1.4 * var(--ms-rem))` equals `14px`.
+
+**Global scaling:**
+
+```html
+<!-- Compact (80%) -->
+<web-multiselect style="--ms-rem: 8px;"></web-multiselect>
+
+<!-- Default (100%) -->
+<web-multiselect></web-multiselect>
+
+<!-- Large (120%) -->
+<web-multiselect style="--ms-rem: 12px;"></web-multiselect>
+
+<!-- Pure Admin integration (inherits from html { font-size: 10px }) -->
+<web-multiselect style="--ms-rem: 1rem;"></web-multiselect>
+```
+
+**Via CSS class:**
+
+```css
+web-multiselect.compact { --ms-rem: 8px; }
+web-multiselect.large   { --ms-rem: 12px; }
+```
+
+> **Shadow DOM note:** CSS variables must be set on the `<web-multiselect>` element itself, not on wrapper divs.
+
+**Fine-grained control:**
+
+Override individual sizing variables for specific adjustments:
+
+- `--ms-input-height` — input field height (default: 35px)
+- `--ms-input-font-size` — input font size
+- `--ms-input-padding` — input padding
+- `--ms-badge-height` — badge height
+- `--ms-option-height` — option height in dropdown
+
+**Input size variants:**
+
+Five size variants for consistent input sizing across KeenMate components:
+
+| Size | Variable | Height | Base variable |
+|------|----------|--------|---------------|
+| XS | `--ms-input-size-xs-height` | 31px | `--base-input-size-xs-height` |
+| SM | `--ms-input-size-sm-height` | 33px | `--base-input-size-sm-height` |
+| MD | `--ms-input-size-md-height` | 35px | `--base-input-size-md-height` |
+| LG | `--ms-input-size-lg-height` | 38px | `--base-input-size-lg-height` |
+| XL | `--ms-input-size-xl-height` | 41px | `--base-input-size-xl-height` |
+
+Heights reference `--base-input-size-*-height` from the [Theme Designer](https://theme-designer.keenmate.dev), ensuring consistent input heights across all KeenMate components.
+
+```css
+/* Set consistent input heights across all components */
+:root {
+  --base-input-size-md-height: 4.0;  /* All components: 40px at 10px rem */
+}
+```
+
+## Theme Designer integration
+
+The easiest way to customize the appearance of this component is the **KeenMate Theme Designer** at [theme-designer.keenmate.dev](https://theme-designer.keenmate.dev).
+
+1. **Choose 3 base colors** — background, text, and accent.
+2. **Preview changes live** — see your theme applied instantly.
+3. **Fine-tune individual variables** — lock specific values while adjusting others.
+4. **Export your theme** — copy CSS, JSON, or SCSS to your project.
+
+### CSS variable layers
+
+KeenMate components support a **two-layer theming architecture**:
+
+**Standalone mode (simple)** — just override the component-specific variables you need:
+
+```css
+:root {
+  --ms-accent-color: #your-brand-color;
+  --ms-primary-bg: #your-background;
+  --ms-text-primary: #your-text-color;
+}
+```
+
+**Cascading mode (multi-component)** — when using multiple KeenMate components, you can define a shared base layer:
+
+```css
+:root {
+  /* Base layer - single source of truth */
+  --base-accent-color: #3b82f6;
+  --base-main-bg: #ffffff;
+  --base-hover-bg: #f3f4f6;
+  --base-text-color-1: #111827;
+
+  /* Components reference base layer */
+  --ms-accent-color: var(--base-accent-color);
+  --drp-accent-color: var(--base-accent-color);
+}
+```
+
+Change `--base-accent-color` once → all components update automatically.
+
+### Unified variable naming
+
+All KeenMate components follow a consistent naming convention for **Tier 1 variables** (core theming):
+
+| Purpose | web-multiselect | web-daterangepicker |
+|---------|-----------------|---------------------|
+| Brand color | `--ms-accent-color` | `--drp-accent-color` |
+| Background | `--ms-primary-bg` | `--drp-primary-bg` |
+| Text color | `--ms-text-primary` | `--drp-text-primary` |
+| Text on accent | `--ms-text-color-on-accent` | `--drp-text-on-accent` |
+| Border color | `--ms-border-color` | `--drp-border-color` |
+
+Learn the pattern once, apply it across all components.
+
+### Component variables manifest
+
+This package exports a `component-variables.manifest.json` file that documents all supported CSS variables for tooling integration (e.g., Theme Designer, IDE autocomplete):
+
+```javascript
+import manifest from '@keenmate/web-multiselect/component-variables.manifest.json';
+// manifest.baseVariables - list of --base-* variables the component responds to
+// manifest.componentVariables - list of --ms-* component-specific variables
+```
+
+## CSS variables (no build system required)
+
+You can customize the component using CSS variables even with just a `<script>` tag:
+
+```html
+<style>
+  /* Override tooltip appearance */
+  web-multiselect {
+    --ms-tooltip-bg: #1f2937;
+    --ms-tooltip-color: #f9fafb;
+    --ms-tooltip-padding: 0.625rem 0.875rem;
+    --ms-tooltip-border-radius: 0.5rem;
+    --ms-tooltip-font-size: 0.8125rem;
+    --ms-tooltip-max-width: 24rem;
+    --ms-tooltip-shadow: 0 4px 12px rgba(0, 0, 0, 0.25);
+    --ms-tooltip-z-index: 10000;
+  }
+
+  /* Override "+X more" badge colors */
+  web-multiselect {
+    --ms-more-badge-bg: #dbeafe;
+    --ms-more-badge-hover-bg: #bfdbfe;
+    --ms-more-badge-active-bg: #93c5fd;
+  }
+
+  /* Size the component */
+  web-multiselect {
+    width: 100%;
+    max-width: 400px;
+  }
+</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.
+
+### Inspecting variables in DevTools
+
+All CSS custom properties are defined at the `:host` level in the compiled CSS, making them visible in browser DevTools:
+
+1. Open DevTools (F12) and select the `<web-multiselect>` element.
+2. In the **Styles** panel, look for the `:host` selector.
+3. You'll see all 150+ variables with their default values.
+4. Edit values live to preview changes instantly.
+
+**CSS variables work with Shadow DOM** because they inherit through the shadow boundary. This means you can customize the component from outside:
+
+```html
+<style>
+  /* These variables will penetrate into the Shadow DOM */
+  web-multiselect {
+    --ms-accent-color: #10b981;          /* Changes primary color */
+    --ms-input-border-radius: 0.5rem;    /* Rounds input corners */
+  }
+</style>
+```
+
+For the complete list of all available CSS variables, see [`src/css/variables.css`](../src/css/variables.css) — all 150+ CSS custom properties at `:host` level.
+
+### Colors
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `--ms-accent-color` | `#3b82f6` | Primary accent color (blue) |
+| `--ms-accent-color-hover` | `#2563eb` | Accent color on hover |
+| `--ms-accent-color-active` | `#1d4ed8` | Accent color when active |
+| `--ms-text-primary` | `#111827` | Primary text color |
+| `--ms-text-secondary` | `#6b7280` | Secondary/muted text color |
+| `--ms-border-color` | `#e5e7eb` | Default border color |
+| `--ms-border` | `var(--base-border, 1px solid var(--ms-border-color))` | Default full border (inherits from theme-designer) |
+
+### Input component
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `--ms-input-bg` | `var(--base-input-bg, #ffffff)` | Input background |
+| `--ms-input-text` | `#111827` | Input text color |
+| `--ms-input-border` | `#d1d5db` | Input border color |
+| `--ms-input-focus-border-color` | `#3b82f6` | Border color when focused |
+| `--ms-input-padding-v` | `0.5rem` | Input vertical padding |
+| `--ms-input-padding-h` | `0.75rem` | Input horizontal padding |
+| `--ms-input-font-size` | `0.875rem` | Input font size |
+| `--ms-input-border-radius` | `0.375rem` | Input border radius |
+| `--ms-input-placeholder-color` | `#6b7280` | Placeholder text color |
+
+### Dropdown & options
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `--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 |
+| `--ms-option-padding-v` | `0.5rem` | Option vertical padding |
+| `--ms-option-padding-h` | `0.75rem` | Option horizontal padding |
+| `--ms-option-hover-bg` | `#f9fafb` | Option background on hover |
+| `--ms-option-color-hover` | `inherit` | Option text color on hover |
+| `--ms-option-bg-selected` | (rgba accent) | Selected option background |
+| `--ms-option-bg-focused` | `#f9fafb` | Focused option background (keyboard) |
+| `--ms-option-color-focused` | `inherit` | Focused option text color |
+| `--ms-option-bg-matched` | (accent 8%) | Matched option background (navigate mode) |
+| `--ms-option-color-matched` | `inherit` | Matched option text color |
+
+### Badges
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `--ms-badge-text-bg` | `var(--ms-accent-color-light)` | Badge background color |
+| `--ms-badge-text-color` | `var(--ms-accent-color)` | Badge text color |
+| `--ms-badge-gap` | `0.5rem` | Gap between badges |
+| `--ms-badge-height` | `1.5rem` | Height of badges |
+| `--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 (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 |
+| `--ms-badge-counter-remove-color` | `var(--ms-text-color-on-accent)` | BadgeCounter remove button color |
+| `--ms-badge-counter-border` | `1px solid var(--ms-border-color)` | BadgeCounter border |
+| `--ms-badge-text-border` | `none` | Badge text border (e.g., `1px solid #3b82f6`) |
+
+### Checkboxes
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `--ms-checkbox-bg` | `var(--ms-input-bg)` | Checkbox background |
+| `--ms-checkbox-border` | `1px solid var(--ms-border-color)` | Checkbox border |
+| `--ms-checkbox-border-radius` | `0.3rem` | Checkbox border radius |
+| `--ms-checkbox-checked-bg` | `var(--ms-accent-color)` | Background when checked |
+| `--ms-checkbox-checked-border` | `1px solid var(--ms-accent-color)` | Border when checked |
+| `--ms-checkbox-checkmark-color` | `var(--ms-text-color-on-accent)` | Checkmark color |
+| `--ms-checkbox-hover-border-color` | `var(--ms-accent-color)` | Border on hover |
+| `--ms-checkbox-disabled-bg` | `var(--ms-primary-bg)` | Disabled background |
+| `--ms-checkbox-disabled-border` | `1px solid var(--ms-border-color)` | Disabled border |
+
+### Scrollbar
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `--ms-scrollbar-width` | `8px` | Scrollbar width |
+| `--ms-scrollbar-track-bg` | `transparent` | Track background |
+| `--ms-scrollbar-thumb-bg` | `var(--ms-border-color)` | Thumb color |
+| `--ms-scrollbar-thumb-bg-hover` | `var(--ms-text-color-3)` | Thumb hover color |
+| `--ms-scrollbar-thumb-border-radius` | `4px` | Thumb border radius |
+
+### Counter (in input)
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `--ms-counter-bg` | `#3b82f6` | Counter background |
+| `--ms-counter-color` | `#ffffff` | Counter text color |
+| `--ms-counter-font-size` | `0.75rem` | Counter font size |
+| `--ms-counter-bg-hover` | `#2563eb` | Hover background color |
+
+### Tooltips
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `--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 |
+| `--ms-tooltip-font-size` | `0.875rem` | Tooltip font size |
+| `--ms-tooltip-max-width` | `20rem` | Tooltip maximum width |
+| `--ms-tooltip-shadow` | (box shadow) | Tooltip box shadow |
+| `--ms-tooltip-z-index` | `10000` | Tooltip z-index |
+
+### Typography
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `--ms-font-size-xs` | `0.75rem` | Extra small font size |
+| `--ms-font-size-sm` | `0.875rem` | Small font size |
+| `--ms-font-size-base` | `1rem` | Base font size |
+| `--ms-font-weight-medium` | `500` | Medium font weight |
+| `--ms-font-weight-semibold` | `600` | Semibold font weight |
+
+### Effects & transitions
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `--ms-transition-fast` | `150ms` | Fast transition duration |
+| `--ms-transition-normal` | `200ms` | Normal transition duration |
+| `--ms-easing-snappy` | (cubic-bezier) | Snappy easing function |
+| `--ms-shadow-md` | (box shadow) | Medium shadow |
+| `--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.
+
+### Visible surface (wrapper-host pattern)
+
+The `:host` is intentionally transparent — the visible chrome is painted by `.ms__input`, which reads `--ms-input-bg`. This wrapper-host pattern keeps the host's outer boundary free of background so the component drops into any container without a colored box, while `--ms-input-bg` still gives consumers a single knob to theme the input surface. Override `--ms-input-bg` (or `--base-input-bg`) to change the painted color; the host doesn't need its own background.
+
+### Watch out — the unlayered-reset footgun
+
+A consumer-side `* { margin: 0; padding: 0; ... }` (Bootstrap reboot, Tailwind preflight, hand-rolled) is *unlayered* and therefore beats every rule inside the component's `@layer component`. The component renders with mysteriously broken spacing even though variables resolved correctly. Wrap your universal reset in its own layer (`@layer reset { * { ... } }`) so the component's layered defaults can win. See the BlissFramework `css-structure.md` → "The unlayered-reset footgun" for the canonical write-up.
+
+## Advanced: direct CSS import
+
+For users who want to import the raw CSS source files:
+
+```css
+/* Import component CSS directly */
+@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';
+/* ... etc */
+```