react-desc-spreadable

Add a schema to your React components based on React PropTypes. This package is a fork of react-desc which adds the describedPropTypes property on described components. This allows raw access to the described prop types of a component, to spread them into another component's prop types for example.

Installation

npm install react-desc-spreadable

Usage

Adding documentation

// Anchor.js

import React from 'react';
import ReactPropTypes from 'prop-types';
import { describe, PropTypes } from 'react-desc-spreadable';

const Anchor = (props) => {
  const { path, ...rest } = props;
  return (
    <a href={path} {...rest}>{props.children}</a>
  );
};

export const AnchorWithSchema = describe(Anchor)
  .availableAt([
    {
      badge: 'https://codesandbox.io/static/img/play-codesandbox.svg',
      url: 'https://codesandbox.io/s/github/grommet/grommet-site?initialpath=anchor&amp;module=%2Fscreens%2FAnchor.js',
    },
  ])
  .description('A text link');

AnchorWithSchema.propTypes = {
  path: PropTypes.string.description('React-router path to navigate to when clicked').isRequired,
  href: PropTypes.string.description('link location').deprecated('use path instead'),
  id: ReactPropTypes.string, // this will be ignored for documentation purposes
  title: PropTypes.custom(() => {}).description('title used for accessibility').format('XXX-XX'),
  target: PropTypes.string.description('target link location').defaultValue('_blank'),
};

export default Anchor;

Accessing documentation

Documented components have a documentation property which contains three functions: toJSON, toMarkdown, and toTypescript (this was added in v4.2.0). The documented component itself also exports the same three functions, although it's recommended to use the documentation property so that your code is more maintainable – MyComponent.documentation.toJSON() makes a lot more sense to someone new than simply MyComponent.toJSON().

• JSON output

    import { AnchorWithSchema } from './Anchor';
  
    const documentation = AnchorWithSchema.documentation.toJSON();

  Expected output:

    {
        "name": "Anchor",
        "description": "A text link",
        "properties": [
          {
            "description": "React-router path to navigate to when clicked",
            "name": "path",
            "required": true,
            "format": "string"
          },
          {
            "description": "link location.",
            "name": "href",
            "deprecated": "use path instead",
            "format": "string"
          },
          {
            "description": "title used for accessibility.",
            "name": "title",
            "format": "XXX-XX"
          },
          {
            "description": "target link location.",
            "name": "target",
            "defaultValue": "_blank",
            "format": "string"
          }
        ]
      }

• Markdown output

    import Anchor from './Anchor';
  
    const documentation = Anchor.documentation.toMarkdown();

  Expected output:

    ## Anchor Component
    A text link
  
    ### Properties
  
    | Property | Description | Format | Default Value | Required | Details |
    | ---- | ---- | ---- | ---- | ---- | ---- |
    | **path** | React-router path to navigate to when clicked | string |  | Yes |  |
    | **~~href~~** | link location. | string |  | No | **Deprecated**: use path instead |
    | **title** | title used for accessibility. | XXX-XX |  | No |  |
    | **target** | target link location. | string | _blank | No |  |

• Typescript output

  Format entry will be a valid typescript definition.

    import { AnchorWithSchema } from './Anchor';
  
    const documentation = AnchorWithSchema.documentation.toTypescript();

  Expected output:

    {
        "name": "Anchor",
        "description": "A text link",
        "properties": [
          {
            "description": "React-router path to navigate to when clicked",
            "name": "path",
            "required": true,
            "format": "string"
          },
          {
            "description": "link location.",
            "name": "href",
            "deprecated": "use path instead",
            "format": "string"
          },
          {
            "description": "title used for accessibility.",
            "name": "title",
            "format": "any"
          },
          {
            "description": "target link location.",
            "name": "target",
            "defaultValue": "_blank",
            "format": "string"
          }
        ]
      }

API

• describe(component)

  Creates a proxy to the actual react component with support for the following functions:

  • availableAt([{ badge: string, url: string }]): function that receives an object or an array of objects that will render where the component is available.
  • description(value): function that receives a string with the component description.
  • deprecated(value): function that receives a string with the deprecation message.
  • toJSON(): function that returns the component schema as a JSON object.
  • toMarkdown(): function that returns the component schema as a Markdown string.
  • usage(value): function that receives a string with the component usage example.

• PropTypes

  Proxy around the React propTypes, all properties are supported. See all options here. This proxy supports the following functions:

  • defaultValue(value): function that receives a value that represents the default prop.
  • description(value): function that receives a string with the PropType description.
  • deprecated(value): function that receives a string with the deprecation message.
  • format(value): function that receives a string with the PropTypex format.

Spreading the prop types from another component

If you have a component which accepts the same props as another component, you may be used to doing something like

SomeComponent.propTypes = {
  ...SomeOtherComponent.propTypes,
  color: PropTypes.string
};

With react-desc, this will not have the intended effect, since components created by describe expose regular React prop types, not the described ones. Instead, use the describedPropTypes property:

const DocumentedSomeComponent = describe(SomeComponent).description(...);
DocumentedSomeComponent.propTypes = {
  ...DocumentedOtherComponent.describedPropTypes,
  color: PropTypes.string.description(...)
};

Why not react-docgen?

react-docgen is a great project but it relies on an AST parser to generate documentation. Most of the time this is ok, but for us the following use cases were hard to solve without a more verbose way to define propTypes:

• Define deprecated properties

• Define a required property for custom function:

  Anchor.propTypes = {
    test: () => { ... } // isRequired is not present here
  }

• Allow internal comments for properties without it showing up in the documentation