@agregio-solutions/design-system 1.102.5 → 2.0.0

package/dist/public_docs/migration-guide-v2.md

@@ -0,0 +1,444 @@
+---
+title: Agregio Solutions Design System — V2 migration guide
+description: Breaking changes shipped in the V2 release of the Design System, and how to adapt your codebase.
+---
+
+# V2 migration guide
+
+Breaking changes of the V2 release. Last V1 version published: `v1.102.6`.
+
+## Install
+
+Install V2 together with its new peer dependencies, in a single command:
+
+```sh
+npm install @agregio-solutions/design-system@^2 @tanstack/react-table@^9 react-aria-components@^1.21.0
+npm install --save-dev @react-aria/optimize-locales-plugin
+```
+
+Installed one at a time, npm goes through an intermediate state where the
+Design System and `@tanstack/react-table` disagree on the major (V1 requires
+`^8`, V2 requires `^9`) and stops with `ERESOLVE`.
+
+If npm still stops with `ERESOLVE`, another package of your project requires
+`@tanstack/react-table@^8` or an incompatible `react-aria-components`. Run
+`npm explain @tanstack/react-table` to find it, and upgrade it. Do not bypass
+the error with `--legacy-peer-deps` (it removes the peer dependencies npm
+installed for your other packages, such as `react-is` for `recharts`) nor with
+`--force`.
+
+## Prompt to migrate with an LLM
+
+Paste this prompt into your coding agent (Claude Code, Cursor, Copilot…) from
+the root of your project, once the V2 package is installed. It points to this
+guide inside `node_modules`, so the agent reads the version you installed.
+
+```text
+Migrate this codebase from V1 to V2 of @agregio-solutions/design-system.
+
+Source of truth: node_modules/@agregio-solutions/design-system/dist/public_docs/migration-guide-v2.md
+Read it in full before changing anything. Each section describes a breaking
+change with "What changes", "Why" and "How to adapt": apply "How to adapt"
+exactly, do not invent another migration. The component API docs are in
+node_modules/@agregio-solutions/design-system/dist/packages/components/*/doc.md.
+
+1. Check that node_modules/@agregio-solutions/design-system/package.json has a
+   version >= 2.0.0. Otherwise stop and tell me.
+2. For each section of the guide, search the codebase for the affected APIs
+   (imports, props, types, tests, CSS) and list the files concerned. Skip the
+   sections that match nothing.
+3. Install the new peer dependencies the guide requires and register the React
+   Aria locales plugin in the bundler config.
+4. Apply the migration section by section. For @tanstack/react-table v9, follow
+   the skills shipped in node_modules/@tanstack/{table-core,react-table}/skills/,
+   starting with migrate-v8-to-v9/SKILL.md, not the TanStack website.
+5. Also replace the deprecated NavigationItem isActive with currentPath on
+   Navigation.
+6. Run the type check, the linter and the tests, and fix every failure caused
+   by the migration. Never silence an error with a cast, a ts-ignore or a
+   skipped test.
+7. Report: the changes made per section, what you could not migrate and why,
+   and the visual changes I must check by hand (helperText position, Drawer
+   layout, CSS that targeted the Button span).
+```
+
+## `react-table` v9 required
+
+**What changes** — the optional peer dependency `@tanstack/react-table` moves from
+`^8.0.0` to `^9.0.0`. `DataTable` and `Filter` now take a `useTable` instance, and
+their generics gained a leading `TFeatures`: `TypeTableColumnWithFilter<TData>`
+becomes `TypeTableColumnWithFilter<typeof features, TData>`.
+
+**Why** — v9 is a full rewrite of TanStack Table. Its types carry the registered
+feature set, so the Design System cannot type a table against both majors.
+
+**How to adapt** — upgrade to `@tanstack/react-table@9`, then follow the v8-to-v9
+skill shipped with the package (see below): replace `useReactTable` with
+`useTable`, register every feature you use in `tableFeatures()` (including the
+row models, which are no longer table options), read state through
+`table.state` instead of `table.getState()`, and type your column helper with
+`createColumnHelper<typeof features, TData>()`. Never pass a row, cell or column
+method as a bare callback (`onChange={column.setFilterValue}`) —
+v9 methods live on prototypes and lose their instance; wrap them
+(`onChange={(value) => column.setFilterValue(value)}`). The `DataTable` and `Filter`
+stories in Storybook are migrated and can be copy-pasted.
+
+**Where to look** — `@tanstack/react-table@9` ships 30 agent skills inside
+`node_modules/@tanstack/{table-core,react-table}/skills/`, versioned with the
+package. Start with `table-core/skills/migrate-v8-to-v9/SKILL.md`, then the
+per-topic ones (`table-features`, `typescript`, `column-filtering`,
+`global-filtering`, `pagination`, `expanding`, `table-state`,
+`api-not-found`...). Prefer them over the TanStack website, which documents the
+`alpha` branch and describes APIs that do not exist in the released v9.
+
+**Also worth knowing** — four v9 details that bite once the migration compiles:
+
+- `useTable` takes an optional state selector as its second argument, and
+  `table.state` then holds only the selected slices. `DataTable` and `Filter`
+  read `columnFilters` and `globalFilter` from it, so call `useTable` without a
+  selector (TypeScript rejects a narrowed table anyway). Use `table.Subscribe`
+  lower in your own tree when you need finer subscriptions.
+- Type each column `meta` with `satisfies TypeTableColumnWithFilter<typeof features, TData>`,
+  as in V1 with the new leading generic:
+  `meta: { FilterInDrawer: ({ column }) => …, filterChips: … } satisfies TypeTableColumnWithFilter<typeof features, User>`.
+  It type-checks the meta keys and types `column` inside `FilterInDrawer` and
+  `filterChips`. The new per-table `columnMeta` slot cannot carry this type,
+  because it needs `typeof features` and would reference the features object
+  inside its own initializer.
+- In your own cell components, a state read hidden behind a method
+  (`row.getIsSelected()`) can be missed by the React Compiler. Wrap it in
+  `Subscribe` or receive the value as a prop.
+- Prefer the `FlexRender` component over the `flexRender` function:
+  `<table.FlexRender cell={cell} />`.
+
+## MUI support removed
+
+**What changes** — `createMuiTheme` is no longer exported. The MUI theme, the MUI
+example stories and the MUI migration guides are gone from Storybook. MUI is no
+longer supported in any form.
+
+**Why** — no Design System component uses MUI. The theme bundled `@mui/system`
+into the package for every consumer and forced `@mui/material` to be installed
+just to resolve the types.
+
+**How to adapt** — remove MUI from your project and use the Design System
+components (`Button`, `Badge`, `Checkbox`, `Select`, `Slider`, `Tabs`,
+`TextInput`, `Link`, `Breadcrumbs`, `Drawer`, `Modal`, `Radio`, `Switch`,
+`Icon`, etc). Style everything with the Design System CSS variables.
+
+## `fontSize` and `lineHeight` exports removed
+
+**What changes** — the `fontSize` and `lineHeight` objects are no longer
+exported. Use the CSS variables `--text-font-size-*` and
+`--text-line-height-*` instead, on the `xs` to `3xl` scale. The values are
+unchanged.
+
+**Why** — the same sizes were exposed twice, under two naming scales
+(`xxSmall`…`xxLarge` in JS, `xs`…`3xl` in CSS). A single scale, the CSS
+variables, removes the ambiguity.
+
+**How to adapt** — replace each key with the CSS variable given in the table
+below.
+
+| Before (`fontSize` / `lineHeight`) | Value (font-size / line-height) | After (CSS variable suffix) |
+| ---------------------------------- | ------------------------------- | --------------------------- |
+| `xxSmall`                          | 12px / 16px                     | `xs`                        |
+| `extraSmall`                       | 14px / 20px                     | `sm`                        |
+| `small`                            | 16px / 24px                     | `md`                        |
+| `medium`                           | 20px / 28px                     | `lg`                        |
+| `large`                            | 24px / 32px                     | `xl`                        |
+| `extraLarge`                       | 32px / 40px                     | `2xl`                       |
+| `xxLarge`                          | 40px / 56px                     | `3xl`                       |
+
+For example, `font-size: ${fontSize.small}; line-height: ${lineHeight.small};`
+becomes `font-size: var(--text-font-size-md); line-height: var(--text-line-height-md);`.
+
+## `react-aria-components` is now a required peer dependency
+
+**What changes** — `react-aria-components` is no longer bundled into the Design
+System nor installed with it. It moves to `peerDependencies` (`^1.21.0`): your
+project must install it.
+
+**Why** — the Design System shipped its own inlined copy of React Aria (about
+40% of the package), next to the one npm installed anyway. Two copies mean two
+sets of React contexts: an `I18nProvider` or `RouterProvider` imported from
+`react-aria-components` in your app did not reach the Design System components.
+With a single copy, they do, and you can pick up React Aria fixes without
+waiting for a Design System release.
+
+**How to adapt** — install the package and the locales plugin (already done if
+you followed [Install](#install)):
+
+```sh
+npm install react-aria-components@^1.21.0
+npm install --save-dev @react-aria/optimize-locales-plugin
+```
+
+Then register the plugin in your bundler, with the
+locales your app supports. React Aria imports the strings of its 34 locales
+statically. The Design System used to strip them at build time. It no longer
+can, and without the plugin your bundle grows by about 180 kB minified
+(40 kB gzipped).
+
+```ts
+// vite.config.ts
+import optimizeLocales from "@react-aria/optimize-locales-plugin";
+
+export default defineConfig({
+  plugins: [
+    // ...
+    optimizeLocales.vite({ locales: ["fr-FR", "en-US"] }),
+  ],
+});
+```
+
+```js
+// next.config.js
+const optimizeLocales = require("@react-aria/optimize-locales-plugin");
+
+module.exports = {
+  webpack(config) {
+    config.plugins.push(
+      optimizeLocales.webpack({ locales: ["fr-FR", "en-US"] }),
+    );
+    return config;
+  },
+};
+```
+
+`I18nProvider` stays exported by the Design System. Importing it from the
+Design System or from `react-aria-components` is now equivalent.
+
+## Deprecated props removed
+
+Props marked `@deprecated` in V1 are removed. TypeScript reports every
+remaining usage once you upgrade, including props passed through a spread or a
+local wrapper component.
+
+### `Tab`: `hasNotification`
+
+**What changes** — the `hasNotification` prop is removed.
+
+**Why** — `badgeProps` replaced it. It renders the same dot and also supports
+every other `Badge` variant.
+
+**How to adapt** — replace `hasNotification` with the equivalent badge:
+
+```tsx
+// Before
+<Tab id="inbox" hasNotification>Inbox</Tab>
+
+// After
+<Tab id="inbox" badgeProps={{ variant: "dot", nature: "negative" }}>
+  Inbox
+</Tab>
+```
+
+### `Dropdown`: `items`
+
+**What changes** — the `items` prop is removed. Items are passed as
+`DropdownListItem` children only.
+
+**Why** — the two APIs did the same thing. Only composition lets you set a
+`ref`, a custom `key` or wrap an item.
+
+**How to adapt** — map your array to `DropdownListItem` children. The item
+props are unchanged:
+
+```tsx
+// Before
+<Dropdown items={items} />
+
+// After
+<Dropdown>
+  {items.map((item) => (
+    <DropdownListItem key={item.text} {...item} />
+  ))}
+</Dropdown>
+```
+
+### `DataTableRow`: `depth`
+
+**What changes** — the `depth` prop is removed.
+
+**Why** — it no longer had any effect: `DataTable` styles sub-rows itself.
+
+**How to adapt** — delete the prop. Nothing else changes.
+
+```tsx
+// Before
+<DataTableRow depth={row.depth}>{cells}</DataTableRow>
+
+// After
+<DataTableRow>{cells}</DataTableRow>
+```
+
+## `description` removed from form fields, use `helperText`
+
+**What changes** — the `description` prop is removed from `TextInput`,
+`Select`, `Combobox`, `DatePicker`, `DateRangePicker`, `TimeField`,
+`YearMonthPicker`, `Slider` and from the `formGroupWrapperProps` of
+`FileUpload`.
+
+**Why** — `description` and `helperText` displayed the same text, with the
+same size and color, under the field. `helperText` also takes an icon
+(`helperTextIcon`) and places the character counter like the other helper
+texts. `Slider` flagged `helperText` as deprecated in favor of `description`.
+That flag was a mistake: `helperText` stays and is no longer deprecated.
+
+**How to adapt** — rename `description` to `helperText`:
+
+```tsx
+// Before
+<TextInput label="Email" description="We never share it" />
+
+// After
+<TextInput label="Email" helperText="We never share it" />
+```
+
+Two visual differences to check:
+
+- `helperText` is displayed after the error, success and warning messages,
+  while `description` sat right under the field.
+- With `orientation="horizontal"`, `helperText` goes under the label and field
+  row, while `description` was placed inside it.
+
+If a field already had both props, merge the two texts into `helperText`.
+
+## `Drawer` actions are composed, like `Modal`
+
+**What changes** — `Drawer` loses `primaryLabel`, `onPrimaryClick`,
+`secondaryLabel`, `onSecondaryClick` and `customActionsBar`. It now renders its
+`children` right under the title, as `Modal` does. Three new exports build the
+body and the footer: `DrawerContent` (padded, scrollable body), `DrawerActions`
+(bottom action bar) and `DrawerForm` (a `<form>` wrapping both).
+
+**Why** — `Modal` and `Drawer` had two different APIs for the same layout. The
+action props could not set `isLoading`, `isDisabled` or an icon, which is why
+`customActionsBar` existed. The footer sat outside any form: submitting needed
+`form="some-id"` on the button, or `onPrimaryClick={handleSubmit(onSubmit)}`,
+which ignores the Enter key. The footer was also rendered, border included,
+when a drawer had no action.
+
+**How to adapt** — wrap the content in `DrawerContent` and move the buttons to
+`DrawerActions`, secondary first, then primary. Without `DrawerContent` the
+content loses its padding and its scroll.
+
+```tsx
+// Before
+<Drawer
+  isOpen={isOpen}
+  onOpenChange={setIsOpen}
+  title="Filters"
+  primaryLabel="Apply"
+  onPrimaryClick={apply}
+  secondaryLabel="Reset"
+  onSecondaryClick={reset}
+>
+  {filters}
+</Drawer>
+
+// After
+<Drawer isOpen={isOpen} onOpenChange={setIsOpen} title="Filters">
+  <DrawerContent>{filters}</DrawerContent>
+  <DrawerActions>
+    <Button text="Reset" mode="secondary" onClick={reset} />
+    <Button text="Apply" onClick={apply} />
+  </DrawerActions>
+</Drawer>
+```
+
+A `customActionsBar` becomes the content of `DrawerActions`, unchanged.
+
+For a form, replace the `form="some-id"` link (or `onPrimaryClick={handleSubmit(onSubmit)}`)
+with `DrawerForm`, which wraps both the fields and the buttons. The submit button
+takes `type="submit"`, and Enter in a field submits the form:
+
+```tsx
+// Before
+<Drawer
+  {...drawerProps}
+  customActionsBar={
+    <>
+      <Button text="Cancel" mode="secondary" onClick={close} />
+      <Button text="Save" type="submit" form="user-form" />
+    </>
+  }
+>
+  <form id="user-form" onSubmit={handleSubmit(onSubmit)}>
+    {fields}
+  </form>
+</Drawer>
+
+// After
+<Drawer {...drawerProps}>
+  <DrawerForm onSubmit={handleSubmit(onSubmit)}>
+    <DrawerContent>{fields}</DrawerContent>
+    <DrawerActions>
+      <Button text="Cancel" mode="secondary" onClick={close} />
+      <Button text="Save" type="submit" />
+    </DrawerActions>
+  </DrawerForm>
+</Drawer>
+```
+
+Put `DrawerForm` in a child component that calls `useForm`, as in the `Drawer`
+story "Example with a form": the form state is then reset each time the drawer
+opens. `Modal` works the same way with `ModalContent`, `ModalActions` and
+`ModalForm`.
+
+## `Button` text is no longer wrapped in a `<span>`
+
+**What changes** — the `Button` text is rendered directly inside the `<button>`
+(or the `<a>` when `href` is set), without the `<span>` that used to wrap it.
+
+**Why** — `getByText("Save")` returned the `<span>`, so assertions on the
+button itself (`toBeDisabled`, `toHaveAttribute("aria-disabled")`, …) failed.
+It now returns the button.
+
+**How to adapt** — in tests, drop the hop from the text to its parent:
+
+```tsx
+// Before
+expect(screen.getByText("Save").parentElement).toBeDisabled();
+
+// After
+expect(screen.getByText("Save")).toBeDisabled();
+```
+
+`.closest("button")` and `.closest("a")` keep working, as they match the
+element itself. CSS targeting the `span` inside a `Button` no longer applies.
+
+## `NavigationItem`: `isActive` deprecated, use `currentPath`
+
+**What changes** — `isActive` on `NavigationItem` and on its `subLinks` is
+deprecated and will be removed in V3. It still works in V2.
+
+**Why** — every app computed it from the router path, most of them copying the
+rule `Navigation` already applies with `currentPath`: an item is active when
+the path starts with its `href` (`/` is matched exactly), a dropdown when one
+of its sub links is. A dropdown also opens by itself when one of its sub links
+becomes active.
+
+**How to adapt** — pass the router path to `Navigation` and delete `isActive`:
+
+```tsx
+// Before
+<Navigation logo="agregio">
+  <NavigationItem
+    label="Offers"
+    iconLeft="sell"
+    href="/offers"
+    isActive={location.pathname.startsWith("/offers")}
+  />
+</Navigation>
+
+// After
+<Navigation logo="agregio" currentPath={location.pathname}>
+  <NavigationItem label="Offers" iconLeft="sell" href="/offers" />
+</Navigation>
+```
+
+For a section with tabs, point the `href` at the section root (e.g.
+`/offers`, redirected by the router to the default tab) rather than at one tab:
+the item then stays active on every tab.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agregio-solutions/design-system",
-  "version": "1.102.5",
+  "version": "2.0.0",
   "description": "React Component library and Storybook that is part of the Design System for Agregio Solutions",
   "type": "module",
   "module": "dist/design-system.js",
@@ -38,12 +38,8 @@
     "vitest:watch": "vitest --project unit"
   },
   "devDependencies": {
-    "@emotion/react": "11.14.0",
-    "@emotion/styled": "11.14.1",
     "@eslint/compat": "2.1.1",
     "@eslint/js": "9.39.5",
-    "@mui/material": "5.18.0",
-    "@react-aria/optimize-locales-plugin": "2.0.2",
     "@semantic-release/gitlab": "13.3.3",
     "@semantic-release/npm": "13.1.5",
     "@storybook/addon-a11y": "10.6.0",
@@ -52,7 +48,7 @@
     "@storybook/addon-vitest": "10.6.0",
     "@storybook/react-vite": "10.6.0",
     "@tanstack/react-query": "5.102.8",
-    "@tanstack/react-table": "8.21.3",
+    "@tanstack/react-table": "9.2.4",
     "@types/lodash": "4.17.25",
     "@types/node": "24.13.4",
     "@types/react": "19.3.0",
@@ -76,6 +72,7 @@
     "playwright": "1.63.0",
     "prettier": "3.9.6",
     "react": "19.3.0",
+    "react-aria-components": "1.21.1",
     "react-dom": "19.3.0",
     "react-hook-form": "7.88.0",
     "react-router-dom": "7.18.3",
@@ -90,15 +87,16 @@
     "vitest": "4.1.11"
   },
   "dependencies": {
+    "@internationalized/date": "^3.12.4",
     "clsx": "2.1.1",
     "normalize.css": "8.0.1",
-    "react-aria-components": "1.21.1",
     "sonner": "2.0.8",
     "styled-components": "6.5.3"
   },
   "peerDependencies": {
-    "@tanstack/react-table": "^8.0.0",
+    "@tanstack/react-table": "^9.0.0",
     "react": "^18.0.0 || ^19.0.0",
+    "react-aria-components": "^1.21.0",
     "react-dom": "^18.0.0 || ^19.0.0"
   },
   "peerDependenciesMeta": {

package/dist/packages/ds-design-tokens/src/fontSize.style.d.ts

@@ -1,60 +0,0 @@
-export declare const fontSize: {
-    /**
-     * 12px
-     */
-    xxSmall: string;
-    /**
-     * 14px
-     */
-    extraSmall: string;
-    /**
-     * 16px
-     */
-    small: string;
-    /**
-     * 20px
-     */
-    medium: string;
-    /**
-     * 24px
-     */
-    large: string;
-    /**
-     * 32px
-     */
-    extraLarge: string;
-    /**
-     * 40px
-     */
-    xxLarge: string;
-};
-export declare const lineHeight: {
-    /**
-     * 16px
-     */
-    xxSmall: string;
-    /**
-     * 20px
-     */
-    extraSmall: string;
-    /**
-     * 24px
-     */
-    small: string;
-    /**
-     * 28px
-     */
-    medium: string;
-    /**
-     * 32px
-     */
-    large: string;
-    /**
-     * 40px
-     */
-    extraLarge: string;
-    /**
-     * 56px
-     */
-    xxLarge: string;
-};

package/dist/packages/mui/mui-theme.d.ts

@@ -1,3 +0,0 @@
-import { ThemeOptions } from '@mui/material/styles';
-export default function createMuiTheme(options?: ThemeOptions): ThemeOptions;
-export declare const BASE_MUI_THEME: ThemeOptions;