@m3ui-vue/nuxt 0.1.0 → 0.2.0

package/README.md

@@ -10,6 +10,11 @@ Nuxt module for [m3ui-vue](https://m3ui.dev), the Material Design 3 component li
 It installs the library's plugin, auto-imports its components and composables, adds its stylesheet, and puts the
 user's theme (dark mode, palette, contrast) on the server-rendered page before the first paint.
 
+> **Beta.** Server-side rendering and this module are new. Every component renders on the server and is tested
+> there, but real apps will find cases we haven't: if something breaks, renders differently on the server, or Vue
+> warns about a hydration mismatch, please [open an issue](https://github.com/SrWither/m3ui-vue-nuxt/issues) (or on
+> [m3ui-vue](https://github.com/SrWither/m3ui-vue/issues) for a component).
+
 ## Install
 
 ```bash
@@ -32,6 +37,9 @@ export default defineNuxtConfig({
 })
 ```
 
+Keep `vue` in your app's own dependencies, as Nuxt's starter does: with pnpm, an app that only gets Vue through
+`nuxt` can end up loading a second copy on the server, which fails to render.
+
 The theme and the palettes are Tailwind CSS, so they go in your own stylesheet, after Tailwind:
 
 ```css
@@ -84,27 +92,60 @@ Everything `createM3UI()` takes, plus what the module itself does:
 | Option | Default | |
 |---|---|---|
 | `palette`, `seed`, `seedOptions`, `contrast`, `persistPalette`, `customPalettes`, `themeColor` | | As in `createM3UI()` |
-| `locale` | English | A preset's code (`'es'`, `'fr'`, `'pt'`, `'de'`, `'ja'`, `'zh'`, `'ko'`) or your own strings |
+| `locale` | English | A preset's code (`'es'`, `'fr'`, `'pt'`, `'de'`, `'ja'`, `'zh'`, `'ko'`), your own strings, or `'auto'` to follow `@nuxtjs/i18n` |
 | `components` | `true` | Auto-import the components |
 | `composables` | `{ prefix: 'M3' }` | Auto-import the composables with this prefix; `false` to import them yourself |
 | `css` | `true` | Add `@m3ui-vue/m3ui-vue/styles` |
+| `cookies` | `true` | Keep the theme, palette and contrast in cookies too, so the server renders with them |
 | `themeScript` | `true` | Inline `themeInitScript()` in `<head>` |
 
+## With @nuxtjs/i18n
+
+`locale: 'auto'` makes the components' built-in text (pagination, pickers, dialogs…) follow `@nuxtjs/i18n`'s current
+language, on the server and when the user switches it. A language tag picks its language's preset (`es-AR` → Spanish);
+languages without one fall back to English.
+
+```ts
+export default defineNuxtConfig({
+  modules: ['@m3ui-vue/nuxt', '@nuxtjs/i18n'],
+  i18n: {
+    locales: [{ code: 'en', language: 'en-US' }, { code: 'es', language: 'es-AR' }],
+    defaultLocale: 'en',
+  },
+  m3ui: { locale: 'auto' },
+})
+```
+
+With `'auto'` all seven presets are bundled (about 11 kB gzipped), since the language can change at any time.
+
 ## Server-side rendering
 
-The user's theme lives in `localStorage`, which the server can't read. The inlined script applies it to `<html>`
-before the page paints, so there's no flash of the default theme, but the composables still start from the defaults
-on the server (`theme` is `'system'`, `palette` is `'purple'`) and switch to the user's choice when the app hydrates.
-Render anything that depends on them inside `<ClientOnly>`, like an icon showing the current theme:
+The library keeps the user's theme, palette and contrast in `localStorage`, and with `cookies` (on by default) in
+cookies too, which the server reads. So `useM3Theme()` and `useM3ColorPalette()` report the user's choice while the
+page renders on the server, and anything built from them (a theme toggle's icon, the selected palette swatch) hydrates
+without mismatches, no `<ClientOnly>` needed:
 
 ```vue
-<ClientOnly>
+<template>
   <MIconButton :icon="theme === 'dark' ? 'dark_mode' : 'light_mode'" label="Theme" @click="cycle" />
-</ClientOnly>
+</template>
+
+<script setup lang="ts">
+const { theme, cycle } = useM3Theme()
+</script>
 ```
 
+The inlined script puts dark mode, the palette and the contrast on `<html>` before the page paints. What the server
+can't know is the system's preferences: with the `'system'` theme or contrast, `theme` is `'system'` there (whether
+the page ends up dark is decided in the browser), and `activeContrast` is `'standard'`. If cookies were cleared but
+`localStorage` wasn't, the first render shows the defaults and switches to the stored choice once hydrated. The other way
+around, a choice only in the cookies is used too: your server can set `m3-theme`, `m3-palette` or `m3-contrast` to apply
+a theme saved in the user's account, for instance.
+
 The adaptive layouts (`MNavigationSuite`, `MListDetail`, `MSupportingPane`) measure their own size, which the server
-doesn't know either: they render their compact layout there and adapt on the client.
+can't. With `cookies`, the window's size is kept in a cookie too (`m3-viewport`), so from the second visit on they
+render on the server for the user's screen (one in a narrower column corrects itself on the client). On a first visit
+they render their compact layout and adapt once the page is interactive.
 
 A `seed` default can't be generated before the app loads: on the first visit the page shows the baseline palette
 until it does (later visits use the cached scheme).
@@ -115,10 +156,18 @@ until it does (later visits use the cached scheme).
 pnpm install
 pnpm dev:prepare   # stub the module and generate types
 pnpm dev           # the playground, with the library linked from ../m3ui-vue
-pnpm test          # builds a fixture app and checks its server-rendered HTML
+pnpm test          # builds fixture apps, checks their server-rendered HTML and hydrates one in Chromium
 pnpm test:types
 ```
 
+The hydration test (`test/browser.test.ts`) drives the Chromium already on the machine through `playwright-core` (no
+browser download): `/usr/bin/chromium` and the usual paths, or `CHROMIUM_PATH`. It fails on any hydration warning
+or page error, including overlays open on load; without a Chromium it's skipped.
+
+`dev:prepare` stubs the module (it loads `src/module.ts` on the fly), and with the stub the editor types the `m3ui`
+options in the playground's `nuxt.config.ts` loosely (no autocompletion of palette ids, for instance). `pnpm build`
+followed by `nuxi prepare playground` types them like the published package.
+
 ## License
 
 MIT

package/dist/module.d.mts

@@ -15,9 +15,10 @@ type LocalePreset = keyof typeof LOCALE_PRESETS | 'en';
 interface ModuleOptions extends Omit<M3UIOptions, 'locale'> {
     /**
      * Built-in text: a preset's language code (`'es'`, `'fr'`, `'pt'`, `'de'`, `'ja'`, `'zh'`, `'ko'`; `'en'` is the
-     * default) or your own strings, which override English.
+     * default), your own strings, which override English, or `'auto'` to follow `@nuxtjs/i18n`'s current language
+     * (by its language tag, `es-AR` → `es`; English where there's no preset), switching with it.
      */
-    locale?: LocalePreset | Partial<M3Locale>;
+    locale?: LocalePreset | 'auto' | Partial<M3Locale>;
     /** Auto-import the components (`<MButton>`…). Each one is bundled only where it's used. Default `true`. */
     components?: boolean;
     /**
@@ -30,6 +31,13 @@ interface ModuleOptions extends Omit<M3UIOptions, 'locale'> {
     };
     /** Add the components' own stylesheet (`@m3ui-vue/m3ui-vue/styles`). Default `true`. */
     css?: boolean;
+    /**
+     * Remember the theme, the palette and the contrast level in cookies too, so the server renders with the user's
+     * choice: `useM3Theme()` and `useM3ColorPalette()` report it during server rendering and hydration, and UI built
+     * from them needs no `<ClientOnly>`. The window's size goes in one too, so the adaptive layouts (`MNavigationSuite`,
+     * `MListDetail`, `MSupportingPane`) render for the user's screen instead of compact. Default `true`.
+     */
+    cookies?: boolean;
     /**
      * Inline `themeInitScript()` in `<head>`, so dark mode, the palette and the contrast level the user picked are
      * on the server-rendered page before the first paint. Default `true`.

package/dist/module.json

@@ -4,7 +4,7 @@
   "compatibility": {
     "nuxt": ">=3.0.0"
   },
-  "version": "0.1.0",
+  "version": "0.2.0",
   "builder": {
     "@nuxt/module-builder": "1.0.3",
     "unbuild": "unknown"

package/dist/module.mjs

@@ -1,6 +1,6 @@
 import { readFileSync } from 'node:fs';
 import { join, dirname } from 'node:path';
-import { defineNuxtModule, useLogger, createResolver, resolvePath, tryResolveModule, addComponent, addImports, addTemplate, addTypeTemplate, addPlugin } from '@nuxt/kit';
+import { defineNuxtModule, useLogger, createResolver, resolvePath, tryResolveModule, addComponent, addImports, hasNuxtModule, addTemplate, addTypeTemplate, addPlugin } from '@nuxt/kit';
 
 const LIB = "@m3ui-vue/m3ui-vue";
 const LOCALE_PRESETS = { es: "esLocale", fr: "frLocale", pt: "ptLocale", de: "deLocale", ja: "jaLocale", zh: "zhLocale", ko: "koLocale" };
@@ -23,12 +23,13 @@ const module$1 = defineNuxtModule({
     components: true,
     composables: { prefix: "M3" },
     css: true,
+    cookies: true,
     themeScript: true
   },
   async setup(options, nuxt) {
     const logger = useLogger("@m3ui-vue/nuxt");
     const resolver = createResolver(import.meta.url);
-    const { components, composables, css, themeScript, locale, ...plugin } = options;
+    const { components, composables, css, cookies, themeScript, locale, ...plugin } = options;
     const entry = await resolvePath(LIB, { extensions: [".js", ".mjs"] });
     let api;
     try {
@@ -49,14 +50,24 @@ const module$1 = defineNuxtModule({
       addImports(api.values.filter((value) => /^use[A-Z]/.test(value.name)).map((value) => ({ name: value.name, as: `use${prefix}${value.name.slice(3)}`, from: value.import })));
     }
     if (css) nuxt.options.css.push(`${LIB}/styles`);
-    const preset = typeof locale === "string" && locale !== "en" ? LOCALE_PRESETS[locale] : void 0;
-    if (typeof locale === "string" && locale !== "en" && !preset) logger.warn(`Unknown locale preset '${locale}', using English`);
+    const auto = locale === "auto";
+    const preset = typeof locale === "string" && locale !== "en" && !auto ? LOCALE_PRESETS[locale] : void 0;
+    if (typeof locale === "string" && locale !== "en" && !auto && !preset) logger.warn(`Unknown locale preset '${locale}', using English`);
+    if (auto) {
+      nuxt.hook("modules:done", () => {
+        if (!hasNuxtModule("@nuxtjs/i18n")) logger.warn(`locale: 'auto' follows @nuxtjs/i18n, which isn't installed: using English`);
+      });
+    }
     addTemplate({
       filename: "m3ui.options.mjs",
       getContents: () => [
         preset ? `import { ${preset} } from '${LIB}/locales'` : "",
+        auto ? `import * as presets from '${LIB}/locales'` : "",
         `export const options = ${JSON.stringify(plugin)}`,
         `export const locale = ${preset ?? (typeof locale === "object" ? JSON.stringify(locale) : "undefined")}`,
+        `export const autoLocale = ${auto}`,
+        `export const localePresets = ${auto ? `{ ${Object.entries(LOCALE_PRESETS).map(([code, name]) => `${code}: presets.${name}`).join(", ")} }` : "{}"}`,
+        `export const cookies = ${JSON.stringify(cookies)}`,
         `export const themeScript = ${JSON.stringify(themeScript)}`
       ].join("\n")
     });
@@ -66,6 +77,9 @@ const module$1 = defineNuxtModule({
         `declare module '#build/m3ui.options.mjs' {`,
         `  export const options: import('${LIB}').M3UIOptions`,
         `  export const locale: Partial<import('${LIB}').M3Locale> | undefined`,
+        `  export const autoLocale: boolean`,
+        `  export const localePresets: Record<string, Partial<import('${LIB}').M3Locale>>`,
+        `  export const cookies: boolean`,
         `  export const themeScript: boolean`,
         `}`
       ].join("\n")

package/dist/runtime/plugin.js

@@ -1,11 +1,25 @@
+import { computed } from "vue";
 import { createM3UI, themeInitScript } from "@m3ui-vue/m3ui-vue";
-import { defineNuxtPlugin, useHead } from "#app";
-import { locale, options, themeScript } from "#build/m3ui.options.mjs";
+import { defineNuxtPlugin, useCookie, useHead } from "#app";
+import { autoLocale, cookies, locale, localePresets, options, themeScript } from "#build/m3ui.options.mjs";
 export default defineNuxtPlugin({
   name: "m3ui",
   enforce: "pre",
   setup(nuxtApp) {
-    nuxtApp.vueApp.use(createM3UI({ ...options, locale, isHydrating: () => !!nuxtApp.isHydrating }));
+    const read = (name) => useCookie(name, { decode: decodeURIComponent, readonly: true }).value;
+    const [width, height] = (read("m3-viewport") ?? "").split("x").map(Number);
+    const initialState = cookies ? {
+      theme: read("m3-theme"),
+      palette: read("m3-palette"),
+      contrast: read("m3-contrast"),
+      viewport: width && height ? { width, height } : void 0
+    } : void 0;
+    const appLocale = autoLocale ? computed(() => {
+      const i18n = nuxtApp.$i18n;
+      const tag = i18n?.localeProperties?.value.language || i18n?.locale.value || "";
+      return localePresets[tag.toLowerCase().split("-")[0]] ?? {};
+    }) : locale;
+    nuxtApp.vueApp.use(createM3UI({ ...options, locale: appLocale, cookies, initialState, isHydrating: () => !!nuxtApp.isHydrating }));
     if (import.meta.server && themeScript) {
       useHead({
         script: [{

package/package.json

@@ -1,8 +1,16 @@
 {
   "name": "@m3ui-vue/nuxt",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Nuxt module for m3ui-vue, the Material Design 3 component library for Vue 3 + Tailwind CSS v4",
-  "keywords": ["nuxt", "nuxt-module", "material-design", "material-3", "m3", "vue", "tailwindcss"],
+  "keywords": [
+    "nuxt",
+    "nuxt-module",
+    "material-design",
+    "material-3",
+    "m3",
+    "vue",
+    "tailwindcss"
+  ],
   "homepage": "https://m3ui.dev",
   "repository": {
     "type": "git",
@@ -41,19 +49,22 @@
     "@nuxt/kit": "^4.6.2"
   },
   "peerDependencies": {
-    "@m3ui-vue/m3ui-vue": "^1.0.2"
+    "@m3ui-vue/m3ui-vue": "^1.0.3"
   },
   "devDependencies": {
-    "@m3ui-vue/m3ui-vue": "^1.0.2",
+    "@m3ui-vue/m3ui-vue": "^1.0.3",
     "@nuxt/module-builder": "^1.0.3",
     "@nuxt/schema": "^4.6.2",
     "@nuxt/test-utils": "^4.3.4",
+    "@nuxtjs/i18n": "^10.6.0",
     "@tailwindcss/vite": "^4.3.3",
     "@types/node": "^24.0.0",
     "nuxt": "^4.6.2",
+    "playwright-core": "^1.64.1",
     "tailwindcss": "^4.3.3",
     "typescript": "^6.0.3",
     "vitest": "^5.0.5",
+    "vue": "^3.5.44",
     "vue-tsc": "^3.3.12"
   }
 }