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

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

@@ -0,0 +1,202 @@
+# CdsField — 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.
+
+The frame of an input: the background, the border, the focus and error states, the inner icons, the clear button and the loading indicator. You put the control itself into the `default` slot — the text fields, selects and autocompletes of the design system are built on `CdsField`.
+
+## Icons
+
+The `prepend-inner-icon` and `append-inner-icon` props put an icon inside the frame — before and after the control. The same areas are available as the `prepend-inner` and `append-inner` slots when you need a button rather than an icon.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsField } from '@central-design-system/components';
+import { ref } from 'vue';
+
+const query = ref('');
+</script>
+
+<template>
+  <div class="w-[320px] m-auto">
+    <CdsField
+      v-slot="{ props: fieldProps, focus, blur }"
+      prepend-inner-icon="search"
+      append-inner-icon="settings"
+      :dirty="!!query"
+    >
+      <input v-bind="fieldProps" v-model="query" placeholder="Поиск по заявкам" @focus="focus" @blur="blur" />
+    </CdsField>
+  </div>
+</template>
+```
+
+## Clearing
+
+The `clearable` prop adds a cross; it shows up when the field is marked `dirty` and appears on hover or focus. The `persistent-clearable` prop keeps the cross visible at all times. The value is reset not by the component but by you — in the `@click:clear` handler.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsField } from '@central-design-system/components';
+import { ref } from 'vue';
+
+const onHover = ref('Видна при наведении');
+const persistent = ref('Видна всегда');
+</script>
+
+<template>
+  <div class="flex flex-col gap-2 w-[320px] m-auto">
+    <CdsField v-slot="{ props: fieldProps, focus, blur }" clearable :dirty="!!onHover" @click:clear="onHover = ''">
+      <input v-bind="fieldProps" v-model="onHover" @focus="focus" @blur="blur" />
+    </CdsField>
+
+    <CdsField
+      v-slot="{ props: fieldProps, focus, blur }"
+      clearable
+      persistent-clearable
+      :dirty="!!persistent"
+      @click:clear="persistent = ''"
+    >
+      <input v-bind="fieldProps" v-model="persistent" @focus="focus" @blur="blur" />
+    </CdsField>
+  </div>
+</template>
+```
+
+## States
+
+The `disabled`, `readonly` and `error` props change the color of the frame and of the text. Set the state of the control inside separately: `CdsField` draws the frame but does not control your `input`.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsField } from '@central-design-system/components';
+</script>
+
+<template>
+  <div class="flex flex-col gap-2 w-[320px] m-auto">
+    <CdsField v-slot="{ props: fieldProps }">
+      <input v-bind="fieldProps" value="Обычное поле" readonly />
+    </CdsField>
+
+    <CdsField v-slot="{ props: fieldProps }" disabled>
+      <input v-bind="fieldProps" value="Заблокировано" disabled />
+    </CdsField>
+
+    <CdsField v-slot="{ props: fieldProps }" readonly>
+      <input v-bind="fieldProps" value="Только для чтения" readonly />
+    </CdsField>
+
+    <CdsField v-slot="{ props: fieldProps }" error>
+      <input v-bind="fieldProps" value="Ошибка" readonly />
+    </CdsField>
+  </div>
+</template>
+```
+
+## Loading
+
+The `loading` prop shows a bar under the field. The `circle` value replaces it with a circular indicator inside the frame — handier when the field waits for a server response while typing.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsField } from '@central-design-system/components';
+</script>
+
+<template>
+  <div class="flex flex-col gap-3 w-[320px] m-auto">
+    <CdsField v-slot="{ props: fieldProps }" loading>
+      <input v-bind="fieldProps" value="Полоса под полем" readonly />
+    </CdsField>
+
+    <CdsField v-slot="{ props: fieldProps }" loading="circle">
+      <input v-bind="fieldProps" value="Индикатор внутри поля" readonly />
+    </CdsField>
+  </div>
+</template>
+```
+
+## Sizes
+
+The `size` prop changes the height of the frame and its inner paddings. The default size is `md`.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsField } from '@central-design-system/components';
+
+const sizes = ['xs', 'sm', 'md', 'lg', 'xl'] as const;
+</script>
+
+<template>
+  <div class="flex flex-col gap-2 w-[320px] m-auto">
+    <CdsField v-for="size of sizes" :key="size" v-slot="{ props: fieldProps }" :size="size">
+      <input v-bind="fieldProps" :value="'Размер ' + size" readonly />
+    </CdsField>
+  </div>
+</template>
+```
+
+## A field with tags
+
+The control in the `default` slot is any markup you like, so a set of tags and an input for a new entry fit inside the frame. The `focus` and `blur` handlers from the slot turn the highlighting of the frame on, `dirty` shows the cross, and `@click:clear` empties the list.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsField, CdsTag } from '@central-design-system/components';
+import { ref } from 'vue';
+
+const tags = ref(['Канцелярия', 'Мебель']);
+const draft = ref('');
+
+function addTag() {
+  const value = draft.value.trim();
+  if (!value) return;
+
+  tags.value = [...tags.value, value];
+  draft.value = '';
+}
+</script>
+
+<template>
+  <div class="w-[350px] m-auto">
+    <CdsField
+      v-slot="{ props: fieldProps, focus, blur }"
+      prepend-inner-icon="category"
+      clearable
+      :dirty="!!tags.length"
+      @click:clear="tags = []"
+    >
+      <div v-bind="fieldProps">
+        <CdsTag
+          v-for="tag of tags"
+          :key="tag"
+          size="sm"
+          :text="tag"
+          closable
+          @click:close="tags = tags.filter((item) => item !== tag)"
+        />
+
+        <input
+          v-model="draft"
+          class="flex-1 min-w-[80px] bg-transparent outline-none"
+          placeholder="Добавить категорию"
+          @focus="focus"
+          @blur="blur"
+          @keydown.enter.prevent="addTag"
+        />
+      </div>
+    </CdsField>
+  </div>
+</template>
+```

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

