igniteui-webcomponents 7.3.1 → 7.4.0

package/skills/igniteui-wc-figma-to-app/references/validation-patterns.md

@@ -0,0 +1,376 @@
+# Playwright Visual Validation Patterns — Web Components
+
+> **Part of the [`igniteui-wc-figma-to-app`](../SKILL.md) skill.**
+>
+> Use this file in Phase 5 for the measurement-driven validation loop. Read it in full
+> before calling any Playwright tool.
+
+---
+
+## Core Philosophy
+
+**Measure, don't eyeball.** The goal is not visual regression (did this change since last
+week?) but design fidelity (does this match the Figma spec?). Screenshots give you the
+gestalt; `playwright_browser_evaluate` gives you the numbers; numbers drive corrections.
+
+**The Web Components twist:** almost everything you want to measure lives inside a shadow
+root. `document.querySelector('igc-card .title')` returns `null` — not because the element
+is missing, but because the selector cannot cross the boundary. Every snippet below is
+shadow-aware. Use them instead of writing ad-hoc selectors.
+
+---
+
+## Phase 5 Tool Sequence
+
+```
+1.  playwright_browser_navigate       → open the app at the target route
+2.  playwright_browser_console_messages → catch startup/registration errors
+3.  playwright_browser_resize          → match the Figma artboard dimensions
+4.  playwright_browser_navigate        → re-navigate after resize (required)
+5.  playwright_browser_evaluate        → registration + theme audit (fail fast)
+6.  playwright_browser_take_screenshot → capture the full viewport
+7.  [Visual comparison]                → against the Phase 1c reference, section by section
+8.  playwright_browser_evaluate        → measure EVERY section in the Phase 1g Surfaces table
+9.  [Surfaces audit]                   → assert background, radius, padding, border
+10. [Action controls audit]            → count and name every control, shadow roots included
+11. [Input variant audit]              → check `outlined` against the Phase 1d variant
+12. [Classify mismatches]              → severity table
+13. [Apply fixes]                      → edit source files
+14. playwright_browser_navigate        → reload after fixes
+15. Repeat 6–14 until no Critical/Major issues remain
+16. Do NOT advance to the next artboard until all checks pass on this one
+17. playwright_browser_snapshot        → final accessibility check
+```
+
+---
+
+## Known Pitfalls
+
+### 1. Viewport reset after resize
+
+After `playwright_browser_resize`, the browser may navigate itself to `about:blank`, and
+subsequent screenshots and measurements come back empty.
+
+```
+playwright_browser_resize({ width: 1440, height: 900 })
+playwright_browser_navigate({ url: "http://localhost:5173/dashboard" })
+// NOW safe to screenshot and measure
+```
+
+### 2. `playwright_browser_evaluate` uses `function`, not `script`
+
+Passing `script` fails with *"Invalid input: expected string, received undefined"*.
+
+```
+// WRONG
+playwright_browser_evaluate({ script: "return document.title;" })
+
+// CORRECT
+playwright_browser_evaluate({ function: "() => document.title" })
+```
+
+### 3. Measuring before the components have upgraded
+
+Custom elements upgrade asynchronously, and Lit renders on a microtask. Measuring too early
+returns pre-upgrade box metrics (often `height: 0`). Wait for definition and render:
+
+```
+playwright_browser_evaluate({
+  function: "async () => { const tags = [...new Set([...document.querySelectorAll('*')].map(e => e.tagName.toLowerCase()).filter(t => t.startsWith('igc-')))]; await Promise.all(tags.map(t => customElements.whenDefined(t))); const els = [...document.querySelectorAll('*')].filter(e => e.tagName.startsWith('IGC-')); await Promise.all(els.map(e => e.updateComplete).filter(Boolean)); await new Promise(r => requestAnimationFrame(() => requestAnimationFrame(r))); return { upgraded: tags.length }; }"
+})
+```
+
+### 4. An unregistered element fails silently
+
+A missing `defineComponents(...)` produces **no console error** — the tag renders as an
+empty inline box. Run the registration audit before blaming CSS.
+
+### 5. Dev server must be running
+
+```
+playwright_browser_navigate({ url: "http://localhost:5173" })
+playwright_browser_console_messages()
+```
+
+`ERR_CONNECTION_REFUSED` or a blank page means the Vite dev server is not running — ask the
+user to run `npm start`. Note the port: Vite defaults to **5173**.
+
+---
+
+## The Deep-Query Helper
+
+Every measurement snippet below assumes this helper. It walks shadow roots, so a selector
+like `igc-card >>> [part="header"]` resolves.
+
+```javascript
+// Paste as the first statements of any evaluate() function.
+const deepQuery = (path, root = document) =>
+  path.split('>>>').map(s => s.trim()).reduce(
+    (node, sel) => node && (node.shadowRoot || node).querySelector(sel),
+    root
+  );
+
+const deepQueryAll = (sel, root = document) => {
+  const out = [];
+  const walk = (node) => {
+    if (!node) return;
+    out.push(...node.querySelectorAll(sel));
+    node.querySelectorAll('*').forEach(el => el.shadowRoot && walk(el.shadowRoot));
+  };
+  walk(root);
+  return out;
+};
+```
+
+Prefer measuring the **host element** (`igc-card`) for box metrics — width, height,
+position, margin — and pierce only for internals that the design calls out (header height,
+row padding). When you must pierce, target documented `::part(...)` names from `get_doc`,
+never internal class names.
+
+---
+
+## Reusable Measurement Snippets
+
+All snippets use the `function` parameter.
+
+### Registration + theme audit (run first, every page)
+
+```
+playwright_browser_evaluate({
+  function: "() => { const tags = [...new Set(deepQueryAll('*').map(e => e.tagName.toLowerCase()).filter(t => t.startsWith('igc-')))]; const undefinedTags = tags.filter(t => !customElements.get(t)); const s = getComputedStyle(document.documentElement); return { tags, undefinedTags, theme: s.getPropertyValue('--ig-theme').trim(), variant: s.getPropertyValue('--ig-theme-variant').trim(), primary500: s.getPropertyValue('--ig-primary-500').trim(), surface500: s.getPropertyValue('--ig-surface-500').trim(), fontFamily: s.getPropertyValue('--ig-font-family').trim() }; }"
+})
+```
+
+Assert: `undefinedTags` is empty; `theme` and `variant` match the design system and variant
+resolved in Phase 3. An empty `theme` means no theme CSS is loaded — components silently
+fall back to `bootstrap` / `light`.
+
+### Measure a single element (shadow-aware)
+
+```
+playwright_browser_evaluate({
+  function: "() => { const deepQuery = (path, root = document) => path.split('>>>').map(s => s.trim()).reduce((n, sel) => n && (n.shadowRoot || n).querySelector(sel), root); const el = deepQuery('<YOUR_SELECTOR_PATH>'); if (!el) return { error: 'element not found' }; const s = getComputedStyle(el); const r = el.getBoundingClientRect(); return { fontSize: s.fontSize, fontWeight: s.fontWeight, lineHeight: s.lineHeight, color: s.color, backgroundColor: s.backgroundColor, padding: s.padding, margin: s.margin, gap: s.gap, borderRadius: s.borderRadius, border: s.border, boxShadow: s.boxShadow, width: Math.round(r.width), height: Math.round(r.height), top: Math.round(r.top), left: Math.round(r.left) }; }"
+})
+```
+
+> A host element with `display: inline` (the Lit default) reports a misleading box. If width
+> or height look wrong, check for a missing `:host { display: block }` before chasing padding.
+
+### Surfaces audit (mandatory — every page, every Phase 1g surface)
+
+```
+playwright_browser_evaluate({
+  function: "() => { const sections = { /* fill from the Phase 1g Surfaces table */ sectionA: '.section-a', sectionB: '.section-b' }; const deepQuery = (path, root = document) => path.split('>>>').map(s => s.trim()).reduce((n, sel) => n && (n.shadowRoot || n).querySelector(sel), root); const out = {}; for (const [key, sel] of Object.entries(sections)) { const el = deepQuery(sel); if (!el) { out[key] = 'NOT FOUND'; continue; } const s = getComputedStyle(el); const r = el.getBoundingClientRect(); out[key] = { bg: s.backgroundColor, radius: s.borderRadius, padding: s.padding, border: s.border, shadow: s.boxShadow, w: Math.round(r.width), h: Math.round(r.height) }; } return out; }"
+})
+```
+
+**Assert for each entry:**
+
+- Figma surface has a background → `bg !== 'rgba(0, 0, 0, 0)'`
+- Figma section floats on the page background → `bg === 'rgba(0, 0, 0, 0)'` (do not over-surface)
+- `radius`, `padding`, `border`, `shadow` match the Phase 1g values
+- children shown inside the card in Figma are inside the card's bounding rect in the DOM
+
+### Action controls audit (mandatory, every page)
+
+```
+playwright_browser_evaluate({
+  function: "() => { const out = []; const walk = (root) => { root.querySelectorAll('igc-button, igc-icon-button, button, [role=button]').forEach(b => { if (b.tagName === 'BUTTON' && b.getRootNode().host?.matches('igc-button, igc-icon-button')) return; out.push((b.textContent || '').trim().replace(/\\s+/g, ' ') || b.getAttribute('aria-label') || b.getAttribute('name') || '(unlabeled)'); }); root.querySelectorAll('*').forEach(el => el.shadowRoot && walk(el.shadowRoot)); }; walk(document); return { count: out.length, controls: out }; }"
+})
+```
+
+Compare against the Phase 1d inventory. Any control not in the design context output is
+fabricated and must be removed. `(unlabeled)` entries are also an accessibility failure —
+icon-only buttons need `aria-label`.
+
+### Input variant audit (every page with form controls)
+
+```
+playwright_browser_evaluate({
+  function: "() => { const tags = ['igc-input','igc-textarea','igc-mask-input','igc-date-time-input','igc-file-input','igc-select','igc-combo','igc-date-picker','igc-date-range-picker']; const out = {}; tags.forEach(t => { const els = deepQueryAll(t); if (els.length) out[t] = { count: els.length, outlined: els.filter(e => e.hasAttribute('outlined')).length }; }); return out; }"
+})
+```
+
+Compare against the variant detected in Phase 1d. If the design uses border-style inputs
+everywhere, every control should report `outlined === count`.
+
+### Property-binding audit (collection-bound charts, grids, combos)
+
+```
+playwright_browser_evaluate({
+  function: "() => { const defs = [ ['igc-category-chart', ['dataSource', 'data']], ['igc-data-chart', ['dataSource', 'data']], ['igc-pie-chart', ['dataSource', 'data']], ['igc-doughnut-chart', ['dataSource', 'data']], ['igc-financial-chart', ['dataSource', 'data']], ['igc-sparkline', ['dataSource', 'data']], ['igc-treemap', ['dataSource', 'data']], ['igc-funnel-chart', ['dataSource', 'data']], ['igc-grid', ['data']], ['igc-grid-lite', ['data']], ['igc-combo', ['data']] ]; const out = {}; defs.forEach(([tag, dataProps]) => { deepQueryAll(tag).forEach((el, i) => { const dataProp = dataProps.find(prop => Array.isArray(el[prop])); const brushProps = ['brushes', 'outlines'].filter(prop => Array.isArray(el[prop])); out[tag + '#' + i] = { dataLength: dataProp ? el[dataProp].length : null, brushCollections: brushProps.length ? Object.fromEntries(brushProps.map(prop => [prop, el[prop]])) : null, height: Math.round(el.getBoundingClientRect().height) }; }); }); return out; }"
+})
+```
+
+`dataLength: null` means the collection was set as an attribute (or not at all) instead of
+as a property. `brushCollections: null` on a chart means none of its documented
+`brushes` / `outlines` arrays were assigned, so it is still using the default palette instead
+of the Figma series colors. `height: 0` means the element or its grid track has no height.
+Use this audit for the collection-bound host tags in the selected plan; gauges and maps need
+their own host-specific validation once you know which properties the chosen component binds.
+
+### Measure the gap between two elements
+
+```
+playwright_browser_evaluate({
+  function: "() => { const a = document.querySelector('<SELECTOR_A>'); const b = document.querySelector('<SELECTOR_B>'); if (!a || !b) return { error: 'one or both elements not found' }; const ra = a.getBoundingClientRect(); const rb = b.getBoundingClientRect(); return { gapBetween: Math.round(rb.top - ra.bottom), aHeight: Math.round(ra.height), bTop: Math.round(rb.top) }; }"
+})
+```
+
+### Measure typography scale
+
+```
+playwright_browser_evaluate({
+  function: "() => { const sels = ['h1','h2','h3','p','.subtitle','.caption']; const out = {}; sels.forEach(sel => { const el = document.querySelector(sel); if (el) { const s = getComputedStyle(el); out[sel] = { fontSize: s.fontSize, fontWeight: s.fontWeight, lineHeight: s.lineHeight, fontFamily: s.fontFamily }; } }); return out; }"
+})
+```
+
+### Measure grid layout proportions
+
+```
+playwright_browser_evaluate({
+  function: "() => { const el = document.querySelector('<LAYOUT_CONTAINER>'); if (!el) return { error: 'layout container not found' }; const s = getComputedStyle(el); return { display: s.display, gridTemplateColumns: s.gridTemplateColumns, gridTemplateRows: s.gridTemplateRows, gap: s.gap, width: Math.round(el.getBoundingClientRect().width) }; }"
+})
+```
+
+### Inspect a component's parts (when a token override is not landing)
+
+```
+playwright_browser_evaluate({
+  function: "() => { const host = document.querySelector('<igc-tag>'); if (!host || !host.shadowRoot) return { error: 'host or shadow root not found' }; return [...host.shadowRoot.querySelectorAll('[part]')].map(el => ({ part: el.getAttribute('part'), bg: getComputedStyle(el).backgroundColor, color: getComputedStyle(el).color })); }"
+})
+```
+
+Use the reported `part` names — they are the supported styling surface when a design token
+does not exist for a detail the design requires.
+
+---
+
+## Mismatch Severity Classification
+
+| Severity     | Category                   | Decision rule                                               | Action                      |
+| ------------ | -------------------------- | ----------------------------------------------------------- | --------------------------- |
+| **Critical** | Missing element            | Present in Figma, absent from DOM                           | Auto-fix                    |
+| **Critical** | Unregistered component     | Tag present but `customElements.get()` is undefined         | Auto-fix (add registration) |
+| **Critical** | Broken layout              | Overlapping elements, content outside bounds, zero-height   | Auto-fix                    |
+| **Critical** | Wrong design system active | `--ig-theme` does not match the Phase 3 resolution          | Auto-fix (theme import)     |
+| **Major**    | Wrong component            | Figma shows a combo, code has a select                      | Auto-fix                    |
+| **Major**    | Wrong variant              | `variant="flat"` when the design shows contained            | Auto-fix                    |
+| **Major**    | Collection not bound       | `data` / `dataSource` / `brushes` set as an attribute       | Auto-fix                    |
+| **Minor**    | Spacing off by > 4px       | `gap: 24px` measured, Figma shows `16px`                    | Auto-fix if a single property |
+| **Minor**    | Font size wrong by > 2px   | `16px` measured, Figma shows `14px`                         | Auto-fix                    |
+| **Cosmetic** | Color shade                | `rgb(50,50,50)` vs `#333333` (perceptually identical)       | Report only                 |
+| **Cosmetic** | Spacing off by ≤ 4px       | Rounding or sub-pixel difference                            | Report only                 |
+
+### Mismatch report format
+
+```
+ISSUE:    <concise description of the mismatch>
+LOCATION: <component/section in the view>
+FIGMA:    <value from the design context>
+RENDERED: <value measured by Playwright>
+SEVERITY: <Critical | Major | Minor | Cosmetic>
+FIX:      <specific, one-line code change>
+```
+
+Example:
+
+```
+ISSUE:    Card surface is transparent
+LOCATION: igc-card in the "Budget Categories" section
+FIGMA:    background = #222222 (Surfaces table row 1)
+RENDERED: backgroundColor = rgba(0, 0, 0, 0)
+SEVERITY: Critical
+FIX:      create_component_theme("card", tokens: { background: "var(--ig-surface-100)" })
+          and apply the generated block — do not set background on a wrapper div.
+
+ISSUE:    Chart series colors are the default palette
+LOCATION: igc-category-chart in the "Spending" panel
+FIGMA:    series = #9DE772, #6DB1FF
+RENDERED: brushes = null
+SEVERITY: Major
+FIX:      chart.brushes = ['#9DE772', '#6DB1FF'] assigned as a property after validating
+          with get_chart_series_colors({ customBrushes: [...] }).
+```
+
+---
+
+## Section-by-Section Comparison Checklist
+
+| Section              | What to check                                                                                                            |
+| -------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| Top navigation       | Height, background, slotted `start`/`end` content alignment, action icon positions                                       |
+| Sidebar / nav drawer | Width (`--menu-full-width`), `position="relative"` vs modal, item spacing, icon + label alignment, selected state          |
+| Page header          | Typography size and weight, breadcrumb spacing, action button prominence                                                  |
+| Data grid            | Column widths (at least one fluid), header background, row height, cell padding, grid theme CSS actually loaded           |
+| Cards / panels       | **Background** (must not be `rgba(0,0,0,0)` when Figma shows a surface), border, radius, shadow, padding                   |
+| Surface containers   | Every entry in the Phase 1g Surfaces table; children enclosed within the card's bounding rect                             |
+| Form fields          | `outlined` presence matching the Phase 1d variant; label placement; helper text slot                                      |
+| Action controls      | Count and names vs the Phase 1d inventory; `aria-label` on icon-only buttons                                              |
+| Buttons              | `variant` (flat/outlined/contained/fab), color, typography, padding                                                       |
+| Charts               | Chart type, **series colors** (explicit `brushes`), marker visibility, legend placement, non-zero height                  |
+| Lists                | Slot usage (`start`/`title`/`subtitle`/`end`), item height, divider treatment                                             |
+| Footer / paginator   | Alignment, spacing, font size                                                                                             |
+
+---
+
+## Accessibility Snapshot Checks
+
+After `playwright_browser_snapshot()`, verify:
+
+| Check                 | What to look for                                                        |
+| --------------------- | ------------------------------------------------------------------------ |
+| Heading hierarchy     | `h1` → `h2` → `h3` without skipping levels                               |
+| Button labels         | Every button has text or `aria-label` — icon-only buttons especially     |
+| Input labels          | Inputs use the `label` attribute or an associated `<label>`              |
+| Navigation landmark   | `<nav>` or `role="navigation"` wraps the main navigation                 |
+| Main content landmark | `<main>` or `role="main"` wraps the primary content region               |
+| Image alt text        | Meaningful `<img>` elements have non-empty `alt`                         |
+| Drawer labelling      | `igc-nav-drawer` has a `label` when more than one nav landmark exists    |
+
+---
+
+## Common Fix Patterns
+
+### Style correction — in order of preference
+
+1. **Component design token** — `get_component_design_tokens` → `create_component_theme`
+2. **Documented `::part(...)`** — for details with no token
+3. **Slotted content you own** — style it in your own CSS
+4. Never internal class names; never attempts to reach into a shadow root from page CSS
+
+### Density and spacing
+
+```
+set_size({ component: "calendar", size: "small", platform: "webcomponents" })
+set_spacing({ component: "calendar", spacing: 0.75, platform: "webcomponents" })
+set_size({ scope: ".compact-toolbar", size: "small", platform: "webcomponents" })
+```
+
+Or directly:
+
+```css
+igc-calendar {
+  --ig-size: var(--ig-size-small);
+  --ig-spacing: 0.75;
+}
+```
+
+Choose the multiplier by visual judgment — never by mapping a Figma pixel value.
+
+### Color correction
+
+```css
+/* never a raw hex once a palette exists */
+background: var(--ig-primary-500);
+color: var(--ig-primary-500-contrast);
+```
+
+Use `get_color({ color: "primary", variant: "500", contrast: true })` when unsure of the
+exact variable name.
+
+### Missing element
+
+If an element is in Figma but absent from the DOM, check in this order: registration
+(`customElements.get`) → import path → the slot name it should occupy → then go back to
+Phase 2 and re-read the component doc. A wrong slot name renders nothing and reports nothing.

