Tree

addOverlay is used to create, or update an existing, overlay over an existing list row. This allows the caller to apply effects to the row by having elements that appear over top of the row. @param id This is a unique id for this overlay. @param rowIndex The index of the row the overlay should hover over. @param render A function which returns the React nodes that should be placed within the overlay. The parent element will be positioned, and have the same height and width as the underlying row element. @param zIndex If there are multiple overlays the caller can use the zIndex parameter to ensure they are layered correctly. @param columnIndex The index of the column the overlay should hover over (used for column header drag/drop)

Sets the focus to the given row after scrolling to it. If it's not focusable, it will use `direction` to find the closest one. @param rowIndex The index of the row to focus. @param direction Use 1 or -1 to try previous or next rows when given row is not focusable.

Returns an object with the indexes of the first and last materialized and rendered rows.

removeOverlay is used to remove an overlay that has already been registered. The unique id is all that is needed. @param id This is a unique id for this overlay.

scrollIntoView works like the element method in the browser, but instead of being based on the element scrollIntoView will scroll the row specified by the rowIndex into view. @param rowIndex The 0 based rowIndex that should be scrolled into view. @param options These options are passed on to the underlying element. @param onScrollComplete This delegate is called when the scrolling is complete. This may not be immediate if the list has to materialize rows to scroll. NOTE: The rowIndex passed to the delegate will be the requested rowIndex or -1 if another scrollIntoView request is made before this scroll request completes.

ariaLabel allows the caller to describe the elements contents to assistive technology. Used when no column name or icon is provided.

Behaviors can be added a column to monitor events and interact with the column.

CSS className to that should be added to the table cell for each of the values in this column.

This is used to help the table understand the general layout of the data. One of the general purposes of this value is used when data is loaded asynchronously the table will render a loading animation by default and the layout is used to help define the visuals for the animation. A column with no columnLayout defined will use the TableColumnLayout.singleLine style.

cell renders MAY use the column style to apply css or other behaviors to this column.

CSS className that will be added to the cell for each header element.

CSS className that will be added to the header title.

hierarchical should be specified for any column that will show the indentation of the tree expansion.

If iconProps are supplied the Icon will be drawn to the left of the column name in the header cell.

Unique Id for this table. NOTE: If this column uses the renderSimpleCell function the id is used as the property name of the row object to render.

Number of pixels the indentation will apply for each depth.

How to justify the content within cells. Will also effect the position of the sorting arrow

maxWidth defines how large the column MAY grow if the column is resizble. This must be an absolute number, it can't be supplied as a percentage.

minWidth defines how small the column MAY shrink if the column is resizble. This must be an absolute number, it can't be supplied as a percentage.

The name of the column is used to render the column header string. If the column has no header shown or only an icon the name can be omitted.

onSize is triggered when the column header is sized by the user. This is a required property to enable the column to be resized. @param event - This is the mouse or keyboard event that has caused the resize to occur. @param index - This is the 0 based column index being resized. @param width - This is the updated width of the column. Note: this is called with values that conform to the defined min/max values. @param column - This is the column definition for the column being resized.

onSizeEnd is called when the currently active sizing operation has completed. This means the user has stopped sizing the column. Any actions the consumer wants to take when sizing ends, they should implement here.

Mark as readonly if there are no interactive elements in the column

renderCell MUST be supplied for a column. This defines how the column values will be rendered in the table. Row rendering functions should use this function unless the row rendering function has a custom presentation for the row/column. @param rowIndex - This is the 0 based row index. @param columnIndex - This is the 0 based column index. @param tableColumn - This is the column definition for this cell. @param tableItem - This is the object being rendered in this row. @param ariaRowIndex - This is the index of the row that aria will read. @param role - This is the role of child "tr" element.

renderHeaderCell can be supplied to render a custom header. It will be the responsibility of the custom render function to manage all status of the header. This includes all accessibitlity and focus management. @param index - This is the 0 based column index. @param tableColumn - This is the column definition for the header being rendered. @param focuszoneId - Focuszone id that needs to be included if the header is focusable. @param isFirstActionableHeader - True for the first column header that gets focused on keyboard accessibility.

Set to mark the column field as required, primarily for editable grids. This will display an asterisk next to the column name.

Show the column divider for resizable columns

Within a table columns may optionally be sorted. The table will render an indicator in the header by default for the current sort order. SortProps should be supplied for each column that MAY be sorted even if it isn't currently sorted. This allows the table to know which columns are and which are not sortable.

