prime-ui-kit 0.3.1 → 0.4.0

package/src/components/checkbox/COMPONENT.md

@@ -2,25 +2,59 @@
 
 **Проектирование по умолчанию:** при проектировании экранов и примеров изначально выбирай **`m`** для `size` (где есть ось размера), если явно не оговорено иное.
 
-## About
+## Canonical
+
+- **Export:** `Checkbox` namespace — **`Checkbox.Root`**, **`Checkbox.Label`**, **`Checkbox.Hint`**, **`Checkbox.Error`**.
+- **Pattern:** compound field — native **`input type="checkbox"`** (visually hidden) + decorative box; **`Checkbox.Label`** is required for the interactive row and wires **`htmlFor`** to the input id.
+- **State:** **controlled** (`checked` + `onChange`) or **uncontrolled** (`defaultChecked`); internal checked state updates before consumer **`onChange`** runs.
+- **`indeterminate`:** boolean on **`Root`** — sets DOM **`input.indeterminate`** and mixed visual; not a third form value — clear or resync in your **`onChange`** when the user toggles.
+- **Sizing:** **`size`** `s` | `m` | `l` | `xl` on **`Root`** (default **`m`**); propagates via **`ControlSizeProvider`** to label/hint typography.
+- **Validation chrome:** **`variant="error"`** on **`Root`** and/or mounted **`Checkbox.Error`** → **`aria-invalid`**, error styling; **`Checkbox.Hint`** contributes to **`aria-describedby`** when mounted.
+- **Forwarding:** **`Root`** accepts **`Omit<InputHTMLAttributes<HTMLInputElement>, "type" | "size">`** spread onto the real input — use **`name`**, **`value`**, **`required`**, **`form`**, etc. Ref on **`Root`** targets the **input** element.
+- **Not supported:** **`asChild`**, loading state, or custom checkbox markup.
+
+## Extended
+
+### About
 
 A compound checkbox: a visually hidden native `input type="checkbox"`, a decorative box with check or indeterminate mark, and optional label, hint, and error text wired to `aria-describedby` and invalid state.
 
-- **When to use** — explicit consent, terms, or other “yes/no” fields that submit with the form (`name`, `value`, `required`).
-- **When to use** — row or “select all” patterns where the parent shows **indeterminate** when only some children are checked.
-- **When to use** — independent toggles (filters, optional features) rather than one-of-many choices.
-- **When to use** — hint text or inline validation aligned under the label column.
-- **When not to use** — exactly one option from a set of alternatives (prefer [Radio](../radio/COMPONENT.md)).
-- **When not to use** — a single binary setting where a switch fits the product language (prefer [Switch](../switch/COMPONENT.md)).
-- **When not to use** — you need `asChild` or fully custom markup; the control is a fixed [Label](../label/COMPONENT.md) row with a hidden input and SVG.
+- **When to use** — explicit consent, terms, or other “yes/no” fields that submit with the form (`name`, `value`, `required`); row or “select all” patterns where the parent shows **indeterminate** when only some children are checked; independent toggles (feature flags, optional features, settings) rather than one-of-many choices; hint text or inline validation aligned under the label column.
+- **When not to use** — exactly one option from a set of alternatives (prefer [Radio](../radio/COMPONENT.md)); a single binary setting where a switch fits the product language (prefer [Switch](../switch/COMPONENT.md)); you need `asChild` or fully custom markup; the control is a fixed [Label](../label/COMPONENT.md) row with a hidden input and SVG.
+
+### Playground snippets
+
+Demos match **`playground/sections/CheckboxSection.tsx`** (order and intent). Sources use `@/` imports under **`playground/snippets/checkbox/`**:
+
+| Block | File | What it shows |
+|-------|------|----------------|
+| **Sizes** | [`sizes.tsx`](../../../playground/snippets/checkbox/sizes.tsx) | **`size`** **`s`**, **`m`**, **`l`**, **`xl`** — box, gap, and label scale from control tokens. |
+| **Variants** | [`variants.tsx`](../../../playground/snippets/checkbox/variants.tsx) | **`variant="default"`** vs **`variant="error"`**; mounting **`Checkbox.Error`** also drives invalid (see **Composition** + recipes). |
+| **States** | [`states.tsx`](../../../playground/snippets/checkbox/states.tsx) | Unchecked, **`defaultChecked`**, **`indeterminate`**, native **`required`**, **`disabled`** (off and on). |
+| **Controlled** | [`controlled.tsx`](../../../playground/snippets/checkbox/controlled.tsx) | **`checked`** + **`onChange`**; **`indeterminate`** from parent state cleared on user change (table “select all” pattern). |
+| **Composition** | [`composition.tsx`](../../../playground/snippets/checkbox/composition.tsx) | **`Hint`** only; **`Error`** without **`variant="error"`** on root; full **`Hint`** + **`Error`** with **`variant="error"`**. |
+| **Full width** | [`full-width.tsx`](../../../playground/snippets/checkbox/full-width.tsx) (+ [`full-width.module.css`](../../../playground/snippets/checkbox/full-width.module.css)) | Narrow container: field root is **`width: 100%`**; long label wraps in the text column; hint aligned under label. |
+| **Specific** | [`specific.tsx`](../../../playground/snippets/checkbox/specific.tsx) | Empty **`Checkbox.Label`** with **`aria-label`** on **`Root`**; **`name`** / **`value`** / **`defaultChecked`** for form submit. |
 
