Phone Mask

https://github.com/desource-labs/phone-mask
Admin
Phone Mask is an ultra-lightweight international phone number formatter and validator that syncs...
Tokens:43,867
Snippets:335
Trust Score:7.5
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Development commands

Source: https://github.com/desource-labs/phone-mask/blob/main/README.md

Development commands for installing dependencies, building packages, running tests with coverage, starting the demo dev server, generating data from Google's library, refreshing benchmarks, and linting/formatting code. Use these for local development and maintenance.

```bash
# Install dependencies
pnpm install

# Build all packages
pnpm build

# Run unit tests with coverage report
pnpm test:unit:coverage

# Start demo dev server
pnpm dev:prepare
pnpm dev:demo

# Generate fresh data from Google's library
pnpm gen

# Refresh README benchmark section (optional, if needed)
pnpm readme:benchmarks

# Lint & format code (if you made changes)
pnpm lint
pnpm lint:fix
pnpm format
```

--------------------------------

### Install the package

Source: https://github.com/desource-labs/phone-mask/blob/main/packages/phone-mask-react/README.md

Commands to install the library using npm, yarn, or pnpm.

```bash
npm install @desource/phone-mask-react
# or
yarn add @desource/phone-mask-react
# or
pnpm add @desource/phone-mask-react
```

--------------------------------

### Start development server

Source: https://github.com/desource-labs/phone-mask/blob/main/CONTRIBUTING.md

Prepare and start the demo application with hot reloading.

```bash
# Start demo with hot reload
pnpm dev:prepare
pnpm dev:demo
```

--------------------------------

### Install and build project

Source: https://github.com/desource-labs/phone-mask/blob/main/CONTRIBUTING.md

Clone the repository, install dependencies, and build all packages.

```bash
# Clone your fork
git clone https://github.com/YOUR_USERNAME/phone-mask.git
cd phone-mask

# Install dependencies
pnpm install

# Build all packages
pnpm build
```

--------------------------------

### Install @desource/phone-mask-vue

Source: https://github.com/desource-labs/phone-mask/blob/main/packages/phone-mask-vue/README.md

Installation commands for npm, yarn, and pnpm.

```bash
npm install @desource/phone-mask-vue
# or
yarn add @desource/phone-mask-vue
# or
pnpm add @desource/phone-mask-vue
```

--------------------------------

### Install @desource/phone-mask-svelte

Source: https://github.com/desource-labs/phone-mask/blob/main/packages/phone-mask-svelte/README.md

Install the package with npm, yarn, or pnpm. Choose one command based on your package manager.

```bash
npm install @desource/phone-mask-svelte
# or
yarn add @desource/phone-mask-svelte
# or
pnpm add @desource/phone-mask-svelte
```

--------------------------------

### Install @desource/phone-mask

Source: https://github.com/desource-labs/phone-mask/blob/main/packages/phone-mask/README.md

Commands to install the package using npm, yarn, or pnpm.

```bash
npm install @desource/phone-mask
# or
yarn add @desource/phone-mask
# or
pnpm add @desource/phone-mask
```

--------------------------------

### Import components and utilities

Source: https://github.com/desource-labs/phone-mask/blob/main/packages/phone-mask-react/README.md

Examples for importing the PhoneInput component, the usePhoneMask hook, and core utilities.

```tsx
import { PhoneInput } from '@desource/phone-mask-react';
import '@desource/phone-mask-react/assets/lib.css'; // Import styles
```

```tsx
import { usePhoneMask } from '@desource/phone-mask-react';
```

```ts
import { getFlagEmoji, formatDigitsWithMap } from '@desource/phone-mask-react/core';
```

--------------------------------

### CSS Component Example

Source: https://github.com/desource-labs/phone-mask/blob/main/CONTRIBUTING.md

CSS example showing a component class using CSS custom properties and a focus state with a nested selector.

```css
.pi-input {
  /* Use CSS variables */
  background: var(--pi-bg);
  border: 1px solid var(--pi-border);

  /* Focus states */
  &:focus {
    border-color: var(--pi-border-focus);
    outline: none;
  }
}
```

--------------------------------

### Install @desource/phone-mask-nuxt with npm, yarn, or pnpm

Source: https://github.com/desource-labs/phone-mask/blob/main/packages/phone-mask-nuxt/README.md

Install the module using your preferred package manager. The module works out of the box with zero configuration.

```bash
npm install @desource/phone-mask-nuxt
# or
yarn add @desource/phone-mask-nuxt
# or
pnpm add @desource/phone-mask-nuxt
```

--------------------------------

### Commit message examples

Source: https://github.com/desource-labs/phone-mask/blob/main/CONTRIBUTING.md

Example git commit commands for common commit types. The breaking change example shows the '!' marker and the BREAKING CHANGE footer in the commit message body.

```bash
# New feature
git commit -m "feat(vue): add dark theme support"

# Bug fix
git commit -m "fix(core): correct GB phone mask format"

# Documentation
git commit -m "docs(readme): add migration guide"

# Breaking change
git commit -m "feat(vue)!: change prop name from 'value' to 'modelValue'

BREAKING CHANGE: Renamed 'value' prop to 'modelValue' for v-model support"
```

--------------------------------

### Shorthand and Full Options Usage

Source: https://github.com/desource-labs/phone-mask/blob/main/packages/phone-mask-svelte/README.md

Examples of using shorthand country codes, full configuration objects, and auto-detection.

```svelte
<!-- Shorthand -->
<input {@attach phoneMaskAttachment('DE')} />

<!-- Full options -->
<input {@attach phoneMaskAttachment({ country: 'DE', onChange: handleChange })} />

<!-- Auto-detect -->
<input {@attach phoneMaskAttachment({ detect: true, onCountryChange: handleCountryChange })} />
```

--------------------------------

### Shorthand and Full Options Usage

