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

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

@@ -0,0 +1,653 @@
+# CdsList — 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 list shows a set of records of the same kind — menu sections, documents, employees, settings — so that the one you need is easy to find and pick. Build it from an `items` array in a single line, or from `CdsListItem` components when a row is more than a title with an icon.
+
+## List data
+
+The `items` prop takes an array of objects and builds the whole list out of it. The `title` field gives the heading, `value` — the value of the item (this is how the list knows what is selected), `props` — any props of `CdsListItem`.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsList } from '@central-design-system/components';
+
+const items = [
+  { title: 'Профиль', value: 'profile', props: { prependIcon: 'user-avatar' } },
+  { title: 'Организация', value: 'company', props: { prependIcon: 'company' } },
+  { title: 'Сотрудники', value: 'employees', props: { prependIcon: 'user-group' } },
+  { title: 'Настройки', value: 'settings', props: { prependIcon: 'settings' } }
+];
+</script>
+
+<template>
+  <CdsList class="m-auto w-[200px]" :items="items" />
+</template>
+```
+
+## List data
+
+When the data arrives from the server in its own format, do not reshape it: `item-title`, `item-value` and `item-children` tell the list which fields to take. Each of them accepts both a field name and a function — that way, for example, `item-props` assembles the props of an item from several fields of the object.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsList } from '@central-design-system/components';
+
+const employees = [
+  { id: 1, name: 'Анна Смирнова', role: 'Руководитель отдела закупок' },
+  { id: 2, name: 'Дмитрий Орлов', role: 'Менеджер по тендерам' },
+  { id: 3, name: 'Елена Васильева', role: 'Юрист' },
+  { id: 4, name: 'Игорь Крылов', role: 'Бухгалтер' }
+];
+</script>
+
+<template>
+  <CdsList
+    class="m-auto w-[250px]"
+    :items="employees"
+    item-title="name"
+    item-value="id"
+    :item-props="(item: Record<string, any>) => ({ subtitle: item.role, prependIcon: 'user-avatar' })"
+    lines="two"
+  />
+</template>
+```
+
+## List data
+
+The `props` field configures a single item: adds icons, turns on the active state or disables the row.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsList } from '@central-design-system/components';
+
+const items = [
+  { title: 'Черновик', value: 'draft', props: { prependIcon: 'doc' } },
+  { title: 'На согласовании', value: 'review', props: { prependIcon: 'clock', appendIcon: 'chevron-right' } },
+  { title: 'Опубликован', value: 'published', props: { prependIcon: 'check', active: true } },
+  { title: 'В архиве', value: 'archived', props: { prependIcon: 'archive', disabled: true } }
+];
+</script>
+
+<template>
+  <CdsList class="m-auto w-[280px]" :items="items" />
+</template>
+```
+
+## Item content
+
+An item has three text blocks: `title` names the record, `subtitle` refines it, `description` adds an explanation. On the sides stand an icon (`prepend-icon`, `append-icon`) or an avatar (`prepend-avatar`, `append-avatar`).
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsList, CdsListItem } from '@central-design-system/components';
+</script>
+
+<template>
+  <CdsList class="m-auto w-[360px]" :lines="false">
+    <CdsListItem prepend-icon="doc" title="Счёт на оплату № 5512" />
+
+    <CdsListItem prepend-icon="doc" title="Договор аренды № 17" subtitle="ООО «Ромашка»" />
+
+    <CdsListItem
+      prepend-icon="doc"
+      append-icon="chevron-right"
+      title="Акт сверки за март"
+      subtitle="ООО «Ромашка»"
+      description="Ожидает подписания второй стороной"
+    />
+
+    <CdsListItem
+      prepend-avatar="https://i.pravatar.cc/80?img=47"
+      title="Анна Смирнова"
+      subtitle="Руководитель отдела закупок"
+    />
+  </CdsList>
+</template>
+```
+
+## Item content
+
+The `lines` prop limits the subtitle and the description to one, two or three lines — the rest of the text is truncated with an ellipsis, and records with text of different length keep a common rhythm. With `three`, the icons in the `prepend` and `append` areas align to the top of the record instead of its center. `:lines="false"` removes the limit — the text takes as many lines as it needs.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsList } from '@central-design-system/components';
+
+const lines = ['one', 'two', 'three'] as const;
+
+const items = [
+  {
+    title: 'Договор поставки № 42 от 14 марта',
+    value: 'supply',
+    props: {
+      prependIcon: 'doc',
+      subtitle:
+        'ООО «Ромашка» · поставка канцелярии и расходных материалов для филиалов в Москве и Санкт-Петербурге до конца квартала'
+    }
+  },
+  {
+    title: 'Акт сверки взаиморасчётов за март',
+    value: 'act',
+    props: {
+      prependIcon: 'doc',
+      subtitle: 'ООО «Василёк» · расхождений не выявлено, подписан обеими сторонами 12 марта'
+    }
+  }
+];
+</script>
+
+<template>
+  <div class="m-auto flex flex-wrap justify-center gap-4">
+    <div v-for="line of lines" :key="line" class="flex w-[280px] flex-col gap-1">
+      <span class="text-100 text-content-secondary">lines="{{ line }}"</span>
+      <CdsList :items="items" :lines="line" />
+    </div>
+  </div>
+</template>
+```
+
+## Structure
+
+Items with `type: 'subheader'` and `type: 'divider'` split the list into sections: a subheader names a group of records, a divider separates blocks without a heading.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsList } from '@central-design-system/components';
+
+const items = [
+  { type: 'subheader', title: 'Сегодня' },
+  { title: 'Договор поставки № 42', value: 'supply', props: { prependIcon: 'doc' } },
+  { title: 'Счёт на оплату № 5512', value: 'invoice', props: { prependIcon: 'doc' } },
+  { type: 'divider' },
+  { type: 'subheader', title: 'На прошлой неделе' },
+  { title: 'Акт сверки за март', value: 'act', props: { prependIcon: 'doc' } },
+  { title: 'Договор аренды № 17', value: 'rent', props: { prependIcon: 'doc' } },
+  { title: 'Спецификация № 3', value: 'spec', props: { prependIcon: 'doc' } }
+];
+</script>
+
+<template>
+  <CdsList class="m-auto w-[250px]" :items="items" />
+</template>
+```
+
+## Structure
+
+A `children` array inside an item turns it into an expandable group — the list manages its state on its own, and `v-model:opened` lets you manage it from the outside. Nesting is not limited to a single level.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsList } from '@central-design-system/components';
+import { ref } from 'vue';
+
+const opened = ref(['contracts']);
+
+const items = [
+  { title: 'Все документы', value: 'all', props: { prependIcon: 'directory' } },
+  {
+    title: 'Договоры',
+    value: 'contracts',
+    props: { prependIcon: 'directory' },
+    children: [
+      { title: 'Поставка', value: 'supply', props: { prependIcon: 'doc' } },
+      { title: 'Аренда', value: 'rent', props: { prependIcon: 'doc' } },
+      {
+        title: 'Услуги',
+        value: 'services',
+        props: { prependIcon: 'directory' },
+        children: [
+          { title: 'Разовые', value: 'services-single', props: { prependIcon: 'doc' } },
+          { title: 'Абонентские', value: 'services-regular', props: { prependIcon: 'doc' } }
+        ]
+      }
+    ]
+  },
+  {
+    title: 'Бухгалтерия',
+    value: 'accounting',
+    props: { prependIcon: 'directory' },
+    children: [
+      { title: 'Счета', value: 'invoices', props: { prependIcon: 'doc' } },
+      { title: 'Акты сверки', value: 'acts', props: { prependIcon: 'doc' } }
+    ]
+  }
+];
+</script>
+
+<template>
+  <CdsList v-model:opened="opened" class="m-auto w-[250px]" :items="items" />
+</template>
+```
+
+## Selection and activation
+
+The `activatable` prop highlights one item as the current one — this is about navigation: "you are here". `selectable` turns on picking records — this is about data: "send these ones". Both states are read through `v-model:activated` and `v-model:selected`, and `select-strategy` sets how many items can be picked at once: `single-leaf` (the default) — one, `independent` — as many as you like.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsList } from '@central-design-system/components';
+import { ref } from 'vue';
+
+const items = [
+  { title: 'Договоры', value: 'contracts' },
+  { title: 'Счета', value: 'invoices' },
+  { title: 'Акты сверки', value: 'acts' },
+  { title: 'Отчёты', value: 'reports' }
+];
+
+const activated = ref(['contracts']);
+const selected = ref(['invoices', 'acts']);
+</script>
+
+<template>
+  <div class="m-auto flex flex-wrap justify-center gap-4">
+    <div class="flex w-[260px] flex-col gap-1">
+      <span class="text-100 text-content-secondary">activatable — один активный элемент</span>
+      <CdsList v-model:activated="activated" activatable :items="items" />
+      <span class="text-100 text-content-secondary">activated: {{ activated }}</span>
+    </div>
+
+    <div class="flex w-[260px] flex-col gap-1">
+      <span class="text-100 text-content-secondary">selectable + select-strategy="independent"</span>
+      <CdsList v-model:selected="selected" selectable select-strategy="independent" :items="items" />
+      <span class="text-100 text-content-secondary">selected: {{ selected }}</span>
+    </div>
+  </div>
+</template>
+```
+
+## Appearance
+
+`nav` rounds the corners of active items — the look of a side menu. `slim` removes the inner paddings when the list sits in a narrow panel or a dropdown. `color` sets the color of active items, `bg-color` — the background of the list.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsList } from '@central-design-system/components';
+
+const items = [
+  { title: 'Профиль', value: 'profile', props: { prependIcon: 'user-avatar' } },
+  { title: 'Организация', value: 'company', props: { prependIcon: 'company', active: true } },
+  { title: 'Настройки', value: 'settings', props: { prependIcon: 'settings' } }
+];
+</script>
+
+<template>
+  <div class="m-auto flex flex-wrap justify-center gap-4">
+    <div class="flex w-[240px] flex-col gap-1">
+      <span class="text-100 text-content-secondary">по умолчанию</span>
+      <CdsList :items="items" />
+    </div>
+
+    <div class="flex w-[240px] flex-col gap-1">
+      <span class="text-100 text-content-secondary">nav</span>
+      <CdsList nav :items="items" />
+    </div>
+
+    <div class="flex w-[240px] flex-col gap-1">
+      <span class="text-100 text-content-secondary">slim</span>
+      <CdsList slim :items="items" />
+    </div>
+
+    <div class="flex w-[240px] flex-col gap-1">
+      <span class="text-100 text-content-secondary">color="brand-primary"</span>
+      <CdsList color="brand-primary" :items="items" />
+    </div>
+  </div>
+</template>
+```
+
+## Assembling from components
+
+When a row is more than a title with an icon, assemble it from `CdsListItem` by hand — the slots accept any components: tags, badges, avatars, buttons.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import {
+  CdsAvatar,
+  CdsBadge,
+  CdsFunctionalButton,
+  CdsIcon,
+  CdsList,
+  CdsListItem,
+  CdsTag
+} from '@central-design-system/components';
+</script>
+
+<template>
+  <CdsList class="m-auto w-[300px]" lines="two">
+    <CdsListItem value="supply">
+      <template #prepend>
+        <CdsIcon name="doc" />
+      </template>
+      <template #title>Договор поставки № 42</template>
+      <template #subtitle>ООО «Ромашка»</template>
+      <template #append>
+        <CdsTag size="sm" text="Подписан" color="green" />
+      </template>
+    </CdsListItem>
+
+    <CdsListItem value="act">
+      <template #prepend>
+        <CdsIcon name="doc" />
+      </template>
+      <template #title>Акт сверки за март</template>
+      <template #subtitle>ООО «Василёк»</template>
+      <template #append>
+        <CdsBadge inline content="3" />
+      </template>
+    </CdsListItem>
+
+    <CdsListItem value="manager">
+      <template #prepend>
+        <CdsAvatar size="sm" image="https://i.pravatar.cc/80?img=47" />
+      </template>
+      <template #title>Анна Смирнова</template>
+      <template #subtitle>Ответственная за закупку</template>
+      <template #append>
+        <CdsFunctionalButton icon="overflow-menu-vertical" aria-label="Ещё" />
+      </template>
+    </CdsListItem>
+  </CdsList>
+</template>
+```
+
+## Assembling from components
+
+The group passes the arrow to the activator as the default value for `append-icon`, and the `append` slot replaces that area entirely — so with your own content the arrow disappears. Bring it back with an empty `<CdsIcon />` next to it: the icon picks up the direction of the arrow from the defaults of the group and keeps toggling on expand.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsBadge, CdsIcon, CdsList, CdsListGroup, CdsListItem } from '@central-design-system/components';
+</script>
+
+<template>
+  <CdsList class="m-auto w-[250px]">
+    <CdsListItem value="all">
+      <template #prepend>
+        <CdsIcon name="directory" />
+      </template>
+      <template #title>Все документы</template>
+    </CdsListItem>
+
+    <CdsListGroup value="contracts">
+      <template #activator="{ props }">
+        <CdsListItem v-bind="props" value="contracts">
+          <template #prepend>
+            <CdsIcon name="directory" />
+          </template>
+          <template #title>Договоры</template>
+          <template #append>
+            <CdsBadge class="mr-2" inline content="12" />
+            <CdsIcon />
+          </template>
+        </CdsListItem>
+      </template>
+
+      <CdsListItem value="supply">
+        <template #prepend>
+          <CdsIcon name="doc" />
+        </template>
+        <template #title>Поставка</template>
+      </CdsListItem>
+
+      <CdsListItem value="rent">
+        <template #prepend>
+          <CdsIcon name="doc" />
+        </template>
+        <template #title>Аренда</template>
+      </CdsListItem>
+
+      <CdsListGroup value="services" subgroup>
+        <template #activator="{ props }">
+          <CdsListItem v-bind="props" value="services">
+            <template #title>Услуги</template>
+          </CdsListItem>
+        </template>
+
+        <CdsListItem value="services-single">
+          <template #prepend>
+            <CdsIcon name="doc" />
+          </template>
+          <template #title>Разовые</template>
+        </CdsListItem>
+
+        <CdsListItem value="services-regular">
+          <template #prepend>
+            <CdsIcon name="doc" />
+          </template>
+          <template #title>Абонентские</template>
+        </CdsListItem>
+      </CdsListGroup>
+    </CdsListGroup>
+
+    <CdsListGroup value="accounting">
+      <template #activator="{ props }">
+        <CdsListItem v-bind="props" value="accounting">
+          <template #prepend>
+            <CdsIcon name="directory" />
+          </template>
+          <template #title>Бухгалтерия</template>
+        </CdsListItem>
+      </template>
+
+      <CdsListItem value="invoices">
+        <template #prepend>
+          <CdsIcon name="doc" />
+        </template>
+        <template #title>Счета</template>
+      </CdsListItem>
+
+      <CdsListItem value="acts">
+        <template #prepend>
+          <CdsIcon name="doc" />
+        </template>
+        <template #title>Акты сверки</template>
+      </CdsListItem>
+    </CdsListGroup>
+  </CdsList>
+</template>
+```
+
+## Section menu
+
+A side menu is `activatable` plus `nav`: exactly one entry is active, `mandatory` forbids clearing the selection, and `v-model:activated` keeps the current section in the application state. Subheaders split the entries into meaningful blocks.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsList } from '@central-design-system/components';
+import { computed, ref } from 'vue';
+
+const activated = ref(['contracts']);
+
+const items: { type?: string; title: string; value?: string; props?: Record<string, unknown> }[] = [
+  { type: 'subheader', title: 'Работа' },
+  { title: 'Закупки', value: 'purchases', props: { prependIcon: 'shopping-cart' } },
+  { title: 'Договоры', value: 'contracts', props: { prependIcon: 'doc' } },
+  { title: 'Поставщики', value: 'suppliers', props: { prependIcon: 'company' } },
+  { type: 'subheader', title: 'Настройки' },
+  { title: 'Сотрудники', value: 'employees', props: { prependIcon: 'user-group' } },
+  { title: 'Уведомления', value: 'notifications', props: { prependIcon: 'notification' } }
+];
+
+const current = computed(() => items.find((item) => item.value === activated.value[0])?.title ?? 'ничего');
+</script>
+
+<template>
+  <div class="m-auto flex w-[250px] flex-col gap-2">
+    <CdsList v-model:activated="activated" activatable nav mandatory :items="items" />
+
+    <span class="text-100 text-content-secondary">Открыт раздел: {{ current }}</span>
+  </div>
+</template>
+```
+
+## Document list with actions
+
+The whole row stays clickable, and the action in the `append` area works on top of it — that is why the button has `@click.stop`, otherwise the click would reach the item and select it. The status next to the button is a regular [CdsTag](../cds-tag/api.md).
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsFunctionalButton, CdsList, CdsListItem, CdsTag } from '@central-design-system/components';
+import { ref } from 'vue';
+
+const documents = ref([
+  { id: 1, title: 'Договор поставки № 42', company: 'ООО «Ромашка»', status: 'Подписан' },
+  { id: 2, title: 'Акт сверки за март', company: 'ООО «Василёк»', status: 'На согласовании' },
+  { id: 3, title: 'Счёт на оплату № 5512', company: 'ООО «Ромашка»', status: 'Черновик' }
+]);
+
+const removed = ref<string[]>([]);
+
+function remove(id: number) {
+  const document = documents.value.find((item) => item.id === id);
+  if (!document) return;
+
+  removed.value = [...removed.value, document.title];
+  documents.value = documents.value.filter((item) => item.id !== id);
+}
+</script>
+
+<template>
+  <div class="m-auto flex w-[380px] flex-col gap-2">
+    <CdsList lines="two">
+      <CdsListItem
+        v-for="document of documents"
+        :key="document.id"
+        :value="document.id"
+        prepend-icon="doc"
+        :title="document.title"
+        :subtitle="document.company"
+      >
+        <template #append>
+          <div class="flex items-center gap-2">
+            <CdsTag size="sm" :text="document.status" />
+            <CdsFunctionalButton icon="delete" aria-label="Удалить документ" @click.stop="remove(document.id)" />
+          </div>
+        </template>
+      </CdsListItem>
+    </CdsList>
+
+    <span v-if="removed.length" class="text-100 text-content-secondary">Удалено: {{ removed.join(', ') }}</span>
+  </div>
+</template>
+```
+
+## Picking recipients
+
+The `prepend` slot receives `isSelected` and `select` — the selection state and the function that changes it. This lets you show a checkbox while keeping the click on the whole row: `CdsListItemAction` aligns it to the grid of the item, and `CdsAvatar` stands next to it.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsAvatar, CdsCheckbox, CdsList, CdsListItem, CdsListItemAction } from '@central-design-system/components';
+import { computed, ref } from 'vue';
+
+const people = [
+  { name: 'Анна Смирнова', email: 'a.smirnova@example.com', image: 'https://i.pravatar.cc/80?img=47' },
+  { name: 'Дмитрий Орлов', email: 'd.orlov@example.com', image: 'https://i.pravatar.cc/80?img=12' },
+  { name: 'Елена Васильева', email: 'e.vasileva@example.com', image: 'https://i.pravatar.cc/80?img=44' },
+  { name: 'Игорь Крылов', email: 'i.krylov@example.com', image: 'https://i.pravatar.cc/80?img=32' }
+];
+
+const selected = ref(['a.smirnova@example.com']);
+
+const summary = computed(() =>
+  selected.value.length ? `Выбрано получателей: ${selected.value.length}` : 'Получатели не выбраны'
+);
+</script>
+
+<template>
+  <div class="m-auto flex w-[300px] flex-col gap-2">
+    <CdsList v-model:selected="selected" selectable select-strategy="independent" lines="two">
+      <CdsListItem v-for="person of people" :key="person.email" :value="person.email" :title="person.name">
+        <template #prepend="{ isSelected, select }">
+          <CdsListItemAction start>
+            <CdsCheckbox :model-value="isSelected" hide-details tabindex="-1" @update:model-value="select" />
+          </CdsListItemAction>
+
+          <CdsAvatar size="sm" :image="person.image" />
+        </template>
+
+        <template #subtitle>{{ person.email }}</template>
+      </CdsListItem>
+    </CdsList>
+
+    <span class="text-100 text-content-secondary">{{ summary }}</span>
+  </div>
+</template>
+```
+
+## Searching through a list
+
+The list is rebuilt from the filtered array — it needs no logic of its own. When there are no matches, a [CdsEmptyState](../cds-empty-state/api.md) is shown instead of an empty list: the user understands that the reason is the query, not the loading.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsEmptyState, CdsList, CdsTextInput } from '@central-design-system/components';
+import { computed, ref } from 'vue';
+
+const query = ref('');
+
+const suppliers = [
+  { title: 'ООО «Ромашка»', value: 'romashka', props: { prependIcon: 'company', subtitle: 'Канцелярия' } },
+  { title: 'ООО «Василёк»', value: 'vasilek', props: { prependIcon: 'company', subtitle: 'Логистика' } },
+  {
+    title: 'АО «Северсталь-Комплект»',
+    value: 'severstal',
+    props: { prependIcon: 'company', subtitle: 'Металлопрокат' }
+  },
+  { title: 'ИП Кузнецов А. В.', value: 'kuznecov', props: { prependIcon: 'company', subtitle: 'Ремонт техники' } }
+];
+
+const filtered = computed(() =>
+  suppliers.filter((supplier) => supplier.title.toLowerCase().includes(query.value.trim().toLowerCase()))
+);
+</script>
+
+<template>
+  <div class="m-auto flex w-[300px] flex-col gap-2">
+    <CdsTextInput
+      v-model="query"
+      placeholder="Поиск по поставщикам"
+      prepend-inner-icon="search"
+      clearable
+      hide-details
+    />
+
+    <CdsList v-if="filtered.length" :items="filtered" lines="two" />
+
+    <CdsEmptyState v-else title="Ничего не найдено" description="Проверьте написание или очистите запрос" />
+  </div>
+</template>
+```

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

@@ -0,0 +1,10 @@
+# CdsList — 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 |
+| --- | --- |
+| A short title names the record — the eye compares items along a single trait. | A paragraph of text in a row turns the list into an article: scanning no longer finds anything. |
+| A long enumeration is split by subheaders — it is clear where to look for the record you need. | A solid list with no grouping has to be read in full. |
+| One action per row, the rest in a menu: the item as a whole stays clickable. | A row of buttons in every line overloads the list and makes the item itself hard to hit. |