@desource/phone-mask-nuxt 1.2.0 → 1.3.1

package/CHANGELOG.md

@@ -1,5 +1,57 @@
 # @desource/phone-mask-nuxt
 
+## 1.3.1
+
+### Patch Changes
+
+- Core Upgrades:
+  - Sync country masks with google-libphonenumber (🇸🇰 Slovakia updates)
+
+- Updated dependencies []:
+  - @desource/phone-mask-vue@1.3.1
+
+## 1.3.0
+
+### Minor Changes
+
+- Core Upgrades:
+  - Improved process keydown event handler for browser autocomplete cases
+
+- Vue Upgrades:
+  - Added new `@desource/phone-mask-vue/core` subpath export (direct core helpers re-export)
+  - Root `PMaskHelpers` facade removed from index (helpers now via `/core` to reduce bundle size impact for Vue users)
+  - Added `id` and `name` props on `PhoneInput`, passed to underlying `<input>` element for better form integration and accessibility
+  - Added autofill style normalization (`-webkit-autofill` / `-moz-autofill`) for better visual consistency
+
+- React Upgrades:
+  - Added new `@desource/phone-mask-react/core` subpath export (direct core helpers re-export)
+  - Root `PMaskHelpers` facade removed from index (helpers now via `/core` to reduce bundle size impact for React users)
+  - Added `id` and `name` props on `PhoneInput`, passed to underlying `<input>` element for better form integration and accessibility
+  - Added autofill style normalization (`-webkit-autofill` / `-moz-autofill`) for better visual consistency
+  - `useCountrySelector`, `useClipboard` internals stabilized (deps/callback consistency improvements)
+  - `usePhoneMask` callback dependency tuning for better stability
+
+- Svelte Upgrades:
+  - Added new `@desource/phone-mask-svelte/core` subpath export (direct core helpers re-export)
+  - Root `PMaskHelpers` facade removed from index (helpers now via `/core` to reduce bundle size impact for Svelte users)
+  - Added `id` and `name` props on `PhoneInput`, passed to underlying `<input>` element for better form integration and accessibility
+  - Added autofill style normalization (`-webkit-autofill` / `-moz-autofill`) for better visual consistency
+
+- Nuxt Upgrades:
+  - Module options expanded and clarified:
+    - `types` (default `true`): auto-import types from packages for TypeScript users
+    - `helpers` (default `false`): auto-import core helpers for direct usage in Nuxt apps (optional due to potential bundle size impact)
+    - new: `composable` (default `false`): auto-import Vue composable for custom phone mask logic (optional for users who only need more custom solution than the provided component/directive)
+  - Default auto-imports now focus on component/directive/types; helpers/composable are opt-in
+  - Runtime shared exports updated:
+    - `usePhoneMask` (composable) is now a separate export from `phoneMaskDirective` and `PhoneInput` component for more flexible usage patterns
+    - `PMaskHelpers` sourced via `@desource/phone-mask-vue/core` for better tree-shaking and bundle size control
+
+### Patch Changes
+
+- Updated dependencies []:
+  - @desource/phone-mask-vue@1.3.0
+
 ## 1.2.0
 
 ### Minor Changes

package/README.md

@@ -10,7 +10,7 @@ Drop-in Nuxt module with auto-imports, SSR support, and zero configuration.
 ## ✨ Features
 
 - 🎯 **Zero Config** — Works out of the box
-- 🔄 **Auto-imports** — Components and composables
+- 🔄 **Auto-imports** — Component, directive, and types by default
 - 🌐 **SSR Compatible** — Server-side rendering ready
 - 🎨 **Styleable** — Bring your own styles or use defaults
 - 🔧 **TypeScript** — Fully typed
@@ -36,7 +36,8 @@ export default defineNuxtConfig({
 });
 ```
 
-That's it! The component and directive are now auto-imported.
+That's it! The component, directive, and related mask types are now auto-imported.
+You can additionally enable helper/composable auto-imports via module options.
 
 ## 📖 Usage
 
@@ -109,6 +110,91 @@ const handleChange = (nextPhone: PMaskPhoneNumber) => {
 </script>
 ```
 
