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

package/skills/cds-builder/references/guides/display-and-platform.md

@@ -0,0 +1,263 @@
+---
+sourceHash: 2d02d03da0e4d6f0fcb171775b7b88784a216ac0
+---
+
+# Display & Platform
+
+Central Design System exposes reactive information about the **screen**
+(breakpoints, viewport size, mobile mode) and the **platform** (browser, OS,
+device type) through a single composable — `useDisplay`. Breakpoints are the same
+in JavaScript and in styles (the `cds-breakpoint-*` SCSS mixins), so responsive
+logic in script and CSS always agrees.
+
+## Breakpoints
+
+| Breakpoint | Width range (px) | Start width | Grid columns |
+| --- | --- | --- | --- |
+| `xs` | `0 … 671` | `0` | 4 |
+| `sm` | `672 … 1055` | `672` | 8 |
+| `md` | `1056 … 1311` | `1056` | 16 |
+| `lg` | `1312 … 1583` | `1312` | 16 |
+| `xl` | `1584 … ∞` | `1584` | 16 |
+
+The values have a single source:
+
+- JS — `defaultDisplayOptions.thresholds` (`src/composables/useDisplay/internal/useDisplay.constants.ts`);
+- SCSS — `$grid-breakpoints` (`src/styles/utilities/grid/_config.scss`).
+
+## In JavaScript — `useDisplay`
+
+The `useDisplay` composable returns the reactive state of the screen and the
+platform. It works out of the box as long as the application is initialized
+through `createCds` (which provides `cds:display`).
+
+```ts
+import { useDisplay } from '@central-design-system/components';
+
+const display = useDisplay();
+
+display.width.value; // current viewport width, px
+display.name.value; // 'xs' | 'sm' | 'md' | 'lg' | 'xl'
+display.mobile.value; // true when width < mobileBreakpoint ('sm' by default)
+```
+
+### Available flags
+
+| Flag | Meaning |
+| --- | --- |
+| `xs` / `sm` / `md` / `lg` / `xl` | exactly one is active — the current breakpoint |
+| `smUp` / `mdUp` / `lgUp` / `xlUp` | width ≥ the breakpoint's start width ("and up") |
+| `smDown` / `mdDown` / `lgDown` / `xlDown` | the breakpoint and everything below it ("and down") |
+| `name` | name of the current breakpoint |
+| `mobile` | mobile mode (based on `mobileBreakpoint`) |
+| `mobileBreakpoint` | current mobile mode threshold |
+| `width` / `height` | viewport size, px |
+| `thresholds` | current threshold map |
+| `platform` | platform/browser flags (see [Platform](#platform)) |
+| `update()` | force a recalculation of size and platform |
+
+For example, `mdUp` is true when `width ≥ 1056`, and `smDown` when `width < 1056`
+(that is, it covers the `xs` and `sm` ranges).
+
+### Example in a component
+
+```tsx
+import { useDisplay } from '@central-design-system/components';
+
+const { mobile, mdUp } = useDisplay();
+
+defineRender(() => (
+  <div class={{ 'is-mobile': mobile.value }}>
+    {mdUp.value ? <DesktopLayout /> : <MobileLayout />}
+  </div>
+));
+```
+
+### Mobile mode at the prop level
+
+Components that mix in `defineDisplayProps()` accept the `mobile` and
+`mobileBreakpoint` props — use them to override the mobile mode threshold
+locally:
+
+```html
+<!-- Mobile mode kicks in below 1056px (md) instead of the global 'sm' -->
+<CdsSlideGroup mobile-breakpoint="md" />
+```
+
+### Overriding the thresholds globally
+
+Thresholds and `mobileBreakpoint` are configured at initialization:
+
+```ts
+import { createCds } from '@central-design-system/components';
+
+app.use(createCds({
+  display: {
+    mobileBreakpoint: 'md',
+    thresholds: { xs: 0, sm: 600, md: 960, lg: 1280, xl: 1920 }
+  }
+}));
+```
+
+> If you change the thresholds in JS, keep them in sync in SCSS
+> (`$grid-breakpoints`) — otherwise responsiveness in script and styles will
+> drift apart.
+
+## In SCSS — the `cds-breakpoint-*` mixins
+
+The mixins come from a public entry point:
+
+```scss
+@use '@central-design-system/components/styles/breakpoints' as breakpoint;
+```
+
+> In plain Dart Sass (without a bundler), use the pkg scheme and the Node
+> importer:
+> `@use 'pkg:@central-design-system/components/styles/breakpoints' as breakpoint;`.
+
+### `cds-breakpoint-up($name)` — "and up"
+
+```scss
+.card {
+  display: none;
+
+  // applies at min-width: 1056px (md and up)
+  @include breakpoint.cds-breakpoint-up(md) {
+    display: block;
+  }
+}
+```
+
+### `cds-breakpoint-down($name)` — "and down"
+
+```scss
+.sidebar {
+  // applies at max-width: 1055.98px — that is, on sm and xs
+  @include breakpoint.cds-breakpoint-down(sm) {
+    display: none;
+  }
+}
+```
+
+`cds-breakpoint-down('<name>')` covers the breakpoint itself **and everything
+below it** (the upper bound is the start of the next breakpoint minus `0.02px`).
+No media query is generated for the largest breakpoint (`xl`) — "xl and down" is
+every width.
+
+### `cds-breakpoint-between($lower, $upper)` — a range
+
+```scss
+.banner {
+  // min-width: 672px and max-width: 1056px
+  @include breakpoint.cds-breakpoint-between(sm, md) {
+    padding: 16px;
+  }
+}
+```
+
+Both mixins also accept a number instead of a name: `cds-breakpoint-up(900px)`.
+
+### Other mixins and functions
+
+- `cds-breakpoint($name)` — an alias for `cds-breakpoint-up`.
+- `cds-largest-breakpoint` — media query for the largest breakpoint.
+- `breakpoint-next($name)` / `breakpoint-prev($name)` — the neighboring breakpoint.
+- `is-smallest-breakpoint($name)` — whether `$name` is the smallest one.
+- `largest-breakpoint-name()` — name of the largest breakpoint.
+
+## JS ↔ CSS correspondence
+
+The `useDisplay` flags and the mixins' media queries cover identical width
+ranges — that's what lets you write consistent responsive logic in script and
+styles.
+
+| JS (`useDisplay`) | SCSS mixin | Width range |
+| --- | --- | --- |
+| `smUp` | `cds-breakpoint-up(sm)` | `≥ 672` |
+| `mdUp` | `cds-breakpoint-up(md)` | `≥ 1056` |
+| `lgUp` | `cds-breakpoint-up(lg)` | `≥ 1312` |
+| `xlUp` | `cds-breakpoint-up(xl)` | `≥ 1584` |
+| `smDown` | `cds-breakpoint-down(sm)` | `< 1056` |
+| `mdDown` | `cds-breakpoint-down(md)` | `< 1312` |
+| `lgDown` | `cds-breakpoint-down(lg)` | `< 1584` |
+| `xlDown` | `cds-breakpoint-down(xl)` | every width |
+
+> **Important (migrating from CDS 3).** In CDS 3 the semantics of
+> `cds-breakpoint-down` in SCSS differed from JS: `down('sm')` meant "strictly
+> below `sm`" (only `xs`), whereas `smDown` in JS means "`sm` and down". In CDS 4
+> the CSS is aligned with JS: `down('<name>')` now always means "`<name>` and
+> down". If you are porting styles from CDS 3, shift the `down()` argument one
+> step down (old `down('md')` ⇒ new `down('sm')`).
+> See the Migration Guide.
+
+## Platform
+
+`useDisplay().platform` is a reactive object with device, OS and browser flags.
+Detection is based on `navigator.userAgent` and touch support.
+
+```ts
+import { useDisplay } from '@central-design-system/components';
+
+const { platform } = useDisplay();
+
+if (platform.value.ios) {
+  // special behavior for iOS
+}
+
+const isTouchDevice = platform.value.touch;
+```
+
+### Fields of the `platform` object
+
+Every field is a `boolean`.
+
+| Field | Meaning |
+| --- | --- |
+| `android` | an Android device |
+| `ios` | an iOS device (iPhone / iPad / iPod) |
+| `cordova` | the app runs in Cordova |
+| `electron` | the app runs in Electron |
+| `chrome` | Chrome browser |
+| `edge` | Edge browser |
+| `firefox` | Firefox browser |
+| `opera` | Opera browser |
+| `win` | Windows OS |
+| `mac` | macOS |
+| `linux` | Linux OS |
+| `touch` | the device supports touch |
+| `ssr` | the value was computed on the server (SSR) |
+
+### Example: a class on the app root
+
+```tsx
+import { useDisplay } from '@central-design-system/components';
+
+const { platform } = useDisplay();
+
+defineRender(() => (
+  <div
+    class={{
+      'platform--ios': platform.value.ios,
+      'platform--android': platform.value.android,
+      'platform--touch': platform.value.touch
+    }}
+  >
+    <slot />
+  </div>
+));
+```
+
+> **Careful with user-agent sniffing.** Detecting the browser or OS from
+> `userAgent` is unreliable (the string can be spoofed, and new browsers may not
+> be recognized). Use `platform` for progressive enhancement — say, a fix
+> specific to iOS Safari — not as the only gate in front of a feature. For
+> feature detection, prefer capability checks (`'ontouchstart' in window` and the
+> like).
+
+### SSR
+
+During server-side rendering `userAgent` is unavailable, so `platform.ssr === true`
+and the rest of the flags are `false`. After hydration the values can be
+recalculated by calling `display.update()` (which recalculates both size and
+platform). Initial sizes for SSR are set through the second argument of
+`createDisplay(options, ssr)` or the `ssr` option in `createCds`.

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

@@ -0,0 +1,77 @@
+# Forms with CDS 4
+
+## Ready-made controls
+
+For typical forms use the ready-made "molecules" (each has its own `api.md`
+and `examples.md` in `references/components/`):
+
+| Control | Purpose |
+| --- | --- |
+| [CdsTextInput](../components/cds-text-input/api.md) | Text field with label / description / messages |
+| [CdsSelect](../components/cds-select/api.md) | Dropdown (single / multiple) |
+| [CdsAutocomplete](../components/cds-autocomplete/api.md) | Selection with search over the list |
+| [CdsCombobox](../components/cds-combobox/api.md) | Selection that also accepts free-form input |
+| [CdsCheckbox](../components/cds-checkbox/api.md) | Checkbox |
+| [CdsRadioGroup](../components/cds-radio-group/api.md) | Radio button group |
+| [CdsToggle](../components/cds-toggle/api.md) | Toggle |
+| [CdsDatePicker](../components/cds-date-picker/api.md) / [CdsTimePicker](../components/cds-time-picker/api.md) | Date / time |
+
+## CdsForm: aggregation and validation
+
+`CdsForm` groups fields, aggregates their validation (`v-model` — form
+validity) and exposes `validate` / `reset` / `resetValidation` methods via
+slot props and the exposed API. Validation rules are set on the fields with
+the `rules` prop (an array of functions `value → true | 'error text'`).
+
+A verified example (from Storybook):
+
+```html
+<CdsForm v-model="valid" @submit.prevent>
+  <template #default="{ reset }">
+    <CdsTextInput v-model="name" :rules="rules.name" label="Name" placeholder="Enter name" />
+    <CdsTextInput v-model="email" :rules="rules.email" label="Email" placeholder="Enter Email" />
+    <CdsButton appearance="secondary" @click="reset">Clear</CdsButton>
+    <CdsButton type="submit">Submit</CdsButton>
+  </template>
+</CdsForm>
+```
+
+```ts
+const valid = ref(false);
+const name = ref('');
+const email = ref('');
+
+const rules = {
+  name: [
+    (value: string) => !!value || 'Must not be empty',
+    (value: string) => value.length <= 10 || 'No more than 10 characters'
+  ],
+  email: [
+    (value: string) => !!value || 'Must not be empty',
+    (value: string) => /.+@.+\..+/.test(value) || 'Invalid format'
+  ]
+};
+```
+
+Useful modes (full list in [api.md](../components/cds-form/api.md)):
+
+- `first-fail` — validation stops at the first invalid field;
+- `disabled` / `readonly` on the form propagate to every nested field.
+
+CdsForm also works with external validators (vuelidate, vee-validate) — see
+[examples.md](../components/cds-form/examples.md).
+
+## Building your own field from atoms
+
+When no ready-made molecule fits, assemble the field from atoms:
+
+| Atom | Role |
+| --- | --- |
+| [CdsField](../components/cds-field/api.md) | Field wrapper: wires up label/control/messages, states |
+| [CdsLabel](../components/cds-label/api.md) | Field label |
+| [CdsDescription](../components/cds-description/api.md) | Supporting description |
+| [CdsMessages](../components/cds-messages/api.md) | Error messages / hints |
+| [CdsInput](../components/cds-input/api.md) | Bare input control |
+
+Before assembling, open the `api.md` of every atom — take the set of props
+and slots only from there.

package/skills/cds-builder/references/guides/global-configuration.md

@@ -0,0 +1,354 @@
+---
+sourceHash: 49864e870f2f989420a5ebf7ffc7eb1a3458124a
+---
+
+# Global configuration
+
+CDS 4 lets you set default prop values — globally, for a specific component, or
+only inside a given subtree. You describe "what buttons look like in our product"
+once and stop repeating the same props in every template.
+
+## Setup
+
+Default values are set through the `defaults` option of `createCds`. The `global`
+key affects every component; a key named after a component affects only that one.
+
+```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,
+  defaults: {
+    global: {
+      size: 'sm'
+    },
+    CdsButton: {
+      appearance: 'secondary'
+    },
+    CdsTextInput: {
+      hideDetails: 'auto'
+    }
+  }
+});
+
+createApp(App).use(cds);
+```
+
+**Important.** Props in `defaults` are written in camelCase: `hideDetails`, not
+`hide-details`.
+
+A component key is its name from `defineOptions({ name })` — `CdsButton`,
+`CdsTextInput`, `CdsCardActions` and so on. Subcomponent names (`CdsCardTitle`,
+`CdsListItem`) work exactly like root component names.
+
+### Resolution order
+
+For every prop, CDS takes the first value that applies:
+
+1. the prop explicitly passed in the template;
+2. `defaults.<ComponentName>.<prop>` from the nearest defaults context;
+3. `defaults.global.<prop>`;
+4. the default value declared in the component itself.
+
+An explicitly passed prop always wins — defaults can never override the template.
+
+### Changing defaults at runtime
+
+`createCds` returns an instance whose defaults live in a reactive ref. You can
+change them on the fly — every mounted component recalculates:
+
+```ts
+const cds = createCds({ components, directives });
+
+// for example, turn on compact mode based on a user setting
+cds.defaults.value = {
+  ...cds.defaults.value,
+  global: { size: 'sm' }
+};
+```
+
+## Contextual defaults
+
+Defaults can be set for components nested inside another component. For example,
+to make every button inside a card secondary by default:
+
+```ts
+createCds({
+  defaults: {
+    CdsCard: {
+      CdsButton: { appearance: 'secondary' }
+    }
+  }
+});
+```
+
+The rule is simple: a capitalized key is the name of a nested component, a
+lowercase key is a prop of the current component. Nesting is not limited to one
+level:
+
+```ts
+createCds({
+  defaults: {
+    CdsCard: {
+      CdsCardActions: {
+        CdsButton: { appearance: 'tertiary', size: 'sm' }
+      }
+    }
+  }
+});
+```
+
+The library uses the same mechanism internally so that grouping components can
+hand their settings down to their children:
+
+- `CdsButtonGroup` sets the `appearance`, `color`, `baseColor`, `size` props on nested `CdsButton`s;
+- `CdsTagGroup` sets the `color`, `activeColor`, `disabled`, `filter` props on `CdsTag`;
+- `CdsSelectionControlGroup` passes settings to the controls, with the target component name
+  set by the `defaultsTarget` prop (`CdsCheckbox`, `CdsRadio` and so on);
+- `CdsTabs`, `CdsSteps`, `CdsList`, `CdsBreadcrumbs`, `CdsButtonToggle`,
+  `CdsExpandablePanels`, `CdsOtpInput` work the same way.
+
+That's why `<CdsButtonGroup size="sm">` makes every button inside small — you
+don't have to set `size` on each of them.
+
+## Global class and style
+
+Besides props, a component's defaults can carry `class` and `style`. It's a
+convenient way to apply product-specific rules to every instance of a component
+without touching the templates:
+
+```ts
+createCds({
+  defaults: {
+    CdsButton: {
+      class: 'my-button'
+    }
+  }
+});
+```
+
+Any value Vue accepts works — a string, an object, an array:
+
+```ts
+createCds({
+  defaults: {
+    CdsButton: {
+      style: [{ textTransform: 'none' }]
+    }
+  }
+});
+```
+
+Unlike ordinary props, `class` and `style` are not overwritten by the template
+but **merged** with it. So `<CdsButton class="mt-2">` gets both `my-button` and
+`mt-2`.
+
+**Important.** `class` and `style` only work under a specific component's key. In
+`global` they are ignored.
+
+## Aliases
+
+An alias is the same component registered under a different name with its own
+defaults. Aliases are a handy way to assemble "product" variants of components.
+
+```ts
+import { createCds, components, directives, CdsButton } from '@central-design-system/components';
+
+const cds = createCds({
+  components,
+  directives,
+  aliases: {
+    CdsButtonPrimary: CdsButton,
+    CdsButtonDanger: CdsButton
+  },
+  defaults: {
+    CdsButtonPrimary: {
+      appearance: 'primary',
+      class: 'my-button--primary'
+    },
+    CdsButtonDanger: {
+      appearance: 'primary',
+      color: 'red',
+      class: 'my-button--danger'
+    }
+  }
+});
+```
+
+Aliases are registered globally, so you can use them in templates right away:
+
+```vue
+<template>
+  <CdsButtonPrimary>Save</CdsButtonPrimary>
+  <CdsButtonDanger class="ml-2">Delete</CdsButtonDanger>
+</template>
+```
+
+**Important.** An alias does not inherit the base component's defaults. If the
+configuration has `defaults.CdsButton`, it will not apply to `<CdsButtonPrimary>`
+— defaults are looked up by the alias name. Move shared settings into `global` or
+duplicate them under the alias key.
+
+## Defaults for part of the application
+
+To set defaults for a subtree rather than globally, use the
+`CdsDefaultsProvider` component. The Controls panel in Storybook is built on it
+too: the values from the panel are applied to the example's components as
+defaults.
+
+```vue
+<script setup lang="ts">
+import { CdsButton, CdsDefaultsProvider } from '@central-design-system/components';
+</script>
+
+<template>
+  <CdsDefaultsProvider :defaults="{ CdsButton: { appearance: 'tertiary', size: 'sm' } }">
+    <CdsButton>Small tertiary button</CdsButton>
+  </CdsDefaultsProvider>
+</template>
+```
+
+| Prop       | Type                | Purpose                                                                                      |
+| ---------- | ------------------- | -------------------------------------------------------------------------------------------- |
+| `defaults` | `DefaultsOptions`   | Defaults for the subtree; merged with the inherited ones by default                            |
+| `scoped`   | `boolean`           | Don't mix with the parent defaults — only the ones set here apply                              |
+| `reset`    | `number \| string`  | Go N levels up the defaults chain                                                              |
+| `root`     | `boolean \| string` | Fall back to the root defaults from `createCds`; with a string — to a named group inside them  |
+| `disabled` | `boolean`           | Provide nothing — the subtree gets the parent defaults as they are                             |
+
+The typical use for `scoped` is an "island" inside someone else's environment:
+enclosing groups (`CdsButtonGroup`, say) should not impose their settings on your
+block.
+
+## Your own components
+
+Your application's own components can take part in the defaults system too. Pass
+their props through `useDefaults`:
+
+```vue
+<script setup lang="ts">
+import { useDefaults } from '@central-design-system/components';
+
+const _props = defineProps<{ foo?: string }>();
+const props = useDefaults(_props, 'MyComponent');
+</script>
+
+<template>
+  <div>I am {{ props.foo }}</div>
+</template>
+```
+
+`useDefaults` takes two arguments, both optional:
+
+- `props` — the props object returned by `defineProps`;
+- `name` — the component name used to look up the key in `defaults`. If omitted,
+  the name from `defineOptions({ name })` is used, and failing that, the file name.
+
+Now the component is configurable from the shared configuration:
+
+```ts
+createCds({
+  defaults: {
+    MyComponent: { foo: 'bar' }
+  }
+});
+```
+
+**Important.** In the template, refer to `props.foo`, not `foo`. `useDefaults`
+returns a proxy over the props, and destructured `defineProps` variables bypass
+it:
+
+```diff
+-<div>I am {{ foo }}</div>
++<div>I am {{ props.foo }}</div>
+```
+
+### Nested defaults in your own components
+
+To make your component hand defaults down to its children (the way
+`CdsButtonGroup` does), just call `useDefaults()` with no arguments — the nested
+keys from its `defaults` section go into the child context:
+
+```vue
+<script setup lang="ts">
+import { useDefaults } from '@central-design-system/components';
+
+useDefaults();
+</script>
+
+<template>
+  <div class="my-panel">
+    <slot />
+  </div>
+</template>
+```
+
+```ts
+createCds({
+  defaults: {
+    MyPanel: {
+      CdsButton: { appearance: 'tertiary' }
+    }
+  }
+});
+```
+
+If the children's defaults depend on the component's props, use `provideDefaults`
+directly:
+
+```vue
+<script setup lang="ts">
+import { provideDefaults } from '@central-design-system/components';
+import { toRef } from 'vue';
+
+const props = defineProps<{ size?: 'sm' | 'md' }>();
+
+provideDefaults({
+  CdsButton: {
+    size: toRef(() => props.size)
+  }
+});
+</script>
+
+<template>
+  <div class="my-toolbar">
+    <slot />
+  </div>
+</template>
+```
+
+## Blueprint — a configuration preset
+
+If several applications need the same set of options, extract it into a
+`blueprint`: a plain `createCds` options object that the rest of the
+configuration is layered on top of.
+
+```ts
+import { createCds, components, directives } from '@central-design-system/components';
+import type { Blueprint } from '@central-design-system/components';
+
+const productBlueprint: Blueprint = {
+  theme: { defaultTheme: 'b2bLight' },
+  defaults: {
+    CdsButton: { appearance: 'secondary' }
+  }
+};
+
+const cds = createCds({
+  blueprint: productBlueprint,
+  components,
+  directives,
+  // overrides the value from the blueprint
+  defaults: {
+    CdsButton: { size: 'sm' }
+  }
+});
+```
+
+Options are merged deeply (`mergeDeep`), so in the example above the buttons keep
+`appearance: 'secondary'` from the preset and gain `size: 'sm'`.