@cat-of-summer/st-script 1.4.2 → 1.5.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 (63) hide show
  1. package/README.md +1 -1
  2. package/dist/shape.esm.min.js +2 -0
  3. package/dist/{cut.esm.min.js.map → shape.esm.min.js.map} +4 -4
  4. package/dist/shape.min.js +2 -0
  5. package/dist/shape.min.js.map +7 -0
  6. package/docs/README.md +36 -0
  7. package/docs/src/README.md +29 -0
  8. package/docs/src/_traits/README.md +8 -0
  9. package/docs/src/_traits/hasInstanceSymbol.js.md +57 -0
  10. package/docs/src/app/README.md +13 -0
  11. package/docs/src/app/datepicker/README.md +9 -0
  12. package/docs/src/app/datepicker/_calendar.js.md +1 -0
  13. package/docs/src/app/datepicker/index.js.md +153 -0
  14. package/docs/src/app/form/README.md +8 -0
  15. package/docs/src/app/form/index.js.md +560 -0
  16. package/docs/src/app/index.js.md +1302 -0
  17. package/docs/src/cookie/README.md +8 -0
  18. package/docs/src/cookie/index.js.md +80 -0
  19. package/docs/src/core/README.md +8 -0
  20. package/docs/src/core/index.js.md +178 -0
  21. package/docs/src/index.js.md +1 -0
  22. package/docs/src/loader/README.md +8 -0
  23. package/docs/src/loader/index.js.md +125 -0
  24. package/docs/src/mask/README.md +10 -0
  25. package/docs/src/mask/_engine.js.md +1 -0
  26. package/docs/src/mask/_groups.js.md +1 -0
  27. package/docs/src/mask/index.js.md +411 -0
  28. package/docs/src/modal/README.md +8 -0
  29. package/docs/src/modal/index.js.md +809 -0
  30. package/docs/src/observer/README.md +9 -0
  31. package/docs/src/observer/_engine.js.md +28 -0
  32. package/docs/src/observer/index.js.md +259 -0
  33. package/docs/src/route/README.md +8 -0
  34. package/docs/src/route/index.js.md +385 -0
  35. package/docs/src/select/README.md +8 -0
  36. package/docs/src/select/index.js.md +115 -0
  37. package/docs/src/shape/README.md +9 -0
  38. package/docs/src/shape/_engine.js.md +1 -0
  39. package/docs/src/shape/index.js.md +98 -0
  40. package/docs/src/st_button_widget/README.md +9 -0
  41. package/docs/src/st_button_widget/README.txt.md +4 -0
  42. package/docs/src/st_button_widget/index.js.md +68 -0
  43. package/docs/src/st_links_widget/README.md +9 -0
  44. package/docs/src/st_links_widget/README.txt.md +4 -0
  45. package/docs/src/st_links_widget/index.js.md +46 -0
  46. package/docs/src/st_widget/README.md +8 -0
  47. package/docs/src/st_widget/button/README.md +4 -0
  48. package/docs/src/toggle/README.md +8 -0
  49. package/docs/src/toggle/index.js.md +572 -0
  50. package/docs/src/typograf/README.md +9 -0
  51. package/docs/src/typograf/_engine.js.md +75 -0
  52. package/docs/src/typograf/index.js.md +165 -0
  53. package/docs/src/uploader/README.md +8 -0
  54. package/docs/src/uploader/index.js.md +112 -0
  55. package/docs/src/validator/README.md +8 -0
  56. package/docs/src/validator/index.js.md +113 -0
  57. package/package.json +3 -2
  58. package/src/index.js +1 -1
  59. package/src/{cut → shape}/_engine.js +1 -1
  60. package/src/{cut → shape}/index.js +10 -10
  61. package/dist/cut.esm.min.js +0 -2
  62. package/dist/cut.min.js +0 -2
  63. package/dist/cut.min.js.map +0 -7
