docs: обновить документацию generated-контракта

- описаны единая конфигурация и exact modes - обновлена структура .svg-sprite - удалены материалы legacy pipeline - синхронизированы русская и английская версии skill
2026-07-22 04:40:17 +03:00 · 2026-07-13 20:07:42 +03:00
parent f4f464a568
commit 7992adc9d3
55 changed files with 618 additions and 2168 deletions
--- a/docs/ru/reference.md
+++ b/docs/ru/reference.md
@@ -8,7 +8,6 @@
 - [Next.js Pages Router](next-pages.md)
 - [React + Vite](react-vite.md)
 - [React + Webpack 5](react-webpack.md)
- [Нативный HTML и классические SVG-спрайты](legacy.md)

 ## Требования

@@ -25,10 +24,10 @@ npm install --save-dev @gromlab/svg-sprites

 ## CLI и режимы генерации

-CLI принимает один режим и путь к каталогу конфигурации:
+CLI принимает ровно один путь: явно выбранный config-файл либо каталог для config-less генерации:

 ```text
-svg-sprites --mode <mode> <path>
+svg-sprites [options] <config-file-or-directory>
 ```

 | Среда | Mode |
@@ -39,20 +38,24 @@ svg-sprites --mode <mode> <path>
 | Next.js App Router + Webpack 5 | `next@app/webpack` |
 | Next.js Pages Router + Turbopack | `next@pages/turbopack` |
 | Next.js Pages Router + Webpack 5 | `next@pages/webpack` |
-| Классические `stack`- и `symbol`-спрайты | `legacy` |

-Современные React- и Next.js-режимы используют локальный `svg-sprite.config.ts`. Legacy-режим использует отдельный `svg-sprites.config.ts` и описан в [собственном руководстве](legacy.md).
+Config-файл может иметь любое имя и расширение `.ts`, `.js` или `.json`. CLI не ищет конфиг по соглашению: файл нужно передать явно. В руководствах используется рекомендуемое имя `svg-sprite.config.ts`.
+
+Если передан каталог, все настройки берутся из CLI. Если передан config-файл, CLI-параметры перекрывают значения файла. Общий порядок: `defaults → config → CLI`.
+
+Доступны `--mode`, `--name`, `--description`, `--input-folder`, повторяемый `--input-file`, а также пары `--remove-size`/`--no-remove-size`, `--replace-colors`/`--no-replace-colors`, `--add-transition`/`--no-add-transition` и `--generated-notice`/`--no-generated-notice`. Переданные transform-флаги перекрывают отдельные поля, а хотя бы один `--input-file` заменяет весь массив `inputFiles` из config.

 Mode должен соответствовать сборщику приложения. Генератор создаёт разный способ подключения SVG asset для Vite и сборщиков, совместимых с Webpack Asset Modules.

-## Конфигурация React и Next.js
+## Единая конфигурация

-Каждый каталог с `svg-sprite.config.ts` описывает один независимый спрайт.
+Каждый config-файл описывает один независимый спрайт.

 ```ts
-import { defineNextSpriteConfig } from '@gromlab/svg-sprites'
+import { defineSpriteConfig } from '@gromlab/svg-sprites'

-export default defineNextSpriteConfig({
+export default defineSpriteConfig({
+  mode: 'next@app/turbopack',
  name: 'app',
  description: 'Общие иконки приложения',
  inputFolder: './local-icons',
@@ -69,18 +72,13 @@ export default defineNextSpriteConfig({
 })
 ```

-Для React используйте `defineReactSpriteConfig`. Контракт конфигурации одинаковый:
-
-```ts
-import { defineReactSpriteConfig } from '@gromlab/svg-sprites'
-```
-
 | Опция | Тип | По умолчанию | Назначение |
 |---|---|---|---|
+| `mode` | `SpriteMode` | Нет | Режим генерации; можно передать через CLI/API |
 | `name` | `string` | Выводится из каталога | Имя спрайта, компонента и публичных типов |
 | `description` | `string` | Нет | Описание для типов и debug manifest |
-| `inputFolder` | `string` | `./icons` | Каталог с SVG относительно конфига |
-| `inputFiles` | `string[]` | `[]` | Пути к отдельным SVG относительно конфига |
+| `inputFolder` | `string` | `./icons` | Каталог с SVG относительно корня модуля |
+| `inputFiles` | `string[]` | `[]` | Пути к отдельным SVG относительно корня модуля |
 | `transform` | `TransformOptions` | Все включены | Настройки подготовки SVG |
 | `generatedNotice` | `boolean` | `true` | Полное или короткое предупреждение в generated-файлах |

