@central-design-system/skills 4.0.0-alpha.6

package/skills/cds-builder/references/components/cds-menu/examples.md

@@ -0,0 +1,595 @@
+# CdsMenu — usage examples
+
+> Extracted from Storybook stories (`docs/*.stories.ts`) by `bun run generate:skill`. Do not edit manually.
+> The full component contract is in [api.md](api.md). `v-bind="args"` in templates refers to the props from the **Args** block of the corresponding example.
+
+A menu pops up next to an activator element and shows a list of actions or sections: the "more" button in a table row, the user menu in the header, a context menu on right click. It positions itself — it opens towards the free space and sticks to the activator while the page scrolls.
+
+## Activators
+
+the page, even a distant one in the markup.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsButton, CdsList, CdsMenu } from '@central-design-system/components';
+
+const items = [
+  { title: 'Скачать', value: 'download' },
+  { title: 'Дублировать', value: 'duplicate' },
+  { title: 'Переименовать', value: 'rename' }
+];
+</script>
+
+<template>
+  <div class="m-auto flex flex-wrap items-center justify-center gap-2">
+    <CdsMenu>
+      <template #activator="{ props }">
+        <CdsButton v-bind="props">Активатор в слоте</CdsButton>
+      </template>
+
+      <CdsList :items="items" />
+    </CdsMenu>
+
+    <CdsButton>
+      Родительский элемент
+
+      <CdsMenu activator="parent">
+        <CdsList :items="items" />
+      </CdsMenu>
+    </CdsButton>
+
+    <CdsButton id="menu-activator">Соседний элемент</CdsButton>
+
+    <CdsMenu activator="#menu-activator">
+      <CdsList :items="items" />
+    </CdsMenu>
+  </div>
+</template>
+```
+
+## Opening
+
+By default the menu opens on click. The `open-on-hover` prop switches it to hover — this is how navigation menus behave; a click then does not open the panel. The `open-delay` and `close-delay` delays (300 and 250 ms) keep the menu from flickering when the cursor just passes by. Together with `open-on-hover`, opening on focus is enabled as well — turn it off with `:open-on-focus="false"` if the menu should react to the mouse only.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsButton, CdsList, CdsMenu } from '@central-design-system/components';
+
+const items = [
+  { title: 'Профиль', value: 'profile' },
+  { title: 'Уведомления', value: 'notifications' },
+  { title: 'Выйти', value: 'logout' }
+];
+</script>
+
+<template>
+  <div class="m-auto flex flex-wrap items-center justify-center gap-2">
+    <CdsMenu open-on-hover>
+      <template #activator="{ props }">
+        <CdsButton v-bind="props">Наведите курсор</CdsButton>
+      </template>
+
+      <CdsList :items="items" />
+    </CdsMenu>
+
+    <CdsMenu open-on-hover :open-delay="0" :close-delay="0">
+      <template #activator="{ props }">
+        <CdsButton v-bind="props" appearance="secondary">Без задержек</CdsButton>
+      </template>
+
+      <CdsList :items="items" />
+    </CdsMenu>
+
+    <CdsMenu open-on-hover :open-on-focus="false">
+      <template #activator="{ props }">
+        <CdsButton v-bind="props" appearance="secondary">Только наведение</CdsButton>
+      </template>
+
+      <CdsList :items="items" />
+    </CdsMenu>
+  </div>
+</template>
+```
+
+## Position
+
+The `location` prop sets the side of the activator the menu appears on: `bottom` by default, `top`, `end`, `bottom end` — the side and the alignment. If there is not enough room, the menu flips to the opposite edge on its own. The `offset` prop tunes the distance to the activator, and `viewport-margin` sets the minimum gap to the edge of the screen.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsButton, CdsList, CdsMenu } from '@central-design-system/components';
+
+const items = [
+  { title: 'Скачать', value: 'download' },
+  { title: 'Дублировать', value: 'duplicate' },
+  { title: 'Переименовать', value: 'rename' }
+];
+
+const locations = ['bottom', 'top', 'end', 'bottom end'] as const;
+</script>
+
+<template>
+  <div class="m-auto flex flex-wrap items-center justify-center gap-2">
+    <CdsMenu v-for="location in locations" :key="location" :location="location">
+      <template #activator="{ props }">
+        <CdsButton v-bind="props" appearance="tertiary">{{ location }}</CdsButton>
+      </template>
+
+      <CdsList :items="items" />
+    </CdsMenu>
+
+    <CdsMenu :offset="16">
+      <template #activator="{ props }">
+        <CdsButton v-bind="props" appearance="tertiary">offset 16</CdsButton>
+      </template>
+
+      <CdsList :items="items" />
+    </CdsMenu>
+  </div>
+</template>
+```
+
+## Sizes
+
+The width of the menu equals the width of its content. The `min-width`, `max-width` and `max-height` props set the bounds: the minimum width keeps the panel from collapsing on short items, and a limited height turns on scrolling instead of a full-screen menu.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsButton, CdsList, CdsMenu } from '@central-design-system/components';
+
+const items = Array.from({ length: 12 }, (_, index) => ({
+  title: `Организация № ${index + 1}`,
+  value: index + 1
+}));
+</script>
+
+<template>
+  <div class="m-auto flex flex-wrap items-center justify-center gap-2">
+    <CdsMenu :min-width="280">
+      <template #activator="{ props }">
+        <CdsButton v-bind="props">Минимальная ширина</CdsButton>
+      </template>
+
+      <CdsList :items="items.slice(0, 3)" />
+    </CdsMenu>
+
+    <CdsMenu :max-height="220">
+      <template #activator="{ props }">
+        <CdsButton v-bind="props" appearance="secondary">Ограниченная высота</CdsButton>
+      </template>
+
+      <CdsList :items="items" />
+    </CdsMenu>
+  </div>
+</template>
+```
+
+## Closing
+
+The menu closes on a click inside the content, on a click outside and on `Esc`. The `:close-on-content-click="false"` prop keeps the panel open — you need that when it holds checkboxes, fields or several steps in a row. The `persistent` prop ignores the outside click and `Esc`: then the menu can only be closed by your own button through `v-model`.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsButton, CdsCheckbox, CdsList, CdsMenu, CdsSurface } from '@central-design-system/components';
+import { ref } from 'vue';
+
+const items = [
+  { title: 'Скачать', value: 'download' },
+  { title: 'Дублировать', value: 'duplicate' },
+  { title: 'Переименовать', value: 'rename' }
+];
+
+const columns = ref(['name']);
+const persistent = ref(false);
+</script>
+
+<template>
+  <div class="m-auto flex flex-wrap items-center justify-center gap-2">
+    <CdsMenu>
+      <template #activator="{ props }">
+        <CdsButton v-bind="props">Закроется по клику</CdsButton>
+      </template>
+
+      <CdsList :items="items" />
+    </CdsMenu>
+
+    <CdsMenu :close-on-content-click="false">
+      <template #activator="{ props }">
+        <CdsButton v-bind="props" appearance="secondary">Останется открытым</CdsButton>
+      </template>
+
+      <CdsSurface class="flex w-[220px] flex-col gap-1">
+        <CdsCheckbox v-model="columns" value="name" label="Название" hide-details />
+        <CdsCheckbox v-model="columns" value="date" label="Дата" hide-details />
+        <CdsCheckbox v-model="columns" value="status" label="Статус" hide-details />
+      </CdsSurface>
+    </CdsMenu>
+
+    <CdsMenu v-model="persistent" persistent :close-on-content-click="false">
+      <template #activator="{ props }">
+        <CdsButton v-bind="props" appearance="secondary">Только своей кнопкой</CdsButton>
+      </template>
+
+      <CdsSurface class="flex w-[240px] flex-col gap-1 p-2">
+        <span class="text-100 text-content-secondary">Клик мимо меню его не закроет.</span>
+
+        <CdsButton size="sm" appearance="tertiary" @click="persistent = false">Закрыть</CdsButton>
+      </CdsSurface>
+    </CdsMenu>
+  </div>
+</template>
+```
+
+## Nested menus
+
+Menus can be nested into each other: every list item becomes an activator (`activator="parent"`) for a child `CdsMenu` with the `submenu` prop — it shifts the panel sideways and moves the navigation to the left and right arrow keys. The `open-on-hover` prop opens the submenu on hover, and `:open-on-focus="false"` keeps it from opening while tabbing through.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsButton, CdsIcon, CdsList, CdsListItem, CdsMenu } from '@central-design-system/components';
+
+const sections = [
+  { title: 'Закупки', children: ['Черновики', 'Опубликованные', 'Завершённые'] },
+  { title: 'Договоры', children: ['На согласовании', 'Подписанные', 'Архив'] },
+  { title: 'Отчёты', children: ['По поставщикам', 'По срокам', 'По суммам'] }
+];
+
+const periods = ['За неделю', 'За месяц', 'За квартал'];
+</script>
+
+<template>
+  <div class="m-auto flex justify-center">
+    <CdsButton>
+      Открыть меню
+
+      <CdsMenu activator="parent">
+        <CdsList>
+          <CdsListItem v-for="section in sections" :key="section.title" link :title="section.title">
+            <template #append>
+              <CdsIcon name="chevron-right" size="xs" />
+            </template>
+
+            <CdsMenu activator="parent" submenu open-on-hover :open-on-focus="false">
+              <CdsList>
+                <CdsListItem v-for="child in section.children" :key="child" link :title="child">
+                  <template #append>
+                    <CdsIcon name="chevron-right" size="xs" />
+                  </template>
+
+                  <CdsMenu activator="parent" submenu open-on-hover :open-on-focus="false">
+                    <CdsList>
+                      <CdsListItem v-for="period in periods" :key="period" link :title="period" />
+                    </CdsList>
+                  </CdsMenu>
+                </CdsListItem>
+              </CdsList>
+            </CdsMenu>
+          </CdsListItem>
+        </CdsList>
+      </CdsMenu>
+    </CdsButton>
+  </div>
+</template>
+```
+
+## Animation
+
+The `transition` prop changes the animation the panel appears with.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsButton, CdsList, CdsMenu } from '@central-design-system/components';
+
+const items = [
+  { title: 'Скачать', value: 'download' },
+  { title: 'Дублировать', value: 'duplicate' },
+  { title: 'Переименовать', value: 'rename' }
+];
+
+const transitions = ['fade-transition', 'scale-transition', 'slide-transition-y', 'slide-transition-x'];
+</script>
+
+<template>
+  <div class="m-auto flex flex-wrap items-center justify-center gap-4">
+    <CdsMenu v-for="transition in transitions" :key="transition" :transition="transition">
+      <template #activator="{ props }">
+        <CdsButton v-bind="props" appearance="tertiary">{{ transition }}</CdsButton>
+      </template>
+
+      <CdsList :items="items" />
+    </CdsMenu>
+  </div>
+</template>
+```
+
+## Actions on a record
+
+Rare actions on a table row or a card are collected in a menu behind the "⋮" button: the row stays clean, and the actions do not compete with the main button. `location="bottom end"` pins the panel to the right edge of the activator, `slim` on the list removes the extra paddings, and `aria-label` names the record the menu belongs to.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsButton, CdsList, CdsListItem, CdsListItemDivider, CdsMenu } from '@central-design-system/components';
+import { ref } from 'vue';
+
+const documents = [
+  { id: 1, title: 'Договор поставки № 42' },
+  { id: 2, title: 'Счёт на оплату № 5512' },
+  { id: 3, title: 'Акт сверки за март' }
+];
+
+const actions = [
+  { title: 'Скачать', icon: 'download' },
+  { title: 'Дублировать', icon: 'copy' },
+  { title: 'Переименовать', icon: 'edit' }
+];
+
+const lastAction = ref('');
+</script>
+
+<template>
+  <div class="m-auto flex w-[300px] flex-col gap-1">
+    <div v-for="doc in documents" :key="doc.id" class="flex items-center justify-between gap-2">
+      <span class="text-100">{{ doc.title }}</span>
+
+      <CdsMenu location="bottom end">
+        <template #activator="{ props }">
+          <CdsButton
+            v-bind="props"
+            size="sm"
+            appearance="tertiary"
+            icon="overflow-menu-vertical"
+            :aria-label="`Действия: ${doc.title}`"
+          />
+        </template>
+
+        <CdsList slim>
+          <CdsListItem
+            v-for="action in actions"
+            :key="action.title"
+            link
+            :title="action.title"
+            :prepend-icon="action.icon"
+            @click="lastAction = `${action.title}: ${doc.title}`"
+          />
+
+          <CdsListItemDivider />
+
+          <CdsListItem link title="Удалить" prepend-icon="delete" @click="lastAction = `Удалить: ${doc.title}`" />
+        </CdsList>
+      </CdsMenu>
+    </div>
+
+    <p class="text-100 text-content-secondary">{{ lastAction || 'Выберите действие в меню строки' }}</p>
+  </div>
+</template>
+```
+
+## Context menu
+
+A menu can open at the point of the click: the `contextmenu` handler puts the cursor coordinates into `target`, and `v-model` controls the visibility — no activator is needed here. A new click moves the open panel to the new spot. The default animation is meant for an element activator, so for a menu placed by coordinates set a CSS animation — for example, `transition="scale-transition"`.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsList, CdsListItem, CdsMenu, CdsSurface } from '@central-design-system/components';
+import { ref } from 'vue';
+
+const isOpen = ref(false);
+const coordinates = ref<[number, number]>([0, 0]);
+const lastAction = ref('');
+
+const openContextMenu = (event: MouseEvent) => {
+  coordinates.value = [event.clientX, event.clientY];
+  isOpen.value = true;
+};
+</script>
+
+<template>
+  <div class="m-auto flex w-[380px] flex-col gap-1">
+    <CdsSurface
+      class="flex h-[140px] cursor-context-menu items-center justify-center rounded border border-dashed"
+      @contextmenu.prevent="openContextMenu"
+    >
+      <span class="text-100 text-content-secondary">Кликните правой кнопкой мыши</span>
+    </CdsSurface>
+
+    <CdsMenu v-model="isOpen" :target="coordinates" transition="scale-transition">
+      <CdsList slim>
+        <CdsListItem link title="Вырезать" prepend-icon="copy" @click="lastAction = 'Вырезать'" />
+        <CdsListItem link title="Копировать" prepend-icon="copy" @click="lastAction = 'Копировать'" />
+        <CdsListItem link title="Вставить" prepend-icon="insert" @click="lastAction = 'Вставить'" />
+      </CdsList>
+    </CdsMenu>
+
+    <p class="text-100 text-content-secondary">{{ lastAction || 'Действие не выбрано' }}</p>
+  </div>
+</template>
+```
+
+## Menu in the header
+
+In the application header a menu solves two tasks: it expands the navigation sections and collects everything about the account behind the avatar. The activator of the user menu is a `CdsAvatar` inside a button with an `aria-label`, `location="bottom end"` pins the panel to the right edge, and `min-width` keeps it from jumping in width. The first list item shows whose account it is, and `CdsListItemDivider` separates the sections from signing out.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import {
+  CdsAvatar,
+  CdsButton,
+  CdsHeader,
+  CdsLayout,
+  CdsList,
+  CdsListItem,
+  CdsListItemDivider,
+  CdsMain,
+  CdsMenu
+} from '@central-design-system/components';
+import { ref } from 'vue';
+
+const sections = [
+  { title: 'Закупки', items: ['Мои закупки', 'Черновики', 'Архив'] },
+  { title: 'Договоры', items: ['Действующие', 'На согласовании'] }
+];
+
+const opened = ref('');
+</script>
+
+<template>
+  <div class="m-auto h-[220px] w-full max-w-[560px]">
+    <CdsLayout container>
+      <CdsHeader elevated>
+        <div class="flex h-[56px] items-center gap-2 px-4">
+          <span class="text-100 font-bold text-content-primary">B2B-Center</span>
+
+          <nav class="flex items-center gap-1">
+            <CdsMenu v-for="section in sections" :key="section.title" :min-width="180">
+              <template #activator="{ props }">
+                <CdsButton
+                  v-bind="props"
+                  size="sm"
+                  appearance="tertiary"
+                  append-icon="chevron-down"
+                  :text="section.title"
+                />
+              </template>
+
+              <CdsList slim>
+                <CdsListItem
+                  v-for="item in section.items"
+                  :key="item"
+                  link
+                  :title="item"
+                  @click="opened = `${section.title} → ${item}`"
+                />
+              </CdsList>
+            </CdsMenu>
+          </nav>
+
+          <div class="ml-auto">
+            <CdsMenu location="bottom end" :min-width="240">
+              <template #activator="{ props }">
+                <CdsButton v-bind="props" appearance="tertiary" aria-label="Меню пользователя">
+                  <CdsAvatar size="sm" text="ИП" />
+                </CdsButton>
+              </template>
+
+              <CdsList slim>
+                <CdsListItem lines="two" title="Иван Петров" subtitle="i.petrov@example.com">
+                  <template #prepend>
+                    <CdsAvatar size="sm" text="ИП" start />
+                  </template>
+                </CdsListItem>
+
+                <CdsListItemDivider />
+
+                <CdsListItem link title="Профиль" prepend-icon="user-avatar" @click="opened = 'Профиль'" />
+                <CdsListItem link title="Организация" prepend-icon="company" @click="opened = 'Организация'" />
+                <CdsListItem link title="Настройки" prepend-icon="settings" @click="opened = 'Настройки'" />
+
+                <CdsListItemDivider />
+
+                <CdsListItem link title="Выйти" prepend-icon="logout" @click="opened = 'Выход из аккаунта'" />
+              </CdsList>
+            </CdsMenu>
+          </div>
+        </div>
+      </CdsHeader>
+
+      <CdsMain>
+        <p class="p-4 text-100 text-content-secondary">{{ opened || 'Выберите пункт в меню шапки' }}</p>
+      </CdsMain>
+    </CdsLayout>
+  </div>
+</template>
+```
+
+## Filter with several values
+
+When several values are picked inside a menu, the panel must not close on the very first click: `:close-on-content-click="false"` keeps it open, and `v-model` lets the "Apply" button close the menu. The selection piles up in a draft and is applied as a whole — until the button is pressed, the list of records does not change.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsButton, CdsCheckbox, CdsMenu, CdsSurface } from '@central-design-system/components';
+import { computed, ref, watch } from 'vue';
+
+const statuses = [
+  { title: 'Черновик', value: 'draft' },
+  { title: 'На согласовании', value: 'review' },
+  { title: 'Подписан', value: 'signed' },
+  { title: 'Отклонён', value: 'rejected' }
+];
+
+const isOpen = ref(false);
+const draft = ref<string[]>(['review']);
+const applied = ref<string[]>(['review']);
+
+const appliedTitles = computed(() =>
+  statuses.filter((status) => applied.value.includes(status.value)).map((status) => status.title)
+);
+
+const apply = () => {
+  applied.value = [...draft.value];
+  isOpen.value = false;
+};
+
+const reset = () => {
+  draft.value = [];
+};
+
+watch(isOpen, (value) => {
+  if (value) draft.value = [...applied.value];
+});
+</script>
+
+<template>
+  <div class="m-auto flex w-[380px] flex-col items-center gap-1">
+    <CdsMenu v-model="isOpen" :close-on-content-click="false" :min-width="240">
+      <template #activator="{ props }">
+        <CdsButton v-bind="props" appearance="secondary" prepend-icon="filters">
+          Статус<template v-if="applied.length">: {{ applied.length }}</template>
+        </CdsButton>
+      </template>
+
+      <CdsSurface class="flex flex-col gap-2 p-2">
+        <CdsCheckbox
+          v-for="status in statuses"
+          :key="status.value"
+          v-model="draft"
+          :value="status.value"
+          :label="status.title"
+          hide-details
+        />
+
+        <div class="flex justify-between gap-2">
+          <CdsButton size="sm" appearance="tertiary" text="Сбросить" @click="reset" />
+          <CdsButton size="sm" text="Применить" @click="apply" />
+        </div>
+      </CdsSurface>
+    </CdsMenu>
+
+    <p class="text-100 text-content-secondary">
+      {{ appliedTitles.length ? `Показаны: ${appliedTitles.join(', ')}` : 'Фильтр не выбран' }}
+    </p>
+  </div>
+</template>
+```

package/skills/cds-builder/references/components/cds-menu/guidelines.md

@@ -0,0 +1,10 @@
+# CdsMenu — guidelines
+
+> Extracted from `docs/demos/Guidelines.vue` by `bun run generate:skill`. Do not edit manually.
+> The full component contract is in [api.md](api.md).
+
+| ✅ Do | ❌ Don't |
+| --- | --- |
+| The activator names what is inside the menu: a label or the well-known «⋮» icon makes it clear that a list of actions will open. | An icon with no label and no aria-label promises nothing — the menu gets opened at random. |
+| A menu triggers actions. A field value is picked in a select — it stays visible and takes part in the form submission. | A menu used instead of a field hides the selected value and drops out of the form validation. |
+| Rare actions on a record are collected in a single menu behind the «⋮» button — press it to see the list. The row stays readable. | A row of equally weighted buttons in every line overloads the table and hides the main action. |

package/skills/cds-builder/references/components/cds-menu/tokens.md

@@ -0,0 +1,19 @@
+# CdsMenu — tokens (level 3)
+
+> Copy of the component's `styles/*.variables.scss`, taken by `bun run generate:skill`. Do not edit manually.
+> `--cds-*` are global level-2 tokens whose values come from the active theme: see [themes.md](../../tokens/themes.md).
+> Variables marked `!default` can be overridden at build time via SCSS.
+
+## _CdsMenu.variables.scss
+
+```scss
+@use '../../../styles/settings';
+
+$menu-padding: var(--cds-spacing-100) !default;
+$menu-border-radius: settings.$border-radius-root !default;
+$menu-border: var(--cds-border-100) solid !default;
+$menu-colors: (
+  'background': rgb(var(--cds-color-surface-elevated)),
+  'border': rgb(var(--cds-color-line-elevated))
+) !default;
+```

package/skills/cds-builder/references/components/cds-messages/api.md

@@ -0,0 +1,29 @@
+# CdsMessages — API
+
+> Generated from meta.json by `bun run generate:skill`. Do not edit manually.
+> Examples: [examples.md](examples.md) · Tokens: [tokens.md](tokens.md)
+
+The block of messages under an input: a hint, an explanation or a validation error. The messages appear and disappear with an animation, so the line under the field does not jerk the layout.
+
+## CdsMessages
+
+**Props**
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `active` | `boolean \| undefined` | — | no | Active state |
+| `activeColor` | `string \| undefined` | — | no | Color of the component in its active state |
+| `baseColor` | `string \| undefined` | — | no | Color of the component in its inactive state |
+| `bgColor` | `string \| undefined` | — | no | Background color of the component |
+| `color` | `string \| undefined` | — | no | Component color |
+| `hideMessages` | `boolean \| undefined` | — | no | Hide the messages under the input |
+| `messages` | `string \| readonly string[] \| undefined` | `[]` | no | Messages shown under the input |
+| `textColor` | `string \| undefined` | — | no | Text color of the component |
+| `transition` | `string \| boolean \| (TransitionProps & { component?: Component \| undefined; }) \| { component: Component; leaveAbsolute: boolean; group: boolean; } \| null \| undefined` | `{ component: slide-transition-y, leaveAbsolute: true, group: true }` | no | Transition animation |
+
+**Slots**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `default` | `any` | Your own look for the whole list of messages instead of the default one |
+| `message` | `CdsMessageSlot` | Template for a single message. The slot props carry the text of the message |