sync

2026-07-22 04:40:17 +03:00 · 2026-07-15 12:27:46 +03:00
parent ab7042001a
commit 44afec7cdb
35 changed files with 1056 additions and 1224 deletions
--- a/docs/ru/reference/programmatic-api.md
+++ b/docs/ru/reference/programmatic-api.md
@@ -14,6 +14,21 @@ const result = await generateSprite(
 )
 ```

+Результат содержит имя и mode спрайта, количество иконок и абсолютные filesystem paths:
+
+```ts
+result.name
+result.mode
+result.target
+result.iconCount
+result.rootDir
+result.generatedDir
+result.spritePath
+result.manifestPath
+```
+
+Next.js modes дополнительно возвращают `router` и `bundler`.
+
 Для static standalone mode `result.spritePath` можно использовать в build-скрипте,
 чтобы опубликовать SVG по URL приложения:

@@ -29,7 +44,7 @@ await copyFile(result.spritePath, 'dist/app-icons/sprite.svg')
 `spritePath` является filesystem path, а не browser URL. Deployment-neutral JSON
 manifest доступен через `result.manifestPath` и копируется независимо от SVG.

-Первый аргумент принимает полный путь к config-файлу с любым именем и расширением `.ts`, `.js` или `.json`. Каталог вместо файла включает config-less режим: корнем sprite-модуля становится этот каталог.
+Первый аргумент принимает абсолютный или относительный путь к config-файлу с любым именем и расширением `.ts`, `.js` или `.json`. Каталог вместо файла включает config-less режим: корнем sprite-модуля становится этот каталог.

 Второй аргумент содержит необязательные overrides и всегда имеет приоритет над конфигом:

@@ -107,13 +122,17 @@ await generateNextSprite('path/to/config.ts', {

 ```ts
 import {
+  isSpriteMode,
  loadSpriteConfig,
  resolveSpriteConfig,
+  resolveSpriteConfigSource,
  validateSpriteConfig,
 } from '@gromlab/svg-sprites'
 ```

+- `isSpriteMode(value)` проверяет, является ли значение поддерживаемым exact mode.
 - `loadSpriteConfig(file)` загружает явно указанный `.ts`, `.js` или `.json` файл.
+- `resolveSpriteConfigSource(source)` разрешает путь как config-файл или config-less каталог.
 - `validateSpriteConfig(value)` выполняет runtime-валидацию объекта.
 - `resolveSpriteConfig(root, config, overrides)` объединяет значения, добавляет defaults и разрешает пути относительно `root`.

@@ -138,6 +157,16 @@ import type { SpriteViewerElement } from '@gromlab/svg-sprites/viewer'

 Browser entry регистрирует `<gromlab-sprite-viewer>`. Bare standalone также может загрузить самостоятельный `dist/viewer-element.js` без bundler.

+Для ручной регистрации импортируйте runtime без auto-register entry:
+
+```ts
+import { defineSpriteViewerElement } from '@gromlab/svg-sprites/viewer'
+
+defineSpriteViewerElement()
+```
+
+Этот entry также экспортирует типы `SpriteViewerElement`, `SpriteViewerManifest`, `SpriteViewerSource`, `SpriteViewerSources` и связанные типы manifest и loaders.
+
 React bridge сохраняет компонентный API:

 ```tsx
--- a/docs/ru/reference/technical.md
+++ b/docs/ru/reference/technical.md
@@ -2,6 +2,8 @@

 [Индекс документации](../README.md)

+[Конфигурация JSON, JavaScript и TypeScript](../configuration.md)
+
 Справочник по конфигурации, generated API и поведению `@gromlab/svg-sprites`. Пошаговую установку смотрите в руководстве для вашего стека:

 - [Bare standalone](../guides/standalone.md)
@@ -24,7 +26,7 @@
 Для генерации не нужна dependency проекта. Запускайте CLI через `npx`:

 ```bash
-npx --yes --package=@gromlab/svg-sprites@latest svg-sprites path/to/svg-sprite.config.ts
+npx --yes @gromlab/svg-sprites path/to/svg-sprite.config.json
 ```

 Устанавливайте пакет как development dependency, только если проекту нужны
