@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,28 @@
|
|
|
1
|
+
# _engine.js
|
|
2
|
+
|
|
3
|
+
## Описание
|
|
4
|
+
|
|
5
|
+
Чистая геометрия [Observer](index.js.md) без DOM: на вход идут прямоугольники
|
|
6
|
+
`{ top, left, width, height }` (подходит и `DOMRect`). Плоские именованные экспорты,
|
|
7
|
+
тесты — `node tests/observer.test.mjs`.
|
|
8
|
+
|
|
9
|
+
## Экспорты
|
|
10
|
+
|
|
11
|
+
| Функция | Что делает |
|
|
12
|
+
|---|---|
|
|
13
|
+
| `parse_edge(token)` | `'top'`, `'80%'`, `'120px'`, `'bottom-10%'`, `40` → `{ frac, px }`: позиция = начало + `frac × размер` + `px`. Мусор — предупреждение и `{ 0, 0 }` |
|
|
14
|
+
| `parse_line(value, root_default)` | `'top 80%'` → `[край элемента, край root]`; без второго токена root берёт `root_default` |
|
|
15
|
+
| `parse_zone(start, end)` | `{ start, end }`; root по умолчанию — `bottom` для start и `top` для end |
|
|
16
|
+
| `measure(rect, root, zone, axis)` | `{ a, b }` — линия элемента минус линия root для start и для end |
|
|
17
|
+
| `state_of(a, b)` | `a > 0` → `before`, `b < 0` → `after`, иначе `active` |
|
|
18
|
+
| `progress_of(a, b)` | `−a / (b − a)`, зажатый в `0…1`. Нулевая или обратная зона — ступенька 0 → 1 на линии start |
|
|
19
|
+
| `intersects(r1, r2)` | Строгое пересечение: касание краем не считается |
|
|
20
|
+
| `steps(prev, next)` | Переход → список `{ hook, direction, state }`. Перескок `before ↔ after` даёт `on_enter` и `on_leave` подряд |
|
|
21
|
+
|
|
22
|
+
## Почему `a` и `b`
|
|
23
|
+
|
|
24
|
+
При прокрутке на δ все прямоугольники во viewport сдвигаются на δ, а root — нет. Поэтому `a`
|
|
25
|
+
и `b` уменьшаются одинаково, и их разность `b − a` — длина пути через зону — постоянна. Состояние и
|
|
26
|
+
прогресс считаются из текущих rect без кэша позиций. Значит, layout-сдвиги, картинки и
|
|
27
|
+
шрифты не требуют ручного `refresh()`, если после них был хоть один кадр прокрутки или
|
|
28
|
+
изменение размера.
|
|
@@ -0,0 +1,259 @@
|
|
|
1
|
+
# Observer.js
|
|
2
|
+
|
|
3
|
+
## Описание
|
|
4
|
+
|
|
5
|
+
Механизм анимаций по скроллу. Следит, где элемент находится относительно зоны прокрутки, и
|
|
6
|
+
пишет это на сам элемент: атрибут `state`, CSS-переменные `--progress` и `--index`, атрибут
|
|
7
|
+
`crossing`. Анимацию задаёт CSS потребителя по этим меткам, как `[state]` у `Select` и
|
|
8
|
+
`Loader`. Хуки нужны там, где мало CSS: счётчики, ленивая загрузка, аналитика.
|
|
9
|
+
|
|
10
|
+
Один инстанс обслуживает все подходящие элементы. Одна прокрутка — один кадр
|
|
11
|
+
`requestAnimationFrame` на инстанс: сначала все чтения геометрии, потом все записи.
|
|
12
|
+
|
|
13
|
+
## Модель: зона и три состояния
|
|
14
|
+
|
|
15
|
+
Зона задаётся двумя линиями, как в GSAP ScrollTrigger:
|
|
16
|
+
|
|
17
|
+
- `start: 'top bottom'` — зона начинается, когда **верх элемента** встречает **низ root**;
|
|
18
|
+
- `end: 'bottom top'` — зона кончается, когда **низ элемента** встречает **верх root**.
|
|
19
|
+
|
|
20
|
+
Первое слово линии — край элемента, второе — край root (viewport или контейнера `root`).
|
|
21
|
+
|
|
22
|
+
```
|
|
23
|
+
before active after
|
|
24
|
+
┌──────────────────────┐ ┌──────────────────────────┐ ┌──────────────────────┐
|
|
25
|
+
элемент ниже линии start между start и end, 0 → 1 элемент прошёл линию end
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
| `state` | Когда | `--progress` |
|
|
29
|
+
|---|---|---|
|
|
30
|
+
| `before` | Зона ещё впереди (и начальное состояние при привязке) | `0` |
|
|
31
|
+
| `active` | Элемент между линиями start и end | `0…1` |
|
|
32
|
+
| `after` | Зона пройдена | `1` |
|
|
33
|
+
|
|
34
|
+
Края в линии:
|
|
35
|
+
|
|
36
|
+
| Запись | Значение |
|
|
37
|
+
|---|---|
|
|
38
|
+
| `top` / `center` / `bottom` | 0 / 50% / 100% высоты (для `axis: 'x'` — `left` / `center` / `right`) |
|
|
39
|
+
| `80%`, `120px`, `-20` | Доля размера или пиксели от начала (число без единиц — пиксели) |
|
|
40
|
+
| `top+100px`, `bottom-10%`, `50%+20px` | Край со сдвигом |
|
|
41
|
+
|
|
42
|
+
Второе слово можно опустить: у `start` root по умолчанию `bottom`, у `end` — `top`.
|
|
43
|
+
|
|
44
|
+
Типичные зоны:
|
|
45
|
+
|
|
46
|
+
| Задача | `start` | `end` |
|
|
47
|
+
|---|---|---|
|
|
48
|
+
| Весь путь через экран (параллакс) | `top bottom` | `bottom top` |
|
|
49
|
+
| Появиться, когда элемент поднялся на 20% экрана | `top 80%` | `bottom top` |
|
|
50
|
+
| Прогресс чтения статьи | `top top` | `bottom bottom` |
|
|
51
|
+
| Подсветка пункта меню, пока секция под серединой экрана | `top center` | `bottom center` |
|
|
52
|
+
|
|
53
|
+
## Конструктор
|
|
54
|
+
|
|
55
|
+
```js
|
|
56
|
+
new Observer(params)
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
| Параметр | По умолчанию | Описание |
|
|
60
|
+
|---|---|---|
|
|
61
|
+
| `target` | `'[observe]'` | Селектор / Element / NodeList отслеживаемых элементов |
|
|
62
|
+
| `root` | `null` | Контейнер прокрутки (селектор / Element); `null` — viewport |
|
|
63
|
+
| `axis` | `'y'` | Ось: `'y'` или `'x'` (горизонтальная лента) |
|
|
64
|
+
| `start` | `'top bottom'` | Линия начала зоны |
|
|
65
|
+
| `end` | `'bottom top'` | Линия конца зоны |
|
|
66
|
+
| `once` | `false` | После первого входа `state="active"` навсегда, элемент снимается с учёта |
|
|
67
|
+
| `progress` | `false` | Писать `--progress` и вызывать `on_progress` |
|
|
68
|
+
| `stagger` | `0` | Сек. Элементы, вошедшие в одном кадре, входят по очереди с этим шагом |
|
|
69
|
+
| `live` | `false` | Подхватывать новые элементы по `target` и отпускать удалённые (`MutationObserver`). Только для строкового `target` |
|
|
70
|
+
| `cross` | `null` | Селектор / Element целей: следить пересечение каждого элемента с ними |
|
|
71
|
+
|
|
72
|
+
### Переопределение атрибутами
|
|
73
|
+
|
|
74
|
+
Атрибуты элемента перекрывают параметры для этого элемента. Читаются при привязке.
|
|
75
|
+
|
|
76
|
+
| Атрибут | Перекрывает |
|
|
77
|
+
|---|---|
|
|
78
|
+
| `observe-start="top 80%"` | `start` |
|
|
79
|
+
| `observe-end="bottom 20%"` | `end` |
|
|
80
|
+
| `observe-once` / `observe-once="false"` | `once` |
|
|
81
|
+
| `observe-progress` / `observe-progress="false"` | `progress` |
|
|
82
|
+
|
|
83
|
+
Пустое значение атрибута-флага значит «да».
|
|
84
|
+
|
|
85
|
+
### Хуки
|
|
86
|
+
|
|
87
|
+
Передаются в `params` и привязываются к инстансу (`this` — Observer).
|
|
88
|
+
|
|
89
|
+
| Хук | Аргументы | Когда |
|
|
90
|
+
|---|---|---|
|
|
91
|
+
| `before_init` / `on_init` | `(params)` | В начале и в конце конструктора |
|
|
92
|
+
| `on_enter` | `(el, info)` | Вход в зону: `forward` — из `before`, `backward` — из `after` |
|
|
93
|
+
| `on_leave` | `(el, info)` | Выход: `forward` — в `after`, `backward` — в `before` |
|
|
94
|
+
| `on_progress` | `(el, info)` | Изменился прогресс (только при `progress`) |
|
|
95
|
+
| `on_cross` / `on_uncross` | `(el, goal)` | Элемент начал или перестал пересекаться с целью из `cross` |
|
|
96
|
+
|
|
97
|
+
`info = { state, prev, direction, progress, index }`:
|
|
98
|
+
`state` — состояние после события, `prev` — до перехода, `direction` — `'forward'` (прокрутка
|
|
99
|
+
вниз или вправо) или `'backward'`, `progress` — последнее значение, `index` — место в
|
|
100
|
+
stagger-очереди.
|
|
101
|
+
|
|
102
|
+
Если быстрый скролл перескочил зону за кадр (`before → after`), вызываются оба хука подряд:
|
|
103
|
+
`on_enter`, затем `on_leave`. Ни одна пара вход/выход не теряется. Ошибка в хуке пишется в
|
|
104
|
+
консоль и не мешает остальным элементам.
|
|
105
|
+
|
|
106
|
+
Таблица соответствия ScrollTrigger: `onEnter` = `on_enter` + `forward`, `onEnterBack` =
|
|
107
|
+
`on_enter` + `backward`, `onLeave` = `on_leave` + `forward`, `onLeaveBack` = `on_leave` + `backward`.
|
|
108
|
+
|
|
109
|
+
## Что пишется на элементы
|
|
110
|
+
|
|
111
|
+
| Метка | Когда | Значение |
|
|
112
|
+
|---|---|---|
|
|
113
|
+
| атрибут `state` | всегда | `before` / `active` / `after` |
|
|
114
|
+
| `--progress` | `progress` | `0…1`, 4 знака |
|
|
115
|
+
| `--index` | `stagger > 0` | Порядковый номер во входящей пачке |
|
|
116
|
+
| атрибут `crossing` | `cross` | Есть, пока элемент пересекается хоть с одной целью |
|
|
117
|
+
|
|
118
|
+
Прятать элементы стоит по `[state="before"]`, а не по «не active». Тогда уже прокрученные
|
|
119
|
+
(`after`) остаются видимыми, а без JS атрибута нет совсем — и ничего не скрыто.
|
|
120
|
+
|
|
121
|
+
## Публичные методы и свойства
|
|
122
|
+
|
|
123
|
+
| Член | Описание |
|
|
124
|
+
|---|---|
|
|
125
|
+
| `observe(target)` | Взять элементы на учёт, в том числе отпущенные раньше через `once` или `unobserve`; возвращает `this` |
|
|
126
|
+
| `unobserve(target)` | Снять с учёта; атрибуты на элементе остаются как есть |
|
|
127
|
+
| `refresh()` | Пересканировать `target` и цели `cross`, отпустить ушедшие из DOM, пересчитать всё. Элементы, отпущенные через `once` или `unobserve`, заново не берутся — иначе `live` перезапускал бы уже отыгравшие анимации |
|
|
128
|
+
| `state(el)` | `{ state, progress, direction }` или `null` |
|
|
129
|
+
| `destroy()` | Снять все слушатели, наблюдателей и таймеры |
|
|
130
|
+
| `clone(params)` | Новый инстанс с объединёнными параметрами и `parent: this` |
|
|
131
|
+
| `params` | Конфигурация без функций |
|
|
132
|
+
| `elements` | Элементы на учёте |
|
|
133
|
+
| `Observer.find(el)` | Инстанс, владеющий элементом |
|
|
134
|
+
|
|
135
|
+
## Как устроено внутри
|
|
136
|
+
|
|
137
|
+
- **Геометрия** — чистые функции [_engine.js](_engine.js.md): по прямоугольникам элемента и root
|
|
138
|
+
считаются `a` и `b` — расстояния до линий start и end. От них зависят состояние и прогресс.
|
|
139
|
+
- **Кадр** — `scroll` ловится на `document` в фазе захвата (это и окно, и вложенные
|
|
140
|
+
контейнеры), `resize` — на window, рост контента — `ResizeObserver` на root. Всё это только
|
|
141
|
+
планирует кадр; постоянного rAF-цикла нет.
|
|
142
|
+
- **Гейт** — `IntersectionObserver` с `rootMargin: 100%` отмечает элементы в пределах ещё
|
|
143
|
+
одного root с каждой стороны. Каждый кадр меряются только они. Ушедший далеко элемент
|
|
144
|
+
меряется один раз и получает финальное состояние. Если задан `cross`, меряются все элементы.
|
|
145
|
+
- **Первый показ** — при привязке ставится `state="before"`, а пересчёт идёт через кадр. Так
|
|
146
|
+
элементы на первом экране тоже проигрывают CSS-переход входа, как в AOS.
|
|
147
|
+
- **Stagger** — входящие в одном кадре элементы сортируются по порядку в документе. `state`
|
|
148
|
+
и `on_enter` откладываются на `index × stagger`. Если до своей очереди элемент снова
|
|
149
|
+
покинул зону, вход отменяется.
|
|
150
|
+
|
|
151
|
+
## Примеры
|
|
152
|
+
|
|
153
|
+
### Появление при прокрутке (как AOS)
|
|
154
|
+
|
|
155
|
+
```html
|
|
156
|
+
<section observe class="fade-up">…</section>
|
|
157
|
+
<section observe observe-start="top 60%">…</section>
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
```css
|
|
161
|
+
.fade-up { transition: opacity .6s, transform .6s; }
|
|
162
|
+
.fade-up[state="before"] { opacity: 0; transform: translateY(40px); }
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
```js
|
|
166
|
+
new Observer({ start: 'top 85%', once: true });
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
### Каскад карточек
|
|
170
|
+
|
|
171
|
+
```css
|
|
172
|
+
.card { transition: opacity .4s, transform .4s; }
|
|
173
|
+
.card[state="before"] { opacity: 0; transform: scale(.94); }
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
```js
|
|
177
|
+
new Observer({ target: '.card', start: 'top 90%', once: true, stagger: 0.08, live: true });
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
`live` подхватывает карточки, которые позже вставит `Loader`. Очередь входа держит таймер
|
|
181
|
+
`stagger`. `--index` остаётся на элементе и пригодится в CSS для чего-то ещё, например для
|
|
182
|
+
чередования направления: `translate: calc((var(--index) % 2 * 2 - 1) * 20px) 0`.
|
|
183
|
+
|
|
184
|
+
### Параллакс и прогресс
|
|
185
|
+
|
|
186
|
+
```css
|
|
187
|
+
.hero img { transform: translateY(calc((var(--progress, 0) - .5) * -120px)); }
|
|
188
|
+
.reading-bar { transform: scaleX(var(--progress, 0)); transform-origin: left; }
|
|
189
|
+
```
|
|
190
|
+
|
|
191
|
+
```js
|
|
192
|
+
new Observer({ target: '.hero', progress: true });
|
|
193
|
+
|
|
194
|
+
// прогресс статьи пишется на саму статью, полоса читает его через наследование
|
|
195
|
+
new Observer({ target: 'article', start: 'top top', end: 'bottom bottom', progress: true });
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
### Шапка над тёмной секцией
|
|
199
|
+
|
|
200
|
+
```css
|
|
201
|
+
header { position: fixed; color: #111; }
|
|
202
|
+
header[crossing] { color: #fff; }
|
|
203
|
+
```
|
|
204
|
+
|
|
205
|
+
```js
|
|
206
|
+
new Observer({ target: 'header', cross: '.section-dark' });
|
|
207
|
+
```
|
|
208
|
+
|
|
209
|
+
### Меню-оглавление (scrollspy)
|
|
210
|
+
|
|
211
|
+
```js
|
|
212
|
+
new Observer({
|
|
213
|
+
target: 'section[id]',
|
|
214
|
+
start: 'top center',
|
|
215
|
+
end: 'bottom center',
|
|
216
|
+
on_enter: el => document.querySelector(`nav a[href="#${el.id}"]`)?.classList.add('current'),
|
|
217
|
+
on_leave: el => document.querySelector(`nav a[href="#${el.id}"]`)?.classList.remove('current'),
|
|
218
|
+
});
|
|
219
|
+
```
|
|
220
|
+
|
|
221
|
+
### Счётчик при первом показе
|
|
222
|
+
|
|
223
|
+
```js
|
|
224
|
+
new Observer({
|
|
225
|
+
target: '[counter]',
|
|
226
|
+
once: true,
|
|
227
|
+
on_enter: el => animateNumber(el, +el.getAttribute('counter')),
|
|
228
|
+
});
|
|
229
|
+
```
|
|
230
|
+
|
|
231
|
+
## Сравнение с библиотеками
|
|
232
|
+
|
|
233
|
+
| Возможность | AOS | GSAP ScrollTrigger | Motion `inView` / `scroll` | Observer |
|
|
234
|
+
|---|---|---|---|---|
|
|
235
|
+
| Вход и выход, `once` | ✓ | ✓ | ✓ | ✓ |
|
|
236
|
+
| Направление входа и выхода | — | ✓ | — | ✓ `direction` |
|
|
237
|
+
| Зона двумя линиями | offset | ✓ | ✓ `offset` | ✓ `start` / `end` |
|
|
238
|
+
| Прогресс 0…1 | — | ✓ `scrub` | ✓ | ✓ `--progress` |
|
|
239
|
+
| Анимация чистым CSS | ✓ пресеты | toggleClass | — | ✓ `[state]`, `--progress` |
|
|
240
|
+
| Каскад | delay | `batch()` | — | ✓ `stagger`, `--index` |
|
|
241
|
+
| Новые элементы из DOM | `refresh` вручную | `refresh` вручную | — | ✓ `live` |
|
|
242
|
+
| Пересечение двух элементов | — | — | — | ✓ `cross` |
|
|
243
|
+
| Pin, smooth-scroll, snap | — | ✓ | — | — (CSS `sticky`, `scroll-snap`) |
|
|
244
|
+
| Готовые анимации | ✓ | ✓ таймлайны | ✓ | — (это делает CSS) |
|
|
245
|
+
|
|
246
|
+
Нативные CSS scroll-driven animations (`animation-timeline: view()`) решают ту же задачу для
|
|
247
|
+
`--progress` без JS, но не дают хуков, `once`, stagger и `cross`, а поддержка браузерами ещё
|
|
248
|
+
неполная. Observer работает везде, где есть `IntersectionObserver` и `ResizeObserver`.
|
|
249
|
+
|
|
250
|
+
## Ограничения
|
|
251
|
+
|
|
252
|
+
- **Один элемент — один Observer.** Элемент, уже занятый другим инстансом, пропускается с
|
|
253
|
+
предупреждением: два инстанса спорили бы за атрибут `state`.
|
|
254
|
+
- **Гейт на один root.** Элементы дальше одного размера root от его краёв меряются только
|
|
255
|
+
при входе в гейт и выходе из него. Если линия зоны вынесена дальше (`'top -150%'`), смена
|
|
256
|
+
состояния за гейтом проявится, только когда элемент в него вернётся.
|
|
257
|
+
- **Сдвиг вёрстки без прокрутки и без изменения размера root** (например, `transform`
|
|
258
|
+
соседей) кадр не планирует — вызовите `refresh()`.
|
|
259
|
+
- **`once` и `--progress`.** После первого входа элемент снят с учёта, прогресс замирает.
|