docs: "Руководство по созданию core компонентов"#2486
Conversation
Yakutoc
added
plasma-docs
| └── base.ts | ||
| ``` | ||
|
|
||
| > **Примечание:** В вариациях могут присутствовать файлы `tokens.json` — они опциональны и используются для документирования, не влияют на работу компонента. |
There was a problem hiding this comment.
[note]: Вот тут не смог для себя вывести правило.
There was a problem hiding this comment.
@neretin-trike подскажи, будет ли это использоваться для билдера? Если нет, то такие файлы - рудемент
|
Theme Builder app deployed! https://plasma.sberdevices.ru/pr/plasma-theme-builder-pr-2486/ |
|
|
||
| Файл `MyComponent.tsx` — содержит layout-функцию (JSX-структуру) и конфигурацию компонента. | ||
|
|
||
| - **`RootProps<RefElement, Props>`** — тип из `../../engines`, описывающий корневой React-компонент, который engine создаёт на основе конфигурации. Первый параметр — тип HTML-элемента (должен соответствовать `tag` в конфигурации), второй — тип пропсов компонента. |
There was a problem hiding this comment.
[Note]: для RootProps тоже кажется можно лучше написать.
| }; | ||
| ``` | ||
|
|
||
| Приватные токены: |
There was a problem hiding this comment.
[Note]: на сколько это "наш" путь, мы действительно так пишем и хотим продолжать?
There was a problem hiding this comment.
Да, это удобнее, чем по нескольким файлам строки со значениями токенов сверять
Yakutoc
requested review from
TitanKuzmich,
Yeti-or,
neretin-trike and
shuga2704
as code owners
github-actions
Bot
removed request for
TitanKuzmich,
neretin-trike and
shuga2704
| Файл `MyComponent.tsx` — содержит layout-функцию (JSX-структуру) и конфигурацию компонента. | ||
|
|
||
| - **`RootProps<RefElement, Props>`** — тип из `../../engines`, описывающий корневой React-компонент, который engine создаёт на основе конфигурации. Первый параметр — тип HTML-элемента (должен соответствовать `tag` в конфигурации), второй — тип пропсов компонента. | ||
| - **`cx(...classes)`** — утилита из `../../utils`, аналог `classnames`/`clsx`. Объединяет строки и условные классы: `cx('a', false && 'b', 'c')` → `'a c'`. |
There was a problem hiding this comment.
Лишнее, надо убрать. Мы используем classnames
|
|
||
| --- | ||
|
|
||
| ### 8. Соберите компонент в вертикали |
There was a problem hiding this comment.
Кажется нужно описать еще компонент, у которого есть несколько конфигов и как через createConditionalComponent делать
|
|
||
| ``` | ||
| ┌─────────────────────────────────────────────────────────────┐ | ||
| │ Вертикали (15 брендов) │ |
There was a problem hiding this comment.
Может просто вертикали? Зачем тут динамическое количество брендов?
| │ sdds-serv, plasma-web, plasma-b2c, ... │ | ||
| │ ───────────────────────────────────────────────────────── │ | ||
| │ • Токены (цвета, размеры, отступы) │ | ||
| │ • Вариации view/size с конкретными значениями │ |
There was a problem hiding this comment.
| │ • Вариации view/size с конкретными значениями │ | |
| │ • Вариации (view, size, ...) с конкретными значениями │ |
| │ component() | ||
| ▼ | ||
| ┌─────────────────────────────────────────────────────────────┐ | ||
| │ Engines (движки) │ | ||
| │ ───────────────────────────────────────────────────────── │ | ||
| │ • Linaria (по умолчанию) │ | ||
| │ • Emotion │ | ||
| │ • styled-components │ | ||
| └─────────────────────────────────────────────────────────────┘ |
There was a problem hiding this comment.
Меня этот бы сбил с толку, т.к. это точно не отдельная сущность, от которой зависит new-hope. Лучше вообще убрать и в ядре добавить пункт про различные поставки.
|
|
||
| ``` | ||
| MyComponent/ | ||
| ├── index.ts # Публичный API компонента |
There was a problem hiding this comment.
| ├── index.ts # Публичный API компонента | |
| ├── index.ts # Экспорт компонента из ядра |
| // variations/_size/base.ts | ||
| import { ContentBefore, Title } from '../../MyComponent.styles'; | ||
|
|
||
| export const base = css` | ||
| padding: var(${tokens.padding}); | ||
|
|
||
| /* Стилизация styled-компонентов */ | ||
| ${ContentBefore} { | ||
| color: var(${tokens.contentBeforeColor}); | ||
| } | ||
|
|
||
| ${Title} { | ||
| font-size: var(${tokens.titleFontSize}); | ||
| } | ||
| `; | ||
| ``` |
There was a problem hiding this comment.
Это нерабочий пример (именно в линарии), лучше его переписать на класснеймы
There was a problem hiding this comment.
А хотя лучше вообще удалить, не думаю что стоит описывать настолько тонкие моменты стилизации
| negative: css`...`, | ||
| }, | ||
| }, | ||
| intersections: [ |
There was a problem hiding this comment.
чиво чиво?) это когда у нас такое появилосЬ?
There was a problem hiding this comment.
довольно давно, и это уже работает
|
|
||
| Для компонентов с под-компонентами используйте: | ||
|
|
||
| - `components/` — составные части, которые экспортируются наружу |
There was a problem hiding this comment.
снова может сбить с толку, components внутри components. Я например не юзаю components внутри, у меня везде ui
There was a problem hiding this comment.
Я еще видимо не понял что такое под-компоненты? Если речь про заимствование других комп из ядра, то это в разделе ниже про композицию.
|
|
||
| --- | ||
|
|
||
| ## Checklist перед PR |
There was a problem hiding this comment.
МОжно еще куда то впихнуть ссылку на кодгайд #1215
|
|
||
| --- | ||
|
|
||
| ## Частые вопросы и проблемы |
There was a problem hiding this comment.
| ## Частые вопросы и проблемы | |
| ## FAQ |
| - **Ядро (`plasma-new-hope`)** — содержит логику, структуру и CSS-переменные компонентов | ||
| - **Вертикаль** — библиотека/пакет для конкретного бренда/продукта (sdds-serv, plasma-giga и т.д.) | ||
| - **Токены** — CSS-переменные, которые определяют внешний вид | ||
| - **Variations** — набор стилей для разных значений пропсов (view, size, disabled) |
| - **Variations** — набор стилей для разных значений пропсов (view, size, disabled) | ||
| - **mergeConfig** — функция слияния конфигурации ядра с конфигурацией вертикали | ||
| - **component** — фабрика, создающая React-компонент из конфигурации | ||
|
|
There was a problem hiding this comment.
добавить пример со "Стилями" (primary, secondary, s, xl и т.д.)
| | `size` | Размер (xs, s, m, l, xl) | | ||
| | `disabled` | Неактивное состояние | | ||
| | `focused` | Состояние фокуса | | ||
|
|
There was a problem hiding this comment.
тут тоже убрать disabled / focus
| - [Button (простой)](../../packages/plasma-new-hope/src/components/Button/) — базовый пример | ||
| - [Note (средний)](../../packages/plasma-new-hope/src/components/Note/) — с ContentBefore и hasClose | ||
| - [Attach (сложный)](../../packages/plasma-new-hope/src/components/Attach/) — с подкомпонентами и ui/ | ||
| - [Button в вертикали](../../packages/sdds-serv/src/components/Button/) |
There was a problem hiding this comment.
а нужно ли тут описывать примеры как писать тесты / документацию и сторисы? Кажется, что без этого компоненты у нас не существуют
There was a problem hiding this comment.
Это в отдельных будет md файлах лежать. А тут будут ссылки на них
Yakutoc
force-pushed
the
docs-how-to-create-core-component
branch
from
c5722b9 to
32a3017
Compare
Yakutoc
force-pushed
the
docs-how-to-create-core-component
branch
from
32a3017 to
a5a26fd
Compare
4 participants
What/why changed
📦 Published PR as canary version:
Canary Versions✨ Test out this PR locally via:
npm install @salutejs/plasma-asdk@0.371.1-canary.2486.24026967213.0 npm install @salutejs/plasma-b2c@1.613.1-canary.2486.24026967213.0 npm install @salutejs/plasma-core@1.222.1-canary.2486.24026967213.0 npm install @salutejs/plasma-giga@0.340.1-canary.2486.24026967213.0 npm install @salutejs/plasma-homeds@0.340.1-canary.2486.24026967213.0 npm install @salutejs/plasma-hope@1.368.1-canary.2486.24026967213.0 npm install @salutejs/plasma-icons@1.234.1-canary.2486.24026967213.0 npm install @salutejs/plasma-new-hope@0.357.1-canary.2486.24026967213.0 npm install @salutejs/plasma-tokens@1.134.1-canary.2486.24026967213.0 npm install @salutejs/plasma-ui@1.344.1-canary.2486.24026967213.0 npm install @salutejs/plasma-web@1.615.1-canary.2486.24026967213.0 npm install @salutejs/sdds-bizcom@0.345.1-canary.2486.24026967213.0 npm install @salutejs/sdds-cs@0.349.1-canary.2486.24026967213.0 npm install @salutejs/sdds-dfa@0.343.1-canary.2486.24026967213.0 npm install @salutejs/sdds-finai@0.336.1-canary.2486.24026967213.0 npm install @salutejs/sdds-insol@0.340.1-canary.2486.24026967213.0 npm install @salutejs/sdds-netology@0.344.1-canary.2486.24026967213.0 npm install @salutejs/sdds-os@0.15.1-canary.2486.24026967213.0 npm install @salutejs/sdds-platform-ai@0.344.1-canary.2486.24026967213.0 npm install @salutejs/sdds-sbcom@0.344.1-canary.2486.24026967213.0 npm install @salutejs/sdds-scan@0.343.1-canary.2486.24026967213.0 npm install @salutejs/sdds-serv@0.344.1-canary.2486.24026967213.0 npm install @salutejs/plasma-themes@0.46.1-canary.2486.24026967213.0 npm install @salutejs/sdds-themes@0.61.1-canary.2486.24026967213.0 npm install @salutejs/sdds-api-tests@0.2.1-canary.2486.24026967213.0 npm install @salutejs/plasma-cy-utils@0.152.1-canary.2486.24026967213.0 npm install @salutejs/plasma-sb-utils@0.222.1-canary.2486.24026967213.0 # or yarn add @salutejs/plasma-asdk@0.371.1-canary.2486.24026967213.0 yarn add @salutejs/plasma-b2c@1.613.1-canary.2486.24026967213.0 yarn add @salutejs/plasma-core@1.222.1-canary.2486.24026967213.0 yarn add @salutejs/plasma-giga@0.340.1-canary.2486.24026967213.0 yarn add @salutejs/plasma-homeds@0.340.1-canary.2486.24026967213.0 yarn add @salutejs/plasma-hope@1.368.1-canary.2486.24026967213.0 yarn add @salutejs/plasma-icons@1.234.1-canary.2486.24026967213.0 yarn add @salutejs/plasma-new-hope@0.357.1-canary.2486.24026967213.0 yarn add @salutejs/plasma-tokens@1.134.1-canary.2486.24026967213.0 yarn add @salutejs/plasma-ui@1.344.1-canary.2486.24026967213.0 yarn add @salutejs/plasma-web@1.615.1-canary.2486.24026967213.0 yarn add @salutejs/sdds-bizcom@0.345.1-canary.2486.24026967213.0 yarn add @salutejs/sdds-cs@0.349.1-canary.2486.24026967213.0 yarn add @salutejs/sdds-dfa@0.343.1-canary.2486.24026967213.0 yarn add @salutejs/sdds-finai@0.336.1-canary.2486.24026967213.0 yarn add @salutejs/sdds-insol@0.340.1-canary.2486.24026967213.0 yarn add @salutejs/sdds-netology@0.344.1-canary.2486.24026967213.0 yarn add @salutejs/sdds-os@0.15.1-canary.2486.24026967213.0 yarn add @salutejs/sdds-platform-ai@0.344.1-canary.2486.24026967213.0 yarn add @salutejs/sdds-sbcom@0.344.1-canary.2486.24026967213.0 yarn add @salutejs/sdds-scan@0.343.1-canary.2486.24026967213.0 yarn add @salutejs/sdds-serv@0.344.1-canary.2486.24026967213.0 yarn add @salutejs/plasma-themes@0.46.1-canary.2486.24026967213.0 yarn add @salutejs/sdds-themes@0.61.1-canary.2486.24026967213.0 yarn add @salutejs/sdds-api-tests@0.2.1-canary.2486.24026967213.0 yarn add @salutejs/plasma-cy-utils@0.152.1-canary.2486.24026967213.0 yarn add @salutejs/plasma-sb-utils@0.222.1-canary.2486.24026967213.0