<script setup lang="ts">
import { EButton } from './Button.ecss';
</script>

<template>
  <EButton as="button" :params="{ variant: 'primary' }" @click="onClick">
    Нажми меня
  </EButton>
</template>

📦 Установка

npm i -D @ecss/vue-adapter

pnpm add -D @ecss/vue-adapter

yarn add -D @ecss/vue-adapter

Требуется установленный vue версии 3.3 или выше.

🚀 Подключение

Адаптер регистрируется в ecss.config.ts через defineConfig из @ecss/config — конфиг не привязан к конкретному сборщику, его читает ECSS-плагин вашего бандлера (@ecss/vite-plugin и др.). defaultAdapter указывает, какой адаптер применяется к .ecss-файлам по умолчанию; id Vue-адаптера — 'vue':

// ecss.config.ts
import { defineConfig } from '@ecss/config';
import { vueAdapter } from '@ecss/vue-adapter';

export default defineConfig({
  adapters: [vueAdapter()],
  defaultAdapter: 'vue',
});

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

Каждый @block превращается в функциональный компонент Vue 3, который импортируется напрямую из .ecss-файла:

<script setup lang="ts">
import { EButton } from './Button.ecss';
</script>

<template>
  <EButton as="button" :params="{ variant: 'primary' }"> Нажми меня </EButton>
</template>

Имя компонента — это префикс + имя блока: @block Button → EButton, @block Card → ECard. Содержимое компонента передаётся через слот по умолчанию (всё, что между тегами).

Проп params

Параметры блока передаются единственным пропом params (в шаблоне — через привязку :params). TypeScript знает их типы из сгенерированного интерфейса {Block}Params (например ButtonParams), поэтому передать несуществующее значение enum не получится.

params обязателен ровно тогда, когда у блока есть хотя бы один обязательный @param (без ?). Если все параметры опциональны или их нет вовсе — проп можно не передавать.

<!-- у Button есть обязательный @param variant → params обязателен -->
<EButton :params="{ variant: 'primary' }" />

<!-- у Card все параметры опциональны → params можно опустить -->
<ECard />

Проп as

По умолчанию компонент рендерится как <div>. Проп as принимает любой HTML-тег и меняет корневой элемент. Компонент типизирован generic-параметром по выбранному тегу (через IntrinsicElementAttributes), поэтому набор допустимых HTML-атрибутов сужается автоматически:

<EButton
  as="button"
  type="submit"
  :params="{ variant: 'primary' }"
>Отправить</EButton>

<EButton as="a" href="/about" :params="{ variant: 'ghost' }">Ссылка</EButton>

При as="a" становятся доступны href, target и прочие атрибуты <a>; при as="button" — type, disabled и т.д.

class, style и атрибуты

ECSS задаёт корневому элементу класс блока, CSS-переменные из params и data-атрибуты. Всё, что передаёт потребитель, прокидывается на корневой элемент через стандартный механизм проброса атрибутов Vue (inheritAttrs):

• class — потребительский класс умно объединяется с классом блока, не затирая его;
• style — мёрджится поверх CSS-переменных, сгенерированных из params;
• остальные атрибуты и обработчики (id, aria-*, data-*, @click, …) попадают на корневой элемент как есть.

🧩 Суб-компоненты (@element)

Если в @block объявлены @element, они становятся вложенными компонентами через статические свойства корневого компонента и доступны в шаблоне через точечную нотацию:

<EButton :params="{ withIcon: true }">
  <EButton.Icon>
    <svg><!-- … --></svg>
  </EButton.Icon>
  <EButton.Text>Нажми меня</EButton.Text>
</EButton>

Суб-компоненты поддерживают тот же проп as (по умолчанию <div>), но не принимают params.

⚙️ Опции

vueAdapter({
  componentNamePrefix: 'E', // по умолчанию 'E'
});

| Опция | Тип | По умолчанию | Описание | | --------------------- | -------- | ------------ | ------------------------------------------------------------------------------ | | componentNamePrefix | string | 'E' | Префикс имени компонента. Первый символ — [A-Z], остальные — [a-zA-Z0-9_]. |

vueAdapter({ componentNamePrefix: 'My' }); // → MyButton, MyCard

Некорректный префикс (не подходящий под /^[A-Z][a-zA-Z0-9_]*$/) приводит к ошибке на этапе сборки.

🟢 Требования

Адаптер генерирует функциональные компоненты Vue 3. Требуется Vue 3.3 или выше: типизация опирается на IntrinsicElementAttributes и обобщённую сигнатуру функционального компонента, которые vue-tsc корректно разрешает в шаблонах начиная с версии 3.3.

👨‍💻 Автор

Разработка и поддержка: Руслан Мартынов

Если нашёл баг или есть предложение — открывай issue или отправляй pull request.

📄 Лицензия

Распространяется под лицензией MIT.