gromov/svg-sprites
1
0
Fork 0
mirror of https://github.com/gromlab-ru/svg-sprites.git synced 2026-07-22 04:40:17 +03:00
Code Issues Packages Projects Releases Wiki Activity
Files
b43814e57bb0094a5f26b23de9f9cb02d91f2e89
svg-sprites/AGENTS.md
S.Gromov 8b3365f957 feat: добавить поддержку 20 framework exact modes 
Добавлены exact modes:
- vue@vite и vue@webpack
- nuxt@vite и nuxt@webpack
- svelte@vite, svelte@webpack и sveltekit@vite
- angular@application и angular@webpack
- astro@vite
- solid@vite, solid@webpack и solid-start@vite
- preact@vite и preact@webpack
- qwik@vite
- lit@vite и lit@webpack
- alpine@vite и alpine@webpack

Для каждого mode реализованы изолированный adapter, нативный
framework-компонент, declarations, manifest, CSS и внешний asset URL.

Добавлены production integration-стенды с генерацией, typecheck,
сборкой и Playwright-проверкой рендера спрайта и Viewer.

Обновлены Viewer, RU/EN-гайды, README, technical reference и AI skills.
Итоговая матрица включает 29 exact modes.

Проверки:
- 48 unit-тестов
- 29 integration E2E-тестов
2026-07-15 16:56:44 +03:00

6.8 KiB
Raw Blame History

Архитектурные правила

Изоляция modes

Каждый полный mode key является независимым adapter со своим generated-контрактом:

  • react@vite;
  • react@webpack;
  • next@app/turbopack;
  • next@app/webpack;
  • next@pages/turbopack;
  • next@pages/webpack;
  • standalone;
  • standalone@vite;
  • standalone@webpack;
  • vue@vite;
  • vue@webpack;
  • nuxt@vite;
  • nuxt@webpack;
  • svelte@vite;
  • svelte@webpack;
  • sveltekit@vite;
  • angular@application;
  • angular@webpack;
  • astro@vite;
  • solid@vite;
  • solid@webpack;
  • solid-start@vite;
  • preact@vite;
  • preact@webpack;
  • qwik@vite;
  • lit@vite;
  • lit@webpack;
  • alpine@vite;
  • alpine@webpack;
  • будущие exact modes.

Для каждого exact mode используется отдельный каталог src/modes/<mode-slug>/. Adapter самостоятельно определяет:

  • compile options;
  • список и имена generated-файлов;
  • runtime JavaScript;
  • TypeScript declarations;
  • manifest source;
  • CSS;
  • способ получения asset URL;
  • mode-specific result metadata.

Изменение output одного mode не должно менять output другого mode. Дублирование component, manifest, declaration и CSS codegen между adapters является сознательной ценой изоляции.

Запрещено:

  • импортировать один src/modes/<exact>/ из другого mode;
  • создавать общий framework/component/manifest/CSS codegen для нескольких modes;
  • создавать общий runtime asset URL generator для нескольких modes;
  • ветвиться по generic target внутри adapter;
  • писать generated-файлы непосредственно из adapter через fs;
  • импортировать exact-mode adapters из core.

Единственное место, которое импортирует все adapters, — src/mode-registry.ts.

Общий core

Общими могут быть только mode-neutral данные и инфраструктура:

  • загрузка, merge и валидация config;
  • scanner исходных SVG;
  • shape IDs и проверка конфликтов;
  • низкоуровневый SVG compiler и transformations;
  • подготовка нейтрального compiled artifact;
  • protocol ModeAdapter/OutputPlan;
  • проверка output paths;
  • staged directory writer и symlink protection;
  • logger и базовые result types.

Core не генерирует JavaScript, declarations, manifest source, CSS или framework-specific exports. Изменение общего compiler может ожидаемо изменить SVG всех modes; изменение generated source должно быть локально одному adapter.

Generated-контракт

Один config разрешается ровно в один mode и один output. Множественные modes не генерируются в один root; orchestration выполняется независимыми config/API/CLI вызовами.

Каждый adapter генерирует один нативный для фреймворка runtime-контракт, совместимый со стандартными JavaScript- и TypeScript-конфигурациями этого фреймворка. Предпочтительный output — ESM JavaScript; если framework compiler требует собственный формат, допускаются framework-native контейнеры с JavaScript-синтаксисом (.jsx, .svelte, .astro и аналогичные). .tsx и TypeScript runtime запрещены, кроме frameworks вроде Angular, чей штатный production toolchain требует TypeScript. Типизация всегда добавляется отдельными .d.ts; отдельные JS- и TS-реализации одного компонента не создаются.

Integration-стенд должен собирать runtime как JavaScript-потребитель без дополнительной TypeScript-настройки, когда framework это допускает. TypeScript-совместимость того же generated API проверяется отдельным type probe внутри стенда. Framework-native adapter нельзя подменять consumer-примером другого mode или Web Component facade.

Core writer полностью владеет каталогом .svg-sprite и при каждой генерации заменяет его через временный каталог с rollback при ошибке. Корневым .gitignore writer владеет, когда exact-mode adapter запрашивает его через OutputPlan. Bare standalone не создаёт .gitignore; остальные modes создают.

Sprite-level asset, icon data, manifest и facade лежат непосредственно в .svg-sprite/. standalone@vite и standalone@webpack генерируют нативный icon Web Component внутри своего facade; bare standalone остаётся без JavaScript runtime. Framework runtime группируется отдельно: React adapters используют .svg-sprite/react/, будущие framework adapters получают собственный framework-каталог.

Adapter возвращает файлы в памяти. Только core writer проверяет paths, полностью заменяет .svg-sprite и обновляет управляемый .gitignore.

Зависимости

Допустимое направление импортов:

public API / CLI
  -> generate
  -> mode-registry
  -> один exact-mode adapter
  -> core protocols and services

Обратные и горизонтальные зависимости запрещены:

core -X-> modes
mode A -X-> mode B
mode A -X-> shared output codegen

src/viewer/ с Web Component является framework-neutral browser runtime пакета, а не mode adapter. src/react/ содержит только React bridge к этому runtime.

Изменение mode

При работе с adapter:

  1. Изменяйте только его каталог и mode-neutral protocol, если это действительно необходимо.
  2. Не переносите output-логику в core ради устранения дублирования.
  3. Не меняйте generated-контракты других adapters автоматически.
  4. Проверяйте отсутствие cross-mode imports.