Example

Check out the full example.

Usage

Install the playground package

$ npm i @latticehr/playground --dev

Or yarn

$ yarn add @latticehr/playground --dev

Then you'll want to create a playground entry file. This is where we'll be rendering the playground.

// playground.js
import React from "react";
import { render } from "react-dom";
import Playground from "@latticehr/playground";

function importAll(r) {
  return r.keys().map(r);
}

const components = importAll(require.context("./components", true, /\.js$/));
const design = importAll(require.context("./design", true, /\.js$/));

// Organize pages by sections. Each section will be a subgroup in the left Sidebar.
const sections = [
  {
    name: "Foundations",
    shouldDisplayInCatalog: false,
    pages: design.map((d) => ({ ...d })),
  },
  {
    name: "Components",
    pages: components.map((d) => ({ ...d })),
  },
];

// These resources will be rendered in the right Sidebar.
const resources = [
  {
    text: "Report an issue",
    href:
      "https://github.com/latticehr/playground/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc",
  },
  { text: "Request a component", href: "#" },
  { type: "separator" },
  {
    text: "Design Principles",
    href:
      "https://www.notion.so/lattice/Design-Principles-73f8d0abac2a42738c042fb9c820be68",
  },

const App = () => (
  <Playground sections={sections} resources={resources} />
);

render(<App />, document.getElementById("root"));

Finally, you'll want to add the loader to your webpack config.

// webpack.config.js
// This loader handles extracting metadata from your react components.
const PlaygroundMetadataLoader = require("@latticehr/playground/loaders/metadata");

// after babel loader
{
  test: /\.m?js$/,
  exclude: /(node_modules)/,
  use: {
    loader: PlaygroundMetadataLoader
  }
},

Creating .playground pages:

  // The playground exports a group of components to let you build documentation pages declaratively.
  import { ComponentStatus, PageDescription, PropsTable, Import, Example } from "@latticehr/playground"

  // You can see what each of these components render by running the playground and going to http://localhost:2000/#/badge.
  export default = () => (
  <>
    <PageDescription>
      Badge are used to inform users of the status of an item. They are not
      actionable or interactive
    </PageDescription>
    <ComponentStatus
      migrationDocsLink="notion.com/test/link"
      status="READY"
      statusDescription="We are perfecting this component"
    />
    <Import code="import Badge from 'system/Badge'" />

    <Example
      title="Badge variants"
      description="Use the size prop to change the visual style of the badge. You can set the value to `default`, `info`, `success` or `danger"
      code={`
        <>
          <Badge variantColor="gray" mr={2}>
            default
          </Badge>
          <Badge variantColor="blue" mr={2}>
            info
          </Badge>
          <Badge variantColor="green" mr={2}>
            success
          </Badge>
          <Badge variantColor="red">danger</Badge>
        </>
      `}
      scope={{ Badge }}
    />

    <Example
      title="Badge variants"
      description="Use the size prop to change the visual style of the badge. You can set the value to `default`, `info`, `success` or `danger"
      code={`
        <>
          <Badge variantColor="gray" mr={2}>
            default
          </Badge>
          <Badge variantColor="blue" mr={2}>
            info
          </Badge>
          <Badge variantColor="green" mr={2}>
            success
          </Badge>
          <Badge variantColor="red">danger</Badge>
        </>
      `}
      scope={{ Badge }}
    />
    <PropsTable />
  </>
);

You can also create playground pages with comment blocks (markup). This feature should be used for simple components that don't require much documentation.

// This comment block should be placed right above the component definition. You can use the same markup available on github.
/**
 * Links are accessible elements used primarily for navigation.
 *
 * [Source code](https://gist.github.com/hanford/7b0cbd3e91ffc3d2e8af7a2035425217)
 *
 * ```js
 * import Link from 'system/Link'
 * ```
 *
 * ```live
 * <Link
 *  title="foo"
 *  style={{ color: theme.red }}
 *  href="https://jackhanford.com"
 * >
 *  I'm a Link Component
 * </Link>
 * ```
 *
 * ```live
 * <Link
 *  title="Personal website"
 *  style={{ color: theme.blue }}
 *  href="https://jackhanford.com"
 * >
 *  Yoooo what's up
 * </Link>
 * ```
 *
 * @status QA
 * @statusDescription Pending review
 * @legacyComponents [LinkDeprecated, PrimaryLinkDeprecated]
 * @migrationDocsLink https://notion.github.io/link-migration-status.html
 */

export default function Link(props: Props) {
  return <a style={{ color: theme.blue }} {...props} />;
}

Gathering and displaying migration data. In order to fetch migration data you must first add the loader to your app:

// webpack.config.js
// This loader extracts migration data from your repo (counts instances of legacy and new components).
const PlaygroundMigrationLoader = require("@latticehr/playground/loaders/migration");

// after babel loader

{
  test: /\.m?js$/,
  exclude: /(node_modules)/,
  use: {
    loader: PlaygroundMigrationLoader
  }
}

Next, each component that wants to display its migration data must export the names of the components it replaces as part of the playgroundOptions object:

//Badge.playground.js
export const playgroundOptions = {
  legacyComponents: ["BadgeDeprecated"],
};

Or use this comment tag:

// Badge.js
/**
 *
 * @legacyComponents [BadgeDeprecated, CollapseDeprecated]
 */

Finally, you'll have to render the ComponentStatus component:

  //Badge.playground.js
  // This component will display a migration percentage based on the number of imports it has and the number of imports its legacyComponents have
  <ComponentStatus status="READY">

Development

$ git clone https://github.com/latticehr/playground
$ cd playground
$ yarn install

To start up webpack-dev-server:

$ yarn demo:server

And finally rebuild when changes happen:

$ yarn demo:watch

License (MIT)

WWWWWW||WWWWWW
 W W W||W W W
      ||
    ( OO )__________
     /  |           \
    /o o|    MIT     \
    \___/||_||__||_|| *
         || ||  || ||
        _||_|| _||_||
       (__|__|(__|__|

Copyright © 2020-present Lattice

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.