@pega/lists-react

Welcome to @pega/lists-react

To import

import { RepeatingStructures } from '@pega/lists-react';

To consume

<RepeatingStructures
  meta={meta}
  ref={compRef}
  apiContext={{
    ...apiContext,
    stateUpdateCallback
  }}
  renderFactory={renderFactory}
  formatters={repeatFormatters}
  additionalInfo={additionalInfo}
  ...
/>

Table configuration (meta - prop)

Property	Value type	Mandatory	Default value	Notes
itemKey	String	Yes		Name of a field to use as the key of the rendered item(s) in the view. This field need not necessarily be one of the fields configured for display as part of the field definitions array. This field is directly looked up in the item data.
patchQueryFields	String array	No		Array of fields(extra) to be included in a query
sortOrder	String array	No	['asc', 'desc', null]	Array denoting sort operation order. Default is a tri-state sort
displayDensity	Array of options	No	[{ name: 'Short', id: '1' }, { name: 'Medium', id: '2' },{ name: 'Tall', id: '3' },{ name: 'Full content', id: '4' }]	A map of names(for display) and id(for persistence). The id values have specific behavior(s) associated with them
height	Object	No	height: { minHeight: 600 }	Height of the view. Full set of options include height: { minHeight: 600, /* Minimum height in pixels to the view */, height: 700, /* Explicit height in pixels - fitHeightToElement option is ignored */ fitHeightToElement: el, /* Fit view to a specific HTML element (or string query selector) in the DOM heightwise */ deltaAdjustment: 10 /* A height adjustment value in pixels */ autoSize: true /* Responsively Height will be adjusted on window resize only if you have given fitHeightToElement */, maxHeight: 800, /* Maximum height value in pixels to the view or a css variable (--view-height) */}
toggleFieldVisibility	Boolean	No	true	Allow show/hide of fields
grouping	Boolean	No	true	Allow grouping on fields
template	String	Yes	Table	Determines the view of a Repeating Structure, values:['Table','Gallery','Timeline']
basicMode	Boolean	No	false	Display views ['Table','Gallery','Timeline'] with full or condensed toolbar. Default shows full toolbar.
editing	Boolean	No	false	Allow editing on fields
deleting	Boolean	No	false	Allow deleting of rows
personalization	Boolean	No	true	Allow personalization views
enableAppDefault	Boolean	No	false	Enable app default personalization options
nonPersonalizationViewName	String	No	Initial view	Name to be shown for non personalized view
reorderFields	Boolean	No	true	Allow field reordering through a drag and drop action
reorderItems (experimental)	Boolean	No	false	Allow row reordering through a drag and drop action
dragHandle (experimental)	Boolean	No	false	Allow to add a column for drag handle
globalSearch	Boolean	No	true	Brings in a search widget to allow searching across all text type fields
toolbar	Boolean	No	true	Display toolbar on the view
showCount	Boolean	No	true	Display count in toolbar
defaultRowHeight	String	No	undefined	Row density id value from displayDensity options
allowBulkActions	boolean	No	false	Renders the 'Bulk actions' button in the table toolbar, which gets enabled on row selection
dateFunctions	Object	No	undefined	Enables date-functions like MONTHS/WEEKS/... during Grouping and Filtering. (Object structure)
relativeDates	Boolean	No	false	Enables Relative Dates, such as "Last 7 days" or "Current Year", in Filtering for DateTime or Date_Only values.
footer	Boolean	No	true	Display footer on the view
dynamicFieldTemplates	Object	No	dynamicFieldTemplates: [{ name: 'Comma separated', value: 'comma',selected: true }, { name: 'Space separated', value: 'space' }, { name: 'Multi line', value: 'multiline' }, { name: 'Forward slash', value: 'forwardslash' }]	Templates for dynamic fields. See section on Dynamic fields
title	String	No	'<label not set>'	Repeating Structure Title
icon	String	No	'picture'	Repeating Structure Icon
headerBar	Boolean	No	false	Display Header Bar
showHeaderIcons	Boolean	No	true	Display Respective Header Icons at field labels based on type
rowActions	Array<object>	No	[]	list of available static actions for an editable table with following properties[{ text: 'Open in a new tab', id: 'row-new-tab', onClick: () => {} }]
selectionMode	String	No	[]	Decides type of row selection mode (radio for single/ checkbox for multi) possible values single / multi / multi-on-hover
toolbarActions	Array<Object>	No	[]	List of available static actions at table level (shown in toolbar/ header bar) with following properties [{ text: 'Add', tooltip: 'Add story', id: 'Add', onClick: () => {}}]
selectionCountThreshold	Number	No		Displays select-all checkbox if selectionMode is multi-on-hover and the records count is not greater than threshold
disableSelectionOnLoad	Boolean	No	false	To Disable/Enable selection of rows
requiredOnLoad	Boolean	No	false	To show asterisk(*) symbol on table header in case of Data Reference/Embedded views. (Note: This works perfectly if the personalization is off.)
timezone	String	No		Timezone which is passed to formatter
locale	String	No	document.documentElement.lang	Locale which is passed to formatter function
refreshAction	Object	No		Action to support manual Refresh from consumer of Repeating structure. Whenever Repeating structure is notified with Refresh action It will show a banner by consuming this action info. Structure : {id: 'uniqueId for banner', message: To show specific message on banner related to refresh notification, action : { text: Action button text, onClick: Function to be executed on click of action that will perform refresh of data based on consumer apiContext logic}} Example: {id: 'refreshBanner', message: 'New records have been added',action: { text: 'Click to refresh.', onClick }}

