V3 icon docs

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
 
@@ -36,7 +39,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',
         },
       ],
@@ -47,33 +50,49 @@ export default defineConfig({
 
 ### Usage of icons inside `@siemens/ix-angular` changed
 
-To use imports by name (e.g. `<ix-icon name="star"></ix-icon>`), you need to add a configuration entry inside of `angular.json`:
+Copy iX icons into your project folder via `angular.json`.
 
 ```json
 "assets": [
   "src/favicon.ico",
   "src/assets",
   {
   "glob": "**/*.svg",
-  "input": "node_modules/@siemens/ix-icons/svg",
+  "input": "node_modules/@siemens/ix-icons/incoming-svg",
   "output": "./svg"
   }
 ],
 ```
 
-TODO: Clarification needed if the legacy feature `preloadIcons` should be part of the PR.
+You can use the `loadIcons` function to load individual icons once during bootstrapping.
 
-To re-enable the preloaded icons you can provide the `preloadIcons` function as configuration to the module import.
+```js
+import { loadIcons } from @siemens/ix-icons;
 
-```ts
-IxModule.forRoot({
-  preloadIcons,
-}),
+const icons = [
+  'star',
+  'star-filled',
+  // ...
+];
+
+loadIcons(icons);
+```
+
+Then you can reference the loaded iX icons by name anywhere in your application.
+
+```html
+<ix-icon name="star"></ix-icon>
 ```
 
+### Usage of icons in pure HTML
+
+```html
+<ix-icon name="star"></ix-icon>
+
 ### 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 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
 
@@ -91,11 +110,11 @@ To configure the asset path from which domain the `ix-icon` component will load
 <IxIcon name="star"></IxIcon>
 ```
 
-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';
@@ -107,9 +126,10 @@ setAssetPath('https://some-resource-domain');
 <IxIcon name="star"></IxIcon>
 ```
 
-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`:
 

packages/angular/src/app-initialize.ts

@@ -12,18 +12,14 @@ 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') {
       if (didInitialize) {
         return;
       }
 
-      if (preloadIcons) {
-        preloadIcons();
-      }
-
       didInitialize = true;
 
       iconsDefineCustomElements();

packages/angular/src/module.ts

@@ -43,15 +43,13 @@ const DECLARATIONS = [
   exports: DECLARATIONS,
 })
 export class IxModule {
-  static forRoot(options?: {
-    preloadIcons?: () => void;
-  }): ModuleWithProviders<IxModule> {
+  static forRoot(): ModuleWithProviders<IxModule> {
     return {
       ngModule: IxModule,
       providers: [
         {
           provide: APP_INITIALIZER,
-          useFactory: appInitialize(options?.preloadIcons),
+          useFactory: appInitialize(),
           multi: true,
           deps: [DOCUMENT, NgZone],
         },

packages/documentation/docs/icon-library/_icon_code.md

@@ -2,10 +2,48 @@ 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
 
+Copy iX icons into your project folder via `angular.json`.
+
+```json
+"assets": [
+  "src/favicon.ico",
+  "src/assets",
+  {
+  "glob": "**/*.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
 <ix-icon name="star" size="16"></ix-icon>
 <ix-icon name="star" size="24"></ix-icon>
@@ -15,9 +53,11 @@ import Icons from '@site/src/components/Icons';
 #### React
 
 ```html
-<IxIcon name="star" size="16"></IxIcon>
-<IxIcon name="star" size="24"></IxIcon>
-<IxIcon name="star" size="32"></IxIcon>
+import { iconStar } from '@siemens/ix-icons/icons';
+
+<IxIcon name="{iconStar}" size="16"></IxIcon>
+<IxIcon name="{iconStar}" size="24"></IxIcon>
+<IxIcon name="{iconStar}" size="32"></IxIcon>
 ```
 
 #### Web components
@@ -31,9 +71,11 @@ import Icons from '@site/src/components/Icons';
 #### Vue
 
 ```html
-<IxIcon name="star" size="16"></IxIcon>
-<IxIcon name="star" size="24"></IxIcon>
-<IxIcon name="star" size="32"></IxIcon>
+import { iconStar } from '@siemens/ix-icons/icons';
+
+<IxIcon name="{iconStar}" size="16"></IxIcon>
+<IxIcon name="{iconStar}" size="24"></IxIcon>
+<IxIcon name="{iconStar}" size="32"></IxIcon>
 ```
 
 ### Integrate external icons

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 (
-    <IxInputGroup style={{ marginBottom: '2rem' }}>
-      <IxIcon
-        name="search"
-        slot="input-start"
-        size="16"
-        color="color-primary"
-      ></IxIcon>
-
-      <input
-        type={'text'}
-        className={'form-control'}
-        placeholder="Search"
-        onChange={(input) => {
-          const value = input.target.value;
-          props.onChange(value);
-        }}
-      />
-    </IxInputGroup>
-  );
-}
-
 function ShadowPreview(props: { border: string }) {
   return (
     <div className="Shadow__Preview">
@@ -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 (
     <div className="Theme__Shadows">
-      <Search onChange={(value) => updateFilter(value)} />
       <IxLayoutGrid>
         {borders.map((border) => {
           return (