@cat-of-summer/st-script 1.4.2 → 1.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (127) hide show
  1. package/README.md +1 -1
  2. package/dist/app/datepicker.min.js +3 -3
  3. package/dist/app/datepicker.min.js.map +3 -3
  4. package/dist/app/form.min.js +1 -1
  5. package/dist/app/form.min.js.map +3 -3
  6. package/dist/app.esm.min.js +1 -1
  7. package/dist/app.esm.min.js.map +3 -3
  8. package/dist/app.min.js +1 -1
  9. package/dist/app.min.js.map +3 -3
  10. package/dist/core.esm.min.js +1 -1
  11. package/dist/core.esm.min.js.map +3 -3
  12. package/dist/core.min.js +1 -1
  13. package/dist/core.min.js.map +3 -3
  14. package/dist/loader.esm.min.js +1 -1
  15. package/dist/loader.esm.min.js.map +3 -3
  16. package/dist/loader.min.js +1 -1
  17. package/dist/loader.min.js.map +3 -3
  18. package/dist/mask.esm.min.js +1 -1
  19. package/dist/mask.esm.min.js.map +3 -3
  20. package/dist/mask.min.js +1 -1
  21. package/dist/mask.min.js.map +3 -3
  22. package/dist/modal.esm.min.js +1 -1
  23. package/dist/modal.esm.min.js.map +3 -3
  24. package/dist/modal.min.js +1 -1
  25. package/dist/modal.min.js.map +3 -3
  26. package/dist/observer.esm.min.js +1 -1
  27. package/dist/observer.esm.min.js.map +3 -3
  28. package/dist/observer.min.js +1 -1
  29. package/dist/observer.min.js.map +3 -3
  30. package/dist/route.esm.min.js.map +2 -2
  31. package/dist/route.min.js +1 -1
  32. package/dist/route.min.js.map +2 -2
  33. package/dist/select.esm.min.js +1 -1
  34. package/dist/select.esm.min.js.map +3 -3
  35. package/dist/select.min.js +1 -1
  36. package/dist/select.min.js.map +3 -3
  37. package/dist/shape.esm.min.js +2 -0
  38. package/dist/shape.esm.min.js.map +7 -0
  39. package/dist/shape.min.js +2 -0
  40. package/dist/shape.min.js.map +7 -0
  41. package/dist/toggle.esm.min.js +1 -1
  42. package/dist/toggle.esm.min.js.map +3 -3
  43. package/dist/toggle.min.js +1 -1
  44. package/dist/toggle.min.js.map +3 -3
  45. package/dist/typograf.esm.min.js +1 -1
  46. package/dist/typograf.esm.min.js.map +3 -3
  47. package/dist/typograf.min.js +1 -1
  48. package/dist/typograf.min.js.map +3 -3
  49. package/dist/uploader.esm.min.js +1 -1
  50. package/dist/uploader.esm.min.js.map +3 -3
  51. package/dist/uploader.min.js +1 -1
  52. package/dist/uploader.min.js.map +3 -3
  53. package/dist/validator.esm.min.js +1 -1
  54. package/dist/validator.esm.min.js.map +3 -3
  55. package/dist/validator.min.js +1 -1
  56. package/dist/validator.min.js.map +3 -3
  57. package/docs/README.md +90 -0
  58. package/docs/src/README.md +29 -0
  59. package/docs/src/_traits/README.md +8 -0
  60. package/docs/src/_traits/hasInstanceSymbol.js.md +57 -0
  61. package/docs/src/app/README.md +13 -0
  62. package/docs/src/app/datepicker/README.md +9 -0
  63. package/docs/src/app/datepicker/_calendar.js.md +1 -0
  64. package/docs/src/app/datepicker/index.js.md +153 -0
  65. package/docs/src/app/form/README.md +8 -0
  66. package/docs/src/app/form/index.js.md +560 -0
  67. package/docs/src/app/index.js.md +1386 -0
  68. package/docs/src/cookie/README.md +8 -0
  69. package/docs/src/cookie/index.js.md +80 -0
  70. package/docs/src/core/README.md +8 -0
  71. package/docs/src/core/index.js.md +224 -0
  72. package/docs/src/index.js.md +1 -0
  73. package/docs/src/loader/README.md +8 -0
  74. package/docs/src/loader/index.js.md +126 -0
  75. package/docs/src/mask/README.md +10 -0
  76. package/docs/src/mask/_engine.js.md +1 -0
  77. package/docs/src/mask/_groups.js.md +1 -0
  78. package/docs/src/mask/index.js.md +412 -0
  79. package/docs/src/modal/README.md +8 -0
  80. package/docs/src/modal/index.js.md +821 -0
  81. package/docs/src/observer/README.md +9 -0
  82. package/docs/src/observer/_engine.js.md +28 -0
  83. package/docs/src/observer/index.js.md +259 -0
  84. package/docs/src/route/README.md +8 -0
  85. package/docs/src/route/index.js.md +385 -0
  86. package/docs/src/select/README.md +8 -0
  87. package/docs/src/select/index.js.md +115 -0
  88. package/docs/src/shape/README.md +9 -0
  89. package/docs/src/shape/_engine.js.md +1 -0
  90. package/docs/src/shape/index.js.md +99 -0
  91. package/docs/src/st_button_widget/README.md +9 -0
  92. package/docs/src/st_button_widget/README.txt.md +4 -0
  93. package/docs/src/st_button_widget/index.js.md +68 -0
  94. package/docs/src/st_links_widget/README.md +9 -0
  95. package/docs/src/st_links_widget/README.txt.md +4 -0
  96. package/docs/src/st_links_widget/index.js.md +46 -0
  97. package/docs/src/st_widget/README.md +8 -0
  98. package/docs/src/st_widget/button/README.md +4 -0
  99. package/docs/src/toggle/README.md +8 -0
  100. package/docs/src/toggle/index.js.md +604 -0
  101. package/docs/src/typograf/README.md +9 -0
  102. package/docs/src/typograf/_engine.js.md +75 -0
  103. package/docs/src/typograf/index.js.md +165 -0
  104. package/docs/src/uploader/README.md +8 -0
  105. package/docs/src/uploader/index.js.md +113 -0
  106. package/docs/src/validator/README.md +8 -0
  107. package/docs/src/validator/index.js.md +114 -0
  108. package/package.json +3 -2
  109. package/src/_traits/hasInstanceSymbol.js +14 -1
  110. package/src/app/index.js +102 -15
  111. package/src/core/index.js +83 -13
  112. package/src/index.js +1 -1
  113. package/src/loader/index.js +13 -3
  114. package/src/mask/index.js +21 -2
  115. package/src/modal/index.js +16 -6
  116. package/src/observer/index.js +3 -3
  117. package/src/select/index.js +24 -4
  118. package/src/{cut → shape}/_engine.js +1 -1
  119. package/src/{cut → shape}/index.js +19 -10
  120. package/src/toggle/index.js +85 -28
  121. package/src/typograf/index.js +3 -3
  122. package/src/uploader/index.js +32 -9
  123. package/src/validator/index.js +20 -2
  124. package/dist/cut.esm.min.js +0 -2
  125. package/dist/cut.esm.min.js.map +0 -7
  126. package/dist/cut.min.js +0 -2
  127. package/dist/cut.min.js.map +0 -7
