@elcrm/components 0.0.1 → 0.1.0

package/README.md

@@ -1,6 +1,6 @@
 # @elcrm/components
 
-Shell UI для elCRM: `Layout`, `Header`, `Section`, `NavSections`, `TabSections`, `Row`, `Column` и др.
+Shell UI для elCRM: `Layout`, `Header`, `Section`, `Stack`, `NavSections`, `TabSections` и др.
 
 Стили — CSS Modules с короткими уникальными классами; значения токенов задаёт приложение (`theme-dark.css` / `theme-light.css`). Fallback в пакете нет.
 
@@ -18,20 +18,28 @@ import {
   List,
   Item,
   Card,
-  Block,
-  Row,
-  Column,
+  Stack,
   Menu,
   Loading,
   Section,
   NavSections,
   TabSections,
   Avatar,
+  AvatarGroup,
+  AvatarName,
   Badge,
   Brand,
   EmptyState,
+  RadioGroup,
+  PricingGroup,
+  PricingTable,
+  Dropdown,
+  Breadcrumb,
+  PageHead,
+  PageShell,
   createLazyResolver,
 } from "@elcrm/components";
+import type { PricingPlan } from "@elcrm/components";
 // CSS подтягивается с чанками; при необходимости единый файл:
 // import "@elcrm/components/style.css";
 ```
@@ -41,6 +49,7 @@ import {
 ```ts
 import { Header } from "@elcrm/components/Header";
 import { Avatar } from "@elcrm/components/Avatar";