@@ -36,7 +38,7 @@ npm install --save-dev @gromlab/svg-sprites

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

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

 ```text
 svg-sprites [options] <config-file-or-directory>
@@ -54,11 +56,11 @@ svg-sprites [options] <config-file-or-directory>
 | Next.js Pages Router + Turbopack | `next@pages/turbopack` |
 | Next.js Pages Router + Webpack 5 | `next@pages/webpack` |

-Config-файл может иметь любое имя и расширение `.ts`, `.js` или `.json`. CLI не ищет конфиг по соглашению: файл нужно передать явно. В руководствах используется рекомендуемое имя `svg-sprite.config.ts`.
+Config-файл может иметь любое имя и расширение `.ts`, `.js` или `.json`. CLI не ищет конфиг по соглашению: файл нужно передать явно. В руководствах используется рекомендуемое имя `svg-sprite.config.json`.

 Если передан каталог, все настройки берутся из CLI. Если передан config-файл, CLI-параметры перекрывают значения файла. Общий порядок: `defaults → config → CLI`.

-Доступны `--mode`, `--name`, `--description`, повторяемый `--input <path-or-glob>`, а также пары `--remove-size`/`--no-remove-size`, `--replace-colors`/`--no-replace-colors`, `--add-transition`/`--no-add-transition` и `--generated-notice`/`--no-generated-notice`. Переданные transform-флаги перекрывают отдельные поля, а хотя бы один `--input` полностью заменяет значение `input` из config.
+`--help` и `-h` выводят справку без обязательного пути. Для генерации доступны `--mode`, `--name`, `--description`, повторяемый `--input <path-or-glob>`, а также пары `--remove-size`/`--no-remove-size`, `--replace-colors`/`--no-replace-colors`, `--add-transition`/`--no-add-transition` и `--generated-notice`/`--no-generated-notice`. Переданные transform-флаги перекрывают отдельные поля, а хотя бы один `--input` полностью заменяет значение `input` из config.

 В CLI заключайте glob-паттерны в одинарные кавычки, чтобы shell не раскрыл их до запуска генератора:

@@ -96,7 +98,7 @@ export default defineSpriteConfig({
 | Опция | Тип | По умолчанию | Назначение |
 |---|---|---|---|
 | `mode` | `SpriteMode` | Нет | Режим генерации; можно передать через CLI/API |
-| `name` | `string` | Выводится из каталога | Имя спрайта, компонента и публичных типов |
+| `name` | `string` | Выводится из каталога | Имя спрайта; в modes с компонентом также задаёт имя компонента и публичных типов |
 | `description` | `string` | Нет | Описание для типов и debug manifest |
 | `input` | `string \| string[]` | `./icons` | Папки, SVG-файлы и glob-паттерны относительно папки конфига |
 | `transform` | `TransformOptions` | Все включены | Настройки подготовки SVG |
@@ -111,7 +113,7 @@ app          → AppIcon
 file-manager → FileManagerIcon
 ```

-Если `name` не задано, генератор выводит его из каталога. Для каталога с именем `svg-sprite` или `svg-sprites` используется имя родительского каталога.
+Если `name` не задано, генератор преобразует имя каталога в kebab-case. Для каталога с именем `svg-sprite` или `svg-sprites` используется имя родительского каталога.

 ### Источники иконок

@@ -141,7 +143,7 @@ file-manager → FileManagerIcon
 ```text
 app-icons/
 ├── .gitignore
-├── svg-sprite.config.ts
+├── svg-sprite.config.json
 ├── index.ts                         # необязательный пользовательский barrel
 └── .svg-sprite/
    ├── index.js
@@ -183,10 +185,10 @@ runtime asset и deployment-neutral manifest data:
 generated Web Component без внешних runtime-зависимостей. Bare `standalone`
 намеренно не создаёт JavaScript-компонент.

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

 ```ts
-export * from './.svg-sprite'
+export * from './.svg-sprite/index.js'
 ```

 ## Standalone Web Component и TypeScript
@@ -307,7 +309,7 @@ folder open.svg → icon="folder open" → id="icon-<stable-hash>"

 ## Множественные спрайты

-Каждый каталог с конфигом создаёт независимый компонент, типы, manifest и SVG asset:
+Каждый каталог с конфигом создаёт независимый mode-specific контракт. React и Next.js создают React-компонент и типы, `standalone@vite` и `standalone@webpack` — Web Component и типы, а bare `standalone` — SVG и JSON manifest:

 ```text
 app-icons       → AppIcon       → общие иконки
