@dxtmisha/wiki 0.39.2 → 0.39.3

package/src/media/functional/ui/properties/values/values.vi.mdx

@@ -0,0 +1,103 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/vi/# UI/properties/# Giá trị'/>
+
+# Làm việc với giá trị (Value)
+
+Trường `value` trong `properties.json` xác định nội dung cuối cùng của một thuộc tính (màu sắc, kích thước, đường dẫn, v.v.). Nội dung của `value` có thể là các giá trị hằng số (literals), các tham chiếu động tới các token khác hoặc các dấu hiệu hệ thống (markers).
+
+### Hằng số và Kiểu dữ liệu
+Hệ thống hỗ trợ các kiểu dữ liệu JSON tiêu chuẩn:
+- **Chuỗi (Strings)**: `"12px"`, `"relative"`, `"none"`.
+- **Số (Numbers)**: `24`, `0.5` (tự động chuyển thành chuỗi khi biên dịch).
+- **Màu sắc**: Hỗ trợ các định dạng HEX:
+    - `#FFF` / `#FFFFFF` — màu tiêu chuẩn.
+    - `#FFFFFF80` — màu có kênh alpha (8 ký tự).
+
+### Tham chiếu và nhãn hệ thống (`{...}`)
+Bạn có thể trích xuất giá trịของ các thuộc tính khác bằng cách sử dụng dấu ngoặc nhọn. Điều này cho phép tạo ra sự phụ thuộc giữa các token.
+
+#### Quy tắc phân giải đường dẫn:
+1. **Đường dẫn tuyệt đối**: `{design.component.property}` — chỉ định đầy đủ từ gốc.
+2. **Đường dẫn tương đối (Tự động Design)**: `{primary-color}`. Nếu phân đoạn đầu tiên của đường dẫn không phải là tên design đã đăng ký, hệ thống sẽ tự động thêm tên design hiện tại (`{current-design.primary-color}`).
+3. **Phân cấp**: Hỗ trợ phân cấp vô hạn thông qua dấu chấm: `{base.spacing.small}`.
+
+#### Nhãn đặc biệt (Shortcuts):
+Các trình giữ chỗ đặc biệt được sử dụng để rút ngắn đường dẫn trong các tham chiếu:
+- `?` — được thay thế bằng `[design_hiện_tại].`.
+- `??` — được thay thế bằng `[design_hiện_tại].[component_hiện_tại].`.
+
+**Ví dụ:**
+```json
+{
+  "button": {
+    "color": "{?primary}",          // Phân giải thành {d1.primary}
+    "padding": "{??base-padding}"   // Phân giải thành {d1.button.base-padding}
+  }
+}
+```
+
+Các nhãn này giúp viết mã cấu hình có khả năng di động cao, không bị hỏng khi đổi tên thiết kế hoặc thành phần.
+
+#### Biểu thức và nội dung hỗn hợp:
+Trường `value` có thể chứa văn bản tùy ý có chứa một hoặc nhiều tham chiếu `{...}` bên trong. Hệ thống sẽ tìm và giải quyết từng tham chiếu trong khi vẫn giữ nguyên phần văn bản còn lại.
+
+Điều này cho phép sử dụng các tham chiếu bên trong các hàm CSS (ví dụ: `calc()`) hoặc kết hợp chúng với các biến CSS gốc.
+
+**Ví dụ:**
+```json
+{
+  "button": {
+    "padding": "var(--sys-height) * {sys.spacing.adaptive.md}"
+  }
+}
+```
+
+### Dấu hiệu "Giá trị đầy đủ" (`=`)
+Nếu một giá trị bắt đầu bằng ký tự `=`, trình biên dịch sẽ coi đó là "giá trị đầy đủ" (full value). Giá trị sẽ được truyền vào SCSS "nguyên bản" mà không qua bất kỳ quá trình xử lý tự động nào khác.
+
+Điều này hữu ích cho các hàm CSS phức tạp hoặc khi cần truyền các đường dẫn thô.
+
+**Ví dụ sử dụng:**
+```json
+{
+  "button": {
+    "color": "{?primary}",           // Tham chiếu qua nhãn design
+    "padding": "{??base-padding}",   // Tham chiếu qua nhãn component
+    "width": "=calc(100% - 20px)",   // Giá trị đầy đủ (không xử lý)
+    "border": "1px solid #00000030"  // HEX có độ trong suốt
+  }
+}
+```
+
+### Các tham số Meta bổ sung
+Để kiểm soát giá trị chính xác hơn, có thể sử dụng các cờ dịch vụ đặc biệt (bắt đầu bằng `_`):
+
+- `_important: boolean` — thêm chỉ thị `!important` vào thuộc tính trong CSS.
+- `_fullValue: boolean` — tương đương lập trình của dấu hiệu `=`. Vô hiệu hóa việc tự động thêm đơn vị (`px`) và giải quyết tham chiếu `{}`.
+- `_replace: object` — cho phép thực hiện thay thế văn bản trong giá trị cuối cùng bằng biểu thức chính quy. Chấp nhận một đối tượng `{ pattern, flags, replace }`.
+- `_modification: boolean` — kiểm soát xem thuộc tính có thể được sửa đổi trong SCSS hay không (mặc định là `true`). Nếu đặt thành `false`, thuộc tính được coi là tĩnh.
+
+**Ví dụ sử dụng:**
+```json
+{
+  "button": {
+    "width": { 
+      "value": "100%", 
+      "_important": true      // Kết quả: width: 100% !important;
+    },
+    "padding": { 
+      "value": "16px", 
+      "_replace": {           // Kết quả: padding: 16rem;
+        "pattern": "px", 
+        "replace": "rem", 
+        "flags": "g" 
+      }
+    },
+    "height": { 
+      "value": "calc(100vh - 20px)", 
+      "_fullValue": true      // Kết quả: height: calc(100vh - 20px);
+    }
+  }
+}
+```

