chakra-ui-docs
chakra-ui-docs copied to clipboard
refactor: replace react live with sandpack
Closes #790
Replace all instances of the React Live Previews with the use of the CSB Sandpack .
Note: Any instance of the word
Sandpack
will be abbreviated toSP
throughout this overview.
As of 7/1: Separate component built to test the functionality before replacing the current SandpackEmbed
.
Implementations (Updated 7/29)
- Via a prop, allowed layout flexibility to account for both doc pages and the embed used on the homepage.
- ~~Remove the
SandpackPreview
component and enableSandpackCodeEditor
'sreadOnly
prop if an mdx code block containedlive=false
~~ Only render the SP if the code is to show a live example. Otherwise, render the original codeblock component. - Included the
CopyButton
component that is used in the current examples, and obtain the code for copy via theuseActiveCode
hook from SP - Because most code examples use Chakra components, SP requires that they are imports in the generated file they are shown in. (React Preview did not require this).
- Due to the level of variety in code examples presented, imports and export function blocks will need to be added within the mdx code blocks in order for the SP instance to work. Simplifying the process on the front-end by using a prop, say, will potentially add further complexity on the back-end to account for the variety of examples used. (Maybe this can be rectified at a later time). Example basic code block format requirement for live previews:
Having to do the above seems somewhat consistent with how beta.reactjs.org is using the embeds.import { Button } from '@chakra-ui/react' export default function Example() { return <Button colorScheme='blue'>Button</Button> }
- Should a contributor be interested in showing components that are provided by another package, added a prop in the mdx codeblock to accepts an array of package names, parse the prop, and dump them into the providers
dependencies
prop with the version value beinglatest
for each dep.
Pages that have been given initial updates (dissolving any current errors):
- All of
Getting Started
pages, minus the recipes - All of the
Styled System
pages - All component pages
- Pages that were using a previous SP component (
with-formik
,advanced-theming
,with-framer
)
Considerations/Issues
- Find a purpose in using
jsx
vstsx
in code blocks, else stick to one and mention inCONTRIBUTING
documentation (favor tsx for consistency?). SP will not care astsx
file will be created regardless when viewing previews and in CSB, unless we interpolate the file types generated from the codeblock type (i.e.App.${props.type}
, say) - Prevent an embed instance from using local storage data set by any other instance. (This might not be possible)
- i.e. Currently, if you toggle color mode in the Advanced Theming example, it will affect the background color rendered in all other instances
- Currently, the preview windows are vertically responsive based on the content rendered. This has no effect on modals, toasts, dialogs, etc. where they do not expand the window as they are portals, and end up getting compressed when visible. The only possibility is to render a higher
minHeight
for the preview. (add a prop for the contributor to adjust the minHeight?) - To extend the previous point, any component that is rendered in a portal is generated within the embed versus the use of a portal from the site itself (which react-live utilizes).
- On initial load of the page with a SP visible, you might be able to see a flash of just the code text before the full embed renders.
- For the SP in the Advanced Theming Page it requires a custom theme in the example to demonstrate the use of creating a component theme. With the approach of this new SP, since the default index file is created with hard code, the solution is to wrap the example return of the main component in a
ChakraProvider
that excepts the custom theme object. This is to remove the code from content files in favor of code blocks in themdx
file.
Based on the above points, there is the high likelihood that almost all code examples will need to be modified in some way. It might be helpful to include documentation in CONTRIBUTING.md
to outline the basic requirements or suggestions in ensuring new or modified code examples are handled successfully.
The latest updates on your projects. Learn more about Vercel for Git ↗︎
Name | Status | Preview | Updated |
---|---|---|---|
chakra-ui-docs | ❌ Failed (Inspect) | Oct 6, 2022 at 2:02AM (UTC) |
Thanks for working on this @TylerAPfledderer.
Some feedback:
-
Codesandbox takes a long time to load on each page. I wonder if there's a way to preload the Codesandbox module
-
There's a black outline around each code preview. It looks a bit jarring, can we remove the outline or use a light gray (gray.200)
-
The font for the code editor is quite bold. Can we use the regular font weight?
-
I'd prefer for the font style to not be in italics. Let's use the normal upright font style
-
I'm concerned about Portal-related elements being scoped to the preview area instead of the entire window. I think we may be able to work around this (for modals and drawers)
Can we get on a call later today to discuss this and figure out a way forward.
Hey @segunadebayo! I'm sorry for not immediately responding; lots of work happened and I am now out of town.
In response to your feedback, in order:
- The closest thing that exists in the package for preloading is the
customSetup
optioninitMode
set toimmediate
which mounts all the Sandpack components immediately, but you still have to wait on the transpiling to finish. I've seen discussions about it though, and there is an outstanding discussion for a new bundler (I found the main package for this, so I check it out further) - We should be able to make a direct color adjustment to the border.
- In terms of the font style and weight in the editor, this actually can get tricky. Due to all the specificity, it seems that the cleaner way to go is to providing our own theme versus importing a custom one like
nightowl
. Thetheme
prop in the provider does not seem to be designed to take specific theme options while spreading in a theme likenightOwl
without getting unintended results. It would be nice though to use our own theme because we can pull in the Chakra theme instead! 😄 - Indeed I made notation in the overview of this PR about the issue with portals. I would like to hear your suggestion with their usage.
I do not know about tomorrow (Monday) but I am currently available all day this Thursday (8/18) if you still want to have a meeting.
Closing this due to staleness