The width of a column can one of two values: Positive value - This is the exact width of the column in pixels. This would be something like 250 to have a 250px column. Negative value - This is the percentage of the remaining space in the containing element this column should consume. This would be something like -100 for 100% of the remaining space. NOTE: This is different than css since we dont want to do unneeded string processing, CSS would have you use a string like 250px or 100%.

The widthStyle can be set when the width is a positive number. By default the width is interpreted as a fixed pixel value. If the column is going to have a small UI representation such as a Coin, User Image, and a button these will scale with font size and should be represented with root EM values. This corresponds to the css rem measurement.

Data that represents the instance of T for this row. In some cases the row data may not be available.

Sets aria-busy on the list item element.

Sets aria-current value if the row matches the requirements of aria-current More information: https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-current

Sets aria-describedby on the list item element.

ariaLabel allows the caller to describe the elements contents to assistive technology.

ariaLabelledBy property enables authors to reference other elements on the page to define an accessible name to assistive technology.

Sets aria-posinset on the tr element. Defaults to the item index.

Amount to offset the aria-rowindex attribute of a row. This should be added to the index to produce the aria-rowindex of the row. The common use case for this property is accounting for the header row of a Table. Per the ARIA spec, a header row should be included in the aria-rowcount, and provided an aria-rowindex of 1, meaning the first actual row of the table needs an aria-rowindex of 2.

Sets aria-setsize on the tr element. Defaults to the itemProvider length.

css class name to add to the rendered row element.

The data represents the object being rendered in this row. If the caller has asynchronous loading of rows, the data MAY be undefined while we wait for the data to be resolved.

An event dispatch the row MAY use to dispatch custom events to list behaviors.

Set to true to exclude the list item from the focus zone.

If false, the row will get tabIndex=0, otherwise tabIndex=-1.

id to add to the rendered row element.

The caller MUST supply the set of items to be shown through the ItemProvider. The IItemProvider allows the caller to store their items in the form that bests suits their needs but gives the table a well defined interface for requesting the items. This can include async fetching of items through observables.

Properties used to render the list as a whole.

The row MUST call onFocusItem when a row or one of the child elements of the row receives focus.

renderSpacer can be supplied to override the spacer columns before and after the actual columns in the table. This is used to apply custom semantics to these areas. The standard spacers should be used unless there is a specific need otherwise.

Sets the aria role on the tr element.

Set to true if text in the list row should be selectable.

A selection object can be supplied for managing the table selection. This is not required since the table offers onSelect as a delegate. If the caller wants multi-selction they must use an IListSelection that supports multi select.

Using singleClickActivation will activate the item when the row is clicked. Where setting singleClickActivation to false will require a doubleclick to activate a given row.

Optional tooltip props to pass to the table row.

ariaLabel allows the caller to describe the elements contents to assistive technology.

Behaviors can be added to the tree and monitor events and interact with the component through the ITree methods.

CSS className to add to the tree root element.

columns is a required property of a tree used to define the column layout for the tree.

CSS className to add to the container element.

The caller can supply an EventDispatch to the tree if it wishes to participate it extending the behaviors. If one isn't supplied the tree will create its own dispatcher when behaviors are supplied.

focuszoneProps allows the caller to manage the how the tree rows are focused. The default focuszone if one isn't supplied is a Vertical non-cyclic focus zone.

Unique Id for this tree.

The caller MUST supply the set of items to be shown through the ItemProvider. The ITreeItemProvider allows the caller to store their items in the form that bests suits their needs but gives the tree a well defined interface for requesting the items. This can include async fetching of items through observables. There is simple TreeItemProvider<T> for those that just have a set of items they want to supply without writing a custom ItemProvider.

The maximum height of the table when virtualized. Browsers have issues rendering elements that are too large and when the List contains thousands of elements, the list renders very large spacer elements to correctly position the scroll bar. The large spacer elements cause rendering issues across browsers. To bypass this, we need to limit how large the list can grow to. By default this size is 100,000px. However, if you have multiple items within a scrollable region, this number might need to be reduced. For instance, if you have 5 lists that can contain a lot of rows in the same scrollable region, you would likely want to set the max height for each list to 20,000. Keep in mind that the smaller this number, the harder it will be for a user to scroll with precision.

