import { Meta } from '@storybook/addon-docs/blocks';

<Meta
  title="Migration guide"
  parameters={{
    layout: 'fullscreen',
    viewMode: 'docs',
    previewTabs: {
      canvas: { hidden: true },
    },
  }}
/>

# Migration Guide

This guide helps you migrate from **v0.30.0** to **v1.X.X** of `@mozaic-ds/web-components`.

This new version introduces **Svelte 5**, ships **Svelte components** and **Web Components**, and aligns with **Mozaic Core V2** (styles + tokens).

---

## Table of contents

- [Overview](#overview)
- [What changed (at a glance)](#what-changed-at-a-glance)
- [Prerequisites](#prerequisites)
- [Install & build updates](#install--build-updates)
- [Styles & tokens migration](#styles--tokens-migration)
- [Component API changes](#component-api-changes)
  - [Button example (props → slots)](#button-example-props--slots)
  - [Common slot patterns](#common-slot-patterns)
- [Using Svelte components](#using-svelte-components)
- [Using Web Components](#using-web-components)
  - [Framework integration quick notes](#framework-integration-quick-notes)
- [New components in V2](#new-components-in-v2)
- [Deprecated components (from V1)](#deprecated-components-from-v1)
- [Component mapping (V1 → V2)](#component-mapping-v1--v2)
- [Accessibility changes](#accessibility-changes)
- [Quality checks before shipping](#quality-checks-before-shipping)
- [FAQ](#faq)
- [References](#references)

---

## Overview

V2 is a modernized, dual-delivery library:

- **Svelte 5 components** for first-class Svelte apps.
- **Web Components** (native Custom Elements) for any framework (React, Vue, Angular, plain HTML, etc.).
- **Slot-first APIs** for icons, labels, and composition.
- **Core V2 alignment** (ITCSS, Sass Module System, functional tokens only).

---

## What changed (at a glance)

| Area           | v1                                 | v2                                                          | Migration action                          |
| -------------- | ---------------------------------- | ----------------------------------------------------------- | ----------------------------------------- |
| Svelte         | Svelte 3                           | **Svelte 5**                                                | Update tooling & code where needed        |
| Delivery       | Mostly WC or Svelte (not unified)  | **Both:** `/svelte` exports + `/lib` web-component build    | Choose one per app (Svelte or WC)         |
| API shape      | Prop-heavy (e.g., `icon`, `label`) | **Slots** (e.g., `<slot name="icon" />`, default for label) | Move content from props to slots          |
| Styles         | `@import` patterns                 | **Sass Modules** (`@use`, `@forward`)                       | Replace imports, use namespaces           |
| Tokens         | Primitive tokens exposed           | **Functional tokens only**                                  | Map/rename tokens; remove primitive usage |
| Browser legacy | IE & Edge legacy workarounds       | **Dropped**                                                 | Remove polyfills/hacks if present         |

---

## Prerequisites

- **Node 20+**
- **Svelte 5** (when consuming Svelte components)
- **Dart Sass 1.80+** (if you build SCSS using Core styles)
- Modern bundler (Vite, Rollup, Webpack 5+)

---

## Install & build updates

```bash
# npm
npm install @mozaic-ds/web-components --save

# or Yarn
yarn add @mozaic-ds/web-components -E
```

If you use the **Web Components** build, ensure the library is **registered** (side-effect import):

```js
// Typically in your app entry
import '@mozaic-ds/web-components/lib';
```

> Tip: For Svelte apps using the **Svelte components** flavor, you don’t need the WC registration import.

---

## Styles & tokens migration

### Replace `@import` with `@use`

**Old (v1):**

```scss
@import '@mozaic-ds/styles/all-settings';
```

**New (v2):**

```scss
@use '@mozaic-ds/tokens' as *;
// Example usage:
.myClass {
  padding: $spacing-400;
}
```

### Functional tokens only

If you referenced **functional tokens** (raw colors, etc.), switch to **functional tokens**.

**Old (primitive-esque):**

```scss
color: $color-blue-500;
```

**New (functional):**

```scss
@use '@mozaic-ds/token' as *;

background-color: $color-background-accent;
```

---

## Component API changes

V2 favors **slots** over props for injectables like icons and labels. Expect to:

- Replace `icon` and `label` props with **slots**.
- Keep semantic attributes (`appearance`, `size`, `disabled`, etc.) as **attributes/props**.

### Button example (props → slots)

**Old (v1, indicative):**

```svelte
<!-- Svelte or WC with props -->
<Button label="Checkout" icon="cart" appearance="accent" />
```

**New (v2):**

#### Web Component

```html
<m-button appearance="accent">
  Checkout
  <span slot="icon">🛒</span>
</m-button>
```

#### Svelte Component

```svelte
<script>
  import { Button } from '@mozaic-ds/web-components/svelte';
</script>

<Button appearance="accent">
  Checkout
  <span slot="icon">🛒</span>
</Button>
```

> Label is now the **default slot** content.  
> Icons go into a **named `icon` slot**.

### Common slot patterns

| Pattern       | Slot name     | Typical content                                                          |
| ------------- | ------------- | ------------------------------------------------------------------------ |
| Icon (single) | `icon`        | `<span slot="icon">…</span>` or `<m-icon slot="icon" name="…"></m-icon>` |
| Header        | `header`      | Titles, headings                                                         |
| Footer        | `footer`      | Actions, secondary buttons                                               |
| Label         | _default_     | Button or link text                                                      |
| Description   | `description` | Supporting text under headings                                           |

> Always check each component’s Storybook page for its exact slot names.

---

## Using Svelte components

**Install** and import from the **`/svelte`** entry:

```svelte
<script>
  import { Button } from '@mozaic-ds/web-components/svelte';
</script>

<Button appearance="accent">My first Svelte Button</Button>
```

**Why Svelte components?**

- Native Svelte 5 reactivity and composition
- No custom element registration step
- Best DX when your app is Svelte

---

## Using Web Components

**Register once** (side-effect import) and use tags directly:

```js
import '@mozaic-ds/web-components/lib';
```

```html
<m-button appearance="accent">This is an accent button</m-button>
```

### Framework integration quick notes

- **React**: Use tags directly in JSX. Remember `className` (React) vs `class`.
- **Vue**: Works out of the box; see Vue’s official Web Components notes.
- **Angular**: Add `CUSTOM_ELEMENTS_SCHEMA` to the module that uses the components.

---

## New components in V2

V2 introduces several components that did not exist in V1:

| **Category**      | **Component**                                                                                           |
| ----------------- | ------------------------------------------------------------------------------------------------------- |
| **Actions**       | `Icon Button`                                                                                           |
| **Content**       | `Accordeon List` • `Avatar` • `Avatar group` • `Callout` • `Carousel` • `Tile`                          |
| **Form elements** | `Advanced Date Picker` • `Pincode Input`                                                                |
| **Indicators**    | `Circular Progress Bar` • `Linear Progress Bar` • `Navigation Indicator` • `Number Badge` • `Scrollbar` |
| **Navigation**    | `Check-list Menu` • `Link group` • `Sidebar`                                                            |
| **Overlay**       | `Action List` • `Drawer` • `Popover` • `Toaster`                                                        |
| **Status**        | `KPI Item` • `Status Badge` • `Status Dot` • `Status Notification`                                      |
| **Structure**     | `Action Bottom Bar` • `Page Header` • `Stepper Bottom Bar`                                              |

> Refer to each component’s Storybook page for detailed props, slots, and examples.

---

## Deprecated components (from V1)

The following V1 components are removed or renamed in V2:

| **V1**          | **V2**     | **Notes**               |
| --------------- | ---------- | ----------------------- |
| `Accordion`     | ❌ Removed |                         |
| `Action Bar`    | Renamed ♻️ | See mapping table below |
| `Badge`         | Renamed ♻️ | See mapping table below |
| `Bottom Bar`    | Renamed ♻️ | See mapping table below |
| `Card`          | ❌ Removed |                         |
| `File Uploader` | Renamed ♻️ | See mapping table below |
| `Header`        | Renamed ♻️ | See mapping table below |
| `Heading`       | ❌ Removed |                         |
| `Hero`          | ❌ Removed |                         |
| `KPI`           | Renamed ♻️ | See mapping table below |
| `Layer`         | Renamed ♻️ | See mapping table below |
| `Menu`          | Renamed ♻️ | See mapping table below |
| `Modal`         | Renamed ♻️ | See mapping table below |
| `Notification`  | Renamed ♻️ | See mapping table below |
| `Option Button` | ❌ Removed |                         |
| `Option Card`   | ❌ Removed |                         |
| `Progress Bar`  | Renamed ♻️ | See mapping table below |
| `Stars Input`   | ❌ Removed |                         |
| `Stars Result`  | ❌ Removed |                         |
| `Stepper Bar`   | Renamed ♻️ | See mapping table below |
| `Tag List`      | ❌ Removed |                         |

---

## Component mapping (V1 → V2)

Use this table to find the V2 replacement or equivalent for each V1 component:

|                   | **V1**               | **V2**                  | **Notes**         |
| ----------------- | -------------------- | ----------------------- | ----------------- |
| **Actions**       |                      |                         |                   |
|                   | `Button`             | `Button`                | Code updated.     |
|                   | —                    | `Icon Button`           | 🆕 New            |
| **Content**       |                      |                         |                   |
|                   | `Accordion`          | —                       | ❌ Removed in V2  |
|                   | —                    | `Accordeon list`        | 🆕 New            |
|                   | —                    | `Avatar`                | 🆕 New            |
|                   | —                    | `Avatar group`          | 🆕 New            |
|                   | —                    | `Callout`               | 🆕 New            |
|                   | —                    | `Carousel`              | 🆕 New            |
|                   | `Heading`            | —                       | ❌ Removed in V2  |
|                   | `Hero`               | —                       | ❌ Removed in V2  |
|                   | —                    | `Tile`                  | 🆕 New            |
| **Data**          |                      |                         |                   |
|                   | `Datatable`          | —                       |                   |
| **Form elements** |                      |                         |                   |
|                   | —                    | `Advanced Datepicker`   | 🆕 New            |
|                   | `Autocomplete`       | `Autocomplete`          |                   |
|                   | `Checkbox`           | `Checkbox`              | ↔️ No code change |
|                   | `Dropdown`           | `Dropdown`              |                   |
|                   | `Datepicker`         | `Datepicker`            | Code updated.     |
|                   | `Fields`             | `Field`                 | Code updated.     |
|                   | `File uploader`      | `File uploader`         |                   |
|                   | `Option Button`      |                         | ❌ Removed in V2  |
|                   | `Option Card`        |                         | ❌ Removed in V2  |
|                   | `Password Input`     | `Password Input`        | Code updated.     |
|                   | `Phone number Input` | `Phone number Input`    | Code updated.     |
|                   | —                    | `Pincode Input`         | 🆕 New            |
|                   | `Quantity selector`  | `Quantity selector`     | Code updated.     |
|                   | `Radio button`       | `Radio button`          | ↔️ No code change |
|                   | `Search Input`       | `Search Input`          | Code updated.     |
|                   | `Select`             | `Select`                | ↔️ No code change |
|                   | `Textarea`           | `Textarea`              | ↔️ No code change |
|                   | `Text Input`         | `Text Input`            | Code updated.     |
|                   | `Toggle`             | `Toggle`                | Code updated.     |
| **Indicators**    |                      |                         |                   |
|                   | —                    | `Circular progress bar` | 🆕 New            |
|                   | `Flag`               | `Flag`                  |                   |
|                   | `Progressbar`        | `Linear progress bar`   |                   |
|                   | `Loader`             | `Loader`                | Code updated.     |
|                   | —                    | `Navigation indicator`  | 🆕 New            |
|                   | —                    | `Number Badge`          | 🆕 New            |
|                   | `Rating Stars`       | `Rating Stars`          |                   |
|                   | —                    | `Scrollbar`             | 🆕 New            |
|                   | `Stepper`            | `Stepper`               |                   |
|                   | `Tag`                | `Tag`                   | Code updated.     |
| **Navigation**    |                      |                         |                   |
|                   | `Breadcrumb`         | `Breadcrumb`            | Code updated.     |
|                   | `Menu`               | `Built-in menu`         |                   |
|                   | —                    | `Check-list menu`       | 🆕 New            |
|                   | `Link`               | `Link (standalone)`     | Code updated.     |
|                   | —                    | `Link group`            | 🆕 New            |
|                   | `Pagination`         | `Pagination`            |                   |
|                   | `Segmented control`  | `Segmented control`     |                   |
|                   | —                    | `Sidebar`               | 🆕 New            |
|                   | `Tabs`               | `Tabs`                  |                   |
| **Overlay**       |                      |                         |                   |
|                   | —                    | `Action list`           | 🆕 New            |
|                   | `Layer`              | `Drawer`                | Renamed ♻️        |
|                   | `Listbox`            | `Listbox`               |                   |
|                   | `Overlay Loader`     | `Loading overlay`       |                   |
|                   | `Modal`              | `Modal`                 | Renamed ♻️        |
|                   | —                    | `Popover`               | 🆕 New            |
|                   | `Overlay`            | `Overlay`               |                   |
|                   | —                    | `Toaster`               | 🆕 New            |
|                   | `Tooltip`            | `Tooltip`               |                   |
| **Status**        |                      |                         |                   |
|                   | `KPI`                | `KPI Item`              | Renamed ♻️        |
|                   | `Badge`              | `Status Badge`          | Renamed ♻️        |
|                   | —                    | `Status Dot`            | 🆕 New            |
|                   | `Notification`       | `Status Notification`   | Renamed ♻️        |
| **Structure**     |                      |                         |                   |
|                   | `Action Bar`         | `Action Bottom Bar`     | Renamed ♻️        |
|                   | `Divider`            | `Divider`               |                   |
|                   | —                    | `Page Header`           | 🆕 New            |
|                   | `Stepper Bar`        | `Stepper Bottom Bar`    | Renamed ♻️        |

> Where the table says “Code updated”, check the component’s Storybook page for new props/slots and behavior.

---

## Accessibility changes

- Prefer WCAG-compliant defaults (via functional tokens).
- Use provided **slot structure** for semantic content.
- For visually hidden text, use Core V2 utilities (`visually-hidden()` or `.mu-visually-hidden`).

---

## Quality checks before shipping

- ✅ Slots replace legacy props.
- ✅ Sass uses `@use`/`@forward` only.
- ✅ Functional tokens only.
- ✅ Toolchain supports Svelte 5 & Dart Sass 1.80+.
- ✅ Interaction + A11y tests pass.

---

## FAQ

**Q: Which library to use (web-components or Svelte)?**  
A:

- Web Components → Ideal for multi-framework projects (React, Vue, Angular, Vanilla JS) or when framework independence is important. Great for CMS-driven, legacy, or microfrontend architectures.

- Svelte Components → Best for Svelte 5 applications. They integrate seamlessly with Svelte’s reactivity, require no element registration, and deliver the smoothest developer experience.

**Q: Do I need both?**  
A: Generally, no. Choose one per application to avoid duplicate code and unnecessary bundle weight.
Only mix if you have a real architectural need (e.g., a Svelte app embedding a WC-only feature in a shared microfrontend).

**Q: How to handle icons?**  
A:

- Svelte → Use @mozaic-ds/icons-svelte (`<Search24 />, <More64 />`…), sizes 20/24/32/64, fill="currentColor", aria-label.

- Web Components → Same package, import globally (custom-elements.js) or individually (`<search-24>`).

- In a V2 component → Pass the icon via the icon slot.

---

## References

- Introduction - [“Getting Started - Introduction”](/docs/getting-started-introduction--docs)
- Svelte documentation - [“Getting Started - Svelte](/docs/getting-started-svelte-introduction--docs)
- Web-component documentation - [“Getting Started - Web-component](/docs/getting-started-web-components-introduction--docs)
- Core V2 [Getting Started](https://main--651ae46c2a6f4410809759ce.chromatic.com/?path=/docs/getting-started--docs)
