@mozaic-ds/web-components 1.0.0-alpha.8 → 1.0.0-beta.0

package/dist/documentation/Contributing.mdx

@@ -0,0 +1,110 @@
+import { Meta } from '@storybook/blocks';
+import { Mermaid } from 'mdx-mermaid/Mermaid';
+
+<Meta title="Getting Started/Contributing" />
+
+# 🤝 Be Part of Something Bigger!
+
+**Mozaic-WebComponents** exists thanks to the continuous support and involvement of an incredible community of developers and designers.<br/>
+Each issue reported, bug fixed, or new feature proposed helps us improve and deliver better tools for everyone.
+
+If you spot something that could be improved, encounter a bug, or have an idea for new functionality — you're more than welcome to contribute!
+
+To get started, simply clone the [Mozaic-WebComponents repository](https://github.com/adeo/mozaic-web-components) and set up the development environment.  
+This guide will walk you through the process step by step.
+
+Need help? Don’t hesitate to reach out to us via our [Slack channel](https://adeo-tech-community.slack.com/archives/CN4K3A99R).
+
+---
+
+## 📄 Contribution Workflow Overview
+
+Here’s a visual summary of how contributing to Mozaic works:
+
+<Mermaid
+  chart={`flowchart TD;
+  A((You need something <br/>fix or new feature));
+  A --> B{Does an issue already exist?};
+  B --> |YES| I;
+  I([The issue fits my need <br/>or I complete it]);
+  I --> D;
+  B --> |NO| C;
+  C([Create a new issue]);
+  C --> D;
+  D{Can I contribute myself?};
+  D --> |YES| E;
+  D --> |NO| J;
+  E([Clone the repo <br/>& create a PR linked to the issue]);
+  E --> F;
+  F([Assign reviewers to your PR]);
+  F --> G;
+  G{Proofreading OK <br/>and PR validated?};
+  G --> |YES| H;
+  G --> |NO| K;
+  H([PR is merged & will be released]);
+  H;
+  J([Wait for issue to be handled <br/>by the core team]);
+  K([Make the requested changes]);
+  K --> F;
+  click B "https://github.com/adeo/mozaic-web-components/issues" _blank;
+  click C "https://github.com/adeo/mozaic-web-components/issues/new/choose" _blank;
+`}
+/>
+
+Let’s dive into each step in more detail 👇
+
+---
+
+## 🐞 Reporting Issues
+
+### 🔎 Check Existing Issues First
+
+We track all bugs and improvements in [GitHub Issues](https://github.com/adeo/mozaic-web-components/issues).  
+Before opening a new one, please make sure the problem hasn’t already been reported.
+
+Look through the list and see if there's an ongoing fix or discussion.
+
+### 📝 Creating a New Issue
+
+If your issue isn’t listed, go ahead and open a new one:  
+➡️ [Report a New Issue](https://github.com/adeo/mozaic-web-components/issues/new/choose)
+
+To help us resolve it efficiently:
+
+- Provide a **clear description**.
+- Include a **minimal reproducible example** if applicable.
+- Mention any relevant versions, context, or logs.
+
+---
+
+## 💡 Proposing Changes or New Features
+
+For **new components**, **major improvements**, or **non-trivial changes**, we strongly recommend first opening an issue to discuss your idea with the core team.
+
+This ensures:
+
+- Alignment with Mozaic’s vision.
+- Avoiding duplicate work.
+- Faster and smoother review once you submit your PR.
+
+For simple bug fixes, feel free to directly open a Pull Request, but linking an issue is always appreciated!
+
+---
+
+## 🛠️ Setting Up Your Dev Environment
+
+Follow these steps to get started contributing:
+
+```bash
+# Clone Mozaic-WebComponents repository
+git clone git@github.com:adeo/mozaic-web-components.git
+
+# Navigate to project directory
+cd mozaic-web-components
+
+# Checkout the branch you're working on (feature/fix/...)
+git checkout <branch-name>
+
+# Install dependencies
+npm install
+```

package/dist/documentation/Introduction.mdx

@@ -0,0 +1,66 @@
+import { Meta, Source } from '@storybook/addon-docs';
+
+import logo from '../../.storybook/logo.svg';
+
+<Meta title="Getting Started/Introduction" />
+
+<h1>
+  <img
+    src={logo}
+    alt="ADS logo"
+    style={{ height: '48px', marginRight: '8px', verticalAlign: 'middle' }}
+  />
+  <span style={{ fontSize: '32px' }}>Svelte x Web Component library</span>
+</h1>
+
+This project contains **Svelte** and **WebComponent** components that implements the **ADEO Design system** guidelines.
+
+## ✨ Introduction
+
+ADEO Design system is a global and collaborative design system
+that facilitates the designer and developer experience,
+enabling them to create universal interfaces
+perfectly aligned with the business strategy of Adeo.
+
+## 🚀 Ambition
+
+The ambition behind this library was to provide a set of **Web Components** to simplify the implementation of the **ADEO Design System** across various front-end architectures.
+
+To achieve this, we chose **Svelte** as the core framework, leveraging its ability to generate native **Custom Elements**. Compared to other solutions like **Lit** or **Stencil**, **Svelte** stood out due to its simplicity, ease of integration, and lightweight nature.
+
+If you're curious about the genesis of this library, check out our detailed article:  
+👉 **[ADEO Design System: Building a Web Component Library with Svelte and Rollup](https://medium.com/adeo-tech/adeo-design-system-building-a-web-component-library-with-svelte-and-rollup-72d65de50163)**.
+
+Given ADEO’s strong focus on e-commerce, the use of **Svelte** grew beyond initial expectations. As a result, the `@mozaic/web-components` package now provides both **Web Components** and native **Svelte Components**.
+
+This Storybook showcases primarily the **Web Components**.
+
+- For guidance on how to use the **Web Components**, refer to our **[Web Components documentation](/docs/web-components--docs)**.
+- For guidance on how to use the **Svelte components**, refer to our **[Svelte components documentation](/docs/svelte-components--docs)**.
+
+## 🧐 Svelte vs Web Components
+
+To help you choose between Svelte native component or Web Components you can follow this guidance:
+
+- Web Components → Ideal when working in multi-framework environments or if your architecture is not Svelte-based.
+- Svelte Components → Perfect for Svelte apps, with a native and seamless developer experience.
+
+## 🤝 Contributing
+
+Be part of something bigger!
+
+**Mozaic-WebComponent** is made possible by an incredible community that finds issues and creates pull requests.\
+It is our job to enable you to create amazing applications.
+
+To do so, see our **[contributing process](/docs/getting-started-contributing--docs)**.
+
+## ℹ️ Support
+
+If you have any questions or need assistance,\
+we are here to help.
+
+Whether you're troubleshooting, looking for documentation,\
+or need to get in touch with our team,\
+you'll find all the resources you need to get the most out of **Mozaic-WebComponent**.
+
+Visit our **[Support page](/docs/getting-started-support-onboarding--docs)** for more information.

package/dist/{stories/SupportAndOnboarding.stories.mdx → documentation/SupportAndOnboarding.mdx}

@@ -1,7 +1,7 @@
 import { Meta } from '@storybook/addon-docs';
 
 <Meta
-  title="Support & Onboarding"
+  title="Getting Started/Help & Support"
   parameters={{
     layout: 'fullscreen',
     viewMode: 'docs',
@@ -14,9 +14,9 @@ import { Meta } from '@storybook/addon-docs';
 <style>
   {`
   .mc-button--mdx {
-    color: #fff;
-  }
-`}
+      color: #fff;
+    }
+  `}
 </style>
 
 # Need help?
@@ -25,13 +25,16 @@ import { Meta } from '@storybook/addon-docs';
 
 Any feedback, ideas or questions?
 
-The **Mozaic Design System team** would welcome any feedback, ideas, or requirements that you have.<br/>
+The **ADEO Design System team** would welcome any feedback, ideas, or requirements that you have.<br/>
+
 Our goal is to make your lives easier.
 
 If you want to get more detailed information on the components or any other topic related to Mozaic web-components, you can contact us through the channels below.
 
 - Join the [#mozaic-web-component](https://adeo-tech-community.slack.com/archives/C021A2J25C4) channel on **Slack**
+
 - Join the [#mozaic-support](https://app.slack.com/client/T4R6RCZFA/CKQJZL7C4/) channel on **Slack**
+
 - Join our [Workplace group](https://adeo.workplace.com/groups/427492661454646/) **Mozaic Design System**
 
 ## Demo
@@ -41,10 +44,13 @@ Once a month, on the last Thursday of the month, the Design System team organise
 On the agenda:
 
 - Presentation of the main features on the library of the past month
+
 - Open discussion about your needs, feedbacks & requests
+
 - Technical discussion about the direction of the project.
 
 Want to be a part of it?! <br/>
+
 Nothing could be easier, you just have to add the **Demo - Mozaic-Web-Component** agenda to yours, by clicking on this link below:
 
 - Join our [Mozaic web components demo](https://calendar.google.com/calendar/u/1?cid=Y19jYmU2ZmFmM2NkODE1NGYyMzkyOTU3MzQyZDdhNjIyNmU2YmVhYjNlNjkwMTM1YjY4MDM0MDJlYTgzNTdhMzA0QGdyb3VwLmNhbGVuZGFyLmdvb2dsZS5jb20)
@@ -52,7 +58,9 @@ Nothing could be easier, you just have to add the **Demo - Mozaic-Web-Component*
 ## Onboarding Sessions
 
 Are you new to using a design system, and in particular Mozaic?<br/>
+
 Do you want to know more about how **Mozaic** works, and more specifically how to use Mozaic-web-components?<br/>
+
 You need a personalized support to install or configure your project?
 
 The **Mozaic Design System team** is at your disposal for that.

package/dist/documentation/Svelte/Introduction.mdx

@@ -0,0 +1,80 @@
+import { Meta } from '@storybook/blocks';
+
+<Meta title="Getting Started/Svelte/Introduction" />
+
+<style>
+  {`
+  .outlineCTA {
+    margin: 16px auto;
+    display: flex;
+    align-items: center;
+    gap: 4px;
+  }
+
+  .outlineCTA span {
+    font-size: 14px;
+  }
+
+  .ch-frame-buttons {
+    margin: 0 .8em !important;
+  }
+
+  .ch-frame-button {
+    font-size: 12px !important;
+  }
+  `}
+</style>
+
+# ✨ Getting Started
+
+**ADEO Design system** is a global and collaborative design system that facilitates the designer and developer experience, enabling them to create universal interfaces perfectly aligned with the business strategy of [Adeo](https://www.adeo.com/).
+
+Learn more about the vision and guidelines by visiting the [main documentation website](https://mozaic.adeo.cloud/).
+
+In addition to Web Components, **@mozaic-ds/web-components** package also exposes native **Svelte Components**, offering an even smoother developer experience when working within **Svelte-based applications**.
+
+## 🚀 Installation
+
+> **PREREQUISITES:**<br/>
+> Installing Mozaic packages require node v18+.<br/>
+> Installing Mozaic packages require Svelte 5.<br/>
+
+Install the Svelte components package:
+
+```bash
+npm install @mozaic-ds/web-components --save
+```
+
+Or with **Yarn**:
+
+```bash
+yarn add @mozaic-ds/web-components -E
+```
+
+## 📦 Usage
+
+You can import and use the Svelte components directly:
+
+Simply call the component as follows:
+
+<CH.Code>
+
+```svelte Svelte
+<script>
+  import { Button } from '@mozaic/web-components/svelte';
+</script>
+
+<Button appearance="accent">My first svelte Button</Button>
+```
+
+</CH.Code>
+
+## 🔥 Why Use Native Svelte Components?
+
+> Full compatibility with Svelte’s reactivity system.
+> Simpler syntax, no need to deal with custom element registration.
+> Easier to compose with other Svelte components.
+
+## 📚 Available Components
+
+Explore the list of available components in this Storybook, each with usage examples, props, and customization options.

package/dist/documentation/Svelte/usingIcons.mdx

@@ -0,0 +1,96 @@
+import { Meta } from '@storybook/blocks';
+import { Source } from '@storybook/addon-docs';
+
+<Meta title="Getting Started/Svelte/Icons Usage (Svelte)" />
+
+# 🖼️ Using Mozaic Icons in Svelte
+
+The **Mozaic Design System** provides a comprehensive set of brand-compliant icons, available as ready-to-use **Svelte components** via the `@mozaic-ds/icons-svelte` package.
+
+These icons are:
+
+- **Optimized**: Lightweight and scalable SVGs.
+- **Customizable**: Adjustable size, color, and accessibility attributes.
+- **Consistent**: Aligned with ADEO's design principles.
+
+---
+
+## 🚀 Installation
+
+To start using Mozaic icons:
+
+```bash
+npm install @mozaic-ds/icons-svelte
+```
+
+or
+
+```bash
+yarn add @mozaic-ds/icons-svelte
+```
+
+## 📦 Basic Usage
+
+Each icon is provided as an individual Svelte component.
+You can import and use them like this:
+
+```svelte
+<script>
+  import { More64 } from '@mozaic-ds/icons-svelte';
+</script>
+
+<More64 />
+```
+
+## 🧩 Icon Naming Convention Mozaic icons follow a simple and predictable naming
+
+convention:
+
+```
+[IconName][Size]
+```
+
+- IconName: Descriptive name in PascalCase (e.g., Search, Close, More)
+- Size: Default icon size, available as 16, 24, 32, 64
+
+## 📛 Examples:
+
+```svelte
+import {(Search24, Close16, More64, ArrowLeft32)} from '@mozaic-ds/icons-svelte';
+```
+
+## 📐 Available Sizes & Use Cases
+
+Here are the available icon sizes and typical contexts:
+
+```
+20px → Small buttons, labels, inline elements
+24px → Toolbars, navigation menus
+32px → Dialog headers, modals, primary buttons
+64px → Hero sections, illustrations, large displays
+
+```
+
+> 🎯 Tip: Always use the closest available size to your design needs to ensure sharp rendering.
+
+## 🎨 Customization Options
+
+Each icon component accepts standard SVG attributes:
+
+```svelte
+<Close16 width="16" height="16" fill="currentColor" aria-label="Close" />
+```
+
+- `width / height`: Control size
+- `fill`: Icon color (recommend using "currentColor")
+- `aria-label`: For accessibility
+
+## ⚙️ Best Practices
+
+- ✅ Use the appropriate size icon directly — no need to scale manually.
+- ✅ Inherit text color using fill="currentColor".
+
+## 📚 Useful Links
+
+- 📦 [@mozaic-ds/icons-svelte on NPM](https://www.npmjs.com/package/@mozaic-ds/icons-svelte)
+- 🛠️ [Mozaic Icons GitHub Repo](https://github.com/adeo/mozaic-icons-svelte)

package/dist/documentation/Svelte/usingPresets.mdx

@@ -0,0 +1,148 @@
+import { Meta } from '@storybook/blocks';
+import { Source } from '@storybook/addon-docs';
+
+<Meta title="Getting Started/Svelte/Using Presets" />
+
+# 🎨 ADEO Design System's Presets
+
+**ADEO Design System** is a **multi-brand design system** designed for maximum flexibility.<br/>
+It provides a set of **Svelte** using **tokens** that can be fully customized to adapt to each brand’s visual identity and guidelines.
+
+To make customization easier, **ADEO Design System** offers ready-to-use themes, also called **presets**, tailored for specific brands or internal contexts.
+
+Currently, ADEO Design System supports the following presets:
+
+- **Leroy Merlin preset**: Default preset applied when ADEO Design System is first installed.
+- **Adeo preset**: Targeted at internal interfaces and products of the **Adeo Group**.
+- **Mbrand preset**: Designed for the **Mbrand** brand's interfaces and products.
+- **Enki preset**: Designed for the **Enki** brand's interfaces and products.
+
+> ℹ️ **Note:**  
+> The process shown below is valid for all presets — simply replace `"adeo"` by the desired brand name (e.g., `"mbrand"` or `"enki"`).
+
+---
+
+## 🚀 Preset usage
+
+Before starting, ensure you’ve completed the installation of **ADEO Design System Web Components** and its related tokens, as described in the [Getting Started](?path=/docs/getting-started-svelte-introduction--docs) section.
+
+### 1️⃣ Load the preset
+
+To load a preset, simply import the corresponding Sass token package into your main stylesheet:
+
+```scss
+// Main stylesheet (e.g., styles.scss)
+@use '@mozaic-ds/tokens/theming';
+```
+
+Then, in the file of your choice (ideally the one containing the global styles for your project) you can call up the themes you want:
+
+```scss
+@use 'sass:meta';
+
+@include meta.load-css('@mozaic-ds/tokens/<presetName>/theme');
+```
+
+> **Replace `<presetName>` with:**
+>
+> - `adeo`
+> - `mbrand`
+> - `enki`
+>
+> **Note:** The `leroymerlin` preset is applied by default, so no need to explicitly import it unless overriding.
+
+> [!WARNING]
+> For the preset flip to work, you need to be able to place a CSS class on the page's HTML tag. The name of this class must be formatted as `preset-<presetName>`.
+
+Example for **Adeo**:
+
+```scss
+@use '@mozaic-ds/tokens/adeo' as *;
+```
+
+---
+
+### 2️⃣ Load the correct brand font
+
+Each brand not only has specific styles but also uses a dedicated font.
+
+| Brand        | Recommended Font | Link                                                                            |
+| ------------ | ---------------- | ------------------------------------------------------------------------------- |
+| Leroy Merlin | LeroyMerlinSans  | [View Details](https://mozaic.adeo.cloud/foundations/typography/font-families/) |
+| Adeo         | Roboto           | [Roboto on Google Fonts](https://fonts.google.com/specimen/Roboto)              |
+| Bricoman     | Inter            | [Inter on Google Fonts](https://fonts.google.com/specimen/Inter)                |
+
+To apply the correct font in your project:
+
+<CH.Code>
+
+```scss LeroyMerlin
+@use '@mozaic-ds/styles/tools/t.font' as *;
+@include import-font-lm();
+
+body {
+  @include set-font-family();
+}
+```
+
+```scss ADEO
+@use '@mozaic-ds/styles/tools/t.font' as *;
+@import url('https://fonts.googleapis.com/css2?family=Roboto:wght@400;500;700&display=swap')
+body {
+  @include set-font-family();
+}
+```
+
+```scss M-Brand
+@use '@mozaic-ds/styles/tools/t.font' as *;
+
+@import url('https://fonts.googleapis.com/css2?family=Inter:wght@400;600;700&display=swap');
+body {
+  @include set-font-family();
+}
+```
+
+</CH.Code>
+
+---
+
+#### 📝 Specific case: **Leroy Merlin font**
+
+For the **Leroy Merlin** preset, we recommend using the **LeroyMerlinSans** font, specifically designed for LM products.
+
+To include it in your project:
+
+1. Create a folder to store fonts (e.g., `static/assets/fonts`).
+2. Copy fonts from ADEO Design System’s dependency:
+
+```bash
+cp node_modules/@mozaic-ds/web-fonts/*.{woff,woff2} static/assets/fonts
+```
+
+Then, import and reference the fonts in your stylesheets as needed.
+
+---
+
+### 3️⃣ Using Components
+
+Once the preset and font are configured, you can directly start using ADEO Design System’s Web Components customized with your selected preset.
+
+Example:
+
+<CH.Code>
+
+```svelte
+<script>
+  import { Button } from '@mozaic/web-components/svelte';
+</script>
+
+<Button appearance="accent">Button label</Button>
+```
+
+</CH.Code>
+
+---
+
+## 📚 Going Further
+
+- Learn how to set up **Svelte** in detail in the [Svelte documentation](?path=/docs/getting-started-svelte-introduction--docs).

package/dist/documentation/WebComponents/Introduction.mdx

@@ -0,0 +1,56 @@
+import { Meta } from '@storybook/blocks';
+
+<Meta title="Getting Started/Web Components/Introduction" />
+
+# Getting Started
+
+**ADEO Design system** is a global and collaborative design system that facilitates the designer and developer experience, enabling them to create universal interfaces perfectly aligned with the business strategy of [Adeo](https://www.adeo.com/).
+
+Learn more about the vision and guidelines by visiting the [main documentation website](https://mozaic.adeo.cloud/).
+
+The Mozaic Web Component library provides a suite of **Web Components** built with **Svelte's custom element API**. These components allow you to integrate the **ADEO Design System** seamlessly, regardless of the front-end framework or stack you are using.
+
+## ✨ Installation
+
+> **PREREQUISITES:**<br/>
+> Installing Mozaic packages require node v18+.<br/>
+
+```bash
+npm install @mozaic-ds/web-components --save
+```
+
+Or with **Yarn**:
+
+```bash
+yarn add @mozaic-ds/web-components -E
+```
+
+## 📦 Usage
+
+Once installed, you can directly use the web components in your HTML or any front-end framework (React, Vue, Angular, etc.):
+
+Simply call the component as follows:
+
+<CH.Code>
+
+```html HTML
+<m-button appearance="accent">This is an accent button</m-button>
+```
+
+```js JS
+import '@mozaic/web-components/dist/lib';
+```
+
+</CH.Code>
+
+## 🔧 Framework Integration
+
+These web components are framework-agnostic. Here are a few resources to help you integrate them:
+
+- React Integration: Use the components directly in JSX (ensure to use className instead of class if needed).
+- Vue Integration: Register them globally or locally in your Vue app.[Official documentation](https://vuejs.org/guide/extras/web-components)
+- Angular Integration: Add CUSTOM_ELEMENTS_SCHEMA to your NgModule. [Official documentation](https://angular.dev/guide/components/advanced-configuration#custom-element-schemas)
+
+## 📚 More Information
+
+For advanced usage, customization options, and available components, check each component’s dedicated documentation in this Storybook.