import {Meta} from '@storybook/addon-docs/blocks'

<Meta title='@dxtmisha/ru/# UI/properties/# Значения'/>

# Работа со значениями (Value)

Поле `value` в `properties.json` определяет конечное содержимое свойства (цвет, размер, путь и т.д.). Содержимое `value` может быть представлено литералами, динамическими ссылками на другие токены или системными маркерами.

### Литералы и Типы данных
Система поддерживает стандартные типы данных JSON:
- **Строки**: `"12px"`, `"relative"`, `"none"`.
- **Числа**: `24`, `0.5` (автоматически преобразуются в строки при сборке).
- **Цвета**: Поддерживаются HEX-форматы:
    - `#FFF` / `#FFFFFF` — стандартный цвет.
    - `#FFFFFF80` — цвет с альфа-каналом (8 символов).

### Ссылки и системные маркеры (`{...}`)
Вы можете заимствовать значения других свойств, используя фигурные скобки. Это позволяет создавать зависимости между токенами.

#### Правила разрешения путей:
1. **Абсолютный путь**: `{design.component.property}` — полное указание от корня.
2. **Относительный путь (Авто-дизайн)**: `{primary-color}`. Если первый сегмент пути не является названием зарегистрированного дизайна, система автоматически подставляет имя текущего дизайна (`{current-design.primary-color}`).
3. **Вложенность**: Поддерживается неограниченная вложенность через точку: `{base.spacing.small}`.

#### Специальные метки (Шорткаты):
Для сокращения путей внутри ссылок используются специальные символы-подстановки:
- `?` — заменяется на `[текущий_дизайн].`.
- `??` — заменяется на `[текущий_дизайн].[текущий_компонент].`.

**Пример:**
```json
{
  "button": {
    "color": "{?primary}",          // Развернется в {d1.primary}
    "padding": "{??base-padding}"   // Развернется в {d1.button.base-padding}
  }
}
```

Эти метки позволяют писать переносимый код, который не сломается при переименовании дизайна или компонента.

#### Выражения и смешанный контент:
Поле `value` может содержать произвольный текст, внутри которого находятся одна или несколько ссылок `{...}`. Система найдет и развернет каждую ссылку, сохранив остальной текст нетронутым.

Это позволяет использовать ссылки внутри функций CSS (например, `calc()`) или комбинировать их с нативными CSS-переменными.

**Пример:**
```json
{
  "button": {
    "padding": "var(--sys-height) * {sys.spacing.adaptive.md}"
  }
}
```

### Маркер «Полного значения» (`=`)
Если значение начинается с символа `=`, компилятор считает его «завершенным» (full value). Значение передается в SCSS «как есть» без какой-либо дальнейшей обработки.

Это полезно для сложных функций CSS или когда нужно передать сырой путь.

**Пример использования:**
```json
{
  "button": {
    "color": "{?primary}",           // Ссылка через метку дизайна
    "padding": "{??base-padding}",   // Ссылка через метку компонента
    "width": "=calc(100% - 20px)",   // Полное значение (без обработки)
    "border": "1px solid #00000030"  // HEX с прозрачностью
  }
}
```

### Дополнительные параметры
Для более точной настройки обработки и вывода значения можно использовать специальные служебные флаги (начинающиеся с `_`):

- `_important: boolean` — добавляет спецификатор `!important` к значению свойства в CSS.
- `_fullValue: boolean` — программный аналог маркера `=`. Отключает автоматическое добавление единиц измерения (`px`) и разрешение ссылок `{}`.
- `_replace: object` — позволяет выполнить замену текста в финальном значении через регулярное выражение. Принимает объект `{ pattern, flags, replace }`.
- `_modification: boolean` — управляет возможностью модификации свойства в SCSS (по умолчанию `true`). При значении `false` свойство считается статичным.

**Пример использования:**
```json
{
  "button": {
    "width": { 
      "value": "100%", 
      "_important": true      // Результат: width: 100% !important;
    },
    "padding": { 
      "value": "16px", 
      "_replace": {           // Результат: padding: 16rem;
        "pattern": "px", 
        "replace": "rem", 
        "flags": "g" 
      }
    },
    "height": { 
      "value": "calc(100vh - 20px)", 
      "_fullValue": true      // Результат: height: calc(100vh - 20px);
    }
  }
}
```
