@cat-of-summer/st-script 1.5.0 → 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 (82) hide show
  1. package/dist/app/datepicker.min.js +3 -3
  2. package/dist/app/datepicker.min.js.map +3 -3
  3. package/dist/app/form.min.js +1 -1
  4. package/dist/app/form.min.js.map +3 -3
  5. package/dist/app.esm.min.js +1 -1
  6. package/dist/app.esm.min.js.map +3 -3
  7. package/dist/app.min.js +1 -1
  8. package/dist/app.min.js.map +3 -3
  9. package/dist/core.esm.min.js +1 -1
  10. package/dist/core.esm.min.js.map +3 -3
  11. package/dist/core.min.js +1 -1
  12. package/dist/core.min.js.map +3 -3
  13. package/dist/loader.esm.min.js +1 -1
  14. package/dist/loader.esm.min.js.map +3 -3
  15. package/dist/loader.min.js +1 -1
  16. package/dist/loader.min.js.map +3 -3
  17. package/dist/mask.esm.min.js +1 -1
  18. package/dist/mask.esm.min.js.map +3 -3
  19. package/dist/mask.min.js +1 -1
  20. package/dist/mask.min.js.map +3 -3
  21. package/dist/modal.esm.min.js +1 -1
  22. package/dist/modal.esm.min.js.map +3 -3
  23. package/dist/modal.min.js +1 -1
  24. package/dist/modal.min.js.map +3 -3
  25. package/dist/observer.esm.min.js +1 -1
  26. package/dist/observer.esm.min.js.map +3 -3
  27. package/dist/observer.min.js +1 -1
  28. package/dist/observer.min.js.map +3 -3
  29. package/dist/route.esm.min.js.map +2 -2
  30. package/dist/route.min.js +1 -1
  31. package/dist/route.min.js.map +2 -2
  32. package/dist/select.esm.min.js +1 -1
  33. package/dist/select.esm.min.js.map +3 -3
  34. package/dist/select.min.js +1 -1
  35. package/dist/select.min.js.map +3 -3
  36. package/dist/shape.esm.min.js +1 -1
  37. package/dist/shape.esm.min.js.map +3 -3
  38. package/dist/shape.min.js +1 -1
  39. package/dist/shape.min.js.map +3 -3
  40. package/dist/toggle.esm.min.js +1 -1
  41. package/dist/toggle.esm.min.js.map +3 -3
  42. package/dist/toggle.min.js +1 -1
  43. package/dist/toggle.min.js.map +3 -3
  44. package/dist/typograf.esm.min.js +1 -1
  45. package/dist/typograf.esm.min.js.map +3 -3
  46. package/dist/typograf.min.js +1 -1
  47. package/dist/typograf.min.js.map +3 -3
  48. package/dist/uploader.esm.min.js +1 -1
  49. package/dist/uploader.esm.min.js.map +3 -3
  50. package/dist/uploader.min.js +1 -1
  51. package/dist/uploader.min.js.map +3 -3
  52. package/dist/validator.esm.min.js +1 -1
  53. package/dist/validator.esm.min.js.map +3 -3
  54. package/dist/validator.min.js +1 -1
  55. package/dist/validator.min.js.map +3 -3
  56. package/docs/README.md +59 -5
  57. package/docs/src/app/index.js.md +91 -7
  58. package/docs/src/core/index.js.md +51 -5
  59. package/docs/src/loader/index.js.md +2 -1
  60. package/docs/src/mask/index.js.md +2 -1
  61. package/docs/src/modal/index.js.md +14 -2
  62. package/docs/src/observer/index.js.md +2 -2
  63. package/docs/src/select/index.js.md +1 -1
  64. package/docs/src/shape/index.js.md +2 -1
  65. package/docs/src/toggle/index.js.md +53 -21
  66. package/docs/src/typograf/index.js.md +2 -2
  67. package/docs/src/uploader/index.js.md +2 -1
  68. package/docs/src/validator/index.js.md +2 -1
  69. package/package.json +1 -1
  70. package/src/_traits/hasInstanceSymbol.js +14 -1
  71. package/src/app/index.js +102 -15
  72. package/src/core/index.js +83 -13
  73. package/src/loader/index.js +13 -3
  74. package/src/mask/index.js +21 -2
  75. package/src/modal/index.js +16 -6
  76. package/src/observer/index.js +3 -3
  77. package/src/select/index.js +24 -4
  78. package/src/shape/index.js +9 -0
  79. package/src/toggle/index.js +85 -28
  80. package/src/typograf/index.js +3 -3
  81. package/src/uploader/index.js +32 -9
  82. package/src/validator/index.js +20 -2
@@ -20,7 +20,7 @@ new Loader(params)
20
20
 
21
21
  | Параметр | Тип | По умолчанию | Описание |
22
22
  |---|---|---|---|
23
- | `target` | `string\|Element` | `null` | Контейнер на странице |
23
+ | `target` | `string\|function\|Element` | `null` | Контейнер на странице. Селектор и функцию пересчитывает `refresh()` |
24
24
  | `source` | `string` | `null` | Где в ответе данные. **HTML** — CSS-селектор; **JSON** — dot-path (`'data.items'`) |
25
25
  | `multiple` | `boolean` | `true` | `true` → массив элементов, `render` на каждый; `false` → один элемент, `render` один раз |
26
26
  | `mode` | `'append'\|'replace'\|'prepend'` | `'append'` | Режим вставки по умолчанию |
