feat: add gdocs component for bespoke viz by marcelgerber · Pull Request #6050 · owid/owid-grapher

marcelgerber · 2026-02-03T13:02:54Z

Adds a {.bespoke-component} component.

It has an in-code registry of component "bundles" (which are just pointers to JS & CSS URLs), and the JS entrypoint needs to export a

mount: (
    container: HTMLElement,
    opts: { variant?: string; config: Record<string, unknown> }
)

method.

The component is a client-only component; it currently doesn't do anything before hydration and just renders an (infinite) loading indicator.

What is `variant`?

The variant is an optional pointer for multiple visualizations to be part of the same bundle, but to be embedded in different spots inside the gdoc - but still being able to share state.
In theory, this could also be achieved by just using config, but I feel like it's a common-enough use case that we want to have an "approved" way to do this.

How this works

Technically, we load the JS file using dynamic await, and then call mount on a div we create inside of a Shadow DOM.
The CSS is also loaded into the Shadow DOM, and thus the bespoke component is fully encapsulated when it comes to CSS.

Drawbacks of Shadow DOM

This creates a bunch of small problems also, though: We need to use :host rather than :root inside the CSS to define global variables, and need to ensure that any code that mounts elements inside portals (e.g. tooltip code like floating-ui in my case) mounts its element inside the Shadow DOM, because if it gets mounted outside it doesn't have CSS styles.

Try it out

You can preview this here (this is the doc)

In the demo, you can easily see how the two charts are connected in state. It's easy to disconnect their state (but the bespoke implementation needs to handle that), but the ability to have them connected is really useful in some of our use cases.

TODOs

Remove test component before merging
Make the error message display more end-user-friendly

Open questions

What's a good way to support sizing, and avoid layout reflows?
What changes would we need to make to allow for articles containing bespoke components to be archived?
Should we remove the .script component now?
Should we add a way to mount a component without using Shadow DOM (as an option in the component registry; we can also easily do this later on)?

Screenshot

owidbot · 2026-02-03T13:03:53Z

Quick links (staging server):

Site Dev	Site Preview	Admin	Wizard	Docs

Login: ssh owid@staging-site-gdocs-bespoke-component

Site-screenshots: https://github.com/owid/site-screenshots/compare/gdocs-bespoke-component
SVG tester: https://github.com/owid/owid-grapher-svgs/compare/gdocs-bespoke-component

Archive:

SVG tester:

Number of differences (graphers): 0 ✅
Number of differences (grapher views): skipped
Number of differences (mdims): skipped
Number of differences (explorers): skipped
Number of differences (thumbnails): skipped

Edited: 2026-03-10 11:40:54 UTC
Execution time: 1.34 seconds

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 2ff8b3c623

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

site/gdocs/components/BespokeComponent.tsx

chatgpt-codex-connector · 2026-02-03T16:27:56Z

site/gdocs/components/BespokeComponent.tsx

+                // Create a container div inside the shadow root for the component to render into
+                const mountContainer = document.createElement("div")
+                mountContainer.className = "bespoke-container"
+                shadowRoot!.appendChild(mountContainer)


Clear shadow DOM on rehydrate to avoid duplicates

Every effect run appends a new mount container (and, earlier, a new <link> for CSS) into the same shadow root, but the cleanup only calls the disposer. When block.config/variant changes or the component remounts, old DOM/CSS can accumulate unless each bespoke bundle explicitly removes it, leading to duplicate visuals or leaked nodes. Consider reusing a single container or clearing the shadow root in cleanup before remounting.

Useful? React with 👍 / 👎.

How would I go about doing this?

Maybe you could still fix this, but it seems like... not a big deal to me, given that block.config and variant won't change, due to how we only ever hydrate the page once.

db/model/Gdoc/enrichedToMarkdown.ts

db/model/Gdoc/rawToArchie.ts

marcelgerber · 2026-02-03T16:21:50Z

site/gdocs/components/BespokeComponent.tsx

This is where the action is

marcelgerber · 2026-02-03T16:21:58Z

site/bespokeComponentRegistry.ts

+    test: {
+        scriptUrl:
+            "https://owid-public.owid.io/marcel-bespoke-data-viz-02-2026/poverty-plots/income-plots.mjs",
+        cssUrls: [
+            "https://owid-public.owid.io/marcel-bespoke-data-viz-02-2026/poverty-plots/income-plots.css",
+        ],
+    },


This is an example registry entry; and what is powering the demo that you're seeing. I'll remove it before we merge the PR.