package/src/classes/WikiStorybook.ts

@@ -1,353 +0,0 @@
-import { forEach, Geo, isObjectNotArray, toCamelCase } from '@dxtmisha/functional'
-
-import { WikiStorybookItem } from './WikiStorybookItem'
-import { WikiStorybookProp } from './WikiStorybookProp'
-
-import {
-  type StorybookArgs,
-  type StorybookArgsToDescription,
-  type StorybookArgsToItem,
-  type StorybookArgsToList,
-  type StorybookArgsToPossibilities,
-  type StorybookComponentsDescription,
-  type StorybookComponentsDescriptionItem,
-  type StorybookComponentsDescriptionStory,
-  type StorybookProp,
-  type StorybookProps
-} from '../types/storybookTypes'
-
-/**
- * Class representing a Storybook wiki
- *
- * Класс, представляющий wiki для Storybook
- */
-export class WikiStorybook {
-  protected list: WikiStorybookItem[]
-
-  /**
-   * Creates a new instance of WikiStorybook
-   *
-   * Создает новый экземпляр WikiStorybook
-   * @param component - Component name/ Название компонента
-   * @param props - Properties for the component/ свойства для компонента
-   * @param defaults - Default values for the component/ значения по умолчанию для компонента
-   * @param wikiDesign - Design values for the wiki/ значения дизайна для wiki
-   * @param wikiBasic - Basic values for the wiki/ базовые значения для wiki
-   * @param wikiDescriptions - Component descriptions for the wiki/ описания компонентов для wiki
-   */
-  constructor(
-    protected readonly component: string,
-    protected readonly props: StorybookProps,
-    protected readonly defaults: Record<string, any>,
-    protected readonly wikiDesign: StorybookArgsToList = {},
-    protected readonly wikiBasic: StorybookArgsToList = {},
-    protected readonly wikiDescriptions: StorybookComponentsDescription = []
-  ) {
-    this.list = this.initList()
-  }
-
-  /**
-   * Returns the name of the component
-   *
-   * Возвращает имя компонента
-   */
-  getName(): string {
-    return this.component
-  }
-
-  /**
-   * Returns the properties wiki for the component
-   *
-   * Возвращает wiki свойств для компонента
-   * @return The properties wiki for the component/ wiki свойств для компонента
-   */
-  getWiki(): StorybookArgs {
-    return this.initPropsWiki()
-  }
-
-  /**
-   * Returns the wiki object for the component
-   *
-   * Возвращает объект wiki для компонента
-   * @return The wiki object for the component/ объект wiki для компонента
-   */
-  getWikiObject(): WikiStorybookProp[] {
-    return forEach(
-      this.getWiki(),
-      (item, name) => {
-        if (item) {
-          return new WikiStorybookProp(name, item)
-        }
-      }
-    ) as WikiStorybookProp[]
-  }
-
-  /**
-   * Returns the description of the component from the wiki
-   *
-   * Возвращает описание компонента из wiki
-   * @return The description of the component/ описание компонента
-   */
-  getDescription(): string {
-    return this.toDescriptionText(this.getDescriptionItem()?.description)
-  }
-
-  /**
-   * Returns the possibilities of the component from the wiki
-   *
-   * Возвращает возможности компонента из wiki
-   * @return A list of possibilities for the component/ список возможностей для компонента
-   */
-  getPossibilities(): string[] {
-    return this.toPossibilitiesText(this.getDescriptionItem()?.possibilities)
-  }
-
-  /**
-   * Returns the values of the wiki items
-   *
-   * Возвращает значения элементов wiki
-   * @return An object containing the values of the wiki items/ объект, содержащий значения элементов wiki
-   */
-  getValues(): Record<string, any> {
-    const values: Record<string, any> = {}
-
-    this.list.forEach((item) => {
-      values[item.getName()] = item.getValue()
-    })
-
-    return values
-  }
-
-  /**
-   * Returns the filtered values of the wiki items
-   *
-   * Возвращает отфильтрованные значения элементов wiki
-   * @return A list of objects containing the filtered values of the wiki items/
-   * список объектов, содержащих отфильтрованные значения элементов wiki
-   */
-  getFilteredValues(): Record<string, any> {
-    const values: Record<string, any> = {}
-
-    forEach(
-      this.getValues(),
-      (value, key) => {
-        if (value !== undefined) {
-          values[key] = value
-        }
-      }
-    )
-
-    return values
-  }
-
-  /**
-   * Returns a Storybook item by its ID
-   *
-   * Возвращает элемент Storybook по его ID
-   * @param id - The ID of the story/ ID истории
-   */
-  getStoryItem(id: string): StorybookComponentsDescriptionStory | undefined {
-    const item = this.getDescriptionItem()
-
-    if (
-      item
-      && item.stories
-    ) {
-      return item.stories.find(story => story.id === id)
-    }
-
-    return undefined
-  }
-
-  /**
-   * Returns the name of the story by its ID
-   *
-   * Возвращает имя истории по ее ID
-   * @param id - The ID of the story/ ID истории
-   */
-  getStoryName(id: string): string | undefined {
-    return this.toDescriptionText(
-      this.getStoryItem(id)?.name
-    )
-  }
-
-  /**
-   * Returns the AI render of the component
-   *
-   * Возвращает AI рендер компонента
-   */
-  getAiRender(): string | undefined {
-    return this.getDescriptionItem()?.ai?.render
-  }
-
-  /**
-   * Returns the AI description of the component
-   *
-   * Возвращает AI описание компонента
-   */
-  getAiDescription(): string | undefined {
-    return this.getDescriptionItem()?.ai?.description
-  }
-
-  /**
-   * Returns the AI hide of the component
-   *
-   * Возвращает AI скрыть компонента
-   */
-  getAiHide(): boolean {
-    return this.getDescriptionItem()?.ai?.hide ?? false
-  }
-
-  /**
-   * Returns a wiki item by its name
-   *
-   * Возвращает элемент wiki по его имени
-   * @param name - The name of the wiki item/ имя элемента wiki
-   */
-  protected getWikiItem(name: string): StorybookArgsToItem | undefined {
-    if (
-      name in this.wikiBasic
-      || name in this.wikiDesign
-    ) {
-      return {
-        ...(this.wikiBasic?.[name] ?? {}),
-        ...(this.wikiDesign?.[name] ?? {})
-      } as StorybookArgsToItem
-    }
-
-    return undefined
-  }
-
-  /**
-   * Returns the description item for the component
-   *
-   * Возвращает элемент описания для компонента
-   * @return The description item for the component/ элемент описания для компонента
-   */
-  private getDescriptionItem(): StorybookComponentsDescriptionItem | undefined {
-    return this.wikiDescriptions.find(item => item.name === this.component)
-  }
-
-  /**
-   * Adds a default value to the wiki item and a list of options
-   *
-   * Добавляет значение по умолчанию к элементу wiki и список опций
-   * @param item - The item to convert/ элемент для преобразования
-   * @param wiki - The wiki item to which the default value and options will be added/
-   * элемент wiki, к которому будут добавлены значение по умолчанию и опции
-   */
-  protected toWikiItemChanged(
-    item: StorybookProp,
-    wiki: StorybookArgsToItem
-  ): StorybookArgsToItem {
-    return {
-      ...wiki,
-      options: {
-        ...wiki.options,
-        type: wiki.options?.type ?? item.type,
-        defaultValue: this.defaults[item.name],
-        options: item.option ?? wiki.options?.options ?? undefined
-      }
-    }
-  }
-
-  /**
-   * Converts the descriptions to text format
-   *
-   * Преобразует описания в текстовый формат
-   * @param descriptions - The descriptions to convert/ Описания для преобразования
-   */
-  private toDescriptionText(descriptions?: StorybookArgsToDescription): string {
-    if (descriptions) {
-      const language = Geo.getLanguage()
-
-      if (isObjectNotArray(descriptions)) {
-        return String(
-          descriptions?.[language]
-          ?? Object.values(descriptions)?.[0]
-        )
-      }
-
-      return descriptions
-    }
-
-    return ''
-  }
-
-  /**
-   * Converts the possibilities to text format
-   *
-   * Преобразует возможности в текстовый формат
-   * @param possibilities - The possibilities to convert/ возможности для преобразования
-   */
-  private toPossibilitiesText(possibilities?: StorybookArgsToPossibilities): string[] {
-    if (possibilities) {
-      const language = Geo.getLanguage()
-
-      if (isObjectNotArray(possibilities)) {
-        return possibilities?.[language]
-          ?? Object.values(possibilities)?.[0]
-          ?? []
-      }
-
-      return possibilities
-    }
-
-    return []
-  }
-
-  /**
-   * Initializes the list of wiki items for the component
-   *
-   * Инициализирует список элементов wiki для компонента
-   * @return The list of wiki items for the component/ список элементов wiki для компонента
-   */
-  initList(): WikiStorybookItem[] {
-    const list: WikiStorybookItem[] = []
-
-    this.props.forEach((item) => {
-      const nameByComponent = `${toCamelCase(this.component)}.${item.name}`
-      const wiki = this.getWikiItem(nameByComponent) ?? this.getWikiItem(item.name)
-
-      if (wiki) {
-        list.push(
-          new WikiStorybookItem(
-            item.name,
-            this.toWikiItemChanged(item, wiki)
-          )
-        )
-      } else {
-        console.error(`[WikiStorybook] ${item.name} not found`)
-      }
-    })
-
-    list.sort((a, b) => {
-      const aOrder = a.getOrder()
-      const bOrder = b.getOrder()
-
-      if (aOrder === bOrder) {
-        return a.getName() > b.getName() ? 1 : -1
-      }
-
-      return aOrder > bOrder ? 1 : -1
-    })
-
-    return list
-  }
-
-  /**
-   * Initializes the properties list for the component
-   *
-   * Инициализирует список свойств для компонента
-   * @return The list of properties for the component/ список свойств для компонента
-   */
-  initPropsWiki(): StorybookArgs {
-    const list: StorybookArgs = {}
-
-    this.list.forEach((item) => {
-      list[item.getName()] = item.to()
-    })
-
-    return list
-  }
-}

