@dxtmisha/scripts 0.11.8 → 1.0.0

package/src/classes/Properties/PropertiesKeys.ts

@@ -1,121 +0,0 @@
-// export:none
-
-import { toCamelCase } from '@dxtmisha/functional-basic'
-
-import { PropertiesConfig } from './PropertiesConfig'
-import { PropertiesTypes } from './PropertiesTypes'
-
-import { type PropertyItem } from '../../types/propertyTypes'
-
-/**
- * Parser and transformer for property key semantics.
- * This static utility class handles the identification of special system keys (like metadata or internal references) and orchestrates the transformation of raw key names into normalized, context-aware tokens (e.g., prepending media types or converting to camelCase).
- *
- * Парсер и трансформер семантики ключей свойств.
- * Этот статический вспомогательный класс обрабатывает идентификацию специальных системных ключей (таких как метаданные или внутренние ссылки) и координирует преобразование необработанных имен ключей в нормализованные токены с учетом контекста (например, добавление типов медиа или преобразование в camelCase).
- */
-export class PropertiesKeys {
-  /**
-   * Identifies if a key is a protected system metadata key or an internal reference.
-   * Special keys include 'value', 'type', 'description', and any key starting with an underscore (internal engine states).
-   *
-   * Определяет, является ли ключ защищенным системным ключом метаданных или внутренней ссылкой.
-   * Специальные ключи включают 'value', 'type', 'description' и любой ключ, начинающийся с подчеркивания (внутренние состояния движка).
-   * @param key the key name to verify / название ключа для проверки
-   */
-  static isSpecialKey(key: string | number): key is keyof PropertyItem {
-    return typeof key === 'string' && (
-      ['value', 'type', 'description'].indexOf(key) !== -1
-      || Boolean(key.match(/^_/))
-    )
-  }
-
-  /**
-   * Checks whether the name is complete.
-   *
-   * Проверяет, является ли название полным.
-   * @param name key name/ название ключа
-   */
-  static isFull(name: string): boolean {
-    return Boolean(name.match(/^=|\|=/))
-  }
-
-  /**
-   * Checks if the property is suitable for splitting.
-   *
-   * Проверяет, подходит ли свойство для разделения.
-   * @param name property names/ названия свойств
-   * @private
-   */
-  static isSeparator(name: string): boolean {
-    return Boolean(name.match(PropertiesConfig.getSeparator()))
-  }
-
-  /**
-   * Normalizes a raw key name by removing metadata prefixes and applying casing rules.
-   * Strips internal type symbols and leading pipes, then optionally converts the result to camelCase (unless the name is a path separator).
-   *
-   * Нормализует необработанное имя ключа, удаляя префиксы метаданных и применяя правила регистра.
-   * Очищает внутренние символы типов и ведущие вертикальные черты, затем опционально преобразует результат в camelCase (если имя не является разделителем пути).
-   * @param name the raw key name / необработанное имя ключа
-   * @param camelCase whether to apply camelCase transformation / нужно ли применять преобразование в camelCase
-   */
-  static getName(name: string, camelCase = true): string {
-    const newName = name
-      .replace(PropertiesTypes.getExpSymbols(), '$2')
-      .replace(/^[|]/, '')
-
-    if (
-      this.isSeparator(newName)
-      || !camelCase
-    ) {
-      return newName
-    }
-
-    return toCamelCase(newName)
-  }
-
-  /**
-   * Transformed key name by its type.
-   *
-   * Преобразованное название ключа по его типу.
-   * @param key property name/ название свойства
-   * @param type property type/ тип свойства
-   */
-  static reKey(
-    key: string,
-    type?: PropertyItem['_type']
-  ): string {
-    const name = this.getName(key)
-
-    if (type) {
-      if (
-        PropertiesTypes.isMedia(type)
-        && !name.match(/^media[A-Z]/)
-      ) {
-        return toCamelCase(`${type}-${name}`)
-      }
-
-      if (
-        PropertiesTypes.isContainer(type)
-        && !name.match(/^container[A-Z]/)
-      ) {
-        return toCamelCase(`${type}-${name}`)
-      }
-
-      if (
-        PropertiesTypes.isScss(type)
-      ) {
-        return `&${this.getName(key, false)}`
-      }
-
-      if (
-        PropertiesTypes.isRoot(type)
-      ) {
-        return this.getName(key, false)
-      }
-    }
-
-    return name
-  }
-}

