@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.
- package/README.md +1 -1
- package/dist/shape.esm.min.js +2 -0
- package/dist/{cut.esm.min.js.map → shape.esm.min.js.map} +4 -4
- package/dist/shape.min.js +2 -0
- package/dist/shape.min.js.map +7 -0
- package/docs/README.md +36 -0
- package/docs/src/README.md +29 -0
- package/docs/src/_traits/README.md +8 -0
- package/docs/src/_traits/hasInstanceSymbol.js.md +57 -0
- package/docs/src/app/README.md +13 -0
- package/docs/src/app/datepicker/README.md +9 -0
- package/docs/src/app/datepicker/_calendar.js.md +1 -0
- package/docs/src/app/datepicker/index.js.md +153 -0
- package/docs/src/app/form/README.md +8 -0
- package/docs/src/app/form/index.js.md +560 -0
- package/docs/src/app/index.js.md +1302 -0
- package/docs/src/cookie/README.md +8 -0
- package/docs/src/cookie/index.js.md +80 -0
- package/docs/src/core/README.md +8 -0
- package/docs/src/core/index.js.md +178 -0
- package/docs/src/index.js.md +1 -0
- package/docs/src/loader/README.md +8 -0
- package/docs/src/loader/index.js.md +125 -0
- package/docs/src/mask/README.md +10 -0
- package/docs/src/mask/_engine.js.md +1 -0
- package/docs/src/mask/_groups.js.md +1 -0
- package/docs/src/mask/index.js.md +411 -0
- package/docs/src/modal/README.md +8 -0
- package/docs/src/modal/index.js.md +809 -0
- package/docs/src/observer/README.md +9 -0
- package/docs/src/observer/_engine.js.md +28 -0
- package/docs/src/observer/index.js.md +259 -0
- package/docs/src/route/README.md +8 -0
- package/docs/src/route/index.js.md +385 -0
- package/docs/src/select/README.md +8 -0
- package/docs/src/select/index.js.md +115 -0
- package/docs/src/shape/README.md +9 -0
- package/docs/src/shape/_engine.js.md +1 -0
- package/docs/src/shape/index.js.md +98 -0
- package/docs/src/st_button_widget/README.md +9 -0
- package/docs/src/st_button_widget/README.txt.md +4 -0
- package/docs/src/st_button_widget/index.js.md +68 -0
- package/docs/src/st_links_widget/README.md +9 -0
- package/docs/src/st_links_widget/README.txt.md +4 -0
- package/docs/src/st_links_widget/index.js.md +46 -0
- package/docs/src/st_widget/README.md +8 -0
- package/docs/src/st_widget/button/README.md +4 -0
- package/docs/src/toggle/README.md +8 -0
- package/docs/src/toggle/index.js.md +572 -0
- package/docs/src/typograf/README.md +9 -0
- package/docs/src/typograf/_engine.js.md +75 -0
- package/docs/src/typograf/index.js.md +165 -0
- package/docs/src/uploader/README.md +8 -0
- package/docs/src/uploader/index.js.md +112 -0
- package/docs/src/validator/README.md +8 -0
- package/docs/src/validator/index.js.md +113 -0
- package/package.json +3 -2
- package/src/index.js +1 -1
- package/src/{cut → shape}/_engine.js +1 -1
- package/src/{cut → shape}/index.js +10 -10
- package/dist/cut.esm.min.js +0 -2
- package/dist/cut.min.js +0 -2
- package/dist/cut.min.js.map +0 -7
|
@@ -0,0 +1,572 @@
|
|
|
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` (по умолчанию
|
|
56
|
+
`[trigger]`). На каждый вешается обработчик события `params.action`.
|
|
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 \| Element \| NodeList \| Array` | `'[trigger]'` | Что считать триггерами. Селектор резолвится через `querySelectorAll` один раз при создании. |
|
|
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` | `boolean` | `false` | Синхронизировать активный триггер с хешем URL (deep-linking). См. раздел [12](#12-якорные-ссылки-deep-linking). |
|
|
126
|
+
| `keep_history` | `boolean` | `false` | Создавать ли запись в истории на каждое переключение. `false` → `replaceState` (кнопка «назад» уходит со страницы); `true` → `pushState` + реакция на `hashchange` (кнопка «назад» возвращает предыдущий таб). **Принудительно включает `anchor: true`** (без якоря история хеша бессмысленна). |
|
|
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
|
+
---
|
|
234
|
+
|
|
235
|
+
## 7. Статические методы
|
|
236
|
+
|
|
237
|
+
### `Toggle.find(element | selector)`
|
|
238
|
+
|
|
239
|
+
Возвращает экземпляр `Toggle`, связанный с переданным **триггером** (или `undefined`).
|
|
240
|
+
|
|
241
|
+
```js
|
|
242
|
+
const instance = Toggle.find(document.querySelector('[trigger]'));
|
|
243
|
+
instance?.deactivate(someTrigger);
|
|
244
|
+
```
|
|
245
|
+
|
|
246
|
+
---
|
|
247
|
+
|
|
248
|
+
## 8. Разрешение целей (target)
|
|
249
|
+
|
|
250
|
+
Цели триггера определяются при **каждом** переключении в таком порядке:
|
|
251
|
+
|
|
252
|
+
1. `params.target` — если задан:
|
|
253
|
+
- **функция** → вызывается как `target(trigger)`; может вернуть селектор, `Element`,
|
|
254
|
+
`NodeList` или массив;
|
|
255
|
+
- **селектор / Element / NodeList / Array** → используется как есть.
|
|
256
|
+
2. Иначе — атрибут `target=""` самого триггера (CSS-селектор).
|
|
257
|
+
3. Если ничего не найдено — целей нет, триггер переключает только себя.
|
|
258
|
+
|
|
259
|
+
Результат приводится к массиву элементов хелпером `elements()` из трейта (без побочных эффектов:
|
|
260
|
+
несовпавший селектор → пустой список).
|
|
261
|
+
|
|
262
|
+
```html
|
|
263
|
+
<div trigger target="#panel">Кнопка</div>
|
|
264
|
+
<div id="panel" content>…</div>
|
|
265
|
+
```
|
|
266
|
+
|
|
267
|
+
```js
|
|
268
|
+
// Цель как замыкание (например, относительно триггера):
|
|
269
|
+
new Toggle({ target: trigger => trigger.parentElement.querySelector('.drop') });
|
|
270
|
+
```
|
|
271
|
+
|
|
272
|
+
---
|
|
273
|
+
|
|
274
|
+
## 9. CSS-анимация через атрибут state
|
|
275
|
+
|
|
276
|
+
Единственный механизм визуала — CSS по атрибуту `[state]`. Класс не задаёт `transition`
|
|
277
|
+
самостоятельно — это делает разработчик.
|
|
278
|
+
|
|
279
|
+
```css
|
|
280
|
+
/* Спойлер: видим в active/activating, скрыт в inactive/deactivating */
|
|
281
|
+
[content] { overflow: hidden; transition: height .3s, opacity .3s; }
|
|
282
|
+
|
|
283
|
+
[content][state="inactive"],
|
|
284
|
+
[content][state="deactivating"] { opacity: 0; height: 0; }
|
|
285
|
+
|
|
286
|
+
[content][state="active"],
|
|
287
|
+
[content][state="activating"] { opacity: 1; }
|
|
288
|
+
```
|
|
289
|
+
|
|
290
|
+
> **Совет:** разделяя `activating`/`deactivating`, можно задать разные анимации входа и выхода.
|
|
291
|
+
|
|
292
|
+
---
|
|
293
|
+
|
|
294
|
+
## 10. Примеры
|
|
295
|
+
|
|
296
|
+
### Спойлер по атрибуту `target`
|
|
297
|
+
|
|
298
|
+
```html
|
|
299
|
+
<button trigger target="#more">Подробнее</button>
|
|
300
|
+
<div id="more" content>Скрытый текст…</div>
|
|
301
|
+
```
|
|
302
|
+
|
|
303
|
+
```js
|
|
304
|
+
import Toggle from './toggle.js';
|
|
305
|
+
new Toggle({ duration: 0.3 }); // trigger по умолчанию '[trigger]'
|
|
306
|
+
```
|
|
307
|
+
|
|
308
|
+
### Аккордеон (`group: true`)
|
|
309
|
+
|
|
310
|
+
```js
|
|
311
|
+
new Toggle({
|
|
312
|
+
duration: 0.3,
|
|
313
|
+
trigger: '#accordion [trigger]',
|
|
314
|
+
group: true, // открытие секции закрывает остальные, повторный клик закрывает текущую
|
|
315
|
+
});
|
|
316
|
+
```
|
|
317
|
+
|
|
318
|
+
### Табы (`group: 'radio'`)
|
|
319
|
+
|
|
320
|
+
```html
|
|
321
|
+
<nav>
|
|
322
|
+
<button trigger target="#tab-1" state="active">Первый</button>
|
|
323
|
+
<button trigger target="#tab-2">Второй</button>
|
|
324
|
+
</nav>
|
|
325
|
+
<section id="tab-1" state="active">…</section>
|
|
326
|
+
<section id="tab-2">…</section>
|
|
327
|
+
```
|
|
328
|
+
|
|
329
|
+
```js
|
|
330
|
+
new Toggle({
|
|
331
|
+
trigger: 'nav [trigger]',
|
|
332
|
+
group: 'radio', // клик по активному табу его не выключает
|
|
333
|
+
anchor: true, // по желанию: активный таб в hash
|
|
334
|
+
});
|
|
335
|
+
```
|
|
336
|
+
|
|
337
|
+
Стартовый таб задаётся атрибутом `state="active"` на триггере и его цели — `Toggle` не
|
|
338
|
+
перезаписывает уже проставленный `state`.
|
|
339
|
+
|
|
340
|
+
### Кнопка-переключатель (без целей)
|
|
341
|
+
|
|
342
|
+
```js
|
|
343
|
+
new Toggle({
|
|
344
|
+
trigger: '.switch',
|
|
345
|
+
target: null, // переключает только сам триггер
|
|
346
|
+
duration: 0.25,
|
|
347
|
+
on_activate: () => console.log('on'),
|
|
348
|
+
on_deactivate: () => console.log('off'),
|
|
349
|
+
});
|
|
350
|
+
```
|
|
351
|
+
|
|
352
|
+
### Hover-меню (target как замыкание)
|
|
353
|
+
|
|
354
|
+
В режиме `'hover'` вешайте триггер на **обёртку**, которая DOM-содержит и подпись, и выпадающий
|
|
355
|
+
список — тогда наведение на пункты считается «внутри» (`mouseleave` не срабатывает при переходе
|
|
356
|
+
на потомка). Триггер на саму подпись закроет меню при наведении на пункты. См. раздел [11](#11-известные-особенности-и-ограничения).
|
|
357
|
+
|
|
358
|
+
```html
|
|
359
|
+
<div class="menu" trigger>
|
|
360
|
+
<div class="menu-trigger">Меню ▾</div>
|
|
361
|
+
<div class="menu-drop"><!-- пункты --></div>
|
|
362
|
+
</div>
|
|
363
|
+
```
|
|
364
|
+
|
|
365
|
+
```js
|
|
366
|
+
new Toggle({
|
|
367
|
+
action: 'hover',
|
|
368
|
+
duration: 0.2,
|
|
369
|
+
trigger: '.menu',
|
|
370
|
+
target: trigger => trigger.querySelector('.menu-drop'),
|
|
371
|
+
});
|
|
372
|
+
```
|
|
373
|
+
|
|
374
|
+
> **Зазор закрывает меню.** Не оставляйте пустого промежутка между подписью и выпадашкой
|
|
375
|
+
> (`margin-top` и т.п.) — курсор пройдёт по «дыре» над `body`, сработает `mouseleave`, и меню
|
|
376
|
+
> закроется. Используйте смежные элементы (`top: 100%` без отступа) или соедините их `padding`.
|
|
377
|
+
|
|
378
|
+
### Программное управление и `find`
|
|
379
|
+
|
|
380
|
+
```js
|
|
381
|
+
const tg = new Toggle({ trigger: '[trigger]' });
|
|
382
|
+
|
|
383
|
+
tg.activate('#item');
|
|
384
|
+
console.log(document.querySelector('#item').getAttribute('state')); // 'activating' → позже 'active'
|
|
385
|
+
|
|
386
|
+
const inst = Toggle.find(document.querySelector('[trigger]'));
|
|
387
|
+
inst.toggle(someTrigger);
|
|
388
|
+
```
|
|
389
|
+
|
|
390
|
+
---
|
|
391
|
+
|
|
392
|
+
## 11. Известные особенности и ограничения
|
|
393
|
+
|
|
394
|
+
### Триггеры привязываются один раз
|
|
395
|
+
|
|
396
|
+
Селектор `params.trigger` резолвится в конструкторе. Элементы, добавленные в DOM позже,
|
|
397
|
+
обработчик не получают — добавляйте их вручную или используйте делегирование.
|
|
398
|
+
|
|
399
|
+
### Цели разрешаются при каждом переключении
|
|
400
|
+
|
|
401
|
+
В отличие от триггеров, цели вычисляются на каждый вызов — это позволяет `target`-замыканию
|
|
402
|
+
учитывать текущий DOM и работать с динамическими элементами.
|
|
403
|
+
|
|
404
|
+
### Группа — это один экземпляр
|
|
405
|
+
|
|
406
|
+
`group` действует на триггеры одного `Toggle`. Две независимые группы табов на странице — два
|
|
407
|
+
экземпляра с разными селекторами `trigger`. Триггеры, добавленные в DOM позже, в группу не
|
|
408
|
+
попадают (см. выше).
|
|
409
|
+
|
|
410
|
+
### Состояния триггера и целей независимы
|
|
411
|
+
|
|
412
|
+
Один target, управляемый несколькими триггерами, может рассинхронизироваться с их состояниями —
|
|
413
|
+
это сделано намеренно (для комбинирования цепочек toggle-ров).
|
|
414
|
+
|
|
415
|
+
### hover: учитываются DOM-потомки триггера, а не геометрия
|
|
416
|
+
|
|
417
|
+
`action: 'hover'` использует `mouseenter`/`mouseleave`. Они **не** срабатывают при переходе курсора
|
|
418
|
+
на DOM-потомка триггера (даже если тот спозиционирован вне его рамки). Поэтому для hover-меню вешайте
|
|
419
|
+
триггер на обёртку, содержащую и подпись, и выпадашку, и не оставляйте между ними геометрического
|
|
420
|
+
зазора (см. пример выше). Если цель — *сосед* триггера, наведение на неё закроет меню.
|
|
421
|
+
|
|
422
|
+
### Класс не управляет display
|
|
423
|
+
|
|
424
|
+
После выключения цель остаётся в DOM со `state="inactive"`. Если нужно `display: none` —
|
|
425
|
+
задайте это в CSS через `[state="inactive"]`.
|
|
426
|
+
|
|
427
|
+
---
|
|
428
|
+
|
|
429
|
+
## 12. Якорные ссылки (deep-linking)
|
|
430
|
+
|
|
431
|
+
При `anchor: true` активный триггер синхронизируется с хешем адресной строки: активация
|
|
432
|
+
дописывает `#id`, открытие страницы с `#id` сразу активирует соответствующий триггер. По умолчанию
|
|
433
|
+
`anchor` выключен (`false`); `keep_history: true` включает его принудительно.
|
|
434
|
+
|
|
435
|
+
### Какой id попадает в URL (авто-приоритет)
|
|
436
|
+
|
|
437
|
+
Для каждого триггера id вычисляется так:
|
|
438
|
+
|
|
439
|
+
1. если у **самого триггера** есть `id` — пишется он;
|
|
440
|
+
2. иначе, если у триггера ровно **одна** цель и у неё есть `id` — пишется `id` цели;
|
|
441
|
+
3. иначе — триггер в URL не отражается.
|
|
442
|
+
|
|
443
|
+
При коллизии (есть `id` и у триггера, и у единственной цели) **выигрывает id триггера**. Триггеры
|
|
444
|
+
без подходящего `id` (например, hover-меню без `id` у дропдауна) ничего не пишут в URL.
|
|
445
|
+
|
|
446
|
+
```html
|
|
447
|
+
<!-- id у цели → в URL попадёт #a2 -->
|
|
448
|
+
<div trigger target="#a2">Раздел 2</div>
|
|
449
|
+
<div id="a2" content>…</div>
|
|
450
|
+
|
|
451
|
+
<!-- id у самого триггера → в URL попадёт #theme-switch -->
|
|
452
|
+
<div class="switch" trigger id="theme-switch"></div>
|
|
453
|
+
```
|
|
454
|
+
|
|
455
|
+
### Поведение кнопки «назад» (`keep_history`)
|
|
456
|
+
|
|
457
|
+
URL всегда обновляется через `history.*` (никогда через `location.hash`) — поэтому **прокрутки к
|
|
458
|
+
элементу не происходит**, а история не засоряется при `keep_history: false`.
|
|
459
|
+
|
|
460
|
+
| `keep_history` | Метод | Кнопка «назад» |
|
|
461
|
+
|---|---|---|
|
|
462
|
+
| `false` (по умолчанию) | `replaceState` | уходит со страницы, переключения табов игнорируются |
|
|
463
|
+
| `true` | `pushState` + `hashchange` | возвращает предыдущий таб; пустой хеш закрывает текущий |
|
|
464
|
+
|
|
465
|
+
```js
|
|
466
|
+
// Табы с навигацией «назад/вперёд» между ними
|
|
467
|
+
new Toggle({ trigger: '#tabs [trigger]', keep_history: true });
|
|
468
|
+
```
|
|
469
|
+
|
|
470
|
+
### Прокрутка к элементу
|
|
471
|
+
|
|
472
|
+
Страницу `Toggle` не прокручивает. Если нужна прокрутка к элементу - сделайте триггер настоящей
|
|
473
|
+
ссылкой `<a href="#id">`: браузер сам проскроллит к нему (это нативное поведение, независимое от
|
|
474
|
+
`Toggle`). Если прокрутка не нужна - используйте любой не-`<a>` элемент.
|
|
475
|
+
|
|
476
|
+
Ленту табов с горизонтальной прокруткой `Toggle` доводит до таба из хеша сам, всегда - см.
|
|
477
|
+
раздел [13](#13-индикатор-и-прокрутка-табов).
|
|
478
|
+
|
|
479
|
+
### Отключение
|
|
480
|
+
|
|
481
|
+
`anchor: false` полностью выключает работу с URL - поведение как до появления фичи.
|
|
482
|
+
|
|
483
|
+
---
|
|
484
|
+
|
|
485
|
+
## 13. Индикатор и прокрутка табов
|
|
486
|
+
|
|
487
|
+
### Индикатор (`indicator`)
|
|
488
|
+
|
|
489
|
+
Элемент, который следует за активным триггером: пилюля под табом, подчёркивание. Визуал и
|
|
490
|
+
анимация - в CSS проекта; `Toggle` пишет индикатору координаты активного триггера:
|
|
491
|
+
|
|
492
|
+
| Переменная | Значение |
|
|
493
|
+
|---|---|
|
|
494
|
+
| `--indicator-x`, `--indicator-y` | Смещение триггера от `offsetParent` индикатора, с учётом его прокрутки и рамки, `px` |
|
|
495
|
+
| `--indicator-width`, `--indicator-height` | Размер триггера, `px` |
|
|
496
|
+
|
|
497
|
+
и атрибут `state`: `active` - есть за кем следовать, `inactive` - активных триггеров нет
|
|
498
|
+
(`group: true` после закрытия последнего, или без группы). При `inactive` координаты остаются
|
|
499
|
+
прежними - индикатор можно погасить на месте.
|
|
500
|
+
|
|
501
|
+
```html
|
|
502
|
+
<nav class="tabs">
|
|
503
|
+
<button trigger target="#tab-1" state="active">Первый</button>
|
|
504
|
+
<button trigger target="#tab-2">Второй</button>
|
|
505
|
+
<button trigger target="#tab-3">Третий</button>
|
|
506
|
+
<i class="tabs__pill"></i>
|
|
507
|
+
</nav>
|
|
508
|
+
```
|
|
509
|
+
|
|
510
|
+
```css
|
|
511
|
+
.tabs { position: relative; display: flex; overflow-x: auto; }
|
|
512
|
+
.tabs__pill {
|
|
513
|
+
position: absolute; left: 0; top: 0;
|
|
514
|
+
width: var(--indicator-width); height: var(--indicator-height);
|
|
515
|
+
transform: translateX(var(--indicator-x));
|
|
516
|
+
transition: transform .3s, width .3s, opacity .3s;
|
|
517
|
+
}
|
|
518
|
+
.tabs__pill[state="inactive"] { opacity: 0; }
|
|
519
|
+
```
|
|
520
|
+
|
|
521
|
+
```js
|
|
522
|
+
new Toggle({ trigger: '.tabs [trigger]', group: 'radio', indicator: '.tabs__pill', reveal: true });
|
|
523
|
+
```
|
|
524
|
+
|
|
525
|
+
**Разметка.** Индикатор кладите **внутрь** прокручиваемой ленты, у ленты - `position: relative`.
|
|
526
|
+
Тогда индикатор прокручивается вместе с табами и при прокрутке не пересчитывается. Индикатор вне
|
|
527
|
+
ленты тоже работает: `Toggle` пересчитывает его на каждом кадре прокрутки.
|
|
528
|
+
|
|
529
|
+
**Когда индикатор анимируется.** Переезд на другой триггер идёт по `transition` из CSS - в момент
|
|
530
|
+
начала активации, вместе с `activating`. Всё остальное индикатор делает **мгновенно**, на время
|
|
531
|
+
записи выключая `transition` в inline-стиле:
|
|
532
|
+
|
|
533
|
+
- первая расстановка при создании - индикатор не "выезжает" из нуля;
|
|
534
|
+
- появление после `state="inactive"` - встаёт на место, а не едет от прежнего;
|
|
535
|
+
- изменение размеров (`ResizeObserver` на триггерах и родителе индикатора): ресайз окна, подгрузка
|
|
536
|
+
шрифта, показ скрытой панели или модалки с табами;
|
|
537
|
+
- прокрутка ленты, если индикатор стоит вне её.
|
|
538
|
+
|
|
539
|
+
За каким триггером следует: за тем, чья активация началась последней. Выключили его (без группы
|
|
540
|
+
или `group: true`) - индикатор переходит к оставшемуся активному, если такой есть.
|
|
541
|
+
|
|
542
|
+
### Доводка таба до видимости
|
|
543
|
+
|
|
544
|
+
Если триггер лежит в горизонтальной ленте с прокруткой (`overflow-x: auto | scroll`) и виден в ней
|
|
545
|
+
не целиком, лента прокручивается так, чтобы он был виден целиком.
|
|
546
|
+
|
|
547
|
+
| Активация | Доводка |
|
|
548
|
+
|---|---|
|
|
549
|
+
| Переход по якорю: хеш при загрузке, `hashchange` при `keep_history` | всегда |
|
|
550
|
+
| Стартовый активный триггер (`state="active"` в разметке) | всегда |
|
|
551
|
+
| Клик, `activate()` / `toggle()` из кода | при `reveal: true` |
|
|
552
|
+
| Наведение (`action: 'hover'`) | никогда - меню прокрутилось бы под курсором |
|
|
553
|
+
|
|
554
|
+
Таб из ссылки или из разметки выбрал не пользователь, и он может стоять за краем ленты, поэтому
|
|
555
|
+
здесь доводка обязательна. Кликнутый таб пользователь видит хотя бы частично - довести его до
|
|
556
|
+
полной видимости или нет, решает проект флагом `reveal`.
|
|
557
|
+
|
|
558
|
+
Что учтено:
|
|
559
|
+
|
|
560
|
+
- прокручивается **только ближайшая** горизонтальная лента - ни страница, ни внешние области с
|
|
561
|
+
прокруткой, ни вертикаль не двигаются;
|
|
562
|
+
- `scroll-padding-inline` ленты: таб не уходит под липкие стрелки или градиент на краю;
|
|
563
|
+
- `scroll-snap`: лента прокручивается к точке прилипания, в которой таб виден целиком, - иначе
|
|
564
|
+
браузер "прилепил" бы её к ближайшей точке, и таб снова ушёл бы за край;
|
|
565
|
+
- `scroll-behavior: smooth` из CSS ленты работает; быстрые клики подряд не накапливают прокрутку -
|
|
566
|
+
лента приходит к последнему табу. Доводка при загрузке страницы и при показе скрытых табов -
|
|
567
|
+
мгновенная;
|
|
568
|
+
- RTL (`dir="rtl"`) - доводка и индикатор работают зеркально;
|
|
569
|
+
- табы скрыты (закрытая модалка, свёрнутая панель) - доводка откладывается до показа;
|
|
570
|
+
- таб, видимый целиком, ленту не двигает: ни после ручной прокрутки, ни при фокусе с клавиатуры
|
|
571
|
+
(браузер уже прокрутил ленту к фокусу, второго рывка нет);
|
|
572
|
+
- таб шире ленты выравнивается по начальному краю.
|