@@ -0,0 +1,412 @@
1
+ # index.js
2
+
3
+ ## Описание
4
+
5
+ Маски ввода для `<input>`. Заменяет устаревший `st_mask`.
6
+
7
+ Движок и адаптер разделены: чистый движок без DOM живёт в модуле `_engine.js` (плоские экспорты `compile`, `build`, `run`, `run_all`, `render`, `caret_for`, `cap`), группы поверх раскладки — в `_groups.js` (`spans`, `fit`, `type_ahead`, `settle`, `step`, `in_range`); оба тестируются в голом Node (`node tests/mask.test.mjs`); класс `Mask` — DOM-адаптер поверх них, наружу отдаёт только конструктор и инстанс-методы.
8
+
9
+ Все виды правок — набор, вставка (Ctrl+V), удаление, drag-and-drop, автозаполнение браузера, программный `set()` — проходят через один общий путь: правка применяется к каноническому «сырому потоку», поток прогоняется через движок, поле получает новый текст и корректную позицию каретки.
10
+
11
+ При `placeholder: 'always'` и одной фиксированной маске (без вариативной длины) включается **режим обособленных частей**: каждый слот - самостоятельная ячейка. Клик в ММ печатает в ММ, не сдвигая ГГГГ; Backspace/Delete очищают только свою ячейку. Пропущенные позиции живут в потоке "дырками" - символами-заполнителями (поэтому заполнитель не должен быть валидным символом слота). Дырки бывают только в этом режиме: в остальных набранный символ-заполнитель, не подошедший слоту, отбрасывается. При нескольких шаблонах режим не включается - ячейки одного шаблона не дали бы набору перейти в другой; поле правится как обычно и показывает полный скелет выбранного шаблона.
12
+
13
+ Поле делится на **группы**. Без разметки всё поле - одна группа; именованные группы задаются в шаблоне (`{dd:00}.{mm:00}.{yyyy:0000}`). У каждой группы свой режим правки `edit` и свои настройки (см. "Группы и режим правки"): так собирается поле, которое ведёт себя как нативный `<input type=date>`, - группа выделяется целиком, набор в ней идёт с чистого листа, ←/→/Tab ходят по группам, ↑/↓ меняют значение.
14
+
15
+ ## Конструктор
16
+
17
+ ```js
18
+ new Mask(params)
19
+ ```
20
+
21
+ | Параметр | По умолчанию | Описание |
22
+ |---|---|---|
23
+ | `target` | `'input[mask]'` | Селектор \| функция, возвращающая поля \| `Element` \| `NodeList` \| массив. Селектор и функцию пересчитывает `refresh()` |
24
+ | `mask` | `null` | Маска (формы — ниже); `null` → берётся из атрибута `mask=""` самого поля (см. «Маска в атрибуте») |
25
+ | `filler` | `'_'` | Заполнитель; строка длиной с маску — позаполнительно (`'ДДММГГГГ'`) |
26
+ | `placeholder` | `true` | `true` — только введённое + авто-разделители (ведущие литералы вроде `'+7 ('` появляются при фокусе); `'typed'` — то же, но пустое поле остаётся пустым и в фокусе: виден родной атрибут `placeholder`, а не начало первого шаблона (несколько шаблонов с разными префиксами: `RAL`/`NCS`); `'always'` — полный скелет с заполнителями; `false` — без плейсхолдера, разделитель появляется, когда за ним введён следующий символ |
27
+ | `edit` | `'free'` | Режим правки групп: `'free'` - обычная каретка; `'end'` - каретка прижата к концу набранного; `'whole'` - группа выделяется и правится целиком, как в `<input type=date>` (см. "Группы и режим правки") |
28
+ | `groups` | `{}` | Настройки именованных групп: `{ имя: { edit, filler, pad, align, min, max } }` - переопределяют параметры верхнего уровня |
29
+ | `pad`, `align`, `min`, `max` | `null`, `'left'`, `null`, `null` | Настройки групп по умолчанию (см. "Группы и режим правки"); для поля без групп - настройки самого поля |
30
+ | `caret` | `true` | `'hide'` - каретка скрыта через `caret-color: transparent !important` (инлайн с `!important` - самый высокий приоритет в каскаде, обычным CSS не вернуть). Где стоит каретка, решает `edit` |
31
+ | `coerce_type` | `true` | Приводить `type="number"`/`"email"` к `type="text"` + `inputmode` (эти типы не отдают selection API). `false` — не трогать тип (будет `console.warn`) |
32
+ | `max_raw` | `null` | Лимит длины `raw` (пользовательских символов). Оверрайдит атрибут `maxlength` поля |
33
+ | `validate` | `null` | `true` — прокидывать `complete` в нативный `setCustomValidity` для всех полей; `null` — только для приведённых `number`/`email`; `false` — не трогать нативную валидность |
34
+ | `validation_message` | `null` | Сообщение для `setCustomValidity` при неполном значении: строка или `(input, state) => string`. По умолчанию — RU-текст по типу поля |
35
+
36
+ ### Коллбэки
37
+
38
+ Все коллбэки одинаковы по форме: `input` первым аргументом, полезная нагрузка объектом; `false` отменяет, возвращённая строка заменяет. Все привязаны к экземпляру: `this` внутри обычной функции — маска (`this.params`, `this.set(…)`).
39
+
40
+ | Коллбэк | Когда | Особенности |
41
+ |---|---|---|
42
+ | `before_init(params)` / `on_init(params)` | Инициализация | |
43
+ | `before_char(input, { char })` | На каждый входной символ до разбора | Нормализация: регистр, транслитерация. Вернуть строку — заменить, `false` или `''` — выбросить символ. Должен быть идемпотентным (поток прогоняется заново на каждой правке) |
44
+ | `before_slot(input, { char, slot, cells, raw, node })` | Символ подошёл слоту и вот-вот в него встанет | Автодополнение (вернуть строку: `'3'` → `'03'`), автоисправление (`false` — отклонить). `cells` — уже заполненные ячейки по номерам слотов; в отличие от `raw`, индексы не сбиваются пропущенными позициями |
45
+ | `before_input(input, { type, insert, start, end })` | Перед каждой правкой | `return false` отменяет |
46
+ | `on_input(input, state)` | После каждой правки | Если правил пользователь, следом поле шлёт всплывающий `input` (см. «Событие `input`») |
47
+ | `before_paste(input, text)` | Перед вставкой | `false` — отменить, строка — заменить вставляемый текст |
48
+ | `on_paste(input, state)` | После вставки | |
49
+ | `on_accept(input, state)` | `raw` реально изменился | |
50
+ | `on_complete(input, state)` | Маска стала заполненной | |
51
+ | `on_incomplete(input, state)` | Перестала быть заполненной | |
52
+ | `on_mask_change(input, state)` | Переключилась активная маска | `state.mask_id` — ключ словаря или индекс массива |
53
+ | `on_reject(input, { char, reason, slot, type })` | Набранный или вставленный символ не принят | По вызову на символ, после `on_input`. `reason`: `'slot'` — не подошёл позиции (в том числе `before_slot` вернул `false`), `slot` — номер слота; `'literal'` — разделитель шаблона не на своём месте (пробел, дефис); `'full'` — шаблон уже заполнен или упёрся в `max_raw`. `type` — `inputType` правки. Символы, выброшенные `before_char`, и отмена через `before_input` отказом не считаются |
54
+
55
+ `state` = `{ raw, formatted, complete, mask_id, progress, groups, empty, skeleton }`, где `groups` - набранное в именованных группах: `{ dd: '12', mm: '03', yyyy: '2026' }` (без групп - `{}`); `empty` - ничего не набрано (`raw` пуст и тогда, когда набраны только литералы: `N` в `NCS S …`); `skeleton` - введённое и остаток текущего шаблона с заполнителями (`'NCS S 1050-_'`), независимо от `placeholder`.
56
+
57
+ `before_char` и `before_slot` — обычные коллбэки: привязаны к `this`, переносятся в `clone()` и переопределяются на уровне отдельной маски (`{ pattern, before_slot }`). Разделены они не по прихоти, а потому что срабатывают в разные моменты: `before_char` видит любой символ, включая мусор при вставке, и не знает позиции; `before_slot` вызывается только когда символ уже подошёл слоту, и знает его номер и соседние ячейки. Объединять их в один хук нельзя — тогда правило вида «цифра больше 3 → дописать 0» применялось бы и к мусору при вставке (`'т' > '3'` истинно для строк) и портило бы значение.
58
+
59
+ ## Формы параметра `mask`
60
+
61
+ | Форма | Смысл |
62
+ |---|---|
63
+ | `'строка'` | Позиционный шаблон (синтаксис ниже) |
64
+ | `RegExp` | Фильтр-режим: посимвольный allowlist — для email/URL, где позиции не фиксированы. Внутри это обычный повторитель `{слот;0-}` |
65
+ | `{ pattern, filler?, before_char?, before_slot?, valid? }` | Шаблон с пер-масочными настройками; `valid` — RegExp по всему значению, дополняет `complete` (например, диапазон октета IP) |
66
+ | `{ filter, valid?, max_length?, before_char? }` | Фильтр-режим |
67
+ | `функция(ctx)` | Возвращает любую из форм; вызывается на каждой правке. `ctx = { stream, raw, value, input }`, где `stream` — набираемое значение (по нему собирают шаблон, зависящий от длины: разряды по три) |
68
+ | `[…]` | Массив любых форм — динамический выбор: выигрывает маска, принявшая больше символов; при равенстве — узнавшая более длинный код (см. ниже); затем первая (ИНН 10/12, телефон 8/+7). Заполненность на выбор не влияет, поэтому шаблоны с общим началом ставятся от короткого к длинному: `['NCS S 0000-{{[YRGBN]}}', 'NCS S 0000-{{[YRGB]}}00{{[YRGB]}}']` — `1080-Y` полон по первому, а следующая цифра переводит во второй. В обратном порядке `1080-Y` так и ждёт ещё три символа |
69
+ | `{ ru: '…', by: '…' }` | Словарь именованных масок: по первым символам подтягивается самая подходящая (правило то же, что у массива), ключ приходит в `state.mask_id`, атрибут `mask_id` и событие `on_mask_change` |
70
+
71
+ **Код маски.** Буквы и цифры среди литералов шаблона (`7` в `'+7 (000)…'`, `375` в `'+375 (00)…'`) считаются кодом маски. Когда кандидаты приняли поровну символов, выбор решает длина кода, совпавшего с началом ввода. Поэтому телефон можно набирать без `+`: `3…` и `37…` → `+375`, `7913…` → `+7`, `77…` → `+7 (7…)` (Казахстан точнее России), `49…` → `+49`. Если ввод начал совпадать с кодом, но разошёлся с ним раньше номера, код не засчитывается: `343…` → `+7 (343)`, а не `+375 (43)`. Ввод, оборвавшийся внутри кода (`37`), — совпадение. Заполненность маски на выбор не влияет: номер без кода (`916…`, `641…`) остаётся у первой маски словаря и не перескакивает на более короткую, заполнившуюся раньше. Первая маска словаря — маска по умолчанию. Трансформация `{8=>+7}` тоже засчитывается как код. Разделители `(`, ` `, `-`, `+` на выбор не влияют, так что маски дат, карт и документов ведут себя как прежде.
72
+
73
+ ### Маска в атрибуте
74
+
75
+ Атрибут `mask=""` принимает строку-шаблон либо JSON: массив строк или словарь `{ ключ: строка | [строки] }`. Это даёт мульти-маски и автоподбор страны прямо в разметке, а в JS достаточно `new Mask()` (или `new Mask({ target })` без `mask`):
76
+
77
+ ```html
78
+ <input type="tel" mask='{"ru":["{8=>+7} (000) 000-00-00","+7 (000) 000-00-00"],"by":"+375 (00) 000-00-00","kz":"+7 (700) 000-00-00"}'>
79
+ <input mask='["0000000000","000000000000"]'>
80
+ ```
81
+
82
+ Шаблоны тоже начинаются с `[` и `{` (`{*;0-}`, `[0]`), поэтому JSON берётся, только если он разобрался и имеет одну из этих двух форм. Всё остальное остаётся строкой-шаблоном.
83
+
84
+ Числовой режим (деньги/суммы) — это **отдельный параметр `numeral`**, а не форма `mask` (см. ниже). Объектная форма `mask` — всегда словарь именованных масок.
85
+
86
+ ## Синтаксис шаблона
87
+
88
+ | Синтаксис | Значение |
89
+ |---|---|
90
+ | `0` | Обязательная цифра |
91
+ | `a` | Обязательная буква (юникод, кириллица включена) |
92
+ | `*` | Любой печатный символ |
93
+ | `\x` | Экранированный литерал: `\0`, `\a`, `\*`, `\[`, `\{`, `\\` |
94
+ | прочие символы | Статические литералы. Вводить их не нужно: маска подставляет их сама, в том числе в конце шаблона — `'NCS S 0000-N'` полон после четырёх цифр. Если на месте литерала у пользователя выбор (`N` или тон), это слот: `{{[YRGBN]}}` |
95
+ | `{{re}}` | Один символ по регулярному выражению: `{{[0-9a-f]}}` |
96
+ | `[ … ]` | Необязательный блок — появляется, когда пользователь начал его вводить: `00.00.0000[ 00:00]` |
97
+ | `{unit;N}` `{unit;min-max}` `{min-}` `{-max}` | Повторитель; `unit` — под-шаблон: `{0;1-3}` — 1–3 цифры, `{0;1-}` — до бесконечности, `{{{[0-9a-f]}};4}` — 4 hex-символа |
98
+ | `{c=>s}` | Трансформация: ввод `c` даёт `s`; вставка текста, начинающегося с `s`, тоже матчится: `{8=>+7}` |
99
+ | `{имя:подшаблон}` | Именованная группа: `{dd:00}`, `{ip:{0;1-3}}`. Имя - идентификатор (`[A-Za-z_]\w*`); группы не вкладываются (вложенная - литералы с `console.warn`). На разбор не влияет: `{dd:00}.{mm:00}` матчит то же, что `00.00` |
100
+
101
+ Ограничение: несбалансированные `{` `}` внутри `{{re}}` нужно экранировать (`\{`). Некорректный блок не роняет компиляцию — превращается в литералы с `console.warn`.
102
+
103
+ ## Группы и режим правки
104
+
105
+ Группа — часть поля, которая правится как единое целое. Без разметки всё поле — одна неявная группа, её настройки — параметры верхнего уровня. Именованные группы размечаются в шаблоне (`{dd:00}`), их настройки — в `groups` по имени, а параметры верхнего уровня служат для них значениями по умолчанию. Слоты вне именованных групп образуют неявные группы.
106
+
107
+ | Настройка | По умолчанию | Смысл |
108
+ |---|---|---|
109
+ | `edit` | `'free'` | `'free'` — обычная каретка; `'end'` — каретка прижата к концу набранного; `'whole'` — группа выделяется и правится целиком |
110
+ | `filler` | `filler` поля | Заполнитель пустой группы, по слоту внутри группы (`'ДД'`, `'ГГГГ'`) |
111
+ | `pad` | `null` | Чем добивать группу, в которой начат набор: `'0'` — `1` даёт `01`. Символы `pad` становятся настоящими (`raw` = `'01'`), поэтому `pad` должен подходить слоту |
112
+ | `align` | `'left'` | `'right'` — набор въезжает справа: `1` → `01` → `12`, год `2` → `0002` (режим `'whole'`) |
113
+ | `min` / `max` | `null` | Числовой диапазон цифровой группы: автопереход, зажим, шаг ↑/↓; значение вне диапазона делает `complete` ложным |
114
+
115
+ **`edit: 'end'`** — каретка прижата к первой пустой ячейке начиная с группы под курсором (у заполненной группы — дальше по полю, без раскладки — к концу набранного). Раз в середину нельзя писать, из неё нельзя и удалять: частичное выделение (двойной клик, протяжка) расширяется до группы под курсором (без раскладки — до всего значения), а сама правка принудительно приводится к прижатой позиции — это закрывает и обходные пути вроде перетаскивания текста мышью. Остаются дописывать/стирать с конца или заменить группу (значение) целиком. Подходит для сумм: `edit: 'end', caret: 'hide'`.
116
+
117
+ **`edit: 'whole'`** — поведение `<input type=date>`. Нужны фиксированная маска и `placeholder: 'always'`; без них режим работает как `'end'` (с `console.warn` при привязке).
118
+
119
+ - Фокус с Tab выделяет первую группу, с Shift+Tab — последнюю; клик — группу под курсором (по разделителю — группу слева от него, если курсор у её конца). Выделить часть группы нельзя.
120
+ - Вход в группу (клик, стрелка, Tab, автопереход) начинает набор с пустого буфера: набор перезаписывает группу, а не дописывает к ней.
121
+ - Набор: символ ложится в буфер группы, группа показывает буфер с выравниванием `align` и добивкой `pad`. Переход к следующей группе — когда буфер полон или следующая цифра гарантированно вывела бы за `max` (`4` в дне: 40 > 31 → `04`). Число выше `max` зажимается (`35` → `31`). На последней группе буфер сбрасывается: следующий символ начинает её заново.
122
+ - Разделитель после группы (`.`) закрывает её досрочно: `1.3.2026` → `01.03.2026`. Разделитель по пустому буферу ничего не делает.
123
+ - Уход из группы, в которой набирали: заполненное значение ниже `min` поднимается до `min` (`00` в дне → `01`).
124
+ - ←/→ — соседняя группа, Home/End — первая/последняя, Tab/Shift+Tab — по группам, а с крайней — штатный уход из поля.
125
+ - ↑/↓ — шаг по кругу в пределах `min…max` (без них — `0…99…9`): `31` ↑ → `01`; пустая группа: ↑ → `min`, ↓ → `max`. У нецифровой группы шага нет.
126
+ - Backspace/Delete очищают группу целиком; Backspace по пустой группе переходит на предыдущую.
127
+ - Вставка идёт тем же путём, что набор, начиная с выделенной группы: `12.03.2026` раскладывается по группам сам.
128
+ - `before_char` и `before_slot` работают как обычно, но диапазоны дат проще задать через `min`/`max`, чем правилами `before_slot`.
129
+
130
+ ```js
131
+ new Mask({
132
+ target: 'input[name=date]',
133
+ mask: '{dd:00}.{mm:00}.{yyyy:0000}',
134
+ placeholder: 'always',
135
+ edit: 'whole', align: 'right', pad: '0',
136
+ groups: {
137
+ dd: { filler: 'ДД', min: 1, max: 31 },
138
+ mm: { filler: 'ММ', min: 1, max: 12 },
139
+ yyyy: { filler: 'ГГГГ', min: 1 }
140
+ }
141
+ });
142
+
143
+ input.state().groups; // { dd: '12', mm: '03', yyyy: '2026' }
144
+ ```
145
+
146
+ Набор группы — пара `filler` + `pad`: пустая группа показывает `ДД`, а начатая добивается нулями (`01`), как у нативного поля.
147
+
148
+ ## Числовой режим (параметр `numeral`)
149
+
150
+ Деньги/суммы — **отдельный параметр `numeral`**, а не форма `mask`. Он приоритетнее `mask`
151
+ (вместе не сочетаются — при заданном `numeral` поле числовое, `mask` игнорируется), а поле
152
+ принимает только цифры (независимо от `type` и токенов). Позиционный шаблон тут не подходит:
153
+ заполнение идёт **справа** — набранные цифры это счётчик младших разрядов (при `fraction: 2`
154
+ первый `1` даёт `0,01`, следующая цифра сдвигает разряды влево), целая часть группируется.
155
+
156
+ | Опция | По умолчанию | Смысл |
157
+ |---|---|---|
158
+ | `fraction` | `0` | Знаков дробной части (заполняется справа) |
159
+ | `group` | `' '` | Разделитель тысяч (`''` — выключить) |
160
+ | `decimal` | `','` | Десятичный разделитель |
161
+ | `prefix` / `suffix` | `''` | Литералы до/после числа (`suffix: ' ₽'`) |
162
+ | `sign` | `false` | Разрешить ведущий `-` |
163
+ | `min` / `max` | — | Диапазон значения (входит в `complete`) |
164
+ | `message` | — | Сообщение нативной валидации при значении вне диапазона |
165
+
166
+ ```js
167
+ new Mask({ target: 'input[name=sum]', edit: 'end', caret: 'hide', placeholder: 'always', filler: '000',
168
+ numeral: { fraction: 2, group: ' ', decimal: ',', suffix: ' ₽', min: 0 } });
169
+ ```
170
+
171
+ `raw` содержит только значащие цифры (и знак): `12 345,67 ₽` → `raw` = `'1234567'`. Ноль — это
172
+ число (`0` → `0,00`), а не пустота. Ввод — end-append, поэтому естественно сочетается с
173
+ `edit: 'end', caret: 'hide'`. При `placeholder: 'always'` пустое поле показывает нулевой скелет из `filler`
174
+ (`filler: '000'` → `0,00 ₽`, по умолчанию → `_,__ ₽`). **`set()`**: голый ряд цифр трактуется
175
+ как заполнение справа (`set('1')` → `0,01`), а строка с десятичным разделителем — как реальное
176
+ число с округлением до `fraction` (`set('1234.5')` → `1 234,50`).
177
+
178
+ Пустой `type="number"` без явной маски получает numeral по умолчанию (`fraction: 0` —
179
+ сгруппированное целое) и ввод только цифр (см. `coerce_type`).
180
+
181
+ ## Публичные методы
182
+
183
+ | Метод | Описание |
184
+ |---|---|
185
+ | `raw(target?)` | Чистое значение поля (только пользовательские символы) |
186
+ | `state(target?)` | `{ raw, formatted, complete, mask_id, progress, groups, empty, skeleton }` |
187
+ | `set(target?, value)` | Программная установка (raw или отформатированное — мусор отфильтруется); шлёт `input`, если значение изменилось |
188
+ | `clear(target?)` | Очистить поле (по умолчанию — все) |
189
+ | `set_mask(mask, target?)` | Заменить маску на лету (по умолчанию — всем полям) |
190
+ | `clone(params)` | Копия экземпляра с переопределёнными параметрами |
191
+ | `refresh()` | Пересканировать `target` (селектор или функцию): поля, ушедшие из DOM, отпустить, новые привязать. Нужен, когда поля перерисовывает App, Vue и т. п. Возвращает `this` |
192
+ | `destroy()` | Разобрать: снять обработчики (в том числе `reset` на форме) и API с полей, вернуть `type` (`number`/`email`), `maxlength` и `caret-color`. Значение поля остаётся |
193
+ | `get value` | Массив отформатированных значений всех привязанных полей |
194
+ | `Mask.find(el)` | Экземпляр, владеющий элементом (`hasInstanceSymbol`) |
195
+ | `import { run, build, … } from '…/_engine.js'` | Чистый движок без DOM (модуль `_engine.js`): `compile`, `build`, `run`, `run_all`, `render`, `caret_for`, `cap` — форматирование строк вне полей |
196
+
197
+ `target` необязателен, когда маска привязана ровно к одному полю; при нескольких — понятная ошибка вместо угадывания. `set` при единственном поле принимает одно значение: `mask.set('12.03.2026')`.
198
+
199
+ ### API на самом элементе
200
+
201
+ Каждое привязанное поле получает методы владельца — можно работать с полем, не доставая экземпляр:
202
+
203
+ ```js
204
+ input.raw(); // '9123456789'
205
+ input.state(); // { raw, formatted, complete, mask_id, progress, groups, empty, skeleton }
206
+ input.set('89123456789'); // → +7 (912) 345-67-89
207
+ input.clear();
208
+ input.set_mask('0000 0000 0000 0000');
209
+ ```
210
+
211
+ Свойства неперечислимые (не попадают в `Object.keys` и `JSON.stringify`); занятое имя — нативное или чужое — не затирается, вместо этого пишется предупреждение. То же самое умеют `Select` (`select.open()`, `close()`, `toggle()`) и `Toggle` (`trigger.toggle()`, `activate()`, `deactivate()`) — общий механизм `expose` из `_traits/hasInstanceSymbol.js`.
212
+
213
+ ## Поведение каретки и правок
214
+
215
+ - Разделители проставляются сами; каретка перескакивает их при наборе.
216
+ - Backspace удаляет предыдущий пользовательский символ, перескакивая разделители; трансформация (`+7`) удаляется атомарно.
217
+ - Delete удаляет только следующий пользовательский символ.
218
+ - `placeholder: 'always'` + фиксированная маска: печать поверх ячеек, части независимы (см. Описание); каретка за последней ячейкой печатает в первую пустую; Delete/Backspace пропускают пустые ячейки и очищают ближайшую занятую.
219
+ - Режимы `edit: 'end'` и `edit: 'whole'` меняют, где стоит каретка и что можно выделить, — см. «Группы и режим правки».
220
+ - Набор разделителя переводит каретку в следующий блок из любой позиции, в том числе из наполовину заполненного (`1.3.2026` → `1Д.3М.2026`).
221
+ - Правка в середине строки переформатирует хвост, каретка остаётся на месте.
222
+ - Вставка любого текста: мусор отфильтровывается («тел: 8 (912) 345-67-89» → телефон), работает в середину и поверх выделения.
223
+ - Автозаполнение браузера и undo/redo сверяются страховочным путём по событию `input`.
224
+
225
+ ## Атрибуты поля после каждой правки
226
+
227
+ | Поле | Описание |
228
+ |---|---|
229
+ | `mask_id` | Индекс активной маски (для массивов) или ключ (для словаря) |
230
+ | `progress` | Число принятых пользовательских символов |
231
+ | `is_complete` | `"true"` если маска заполнена |
232
+
233
+ Атрибуты обычные, не `data-*` — селекторы вида `input[is_complete="true"]` работают напрямую.
234
+
235
+ ## Событие `input`
236
+
237
+ Маска перехватывает `beforeinput` и отменяет его (`preventDefault`), поэтому нативного `input` у
238
+ поля нет. Чтобы внешний код видел правку, маска после каждой своей правки сама шлёт всплывающий
239
+ `InputEvent('input', { bubbles: true, inputType, data })` — и после набора, и после `set()`,
240
+ `clear()`, `set_mask()` (у них `inputType: 'insertReplacementText'`). Значение в нём уже отформатировано,
241
+ `on_input` к этому моменту вызван. Для слушателей на поле или на `<form>` маскированное поле
242
+ ничем не отличается от обычного, поэтому `app/form` сбрасывает `setCustomValidity('')` у полей с
243
+ валидатором и шлёт `field:input` без дополнительной настройки.
244
+
245
+ - Символ отвергнут, и значение не изменилось — события нет; об отказе сообщает `on_reject`.
246
+ - `set()`, `clear()` и `set_mask()` шлют событие, только если значение поля изменилось, поэтому
247
+ `set()` из слушателя `input` не зацикливается. Так `#model` в App видит программную запись.
248
+ - `app/form` на каждый `input` сбрасывает `customValidity` у поля со своим валидатором. Если
249
+ маска стоит с `validate: true` на том же поле, её сообщение о неполном значении будет стёрто до
250
+ отправки. При сабмите `app/form` проверяет своим валидатором, так что полноту проверяйте в нём
251
+ (или оставьте валидацию маске и не задавайте валидатор в форме).
252
+
253
+ ## Нативная валидация (Constraint Validation API)
254
+
255
+ Признак `complete` прокидывается в `input.setCustomValidity(complete ? '' : message)`, поэтому
256
+ работают штатные `:invalid`, `input.reportValidity()` и блокировка отправки формы — без
257
+ самописной проверки. Включена автоматически для приведённых `number`/`email`; для остальных
258
+ типов — параметром `validate: true`. Пустое поле считается валидным (за обязательность отвечает
259
+ нативный `required`). Сообщение задаётся `validation_message` (или пер-масочным `{ message }`).
260
+
261
+ ## `type="number"` / `type="email"`
262
+
263
+ Эти типы не отдают selection API (spec: выделение есть только у `text/search/tel/url/password`),
264
+ поэтому при `coerce_type: true` (по умолчанию) поле приводится к `type="text"` + подходящему
265
+ `inputmode`. `number` дополнительно принимает только цифры (независимо от токенов маски), а без
266
+ явной маски получает numeral по умолчанию; `email` без явной маски — универсальную фильтр-маску.
267
+
268
+ **Caveat:** приведение типа меняет отправляемое значение формы — для numeral с группировкой
269
+ `input.value` = `'1 234 567 ₽'`, число берётся через `input.raw()` (или зеркалируется в скрытое поле).
270
+
271
+ ## `maxlength`
272
+
273
+ Атрибут `maxlength` снимается с поля (нативный считает символы **отформатированного** значения
274
+ и воевал бы с движком) и применяется как лимит длины **`raw`** — пользовательских символов.
275
+ Программный оверрайд — параметр `max_raw`.
276
+
277
+ ## Ограничения (осознанные)
278
+
279
+ - Undo/redo не поддерживается: программные записи значения опустошают нативную историю; значение просто приводится к маске.
280
+
281
+ ## Пример
282
+
283
+ ```js
284
+ new Mask({
285
+ target: 'input[name=phone]',
286
+ mask: [
287
+ '{8=>+7} (000) 000-00-00[ доб. {0;1-5}]',
288
+ '+7 (000) 000-00-00[ доб. {0;1-5}]'
289
+ ],
290
+ on_complete: (input, state) => console.log('готово:', state.raw)
291
+ });
292
+
293
+ new Mask({
294
+ target: 'input[name=date]',
295
+ mask: '00.00.0000',
296
+ filler: 'ДДММГГГГ',
297
+ placeholder: 'always',
298
+ before_slot: (input, { char, slot }) => {
299
+ if (slot == 0 && char > '3') return '0' + char; // день: 4 → 04
300
+ if (slot == 2 && char > '1') return '0' + char; // месяц: 3 → 03
301
+ }
302
+ });
303
+ ```
304
+
305
+ ### Автодополнение и автоисправление (`before_slot`)
306
+
307
+ Это два разных правила, оба через один хук:
308
+
309
+ - **Автодополнение** — когда цифра однозначна и не может быть началом двузначного числа. День: `4` не может начинать `40+`, значит это `04`. Месяц: `2`–`9` → `02`–`09`. Цифры `1`–`3` для дня неоднозначны (`1` → `01`, `10`–`19`, `31`), поэтому дополнять их нельзя — ждём второй разряд.
310
+ - **Автоисправление** — ограничение второго разряда, чтобы невозможными стали `00`, `13`–`19` (месяц) и `32`–`39` (день). Именно оно, а не автодополнение, не даёт указать месяц больше 12.
311
+
312
+ ```js
313
+ before_slot: (input, { char, slot, cells }) => {
314
+ if (slot == 0 && char > '3') return '0' + char; // день: 4 → 04
315
+ if (slot == 1 && (cells[0] == '3' && char > '1'
316
+ || cells[0] == '0' && char == '0')) return false; // не 32-39 и не 00
317
+ if (slot == 2 && char > '1') return '0' + char; // месяц: 3 → 03
318
+ if (slot == 3 && (cells[2] == '1' && char > '2'
319
+ || cells[2] == '0' && char == '0')) return false; // не 13-19 и не 00
320
+ }
321
+ ```
322
+
323
+ Нормализация символов — второй хук, `before_char`. Он не знает позиции, зато видит любой символ:
324
+
325
+ ```js
326
+ // Госномер: латиница с клавиатуры превращается в кириллицу
327
+ before_char: (input, { char }) => {
328
+ char = char.toUpperCase();
329
+ return lat2cyr[char] ?? char;
330
+ }
331
+ ```
332
+
333
+ ### Переключение маски из события
334
+
335
+ Событий и методов достаточно, чтобы разбирать ввод посимвольно и самому выбирать подмаску: `before_input` отдаёт вставляемый текст до применения правки, `set_mask` меняет маску поля на лету.
336
+
337
+ ```js
338
+ const doc = new Mask({
339
+ target: 'input[name=doc]',
340
+ mask: '{*;0-}',
341
+ before_input: (input, edit) => {
342
+ if (!edit.insert || doc.raw(input)) return; // только первый символ
343
+
344
+ let kind = Object.keys(DOC_MASKS).find(k => DOC_MASKS[k].test(edit.insert[0]));
345
+ if (!kind) return false; // символ не подошёл ни одной маске
346
+
347
+ doc.set_mask(DOC_MASKS[kind].mask, input); // дальше правка идёт по новой маске
348
+ }
349
+ });
350
+ ```
351
+
352
+ Если выбор маски выражается правилом «по первым символам», словарь делает это сам, без событий — см. форму `{ ru: …, by: … }` и «Код маски» выше.
353
+
354
+ ### Телефон с выбором страны (как intl-tel-input)
355
+
356
+ `set_mask` здесь не нужен. Одна маска-словарь на все страны, а `<select>` синхронизирован с ней в обе стороны: ввод переключает select через `state.mask_id`, выбор в select подставляет код страны перед набранной частью номера, и автоподбор выбирает нужную маску:
357
+
358
+ ```js
359
+ const COUNTRIES = {
360
+ ru: { dial: '+7', mask: ['{8=>+7} (000) 000-00-00', '+7 (000) 000-00-00'] },
361
+ kz: { dial: '+77', mask: '+7 (700) 000-00-00' },
362
+ by: { dial: '+375', mask: '+375 (00) 000-00-00' }
363
+ };
364
+
365
+ const phone = new Mask({
366
+ target: tel,
367
+ mask: Object.fromEntries(Object.entries(COUNTRIES).map(([code, c]) => [code, c.mask])),
368
+ on_input: (input, state) => { if (state.mask_id != null) select.value = state.mask_id; }
369
+ });
370
+
371
+ select.addEventListener('change', () =>
372
+ phone.set(tel, COUNTRIES[select.value].dial + phone.raw(tel))); // код меняется, номер остаётся
373
+ ```
374
+
375
+ `dial` у Казахстана - `+77`: страны с общим `+7` различаются по первой цифре номера, и для автоподбора она часть кода.
376
+
377
+ ### Несколько форматов в одном поле: цвет RAL или NCS
378
+
379
+ Шаблон выбирается по первым символам: цифра даёт RAL, `N` или `S` - NCS. Пустое поле показывает
380
+ родной `placeholder`, разделители появляются сразу, ошибку формата сообщает `on_reject`.
381
+
382
+ ```js
383
+ new Mask({
384
+ target: input,
385
+ mask: [
386
+ { pattern: 'RAL 0000', filler: '0000' },
387
+ { pattern: 'NCS S 0000-{{[YRGBN]}}', filler: '0000N' },
388
+ { pattern: 'NCS S 0000-{{[YRGB]}}00{{[YRGB]}}', filler: '0000N00N' }
389
+ ],
390
+ placeholder: 'typed',
391
+ before_char: (input, { char }) => char.toUpperCase(),
392
+ on_input: (input, state) => {
393
+ error.hidden = true;
394
+ // Подложка под полем тем же шрифтом: <span прозрачный>введённое</span><span серый>остаток</span>
395
+ typed.textContent = input.value;
396
+ rest.textContent = state.empty ? '' : state.skeleton.slice(input.value.length);
397
+ },
398
+ on_reject: (input, { reason }) => error.hidden = reason != 'slot' // 'full' и 'literal' - не ошибка
399
+ });
400
+ ```
401
+
402
+ `filler` здесь - подсказка по слотам (`0` - цифра, `N` - буква): `skeleton` после `NCS S 1050`
403
+ даёт `NCS S 1050-N`. Как заполнитель-"дырка" он не работает: вне режима ячеек набранная `N`, не
404
+ подошедшая слоту тона, отбрасывается, а не занимает его.
405
+
406
+ **С App.** Маска привязывается к узлу, а не к разметке. Поле под маской должно жить постоянно -
407
+ `#show`, а не `#if`: при перерисовке `#if` маска осталась бы на удалённом узле. Подключать маску
408
+ удобно в событии `rendered`, с проверкой `Mask.find(input)`, чтобы не привязать дважды; если узел
409
+ всё же удаляется - `destroy()`. `set()` шлёт `input`, поэтому `#model` на том же поле видит и
410
+ программную запись.
411
+
412
+ Рецепты всех типовых масок (телефон, дата, время, email, URL, IPv4/IPv6, MAC, UUID, карта, CVV, срок карты, паспорт, ИНН, СНИЛС, ОГРН, БИК, индекс, VIN, госномер, GPS) — в `examples/mask.html`.
@@ -0,0 +1,8 @@
1
+ <!-- DOCGEN:START -->
2
+ # modal
3
+
4
+ ## Файлы
5
+
6
+ - [index.js](index.js.md)
7
+
8
+ <!-- DOCGEN:END -->