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

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

@@ -0,0 +1,447 @@
+# CdsAutocomplete — 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.
+
+An autocomplete is a field for picking from a long list: the user types a query, the list is filtered on the fly and the matches are highlighted. The field is built on [CdsTextInput](../cds-text-input/api.md), and the menu and the list are the same as in [CdsSelect](../cds-select/api.md), so the label, the messages, validation and the menu behave identically.
+
+## List items
+
+The list is set by the `items` prop — an array of strings or of objects with the same interface as in [CdsList](../cds-list/api.md). Start typing and the list is filtered by item titles, with the matching fragments highlighted.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsAutocomplete } from '@central-design-system/components';
+import { ref } from 'vue';
+
+const items = ['Австрия', 'Бельгия', 'Болгария', 'Венгрия', 'Германия', 'Греция', 'Дания', 'Ирландия'];
+
+const selected = ref(null);
+</script>
+
+<template>
+  <div class="w-[350px] m-auto">
+    <CdsAutocomplete
+      v-model="selected"
+      :items="items"
+      label="Страна"
+      placeholder="Начните вводить"
+      description="Вспомогательное описание для выбора из списка"
+    />
+  </div>
+</template>
+```
+
+## Search across several fields
+
+By default the filter compares the query with the item title. The `filter-keys` prop widens the search area: `title` — the title, `raw.*` — a path to a field of the source object. Your own comparison logic is set by the `custom-filter` function, and `no-filter` turns the built-in filtering off entirely — when the results are already filtered by the server, for example.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsAutocomplete } from '@central-design-system/components';
+import { ref } from 'vue';
+
+const people = [
+  { name: 'Анна Смирнова', role: 'Дизайнер' },
+  { name: 'Дмитрий Орлов', role: 'Разработчик' },
+  { name: 'Елена Васильева', role: 'Аналитик' },
+  { name: 'Игорь Крылов', role: 'Разработчик' },
+  { name: 'Мария Соколова', role: 'Тестировщик' },
+  { name: 'Павел Зайцев', role: 'Менеджер проекта' }
+];
+
+const selected = ref(null);
+</script>
+
+<template>
+  <div class="w-[350px] m-auto">
+    <CdsAutocomplete
+      v-model="selected"
+      :items="people"
+      item-title="name"
+      item-value="name"
+      :filter-keys="['title', 'raw.role']"
+      label="Сотрудник"
+      placeholder="Имя или роль"
+      description="Попробуйте ввести «разработчик»"
+    />
+  </div>
+</template>
+```
+
+## Auto-selecting the first item
+
+The `auto-select-first` prop highlights the first matching item — Enter or Tab select it without arrow keys or a click. The `exact` value highlights an item only when the query matches its title completely.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsAutocomplete } from '@central-design-system/components';
+import { ref } from 'vue';
+
+const items = ['Австрия', 'Бельгия', 'Болгария', 'Венгрия', 'Германия', 'Греция', 'Дания', 'Ирландия'];
+
+const first = ref(null);
+const exact = ref(null);
+</script>
+
+<template>
+  <div class="flex flex-col gap-2 w-[350px] m-auto">
+    <CdsAutocomplete
+      v-model="first"
+      auto-select-first
+      :items="items"
+      label="Автовыбор первого"
+      placeholder="Начните вводить"
+      description="Введите «гер» и нажмите Enter"
+    />
+
+    <CdsAutocomplete
+      v-model="exact"
+      auto-select-first="exact"
+      :items="items"
+      label="Только при полном совпадении"
+      placeholder="Начните вводить"
+      description="Подсветится только полностью введённая «Германия»"
+    />
+  </div>
+</template>
+```
+
+## Multiple selection and chips
+
+The `multiple` prop allows selecting several values, `chips` shows them as [CdsTag](../cds-tag/api.md) tags, and `closable-chips` adds a cross — the value is removed right in the field. `clear-on-select` clears the search query after every selection, `hide-selected` removes the already selected items from the list.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsAutocomplete } from '@central-design-system/components';
+import { ref } from 'vue';
+
+const items = ref([
+  'Австрия',
+  'Бельгия',
+  'Болгария',
+  'Венгрия',
+  'Германия',
+  'Греция',
+  'Дания',
+  'Ирландия',
+  'Испания',
+  'Италия',
+  'Кипр',
+  'Латвия',
+  'Литва',
+  'Люксембург',
+  'Мальта',
+  'Нидерланды',
+  'Польша',
+  'Португалия',
+  'Румыния',
+  'Словакия',
+  'Словения',
+  'Финляндия',
+  'Франция',
+  'Хорватия',
+  'Чехия',
+  'Швеция',
+  'Эстония'
+]);
+
+const selected = ref(['Германия', 'Франция']);
+</script>
+
+<template>
+  <CdsAutocomplete
+    v-model="selected"
+    class="w-[350px] m-auto"
+    multiple
+    chips
+    closable-chips
+    clear-on-select
+    :items="items"
+    label="Множественный выбор"
+    placeholder="Начните вводить"
+  />
+</template>
+```
+
+## Slots
+
+The `no-data` slot is seen more often in the autocomplete than in the select: a query is easy to mistype. Bind the query through `v-model:search` and offer a way out — adding the entered value to the reference book, for example.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsAutocomplete, CdsButton } from '@central-design-system/components';
+import { ref } from 'vue';
+
+const items = ref(['Отдел продаж', 'Отдел закупок', 'Бухгалтерия', 'Юридический отдел']);
+
+const selected = ref<string | null>(null);
+const search = ref('');
+
+function addItem() {
+  items.value = [...items.value, search.value];
+  selected.value = search.value;
+}
+</script>
+
+<template>
+  <div class="w-[350px] m-auto">
+    <CdsAutocomplete
+      v-model="selected"
+      v-model:search="search"
+      :items="items"
+      label="Отдел"
+      placeholder="Начните вводить название"
+    >
+      <template #no-data>
+        <div class="flex flex-col items-start gap-2 p-4">
+          <span class="text-sm">По запросу «{{ search }}» ничего не найдено.</span>
+          <CdsButton appearance="secondary" size="sm" :text="`Добавить «${search}»`" @click="addItem" />
+        </div>
+      </template>
+    </CdsAutocomplete>
+  </div>
+</template>
+```
+
+## Search on the server
+
+When the reference book is too large to load in full, search on the server: `v-model:search` gives out the query, the response goes into `items`, and `no-filter` turns off the repeated filtering on the client. `loading` shows that a request is in progress, and the `no-data` slot changes the caption of the empty menu by state: a hint before the input, "Searching…" during the request, "Nothing found" after an empty response — the menu never stays blank.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsAutocomplete, CdsListItem } from '@central-design-system/components';
+import { computed, ref, watch } from 'vue';
+
+const cities = [
+  'Барнаул',
+  'Владивосток',
+  'Волгоград',
+  'Воронеж',
+  'Екатеринбург',
+  'Казань',
+  'Краснодар',
+  'Красноярск',
+  'Москва',
+  'Нижний Новгород',
+  'Новосибирск',
+  'Омск',
+  'Пермь',
+  'Ростов-на-Дону',
+  'Самара',
+  'Санкт-Петербург',
+  'Саратов',
+  'Тюмень',
+  'Уфа',
+  'Челябинск'
+];
+
+const items = ref<string[]>([]);
+const selected = ref(null);
+const search = ref('');
+const loading = ref(false);
+
+const noDataText = computed(() => {
+  if (loading.value) return 'Ищем…';
+  return search.value ? 'Ничего не найдено' : 'Начните вводить название';
+});
+
+let timer: ReturnType<typeof setTimeout>;
+
+watch(search, (query) => {
+  clearTimeout(timer);
+
+  if (!query) {
+    items.value = [];
+    loading.value = false;
+    return;
+  }
+
+  loading.value = true;
+
+  // Имитация запроса к серверу: фильтрация выполняется на «бэкенде».
+  timer = setTimeout(() => {
+    items.value = cities.filter((city) => city.toLowerCase().includes(query.toLowerCase()));
+    loading.value = false;
+  }, 600);
+});
+</script>
+
+<template>
+  <div class="w-[350px] m-auto">
+    <CdsAutocomplete
+      v-model="selected"
+      v-model:search="search"
+      no-filter
+      :items="items"
+      :loading="loading"
+      label="Город"
+      placeholder="Начните вводить название"
+      hint="Результаты приходят с сервера"
+    >
+      <template #no-data>
+        <CdsListItem :title="noDataText" />
+      </template>
+    </CdsAutocomplete>
+  </div>
+</template>
+```
+
+## Picking recipients
+
+The combination of `multiple`, `chips`, `closable-chips` and `clear-on-select` collects the recipients as tags and is immediately ready for the next input. `filter-keys` searches both by name and by email, `hide-selected` removes the already added ones from the list, and the `item` slot shows the avatar and the address — that way it is easier not to confuse namesakes.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsAutocomplete, CdsAvatar, CdsListItem } from '@central-design-system/components';
+import { 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' },
+  { name: 'Мария Соколова', email: 'm.sokolova@example.com', image: 'https://i.pravatar.cc/80?img=26' },
+  { name: 'Павел Зайцев', email: 'p.zaycev@example.com', image: 'https://i.pravatar.cc/80?img=59' }
+];
+
+const selected = ref(['Анна Смирнова']);
+</script>
+
+<template>
+  <div class="w-[350px] m-auto">
+    <CdsAutocomplete
+      v-model="selected"
+      multiple
+      chips
+      closable-chips
+      clear-on-select
+      hide-selected
+      :items="people"
+      item-title="name"
+      item-value="name"
+      :filter-keys="['title', 'raw.email']"
+      label="Получатели"
+      placeholder="Имя или почта"
+    >
+      <template #item="{ item, props }">
+        <CdsListItem v-bind="props" :title="item.name">
+          <template #prepend>
+            <CdsAvatar :image="item.image" size="sm" class="mr-3" />
+          </template>
+          <template #description>{{ item.email }}</template>
+        </CdsListItem>
+      </template>
+    </CdsAutocomplete>
+  </div>
+</template>
+```
+
+## Submitting a form
+
+The autocomplete takes part in [CdsForm](../cds-form/api.md) validation on a par with text fields: `rules` will not let the form through without a chosen city. Remember that only the selected item stays as the value — text typed without a selection does not get into the model.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsAutocomplete, CdsButton, CdsForm, CdsTextInput } from '@central-design-system/components';
+import { ref } from 'vue';
+
+const cities = [
+  'Владивосток',
+  'Волгоград',
+  'Екатеринбург',
+  'Казань',
+  'Краснодар',
+  'Москва',
+  'Нижний Новгород',
+  'Новосибирск',
+  'Санкт-Петербург',
+  'Челябинск'
+];
+
+const valid = ref(false);
+const city = ref(null);
+const street = ref('');
+const loading = ref(false);
+const sent = ref(false);
+
+const rules = [(value: string) => !!value || 'Выберите город из списка'];
+
+async function submit() {
+  if (!valid.value) return;
+
+  try {
+    loading.value = true;
+    sent.value = false;
+    await new Promise((resolve) => setTimeout(resolve, 1500));
+    sent.value = true;
+  } finally {
+    loading.value = false;
+  }
+}
+</script>
+
+<template>
+  <CdsForm v-model="valid" class="flex flex-col gap-2 w-[350px] m-auto" @submit.prevent="submit">
+    <CdsAutocomplete
+      v-model="city"
+      :items="cities"
+      :rules="rules"
+      label="Город доставки"
+      placeholder="Начните вводить"
+    />
+
+    <CdsTextInput v-model="street" label="Улица и дом" placeholder="Тверская, 1" />
+
+    <CdsButton type="submit" :loading="loading" text="Оформить доставку" />
+
+    <p v-if="sent" class="text-sm text-center">Заявка отправлена</p>
+  </CdsForm>
+</template>
+```
+
+## A large reference book
+
+The menu renders items through virtual scrolling, so a list of tens of thousands of entries does not slow down either on opening or on filtering. `auto-select-first` speeds up the input: type the number — press Enter.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsAutocomplete } from '@central-design-system/components';
+import { ref } from 'vue';
+
+const items = Array.from({ length: 10000 }, (_, index) => `Артикул ${String(index + 1).padStart(5, '0')}`);
+
+const selected = ref(null);
+</script>
+
+<template>
+  <div class="w-[350px] m-auto">
+    <CdsAutocomplete
+      v-model="selected"
+      auto-select-first
+      :items="items"
+      label="Позиция каталога"
+      placeholder="Начните вводить номер"
+      :description="`В списке ${items.length.toLocaleString('ru-RU')} позиций`"
+    />
+  </div>
+</template>
+```

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

@@ -0,0 +1,10 @@
+# CdsAutocomplete — 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 |
+| --- | --- |
+| An autocomplete pays off on a long list — typing a couple of letters is faster than scrolling. | Two or three options do not need a search: take CdsSelect or radio buttons. |
+| If values outside the list are allowed, take CdsCombobox — what is typed is kept as is. | The autocomplete accepts list items only: text typed without a selection is lost. |
+| An empty result explains what happened and suggests the next step. | A hidden menu (hide-no-data) looks like a breakage: the user does not understand why the list disappeared. |

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

@@ -0,0 +1,19 @@
+# CdsAutocomplete — 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.
+
+## _CdsAutocomplete.variables.scss
+
+```scss
+@use '../../../styles/settings';
+
+$autocomplete-content-border-radius: var(--cds-border-radius-200) !default;
+$autocomplete-content-padding-inline: var(--cds-spacing-100) !default;
+$autocomplete-focused-input-min-width: 64px !default;
+$autocomplete-mask-background: rgb(var(--cds-color-content-placeholder)) !default;
+$autocomplete-selection-inline-gap: var(--cds-spacing-50) !default;
+$autocomplete-unselected-opacity: var(--cds-medium-emphasis-opacity) !default;
+$autocomplete-transition: .2s settings.$standard-easing !default;
+```

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

@@ -0,0 +1,35 @@
+# CdsAvatar — 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)
+
+An avatar shows a person, a team or a company: a photo, initials or an icon inside a round container. Use it in member lists, comments and profile headers — anywhere the reader needs to recognize "who is this" at a glance.
+
+## CdsAvatar
+
+**Props**
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `activeColor` | `string \| undefined` | — | no | Color of the component in its active state |
+| `badge` | `boolean \| CdsBadgeProps \| undefined` | `false` | no | Avatar badge. `true` shows a dot, an object is passed through as `CdsBadge` props. |
+| `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 |
+| `content` | `string \| number \| undefined` | — | no | Content displayed in the component. |
+| `end` | `boolean \| undefined` | — | no | Adds a margin on the left — for an avatar at the end of a line of content. |
+| `icon` | `IconValue \| undefined` | — | no | Icon shown in the avatar when no image is set. |
+| `image` | `string \| undefined` | — | no | Source of the avatar image. Takes priority over `icon` and `text`. |
+| `size` | `number \| "xs" \| "sm" \| "md" \| "lg" \| "xl" \| undefined` | `'md'` | no | Size of the component |
+| `start` | `boolean \| undefined` | — | no | Adds a margin on the right — for an avatar at the beginning of a line of content. |
+| `tag` | `string \| JSXComponent<any> \| undefined` | `'div'` | no | Custom HTML tag or component to render |
+| `text` | `string \| number \| undefined` | — | no | Text displayed in the component. |
+| `textColor` | `string \| undefined` | — | no | Text color of the component |
+| `theme` | `string \| undefined` | — | no | Component theme |
+
+**Slots**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `badge` | `any` | Content of the avatar badge. |
+| `default` | `any` | Avatar content. Overrides `image`, `icon` and `text`. |