-## Composition
+### Scenarios (recipes)
+
+| Scenario | Approach |
+|----------|----------|
+| **Terms acceptance** | **`required`** on **`Root`**; optional **`Checkbox.Hint`** for legal context; show **`Checkbox.Error`** or **`variant="error"`** after validation when unchecked. → [`examples/terms-acceptance.tsx`](examples/terms-acceptance.tsx) |
+| **Feature flags list** | One **`Checkbox.Root` per flag**; independent **controlled** booleans or a small state map; no indeterminate unless a parent “enable all” exists. → [`examples/feature-flags-list.tsx`](examples/feature-flags-list.tsx) |
+| **Bulk select (row / table)** | **Header** checkbox: **`checked`** when all rows selected, **`indeterminate`** when some; **`onChange`** selects or clears all row ids. **Row** checkboxes toggle one id each. → [`examples/bulk-select-rows.tsx`](examples/bulk-select-rows.tsx) |
+| **Settings panel** | Stack of **`Root` → `Label` → optional `Hint`** rows; same **`size`** across the panel for rhythm; **`disabled`** for plan-gated options. → [`examples/settings-panel.tsx`](examples/settings-panel.tsx) |
+| **Empty label + form attrs** | Icon-only / compact cell: **`aria-label`** (or **`aria-labelledby`**) on **`Root`**; optional **`name`** / **`value`** for submission. → [`examples/empty-label-form.tsx`](examples/empty-label-form.tsx) |
+
+Runnable recipe examples use **`prime-ui-kit`** imports under **`examples/`**. Snippet-level demos (internal imports) are listed in **Playground snippets** above.
+
+### Composition
 
 - **`Checkbox.Root`** — wraps the field in a `div` with `data-size`, `data-variant`, `data-disabled`, `data-invalid`, `data-checked`, `data-indeterminate`; provides context and `ControlSizeProvider` for child parts.
 - **`Checkbox.Label`** — required for the control: hosts the native checkbox and decorative SVG, then optional text in a trailing column; sets `htmlFor` to the input id.
 - **`Checkbox.Hint`** — optional; registers hint text and contributes its id to the input’s `aria-describedby`.
 - **`Checkbox.Error`** — optional; error-styled [Hint](../hint/COMPONENT.md) and registers invalid state when mounted (with `variant="error"` on the root when you want error chrome without the slot).
-- **Order:** `Root` → `Label` (always) → `Hint` / `Error` below when needed. Public API: `Checkbox` with `Root`, `Label`, `Hint`, `Error`.
+- **Order:** `Root` → `Label` (always) → `Hint` / `Error` below when needed.
 
 ### Minimal example
 
