@desource/phone-mask-vue 0.3.0 → 1.1.0

package/CHANGELOG.md

@@ -1,5 +1,70 @@
 # @desource/phone-mask-vue
 
+## 1.1.0
+
+### Minor Changes
+
+- Svelte Upgrades:
+  - Added attachment `phoneMaskAttachment` for usage in native input (for Svelte 5.29+ versions)
+  - Added action `phoneMaskAction` for usage in native input (for Svelte 5.0+ versions)
+  - Improved keyboard country selection flow and active-descendant accessibility behavior
+  - Refined dropdown/key navigation handling and related focus behavior
+  - `usePhoneMask` now exposes `formatter` in the return object
+
+- Vue Upgrades:
+  - Directive was refactored to align with Svelte action
+  - Improved keyboard country selection flow and active-descendant accessibility behavior
+  - Refined dropdown/key navigation handling and related focus behavior
+  - `usePhoneMask` now exposes `formatter` in the return object
+
+- React Upgrades:
+  - Improved keyboard country selection flow and active-descendant accessibility behavior
+  - Refined dropdown/key navigation handling and related focus behavior
+  - `usePhoneMask` now exposes `formatter` in the return object
+
+- Core Upgrades:
+  - Fixed edge cases in mask variant selection and improved input handler robustness
+  - Applied reliability-focused refactors in formatter/handlers and build script generation logic
+
+### Patch Changes
+
+- Updated dependencies []:
+  - @desource/phone-mask@1.1.0
+
+## 1.0.0
+
+### Major Changes
+
+- Core Upgrades:
+  - Refactored core architecture for better separation of concerns and reusability
+  - Added zero-config browser script support path
+  - Improved Intl.DisplayNames caching for performance
+  - Fixed various edge cases in formatting and event handling
+  - Added comprehensive unit tests for core utilities and handlers
+
+- React Upgrades:
+  - Major internal refactor to a controlled pattern with consistent hooks
+  - Improved React 18/19 compatibility for ref behavior
+  - Added and expanded unit/e2e tests for React components and behavior
+
+- Vue Upgrades:
+  - Refactored to align composable structure and reuse core utilities
+  - Fixed directive behavior for external value updates and dropdown close logic
+  - Added substantial unit/e2e test coverage for Vue composables and directive
+
+- 🚀 Svelte Upgrades:
+  - Introduced Svelte version of phone-mask library
+
+- Nuxt Upgrades:
+  - Added full test foundation with @nuxt/test-utils
+  - Added unit tests for module and runtime behavior
+  - Added e2e fixtures/tests and shared e2e utilities
+
+### Patch Changes
+
+- Updated dependencies []:
+  - @desource/phone-mask@1.0.0
+
 ## 0.3.0
 
 ### Minor Changes

package/README.md

