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

package/skills/cds-builder/references/components/cds-progress-circle/examples.md

@@ -0,0 +1,326 @@
+# CdsProgressCircle — 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 circular progress indicator shows the course of an operation: a file upload, data processing, a filling quota. The value is set in percent through `model-value`, and when the course of the operation is unknown, the `indeterminate` mode turns on an endless waiting animation.
+
+## Value
+
+The `model-value` prop is the current progress in percent, from 0 to 100. A change of the value is animated with a smooth transition of the arc.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsProgressCircle } from '@central-design-system/components';
+
+const values = [15, 40, 75, 100];
+</script>
+
+<template>
+  <div class="flex flex-wrap items-center justify-center gap-4">
+    <CdsProgressCircle v-for="value in values" :key="value" :model-value="value" />
+  </div>
+</template>
+```
+
+## Value
+
+The `rotate` prop turns the starting point of the arc by the given number of degrees. By default the progress grows clockwise from "12 o'clock".
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsProgressCircle } from '@central-design-system/components';
+
+const rotations = [0, 90, 180, 270];
+</script>
+
+<template>
+  <div class="flex flex-wrap items-center justify-center gap-4">
+    <CdsProgressCircle v-for="rotate in rotations" :key="rotate" :model-value="25" :rotate="rotate" />
+  </div>
+</template>
+```
+
+## Indeterminate progress
+
+The `indeterminate` prop turns on an endless animation — use it when the course of the operation is unknown. The value `disable-shrink` leaves only the rotation without the pulsation of the arc: this animation is simpler and does not load the main thread. It is also enabled automatically for users with the `prefers-reduced-motion` setting.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsProgressCircle } from '@central-design-system/components';
+</script>
+
+<template>
+  <div class="flex flex-wrap items-center justify-center gap-4">
+    <CdsProgressCircle indeterminate />
+    <CdsProgressCircle indeterminate="disable-shrink" />
+  </div>
+</template>
+```
+
+## Sizes
+
+The `size` prop sets the diameter: from `xs` to `xl` or a number in pixels. The default size is `md`.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsProgressCircle } from '@central-design-system/components';
+
+const { sizes } = CdsProgressCircle.constants;
+</script>
+
+<template>
+  <div class="flex flex-wrap items-center justify-center gap-4">
+    <CdsProgressCircle v-for="size of sizes" :key="size" :size="size" :model-value="65" />
+    <CdsProgressCircle :size="72" :model-value="65" />
+  </div>
+</template>
+```
+
+## Stroke
+
+The `width` prop sets the thickness of the stroke in pixels regardless of the diameter.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsProgressCircle } from '@central-design-system/components';
+
+const widths = [2, 4, 8];
+</script>
+
+<template>
+  <div class="flex flex-wrap items-center justify-center gap-4">
+    <CdsProgressCircle v-for="width in widths" :key="width" :model-value="65" :width="width" size="lg" />
+  </div>
+</template>
+```
+
+## Stroke
+
+The `rounded` prop rounds the ends of the arc.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsProgressCircle } from '@central-design-system/components';
+</script>
+
+<template>
+  <div class="flex flex-wrap items-center justify-center gap-4">
+    <CdsProgressCircle :model-value="65" :width="6" size="lg" />
+    <CdsProgressCircle :model-value="65" :width="6" size="lg" rounded />
+  </div>
+</template>
+```
+
+## Colors
+
+The `color` prop paints the progress arc, `bg-color` paints the background ring underneath. Both accept color tokens of the design system.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsProgressCircle } from '@central-design-system/components';
+</script>
+
+<template>
+  <div class="flex flex-wrap items-center justify-center gap-4">
+    <CdsProgressCircle :model-value="65" color="green" />
+    <CdsProgressCircle :model-value="65" color="lemon" />
+    <CdsProgressCircle :model-value="65" color="red" />
+    <CdsProgressCircle :model-value="65" color="brand-primary" bg-color="red" />
+  </div>
+</template>
+```
+
+## Content
+
+The `default` slot renders content in the center of the ring and receives the current value through the `value` slot prop — a handy way to show the percentage next to the arc.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsProgressCircle } from '@central-design-system/components';
+</script>
+
+<template>
+  <div class="flex justify-center">
+    <CdsProgressCircle :model-value="68" :size="64">
+      <template #default="{ value }">{{ Math.round(value) }}%</template>
+    </CdsProgressCircle>
+  </div>
+</template>
+```
+
+## Reveal animation
+
+The `reveal` prop animates the arc from zero to the current value when the component appears. The duration is configured with an object: `:reveal="{ duration: 1500 }"`.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsButton, CdsProgressCircle } from '@central-design-system/components';
+import { ref } from 'vue';
+
+const key = ref(0);
+</script>
+
+<template>
+  <div class="flex flex-col items-center gap-3">
+    <CdsProgressCircle :key="key" :model-value="75" :size="64" reveal />
+    <CdsButton appearance="secondary" size="sm" text="Повторить" @click="key++" />
+  </div>
+</template>
+```
+
+## File upload
+
+The upload progress is visible in the center of the ring through the `default` slot, and once it is done the percentage turns into a success icon. The `rounded` prop softens the arc, and `color` supports the positive scenario.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsButton, CdsIcon, CdsProgressCircle } from '@central-design-system/components';
+import { ref } from 'vue';
+
+const progress = ref(0);
+const uploading = ref(false);
+
+let timer: ReturnType<typeof setInterval> | undefined;
+
+const upload = () => {
+  clearInterval(timer);
+  progress.value = 0;
+  uploading.value = true;
+
+  timer = setInterval(() => {
+    progress.value = Math.min(progress.value + Math.random() * 18, 100);
+
+    if (progress.value === 100) {
+      clearInterval(timer);
+      uploading.value = false;
+    }
+  }, 300);
+};
+</script>
+
+<template>
+  <div class="flex flex-col items-center gap-3">
+    <CdsProgressCircle :model-value="progress" :size="72" :width="6" rounded color="green">
+      <template #default="{ value }">
+        <CdsIcon v-if="value === 100" icon="check-fill" color="green" />
+        <span v-else>{{ Math.round(value) }}%</span>
+      </template>
+    </CdsProgressCircle>
+
+    <CdsButton
+      prepend-icon="upload"
+      :text="progress === 100 ? 'Загрузить ещё раз' : 'Загрузить файл'"
+      :disabled="uploading"
+      @click="upload"
+    />
+  </div>
+</template>
+```
+
+## A filling quota
+
+The ring shows not only a process but also a static value — the used storage space, for example. A computed `color` switches the indicator from green to yellow and red as the limit approaches.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsButton, CdsProgressCircle } from '@central-design-system/components';
+import { computed, ref } from 'vue';
+
+const used = ref(52);
+
+const color = computed(() => {
+  if (used.value >= 90) return 'red';
+  if (used.value >= 70) return 'lemon';
+  return 'green';
+});
+</script>
+
+<template>
+  <div class="flex flex-col items-center gap-3">
+    <CdsProgressCircle :model-value="used" :size="80" :width="8" :color="color">
+      <template #default="{ value }">
+        <span class="text-content-secondary">{{ Math.round(value) }} ГБ</span>
+      </template>
+    </CdsProgressCircle>
+
+    <div class="flex gap-2">
+      <CdsButton
+        appearance="secondary"
+        size="sm"
+        text="Добавить файлы"
+        :disabled="used >= 100"
+        @click="used = Math.min(used + 15, 100)"
+      />
+      <CdsButton
+        appearance="tertiary"
+        size="sm"
+        text="Очистить"
+        :disabled="used <= 0"
+        @click="used = Math.max(used - 30, 0)"
+      />
+    </div>
+  </div>
+</template>
+```
+
+## A background operation
+
+A compact `indeterminate` indicator of the `xs` size sits in a line with the text and reports that the operation that was started is still running. The caption next to it explains what to expect — without it a spinning ring says nothing.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsButton, CdsIcon, CdsProgressCircle } from '@central-design-system/components';
+import { ref } from 'vue';
+
+const state = ref<'idle' | 'pending' | 'done'>('idle');
+
+const generate = () => {
+  state.value = 'pending';
+
+  setTimeout(() => {
+    state.value = 'done';
+  }, 2500);
+};
+</script>
+
+<template>
+  <div class="flex flex-col items-center gap-3">
+    <CdsButton text="Сформировать отчёт" :disabled="state === 'pending'" @click="generate" />
+
+    <div v-if="state === 'pending'" class="flex items-center gap-2 text-content-secondary">
+      <CdsProgressCircle indeterminate size="xs" :width="2" />
+      <span>Готовим отчёт — обычно это занимает меньше минуты</span>
+    </div>
+
+    <div v-else-if="state === 'done'" class="flex items-center gap-2">
+      <CdsIcon icon="check-fill" color="green" />
+      <span>Отчёт готов</span>
+    </div>
+  </div>
+</template>
+```

