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

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

@@ -0,0 +1,320 @@
+# CdsPagination — 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.
+
+Pagination splits a large data set into pages and helps you jump to the one you need: numbered buttons, "back" and "forward" arrows, jumps to the first and the last page, and a quick jump field. Extra numbers collapse into an ellipsis, and without an explicit limit the number of buttons adapts to the width of the container.
+
+## Number of pages
+
+The `length` prop sets the number of pages, `v-model` holds the number of the current one. While the focus is inside the pagination, the ← and → keys page through.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsPagination } from '@central-design-system/components';
+import { ref } from 'vue';
+
+const page = ref(1);
+</script>
+
+<template>
+  <div class="flex justify-center">
+    <CdsPagination v-model="page" length="10" />
+  </div>
+</template>
+```
+
+## Visible buttons
+
+The `total-visible` prop limits how many buttons are visible at once — the remaining pages collapse into an ellipsis (its text is changed by the `ellipsis` prop). Without `total-visible` the component counts how many buttons fit into the container itself and collapses the extra ones.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsPagination } from '@central-design-system/components';
+import { ref } from 'vue';
+
+const page = ref(5);
+</script>
+
+<template>
+  <div class="flex justify-center">
+    <CdsPagination v-model="page" length="20" total-visible="5" />
+  </div>
+</template>
+```
+
+## Edge pages
+
+The `show-first-last-page` prop adds buttons that jump to the first and the last page. The `only-first` value keeps just the first page button — handy when the total number of pages is unknown or only approximate.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsPagination } from '@central-design-system/components';
+import { ref } from 'vue';
+
+const page = ref(5);
+const pageOnlyFirst = ref(5);
+</script>
+
+<template>
+  <div class="flex flex-col items-center gap-4">
+    <CdsPagination v-model="page" length="10" total-visible="5" show-first-last-page />
+    <CdsPagination v-model="pageOnlyFirst" length="10" total-visible="5" show-first-last-page="only-first" />
+  </div>
+</template>
+```
+
+## Quick jump
+
+The `quick-jumper` prop adds a field where the user types a page number and gets there on Enter or on blur. The label before the field is changed by the `quick-jumper-label` prop.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsPagination } from '@central-design-system/components';
+import { ref } from 'vue';
+
+const page = ref(1);
+</script>
+
+<template>
+  <div class="flex justify-center">
+    <CdsPagination v-model="page" length="20" total-visible="5" quick-jumper />
+  </div>
+</template>
+```
+
+## Disabled state
+
+The `disabled` prop blocks the whole navigation — while the current page is loading, for example.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsPagination } from '@central-design-system/components';
+import { ref } from 'vue';
+
+const page = ref(3);
+</script>
+
+<template>
+  <div class="flex justify-center">
+    <CdsPagination v-model="page" length="10" disabled />
+  </div>
+</template>
+```
+
+## Slots
+
+Slots replace the default buttons while keeping the switching logic: every slot receives a ready `onClick` handler and the `disabled` state.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsButton, CdsPagination } from '@central-design-system/components';
+import { ref } from 'vue';
+
+const page = ref(1);
+</script>
+
+<template>
+  <div class="flex justify-center">
+    <CdsPagination v-model="page" length="8" total-visible="5">
+      <template #prev="{ onClick, disabled }">
+        <CdsButton
+          appearance="tertiary"
+          size="sm"
+          prepend-icon="chevron-left"
+          text="Назад"
+          :disabled="disabled"
+          @click="onClick"
+        />
+      </template>
+
+      <template #next="{ onClick, disabled }">
+        <CdsButton
+          appearance="tertiary"
+          size="sm"
+          append-icon="chevron-right"
+          text="Вперёд"
+          :disabled="disabled"
+          @click="onClick"
+        />
+      </template>
+    </CdsPagination>
+  </div>
+</template>
+```
+
+## Paged list
+
+The classic pairing: the list shows the slice of data for the current page, the "Показано 1–4 из 23" caption gives a sense of the total, and `total-visible="3"` keeps the pagination compact next to the counter.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsPagination } from '@central-design-system/components';
+import { computed, ref } from 'vue';
+
+const pageSize = 4;
+
+const contracts = Array.from({ length: 23 }, (_, index) => ({
+  id: index + 1,
+  title: `Договор поставки №${1240 + index}`,
+  date: `${String((index % 28) + 1).padStart(2, '0')}.06.2026`
+}));
+
+const page = ref(1);
+const pages = Math.ceil(contracts.length / pageSize);
+
+const visible = computed(() => contracts.slice((page.value - 1) * pageSize, page.value * pageSize));
+
+const rangeLabel = computed(() => {
+  const from = (page.value - 1) * pageSize + 1;
+  const to = Math.min(page.value * pageSize, contracts.length);
+
+  return `${from}–${to} из ${contracts.length}`;
+});
+</script>
+
+<template>
+  <div class="m-auto flex w-full max-w-md flex-col gap-3">
+    <ul class="m-0 flex list-none flex-col gap-1 p-0">
+      <li v-for="contract in visible" :key="contract.id" class="flex justify-between gap-3">
+        <span>{{ contract.title }}</span>
+        <span>{{ contract.date }}</span>
+      </li>
+    </ul>
+
+    <div class="flex flex-wrap items-center justify-between gap-3">
+      <span>Показано {{ rangeLabel }}</span>
+
+      <CdsPagination v-model="page" :length="pages" total-visible="3" />
+    </div>
+  </div>
+</template>
+```
+
+## Loading pages from the server
+
+When the data comes from the server, watch `v-model` (or the `first` / `prev` / `next` / `last` / `quickJump` events) and fire the request on a page change. While the request is in flight, `disabled` blocks the pagination and guards against extra switches.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsPagination, CdsProgressCircle } from '@central-design-system/components';
+import { onMounted, ref, watch } from 'vue';
+
+const pageSize = 3;
+const total = 27;
+
+const page = ref(1);
+const loading = ref(false);
+const items = ref<string[]>([]);
+
+async function load() {
+  loading.value = true;
+
+  await new Promise((resolve) => setTimeout(resolve, 800));
+
+  items.value = Array.from(
+    { length: Math.min(pageSize, total - (page.value - 1) * pageSize) },
+    (_, index) => `Заявка №${(page.value - 1) * pageSize + index + 1} — согласование договора`
+  );
+
+  loading.value = false;
+}
+
+watch(page, load);
+onMounted(load);
+</script>
+
+<template>
+  <div class="m-auto flex w-full max-w-md flex-col items-center gap-3">
+    <div class="flex min-h-[72px] w-full items-center justify-center">
+      <CdsProgressCircle v-if="loading" indeterminate aria-label="Загружаем страницу" />
+
+      <ul v-else class="m-0 flex w-full list-none flex-col gap-1 p-0">
+        <li v-for="item in items" :key="item">{{ item }}</li>
+      </ul>
+    </div>
+
+    <CdsPagination v-model="page" :length="total / pageSize" total-visible="5" :disabled="loading" />
+  </div>
+</template>
+```
+
+## Search with a page reset
+
+Filtering recalculates the number of pages and resets the current page to the first one — otherwise the user may end up on a page that no longer exists. When the results fit on a single page, the pagination hides.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsPagination, CdsTextInput } from '@central-design-system/components';
+import { computed, ref, watch } from 'vue';
+
+const pageSize = 4;
+
+const companies = [
+  'Альфа Логистика',
+  'Вектор Строй',
+  'Гранит Сервис',
+  'Дельта Транс',
+  'Звезда Ритейл',
+  'Импульс Энерго',
+  'Квант Технологии',
+  'Ладога Снаб',
+  'Меркурий Опт',
+  'Нева Комплект',
+  'Орион Металл',
+  'Прогресс Авто',
+  'Ресурс Групп',
+  'Салют Пром',
+  'Титан Инжиниринг',
+  'Урал Механика',
+  'Фотон Электро',
+  'Эталон Сталь'
+];
+
+const query = ref('');
+const page = ref(1);
+
+const filtered = computed(() =>
+  companies.filter((company) => company.toLowerCase().includes(query.value.trim().toLowerCase()))
+);
+
+const pages = computed(() => Math.ceil(filtered.value.length / pageSize));
+
+const visible = computed(() => filtered.value.slice((page.value - 1) * pageSize, page.value * pageSize));
+
+watch(query, () => (page.value = 1));
+</script>
+
+<template>
+  <div class="m-auto flex w-full max-w-md flex-col gap-3">
+    <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="company in visible" :key="company">{{ company }}</li>
+      <li v-if="filtered.length === 0">Ничего не найдено</li>
+    </ul>
+
+    <div v-if="pages > 1" class="flex justify-center">
+      <CdsPagination v-model="page" :length="pages" total-visible="5" />
+    </div>
+  </div>
+</template>
+```

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

@@ -0,0 +1,10 @@
+# CdsPagination — 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 |
+| --- | --- |
+| A long list of pages is collapsed: the edge pages, the neighbors of the current one and an ellipsis stay visible. | A row with every page takes the full width and forces the reader to hunt for the right number. |
+| The quick jump field helps when there are dozens of pages and paging with arrows takes too long. | With three pages the field is redundant: every page is one click away. |
+| Pagination appears only when there is more than one page. | A single-page pagination offers no actions — hide it. |

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

@@ -0,0 +1,20 @@
+# CdsPagination — 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.
+
+## _CdsPagination.variables.scss
+
+```scss
+@use '../../../styles/tools';
+
+$pagination-padding: var(--cds-spacing-100) 0 !default;
+$pagination-button-padding: var(--cds-spacing-100) !default;
+$pagination-button-width: tools.to-rem(24px) !default;
+$pagination-active-color: rgb(var(--cds-color-content-tertiary)) !default;
+$pagination-controls-gap: var(--cds-spacing-200) !default;
+$pagination-controls-margin: var(--cds-spacing-400) !default;
+$pagination-controls-page-color: rgb(var(--cds-color-content-tertiary)) !default;
+$pagination-input-width: tools.to-rem(48px) !default;
+```

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

@@ -0,0 +1,53 @@
+# CdsProgressBar — 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 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.
+
+## CdsProgressBar
+
+**Props**
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `absolute` | `boolean \| undefined` | — | no | Absolute positioning of the component |
+| `active` | `boolean \| undefined` | `true` | no | Controls the active state of the progress bar |
+| `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 |
+| `bgOpacity` | `string \| number \| undefined` | — | no | Opacity of the progress bar background |
+| `bufferColor` | `string \| undefined` | — | no | Color of the buffer part of the progress bar |
+| `bufferOpacity` | `string \| number \| undefined` | — | no | Opacity of the buffer part of the progress bar |
+| `bufferValue` | `string \| number \| undefined` | `0` | no | Buffer value of the progress |
+| `chunkCount` | `string \| number \| undefined` | `null` | no | Number of segments the progress bar is split into |
+| `chunkGap` | `string \| number \| undefined` | `4` | no | Gap between the segments of the progress bar |
+| `chunkWidth` | `string \| number \| undefined` | `null` | no | Width of a single segment of the progress bar |
+| `clickable` | `boolean \| undefined` | — | no | Makes the progress bar clickable |
+| `color` | `string \| undefined` | — | no | Component color |
+| `height` | `string \| number \| undefined` | `4` | no | Height of the progress bar |
+| `indeterminate` | `boolean \| undefined` | — | no | Indeterminate progress state with no fixed value |
+| `location` | `Anchor \| null \| undefined` | `'top'` | no | Position of the element relative to its container, for example "top left", "center", "bottom right". |
+| `max` | `string \| number \| undefined` | `100` | no | Maximum progress value |
+| `modelValue` | `string \| number \| undefined` | `0` | no | Current progress value |
+| `opacity` | `string \| number \| undefined` | — | no | Opacity of the main progress indicator |
+| `reverse` | `boolean \| undefined` | — | no | Fills the progress bar in the opposite direction |
+| `roundedBar` | `boolean \| undefined` | — | no | Rounds the progress indicator |
+| `stream` | `boolean \| undefined` | — | no | Shows a streaming animation over the progress indicator |
+| `striped` | `boolean \| undefined` | — | no | Shows stripes on the progress indicator |
+| `tag` | `string \| JSXComponent<any> \| undefined` | `'div'` | no | Custom HTML tag or component to render |
+| `textColor` | `string \| undefined` | — | no | Text color of the component |
+| `theme` | `string \| undefined` | — | no | Component theme |
+| `variant` | `"split" \| undefined` | — | no | Display variant of the progress bar segments |
+
+**Events**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `update:modelValue` | `[value: number]` | Fires when the progress value changes — by dragging in the interactive mode, for example |
+
+**Slots**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `default` | `{ value: number; buffer: number; }` | Content above the bar — a caption with the percentage, for example. The params carry the current value and the buffer value |