package/skills/igniteui-wc-generate-from-image-design/references/gotchas.md

@@ -134,6 +134,27 @@ For core UI component theming, prefer `create_component_theme` and apply the ret
 ### Grid theming is package-specific
 `igniteui-grid-lite` and the premium grid packages do not map to Angular's `igx-grid__*` internal class structure. Use `get_component_design_tokens("grid")`, the exact grid package docs, and exposed tokens or parts for the package present in the workspace.
 
+### `igniteui-webcomponents-grids` theme must be injected into the shadow root
+
+A bare CSS import (`import '...material.css'`) lands in the document head and selector rules outside a Shadow root never reach inside it. When the grid is rendered inside a Shadow root, the theme must be injected there too — it targets the grid's internal structure and elements. Without it, internal grid elements render with broken dimensions; checkboxes can expand to 1,100 px wide and collapse the entire grid UI.
+
+Import the theme as an inline string (requires bundler support for `?inline`, e.g. Vite) and inject it as a `<style>` tag inside the shadow root. The exact approach depends on the framework — for a LitElement component, render it at the top of `render()`:
+
+```typescript
+import { html } from 'lit';
+import gridTheme from 'igniteui-webcomponents-grids/grids/themes/light/material.css?inline';
+
+// LitElement example — adapt to your Shadow DOM approach (Stencil, FAST, vanilla attachShadow, etc.)
+render() {
+  return html`
+    <style>${gridTheme}</style>
+    <igc-grid ...></igc-grid>
+  `;
+}
+```
+
+Apply the same `?inline` + `<style>` approach for dark or other theme variants.
+
 ### Read luminance warnings from palette generation
 If palette generation returns a luminance warning for a generated surface, do not ignore it. If the design needs multiple surface depths, use `create_custom_palette` or define semantic CSS variables such as `--surface-1` and `--surface-2` in the main stylesheet instead of relying on a single generated surface color.
 

