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

package/skills/cds-builder/references/components/cds-tag-group/examples.md

@@ -0,0 +1,346 @@
+# CdsTagGroup — 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 tag group turns a set of [CdsTag](../cds-tag/api.md) into a toggle: the selected tag is highlighted, the value is available through `v-model`, and the tags that do not fit move into a horizontal scroll. Fits catalog filters, category pickers and quick period switches.
+
+## Selection
+
+Give every tag a `value` — exactly this value lands in `v-model`. Without `value` the index of the tag in the group becomes its value. A repeated click on the selected tag clears the selection.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsTag, CdsTagGroup } from '@central-design-system/components';
+import { ref } from 'vue';
+
+const categories = ['Электроника', 'Одежда', 'Мебель', 'Спорт', 'Книги'];
+const selected = ref('Электроника');
+</script>
+
+<template>
+  <div class="flex flex-col items-center gap-2">
+    <CdsTagGroup v-model="selected">
+      <CdsTag v-for="category in categories" :key="category" :value="category" :text="category" />
+    </CdsTagGroup>
+
+    <span class="text-100 text-content-secondary">Выбрано: {{ selected ?? '—' }}</span>
+  </div>
+</template>
+```
+
+## Multiple selection
+
+The `multiple` prop allows selecting several tags — `v-model` becomes an array of values.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsTag, CdsTagGroup } from '@central-design-system/components';
+import { ref } from 'vue';
+
+const deliveries = ['Самовывоз', 'Курьер', 'Почта', 'Транспортная компания'];
+const selected = ref(['Курьер', 'Почта']);
+</script>
+
+<template>
+  <div class="flex flex-col items-center gap-2">
+    <CdsTagGroup v-model="selected" multiple>
+      <CdsTag v-for="delivery in deliveries" :key="delivery" :value="delivery" :text="delivery" />
+    </CdsTagGroup>
+
+    <span class="text-100 text-content-secondary">Выбрано: {{ selected.join(', ') || '—' }}</span>
+  </div>
+</template>
+```
+
+## Multiple selection
+
+The `max` prop limits the number of selected tags: once the limit is reached, clicks on the remaining tags do not add to the selection.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsTag, CdsTagGroup } from '@central-design-system/components';
+import { ref } from 'vue';
+
+const deliveries = ['Самовывоз', 'Курьер', 'Почта', 'Транспортная компания'];
+const selected = ref(['Курьер']);
+</script>
+
+<template>
+  <div class="flex flex-col items-center gap-2">
+    <CdsTagGroup v-model="selected" multiple :max="2">
+      <CdsTag v-for="delivery in deliveries" :key="delivery" :value="delivery" :text="delivery" />
+    </CdsTagGroup>
+
+    <span class="text-100 text-content-secondary">Выбрано {{ selected.length }} из 2</span>
+  </div>
+</template>
+```
+
+## Mandatory selection
+
+The `mandatory` prop does not let you clear the last selection: a tag can only be switched. With the `'force'` value the first available tag is selected automatically, even when `v-model` is empty.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsTag, CdsTagGroup } from '@central-design-system/components';
+import { ref } from 'vue';
+
+const periods = ['Неделя', 'Месяц', 'Квартал', 'Год'];
+const selected = ref('Месяц');
+</script>
+
+<template>
+  <div class="flex flex-col items-center gap-2">
+    <CdsTagGroup v-model="selected" mandatory>
+      <CdsTag v-for="period in periods" :key="period" :value="period" :text="period" />
+    </CdsTagGroup>
+
+    <span class="text-100 text-content-secondary">
+      Период: {{ selected }} — снять выбор нельзя, можно только переключить
+    </span>
+  </div>
+</template>
+```
+
+## Selection indicator
+
+The `filter` prop adds a check icon to the selected tags — the selection reads not only from the fill. The `filter-icon` prop of the tag changes the icon, and the `filter` slot replaces it with your own markup.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsTag, CdsTagGroup } from '@central-design-system/components';
+import { ref } from 'vue';
+
+const statuses = ['Черновики', 'На проверке', 'Опубликованные', 'В архиве'];
+const selected = ref(['На проверке']);
+</script>
+
+<template>
+  <div class="flex flex-col items-center gap-2">
+    <CdsTagGroup v-model="selected" multiple filter>
+      <CdsTag v-for="status in statuses" :key="status" :value="status" :text="status" />
+    </CdsTagGroup>
+
+    <span class="text-100 text-content-secondary">Выбрано: {{ selected.join(', ') || '—' }}</span>
+  </div>
+</template>
+```
+
+## Color and disabling
+
+The group passes the `color`, `active-color`, `disabled` and `filter` props to its tags as defaults — there is no need to repeat them on every tag. `color` paints the unselected tags, `active-color` paints the selected one; without it the selected tag stays in the brand color so that the selection reads with any palette. `disabled` blocks the whole group: the selection is visible but cannot be switched. A prop set directly on a tag wins over the value of the group.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsTag, CdsTagGroup } from '@central-design-system/components';
+import { ref } from 'vue';
+
+const formats = ['Отчёт', 'Презентация', 'Таблица'];
+const colored = ref('Отчёт');
+const active = ref('Отчёт');
+const locked = ref('Презентация');
+</script>
+
+<template>
+  <div class="m-auto flex w-[320px] flex-col gap-4">
+    <div class="flex flex-col gap-1">
+      <span class="text-100 text-content-secondary">color — цвет невыбранных тегов</span>
+
+      <CdsTagGroup v-model="colored" color="red">
+        <CdsTag v-for="format in formats" :key="format" :value="format" :text="format" />
+      </CdsTagGroup>
+    </div>
+
+    <div class="flex flex-col gap-1">
+      <span class="text-100 text-content-secondary">active-color — цвет выбранного тега</span>
+
+      <CdsTagGroup v-model="active" color="green" active-color="red">
+        <CdsTag v-for="format in formats" :key="format" :value="format" :text="format" />
+      </CdsTagGroup>
+    </div>
+
+    <div class="flex flex-col gap-1">
+      <span class="text-100 text-content-secondary">disabled — выбор сохраняется, но недоступен</span>
+
+      <CdsTagGroup v-model="locked" disabled>
+        <CdsTag v-for="format in formats" :key="format" :value="format" :text="format" />
+      </CdsTagGroup>
+    </div>
+  </div>
+</template>
+```
+
+## Layout
+
+By default the tags stand in a single row, and the extra ones move into a horizontal scroll with arrows: the group is built on [CdsSlideGroup](../cds-slide-group/api.md) and accepts its props — `show-arrows`, `direction`, `center-active`. The `column` prop wraps the tags into rows instead of scrolling — that way all the options are visible at once.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsTag, CdsTagGroup } from '@central-design-system/components';
+import { ref } from 'vue';
+
+const categories = ['Электроника', 'Бытовая техника', 'Одежда', 'Обувь', 'Мебель', 'Спорт', 'Книги', 'Игрушки'];
+
+const scrolled = ref('Электроника');
+const wrapped = ref('Электроника');
+</script>
+
+<template>
+  <div class="m-auto flex w-[360px] flex-col gap-4">
+    <div class="flex flex-col gap-1">
+      <span class="text-1 text-content-secondary">По умолчанию — горизонтальная прокрутка со стрелками</span>
+
+      <CdsTagGroup v-model="scrolled">
+        <CdsTag v-for="category in categories" :key="category" :value="category" :text="category" />
+      </CdsTagGroup>
+    </div>
+
+    <div class="flex flex-col gap-1">
+      <span class="text-1 text-content-secondary">column — перенос по строкам</span>
+
+      <CdsTagGroup v-model="wrapped" column>
+        <CdsTag v-for="category in categories" :key="category" :value="category" :text="category" />
+      </CdsTagGroup>
+    </div>
+  </div>
+</template>
+```
+
+## Catalog filter
+
+A row of categories above the results is the most common job for a tag group. `column` shows all the categories at once, `mandatory` prevents ending up without a filter, and `v-model` gives you a ready key for the product request.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsTag, CdsTagGroup } from '@central-design-system/components';
+import { computed, ref } from 'vue';
+
+const products = [
+  { name: 'Ноутбук Alfa 14', category: 'Ноутбуки', price: '68 900 ₽' },
+  { name: 'Ноутбук Beta Pro', category: 'Ноутбуки', price: '94 500 ₽' },
+  { name: 'Смартфон Gamma 5', category: 'Смартфоны', price: '32 400 ₽' },
+  { name: 'Смартфон Delta Mini', category: 'Смартфоны', price: '21 900 ₽' },
+  { name: 'Монитор Epsilon 27"', category: 'Мониторы', price: '27 300 ₽' }
+];
+
+const categories = ['Все', 'Ноутбуки', 'Смартфоны', 'Мониторы'];
+const category = ref('Все');
+
+const filtered = computed(() =>
+  category.value === 'Все' ? products : products.filter((product) => product.category === category.value)
+);
+</script>
+
+<template>
+  <div class="m-auto flex w-[360px] flex-col gap-2">
+    <CdsTagGroup v-model="category" column mandatory>
+      <CdsTag v-for="item in categories" :key="item" :value="item" :text="item" />
+    </CdsTagGroup>
+
+    <div class="flex flex-col gap-1">
+      <div
+        v-for="product in filtered"
+        :key="product.name"
+        class="flex items-center justify-between rounded-200 bg-surface-secondary p-2"
+      >
+        <span>{{ product.name }}</span>
+        <span class="text-100 text-content-secondary">{{ product.price }}</span>
+      </div>
+    </div>
+
+    <span class="text-100 text-content-secondary">Найдено товаров: {{ filtered.length }}</span>
+  </div>
+</template>
+```
+
+## Picking several topics
+
+When the values do not exclude each other, turn on `multiple`. `max` keeps the selection within reasonable bounds, `filter` marks the selected topics with a check, and the hint under the group explains the limit.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsTag, CdsTagGroup } from '@central-design-system/components';
+import { computed, ref } from 'vue';
+
+const topics = ['Аналитика', 'Дизайн', 'Разработка', 'Маркетинг', 'Продажи', 'Логистика', 'Поддержка'];
+const selected = ref(['Дизайн']);
+
+const isFull = computed(() => selected.value.length >= 3);
+</script>
+
+<template>
+  <div class="m-auto flex w-[360px] flex-col gap-2">
+    <span>Выберите до трёх тем — по ним будем присылать дайджест</span>
+
+    <CdsTagGroup v-model="selected" column multiple filter :max="3">
+      <CdsTag v-for="topic in topics" :key="topic" :value="topic" :text="topic" />
+    </CdsTagGroup>
+
+    <span class="text-100" :class="isFull ? 'text-content-secondary' : 'text-content-tertiary'">
+      {{ isFull ? 'Лимит достигнут — снимите тему, чтобы выбрать другую' : `Выбрано ${selected.length} из 3` }}
+    </span>
+  </div>
+</template>
+```
+
+## Switching the period
+
+The group exposes the `next`, `prev` and `select` methods and the `selected` list — get them through a `ref` on the component. This is how tags get the back / forward arrows that walk through the periods in order.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsFunctionalButton, CdsTag, CdsTagGroup } from '@central-design-system/components';
+import { ref } from 'vue';
+
+const revenue: Record<string, string> = {
+  'I квартал': '1,2 млн ₽',
+  'II квартал': '1,8 млн ₽',
+  'III квартал': '2,4 млн ₽',
+  'IV квартал': '3,1 млн ₽'
+};
+
+const quarters = Object.keys(revenue);
+const quarter = ref('II квартал');
+const group = ref<InstanceType<typeof CdsTagGroup> | null>(null);
+</script>
+
+<template>
+  <div class="m-auto flex w-[420px] flex-col items-center gap-2">
+    <div class="flex items-center gap-1">
+      <CdsFunctionalButton icon="prev" aria-label="Предыдущий квартал" @click="group?.prev()" />
+
+      <CdsTagGroup ref="group" v-model="quarter" mandatory>
+        <CdsTag v-for="item in quarters" :key="item" :value="item" :text="item" />
+      </CdsTagGroup>
+
+      <CdsFunctionalButton icon="next" aria-label="Следующий квартал" @click="group?.next()" />
+    </div>
+
+    <div class="flex w-full flex-col items-center rounded-200 bg-surface-secondary p-4">
+      <span class="text-900">{{ revenue[quarter] }}</span>
+      <span class="text-content-secondary">выручка за {{ quarter.toLowerCase() }}</span>
+    </div>
+  </div>
+</template>
+```