| displayFeatures | Object | No | displayFeatures:{filter:true, grouping:true, sort:true} | Allow display of features-Group, Sort, Filter |

Field configuration

fieldDefs

A mandatory array of objects with the following keys

Property	Value type	Mandatory	Default value	Notes
type	String	Yes		number or text or date or datetime
name	String	Yes		Actual field name in data
id	String	Yes		Persistent ID of the field, typically the same as the name
label	String	Yes
category	Array<Object>	No		Category of the field which should of the format [{label:'categoryName'}] where index denotes the level of category. ClassName for regular fields and association name for associated fields. Example: category:[{label:'Bugs class'}]
showCategoryInHeaderLabel	Boolean	No	false	Show category in header label. The header will be displayed in format {categoryName}.{label} where categoryName will be all the category's labels combined with .(dot) notation
tooltip	String	No	Current Field's formatted value	Defines Field whose value needs to be shown as HelperText e.g tooltip: 'pzDescription' field value for pyID field
showTooltip	Boolean	No	true	Enable/Disable tooltip on column
width	Number	No	150	Pixel width of the field
minWidth	Number	No	90	Minimum width in pixels, field width cannot be resized below this threshold
filter	Boolean	No	true	Allow filtering on this field
filterPickList	Boolean	No	false	Filter popup presents a pick list to choose values from
sort	Boolean	No	true	Allow sorting
sortDirection	String	No		asc or desc. Allows sorting on load. If this property is present, then sortPriority is mandatory
sortPriority	Number	No		Sets the priority on filed for multi sorting(1 takes highest precedence). Allows sorting on load. If this property is present, then sortDirection is mandatory
grouping	Boolean	No	true	Enable grouping
resize	Boolean	No	true	Enable resizing
reorderFields	Boolean	No	true	Allows reordering of column.
freeze	Boolean	No	true	Enable freezing
fillAvailableSpace	Boolean	No	false	field will resize to available excess width. First field definition will be honoured if configured on multiple columns.
required	Boolean	No	false	An asterisk will be added in the table header cell right after the label
toggle	Boolean	No	true	Enable field show/hide
show	Boolean	No	true	Field shows in the view by default. Can be set to false to toggle it in later
showMenu	Boolean	No	true	Show/hide field level Header menu
aggregation	Boolean	No	true	Allow aggregation on column
combineColumn	Boolean	No	true	Allow combining columns
customizeColumn	Boolean	No	true	Allow customizing column label and formatting
noContextMenu	Boolean	No	false	Disable context menu at cells
contextMenuOptions	Array<Object>	No	[]	This property extends options provided on right click in a cell context. Object structure: { id: <string(required)>, icon: <optional>, label: <required>, show: <bool(optional)>, disabled: <bool(optional)> onClick: <Func(target, field, rowContext)(optional)> }
cellRenderer	String	No		Name of a custom component that is made available through the render factory. Check section on cellRenderer
hierarchicalInfo	Object	No		Enable 'Hierarchical' display mode on column if hierarchicalInfo exists. Object structure: {parentId: string, materializedPathId: string, targetId: string, sortById:<string(optional)>}
cellAlign	String	No		Align cell to left/right/center. Values accepted: 'left', 'right', 'center'
hideGroupColumnNameLabel	boolean	No	false	Column name label in group header will be hidden when set to 'true'
filterParams	Object	No	TODO	Filter options for various field

API Context

API	Arguments	Mandatory	Notes
stateUpdateCallback	state: updated state from the component	No	This api gets called with updated state whenever it gets modified
setSelectedRows	selectedRows: selected rows data on the table	Yes	This api sets the selected rows data on the state
getSelectedRows			This api gets the selected rows data from the state

Formatters

Value type	Mandatory	Notes
Object	No	Object of formatter functions mapping where each function accepts 2 parameters, (inputValue, Options). Options is an object having properties: {locale, timezone, rowData, fieldDef, translate}