Source: https://github.com/desource-labs/phone-mask/blob/main/packages/phone-mask-svelte/README.md

Examples of using shorthand country codes, full configuration objects, and auto-detection.

```svelte
<!-- Shorthand -->
<input use:phoneMaskAction={'DE'} />

<!-- Full options -->
<input use:phoneMaskAction={{ country: 'DE', onChange: handleChange }} />

<!-- Auto-detect -->
<input use:phoneMaskAction={{ detect: true, onCountryChange: handleCountryChange }} />
```

--------------------------------

### Create release branch

Source: https://github.com/desource-labs/phone-mask/blob/main/RELEASE.md

Start from an up-to-date main branch and create a release branch. Replace X.Y.Z with the intended version.

```bash
git switch main
git pull --ff-only
git switch -c chore/release-X.Y.Z
```

--------------------------------

### Example Security Vulnerability Report

Source: https://github.com/desource-labs/phone-mask/blob/main/SECURITY.md

An example email report for a security vulnerability, showing the required format including subject, package, version, description, impact, reproduction steps, and suggested fix.

```text
Subject: [SECURITY] XSS vulnerability in PhoneInput component

Package: @desource/phone-mask-vue
Version: 0.2.0

Description:
The PhoneInput component does not properly sanitize user input in the
country search field, allowing XSS attacks.

Impact:
An attacker can inject malicious scripts that execute in the context
of the application.

Reproduction:
1. Open PhoneInput component
2. Enter: <script>alert('XSS')</script> in search field
3. Script executes

Suggested Fix:
Sanitize all user input before rendering or use textContent instead of innerHTML.
```

--------------------------------

### Apply the version

Source: https://github.com/desource-labs/phone-mask/blob/main/RELEASE.md

Run pnpm changeset:version to consume all pending changesets and update the five package versions and changelogs. A pnpm install is not required because internal packages use workspace:*.

```bash
pnpm changeset:version
```

--------------------------------

### Vue Component Example

Source: https://github.com/desource-labs/phone-mask/blob/main/CONTRIBUTING.md

Vue component example using Composition API with TypeScript. Defines props and emits interfaces, with defaults for modelValue and country.

```vue
<script setup lang="ts">
interface Props {
  modelValue?: string;
  country?: string;
}

interface Emits {
  (e: 'update:modelValue', value: string): void;
  (e: 'country-change', country: MaskFull): void;
}

const props = withDefaults(defineProps<Props>(), {
  modelValue: '',
  country: 'US'
});

const emit = defineEmits<Emits>();
</script>
```

--------------------------------

### Nuxt Module Integration

Source: https://github.com/desource-labs/phone-mask/blob/main/README.md

Install the Nuxt module, add it to nuxt.config.ts, and use the PhoneInput component.

```bash
npm install @desource/phone-mask-nuxt
```

```ts
// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@desource/phone-mask-nuxt']
});
```

```vue
<script setup>
import { ref } from 'vue';

const phone = ref('');
</script>

<template>
  <PhoneInput v-model="phone" country="US" />
</template>
```

--------------------------------

### TypeScript Function Example

Source: https://github.com/desource-labs/phone-mask/blob/main/CONTRIBUTING.md

TypeScript example showing a documented function that formats digits according to a mask template. Uses JSDoc comments and a return type of FormatResult.

```ts
/**
 * Format digits according to mask template
 * @param template - Mask template with # placeholders
 * @param digits - Raw digit string
 * @returns Formatted display and index map
 */
export function formatDigitsWithMap(template: string, digits: string): FormatResult {
  // Implementation
}
```

--------------------------------

### Contribution workflow commands

Source: https://github.com/desource-labs/phone-mask/blob/main/README.md

Commands for the contribution workflow: clone the repository, install dependencies, create a branch, commit changes, push the branch, and add a changeset for package releases. Run these in order to contribute to the project.

```bash
git clone https://github.com/YOUR_USERNAME/phone-mask.git
```

```bash
pnpm install
```

```bash
git checkout -b feature/my-feature
```

```bash
git commit -m "feat: add awesome feature"
```

```bash
git push origin feature/my-feature
```

```bash
pnpm changeset
```

--------------------------------

### TypeScript/Vanilla JS Formatting

Source: https://github.com/desource-labs/phone-mask/blob/main/README.md

Install the core package and use formatDigitsWithMap to format phone numbers manually.

```bash
npm install @desource/phone-mask
```

```ts
import { MasksFullMapEn } from '@desource/phone-mask';
import { formatDigitsWithMap } from '@desource/phone-mask/kit';

const mask = MasksFullMapEn.US.mask[0]; // "###-###-####"
const formatted = formatDigitsWithMap(mask, '2025551234').display;
// Result: "202-555-1234"
```

--------------------------------

### Raw Digits for Backend Processing with buildPhonePayload

Source: https://github.com/desource-labs/phone-mask/blob/main/packages/phone-mask/README.md

Shows how to build a backend payload with raw digits using createPhoneFormatter. The example defines a buildPhonePayload function that returns an object with country, phoneDigits, and optional phoneE164.

```ts
import { MasksFullMapEn, type CountryKey } from '@desource/phone-mask';
import { createPhoneFormatter, extractDigits, removeCountryCodePrefix } from '@desource/phone-mask/kit';

function buildPhonePayload(input: string, id: CountryKey) {
  const country = MasksFullMapEn[id];
  if (!country) return null;

  const formatter = createPhoneFormatter({ ...country, id });
  const inputWithoutCode = removeCountryCodePrefix(input);
  const localDigits = extractDigits(inputWithoutCode, formatter.getMaxDigits());

  return {
    country: id,
    phoneDigits: localDigits, // canonical backend field
    phoneE164: `${country.code}${localDigits}` // optional: with dialing prefix
  };
}
```

--------------------------------

### Multiple Mask Variants for GB

