@rotcetihra/c2c-config

@rotcetihra/c2c-config — это официальная стандартная библиотека конфигурационных матриц для атомарного CSS-компилятора C2C (@rotcetihra/c2c).

Пакет поставляется как готовый пресет ядра, который полностью берет на себя рутинную декларацию карт генерации. Он разворачивает полноценную, предсказуемую дизайн-систему непосредственно на уровне вашего препроцессора, избавляя от необходимости описывать конфигурации утилит вручную.

🎯 Философия и синтаксис

Данная библиотека пресетов спроектирована на основе философии Tailwind CSS. Все ключевые группы свойств, логика наименования классов, модификаторы и адаптивные брейкпоинты здесь идентичны популярному фреймворку.

Если вы знакомы с Tailwind, вам не придется учить синтаксис заново:

• Для позиционирования и отображения используются знакомые утилиты вроде block, absolute, z-10 или sr-only.
• Для работы с флексбоксами и сетками доступны flex, grid-cols-3 или justify-center.

🔧 Особенности расчета шагов и единиц измерения

Несмотря на общее сходство синтаксиса, библиотека C2C имеет принципиальное архитектурное отличие от Tailwind CSS в подходе к компиляции и вычислению размерных сеток (для утилит sizes, intervals и др.):

• Tailwind CSS полагается на динамический расчет в браузере (Runtime), используя CSS-переменные и функции вида calc(var(--step) * <number>).
• C2C работает по принципу Ahead-of-Time (AOT) компиляции. Он полностью производит все математические вычисления на этапе сборки проекта средствами Dart Sass и генерирует чистые, фиксированные значения.

📐 Прямое указание значений в rem

Вместо абстрактных номеров шагов или условных единиц фреймворка, утилиты в этой библиотеке конфигураций генерируют классы, основываясь на реальных значениях rem, которые необходимы вам в верстке.

Наименование класса напрямую отражает его итоговый размер:

• Если вам нужно задать элементу ширину ровно 1.125rem, вам больше не нужно вспоминать, какому шагу сетки это соответствует. Достаточно использовать утилиту: w-1.125.
• Для внешнего отступа в 0.25rem используется класс: m-0.25.
• Для высоты в 20rem используется класс: h-20.

Такой подход делает генерируемый CSS-код чистым, избавляет браузер от лишних вычислений через calc() и позволяет разработчику полностью контролировать размеры макета, видя конечный результат прямо в имени класса.

📦 Установка

Вы можете установить библиотеку конфигураций C2C-Config как зависимость разработки (devDependency) с помощью вашего любимого пакетного менеджера.

Обратите внимание, что данный пакет является набором пресетов и требует наличия установленного ядра — самого компилятора @rotcetihra/c2c.

# Через npm
npm install -D @rotcetihra/c2c-config

# Через yarn
yarn add -D @rotcetihra/c2c-config

# Через pnpm
pnpm add -D @rotcetihra/c2c-config

⚠️ Системные требования

Для успешной компиляции стилей в вашем проекте должен быть установлен современный препроцессор Dart Sass версии не ниже ^1.45.0.

🚀 Быстрый старт (Интеграция)

Поскольку библиотека @rotcetihra/c2c-config внутри своего главного файла index.scss уже содержит все необходимые импорты модулей и автоматически передает их в компилятор, интеграция в ваш проект происходит буквально в одну строку.

Вам достаточно импортировать пакет в вашем основном стилистическом файле (например, app.scss или main.scss):

// Импортируем конфигурационный пакет.
// Он сам подключит ядро c2c, сбросит стили и скомпилирует все атомарные классы.
@use "pkg:@rotcetihra/c2c-config";

🧬 Что происходит при этом импорте?

Когда вы подключаете этот пакет, внутри вашего финального CSS-файла автоматически разворачивается готовая дизайн-система в строго определенном порядке:

1. Reset CSS — классический кроссбраузерный сброс стилей Эрика Мейера (v2.0).
2. Глобальный Box-Sizing — автоматическое применение box-sizing: border-box ко всем элементам и их псевдоэлементам (*, ::before, ::after) для предсказуемого расчета размеров.
3. Автоматическая генерация слоев — последовательный вызов внутреннего миксина компилятора для каждой группы свойств:

• Стили макета (layout)
• Флексы и гриды (flexbox)
• Отступы (intervals)
• Размеры элементов (sizes)
• Типографика (typography)
• Фоны (backgrounds)
• Границы (borders)
• Эффекты и фильтры (effects, filters)
• Таблицы (tables)
• Анимации (animations)
• Трансформации (transformations)
• Интерактивность (interactivity)
• Векторная графика (svg)
• Доступность (availability)

Такой подход позволяет развернуть весь спектр утилит в стиле Tailwind CSS за долю секунды, не написав ни одной строчки конфигурации вручную.

📂 Каталог модулей (Подробный справочник)

Библиотека предоставляет исчерпывающий набор утилит, разделенных на логические модули. Ниже представлен детальный разбор ключевых префиксов и классов для каждой группы.

Layout (Отображение и позиционирование)

Отвечает за базовое поведение элемента в потоке документа, его видимость и перекрытие.

| Префикс / Класс | CSS-свойство | Примеры использования | | --------------------------------- | -------------------------------- | ------------------------------------ | | block, flex, grid, hidden | display | block, inline-flex, hidden | | absolute, relative, fixed | position | absolute, sticky, static | | inset-*, top-*, bottom-* | top, right, bottom, left | top-0, inset-x-auto, -left-1 | | z-* | z-index | z-0, z-50, z-auto | | overflow-* | overflow | overflow-hidden, overflow-y-auto | | box-* | box-sizing | box-border, box-content |

Flexbox и Grid

Инструменты для создания адаптивных сеток и гибких интерфейсов.

| Префикс / Класс | CSS-свойство | Примеры использования | | ---------------------- | ------------------------------ | ----------------------------------- | | flex-* | flex-direction, flex-wrap | flex-row, flex-col, flex-wrap | | justify-* | justify-content | justify-center, justify-between | | items-*, content-* | align-items, align-content | items-center, content-start | | grid-cols-* | grid-template-columns | grid-cols-4, grid-cols-none | | col-span-* | grid-column | col-span-2, col-span-full | | gap-* | gap | gap-4, gap-x-2, gap-y-1 |

Intervals (Отступы)

Управление внешними и внутренними отступами. Напоминаем, что числовое значение в классе — это прямое значение в rem.

| Префикс / Класс | CSS-свойство | Примеры использования | | ------------------------ | -------------------------- | --------------------------- | | m-*, mx-*, my-* | margin | m-1, mx-auto, -mt-2.5 | | p-*, px-*, py-* | padding | p-2, px-4, py-0.5 | | space-x-*, space-y-* | margin (между дочерними) | space-x-4, -space-y-1 |

Sizes (Размеры)

Геометрия элементов. Поддерживаются как точные значения в rem, так и процентные дроби (1/2, 1/3, full).

| Префикс / Класс | CSS-свойство | Примеры использования | | --------------------------- | ------------------ | ------------------------------------ | | w-*, min-w-*, max-w-* | width | w-full, w-1/2, max-w-screen-md | | h-*, min-h-*, max-h-* | height | h-screen, h-3.125, min-h-full | | size-* | width + height | size-10, size-full |

Typography (Типографика)

Все, что касается оформления текстового контента.

| Префикс / Класс | CSS-свойство | Примеры использования | | --------------- | ----------------------------- | -------------------------------------- | | font-* | font-family, font-weight | font-sans, font-bold, font-light | | text-* | font-size, text-align | text-sm, text-2xl, text-center | | leading-* | line-height | leading-tight, leading-relaxed | | tracking-* | letter-spacing | tracking-wide, tracking-tight | | list-* | list-style-type, position | list-disc, list-inside |

Backgrounds и Borders (Фоны и Границы)

Декоративное оформление контейнеров.

| Префикс / Класс | CSS-свойство | Примеры использования | | ---------------- | -------------------------------- | -------------------------------------------- | | bg-* | background | bg-cover, bg-no-repeat, bg-fixed | | from-*, to-* | background-image (градиенты) | bg-linear-to-r, from-inherit | | rounded-* | border-radius | rounded-md, rounded-full, rounded-t-lg | | border-* | border-width, border-style | border, border-2, border-dashed | | divide-* | border-width (между дочерними) | divide-x, divide-y-2 |