@@ -0,0 +1,560 @@
1
+ # form.js
2
+
3
+ ## Обзор
4
+
5
+ `form` — приложение-расширение для `st_app`, которое берёт на себя всю механику HTML-формы: валидацию, отправку через XHR, заполнение полей и обработку ответа сервера. Подключается как обычное `st_app`-приложение и настраивается через метод `configure()`.
6
+
7
+ **Ключевые возможности:**
8
+
9
+ - Отправка формы через XHR без перезагрузки страницы
10
+ - Гибкая валидация: встроенная браузерная + кастомные функции на любые поля
11
+ - Заполнение полей любого типа через `fill()`: text, checkbox, radio, select, file (File, data-URL, URL)
12
+ - Управление полями: добавление, удаление, сброс
13
+ - Полная событийная модель для формы и каждого поля
14
+ - Автоматическое переключение `enctype` при наличии `<input type="file">`
15
+ - Обработка серверного редиректа через `{ redirect: '...' }` в ответе
16
+
17
+ ---
18
+
19
+ ## Подключение в HTML
20
+
21
+ ```html
22
+ <st-app app="form">
23
+ <form action="/submit" method="post">
24
+ <input type="text" name="name" required>
25
+ <input type="email" name="email" required>
26
+ <button type="submit">Отправить</button>
27
+ </form>
28
+ </st-app>
29
+ ```
30
+
31
+ > Внутри `<st-app app="form">` обязан находиться элемент `<form>`. Если в форме есть `<input type="file">`, `enctype="multipart/form-data"` устанавливается автоматически.
32
+
33
+ > [!warning] Разметка формы — это шаблон `st_app`
34
+ > Всё содержимое `<st-app>` проходит через шаблонизатор: `{{ … }}` в тексте и атрибутах
35
+ > вычисляется, атрибуты на `@` становятся обработчиками, на `#` — директивами (`#if`, `#for`,
36
+ > `#model`…), на `:` — привязками. Фигурные скобки в подсказках, `@` и `#` в именах атрибутов
37
+ > внутри формы легко превращаются в директиву случайно. Участок, который должен остаться как есть,
38
+ > пометьте `#pre` (см. «Директивы шаблона» в документации `st_app`).
39
+
40
+ ---
41
+
42
+ ## configure(config)
43
+
44
+ Главная точка настройки. Вызывается на элементе `<st-app>`.
45
+
46
+ ```js
47
+ form.configure({
48
+ setup() { /* вызывается после рендеринга */ },
49
+ validate: { /* валидаторы */ },
50
+ form: { /* обработчики событий формы */ },
51
+ field: { /* обработчики событий полей */ },
52
+ });
53
+ ```
54
+
55
+ | Ключ | Тип | Описание |
56
+ |---|---|---|
57
+ | `setup` | `function` | Вызывается один раз после рендеринга формы. `this` — элемент `<st-app>`. Если форма уже отрендерена — запускается немедленно через `queueMicrotask` |
58
+ | `validate` | `object` | Объект `{ selector: fn(field) => string }`. Функция возвращает строку ошибки или `''` при успехе |
59
+ | `form` | `object` | Обработчики событий формы — ключи совпадают с именами событий без префикса `form:` |
60
+ | `field` | `object` | Обработчики событий полей — ключи совпадают с именами событий без префикса `field:` |
61
+
62
+ `configure()` можно вызывать и после того, как форма отрендерена: подписка на `setup` в таком случае
63
+ срабатывает сразу, через `queueMicrotask`, и обработчики навешиваются.
64
+
65
+ ---
66
+
67
+ ## Жизненный цикл
68
+
69
+ ### Инициализация
70
+
71
+ 1. `App.create(form)` регистрирует приложение. Элемент `<st-app app="form">` получает методы и
72
+ свойства конфигурации (`action`, `method`, `headers`, `validators`, `configure()`…) —
73
+ с этого момента `configure()` можно вызывать.
74
+ 2. Событие `setup`: сначала `setup` самого приложения (заводит хранилище валидаторов), затем
75
+ подписки, сделанные через `configure()` — они навешивают `validate`, `form`, `field`.
76
+ 3. Применяются атрибуты `:action`, `:method`, `:headers` на элементе.
77
+ 4. Рендер шаблона — содержимое `<st-app>` проходит через шаблонизатор `st_app`.
78
+ 5. Событие `rendered`: приложение находит `<form>`, ставит `enctype`/`action`/`method`,
79
+ скрывает слот `[form-done]`, навешивает слушатели `input`/`focus`/`invalid`/`submit` и
80
+ валидаторы. После этого вызывается `setup` из `configure()` — поля уже в DOM.
81
+
82
+ При перерендере шаблона шаг 5 повторяется; `setup` из `configure()` — нет (`once`).
83
+
84
+ ### Слияние настроек
85
+
86
+ | Что | Источники по порядку, последний побеждает |
87
+ |---|---|
88
+ | `action`, `method`, `headers` | значение в `App.create` (`null`) → атрибут `:action`… на элементе → присваивание в коде |
89
+ | `validate` | вызовы `configure()` / `validate()` сливаются по ключу-селектору: одинаковый ключ заменяется |
90
+ | `form`, `field` | **не заменяются, а накапливаются**: каждый `configure()` добавляет свои обработчики, они вызываются в порядке вызовов |
91
+
92
+ > [!warning] Одно поле — один валидатор
93
+ > Если поле подходит под несколько ключей `validate`, действует функция последнего из них.
94
+ > Проверки одного поля собирайте в одну функцию.
95
+
96
+ > [!warning] `App.extend('form', …)` с `events` заменяет обработчики по имени
97
+ > `events` сливаются поверх базовых по ключу: собственный `events.rendered` вытеснит
98
+ > `rendered` приложения, и форма перестанет работать. Для своей логики после рендера —
99
+ > `configure({ setup })` или `addEventListener('rendered', …)`.
100
+
101
+ ### Отправка
102
+
103
+ ```
104
+ submit
105
+ ├─ валидаторы → есть ошибки → form:invalid ──(не отменено)──→ reportValidity() → field:invalid × N
106
+ └─ ошибок нет → form:before_send → запрос → form:send
107
+ ├─ 2xx, в ответе { redirect } → form:redirect → form:complete → переход (если redirect не отменён)
108
+ ├─ 2xx → form:success → done() (если не отменено) → form:complete
109
+ └─ не 2xx / сеть → form:failed → form:complete
110
+ ```
111
+
112
+ > [!note] Без `novalidate` нативные ограничения проверяет браузер — до `submit`
113
+ > Если у полей есть `required`, `pattern`, `type="email"` и т. п., а у `<form>` нет `novalidate`,
114
+ > браузер при невалидном поле не пускает событие `submit`: приходят только `field:invalid`,
115
+ > а `form:invalid` и кастомные валидаторы не срабатывают. Чтобы все ошибки шли одной дорогой через
116
+ > `form:invalid`, ставьте `<form novalidate>` — нативные ограничения при этом всё равно
117
+ > учитываются в `form:invalid`.
118
+
119
+ Что отменяет `e.preventDefault()`:
120
+
121
+ | Событие | Отменяет |
122
+ |---|---|
123
+ | `form:invalid` | браузерный `reportValidity()` (и, значит, `field:invalid`) |
124
+ | `field:invalid` | всплывающее сообщение браузера у поля |
125
+ | `form:redirect` | переход по `redirect` |
126
+ | `form:success` | показ слота `[form-done]` |
127
+
128
+ У остальных событий `preventDefault()` ни на что не влияет.
129
+
130
+ ---
131
+
132
+ ## События формы (form:*)
133
+
134
+ Подписываются через ключ `form` в `configure()` или напрямую через `addEventListener('form:*', handler)`.
135
+
136
+ | Событие | `e.detail` | Описание |
137
+ |---|---|---|
138
+ | `before_send` | `{ url, method, headers, data: FormData }` | Вызывается перед отправкой. Можно мутировать `data` (добавлять поля в FormData), изменять `url`, `method`, `headers` |
139
+ | `send` | `{ detail }` | Запрос отправлен |
140
+ | `success` | `{ data, request }` | Сервер вернул успешный ответ. Если обработчик не вызвал `e.preventDefault()` и в `<st-app>` есть слот `[form-done]` — форма скрывается, слот показывается (см. «Экран после отправки») |
141
+ | `failed` | payload | Запрос завершился ошибкой |
142
+ | `complete` | `{ data, request }` | Вызывается всегда после завершения (кроме случая редиректа) |
143
+ | `redirect` | `{ url, data, request }` | Ответ сервера содержит `{ redirect: '...' }`. Если обработчик не отменяет событие — браузер выполняет редирект |
144
+ | `invalid` | `{ errors }` | Форма не прошла валидацию. `errors` — объект `{ fieldName: validationMessage }`. Если обработчик вызывает `e.preventDefault()` — браузерный `reportValidity()` не вызывается |
145
+ | `reset` | — | Форма сброшена через `reset()` |
146
+
147
+ > `data` в событиях — результат разбора ответа: объект, если сервер вернул JSON, иначе строка.
148
+ > `request` — объект `XMLHttpRequest` с полями `status`, `statusText`, `responseText`.
149
+
150
+ ---
151
+
152
+ ## События полей (field:*)
153
+
154
+ Подписываются через ключ `field` в `configure()` или напрямую через `addEventListener('field:*', handler)`.
155
+
156
+ | Событие | `e.detail` | Описание |
157
+ |---|---|---|
158
+ | `input` | `{ field, name, value }` | Пользователь ввёл данные. Для чекбоксов `value` — `boolean` |
159
+ | `focus` | `{ field, name, value }` | Поле получило фокус |
160
+ | `invalid` | `{ field, name, value }` | Поле не прошло валидацию при сабмите. Если обработчик вызывает `e.preventDefault()` — браузерное всплывающее сообщение подавляется |
161
+
162
+ > [!note] Отмена — через `e.preventDefault()`, а не `return false`
163
+ > Обработчики навешиваются через `addEventListener`, и возвращаемое значение браузер игнорирует.
164
+ > Все события `form:*` и `field:*` создаются с `cancelable: true`.
165
+
166
+ > `field:input` приходит и от полей с маской (`Mask`): после своей правки маска сама шлёт
167
+ > всплывающий `input`. Если маска не пропустила символ и значение не изменилось, события нет.
168
+
169
+ ---
170
+
171
+ ## Свойства
172
+
173
+ Можно задавать программно на элементе до или после `configure()`.
174
+
175
+ | Свойство | Тип | По умолчанию | Описание |
176
+ |---|---|---|---|
177
+ | `action` | `string\|null` | `null` | Переопределяет атрибут `action` формы |
178
+ | `method` | `string\|null` | `null` | Переопределяет атрибут `method` формы |
179
+ | `headers` | `object\|null` | `null` | Дополнительные HTTP-заголовки запроса |
180
+ | `form` | `HTMLFormElement` | — | Ссылка на внутренний элемент `<form>` (read-only) |
181
+ | `is_done` | `boolean` | `false` | Открыт экран "Спасибо": форма спрятана `done()`, слот `[form-done]` показан (read-only). Без слота - всегда `false` |
182
+
183
+ ---
184
+
185
+ ## Методы API
186
+
187
+ ### fields(selector?)
188
+
189
+ Возвращает массив элементов формы. Без аргумента — все поля. Аргумент может быть именем поля (`name`) или CSS-селектором.
190
+
191
+ ```js
192
+ form.fields(); // все поля формы
193
+ form.fields('email'); // поля с name="email"
194
+ form.fields('[type="phone"], [type="tel"]'); // по CSS-селектору
195
+ ```
196
+
197
+ ### field(selector)
198
+
199
+ Возвращает первое найденное поле или `null`.
200
+
201
+ ```js
202
+ const emailInput = form.field('email');
203
+ ```
204
+
205
+ ### appendField(name, value, options?)
206
+
207
+ Если поле с таким именем уже существует — обновляет его `value` и применяет `options` к элементу. Если нет — создаёт элемент и добавляет в форму.
208
+
209
+ `options.tag` задаёт тег создаваемого элемента (по умолчанию `'input'`). По умолчанию `type="hidden"`, но можно переопределить через `options`. Ключ `tag` удаляется из `options` до применения к элементу.
210
+
211
+ ```js
212
+ form.appendField('sessid', BX.bitrix_sessid());
213
+ form.appendField('source', 'organic', { type: 'text' });
214
+ form.appendField('note', '', { tag: 'textarea', rows: 3 });
215
+ form.appendField('city', '', { tag: 'select' });
216
+ ```
217
+
218
+ ### removeField(name)
219
+
220
+ Удаляет поле и связанный с ним `<label>` (если есть).
221
+
222
+ ```js
223
+ form.removeField('promo_code');
224
+ ```
225
+
226
+ ### resetField(name)
227
+
228
+ Сбрасывает конкретное поле. Корректно обрабатывает checkbox, radio, file, multiple select.
229
+
230
+ ```js
231
+ form.resetField('phone');
232
+ form.resetField('agree'); // checkbox → unchecked
233
+ ```
234
+
235
+ ### reset()
236
+
237
+ Сбрасывает всю форму через нативный `form.reset()` и генерирует событие `form:reset`.
238
+
239
+ ```js
240
+ form.reset();
241
+ ```
242
+
243
+ ### fill(data)
244
+
245
+ Заполняет поля формы переданным объектом. Ключи — имена полей (`name`).
246
+
247
+ ```js
248
+ form.fill({
249
+ name: 'Иван',
250
+ agree: true,
251
+ rating: '4',
252
+ tags: ['js', 'css'], // multiple select или checkbox-группа
253
+ });
254
+ ```
255
+
256
+ Поддерживаемые типы значений по типу поля:
257
+
258
+ | Тип поля | Допустимое значение |
259
+ |---|---|
260
+ | `text`, `textarea`, и др. | `string` |
261
+ | `checkbox` | `boolean`, `string` (сравнивается с `value`), `string[]` (для группы) |
262
+ | `radio` | `string` (сравнивается с `value` каждого radio) |
263
+ | `select[multiple]` | `string[]` |
264
+ | `file` | `File`, data-URL (`data:mime;base64,...`), URL-строка (загружается через `fetch`) |
265
+
266
+ ### validate(validators)
267
+
268
+ Добавляет или обновляет валидаторы программно. Сливается с существующими.
269
+
270
+ ```js
271
+ form.validate({
272
+ '[type="tel"]': input => /^\+7/.test(input.value) ? '' : 'Неверный формат',
273
+ });
274
+ ```
275
+
276
+ ### hide() / show()
277
+
278
+ Скрывает или показывает элемент `<st-app>`.
279
+
280
+ ```js
281
+ form.hide();
282
+ form.show();
283
+ ```
284
+
285
+ ### done(state = true)
286
+
287
+ Переключает форму и слот `[form-done]`: `done()` скрывает `<form>` и показывает слот,
288
+ `done(false)` — наоборот. Вызывается сам после `form:success`; вручную нужен, чтобы вернуть
289
+ форму. Без слота в `<st-app>` ничего не делает. Текущее состояние - свойство `is_done`.
290
+
291
+ ```js
292
+ form.done(false); // снова показать форму
293
+ ```
294
+
295
+ ---
296
+
297
+ ## Экран после отправки
298
+
299
+ Разметка «Спасибо» кладётся в `<st-app>` **рядом с `<form>`, а не внутрь неё** — иначе скроется
300
+ вместе с формой. Атрибут `form-done` делает её слотом: до успеха приложение держит её скрытой
301
+ (`hidden`), после `form:success` прячет `<form>` и показывает слот.
302
+
303
+ ```html
304
+ <st-app app="form">
305
+ <form action="/feedback" method="post">
306
+ …
307
+ </form>
308
+
309
+ <div form-done>
310
+ <p>Спасибо! Мы свяжемся с вами.</p>
311
+ <button type="button" @click="done(false)">Отправить ещё</button>
312
+ </div>
313
+ </st-app>
314
+ ```
315
+
316
+ - Переключение идёт атрибутом `hidden`: анимацию или другое оформление задавайте через
317
+ `[form-done]:not([hidden])` и `form[hidden]` в своих стилях. Если у слота или формы в CSS
318
+ задан `display` (`flex`, `grid`…), он перебивает `hidden` — добавьте
319
+ `[form-done][hidden], st-app form[hidden] { display: none }`.
320
+ - Не показывать слот в конкретном случае — `e.preventDefault()` в обработчике `success`.
321
+ - `reset()` слот не прячет: форму можно очистить сразу после успеха, не теряя экран «Спасибо».
322
+ - Если спрятать нужно весь блок вокруг `<st-app>` (карточку, модалку), это по-прежнему делается
323
+ в обработчике `success` — слот отвечает только за содержимое `<st-app>`.
324
+
325
+ ### Форма в модалке
326
+
327
+ Форма не знает, что лежит в модалке: после успеха она остаётся на экране "Спасибо", и при
328
+ следующем открытии окна пользователь увидит его снова. Вернуть форму - дело закрытия окна:
329
+ в хуке `on_hide` модалки (или на событии `modal:hidden`) проверить `is_done` и вызвать `done(false)`.
330
+ `reset()` рядом очищает поля: отправленное повторно не нужно. Если окно закрыли, не отправив форму,
331
+ `is_done` равно `false` - набранное остаётся черновиком до следующего открытия.
332
+
333
+ ```js
334
+ new Modal({
335
+ content: '#feedback',
336
+ trigger: '[open-feedback]',
337
+ on_hide() {
338
+ let form = this.content.querySelector('st-app[app="form"]');
339
+ if (form.is_done) { form.done(false); form.reset(); }
340
+ },
341
+ });
342
+ ```
343
+
344
+ Если модалку и форму настраивают в разных местах (окно - общий компонент, форма - своя), то же
345
+ делается из формы, через событие окна - оно всплывает от содержимого окна до документа:
346
+
347
+ ```js
348
+ form.configure({
349
+ setup() {
350
+ document.addEventListener('modal:hidden', e => {
351
+ if (e.target.contains(this) && this.is_done) { this.done(false); this.reset(); }
352
+ });
353
+ },
354
+ });
355
+ ```
356
+
357
+ Именно закрытие, а не `before_show`: возврат в `before_show` идёт в момент открытия, и на время
358
+ анимации показа виден был бы ещё старый экран. После закрытия окно невидимо, и смена незаметна.
359
+
360
+ ---
361
+
362
+ ## Валидация
363
+
364
+ Валидаторы задаются объектом `{ selector: fn }`:
365
+
366
+ ```js
367
+ {
368
+ '[type="tel"]': input => /^\+7\s\(\d{3}\)/.test(input.value.trim())
369
+ ? ''
370
+ : 'Неверный формат номера телефона',
371
+ '[name="agree"]': input => input.checked
372
+ ? ''
373
+ : 'Необходимо согласие',
374
+ }
375
+ ```
376
+
377
+ Функция получает элемент поля и должна вернуть:
378
+ - `''` (пустую строку) — если поле валидно
379
+ - строку с описанием ошибки — если нет
380
+
381
+ Под капотом валидатор патчит `checkValidity()` и `reportValidity()` у поля, интегрируясь в стандартный механизм браузерной валидации. При сабмите сначала вызываются кастомные валидаторы, затем — `form.reportValidity()`.
382
+
383
+ ---
384
+
385
+ ## Примеры
386
+
387
+ ### Базовая отправка с обработкой ответа
388
+
389
+ ```js
390
+ document.querySelectorAll('st-app[app="form"]').forEach(form => {
391
+ form.configure({
392
+ form: {
393
+ before_send() {
394
+ // добавляем csrf-токен перед отправкой
395
+ form.appendField('sessid', BX.bitrix_sessid());
396
+ },
397
+ complete(e) {
398
+ const { data, request } = e.detail;
399
+
400
+ let messages = ['Форма успешно отправлена!'];
401
+ const success = request.status >= 200 && request.status < 300;
402
+
403
+ if (success) {
404
+ form.reset();
405
+
406
+ if (data) {
407
+ if (data.message)
408
+ messages = Array.isArray(data.message)
409
+ ? data.message
410
+ : [data.message];
411
+
412
+ form.fill(data.data || {});
413
+ }
414
+ } else {
415
+ console.error('Form submission failed', {
416
+ status: request.status,
417
+ status_text: request.statusText,
418
+ response: request.responseText,
419
+ });
420
+ messages = ['Произошла ошибка. Попробуйте позже.'];
421
+ }
422
+
423
+ success_modal.show(messages);
424
+ },
425
+ },
426
+ });
427
+ });
428
+ ```
429
+
430
+ ---
431
+
432
+ ### Маска телефона + валидация
433
+
434
+ ```js
435
+ document.querySelectorAll('st-app[app="form"]').forEach(form => {
436
+ form.configure({
437
+ setup() {
438
+ new Mask({
439
+ target: form.querySelectorAll('[type="phone"], [type="tel"]'),
440
+ mask: [
441
+ '{8=>+7} (000) 000-00-00',
442
+ '+7 (000) 000-00-00',
443
+ ],
444
+ });
445
+ },
446
+ validate: {
447
+ '[type="phone"], [type="tel"]': input =>
448
+ /^\+7 \(\d{3}\) \d{3}-\d{2}-\d{2}$/.test(input.value.trim())
449
+ ? ''
450
+ : 'Неверный формат номера телефона',
451
+ },
452
+ field: {
453
+ invalid(e) {
454
+ e.detail.field.style.borderColor = 'red';
455
+ },
456
+ input(e) {
457
+ e.detail.field.style.borderColor = '';
458
+ },
459
+ },
460
+ });
461
+ });
462
+ ```
463
+
464
+ Подсветка снимается в `field.input`: маска шлёт `input` после каждой своей правки, и там же
465
+ `form` сбрасывает `setCustomValidity('')` у полей с валидатором.
466
+
467
+ > [!tip] Показываете ошибки в `form:invalid` — снимайте их там же
468
+ > Если ошибки выводятся своим кодом по `e.detail.errors`, при повторной отправке очищайте
469
+ > состояние у полей, **которых нет** в `errors`: поле могли исправить, не вызвав `field:input`
470
+ > (автозаполнение, `fill()`, `Mask.set()`). Иначе ошибка на уже валидном поле «залипнет».
471
+ >
472
+ > ```js
473
+ > form: {
474
+ > invalid(e) {
475
+ > e.preventDefault();
476
+ > form.fields().forEach(field => {
477
+ > const message = e.detail.errors[field.name];
478
+ > field.closest('.field')?.classList.toggle('is-invalid', !!message);
479
+ > });
480
+ > },
481
+ > },
482
+ > ```
483
+
484
+ ---
485
+
486
+ ### Звёздный рейтинг
487
+
488
+ Обработка кастомного UI-элемента с привязкой к скрытому полю и сбросом при `form:reset`.
489
+
490
+ ```js
491
+ document.querySelectorAll('st-app[app="form"]').forEach(appEl => {
492
+ let starsAbort = null;
493
+
494
+ appEl.addEventListener('rendered', () => {
495
+ const container = appEl.querySelector('.review-form__stars');
496
+ if (!container) return;
497
+
498
+ if (starsAbort) starsAbort.abort();
499
+ starsAbort = new AbortController();
500
+ const { signal } = starsAbort;
501
+
502
+ const stars = Array.from(container.querySelectorAll('.review-form__star'));
503
+ const input = appEl.querySelector('[name="rating"]');
504
+ let current = 0;
505
+
506
+ function highlight(upTo) {
507
+ stars.forEach((s, i) => s.classList.toggle('is-active', i < upTo));
508
+ }
509
+
510
+ stars.forEach((star, idx) => {
511
+ star.addEventListener('mouseenter', () => highlight(idx + 1), { signal });
512
+ star.addEventListener('click', () => {
513
+ current = idx + 1;
514
+ if (input) input.value = current;
515
+ highlight(current);
516
+ }, { signal });
517
+ });
518
+
519
+ container.addEventListener('mouseleave', () => highlight(current), { signal });
520
+
521
+ // сброс звёзд при form.reset()
522
+ appEl.addEventListener('form:reset', () => {
523
+ current = 0;
524
+ if (input) input.value = 0;
525
+ highlight(0);
526
+ }, { signal });
527
+ });
528
+ });
529
+ ```
530
+
531
+ > `AbortController` используется для снятия всех слушателей при повторном рендеринге (например, при смене шаблона).
532
+
533
+ ---
534
+
535
+ ### Программное управление формой
536
+
537
+ ```js
538
+ const form = document.querySelector('st-app[app="form"]');
539
+
540
+ // заполнить форму данными (например, при редактировании)
541
+ form.fill({
542
+ name: 'Иван Иванов',
543
+ email: 'ivan@example.com',
544
+ agree: true,
545
+ role: 'admin', // radio
546
+ interests: ['js', 'css'], // checkbox-группа или multiple select
547
+ });
548
+
549
+ // добавить скрытое поле
550
+ form.appendField('user_id', 42);
551
+
552
+ // убрать поле, которое не нужно в этом контексте
553
+ form.removeField('promo_code');
554
+
555
+ // сбросить только одно поле
556
+ form.resetField('phone');
557
+
558
+ // программный сброс всей формы
559
+ form.reset();
560
+ ```