From f525c4f8ae4f80044fc613f44036a8b66c72b45e Mon Sep 17 00:00:00 2001 From: "S.Gromov" Date: Fri, 30 Jan 2026 12:14:53 +0300 Subject: [PATCH] sync --- .vitepress/cache/deps/_metadata.json | 12 ++--- AGENTS.md | 38 +++++++++++++ parts/1-tech-stack.md | 1 + parts/8-components.md | 80 ++++++++++++++++++++++++++++ 4 files changed, 125 insertions(+), 6 deletions(-) create mode 100644 AGENTS.md diff --git a/.vitepress/cache/deps/_metadata.json b/.vitepress/cache/deps/_metadata.json index 6f83d47..ca0db82 100644 --- a/.vitepress/cache/deps/_metadata.json +++ b/.vitepress/cache/deps/_metadata.json @@ -1,25 +1,25 @@ { - "hash": "89603b55", - "configHash": "8cb3bfba", + "hash": "328a40d6", + "configHash": "755e8183", "lockfileHash": "5778a81f", - "browserHash": "39b85539", + "browserHash": "9485839a", "optimized": { "vue": { "src": "../../../node_modules/vue/dist/vue.runtime.esm-bundler.js", "file": "vue.js", - "fileHash": "a740251a", + "fileHash": "2c01c408", "needsInterop": false }, "vitepress > @vue/devtools-api": { "src": "../../../node_modules/@vue/devtools-api/dist/index.js", "file": "vitepress___@vue_devtools-api.js", - "fileHash": "35102a70", + "fileHash": "668fe053", "needsInterop": false }, "vitepress > @vueuse/core": { "src": "../../../node_modules/@vueuse/core/index.mjs", "file": "vitepress___@vueuse_core.js", - "fileHash": "c5cd7aa4", + "fileHash": "adb8a37f", "needsInterop": false } }, diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..200317b --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,38 @@ +# Repository Guidelines + +## Назначение репозитория +Этот репозиторий хранит документацию и правила разработки фронтенд‑проектов (React/Next.js, TypeScript) и публикуется через VitePress. Контент пишется на русском языке. Сейчас ведётся рефакторинг документации: цель — краткие, чёткие и не дублирующиеся правила. + +## Project Structure & Module Organization +- `index.md` — главная страница документации. +- `parts/` — разделы документации, один файл на тему. Именование: `N-title.md` в `kebab-case` (например, `3-code-style.md`). +- `.vitepress/config.ts` — конфигурация VitePress и sidebar; добавляя новый раздел, обновляйте список ссылок. +- `RULES.md` — агрегированный документ, собирается из `parts/`. +- `concat-md.js` — скрипт сборки `RULES.md`. +- `OLD_parts/` — архив старой документации, используется только как справочник при переносе идей. + +## Build, Test, and Development Commands +- `npm install` — установка зависимостей. +- `npm run dev` — локальный сервер VitePress (обычно http://localhost:5173). +- `npm run build` — сборка статического сайта. +- `npm run serve` — предпросмотр собранной статики. +- `npm run docs` — пересборка `RULES.md` из `parts/`. + +## Coding Style & Naming Conventions +- Язык документации — русский. +- Для новых разделов придерживайтесь нумерации и `kebab-case` в именах файлов. +- В примерах кода ориентируйтесь на правила из `RULES.md`: отступ 2 пробела, одинарные кавычки в TS, двойные в JSX, `import type` для типов, избегать `default` экспортов. + +## Принципы рефакторинга документации +- Один смысл — один раздел. Не размазывайте правила по нескольким файлам. +- Если правило уже описано (например, нейминг), не повторяйте его в других разделах — добавляйте недостающее только в профильный файл. +- При переносе из `OLD_parts/` переписывайте кратко и по делу, исключая устаревшее и дубли. +- Новые правила добавляйте только в подходящий раздел; если такого нет — создайте его и обновите sidebar. + +## Testing Guidelines +Тестовая инфраструктура отсутствует. Если добавляете тесты или проверяющие скрипты, добавьте соответствующий `npm`‑скрипт и опишите его в этом документе. + +## Commit & Pull Request Guidelines +- История коммитов содержит короткие однословные сообщения (например, `sync`, `first`) — формального стандарта не видно. +- Для PR: укажите цель изменений, список затронутых разделов и отметьте, обновляли ли `RULES.md` и `sidebar`. +- Если меняется структура документации или навигация, приложите краткий скриншот/описание результата. diff --git a/parts/1-tech-stack.md b/parts/1-tech-stack.md index 5a943d2..5ab3cbb 100644 --- a/parts/1-tech-stack.md +++ b/parts/1-tech-stack.md @@ -16,5 +16,6 @@ title: Технологии и библиотеки - **Zustand** — глобальное состояние. - **i18next (i18n)** — локализация всех пользовательских текстов. - **Vitest** — тестирование. +- **clsx** — конкатенация CSS‑классов. - **PostCSS Modules** — изоляция стилей. - **Mobile First** — подход к адаптивной верстке. diff --git a/parts/8-components.md b/parts/8-components.md index e69de29..5d21823 100644 --- a/parts/8-components.md +++ b/parts/8-components.md @@ -0,0 +1,80 @@ +# Компоненты + +Раздел описывает правила создания UI‑компонентов. Эти правила обязательны для всех слоёв FSD: `app`, `screens`, `layouts`, `widgets`, `features`, `entities`, `shared`. + +## Базовая структура компонента + +Минимальный набор файлов: компонент, стили, типы и публичный экспорт. + +```text +container/ +├── styles/ +│ └── container.module.scss +├── types/ +│ └── container.interface.ts +├── container.ui.tsx +└── index.ts +``` + +## Пример базового компонента + +`styles/container.module.scss` +```scss +.root {} +``` +В CSS Modules использование имени класса **.root** — это общепринятое соглашение (best practice) + +`types/container.interface.ts` +```ts +import type { HTMLAttributes } from 'react' + +/** + * Параметры контейнера. + */ +export interface ContainerProps extends HTMLAttributes {} +``` +Интерфес параметров компонента всегда наследует свойства своего тега: div, button, итд.. + +`container.ui.tsx` + +```tsx +import type { FC } from 'react' +import { cl } from 'clsx' +import type { ContainerProps } from './types/container.interface' +import styles from './styles/container.module.scss' + +/** + * Контейнер с адаптивной максимальной шириной. + * + * Используется для: + * - ограничения ширины контента + * - центрирования содержимого + * - построения адаптивной сетки страницы + */ +export const Container: FC = ({ className, ...htmlAttr }) => { + return ( +
+ Container... +
+ ) +} +``` + +- Компонент объявляется через `const` и экспортируется именованно. +- Пропсы деструктурируются в сигнатуре; если их больше двух — деструктуризацию переносим в тело компонента. +- Из пропсов отдельно извлекаются `className` и `...htmlAttr`, чтобы корректно объединять классы и прокидывать остальные атрибуты. +- `cl` — короткое имя функции для конкатенации CSS‑классов. +- `FC<>` используется для декларации `children`. + +`index.ts` + +```ts +export { Container } from './container.ui' +``` + + +## Вложенные (дочерние) компоненты + +Если для реализации функционала нужны компоненты, которые используются только внутри текущего компонента, создавайте их как вложенные в папке `ui/`. Такие компоненты не экспортируются наружу и используются только локально. + +Вложенные компоненты подчиняются тем же правилам по структуре, именованию и стилю (включая папку `styles/` для их стилей).