package/skills/igniteui-wc-integrate-with-framework/SKILL.md

@@ -96,7 +96,8 @@ Before loading a reference, identify the target framework from the project conte
 - No major framework found in `package.json`
 - Plain `.html` files reference a `<script type="module">`
 - Entry point is a plain `.js` or `.ts` file with no framework imports
-- User explicitly asks for vanilla JS or HTML integration
+- `package.json` contains "lit" — start with the vanilla JS reference; if using Shadow DOM, follow the Shadow root theming note for grids
+- User explicitly asks for vanilla JS, HTML, or LitElement integration
 
 → **Load:** [vanilla-js.md](./references/vanilla-js.md)
 
@@ -106,7 +107,7 @@ Before loading a reference, identify the target framework from the project conte
 
 Ask the user directly:
 
-> "What framework or platform are you using? (React, Angular, Vue 3, or Vanilla JS / HTML)"
+> "What framework or platform are you using? (React, Angular, Vue 3, Vanilla JS / HTML, or LitElement)"
 
 Then load the matching reference from the options above.
 
@@ -119,7 +120,7 @@ Then load the matching reference from the options above.
 | React | [react.md](./references/react.md) |
 | Angular | [angular.md](./references/angular.md) |
 | Vue 3 | [vue.md](./references/vue.md) |
