import { V1DataGrid } from '@uhg-abyss/web/ui/DataGrid';

Overview

The data grid features are ideal for displaying and editing a matrix of data within the UI. This component shares similar features to a spreadsheet application such as Excel with similar layout, user experience and available functionality. See the following sections below for further details on available features and implementation.

Usage (useDataGridV1)

import { useDataGridV1 } from '@uhg-abyss/web/hooks/useDataGrid';

V1DataGrid requires usage of the useDataGridV1 hook. All available props as displayed within the API integration tab and shown in the examples below must be passed into useDataGridV1. The return should then be supplied to the gridState prop within the V1DataGrid component. There are also methods available in the return from useDataGridV1 such as updateData, getData, updateColumns, updateGrid, etc.

Grid title

A title is required for accessibility reasons. Use the gridTitle prop to pass in a title that describes the grid. The title is hidden by default. If you'd like the title to be displayed pass in the showGridTitle prop.

Grid read-only

Set the readOnly prop to true on useDataGridV1 to place all data cells within the grid into read-only mode. Read-only cells are not editable, but the cell's data can be copied.

If you'd like to manage the read-only configuration at the column level, please see the Column Read-Only section below.

Data

Use the initialData prop to provide the data to V1DataGrid on load. This takes in an array of arrays with the values that correspond to the desired row and column. After load, you can use the following data methods:

Update data

To make any updates to the grid data after load, use the updateData method that's returned from useDataGridV1.

Get data

To retrieve the current state of the data from the grid, call the getData method that's returned from useDataGridV1.

Columns

Use the initialColumns prop to supply the V1DataGrid with the column information for your grid. Columns is an array of objects that take in the following properties covered below.

After initial load, if you need to change the columns content, please set the Update Columns section below.

Note: If no column information is provided, all column properties will be set to their respective default values. The number of columns will be determined by the length of the initialData provided. If no data is available, it will be set by startColumns or default to 5 columns.

Title

Use the title prop to provide a custom name to a column header. If no title is provided for a column, the default headers (A, B, C, etc.) will be displayed in alphabetical order.

Type

All cells of a given column are of the same type and have the same widget. The following columns types are available:

text (default)

date

Note the below configurations only affect the calendar picker and do not provide validation on the input field. Use the validator prop to handle validation of the input field on blur.

Additional Configurations:

• Min/Max Date - Use the minimumDate and maximumDate props to set the min and max dates in the calendar picker.
• Excluded Dates - To exclude dates within the calendar picker, use the excludeDates prop. Set a function that receives date as an argument and returns true if date should be disabled.
• Starting/Ending Year - Use the startingYear and endingYear props to set the min and max years in the calendar picker.

select

Additional Configurations:

• Label/Value Key - Use the valueKey and labelKey props to change the key that is used to read the labels and values from the options list.
• Section Headers - Add description headers to your drop-down option list items.
• Custom Render - Used the customRender prop to customize the render of each option item. Provides the item object as the first parameter and the item state as the second.
• Option List Height - Use the maxListHeight prop to set the maximum height of the drop-down menu. The default value is 185px.

number

Below are examples of the available number configurations. For further configurations please see the following site for additional props that can be passed into the numericConfig property.

Default value

Use the defaultValue prop to set a default value within each empty cell in the column. To generate an empty grid with no data, please see the Start Columns/Rows section.

Column width

Column width is dynamically computed using flex settings. To control minimum and maximum width values for a particular column, use the minWidth and maxWidth props. The default minWidth value is 100 and anything below will not be applied.

Hide

The hide prop can be used when you do not want to display all columns of data in the V1DataGrid.

Sort

Use the sort prop within a column object to designate its sort functionality. If a sort value is applied, either true or false, this will override the global sort configuration. For more information on column sorting please see the Column Sort section.

Filter

Use the filter prop within a column object to designate its filter functionality. If a filter value is applied, either true or false, this will override the global filter configuration. For more information on column filtering please see the Column Filter section.

Update columns

To make any updates to the grid columns after load, use the updateColumns method that's returned from useDataGridV1. If you'd like to update both the columns and interior cell data use updateGrid.

Disabled / read-only

The disabled prop accepts either a boolean or a function. If a boolean value of true is provided, it will disable the entire column. If a function is provided, it receives an object containing rowIndex and rowData and must return a boolean. Disabled columns are not editable and do not allow copying of cell data.