Source: https://github.com/desource-labs/phone-mask/blob/main/packages/phone-mask/README.md

Shows that some countries have multiple mask formats. The example retrieves the GB mask array and logs it, displaying three different mask patterns.

```ts
import { MasksFullMapEn } from '@desource/phone-mask';

const gb = MasksFullMapEn.GB;
console.log(gb.mask);
// [
//   "### ### ####",
//   "#### ######",
//   "## #### ####"
// ]
```

--------------------------------

### React PhoneInput Integration

Source: https://github.com/desource-labs/phone-mask/blob/main/README.md

Install the React package and use the PhoneInput component with the required CSS.

```bash
npm install @desource/phone-mask-react
```

```tsx
import { useState } from 'react';
import { PhoneInput } from '@desource/phone-mask-react';
import '@desource/phone-mask-react/assets/lib.css';

function App() {
  const [phone, setPhone] = useState('');

  return <PhoneInput value={phone} onChange={setPhone} country="US" />;
}
```

--------------------------------

### Access Country Data with MasksFullMapEn

Source: https://github.com/desource-labs/phone-mask/blob/main/packages/phone-mask/README.md

Shows how to access country data (name, code, mask, flag) using MasksFullMapEn. The example retrieves US data and logs its properties.

```ts
import { MasksFullMapEn, type MaskFull } from '@desource/phone-mask';

// Access country data
const us = MasksFullMapEn.US;

console.log(us.name); // "United States"
console.log(us.code); // "+1"
console.log(us.mask); // ["###-###-####"]
console.log(us.flag); // "🇺🇸"
```

--------------------------------

### Svelte 5 PhoneInput Integration

Source: https://github.com/desource-labs/phone-mask/blob/main/README.md

Install the Svelte package and use the PhoneInput component with bind:value.

```bash
npm install @desource/phone-mask-svelte
```

```svelte
<script lang="ts">
  import { PhoneInput } from '@desource/phone-mask-svelte';
  import '@desource/phone-mask-svelte/assets/lib.css';

  let phone = $state('');
</script>

<PhoneInput bind:value={phone} country="US" />
```

--------------------------------

### Bug report template (markdown)

Source: https://github.com/desource-labs/phone-mask/blob/main/CONTRIBUTING.md

Use this template when reporting a bug to provide a clear title, reproduction steps, expected vs actual behavior, and environment details. The example shows a placeholder update issue with country change, including browser and package versions.

```markdown
## Bug: Placeholder not updating on country change

**Steps:**

1. Select "United States"
2. Type phone number
3. Change country to "United Kingdom"

**Expected:** Placeholder updates to UK format
**Actual:** Placeholder remains US format

**Environment:**

- Browser: Chrome 120
- Vue: 3.4.0
- @desource/phone-mask-vue: 1.0.0
```

--------------------------------

### Migrate from Vue plugin to Nuxt module

Source: https://github.com/desource-labs/phone-mask/blob/main/packages/phone-mask-nuxt/README.md

Migration from the Vue plugin to the Nuxt module. The first block shows the old setup in main.ts, and the second shows the new Nuxt configuration. No component changes are required.

```ts
// main.ts
import PhoneMaskPlugin from '@desource/phone-mask-vue';
import '@desource/phone-mask-vue/assets/lib.css';

app.use(PhoneMaskPlugin);
```

```ts
// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@desource/phone-mask-nuxt']
});
```

--------------------------------

### Vue component with usePhoneMask for multi-tenant phone input

Source: https://github.com/desource-labs/phone-mask/blob/main/packages/phone-mask-vue/README.md

Use this Vue 3 script setup component to integrate phone masking with tenant-specific default countries and validation rules. It defines tenant policies with default countries and optional prefix regex rules, then uses usePhoneMask to manage the input. The template displays the default country and whether the tenant validation passes.

```vue
<script setup lang="ts">
import { computed, ref } from 'vue';
import { usePhoneMask, type PCountryKey } from '@desource/phone-mask-vue';

type TenantPolicy = {
  defaultCountry: PCountryKey;
  prefixRule?: RegExp;
};

const props = defineProps<{ tenantId: string }>();

const TENANT_POLICIES: Record<string, TenantPolicy> = {
  acme: { defaultCountry: 'US', prefixRule: /^(202|303)\d{7}$/ },
  globex: { defaultCountry: 'GB', prefixRule: /^7\d{9}$/ }
};

const tenantPolicy = computed(() => TENANT_POLICIES[props.tenantId] ?? { defaultCountry: 'US' as const });
const digits = ref('');

const {
  inputRef,
  digits: maskDigits,
  isComplete
} = usePhoneMask({
  value: digits,
  onChange: (value) => (digits.value = value),
  country: computed(() => tenantPolicy.value.defaultCountry)
});

const isTenantValid = computed(() => {
  if (!isComplete.value) return false;
  const rule = tenantPolicy.value.prefixRule;
  return rule ? rule.test(maskDigits.value) : true;
});
</script>

<template>
  <input ref="inputRef" type="tel" />
  <p>Default country: {{ tenantPolicy.defaultCountry }}</p>
  <p>Tenant validation: {{ isTenantValid ? 'pass' : 'fail' }}</p>
</template>
```

--------------------------------

### Send Raw Digits to Backend

Source: https://github.com/desource-labs/phone-mask/blob/main/packages/phone-mask-vue/README.md

Example of sending unformatted digits to a backend API using the change event.

```vue
<script setup lang="ts">
import { ref } from 'vue';
import { PhoneInput, type PMaskPhoneNumber } from '@desource/phone-mask-vue';

const phoneDigits = ref('');

const onPhoneChange = async (phone: PMaskPhoneNumber) => {
  await fetch('/api/profile/phone', {
    method: 'POST',
    headers: { 'content-type': 'application/json' },
    body: JSON.stringify({
      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="onPhoneChange" />
</template>
```

--------------------------------