@@ -353,7 +355,7 @@ Static HTML после публикации `.svg-sprite/sprite.svg` прило
 </svg>
 ```

-Standalone Vite/Webpack предоставляет generated `getIconsIconHref()` и mapping
+Standalone Vite/Webpack предоставляет generated `getAppIconHref()` и mapping
 внутренних IDs. Не конструируйте fragment из небезопасного имени файла вручную.

 Vite:
@@ -602,7 +604,7 @@ Viewer показывает группы, поиск, `viewBox`, CSS-перем
 ```json
 {
  "scripts": {
-    "sprites": "npx --yes --package=@gromlab/svg-sprites@latest svg-sprites src/ui/app-icons/svg-sprite.config.ts",
+    "sprites": "npx --yes @gromlab/svg-sprites src/ui/app-icons/svg-sprite.config.ts",
    "predev": "npm run sprites",
    "prebuild": "npm run sprites",
    "pretypecheck": "npm run sprites"
@@ -610,22 +612,22 @@ Viewer показывает группы, поиск, `viewBox`, CSS-перем
 }
 ```

-CI должен выполнять generation script до сборки или проверки типов. Для воспроизводимости замените `latest` на точную версию. Локальная установка package не нужна, если CI не использует Viewer, package-типы config или программный API.
+CI должен выполнять generation script до сборки или проверки типов. Локальная установка package не нужна, если CI не использует Viewer, package-типы config или программный API.

-Bare `standalone` не создаёт и не изменяет `.gitignore`: приложение само решает, коммитить или игнорировать его `.svg-sprite/`. В остальных modes генератор не перезапишет пользовательский `.gitignore`. Он также откажется перезаписывать пользовательский файл внутри `.svg-sprite`. Корневой `index.ts` остаётся пользовательским и может переэкспортировать generated API.
+Bare `standalone` не создаёт `.gitignore` и сохраняет пользовательский файл. Если после другого mode остался управляемый `.gitignore`, bare mode удалит его. В остальных modes генератор откажется перезаписать пользовательский `.gitignore` без generated marker. Корневой `index.ts` остаётся пользовательским и может переэкспортировать generated API.

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

- Нет `.svg-sprite/index.js`: запустите generation script до импорта generated-модуля.
+- Для всех modes, кроме bare `standalone`: если нет `.svg-sprite/index.js`, запустите generation script до импорта generated-модуля.
 - Не найден источник: передайте существующий config-файл или каталог sprite-модуля.
 - Не указан mode: добавьте `mode` в config либо передайте `--mode`.
 - Иконка отсутствует в типе: проверьте `input`, расширение `.svg`, glob-исключения и необходимость `**/*.svg` для вложенных папок.
 - Конфликт имени: два разных SVG имеют одинаковый basename; переименуйте один файл.
- `Refusing to overwrite a user file`: в managed-пути находится файл без generated marker.
+- `Refusing to overwrite a user file`: в корне sprite-модуля находится пользовательский `.gitignore`, который генератор не может заменить.
 - Иконка не меняет цвет: используйте `<svg><use>` или generated-компонент и проверьте `replaceColors`.
 - Webpack выдаёт неверный URL: проверьте Asset Modules, `output.publicPath` и SVG loaders.
 - Static sprite возвращает 404: проверьте post-generation copy или server alias и не передавайте filesystem `spritePath` в HTML.
- Viewer не видит спрайт: проверьте путь к `.svg-sprite/svg-sprite.manifest.js` и выполните генерацию до запуска приложения.
+- Viewer не видит спрайт: для bundler modes проверьте путь к `.svg-sprite/svg-sprite.manifest.js`; для bare `standalone` — URL опубликованных `svg-sprite.manifest.json` и `sprite.svg`. Выполните генерацию до запуска приложения.
 - Build и mode не совпадают: используйте target, соответствующий фактическому сборщику.

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