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

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

@@ -0,0 +1,553 @@
+# CdsUploader — 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.
+
+The uploader sends files to the server right from the interface: the user picks them in the system dialog or drags them onto the button, and the component shows the list of what was uploaded — with a status, progress, downloading and removal. Every step of the file lifecycle comes with an event.
+
+## The upload button
+
+By default the upload is started by the primary "Загрузить файл" button with the `upload-icon` icon. The `button-props` prop passes any [CdsButton](../cds-button/api.md) props to the button, and the `default` slot replaces it entirely — the ready props of the button arrive in the `props` slot argument.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import type { NUploader } from '@central-design-system/components';
+import { CdsButton, CdsUploader } from '@central-design-system/components';
+import { ref } from 'vue';
+
+const documents = ref<NUploader.IUploadFile[]>([]);
+const photos = ref<NUploader.IUploadFile[]>([]);
+</script>
+
+<template>
+  <div class="flex flex-col gap-2 w-[350px] m-auto">
+    <CdsUploader
+      v-model="documents"
+      label="Свойства кнопки"
+      action="https://user1694090019726.requestly.dev/upload"
+      :button-props="{ appearance: 'secondary', text: 'Прикрепить файлы' }"
+    />
+
+    <CdsUploader
+      v-model="photos"
+      label="Своя кнопка через слот"
+      action="https://user1694090019726.requestly.dev/upload"
+    >
+      <template #default="{ props }">
+        <CdsButton v-bind="props" appearance="tertiary" prepend-icon="add" text="Добавить фото" />
+      </template>
+    </CdsUploader>
+  </div>
+</template>
+```
+
+## Allowed file types
+
+The `accept` prop limits the choice in the system dialog and filters out the unsuitable files on a drop — the rejected ones arrive in the `reject` event.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import type { NUploader } from '@central-design-system/components';
+import { CdsUploader } from '@central-design-system/components';
+import { ref } from 'vue';
+
+const files = ref<NUploader.IUploadFile[]>([]);
+</script>
+
+<template>
+  <div class="w-[350px] m-auto">
+    <CdsUploader
+      v-model="files"
+      label="Загрузка файла"
+      description="Подойдут только изображения jpeg, jpg или png"
+      action="https://user1694090019726.requestly.dev/upload"
+      accept="image/png, image/jpeg"
+    />
+  </div>
+</template>
+```
+
+## The file list
+
+The list of the uploaded files lives in `v-model` — put the files received from the server into it and they will be shown right away. The `show-upload-list` prop controls the list: `false` hides it entirely, an object turns on the download and removal icons.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import type { NUploader } from '@central-design-system/components';
+import { CdsUploader } from '@central-design-system/components';
+import { ref } from 'vue';
+
+const files = ref<NUploader.IUploadFile[]>([
+  {
+    uid: '1',
+    name: 'dummy.pdf',
+    status: 'done',
+    url: 'https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf'
+  },
+  {
+    uid: '2',
+    name: 'B2b-elbcp-180x130.png',
+    status: 'done',
+    url: 'https://upload.wikimedia.org/wikipedia/commons/a/ae/B2b-elbcp-180x130.png'
+  }
+]);
+</script>
+
+<template>
+  <div class="w-[350px] m-auto">
+    <CdsUploader
+      v-model="files"
+      label="Документы"
+      description="Уже загруженные файлы приходят через v-model"
+      action="https://user1694090019726.requestly.dev/upload"
+      :show-upload-list="{ showDownloadIcon: true, showRemoveIcon: true }"
+    />
+  </div>
+</template>
+```
+
+## Number of files
+
+The `max-count` prop limits the length of the list: with `max-count="1"` a new file replaces the previous one, with a larger limit the extra files are dropped.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import type { NUploader } from '@central-design-system/components';
+import { CdsUploader } from '@central-design-system/components';
+import { ref } from 'vue';
+
+const avatar = ref<NUploader.IUploadFile[]>([]);
+const documents = ref<NUploader.IUploadFile[]>([]);
+</script>
+
+<template>
+  <div class="flex flex-col gap-2 w-[350px] m-auto">
+    <CdsUploader
+      v-model="avatar"
+      label="Фото профиля"
+      description="Новый файл заменяет предыдущий"
+      action="https://user1694090019726.requestly.dev/upload"
+      accept="image/png, image/jpeg"
+      :max-count="1"
+    />
+
+    <CdsUploader
+      v-model="documents"
+      label="Документы"
+      description="Не больше трёх файлов — лишние отбрасываются"
+      action="https://user1694090019726.requestly.dev/upload"
+      :max-count="3"
+    />
+  </div>
+</template>
+```
+
+## Uploading directories
+
+The `directory` prop turns on picking a whole folder — the files are collected from it recursively, on a drop as well.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import type { NUploader } from '@central-design-system/components';
+import { CdsButton, CdsUploader } from '@central-design-system/components';
+import { ref } from 'vue';
+
+const files = ref<NUploader.IUploadFile[]>([]);
+</script>
+
+<template>
+  <div class="w-[350px] m-auto">
+    <CdsUploader
+      v-model="files"
+      label="Загрузка директории"
+      description="Выберите папку — файлы соберутся из неё рекурсивно"
+      action="https://user1694090019726.requestly.dev/upload"
+      directory
+    >
+      <template #default="{ props }">
+        <CdsButton v-bind="props" text="Загрузить директорию" />
+      </template>
+    </CdsUploader>
+  </div>
+</template>
+```
+
+## States
+
+`disabled` blocks the button and removes the removal icons from the list, `readonly` forbids changing the list but keeps the downloading.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import type { NUploader } from '@central-design-system/components';
+import { CdsUploader } from '@central-design-system/components';
+
+const files: NUploader.IUploadFile[] = [
+  {
+    uid: '1',
+    name: 'dummy.pdf',
+    status: 'done',
+    url: 'https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf'
+  }
+];
+</script>
+
+<template>
+  <div class="flex flex-col gap-2 w-[350px] m-auto">
+    <CdsUploader label="Disabled" description="Загрузка недоступна" disabled />
+
+    <CdsUploader
+      label="Readonly"
+      description="Список нельзя изменить, скачивание работает"
+      :model-value="files"
+      :show-upload-list="{ showDownloadIcon: true }"
+      readonly
+    />
+  </div>
+</template>
+```
+
+## Slots
+
+When props are not enough, the content of any block is replaced by a slot.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import type { NUploader } from '@central-design-system/components';
+import {
+  CdsButton,
+  CdsFunctionalButton,
+  CdsIcon,
+  CdsListItem,
+  CdsTooltip,
+  CdsUploader
+} from '@central-design-system/components';
+import { ref } from 'vue';
+
+const files = ref<NUploader.IUploadFile[]>([
+  {
+    uid: '1',
+    name: 'dummy.pdf',
+    status: 'done',
+    url: 'https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf'
+  }
+]);
+
+const clearAll = () => {
+  files.value = [];
+};
+</script>
+
+<template>
+  <div class="w-[350px] m-auto">
+    <CdsUploader v-model="files" action="https://user1694090019726.requestly.dev/upload">
+      <template #label>
+        <span class="flex items-center gap-0.5">
+          Загрузка файла
+          <CdsTooltip text="Дополнительная информация">
+            <template #activator="{ props }">
+              <CdsIcon name="info" v-bind="props" />
+            </template>
+          </CdsTooltip>
+        </span>
+      </template>
+
+      <template #description> Подойдёт любой формат — <strong>jpg, png, doc, zip</strong> — до 10 МБ. </template>
+
+      <template #default="{ props }">
+        <CdsButton v-bind="props" text="Выбрать файл" />
+      </template>
+
+      <template #append>
+        <CdsFunctionalButton icon="delete" aria-label="Удалить все файлы" @click="clearAll">
+          <CdsTooltip activator="parent">Удалить все файлы</CdsTooltip>
+        </CdsFunctionalButton>
+      </template>
+
+      <template #messages>Файлы проверяются после загрузки</template>
+
+      <template #itemRender="{ file, actions }">
+        <CdsListItem :title="file?.name">
+          <template #append>
+            <CdsFunctionalButton icon="download" aria-label="Скачать файл" @click="actions.download" />
+            <CdsFunctionalButton icon="delete" aria-label="Удалить файл" @click="actions.remove" />
+          </template>
+        </CdsListItem>
+      </template>
+    </CdsUploader>
+  </div>
+</template>
+```
+
+## Deferred sending
+
+The `before-upload` hook returning `false` turns the automatic sending off: the files pile up in the list, and the upload is started by a separate button in the `append` slot — together with the submission of the whole form, for example.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import type { NUploader } from '@central-design-system/components';
+import { CdsButton, CdsToast, CdsUploader } from '@central-design-system/components';
+import { ref, unref } from 'vue';
+
+const files = ref<NUploader.IUploadFile[]>([]);
+const loading = ref(false);
+const uploaded = ref(false);
+
+const beforeUpload = (file: NUploader.IUploadFile): boolean => {
+  files.value = [...(unref(files) || []), file];
+  return false;
+};
+
+const handleUpload = async () => {
+  loading.value = true;
+  await new Promise((resolve) => setTimeout(resolve, 3000));
+  files.value = [];
+  loading.value = false;
+  uploaded.value = true;
+};
+</script>
+
+<template>
+  <div class="w-[350px] m-auto">
+    <CdsUploader
+      v-model="files"
+      label="Выберите файлы"
+      description="Файлы копятся в списке, загрузку запускает кнопка"
+      :before-upload="beforeUpload"
+      :show-upload-list="{ showRemoveIcon: true }"
+    >
+      <template #default="{ props }">
+        <CdsButton appearance="secondary" text="Выбрать файлы" :disabled="props.disabled" :readonly="props.readonly" />
+      </template>
+      <template #append>
+        <CdsButton prepend-icon="upload" :loading="loading" :disabled="!files.length" @click="handleUpload">
+          Загрузить файлы
+        </CdsButton>
+      </template>
+    </CdsUploader>
+    <CdsToast v-model="uploaded" title="Файлы успешно загружены" status="success" />
+  </div>
+</template>
+```
+
+## A check before the upload
+
+The same `before-upload` is the place for validation: return `false` and the file will not go to the server. A rejected file still gets into the list — remove it in the `change` handler and show the reason through `error-messages`.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import type { NUploader } from '@central-design-system/components';
+import { CdsUploader } from '@central-design-system/components';
+import { ref } from 'vue';
+
+const MAX_SIZE_MB = 5;
+
+const files = ref<NUploader.IUploadFile[]>([]);
+const errors = ref<string[]>([]);
+
+const beforeUpload = (file: NUploader.IUploadFile): boolean => {
+  const valid = (file.size ?? 0) <= MAX_SIZE_MB * 1024 * 1024;
+
+  if (!valid) {
+    errors.value = [`«${file.name}» больше ${MAX_SIZE_MB} МБ`];
+  }
+
+  return valid;
+};
+
+const handleChange = (info: NUploader.IUploadChangeParam<NUploader.IUploadFile> | Event) => {
+  if (info instanceof Event) return;
+
+  files.value = info.fileList.filter((file) => file.status);
+};
+</script>
+
+<template>
+  <div class="w-[350px] m-auto">
+    <CdsUploader
+      v-model="files"
+      label="Вложения"
+      :description="`Любые файлы до ${MAX_SIZE_MB} МБ`"
+      action="https://user1694090019726.requestly.dev/upload"
+      :error-messages="errors"
+      :before-upload="beforeUpload"
+      @change="handleChange"
+    />
+  </div>
+</template>
+```
+
+## Upload errors
+
+A file rejected by the server stays in the list with the error status. The `show-tooltip-with-error` prop shows the server response in a tooltip next to the status, and the `error` event lets you collect the messages under the field — here they pile up in `error-messages` and are reset when the file is removed.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import type { NUploader } from '@central-design-system/components';
+import { CdsUploader } from '@central-design-system/components';
+import { ref } from 'vue';
+
+const files = ref<NUploader.IUploadFile[]>([]);
+const errors = ref<string[]>([]);
+
+const handleError = (
+  _error: NUploader.IUploadRequestError | ProgressEvent,
+  response: { message?: string } | null,
+  file: NUploader.IUploadFile
+) => {
+  errors.value = [...errors.value, `${response?.message ?? 'Ошибка сервера'}: ${file.name}`];
+};
+
+const handleRemove = () => {
+  errors.value = [];
+};
+</script>
+
+<template>
+  <div class="w-[350px] m-auto">
+    <CdsUploader
+      v-model="files"
+      label="Загрузка с ошибкой"
+      description="Тестовый сервер отклоняет любой файл"
+      action="https://user1694090019726.requestly.dev/upload-error"
+      :error-messages="errors"
+      show-tooltip-with-error
+      @error="handleError"
+      @remove="handleRemove"
+    />
+  </div>
+</template>
+```
+
+## Uploading without a server
+
+The `custom-request` prop replaces the built-in XHR transport with your own function: it receives the file and the `onProgress`, `onSuccess`, `onError` callbacks and returns an object with an `abort` method. Here the upload is simulated with a timer — files can be sent through an SDK or a WebSocket in the same way.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import type { NUploader } from '@central-design-system/components';
+import { CdsUploader } from '@central-design-system/components';
+import { ref } from 'vue';
+
+const files = ref<NUploader.IUploadFile[]>([]);
+
+// Имитация загрузки: прогресс по таймеру вместо XHR-запроса
+const customRequest = ({ onProgress, onSuccess }: NUploader.IUploadRequestOption) => {
+  let percent = 0;
+
+  const timer = setInterval(() => {
+    percent += 20;
+    onProgress?.({ percent });
+
+    if (percent >= 100) {
+      clearInterval(timer);
+      onSuccess?.({});
+    }
+  }, 400);
+
+  return { abort: () => clearInterval(timer) };
+};
+</script>
+
+<template>
+  <div class="w-[350px] m-auto">
+    <CdsUploader
+      v-model="files"
+      label="Загрузка без сервера"
+      description="Файл никуда не отправляется — прогресс имитируется"
+      :custom-request="customRequest"
+      :show-upload-list="{ showRemoveIcon: true }"
+    />
+  </div>
+</template>
+```
+
+## Events
+
+The component reports every step: `change` — any change of the list, `progress`, `success` and `error` — the course of the upload, `remove`, `drop`, `reject`, `download`, `preview` — the actions of the user. Open the console to see them.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import type { NUploader } from '@central-design-system/components';
+import { CdsUploader } from '@central-design-system/components';
+import { ref } from 'vue';
+
+const files = ref<NUploader.IUploadFile[]>([]);
+
+const handleChange = (info: NUploader.IUploadChangeParam<NUploader.IUploadFile> | Event) => {
+  console.log('onChange', info);
+};
+const handleProgress = (event: NUploader.IUploadChangeParam['event'], file: NUploader.IUploadFile) => {
+  console.log('onProgress', event, file);
+};
+const handleSuccess = (response: Record<string, any>, file: NUploader.IUploadFile) => {
+  console.log('onSuccess', response, file);
+};
+const handleError = (
+  event: NUploader.IUploadRequestError | ProgressEvent,
+  response: any,
+  file: NUploader.IUploadFile
+) => {
+  console.log('onError', event, response, file);
+};
+const handleRemove = (file: NUploader.IUploadFile) => {
+  console.log('onRemove', file);
+};
+const handleDrop = (event: DragEvent) => {
+  console.log('onDrop', event);
+};
+const handleReject = (rejected: NUploader.IUploadFile[]) => {
+  console.log('onReject', rejected);
+};
+const handleDownload = (file: NUploader.IUploadFile) => {
+  console.log('onDownload', file);
+};
+const handlePreview = (file: NUploader.IUploadFile) => {
+  console.log('onPreview', file);
+};
+</script>
+
+<template>
+  <div class="w-[350px] m-auto">
+    <CdsUploader
+      v-model="files"
+      label="Загрузка файлов"
+      description="Откройте консоль, чтобы увидеть все циклы событий"
+      action="https://user1694090019726.requestly.dev/upload"
+      :show-upload-list="{ showDownloadIcon: true, showRemoveIcon: true }"
+      @change="handleChange"
+      @progress="handleProgress"
+      @success="handleSuccess"
+      @error="handleError"
+      @remove="handleRemove"
+      @drop="handleDrop"
+      @reject="handleReject"
+      @download="handleDownload"
+      @preview="handlePreview"
+    />
+  </div>
+</template>
+```

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

