malcolm-kee / react-showroom Goto Github PK

View Code? Open in Web Editor NEW

43.0 3.0 1.0 2.19 MB

Document React components by declaring props definition and writing markdown.

Home Page: https://react-showroom.js.org/

TypeScript 87.91% JavaScript 0.74% AppleScript 0.39% HTML 1.01% CSS 9.95%

react typescript showroom component-library

react-showroom's Introduction

react-showroom

https://react-showroom.js.org/

Document React components by declaring props definition and writing markdown.

Key Features

Auto generate documentations for your component props from the component's TypeScript definition.
Write markdown to show examples to use the component, which will become an editable playground.
Auto generated props control/knobs based on component props type definitions.
Supported languages for live examples: typescript (TSX and TS), javascript (JSX and JS), and HTML.
Improve collaborations: edit code/add comments on specific examples with shareable URL without any backend.
Ensure the components are SSR-friendly - the site can be pre-render on build time.

Built With

Inspired by

This project is largely inspired by React Styleguidist. To be honest this project was started as my plan to rewrite it to understand how it works.

The standalone editor view is inspired by Playroom.

Philosophy

The philosophy of React Showroom is that you should be continuing your existing workflow (declaring component props/writing standard markdown) and the Showroom is just an automatic side product (hopefully a valuable one) of that workflow.

This is in contrast with Storybook where it aims to be central part of your development workflow (and requires you to write examples/documentations in a special format).

We believe that compared to languages (TypeScript and markdown), libraries are generally short-lived and often less stable. Write your documentations in a more stable medium gives you more freedom and allows you to migrate to alternative tool in future.

Roadmap

Following are the ideas that I want to implement as enhancements (but I not sure if they are possible):

Run jest tests in the Showroom
Vue support

Contributors ✨

Thanks goes to these wonderful people (emoji key):

_{Malcolm Kee}
💻 🐛

This project follows the all-contributors specification. Contributions of any kind welcome!

react-showroom's People

Contributors

Stargazers

Watchers

Forkers

huygn

react-showroom's Issues

Create showroom for `@showroomjs/ui` package

Which need circular dependency support. Not sure if that's possible.

Render multiple screens in standalone view

Support Table

Add E2E Tests

RFC: Interactions

Inspired by the upcoming StorybookJS Interaction Testing, I am thinking of introducing something similar to React Showroom.

Goals

Allow docs viewer to see a sequence of interactions in browser directly

Must-have

use testing-library as the programmatic way to run simulations.

Nice-to-have

Allowing reusing code for the interaction demo and tests, following our philosophy of reusing existing dev workflow instead of reinvent one.
Undo/redo the interaction steps
Ability to run the interaction step-by-step

Challenges

Because we're using markdown instead of javascript, it is probably challenging to achieve nice-to-have 1.

Support Fast Refresh

Tweak design for NumberInput to differentiate with TextInput

Standalone in Dialog is not a good design

There may be conflict with other UI library approach for portal.

Better stick to full page view only to be safe.

useMenu

Allow add comment in standalone view

The comment should be point to a specific point of the preview
The comment location/content should be encoded into URL, so it can be shared together with the link

Use react-draggable for the anchor of the comment

Basic support: only our components
Advanced support: support for imported libraries as well

use puppeteer - this would probably implemented as an optional feature (as forcing user to install puppeteer with this package is a no-go), user need to install puppeteer for this and turn it on.
use html2canvas. However this requires user to manually run it and save the image as part of the repositories. We probably need to render a dev only panel that allows us to run this in dev server. This may be a good approach, combining with File System Access API.