@m3ui-vue/nuxt 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fadel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,127 @@
-# Temporary Holding Version
+# @m3ui-vue/nuxt
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<p>
+  <a href="https://www.npmjs.com/package/@m3ui-vue/nuxt"><img src="https://img.shields.io/npm/v/@m3ui-vue/nuxt?color=blue" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/@m3ui-vue/nuxt"><img src="https://img.shields.io/npm/l/@m3ui-vue/nuxt" alt="license"></a>
+</p>
+
+Nuxt module for [m3ui-vue](https://m3ui.dev), the Material Design 3 component library for Vue 3 + Tailwind CSS v4.
+
+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.
+
+## Install
+
+```bash
+pnpm add @m3ui-vue/nuxt @m3ui-vue/m3ui-vue
+pnpm add -D tailwindcss @tailwindcss/vite
+```
+
+```ts
+// nuxt.config.ts
+import tailwindcss from '@tailwindcss/vite'
+
+export default defineNuxtConfig({
+  modules: ['@m3ui-vue/nuxt'],
+  css: ['~/assets/main.css'],
+  vite: { plugins: [tailwindcss()] },
+  m3ui: {
+    palette: 'red',
+    locale: 'es',
+  },
+})
+```
+
+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
+/* assets/main.css */
+@import 'tailwindcss';
+@import '@m3ui-vue/m3ui-vue/theme';
+@import '@m3ui-vue/m3ui-vue/palettes';
+```
+
+Load the fonts as the [library's README](https://github.com/SrWither/m3ui-vue#fonts) says (Roboto and Material Symbols),
+for example in `app.head.link`.
+
+## Usage
+
+Components work in any page or component without importing them:
+
+```vue
+<template>
+  <MButton @click="toast.success('Saved')">Save</MButton>
+</template>
+
+<script setup lang="ts">
+const toast = useM3Toast()
+</script>
+```
+
+Each component is bundled only where it's used. `MChart`, `MCodeEditor`, `MJsonEditor`, `MMarkdown`,
+`MRichTextEditor`, `MTerminal`, `MQRCode` and `MBarcode` are registered when their optional dependency is installed
+(see the library's README).
+
+The composables are prefixed so they can't clash with other modules (`useDevice`, `useTheme`… are common names):
+
+| Library | Auto-imported as |
+|---|---|
+| `useTheme` | `useM3Theme` |
+| `useColorPalette` | `useM3ColorPalette` |
+| `useToast` | `useM3Toast` |
+| `useNotification` | `useM3Notification` |
+| `useLocale` | `useM3Locale` |
+| `useDevice` | `useM3Device` |
+| `useWindowSizeClass` | `useM3WindowSizeClass` |
+| `useFieldBg`, `useDebounce`, `usePageProgress`, `useSpring` | `useM3FieldBg`, `useM3Debounce`, `useM3PageProgress`, `useM3Spring` |
+
+Anything else (types, `palettes`, `motionSprings`…) is imported from `@m3ui-vue/m3ui-vue` as usual.
+
+## Options
+
+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 |
+| `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` |
+| `themeScript` | `true` | Inline `themeInitScript()` in `<head>` |
+
+## 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:
+
+```vue
+<ClientOnly>
+  <MIconButton :icon="theme === 'dark' ? 'dark_mode' : 'light_mode'" label="Theme" @click="cycle" />
+</ClientOnly>
+```
+
+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.
+
+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).
+
+## Development
+
+```bash
+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:types
+```
+
+## License
+
+MIT

package/dist/module.d.mts

@@ -0,0 +1,42 @@
+import * as _nuxt_schema from '@nuxt/schema';
+import { M3UIOptions, M3Locale } from '@m3ui-vue/m3ui-vue';
+
+/** The presets shipped in `@m3ui-vue/m3ui-vue/locales`, by language code. English is the built-in default. */
+declare const LOCALE_PRESETS: {
+    readonly es: "esLocale";
+    readonly fr: "frLocale";
+    readonly pt: "ptLocale";
+    readonly de: "deLocale";
+    readonly ja: "jaLocale";
+    readonly zh: "zhLocale";
+    readonly ko: "koLocale";
+};
+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.
+     */
+    locale?: LocalePreset | Partial<M3Locale>;
+    /** Auto-import the components (`<MButton>`…). Each one is bundled only where it's used. Default `true`. */
+    components?: boolean;
+    /**
+     * Auto-import the composables, prefixed so they can't clash with other modules: `useTheme` becomes `useM3Theme`,
+     * `useColorPalette` `useM3ColorPalette`… Set the `prefix`, or `false` to import them yourself from
+     * `@m3ui-vue/m3ui-vue`. Default `{ prefix: 'M3' }`.
+     */
+    composables?: boolean | {
+        prefix?: string;
+    };
+    /** Add the components' own stylesheet (`@m3ui-vue/m3ui-vue/styles`). Default `true`. */
+    css?: 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`.
+     */
+    themeScript?: boolean;
+}
+declare const _default: _nuxt_schema.NuxtModule<ModuleOptions, ModuleOptions, false>;
+
+export { _default as default };
+export type { LocalePreset, ModuleOptions };

package/dist/module.json

@@ -0,0 +1,12 @@
+{
+  "name": "@m3ui-vue/nuxt",
+  "configKey": "m3ui",
+  "compatibility": {
+    "nuxt": ">=3.0.0"
+  },
+  "version": "0.1.1",
+  "builder": {
+    "@nuxt/module-builder": "1.0.3",
+    "unbuild": "unknown"
+  }
+}

package/dist/module.mjs

