From 5d3f7008cdf22463e899fe8018972dab45229c36 Mon Sep 17 00:00:00 2001 From: mollykreis <20542556+mollykreis@users.noreply.github.com> Date: Mon, 1 Apr 2024 15:00:38 -0500 Subject: [PATCH 01/16] Update table-column-mapping.md --- .../table-column-mapping.md | 141 +++++------------- 1 file changed, 37 insertions(+), 104 deletions(-) diff --git a/packages/nimble-components/src/table/specs/table-column-specs/table-column-mapping.md b/packages/nimble-components/src/table/specs/table-column-specs/table-column-mapping.md index c58c1e475e..f3c91a0d6a 100644 --- a/packages/nimble-components/src/table/specs/table-column-specs/table-column-mapping.md +++ b/packages/nimble-components/src/table/specs/table-column-specs/table-column-mapping.md @@ -2,7 +2,7 @@ ## Overview -The `nimble-table-column-enum-text` is a component that supports rendering specific number, boolean, or string values as mapped text. `nimble-table-column-icon` instead maps values to icons and/or spinners. The actual mappings are defined by child elements `nimble-mapping-icon`, `nimble-mapping-spinner`, and `nimble-mapping-text`. +The `nimble-table-column-icon` is a component that supports rendering specific number, boolean, or string values as to icon/label pairs and/or spinner/label pairs. The mappings are defined by child elements of `nimble-mapping-icon` and `nimble-mapping-spinner`. ### Background @@ -20,6 +20,7 @@ The `nimble-table-column-enum-text` is a component that supports rendering speci - Text - Icon - Spinner + - Icon (or Spinner) with text - (empty) ### Non-goals @@ -27,7 +28,6 @@ The `nimble-table-column-enum-text` is a component that supports rendering speci - Non-Nimble icon support - Arbitrary icon colors - Hyperlink icons -- Mixed text and icons - Non-icon, non-spinner Nimble components --- @@ -36,31 +36,33 @@ The `nimble-table-column-enum-text` is a component that supports rendering speci Below is an example of how these elements would be used within a `nimble-table`: +// mkreis TODO: update example ```HTML - + Status - + Error Code - + Archived + ``` Each column contains mapping elements that define what to render when the cell's value matches the given `key` value. -When none of the given mappings match the record value for a cell, that cell will be empty. +When none of the given mappings match the record value for a cell, that cell will be empty. While the table will not enter an error state, this is considered invalid data from the table's perspective and should be fixed within the client application. The column will translate its contained mapping elements into a map that is stored in the `columnConfig`. @@ -70,7 +72,7 @@ If multiple mappings in a column have the same key, an error flag will be set on If an invalid `icon` value is passed to `nimble-mapping-icon`, an error flag will be set on the column's validity object. An invalid `icon` value is any element that cannot be resolved or that does not derive from `Icon`. -`nimble-table-column-icon` supports only `nimble-mapping-icon` and `nimble-mapping-spinner` as mapping elements. `nimble-table-column-enum-text` supports only `nimble-mapping-text`. Unsupported mappings will result in an error flag being set on the column's validity object. +`nimble-table-column-icon` supports only `nimble-mapping-icon` and `nimble-mapping-spinner` as mapping elements. Unsupported mappings will result in an error flag being set on the column's validity object. Text in a grouping header or in the cell will be ellipsized and gain a tooltip when the full text is too long to display. @@ -102,30 +104,14 @@ _Props/Attrs_ - `field-name`: string - `key-type`: 'string' | 'number' | 'boolean' +- `label-hidden`: boolean - When `true`, the `label` for a mapping will be rendered in a cell next to the specified icon. Note, that this attribute only affects what is rendered in a cell; a group row will always render both the icon and the label. +- `icon-width`: boolean - When `true`, the column will have a fixed width that makes the column the appropriate width to render only a single icon in the cell. This should only be set to `true` when the header contains a single icon (no text) and `label-hidden` is `true`. If set to `true` when `label-hidden` is `false`, the column's configuration will be considered invalid. _Content_ -- column title (icon) +- column title - 1 or more `nimble-mapping-icon` or `nimble-mapping-spinner` elements -#### General mapping column element: - -_Component Name_ - -- `nimble-table-column-enum-text` - -_Props/Attrs_ - -- `field-name`: string -- `key-type`: 'string' | 'number' | 'boolean' -- `fractional-width`: number (defaults to 1) -- `min-pixel-width`: number (defaults to minimum supported by table) - -_Content_ - -- column title (text or icon) -- 1 or more `nimble-mapping-text` elements - #### Mapping element (icon): _Component Name_ @@ -135,9 +121,9 @@ _Component Name_ _Props/Attrs_ - `key`: string | number | boolean | undefined -- `icon`: string - name of the Nimble icon element +- `icon`: string | undefined - name of the Nimble icon element. If `undefined`, no icon will be associated with the given `key`. - `severity`: string - one of the supported enum values. Controls color of the icon. -- `label`: string - localized value used as the accessible name and `title` of the icon. Will also be displayed in the group header. +- `label`: string - localized value associated with the given `key`. #### Mapping element (spinner): @@ -148,50 +134,7 @@ _Component Name_ _Props/Attrs_ - `key`: string | number | boolean | undefined -- `label`: string - localized value used as the accessible name and `title` of the spinner. Will also be displayed in the group header. - -#### Mapping element (text): - -_Component Name_ - -- `nimble-mapping-text` - -_Props/Attrs_ - -- `key`: string | number | boolean | undefined -- `label`: string - display text - -### Anatomy - -#### `nimble-table-column-enum-text` - -```HTML - -``` - -Cell view: - -The cell view relies on the matched mapping to provide a template to render. - -```HTML -html`${x => x.getMappingToRender().cellViewTemplate}` -``` - -Group header view: - -Similarly, the group header view relies on the matched mapping to provide a template to render. - -```HTML -html`${x => x.getMappingToRender().groupHeaderViewTemplate}` -``` +- `label`: string - localized value associated with the given `key`. #### `nimble-mapping-*` @@ -205,38 +148,33 @@ html`${x => x.getMappingToRender().groupHeaderView ```HTML <${this.icon} - title="${x => x.label}" - aria-label="${x => x.label}" + title="${x => x.labelHidden ? x.label: null}" + aria-label="${x => x.labelHidden ? x.label: null}" + aria-hidden="${x => x.labelHidden ? 'false' : 'true'}" severity="${x => x.severity}"> +${when(() => !x.labelHidden, html` + ${x => x.label} +`)} ``` `mapping.groupHeaderViewTemplate`: ```HTML <${this.icon} - title="${x => x.label}" - aria-label="${x => x.label}" + aria-hidden="${x => x.labelHidden ? 'false' : 'true'}" severity="${x => x.severity}"> - (x.isValidContentAndHasOverflow ? x.label : null)}> + ${x => x.label} `; ``` ### Grouping -Grouping will be based on the record value. The grouping header will display the rendered icon/spinner/text. In the case of an icon/spinner, it will also be followed by the `label` text. This will disambiguate cases where multiple record values map to the same icon (assuming the labels are different). +Grouping will be based on the record value. The grouping header will display the rendered label along with the icon/spinner, if configured. -For values that do not match any mapping, we will display the raw data value. While this introduces inconsistency, it seems preferable to the alternative, which is having multiple, separate groupings with a blank header (well, with just the item count in parens). Even in the case where there is a default mapping, we would still end up with separate groups with the identical default mapped icon and/or text, which is just as bad. +For values that do not match any mapping, the group row will display only the count. This is considered invalid data from the table's perspective and should be fixed within the client application. Text in a grouping header will be ellipsized and gain a tooltip if there is not enough room to display it all. @@ -258,25 +196,20 @@ For icons, if multiple values map to the same icon, it is possible that sorting ### Sizing -`nimble-table-column-icon` will be a fixed pixel size (32px) and will not be resizable. The 32px fixed size allows room from a single icon along with left and right cell padding of 8px each. +By default ,the `nimble-table-column-icon` will be a fractional width column with a fractional width of 1. However, it can be configured to be a fixed pixel size (32px) and not be resizable by setting `icon-width` to `true` on the column. The 32px fixed size allows room from a single icon along with left and right cell padding of 8px each. -This has the following implications: +When the column is a fixed 32px: -- The grouping indicator and sorting indicator will always be hidden on the icon column. +- The grouping indicator and sorting indicator will be hidden in the column header. - A client is expected to only place an icon as the header content of an icon column. - A user cannot resize an icon column. -- There will be no public API exposed on the icon column related to sizing. Unlike other columns today, the icon column will not have attributes for `min-pixel-width` or `fractional-width`. +- Column sizing configuration on the column, such as `fractional-width`, will be ignored. This will be accomplished through the following configuration on the column: -- The icon column will not use the `mixinFractionalWidthColumnAPI` mixin because it will not expose a sizing API. - The icon column will set `columnInternals.resizingDisabled` to `true`. - The icon column will set both `columnInternals.pixelWidth` and `columnInternals.minPixelWidth` to `32`, which is equal to the icon size plus left and right paddings of 8px -In the future, we can consider adding an API to allow the icon column to have its size configured by a user and/or client, but that is currently out of scope. - -`nimble-table-column-enum-text` will support fixed or fractional widths. If `pixel-width` is set, the column will have a fixed width, otherwise it defaults to a fractional width of 1. The client may configure `fractional-width` and/or `min-pixel-width`. - ### Angular integration Angular directives will be created for the column components and the mapping components. No component has form association, so a `ControlValueAccessor` will not be created. @@ -286,10 +219,10 @@ Angular directives will be created for the column components and the mapping com Blazor wrappers will be created for the components. Columns will be generic in the type of the key, and will cascade that type parameter to contained mapping elements (see [`CascadingTypeParameter`](https://learn.microsoft.com/en-us/aspnet/core/blazor/components/generic-type-support?view=aspnetcore-7.0#cascaded-generic-type-support)): ```HTML - - - - + + + + ``` ### Visual Appearance @@ -306,7 +239,9 @@ N/A ### Accessibility -Text, icons, and spinner are not interactive and cannot receive keyboard focus. These items already have proper accessibility roles, and we will set accessible names (`aria-label`) based on the `label` value provided by the client. +- Text, icons, and spinner are not interactive and cannot receive keyboard focus. +- In group rows, the rendered icon/spinner will have `aria-hidden="true"` set because the label is displayed directly next to the icon. The icon/spinner is purely decorative, and it does not contain any additional information that needs to be available with a screen reader. +- In table cells, if an icon/spinner is displayed with the label, the icon/spinner will have `aria-hidden="true"` set for the same reason explained for group rows above. However, if the label is not displayed, the icon/spinner will have a role of `img` and use the label as its `title` and `aria-label`. ### Globalization @@ -330,10 +265,8 @@ None - renders mapping matching the cell value (string, number, and boolean) - nothing rendered when value matches no mappings - validation error when non-unique mapping keys exist - - validation error when multiple mappings marked as default - - validation error when mapping key is null and not marked default - validation error when invalid icon name given - - validation error when icon column has a `nimble-mapping-text` element + - validation error when `icon-width` is set to `true` while `label-hidden` is set to `false` - grouping header for icon column includes label - Verify manually that the column content appears in the accessibility tree and can be read by a screen reader. - Verify manually that several mapping columns with thousands of elements scrolls performantly. From 1dbb9f35b0bf19a4b7740487d863acfb3fea47dc Mon Sep 17 00:00:00 2001 From: mollykreis <20542556+mollykreis@users.noreply.github.com> Date: Mon, 1 Apr 2024 15:01:43 -0500 Subject: [PATCH 02/16] Change files --- ...le-components-e559fa6d-6507-478a-9e4e-889ea5cb3c9d.json | 7 +++++++ 1 file changed, 7 insertions(+) create mode 100644 change/@ni-nimble-components-e559fa6d-6507-478a-9e4e-889ea5cb3c9d.json diff --git a/change/@ni-nimble-components-e559fa6d-6507-478a-9e4e-889ea5cb3c9d.json b/change/@ni-nimble-components-e559fa6d-6507-478a-9e4e-889ea5cb3c9d.json new file mode 100644 index 0000000000..2efc9774d5 --- /dev/null +++ b/change/@ni-nimble-components-e559fa6d-6507-478a-9e4e-889ea5cb3c9d.json @@ -0,0 +1,7 @@ +{ + "type": "none", + "comment": "Update mapping column HLD with new plan of supporting icon + text in the same cell", + "packageName": "@ni/nimble-components", + "email": "20542556+mollykreis@users.noreply.github.com", + "dependentChangeType": "none" +} From 1aea91602d00614a78c2b6dc1d045b22acbd468c Mon Sep 17 00:00:00 2001 From: mollykreis <20542556+mollykreis@users.noreply.github.com> Date: Mon, 1 Apr 2024 15:08:38 -0500 Subject: [PATCH 03/16] Update table-column-mapping.md --- .../src/table/specs/table-column-specs/table-column-mapping.md | 1 - 1 file changed, 1 deletion(-) diff --git a/packages/nimble-components/src/table/specs/table-column-specs/table-column-mapping.md b/packages/nimble-components/src/table/specs/table-column-specs/table-column-mapping.md index f3c91a0d6a..30be3509b0 100644 --- a/packages/nimble-components/src/table/specs/table-column-specs/table-column-mapping.md +++ b/packages/nimble-components/src/table/specs/table-column-specs/table-column-mapping.md @@ -36,7 +36,6 @@ The `nimble-table-column-icon` is a component that supports rendering specific n Below is an example of how these elements would be used within a `nimble-table`: -// mkreis TODO: update example ```HTML From 27f27df331f0043aad59a96af46bde853e5518c3 Mon Sep 17 00:00:00 2001 From: mollykreis <20542556+mollykreis@users.noreply.github.com> Date: Mon, 1 Apr 2024 15:40:30 -0500 Subject: [PATCH 04/16] Update table-column-mapping.md --- .../table-column-specs/table-column-mapping.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/packages/nimble-components/src/table/specs/table-column-specs/table-column-mapping.md b/packages/nimble-components/src/table/specs/table-column-specs/table-column-mapping.md index 30be3509b0..a371170f1e 100644 --- a/packages/nimble-components/src/table/specs/table-column-specs/table-column-mapping.md +++ b/packages/nimble-components/src/table/specs/table-column-specs/table-column-mapping.md @@ -2,7 +2,7 @@ ## Overview -The `nimble-table-column-icon` is a component that supports rendering specific number, boolean, or string values as to icon/label pairs and/or spinner/label pairs. The mappings are defined by child elements of `nimble-mapping-icon` and `nimble-mapping-spinner`. +The `nimble-table-column-icon` is a component that supports rendering specific number, boolean, or string values as icon/label pairs and/or spinner/label pairs. The mappings are defined by child elements of `nimble-mapping-icon` and `nimble-mapping-spinner`. ### Background @@ -20,7 +20,8 @@ The `nimble-table-column-icon` is a component that supports rendering specific n - Text - Icon - Spinner - - Icon (or Spinner) with text + - Icon with text + - Spinner with text - (empty) ### Non-goals @@ -38,7 +39,7 @@ Below is an example of how these elements would be used within a `nimble-table`: ```HTML - + Status @@ -103,8 +104,8 @@ _Props/Attrs_ - `field-name`: string - `key-type`: 'string' | 'number' | 'boolean' -- `label-hidden`: boolean - When `true`, the `label` for a mapping will be rendered in a cell next to the specified icon. Note, that this attribute only affects what is rendered in a cell; a group row will always render both the icon and the label. -- `icon-width`: boolean - When `true`, the column will have a fixed width that makes the column the appropriate width to render only a single icon in the cell. This should only be set to `true` when the header contains a single icon (no text) and `label-hidden` is `true`. If set to `true` when `label-hidden` is `false`, the column's configuration will be considered invalid. +- `display`: enum with possible values of `iconOnly`, `labelOnly`, and `iconAndLabel` - Specifies what is rendered in a cell for the column. Note, that this attribute only affects a cell's rendering; a group row will always render both the icon and the label. +- `icon-width`: boolean - When `true`, the column will have a fixed width that makes the column the appropriate width to render only a single icon in the cell. This should only be set to `true` when the header contains a single icon (no text) and `display` is `iconOnly`. If set to `true` when `display` is not `iconOnly`, the column's configuration will be considered invalid. _Content_ @@ -265,7 +266,7 @@ None - nothing rendered when value matches no mappings - validation error when non-unique mapping keys exist - validation error when invalid icon name given - - validation error when `icon-width` is set to `true` while `label-hidden` is set to `false` + - validation error when `icon-width` is set to `true` while `display` is not `iconOnly` - grouping header for icon column includes label - Verify manually that the column content appears in the accessibility tree and can be read by a screen reader. - Verify manually that several mapping columns with thousands of elements scrolls performantly. From 35335d61a43652e696f33dfa851a0ceeba8974c1 Mon Sep 17 00:00:00 2001 From: mollykreis <20542556+mollykreis@users.noreply.github.com> Date: Tue, 2 Apr 2024 11:36:39 -0500 Subject: [PATCH 05/16] Update packages/nimble-components/src/table/specs/table-column-specs/table-column-mapping.md Co-authored-by: m-akinc <7282195+m-akinc@users.noreply.github.com> --- .../src/table/specs/table-column-specs/table-column-mapping.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/nimble-components/src/table/specs/table-column-specs/table-column-mapping.md b/packages/nimble-components/src/table/specs/table-column-specs/table-column-mapping.md index a371170f1e..076950f66f 100644 --- a/packages/nimble-components/src/table/specs/table-column-specs/table-column-mapping.md +++ b/packages/nimble-components/src/table/specs/table-column-specs/table-column-mapping.md @@ -109,7 +109,7 @@ _Props/Attrs_ _Content_ -- column title +- column title (icon and/or text) - 1 or more `nimble-mapping-icon` or `nimble-mapping-spinner` elements #### Mapping element (icon): From 3aef59f68b50496f3f124188989eb008f71e346e Mon Sep 17 00:00:00 2001 From: mollykreis <20542556+mollykreis@users.noreply.github.com> Date: Tue, 2 Apr 2024 11:42:36 -0500 Subject: [PATCH 06/16] remove usages of nimble-mapping-text --- .../specs/table-column-specs/table-column-mapping.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/packages/nimble-components/src/table/specs/table-column-specs/table-column-mapping.md b/packages/nimble-components/src/table/specs/table-column-specs/table-column-mapping.md index a371170f1e..b0b17a21bb 100644 --- a/packages/nimble-components/src/table/specs/table-column-specs/table-column-mapping.md +++ b/packages/nimble-components/src/table/specs/table-column-specs/table-column-mapping.md @@ -48,9 +48,9 @@ Below is an example of how these elements would be used within a `nimble-table`: Error Code - - - + + + Archived @@ -183,9 +183,9 @@ Text in a grouping header will be ellipsized and gain a tooltip if there is not Sorting will be based on the record value. For boolean and number values, a basic sort (just using basic comparison/equality operators) is the clear choice. For string values, it is less clear. In the case where the strings are enum values, they are likely to be non-localized, English strings. Using a basic (alphabetical) sort is not unreasonable. However, if there is a semantically meaningful sort order (e.g. "NOT_STARTED" < "RUNNING" < "DONE"), it would be nice to sort by that. We can only infer that semantic order from the order in which the mappings are given, e.g.: ```HTML - - - + + + ``` We would need new support for sorting this way. We could define a new sorting option, "enumerated sort", where the column provides an ordered list of values, and the table sorts the column based on that given order. To compare the relative order of two values, we have to search the list, making the sort operation a bit more expensive, but still probably reasonable except in the case of enums with many values. From 38cfd13e74e8fc7dee065c76ef84c9d5af3d6f2c Mon Sep 17 00:00:00 2001 From: mollykreis <20542556+mollykreis@users.noreply.github.com> Date: Tue, 2 Apr 2024 16:25:34 -0500 Subject: [PATCH 07/16] lots of updates --- .../table-column-mapping.md | 101 +++++++++++++----- 1 file changed, 72 insertions(+), 29 deletions(-) diff --git a/packages/nimble-components/src/table/specs/table-column-specs/table-column-mapping.md b/packages/nimble-components/src/table/specs/table-column-specs/table-column-mapping.md index 6fb3964f00..068507e581 100644 --- a/packages/nimble-components/src/table/specs/table-column-specs/table-column-mapping.md +++ b/packages/nimble-components/src/table/specs/table-column-specs/table-column-mapping.md @@ -2,7 +2,7 @@ ## Overview -The `nimble-table-column-icon` is a component that supports rendering specific number, boolean, or string values as icon/label pairs and/or spinner/label pairs. The mappings are defined by child elements of `nimble-mapping-icon` and `nimble-mapping-spinner`. +The `nimble-table-column-enum` is a component that supports rendering specific number, boolean, or string values as an icon, a spinner, text, or an icon/spinner with text. The mappings are defined by child elements of `nimble-mapping-icon`, `nimble-mapping-spinner`, `nimble-mapping-text`, or `nimble-mapping-placeholder`. ### Background @@ -30,6 +30,8 @@ The `nimble-table-column-icon` is a component that supports rendering specific n - Arbitrary icon colors - Hyperlink icons - Non-icon, non-spinner Nimble components +- Specifying different text for an icon/spinner's label than the overall label of the mapping +- Detecting that only icons/spinners can be rendered in the cells and column header and automatically making the column non-resizable and 32px --- @@ -39,24 +41,24 @@ Below is an example of how these elements would be used within a `nimble-table`: ```HTML - + Status - - + + Error Code - - - - - + + + + + Archived - - - + + + ``` @@ -72,7 +74,7 @@ If multiple mappings in a column have the same key, an error flag will be set on If an invalid `icon` value is passed to `nimble-mapping-icon`, an error flag will be set on the column's validity object. An invalid `icon` value is any element that cannot be resolved or that does not derive from `Icon`. -`nimble-table-column-icon` supports only `nimble-mapping-icon` and `nimble-mapping-spinner` as mapping elements. Unsupported mappings will result in an error flag being set on the column's validity object. +`nimble-table-column-enum` supports `nimble-mapping-icon`, `nimble-mapping-spinner`, `nimble-mapping-text`, and `nimble-mapping-placeholder` as mapping elements. Unsupported mappings will result in an error flag being set on the column's validity object. Text in a grouping header or in the cell will be ellipsized and gain a tooltip when the full text is too long to display. @@ -94,26 +96,27 @@ Cons: ### API -#### Icon column element: +#### Enum column element: _Component Name_ -- `nimble-table-column-icon` +- `nimble-table-column-enum` _Props/Attrs_ - `field-name`: string - `key-type`: 'string' | 'number' | 'boolean' -- `display`: enum with possible values of `iconOnly`, `labelOnly`, and `iconAndLabel` - Specifies what is rendered in a cell for the column. Note, that this attribute only affects a cell's rendering; a group row will always render both the icon and the label. -- `icon-width`: boolean - When `true`, the column will have a fixed width that makes the column the appropriate width to render only a single icon in the cell. This should only be set to `true` when the header contains a single icon (no text) and `display` is `iconOnly`. If set to `true` when `display` is not `iconOnly`, the column's configuration will be considered invalid. +- `fixed-to-icon-width`: boolean - When `true`, the column will have a fixed width that makes the column the appropriate width to render only a single icon in the cell. This should only be set to `true` when the header contains a single icon (no text) and none of the child mapping elements will result in text being rendered in a cell. _Content_ - column title (icon and/or text) -- 1 or more `nimble-mapping-icon` or `nimble-mapping-spinner` elements +- 1 or more `nimble-mapping-icon`, `nimble-mapping-spinner`, `nimble-mapping-text`, or `nimble-mapping-placeholder` elements #### Mapping element (icon): +The icon mapping element will support displaying an icon, icon + text, or only text in a cell. If only text is displayed in a cell, space will be reserved for an icon so that the text associated with all icon mapping elements is aligned. A group row associated with an icon mapping element will always display the icon, if specified, and text. + _Component Name_ - `nimble-mapping-icon` @@ -121,12 +124,20 @@ _Component Name_ _Props/Attrs_ - `key`: string | number | boolean | undefined -- `icon`: string | undefined - name of the Nimble icon element. If `undefined`, no icon will be associated with the given `key`. +- `icon`: string | undefined - name of the Nimble icon element. If `undefined`, no icon will be associated with the given `key`, but space will be reserved in the cell for an icon. - `severity`: string - one of the supported enum values. Controls color of the icon. - `label`: string - localized value associated with the given `key`. +- `label-hidden`: boolean - When set, the label will not be rendered within a cell. When unset, the label will be rendered with a cell. This does not affect the rendering of group rows; group rows will always display the label associated with the mapping. + +The label will be used in the following places: +- In the group row for a mapping +- If `label-hidden` is set, as the accessible name and `title` of the icon within a cell +- If `label-hidden` is not set, as text rendered next to the icon within a cell #### Mapping element (spinner): +The spinner mapping element will support displaying a spinner or spinner + text in a cell. A group row associated with a spinner mapping element will always display the spinner and text. + _Component Name_ - `nimble-mapping-spinner` @@ -135,6 +146,38 @@ _Props/Attrs_ - `key`: string | number | boolean | undefined - `label`: string - localized value associated with the given `key`. +- `label-hidden`: boolean - When set, the label will not be rendered within a cell. When unset, the label will be rendered with a cell. This does not affect the rendering of group rows; group rows will always display the label associated with the mapping. + +The label will be used in the following places: +- In the group row for a mapping +- If `label-hidden` is set, as the accessible name and `title` of the spinner within a cell +- If `label-hidden` is not set, as text rendered next to the spinner within a cell + +#### Mapping element (text): + +The text mapping element will support displaying text in a cell. A group row associated with a text mapping will also display the text associated with the mapping. + +_Component Name_ + +- `nimble-mapping-text` + +_Props/Attrs_ + +- `key`: string | number | boolean | undefined +- `label`: string - display text + +#### Mapping element (placeholder): + +The placeholder mapping element will display an empty cell. A group row associated with a placeholder mapping will display the mapping's text. The purpose of the placeholder mapping element is to allow clients to avoid cluttering their table with information that isn't particularly helpful to a user (e.g. that the state of a system is 'idle') while still having a good grouping experience that ensures group rows are not blank. + +_Component Name_ + +- `nimble-mapping-placeholder` + +_Props/Attrs_ + +- `key`: string | number | boolean | undefined +- `label`: string - display text #### `nimble-mapping-*` @@ -149,6 +192,7 @@ _Props/Attrs_ ```HTML <${this.icon} title="${x => x.labelHidden ? x.label: null}" + role="img" aria-label="${x => x.labelHidden ? x.label: null}" aria-hidden="${x => x.labelHidden ? 'false' : 'true'}" severity="${x => x.severity}"> @@ -162,7 +206,7 @@ ${when(() => !x.labelHidden, html` ```HTML <${this.icon} - aria-hidden="${x => x.labelHidden ? 'false' : 'true'}" + aria-hidden="true" severity="${x => x.severity}"> @@ -183,9 +227,9 @@ Text in a grouping header will be ellipsized and gain a tooltip if there is not Sorting will be based on the record value. For boolean and number values, a basic sort (just using basic comparison/equality operators) is the clear choice. For string values, it is less clear. In the case where the strings are enum values, they are likely to be non-localized, English strings. Using a basic (alphabetical) sort is not unreasonable. However, if there is a semantically meaningful sort order (e.g. "NOT_STARTED" < "RUNNING" < "DONE"), it would be nice to sort by that. We can only infer that semantic order from the order in which the mappings are given, e.g.: ```HTML - - - + + + ``` We would need new support for sorting this way. We could define a new sorting option, "enumerated sort", where the column provides an ordered list of values, and the table sorts the column based on that given order. To compare the relative order of two values, we have to search the list, making the sort operation a bit more expensive, but still probably reasonable except in the case of enums with many values. @@ -196,7 +240,7 @@ For icons, if multiple values map to the same icon, it is possible that sorting ### Sizing -By default ,the `nimble-table-column-icon` will be a fractional width column with a fractional width of 1. However, it can be configured to be a fixed pixel size (32px) and not be resizable by setting `icon-width` to `true` on the column. The 32px fixed size allows room from a single icon along with left and right cell padding of 8px each. +By default, the `nimble-table-column-enum` will be a fractional width column with a fractional width of 1. However, it can be configured to be a fixed pixel size (32px) and not be resizable by setting `fixed-to-icon-width` on the column. The 32px fixed size allows room from a single icon or spinner along with left and right cell padding of 8px each. When the column is a fixed 32px: @@ -219,10 +263,10 @@ Angular directives will be created for the column components and the mapping com Blazor wrappers will be created for the components. Columns will be generic in the type of the key, and will cascade that type parameter to contained mapping elements (see [`CascadingTypeParameter`](https://learn.microsoft.com/en-us/aspnet/core/blazor/components/generic-type-support?view=aspnetcore-7.0#cascaded-generic-type-support)): ```HTML - - - - + + + + ``` ### Visual Appearance @@ -266,7 +310,6 @@ None - nothing rendered when value matches no mappings - validation error when non-unique mapping keys exist - validation error when invalid icon name given - - validation error when `icon-width` is set to `true` while `display` is not `iconOnly` - grouping header for icon column includes label - Verify manually that the column content appears in the accessibility tree and can be read by a screen reader. - Verify manually that several mapping columns with thousands of elements scrolls performantly. From a939ea2d3cbf44512bf3ecb156fb461869ffa4f1 Mon Sep 17 00:00:00 2001 From: mollykreis <20542556+mollykreis@users.noreply.github.com> Date: Tue, 2 Apr 2024 16:29:51 -0500 Subject: [PATCH 08/16] format --- .../src/table/specs/table-column-specs/table-column-mapping.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/packages/nimble-components/src/table/specs/table-column-specs/table-column-mapping.md b/packages/nimble-components/src/table/specs/table-column-specs/table-column-mapping.md index 068507e581..e1d076b82d 100644 --- a/packages/nimble-components/src/table/specs/table-column-specs/table-column-mapping.md +++ b/packages/nimble-components/src/table/specs/table-column-specs/table-column-mapping.md @@ -130,6 +130,7 @@ _Props/Attrs_ - `label-hidden`: boolean - When set, the label will not be rendered within a cell. When unset, the label will be rendered with a cell. This does not affect the rendering of group rows; group rows will always display the label associated with the mapping. The label will be used in the following places: + - In the group row for a mapping - If `label-hidden` is set, as the accessible name and `title` of the icon within a cell - If `label-hidden` is not set, as text rendered next to the icon within a cell @@ -149,6 +150,7 @@ _Props/Attrs_ - `label-hidden`: boolean - When set, the label will not be rendered within a cell. When unset, the label will be rendered with a cell. This does not affect the rendering of group rows; group rows will always display the label associated with the mapping. The label will be used in the following places: + - In the group row for a mapping - If `label-hidden` is set, as the accessible name and `title` of the spinner within a cell - If `label-hidden` is not set, as text rendered next to the spinner within a cell From 96ac08fc6ad47040e42274c3a95b2ecadf236d6a Mon Sep 17 00:00:00 2001 From: mollykreis <20542556+mollykreis@users.noreply.github.com> Date: Wed, 3 Apr 2024 12:27:01 -0500 Subject: [PATCH 09/16] minor updates --- .../table/specs/table-column-specs/table-column-mapping.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/packages/nimble-components/src/table/specs/table-column-specs/table-column-mapping.md b/packages/nimble-components/src/table/specs/table-column-specs/table-column-mapping.md index e1d076b82d..5ad9f7e07f 100644 --- a/packages/nimble-components/src/table/specs/table-column-specs/table-column-mapping.md +++ b/packages/nimble-components/src/table/specs/table-column-specs/table-column-mapping.md @@ -106,7 +106,7 @@ _Props/Attrs_ - `field-name`: string - `key-type`: 'string' | 'number' | 'boolean' -- `fixed-to-icon-width`: boolean - When `true`, the column will have a fixed width that makes the column the appropriate width to render only a single icon in the cell. This should only be set to `true` when the header contains a single icon (no text) and none of the child mapping elements will result in text being rendered in a cell. +- `fixed-to-icon-width`: boolean - When set, the column will have a fixed width that makes the column the appropriate width to render only a single icon in the cell. This should only be set when the header contains a single icon (no text) and none of the child mapping elements will result in text being rendered in a cell. _Content_ @@ -115,7 +115,7 @@ _Content_ #### Mapping element (icon): -The icon mapping element will support displaying an icon, icon + text, or only text in a cell. If only text is displayed in a cell, space will be reserved for an icon so that the text associated with all icon mapping elements is aligned. A group row associated with an icon mapping element will always display the icon, if specified, and text. +The icon mapping element will support displaying an icon, icon with text, or only text in a cell. If only text is displayed in a cell, space will be reserved for an icon so that the text associated with all icon mapping elements is aligned. A group row associated with an icon mapping element will always display the icon, if specified, and text. _Component Name_ @@ -137,7 +137,7 @@ The label will be used in the following places: #### Mapping element (spinner): -The spinner mapping element will support displaying a spinner or spinner + text in a cell. A group row associated with a spinner mapping element will always display the spinner and text. +The spinner mapping element will support displaying a spinner or spinner with text in a cell. A group row associated with a spinner mapping element will always display the spinner and text. _Component Name_ From 3c6a2ef8d22a763a4833646ab2668fec3a6416da Mon Sep 17 00:00:00 2001 From: mollykreis <20542556+mollykreis@users.noreply.github.com> Date: Thu, 4 Apr 2024 09:40:19 -0500 Subject: [PATCH 10/16] Update packages/nimble-components/src/table/specs/table-column-specs/table-column-mapping.md Co-authored-by: m-akinc <7282195+m-akinc@users.noreply.github.com> --- .../src/table/specs/table-column-specs/table-column-mapping.md | 1 - 1 file changed, 1 deletion(-) diff --git a/packages/nimble-components/src/table/specs/table-column-specs/table-column-mapping.md b/packages/nimble-components/src/table/specs/table-column-specs/table-column-mapping.md index 5ad9f7e07f..333695b5b2 100644 --- a/packages/nimble-components/src/table/specs/table-column-specs/table-column-mapping.md +++ b/packages/nimble-components/src/table/specs/table-column-specs/table-column-mapping.md @@ -74,7 +74,6 @@ If multiple mappings in a column have the same key, an error flag will be set on If an invalid `icon` value is passed to `nimble-mapping-icon`, an error flag will be set on the column's validity object. An invalid `icon` value is any element that cannot be resolved or that does not derive from `Icon`. -`nimble-table-column-enum` supports `nimble-mapping-icon`, `nimble-mapping-spinner`, `nimble-mapping-text`, and `nimble-mapping-placeholder` as mapping elements. Unsupported mappings will result in an error flag being set on the column's validity object. Text in a grouping header or in the cell will be ellipsized and gain a tooltip when the full text is too long to display. From a48cf3f6e16c89f7f76af7f0e59455b144eba210 Mon Sep 17 00:00:00 2001 From: mollykreis <20542556+mollykreis@users.noreply.github.com> Date: Thu, 4 Apr 2024 11:05:45 -0500 Subject: [PATCH 11/16] Update table-column-mapping.md --- .../table-column-specs/table-column-mapping.md | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/packages/nimble-components/src/table/specs/table-column-specs/table-column-mapping.md b/packages/nimble-components/src/table/specs/table-column-specs/table-column-mapping.md index 333695b5b2..2c760426e7 100644 --- a/packages/nimble-components/src/table/specs/table-column-specs/table-column-mapping.md +++ b/packages/nimble-components/src/table/specs/table-column-specs/table-column-mapping.md @@ -2,7 +2,7 @@ ## Overview -The `nimble-table-column-enum` is a component that supports rendering specific number, boolean, or string values as an icon, a spinner, text, or an icon/spinner with text. The mappings are defined by child elements of `nimble-mapping-icon`, `nimble-mapping-spinner`, `nimble-mapping-text`, or `nimble-mapping-placeholder`. +The `nimble-table-column-enum` is a component that supports rendering specific number, boolean, or string values as an icon, a spinner, text, or an icon/spinner with text. The mappings are defined by child elements of `nimble-mapping-icon`, `nimble-mapping-spinner`, `nimble-mapping-text`, or `nimble-mapping-blank`. ### Background @@ -57,7 +57,7 @@ Below is an example of how these elements would be used within a `nimble-table`: Archived - + ``` @@ -74,7 +74,6 @@ If multiple mappings in a column have the same key, an error flag will be set on If an invalid `icon` value is passed to `nimble-mapping-icon`, an error flag will be set on the column's validity object. An invalid `icon` value is any element that cannot be resolved or that does not derive from `Icon`. - Text in a grouping header or in the cell will be ellipsized and gain a tooltip when the full text is too long to display. **Alternatives:** @@ -110,7 +109,7 @@ _Props/Attrs_ _Content_ - column title (icon and/or text) -- 1 or more `nimble-mapping-icon`, `nimble-mapping-spinner`, `nimble-mapping-text`, or `nimble-mapping-placeholder` elements +- 1 or more `nimble-mapping-icon`, `nimble-mapping-spinner`, `nimble-mapping-text`, or `nimble-mapping-blank` elements #### Mapping element (icon): @@ -167,13 +166,13 @@ _Props/Attrs_ - `key`: string | number | boolean | undefined - `label`: string - display text -#### Mapping element (placeholder): +#### Mapping element (blank): -The placeholder mapping element will display an empty cell. A group row associated with a placeholder mapping will display the mapping's text. The purpose of the placeholder mapping element is to allow clients to avoid cluttering their table with information that isn't particularly helpful to a user (e.g. that the state of a system is 'idle') while still having a good grouping experience that ensures group rows are not blank. +The blank mapping element will display an empty cell. A group row associated with a blank mapping will display the mapping's text. The purpose of the blank mapping element is to allow clients to avoid cluttering their table with information that isn't particularly helpful to a user (e.g. that the state of a system is 'idle') while still having a good grouping experience that ensures group rows are not blank. _Component Name_ -- `nimble-mapping-placeholder` +- `nimble-mapping-blank` _Props/Attrs_ From b23a425c4843e1e8dd3b6964d4fb73921bf4bcb9 Mon Sep 17 00:00:00 2001 From: mollykreis <20542556+mollykreis@users.noreply.github.com> Date: Tue, 9 Apr 2024 16:06:48 -0500 Subject: [PATCH 12/16] Update table-column-mapping.md --- .../table-column-specs/table-column-mapping.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/packages/nimble-components/src/table/specs/table-column-specs/table-column-mapping.md b/packages/nimble-components/src/table/specs/table-column-specs/table-column-mapping.md index 2c760426e7..aad7fd2a57 100644 --- a/packages/nimble-components/src/table/specs/table-column-specs/table-column-mapping.md +++ b/packages/nimble-components/src/table/specs/table-column-specs/table-column-mapping.md @@ -2,7 +2,7 @@ ## Overview -The `nimble-table-column-enum` is a component that supports rendering specific number, boolean, or string values as an icon, a spinner, text, or an icon/spinner with text. The mappings are defined by child elements of `nimble-mapping-icon`, `nimble-mapping-spinner`, `nimble-mapping-text`, or `nimble-mapping-blank`. +The `nimble-table-column-enum` is a component that supports rendering specific number, boolean, or string values as an icon, a spinner, text, or an icon/spinner with text. The mappings are defined by child elements of `nimble-mapping-icon`, `nimble-mapping-spinner`, `nimble-mapping-text`, or `nimble-mapping-empty`. ### Background @@ -57,7 +57,7 @@ Below is an example of how these elements would be used within a `nimble-table`: Archived - + ``` @@ -104,12 +104,12 @@ _Props/Attrs_ - `field-name`: string - `key-type`: 'string' | 'number' | 'boolean' -- `fixed-to-icon-width`: boolean - When set, the column will have a fixed width that makes the column the appropriate width to render only a single icon in the cell. This should only be set when the header contains a single icon (no text) and none of the child mapping elements will result in text being rendered in a cell. +- `fixed-width-mode`: enum - `flexibleWidth` (default) | `iconWidth` - When set to `iconWidth`, the column will have a fixed width that makes the column the appropriate width to render only a single icon in the cell. This should only be set when the header contains a single icon (no text) and none of the child mapping elements will result in text being rendered in a cell. _Content_ - column title (icon and/or text) -- 1 or more `nimble-mapping-icon`, `nimble-mapping-spinner`, `nimble-mapping-text`, or `nimble-mapping-blank` elements +- 1 or more `nimble-mapping-icon`, `nimble-mapping-spinner`, `nimble-mapping-text`, or `nimble-mapping-empty` elements #### Mapping element (icon): @@ -166,13 +166,13 @@ _Props/Attrs_ - `key`: string | number | boolean | undefined - `label`: string - display text -#### Mapping element (blank): +#### Mapping element (empty): -The blank mapping element will display an empty cell. A group row associated with a blank mapping will display the mapping's text. The purpose of the blank mapping element is to allow clients to avoid cluttering their table with information that isn't particularly helpful to a user (e.g. that the state of a system is 'idle') while still having a good grouping experience that ensures group rows are not blank. +The empty mapping element will display an empty cell. A group row associated with an empty mapping will display the mapping's text. The purpose of the empty mapping element is to allow clients to avoid cluttering their table with information that isn't particularly helpful to a user (e.g. that the state of a system is 'idle') while still having a good grouping experience that ensures group rows are not empty. _Component Name_ -- `nimble-mapping-blank` +- `nimble-mapping-empty` _Props/Attrs_ @@ -240,7 +240,7 @@ For icons, if multiple values map to the same icon, it is possible that sorting ### Sizing -By default, the `nimble-table-column-enum` will be a fractional width column with a fractional width of 1. However, it can be configured to be a fixed pixel size (32px) and not be resizable by setting `fixed-to-icon-width` on the column. The 32px fixed size allows room from a single icon or spinner along with left and right cell padding of 8px each. +By default, the `nimble-table-column-enum` will be a fractional width column with a fractional width of 1. However, it can be configured to be a fixed pixel size (32px) and not be resizable by setting `fixed-width-mode` to `iconWidth`. The 32px fixed size allows room from a single icon or spinner along with left and right cell padding of 8px each. When the column is a fixed 32px: From ac0ad0fc3d4ca0e79f042343e2f0c748f8e3ff3c Mon Sep 17 00:00:00 2001 From: mollykreis <20542556+mollykreis@users.noreply.github.com> Date: Tue, 9 Apr 2024 16:22:54 -0500 Subject: [PATCH 13/16] format --- .../src/table/specs/table-column-specs/table-column-mapping.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/nimble-components/src/table/specs/table-column-specs/table-column-mapping.md b/packages/nimble-components/src/table/specs/table-column-specs/table-column-mapping.md index aad7fd2a57..d7898492e1 100644 --- a/packages/nimble-components/src/table/specs/table-column-specs/table-column-mapping.md +++ b/packages/nimble-components/src/table/specs/table-column-specs/table-column-mapping.md @@ -104,7 +104,7 @@ _Props/Attrs_ - `field-name`: string - `key-type`: 'string' | 'number' | 'boolean' -- `fixed-width-mode`: enum - `flexibleWidth` (default) | `iconWidth` - When set to `iconWidth`, the column will have a fixed width that makes the column the appropriate width to render only a single icon in the cell. This should only be set when the header contains a single icon (no text) and none of the child mapping elements will result in text being rendered in a cell. +- `fixed-width-mode`: enum - `flexibleWidth` (default) | `iconWidth` - When set to `iconWidth`, the column will have a fixed width that makes the column the appropriate width to render only a single icon in the cell. This should only be set when the header contains a single icon (no text) and none of the child mapping elements will result in text being rendered in a cell. _Content_ From d04ca0018870c71244137f36fe534621c01bd69f Mon Sep 17 00:00:00 2001 From: mollykreis <20542556+mollykreis@users.noreply.github.com> Date: Wed, 10 Apr 2024 14:52:54 -0500 Subject: [PATCH 14/16] update width configuration naming --- .../table/specs/table-column-specs/table-column-mapping.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/nimble-components/src/table/specs/table-column-specs/table-column-mapping.md b/packages/nimble-components/src/table/specs/table-column-specs/table-column-mapping.md index d7898492e1..9a1c457424 100644 --- a/packages/nimble-components/src/table/specs/table-column-specs/table-column-mapping.md +++ b/packages/nimble-components/src/table/specs/table-column-specs/table-column-mapping.md @@ -104,7 +104,7 @@ _Props/Attrs_ - `field-name`: string - `key-type`: 'string' | 'number' | 'boolean' -- `fixed-width-mode`: enum - `flexibleWidth` (default) | `iconWidth` - When set to `iconWidth`, the column will have a fixed width that makes the column the appropriate width to render only a single icon in the cell. This should only be set when the header contains a single icon (no text) and none of the child mapping elements will result in text being rendered in a cell. +- `width-mode`: enum - `flexibleWidth` (default) | `fixedIconWidth` - When set to `fixedIconWidth`, the column will have a fixed width that makes the column the appropriate width to render only a single icon in the cell. This should only be set when the header contains a single icon (no text) and none of the child mapping elements will result in text being rendered in a cell. _Content_ @@ -240,7 +240,7 @@ For icons, if multiple values map to the same icon, it is possible that sorting ### Sizing -By default, the `nimble-table-column-enum` will be a fractional width column with a fractional width of 1. However, it can be configured to be a fixed pixel size (32px) and not be resizable by setting `fixed-width-mode` to `iconWidth`. The 32px fixed size allows room from a single icon or spinner along with left and right cell padding of 8px each. +By default, the `nimble-table-column-enum` will be a fractional width column with a fractional width of 1. However, it can be configured to be a fixed pixel size (32px) and not be resizable by setting `width-mode` to `fixedIconWidth`. The 32px fixed size allows room from a single icon or spinner along with left and right cell padding of 8px each. When the column is a fixed 32px: From abab8ab6744ab2bc25b74026552295dd088bc331 Mon Sep 17 00:00:00 2001 From: mollykreis <20542556+mollykreis@users.noreply.github.com> Date: Wed, 10 Apr 2024 15:12:55 -0500 Subject: [PATCH 15/16] its called 'text' not 'label' --- .../table-column-mapping.md | 74 +++++++++---------- 1 file changed, 37 insertions(+), 37 deletions(-) diff --git a/packages/nimble-components/src/table/specs/table-column-specs/table-column-mapping.md b/packages/nimble-components/src/table/specs/table-column-specs/table-column-mapping.md index 9a1c457424..281eac5c39 100644 --- a/packages/nimble-components/src/table/specs/table-column-specs/table-column-mapping.md +++ b/packages/nimble-components/src/table/specs/table-column-specs/table-column-mapping.md @@ -30,7 +30,7 @@ The `nimble-table-column-enum` is a component that supports rendering specific n - Arbitrary icon colors - Hyperlink icons - Non-icon, non-spinner Nimble components -- Specifying different text for an icon/spinner's label than the overall label of the mapping +- Specifying different text for an icon/spinner's label than the overall text of the mapping - Detecting that only icons/spinners can be rendered in the cells and column header and automatically making the column non-resizable and 32px --- @@ -43,21 +43,21 @@ Below is an example of how these elements would be used within a `nimble-table`: Status - - - - + + + + Error Code - - - + + + Archived - - + + ``` @@ -124,14 +124,14 @@ _Props/Attrs_ - `key`: string | number | boolean | undefined - `icon`: string | undefined - name of the Nimble icon element. If `undefined`, no icon will be associated with the given `key`, but space will be reserved in the cell for an icon. - `severity`: string - one of the supported enum values. Controls color of the icon. -- `label`: string - localized value associated with the given `key`. -- `label-hidden`: boolean - When set, the label will not be rendered within a cell. When unset, the label will be rendered with a cell. This does not affect the rendering of group rows; group rows will always display the label associated with the mapping. +- `text`: string - localized value associated with the given `key`. +- `text-hidden`: boolean - When set, the mapping's text will not be rendered within a cell. When unset, the text will be rendered in a cell. This does not affect the rendering of group rows; group rows will always display the text associated with the mapping. -The label will be used in the following places: +The text will be used in the following places: - In the group row for a mapping -- If `label-hidden` is set, as the accessible name and `title` of the icon within a cell -- If `label-hidden` is not set, as text rendered next to the icon within a cell +- If `text-hidden` is set, as the accessible name and `title` of the icon within a cell +- If `text-hidden` is not set, as text rendered next to the icon within a cell #### Mapping element (spinner): @@ -144,14 +144,14 @@ _Component Name_ _Props/Attrs_ - `key`: string | number | boolean | undefined -- `label`: string - localized value associated with the given `key`. -- `label-hidden`: boolean - When set, the label will not be rendered within a cell. When unset, the label will be rendered with a cell. This does not affect the rendering of group rows; group rows will always display the label associated with the mapping. +- `text`: string - localized value associated with the given `key`. +- `text-hidden`: boolean - When set, the mapping's text will not be rendered within a cell. When unset, the text will be rendered in a cell. This does not affect the rendering of group rows; group rows will always display the text associated with the mapping. -The label will be used in the following places: +The text will be used in the following places: - In the group row for a mapping -- If `label-hidden` is set, as the accessible name and `title` of the spinner within a cell -- If `label-hidden` is not set, as text rendered next to the spinner within a cell +- If `text-hidden` is set, as the accessible name and `title` of the spinner within a cell +- If `text-hidden` is not set, as text rendered next to the spinner within a cell #### Mapping element (text): @@ -164,7 +164,7 @@ _Component Name_ _Props/Attrs_ - `key`: string | number | boolean | undefined -- `label`: string - display text +- `text`: string - display text #### Mapping element (empty): @@ -177,7 +177,7 @@ _Component Name_ _Props/Attrs_ - `key`: string | number | boolean | undefined -- `label`: string - display text +- `text`: string - display text #### `nimble-mapping-*` @@ -191,14 +191,14 @@ _Props/Attrs_ ```HTML <${this.icon} - title="${x => x.labelHidden ? x.label: null}" + title="${x => x.textHidden ? x.text: null}" role="img" - aria-label="${x => x.labelHidden ? x.label: null}" - aria-hidden="${x => x.labelHidden ? 'false' : 'true'}" + aria-label="${x => x.textHidden ? x.text: null}" + aria-hidden="${x => x.textHidden ? 'false' : 'true'}" severity="${x => x.severity}"> -${when(() => !x.labelHidden, html` - ${x => x.label} +${when(() => !x.textHidden, html` + ${x => x.text} `)} ``` @@ -210,13 +210,13 @@ ${when(() => !x.labelHidden, html` severity="${x => x.severity}"> - ${x => x.label} + ${x => x.text} `; ``` ### Grouping -Grouping will be based on the record value. The grouping header will display the rendered label along with the icon/spinner, if configured. +Grouping will be based on the record value. The grouping header will display the rendered text along with the icon/spinner, if configured. For values that do not match any mapping, the group row will display only the count. This is considered invalid data from the table's perspective and should be fixed within the client application. @@ -227,9 +227,9 @@ Text in a grouping header will be ellipsized and gain a tooltip if there is not Sorting will be based on the record value. For boolean and number values, a basic sort (just using basic comparison/equality operators) is the clear choice. For string values, it is less clear. In the case where the strings are enum values, they are likely to be non-localized, English strings. Using a basic (alphabetical) sort is not unreasonable. However, if there is a semantically meaningful sort order (e.g. "NOT_STARTED" < "RUNNING" < "DONE"), it would be nice to sort by that. We can only infer that semantic order from the order in which the mappings are given, e.g.: ```HTML - - - + + + ``` We would need new support for sorting this way. We could define a new sorting option, "enumerated sort", where the column provides an ordered list of values, and the table sorts the column based on that given order. To compare the relative order of two values, we have to search the list, making the sort operation a bit more expensive, but still probably reasonable except in the case of enums with many values. @@ -264,8 +264,8 @@ Blazor wrappers will be created for the components. Columns will be generic in t ```HTML - - + + ``` @@ -284,8 +284,8 @@ N/A ### Accessibility - Text, icons, and spinner are not interactive and cannot receive keyboard focus. -- In group rows, the rendered icon/spinner will have `aria-hidden="true"` set because the label is displayed directly next to the icon. The icon/spinner is purely decorative, and it does not contain any additional information that needs to be available with a screen reader. -- In table cells, if an icon/spinner is displayed with the label, the icon/spinner will have `aria-hidden="true"` set for the same reason explained for group rows above. However, if the label is not displayed, the icon/spinner will have a role of `img` and use the label as its `title` and `aria-label`. +- In group rows, the rendered icon/spinner will have `aria-hidden="true"` set because the text is displayed directly next to the icon. The icon/spinner is purely decorative, and it does not contain any additional information that needs to be available with a screen reader. +- In table cells, if an icon/spinner is displayed with the text, the icon/spinner will have `aria-hidden="true"` set for the same reason explained for group rows above. However, if the text is not displayed, the icon/spinner will have a role of `img` and use the text as its `title` and `aria-label`. ### Globalization @@ -310,7 +310,7 @@ None - nothing rendered when value matches no mappings - validation error when non-unique mapping keys exist - validation error when invalid icon name given - - grouping header for icon column includes label + - grouping header for icon column includes text - Verify manually that the column content appears in the accessibility tree and can be read by a screen reader. - Verify manually that several mapping columns with thousands of elements scrolls performantly. - Visual Chromatic tests will be created From cfd19cf3190ab76ba4f1d362e74e9451957f822b Mon Sep 17 00:00:00 2001 From: mollykreis <20542556+mollykreis@users.noreply.github.com> Date: Thu, 11 Apr 2024 10:06:54 -0500 Subject: [PATCH 16/16] a few more updates --- .../table-column-mapping.md | 26 ++++++++++--------- 1 file changed, 14 insertions(+), 12 deletions(-) diff --git a/packages/nimble-components/src/table/specs/table-column-specs/table-column-mapping.md b/packages/nimble-components/src/table/specs/table-column-specs/table-column-mapping.md index 281eac5c39..0a154c616c 100644 --- a/packages/nimble-components/src/table/specs/table-column-specs/table-column-mapping.md +++ b/packages/nimble-components/src/table/specs/table-column-specs/table-column-mapping.md @@ -2,7 +2,7 @@ ## Overview -The `nimble-table-column-enum` is a component that supports rendering specific number, boolean, or string values as an icon, a spinner, text, or an icon/spinner with text. The mappings are defined by child elements of `nimble-mapping-icon`, `nimble-mapping-spinner`, `nimble-mapping-text`, or `nimble-mapping-empty`. +The `nimble-table-column-mapping` is a component that supports rendering specific number, boolean, or string values as an icon, a spinner, text, or an icon/spinner with text. The mappings are defined by child elements of `nimble-mapping-icon`, `nimble-mapping-spinner`, `nimble-mapping-text`, or `nimble-mapping-empty`. ### Background @@ -41,24 +41,24 @@ Below is an example of how these elements would be used within a `nimble-table`: ```HTML - + Status - - + + Error Code - - + + Archived - + ``` @@ -98,13 +98,15 @@ Cons: _Component Name_ -- `nimble-table-column-enum` +- `nimble-table-column-mapping` _Props/Attrs_ - `field-name`: string - `key-type`: 'string' | 'number' | 'boolean' -- `width-mode`: enum - `flexibleWidth` (default) | `fixedIconWidth` - When set to `fixedIconWidth`, the column will have a fixed width that makes the column the appropriate width to render only a single icon in the cell. This should only be set when the header contains a single icon (no text) and none of the child mapping elements will result in text being rendered in a cell. +- `width-mode`: enum - `default` (`undefined`) | `iconSize` (`'icon-size'`) - When set to `iconSize`, the column will have a fixed width that makes the column the appropriate width to render only a single icon in the cell. This should only be set when the header contains a single icon (no text) and none of the child mapping elements will result in text being rendered in a cell. When unset or set to `default`, the column will be resizable and be sized based on its `fractional-width` and `min-pixel-width` values. +- `fractional-width`: number (defaults to 1) +- `min-pixel-width`: number (defaults to minimum supported by table) _Content_ @@ -240,7 +242,7 @@ For icons, if multiple values map to the same icon, it is possible that sorting ### Sizing -By default, the `nimble-table-column-enum` will be a fractional width column with a fractional width of 1. However, it can be configured to be a fixed pixel size (32px) and not be resizable by setting `width-mode` to `fixedIconWidth`. The 32px fixed size allows room from a single icon or spinner along with left and right cell padding of 8px each. +By default, the `nimble-table-column-mapping` will be a fractional width column with a fractional width of 1. However, it can be configured to be a fixed pixel size (32px) and not be resizable by setting `width-mode` to `iconSize`. The 32px fixed size allows room from a single icon or spinner along with left and right cell padding of 8px each. When the column is a fixed 32px: @@ -263,10 +265,10 @@ Angular directives will be created for the column components and the mapping com Blazor wrappers will be created for the components. Columns will be generic in the type of the key, and will cascade that type parameter to contained mapping elements (see [`CascadingTypeParameter`](https://learn.microsoft.com/en-us/aspnet/core/blazor/components/generic-type-support?view=aspnetcore-7.0#cascaded-generic-type-support)): ```HTML - + - + ``` ### Visual Appearance