@@ -112,28 +110,41 @@ file-manager → FileManagerIcon
 ```text
 app-icons/
 ├── .gitignore
-├── index.ts
-├── manifest.ts
 ├── svg-sprite.config.ts
-└── generated/
-    ├── .svg-sprites.manifest.json
-    ├── react-component.tsx
+├── index.ts                         # необязательный пользовательский barrel
+└── .svg-sprite/
+    ├── state.json
+    ├── index.js
+    ├── index.d.ts
+    ├── icon-data.js
+    ├── icon-data.d.ts
    ├── sprite.svg
-    ├── styles.module.css
-    └── types.ts
+    ├── svg-sprite.manifest.js
+    ├── svg-sprite.manifest.d.ts
+    └── react/
+        ├── react-component.js
+        ├── react-component.d.ts
+        └── react-component.module.css
 ```

 | Файл | Назначение |
 |---|---|
-| `index.ts` | Production exports компонента, props, стилей и имён иконок |
-| `manifest.ts` | Debug metadata и URL asset для `SpriteViewer` |
-| `generated/sprite.svg` | Собранный SVG-спрайт |
-| `generated/react-component.tsx` | Типизированный React-компонент |
-| `generated/styles.module.css` | Базовые стили и transitions |
-| `generated/types.ts` | Runtime-список и union-тип имён |
-| `generated/.svg-sprites.manifest.json` | Список файлов, которыми управляет генератор |
+| `.svg-sprite/index.js` | Production exports компонента и runtime-списка имён |
+| `.svg-sprite/index.d.ts` | Публичные декларации компонента, props, стилей и union-типа имён |
+| `.svg-sprite/svg-sprite.manifest.js` | Debug metadata и URL asset для `SpriteViewer` |
+| `.svg-sprite/sprite.svg` | Собранный SVG-спрайт |
+| `.svg-sprite/react/react-component.js` | Runtime React-компонента без TypeScript и JSX |
+| `.svg-sprite/react/react-component.d.ts` | Props, style и declaration React-компонента |
+| `.svg-sprite/react/react-component.module.css` | Стили конкретной React-реализации |
+| `.svg-sprite/icon-data.js` | Runtime-список имён и внутренние IDs |
+| `.svg-sprite/*.d.ts` | TypeScript-декларации соответствующих JS-модулей |
+| `.svg-sprite/state.json` | Mode, версия контракта и список управляемых файлов |

-Генератор перезаписывает и удаляет только файлы со своим marker. Если в managed-пути находится пользовательский файл, генерация завершается ошибкой.
+Генератор перезаписывает и удаляет только файлы со своим marker. Если в managed-пути находится пользовательский файл, генерация завершается ошибкой. Корневой `index.ts` генератору не принадлежит; при необходимости создайте пользовательский barrel:
+
+```ts
+export * from './.svg-sprite'
+```

 ## React-компонент и TypeScript

@@ -224,12 +235,11 @@ editor-icons    → EditorIcon    → иконки редактора

 ## Форматы и способы отображения

-Современные React- и Next.js-режимы создают формат `stack`. Legacy-режим поддерживает `stack` и `symbol`.
+React- и Next.js-режимы создают формат `stack`.

 | Формат | `<svg><use>` | `<img>` | CSS background |
 |---|---:|---:|---:|
 | `stack` | Да | Да | Да |
-| `symbol` | Да | Нет | Нет |

 ### Generated-компонент

@@ -246,13 +256,13 @@ editor-icons    → EditorIcon    → иконки редактора
 Vite:

 ```ts
-import spriteUrl from './generated/sprite.svg?no-inline'
+import spriteUrl from './.svg-sprite/sprite.svg?no-inline'
 ```

 Webpack 5, Turbopack и Next.js:

 ```ts
-const spriteUrl = new URL('./generated/sprite.svg', import.meta.url).href
+const spriteUrl = new URL('./.svg-sprite/sprite.svg', import.meta.url).href
 ```

 После получения URL используйте его в JSX:
@@ -277,7 +287,7 @@ SVG внутри `<img>` изолирован от CSS страницы. `color`

 ```css
 .icon {
-  background: url('./generated/sprite.svg#search') center / contain no-repeat;
+  background: url('./.svg-sprite/sprite.svg#search') center / contain no-repeat;
 }
 ```

@@ -286,7 +296,7 @@ SVG внутри `<img>` изолирован от CSS страницы. `color`
 ```css
 .icon {
  background-color: currentColor;
-  mask: url('./generated/sprite.svg#search') center / contain no-repeat;
+  mask: url('./.svg-sprite/sprite.svg#search') center / contain no-repeat;
 }
 ```