### Utility Functions: countPlaceholders, removeCountryCodePrefix, pickMaskVariant, extractDigits

Source: https://github.com/desource-labs/phone-mask/blob/main/packages/phone-mask/README.md

Shows usage of utility functions from '@desource/phone-mask/kit': countPlaceholders, removeCountryCodePrefix, pickMaskVariant, and extractDigits. Each function is demonstrated with example inputs and outputs.

```ts
import { countPlaceholders, removeCountryCodePrefix, pickMaskVariant, extractDigits } from '@desource/phone-mask/kit';

// Count placeholder digits
const count = countPlaceholders('+1 ###-###-####');
// 10

// Remove country code prefix
const stripped = removeCountryCodePrefix('+1 ###-###-####');
// "###-###-####"

// Pick best mask variant for digit count
const variants = ['+44 ### ### ####', '+44 #### ######'];
const best = pickMaskVariant(variants, 11);
// "+44 #### ######"

// Extract only digits from string
const digits = extractDigits('+1 (202) 555-1234');
// "12025551234"
```

--------------------------------

### Localized Country Names with MasksFullMap

Source: https://github.com/desource-labs/phone-mask/blob/main/packages/phone-mask/README.md

Shows how to get localized country names using MasksFullMap with a language code. The example retrieves German and French names for the US.

```ts
import { MasksFullMap } from '@desource/phone-mask';

// Get localized names
const germanMap = MasksFullMap('de');
console.log(germanMap.US.name); // "Vereinigte Staaten"

const frenchMap = MasksFullMap('fr');
console.log(frenchMap.US.name); // "États-Unis"
```

--------------------------------

### Release preparation workflow with pnpm changeset

Source: https://github.com/desource-labs/phone-mask/blob/main/CONTRIBUTING.md

Use this sequence to prepare a release: create a release branch, add a changeset for all public packages, update versions and changelogs, then commit and push the branch to open a pull request to main. All public packages are a Changesets fixed group, so they share the same version and bump type; include every package in the changeset to copy the release summary to each changelog.

```bash
# Create the release branch
git switch -c chore/release-X.Y.Z

# Include every public package so the release summary is added to every changelog
pnpm changeset

# Update all package versions and changelogs
pnpm changeset:version

# Commit and open a pull request to main
git add .
git commit -m "chore: Release packages"
git push -u origin chore/release-X.Y.Z
```

--------------------------------

### Test Your Changes

Source: https://github.com/desource-labs/phone-mask/blob/main/CONTRIBUTING.md

Runs the full test and verification suite: builds packages, prepares and runs the demo, lints, formats, and executes unit, coverage, and e2e tests.

```bash
# Build packages
pnpm build

# Run demo to verify visually
pnpm dev:prepare
pnpm dev:demo

# Run linting
pnpm lint
pnpm lint:fix

# Format code
pnpm format

# Run tests
pnpm test:unit
pnpm test:unit:coverage
pnpm test:e2e
```

--------------------------------

### Run tests

Source: https://github.com/desource-labs/phone-mask/blob/main/CONTRIBUTING.md

Execute unit tests, unit tests with coverage, or end-to-end tests.

```bash
# Run unit tests
pnpm test:unit

# Run unit tests with coverage
pnpm test:unit:coverage

# Run E2E tests
pnpm test:e2e
```

--------------------------------

### Create release changeset

Source: https://github.com/desource-labs/phone-mask/blob/main/RELEASE.md

Run pnpm changeset to create a changeset. In the prompts, select every public package, choose the same major/minor/patch bump, write the release summary, and confirm the generated changeset.

```bash
pnpm changeset
```

--------------------------------

### Import library modules

Source: https://github.com/desource-labs/phone-mask/blob/main/packages/phone-mask/README.md

Import country metadata from the root and utility helpers from the kit subpath.

```typescript
import { MasksFullMapEn, type CountryKey } from '@desource/phone-mask';
import { createPhoneFormatter, formatDigitsWithMap } from '@desource/phone-mask/kit';
```

--------------------------------

### Import Core Utilities

Source: https://github.com/desource-labs/phone-mask/blob/main/packages/phone-mask-vue/README.md

Access core kit utilities and mask data from the core subpath.

```ts
import { getFlagEmoji, formatDigitsWithMap } from '@desource/phone-mask-vue/core';
```

--------------------------------

### Vue 3 PhoneInput Integration

Source: https://github.com/desource-labs/phone-mask/blob/main/README.md

Install the Vue package and use the PhoneInput component with v-model binding.

```bash
npm install @desource/phone-mask-vue
```

```vue
<script setup>
import { ref } from 'vue';
import { PhoneInput } from '@desource/phone-mask-vue';
import '@desource/phone-mask-vue/assets/lib.css';

const phone = ref('');
</script>

<template>
  <PhoneInput v-model="phone" country="US" />
</template>
```

--------------------------------

### Programmatic Control with PhoneInputExposed

Source: https://github.com/desource-labs/phone-mask/blob/main/packages/phone-mask-svelte/README.md

Demonstrates programmatic control via the PhoneInputExposed type and bind:this. Provides methods focus(), clear(), selectCountry(), getFullFormattedNumber(), and isValid() to manipulate the input from outside.

```svelte
<script lang="ts">
  import { PhoneInput } from '@desource/phone-mask-svelte';
  import type { PhoneInputExposed } from '@desource/phone-mask-svelte';

  let phone = $state('');
  let phoneInput = $state<PhoneInputExposed | null>(null);
</script>

<PhoneInput bind:this={phoneInput} bind:value={phone} />

<div>
  <button onclick={() => phoneInput?.focus()}>Focus</button>
  <button onclick={() => phoneInput?.clear()}>Clear</button>
  <button onclick={() => phoneInput?.selectCountry('GB')}>Switch to UK</button>
  <p>Full: {phoneInput?.getFullFormattedNumber()}</p>
  <p>Valid: {phoneInput?.isValid()}</p>
</div>
```