-| Vanilla JS / HTML | [vanilla-js.md](./references/vanilla-js.md) |
+| Vanilla JS / HTML / LitElement | [vanilla-js.md](./references/vanilla-js.md) |
 
 Each reference covers:
 

package/skills/igniteui-wc-integrate-with-framework/references/vanilla-js.md

@@ -113,6 +113,20 @@ document.body.innerHTML = '<igc-button>Click</igc-button>';
 
 Ensure you import a theme CSS file in your entry point. Without it, components render unstyled.
 
+**`igniteui-webcomponents-grids` inside a Shadow root:** A bare `import '...css'` lands in the document head and never reaches inside a Shadow root — the grid's internal structure and elements receive no styles and render with incorrect dimensions. Import the theme as an inline string and inject it as a `<style>` tag inside the shadow root (requires bundler support for `?inline`, e.g. Vite). For a LitElement component:
+
+```typescript
+import { html } from 'lit';
+import gridTheme from 'igniteui-webcomponents-grids/grids/themes/light/material.css?inline';
+
+render() {
+  return html`
+    <style>${gridTheme}</style>
+    <igc-grid ...></igc-grid>
+  `;
+}
+```
+
 ## Next Steps
 
 - [Optimize bundle size](../../igniteui-wc-optimize-bundle-size/SKILL.md) — import only the components you use