Right so we still need to figure out the way we write and generate these bundles. I guess for starters it doesn't need to be too systematized.

ikesau · 2026-02-05T20:55:25Z

db/model/Gdoc/rawToArchie.ts

+    yield* propertyToArchieMLString("variant", block.value)
+    yield* propertyToArchieMLString("size", block.value)
+    if (block.value.config) {
+        // TODO this doesn't support deep nesting, which in theory the type Record<string, unknown> allows for


I wonder if it'd be smart to just decide now that nesting isn't allowed, and check for it in parsing/validation.

i.e. we'd force:

{.config} aspect-ratio-small: 1 aspect-ratio-large: 2 {}

instead of

{.config} {.aspect-ratio} small: 1 large: 2 {} {}

I don't have a strong opinion on this, but maybe it makes it a little easier to work with and a little harder to write? (Though, the most common archieML breakage we encounter is authors mistakenly missing/closing brackets, so this might make that failure mode a little rarer)

ikesau

All the Archie stuff looks good! Will QA this tomorrow before full approval 👍

db/model/Gdoc/rawToEnriched.ts

site/gdocs/components/BespokeComponent.tsx

ikesau

Really clean proof of concept!

I left a few thoughts on some smaller details, but the overall approach makes sense to me.

ikesau · 2026-02-06T17:46:50Z

site/gdocs/components/ArticleBlock.tsx

+        .with({ type: "bespoke-component" }, (block) => (
+            <BespokeComponent
+                className={getLayout(
+                    `bespoke-component--${block.size}`,


What if we just rendered the container at 12 columns no matter what, and the viz itself took care of its sizing?

Doing it this way (with block.size) means that the logic for sizing a bespoke data viz will exist in at least 2 places:

The archie wrapper component (adding a dependency on our site's CSS (unlikely to change, but technically possible)

The bespoke viz rendering & CSS

Given that there's a config object that we can pass down (if we want a big and small version of the same viz) I feel like we might as well centralize?

Hm, I'm not sure how this will play along with putting this component into other, small components - whether it's an aside or side-by-side or anything else - but I'll keep it in mind when thinking about grid-aware sizing.

ikesau · 2026-02-06T17:49:21Z

site/gdocs/components/BespokeComponent.tsx

+                // Create a container div inside the shadow root for the component to render into
+                const mountContainer = document.createElement("div")
+                mountContainer.className = "bespoke-container"
+                shadowRoot!.appendChild(mountContainer)


Maybe you could still fix this, but it seems like... not a big deal to me, given that block.config and variant won't change, due to how we only ever hydrate the page once.

ikesau · 2026-02-06T17:55:44Z

site/gdocs/components/BespokeComponent.tsx

+                position: "relative",
+                minHeight: 300,


So this is where we could implement the aspect ratio system we were talking about.

If we go with the "centralize sizing information in one place" idea that I mentioned in the other comment, does that mean we'll also need a max-width attribute for each variant? 🤔

{.config} desktop-aspect-ratio: 1.618 max-width: 900px mobile-aspect-ratio: 1 // we'd probably want mobile max width to always be 100% {}

Or if we want it to be more consistent, use a size enum.

ikesau · 2026-02-06T18:03:08Z

site/bespokeComponentRegistry.ts

+    test: {
+        scriptUrl:
+            "https://owid-public.owid.io/marcel-bespoke-data-viz-02-2026/poverty-plots/income-plots.mjs",
+        cssUrls: [
+            "https://owid-public.owid.io/marcel-bespoke-data-viz-02-2026/poverty-plots/income-plots.css",
+        ],
+    },


Right so we still need to figure out the way we write and generate these bundles. I guess for starters it doesn't need to be too systematized.

github-actions · 2026-03-06T07:22:02Z

This PR has had no activity within the last two weeks. It is considered stale and will be closed in 3 days if no further activity is detected.

marcelgerber · 2026-03-11T09:38:40Z

@codex review

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: f5d185ae4d

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector · 2026-03-11T09:48:57Z

site/gdocs/components/BespokeComponent.tsx

+    if (error) {
+        return <BespokeError className={className} message={error} />


Reset error state before rendering fallback-only branch

After any load failure, setError(...) causes the component to render only BespokeError, which removes the containerRef node. Because the effect exits early on if (!container) return, the same mounted instance cannot hydrate again on later prop updates (e.g. live-preview edits or retry-worthy transient CDN failures), so the block stays permanently broken until a full remount. Clearing error before retry/hydration (and keeping a mount container available) avoids this dead-end state.

Useful? React with 👍 / 👎.

chatgpt-codex-connector · 2026-03-11T09:48:57Z

site/gdocs/components/BespokeComponent.tsx

+                const mountContainer = document.createElement("div")
+                mountContainer.className = "bespoke-container"
+                shadowRoot!.appendChild(mountContainer)
+


Remove stale shadow nodes when rehydrating bespoke block

Each effect run appends a new bespoke-container into the shadow root, but cleanup only calls an optional module-provided disposer and never removes previously appended DOM/styles. Since mount is explicitly allowed to return void, updates to bundle, variant, or config on the same component instance can accumulate old mounts and leaked styles, leading to duplicated or stale UI. Explicitly clearing/replacing injected shadow-root nodes during rehydration would prevent this.

Useful? React with 👍 / 👎.

github-actions bot assigned marcelgerber Feb 3, 2026

marcelgerber force-pushed the gdocs-bespoke-component branch from 2310235 to 15faf3d Compare February 3, 2026 15:33

marcelgerber marked this pull request as ready for review February 3, 2026 16:26

marcelgerber requested a review from ikesau February 3, 2026 16:26

chatgpt-codex-connector bot reviewed Feb 3, 2026

View reviewed changes

marcelgerber commented Feb 3, 2026

View reviewed changes

ikesau reviewed Feb 5, 2026

View reviewed changes

db/model/Gdoc/rawToEnriched.ts Outdated Show resolved Hide resolved

site/gdocs/components/BespokeComponent.tsx Outdated Show resolved Hide resolved

ikesau approved these changes Feb 6, 2026

View reviewed changes

github-actions bot added the stale label Mar 6, 2026

github-actions bot closed this Mar 9, 2026

marcelgerber reopened this Mar 9, 2026

marcelgerber added 13 commits March 9, 2026 14:56

feat(gdocs): add bespoke component

a9deb56

feat: add bespoke component registry

bd93d21

enhance: allow for multiple CSS URLs

982b843

enhance: split into bundle and variant

7a8e084

enhance: turn bespoke component into "normal" React component

bf5b42c

enhance: add comment

a966dad

enhance: show loading indicator while loading

c315ba1

enhance: add example archieml

9975a1a

enhance: add test urls

4c7d49d

fix: fix archie serialization

3077731

enhance: single css file & parallel JS & CSS loading

2b1837e

fix: await mount

af614b0

add how rich am I urls for now

95ed30d

marcelgerber force-pushed the gdocs-bespoke-component branch from c77eeb7 to 95ed30d Compare March 9, 2026 13:59

marcelgerber added 2 commits March 9, 2026 15:14

refactor: move types to own file

e35a416

fix: include in indexable text

9292001

marcelgerber added 3 commits March 9, 2026 15:34

refactor: check for flat config

d8026a6

refactor: better size validation

b2754a8

refactor: add vite-ignore directive to dynamic import

31920a5

github-actions bot removed the stale label Mar 10, 2026

marcelgerber added the staging-bake label Mar 10, 2026

marcelgerber added 2 commits March 10, 2026 15:06

properly handle abort

f9327ef

add bespoke component layout classes

f5d185a

chatgpt-codex-connector bot reviewed Mar 11, 2026

View reviewed changes

marcelgerber added 4 commits March 11, 2026 12:27

fix: proper component cleanup

5865698

improvements

59c173e

fix types

4b17b31

remove entries from bespoke component registry

0fcc7be

marcelgerber merged commit f2a096f into master Mar 11, 2026
25 of 27 checks passed

marcelgerber deleted the gdocs-bespoke-component branch March 11, 2026 12:34

		if (error) {
		return <BespokeError className={className} message={error} />

Uh oh!

Conversation

marcelgerber commented Feb 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What is variant?

How this works

Drawbacks of Shadow DOM

Try it out

TODOs

Open questions

Screenshot

Uh oh!

owidbot commented Feb 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

chatgpt-codex-connector bot Feb 3, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

marcelgerber Feb 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ikesau left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

ikesau left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions bot commented Mar 6, 2026

Uh oh!

marcelgerber commented Mar 11, 2026

Uh oh!

chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector bot Mar 11, 2026

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector bot Mar 11, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

marcelgerber commented Feb 3, 2026 •

edited

Loading

What is `variant`?

owidbot commented Feb 3, 2026 •

edited

Loading

marcelgerber Feb 3, 2026 •

edited

Loading