Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

V3 icon docs #1600

Draft
wants to merge 2 commits into
base: release-3.0.0
Choose a base branch
from
Draft

V3 icon docs #1600

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
1542c09
docs: add icon usage examples
nuke-ellington Dec 5, 2024
46e1b14
Merge branch 'release-3.0.0' into v3-icon-docs
danielleroux Dec 5, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 25 additions & 13 deletions BREAKING_CHANGES/v3.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -47,7 +47,16 @@ 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`:

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": [
Expand All @@ -61,19 +70,21 @@ To use imports by name (e.g. `<ix-icon name="star"></ix-icon>`), you need to add
],
```

TODO: Clarification needed if the legacy feature `preloadIcons` should be part of the PR.
```html
<ix-icon name="star"></ix-icon>
```

### 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
<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 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

Expand All @@ -91,11 +102,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';
Expand All @@ -107,9 +118,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`:

Expand Down
6 changes: 1 addition & 5 deletions packages/angular/src/app-initialize.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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();
Expand Down
6 changes: 2 additions & 4 deletions packages/angular/src/module.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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],
},
Expand Down
48 changes: 42 additions & 6 deletions packages/documentation/docs/icon-library/_icon_code.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
<ix-icon name="star" size="16"></ix-icon>
<ix-icon name="star" size="24"></ix-icon>
Expand All @@ -15,13 +45,17 @@ 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

TODO: Add sample code that loads icons

```html
<ix-icon name="star" size="16"></ix-icon>
<ix-icon name="star" size="24"></ix-icon>
Expand All @@ -31,9 +65,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
Expand Down
47 changes: 2 additions & 45 deletions packages/documentation/src/components/ThemeShadows/index.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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">
Expand All @@ -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);
Expand All @@ -81,7 +39,6 @@ const ThemeShadows: React.FC = () => {

return (
<div className="Theme__Shadows">
<Search onChange={(value) => updateFilter(value)} />
<IxLayoutGrid>
{borders.map((border) => {
return (
Expand Down
Loading