package/src/classes/Properties/PropertiesMain.ts

@@ -1,138 +0,0 @@
-// export:none
-
-import { forEach, isFilled, isObjectNotArray } from '@dxtmisha/functional-basic'
-
-import { PropertiesPath } from './PropertiesPath'
-import { PropertiesTool } from './PropertiesTool'
-
-import { PropertiesConvector } from './PropertiesConvector'
-import { PropertiesStandard } from './PropertiesStandard'
-import { PropertiesImport } from './PropertiesImport'
-import { PropertiesSeparator } from './PropertiesSeparator'
-import { PropertiesWrap } from './PropertiesWrap'
-
-import type {
-  PropertyItem,
-  PropertyList
-} from '../../types/propertyTypes'
-
-const DIR_NAME = 'main'
-
-/**
- * Orchestrator for global design token transformation.
- * This class serves as the primary engine for loading, validating, and normalizing "main" tokens across all supported designs. It coordinates a multi-stage pipeline—including semantic conversion, reference import, and structural wrapping—to synthesize a unified property tree ready for consumption by external builders.
- *
- * Оркестратор глобальной трансформации токенов дизайна.
- * Этот класс служит основным движком для загрузки, валидации и нормализации «основных» (main) токенов во всех поддерживаемых дизайнах. Он координирует многоэтапный конвейер — включая семантическую конвертацию, импорт ссылок и структурную обертку — для синтеза унифицированного дерева свойств, готового к использованию внешними строителями.
- */
-export class PropertiesMain {
-  /**
-   * Constructor
-   * @param path object of the class for working with paths/ объект класса для работы с путями
-   */
-  constructor(
-    private readonly path: PropertiesPath
-  ) {
-  }
-
-  /**
-   * Executes the full transformation pipeline for all main design tokens.
-   * Discovers token files via the path manager, then sequentially applies reading, conversion, standardization, link resolution, and structural wrapping for every design entry.
-   *
-   * Выполняет полный конвейер трансформации для всех основных токенов дизайна.
-   * Обнаруживает файлы токенов через менеджер путей, затем последовательно применяет чтение, конвертацию, стандартизацию, разрешение ссылок и структурную обертку для каждой записи дизайна.
-   */
-  get(): PropertyList {
-    return this.path.toAll(DIR_NAME, (
-      path,
-      _,
-      design
-    ) => {
-      let properties = PropertiesTool.readFile(design, path)
-
-      if (isFilled(properties)) {
-        PropertiesConvector.to(properties)
-
-        properties = PropertiesStandard.to({ [design]: properties })
-
-        if (path) {
-          properties = new PropertiesImport(properties, path).to()
-        }
-
-        if (PropertiesSeparator.is(properties)) {
-          properties = PropertiesSeparator.to(properties)
-          PropertiesWrap.to(properties)
-        }
-      }
-
-      return properties ?? {}
-    }) as PropertyList
-  }
-
-  /**
-   * Synchronizes global tokens with a provided settings cluster.
-   * Retrieves the full set of main tokens and deeply merges internal state flags from the settings list into the corresponding nodes of the global tree.
-   *
-   * Синхронизирует глобальные токены с предоставленным кластером настроек.
-   * Получает полный набор основных токенов и глубоко объединяет флаги внутреннего состояния из списка настроек в соответствующие узлы глобального дерева.
-   * @param list the settings cluster to apply / кластер настроек для применения
-   */
-  getBySettings(list: PropertyList): PropertyList {
-    const data = this.get()
-
-    forEach(list, (designItems, design) => {
-      const dataDesign = data?.[design]?.value
-
-      if (
-        dataDesign
-        && isObjectNotArray(dataDesign)
-        && isObjectNotArray(designItems.value)
-      ) {
-        forEach(designItems.value, (componentItems, component) => {
-          const dataComponent = dataDesign?.[component]?.value
-
-          if (
-            dataComponent
-            && isObjectNotArray(dataComponent)
-            && isObjectNotArray(componentItems.value)
-          ) {
-            forEach(componentItems.value, (item, name) => {
-              this.copySettings(
-                item,
-                dataComponent?.[name]
-              )
-            })
-          }
-        })
-      }
-    })
-
-    return data
-  }
-
-  /**
-   * We copy the settings.
-   *
-   * Копируем настройки.
-   * @param item element with settings/ элемент с настройками
-   * @param itemCopy element for copying settings/ элемент для копирования настроек
-   */
-  protected copySettings(
-    item: PropertyItem,
-    itemCopy?: PropertyItem
-  ): this {
-    if (itemCopy) {
-      forEach(item, (value, property: keyof PropertyItem) => {
-        if (
-          property.match(/^_/)
-          && property in itemCopy
-          && itemCopy[property] !== value
-        ) {
-          itemCopy[property] = value as never
-        }
-      })
-    }
-
-    return this
-  }
-}