package/skills/cds-builder/references/components/cds-progress-circle/guidelines.md

@@ -0,0 +1,10 @@
+# CdsProgressCircle — 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 |
+| --- | --- |
+| When the course of the operation is known, show the value: the user sees how much is left. | An indeterminate animation over known progress leaves the user guessing how long the wait will be. |
+| A caption next to the indicator explains what is happening and what to expect. | Кольцо без подписи не отвечает на вопрос «что сейчас загружается?». |
+| For waiting inside a line of text xs is enough — the indicator does not compete with the content. | A large indicator in a line pulls attention away and breaks the vertical rhythm. |

package/skills/cds-builder/references/components/cds-progress-circle/tokens.md

@@ -0,0 +1,31 @@
+# CdsProgressCircle — 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.
+
+## _CdsProgressCircle.variables.scss
+
+```scss
+@use '../../../styles/tools';
+
+$progress-circle-underlay-color: rgb(var(--cds-color-content-placeholder), 0.4) !default;
+
+// Transition
+$progress-circle-reveal-duration: 900ms;
+$progress-circle-overlay-transition: all 0.4s ease-in-out, stroke-width 0s !default;
+$progress-circle-intermediate-svg-transition: all 0.4s ease-in-out !default;
+$progress-circle-rotate-animation: progress-circle-rotate 2s linear infinite !default;
+$progress-circle-rotate-dash: progress-circle-dash 2s ease-in-out infinite !default;
+$progress-circle-overlay-transform: rotate(calc(-90deg)) !default;
+
+// Sizes
+$progress-circle-size: 32px !default;
+$progress-circle-sizes: (
+  'xs': -4,
+  'sm': -2,
+  'md': 0,
+  'lg': 4,
+  'xl': 8
+) !default;
+```

