npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@react-ui-org/docoff

v0.5.5-rc.0

Published

Library of custom HTML elements for creating flexible and simple to use `React.Component` documentation

Downloads

330

Readme

Docoff

This library provides a collection of custom HTML elements that allow easy React component library documentation.

The aim is:

  1. to be documentation stack independent
  2. to have very little dependencies
  3. to not force a specific version of React

docoff-react-base / docoff-react-preview

These components allow to create a live editable JSX component demo in browser.

Design decisions:

  1. The documentation elements are <textarea> based custom element. This is needed so as that special HTML characters (<, > etc.) are not parsed by the browser and are accessible to JS as text.
  2. All rendering code is run from within a <script> tag inserted into the document. This is needed so that the React version is not hard-coded in this library and can be loaded by the user in the desired version.
  3. @babel/standalone is loaded via CDN because that seems to be the only supported way.
  4. Components preview are completely isolated inside a shadowDom from the page CSS styles.

Usage

See index.html for a basic working example.

In short, you need to:

  1. Include dependencies from CDN:
    <script crossorigin src="https://unpkg.com/@babel/standalone@7/babel.min.js"></script>
    <script crossorigin src="https://unpkg.com/react@17/umd/react.development.js"></script>
    <script crossorigin src="https://unpkg.com/react-dom@17/umd/react-dom.development.js"></script>
  2. Include code from this package:
    <script src="/generated/bundle.js"></script>
    <link type="text/css" rel="stylesheet" href="/main.css" />
  3. Optionally define docoff-react-base elements with code that is to be common for all docoff-react-preview elements on the given page.
        <textarea is="docoff-react-base">
            const MyHello = ({name}) => <strong>Hello, {name}</strong>;
        </textarea>
    ⚠ All docoff-react-base elements must be defined before any docoff-react-preview element.
  4. Define docoff-react-preview element with code that renders the JSX:
        <textarea is="docoff-react-preview">
            <MyHello name="Igor" />
        </textarea>
    The content always needs to be a single React element. To achieve that we either wrap the content in React.Fragment:
        <textarea is="docoff-react-preview">
            <>
                <MyHello name="Igor" />
                <MyHello name="Uwe" />
            </>
        </textarea>
    or we explicitly create the React element (useful for hooks):
        React.createElement(() => {
            const [isActive, setIsActive] = React.useState(false);
            return (
               <MyButton
                   label={isActive ? 'On' : 'Off'}
                   onClick={() => setIsActive(!isActive)}
               />
            );
       });

docoff-react-props

This element renders a React component prop definition table.

Design decisions:

  1. The aim was to strike a balance between sane API, technical possibilities and ease of use. Some solutions (e.g. the fake component) are not elegant, but they make this component more useful.
  2. It is opinionated as there was no way to make it useful without it. See the inheritance rules in the Inheritance Rules section.
  3. Everything happens in browser to eliminate the need for a build pipe.

Usage

See index.html for a basic working example.

Single Component Props

To render props of a single React.Component:

  1. Include package dependencies:
    <script src="/generated/bundle.js"></script>
    <link type="text/css" rel="stylesheet" href="main.css" />
  2. Use component the <docoff-react-props> element:
    <docoff-react-props data-src="https://raw.githubusercontent.com/react-ui-org/react-ui/master/src/components/CheckboxField/CheckboxField.jsx"></docoff-react-props>

Props with Inheritance

This element also provides some shortcuts to cascade prop type definitions. It allows using prop definition files separate from component definition. It is useful to avoid huge files or to have one prop definition used on several places.

Beware, that some React related eslint rules do not always work with the more complicated inheritance constructs.

Files

The files that are parsed for prop definition need to be of the following types:

  1. React.Component that can be parsed by react-docgen - in short, this file must import and depend on React. It must:
    1. Use the *.js or *.jsx suffix
    2. Define only one component per file
  2. A prop definition file - it must not create a React.Component as it only defines propTypes and defaultProps. It must:
    1. Use the *.props.js suffix
    2. Define constant defaultProps (even when empty)
    3. Define constant propTypes (even when empty)

Parsing of the prop definition file is not too elegant. As react-docgen only supports parsing components, a fake component is created around these definitions. It is not a robust solution. If you run into problems, see the source code to see what is going on.

Inheritance Rules

Typically, there should be only one React.Component definition as the last file in the cascade. All files preceding it should be prop definition files.

There is no clean way to achieve full inheritance so for things to work the following rules must be observed:

  1. The props are overloaded one at a time in the sequence as defined.
  2. The component must define all propTypes and defaultProps, that it uses. However, they can be references to definitions in a prop definition file. Destructuring is not supported.
  3. If prop type has a docblock description its definition and description will be used. Otherwise, the definition and description from the referenced prop definition file will be used.

Usage

To use this component:

  1. Include package dependencies:
    <script src="/generated/bundle.js"></script>
    <link type="text/css" rel="stylesheet" href="main.css" />
  2. Use component:
    <docoff-react-props data-src="/exampleJS/common.props.js|/exampleJS/BaseGreeting.jsx|/exampleJS/MyGreeting.jsx"></docoff-react-props>

Development

Native

Run locally: npm start

Build: npm run build

Test: npm test

Using Docker

Run locally: docker compose up dev_server

Open shell (access to npm etc.): docker compose run --rm node_shell