Sitelet https://github.com/ag-grid/ag-grid/pull/14951
Skip to content

AG-18256 Apply the docs example colour scheme before the example runs (integrated-charts dark mode) - #14951

Merged
sdwvit merged 1 commit into
b36.1.0from
ag-18256/example-colour-scheme-b36.1.0
Aug 25, 2026
Merged

AG-18256 Apply the docs example colour scheme before the example runs (integrated-charts dark mode)#14951
sdwvit merged 1 commit into
b36.1.0from
ag-18256/example-colour-scheme-b36.1.0

Conversation

@sdwvit

@sdwvit sdwvit commented Aug 25, 2026

Copy link
Copy Markdown
Contributor

Backport of #14917 to b36.1.0 (cherry-pick of 6a81bdd).

Fix AG-18256

… (integrated-charts dark mode) (#14917)

* AG-18256 - Apply the example colour scheme before the example runs

Integrated-charts docs examples rendered a light chart inside a dark grid, or
flickered light-then-dark. The example page's `data-ag-theme-mode` was only ever
written by the parent frame's iframe `load` handler, which runs after the
example's deferred entry module has already created its grid and chart.

- Carry the resolved colour scheme on the example iframe `src` as
  `?agThemeMode=`, composed by a pure `withThemeMode()` helper at src-assignment
  only, so the re-navigation guard (which compares pathnames) still matches and a
  dark-mode toggle does not reload the example. Omitted when `suppressDarkMode`.
- Apply it synchronously in `example-runner.js` `setUpPage()`, before any example
  module runs.
- Make the generator-injected chart-theme snippet read the theme mode at apply
  time and wait for it, register its `color-scheme-change` listener before the
  initial apply, and no-op when the theme list is unchanged.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* AG-18256 - Pin the generator dark-mode snippet's apply-time contract

The typescript and javascript bodies of the injected chart dark-mode code are
maintained separately, so a change applied to only one is a silent half-fix
across frameworks. Assert both read the theme mode at apply time, wait for it
alongside the grid api, register the listener before the initial apply, and skip
an unchanged theme list.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* AG-18256 - Keep the light-mode fallback and re-point in-flight example navigations

* AG-18256 - Cover the light-mode fallback and the in-flight navigation re-point

* AG-18256 - Format

* AG-18256 - Cover the example url's colour scheme with a docs e2e regression test

* AG-18256 Chart themes follow the grid's colour scheme

Integrated charts render to a canvas, so they cannot inherit the grid's
colour scheme from CSS. Without chartThemes the stock light themes were
used regardless, leaving a dark grid beside a light chart.

The scheme is resolved by painting --ag-background-color onto an
off-screen probe and reading the computed value back, because the
theming API emits that variable as authored (hsl(), color-mix(), var()
chains) and it is not readable as text.

The example spec now samples the rendered chart canvas rather than the
chartThemes option, which the example's own dark-mode code sets.

* AG-18256 - Format

* AG-18256 - Revert the chart-theme colour-scheme change to grid code

Out of scope for a website regression ticket. The docs fix stands on its
own: the runner applies the colour scheme before the entry module runs and
the generated example snippet sets the dark chart themes itself.

Tracked separately as an improvement to the grid.

* AG-18256 - Remove the explanatory comments

---------

Co-authored-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-authored-by: sdwvit <victor.musienko@ag-grid.com>
Co-authored-by: Victor Musienko <8777372+sdwvit@users.noreply.github.com>
(cherry picked from commit 6a81bdd)
@sdwvit sdwvit self-assigned this Aug 25, 2026
@sonarqubecloud

Copy link
Copy Markdown

nextSrc: string;
pendingSrc?: string;
}): boolean => {
if (currentPathname !== url) {

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ℹ️ [P2] Navigation guard compares a pathname with an unparsed URL

currentPathname contains only the path, while url may include an existing query string or fragment (which withThemeMode explicitly supports). Such URLs never compare equal, so every dark-mode change reruns the iframe navigation and loses the example's interactive state instead of relying on the colour-scheme message. Compare against new url(/sitelet?url=https%3A%2F%2Fgithub.com%2Fag-grid%2Fag-grid%2Fpull%2Furl%2C%2520base).pathname, or compare consistently normalised full URLs.

@github-actions

Copy link
Copy Markdown
Contributor

✅ Codex review complete; 1 issue found (P0: 0 | P1: 0 | P2: 1 | P3: 0)

View full review

AG-18256 Apply the docs example colour scheme before the example runs (integrated-charts dark mode)

PR: #14951
Author: sdwvit | Base: b36.1.0 ← Head: ag-18256/example-colour-scheme-b36.1.0
Diff: 8 files changed, +267 -45

Summary

This PR propagates the initial documentation colour scheme into example iframes and generated integrated-chart themes, with supporting tests.

Findings

P0: 0 | P1: 0 | P2: 1 | P3: 0

1 of 1 finding(s) also posted inline; all findings are listed below.

ℹ️ [P2] Navigation guard compares a pathname with an unparsed URL

documentation/ag-grid-docs/src/components/example-runner/components/exampleThemeMode.ts:28

currentPathname contains only the path, while url may include an existing query string or fragment (which withThemeMode explicitly supports). Such URLs never compare equal, so every dark-mode change reruns the iframe navigation and loses the example's interactive state instead of relying on the colour-scheme message. Compare against new url(/sitelet?url=https%3A%2F%2Fgithub.com%2Fag-grid%2Fag-grid%2Fpull%2Furl%2C%2520base).pathname, or compare consistently normalised full URLs.

Verdict

Assessment: correct
Confidence: 0.9

The initial theme propagation and chart-theme retry logic are coherent, but the pathname comparison can cause unnecessary iframe reloads for parameterised example URLs.

Required Actions:

  • Normalise the example URL before comparing it with the iframe pathname.

@github-actions

Copy link
Copy Markdown
Contributor

Live-test this PR in Plunker

Paste these two <script> tags into a Plunker (or any vanilla-JS host) to load the UMD bundles built from this PR:

<script src="https://ag-grid.github.io/ag-grid/pr-14951/ag-grid-community.min.js"></script>
<script src="https://ag-grid.github.io/ag-grid/pr-14951/ag-grid-enterprise.min.js"></script>

Bundles are removed automatically when the PR is closed. Updated on every push.

@sdwvit
sdwvit merged commit caacedf into b36.1.0 Aug 25, 2026
28 checks passed
@sdwvit
sdwvit deleted the ag-18256/example-colour-scheme-b36.1.0 branch August 25, 2026 13:57
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants