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

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

@@ -0,0 +1,393 @@
+# CdsProgressBar — 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 linear progress indicator — a horizontal bar for the course of an operation: a file upload, the steps of a wizard, media playback. The value comes from `model-value`, and when the course of the operation is unknown, the `indeterminate` mode turns on a running waiting animation.
+
+## Value
+
+The `model-value` prop is the current progress. The bar counts from 0 to `max` (100 by default), so you can pass raw values — seconds or megabytes — without converting them into percent. A change of the value is animated with a smooth transition, and `reverse` fills the bar from right to left.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsProgressBar } from '@central-design-system/components';
+
+const values = [15, 40, 75, 100];
+</script>
+
+<template>
+  <div class="m-auto flex w-[400px] flex-col gap-4">
+    <CdsProgressBar v-for="value in values" :key="value" :model-value="value" />
+  </div>
+</template>
+```
+
+## Indeterminate progress
+
+The `indeterminate` prop turns on the running animation — use it when the course of the operation is unknown and there is no percentage to show.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsProgressBar } from '@central-design-system/components';
+</script>
+
+<template>
+  <div class="m-auto w-[400px]">
+    <CdsProgressBar indeterminate color="brand-primary" />
+  </div>
+</template>
+```
+
+## Buffer
+
+The `buffer-value` prop is a second bar between the indicator and the background: the part that is already prepared but not passed yet — a preloaded fragment of a video, for example. To make the buffer readable against the bar, raise `buffer-opacity`; a separate color comes from `buffer-color`.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsProgressBar } from '@central-design-system/components';
+</script>
+
+<template>
+  <div class="m-auto w-[400px]">
+    <CdsProgressBar :model-value="30" :buffer-value="65" buffer-opacity="0.3" color="brand-primary" />
+  </div>
+</template>
+```
+
+## Buffer
+
+The `stream` prop adds a dashed animation from the edge of the buffer to the end of the bar — a signal that the data keeps coming. The edge of the stream is set by `buffer-value`, and the background is hidden.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsProgressBar } from '@central-design-system/components';
+</script>
+
+<template>
+  <div class="m-auto w-[400px]">
+    <CdsProgressBar :model-value="25" :buffer-value="60" buffer-opacity="0.3" stream color="brand-primary" />
+  </div>
+</template>
+```
+
+## Height
+
+The `height` prop sets the height of the bar in pixels. The default is 4.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsProgressBar } from '@central-design-system/components';
+</script>
+
+<template>
+  <div class="m-auto flex w-[400px] flex-col gap-4">
+    <CdsProgressBar :model-value="60" :height="2" />
+    <CdsProgressBar :model-value="60" />
+    <CdsProgressBar :model-value="60" :height="8" />
+    <CdsProgressBar :model-value="60" :height="16" />
+  </div>
+</template>
+```
+
+## Rounding
+
+The `rounded-bar` prop rounds the leading edge of the indicator. The start stays straight — the bar reads as continuous from the zero mark.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsProgressBar } from '@central-design-system/components';
+</script>
+
+<template>
+  <div class="m-auto flex w-[400px] flex-col gap-4">
+    <CdsProgressBar :model-value="60" :height="8" color="brand-primary" />
+    <CdsProgressBar :model-value="60" :height="8" color="brand-primary" rounded-bar />
+  </div>
+</template>
+```
+
+## Colors
+
+The `color` prop paints the indicator and — as long as separate colors are not set — the buffer and the background too. Your own background color comes from `bg-color`, and the transparency of the layers from `opacity` for the indicator and `bg-opacity` for the background.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsProgressBar } from '@central-design-system/components';
+</script>
+
+<template>
+  <div class="m-auto flex w-[400px] flex-col gap-4">
+    <CdsProgressBar :model-value="60" color="green" />
+    <CdsProgressBar :model-value="60" color="lemon" />
+    <CdsProgressBar :model-value="60" color="red" />
+    <CdsProgressBar :model-value="60" color="brand-primary" bg-color="red" />
+  </div>
+</template>
+```
+
+## Stripes
+
+The `striped` prop lays running diagonal stripes over the indicator — they bring long operations with a known course to life.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsProgressBar } from '@central-design-system/components';
+</script>
+
+<template>
+  <div class="m-auto flex w-[400px] flex-col gap-4">
+    <CdsProgressBar :model-value="45" striped color="brand-primary" :height="12" />
+    <CdsProgressBar :model-value="70" striped color="green" :height="12" />
+  </div>
+</template>
+```
+
+## Segments
+
+The `chunk-count` prop splits the bar into equal segments — by the number of steps, for example — while `chunk-width` builds segments of a fixed width. The gap between them comes from `chunk-gap`. The indicator fills segments whole: the value snaps to the edge of the nearest segment.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsProgressBar } from '@central-design-system/components';
+</script>
+
+<template>
+  <div class="m-auto flex w-[400px] flex-col gap-4">
+    <CdsProgressBar :model-value="60" :chunk-count="10" :height="8" color="brand-primary" />
+    <CdsProgressBar :model-value="60" :chunk-width="12" :height="8" color="brand-primary" />
+    <CdsProgressBar :model-value="60" :chunk-count="10" :chunk-gap="8" :height="8" color="brand-primary" />
+  </div>
+</template>
+```
+
+## Segments
+
+The `variant="split"` option does not cut the bar into pieces but separates the filled part from the rest with a single gap — the indicator and the background read as two independent segments.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsProgressBar } from '@central-design-system/components';
+</script>
+
+<template>
+  <div class="m-auto flex w-[400px] flex-col gap-4">
+    <CdsProgressBar variant="split" :model-value="40" :height="8" color="brand-primary" />
+    <CdsProgressBar
+      variant="split"
+      :model-value="40"
+      :buffer-value="70"
+      buffer-opacity="0.4"
+      :height="8"
+      color="brand-primary"
+    />
+  </div>
+</template>
+```
+
+## Content
+
+The `default` slot renders content in the center of the bar and receives the `value` and `buffer` slot props — normalized percentages. Increase `height` so that the content fits.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsProgressBar } from '@central-design-system/components';
+</script>
+
+<template>
+  <div class="m-auto w-[400px]">
+    <CdsProgressBar :model-value="64" :height="20" color="green">
+      <template #default="{ value }">{{ Math.round(value) }}%</template>
+    </CdsProgressBar>
+  </div>
+</template>
+```
+
+## File upload
+
+The button starts the upload: the bar grows as the data arrives, and the caption above it shows the file and the percentage. The `green` color supports the positive scenario, and once it is done the button offers to upload again.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsButton, CdsProgressBar } 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="m-auto flex w-[360px] flex-col items-center gap-3">
+    <div class="flex w-full items-center justify-between">
+      <span>report.xlsx</span>
+      <span>{{ Math.round(progress) }}%</span>
+    </div>
+
+    <CdsProgressBar :model-value="progress" :height="8" color="green" />
+
+    <CdsButton
+      prepend-icon="upload"
+      :text="progress === 100 ? 'Загрузить ещё раз' : 'Загрузить файл'"
+      :disabled="uploading"
+      @click="upload"
+    />
+  </div>
+</template>
+```
+
+## Wizard steps
+
+`chunk-count` set to the number of steps turns the bar into a wizard indicator: filled segments are the steps behind, semi-transparent ones are the steps ahead. The value is the share of the current step out of the total.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsButton, CdsProgressBar } from '@central-design-system/components';
+import { computed, ref } from 'vue';
+
+const steps = ['Данные компании', 'Контакты', 'Реквизиты', 'Подтверждение'];
+const step = ref(1);
+
+const progress = computed(() => (step.value / steps.length) * 100);
+</script>
+
+<template>
+  <div class="m-auto flex w-[400px] flex-col gap-3">
+    <span>Шаг {{ step }} из {{ steps.length }}: {{ steps[step - 1] }}</span>
+
+    <CdsProgressBar :model-value="progress" :chunk-count="steps.length" :height="8" color="brand-primary" />
+
+    <div class="flex justify-between">
+      <CdsButton text="Назад" appearance="secondary" :disabled="step === 1" @click="step--" />
+      <CdsButton text="Далее" :disabled="step === steps.length" @click="step++" />
+    </div>
+  </div>
+</template>
+```
+
+## Seeking a video
+
+The `clickable` prop turns the bar into a control: a click writes the new value into `v-model`. The buffer shows the preloaded fragment, `stream` shows that the loading continues, and the captions compute the time from the percentages.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsProgressBar } from '@central-design-system/components';
+import { ref } from 'vue';
+
+const duration = 225;
+const position = ref(35);
+const buffered = ref(60);
+
+const seek = (value: number) => {
+  buffered.value = Math.min(100, value + 25);
+};
+
+const format = (percent: number) => {
+  const seconds = Math.round((percent / 100) * duration);
+
+  return `${Math.floor(seconds / 60)}:${String(seconds % 60).padStart(2, '0')}`;
+};
+</script>
+
+<template>
+  <div class="m-auto flex w-[400px] flex-col gap-2">
+    <CdsProgressBar
+      v-model="position"
+      clickable
+      :buffer-value="buffered"
+      buffer-opacity="0.3"
+      stream
+      :height="8"
+      color="brand-primary"
+      @update:model-value="seek"
+    />
+
+    <div class="flex justify-between">
+      <span>{{ format(position) }}</span>
+      <span>{{ format(100) }}</span>
+    </div>
+  </div>
+</template>
+```
+
+## Refreshing the data in a card
+
+The `absolute` prop pins the bar to the top edge of a container with `position: relative` — the indicator does not push the content around. The `active` prop hides the bar by smoothly collapsing its height to zero, and `indeterminate` spares you from measuring the progress of a background operation.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsButton, CdsCard, CdsCardText, CdsCardTitle, CdsProgressBar } from '@central-design-system/components';
+import { ref } from 'vue';
+
+const loading = ref(false);
+
+let timer: ReturnType<typeof setTimeout> | undefined;
+
+const refresh = () => {
+  clearTimeout(timer);
+  loading.value = true;
+  timer = setTimeout(() => (loading.value = false), 2500);
+};
+</script>
+
+<template>
+  <CdsCard class="relative m-auto w-[320px] overflow-hidden">
+    <CdsProgressBar absolute indeterminate :active="loading" color="brand-primary" />
+
+    <CdsCardItem>
+      <CdsCardTitle>Курсы валют</CdsCardTitle>
+    </CdsCardItem>
+    <CdsCardText>Доллар — 79,8 ₽, евро — 86,2 ₽. Данные обновляются раз в час.</CdsCardText>
+
+    <CdsCardActions class="justify-end p-4 pt-0">
+      <CdsButton text="Обновить" appearance="secondary" prepend-icon="refresh" :loading="loading" @click="refresh" />
+    </CdsCardActions>
+  </CdsCard>
+</template>
+```

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

@@ -0,0 +1,10 @@
+# CdsProgressBar — 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 hides how long the wait will be. |
+| A caption next to the bar explains what is happening and what to expect. | Шкала без подписи не отвечает на вопрос «что сейчас загружается?». |
+| Content inside the bar needs room — increase height so that the text fits. | At the default height the text does not fit and runs over the neighboring content. |

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

@@ -0,0 +1,33 @@
+# CdsProgressBar — 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.
+
+## _CdsProgressBar.variables.scss
+
+```scss
+@use 'sass:map';
+@use '../../../styles/tools';
+@use '../../../styles/settings';
+
+$progress-bar-transition: .2s settings.$standard-easing !default;
+$progress-bar-background: currentcolor !default;
+$progress-bar-background-opacity: 0.15 !default;
+$progress-bar-border-radius: map.get(settings.$rounded, 'pill') !default;
+$progress-bar-indeterminate-animation-duration: 2.2s !default;
+$progress-bar-stream-animation: stream .25s infinite linear !default;
+$progress-bar-stream-opacity: 0.3 !default;
+$progress-bar-striped-size: var(--cds-progress-bar-height) !default;
+$progress-bar-striped-animation: progress-bar-stripes 1s infinite linear !default;
+$progress-bar-stripe-gradient: linear-gradient(
+  135deg,
+  hsl(0deg 0% 100% / 25%) 25%,
+  transparent 0,
+  transparent 50%,
+  hsl(0deg 0% 100% / 25%) 0,
+  hsl(0deg 0% 100% / 25%) 75%,
+  transparent 0,
+  transparent
+) !default;
+```

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

@@ -0,0 +1,30 @@
+# CdsProgressCircle — 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 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.
+
+## CdsProgressCircle
+
+**Props**
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `bgColor` | `string \| undefined` | — | no | Background color of the loader |
+| `color` | `string \| undefined` | — | no | Color of the loader |
+| `indeterminate` | `boolean \| "disable-shrink" \| undefined` | — | no | Shows the animation continuously; use it when the course of the loading is unknown. The string `disable-shrink` switches to a simpler animation that does not run on the main thread |
+| `modelValue` | `string \| number \| undefined` | `0` | no | Current loading progress in percent |
+| `reveal` | `boolean \| { duration?: number \| undefined; } \| undefined` | `false` | no | Animates the indicator from zero to the current value when the component appears. The `{ duration }` object sets the animation duration in milliseconds |
+| `rotate` | `string \| number \| undefined` | `0` | no | Turns the starting point of the circle by the given number of degrees |
+| `rounded` | `boolean \| undefined` | — | no | Rounds the ends of the progress arc |
+| `size` | `number \| "xs" \| "sm" \| "md" \| "lg" \| "xl" \| undefined` | `'md'` | no | Size of the component |
+| `tag` | `string \| JSXComponent<any> \| undefined` | `'div'` | no | Custom HTML tag or component to render |
+| `theme` | `string \| undefined` | — | no | Component theme |
+| `width` | `string \| number \| undefined` | `4` | no | Sets the thickness of the circle stroke in pixels |
+
+**Slots**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `default` | `{ value: number; }` | Default slot. Carries the progress value of the loading indicator. |