@@ -36,16 +70,15 @@ export function Example() {
 }
 ```
 
-## Rules
+### Rules
 
-- Вертикальный ритм между **подписью и hint** задаётся самим компонентом; не вставляйте между ними лишний [Typography](../typography/COMPONENT.md) с другой ролью чтения без необходимости.
-- Support **controlled** (`checked` + `onChange`) and **uncontrolled** (`defaultChecked`); internal state updates from the change handler before your `onChange` runs.
+- Vertical rhythm between **label and hint** is owned by the component; avoid inserting extra [Typography](../typography/Typography.tsx) between them unless the design explicitly requires a different reading role.
 - **`indeterminate`** only affects visuals and the DOM `indeterminate` property; it is not a separate submitted value—clear or sync it in your handler when the user clicks.
-- Set **`aria-label`** or **`aria-labelledby`** on **`Checkbox.Root`** when **`Checkbox.Label`** has no visible text (icon-only or header “select all” cell).
-- **`aria-describedby`** on the root is merged with hint and error ids when those slots are mounted; include your own ids in `aria-describedby` if you need extra descriptors.
+- Set **`aria-label`** or **`aria-labelledby`** on **`Checkbox.Root`** (forwarded to the input via rest props) when **`Checkbox.Label`** has no visible text (icon-only or compact “select all” cell).
+- **`aria-describedby`** on **`Root`** is merged with hint and error ids when those slots are mounted; include your own ids in `aria-describedby` if you need extra descriptors.
 - **`variant="error"`** or a mounted **`Checkbox.Error`** sets `aria-invalid` and error styling; **`disabled`** disables the input and dims hint styling.
 - Focus and keyboard activation use the native checkbox; the visible focus ring targets the decorative control via `focus-visible`.
-- There is no loading or `asChild` API; **`size`** on the root does not forward to the DOM input (layout token only).
+- There is no loading or `asChild` API; **`size`** on the root does not forward as a DOM attribute on the wrapper (layout/visual token axis only).
 
 ## API
 
@@ -96,3 +129,11 @@ export function Example() {
 - [Radio](../radio/COMPONENT.md) — one-of-many choice with the same validation variants.
 - [Switch](../switch/COMPONENT.md) — binary setting with a different control pattern.
 - [Label](../label/COMPONENT.md), [Hint](../hint/COMPONENT.md) — primitives used inside the checkbox; pair with [Input](../input/COMPONENT.md) in larger forms.
+
+## LLM note
+
+- Prefer **`Checkbox.Label`** with visible text; if the label slot is empty or icon-only, set **`aria-label`** (or **`aria-labelledby`**) via **`Checkbox.Root`** rest props so the native input has a name.
+- **`indeterminate`** is purely visual + DOM hinting — parent “select all” logic must derive **`checked`** / **`indeterminate`** from child selection state and normalize **`onChange`** (e.g. indeterminate click → select all).
+- Use **`Checkbox.Error`** or **`variant="error"`** for validation feedback; mounting **`Checkbox.Error`** registers invalid state even without **`variant`** on **`Root`**.
+- Do not substitute **Radio** or **Switch** based on “sounds nicer” — **Radio** is for mutually exclusive options; **Switch** for settings that read as on/off system toggles.
+- Keep composition order **`Root` → `Label` → `Hint`/`Error`**; refs on **`Root`** attach to the **`<input>`**, not the wrapper `div`.

package/src/components/checkbox/examples/bulk-select-rows.tsx

@@ -0,0 +1,54 @@
+import { Checkbox } from "prime-ui-kit";
+import * as React from "react";
+
+const ROW_IDS = ["row-1", "row-2", "row-3"] as const;
+
+/**
+ * Header “select all” with indeterminate when partially selected; row checkboxes toggle membership.
+ */
+export function BulkSelectRowsExample() {
+  const [selected, setSelected] = React.useState<Set<string>>(() => new Set());
+
+  const allSelected = selected.size === ROW_IDS.length;
+  const noneSelected = selected.size === 0;
+  const headerIndeterminate = !noneSelected && !allSelected;
+
+  function toggleRow(id: string, checked: boolean) {
+    setSelected((prev) => {
+      const next = new Set(prev);
+      if (checked) {
+        next.add(id);
+      } else {
+        next.delete(id);
+      }
+      return next;
+    });
+  }
+
+  function toggleAll(checked: boolean) {
+    setSelected(checked ? new Set(ROW_IDS) : new Set());
+  }
+
+  return (
+    <>
+      <Checkbox.Root
+        size="m"
+        checked={allSelected}
+        indeterminate={headerIndeterminate}
+        onChange={(e) => toggleAll(e.target.checked)}
+      >
+        <Checkbox.Label>Select all rows</Checkbox.Label>
+      </Checkbox.Root>
+      {ROW_IDS.map((id) => (
+        <Checkbox.Root
+          key={id}
+          size="m"
+          checked={selected.has(id)}
+          onChange={(e) => toggleRow(id, e.target.checked)}
+        >
+          <Checkbox.Label>Row {id}</Checkbox.Label>
+        </Checkbox.Root>
+      ))}
+    </>
+  );
+}

package/src/components/checkbox/examples/empty-label-form.tsx

@@ -0,0 +1,24 @@
+import { Checkbox } from "prime-ui-kit";
+
+/**
+ * Matches playground `snippets/checkbox/specific.tsx`: no visible label text — set an accessible name on
+ * Root; optional name/value for form submission.
+ */
+export function EmptyLabelFormExample() {
+  return (
+    <>
+      <Checkbox.Root size="m" aria-label="Receive digest by email (no visible label)">
+        <Checkbox.Label />
+      </Checkbox.Root>
+      <Checkbox.Root
+        size="m"
+        name="newsletter"
+        value="weekly"
+        defaultChecked
+        aria-label="Subscribe to weekly newsletter"
+      >
+        <Checkbox.Label />
+      </Checkbox.Root>
+    </>
+  );
+}

package/src/components/checkbox/examples/feature-flags-list.tsx

@@ -0,0 +1,43 @@
+import { Checkbox } from "prime-ui-kit";
+import * as React from "react";
+
+const FLAGS = [
+  { id: "analytics", label: "Product analytics", hint: "Usage events to improve the app." },
+  { id: "beta", label: "Beta features", hint: "Early access; may be unstable." },
+  { id: "marketing", label: "Marketing emails", hint: "Tips and offers; no spam." },
+] as const;
+
+type FlagId = (typeof FLAGS)[number]["id"];
+
+/**
+ * Independent feature toggles: one checkbox per flag, shared controlled map.
+ */
+export function FeatureFlagsListExample() {
+  const [flags, setFlags] = React.useState<Record<FlagId, boolean>>({
+    analytics: true,
+    beta: false,
+    marketing: false,
+  });
+
+  function setFlag(id: FlagId, checked: boolean) {
+    setFlags((prev) => ({ ...prev, [id]: checked }));
+  }
+
+  return (
+    <>
+      {FLAGS.map((f) => (
+        <Checkbox.Root
+          key={f.id}
+          name={`flag_${f.id}`}
+          value="on"
+          size="m"
+          checked={flags[f.id]}
+          onChange={(e) => setFlag(f.id, e.target.checked)}
+        >
+          <Checkbox.Label>{f.label}</Checkbox.Label>
+          <Checkbox.Hint>{f.hint}</Checkbox.Hint>
+        </Checkbox.Root>
+      ))}
+    </>
+  );
+}

package/src/components/checkbox/examples/settings-panel.tsx

@@ -0,0 +1,50 @@
+import { Checkbox } from "prime-ui-kit";
+import * as React from "react";
+
+/**
+ * Settings-style list: optional features with hints; one option disabled (e.g. plan-gated).
+ */
+export function SettingsPanelExample() {
+  const [desktopNotify, setDesktopNotify] = React.useState(true);
+  const [sound, setSound] = React.useState(false);
+  const [weeklyDigest, setWeeklyDigest] = React.useState(true);
+
+  return (
+    <>
+      <Checkbox.Root
+        name="notify_desktop"
+        value="on"
+        size="m"
+        checked={desktopNotify}
+        onChange={(e) => setDesktopNotify(e.target.checked)}
+      >
+        <Checkbox.Label>Desktop notifications</Checkbox.Label>
+        <Checkbox.Hint>Show alerts when the app is in the background.</Checkbox.Hint>
+      </Checkbox.Root>
+      <Checkbox.Root
+        name="sound"
+        value="on"
+        size="m"
+        checked={sound}
+        onChange={(e) => setSound(e.target.checked)}
+      >
+        <Checkbox.Label>Sound effects</Checkbox.Label>
+        <Checkbox.Hint>Short UI sounds for sends and errors.</Checkbox.Hint>
+      </Checkbox.Root>
+      <Checkbox.Root name="sso" value="on" size="m" disabled>
+        <Checkbox.Label>SSO / SAML (Enterprise)</Checkbox.Label>
+        <Checkbox.Hint>Contact sales to enable single sign-on.</Checkbox.Hint>
+      </Checkbox.Root>
+      <Checkbox.Root
+        name="digest"
+        value="on"
+        size="m"
+        checked={weeklyDigest}
+        onChange={(e) => setWeeklyDigest(e.target.checked)}
+      >
+        <Checkbox.Label>Weekly activity summary</Checkbox.Label>
+        <Checkbox.Hint>Email recap of mentions and tasks.</Checkbox.Hint>
+      </Checkbox.Root>
+    </>
+  );
+}

package/src/components/checkbox/examples/terms-acceptance.tsx

@@ -0,0 +1,42 @@
+import { Checkbox } from "prime-ui-kit";
+import * as React from "react";
+
+/**
+ * Terms / consent: required submission, hint for context, error after failed validation.
+ */
+export function TermsAcceptanceExample() {
+  const [accepted, setAccepted] = React.useState(false);
+  const [showError, setShowError] = React.useState(false);
+
+  function handleSubmit(e: React.FormEvent<HTMLFormElement>) {
+    e.preventDefault();
+    if (!accepted) {
+      setShowError(true);
+    }
+  }
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <Checkbox.Root
+        name="terms"
+        value="accept"
+        required
+        checked={accepted}
+        onChange={(e) => {
+          setAccepted(e.target.checked);
+          if (e.target.checked) {
+            setShowError(false);
+          }
+        }}
+        variant={showError ? "error" : "default"}
+      >
+        <Checkbox.Label>I accept the Terms of Service and Privacy Policy</Checkbox.Label>
+        <Checkbox.Hint>
+          Required to create an account. You can withdraw consent in settings.
+        </Checkbox.Hint>
+        {showError ? <Checkbox.Error>Please accept the terms to continue.</Checkbox.Error> : null}
+      </Checkbox.Root>
+      <button type="submit">Continue</button>
+    </form>
+  );
+}

package/src/components/code-block/COMPONENT.md

@@ -1,21 +1,57 @@
 # CodeBlock
 
-## About
+## Canonical
 
-`CodeBlock` is a static presentation component: it renders a TS or TSX source string with syntax highlighting and a light or dark token palette. The kit exposes a single part, `Root`, which outputs a `pre` whose inner `code` markup is produced by `highlightTsxHtml`.
+- **API:** `CodeBlock.Root` only. Required prop: **`code`** (string). Optional **`colorScheme`**: `"light"` (default) or `"dark"` for `data-theme` on the root `pre`.
+- **Rendering:** `pre` + inner `code` filled via **`highlightTsxHtml(code.trimEnd())`** and **`dangerouslySetInnerHTML`**. Do not pass **`children`** or **`dangerouslySetInnerHTML`** (omitted from props).
+- **Trust:** only **trusted** `code` strings (constants, vetted CMS, sanitized server output). Never pass raw user HTML/TSX here.
+- **Language:** heuristic **TS/TSX** highlighting — not a full grammar. JSON, stacks, and other text still render; token classes may be partial.
+- **Sizing:** no **`size`** prop; **`font-size`** / **`line-height`** inherit from the parent. Layout wrappers and typography tokens control rhythm.
+- **Extras:** **`className`** and native **`pre`** attributes ( **`id`**, ARIA, **`data-*`**, handlers) via **`…rest`**.
 
-- **When to use** — partner docs, marketing pages, or in-app help where you need a short snippet that matches the kit’s typography and theme.
-- **When to use** — API reference cards, integration guides, or internal tools showing request bodies, configs, or generated output you control.
-- **When to use** — pairing a snippet with surrounding copy (`Typography`, labels) where the block should stay non-interactive and read-only.
-- **When not to use** — raw or untrusted user input as `code` (markup is injected via `dangerouslySetInnerHTML`).
-- **When not to use** — languages other than TS/TSX or cases that need a full parser or line numbers, copy buttons, and tabs (add those in your app layer).
-- **When not to use** — when you need a focusable, editable code field (use an input or a dedicated editor instead).
+## Extended
 
-## Composition
+### About
 
-- The public API is the `CodeBlock` object with one subpart: **`Root`**.
-- **`Root`** renders a native **`pre`**. Highlighted content is injected as a single inner **`code`** element; do not pass `children` or `dangerouslySetInnerHTML` yourself — they are excluded from the props type.
-- Pass the source as the **`code`** string prop. Optional **`colorScheme`** selects the highlighting palette (`data-theme` on `pre`).
+`CodeBlock` is a static, read-only presentation component: it shows a source string with kit-aligned monospace and a light or dark token palette.
+
+- **Use** for partner docs, marketing, in-app help, API reference cards, integration guides, or internal tools when the snippet is **trusted** and TS/TSX-oriented highlighting is enough.
+- **Use** with surrounding copy ([Typography](../typography/COMPONENT.md), headings, captions) for documentation-style layouts.
+- **Do not use** for **untrusted** input (inner HTML is injected).
+- **Do not use** when you need another language grammar, line numbers, copy-to-clipboard, or tabs — implement those in the app layer.
+- **Do not use** for an editable or primary focus target for typing (use inputs or an editor).
+
+### Composition
+
+- Public API: **`CodeBlock`** object with **`Root`**.
+- **`Root`** renders a **`pre`**; highlighted markup is a single inner **`code`** (do not supply **`children`**).
+- Pass source as **`code`**. Optional **`colorScheme`** sets highlighting palette / **`data-theme`** on **`pre`**.
+
+### Scenarios (playground)
+
+Same order as `playground/sections/CodeBlockSection.tsx`. Snippets use the `@/` alias and may use `usePlaygroundTheme` for `colorScheme`.
+
+| Scenario | Snippet |
+|----------|---------|
+| Sizes — wrapper `font-size` / `line-height`; no `size` prop | [`sizes.tsx`](../../../playground/snippets/code-block/sizes.tsx) |
+| Variants — `colorScheme` light and dark side by side | [`variants.tsx`](../../../playground/snippets/code-block/variants.tsx) |
+| Controlled — `code` from parent state; switch between snippets | [`controlled.tsx`](../../../playground/snippets/code-block/controlled.tsx) |
+| Composition — documentation-style card (Typography + code) | [`composition.tsx`](../../../playground/snippets/code-block/composition.tsx) |
+| Full width — narrow column, `codeBlockFullBleed`, horizontal scroll | [`full-width.tsx`](../../../playground/snippets/code-block/full-width.tsx) |
+| Features — `id`, `aria-label`, `data-*`, trailing spaces + `trimEnd` | [`features.tsx`](../../../playground/snippets/code-block/features.tsx) |
+
+### Package examples (`examples/`)
+
+Recipes import **`prime-ui-kit`** (no playground path alias).
+
+| Scenario | File |
+|----------|------|
+| Minimal usage | [`minimal.tsx`](./examples/minimal.tsx) |
+| Controlled — `code` из состояния (рецепт на `ButtonGroup`) | [`controlled.tsx`](./examples/controlled.tsx) |
+| API response preview (JSON body) | [`api-response-preview.tsx`](./examples/api-response-preview.tsx) |
+| Config snippet (TS config) | [`config-snippet.tsx`](./examples/config-snippet.tsx) |
+| Error stack / log | [`error-stack.tsx`](./examples/error-stack.tsx) |
+| Tutorial step (copy + snippet) | [`tutorial-step.tsx`](./examples/tutorial-step.tsx) |
 
 ### Minimal example
 
@@ -27,32 +63,41 @@ export function Example() {
 }
 ```
 
-## Rules
+### Rules
 
-- **`code`** is required. The implementation applies **`trimEnd()`** before highlighting; leading indentation in the string is preserved aside from trailing whitespace on the whole string.
-- **`colorScheme`** defaults to **`"light"`**; use **`"dark"`** when the block sits on a dark surface so token colors stay readable.
-- **Security:** inner HTML comes from **`highlightTsxHtml`**. Only pass **trusted** strings (constants, vetted CMS content, sanitized backend output).
-- **Highlighting** uses a TS/TSX-oriented heuristic in the kit, not a full language grammar — rare syntax may not get the expected classes.
-- **No built-in `size`:** font size and line height follow the parent; control rhythm with wrapper layout and typography tokens.
-- **Accessibility:** treat the block as static prose context; add **`aria-label`**, **`aria-describedby`**, or nearby headings via standard **`pre`** attributes spread from **`…rest`** when screen readers need an explicit label.
-- **Focus:** the component does not set **`tabIndex`**; make it focusable only if your UX requires it.
+- **`code`** is required. The implementation applies **`trimEnd()`** on the whole string before highlighting; per-line content is preserved except trailing whitespace at the end of the string.
+- **`colorScheme`** defaults to **`"light"`**; use **`"dark"`** on dark surfaces so tokens stay readable.
+- **Security:** HTML comes from **`highlightTsxHtml`** only as wrapped **`code`** content; treat **`code`** as trusted.
+- **Highlighting** is TS/TSX-oriented; edge syntax may not match expectations.
+- **Accessibility:** static prose; add **`aria-label`**, **`aria-describedby`**, or headings via **`…rest`** when assistive tech needs an explicit name.
+- **Focus:** no default **`tabIndex`**; add only if your UX requires a focusable static block.
 
