1 | # Rendition
|
2 |
|
3 | [![npm version](https://badge.fury.io/js/rendition.svg)](http://badge.fury.io/js/rendition)
|
4 | [![Dependency Status](https://img.shields.io/david/balena-io-modules/rendition.svg)](https://david-dm.org/balena-io-modules/rendition)
|
5 | [![style: styled-components](https://img.shields.io/badge/style-%F0%9F%92%85%20styled--components-orange.svg?colorB=daa357&colorA=db748e)](https://github.com/styled-components/styled-components)
|
6 |
|
7 | A library of UI components, built using [React][react], [recompose][recompose], [styled-components][styled-components] and [styled-system][styled-system].
|
8 |
|
9 | ## Table of Contents
|
10 |
|
11 | * [Installation](#installation)
|
12 | * [Usage](#usage)
|
13 | * [Components](#components)
|
14 | * [Development](#development)
|
15 | * [Testing](#testing)
|
16 | * [Upgrading](#testing)
|
17 |
|
18 | ## Installation
|
19 |
|
20 | ```
|
21 | npm install --save rendition
|
22 | ```
|
23 |
|
24 | ## Usage
|
25 |
|
26 | Wrap your application in the `Provider` component and start using components!
|
27 |
|
28 | ```jsx
|
29 | import React from 'react'
|
30 | import ReactDOM from 'react-dom'
|
31 | import { Button, Box, Provider } from 'rendition';
|
32 |
|
33 | ReactDOM.render(
|
34 | <Provider>
|
35 | <Box my={3} mx={['auto', 15]}>
|
36 | <Button primary emphasized>Click me</Button>
|
37 | </Box>
|
38 | </Provider>,
|
39 | document.getElementById('root')
|
40 | );
|
41 | ```
|
42 |
|
43 | ## Components
|
44 |
|
45 | For an interactive demo of all components, see https://balena-io-modules.github.io/rendition
|
46 |
|
47 | - [Accordion](#accordion)
|
48 | - [Alert](#alert)
|
49 | - [ArcSlider](#arcslider)
|
50 | - [Badge](#badge)
|
51 | - [Banner](#banner)
|
52 | - [Box](#box)
|
53 | - [Button](#button)
|
54 | - [ButtonGroup](#buttongroup)
|
55 | - [Card](#card)
|
56 | - [Checkbox](#checkbox)
|
57 | - [Container](#container)
|
58 | - [Copy](#copy)
|
59 | - [Divider](#divider)
|
60 | - [DropDownButton](#dropdownbutton)
|
61 | - [Filters](#filters)
|
62 | - [Fixed](#fixed)
|
63 | - [Flex](#flex)
|
64 | - [Heading](#heading)
|
65 | - [HighlightedName](#highlightedname)
|
66 | - [Img](#img)
|
67 | - [Input](#input)
|
68 | - [Link](#link)
|
69 | - [List](#list)
|
70 | - [Modal](#modal)
|
71 | - [Navbar](#navbar)
|
72 | - [Notifications](#notifications)
|
73 | - [Pager](#pager)
|
74 | - [ProgressBar](#progressbar)
|
75 | - [RadioButton](#radiobutton)
|
76 | - [RadioButtonGroup](#radiobuttongroup)
|
77 | - [Search](#search)
|
78 | - [Select](#select)
|
79 | - [Spinner](#spinner)
|
80 | - [Steps](#steps)
|
81 | - [Table](#table)
|
82 | - [Tabs](#tabs)
|
83 | - [Tag](#tag)
|
84 | - [Terminal](#terminal)
|
85 | - [TextWithCopy](#textwithcopy)
|
86 | - [Textarea](#textarea)
|
87 | - [Tooltips](#tooltips)
|
88 | - [Txt](#txt)
|
89 | - [Markdown](#markdown)
|
90 | - [MarkdownEditor](#markdowneditor)
|
91 | - [Mermaid](#mermaid)
|
92 | - [Form](#form)
|
93 |
|
94 | ### Accordion
|
95 |
|
96 | [View story source](https://github.com/balena-io-modules/rendition/blob/master/src/components/Accordion/story.js)
|
97 |
|
98 | #### Props
|
99 |
|
100 | | Name | Type | Default | Required | Description |
|
101 | | ------ | ------ | --------- | ---------- | ------------- |
|
102 | | `items` | `[{label: string \| node; panel: string \| node }]` | - | true | renders label as title and panel as body of accordion |
|
103 |
|
104 | ### Alert
|
105 |
|
106 | [View story source](https://github.com/balena-io-modules/rendition/blob/master/src/components/Alert/story.js)
|
107 |
|
108 | #### Props
|
109 |
|
110 | | Name | Type | Default | Required | Description |
|
111 | | ------ | ------ | --------- | ---------- | ------------- |
|
112 | | `primary` | `boolean` | - | - | If true, use the `primary` theme color |
|
113 | | `secondary` | `boolean` | - | - | If true, use the `secondary` theme color |
|
114 | | `tertiary` | `boolean` | - | - | If true, use the `tertiary` theme color |
|
115 | | `quarternary` | `boolean` | - | - | If true, use the `quarternary` theme color |
|
116 | | `danger` | `boolean` | - | - | If true, use the `danger` theme color |
|
117 | | `warning` | `boolean` | - | - | If true, use the `warning` theme color |
|
118 | | `success` | `boolean` | - | - | If true, use the `success` theme color |
|
119 | | `info` | `boolean` | - | - | If true, use the `info` theme color |
|
120 | | `emphasized` | `boolean` | - | - | If true, use the use bolder colors and a larger size |
|
121 | | `plaintext` | `boolean` | - | - | If true, the alert will be rendered without a border or a background |
|
122 | | `prefix` | <code>JSX.Element | string | false</code> | - | - | Set a prefix on the alert message, if this prop is set to false, the default prefix will not be shown |
|
123 | | `onDismiss` | `() => void` | - | - | A function that is called when dismissing an alert
|
124 |
|
125 | ### ArcSlider
|
126 |
|
127 | A slider input that is displayed as an arc. This component will scale in size to
|
128 | fit it's container. A label can be added by placing a child element inside this
|
129 | component.
|
130 |
|
131 | [View story source](https://github.com/balena-io-modules/rendition/blob/master/src/components/ArcSlider/story.js)
|
132 |
|
133 | #### Props
|
134 |
|
135 | | Name | Type | Default | Required | Description |
|
136 | | --------------|-----------|-----------|------------|-------------------------------------------------------------- |
|
137 | | `onValueChange` | `(value: number) => void` | - | - | A function that is called when the slider value changes, this will always be a value between 0 and 1 |
|
138 | | `value` | `number` | - | - | A number between 0 and 1 that represents the progress |
|
139 | | `fillColor` | `string` | - | - | A CSS color string to use for the color of the "filled" part of the arc |
|
140 | | `background` | `string` | - | - | A CSS color string to use for the color of the arc track |
|
141 |
|
142 | #### Inheritance
|
143 |
|
144 | The properties of the [`Box`](#box) component are also available.
|
145 | ### Badge
|
146 |
|
147 | Badges should be used to present data that is not generated by the user (otherwise, tags should be used).
|
148 | The badge can use any of the pre-defined shades, from which the background and text color are generated.
|
149 |
|
150 | [View story source](https://github.com/balena-io-modules/rendition/blob/master/src/components/Badge/story.js)
|
151 |
|
152 | #### Props
|
153 |
|
154 | | Name | Type | Default | Required | Description |
|
155 | | ------ | ------ | --------- | ---------- | ------------- |
|
156 | | `shade` | `number` | - | - | The index for one of the pre-determined shades for the badge |
|
157 | | `children` | `string` | - | ✓ | The text to display inside the badge |
|
158 |
|
159 | ### Banner
|
160 |
|
161 | [View story source](https://github.com/balena-io-modules/rendition/blob/master/src/components/Banner/story.js)
|
162 |
|
163 | #### Props
|
164 |
|
165 | | Name | Type | Default | Required | Description |
|
166 | | ------ | ------ | --------- | ---------- | ------------- |
|
167 | | `backgroundImage`| `string`| - | - | The path to an image that should be displayed in the background |
|
168 | | `minHeight`| `string`| - | - | The minimum height of the `Banner`, eg `180px` |
|
169 |
|
170 |
|
171 | ### Box
|
172 |
|
173 | Displays a block level element.
|
174 |
|
175 | The basic building block of a rendition application.
|
176 |
|
177 | [View story source](https://github.com/balena-io-modules/rendition/blob/master/src/components/Grid/Box.js)
|
178 |
|
179 | #### Props
|
180 |
|
181 | | Name | Type | Default | Required | Description |
|
182 | | ------ | ------ | --------- | ---------- | ------------- |
|
183 | | `flex` | <code>string | string[]</code> | - | - | Sets `flex`, if the value is an array, sets a responsive style corresponding to the theme's breakpoints
|
184 | | `order` | <code>number | string | Array<number | string></code> | - | - | Sets `order`, if the value is an array, sets a responsive style corresponding to the theme's breakpoints
|
185 |
|
186 |
|
187 | ### Button
|
188 |
|
189 | [View story source](https://github.com/balena-io-modules/rendition/blob/master/src/components/Button/story.js)
|
190 |
|
191 | #### Props
|
192 |
|
193 | | Name | Type | Default | Required | Description |
|
194 | | ------ | ------ | --------- | ---------- | ------------- |
|
195 | | `primary` | `boolean` | - | - | If true, use the `primary` theme color |
|
196 | | `secondary` | `boolean` | - | - | If true, use the `secondary` theme color |
|
197 | | `tertiary` | `boolean` | - | - | If true, use the `tertiary` theme color |
|
198 | | `quarternary` | `boolean` | - | - | If true, use the `quarternary` theme color |
|
199 | | `danger` | `boolean` | - | - | If true, use the `danger` theme color |
|
200 | | `warning` | `boolean` | - | - | If true, use the `warning` theme color |
|
201 | | `success` | `boolean` | - | - | If true, use the `success` theme color |
|
202 | | `info` | `boolean` | - | - | If true, use the `info` theme color |
|
203 | | `light` | `boolean` | - | - | If true, use white background and default text color |
|
204 | | `disabled` | `boolean` | - | - | If true, disabled the button |
|
205 | | `outline` | `boolean` | - | - | If true, the button will have a transparent background, and the border and text color will match |
|
206 | | `plain` | `boolean` | - | - | If true, render the button without padding, background or border |
|
207 | | `underline` | `boolean` | - | - | Similar to the `plaintext` prop, but displays a line underneath the button text |
|
208 | | `icon` | `JSX.Element` | - | - | Optionally provide a JSX element that will be rendered before the text inside the button |
|
209 | | `compact` | `boolean[]` | [false] | - | Optionally renders the label according to the value inside the array for each breakpoint |
|
210 |
|
211 | ### ButtonGroup
|
212 |
|
213 | Wrapper for buttons to make them stick together.
|
214 |
|
215 | [View story source](https://github.com/balena-io-modules/rendition/blob/master/src/components/ButtonGroup/story.js)
|
216 | ### Card
|
217 |
|
218 | Section containing content and actions on the same topic.
|
219 |
|
220 | [View story source](https://github.com/balena-io-modules/rendition/blob/master/src/components/Card/story.js)
|
221 |
|
222 | #### Props
|
223 |
|
224 | | Name | Type | Default | Required | Description |
|
225 | | -------|--------|-----------|------------|-------------- |
|
226 | | `title` | `string` | - | - | The title of the card |
|
227 | | `cta` | `JSX.Element` | - | - | React component added to the header |
|
228 | | `rows` | `JSX.Element[]` | - | - | Subsections separated by a horizontal separator |
|
229 | | `minHeight` | `string` | `auto` | - | CSS minHeight property |
|
230 | | `small` | `boolean` | - | - | If true, reduces the scale of the card |
|
231 | | `children` | `JSX.Element` | - | - | Any content that is internally wrapped in a Box |
|
232 |
|
233 | ### Checkbox
|
234 |
|
235 | [View story source](https://github.com/balena-io-modules/rendition/blob/master/src/components/Checkbox/story.js)
|
236 |
|
237 | #### Props
|
238 |
|
239 | `Checkbox` implements all properties from [Grommet's CheckBox component](https://v2.grommet.io/checkbox)
|
240 |
|
241 | ### Container
|
242 |
|
243 | A padded container with a responsive width.
|
244 |
|
245 | [View story source](https://github.com/balena-io-modules/rendition/blob/master/src/components/Container/story.js)
|
246 |
|
247 |
|
248 | ### Copy
|
249 |
|
250 | Wrapper that adds a "copy to clipboard" button to any component and copies the passed content to the user's clipboard.
|
251 |
|
252 | [View story source](https://github.com/balena-io-modules/rendition/blob/master/src/components/Copy/story.js)
|
253 |
|
254 | #### Props
|
255 |
|
256 | | Name | Type | Default | Required | Description |
|
257 | | ------ | ------ | --------- | ---------- | ------------- |
|
258 | | `content` | `string` | - | ✓ | The value that should be copied to the clipboard
|
259 | | `show` | <code>'hover' | 'always'</code> | - | - | Optionally show the copy button on hover or always show the button
|
260 | | `onClick` | `(content: string) => void` | - | - | onClick handler, useful if you wish to do other actions after content was copied
|
261 | | `children` | `React.ReactNode` | - | - | The content next to which the clipboard button should be shown
|
262 |
|
263 | ### Divider
|
264 |
|
265 | A styled horizontal rule.
|
266 |
|
267 | [View story source](https://github.com/balena-io-modules/rendition/blob/master/src/components/Divider/story.js)
|
268 |
|
269 | #### Props
|
270 |
|
271 | | Name | Type | Default | Required | Description |
|
272 | | -------|--------|-----------|------------|-------------- |
|
273 | | `height` | `number` | `0.5` | - | The height of the divider |
|
274 | | `color` | `string` | `quartenary.main` | - | The color of the divider |
|
275 | | `type` | `'solid' | 'dashed'` | `'solid` | - | The type of divider |
|
276 | | `children` | `string` | - | - | Textual explanation to go in the middle of the divider |
|
277 |
|
278 |
|
279 | ### DropDownButton
|
280 |
|
281 | Displays a button with an attached dropdown list, `children` of the component
|
282 | are rendered inside a dropdown list.
|
283 |
|
284 | [View story source](https://github.com/balena-io-modules/rendition/blob/master/src/components/DropDownButton/story.js)
|
285 |
|
286 | #### Props
|
287 |
|
288 | | Name | Type | Default | Required | Description |
|
289 | | ------------- | ------ | --------- | ---------- | ------------- |
|
290 | | `primary` | `boolean` | - | - | If true, use the `primary` theme color |
|
291 | | `secondary` | `boolean` | - | - | If true, use the `secondary` theme color |
|
292 | | `tertiary` | `boolean` | - | - | If true, use the `tertiary` theme color |
|
293 | | `quarternary` | `boolean` | - | - | If true, use the `quarternary` theme color |
|
294 | | `danger` | `boolean` | - | - | If true, use the `danger` theme color |
|
295 | | `warning` | `boolean` | - | - | If true, use the `warning` theme color |
|
296 | | `success` | `boolean` | - | - | If true, use the `success` theme color |
|
297 | | `info` | `boolean` | - | - | If true, use the `info` theme color |
|
298 | | `emphasized` | `boolean` | - | - | If true, use a larger size |
|
299 | | `square` | `boolean` | - | - | If true, render the button with equal length width and height |
|
300 | | `disabled` | `boolean` | - | - | If true, disabled the button |
|
301 | | `label` | `JSX.Element` | - | - | Optionally provide a JSX element that will be displayed inside the main button |
|
302 | | `border` | `boolean` | - | - | If true, place a border between each item in the dropdown |
|
303 | | `joined` | `boolean` | - | - | If true, render the component as a single button instead of two |
|
304 | | `noListFormat` | `boolean` | - | - | If true, render children as a single JSX element instead of iterating over each of them |
|
305 | | `alignRight` | `boolean` | - | - | If true, put the dropdown list on the right |
|
306 | | `listMaxHeight` | `string \| number` | - | - | If setted, it defines the maximum height of the dropdown list |
|
307 | | `compact` | `boolean[]` | [false] | - | Optionally renders the label according to the value inside the array for each breakpoint |
|
308 |
|
309 | ### Filters
|
310 |
|
311 | A component that can be used for generating filters in the form of [json schema](http://json-schema.org/) objects and saving sets of filters as "views".
|
312 | The filters created by this component can be used to filter a collection of
|
313 | objects using the `SchemaSieve` object.
|
314 |
|
315 | [View story source](https://github.com/balena-io-modules/rendition/blob/master/src/components/Filters/story.js)
|
316 |
|
317 | #### Schema
|
318 |
|
319 | The `Filters` component requires a `schema` property which should be a json
|
320 | schema that defines the shape of the objects you want to filter. For example if
|
321 | you want to filter on a collection that looks like this:
|
322 |
|
323 | ```
|
324 | [
|
325 | {
|
326 | name: 'Bulbasaur',
|
327 | caught: true,
|
328 | },
|
329 | {
|
330 | name: 'Pikachu',
|
331 | caught: true,
|
332 | },
|
333 | {
|
334 | name: 'Dratini',
|
335 | caught: false,
|
336 | }
|
337 | ]
|
338 | ```
|
339 |
|
340 | You would define a schema that looks like this:
|
341 |
|
342 | ```
|
343 | {
|
344 | type: 'object',
|
345 | properties: {
|
346 | name: {
|
347 | title: 'Name',
|
348 | type: 'string'
|
349 | },
|
350 | caught: {
|
351 | title: 'Has been caught',
|
352 | type: 'boolean'
|
353 | }
|
354 | }
|
355 | }
|
356 | ```
|
357 |
|
358 | If you provide a `title` property, it will be used to label the field when
|
359 | filtering, otherwise the field name will be used.
|
360 |
|
361 | ##### Views
|
362 |
|
363 | Views represent a set of filters, along with an id and a name. This is a useful
|
364 | feature for storing a set filters and loading it again at a later point.
|
365 | A view can optionally have a `scope` property, which will correspond to the
|
366 | `slug` of a view scope, if you have provided one in the `Filters` property
|
367 | `viewScopes` property. Scopes allow you to easily add an extra layer of
|
368 | granularity/grouping to views that are generated. If you provide view scopes,
|
369 | the user can select a scope when creating a new view.
|
370 |
|
371 | A view scope has the following properties:
|
372 |
|
373 | | Name | Type | Description |
|
374 | | ------------- | --------- | ---------------------------------------------------- |
|
375 | | slug | `string` | A unique identifier for the scope |
|
376 | | name | `string` | A descriptive name for the scope |
|
377 | | label | `string` | An optional label to use for this scope when creating a view |
|
378 |
|
379 | A view has the following properties:
|
380 |
|
381 | | Name | Type | Description |
|
382 | | ------------- | --------- | ---------------------------------------------------- |
|
383 | | id | `string` | A unique identifier for the view |
|
384 | | name | `string` | A descriptive name for the view |
|
385 | | filters | `string` | An array of json schemas |
|
386 | | scope | <code>string | null</code> | The slug of a view scope, or `null` if now scopes are provided |
|
387 |
|
388 | #### Props
|
389 |
|
390 | | Name | Type | Default | Required | Description |
|
391 | | ------ | ------ | --------- | ---------- | ------------- |
|
392 | | `schema` | `object` | - | ✓ | A json schema describing the shape of the objects you want to filter |
|
393 | | `disabled` | `boolean` | - | - | If true, disable the entire `Filters` interface
|
394 | | `filters` | `object[]` | - | - | An array of json schemas to be displayed as the currently selected filters, typically used when loading when loading filters from storage |
|
395 | | `views` | `object[]` | - | - | An array of views, as described above, typically used when loading when loading views from storage |
|
396 | | `viewScopes` | `object[]` | - | - | An array of view scopes, as described above |
|
397 | | `onFiltersUpdate` | `(filters: object[]) => void` | - | - | A function that is called when filters are updated |
|
398 | | `onViewsUpdate` | `(views: object[]) => void` | - | - | A function that is called when views are updated |
|
399 | | `addFilterButtonProps` | `object` | - | - | Properties that are passed to the "Add filter" button, these are the same props used for the [`Button`](#button) component |
|
400 | | `viewsMenuButtonProps` | `object` | - | - | Properties that are passed to the "Views" button, these are the same props used for the [`DropDownButton`](#dropdownbutton) component |
|
401 | | `renderMode` | <code>string | string[]</code> | - | - | Controls which parts of the `Filters` interface are displayed. One of `all`, `add`, `search`, `views`, `summary`, or an array containing any of these values |
|
402 | | `dark` | `boolean` | - | - | If true, Set the `Filters` component against a dark background |
|
403 | | `compact` | `boolean[]` | - | - | Accept a boolean for each rendition breakpoint. If true remove `Filters` labels |
|
404 | ### Fixed
|
405 |
|
406 | Displays an element with a [`fixed`](https://developer.mozilla.org/en-US/docs/Web/CSS/position#fixed) position.
|
407 |
|
408 | [View story source](https://github.com/balena-io-modules/rendition/blob/master/src/components/Fixed/story.js)
|
409 |
|
410 | #### Props
|
411 |
|
412 | | Name | Type | Default | Required | Description |
|
413 | | ------ | ------ | --------- | ---------- | ------------- |
|
414 | | `top` | <code>boolean | ResponsiveStyle</code> | - | - | Sets the distance to the top of the containing block. If true, sets the value to zero
|
415 | | `right` | <code>boolean | ResponsiveStyle</code> | - | - | Sets the distance to the right of the containing block. If true, sets the value to zero
|
416 | | `bottom` | <code>boolean | ResponsiveStyle</code> | - | - | Sets the distance to the bottom of the containing block. If true, sets the value to zero
|
417 | | `left` | <code>boolean | ResponsiveStyle</code> | - | - | Sets the distance to the left of the containing block. If true, sets the value to zero
|
418 | | `z` | `ResponsiveStyle` | - | - | Sets the z-index of the component |
|
419 | ### Flex
|
420 |
|
421 | Displays an element using [flexbox](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Flexible_Box_Layout/Basic_Concepts_of_Flexbox).
|
422 |
|
423 | [View story source](https://github.com/balena-io-modules/rendition/blob/master/src/components/Grid/Flex.js)
|
424 |
|
425 | #### Props
|
426 |
|
427 | | Name | Type | Default | Required | Description |
|
428 | | ------ | ------ | --------- | ---------- | ------------- |
|
429 | | `alignItems` | <code>string | string[]</code> | - | - | Sets `align-items`, if the value is an array, sets a responsive style corresponding to the theme's breakpoints
|
430 | | `justifyContent` | <code>string | string[]</code> | - | - | Sets `justify-content`, if the value is an array, sets a responsive style corresponding to the theme's breakpoints
|
431 | | `flexDirection` | <code>string | string[]</code> | - | - | Sets `flex-direction`, if the value is an array, sets a responsive style corresponding to the theme's breakpoints
|
432 | | `flexWrap` | <code>string | string[]</code> | - | - | Sets `flex-wrap` css property
|
433 | ### Heading
|
434 |
|
435 | A component that displays a heading. By default an `<h3>` tag is used. The exact
|
436 | heading type can be specifed by appending the element name to the component, for
|
437 | example `<Heading.h1>`, `<Heading.h2>`, `<Heading.h3>` etc.
|
438 |
|
439 | [View story source](https://github.com/balena-io-modules/rendition/blob/master/src/components/Heading/story.js)
|
440 |
|
441 | ### HighlightedName
|
442 |
|
443 | By default, the background color of a `HighlightedName` component is generated
|
444 | automatically from its `children` (which must be a string), though this can be overridden.
|
445 |
|
446 | [View story source](https://github.com/balena-io-modules/rendition/blob/master/src/components/HighlightedName/story.js)
|
447 |
|
448 | #### Props
|
449 |
|
450 | | Name | Type | Default | Required | Description |
|
451 | |------------|----------|-------------------------------------|----------|-----------------------------------------------------|
|
452 | | `children` | `string` | - | ✓ | The text to display inside the highlighted name |
|
453 | | `bg` | `string` | autogenerated from `children` | - | If passed, it will be used as the background color of the component |
|
454 | | `color` | `string` | `theme.colors.text.main` or `white` | - | If passed, it will be used as the text color of the component |
|
455 |
|
456 | ### Img
|
457 |
|
458 | Displays an image.
|
459 |
|
460 | [View story source](https://github.com/balena-io-modules/rendition/blob/master/src/components/Img/story.js)
|
461 |
|
462 | #### Inheritance
|
463 |
|
464 | The attributes of an [`<img>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img) element are also available.
|
465 |
|
466 | ### Input
|
467 |
|
468 | [View story source](https://github.com/balena-io-modules/rendition/blob/master/src/components/Input/story.js)
|
469 |
|
470 | #### Props
|
471 |
|
472 | | Name | Type | Default | Required | Description |
|
473 | | ------ | ------ | --------- | ---------- | ------------- |
|
474 | | `emphasized` | `boolean` | - | - | If true, use a larger size |
|
475 | | `monospace` | `boolean` | - | - | If true, render text in a monospace font |
|
476 | | `onChange` | `(e: Event) => void` | - | - | A function that is called when the input value changes |
|
477 |
|
478 | #### Inheritance
|
479 |
|
480 | The attributes of an [`<input>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input) element are also available.
|
481 |
|
482 |
|
483 |
|
484 | ### Link
|
485 |
|
486 | Displays an anchor link.
|
487 |
|
488 | [View story source](https://github.com/balena-io-modules/rendition/blob/master/src/components/Link/story.js)
|
489 |
|
490 | #### Props
|
491 |
|
492 | | Name | Type | Default | Required | Description |
|
493 | | ------ | ------ | --------- | ---------- | ------------- |
|
494 | | `blank` | `boolean` | - | - | If true, open the link in a new tab |
|
495 | | `disabled` | `boolean` | - | - | If true, disable the link |
|
496 |
|
497 | #### Inheritance
|
498 |
|
499 | The attributes of an [`<a>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a) element are also available.
|
500 |
|
501 |
|
502 | ### List
|
503 |
|
504 | [View story source](https://github.com/balena-io-modules/rendition/blob/master/src/components/List/story.js)
|
505 |
|
506 | #### Props
|
507 |
|
508 | | Name | Type | Default | Required | Description |
|
509 | | ------ | ------ | --------- | ---------- | ------------- |
|
510 | | `children` | `ReactNode` | - | - | Each child represents a list item |
|
511 | | `ordered` | `boolean` | - | - | If true, render an ordered (numbered) list, otherwise render a bullet list |
|
512 |
|
513 |
|
514 |
|
515 |
|
516 | ### Modal
|
517 |
|
518 | Displays a centrally position modal overlay. Children passed to this component
|
519 | are rendered inside the modal.
|
520 |
|
521 | [View story source](https://github.com/balena-io-modules/rendition/blob/master/src/components/Modal/story.js)
|
522 |
|
523 | #### Props
|
524 |
|
525 | | Name | Type | Default | Required | Description |
|
526 | | --------------|-----------|-----------|------------|----------------------------------------------------- |
|
527 | | `title` | `string`
|
528 | | - | - | A title to display at the top of the Modal, only displayed if the `titleElement` property is not used |
|
529 | | `titleElement` | <code>string | JSX.Element</code> | - | - | A string or JSX element to display at the top of the modal |
|
530 | | `titleDetails` | <code>string | JSX.Element</code> | - | - | A string or JSX element to display underneath the modal's `title`, only displayed if the `titleElement` property is not used and a `title` property is provided |
|
531 | | `action` | <code>string | JSX.Element</code> | - | - | A string or JSX element to display in the primary modal button, defaults to 'OK' |
|
532 | | `cancel` | `() => any` | - | - | A function that is called if the modal is dismissed |
|
533 | | `done` | `() => any` | - | ✓ | A function that is called if the primary modal button is clicked |
|
534 | | `primaryButtonProps` | `object` | - | - | Properties that are passed to the primary button, these are the same props used for the [`Button`](#button) component |
|
535 | | `secondaryButtonProps` | `object` | - | - | If provided, will cause a secondary button to appear on the modal. These properties that are passed to that button, these are the same props used for the [`Button`](#button) component |
|
536 | | `cancelButtonProps` | `object` | - | - | Properties that are passed to the cancel button, these are the same props used for the [`Button`](#button) component |
|
537 | | style | `object` | - | - | Apply custom styles to Modal, the object is applied as a [`style` attribute](https://reactjs.org/docs/dom-elements.html#style) |
|
538 | | position | <code>'center' | 'top'</code> | - | - | Start the modal from the center (default) or top |
|
539 |
|
540 | ### Navbar
|
541 |
|
542 | A component used to render a navigation bar.
|
543 |
|
544 | [View story source](https://github.com/balena-io-modules/rendition/blob/master/src/components/Navbar/story.js)
|
545 |
|
546 | #### Props
|
547 |
|
548 | | Name | Type | Default | Required | Description |
|
549 | | ------ | ------ | --------- | ---------- | ------------- |
|
550 | | `brand` | `JSX.Element` | - | ✓ | A JSX element used as the main branding in the navbar |
|
551 |
|
552 | ### Notifications
|
553 |
|
554 | To use this component, you first need to add the `NotificationsContainer` component at the root of your React application.
|
555 | You can then programatically add or remove notifications using the `notifications` module. For example:
|
556 |
|
557 | ```
|
558 | import {notifications} from 'rendition';
|
559 |
|
560 | const notificationId = notifications.addNotification("Hi there");
|
561 | notifications.removeNotification(notificationId);
|
562 | ```
|
563 |
|
564 | [View story source](https://github.com/balena-io-modules/rendition/blob/master/src/components/Notifications/story.js)
|
565 |
|
566 | #### Props
|
567 |
|
568 | The `NotificationsContainer` component doesn't take any props. You do all customizations on a per-notification basis.
|
569 | The `addNotification` function can take either a valid React node component, or the following options:
|
570 |
|
571 | | Name | Type | Default | Required | Description |
|
572 | | ------ | ------ | --------- | ---------- | ------------- |
|
573 | | `content` | `React.ReactNode` | - | ✓ | The content you wish to display in the notification |
|
574 | | `duration`| `number` | 6000 | - | The duration this notification will be shown for in `ms`. `0` means it will never close automatically |
|
575 | | `id` | `number` | (random) | - | A custom id for the notification |
|
576 | | `baselineHeight` | `number` | Normal text line height | - | The base height of the content, used to align the dismiss button correctly |
|
577 | | `onDismiss` | `() => void` | | - | A callback function that is triggered when the "dismiss" button is clicked |
|
578 | ### Pager
|
579 |
|
580 | Displays a pager widget.
|
581 |
|
582 | [View story source](https://github.com/balena-io-modules/rendition/blob/master/src/components/Pager/story.js)
|
583 |
|
584 | #### Props
|
585 |
|
586 | | Name | Type | Default | Required | Description |
|
587 | | ------ | ------ | --------- | ---------- | ------------- |
|
588 | | `totalItems` | `number` | - | - | The total number of items to split into pages |
|
589 | | `itemsPerPage`| `number` | - | - | The number of items on each page |
|
590 | | `page` | `number` | - | - | The current page (zero-indexed) |
|
591 | | `nextPage` | `() => void` | - | - | Callback invoked when the "next page" button is clicked
|
592 | | `prevPage` | `() => void` | - | - | Callback invoked when the "previous page" button is clicked
|
593 |
|
594 | ### ProgressBar
|
595 |
|
596 | Displays a progress bar using a value representing a percentage.
|
597 |
|
598 | [View story source](https://github.com/balena-io-modules/rendition/blob/master/src/components/ProgressBar/story.js)
|
599 |
|
600 | #### Props
|
601 |
|
602 | | Name | Type | Default | Required | Description |
|
603 | | --------------|-----------|-----------|------------|-------------------------------------------------------------- |
|
604 | | `primary` | `boolean` | `true` | - | If true, use the `primary` theme color |
|
605 | | `secondary` | `boolean` | - | - | If true, use the `secondary` theme color |
|
606 | | `tertiary` | `boolean` | - | - | If true, use the `tertiary` theme color |
|
607 | | `quarternary` | `boolean` | - | - | If true, use the `quarternary` theme color |
|
608 | | `danger` | `boolean` | - | - | If true, use the `danger` theme color |
|
609 | | `warning` | `boolean` | - | - | If true, use the `warning` theme color |
|
610 | | `success` | `boolean` | - | - | If true, use the `success` theme color |
|
611 | | `info` | `boolean` | - | - | If true, use the `info` theme color |
|
612 | | `emphasized` | `boolean` | - | - | If true, use a larger size |
|
613 | | `value` | `number` | - | ✓ | A value between 1 and 100 that represents the progress |
|
614 | | background | `string` | - | - | A CSS color string to use for the progress bar |
|
615 | | color | `string` | - | - | A CSS color string to use for the content of the progress bar |
|
616 |
|
617 | ### RadioButton
|
618 |
|
619 | [View story source](https://github.com/balena-io-modules/rendition/blob/master/src/components/RadioButton/story.js)
|
620 |
|
621 | #### Props
|
622 |
|
623 | | Name | Type | Default | Required | Description |
|
624 | | ------ | ------ | --------- | ---------- | ------------- |
|
625 | | `checked` | `boolean` | - | - | If true, render the radio button as checked |
|
626 | | `disabled` | `boolean` | - | - | If true, set the radio button as disabled |
|
627 | | `label` | `string` | - | - | The label to render next to the radio button |
|
628 | | `onChange` | `(event: Event) => void` | - | - | Function called when the value of the radio button changes |
|
629 |
|
630 |
|
631 | ### RadioButtonGroup
|
632 |
|
633 | [View story source](https://github.com/balena-io-modules/rendition/blob/master/src/components/Search/story.js)
|
634 |
|
635 | #### Props
|
636 |
|
637 | | Name | Type | Default | Required | Description |
|
638 | | ------ | ------ | --------- | ---------- | ------------- |
|
639 | | `value` | `string` | - | - | Currently selected option value |
|
640 | | `options` | `["string"] | [{"disabled": boolean, "id": string, "label": string, "name": string, "value": string}]` | - | - | Settings for each radio button |
|
641 | | `onChange` | `(event: Event) => void` | - | - | Function called when the value of the radio button changes |
|
642 |
|
643 |
|
644 | ### Search
|
645 |
|
646 | Displays an input styled as a search bar.
|
647 |
|
648 | [View story source](https://github.com/balena-io-modules/rendition/blob/master/src/components/Search/story.js)
|
649 |
|
650 | #### Props
|
651 |
|
652 | | Name | Type | Default | Required | Description |
|
653 | | ------ | ------ | --------- | ---------- | ------------- |
|
654 | | `dark` | `boolean` | - | - | If true, uses a light colorscheme for use on a dark background |
|
655 | | `disabled` | `boolean` | - | - | If true, disable the input |
|
656 | | `placeholder` | `string` | - | - | A placeholder to use in the input |
|
657 | | `value` | `string` | - | ✓ | The value of the input |
|
658 | | `onChange` | `(event: Event) => void` | - | ✓ | A function that is called when the input changes |
|
659 |
|
660 | ### Select
|
661 |
|
662 | [View story source](https://github.com/balena-io-modules/rendition/blob/master/src/components/Select/story.js)
|
663 |
|
664 | #### Props
|
665 |
|
666 | You can refer to the [grommet select page](https://v2.grommet.io/select) for all possible props.
|
667 |
|
668 | ##### Excluded props are:
|
669 |
|
670 | `'size' | 'selected' | 'focusIndicator' | 'margin'`
|
671 |
|
672 |
|
673 | ##### Additional props are:
|
674 |
|
675 | | Name | Type | Default | Required | Description |
|
676 | | ------ | ------ | --------- | ---------- | ------------- |
|
677 | | `emphasized` | `boolean` | - | - | If true, use a larger size |
|
678 |
|
679 |
|
680 |
|
681 | ### Spinner
|
682 |
|
683 | [View story source](https://github.com/balena-io-modules/rendition/blob/master/src/components/Spinner/story.js)
|
684 |
|
685 | #### Props
|
686 |
|
687 | | Name | Type | Default | Required | Description |
|
688 | | ------ | ------ | --------- | ---------- | ------------- |
|
689 | | `children` | `React.ReactNode` | | - | If the spinner has children, it will show an opaque overlay over the children when it is spinning |
|
690 | | `show` | `boolean` | true | - | If passed, it will control whether the spinner is shown or not |
|
691 | | `emphasized` | `boolean` | false | - | If true, it will render a large spinner |
|
692 | | `label` | `string` \| `React.ReactNode`| | - | A label that will be rendered next to the spinner. Renders on right-hand side for standard spinner, and below spinner for emphasized |
|
693 | ### Steps
|
694 |
|
695 | A visual guide showing a number of steps to be performed by the user. The `Steps` component takes one or more `Step` components as children.
|
696 |
|
697 | If the `ordered` prop is `true`, the steps will be considered as an ordered (numbered) list. In this case, the `activeStepIndex` must be set and the `onClick` callback prop of the child `Step` components used to update the `activeStepIndex`.
|
698 |
|
699 | [View story source](https://github.com/balena-io-modules/rendition/blob/master/src/components/Steps/story.js)
|
700 |
|
701 | #### Props
|
702 |
|
703 | | Name | Type | Default | Required | Description |
|
704 | | ------------- | ------------- | --------- | ---------- | ----------- |
|
705 | | `children` | `Array<Step>` | - | - | The step components that form this sequence of steps |
|
706 | | `titleText` | `string` | - | - | If passed, the steps will have a title at the beginning |
|
707 | | `titleIcon` | `ReactNode` | - | - | If passed, an icon will be shown next to the title text, or on its own if there is no title text passed |
|
708 | | `onClose` | `() => void` | - | - | Function that is called when a user clicks on the close button, if not passed, no close button will be rendered |
|
709 | | `bordered` | `boolean` | `true` | - | If true (default), the steps container will have a visible border |
|
710 | | `ordered` | `boolean` | `false` | - | If true, the steps will be treated as an ordered list. Instead of the check icon, pending ordered steps will be displayed with a grey step number and active ordered steps with a blue step number.
|
711 | | `activeStepIndex` | `number` | - | - | If passed, specifies the step that is currently active. Only use with the `ordered` prop |
|
712 |
|
713 | ##### Step Props
|
714 |
|
715 | | Name | Type | Default | Required | Description |
|
716 | | ---------- | ---------------------------------- | ------- | ---------- | ----------- |
|
717 | | `children` | `string` | - | ✓ | The text of the step |
|
718 | | `status` | `'pending' | 'completed' | 'none'` | - | ✓ | Whether the step has been completed or is still pending |
|
719 | | `onClick` | () => void | - | - | If passed, the step will be clickable. _Note: If the steps are ordered, this callback should be used to update the `activeStepIndex` prop passed to the `Steps` component._ |
|
720 |
|
721 | ### Table
|
722 |
|
723 | A component used to generate a styled table.
|
724 |
|
725 | [View story source](https://github.com/balena-io-modules/rendition/blob/master/src/components/Table/story.js)
|
726 |
|
727 | #### Columns
|
728 |
|
729 | The `columns` property defines what columns the table should display, how they
|
730 | are rendered and whether or not the column is sortable.
|
731 |
|
732 | The `columns` property should be an array of objects with the following properties:
|
733 |
|
734 | | Name | Type | Required | Description |
|
735 | | ------------- | --------- | -------- | ---------------------------------------------------- |
|
736 | | field | `keyof T` | ✓ | The name of the field this column should render, this should correspond to a key on the objects passed to the `data` property of the `Table` component |
|
737 | | cellAttributes | <code>object | (value: any, row: T) => object</code> | - | Attributes that are passed to each cell in this column. This can also be a function, which will be called with the value of the `field` provided and the row data (`T`) |
|
738 | | label | <code>string | JSX.Element</code> | - | A string or JSX element that will be used to display the name of the column. If this property is not provided, the `field` property will be used instead |
|
739 | | render | <code>(value: any, row: T) => string | number | number | JSX.Element | null</code> | - | Use a custom render function to display the value in each column cell. This function will be called with the value of the `field` provided and the row data (`T`) |
|
740 | | sortable | <code>boolean | (a: T, b: T) => number</code> | - | If true, the column will be sortable using an alphanumeric sort, alternatively a function can be provided allowing finer grained control over sorting |
|
741 |
|
742 | #### Notes
|
743 |
|
744 | For performance reasons table rows are only re-rendered if the row properties
|
745 | have changed. For this reason, rows **will not** re-render if their properties
|
746 | are mutated: you should clone the item instead, for example:
|
747 |
|
748 | ```js
|
749 | update (index) {
|
750 | const newData = this.state.data
|
751 | const element = newData[index]
|
752 | newData[index] = Object.assign({}, element, { active: !element.active })
|
753 | this.setState({ data: newData })
|
754 | }
|
755 | ```
|
756 |
|
757 | See the **Updating data in a table** story for an example of how this can be
|
758 | done using a high order component.
|
759 |
|
760 | Additionally, because of this rendering behaviour the `render()` functions in
|
761 | the `Table` component's `columns` property should only use values provided to
|
762 | the render function.
|
763 | When `render()` functions are provided, they must act like pure functions with
|
764 | respect to their props. They should only rely on their arguments to generate
|
765 | their output and not use any context variables. If you are using a context
|
766 | variable in your `render()` function, then changes to that variable will not
|
767 | cause a re-render of the component and will not be reflected on the table.
|
768 |
|
769 | #### Props
|
770 |
|
771 | | Name | Type | Default | Required | Description |
|
772 | | ------------- | --------- | --------- | ---------- | ---------------------------------------------------- |
|
773 | | `columns` | `object[]` | - | ✓ | An array of column objects, as described above |
|
774 | | `data` | `T[]` | - | ✓ | An array of objects that will be displayed in the table |
|
775 | | `getRowHref` | `(row: T) => string` | - | - | If provided, each row in the table will be a clickable link, this function is used to create the link href |
|
776 | | `onCheck` | `(checkedItems: T[]) => string` | - | - | If provided, each row will begin with a checkbox. This function is called with every checked row every time a checkbox is toggled on or off. This property requires that you have provided a `rowKey` property |
|
777 | | `onRowClick` | `(row: T, event: Event) => void` | - | - | A function that is called when a row is clicked. This property requires that you have provided a `rowKey` property |
|
778 | | `onSort` | `(sort: TableSortOptions<T>) => void` | - | - | A function that is called when a column is sorted |
|
779 | | `onPageChange` | `(page: number) => void` | - | - | A function that is called when the page is incremented, decremented and reset |
|
780 | | `sort` | `TableSortOptions<T>` | - | - | sort options to be used both as a default sort, and on subsequent renders if the passed sort changes |
|
781 | | `rowAnchorAttributes` | `object` | - | - | Attributes to pass to the anchor element used in a row |
|
782 | | `rowCheckboxAttributes` | `object` | - | - | Attributes to pass to the checkbox element used in a row |
|
783 | | `rowKey` | `key of T` | - | - | A field on a row that contains a unique identifier, can help speed up render performance and is required for the `onCheck` property |
|
784 | | `toBodyPrefix` | <code>JSX.element | JSX.Element</code> | - | - | JSX element(s) to display at the top of the table body |
|
785 | | `highlightedRows` | <code>*[]</code> | - | - | Highlights one or more rows. This property requires that you have provided a `rowKey` property: the row with a `rowKey` property that matches one of these values is highlighted.
|
786 | | `usePager` | `boolean` | - | - | If true, a pager will be used when displaying items.
|
787 | | `itemsPerPage` | `number` | `50` | - | The number of items to be shown per page. Only used if `usePager` is true. Defaults to `50`.
|
788 | | `pagerPosition` | <code>'top' | 'bottom' | 'both'</code> | `top` | - | Sets wether the pager is displayed at the top of the table, the bottom of the table or in both positions. Only used if `usePager` is true. Defaults to `top`.
|
789 |
|
790 | #### Programmatically selecting rows
|
791 |
|
792 | The component has a `setRowSelection` method that can be accesssed via <a href='https://reactjs.org/docs/refs-and-the-dom.html' target='_blank' rel='noopener'>ref</a>.
|
793 |
|
794 | It will accept an array of rows `T[]`, or an empty array in order to clear the selection.
|
795 |
|
796 | This method requires that you have provided a `rowKey` property.
|
797 |
|
798 | ### Tabs
|
799 |
|
800 | A component used to render tabbed children components.
|
801 |
|
802 | [View story source](https://github.com/balena-io-modules/rendition/blob/master/src/components/Tabs/story.js)
|
803 |
|
804 | ### Tag
|
805 |
|
806 | Represents a name-value pair with an optional operator between.
|
807 |
|
808 | [View story source](https://github.com/balena-io-modules/rendition/blob/master/src/components/Tag/story.js)
|
809 |
|
810 | #### Props
|
811 |
|
812 | | Name | Type | Default | Required | Description |
|
813 | | ------ | ------ | --------- | ---------- | ------------- |
|
814 | | `value` | `string` | - | - | The value part of the tag |
|
815 | | `operator` | `boolean` | `':'` | - | The operator that goes between the name and value of the tag |
|
816 | | `name` | `boolean` | - | - | The name part of the tag, if not provided, only the value will be shown |
|
817 | | `multiple` | `Array<{name?: string, value?: string, operator?: string, prefix?: string}>` | - | - | An array of name-value pairs, with an optional delimiter to be used between the previous and current tag entry |
|
818 | | `onClose` | `() => void` | - | - | Callback method, that if passed, a "close" button will be added to the right-hand side of the tag|
|
819 | | `onClick` | `() => void` | - | - | Callback method, that if passed, the tag will become clickable |
|
820 |
|
821 | ### Terminal
|
822 |
|
823 | An xterm emulator built on top of [xterm.js](https://xtermjs.org/).
|
824 |
|
825 | [View story source](https://github.com/balena-io-modules/rendition/blob/master/src/components/Terminal/story.js)
|
826 |
|
827 | #### API
|
828 |
|
829 | The `Terminal` component exposes a simple api, typically accessed via a `ref`.
|
830 |
|
831 | Here is a simple example that writes a number every second:
|
832 |
|
833 | ```
|
834 | import * as React from 'react'
|
835 | import { Terminal } from 'rendition'
|
836 |
|
837 | export class Logger extends React.Component {
|
838 | constructor (props) {
|
839 | super(props)
|
840 |
|
841 | this.count = 0
|
842 | }
|
843 |
|
844 | componentDidMount () {
|
845 | this.interval = setInterval(() => {
|
846 | this.term.writeln(++this.count)
|
847 | }
|
848 | }, 1000)
|
849 | }
|
850 |
|
851 | render () {
|
852 | return (
|
853 | <Terminal
|
854 | ref={term => (this.term = term)}
|
855 | />
|
856 | )
|
857 | }
|
858 | }
|
859 | ```
|
860 |
|
861 | ##### `resize()`
|
862 |
|
863 | Resize the `Terminal` component to fill its container.
|
864 |
|
865 | ##### `clear()`
|
866 |
|
867 | Clear all output from the terminal.
|
868 |
|
869 | ##### `writeln(text)`
|
870 |
|
871 | Write text to the terminal, followed by a line break.
|
872 |
|
873 | ##### `write(text)`
|
874 |
|
875 | Write text to the terminal.
|
876 |
|
877 | ##### `destroy(text)`
|
878 |
|
879 | Tear down the terminal instance.
|
880 |
|
881 | #### Remounting old instances
|
882 |
|
883 | If you'd like to preserve a terminal session and remount it to the DOM at
|
884 | a later point, you will need to set the `persistent` property to `true` and then access the readonly property `tty` and store it in memory.
|
885 | The `persistent` flag prevents the `Terminal` component form destroying the
|
886 | `tty` instance when it unmounts.
|
887 | When you want to remount the session, instantiate a new `Terminal`
|
888 | component and provide the `tty` value as the `ttyInstance` property. When
|
889 | a `ttyInstance` property is provided, the `Terminal` component will use that
|
890 | instance instead of creating a new one.
|
891 |
|
892 | #### Props
|
893 |
|
894 | | Name | Type | Default | Required | Description |
|
895 | | ------ | ------ | --------- | ---------- | ------------- |
|
896 | | `ttyInstance` | `object` | - | - | An existing `Terminal.tty` instance to use instead of creating a new one |
|
897 | | `persistent` | `boolean` | - | - | If true, don't destroy the `Terminal.tty` instance when the component unmounts |
|
898 | | `nonInteractive` | `boolean` | - | - | If true, the component will go into a "read-only" state, useful for displaying logs |
|
899 | | `color` | `string` | - | - | A CSS color string that sets the background color of the terminal |
|
900 | | `config` | `object` | - | - | Startup options to pass to the tty instance, see the [xterm.js options](https://github.com/xtermjs/xterm.js/blob/master/typings/xterm.d.ts#L24) for more detail |
|
901 | ### TextWithCopy
|
902 |
|
903 | Displays text that can be copied to the clipboard.
|
904 |
|
905 | [View story source](https://github.com/balena-io-modules/rendition/blob/master/src/components/TextWithCopy/story.js)
|
906 |
|
907 | #### Props
|
908 |
|
909 | | Name | Type | Default | Required | Description |
|
910 | | ------ | ------ | --------- | ---------- | ------------- |
|
911 | | `copy` | `string` | - | ✓ | The value that should be copied to the clipboard
|
912 | | `showCopyButton` | <code>'hover' | 'always'</code> | - | - | Optionally show the copy button on hover or always show the button
|
913 |
|
914 | ### Textarea
|
915 |
|
916 | [View story source](https://github.com/balena-io-modules/rendition/blob/master/src/components/Textarea/story.js)
|
917 |
|
918 | #### Props
|
919 |
|
920 | | Name | Type | Default | Required | Description |
|
921 | | ------ | ------ | --------- | ---------- | ------------- |
|
922 | | `monospace` | `boolean` | `false` | - | If true, render text in a monospace font |
|
923 | | `autoRows` | `boolean` | `false` | - | If true, the textarea `rows` property will be changed automatically based on the content of the textarea, this behaviour will only work with a [controlled input](https://reactjs.org/docs/forms.html#controlled-components) (i.e. you have used the `onChange` property |
|
924 | | `minRows` | `number` | - | - | Set the minimum number of rows |
|
925 | | `maxRows` | `number` | - | - | Set the maximum number of rows |
|
926 | | `onChange` | `(e: Event) => void` | - | - | A function that is called when the textarea value changes |
|
927 |
|
928 | #### Inheritance
|
929 |
|
930 | The attributes of a [`<textarea>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/textarea) element are also available.
|
931 |
|
932 |
|
933 | ### Tooltips
|
934 |
|
935 | Tooltips are somewhat special in how they are used.
|
936 | Instead of using them as a typical React component, they can be added to a supported component using the `tooltip` attribute.
|
937 | For example, to add a tooltip to a `Button` component you would do the
|
938 | following:
|
939 |
|
940 | ```
|
941 | <Button
|
942 | tooltip='I am a tooltip'
|
943 | >
|
944 | Click me
|
945 | </Button>
|
946 | ```
|
947 |
|
948 | If the `tooltip` attribute is a string then a tooltip containing the strings
|
949 | content will be displayed above the component.
|
950 |
|
951 | If you need more control over the tooltip, you can set the attribute to an
|
952 | object with the following properties:
|
953 |
|
954 | | Name | Type | Required | Description |
|
955 | | ------------- | --------- | -------- | ---------------------------------------------------- |
|
956 | | text | `string` | ✓ | The text to display in the tooltip |
|
957 | | trigger | <code>'click' | 'hover'</code> | - | Controls whether the tooltip is displayed on hover or click, defaults to `'hover'`
|
958 | | placement | <code>'top' | 'right' | 'bottom' | 'left'</code> | - | Controls the position of the tooltip related to the component, defaults to `'top'` |
|
959 | | containerStyle | `object` | - | Apply custom styles to the tooltip outer container, the object is applied as a [`style` attribute](https://reactjs.org/docs/dom-elements.html#style) |
|
960 | | innerStyle | `object` | - | Apply custom styles to the tooltip inner container, the object is applied as a [`style` attribute](https://reactjs.org/docs/dom-elements.html#style) |
|
961 | | arrowStyle | `object` | - | Apply custom styles to the tooltip arrow, the object is applied as a [`style` attribute](https://reactjs.org/docs/dom-elements.html#style) |
|
962 |
|
963 | The following rendition components support the `tooltip` attribute:
|
964 |
|
965 | - `Alert`
|
966 | - `Badge`
|
967 | - `Box`
|
968 | - `Button`
|
969 | - `CodeWithCopy`
|
970 | - `DropDownButton`
|
971 | - `Fixed`
|
972 | - `Flex`
|
973 | - `Heading`
|
974 | - `Txt`
|
975 | - `Link`
|
976 |
|
977 | [View story source](https://github.com/balena-io-modules/rendition/blob/master/src/components/Tooltip/story.js)
|
978 |
|
979 | ### Txt
|
980 |
|
981 | Displays a text block. A `<span>` tag can be used with `<Txt.span>` and a `<p>`
|
982 | tag can be used with `<Txt.p>`.
|
983 |
|
984 | [View story source](https://github.com/balena-io-modules/rendition/blob/master/src/components/Txt/story.js)
|
985 |
|
986 | #### Props
|
987 |
|
988 | | Name | Type | Default | Required | Description |
|
989 | | ------ | ------ | --------- | ---------- | ------------- |
|
990 | | `monospace` | `boolean` | - | - | If true, render text in a monospace font |
|
991 | | `bold` | `boolean` | - | - | If true, render text in a bold font |
|
992 | | `italic` | `boolean` | - | - | If true, render text in an italic font style |
|
993 | | `caps` | `boolean` | - | - | If true, render text in uppercase |
|
994 | | `align` | `string` | - | - | Align text inside the component, one of 'left', 'right', 'center', 'justify', 'justify-all', 'start', 'end', 'match-parent', 'inherit', 'initial', 'unset' |
|
995 | | `whitespace` | `string` | - | - | Equivalent to the CSS `white-space` property, one of 'normal', 'nowrap', 'pre', 'pre-line', 'pre-wrap', 'initial', 'inherit' |
|
996 |
|
997 |
|
998 | ### Markdown
|
999 |
|
1000 | A simple component for rendering [GitHub flavored markdown](https://github.github.com/gfm/). This component
|
1001 | sanitizes input.
|
1002 | This component is not loaded by default as it relies on a markdown parsing package
|
1003 | that you may not want to include in your application.
|
1004 | You can load this component using:
|
1005 |
|
1006 | ```
|
1007 | import { Markdown } from 'rendition/dist/extra/Markdown';
|
1008 | ```
|
1009 |
|
1010 | If you need to customize the conversion of markdown to HTML you can supply the `sanitizerOptions` prop. In this case, use the defaults as a starting point for your options:
|
1011 |
|
1012 | ```
|
1013 | import { Markdown, defaultSanitizerOptions } from 'rendition/dist/extra/Markdown';
|
1014 | ```
|
1015 |
|
1016 |
|
1017 | [View story source](https://github.com/balena-io-modules/rendition/blob/master/src/extra/Markdown/story.js)
|
1018 |
|
1019 | #### Props
|
1020 |
|
1021 | | Name | Type | Default | Required | Description |
|
1022 | | ------ | ------ | --------- | ---------- | ------------- |
|
1023 | | `children` | `string` | - | ✓ | The markdown source that should be rendered |
|
1024 | | `sanitizerOptions` | [`sanitizeHtml.IOptions`](https://github.com/apostrophecms/sanitize-html#how-to-use) | (See `extra/utils/defaultSanitizerOptions`) | - | Specifies the options used when sanitizing the generated HTML. |
|
1025 |
|
1026 | Any other properties supplied are spread to the root element ([`Txt`](#txt)).
|
1027 |
|
1028 | #### Inheritance
|
1029 |
|
1030 | The properties of the [`Txt`](#txt) component are also available.
|
1031 |
|
1032 | ### MarkdownEditor
|
1033 |
|
1034 | A markdown editor based on [simple MDE editor](https://github.com/RIP21/react-simplemde-editor)
|
1035 |
|
1036 | ```
|
1037 | import { MarkdownEditor } from 'rendition/dist/extra/MarkdownEditor';
|
1038 | ```
|
1039 |
|
1040 | [View story source](https://github.com/balena-io-modules/rendition/blob/master/src/extra/MarkdownEditor/story.js)
|
1041 |
|
1042 | #### Props
|
1043 |
|
1044 | | Name | Type | Default | Required | Description |
|
1045 | | ------ | ------ | --------- | ---------- | ------------- |
|
1046 | | `value` | `string` | - | ✓ | The markdown-flavored text |
|
1047 | | `onChange` | `(text: string) => void` | - | ✓ | Callback called on every content change |
|
1048 |
|
1049 | ### Mermaid
|
1050 |
|
1051 | Generate charts from text using [mermaidjs](https://mermaidjs.github.io/).
|
1052 | This component is not loaded by default as it relies on the mermaidjs library
|
1053 | that you may not want to include in your application.
|
1054 | You can load this component using:
|
1055 |
|
1056 | ```
|
1057 | import { Mermaid } from 'rendition/dist/extra/Mermaid';
|
1058 | ```
|
1059 |
|
1060 | [View story source](https://github.com/balena-io-modules/rendition/blob/master/src/extra/Mermaid/story.js)
|
1061 |
|
1062 | #### Props
|
1063 |
|
1064 | | Name | Type | Default | Required | Description |
|
1065 | | ------ | ------ | --------- | ---------- | ------------- |
|
1066 | | `value` | `string` | - | ✓ | The mermaid source that should be rendered |
|
1067 |
|
1068 |
|
1069 | ### Form
|
1070 |
|
1071 | A component that can be used for generating a form from a [json schema](http://json-schema.org/) object.
|
1072 | The standard json schema types are supported, as well as the `date-time` format.
|
1073 |
|
1074 | Under the hood, this component uses [`react-jsonschema-form`](https://github.com/mozilla-services/react-jsonschema-form) and support
|
1075 | all [`uiSchema`](https://github.com/mozilla-services/react-jsonschema-form#the-uischema-object) options from that project.
|
1076 |
|
1077 | Additional formats are supported, but require supporting widgets to be loaded.
|
1078 | For example if you would like to support the [mermaid](https://mermaidjs.github.io/) format, you'll need to
|
1079 | import the widget using `import 'renditon/dist/extra/Form/mermaid'`.
|
1080 |
|
1081 | This import only needs to happen once, so it is recommended that its done at the
|
1082 | root level of your application.
|
1083 |
|
1084 | This component is experimental and still under development, if you would like to
|
1085 | use it, it can be imported using `import { Form } from 'rendition/dist/unstable'`.
|
1086 |
|
1087 | #### Custom uiSchema properties
|
1088 |
|
1089 | Some templates and widgets support additional uiSchema options, defined using `ui:options` object in the `uiSchema` definition. Those are:
|
1090 |
|
1091 | ##### PasswordWidget
|
1092 |
|
1093 | | Name | Type | Default | Required | Description |
|
1094 | | ------ | ------ | --------- | ---------- | ------------- |
|
1095 | | `showPasswordStrengthMeter` | `boolean` | false | - | A boolean denoting whether a password strenth meter will be shown. `zxcvbn` should be loaded beforehand and set to the window object as `window.zxcvbn` |
|
1096 |
|
1097 | ##### ObjectField
|
1098 |
|
1099 | | Name | Type | Default | Required | Description |
|
1100 | | ------ | ------ | --------- | ---------- | ------------- |
|
1101 | | `responsive` | `boolean` | false | - | A boolean denoting whether the object fields should be wrapped in a row-directed flex container and wrap once their size is larger than the minimum|
|
1102 | | `flex` | `Array<number | string>` | - | - | Works together with `responsive`. It passes the `flex` value to the same-indexed field in the object. This allows you to have more control over the layout of the fields |
|
1103 |
|
1104 |
|
1105 | #### Captcha
|
1106 |
|
1107 | If you wish to use a captcha (google recaptcha v2) in your form, you need to load the `captcha` widget using `import { CaptchaWidget } from 'rendition/dist/extra/Form/captcha'` and register it using `registerWidget` (see [story source](https://github.com/balena-io-modules/rendition/blob/master/src/unstable/components/Form/story.js)).
|
1108 |
|
1109 | In order for the captcha to work, you also need to set a valid recaptcha API key to the `window.RECAPTCHA_V2_API_KEY` variable.
|
1110 | A gotcha with the captcha widget is, upon submitting, you need to reset the captcha form value where you manage its state. Google only allows a captcha value (generated by clicking the captcha widget) to be verified only once against their API, after which it will be invalid so it needs to be reset.
|
1111 |
|
1112 | #### API
|
1113 |
|
1114 | ##### `registerWidget(format, widget)`
|
1115 |
|
1116 | Register a widget that will be used to render fields of the specified format.
|
1117 |
|
1118 | #### Props
|
1119 |
|
1120 | | Name | Type | Default | Required | Description |
|
1121 | | ------ | ------ | --------- | ---------- | ------------- |
|
1122 | | `schema` | `object` | - | ✓ | A json schema describing the shape of the data you would like to gather |
|
1123 | | `submitButtonText` | <code>string | JSX.Element</code> | - | - | A string or JSX element to replace the text in the form submit button |
|
1124 | | `hideSubmitButton` | `boolean` | - | - | If true, do not display the form submit button |
|
1125 | | `submitButtonProps` | `object` | - | - | Properties that are passed to the submit button, these are the same props used for the [`Button`](#button) component |
|
1126 | | `value` | `*` | - | - | The data that should be displayed in the form |
|
1127 | | `onFormChange` | `(result: object) => void` | - | - | A function that is called when form data changes |
|
1128 | | `onFormSubmit` | `(result: object) => void` | - | - | A function that is called when the form is submitted |
|
1129 | | `uiSchema` | `object` | - | - | A configuration object used to change the styling and layout of the form. See the [`react-jsonschema-form`](https://github.com/mozilla-services/react-jsonschema-form) docs for more details |
|
1130 |
|
1131 |
|
1132 | ### Provider
|
1133 |
|
1134 | Wrap your application in the `<Provider>` component so that child components can correctly inherit the default theme. You can optionally provide your own theme.
|
1135 |
|
1136 | ### Accessing the theme object
|
1137 |
|
1138 | You can access the theme object in `<Provider>`'s descendant components using the `useTheme` hook:
|
1139 |
|
1140 | ```jsx
|
1141 | import React from 'react'
|
1142 | import { useTheme } from 'rendition';
|
1143 |
|
1144 | const MyComponent = () => {
|
1145 | const theme = useTheme()
|
1146 |
|
1147 | // ...
|
1148 | }
|
1149 | ```
|
1150 |
|
1151 | ### Styled system
|
1152 |
|
1153 | All components support [styled-system][styled-system] attributes, allowing you to use a shorthand properties for styling components. The properties can have the properties in the form of `string | number | Array<string | number>`. If an array is provided, then a property is chosen based on the width of the screen. The screen width corresponds to a breakpoint set in the `theme` property of the `Provider` component, by default this is set to `[32, 48, 64, 80]` where each number is the screen width in ems.
|
1154 |
|
1155 | | Name | Type | Description |
|
1156 | | --------------|-------------------|--------------------------------------------- |
|
1157 | | width | `ResponsiveStyle` | sets the width
|
1158 | | minWidth | `ResponsiveStyle` | sets the min-width
|
1159 | | maxWidth | `ResponsiveStyle` | sets the max-width
|
1160 | | height | `ResponsiveStyle` | sets the height
|
1161 | | minHeight | `ResponsiveStyle` | sets the min-height
|
1162 | | maxHeight | `ResponsiveStyle` | sets the max-height
|
1163 | | fontSize | `ResponsiveStyle` | sets the font size
|
1164 | | display | `ResponsiveStyle` | sets the `display` css property
|
1165 | | color | `ResponsiveStyle` | sets the `color` css property
|
1166 | | bg | `ResponsiveStyle` | sets the `background` css property
|
1167 | | m | `ResponsiveStyle` | sets the `margin` css property
|
1168 | | mt | `ResponsiveStyle` | sets the `margin-top` css property
|
1169 | | mr | `ResponsiveStyle` | sets the `margin-right` css property
|
1170 | | mb | `ResponsiveStyle` | sets the `margin-bottom` css property
|
1171 | | ml | `ResponsiveStyle` | sets the `margin-bottom` css property
|
1172 | | mx | `ResponsiveStyle` | sets both the `margin-right` and `margin-left` css properties
|
1173 | | my | `ResponsiveStyle` | sets both the `margin-top` and `margin-bottom` css properties
|
1174 | | p | `ResponsiveStyle` | sets the `padding` css property
|
1175 | | pt | `ResponsiveStyle` | sets the `padding-top` css property
|
1176 | | pr | `ResponsiveStyle` | sets the `padding-right` css property
|
1177 | | pb | `ResponsiveStyle` | sets the `padding-bottom` css property
|
1178 | | pl | `ResponsiveStyle` | sets the `padding-left` css property
|
1179 | | px | `ResponsiveStyle` | sets both the `padding-right` and `padding-left` css properties
|
1180 | | py | `ResponsiveStyle` | sets both the `padding-top` and `padding-bottom` css properties
|
1181 |
|
1182 | **`ResponsiveStyle` corresponds to a type of `string | number | Array<string | number>`*
|
1183 |
|
1184 | ## Extra components
|
1185 |
|
1186 | Some components in the [storybook](https://balena-io-modules.github.io/rendition)
|
1187 | are grouped separately under the `Extra` label. These components are not loaded by default
|
1188 | as they rely on other large packages that you may not want to include in your
|
1189 | application.
|
1190 | If you would like to use them they can be loaded using by prefixing the
|
1191 | component name with `rendition/dist/extra/`. For example to load the `Markdown`
|
1192 | components you can use:
|
1193 |
|
1194 | ```
|
1195 | import { Markdown } from 'rendition/dist/extra/Markdown';
|
1196 | ```
|
1197 |
|
1198 | ## Unstable/Beta components
|
1199 |
|
1200 | Some components in the [storybook](https://balena-io-modules.github.io/rendition)
|
1201 | are grouped seperately under the `Beta` label. These components are experimental and still
|
1202 | under development, as such their API may change without notice. They should not
|
1203 | be used in a production application.
|
1204 | If you would like to try them out they can be loaded using
|
1205 | `import * from 'rendition/dist/unstable'`.
|
1206 |
|
1207 | ## Upgrading
|
1208 |
|
1209 | [Upgrading from 3.x to 4.x](docs/migrating_3x-4x.md)
|
1210 |
|
1211 | [Upgrading from 4.x to 5.x](docs/migrating_4x-5x.md)
|
1212 |
|
1213 | [Upgrading from 6.x to 7.x](docs/migrating_6x-7x.md)
|
1214 |
|
1215 | ## Contributing
|
1216 |
|
1217 | Please read our [contribution guidelines](docs/CONTRIBUTING.md)
|
1218 |
|
1219 | [react]:https://reactjs.org/
|
1220 | [recompose]:https://github.com/acdlite/recompose
|
1221 | [styled-components]:https://www.styled-components.com/
|
1222 | [styled-system]:http://jxnblk.com/styled-system/
|
1223 | [husky]:https://github.com/typicode/husky
|