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

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

@@ -0,0 +1,327 @@
+# CdsTextArea — 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 area is a field for multiline text: a comment, a description, a support request. Around the native `textarea` the component gathers everything a form needs: a label, a description, hints, error messages, clearing and a character counter, and with `auto-grow` it grows together with the text.
+
+## 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 { CdsTextArea } from '@central-design-system/components';
+</script>
+
+<template>
+  <CdsTextArea
+    label="Заголовок"
+    description="Описание для элемента формы или вспомогательный текст"
+    placeholder="Введите текст"
+    class="max-w-sm m-auto"
+  />
+</template>
+```
+
+## Number of rows
+
+The `rows` prop sets the height of the area in rows — 5 by default. Choose the height to match the expected length of the answer: two or three rows are enough for a comment.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsTextArea } from '@central-design-system/components';
+</script>
+
+<template>
+  <div class="max-w-sm m-auto">
+    <CdsTextArea label="rows: 2" :rows="2" placeholder="Введите текст" />
+    <CdsTextArea label="rows: 5 (по умолчанию)" placeholder="Введите текст" />
+    <CdsTextArea label="rows: 8" :rows="8" placeholder="Введите текст" />
+  </div>
+</template>
+```
+
+## Automatic height
+
+The `auto-grow` prop increases the height of the area as you type — the text does not have to be scrolled. `max-rows` limits the growth by a number of rows, `max-height` — by a height in pixels; beyond that a scrollbar appears.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsTextArea } from '@central-design-system/components';
+import { ref } from 'vue';
+
+const value = ref('Съешь ещё этих мягких французских булок,\nда выпей чаю.');
+</script>
+
+<template>
+  <div class="max-w-sm m-auto">
+    <CdsTextArea v-model="value" label="autoGrow" auto-grow :rows="2" placeholder="Начните вводить текст" />
+    <CdsTextArea
+      v-model="value"
+      label="autoGrow + maxRows: 4"
+      auto-grow
+      :rows="2"
+      :max-rows="4"
+      placeholder="Начните вводить текст"
+    />
+  </div>
+</template>
+```
+
+## Resizing
+
+By default the user can stretch the area by its bottom right corner. The `no-resize` prop turns that off; with `auto-grow` manual resizing is disabled automatically.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsTextArea } from '@central-design-system/components';
+</script>
+
+<template>
+  <div class="max-w-sm m-auto">
+    <CdsTextArea label="Обычная область (resize доступен)" :rows="3" placeholder="Введите текст" />
+    <CdsTextArea label="noResize" no-resize :rows="3" placeholder="Введите текст" />
+  </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 { CdsTextArea } from '@central-design-system/components';
+import { ref } from 'vue';
+
+const value = ref('Очисти меня!');
+</script>
+
+<template>
+  <CdsTextArea
+    v-model="value"
+    placeholder="Введите значение"
+    hint="Это поле можно очистить"
+    clearable
+    persistent-clearable
+    :rows="3"
+    class="max-w-sm m-auto"
+  />
+</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. To make the limit impossible to exceed, add the `maxlength` attribute.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsTextArea } 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">
+    <CdsTextArea label="counter true" placeholder="Просто счётчик" counter :rows="3" />
+    <CdsTextArea label="counter с лимитом" placeholder="До 200 символов" counter="200" maxlength="200" :rows="3" />
+    <CdsTextArea label="persistentCounter" placeholder="Счётчик всегда виден" counter persistent-counter :rows="3" />
+    <CdsTextArea
+      label="counterValue (слова)"
+      placeholder="Считаем слова"
+      counter
+      :counter-value="wordCount"
+      :rows="3"
+    />
+  </div>
+</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 { CdsTextArea } from '@central-design-system/components';
+</script>
+
+<template>
+  <div class="max-w-sm m-auto">
+    <CdsTextArea label="Disabled" model-value="Значение" :rows="2" disabled />
+    <CdsTextArea label="Readonly" model-value="Только для чтения" :rows="2" readonly />
+    <CdsTextArea label="Loading" model-value="Загрузка" :rows="2" loading />
+    <CdsTextArea label="Loading circle" model-value="Загрузка" :rows="2" loading="circle" />
+  </div>
+</template>
+```
+
+## Sending a request
+
+The form is made of `CdsForm`, a short subject in a text field and the message in a text area. The `rules` prop checks that the message is detailed enough, and `counter` together with `maxlength` show the limit upfront. The button gets `loading` for the duration of the request.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import {
+  CdsButton,
+  CdsForm,
+  CdsTextArea,
+  CdsTextInput,
+  type SubmitEventPromise
+} from '@central-design-system/components';
+import { ref } from 'vue';
+
+const subject = ref('');
+const message = ref('');
+const loading = ref(false);
+const sent = ref(false);
+
+const rules = {
+  subject: [(value: string) => !!value || 'Введите тему обращения'],
+  message: [
+    (value: string) => !!value || 'Опишите вопрос',
+    (value: string) => value.trim().length >= 20 || 'Расскажите подробнее — не меньше 20 символов'
+  ]
+};
+
+async function onSubmit(event: SubmitEventPromise) {
+  sent.value = false;
+
+  const { valid } = await event;
+
+  if (!valid) return;
+
+  loading.value = true;
+
+  setTimeout(() => {
+    loading.value = false;
+    sent.value = true;
+  }, 1500);
+}
+</script>
+
+<template>
+  <CdsForm class="flex flex-col gap-2 w-[350px] m-auto" @submit.prevent="onSubmit">
+    <CdsTextInput v-model="subject" :rules="rules.subject" label="Тема" placeholder="Кратко о сути вопроса" />
+    <CdsTextArea
+      v-model="message"
+      :rules="rules.message"
+      label="Сообщение"
+      placeholder="Что случилось и как это воспроизвести"
+      :rows="4"
+      counter="500"
+      maxlength="500"
+    />
+    <div class="mt-2">
+      <CdsButton :loading="loading" type="submit">Отправить</CdsButton>
+    </div>
+    <div v-if="sent" class="text-sm text-content-secondary">Сообщение отправлено — ответим в течение дня.</div>
+  </CdsForm>
+</template>
+```
+
+## A comment in a discussion
+
+A compact comment field: `rows="1"` and `auto-grow` with `max-rows` — the area starts with a single row and grows together with the text, `hide-details` removes the bottom block. The send button is a `CdsFunctionalButton` in the `append-inner` slot; Enter sends the comment, Shift+Enter inserts a line break.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsFunctionalButton, CdsTextArea } from '@central-design-system/components';
+import { ref } from 'vue';
+
+const draft = ref('');
+const comments = ref(['Отличная идея, поддерживаю.']);
+
+const send = () => {
+  const text = draft.value.trim();
+
+  if (!text) return;
+
+  comments.value.push(text);
+  draft.value = '';
+};
+</script>
+
+<template>
+  <div class="flex w-full max-w-md flex-col gap-3 m-auto">
+    <ul class="m-0 flex list-none flex-col gap-1 p-0">
+      <li v-for="(comment, index) in comments" :key="index">{{ comment }}</li>
+    </ul>
+
+    <CdsTextArea
+      v-model="draft"
+      placeholder="Написать комментарий"
+      auto-grow
+      :rows="1"
+      :max-rows="6"
+      hide-details
+      @keydown.enter.exact.prevent="send"
+    >
+      <template #append-inner>
+        <CdsFunctionalButton icon="arrow-up" aria-label="Отправить комментарий" @click="send" />
+      </template>
+    </CdsTextArea>
+  </div>
+</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 a text that is already fixed.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsButton, CdsTextArea } from '@central-design-system/components';
+import { ref } from 'vue';
+
+const description = ref('Надёжная компания, подробности на example.com');
+const loading = ref(false);
+const serverErrors = ref<string[]>([]);
+
+const publish = 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="publish">
+    <CdsTextArea
+      v-model="description"
+      label="Описание компании"
+      :rows="3"
+      :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-area/guidelines.md

@@ -0,0 +1,10 @@
+# CdsTextArea — 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 height of the area hints at the expected length: two or three rows are enough for a comment. | An area too tall for a short answer looks like a demand to write an essay. |
+| A counter with a limit shows the restriction upfront, and maxlength keeps it from being exceeded. | An error after the input forces the user to cut down text that is already written. |
+| For a short single-line value use a text field. | A text area for the subject of a request takes up space and hints at a long answer. |

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

@@ -0,0 +1,16 @@
+# CdsTextArea — 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.
+
+## _CdsTextArea.variables.scss
+
+```scss
+@use '../../../styles/settings';
+
+$text-area-affix-color: rgb(var(--cds-color-content-tertiary)) !default;
+$text-area-padding-start: var(--cds-spacing-100) !default;
+$text-area-padding-end: 0 !default;
+$text-area-padding-block: var(--cds-spacing-100) !default;
+```

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

@@ -0,0 +1,115 @@
+# CdsTextInput — 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)
+
+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.
+
+## CdsTextInput
+
+**Props**
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `active` | `boolean \| undefined` | — | no | Active state of the field |
+| `activeColor` | `string \| undefined` | — | no | Color of the component in its active state |
+| `appendIcon` | `IconValue \| undefined` | — | no | Icon in the append slot, after the content |
+| `appendInnerIcon` | `IconValue \| undefined` | — | no | Icon in the inner append slot, after the content of the field |
+| `autocomplete` | `string \| undefined` | — | no | Helps to influence browser suggestions. The `suppress` value changes the name attribute of the fields, and `off` relies on the browser to stop suggesting values on its own. Any other value is passed to the built-in autocomplete of the corresponding element. |
+| `autofocus` | `boolean \| undefined` | — | no | Enables autofocus |
+| `baseColor` | `string \| undefined` | — | no | Color of the component in its inactive state |
+| `bgColor` | `string \| undefined` | — | no | Background color of the component |
+| `centerAffix` | `boolean \| undefined` | — | no | Vertically center the appendInner, prependInner, clearIcon and label elements. |
+| `clearable` | `boolean \| undefined` | — | no | Shows the clear button |
+| `clearIcon` | `IconValue \| undefined` | `'remove'` | no | Icon of the clear button |
+| `color` | `string \| undefined` | — | no | Component color |
+| `counter` | `string \| number \| boolean \| undefined` | — | no | Character counter. Accepts a boolean, a number or a string |
+| `counterValue` | `number \| ((value: any) => number) \| undefined` | — | no | Custom counter value. Either a number or a function computing it from the current value |
+| `description` | `string \| undefined` | — | no | Description of the component, shown under the label |
+| `dirty` | `boolean \| undefined` | — | no | Marks that the value of the field was changed by the user |
+| `disabled` | `boolean \| null \| undefined` | `null` | no | Disabled state |
+| `error` | `boolean \| undefined` | — | no | Error state |
+| `errorMessages` | `string \| readonly string[] \| null \| undefined` | `[]` | no | Puts the component into the error state and passes custom error messages. They are merged with any checks defined in the `rules` prop. This field does not trigger validation. |
+| `focused` | `boolean \| undefined` | — | no | Controls the focus state of the component. When `true`, the component is considered focused and may apply the corresponding styles or behavior. |
+| `hideDetails` | `boolean \| "auto" \| undefined` | — | no | Hides the details block (messages and hints). With the 'auto' value the block is hidden when there are no messages |
+| `hideMessages` | `boolean \| undefined` | — | no | Hide the messages under the input |
+| `hint` | `string \| undefined` | — | no | Hint text shown under the input |
+| `iconColor` | `string \| boolean \| undefined` | — | no | Icon color. Accepts a boolean or a color string |
+| `id` | `string \| undefined` | — | no | Unique identifier of the component |
+| `label` | `string \| undefined` | — | no | Label text of the component |
+| `loading` | `string \| boolean \| undefined` | — | no | Loading indicator for the component |
+| `maxErrors` | `string \| number \| undefined` | `1` | no | Maximum number of validation errors shown |
+| `maxWidth` | `string \| number \| undefined` | — | no | Maximum component width |
+| `messages` | `string \| readonly string[] \| undefined` | `[]` | no | Messages shown under the input |
+| `minWidth` | `string \| number \| undefined` | — | no | Minimum component width |
+| `modelModifiers` | `Record<string, boolean> \| undefined` | — | no | v-model modifiers passed by Vue to process the field value |
+| `modelValue` | `any` | — | no | Value of the component in v-model. If the component supports the multiple prop, an empty array is used by default. |
+| `name` | `string \| undefined` | — | no | Name of the input |
+| `persistentClearable` | `boolean \| undefined` | — | no | Always show the clear button, not only on hover or focus |
+| `persistentCounter` | `boolean \| undefined` | — | no | Always show the counter, not only while the field is in use |
+| `persistentHint` | `boolean \| undefined` | — | no | Always show the hint, not only on focus |
+| `persistentPlaceholder` | `boolean \| undefined` | — | no | Always show the placeholder instead of hiding it while the field is in use |
+| `placeholder` | `string \| undefined` | — | no | Placeholder text shown in an empty field |
+| `prefix` | `string \| undefined` | — | no | Text prefix shown before the field value |
+| `prependIcon` | `IconValue \| undefined` | — | no | Icon in the prepend slot, before the content |
+| `prependInnerIcon` | `IconValue \| undefined` | — | no | Icon in the inner prepend slot, before the content of the field |
+| `readonly` | `boolean \| null \| undefined` | `null` | no | Read-only state |
+| `reverse` | `boolean \| undefined` | — | no | Reverses the order of the elements inside the field |
+| `role` | `string \| undefined` | — | no | ARIA role for the native input element |
+| `rules` | `readonly ValidationRule[] \| undefined` | `[]` | no | Accepts an array of items of different types: functions, booleans and strings. Functions take the input value as an argument and must return either true / false, or a string with an error message. The input goes into the error state if a function returns false (or any value in the array is false) or is a string. |
+| `size` | `number \| "xs" \| "sm" \| "md" \| "lg" \| "xl" \| undefined` | `'md'` | no | Size of the component |
+| `suffix` | `string \| undefined` | — | no | Text suffix shown after the field value |
+| `textColor` | `string \| undefined` | — | no | Text color of the component |
+| `theme` | `string \| undefined` | — | no | Component theme |
+| `type` | `string \| undefined` | `'text'` | no | Type of the native input |
+| `validateOn` | `ValidateOn \| undefined` | — | no | Changes the type of the event that triggers validation |
+| `validationValue` | `any` | — | no | Value used when applying the validation rules |
+| `width` | `string \| number \| undefined` | — | no | Component width |
+
+**Events**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `click:append` | `[e: MouseEvent]` | Click on the outer append icon (`append-icon` prop) |
+| `click:appendInner` | `[e: MouseEvent]` | Click on the inner append icon (`append-inner-icon` prop) |
+| `click:clear` | `[e: MouseEvent]` | Click on the clear icon (`clearable`); fires after the value has been reset |
+| `click:control` | `[e: MouseEvent]` | Fires on a click in the main area of the control |
+| `click:prepend` | `[e: MouseEvent]` | Click on the outer prepend icon (`prepend-icon` prop) |
+| `click:prependInner` | `[e: MouseEvent]` | Click on the inner prepend icon (`prepend-inner-icon` prop) |
+| `mousedown:control` | `[e: MouseEvent]` | Fires on a mouse button press in the main area of the control |
+| `update:focused` | `[focused: boolean]` | Fires when the element gains or loses focus |
+| `update:modelValue` | `[value: string]` | Fires when the model of the component changes |
+
+**Slots**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `append` | `CdsInputSlot` | Adds an element after the input |
+| `append-inner` | `CdsInputDefaultSlot` | Slot added at the end of the input |
+| `clear` | `CdsInputDefaultSlot & { props: Record<string, any>; }` | Slot for a custom clear icon (shown when the clearable prop is true). |
+| `counter` | `CdsCounterSlot` | Slot for a custom counter |
+| `default` | `{ id: Readonly<Ref<string, string>>; }` | Default slot |
+| `description` | `{ description: string \| undefined; props: Record<string, any>; }` | Default slot of the CdsDescription component |
+| `details` | `CdsInputSlot` | Slot for custom content that lets you customize how the messages are displayed |
+| `label` | `{ label: string \| undefined; props: Record<string, any>; }` | Default slot of the CdsLabel component |
+| `loader` | `LoaderSlotProps` | Slot for a custom loader (shown when the loading prop is true). |
+| `message` | `CdsMessagesSlots` | Slot for customizing the content of a message |
+| `messages` | `CdsInputSlot` | Slot for custom content that lets you customize how the messages are displayed |
+| `prepend` | `CdsInputSlot` | Adds an element before the input |
+| `prepend-inner` | `CdsInputDefaultSlot` | Slot added at the start of the input |
+
+**Exposed**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `controlRef` | `HTMLElement \| undefined` | Ref to the control of the input |
+| `fieldIconColor` | `string \| undefined` | Icon color |
+| `isDirty` | `boolean` | Whether the input is dirty |
+| `isDisabled` | `boolean` | Whether the input is disabled |
+| `isPure` | `boolean` | Whether the input is pure |
+| `isReadonly` | `boolean` | Whether the input is read-only |
+| `isValid` | `boolean \| null` | Whether the input is valid |
+| `isValidating` | `boolean` | Whether the input is being validated |
+| `reset` | `() => Promise<void>` | Resets the input to its initial state |
+| `resetValidation` | `() => Promise<void>` | Resets the validation of the input |
+| `validate` | `(silent?: boolean) => Promise<string[]>` | Validates the input |