package/skills/cds-builder/references/components/cds-tag-group/guidelines.md

@@ -0,0 +1,10 @@
+# CdsTagGroup — 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 |
+| --- | --- |
+| One group — one attribute: the values exclude each other and read as a row of equals. | Different attributes in one group: you cannot pick a category and a price at the same time. |
+| In a narrow block use column: all the options are visible at once. | A horizontal scroll in a narrow column hides half of the options behind an arrow. |
+| A tag group holds a few popular values — they are visible without expanding anything. | Dozens of values turn into a tag cloud: picking from such a list is more convenient in CdsSelect. |

package/skills/cds-builder/references/components/cds-tag-group/tokens.md

@@ -0,0 +1,18 @@
+# CdsTagGroup — 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.
+
+## _CdsTagGroup.variables.scss
+
+```scss
+// Внутренний отступ группы и промежуток между тегами.
+$tag-group-padding: var(--cds-spacing-100) !default;
+$tag-group-gap: var(--cds-spacing-100) !default;
+
+// Выбранное состояние тега: заливка брендовым цветом с контентом на тёмном фоне.
+$tag-group-selected-background: rgb(var(--cds-color-brand-primary)) !default;
+$tag-group-selected-background-hover: rgb(var(--cds-color-brand-primary-hover)) !default;
+$tag-group-selected-color: rgb(var(--cds-color-content-on-dark)) !default;
+```

