@hikasami/naming

HCNC (Hikasami CSS Naming Convention) — внутренняя методология наименования CSS-классов, основанная на BEM и дополненная утилитарными классами и camelCase состояниями.

Установка

# npm
npm install @hikasami/naming --save-dev

# pnpm
pnpm add -D @hikasami/naming

# yarn
yarn add -D @hikasami/naming

Правила именования HCNC

Тип	Формат	Пример
Блок	lowercase/kebab	card, button, header-nav
Элемент 1 ур.	_	card_info, button_icon
Элемент вложен.	__	card_info__title
Модификатор	--	card--highlighted
Состояние	is/has + camelCase	isActive, hasError
Утилиты	atomic	mt-2, flex, text-sm

Примеры

<!-- Блок -->
<div class="card"></div>

<!-- Элемент первого уровня -->
<div class="card_info"></div>

<!-- Вложенный элемент -->
<h3 class="card_info__title"></h3>

<!-- Модификатор -->
<div class="card card--highlighted"></div>

<!-- Состояние -->
<button class="button isActive">Click</button>

<!-- Полный пример -->
<div class="card card--highlighted isActive">
  <div class="card_info flex mt-2">
    <h3 class="card_info__title">Title</h3>
    <p class="card_info__description">Description</p>
  </div>
  <button class="button isActive">
    <svg class="button_icon"></svg>
  </button>
</div>

SCSS вложенность

.card {
  &_info {
    display: flex;

    &__title {
      font-weight: bold;
    }

    &__description {
      color: #777;
    }
  }

  &--highlighted {
    border: 2px solid #eb0052;
  }

  &.isActive {
    opacity: 1;
  }
}

Использование

Интеграция с BiomeJS

Самый простой способ — использовать команду init:

npx hcnc init

Это автоматически добавит плагины в ваш biome.json:

{
  "plugins": [
    "./node_modules/@hikasami/naming/rules/hcnc-jsx.grit",
    "./node_modules/@hikasami/naming/rules/hcnc-css.grit"
  ]
}

После этого запустите линтер:

biome check ./src

CLI

# Инициализация (добавляет плагины в biome.json)
npx hcnc init

# Валидация строки классов
npx hcnc validate "card card_info isActive"

# Проверка директории
npx hcnc check ./src

# Помощь
npx hcnc help

Программный API

import { 
  validateClassName, 
  validateClassString, 
  isHcncClass,
  getClassType 
} from '@hikasami/naming';

// Валидация одного класса
const result = validateClassName('card_info__title');
console.log(result);
// { valid: true, type: 'nested-element' }

// Валидация строки классов
const results = validateClassString('card card--highlighted isActive mt-2');
// [
//   { valid: true, type: 'block' },
//   { valid: true, type: 'modifier' },
//   { valid: true, type: 'state' },
//   { valid: true, type: 'utility' }
// ]

// Проверка типа класса
console.log(getClassType('isActive')); // 'state'
console.log(getClassType('card_info')); // 'element'
console.log(getClassType('mt-2')); // 'utility'

// Проверка валидности
if (isHcncClass('button_icon')) {
  console.log('Valid HCNC class!');
}

Конфигурация

import { validateClassName, HcncConfig } from '@hikasami/naming';

const config: HcncConfig = {
  // Дополнительные паттерны утилит (regex)
  customUtilities: ['^my-custom-.*$', '^theme-.*$'],
  
  // Разрешить неизвестные классы без ошибки
  allowUnknown: false,
  
  // Строгий режим — без утилит
  strictBem: false,
};

validateClassName('my-custom-class', config);

Интеграция с BiomeJS

Настройка biome.json

{
  "$schema": "https://biomejs.dev/schemas/1.9.4/schema.json",
  "linter": {
    "enabled": true
  }
}

GritQL правила

Скопируйте правила из node_modules/@hikasami/naming/rules/ в ваш проект:

rules/
├── hcnc-jsx.grit   # Правила для JSX/TSX
└── hcnc-css.grit   # Правила для CSS/SCSS

API Reference

Функции валидации

Функция	Описание
isBlock(className)	Проверяет, является ли класс блоком
isElement(className)	Проверяет, является ли класс элементом (L1)
isNestedElement(className)	Проверяет, является ли класс вложенным элементом (L2)
isModifier(className)	Проверяет, является ли класс модификатором
isStateClass(className)	Проверяет, является ли класс состоянием
isUtilityClass(className, customPatterns?)	Проверяет, является ли класс утилитой
isHcncClass(className)	Проверяет BEM-совместимость (без состояний и утилит)
validateClassName(className, config?)	Полная валидация с типом и сообщением об ошибке
validateClassString(classString, config?)	Валидация строки классов
getClassType(className, config?)	Получить тип класса
getInvalidClasses(classString, config?)	Получить только невалидные классы

Функции для CSS

Функция	Описание
extractClassSelectors(selector)	Извлечь классы из CSS селектора
validateCssSelector(selector, config?)	Валидировать CSS селектор
expandScssNesting(scss)	Развернуть SCSS вложенность
parseClassString(classString)	Разбить строку на массив классов

Типы

interface ValidationResult {
  valid: boolean;
  type: HcncClassType | null;
  message?: string;
}

type HcncClassType = 
  | 'block'
  | 'element'
  | 'nested-element'
  | 'modifier'
  | 'state'
  | 'utility';

interface HcncConfig {
  customUtilities?: string[];
  allowUnknown?: boolean;
  strictBem?: boolean;
}

Поддерживаемые форматы

• ✅ HTML
• ✅ JavaScript (JS)
• ✅ TypeScript (TS)
• ✅ JSX
• ✅ TSX
• ✅ CSS
• ✅ SCSS
• ✅ Sass

Разработка

# Установка зависимостей
pnpm install

# Сборка
pnpm build

# Разработка с watch
pnpm dev

# Тесты
pnpm test

# Линтинг
pnpm lint

Лицензия

MIT © Hikasami