@@ -80,6 +80,7 @@ Lifecycle-хуки `before_init` / `on_init` / `before_load` / `on_failed` / `on
80
80
  |---|---|---|
81
81
  | `load(urlOrParams)` | `this` | Запрос + вставка. `params` (кроме `mode`) уходят в `Core.fetch`. Строка = `{ url }` |
82
82
  | `abort()` | `this` | Прервать текущий запрос |
83
+ | `refresh()` | `this` | Найти контейнер заново по `target`: прежний перерисовал App, Vue и т. п. Загрузка идёт в контейнер, найденный последним |
83
84
  | `clone(params)` | `Loader` | Новый инстанс с унаследованными параметрами (`formats` сливается поверхностно) |
84
85
  | `loading` | `boolean` | Идёт ли запрос |
85
86
  | `params` | `object` | Текущие не-функциональные параметры (без `formats`) |
@@ -20,7 +20,7 @@ new Mask(params)
20
20
 
21
21
  | Параметр | По умолчанию | Описание |
22
22
  |---|---|---|
23
- | `target` | `'input[mask]'` | Селектор \| `Element` \| `NodeList` \| массив |
23
+ | `target` | `'input[mask]'` | Селектор \| функция, возвращающая поля \| `Element` \| `NodeList` \| массив. Селектор и функцию пересчитывает `refresh()` |
24
24
  | `mask` | `null` | Маска (формы — ниже); `null` → берётся из атрибута `mask=""` самого поля (см. «Маска в атрибуте») |
25
25
  | `filler` | `'_'` | Заполнитель; строка длиной с маску — позаполнительно (`'ДДММГГГГ'`) |
26
26
  | `placeholder` | `true` | `true` — только введённое + авто-разделители (ведущие литералы вроде `'+7 ('` появляются при фокусе); `'typed'` — то же, но пустое поле остаётся пустым и в фокусе: виден родной атрибут `placeholder`, а не начало первого шаблона (несколько шаблонов с разными префиксами: `RAL`/`NCS`); `'always'` — полный скелет с заполнителями; `false` — без плейсхолдера, разделитель появляется, когда за ним введён следующий символ |
@@ -188,6 +188,7 @@ new Mask({ target: 'input[name=sum]', edit: 'end', caret: 'hide', placeholder: '
188
188
  | `clear(target?)` | Очистить поле (по умолчанию — все) |
189
189
  | `set_mask(mask, target?)` | Заменить маску на лету (по умолчанию — всем полям) |
190
190
  | `clone(params)` | Копия экземпляра с переопределёнными параметрами |
191
+ | `refresh()` | Пересканировать `target` (селектор или функцию): поля, ушедшие из DOM, отпустить, новые привязать. Нужен, когда поля перерисовывает App, Vue и т. п. Возвращает `this` |
191
192
  | `destroy()` | Разобрать: снять обработчики (в том числе `reset` на форме) и API с полей, вернуть `type` (`number`/`email`), `maxlength` и `caret-color`. Значение поля остаётся |
192
193
  | `get value` | Массив отформатированных значений всех привязанных полей |
193
194
  | `Mask.find(el)` | Экземпляр, владеющий элементом (`hasInstanceSymbol`) |
@@ -150,6 +150,9 @@ new Modal(params)
150
150
  | `content` | `string \| Element` | `'<div></div>'` | HTML-строка, CSS-селектор или готовый `Element`. Если передан селектор — элемент **физически перемещается** в `<modal-container>`. Если HTML-строка — парсится через `DOMParser`, берётся первый дочерний элемент `<body>`. |
151
151
  | `container` | `string \| Element` | `'body'` | Куда вставить `<modal>`. Принимает CSS-селектор или `Element`. |
152
152
 
153
+ > [!tip] Тема на корне приложения
154
+ > Окно по умолчанию уходит в конец `<body>`, за пределы корня приложения. Если тема объявлена CSS-переменными на корне (Primer - на `[data-color-mode]`, своя тема - на `.app`), окно её не видит: цвета и отступы пропадают. Вставляйте окно внутрь корня: `container: '.app'` (или `'[data-color-mode]'`). Окно позиционируется `fixed`, поэтому место в DOM на раскладку не влияет.
155
+
153
156
  ### Позиционирование
154
157
 
155
158
  | Параметр | Тип | По умолчанию | Описание |
@@ -198,7 +201,7 @@ new Modal(params)
198
201
 
199
202
  | Параметр | Тип | По умолчанию | Описание |
200
203
  |---|---|---|---|
201
- | `trigger` | `string \| null` | `null` | CSS-селектор элементов, которые будут открывать модал по клику. Привязка происходит один раз при создании (`querySelectorAll`). Динамически добавленные элементы не отслеживаются. Нажатая кнопка передаётся в `show(trigger)`, поэтому `before_show` / `on_show` получают её как `data` — по ней удобно менять заголовок или состав формы. |
204
+ | `trigger` | `string \| Element \| NodeList \| Array \| function \| null` | `null` | Элементы, которые открывают модал по клику: селектор, элементы или функция, которая их возвращает. Привязываются при создании; появившиеся позже (их отрисовал App, Vue) привязывает `refresh()`. Нажатая кнопка передаётся в `show(trigger)`, поэтому `before_show` / `on_show` получают её как `data` - по ней удобно менять заголовок или состав формы. |
202
205
 
203
206
  ### Хуки жизненного цикла
204
207
 
@@ -414,6 +417,15 @@ const modal = new Modal({ content: el });
414
417
  modal.destroy();
415
418
  ```
416
419
 
420
+ #### `refresh()`
421
+
422
+ Привязывает триггеры по `trigger`, которых ещё нет: их отрисовал App, Vue или другой код после создания окна. Уже привязанные не дублируются, ушедшие из DOM отпадают вместе с узлами. Возвращает экземпляр.
423
+
424
+ ```js
425
+ const modal = new Modal({ content: '#confirm', trigger: '[data-open-confirm]' });
426
+ app.addEventListener('updated', () => modal.refresh()); // <st-app> перерисовал кнопки
427
+ ```
428
+
417
429
  ---
418
430
 
419
431
  ## 7. Статические методы