package/skills/igniteui-wc-migrate-grid-lite-to-premium/SKILL.md

@@ -108,11 +108,21 @@ import {
   IgcNoopFilteringStrategy,
 } from 'igniteui-webcomponents-grids';
 
-// Theme - change to the grids-specific path
+// Theme — import as an inline string so it can be injected into the shadow root (requires bundler support for ?inline, e.g. Vite)
 // Available: light|dark x bootstrap|material|fluent|indigo
-import 'igniteui-webcomponents-grids/grids/themes/light/bootstrap.css';
+import gridTheme from 'igniteui-webcomponents-grids/grids/themes/light/material.css?inline';
 ```
 
+> **Grid inside a Shadow root — required step:** A bare CSS import lands in the document head and never reaches inside a Shadow root — the grid's internal structure and elements get no styles. Inject the theme as a `<style>` tag inside the shadow root. For a LitElement component, at the top of `render()`:
+> ```typescript
+> render() {
+>   return html`
+>     <style>${gridTheme}</style>
+>     <igc-grid ...></igc-grid>
+>   `;
+> }
+> ```
+
 ## Step 3 - Update HTML Tags
 
 | Grid Lite | Premium Grid |

package/theming/config.d.ts

@@ -1,9 +1,17 @@
+import { type ChangeThemeEventDetail } from './theming-event.js';
 import type { Theme, ThemeVariant } from './types.js';
-export declare function getTheme(): {
-    theme: Theme;
-    themeVariant: ThemeVariant;
-};
-export declare function setTheme(value: Theme, variant: ThemeVariant): void;
+/**
+ * Relays "igc-change-theme" events from `window` to the theming controllers.
+ * It also syncs the module state from the event detail, so an event from another
+ * copy of the library changes the theme here too.
+ */
+declare class ThemeChangedEmitter extends EventTarget {
+    constructor();
+    /** @internal */
+    handleEvent({ detail }: CustomEvent<ChangeThemeEventDetail>): void;
+}
+export declare const _themeChangedEmitter: ThemeChangedEmitter;
+export declare function getTheme(): ChangeThemeEventDetail;
 /**
  * Allows the global configuration of the active theme.
  *
@@ -15,3 +23,4 @@ export declare function setTheme(value: Theme, variant: ThemeVariant): void;
  *  ```
  */
 export declare function configureTheme(t: Theme, v?: ThemeVariant): void;
+export {};

package/theming/config.js

@@ -1,37 +1,57 @@
 import { isServer } from 'lit';
-import { CHANGE_THEME_EVENT, } from './theming-event.js';
-import { getAllCssVariables } from './utils.js';
+import { CHANGE_THEME_EVENT, CHANGED_THEME_EVENT, } from './theming-event.js';
+const THEMES = new Set(['bootstrap', 'material', 'indigo', 'fluent']);
+const THEME_VARIANTS = new Set(['light', 'dark']);
 let theme;
 let themeVariant;
