From 2a1ecff3368e382cb42c0f019469b67267e05f14 Mon Sep 17 00:00:00 2001 From: Valerie Gleason <5265744+hellovolcano@users.noreply.github.com> Date: Thu, 8 Jan 2026 13:10:31 -0600 Subject: [PATCH 1/7] HLD draft for non-nimble icons in the table --- ...e-table-column-mapping-custom-icons-hld.md | 59 +++++++++++++++++++ 1 file changed, 59 insertions(+) create mode 100644 specs/nimble-table-column-mapping-custom-icons-hld.md diff --git a/specs/nimble-table-column-mapping-custom-icons-hld.md b/specs/nimble-table-column-mapping-custom-icons-hld.md new file mode 100644 index 0000000000..e4a6482f94 --- /dev/null +++ b/specs/nimble-table-column-mapping-custom-icons-hld.md @@ -0,0 +1,59 @@ +# Custom Icon Support for Table Column Mapping HLD + +## Problem Statement + +Currently, the `nimble-table-column-mapping` component only supports Nimble icons through the `nimble-mapping-icon` element. Users need to add custom SVG and PNG icons in some applications that are leveraging the nimble table. + +This design proposes adding two new mapping elements (`nimble-mapping-svg-icon` and `nimble-mapping-png-icon`) to enable custom icon support. + +## Links To Relevant Work Items and Reference Material + +- [Original table column mapping specification](../nimble-components/src/table/specs/table-column-specs/table-column-mapping.md) +- [Icon column type issue #1013](https://github.com/ni/nimble/issues/1013) +- Original specification explicitly listed "Non-Nimble icon support" as a non-goal + +## Implementation / Design + +### New Mapping Elements + +Create two new mapping elements following the existing pattern: + +#### `nimble-mapping-svg-icon` +- **Attributes:** + - `key`: string | number | boolean (same as existing mappings) + - `svg-content`: string - Raw SVG markup to render + - `severity`: IconSeverity - Controls color theming + - `text`: string - Tooltip and accessibility text + - `text-hidden`: boolean - Controls text visibility + +#### `nimble-mapping-png-icon` +- **Attributes:** + - `key`: string | number | boolean (same as existing mappings) + - `src`: string - URL or data URL to PNG/image + - `alt`: string - Alt text for accessibility + - `text`: string - Tooltip and display text + - `text-hidden`: boolean - Controls text visibility + +### Supporting Infrastructure + +- Add **`MappingSvgIconConfig`** and **`MappingPngIconConfig`** following existing `MappingIconConfig` pattern +- Custom ViewTemplates for rendering SVG content and images with proper styling and accessibility +- CSS classes to match nimble design tokens and severity theming +- Extend existing `TableColumnMappingCellView` and `TableColumnMappingGroupHeaderView` to handle new mapping types + +### Framework Integration + +Update Angular, React, and Blazor integrations to support the new mapping elements using existing patterns. + +## Alternative Implementations / Designs + +### Alternative 1: Extend Existing `nimble-mapping-icon` +Add `svg-content`, `image-src`, and `image-alt` attributes to the existing `nimble-mapping-icon` element. + +**Rejected because:** +Creates a confusing list of attributes, and a less-than-ideal developer experience. + + +## Open Issues + +- Do we need to add any security checks/validation for SVG content or PNG links? From 4d03e449f76c6da803819789caaae37f122a6599 Mon Sep 17 00:00:00 2001 From: Valerie Gleason <5265744+hellovolcano@users.noreply.github.com> Date: Thu, 8 Jan 2026 13:12:40 -0600 Subject: [PATCH 2/7] change spec location --- .../icon/specs}/nimble-table-column-mapping-custom-icons-hld.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename {specs => packages/nimble-components/src/mapping/icon/specs}/nimble-table-column-mapping-custom-icons-hld.md (100%) diff --git a/specs/nimble-table-column-mapping-custom-icons-hld.md b/packages/nimble-components/src/mapping/icon/specs/nimble-table-column-mapping-custom-icons-hld.md similarity index 100% rename from specs/nimble-table-column-mapping-custom-icons-hld.md rename to packages/nimble-components/src/mapping/icon/specs/nimble-table-column-mapping-custom-icons-hld.md From 59a10b10b28c5ad11d110b6639704c683a9673af Mon Sep 17 00:00:00 2001 From: Valerie Gleason <5265744+hellovolcano@users.noreply.github.com> Date: Thu, 8 Jan 2026 14:36:30 -0600 Subject: [PATCH 3/7] cleanup --- .../specs/nimble-table-column-mapping-custom-icons-hld.md | 6 ------ 1 file changed, 6 deletions(-) diff --git a/packages/nimble-components/src/mapping/icon/specs/nimble-table-column-mapping-custom-icons-hld.md b/packages/nimble-components/src/mapping/icon/specs/nimble-table-column-mapping-custom-icons-hld.md index e4a6482f94..30cb96b4d1 100644 --- a/packages/nimble-components/src/mapping/icon/specs/nimble-table-column-mapping-custom-icons-hld.md +++ b/packages/nimble-components/src/mapping/icon/specs/nimble-table-column-mapping-custom-icons-hld.md @@ -6,12 +6,6 @@ Currently, the `nimble-table-column-mapping` component only supports Nimble icon This design proposes adding two new mapping elements (`nimble-mapping-svg-icon` and `nimble-mapping-png-icon`) to enable custom icon support. -## Links To Relevant Work Items and Reference Material - -- [Original table column mapping specification](../nimble-components/src/table/specs/table-column-specs/table-column-mapping.md) -- [Icon column type issue #1013](https://github.com/ni/nimble/issues/1013) -- Original specification explicitly listed "Non-Nimble icon support" as a non-goal - ## Implementation / Design ### New Mapping Elements From 6fcc0c0c570ffd64cd09c9aa80c65707dd30c0f0 Mon Sep 17 00:00:00 2001 From: Valerie Gleason <5265744+hellovolcano@users.noreply.github.com> Date: Thu, 8 Jan 2026 17:08:10 -0600 Subject: [PATCH 4/7] Change files --- ...le-components-e24ccafe-f3e9-4a34-bd19-7696fb0d00d1.json | 7 +++++++ 1 file changed, 7 insertions(+) create mode 100644 change/@ni-nimble-components-e24ccafe-f3e9-4a34-bd19-7696fb0d00d1.json diff --git a/change/@ni-nimble-components-e24ccafe-f3e9-4a34-bd19-7696fb0d00d1.json b/change/@ni-nimble-components-e24ccafe-f3e9-4a34-bd19-7696fb0d00d1.json new file mode 100644 index 0000000000..7142bdd521 --- /dev/null +++ b/change/@ni-nimble-components-e24ccafe-f3e9-4a34-bd19-7696fb0d00d1.json @@ -0,0 +1,7 @@ +{ + "type": "none", + "comment": "HLD draft for non-nimble icons in the table", + "packageName": "@ni/nimble-components", + "email": "5265744+hellovolcano@users.noreply.github.com", + "dependentChangeType": "none" +} From 380ba3033aa34f4c17c78e62188bc5194831e47f Mon Sep 17 00:00:00 2001 From: Valerie Gleason <5265744+hellovolcano@users.noreply.github.com> Date: Fri, 9 Jan 2026 15:23:02 -0600 Subject: [PATCH 5/7] move to ok, apply new template --- ...e-table-column-mapping-custom-icons-hld.md | 53 -------- .../table-column-mapping-custom-icons-hld.md | 126 ++++++++++++++++++ 2 files changed, 126 insertions(+), 53 deletions(-) delete mode 100644 packages/nimble-components/src/mapping/icon/specs/nimble-table-column-mapping-custom-icons-hld.md create mode 100644 packages/ok-components/src/mapping/custom-image/specs/table-column-mapping-custom-icons-hld.md diff --git a/packages/nimble-components/src/mapping/icon/specs/nimble-table-column-mapping-custom-icons-hld.md b/packages/nimble-components/src/mapping/icon/specs/nimble-table-column-mapping-custom-icons-hld.md deleted file mode 100644 index 30cb96b4d1..0000000000 --- a/packages/nimble-components/src/mapping/icon/specs/nimble-table-column-mapping-custom-icons-hld.md +++ /dev/null @@ -1,53 +0,0 @@ -# Custom Icon Support for Table Column Mapping HLD - -## Problem Statement - -Currently, the `nimble-table-column-mapping` component only supports Nimble icons through the `nimble-mapping-icon` element. Users need to add custom SVG and PNG icons in some applications that are leveraging the nimble table. - -This design proposes adding two new mapping elements (`nimble-mapping-svg-icon` and `nimble-mapping-png-icon`) to enable custom icon support. - -## Implementation / Design - -### New Mapping Elements - -Create two new mapping elements following the existing pattern: - -#### `nimble-mapping-svg-icon` -- **Attributes:** - - `key`: string | number | boolean (same as existing mappings) - - `svg-content`: string - Raw SVG markup to render - - `severity`: IconSeverity - Controls color theming - - `text`: string - Tooltip and accessibility text - - `text-hidden`: boolean - Controls text visibility - -#### `nimble-mapping-png-icon` -- **Attributes:** - - `key`: string | number | boolean (same as existing mappings) - - `src`: string - URL or data URL to PNG/image - - `alt`: string - Alt text for accessibility - - `text`: string - Tooltip and display text - - `text-hidden`: boolean - Controls text visibility - -### Supporting Infrastructure - -- Add **`MappingSvgIconConfig`** and **`MappingPngIconConfig`** following existing `MappingIconConfig` pattern -- Custom ViewTemplates for rendering SVG content and images with proper styling and accessibility -- CSS classes to match nimble design tokens and severity theming -- Extend existing `TableColumnMappingCellView` and `TableColumnMappingGroupHeaderView` to handle new mapping types - -### Framework Integration - -Update Angular, React, and Blazor integrations to support the new mapping elements using existing patterns. - -## Alternative Implementations / Designs - -### Alternative 1: Extend Existing `nimble-mapping-icon` -Add `svg-content`, `image-src`, and `image-alt` attributes to the existing `nimble-mapping-icon` element. - -**Rejected because:** -Creates a confusing list of attributes, and a less-than-ideal developer experience. - - -## Open Issues - -- Do we need to add any security checks/validation for SVG content or PNG links? diff --git a/packages/ok-components/src/mapping/custom-image/specs/table-column-mapping-custom-icons-hld.md b/packages/ok-components/src/mapping/custom-image/specs/table-column-mapping-custom-icons-hld.md new file mode 100644 index 0000000000..064d318a95 --- /dev/null +++ b/packages/ok-components/src/mapping/custom-image/specs/table-column-mapping-custom-icons-hld.md @@ -0,0 +1,126 @@ +# Custom Image Mapping [Template] + +## Overview + +Custom image support for table column mapping, enabling the use of user-provided images in addition to Nimble's built-in icon set. + +### Background + +- Currently, the `nimble-table-column-mapping` component only supports Nimble icons through the `nimble-mapping-icon` element +- Users need to add custom images in some applications that are leveraging the nimble table + +### Containing Library + +This component will be part of Ok component library. + +### Non-goals + +- Image validation + +### Features + +- Support for locally hosted images +- Integration with existing table column mapping + +### Risks and Challenges + +- If cross origin images are required, there will be additional security challenges to address. + +### Prior Art/Examples + +- Existing `nimble-mapping-icon` component for Nimble icons +- Standard HTML `` element patterns + +--- + +## Design + +### API + +**Component Name:** `ok-mapping-custom-image` + +**Props/Attrs:** +- `key`: string | number | boolean - Mapping key value +- `src`: string - URL for custom image +- `severity`: IconSeverity - Controls color theming (default, error, warning, success, information) +- `text`: string - Tooltip and display text +- `text-hidden`: boolean - Controls text visibility + +**Supporting Infrastructure** + +- Add **`MappingCustomImageConfig`** following existing `MappingIconConfig` pattern +- Custom ViewTemplates for rendering images with proper styling and accessibility +- Extend existing `TableColumnMappingCellView` and `TableColumnMappingGroupHeaderView` to handle new mapping type + +### Anatomy + + +### Native form integration + +N/A - This component is for display purposes within table cells. + +### Angular integration + +- Directive for attribute binding following existing mapping patterns +- Integration with existing table column mapping directives + +### Blazor integration (TBD if necessary) + +- Razor component following existing mapping patterns +- Integration with existing table column mapping components + +### Visual Appearance + +- Custom images will have a class applied that ensures proper sizing, spacing, and alignment within table cells + +--- + +## Implementation + +### States + +- Default state with custom image display +- Error states for missing or invalid image sources + +### Accessibility + +- Tooltip support for additional context +- Role and labeling support + +### Mobile + +- Mirror behavior for existing table column icon mapping. + +### Globalization + +- No additional considerations. + +### Security + +- Images will be hosted locally. No image validation is provided by this component. + +### Performance + +- Images will not be pre-fetched for the initial implementation. + +### Dependencies + +- No additional dependencies required. + +### Test Plan + +- Unit tests for basic functionality and attribute binding +- Integration tests with table column mapping + +### Tooling + +- Integration with existing Storybook documentation + +### Documentation + +- Usage examples in Storybook + +--- +## Open Issues + +- From 6c546be34305dd68eb254d09afa9aeeb871fda51 Mon Sep 17 00:00:00 2001 From: Valerie Gleason <5265744+hellovolcano@users.noreply.github.com> Date: Fri, 9 Jan 2026 15:23:23 -0600 Subject: [PATCH 6/7] Change files --- ...ok-components-fcf4988c-1c17-46a4-a0c0-381fc8974f5a.json | 7 +++++++ 1 file changed, 7 insertions(+) create mode 100644 change/@ni-ok-components-fcf4988c-1c17-46a4-a0c0-381fc8974f5a.json diff --git a/change/@ni-ok-components-fcf4988c-1c17-46a4-a0c0-381fc8974f5a.json b/change/@ni-ok-components-fcf4988c-1c17-46a4-a0c0-381fc8974f5a.json new file mode 100644 index 0000000000..daca221adc --- /dev/null +++ b/change/@ni-ok-components-fcf4988c-1c17-46a4-a0c0-381fc8974f5a.json @@ -0,0 +1,7 @@ +{ + "type": "none", + "comment": "HLD draft for non-nimble icons in the table", + "packageName": "@ni/ok-components", + "email": "5265744+hellovolcano@users.noreply.github.com", + "dependentChangeType": "none" +} From 84ed3b3e4a6807a2a05c167c41a74f0a5d494cb6 Mon Sep 17 00:00:00 2001 From: Valerie Gleason <5265744+hellovolcano@users.noreply.github.com> Date: Thu, 22 Jan 2026 14:24:02 -0600 Subject: [PATCH 7/7] change approach to separate Icon base class --- .../table-column-mapping-custom-icons-hld.md | 126 ------------------ .../dynamic-icon/specs/custom-icons-hld.md | 62 +++++++++ 2 files changed, 62 insertions(+), 126 deletions(-) delete mode 100644 packages/ok-components/src/mapping/custom-image/specs/table-column-mapping-custom-icons-hld.md create mode 100644 packages/ok-components/src/mapping/dynamic-icon/specs/custom-icons-hld.md diff --git a/packages/ok-components/src/mapping/custom-image/specs/table-column-mapping-custom-icons-hld.md b/packages/ok-components/src/mapping/custom-image/specs/table-column-mapping-custom-icons-hld.md deleted file mode 100644 index 064d318a95..0000000000 --- a/packages/ok-components/src/mapping/custom-image/specs/table-column-mapping-custom-icons-hld.md +++ /dev/null @@ -1,126 +0,0 @@ -# Custom Image Mapping [Template] - -## Overview - -Custom image support for table column mapping, enabling the use of user-provided images in addition to Nimble's built-in icon set. - -### Background - -- Currently, the `nimble-table-column-mapping` component only supports Nimble icons through the `nimble-mapping-icon` element -- Users need to add custom images in some applications that are leveraging the nimble table - -### Containing Library - -This component will be part of Ok component library. - -### Non-goals - -- Image validation - -### Features - -- Support for locally hosted images -- Integration with existing table column mapping - -### Risks and Challenges - -- If cross origin images are required, there will be additional security challenges to address. - -### Prior Art/Examples - -- Existing `nimble-mapping-icon` component for Nimble icons -- Standard HTML `` element patterns - ---- - -## Design - -### API - -**Component Name:** `ok-mapping-custom-image` - -**Props/Attrs:** -- `key`: string | number | boolean - Mapping key value -- `src`: string - URL for custom image -- `severity`: IconSeverity - Controls color theming (default, error, warning, success, information) -- `text`: string - Tooltip and display text -- `text-hidden`: boolean - Controls text visibility - -**Supporting Infrastructure** - -- Add **`MappingCustomImageConfig`** following existing `MappingIconConfig` pattern -- Custom ViewTemplates for rendering images with proper styling and accessibility -- Extend existing `TableColumnMappingCellView` and `TableColumnMappingGroupHeaderView` to handle new mapping type - -### Anatomy - - -### Native form integration - -N/A - This component is for display purposes within table cells. - -### Angular integration - -- Directive for attribute binding following existing mapping patterns -- Integration with existing table column mapping directives - -### Blazor integration (TBD if necessary) - -- Razor component following existing mapping patterns -- Integration with existing table column mapping components - -### Visual Appearance - -- Custom images will have a class applied that ensures proper sizing, spacing, and alignment within table cells - ---- - -## Implementation - -### States - -- Default state with custom image display -- Error states for missing or invalid image sources - -### Accessibility - -- Tooltip support for additional context -- Role and labeling support - -### Mobile - -- Mirror behavior for existing table column icon mapping. - -### Globalization - -- No additional considerations. - -### Security - -- Images will be hosted locally. No image validation is provided by this component. - -### Performance - -- Images will not be pre-fetched for the initial implementation. - -### Dependencies - -- No additional dependencies required. - -### Test Plan - -- Unit tests for basic functionality and attribute binding -- Integration tests with table column mapping - -### Tooling - -- Integration with existing Storybook documentation - -### Documentation - -- Usage examples in Storybook - ---- -## Open Issues - -- diff --git a/packages/ok-components/src/mapping/dynamic-icon/specs/custom-icons-hld.md b/packages/ok-components/src/mapping/dynamic-icon/specs/custom-icons-hld.md new file mode 100644 index 0000000000..ed8bbc245c --- /dev/null +++ b/packages/ok-components/src/mapping/dynamic-icon/specs/custom-icons-hld.md @@ -0,0 +1,62 @@ +# High Level Design: Support for Custom Icons + +## Problem Statement + +The current nimble icon system has the `Icon` class handling both general icon functionality and SVG-specific functionality. This limits extensibility for other icon types, like PNG. + +This design introduces a separation between base icon functionality and SVG-specific icon implementations and can be extended to support custom icon types. It also introduces a new component in Ok to render icons dynamically. + +## Links To Relevant Work Items and Reference Material + +- [GitHub PR #2814: SVGIcon prototype](https://github.com/ni/nimble/pull/2814) + +## Implementation / Design + +### Class Hierarchy Changes + +``` +Icon (base class with severity, etc.) +├── SvgIcon (extends Icon, handles SVG data) - Class for Nimble Icons +└── DynamicIcon (extends Icon, dynamically register custom icons) +``` + +### API Changes + + - Rename `registerIcon()` to `registerSvgIcon()` + - Update type signature to accept `typeof SvgIcon` instead of generic type + +### New Component: Ok Dynamic Icon +A component that enables dynamic registration and usage of custom icons from URLs (data URLs, external URLs, etc.) following the same patterns as standard nimble icons. + +#### API +- **registerDynamicIcon(name: string, src: string)**: Registers a new dynamic icon +- **getDynamicIconTag(name: string)**: Returns the custom element tag name for a registered icon +- **Generated Custom Elements**: Each registered icon creates its own custom element (e.g., ``) + +#### Usage Example +```javascript +// Registration +registerDynamicIcon('rumham', 'data:image/png;base64,...'); + +// Usage in HTML +const tag = getDynamicIconTag('rumham'); // Returns 'ok-dynamic-icon-rumham' +// +``` + +#### Blazor Integration +Provide a Blazor wrapper component that handles JavaScript interop for icon registration and returns the appropriate custom element tag for use in Blazor applications. + +**Usage in Blazor:** +```html + +``` + +The component automatically registers the icon and renders the corresponding custom element (e.g., ``) using the OkDynamicIcon.register method accessed through OkBlazor.module.js. + +## Alternative Implementations / Designs + +1. **Create a new table column mapping in Ok**: Would require significant duplication of nimble table column components, and introduce a circular dependency. + +## Open Issues + +N/A \ No newline at end of file