+### SSR + Auto-imports in Practice
+
+`@desource/phone-mask-nuxt` is SSR-safe: the module config is evaluated on server, while the UI component is registered in client mode.
+
+```vue
+<script setup lang="ts">
+const phone = ref('');
+const valid = ref(false);
+</script>
+
+<template>
+  <!-- Auto-imported: no explicit component import required -->
+  <PhoneInput id="phone" name="phone" v-model="phone" country="US" @validation-change="valid = $event" />
+
+  <p v-if="valid">✓ Ready to submit</p>
+</template>
+```
+
+### Backend Payload (Raw Digits)
+
+```vue
+<script setup lang="ts">
+import type { PMaskPhoneNumber } from '#imports';
+
+const phoneDigits = ref('');
+
+const handlePhoneChange = async (phone: PMaskPhoneNumber) => {
+  await $fetch('/api/profile/phone', {
+    method: 'POST',
+    body: {
+      phoneDigits: phone.digits, // unformatted value for backend
+      phoneFull: phone.full // optional full number with country code
+    }
+  });
+};
+</script>
+
+<template>
+  <PhoneInput v-model="phoneDigits" country="US" @change="handlePhoneChange" />
+</template>
+```
+
+### Auto-importing Helpers + Composable
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  modules: ['@desource/phone-mask-nuxt'],
+  phoneMask: {
+    // Disable auto-imported styles, component, and directive if you don't need them
+    css: false,
+    component: false,
+    directive: false,
+    // And enable only needed auto-imports
+    helpers: true,
+    composable: true
+  }
+});
+```
+
+Then use them directly in SFCs without manual imports:
+
+```vue
+<script setup lang="ts">
+const value = ref('');
+const selectedCountry = ref('US');
+
+const { inputRef, setCountry } = usePhoneMask({
+  value,
+  onChange: (digits) => (value.value = digits),
+  country: selectedCountry
+});
+
+const setGermany = () => {
+  setCountry('DE');
+};
+</script>
+
+<template>
+  <input ref="inputRef" type="tel" />
+  <button @click="setGermany">Use Germany</button>
+  <p>Code for DE: {{ PMaskHelpers.MasksMap.DE.code }}</p>
+</template>
+```
+
 ## ⚙️ Configuration
 
 ### Module Options
@@ -129,8 +215,26 @@ export default defineNuxtConfig({
     // Register v-phone-mask directive
     directive: true, // Default: true
 
-    // Register shared helpers and types
-    helpers: true // Default: true
+    // Register mask-related TypeScript types
+    types: true, // Default: true
+
+    // Register shared helper namespace + directive helper
+    helpers: false, // Default: false
+
+    // Register usePhoneMask composable
+    composable: false // Default: false
+  }
+});
+```
+
+### Enable Helpers and Composable Auto-imports
+
+```ts
+export default defineNuxtConfig({
+  modules: ['@desource/phone-mask-nuxt'],
+  phoneMask: {
+    helpers: true,
+    composable: true
   }
 });
 ```
