fix(theme-classic): inconsistent code block wrapping #7485

dpang314 · 2022-05-25T02:03:52Z

Pre-flight checklist

I have read the Contributing Guidelines on pull requests.
If this is a code change: I have written unit tests and/or added dogfooding pages to fully verify the new behavior.
If this is a new API or substantial change: the PR has an accompanying issue (closes #0000) and the maintainers have approved on my working plan.

Motivation

Resolves #7449

Addresses the following issues:

Wrap code button not breaking apart long words
Wrap code button not appearing when switching to initially hidden tab components

Also fixes one other issue that can be replicated as follows

Start on a tab component with the window wide enough that it does not have a wrap code button
Switch to another tab component
While still on the second tab, make the window narrow enough that the original tab would become scrollable
Switch back to the original tab. Even though it is scrollable, it will not have a code wrap button

The issues with hidden tabs were caused by elements with an ancestor with the "hidden" attribute that caused their clientWidth and scrollWidth to be 0, so they could not properly determine whether the code block was scrollable. The new code looks for ancestors with the "hidden" attribute and watches for when they are no have the "hidden" attribute. At that point, the clientWidth and scrollWidth are accurate and it can determine whether the code block is scrollable.

Test Plan

Tests added to bottom of dogfooding code-block-tests.mdx

Before

before.mp4

After

after.mp4

Test links

Deploy preview: https://deploy-preview-7485--docusaurus-2.netlify.app/tests/pages/code-block-tests#code-block-wrapping-tests
@alexfornuto's example with bugs resolved: https://rad-bienenstitch-2b77e5.netlify.app/tests/pages/long-code-block-tests

Related issues/PRs

Fixes bugs in #7036
Resolves #7449

netlify · 2022-05-25T02:11:36Z

✅ [V2]

Name	Link
🔨 Latest commit	`df58da0`
🔍 Latest deploy log	https://app.netlify.com/sites/docusaurus-2/deploys/6298b59249e1f90009c8f881
😎 Deploy Preview	https://deploy-preview-7485--docusaurus-2.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site settings.

github-actions · 2022-05-25T02:12:25Z

⚡️ Lighthouse report for the deploy preview of this PR

URL	Performance	Accessibility	Best Practices	SEO	PWA	Report
/	🟠 69	🟢 100	🟢 100	🟢 100	🟢 90	Report
/docs/installation	🟠 78	🟢 99	🟢 100	🟢 100	🟢 90	Report

Josh-Cena · 2022-05-25T03:50:41Z

website/_dogfooding/_pages tests/code-block-tests.mdx

+
+## Code block wrapping tests
+
+[// spell-checker:disable]: #


Huh, I didn't know this is a thing 🤔

Josh-Cena · 2022-05-25T03:52:14Z

packages/docusaurus-theme-common/src/hooks/useCodeWordWrap.ts

@@ -17,6 +17,8 @@ export function useCodeWordWrap(): {
  const [isEnabled, setIsEnabled] = useState(false);
  const [isCodeScrollable, setIsCodeScrollable] = useState<boolean>(false);
  const codeBlockRef = useRef<HTMLPreElement>(null);
+  const [mutationObserver, setMutationObserver] =
+    useState<MutationObserver | null>(null);


Should this be a state or a ref? We have usage of IntersectionObserver in core, and we use a ref there.

We shouldn't need to re-render after IO is set, so ref is better 👍

slorber

Looks like a good solution thanks 👍

I'd like the complexity of IO to be more encapsulated, let me know if you need help

slorber · 2022-05-25T13:01:25Z

packages/docusaurus-theme-common/src/hooks/useCodeWordWrap.ts

@@ -17,6 +17,8 @@ export function useCodeWordWrap(): {
  const [isEnabled, setIsEnabled] = useState(false);
  const [isCodeScrollable, setIsCodeScrollable] = useState<boolean>(false);
  const codeBlockRef = useRef<HTMLPreElement>(null);
+  const [mutationObserver, setMutationObserver] =
+    useState<MutationObserver | null>(null);


We shouldn't need to re-render after IO is set, so ref is better 👍

slorber · 2022-05-25T13:05:13Z

packages/docusaurus-theme-common/src/hooks/useCodeWordWrap.ts

+    if (!mutationObserver) {
+      setMutationObserver(
+        new MutationObserver((mutations) => {
+          mutations.forEach((mutation) => {
+            if (
+              mutation.type === 'attributes' &&
+              mutation.attributeName === 'hidden'
+            ) {
+              updateCodeIsScrollable();
+            }
+          });
+        }),
+      );
+    }
+


it's a good practice in React to use one separate effect per concern (resize, observe mutations...) instead of trying to fit everything into a single effect

Also I suggest to create a reusable abstraction here to encapsulate the IO complexity.

For example: useMutationObserver() could be added to theme-common as it would likely be useful in other places: https://www.30secondsofcode.org/react/s/use-mutation-observer

note: we may want to take care of memorizing to avoid IO recreation:

the options (or making it a static constant)

the callback (we have a useDynamicCallback() hook which is basically the same as the useEvent RFC proposal https://github.com/reactjs/rfcs/blob/useevent/text/0000-useevent.md)

And you can still extract a custom hook dedicated to this specific case.

In the end the component code could look as simple as: useHiddenAttributeMutationObserver(() => updateCodeIsScrollable());

Thank you for the help! I started implementing useMutationObserver() but had trouble passing in the target element, since it is constantly changing, and the mutation observer must call observe on the bew element each time it is changed. I followed the link, but instead of passing in a RefObject I pass in an an Element instead of a in order to trigger useEffect(). Is this fine?

I also have another implementation that does not need to store any additional state. It does cause errors with the linter (@typescript-eslint/no-use-before-define), but it builds and works properly. However, it is less reusable and not as well encapsulated. Is it better to go with this method?

Inside useMutationObserver:

return { setAncestor: (ancestor: Element | null | undefined): void => { if (ancestor) { mutationObserver.current.observe(ancestor, options); } } }

Inside useCodeWordWrap:

const observer = useMutationObserver((mutations) => { mutations.forEach((mutation) => { if ( mutation.type === 'attributes' && mutation.attributeName === 'hidden' ) { updateCodeIsScrollable(); } }); });

Inside updateCodeisScrollable:

observer.setAncestor(codeBlockRef.current?.closest('[hidden]'));

slorber

👍

Did some cleanup but it looks to work fine

slorber · 2022-06-02T12:43:33Z

packages/docusaurus-theme-common/src/hooks/useMutationObserver.ts

+  const mutationObserver = useRef<MutationObserver | undefined>(
+    ExecutionEnvironment.canUseDOM ? new MutationObserver(callback) : undefined,
+  );
+  const memoOptions = useMemo(() => options, [options]);


this is useless memo

slorber · 2022-06-02T12:43:52Z

packages/docusaurus-theme-common/src/hooks/useCodeWordWrap.ts

@@ -25,19 +52,25 @@ export function useCodeWordWrap(): {
      codeElement.removeAttribute('style');
    } else {
      codeElement.style.whiteSpace = 'pre-wrap';
+      codeElement.style.overflowWrap = 'anywhere';


why is this needed?

The whiteSpace style will never break words apart, so for a single word that is long enough to overflow the code block, it would stay on one line and cause the scroll bar to remain.

👍 will add this back sorry

packages/docusaurus-theme-common/src/hooks/useShallowMemoObject.ts

fix(theme-classic): inconsistent code block wrapping

d6db387

dpang314 requested review from slorber, lex111 and Josh-Cena as code owners May 25, 2022 02:03

facebook-github-bot added the CLA Signed Signed Facebook CLA label May 25, 2022

Josh-Cena added the pr: bug fix This PR fixes a bug in a past release. label May 25, 2022

Josh-Cena reviewed May 25, 2022

View reviewed changes

slorber requested changes May 25, 2022

View reviewed changes

dpang314 and others added 3 commits May 25, 2022 17:02

refactor(theme-classic): abstract mutation observer

9eec193

fix: MutationObserver reference error

e2864bc

Merge branch 'main' into code-wrap

062348e

slorber approved these changes Jun 2, 2022

View reviewed changes

refactor

2eb5951

Josh-Cena reviewed Jun 2, 2022

View reviewed changes

packages/docusaurus-theme-common/src/hooks/useShallowMemoObject.ts Outdated Show resolved Hide resolved

refactor

df58da0

slorber merged commit b215ad0 into facebook:main Jun 2, 2022

slorber mentioned this pull request Jun 2, 2022

fix(theme-classic): code block wrap mode should allow wrapping in the middle of a word #7551

Merged

3 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

fix(theme-classic): inconsistent code block wrapping #7485

fix(theme-classic): inconsistent code block wrapping #7485

dpang314 commented May 25, 2022 •

edited

netlify bot commented May 25, 2022 •

edited

github-actions bot commented May 25, 2022 •

edited

Josh-Cena May 25, 2022

Josh-Cena May 25, 2022

slorber May 25, 2022

slorber left a comment

slorber May 25, 2022

slorber May 25, 2022 •

edited

dpang314 May 25, 2022 •

edited

slorber left a comment

slorber Jun 2, 2022

slorber Jun 2, 2022

dpang314 Jun 2, 2022

slorber Jun 2, 2022

slorber Jun 2, 2022

fix(theme-classic): inconsistent code block wrapping #7485

fix(theme-classic): inconsistent code block wrapping #7485

Conversation

dpang314 commented May 25, 2022 • edited

Pre-flight checklist

Motivation

Test Plan

Test links

Related issues/PRs

netlify bot commented May 25, 2022 • edited

✅ [V2]

github-actions bot commented May 25, 2022 • edited

⚡️ Lighthouse report for the deploy preview of this PR

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

slorber left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

slorber May 25, 2022 • edited

Choose a reason for hiding this comment

dpang314 May 25, 2022 • edited

Choose a reason for hiding this comment

slorber left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dpang314 commented May 25, 2022 •

edited

netlify bot commented May 25, 2022 •

edited

github-actions bot commented May 25, 2022 •

edited

slorber May 25, 2022 •

edited

dpang314 May 25, 2022 •

edited