package/skills/cds-builder/references/components/cds-radio/api.md

@@ -0,0 +1,47 @@
+# CdsRadio — API
+
+> Generated from meta.json by `bun run generate:skill`. Do not edit manually.
+> Tokens: [tokens.md](tokens.md)
+
+A radio button is one option of a mutually exclusive choice. It is not used on its own: the buttons are joined by [CdsRadioGroup](../cds-radio-group/api.md) — it keeps the selected value, captions the set and shows the messages. The button is left with `value` — the value of the option, `label` and `description` — its caption and details.
+
+## CdsRadio
+
+**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 |
+| `bgColor` | `string \| undefined` | — | no | Background color of the component |
+| `color` | `string \| undefined` | — | no | Component color |
+| `defaultsTarget` | `string \| undefined` | — | no | Name of the child component the group prop values are passed to as defaults |
+| `description` | `string \| undefined` | — | no | Description of the component, shown under the label |
+| `direction` | `"horizontal" \| "vertical" \| undefined` | `'horizontal'` | no | Switches the component between horizontal and vertical layout. |
+| `disabled` | `boolean \| null \| undefined` | `null` | no | Disabled state |
+| `error` | `boolean \| undefined` | — | no | Puts the component into the visual error state |
+| `falseIcon` | `IconValue \| undefined` | `'radio-off'` | no | Icon of the unselected state |
+| `falseValue` | `any` | — | no | Value for the false state. |
+| `id` | `string \| undefined` | — | no | Unique identifier of the component |
+| `inline` | `boolean \| undefined` | — | no | Renders the control as an inline element — the container does not stretch to the full width |
+| `label` | `string \| undefined` | — | no | Label text of the component |
+| `modelValue` | `any` | — | no | Value of the component (v-model). In a group it is the value of the selected control, with `multiple` — an array of the selected values |
+| `multiple` | `boolean \| null \| undefined` | `null` | no | Allows selecting several values — the model becomes an array. Turns on automatically when an array is passed to `modelValue` |
+| `name` | `string \| undefined` | — | no | The `name` attribute of the native input element. In a group one name joins all the nested controls |
+| `readonly` | `boolean \| null \| undefined` | `null` | no | Read-only state |
+| `textColor` | `string \| undefined` | — | no | Text color of the component |
+| `theme` | `string \| undefined` | — | no | Component theme |
+| `trueIcon` | `IconValue \| undefined` | `'radio-on'` | no | Icon of the selected state |
+| `trueValue` | `any` | — | no | Value for the true state. |
+| `type` | `string \| undefined` | — | no | Type of the native input element — `radio` or `checkbox`, for example |
+| `value` | `any` | — | no | Value used when the component is selected inside a group. When it is not set, a unique identifier is used. |
+| `valueComparator` | `ValueComparator \| undefined` | `true` | no | Function comparing the model value with the `value` of the control. Deep comparison by default |
+
+**Slots**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `default` | `{ backgroundColorClasses: Ref<string[], string[]>; backgroundColorStyles: Ref<CSSProperties, CSSProperties>; }` | Default slot |
+| `description` | `{ description: string \| undefined; props: Record<string, any>; }` | Default slot of the CdsDescription component |
+| `input` | `SelectionControlSlot` | Slot for the default input element. |
+| `label` | `{ label: string \| undefined; props: Record<string, any>; }` | Default slot of the CdsLabel component |

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