-## API
+### API
 
-### CodeBlock.Root
+#### CodeBlock.Root
 
 | Prop | Type | Default | Required | Description |
 |------|------|---------|----------|-------------|
-| `code` | `string` | — | Yes | TS/TSX source; trailing whitespace is trimmed with `trimEnd()` before highlighting. |
+| `code` | `string` | — | Yes | TS/TSX-oriented source; trailing whitespace trimmed with `trimEnd()` before highlighting. |
 | `colorScheme` | `CodeBlockColorScheme` (`"light" \| "dark"`) | `"light"` | No | Token palette / `data-theme` on the root `pre`. |
 | `className` | `string` | — | No | Additional class on the root `pre`. |
-| `…rest` | `Omit<React.HTMLAttributes<HTMLPreElement>, "children" \| "dangerouslySetInnerHTML">` | — | No | Other native `pre` attributes (`id`, `style`, ARIA, `data-*`, event handlers, etc.). `children` and `dangerouslySetInnerHTML` are omitted. |
+| `…rest` | `Omit<React.HTMLAttributes<HTMLPreElement>, "children" \| "dangerouslySetInnerHTML">` | — | No | Other native `pre` attributes. `children` and `dangerouslySetInnerHTML` are omitted. |
+
+The package also exports **`CodeBlockColorScheme`** and **`CodeBlockRootProps`**.
+
+### Related
 
