From 1542c0913bbdefc1485fedf4d7e16ca07dcb9d99 Mon Sep 17 00:00:00 2001 From: Lukas Maurer Date: Thu, 5 Dec 2024 14:49:02 +0100 Subject: [PATCH 01/13] docs: add icon usage examples --- BREAKING_CHANGES/v3.md | 38 ++++++++++----- packages/angular/src/app-initialize.ts | 6 +-- packages/angular/src/module.ts | 6 +-- .../docs/icon-library/_icon_code.md | 48 ++++++++++++++++--- .../src/components/ThemeShadows/index.tsx | 47 +----------------- 5 files changed, 72 insertions(+), 73 deletions(-) diff --git a/BREAKING_CHANGES/v3.md b/BREAKING_CHANGES/v3.md index e7e18157092..0fe85458c78 100644 --- a/BREAKING_CHANGES/v3.md +++ b/BREAKING_CHANGES/v3.md @@ -45,7 +45,16 @@ export default defineConfig({ ### Usage of icons inside `@siemens/ix-angular` changed -To use imports by name (e.g. ``), you need to add a configuration entry inside of `angular.json`: + +Use the 'addIcon' function to load individual icons once during bootstrapping. +TODO (IX-2072): Add real code example + +```js +addIcon('star') +``` + +Alternatively the whole icon set can be loaded via `angular.json`. +Keep in mind that loading all icons can have a negative impact on the performance of your application and is therefor not recommended. ```json "assets": [ @@ -59,19 +68,21 @@ To use imports by name (e.g. ``), you need to add ], ``` -TODO: Clarification needed if the legacy feature `preloadIcons` should be part of the PR. +```html + +``` + +### Usage of icons in pure HTML -To re-enable the preloaded icons you can provide the `preloadIcons` function as configuration to the module import. +TODO: Add example -```ts -IxModule.forRoot({ - preloadIcons, -}), -``` +```html + ### Custom asset path for icons -To configure the asset path from which domain the `ix-icon` component will load the resource you have two options via `meta`-tag or the `setAssetPath`-function. +In order be able to load custom icons, we need to configure the domain of the asset path. +This can either be done via `meta`-tag or with the `setAssetPath`-function. #### with `meta`-tag @@ -89,11 +100,11 @@ To configure the asset path from which domain the `ix-icon` component will load ``` -Above will fetch the svg from `https://some-resource-domain/star.svg` +Above will fetch the SVG from `https://some-resource-domain/star.svg` #### with `setAssetPath`-function -Make sure to call the `setAssetPath`-function before using the `IxIcon` component, such as in the main file. +Make sure to call the `setAssetPath`-function before using the `IxIcon` component (f.e. in the main file). ```ts import { setAssetPath } from '@siemens/ix-icons/components'; @@ -105,9 +116,10 @@ setAssetPath('https://some-resource-domain'); ``` -Above will fetch the SVG from `https://some-resource-domain/star.svg` +Above code will fetch the SVG from `https://some-resource-domain/star.svg` -This will preload all icons without including the SVGs as assets, which results in a larger bundle size. This approach ist **NOT recommended**. +This will preload all icons without including the SVGs as assets, which results in a larger bundle size. +Therefor this approach is **NOT recommended**. ## Change props to `@internal`: diff --git a/packages/angular/src/app-initialize.ts b/packages/angular/src/app-initialize.ts index d87b06fef0b..9209ca3d897 100644 --- a/packages/angular/src/app-initialize.ts +++ b/packages/angular/src/app-initialize.ts @@ -12,7 +12,7 @@ import { defineCustomElements } from '@siemens/ix/loader'; let didInitialize = false; -export const appInitialize = (preloadIcons?: () => void) => (doc: Document) => { +export const appInitialize = () => (doc: Document) => { return () => { const win: Window | undefined = doc.defaultView as any; if (win && typeof (window as any) !== 'undefined') { @@ -20,10 +20,6 @@ export const appInitialize = (preloadIcons?: () => void) => (doc: Document) => { return; } - if (preloadIcons) { - preloadIcons(); - } - didInitialize = true; iconsDefineCustomElements(); diff --git a/packages/angular/src/module.ts b/packages/angular/src/module.ts index a95a6607c80..a7987ef8bfa 100644 --- a/packages/angular/src/module.ts +++ b/packages/angular/src/module.ts @@ -43,15 +43,13 @@ const DECLARATIONS = [ exports: DECLARATIONS, }) export class IxModule { - static forRoot(options?: { - preloadIcons?: () => void; - }): ModuleWithProviders { + static forRoot(): ModuleWithProviders { return { ngModule: IxModule, providers: [ { provide: APP_INITIALIZER, - useFactory: appInitialize(options?.preloadIcons), + useFactory: appInitialize(), multi: true, deps: [DOCUMENT, NgZone], }, diff --git a/packages/documentation/docs/icon-library/_icon_code.md b/packages/documentation/docs/icon-library/_icon_code.md index d9ef8589b82..6c86aace36f 100644 --- a/packages/documentation/docs/icon-library/_icon_code.md +++ b/packages/documentation/docs/icon-library/_icon_code.md @@ -2,10 +2,40 @@ import Icons from '@site/src/components/Icons'; ## Development +The package ```@siemens/ix-icons``` offers a large set of icons. +It also comes with the ```ix-icon``` component that displays them in your application. +Additionally custom SVG icons (that are not part of the library) can be used. + +As of iX version 3.0.0 not all available iX icons will be loaded automatically anymore. +Only the icons actually used in an app will be part of the bundle to save bandwidth and memory. +Therefor icons need to be imported explicitly. + ### Usage #### Angular +Use the 'addIcon' function to load individual icons once during bootstrapping. +TODO (IX-2072): Add real code example + +```js +addIcon('star') +``` + +Alternatively the whole icon set can be loaded via `angular.json`. +Keep in mind that loading all icons can have a negative impact on the performance of your application and is therefor not recommended. + +```json +"assets": [ + "src/favicon.ico", + "src/assets", + { + "glob": "**/*.svg", + "input": "node_modules/@siemens/ix-icons/svg", + "output": "./svg" + } +], +``` + ```html @@ -15,13 +45,17 @@ import Icons from '@site/src/components/Icons'; #### React ```html - - - +import { iconStar } from '@siemens/ix-icons/icons'; + + + + ``` #### Web components +TODO: Add sample code that loads icons + ```html @@ -31,9 +65,11 @@ import Icons from '@site/src/components/Icons'; #### Vue ```html - - - +import { iconStar } from '@siemens/ix-icons/icons'; + + + + ``` ### Integrate external icons diff --git a/packages/documentation/src/components/ThemeShadows/index.tsx b/packages/documentation/src/components/ThemeShadows/index.tsx index 3b64c7d034f..fd7d978b5cb 100644 --- a/packages/documentation/src/components/ThemeShadows/index.tsx +++ b/packages/documentation/src/components/ThemeShadows/index.tsx @@ -7,42 +7,12 @@ * LICENSE file in the root directory of this source tree. */ import { toast } from '@siemens/ix'; -import { - IxCol, - IxIcon, - IxIconButton, - IxInputGroup, - IxLayoutGrid, - IxRow, -} from '@siemens/ix-react'; +import { IxCol, IxIconButton, IxLayoutGrid, IxRow } from '@siemens/ix-react'; import React, { useState } from 'react'; import { themeShadows } from './shadows'; import './ThemeShadows.css'; import { useTheme } from '@site/src/utils/hooks/useTheme'; -function Search(props: { onChange: (value: string) => void }) { - return ( - - - - { - const value = input.target.value; - props.onChange(value); - }} - /> - - ); -} - function ShadowPreview(props: { border: string }) { return (
@@ -57,19 +27,7 @@ function ShadowPreview(props: { border: string }) { const ThemeShadows: React.FC = () => { useTheme(); - const [borders, setBorders] = useState(themeShadows); - - const updateFilter = (filter) => { - setBorders([ - ...themeShadows.filter((color) => { - if (!filter) { - return true; - } - - return color.toLowerCase().includes(filter.toLowerCase()); - }), - ]); - }; + const [borders] = useState(themeShadows); const copyToClipboard = async (value: string) => { await navigator.clipboard.writeText(value); @@ -81,7 +39,6 @@ const ThemeShadows: React.FC = () => { return (
- updateFilter(value)} /> {borders.map((border) => { return ( From 6fe9ddf00150af44f164318de76ccc4504da4eaf Mon Sep 17 00:00:00 2001 From: Lukas Maurer Date: Thu, 9 Jan 2025 13:10:40 +0100 Subject: [PATCH 02/13] docs(icons): document preloading of icons --- BREAKING_CHANGES/v3.md | 29 +++++++++++++++++------------ 1 file changed, 17 insertions(+), 12 deletions(-) diff --git a/BREAKING_CHANGES/v3.md b/BREAKING_CHANGES/v3.md index 9b2b188bc55..c0986d797f2 100644 --- a/BREAKING_CHANGES/v3.md +++ b/BREAKING_CHANGES/v3.md @@ -47,16 +47,7 @@ export default defineConfig({ ### Usage of icons inside `@siemens/ix-angular` changed - -Use the 'addIcon' function to load individual icons once during bootstrapping. -TODO (IX-2072): Add real code example - -```js -addIcon('star') -``` - -Alternatively the whole icon set can be loaded via `angular.json`. -Keep in mind that loading all icons can have a negative impact on the performance of your application and is therefor not recommended. +Copy iX icons into your project folder via `angular.json`. ```json "assets": [ @@ -70,14 +61,28 @@ Keep in mind that loading all icons can have a negative impact on the performanc ], ``` +Use the `loadIcons` function to load individual icons once during bootstrapping. + +```js +import { loadIcons } from @siemens/ix-icons; + +const icons = [ + 'star', + 'star-filled', + // ... +]; + +loadIcons(icons); +``` + +Then you can reference the loaded iX icons by name anywhere in your application. + ```html ``` ### Usage of icons in pure HTML -TODO: Add example - ```html From f9b18b71f45de93399081f81fde7b871d53029ca Mon Sep 17 00:00:00 2001 From: Lukas Maurer Date: Thu, 9 Jan 2025 13:13:57 +0100 Subject: [PATCH 03/13] Update v3.md --- BREAKING_CHANGES/v3.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/BREAKING_CHANGES/v3.md b/BREAKING_CHANGES/v3.md index c0986d797f2..5aa40537211 100644 --- a/BREAKING_CHANGES/v3.md +++ b/BREAKING_CHANGES/v3.md @@ -88,7 +88,7 @@ Then you can reference the loaded iX icons by name anywhere in your application. ### Custom asset path for icons -In order be able to load custom icons, we need to configure the domain of the asset path. +In order to be able to load custom icons, we need to configure the domain of the asset path. This can either be done via `meta`-tag or with the `setAssetPath`-function. #### with `meta`-tag From 68fc20accef33b791ec4b4e8e82f8effc2141b30 Mon Sep 17 00:00:00 2001 From: Lukas Maurer Date: Thu, 9 Jan 2025 13:34:46 +0100 Subject: [PATCH 04/13] Update v3.md --- BREAKING_CHANGES/v3.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/BREAKING_CHANGES/v3.md b/BREAKING_CHANGES/v3.md index 5aa40537211..1ccfc9b70f7 100644 --- a/BREAKING_CHANGES/v3.md +++ b/BREAKING_CHANGES/v3.md @@ -36,7 +36,7 @@ export default defineConfig({ verbose: true, targets: [ { - src: 'node_modules/@siemens/ix-icons/svg/*.svg', + src: 'node_modules/@siemens/ix-icons/incoming-svg/*.svg', dest: 'public/svg', }, ], From 02ffd1d318a8bc25883753bf8a3268ddcf778c9e Mon Sep 17 00:00:00 2001 From: Lukas Maurer Date: Thu, 9 Jan 2025 13:39:02 +0100 Subject: [PATCH 05/13] Update v3.md --- BREAKING_CHANGES/v3.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/BREAKING_CHANGES/v3.md b/BREAKING_CHANGES/v3.md index 1ccfc9b70f7..2d479cc47f9 100644 --- a/BREAKING_CHANGES/v3.md +++ b/BREAKING_CHANGES/v3.md @@ -55,7 +55,7 @@ Copy iX icons into your project folder via `angular.json`. "src/assets", { "glob": "**/*.svg", - "input": "node_modules/@siemens/ix-icons/svg", + "input": "node_modules/@siemens/ix-icons/incoming-svg", "output": "./svg" } ], From 4ba02d76fc7458e31a892b94ac1a7d042ba7bc2a Mon Sep 17 00:00:00 2001 From: Lukas Maurer Date: Thu, 9 Jan 2025 13:47:05 +0100 Subject: [PATCH 06/13] Update v3.md --- BREAKING_CHANGES/v3.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/BREAKING_CHANGES/v3.md b/BREAKING_CHANGES/v3.md index 2d479cc47f9..730c86314c0 100644 --- a/BREAKING_CHANGES/v3.md +++ b/BREAKING_CHANGES/v3.md @@ -4,9 +4,12 @@ Here is a detailed overview of all breaking changes introduced in this major upd ## Remove package `@siemens/ix-icons` from `@siemens/ix` base library -The `@siemens/ix-icons` package requires manual bootstrapping. For detailed installation instructions, please refer to the [`@siemens/ix-icons`](https://github.com/siemens/ix-icons) repository. +Before version 3 of `@siemens/ix-icons` the entire icon set was loaded into the client causing unnecessary usage of bandwidth and memory. +It is now possible to load icons individually in order to optimize performance. +For that to work the package `@siemens/ix-icons` now requires some manual bootstrapping. +Please refer to the [`@siemens/ix-icons`](https://github.com/siemens/ix-icons) repository for detailed installation instructions. -If you are using one of the framework wrappers such as `@siemens/ix-angular`, `@siemens/ix-react` or `@siemens/ix-vue` refer to the sections below. +For usage with one of the framework wrappers ( `@siemens/ix-angular`, `@siemens/ix-react` and `@siemens/ix-vue`) read the respective section below. ### Usage of icons inside `@siemens/ix-react` and `@siemens/ix-vue` changed From 38dc4ccc70105317a63cd9f315b16c8b0c917d7e Mon Sep 17 00:00:00 2001 From: Lukas Maurer Date: Thu, 9 Jan 2025 13:48:19 +0100 Subject: [PATCH 07/13] Update v3.md --- BREAKING_CHANGES/v3.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/BREAKING_CHANGES/v3.md b/BREAKING_CHANGES/v3.md index 730c86314c0..0fb8d0bf21a 100644 --- a/BREAKING_CHANGES/v3.md +++ b/BREAKING_CHANGES/v3.md @@ -9,7 +9,7 @@ It is now possible to load icons individually in order to optimize performance. For that to work the package `@siemens/ix-icons` now requires some manual bootstrapping. Please refer to the [`@siemens/ix-icons`](https://github.com/siemens/ix-icons) repository for detailed installation instructions. -For usage with one of the framework wrappers ( `@siemens/ix-angular`, `@siemens/ix-react` and `@siemens/ix-vue`) read the respective section below. +For usage with one of the framework wrappers (`@siemens/ix-angular`, `@siemens/ix-react` and `@siemens/ix-vue`) read the respective section below. ### Usage of icons inside `@siemens/ix-react` and `@siemens/ix-vue` changed From af3e93e19af0afc25ebfe0086f7befdd565ace12 Mon Sep 17 00:00:00 2001 From: Lukas Maurer Date: Thu, 9 Jan 2025 13:49:17 +0100 Subject: [PATCH 08/13] Update v3.md --- BREAKING_CHANGES/v3.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/BREAKING_CHANGES/v3.md b/BREAKING_CHANGES/v3.md index 0fb8d0bf21a..a3a45a354d6 100644 --- a/BREAKING_CHANGES/v3.md +++ b/BREAKING_CHANGES/v3.md @@ -64,7 +64,7 @@ Copy iX icons into your project folder via `angular.json`. ], ``` -Use the `loadIcons` function to load individual icons once during bootstrapping. +You can use the `loadIcons` function to load individual icons once during bootstrapping. ```js import { loadIcons } from @siemens/ix-icons; From aca6e4c6a7e92761484f510ca299c608a59f6043 Mon Sep 17 00:00:00 2001 From: Lukas Maurer Date: Thu, 9 Jan 2025 13:56:58 +0100 Subject: [PATCH 09/13] docs(angular/icons): update installation guide --- .../docs/icon-library/_icon_code.md | 30 +++++++++++-------- 1 file changed, 18 insertions(+), 12 deletions(-) diff --git a/packages/documentation/docs/icon-library/_icon_code.md b/packages/documentation/docs/icon-library/_icon_code.md index 6c86aace36f..c677078c495 100644 --- a/packages/documentation/docs/icon-library/_icon_code.md +++ b/packages/documentation/docs/icon-library/_icon_code.md @@ -14,15 +14,7 @@ Therefor icons need to be imported explicitly. #### Angular -Use the 'addIcon' function to load individual icons once during bootstrapping. -TODO (IX-2072): Add real code example - -```js -addIcon('star') -``` - -Alternatively the whole icon set can be loaded via `angular.json`. -Keep in mind that loading all icons can have a negative impact on the performance of your application and is therefor not recommended. +Copy iX icons into your project folder via `angular.json`. ```json "assets": [ @@ -30,12 +22,28 @@ Keep in mind that loading all icons can have a negative impact on the performanc "src/assets", { "glob": "**/*.svg", - "input": "node_modules/@siemens/ix-icons/svg", + "input": "node_modules/@siemens/ix-icons/incoming-svg", "output": "./svg" } ], ``` +You can use the `loadIcons` function to load individual icons once during bootstrapping. + +```js +import { loadIcons } from @siemens/ix-icons; + +const icons = [ + 'star', + 'star-filled', + // ... +]; + +loadIcons(icons); +``` + +Then you can reference the loaded iX icons by name anywhere in your application. + ```html @@ -54,8 +62,6 @@ import { iconStar } from '@siemens/ix-icons/icons'; #### Web components -TODO: Add sample code that loads icons - ```html From 7075effe3df6775a62e58615ee53dbb2fe2df441 Mon Sep 17 00:00:00 2001 From: Lukas Maurer Date: Mon, 13 Jan 2025 14:44:11 +0100 Subject: [PATCH 10/13] Update BREAKING_CHANGES/v3.md Co-authored-by: matthiashader <144090716+matthiashader@users.noreply.github.com> --- BREAKING_CHANGES/v3.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/BREAKING_CHANGES/v3.md b/BREAKING_CHANGES/v3.md index a3a45a354d6..45b895eb9d7 100644 --- a/BREAKING_CHANGES/v3.md +++ b/BREAKING_CHANGES/v3.md @@ -110,7 +110,7 @@ This can either be done via `meta`-tag or with the `setAssetPath`-function. ``` -Above will fetch the SVG from `https://some-resource-domain/star.svg` +Above code will fetch the SVG from `https://some-resource-domain/star.svg` #### with `setAssetPath`-function From 075f9ee9ba5fb92489fa50814e8c8fcec2277e0d Mon Sep 17 00:00:00 2001 From: Lukas Maurer Date: Mon, 13 Jan 2025 14:44:49 +0100 Subject: [PATCH 11/13] Update BREAKING_CHANGES/v3.md Co-authored-by: matthiashader <144090716+matthiashader@users.noreply.github.com> --- BREAKING_CHANGES/v3.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/BREAKING_CHANGES/v3.md b/BREAKING_CHANGES/v3.md index 45b895eb9d7..3a2b3580f78 100644 --- a/BREAKING_CHANGES/v3.md +++ b/BREAKING_CHANGES/v3.md @@ -129,7 +129,7 @@ setAssetPath('https://some-resource-domain'); Above code will fetch the SVG from `https://some-resource-domain/star.svg` This will preload all icons without including the SVGs as assets, which results in a larger bundle size. -Therefor this approach is **NOT recommended**. +Therefore, this approach is **NOT recommended**. ## Change props to `@internal`: From 7bf336306ce0c61ad0386fe7d45a39c327ad7bbd Mon Sep 17 00:00:00 2001 From: Lukas Maurer Date: Mon, 13 Jan 2025 16:29:39 +0100 Subject: [PATCH 12/13] Apply suggestions from code review Co-authored-by: matthiashader <144090716+matthiashader@users.noreply.github.com> --- BREAKING_CHANGES/v3.md | 2 +- packages/documentation/docs/icon-library/_icon_code.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/BREAKING_CHANGES/v3.md b/BREAKING_CHANGES/v3.md index 3a2b3580f78..cba01dc5f15 100644 --- a/BREAKING_CHANGES/v3.md +++ b/BREAKING_CHANGES/v3.md @@ -114,7 +114,7 @@ Above code will fetch the SVG from `https://some-resource-domain/star.svg` #### with `setAssetPath`-function -Make sure to call the `setAssetPath`-function before using the `IxIcon` component (f.e. in the main file). +Make sure to call the `setAssetPath`-function before using the `IxIcon` component (e.g. in the main file). ```ts import { setAssetPath } from '@siemens/ix-icons/components'; diff --git a/packages/documentation/docs/icon-library/_icon_code.md b/packages/documentation/docs/icon-library/_icon_code.md index c677078c495..bf0a8ead10c 100644 --- a/packages/documentation/docs/icon-library/_icon_code.md +++ b/packages/documentation/docs/icon-library/_icon_code.md @@ -7,8 +7,8 @@ It also comes with the ```ix-icon``` component that displays them in your applic Additionally custom SVG icons (that are not part of the library) can be used. As of iX version 3.0.0 not all available iX icons will be loaded automatically anymore. -Only the icons actually used in an app will be part of the bundle to save bandwidth and memory. -Therefor icons need to be imported explicitly. +Only the icons actually used in the application will be part of the bundle to save bandwidth and memory. +As a result, icons must now be imported explicitly. ### Usage From b217eeb7022c6c3ced70e111e7178be6a2d4b70a Mon Sep 17 00:00:00 2001 From: Lukas Maurer Date: Mon, 13 Jan 2025 16:32:34 +0100 Subject: [PATCH 13/13] docs(v3): apply feedback from code review --- BREAKING_CHANGES/v3.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/BREAKING_CHANGES/v3.md b/BREAKING_CHANGES/v3.md index cba01dc5f15..840a71d406b 100644 --- a/BREAKING_CHANGES/v3.md +++ b/BREAKING_CHANGES/v3.md @@ -4,9 +4,9 @@ Here is a detailed overview of all breaking changes introduced in this major upd ## Remove package `@siemens/ix-icons` from `@siemens/ix` base library -Before version 3 of `@siemens/ix-icons` the entire icon set was loaded into the client causing unnecessary usage of bandwidth and memory. -It is now possible to load icons individually in order to optimize performance. -For that to work the package `@siemens/ix-icons` now requires some manual bootstrapping. +Prior to version 3.0.0 of `@siemens/ix-icons` the entire icon set was loaded into the client by default, which caused unnecessary usage of bandwidth and memory. +Starting with version 3.0.0, icons can now be loaded individually, providing significant performance optimizations. +To enable individual icon loading, the @siemens/ix-icons package now requires manual bootstrapping. Please refer to the [`@siemens/ix-icons`](https://github.com/siemens/ix-icons) repository for detailed installation instructions. For usage with one of the framework wrappers (`@siemens/ix-angular`, `@siemens/ix-react` and `@siemens/ix-vue`) read the respective section below.