prime-ui-kit 0.10.0 → 0.11.1

package/src/components/dropdown/examples/item-description.tsx

@@ -0,0 +1,30 @@
+/** A second line under an item: what an action does, and why a disabled one is unavailable, readable by everyone and read with the item — `Dropdown.ItemDescription`. */
+import { Button, Dropdown, Icon } from "prime-ui-kit";
+
+export default function DropdownItemDescriptionExample() {
+  return (
+    <Dropdown.Root>
+      <Dropdown.Trigger>
+        <Button.Root variant="soft" tone="neutral">
+          Проект
+        </Button.Root>
+      </Dropdown.Trigger>
+      <Dropdown.Content>
+        <Dropdown.Item>
+          <Dropdown.ItemIcon>
+            <Icon name="action.copy" />
+          </Dropdown.ItemIcon>
+          Дублировать
+          <Dropdown.ItemDescription>Копия без задач и участников</Dropdown.ItemDescription>
+        </Dropdown.Item>
+        <Dropdown.Item disabled tone="danger">
+          <Dropdown.ItemIcon>
+            <Icon name="action.delete" />
+          </Dropdown.ItemIcon>
+          Удалить проект
+          <Dropdown.ItemDescription>Доступно владельцу проекта</Dropdown.ItemDescription>
+        </Dropdown.Item>
+      </Dropdown.Content>
+    </Dropdown.Root>
+  );
+}

package/src/components/dropdown/examples/link-items.tsx

@@ -0,0 +1,29 @@
+/** Items that navigate are real links: Cmd-click or the context menu opens them in a new tab, a plain pick closes the menu — `asChild`. */
+import { Button, Dropdown, Icon } from "prime-ui-kit";
+
+const LINKS = [
+  { href: "#deal-1042", label: "Открыть сделку" },
+  { href: "#client-nwind", label: "Карточка клиента" },
+  { href: "#invoice-318", label: "Счёт №318" },
+] as const;
+
+export default function DropdownLinkItemsExample() {
+  return (
+    <Dropdown.Root>
+      <Dropdown.Trigger>
+        <Button.Root variant="ghost" tone="neutral" aria-label="Перейти">
+          <Button.Icon>
+            <Icon name="action.externalLink" />
+          </Button.Icon>
+        </Button.Root>
+      </Dropdown.Trigger>
+      <Dropdown.Content>
+        {LINKS.map(({ href, label }) => (
+          <Dropdown.Item key={href} asChild>
+            <a href={href}>{label}</a>
+          </Dropdown.Item>
+        ))}
+      </Dropdown.Content>
+    </Dropdown.Root>
+  );
+}

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