@@ -243,7 +347,7 @@ export const useUserStore = defineStore('user', {
 
   actions: {
     setPhoneDigits(phone: string) {
-      this.phone = phone;
+      this.phoneDigits = phone;
     },
 
     setCountry(id: string) {
@@ -324,7 +428,7 @@ const phone = ref('');
 
 ## 🎯 Auto-imports
 
-The following are automatically imported (until disabled in nuxt.config.ts):
+By default (without extra options), Nuxt auto-imports:
 
 ### Components
 
@@ -334,22 +438,23 @@ The following are automatically imported (until disabled in nuxt.config.ts):
 
 - `vPhoneMask` — Phone mask directive
 
-### Helpers
+### Types
+
+- `PCountryKey`
+- `PMaskBase`, `PMaskBaseMap`
+- `PMask`, `PMaskMap`
+- `PMaskWithFlag`, `PMaskWithFlagMap`
+- `PMaskFull`, `PMaskFullMap`
+- `PMaskPhoneNumber`
 
-- `vPhoneMaskSetCountry` — Programmatically set country for directive
-- `PMaskHelpers` — Utility functions for phone masks like:
-  - `getFlagEmoji`
-  - `countPlaceholders`
-  - `formatDigitsWithMap`
-  - `pickMaskVariant`
-  - `removeCountryCodePrefix`
-  - And more...
+Enable `phoneMask.helpers: true` to auto-import:
 
-Read more about helpers in the [Utility Functions of @desource/phone-mask README](../phone-mask/README.md#utility-functions).
+- `vPhoneMaskSetCountry` — Programmatically set country for directive
+- `PMaskHelpers` — Utility functions from `@desource/phone-mask-vue/core`
 
-### Types
+Enable `phoneMask.composable: true` to auto-import:
 
-All TypeScript types from `@desource/phone-mask-vue`
+- `usePhoneMask`
 
 ## 🔄 Migration from Vue Plugin
 
@@ -378,11 +483,12 @@ No changes needed in your components!
 
 ## 📦 What's Included
 
-- `PhoneInput` component (auto-imported)
-- `vPhoneMask` directive (auto-imported)
-- Default styles (auto-imported, can be disabled)
-- TypeScript definitions (auto-imported)
-- Utility functions (auto-imported)
+- `PhoneInput` component (auto-imported by default)
+- `vPhoneMask` directive (auto-imported by default)
+- Mask-related TypeScript types (auto-imported by default)
+- Default styles (auto-imported by default, can be disabled)
+- `vPhoneMaskSetCountry` and `PMaskHelpers` (optional via `phoneMask.helpers`)
+- `usePhoneMask` (optional via `phoneMask.composable`)
 
 ## 🔗 Related
 

package/dist/module.d.mts

@@ -4,7 +4,9 @@ interface ModuleOptions {
     css?: boolean;
     component?: boolean;
     directive?: boolean;
+    types?: boolean;
     helpers?: boolean;
+    composable?: boolean;
 }
 declare const module$1: NuxtModule<ModuleOptions>;
 

package/dist/module.json

@@ -4,7 +4,7 @@
     "nuxt": ">=3.0.0"
   },
   "configKey": "phoneMask",
-  "version": "1.2.0",
+  "version": "1.3.1",
   "builder": {
     "@nuxt/module-builder": "1.0.2",
     "unbuild": "unknown"

package/dist/module.mjs

@@ -12,7 +12,9 @@ const module$1 = defineNuxtModule({
     css: true,
     component: true,
     directive: true,
-    helpers: true
+    types: true,
+    helpers: false,
+    composable: false
   },
   async setup(options, nuxt) {
     const { resolve } = createResolver(import.meta.url);
@@ -26,12 +28,19 @@ const module$1 = defineNuxtModule({
         addPlugin(resolve(runtimeDir, "plugin.phone-mask"));
       }
     });
+    const shared = resolve(runtimeDir, "shared");
     if (options.helpers) {
-      const shared = resolve(runtimeDir, "shared");
       addImports([
         { name: "vPhoneMaskSetCountry", from: shared },
         { name: "PMaskHelpers", from: shared },
-        { name: "vPhoneMask", from: shared },
+        { name: "vPhoneMask", from: shared }
+      ]);
+    }
+    if (options.composable) {
+      addImports({ name: "usePhoneMask", from: shared });
+    }
+    if (options.types) {
+      addImports([
         { name: "PCountryKey", from: shared, type: true },
         { name: "PMaskBase", from: shared, type: true },
         { name: "PMaskBaseMap", from: shared, type: true },

package/dist/runtime/shared.d.ts

@@ -1 +1,2 @@
-export { vPhoneMaskSetCountry, vPhoneMask, PMaskHelpers, type PCountryKey, type PMaskBase, type PMaskBaseMap, type PMask, type PMaskMap, type PMaskWithFlag, type PMaskWithFlagMap, type PMaskFull, type PMaskFullMap, type PMaskPhoneNumber } from '@desource/phone-mask-vue';
+export * as PMaskHelpers from '@desource/phone-mask-vue/core';
+export { vPhoneMaskSetCountry, vPhoneMask, usePhoneMask, type PCountryKey, type PMaskBase, type PMaskBaseMap, type PMask, type PMaskMap, type PMaskWithFlag, type PMaskWithFlagMap, type PMaskFull, type PMaskFullMap, type PMaskPhoneNumber } from '@desource/phone-mask-vue';

package/dist/runtime/shared.js

@@ -1,5 +1,6 @@
+export * as PMaskHelpers from "@desource/phone-mask-vue/core";
 export {
   vPhoneMaskSetCountry,
   vPhoneMask,
-  PMaskHelpers
+  usePhoneMask
 } from "@desource/phone-mask-vue";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@desource/phone-mask-nuxt",
-  "version": "1.2.0",
+  "version": "1.3.1",
   "description": "🎯 Zero-config Nuxt module for international phone masking. Powered by @desource/phone-mask with Google libphonenumber sync.",
   "type": "module",
   "exports": {
@@ -54,15 +54,15 @@
     "vue": "^3.4.33"
   },
   "dependencies": {
-    "@desource/phone-mask-vue": "1.2.0"
+    "@desource/phone-mask-vue": "1.3.1"
   },
   "devDependencies": {
     "@nuxt/kit": "^4.4.2",
     "@nuxt/module-builder": "^1.0.2",
-    "@nuxt/test-utils": "^4.0.0",
+    "@nuxt/test-utils": "^4.0.2",
     "nuxt": "^4.4.2",
     "vite": "7.3.1",
-    "vue": "^3.5.30"
+    "vue": "^3.5.33"
   },
   "scripts": {
     "dev:prepare": "nuxt prepare",