-The package also exports **`CodeBlockColorScheme`** and **`CodeBlockRootProps`** for typing.
+- [Typography](../typography/COMPONENT.md) — headings and body around snippets.
+- [Button](../button/COMPONENT.md) — switching the active snippet from parent state (playground `controlled.tsx`).
+- [ButtonGroup](../button-group/COMPONENT.md) — segmented control for switching `code` ([`examples/controlled.tsx`](./examples/controlled.tsx)).
+- [Segmented control](../segmented-control/COMPONENT.md) — compact scenario switching.
+- [Kbd](../kbd/COMPONENT.md) — shortcut hints beside prose.
 
-## Related
+## Note for LLM assistants
 
-- [Typography](../typography/COMPONENT.md) — headings and body copy around snippets.
-- [Button](../button/COMPONENT.md) — switching multiple samples from parent state.
-- [Segmented control](../segmented-control/COMPONENT.md) — compact mode or sample switching in toolbars.
-- [Kbd](../kbd/COMPONENT.md) — shortcut hints next to prose, without duplicating the code block’s role.
+- Recommend **`CodeBlock.Root`** only; **`code`** must be a **trusted** string — flag any pattern that pipes user or CMS content without sanitization.
+- Do not suggest **`children`**, **`dangerouslySetInnerHTML`**, or wrapping the kit block to replace inner HTML.
+- Prefer **`colorScheme="dark"`** when the parent surface uses dark **`data-theme`** or dark backgrounds so contrast stays valid.
+- If the user asks for copy button, line numbers, tabs, or non-TS languages, say these are **out of kit scope** and belong in the app (or a different library).
+- For JSON-only bodies, remind that highlighting is **TS/TSX heuristic**; formatting as a template or TS-adjacent string is fine.
+- **`trimEnd()`** applies to the **entire** `code` string once, not each line.