Effects, Filters и Transformations

Визуальные модификации и аппаратное ускорение.

| Префикс / Класс | CSS-свойство | Примеры использования | | --------------- | ------------------------ | ------------------------------------------ | | shadow-* | box-shadow | shadow-md, shadow-inner, shadow-none | | opacity-* | opacity | opacity-0, opacity-50, opacity-100 | | blur-* | filter: blur() | blur, blur-md, blur-none | | scale-* | transform: scale() | scale-90, scale-x-110 | | rotate-* | transform: rotate() | rotate-45, -rotate-90 | | translate-* | transform: translate() | translate-x-1/2, -translate-y-full |

Адаптивный дизайн (Брейкпоинты)

В библиотеку встроена строгая система брейкпоинтов (контрольных точек), работающая по принципу Mobile-First. Классы без префикса применяются ко всем экранам (начиная с самых маленьких). Для изменения стилей на больших экранах просто добавьте соответствующий префикс к любой утилите.

| Префикс | Значение в rem | Эквивалент в px | Целевые устройства | | -------- | -------------- | --------------- | -------------------------------- | | xs: | 30rem | ~480px | Крупные телефоны (горизонтально) | | sm: | 40rem | ~640px | Мини-планшеты | | md: | 48rem | ~768px | Планшеты | | lg: | 64rem | ~1024px | Ноутбуки | | xl: | 80rem | ~1280px | Десктопы | | xxl: | 96rem | ~1536px | Большие мониторы | | ultra: | 120rem | ~1920px | Ultra-wide / Full HD мониторы |

Пример использования:

<div class="w-full md:w-1/2 lg:w-1/3">...</div>

<div class="hidden xl:flex">...</div>

Интерактивные и структурные состояния (Псевдоклассы)

Для генерации стилей, зависящих от действий пользователя, состояния формы или ее положения в структуре документа, библиотека поддерживает полный спектр коротких префиксов.

Генерация этих состояний управляется флагами конфигурации states для каждого конкретного модуля.

| Префикс | Псевдокласс | Описание | Примеры использования | | ------------------------------------------- | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- | | Интерактивность (User Action) | | | | | h: | :hover | Наведение курсора (внутри миксина компилятора автоматически защищено медиа-запросом @media (hover: hover) от залипания на тачскринах). | h:bg-primary, h:scale-105 | | f: | :focus | Элемент находится в фокусе (например, при текстовом вводе или навигации). | f:border-blue-500, f:outline-none | | a: | :active | Элемент находится в состоянии нажатия (активен в момент клика). | a:bg-dark, a:translate-y-0.5 | | Доступность и навигация (Accessibility) | | | | | fw: | :focus-within | Фокус находится на самом элементе или на любом из его внутренних дочерних элементов. | fw:border-green-500, fw:shadow-lg | | fv: | :focus-visible | Фокус активирован исключительно с клавиатуры (позволяет скрыть контур выделения при кликах мышью, сохраняя доступность). | fv:outline-2, fv:outline-blue-600 | | t: | :target | Элемент, идентификатор (ID) которого совпадает с хэшем (якорем) в текущем URL страницы. | t:bg-yellow-100, t:border-pulse | | v: | :visited | Ссылка, по которой пользователь уже кликал ранее (ограничено системными правилами безопасности браузеров). | v:text-gray-400 | | Формы и валидация (Form States) | | | | | dis: | :disabled | Заблокированное состояние элемента интерфейса (инпуты, кнопки, селекты). | dis:opacity-50, dis:cursor-not-allowed | | req: | :required | Поле формы, обязательное для заполнения перед отправкой. | req:border-red-300 | | val: | :valid | Поле ввода, данные в котором успешно прошли текущую браузерную валидацию. | val:border-green-500 | | inval: | :invalid | Поле ввода, содержимое которого не соответствует правилам валидации. | inval:text-red-600, inval:border-red-500 | | Положение в структуре (Structural) | | | | | first: | :first-child | Первый дочерний элемент внутри своего родительского контейнера. | first:mt-0, first:rounded-t-md | | last: | :last-child | Последний дочерний элемент внутри своего родительского контейнера. | last:mb-0, last:rounded-b-md | | odd: | :nth-child(odd) | Все нечетные элементы в списке или таблице (используется для создания чередующейся "зебры"). | odd:bg-gray-50 | | even: | :nth-child(even) | Все четные элементы в списке или таблице. | even:bg-white |

