## Special characters

The `special` property defines special characters to denote user input positions in the mask and configure their extended behavior.

**Possible values:**

- `string` — single special character (default `'*'`)
- `string[]` — array of special characters for different group types
- `MaskSpecialList` — object with extended configuration for each character

Special characters in the mask template denote positions where users can enter data, unlike literal characters that are inserted automatically.

When using a simple string (e.g., `special="*"`), all input positions in the mask are restricted by the same validation rules.

An array of characters (e.g., `special="['*', 'A', '#']"`) allows creating different group types with individual constraints: one group for digits, another for letters, a third for special characters.

Object notation `MaskSpecialList` (see [detailed description below](#maskspeciallist)) provides maximum flexibility. Each special character is configured separately with the ability to set default values, rubber groups with variable length, auto-transition characters, and custom validation.

For built-in types (`currency`, `number`, `date`, `time`), the system automatically generates special characters considering regional settings, ignoring the user-defined `special` value.

```html
<!-- Simple special character -->
<Mask mask="***-***" special="*" />

<!-- Multiple group types -->
<Mask mask="AA*-###" :special="['A', '*', '#']" />

<!-- Extended configuration -->
<Mask
  mask="***-***"
  :special="{
    '*': {
      pattern: '\\d',
      view: '_',
      rubber: true,
      minLength: 2,
      maxLength: 8,
      transitionChar: ' '
    }
  }"
/>

<!-- Groups with default values -->
<Mask
  mask="DD/MM/YYYY"
  :special="{
    'D': { defaultValue: '01', pattern: '\\d' },
    'M': { defaultValue: '01', pattern: '\\d' },
    'Y': { defaultValue: '2024', pattern: '\\d' }
  }"
/>
```

## MaskSpecialList

`MaskSpecialList` — object with extended configuration for mask special characters, where each key corresponds to a special character in the template.

### Type structure

```typescript
type MaskSpecialList = Record<string, MaskSpecialItem>

interface MaskSpecialItem {
  /** Default value for the group */
  defaultValue?: string

  /** Enables variable-length mode (rubber group) */
  rubber?: boolean

  /** Characters for automatic transition to the next group */
  transitionChar?: string | string[]

  /** Minimum length for rubber group */
  minLength?: number

  /** Maximum length for rubber group */
  maxLength?: number

  /** Regular expression for character validation */
  match?: RegExp | string

  /** Pattern for group validation */
  pattern?: FieldPatternItemOrFunction

  /** Displayed placeholder character */
  view?: string
}
```

### Properties

#### `defaultValue`

String with the initial value for the group. Automatically inserted on initialization or when the user hasn't entered data.

#### `rubber`

Boolean value enabling rubber group mode with variable length. Allows users to enter from `minLength` to `maxLength` characters in one group.

#### `transitionChar`

Character or array of characters that complete the rubber group and move the cursor to the next part of the mask. Only works with rubber groups (`rubber: true`).

#### `minLength`

Minimum number of characters for rubber group. Only works with `rubber: true`.

#### `maxLength`

Maximum number of characters for rubber group. Only works with `rubber: true`.

#### `match`

Regular expression or string for validating entered characters in the group.

#### `pattern`

Regular expression or string for validating characters in the current group during input. Can also be a function that dynamically returns a pattern based on mask data.

**Type:**

```typescript
type FieldPatternItemOrFunction = FieldPatternItem | ((item: FieldMasks) => FieldPatternItem)
type FieldPatternItem = string | Partial<HTMLInputElement>
```

Where `FieldMasks` is an object with information about all mask groups, each containing:
- `group` — group key
- `value` — accumulated group value
- `maxLength` — maximum fragment length
- `full` — fragment filled flag
- `end` — end of input flag
- `chars` — array of value characters

#### `view`

Character displayed as placeholder for unfilled group positions.

### Usage example

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

const phoneCode = ref('')
const productCode = ref('')
const dateValue = ref('')
</script>

<template>
  <!-- Phone code with variable length and auto-completion -->
  <Mask
    v-model="phoneCode"
    mask="+* (***) *** ** **"
    :special="{
      '*': {
        rubber: true,
        minLength: 1,
        maxLength: 3,
        pattern: '\\d',
        transitionChar: ' '
      }
    }"
  />

  <!-- Product code with variable length -->
  <Mask
    v-model="productCode"
    mask="PRD-***"
    :special="{
      '*': {
        rubber: true,
        minLength: 4,
        maxLength: 10,
        match: /[A-Z0-9]/,
        view: '_'
      }
    }"
  />

  <!-- Date with default values -->
  <Mask
    v-model="dateValue"
    mask="DD/MM/YYYY"
    :special="{
      'D': {
        defaultValue: '01',
        pattern: '\\d',
        view: '0'
      },
      'M': {
        defaultValue: '01',
        pattern: '\\d',
        view: '0'
      },
      'Y': {
        defaultValue: '2024',
        pattern: '\\d',
        view: '0'
      }
    }"
  />
</template>
```
