@engie-group/fluid-design-system-angular
Version:
Fluid Design System Angular
217 lines (160 loc) • 5.92 kB
Markdown
# Fluid Angular Library v2.13.0 → v6.0.0 Migration Guide
This migration guide helps you upgrade from v2.13.0 (or v3.x) to v6.0.0, summarizing breaking changes, new features, and actions needed for a smooth transition. Follow each step and test your UI after each phase.
---
## 1. **Framework & Dependency Update**
### 1.1. **Angular Version**
- **What changed:** Fluid v6.0.0 requires Angular 20.
- **Action:** Upgrade your app to Angular 20. Older versions are not supported. You may need to apply Angular update steps first.
---
## 2. **General Property Changes**
- **Many `size` inputs are now called `scale`** for consistency.
- **Action:** Update all component inputs, outputs, and local CSS/classnames from `size` to `scale`.
```html
<!-- Before -->
<nj-avatar size="md"></nj-avatar>
<!-- After -->
<nj-avatar scale="md"></nj-avatar>
```
- **All deprecated components, from v2.x, have been removed.**
- **Action:** Remove any usages of deprecated components from your codebase.
---
## 3. **Component-by-Component Migration Steps**
### 3.1. **Button & Icon Button**
- **What changed:** Custom elements replaced with directives on native buttons.
- **Action:** Change `<nj-button>` to `<button nj-button>`, and `<nj-icon-button>` to `<button nj-icon-button>`.
```html
<!-- Before -->
<nj-button>Label</nj-button>
<nj-icon-button icon="info"></nj-icon-button>
<!-- After -->
<button nj-button>Label</button>
<button nj-icon-button icon="info"></button>
```
---
### 3.2. **List & List Items**
- **What changed:** List component/directive pattern updated.
- **Action:** Replace usages of `<nj-list-group>` and `<li nj-list-item>` with `<ul njList>` and `<li njListItem>`.
```html
<!-- Before -->
<nj-list-group>
<li nj-list-item>Item</li>
</nj-list-group>
<!-- After -->
<ul njList >
<li njListItem>
<nj-list-item-content>Item</nj-list-item-content>
</li>
</ul>
```
---
### 3.3. **Link & Icon**
- **What changed:** `<nj-link>` is now a directive for `<a>`. Custom icons use `*njTemplate="'icon'"` instead of `custom-icon` attribute. `nj-link` no longer need to have `hasIcon="true"` it is inferred automatically.
- **Action:** Switch to `<a nj-link>` and adjust any custom icon markup.
```html
<!-- Before -->
<nj-link href="..." hasIcon="true">
Label
<nj-icon custom-icon name="home"></nj-icon>
</nj-link>
<!-- After -->
<a nj-link href="...">
Label
<nj-icon *njTemplate="'icon'" name="home"></nj-icon>
</a>
```
---
### 3.4. **Segmented Control**
- **What changed:** Value/output handling is simplified, child elements must be native `<button>`.
- **Action:** Use `[(value)]`, `(valueChange)`, and update your markup.
```html
<!-- Before -->
<nj-segmented-control [(ngModel)]="selected">
<nj-segmented-control-button value="item">Item</nj-segmented-control-button>
</nj-segmented-control>
<!-- After -->
<nj-segmented-control [(value)]="selected">
<button nj-segmented-control-button value="item">Item</button>
</nj-segmented-control>
```
---
### 3.5. **Avatar & Avatar List**
- **What changed:** All avatar sizing now uses `scale`, background for image avatars removed. Scale values updated:
- `md`: 40px (was 48px)
- `lg`: 48px (was 64px)
- `xl`: 56px (was 96px)
- New: `2xl` → 64px; `3xl` → 96px
- **Action:** Update all usages and compositions.
```html
<!-- Before -->
<nj-avatar size="md" ...></nj-avatar>
<!-- After -->
<nj-avatar scale="md" ...>
<nj-status-indicator status="online" />
<nj-badge [value]="3"/>
</nj-avatar>
```
---
### 3.6. **Inline Message**
- **What changed:** Title slot removed; for an action use `*njTemplate="'action'"`, position determined by `actionsPlacement`.
- **Action:** Remove title, add action via template.
```html
<!-- Before -->
<nj-inline-message>
<span njInlineMessageTitle>Title</span>
Message.
</nj-inline-message>
<!-- After: Remove title -->
<nj-inline-message>
Message.
<nj-link *njTemplate="'action'">Learn more</nj-link>
</nj-inline-message>
```
---
### 3.7. **Autocomplete**
- **What changed:** `search` output has been renamed to `inputValueChange`.
- **Action:** Rename output from `search` to `inputValueChange`.
```html
<!-- Before -->
<nj-autocomplete (search)="handleFunction($event)">
<span njFormLabel>label</span>
<span njFormSubscript>subscript</span>
</nj-autocomplete>
<!-- After: Remove title -->
<nj-autocomplete (inputValueChange)="handleFunction($event)">
<span njFormLabel>label</span>
<span njFormSubscript>subscript</span>
</nj-autocomplete>
```
---
## 4. **Other Major Changes**
- **Spinner:** Use `scale="2xs"`, not `xxs`; conditionally render the component with `@if` instead of removed `isLoading` input.
```angular2html
<!-- Before -->
<nj-spinner size="xxs" isLoading="isLoading"></nj-spinner>
<!-- After -->
@if (isLoading) {
<nj-spinner scale="2xs"></nj-spinner>
}
```
- **Toggle:** New `handleIcon` input to show an icon on the handle.
- **Tag:** Use `scale` for sizing, new `xl` size available.
---
## 5. **Design Tokens & Styles**
- **Fonts (Lato, Material Icons, Roboto Mono):** Now included; remove manual imports.
- **Typo/line-height tokens:** Switch to responsive tokens (e.g. `--nj-semantic-font-size-text-<scale>`).
---
## 6. **Recommended Migration Steps**
1. Upgrade Angular to v20, update Fluid dependencies.
2. Refactor HTML for all described component/selector changes.
3. Update input names (`size` → `scale`, etc), outputs, and template usage.
4. Remove deprecated components/packages.
5. Adjust stylesheets and font imports as needed.
6. Test your UI thoroughly.
---
## 7. **Testing & Troubleshooting**
- Check all page sections for rendering and errors.
- Double-check list, button, avatar, menu, spinner, and message usages.
- Consult Fluid documentation for examples.
---
**Done! Your app is now on Fluid Angular v6.0.0.**
If you encounter issues or need clarification, please reach out to us.