--------------------------------

### Get Flag Emojis

Source: https://github.com/desource-labs/phone-mask/blob/main/packages/phone-mask/README.md

Retrieves the flag emoji for a given country code using the getFlagEmoji utility.

```ts
import { getFlagEmoji } from '@desource/phone-mask';

// Get flag emoji for country code
const flag = getFlagEmoji('US'); // "🇺🇸"
```

--------------------------------

### PhoneInput ref methods usage

Source: https://github.com/desource-labs/phone-mask/blob/main/packages/phone-mask-react/README.md

Shows how to create a ref and call the imperative methods for focus, blur, clear, selection, and number retrieval.

```tsx
const phoneInputRef = useRef<PhoneInputRef>(null);

phoneInputRef.current?.focus(); // Focuses the input
phoneInputRef.current?.blur(); // Blurs the input
phoneInputRef.current?.clear(); // Clears the input value
phoneInputRef.current?.selectCountry('GB'); // Programmatically selects a country by ISO code (e.g., 'US', 'DE', 'GB')
phoneInputRef.current?.getFullNumber(); // Returns the full phone number with country code (e.g., +1234567890)
phoneInputRef.current?.getFullFormattedNumber(); // Returns the full phone number formatted according to country rules (e.g., +1 234-567-890)
phoneInputRef.current?.getDigits(); // Returns only the digits of the phone number without country code (e.g., 234567890)
phoneInputRef.current?.isValid(); // Checks if the current phone number is valid
phoneInputRef.current?.isComplete(); // Checks if the current phone number is complete

```

--------------------------------

### Package File Structure

Source: https://github.com/desource-labs/phone-mask/blob/main/packages/phone-mask-react/README.md

Displays the directory layout of the @desource/phone-mask-react package, including build artifacts and configuration files.

```text
@desource/phone-mask-react/
├── dist/
│   ├── index.mjs               # Main ESM entry
│   ├── index.cjs               # Main CommonJS entry
│   ├── core.mjs                # Core kit utilities and mask data subpath
│   ├── core.cjs                # Core kit utilities and mask data CJS subpath
│   ├── phone-mask-react.css    # Component styles
│   └── types/                  # TypeScript declarations
├── README.md                   # This file
└── package.json                # Package manifest
```

--------------------------------

### Basic Formatting with formatDigitsWithMap

Source: https://github.com/desource-labs/phone-mask/blob/main/packages/phone-mask/README.md

Shows how to import MasksBaseMap, MasksMap, and formatDigitsWithMap to format phone numbers. Demonstrates formatting with and without country code prefix, and shows the resulting display string and map array.

```ts
import { MasksBaseMap, MasksMap } from '@desource/phone-mask';
import { formatDigitsWithMap } from '@desource/phone-mask/kit';

// Get US mask with country code prefix
const prefixUsMask = MasksBaseMap.US;
// ["+1 ###-###-####"]

// Format digits
const result = formatDigitsWithMap(prefixUsMask[0], '2025551234');
console.log(result.display); // "+1 202-555-1234"
console.log(result.map); // [-1, -1, -1, 0, 1, 2, -1, 3, 4, 5, -1, 6, 7, 8, 9]

// Get US mask without country code prefix
const usMask = MasksMap.US.mask;
// ["###-###-####"]

// Format digits without country code
const resultNoCode = formatDigitsWithMap(usMask[0], '2025551234');
console.log(resultNoCode.display); // "202-555-1234"
console.log(resultNoCode.map); // [0, 1, 2, -1, 3, 4, 5, -1, 6, 7, 8, 9]
```

--------------------------------

### Dark Theme with theme prop

Source: https://github.com/desource-labs/phone-mask/blob/main/packages/phone-mask-vue/README.md

Use the theme="dark" prop on the PhoneInput component to apply a dark theme. This is a Vue template example.

```vue
<template>
  <PhoneInput v-model="phone" theme="dark" />
</template>
```

--------------------------------

### Project structure overview

Source: https://github.com/desource-labs/phone-mask/blob/main/CONTRIBUTING.md

A visual representation of the monorepo directory structure, excluding generated files.

```text
phone-mask/
├── packages/
│   ├── phone-mask/              # Core package
│   │   ├── src/
│   │   │   ├── data.json        # Source-of-truth phone metadata
│   │   │   ├── data.min.js      # Generated compact metadata
│   │   │   ├── data-types.ts    # Generated metadata typings
│   │   │   ├── entries.ts       # Static maps/entries exports
│   │   │   ├── formatter.ts
│   │   │   ├── handlers.ts
│   │   │   ├── services/
│   │   │   ├── utils.ts
│   │   │   └── index.ts
│   │   ├── scripts/
│   │   │   └── gen.mts          # Metadata generator (Google libphonenumber release artifacts)
│   │   └── tests/
│   │       └── unit/
│
│   ├── phone-mask-react/        # React package
│   │   ├── src/                 # components/, hooks/, types.ts, index.ts
│   │   └── tests/               # unit + e2e
│   │
│   ├── phone-mask-vue/          # Vue package
│   │   ├── src/                 # components/, composables/, directives/, types.ts, index.ts
│   │   └── tests/               # unit + e2e
│   │
│   ├── phone-mask-svelte/       # Svelte package
│   │   ├── src/                 # components/, composables/, directives/, types.ts, index.ts
│   │   └── tests/               # unit + e2e
│   │
│   └── phone-mask-nuxt/         # Nuxt module package
│       ├── src/                 # module.ts + runtime/
│       └── tests/               # unit + e2e fixtures
│
├── common/
│   └── tests/                   # Shared test contracts/utilities for framework packages
│       ├── unit/
│       └── e2e/
│
├── scripts/
│   ├── update-readme-benchmarks.mts
│   ├── build-coverage-pr-report.mts
│   └── comment-coverage-pr.mts

├── demo/                        # Nuxt playground/demo app
│   ├── app/
│   └── nuxt.config.ts
│
├── .changeset/                  # Changesets entries for release notes/versioning
└── .github/
    ├── PULL_REQUEST_TEMPLATE.md
    └── workflows/
        ├── coverage.yml         # Coverage on main + optional manual PR report
        ├── release.yml          # Changesets publish workflow
        ├── weekly-gen.yml       # Weekly metadata sync PR
        └── weekly-benchmarks.yml # Weekly README benchmark refresh PR
```

