promenade v2.0.0

Promenade

A build-agnostic React component for viewing components in isolation.

Promenade provides a single React component - Promenade - and some accompanying styles. The aim is to give an isolated display environment for components, comparable to Storybook or Cosmos, without being tied to any particular build infrastructure. You only need to make a basic React app and include the provided styles, running it through whatever build process you're already using.

Usage

Installation

Just add the package as a dependency (typically a devDependency):

npm install -D promenade

Basic usage

Once Promenade is installed, create a page + React app however you normally would. Make sure the page includes the promenade.css stylesheet. Within the React app create a Promenade element, ideally as the root:

const ComponentLibrary = () => (
  <Promenade
    pavilions={[
      ['Hello World', <HelloWorld />],
      [
        'Button',
        <div>
          Click me: <Button onClick={() => console.log('Clicked'!)} />
        </div>,
      ],
    ]}
  />
)

ReactDOM.render(<ComponentLibrary />, document.getElementById('promenade'))

The pavilions prop accepts an array of tuples, each tuple being a name for the pavilion (which must be unique) and an element to render. Each pavilion will have a menu entry for its name, allowing you to select the one to view.

Controls

If a component needs variable props (comparable to Storybook's Knobs addon), you can create a function instead of a static component, which will receive a selectuion of functions for creating named controls.

<Promenade
  pavilions={[
    [
      'With controls',
      ({ bool, str, num }) => (
        <ComponentReceivingProps
          booleanProp={bool('Toggle', false)}
          numericProp={num('Counter', 0)}
          stringyProp={str('Text', 'abc')}
        />
      ),
    ],
  ]}
/>

The control creation functions take a name and a default value, and for each name a control will be created in the Control Panel that appears to the side. In addition to the basic value functions, you can also make use of the group function to form your own groupings of controls: any controls given the same group name will appear in a shared section of the control panel.

<Promenade
  pavilions={[
    [
      'With grouped controls',
      ({ group, str }) => (
        <ComponentReceivingProps
          favourite={group('Dinosaurs').str('Favourite', 'Steggy')}
          allMammals={group('Mammals', ({ str }) => [str('Toothy', 'Sabretooth'), str('Large', 'Mammoth')])}
          allDinosaurs={group('Dinosaurs', ({ str }) => [
            str('Clever', 'Raptor'),
            str('Flying', 'Pterosaur'),
            str('Large', 'Brontosaurus'),
          ])}
        />
      ),
    ],
  ]}
/>

In the above example, there would be two control groups: Dinosaurs and Mammals. Dinosaurs would contain controls for Favourite, Clever, Flying and Large, while Mammals would contain controls for Toothy and Large. If there were any other controls not in groups, they would still appear in the separate ungrouped section.