package/src/classes/WikiStorybookDescriptions.ts

@@ -1,60 +0,0 @@
-import { executeFunction, Geo, isObjectNotArray } from '@dxtmisha/functional'
-
-import type {
-  StorybookComponentsDescriptionItem,
-  StorybookComponentsMdxItem
-} from '../types/storybookTypes'
-
-import { wikiDescriptions } from '../media/descriptions/wikiDescriptions'
-import { wikiMdx } from '../media/mdx/wikiMdx'
-
-/**
- * Class for working with Storybook component descriptions in the wiki
- *
- * Класс для работы с описаниями компонентов Storybook в вики
- */
-export class WikiStorybookDescriptions {
-  private readonly item?: StorybookComponentsDescriptionItem
-  private readonly mdx?: StorybookComponentsMdxItem
-
-  /**
-   * Constructor
-   * @param name - Name of the component to find in the descriptions/ Имя компонента для поиска в описаниях
-   */
-  constructor(name: string) {
-    this.item = wikiDescriptions.find(item => item.name === name)
-    this.mdx = wikiMdx.find(item => item.name === name)
-  }
-
-  /**
-   * Get the description of the component
-   *
-   * Возвращает описание компонента
-   * @return The description of the component or undefined if not found/ Описание компонента или undefined, если не найдено
-   */
-  getItem(): StorybookComponentsDescriptionItem | undefined {
-    return this.item
-  }
-
-  /**
-   * Get an additional description of the component for a specific type
-   *
-   * Возвращает дополнительное описание компонента для конкретного типа
-   * @param type - Type of the description to retrieve/ тип описания для получения
-   */
-  getDescriptionByType(type: string): any {
-    const descriptions = this.mdx?.descriptions?.[type]
-
-    return executeFunction((() => {
-      if (descriptions) {
-        if (isObjectNotArray(descriptions)) {
-          return descriptions[Geo.getLanguage()]
-        }
-
-        return descriptions
-      }
-
-      return ''
-    })())
-  }
-}