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

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

@@ -0,0 +1,101 @@
+# Pattern: a form with validation and server errors
+
+The basic form assembly is covered in the [Forms](../guides/forms.md) guide.
+This page covers what it does not: waiting for the server response, backend
+errors, and blocking a repeated submit.
+
+## Submitting with an awaited response
+
+`@submit` on `CdsForm` yields a **Promise with the validation result**, not a
+ready result — await it before sending the request. `.prevent` is mandatory,
+otherwise the browser reloads the page.
+
+```vue
+<script setup lang="ts">
+import { CdsButton, CdsForm, CdsNotification, CdsTextInput } from '@central-design-system/components';
+import { ref } from 'vue';
+
+const email = ref('');
+const password = ref('');
+const loading = ref(false);
+const formError = ref('');
+
+const rules = {
+  email: [
+    (value: string) => !!value || 'Cannot be empty',
+    (value: string) => /.+@.+\..+/.test(value) || 'Invalid format'
+  ],
+  password: [(value: string) => !!value || 'Cannot be empty']
+};
+
+const submit = async (event: Promise<{ valid: boolean }>): Promise<void> => {
+  const { valid } = await event;
+  if (!valid) return;
+
+  loading.value = true;
+  formError.value = '';
+
+  try {
+    await api.login({ email: email.value, password: password.value });
+  } catch (error) {
+    formError.value = 'Could not sign in. Check your credentials and try again.';
+  } finally {
+    loading.value = false;
+  }
+};
+</script>
+
+<template>
+  <CdsForm class="flex flex-col gap-2" @submit.prevent="submit">
+    <CdsTextInput v-model="email" :rules="rules.email" label="Email" />
+    <CdsTextInput v-model="password" :rules="rules.password" label="Password" type="password" />
+
+    <CdsNotification v-if="formError" status="danger" :text="formError" />
+
+    <CdsButton type="submit" :loading="loading" text="Sign in" />
+  </CdsForm>
+</template>
+```
+
+Key points:
+
+- `:loading` on the submit button solves two problems at once — it shows
+  request progress and guards against a repeated click. No separate spinner
+  is needed.
+- A form-level error (network, server rejection) goes into a separate
+  `CdsNotification` in the form flow, not into a toast: it belongs to the
+  content, not to an event.
+- Spacing: `gap-2` between fields and between buttons; the actions row of a
+  multi-button form is right-aligned with the primary action last (see
+  SKILL.md, steps 5–6).
+
+## Server-side field errors
+
+The `rules` are synchronous, so they are not suited for server errors. Keep
+the error for a specific field in a separate ref and add a rule that reads it:
+
+```ts
+const serverErrors = ref<Record<string, string>>({});
+
+const rules = {
+  email: [
+    (value: string) => !!value || 'Cannot be empty',
+    () => serverErrors.value.email ?? true
+  ]
+};
+```
+
+After the server responds, fill `serverErrors` and call the form's
+`validate()` via the slot prop or a `ref`. The rule resets once the server
+stops returning an error for that field.
+
+## What not to do
+
+- Do not disable the submit button with `:disabled="!valid"`. The user does
+  not understand why the button will not press; let them press it and show
+  the errors.
+- Do not assemble a field from `CdsField` + `CdsInput` when a ready-made
+  control exists — you would rebuild `CdsTextInput` by hand and lose its
+  error wiring.
+- Do not duplicate the error message next to the field: `CdsMessages` inside
+  the control already shows it.

package/skills/cds-builder/references/patterns/page-layout.md