onActivate is called when the row is activated. Activation occurs on the Enter keystroke or double click. @param event - This is the event that is causing the activation. @param treeRow - Details about the tree row being activated.

onFocus is called when a item in the list is focused. Preventing default on the focus event will prevent row selection from occuring even if selectOnFocus is set to true. @param event This is the event that is causing the activation. @param tableRow Details about the list row being activated.

onSelect is called when the row is selected. Selection occurs on the Space keystroke or click. @param event - This is the event that is causing the selection. @param treeRow - Details about the tree row being selected.

onToggle is called when an item is either expanded or collapsed. @param event - This is the event that is causing the toggle. @param treeItem - Details about the tree item being toggled.

pageSize controls the granularity of row rendering. The tree always renders a full page worth of rows even when they are not needed to fill the viewport. Smaller values will help reduce the number of wasted rows that are rendered outside the viewport, but will force the tree to re-render more often as scrolling occurs.

Trees MAY render a header above the tree contents. This is done through the onRenderHeader. Like the renderRow method, there are set of restrictions the implmentation MUST follow. Requirements: 1) The header function MUST return a singlely rooted component that resolves to single rooted element, or return a single element that is either a <tr> or another acceptable tag that is marked as a display: table-row. 2) The header function MUST only include direct child elements that are either <td>'s or acceptable elements that are maked as display: table-cell. The renderer MUST return one element for each defined column even if there is no data to be rendered in the column.

When a row's value is given as an ObservableValue with an undefined value, the list will render a Loading row for the content. The default will be a shimmer row that is semi random and matches the content. @param index This is the 0 based row index that should be rendered. @param details Additional details about this row.

The requirements of this function are quite complicated and before writing a new row renderer you should ensure one doesnt already exist that solves your needs. Requirements: 1) The row function MUST return a singlely rooted component that resolves to single rooted element, or return a single element that is either a <tr> or another acceptable tag that is marked as a display: table-row. 2) The row function MUST only include direct child elements that are either <td>'s or acceptable elements that are maked as display: table-cell. The renderer MUST return one element for each defined column even if there is no data to be rendered in the column. 3) The row function MUST call onFocusItem when a either the row element of any of the rows child elements receive the focus. This is needed to ensure navigation within the tree as well as in and out of the tree function correctly. 4) The row function MUST ensure the className for each of the columns is added the cell for the given colmn. 5) The row function MAY dispatch events for behaviors but is not required. If any events are dispatched they should be documented on the row renderer. 6) The row function is responsible for all accessibility and focus management within the row.

renderSpacer can be supplied to override the spacer columns before and after the actual columns in the table. This is used to apply custom semantics to these areas. The standard spacers should be used unless there is a specific need otherwise.

role defines the aria role of the tree and defaults to "tree"

If the caller has variable height rows they can specify the rowHeight they want used to estimate the size of virtualized rows. This means that when rows are not rendered, the component will create virtual space for those rows to ensure the scrolling behavior acts appropriately. If the tree has fixed size rows there is no need to specify a rowHeight. The tree will determine the height of the rows after the initial render when the observer reports on page visibility. Question: How do I determine the rowHeight if their are variable height rows. This one is a tough question, and the general answer is come up with a fair average for the rows on a given page. If the select too large or too small scrolling behaviors can become a bit odd, generally select on the smaller side if you are unsure.

scrollable should be set to true if the tree is not contained in a scrolling element. This will ensure the tree scrolls vertically within the tree element itself.

Set to true to make the text in the tree rows selectable.

A selection object can be supplied for managing the tree selection. This is not required since the tree offers onSelect as a delegate. If the caller wants multi-selction they must use an IListSelection that supports multi select. There is a basic ListSelection implementation available from the List component.

showHeader determines whether or not the column headers are shown at the top of the tree.

showLines determines whether or not lines displayed between rows.

showScroll determines whether we allow overflow on the table if it is false (as in default), we will add scroll-hidden css class to the table

Using singleClickActivation will activate the item when the row is clicked. Where setting singleClickActivation to false will require a doubleclick to activate a given row.

A tree can be defined with a set of breakpoints. These breakpoints will be used to control the column layout as the space available to the tree changes.

If virtualize false is supplied the list will render all the items supplied to it. This shouldn't be used unless you know you have a limited number of rows. Virtualization is used to avoid performance problems.

css class names to add to the row element.

Details about the row being rendered.

This is the 0 based row index.