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

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

@@ -0,0 +1,172 @@
+---
+sourceHash: 5822739245a9c6095f09064c0b58dc326ac5c188
+---
+
+# Icons
+
+CDS v4 supports many popular icon packs out of the box.
+
+## Usage
+
+You can pick one of the ready-made icon packs or plug in your own.
+By default CDS uses the `cds` pack — it contains every icon the design system
+components need.
+
+```ts
+import { createCds } from '@central-design-system/components';
+
+const cds = createCds({
+  icons: {
+    defaultSet: 'cds'
+  },
+});
+
+app.use(cds);
+```
+
+After that, use the icon in templates:
+
+```html
+<template>
+  <CdsIcon icon="add" />
+</template>
+```
+
+## Installing icon packs through UnoCSS
+
+CDS integrates with [UnoCSS Preset Icons](https://unocss.dev/presets/icons), which
+supports every icon pack available on [Iconify](https://icon-sets.iconify.design/).
+
+Icons are tree-shaken, so only the icons you actually use end up in the final CSS
+bundle. You can register several packs at once and freely mix icons from any of
+them in your components.
+
+### Icon packs
+
+For the packs listed below, CDS ships iconsets with alias mappings — aliases for
+the icons CDS components use (checkboxes, dropdowns, radio buttons and so on).
+Pick one of them as the default pack (`defaultSet`); the alias mappings can be
+overridden if needed.
+Additional packs — without aliases — can be plugged in alongside and used freely
+in your own templates.
+
+| Icon library                                                     | Iconify package        | Iconset import                                            | Set name   |
+|------------------------------------------------------------------|------------------------|-----------------------------------------------------------|------------|
+| [Remix Icon](https://remixicon.com/)                             | `@iconify-json/ri`     | `@central-design-system/components/iconsets/remix`        | `ri`       |
+| [Phosphor Icons](https://phosphoricons.com/)                     | `@iconify-json/ph`     | `@central-design-system/components/iconsets/phosphor`     | `phosphor` |
+| [Lucide](https://lucide.dev/)                                    | `@iconify-json/lucide` | `@central-design-system/components/iconsets/lucide`       | `lucide`   |
+| [Carbon](https://carbondesignsystem.com/elements/icons/library/) | `@iconify-json/carbon` | `@central-design-system/components/iconsets/carbon`       | `carbon`   |
+| [Material Design Icons](https://pictogrammers.com/library/mdi/)  | `@iconify-json/mdi`    | `@central-design-system/components/iconsets/mdi`          | `mdi`      |
+
+Each module exports an object named after the pack: `icons` (the pack itself, for
+`sets`) and `aliases` (the aliases, for `aliases`).
+
+Install the pack you need from the table above:
+
+```bash
+npm install @iconify-json/ri
+```
+
+> Icons from the table run through UnoCSS, so you have to install and configure
+> UnoCSS first. See the [official documentation](https://unocss.dev/integrations/)
+> for details.
+
+Here is an example integration in a Vite project.
+
+1. Install UnoCSS as a dev dependency (see the [Vite integration](https://unocss.dev/integrations/vite)):
+
+```bash
+npm install -D unocss
+```
+
+2. Add the UnoCSS plugin to your Vite config:
+
+```ts
+// vite.config.ts
+import UnoCSS from 'unocss/vite'
+import { defineConfig } from 'vite'
+
+export default defineConfig({
+  plugins: [
+    UnoCSS(),
+  ],
+})
+```
+
+3. Create an **unocss.config.ts** file in the project root:
+
+```ts
+// unocss.config.ts
+import { presetIcons, defineConfig } from 'unocss'
+
+export default defineConfig({
+  presets: [
+    presetIcons({
+      processor(props) {
+        delete props.color
+      },
+    }),
+  ],
+})
+```
+
+> Nothing else needs to go into `unocss.config.ts`: CDS iconsets carry the
+> `@unocss-include` marker, so UnoCSS scans them on its own — even though they
+> live in `node_modules` as `.js` files, which are not part of
+> `content.pipeline.include` by default.
+
+4. Pass the icon pack to `createCds()`.
+The example uses the **[Remix](https://remixicon.com/)** pack, but you can swap it
+for any other pack from the table above:
+
+```ts
+import { createCds } from '@central-design-system/components';
+import { remix } from '@central-design-system/components/iconsets/remix';
+
+const cds = createCds({
+  icons: {
+    defaultSet: 'remix',
+    aliases: remix.aliases,
+    sets: {
+      remix: remix.icons,
+    }
+  },
+});
+
+app.use(cds);
+```
+
+> Import the pack through the `@central-design-system/components/iconsets/<pack>`
+> subpath, not from the shared `iconsets` object. The shared object references all
+> packs at once and is not tree-shaken — you would ship the JS and CSS of all five
+> packs (≈370 KB instead of ≈70 KB for a single one).
+
+After that, pick any icon from the pack — for example
+[ri:settings-3-line](https://icon-sets.iconify.design/ri/?icon-filter=settings-3-line) —
+and use it in templates:
+
+```html
+<CdsButton icon="i-ri:settings-3-line" />
+```
+
+> UnoCSS uses the `i-` prefix for icons. CDS uses the same prefix and already
+> configures its aliases with it — don't change it, or the CDS aliases will stop
+> working.
+
+## Legacy icon pack from CDS v3
+
+If you need the full icon pack from CDS v3, plug it in like this:
+
+```bash
+npm install @central-design-system/icons
+```
+
+```ts
+import { icons } from '@central-design-system/icons';
+
+const cds = createCds({
+  icons
+});
+
+app.use(cds);
+```

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

@@ -0,0 +1,470 @@
+---
+sourceHash: 26c790bd53cd55729b9902cf5d1032b5c6457f6b
+---
+
+# Internationalization (i18n)
+
+CDS components carry texts of their own: "No data available" in a select, the
+table filter labels, the `aria-label` of a close button, the file counter. They
+all go through the built-in localization layer, so you can translate them into
+another language, override a single string for your product, or switch languages
+on the fly — without rewriting components.
+
+The library ships two dictionaries — Russian and English. `ru` is active by
+default, so out of the box everything is in Russian.
+
+## Setup
+
+The locale is configured through the `locale` option of `createCds`. Switching to
+the built-in English is a one-liner — you don't need to pass any dictionaries:
+
+```ts
+import { createApp } from 'vue';
+import '@central-design-system/components/styles';
+import { createCds, components, directives } from '@central-design-system/components';
+
+import App from './App.vue';
+
+const cds = createCds({
+  components,
+  directives,
+  locale: {
+    locale: 'en'
+  }
+});
+
+createApp(App).use(cds);
+```
+
+Languages the library doesn't have are added as a dictionary in `messages`:
+
+```ts
+import de from './locales/cds-de';
+
+createCds({
+  components,
+  directives,
+  locale: {
+    locale: 'de',
+    fallback: 'en',
+    messages: { de }
+  }
+});
+```
+
+| Option             | Type                      | Purpose                                                                       |
+| ------------------ | ------------------------- | ----------------------------------------------------------------------------- |
+| `locale`           | `string`                  | Active language; `ru` (default) and `en` are available out of the box          |
+| `fallback`         | `string`                  | Language a string is taken from when the active one lacks it; `ru` by default  |
+| `messages`         | `LocaleMessages`          | Dictionaries of extra languages; a same-named built-in dictionary is replaced entirely |
+| `decimalSeparator` | `string`                  | Decimal separator; derived from the active locale by default                   |
+| `rtl`              | `Record<string, boolean>` | Map of right-to-left languages (see [RTL](#rtl))                               |
+| `adapter`          | `LocaleInstance`          | Your own translation engine instead of the built-in one (see [Custom adapter](#custom-adapter)) |
+
+The built-in dictionaries are available to you as well — they live in the
+`locales` export. Use them as a base for your own language or to fix a couple of
+strings:
+
+```ts
+import { locales } from '@central-design-system/components';
+
+locales.ru; // Russian dictionary
+locales.en; // English dictionary
+```
+
+For the full set of keys, see [Message keys](#message-keys).
+
+## How components get their text
+
+Component strings are keys prefixed with `$cds.` that the library runs through a
+translation function. Some of the keys are declared as default prop values, so
+you can see them in the API: `text` on `CdsFileUpload` is `$cds.fileUpload.browse`,
+`closeLabel` on `CdsNotification` is `$cds.close`, `noDataText` on `CdsSelect` is
+`$cds.noDataText`.
+
+That gives you three ways to change a text.
+
+**Switch the whole language** — with the `locale` option:
+
+```ts
+createCds({ locale: { locale: 'en' } });
+```
+
+**Change wording across the product** — with a dictionary on top of the built-in
+one:
+
+```ts
+import { createCds, locales } from '@central-design-system/components';
+
+createCds({
+  locale: {
+    messages: {
+      en: { ...locales.en, noDataText: 'Nothing found' }
+    }
+  }
+});
+```
+
+**Important.** A language dictionary is replaced entirely, not merged key by key.
+Without the `...locales.en` spread, the English locale is left with a single key
+and the rest of the strings turn into their own keys (`$cds.close` instead of
+"Close"). Spread nested sections separately:
+`table: { ...locales.en.table, emptyText: '…' }`.
+
+**Change one label in one place** — with a prop:
+
+```vue
+<CdsSelect :items="items" no-data-text="No matching suppliers" />
+```
+
+The same prop can be set as the default for every instance of the component — see
+[global configuration](global-configuration.md):
+
+```ts
+createCds({
+  defaults: {
+    CdsSelect: { noDataText: 'Nothing found' }
+  }
+});
+```
+
+The translation function also accepts plain text: a string without the `$cds.`
+prefix is returned as is, with the parameters substituted. That's how props with
+a localizable value work the same way with a key and with a ready-made phrase.
+
+If a key is missing from both the active locale and the `fallback`, the component
+shows the key itself, and in dev mode a
+`[CDS: useLocale] Translation key … not found` warning appears in the console.
+
+## Switching the language at runtime
+
+`createCds` returns an instance whose locale lives in reactive refs — to switch
+languages, just write to `current`:
+
+```ts
+const cds = createCds({ components, directives });
+
+// for example, following the user's choice in profile settings
+cds.locale.current.value = 'en';
+```
+
+Inside components, the `useLocale` composable does the same:
+
+```vue
+<script setup lang="ts">
+import { CdsButton, CdsButtonToggle, useLocale } from '@central-design-system/components';
+
+const { current } = useLocale();
+</script>
+
+<template>
+  <CdsButtonToggle v-model="current" appearance="tertiary">
+    <CdsButton value="ru" text="Русский" />
+    <CdsButton value="en" text="English" />
+  </CdsButtonToggle>
+</template>
+```
+
+Every mounted component recalculates its strings on its own — no page reload
+needed.
+
+## A locale for part of the application
+
+A single subtree can get its own language — for example, an English-language
+widget inside a Russian interface. Call `provideLocale` in a wrapper component:
+it takes the locale from the context, applies the props you passed and provides
+the result to the children.
+
+```vue
+<script setup lang="ts">
+import { provideLocale } from '@central-design-system/components';
+
+const props = defineProps<{ locale?: string; fallback?: string }>();
+
+provideLocale(props);
+</script>
+
+<template>
+  <div>
+    <slot />
+  </div>
+</template>
+```
+
+```vue
+<template>
+  <LocaleProvider locale="en">
+    <CdsSelect :items="items" />
+  </LocaleProvider>
+</template>
+```
+
+Props you don't pass are inherited from the parent locale, so a wrapper with just
+a `locale` loses neither the `fallback` nor the dictionaries.
+
+## useLocale
+
+The composable hands you the current locale and its functions — use it in your
+own components so their texts live in the same dictionaries as the CDS ones.
+
+```vue
+<script setup lang="ts">
+import { useLocale } from '@central-design-system/components';
+
+const { t, n } = useLocale();
+</script>
+
+<template>
+  <p>{{ t('$cds.table.emptyText') }}</p>
+  <p>{{ n(1234.56) }}</p>
+</template>
+```
+
+| Property           | Type                                           | Purpose                                                       |
+| ------------------ | ---------------------------------------------- | ------------------------------------------------------------- |
+| `t`                | `(key: string, ...params: unknown[]) => string` | Translation of a `$cds.…` key with parameter substitution      |
+| `n`                | `(value: number) => string`                    | Number formatting for the active locale                        |
+| `current`          | `Ref<string>`                                  | Active language; writing to it switches the language           |
+| `fallback`         | `Ref<string>`                                  | Fallback language                                              |
+| `messages`         | `Ref<LocaleMessages>`                          | Dictionaries; can be extended at runtime                       |
+| `decimalSeparator` | `ShallowRef<string>`                           | Decimal separator of the active locale                         |
+
+Parameters in strings are numbered — `{0}`, `{1}`:
+
+```ts
+const { t } = useLocale();
+
+t('$cds.carousel.delimiter', 3, 8); // "Slide 3 of 8"
+t('Days left: {0}', 5); // "Days left: 5"
+```
+
+Under the hood `n` is `Intl.NumberFormat` with the active locale and the
+`fallback`, so group and decimal separators come from the browser. The library
+derives `decimalSeparator` from the same locale (`,` for `ru`, `.` for `en`); if
+your product uses a different one, set it explicitly in `createCds`.
+
+## Dates
+
+Month and weekday names live in separate date locales, shipped by `ru` and `en`.
+Date and time components pick the date locale by the active language, so after
+`current.value = 'en'` the calendar switches by itself.
+
+A single component gets its language from the `locale` prop — `CdsDatePicker`,
+`CdsDateInput` and `CdsTimePicker` all have it:
+
+```vue
+<CdsDatePicker v-model="value" locale="en" :first-day-of-week="0" header />
+```
+
+The prop accepts not only a language name but also your own date locale object
+(type `TDateLocale`) — that's how you plug in a language the library doesn't
+have. The built-in date locales, for reference and reuse, live in the same
+`locales` export: `locales.ruDate`, `locales.enDate` and the `locales.dateLocales`
+map.
+
+```ts
+const de = {
+  days: 'Sonntag_Montag_Dienstag_Mittwoch_Donnerstag_Freitag_Samstag'.split('_'),
+  daysShort: 'So_Mo_Di_Mi_Do_Fr_Sa'.split('_'),
+  months: 'Januar_Februar_März_April_Mai_Juni_Juli_August_September_Oktober_November_Dezember'.split('_'),
+  monthsLong: 'Januar_Februar_März_April_Mai_Juni_Juli_August_September_Oktober_November_Dezember'.split('_'),
+  monthsShort: 'Jan_Feb_Mär_Apr_Mai_Jun_Jul_Aug_Sep_Okt_Nov_Dez'.split('_'),
+  today: 'Heute',
+  now: 'Jetzt',
+  firstDayOfWeek: 1,
+  format24h: true,
+  pluralDay: (day = 0) => (day === 1 ? 'Tag' : 'Tage')
+};
+```
+
+```vue
+<CdsDatePicker v-model="value" :locale="de" />
+```
+
+## Table
+
+`CdsTable` builds its labels from the `$cds.table.*` keys, but it also accepts a
+pinpoint override through the `locale` prop — which replaces only the strings you
+pass:
+
+```vue
+<CdsTable :columns="columns" :data="data" :locale="{ emptyText: 'No requests yet' }" />
+```
+
+## RTL
+
+Right-to-left languages are described by the `rtl` map: the key is the language,
+the value is the direction.
+
+```ts
+createCds({
+  locale: {
+    locale: 'ar',
+    messages: { ar },
+    rtl: { ar: true }
+  }
+});
+```
+
+Components read the direction through `useRtl` and flip whatever depends on the
+axis: the side menus and tooltips open to, the pagination arrows, the cell order
+in `CdsOtpInput`, the fill of `CdsProgressBar`. Spacing and borders in the styles
+are mostly written with logical properties (`margin-inline`, `inset-inline`) and
+are mirrored by the browser itself — but the design system does not claim full
+RTL support yet, and some places will need polishing on your side.
+
+The library does not set the direction attribute for you — put it on the
+application root yourself:
+
+```vue
+<script setup lang="ts">
+import { useRtl } from '@central-design-system/components';
+
+const { isRtl } = useRtl();
+</script>
+
+<template>
+  <div :dir="isRtl ? 'rtl' : 'ltr'">
+    <slot />
+  </div>
+</template>
+```
+
+`useRtl` gives you `isRtl` and `rtlClasses` — a ready `cds-locale--is-rtl` /
+`cds-locale--is-ltr` class for your own styles.
+
+## Custom adapter
+
+If your application already has an i18n library, hand the translations over to
+it: the `adapter` option accepts any object implementing the `LocaleInstance`
+interface. In that case `messages`, `locale` and `fallback` from `createCds` are
+unused — your engine becomes the source of truth, and the CDS strings live in the
+application's shared dictionaries under the `$cds` key.
+
+```ts
+import type { LocaleInstance, LocaleOptions } from '@central-design-system/components';
+import { toRef } from 'vue';
+import type { I18n } from 'vue-i18n';
+
+export function createVueI18nAdapter(i18n: I18n<any, any, any, string, false>): LocaleInstance {
+  const format = (value: number) => i18n.global.n(value);
+
+  return {
+    name: 'vue-i18n',
+    current: i18n.global.locale,
+    fallback: i18n.global.fallbackLocale as never,
+    messages: i18n.global.messages as never,
+    decimalSeparator: toRef(() => (format(0.1).includes(',') ? ',' : '.')),
+    t: (key, ...params) => i18n.global.t(key, params as never),
+    n: format,
+    provide: () => createVueI18nAdapter(i18n)
+  };
+}
+```
+
+```ts
+import { createI18n } from 'vue-i18n';
+
+const i18n = createI18n({
+  legacy: false,
+  locale: 'en',
+  messages: {
+    en: {
+      $cds: { noDataText: 'No data available' },
+      profile: { title: 'Profile' }
+    }
+  }
+});
+
+const cds = createCds({
+  components,
+  directives,
+  locale: {
+    adapter: createVueI18nAdapter(i18n)
+  }
+});
+```
+
+Required members of `LocaleInstance`: `name` (that's how the adapter is
+recognized), `current`, `fallback`, `messages`, `decimalSeparator`, `t`, `n` and
+`provide` — a factory for a nested locale, used by `provideLocale`. If you don't
+need "a locale in a subtree", `provide` can return the same instance, as in the
+example above.
+
+## Message keys
+
+The built-in English dictionary is a template for translating into a new
+language. Copy it, translate the values and pass it to `messages` under your
+language's key; the Russian version is available as `locales.ru`.
+
+```ts
+export default {
+  badge: 'Badge',
+  noDataText: 'No data available',
+  selectAll: 'Select all',
+  close: 'Close',
+  open: 'Open',
+  dismiss: 'Dismiss',
+  confirmEdit: {
+    ok: 'OK',
+    cancel: 'Cancel'
+  },
+  carousel: {
+    prev: 'Previous slide',
+    next: 'Next slide',
+    delimiter: 'Slide {0} of {1}'
+  },
+  input: {
+    clear: 'Clear {0}',
+    otp: 'Please enter OTP character',
+    prependAction: '{0} prepended action',
+    appendAction: '{0} appended action'
+  },
+  fileInput: {
+    counter: '{0} files',
+    counterSize: '{0} files ({1} in total)'
+  },
+  fileUpload: {
+    title: 'Drag and drop files here',
+    divider: 'or',
+    browse: 'Browse files'
+  },
+  steps: {
+    prev: 'Back',
+    next: 'Next'
+  },
+  table: {
+    filterTitle: 'Filter menu',
+    filterConfirm: 'OK',
+    filterReset: 'Reset',
+    filterEmptyText: 'No filters',
+    filterCheckAll: 'Select all items',
+    filterSearchPlaceholder: 'Search in filters',
+    emptyText: 'No data',
+    selectAll: 'Select current page',
+    selectInvert: 'Invert current page',
+    selectNone: 'Clear all data',
+    selectionAll: 'Select all data',
+    sortTitle: 'Sort',
+    expand: 'Expand row',
+    collapse: 'Collapse row',
+    triggerDesc: 'Click to sort descending',
+    triggerAsc: 'Click to sort ascending',
+    cancelSort: 'Click to cancel sorting',
+    showed: 'Showed',
+    from: 'from',
+    rowOnPage: 'Row on page'
+  },
+  uploader: {
+    uploading: 'Uploading...',
+    uploadFile: 'Upload file',
+    downloadFile: 'Download file',
+    removeFile: 'Remove file',
+    uploadError: 'Upload error',
+    previewFile: 'Preview file'
+  }
+};
+```
+
+The dictionary may stay incomplete: missing keys are taken from the `fallback` —
+that is, from Russian by default.

package/skills/cds-builder/references/guides/migration-cds3-to-cds4.md

@@ -0,0 +1,49 @@
+# CDS 3 → CDS 4 migration (digest)
+
+This is a short digest. **The full version with Before/After for every
+change is `MIGRATION.md` at the root of the
+`@central-design-system/components` npm package.**
+
+## Severity legend
+
+| Marker | Meaning |
+| --- | --- |
+| ⚠️ **BREAKING** | Breaks existing code — action required |
+| 🔁 **RENAMED** | Rename — mechanical search & replace |
+| 🟠 **DEPRECATED** | Works in 4.x, will be removed in 5.x |
+| ✨ **NEW** | New capability, nothing breaks |
+
+## Quick checklist
+
+- [ ] Replace the CSS import: `@central-design-system/components/dist/cds.css` →
+      `@central-design-system/components/styles` (⚠️ breaking).
+- [ ] If you use `@central-design-system/icons` — the package is 🟠 deprecated;
+      switch to iconpacks via `createCds({ icons })` (see [setup.md](setup.md)).
+- [ ] Go through the component rename index below.
+- [ ] Run the build and check the dev console: `[CDS UPGRADE]` warnings
+      point at deprecated props.
+
+## Key breaking changes
+
+- ⚠️ **CSS import path** — `dist/cds.css` is no longer a public entry point;
+  import `@central-design-system/components/styles` instead.
+- ⚠️ **Legacy reset is off by default** — the global reset from CDS 3 is now
+  opt-in: `@use '@central-design-system/components/styles' with ($legacy-reset: true);`.
+- ⚠️ **CSS architecture on ITCSS + CSS Layers** — the cascade is driven by
+  native `@layer`; global overrides of CDS styles without `!important` may
+  now resolve differently.
+
+## Component rename and removal index
+
+| CDS 3 | CDS 4 |
+| --- | --- |
+| `CdsDropdown` | 🔁 `CdsSelect` (the native `<select>` from CDS 3 — via the `native-select` prop) |
+| `CdsRadioButton` | 🔁 `CdsRadioGroup` |
+| `CdsProgress` | 🔁 `CdsProgressBar` |
+| `CdsTabsV2` | 🔁 `CdsTabs` |
+| `CdsCheckboxGroup` | ⚠️ removed (use `CdsCheckbox` on its own) |
+| `CdsContainer` | ⚠️ removed |
+| `CdsBadge` | 🔁 props: `count`→`content`, `limited`→`:max`; ⚠️ `invertColor` removed |
+
+After renaming, double-check the `api.md` of the new component in
+`../components/` — prop contracts may have changed.