@dxtmisha/scripts 0.9.0 → 0.9.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@dxtmisha/scripts",
   "private": false,
-  "version": "0.9.0",
+  "version": "0.9.1",
   "type": "module",
   "description": "Development scripts and CLI tools for DXT UI projects - automated component generation, library building and project management tools",
   "keywords": [

package/src/media/templates/componentDoc/materials/README.md

@@ -0,0 +1,8 @@
+# Work Materials
+
+This folder is designed to store all supporting design documents, component specifications, assets, research notes, and raw inputs utilized for generating high-quality component documentation and design integrations.
+
+### Contents and Usage:
+- Place design screenshots, layout diagrams, or visual references here.
+- Place text drafts, API research files, or functional notes here.
+- Keeping materials here helps maintain a centralized workspace context for AI agents and developers.

package/src/media/templates/componentDoc/materials/prompt.txt

@@ -0,0 +1,28 @@
+Task Goal:
+Based on the design assets, specifications, and other work materials located in this "materials" folder, you must implement a fully working, production-ready, and robust component.
+
+Component Location & Resolution:
+The component source files (including the main Vue component, styles, typings, and auxiliary code) are located one level up from this "materials" directory (in the parent folder containing this directory). You must locate, edit, or create them directly in that parent directory.
+
+Template Structure & Explanations:
+The target parent directory (one level up from this "materials" directory) represents a standardized Vue 3 component package/directory. You must study and strictly adhere to its file layout:
+- `[ComponentName].vue`: The main Vue single-file component (SFC) implementing the layout template, script setup, and BEM-compliant SCSS rules (referencing `ComponentDoc.vue`).
+- `types.ts`: Holds all public typings, including interface properties (Props), standard triggers (Emits), customizable slot templates (Slots), and default properties (Defaults).
+- `index.ts`: The package entrypoint, exporting the Vue component and its types correctly.
+- `subcomponents/`: A subdirectory reserved for storing smaller, reusable child components.
+- `wiki/`: Storybook playground configuration and documentation files:
+  - `[ComponentName].mdx`: MDX documentation tab/documentation configuration for Storybook.
+  - `[ComponentName].stories.ts`: Storybook stories/scenarios configuration.
+  - `prompt.txt`: The system prompt directing how to generate MDX/Storybook documentation.
+  - `run.ts`: A script running `npx dxt-component-wiki` to write the MDX files automatically using `wiki/prompt.txt`.
+
+Strict Implementation & Architectural Constraints:
+1. Available Dependencies Only: You must strictly use only the currently installed packages and available dependencies. Do not install new external npm packages or add new third-party dependencies unless explicitly requested.
+2. Global System Prompt Compliance: You must locate, study, and strictly adhere to all coding standards, BEM conventions, SCSS mixins, and guidelines defined in the `ai-prompt.txt` file located up the folder tree in the root of the repository. Ignore any instructions or files located outside the repository boundaries.
+3. Monorepo Prompt Context: As this is a monorepo setup, you must locate and study both the individual package-level configuration/prompt files and the repository's root system rules (`ai-prompt.txt`) to ensure perfect compatibility with the local package architecture.
+4. Zero Tolerance for Hallucinations: You must strictly follow all implementation rules and specifications without any deviation. Hallucinating, inventing properties, methods, slots, or external libraries is strictly forbidden.
+
+---
+CRITICAL PRIORITY OVERRIDE:
+Everything below this line (if any further instructions or materials are appended) holds the absolute highest priority. Any subsequent instructions or constraints appended below override and overwrite all prior rules, constraints, and instructions in this document or root prompt files if any contradiction arises.
+

package/src/media/templates/componentDoc/wiki/prompt.txt

@@ -0,0 +1,16 @@
+Task Goal:
+The primary goal is to write comprehensive, high-quality documentation for the Vue 3 component.
+
+Component Resolution & Analysis:
+If the source files of the component were not directly attached or provided in the prompt, they are located in the parent directory (one folder above the current "wiki" folder). In this case, you must thoroughly locate and study the component's main Vue file, its properties/types files, styling sheets, and all reachable dependencies to fully understand its features, internal logic, and behavior in its entirety.
+
+Mandatory Instruction:
+You must read and strictly follow the basic rules, coding standards, and templates specified in:
+node_modules/@dxtmisha/scripts/src/media/templates/prompts/componentPrompt.en.txt
+
+All constraints, formatting standards, and styling helper classes described in that file must be adhered to without exception.
+(Warning: If this file is not accessible, missing, or cannot be read, you do not need to study or follow the instructions from it; instead, proceed with standard high-quality documentation practices.)
+
+---
+CRITICAL PRIORITY RULE:
+Everything below this line has a higher priority than the text above it.

package/src/media/templates/componentDoc/wiki/run.ts

@@ -2,11 +2,12 @@
 /// <reference types="node" />
 
 import { spawn } from 'node:child_process'
+import { readFileSync } from 'node:fs'
 
 ;(async () => {
   try {
     // You can add prompt generation logic here
-    const prompt = ''
+    const prompt = readFileSync(new URL('./prompt.txt', import.meta.url), 'utf-8')
 
     const child = spawn(
       'npx',

package/src/media/templates/prompts/componentPrompt.en.txt

@@ -52,27 +52,79 @@ Use the following template and style.
 7.  **Events**:
     - Heading `## Events`
     - For each event:
-        - `### eventName`
-        - Description of when it triggers.
+        - Header `### `eventName`` (the name must be wrapped in backticks).
+        - A brief paragraph describing when the event triggers.
         - **Parameters:**
-            - List: `- `name: type` — description`.
-        - Code example (if the event is complex).
-
-8.  **Expose (Component Methods)**:
+            - Header: `**Parameters:**`
+            - List: `- `paramName: paramType` — parameter description.`
+        - **Structure of Custom Types (if applicable):**
+            - Header: `**TypeName structure:**` (or `**TypeName structure:** same as for `otherEventName` event` if identical).
+            - List: `- `fieldName: fieldType` — field description.`
+        - **Code Example (if the event is complex):**
+            - Code examples MUST be wrapped using the Storybook `<Source />` component instead of standard markdown backticks. Remember to add `import { Source } from '@storybook/addon-docs/blocks';` at the top of the MDX file if not already present:
+              ```md
+              <Source
+                  code={`
+              <script setup>
+              // code example here
+              </script>
+                `}
+                  language="html"
+              />
+              ```
+
+8.  **Expose (Component Methods & Properties)**:
     - Heading `## Expose`
-    - For each public method (accessible via ref):
-        - `### methodName()`
-        - Description of the action.
-        - **Returns:** `Type` (or `void`).
+    - Under the heading, present the list of public methods, reactive references (Refs), and computed variables exposed by the component, in the clean, signature-based bullet format:
+        - For methods: `- `methodName(paramName: paramType): returnType` — Description.`
+        - For reactive states (Refs/Computed): `- `propertyName: PropertyType` — Description.`
+        - Standard types include `boolean`, `void`, `Ref<any>`, `ComputedRef<any>`, etc.
 
 9.  **Slots**:
     - Heading `## Slots`
-    - For each slot:
-        - `### slotName`
-        - Description of purpose.
-        - **Parameters (Scoped Props):**
-            - List: `- `name: type` — description`.
-        - Code example using the slot.
+    - Under the heading, present the list of slots in the clean, signature-based bullet format:
+        - For slots without parameters: `- `slotName: Type` — Description.`
+        - For slots with parameters: `- `slotName(paramName: paramType): Type` — Description.`
+        - Standard return type is usually `VNode` or `any`.
+
+### Storybook Layout Helpers (storybookStyle.scss):
+When writing Storybook stories (`*.stories.ts`) and examples in the MDX documentation, you MUST use the predefined showcase helper classes. These styles are imported globally and start with the `.wiki-storybook-` prefix. Do not write custom inline styles or new CSS classes for showcase layout, positioning, placeholders, or containers; use the following helper classes:
+
+- **Containers & Layouts**:
+  - `.wiki-storybook-container` — enables container queries (`container-type: inline-size`).
+  - `.wiki-storybook-group` — a 12-column CSS Grid layout (`grid-template-columns: repeat(12, 1fr)`) with an `8px` gap, perfect for presenting multiple items or variations.
+  - `.wiki-storybook-flex` — basic flexbox wrapper (`display: flex; flex-wrap: wrap`) with an `8px` gap.
+  - `.wiki-storybook-flex-align-center` — same as flex wrapper, but aligns items vertically (`align-items: center`).
+  - `.wiki-storybook-flex-center` — centers items horizontally and vertically with an `8px` gap.
+  - `.wiki-storybook-flex-column` — vertical flexbox layout (`display: flex; flex-direction: column`) with a `16px` gap.
+  - `.wiki-storybook-decreased` — constrains maximum width of the showcase block to `72%`.
+  - `.wiki-storybook-decreasedX2` — constrains showcase block width responsively (`64%` at `md` screens, `48%` at `lg` screens).
+
+- **Showcase Items (`.wiki-storybook-item`)**:
+  Used to display components inside a unified visual frame (aspect-ratio `1/1` by default, border, rounded corners, hidden overflow):
+  - `.wiki-storybook-item__label` — a small floaty label at the top-left corner (`font-size: 12px`, semi-transparent blurred background) for labeling specific variations. Use `.wiki-storybook-item__label--static` to make it flow statically inside the block without absolute positioning.
+  - `&--padding` — adds standard `16px` padding inside the item box.
+  - `&--rectangle` — sets a `16:9` aspect ratio and spans all 12 columns in a grid.
+  - `&--widescreen` — sets a `32:9` aspect ratio and spans all 12 columns in a grid.
+  - `&--compact` — sets a `64:9` aspect ratio and spans all 12 columns in a grid.
+  - `&--auto` — sets aspect ratio to `auto` and spans all 12 columns in a grid.
+  - `&--squared--xs`, `&--squared--sm`, `&--squared--md`, `&--squared--lg`, `&--squared--max` — responsive grid item spans. For instance, `--squared--sm` spans 6 columns on mobile, 4 columns on tablet (640px+), and 2 columns on desktop (1024px+).
+  - `&--center` — flex-centers internal elements.
+  - `&--widthAuto` — sets width to `auto`.
+  - `&--overflowVisible` — overrides `overflow: hidden` to `overflow: visible` (useful for dropdowns or modals).
+  - `&--rtl` — sets Right-to-Left (RTL) text and flex layout direction.
+
+- **Mock Components & Placeholders**:
+  - `.wiki-storybook-card` — a mock card (`320px` width, rounded borders) to simulate real-world layout placement:
+    - `.wiki-storybook-card__image` — 128px high cover image.
+    - `.wiki-storybook-card__content` — vertical flex layout with `16px` padding and `16px` gap.
+    - `.wiki-storybook-card__label` — title with `20px` font size.
+    - `.wiki-storybook-card__information` — muted descriptions (`14px` size, gray).
+    - `.wiki-storybook-card__actions` — horizontal actions flex wrapper (`8px` gap).
+  - `.wiki-storybook-button` — standard story action trigger button. Modifiers for status colors: `&--success` (green), `&--error` (red), `&--warning` (yellow), `&--info` (blue).
+  - `.wiki-storybook-dummy` — visual placeholder box (`32px` high, dark translucent grey).
+    - Colors: `&--color--blue`, `&--color--red`, `&--color--green`.
+    - Sizes: `&--size--sm` (height `64px`), `&--size--md` (height `128px`), `&--size--lg` (height `256px`).
 
 ### Instructions:
 1. Study the provided component code (including props, emits, slots, expose).
@@ -82,6 +134,9 @@ Use the following template and style.
 3.2. Try to keep original descriptions unchanged.
 4. Use the correct terminology (Props, Events, Slots, Expose).
 4.1. All headings must be in [wikiLanguage].
+4.2. In Storybook stories and MDX code examples, you MUST use the predefined layout helper classes from `storybookStyle.scss` (described above) instead of inline styles or custom CSS blocks.
+4.3. Do not modify the original component code under any circumstances unless explicitly requested.
+4.4. Strictly follow all rules in this prompt. There is zero tolerance for hallucinations: do not invent, assume, or add any non-existent properties, methods, events, slots, or external package dependencies.
 5. Do not add unnecessary introductions or conclusions, only MDX.
 6. Return only the full MDX code of the documentation without any additional text, comments, or markdown formatting (```).
 7. The result must be exclusively text (response), do not attach any files.

package/src/media/templates/prompts/componentPrompt.ru.txt

@@ -52,27 +52,79 @@
 7.  **Events (События)**:
     - Заголовок `## Events`
     - Для каждого события:
-        - `### имяСобытия`
-        - Описание, когда срабатывает.
+        - Заголовок `### \`имяСобытия\`` (имя события обязательно должно быть обернуто в обратные кавычки).
+        - Краткое текстовое описание того, когда событие срабатывает.
         - **Параметры:**
-            - Список: `- `имя: тип` — описание`.
-        - Пример кода (если событие сложное).
-
-8.  **Expose (Методы компонента)**:
+            - Заголовок: `**Параметры:**`
+            - Список: `- \`имяПараметра: типПараметра\` — описание параметра.`
+        - **Структура сложных типов (если применимо):**
+            - Заголовок: `**Структура TypeName:**` (или `**Структура TypeName:** такая же, как для события \`другоеСобытие\``, если они идентичны).
+            - Список: `- \`имяПоля: типПоля\` — описание поля.`
+        - **Пример кода (если событие сложное):**
+            - Примеры кода ОБЯЗАТЕЛЬНО должны быть обернуты в компонент Storybook `<Source />` вместо стандартного markdown-форматирования (три обратные кавычки). Не забудь добавить `import { Source } from '@storybook/addon-docs/blocks';` в самый верх MDX файла, если его там еще нет:
+              ```md
+              <Source
+                  code={`
+              <script setup>
+              // пример кода здесь
+              </script>
+                `}
+                  language="html"
+              />
+              ```
+
+8.  **Expose (Публичные методы и свойства компонента)**:
     - Заголовок `## Expose`
-    - Для каждого публичного метода (доступного через ref):
-        - `### имяМетода()`
-        - Описание действия.
-        - **Возвращает:** `Тип` (или `void`).
+    - Внутри раздела выводи список публичных методов, реактивных ссылок (Refs) и вычисляемых свойств (Computed), доступных через ref компонента, в чистом маркированном формате сигнатур:
+        - Для методов: `- `имяМетода(имяПараметра: типПараметра): возвращаемыйТип` — Описание.`
+        - Для реактивных переменных/свойств: `- `имяСвойства: ТипСвойства` — Описание.`
+        - Стандартные типы возвращаемых значений: `boolean`, `void`, `Ref<any>`, `ComputedRef<any>` и т.д.
 
 9.  **Slots (Слоты)**:
     - Заголовок `## Slots`
-    - Для каждого слота:
-        - `### имяСлота`
-        - Описание назначения.
-        - **Параметры (Scoped Props):**
-            - Список: `- `имя: тип` — описание`.
-        - Пример кода использования слота.
+    - Внутри раздела выводи список слотов в чистом маркированном формате сигнатур:
+        - Для слотов без параметров: `- `имяСлота: Тип` — Описание.`
+        - Для слотов с параметрами: `- `имяСлота(имяПараметра: типПараметра): Тип` — Описание.`
+        - Стандартный тип возвращаемого значения обычно `VNode` или `any`.
+
+### Вспомогательные стили Storybook (storybookStyle.scss):
+При написании сценариев Storybook (`*.stories.ts`) и примеров кода в MDX-документации ОБЯЗАТЕЛЬНО используй предопределенные вспомогательные классы для демонстрации. Эти стили импортируются глобально и имеют префикс `.wiki-storybook-`. Избегай написания кастомных инлайн-стилей или новых CSS-классов для лейаута, позиционирования, заглушек или контейнеров. Используй следующие готовые классы:
+
+- **Контейнеры и сетки**:
+  - `.wiki-storybook-container` — включает контейнерные запросы (`container-type: inline-size`).
+  - `.wiki-storybook-group` — CSS Grid сетка на 12 колонок (`grid-template-columns: repeat(12, 1fr)`) с отступом `8px`. Отлично подходит для демонстрации нескольких вариантов компонента.
+  - `.wiki-storybook-flex` — базовая flex-обертка (`display: flex; flex-wrap: wrap`) с отступом `8px`.
+  - `.wiki-storybook-flex-align-center` — flex-обертка с центрированием элементов по вертикали (`align-items: center`).
+  - `.wiki-storybook-flex-center` — полное центрирование элементов (горизонтальное и вертикальное) с отступом `8px`.
+  - `.wiki-storybook-flex-column` — вертикальный flex-контейнер (`display: flex; flex-direction: column`) с отступом `16px`.
+  - `.wiki-storybook-decreased` — уменьшает максимальную ширину блока до `72%`.
+  - `.wiki-storybook-decreasedX2` — адаптивно уменьшает ширину блока (`64%` на экранах `md`, `48%` на экранах `lg`).
+
+- **Демонстрационные карточки (`.wiki-storybook-item`)**:
+  Используются для отображения компонентов внутри единого визуального блока (по умолчанию aspect-ratio `1/1`, рамка, скругление углов, скрытый overflow):
+  - `.wiki-storybook-item__label` — небольшая плавающая метка в левом верхнем углу (`font-size: 12px`, полупрозрачный размытый фон) для подписи вариаций. Класс `.wiki-storybook-item__label--static` делает метку статичной без абсолютного позиционирования.
+  - `&--padding` — добавляет стандартные внутренние отступы `16px`.
+  - `&--rectangle` — устанавливает соотношение сторон `16:9` и растягивает блок на все 12 колонок в сетке.
+  - `&--widescreen` — соотношение сторон `32:9`, растягивает блок на все 12 колонок в сетке.
+  - `&--compact` — соотношение сторон `64:9`, растягивает блок на все 12 колонок в сетке.
+  - `&--auto` — автоматическое соотношение сторон, растягивает блок на все 12 колонок в сетке.
+  - `&--squared--xs`, `&--squared--sm`, `&--squared--md`, `&--squared--lg`, `&--squared--max` — адаптивное управление шириной квадратных блоков. Например, `--squared--sm` занимает 6 колонок на мобильных, 4 колонки на планшетах (от 640px) и 2 колонки на десктопах (от 1024px).
+  - `&--center` — выравнивает содержимое по центру с помощью flex.
+  - `&--widthAuto` — устанавливает ширину `auto`.
+  - `&--overflowVisible` — сбрасывает `overflow: hidden` на `overflow: visible` (необходимо для выпадающих меню, модалок).
+  - `&--rtl` — включает режим отображения справа налево (Right-to-Left).
+
+- **Тестовые компоненты и заглушки**:
+  - `.wiki-storybook-card` — тестовая карточка (ширина `320px`, скругления, рамка) для симуляции реального интерфейса:
+    - `.wiki-storybook-card__image` — обложка высотой 128px.
+    - `.wiki-storybook-card__content` — вертикальный flex-контейнер с отступами `16px` и расстоянием `16px`.
+    - `.wiki-storybook-card__label` — заголовок с размером шрифта `20px`.
+    - `.wiki-storybook-card__information` — серый текст описания (`14px`).
+    - `.wiki-storybook-card__actions` — горизонтальный контейнер для кнопок (`8px`).
+  - `.wiki-storybook-button` — кнопка-заглушка для обработки кликов. Модификаторы для статусных цветов: `&--success` (зеленый), `&--error` (красный), `&--warning` (желтый), `&--info` (синий).
+  - `.wiki-storybook-dummy` — визуальный блок-заглушка (`32px` высотой, полупрозрачный серый).
+    - Цвета: `&--color--blue`, `&--color--red`, `&--color--green`.
+    - Размеры (высота): `&--size--sm` (`64px`), `&--size--md` (`128px`), `&--size--lg` (`256px`).
 
 ### Инструкции:
 1. Изучи предоставленный код компонента (включая props, emits, slots, expose).
@@ -82,6 +134,9 @@
 3.2. Старайся сохранять оригинальные описания без изменений.
 4. Используй правильную терминологию (Props, Events, Slots, Expose).
 4.1. Все заголовки должны быть на языке [wikiLanguage].
+4.2. В сценариях Storybook и примерах MDX-кода вы ОБЯЗАНЫ использовать предопределенные классы-помощники разметки из `storybookStyle.scss` (описанные выше) вместо инлайн-стилей или кастомных блоков CSS.
+4.3. Ни при каких обстоятельствах не изменяй оригинальный код компонента, если об этом явно не попросили.
+4.4. Строго следуй всем правилам и инструкциям данного промпта. Никаких галлюцинаций: категорически запрещено придумывать, домысливать или добавлять несуществующие свойства (props), методы (expose), события (events), слоты (slots) или внешние зависимости.
 5. Не добавляй лишних введений или заключений, только MDX.
 6. Верни только полный MDX-код документации без какого-либо дополнительного текста, комментариев или форматирования markdown (```).
 7. Результат должен быть исключительно в виде текста (ответа), не прикрепляй никаких файлов.

package/src/media/templates/componentDoc/figma/run-figma.ts

@@ -1,26 +0,0 @@
-#!/usr/bin/env vite-node
-/// <reference types="node" />
-
-import { spawn } from 'node:child_process'
-
-;(async () => {
-  try {
-    // Figma file key. Can be found in the URL of your Figma file:
-    // figma.com/design/FILE_KEY/...
-    const fileKey = ''
-
-    // Node ID in Figma file. Select an element and find 'node-id=...' in the URL
-    // or use "Copy link to selection" to see it in the URL.
-    const nodeId = ''
-
-    const child = spawn(
-      'npx',
-      ['dxt-figma-layout', fileKey, nodeId],
-      { stdio: 'inherit' }
-    )
-
-    child.on('exit', code => console.log('End:', code))
-  } catch (error) {
-    console.error('Error:', error)
-  }
-})()