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

package/skills/cds-builder/references/components/cds-file-input/examples.md

@@ -0,0 +1,368 @@
+# CdsFileInput — 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 file field: the user attaches documents by a click, by dragging or by pasting from the clipboard. Around the native `input type="file"` the component gathers everything a form needs: a label, a description, messages, a counter, clearing and a filter by file types.
+
+## Label and hints
+
+`label` names the field, the requirements for the files go into `description`, and `placeholder` hints that a file can be dragged into the field. A chosen file is shown by its name.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsFileInput } from '@central-design-system/components';
+import { ref } from 'vue';
+
+const model = ref<File | null>(null);
+</script>
+
+<template>
+  <div class="max-w-sm m-auto">
+    <CdsFileInput
+      v-model="model"
+      label="Документ"
+      description="Прикрепите один файл"
+      placeholder="Выберите или перетащите файл в поле"
+    />
+  </div>
+</template>
+```
+
+## Several files
+
+The `multiple` prop allows choosing several files at once — their names are listed separated by commas.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsFileInput } from '@central-design-system/components';
+import { ref } from 'vue';
+
+const model = ref<File[]>([]);
+</script>
+
+<template>
+  <div class="max-w-sm m-auto">
+    <CdsFileInput
+      v-model="model"
+      label="Вложения"
+      description="Можно выбрать несколько файлов"
+      placeholder="Выберите или перетащите файлы в поле"
+      multiple
+    />
+  </div>
+</template>
+```
+
+## Showing as tags
+
+The `chips` prop shows every file as a separate tag ([CdsTag](../cds-tag/api.md)) — a list of several files reads more easily.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsFileInput } from '@central-design-system/components';
+import { ref } from 'vue';
+
+const model = ref<File[]>([]);
+</script>
+
+<template>
+  <div class="max-w-sm m-auto">
+    <CdsFileInput
+      v-model="model"
+      label="Вложения"
+      description="Выбранные файлы показываются тегами"
+      placeholder="Выберите или перетащите файл в поле"
+      multiple
+      chips
+    />
+  </div>
+</template>
+```
+
+## Size and counter
+
+`show-size` adds the size to the file name, `counter` shows the number and the total size under the field. Long names are truncated in the middle — the threshold is set by `truncate-length` (22 characters by default).
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsFileInput } from '@central-design-system/components';
+import { ref } from 'vue';
+
+const model = ref<File[]>([]);
+</script>
+
+<template>
+  <div class="max-w-sm m-auto">
+    <CdsFileInput
+      v-model="model"
+      label="Вложения"
+      description="Отображается размер файлов и счётчик"
+      placeholder="Выберите или перетащите файл в поле"
+      multiple
+      show-size
+      counter
+    />
+  </div>
+</template>
+```
+
+## Filter by type
+
+`filter-by-type` accepts MIME types, wildcard types and extensions separated by commas (`image/*,.pdf`). The files that do not fit never get into the model — the `rejected` event reports them: show the user what exactly was rejected and why.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsFileInput } from '@central-design-system/components';
+import { ref } from 'vue';
+
+const files = ref<File[]>([]);
+const rejectedMessages = ref<string[]>([]);
+
+// `rejected` срабатывает до обновления модели — флаг защищает свежие
+// сообщения от сброса в обработчике update:model-value
+let justRejected = false;
+
+function onRejected(rejected: File[]) {
+  rejectedMessages.value = rejected.map((file) => `${file.name} — не подходит по формату`);
+  justRejected = true;
+}
+
+function onUpdate() {
+  if (justRejected) {
+    justRejected = false;
+
+    return;
+  }
+
+  rejectedMessages.value = [];
+}
+</script>
+
+<template>
+  <div class="max-w-sm m-auto">
+    <CdsFileInput
+      v-model="files"
+      label="Сканы документов"
+      description="Только изображения или PDF"
+      placeholder="Выберите или перетащите файлы"
+      filter-by-type="image/*,.pdf"
+      multiple
+      :error-messages="rejectedMessages"
+      @rejected="onRejected"
+      @update:model-value="onUpdate"
+    />
+  </div>
+</template>
+```
+
+## States
+
+`disabled` blocks the field, `readonly` lets you look at the selection but not change it, `loading` shows an indicator — while the files are going to the server, for example.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsFileInput } from '@central-design-system/components';
+import { onMounted, ref } from 'vue';
+
+const file = ref<File | null>(null);
+
+// Файлы создаются только в браузере — SSR-сборка сайта обходится без File
+onMounted(() => {
+  file.value = new File([new Uint8Array(240_000)], 'отчёт-за-квартал.pdf', { type: 'application/pdf' });
+});
+</script>
+
+<template>
+  <div class="max-w-sm m-auto">
+    <CdsFileInput label="Disabled" placeholder="Выберите файл" disabled />
+    <CdsFileInput :model-value="file" label="Readonly" readonly />
+    <CdsFileInput :model-value="file" label="Loading" loading />
+  </div>
+</template>
+```
+
+## Slots
+
+The `selection` slot receives the truncated file names (`fileNames`) and the total size (`totalBytes`, `totalBytesReadable`).
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsFileInput, CdsTag } from '@central-design-system/components';
+import { ref } from 'vue';
+
+const files = ref<File[]>([]);
+</script>
+
+<template>
+  <div class="max-w-sm m-auto">
+    <CdsFileInput
+      v-model="files"
+      label="Вложения"
+      placeholder="Выберите или перетащите файлы"
+      multiple
+      show-size
+      counter
+    >
+      <template #selection="{ fileNames }">
+        <CdsTag v-for="name in fileNames" :key="name" prepend-icon="doc" size="sm" :text="name" />
+      </template>
+    </CdsFileInput>
+  </div>
+</template>
+```
+
+## Submitting a form with attachments
+
+The field takes part in [CdsForm](../cds-form/api.md) validation on a par with the others: `rules` receive the chosen files — check that the attachments are there and do not exceed the size limit before sending them to the server. `chips` and `counter` help the user keep track of the list.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsButton, CdsFileInput, CdsForm, CdsTextInput } from '@central-design-system/components';
+import { ref } from 'vue';
+
+const valid = ref(false);
+const topic = ref('');
+const files = ref<File[]>([]);
+const loading = ref(false);
+const sent = ref(false);
+
+const topicRules = [(value: string) => !!value || 'Укажите тему обращения'];
+
+const fileRules = [
+  (value: File[]) => (value?.length ?? 0) > 0 || 'Приложите хотя бы один файл',
+  (value: File[]) =>
+    (value ?? []).every((file) => file.size <= 10 * 1024 * 1024) || 'Файл больше 10 МБ — сожмите его или разбейте архив'
+];
+
+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">
+    <CdsTextInput v-model="topic" label="Тема обращения" :rules="topicRules" />
+
+    <CdsFileInput
+      v-model="files"
+      label="Вложения"
+      description="До 10 МБ каждый файл"
+      placeholder="Выберите или перетащите файлы"
+      :rules="fileRules"
+      multiple
+      chips
+      counter
+    />
+
+    <CdsButton type="submit" :loading="loading" text="Отправить обращение" />
+
+    <p v-if="sent" class="text-sm text-center">Обращение отправлено</p>
+  </CdsForm>
+</template>
+```
+
+## An upload button without a field
+
+The `hide-input` prop hides the field, leaving only the clickable icon — handy for embedding the upload into a toolbar or a comment line. Show the chosen files next to it yourself: here they are tags with `closable`, and a click on the cross removes a file from the model.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsFileInput, CdsTag } from '@central-design-system/components';
+import { ref } from 'vue';
+
+const files = ref<File[]>([]);
+
+function removeFile(name: string) {
+  files.value = files.value.filter((file) => file.name !== name);
+}
+</script>
+
+<template>
+  <div class="flex flex-col items-center gap-2">
+    <div class="flex items-center gap-1">
+      <span>Прикрепите файлы к комментарию</span>
+      <CdsFileInput v-model="files" hide-input hide-details multiple aria-label="Прикрепить файлы" />
+    </div>
+
+    <div v-if="files.length" class="flex flex-wrap justify-center gap-1">
+      <CdsTag
+        v-for="file in files"
+        :key="file.name"
+        prepend-icon="doc"
+        :text="file.name"
+        closable
+        @click:close="removeFile(file.name)"
+      />
+    </div>
+  </div>
+</template>
+```
+
+## An image preview
+
+`filter-by-type="image/*"` lets images through only, and the preview is built from the model value through `URL.createObjectURL`. Do not forget to release the previous URL — otherwise the chosen files pile up in the memory of the tab.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsFileInput } from '@central-design-system/components';
+import { onBeforeUnmount, ref, watch } from 'vue';
+
+const file = ref<File | null>(null);
+const previewUrl = ref('');
+
+watch(file, (value) => {
+  if (previewUrl.value) URL.revokeObjectURL(previewUrl.value);
+
+  previewUrl.value = value ? URL.createObjectURL(value) : '';
+});
+
+onBeforeUnmount(() => {
+  if (previewUrl.value) URL.revokeObjectURL(previewUrl.value);
+});
+</script>
+
+<template>
+  <div class="flex flex-col items-center gap-2 max-w-sm m-auto">
+    <CdsFileInput
+      v-model="file"
+      class="w-full"
+      label="Логотип компании"
+      description="PNG, JPG или SVG"
+      placeholder="Выберите или перетащите изображение"
+      filter-by-type="image/*"
+    />
+
+    <img v-if="previewUrl" :src="previewUrl" alt="Превью логотипа" class="max-h-40 rounded" />
+  </div>
+</template>
+```

package/skills/cds-builder/references/components/cds-file-input/guidelines.md

@@ -0,0 +1,10 @@
+# CdsFileInput — 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 file requirements are visible before the choice: the description names the formats and the size limit. | The user learns about the restrictions only from an error after picking a file. |
+| Tags and a counter: every file reads separately and the number is visible at once. | Comma-separated names merge together already at three or four files. |
+| The error names the reason and suggests what to do. | “Upload error” explains neither what is wrong nor how to fix it. |

package/skills/cds-builder/references/components/cds-file-input/tokens.md

@@ -0,0 +1,15 @@
+# CdsFileInput — 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.
+
+## _CdsFileInput.variables.scss
+
+```scss
+@use '../../../styles/settings';
+
+$file-input-native-z-index: 0 !default;
+$file-input-native-dragging-z-index: 1 !default;
+$file-input-placeholder-color: rgb(var(--cds-color-content-tertiary)) !default;
+```