@dxtmisha/wiki 0.24.2 → 0.25.1

package/src/media/mdx/Mask/pattern.ru.mdx

@@ -1,78 +1,66 @@
 ## Валидация и паттерны
 
-Свойства `check` и `pattern` предназначены для управления валидацией ввода и определения допустимых символов в маске.
-
-### Свойства
-
-- **pattern** — Определяет паттерны валидации для отдельных групп маски, задавая допустимые символы и правила по группам
-- **check** — Глобальный паттерн валидации, применяемый после завершения маски для дополнительной проверки ввода
-
-### Тип FieldPatternItemOrFunction
-
-Оба параметра `pattern` и `check` имеют тип `FieldPatternItemOrFunction` и принимают следующие значения:
-
-```ts
-type FieldPatternItemOrFunction =
-  | string                                    // RegExp строка
-  | Partial<HTMLInputElement>                 // Объект с атрибутами input
-  | ((item: FieldMasks) => FieldPatternItem)  // Функция-генератор паттерна
-
-interface FieldMasks {
-  group: string      // Название группы маски
-  value: string      // Текущее значение группы
-  maxLength: number  // Максимальная длина группы
-  full: boolean      // Группа заполнена полностью
-  end: boolean       // Конец ввода
-  // ...другие свойства маски
-}
+Свойства `pattern` и `check` предназначены для управления валидацией ввода в маске.
+
+**Свойства:**
+
+- `pattern` — определяет паттерны валидации для отдельных групп маски, проверяя введённые значения
+- `check` — глобальный паттерн валидации, применяемый после полного заполнения маски
+
+Свойства работают последовательно: `pattern` проверяет введённые значения на уровне групп маски, подсвечивая ошибки валидации после ввода. Символы вводятся в поле, но при несоответствии паттерну отображается сообщение об ошибке. Каждая группа (определённая специальными символами) получает свой паттерн. После полного заполнения маски `check` выполняет финальную валидацию всего значения, обеспечивая дополнительный слой проверки для сложной бизнес-логики. Оба свойства опциональны и могут использоваться независимо или совместно для многоуровневой защиты от некорректных данных.
+
+```html
+<script setup>
+import { ref } from 'vue'
+
+const phone = ref('')
+const cardNumber = ref('')
+</script>
+
+<template>
+  <!-- Pattern для групп: только цифры -->
+  <Mask
+    v-model="phone"
+    mask="+7 (***) ***-**-**"
+    pattern="\\d"
+  />
+
+  <!-- Pattern с функцией для разных групп -->
+  <Mask
+    v-model="phone"
+    mask="DD/MM/YYYY"
+    :special="{
+      'D': {
+        pattern: (masks) => {
+          const value = masks['D']?.value || ''
+          if (value === '0') return '[1-9]'
+          if (value === '3') return '[0-1]'
+          return '\\d'
+        }
+      },
+      'M': {
+        pattern: (masks) => {
+          const value = masks['M']?.value || ''
+          if (value === '0') return '[1-9]'
+          if (value === '1') return '[0-2]'
+          return '\\d'
+        }
+      },
+      'Y': { pattern: '\\d' }
+    }"
+  />
+
+  <!-- Check для финальной валидации -->
+  <Mask
+    v-model="cardNumber"
+    mask="**** **** **** ****"
+    pattern="\\d"
+    :check="(maskData) => {
+      const number = maskData.value.replace(/\s/g, '')
+      return isValidLuhn(number) ? {} : {
+        validationMessage: 'Неверный номер карты'
+      }
+    }"
+  />
+</template>
 ```
-
-### Различия в применении
-
-**Pattern** работает на уровне групп маски:
-- Применяется в реальном времени при вводе символов
-- Каждая группа маски (определённая спецсимволами) получает свой паттерн
-- Недопустимые символы отклоняются до появления в поле
-- Разные группы могут иметь разные правила валидации
-
-**Check** работает с полным значением:
-- Запускается только после полного заполнения маски
-- Применяется ко всему введённому значению
-- Обеспечивает дополнительный слой валидации для сложной бизнес-логики
-- Используется для финальной проверки корректности данных
-
-### Примеры использования
-
-```javascript
-// Pattern для групп: только цифры в телефонном номере
-pattern: "\\d"
-
-// Pattern с функцией для разных групп
-pattern: (maskData) => {
-  if (maskData.group === 'month') return "[0-1]\\d"
-  if (maskData.group === 'day') return "[0-3]\\d"
-  return "\\d"
-}
-
-// Check для валидации номера карты алгоритмом Луна
-check: (maskData) => {
-  const cardNumber = maskData.value.replace(/\s/g, '')
-  return isValidLuhn(cardNumber)
-    ? { valid: true }
-    : { valid: false, message: "Неверный номер карты" }
-}
-
-// Check с RegExp для проверки формата
-check: "^\\+1\\d{10}$"
-```
-
-### Взаимосвязь свойств
-
-Свойства работают последовательно для обеспечения качественной валидации:
-
-- `pattern` фильтрует ввод на уровне символов и групп, предотвращая некорректный ввод
-- `check` выполняет финальную валидацию полного значения по завершении заполнения маски
-- Оба свойства опциональны и могут использоваться независимо или совместно
-- При совместном использовании обеспечивают многоуровневую защиту от некорректных данных
-
-Такой подход позволяет создавать гибкие и надёжные поля ввода с детальным контролем валидации на всех этапах взаимодействия с пользователем.

package/src/media/mdx/Mask/special.en.mdx

@@ -1,127 +1,204 @@
-## Special characters (special)
+## Special characters
 
-The `special` property defines special characters for mask groups and their advanced settings.
+The `special` property defines special characters to denote user input positions in the mask and configure their extended behavior.
 
-### Purpose
+**Possible values:**
 
-Special characters in a mask denote places where users can input data. The `special` property allows configuring the behavior of these input groups with additional capabilities.
+- `string` — single special character (default `'*'`)
+- `string[]` — array of special characters for different group types
+- `MaskSpecialList` — object with extended configuration for each character
 
-### Value types
+Special characters in the mask template denote positions where users can enter data, unlike literal characters that are inserted automatically.
 
-```ts
-type MaskSpecialProp = string | string[] | MaskSpecialList
+When using a simple string (e.g., `special="*"`), all input positions in the mask are restricted by the same validation rules.
 