@@ -0,0 +1,10 @@
+# CdsUploader — 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 description names the allowed formats and size upfront — the user does not waste an attempt. | Without a description the restrictions are learned only from an error after the upload. |
+| The text of the button names exactly what to upload. | “Click here” says nothing about the action nor about the content. |
+| The list shows what has already been uploaded and lets the extra files be removed. | With the list hidden the user does not see the result and uploads the files again. |

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

@@ -0,0 +1,26 @@
+# CdsUploader — 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.
+
+## _CdsUploader.variables.scss
+
+```scss
+@use 'sass:map';
+@use '../../../styles/tools';
+
+$uploader-color: (
+  'hover': rgb(var(--cds-color-fill-primary-hover)),
+  'progress': rgb(var(--cds-color-status-progress-surface)),
+  'text': rgb(var(--cds-color-content-primary))
+) !default;
+$uploader-label-offset: var(--cds-spacing-200) !default;
+$uploader-description-offset: var(--cds-spacing-200) !default;
+$uploader-messages-offset: var(--cds-spacing-200) !default;
+$uploader-list-item-height: tools.to-rem(32px) !default;
+$uploader-list-item-padding-inline: var(--cds-spacing-200) !default;
+$uploader-list-item-padding-block: var(--cds-spacing-50) !default;
+$uploader-list-item-gap: var(--cds-spacing-200) !default;
+$uploader-item-progress-offset: $uploader-list-item-padding-block !default;
+```

