@dxtmisha/scripts 0.4.1 → 0.4.3

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/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@dxtmisha/scripts",
3
3
  "private": false,
4
- "version": "0.4.1",
4
+ "version": "0.4.3",
5
5
  "type": "module",
6
6
  "description": "Development scripts and CLI tools for DXT UI projects - automated component generation, library building and project management tools",
7
7
  "keywords": [
@@ -15,11 +15,12 @@ import {
15
15
  UI_FILE_NAME_VITE,
16
16
  UI_FILE_NAME_VITE_WORKERS
17
17
  } from '../../config'
18
+ import { isFilled } from '@dxtmisha/functional'
18
19
 
19
20
  // Sample Vite config template path / Путь к шаблону Vite-конфига
20
21
  const FILE_VITE_SAMPLE = [__dirname, '..', '..', 'media', 'templates', 'viteComponentTemplateConfig.ts']
21
22
  // Sample AI prompt template path / Путь к шаблону AI-промпта
22
- const FILE_PROMPT_SAMPLE = [__dirname, '..', '..', 'media', 'templates', 'componentPrompt.txt']
23
+ const FILE_PROMPT_SAMPLE = [__dirname, '..', '..', 'media', 'templates', 'componentPrompt.en.txt']
23
24
 
24
25
  // Async exec wrapper / Обёртка для асинхронного exec
25
26
  const execAsync = promisify(exec)
@@ -296,7 +297,7 @@ ${content}
296
297
  .replace('[stories]', this.storiesFile.read())
297
298
  .replace('[md]', this.mdFile.read())
298
299
  .replace(/\[wikiLanguage]/g, PropertiesConfig.getWikiLanguage())
299
- + ` ${this.prompt}`
300
+ + (isFilled(this.prompt) ? `Additional conditions (these conditions take priority): ${this.prompt}` : '')
300
301
  )
301
302
  }
302
303
 