-// Extended group configuration
-interface MaskSpecialItem {
-  defaultValue?: string           // Default value
-  rubber?: boolean               // Rubber group (variable length)
-  transitionChar?: string | string[]  // Transition characters
-  minLength?: number             // Minimum length
-  maxLength?: number             // Maximum length
-  match?: RegExp | string        // Validation pattern
-  pattern?: FieldPatternItemOrFunction  // Validation pattern
-  view?: string                  // Display character
-}
-```
+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.
 
-### Usage methods
+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.
 
-**1. Simple string (single special character)**
-```javascript
-special: '*'           // Symbol * denotes input places
-// Mask: "***-***" → groups: *, *, *, *, *, *
-```
+For built-in types (`currency`, `number`, `date`, `time`), the system automatically generates special characters considering regional settings, ignoring the user-defined `special` value.
 
-**2. Character array (multiple group types)**
-```javascript
-special: ['*', '#', 'A']
-// * - any characters, # - digits, A - letters
-// Mask: "A**-###" → different group types
-```
+```html
+<!-- Simple special character -->
+<Mask mask="***-***" special="*" />
 
-**3. Object with extended settings**
-```javascript
-special: {
-  '*': {
-    pattern: '\\d',        // Digits only
-    view: '_',             // Show _ as placeholder
-    rubber: false          // Fixed length
-  },
-  '#': {
-    pattern: '[A-Z]',      // Uppercase letters only
-    defaultValue: 'X',     // Default value
-    rubber: true,          // Variable length
-    minLength: 1,
-    maxLength: 5
-  }
-}
+<!-- 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' }
+  }"
+/>
 ```
 
-### Rubber groups
+## MaskSpecialList
 
-Rubber groups allow entering a variable number of characters:
+`MaskSpecialList` — object with extended configuration for mask special characters, where each key corresponds to a special character in the template.
 
-```javascript
-special: {
-  '*': {
-    rubber: true,
-    minLength: 2,
-    maxLength: 8,
-    pattern: '\\d'
-  }
-}
-// Mask: "***-***" can accept 2 to 8 digits in each group
-```
+### Type structure
 
-### Default values
+```typescript
+type MaskSpecialList = Record<string, MaskSpecialItem>
 
-```javascript
-special: {
-  'Y': { defaultValue: '2024' },    // Default year
-  'M': { defaultValue: '01' },      // Default month
-  'D': { defaultValue: '01' }       // Default day
-}
-// Mask: "DD/MM/YYYY" → autofill: "01/01/2024"
-```
+interface MaskSpecialItem {
+  /** Default value for the group */
+  defaultValue?: string
 
-### Transition characters
+  /** Enables variable-length mode (rubber group) */
+  rubber?: boolean
 
-Define characters that automatically move the cursor to the next group:
+  /** Characters for automatic transition to the next group */
+  transitionChar?: string | string[]
 
-```javascript
-special: {
-  '*': {
-    transitionChar: [' ', '-'],     // Space or dash moves forward
-    pattern: '\\d'
-  }
-}
-// When typing "123 " cursor automatically moves to next group
-```
+  /** Minimum length for rubber group */
+  minLength?: number
 
-### Display (view)
+  /** Maximum length for rubber group */
+  maxLength?: number
 
-Configure placeholder characters for unfilled positions:
+  /** Regular expression for character validation */
+  match?: RegExp | string
 
-```javascript
-special: {
-  '*': { view: '_' },       // Show underscores
-  '#': { view: '0' }        // Show zeros
+  /** Pattern for group validation */
+  pattern?: FieldPatternItemOrFunction
+
+  /** Displayed placeholder character */
+  view?: string
 }
-// Mask: "***-###" displays as "___-000"
 ```
 
-### Integration with mask types
+### 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`
 
-For built-in types (`currency`, `number`, date/time) the system automatically generates corresponding special characters:
+Minimum number of characters for rubber group. Only works with `rubber: true`.
 
-- **currency/number**: special characters for digits and decimal parts
-- **date/time**: characters for day, month, year, hours, minutes, seconds
-- **text**: uses settings from the `special` property
+#### `maxLength`
 
-### Interaction with other properties
+Maximum number of characters for rubber group. Only works with `rubber: true`.
 
-- `pattern` — complements special characters with group patterns
-- `check` — applied after filling all special groups
-- `mask` — uses special characters to define input places
+#### `match`
 
-Special characters are the foundation of the mask system, providing flexible definition of input groups with individual validation rules and behavior.
+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>
+```