@@ -300,7 +310,7 @@ Generated-компонент передаёт SVG сборщику как отд

 - Vite использует статический импорт с `?no-inline`;
 - Webpack 5, Turbopack и Next.js используют `new URL(..., import.meta.url)`;
- SVG path-данные не сериализуются в generated TSX.
+- SVG path-данные не сериализуются в generated JavaScript.

 При стандартном именовании assets сборщик добавляет content hash:

@@ -325,7 +335,8 @@ HTTP cache headers, CDN и `Cache-Control` настраиваются прило
 Чтобы отключить отдельную операцию:

 ```ts
-export default defineNextSpriteConfig({
+export default defineSpriteConfig({
+  mode: 'next@app/turbopack',
  transform: {
    removeSize: false,
    replaceColors: false,
@@ -399,7 +410,7 @@ import { SpriteViewer } from '@gromlab/svg-sprites/react'
 import type { SpriteManifestModule } from '@gromlab/svg-sprites/react'

 const sources = import.meta.glob<SpriteManifestModule>(
-  '/src/**/svg-sprite/manifest.ts',
+  '/src/**/svg-sprite/.svg-sprite/svg-sprite.manifest.js',
 )

 export const IconsDebugPage = () => (
@@ -411,8 +422,8 @@ Webpack и Next.js:

 ```tsx
 const sources = [
-  () => import('@/ui/app-icons/manifest'),
-  () => import('@/features/analytics/icons/manifest'),
+  () => import('@/ui/app-icons/.svg-sprite/svg-sprite.manifest.js'),
+  () => import('@/features/analytics/icons/.svg-sprite/svg-sprite.manifest.js'),
 ]

 export const IconsDebugPage = () => (
@@ -447,9 +458,7 @@ Viewer показывает группы, поиск, `viewBox`, CSS-перем
 Современный sprite-модуль создаёт локальный `.gitignore` для:

 ```text
-/generated/
-/index.ts
-/manifest.ts
+/.svg-sprite/
 ```

 Локальный `.gitignore` следует один раз добавить в репозиторий. Он исключает остальные generated-файлы, поэтому генерацию нужно запускать перед командами, которые импортируют sprite-модуль:
@@ -457,7 +466,7 @@ Viewer показывает группы, поиск, `viewBox`, CSS-перем
 ```json
 {
  "scripts": {
-    "sprites": "svg-sprites --mode next@app/turbopack src/ui/app-icons",
+    "sprites": "svg-sprites src/ui/app-icons/svg-sprite.config.ts",
    "predev": "npm run sprites",
    "prebuild": "npm run sprites",
    "pretypecheck": "npm run sprites"
@@ -467,18 +476,19 @@ Viewer показывает группы, поиск, `viewBox`, CSS-перем

 CI должен устанавливать development dependencies и выполнять generation script до сборки или проверки типов.

-Если в каталоге спрайта уже находится пользовательский `.gitignore`, `index.ts` или `manifest.ts`, генератор не перезапишет его. Переместите пользовательский файл или выберите отдельный каталог спрайта.
+Если в каталоге спрайта уже находится пользовательский `.gitignore` либо пользовательский файл внутри `.svg-sprite`, генератор не перезапишет его. Корневой `index.ts` остаётся пользовательским и может переэкспортировать generated API.

 ## Диагностика

- Нет `index.ts`: запустите generation script до импорта модуля.
- Не найдена конфигурация: проверьте путь CLI и имя `svg-sprite.config.ts`.
+- Нет `.svg-sprite/index.js`: запустите generation script до импорта generated-модуля.
+- Не найден источник: передайте существующий config-файл или каталог sprite-модуля.
+- Не указан mode: добавьте `mode` в config либо передайте `--mode`.
 - Иконка отсутствует в типе: проверьте `inputFiles`, расширение `.svg` и уровень вложенности `inputFolder`.
 - Конфликт имени: два разных SVG имеют одинаковый basename; переименуйте один файл.
 - `Refusing to overwrite a user file`: в managed-пути находится файл без generated marker.
 - Иконка не меняет цвет: используйте `<svg><use>` или generated-компонент и проверьте `replaceColors`.
 - Webpack выдаёт неверный URL: проверьте Asset Modules, `output.publicPath` и SVG loaders.
- Viewer не видит спрайт: проверьте путь к `manifest.ts` и выполните генерацию до запуска приложения.
+- Viewer не видит спрайт: проверьте путь к `.svg-sprite/svg-sprite.manifest.js` и выполните генерацию до запуска приложения.
 - Build и mode не совпадают: используйте target, соответствующий фактическому сборщику.

 Для собственного orchestration и низкоуровневой компиляции смотрите [Программный API](programmatic-api.md).