Skip to content

[docs] Make demos editable#29885

Closed
bharatkashyap wants to merge 1 commit intomui:masterfrom
bharatkashyap:editable-demos
Closed

[docs] Make demos editable#29885
bharatkashyap wants to merge 1 commit intomui:masterfrom
bharatkashyap:editable-demos

Conversation

@bharatkashyap
Copy link
Collaborator

@bharatkashyap bharatkashyap commented Nov 25, 2021

https://deploy-preview-29885--material-ui.netlify.app/components/buttons/

Description

Remaining issues:
  • The placement of the Editor and Preview is not exactly the same as the static components.
  • The replacement of the dynamic component is not smooth.
  • JS/TS toggle is missing.
  • The styling and syntax highlighting on the Editor is not the same as the static code.
  • The preview isn't editable (editor loads the full code).
  • The toolbar buttons do not respond properly to the Editor.
  • The styling of the editable preview is different from the static preview (should use the same theme)
  • yarn.lock issue on Circle CI.
  • Adding a "loading" state for editor between the static and dynamic states.
  • "Press esc to disable tab-to-indent" message inconsistent with behavior. (Esc leaves the editor, which may be preferable.)
screen capture

UX

  • Fix font smoothing.
  • Support components other than Button.
  • Focus indicator should only be shown when editor is keyboard focused.
  • Preview layout shift (first interaction with one editor).
  • Layout shift of text below editor (first interaction with any editor).
  • Editor cursor not placed at position clicked.
  • Showing & hiding full code doesn't retain edits. (low-pri)
  • Fix propTypes warning for demoKey
  • Fix HTML validation warnings in react-simple-code-editor. (@oliviertassinari can merge.)
  • Add resolveDemoImports to all demo files

@bharatkashyap bharatkashyap marked this pull request as draft November 25, 2021 05:15
@bharatkashyap bharatkashyap changed the title feat: load jarle editor on static demo click [docs] load Jarle editor on static demo click Nov 25, 2021
@github-actions github-actions bot added the PR: out-of-date The pull request has merge conflicts and can't be merged. label Nov 25, 2021
@github-actions github-actions bot removed the PR: out-of-date The pull request has merge conflicts and can't be merged. label Nov 25, 2021
@bharatkashyap bharatkashyap force-pushed the editable-demos branch 2 times, most recently from 1f8f8ab to 117733b Compare November 25, 2021 14:42
@github-actions github-actions bot added the PR: out-of-date The pull request has merge conflicts and can't be merged. label Nov 25, 2021
@mbrookes

This comment has been minimized.

@mbrookes

This comment has been minimized.

@Janpot

This comment has been minimized.

@mbrookes mbrookes changed the title [docs] load Jarle editor on static demo click [docs] Make demos editable Nov 28, 2021
@mbrookes mbrookes added the docs Improvements or additions to the documentation. label Nov 28, 2021
@github-actions github-actions bot removed the PR: out-of-date The pull request has merge conflicts and can't be merged. label Nov 30, 2021
@bharatkashyap bharatkashyap marked this pull request as ready for review December 2, 2021 19:26
@mbrookes
Copy link
Member

mbrookes commented Dec 5, 2021

Released a few days ago: https://sandpack.codesandbox.io/

@github-actions github-actions bot added PR: out-of-date The pull request has merge conflicts and can't be merged. and removed PR: out-of-date The pull request has merge conflicts and can't be merged. labels Dec 7, 2021
@mui-pr-bot
Copy link

mui-pr-bot commented Dec 7, 2021

Details of bundle changes

@material-ui/core: parsed: +Infinity% , gzip: +Infinity%
@material-ui/lab: parsed: +Infinity% , gzip: +Infinity%
@material-ui/styles: parsed: +Infinity% , gzip: +Infinity%
@material-ui/private-theming: parsed: +Infinity% , gzip: +Infinity%
@material-ui/system: parsed: +Infinity% , gzip: +Infinity%
@material-ui/unstyled: parsed: +Infinity% , gzip: +Infinity%
@material-ui/utils: parsed: +Infinity% , gzip: +Infinity%

Generated by 🚫 dangerJS against 0442bbd

yarn.lock Outdated
clsx "^1.1.1"
prop-types "^15.7.2"
react-is "^17.0.2"
version "0.0.0"
Copy link
Member

Choose a reason for hiding this comment

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

🤔 Not excatly sure what's going on here, this is what the lockfile ends up like after installing over the one that's on the master branch. (yarn v1.22.10)

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