@@ -0,0 +1,36 @@
+# CdsRadio — 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.
+
+## _CdsRadio.variables.scss
+
+```scss
+@use "../../../styles/tools";
+
+// Radio
+$radio-button-size: tools.to-rem(16px) !default;
+
+// Selection Field
+$radio-selection-control-width: calc($radio-button-size + var(--cds-spacing-200)) !default;
+$radio-selection-control-height: tools.to-rem(20px) !default;
+
+// Colors
+$radio-button-colors: (
+  'unselected': (
+    default: rgb(var(--cds-color-line-primary)),
+    error: rgb(var(--cds-color-status-danger-line))
+  ),
+  'selected': (
+    default: rgb(var(--cds-color-line-selected)),
+    error: rgb(var(--cds-color-status-danger-line))
+  ),
+  'disabled': (
+    default: rgb(var(--cds-color-line-disable))
+  ),
+  'focus': (
+    default: rgb(var(--cds-color-line-focus-outline))
+  )
+) !default;
+```

package/skills/cds-builder/references/components/cds-radio-group/api.md

@@ -0,0 +1,87 @@
+# CdsRadioGroup — 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 radio group is a choice of one option out of a short mutually exclusive set: a payment method, a plan, a report period. The group keeps the selected value, captions the set with a heading and a description, shows messages and errors; the options themselves are [CdsRadio](../cds-radio/api.md) components with their own `value`.
+
+## CdsRadioGroup
+
+**Props**
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `activeColor` | `string \| undefined` | — | no | Color of the component in its active state |
+| `appendIcon` | `IconValue \| undefined` | — | no | Icon in the append slot, after the content |
+| `baseColor` | `string \| undefined` | — | no | Color of the component in its inactive state |
+| `bgColor` | `string \| undefined` | — | no | Background color of the component |
+| `centerAffix` | `boolean \| undefined` | `true` | no | Vertically center the appendInner, prependInner, clearIcon and label elements. |
+| `color` | `string \| undefined` | — | no | Component color |
+| `defaultsTarget` | `string \| undefined` | — | no | Name of the child component the group prop values are passed to as defaults |
+| `description` | `string \| undefined` | — | no | Description of the component, shown under the label |
+| `direction` | `"horizontal" \| "vertical" \| undefined` | `'vertical'` | no | Switches the component between horizontal and vertical layout. |
+| `disabled` | `boolean \| null \| undefined` | `null` | no | Disabled state |
+| `error` | `boolean \| undefined` | — | no | Puts the component into the visual 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. |
+| `falseIcon` | `IconValue \| undefined` | `'radio-off'` | no | Icon of an unselected radio button |
+| `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. |
+| `height` | `string \| number \| undefined` | `'auto'` | no | Height of the component |
+| `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 |
+| `inline` | `boolean \| undefined` | — | no | Renders the control as an inline element — the container does not stretch to the full width |
+| `label` | `string \| undefined` | — | no | Label text of 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 |
+| `modelValue` | `any` | — | no | Value of the component (v-model). In a group it is the value of the selected control, with `multiple` — an array of the selected values |
+| `name` | `string \| undefined` | — | no | The `name` attribute of the native input element. In a group one name joins all the nested controls |
+| `persistentHint` | `boolean \| undefined` | — | no | Always show the hint, not only on focus |
+| `prependIcon` | `IconValue \| undefined` | — | no | Icon in the prepend slot, before the content |
+| `readonly` | `boolean \| null \| undefined` | `null` | no | Read-only state |
+| `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 |
+| `textColor` | `string \| undefined` | — | no | Text color of the component |
+| `theme` | `string \| undefined` | — | no | Component theme |
+| `trueIcon` | `IconValue \| undefined` | `'radio-on'` | no | Icon of a selected radio button |
+| `type` | `string \| undefined` | `'radio'` | no | Type of the native input element of the group buttons |
+| `validateOn` | `ValidateOn \| undefined` | — | no | Changes the type of the event that triggers validation |
+| `validationValue` | `any` | — | no | Value used when applying the validation rules |
+| `valueComparator` | `ValueComparator \| undefined` | `true` | no | Function comparing the model value with the `value` of the control. Deep comparison by default |
+| `width` | `string \| number \| undefined` | — | no | Component width |
+
+**Events**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `update:modelValue` | `[value: any]` | Fires when the model of the component changes |
+
+**Slots**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `append` | `CdsInputSlot` | Adds an element after the input |
+| `default` | `any` | Default slot — the radio buttons of the group (`CdsRadio`) |
+| `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 |
+| `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 |
+
+**Exposed**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `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 |