dis-gui-lifetoys

This repo was forked from wwwtyro/dis-gui and includes the following notable changes:

• Babel 6 was updated to Babel 7 configured with preset-env and preset-react
• React 16 was updated to React 18
• Added install-peers-cli package and npm run prepare script to install peer dependencies
• Added styled-components package
• Range slider now uses a styled input[type=range] instead of a custom control

Additional Notes:

• The components are still using componentWillReceiveProps() to update state synchronously such that a re-render is not triggered. Each component has specific UX concerns that require investigation and dev testing. In some cased, componentDidUpdate() seems like an appropriate replacement. In other cases, another method may be more suitable.

An extensible, styleable, & React-based controller library inspired by the venerable dat-gui.

The above was created with the following JSX:

1import * as dg from 'dis-gui-lifetoys';
2
3...
4
5<dg.GUI>
6  <dg.Text label='Text' value='Hello world!'/>
7  <dg.Number label='Number' value={65536}/>
8  <dg.Number label='Range' value={512} min={-1024} max={1024} step={64}/>
9  <dg.Checkbox label='Checkbox' checked={true}/>
10  <dg.Select label='Select' options={['Option one', 'Option two', 'Option three']}/>
11  <dg.Button label='Button'/>
12  <dg.Folder label='Folder' expanded={true}>
13    <dg.Text label='Text' value='Hello folder!'/>
14    <dg.Number label='Number' value={2}/>
15    <dg.Folder label='Subfolder' expanded={true}>
16      <dg.Text label='Text' value='Hello subfolder!'/>
17      <dg.Number label='Number' value={2}/>
18    </dg.Folder>
19  </dg.Folder>
20  <dg.Color label='Color' expanded={true} red={0} green={128} blue={255}/>
21  <dg.Gradient label='Gradient' expanded={true}/>
22</dg.GUI>

Demo

Try out the live demo.

Installation

npm install dis-gui-lifetoys

Note: dis-gui-lifetoys has peer dependencies react@^18.0.0 react-dom@^18.0.0

Events

The onChange event is fired when a control's value changes:

1<dg.GUI>
2  <dg.Text
3    label='Text' value='Hello world!'
4    onChange={function(value) {console.log(value)}}
5  />
6</dg.GUI>

The onFinishChange event fires when the user performs some action that indicates that they are finished changing a value, like hitting enter or tabbing out of a text or number field, or releasing a mouse button after dragging a number range thumb:

1<dg.GUI>
2  <dg.Number
3    label='Horses'
4    value={2}
5    min={0}
6    max={4}
7    step={0.1}
8    onFinishChange={function(value) {console.log(value)}}
9  />
10</dg.GUI>

The Button control fires an onClick event:

1<dg.GUI>
2  <dg.Button
3    label='Run The Horses'
4    onClick={function() {console.log('The horses are running.')}}
5  />
6</dg.GUI>

Numbers

If you provide a min and max prop to the Number control, you'll get a range slider and a number field:

1<dg.GUI>
2  <dg.Number
3    label='Horses'
4    value={2}
5    min={0}
6    max={4}
7    step={0.1}
8    onFinishChange={function(value) {console.log(value)}}
9  />
10</dg.GUI>

If you don't, it won't:

1<dg.GUI>
2  <dg.Number
3    label='Horses'
4    value={2}
5    onFinishChange={function(value) {console.log(value)}}
6  />
7</dg.GUI>

If the user enters a value that is not a number, the onChange and onFinishChange event will not fire, and the value will be highlighted with the value defined by lowlighterr in the style property of the GUI component:

Folders

Nest controls to arbitrary depth with the Folder component:

1<dg.GUI>
2  <dg.Folder label='Folder 1'>
3    <dg.Folder label='Folder 2'>
4      <dg.Folder label='Folder 3'>
5        <dg.Folder label='Folder 4'>
6          <dg.Folder label='Folder 5'>
7            <dg.Text label='You' value='...made it!'></dg.Text>
8          </dg.Folder>
9        </dg.Folder>
10      </dg.Folder>
11    </dg.Folder>
12  </dg.Folder>
13</dg.GUI>

Pass the expanded prop a boolean to indicate if the folder should start out open or closed:

1<dg.GUI>
2  <dg.Folder label='Folder 1' expanded={true}>
3    <dg.Text label='You' value='...made it!'></dg.Text>
4  </dg.Folder>
5</dg.GUI>

Styling

Pass a style property to the GUI component to change its appearance:

1<dg.GUI style={{
2  paddingX: 3,
3  paddingY: 3,
4  backgroundColor: '#EEE',
5  lowlight: '#DDD',
6  lowlighterr: '#FBB',
7  highlight: '#444',
8  separator: '1px solid #DDD',
9  label: {
10    fontColor: '#444',
11    fontWeight: 'normal'
12  }
13}}>
14  <dg.Text label='Text' value='Hello world!'/>
15  <dg.Number label='Number' value={65536}/>
16  <dg.Number label='Range' value={512} min={-1024} max={1024} step={64}/>
17  <dg.Checkbox label='Checkbox' checked={true}/>
18  <dg.Select label='Select' options={['Option one', 'Option two', 'Option three']}/>
19  <dg.Button label='Button'/>
20  <dg.Folder label='Folder' expanded={true}>
21    <dg.Text label='Text' value='Hello folder!'/>
22    <dg.Number label='Number' value={2}/>
23    <dg.Folder label='Subfolder' expanded={true}>
24      <dg.Text label='Text' value='Hello subfolder!'/>
25      <dg.Number label='Number' value={2}/>
26    </dg.Folder>
27  </dg.Folder>
28  <dg.Color label='Color' expanded={true} red={0} green={128} blue={255}/>
29  <dg.Gradient label='Gradient' expanded={true}/>
30</dg.GUI>

You can change the width of the labels and controls:

1<dg.GUI style={{ labelWidth: 100, controlWidth: 400 }}>
2  <dg.Gradient label='Gradient' expanded={true}/>
3</dg.GUI>

And you can position the whole thing:

1<dg.GUI style={{top: '0px', right: '0px'}}>
2  <dg.Gradient label='Gradient' expanded={true}/>
3</dg.GUI>
4
5<dg.GUI style={{top: '0px', left: '0px'}}>
6  <dg.Color label='Color' red={255} green={128} blue={64} expanded={true}/>
7</dg.GUI>
8
9<dg.GUI style={{bottom: '0px', right: '0px'}}>
10  <dg.Text label='Text' value='So many positions!'/>
11</dg.GUI>
12
13<dg.GUI style={{bottom: '0px', left: '0px'}}>
14  <dg.Number label='Number'/>
15</dg.GUI>

Colors

Color controls take red, green, and blue props as numbers from zero to 255:

1<dg.GUI>
2  <dg.Color label='Some blue color' red={64} green={128} blue={255}/>
3</dg.GUI>

...and return an object like the following in their onChange and onFinishChange events:

1{
2  red: 64,
3  green: 128,
4  blue: 255
5}

Color controls can be expanded by clicking on them, or you can pass the expanded prop a boolean to expand them by default:

1<dg.GUI>
2  <dg.Color label='Some blue color' red={64} green={128} blue={255} expanded={true}/>
3</dg.GUI>

Gradients

The Gradient control takes a stops prop, which is an array of objects that have red, green, blue, and stop properties. The color properties behave identically to the Color control, and the stop property is a number from zero to one that represents the position of the stop.

1<dg.GUI>
2  <dg.Gradient
3    label='The floor is lava!'
4    stops={[
5      {red: 255, green: 0, blue: 0, stop: 0},
6      {red: 255, green: 255, blue: 0, stop: 0.5},
7      {red: 255, green: 255, blue: 255, stop: 1.0},
8    ]}
9  />
10</dg.GUI>

Like the Color control, the Gradient control will expand when the user clicks it or if you add the expanded boolean property set to true:

1<dg.GUI>
2  <dg.Gradient
3    label='The floor is lava!'
4    stops={[
5      {red: 255, green: 0, blue: 0, stop: 0},
6      {red: 255, green: 255, blue: 0, stop: 0.5},
7      {red: 255, green: 255, blue: 255, stop: 1.0},
8    ]}
9    expanded={true}
10  />
11</dg.GUI>

Roadmap

• Add documentation about extending dis-gui-lifetoys.