package/skills/cds-builder/references/components/cds-text-area/api.md

@@ -0,0 +1,113 @@
+# CdsTextArea — API
+
+> Generated from meta.json by `bun run generate:skill`. Do not edit manually.
+> Examples: [examples.md](examples.md) · Guidelines: [guidelines.md](guidelines.md) · Tokens: [tokens.md](tokens.md)
+
+A text area is a field for multiline text: a comment, a description, a support request. Around the native `textarea` the component gathers everything a form needs: a label, a description, hints, error messages, clearing and a character counter, and with `auto-grow` it grows together with the text.
+
+## CdsTextArea
+
+**Props**
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `active` | `boolean \| undefined` | — | no | Active state of the field |
+| `activeColor` | `string \| undefined` | — | no | Color of the component in its active state |
+| `appendIcon` | `IconValue \| undefined` | — | no | Icon in the append slot, after the content |
+| `appendInnerIcon` | `IconValue \| undefined` | — | no | Icon in the inner append slot, after the content of the field |
+| `autocomplete` | `string \| undefined` | — | no | Helps to influence browser suggestions. The `suppress` value changes the name attribute of the fields, and `off` relies on the browser to stop suggesting values on its own. Any other value is passed to the built-in autocomplete of the corresponding element. |
+| `autofocus` | `boolean \| undefined` | — | no | Enables autofocus |
+| `autoGrow` | `boolean \| undefined` | — | no | Automatic growth of the text area height as you type |
+| `baseColor` | `string \| undefined` | — | no | Color of the component in its inactive state |
+| `bgColor` | `string \| undefined` | — | no | Background color of the component |
+| `centerAffix` | `boolean \| undefined` | — | no | Vertically center the appendInner, prependInner, clearIcon and label elements. |
+| `clearable` | `boolean \| undefined` | — | no | Shows the clear button |
+| `clearIcon` | `IconValue \| undefined` | `'remove'` | no | Icon of the clear button |
+| `color` | `string \| undefined` | — | no | Component color |
+| `counter` | `string \| number \| boolean \| undefined` | — | no | Character counter. Accepts a boolean, a number or a string |
+| `counterValue` | `number \| ((value: any) => number) \| undefined` | — | no | Custom counter value. Either a number or a function computing it from the current value |
+| `description` | `string \| undefined` | — | no | Description of the component, shown under the label |
+| `dirty` | `boolean \| undefined` | — | no | Marks that the value of the field was changed by the user |
+| `disabled` | `boolean \| null \| undefined` | `null` | no | Disabled state |
+| `error` | `boolean \| undefined` | — | no | Error state |
+| `errorMessages` | `string \| readonly string[] \| null \| undefined` | `[]` | no | Puts the component into the error state and passes custom error messages. They are merged with any checks defined in the `rules` prop. This field does not trigger validation. |
+| `focused` | `boolean \| undefined` | — | no | Controls the focus state of the component. When `true`, the component is considered focused and may apply the corresponding styles or behavior. |
+| `hideDetails` | `boolean \| "auto" \| undefined` | — | no | Hides the details block (messages and hints). With the 'auto' value the block is hidden when there are no messages |
+| `hideMessages` | `boolean \| undefined` | — | no | Hide the messages under the input |
+| `hint` | `string \| undefined` | — | no | Hint text shown under the input |
+| `iconColor` | `string \| boolean \| undefined` | — | no | Icon color. Accepts a boolean or a color string |
+| `id` | `string \| undefined` | — | no | Unique identifier of the component |
+| `label` | `string \| undefined` | — | no | Label text of the component |
+| `loading` | `string \| boolean \| undefined` | — | no | Loading indicator for the component |
+| `maxErrors` | `string \| number \| undefined` | `1` | no | Maximum number of validation errors shown |
+| `maxHeight` | `string \| number \| undefined` | — | no | Maximum height of the text area |
+| `maxRows` | `string \| number \| undefined` | — | no | Maximum number of rows while the height grows automatically |
+| `maxWidth` | `string \| number \| undefined` | — | no | Maximum component width |
+| `messages` | `string \| readonly string[] \| undefined` | `[]` | no | Messages shown under the input |
+| `minWidth` | `string \| number \| undefined` | — | no | Minimum component width |
+| `modelModifiers` | `Record<string, boolean> \| undefined` | — | no | The v-model modifiers passed by Vue to process the field value |
+| `modelValue` | `any` | — | no | Value of the component in v-model. If the component supports the multiple prop, an empty array is used by default. |
+| `name` | `string \| undefined` | — | no | Name of the input |
+| `noResize` | `boolean \| undefined` | — | no | Turn off the ability to resize the text area |
+| `persistentClearable` | `boolean \| undefined` | — | no | Always show the clear button, not only on hover or focus |
+| `persistentCounter` | `boolean \| undefined` | — | no | Always show the counter, not only while the field is in use |
+| `persistentHint` | `boolean \| undefined` | — | no | Always show the hint, not only on focus |
+| `persistentPlaceholder` | `boolean \| undefined` | — | no | Always show the placeholder instead of hiding it while the field is in use |
+| `placeholder` | `string \| undefined` | — | no | Placeholder text shown in an empty field |
+| `prefix` | `string \| undefined` | — | no | Text prefix shown before the field value |
+| `prependIcon` | `IconValue \| undefined` | — | no | Icon in the prepend slot, before the content |
+| `prependInnerIcon` | `IconValue \| undefined` | — | no | Icon in the inner prepend slot, before the content of the field |
+| `readonly` | `boolean \| null \| undefined` | `null` | no | Read-only state |
+| `reverse` | `boolean \| undefined` | — | no | Reverses the order of the elements inside the field |
+| `rows` | `string \| number \| undefined` | `5` | no | Number of rows of the text area |
+| `rules` | `readonly ValidationRule[] \| undefined` | `[]` | no | Accepts an array of items of different types: functions, booleans and strings. Functions take the input value as an argument and must return either true / false, or a string with an error message. The input goes into the error state if a function returns false (or any value in the array is false) or is a string. |
+| `size` | `number \| "xs" \| "sm" \| "md" \| "lg" \| "xl" \| undefined` | `'md'` | no | Size of the component |
+| `suffix` | `string \| undefined` | — | no | Text suffix shown after the field value |
+| `textColor` | `string \| undefined` | — | no | Text color of the component |
+| `theme` | `string \| undefined` | — | no | Component theme |
+| `validateOn` | `ValidateOn \| undefined` | — | no | Changes the type of the event that triggers validation |
+| `validationValue` | `any` | — | no | Value used when applying the validation rules |
+| `width` | `string \| number \| undefined` | — | no | Component width |
+
+**Events**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `click:control` | `[e: MouseEvent]` | Fires on a click in the main area of the control |
+| `mousedown:control` | `[e: MouseEvent]` | Fires on a mouse button press in the main area of the control |
+| `update:focused` | `[focused: boolean]` | Fires when the element gains or loses focus |
+| `update:modelValue` | `[value: string]` | Fires when the model of the component changes |
+| `update:rows` | `[rows: number]` | Fires when the computed number of rows changes while the height grows automatically |
+
+**Slots**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `append` | `CdsInputSlot` | Adds an element after the input |
+| `append-inner` | `CdsInputDefaultSlot` | Slot added at the end of the input |
+| `clear` | `CdsInputDefaultSlot & { props: Record<string, any>; }` | Slot for a custom clear icon (shown when the clearable prop is true). |
+| `counter` | `CdsCounterSlot` | Slot for a custom counter |
+| `description` | `{ description: string \| undefined; props: Record<string, any>; }` | Default slot of the CdsDescription component |
+| `details` | `CdsInputSlot` | Slot for custom content that lets you customize how the messages are displayed |
+| `label` | `{ label: string \| undefined; props: Record<string, any>; }` | Default slot of the CdsLabel component |
+| `loader` | `LoaderSlotProps` | Slot for a custom loader (shown when the loading prop is true). |
+| `message` | `CdsMessagesSlots` | Slot for customizing the content of a message |
+| `messages` | `CdsInputSlot` | Slot for custom content that lets you customize how the messages are displayed |
+| `prepend` | `CdsInputSlot` | Adds an element before the input |
+| `prepend-inner` | `CdsInputDefaultSlot` | Slot added at the start of the input |
+
+**Exposed**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `controlRef` | `HTMLElement \| undefined` | Ref to the control of the input |
+| `fieldIconColor` | `string \| undefined` | Icon color |
+| `isDirty` | `boolean` | Whether the input is dirty |
+| `isDisabled` | `boolean` | Whether the input is disabled |
+| `isPure` | `boolean` | Whether the input is pure |
+| `isReadonly` | `boolean` | Whether the input is read-only |
+| `isValid` | `boolean \| null` | Whether the input is valid |
+| `isValidating` | `boolean` | Whether the input is being validated |
+| `reset` | `() => Promise<void>` | Resets the input to its initial state |
+| `resetValidation` | `() => Promise<void>` | Resets the validation of the input |
+| `validate` | `(silent?: boolean) => Promise<string[]>` | Validates the input |