The readOnly prop mirrors disabled with one exception: read-only cells allow copying of cell data. To apply a read-only state to all data cells within a grid, please see the Grid Read-Only section above.

Custom component

Use the component prop within a column object to pass a custom component to render within the cell. See below for the props that will be passed to the component.

Custom component props

When creating a custom component, the following props are available:

Prop	Type	Description
rowData	any	The data for the current cell
setRowData	function	Function to update the cell data
active	boolean	Whether the cell is currently active (selected)
focus	boolean	Whether the cell is in edit mode
stopEditing	function	Function to exit edit mode
setEditing	function	Function to enter edit mode
setActiveCell	function	Function to set the active cell
rowIndex	number	The index of the current row
columnIndex	number	The index of the current column
isDisabled	boolean	Whether the cell is disabled
columnData	object	Additional column data passed to the component
defaultValue	any	Default value for the cell

Other column props

• updateOnChange When true, cell data will be written on input change. Default is false and recommended for better performance.
• validator Use to handle validation of the cell. It takes a function that receives two arguments, the newly entered value and previous value (if available), and must return the desired value. The function is called on blur of cell edit and when pasting values to the cell. If updateOnChange is set to true, it will be called on input change.
• cellClassName Takes either a string with a single class name or a function that receives a single argument as an object with the rowIndex and rowData. Use to add a custom class to a cell that can be targeted using the css prop.
• textAlign Determines text alignment within a columns cells. Available options are 'left' | 'center' | 'right'. Default value is right for all numeric values and left for all others.
• placeholder Adds a placeholder value to the columns cells. The placeholder value will only be displayed when a cell is active/selected and contains no data.
• disabled Takes either a boolean or a function. If a boolean is provided, it will disable the entire column. If a function is provided, it receives an object with the rowIndex and rowData and must return a boolean. Disabled columns will not be editable or allow for copying of cell data.
• readOnly Takes either a boolean or a function. If a boolean is provided, it will set the entire column as read-only. If a function is provided, it receives an object with the rowIndex and rowData and must return a boolean. Read-only columns will not be editable but will allow for copying of cell data.
• move Set whether the column is movable. If a value is applied, either true or false, this will override the global columnMove configuration.
• disableContextMenu Set whether the context menu is disabled for all cells within a column. If a value is applied, either true or false, this will NOT override the global disableContextMenu configuration.
• ariaRoleDescription Use when utilizing a custom component to set the role description for the column. When using a built in column type, the role description is automatically set by the type.

{
  updateOnChange: boolean,
  validator: function,
  cellClassName: function | string,
  textAlign: string,
  placeholder: string,
  disabled: boolean | function
  readOnly: boolean | function
  move: boolean
  disableContextMenu: boolean
  ariaRoleDescription: string
}

Layout

Start columns/rows

If no initialData is set, the startColumns and startRows props are used to generate a grid with empty cells. Both default to a value of 5.

Hide gutter column

If hideGutterColumn is set to true, the left-most numerical gutter column will not be visible. The gutter column is displayed by default.

Grid height/width

Use the maxHeight and maxWidth props to set the maximum height and width of the grid. If no height or width is provided, both will default to a value of 100%. If the content becomes larger than these values, the grid will become scrollable.

Row height

Use the rowHeight prop to either pass in an array of row heights or a single number value that will be applied across all rows. If no row height is supplied, it will default to a value of 40px. The minimum height allowed is 20px.

Header row height

Use the headerRowHeight prop to set the height of the column header row. The default value is 40px.

Operations

Update grid

To make any updates after load to both the grid columns and the interior cell values, use the updateGrid method that's returned from useDataGridV1.

Reorder rows/columns

Use the rowMove and columnMove props to enable the ability to reorder rows and/or columns. A row or column must first be selected in order to drag it to another location on the grid. Once a row/column is selected by clicking on the corresponding row/column header cell, the hand tool will display and the selected row/column can be moved. Currently, only one row/column may be moved at a time.

Column sort

Use the columnSort prop to globally turn on sort functionality for all columns. When applied the sort arrow indicators will display within the column header cells and sort functionality can be accessed within the Context Menu. When sorting is active for a column, the corresponding ascending/descending sorting indicator will be highlighted blue. Note that the sort configuration within an individual column will take precedence over this global setting.