--------------------------------

### Accessing Exposed Methods with bind:this

Source: https://github.com/desource-labs/phone-mask/blob/main/packages/phone-mask-svelte/README.md

Demonstrates how to access component methods by binding the component instance to a variable.

```svelte
<script lang="ts">
  import { PhoneInput } from '@desource/phone-mask-svelte';
  import type { PhoneInputExposed } from '@desource/phone-mask-svelte';

  let phoneInput = $state<PhoneInputExposed | null>(null);
</script>

<PhoneInput bind:this={phoneInput} />
<button onclick={() => phoneInput?.focus()}>Focus</button>
```

--------------------------------

### Reactive country with v-phone-mask

Source: https://github.com/desource-labs/phone-mask/blob/main/packages/phone-mask-vue/README.md

Bind a reactive selectedCountry ref to the v-phone-mask country option. The example includes a select element to change the country and an input that uses the directive with a change handler.

```vue
<script setup lang="ts">
import type { PMaskPhoneNumber } from '@desource/phone-mask-vue';

const selectedCountry = ref('US');

const handleChange = (phone: PMaskPhoneNumber) => {
  console.log('Phone:', phone.full, 'Digits:', phone.digits);
};
</script>

<template>
  <select v-model="selectedCountry">
    <option value="US">🇺🇸 United States</option>
    <option value="GB">🇬🇧 United Kingdom</option>
  </select>

  <input
    v-phone-mask="{
      country: selectedCountry,
      onChange: handleChange
    }"
  />
</template>
```

--------------------------------

### Commit Your Changes

Source: https://github.com/desource-labs/phone-mask/blob/main/CONTRIBUTING.md

Stages all changes and commits them with a conventional commit message. See the Commit Guidelines for the required format.

```bash
git add .
git commit -m "feat: add amazing feature"
```

--------------------------------

### MasksFullMap and MasksFull functions

Source: https://github.com/desource-labs/phone-mask/blob/main/packages/phone-mask/README.md

Functions to get full country data with localized country names. Supported locales include en, de, fr, es, it, pt, ru, zh, ja, ko, and more.

```typescript
function MasksFullMap(locale: string): MaskFullMap;
function MasksFull(locale: string): MaskFull[];
```

--------------------------------

### Multi-tenant: tenantId Default Country + Tenant-specific Validation Rules

Source: https://github.com/desource-labs/phone-mask/blob/main/packages/phone-mask/README.md

Creates a phone service for a tenant with a default country and optional prefix rule. Uses TENANT_POLICIES to map tenant IDs to policies, and returns format and validate functions that use the formatter.

```TypeScript
import { MasksFullMapEn, type CountryKey } from '@desource/phone-mask';
import { createPhoneFormatter, extractDigits, removeCountryCodePrefix } from '@desource/phone-mask/kit';

type TenantPolicy = {
  defaultCountry: CountryKey;
  prefixRule?: RegExp;
};

const TENANT_POLICIES: Record<string, TenantPolicy> = {
  acme: { defaultCountry: 'US', prefixRule: /^(202|303)\d{7}$/ },
  globex: { defaultCountry: 'GB', prefixRule: /^7\d{9}$/ }
};

function createTenantPhoneService(tenantId: string) {
  const policy = TENANT_POLICIES[tenantId] ?? { defaultCountry: 'US' as const };
  const id = policy.defaultCountry;
  const country = MasksFullMapEn[id];
  const formatter = createPhoneFormatter({ ...country, id });

  return {
    defaultCountry: id,
    format(input: string) {
      const inputWithoutCode = removeCountryCodePrefix(input);
      const digits = extractDigits(inputWithoutCode, formatter.getMaxDigits());
      return formatter.formatDisplay(digits);
    },
    validate(input: string) {
      const inputWithoutCode = removeCountryCodePrefix(input);
      const digits = extractDigits(inputWithoutCode, formatter.getMaxDigits());
      const complete = formatter.isComplete(digits);
      const prefixOk = policy.prefixRule ? policy.prefixRule.test(digits) : true;
      return complete && prefixOk;
    }
  };
}
```

--------------------------------

### Changeset management commands

Source: https://github.com/desource-labs/phone-mask/blob/main/RELEASE.md

A collection of pnpm commands to manage changesets, inspect status, version packages, and publish releases.

```bash
# Create a changeset
pnpm changeset

# Inspect pending changesets and calculated bumps
pnpm changeset status

# Consume changesets and update package versions/changelogs
pnpm changeset:version

# Build and publish unpublished versions without creating Git tags
pnpm changeset:publish
```

--------------------------------

### Update @desource/phone-mask Packages to Latest

Source: https://github.com/desource-labs/phone-mask/blob/main/SECURITY.md

Commands to update the @desource/phone-mask packages to the latest versions using pnpm.

```bash
# Update to latest
pnpm update @desource/phone-mask@latest
pnpm update @desource/phone-mask-vue@latest
pnpm update @desource/phone-mask-nuxt@latest
```

--------------------------------

### Multi-tenant: TenantId Default Country and Validation Rules

Source: https://github.com/desource-labs/phone-mask/blob/main/packages/phone-mask-svelte/README.md

Shows how to implement tenant-specific default countries and custom validation rules using derived state and the usePhoneMask hook.