@@ -0,0 +1,94 @@
+# CdsField — 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.
+
+## _CdsField.variables.scss
+
+```scss
+@use 'sass:map';
+@use '../../../styles/tools';
+@use '../../../styles/settings';
+
+// ======================= Variables =======================
+$field-input-border-size: var(--cds-border-100) solid !default;
+$field-input-border-radius: var(--cds-border-radius-200) !default;
+$field-input-shadow-border-size: 2px;
+$field-input-shadow-border-opacity: 0.2;
+$field-input-row-gap: var(--cds-spacing-50) !default;
+$field-input-clearable-margin: var(--cds-spacing-200) !default;
+$field-input-loader-circle-margin: var(--cds-spacing-200) !default;
+$field-input-transition: tools.$cds-duration-fast + ms settings.$standard-easing !default;
+
+
+// ======================= Colors =======================
+$field-control-color: (
+  default: (
+    'background': rgb(var(--cds-color-fill-primary)),
+    'content': rgb(var(--cds-color-content-primary)),
+    'border': rgb(var(--cds-color-line-primary)),
+    'placeholder': rgb(var(--cds-color-content-tertiary)),
+  ),
+  hover: (
+    'border': rgb(var(--cds-color-line-primary-hover))
+  ),
+  focus: (
+    'border': rgb(var(--cds-color-line-focus))
+  ),
+  error: (
+    'border': rgb(var(--cds-color-status-danger-line)),
+    'content': rgb(var(--cds-color-status-danger-content)),
+    'placeholder': rgb(var(--cds-color-status-danger-content)),
+  ),
+  disabled: (
+    'background': rgb(var(--cds-color-fill-disable)),
+    'border': rgb(var(--cds-color-line-disable)),
+    'content': rgb(var(--cds-color-content-disable))
+  ),
+) !default;
+
+// ======================= Sizes =======================
+$field-control-sizes: (
+  xs: (
+    'min-height': calc(tools.to-rem(24px) - var(--cds-border-200)),
+    'padding-inline': var(--cds-spacing-200),
+    'padding-block': 0,
+    'affixed-padding': var(--cds-spacing-200),
+    'affixed-inner-padding': var(--cds-spacing-100),
+    'loader-circle-size': tools.to-rem(12px),
+  ),
+  sm: (
+    'min-height': calc(tools.to-rem(28px) - var(--cds-border-200)),
+    'padding-inline': var(--cds-spacing-200),
+    'padding-block': 0,
+    'affixed-padding': var(--cds-spacing-200),
+    'affixed-inner-padding': var(--cds-spacing-100),
+    'loader-circle-size': tools.to-rem(14px),
+  ),
+  md: (
+    'min-height': calc(tools.to-rem(32px) - var(--cds-border-200)),
+    'padding-inline': var(--cds-spacing-300),
+    'padding-block': var(--cds-spacing-100),
+    'affixed-padding': var(--cds-spacing-300),
+    'affixed-inner-padding': var(--cds-spacing-200),
+    'loader-circle-size': tools.to-rem(16px),
+  ),
+  lg: (
+    'min-height': calc(tools.to-rem(36px) - var(--cds-border-200)),
+    'padding-inline': var(--cds-spacing-300),
+    'padding-block': 0,
+    'affixed-padding': var(--cds-spacing-300),
+    'affixed-inner-padding': var(--cds-spacing-200),
+    'loader-circle-size': tools.to-rem(20px),
+  ),
+  xl: (
+    'min-height': calc(tools.to-rem(40px) - var(--cds-border-200)),
+    'padding-inline': var(--cds-spacing-400),
+    'padding-block': 0,
+    'affixed-padding': var(--cds-spacing-300),
+    'affixed-inner-padding': var(--cds-spacing-200),
+    'loader-circle-size': tools.to-rem(24px),
+  )
+) !default;
+```

