@maz-ui/upgrade 5.0.0-canary.ef64a02.0 → 5.1.0-beta.0

package/README.md

@@ -5,10 +5,10 @@ Automated source rewrites for migrating a project from **Maz-UI v4** to **v5**.
 Run it once at the start of your migration to clear the mechanical changes
 from your todo list, then walk through the rest of the
 [migration guide](https://maz-ui.com/guide/migration-v5) for the items that
-need a human eye (theme `foundation.radius` reshape, `MazIcon` API,
-`MazBadge` numeric sizes, `MazChart` `update-mode`).
+need a human eye (theme `foundation.radius` reshape, bound `MazIcon` values,
+`MazBadge` `px` / `em` sizes, `MazChart` `update-mode`).
 
-The companion [`@maz-ui/mcp`](https://maz-ui.com/guide/mcp) server lets your
+The companion [`@maz-ui/mcp`](https://maz-ui.com/ecosystem/mcp) server lets your
 AI assistant read the migration guide and apply the manual steps with full
 context.
 
@@ -96,7 +96,7 @@ The CLI walks every file matching one of these extensions inside the
 provided paths:
 
 - **Vue:** `.vue`
-- **CSS:** `.css`
+- **Stylesheets:** `.css`, `.scss`, `.sass`, `.less`, `.styl`, `.stylus`, `.pcss`, `.postcss`
 - **TypeScript:** `.ts`, `.tsx`, `.cts`, `.mts`
 - **JavaScript:** `.js`, `.jsx`, `.cjs`, `.mjs`
 - **Manifest:** every `package.json` (root + nested in monorepo workspaces)
@@ -124,50 +124,106 @@ outside both lists, add them to a local `.gitignore` (or to a sibling
 ## Transform groups
 
 By default all five groups run. Use `--only=<a,b,...>` to scope the run.
-Each group is independent and idempotent: re-running the tool on
-already-migrated code is a no-op.
+Each group is independent. Re-running the tool on already-migrated code is a
+no-op, except for the `MazAvatar` size rewrite (a unit value can not be told
+apart from an already multiplied one): run it once, on v4 code.
 
 ### `imports`
 
-CSS subpath rename, applied to imports in `.vue` and JS/TS files:
+CSS subpath renames, applied to imports in `.vue`, JS/TS files and
+stylesheets (`@import`), and the root import move, applied to `.vue` and JS/TS
+files:
 
-| v4                           | v5                          |
-| ---------------------------- | --------------------------- |
-| `import 'maz-ui/styles'`     | `import 'maz-ui/style.css'` |
-| `import 'maz-ui/aos-styles'` | `import 'maz-ui/aos.css'`   |
+| v4                                  | v5                                      |
+| ----------------------------------- | --------------------------------------- |
+| `import 'maz-ui/styles'`            | `import 'maz-ui/style.css'`             |
+| `import 'maz-ui/aos-styles'`        | `import 'maz-ui/aos.css'`               |
+| `import 'maz-ui/dist/css/main.css'` | `import 'maz-ui/style.css'`             |
+| `import 'maz-ui/dist/css/aos.css'`  | `import 'maz-ui/aos.css'`               |
+| `import { sleep } from 'maz-ui'`    | `import { sleep } from '@maz-ui/utils'` |
+
+The `maz-ui` root entry still exists in v5 as a type-only surface: imports made
+only of its types (`MazColor`, `MazSize`, `MazSizeUnit`, `MazRoundedSize`,
+`GlobalizableProps`, `MazComponentName`, `MazUiDefaultsOptions`,
+`MazUiOptions`) are kept on `maz-ui`. Other deep `maz-ui/dist/...` imports (the
+`./*` wildcard export was removed) are reported as a warning at the end of the
+run.
 
 ### `props`
 
-Component prop / slot / class renames, applied to `.vue` files only.
-Patterns specific enough to rewrite globally (e.g. `left-icon` /
-`right-icon`) are handled file-wide. Patterns that would otherwise be
-ambiguous (`variant=`, `color="background"`) are rewritten **only inside
-`<Maz...>` opening tags**, never on your own components.
-
-| v4                                                                | v5                                                          |
-| ----------------------------------------------------------------- | ----------------------------------------------------------- |
-| `left-icon="x"` / `right-icon="x"`                                | `start-icon="x"` / `end-icon="x"`                           |
-| `:left-icon="x"` / `:right-icon="x"`                              | `:start-icon="x"` / `:end-icon="x"`                         |
-| `<template #left-icon>` / `<template #right-icon>`                | `<template #start-icon>` / `<template #end-icon>`           |
-| `<template #icon-left>` / `<template #icon-right>` (MazContainer) | `<template #icon-start>` / `<template #icon-end>`           |
-| `footer-align="left"` / `footer-align="right"`                    | `footer-align="start"` / `footer-align="end"`               |
-| `<MazDrawer variant="left">` / `<MazDrawer variant="right">`      | `<MazDrawer variant="start">` / `<MazDrawer variant="end">` |
-| `<Maz... color="background">`                                     | `<Maz... color="surface">`                                  |
-| `active-color="background"`                                       | `active-color="surface"`                                    |
-| `rounded-size="base"`                                             | `rounded-size="md"`                                         |
-| `.--has-left-icon` / `.--has-right-icon` (CSS selectors)          | `.--has-start-icon` / `.--has-end-icon`                     |
+Component prop / slot / class renames, applied to `.vue` files only. The
+props (`left-icon`, `variant=`, `color="background"`, icon names…) are
+rewritten **only inside `<Maz...>` / `<maz-...>` opening tags**, never on your
+own components or other libraries (Vant `left-icon`…). The slots,
+`footer-align`, `rounded-size`, `active-color` and the maz-ui class names are
+specific enough to be rewritten file-wide. Kebab-case, camelCase and
+`v-bind:` / `v-slot:` forms are all handled.
+
+| v4                                                                                                        | v5                                                                |
+| --------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
+| `left-icon="x"` / `right-icon="x"`                                                                        | `start-icon="x"` / `end-icon="x"`                                 |
+| `:left-icon="x"` / `:right-icon="x"`                                                                      | `:start-icon="x"` / `:end-icon="x"`                               |
+| `:leftIcon="x"` / `v-bind:right-icon="x"`                                                                 | `:startIcon="x"` / `v-bind:end-icon="x"`                          |
+| `start-icon="user"` (bare icon name, MazBtn / MazInput / MazLink / MazContainer / MazDropdown / MazAlert) | `start-icon="/user.svg"`                                          |
+| `<MazIcon src="/a.svg">` / `<MazIcon :src="url">`                                                         | `<MazIcon icon="/a.svg">` / `<MazIcon :icon="url">`               |
+| `<MazIcon name="home">` / `<MazIcon name="home" path="/icons">`                                           | `<MazIcon icon="/home.svg">` / `<MazIcon icon="/icons/home.svg">` |
+| `<template #left-icon>` / `<template #right-icon>`                                                        | `<template #start-icon>` / `<template #end-icon>`                 |
+| `<template #icon-left>` / `<template #icon-right>` (MazContainer)                                         | `<template #icon-start>` / `<template #icon-end>`                 |
+| `footer-align="left"` / `footer-align="right"`                                                            | `footer-align="start"` / `footer-align="end"`                     |
+| `<MazDrawer variant="left">` / `<MazDrawer variant="right">`                                              | `<MazDrawer variant="start">` / `<MazDrawer variant="end">`       |
+| `<Maz... color="background">`                                                                             | `<Maz... color="surface">`                                        |
+| `active-color="background"`                                                                               | `active-color="surface"`                                          |
+| `rounded-size="base"`                                                                                     | `rounded-size="md"`                                               |
+| `.--has-left-icon` / `.--has-right-icon` (CSS selectors)                                                  | `.--has-start-icon` / `.--has-end-icon`                           |
+| `.m-input-wrapper-left` / `.m-input-wrapper-right`                                                        | `.m-input-wrapper-start` / `.m-input-wrapper-end`                 |
+| `.drawer-anim-left-*` / `.drawer-anim-right-*`                                                            | `.drawer-anim-start-*` / `.drawer-anim-end-*`                     |
+| `<MazAvatar size="2rem">` (static CSS unit)                                                               | `<MazAvatar size="6rem">` (value ×3, render preserved)            |
+| `<MazBadge size="0.8rem">` (static `rem` size)                                                            | `<MazBadge size="sm">` (closest `MazSize` keyword)                |
+| `<MazPullToRefresh :on-click="x">`                                                                        | `<MazPullToRefresh :on-refresh="x">`                              |
+
+The `MazAvatar` rewrite targets only `<MazAvatar>` / `<maz-avatar>` opening
+tags. v5 fixed the avatar size scale (a CSS-unit `size` no longer renders 3x
+too large), so the numeric value is multiplied by 3 to keep the exact same
+render. Every CSS unit is supported. `MazSize` keywords (`mini`..`xl`) and
+bound `:size="…"` expressions are left untouched - the latter is reported as
+a warning at the end of the run.
+
+v4 rendered a string icon prop as `<MazIcon :name>`, resolved to
+`${mazIconPath}/<name>.svg`. v5 only accepts a URL (or a raw SVG) for a string,
+so a bare name renders nothing: it is rewritten to the relative URL of the same
+file (`mazIconPath` is still prepended to relative URLs). A bare name is never
+a valid v5 value, so this rewrite is idempotent. Bound values, a bound
+`:name` / `:path` on `MazIcon` and the removed `@loaded` / `@unloaded` events
+are reported as warnings at the end of the run. If you provide a `mazIconPath`
+(Nuxt `general.defaultMazIconPath`), note that v5 also prepends it to the
+relative URLs of a former `src` or `path`.
+
+The `MazBadge` rewrite targets only `<MazBadge>` / `<maz-badge>` opening tags.
+v5 `size` only accepts a `MazSize` keyword (the v4 value was the badge
+font-size). The keywords are `rem` font-sizes (`mini` 0.625, `xs` 0.6875, `sm`
+0.75, `md` 0.875, `lg` 1, `xl` 1.25), so a static `rem` value is mapped to the
+closest one (a tie goes to the larger keyword), which gives the table of the
+migration guide whatever the root font size. `px` / `em` values depend on the
+root or parent font size and are reported as warnings at the end of the run.
+
+The `MazPullToRefresh` rewrite targets only `<MazPullToRefresh>` /
+`<maz-pull-to-refresh>` opening tags. v5 renamed the callback prop `on-click`
+to `on-refresh` (both kebab-case and camelCase, bound or static), so native
+click handlers and the `onClick` prop of other components are never touched.
 
 ### `css`
 
-CSS variable renames + `hsl(var(...))` collapse, applied to `.vue` style
-blocks, `.css` files, and any inline strings in `.ts`/`.js`:
+CSS variable renames + `hsl(var(...))` collapse, applied to `.vue` files,
+stylesheets, and any inline strings in `.ts`/`.js` (the maz-ui class names of
+the `props` table are renamed in stylesheets too):
 
 | v4                                                                                         | v5                                                                                |
 | ------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------- |
 | `var(--maz-background)` / `var(--maz-background-700)` / `var(--maz-background-foreground)` | `var(--maz-surface)` / `var(--maz-surface-700)` / `var(--maz-surface-foreground)` |
 | `var(--maz-border)` / `var(--maz-border-700)`                                              | `var(--maz-divider)` / `var(--maz-divider-700)`                                   |
 | `hsl(var(--maz-primary))`                                                                  | `var(--maz-primary)`                                                              |
-| `hsl(var(--maz-primary) / 0.5)`                                                            | `color-mix(in srgb, var(--maz-primary) 0.5, transparent)`                         |
+| `hsl(var(--maz-primary) / 0.5)` / `hsl(var(--maz-primary) / 50%)`                          | `color-mix(in srgb, var(--maz-primary) 50%, transparent)`                         |
+| `hsl(var(--maz-primary) / var(--alpha))`                                                   | `color-mix(in srgb, var(--maz-primary) calc(var(--alpha) * 100%), transparent)`   |
 
 Foundation tokens that happen to start with the same prefix (e.g.
 `--maz-border-width`, `--maz-border-radius`) are explicitly **not**
@@ -178,18 +234,23 @@ renamed.
 Plugin / Nuxt module / preset config keys, applied to `.vue` and JS/TS
 files:
 
-| v4                                                                      | v5                                    |
-| ----------------------------------------------------------------------- | ------------------------------------- |
-| Nuxt `mazUi.css.injectMainCss`                                          | `mazUi.css.injectCss`                 |
-| Theme `strategy: 'hybrid'`                                              | `strategy: 'runtime'`                 |
-| `MazUiTheme` plugin options `injectCriticalCSS: …` / `injectFullCSS: …` | line removed (silently ignored in v5) |
-| Nuxt theme `injectAllCSSOnServer: …`                                    | line removed (silently ignored in v5) |
-| Custom preset `colors.{light,dark}.background`                          | `colors.{light,dark}.surface`         |
-| Custom preset `colors.{light,dark}.border`                              | `colors.{light,dark}.divider`         |
-
-The preset color rename is scoped to `light: { … }` / `dark: { … }`
-blocks, so unrelated CSS-in-JS / JSX style props elsewhere are left
-alone.
+| v4                                                                                                                                       | v5                                      |
+| ---------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- |
+| Nuxt `mazUi.css.injectMainCss`                                                                                                           | `mazUi.css.injectCss`                   |
+| Theme `strategy: 'hybrid'`                                                                                                               | `strategy: 'runtime'`                   |
+| `MazUiTheme` plugin options `injectCriticalCSS: …` / `injectFullCSS: …`                                                                  | option removed (silently ignored in v5) |
+| Nuxt theme `injectAllCSSOnServer: …`                                                                                                     | option removed (silently ignored in v5) |
+| `generateCSS` / `buildThemeCSS` / `buildSeparateThemeFiles` `onlyCritical`, `criticalColors`, `criticalFoundation`, `includeColorScales` | option removed                          |
+| Custom preset `colors.{light,dark}.background`                                                                                           | `colors.{light,dark}.surface`           |
+| Custom preset `colors.{light,dark}.border`                                                                                               | `colors.{light,dark}.divider`           |
+
+The removed options are cleaned on their own line or inline
+(`{ preset, onlyCritical: true }`). The preset color rename is scoped to
+`light: { … }` / `dark: { … }` blocks, and it runs with the
+`strategy: 'hybrid'` rewrite only in files referencing maz-ui (a `maz-ui` /
+`@maz-ui/*` import, the Nuxt `mazUi` key, `MazUi*` plugins, `definePreset`,
+`setupTheme`, `useTheme`, `darkModeStrategy`), so generic objects elsewhere are
+left alone.
 
 ### `deps`
 
@@ -204,8 +265,15 @@ preserved; non-maz-ui dependencies are never touched.
 | `maz-ui`, `@maz-ui/*` semver ranges (`^4.x`, `~4.x`, `4.x`, `4.0.0`, …)      | Rewritten to `^5.0.0` |
 | `workspace:*`, `link:…`, `file:…`, `portal:…`, `npm:…`, `http(s):…`, `git+…` | Left untouched        |
 | Dist tags (`latest`, `next`, `beta`, `alpha`, `canary`)                      | Left untouched        |
+| `@maz-ui/cli` (not published in v5)                                          | Left untouched        |
 | Anything else (`vue`, `chart.js`, your own packages, …)                      | Left untouched        |
 
+When the `imports` group runs, two dependencies are added next to `maz-ui`
+if a source needs them and no `package.json` declares them: `@maz-ui/utils`
+(when a `from 'maz-ui'` import is moved to it) and `valibot` (`^1.3.1`, when a
+source imports it: it was a dependency of maz-ui v4, it is an optional peer
+dependency in v5).
+
 `vue-chartjs` is **not** removed automatically, even though `MazChart`
 no longer depends on it — keep it if you use it directly elsewhere,
 remove it manually otherwise.
@@ -255,7 +323,7 @@ Detected package manager: pnpm. Running `pnpm install`…
 [ … pnpm install output … ]
 
 Next: see https://maz-ui.com/guide/migration-v5 for the manual steps
-(foundation.radius → scales.rounded.md, MazIcon API, MazBadge sizes, MazChart update-mode).
+(foundation.radius → scales.rounded.md, MazIcon API, MazBadge px / em sizes, MazChart update-mode).
 ```
 
 ## Exit codes
@@ -270,15 +338,18 @@ Next: see https://maz-ui.com/guide/migration-v5 for the manual steps
 ## What it does NOT do
 
 Some changes need a human (or your AI assistant via the
-[`@maz-ui/mcp`](https://maz-ui.com/guide/mcp) server) — see the
+[`@maz-ui/mcp`](https://maz-ui.com/ecosystem/mcp) server) — see the
 [migration guide](https://maz-ui.com/guide/migration-v5) for the full
 context:
 
-- **`MazIcon` API simplification** — `name`/`path`/`src` props collapsing
-  into a single `icon` prop needs the original asset path to rewrite
-  correctly.
-- **`MazBadge` numeric `size`** — picking the right keyword (`mini`/`xs`/…)
-  is a judgment call.
+- **`MazIcon` bound values** - a bound `:name` / `:path` and the removed
+  `@loaded` / `@unloaded` events (reported as warnings). Static `name`,
+  `path` and `src` are rewritten by the `props` group.
+- **Icon values in scripts** - `h(MazBtn, { leftIcon })`, `v-bind` objects,
+  `MazStepper` `steps[].icon`: keys too generic to rewrite safely in JS.
+- **`MazBadge` `px` / `em` `size`** - the keyword depends on the root or
+  parent font size (reported as warnings). Static `rem` sizes are rewritten by
+  the `props` group.
 - **Theme preset radius reshape** — `foundation.radius` →
   `scales.rounded.md` needs to move the value to a new sibling block,
   which is too structural for a safe regex. The simpler color key renames

package/dist/cli.mjs

@@ -5,7 +5,7 @@ import { resolve, dirname } from 'node:path';
 import process from 'node:process';
 import { logger } from '@maz-ui/node';
 import { globby } from 'globby';
-import { transformFile, ALL_GROUPS } from './index.mjs';
+import { ALL_GROUPS, transformFile, hasMazUiDistImport, hasMazIconLegacyApi, hasMazBadgeLengthSize, hasMazAvatarBoundSize, hasFoundationRadius, hasValibotImport, hasMazUiRootImport } from './index.mjs';
 
 const DEFAULT_IGNORES = [
   "**/node_modules/**",
@@ -88,22 +88,36 @@ Options:
   -v, --version        Print the upgrade tool version.
 
 Transform groups:
-  imports   maz-ui/styles \u2192 maz-ui/style.css, maz-ui/aos-styles \u2192 maz-ui/aos.css
-  props     left-icon/right-icon \u2192 start-icon/end-icon (props, slots,
-            #icon-left/#icon-right, --has-*-icon classes), footer-align,
-            variant, color="background", active-color, rounded-size="base"
+  imports   maz-ui/styles \u2192 maz-ui/style.css, maz-ui/aos-styles \u2192 maz-ui/aos.css,
+            maz-ui/dist/css/{main,aos}.css \u2192 maz-ui/{style,aos}.css (also in
+            stylesheets), from 'maz-ui' \u2192 from '@maz-ui/utils' (root re-export
+            removed in v5, imports of the v5 root types are kept). When this
+            rewrite fires and the deps group runs, @maz-ui/utils is also added
+            to package.json next to maz-ui (and valibot when imported).
+  props     left-icon/right-icon \u2192 start-icon/end-icon (kebab, camelCase,
+            v-bind:, slots #left-icon / v-slot:, #icon-left/#icon-right),
+            bare icon names \u2192 relative SVG URLs (start-icon="user" \u2192
+            "/user.svg"), MazIcon src/name/path \u2192 icon, footer-align, variant,
+            color="background", active-color, rounded-size="base", internal
+            class names (--has-*-icon, m-input-wrapper-*, drawer-anim-*),
+            MazAvatar static size unit x3 (scale fix, render preserved),
+            MazBadge rem size \u2192 closest MazSize keyword,
+            MazPullToRefresh on-click \u2192 on-refresh
   css       --maz-background \u2192 --maz-surface, --maz-border \u2192 --maz-divider,
-            hsl(var(--maz-X)) collapse (incl. alpha \u2192 color-mix)
+            hsl(var(--maz-X)) collapse (incl. alpha \u2192 color-mix with a
+            percentage), internal class names in stylesheets
   config    Nuxt injectMainCss \u2192 injectCss, theme strategy 'hybrid' \u2192 'runtime',
             removes dropped theme options (injectCriticalCSS, injectFullCSS,
-            injectAllCSSOnServer), preset colors.{light,dark}.background \u2192 surface
-            and .border \u2192 divider
+            injectAllCSSOnServer, onlyCritical, criticalColors,
+            criticalFoundation, includeColorScales), preset
+            colors.{light,dark}.background \u2192 surface and .border \u2192 divider
   deps      Bumps every maz-ui / @maz-ui/* entry in package.json
-            (dependencies, devDependencies, peerDependencies) to ^5.0.0.
-            Workspace, link, file and url specs are left untouched.
+            (dependencies, devDependencies, peerDependencies) to ^5.0.0
+            (except @maz-ui/cli, not published in v5). Workspace, link, file
+            and url specs are left untouched.
 
-Scans the given paths for .vue, .css, .ts/.tsx/.cts/.mts,
-.js/.jsx/.cjs/.mjs and package.json files. By default it respects
+Scans the given paths for .vue, stylesheets (.css, .scss, .sass, .less,
+.styl, .pcss), .ts/.tsx/.cts/.mts, .js/.jsx/.cjs/.mjs and package.json files. By default it respects
 your .gitignore (plus a built-in safe list of node_modules, dist,
 build, .nuxt, .output, .next, .svelte-kit, .turbo, .cache, coverage,
 .vercel, .netlify). Pass --no-gitignore to skip the .gitignore step.
@@ -115,8 +129,10 @@ npm \u2014 based on the lockfile in cwd) and runs <pm> install. Pass
 
 What it does NOT do (handle by hand or with the @maz-ui/mcp server):
   - Reshape foundation.radius into scales.rounded.md (move + key restructure).
-  - Map MazIcon name=/path=/src= props to the new icon= API.
-  - Map numeric MazBadge size to the keyword scale.
+  - Map bound MazIcon :name / :path and the removed @loaded / @unloaded events
+    (reported as warnings).
+  - Map px / em MazBadge sizes to the keyword scale (reported as warnings,
+    rem values are rewritten).
   - MazChart updateMode default change (judgment call).
 
 Full migration guide: https://maz-ui.com/guide/migration-v5
@@ -166,18 +182,46 @@ Detected package manager: ${pm}. Running \`${pm} install\`\u2026
     process.exit(code);
   }
 }
-async function run() {
-  const opts = parseArgs(process.argv);
-  const cwd = process.cwd();
+const PACKAGE_JSON_RE = /(?:^|[\\/])package\.json$/;
+function applyTransform(file, opts, deps = {}) {
+  const before = readFileSync(file, "utf8");
+  const after = transformFile(file, before, { groups: opts.groups, ...deps });
+  return { before, after };
+}
+function reportAndWrite(file, after, opts, cwd) {
+  const shown = file.replace(`${cwd}/`, "");
+  logger.log(`${opts.dryRun ? "[dry-run] would update" : "updated"}: ${shown}`);
+  if (!opts.dryRun)
+    writeFileSync(file, after, "utf8");
+}
+function detectManualSteps(content, importsEnabled) {
+  return {
+    needsUtilsDep: importsEnabled && hasMazUiRootImport(content),
+    needsValibotDep: importsEnabled && hasValibotImport(content),
+    radius: hasFoundationRadius(content),
+    avatarSize: hasMazAvatarBoundSize(content),
+    badgeSize: hasMazBadgeLengthSize(content),
+    iconLegacy: hasMazIconLegacyApi(content),
+    distImport: hasMazUiDistImport(content)
+  };
+}
+async function processSourceFiles(opts, cwd, packageJsonFiles) {
+  const importsEnabled = opts.groups.includes("imports");
   let scanned = 0;
   let changed = 0;
-  let depsChanged = false;
+  let needsUtilsDep = false;
+  let needsValibotDep = false;
+  const radiusFiles = [];
+  const avatarSizeFiles = [];
+  const badgeSizeFiles = [];
+  const iconLegacyFiles = [];
+  const distImportFiles = [];
   for (const root of opts.roots) {
     const absoluteRoot = resolve(cwd, root);
     const files = await globby(
       [
         "**/*.vue",
-        "**/*.css",
+        "**/*.{css,scss,sass,less,styl,stylus,pcss,postcss}",
         "**/*.{js,mjs,cjs,jsx}",
         "**/*.{ts,mts,cts,tsx}",
         "**/package.json"
@@ -190,29 +234,105 @@ async function run() {
       }
     );
     for (const file of files) {
+      if (PACKAGE_JSON_RE.test(file)) {
+        packageJsonFiles.push(file);
+        continue;
+      }
       scanned += 1;
-      const before = readFileSync(file, "utf8");
-      const after = transformFile(file, before, { groups: opts.groups });
+      const { before, after } = applyTransform(file, opts);
+      const detection = detectManualSteps(before, importsEnabled);
+      needsUtilsDep ||= detection.needsUtilsDep;
+      needsValibotDep ||= detection.needsValibotDep;
+      for (const [warning, files2] of [
+        [detection.radius, radiusFiles],
+        [detection.avatarSize, avatarSizeFiles],
+        [detection.badgeSize, badgeSizeFiles],
+        [detection.iconLegacy, iconLegacyFiles],
+        [detection.distImport, distImportFiles]
+      ]) {
+        if (warning)
+          files2.push(file);
+      }
       if (after === before)
         continue;
       changed += 1;
-      if (file.endsWith("package.json"))
-        depsChanged = true;
-      const shown = file.replace(`${cwd}/`, "");
-      logger.log(`${opts.dryRun ? "[dry-run] would update" : "updated"}: ${shown}`);
-      if (!opts.dryRun) {
-        writeFileSync(file, after, "utf8");
-      }
+      reportAndWrite(file, after, opts, cwd);
     }
   }
+  return { scanned, changed, needsUtilsDep, needsValibotDep, radiusFiles, avatarSizeFiles, badgeSizeFiles, iconLegacyFiles, distImportFiles };
+}
+function processPackageJsonFiles(files, opts, cwd, deps) {
+  let scanned = 0;
+  let changed = 0;
+  let depsChanged = false;
+  for (const file of files) {
+    scanned += 1;
+    const { before, after } = applyTransform(file, opts, deps);
+    if (after === before)
+      continue;
+    changed += 1;
+    depsChanged = true;
+    reportAndWrite(file, after, opts, cwd);
+  }
+  return { scanned, changed, depsChanged };
+}
+async function run() {
+  const opts = parseArgs(process.argv);
+  const cwd = process.cwd();
+  const packageJsonFiles = [];
+  const sources = await processSourceFiles(opts, cwd, packageJsonFiles);
+  const pkgs = processPackageJsonFiles(packageJsonFiles, opts, cwd, { addUtilsDep: sources.needsUtilsDep, addValibotDep: sources.needsValibotDep });
+  const scanned = sources.scanned + pkgs.scanned;
+  const changed = sources.changed + pkgs.changed;
+  const depsChanged = pkgs.depsChanged;
   const prefix = opts.dryRun ? "would update" : "updated";
   logger.log(`
 Scanned ${scanned} files, ${prefix} ${changed}.`);
   logger.log(`Groups applied: ${opts.groups.join(", ")}`);
   maybeInstallDeps(opts, depsChanged, cwd);
+  if (sources.radiusFiles.length > 0) {
+    const cwdPrefix = `${cwd}/`;
+    logger.log(`
+\u26A0 foundation.radius detected in ${sources.radiusFiles.length} file(s) \u2014 manual migration required:`);
+    for (const file of sources.radiusFiles)
+      logger.log(`   - ${file.replace(cwdPrefix, "")}`);
+    logger.log(`  \u2192 Move the value to scales.rounded.md (other rounded keys are now derived from it via calc).`);
+  }
+  if (sources.avatarSizeFiles.length > 0) {
+    const cwdPrefix = `${cwd}/`;
+    logger.log(`
+\u26A0 MazAvatar bound :size detected in ${sources.avatarSizeFiles.length} file(s) - manual check required:`);
+    for (const file of sources.avatarSizeFiles)
+      logger.log(`   - ${file.replace(cwdPrefix, "")}`);
+    logger.log(`  \u2192 The size scale was fixed (no more x3). Multiply the CSS unit value by 3 to keep the same render, or use a MazSize keyword. Static size="<unit>" values were already rewritten.`);
+  }
+  if (sources.badgeSizeFiles.length > 0) {
+    const cwdPrefix = `${cwd}/`;
+    logger.log(`
+\u26A0 MazBadge px / em size detected in ${sources.badgeSizeFiles.length} file(s) - manual migration required:`);
+    for (const file of sources.badgeSizeFiles)
+      logger.log(`   - ${file.replace(cwdPrefix, "")}`);
+    logger.log(`  \u2192 size now only accepts a MazSize keyword (mini, xs, sm, md, lg, xl): pick the closest one (rem values were already rewritten).`);
+  }
+  if (sources.iconLegacyFiles.length > 0) {
+    const cwdPrefix = `${cwd}/`;
+    logger.log(`
+\u26A0 MazIcon v4 API detected in ${sources.iconLegacyFiles.length} file(s) - manual migration required:`);
+    for (const file of sources.iconLegacyFiles)
+      logger.log(`   - ${file.replace(cwdPrefix, "")}`);
+    logger.log(`  \u2192 Replace the bound :name / :path by :icon (a component, a URL or a raw SVG), and the removed @loaded / @unloaded events.`);
+  }
+  if (sources.distImportFiles.length > 0) {
+    const cwdPrefix = `${cwd}/`;
+    logger.log(`
+\u26A0 Deep maz-ui/dist imports detected in ${sources.distImportFiles.length} file(s) - manual migration required:`);
+    for (const file of sources.distImportFiles)
+      logger.log(`   - ${file.replace(cwdPrefix, "")}`);
+    logger.log(`  \u2192 The maz-ui/* wildcard export was removed: import from the public entries (maz-ui/components, maz-ui/composables, \u2026).`);
+  }
   logger.log(`
 Next: see https://maz-ui.com/guide/migration-v5 for the manual steps`);
-  logger.log(`(foundation.radius \u2192 scales.rounded.md, MazIcon API, MazBadge sizes, MazChart update-mode).`);
+  logger.log(`(foundation.radius \u2192 scales.rounded.md, MazIcon API, MazBadge px / em sizes, MazChart update-mode).`);
 }
 run().catch((err) => {
   logger.error(err);

package/dist/index.d.mts

@@ -1,16 +1,39 @@
 declare function transformImports(content: string): string;
+declare function transformStyleImports(content: string): string;
+declare function hasMazUiRootImport(content: string): boolean;
+declare function hasMazUiDistImport(content: string): boolean;
+declare function hasValibotImport(content: string): boolean;
+declare function transformClassNames(content: string): string;
+declare function transformBareIconNames(content: string): string;
+declare function transformMazIcon(content: string): string;
+declare function hasMazIconLegacyApi(content: string): boolean;
 declare function transformProps(content: string): string;
+declare function transformPullToRefresh(content: string): string;
+declare function transformAvatarSize(content: string): string;
+declare function transformBadgeSize(content: string): string;
+declare function hasMazBadgeLengthSize(content: string): boolean;
+declare function hasMazAvatarBoundSize(content: string): boolean;
 declare function transformCssVars(content: string): string;
 declare function transformHslVar(content: string): string;
 declare function transformConfig(content: string): string;
 declare function transformPresetColors(content: string): string;
-declare function transformDeps(content: string): string;
+declare function hasFoundationRadius(content: string): boolean;
+interface TransformDepsOptions {
+    addUtils?: boolean;
+    /**
+     * Add `valibot` next to maz-ui: a dependency of maz-ui v4, an optional peer in v5
+     */
+    addValibot?: boolean;
+}
+declare function transformDeps(content: string, options?: TransformDepsOptions): string;
 type TransformGroup = 'imports' | 'props' | 'css' | 'config' | 'deps';
 declare const ALL_GROUPS: readonly TransformGroup[];
 interface TransformOptions {
     groups?: readonly TransformGroup[];
+    addUtilsDep?: boolean;
+    addValibotDep?: boolean;
 }
 declare function transformFile(filename: string, content: string, options?: TransformOptions): string;
 
-export { ALL_GROUPS, transformConfig, transformCssVars, transformDeps, transformFile, transformHslVar, transformImports, transformPresetColors, transformProps };
+export { ALL_GROUPS, hasFoundationRadius, hasMazAvatarBoundSize, hasMazBadgeLengthSize, hasMazIconLegacyApi, hasMazUiDistImport, hasMazUiRootImport, hasValibotImport, transformAvatarSize, transformBadgeSize, transformBareIconNames, transformClassNames, transformConfig, transformCssVars, transformDeps, transformFile, transformHslVar, transformImports, transformMazIcon, transformPresetColors, transformProps, transformPullToRefresh, transformStyleImports };
 export type { TransformGroup, TransformOptions };

package/dist/index.d.ts

@@ -1,16 +1,39 @@
 declare function transformImports(content: string): string;
+declare function transformStyleImports(content: string): string;
+declare function hasMazUiRootImport(content: string): boolean;
+declare function hasMazUiDistImport(content: string): boolean;
+declare function hasValibotImport(content: string): boolean;
+declare function transformClassNames(content: string): string;
+declare function transformBareIconNames(content: string): string;
+declare function transformMazIcon(content: string): string;
+declare function hasMazIconLegacyApi(content: string): boolean;
 declare function transformProps(content: string): string;
+declare function transformPullToRefresh(content: string): string;
+declare function transformAvatarSize(content: string): string;
+declare function transformBadgeSize(content: string): string;
+declare function hasMazBadgeLengthSize(content: string): boolean;
+declare function hasMazAvatarBoundSize(content: string): boolean;
 declare function transformCssVars(content: string): string;
 declare function transformHslVar(content: string): string;
 declare function transformConfig(content: string): string;
 declare function transformPresetColors(content: string): string;
-declare function transformDeps(content: string): string;
+declare function hasFoundationRadius(content: string): boolean;
+interface TransformDepsOptions {
+    addUtils?: boolean;
+    /**
+     * Add `valibot` next to maz-ui: a dependency of maz-ui v4, an optional peer in v5
+     */
+    addValibot?: boolean;
+}
+declare function transformDeps(content: string, options?: TransformDepsOptions): string;
 type TransformGroup = 'imports' | 'props' | 'css' | 'config' | 'deps';
 declare const ALL_GROUPS: readonly TransformGroup[];
 interface TransformOptions {
     groups?: readonly TransformGroup[];
+    addUtilsDep?: boolean;
+    addValibotDep?: boolean;
 }
 declare function transformFile(filename: string, content: string, options?: TransformOptions): string;
 
-export { ALL_GROUPS, transformConfig, transformCssVars, transformDeps, transformFile, transformHslVar, transformImports, transformPresetColors, transformProps };
+export { ALL_GROUPS, hasFoundationRadius, hasMazAvatarBoundSize, hasMazBadgeLengthSize, hasMazIconLegacyApi, hasMazUiDistImport, hasMazUiRootImport, hasValibotImport, transformAvatarSize, transformBadgeSize, transformBareIconNames, transformClassNames, transformConfig, transformCssVars, transformDeps, transformFile, transformHslVar, transformImports, transformMazIcon, transformPresetColors, transformProps, transformPullToRefresh, transformStyleImports };
 export type { TransformGroup, TransformOptions };

package/dist/index.mjs

@@ -1,61 +1,277 @@
-const IMPORT_PATH = /(['"])maz-ui\/(styles|aos-styles)\1/g;
+const IMPORT_PATH = /(['"])maz-ui\/(styles|aos-styles|dist\/css\/main\.css|dist\/css\/aos\.css)\1/g;
+const ROOT_IMPORT_SPECIFIER = /(\bfrom\s+|\bimport\s*\(\s*|\brequire\s*\(\s*)(['"])maz-ui\2/g;
+const STYLE_IMPORT_TARGET = {
+  "styles": "style.css",
+  "aos-styles": "aos.css",
+  "dist/css/main.css": "style.css",
+  "dist/css/aos.css": "aos.css"
+};
+const MAZ_UI_ROOT_TYPES = /* @__PURE__ */ new Set([
+  "MazColor",
+  "MazRoundedSize",
+  "MazSize",
+  "MazSizeUnit",
+  "GlobalizableProps",
+  "MazComponentName",
+  "MazUiDefaultsOptions",
+  "MazUiOptions"
+]);
+const ROOT_NAMED_STATEMENT = /\b(import|export)(\s+type)?\s*\{([^}]*)\}\s*from\s*(['"])maz-ui\4/g;
+const ROOT_TYPES_PLACEHOLDER = "\0maz-ui-root-types\0";
+function isRootTypesOnly(specifiers) {
+  const names = specifiers.split(",").map((specifier) => specifier.trim().replace(/^type\s/, "").trim().split(/\sas\s/)[0]?.trim()).filter(Boolean);
+  return names.length > 0 && names.every((name) => MAZ_UI_ROOT_TYPES.has(name));
+}
+function maskRootTypeImports(content) {
+  return content.replace(ROOT_NAMED_STATEMENT, (statement, _kind, _type, specifiers, quote) => isRootTypesOnly(specifiers) ? statement.replace(`${quote}maz-ui${quote}`, `${quote}${ROOT_TYPES_PLACEHOLDER}${quote}`) : statement);
+}
 function transformImports(content) {
-  return content.replace(IMPORT_PATH, (_, q, sub) => `${q}maz-ui/${sub === "styles" ? "style.css" : "aos.css"}${q}`);
-}
-const ICON_ATTR = /(\s:?)(left|right)-icon\b/g;
-const ICON_SLOT = /#(left|right)-icon\b/g;
-const ICON_LEFT_RIGHT_SLOT = /#icon-(left|right)\b/g;
-const FOOTER_ALIGN = /(\sfooter-align\s*=\s*['"])(left|right)(['"])/g;
-const ROUNDED_SIZE_BASE = /(\srounded-size\s*=\s*['"])base(['"])/g;
-const ACTIVE_COLOR_BG = /(\sactive-color\s*=\s*['"])background(['"])/g;
-const HAS_ICON_CLASS = /\.--has-(left|right)-icon\b/g;
-const MAZ_OPEN_TAG = /<Maz[A-Z]\w*\b[^>]*>/g;
+  return maskRootTypeImports(content).replace(IMPORT_PATH, (_, q, sub) => `${q}maz-ui/${STYLE_IMPORT_TARGET[sub]}${q}`).replace(ROOT_IMPORT_SPECIFIER, (_, prefix, quote) => `${prefix}${quote}@maz-ui/utils${quote}`).replaceAll(ROOT_TYPES_PLACEHOLDER, "maz-ui");
+}
+function transformStyleImports(content) {
+  return content.replace(IMPORT_PATH, (_, q, sub) => `${q}maz-ui/${STYLE_IMPORT_TARGET[sub]}${q}`);
+}
+function hasMazUiRootImport(content) {
+  return /(?:\bfrom\s+|\bimport\s*\(\s*|\brequire\s*\(\s*)(['"])maz-ui\1/.test(maskRootTypeImports(content));
+}
+const DIST_IMPORT = /(['"])maz-ui\/dist\/(?!css\/(?:main|aos)\.css\1)[^'"]+\1/;
+function hasMazUiDistImport(content) {
+  return DIST_IMPORT.test(content);
+}
+const VALIBOT_IMPORT = /(?:\bfrom\s+|\bimport\s*\(\s*|\brequire\s*\(\s*)(['"])valibot\1/;
+function hasValibotImport(content) {
+  return VALIBOT_IMPORT.test(content);
+}
+function openTags(names) {
+  return new RegExp(String.raw`<(?:${names})\b(?:[^>"']|"[^"]*"|'[^']*')*>`, "g");
+}
+const MAZ_OPEN_TAG = openTags(String.raw`Maz[A-Z]\w*|maz-[a-z][\w-]*`);
+const ICON_ATTR = /(\s(?::|v-bind:)?)(left|right)-icon\b/g;
+const ICON_ATTR_CAMEL = /(\s(?::|v-bind:)?)(left|right)Icon\b/g;
+const ICON_SLOT = /(#|\bv-slot:)(left|right)-icon\b/g;
+const ICON_LEFT_RIGHT_SLOT = /(#|\bv-slot:)icon-(left|right)\b/g;
+const FOOTER_ALIGN = /(\s(?:footer-align|footerAlign)\s*=\s*['"])(left|right)(['"])/g;
+const ROUNDED_SIZE_BASE = /(\s(?:rounded-size|roundedSize)\s*=\s*['"])base(['"])/g;
+const ACTIVE_COLOR_BG = /(\s(?:active-color|activeColor)\s*=\s*['"])background(['"])/g;
 const VARIANT_LR = /(\svariant\s*=\s*['"])(left|right)(['"])/g;
 const COLOR_BG = /(\scolor\s*=\s*['"])background(['"])/g;
 function flipDirection(value) {
   return value === "left" ? "start" : "end";
 }
+const HAS_ICON_CLASS = /\.--has-(left|right)-icon\b/g;
+const INPUT_WRAPPER_CLASS = /\bm-input-wrapper-(left|right)\b/g;
+const DRAWER_ANIM_CLASS = /\bdrawer-anim-(left|right)\b/g;
+function transformClassNames(content) {
+  return content.replace(HAS_ICON_CLASS, (_, dir) => `.--has-${flipDirection(dir)}-icon`).replace(INPUT_WRAPPER_CLASS, (_, dir) => `m-input-wrapper-${flipDirection(dir)}`).replace(DRAWER_ANIM_CLASS, (_, dir) => `drawer-anim-${flipDirection(dir)}`);
+}
+const ICON_STRING_TAG = openTags("MazBtn|MazInput|MazLink|MazContainer|MazDropdown|MazAlert|maz-btn|maz-input|maz-link|maz-container|maz-dropdown|maz-alert");
+const BARE_ICON_NAME = /(\s(?:start-icon|end-icon|startIcon|endIcon|icon|dropdown-icon|dropdownIcon)\s*=\s*)(["'])([\w-]+)\2/g;
+function transformBareIconNames(content) {
+  return content.replace(ICON_STRING_TAG, (tag) => tag.replace(BARE_ICON_NAME, (_, prefix, quote, name) => `${prefix}${quote}/${name}.svg${quote}`));
+}
+const MAZ_ICON_OPEN_TAG = openTags("MazIcon|maz-icon");
+const ICON_SRC_ATTR = /(\s(?::|v-bind:)?)src(\s*=)/g;
+const ICON_STATIC_NAME = /\sname\s*=\s*(["'])([^"']+)\1/;
+const ICON_STATIC_PATH = /\spath\s*=\s*(["'])([^"']*)\1/;
+const ICON_BOUND_NAME_OR_PATH = /\s(?::|v-bind:)(?:name|path)\s*=/;
+function transformIconName(tag) {
+  const nameMatch = tag.match(ICON_STATIC_NAME);
+  if (!nameMatch || ICON_BOUND_NAME_OR_PATH.test(tag))
+    return tag;
+  const pathMatch = tag.match(ICON_STATIC_PATH);
+  let base = pathMatch?.[2] ?? "";
+  while (base.endsWith("/"))
+    base = base.slice(0, -1);
+  const quote = nameMatch[1];
+  const url = `${base}/${nameMatch[2]}.svg`;
+  return tag.replace(ICON_STATIC_PATH, "").replace(ICON_STATIC_NAME, ` icon=${quote}${url}${quote}`);
+}
+function transformMazIcon(content) {
+  return content.replace(MAZ_ICON_OPEN_TAG, (tag) => transformIconName(tag.replace(ICON_SRC_ATTR, (_, prefix, suffix) => `${prefix}icon${suffix}`)));
+}
+const ICON_LEGACY_EVENTS = /\s(?:@|v-on:)(?:loaded|unloaded)\b/;
+function hasMazIconLegacyApi(content) {
+  for (const match of content.matchAll(MAZ_ICON_OPEN_TAG)) {
+    if (ICON_BOUND_NAME_OR_PATH.test(match[0]) || ICON_LEGACY_EVENTS.test(match[0]))
+      return true;
+  }
+  return false;
+}
 function transformProps(content) {
   let out = content;
-  out = out.replace(ICON_ATTR, (_, prefix, dir) => `${prefix}${flipDirection(dir)}-icon`);
-  out = out.replace(ICON_SLOT, (_, dir) => `#${flipDirection(dir)}-icon`);
-  out = out.replace(ICON_LEFT_RIGHT_SLOT, (_, dir) => `#icon-${flipDirection(dir)}`);
+  out = out.replace(ICON_SLOT, (_, prefix, dir) => `${prefix}${flipDirection(dir)}-icon`);
+  out = out.replace(ICON_LEFT_RIGHT_SLOT, (_, prefix, dir) => `${prefix}icon-${flipDirection(dir)}`);
   out = out.replace(FOOTER_ALIGN, (_, p, dir, s) => `${p}${flipDirection(dir)}${s}`);
   out = out.replace(ROUNDED_SIZE_BASE, (_, p, s) => `${p}md${s}`);
   out = out.replace(ACTIVE_COLOR_BG, (_, p, s) => `${p}surface${s}`);
-  out = out.replace(HAS_ICON_CLASS, (_, dir) => `.--has-${flipDirection(dir)}-icon`);
-  out = out.replace(MAZ_OPEN_TAG, (tag) => tag.replace(VARIANT_LR, (_, p, dir, s) => `${p}${flipDirection(dir)}${s}`).replace(COLOR_BG, (_, p, s) => `${p}surface${s}`));
+  out = transformClassNames(out);
+  out = out.replace(MAZ_OPEN_TAG, (tag) => tag.replace(ICON_ATTR, (_, prefix, dir) => `${prefix}${flipDirection(dir)}-icon`).replace(ICON_ATTR_CAMEL, (_, prefix, dir) => `${prefix}${dir === "left" ? "start" : "end"}Icon`).replace(VARIANT_LR, (_, p, dir, s) => `${p}${flipDirection(dir)}${s}`).replace(COLOR_BG, (_, p, s) => `${p}surface${s}`));
+  out = transformBareIconNames(out);
+  out = transformMazIcon(out);
+  out = transformAvatarSize(out);
+  out = transformBadgeSize(out);
+  out = transformPullToRefresh(out);
   return out;
 }
+const MAZ_PULL_TO_REFRESH_OPEN_TAG = openTags("MazPullToRefresh|maz-pull-to-refresh");
+const PULL_TO_REFRESH_ON_CLICK_KEBAB = /(\s:?)on-click\b/g;
+const PULL_TO_REFRESH_ON_CLICK_CAMEL = /(\s:?)onClick\b/g;
+function transformPullToRefresh(content) {
+  return content.replace(MAZ_PULL_TO_REFRESH_OPEN_TAG, (tag) => tag.replace(PULL_TO_REFRESH_ON_CLICK_KEBAB, (_, prefix) => `${prefix}on-refresh`).replace(PULL_TO_REFRESH_ON_CLICK_CAMEL, (_, prefix) => `${prefix}onRefresh`));
+}
+const MAZ_AVATAR_OPEN_TAG = openTags("MazAvatar|maz-avatar");
+const AVATAR_SIZE_UNIT = /(?<![:\w-])(size\s*=\s*(["']))(\d+(?:\.\d+)?|\.\d+)([a-z%]+)\2/gi;
+function tripleLength(value) {
+  return String(Number.parseFloat((Number.parseFloat(value) * 3).toFixed(4)));
+}
+function transformAvatarSize(content) {
+  return content.replace(MAZ_AVATAR_OPEN_TAG, (tag) => tag.replace(AVATAR_SIZE_UNIT, (_, prefix, quote, num, unit) => `${prefix}${tripleLength(num)}${unit}${quote}`));
+}
+const MAZ_BADGE_OPEN_TAG = openTags("MazBadge|maz-badge");
+const BADGE_STATIC_SIZE = /(?<![:\w-])(size\s*=\s*(["']))([^"']*)\2/;
+const BADGE_SIZE_KEYWORDS = /* @__PURE__ */ new Set(["mini", "xs", "sm", "md", "lg", "xl"]);
+const BADGE_KEYWORD_REM = [
+  ["mini", 0.625],
+  ["xs", 0.6875],
+  ["sm", 0.75],
+  ["md", 0.875],
+  ["lg", 1],
+  ["xl", 1.25]
+];
+function getClosestBadgeSize(rem) {
+  let closest = BADGE_KEYWORD_REM[0];
+  for (const candidate of BADGE_KEYWORD_REM) {
+    if (Math.abs(candidate[1] - rem) <= Math.abs(closest[1] - rem) + 1e-9)
+      closest = candidate;
+  }
+  return closest[0];
+}
+function parseRem(value) {
+  if (!value.endsWith("rem"))
+    return void 0;
+  const number = value.slice(0, -"rem".length);
+  return /^[\d.]+$/.test(number) && Number.isFinite(Number(number)) ? Number(number) : void 0;
+}
+function transformBadgeSize(content) {
+  return content.replace(MAZ_BADGE_OPEN_TAG, (tag) => tag.replace(BADGE_STATIC_SIZE, (match, prefix, quote, value) => {
+    const rem = parseRem(value.trim());
+    return rem === void 0 ? match : `${prefix}${getClosestBadgeSize(rem)}${quote}`;
+  }));
+}
+function hasMazBadgeLengthSize(content) {
+  for (const match of content.matchAll(MAZ_BADGE_OPEN_TAG)) {
+    const value = match[0].match(BADGE_STATIC_SIZE)?.[3].trim();
+    if (value && !BADGE_SIZE_KEYWORDS.has(value) && parseRem(value) === void 0)
+      return true;
+  }
+  return false;
+}
+const AVATAR_BOUND_SIZE = /(?:^|\s)(?::|v-bind:)size\s*=/;
+function hasMazAvatarBoundSize(content) {
+  for (const match of content.matchAll(MAZ_AVATAR_OPEN_TAG)) {
+    if (AVATAR_BOUND_SIZE.test(match[0]))
+      return true;
+  }
+  return false;
+}
 const MAZ_BACKGROUND = /--maz-background(?:(?![-\w])|(?=-(?:foreground|\d)))/g;
 const MAZ_BORDER_COLOR = /--maz-border(?:(?![-\w])|(?=-(?:foreground|\d)))/g;
-const MAZ_VAR = String.raw`var\(--(?:maz|m)-[\w-]+\)`;
-const HSL_WITH_ALPHA = new RegExp(String.raw`hsl\(\s*(${MAZ_VAR})\s*\/\s*([^)]+)\)`, "g");
-const HSL_NO_ALPHA = new RegExp(String.raw`hsl\(\s*(${MAZ_VAR})\s*\)`, "g");
+const MAZ_VAR = /^var\(--(?:maz|m)-[\w-]+\)$/;
+const HSL_OPEN = /hsl\(/g;
 function transformCssVars(content) {
   return content.replace(MAZ_BACKGROUND, "--maz-surface").replace(MAZ_BORDER_COLOR, "--maz-divider");
 }
+function findClosingParen(content, start) {
+  let depth = 1;
+  for (let index = start; index < content.length; index++) {
+    if (content[index] === "(")
+      depth++;
+    else if (content[index] === ")")
+      depth--;
+    if (depth === 0)
+      return index;
+  }
+  return -1;
+}
+function isPlainNumber(value) {
+  return /^[\d.]+$/.test(value) && Number.isFinite(Number(value));
+}
+function toPercentage(alpha) {
+  if (alpha.endsWith("%") && isPlainNumber(alpha.slice(0, -1)))
+    return alpha;
+  if (isPlainNumber(alpha))
+    return `${Number.parseFloat((Number.parseFloat(alpha) * 100).toFixed(4))}%`;
+  return `calc(${alpha} * 100%)`;
+}
+function collapseHsl(inner) {
+  const slashIndex = inner.indexOf("/");
+  const color = (slashIndex === -1 ? inner : inner.slice(0, slashIndex)).trim();
+  if (!MAZ_VAR.test(color))
+    return void 0;
+  if (slashIndex === -1)
+    return color;
+  return `color-mix(in srgb, ${color} ${toPercentage(inner.slice(slashIndex + 1).trim())}, transparent)`;
+}
 function transformHslVar(content) {
-  return content.replace(HSL_WITH_ALPHA, (_, v, alpha) => `color-mix(in srgb, ${v} ${alpha.trim()}, transparent)`).replace(HSL_NO_ALPHA, (_, v) => v);
+  let out = "";
+  let cursor = 0;
+  for (const match of content.matchAll(HSL_OPEN)) {
+    const start = match.index;
+    if (start < cursor)
+      continue;
+    const innerStart = start + match[0].length;
+    const end = findClosingParen(content, innerStart);
+    const collapsed = end === -1 ? void 0 : collapseHsl(content.slice(innerStart, end));
+    if (collapsed === void 0)
+      continue;
+    out += content.slice(cursor, start) + collapsed;
+    cursor = end + 1;
+  }
+  return out + content.slice(cursor);
 }
 const NUXT_INJECT_MAIN_CSS = /\binjectMainCss\b/g;
 const STRATEGY_HYBRID = /(\bstrategy\s*:\s*['"])hybrid(['"])/g;
-const DEPRECATED_THEME_OPTIONS = /^[^\S\n]*(?:injectCriticalCSS|injectFullCSS|injectAllCSSOnServer)\s*:[^,\n]*,?[^\S\n]*\n?/gm;
+const DEPRECATED_OPTION_KEYS = "injectCriticalCSS|injectFullCSS|injectAllCSSOnServer|onlyCritical|criticalColors|criticalFoundation|includeColorScales";
+const DEPRECATED_OPTION_VALUE = String.raw`(?:\[[^\]\n]*\]|\{[^}\n]*\}|[^,}\n]*)`;
+const DEPRECATED_OPTION_INLINE_VALUE = String.raw`(?:\[[^\]\n]*\]|\{[^}\n]*\}|[^,}\n]*?)`;
+const DEPRECATED_OPTION_LINE = new RegExp(String.raw`^[ \t]*(?:${DEPRECATED_OPTION_KEYS})\s*:\s*${DEPRECATED_OPTION_VALUE},?[^\S\n]*\n?`, "gm");
+const DEPRECATED_OPTION_INLINE_AFTER = new RegExp(String.raw`,[^\S\n]*(?:${DEPRECATED_OPTION_KEYS})\s*:\s*${DEPRECATED_OPTION_INLINE_VALUE}(?=[^\S\n]*[,}])`, "g");
+const DEPRECATED_OPTION_INLINE_FIRST = new RegExp(String.raw`(\{[^\S\n]*)(?:${DEPRECATED_OPTION_KEYS})\s*:\s*${DEPRECATED_OPTION_INLINE_VALUE}(?:,[^\S\n]*|(?=[^\S\n]*\}))`, "g");
+const MAZ_UI_REFERENCE = /['"](?:maz-ui|@maz-ui\/[\w-]+)(?:\/[^'"]*)?['"]|\bmazUi\s*:|\bMazUi\w*\b|\b(?:definePreset|setupTheme|useTheme)\s*\(|\bdarkModeStrategy\s*:/;
+function referencesMazUi(content) {
+  return MAZ_UI_REFERENCE.test(content);
+}
 function transformConfig(content) {
-  return content.replace(NUXT_INJECT_MAIN_CSS, "injectCss").replace(STRATEGY_HYBRID, (_, p, s) => `${p}runtime${s}`).replace(DEPRECATED_THEME_OPTIONS, "");
+  const out = content.replace(NUXT_INJECT_MAIN_CSS, "injectCss");
+  return (referencesMazUi(out) ? out.replace(STRATEGY_HYBRID, (_, p, s) => `${p}runtime${s}`) : out).replace(DEPRECATED_OPTION_LINE, "").replace(DEPRECATED_OPTION_INLINE_AFTER, "").replace(DEPRECATED_OPTION_INLINE_FIRST, (_, open) => open);
 }
 const LIGHT_DARK_BLOCK = /(\b(?:light|dark)\s*:\s*\{)([^{}]*)(\})/g;
 function transformPresetColors(content) {
+  if (!referencesMazUi(content))
+    return content;
   return content.replace(LIGHT_DARK_BLOCK, (_, open, body, close) => {
     const renamed = body.replace(/(['"]?)background\1(\s*:)/g, (_match, q, suffix) => `${q}surface${q}${suffix}`).replace(/(['"]?)border\1(\s*:)/g, (_match, q, suffix) => `${q}divider${q}${suffix}`);
     return `${open}${renamed}${close}`;
   });
 }
+const FOUNDATION_BLOCK = /\bfoundation\s*:\s*\{([^{}]*)\}/g;
+const RADIUS_KEY_INSIDE = /(?:^|[\s,{])(['"]?)radius\1\s*:/;
+function hasFoundationRadius(content) {
+  for (const match of content.matchAll(FOUNDATION_BLOCK)) {
+    if (RADIUS_KEY_INSIDE.test(match[1]))
+      return true;
+  }
+  return false;
+}
 const MAZ_UI_PKG = /^(?:maz-ui|@maz-ui\/.+)$/;
+const UNPUBLISHED_PKGS = /* @__PURE__ */ new Set(["@maz-ui/cli"]);
 const TARGET_VERSION = "^5.0.0";
+const UTILS_PKG = "@maz-ui/utils";
+const VALIBOT_PKG = "valibot";
+const VALIBOT_VERSION = "^1.3.1";
 const PROTECTED_PREFIX = /^(?:workspace|link|file|portal|npm|http|https|git\+|github):/;
 function shouldBump(name, range) {
-  if (!MAZ_UI_PKG.test(name))
+  if (!MAZ_UI_PKG.test(name) || UNPUBLISHED_PKGS.has(name))
     return false;
   if (PROTECTED_PREFIX.test(range))
     return false;
@@ -68,62 +284,110 @@ function detectIndent(content) {
   return match ? match[1] : 2;
 }
 const DEP_FIELDS = ["dependencies", "devDependencies", "peerDependencies"];
-function transformDeps(content) {
-  let pkg;
-  try {
-    pkg = JSON.parse(content);
-  } catch {
-    return content;
+function getDepMap(pkg, field) {
+  const deps = pkg[field];
+  if (!deps || typeof deps !== "object" || Array.isArray(deps))
+    return void 0;
+  return deps;
+}
+function packageHasDep(pkg, name) {
+  return DEP_FIELDS.some((field) => {
+    const map = getDepMap(pkg, field);
+    return !!map && name in map;
+  });
+}
+function findMazUiHostField(pkg) {
+  for (const field of DEP_FIELDS) {
+    const map = getDepMap(pkg, field);
+    if (!map)
+      continue;
+    if (Object.keys(map).some((k) => k === "maz-ui" || k.startsWith("@maz-ui/")))
+      return field;
   }
-  if (!pkg || typeof pkg !== "object" || Array.isArray(pkg))
-    return content;
+  return void 0;
+}
+function bumpMazUiVersions(pkg) {
   let changed = false;
   for (const field of DEP_FIELDS) {
-    const deps = pkg[field];
-    if (!deps || typeof deps !== "object" || Array.isArray(deps))
+    const map = getDepMap(pkg, field);
+    if (!map)
       continue;
-    const map = deps;
     for (const [name, range] of Object.entries(map)) {
-      if (typeof range !== "string")
-        continue;
-      if (shouldBump(name, range)) {
+      if (typeof range === "string" && shouldBump(name, range)) {
         map[name] = TARGET_VERSION;
         changed = true;
       }
     }
   }
-  if (!changed)
+  return changed;
+}
+function addMissingDeps(pkg, deps) {
+  let changed = false;
+  for (const [name, version] of deps) {
+    const host = findMazUiHostField(pkg);
+    if (!host || packageHasDep(pkg, name))
+      continue;
+    getDepMap(pkg, host)[name] = version;
+    changed = true;
+  }
+  return changed;
+}
+function transformDeps(content, options = {}) {
+  let pkg;
+  try {
+    pkg = JSON.parse(content);
+  } catch {
+    return content;
+  }
+  if (!pkg || typeof pkg !== "object" || Array.isArray(pkg))
+    return content;
+  const addedDeps = [];
+  if (options.addUtils)
+    addedDeps.push([UTILS_PKG, TARGET_VERSION]);
+  if (options.addValibot)
+    addedDeps.push([VALIBOT_PKG, VALIBOT_VERSION]);
+  const bumped = bumpMazUiVersions(pkg);
+  const added = addMissingDeps(pkg, addedDeps);
+  if (!bumped && !added)
     return content;
   const indent = detectIndent(content);
   const trailingNewline = content.endsWith("\n") ? "\n" : "";
   return JSON.stringify(pkg, null, indent) + trailingNewline;
 }
 const ALL_GROUPS = ["imports", "props", "css", "config", "deps"];
+const STYLESHEET_EXTENSION = /\.(?:css|scss|sass|less|styl|stylus|pcss|postcss)$/;
+function getFileKind(filename) {
+  if (filename.endsWith(".vue"))
+    return "vue";
+  if (STYLESHEET_EXTENSION.test(filename))
+    return "stylesheet";
+  if (/\.[cm]?[jt]sx?$/.test(filename))
+    return "script";
+  if (/(?:^|[\\/])package\.json$/.test(filename))
+    return "packageJson";
+  return void 0;
+}
+const PIPELINE = [
+  { group: "imports", kinds: ["vue", "script"], transform: transformImports },
+  { group: "imports", kinds: ["stylesheet"], transform: transformStyleImports },
+  { group: "props", kinds: ["vue"], transform: transformProps },
+  { group: "css", kinds: ["stylesheet"], transform: transformClassNames },
+  { group: "css", kinds: ["vue", "stylesheet", "script"], transform: transformCssVars },
+  { group: "css", kinds: ["vue", "stylesheet", "script"], transform: transformHslVar },
+  { group: "config", kinds: ["vue", "script"], transform: transformConfig },
+  { group: "config", kinds: ["vue", "script"], transform: transformPresetColors },
+  {
+    group: "deps",
+    kinds: ["packageJson"],
+    transform: (content, options) => transformDeps(content, { addUtils: options.addUtilsDep, addValibot: options.addValibotDep })
+  }
+];
 function transformFile(filename, content, options = {}) {
   const groups = options.groups ?? ALL_GROUPS;
-  const enabled = (g) => groups.includes(g);
-  const isVue = filename.endsWith(".vue");
-  const isCss = filename.endsWith(".css");
-  const isJs = /\.[cm]?[jt]sx?$/.test(filename);
-  const isPackageJson = /(?:^|[\\/])package\.json$/.test(filename);
-  let out = content;
-  if (enabled("imports") && (isVue || isJs))
-    out = transformImports(out);
-  if (enabled("props") && isVue)
-    out = transformProps(out);
-  if (enabled("css")) {
-    if (isVue || isCss)
-      out = transformCssVars(out);
-    if (isVue || isCss || isJs)
-      out = transformHslVar(out);
-  }
-  if (enabled("config") && (isVue || isJs)) {
-    out = transformConfig(out);
-    out = transformPresetColors(out);
-  }
-  if (enabled("deps") && isPackageJson)
-    out = transformDeps(out);
-  return out;
+  const kind = getFileKind(filename);
+  if (!kind)
+    return content;
+  return PIPELINE.filter((step) => groups.includes(step.group) && step.kinds.includes(kind)).reduce((out, step) => step.transform(out, options), content);
 }
 
-export { ALL_GROUPS, transformConfig, transformCssVars, transformDeps, transformFile, transformHslVar, transformImports, transformPresetColors, transformProps };
+export { ALL_GROUPS, hasFoundationRadius, hasMazAvatarBoundSize, hasMazBadgeLengthSize, hasMazIconLegacyApi, hasMazUiDistImport, hasMazUiRootImport, hasValibotImport, transformAvatarSize, transformBadgeSize, transformBareIconNames, transformClassNames, transformConfig, transformCssVars, transformDeps, transformFile, transformHslVar, transformImports, transformMazIcon, transformPresetColors, transformProps, transformPullToRefresh, transformStyleImports };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@maz-ui/upgrade",
   "type": "module",
-  "version": "5.0.0-canary.ef64a02.0",
+  "version": "5.1.0-beta.0",
   "description": "Automated source rewrites for migrating a project from Maz-UI v4 to v5.",
   "author": "Louis Mazel <me@loicmazuel.com>",
   "license": "MIT",
@@ -23,7 +23,8 @@
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.mjs"
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
     }
   },
   "main": "./dist/index.mjs",
@@ -37,24 +38,20 @@
     "dist"
   ],
   "engines": {
-    "node": ">=20.19.0"
+    "node": ">=22.12.0"
   },
   "dependencies": {
-    "globby": "^16.2.0",
-    "@maz-ui/node": "5.0.0-canary.ef64a02.0"
+    "@maz-ui/node": "5.1.0-beta.0",
+    "globby": "^16.2.4"
   },
   "devDependencies": {
-    "@types/node": "^25.6.0",
-    "typescript": "^5.9.3",
-    "unbuild": "^3.6.1",
-    "vitest": "4.1.5",
-    "@maz-ui/eslint-config": "5.0.0-canary.ef64a02.0"
+    "@maz-ui/eslint-config": "5.0.0",
+    "unbuild": "^3.6.1"
   },
   "lint-staged": {
     "*.{js,ts,mjs,mts,cjs,md,yml,json}": "cross-env NODE_ENV=production eslint --fix"
   },
   "scripts": {
-    "postinstall": "nx build",
     "build": "unbuild",
     "dev": "unbuild --stub",
     "typecheck": "tsc --noEmit --skipLibCheck",