@siriwatknp @hbjORbj
Tagging you to ask if you have any ideas as to why this one particular test keeps failing for this PR. It'll be very helpful if you do!

Copy link
Contributor

Choose a reason for hiding this comment

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

I think it is related to the new dependency, jarle. Won't you uninstall this anyways when you use Sandpack as Marija suggested?

Copy link
Member

Choose a reason for hiding this comment

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

yeah, have you run yarn. I think the yarn.lock is not sync or updated.

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

I've added jarle as a dependency manually to package.json and then runyarn (doing it via yarn add seems to break)

For Sandpack - I am exploring it currently, although it might be more long term and this option might still be the one to go with till that is implementable

@github-actions github-actions bot added the PR: out-of-date The pull request has merge conflicts and can't be merged. label Dec 9, 2021
@mnajdova
Copy link
Member

Released a few days ago: https://sandpack.codesandbox.io/

I was going to ask whether we have considered https://www.npmjs.com/package/@codesandbox/sandpack-react too :)
I would say it would be better to use this option, rather than implement our own tool. Looks like it's already battle-tested in https://beta.reactjs.org/learn and is coming in the docs in Chakra-UI too.

@bharatkashyap
Copy link
Collaborator Author

I was going to ask whether we have considered https://www.npmjs.com/package/@codesandbox/sandpack-react too :) I would say it would be better to use this option, rather than implement our own tool. Looks like it's already battle-tested in https://beta.reactjs.org/learn and is coming in the docs in Chakra-UI too.

Makes sense, Marija. I can implement a version with Sandpack and then we can compare the performance, UX and bundle size changes across the two branches.

@github-actions github-actions bot removed the PR: out-of-date The pull request has merge conflicts and can't be merged. label Jan 6, 2022
@bharatkashyap
Copy link
Collaborator Author

bharatkashyap commented Jan 6, 2022

There is a layout shift when starting to interact with an editable demo.

This is fixed on the deploy preview for me:
Demo

@mbrookes
Copy link
Member

mbrookes commented Jan 7, 2022

This is fixed on the deploy preview for me

I get it for the first click on a code block on a page. Clicking on a subsequent demo doesn't have the same issue.
However in addition to the layout shift shown in the screen capture in the PR description, the text following the code block moves up when you click to edit. This happens for every demo, not just the first one clicked.

@mui-bot
Copy link

mui-bot commented Jan 12, 2022

No bundle size changes

Generated by 🚫 dangerJS against 47ee023

@bharatkashyap
Copy link
Collaborator Author

The ComboBox demo fails in the editable version; it works only when the

export default function ComboBox() {
  return (
    <Autocomplete
      disablePortal
      id="combo-box-demo"
      options={top100Films}
      sx={{ width: 300 }}
      renderInput={(params) => <TextField {...params} label="Movie" />}
    />
  );
}