+import { RadioGroup } from "@elcrm/components/RadioGroup";
 ```
 
 ## Компоненты
@@ -51,21 +60,391 @@ import { Avatar } from "@elcrm/components/Avatar";
 | **Header**                       | Шапка со слотами                 | `brand`, `nav`, `search`, `actions`                  |
 | **Footer**                       | Подвал                           | `children`                                           |
 | **Brand**                        | Название / логотип               | `as`, `children`, `onClick`                          |
-| **Avatar**                       | Фото или инициалы                | `src`, `name`, `size`, `active`, `as`                |
+| **Avatar**                       | Фото или инициалы                | `src`, `name` (инициалы), `size`, `status`, `as`     |
+| **AvatarName**                   | Аватар + title + description     | `title`, `description`, `name?`, `size`, `status`    |
+| **AvatarGroup**                  | Стопка аватаров + «+N»           | `items` (`value`/`title`/`name`), `max`, `add`       |
 | **Badge**                        | Метка / статус                   | `tone`, `children`                                   |
-| **Menu**                         | Навигация (не overlay)           | `items`, `activeKey`, `vertical`, `onSelect`         |
-| **Section**                      | Блок страницы / auth / подраздел | `title`, `description`, `icon`, `actions`, `variant` |
-| **NavSections**                  | Сайдбар + lazy-панель            | `groups`, `resolveSection`, `defaultActiveKey`       |
-| **TabSections**                  | Горизонтальные вкладки + lazy    | `items` (+ `badge`), `resolveSection`                |
+| **RadioGroup**                   | Выбор одной опции-карточки       | `items`, `value`, `indicator`, `indicatorSide`       |
+| **PricingGroup**                 | Тарифные карточки в ряд          | `items` (`PricingPlan`), `selectable`, `value`       |
+| **PricingTable**                 | Сравнение тарифов (таблица)      | те же `items` + `sections`                           |
+| **Menu**                         | Навигация в шапке (не popover)   | `items` (`value`), `value`, `onSelect`               |
+| **Dropdown**                     | Выпадающее меню (items)          | `label`/`trigger`, `items`/`groups`, `onSelect`      |
+| **Breadcrumb**                   | Хлебные крошки                   | `items`, `separator`, `collapseAfter`                |
+| **PageShell**                    | Каркас модуля (скролл + footer)  | `wide`, `footer`, `children`                         |
+| **PageHead**                     | Заголовок страницы + actions     | `title`, `subtitle`, `actions`                       |
+| **Section**                      | Блок контента / auth / подраздел | `title`, `description`, `icon`, `actions`, `variant` |
+| **NavSections**                  | Сайдбар + lazy-панель            | `groups` (`value`), `resolveSection`, `defaultValue` |
+| **TabSections**                  | Горизонтальные вкладки + lazy    | `items` (`value` + `badge`), `resolveSection`        |
 | **Card**                         | Карточка                         | `title`, `children`                                  |
 | **List** / **Item**              | Список и строка                  | List: `row`; Item: `as`, `active`                    |
-| **Block** / **Row** / **Column** | Стеки                            | `gap`; Block ещё `row`                               |
+| **Stack**                        | Ряд / колонка                    | `direction`, `gap`                                   |
 | **Loading**                      | Плейсхолдер загрузки             | `children`                                           |
 | **EmptyState**                   | Заглушка «нет данных»            | `title`, `description`, `icon`, `actions`            |
 | **createLazyResolver**           | Кэш `import()` секций            | `(key) => import(…)`                                 |
 
 Слоты `Header` заполняет приложение: поиск — `@elcrm/search`, кнопки — `@elcrm/button`, и т.д.
 
+`Block` / `Row` / `Column` — deprecated-обёртки над `Stack`. В проектах: `elcrm migrate components`.
+
+### Stack
+
+```tsx
+<Stack gap="0.75rem">{/* колонка */}</Stack>
+<Stack direction="row" gap={8}>{/* ряд */}</Stack>
+```
+
+### RadioGroup
+
+Декларативно через `items` — всё из коробки. Нет поля → блок не рисуется.
+
+```tsx
+const items = [
+  {
+    value: "basic",
+    icon: <LayersIcon />,
+    title: "Basic plan",
+    meta: "$10/month",
+    description: "Includes up to 10 users…",
+  },
+  {
+    value: "pro",
+    title: "Pro plan",
+    meta: "$20/month",
+    description: "Includes up to 20 users…",
+  },
+  {
+    value: "olivia",
+    icon: <Avatar name="Olivia Rhye" src="…" />,
+    iconFramed: false,
+    title: "Olivia Rhye",
+    meta: "@olivia",
+    description: "Product Manager",
+  },
+  {
+    value: "visa",
+    icon: <VisaLogo />,
+    title: "Visa ending in 1234",
+    description: "Expiry 06/2028",
+    actions: (
+      <>
+        <button type="button">Set as default</button>
+        <button type="button">Edit</button>
+      </>
+    ),
+  },
+  {
+    value: "enterprise",
+    variant: "split",
+    icon: <BoltIcon />,
+    title: "Enterprise plan",
+    price: "$40",
+    meta: "per month",
+    badge: <Badge tone="success">Limited time only</Badge>,
+    description: "Unlimited users…",
+  },
+];
+
+<RadioGroup
+  items={items}
+  value={plan}
+  onValueChange={setPlan}
+  indicator="check"
+/>
+
+{/* Круглый radio слева */}
+<RadioGroup
+  items={items}
+  value={plan}
+  onValueChange={setPlan}
+  indicator="radio"
+  indicatorSide="start"
+/>
+```
+
+### PricingGroup / PricingTable
+
+Один тип **`PricingPlan`** и один массив `plans` на оба компонента. Table только добавляет `sections` (матрица по `plan.value`).
+
+```tsx
+import type { PricingPlan } from "@elcrm/components";
+
+const plans: PricingPlan[] = [
+  {
+    value: "basic",
+    title: "Basic plan",
+    price: "$10",
+    meta: "per month",
+    description: "Basic features for up to 10 users.",
+    actions: (
+      <>
+        <button type="button">Get started</button>
+        <button type="button">Chat to sales</button>
+      </>
+    ),
+    actionsPlacement: "before",
+    featuresLabel: "FEATURES",
+    featuresSummary: "Everything in Starter plus…",
+    features: [
+      "Access to basic features",
+      "Basic reporting and analytics",
+    ],
+  },
+  {
+    value: "business",
+    title: "Business plan",
+    badge: "Popular",
+    badgePlacement: "pill",
+    highlighted: true,
+    price: "$20",
+    meta: "per month",
+    description: "Growing teams up to 20 users.",
+    actions: <button type="button">Get started</button>,
+    features: ["200+ integrations", "Advanced custom fields"],
+  },
+  {
+    value: "enterprise",
+    badge: "Most popular plan",
+    badgePlacement: "banner",
+    priceFirst: true,
+    price: "$40/mth",
+    title: "Enterprise plan",
+    description: "Advanced features + unlimited users.",
+    features: ["Audit log", "Data loss prevention"],
+    actions: <button type="button">Get started</button>,
+  },
+];
+
+<PricingGroup items={plans} />
+<PricingGroup items={plans} selectable value={plan} onValueChange={setPlan} />
+
+const sections = [
+  {
+    title: "Overview",
+    rows: [
+      {
+        key: "basic",
+        label: "Basic features",
+        hint: "Core product features",
+        values: { basic: true, business: true, enterprise: true },
+      },
+      {
+        key: "users",
+        label: "Users",
+        values: { basic: "10", business: "20", enterprise: "Unlimited" },
+      },
+    ],
+  },
+];
+
+<PricingTable items={plans} sections={sections} />
+<PricingTable
+  items={plans}
+  sections={sections}
+  footerActions
+  selectable
+  value={plan}
+  onValueChange={setPlan}
+/>
+```
+
+`true` → галочка, `false` / нет значения → «—», иначе текст/node.
+
+### PageShell / PageHead / Section
+
+Три разных роли — не путать:
+
+| | Роль |
+| --- | --- |
+| **PageShell** | Каркас модуля: скролл в body, опциональный footer снизу |
+| **PageHead** | Строка title (+ subtitle) слева и actions справа |
+| **Section** | Блок контента / auth-карточка / подраздел с title+description |
+
+```tsx
+<PageShell footer={<button type="button">Сохранить</button>}>
+  <PageHead title="Товары" subtitle="Каталог" actions={<button>Добавить</button>} />
+  <Section title="Фильтры">{/* … */}</Section>
+</PageShell>
+```
+
+### AvatarGroup
+
+Стопка аватаров через `items`:
+
+```tsx
+const people = [
+  { value: "1", src: "/a.jpg", name: "Anna" },
+  { value: "2", name: "Boris" },
+  { value: "3", src: "/c.jpg", name: "Clara" },
+  // …
+];
+
+<AvatarGroup items={people} size="s" max={5} />
+<AvatarGroup items={people} size="m" max={5} add onAdd={() => {}} />
+<AvatarGroup
+  items={people}
+  size="l"
+  max={5}
+  add
+  onAdd={() => {}}
+  onItemClick={(item) => console.log(item)}
+/>
+```
+
+`max` — сколько показать; остаток → «+N». `add` — кнопка «+» справа.
+
+### Avatar / AvatarName
+
+Канон: у текста — `title` + `description`; `name` — только для инициалов (если нет `src`).
+
+```tsx
+<Avatar src="/a.jpg" name="Olivia" size="m" status="online" />
+<Avatar name="Olivia Rhye" size="l" status="offline" />
+
+<AvatarName
+  src="/a.jpg"
+  title="Olivia Rhye"
+  description="olivia@untitledui.com"
+  size="m"
+  status="online"
+/>
+
+{/* name — инициалы; title — подпись */}
+<AvatarName
+  as="button"
+  name="Olivia Rhye"
+  title="Olivia Rhye"
+  description="Product Manager"
+  size="s"
+  onClick={() => {}}
+/>
+```
+
+### Dropdown
+
+Выпадающее меню через `items` или `groups` (разделители между группами):
+
+```tsx
+<Dropdown
+  label="Account"
+  align="end"
+  groups={[
+    {
+      items: [
+        { value: "cut", label: "Cut", shortcut: "⌘X" },
+        { value: "copy", label: "Copy", shortcut: "⌘C" },
+        { value: "paste", label: "Paste", shortcut: "⌘V" },
+      ],
+    },
+    {
+      items: [
+        { value: "edit", label: "Edit" },
+        { value: "dup", label: "Duplicate" },
+        { value: "del", label: "Delete", danger: true },
+      ],
+    },
+    {
+      items: [
+        { value: "details", label: "View details", submenu: true },
+      ],
+    },
+  ]}
+  onSelect={(value) => console.log(value)}
+/>
+
+{/* Выбор с галочкой */}
+<Dropdown
+  label="Can edit"
+  items={[
+    { value: "owner", label: "Owner" },
+    { value: "edit", label: "Can edit", checked: true },
+    { value: "view", label: "Can view" },
+  ]}
+/>
+
+{/* Иконки, статус, submenu */}
+<Dropdown
+  label="Actions"
+  groups={[
+    {
+      items: [
+        { value: "back", label: "Back", icon: <BackIcon /> },
+        { value: "reload", label: "Reload", icon: <ReloadIcon />, shortcut: "⌘R" },
+      ],
+    },
+    {
+      items: [
+        { value: "bm", label: "Show bookmarks", checked: true },
+        { value: "url", label: "Show full URLs" },
+      ],
+    },
+    {
+      items: [
+        { value: "o", label: "Olivia Rhye", status: "online" },
+        { value: "s", label: "Sienna Hewitt", status: "offline" },
+      ],
+    },
+    {
+      items: [
+        { value: "more", label: "More tools", icon: <CubeIcon />, submenu: true },
+      ],
+    },
+  ]}
+/>
+
+{/* Колонки: checkbox, title, не закрывать при клике */}
+<Dropdown
+  trigger={<button type="button">⚙</button>}
+  title="Колонки в списке"
+  closeOnSelect={false}
+  items={[
+    { value: "photo", label: "Фото", checkbox: true, checked: true },
+    { value: "sku", label: "SKU", checkbox: true, checked: true, disabled: true },
+    { value: "brand", label: "Бренд", checkbox: true, checked: false },
+  ]}
+  onSelect={(value) => toggleColumn(value)}
+/>
+```
+
+`Menu` — навигация в шапке (inline, не popover).
+
+**Dropdown vs `@elcrm/overlay`:** в пакете `Dropdown` — готовое меню по `items`/`groups` (контент + поведение выбора). `@elcrm/overlay` — portal, позиционирование и z-index стек, когда нужен свой попап или общий слой поверх страницы. Не смешивать: для типового меню пунктов — `Dropdown`; для кастомного портала — overlay.
+
+### Breadcrumb
+
+```tsx
+<Breadcrumb
+  separator="chevron" // или "slash"
+  items={[
+    { value: "home", icon: <HomeIcon />, href: "/" },
+    { value: "settings", label: "Settings", href: "/settings" },
+    { value: "team", label: "Team" }, // текущий — последний
+  ]}
+/>
+
+{/* Иконка + avatar + dropdown */}
+<Breadcrumb
+  items={[
+    { value: "org", icon: <Logo />, label: "Warpspeed", href: "/" },
+    {
+      value: "user",
+      icon: <Avatar src="…" name="Caitlyn" size="s" />,
+      label: "Caitlyn King",
+      dropdown: true,
+      onClick: () => openSwitcher(),
+    },
+    { value: "settings", label: "Settings" },
+  ]}
+/>
+
+{/* Длинный путь → первые 2, …, последний */}
+<Breadcrumb
+  collapseAfter={2}
+  separator="slash"
+  items={longPath}
+  onEllipsisClick={() => {}}
+/>
+```
+
 ## Пример
 
 ```tsx
