Charts: fix color flicker on initial render

[kangzj]

Fixes https://linear.app/a8c/issue/CHARTS-168

Proposed changes:

Fix the color flicker issue in Conversion Funnel Chart (and other charts) where bars briefly show a red color (#813131) before switching to the correct theme color (#98C8DF).

Root Cause Analysis

When the GlobalChartsProvider component first renders, it needs a color palette to know what colors to use. The palette was being prepared in two steps:

Step 1: Component renders → colorCache = { colors: [] }  ← EMPTY!
Step 2: useLayoutEffect runs → colorCache = { colors: ['#98C8DF', ...] }  ← CORRECT!

The problem is that React renders the component BEFORE useLayoutEffect runs.

So on the first render:

• The code asks: "Give me color at index 0"
• It checks: Is 0 < 0? (is index less than array length?)
• Answer: No (because the array is empty!)
• So it falls back to generating a color using the golden ratio algorithm
• This generated color happens to be #813131 (a reddish color)

Then useLayoutEffect runs, populates the real colors, triggers a re-render, and now colors[0] returns #98C8DF.

The Fix

Add a fallback path in resolveColor that checks if colorCache is empty and uses raw theme hex colors directly:

const resolveColor = useCallback(({ group, index, overrideColor }) => {
  // ... override handling ...

  // Fallback for first render: if colorCache is not yet populated,
  // use raw theme hex colors directly to prevent color flicker
  const getRawThemeColor = (colorIndex: number): string | null => {
    if (colorCache.colors.length === 0) {
      const themeColor = providerTheme.colors?.[colorIndex];
      if (themeColor?.startsWith('#')) {
        return themeColor;
      }
    }
    return null;
  };

  // Use fallback if available, otherwise use normal color resolution
  return getRawThemeColor(index) ?? getChartColor(index, colorCache);
}, [colorCache, groupToColorMap, providerTheme.colors]);

Now on the first render, when colorCache is empty, we fall back to the raw theme colors directly. No flicker!

Why useLayoutEffect Still Exists

Some colors might be CSS variables like var(--my-color). These can't be resolved until the DOM exists. So useLayoutEffect handles those cases, but for normal hex colors, the fallback provides immediate access.

Other information:

• Have you written new tests for your changes, if applicable?
• Have you checked the E2E test CI results, and verified that your changes do not break them?
• Have you tested your changes on WordPress.com, if applicable (if so, you'll see a generated comment below with a script to run)?

Testing instructions:

1. Go to projects/js-packages/charts
2. Run pnpm storybook (or from monorepo root: pnpm --filter @automattic/charts storybook)
3. Navigate to any Conversion Funnel Chart story
4. Observe that the chart loads without flickering from red to blue
5. Previously, you would see a brief flash of #813131 (red) before settling on #98C8DF (blue)

[github-actions]

Are you an Automattician? Please test your changes on all WordPress.com environments to help mitigate accidental explosions.

• To test on WoA, go to the Plugins menu on a WoA dev site. Click on the "Upload" button and follow the upgrade flow to be able to upload, install, and activate the Jetpack Beta plugin. Once the plugin is active, go to Jetpack > Jetpack Beta, select your plugin (Jetpack), and enable the fix/charts-color-flicker branch.
• To test on Simple, run the following command on your sandbox:

bin/jetpack-downloader test jetpack fix/charts-color-flicker

Interested in more tips and information?

• In your local development environment, use the jetpack rsync command to sync your changes to a WoA dev blog.
• Read more about our development workflow here: PCYsg-eg0-p2
• Figure out when your changes will be shipped to customers here: PCYsg-eg5-p2

[github-actions]

Thank you for your PR!

When contributing to Jetpack, we have a few suggestions that can help us test and review your patch:

• ✅ Include a description of your PR changes.
  
• ✅ Add a "[Status]" label (In Progress, Needs Review, ...).
  
• ✅ Add testing instructions.
  
• 🔴 Specify whether this PR includes any changes to data or privacy.
  
• ✅ Add changelog entries to affected projects
  

This comment will be updated as you work on your PR and make changes. If you think that some of those checks are not needed for your PR, please explain why you think so. Thanks for cooperation 🤖

---

🔴 Action required: We would recommend that you add a section to the PR description to specify whether this PR includes any changes to data or privacy, like so:

## Does this pull request change what data or activity we track or use?

My PR adds *x* and *y*.

---

Follow this PR Review Process:

1. Ensure all required checks appearing at the bottom of this PR are passing.
2. Make sure to test your changes on all platforms that it applies to. You're responsible for the quality of the code you ship.
3. You can use GitHub's Reviewers functionality to request a review.
4. When it's reviewed and merged, you will be pinged in Slack to deploy the changes to WordPress.com simple once the build is done.

If you have questions about anything, reach out in #jetpack-developers for guidance!

[Copilot]

Pull request overview

This PR fixes a visual bug where chart colors briefly flicker from an incorrect red color (#813131) to the correct theme color (e.g., #98C8DF) during the initial render of the Conversion Funnel Chart and other charts.

Changes:

• Pre-compute hex colors synchronously in the useState initializer to populate the color cache before the first render
• Retain the useLayoutEffect to handle CSS variable resolution after DOM is ready
• Add changelog entry documenting the fix

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.

File	Description
projects/js-packages/charts/src/providers/chart-context/global-charts-provider.tsx	Modified useState initializer to pre-compute hex colors synchronously, preventing color flicker on initial render
projects/js-packages/charts/changelog/fix-charts-color-flicker	Added changelog entry documenting the fix

[Copilot]

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated 4 comments.

[Copilot]

The getRawThemeColor function is defined inside the useCallback for resolveColor, which means it gets recreated on every render. This is inefficient and goes against the purpose of using useCallback for performance optimization.

Consider moving this function outside of the useCallback, or better yet, implementing the solution described in the PR description: pre-computing hex colors directly in the useState initializer. This would eliminate the need for this runtime fallback function entirely and would be more performant.

[kangzj]

Copilot has a point about the function being recreated. However, getRawThemeColor is only created when resolveColor itself is recreated (when dependencies change), not on every render. The performance impact is minimal.

[jp-launch-control]

Code Coverage Summary

Coverage changed in 1 file.

File	Coverage	Δ%	Δ Uncovered
projects/js-packages/charts/src/providers/chart-context/global-charts-provider.tsx	91/91 (100.00%)	0.00%	0 💚

Full summary · PHP report · JS report

[Copilot]

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated no new comments.