@@ -0,0 +1,77 @@
+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';
+
+const LIB = "@m3ui-vue/m3ui-vue";
+const LOCALE_PRESETS = { es: "esLocale", fr: "frLocale", pt: "ptLocale", de: "deLocale", ja: "jaLocale", zh: "zhLocale", ko: "koLocale" };
+const OPTIONAL_ENTRIES = {
+  [`${LIB}/chart`]: "chart.js",
+  [`${LIB}/code-editor`]: "codemirror",
+  [`${LIB}/markdown`]: "markdown-it",
+  [`${LIB}/rich-text-editor`]: "@tiptap/vue-3",
+  [`${LIB}/terminal`]: "@xterm/xterm",
+  [`${LIB}/qrcode`]: "qrcode-generator",
+  [`${LIB}/barcode`]: "jsbarcode"
+};
+const module$1 = defineNuxtModule({
+  meta: {
+    name: "@m3ui-vue/nuxt",
+    configKey: "m3ui",
+    compatibility: { nuxt: ">=3.0.0" }
+  },
+  defaults: {
+    components: true,
+    composables: { prefix: "M3" },
+    css: 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 entry = await resolvePath(LIB, { extensions: [".js", ".mjs"] });
+    let api;
+    try {
+      api = JSON.parse(readFileSync(join(dirname(entry), "api.json"), "utf8"));
+    } catch {
+      logger.error(`Couldn't read ${LIB}'s dist/api.json: is ${LIB} installed?`);
+      return;
+    }
+    if (components) {
+      for (const component of api.components) {
+        const peer = OPTIONAL_ENTRIES[component.import];
+        if (peer && !await tryResolveModule(peer, nuxt.options.modulesDir)) continue;
+        addComponent({ name: component.name, export: component.name, filePath: component.import });
+      }
+    }
+    if (composables) {
+      const prefix = typeof composables === "object" ? composables.prefix ?? "" : "M3";
+      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`);
+    addTemplate({
+      filename: "m3ui.options.mjs",
+      getContents: () => [
+        preset ? `import { ${preset} } from '${LIB}/locales'` : "",
+        `export const options = ${JSON.stringify(plugin)}`,
+        `export const locale = ${preset ?? (typeof locale === "object" ? JSON.stringify(locale) : "undefined")}`,
+        `export const themeScript = ${JSON.stringify(themeScript)}`
+      ].join("\n")
+    });
+    addTypeTemplate({
+      filename: "types/m3ui.options.d.ts",
+      getContents: () => [
+        `declare module '#build/m3ui.options.mjs' {`,
+        `  export const options: import('${LIB}').M3UIOptions`,
+        `  export const locale: Partial<import('${LIB}').M3Locale> | undefined`,
+        `  export const themeScript: boolean`,
+        `}`
+      ].join("\n")
+    });
+    addPlugin(resolver.resolve("./runtime/plugin"));
+  }
+});
+
+export { module$1 as default };

package/dist/runtime/plugin.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("#app").Plugin<Record<string, unknown>> & import("#app").ObjectPlugin<Record<string, unknown>>;
+export default _default;

package/dist/runtime/plugin.js

@@ -0,0 +1,19 @@
+import { createM3UI, themeInitScript } from "@m3ui-vue/m3ui-vue";
+import { defineNuxtPlugin, useHead } from "#app";
+import { locale, 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 }));
+    if (import.meta.server && themeScript) {
+      useHead({
+        script: [{
+          key: "m3ui-theme",
+          innerHTML: themeInitScript({ palette: options.palette, contrast: options.contrast, persistPalette: options.persistPalette }),
+          tagPriority: "critical"
+        }]
+      });
+    }
+  }
+});

package/dist/types.d.mts

@@ -0,0 +1,3 @@
+export { default } from './module.mjs'
+
+export { type LocalePreset, type ModuleOptions } from './module.mjs'

package/package.json

@@ -1,6 +1,68 @@
 {
   "name": "@m3ui-vue/nuxt",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "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"
+  ],
+  "homepage": "https://m3ui.dev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SrWither/m3ui-vue-nuxt.git"
+  },
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/types.d.mts",
+      "import": "./dist/module.mjs"
+    }
+  },
+  "main": "./dist/module.mjs",
+  "typesVersions": {
+    "*": {
+      ".": [
+        "./dist/types.d.mts"
+      ]
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "nuxt-module-build prepare && nuxt-module-build build",
+    "prepack": "pnpm build",
+    "dev": "pnpm dev:prepare && nuxt dev playground",
+    "dev:build": "nuxt build playground",
+    "dev:prepare": "nuxt-module-build build --stub && nuxt-module-build prepare && nuxt prepare playground",
+    "test": "vitest run",
+    "test:watch": "vitest watch",
+    "test:types": "vue-tsc --noEmit && cd playground && vue-tsc --noEmit"
+  },
+  "dependencies": {
+    "@nuxt/kit": "^4.6.2"
+  },
+  "peerDependencies": {
+    "@m3ui-vue/m3ui-vue": "^1.0.2"
+  },
+  "devDependencies": {
+    "@m3ui-vue/m3ui-vue": "^1.0.2",
+    "@nuxt/module-builder": "^1.0.3",
+    "@nuxt/schema": "^4.6.2",
+    "@nuxt/test-utils": "^4.3.4",
+    "@tailwindcss/vite": "^4.3.3",
+    "@types/node": "^24.0.0",
+    "nuxt": "^4.6.2",
+    "tailwindcss": "^4.3.3",
+    "typescript": "^6.0.3",
+    "vitest": "^5.0.5",
+    "vue": "^3.5.44",
+    "vue-tsc": "^3.3.12"
+  }
+}