package/src/components/code-block/examples/api-response-preview.tsx

@@ -0,0 +1,21 @@
+import { CodeBlock } from "prime-ui-kit";
+
+const RESPONSE_BODY = `{
+  "id": "ord_8f2a",
+  "status": "paid",
+  "total": 14990,
+  "currency": "RUB",
+  "items": [{ "sku": "sku-12", "qty": 2 }]
+}
+`;
+
+/** Превью тела ответа API (JSON как текст; подсветка эвристическая, как для TS-подобного синтаксиса). */
+export default function CodeBlockApiResponsePreview() {
+  return (
+    <CodeBlock.Root
+      code={RESPONSE_BODY}
+      colorScheme="light"
+      aria-label="Пример JSON ответа GET /orders/:id"
+    />
+  );
+}

package/src/components/code-block/examples/config-snippet.tsx

@@ -0,0 +1,17 @@
+import { CodeBlock } from "prime-ui-kit";
+
+const CONFIG_TS = `// vite.config.ts — фрагмент
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+
+export default defineConfig({
+  plugins: [react()],
+  server: { port: 5173, strictPort: true },
+  build: { outDir: "dist", sourcemap: true },
+});
+`;
+
+/** Фрагмент конфигурации как TS-исходник (предпочтительный формат для подсветки кита). */
+export default function CodeBlockConfigSnippet() {
+  return <CodeBlock.Root code={CONFIG_TS} colorScheme="dark" />;
+}

