@genesislcap/grid-pro 15.21.1 → 15.22.1

package/.cursor/rules/ag-embedded-components.mdc

@@ -0,0 +1,83 @@
+---
+description: - When creating or editing an AG Grid embedded component in grid-pro (column filter, floating filter, tooltip, status panel), When styling such a component, When deciding between a plain class and a FAST FoundationElement, When wiring components into combineAllGridComponents or schema fallbacks
+globs:
+  - "src/column-filters/**"
+  - "src/status-bar-components/**"
+  - "src/tooltips/**"
+  - "src/cell-editors/**"
+  - "src/cell-renderers/**"
+  - "src/grid-pro-beta.ts"
+alwaysApply: false
+---
+# AG-embedded components: class model and styling
+
+> **Purpose**: grid-pro embeds two different kinds of components into AG Grid, and mixing up
+> their rules produces runtime crashes ("Illegal constructor") or styling hacks that were already
+> tried and reverted (an inject-styles helper with a rAF retry — see PR #2498, removed in commit
+> `223771156`). Reference implementations: `src/column-filters/enum-column.filter.ts` (plain
+> class) and `src/cell-editors/select.editor.ts` (FoundationElement).
+
+## Rule 1 — pick the right class model
+
+**Auto-wired components** — anything the grid registers unconditionally in
+`combineAllGridComponents` or swaps in itself (e.g. the schema filter fallbacks in
+`GridProBeta.applyCommunityFilterFallbacks`): column filters, floating filters, tooltips, status
+panels.
+
+- MUST be plain classes implementing the AG interface (`IFilterComp`, `IFloatingFilterComp`,
+  `ITooltipComp`, `IStatusPanelComp`).
+- MUST NOT extend `FoundationElement` (or any custom element). AG instantiates components with
+  `new`, and constructing a custom element that no design system has registered throws
+  `Illegal constructor`. Auto-wired components must work with **zero registration** — a
+  registration requirement recreates exactly the missing-module crash (AG error #200/#256) the
+  enum filter exists to remove.
+
+**Opt-in components** — editors/renderers a consumer references deliberately (`selectEditor`,
+`statusPill`, ...):
+
+- These are FAST `FoundationElement`s composed with template + styles and registered per design
+  system (foundation/zero/rapid). Follow the existing `cell-editors`/`cell-renderers` pattern,
+  including exposure via `grid-components.ts`.
+
+## Rule 2 — style plain components with FAST css in their own shadow root
+
+```ts
+const styles = css`
+  :host { /* container styles — the host element */ }
+  .my-part { /* inner parts by class */ }
+`;
+
+this.eGui = document.createElement('div');
+this.eRoot = this.eGui.attachShadow({ mode: 'open' });
+styles.addStylesTo(this.eRoot); // one constructable sheet, shared by every instance
+```
+
+- The stylesheet travels with the element wherever AG attaches it, works while detached, and is
+  parsed once regardless of how many columns use the component.
+- Theme with `--ag-*` custom properties (they inherit through shadow boundaries); always give
+  them fallbacks.
+
+**Never**:
+
+- append a `<style>` element per instance (duplicated per column, per popup open);
+- inject styles into an ancestor root (`document.head` or the grid's shadow root). The grid
+  lives inside a design-system shadow root, so document styles don't reach it — and floating
+  filters get **no attach hook** from AG, so injection-on-attach degenerates into
+  `requestAnimationFrame` retry loops. This was implemented and reverted; don't reintroduce it.
+
+## Gotchas that already bit
+
+- Listen for keyboard/DOM events on the **shadow root**, not the host — events retarget at the
+  shadow boundary, so a host listener sees `event.target === host` instead of the real control.
+- AG's popup focus trap collects focusable elements with `querySelectorAll`, which does not
+  pierce a shadow root — a shadow-DOM popup component must trap Tab/Shift-Tab itself (see
+  `EnumColumnFilter.handleKeyDown`). Escape still reaches AG's popup handling, because keyboard
+  events are composed and bubble out of the root.
+- On selection/state changes, update existing DOM in place instead of rebuilding lists —
+  rebuilding drops keyboard focus mid-interaction.
+- `afterGuiAttached` is only called for filter popups. Floating filters, tooltips, and status
+  panels must be fully correct (styles included) straight out of `init()`.
+- Tests: query content via `component.getGui().shadowRoot`, and read focus via
+  `shadowRoot.activeElement` (not `document.activeElement`, which reports the host).
+- Render user-visible state as real text, not CSS `content` — generated content is invisible to
+  screen readers.