prime-ui-kit 0.15.0 → 0.17.0

package/src/components/checkbox/examples/in-form.tsx

@@ -1,5 +1,5 @@
-/** Consent in a sign-up form: a hint under the text, an error after a submit without the tick — `required`, `hint`, `error`. */
-import { Button, Checkbox } from "prime-ui-kit";
+/** Consent in a sign-up form: the required tick and an optional subscription, a hint under the text, an error after a submit without the tick — `required`, `optional`, `hint`, `error`. */
+import { Button, Checkbox, Fieldset } from "prime-ui-kit";
 import * as React from "react";
 
 import styles from "./examples.module.css";
@@ -15,20 +15,20 @@ export default function CheckboxInFormExample() {
 
   return (
     <form className={styles.form} noValidate onSubmit={submit}>
-      <Checkbox.Root
-        name="terms"
-        required
-        error={error}
-        onCheckedChange={(checked) => checked && setError(undefined)}
-      >
-        <Checkbox.Label>Принимаю условия оферты</Checkbox.Label>
-      </Checkbox.Root>
-      <Checkbox.Root name="news" hint="Не чаще раза в месяц, отписаться можно в профиле">
-        <Checkbox.Label>Получать новости продукта</Checkbox.Label>
-      </Checkbox.Root>
-      <div className={styles.formActions}>
-        <Button.Root type="submit">Создать аккаунт</Button.Root>
-      </div>
+      <Fieldset>
+        <Checkbox.Root
+          name="terms"
+          required
+          error={error}
+          onCheckedChange={(checked) => checked && setError(undefined)}
+        >
+          <Checkbox.Label>Принимаю условия оферты</Checkbox.Label>
+        </Checkbox.Root>
+        <Checkbox.Root name="news" optional hint="Не чаще раза в месяц, отписаться можно в профиле">
+          <Checkbox.Label>Получать новости продукта</Checkbox.Label>
+        </Checkbox.Root>
+      </Fieldset>
+      <Button.Root type="submit">Создать аккаунт</Button.Root>
     </form>
   );
 }

package/src/components/checkbox/examples/indicator.tsx

@@ -1,80 +1,35 @@
-/** The box alone in a multi-select list: the option row carries `aria-selected`, the box only shows it — `Checkbox.Indicator`. */
-import { Checkbox, Typography } from "prime-ui-kit";
+/** The box alone on selectable tiles: the toggle button carries `aria-pressed`, the box only shows it — `Checkbox.Indicator`. */
+import { Card, Checkbox } from "prime-ui-kit";
 import * as React from "react";
 
 import styles from "./examples.module.css";
 