package/src/components/code-block/examples/controlled.tsx

@@ -0,0 +1,43 @@
+import { ButtonGroup, CodeBlock, Typography } from "prime-ui-kit";
+import { useState } from "react";
+
+const SNIPPETS: [string, string][] = [
+  [
+    "Утилита",
+    `export function clamp(n: number, min: number, max: number) {
+  return Math.min(max, Math.max(min, n));
+}
+`,
+  ],
+  [
+    "React",
+    `import { useMemo } from "react";
+
+export function useStableId(prefix: string) {
+  return useMemo(() => \`\${prefix}-\${Math.random().toString(36).slice(2)}\`, [prefix]);
+}
+`,
+  ],
+];
+
+/** Проп `code` из состояния родителя: сегменты переключают два разных фрагмента (как в playground `controlled.tsx`). */
+export default function CodeBlockControlledExample() {
+  const [index, setIndex] = useState(0);
+  const [label, code] = SNIPPETS[index] ?? SNIPPETS[0];
+
+  return (
+    <div>
+      <Typography.Root variant="body-compact" tone="muted" as="p">
+        Активный фрагмент: <strong>{label}</strong> (проп <code>code</code> из состояния).
+      </Typography.Root>
+      <ButtonGroup.Root size="s" aria-label="Выбор фрагмента кода">
+        {SNIPPETS.map(([title], i) => (
+          <ButtonGroup.Item key={title} pressed={i === index} onClick={() => setIndex(i)}>
+            {title}
+          </ButtonGroup.Item>
+        ))}
+      </ButtonGroup.Root>
+      <CodeBlock.Root code={code} colorScheme="light" />
+    </div>
+  );
+}

package/src/components/code-block/examples/error-stack.tsx

@@ -0,0 +1,19 @@
+import { CodeBlock } from "prime-ui-kit";
+
+const STACK = `Error: connect ECONNREFUSED 127.0.0.1:5432
+    at createConnectionError (node:net:1234:5)
+    at afterConnect (node:net:567:8)
+    at Query.run (/app/node_modules/pg/lib/query.js:42:10)
+    at async fetchUserById (/app/src/users.ts:18:20)
+`;
+
+/** Стек ошибки или лог — многострочная строка; читабельность на тёмной подложке через colorScheme. */
+export default function CodeBlockErrorStack() {
+  return (
+    <CodeBlock.Root
+      code={STACK}
+      colorScheme="dark"
+      aria-label="Пример стека ошибки подключения к БД"
+    />
+  );
+}

package/src/components/code-block/examples/minimal.tsx

@@ -0,0 +1,6 @@
+import { CodeBlock } from "prime-ui-kit";
+
+/** Минимальный фрагмент: один `CodeBlock.Root` и строка `code`. */
+export default function CodeBlockMinimalExample() {
+  return <CodeBlock.Root code="export const n = 1;" />;
+}

package/src/components/code-block/examples/tutorial-step.tsx

@@ -0,0 +1,28 @@
+import { CodeBlock, Typography } from "prime-ui-kit";
+
+const STEP_CODE = `import { useState } from "react";
+
+export function Counter() {
+  const [n, setN] = useState(0);
+  return (
+    <button type="button" onClick={() => setN((c) => c + 1)}>
+      Счёт: {n}
+    </button>
+  );
+}
+`;
+
+/** Шаг туториала: короткий контекст в Typography и код ниже. */
+export default function CodeBlockTutorialStep() {
+  return (
+    <div>
+      <Typography.Root variant="body-small" weight="semibold" as="p">
+        Шаг 3 — счётчик на состоянии
+      </Typography.Root>
+      <Typography.Root variant="body-compact" tone="muted" as="p">
+        Добавьте компонент и вызовите setN в обработчике клика.
+      </Typography.Root>
+      <CodeBlock.Root code={STEP_CODE} colorScheme="light" />
+    </div>
+  );
+}