Svelte

@ecss/svelte-adapter генерирует типизированные компоненты Svelte (4 и 5) из объявлений @block и @element. id адаптера — 'svelte'.

В отличие от React/Vue-адаптеров, Svelte-адаптер module-based: он генерирует настоящие .svelte-файлы в каталог .ecss/svelte/, а импорт ./X.ecss перенаправляется на них ECSS-плагином автоматически. Для вас это прозрачно — компонент импортируется из .ecss-файла как обычно.

Установка

npm

npm i -D @ecss/svelte-adapter

pnpm

pnpm add -D @ecss/svelte-adapter

yarn

yarn add -D @ecss/svelte-adapter

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

Подключение

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

// ecss.config.ts
import { defineConfig } from '@ecss/config';
import { svelteAdapter } from '@ecss/svelte-adapter';

export default defineConfig({
  adapters: [svelteAdapter()],
  defaultAdapter: 'svelte',
});

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

Каждый @block превращается в компонент Svelte, который импортируется напрямую из .ecss-файла. Имя компонента формируется как {префикс}{BlockName} (по умолчанию префикс E): @block Button → EButton. Содержимое передаётся через слот по умолчанию.

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

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

Проп params

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

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

<EButton params={{ variant: 'primary' }} /> <!-- variant обязателен -->
<ECard />                                    <!-- у Card все параметры опциональны -->

Проп as

По умолчанию компонент рендерится как <div>. Проп as принимает любой HTML-тег и меняет корневой элемент. В Svelte 5 тип сужается по выбранному тегу (через generics + SvelteHTMLElements), поэтому доступны соответствующие атрибуты:

<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-атрибуты. То, что передаёт потребитель, объединяется с этими значениями:

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

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

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

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

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

Опции

Единственная опция фабрики — componentNamePrefix (префикс имени компонента, по умолчанию 'E'): svelteAdapter({ componentNamePrefix: 'My' }) → MyButton. Подробнее — в обзоре адаптеров.

Поддержка версий Svelte

Адаптер определяет мажорную версию Svelte, установленного в проекте, и генерирует соответствующий код:

• Svelte 5 — компоненты на рунах ($props, $derived), слот через {@render children?.()}; события — обычные атрибуты (onclick, oninput, …).
• Svelte 4 — export let + реактивные объявления $:, слот через <slot />; все события (on:click, on:input, …) автоматически перенаправляются на корневой элемент.

Версия читается из svelte/package.json относительно корня проекта и кешируется. Если Svelte не удаётся разрешить, адаптер выводит предупреждение и использует Svelte 5 как значение по умолчанию.

См. также

• Конфигурация — опции adapters и defaultAdapter
• @block — объявление блоков
• @element — суб-компоненты
• @param — параметры и их типы
• Типы данных — типы значений параметров