@pega/lists-react
TypeScript icon, indicating that this package has built-in type declarations

8.0.0-build.34.1 • Public • Published

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.

Readme

Keywords

none

Package Sidebar

Install

npm i @pega/lists-react

Weekly Downloads

524

Version

8.0.0-build.34.1

License

SEE LICENSE IN LICENSE

Unpacked Size

1.87 MB

Total Files

728

Last publish

Collaborators

  • baipc
  • andrewlewis2
  • duddrc
  • ricmars
  • ssowersby
  • bob-difronzo
  • feenr-pega
  • cpmotion
  • pega-cosmos
  • ghosa4
  • sharv12
  • pgagnon
  • tumms2021389
  • vrspega
  • patilvishal
  • nikhilparmar