feat(typography)!: recolor `CodeBlock` and migrate to `prism-react-renderer` v2 #1864

jzempel · 2024-07-18T13:30:11Z

Description

Completed recolor work for CodeBlock both isLight={false} and isLight={true}.

Detail

BREAKING CHANGE: the migration to prism-react-renderer cuts out a bunch of non-essential Prism languages.

Checklist

👌 design updates will be Garden Designer approved (add the designer as a reviewer)
🌐 demo is up-to-date (npm start)
⬅️ ~~renders as expected with reversed (RTL) direction~~
🤘 renders as expected with Bedrock CSS (?bedrock)
💂‍♂️ includes new unit tests. Maintain existing coverage (always >= 96%)
♿ tested for WCAG 2.1 AA accessibility compliance
📝 ~~tested in Chrome, Firefox, Safari, and Edge~~

jzempel · 2024-07-18T13:31:32Z

packages/typography/src/elements/CodeBlock.tsx

+    const [isPrismImported, setIsPrismImported] = useState(false);
+    const win = useWindow();
+
+    const importPrism = useCallback(async () => {
+      // TODO remove `importPrism` if/when `prismJS` releases v2 ESM
+      // https://github.com/orgs/PrismJS/discussions/3531
+      if (win && !isPrismImported) {
+        (win as any).Prism = Prism;
+
+        await Promise.all([
+          import('prismjs/components/prism-diff' as any),
+          import('prismjs/components/prism-json' as any)
+        ]);
+
+        setIsPrismImported(true);
+      }
+    }, [win, isPrismImported]);
+
+    useLayoutEffect(() => {
+      // Import languages missing from the vendored `Prism` using a variant of
+      // https://github.com/FormidableLabs/prism-react-renderer?tab=readme-ov-file#custom-language-support
+      // that is compatible with both React and Jest
+      importPrism();
+    }, [importPrism]);


All of this goes away if/when PrismJS releases v2 with support for ESM imports 🙄

jzempel · 2024-07-18T13:32:56Z

packages/typography/src/elements/CodeBlock.tsx

+              <ThemeProvider
+                theme={parentTheme => ({
+                  ...parentTheme,
+                  colors: { ...parentTheme.colors, base: isLight ? 'light' : 'dark' }
+                })}
+              >


Using the coerced mode theming technique here to render styled components based on the isLight prop.

ze-flo · 2024-07-19T15:42:40Z

packages/typography/src/elements/CodeBlock.tsx

-          Prism={Prism}
-          code={code ? code.trim() : ''}
-          language={LANGUAGES.includes(language as Language) ? (language as Language) : 'tsx'}
+      isPrismImported && (


Should we explore displaying a loading state while Prism deps are loading?

I wonder if an enhancement could be made on this component (perhaps not right now) to allow a consumer-provided loading state.

As this aims to be a temporary solution based on PrismJS's ESM roadmap, I hope we don't have to explore loading states.

ze-flo · 2024-07-19T15:45:54Z

packages/typography/src/elements/CodeBlock.tsx

+      }
+    }, [win, isPrismImported]);
+
+    useLayoutEffect(() => {


[nit] Would useEffect be sufficient here?

Also curious about this. My understanding is that useLayoutEffect is most useful in dealing with positioning and layout discrepancies. Does that apply for CodeBlock?

useEffect is the right hook since we aren't rendering until language tokenization is in place. I've updated the code.

ze-flo · 2024-07-19T15:50:51Z

packages/typography/src/elements/CodeBlock.tsx

+        await Promise.all([
+          import('prismjs/components/prism-diff' as any),
+          import('prismjs/components/prism-json' as any)
+        ]);


Should we handle dynamic import failures with an error state?

+1 to always have error states for dynamic imports

We don't need an error state, per se. But we should always allow the component to render – whether or not it can be tokenized for language highlighting. The updated try .. catch .. finally allows for that.

geotrev · 2024-07-19T17:54:24Z

I'm curious what the implication is for consumers/product implementations relying on the cut languages. Do we know who this affects and how wide spread it will be? Or is it a non-issue?

geotrev

LGTM other than what is being discussed above.

geotrev · 2024-07-19T20:36:31Z

packages/typography/src/styled/StyledCodeBlockLine.ts

+      change: { hue: 'lemon', shade: 300 }
+    }[diff];
+
+    backgroundColor = getColor({ theme, ...options, transparency: theme.opacity[200] });


sieeeeeenna · 2024-07-19T21:15:10Z

everything looks as expected on the design side! yay!

jzempel · 2024-07-19T21:42:04Z

I'm curious what the implication is for consumers/product implementations relying on the cut languages. Do we know who this affects and how wide spread it will be? Or is it a non-issue?

@geotrev I searched all product code and the majority simply use <CodeBlock> without language specified (defaults to tsx). What we have here is already more extensive than what is currently in use. And I've added bash back in order to retain support for developer API docs.

geotrev · 2024-07-19T22:00:15Z

@jzempel Awesome. Sounds like a minimal number of folks then.

ze-flo

Awesome work! 💯

jzempel added 5 commits July 16, 2024 16:13

feat(typography): recolor CodeBlock component

3d3aeab

Fix tests

7238a2a

Upgrade prism-react-renderer

002edc3

Fix imports, tests, and reduce languages

51fc641

Update migration guide

dc36fb8

jzempel added the PR: Breaking Change 💥 label Jul 18, 2024

jzempel requested review from lucijanblagonic, sieeeeeenna and steue July 18, 2024 13:30

jzempel requested a review from a team as a code owner July 18, 2024 13:30

jzempel commented Jul 18, 2024

View reviewed changes

github-actions bot deployed to staging July 18, 2024 13:39 View deployment

ze-flo reviewed Jul 19, 2024

View reviewed changes

geotrev reviewed Jul 19, 2024

View reviewed changes

Refine dynamic prismjs imports and add bash language support

ca81edb

jzempel requested review from geotrev and ze-flo July 19, 2024 21:42

jzempel added 2 commits July 19, 2024 17:44

Revert bash example

230b3f8

Merge branch 'next' into jzempel/recolor-codeblock

f1398db

github-actions bot deployed to staging July 19, 2024 22:00 View deployment

geotrev approved these changes Jul 19, 2024

View reviewed changes

ze-flo approved these changes Jul 19, 2024

View reviewed changes

jzempel merged commit 5fd3fd9 into next Jul 22, 2024

jzempel deleted the jzempel/recolor-codeblock branch July 22, 2024 13:07

feat(typography)!: recolor CodeBlock and migrate to prism-react-renderer v2 #1864

feat(typography)!: recolor CodeBlock and migrate to prism-react-renderer v2 #1864

Uh oh!

Conversation

jzempel commented Jul 18, 2024

Description

Detail

Checklist

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!

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!

geotrev commented Jul 19, 2024

Uh oh!

geotrev left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sieeeeeenna commented Jul 19, 2024

Uh oh!

jzempel commented Jul 19, 2024

Uh oh!

geotrev commented Jul 19, 2024

Uh oh!

ze-flo left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

4 participants

feat(typography)!: recolor `CodeBlock` and migrate to `prism-react-renderer` v2 #1864

feat(typography)!: recolor `CodeBlock` and migrate to `prism-react-renderer` v2 #1864