@@ -6,7 +6,7 @@
 [![bundle size](https://img.shields.io/bundlephobia/minzip/@desource/phone-mask-vue?label=gzip%20size&color=purple)](https://bundlephobia.com/package/@desource/phone-mask-vue)
 [![license](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/DeSource-Labs/phone-mask/blob/main/LICENSE)
 
-Beautiful, accessible, extreme small & tree-shackable Vue 3 phone input with auto-formatting, country selector, and validation.
+Beautiful, accessible, extreme small & tree-shakeable Vue 3 phone input with auto-formatting, country selector, and validation.
 
 ## ✨ Features
 
@@ -19,7 +19,7 @@ Beautiful, accessible, extreme small & tree-shackable Vue 3 phone input with aut
 - ♿ **Accessible** — ARIA labels, keyboard navigation
 - 📱 **Mobile-friendly** — Optimized for touch devices
 - 🎯 **TypeScript** — Full type safety
-- 🧩 **Two modes** — Component or directive
+- 🧩 **Three modes** — Component, composable, or directive
 - ⚡ **Optimized** — Tree-shaking and code splitting
 
 ## 📦 Installation
@@ -36,19 +36,36 @@ pnpm add @desource/phone-mask-vue
 
 ### Importing
 
+Component mode:
+
 ```ts
 import { createApp } from 'vue';
-import { PhoneInput, vPhoneMask } from '@desource/phone-mask-vue';
-import '@desource/phone-mask-vue/assets/lib.css'; // Import styles (for component mode only)
+import { PhoneInput } from '@desource/phone-mask-vue';
+import '@desource/phone-mask-vue/assets/lib.css'; // Import styles
 
 const app = createApp(App);
+app.component('PhoneInput', PhoneInput);
+app.mount('#app');
+```
+
+Directive mode (for custom input implementations):
 
-app.component('PhoneInput', PhoneInput); // Register component if you need component mode
-app.directive('phone-mask', vPhoneMask); // Register directive if you need directive mode
+```ts
+import { createApp } from 'vue';
+import { vPhoneMask } from '@desource/phone-mask-vue';
+
+const app = createApp(App);
+app.directive('phone-mask', vPhoneMask);
 app.mount('#app');
 ```
 
-If you need both modes:
+Composable mode (for custom input implementations in case even directive doesn't fit your needs):
+
+```ts
+import { usePhoneMask } from '@desource/phone-mask-vue';
+```
+
+Register all at once (component + directive):
 
 ```ts
 import { createApp } from 'vue';
@@ -56,8 +73,7 @@ import phoneMask from '@desource/phone-mask-vue';
 import '@desource/phone-mask-vue/assets/lib.css'; // Import styles for component mode
 
 const app = createApp(App);
-
-app.use(phoneMask); // Registers both component and directive
+app.use(phoneMask); // Registers component and directive
 app.mount('#app');
 ```
 
@@ -119,6 +135,35 @@ const handleChange = (phone: PMaskPhoneNumber) => {
 </template>
 ```
 
+### Composable Mode
+
+For custom input implementations (in case even directive doesn't fit your needs):
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { usePhoneMask } from '@desource/phone-mask-vue';
+
+const value = ref('');
+
+const { inputRef, digits, full, fullFormatted, isComplete, setCountry } = usePhoneMask({
+  value,
+  onChange: (newValue) => (value.value = newValue),
+  country: 'US',
+  detect: true
+});
+</script>
+
+<template>
+  <div>
+    <input ref="inputRef" type="tel" placeholder="Phone number" />
+    <p>Formatted: {{ fullFormatted }}</p>
+    <p>Valid: {{ isComplete ? 'Yes' : 'No' }}</p>
+    <button @click="setCountry('GB')">Use UK</button>
+  </div>
+</template>
+```
+
 ## 📖 Component API
 
 ### Props
@@ -405,6 +450,106 @@ const handleChange = (phone: PMaskPhoneNumber) => {
 </template>
 ```
 
+## 🪝 Composable API
+
+### `usePhoneMask`
+
+For custom input implementations:
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { usePhoneMask } from '@desource/phone-mask-vue';
+
+const value = ref('');
+
+const { inputRef, digits, full, fullFormatted, isComplete, setCountry, clear } = usePhoneMask({
+  value,
+  onChange: (newValue) => (value.value = newValue),
+  country: 'US',
+  detect: false
+});
+</script>
+
+<template>
+  <div>
+    <input ref="inputRef" type="tel" />
+    <button @click="setCountry('GB')">Switch to UK</button>
+    <button @click="clear">Clear</button>
+    <p>Full: {{ fullFormatted || '—' }}</p>
+    <p>Valid: {{ isComplete ? 'Yes' : 'No' }}</p>
+  </div>
+</template>
+```
+
+### Options
+
+> **Note:** The composable requires controlled behavior. Both `value` and `onChange` options are required.
+
+```ts
+interface UsePhoneMaskOptions {
+  // Controlled value (digits only, without country code) - REQUIRED
+  value: MaybeRefOrGetter<string>;
+
+  // Callback when the digits value changes - REQUIRED
+  onChange: (digits: string) => void;
+
+  // Predefined country ISO code (e.g., 'US', 'DE', 'GB')
+  country?: MaybeRefOrGetter<string | undefined>;
+
+  // Locale for country names (default: navigator.language)
+  locale?: MaybeRefOrGetter<string | undefined>;
+
+  // Auto-detect country from IP/locale (default: false)
+  detect?: MaybeRefOrGetter<boolean | undefined>;
+
+  // Callback when the phone changes (full, fullFormatted, digits)
+  onPhoneChange?: (phone: PhoneNumber) => void;
+
+  // Country change callback
+  onCountryChange?: (country: MaskFull) => void;
+}
+```
+
+### Return Value
+
+```ts
+interface UsePhoneMaskReturn {
+  // Ref to attach to your input element
+  inputRef: ShallowRef<HTMLInputElement | null>;
+
+  // Raw digits without formatting (e.g., "1234567890")
+  digits: ComputedRef<string>;
+
+  // Phone formatter instance
+  formatter: ComputedRef<FormatterHelpers>;
+
+  // Full phone number with country code (e.g., "+11234567890")
+  full: ComputedRef<string>;
+
+  // Full phone number formatted (e.g., "+1 123-456-7890")
+  fullFormatted: ComputedRef<string>;
+
+  // Whether the phone number is complete
+  isComplete: ComputedRef<boolean>;
+
+  // Whether the input is empty
+  isEmpty: ComputedRef<boolean>;
+
+  // Whether to show validation warning
+  shouldShowWarn: ComputedRef<boolean>;
+
+  // Current country data
+  country: ComputedRef<MaskFull>;
+
+  // Change country programmatically
+  setCountry: (countryCode?: string | null) => boolean;
+
+  // Clear the input
+  clear: () => void;
+}
+```
+
 ## 📚 Examples
 
 ### With Validation
@@ -439,12 +584,12 @@ const errorMessage = computed(() => {
 ```vue
 <script setup lang="ts">
 import { ref } from 'vue';
-import { PhoneInput, type MaskFull } from '@desource/phone-mask-vue';
+import { PhoneInput, type PMaskFull } from '@desource/phone-mask-vue';
 
 const phone = ref('');
 const detectedCountry = ref('');
 
-const handleCountryChange = (country: MaskFull) => {
+const handleCountryChange = (country: PMaskFull) => {
   detectedCountry.value = country.name;
 };
 </script>
@@ -538,6 +683,7 @@ const form = reactive({
 
 - [@desource/phone-mask](../phone-mask) — Core library
 - [@desource/phone-mask-nuxt](../phone-mask-nuxt) — Nuxt module
+- [@desource/phone-mask-react](../phone-mask-react) — React bindings
 
 ## 📄 License