@@ -20,7 +20,7 @@ export default function DropdownOverviewExample() {
             </Button.Icon>
           </Button.Root>
         </Dropdown.Trigger>
-        <Dropdown.Content align="end">
+        <Dropdown.Content>
           <Dropdown.Item onSelect={() => setStatus("Счёт № 4821 · отправлен")}>
             Отправить клиенту
           </Dropdown.Item>

package/src/components/dropdown/examples/structure.tsx

@@ -9,7 +9,7 @@ export default function DropdownStructureExample() {
           Анна Петрова
         </Button.Root>
       </Dropdown.Trigger>
-      <Dropdown.Content align="end">
+      <Dropdown.Content>
         <Dropdown.Header>
           <Avatar.Root size="l">
             <Avatar.Fallback>АП</Avatar.Fallback>

package/src/components/empty-page/COMPONENT.md

@@ -3,16 +3,16 @@
 **Category:** status
 **Kind:** composite
 
-> Empty state of a page, a block or a menu: icon, title, explanation and an action.
+> Empty or failed state of a page, a block or a menu: icon, title, explanation and an action — a retry for a failed load.
 
 ## When to use
 - A list, table or page has no data yet (first run) and the user should know what to do.
 - A search or filter returned nothing (`layout="compact"` inside menus and lists).
-- Data failed to load and the user can retry.
+- A region failed to load and the user can retry (`tone="danger"` + `EmptyPage.RetryButton`) — the region error of every data block.
 - Inside a card or data region that should keep its height (`layout="fill"`).
 
 ## When not to use
-- A message about the page while data is present → use [Banner](../banner/COMPONENT.md).
+- A message about the page while data is present (a failed refresh over shown data) → use [Banner](../banner/COMPONENT.md); the data stays.
 - A transient result of an action → use [Notification](../notification/COMPONENT.md).
 - Loading in progress → a [Skeleton](../skeleton/COMPONENT.md) of the content (a [Spinner](../spinner/COMPONENT.md) when there is no shape to hold), not an empty state; [Crossfade](../crossfade/COMPONENT.md) swaps it for the data or the empty state.
 
@@ -23,11 +23,12 @@ import { EmptyPage } from "prime-ui-kit";
 
 ## Anatomy
 ```
-EmptyPage.Root               centered column; size, layout
-├─ EmptyPage.Icon            tile with one icon; tone
+EmptyPage.Root               centered column; size, layout, tone (role="alert" when danger)
+├─ EmptyPage.Icon            tile with one icon; tone (default: the root's)
 ├─ EmptyPage.Title           <h2> (as)
 ├─ EmptyPage.Description     <p>
 └─ EmptyPage.Actions         row of buttons
+   └─ EmptyPage.RetryButton  the kit's «Повторить» (Button outline neutral + refresh icon); onRetry
 ```
 
 ## API
@@ -41,6 +42,8 @@ EmptyPage.Root               centered column; size, layout
 |---|---|---|---|
 | `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `"m"` | Icon tile, title type and padding; given to the controls inside. |
 | `layout` | `"default" \| "fill" \| "compact"` | `"default"` | `default` sizes by content; `fill` stretches to the parent's height and centers; `compact` — a quiet state inside a menu or list: smaller text and icon, no entrance motion. |
+| `tone` | `"neutral" \| "danger"` | `"neutral"` | `neutral` — nothing here (yet); `danger` — the region failed to load: the icon tile turns danger and the root is `role="alert"` unless you pass a `role`. |
+| `labels` | `Partial<EmptyPageLabels>` | — | Built-in strings, see Labels. |
 | `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `className`, `role` (`status` in a filtered list), `aria-labelledby` and the other div attributes. |
 
 ### EmptyPage.Icon
@@ -48,7 +51,7 @@ EmptyPage.Root               centered column; size, layout
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `tone` | `"neutral" \| "accent" \| "danger"` | `"neutral"` | `neutral` — no data yet, `accent` — a first run and a call to start, `danger` — a failed load. |
+| `tone` | `"neutral" \| "accent" \| "danger"` | `the root's `tone`` | `neutral` — no data yet, `accent` — a first run and a call to start, `danger` — a failed load. |
 | `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `children` (the icon), `className` and the other div attributes. |
 
 ### EmptyPage.Title · EmptyPage.Description
@@ -66,6 +69,14 @@ EmptyPage.Root               centered column; size, layout
 |---|---|---|---|
 | `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `children` (Buttons in the same `size`), `className` and the other div attributes. |
 
+### EmptyPage.RetryButton
+`ref` → `HTMLButtonElement`. The kit's retry of a failed region: an outline neutral Button with the refresh icon and `labels.retry`, in the root's tier. Put it in `EmptyPage.Actions`.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `onRetry` | `() => void \| Promise<void>` | — (required) | Loads the region again. A returned Promise keeps the button loading until it settles; on reject the error state stays and the button is ready again. |
+| `…rest` | `Omit<ButtonHTMLAttributes<HTMLButtonElement>, "onClick" \| "type">` | — | `children` (text instead of `labels.retry`), `disabled`, `className` and the other button attributes. |
+
 ## Variants
 
 ### size
@@ -82,10 +93,16 @@ EmptyPage.Root               centered column; size, layout
 | `fill` | stretches to the parent's height, centered | a card or data region that keeps its height | |
 | `compact` | panel padding, body-s title, caption description, small tile, no entrance motion | menus, listboxes, command lists that filter to nothing | |
 
-### tone (Icon)
+### tone (Root)
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
-| `neutral` | muted tile | no data yet | yes |
+| `neutral` | muted tile | nothing here (yet) | yes |
+| `danger` | danger-soft tile; the root announces itself (`role="alert"`) | the region failed to load | |
+
+### tone (Icon, overrides the root's)
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `neutral` | muted tile | no data yet | the root's tone |
 | `accent` | accent-soft tile | first run, a call to start | |
 | `danger` | danger-soft tile | failed to load | |
 
@@ -95,18 +112,24 @@ EmptyPage.Root               centered column; size, layout
 | first render | mount (not `compact`) | parts rise in (`enterMotion`), `--prime-motion-stagger` apart; collapses under reduced motion |
 | layout | `layout` | `data-layout="fill" \| "compact"` (none for `default`) |
 | size | `size` | `data-size`; controls inside get the same tier |
+| error | `tone="danger"` | `data-tone="danger"`, `role="alert"` (unless a `role` is passed), the icon tile danger |
+| retrying | `onRetry` returned a Promise that is pending | the RetryButton shows its loading state (`aria-busy`, spinner in place of the icon, same width) and ignores presses; resolve — the owner swaps the region (Crossfade), reject — the error stays and the button is ready |
 
 ## Layout & spacing
 - Centered column, gap `--prime-space-2`; icon → title adds `--prime-space-2`, actions sit `--prime-space-3` lower.
 - Title and description are capped at the reading width; actions wrap.
-- Pass the same `size` to the buttons in Actions.
+- Buttons in Actions take the root's tier from context (`EmptyPage.RetryButton` too).
+- A region error fills its region like the data would (`layout="fill"` in a card), so the swap to data does not move the page.
 
 ## Accessibility
 
 ### Keyboard
-No keyboard interaction.
+| Key | Action |
+|---|---|
+| `Enter` · `Space` | On `EmptyPage.RetryButton`: retry the load; while the retry runs the button is loading and ignores presses. |
 
 ### ARIA
+- `tone="danger"` makes the root `role="alert"`, so the failure is announced when it appears; a `role` you pass replaces it.
 - The title is an `<h2>` (`as` picks `h3` / `h4` by the outline, `p` inside menus, lists and table cells); link the root to it with `aria-labelledby` when the empty state replaces a whole region.
 - In a filtered menu or list set `role="status"`, so screen readers announce «Ничего не найдено».
 - The icon is decorative: pass it with `aria-hidden`.
@@ -114,26 +137,31 @@ No keyboard interaction.
 ### Labels
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
 
-No `labels`.
+| Key | Default | Used for |
+|---|---|---|
+| `retry` | `"Повторить"` | Text of `EmptyPage.RetryButton`. |
 
 ## Examples
 | Example | Shows |
 |---|---|
 | [overview.tsx](examples/overview.tsx) | An empty search result: icon, title, description and two actions — `EmptyPage.Icon`, `EmptyPage.Actions`. |
+| [variants.tsx](examples/variants.tsx) | The tone tells why the area is empty: no data yet, a first run, or a failed load with a retry — `tone`, `EmptyPage.RetryButton`. |
 | [sizes.tsx](examples/sizes.tsx) | Every tier changes the icon tile, the title and the padding; buttons in Actions take the same size — `size`. |
-| [icon-tones.tsx](examples/icon-tones.tsx) | The tile tone tells why the area is empty: no data yet, a first run, or a failed load — `tone`. |
 | [data-region.tsx](examples/data-region.tsx) | An empty data region: the empty state stretches over the rest of a card with a header — `layout`. |
+| [region-error.tsx](examples/region-error.tsx) | A data region that failed to load: the error state takes the region, the retry shows its loading until the data cross-fades in — `tone`, `layout`, `EmptyPage.RetryButton`, `onRetry`. |
 | [compact.tsx](examples/compact.tsx) | The quiet empty state of a search panel: no entrance motion, smaller text, a paragraph title, one action — `layout`, `as`. |
 | [narrow.tsx](examples/narrow.tsx) | In a 320 px side panel the text wraps under the tile and the actions wrap to a second line. |
 
 ## Mistakes
-- Buttons in a non-`m` EmptyPage without `size` → pass the same `size` to them.
-- `tone` on `EmptyPage.Root` → `tone` belongs to `EmptyPage.Icon`.
+- Buttons in a non-`m` EmptyPage without `size` → they take the root's tier from context; do not pass another one.
+- A failed load drawn as a neutral empty state → `tone="danger"` on the root; the icon follows.
+- A hand-made «Повторить» with its own pending flag → `EmptyPage.RetryButton` with an async `onRetry`.
+- Clearing the error the moment the retry starts → keep the error state until the retry settles; the button shows the wait.
 - Showing an empty state while data is loading → show loading first.
 - Several primary buttons → one primary, placed last.
 - A default empty state inside a menu → use `layout="compact"`; the entrance motion on every keystroke is noise.
 - An `<h2>` title inside a menu, listbox or table cell → `EmptyPage.Title as="p"`.
 
 ## Related
-- **Built from:** —
-- **See also:** [DataTable](../data-table/COMPONENT.md), [Banner](../banner/COMPONENT.md), [Notification](../notification/COMPONENT.md), [Card](../card/COMPONENT.md)
+- **Built from:** [Button](../button/COMPONENT.md) (RetryButton), Icon (`action.refresh`)
+- **See also:** [Crossfade](../crossfade/COMPONENT.md), [DataTable](../data-table/COMPONENT.md), [Banner](../banner/COMPONENT.md), [Notification](../notification/COMPONENT.md), [Card](../card/COMPONENT.md)

package/src/components/empty-page/examples/examples.module.css

@@ -1,6 +1,6 @@
 /* Layout of the EmptyPage scenarios: semantic tokens only. */
 
-/* sizes.tsx, icon-tones.tsx: cells of 16rem that wrap; an odd last cell stays centered. */
+/* sizes.tsx, variants.tsx: cells of 16rem that wrap; an odd last cell stays centered. */
 .grid {
   display: flex;
   flex-wrap: wrap;
@@ -16,11 +16,28 @@
   min-width: 0;
 }
 
-/* data-region.tsx: the Card's minimum height that the empty state fills. */
+/* data-region.tsx, region-error.tsx: the Card's minimum height that the state fills. */
 .region {
   min-height: calc(var(--prime-space-24) * 3);
 }
 
+/* region-error.tsx: the loaded rows — client and amount at the two ends. */
+.list {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-space-3);
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+.row {
+  display: flex;
+  justify-content: space-between;
+  gap: var(--prime-space-4);
+  min-width: 0;
+}
+
 /* compact.tsx: a floating panel (menu / listbox) the compact empty state sits in. */
 .panel {
   box-sizing: border-box;

package/src/components/empty-page/examples/region-error.tsx

@@ -0,0 +1,86 @@
+/** A data region that failed to load: the error state takes the region, the retry shows its loading until the data cross-fades in — `tone`, `layout`, `EmptyPage.RetryButton`, `onRetry`. */
+import { Button, Card, Crossfade, EmptyPage, Icon, Skeleton, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+type RegionState = "loading" | "error" | "ready";
+
+const INVOICES = [
+  { id: "inv-4821", client: "ООО «Гранит»", amount: "94 750 ₽" },
+  { id: "inv-4822", client: "АО «Альфа Медиа»", amount: "380 000 ₽" },
+  { id: "inv-4823", client: "ИП Орлов Д. С.", amount: "18 000 ₽" },
+];
+
+const RESPONSE_MS = 1200;
+
+const wait = (ms: number) => new Promise<void>((resolve) => window.setTimeout(resolve, ms));
+
+export default function EmptyPageRegionErrorExample() {
+  const [state, setState] = React.useState<RegionState>("loading");
+
+  // The first request fails, as a server that is down would.
+  React.useEffect(() => {
+    if (state !== "loading") return;
+    const id = window.setTimeout(() => setState("error"), RESPONSE_MS);
+    return () => window.clearTimeout(id);
+  }, [state]);
+
+  const retry = async () => {
+    await wait(RESPONSE_MS);
+    setState("ready");
+  };
+
+  return (
+    <Card.Root role="region" aria-labelledby="invoices-title" className={styles.region}>
+      <Card.Header>
+        <Card.Title id="invoices-title">Счета к оплате</Card.Title>
+        <Button.Root
+          variant="ghost"
+          tone="neutral"
+          size="s"
+          disabled={state === "loading"}
+          onClick={() => setState("loading")}
+        >
+          <Button.Icon>
+            <Icon name="action.refresh" />
+          </Button.Icon>
+          Обновить
+        </Button.Root>
+      </Card.Header>
+      <Card.Body>
+        <Crossfade state={state} aria-busy={state === "loading"}>
+          {state === "loading" ? (
+            <Skeleton lines={3} />
+          ) : state === "error" ? (
+            <EmptyPage.Root layout="fill" size="s" tone="danger" aria-labelledby="invoices-error">
+              <EmptyPage.Icon>
+                <Icon name="status.offline" />
+              </EmptyPage.Icon>
+              <EmptyPage.Title as="h4" id="invoices-error">
+                Не удалось загрузить счета
+              </EmptyPage.Title>
+              <EmptyPage.Description>Сервер не ответил. Данные не потеряны.</EmptyPage.Description>
+              <EmptyPage.Actions>
+                <EmptyPage.RetryButton onRetry={retry} />
+              </EmptyPage.Actions>
+            </EmptyPage.Root>
+          ) : (
+            <ul className={styles.list}>
+              {INVOICES.map((invoice) => (
+                <li key={invoice.id} className={styles.row}>
+                  <Typography as="span" variant="body-m">
+                    {invoice.client}
+                  </Typography>
+                  <Typography as="span" variant="body-m" tone="secondary">
+                    {invoice.amount}
+                  </Typography>
+                </li>
+              ))}
+            </ul>
+          )}
+        </Crossfade>
+      </Card.Body>
+    </Card.Root>
+  );
+}

package/src/components/empty-page/examples/variants.tsx

@@ -0,0 +1,43 @@
+/** The tone tells why the area is empty: no data yet, a first run, or a failed load with a retry — `tone`, `EmptyPage.RetryButton`. */
+import { Button, EmptyPage, Icon } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+/** A retry that answers after a second, as a slow server would. */
+const retryInbox = () => new Promise<void>((resolve) => window.setTimeout(resolve, 1000));
+
+export default function EmptyPageVariantsExample() {
+  return (
+    <div className={styles.grid}>
+      <EmptyPage.Root size="s" aria-labelledby="tone-neutral">
+        <EmptyPage.Icon>
+          <Icon name="object.inbox" />
+        </EmptyPage.Icon>
+        <EmptyPage.Title id="tone-neutral">Входящих нет</EmptyPage.Title>
+        <EmptyPage.Description>Новые заявки появятся здесь.</EmptyPage.Description>
+      </EmptyPage.Root>
+
+      <EmptyPage.Root size="s" aria-labelledby="tone-accent">
+        <EmptyPage.Icon tone="accent">
+          <Icon name="object.rocket" />
+        </EmptyPage.Icon>
+        <EmptyPage.Title id="tone-accent">Создайте первый проект</EmptyPage.Title>
+        <EmptyPage.Description>Проекты объединяют задачи, файлы и команду.</EmptyPage.Description>
+        <EmptyPage.Actions>
+          <Button.Root>Создать проект</Button.Root>
+        </EmptyPage.Actions>
+      </EmptyPage.Root>
+
+      <EmptyPage.Root size="s" tone="danger" aria-labelledby="tone-danger">
+        <EmptyPage.Icon>
+          <Icon name="status.offline" />
+        </EmptyPage.Icon>
+        <EmptyPage.Title id="tone-danger">Не удалось загрузить</EmptyPage.Title>
+        <EmptyPage.Description>Сервер не ответил. Проверьте соединение.</EmptyPage.Description>
+        <EmptyPage.Actions>
+          <EmptyPage.RetryButton onRetry={retryInbox} />
+        </EmptyPage.Actions>
+      </EmptyPage.Root>
+    </div>
+  );
+}

package/src/components/example-frame/COMPONENT.md

@@ -79,14 +79,15 @@ Frame look: the chrome is a layer of the surface ladder (`data-depth`, one above
 ## States
 | State | Driven by | DOM |
 |---|---|---|
-| pane | toolbar switch (internal, starts at Preview) | preview stage or code pane is rendered |
+| pane | toolbar switch (internal, starts at Preview) | preview stage or code pane is rendered; the device switch shows only with the preview |
 | viewport | `viewport` / `defaultViewport` | `data-viewport` on the preview viewport |
 | theme | `colorScheme` / `defaultColorScheme` | `data-theme` on the stage and code pane |
 | layout | `previewLayout` | `data-preview-layout` on the stage |
 | copy | copy button | its `aria-label` switches to `labels.copied` / `labels.copyError` for 2 s; on success the copy glyph cross-fades to a check (`data-copy-state`) |
 
 ## Layout & spacing
-- The frame is `max-width: 100%`; long code lines scroll inside the code pane instead of widening the page.
+- The frame is `max-width: 100%`; long code lines scroll inside the code pane instead of widening the page. The code pane is at most `min(512px, 70vh)` high and scrolls both ways.
+- The stage is at least 160 high with `--prime-space-6` / `--prime-space-4` padding; content wider than it is clipped (`matrix` scrolls instead).
 - The toolbar wraps below 40rem of frame width; below 25rem the visible device labels are hidden (icons stay, each option keeps a screen-reader name).
 - The device width switches at once: `max-width` is layout, so it does not animate.
 - Stack frames one per demo block; spacing between blocks comes from the page.

package/src/components/fieldset/COMPONENT.md

@@ -0,0 +1,107 @@
+# Fieldset
+
+**Category:** inputs
+**Kind:** primitive
+
+> A frameless group of related form fields: a native `<fieldset>` with a `title-s` legend, the form rhythm between its fields and one `disabled` for all of them.
+
+## When to use
+- A long form split into groups («Реквизиты», «Контакты», «Уведомления»), each with a heading 16 above its fields.
+- Disabling every field of a form while its request runs: `disabled` on the group instead of `disabled` on each field.
+- A group that needs a native name for assistive tech (`<legend>`), e.g. a set of switches under one heading.
+
+## When not to use
+- One choice among options with a heading → [Radio](../radio/COMPONENT.md) `Radio.Group label`, a [SegmentedControl](../segmented-control/COMPONENT.md) or [ButtonGroup](../button-group/COMPONENT.md) `label`.
+- A bounded block with a surface (a settings panel) → [Card](../card/COMPONENT.md) `Card.Root`; a Fieldset inside it groups the fields.
+- A page section with a title and actions → [PageContent](../page-content/COMPONENT.md) sections.
+- A single field's label → the field's own `label`.
+
+## Import
+```tsx
+import { Fieldset } from "prime-ui-kit";
+```
+
+## Anatomy
+```
+Fieldset           <fieldset>: no border, padding or fill; native disabled + the kit's disabled context
+├─ <legend>        `label`: the heading, title-s, names the group
+├─ <p>             `description`: secondary text, aria-describedby
+└─ fields          children, field → field 20
+```
+A leaf: everything is a prop or a child. A row of two fields inside is the consumer's grid.
+
+## API
+
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+### Fieldset
+`ref` → `HTMLFieldSetElement`. A native `<fieldset>` without border, padding or fill: the `<legend>` heading, an optional description, then the children at the form rhythm. `disabled` disables every control inside.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `label` | `ReactNode` | — | Group heading in the native `<legend>` (`title-s`); it names the group for assistive tech. Without it give the fieldset an `aria-label` when the group needs a name. |
+| `description` | `ReactNode` | — | Secondary text under the heading (`body-s`, secondary), linked through `aria-describedby`. |
+| `disabled` | `boolean` | `false` | Disables every control inside, native and kit (they take their own disabled look, ARIA and keyboard); nested groups inherit it. Use it while the form's request runs. |
+| `children` | `ReactNode` | — (required) | The fields, stacked 20 apart; a row of two fields is the consumer's grid. |
+| `…rest` | `Omit<FieldsetHTMLAttributes<HTMLFieldSetElement>, "children" \| "disabled">` | — | `className`, `name`, `form`, `aria-*` and the other attributes of the `<fieldset>`. |
+
+## Variants
+Fieldset has no `variant`, `tone` or `size`: fields keep their own tier (or the host's).
+
+### Flags
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `disabled` | Every control inside in its disabled look; the heading and the description keep their color | While the form's request runs; a section the person cannot edit | `false` |
+
+**Combinations**
+- Recommended: groups 32 apart in the form, a `label` on each; `disabled={saving}` on every group and `loading` on the submit button outside them.
+- Allowed but rare: no `label` — a group only for `disabled`; give it an `aria-label` when the group itself needs a name.
+- Pointless: a description without a heading.
+- Forbidden: a border, padding or fill added to the group — the group is made by proximity; use a Card when it needs a surface.
+
+## States
+| State | Driven by | DOM |
+|---|---|---|
+| disabled | `disabled` (or a disabled Fieldset around it) | native `disabled` + `data-disabled="true"` on the `<fieldset>`; native controls inside match `:disabled`; kit controls take their own disabled state (`data-disabled`, `aria-disabled`, native `disabled`) from the context |
+
+A Button inside a disabled group is disabled too (it reads the same context), so the submit button sits outside the group and shows `loading` while the request runs. `FormData` skips the controls of a disabled fieldset: read the form before disabling it.
+
+## Layout & spacing
+- Heading → fields `--prime-space-4` (16); heading → description `--prime-space-1` (4); description → fields `--prime-space-4`; field → field `--prime-space-5` (20).
+- Group → group `--prime-space-8` (32) — set by the form around the groups.
+- `width: 100%`, `min-width: 0` (the native fieldset's `min-content` minimum is reset), so long values never widen the form.
+
+## Accessibility
+
+### Keyboard
+| Key | Action |
+|---|---|
+| `Tab` | Moves through the group's fields; the fields of a disabled group are skipped. |
+
+### ARIA
+- The native `<fieldset>` is a group (`role="group"`) named by the `<legend>` text from `label`; without a heading give it `aria-label`.
+- `description` is linked to the group through `aria-describedby`.
+- `disabled` disables the native controls inside and passes a context to kit controls: they set their own `disabled` / `aria-disabled` and drop out of the Tab order.
+
+### Labels
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+No `labels`.
+
+## Examples
+| Example | Shows |
+|---|---|
+| [overview.tsx](examples/overview.tsx) | A group of contact fields under a heading with a short description, no frame of its own — `label`, `description`. |
+| [states.tsx](examples/states.tsx) | An enabled group next to a disabled one: every kit control inside takes its disabled look — `disabled`. |
+| [in-form.tsx](examples/in-form.tsx) | A client form in two groups: while the request runs every field inside is disabled at once and the submit button shows its progress — `label`, `disabled`. |
+
+## Mistakes
+- A raw `<fieldset disabled>` around kit controls → `Fieldset disabled`; the raw one leaves choice rows, segments and triggers in their enabled look.
+- `disabled` on every field of a saving form → one `disabled` on the group.
+- A `Typography` heading + `aria-labelledby` inside a hand-reset fieldset → `label`.
+- Reading `new FormData(form)` after disabling the group → the disabled fields are missing; read it first.
+- A border or a fill around the group → none; groups are separated by air, a surface is a Card.
+
+## Related
+- **Built from:** —
+- **See also:** [Card](../card/COMPONENT.md) (a surface around the groups), [Input](../input/COMPONENT.md) (takes its disabled look from the group), [Button](../button/COMPONENT.md) (the submit with `loading`, outside the group), [LoginForm](../login-form/COMPONENT.md) (its fields wrapped in `Fieldset disabled` while signing in), [Radio](../radio/COMPONENT.md)

package/src/components/fieldset/examples/examples.module.css

@@ -0,0 +1,14 @@
+/* Layout of the Fieldset scenarios: semantic tokens only. */
+
+/* in-form.tsx: group → group 32, groups → actions 32 (foundation §1); one readable column. */
+.form {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-space-8);
+  width: min(100%, var(--prime-modal-width-s));
+}
+
+.actions {
+  display: flex;
+  justify-content: flex-end;
+}

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

@@ -0,0 +1,59 @@
+/** A client form in two groups: while the request runs every field inside is disabled at once and the submit button shows its progress — `label`, `disabled`. */
+import { Button, Fieldset, Input, Radio, Switch } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+const SAVE_DELAY_MS = 1200;
+
+export default function FieldsetInFormExample() {
+  const [saving, setSaving] = React.useState(false);
+  const [saved, setSaved] = React.useState(false);
+
+  const submit = (event: React.FormEvent<HTMLFormElement>) => {
+    event.preventDefault();
+    setSaving(true);
+    setSaved(false);
+    window.setTimeout(() => {
+      setSaving(false);
+      setSaved(true);
+    }, SAVE_DELAY_MS);
+  };
+
+  return (
+    <form className={styles.form} noValidate onSubmit={submit} onChange={() => setSaved(false)}>
+      <Fieldset label="Реквизиты" disabled={saving}>
+        <Radio.Group label="Тип клиента" defaultValue="company" orientation="horizontal">
+          <Radio.Root value="company">
+            <Radio.Label>Компания</Radio.Label>
+          </Radio.Root>
+          <Radio.Root value="person">
+            <Radio.Label>ИП</Radio.Label>
+          </Radio.Root>
+        </Radio.Group>
+        <Input.Root label="Название" required>
+          <Input.Wrapper>
+            <Input.Field name="name" defaultValue="ООО «Северный ветер»" />
+          </Input.Wrapper>
+        </Input.Root>
+      </Fieldset>
+      <Fieldset
+        label="Уведомления"
+        description="Письма уходят на почту для счетов."
+        disabled={saving}
+      >
+        <Switch.Root name="invoices" defaultChecked>
+          <Switch.Label>Новые счета</Switch.Label>
+        </Switch.Root>
+        <Switch.Root name="reminders">
+          <Switch.Label>Напоминания об оплате</Switch.Label>
+        </Switch.Root>
+      </Fieldset>
+      <div className={styles.actions}>
+        <Button.Root type="submit" loading={saving} tone={saved ? "success" : "accent"}>
+          {saved ? "Сохранено" : "Сохранить"}
+        </Button.Root>
+      </div>
+    </form>
+  );
+}

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

@@ -0,0 +1,22 @@
+/** A group of contact fields under a heading with a short description, no frame of its own — `label`, `description`. */
+import { Fieldset, Icon, Input } from "prime-ui-kit";
+
+export default function FieldsetOverviewExample() {
+  return (
+    <Fieldset label="Контакты" description="На эти адреса уйдут счета и закрывающие документы.">
+      <Input.Root label="Почта для счетов">
+        <Input.Wrapper>
+          <Input.Icon side="start">
+            <Icon name="field.email" />
+          </Input.Icon>
+          <Input.Field type="email" defaultValue="billing@severny-veter.ru" />
+        </Input.Wrapper>
+      </Input.Root>
+      <Input.Root label="Телефон бухгалтерии" optional>
+        <Input.Wrapper>
+          <Input.Field type="tel" defaultValue="+7 812 555-01-42" />
+        </Input.Wrapper>
+      </Input.Root>
+    </Fieldset>
+  );
+}