diff --git a/.vitepress/config.ts b/.vitepress/config.ts index 74e28a9..3c43aaa 100644 --- a/.vitepress/config.ts +++ b/.vitepress/config.ts @@ -86,6 +86,7 @@ const sidebar = [ text: 'SVG-спрайты', collapsed: true, items: [ + { text: 'Введение', link: '/docs/applied/svg-sprites/svg-sprites-intro' }, { text: 'Настройка', link: '/docs/applied/svg-sprites/svg-sprites-setup' }, { text: 'Использование', link: '/docs/applied/svg-sprites/svg-sprites-usage' }, ], @@ -101,7 +102,8 @@ const sidebar = [ ], }, { text: 'Структура проекта', link: '/docs/applied/project-structure' }, - { text: 'Компоненты', link: '/docs/applied/components' }, + { text: 'Модуль', link: '/docs/applied/module' }, + { text: 'Компонент · в разработке' }, { text: 'Страницы (App Router)', link: '/docs/applied/page-level' }, // Неактивные разделы: страницы существуют, но пока пустые. // Оставляем в sidebar без `link`, чтобы видеть план, но без перехода. diff --git a/docs/docs/MAP.md b/docs/docs/MAP.md index fba7eeb..ae2cbeb 100644 --- a/docs/docs/MAP.md +++ b/docs/docs/MAP.md @@ -42,6 +42,7 @@ - [VS Code](./applied/vscode.md) — Единые настройки редактора и расширений для команды. - [Стили: Настройка](./applied/styles/styles-setup.md) — Подготовка стилевой основы проекта: токены, медиа-запросы, глобальные стили. - [Стили: Использование](./applied/styles/styles-usage.md) — Как пишутся стили в проекте. +- [SVG-спрайты](./applied/svg-sprites/svg-sprites-intro.md) — Что такое SVG-спрайты и какие проблемы они решают. - [SVG-спрайты: Настройка](./applied/svg-sprites/svg-sprites-setup.md) — Подключение SVG-спрайтов в новом проекте. - [SVG-спрайты: Использование](./applied/svg-sprites/svg-sprites-usage.md) — Как добавлять и использовать SVG-иконки в коде. - [Шаблоны генерации](./applied/templates/templates-intro.md) — Что такое шаблоны кодогенерации и какие проблемы они решают. @@ -49,5 +50,5 @@ - [Шаблоны генерации: Создание шаблонов](./applied/templates/templates-create.md) — Структура шаблонов, синтаксис переменных и примеры. - [Шаблоны генерации: Использование](./applied/templates/templates-usage.md) — Генерация файлов из шаблонов через VS Code плагин и CLI. - [Структура проекта](./applied/project-structure.md) — Из чего состоит проект и где что лежит. -- [Компоненты](./applied/components.md) — Как устроен и пишется React-компонент в проекте. +- [Модуль](./applied/module.md) — Как устроен и пишется React-компонент в проекте. - [Страницы (App Router)](./applied/page-level.md) — Что должно лежать в файлах роутинга, а что — в экранах. diff --git a/docs/docs/applied/component.md b/docs/docs/applied/component.md new file mode 100644 index 0000000..daf3c5e --- /dev/null +++ b/docs/docs/applied/component.md @@ -0,0 +1,4 @@ +--- +title: Компонент +description: Как устроен и пишется React-компонент в проекте. +--- diff --git a/docs/docs/applied/components.md b/docs/docs/applied/module.md similarity index 98% rename from docs/docs/applied/components.md rename to docs/docs/applied/module.md index 1717228..ea399a7 100644 --- a/docs/docs/applied/components.md +++ b/docs/docs/applied/module.md @@ -1,9 +1,9 @@ --- -title: Компоненты +title: Модуль description: Как устроен и пишется React-компонент в проекте. --- -# Компоненты +# Модуль Как устроен и пишется React-компонент в проекте. diff --git a/docs/docs/applied/svg-sprites/svg-sprites-intro.md b/docs/docs/applied/svg-sprites/svg-sprites-intro.md new file mode 100644 index 0000000..68c2797 --- /dev/null +++ b/docs/docs/applied/svg-sprites/svg-sprites-intro.md @@ -0,0 +1,31 @@ +--- +title: SVG-спрайты +description: "Что такое SVG-спрайты и какие проблемы они решают." +--- + +# SVG-спрайты + +Что такое SVG-спрайты и какие проблемы они решают. + +## Проблема + +Иконки в проекте — это десятки и сотни SVG-файлов, которые нужно как-то доставлять в интерфейс. Подход «один `` на иконку» или инлайн SVG в каждом компоненте приводят к трём проблемам: + +- **Дублирование.** Инлайн SVG в нескольких компонентах — один и тот же код размазан по проекту. Изменение иконки требует правок в десяти местах. +- **Размер бандла.** Каждый инлайн SVG — полный XML-код, который попадает в JS-бандл. Сотня иконок × средний размер SVG = сотни килобайт, которые браузер парсит как JavaScript, а не как статику. +- **Нет управления цветом.** Инлайн SVG жёстко закрашивает иконку. Сменить цвет по состоянию (`:hover`, `._disabled`) — значит дублировать SVG или городить `currentColor`-хаки в каждом компоненте. + +## Решение + +SVG-спрайты — это единый файл-контейнер, в который собираются все иконки проекта. В коде используется один React-компонент ``, а браузер загружает спрайт как статику — один раз, с кешированием. + +Что дают SVG-спрайты: + +- **Один источник.** Каждая иконка — один SVG-файл в `src/shared/sprites/`. Обновил файл — иконка обновилась везде. +- **Лёгкий бандл.** Спрайт отдаётся как статический файл из `public/`, не попадает в JavaScript. Типы имён иконок генерируются автоматически — автодополнение работает без ручных описаний. +- **Цвет через CSS.** При сборке цвета в SVG заменяются на CSS-переменные. Цвет иконки меняется через `color` родителя или через переменные `--icon-color-N` — как любой другой стиль. + +## Состав раздела + +- [Настройка](/docs/applied/svg-sprites/svg-sprites-setup) — подключение пакета, конфигурация, первая генерация. +- [Использование](/docs/applied/svg-sprites/svg-sprites-usage) — добавление иконок, компонент ``, управление цветом. diff --git a/docs/docs/applied/svg-sprites/svg-sprites-setup.md b/docs/docs/applied/svg-sprites/svg-sprites-setup.md index 0d927d2..3d44c82 100644 --- a/docs/docs/applied/svg-sprites/svg-sprites-setup.md +++ b/docs/docs/applied/svg-sprites/svg-sprites-setup.md @@ -15,7 +15,7 @@ keywords: [svg-sprites, установка, настройка, config, паке npm install @gromlab/svg-sprites ``` -2. Создать `svg-sprites.config.ts` в корне проекта (см. «Стандартный конфиг»). +2. Создать `svg-sprites.config.ts` в корне проекта (см. [Стандартный конфиг](#стандартныи-конфиг)). 3. Создать папку входа для SVG-файлов в слое `shared`: @@ -47,11 +47,38 @@ keywords: [svg-sprites, установка, настройка, config, паке /src/ui/svg-sprite/ ``` -6. Выполнить первую генерацию: + 6. Выполнить первую генерацию: - ```bash - npm run sprite - ``` + ```bash + npm run sprite + ``` + +7. Подключить спрайт в layout. Глобальный спрайт (иконки) подключается через `` в корневом layout — браузер загрузит файл заранее и закеширует: + + ```tsx + // src/app/layout.tsx + import 'shared/styles/global.css' + + import type { Metadata } from 'next' + + export const metadata: Metadata = { + title: 'App', + description: '', + } + + export default function RootLayout({ children }: { children: React.ReactNode }) { + return ( + + + + + {children} + + ) + } + ``` + + Локальные спрайты (если есть) подключаются аналогично в layout конкретной страницы или маршрута. ## Стандартный конфиг @@ -99,3 +126,7 @@ transform: { ### Режим По умолчанию `mode: 'stack'` — не указывать явно. Переход на `symbol` требует обоснования: превью и примеры в пакете оптимизированы под `stack`. + +## Дальше + +- [Использование](/docs/applied/svg-sprites/svg-sprites-usage) — добавление иконок, компонент ``, управление цветом.