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

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

@@ -0,0 +1,552 @@
+# CdsForm — 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 form joins fields into one group: it collects their validation into a common status, intercepts the submission and can reset the values. CDS fields with the `rules` prop connect to the form automatically — with no registration and no extra code.
+
+## Heading and description
+
+The `label` prop names the form, `description` adds an explanation under the heading. The slots of the same name accept arbitrary markup.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsForm, CdsTextInput } from '@central-design-system/components';
+</script>
+
+<template>
+  <CdsForm
+    label="Адрес доставки"
+    description="Привезём заказ по этому адресу"
+    class="flex flex-col gap-2 w-[350px] m-auto"
+  >
+    <CdsTextInput label="Город" placeholder="Москва" />
+    <CdsTextInput label="Улица и дом" placeholder="Тверская, 1" />
+  </CdsForm>
+</template>
+```
+
+## Validity status
+
+The `v-model` of the form is the common status of its fields: `null` while the form has not been checked, `false` on errors and `true` when all the fields are valid. The status is updated on the fly — it is handy for blocking the submit button, for example.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsButton, CdsForm, CdsTextInput } from '@central-design-system/components';
+import { ref } from 'vue';
+
+const valid = ref<boolean | null>(null);
+const login = ref('');
+const password = ref('');
+
+const rules = {
+  login: [(value: string) => !!value || 'Введите логин'],
+  password: [(value: string) => value.length >= 8 || 'Минимум 8 символов']
+};
+</script>
+
+<template>
+  <CdsForm v-model="valid" class="flex flex-col gap-2 w-[350px] m-auto" @submit.prevent>
+    <CdsTextInput v-model="login" :rules="rules.login" label="Логин" placeholder="Введите логин" />
+    <CdsTextInput
+      v-model="password"
+      :rules="rules.password"
+      type="password"
+      label="Пароль"
+      placeholder="Минимум 8 символов"
+    />
+    <div class="mt-2">
+      <CdsButton :disabled="!valid" type="submit" block>Войти</CdsButton>
+    </div>
+  </CdsForm>
+</template>
+```
+
+## The moment of validation
+
+The `validate-on` prop sets the moment the check runs for all the fields of the form; the field's own `validate-on` takes precedence. Switch the mode and try it out: with `input` (the default) the error appears as you type, with `blur` — after leaving the field, with `submit` — only when the form is submitted.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsButton, CdsButtonToggle, CdsForm, CdsTextInput } from '@central-design-system/components';
+import { ref, unref, watch } from 'vue';
+
+const mode = ref<'input' | 'blur' | 'submit'>('input');
+const formRef = ref<InstanceType<typeof CdsForm>>();
+
+const name = ref('');
+const email = ref('');
+
+const rules = {
+  name: [(value: string) => !!value || 'Обязательное поле'],
+  email: [(value: string) => /.+@.+\..+/.test(value) || 'Некорректная почта']
+};
+
+watch(mode, () => unref(formRef)?.resetValidation());
+</script>
+
+<template>
+  <div class="flex flex-col gap-2 w-[350px] m-auto">
+    <div class="flex items-center justify-between">
+      <span class="text-sm text-content-secondary">validate-on</span>
+      <CdsButtonToggle v-model="mode" mandatory appearance="tertiary" size="sm">
+        <CdsButton text="input" value="input" />
+        <CdsButton text="blur" value="blur" />
+        <CdsButton text="submit" value="submit" />
+      </CdsButtonToggle>
+    </div>
+
+    <CdsForm ref="formRef" :validate-on="mode" class="flex flex-col gap-2" @submit.prevent>
+      <CdsTextInput v-model="name" :rules="rules.name" label="Имя" placeholder="Введите имя" />
+      <CdsTextInput v-model="email" :rules="rules.email" label="Электронная почта" placeholder="name@company.ru" />
+      <div class="mt-2">
+        <CdsButton type="submit">Отправить</CdsButton>
+      </div>
+    </CdsForm>
+  </div>
+</template>
+```
+
+## Fast validation
+
+The `first-fail` prop stops the check at the first invalid field. Submit the form: the error is shown only for "Имя", although "Фамилия" is invalid too.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsButton, CdsForm, CdsTextInput } from '@central-design-system/components';
+import { ref } from 'vue';
+
+const firstName = ref('');
+const lastName = ref('1020');
+
+const rules = {
+  firstName: [(value: string) => value.length >= 3 || 'Имя не короче 3 символов'],
+  lastName: [(value: string) => !/\d/.test(value) || 'Фамилия не может содержать цифры']
+};
+</script>
+
+<template>
+  <CdsForm first-fail class="flex flex-col gap-2 w-[350px] m-auto" @submit.prevent>
+    <CdsTextInput v-model="firstName" :rules="rules.firstName" label="Имя" placeholder="Введите имя" />
+    <CdsTextInput v-model="lastName" :rules="rules.lastName" label="Фамилия" placeholder="Введите фамилию" />
+    <div class="mt-2">
+      <CdsButton type="submit">Отправить</CdsButton>
+    </div>
+  </CdsForm>
+</template>
+```
+
+## States
+
+`disabled` blocks all the fields of the form at once, `readonly` keeps the values visible and copyable but forbids changing them. There is no need to configure the individual fields — the state is inherited.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsForm, CdsTextInput } from '@central-design-system/components';
+</script>
+
+<template>
+  <div class="flex flex-col gap-4 w-[350px] m-auto">
+    <CdsForm disabled label="Недоступная форма" class="flex flex-col gap-2">
+      <CdsTextInput label="Имя" value="Анна Смирнова" />
+      <CdsTextInput label="Электронная почта" value="anna@company.ru" />
+    </CdsForm>
+    <CdsForm readonly label="Только для чтения" class="flex flex-col gap-2">
+      <CdsTextInput label="Имя" value="Анна Смирнова" />
+      <CdsTextInput label="Электронная почта" value="anna@company.ru" />
+    </CdsForm>
+  </div>
+</template>
+```
+
+## Hiding the details
+
+The bottom block with the messages is controlled by the `hide-details` prop on the fields themselves: `true` always hides the block — errors included, `false` always reserves space for it, `auto` shows the block only when there is something to show. In dense forms use `auto`: the fields sit right next to each other, but the validation errors are not lost. Switch the value and submit an empty form.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsButton, CdsButtonToggle, CdsForm, CdsTextInput } from '@central-design-system/components';
+import { computed, ref } from 'vue';
+
+const mode = ref('auto');
+const hideDetails = computed(() => (mode.value === 'auto' ? ('auto' as const) : mode.value === 'true'));
+
+const rules = {
+  login: [(value: string) => !!value || 'Логин не может быть пустым'],
+  password: [(value: string) => !!value || 'Пароль не может быть пустым']
+};
+</script>
+
+<template>
+  <div class="flex flex-col gap-2 w-[350px] m-auto">
+    <div class="flex items-center justify-between">
+      <span class="text-sm text-content-secondary">hide-details</span>
+      <CdsButtonToggle v-model="mode" mandatory appearance="tertiary" size="sm">
+        <CdsButton text="auto" value="auto" />
+        <CdsButton text="true" value="true" />
+        <CdsButton text="false" value="false" />
+      </CdsButtonToggle>
+    </div>
+
+    <CdsForm class="flex flex-col gap-2" @submit.prevent>
+      <template #default="{ reset }">
+        <CdsTextInput
+          :hide-details="hideDetails"
+          :rules="rules.login"
+          label="Логин"
+          placeholder="Введите логин"
+          clearable
+        />
+        <CdsTextInput
+          :hide-details="hideDetails"
+          :rules="rules.password"
+          type="password"
+          label="Пароль"
+          placeholder="Введите пароль"
+        />
+        <div class="flex gap-2 mt-2 justify-end">
+          <CdsButton appearance="tertiary" @click="reset">Сбросить</CdsButton>
+          <CdsButton type="submit">Отправить</CdsButton>
+        </div>
+      </template>
+    </CdsForm>
+  </div>
+</template>
+```
+
+## Slots
+
+The default slot receives the state of the form and the control methods — the "Check" and "Reset" buttons are built without a ref to the component.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsButton, CdsForm, CdsTextInput } from '@central-design-system/components';
+import { ref } from 'vue';
+
+const valid = ref<boolean | null>(null);
+const value = ref('');
+
+const rules = [(input: string) => !!input || 'Не может быть пустым'];
+</script>
+
+<template>
+  <CdsForm v-model="valid" class="flex flex-col gap-2 w-[350px] m-auto" @submit.prevent>
+    <template #default="{ isValid, validate, reset, resetValidation }">
+      <CdsTextInput v-model="value" :rules="rules" label="Поле" placeholder="Введите текст" />
+      <div class="text-sm text-content-secondary">
+        Статус формы: {{ isValid === null ? 'не проверена' : isValid ? 'валидна' : 'есть ошибки' }}
+      </div>
+      <div class="flex flex-wrap gap-2 mt-2">
+        <CdsButton @click="validate">Проверить</CdsButton>
+        <CdsButton appearance="secondary" @click="reset">Сброс</CdsButton>
+        <CdsButton appearance="tertiary" @click="resetValidation">Сброс валидации</CdsButton>
+      </div>
+    </template>
+  </CdsForm>
+</template>
+```
+
+## Submitting a form
+
+The `submit` event is a Promise: `await event` returns the validation result, and the handler decides on its own whether to send the data. The `.prevent` modifier turns off the native page submission. The request here is simulated with `setTimeout`, and the button shows `loading` for the duration of the "request".
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsButton, CdsForm, CdsTextInput, type SubmitEventPromise } from '@central-design-system/components';
+import { ref } from 'vue';
+
+const name = ref('');
+const email = ref('');
+const loading = ref(false);
+const sent = ref(false);
+
+const rules = {
+  name: [(value: string) => !!value || 'Введите имя'],
+  email: [(value: string) => /.+@.+\..+/.test(value) || 'Некорректная почта']
+};
+
+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="name" :rules="rules.name" label="Имя" placeholder="Введите имя" />
+    <CdsTextInput v-model="email" :rules="rules.email" label="Электронная почта" placeholder="name@company.ru" />
+    <div class="mt-2">
+      <CdsButton :loading="loading" type="submit">Отправить заявку</CdsButton>
+    </div>
+    <div v-if="sent" class="text-sm text-content-secondary">Заявка отправлена — мы напишем вам на почту.</div>
+  </CdsForm>
+</template>
+```
+
+## Control from outside
+
+The `validate`, `reset` and `resetValidation` methods are also available through a ref to the form. That is how the form is driven from outside — from the footer of a modal or a wizard panel, where the buttons live outside the form markup.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsButton, CdsCheckbox, CdsForm, CdsTextInput } from '@central-design-system/components';
+import { ref, unref } from 'vue';
+
+const formRef = ref<InstanceType<typeof CdsForm>>();
+
+const name = ref('');
+const agree = ref(false);
+const result = ref('');
+
+const rules = {
+  name: [(value: string) => !!value || 'Введите имя'],
+  agree: [(value: boolean) => !!value || 'Нужно согласие, чтобы продолжить']
+};
+
+async function validate() {
+  const form = unref(formRef);
+
+  if (!form) return;
+
+  const { valid } = await form.validate();
+
+  result.value = valid ? 'Форма валидна' : 'В форме есть ошибки';
+}
+
+function reset() {
+  unref(formRef)?.reset();
+  result.value = '';
+}
+
+function resetValidation() {
+  unref(formRef)?.resetValidation();
+  result.value = '';
+}
+</script>
+
+<template>
+  <div class="flex flex-col gap-2 w-[380px] m-auto">
+    <CdsForm ref="formRef" class="flex flex-col gap-2">
+      <CdsTextInput v-model="name" :rules="rules.name" label="Имя" placeholder="Введите имя" />
+      <CdsCheckbox v-model="agree" :rules="rules.agree" label="Согласен с условиями" />
+    </CdsForm>
+    <div class="flex flex-wrap gap-2">
+      <CdsButton @click="validate">Проверить</CdsButton>
+      <CdsButton appearance="secondary" @click="reset">Сбросить</CdsButton>
+      <CdsButton appearance="tertiary" @click="resetValidation">Сбросить валидацию</CdsButton>
+    </div>
+    <div v-if="result" class="text-sm text-content-secondary">{{ result }}</div>
+  </div>
+</template>
+```
+
+## Vee-validate
+
+The form gets along with external validation libraries. With [vee-validate](https://vee-validate.logaretm.com/v4/) the schema is set in `useForm`, and the error messages of the fields are passed into `error-messages`.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsButton, CdsCheckbox, CdsForm, CdsTextInput } from '@central-design-system/components';
+import { useField, useForm } from 'vee-validate';
+import { ref } from 'vue';
+
+const { handleSubmit, handleReset } = useForm({
+  validationSchema: {
+    name(value: string) {
+      if (!value) return 'Обязательно для заполнения';
+      if (value.length < 3) return 'Минимальное кол-во символов 3';
+      if (value.length > 10) return 'Максимальное кол-во символов 10';
+      return true;
+    },
+    phone(value: string) {
+      if (!value) return 'Обязательно для заполнения';
+      if (value.length < 8) return 'Минимальное кол-во символов 8';
+      if (value.length > 9) return 'Максимальное кол-во символов 9';
+      return true;
+    },
+    email(value: string) {
+      if (!value) return 'Обязательно для заполнения';
+      if (!/^[a-z.-]+@[a-z.-]+\.[a-z]+$/i.test(value)) return 'Некорректный E-mail';
+      return true;
+    },
+    checkbox(value: boolean) {
+      if (!value) return 'Обязательно для заполнения';
+      return true;
+    }
+  }
+});
+
+const name = useField('name');
+const phone = useField('phone');
+const email = useField('email');
+const checkbox = useField('checkbox');
+
+const result = ref('');
+
+const submit = handleSubmit((values) => {
+  result.value = `Отправлено: ${JSON.stringify(values)}`;
+});
+
+const clear = () => {
+  handleReset();
+  result.value = '';
+};
+</script>
+
+<template>
+  <CdsForm class="flex flex-col gap-2 w-[350px] m-auto" @submit.prevent="submit">
+    <CdsTextInput
+      v-model="name.value.value"
+      :error-messages="name.errorMessage.value"
+      label="Имя"
+      placeholder="Введите имя"
+    />
+    <CdsTextInput
+      v-model="phone.value.value"
+      :error-messages="phone.errorMessage.value"
+      label="Номер телефона"
+      placeholder="Введите номер"
+    />
+    <CdsTextInput
+      v-model="email.value.value"
+      :error-messages="email.errorMessage.value"
+      label="E-mail"
+      placeholder="Введите E-mail"
+    />
+    <CdsCheckbox
+      v-model="checkbox.value.value"
+      :error-messages="checkbox.errorMessage.value"
+      value="1"
+      label="Согласен с условиями"
+    />
+    <div class="flex gap-2">
+      <CdsButton type="submit">Отправить</CdsButton>
+      <CdsButton appearance="secondary" @click="clear">Очистить</CdsButton>
+    </div>
+    <div v-if="result" class="text-sm text-content-secondary break-all">{{ result }}</div>
+  </CdsForm>
+</template>
+```
+
+## Vuelidate
+
+With [vuelidate](https://vuelidate-next.netlify.app/) the rules are declared declaratively, and the field errors are passed into `error-messages` in the same way.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsButton, CdsCheckbox, CdsForm, CdsTextInput } from '@central-design-system/components';
+import { useVuelidate } from '@vuelidate/core';
+import { email, maxLength, minLength, required } from '@vuelidate/validators';
+import { reactive, ref, unref } from 'vue';
+
+const initialState = {
+  name: '',
+  email: '',
+  phone: '',
+  checkbox: null as boolean | null
+};
+
+const state = reactive({ ...initialState });
+const result = ref('');
+
+const rules = {
+  name: { required },
+  phone: { required, minLength: minLength(8), maxLength: maxLength(9) },
+  email: { required, email },
+  checkbox: { required }
+};
+
+const v$ = useVuelidate(rules, state);
+
+const clear = () => {
+  v$.value.$reset();
+  result.value = '';
+
+  for (const [key, value] of Object.entries(initialState)) {
+    (state as Record<string, any>)[key] = value;
+  }
+};
+
+const submit = () => {
+  if (v$.value.$invalid) {
+    v$.value.$touch();
+    return;
+  }
+
+  result.value = `Отправлено: ${JSON.stringify(state)}`;
+};
+</script>
+
+<template>
+  <CdsForm class="flex flex-col gap-2 w-[350px] m-auto" @submit.prevent="submit">
+    <CdsTextInput
+      v-model="state.name"
+      :error-messages="v$.name.$errors.map((e) => unref(e.$message))"
+      label="Имя"
+      placeholder="Введите имя"
+      @input="v$.name.$touch()"
+      @blur="v$.name.$touch()"
+    />
+    <CdsTextInput
+      v-model="state.phone"
+      :error-messages="v$.phone.$errors.map((e) => unref(e.$message))"
+      label="Номер телефона"
+      placeholder="Введите номер"
+      @input="v$.phone.$touch()"
+      @blur="v$.phone.$touch()"
+    />
+    <CdsTextInput
+      v-model="state.email"
+      :error-messages="v$.email.$errors.map((e) => unref(e.$message))"
+      label="E-mail"
+      placeholder="Введите E-mail"
+      @input="v$.email.$touch()"
+      @blur="v$.email.$touch()"
+    />
+    <CdsCheckbox
+      v-model="state.checkbox"
+      :error-messages="v$.checkbox.$errors.map((e) => unref(e.$message))"
+      label="Согласен с условиями"
+      @change="v$.checkbox.$touch()"
+      @blur="v$.checkbox.$touch()"
+    />
+    <div class="flex gap-2">
+      <CdsButton type="submit">Отправить</CdsButton>
+      <CdsButton appearance="secondary" @click="clear">Очистить</CdsButton>
+    </div>
+    <div v-if="result" class="text-sm text-content-secondary break-all">{{ result }}</div>
+  </CdsForm>
+</template>
+```

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

@@ -0,0 +1,10 @@
+# CdsForm — 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 heading and the description explain what the form is and what happens after submission. | A set of fields without context makes the user guess why they are filling them in. |
+| Show an error after the input or on submission — while a field is untouched the form stays silent. | A form that complains before the user's first action looks broken. |
+| The submit button names the action — it is clear what happens after the click. | A faceless “OK” says nothing about what the form will do. |

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

@@ -0,0 +1,15 @@
+# CdsForm — 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.
+
+## _CdsForm.variables.scss
+
+```scss
+@use '../../../styles/tools';
+
+$form-label-gap: var(--cds-spacing-100) !default;
+$form-description-gap: var(--cds-spacing-200) !default;
+$form-description-color: rgb(var(--cds-color-content-secondary)) !default;
+```

package/skills/cds-builder/references/components/cds-functional-button/api.md

@@ -0,0 +1,34 @@
+# CdsFunctionalButton — 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 functional button is a utility action next to the content: download a file in a row of a list, reveal a password in a field, collapse a block, open the menu of a record. It is a [CdsButton](../cds-button/api.md) with `size="sm"` and `appearance="tertiary"` fixed in place: the background is transparent and appears only on hover, so the button does not compete for attention with the content it stands next to.
+
+## CdsFunctionalButton
+
+**Props**
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `activeColor` | `string \| undefined` | — | no | Color of the component in its active state |
+| `baseColor` | `string \| undefined` | — | no | Color of the component in its inactive state |
+| `color` | `string \| undefined` | — | no | Component color |
+| `disabled` | `boolean \| null \| undefined` | `null` | no | Disabled state |
+| `exact` | `boolean \| undefined` | — | no | If true, the active state applies only on an exact route match |
+| `href` | `string \| undefined` | — | no | The `href` attribute of the link. When set, the component behaves as a regular link |
+| `icon` | `IconValue \| undefined` | — | no | Icon |
+| `loading` | `string \| boolean \| undefined` | — | no | Loading indicator for the component |
+| `readonly` | `boolean \| null \| undefined` | `null` | no | Read-only state |
+| `replace` | `boolean \| undefined` | — | no | If true, navigation replaces the current history entry instead of pushing a new one |
+| `tag` | `string \| JSXComponent<any> \| undefined` | `'button'` | no | Custom HTML tag or component to render |
+| `textColor` | `string \| undefined` | — | no | Text color of the component |
+| `theme` | `string \| undefined` | — | no | Component theme |
+| `to` | `LinkTo \| undefined` | — | no | Target route or route location object for RouterLink. When set, the component behaves as a RouterLink |
+
+**Slots**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `default` | `any` | Content inside the button |
+| `loader` | `any` | Loading indicator |