-const CITIES: { value: string; label: string; disabled?: boolean }[] = [
-  { value: "msk", label: "Москва" },
-  { value: "spb", label: "Санкт-Петербург" },
-  { value: "kzn", label: "Казань" },
-  { value: "tver", label: "Тверь · закрыт", disabled: true },
+const MODULES = [
+  { value: "crm", label: "CRM и сделки", price: "2 400 ₽" },
+  { value: "stock", label: "Складской учёт", price: "1 900 ₽" },
+  { value: "edo", label: "Электронный документооборот", price: "1 200 ₽" },
 ];
 
-/** One tab stop: arrows move the focused row (wrapping), Home / End jump to the ends. */
-function nextIndex(key: string, index: number, count: number): number | null {
-  if (key === "ArrowDown") return (index + 1) % count;
-  if (key === "ArrowUp") return (index - 1 + count) % count;
-  if (key === "Home") return 0;
-  if (key === "End") return count - 1;
-  return null;
-}
-
 export default function CheckboxIndicatorExample() {
-  const [selected, setSelected] = React.useState<string[]>(["msk"]);
-  const [active, setActive] = React.useState(0);
-  const optionRefs = React.useRef<(HTMLDivElement | null)[]>([]);
+  const [selected, setSelected] = React.useState<string[]>(["crm"]);
 
-  const toggle = (city: (typeof CITIES)[number]) => {
-    if (city.disabled) return;
+  const toggle = (value: string) =>
     setSelected((current) =>
-      current.includes(city.value)
-        ? current.filter((item) => item !== city.value)
-        : [...current, city.value],
+      current.includes(value) ? current.filter((item) => item !== value) : [...current, value],
     );
-  };
 
   return (
-    <div
-      role="listbox"
-      aria-label="Города доставки"
-      aria-multiselectable
-      className={styles.optionList}
-      onKeyDown={(event) => {
-        const next = nextIndex(event.key, active, CITIES.length);
-        if (next === null) return;
-        event.preventDefault();
-        setActive(next);
-        optionRefs.current[next]?.focus();
-      }}
-    >
-      {CITIES.map((city, index) => {
-        const isSelected = selected.includes(city.value);
+    <div className={styles.tiles}>
+      {MODULES.map((module) => {
+        const pressed = selected.includes(module.value);
         return (
-          <div
-            key={city.value}
-            ref={(node) => {
-              optionRefs.current[index] = node;
-            }}
-            role="option"
-            aria-selected={isSelected}
-            aria-disabled={city.disabled || undefined}
-            tabIndex={index === active ? 0 : -1}
-            className={styles.option}
-            onFocus={() => setActive(index)}
-            onClick={() => toggle(city)}
-            onKeyDown={(event) => {
-              if (event.key === " " || event.key === "Enter") {
-                event.preventDefault();
-                toggle(city);
-              }
-            }}
-          >
-            <Checkbox.Indicator checked={isSelected} disabled={city.disabled} />
-            <Typography as="span" variant="body-m" tone={city.disabled ? "muted" : undefined}>
-              {city.label}
-            </Typography>
-          </div>
+          <Card.Root key={module.value} variant="mini" asChild>
+            <button type="button" aria-pressed={pressed} onClick={() => toggle(module.value)}>
+              <Checkbox.Indicator checked={pressed} />
+              <Card.Label>{module.label}</Card.Label>
+              <Card.Meta>{module.price} в месяц</Card.Meta>
+            </button>
+          </Card.Root>
         );
       })}
     </div>

package/src/components/checkbox/examples/overview.tsx

@@ -1,4 +1,4 @@
-/** A checkbox with its label; a click anywhere on the row toggles it. */
+/** A checkbox with its label; a click anywhere on the row toggles it — `Checkbox.Label`, `defaultChecked`. */
 import { Checkbox } from "prime-ui-kit";
 
 export default function CheckboxOverviewExample() {

package/src/components/checkbox/examples/states.tsx

@@ -1,4 +1,4 @@
-/** Every state side by side, each labelled by its prop — `checked`, `indeterminate`, `readOnly`, `invalid`, `disabled`. */
+/** Every state side by side, each labelled by its prop — `defaultChecked`, `indeterminate`, `readOnly`, `invalid`, `disabled`. */
 import { Checkbox } from "prime-ui-kit";
 
 export default function CheckboxStatesExample() {

package/src/components/checkbox/examples/without-label.tsx

@@ -1,4 +1,4 @@
-/** Bare boxes in table rows, named by `aria-label` and submitted with `name` and `value`. */
+/** Bare boxes in table rows, named for assistive tech and submitted with the form — `aria-label`, `name`, `value`. */
 import { Checkbox } from "prime-ui-kit";
 
 import styles from "./examples.module.css";

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

@@ -23,8 +23,8 @@ import { CodeBlock } from "prime-ui-kit";
 
 ## Anatomy
 ```
-CodeBlock        <pre>; variant, colorScheme (data-theme)
-└─ code          <code> with highlighted tokens from the `code` string
+CodeBlock        <pre> (a ScrollContainer when `soft`); variant, colorScheme (data-theme)
+└─ code          <code>: the tokens of the `code` string as text in coloured spans
 ```
 
 ## API
@@ -32,7 +32,7 @@ CodeBlock        <pre>; variant, colorScheme (data-theme)
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
 
 ### CodeBlock
-`ref` → `HTMLPreElement`. Renders `<pre><code>`; the markup comes from the escaped, highlighted `code`.
+`ref` → `HTMLPreElement`. Renders `<pre><code>`: the tokens of `code` as text in coloured spans, never as HTML. A `soft` block scrolls sideways through ScrollContainer.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -40,7 +40,7 @@ CodeBlock        <pre>; variant, colorScheme (data-theme)
 | `variant` | `"soft" \| "ghost"` | `"soft"` | `soft` — a filled panel (one ladder step off its host) with padding and the `code` text role; `ghost` — bare `pre` that inherits type and background from its host. |
 | `colorScheme` | `"light" \| "dark"` | — | Fixes the theme for this block only (`data-theme`). Omit to follow the page theme. |
 | `tabIndex` | `number` | — | Default `0` for `soft` (a scrolling block stays reachable from the keyboard), none for `ghost`; pass `-1` when it never overflows. |
-| `…rest` | `Omit<HTMLAttributes<HTMLPreElement>, "children" \| "dangerouslySetInnerHTML">` | — | `className`, `aria-label` and the other `<pre>` attributes. |
+| `…rest` | `Omit<HTMLAttributes<HTMLPreElement>, "children">` | — | `className`, `aria-label` and the other `<pre>` attributes. |
 
 ## Variants
 
@@ -54,8 +54,8 @@ CodeBlock        <pre>; variant, colorScheme (data-theme)
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
 | — (omitted) | token colors and fill follow the page theme | normal case | yes |
-| `light` | light palette; the soft fill becomes that scheme's floating layer (`layer-floating-bg`) | a light sample inside a dark page | |
-| `dark` | dark palette; the soft fill becomes that scheme's floating layer (`layer-floating-bg`) | a terminal-like sample inside a light page | |
+| `light` | light palette; a soft block becomes a floating surface of that scheme and paints its ground | a light sample inside a dark page | |
+| `dark` | dark palette; a soft block becomes a floating surface of that scheme and paints its ground | a terminal-like sample inside a light page | |
 
 Syntax tokens: keywords purple (weight 500), strings teal, numbers orange, JSX tags blue, comments muted italic — palette text tokens, readable in both themes.
 
@@ -63,23 +63,27 @@ Syntax tokens: keywords purple (weight 500), strings teal, numbers orange, JSX t
 | State | Driven by | DOM |
 |---|---|---|
 | treatment | `variant` | `data-variant` (always set) |
-| fixed scheme | `colorScheme` | `data-theme` re-scopes the palette for the block |
+| fixed scheme | `colorScheme` | `data-theme` re-scopes the palette for the block; a soft block adds `data-depth="floating"` |
 | focus-visible | keyboard focus on a `soft` block | inset focus ring |
 
 ## Layout & spacing
-- `max-width: 100%`; the block takes the column width and long lines scroll horizontally (`white-space: pre`, tab size 2).
-- Heading / text → code block: `--prime-space-2` to `--prime-space-4`.
-- Constrain the column (`--prime-layout-reading-max-width` for docs), not the block.
+- `max-width: 100%`; the block takes the column width and long lines scroll horizontally inside it (`white-space: pre`, tab size 2), with the kit's thin scrollbar.
+- Heading / text → code block: space step 2–4 (8–16px).
+- Constrain the column (`Page.Root maxWidth="readable"` for docs), not the block.
 
 ## Accessibility
 
 ### Keyboard
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 | Key | Action |
 |---|---|
 | `Tab` | Focuses a `soft` block so overflowing code can be scrolled. |
 | `←` · `→` | Scroll a focused block horizontally. |
 
 ### ARIA
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 - Native `<pre>` / `<code>`; screen readers read the text.
 - A `soft` block is a Tab stop (`tabIndex=0`); pass `tabIndex={-1}` when it never overflows.
 - Give standalone blocks an `aria-label` («Команда установки»).
@@ -95,7 +99,7 @@ No `labels`.
 | [overview.tsx](examples/overview.tsx) | An API response sample on a filled panel, named for screen readers — `code`, `aria-label`. |
 | [variants.tsx](examples/variants.tsx) | A filled panel and a bare block that takes type and background from its host — `variant`. |
 | [color-scheme.tsx](examples/color-scheme.tsx) | A block fixed to one scheme looks the same in both page themes — `colorScheme`. |
-| [narrow.tsx](examples/narrow.tsx) | In a narrow column a long line scrolls inside the block and never wraps; Tab, then arrow keys. |
+| [narrow.tsx](examples/narrow.tsx) | In a narrow column a long line scrolls inside the block and never wraps; Tab, then arrow keys — `aria-label`. |
 
 ## Mistakes
 - Passing JSX children → pass the source string to `code`.
@@ -104,5 +108,5 @@ No `labels`.
 - Wrapping a soft block in another box → the block is already a filled panel.
 
 ## Related
-- **Built from:** —
+- **Built from:** [ScrollContainer](../scroll-container/COMPONENT.md)
 - **See also:** [Kbd](../kbd/COMPONENT.md), [ExampleFrame](../example-frame/COMPONENT.md), [Typography](../typography/COMPONENT.md)

package/src/components/code-block/examples/color-scheme.tsx

@@ -1,16 +1,14 @@
 /** A block fixed to one scheme looks the same in both page themes — `colorScheme`. */
 import { CodeBlock } from "prime-ui-kit";
 
-import styles from "./examples.module.css";
-
 const SAMPLE = `const retries = 3; // повторы при ошибке сети
 export const isReady = (status: "idle" | "busy") => status === "idle";`;
 
 export default function CodeBlockColorSchemeExample() {
   return (
-    <div className={styles.grid}>
+    <>
       <CodeBlock code={SAMPLE} colorScheme="light" aria-label="Светлая схема" />
       <CodeBlock code={SAMPLE} colorScheme="dark" aria-label="Тёмная схема" />
-    </div>
+    </>
   );
 }

package/src/components/code-block/examples/examples.module.css

@@ -6,16 +6,8 @@
   min-width: 0;
 }
 
-/* color-scheme.tsx: two blocks side by side, stacked when narrow. */
-.grid {
-  display: grid;
-  grid-template-columns: repeat(auto-fit, minmax(min(100%, var(--prime-panel-min-width)), 1fr));
-  gap: var(--prime-space-4);
-  width: 100%;
-}
-
 /* narrow.tsx: a column narrower than the line. */
 .narrow {
-  width: min(100%, var(--prime-modal-width-s));
+  width: min(100%, var(--prime-layout-form-width-s));
   min-width: 0;
 }

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

@@ -1,4 +1,4 @@
-/** In a narrow column a long line scrolls inside the block and never wraps; Tab, then arrow keys. */
+/** In a narrow column a long line scrolls inside the block and never wraps; Tab, then arrow keys — `aria-label`. */
 import { CodeBlock } from "prime-ui-kit";
 
 import styles from "./examples.module.css";

package/src/components/color-field/COMPONENT.md

@@ -50,9 +50,9 @@ ColorField                       field frame: label · field button · hint | er
 | `onValueChange` | `(value: string) => void` | — | Called with the new color as hex: `#RRGGBB`, or `#RRGGBBAA` when `alpha` lowers the opacity. A controlled field that does not take the value keeps its color. |
 | `presets` | `readonly ColorPreset[]` | — | Ready colors under the channels (`{ value, label }`), picked in one click; none by default. |
 | `alpha` | `boolean` | `false` | Adds the opacity slider; the value then carries alpha. |
-| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `"m"` | Field tier (height 28 · 32 · 36 · 40 · 48); the panel uses the same tier. |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | host tier, else `"m"` | Field tier (height 28 · 32 · 36 · 40 · 48); the panel uses the same tier. Without it the tier of its host, else `m`. |
 | `label` | `ReactNode` | — | Field label above; with the hex it names the field button. |
-| `required` | `boolean` | `false` | Red `*` after the label. |
+| `required` | `boolean` | `false` | Red `*` after the label; the field button is described by `labels.required` (a button takes no `aria-required`). |
 | `optional` | `boolean` | — | Muted marker right after the label text (`labels.optional`). |
 | `hint` | `ReactNode` | — | Help text under the field. Hidden while `error` is shown. |
 | `error` | `ReactNode` | — | Error message in the hint slot; implies `invalid`. |
@@ -85,6 +85,8 @@ ColorField                       field frame: label · field button · hint | er
 | `alpha` | an opacity slider under the hue; the hex gets two more digits | the color may be translucent (overlays, shadows) | `false` |
 | `disabled` | disabled fill, the color shown at half opacity, does not open | not editable now | `false` |
 | `invalid` / `error` | danger ring (+ the message) | validation failed | — |
+| `required` / `optional` | red `*` / muted «необязательно» after the label; a required field reads `labels.required` after its name | mark the minority of the form | `false` / — |
+| `focusRing` | `false`: no focus ring on the field button; the focus fill stays | a single color control where focus is obvious; never in a regular form (WCAG 2.4.7) | `true` |
 
 **Combinations**
 - Recommended: `label` + `name` inside a form; `presets` with the brand palette; `alpha` only where transparency means something.
@@ -109,6 +111,8 @@ Controlled with `value` + `onValueChange`; uncontrolled with `defaultValue`. A c
 ## Accessibility
 
 ### Keyboard
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 | Key | Action |
 |---|---|
 | `Enter` · `Space` | Open the panel from the field; in a channel cell, apply the value. |
@@ -118,6 +122,8 @@ Controlled with `value` + `onValueChange`; uncontrolled with `defaultValue`. A c
 | `Escape` | Closes the panel and returns focus to the field. |
 
 ### ARIA
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 - The field is a `<button>` with `aria-haspopup="dialog"` and `aria-expanded`; it is named by the label and the current hex (`aria-labelledby`), or by `aria-label` plus the hex.
 - The panel is `role="dialog"` named by the field; the area and the sliders are React Aria `role="slider"`, the sliders named by `labels.hue` and `labels.alpha`.
 - The ready colors are a `role="radiogroup"` named by `labels.presets`.
@@ -128,18 +134,18 @@ Controlled with `value` + `onValueChange`; uncontrolled with `defaultValue`. A c
 
 | Key | Default | Used for |
 |---|---|---|
-| `optional` | `"необязательно"` | Marker after the label when `optional`. |
-| `presets` | `"Готовые цвета"` | Accessible name of the preset swatches in the panel. |
-| `hue` | `"Оттенок, градусы"` | Hue slider and the hue cell of the channels. |
-| `alpha` | `"Непрозрачность, проценты"` | Opacity slider (`alpha`) and the opacity cell. |
-| `hex` | `"Hex"` | Hex cell of the channels. |
 | `eyeDropper` | `"Пипетка"` | Eyedropper button of the channels. |
-| `format` | `"Формат значений цвета"` | Value format select (the ColorPicker labels are shared). |
+| `hex` | `"Hex"` | Hex cell of the channels. |
+| `hue` | `"Оттенок, градусы"` | Hue slider and the hue cell of the channels. |
 | `saturation` | `"Насыщенность, проценты"` | Saturation cell. |
 | `lightness` | `"Яркость, проценты"` | Lightness cell. |
+| `alpha` | `"Непрозрачность, проценты"` | Opacity slider (`alpha`) and the opacity cell. |
 | `red` | `"Красный, 0–255"` | Red cell. |
 | `green` | `"Зелёный, 0–255"` | Green cell. |
 | `blue` | `"Синий, 0–255"` | Blue cell. |
+| `optional` | `"необязательно"` | Marker after the label when `optional`. |
+| `required` | `"обязательное поле"` | Read after the field name of a `required` field: its trigger is a button, which takes no `aria-required`. |
+| `presets` | `"Готовые цвета"` | Accessible name of the preset swatches in the panel. |
 
 ## Examples
 | Example | Shows |
@@ -159,5 +165,5 @@ Controlled with `value` + `onValueChange`; uncontrolled with `defaultValue`. A c
 - Expecting a `Color` object in `onValueChange` → the field speaks hex strings; use ColorPicker parts for `Color`.
 
 ## Related
-- **Built from:** [ColorPicker](../color-picker/COMPONENT.md) (area, sliders, channel strip, swatches), [Popover](../popover/COMPONENT.md), [ColorSwatches](../color-swatches/COMPONENT.md) (`presets`), [Button](../button/COMPONENT.md) (eyedropper), `Icon` (chevron), [Label](../label/COMPONENT.md) and [Hint](../hint/COMPONENT.md) (field frame)
+- **Built from:** [ColorPicker](../color-picker/COMPONENT.md) (area, sliders, channel strip with the eyedropper, the `presets` swatches), [Popover](../popover/COMPONENT.md), `Icon` (chevron), [Label](../label/COMPONENT.md) and [Hint](../hint/COMPONENT.md) (field frame), [VisuallyHidden](../visually-hidden/COMPONENT.md)
 - **See also:** [ColorSwatches](../color-swatches/COMPONENT.md), [ColorPicker](../color-picker/COMPONENT.md), [Datepicker](../datepicker/COMPONENT.md)

package/src/components/color-field/examples/examples.module.css

@@ -2,14 +2,13 @@
 
 /* in-form.tsx: a form in a Card. */
 .formCard {
-  width: min(100%, var(--prime-modal-width-s));
+  width: min(100%, var(--prime-layout-form-width-s));
 }
 
-/* Field → field 20. */
+/* The fields (a Fieldset), then the actions — group → actions 32. */
 .form {
-  display: flex;
-  flex-direction: column;
-  gap: var(--prime-space-5);
+  display: grid;
+  gap: var(--prime-space-8);
 }
 
 /* A row of actions at the end. */

package/src/components/color-field/examples/in-form.tsx

@@ -1,5 +1,5 @@
 /** A pipeline stage form: the color goes with the form by `name`, a calm note confirms the save — `name`, `required`. */
-import { Button, Card, Input, Typography } from "prime-ui-kit";
+import { Button, Card, Fieldset, Input, Typography } from "prime-ui-kit";
 import { ColorField } from "prime-ui-kit/color-picker";
 import * as React from "react";
 
@@ -18,18 +18,20 @@ export default function ColorFieldInFormExample() {
     <Card.Root className={styles.formCard}>
       <Card.Body>
         <form className={styles.form} noValidate onSubmit={submit}>
-          <Input.Root label="Название этапа" required>
-            <Input.Wrapper>
-              <Input.Field name="stage" defaultValue="Переговоры" />
-            </Input.Wrapper>
-          </Input.Root>
-          <ColorField
-            label="Цвет этапа"
-            required
-            name="stageColor"
-            defaultValue="#F76B15"
-            onValueChange={() => setSaved(undefined)}
-          />
+          <Fieldset>
+            <Input.Root label="Название этапа" required>
+              <Input.Wrapper>
+                <Input.Field name="stage" defaultValue="Переговоры" />
+              </Input.Wrapper>
+            </Input.Root>
+            <ColorField
+              label="Цвет этапа"
+              required
+              name="stageColor"
+              defaultValue="#F76B15"
+              onValueChange={() => setSaved(undefined)}
+            />
+          </Fieldset>
           <div className={styles.actions}>
             {saved ? (
               <Typography as="p" variant="body-s" tone="secondary" role="status">

package/src/components/color-field/examples/sizes.tsx

@@ -7,7 +7,11 @@ export default function ColorFieldSizesExample() {
   return (
     <>
       {SIZES.map((size) => (
-        <ColorField key={size} size={size} label={size} defaultValue="#0090ff" />
+        <div key={size}>
+          <div>
+            <ColorField size={size} label={size} defaultValue="#0090ff" />
+          </div>
+        </div>
       ))}
     </>
   );

package/src/components/color-field/examples/states.tsx

@@ -4,9 +4,21 @@ import { ColorField } from "prime-ui-kit/color-picker";
 export default function ColorFieldStatesExample() {
   return (
     <>
-      <ColorField label="default" defaultValue="#30a46c" />
-      <ColorField label="invalid" defaultValue="#f5f5f5" invalid />
-      <ColorField label="disabled" defaultValue="#30a46c" disabled />
+      <div>
+        <div>
+          <ColorField label="default" defaultValue="#30a46c" />
+        </div>
+      </div>
+      <div>
+        <div>
+          <ColorField label="invalid" defaultValue="#f5f5f5" invalid />
+        </div>
+      </div>
+      <div>
+        <div>
+          <ColorField label="disabled" defaultValue="#30a46c" disabled />
+        </div>
+      </div>
     </>
   );
 }