// Top 100 films as rated by IMDb users. http://www.imdb.com/chart/top
const top100Films = [
  { label: 'The Shawshank Redemption', year: 1994 },
  { label: 'The Godfather', year: 1972 },
  ...

top100Films definition is moved before the ComboBox component definition; however, this is reversed by yarn docs:typescript:formatted

@siriwatknp Any thoughts on this?

@siriwatknp
Copy link
Member

I am not sure, can you try with a function instead?

export default function ComboBox() {
  return (
    <Autocomplete
      disablePortal
      id="combo-box-demo"
      options={getTop100Films()}
      sx={{ width: 300 }}
      renderInput={(params) => <TextField {...params} label="Movie" />}
    />
  );
}

const getTop100Films = () => [
  { label: 'The Shawshank Redemption', year: 1994 },
  { label: 'The Godfather', year: 1972 },
  ...

@mbrookes
Copy link
Member

mbrookes commented Jan 16, 2022

Just so that I understand correctly, by the first one do you mean that the outline (focus indicator) should not appear if the editor is clicked on?

Yes. Here's how it was done in the prior PR.

I seem to be missing this one locally and on the deploy previews as well

Whether by accident or design, the message seems to be gone

@bharatkashyap
Copy link
Collaborator Author

Just so that I understand correctly, by the first one do you mean that the outline (focus indicator) should not appear if the editor is clicked on?

Yes. Here's how it was done in the prior PR.

I seem to be missing the rationale for this - why should the focus indicator not show up if clicked?

@oliviertassinari
Copy link
Member

oliviertassinari commented Jan 23, 2022

why should the focus indicator not show up if clicked?

@bharatkashyap I think that it's well explained in https://www.w3.org/TR/wai-aria-practices-1.1/#kbd_focus_discernable_predictable. TL:DR The focus indicator is distracting when the modality is a mouse but helpful when the modality is a keyboard. It's mostly a UX consideration, I wouldn't expect all the designers to agree on what is right.
This is why the W3C has introduced the concept of :focus-visible. It's progressively implemented by all browsers, e.g. Safari: https://blogs.igalia.com/mrego/2021/06/07/focus-visible-in-webkit-may-2021/

@bharatkashyap bharatkashyap force-pushed the editable-demos branch 2 times, most recently from 3970dc8 to da53757 Compare January 28, 2022 23:45
@bharatkashyap
Copy link
Collaborator Author

bharatkashyap commented Feb 1, 2022

[x] Layout shift of text below editor (first interaction with any editor).

The current state of the layout issue seems to be best one possible given a reasonable effort

  • Preview layout shift (first interaction with one editor).

The flash on first interaction is still occurring and is a production only issue, probably related next/dynamic

  • Editor cursor not placed at position clicked.

Since we are replacing one component with the other, this is highly unlikely to be able achievable with any reasonable approach.

As an alternative, spent some time on this possibility: #30873 (load the editable demos by default, not requiring replacement) which fixes all of the above at a marginal cost to first load time.

@mbrookes
Copy link
Member

mbrookes commented Feb 2, 2022

load the editable demos by default, not requiring replacement) which fixes all of the above at a marginal cost to first load time.

Would there be any benefit in loading the editor on page load, but only load the live preview when the editor is focused?

Is there any bundle-size advantage to not having both?

@Janpot
Copy link
Member

Janpot commented Feb 3, 2022

Would there be any benefit in loading the editor on page load, but only load the live preview when the editor is focused?

Comparing the network tab of preview deploys of both PRs (cache disabled), I seem to notice about a 90kB increase in downloaded resources (= +/- 5% increase). It's not nothing, but it's also not dramatic compared to the 1.8MB we already have.

Bundle size checker doesn't seem to take the docs into account. We should include them in there.

@mbrookes
Copy link
Member

mbrookes commented Feb 3, 2022

I seem to notice about a 90kB increase in downloaded resources

With which one? (I could run the same exercise, but since you already have...)

@github-actions github-actions bot added the PR: out-of-date The pull request has merge conflicts and can't be merged. label Feb 4, 2022
@Janpot
Copy link
Member

Janpot commented Feb 4, 2022

I compared this PR (deploy) with #30873 (deploy). The latter downloads about 90kB 85kB more resources. jarle is a pretty heavy dependency so I think we can attribute most of the increase to not lazy loading it in #30873.
This shouldn't necessarily stop us from using #30873, ofcourse.

Screenshot 2022-02-04 at 09 15 32

Screenshot 2022-02-04 at 09 15 47

@mbrookes
Copy link
Member

mbrookes commented Feb 4, 2022

Okay, so a hybrid of "load the editor by default, but don't load the preview until the editor is interacted with" could be the way to go.

@bharatkashyap
Copy link
Collaborator Author

bharatkashyap commented Feb 7, 2022

Okay, so a hybrid of "load the editor by default, but don't load the preview until the editor is interacted with" could be the way to go.

The "flicker" production-only issue would remain unsolved with that approach given that we would still need to replace a static component with a dynamic one on runtime. Are there any particular benefits to this hybrid approach over loading both by default (except the bundle size)?

@mbrookes
Copy link
Member

mbrookes commented Feb 7, 2022

No, but bundle size is obviously important. What causes the "flicker"?

@mbrookes
Copy link
Member

The "flicker" production-only issue would remain unsolved with that approach given that we would still need to replace a static component with a dynamic one on runtime.

What if Jarle was render on top of the "static" demo?

@mnajdova
Copy link
Member

mnajdova commented May 2, 2022

Closing in favor of #32107 Great job for kicking off this effort @bharatkashyap

@mnajdova mnajdova closed this May 2, 2022
@mbrookes
Copy link
Member

mbrookes commented May 2, 2022

Great job for kicking off this effort @bharatkashyap

<Cough>: #24640 😁

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

docs Improvements or additions to the documentation. PR: out-of-date The pull request has merge conflicts and can't be merged.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[docs] Make source code snippet editable

9 participants