@@ -669,7 +681,7 @@ notify.show();
669
681
  ```js
670
682
  const modal = new Modal({
671
683
  content: `<div class="dialog"><button action="close">✕</button><p>Привет!</p></div>`,
672
- trigger: '.open-btn', // найдёт все .open-btn при инициализации
684
+ trigger: '.open-btn', // найдёт все .open-btn при инициализации; новые - refresh()
673
685
  duration: 0.3
674
686
  });
675
687
  // Обработчик клика добавлен автоматически, явный addEventListener не нужен
@@ -58,7 +58,7 @@ new Observer(params)
58
58
 
59
59
  | Параметр | По умолчанию | Описание |
60
60
  |---|---|---|
61
- | `target` | `'[observe]'` | Селектор / Element / NodeList отслеживаемых элементов |
61
+ | `target` | `'[observe]'` | Селектор / функция / Element / NodeList отслеживаемых элементов |
62
62
  | `root` | `null` | Контейнер прокрутки (селектор / Element); `null` — viewport |
63
63
  | `axis` | `'y'` | Ось: `'y'` или `'x'` (горизонтальная лента) |
64
64
  | `start` | `'top bottom'` | Линия начала зоны |
@@ -66,7 +66,7 @@ new Observer(params)
66
66
  | `once` | `false` | После первого входа `state="active"` навсегда, элемент снимается с учёта |
67
67
  | `progress` | `false` | Писать `--progress` и вызывать `on_progress` |
68
68
  | `stagger` | `0` | Сек. Элементы, вошедшие в одном кадре, входят по очереди с этим шагом |
69
- | `live` | `false` | Подхватывать новые элементы по `target` и отпускать удалённые (`MutationObserver`). Только для строкового `target` |
69
+ | `live` | `false` | Подхватывать новые элементы по `target` и отпускать удалённые (`MutationObserver`). Только для `target` селектором или функцией |
70
70
  | `cross` | `null` | Селектор / Element целей: следить пересечение каждого элемента с ними |
71
71
 
72
72
  ### Переопределение атрибутами
@@ -55,7 +55,7 @@ new Select(params)
55
55
  |---|---|
56
56
  | `open(el)` / `close(el)` / `toggle(el)` | Управление панелью; `el` — контейнер, `<select>` или вложенный элемент |
57
57
  | `clone(params)` | Новый инстанс с объединёнными параметрами и `parent: this` |
58
- | `refresh(target?)` | Пересобрать пункты и текст триггера по нативному `<select>` (по умолчанию — все свои): после смены `<option>` или значения из кода (`select.value = …`, `v-model`). Возвращает `this` |
58
+ | `refresh(target?)` | Пересобрать пункты и текст триггера по нативному `<select>`: после смены `<option>` или значения из кода (`select.value = …`, `v-model`). С аргументом — только эти `<select>`. Без аргумента — все свои, а ещё: ушедшие из DOM отпустить и поднять новые по `target` (селектор или функция) — их перерисовал App, Vue и т. п. Возвращает `this` |
59
59
  | `destroy()` | Разобрать: снять обработчики (в том числе клик мимо на `document`), вернуть `<select>` на место контейнера с прежним `style`, убрать `select-container`. Поле можно снова передать в `new Select` |
60
60
  | `get params()` | Текущая конфигурация (без функций) |
61
61
  | `get value()` | Массив значений по управляемым `<select>` (для `multiple` — массив массивов) |
@@ -54,7 +54,7 @@ new Shape(params)
54
54
 
55
55
  | Параметр | По умолчанию | Описание |
56
56
  |---|---|---|
57
- | `target` | `'[shape]'` | элементы: селектор, Element, NodeList, массив |
57
+ | `target` | `'[shape]'` | элементы: селектор, функция, Element, NodeList, массив |
58
58
  | `attribute` | `'shape'` | имя атрибута; варианты - `<attribute>-<брейкпоинт>` |
59
59
  | `breakpoints` | `{ xs: 360, sm: 576, md: 768, lp: 1024, lg: 1280, dt: 1536, xl: 1920 }` | шкала брейкпоинтов (min, px). По умолчанию это шкала st-style. Своя шкала проекта передаётся сюда же |
60
60
  | `scale` | `10` | px макета в `1rem`: координаты переводятся в rem и масштабируются вместе с вёрсткой. `0` - без масштаба, 1px макета = 1px экрана |
@@ -71,6 +71,7 @@ new Shape(params)
71
71
 
72
72
  - `refresh(target = params.target)` - перечитать атрибуты и перерисовать. Элементы под `target`, которых
73
73
  ещё нет у экземпляра, берутся под управление: так подключают разметку, добавленную после инициализации.
74
+ Элементы, ушедшие из DOM (их перерисовал App, Vue и т. п.), отпускаются.
74
75
  - `destroy()` - снять наблюдатели и слушатели, убрать svg, вернуть элементу прежний `clip-path`.
75
76
  - `clone(params)` - новый экземпляр с теми же параметрами и хуками.
76
77
 
@@ -52,8 +52,8 @@ new Toggle({ trigger: '[trigger]', target: null })
52
52
  └── trigger #N ──► targets: [ ... ]
53
53
  ```
54
54
 
55
- - **Триггеры** ищутся один раз при создании по селектору `params.trigger` (по умолчанию
56
- `[trigger]`). На каждый вешается обработчик события `params.action`.
55
+ - **Триггеры** ищутся при создании по `params.trigger` (по умолчанию `[trigger]`). На каждый
56
+ вешается обработчик события `params.action`. Появившиеся позже подхватывает `refresh()`.
57
57
  - **Цели** разрешаются **при каждом переключении** (а не один раз) — см. раздел
