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

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

@@ -0,0 +1,794 @@
+# CdsSelect — 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 select opens a dropdown list and lets you pick one or several values from a known set: a country, a status, a category. The field is built on [CdsTextInput](../cds-text-input/api.md), so the label, the description, the messages, validation and the states work exactly as in a text field.
+
+## 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). While no value is selected, the field shows the `placeholder`.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsSelect } from '@central-design-system/components';
+import { ref } from 'vue';
+
+const items = ['Первый', 'Второй', 'Третий', 'Четвёртый'];
+
+const selected = ref(null);
+</script>
+
+<template>
+  <div class="w-[350px] m-auto">
+    <CdsSelect
+      v-model="selected"
+      :items="items"
+      label="Выберите значение"
+      placeholder="Выбрать значение"
+      description="Вспомогательное описание для выбора из списка"
+    />
+  </div>
+</template>
+```
+
+## Your own data fields
+
+When the objects come from the server as they are, use `item-title` and `item-value` to say which fields the title and the value are taken from. `return-object` puts the whole object into `v-model` instead of just the value.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsSelect } from '@central-design-system/components';
+import { ref } from 'vue';
+
+const select = ref({ lang: 'Русский', code: 'ru' });
+const languages = ref([
+  { lang: 'English', code: 'en' },
+  { lang: 'Русский', code: 'ru' },
+  { lang: 'Deutsch', code: 'de' },
+  { lang: 'Français', code: 'fr' },
+  { lang: 'Italiano', code: 'it' },
+  { lang: 'Español', code: 'es' },
+  { lang: 'Português', code: 'pt' },
+  { lang: 'Nederlands', code: 'nl' },
+  { lang: 'Polski', code: 'pl' },
+  { lang: 'Svenska', code: 'sv' },
+  { lang: 'Dansk', code: 'da' },
+  { lang: 'Türkçe', code: 'tr' },
+  { lang: '日本語', code: 'ja' },
+  { lang: '中文', code: 'zh' },
+  { lang: '한국어', code: 'ko' },
+  { lang: 'العربية', code: 'ar' },
+  { lang: 'עברית', code: 'he' }
+]);
+</script>
+
+<template>
+  <div class="w-[350px] m-auto">
+    <CdsSelect
+      v-model="select"
+      :items="languages"
+      item-title="lang"
+      item-value="code"
+      return-object
+      label="Выберите язык"
+      placeholder="Выбрать язык"
+      :messages="select.lang + ' (' + select.code + ')'"
+    />
+  </div>
+</template>
+```
+
+## Grouping
+
+Split a long list into meaningful blocks: an item with `type: 'subheader'` adds a subheader, one with `type: 'divider'` — a divider. Such items cannot be selected.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsSelect } from '@central-design-system/components';
+import { ref } from 'vue';
+
+const items = [
+  { type: 'subheader', title: 'Европа' },
+  'Австрия',
+  'Германия',
+  'Франция',
+  { type: 'divider' },
+  { type: 'subheader', title: 'Азия' },
+  'Китай',
+  'Южная Корея',
+  'Япония'
+];
+
+const selected = ref(null);
+</script>
+
+<template>
+  <div class="w-[350px] m-auto">
+    <CdsSelect v-model="selected" :items="items" label="Страна производства" placeholder="Выберите страну" />
+  </div>
+</template>
+```
+
+## Multiple selection
+
+The `multiple` prop allows selecting several values: the items get checkboxes and the field lists the selection separated by commas. `ellipsis` keeps the listing on a single line and cuts the rest off with an ellipsis.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsSelect } from '@central-design-system/components';
+import { ref } from 'vue';
+
+const items = ref([
+  'Австрия',
+  'Бельгия',
+  'Болгария',
+  'Венгрия',
+  'Германия',
+  'Греция',
+  'Дания',
+  'Ирландия',
+  'Испания',
+  'Италия',
+  'Кипр',
+  'Латвия',
+  'Литва',
+  'Люксембург',
+  'Мальта',
+  'Нидерланды',
+  'Польша',
+  'Португалия',
+  'Румыния',
+  'Словакия',
+  'Словения',
+  'Финляндия',
+  'Франция',
+  'Хорватия',
+  'Чехия',
+  'Швеция',
+  'Эстония'
+]);
+
+const selected = ref([]);
+</script>
+
+<template>
+  <div class="flex flex-col gap-2 w-[350px] m-auto">
+    <CdsSelect v-model="selected" multiple :items="items" label="Множественный выбор" placeholder="Выбрать страну" />
+
+    <CdsSelect
+      v-model="selected"
+      multiple
+      ellipsis
+      :items="items"
+      label="Множественный выбор в строку"
+      placeholder="Выбрать страну"
+    />
+  </div>
+</template>
+```
+
+## Selecting all the values
+
+The `is-select-all` prop adds a "select all" entry as the first item of the list (works together with `multiple`). The `true` value uses the default caption, a string sets your own.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsSelect } from '@central-design-system/components';
+import { ref } from 'vue';
+
+const items = ref([
+  'Австрия',
+  'Бельгия',
+  'Болгария',
+  'Венгрия',
+  'Германия',
+  'Греция',
+  'Дания',
+  'Ирландия',
+  'Испания',
+  'Италия',
+  'Кипр',
+  'Латвия',
+  'Литва',
+  'Люксембург',
+  'Мальта',
+  'Нидерланды',
+  'Польша',
+  'Португалия',
+  'Румыния',
+  'Словакия',
+  'Словения',
+  'Финляндия',
+  'Франция',
+  'Хорватия',
+  'Чехия',
+  'Швеция',
+  'Эстония'
+]);
+
+const selected = ref([]);
+const selectedCustom = ref([]);
+</script>
+
+<template>
+  <div class="flex flex-col gap-2 w-[350px] m-auto">
+    <CdsSelect
+      v-model="selected"
+      multiple
+      is-select-all
+      :items="items"
+      label="Множественный выбор с «Выбрать все»"
+      placeholder="Выбрать страну"
+    />
+
+    <CdsSelect
+      v-model="selectedCustom"
+      multiple
+      is-select-all="Отметить все страны"
+      :items="items"
+      label="Своя надпись «Выбрать все»"
+      placeholder="Выбрать страну"
+    />
+  </div>
+</template>
+```
+
+## Chips
+
+The `chips` prop shows the selected values as [CdsTag](../cds-tag/api.md) tags, `closable-chips` adds a cross to them — a value is removed right in the field, without opening the menu.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsSelect } from '@central-design-system/components';
+import { ref } from 'vue';
+
+const items = ['Австрия', 'Бельгия', 'Германия', 'Греция', 'Испания', 'Италия', 'Франция'];
+
+const selected = ref(['Германия', 'Испания']);
+const selectedClosable = ref(['Австрия', 'Италия', 'Франция']);
+</script>
+
+<template>
+  <div class="flex flex-col gap-2 w-[350px] m-auto">
+    <CdsSelect v-model="selected" multiple chips :items="items" label="Чипы" placeholder="Выбрать страну" />
+
+    <CdsSelect
+      v-model="selectedClosable"
+      multiple
+      chips
+      closable-chips
+      :items="items"
+      label="Удаляемые чипы"
+      placeholder="Выбрать страну"
+    />
+  </div>
+</template>
+```
+
+## Native list
+
+The `native-select` prop replaces the custom menu with a native `<select>`: on mobile devices the system list is more familiar. Filtering, virtual scrolling and the menu slots do not work in this mode.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsSelect } from '@central-design-system/components';
+import { ref } from 'vue';
+
+const items = ['Первый', 'Второй', 'Третий', 'Четвёртый'];
+
+const selected = ref(null);
+</script>
+
+<template>
+  <div class="w-[350px] m-auto">
+    <CdsSelect
+      v-model="selected"
+      native-select
+      :items="items"
+      label="Выберите значение"
+      placeholder="Выбрать значение"
+    />
+  </div>
+</template>
+```
+
+## Tuning the list
+
+The `list-props` prop passes any props through to the inner [CdsList](../cds-list/api.md) — in the example `bgColor` paints the background of the menu, and `slim` removes the inner paddings of the menu so that the list fills it entirely. `item-color` sets the color of the selected items (`color` is taken by default). In the same way `menu-props` configures the inner [CdsMenu](../cds-menu/api.md), and `menu-height` limits the height of the menu.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsSelect } from '@central-design-system/components';
+import { ref } from 'vue';
+
+const items = ['Яблоко', 'Апельсин', 'Банан', 'Груша'];
+
+const selected = ref(['Яблоко']);
+</script>
+
+<template>
+  <div class="w-[350px] m-auto">
+    <CdsSelect
+      v-model="selected"
+      multiple
+      :items="items"
+      :list-props="{ bgColor: 'other-cyan-fill', slim: true }"
+      item-color="status-warning-fill"
+      label="Выберите фрукты"
+      placeholder="Выбрать фрукт"
+    />
+  </div>
+</template>
+```
+
+## Slots
+
+The `item` slot overrides the rendering of an item completely. Be sure to pass `props` into `CdsListItem` — the selection handler lives in them. In the example every country shows its flag and capital.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsListItem, CdsSelect } from '@central-design-system/components';
+import { ref } from 'vue';
+
+const countries = ref([
+  { title: 'Австрия', flag: '🇦🇹', capital: 'Вена' },
+  { title: 'Бельгия', flag: '🇧🇪', capital: 'Брюссель' },
+  { title: 'Германия', flag: '🇩🇪', capital: 'Берлин' },
+  { title: 'Греция', flag: '🇬🇷', capital: 'Афины' },
+  { title: 'Испания', flag: '🇪🇸', capital: 'Мадрид' },
+  { title: 'Италия', flag: '🇮🇹', capital: 'Рим' },
+  { title: 'Нидерланды', flag: '🇳🇱', capital: 'Амстердам' },
+  { title: 'Польша', flag: '🇵🇱', capital: 'Варшава' },
+  { title: 'Португалия', flag: '🇵🇹', capital: 'Лиссабон' },
+  { title: 'Финляндия', flag: '🇫🇮', capital: 'Хельсинки' },
+  { title: 'Франция', flag: '🇫🇷', capital: 'Париж' },
+  { title: 'Швеция', flag: '🇸🇪', capital: 'Стокгольм' }
+]);
+</script>
+
+<template>
+  <CdsSelect class="w-[350px] m-auto" :items="countries" label="Страны" placeholder="Выбрать страну">
+    <template #item="{ item, props }">
+      <CdsListItem v-bind="props" :title="item.title">
+        <template #prepend>
+          <span class="mr-3 text-2xl">{{ item.flag }}</span>
+        </template>
+        <template #description>
+          Столица: <strong>{{ item.capital }}</strong>
+        </template>
+      </CdsListItem>
+    </template>
+  </CdsSelect>
+</template>
+```
+
+## Slots
+
+The `selection` slot is your own display of what is selected in the field: the first two countries are shown as tags, the rest are folded into a counter.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsSelect, CdsTag } from '@central-design-system/components';
+import { ref } from 'vue';
+
+const items = ref([
+  'Австрия',
+  'Бельгия',
+  'Германия',
+  'Греция',
+  'Испания',
+  'Италия',
+  'Нидерланды',
+  'Польша',
+  'Португалия',
+  'Франция',
+  'Швеция'
+]);
+const selected = ref(['Португалия', 'Испания', 'Франция']);
+</script>
+
+<template>
+  <CdsSelect
+    v-model="selected"
+    class="w-[350px] m-auto"
+    multiple
+    :items="items"
+    label="Выберите страны"
+    placeholder="Выбрать страну"
+  >
+    <template #selection="{ item, index }">
+      <CdsTag v-if="index < 2" :text="item" size="sm" />
+
+      <span v-if="index === 2" class="self-center text-sm text-gray-500"> (+{{ selected.length - 2 }} ещё) </span>
+    </template>
+  </CdsSelect>
+</template>
+```
+
+## Slots
+
+The `prepend-item` and `append-item` slots add your own entries to the start and the end of the list. In the example the start holds "Select all countries" with a checkbox, and the end — "Load more" with a simulated fetch through `loading`.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsCheckbox, CdsListItem, CdsListItemDivider, CdsSelect } from '@central-design-system/components';
+import { computed, ref } from 'vue';
+
+const allCountries = [
+  'Австрия',
+  'Бельгия',
+  'Болгария',
+  'Венгрия',
+  'Германия',
+  'Греция',
+  'Дания',
+  'Ирландия',
+  'Испания',
+  'Италия',
+  'Кипр',
+  'Латвия',
+  'Литва',
+  'Люксембург',
+  'Мальта',
+  'Нидерланды',
+  'Польша',
+  'Португалия',
+  'Румыния',
+  'Словакия',
+  'Словения',
+  'Финляндия',
+  'Франция',
+  'Хорватия',
+  'Чехия',
+  'Швеция',
+  'Эстония'
+];
+
+const loading = ref(false);
+const countries = ref(allCountries.slice(0, 3));
+const selected = ref<string[]>([]);
+
+const allSelected = computed(() => countries.value.length > 0 && selected.value.length === countries.value.length);
+const someSelected = computed(() => selected.value.length > 0);
+const hasMore = computed(() => countries.value.length < allCountries.length);
+
+function selectingAll() {
+  selected.value = allSelected.value ? [] : countries.value.slice();
+}
+
+async function addMore() {
+  if (!hasMore.value) return;
+
+  try {
+    loading.value = true;
+    await new Promise((resolve) => setTimeout(resolve, 1000));
+
+    countries.value = [...countries.value, allCountries[countries.value.length]];
+  } finally {
+    loading.value = false;
+  }
+}
+</script>
+
+<template>
+  <CdsSelect
+    v-model="selected"
+    class="w-[350px] m-auto"
+    multiple
+    :loading="loading"
+    :items="countries"
+    label="Страны"
+    placeholder="Выбрать страну"
+  >
+    <template #prepend-item>
+      <CdsListItem title="Выбрать все страны" link @click="selectingAll">
+        <template #prepend>
+          <CdsCheckbox
+            :model-value="allSelected"
+            :indeterminate="someSelected && !allSelected"
+            tabindex="-1"
+            hide-messages
+          />
+        </template>
+      </CdsListItem>
+
+      <CdsListItemDivider />
+    </template>
+
+    <template #append-item>
+      <CdsListItemDivider />
+
+      <CdsListItem v-if="hasMore" title="Добавить еще" prepend-icon="add" :disabled="loading" link @click="addMore" />
+    </template>
+  </CdsSelect>
+</template>
+```
+
+## Slots
+
+The `menu-header` and `menu-footer` slots add content to the header and the footer of the menu — a search field and a confirmation button, for example. Both slots receive `search` (written into `v-model:search`, it filters the list) and `filteredItems`.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsButton, CdsListItemDivider, CdsSelect, CdsTextInput } from '@central-design-system/components';
+import { ref } from 'vue';
+
+const items = ref([
+  { id: 1, value: 'Австрия' },
+  { id: 2, value: 'Бельгия' },
+  { id: 3, value: 'Германия' },
+  { id: 4, value: 'Греция' },
+  { id: 5, value: 'Испания' },
+  { id: 6, value: 'Италия' },
+  { id: 7, value: 'Нидерланды' },
+  { id: 8, value: 'Франция' },
+  { id: 9, value: 'Португалия' }
+]);
+const model = ref([]);
+const menu = ref(false);
+</script>
+
+<template>
+  <CdsSelect
+    v-model="model"
+    v-model:menu="menu"
+    class="w-[350px] m-auto"
+    :items="items"
+    item-title="value"
+    item-value="id"
+    multiple
+    menu-height="280"
+    label="Выберите страны"
+    placeholder="Выбрать страну"
+  >
+    <template #menu-header="{ search, filteredItems }">
+      <div class="p-2">
+        <CdsTextInput
+          v-model="search.value"
+          :error="!!search.value && !filteredItems.length"
+          placeholder="Поиск..."
+          prepend-inner-icon="search"
+          clearable
+          hide-messages
+        />
+      </div>
+
+      <CdsListItemDivider />
+    </template>
+
+    <template #menu-footer="{ search, filteredItems }">
+      <CdsListItemDivider />
+
+      <div class="flex items-center p-2 pl-4">
+        <span v-if="search.value" class="text-sm text-brand-secondary-content">
+          Найдено {{ filteredItems.length }} из {{ items.length }}
+        </span>
+
+        <CdsButton class="ml-auto" text="Принять" @click="menu = false" />
+      </div>
+    </template>
+  </CdsSelect>
+</template>
+```
+
+## Submitting a form
+
+The select 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 subject. Give optional fields a default value — that way the form is filled in faster.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsButton, CdsForm, CdsSelect } from '@central-design-system/components';
+import { ref } from 'vue';
+
+const topics = ['Вопрос по заказу', 'Проблема с оплатой', 'Возврат товара', 'Другое'];
+const priorities = ['Низкий', 'Средний', 'Высокий'];
+
+const valid = ref(false);
+const topic = ref(null);
+const priority = 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">
+    <CdsSelect v-model="topic" :items="topics" :rules="rules" label="Тема обращения" placeholder="Выберите тему" />
+
+    <CdsSelect v-model="priority" :items="priorities" label="Приоритет" />
+
+    <CdsButton type="submit" :loading="loading" text="Отправить" />
+
+    <p v-if="sent" class="text-sm text-center">Обращение отправлено</p>
+  </CdsForm>
+</template>
+```
+
+## Dependent lists
+
+The list of cities depends on the chosen country: while there is no country the second select is turned off through `disabled`, and while the options are loading it shows `loading`. When the country changes the chosen city is reset — otherwise a non-existent pair would stay in the form.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsSelect } from '@central-design-system/components';
+import { ref, watch } from 'vue';
+
+const citiesByCountry: Record<string, string[]> = {
+  Германия: ['Берлин', 'Гамбург', 'Мюнхен', 'Франкфурт'],
+  Испания: ['Барселона', 'Валенсия', 'Мадрид', 'Севилья'],
+  Франция: ['Лион', 'Марсель', 'Ницца', 'Париж']
+};
+const countries = Object.keys(citiesByCountry);
+
+const country = ref<string | null>(null);
+const city = ref<string | null>(null);
+const cities = ref<string[]>([]);
+const loading = ref(false);
+
+watch(country, async (value) => {
+  city.value = null;
+  cities.value = [];
+  if (!value) return;
+
+  try {
+    loading.value = true;
+    await new Promise((resolve) => setTimeout(resolve, 800));
+    cities.value = citiesByCountry[value];
+  } finally {
+    loading.value = false;
+  }
+});
+</script>
+
+<template>
+  <div class="flex flex-col gap-2 w-[350px] m-auto">
+    <CdsSelect v-model="country" :items="countries" label="Страна" placeholder="Выберите страну" />
+
+    <CdsSelect
+      v-model="city"
+      :items="cities"
+      :loading="loading"
+      :disabled="!country"
+      label="Город"
+      :placeholder="country ? 'Выберите город' : 'Сначала выберите страну'"
+    />
+  </div>
+</template>
+```
+
+## Picking assignees
+
+The combination of `multiple`, `chips` and `closable-chips` shows the chosen people as tags and removes them by the cross right in the field. The `item` slot adds an avatar and a role — that way it is easier to find the right person in a long list.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsAvatar, CdsListItem, CdsSelect } from '@central-design-system/components';
+import { ref } from 'vue';
+
+const people = [
+  { name: 'Анна Смирнова', role: 'Дизайнер', image: 'https://i.pravatar.cc/80?img=47' },
+  { name: 'Дмитрий Орлов', role: 'Разработчик', image: 'https://i.pravatar.cc/80?img=12' },
+  { name: 'Елена Васильева', role: 'Аналитик', image: 'https://i.pravatar.cc/80?img=44' },
+  { name: 'Игорь Крылов', role: 'Разработчик', image: 'https://i.pravatar.cc/80?img=32' },
+  { name: 'Мария Соколова', role: 'Тестировщик', image: 'https://i.pravatar.cc/80?img=26' },
+  { name: 'Павел Зайцев', role: 'Менеджер проекта', image: 'https://i.pravatar.cc/80?img=59' }
+];
+
+const selected = ref(['Анна Смирнова']);
+</script>
+
+<template>
+  <div class="w-[350px] m-auto">
+    <CdsSelect
+      v-model="selected"
+      multiple
+      chips
+      closable-chips
+      :items="people"
+      item-title="name"
+      item-value="name"
+      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.role }}</template>
+        </CdsListItem>
+      </template>
+    </CdsSelect>
+  </div>
+</template>
+```
+
+## Sorting the results
+
+A compact select controls the order of a list: `hide-messages` removes the bottom block, `aria-label` replaces the hidden label for screen readers. The choice is applied at once — an "Apply" button is not needed.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsList, CdsListItem, CdsSelect } from '@central-design-system/components';
+import { computed, ref } from 'vue';
+
+const sortOptions = ['По алфавиту', 'Сначала дешевле', 'Сначала дороже'];
+const sort = ref('По алфавиту');
+
+const products = [
+  { title: 'Кабель силовой', price: 1200 },
+  { title: 'Автомат защиты', price: 350 },
+  { title: 'Розетка накладная', price: 90 },
+  { title: 'Щит распределительный', price: 4800 },
+  { title: 'Светильник потолочный', price: 2100 }
+];
+
+const sorted = computed(() => {
+  const items = [...products];
+
+  if (sort.value === 'Сначала дешевле') return items.sort((a, b) => a.price - b.price);
+  if (sort.value === 'Сначала дороже') return items.sort((a, b) => b.price - a.price);
+
+  return items.sort((a, b) => a.title.localeCompare(b.title));
+});
+</script>
+
+<template>
+  <div class="flex flex-col gap-2 w-[350px] m-auto">
+    <CdsSelect v-model="sort" class="w-56 self-end" :items="sortOptions" aria-label="Сортировка" hide-messages />
+
+    <CdsList>
+      <CdsListItem v-for="product of sorted" :key="product.title" :title="product.title">
+        <template #append>{{ product.price }} ₽</template>
+      </CdsListItem>
+    </CdsList>
+  </div>
+</template>
+```