Column filter

Use the columnFilter prop to globally turn on filter functionality for all columns. When applied, the filter indicator will display within the column header cells and filter functionality can be accessed within the Context Menu. When filtering is active for a column, the corresponding indicator will be highlighted blue. Note that there is a limit of 2 filters per column, and the filter configuration within an individual column will take precedence over this global setting.

Update filtering

To programmatically make filter updates, use the updateFilter method that's returned from useDataGridV1. See the configuration details below, along with an example of how you can set an initial filter state on load.

const filters = [
      {
        columnIndex: 1, // The index of the column to apply the filter on
        value: [ // Limited to 2 filters per column
          {
            condition: 'contains', // The condition to filter on
            filterValue: '10' // The filter value
            operator: 'and' // The operator if more than one filter is applied.  Can be either 'and'/'or'; default is 'and'
          },
          ]
      },
      ... // More filters on other columns
    ],

The condition property within value must be one of the following strings:

• is-empty - Empty cell
• not-empty - Non-empty cell
• equals - Equal to
• not-equal - Not equal to
• contains - Contains
• starts-with - Starts with
• ends-with - Ends with
• greater - Greater than (number type only)
• greater-equal - Greater than or equal to (number type only)
• less - Less than (number type only)
• less-equal - Less than or equal to (number type only)
• before - Before (date type only)
• after - After (date type only)
• between - Between (date type only)

Resize rows

Use the rowResize prop to enable the ability to resize rows by dragging the resize handle available on hover of the bottom of each row header cell.

Disable auto fill

Use the disableAutoFill prop to disable the UI fill handle and the ability to drag and copy cell values across multiple column and row cells. Auto-fill is enabled by default.

Context menu

Use the context menu to access contextual actions such as copying data or deleting/inserting columns or rows. To open the context menu, right-click or press Shift + F10 for Mac and Control + Shift + F10 for Windows, while on any cell and the applicable options will be made available. While on a column or row header cell the Enter key will open the context menu and simultaneously select the contents for the selected column or row. Here is a list of the currently available options:

• Sort Ascending
• Sort Descending
• Filter
• Copy
• Cut
• Paste
• Insert row above
• Insert row below
• Delete row(s)
• Insert column before
• Insert column after
• Delete column(s)

To disable the context menu, use the disableContextMenu prop. The menu is enabled by default.

Insert row/column

To programmatically insert new rows or columns, call insertRow or insertColumn method that's returned from useDataGridV1. It takes two arguments: the index of the row or column you'd like to insert around and the insert position of either 'before' or 'after'.

Delete rows/columns

To programmatically delete rows or columns, call the deleteRows or deleteColumns method that's returned from useDataGridV1. It takes two arguments: the starting and then ending row or column for the selection range you'd like to delete. If you'd like to only delete a single row or column, only the starting index is required.

Events

onActiveCellChange

The onActiveCellChange prop take a function that is called each time the active cell is changed and includes the active cell's column index, row index and column id.

{
  col: number, // active cell column index
  row: number, // active cell row index
  colId: string,
}

onSelectionChange

The onSelectionChange prop take a function that is called each time cell selection is changed and includes the min and max cell data.

{
  min: {
    col: number,
    row: number,
    colId: string,
  },
  max: {
    col: number,
    row: number,
    colId: string,
  }
}

onEditEnter / onEditLeave

The onEditEnter and onEditLeave props take a function that is called each time a cell enters or leaves edit mode and includes the current cell's column index, row index and column id.

{
  col: number, // active cell column index
  row: number, // active cell row index
  colId: string,
}

onRowCreate

The onRowCreate prop takes a function that includes the column data as an argument and should return a new row object. It is called each time the user adds a new row. The return object must include the id for the columns you'd like to apply new data. This is typically used for adding custom data whenever a new row is added. If not used, an empty row will be generated and any column default data will be applied to the applicable cells.

onColumnCreate

The onColumnCreate prop takes a function that should return a new column object. It is called each time the user adds a new column. Use this function to return custom column settings. If not utilized, the default text type column will be created.

onDelete

