[Table] specification for table column rendering needed

[bjornalm]

What package is this for?

• [x] React
• [-] Angular

Functionality

Much of the functionality related to the layout of the table columns have been added incrementally over time and often without a clear specification. When it comes to the table column layout we would like to have a clear functional specification for the following cases

• Initial rendering
• Add column
• Remove column
• Show hidden column
• Hide visible column
• Resize column width
• Reorder columns
• Table resize

Parameters

There are many parameters that in an intricate way affect how the table columns are rendered and behave. Many of the parameters can be explored in this story

1. Initial individual column configuration. a. Width (prop table.columns). A column does not need an initial width but if the table has resizable columns it will be assigned a width after it has rendered. For legacy reasons it is possible that some columns have widths and others don’t in the initial rendering. b. Name (prop table.columns). Renders in the table header cell and its length can affect the width of columns that don’t have an explicit width. c. Position (prop table.ordering). A column always has to have a position. d. Hidden (prop table.ordering). The column can exist but can be defined as hidden.
2. Has resizable columns (prop hasResize). Makes the columns resizable by introducing a drag and drop handle per column header. All columns must have a width before any column width altering drag and drop may happen.
3. Table-layout “fixed” vs “auto” (prop useAutoTableLayoutForResize) Tables with resizable columns get the CSS table-layout:fixed by default. “fixed” means that all columns have the same width unless specific widths have been assigned, and “auto” means that the column widths are automatically set based on the content of the cells. This mainly affects the rendering when the columns don’t have a width defined, but the width of the column is also better respected when table-layout is “fixed”.
4. Column min-width. Not a prop but a hardcoded value of 62px (with extra padding for sort and overflow menus) that prevents users from shrinking resizable columns below that width using drag and drop.
5. Width of parent element holding the Table. Not a table prop but it will affect if the table uses horizontal scrollbars when the total width of visible columns exceeds the width of the parent container.
6. Table body cell content and length (prop data). Can affect the width of columns together with table cell text overflow.
7. Table cell text overflow (prop wrapCellText). Determines how long cell texts are managed by either a. Wrap for tables with dynamic column widths and truncate for tables with fixed or resizable columns (auto) b. Wrap if needed for all table column configurations (always) c. Tables with dynamic columns widths grow larger and tables with fixed or resizable columns truncate (never) d. Always truncate if needed for all table column configurations (alwaysTruncate)
8. Expander column. Not a table prop but good to know about. Tables with resizable columns and Table-layout “fixed” will get a special automatically expanding column added to the right of the last column. The expander column will occupy unused space and let the rightmost column be resizable into that space. For table-layout:auto there is no expander column.
9. Row actions. Row actions introduces an additional column at the right of the table with a min width that must be considered for table column layout.
10. Toggled filters. Toggled filters add additional content to each column on a new row, e.g. a dropdown, that could affect the minimum width needed to correctly render the column.
11. Row selections. Introduces an additional column.
12. Sort/Multisort?

Example of current complexity

We can use the example of horizontal scrollbars on initial rendering to illustrate the complexity. The table will get a horizontal scrollbar if

• the table has a parent container with fixed width
• and columns have explicit widths defined (being resizable or not)
• and the sum of the column lengths* exceeds the width of the parent container.

Or

• the table has a parent container with fixed width
• the table itself has table-layout:“auto” (prop useAutoTableLayoutForResize:true)
• and the table body cell text overflow is set to never wrap (prop wrapCellText:never)
• The length of table body cell texts* causes the browser to render the table wider than the parent container width

Or

• the table has a parent container with fixed width
• the table itself has table-layout:“auto” (prop useAutoTableLayoutForResize:true)
• and the length of the column names* causes the browser to render the table wider than the parent container width.

*) The sum of column lengths must also include the length of additional columns added for actions, row selections and other features.

Note, the column min-width only applies to the actual manual resize, not on columns in general so it will currently not affect horizontal scrollbars.

Example of functionality that changed back and forth in lack of proper spec

How do we handle the width of existing columns when new columns are added or existing ones are removed. The answer to that question needs to take many of the above listed parameters into account.

Available extra resources

What resources do you have to assist this effort?

Carbon add-ons for Watson IoT is a collaborative system. We encourage teams to build components and submit them for integration.

[kevinsperrine]

Also relevant to this discussion: https://github.com/carbon-design-system/carbon-addons-iot-react/issues/2317

[davidicus]

Links to spec: https://pages.github.ibm.com/ai-applications/design/components/datatable/columncustomization#column-resizing https://pages.github.ibm.com/cdai-design/pal/patterns/data-table/resizable-columns

[dianasanborn]

Thanks for sharing the links David.

To summarize on the design side:

• We have some very basic guidance on column resizing here under our column customization guidance. Although, we don't have much guidance on the width of the columns on the table themselves when they are added/removed
• The Cloud & Cognitive team just recently released their guidance on resizing columns as well. We got our initial basic guidance from them, so this is the extended guidance they've worked through. There might be some other use cases outlined there that we don't necessarily support, but you can see the resizing behaviors.

I'll call out this specific line

Resizing data table columns is intended to help users with better consume their content. Resizing columns will push all of the columns to the right of it and they will retain their current widths. If the content gets pushed outside the data table’s visible area, a horizontal scroll bar will appear as a visual signifier to the user.

[davidicus]

@bjornalm Is this epic closed by your recent work on the Table. If not, what other issues are linked?

[bjornalm]

There is still no functional spec that covers all of this, but I think the some of the more confusing parts of it will become a bit more intuitive and have fewer corner cases with the implementation of #2658 if we make that the only option in V3.