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

package/skills/cds-builder/references/components/cds-virtual-scroll/examples.md

@@ -0,0 +1,272 @@
+# CdsVirtualScroll — 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.
+
+Virtual scrolling keeps long lists fast: only the visible rows get into the DOM, not the whole array. Pass the records to `items`, the markup of a row to the slot, and a list of tens of thousands of positions scrolls as smoothly as a list of ten.
+
+## Fixed height
+
+The `height` prop sets the height of the viewport — the scrolling happens inside it. If all the rows have the same height, set `item-height`: the component will not measure every row, and the positions and the scrollbar will be exact from the very first render.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsCard, CdsList, CdsListItem, CdsVirtualScroll } from '@central-design-system/components';
+
+const items = Array.from({ length: 10000 }, (_, index) => ({
+  title: `Позиция каталога №${index + 1}`
+}));
+</script>
+
+<template>
+  <CdsCard class="m-auto w-[320px]">
+    <CdsList>
+      <CdsVirtualScroll height="300" item-height="36" :items="items">
+        <template #default="{ item, index }">
+          <CdsListItem
+            :base-color="index % 2 ? 'surface-primary' : 'surface-secondary'"
+            :height="36"
+            :title="item.title"
+          />
+        </template>
+      </CdsVirtualScroll>
+    </CdsList>
+  </CdsCard>
+</template>
+```
+
+## Dynamic height
+
+Without `item-height` the component measures the rows automatically — this fits content of variable length: comments, messages, descriptions. The heights get refined as you scroll, so the scrollbar may shift slightly.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsCard, CdsVirtualScroll } from '@central-design-system/components';
+
+const texts = [
+  'Согласовано.',
+  'Уточните, пожалуйста, сроки поставки: в прошлой заявке отгрузка задержалась на неделю.',
+  'Прошу приложить спецификацию к позиции.',
+  'Цена выше средней по рынку — запросите у поставщика пересчёт и добавьте обоснование к заявке, иначе финансовый отдел вернёт её на доработку.'
+];
+
+const items = Array.from({ length: 5000 }, (_, index) => ({
+  id: index + 1,
+  author: `Участник ${(index % 27) + 1}`,
+  text: texts[index % texts.length]
+}));
+</script>
+
+<template>
+  <CdsCard class="m-auto w-[360px]">
+    <CdsVirtualScroll height="300" item-key="id" :items="items">
+      <template #default="{ item }">
+        <div class="border-b border-line-primary p-2">
+          <div class="text-100 text-content-secondary">{{ item.author }}</div>
+          <div class="text-200">{{ item.text }}</div>
+        </div>
+      </template>
+    </CdsVirtualScroll>
+  </CdsCard>
+</template>
+```
+
+## Renderless mode
+
+The `renderless` prop removes the own scroll container: the component listens to the scrolling of the nearest scrollable parent and renders the rows without wrappers. The slot additionally receives `itemRef` — bind it to the root node of the row so that the component knows its height. This is how the list fits into an existing scroll — of a panel or of the whole page. Give the scrollable parent `position: relative` — the component counts the row positions from it.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsVirtualScroll } from '@central-design-system/components';
+
+const items = Array.from({ length: 3000 }, (_, index) => `Строка отчёта №${index + 1}`);
+</script>
+
+<template>
+  <div class="relative m-auto h-[300px] w-[360px] overflow-y-auto rounded-200 border border-line-primary p-2">
+    <div class="text-300">Отчёт за квартал</div>
+    <p class="text-100 text-content-secondary">
+      Шапка — часть общего потока: скролл-контейнер здесь один, родительский, и заголовок прокручивается вместе со
+      строками списка.
+    </p>
+
+    <CdsVirtualScroll renderless :items="items">
+      <template #default="{ item, itemRef }">
+        <div :ref="itemRef" class="py-1">{{ item }}</div>
+      </template>
+    </CdsVirtualScroll>
+  </div>
+</template>
+```
+
+## Catalog search
+
+Pass an already filtered array to `items`: a `computed` recalculates the records on input, and the component picks the new list up on its own. `item-key="id"` binds the rows to the records rather than to the positions in the array — so the rows do not get mixed up while filtering.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsCard, CdsList, CdsListItem, CdsTextInput, CdsVirtualScroll } from '@central-design-system/components';
+import { computed, ref } from 'vue';
+
+const query = ref('');
+
+const categories = ['Крепёж', 'Инструмент', 'Электрика', 'Сантехника', 'Спецодежда'];
+
+const items = Array.from({ length: 10000 }, (_, index) => ({
+  id: index + 1,
+  title: `${categories[index % categories.length]}, артикул ${10000 + index}`
+}));
+
+const filtered = computed(() => {
+  const search = query.value.trim().toLowerCase();
+
+  return search ? items.filter((item) => item.title.toLowerCase().includes(search)) : items;
+});
+</script>
+
+<template>
+  <div class="m-auto flex w-[360px] flex-col gap-2">
+    <CdsTextInput v-model="query" clearable hide-details placeholder="Поиск по каталогу" prepend-inner-icon="search" />
+
+    <CdsCard>
+      <CdsList v-if="filtered.length">
+        <CdsVirtualScroll height="260" item-height="36" item-key="id" :items="filtered">
+          <template #default="{ item }">
+            <CdsListItem :height="36" :title="item.title" />
+          </template>
+        </CdsVirtualScroll>
+      </CdsList>
+      <div v-else class="p-2 text-content-secondary">Ничего не найдено</div>
+    </CdsCard>
+
+    <div class="text-100 text-content-secondary">Найдено: {{ filtered.length.toLocaleString('ru-RU') }}</div>
+  </div>
+</template>
+```
+
+## Jumping through a journal
+
+The component exposes the `scrollToIndex` method — get it through a ref and scroll the list programmatically. The month buttons calculate the index of the first operation of the month; with a fixed `item-height` the jump lands exactly on the right row.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsButton, CdsCard, CdsList, CdsListItem, CdsVirtualScroll } from '@central-design-system/components';
+import { ref } from 'vue';
+
+const MONTHS = [
+  'Январь',
+  'Февраль',
+  'Март',
+  'Апрель',
+  'Май',
+  'Июнь',
+  'Июль',
+  'Август',
+  'Сентябрь',
+  'Октябрь',
+  'Ноябрь',
+  'Декабрь'
+];
+const PER_MONTH = 400;
+
+const items = Array.from({ length: MONTHS.length * PER_MONTH }, (_, index) => ({
+  id: index + 1,
+  title: `${MONTHS[Math.floor(index / PER_MONTH)]} — операция №${index + 1}`
+}));
+
+const virtualScroll = ref<InstanceType<typeof CdsVirtualScroll>>();
+
+function scrollToMonth(month: number) {
+  virtualScroll.value?.scrollToIndex(month * PER_MONTH);
+}
+</script>
+
+<template>
+  <div class="m-auto flex w-[400px] flex-col gap-2">
+    <div class="flex flex-wrap justify-center gap-1">
+      <CdsButton
+        v-for="(month, index) in MONTHS"
+        :key="month"
+        appearance="tertiary"
+        size="xs"
+        @click="scrollToMonth(index)"
+      >
+        {{ month.slice(0, 3) }}
+      </CdsButton>
+    </div>
+
+    <CdsCard>
+      <CdsList>
+        <CdsVirtualScroll ref="virtualScroll" height="260" item-height="36" item-key="id" :items="items">
+          <template #default="{ item }">
+            <CdsListItem :height="36" :title="item.title" />
+          </template>
+        </CdsVirtualScroll>
+      </CdsList>
+    </CdsCard>
+  </div>
+</template>
+```
+
+## Selection in a long list
+
+The rows outside the screen do not exist in the DOM, so keep the selection state in the data, not in the rows themselves. In the demo the checked `id`s live in a `Set`: the checkbox of a row reads it and changes it on click — the selection survives any scrolling.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsCard, CdsCheckbox, CdsVirtualScroll } from '@central-design-system/components';
+import { ref } from 'vue';
+
+const departments = ['Закупки', 'Продажи', 'Логистика', 'Финансы'];
+
+const employees = Array.from({ length: 8000 }, (_, index) => ({
+  id: index + 1,
+  name: `Сотрудник ${index + 1}`,
+  department: departments[index % departments.length]
+}));
+
+const selected = ref(new Set<number>());
+
+function toggle(id: number) {
+  if (selected.value.has(id)) {
+    selected.value.delete(id);
+  } else {
+    selected.value.add(id);
+  }
+}
+</script>
+
+<template>
+  <div class="m-auto flex w-[360px] flex-col gap-2">
+    <CdsCard>
+      <CdsVirtualScroll height="260" item-height="40" item-key="id" :items="employees">
+        <template #default="{ item }">
+          <div class="flex h-[40px] items-center justify-between px-2">
+            <CdsCheckbox
+              hide-details
+              :label="item.name"
+              :model-value="selected.has(item.id)"
+              @update:model-value="toggle(item.id)"
+            />
+            <span class="text-100 text-content-secondary">{{ item.department }}</span>
+          </div>
+        </template>
+      </CdsVirtualScroll>
+    </CdsCard>
+
+    <div class="text-100 text-content-secondary">Выбрано получателей: {{ selected.size }}</div>
+  </div>
+</template>
+```

package/skills/cds-builder/references/components/cds-virtual-scroll/guidelines.md

@@ -0,0 +1,9 @@
+# CdsVirtualScroll — 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 short list renders in full — with the regular CdsList, without a nested scroll. | Virtualizing a few rows speeds up nothing, while an extra scroll container hides part of the list. |
+| A search next to a long list leads to the right row in seconds. | Scrolling by hand is the only way to find a record among thousands of rows. |

package/skills/cds-builder/references/components/cds-virtual-scroll/tokens.md

@@ -0,0 +1,13 @@
+# CdsVirtualScroll — 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.
+
+## _CdsVirtualScroll.variables.scss
+
+```scss
+@use '../../../styles/settings';
+
+$virtual-scroll-max-width: 100% !default;
+```

package/skills/cds-builder/references/guides/conventions.md

@@ -0,0 +1,48 @@
+# CDS 4 conventions
+
+The golden rule: **the source of truth is the component's `api.md`**
+(`references/components/<name>/api.md`). Do not invent props, events or
+slots — if they are not in api.md, they do not exist on the component.
+
+## Shared props
+
+The props below come from shared composable factories and behave identically
+in every component that has them:
+
+| Prop | Semantics |
+| --- | --- |
+| `size` | Size: `xs` / `sm` / `md` / `lg` / `xl` or a number |
+| `appearance` | Appearance (visual variant); the set of values is component-specific — check the type in api.md |
+| `color` / `bgColor` | Content / background color as a **theme token**, not a CSS value |
+| `disabled` | Disabled state |
+| `loading` | Loading state |
+| `width` / `height` | Dimensions (number → px, or a CSS value as a string) |
+
+## Tokens, not raw values
+
+- Set colors via the `color` prop / theme tokens (`--cds-color-*`), never
+  arbitrary CSS (`#fff`, `red`). Theme tokens are listed in [../tokens/themes.md](../tokens/themes.md).
+- Spacing, radii and other values in custom SCSS go through the global
+  `--cds-*` variables, never hardcoded.
+
+## Atomic Design
+
+Complex UI is composed from atoms. Example — a form: the ready-made
+`CdsTextInput` "molecule" is internally built as `CdsField` + `CdsLabel` +
+`CdsDescription` + `CdsMessages` + `CdsInput`, and the same atoms are
+available for building your own fields. See the [Forms](forms.md) guide
+for details.
+
+## Defaults
+
+Prop defaults can be set centrally:
+
+- globally — via the `defaults` option in `createCds({ defaults: { CdsButton: { size: 'lg' } } })`;
+- for a subtree — with the `CdsDefaultsProvider` component
+  ([api](../components/cds-defaults-provider/api.md)).
+
+## Deprecated APIs
+
+Props/components marked `_(deprecated)_` in api.md still work but will be
+removed. In the dev console they emit a warning prefixed `[CDS UPGRADE]`.
+When migrating legacy code, see the [migration guide](migration-cds3-to-cds4.md).

package/skills/cds-builder/references/guides/date-utils.md

@@ -0,0 +1,301 @@
+---
+sourceHash: 16f5caa5227fd7ac98a4d370070985a7094a8a2b
+---
+
+# Date Utils
+
+Central Design System includes a set of functions for working with the native JS
+`Date`: mask-based formatting, string parsing, arithmetic, comparison and
+calendar math. You don't need a separate date library (dayjs, date-fns) for
+everyday tasks. The date and time components use the very same functions —
+[CdsDateInput](../components/cds-date-input/api.md), [CdsDatePicker](../components/cds-date-picker/api.md),
+[CdsTimePicker](../components/cds-time-picker/api.md) — so format masks are identical in
+the utilities and in the components.
+
+The functions accept a `Date`, a timestamp (milliseconds) or a date string,
+return a native `Date` and **never mutate** the arguments you pass — the result
+is always a new object.
+
+## Setup
+
+The utilities are exported from the package under the `utils` namespace:
+
+```ts
+import { utils } from '@central-design-system/components';
+
+const { formatDate, addToDate } = utils;
+
+formatDate(new Date(2026, 7, 18), 'DD.MM.YYYY'); // '18.08.2026'
+```
+
+## Formatting — `formatDate`
+
+`formatDate(value, mask, dateLocale?)` turns a date into a string using a mask:
+
+```ts
+const { formatDate } = utils;
+
+formatDate(new Date(2026, 7, 18, 14, 30), 'DD.MM.YYYY HH:mm'); // '18.08.2026 14:30'
+formatDate(Date.now(), 'D MMM YYYY'); // '18 Авг 2026'
+formatDate(new Date(2026, 7, 18), 'dddd'); // 'Вторник'
+```
+
+Without a mask, an ISO-like format is used: `YYYY-MM-DDTHH:mm:ss.SSSZ`.
+For an invalid value the function returns `undefined`.
+
+Month and weekday names come from the Russian date locale by default. To print
+them in another language, pass a date locale as the third argument — the
+built-in ones live in the `locales` export:
+
+```ts
+import { locales, utils } from '@central-design-system/components';
+
+utils.formatDate(new Date(2026, 7, 18), 'dddd, D MMMM', locales.enDate);
+// 'Tuesday, 18 August'
+```
+
+Your own language is plugged in as a `TDateLocale` object — the same fields as
+`locales.ruDate`. See the [Internationalization](internationalization.md#dates)
+guide for more on date locales.
+
+### Format tokens
+
+| Unit | Token | Result |
+| --- | --- | --- |
+| Year | `YY` / `YYYY` | `26` / `2026` |
+| Month | `M` / `MM` | `8` / `08` |
+| Month (name) | `MMM` / `MMMM` | `Авг` / `Август` |
+| Quarter | `Q` / `Qo` | `3` / `3rd` |
+| Day of month | `D` / `Do` / `DD` | `18` / `18th` / `18` |
+| Day of year | `DDD` / `DDDD` | `230` / `230` (zero-padded to 3 digits) |
+| Day of week | `d` | `2` (0 — Sunday) |
+| Day of week (name) | `dd` / `ddd` / `dddd` | `Вт` / `Вт` / `Вторник` |
+| Day of week (ISO) | `E` | `2` (1 — Monday, 7 — Sunday) |
+| Week of year | `w` / `ww` | `34` / `34` |
+| Hour (0–23) | `H` / `HH` | `14` / `14` |
+| Hour (1–12) | `h` / `hh` | `2` / `02` |
+| Minute | `m` / `mm` | `30` / `30` |
+| Second | `s` / `ss` | `5` / `05` |
+| Fractions of a second | `S` / `SS` / `SSS` | `1` / `12` / `123` |
+| Time zone | `Z` / `ZZ` | `+03:00` / `+0300` |
+| Meridiem | `A` / `a` / `aa` | `PM` / `pm` / `p.m.` |
+| Unix time | `X` / `x` | seconds / milliseconds |
+
+Ordinal suffixes (`Do`, `Qo`) are English (`1st`, `2nd`…) regardless of the
+locale.
+
+Arbitrary text inside a mask is escaped with square brackets:
+
+```ts
+formatDate(new Date(2026, 7, 18), '[Сегодня] DD.MM'); // 'Сегодня 18.08'
+```
+
+## Parsing — `extractDate` and `splitDate`
+
+`extractDate(str, mask, dateLocale?)` parses a string with a mask and returns a
+`Date`:
+
+```ts
+const { extractDate } = utils;
+
+extractDate('21.03.1985', 'DD.MM.YYYY'); // Date: 21 March 1985
+extractDate('2019-10-29 23:12', 'YYYY-MM-DD HH:mm'); // Date: 29 October 2019, 23:12
+```
+
+Month and day names inside the string are recognized through the date locale —
+Russian by default, just like in `formatDate`.
+
+A non-existent day overflows following the rules of the native `Date`:
+`extractDate('30.02.2024', 'DD.MM.YYYY')` gives 1 March 2024. When you need
+strict input validation, format the result back and compare it with the string:
+
+```ts
+const strict = (str: string, mask: string) => formatDate(extractDate(str, mask), mask) === str;
+
+strict('18.08.2026', 'DD.MM.YYYY'); // true
+strict('30.02.2024', 'DD.MM.YYYY'); // false — overflowed into 01.03.2024
+```
+
+If you don't need a `Date`, `splitDate(str, mask, dateLocale?)` splits the string
+into its parts — an `IRawDate` object with the fields `year`, `month`, `day`,
+`hour`, `minute`, `second`, `millisecond` (anything not found is `null`):
+
+```ts
+const { splitDate } = utils;
+
+splitDate('18.08.2026', 'DD.MM.YYYY');
+// { year: 2026, month: 8, day: 18, hour: null, … }
+```
+
+## Creating and changing
+
+### `buildDate`
+
+`buildDate(modified, utc?)` — the current moment with individual parts replaced.
+Handy when you need "now, but at 15:00" or "today, but in 2010":
+
+```ts
+const { buildDate } = utils;
+
+buildDate({ year: 2010, day: 5, hour: 15 });
+// current month, minutes and seconds; year 2010, day 5, hour 15
+```
+
+Supported object fields: `year`, `month` (1–12), `day` (or `date`), `hour`,
+`minute`, `second`, `millisecond`.
+
+### `adjustDate`
+
+`adjustDate(date, modified, utc?)` — the same thing, but for an arbitrary date:
+
+```ts
+const { adjustDate } = utils;
+
+adjustDate(new Date(2026, 10, 2), { year: 2010, month: 2 });
+// Date: 2 February 2010
+```
+
+Note that `month` here is 1-based (February is `2`), unlike in the `Date`
+constructor.
+
+### `addToDate` / `subtractFromDate`
+
+Add and subtract intervals. The object fields are the same, but they mean "how
+much to add" rather than "what to set":
+
+```ts
+const { addToDate, subtractFromDate } = utils;
+
+addToDate(new Date(2026, 2, 7), { day: 7, month: 1 }); // Date: 14 April 2026
+subtractFromDate(new Date(2026, 2, 7), { hour: 24 }); // Date: 6 March 2026
+```
+
+### `startOfDate` / `endOfDate`
+
+The start and the end of a period — year, month, day, hour, minute or second:
+
+```ts
+const { startOfDate, endOfDate } = utils;
+
+startOfDate(new Date(2026, 7, 18, 14, 30), 'year'); // Date: 1 January 2026, 00:00:00.000
+endOfDate(new Date(2026, 7, 18, 14, 30), 'month'); // Date: 31 August 2026, 23:59:59.999
+```
+
+Period unit: `'year'`, `'month'`, `'day'`, `'hour'`, `'minute'`, `'second'`
+(the plural form is accepted too).
+
+## Comparison and ranges
+
+### `isSameDate`
+
+Compares dates down to a unit: `'year'` — the year only, `'month'` — month and
+year, `'day'` — the calendar day, and so on. Without a unit, the timestamps are
+compared in full.
+
+```ts
+const { isSameDate } = utils;
+
+isSameDate(new Date(2026, 7, 1), new Date(2026, 7, 30), 'month'); // true
+isSameDate(new Date(2026, 7, 1), new Date(2026, 7, 30), 'day'); // false
+```
+
+### `getDateDiff`
+
+The difference between two dates in the chosen unit (days by default):
+
+```ts
+const { getDateDiff } = utils;
+
+getDateDiff(new Date(2026, 4, 12), new Date(2026, 3, 8)); // 34 (days)
+getDateDiff(new Date(2026, 4, 12), new Date(2026, 3, 8), 'months'); // 1
+```
+
+### `isBetweenDates` / `getDateBetween`
+
+`isBetweenDates(date, from, to, opts?)` checks whether a date falls inside a
+range. The bounds are excluded by default; the `inclusiveFrom` and `inclusiveTo`
+options include them, and `onlyDate: true` compares calendar days only, ignoring
+the time:
+
+```ts
+const { isBetweenDates } = utils;
+
+isBetweenDates(date, from, to); // strict range
+isBetweenDates(date, from, to, { inclusiveFrom: true, inclusiveTo: true, onlyDate: true });
+```
+
+`getDateBetween(date, min, max)` clamps a date to a range: it returns the date
+itself if it is inside, otherwise the nearest bound:
+
+```ts
+const { getDateBetween } = utils;
+
+getDateBetween(new Date(2025, 0, 1), new Date(2026, 0, 1), new Date(2026, 11, 31));
+// Date: 1 January 2026 — the date is below the minimum, so the min bound came back
+```
+
+### `getMinDate` / `getMaxDate`
+
+The smallest and the largest of a set of dates. They return a timestamp (number) —
+wrap it in `new Date()` if you need a date object:
+
+```ts
+const { getMinDate, getMaxDate } = utils;
+
+const min = getMinDate(new Date(2026, 6, 24), new Date(2026, 5, 20), new Date(2026, 6, 26));
+new Date(min); // Date: 20 June 2026
+
+const dates = [/* Date[] */];
+const max = getMaxDate(dates[0], ...dates.slice(1));
+```
+
+## Calendar
+
+```ts
+const { getDayOfWeek, getWeekOfYear, getDayOfYear, daysInMonth } = utils;
+
+getDayOfWeek(new Date(2026, 7, 16)); // 7 — Sunday (ISO: 1 — Monday)
+getWeekOfYear(new Date(2026, 0, 4)); // 1 — ISO week number in the year
+getDayOfYear(new Date(2026, 1, 4)); // 35 — ordinal day in the year
+daysInMonth(new Date(2024, 1, 15)); // 29 — February of a leap year
+```
+
+## Other
+
+### `isValidDate`
+
+Checks whether a value parses into a date:
+
+```ts
+const { isValidDate } = utils;
+
+isValidDate('2026-08-18'); // true
+isValidDate('не дата'); // false
+```
+
+The check is syntactic — it does not catch non-existent calendar days
+(see `splitDate` above).
+
+### `cloneDate`
+
+A copy of a date. Useful before handing it to third-party code that might mutate
+the object (CDS utilities themselves never modify their arguments):
+
+```ts
+const { cloneDate } = utils;
+
+const copy = cloneDate(original);
+```
+
+### `inferDateFormat`
+
+Detects the shape of a value — handy for returning the result in the same form
+the value came in:
+
+```ts
+const { inferDateFormat } = utils;
+
+inferDateFormat(new Date()); // 'date'
+inferDateFormat(1787059805000); // 'number'
+inferDateFormat('18.08.2026'); // 'string'
+```