```svelte
<script lang="ts">
  import { usePhoneMask, type PCountryKey } from '@desource/phone-mask-svelte';

  type TenantPolicy = {
    defaultCountry: PCountryKey;
    prefixRule?: RegExp;
  };

  let { tenantId }: { tenantId: string } = $props();

  const TENANT_POLICIES: Record<string, TenantPolicy> = {
    acme: { defaultCountry: 'US', prefixRule: /^(202|303)\d{7}$/ },
    globex: { defaultCountry: 'GB', prefixRule: /^7\d{9}$/ }
  };

  const policy = $derived(TENANT_POLICIES[tenantId] ?? { defaultCountry: 'US' as const });
  let digits = $state('');

  const phoneMask = usePhoneMask({
    value: () => digits,
    onChange: (value) => (digits = value),
    country: () => policy.defaultCountry
  });

  const isTenantValid = $derived(
    phoneMask.isComplete && (policy.prefixRule ? policy.prefixRule.test(phoneMask.digits) : true)
  );
</script>

<input bind:this={phoneMask.inputRef} type="tel" />
<p>Default country: {policy.defaultCountry}</p>
<p>Tenant validation: {isTenantValid ? 'pass' : 'fail'}</p>
```

--------------------------------

### Validate Number Against Country Rules with createPhoneFormatter

Source: https://github.com/desource-labs/phone-mask/blob/main/packages/phone-mask/README.md

Shows how to use createPhoneFormatter to validate a phone number's length against a specific country's mask variants. The example defines a validateForCountry function that returns digits, display, and isComplete status.

```ts
import { MasksFullMapEn, type CountryKey } from '@desource/phone-mask';
import { createPhoneFormatter, extractDigits, removeCountryCodePrefix } from '@desource/phone-mask/kit';

function validateForCountry(input: string, id: CountryKey) {
  const country = MasksFullMapEn[id];
  if (!country) {
    return {
      digits: '',
      display: '',
      isComplete: false
    };
  }

  const formatter = createPhoneFormatter({ ...country, id });
  const inputWithoutCode = removeCountryCodePrefix(input);
  const digits = extractDigits(inputWithoutCode, formatter.getMaxDigits());

  return {
    digits,
    display: formatter.formatDisplay(digits),
    isComplete: formatter.isComplete(digits)
  };
}

validateForCountry('+1 (202) 555-1234', 'US');
// { digits: "2025551234", display: "202-555-1234", isComplete: true }
```

--------------------------------

### Open and merge release pull request

Source: https://github.com/desource-labs/phone-mask/blob/main/RELEASE.md

Stage, commit, and push the release changes. Open a pull request to main and squash-merge it, keeping the squash commit message as 'chore: Release packages' to trigger the release workflow.

```bash
git add .
git commit -m "chore: Release packages"
git push -u origin chore/release-X.Y.Z
```

--------------------------------

### Using usePhoneMask composable and PMaskHelpers in SFC

Source: https://github.com/desource-labs/phone-mask/blob/main/packages/phone-mask-nuxt/README.md

Shows how to use the auto-imported usePhoneMask composable and PMaskHelpers in a Vue SFC without manual imports. The composable provides inputRef and setCountry, and PMaskHelpers.MasksMap.DE.code is displayed.

```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>
```

--------------------------------

### usePhoneMask composable usage in Vue

Source: https://github.com/desource-labs/phone-mask/blob/main/packages/phone-mask-vue/README.md

Use this composable in a Vue component to manage a phone input with masking. It requires controlled behavior: both `value` and `onChange` options are required. The example shows attaching `inputRef` to an input element, switching country with `setCountry('GB')`, clearing with `clear`, and displaying the formatted number and validation state.

```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>
```

--------------------------------

### Run Release workflow via GitHub CLI

Source: https://github.com/desource-labs/phone-mask/blob/main/RELEASE.md

Use this command to manually trigger the release workflow if the automatic process was interrupted.

```bash
gh workflow run Release
```

--------------------------------

### Reactive Country Selection

Source: https://github.com/desource-labs/phone-mask/blob/main/packages/phone-mask-svelte/README.md

Demonstrates how to use reactive state to update the phone mask dynamically when the country changes.

```svelte
<script lang="ts">
  import { phoneMaskAction as phoneMask } from '@desource/phone-mask-svelte';

  let selectedCountry = $state('US');
  let phoneData = $state<{ full: string; digits: string } | null>(null);
</script>

<select bind:value={selectedCountry}>
  <option value="US">🇺🇸 United States</option>
  <option value="GB">🇬🇧 United Kingdom</option>
  <option value="DE">🇩🇪 Germany</option>
</select>

<input use:phoneMask={{ country: selectedCountry, onChange: (p) => (phoneData = p) }} placeholder="Phone number" />
```

--------------------------------

### Dynamic Mask Updates on Country Change

Source: https://github.com/desource-labs/phone-mask/blob/main/packages/phone-mask-svelte/README.md

Demonstrates how to use the usePhoneMask hook to update the phone mask dynamically when the selected country changes.

```svelte
<script lang="ts">
  import { usePhoneMask, type PCountryKey } from '@desource/phone-mask-svelte';

  let selectedCountry = $state<PCountryKey>('US');
  let digits = $state('');

  const phoneMask = usePhoneMask({
    value: () => digits,
    onChange: (value) => (digits = value),
    country: () => selectedCountry
  });

  function onCountrySelect(nextCountry: PCountryKey) {
    selectedCountry = nextCountry;
    phoneMask.setCountry(nextCountry); // updates mask immediately
  }
</script>

<select
  value={selectedCountry}
  onchange={(e) => onCountrySelect((e.currentTarget as HTMLSelectElement).value as PCountryKey)}
>
  <option value="US">US</option>
  <option value="GB">GB</option>
  <option value="DE">DE</option>
</select>

<input bind:this={phoneMask.inputRef} type="tel" />
<p>{phoneMask.fullFormatted}</p>
<p>{phoneMask.isComplete ? 'complete' : 'incomplete'}</p>
```