The onDelete prop is a callback function passed into useDataGridV1. When any cells are deleted, the function is called and two arguments are provided. The first argument is an array of objects that contain the row and col indexes of the cells being deleted, along with the corresponding deleted cell value. The second argument is the post-delete grid data.

(
  deletedCells?: { row: number, col: number, value: any }[],
  data?: any[][]
)

V1DataGrid Props

Prop Name	Type	Default	Description
columnFilter	boolean	false	Enables ability to filter grid data by columns
columnMove	boolean	false	Enables UI control for dragging and reordering columns
columnSort	boolean	false	Enables ability to sort grid data by columns
disableAutoFill	boolean	false	Disables UI control for dragging and copying values across cells
disableContextMenu	boolean	false	Disables context menu
gridTitle	string	-	Grid title (required)
headerRowHeight	number	40	Sets height for the column header row
hideGutterColumn	boolean	false	Set to true to hide gutter/row-header column
initialColumns	array	[]	Initial column configuration
initialData	array	[]	Initial data set
maxHeight	number | string	100%	Sets maximum height of grid
maxWidth	number | string	100%	Sets maximum width of grid
onActiveCellChange	function	-	Callback fired each time active cell is changed
onColumnCreate	function	-	Callback fired each time user adds a new column
onDelete	function	(deletedCells?, data?) => void	Callback fired each time user deletes cells
onEditEnter	function	-	Callback fired each time a cell is entered into edit mode
onEditLeave	function	-	Callback fired each time a cell leaves edit mode
onRowCreate	function	-	Callback fired each time user adds a new row
onSelectionChange	function	-	Callback fired each time cell selection is changed
readOnly	boolean	-	Place all content cells within the V1DataGrid into read-only mode
rowHeight	number | array	40	Sets row height for all or individual rows
rowMove	boolean	false	Enables UI control for dragging and reordering rows
rowResize	boolean	false	Enables UI control for resizing row heights
showGridTitle	boolean	false	Show/hide grid title caption
startColumns	number	5	Sets number of empty start columns
startRows	number	5	Sets number of empty start rows

V1DataGrid Classes

Class Name	Description
.abyss-data-grid-active-cell	Data Grid active cell
.abyss-data-grid-auto-fill-indicator	Data Grid auto-fill indicator element
.abyss-data-grid-auto-fill-selector	Data Grid auto-fill selector
.abyss-data-grid-cell-display-text	Data Grid cell display text
.abyss-data-grid-column-gutter-corner-indicator	Data Grid column gutter corner indicator
.abyss-data-grid-column-header-cell-button	Data Grid column header cell button
.abyss-data-grid-column-header-cell-container	Data Grid column header cell container
.abyss-data-grid-column-header-cell-title	Data Grid column header cell title content
.abyss-data-grid-column-header-row-container	Data Grid column header row container
.abyss-data-grid-container	Data Grid inner container
.abyss-data-grid-context-menu-item	Data Grid context menu item
.abyss-data-grid-context-menu-item-icon	Data Grid context menu item icon
.abyss-data-grid-context-menu-item-key-command	Data Grid context menu item key command
.abyss-data-grid-context-menu-portal-container	Data Grid context menu portal container
.abyss-data-grid-drag-layer-container	Data Grid drag layer container
.abyss-data-grid-drag-layer-overlay	Data Grid drag layer overlay
.abyss-data-grid-filter-modal	Data Grid filter modal
.abyss-data-grid-filter-modal-apply-filter-button	Data Grid filter modal apply filter button
.abyss-data-grid-filter-modal-reset-button	Data Grid filter modal reset button
.abyss-data-grid-filter-table	Data Grid filter table
.abyss-data-grid-filter-table-add-filter	Data Grid filter table add filter button
.abyss-data-grid-filter-table-container	Data Grid filter table container
.abyss-data-grid-filter-table-remove-filter	Data Grid filter table remove filter button
.abyss-data-grid-header-sort-arrow	Data Grid header sort arrow element
.abyss-data-grid-header-sort-arrow-container	Data Grid header sort arrow container
.abyss-data-grid-resizer-guide	Data Grid re-sizer guide
.abyss-data-grid-resizer-handle	Data Grid re-sizer handle element
.abyss-data-grid-root	Data Grid root element
.abyss-data-grid-row-cell	Data Grid row cell
.abyss-data-grid-row-container	Data Grid row container
.abyss-data-grid-row-gutter-cell	Data Grid gutter row cell
.abyss-data-grid-selection-column-marker	Data Grid column marker
.abyss-data-grid-selection-column-marker-container	Data Grid column marker container
.abyss-data-grid-selection-highlighter	Data Grid selection highlighter
.abyss-data-grid-selection-row-marker	Data Grid row marker
.abyss-data-grid-selection-row-marker-container	Data Grid row marker container
.abyss-data-grid-title	Data Grid title/caption element