Render Factory

Prop key	Mandatory	Description	Return type
renderFactory	No	This should be a factory function which receives two arguments where second argument is optional. First argument value is the cell renderer name (if added in fieldDefs of that column). Second argument value is metadata which contains info configured for that column. It should return a component definition (or an object that contains component definition --> see Return type). This component definition will be used by RepeatingStructures to render a cell with the component provided by renderFactory. If component definition is not provided from render factory or renderFactory is not provided to Repeating structures then cell will be rendered directly with value derived for the cell or the formatted value(if formatter is provided for that column)	Repeating structures currently support 2 return types from renderFactory function a component definition function. (OR) an object that contains 2 keys {props: [props that you want to be passed to component along with cellProps], component: [a component definition function]}

Presets

Value type	Mandatory	Notes
Array<Array<Object>>	No	This property value comes from authorization

Other Props

Property	Value type	Mandatory	Default value	Notes
toolBarOptions	Array<Array<Object>>	No	[]	This property extends options provided in toolbar. Object structure: { id: <string(required)>, icon: <optional>, label: <required>, show: <bool(optional)> , onClick: <Func(optional)> }
onViewReady	Function	No	null	This function acts as a callback that is invoked when the view is ready
onRowClickAction	Function	No	null	This function is invoked when an item/entry is clicked. The corresponding item data is passed into the function on invocation
showExportToExcelOption	Boolean	No	false	This option is shown in the toolbar menu when the ListView is sourced from queryable DataPage
additionalInfo	Object	No	`undefined	AdditionalInfo displayed on the toolbar is passed as is to List Toolbar component

State

Feature	Property	Value type	Example
Column reorder	colOrder	Array<string> - Array of column id	colOrder: ["A", "custom1590925631168", "2", "3", "D", "10", "11"]
Column resize	columnWidths	Object - key: columnId, value: column width	columnWidths: {10: 132.5, 11: 132.5, 12: 132.5, 2: 235.5, 3: 353}
Column freeze	freezeColumns	Array<string> - Array of column id	freezeColumns: ["3", "10"]
Column show/hide	hiddenColumns	Array<string> - Array of column id	hiddenColumns: ["8", "9"]
Density	selectedHeightOption	String - id value from displayDensity table configuration property	selectedHeightOption: "4"
Sort	sortingOrder	Array<object> - [{columnId: string, order: [asc|desc], sequence: number}]	javascript sortingOrder: [ {columnId: "2", order: "asc", sequence: 1}, {columnId: "A", order: "desc", sequence: 2} ]
Filter	filterExpression	Object - output of condition builder	Refer - Condition builder documentation
Group	groups	Array<object> - [{columnId: string, level: number, order: [asc|desc]}]	groups: [ {columnId: "F", level: 0, order: "asc"}, {columnId: "D", level: 1, order: "asc"} ]
Aggregation	aggregationInfo	Array<object> - [{columnId: string, type: [Sum|Max|Min|Avg]}]	aggregationInfo: [ {columnId: "D", type: "Max"}, {columnId: "11", type: "Avg"} ]
Merge column	customFields	Array<object> - [{id: string - should be unique, expression: array, primaryColumnId: string, label: string }]	customFields: [ { id: 'custom4', label: 'MyCustomColumn', primaryColumnId: '2', expression: ['2', '1', ['template1'], '3', ['template2'] ] } ]

Reference to the Component ("compRef" in below example)

APIs exposed on the component ref are accessible via compRef.current.<API_NAME> (like compRef.current.refreshView)

API_NAME	Default values	Notes	Example
refreshView		refreshView api is used to re-render the already loaded table to re-fetch the data and re-fetch selections using apiContext.getSelectedRows api (if any of the selection mode is enabled). You can provide two arguments to refreshView; 1. stateToReset (<object>) - (ex: you want to remove grouping before triggering re-render). Currently, supported state flushing of only ['filterExpression', 'search', 'selectedRows'], 2. featuresToAvoid (Array<string>) - to avoid re-running of the following features - ['rowAnimation', 'columnAnimation']	compRef.current.refreshView({ filterExpression: true, search: true }, ['rowAnimation']);
moveListRecords		apiContext.moveListRecords api is used to consume a dx api which invokes a OOTB data transform. api flow: 1. invokes dx api with necessary payload, 2. dx api is configured with activity which invokes a data transform based on the payload & path param received 3. returns success response object with {refresh: true} 4. based on this flag it triggers refresh strategy which fetch new set of data	compRef.current.apiContext.moveListRecords({sourceID, destinationID})
dispatchAction		dispatchAction(action,payload) is used to trigger specific actions to the table with a specific payload. Below actions are available: 'toggleDisableSelection' - it supports enable/disable of selection of rows. Payload should be a boolean in order to enable disable the selection. 'updateDebugInfo' - Show the stats of API call for debugging purposes. The payload must be an object. 'toggleRequired' - It supports show/hide of asterisk(*) sign in case of embedded/data reference tables, To show/hide of warning sign in case required condition is not met. The payload must be an object. 'notifyDataRefresh' - To show notification banner for refresh of data by consuming refreshAction from meta 'clearDataRefreshNotification' - To reset the refresh that was notified by consumer by sending 'notifyDataRefresh' action 'userConfirmationAction' - Display a generic confirmation modal with cancel and submit action. This will return a promise. 'setInExternalState' - To set something in table external state. By default the externalState will take part in personalization of table. 'updateSelectedRows' - To force re-fetch the selections using apiContext.getSelectedRows.	Disable the selection - compRef.current.dispatchAction('toggleDisableSelection',true) Pass API stats - compRef.current.dispatchAction('updateDebugInfo', {className: "ABC", dataPage: "D_Page", dataSource: "RDBMS", timeTaken: "1.2 s", insightId: "someId"}) Show/Hide Required UX(asterisk(*) & warning sign) - cosmosTableRef.current?.dispatchAction('toggleRequired',{required, validatemessage Notify the data refresh - compRef.current.dispatchAction('notifyDataRefresh') Clear the notification of data refresh - compRef.current.dispatchAction('clearDataRefreshNotification') Show confirmation modal - compRef.current.dispatchAction(USER_CONFIRMATION_ACTION, {labels: {header, description, submitButtonLabel, cancelButtonLabel}}): Promise<any> Set in external state - compRef.current.dispatchAction('setInExternalState', {PromotedFilters: {[filterExpression payload]}}) updateSelectedRows - compRef.current.dispatchAction('updateSelectedRows')
getActiveViewInfo		getActiveViewInfo() returns {id, name, isDirty} of current active view	compRef.current.getActiveViewInfo()
setHiddenColumns		setHiddenColumns(columns,{ dragHandle: boolean }) sets the hiddenColumns property in component state and re-renders with features appropriately, the second parameter is an optional payload that can be used for hidding and showing the columns provided by repeating structures	compRef.current.setHiddenColumns('pyLabel', 'pyDescription')
setColumnOrder		setColumnOrder(columns) sets the colOrder property in component state and re-renders with features appropriately	compRef.current.setColumnOrder('pyID', 'pxCommitDateTime', ',pxUpdateDateTime', 'pyStatusWork')
setFilter		setFilter(filter) sets the filterExpression property in component state and re-renders with features appropriately. The new filter must consist of a top-level AND condition in ConditionBuilder format.	compRef.current.setFilter({ "condition": { "comparator": "IS_TRUE", "lhs": { "field": "IsActive" } } })
setGrouping		setGrouping(groups) sets the groups property in component state and re-renders with features appropriately	compRef.current.setGrouping([{ "columnId": "Status", "order": "asc", "level": 0 }])
setSorting		setSorting(groups) sets the sortingOrder property in component state and re-renders with features appropriately	compRef.current.setSorting([{ "columnId": "Priority", "order": "asc", "sequence": 1 }])

Cell renderers

Dynamic field templates and renderers

**

Accessibility

Keyboard

Navigation in the toolbar component

• The Toolbar component can be traversed with the tab key.
• Popover elements such as: Filter, Sort, Group by, and Toolbar more elements can be navigated by tab key.
• On reaching the last element, pressing the tab will focus on the first element performing circular navigation.
• Similarly, if focus is on first element, then pressing SHIFT+TAB will focus the last focusable element.
• Pressing escape will close the popover and puts the focus back to the action button i.e. filter, sort, group by, and more toolbar button.

Navigation in the table

• The first focus will be on the table's first header cell if earlier no navigation has been done.
• To navigate between the cells, use the arrow keys.
• Pressing enter on the cell can turn the cell in edit mode if it is editable.
  • Pressing enter again will submit the data
  • Pressing escape will discard the changes and turn the cell back to read mode.
• To focus out from the table cells, press the tab key and focus will be shifted to the next focusable element on the page after table.
• Next time when navigated again to the table, the last visited cell will be focused.

Translations

• RepeatingStructures uses the cosmos, hence translations are fetched from useConfiguration hook exposed by cosmos-core.
• Note: Configuration component which is a provider component of cosmos accepts the translations prop, in which make sure to send the translations required for RepeatingStructure component as part of {lists: {'Sort': 'Translation of Sort'}}

Note to this repo code owners / Dev's:

• Every time a user facing / listening string is added in a component:
  • Make sure to add the new translation in the pyGenericFields localisation rule under the cosmosFields.fields.lists category.
  • Then raise a PR to Cosmos translations pack defintions file to update the same key string.