@@ -0,0 +1,370 @@
1
+ You need to prepare documentation for a component in the [wikiLanguage] language. Follow the format and requirements strictly. Do not add anything beyond what is described.
2
+ Stack: Storybook 9.x, TypeScript, MDX.
3
+
4
+ Canvas component is imported from '@storybook/addon-docs/blocks'
5
+
6
+ ====================================
7
+ 1) Study the current component code
8
+ ====================================
9
+ ```
10
+ [code]
11
+ ```
12
+ Analyze the structure, props, events, slots, types, internal logic.
13
+
14
+ ====================================
15
+ 2) Add missing type comments
16
+ ====================================
17
+ Add brief single-language (in [wikiLanguage]) JSDoc comments to missing types and their properties.
18
+ Code to fix:
19
+ ```ts
20
+ // types.ts
21
+ [types]
22
+ ```
23
+ Duplicate the result below without wrapper:
24
+ [types]
25
+
26
+ Comment requirements:
27
+ - Single-line for simple fields.
28
+ - Multi-line for logic blocks.
29
+ - No duplication of the obvious.
30
+ - Adapted for storybook.
31
+
32
+ Example:
33
+ ```ts
34
+ /**
35
+ * Basic properties for image components.
36
+ */
37
+ export interface IconPropsBasic<
38
+ Image extends ImagePropsBasic = ImagePropsBasic
39
+ > extends SkeletonPropsInclude {
40
+ // Status
41
+ /** Active state of the icon */
42
+ active?: boolean
43
+
44
+ // Icon
45
+ /** Main icon value */
46
+ icon?: ImageValue<Image>
47
+ /** Active icon value */
48
+ iconActive?: ImageValue<Image>
49
+ }
50
+ ```
51
+
52
+ ====================================
53
+ 3) Stories for Storybook
54
+ ====================================
55
+ Create only the minimum necessary examples. Each example is as simple as possible, without extra wrappers, only what demonstrates the essence.
56
+ Code to fix:
57
+ ```ts
58
+ // ComponentDoc.stories.ts
59
+ [stories]
60
+ ```
61
+ Rules:
62
+ - Don't touch existing stories, only additions.
63
+ - Don't touch const meta. DO NOT CHANGE ANYTHING IN META.
64
+ - Don't touch existing constants.
65
+ - Don't add stories just for filling.
66
+ - If the component has different modes (e.g., states or display variants), show one example each.
67
+ - Story names in PascalCase style without extra words.
68
+ - Minimize imports: only what is required.
69
+
70
+ ====================================
71
+ 4) MDX documentation (component description)
72
+ ====================================
73
+ Prepare a complete component description in MDX format. Strict style: no tables, no extra sections.
74
+ Code to fix:
75
+ ```md
76
+ // UiPlayerLite.mdx
77
+ [md]
78
+ ```
79
+
80
+ MDX structure rules:
81
+ - At the beginning: [description] — Brief description of the purpose (1–3 sentences): conveys the essence of the component as briefly as possible.
82
+ - Next: main text (documentation) — starts without a heading. This is [doc].
83
+ - You can refine existing text by changing it, but don't delete. Delete only unnecessary or outdated content.
84
+ - Be sure to list slots (if any) and events (if any) in the given format.
85
+ - Don't describe props in a list if they are simple. Describe only complex relationships (e.g., dependent props) or composite types in detail.
86
+ - Usage example — at the end of the corresponding semantic block or at the very bottom if there is one general example.
87
+ - Slots and events — strictly in the format below. If there are no types, the type block is omitted.
88
+ - Add Canvas if there is a usage example. If not, add stories.
89
+
90
+ Slot format:
91
+ ```
92
+ ## Slots
93
+ ### `slotName`
94
+ Brief description of the slot's purpose. You can highlight features with a bulleted list.
95
+ If there are props, add props description. `props: any` means there are no props, no need to write it.
96
+ If there are multiple slots — each with `###` subheading.
97
+ If it just returns VNode, no need to describe.
98
+ Don't write something like: `This slot accepts any VNode and doesn't pass any properties.`
99
+ If there are no events, don't describe the events block.
100
+ If there are no slots, don't describe the slots block.
101
+
102
+ Event format:
103
+ ```
104
+ ## Events
105
+ ### `eventName`
106
+ Description of when and why it is emitted.
107
+
108
+ Slot description example (don't copy verbatim, adapt):
109
+ ### `suffix`
110
+
111
+ Slot for placing content at the end of the component, after the main content.
112
+
113
+ **Returns:** `VNode` — element with class `{className}__suffix` and attribute `data-event-type="suffix"`
114
+
115
+ ```html
116
+ <Component>
117
+ <template #suffix>
118
+ <Icon name="check" />
119
+ </template>
120
+ </Component>
121
+ ```
122
+
123
+ ### `control`
124
+
125
+ Slot for placing window control elements (close buttons, minimize, etc.).
126
+
127
+ **Parameters:**
128
+ - `props: WindowControlItem` — object with window control data
129
+
130
+ ```html
131
+ <Window>
132
+ <template #control="{ onclick, open }">
133
+ <button @click="onclick">
134
+ {{ open ? 'Close' : 'Open' }}
135
+ </button>
136
+ </template>
137
+ </Window>
138
+ ```
139
+
140
+ Event description example (adapt to context):
141
+ ### `window`
142
+
143
+ Event fires when the window state changes (open/close).
144
+
145
+ **Parameters:**
146
+ - `options: WindowEmitOptions` — object with window data
147
+
148
+ **WindowEmitOptions structure:**
149
+ - `id: string` — unique window identifier
150
+ - `element: HTMLDivElement` — window DOM element
151
+ - `control: HTMLElement` — control DOM element
152
+ - `open: boolean` — window open state (`true` - open, `false` - closed)
153
+
154
+ ```html
155
+ <script setup>
156
+ const handleWindow = (options) => {
157
+ console.log('Window ID:', options.id)
158
+ console.log('Window open:', options.open)
159
+ console.log('Window element:', options.element)
160
+ console.log('Control element:', options.control)
161
+ }
162
+ </script>
163
+
164
+ <template>
165
+ <Window @window="handleWindow">
166
+ <template #default>
167
+ <p>Window content</p>
168
+ </template>
169
+ </Window>
170
+ </template>
171
+ ```
172
+
173
+
174
+ Canvas usage example:
175
+ <Canvas of={Chip.ChipSkeleton}/>
176
+
177
+ ====================================
178
+ 5) Final return
179
+ ====================================
180
+ Return the result strictly in the format (nothing extra before or after):
181
+ [types.ts]
182
+ #########
183
+ [ComponentDoc.stories.ts]
184
+ #########
185
+ [UiPlayerLite.mdx]
186
+
187
+ Where:
188
+ - Don't add anything extra (like ```ts)
189
+ - Don't wrap in blocks.
190
+ - Don't wrap in ```ts or anything similar.
191
+ - [types.ts] — final types block with comments (only content, without file name comments).
192
+ - [ComponentDoc.stories.ts] — final stories file (only content, without file name comments).
193
+ - [UiPlayerLite.mdx] — final MDX documentation (only content, without file name comments).
194
+
195
+ ====================================
196
+ Constraints and style
197
+ ====================================
198
+ - No tables.
199
+ - No arbitrary additional sections.
200
+ - Don't add "Props" section if there are no complex dependencies.
201
+ - Don't duplicate descriptions of the same thing.
202
+ - Respect the [wikiLanguage] language — if it's "en" use English, otherwise the corresponding language.
203
+ - Don't use placeholders outside those specified.
204
+ - Code blocks: for types and events — ```ts, for markup — ```html when necessary.
205
+ - Stories: only necessary scenarios, without extra visual decorations.
206
+
207
+ ====================================
208
+ Example (don't include in response, only as style guide)
209
+ ====================================
210
+ Component for creating modal windows, dialogs, and popup elements with flexible positioning and adaptive behavior.
211
+
212
+ Window manages content display over the main interface, supports various positioning types (modal windows, dropdown menus, action sheets), open/close animations, and event system integration. The component automatically handles clicks outside the area, focus management, and adaptation to different screen sizes.
213
+
214
+ **Key Features:**
215
+
216
+ - Flexible positioning (center, edges, screen corners)
217
+ - Adaptive modes (modal, menu, actionSheet, static)
218
+ - Open/close animations with origin configuration
219
+ - State management via v-model or expose methods
220
+ - Scrollbar integration for scrollable content
221
+ - Background interaction blocking (persistent mode)
222
+ - Window lifecycle events
223
+
224
+ **Typical Use Cases:**
225
+
226
+ - Modal windows for forms and confirmations
227
+ - Dropdown menus and context menus
228
+ - Side panels and drawer components
229
+ - Action sheets for mobile interfaces
230
+ - Tooltips and dialogs
231
+
232
+ ## CSS Classes for Behavior Control
233
+
234
+ - `*--block` — prevents window from closing when clicking outside its boundaries
235
+ - `*--blockChildren` — prevents current window from closing
236
+ - `*--blockOther` — prevents other windows from closing until current one is closed
237
+ - `*--close` — applies to elements for closing the window
238
+ - `*--controlOpenOnly` — applies to control elements that only open the window
239
+ - `*--controlStatic` — applies to control elements in static mode
240
+ - `*--static` — applies to elements inside window, canceling all actions
241
+
242
+ Where `*` is the component class name (e.g., `d1-window`, `m3-window`).
243
+
244
+ ## Static Mode (staticMode)
245
+
246
+ The Window component supports static mode operation through the `staticMode` property. In this mode, the window works as an embedded component without modal behavior:
247
+
248
+ - **Content displays immediately** — window doesn't hide and doesn't require activation
249
+ - **Animations disabled** — no appearance/disappearance effects
250
+ - **Positioning disabled** — window is embedded in document flow
251
+ - **Works with adaptive** — when the `adaptive` property has one of the static modes (e.g., `static`), static mode is enabled
252
+
253
+ Static mode is especially useful for embedding window content directly into the interface without modal behavior.
254
+
255
+ ## Positioning Direction (axis)
256
+
257
+ Controls the axis of window placement relative to the anchor element. Default: `y`.
258
+
259
+ > Applies only in menu mode (`adaptive="menu"` or `adaptive="menuWindow"`).
260
+
261
+ **Possible values:**
262
+ - `'x'` — horizontal axis (left or right of anchor)
263
+ - `'y'` — vertical axis (top or bottom of anchor)
264
+ - `'on'` — over anchor (window centers on element)
265
+
266
+ ### Behavior
267
+
268
+ - Component automatically selects the placement side with the most available space
269
+ - When using context menu (`contextmenu`), positioning occurs from cursor coordinates
270
+ - Window always stays within visible screen area (viewport)
271
+ - Indent from anchor is set via `indent` property (default 4px)
272
+
273
+ ## State Management via v-model
274
+
275
+ Two-way binding of window open state via `v-model:open`.
276
+
277
+ **Parameters:**
278
+ - `open: boolean` — window open state
279
+
280
+ ```html
281
+ <script setup>
282
+ import { ref } from 'vue'
283
+
284
+ const isOpen = ref(false)
285
+ </script>
286
+
287
+ <template>
288
+ <button @click="isOpen = true">Open</button>
289
+
290
+ <Window v-model:open="isOpen">
291
+ <template #default>
292
+ <p>Window content</p>
293
+ <button @click="isOpen = false">Close</button>
294
+ </template>
295
+ </Window>
296
+ </template>
297
+ ```
298
+
299
+ ## Expose Methods
300
+ ### `id`
301
+
302
+ Unique window identifier.
303
+
304
+ **Type:** `string`
305
+
306
+ ```html
307
+ <script setup>
308
+ const windowRef = ref()
309
+
310
+ onMounted(() => {
311
+ console.log(windowRef.value.id) // "window-123"
312
+ })
313
+ </script>
314
+
315
+ <template>
316
+ <Window ref="windowRef" />
317
+ </template>
318
+ ```
319
+
320
+ ## Slots
321
+ ### `control`
322
+
323
+ Slot for placing window control elements (close buttons, minimize, etc.).
324
+
325
+ **Parameters:**
326
+ - `props: WindowControlItem` — object with window control data
327
+
328
+ ```html
329
+ <Window>
330
+ <template #control="{ onclick, open }">
331
+ <button @click="onclick">
332
+ {{ open ? 'Close' : 'Open' }}
333
+ </button>
334
+ </template>
335
+ </Window>
336
+ ```
337
+
338
+ ## Events
339
+ ### `window`
340
+
341
+ Event fires when the window state changes (open/close).
342
+
343
+ **Parameters:**
344
+ - `options: WindowEmitOptions` — object with window data
345
+
346
+ **WindowEmitOptions structure:**
347
+ - `id: string` — unique window identifier
348
+ - `element: HTMLDivElement` — window DOM element
349
+ - `control: HTMLElement` — control DOM element
350
+ - `open: boolean` — window open state (`true` - open, `false` - closed)
351
+
352
+ ```html
353
+ <script setup>
354
+ const handleWindow = (options) => {
355
+ console.log('Window ID:', options.id)
356
+ console.log('Window open:', options.open)
357
+ console.log('Window element:', options.element)
358
+ console.log('Control element:', options.control)
359
+ }
360
+ </script>
361
+
362
+ <template>
363
+ <Window @window="handleWindow">
364
+ <template #default>
365
+ <p>Window content</p>
366
+ </template>
367
+ </Window>
368
+ </template>
369
+ ```
370
+
@@ -0,0 +1,369 @@
1
+ Нужно подготовить документацию для компонента на языке [wikiLanguage]. Следуй строго формату и требованиям ниже. Не добавляй ничего лишнего вне описанного.
2
+ Стек Storybook 9.x, TypeScript, MDX.
3
+
4
+ Компонент Canvas подключается из '@storybook/addon-docs/blocks'
5
+
6
+ ====================================
7
+ 1) Изучи текущий код компонента
8
+ ====================================
9
+ ```
10
+ [code]
11
+ ```
12
+ Проанализируй структуру, props, события, слоты, типы, внутреннюю логику.
13
+
14
+ ====================================
15
+ 2) Добавь недостающие комментарии к типам
16
+ ====================================
17
+ Добавь краткие одноязычные (на [wikiLanguage]) JSDoc-комментарии к отсутствующим типам и их свойствам.
18
+ Код для исправления:
19
+ ```ts
20
+ // types.ts
21
+ [types]
22
+ ```
23
+ Ниже продублируй итог без обёртки:
24
+ [types]
25
+
26
+ Требования к комментариям:
27
+ - Однострочные для простых полей.
28
+ - Многострочные для блоков логики.
29
+ - Без дублирования очевидного.
30
+ - Адаптированы к storybook.
31
+
32
+ Пример:
33
+ ```ts
34
+ /**
35
+ * Basic properties for image components.
36
+ */
37
+ export interface IconPropsBasic<
38
+ Image extends ImagePropsBasic = ImagePropsBasic
39
+ > extends SkeletonPropsInclude {
40
+ // Status
41
+ /** Active state of the icon */
42
+ active?: boolean
43
+
44
+ // Icon
45
+ /** Значение основной иконки */
46
+ icon?: ImageValue<Image>
47
+ /** Значение активной иконки */
48
+ iconActive?: ImageValue<Image>
49
+ }
50
+ ```
51
+
52
+ ====================================
53
+ 3) Истории (stories) для Storybook
54
+ ====================================
55
+ Создай только минимально необходимые примеры. Каждый пример — максимально простой, без лишних обёрток, только то, что демонстрирует суть.
56
+ Код для исправления:
57
+ ```ts
58
+ // ComponentDoc.stories.ts
59
+ [stories]
60
+ ```
61
+ Правила:
62
+ - Не трогать те stories, которые уже есть, только добавления.
63
+ - Не трогать const meta. НИЧЕГО НЕ МЕНЯТЬ В META.
64
+ - Не трогать существующие константы.
65
+ - Не добавляй истории ради заполнения.
66
+ - Если компонент имеет разные режимы (например, состояния или варианты отображения), покажи по одному примеру.
67
+ - Имена историй — в стиле PascalCase без лишних слов.
68
+ - Минимизируй импорты: только то, что требуется.
69
+
70
+ ====================================
71
+ 4) MDX-документация (описание компонента)
72
+ ====================================
73
+ Подготовь полное описание компонента в формате MDX. Строгая стилистика: никаких таблиц, никаких лишних разделов.
74
+ Код для исправления:
75
+ ```md
76
+ // UiPlayerLite.mdx
77
+ [md]
78
+ ```
79
+
80
+ Правила структуры MDX:
81
+ - В начале: [description] — Краткое описание назначения (1–3 предложения): максимально коротко передаёт суть компонента.
82
+ - Далее: основной текст (документация) — начинается без заголовка. Это [doc].
83
+ - Можно дорабатывать существующий текст, изменяя, но не удалять. Удаляй только лишнее или неактуальное.
84
+ - Обязательно перечисли слоты (если есть) и события (если есть) в заданном формате.
85
+ - Не описывай props списком, если они простые. Подробно описывай только сложные связки (например, зависимые props) или составные типы.
86
+ - Пример использования — в конце соответствующего смыслового блока или в самом низу, если один общий пример.
87
+ - Слоты и события — строго в формате ниже. Если типов нет — блок с типом опускается.
88
+ - Добавь Canvas, если есть пример использования. Если нет — добавь stories.
89
+
90
+ Формат слотов:
91
+ ```
92
+ ## Слоты
93
+ ### `имяСлота`
94
+ Краткое описание назначения слота. Можно маркированным списком выделить особенности.
95
+ Если есть props, добавить описание props. `props: any` - это значит, что нет пропсов, его не надо писать.
96
+ Если слотов несколько — каждый с подпунктом `###`.
97
+ Если возвращает просто VNode, не надо описывать.
98
+ Не надо писать что-то в таком виде: `Этот слот принимает любые VNode и не передает никаких свойств.`
99
+ Если нет событий, не описывать блок событий.
100
+ Если нет слотов, не описывать блок слотов.
101
+
102
+ Формат событий:
103
+ ```
104
+ ## События
105
+ ### `имяСобытия`
106
+ Описание, когда и зачем испускается.
107
+
108
+ Пример описания слота (не вставляй дословно, адаптируй):
109
+ ### `suffix`
110
+
111
+ Слот для размещения контента в конце компонента, после основного содержимого.
112
+
113
+ **Возвращает:** `VNode` — элемент с классом `{className}__suffix` и атрибутом `data-event-type="suffix"`
114
+
115
+ ```html
116
+ <Component>
117
+ <template #suffix>
118
+ <Icon name="check" />
119
+ </template>
120
+ </Component>
121
+ ```
122
+
123
+ ### `control`
124
+
125
+ Слот для размещения элементов управления окном (кнопки закрытия, минимизации и т.д.).
126
+
127
+ **Параметры:**
128
+ - `props: WindowControlItem` — объект с данными управления окном
129
+
130
+ ```html
131
+ <Window>
132
+ <template #control="{ onclick, open }">
133
+ <button @click="onclick">
134
+ {{ open ? 'Закрыть' : 'Открыть' }}
135
+ </button>
136
+ </template>
137
+ </Window>
138
+ ```
139
+
140
+ Пример описания события (адаптируй под контекст):
141
+ ### `window`
142
+
143
+ Событие срабатывает при изменении состояния окна (открытие/закрытие).
144
+
145
+ **Параметры:**
146
+ - `options: WindowEmitOptions` — объект с данными окна
147
+
148
+ **Структура WindowEmitOptions:**
149
+ - `id: string` — уникальный идентификатор окна
150
+ - `element: HTMLDivElement` — DOM элемент окна
151
+ - `control: HTMLElement` — DOM элемент управления
152
+ - `open: boolean` — состояние открытия окна (`true` - открыто, `false` - закрыто)
153
+
154
+ ```html
155
+ <script setup>
156
+ const handleWindow = (options) => {
157
+ console.log('ID окна:', options.id)
158
+ console.log('Окно открыто:', options.open)
159
+ console.log('Элемент окна:', options.element)
160
+ console.log('Элемент управления:', options.control)
161
+ }
162
+ </script>
163
+
164
+ <template>
165
+ <Window @window="handleWindow">
166
+ <template #default>
167
+ <p>Содержимое окна</p>
168
+ </template>
169
+ </Window>
170
+ </template>
171
+ ```
172
+
173
+
174
+ Пример использования Canvas:
175
+ <Canvas of={Chip.ChipSkeleton}/>
176
+
177
+ ====================================
178
+ 5) Итоговый возврат
179
+ ====================================
180
+ Верни результат строго в формате (ничего лишнего до или после):
181
+ [types.ts]
182
+ #########
183
+ [ComponentDoc.stories.ts]
184
+ #########
185
+ [UiPlayerLite.mdx]
186
+
187
+ Где:
188
+ - Не добавляй ничего лишнего (типа ```ts)
189
+ - Не оборачивай в блоки.
190
+ - Не оборачивай в ```ts или что-то подобное.
191
+ - [types.ts] — итоговый блок типов с комментариями (only content, without file name comments).
192
+ - [ComponentDoc.stories.ts] — итоговый файл историй (only content, without file name comments).
193
+ - [UiPlayerLite.mdx] — итоговая MDX-документация (only content, without file name comments).
194
+
195
+ ====================================
196
+ Ограничения и стилистика
197
+ ====================================
198
+ - Никаких таблиц.
199
+ - Никаких произвольных дополнительных разделов.
200
+ - Не добавляй раздел "Props", если нет сложных зависимостей.
201
+ - Не дублируй описание одного и того же.
202
+ - Уважай язык [wikiLanguage] — если это "en" используй английский, иначе соответствующий язык.
203
+ - Не используй placeholder'ы вне оговорённых.
204
+ - Кодовые блоки: для типов и событий — ```ts, для разметки — ```html при необходимости.
205
+ - Сторисы: только необходимые сценарии, без лишних визуальных украшений.
206
+
207
+ ====================================
208
+ Пример (не включать в ответ, только как ориентир стиля)
209
+ ====================================
210
+ Компонент для создания модальных окон, диалогов и всплывающих элементов с гибким позиционированием и адаптивным поведением.
211
+
212
+ Window управляет отображением контента поверх основного интерфейса, поддерживает различные типы позиционирования (модальные окна, выпадающие меню, action sheets), анимации открытия/закрытия и интеграцию с системой событий. Компонент автоматически обрабатывает клики вне области, управление фокусом и адаптацию под различные размеры экранов.
213
+
214
+ **Основные возможности:**
215
+
216
+ - Гибкое позиционирование (центр, края, углы экрана)
217
+ - Адаптивные режимы (modal, menu, actionSheet, static)
218
+ - Анимации открытия/закрытия с настройкой origin
219
+ - Управление состоянием через v-model или expose методы
220
+ - Интеграция со Scrollbar для прокручиваемого контента
221
+ - Блокировка взаимодействия с фоном (persistent режим)
222
+ - События жизненного цикла окна
223
+
224
+ **Типичные сценарии использования:**
225
+
226
+ - Модальные окна для форм и подтверждений
227
+ - Выпадающие меню и контекстные меню
228
+ - Боковые панели и drawer компоненты
229
+ - Action sheets для мобильных интерфейсов
230
+ - Всплывающие подсказки и диалоги
231
+
232
+ ## CSS классы для управления поведением
233
+
234
+ - `*--block` — предотвращает закрытие окна при клике вне его границ
235
+ - `*--blockChildren` — предотвращает закрытие текущего окна
236
+ - `*--blockOther` — предотвращает закрытие других окон до закрытия текущего
237
+ - `*--close` — применяется к элементам для закрытия окна
238
+ - `*--controlOpenOnly` — применяется к элементам управления, которые только открывают окно
239
+ - `*--controlStatic` — применяется к элементам управления в статическом режиме
240
+ - `*--static` — применяется к элементам внутри окна, отменяя все действия
241
+
242
+ Где `*` — название класса компонента (например, `d1-window`, `m3-window`).
243
+
244
+ ## Статический режим (staticMode)
245
+
246
+ Компонент Window поддерживает статический режим работы через свойство `staticMode`. В этом режиме окно работает как встроенный компонент без модального поведения:
247
+
248
+ - **Содержимое отображается сразу** — окно не скрывается и не требует активации
249
+ - **Отключены анимации** — нет эффектов появления/исчезновения
250
+ - **Отключено позиционирование** — окно встраивается в поток документа
251
+ - **Работает с adaptive** — когда свойство `adaptive` имеет один из статичных режимов (например, `static`), включается статичный режим
252
+
253
+ Статический режим особенно полезен для встраивания содержимого окна непосредственно в интерфейс без модального поведения.
254
+
255
+ ## Направление позиционирования (axis)
256
+
257
+ Управляет осью размещения окна относительно элемента-якоря. По умолчанию: `y`.
258
+
259
+ > Применяется только в режиме меню (`adaptive="menu"` или `adaptive="menuWindow"`).
260
+
261
+ **Возможные значения:**
262
+ - `'x'` — горизонтальная ось (слева или справа от якоря)
263
+ - `'y'` — вертикальная ось (сверху или снизу от якоря)
264
+ - `'on'` — поверх якоря (окно центрируется над элементом)
265
+
266
+ ### Поведение
267
+
268
+ - Компонент автоматически выбирает сторону размещения с наибольшим доступным пространством
269
+ - При использовании контекстного меню (`contextmenu`) позиционирование происходит от координат курсора
270
+ - Окно всегда остается в пределах видимой области экрана (viewport)
271
+ - Отступ от якоря задается через свойство `indent` (по умолчанию 4px)
272
+
273
+ ## Управление состоянием через v-model
274
+
275
+ Двусторонняя привязка состояния открытия окна через `v-model:open`.
276
+
277
+ **Параметры:**
278
+ - `open: boolean` — состояние открытия окна
279
+
280
+ ```html
281
+ <script setup>
282
+ import { ref } from 'vue'
283
+
284
+ const isOpen = ref(false)
285
+ </script>
286
+
287
+ <template>
288
+ <button @click="isOpen = true">Открыть</button>
289
+
290
+ <Window v-model:open="isOpen">
291
+ <template #default>
292
+ <p>Содержимое окна</p>
293
+ <button @click="isOpen = false">Закрыть</button>
294
+ </template>
295
+ </Window>
296
+ </template>
297
+ ```
298
+
299
+ ## Expose методы
300
+ ### `id`
301
+
302
+ Уникальный идентификатор окна.
303
+
304
+ **Тип:** `string`
305
+
306
+ ```html
307
+ <script setup>
308
+ const windowRef = ref()
309
+
310
+ onMounted(() => {
311
+ console.log(windowRef.value.id) // "window-123"
312
+ })
313
+ </script>
314
+
315
+ <template>
316
+ <Window ref="windowRef" />
317
+ </template>
318
+ ```
319
+
320
+ ## Слоты
321
+ ### `control`
322
+
323
+ Слот для размещения элементов управления окном (кнопки закрытия, минимизации и т.д.).
324
+
325
+ **Параметры:**
326
+ - `props: WindowControlItem` — объект с данными управления окном
327
+
328
+ ```html
329
+ <Window>
330
+ <template #control="{ onclick, open }">
331
+ <button @click="onclick">
332
+ {{ open ? 'Закрыть' : 'Открыть' }}
333
+ </button>
334
+ </template>
335
+ </Window>
336
+ ```
337
+
338
+ ## События
339
+ ### `window`
340
+
341
+ Событие срабатывает при изменении состояния окна (открытие/закрытие).
342
+
343
+ **Параметры:**
344
+ - `options: WindowEmitOptions` — объект с данными окна
345
+
346
+ **Структура WindowEmitOptions:**
347
+ - `id: string` — уникальный идентификатор окна
348
+ - `element: HTMLDivElement` — DOM элемент окна
349
+ - `control: HTMLElement` — DOM элемент управления
350
+ - `open: boolean` — состояние открытия окна (`true` - открыто, `false` - закрыто)
351
+
352
+ ```html
353
+ <script setup>
354
+ const handleWindow = (options) => {
355
+ console.log('ID окна:', options.id)
356
+ console.log('Окно открыто:', options.open)
357
+ console.log('Элемент окна:', options.element)
358
+ console.log('Элемент управления:', options.control)
359
+ }
360
+ </script>
361
+
362
+ <template>
363
+ <Window @window="handleWindow">
364
+ <template #default>
365
+ <p>Содержимое окна</p>
366
+ </template>
367
+ </Window>
368
+ </template>
369
+ ```
@@ -2,7 +2,6 @@
2
2
  <html lang="en">
3
3
  <head>
4
4
  <meta charset="UTF-8" />
5
- <link rel="icon" type="image/svg+xml" href="/vite.svg" />
6
5
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
7
6
  <title>@packages/library</title>
8
7
  </head>
@@ -1,190 +0,0 @@
1
- Нужно подготовить документацию для компонента на языке [wikiLanguage]. Следуй строго формату и требованиям ниже. Не добавляй ничего лишнего вне описанного.
2
- Стек Storybook 9.x, TypeScript, MDX.
3
-
4
- ====================================
5
- 1) Изучи текущий код компонента
6
- ====================================
7
- ```
8
- [code]
9
- ```
10
- Проанализируй структуру, props, события, слоты, типы, внутреннюю логику.
11
-
12
- ====================================
13
- 2) Добавь недостающие комментарии к типам
14
- ====================================
15
- Добавь краткие одноязычные (на [wikiLanguage]) JSDoc-комментарии к отсутствующим типам и его свойство.
16
- Код для испправления:
17
- ```ts
18
- // types.ts
19
- [types]
20
- ```
21
- Ниже продублируй итог без обёртки:
22
- [types]
23
-
24
- Требования к комментариям:
25
- - Однострочные для простых полей.
26
- - Многострочные для блоков логики.
27
- - Без дублирования очевидного.
28
- - адаптированы к storybook.
29
-
30
- Пример:
31
- ```ts
32
- /**
33
- * Basic properties for image components.
34
- */
35
- export interface IconPropsBasic<
36
- Image extends ImagePropsBasic = ImagePropsBasic
37
- > extends SkeletonPropsInclude {
38
- // Status
39
- /** Active state of the icon */
40
- active?: boolean
41
-
42
- // Icon
43
- /** Значение основной иконки */
44
- icon?: ImageValue<Image>
45
- /** Значение активной иконки */
46
- iconActive?: ImageValue<Image>
47
- }
48
- ```
49
-
50
- ====================================
51
- 3) Истории (stories) для Storybook
52
- ====================================
53
- Создай только минимально необходимые примеры. Каждый пример — максимально простой, без лишних обёрток, только то, что демонстрирует суть.
54
- Код для испправления:
55
- ```ts
56
- // ComponentDoc.stories.ts
57
- [stories]
58
- ```
59
- Правила:
60
- - Не трогать те сторис, который уже есть, только добавления.
61
- - Не трогать const meta. НЕЧЕГО НЕ МЕНЯТЬ В META.
62
- - Не трогать существующие константы.
63
- - Не добавляй истории ради заполнения.
64
- - Если компонент имеет разные режимы (например, состояния или варианты отображения), покажи по одному примеру.
65
- - Имена историй — в стиле PascalCase без лишних слов.
66
- - Минимизируй импорты: только то, что требуется.
67
-
68
- ====================================
69
- 4) MDX-документация (описание компонента)
70
- ====================================
71
- Подготовь полное описание компонента в формате MDX. Строгая стилистика: никаких таблиц, никаких лишних разделов.
72
- Код для испправления:
73
- ```md
74
- // UiPlayerLite.mdx
75
- [md]
76
- ```
77
-
78
- Правила структуры MDX:
79
- - В начале: [description] — Краткое описание назначения (1–3 предложения): максимально коротко передаёт суть компонента.
80
- - Далее: основной текст (документация) — начинается без заголовка. Это [doc].
81
- - Можно дорабатывать существующий текст, изменя, но не удалять. Удаляй только лишнее или не актуальный.
82
- - Обязательно перечисли слоты (если есть) и события (если есть) в заданном формате.
83
- - Не описывай props списком, если они простые. Подробно описывай только сложные связки (например, зависимые props) или составные типы.
84
- - Пример использования — в конце соответствующего смыслового блока или в самом низу, если один общий пример.
85
- - Слоты и события — строго в формате ниже. Если типов нет — блок с типом опускается.
86
- - Добавит Canvas, если есть пример использования. Если нет — добавить сторис.
87
-
88
- Формат слотов:
89
- ```
90
- ## Слоты
91
- ### `имяСлота`
92
- Краткое описание назначения слота. Можно маркированным списком выделить особенности.
93
- Если есть props, добавить описанике props. `props: any` - это значить что нету пропсов, его не надо писать.
94
- Если слотов несколько — каждый с подпунктом `###`.
95
-
96
- Формат событий:
97
- ```
98
- ## События
99
- ### `имяСобытия`
100
- Описание когда и зачем испускается.
101
- ```ts
102
- // сигнатура обработчика
103
- ```
104
- ```
105
-
106
- Пример блока props для связанных свойств (использовать ТОЛЬКО если реально нужно):
107
- ```
108
- ## Свойства выделения текста
109
- ... (как в примере ниже)
110
- ```
111
-
112
- Пример описания слота (не вставляй дословно, адаптируй):
113
- ```
114
- ### `prefix`
115
- Слот для размещения контента в начале компонента перед основным содержимым.
116
- - Подходит для иконок, индикаторов или меток
117
- - Не влияет на структуру
118
- ```
119
-
120
- Пример описания события (адаптируй под контекст):
121
- ```
122
- ### `click`
123
- Событие клика по корневой области компонента.
124
- ```ts
125
- function onClick(event: MouseEvent, value: EventClickValue) {
126
- // обработка
127
- }
128
-
129
- type EventClickValue = {
130
- type: string
131
- value: any
132
- detail: Record<string, any> | undefined
133
- }
134
- ```
135
- ```
136
-
137
- Пример использования Canvas:
138
- <Canvas of={Chip.ChipSkeleton}/>
139
-
140
- ====================================
141
- 5) Итоговый возврат
142
- ====================================
143
- Верни результат строго в формате (ничего лишнего до или после):
144
- [types.ts]
145
- #########
146
- [ComponentDoc.stories.ts]
147
- #########
148
- [UiPlayerLite.mdx]
149
-
150
- Где:
151
- - не добавляй ничего лишнего. (типа ```ts)
152
- - не оборачивай в блоки.
153
- - не оборачивай в ```ts или что-то подбного.
154
- - [types.ts] — итоговый блок типов с комментариями (only content, without file name comments).
155
- - [ComponentDoc.stories.ts] — итоговый файл историй (only content, without file name comments).
156
- - [UiPlayerLite.mdx] — итоговая MDX-документация (only content, without file name comments).
157
-
158
- ====================================
159
- Ограничения и стилистика
160
- ====================================
161
- - Никаких таблиц.
162
- - Никаких произвольных дополнительных разделов.
163
- - Не добавляй раздел "Props", если нет сложных зависимостей.
164
- - Не дублируй описание одного и того же.
165
- - Уважай язык [wikiLanguage] — если это "en" используй английский, иначе соответствующий язык.
166
- - Не используй placeholder'ы вне оговорённых.
167
- - Кодовые блоки: для типов и событий — ```ts, для разметки — ```html при необходимости.
168
- - Сторисы: только необходимые сценарии, без лишних визуальных украшений.
169
-
170
- ====================================
171
- Пример (не включать в ответ, только как ориентир стиля)
172
- ====================================
173
- ## Свойства выделения текста
174
-
175
- Свойства `highlight` и `highlightLengthStart` предназначены для управления выделением текста в компонентах.
176
-
177
- ### Свойства
178
-
179
- - **highlight** — Текст для выделения в содержимом компоненте
180
- - **highlightLengthStart** — Минимальная длина значения highlight для начала выделения
181
-
182
- ### Взаимосвязь свойств
183
-
184
- Свойства работают совместно для обеспечения интеллектуального выделения текста. `highlight` определяет что выделять, а `highlightLengthStart` контролирует когда начинать выделение.
185
-
186
- - `highlight` содержит строку текста, которую нужно найти и выделить в компоненте
187
- - `highlightLengthStart` устанавливает минимальную длину строки поиска для активации функции выделения
188
- - Выделение активируется только когда длина `highlight` достигает значения `highlightLengthStart`
189
- - Это предотвращает нежелательное выделение при вводе коротких строк поиска
190
- - Оба свойства обеспечивают оптимальный пользовательский опыт при работе с поиском и фильтрацией