Data Grid Keyboard Interactions

Key	Description
Right Arrow	Moves focus one cell to the right. If focus is on the right-most cell in the row, focus does not move.
Left Arrow	Moves focus one cell to the left. If focus is on the left-most cell in the row, focus does not move.
Down Arrow	Moves focus one cell down. If focus is on the bottom cell in column, focus does not move.
Up Arrow	Moves focus one cell up. If focus is on the top cell in column, focus does not move.
Shift + Right Arrow	Extends selection one cell to the right.
Shift + Left Arrow	Extends selection one cell to the left.
Shift + Down Arrow	Extends selection one cell down..
Shift + Up Arrow	Extends selection one cell up.
Control + Right Arrow	Moves focus to rightmost cell of column.
Control + Left Arrow	Moves focus to leftmost cell of column.
Control + Down Arrow	Moves focus to bottom cell of column.
Control + Up Arrow	Moves focus to top cell of column.
Shift + Control + Right Arrow	Selects current cell and cells right of it.
Shift + Control + Left Arrow	Selects current cell and cells left of it.
Shift + Control + Down Arrow	Selects current cell and cells below it.
Shift + Control + Up Arrow	Selects current cell and cells above it.
Page Down	Moves focus down to bottom row, scrolling so the bottom row in the currently visible set of rows becomes the first visible row. If focus is in the last row, focus does not move.
Page Up	Moves focus up to top row, scrolling so the top row in the currently visible set of rows becomes the last visible row. If focus is in the first row, focus does not move.
Home	Moves focus to the first cell in the row that contains focus.
End	Moves focus to the last cell in the row that contains focus.
Control + Home	Moves focus to the first cell in the first row.
Control + End	Moves focus to the last cell in the last row.
Control + Space	Selects the column that contains the focus.
Shift + Space	Selects the row that contains the focus. If the grid includes a column with checkboxes for selecting rows, this key can serve as a shortcut for checking the box when focus is not on the checkbox.
Control + A	Selects all cells.
Tab	Moves focus to the next focusable widget on the grid. If currently focused on the last column sort button, focus will move to the top and left most non-header cell in the grid.
Shift + Tab	Moves focus to the previous focusable widget on the grid. If currently focused on the top and left most non-header cell in the grid, focus will move to the last column sort button
Fn + Return (Mac) / Control + Shift + F10 (Windows)	Opens the context menu. See Shift + F10 alternative below for opening the context menu on Mac.
Enter	Opens the context menu if on a column or row header cell. Simultaneously it will also select the contents for the selected column or row. For all interior cells it will attempt to place the cell into edit mode. See below for further information on editing/navigation inside a cell.

Additional MacOS context menu option: Shift + F10

Shift + F10 can also trigger the context menu. This requires the Mac's keyboard be set to support F1-F12 (or F15) to as standard function keys.

According to MacOS User Guide in Use keyboard function keys on Mac:

• On your Mac, choose Apple menu > System Settings, then click Keyboard in the sidebar. (You may need to scroll down.)
• Click Keyboard Shortcuts, then click Function Keys in the sidebar.
• Turn on “Use F1, F2, etc. keys as standard function keys.”

Editing/Navigating Inside a Cell Keyboard Interactions

Key	Description
Enter	Disables grid navigation and if the cell contains editable content, places focus on an input field, such as a textbox. If the input is a text field or includes a selection widget such as a calendar picker or drop-down selection menu, a subsequent selection of an available item will restore navigation and move focus down one cell.
Escape	Restores grid navigation. If content was being edited, it will also undo edits.
Tab	Moves focus to the next widget in the cell. Focus movement will wrap inside a single cell.
Shift + Tab	Moves focus to the previous widget in the cell. Focus movement will wrap inside a single cell.