package/skills/cds-builder/references/components/cds-virtual-scroll/api.md

@@ -0,0 +1,60 @@
+# CdsVirtualScroll — 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)
+
+Virtual scrolling keeps long lists fast: only the visible rows get into the DOM, not the whole array. Pass the records to `items`, the markup of a row to the slot, and a list of tens of thousands of positions scrolls as smoothly as a list of ten.
+
+Family: [CdsVirtualScroll](#cdsvirtualscroll) + subcomponents: [CdsVirtualScrollItem](#cdsvirtualscrollitem).
+
+## CdsVirtualScroll
+
+**Props**
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `height` | `string \| number \| undefined` | — | no | Component height |
+| `itemHeight` | `string \| number \| undefined` | `null` | no | Height of a single item in pixels. When omitted, the height is measured automatically. |
+| `itemKey` | `SelectItemKey` | `null` | no | Key that identifies an item (a field name, a path or a function). The index is used by default. |
+| `items` | `readonly unknown[] \| undefined` | `[]` | no | Array of the items rendered by the virtual scroll. |
+| `maxHeight` | `string \| number \| undefined` | — | no | Maximum component height |
+| `maxWidth` | `string \| number \| undefined` | — | no | Maximum component width |
+| `minHeight` | `string \| number \| undefined` | — | no | Minimum component height |
+| `minWidth` | `string \| number \| undefined` | — | no | Minimum component width |
+| `renderless` | `boolean \| undefined` | — | no | Renderless mode: the component does not create its own scroll container and uses the nearest scrollable parent instead. |
+| `width` | `string \| number \| undefined` | — | no | Component width |
+
+**Slots**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `default` | `CdsVirtualScrollSlot<any> & { itemRef?: TemplateRef \| undefined; }` | Content of a single list item. In `renderless` mode it additionally receives `itemRef`. |
+
+**Exposed**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `calculateVisibleItems` | `() => void` | Recalculates the window of visible items — needed after their height changes outside the update cycle. |
+| `scrollToIndex` | `(index: number) => void` | Scrolls the list to the item with the given index. |
+
+---
+
+## CdsVirtualScrollItem
+
+**Props**
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `renderless` | `boolean \| undefined` | — | no | Renderless mode: the item renders only the slot content, without a wrapper. |
+
+**Events**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `update:height` | `[height: number]` | Tells the virtual list that the height of the item has changed. |
+
+**Slots**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `default` | `{ itemRef: TemplateRef; }` | Content of the item. In `renderless` mode it receives `itemRef` to measure the height. |