@@ -73,7 +452,7 @@ import { Avatar } from "@elcrm/components/Avatar";
   header={
     <Header
       brand={<Brand onClick={() => {}}>App</Brand>}
-      nav={<Menu items={[{ key: "home", label: "Главная", active: true }]} />}
+      nav={<Menu items={[{ value: "home", label: "Главная", active: true }]} />}
       actions={
         <>
           <Avatar as="button" name="Admin" />
@@ -108,17 +487,17 @@ import { Avatar } from "@elcrm/components/Avatar";
 {
   /* Настройки: меню слева + sections/*.tsx справа */
 }
-const resolve = createLazyResolver((key) => import(`./sections/${key}.tsx`));
+const resolve = createLazyResolver((value) => import(`./sections/${value}.tsx`));
 
 <NavSections
-  defaultActiveKey="Profile"
+  defaultValue="Profile"
   resolveSection={resolve}
   groups={[
     {
       label: "Личное",
       items: [
-        { key: "Profile", label: "Профиль" },
-        { key: "Appearance", label: "Оформление" },
+        { value: "Profile", label: "Профиль" },
+        { value: "Appearance", label: "Оформление" },
       ],
     },
   ]}
@@ -132,11 +511,11 @@ const resolve = createLazyResolver((key) => import(`./sections/${key}.tsx`));
 ```tsx
 <Section title="Дети" description="Список">
   <TabSections
-    defaultActiveKey="News"
-    resolveSection={createLazyResolver((k) => import(`./sections/${k}.tsx`))}
+    defaultValue="News"
+    resolveSection={createLazyResolver((v) => import(`./sections/${v}.tsx`))}
     items={[
-      { key: "News", label: "Новые", badge: 1 },
-      { key: "Active", label: "Активные" },
+      { value: "News", label: "Новые", badge: 1 },
+      { value: "Active", label: "Активные" },
     ]}
   />
 </Section>
@@ -144,208 +523,77 @@ const resolve = createLazyResolver((key) => import(`./sections/${key}.tsx`));
 
 ## CSS-токены
 
-Тема приложения объявляет **все** переменные (fallback в пакете нет).  
-Эталон: panel `theme.css` (геометрия) + `theme-light` / `theme-dark` (цвета).
+Как в `@elcrm/form`: сначала **общие**, потом узкие.
 
-**layout** · Loading
+| Слой | Где | Примеры |
+| ---- | --- | ------- |
+| Палитра | theme-light / dark | `--text`, `--muted`, `--line`, `--panel`, `--accent`, `--shadow` |
+| Control | theme.css | `--control-height`, `--control-radius`, `--control-font-size` |
+| **Shell** | theme.css + light/dark | `--shell-*` — общие для Dropdown, RadioGroup, Pricing*, Breadcrumb, AvatarName… |
+| Popover | light/dark | `--popup-shadow` (общий с form) |
+| Узкие | theme.css | `--header-height`, `--avatar-size-*`, `--dropdown-min-width`, `--pricing-card-min-width`… |
 
-```
---layout-background
---layout-gap
---layout-min-height
---loading-color
---loading-padding
-```
+Задай `--shell-*` один раз — большинство новых компонентов подхватят.
 
-**header**
+**shell (геометрия → theme.css)**
 
 ```
---header-background
---header-border
---header-color
---header-gap
---header-height
---header-margin
---header-padding
---header-radius
---header-shadow
---header-z
+--shell-radius          (= --control-radius)
+--shell-font-size       (= --control-font-size)
+--shell-font-size-sm
+--shell-font-size-lg
+--shell-font-weight
+--shell-gap / -sm / -lg
+--shell-padding         (или -block / -inline)
+--shell-icon-size
+--shell-check-size
+--shell-status-size
+--shell-disabled-opacity
+--shell-z
 ```
 
-**footer**
+**shell (цвет → light / dark, обычно алиасы палитры)**
 
 ```
---footer-background
---footer-border
---footer-color
---footer-font-size
---footer-padding
+--shell-color           (= --text)
+--shell-color-muted     (= --muted)
+--shell-color-accent    (= --accent)
+--shell-color-danger
+--shell-color-success
+--shell-color-warning
+--shell-border          (= --line, только цвет)
+--shell-background      (= --panel)
+--shell-background-muted / -hover / -selected
+--shell-shadow
 ```
 
-**list** · Item
+**Узкие (только если нужно иначе)**
 
 ```
---list-gap
---list-padding
---item-background
---item-background-active
---item-background-hover
---item-border
---item-color
---item-gap
---item-padding
---item-radius
+--header-height / --header-z / --header-margin / --header-shadow / --header-radius
+--section-padding / --section-title-size / --section-title-size-md / --section-auth-card-max-width
+--nav-sections-padding / --nav-sections-nav-width / --nav-sections-main-max-width
+--avatar-size-s|m|l / --avatar-group-overlap
+--dropdown-min-width / --dropdown-max-width / --dropdown-max-height
+--pricing-card-min-width / --pricing-table-label-width
+--row-gap / --column-gap
+--popup-shadow
 ```
 
-**card** · Block · Row · Column
-
-```
---card-background
---card-border
---card-padding
---card-radius
---card-shadow
---block-gap
---block-padding
---row-gap
---column-gap
-```
+Эталон геометрии+shell: panel `theme.css`. Цвета: `theme-light` / `theme-dark`.  
+В пакете: `tokens.css` / `light.css` / `dark.css` — дефолты для `elcrm css`.
 
-**menu**
+## Миграция в приложениях
 
-```
---menu-gap
---menu-item-background
---menu-item-background-active
---menu-item-background-hover
---menu-item-color
---menu-item-color-active
---menu-item-padding
---menu-item-radius
-```
-
-**section**
-
-```
---section-padding
---section-gap
---section-title-color
---section-title-size
---section-title-size-md
---section-description-color
---section-description-size
---section-icon-gap
---section-body-gap
---section-actions-gap
---section-auth-padding
---section-auth-card-background
---section-auth-card-border
---section-auth-card-max-width
---section-auth-card-padding
---section-auth-card-radius
---section-auth-card-shadow
---section-block-border
---section-block-margin-bottom
---section-block-padding-bottom
-```
-
-**nav-sections**
-
-```
---nav-sections-padding
---nav-sections-gap
---nav-sections-nav-width
---nav-sections-main-max-width
---nav-sections-label-color
---nav-sections-item-color
---nav-sections-item-background-hover
---nav-sections-item-background-active
---nav-sections-item-padding
---nav-sections-item-radius
---nav-sections-accent
---nav-sections-icon-color
---nav-sections-group-border
---nav-sections-footer-border
-```
-
-**tab-sections**
-
-```
---tab-sections-gap
---tab-sections-border
---tab-sections-color
---tab-sections-color-active
---tab-sections-accent
---tab-sections-tab-gap
---tab-sections-tab-padding
---tab-sections-badge-background
---tab-sections-badge-color
---tab-sections-badge-size
-```
-
-**avatar**
-
-```
---avatar-size-s
---avatar-size-m
---avatar-size-l
---avatar-radius
---avatar-font-size-s
---avatar-font-size-m
---avatar-font-size-l
---avatar-font-weight
---avatar-background
---avatar-color
---avatar-border
---avatar-outline-active
---avatar-outline-offset
-```
-
-**badge**
-
-```
---badge-padding
---badge-radius
---badge-font-size
---badge-font-weight
---badge-border
---badge-neutral-background
---badge-neutral-color
---badge-accent-background
---badge-accent-color
---badge-success-background
---badge-success-color
---badge-warning-background
---badge-warning-color
---badge-danger-background
---badge-danger-color
-```
-
-**brand**
-
-```
---brand-font-weight
---brand-letter-spacing
---brand-color
---brand-color-hover
+```bash
+elcrm update --fix --test   # включает migrate components
+# или точечно:
+elcrm migrate components
+elcrm css
+elcrm docs && elcrm cursor
 ```
 
-**empty-state**
-
-```
---empty-state-gap
---empty-state-padding
---empty-state-icon-gap
---empty-state-title-size
---empty-state-description-size
---empty-state-max-width
---empty-state-actions-gap
---empty-state-actions-margin-top
---empty-state-color
---empty-state-icon-color
---empty-state-title-color
---empty-state-description-color
-```
+Пилюля `components`: Block/Row/Column → Stack; `key`/`activeKey` → `value`; старые `--item-*` / `--menu-*` / … → `--shell-*`.
 
 ## Лицензия