This repository has been archived by the owner on May 22, 2024. It is now read-only.
Releases: cerner/terra-clinical
Releases · cerner/terra-clinical
[email protected]
Migrating from terra-clinical-item-collection v1 to v2
The following sections describe how to migrate from using the ItemCollection API provided in terra-clinical-item-collection v1 to the new API provided in the v2 release. The v2 release introduces new API and now allows for static and selectable Item Collection rendering. These changes allow for easier implementation, as well as more flexibility in use and future enhancements.
Behavior Changes
Added/Changed Behavior
- Allows for either static and selectable implementation
- Supports Children API which introduces the ItemCollection.Item component
- OnSelect returns the event and child key for onClicks and onKeyDowns
- Exports the following components:
ItemCollection.Item,ItemCollection.DisplayandItemCollection.Comment - Table layout is no longer dependent on first collection row #213
If a display is missing, the ItemCollection will allocate space to maintain the provided layout.
Prop Changes
Props Added
children- the Item Collection Items that will flex between either a list item or a table row.hasStartAccessory- indicates if space should be allocated for a start accessory.numberOfDisplays- the number of displays the Item Collection should allocate space for (maximum of 8).hasComment- indicates if space should be allocated for a comment.hasEndAccessory- indicates if space should be allocated for an end accessory.onSelect- the callback function that is assigned as to a child's onClick and onKeyDown callback if the child isSelectable. The first parameter returned is the event and the second parameter is the child key.
Props Changed
rows- replaced withchildrenprop.onChange- replaced withonSelectprop.listStyles- flattened and replaced withisListDividedprop. Additionally, the Item Collection no longer provides chevron styles as chevrons are intended for single-selectable lists only to indicate clicking the item will reveal more information. This behavior is not currently present in selectable tables.tableStyles- flattened and replaced withisTablePaddedandisTableStriped.
ItemCollection.Item
This component handles the rendering of a list item or table row for the ItemCollection. By default, this would render an ListItem with an ItemView as the content. Else, it will render a TableRow with the element layout order of startAccessory, displays, comment, then endAccessory. This component provides a clean way to represent an item within the item collection, and would not handle missing element logic if used outside of the Item Collection as intended.
Usage
<ItemCollection.Item
startAccessory={ <Accessory />}
comment={ <ItemCollection.Comment />}
endAccessory={ <Accessory />}
isListItemTruncated
>
<ItemCollection.Display />
<ItemCollection.Display />
<ItemCollection.Display />
</ItemCollection.Item>
Code Migration
Migrating from v1.4 to v2:
import React from 'react';
- import ItemView from 'terra-clinical-item-view';
import ItemCollection from 'terra-clinical-item-collection';
class OnChangeItemCollection extends React.Component {
constructor(props) {
super(props);
- this.state = { selectedIndex: 2 };
+ this.state = { selectedItemKey: 'key-2' };
this.handleSelection = this.handleSelection.bind(this);
}
- handleSelection(event, selectedIndex) {
- this.setState({ selectedIndex });
- }
// Selection logic is not handled by the Item Collection, it only returns the event and child key selected
+ handleSelection(event, selectedItemKey) {
+ if (event.nativeEvent.type === 'click') {
+ this.setState({ selectedItemKey });
+ }
+ }
render() {
return (
<ItemCollection
breakpoint="medium"
+ hasStartAccessory
+ numberOfDisplays={3}
+ hasComment
+ hasEndAccessory
- onChange={this.handleSelection}
+ onSelect={this.handleSelection}
- rows={[
- {
- startAccessory: <p>S</p>,
- displays: [
- <ItemView.Display text="Display 1" />,
- <ItemView.Display text="Display 2" />,
- <ItemView.Display text="Display 3" />
- ],
- comment: <ItemView.Comment text="test comment" />,
- endAccessory: <p>E</p>,
- isSelected: {this.state.selectedIndex === '1'},
- },
- {
- startAccessory: <p>S</p>,
- displays: [
- <ItemView.Display text="Display 1" />,
- <ItemView.Display text="Display 2" />,
- <ItemView.Display text="Display 3" />
- ],
- comment: <ItemView.Comment text="test comment" />,
- endAccessory: <p>E</p>,
- isSelected: {this.state.selectedIndex === '2'},
- },
- ]}
- />
+ >
+ <ItemCollection.Item
+ key="key-1"
+ isSelectable
+ isSelected={this.state.selectedItemKey === 'key-1'}
+ startAccessory={<p>S</p>}
+ comment={<ItemCollection.Comment text="test comment" />}
+ endAccessory={<p>S</p>}
+ >
+ <ItemCollection.Display text="Display 1" />
+ <ItemCollection.Display text="Display 2" />
+ <ItemCollection.Display text="Display 3" />
+ </ItemCollection.Item>
+ <ItemCollection.Item
+ key="key-2"
+ isSelectable
+ isSelected={this.state.selectedItemKey === 'key-2'}
+ startAccessory={<p>S</p>}
+ comment={<ItemCollection.Comment text="test comment" />}
+ endAccessory={<p>S</p>}
+ >
+ <ItemCollection.Display text="Display 1" />
+ <ItemCollection.Display text="Display 2" />
+ <ItemCollection.Display text="Display 3" />
+ </ItemCollection.Item>
+ </ItemCollection>
);
}
}
export default OnChangeItemCollection;Prop Tables
terra-clinical-item-collection v1.4.0
| Prop Name | Type | Is Required | Default Value | Description |
|---|---|---|---|---|
| breakpoint | string | optional | small | The breakpoint to switch from a table view to a list view. Breakpoint options are tiny, small, medium, large, or huge. |
| tableStyles | shape | optional | undefined | The styles to spread to the table. Table style options are isPadded and isStriped. |
| listStyles | shape | optional | undefined | The styles to spread to the list. List style options are isDivided and hasChevrons. |
| rows | string | optional | [] | The array of hashes to be displayed as rows. Each hash can contain a startAccessory, endAccessory, comment, array of displays, isSelected, and a itemStyles hash. The item style options are layout, textEmphasis, isTruncated and accessoryAlignment. |
| onChange | func | optional | undefined | A callback event that will be triggered when selection state changes. |
terra-clinical-item-collection v2.0.0
ItemCollection Props
| Prop Name | Type | Is Required | Default Value | Description |
|---|---|---|---|---|
| breakpoint | string | optional | small | The breakpoint to switch from a table view to a list view. Breakpoint options are tiny, small, medium, large, or huge. |
| isTablePadded | bool | optional | false | Whether or not the table cells should be padded. |
| isTableStriped | bool | optional | false | Whether or not the table rows should be zebra striped. |
| isListDivided | bool | optional | false | Whether or not the list items should be divided. |
| children | string | optional | [] | The Item Collection Items that will flex between either a list item or a table row. |
| hasStartAccessory | bool | optional | false | Whether or not the item collection should create a layout to display a start accessory. |
| numberOfDisplays | number | optional | 0 | The number of displays the item collection should create a layout for. |
| hasComment | bool | optional | false | Whether or not the item collection should create a layout to display a comment. |
| hasEndAccessory | bool | optional | false | Whether or not the item collection should create a layout to display an end accessory. |
| onSelect | func | optional | undefined | The callback function that is assigned as to a child's onClick and onKeyDown callback if the child isSelectable. The first parameter returned is the event and the second parameter is the child key. Function is not applied if child is not selectable. |
ItemCollection.Item Props
| Prop Name | Type | Is Required | Default Value | Description |
|---|---|---|---|---|
| children | node | optional | undefined | The display elements to be presented. |
| startAccessory | node | optional | undefined | The start accessory element to be presented. |
| comment | node | optional | undefined | The comment element to be presented. |
| endAccessory | node | optional | undefined | The end accessory element to be presented. |
| listItemLayout | string | optional | 'oneColumn' | When displayed as a list item, the column layout in which to present the displays. |
| listItemTextEmphasis | string | optional | 'default' | When displayed as a list item, the text color emphasis when using the two columns layout. |
| isListItemTruncated | bool | optional | false ... |