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

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

@@ -0,0 +1,546 @@
+# CdsTextInput — 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 text field is the basic way to get data from the user: a name, an email, an amount, a search query. Around the native `input` the component gathers everything a form needs: a label, a description, hints, error messages, icons, clearing and a character counter.
+
+## Label and description
+
+The `label` prop names the field, `description` adds a supporting text under the label. The slots of the same name accept arbitrary markup.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsTextInput } from '@central-design-system/components';
+</script>
+
+<template>
+  <CdsTextInput
+    label="Заголовок"
+    description="Описание для элемента формы или вспомогательный текст"
+    placeholder="Введите текст"
+    class="max-w-sm m-auto"
+  />
+</template>
+```
+
+## Messages and hints
+
+There is a single text line under the field, and props split it by state: `messages` is visible at rest, `hint` — on focus, `error-messages` — on an error and on top of the rest. The `messages` and `details` slots override the content.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsTextInput } from '@central-design-system/components';
+</script>
+
+<template>
+  <CdsTextInput
+    label="Заголовок"
+    placeholder="Введите текст"
+    hint="Сообщение подсказка"
+    messages="Пользовательское сообщение"
+    class="max-w-sm m-auto"
+  />
+</template>
+```
+
+## Hiding the details
+
+The `hide-details` prop removes the bottom block entirely — fields can then sit right next to each other. The `auto` value hides the block only while there is nothing to show: as soon as an error or a hint appears, the block is rendered and pushes the content below.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsButton, CdsForm, CdsTextInput } from '@central-design-system/components';
+</script>
+
+<template>
+  <CdsForm class="flex flex-col gap-2 w-[350px] m-auto">
+    <template #default="{ reset }">
+      <CdsTextInput
+        label="Логин"
+        placeholder="Очистите поле!"
+        hide-details="auto"
+        :rules="[(value: string) => !!value || 'Логин не может быть пустым']"
+        clearable
+      />
+      <CdsTextInput
+        label="Пароль"
+        placeholder="Введите пароль"
+        type="password"
+        hide-details="auto"
+        :rules="[(value: string) => !!value || 'Пароль не может быть пустым']"
+      />
+
+      <div class="flex gap-2 mt-2 justify-end">
+        <CdsButton text="Сбросить" appearance="tertiary" @click="reset" />
+        <CdsButton type="submit" text="Отправить" />
+      </div>
+    </template>
+  </CdsForm>
+</template>
+```
+
+## Icons
+
+The `prepend-icon` and `append-icon` props put an icon outside the field, `prepend-inner-icon` and `append-inner-icon` — inside it.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsTextInput } from '@central-design-system/components';
+</script>
+
+<template>
+  <div class="max-w-sm m-auto">
+    <CdsTextInput prepend-icon="user-avatar" placeholder="prepend-icon" />
+    <CdsTextInput append-icon="add" placeholder="append-icon" />
+    <CdsTextInput prepend-inner-icon="user-avatar" placeholder="prepend-inner-icon" />
+    <CdsTextInput append-inner-icon="add" placeholder="append-inner-icon" />
+    <CdsTextInput prepend-icon="user-avatar" append-icon="add" placeholder="prepend-icon & append-icon" />
+    <CdsTextInput
+      prepend-inner-icon="user-avatar"
+      append-inner-icon="add"
+      placeholder="prepend-inner-icon & append-inner-icon"
+    />
+  </div>
+</template>
+```
+
+## Prefix and suffix
+
+The `prefix` and `suffix` props add an immutable text at the edges of the entered value — a currency, a country code, a domain.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsTextInput } from '@central-design-system/components';
+</script>
+
+<template>
+  <div class="max-w-sm m-auto">
+    <CdsTextInput type="number" label="Число" prefix="$" value="100" />
+    <CdsTextInput type="email" label="Электронная почта" suffix="@email.com" value="example" />
+    <CdsTextInput type="tel" label="Телефон" prefix="+7" placeholder="(000) 000-00-00" />
+    <CdsTextInput type="time" label="Время" model-value="10:45:00" prefix="UTC" />
+  </div>
+</template>
+```
+
+## Clearing
+
+The `clearable` prop shows the clear icon on hover or focus, `persistent-clearable` keeps it visible at all times.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsTextInput } from '@central-design-system/components';
+import { ref } from 'vue';
+
+const value = ref('Очисти меня!');
+</script>
+
+<template>
+  <CdsTextInput
+    v-model="value"
+    placeholder="Введите значение"
+    hint="Это поле можно очистить"
+    clearable
+    persistent-clearable
+    class="max-w-sm m-auto"
+  />
+</template>
+```
+
+## States
+
+`disabled` blocks the input and lowers the contrast, `readonly` forbids changes but keeps focus and copying, `loading` shows a loading indicator — as a bar or as a circle (`loading="circle"`).
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsTextInput } from '@central-design-system/components';
+</script>
+
+<template>
+  <div class="max-w-sm m-auto">
+    <CdsTextInput label="Disabled" value="Значение" disabled />
+    <CdsTextInput label="Readonly" value="Только для чтения" readonly />
+    <CdsTextInput label="Loading" value="Загрузка" loading />
+    <CdsTextInput label="Loading circle" value="Загрузка" loading="circle" />
+  </div>
+</template>
+```
+
+## Validation
+
+The `rules` prop accepts an array of validator functions: each one returns either `true` or a string with an error message. `validate-on` sets the moment they run — `blur`, `input` or `submit` (only on a `validate()` call).
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsTextInput } from '@central-design-system/components';
+import { ref } from 'vue';
+
+const title = ref('Удалите значение');
+</script>
+
+<template>
+  <CdsTextInput
+    v-model="title"
+    :rules="[
+      (value: string) => !!value || 'Не может быть пустым',
+      (value: string) => value.length <= 10 || 'Допустимое значение 10 символов'
+    ]"
+    label="Заголовок"
+    placeholder="Введите текст"
+    required
+    class="max-w-sm m-auto"
+  />
+</template>
+```
+
+## Validation
+
+Validators are plain functions: declare them once and reuse them across the fields of a form. Here the title is checked for being required and for its length (together with `maxlength` and the counter), and the email — for its format.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsForm, CdsTextInput } from '@central-design-system/components';
+import { ref } from 'vue';
+
+const title = ref('Предварительный отчёт');
+const email = ref('');
+
+const rules = {
+  required: (value: string) => !!value || 'Обязательное поле',
+  counter: (value: string) => value.length <= 20 || 'Не больше 20 символов',
+  email: (value: string) => /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value) || 'Некорректная почта'
+};
+</script>
+
+<template>
+  <CdsForm class="flex flex-col gap-2 w-[350px] m-auto">
+    <CdsTextInput
+      v-model="title"
+      label="Заголовок"
+      :rules="[rules.required, rules.counter]"
+      persistent-counter
+      maxlength="20"
+      counter="20"
+    />
+
+    <CdsTextInput
+      v-model="email"
+      label="Электронная почта"
+      placeholder="name@company.ru"
+      :rules="[rules.required, rules.email]"
+    />
+  </CdsForm>
+</template>
+```
+
+## Errors from outside
+
+The `error-messages` prop shows ready messages — the ones coming from the server, for example — independently of `rules`. `error` turns on the visual error state without any text, `max-errors` limits the number of messages.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsTextInput } from '@central-design-system/components';
+</script>
+
+<template>
+  <div class="flex flex-col max-w-sm m-auto gap-2">
+    <CdsTextInput
+      label="Состояние ошибки"
+      placeholder="errorMessages (string)"
+      error-messages="Поле заполнено некорректно"
+    />
+    <CdsTextInput
+      label="Состояние ошибки"
+      placeholder="errorMessages (array)"
+      :error-messages="['Ошибка 1', 'Ошибка 2']"
+      :max-errors="2"
+    />
+    <CdsTextInput label="Состояние ошибки" placeholder="Без сообщения, но error: true" error />
+  </div>
+</template>
+```
+
+## Counter
+
+The `counter` prop shows a character counter: `true` — without a limit, a number — with a limit. `counter-value` accepts your own counting formula, `persistent-counter` keeps the counter visible outside of focus.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsTextInput } from '@central-design-system/components';
+
+const wordCount = (value: unknown) => (value ?? '').toString().trim().split(/\s+/).filter(Boolean).length;
+</script>
+
+<template>
+  <div class="max-w-sm m-auto">
+    <CdsTextInput label="counter true" placeholder="Просто счётчик" counter />
+    <CdsTextInput label="counter с лимитом" placeholder="До 20 символов" counter="20" maxlength="20" />
+    <CdsTextInput label="persistentCounter" placeholder="Счётчик всегда виден" counter persistent-counter />
+    <CdsTextInput label="counterValue (слова)" placeholder="Считаем слова" counter :counter-value="wordCount" />
+  </div>
+</template>
+```
+
+## Colors
+
+The `color` prop sets the main color, `active-color` — the color on focus, `icon-color` — the color of the icons, `bg-color` — the background of the field.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsTextInput } from '@central-design-system/components';
+</script>
+
+<template>
+  <div class="max-w-sm m-auto">
+    <CdsTextInput label="color" value="Цвет компонента" color="green" />
+    <CdsTextInput label="activeColor" placeholder="Цвет при фокусе" active-color="purple" />
+    <CdsTextInput
+      label="iconColor"
+      placeholder="Цвет иконки"
+      prepend-inner-icon="user-avatar"
+      icon-color="brand-primary"
+    />
+    <CdsTextInput label="bgColor" placeholder="Цвет фона" bg-color="status-success-fill" />
+  </div>
+</template>
+```
+
+## Slots
+
+When props are not enough, the content of any block is replaced by a slot. `prepend` / `append` put elements outside the field, `prepend-inner` / `append-inner` — inside it; unlike the `*-icon` props, slots accept any components — buttons, links, badges.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import {
+  CdsButton,
+  CdsFunctionalButton,
+  CdsIcon,
+  CdsProgressBar,
+  CdsTextInput
+} from '@central-design-system/components';
+import { ref } from 'vue';
+
+const showed = ref(false);
+</script>
+
+<template>
+  <CdsTextInput loading placeholder="Введите текст" class="max-w-sm m-auto">
+    <template #label>
+      <span class="inline-flex items-center gap-1">
+        <CdsIcon name="user-avatar" />
+        <strong>Кастомный заголовок</strong>
+      </span>
+    </template>
+    <template #description>
+      <em>Описание через <span class="text-purple-500 font-bold">слот</span></em>
+    </template>
+    <template #messages>
+      <span class="text-green-500">✓ Кастомное сообщение</span>
+    </template>
+
+    <template #prepend="props">
+      <CdsButton appearance="tertiary" icon="add" :size="props.size.value" />
+    </template>
+    <template #append="props">
+      <CdsButton appearance="primary" text="OK" :size="props.size.value" />
+    </template>
+
+    <template #prepend-inner="props">
+      <CdsIcon name="user-avatar" :size="props.size.value" />
+    </template>
+    <template #append-inner>
+      <CdsFunctionalButton :icon="showed ? 'visibility-off' : 'visibility-on'" @click="showed = !showed" />
+    </template>
+
+    <template #loader>
+      <CdsProgressBar color="purple" height="4" indeterminate />
+    </template>
+  </CdsTextInput>
+</template>
+```
+
+## Searching through a list
+
+A search field is made of the `prepend-inner-icon="search"` icon and `clearable` — the user resets the query in one click and sees the full list again. A label is not needed here: the role of the field is obvious from the icon and the placeholder.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsTextInput } from '@central-design-system/components';
+import { computed, ref } from 'vue';
+
+const query = ref('');
+
+const items = ['Договор поставки', 'Договор аренды', 'Акт сверки', 'Счёт на оплату'];
+
+const filtered = computed(() => items.filter((item) => item.toLowerCase().includes(query.value.trim().toLowerCase())));
+</script>
+
+<template>
+  <div class="flex w-full max-w-md flex-col gap-3 m-auto">
+    <CdsTextInput v-model="query" placeholder="Поиск по документам" prepend-inner-icon="search" clearable />
+
+    <ul class="m-0 flex list-none flex-col gap-1 p-0">
+      <li v-for="item in filtered" :key="item">{{ item }}</li>
+      <li v-if="filtered.length === 0">Ничего не найдено</li>
+    </ul>
+  </div>
+</template>
+```
+
+## Password with a preview
+
+The `append-inner` slot accepts interactive elements — a button that toggles `type` between `password` and `text`, for example. The hint in `hint` states the password requirements before the user makes a mistake.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsFunctionalButton, CdsTextInput } from '@central-design-system/components';
+import { ref } from 'vue';
+
+const password = ref('qwerty123');
+const visible = ref(false);
+</script>
+
+<template>
+  <CdsTextInput
+    v-model="password"
+    class="w-full max-w-md m-auto"
+    label="Пароль"
+    :type="visible ? 'text' : 'password'"
+    hint="Минимум 8 символов"
+  >
+    <template #append-inner>
+      <CdsFunctionalButton
+        :icon="visible ? 'visibility-off' : 'visibility-on'"
+        :aria-label="visible ? 'Скрыть пароль' : 'Показать пароль'"
+        @click="visible = !visible"
+      />
+    </template>
+  </CdsTextInput>
+</template>
+```
+
+## Events
+
+Every icon zone emits its own click event: `click:prepend`, `click:append`, `click:prepend-inner`, `click:append-inner` and `click:clear` (the last one fires after the value has already been reset). Here the icon on the left cycles through the options, the lock inside the field toggles, and the submit button clears the message. When you need a complex element instead of an icon — a button, a badge — use the slots of the same name, like in the password example above.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsTextInput } from '@central-design-system/components';
+import { computed, ref } from 'vue';
+
+const message = ref('Привет!');
+const locked = ref(false);
+const iconIndex = ref(0);
+
+const icons = ['comment', 'star', 'flag', 'bookmark'];
+const icon = computed(() => icons[iconIndex.value]);
+
+const changeIcon = () => {
+  iconIndex.value = (iconIndex.value + 1) % icons.length;
+};
+
+const toggleLock = () => {
+  locked.value = !locked.value;
+};
+
+const resetIcon = () => {
+  iconIndex.value = 0;
+};
+
+const sendMessage = () => {
+  resetIcon();
+  message.value = '';
+};
+</script>
+
+<template>
+  <CdsTextInput
+    v-model="message"
+    class="w-[350px] m-auto"
+    label="Сообщение"
+    :prepend-icon="icon"
+    :append-inner-icon="locked ? 'locked' : 'unlocked'"
+    append-icon="telegram"
+    clearable
+    @click:prepend="changeIcon"
+    @click:append-inner="toggleLock"
+    @click:append="sendMessage"
+    @click:clear="resetIcon"
+  />
+</template>
+```
+
+## An error from the server
+
+The server response goes into `error-messages` as is — validation through `rules` is not needed for that. Reset the error when the value changes, so that the field does not complain about an input that is already fixed.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsButton, CdsTextInput } from '@central-design-system/components';
+import { ref } from 'vue';
+
+const email = ref('taken@company.ru');
+const loading = ref(false);
+const serverErrors = ref<string[]>([]);
+
+const save = async () => {
+  loading.value = true;
+  serverErrors.value = [];
+
+  // Имитация ответа сервера
+  await new Promise((resolve) => setTimeout(resolve, 1000));
+
+  loading.value = false;
+  serverErrors.value = ['Эта почта уже занята — укажите другую'];
+};
+</script>
+
+<template>
+  <form class="flex w-full max-w-md flex-col gap-4 m-auto" @submit.prevent="save">
+    <CdsTextInput
+      v-model="email"
+      label="Электронная почта"
+      placeholder="name@company.ru"
+      :error-messages="serverErrors"
+      @update:model-value="serverErrors = []"
+    />
+
+    <CdsButton class="self-start" type="submit" text="Сохранить" :loading="loading" />
+  </form>
+</template>
+```

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

@@ -0,0 +1,10 @@
+# CdsTextInput — 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 label is always visible and names the field, the placeholder shows a sample value. | A placeholder used instead of a label disappears on input — the user forgets what they are filling in. |
+| The error message says exactly what to fix. | “Invalid value” does not help: it is unclear what is wrong and what to do. |
+| The placeholder is a short sample value in the right format. | Instructions in the placeholder duplicate the label and vanish on input. |

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

@@ -0,0 +1,17 @@
+# CdsTextInput — 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.
+
+## _CdsTextInput.variables.scss
+
+```scss
+@use 'sass:map';
+@use '../../../styles/tools';
+@use '../../../styles/settings';
+
+$text-input-affix-color: rgb(var(--cds-color-content-tertiary)) !default;
+$text-input-padding-start: var(--cds-spacing-100) !default;
+$text-input-padding-end: 0 !default;
+```

package/skills/cds-builder/references/components/cds-time-picker/api.md

@@ -0,0 +1,44 @@
+# CdsTimePicker — 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)
+
+Time selection: hours, minutes and — if you want — seconds. The value can be typed on the keyboard or stepped through with the arrows, and `v-model` receives a string in the given format (`HH:mm` by default), which is convenient to store and to send to the server.
+
+## CdsTimePicker
+
+**Props**
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `allowedHours` | `number[] \| undefined` | — | no | Configures which hours are available for selection. |
+| `allowedMinutes` | `number[] \| undefined` | — | no | Configures which minutes are available for selection. |
+| `allowedSeconds` | `number[] \| undefined` | — | no | Configures which seconds are available for selection. |
+| `allowedTime` | `((hr: number \| null, min: number \| null, sec: number \| null) => boolean) \| undefined` | — | no | Configures which time is available for selection. |
+| `defaultDate` | `string \| undefined` | — | no | Date used by default when the model is empty (in the YYYY/MM/DD format). |
+| `disabled` | `boolean \| null \| undefined` | `null` | no | Disabled state |
+| `format12h` | `boolean \| undefined` | — | no | Shows the time in the 12-hour AM/PM format. |
+| `locale` | `string \| TDateLocale \| undefined` | — | no | Locale for the dates. A locale name ('ru' \| 'en') or a `TDateLocale` object. The current locale from `useLocale` is taken by default, otherwise `ru`. |
+| `mask` | `string \| undefined` | `'HH:mm'` | no | Date/time format |
+| `modelValue` | `string \| TDatetimeValueRange \| (string \| TDatetimeValueRange)[] \| null \| undefined` | `null` | no | Value of the model |
+| `nowBtn` | `boolean \| undefined` | — | no | Shows the "Now" button. |
+| `readonly` | `boolean \| null \| undefined` | `null` | no | Read-only state |
+| `theme` | `string \| undefined` | — | no | Component theme |
+| `withSeconds` | `boolean \| undefined` | — | no | Adds seconds to the time selection. |
+
+**Events**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `update:modelValue` | `[value: string \| undefined, date: IRawDate]` | The value changed (v-model). Passes the formatted value and the date object. |
+
+**Exposed**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `setAm` | `() => void` | Switches the 12-hour format to the first half of the day (AM). |
+| `setHour` | `(hour: number) => void` | Sets the hours. |
+| `setMinute` | `(minute: number) => void` | Sets the minutes. |
+| `setNow` | `() => void` | Sets the current system time. |
+| `setPm` | `() => void` | Switches the 12-hour format to the second half of the day (PM). |
+| `setSecond` | `(second: number) => void` | Sets the seconds. |