-function dispatchThemingEvent(detail) {
-    if (!isServer) {
-        globalThis.dispatchEvent(new CustomEvent(CHANGE_THEME_EVENT, { detail }));
-    }
+function isOfTypeTheme(value) {
+    return THEMES.has(value);
 }
-function isOfTypeTheme(theme) {
-    return ['bootstrap', 'material', 'indigo', 'fluent'].includes(theme);
+function isOfTypeThemeVariant(value) {
+    return THEME_VARIANTS.has(value);
 }
-function isOfTypeThemeVariant(variant) {
-    return ['light', 'dark'].includes(variant);
+function setTheme(value, variant) {
+    theme = value;
+    themeVariant = variant;
 }
+class ThemeChangedEmitter extends EventTarget {
+    constructor() {
+        super();
+        if (!isServer) {
+            globalThis.addEventListener(CHANGE_THEME_EVENT, this);
+        }
+    }
+    handleEvent({ detail }) {
+        if (isOfTypeTheme(detail?.theme) &&
+            isOfTypeThemeVariant(detail?.themeVariant)) {
+            setTheme(detail.theme, detail.themeVariant);
+            this.dispatchEvent(new CustomEvent(CHANGED_THEME_EVENT));
+        }
+    }
+}
+export const _themeChangedEmitter = new ThemeChangedEmitter();
 export function getTheme() {
     if (!(theme && themeVariant)) {
-        const cssVars = getAllCssVariables();
-        const foundTheme = cssVars.igTheme;
-        const foundVariant = cssVars.igThemeVariant;
+        const rootStyles = isServer
+            ? undefined
+            : getComputedStyle(document.documentElement);
+        const foundTheme = rootStyles?.getPropertyValue('--ig-theme').trim();
+        const foundVariant = rootStyles
+            ?.getPropertyValue('--ig-theme-variant')
+            .trim();
         theme = isOfTypeTheme(foundTheme) ? foundTheme : 'bootstrap';
         themeVariant = isOfTypeThemeVariant(foundVariant) ? foundVariant : 'light';
     }
     return { theme, themeVariant };
 }
-export function setTheme(value, variant) {
-    theme = value;
-    themeVariant = variant;
-}
 export function configureTheme(t, v = 'light') {
     if (isOfTypeTheme(t) && isOfTypeThemeVariant(v)) {
         setTheme(t, v);
-        dispatchThemingEvent({ theme, themeVariant });
+        if (!isServer) {
+            globalThis.dispatchEvent(new CustomEvent(CHANGE_THEME_EVENT, {
+                detail: { theme, themeVariant },
+            }));
+        }
     }
 }
 //# sourceMappingURL=config.js.map

package/theming/config.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/theming/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,KAAK,CAAC;AAC/B,OAAO,EACL,kBAAkB,GAEnB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAEhD,IAAI,KAAY,CAAC;AACjB,IAAI,YAA0B,CAAC;AAK/B,SAAS,oBAAoB,CAAC,MAA8B;IAC1D,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,UAAU,CAAC,aAAa,CAAC,IAAI,WAAW,CAAC,kBAAkB,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC;IAC5E,CAAC;AACH,CAAC;AAED,SAAS,aAAa,CAAC,KAAa;IAClC,OAAO,CAAC,WAAW,EAAE,UAAU,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AACvE,CAAC;AAED,SAAS,oBAAoB,CAAC,OAAe;IAC3C,OAAO,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;AAC7C,CAAC;AAED,MAAM,UAAU,QAAQ;IACtB,IAAI,CAAC,CAAC,KAAK,IAAI,YAAY,CAAC,EAAE,CAAC;QAC7B,MAAM,OAAO,GAAG,kBAAkB,EAAE,CAAC;QACrC,MAAM,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC;QACnC,MAAM,YAAY,GAAG,OAAO,CAAC,cAAc,CAAC;QAE5C,KAAK,GAAG,aAAa,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,WAAW,CAAC;QAC7D,YAAY,GAAG,oBAAoB,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,OAAO,CAAC;IAC7E,CAAC;IAED,OAAO,EAAE,KAAK,EAAE,YAAY,EAAE,CAAC;AACjC,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,KAAY,EAAE,OAAqB;IAC1D,KAAK,GAAG,KAAK,CAAC;IACd,YAAY,GAAG,OAAO,CAAC;AACzB,CAAC;AAYD,MAAM,UAAU,cAAc,CAAC,CAAQ,EAAE,IAAkB,OAAO;IAChE,IAAI,aAAa,CAAC,CAAC,CAAC,IAAI,oBAAoB,CAAC,CAAC,CAAC,EAAE,CAAC;QAChD,QAAQ,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QACf,oBAAoB,CAAC,EAAE,KAAK,EAAE,YAAY,EAAE,CAAC,CAAC;IAChD,CAAC;AACH,CAAC","sourcesContent":["import { isServer } from 'lit';\nimport {\n  CHANGE_THEME_EVENT,\n  type ChangeThemeEventDetail,\n} from './theming-event.js';\nimport type { Theme, ThemeVariant } from './types.js';\nimport { getAllCssVariables } from './utils.js';\n\nlet theme: Theme;\nlet themeVariant: ThemeVariant;\n\n/**\n * Dispatch an \"igc-change-theme\" event to `window` with the given detail.\n */\nfunction dispatchThemingEvent(detail: ChangeThemeEventDetail): void {\n  if (!isServer) {\n    globalThis.dispatchEvent(new CustomEvent(CHANGE_THEME_EVENT, { detail }));\n  }\n}\n\nfunction isOfTypeTheme(theme: string): theme is Theme {\n  return ['bootstrap', 'material', 'indigo', 'fluent'].includes(theme);\n}\n\nfunction isOfTypeThemeVariant(variant: string): variant is ThemeVariant {\n  return ['light', 'dark'].includes(variant);\n}\n\nexport function getTheme() {\n  if (!(theme && themeVariant)) {\n    const cssVars = getAllCssVariables();\n    const foundTheme = cssVars.igTheme;\n    const foundVariant = cssVars.igThemeVariant;\n\n    theme = isOfTypeTheme(foundTheme) ? foundTheme : 'bootstrap';\n    themeVariant = isOfTypeThemeVariant(foundVariant) ? foundVariant : 'light';\n  }\n\n  return { theme, themeVariant };\n}\n\nexport function setTheme(value: Theme, variant: ThemeVariant): void {\n  theme = value;\n  themeVariant = variant;\n}\n\n/**\n * Allows the global configuration of the active theme.\n *\n * Usage:\n *  ```ts\n *  import { configureTheme } from 'igniteui-webcomponents';\n *\n *  configureTheme('material', 'light');\n *  ```\n */\nexport function configureTheme(t: Theme, v: ThemeVariant = 'light'): void {\n  if (isOfTypeTheme(t) && isOfTypeThemeVariant(v)) {\n    setTheme(t, v);\n    dispatchThemingEvent({ theme, themeVariant });\n  }\n}\n"]}
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/theming/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,KAAK,CAAC;AAC/B,OAAO,EACL,kBAAkB,EAClB,mBAAmB,GAEpB,MAAM,oBAAoB,CAAC;AAG5B,MAAM,MAAM,GAAG,IAAI,GAAG,CAAU,CAAC,WAAW,EAAE,UAAU,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC;AAC/E,MAAM,cAAc,GAAG,IAAI,GAAG,CAAU,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC;AAE3D,IAAI,KAAY,CAAC;AACjB,IAAI,YAA0B,CAAC;AAE/B,SAAS,aAAa,CAAC,KAAc;IACnC,OAAO,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;AAC3B,CAAC;AAED,SAAS,oBAAoB,CAAC,KAAc;IAC1C,OAAO,cAAc,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;AACnC,CAAC;AAED,SAAS,QAAQ,CAAC,KAAY,EAAE,OAAqB;IACnD,KAAK,GAAG,KAAK,CAAC;IACd,YAAY,GAAG,OAAO,CAAC;AACzB,CAAC;AAOD,MAAM,mBAAoB,SAAQ,WAAW;IAC3C;QACE,KAAK,EAAE,CAAC;QACR,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,UAAU,CAAC,gBAAgB,CAAC,kBAAkB,EAAE,IAAI,CAAC,CAAC;QACxD,CAAC;IACH,CAAC;IAGM,WAAW,CAAC,EAAE,MAAM,EAAuC;QAChE,IACE,aAAa,CAAC,MAAM,EAAE,KAAK,CAAC;YAC5B,oBAAoB,CAAC,MAAM,EAAE,YAAY,CAAC,EAC1C,CAAC;YACD,QAAQ,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,YAAY,CAAC,CAAC;YAC5C,IAAI,CAAC,aAAa,CAAC,IAAI,WAAW,CAAC,mBAAmB,CAAC,CAAC,CAAC;QAC3D,CAAC;IACH,CAAC;CACF;AAED,MAAM,CAAC,MAAM,oBAAoB,GAAG,IAAI,mBAAmB,EAAE,CAAC;AAE9D,MAAM,UAAU,QAAQ;IACtB,IAAI,CAAC,CAAC,KAAK,IAAI,YAAY,CAAC,EAAE,CAAC;QAC7B,MAAM,UAAU,GAAG,QAAQ;YACzB,CAAC,CAAC,SAAS;YACX,CAAC,CAAC,gBAAgB,CAAC,QAAQ,CAAC,eAAe,CAAC,CAAC;QAC/C,MAAM,UAAU,GAAG,UAAU,EAAE,gBAAgB,CAAC,YAAY,CAAC,CAAC,IAAI,EAAE,CAAC;QACrE,MAAM,YAAY,GAAG,UAAU;YAC7B,EAAE,gBAAgB,CAAC,oBAAoB,CAAC;aACvC,IAAI,EAAE,CAAC;QAEV,KAAK,GAAG,aAAa,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,WAAW,CAAC;QAC7D,YAAY,GAAG,oBAAoB,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,OAAO,CAAC;IAC7E,CAAC;IAED,OAAO,EAAE,KAAK,EAAE,YAAY,EAAE,CAAC;AACjC,CAAC;AAYD,MAAM,UAAU,cAAc,CAAC,CAAQ,EAAE,IAAkB,OAAO;IAChE,IAAI,aAAa,CAAC,CAAC,CAAC,IAAI,oBAAoB,CAAC,CAAC,CAAC,EAAE,CAAC;QAEhD,QAAQ,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QAEf,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,UAAU,CAAC,aAAa,CACtB,IAAI,WAAW,CAAC,kBAAkB,EAAE;gBAClC,MAAM,EAAE,EAAE,KAAK,EAAE,YAAY,EAAE;aAChC,CAAC,CACH,CAAC;QACJ,CAAC;IACH,CAAC;AACH,CAAC","sourcesContent":["import { isServer } from 'lit';\nimport {\n  CHANGE_THEME_EVENT,\n  CHANGED_THEME_EVENT,\n  type ChangeThemeEventDetail,\n} from './theming-event.js';\nimport type { Theme, ThemeVariant } from './types.js';\n\nconst THEMES = new Set<unknown>(['bootstrap', 'material', 'indigo', 'fluent']);\nconst THEME_VARIANTS = new Set<unknown>(['light', 'dark']);\n\nlet theme: Theme;\nlet themeVariant: ThemeVariant;\n\nfunction isOfTypeTheme(value: unknown): value is Theme {\n  return THEMES.has(value);\n}\n\nfunction isOfTypeThemeVariant(value: unknown): value is ThemeVariant {\n  return THEME_VARIANTS.has(value);\n}\n\nfunction setTheme(value: Theme, variant: ThemeVariant): void {\n  theme = value;\n  themeVariant = variant;\n}\n\n/**\n * Relays \"igc-change-theme\" events from `window` to the theming controllers.\n * It also syncs the module state from the event detail, so an event from another\n * copy of the library changes the theme here too.\n */\nclass ThemeChangedEmitter extends EventTarget {\n  constructor() {\n    super();\n    if (!isServer) {\n      globalThis.addEventListener(CHANGE_THEME_EVENT, this);\n    }\n  }\n\n  /** @internal */\n  public handleEvent({ detail }: CustomEvent<ChangeThemeEventDetail>): void {\n    if (\n      isOfTypeTheme(detail?.theme) &&\n      isOfTypeThemeVariant(detail?.themeVariant)\n    ) {\n      setTheme(detail.theme, detail.themeVariant);\n      this.dispatchEvent(new CustomEvent(CHANGED_THEME_EVENT));\n    }\n  }\n}\n\nexport const _themeChangedEmitter = new ThemeChangedEmitter();\n\nexport function getTheme(): ChangeThemeEventDetail {\n  if (!(theme && themeVariant)) {\n    const rootStyles = isServer\n      ? undefined\n      : getComputedStyle(document.documentElement);\n    const foundTheme = rootStyles?.getPropertyValue('--ig-theme').trim();\n    const foundVariant = rootStyles\n      ?.getPropertyValue('--ig-theme-variant')\n      .trim();\n\n    theme = isOfTypeTheme(foundTheme) ? foundTheme : 'bootstrap';\n    themeVariant = isOfTypeThemeVariant(foundVariant) ? foundVariant : 'light';\n  }\n\n  return { theme, themeVariant };\n}\n\n/**\n * Allows the global configuration of the active theme.\n *\n * Usage:\n *  ```ts\n *  import { configureTheme } from 'igniteui-webcomponents';\n *\n *  configureTheme('material', 'light');\n *  ```\n */\nexport function configureTheme(t: Theme, v: ThemeVariant = 'light'): void {\n  if (isOfTypeTheme(t) && isOfTypeThemeVariant(v)) {\n    // Also set by the emitter's window listener, but that listener does not exist on the server.\n    setTheme(t, v);\n\n    if (!isServer) {\n      globalThis.dispatchEvent(\n        new CustomEvent(CHANGE_THEME_EVENT, {\n          detail: { theme, themeVariant },\n        })\n      );\n    }\n  }\n}\n"]}

package/theming/context.d.ts

@@ -7,29 +7,7 @@ export interface ThemeContext {
     variant: ThemeVariant;
 }
 /**
- * Context for providing theme information to descendant components.
- *
- * Components can consume this context to receive theme information from a theme provider
- * instead of relying on global theming events.
- *
- * @example
- * ```ts
- * // In a component
- * import { ContextConsumer } from '@lit/context';
- * import { themeContext } from './context.js';
- *
- * class MyComponent extends LitElement {
- *   private _themeConsumer = new ContextConsumer(this, {
- *     context: themeContext,
- *     subscribe: true
- *   });
- *
- *   render() {
- *     const theme = this._themeConsumer.value;
- *     // ...
- *   }
- * }
- * ```
+ * Theme context provided by the theme provider component and consumed by the theming controller.
  */
 export declare const themeContext: {
     __context__: ThemeContext;

package/theming/context.js.map

@@ -1 +1 @@
-{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/theming/context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAoC7C,MAAM,CAAC,MAAM,YAAY,GAAG,aAAa,CAAe,kBAAkB,CAAC,CAAC","sourcesContent":["import { createContext } from '@lit/context';\nimport type { Theme, ThemeVariant } from './types.js';\n\n/**\n * The theme context value.\n */\nexport interface ThemeContext {\n  theme: Theme;\n  variant: ThemeVariant;\n}\n\n/**\n * Context for providing theme information to descendant components.\n *\n * Components can consume this context to receive theme information from a theme provider\n * instead of relying on global theming events.\n *\n * @example\n * ```ts\n * // In a component\n * import { ContextConsumer } from '@lit/context';\n * import { themeContext } from './context.js';\n *\n * class MyComponent extends LitElement {\n *   private _themeConsumer = new ContextConsumer(this, {\n *     context: themeContext,\n *     subscribe: true\n *   });\n *\n *   render() {\n *     const theme = this._themeConsumer.value;\n *     // ...\n *   }\n * }\n * ```\n */\nexport const themeContext = createContext<ThemeContext>('ig-theme-context');\n"]}
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/theming/context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAc7C,MAAM,CAAC,MAAM,YAAY,GAAG,aAAa,CAAe,kBAAkB,CAAC,CAAC","sourcesContent":["import { createContext } from '@lit/context';\nimport type { Theme, ThemeVariant } from './types.js';\n\n/**\n * The theme context value.\n */\nexport interface ThemeContext {\n  theme: Theme;\n  variant: ThemeVariant;\n}\n\n/**\n * Theme context provided by the theme provider component and consumed by the theming controller.\n */\nexport const themeContext = createContext<ThemeContext>('ig-theme-context');\n"]}