package/src/classes/Properties/PropertiesPalette.ts

@@ -1,149 +0,0 @@
-// export:none
-
-import { forEach, getColumn, isObjectNotArray, toCamelCase } from '@dxtmisha/functional-basic'
-
-import { PropertiesItems } from './PropertiesItems'
-
-import {
-  PropertyCategory,
-  type PropertyItem,
-  PropertyKey,
-  type PropertyPaletteList,
-  type PropertyPaletteUsed,
-  PropertyType
-} from '../../types/propertyTypes'
-
-/**
- * Manager for design palette and color saturation.
- * This class handles the extraction of available shade levels (saturation steps) and tracks the usage of palette colors across the design system. It facilitates the mapping between functional variables and their underlying palette definitions, ensuring that generated styles correctly reference the intended theme colors.
- *
- * Менеджер палитры дизайна и насыщенности цветов.
- * Этот класс обрабатывает извлечение доступных уровней оттенков (шагов насыщенности) и отслеживает использование цветов палитры в системе дизайна. Он упрощает сопоставление функциональных переменных с их базовыми определениями в палитре, гарантируя, что сгенерированные стили правильно ссылаются на нужные цвета темы.
- */
-export class PropertiesPalette {
-  /**
-   * Constructor
-   * @param items
-   */
-
-  constructor(private items: PropertiesItems) {
-  }
-
-  /**
-   * Retrieves a list of available saturation levels (shades) grouped by design.
-   * Scans the token cluster for items categorized as 'shade' and returns their resolved value structures.
-   *
-   * Возвращает список доступных уровней насыщенности (оттенков), сгруппированных по дизайну.
-   * Сканирует кластер токенов на наличие элементов, классифицированных как 'shade', и возвращает их разрешенные структуры значений.
-   */
-  getShade(): PropertyPaletteList {
-    return forEach(this.items.findCategory(PropertyCategory.shade), ({
-      design,
-      value
-    }) => {
-      if (isObjectNotArray(value)) {
-        return {
-          design,
-          value: getColumn(value, 'value')
-        }
-      }
-
-      return undefined
-    }) as PropertyPaletteList
-  }
-
-  /**
-   * Generates a report of all palette colors currently utilized in functional variables.
-   * Iterates through the entire property tree to identify variables referencing palette colors and maps them to their corresponding CSS variable names.
-   *
-   * Генерирует отчет обо всех цветах палитры, используемых в данный момент в функциональных переменных.
-   * Итерирует по всему дереву свойств для идентификации переменных, ссылающихся на цвета палитры, и сопоставляет их с соответствующими именами CSS-переменных.
-   */
-  getUsed(): PropertyPaletteUsed[] {
-    const list = this.getList()
-    const data: PropertyPaletteUsed[] = []
-
-    this.items.each(({
-      design,
-      component,
-      value,
-      item,
-      parents
-    }) => {
-      if (
-        component
-        && typeof value === 'string'
-        && item?.[PropertyKey.variable] === PropertyType.var
-        && item?.[PropertyKey.category] !== PropertyCategory.color
-        && item?.[PropertyKey.name]
-      ) {
-        const focusValue = this.getFocusUsed(list, design, component, value)
-
-        if (focusValue) {
-          const name = item[PropertyKey.name]
-          const code = data.find(code => code.name === name)
-          const theme = parents.find(parent => parent.item[PropertyKey.category] === 'theme')?.name || 'basic'
-          const color = `--${design}-palette-${toCamelCase(`${theme}-${focusValue.match(/\.([^.{}]+)}/)?.[1]}`)}`
-
-          if (code) {
-            code.value.push(color)
-          } else {
-            data.push({
-              name,
-              value: [color]
-            })
-          }
-        }
-      }
-    })
-
-    return data
-  }
-
-  getFocusUsed(
-    list: PropertyItem['value'][],
-    design: string,
-    component: string,
-    value: string
-  ): string | undefined {
-    const data = this.items.getLink(
-      design,
-      component,
-      value
-    )
-
-    if (list.indexOf(data) !== -1) {
-      return value
-    }
-
-    const item = this.items.getInfo(data)
-
-    if (
-      item
-      && item.design === design
-      && typeof item.component === 'string'
-      && typeof item.value === 'string'
-    ) {
-      return this.getFocusUsed(
-        list,
-        item.design,
-        item.component,
-        item.value
-      )
-    }
-
-    return undefined
-  }
-
-  /**
-   * Getting a list of all colors.
-   *
-   * Получение списка всех цветов.
-   */
-  private getList(): PropertyItem['value'][] {
-    return forEach(
-      this.items.findCategory(PropertyCategory.color),
-      ({ value }) => value
-    )
-  }
-}