Комбинация с брейкпоинтами

Все префиксы состояний можно бесшовно комбинировать с адаптивными брейкпоинтами мобильной адаптации. При написании классов строго соблюдается иерархический порядок: сначала указывается ширина экрана, затем псевдокласс, и в конце — сама утилита.

Синтаксическая схема: [брейкпоинт]:[состояние]:[утилита]

Примеры использования в верстке:

<div class="bg-white lg:h:bg-gray-100">...</div>

<tr class="bg-transparent md:odd:bg-gray-50">
    ...
</tr>

<div class="border-gray-200 fw:border-blue-500">
    <input type="text" />
</div>

📐 Архитектура шагов (Математика сетки)

Размерная сетка в @rotcetihra/c2c-config построена на строгой Ahead-of-Time (AOT) компиляции фиксированных значений rem. Это гарантирует абсолютную предсказуемость верстки и избавляет браузер от выполнения тяжелых динамических расчетов на стороне клиента.

Вся математика модулей, отвечающих за геометрию и пространство (sizes, intervals и др.), опирается на два ключевых принципа: линейные шаги и пропорциональные дроби.

Линейные шаги (Множители базовой единицы)

Базовый шаг генерации утилит эквивалентен 0.125rem (что при стандартных настройках браузера и базовом шрифте в 16px равняется ровно 2px). Однако имена классов формируются не абстрактными индексами или номерами шагов, а конечным значением в rem.

Генератор автоматически распределяет сетку с высокой точностью:

• Микро-шаги (до 1rem): Позволяют филигранно настраивать интерфейс с шагом 0.125rem. Сюда входят утилиты для точечной верстки: 0.125, 0.25, 0.375, 0.5, 0.625, 0.75, 0.875.
• Стандартные шаги (после 1rem): Сетка плавно увеличивается, предлагая линейный и интуитивно понятный ряд: 1, 1.125, 1.25, 1.5, 1.75, 2 и так далее.
• Крупные шаги: Для больших контейнеров, секций и брейкпоинтов шаг становится более редким, чтобы избежать раздувания итогового CSS-файла, сохраняя при этом все ключевые размеры.

Пример компиляции линейного шага:

// Исходный класс в HTML: w-1.125
// Результат компиляции в CSS:
.w-1\.125 {
    width: 1.125rem; /* Ровно 18px при базовом шрифте 16px */
}

// Исходный класс в HTML: m-0.375
// Результат компиляции в CSS:
.m-0\.375 {
    margin: 0.375rem; /* Ровно 6px при базовом шрифте 16px */
}

Пропорциональные дроби (Декларация сетки)

Для создания гибких резиновых колонок и макетов в модулях размеров используется синтаксис простых дробей. Компилятор берет числитель и знаменатель из имени класса, делит их друг на друга во время сборки и переводит в точные проценты.

Библиотека поддерживает следующие базовые сетки:

• Половины и трети: 1/2, 1/3, 2/3
• Четверти: 1/4, 2/4 (эквивалент 1/2), 3/4
• Пятые и шестые доли: 1/5 ... 4/5, 1/6 ... 5/6
• Двенадцатые доли (Стандартный Grid): от 1/12 до 11/12

Пример компиляции пропорциональной дроби:

// Исходный класс в HTML: w-1/3
// Результат компиляции в CSS:
.w-1\/3 {
    width: 33.33333%;
}

// Исходный класс в HTML: w-5/12
// Результат компиляции в CSS:
.w-5\/12 {
    width: 41.66667%;
}

Специальные именованные значения

Помимо цифр и дробей, математика сетки включает в себя системные ключевые слова для явного управления поведением элементов:

• full — преобразуется в 100% (например, w-full, h-full).
• screen — использует размеры области видимости браузера (100vw для ширины, 100vh для высоты).
• min / max / fit — задействуют встроенные алгоритмы расчета контента браузером (min-content, max-content, fit-content).
• auto — возвращает автоматический расчет (наиболее применимо в m-auto, h-auto).
• none — полностью сбрасывает ограничения (например, max-w-none).

⚙️ Выборочный импорт и расширение

Библиотека @rotcetihra/c2c-config спроектирована как модульная система. Если вам не нужен весь спектр утилит Tailwind-модели или вы хотите кастомизировать конфигурационные матрицы под специфику своего проекта (например, добавить новые размеры или переопределить свойства), вы можете использовать раздельные импорты и встроенные инструменты Sass для работы с картами (map.deep-merge).

Выборочный импорт модулей

Каждая группа свойств вынесена в отдельный подмодуль. Вы можете импортировать только те части пресета, которые необходимы в текущем проекте, полностью контролируя состав и объем итогового CSS-файла.

Для выборочной сборки импортируйте ядро компилятора и конкретные конфигурации напрямую из пакета:

// Подключаем ядро компилятора
@use "pkg:@rotcetihra/c2c" as c2c;

// Импортируем только нужные конфигурационные матрицы
@use "pkg:@rotcetihra/c2c-config/typography";
@use "pkg:@rotcetihra/c2c-config/sizes";

// Компилируем выбранные слои по отдельности
@include c2c.by(typography.$config);
@include c2c.by(sizes.$config);

Примечание: При выборочном импорте автоматический сброс стилей Эрика Мейера (Reset CSS) и глобальное правило box-sizing не подключаются. При необходимости вы можете импортировать их вручную через @use "pkg:@rotcetihra/c2c-config/reset";

Расширение и кастомизация конфигурации

Все конфигурационные матрицы внутри модулей представляют собой стандартные карты Dart Sass (map). Это позволяет гибко модифицировать их перед передачей в компилятор с помощью встроенной функции sass:map.

Пример: Добавление кастомных значений размеров

Если стандартного шага 0.125rem вам недостаточно и в проекте необходимо использовать специфические или фиксированные размеры (например, нестандартный размер шапки или боковой панели), вы можете подмешать свои значения в существующую матрицу:

@use "sass:map";
@use "pkg:@rotcetihra/c2c" as c2c;
@use "pkg:@rotcetihra/c2c-config/sizes";

// Создаем карту с вашими уникальными шагами генерации
$my-custom-sizes: (
    "steps": (
        (
            "meta": (
                "step": 1,
                // Шаг итерации
                "from": 0,
                // Начало диапазона
                "to": 100,
                // Конец диапазона
                "unit": "px",
                // Единица измерения для CSS-значения
            ),
            "use": (
                "breakpoints": true,
                // Включить адаптивные префиксы (md:, lg:)
                "states": false,
                // Отключить псевдоклассы (h:, f:)
            ),
            "values": (
                // Шаблон имени класса : CSS-свойство
                "w-*px": "width",
                "h-*px": "height",
                "max-w-*px": "max-width",
                "max-h-*px": "max-height",
            ),
        ),
    ),
);

// Глубоко объединяем базовую конфигурацию с кастомной
$extended-sizes-config: map.deep-merge(sizes.$config, $my-custom-sizes);

// Передаем расширенную матрицу в движок компилятора через миксин .by()
@include c2c.by($extended-sizes-config);

Что произойдет при компиляции этого примера?

Движок C2C возьмет базовые утилиты из модуля sizes и добавит к ним новую сгенерированную пиксельную матрицу. В вашем итоговом CSS-файле появится ровно по 100 новых утилит для каждого указанного свойства:

/* Примеры сгенерированного CSS */
.w-1px {
    width: 1px;
}
.w-2px {
    width: 2px;
}
... .w-100px {
    width: 100px;
}

/* А также их адаптивные копии благодаря флагу breakpoints: true */
@media (min-width: 48rem) {
    .md\:w-50px {
        width: 50px;
    }
}

📄 Лицензия

Проект распространяется на условиях лицензии MIT. Вы можете свободно использовать, модифицировать и распространять данный пакет как в личных, так и в коммерческих целях.

Полный текст лицензии доступен в файле LICENSE в корневом каталоге репозитория.