@@ -0,0 +1,78 @@
+# Pattern: page skeleton
+
+The application skeleton is assembled from Layouts-category components, not
+from `div`s with manual `position: fixed`. They are already coordinated with
+each other: the header and footer know their height, the side panel knows its
+width, and the main content gets the right offsets on its own.
+
+## Building blocks
+
+| Component | Role |
+| --- | --- |
+| `CdsApp` | Application root. |
+| `CdsLayout` | Skeleton: lays out the header, side panels, content, and footer. |
+| `CdsHeader` | Application header. |
+| `CdsDrawer` | Side navigation panel. |
+| `CdsMain` | Main content wrapper. |
+| `CdsFooter` | Footer. |
+| `CdsPage` | Wrapper for a specific page's content inside `CdsMain`. |
+
+## Assembly
+
+```vue
+<script setup lang="ts">
+import {
+  CdsApp,
+  CdsDrawer,
+  CdsFooter,
+  CdsHeader,
+  CdsLayout,
+  CdsMain,
+  CdsPage
+} from '@central-design-system/components';
+import { ref } from 'vue';
+
+const drawerOpen = ref(true);
+</script>
+
+<template>
+  <CdsApp>
+    <CdsLayout>
+      <CdsHeader>Header</CdsHeader>
+
+      <CdsDrawer v-model="drawerOpen">Navigation</CdsDrawer>
+
+      <CdsMain>
+        <CdsPage>
+          <router-view />
+        </CdsPage>
+      </CdsMain>
+
+      <CdsFooter>Footer</CdsFooter>
+    </CdsLayout>
+  </CdsApp>
+</template>
+```
+
+## Layout scheme
+
+The `view` prop on `CdsLayout` defines a three-row scheme — top, middle,
+bottom. The default value `'hhh lpr fff'` means: full-width header, left
+panel / content / right panel in the middle, full-width footer.
+
+If the header should start after the side panel, the scheme changes to
+`'lhh lpr lff'` — the panel occupies its column in all three rows.
+
+The `container` prop switches the layout into a mode where it scrolls itself
+rather than the page. Needed when the skeleton is embedded into another
+interface.
+
+## What not to do
+
+- Do not offset the content under a fixed header manually (`padding-top: 64px`).
+  `CdsMain` inside `CdsLayout` computes this itself, and the hardcoded value
+  breaks when the header size changes.
+- Do not replace `CdsDrawer` with your own panel built on `CdsSurface` — you
+  lose consistency with the layout and the mobile behavior.
+- `CdsDrawer` is app-level navigation. A panel with a form that slides in from
+  the side on a user action is `CdsModal`.

package/skills/cds-builder/references/patterns/tables.md

@@ -0,0 +1,87 @@
+# Pattern: a data list with filters and an empty state
+
+A list screen almost never consists of a single table: it has filters,
+loading, pagination, and at least two empty states. A common mistake is
+building the table by hand out of `CdsList` and markup: sorting, sticky
+header, and expandable rows already exist in `CdsTable`.
+
+## Data contract
+
+`CdsTable` accepts `columns` (column definitions) and `data` (an array of
+rows) — not `headers` / `items`. The full list of props, including expandable
+rows, fixed columns, and drag-and-drop, is in
+[api.md](../components/cds-table/api.md).
+
+```vue
+<script setup lang="ts">
+import { CdsEmptyState, CdsTable, CdsTextInput } from '@central-design-system/components';
+import { computed, ref } from 'vue';
+
+const search = ref('');
+const loading = ref(false);
+const rows = ref<Order[]>([]);
+
+const columns = [
+  { title: 'Number', dataIndex: 'number', key: 'number' },
+  { title: 'Customer', dataIndex: 'customer', key: 'customer' },
+  { title: 'Status', dataIndex: 'status', key: 'status' }
+];
+
+const filtered = computed(() =>
+  rows.value.filter((row) => row.customer.toLowerCase().includes(search.value.toLowerCase()))
+);
+</script>
+
+<template>
+  <div class="flex flex-col gap-4">
+    <CdsTextInput v-model="search" label="Search by customer" prepend-inner-icon="search" />
+
+    <CdsTable :columns="columns" :data="filtered" :loading="loading" />
+
+    <CdsEmptyState
+      v-if="!loading && filtered.length === 0 && search"
+      title="Nothing found"
+      text="Try changing the search criteria."
+    />
+    <CdsEmptyState
+      v-else-if="!loading && rows.length === 0"
+      title="No orders yet"
+      text="Orders will appear here as soon as you create them."
+    />
+  </div>
+</template>
+```
+
+## Two distinct empty states
+
+There are always two, and they must not be confused:
+
+- **No data at all** — explain what will appear here and offer an action
+  ("Create order").
+- **The filter found nothing** — say that the filter is the reason and offer
+  to reset it. Do not show "create your first order" here: orders exist.
+
+## Loading
+
+The `loading` prop on `CdsTable` shows the loading state of the table itself.
+For the screen's first load, when even the shape of the data is unknown,
+`CdsSkeletonLoader` fits — it keeps the layout from jumping when the content
+appears.
+
+The empty state must not show while loading is in progress — hence the
+`!loading` in the conditions above. Otherwise the user sees "nothing here"
+for a second.
+
+## Server-side data
+
+With server-side pagination and filtering, do not filter `data` on the
+client: send the query parameters and put whatever the server returned into
+`data`. Pagination is configured via the `pagination` prop.
+
+## What not to do
+
+- Do not build a table out of `CdsList` or `div`s when you need columns.
+- Do not hide pagination when there is a single page but a lot of data — it
+  breaks the user's expectation when they return to the screen.
+- Do not write "No data" without an explanation: an empty screen must suggest
+  the next step.