@dxtmisha/scripts 0.7.2 → 0.7.7

package/src/classes/Design/DesignComponent.ts

@@ -2,9 +2,10 @@
 
 import {
   forEach,
-  isObjectNotArray, replaceComponentName,
+  isObjectNotArray,
+  replaceComponentName,
   toArray,
-  toKebabCase
+  toCamelCase
 } from '@dxtmisha/functional-basic'
 import { wikiDescriptions } from '@dxtmisha/wiki/media'
 import type { StorybookComponentsDescriptionItem } from '@dxtmisha/wiki'
@@ -19,6 +20,7 @@ import type { DesignReplace } from './DesignReplace'
 import {
   UI_DIR_COMPONENTS,
   UI_DIR_CONSTRUCTOR,
+  UI_DIR_DIST,
   UI_DIR_IN,
   UI_DIRS_COMPONENTS,
   UI_DIRS_LIBRARY,
@@ -33,24 +35,32 @@ const FILE_STYLE = 'styleToken.scss'
 const FILE_CLASS = 'DesignComponent.vue'
 const FILE_CLASS_AI = 'DesignComponentAiWiki.vue'
 const FILE_INDEX = 'index.ts'
+const FILE_INDEX_DTS = 'index.d.ts'
 const FILE_WIKI = 'wiki.ts'
+const FILE_WIKI_DATA = 'wikiData.ts'
 const FILE_STORIES = 'DesignComponent.stories.ts'
 const FILE_STORIES_DOCUMENTATION = 'DesignComponent.mdx'
 
 /**
- * Class for creating a component or updating data.
+ * Class for generating and updating all files and configurations associated with a design system component.
+ * It manages the lifecycle of properties, styles, Vue components, stories, and wiki documentation.
  *
- * Класс для создания компонента или обновления данных.
+ * Класс для генерации и обновления всех файлов и конфигураций, связанных с компонентом дизайн-системы.
+ * Управляет жизненным циклом свойств, стилей, компонентов Vue, историй и вики-документации.
  */
 export class DesignComponent extends DesignCommand {
   protected DIR_SAMPLE: string = 'component'
   protected dir: string[]
   protected propsType: DesignTypescriptProp[] | undefined
+  protected slotsType: DesignTypescriptProp[] | undefined
+  protected eventsType: DesignTypescriptProp[] | undefined
 
   /**
-   * Constructor
-   * @param command component name/ названия компонента
-   * @param options additional parameters/ дополнительные параметры
+   * Constructor for DesignComponent.
+   *
+   * Конструктор для DesignComponent.
+   * @param command component name or command identifier / название компонента или идентификатор команды
+   * @param options additional key-value parameters / дополнительные параметры ключ-значение
    */
   constructor(
     command: string,
@@ -82,6 +92,7 @@ export class DesignComponent extends DesignCommand {
       .makeMainAi()
       .makeIndex()
       .makeWiki()
+      .makeWikiData()
       .makeStories()
       .makeStoriesDocumentation()
       .makeFilePackage()
@@ -232,11 +243,27 @@ export class DesignComponent extends DesignCommand {
    */
   protected makeWiki(): this {
     const file = FILE_WIKI
+    const sample = this.readDefinable(file)
+
+    this.write(file, sample.get())
+    return this
+  }
+
+  /**
+   * This code generates the wikiData.ts.
+   *
+   * Генерация файла wikiData.ts.
+   */
+  protected makeWikiData(): this {
+    const file = FILE_WIKI_DATA
     const typeInfo = this.getPropsList()
+    const slotsInfo = this.getSlotsList()
+    const eventsInfo = this.getEventsList()
     const sample = this.readDefinable(file)
-    const props: string[] = []
 
     if (typeInfo) {
+      const props: string[] = []
+
       typeInfo
         .sort((a, b) => a.name.localeCompare(b.name))
         .forEach((prop) => {
@@ -259,6 +286,70 @@ export class DesignComponent extends DesignCommand {
       sample.replaceMark('propsList', props, ',')
     }
 
+    if (slotsInfo) {
+      const slots: string[] = []
+
+      slotsInfo
+        .sort((a, b) => a.name.localeCompare(b.name))
+        .forEach((slot) => {
+          const description = slot.description
+          const type = slot.type
+            .replace(/\(props: ([^)]+)\) => any/i, '$1')
+            .trim()
+
+          let item: string = ''
+
+          item += `{ name: '${slot.name}'`
+
+          if (description) {
+            item += `, description: \`${description}\``
+          }
+
+          if (
+            type
+            && type !== 'any'
+          ) {
+            item += `, properties: [{ name: 'props', type: '${type}' }]`
+          }
+
+          item += ` }`
+          slots.push(item)
+        })
+
+      sample.replaceMark('slotsList', slots, ',')
+    }
+
+    if (eventsInfo) {
+      const events: string[] = []
+
+      eventsInfo
+        .sort((a, b) => a.name.localeCompare(b.name))
+        .forEach((event) => {
+          const description = event.description
+          const type = event.type
+
+          let item: string = ''
+
+          item += `{ name: '${event.name}'`
+
+          if (description) {
+            item += `, description: \`${description}\``
+          }
+
+          if (
+            type
+            && type !== '[]'
+          ) {
+            item += `, properties: ${type}`
+          }
+
+          item += ` }`
+          events.push(item)
+        })
+
+      sample.replaceMark('eventsList', events, ',')
+    }
+
     this.write(file, sample.get())
     return this
   }
@@ -319,6 +410,65 @@ export class DesignComponent extends DesignCommand {
     return constructor ?? ''
   }
 
+  /**
+   * Getting the paths for the typescript compiler.
+   *
+   * Получение путей для компилятора typescript.
+   * @returns paths for the typescript compiler/ пути для компилятора typescript
+   */
+  private getTypescriptPaths(): string[] | undefined {
+    const root = PropertiesFile.getRootProject()
+    const componentName = this.getStructure().getComponentNameFirst()
+
+    if (root) {
+      return [
+        root,
+        UI_PROJECT_CONSTRUCTOR_NAME,
+        UI_DIR_DIST,
+        UI_DIR_CONSTRUCTOR,
+        componentName
+      ]
+    }
+
+    return undefined
+  }
+
+  /**
+   * Getting the path to the index file.
+   *
+   * Получение пути к файлу index.
+   */
+  private getTypescriptPathsIndex(): string | undefined {
+    const paths = this.getTypescriptPaths()
+
+    if (paths) {
+      return PropertiesFile.joinPath([
+        ...paths,
+        FILE_INDEX_DTS
+      ])
+    }
+
+    return undefined
+  }
+
+  /**
+   * Getting the path to the type file.
+   *
+   * Получение пути к файлу type.
+   */
+  private getTypescriptPathsType(): string | undefined {
+    const paths = this.getTypescriptPaths()
+
+    if (paths) {
+      return PropertiesFile.joinPath([
+        ...paths,
+        'types.d.ts'
+      ])
+    }
+
+    return undefined
+  }
+
   /**
    * Getting a list of all properties of a component.
    *
@@ -326,11 +476,11 @@ export class DesignComponent extends DesignCommand {
    */
   private getPropsList(): DesignTypescriptProp[] | undefined {
     if (!this.propsType) {
-      const root = PropertiesFile.getRootProject()
+      const paths = this.getTypescriptPathsIndex()
       const componentName = this.getStructure().getComponentNameFirst()
 
-      if (root) {
-        const ts = new DesignTypescript(
+      if (paths) {
+        const tsRead = new DesignTypescript(
           PropertiesFile.joinPath([
             PropertiesFile.getRoot(),
             UI_DIR_IN,
@@ -341,27 +491,63 @@ export class DesignComponent extends DesignCommand {
           ]),
           {
             paths: {
-              [`${UI_PROJECT_CONSTRUCTOR_FULL_NAME}/${componentName}`]: [
-                PropertiesFile.joinPath([
-                  root,
-                  UI_PROJECT_CONSTRUCTOR_NAME,
-                  UI_DIR_IN,
-                  UI_DIR_CONSTRUCTOR,
-                  componentName,
-                  FILE_INDEX
-                ])
-              ]
+              [`${UI_PROJECT_CONSTRUCTOR_FULL_NAME}/${componentName}`]: [paths]
             }
           }
         )
 
-        this.propsType = ts.getType(`${componentName}Props`)?.props
+        this.propsType = tsRead.getType(`${componentName}Props`)?.props
       }
     }
 
     return this.propsType
   }
 
+  /**
+   * Getting a list of all slots of a component.
+   *
+   * Получение списка всех слотов компонента.
+   */
+  private getSlotsList(): DesignTypescriptProp[] | undefined {
+    if (!this.slotsType) {
+      const types = this.getTypesFromConstructor('Slots')
+
+      if (types) {
+        this.slotsType = types
+      }
+    }
+
+    return this.slotsType
+  }
+
+  /**
+   * Getting a list of all events of a component.
+   *
+   * Получение списка всех событий компонента.
+   */
+  private getEventsList(): DesignTypescriptProp[] | undefined {
+    if (!this.eventsType) {
+      const types = this.getTypesFromConstructor('Emits')
+
+      if (types) {
+        this.eventsType = forEach(
+          types,
+          (item) => {
+            return {
+              name: item.name,
+              type: String(item.type)
+                .replace(/([^:,[\] ]+): ([^:,[\]]+)/gi, `{ name: '$1', type: '$2' }`)
+                .replace(/,{/gi, ', {'),
+              description: item.description
+            }
+          }
+        )
+      }
+    }
+
+    return this.eventsType
+  }
+
   /**
    * Returns the description of the component from the wiki
    *
@@ -396,6 +582,24 @@ export class DesignComponent extends DesignCommand {
     return []
   }
 
+  /**
+   * Getting the types from the constructor.
+   *
+   * Получение типов из конструктора.
+   * @param name name of the type/ имя типа
+   */
+  private getTypesFromConstructor(name: string): DesignTypescriptProp[] | undefined {
+    const paths = this.getTypescriptPathsType()
+    const componentName = this.getStructure().getComponentNameFirst()
+
+    if (paths) {
+      const tsRead = new DesignTypescript(paths)
+      return tsRead.getType(`${componentName}${name}`)?.props
+    }
+
+    return undefined
+  }
+
   /**
    * Converts the code to the component name.
    *
@@ -404,11 +608,12 @@ export class DesignComponent extends DesignCommand {
    */
   private toComponentName(code: string): string {
     const design = this.getStructure().getDesignFirst()
-    const name = this.getStructure().getFullComponentName()
+    const name = this.getStructure().getComponentName()
+    const fullName = this.getStructure().getFullComponentName()
 
     return code
-      .replace(/DesignComponent/g, name).trim()
-      .replace(/design-component/g, toKebabCase(name)).trim()
+      .replace(/DesignComponent/g, fullName).trim()
+      .replace(/design-component/g, `${toCamelCase(design)}-${toCamelCase(name)}`).trim()
       .replace(/<(\/?)Design/g, `<$1${design}`)
   }
 
@@ -588,7 +793,7 @@ export class DesignComponent extends DesignCommand {
     this.updatePackage(
       `exports|${name}`,
       {
-        types: `./dist/${this.getFullName()}.d.ts`,
+        types: `./dist/library/${this.getFullName()}.d.ts`,
         default: `./dist/${this.getFullName()}.js`
       }
     )
@@ -607,8 +812,10 @@ export class DesignComponent extends DesignCommand {
 
     PropertiesFile.writeByPath(
       [...UI_DIRS_LIBRARY, `${name}.ts`],
-      `export { default as ${name} } from '${dir}${name}.vue'
-export type { ${this.getName()}Props as ${name}Props } from '${dir}props'
+      `// This file is generated by a script, do not edit.
+// Этот файл генерируется скриптом, не редактировать.
+
+export * from '${dir}index.js'
 `
     )
 

package/src/classes/Design/DesignConstructor.ts

@@ -18,18 +18,22 @@ const FILE_CLASS = 'ConstructorsDesign.tsx'
 const FILE_INDEX = 'index.ts'
 
 /**
- * Class for generating files based on a constructor.
+ * Class for generating files and configurations based on a component's constructor.
+ * It automates the creation of property definitions, type files, styles, and integration logic for constructors.
  *
- * Класс для генерации файлов по конструктору.
+ * Класс для генерации файлов и конфигураций на основе конструктора компонента.
+ * Автоматизирует создание определений свойств, файлов типов, стилей и логики интеграции для конструкторов.
  */
 export class DesignConstructor extends DesignCommand {
   protected DIR_SAMPLE: string = UI_DIR_CONSTRUCTOR
   protected dir: string[]
 
   /**
-   * Constructor
-   * @param command component name/ названия компонента
-   * @param options additional parameters/ дополнительные параметры
+   * Constructor for DesignConstructor.
+   *
+   * Конструктор для DesignConstructor.
+   * @param command component name or command identifier / название компонента или идентификатор команды
+   * @param options additional key-value parameters / дополнительные параметры ключ-значение
    */
   constructor(
     command: string,

package/src/classes/Design/DesignConstructors.ts

@@ -9,14 +9,18 @@ import { DesignConstructor } from './DesignConstructor'
 import { UI_DIR_CONSTRUCTOR, UI_DIR_IN, UI_DIRS_LIBRARY, UI_FILE_STYLE_SCSS } from '../../config'
 
 /**
- * Class for managing design constructors.
+ * Class for orchestrating the generation and update of multiple design constructors.
+ * It manages the collective lifecycle of component constructors, including bulk updates and shared style generation.
  *
- * Класс для управления конструкторами дизайна.
+ * Класс для управления генерацией и обновлением нескольких конструкторов дизайна.
+ * Управляет коллективным жизненным циклом конструкторов компонентов, включая массовые обновления и генерацию общих стилей.
  */
 export class DesignConstructors {
   /**
-   * Constructor
-   * @param name component name/ название компонента
+   * Constructor for DesignConstructors.
+   *
+   * Конструктор для DesignConstructors.
+   * @param name optional specific component name to process / необязательное имя конкретного компонента для обработки
    */
   constructor(
     protected readonly name?: string

package/src/classes/Design/DesignFlags.ts

@@ -15,6 +15,13 @@ const DESIGN_FLAGS_FILE_PATH = ['.', '..', 'assets', DESIGN_FLAGS_FILE_NAME_ITEM
 const DESIGN_FLAGS_FILE_STYLE_NAME = [UI_DIR_IN, 'styles', 'flags.css']
 const DESIGN_FLAGS_CLASS_NAME = '.ui-sys-flags'
 
+/**
+ * Class for generating a sprite image and CSS mapping from a directory of flag icons.
+ * It automates the creation of a combined webp image and a CSS file with specific background-position utility classes.
+ *
+ * Класс для генерации спрайта и CSS-маппинга из директории иконок флагов.
+ * Автоматизирует создание комбинированного изображения webp и CSS-файла с утилитарными классами для позиционирования фона.
+ */
 export class DesignFlags {
   protected list: string[]
   protected data: DesignFlagsList = []
@@ -29,6 +36,15 @@ export class DesignFlags {
   protected readonly canvas: Canvas
   protected readonly context: SKRSContext2D
 
+  /**
+   * Constructor for DesignFlags.
+   *
+   * Конструктор для DesignFlags.
+   * @param dir path to the directory containing SVG icons / путь к директории с SVG-иконками
+   * @param width width of a single flag in the sprite / ширина одного флага в спрайте
+   * @param height height of a single flag in the sprite / высота одного флага в спрайте
+   * @param columns number of columns in the sprite grid / количество колонок в сетке спрайта
+   */
   constructor(
     protected readonly dir: string = 'src/assets/flags',
     protected readonly width: number = 96,

package/src/classes/Design/DesignReplace.ts

@@ -15,19 +15,23 @@ import { UI_KEY_CUSTOM } from '../../config'
 import { PropertiesConfig } from '../Properties/PropertiesConfig'
 
 /**
- * Class with basic replacement for templates.
+ * Engine for systematic text replacement within file templates based on component structure.
+ * It manages the transformation of labels (marks) into actual code segments, including property types, default values, and CSS class mappings.
  *
- * Класс с базовой заменой для шаблонов.
+ * Движок для систематической замены текста в шаблонах файлов на основе структуры компонента.
+ * Управляет преобразованием меток (marks) в реальные сегменты кода, включая типы свойств, значения по умолчанию и маппинг CSS-классов.
  */
 export class DesignReplace {
   protected readonly component: string
   protected readonly mark: string
 
   /**
-   * Constructor
-   * @param structure object for working with components/ объект для работы с компонентами
-   * @param mark метка для замена на имя
-   * @param sample property template/ шаблон свойства
+   * Constructor for DesignReplace.
+   *
+   * Конструктор для DesignReplace.
+   * @param structure object containing component metadata and design logic / объект, содержащий метаданные компонента и логику дизайна
+   * @param mark the identifier used in templates for replacement (e.g., 'button') / идентификатор, используемый в шаблонах для замены
+   * @param sample the raw template content to be processed / необработанное содержимое шаблона для обработки
    */
   constructor(
     protected structure: DesignStructure,

package/src/classes/Design/DesignStructure.ts

@@ -19,9 +19,11 @@ import {
 } from '../../config'
 
 /**
- * Class for processing structured components.
+ * Class for managing and resolving the data structure of a design system component.
+ * It serves as a central hub for reading component metadata, generating class mappings, and resolving style tokens.
  *
- * Класс для обработки структурированных компонентов.
+ * Класс для управления и разрешения структуры данных компонента дизайн-системы.
+ * Служит центральным узлом для чтения метаданных компонента, генерации маппингов классов и разрешения стилевых токенов.
  */
 export class DesignStructure {
   protected readonly component: string
@@ -30,11 +32,11 @@ export class DesignStructure {
   protected itemsClasses?: DesignStructureClassesList
   protected itemsStyles?: string[]
 
-  constructor(path: string)
-  constructor(design: string, component: string)
   /**
-   * Constructor
-   * @param component component name/ название компонента
+   * Constructor for DesignStructure.
+   *
+   * Конструктор для DesignStructure.
+   * @param component component name or identifier / название или идентификатор компонента
    */
   constructor(
     component?: string

package/src/classes/Design/DesignStructureClasses.ts

@@ -14,16 +14,20 @@ import {
 } from '../../types/designTypes'
 
 /**
- * A class for getting a list of classes of components.
+ * Class for resolving and generating a hierarchical list of CSS classes for a component.
+ * It recursively parses component properties to identify subclasses and build BEM-compliant class names.
  *
- * Класс для получения списка классов компонентов.
+ * Класс для разрешения и генерации иерархического списка CSS-классов для компонента.
+ * Рекурсивно анализирует свойства компонента для идентификации подклассов и построения имен классов, соответствующих BEM.
  */
 export class DesignStructureClasses extends DesignStructureItemAbstract<DesignStructureClassesList> {
   protected data: DesignStructureClassesList = []
 
   /**
-   * Constructor
-   * @param component component name/ название компонента
+   * Constructor for DesignStructureClasses.
+   *
+   * Конструктор для DesignStructureClasses.
+   * @param component component name used as the base for class generation / имя компонента, используемое в качестве базы для генерации классов
    */
   constructor(
     component: string

package/src/classes/Design/DesignStructureItemAbstract.ts

@@ -5,6 +5,13 @@ import { PropertiesConfig } from '../Properties/PropertiesConfig'
 
 import type { PropertyItemsItem } from '../../types/propertyTypes'
 
+/**
+ * Base abstract class for structural component items.
+ * It provides the foundation for resolving component properties and metadata from the design system's central storage.
+ *
+ * Базовый абстрактный класс для структурных элементов компонента.
+ * Предоставляет основу для разрешения свойств и метаданных компонента из центрального хранилища дизайн-системы.
+ */
 export abstract class DesignStructureItemAbstract<D> {
   protected properties: Properties
   protected items?: PropertyItemsItem
@@ -12,8 +19,10 @@ export abstract class DesignStructureItemAbstract<D> {
   protected abstract data: D
 
   /**
-   * Constructor
-   * @param component component name/ название компонента
+   * Constructor for DesignStructureItemAbstract.
+   *
+   * Конструктор для DesignStructureItemAbstract.
+   * @param component component name for which the structure is being resolved / имя компонента, для которого разрешается структура
    */
   protected constructor(
     protected readonly component: string

package/src/classes/Design/DesignStructureRead.ts

@@ -19,9 +19,11 @@ import type {
 import { UI_PROPERTY_FOR_PROPS } from '../../config'
 
 /**
- * Class for processing dependency properties of the component.
+ * Engine for parsing and resolving component property dependencies and states.
+ * It processes the raw property metadata to identify interactive states, link classes, and compile all possible values for code generation.
  *
- * Класс для обработки зависимости свойств у компонента.
+ * Движок для парсинга и разрешения зависимостей свойств и состояний компонента.
+ * Обрабатывает сырые метаданные свойств для идентификации интерактивных состояний, связанных классов и компиляции всех возможных значений для генерации кода.
  */
 export class DesignStructureRead extends DesignStructureItemAbstract<DesignStructureList> {
   protected states: DesignStructureStateList
@@ -29,8 +31,10 @@ export class DesignStructureRead extends DesignStructureItemAbstract<DesignStruc
   protected data: DesignStructureList = {}
 
   /**
-   * Constructor
-   * @param component component name/ название компонента
+   * Constructor for DesignStructureRead.
+   *
+   * Конструктор для DesignStructureRead.
+   * @param component component name whose properties are being resolved / имя компонента, свойства которого разрешаются
    */
   constructor(
     component: string

package/src/classes/Design/DesignStructureStyles.ts

@@ -4,16 +4,20 @@ import { StylesProperties } from '../Styles/StylesProperties'
 import { DesignStructureItemAbstract } from './DesignStructureItemAbstract'
 
 /**
- * Class for processing styles from tokens for the component.
+ * Engine for compiling component-specific styles from design system tokens.
+ * It coordinates the transformation of structural metadata into CSS-in-JS style rules using the global theme environment.
  *
- * Класс для обработки стилей из токенов для компонента.
+ * Движок для компиляции специфичных для компонента стилей из токенов дизайн-системы.
+ * Координирует преобразование структурных метаданных в правила стилей CSS-in-JS с использованием глобального тематического окружения.
  */
 export class DesignStructureStyles extends DesignStructureItemAbstract<string[]> {
   protected data: string[]
 
   /**
-   * Constructor
-   * @param component component name/ название компонента
+   * Constructor for DesignStructureStyles.
+   *
+   * Конструктор для DesignStructureStyles.
+   * @param component component name for which styles are being compiled / имя компонента, для которого компилируются стили
    */
   constructor(
     component: string