@mozaic-ds/vue 2.19.2 → 2.20.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mozaic-ds/vue",
-  "version": "2.19.2",
+  "version": "2.20.0",
   "type": "module",
   "description": "Mozaic-Vue is the Vue.js implementation of ADEO Design system",
   "author": "ADEO - ADEO Design system",
@@ -43,7 +43,7 @@
     "*.d.ts"
   ],
   "dependencies": {
-    "@mozaic-ds/styles": "^2.23.0",
+    "@mozaic-ds/styles": "^2.26.0",
     "@mozaic-ds/web-fonts": "^1.65.0",
     "postcss-scss": "^4.0.9"
   },
@@ -98,6 +98,9 @@
     "vue-eslint-parser": "^10.1.1",
     "vue-tsc": "^3.1.8"
   },
+  "overrides": {
+    "undici": "^7.28.0"
+  },
   "sideEffects": false,
   "publishConfig": {
     "access": "public"

package/src/components/Catalog.scss

@@ -0,0 +1,84 @@
+#anchor--catalog--default,
+#import,
+#import-1,
+#stories,
+#stories-1,
+.import-description {
+  display: none;
+}
+
+.catalog-grid {
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  gap: 1rem;
+}
+
+@media (max-width: 56rem) {
+  .catalog-grid {
+    grid-template-columns: 1fr;
+  }
+}
+
+.catalog-card {
+  display: flex;
+  flex-direction: column;
+  gap: 0.75rem;
+  padding: 1rem;
+  border: 1px solid var(--color-border-default, #d7d9dd);
+  border-radius: 0.75rem;
+  background: var(--color-background-default, #fff);
+  box-shadow: 0 6px 18px rgba(0, 0, 0, 0.05);
+  overflow: hidden;
+  contain: layout paint;
+}
+
+.catalog-preview {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  height: 12rem;
+  padding: 0.75rem;
+  border-radius: 0.5rem;
+  background: linear-gradient(
+    135deg,
+    rgba(242, 244, 248, 0.9),
+    rgba(255, 255, 255, 0.95)
+  );
+  position: relative;
+  overflow: hidden;
+  isolation: isolate;
+  contain: layout paint;
+  transform: translateZ(0);
+}
+
+.catalog-preview > * {
+  max-width: 100%;
+  max-height: 100%;
+}
+
+.catalog-title {
+  margin: 0;
+  font-size: 1rem;
+  font-weight: 700;
+  color: var(--color-text-primary, #111827);
+}
+
+.catalog-description {
+  margin: 0;
+  color: var(--color-text-secondary, #4b5563);
+  font-size: 0.95rem;
+  line-height: 1.4;
+  display: -webkit-box;
+  -webkit-line-clamp: 3;
+  -webkit-box-orient: vertical;
+  overflow: hidden;
+}
+
+.catalog-link {
+  color: inherit;
+  text-decoration: none;
+}
+
+.catalog-link:hover {
+  text-decoration: underline;
+}

package/src/components/Catalog.stories.ts

@@ -0,0 +1,146 @@
+import type { Meta, StoryObj } from '@storybook/vue3-vite';
+import { defineComponent } from 'vue';
+import './Catalog.scss';
+
+type StoryModule = {
+  default?: {
+    title?: string;
+    args?: Record<string, unknown>;
+    parameters?: {
+      docs?: {
+        description?: {
+          component?: string;
+          story?: string;
+        };
+      };
+    };
+    render?: (...args: unknown[]) => unknown;
+  };
+  [key: string]: unknown;
+};
+
+const storyModules = import.meta.glob('../components/*/*.stories.ts', {
+  eager: true,
+}) as Record<string, StoryModule>;
+
+const humanizeComponentName = (value: string) =>
+  value
+    .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+    .replace(/[-_]+/g, ' ')
+    .replace(/\b\w/g, (char) => char.toUpperCase())
+    .trim();
+
+const slugify = (value: string) =>
+  value
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+
+const getStoryHref = (title: string) => `/?path=/docs/${slugify(title)}--docs`;
+
+const catalogStories = Object.entries(storyModules)
+  .filter(([, module]) => Boolean(module.default?.title))
+  .map(([filePath, module]) => {
+    const meta = module.default ?? {};
+    const storyName = Object.keys(module).find(
+      (name) => name !== 'default' && name !== '__esModule',
+    );
+    const story = storyName ? (module[storyName] as StoryModule) : undefined;
+    const render =
+      typeof story?.render === 'function'
+        ? story.render
+        : typeof meta.render === 'function'
+          ? meta.render
+          : undefined;
+    const args = {
+      ...(meta.args ?? {}),
+      ...(story?.args ?? {}),
+    };
+    const componentName =
+      filePath.split('/components/')[1]?.split('/')[0] ??
+      meta.title ??
+      'Component';
+    const rawTitle =
+      (meta.title ?? componentName).split('/').pop() ?? componentName;
+
+    return {
+      filePath,
+      title: humanizeComponentName(rawTitle),
+      description:
+        meta.parameters?.docs?.description?.component ??
+        meta.parameters?.docs?.description?.story ??
+        'Component documentation and examples.',
+      storyHref: getStoryHref(meta.title ?? componentName),
+      previewComponent:
+        render && typeof render === 'function'
+          ? defineComponent(render(args as never))
+          : undefined,
+    };
+  })
+  .sort((left, right) => left.title.localeCompare(right.title));
+
+const meta: Meta = {
+  title: 'Catalog',
+  parameters: {
+    controls: {
+      disable: true,
+    },
+    docs: {
+      controls: {
+        disable: true,
+      },
+      description: {
+        component: 'A live catalog of the library components.',
+      },
+      toc: false,
+      canvas: { sourceState: 'none' },
+    },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj;
+
+export const Default: Story = {
+  render: () => ({
+    setup() {
+      return { catalogStories };
+    },
+    template: `
+      <section
+        class="catalog-grid"
+      >
+        <article
+          v-for="entry in catalogStories"
+          :key="entry.filePath"
+          class="catalog-card"
+        >
+          <div
+            class="catalog-preview"
+          >
+            <component :is="entry.previewComponent" v-if="entry.previewComponent" />
+            <span v-else>{{ entry.title }}</span>
+          </div>
+          <h3
+            class="catalog-title"
+          >
+            <a class="catalog-link" :href="entry.storyHref">{{ entry.title }}</a>
+          </h3>
+          <p
+            class="catalog-description"
+          >
+            {{ entry.description }}
+          </p>
+        </article>
+      </section>
+    `,
+  }),
+  parameters: {
+    docs: {
+      canvas: {
+        withToolbar: false,
+      },
+    },
+  },
+};

package/src/components/GettingStarted.mdx

@@ -6,7 +6,7 @@ import { Meta, Source } from '@storybook/addon-docs/blocks';
 
 **Mozaic-Vue** is the [Vue.js](https://vuejs.org/) implementation of ADEO Design system.
 
-## 📦 Installation
+### 📦 Installation
 
 In order to use **Mozaic-Vue** in your **Vue.js** project, you must first install the [npm package](https://www.npmjs.com/package/@mozaic-ds/vue):
 
@@ -16,7 +16,7 @@ Or with **Yarn**:
 
 <Source language="bash" dark code="yarn add @mozaic-ds/vue" />
 
-## 📝 Usage
+### 📝 Usage
 
 Import the styles
 
@@ -43,3 +43,259 @@ To import and use a component, you can proceed as follows:
   <MButton>Button Label</MButton>
 </template>
 `} />
+
+### 🎨 Brand Presets
+
+**Mozaic** is a **multi-brand** design system.<br/>
+This means that it is fully customisable so that its constituent elements _(foundations, components, etc.)_ can be adapted to the graphic charter of the brand that uses it.
+
+To simplify this aspect of customising **Mozaic** for you, we have created themes _(which we also call **"presets"**)_ ready to use according to your context of use.
+
+Currently **Mozaic** can be customized with the following presets:
+
+- Preset **Leroy Merlin**: this is the default preset/theme configured when **Mozaic** was first installed
+- Preset **Adeo**: dedicated to the **Adeo Group's** internal interfaces and products
+- Preset **Bricoman**: dedicated to the interfaces and products of the **Bricoman** brand
+
+The rest of this documentation shows you how to use/install the Adeo preset in your project.
+
+> Note that the procedure remains the same for all other presets.<br/> You just need to replace all references to "Adeo" with the brand name of your choice.
+
+#### Using the Adeo's preset
+
+Before anything else, make sure you have followed the **Mozaic-Vue** installation procedure as described in the [Getting Started](?path=/docs/getting-started--docs) page.
+
+Once **Mozaic-Vue** is installed as shown, we can make the following changes:
+
+#### Loading preset
+
+All it has to do is insert the following code into its main Sass file (entrypoint stylesheet):
+
+<Source
+  language="css"
+  dark
+  code={`
+// Entrypoint stylesheet
+@use "@mozaic-ds/tokens/<presetName>/theme" as *;
+`}
+/>
+
+> [!NOTE]
+> The `<presetName>` string should be replaced by the name of the preset you want, one of the following values: `adeo | mbrand`.
+> As the `leroymerlin` preset is the default preset, you don't need to use this syntax to use it.
+
+For example, for ADEO
+
+<Source
+  language="css"
+  dark
+  code={`
+// Entrypoint stylesheet
+@use "@mozaic-ds/tokens/adeo/theme" as *;
+`}
+/>
+
+#### Font by brand
+
+Each brand is distinguished not only by different styles but also by a different font.
+
+The table below summarises which font to use depending on the brand.
+
+<table>
+  <tr>
+    <td>Brand</td>
+    <td>Font</td>
+  </tr>
+  <tr>
+    <td>Leroy Merlin</td>
+    <td>
+      [LeroyMerlinSans](https://mozaic.adeo.cloud/foundations/typography/font-families/)
+    </td>
+  </tr>
+  <tr>
+    <td>Adeo</td>
+    <td>[Roboto](https://fonts.google.com/specimen/Roboto)</td>
+  </tr>
+  <tr>
+    <td>Bricoman</td>
+    <td>[Inter](https://fonts.google.com/specimen/Inter)</td>
+  </tr>
+</table>
+
+For example, here is how to include the Roboto font in your HTML for the Adeo brand:
+
+<Source
+  language="html"
+  dark
+  code={`
+<head>
+    <meta charset="UTF-8" />
+    <link rel="preconnect" href="https://fonts.googleapis.com" />
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+    <link
+      href="https://fonts.googleapis.com/css2?family=Roboto:ital,wght@0,100..900;1,100..900&display=swap"
+      rel="stylesheet"
+    />
+  </head>
+`}
+/>
+
+From there, we can update the main style sheet of your project, in order to import the right font.
+
+<Source
+  language='css'
+  dark
+  code={`
+@use '@mozaic-ds/tokens/adeo/theme' as *;
+
+body {
+font-family: var(--font-family, 'Roboto', sans-serif);
+}
+`} />
+
+Specific for LM fonts
+
+> This section describes the use of fonts for the **Leroy Merlin** preset, but if you are using another preset, please see [the associated documentation](?path=/docs/using-presets--docs).
+
+The theme defined by default when **Mozaic-Vue** is first installed/used is the theme corresponding to the **Leroy Merlin** charter.
+
+For any use of the **Leroy Merlin** theme, it is recommended to use the font [LeroyMerlinSans](/typography/font-families/) which has been specially designed for **Leroy Merlin** products.
+
+To use the `LeroyMerlinSans` font in your project, you must copy it into your project so that it is present in your `assets`.
+
+You can do this as follows:
+
+1. Create a folder in your project where you can save the fonts, for example: `static/assets/fonts`
+
+2. Copy fonts from Mozaic dependencies:
+
+<Source
+  language="bash"
+  dark
+  code="cp node_modules/@mozaic-ds/web-fonts/*.{woff,woff2} static/assets/fonts"
+/>
+
+#### Usage
+
+At this stage, the integration of the **Mozaic-Vue** components should normally be customised with the preset values.
+
+All that remains is to use the components as usual:
+
+<Source
+  language="html"
+  dark
+  code='<MButton label="This is a Mozaic Button" />'
+/>
+
+### 🌑 Dark Mode
+
+A concise guide explaining **how dark mode works** with your CSS variables and **how to use it** in Storybook.
+
+---
+
+## What dark mode is (high‑level)
+
+Dark mode is implemented with **two sets of CSS variables** (tokens):
+
+- **Light** values live under `:root`.
+- **Dark** values override under `:root[data-theme="dark"]`.
+
+Components only reference tokens with `var(--token-name)` — switching theme is just toggling the `data-theme` attribute (no component code changes).
+
+---
+
+#### Token structure (SCSS → CSS)
+
+Your presets export SCSS like this:
+
+<Source 
+  language="scss" 
+  dark 
+  code={`
+  $root-selector: ':root' !default;
+$dark-selector: '[data-theme="dark"]' !default;
+
+#{$root-selector} {
+/_ Light tokens _/
+--color-background-primary: #ffffff;
+--color-text-primary: #000000;
+/_ … all your light variables … _/
+}
+
+#{$root-selector}#{$dark-selector} {
+/_ Dark tokens _/
+--color-background-primary: #191919;
+--color-text-primary: #d9d9d9;
+/_ … all your dark variables … _/
+}
+`}
+/>
+
+After compilation, this becomes standard CSS:
+
+<Source
+  language="css"
+  dark
+  code={`
+    :root {
+      /* light tokens */
+    }
+    :root[data-theme='dark'] {
+      /* dark tokens */
+    }
+  `}
+/>
+
+> If you can’t (or don’t want to) target `:root`, you can pass a different `$root-selector` when building your theme and apply `data-theme="dark"` on that container instead.
+
+---
+
+#### Using tokens inside components
+
+To enable the dark mode you have to ensure to:
+
+- Add the `data-theme` attribute in your root element with the value `dark`,
+- Use variables — never hard‑code colors or sizes
+
+```html
+<div class="root" data-theme="dark">…</div>
+```
+
+<Source 
+  language="sass" 
+  dark 
+  code={`
+    @use "@mozaic-ds/tokens" as *;
+
+    .mc-component: {
+      background-color: $--color-background-primary;
+    }
+
+`}
+/>
+
+When the theme changes, these values update automatically via CSS.
+
+---
+
+#### Accessibility & good practices
+
+- Aim for **WCAG AA** contrast at minimum; verify text vs. background pairs.
+- Prefer **semantic tokens** (`--button-color-…`, `--color-text-…`) over raw color hexes.
+- Keep all component styles expressed in tokens so the **theme switch has zero component logic**.
+
+---
+
+#### Troubleshooting
+
+- **Dark toggle does nothing** → Ensure the tokens were imported **before** component styles and that `data-theme="dark"` is set on the same selector the tokens target (usually `:root`).
+- **Weird colors** → Search for hard‑coded values and replace them with tokens.
+- **Variables undefined** → Check your build order and that the SCSS was compiled to CSS and loaded by Storybook.
+
+---
+
+#### Summary
+
+- Light tokens on `:root`, dark overrides on `:root[data-theme="dark"]`.
+- Components read tokens with `var(--$token-name)` — no runtime branching required.
+