apexgrid-skill 2.4.0 → 2.5.0

package/.cursorrules

@@ -4,7 +4,7 @@ You are working with `apex-grid`, a Lit-based web-component data grid by ApexCha
 Documentation: https://github.com/apexcharts/apexgrid
 NPM: apex-grid (with a hyphen — no `apexgrid` package exists)
 GitHub: https://github.com/apexcharts/apexgrid
-Confirmed versions: apex-grid@3.6.0, lit@^3.0.0
+Confirmed versions: apex-grid@3.6.0, lit@^3.0.0 (Ignite UI add-on: apex-grid@4.0.0-beta.2, npm `next` tag only)
 
 ## Quickstart — register + size the host
 
@@ -17,7 +17,11 @@ height or it collapses and renders nothing. `setup()` handles both.
 npm install apex-grid lit
 ```
 That is the whole install: `apex-grid` brings `lit`, `@lit/context` and `@lit-labs/virtualizer`.
-There is no theme CSS to import from anywhere (3.5.0 dropped the old Ignite UI dependencies).
+There is no theme CSS to import for a styled grid (3.5.0 dropped the old `igniteui-webcomponents`
+dependency). An Ignite UI theme never fully themed the grid: 3.x only took its brand and font. From
+4.0 the only way to follow an Ignite UI theme is the free `apex-grid/ignite-ui` add-on, in 4.0 only
+(`npm install apex-grid@next`, 4.0.0-beta.2; plain `npm install apex-grid` gets 3.6.0 without it;
+see "Ignite UI theming" below).
 
 ### 2. Register + size — `setup()` does both
 ```ts
@@ -40,6 +44,28 @@ and IGNORES the light ones (`--ag-surface`, ...), even when set on the dark grid
 Brand, sizing and typography tokens are shared. In your own CSS, `var(--ag-brand)` has no
 root default: write `var(--ag-brand, #0d6fd3)`.
 