package/skills/cds-builder/references/components/cds-file-input/api.md

@@ -0,0 +1,109 @@
+# CdsFileInput — 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 file field: the user attaches documents by a click, by dragging or by pasting from the clipboard. Around the native `input type="file"` the component gathers everything a form needs: a label, a description, messages, a counter, clearing and a filter by file types.
+
+## CdsFileInput
+
+**Props**
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `active` | `boolean \| undefined` | — | no | Active state of the field |
+| `activeColor` | `string \| undefined` | — | no | Color of the component in its active state |
+| `appendIcon` | `IconValue \| undefined` | — | no | Icon in the append slot, after the content |
+| `appendInnerIcon` | `IconValue \| undefined` | — | no | Icon in the inner append slot, after the content of the field |
+| `baseColor` | `string \| undefined` | — | no | Color of the component in its inactive state |
+| `bgColor` | `string \| undefined` | — | no | Background color of the component |
+| `centerAffix` | `boolean \| undefined` | — | no | Vertically center the appendInner, prependInner, clearIcon and label elements. |
+| `chips` | `boolean \| undefined` | — | no | Show the chosen files as tags (CdsTag) instead of a list of names. |
+| `clearable` | `boolean \| undefined` | `true` | no | Shows the clear button |
+| `clearIcon` | `IconValue \| undefined` | `'remove'` | no | Icon of the clear button |
+| `color` | `string \| undefined` | — | no | Component color |
+| `counter` | `boolean \| undefined` | — | no | Show a counter of the number (and, with `showSize`, of the total size) of the chosen files. |
+| `counterSizeString` | `string \| undefined` | `'$cds.fileInput.counterSize'` | no | Localization key for the text of the counter with the file size. |
+| `counterString` | `string \| undefined` | `'$cds.fileInput.counter'` | no | Localization key for the text of the file count counter. |
+| `description` | `string \| undefined` | — | no | Description of the component, shown under the label |
+| `dirty` | `boolean \| undefined` | — | no | Marks that the value of the field was changed by the user |
+| `disabled` | `boolean \| null \| undefined` | `null` | no | Disabled state |
+| `error` | `boolean \| undefined` | — | no | 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. |
+| `filterByType` | `string \| undefined` | — | no | Filtering of files by MIME type or extension (`image/*,.pdf`, for example). The rejected files do not get into the model. |
+| `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. |
+| `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 |
+| `hideInput` | `boolean \| undefined` | — | no | Hide the field, leaving only the prepend icon (to use it as a button, for example). |
+| `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 |
+| `label` | `string \| undefined` | — | no | Label text of the component |
+| `loading` | `string \| boolean \| undefined` | — | no | Loading indicator for 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` | `File \| File[] \| null \| undefined` | `(props) => props.multiple ? [] : null` | no | Value of the model: an array of files (with `multiple`), a single file or `null`. |
+| `multiple` | `boolean \| undefined` | — | no | Allow selecting several files. |
+| `name` | `string \| undefined` | — | no | Name of the input |
+| `persistentClearable` | `boolean \| undefined` | — | no | Always show the clear button, not only on hover or focus |
+| `persistentHint` | `boolean \| undefined` | — | no | Always show the hint, not only on focus |
+| `placeholder` | `string \| undefined` | — | no | Placeholder text shown in an empty field (while no files are chosen yet). |
+| `prependIcon` | `IconValue \| undefined` | `'upload'` | no | Icon in the prepend slot, before the content |
+| `prependInnerIcon` | `IconValue \| undefined` | — | no | Icon in the inner prepend slot, before the content of the field |
+| `readonly` | `boolean \| null \| undefined` | `null` | no | Read-only state |
+| `reverse` | `boolean \| undefined` | — | no | Reverses the order of the elements inside the field |
+| `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. |
+| `showSize` | `boolean \| 1000 \| 1024 \| undefined` | `false` | no | Show the size of the chosen files. A boolean or the base: 1000 (kB) or 1024 (KiB). |
+| `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 |
+| `truncateLength` | `string \| number \| undefined` | `22` | no | Maximum length of a file name before it is truncated (the characters at the start and at the end are kept). |
+| `validateOn` | `ValidateOn \| undefined` | — | no | Changes the type of the event that triggers validation |
+| `validationValue` | `any` | — | no | Value used when applying the validation rules |
+| `width` | `string \| number \| undefined` | — | no | Component width |
+
+**Events**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `click:control` | `[e: MouseEvent]` | Fires on a click in the main area of the control. |
+| `mousedown:control` | `[e: MouseEvent]` | Fires on a mouse button press in the main area of the control. |
+| `rejected` | `[files: File[]]` | Fires when some of the files were rejected by the `filterByType` filter. |
+| `update:focused` | `[focused: boolean]` | Fires when the element gains or loses focus. |
+| `update:modelValue` | `[value: File \| File[]]` | Fires when the list of the chosen files changes. |
+
+**Slots**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `append` | `CdsInputSlot` | Adds an element after the input |
+| `append-inner` | `CdsInputDefaultSlot` | Slot added at the end of the input |
+| `clear` | `CdsInputDefaultSlot & { props: Record<string, any>; }` | Slot for a custom clear icon (shown when the clearable prop is true). |
+| `counter` | `CdsCounterSlot` | Slot for a custom counter. |
+| `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 |
+| `loader` | `LoaderSlotProps` | Slot for a custom loader (shown when the loading prop is true). |
+| `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 |
+| `prepend-inner` | `CdsInputDefaultSlot` | Slot added at the start of the input |
+| `selection` | `CdsFileInputSelectionSlot` | Slot for a custom display of the chosen files. |
+
+**Exposed**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `controlRef` | `HTMLElement \| undefined` | Ref to the control of the input |
+| `fieldIconColor` | `string \| undefined` | Icon color |
+| `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 |