@rotcetihra/c2c 1.0.0

package/README.md

@@ -0,0 +1,1309 @@
+# C2C — Config-to-CSS Compiler
+
+[![Sass](https://img.shields.io/badge/Sass-CC6699?style=for-the-badge&logo=sass&logoColor=white)](https://sass-lang.com/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=for-the-badge)](https://opensource.org/licenses/MIT)
+
+**C2C (Config-to-CSS)** — это декларативный AOT (Ahead-Of-Time) компилятор и движок генерации
+атомарных CSS-утилит, написанный на современном Dart Sass.
+
+Проект вдохновлен философией Tailwind CSS, но переносит логику сборки дизайн-системы непосредственно
+на уровень препроцессора. Вместо написания шаблонного CSS-кода вручную, вы описываете структуру
+вашей дизайн-системы в виде Sass-карт (`Maps`), а движок автоматически разворачивает их в
+структурированные атомарные классы, включая адаптивные брейкпоинты, интерактивные состояния и их
+пересечения.
+
+## 🚀 Главные особенности
+
+- **Декларативность:** Полное разделение данных (вашей конфигурации) и логики рендеринга.
+- **Продвинутый полиморфизм:** Генераторы компилятора автоматически адаптируются под тип переданных
+  данных (обработка плоских строк, списков и комплексных карт-шаблонов).
+- **Комбинаторика вариантов:** Автоматическая генерация модификаторов состояний (`h:`, `f:`, `a:`) и
+  адаптивных медиа-запросов (`md:`, `lg:`) для любого модуля одной строчкой в конфиге.
+- **Строгая валидация:** Встроенная система контроля типов и обязательных полей верхнего и
+  вложенного уровней — понятные сообщения об ошибках в консоли компилятора при сборке.
+- **Готов к Production:** Спроектирован с учетом обязательной фильтрации через **PurgeCSS /
+  PostCSS**, что позволяет генерировать любые объемы утилит на этапе разработки без раздувания
+  финального бандла.
+
+> 💡 **Обратите внимание:** Это статический AOT-компилятор (генерация до сборки), а не JIT-движок.
+> Он компилирует конфигурационные матрицы в статический CSS-файл, из которого сборщик затем вычищает
+> неиспользуемые классы.
+
+---
+
+## 📦 Установка
+
+Вы можете установить компилятор **C2C** как стандартную зависимость через ваш любимый пакетный
+менеджер.
+
+```bash
+# Через npm
+npm install @rotcetihra/c2c
+
+# Через yarn
+yarn add c2c
+
+# Через pnpm
+pnpm add c2c
+```
+
+### 🔌 Базовое подключение
+
+Чтобы начать работу, достаточно импортировать компилятор в ваш главный файл стилей и передать
+конфигурационную карту в метод-оркестратор. Благодаря встроенной системе модулей Dart Sass (`@use`),
+все внутренние механизмы компилятора доступны через единую точку входа.
+
+```scss
+// main.scss проекта
+@use "pkg:@rotcetihra/c2c" as c2c;
+
+// 1. Описываем конфигурацию вашего модуля
+$display-config: (
+    // Имя модуля (Используется для отладки).
+    "name": "layout",
+
+    // Блок с описанием утилит по их свойствам.
+    "properties": (
+            (
+                "use": (
+                    // Сгенерировать точки останова (`sm:`, `md:`, `lg:` и др.).
+                    "breakpoints": true,
+                    // Сгенерировать только перечисленные состояния.
+                    "states": (
+                            "h",
+                            // :hover
+                            "f",
+                            // :focus
+                            "a" // :active
+                        ),
+                ),
+                "values": (
+                    // Свойство, на основе которого будут генерироваться утилиты.
+                    "display": (
+                            // "Имя утилиты": "Значение утилиты"
+                            "block": "block",
+                            "inline": "inline",
+                            "flex": "flex",
+                            "hidden": "none"
+                        ),
+                ),
+            )
+        )
+);
+
+// 2. Запускаем компиляцию
+@include c2c.by($display-config);
+```
+
+> 📌 **Примечание к импорту:** Префикс `pkg:` поддерживается современным Dart Sass и большинством
+> популярных сборщиков (Vite, Webpack с `sass-loader`, Rspack). Если ваш сборщик использует
+> устаревшие настройки разрешения путей, импорт может выглядеть как `@use "~c2c" as c2c;` или
+> требовать прямого указания пути к `node_modules`.
+
+---
+
+## 📐 Архитектура конфигурации (Configuration Matrix)
+
+В основе **C2C** лежит концепция **конфигурационной матрицы модуля**. Каждый модуль (например,
+`display`, `spacing`, `colors`) описывается в виде единой многомерной карты Sass (`Map`).
+
+Движок устроен ортогонально: свойства отображения (брейкпоинты, ховеры) отделены от самих
+генерируемых данных. Вы можете комбинировать разные типы генераторов внутри одной конфигурации.
+
+### Полный каркас конфигурации модуля
+
+Ниже представлена полная структура карты, которую принимает оркестратор `c2c.by()`. Каждая секция
+является опциональной и запускает соответствующий метод компиляции:
+
+```scss
+$module-config: (
+    // 1. Идентификатор модуля
+    "name": "module-name",
+
+    // 2. Статические утилиты (Один класс = Одно свойство = Одно значение)
+    "properties": (/* ... */),
+    // 3. Динамические числовые диапазоны
+    "steps": (/* ... */),
+    // 4. Дробные и сеточные утилиты
+    "fractions": (/* ... */),
+    // 5. Цветовые утилиты
+    "palettes": (/* ... */),
+    // 6. Комплексные составные классы (Один класс = Пачка CSS-свойств)
+    "classes": (/* ... */),
+    // 7. Глобальные именованные CSS-блоки (На данный момент поддерживается только @keyframes)
+    "blocks": (/* ... */)
+);
+```
+
+### Общая анатомия внутренних блоков
+
+Каждый генератор (`properties`, `steps` и т.д.) внутри конфигурации ожидает карту, состоящую из двух
+ключевых частей:
+
+1. **`"use"` (Настройки вариантов):** Управляет генерацией модификаторов. Здесь вы указываете, нужно
+   ли генерировать для этого конкретного блока адаптивные брейкпоинты (`"breakpoints": true`) или
+   интерактивные состояния (`"states": ("h", "f")`).
+2. **`"values"` (Данные для компиляции):** Карта, структура которой специфична для каждого
+   конкретного метода (строки, списки или вложенные карты).
+
+#### Абстрактный пример структуры генератора:
+
+```scss
+"properties":(("use":("breakpoints":true,"states": ("h"), 
+        ),
+        "values": (
+            // Данные, которые будут прогнаны через циклы модификаторов
+        )
+    )
+);
+```
+
+Такой подход позволяет гибко настраивать генерацию кода: например, для модуля `display` вам могут
+быть жизненно необходимы брейкпоинты (`md:block`), но абсолютно не нужны ховеры, в то время как для
+модуля `palettes` (цветовых схем) вам понадобятся и брейкпоинты, и ховеры одновременно.
+
+---
+
+## 🛠 Руководство по методам компиляции
+
+В этом разделе подробно описаны все доступные миксины-генераторы компилятора **C2C**. Каждый метод
+спроектирован как изолированный математический движок, который принимает очищенные данные из вашей
+конфигурации и разворачивает их в валидный CSS-код.
+
+### 🧩 Главный принцип: Полиморфизм данных
+
+Ключевая особенность компилятора **C2C** — его «всеядность» и гибкость к типам данных во входных
+параметрах (`values`). Движок под капотом использует инспекцию типов (мета-проверки на строки,
+списки и карты).
+
+Это означает, что один и тот же метод компиляции может вести себя абсолютно по-разному в зависимости
+от того, как вы описали целевое CSS-свойство:
+
+- **Плоская строка (`String`):** Запускает классический атомарный рендеринг (одно свойство = одно
+  динамическое значение).
+- **Список (`List`):** Позволяет генерировать комбинированные классы, где одно динамическое значение
+  одновременно присваивается массиву свойств (например, `inset-x` сразу для `left` и `right`).
+- **Карта-шаблон (`Map`):** Включает продвинутый режим шаблонизации. Движок ищет внутри
+  строки-значения специальный знак плейсхолдера (`*`) и подставляет вычисленный шаг или цвет прямо
+  внутрь сложных CSS-функций (например, `rgba(*, var(--opacity))` или `translateX(*)`).
+
+Ниже приведены подробные спецификации для каждого метода компиляции с примерами входных конфигураций
+(`Map`) и результатом их компиляции в CSS-код.
+
+### 4.1. Оркестратор `by($config)`
+
+Миксин `by()` является главной входной точкой (оркестратором) конвейера **C2C**. Он инкапсулирует
+логику верхнего уровня: принимает сырую конфигурационную карту модуля, проверяет её целостность,
+извлекает метаданные (имя модуля, глобальные флаги) и автоматически распределяет блоки данных по
+соответствующим генераторам нижнего уровня с помощью динамического вызова миксинов
+(`meta.get-mixin`).
+
+Вам не нужно вручную вызывать `properties`, `steps` или `palettes` — оркестратор сделает это сам на
+основе ключей вашей конфигурации.
+
+#### 📝 Пример конфигурации модуля
+
+Передаем карту модуля в миксин `c2c.by()`. В данном примере мы объединяем статические свойства и
+динамические шаги в рамках одного модуля `spacing`:
+
+```scss
+@use "pkg:@rotcetihra/c2c" as c2c;
+
+$spacing-module: (
+    "name": "spacing",
+
+    // Статический блок (вызовет метод properties)
+    "properties": (
+            (
+                "use": (
+                    "breakpoints": true,
+                ),
+                "values": (
+                    "box-sizing": (
+                        "box-border": "border-box",
+                        "box-content": "content-box",
+                    ),
+                ),
+            ),
+        ),
+
+    // Динамический блок (вызовет метод steps)
+    "steps": (
+            (
+                "use": (
+                    "breakpoints": true,
+                ),
+                "meta": (
+                    "from": 0,
+                    "to": 2,
+                    "step": 1,
+                    "unit": "rem",
+                ),
+                "values": (
+                    "p": "padding",
+                ),
+            ),
+        ),
+);
+
+// Запуск глобального конвейера сборки модуля
+@include c2c.by($spacing-module);
+```
+
+#### 📄 Результат компиляции в CSS
+
+Оркестратор самостоятельно распознал типы блоков, прогнал их через внутренний цикл брейкпоинтов (для
+тех блоков, где был флаг `breakpoints: true`) и сгенерировал плоский CSS-код:
+
+```css
+/* Базовые статические утилиты */
+.box-border {
+    box-sizing: border-box;
+}
+.box-content {
+    box-sizing: content-box;
+}
+
+/* Базовые динамические шаги */
+.p-0 {
+    padding: 0rem;
+}
+.p-1 {
+    padding: 1rem;
+}
+.p-2 {
+    padding: 2rem;
+}
+
+/* Адаптивные модификаторы (внутри медиа-запросов) */
+@media (min-width: 768px) {
+    .md\:box-border {
+        box-sizing: border-box;
+    }
+    .md\:box-content {
+        box-sizing: content-box;
+    }
+
+    .md\:p-0 {
+        padding: 0rem;
+    }
+    .md\:p-1 {
+        padding: 1rem;
+    }
+    .md\:p-2 {
+        padding: 2rem;
+    }
+}
+```
+
+### 4.2. Метод `properties` (Статические утилиты)
+
+Метод `properties` предназначен для generation традиционных статических утилит, где имя класса,
+целевое CSS-свойство и его значение жестко зафиксированы в конфигурации. Этот генератор идеально
+подходит для таких модулей, как `display`, `position`, `overflow`, `text-align`, `font-weight` и
+других нечисловых CSS-свойств.
+
+Генератор ожидает строгую двумерную карту (`2D Map`) в ключе `values`, которая раскладывается по
+следующему принципу: `CSS-Свойство -> ( Желаемый CSS-Класс: Итоговое CSS-Значение )`
+
+#### 📝 Пример конфигурации модуля
+
+В данном примере настраивается генерация утилит для управления позиционированием и отображением
+элементов с поддержкой адаптивных брейкпоинтов и ховер-состояний:
+
+```scss
+@use "pkg:@rotcetihra/c2c" as c2c;
+
+$layout-module: (
+    "name": "layout",
+    "properties": (
+        (
+            // Настройки вариантов (модификаторов)
+            "use": (
+                    "breakpoints": true,
+                    "states": (
+                        "h",
+                    ),
+                ),
+            // Матрица статических значений
+            "values": (
+                    "position": (
+                        "absolute": "absolute",
+                        "relative": "relative",
+                        "fixed": "fixed",
+                    ),
+                    "pointer-events": (
+                        "click-allow": "auto",
+                        "click-none": "none",
+                    ),
+                )
+        ),
+    ),
+);
+
+@include c2c.by($layout-module);
+```
+
+#### 📄 Результат компиляции в CSS
+
+Благодаря встроенной в метод безопасной интерполяции строк, пустые модификаторы контекста бесследно
+исчезают в базовых классах, но автоматически разворачиваются при генерации вариантов:
+
+```css
+/* Базовые утилиты */
+.absolute {
+    position: absolute;
+}
+.relative {
+    position: relative;
+}
+.fixed {
+    position: fixed;
+}
+.click-allow {
+    pointer-events: auto;
+}
+.click-none {
+    pointer-events: none;
+}
+
+/* Модификаторы состояний (Глобальные) */
+.h\:absolute:hover {
+    position: absolute;
+}
+.h\:relative:hover {
+    position: relative;
+}
+.h\:fixed:hover {
+    position: fixed;
+}
+.h\:click-allow:hover {
+    pointer-events: auto;
+}
+.h\:click-none:hover {
+    pointer-events: none;
+}
+
+/* Адаптивные модификаторы (внутри медиа-запросов) */
+@media (min-width: 768px) {
+    .md\:absolute {
+        position: absolute;
+    }
+    .md\:relative {
+        position: relative;
+    }
+    .md\:fixed {
+        position: fixed;
+    }
+    .md\:click-allow {
+        pointer-events: auto;
+    }
+    .md\:click-none {
+        pointer-events: none;
+    }
+
+    /* Адаптивные модификаторы состояний */
+    .md\:h\:absolute:hover {
+        position: absolute;
+    }
+    .md\:h\:relative:hover {
+        position: relative;
+    }
+    .md\:h\:fixed:hover {
+        position: fixed;
+    }
+    .md\:h\:click-allow:hover {
+        pointer-events: auto;
+    }
+    .md\:h\:click-none:hover {
+        pointer-events: none;
+    }
+}
+```
+
+### 4.3. Метод `steps` (Динамические числовые диапазоны)
+
+Метод `steps` — это мощный математический генератор, который избавляет от ручного описания
+однотипных числовых классов (отступы, размеры, углы поворота, индексы слоев). Вместо перечисления
+каждого значения, вы задаете диапазон и шаг в блоке `"meta"`, а движок сам рассчитывает итерации
+цикла.
+
+Генератор ожидает обязательную карту конфигурации `"meta"` со следующими ключами:
+
+- `from` (Number) — стартовое значение диапазона.
+- `to` (Number) — конечное значение диапазона.
+- `step` (Number) — шаг инкремента.
+- `unit` (String | Null) — единица измерения (например, `px`, `rem`, `%`, `deg` или `null` для
+  безразмерных величин).
+
+#### 🧩 Три режима работы (Полиморфизм данных)
+
+В ключе `values` метод принимает три типа данных, полностью меняющих логику вывода:
+
+1. **Строка (`String`):** Классическое одиночное свойство. Пара `"w": "width"` развернется в `.w-0`,
+   `.w-1` и т.д.
+2. **Список (`List`):** Группировка свойств. Пара `"mx": ("margin-left", "margin-right")` создаст
+   утилиту, управляющую сразу обоими свойствами.
+3. **Карта (`Map`):** Продвинутая шаблонизация. Позволяет оборачивать вычисленное число в сложные
+   CSS-функции. Знак плейсхолдера `*` внутри строки указывает движку, куда именно нужно подставить
+   вычисленное значение с единицей измерения.
+
+#### 📝 Пример конфигурации модуля
+
+В данном примере мы настраиваем комплексный модуль `dimensions`, используя все три режима
+полиморфизма:
+
+```scss
+@use "pkg:@rotcetihra/c2c" as c2c;
+
+$steps-module: (
+    "name": "dimensions",
+    "steps": (
+        (
+            "use": (
+                "breakpoints": true,
+            ),
+            // Описание математического диапазона
+            "meta": (
+                    "from": 0,
+                    "to": 10,
+                    "step": 5,
+                    "unit": "px",
+                ),
+            // Матрица полиморфных значений
+            "values": (
+                    // 1. Строка: Одиночное свойство
+                    "w": "width",
+                    // 2. Список: Группа свойств (осевой отступ)
+                    "my": ("margin-top", "margin-bottom"),
+                    // 3. Карта: Шаблонизация CSS-переменной с плейсхолдером *
+                    "translate-y": (
+                            "--tw-translate-y": "translateY(*)",
+                        ),
+                ),
+        ),
+    ),
+);
+
+@include c2c.by($steps-module);
+```
+
+#### 📄 Результат компиляции в CSS
+
+Движок проитерировал диапазон от 0 до 10 с шагом 5 (получилось три шага: 0, 5, 10), применил единицу
+измерения `px`, корректно обработал списки и подставил значение внутрь функции `translateY()` вместо
+знака `*`:
+
+```css
+/* --- Шаг 0 (0px) --- */
+.w-0 {
+    width: 0px;
+}
+.my-0 {
+    margin-top: 0px;
+    margin-bottom: 0px;
+}
+.translate-y-0 {
+    --tw-translate-y: translateY(0px);
+}
+
+/* --- Шаг 5 (5px) --- */
+.w-5 {
+    width: 5px;
+}
+.my-5 {
+    margin-top: 5px;
+    margin-bottom: 5px;
+}
+.translate-y-5 {
+    --tw-translate-y: translateY(5px);
+}
+
+/* --- Шаг 10 (10px) --- */
+.w-10 {
+    width: 10px;
+}
+.my-10 {
+    margin-top: 10px;
+    margin-bottom: 10px;
+}
+.translate-y-10 {
+    --tw-translate-y: translateY(10px);
+}
+
+/* Адаптивные модификаторы (внутри медиа-запросов) */
+@media (min-width: 768px) {
+    .md\:w-0 {
+        width: 0px;
+    }
+    .md\:my-0 {
+        margin-top: 0px;
+        margin-bottom: 0px;
+    }
+    .md\:translate-y-0 {
+        --tw-translate-y: translateY(0px);
+    }
+
+    .md\:w-5 {
+        width: 5px;
+    }
+    .md\:my-5 {
+        margin-top: 5px;
+        margin-bottom: 5px;
+    }
+    .md\:translate-y-5 {
+        --tw-translate-y: translateY(5px);
+    }
+
+    .md\:w-10 {
+        width: 10px;
+    }
+    .md\:my-10 {
+        margin-top: 10px;
+        margin-bottom: 10px;
+    }
+    .md\:translate-y-10 {
+        --tw-translate-y: translateY(10px);
+    }
+}
+```
+
+### 4.4. Метод `fractions` (Дроби и Сетки)
+
+Метод `fractions` — специализированный генератор для создания пропорциональных и сеточных утилит
+(например, адаптивных сеток в стиле `cols-1/3`, `w-2/5`). Он автоматически рассчитывает дроби во
+вложенных циклах `@while`, генерирует правильные имена классов с экранированием слэша (`\/`) и умеет
+работать в двух принципиально разных режимах калькуляции.
+
+Для управления диапазонами и логикой генерации блок `"meta"` принимает следующие обязательные
+параметры:
+
+- `from` (Number) — стартовая точка для числителя и знаменателя (обычно `0` или `1`).
+- `to` (Number) — максимальный предел разрешения сетки или знаменателя (например, `4` для четвертей
+  или `12` для стандартной двенадцатиколоночной сетки).
+- `unit` (String | Null) — единица измерения для вычисляемых значений (например, `%` или `vh`).
+- `divide` (Boolean) — **Главный переключатель режима:**
+- `true` (Режим процентов): Движок делит числитель на знаменатель и умножает на 100
+  (`(1 / 2) * 100 = 50%`). Идеально для `width`, `height`, `flex-basis`.
+- `false` (Режим разделителя/сеток): Движок не считает математику, а выводит числитель и знаменатель
+  через пробел со слэшем (`1 / 2`). Идеально для CSS Grid утилит вроде `grid-column-start`.
+
+- `incorrect` (Boolean) — разрешить генерацию неправильных дробей, где числитель больше знаменателя
+  или равен ему (например, `w-4/3` или `w-2/2`). При значении `false` генерируются строго правильные
+  дроби (числитель всегда меньше знаменателя).
+- `negative` (Boolean) — инвертировать вычисленное процентное значение в отрицательное (умножает
+  результат на `-1`). Используется для утилит отрицательных сдвигов.
+
+#### 📝 Пример конфигурации модуля
+
+В данном примере мы объявляем два разных блока в рамках одного модуля: один для процентной ширины (с
+математическим делением от 1 до 3), второй — для позиционирования в CSS Grid (без деления):
+
+```scss
+@use "pkg:@rotcetihra/c2c" as c2c;
+
+$grid-module: (
+    "name": "grid-system",
+    "fractions": (
+        (
+            "use": (
+                "breakpoints": true,
+            ),
+            "meta": (
+                "from": 1,
+                "to": 3,
+                "unit": "%",
+                "divide": true,
+                // Включаем деление в проценты
+                "incorrect": false,
+                // Запрещаем дроби вроде 2/2 или 3/2
+                "negative": false,
+            ),
+            "values": (
+                "w": "width",
+            ),
+        ),
+        (
+            "use": (
+                "breakpoints": true,
+            ),
+            "meta": (
+                "from": 1,
+                "to": 2,
+                "unit": null,
+                "divide": false,
+                // Отключаем деление, выводим строку "1 / 2"
+                "incorrect": true,
+                // Разрешаем неправильные дроби (2/1 и т.д.)
+                "negative": false,
+            ),
+            "values": (
+                "col-start": "grid-column-start",
+            ),
+        ),
+    ),
+);
+
+@include c2c.by($grid-module);
+```
+
+#### 📄 Результат компиляции в CSS
+
+Обратите внимание, как движок автоматически экранирует символ слэша `\/` в именах классов, как
+отрабатывают вложенные циклы и как меняется CSS-значение в зависимости от флага `divide`:
+
+```css
+/* --- Блок 1: Процентная ширина (divide: true, incorrect: false) --- */
+.w-1\/2 {
+    width: 50%;
+}
+.w-1\/3 {
+    width: 33.3333333%;
+}
+.w-2\/3 {
+    width: 66.6666666%;
+}
+/* Классы вроде .w-1/1 или .w-2/2 не создаются, так как числитель строго меньше знаменателя */
+
+/* --- Блок 2: Сеточное позиционирование (divide: false, incorrect: true) --- */
+.col-start-1\/1 {
+    grid-column-start: 1 / 1;
+}
+.col-start-2\/1 {
+    grid-column-start: 2 / 1;
+} /* Сгенерировано благодаря incorrect: true */
+.col-start-1\/2 {
+    grid-column-start: 1 / 2;
+}
+.col-start-2\/2 {
+    grid-column-start: 2 / 2;
+}
+
+/* Адаптивные модификаторы (внутри медиа-запросов) */
+@media (min-width: 768px) {
+    .md\:w-1\/2 {
+        width: 50%;
+    }
+    .md\:w-1\/3 {
+        width: 33.3333333%;
+    }
+    .md\:w-2\/3 {
+        width: 66.6666666%;
+    }
+
+    .md\:col-start-1\/1 {
+        grid-column-start: 1 / 1;
+    }
+    .md\:col-start-2\/1 {
+        grid-column-start: 2 / 1;
+    }
+    .md\:col-start-1\/2 {
+        grid-column-start: 1 / 2;
+    }
+    .md\:col-start-2\/2 {
+        grid-column-start: 2 / 2;
+    }
+}
+```
+
+### 4.5. Метод `palettes` (Цветовые схемы)
+
+Метод `palettes` — это специализированный генератор для массового создания цветовых утилит (текст,
+фоны, границы, заливка SVG). Он автоматически берет встроенную в компилятор палитру цветов и
+прогоняет её через переданные вами префиксы классов.
+
+Вшитая палитра компилятора включает два типа структуры цветов, которые генерируют разные виды
+классов:
+
+1. **Цвета со шкалой оттенков:** Для цветов с цифровыми индексами яркости (например, `blue-500`)
+   метод генерирует трехсоставный класс (например, `.bg-blue-500`).
+2. **Одиночные цвета:** Для базовых цветов без оттенков (например, `white`) метод генерирует
+   лаконичный двухсоставный класс без лишних дефисов (`.bg-white`).
+
+#### 📝 Пример конфигурации модуля
+
+Каждая группа настроек оформляется в виде карты, которая передается внутри **списка (List)**
+конфигураций конкретного метода. Вы лишь указываете префикс класса и целевое CSS-свойство:
+
+```scss
+@use "pkg:@rotcetihra/c2c" as c2c;
+
+$colors-module: (
+    "name": "design-colors",
+
+    // Передаем список конфигураций для метода palettes
+    "palettes": (
+            // Первая конфигурационная карта: фоны с поддержкой ховеров
+            (
+                    "use": (
+                        "breakpoints": true,
+                        "states": (
+                            "h",
+                        ),
+                    ),
+                    "values": (
+                        "bg": "background-color",
+                    ),
+                ),
+            // Вторая конфигурационная карта: цвет текста (без ховеров)
+            (
+                    "use": (
+                        "breakpoints": true,
+                        "states": false,
+                    ),
+                    "values": (
+                        "text": "color",
+                    ),
+                ),
+        ),
+);
+
+@include c2c.by($colors-module);
+```
+
+#### 📄 Результат компиляции в CSS
+
+Компилятор берет встроенные цвета и разворачивает их для каждого префикса из вашего списка
+конфигураций с учетом заданных вариантов:
+
+```css
+/* --- Базовые цветовые утилиты (Фоны и Текст) --- */
+.bg-white {
+    background-color: #ffffff;
+}
+.bg-blue-500 {
+    background-color: #3b82f6;
+}
+.text-white {
+    color: #ffffff;
+}
+.text-blue-500 {
+    color: #3b82f6;
+}
+
+/* --- Модификаторы состояний (Только для первой карты, где были разрешены states) --- */
+.h\:bg-white:hover {
+    background-color: #ffffff;
+}
+.h\:bg-blue-500:hover {
+    background-color: #3b82f6;
+}
+
+/* --- Адаптивные модификаторы (внутри медиа-запросов) --- */
+@media (min-width: 768px) {
+    .md\:bg-white {
+        background-color: #ffffff;
+    }
+    .md\:bg-blue-500 {
+        background-color: #3b82f6;
+    }
+    .md\:text-white {
+        color: #ffffff;
+    }
+    .md\:text-blue-500 {
+        color: #3b82f6;
+    }
+
+    /* Адаптивные ховеры для фонов */
+    .md\:h\:bg-white:hover {
+        background-color: #ffffff;
+    }
+    .md\:h\:bg-blue-500:hover {
+        background-color: #3b82f6;
+    }
+}
+```
+
+### 4.6. Метод `classes` (Составные утилиты)
+
+Метод `classes` предназначен для генерации комплексных составных утилит. В отличие от метода
+`properties`, где структура данных строится от свойства к классу, здесь логика инвертирована:
+`Желаемый CSS-Класс -> ( Карта статических CSS-Свойств и их Значений )`
+
+Этот генератор идеально подходит для создания утилит, которые должны применять сразу несколько
+CSS-правил к одному селектору (например, утилиты центрирования, сброса обтекания `clearfix`,
+создания красивых эффектов или фиксированных кастомных компонентов).
+
+#### 📝 Пример конфигурации модуля
+
+Каждая конфигурация оформляется в виде карты внутри общего **списка (List)** метода `classes`. В
+данном примере настраивается генерация утилит для центрирования контента и создания эффекта скрытия
+элементов с поддержкой адаптивных модификаторов:
+
+```scss
+@use "pkg:@rotcetihra/c2c" as c2c;
+
+$effects-module: (
+    "name": "custom-utilities",
+
+    // Передаем список конфигураций для метода classes
+    "classes": (
+            (
+                // Настройки вариантов (модификаторов)
+                "use": (
+                        "breakpoints": true,
+                        "states": (
+                            "h",
+                        ),
+                    ),
+                // Матрица составных классов
+                "values": (
+                        // Утилита для центрирования флекс-контента
+                        "flex-center": (
+                                "display": "flex",
+                                "align-items": "center",
+                                "justify-content": "center",
+                            ),
+                        // Утилита для создания "невидимого", но доступного элемента
+                        "sr-only": (
+                                "position": "absolute",
+                                "width": "1px",
+                                "height": "1px",
+                                "padding": "0",
+                                "margin": "-1px",
+                                "overflow": "hidden",
+                                "clip": "rect(0, 0, 0, 0)",
+                                "border-width": "0",
+                            )
+                    )
+            ),
+        ),
+);
+
+@include c2c.by($effects-module);
+```
+
+#### 📄 Результат компиляции в CSS
+
+Компилятор разворачивает имя класса, генерирует для него все указанные внутри свойства как единый
+блок и накатывает модификаторы брейкпоинтов и состояний:
+
+```css
+/* --- Базовые составные утилиты --- */
+.flex-center {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+}
+.sr-only {
+    position: absolute;
+    width: 1px;
+    height: 1px;
+    padding: 0;
+    margin: -1px;
+    overflow: hidden;
+    clip: rect(0, 0, 0, 0);
+    border-width: 0;
+}
+
+/* --- Модификаторы состояний --- */
+.h\:flex-center:hover {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+}
+.h\:sr-only:hover {
+    position: absolute;
+    width: 1px;
+    height: 1px;
+    padding: 0;
+    margin: -1px;
+    overflow: hidden;
+    clip: rect(0, 0, 0, 0);
+    border-width: 0;
+}
+
+/* --- Адаптивные модификаторы (внутри медиа-запросов) --- */
+@media (min-width: 768px) {
+    .md\:flex-center {
+        display: flex;
+        align-items: center;
+        justify-content: center;
+    }
+    .md\:sr-only {
+        position: absolute;
+        width: 1px;
+        height: 1px;
+        padding: 0;
+        margin: -1px;
+        overflow: hidden;
+        clip: rect(0, 0, 0, 0);
+        border-width: 0;
+    }
+
+    /* Адаптивные модификаторы состояний */
+    .md\:h\:flex-center:hover {
+        display: flex;
+        align-items: center;
+        justify-content: center;
+    }
+    .md\:h\:sr-only:hover {
+        position: absolute;
+        width: 1px;
+        height: 1px;
+        padding: 0;
+        margin: -1px;
+        overflow: hidden;
+        clip: rect(0, 0, 0, 0);
+        border-width: 0;
+    }
+}
+```
+
+### 4.7. Метод `blocks` (Глобальные CSS-директивы)
+
+Метод `blocks` предназначен для генерации сложных именованных CSS-конструкций и глобальных директив,
+которые выходят за рамки обычных классов.
+
+> ⚠️ **Важное ограничение:** На текущий момент компилятор поддерживает генерацию только одного типа
+> блоков — анимационных циклов **`keyframes`**. Поддержка других глобальных директив будет добавлена
+> в будущих релизах.
+
+Поскольку анимации являются глобальными правилами автоматизации интерфейса, этот метод генерирует
+чистые CSS-блоки `@keyframes` без привязки к адаптивным брейкпоинтам или интерактивным состояниям
+(параметр `"use"` здесь игнорируется или опускается).
+
+Структура данных внутри `values` строится по следующему многомерному принципу:
+`Имя анимации -> ( Шаг таймлайна/Ключевой кадр -> ( CSS-Свойства и их Значения ) )`
+
+#### 📝 Пример конфигурации модуля
+
+Конфигурационная карта передается внутри общего **списка (List)** метода `blocks`. В данном примере
+мы описываем параметры для создания двух стандартных анимаций интерфейса: плавного появления
+(`fade-in`) и бесконечного вращения (`spin`):
+
+```scss
+@use "pkg:@rotcetihra/c2c" as c2c;
+
+$animations-module: (
+    "name": "global-animations",
+
+    // Передаем список конфигураций для метода blocks
+    "blocks": (
+            (
+                // Указываем тип блока, который мы конфигурируем
+                "type": "keyframes",
+
+                // Матрица ключевых кадров анимаций
+                "values": (
+                        // Анимация 1: Плавное проявление
+                        "fade-in": (
+                                "from": (
+                                    "opacity": "0",
+                                ),
+                                "to": (
+                                    "opacity": "1",
+                                ),
+                            ),
+                        // Анимация 2: Цикличное вращение лоадера
+                        "spin": (
+                                "0%": (
+                                    "transform": "rotate(0deg)",
+                                ),
+                                "100%": (
+                                    "transform": "rotate(360deg)",
+                                ),
+                            )
+                    )
+            ),
+        ),
+);
+
+@include c2c.by($animations-module);
+```
+
+#### 📄 Результат компиляции в CSS
+
+Компилятор обрабатывает переданную многомерную карту, изолирует каждый шаг таймлайна и разворачивает
+валидные директивы `@keyframes`, которые затем можно использовать в стандартных свойствах
+`animation` вашего проекта:
+
+```css
+/* --- Глобальные блоки анимаций CSS --- */
+@keyframes fade-in {
+    from {
+        opacity: 0;
+    }
+    to {
+        opacity: 1;
+    }
+}
+
+@keyframes spin {
+    0% {
+        transform: rotate(0deg);
+    }
+    100% {
+        transform: rotate(360deg);
+    }
+}
+```
+
+---
+
+## 5. Управление вариантами: Модификаторы (`use`)
+
+Одной из самых мощных возможностей компилятора **C2C** является система автоматической генерации
+вариантов (модификаторов) для базовых классов. Вместо того чтобы вручную дублировать конфигурации
+для адаптивной верстки или интерактивных состояний, вы управляете этим с помощью декларативного
+блока `"use"`, который присутствует в каждой конфигурационной карте.
+
+Блок `"use"` принимает следующие параметры:
+
+- `breakpoints` (Boolean) — включать ли генерацию адаптивных префиксов. Если установлено в `true`,
+  компилятор автоматически обернет утилиты в медиа-запросы и добавит префиксы вида `sm:`, `md:`,
+  `lg:` к именам классов.
+- `states` (Boolean | List) — флаг или список целевых псевдоклассов. Принимает два типа значений:
+- `true` — автоматически генерирует **весь встроенный список состояний** компилятора.
+- Список вида `("h", "f", "a")` — генерирует **только указанные** псевдоклассы (режим `only`).
+
+---
+
+### 📋 Встроенная карта состояний компилятора
+
+При использовании `states: true` или точечном выборе сокращений, компилятор опирается на следующий
+зашитый набор состояний:
+
+| Сокращение  | Псевдокласс        | Категория       | Описание                                              |
+| ----------- | ------------------ | --------------- | ----------------------------------------------------- |
+| **`h`**     | `:hover`           | Интерактивность | Наведение курсора (защищено `@media (hover: hover)`)  |
+| **`f`**     | `:focus`           | Интерактивность | Получение фокуса элементом                            |
+| **`a`**     | `:active`          | Интерактивность | Состояние в момент нажатия (клик)                     |
+| **`fw`**    | `:focus-within`    | Доступность     | Фокус на самом элементе или любом его потомке         |
+| **`fv`**    | `:focus-visible`   | Доступность     | Фокус от клавиатуры (скрывает контур при клике мышью) |
+| **`t`**     | `:target`          | Навигация       | Элемент, на который ссылается текущий URL (якорь)     |
+| **`v`**     | `:visited`         | Навигация       | Ссылка, по которой пользователь уже переходил         |
+| **`val`**   | `:valid`           | Формы           | Поле ввода с корректно заполненными данными           |
+| **`inval`** | `:invalid`         | Формы           | Поле ввода с ошибкой валидации                        |
+| **`req`**   | `:required`        | Формы           | Обязательное для заполнения поле ввода                |
+| **`dis`**   | `:disabled`        | Формы           | Заблокированный элемент (кнопка или инпут)            |
+| **`first`** | `:first-child`     | Структура       | Первый дочерний элемент в контейнере                  |
+| **`last`**  | `:last-child`      | Структура       | Последний дочерний элемент в контейнере               |
+| **`odd`**   | `:nth-child(odd)`  | Структура       | Нечетные элементы (эффект "зебры" в списках/таблицах) |
+| **`even`**  | `:nth-child(even)` | Структура       | Четные элементы                                       |
+
+---
+
+### 📝 Пример конфигурации с точечным выбором состояний
+
+Пример оформления блока `"use"` внутри списка конфигураций для метода `properties`, где мы
+активируем брейкпоинты и выбираем только `hover` и `focus`:
+
+```scss
+@use "pkg:@rotcetihra/c2c" as c2c;
+
+$interactive-module: (
+    "name": "interactive-components",
+    "properties": (
+        (
+            // Настраиваем генерацию вариантов
+            "use": (
+                    "breakpoints": true,
+                    "states": (
+                        "h",
+                        "f",
+                    ),
+                    // Генерируем ТОЛЬКО hover и focus
+                ),
+            "values": (
+                "outline": (
+                    "accent": "2px solid #3b82f6",
+                    "none": "none",
+                ),
+            )
+        ),
+    ),
+);
+
+@include c2c.by($interactive-module);
+```
+
+#### 📄 Результат компиляции в CSS
+
+Компилятор подставляет короткое сокращение в качестве префикса класса (например, `h\:`), а полное
+имя псевдокласса — в конец селектора:
+
+```css
+/* Базовые утилиты */
+.outline-accent {
+    outline: 2px solid #3b82f6;
+}
+.outline-none {
+    outline: none;
+}
+
+/* Глобальные модификаторы состояний (точечная выборка) */
+.h\:outline-accent:hover {
+    outline: 2px solid #3b82f6;
+}
+.h\:outline-none:hover {
+    outline: none;
+}
+.f\:outline-accent:focus {
+    outline: 2px solid #3b82f6;
+}
+.f\:outline-none:focus {
+    outline: none;
+}
+
+/* Адаптивный слой (внутри медиа-запроса) */
+@media (min-width: 768px) {
+    .md\:outline-accent {
+        outline: 2px solid #3b82f6;
+    }
+    .md\:outline-none {
+        outline: none;
+    }
+
+    /* Адаптивные состояния */
+    .md\:h\:outline-accent:hover {
+        outline: 2px solid #3b82f6;
+    }
+    .md\:h\:outline-none:hover {
+        outline: none;
+    }
+    .md\:f\:outline-accent:focus {
+        outline: 2px solid #3b82f6;
+    }
+    .md\:f\:outline-none:focus {
+        outline: none;
+    }
+}
+```
+
+---
+
+## 6. Валидация и Логирование ошибок (Error Handling)
+
+Компилятор **C2C** оснащен строгим изолированным миксином валидации, который проверяет целостность
+структуры данных перед тем, как запустить конвейер генерации CSS. Если в вашей конфигурации
+отсутствует обязательный параметр или вложенное подполе, компилятор не станет генерировать сломанный
+CSS, а мгновенно прервет сборку проекта, выбросив системное исключение с точным указанием места
+ошибки.
+
+---
+
+### 🔍 Карта обязательных полей
+
+Валидатор автоматически проверяет каждую конфигурационную карту внутри списков методов на наличие
+следующих обязательных ключей:
+
+| Метод компиляции | Обязательные поля верхнего уровня | Обязательные вложенные подполя   |
+| ---------------- | --------------------------------- | -------------------------------- |
+| **`properties`** | `"values"`                        | _Нет_                            |
+| **`classes`**    | `"values"`                        | _Нет_                            |
+| **`palettes`**   | `"values"`                        | _Нет_                            |
+| **`blocks`**     | `"values"`                        | _Нет_                            |
+| **`steps`**      | `"meta"`, `"values"`              | `"meta" -> "step", "from", "to"` |
+| **`fractions`**  | `"meta"`, `"values"`              | `"meta" -> "from", "to"`         |
+
+Если вы конфигурируете сложный метод (например, `steps` или `fractions`), валидатор рекурсивно
+спустится в карту `"meta"` и проверит наличие всех математических границ диапазона.
+
+---
+
+### 🚨 Строгая цепочка локализации ошибок
+
+При обнаружении пропущенного поля компилятор вызывает директиву `@error`, останавливая сборку. Вывод
+ошибки стандартизирован и собирает полную цепочку контекста через двойное двоеточие по принципу:
+`Имя модуля :: Метод (Группа) :: Индекс карты в списке :: Пропущенный параметр`
+
+#### 📝 Формат системного исключения:
+
+```text
+Error: Отсутствует обязательное поле '[Имя модуля]::[Группа]::[Индекс конфигурации]::[Параметр]'.
+
+```
+
+#### Примеры реального вывода ошибок в консоль:
+
+- Если вы забыли указать шаг `step` во второй карте конфигурации метода `steps` внутри модуля
+  `spacing`:
+
+```text
+Error: Отсутствует обязательное поле 'spacing::steps::2::meta::step'.
+
+```
+
+- Если вы забыли передать блок `values` в первой карте конфигурации метода `properties` внутри
+  модуля `display`:
+
+```text
+Error: Отсутствует обязательное поле 'display::properties::1::values'.
+
+```
+
+---
+
+## 7. Интеграция с PurgeCSS (Production Build)
+
+Поскольку **C2C** генерирует утилиты динамически на основе конфигурационных матриц, ваш CSS-файл на
+этапе разработки может весить достаточно много. Для очистки неиспользуемого кода в продакшн-сборке
+настоятельно рекомендуется использовать **PurgeCSS** (или встроенные инструменты сборщиков, такие
+как PostCSS PurgeCSS).
+
+---
+
+### ⚠️ Важная особенность экстракции классов
+
+Из-за того, что компилятор **C2C** активно использует спецсимволы для разделения модификаторов
+(двоеточие `\:` для состояний и брейкпоинтов) и дробей (экранированный слэш `\/`), стандартные
+экстракторы PurgeCSS не смогут распознать эти классы в ваших HTML/JS файлах и полностью удалят их из
+финальной сборки.
+
+Чтобы этого не произошло, необходимо настроить кастомный **Extractor**, который обучит PurgeCSS
+корректно считывать спецсимволы **C2C**.
+
+---
+
+### ⚙️ Настройка конфигурации (PurgeCSS Config)
+
+Добавьте следующее регулярное выражение в массив `defaultExtractor` вашего конфигурационного файла
+(например, `purgecss.config.js` или в настройки плагина PostCSS):
+
+```javascript
+module.exports = {
+    content: [
+        "./src/**/*.html",
+        "./src/**/*.js",
+        "./src/**/*.vue",
+        "./src/**/*.jsx",
+        // Укажите пути ко всем вашим шаблонам
+    ],
+    defaultExtractor: (content) => {
+        // Регулярное выражение, которое захватывает классы со спецсимволами \: и \/
+        return content.match(/[A-Za-z0-9_-]+(?::[A-Za-z0-9_-]+)*(?:\/[A-Za-z0-9_-]+)?/g) || [];
+    },
+};
+```
+
+### 💡 Как это работает?
+
+Данное регулярное выражение гарантирует, что PurgeCSS корректно свяжет строковую запись в вашем
+HTML-шаблоне с селектором в CSS-файле:
+
+- Строка `class="md:hover:bg-blue-500"` в HTML будет успешно сопоставлена со сгенерированным
+  селектором `.md\:hover\:bg-blue-500`.
+- Строка `class="w-1/2"` в HTML свяжется с селектором `.w-1\/2`.
+
+Без этой настройки ваша адаптивная верстка и дробные сетки **сломаются в продакшене**, так как
+PurgeCSS посчитает их неиспользуемыми.
+
+---
+
+## 8. Лицензия (License)
+
+Этот проект распространяется под свободной лицензией **MIT**.
+
+Это означает, что вы можете совершенно бесплатно использовать компилятор **C2C** как в личных, так
+как и в коммерческих проектах, изменять код, форкать репозиторий или интегрировать его в свои
+проприетарные продукты без каких-либо жестких ограничений.
+
+Полный текст лицензии находится в файле [LICENSE](https://www.google.com/search?q=./LICENSE) в
+корневом каталоге данного репозитория.
+
+---
+
+Разработано с фокусом на скорость, чистоту кода и гибкость конфигурации. Если у вас возникли вопросы
+или предложения по улучшению компилятора — создавайте **Issues** или присылайте **Pull Requests**!
+🚀