--------------------------------

### Import usePhoneMask Composable

Source: https://github.com/desource-labs/phone-mask/blob/main/packages/phone-mask-vue/README.md

Import the usePhoneMask composable for advanced custom input needs.

```ts
import { usePhoneMask } from '@desource/phone-mask-vue';
```

--------------------------------

### Push and Create PR

Source: https://github.com/desource-labs/phone-mask/blob/main/CONTRIBUTING.md

Pushes the feature branch to the remote repository, after which a Pull Request can be opened on GitHub.

```bash
git push origin feature/amazing-feature
```

--------------------------------

### Import PhoneInput component

Source: https://github.com/desource-labs/phone-mask/blob/main/packages/phone-mask-svelte/README.md

Import the PhoneInput component and its styles for component mode.

```ts
import { PhoneInput } from '@desource/phone-mask-svelte';
import '@desource/phone-mask-svelte/assets/lib.css'; // Import styles
```

--------------------------------

### Update phone metadata manually

Source: https://github.com/desource-labs/phone-mask/blob/main/packages/phone-mask/README.md

Run this command to fetch the latest data from libphonenumber and regenerate the package's metadata files.

```bash
pnpm gen
```

--------------------------------

### PhoneInput Component API

Source: https://github.com/desource-labs/phone-mask/blob/main/packages/phone-mask-react/README.md

Documentation for the PhoneInput component props and ref methods.

```APIDOC
## PhoneInput Component

### Description
A React component for phone number input with country selection, formatting, and validation. It requires controlled behavior with `value` and `onChange` props.

### Props

#### Required Props
- **value** (string) - Required - Controlled value (digits only, without country code)
- **onChange** (function) - Required - Callback when the digits value changes. Returns only the digits without country code (e.g. '234567890')

#### Optional Props
- **id** (string) - Optional - id applied to the underlying `<input>` for forms/autofill
- **name** (string) - Optional - name applied to the underlying `<input>` for forms/autofill
- **country** (CountryKey) - Optional - Preselected country (ISO 3166-1 alpha-2)
- **detect** (boolean) - Optional - Auto-detect country from IP/locale. Default: true
- **locale** (string) - Optional - Locale for country names. Default: browser language
- **size** ('compact' | 'normal' | 'large') - Optional - Size variant. Default: 'normal'
- **theme** ('auto' | 'light' | 'dark') - Optional - Visual theme. Default: 'auto'
- **disabled** (boolean) - Optional - Disabled state. Default: false
- **readonly** (boolean) - Optional - Readonly state. Default: false
- **showCopy** (boolean) - Optional - Show copy button. Default: true
- **showClear** (boolean) - Optional - Show clear button. Default: false
- **withValidity** (boolean) - Optional - Show validation state (borders & outline). Default: true
- **searchPlaceholder** (string) - Optional - Custom search placeholder. Default: 'Search country or code...'
- **noResultsText** (string) - Optional - Custom no results text. Default: 'No countries found'
- **clearButtonLabel** (string) - Optional - Custom clear button label. Default: 'Clear phone number'
- **dropdownClass** (string) - Optional - Dropdown menu custom CSS class
- **disableDefaultStyles** (boolean) - Optional - Disable default styles. Default: false
- **onPhoneChange** (function) - Optional - Callback when the phone number changes. Provides an object with:
  - **full** (string) - Full phone number with country code (e.g. +1234567890)
  - **fullFormatted** (string) - Full phone number formatted according to country rules (e.g. +1 234-567-890)
  - **digits** (string) - Only the digits of the phone number without country code (e.g. 234567890)
- **onCountryChange** (function) - Optional - Callback when the selected country changes. Provides a `MaskFull` object.
- **onValidationChange** (function) - Optional - Callback when the validation state changes. Provides a boolean `isValid`.
- **onFocus** (function) - Optional - Callback when the input is focused. Provides a `FocusEvent<HTMLInputElement>`.
- **onBlur** (function) - Optional - Callback when the input is blurred. Provides a `FocusEvent<HTMLInputElement>`.
- **onCopy** (function) - Optional - Callback when phone number is copied. Provides the copied value as a string.
- **onClear** (function) - Optional - Callback when input is cleared.
- **renderActionsBefore** (function) - Optional - Render custom action buttons before default ones. Returns a `ReactNode`.
- **renderFlag** (function) - Optional - Render custom flag icons in the country list and country selector. Takes a `MaskFull` country and returns a `ReactNode`.
- **renderCopySvg** (function) - Optional - Render custom copy button SVG. Takes a boolean `copied` and returns a `ReactNode`.
- **renderClearSvg** (function) - Optional - Render custom clear button SVG. Returns a `ReactNode`.

### Ref Methods

#### focus()
Focuses the input.

#### blur()
Blurs the input.

#### clear()
Clears the input value.

#### selectCountry(countryCode)
Programmatically selects a country by ISO code (e.g., 'US', 'DE', 'GB').

#### getFullNumber()
Returns the full phone number with country code (e.g., +1234567890).

#### getFullFormattedNumber()
Returns the full phone number formatted according to country rules (e.g., +1 234-567-890).

#### getDigits()
Returns only the digits of the phone number without country code (e.g., 234567890).

#### isValid()
Checks if the current phone number is valid.

#### isComplete()
Checks if the current phone number is complete.
```

--------------------------------

### Implement Dark Theme via CSS

Source: https://github.com/desource-labs/phone-mask/blob/main/packages/phone-mask-react/README.md

Override CSS variables for the dark theme using the .theme-dark class.

```css
.desource-phone-input.theme-dark {
  --pi-bg: #1f2937;
  --pi-fg: #f9fafb;
  --pi-border: #374151;
}
```
Tokens:
Raw