+### Ignite UI theming (apex-grid 4.0.0-beta.2, npm `next` tag only)
+Not in 3.6.0 (what `npm install apex-grid` installs): `npm install apex-grid@next` first
+(`apex-grid-enterprise@next`, 0.9.0-beta.2, if you use it). 4.0 has other breaking changes (body rows
+recycled by default via `rowRecycling`, grid role moved off the host); check the CHANGELOG.
+`import 'apex-grid/ignite-ui';` once (free, no licence key; ES modules only, no script-tag file).
+Every grid on the page, shadow roots included, then follows the Ignite UI theme: brand, text,
+gridlines, pinned edge, header (`--ig-surface-raised`, 7.5+), state colours, font, enterprise popups.
+- Ranking: `--ag-*` you set > family `--apx-*` tokens > Ignite UI > built-in values
+  (family-wide: explicit option > product CSS variable > `--apx-*` > named theme/palette > `--ig-*` > defaults).
+- Mode: no `theme` attribute follows `--ig-theme-variant` live; `theme="light"`/`"dark"` pins the mode
+  (a pinned `light` blocks the dark variant).
+- Per grid: `design-system="off"` (`designSystem = false`) drops the Ignite UI colours and font;
+  `tokens="off"` (`tokens = false`) drops `--apx-*` and Ignite UI, variant included.
+- Live: no `refreshTokens()` needed. With the add-on, the Ignite-following tokens leave the root
+  defaults: page CSS reading them needs a fallback, `var(--ag-text, #111827)`.
+- New tokens `--ag-overlay`, `--ag-overlay-text` (dark: `--ag-dark-overlay`, `--ag-dark-overlay-text`)
+  colour the enterprise popups (apex-grid-enterprise 0.9.0-beta.2); no default.
+- `--ag-font` you set now wins over family and Ignite UI fonts and has no root default: `var(--ag-font, Inter, sans-serif)`.
+- BREAKING (4.0): the grid no longer reads `--ig-*` by itself (3.x took the brand and font with no
+  import). Without the add-on an Ignite UI stylesheet changes nothing. The 4.0 grid also follows
+  `--apx-*` set on `:root`.
+
 ### Minimal example
 
 ```ts
@@ -234,7 +260,8 @@ Built-in pipeline is skipped for whichever operations have a hook. Omit one to k
 
 ### 3. Importing a theme CSS that no longer exists
 ❌ `import 'igniteui-webcomponents/themes/.../bootstrap.css'` + `configureTheme(...)` — obsolete; no effect.
-✅ No import needed — grid self-styles; retheme via `--ag-*`. The only required CSS is host height.
+✅ No import needed for a styled grid; retheme via `--ag-*`. The only required CSS is host height.
+To follow an Ignite UI theme, `import 'apex-grid/ignite-ui'` (4.0 only: `apex-grid@next`), not a theme import.
 
 ### 4. Stringified attribute
 ❌ `<apex-grid columns="[...]">`
@@ -268,6 +295,12 @@ Built-in pipeline is skipped for whichever operations have a hook. Omit one to k
 ❌ `import ... from 'apexgrid'` — no such package.
 ✅ `import ... from 'apex-grid'`.
 
+### 12. Ignite UI theme without the add-on (4.0)
+❌ Ignite UI stylesheet on the page, no `apex-grid/ignite-ui`: `--ig-*` is silently ignored in 4.0.
+❌ `theme="light"` on the grid while the page switches to a dark Ignite UI theme: blocks the dark variant.
+❌ `import 'apex-grid/ignite-ui'` after a plain `npm install apex-grid` (3.6.0): no such module.
+✅ `npm install apex-grid@next`, `import 'apex-grid/ignite-ui'` once and leave `theme` unset.
+
 ---
 
 ## New in 3.1–3.3

package/README.md

@@ -20,7 +20,7 @@ AI models routinely get web-component grid code wrong: they treat `<apex-grid>`
 
 ### Coverage
 
-- **Quickstart** — register + size the host (`setup()` does both); no theme import — the grid self-styles via `--ag-*` CSS variables
+- **Quickstart**: register + size the host (`setup()` does both); no theme import, since the grid self-styles via `--ag-*` CSS variables; the free `apex-grid/ignite-ui` add-on (apex-grid 4.0 only, now `4.0.0-beta.2` on the npm `next` tag) follows an Ignite UI theme
 - **Custom-element registration** — `setup()`, `import 'apex-grid/define'`, or `ApexGrid.register()`
 - **Generic `ColumnConfiguration<T>`** — `key`, the 13 column `type`s (incl. `date`, `select`, `currency`, …), templates, `sort`, `filter`, `pinned`, explicit widths
 - **Lit cell, header & editor templates** with the right context shapes

package/SKILL.md

@@ -5,7 +5,9 @@ description: >
   data grid by ApexCharts). Use whenever the user asks to create, configure, or
   troubleshoot a sortable / filterable / paginated / editable / virtualized data
   table with `<apex-grid>`. Covers the register-and-size setup (no theme import —
-  the grid styles itself via `--ag-*` CSS variables), the generic
+  the grid styles itself via `--ag-*` CSS variables), the optional free
+  `apex-grid/ignite-ui` add-on that follows an Ignite UI theme (apex-grid 4.0
+  pre-release only, `apex-grid@next`), the generic
   `ColumnConfiguration<T>` shape with its 13 column types, Lit `cellTemplate`
   requirements, theming and dark mode (`--ag-*` / `--ag-dark-*` tokens,
   `theme="dark"`), sorting / filtering / quick-filter, pagination, inline
@@ -14,7 +16,7 @@ description: >
   `dataPipelineConfiguration` hooks for server-side data.
 metadata:
   author: ApexCharts
-  version: "2.4.0"
+  version: "2.5.0"
   library_version: "3.6.0"
   category: data-visualization
   tags: [grid, data-grid, table, web-component, lit, apex-grid]
@@ -37,9 +39,9 @@ npm install apex-grid lit
 
 That is the whole install. `apex-grid` brings its own runtime dependencies (`lit`, `@lit/context`, `@lit-labs/virtualizer`) and there is **no theme CSS to import** from anywhere.
 
-> **Changed in 3.5.0:** earlier versions also pulled in `igniteui-webcomponents` and `igniteui-theming` transitively. Both are gone. The grid never registered an Ignite UI element, so nothing you wrote against the grid is affected, but code that relied on `igc-*` elements being installed as a side effect must now depend on that package directly.
+> **Changed in 3.5.0:** earlier versions also pulled in `igniteui-webcomponents` and `igniteui-theming` transitively. Both are gone. The grid never registered an Ignite UI element, so nothing you wrote against the grid is affected, but code that relied on `igc-*` elements being installed as a side effect must now depend on that package directly. An Ignite UI theme on the page never fully themed the grid: through 3.x it only tinted the brand and replaced the font. From 4.0 the only way to make the grid follow an Ignite UI theme is the `apex-grid/ignite-ui` add-on, which exists only in apex-grid 4.0 (in pre-release as `4.0.0-beta.2` on the npm `next` tag, §1.3).
 
-> Confirmed working versions: `apex-grid@3.6.0`, `lit@^3.0.0`.
+> Confirmed working versions: `apex-grid@3.6.0`, `lit@^3.0.0`. The `apex-grid/ignite-ui` add-on (§1.3) is the exception: it exists only in `apex-grid@4.0.0-beta.2`, installed with `npm install apex-grid@next`. Plain `npm install apex-grid` gets 3.6.0, which has no add-on.
 
 ### 1.2 Register the element + size the host — `setup()` does both
 
@@ -100,7 +102,34 @@ apex-grid[theme~='dark'] { --ag-grid-shadow: var(--ag-dark-shadow-card); } /* th
 
 **CSS parts.** Since 3.6.0 every part a body row renders is reachable with `apex-grid::part(...)`: `cell`, `selection-cell`, `selection-checkbox`, `expansion-cell`, `expansion-toggle`, `expansion-chevron`, `detail-panel`, `row-number-cell`, `row-number`, `reorder-handle-cell`, `reorder-handle`, `reorder-grip`. Before, only `cell` was. Parts inside your own `detailTemplate` content are reached by listing them in `expansion.exportParts` (`references/state-and-features.md`).
 
-> The deprecated `setup({ theme })` option does **not** change the grid's appearance. It only ever forwarded to Ignite UI's `configureTheme()`, and since 3.5.0 it is inert and warns once. Omit it; use `--ag-*` variables (and the `theme="dark"` attribute) instead.
+> The deprecated `setup({ theme })` option does **not** change the grid's appearance. It only ever forwarded to Ignite UI's `configureTheme()`, and since 3.5.0 it is inert and warns once. Omit it; use `--ag-*` variables (and the `theme="dark"` attribute) instead, and to follow an Ignite UI theme, the `apex-grid/ignite-ui` add-on below.
+
+**Ignite UI theming (apex-grid 4.0 pre-release only: `4.0.0-beta.2` on the npm `next` tag).** The add-on is not in 3.6.0, the version `npm install apex-grid` installs, and `import 'apex-grid/ignite-ui'` does not resolve there. Install the pre-release first:
+
+```bash
+npm install apex-grid@next lit            # apex-grid 4.0.0-beta.2
+npm install apex-grid-enterprise@next      # only if you use it: 0.9.0-beta.2, needs the 4.0 beta
+```
+
+4.0 is a major version with other breaking changes besides theming (body rows are recycled by default through `rowRecycling`; the grid role and ARIA attributes moved off the host onto the inner `[part~="table"]` element), so read the package CHANGELOG before moving an app to it. The rest of this skill describes 3.6.0.
+
+To make grids follow an Ignite UI theme loaded on the page, import the add-on once. It is free and needs no licence key.
+
+```ts
+import 'apex-grid/ignite-ui';
+```
+
+Every grid on the page, in the document or any shadow root, then follows the theme, including grids that connected before the import: the brand (`--ig-primary-*`), text and muted text, gridlines and the pinned-column edge, the header (`--ig-surface-raised`, Ignite UI 7.5+), the state colours, the font, and the `apex-grid-enterprise` popups (`--ig-surface-overlay`, 7.5+). Card and row surfaces keep the grid's own light or dark background. The add-on registers on a shared `globalThis` slot, so it reaches grids from a separately built bundle too. The grid ships as ES modules only: load it from your bundle or a `<script type="module">`.
+
+- **Ranking**, highest first: an `--ag-*` token you set > the family `--apx-*` tokens (`--apx-accent`, `--apx-fore`, `--apx-grid`, `--apx-surface`, `--apx-font-family`, `--apx-radius-factor`, also new in that release) > Ignite UI > built-in values. (Across the Apex family: explicit option > product CSS variable > `--apx-*` > named theme/palette > `--ig-*` > defaults.)
+- **Mode:** a grid without a `theme` attribute follows the Ignite UI variant (`--ig-theme-variant`) declared on `:root` or an ancestor, live, on a theme swap too. `theme="light"` keeps a grid light and `theme="dark"` keeps it dark, so do not pin `theme="light"` if the grid should go dark with a dark Ignite UI theme.
+- **Per grid:** `design-system="off"` (property `designSystem = false`) turns the Ignite UI colours and font off (the variant still picks the mode); `tokens="off"` (`tokens = false`) turns off the `--apx-*` tokens and Ignite UI together, the variant included, for the grid and the content it renders.
+- **No `refreshTokens()` needed:** the grid follows the cascade live.
+- **Your own CSS:** while the add-on is loaded, the tokens that follow Ignite UI (text, lines, surfaces, header, state colours, pinned edge) leave the root defaults, so page CSS that reads one needs its own fallback: `var(--ag-text, #111827)`.
+- **Enterprise popups:** new tokens `--ag-overlay` and `--ag-overlay-text` (dark grids: `--ag-dark-overlay`, `--ag-dark-overlay-text`) colour the `apex-grid-enterprise` popups (apex-grid-enterprise `0.9.0-beta.2`, also on `next`); unset, each keeps its built-in colours. For the enterprise chart panel to read the theme itself, also import `apexcharts/features/ignite-ui` (ApexCharts 8.8.0 or later; the grid never loads it).
+- **`--ag-font`:** in 4.0 an `--ag-font` you set wins over the family and Ignite UI fonts, and it no longer has a root default (the built-in Inter stack is unchanged inside the grid), so page CSS that reads it needs a fallback, as with `--ag-brand`.
+
+> **Breaking in 4.0 (already in `4.0.0-beta.2`):** the grid no longer reads Ignite UI tokens by itself. Through 3.x an Ignite UI theme on the page re-tinted the brand (`--ig-primary-500`, `--ig-primary-700`) and replaced the font (`--ig-font-family`) with no import. From 4.0 an Ignite UI stylesheet changes nothing until you `import 'apex-grid/ignite-ui'`, which brings the brand and font back along with the rest of the theme. The 4.0 grid also follows the family `--apx-*` tokens: a page that sets them on `:root` for its charts sees the grid follow them too (set the matching `--ag-*` tokens to keep the grid as it was).
 
 ### 1.4 Minimal example — a styled, sortable, filterable table
 
@@ -467,7 +496,7 @@ Arrow-key navigation, column resize and column reorder all follow inline order r
 
 ### 3. Importing a theme CSS that no longer exists
 ❌ `import 'igniteui-webcomponents/themes/light/bootstrap.css'` + `setup({ theme: 'bootstrap' })` is obsolete; it never affected the grid, and as of 3.5.0 the option is inert and that package is not even installed.
-✅ Nothing to import — the grid styles itself; retheme via `--ag-*` CSS variables. The only required CSS is a host **height**.
+✅ Nothing to import for a styled grid: it styles itself; retheme via `--ag-*` CSS variables. The only required CSS is a host **height**. To follow an Ignite UI theme that the page loads, the path is the `apex-grid/ignite-ui` add-on (apex-grid 4.0 only, `npm install apex-grid@next` while it is in pre-release, §1.3), not a theme import into the grid.
 
 ### 4. Stringified `columns` attribute
 ❌ `<apex-grid columns="[...]">` — becomes the literal string `"[object Object],..."`.
@@ -505,6 +534,10 @@ Arrow-key navigation, column resize and column reorder all follow inline order r
 ❌ `apex-grid[theme='dark'] { --ag-surface: #111827; --ag-text: #f9fafb; }`: since 3.6 a dark grid ignores the light colour tokens, even on its own element.
 ✅ `apex-grid { --ag-dark-surface: #111827; --ag-dark-text: #f9fafb; }` (or on any ancestor). Brand, sizing and typography tokens are shared, so `--ag-brand` still applies to both.
 
+### 13. Expecting an Ignite UI theme to restyle the grid without the add-on (4.0)
+❌ Loading an Ignite UI theme stylesheet and expecting the 4.0 grid to follow it: without `apex-grid/ignite-ui` every `--ig-*` token is silently ignored (3.x picked up the brand and font on its own; 4.0 does not). Also ❌ `theme="light"` on a page that switches to a dark Ignite UI theme: the pinned mode blocks the dark variant. Also ❌ `import 'apex-grid/ignite-ui'` after a plain `npm install apex-grid`: that installs 3.6.0, which has no such module.
+✅ `npm install apex-grid@next` (4.0.0-beta.2), then `import 'apex-grid/ignite-ui'` once (free, no licence key) and leave the `theme` attribute off so the grid follows `--ig-theme-variant`. Use `design-system="off"` or `tokens="off"` to opt one grid out.
+
 ---
 
 ## 7. Reference Routing Table

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apexgrid-skill",
-  "version": "2.4.0",
+  "version": "2.5.0",
   "description": "AI coding skill for the apex-grid web component — structured reference docs that help AI assistants (Claude, Cursor, Copilot, etc.) generate correct apex-grid code.",
   "keywords": [
     "apex-grid",

package/references/framework-integration.md

@@ -239,7 +239,8 @@ export class UsersGridComponent implements OnInit {
 | ❌ | ✅ |
 |---|---|
 | Forgetting to register the element | Top-level `import 'apex-grid/define'` once in the app entry |
-| Importing an Ignite UI theme + `configureTheme(name)` | Obsolete — the grid self-styles; retheme via `--ag-*` CSS variables. No import does anything for appearance |
+| Importing an Ignite UI theme + `configureTheme(name)` | Obsolete: the grid self-styles; retheme via `--ag-*` CSS variables. To follow an Ignite UI theme on the page, `import 'apex-grid/ignite-ui'` once in the app entry (apex-grid 4.0 only: `npm install apex-grid@next` while it is in pre-release; free). Without it the 4.0 grid ignores `--ig-*` |
+| Pinning `theme="light"` on a page with a dark Ignite UI theme | Leave the `theme` attribute off so the grid follows `--ig-theme-variant`; `design-system="off"` / `tokens="off"` opt one grid out |
 | Forgetting `setup()` / no host-height rule for `apex-grid` | `setup()` registers + sizes the host. Or `import 'apex-grid/define'` + `apex-grid { height: ... }` (never set `display` — it overrides the component's `:host { display: grid }`) |
 | Vue: `:data="data"` (attribute, becomes `"[object Object]"`) | `:data.prop="data"`, or set via `ref` in `onMounted` |
 | React: `<apex-grid columns={[...]}>` before React 19 | Use `ref` + `useEffect` to set as property |