package/src/classes/Properties/PropertiesPath.ts

@@ -1,193 +0,0 @@
-// export:none
-
-import { replaceRecursive, toKebabCase } from '@dxtmisha/functional-basic'
-
-import { PropertiesConfig } from './PropertiesConfig'
-import { PropertiesTool } from './PropertiesTool'
-import { PropertiesFile } from './PropertiesFile'
-import { PropertiesCache } from './PropertiesCache'
-
-import {
-  type PropertyListOrData
-} from '../../types/propertyTypes'
-
-import { UI_DIRS_COMPONENTS, UI_DIRS_TOKENS } from '../../config'
-
-export type PropertiesPathItem = {
-  design: string
-  paths?: string[]
-  pathsComponent?: string[]
-}
-
-export type PropertiesPathList = PropertiesPathItem[]
-
-const DIR_CACHE = 'read'
-
-/**
- * Directory and path resolver for multi-design token environments.
- * This class translates abstract design names into concrete filesystem paths for global tokens and component-specific settings. It coordinates the cross-platform path discovery flow and provided cached traversal mechanisms (`to`, `toAll`) to efficiently process token files across the entire project structure.
- *
- * Резолвер директорий и путей для сред с несколькими дизайнами токенов.
- * Этот класс преобразует абстрактные названия дизайнов в конкретные пути файловой системы для глобальных токенов и настроек компонентов. Он координирует процесс обнаружения путей на разных платформах и предоставляет механизмы кэшированного обхода (`to`, `toAll`) для эффективной обработки файлов токенов во всей структуре проекта.
- */
-export class PropertiesPath {
-  private readonly paths: PropertiesPathList
-  private readonly constructorType: boolean = false
-
-  /**
-   * Constructor
-   * @param designs list of design names corresponding to folder names/
-   * список названий дизайнов, соответствующих названиям папок
-   */
-  constructor(
-    private designs: string[]
-  ) {
-    this.paths = []
-
-    designs.forEach((design) => {
-      this.paths.push({
-        design: toKebabCase(design),
-        paths: this.getDir(design),
-        pathsComponent: this.getDirComponents(design)
-      })
-    })
-
-    if (
-      this.paths?.[1]
-      && PropertiesTool.isConstructor(this.paths?.[1].design)
-    ) {
-      delete this.paths[1]
-      this.constructorType = true
-    }
-  }
-
-  isConstructor(): boolean {
-    return this.constructorType
-  }
-
-  /**
-   * Returns the names of available designs.
-   *
-   * Возвращает названия доступных дизайнов.
-   */
-  getDesigns(): string[] {
-    return this.designs
-  }
-
-  /**
-   * Gets a list of available paths to the file of global component settings.
-   *
-   * Получает список доступных путей к файлу глобальных настроек компонента.
-   * @param name design name/ название дизайна
-   */
-  getPath(name: string): PropertiesPathItem | undefined {
-    return this.paths.find(item => item.design === name)
-  }
-
-  /**
-   * List of available paths.
-   *
-   * Список доступных путей.
-   */
-  getPaths(): PropertiesPathList {
-    return this.paths
-  }
-
-  /**
-   * Executes a cached transformation for a specific design and token group.
-   * Resolves paths for the target design, executes the provided callback to process the data, and caches the result for future performance. Ideal for processing individual themes or component layers within a theme.
-   *
-   * Выполняет кэшированную трансформацию для конкретного дизайна и группы токенов.
-   * Разрешает пути для целевого дизайна, выполняет предоставленный callback для обработки данных и кэширует результат. Идеально подходит для обработки отдельных тем или слоев компонентов внутри темы.
-   * @param name unique name for the processing group (used as cache key) / уникальное имя группы обработки (используется как ключ кэша)
-   * @param design names of the design to process / названия дизайна для обработки
-   * @param callback function that receives resolved paths and returns processed data / функция, которая получает разрешенные пути и возвращает обработанные данные
-   */
-  to(
-    name: string,
-    design: string,
-    callback: (
-      path: string[] | undefined,
-      pathsComponent: string[] | undefined,
-      design: string
-    ) => PropertyListOrData
-  ): PropertyListOrData {
-    return PropertiesCache.get<PropertyListOrData>([DIR_CACHE, name], `${name}-${design}`, () => {
-      let data: PropertyListOrData = {}
-      const item = this.getPath(design)
-
-      if (item) {
-        data = replaceRecursive(
-          data,
-          callback(
-            item.paths,
-            item.pathsComponent,
-            design
-          )
-        )
-      }
-
-      return data
-    })
-  }
-
-  /**
-   * Orchestrates a global cached transformation across all registered designs.
-   * Iterates through every design defined in the constructor, processes its tokens using the provided callback, and merges the results into a single unified property tree.
-   *
-   * Координирует глобальную кэшированную трансформацию для всех зарегистрированных дизайнов.
-   * Итерирует по каждому дизайну, определенному в конструкторе, обрабатывает его токены с помощью предоставленного callback и объединяет результаты в единое унифицированное дерево свойств.
-   * @param name unique name for the global processing group / уникальное имя глобальной группы обработки
-   * @param callback function for processing individual designs / функция для обработки отдельных дизайнов
-   */
-  toAll(
-    name: string,
-    callback: (
-      path: string[] | undefined,
-      pathsComponent: string[] | undefined,
-      design: string
-    ) => PropertyListOrData
-  ): PropertyListOrData {
-    return PropertiesCache.get<PropertyListOrData>([DIR_CACHE], name, () => {
-      let data: PropertyListOrData = {}
-
-      this.designs.forEach((design) => {
-        data = replaceRecursive(data, this.to(name, design, callback))
-      })
-
-      return data
-    })
-  }
-
-  /**
-   * Returns the path to a file by design name.
-   *
-   * Возвращает путь к файлу по названию дизайна.
-   * @param name design name/ название дизайна
-   */
-  private getDir(name: string): string[] | undefined {
-    if (PropertiesTool.isConstructor(name)) {
-      return undefined
-    }
-
-    return [PropertiesFile.getRoot(), ...UI_DIRS_TOKENS]
-  }
-
-  /**
-   * Returns the path to a file by design name.
-   *
-   * Возвращает путь к файлу по названию дизайна.
-   * @param name design name/ название дизайна
-   */
-  private getDirComponents(name: string): string[] | undefined {
-    if (PropertiesTool.isConstructor(name)) {
-      return undefined
-    }
-
-    return [
-      PropertiesFile.getRoot(),
-      ...UI_DIRS_COMPONENTS,
-      PropertiesConfig.getProjectName()
-    ]
-  }
-}