@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,604 @@
1
+ # toggle.js
2
+
3
+ ## Содержание
4
+
5
+ 1. [Описание](#1-описание)
6
+ 2. [Модель: триггеры и цели](#2-модель-триггеры-и-цели)
7
+ 3. [Машина состояний](#3-машина-состояний)
8
+ 4. [Параметры конструктора](#4-параметры-конструктора)
9
+ 5. [Хуки жизненного цикла](#5-хуки-жизненного-цикла)
10
+ 6. [Публичные свойства и методы](#6-публичные-свойства-и-методы)
11
+ 7. [Статические методы](#7-статические-методы)
12
+ 8. [Разрешение целей (target)](#8-разрешение-целей-target)
13
+ 9. [CSS-анимация через атрибут state](#9-css-анимация-через-атрибут-state)
14
+ 10. [Примеры](#10-примеры)
15
+ 11. [Известные особенности и ограничения](#11-известные-особенности-и-ограничения)
16
+ 12. [Якорные ссылки (deep-linking)](#12-якорные-ссылки-deep-linking)
17
+ 13. [Индикатор и прокрутка табов](#13-индикатор-и-прокрутка-табов)
18
+
19
+ ---
20
+
21
+ ## 1. Описание
22
+
23
+ `Toggle` — универсальный примитив переключения состояния. Один экземпляр обслуживает
24
+ **множество независимых триггеров**; по событию (`click` и т.п.) триггер переключается между
25
+ состояниями и вместе с собой переводит свои **цели** (targets). Класс приходит на смену
26
+ `st_accordion` и достаточно общий, чтобы строить на нём аккордеоны, кнопки-переключатели,
27
+ спойлеры, hover-меню и т.п.
28
+
29
+ **Ключевые принципы:**
30
+
31
+ - **Только состояние.** Класс лишь меняет атрибут `state` на триггере и целях и вызывает
32
+ пользовательские замыкания. Он **не трогает** `display`/`style` триггеров и целей - весь визуал
33
+ отдаётся CSS (по селекторам `[state="..."]`). Исключения - табы: индикатору (`indicator`)
34
+ пишутся CSS-переменные с координатами активного таба, и лента с прокруткой доводится до
35
+ активного таба (раздел [13](#13-индикатор-и-прокрутка-табов)).
36
+ - **Группы - параметром `group`.** Аккордеон (`true`) и табы (`'radio'`) внутри одного экземпляра;
37
+ более сложное взаимоисключение пишется в хуках через `deactivate()` у соседей.
38
+ - **Триггеры и цели независимы.** Один target может управляться несколькими триггерами; источник
39
+ направления — состояние самого триггера. События триггера и целей раздельные и асинхронные —
40
+ это позволяет комбинировать цепочки toggle-ров (цель одного может быть триггером другого).
41
+ - **Нет зависимостей.** Чистый ES6-класс, экспортируется как ES-модуль.
42
+
43
+ ---
44
+
45
+ ## 2. Модель: триггеры и цели
46
+
47
+ ```
48
+ new Toggle({ trigger: '[trigger]', target: null })
49
+ │
50
+ ├── trigger #1 ──► targets: [ ... ] (из атрибута target="" или params.target)
51
+ ├── trigger #2 ──► targets: [ ... ]
52
+ └── trigger #N ──► targets: [ ... ]
53
+ ```
54
+
55
+ - **Триггеры** ищутся при создании по `params.trigger` (по умолчанию `[trigger]`). На каждый
56
+ вешается обработчик события `params.action`. Появившиеся позже подхватывает `refresh()`.
57
+ - **Цели** разрешаются **при каждом переключении** (а не один раз) — см. раздел
58
+ [8](#8-разрешение-целей-target). У одного триггера может быть несколько целей.
59
+ - Каждый триггер хранит ссылку на экземпляр через приватный Symbol — доступно через
60
+ `Toggle.find()`.
61
+
62
+ ---
63
+
64
+ ## 3. Машина состояний
65
+
66
+ Атрибут `state` (на триггере и на каждой цели) проходит цикл:
67
+
68
+ ```
69
+ activate on_activate / on_activated
70
+ inactive ──────────────► activating ──────────────────────────────► active
71
+ ▲ │
72
+ │ on_deactivate / deactivate │
73
+ └──── on_deactivated ◄──── deactivating ◄───────────────────────────┘
74
+ ```
75
+
76
+ | Состояние | Описание |
77
+ |---|---|
78
+ | `inactive` | Выключено (конечное состояние после деактивации) |
79
+ | `activating` | Идёт анимация включения (прошёл один `requestAnimationFrame`) |
80
+ | `active` | Анимация завершена, включено |
81
+ | `deactivating` | Идёт анимация выключения |
82
+
83
+ ### Как происходит переход (внутренняя механика)
84
+
85
+ Мирроринг механики `Modal`:
86
+
87
+ 1. Решается направление (для `toggle()` — по текущему состоянию триггера).
88
+ 2. Вызывается хук `before_*` (на старте).
89
+ 3. Первый `requestAnimationFrame` ставит промежуточное состояние
90
+ (`activating` / `deactivating`) — это запускает CSS-переход.
91
+ 4. Второй `requestAnimationFrame` запускает `setTimeout(duration * 1000)`.
92
+ 5. По окончании таймаута ставится финальное состояние (`active` / `inactive`) и
93
+ вызывается хук `on_*`.
94
+
95
+ Триггер и его цели переводятся **отдельными** проходами (независимые жизненные циклы), но в
96
+ рамках одного прохода состояния всех целей меняются «пачкой» в одном `requestAnimationFrame` —
97
+ это снижает нагрузку при большом числе целей. Таймер хранится **per-element**, поэтому повторное
98
+ переключение прерывает ожидающий финал только нужных элементов.
99
+
100
+ ### allow_interrupt
101
+
102
+ По умолчанию (`allow_interrupt: false`) переключение, вызванное во время обратной анимации,
103
+ игнорируется: `activate` работает только из `inactive`, `deactivate` — только из `active`.
104
+
105
+ При `allow_interrupt: true` разрешается прервать текущий переход и стартовать обратный
106
+ (`activate` из `deactivating`, `deactivate` из `activating`) — для плавного реверса.
107
+
108
+ ---
109
+
110
+ ## 4. Параметры конструктора
111
+
112
+ ```js
113
+ new Toggle(params)
114
+ ```
115
+
116
+ Все параметры необязательны.
117
+
118
+ | Параметр | Тип | По умолчанию | Описание |
119
+ |---|---|---|---|
120
+ | `trigger` | `string \| function \| Element \| NodeList \| Array` | `'[trigger]'` | Что считать триггерами. Селектор или функция, возвращающая элементы, резолвится при создании и заново в `refresh()`. Готовый список элементов `refresh()` не пересчитывает. |
121
+ | `target` | `string \| function \| Element \| NodeList \| Array \| null` | `null` | Цели триггера. Если функция — вызывается как `target(trigger)` при каждом переключении. Если `null` — берётся из атрибута `target=""` триггера. См. раздел [8](#8-разрешение-целей-target). |
122
+ | `action` | `string` | `'click'` | Имя DOM-события на триггере. Спец-значение `'hover'` → `mouseenter` включает, `mouseleave` выключает. |
123
+ | `duration` | `number` | `0` | Длительность перехода в секундах (= время до установки финального состояния и вызова `on_*`). CSS-`transition` задаётся разработчиком. |
124
+ | `allow_interrupt` | `boolean` | `false` | Разрешить прерывание текущего перехода обратным. |
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
+ | `group` | `false \| true \| 'radio'` | `false` | Взаимоисключение триггеров **одного экземпляра**. `true` — аккордеон: при активации триггера остальные активные триггеры экземпляра деактивируются (ещё не доигравший `activating` — только при `allow_interrupt: true`), их хуки `before_/on_deactivate(d)` срабатывают как обычно; повторный клик закрывает открытый. `'radio'` — табы: то же, но `toggle()` (и клик) по активному триггеру ничего не делает, и один таб всегда остаётся открытым. Явный `deactivate()` работает в обоих режимах. |
128
+ | `indicator` | `string \| Element \| function \| null` | `null` | Элемент, который следует за активным триггером (пилюля, подчёркивание табов). Функция вызывается как `indicator(toggle)` один раз при создании. Индикатор получает CSS-переменные `--indicator-x/-y/-width/-height` и `state="active" \| "inactive"`. `clone()` копирует его вместе с остальными параметрами - для другой ленты переопределяйте `indicator` вместе с `trigger`. См. раздел [13](#13-индикатор-и-прокрутка-табов). |
129
+ | `reveal` | `boolean` | `false` | Доводить ли активируемый кликом или из кода триггер до полной видимости в горизонтальной ленте с прокруткой. При переходе по якорю и для стартового активного триггера доводка идёт всегда; при `action: 'hover'` по клику - никогда. См. раздел [13](#13-индикатор-и-прокрутка-табов). |
130
+
131
+ > **Имена атрибутов фиксированы:** триггеры по умолчанию `[trigger]`, цель — атрибут `target=""`,
132
+ > состояние — атрибут `state=""`.
133
+
134
+ ---
135
+
136
+ ## 5. Хуки жизненного цикла
137
+
138
+ Хуки делятся на **события триггера** и **события целей** — они независимы.
139
+
140
+ ### События триггера — вызываются 1 раз, аргументы `(trigger, targets)`
141
+
142
+ | Хук | Когда | `targets` |
143
+ |---|---|---|
144
+ | `before_activate` | на старте включения | массив целей |
145
+ | `on_activate` | после `duration` (включено) | массив целей |
146
+ | `before_deactivate` | на старте выключения | массив целей |
147
+ | `on_deactivate` | после `duration` (выключено) | массив целей |
148
+
149
+ ### События целей — вызываются **для каждой цели**, аргументы `(target, trigger)`
150
+
151
+ | Хук | Когда |
152
+ |---|---|
153
+ | `before_activated` | на старте включения цели |
154
+ | `on_activated` | после `duration` (цель включена) |
155
+ | `before_deactivated` | на старте выключения цели |
156
+ | `on_deactivated` | после `duration` (цель выключена) |
157
+
158
+ ### Инициализация
159
+
160
+ | Хук | Когда |
161
+ |---|---|
162
+ | `before_init` | до поиска триггеров и навешивания обработчиков; получает `params` |
163
+ | `on_init` | после полной инициализации; получает `params` |
164
+
165
+ ### Привязка контекста
166
+
167
+ Все хуки (кроме `target`-функции) привязываются к экземпляру через `.bind(this)` — внутри хука
168
+ `this` указывает на экземпляр `Toggle`.
169
+
170
+ ---
171
+
172
+ ## 6. Публичные свойства и методы
173
+
174
+ ### Геттеры
175
+
176
+ | Член | Возвращает | Описание |
177
+ |---|---|---|
178
+ | `params` | `object` | Параметры экземпляра (без функций-хуков) |
179
+
180
+ > Текущее состояние читается прямо из DOM: `el.getAttribute('state')` — отдельного метода нет.
181
+
182
+ ### Методы
183
+
184
+ Все три принимают `Element`, `NodeList`, `Array` **или** CSS-селектор; применяются к каждому
185
+ совпавшему элементу.
186
+
187
+ #### `toggle(el)`
188
+
189
+ Переключает направление по текущему состоянию триггера: из `active`/`activating` → деактивирует,
190
+ иначе активирует. Это обработчик, навешиваемый по умолчанию.
191
+
192
+ #### `activate(el)`
193
+
194
+ Принудительно включает (с учётом guard'а состояния и `allow_interrupt`).
195
+
196
+ #### `deactivate(el)`
197
+
198
+ Принудительно выключает (с учётом guard'а состояния и `allow_interrupt`).
199
+
200
+ ```js
201
+ tg.toggle('#item');
202
+ tg.activate(document.querySelector('[trigger]'));
203
+ tg.deactivate('#accordion [trigger]'); // на все совпадения
204
+ ```
205
+
206
+ #### `clone(params)`
207
+
208
+ Создаёт новый экземпляр `Toggle` на основе текущего: параметры и хуки исходного экземпляра берутся
209
+ за основу, переданный `params` их переопределяет, а в новый экземпляр добавляется ссылка на
210
+ оригинал через параметр `parent`.
211
+
212
+ В отличие от `Modal.clone()`, DOM не клонируется — `Toggle` не владеет собственными элементами,
213
+ поэтому обычно при клонировании переопределяют `trigger` (и при необходимости `target`), чтобы
214
+ тот же конфиг применить к другим элементам без повторной привязки к исходным.
215
+
216
+ ```js
217
+ const base = new Toggle({ duration: 0.3, on_activate() { /* … */ } });
218
+
219
+ // та же логика, но на другом наборе триггеров
220
+ const copy = base.clone({ trigger: '#sidebar [trigger]' });
221
+ ```
222
+
223
+ #### `destroy()`
224
+
225
+ Разбирает экземпляр: снимает обработчики триггеров и `hashchange` на `window` (`keep_history`), слежение за индикатором (`ResizeObserver`, прокрутка), таймеры переходов и методы `toggle`/`activate`/`deactivate` с триггеров. `state` на триггерах и целях остаётся как есть. Нужен, когда группа живёт меньше страницы - компонент SPA, который уходит со сменой маршрута: без `destroy()` слушатель `hashchange` каждого экземпляра остаётся на `window`.
226
+
227
+ ```js
228
+ const tabs = new Toggle({ trigger: '#tabs [trigger]', group: 'radio', anchor: true, keep_history: true });
229
+ // компонент снимается
230
+ tabs.destroy();
231
+ ```
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
+
247
+ ---
248
+
249
+ ## 7. Статические методы
250
+
251
+ ### `Toggle.find(element | selector)`
252
+
253
+ Возвращает экземпляр `Toggle`, связанный с переданным **триггером** (или `undefined`).
254
+
255
+ ```js
256
+ const instance = Toggle.find(document.querySelector('[trigger]'));
257
+ instance?.deactivate(someTrigger);
258
+ ```
259
+
260
+ ---
261
+
262
+ ## 8. Разрешение целей (target)
263
+
264
+ Цели триггера определяются при **каждом** переключении в таком порядке:
265
+
266
+ 1. `params.target` — если задан:
267
+ - **функция** → вызывается как `target(trigger)`; может вернуть селектор, `Element`,
268
+ `NodeList` или массив;
269
+ - **селектор / Element / NodeList / Array** → используется как есть.
270
+ 2. Иначе — атрибут `target=""` самого триггера (CSS-селектор).
271
+ 3. Если ничего не найдено — целей нет, триггер переключает только себя.
272
+
273
+ Результат приводится к массиву элементов хелпером `elements()` из трейта (без побочных эффектов:
274
+ несовпавший селектор → пустой список).
275
+
276
+ ```html
277
+ <div trigger target="#panel">Кнопка</div>
278
+ <div id="panel" content>…</div>
279
+ ```
280
+
281
+ ```js
282
+ // Цель как замыкание (например, относительно триггера):
283
+ new Toggle({ target: trigger => trigger.parentElement.querySelector('.drop') });
284
+ ```
285
+
286
+ ---
287
+
288
+ ## 9. CSS-анимация через атрибут state
289
+
290
+ Единственный механизм визуала — CSS по атрибуту `[state]`. Класс не задаёт `transition`
291
+ самостоятельно — это делает разработчик.
292
+
293
+ ```css
294
+ /* Спойлер: видим в active/activating, скрыт в inactive/deactivating */
295
+ [content] { overflow: hidden; transition: height .3s, opacity .3s; }
296
+
297
+ [content][state="inactive"],
298
+ [content][state="deactivating"] { opacity: 0; height: 0; }
299
+
300
+ [content][state="active"],
301
+ [content][state="activating"] { opacity: 1; }
302
+ ```
303
+
304
+ > **Совет:** разделяя `activating`/`deactivating`, можно задать разные анимации входа и выхода.
305
+
306
+ ---
307
+
308
+ ## 10. Примеры
309
+
310
+ ### Спойлер по атрибуту `target`
311
+
312
+ ```html
313
+ <button trigger target="#more">Подробнее</button>
314
+ <div id="more" content>Скрытый текст…</div>
315
+ ```
316
+
317
+ ```js
318
+ import Toggle from './toggle.js';
319
+ new Toggle({ duration: 0.3 }); // trigger по умолчанию '[trigger]'
320
+ ```
321
+
322
+ ### Аккордеон (`group: true`)
323
+
324
+ ```js
325
+ new Toggle({
326
+ duration: 0.3,
327
+ trigger: '#accordion [trigger]',
328
+ group: true, // открытие секции закрывает остальные, повторный клик закрывает текущую
329
+ });
330
+ ```
331
+
332
+ ### Табы (`group: 'radio'`)
333
+
334
+ ```html
335
+ <nav>
336
+ <button trigger target="#tab-1" state="active">Первый</button>
337
+ <button trigger target="#tab-2">Второй</button>
338
+ </nav>
339
+ <section id="tab-1" state="active">…</section>
340
+ <section id="tab-2">…</section>
341
+ ```
342
+
343
+ ```js
344
+ new Toggle({
345
+ trigger: 'nav [trigger]',
346
+ group: 'radio', // клик по активному табу его не выключает
347
+ anchor: true, // по желанию: активный таб в hash
348
+ });
349
+ ```
350
+
351
+ Стартовый таб задаётся атрибутом `state="active"` на триггере и его цели - `Toggle` не
352
+ перезаписывает уже проставленный `state`.
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
+
368
+ ### Кнопка-переключатель (без целей)
369
+
370
+ ```js
371
+ new Toggle({
372
+ trigger: '.switch',
373
+ target: null, // переключает только сам триггер
374
+ duration: 0.25,
375
+ on_activate: () => console.log('on'),
376
+ on_deactivate: () => console.log('off'),
377
+ });
378
+ ```
379
+
380
+ ### Hover-меню (target как замыкание)
381
+
382
+ В режиме `'hover'` вешайте триггер на **обёртку**, которая DOM-содержит и подпись, и выпадающий
383
+ список — тогда наведение на пункты считается «внутри» (`mouseleave` не срабатывает при переходе
384
+ на потомка). Триггер на саму подпись закроет меню при наведении на пункты. См. раздел [11](#11-известные-особенности-и-ограничения).
385
+
386
+ ```html
387
+ <div class="menu" trigger>
388
+ <div class="menu-trigger">Меню ▾</div>
389
+ <div class="menu-drop"><!-- пункты --></div>
390
+ </div>
391
+ ```
392
+
393
+ ```js
394
+ new Toggle({
395
+ action: 'hover',
396
+ duration: 0.2,
397
+ trigger: '.menu',
398
+ target: trigger => trigger.querySelector('.menu-drop'),
399
+ });
400
+ ```
401
+
402
+ > **Зазор закрывает меню.** Не оставляйте пустого промежутка между подписью и выпадашкой
403
+ > (`margin-top` и т.п.) — курсор пройдёт по «дыре» над `body`, сработает `mouseleave`, и меню
404
+ > закроется. Используйте смежные элементы (`top: 100%` без отступа) или соедините их `padding`.
405
+
406
+ ### Программное управление и `find`
407
+
408
+ ```js
409
+ const tg = new Toggle({ trigger: '[trigger]' });
410
+
411
+ tg.activate('#item');
412
+ console.log(document.querySelector('#item').getAttribute('state')); // 'activating' → позже 'active'
413
+
414
+ const inst = Toggle.find(document.querySelector('[trigger]'));
415
+ inst.toggle(someTrigger);
416
+ ```
417
+
418
+ ---
419
+
420
+ ## 11. Известные особенности и ограничения
421
+
422
+ ### Новые триггеры - через `refresh()`
423
+
424
+ `params.trigger` резолвится в конструкторе. Элементы, добавленные в DOM позже, `Toggle` сам не
425
+ замечает: вызовите `refresh()` после перерисовки (в `<st-app>` - в событии `updated`). Передавайте
426
+ триггеры селектором или функцией: готовый список элементов `refresh()` не пересчитывает.
427
+
428
+ ### Цели разрешаются при каждом переключении
429
+
430
+ В отличие от триггеров, цели вычисляются на каждый вызов — это позволяет `target`-замыканию
431
+ учитывать текущий DOM и работать с динамическими элементами.
432
+
433
+ ### Группа — это один экземпляр
434
+
435
+ `group` действует на триггеры одного `Toggle`. Две независимые группы табов на странице - два
436
+ экземпляра с разными селекторами `trigger`. Триггеры, добавленные в DOM позже, попадают в группу
437
+ после `refresh()` (см. выше).
438
+
439
+ ### Состояния триггера и целей независимы
440
+
441
+ Один target, управляемый несколькими триггерами, может рассинхронизироваться с их состояниями —
442
+ это сделано намеренно (для комбинирования цепочек toggle-ров).
443
+
444
+ ### hover: учитываются DOM-потомки триггера, а не геометрия
445
+
446
+ `action: 'hover'` использует `mouseenter`/`mouseleave`. Они **не** срабатывают при переходе курсора
447
+ на DOM-потомка триггера (даже если тот спозиционирован вне его рамки). Поэтому для hover-меню вешайте
448
+ триггер на обёртку, содержащую и подпись, и выпадашку, и не оставляйте между ними геометрического
449
+ зазора (см. пример выше). Если цель — *сосед* триггера, наведение на неё закроет меню.
450
+
451
+ ### Класс не управляет display
452
+
453
+ После выключения цель остаётся в DOM со `state="inactive"`. Если нужно `display: none` —
454
+ задайте это в CSS через `[state="inactive"]`.
455
+
456
+ ---
457
+
458
+ ## 12. Якорные ссылки (deep-linking)
459
+
460
+ При `anchor` активный триггер синхронизируется с хешем адресной строки: активация
461
+ дописывает `#id`, открытие страницы с `#id` сразу активирует соответствующий триггер. По умолчанию
462
+ `anchor` выключен (`false`); `keep_history: true` включает его, если он не задан.
463
+
464
+ ### Какой id попадает в URL
465
+
466
+ `anchor: true` или `'trigger'` - приоритет у триггера:
467
+
468
+ 1. если у **самого триггера** есть `id` - пишется он;
469
+ 2. иначе, если у триггера ровно **одна** цель и у неё есть `id` - пишется `id` цели;
470
+ 3. иначе - триггер в URL не отражается.
471
+
472
+ `anchor: 'target'` - приоритет у панели: сначала `id` единственной цели, затем `id` триггера.
473
+ Ссылку на раздел естественнее давать на панель (`#core-keys`), а не на кнопку вкладки
474
+ (`#core-keys-tab`).
475
+
476
+ Триггеры без подходящего `id` (например, hover-меню без `id` у дропдауна) ничего не пишут в URL.
477
+
478
+ ```html
479
+ <!-- id у цели → в URL попадёт #a2 -->
480
+ <div trigger target="#a2">Раздел 2</div>
481
+ <div id="a2" content>…</div>
482
+
483
+ <!-- id у самого триггера → в URL попадёт #theme-switch -->
484
+ <div class="switch" trigger id="theme-switch"></div>
485
+ ```
486
+
487
+ ### Поведение кнопки «назад» (`keep_history`)
488
+
489
+ URL всегда обновляется через `history.*` (никогда через `location.hash`) — поэтому **прокрутки к
490
+ элементу не происходит**, а история не засоряется при `keep_history: false`.
491
+
492
+ | `keep_history` | Метод | Кнопка «назад» |
493
+ |---|---|---|
494
+ | `false` (по умолчанию) | `replaceState` | уходит со страницы, переключения табов игнорируются |
495
+ | `true` | `pushState` + `hashchange` | возвращает предыдущий таб; пустой хеш закрывает текущий |
496
+
497
+ ```js
498
+ // Табы с навигацией «назад/вперёд» между ними
499
+ new Toggle({ trigger: '#tabs [trigger]', keep_history: true });
500
+ ```
501
+
502
+ ### Прокрутка к элементу
503
+
504
+ Страницу `Toggle` не прокручивает. Если нужна прокрутка к элементу - сделайте триггер настоящей
505
+ ссылкой `<a href="#id">`: браузер сам проскроллит к нему (это нативное поведение, независимое от
506
+ `Toggle`). Если прокрутка не нужна - используйте любой не-`<a>` элемент.
507
+
508
+ Ленту табов с горизонтальной прокруткой `Toggle` доводит до таба из хеша сам, всегда - см.
509
+ раздел [13](#13-индикатор-и-прокрутка-табов).
510
+
511
+ ### Отключение
512
+
513
+ `anchor: false` полностью выключает работу с URL - поведение как до появления фичи.
514
+
515
+ ---
516
+
517
+ ## 13. Индикатор и прокрутка табов
518
+
519
+ ### Индикатор (`indicator`)
520
+
521
+ Элемент, который следует за активным триггером: пилюля под табом, подчёркивание. Визуал и
522
+ анимация - в CSS проекта; `Toggle` пишет индикатору координаты активного триггера:
523
+
524
+ | Переменная | Значение |
525
+ |---|---|
526
+ | `--indicator-x`, `--indicator-y` | Смещение триггера от `offsetParent` индикатора, с учётом его прокрутки и рамки, `px` |
527
+ | `--indicator-width`, `--indicator-height` | Размер триггера, `px` |
528
+
529
+ и атрибут `state`: `active` - есть за кем следовать, `inactive` - активных триггеров нет
530
+ (`group: true` после закрытия последнего, или без группы). При `inactive` координаты остаются
531
+ прежними - индикатор можно погасить на месте.
532
+
533
+ ```html
534
+ <nav class="tabs">
535
+ <button trigger target="#tab-1" state="active">Первый</button>
536
+ <button trigger target="#tab-2">Второй</button>
537
+ <button trigger target="#tab-3">Третий</button>
538
+ <i class="tabs__pill"></i>
539
+ </nav>
540
+ ```
541
+
542
+ ```css
543
+ .tabs { position: relative; display: flex; overflow-x: auto; }
544
+ .tabs__pill {
545
+ position: absolute; left: 0; top: 0;
546
+ width: var(--indicator-width); height: var(--indicator-height);
547
+ transform: translateX(var(--indicator-x));
548
+ transition: transform .3s, width .3s, opacity .3s;
549
+ }
550
+ .tabs__pill[state="inactive"] { opacity: 0; }
551
+ ```
552
+
553
+ ```js
554
+ new Toggle({ trigger: '.tabs [trigger]', group: 'radio', indicator: '.tabs__pill', reveal: true });
555
+ ```
556
+
557
+ **Разметка.** Индикатор кладите **внутрь** прокручиваемой ленты, у ленты - `position: relative`.
558
+ Тогда индикатор прокручивается вместе с табами и при прокрутке не пересчитывается. Индикатор вне
559
+ ленты тоже работает: `Toggle` пересчитывает его на каждом кадре прокрутки.
560
+
561
+ **Когда индикатор анимируется.** Переезд на другой триггер идёт по `transition` из CSS - в момент
562
+ начала активации, вместе с `activating`. Всё остальное индикатор делает **мгновенно**, на время
563
+ записи выключая `transition` в inline-стиле:
564
+
565
+ - первая расстановка при создании - индикатор не "выезжает" из нуля;
566
+ - появление после `state="inactive"` - встаёт на место, а не едет от прежнего;
567
+ - изменение размеров (`ResizeObserver` на триггерах и родителе индикатора): ресайз окна, подгрузка
568
+ шрифта, показ скрытой панели или модалки с табами;
569
+ - прокрутка ленты, если индикатор стоит вне её.
570
+
571
+ За каким триггером следует: за тем, чья активация началась последней. Выключили его (без группы
572
+ или `group: true`) - индикатор переходит к оставшемуся активному, если такой есть.
573
+
574
+ ### Доводка таба до видимости
575
+
576
+ Если триггер лежит в горизонтальной ленте с прокруткой (`overflow-x: auto | scroll`) и виден в ней
577
+ не целиком, лента прокручивается так, чтобы он был виден целиком.
578
+
579
+ | Активация | Доводка |
580
+ |---|---|
581
+ | Переход по якорю: хеш при загрузке, `hashchange` при `keep_history` | всегда |
582
+ | Стартовый активный триггер (`state="active"` в разметке) | всегда |
583
+ | Клик, `activate()` / `toggle()` из кода | при `reveal: true` |
584
+ | Наведение (`action: 'hover'`) | никогда - меню прокрутилось бы под курсором |
585
+
586
+ Таб из ссылки или из разметки выбрал не пользователь, и он может стоять за краем ленты, поэтому
587
+ здесь доводка обязательна. Кликнутый таб пользователь видит хотя бы частично - довести его до
588
+ полной видимости или нет, решает проект флагом `reveal`.
589
+
590
+ Что учтено:
591
+
592
+ - прокручивается **только ближайшая** горизонтальная лента - ни страница, ни внешние области с
593
+ прокруткой, ни вертикаль не двигаются;
594
+ - `scroll-padding-inline` ленты: таб не уходит под липкие стрелки или градиент на краю;
595
+ - `scroll-snap`: лента прокручивается к точке прилипания, в которой таб виден целиком, - иначе
596
+ браузер "прилепил" бы её к ближайшей точке, и таб снова ушёл бы за край;
597
+ - `scroll-behavior: smooth` из CSS ленты работает; быстрые клики подряд не накапливают прокрутку -
598
+ лента приходит к последнему табу. Доводка при загрузке страницы и при показе скрытых табов -
599
+ мгновенная;
600
+ - RTL (`dir="rtl"`) - доводка и индикатор работают зеркально;
601
+ - табы скрыты (закрытая модалка, свёрнутая панель) - доводка откладывается до показа;
602
+ - таб, видимый целиком, ленту не двигает: ни после ручной прокрутки, ни при фокусе с клавиатуры
603
+ (браузер уже прокрутил ленту к фокусу, второго рывка нет);
604
+ - таб шире ленты выравнивается по начальному краю.
@@ -0,0 +1,9 @@
1
+ <!-- DOCGEN:START -->
2
+ # typograf
3
+
4
+ ## Файлы
5
+
6
+ - [_engine.js](_engine.js.md)
7
+ - [index.js](index.js.md)
8
+
9
+ <!-- DOCGEN:END -->