58
58
  [8](#8-разрешение-целей-target). У одного триггера может быть несколько целей.
59
59
  - Каждый триггер хранит ссылку на экземпляр через приватный Symbol — доступно через
@@ -117,13 +117,13 @@ new Toggle(params)
117
117
 
118
118
  | Параметр | Тип | По умолчанию | Описание |
119
119
  |---|---|---|---|
120
- | `trigger` | `string \| Element \| NodeList \| Array` | `'[trigger]'` | Что считать триггерами. Селектор резолвится через `querySelectorAll` один раз при создании. |
120
+ | `trigger` | `string \| function \| Element \| NodeList \| Array` | `'[trigger]'` | Что считать триггерами. Селектор или функция, возвращающая элементы, резолвится при создании и заново в `refresh()`. Готовый список элементов `refresh()` не пересчитывает. |
121
121
  | `target` | `string \| function \| Element \| NodeList \| Array \| null` | `null` | Цели триггера. Если функция — вызывается как `target(trigger)` при каждом переключении. Если `null` — берётся из атрибута `target=""` триггера. См. раздел [8](#8-разрешение-целей-target). |
122
122
  | `action` | `string` | `'click'` | Имя DOM-события на триггере. Спец-значение `'hover'` → `mouseenter` включает, `mouseleave` выключает. |
123
123
  | `duration` | `number` | `0` | Длительность перехода в секундах (= время до установки финального состояния и вызова `on_*`). CSS-`transition` задаётся разработчиком. |
124
124
  | `allow_interrupt` | `boolean` | `false` | Разрешить прерывание текущего перехода обратным. |
125
- | `anchor` | `boolean` | `false` | Синхронизировать активный триггер с хешем URL (deep-linking). См. раздел [12](#12-якорные-ссылки-deep-linking). |
126
- | `keep_history` | `boolean` | `false` | Создавать ли запись в истории на каждое переключение. `false` → `replaceState` (кнопка «назад» уходит со страницы); `true` → `pushState` + реакция на `hashchange` (кнопка «назад» возвращает предыдущий таб). **Принудительно включает `anchor: true`** (без якоря история хеша бессмысленна). |
125
+ | `anchor` | `false \| true \| 'trigger' \| 'target'` | `false` | Синхронизировать активный триггер с хешем URL (deep-linking). `true` и `'trigger'` пишут в hash id триггера, `'target'` - id панели. См. раздел [12](#12-якорные-ссылки-deep-linking). |
126
+ | `keep_history` | `boolean` | `false` | Создавать ли запись в истории на каждое переключение. `false` → `replaceState` (кнопка "назад" уходит со страницы); `true` → `pushState` + реакция на `hashchange` (кнопка "назад" возвращает предыдущий таб). **Включает `anchor: true`, если якорь не задан** (без якоря история хеша бессмысленна); `anchor: 'target'` сохраняется. |
127
127
  | `group` | `false \| true \| 'radio'` | `false` | Взаимоисключение триггеров **одного экземпляра**. `true` — аккордеон: при активации триггера остальные активные триггеры экземпляра деактивируются (ещё не доигравший `activating` — только при `allow_interrupt: true`), их хуки `before_/on_deactivate(d)` срабатывают как обычно; повторный клик закрывает открытый. `'radio'` — табы: то же, но `toggle()` (и клик) по активному триггеру ничего не делает, и один таб всегда остаётся открытым. Явный `deactivate()` работает в обоих режимах. |
128
128
  | `indicator` | `string \| Element \| function \| null` | `null` | Элемент, который следует за активным триггером (пилюля, подчёркивание табов). Функция вызывается как `indicator(toggle)` один раз при создании. Индикатор получает CSS-переменные `--indicator-x/-y/-width/-height` и `state="active" \| "inactive"`. `clone()` копирует его вместе с остальными параметрами - для другой ленты переопределяйте `indicator` вместе с `trigger`. См. раздел [13](#13-индикатор-и-прокрутка-табов). |
129
129
  | `reveal` | `boolean` | `false` | Доводить ли активируемый кликом или из кода триггер до полной видимости в горизонтальной ленте с прокруткой. При переходе по якорю и для стартового активного триггера доводка идёт всегда; при `action: 'hover'` по клику - никогда. См. раздел [13](#13-индикатор-и-прокрутка-табов). |
@@ -230,6 +230,20 @@ const tabs = new Toggle({ trigger: '#tabs [trigger]', group: 'radio', anchor: tr
230
230
  tabs.destroy();
231
231
  ```
232
232
 
233
+ #### `refresh()`
234
+
235
+ Пересканирует `trigger` (селектор или функцию): триггеры, ушедшие из DOM, снимает (обработчики, методы, якорь, слежение индикатора), новые привязывает. Если вкладки отрисовались после создания `Toggle`, а в hash уже их якорь, — открывает нужную. Индикатор пересчитывается. Возвращает экземпляр.
236
+
237
+ Нужен, когда триггеры перерисовывает App, Vue или свой код: `Toggle` о них не знает.
238
+
239
+ ```js
240
+ // вкладки из #for внутри <st-app>
241
+ const tabs = new Toggle({ trigger: () => app.querySelectorAll('[role=tab]'), group: 'radio', anchor: 'target' });
242
+ app.addEventListener('updated', () => tabs.refresh());
243
+ ```
244
+
245
+ Новые триггеры начинают с `state` из разметки (без него - `inactive`). Строку `#for` с `#key` App переносит, не пересоздавая, и её состояние сохраняется.
246
+
233
247
  ---
234
248
 
235
249
  ## 7. Статические методы
@@ -334,9 +348,23 @@ new Toggle({
334
348
  });
335
349
  ```
336
350
 
337
- Стартовый таб задаётся атрибутом `state="active"` на триггере и его цели — `Toggle` не
351
+ Стартовый таб задаётся атрибутом `state="active"` на триггере и его цели - `Toggle` не
338
352
  перезаписывает уже проставленный `state`.
339
353
 
354
+ **Доступность.** У триггера с `role="tab"` `Toggle` сам ведёт `aria-selected` (`"true"` у
355
+ активного, `"false"` у остальных), у триггера с атрибутом `aria-expanded` в разметке (аккордеон,
356
+ раскрывающийся блок) - `aria-expanded`. Значения меняются сразу при переключении, до конца
357
+ анимации. `tabindex` не трогается: навигации стрелками в `Toggle` нет, и без неё вкладки с
358
+ `tabindex="-1"` нельзя было бы выбрать с клавиатуры.
359
+
360
+ ```html
361
+ <nav role="tablist">
362
+ <button role="tab" trigger target="#tab-1" state="active">Первый</button>
363
+ <button role="tab" trigger target="#tab-2">Второй</button>
364
+ </nav>
365
+ <button aria-expanded="false" class="faq" target="#answer">Вопрос</button>
366
+ ```
367
+
340
368
  ### Кнопка-переключатель (без целей)
341
369
 
342
370
  ```js
@@ -391,10 +419,11 @@ inst.toggle(someTrigger);
391
419
 
392
420
  ## 11. Известные особенности и ограничения
393
421
 
394
- ### Триггеры привязываются один раз
422
+ ### Новые триггеры - через `refresh()`
395
423
 
396
- Селектор `params.trigger` резолвится в конструкторе. Элементы, добавленные в DOM позже,
397
- обработчик не получают — добавляйте их вручную или используйте делегирование.
424
+ `params.trigger` резолвится в конструкторе. Элементы, добавленные в DOM позже, `Toggle` сам не
425
+ замечает: вызовите `refresh()` после перерисовки (в `<st-app>` - в событии `updated`). Передавайте
426
+ триггеры селектором или функцией: готовый список элементов `refresh()` не пересчитывает.
398
427
 
399
428
  ### Цели разрешаются при каждом переключении
400
429
 
@@ -403,9 +432,9 @@ inst.toggle(someTrigger);
403
432
 
404
433
  ### Группа — это один экземпляр
405
434
 
406
- `group` действует на триггеры одного `Toggle`. Две независимые группы табов на странице — два
407
- экземпляра с разными селекторами `trigger`. Триггеры, добавленные в DOM позже, в группу не
408
- попадают (см. выше).
435
+ `group` действует на триггеры одного `Toggle`. Две независимые группы табов на странице - два
436
+ экземпляра с разными селекторами `trigger`. Триггеры, добавленные в DOM позже, попадают в группу
437
+ после `refresh()` (см. выше).
409
438
 
410
439
  ### Состояния триггера и целей независимы
411
440
 
@@ -428,20 +457,23 @@ inst.toggle(someTrigger);
428
457
 
429
458
  ## 12. Якорные ссылки (deep-linking)
430
459
 
431
- При `anchor: true` активный триггер синхронизируется с хешем адресной строки: активация
460
+ При `anchor` активный триггер синхронизируется с хешем адресной строки: активация
432
461
  дописывает `#id`, открытие страницы с `#id` сразу активирует соответствующий триггер. По умолчанию
433
- `anchor` выключен (`false`); `keep_history: true` включает его принудительно.
462
+ `anchor` выключен (`false`); `keep_history: true` включает его, если он не задан.
463
+
464
+ ### Какой id попадает в URL
434
465
 
435
- ### Какой id попадает в URL (авто-приоритет)
466
+ `anchor: true` или `'trigger'` - приоритет у триггера:
436
467
 
437
- Для каждого триггера id вычисляется так:
468
+ 1. если у **самого триггера** есть `id` - пишется он;
469
+ 2. иначе, если у триггера ровно **одна** цель и у неё есть `id` - пишется `id` цели;
470
+ 3. иначе - триггер в URL не отражается.
438
471
 
439
- 1. если у **самого триггера** есть `id` — пишется он;
440
- 2. иначе, если у триггера ровно **одна** цель и у неё есть `id` — пишется `id` цели;
441
- 3. иначе — триггер в URL не отражается.
472
+ `anchor: 'target'` - приоритет у панели: сначала `id` единственной цели, затем `id` триггера.
473
+ Ссылку на раздел естественнее давать на панель (`#core-keys`), а не на кнопку вкладки
474
+ (`#core-keys-tab`).
442
475
 
443
- При коллизии (есть `id` и у триггера, и у единственной цели) **выигрывает id триггера**. Триггеры
444
- без подходящего `id` (например, hover-меню без `id` у дропдауна) ничего не пишут в URL.
476
+ Триггеры без подходящего `id` (например, hover-меню без `id` у дропдауна) ничего не пишут в URL.
445
477
 
446
478
  ```html
447
479
  <!-- id у цели → в URL попадёт #a2 -->
@@ -56,10 +56,10 @@ new Typograf(params)
56
56
 
57
57
  | Параметр | По умолчанию | Описание |
58
58
  |---|---|---|
59
- | `target` | `'[typograf]'` | Селектор / Element / NodeList целей |
59
+ | `target` | `'[typograf]'` | Селектор / функция / Element / NodeList целей |
60
60
  | `root` | `null` | Контейнер прокрутки для ленивости (селектор / Element); `null` — viewport |
61
61
  | `lazy` | `true` | Обрабатывать цель, когда до неё остаётся не больше экрана. `false` — все цели сразу |
62
- | `live` | `false` | Подхватывать новые цели по `target` (`MutationObserver` на документе). Только для строкового `target` |
62
+ | `live` | `false` | Подхватывать новые цели по `target` (`MutationObserver` на документе). Только для `target` селектором или функцией |
63
63
  | `rules` | `{}` | Поверх правил по умолчанию: `{ last_word: false }` выключает одно правило, `{ max_chain: 20 }` меняет предел цепочки, `{ max_chain: 0 }` снимает его |
64
64
  | `skip` | см. выше | Селектор того, что не трогается. Свой список заменяет стандартный целиком |
65
65
 
@@ -33,7 +33,7 @@ new Uploader(params)
33
33
 
34
34
  | Параметр | Описание |
35
35
  |---|---|
36
- | `target` | Корневой контейнер: CSS-селектор (можно несколько совпадений), элемент или список элементов |
36
+ | `target` | Корневой контейнер: CSS-селектор (можно несколько совпадений), функция, элемент или список элементов. Селектор и функцию пересчитывает `refresh()` |
37
37
  | `input_name` | Имя `<input file>` для передачи файлов в форме. Обязателен. При `limits.files != 1` к нему дописывается `[]` |
38
38
  | `delete_name` | Имя поля для значений удалённых существующих файлов (по умолчанию `<input_name>_to_delete`) |
39
39
  | `entry` | Шаблон записи файла: CSS-селектор существующих записей (по умолчанию `'*[file-item]'`) или HTML-строка |
@@ -87,6 +87,7 @@ new Uploader(params)
87
87
 
88
88
  - `uploader.clear()` — убрать все записи из всех контейнеров экземпляра. Для каждой вызываются `on_file_delete` и `uploader:delete`; `before_file_delete` не спрашивается. Существующие файлы уходят в `delete_name`, как при удалении кнопкой.
89
89
  - `target.clear()` — то же для одного контейнера.
90
+ - `uploader.refresh()` — пересканировать `target` (селектор или функцию): корни, ушедшие из DOM, отпустить, новые поднять. Нужен, когда корень загрузчика перерисовывает App, Vue и т. п. Содержимое корня (записи, кнопки, зона перетаскивания) ведёт сам `Uploader`: снаружи его не перерисовывают, в `<st-app>` закройте его `#pre`.
90
91
  - `uploader.destroy()` — разобрать: снять обработчики и скрытое поле выбора файлов. Записи и поля с файлами остаются в разметке, контейнер можно передать в новый `Uploader`.
91
92
 
92
93
  ## Свойства `target` после инициализации
@@ -21,7 +21,7 @@ new Validator(params)
21
21
 
22
22
  | Параметр | По умолчанию | Описание |
23
23
  |---|---|---|
24
- | `target` | `'[validate]'` | Селектор / Element / NodeList / Array валидируемых элементов |
24
+ | `target` | `'[validate]'` | Селектор / функция / Element / NodeList / Array валидируемых элементов. Селектор и функцию пересчитывает `refresh()` |
25
25
  | `events` | `['input', 'blur']` | События, запускающие проверку |
26
26
  | `test` | `null` | Правило или массив правил (все должны пройти): `RegExp`, строка-regexp или `fn(el)` |
27
27
  | `property` | `null` | Свойство элемента, к которому применяются regexp-правила (`innerHTML`, `textContent`, …) |
@@ -54,6 +54,7 @@ new Validator(params)
54
54
  | `check(target?)` | Проверить элементы (по умолчанию — все свои): `state`, `setCustomValidity`, хуки. Возвращает `true`, если все валидны |
55
55
  | `reset(target?)` | Снять `state`; `setCustomValidity` пересчитывается без хуков, чтобы submit оставался заблокированным |
56
56
  | `clone(params)` | Новый инстанс с объединёнными параметрами и `parent: this` |
57
+ | `refresh()` | Пересканировать `target` (селектор или функцию): поля, ушедшие из DOM, отпустить, новые привязать. Нужен, когда поля перерисовывает App, Vue и т. п. Возвращает `this` |
57
58
  | `destroy()` | Разобрать: снять обработчики (в том числе `reset` на форме), `state`, `setCustomValidity` и `el.check()`/`el.reset()` со своих полей. На поле можно поднять новый Validator |
58
59
  | `get params()` | Текущая конфигурация (без хуков) |
59
60
  | `get valid()` | Массив `boolean` по привязанным элементам — без `state` и хуков |
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@cat-of-summer/st-script",
3
- "version": "1.5.0",
3
+ "version": "1.6.0",
4
4
  "description": "Standalone JS classes/components (Modal, App, Typograf , …), shipped as ESM and IIFE/CDN builds.",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -11,9 +11,11 @@ export const element = (param) => {
11
11
  };
12
12
 
13
13
  // Множество существующих элементов: Element | NodeList | HTMLCollection | Array |
14
- // CSS-селектор → Array<Element>. Без побочных эффектов (несовпадение → []).
14
+ // CSS-селектор | функция, возвращающая одно из них → Array<Element>. Без побочных эффектов
15
+ // (несовпадение → []). Селектор и функцию refresh() модулей пересчитывает заново.
15
16
  export const elements = (param) => {
16
17
  if (param == null) return [];
18
+ if (typeof param == 'function') return elements(param());
17
19
  if (param instanceof Element) return [param];
18
20
  if (param instanceof NodeList || param instanceof HTMLCollection) return [...param];
19
21
  if (Array.isArray(param)) return param.flatMap(elements);
@@ -25,6 +27,17 @@ export const elements = (param) => {
25
27
  }
26
28
  };
27
29
 
30
+ // Можно ли пересканировать параметр в refresh(): готовый список элементов — нельзя.
31
+ export const rescannable = (param) => typeof param == 'string' || typeof param == 'function';
32
+
33
+ // Подписки одного элемента: обрываются вместе с общим сигналом экземпляра (destroy) и
34
+ // отдельно — refresh() отпускает элемент, ушедший из DOM, со слушателями на его форме.
35
+ export const linked = (signal) => {
36
+ let controller = new AbortController();
37
+ signal.addEventListener('abort', () => controller.abort(), { once: true, signal: controller.signal });
38
+ return controller;
39
+ };
40
+
28
41
  export const find = (param) => element(param)?.[instance];
29
42
 
30
43
  export const own = (el, inst) => { if (el) el[instance] = inst; return el; };
package/src/app/index.js CHANGED
@@ -45,8 +45,27 @@ export default class App extends HTMLElement {
45
45
  return copy;
46
46
  }
47
47
 
48
+ // Опции конфига, которые не становятся свойствами компонента, и их ожидаемый вид.
49
+ static #reserved = {
50
+ setup: ['function', 'функция'],
51
+ template: ['string', 'строка'],
52
+ events: ['object', 'обработчики { имя: функция }'],
53
+ helpers: ['object', 'объект { имя: значение }']
54
+ };
55
+
56
+ // Данные с именем опции (events: [] для <select>) иначе молча становятся опцией.
57
+ static #check(options) {
58
+ for (let [key, [type, hint]] of Object.entries(App.#reserved)) {
59
+ let value = options[key];
60
+ if (value === undefined || typeof value === type && !Array.isArray(value) && value !== null) continue;
61
+ let got = Array.isArray(value) ? 'массив' : value === null ? 'null' : typeof value;
62
+ throw new TypeError(`App.create("${options.app}"): "${key}" - ${hint}, получен ${got}. Если это данные, переименуйте поле`);
63
+ }
64
+ }
65
+
48
66
  static create(options) {
49
67
  let { app, setup = () => {}, template = ``, events = {} } = options;
68
+ App.#check(options);
50
69
  if (App.#apps.has(app))
51
70
  throw new Error(`Application "${app}" already exists!`);
52
71
  App.#apps.set(app, { setup, template, events, config: options });
@@ -60,6 +79,8 @@ export default class App extends HTMLElement {
60
79
  let base = App.#apps.get(app);
61
80
  if (!base)
62
81
  throw new Error(`Application "${app}" not found!`);
82
+ // До слияния: массив в events растворился бы в { ...base.events, ...options.events }.
83
+ App.#check(options);
63
84
  let baseConfig = base.config;
64
85
  // Через дескрипторы, а не spread: spread вычисляет геттеры и замораживает их значения.
65
86
  let merged = Object.defineProperties({}, {
@@ -88,6 +109,8 @@ export default class App extends HTMLElement {
88
109
  #triggeredKeys = new Set();
89
110
  #pendingFlush = false;
90
111
  #tickWaiters = [];
112
+ // В проходах текущего flush выполнялись эффекты: в конце отправляется updated.
113
+ #redrawn = false;
91
114
  // Тип значения из конфига: по нему приводится строка из атрибута :prop.
92
115
  #types = new Map();
93
116
  #methodWrappers = new Map();
@@ -370,6 +393,7 @@ export default class App extends HTMLElement {
370
393
  }
371
394
  this.#flushing = true;
372
395
  const runFlush = () => {
396
+ this.#redrawn ||= this.#updateQueue.size > 0;
373
397
  this.#updateQueue.forEach(effect => {
374
398
  try {
375
399
  effect();
@@ -409,8 +433,13 @@ export default class App extends HTMLElement {
409
433
  this.#pendingFlush = false;
410
434
  this.#flushing = true;
411
435
  Promise.resolve().then(runFlush);
412
- } else
436
+ } else {
413
437
  this.#tickWaiters.splice(0).forEach(resolve => resolve());
438
+ // updated — DOM догнал данные после перерисовки: сигнал внешнему коду
439
+ // (модулям с refresh()), что разметка шаблона могла смениться.
440
+ if (this.#redrawn && this.#rendered) this.dispatchEvent('updated');
441
+ this.#redrawn = false;
442
+ }
414
443
  };
415
444
  Promise.resolve().then(runFlush);
416
445
  }
@@ -591,7 +620,10 @@ export default class App extends HTMLElement {
591
620
  let descriptor = Object.getOwnPropertyDescriptor(this, key);
592
621
  if (!descriptor || !('value' in descriptor)) return;
593
622
  this.#warnedKeys.add(key);
594
- console.warn(`<st-app app="${this.getAttribute('app') ?? ''}">: свойство "${key}" не объявлено в конфиге и не реактивно`);
623
+ let reason = key in App.#reserved || key === 'app'
624
+ ? 'занято опцией App.create, переименуйте его'
625
+ : 'не объявлено в конфиге';
626
+ console.warn(`<st-app app="${this.getAttribute('app') ?? ''}">: свойство "${key}" ${reason} и не реактивно`);
595
627
  }
596
628
 
597
629
  #evalExpression(expr) {
@@ -710,17 +742,52 @@ export default class App extends HTMLElement {
710
742
  this.#bindings.push({ type: 'class', element, effect });
711
743
  }
712
744
 
745
+ // #attr="{ disabled: busy, 'aria-selected': on }" и #attr.disabled="busy": значение берётся
746
+ // из выражения, а не из строки атрибута, поэтому шаблонизатор (Astro) не превратит его
747
+ // в голый disabled. Булевы атрибуты ставятся по истинности, остальные null и undefined
748
+ // снимают, иначе пишется String(). Имя, пропавшее из объекта, снимается.
749
+ #bindAttrs(element, attr) {
750
+ let name = attr.name.slice(6), expr = attr.value;
751
+ let active = new Set();
752
+ let apply = (attrName, value) => {
753
+ let live = App.#live_properties.has(attrName) && attrName in element
754
+ && (attrName !== 'value' || element.tagName === 'INPUT');
755
+ if (App.#boolean_attributes.has(attrName)) {
756
+ element.toggleAttribute(attrName, !!value);
757
+ if (live) element[attrName] = !!value;
758
+ } else if (value == null)
759
+ element.removeAttribute(attrName);
760
+ else {
761
+ element.setAttribute(attrName, value = String(value));
762
+ if (live && element.value !== value)
763
+ element.value = value;
764
+ }
765
+ };
766
+ let effect = this.#effect(() => {
767
+ let value = this.#evalExpression(expr);
768
+ let next = name ? { [name]: value } : value && typeof value === 'object' ? value : {};
769
+ active.forEach(attrName => attrName in next || apply(attrName, null));
770
+ active = new Set(Object.keys(next));
771
+ active.forEach(attrName => apply(attrName, next[attrName]));
772
+ });
773
+ this.#bindings.push({ type: 'attrs', element, effect });
774
+ }
775
+
713
776
  #bindModel(element, attr) {
714
777
  let prop = attr.value;
715
778
  let effect = this.#effect(() => {
716
779
  let value = this.#evalExpression(prop);
780
+ // Массив у checkbox — группа: флажок отмечен, если его value есть в массиве.
717
781
  if (element.tagName === 'INPUT' && element.type === 'checkbox')
718
- element.checked = !!value;
782
+ element.checked = Array.isArray(value) ? value.some(v => String(v) === element.value) : !!value;
719
783
  else if (element.tagName === 'INPUT' && element.type === 'radio')
720
784
  element.checked = element.value === value;
721
785
  else if (element.tagName === 'SELECT') {
722
786
  // Опции из #for появляются позже эффекта: ставим значение ещё раз после них.
723
- let sync = () => { element.value = value; };
787
+ let values = element.multiple && Array.isArray(value) ? value.map(String) : [];
788
+ let sync = element.multiple
789
+ ? () => { for (let option of element.options) option.selected = values.includes(option.value); }
790
+ : () => { element.value = value; };
724
791
  App.#selectSync.set(element, sync);
725
792
  sync();
726
793
  queueMicrotask(sync);
@@ -729,19 +796,26 @@ export default class App extends HTMLElement {
729
796
  });
730
797
  let capturedLoopCtx = this.#loopContext;
731
798
  let eventName = element.tagName === 'SELECT' ? 'change' : 'input';
732
- let handler = (e) => {
733
- let newValue;
734
- if (element.type === 'checkbox')
735
- newValue = element.checked;
799
+ let read = () => {
800
+ if (element.type === 'checkbox') {
801
+ // Группа получает новый массив, а не правку на месте: так меняется сам prop.
802
+ let list = this.#evalExpression(prop);
803
+ if (!Array.isArray(list)) return element.checked;
804
+ list = list.filter(v => String(v) !== element.value);
805
+ return element.checked ? [...list, element.value] : list;
806
+ }
736
807
  // Пустое числовое поле — null, а не NaN из valueAsNumber.
737
- else if (element.type === 'number' || element.type === 'range')
738
- newValue = element.value === '' ? null : element.valueAsNumber;
739
- else
740
- newValue = element.value;
808
+ if (element.type === 'number' || element.type === 'range')
809
+ return element.value === '' ? null : element.valueAsNumber;
810
+ if (element.tagName === 'SELECT' && element.multiple)
811
+ return Array.from(element.selectedOptions, option => option.value);
812
+ return element.value;
813
+ };
814
+ let handler = () => {
741
815
  if (capturedLoopCtx)
742
- this.#withLoopVars(capturedLoopCtx, () => this.#assign(prop, newValue));
816
+ this.#withLoopVars(capturedLoopCtx, () => this.#assign(prop, read()));
743
817
  else
744
- this.#assign(prop, newValue);
818
+ this.#assign(prop, read());
745
819
  };
746
820
  element.addEventListener(eventName, handler);
747
821
  this.#bindings.push({ type: 'model', element, effect, handler });
@@ -880,7 +954,8 @@ export default class App extends HTMLElement {
880
954
  let vars = { [itemName]: value, $index: index };
881
955
  if (key !== undefined) vars.$key = key;
882
956
  let ctx = this.#loopScope(vars);
883
- let id = keyExpr ? this.#withLoopVars(ctx, () => this.#evalExpression(keyExpr)) : Symbol();
957
+ // Ключ-объект (#key="row") — по исходнику: прокси у каждого пути items.N свой.
958
+ let id = keyExpr ? App.#raw(this.#withLoopVars(ctx, () => this.#evalExpression(keyExpr))) : Symbol();
884
959
  if (keyExpr && next.has(id))
885
960
  console.warn('Duplicate #key in #for:', loopExpr, id);
886
961
  let prev = rendered.get(id);
@@ -905,6 +980,10 @@ export default class App extends HTMLElement {
905
980
  });
906
981
  rendered.forEach(dispose);
907
982
  rendered = next;
983
+ // Перестановка узла в DOM снимает с него фокус: полю перенесённой строки он
984
+ // возвращается вместе с выделением.
985
+ let focused = anchor.parentNode.contains(document.activeElement) ? document.activeElement : null, range = null;
986
+ try { range = focused && [focused.selectionStart, focused.selectionEnd, focused.selectionDirection]; } catch {}
908
987
  let ref = anchor;
909
988
  for (let i = ordered.length - 1; i >= 0; i--) {
910
989
  let node = ordered[i].node;
@@ -912,6 +991,10 @@ export default class App extends HTMLElement {
912
991
  anchor.parentNode.insertBefore(node, ref);
913
992
  ref = node;
914
993
  }
994
+ if (focused?.isConnected && document.activeElement !== focused) {
995
+ focused.focus({ preventScroll: true });
996
+ try { if (range?.[0] != null) focused.setSelectionRange(...range); } catch {}
997
+ }
915
998
  let select = anchor.parentNode?.closest?.('select');
916
999
  if (select) App.#selectSync.get(select)?.();
917
1000
  });
@@ -997,6 +1080,10 @@ export default class App extends HTMLElement {
997
1080
  this.#bindClass(element, attr);
998
1081
  element.removeAttribute(attr.name);
999
1082
  }
1083
+ else if (attr.name === '#attr' || attr.name.startsWith('#attr.')) {
1084
+ this.#bindAttrs(element, attr);
1085
+ element.removeAttribute(attr.name);
1086
+ }
1000
1087
  else if (attr.name === '#show') {
1001
1088
  this.#bindShow(element, attr);
1002
1089
  element.removeAttribute(attr.name);