@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,57 @@
1
+ # hasInstanceSymbol.js
2
+
3
+ ## Описание
4
+
5
+ Внутренний разделяемый модуль («трейт»). Папка `_traits/` имеет префикс `_`, поэтому сборщик не делает из неё отдельный бандл — содержимое инлайнится в каждый модуль, который его импортирует (см. `scripts/build.mjs`). Классы импортируют только нужные им функции:
6
+
7
+ ```js
8
+ import { element, find, own } from '../_traits/hasInstanceSymbol.js';
9
+ ```
10
+
11
+ Модуль решает три задачи:
12
+
13
+ 1. **Разрешение элементов** — превратить `Element` / CSS-селектор / коллекцию в узел (`element`) или массив узлов (`elements`), с которым работает класс.
14
+ 2. **Реестр экземпляров** — пометить DOM-элемент приватным `Symbol`, ссылающимся на владеющий им экземпляр, и затем найти этот экземпляр по элементу.
15
+ 3. **Публикация API на элементе** (`expose`) — повесить методы владельца прямо на узел, чтобы с ним можно было работать, не доставая экземпляр.
16
+
17
+ `instance` — единственный `Symbol` уровня модуля, поэтому реестр общий для всех импортирующих модулей. Это корректно, так как DOM-узел принадлежит ровно одному компоненту.
18
+
19
+ ## Экспорты
20
+
21
+ | Экспорт | Сигнатура | Описание |
22
+ |---|---|---|
23
+ | `element` | `(param) => Element \| undefined` | `Element` возвращается как есть; селектор разрешается через `querySelector`. При ошибке/промахе — `undefined`. |
24
+ | `elements` | `(param) => Element[]` | Множество существующих элементов: `Element`, `NodeList`, `HTMLCollection`, массив (рекурсивно) или селектор → массив. Без побочных эффектов: `null`/промах/ошибка → `[]`. |
25
+ | `find` | `(param) => instance \| undefined` | Возвращает экземпляр, которому принадлежит элемент (или селектор), если он был помечен через `own`. |
26
+ | `own` | `(el, inst) => el` | Помечает `el` владельцем `inst` и возвращает `el` (можно вызывать по цепочке). |
27
+ | `expose` | `(el, api) => el` | Публикует методы владельца на самом элементе. Свойства неперечислимые (не попадают в `Object.keys` / `JSON.stringify`) и перезаписываемые. Занятое имя — нативное (`value`, `form`) или опубликованное другим владельцем — не затирается: `console.warn` и пропуск. |
28
+
29
+ ## Использование
30
+
31
+ Регистрация и обратный поиск (`Modal`, `Uploader`):
32
+
33
+ ```js
34
+ import { find, own } from '../_traits/hasInstanceSymbol.js';
35
+
36
+ class Modal {
37
+ static find = find; // публичный Modal.find(...)
38
+
39
+ constructor() {
40
+ this.modal = own(document.createElement('modal'), this);
41
+ // ...
42
+ }
43
+ }
44
+
45
+ // Где-нибудь в обработчике:
46
+ const modal = Modal.find(e.target.closest('modal'));
47
+ ```
48
+
49
+ Только разрешение элементов, без владения:
50
+
51
+ ```js
52
+ import { element } from '../_traits/hasInstanceSymbol.js';
53
+ const root = element(entity); // Element | undefined
54
+
55
+ import { elements } from '../_traits/hasInstanceSymbol.js';
56
+ elements(params.target).forEach(node => { /* ... */ });
57
+ ```
@@ -0,0 +1,13 @@
1
+ <!-- DOCGEN:START -->
2
+ # app
3
+
4
+ ## Папки
5
+
6
+ - [datepicker](datepicker/)
7
+ - [form](form/)
8
+
9
+ ## Файлы
10
+
11
+ - [index.js](index.js.md)
12
+
13
+ <!-- DOCGEN:END -->
@@ -0,0 +1,9 @@
1
+ <!-- DOCGEN:START -->
2
+ # datepicker
3
+
4
+ ## Файлы
5
+
6
+ - [_calendar.js](_calendar.js.md)
7
+ - [index.js](index.js.md)
8
+
9
+ <!-- DOCGEN:END -->
@@ -0,0 +1 @@
1
+ # _calendar.js
@@ -0,0 +1,153 @@
1
+ # datepicker.js
2
+
3
+ ## Обзор
4
+
5
+ `datepicker` - календарь на `st_app` без сторонних библиотек: поле с маской `ДД.ММ.ГГГГ` и
6
+ всплывающая сетка месяца, диапазон дат, границы `min`/`max`, режим `inline` с кнопками
7
+ "Сбросить" и "Выбрать". Как и `form`, это конфиг: регистрируется через `App.create(datepicker)`,
8
+ а `App` в его бандл не входит. `Mask` входит.
9
+
10
+ - Дату можно набрать с клавиатуры (маска как у `input type=date`: группы `ДД`, `ММ`, `ГГГГ`) или выбрать в сетке.
11
+ - В форму уходит ISO `YYYY-MM-DD` из скрытых полей. Видимые поля без `name` не отправляются.
12
+ - Проверка - через `setCustomValidity` на видимых полях. Несуществующая дата (`31.02`), выход за `min`/`max`,
13
+ конец диапазона раньше начала, пустое обязательное поле видны форме и `reportValidity()`.
14
+ - Календарное ядро (`_calendar.js`) - чистые функции без DOM. Им пользуются обёртки в других
15
+ фреймворках, чтобы не дублировать логику (`@cat-of-summer/st-script/src/app/datepicker/_calendar.js`).
16
+
17
+ Подключение:
18
+
19
+ ```js
20
+ // ESM / npm
21
+ import App from '@cat-of-summer/st-script/app';
22
+ import datepicker from '@cat-of-summer/st-script/app/datepicker';
23
+ App.create(datepicker);
24
+ ```
25
+
26
+ ```html
27
+ <!-- CDN / IIFE: App и глобальный Datepicker (конфиг) -->
28
+ <script defer src="dist/app.min.js"></script>
29
+ <script defer src="dist/app/datepicker.min.js"></script>
30
+ <script>document.addEventListener('DOMContentLoaded', () => App.create(Datepicker));</script>
31
+ ```
32
+
33
+ ---
34
+
35
+ ## Разметка
36
+
37
+ Разметку строит шаблон конфига, если `<st-app>` пустой; разметка внутри `<st-app>` заменяет его (см. "Свой шаблон"). Данные передаются атрибутами `:prop`:
38
+
39
+ ```html
40
+ <label for="delivery-date">Дата доставки</label>
41
+ <st-app app="datepicker" :name="date" :input-id="delivery-date" :min="2026-01-01" :required="true"></st-app>
42
+
43
+ <st-app app="datepicker" :name="period" :range="true" :value="2026-10-12/2026-10-15"></st-app>
44
+
45
+ <st-app app="datepicker" :inline="true" :range="true"></st-app>
46
+ ```
47
+
48
+ | Свойство (`:атрибут`) | По умолчанию | Описание |
49
+ |---|---|---|
50
+ | `name` | `''` | имя поля формы. Одиночная дата уходит как `name`, диапазон - как `name_from` и `name_to`. Пусто - ничего не отправляется |
51
+ | `range` | `false` | диапазон: два поля, в сетке выбираются начало и конец |
52
+ | `inline` | `false` | без полей, сетка всегда открыта, кнопки "Сбросить" и "Выбрать". Выбор становится значением только по "Выбрать" |
53
+ | `required` | `false` | пустое поле - ошибка проверки |
54
+ | `value` | `''` | ISO `YYYY-MM-DD`; диапазон - `YYYY-MM-DD/YYYY-MM-DD` (интервал ISO 8601). Меняется при выборе; запись из кода или в `:value` перерисовывает календарь |
55
+ | `min`, `max` | `''` | границы, ISO. Дни вне границ в сетке выключены, набранная дата вне границ - ошибка проверки |
56
+ | `inputId` (`:input-id`) | `''` | `id` первого поля - для `<label for>` |
57
+ | `messages` | см. ниже | тексты ошибок проверки |
58
+
59
+ > [!warning] Пустой `:prop` при монтировании берёт значение из конфига
60
+ > `:range=""` - это `false` из конфига, а не "включено". Булевы свойства пишите явно: `:range="true"`.
61
+
62
+ Сообщения по умолчанию (`{date}` - граница в `ДД.ММ.ГГГГ`):
63
+
64
+ ```js
65
+ messages: {
66
+ required: 'Заполните поле',
67
+ incomplete: 'Введите дату полностью',
68
+ invalid: 'Такой даты нет',
69
+ min: 'Дата не раньше {date}',
70
+ max: 'Дата не позже {date}',
71
+ order: 'Конец периода раньше начала',
72
+ }
73
+ ```
74
+
75
+ Свои тексты задаются через `App.extend('datepicker', { messages: {…} })` до монтирования.
76
+
77
+ ### Свой шаблон
78
+
79
+ Разметка внутри `<st-app app="datepicker">` заменяет встроенный шаблон - как у любого `st_app`.
80
+ Так проект держит вёрстку календаря у себя (обёртка `default/Datepicker` в шаблонах ST-forge),
81
+ а логика остаётся в конфиге. За основу берите `template` из `src/app/datepicker/index.js` и
82
+ сохраните маркеры `datepicker-from`, `datepicker-to` и `datepicker-value="from|to"`: по ним конфиг
83
+ находит поля. Имена скрытых полей и `id` в своём шаблоне можно писать сразу, без `{{ }}`.
84
+
85
+ ---
86
+
87
+ ## Классы шаблона
88
+
89
+ Конфиг не несёт CSS: внешний вид и тема - на стороне проекта. Классы статичные, целыми именами,
90
+ поэтому очистка неиспользуемого CSS их видит.
91
+
92
+ | Класс | Элемент |
93
+ |---|---|
94
+ | `[app="datepicker"]` | корень - сам `<st-app>`; от него и пишутся стили |
95
+ | `.datepicker__field` | строка полей с кнопкой; `--invalid` - ошибка после ухода из поля или попытки отправки |
96
+ | `.datepicker__input` | видимое поле (`[datepicker-from]`, `[datepicker-to]`) |
97
+ | `.datepicker__dash` | тире между полями диапазона |
98
+ | `.datepicker__toggle` | кнопка календаря; открыт - `aria-expanded="true"` |
99
+ | `.datepicker__popup` | сетка с навигацией; закрытая - атрибут `hidden`; `--inline` - режим `inline` |
100
+ | `.datepicker__nav`, `.datepicker__prev`, `.datepicker__next`, `.datepicker__caption` | навигация по месяцам и заголовок "Октябрь 2026" |
101
+ | `.datepicker__grid` | сетка 7 колонок: 7 `.datepicker__weekday` и 42 `.datepicker__day` |
102
+ | `.datepicker__day` | день; модификаторы `--other` (соседний месяц), `--today`, `--selected`, `--in-range`, `--range-from`, `--range-to`; вне границ - `disabled` |
103
+ | `.datepicker__buttons`, `.datepicker__reset`, `.datepicker__apply` | кнопки режима `inline` |
104
+
105
+ Тему удобно держать в переменных с фолбэком в месте использования (`var(--datepicker-accent, #4f46e5)`):
106
+ тогда тёмная секция переопределяет их на себе, а не правилами на каждый класс. Готовый набор - в
107
+ `examples/datepicker.html`.
108
+
109
+ ---
110
+
111
+ ## События
112
+
113
+ Все всплывают, `cancelable`.
114
+
115
+ | Событие | `detail` | Когда |
116
+ |---|---|---|
117
+ | `datepicker:change` | `{ from, to, value }` (ISO или `null`) | значение сменилось: выбор в сетке, набор с клавиатуры, "Выбрать", "Сбросить" |
118
+ | `datepicker:open` | `null` | открылась сетка |
119
+ | `datepicker:close` | `null` | закрылась сетка |
120
+
121
+ При смене значения скрытые поля получают всплывающие `input` и `change`: внутри `<st-app app="form">`
122
+ это `field:input` с `name` и ISO.
123
+
124
+ ---
125
+
126
+ ## Методы
127
+
128
+ - `open()`, `close()`, `toggle()` - сетка (кроме `inline`). Закрывают её также `Escape`, после которого фокус
129
+ возвращается на кнопку, и клик мимо календаря.
130
+ - `go(delta)` - листать месяцы: `go(-1)`, `go(12)`.
131
+ - `pick(iso)` - выбрать день, как кликом.
132
+ - `apply()` - текущий выбор сделать значением (кнопка "Выбрать").
133
+ - `clear()` - очистить значение (кнопка "Сбросить").
134
+ - `refresh()` - перечитать значение из скрытых полей. Нужен после `form.fill()`: он пишет `.value`
135
+ без событий.
136
+
137
+ `reset` формы возвращает начальное значение (`:value` на момент монтирования).
138
+
139
+ ---
140
+
141
+ ## Пример
142
+
143
+ ```js
144
+ App.create(datepicker);
145
+
146
+ document.addEventListener('datepicker:change', e => {
147
+ if (e.target.id == 'events-filter') loadEvents(e.detail.from, e.detail.to);
148
+ });
149
+ ```
150
+
151
+ ```html
152
+ <st-app app="datepicker" id="events-filter" :inline="true" :range="true" :min="2026-01-01"></st-app>
153
+ ```
@@ -0,0 +1,8 @@
1
+ <!-- DOCGEN:START -->
2
+ # form
3
+
4
+ ## Файлы
5
+
6
+ - [index.js](index.js.md)
7
+
8
+ <!-- DOCGEN:END -->