prime-ui-kit 0.9.0 → 0.9.1

package/src/components/login-form/examples/states.tsx

@@ -0,0 +1,75 @@
+/** The submit cycle: the button is busy while the request runs, a failed request shows a danger Banner and marks the password — `loading`, `invalid`. */
+import { Banner, Button, Icon, Input, LoginForm } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+export default function LoginFormStatesExample() {
+  const [pending, setPending] = React.useState(false);
+  const [failed, setFailed] = React.useState(false);
+  const timer = React.useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
+
+  React.useEffect(() => () => clearTimeout(timer.current), []);
+
+  return (
+    <div className={styles.stage}>
+      <LoginForm.Root>
+        <LoginForm.Header>
+          <LoginForm.Logo>
+            <Icon name="action.login" />
+          </LoginForm.Logo>
+          <LoginForm.Title>Войти в аккаунт</LoginForm.Title>
+          <LoginForm.Description>Любая пара email и пароля вернёт ошибку</LoginForm.Description>
+        </LoginForm.Header>
+        <LoginForm.Body>
+          <LoginForm.Form
+            onSubmit={(e) => {
+              e.preventDefault();
+              setFailed(false);
+              setPending(true);
+              timer.current = setTimeout(() => {
+                setPending(false);
+                setFailed(true);
+              }, 1200);
+            }}
+          >
+            {failed ? (
+              <Banner.Root tone="danger" role="alert">
+                <Banner.Content>
+                  <Banner.Icon>
+                    <Icon name="status.danger" />
+                  </Banner.Icon>
+                  <Banner.Title>Неверный email или пароль</Banner.Title>
+                </Banner.Content>
+              </Banner.Root>
+            ) : null}
+            <Input.Root label="Email" required>
+              <Input.Wrapper>
+                <Input.Field
+                  type="email"
+                  autoComplete="email"
+                  placeholder="name@company.ru"
+                  disabled={pending}
+                />
+              </Input.Wrapper>
+            </Input.Root>
+            <Input.Root label="Пароль" required invalid={failed}>
+              <Input.Wrapper>
+                <Input.Field
+                  type="password"
+                  autoComplete="current-password"
+                  placeholder="********"
+                  disabled={pending}
+                  onValueChange={() => setFailed(false)}
+                />
+              </Input.Wrapper>
+            </Input.Root>
+            <Button.Root type="submit" fullWidth loading={pending}>
+              Войти
+            </Button.Root>
+          </LoginForm.Form>
+        </LoginForm.Body>
+      </LoginForm.Root>
+    </div>
+  );
+}

package/src/components/login-form/examples/structure.tsx

@@ -0,0 +1,28 @@
+/** The minimal form: no logo, description or footer, and no shadow for a host that already is a surface — `flat`. */
+import { Button, Input, LoginForm } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+export default function LoginFormStructureExample() {
+  return (
+    <div className={styles.stage}>
+      <LoginForm.Root flat>
+        <LoginForm.Header>
+          <LoginForm.Title>Войти в аккаунт</LoginForm.Title>
+        </LoginForm.Header>
+        <LoginForm.Body>
+          <LoginForm.Form onSubmit={(e) => e.preventDefault()}>
+            <Input.Root label="Email">
+              <Input.Wrapper>
+                <Input.Field type="email" placeholder="name@company.ru" />
+              </Input.Wrapper>
+            </Input.Root>
+            <Button.Root type="submit" fullWidth>
+              Получить ссылку для входа
+            </Button.Root>
+          </LoginForm.Form>
+        </LoginForm.Body>
+      </LoginForm.Root>
+    </div>
+  );
+}

package/src/components/login-form/examples/verification-code.tsx

@@ -0,0 +1,57 @@
+/** The second step with a one-time code: a rejected code shows its error under the cells, resend is a quiet action — `DigitInput`, `LoginForm.Actions`. */
+import { Button, DigitInput, Icon, LinkButton, LoginForm } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+export default function LoginFormVerificationCodeExample() {
+  const [code, setCode] = React.useState("");
+  const [invalid, setInvalid] = React.useState(false);
+
+  return (
+    <div className={styles.stage}>
+      <LoginForm.Root>
+        <LoginForm.Header>
+          <LoginForm.Logo>
+            <Icon name="status.emailSent" />
+          </LoginForm.Logo>
+          <LoginForm.Title>Введите код</LoginForm.Title>
+          <LoginForm.Description>Мы отправили 6 цифр на name@company.ru</LoginForm.Description>
+        </LoginForm.Header>
+        <LoginForm.Body>
+          <LoginForm.Form
+            onSubmit={(e) => {
+              e.preventDefault();
+              setInvalid(code !== "123456");
+            }}
+          >
+            <DigitInput
+              length={6}
+              size="l"
+              fullWidth
+              groupSize={3}
+              value={code}
+              error={invalid ? "Неверный код. Проверьте письмо и попробуйте ещё раз" : undefined}
+              onValueChange={(value) => {
+                setCode(value);
+                setInvalid(false);
+              }}
+              labels={{ group: "Код из письма" }}
+            />
+            <LoginForm.Actions>
+              <Button.Root type="submit" fullWidth disabled={code.length < 6}>
+                Подтвердить
+              </Button.Root>
+              <Button.Root variant="ghost" tone="neutral" fullWidth>
+                Отправить код ещё раз
+              </Button.Root>
+            </LoginForm.Actions>
+          </LoginForm.Form>
+          <LoginForm.Footer>
+            Не тот адрес? <LinkButton href="#">Изменить email</LinkButton>
+          </LoginForm.Footer>
+        </LoginForm.Body>
+      </LoginForm.Root>
+    </div>
+  );
+}

package/src/components/modal/COMPONENT.md

@@ -1,6 +1,7 @@
 # Modal
 
 **Category:** overlays
+**Kind:** overlay
 
 > A dialog over the page for confirmations, short forms and important text.
 
@@ -37,88 +38,72 @@ Modal.Root                    state and dismiss policy (no DOM)
 
 ## API
 
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 ### Modal.Root
-No DOM, no ref.
+No DOM, no ref. State and dismiss policy.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `open` | `boolean` | — | Controlled visibility. |
+| `open` | `boolean` | — | Controlled visibility; together with `onOpenChange`. |
 | `defaultOpen` | `boolean` | `false` | Initial visibility, uncontrolled. |
-| `onOpenChange` | `(open: boolean) => void` | — | Called on trigger, close button, Close, Escape and scrim click. |
+| `onOpenChange` | `(open: boolean) => void` | — | Called on every open and close: trigger, close button, `Close`, Escape, scrim click, code. |
 | `closeOnEscape` | `boolean` | `true` | Escape closes the dialog. |
 | `closeOnOutsideClick` | `boolean` | `true` | A click on the scrim closes the dialog; turn off for destructive confirms. |
-| `confirmOnEnter` | `boolean` | `true` | Enter inside the dialog clicks the element wrapped in `Modal.Confirm`. |
-| `onEnterConfirm` | `(event: KeyboardEvent) => void` | — | Replaces the default Enter confirm. |
-| `labels` | `Partial<ModalLabels>` | `{ close: "Закрыть" }` | Built-in strings. |
+| `labels` | `Partial<ModalLabels>` | — | Built-in strings, see Labels. |
 | `children` | `ReactNode` | — | Trigger and Content. |
-
-### Modal.Trigger
-No DOM: clones the single child and chains `onClick`; opens unless the child's handler calls `preventDefault()`.
-
-| Prop | Type | Default | Description |
-|---|---|---|---|
-| `children` | `ReactElement` | — (required) | One element, usually a Button. |
+| `confirmOnEnter` | `boolean` | `true` | Enter inside the dialog clicks the element wrapped in `Modal.Confirm`; Enter on a button or link activates that element instead. |
+| `onEnterConfirm` | `(event: KeyboardEvent) => void` | — | Replaces the default Enter confirm. |
 
 ### Modal.Content
-No ref. Renders in a portal while open and during its exit animation. Controls inside get size `m`.
+`ref` → `HTMLDivElement` (the dialog panel). Portal + scrim + `role="dialog"`; renders while open and during its exit animation. Controls inside get size `m`.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `size` | `"s" \| "m" \| "l" \| "xl"` | `"m"` | Width: 440 · 560 · 720 · 960. |
+| `size` | `"s" \| "m" \| "l" \| "xl"` | `"m"` | Width: 440 · 560 · 720 · 960. Below 640 px of viewport — a full-width bottom sheet. |
 | `container` | `HTMLElement \| null` | `document.body` | Portal target. |
-| `overlayClassName` | `string` | — | Class on the scrim. |
 | `aria-label` | `string` | — | Dialog name when there is no Title. |
 | `aria-labelledby` | `string` | — | Overrides the Title id. |
 | `aria-describedby` | `string` | — | Overrides the Description id. |
-| `className` | `string` | — | Class on the `role="dialog"` element. |
-
-+ native `<div>` props (on the dialog element).
+| `overlayClassName` | `string` | — | Class on the scrim. |
+| `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `className` and the other attributes of the `role="dialog"` element. |
 
 ### Modal.Header
-No ref. Renders `<header>`.
+`ref` → `HTMLElement`. Renders `<header>`: [Icon] [Title + Description] [close button]. + native `HTMLAttributes<HTMLElement>`.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `showClose` | `boolean` | `true` | Built-in square ghost `s` close button with `labels.close`. |
-| `children` | `ReactNode` | — | Icon, Title, Description in any order. |
-
-+ native `HTMLAttributes<HTMLElement>`.
+| `showClose` | `boolean` | `true` | Built-in square ghost `s` close button named by `labels.close`. |
+| `children` | `ReactNode` | — | Icon, Title, Description in any order; the icon goes to the leading slot. |
 
 ### Modal.Icon
-No ref. Renders an `aria-hidden` tile.
+`ref` → `HTMLSpanElement`. An `aria-hidden` 40 px tile with a tone fill.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `tone` | `"neutral" \| "accent" \| "success" \| "warning" \| "danger" \| "info"` | `"neutral"` | Soft fill and icon color. |
 | `children` | `ReactNode` | — (required) | Icon glyph (sized to the m icon). |
-| `className` | `string` | — | Extra class. |
+| `…rest` | `Omit<HTMLAttributes<HTMLSpanElement>, "children">` | — | `className` and the other attributes of the tile. |
 
 ### Modal.Title · Modal.Description
-No ref. `<h2>` / `<p>`; their ids are generated and wired to `aria-labelledby` / `aria-describedby`. + native props except `id`.
+`ref` → `HTMLHeadingElement` / `HTMLParagraphElement`. `<h2>` (title-m) / `<p>` (body-s, muted); their ids name and describe the dialog. + native props except `id`.
 
 ### Modal.Body
-No ref. A ScrollContainer. + native `<div>` props.
+`ref` → `HTMLDivElement`. The only scrolling zone (a ScrollContainer), 16 gap between blocks. + native `<div>` props.
 
 ### Modal.Footer
-No ref. Renders `<footer>`.
+`ref` → `HTMLElement`. Renders `<footer>` with the actions, primary last. + native `HTMLAttributes<HTMLElement>`.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `layout` | `"fill" \| "end"` | `"fill"` for `s`/`m`, `"end"` for `l`/`xl` | `fill`: equal-width buttons in one row; `end`: auto width, right-aligned. |
-
-+ native `HTMLAttributes<HTMLElement>`.
+| `layout` | `"fill" \| "end"` | `"fill" (s/m), "end" (l/xl)` | `fill`: equal-width buttons in one row; `end`: auto width, at the end. Narrower than 360 px — stacked. |
 
-### Modal.Close · Modal.Confirm
-No DOM: clone the single child.
+### Modal.Trigger · Modal.Close · Modal.Confirm
+No DOM: clone the single child and chain its `onClick` (unless the child's handler calls `preventDefault()`).
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `children` | `ReactElement` | — (required) | Close: closes on click unless `preventDefault()`. Confirm: becomes the Enter target (ref is merged). |
-
-### ModalLabels
-| Key | Default | Used for |
-|---|---|---|
-| `close` | `"Закрыть"` | `aria-label` of the header close button |
+| `children` | `ReactElement` | — (required) | One element, usually a Button. |
 
 ## Variants
 The dialog has one look: `bg-raised`, `--prime-modal-radius` (16), `shadow-modal`, on a `bg-scrim`. Header, body and footer are separated by faint inset hairlines.
@@ -151,7 +136,7 @@ When the dialog itself is narrower than 360px, actions stack full width in DOM o
 | `danger` | `danger-soft` tile, danger icon | Delete confirmations | |
 | `info` | `info-soft` tile, info icon | Informational notices | |
 
-### Structure flags
+### Flags
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
 | `showClose` | Close button at the end of the header | Default | `true` |
@@ -164,10 +149,16 @@ When the dialog itself is narrower than 360px, actions stack full width in DOM o
 **Hierarchy** — one primary action, last in the footer and wrapped in `Modal.Confirm`; the secondary is `outline` neutral.
 
 ## States
-- Closed / open: `open` / `defaultOpen` / `onOpenChange`. `data-state="open" | "closed"` on the scrim and the dialog (closed while the exit animation plays), `data-size` on the dialog.
-- Header: `data-has-description="true"` when a Description is present. Footer: `data-layout`. Icon: `data-tone`.
-- While open: focus is trapped inside, page scroll is locked, siblings of the portal are `inert`.
-- Loading/disabled actions: use the Button props (`loading`, `disabled`) inside the footer.
+| State | Driven by | DOM |
+|---|---|---|
+| open / closed | `open` / `defaultOpen` / `onOpenChange` | `data-state="open" \| "closed"` on the scrim and the dialog (closed while the exit animation plays) |
+| size | `size` on Content | `data-size` on the dialog |
+| header with description | a `Modal.Description` inside | `data-has-description="true"` on the header |
+| footer layout | `layout` or the size default | `data-layout` on the footer |
+| icon tone | `tone` on Icon | `data-tone` on the tile |
+| while open | — | focus trapped inside, page scroll locked, siblings of the portal `inert` (the toast region stays usable) |
+
+Loading or disabled actions use the Button props (`loading`, `disabled`) inside the footer.
 
 ## Layout & spacing
 - Dialog padding `--prime-modal-padding` (24) on every zone; header 24 top / 20 bottom, body 20 with a 16 gap between blocks, footer 20 top / 24 bottom.
@@ -176,50 +167,38 @@ When the dialog itself is narrower than 360px, actions stack full width in DOM o
 - Narrow viewport (< 640px): bottom sheet, full width, top corners rounded.
 
 ## Accessibility
+
+### Keyboard
+| Key | Action |
+|---|---|
+| `Escape` | Closes the dialog (`closeOnEscape`); focus returns to the opener. |
+| `Enter` | Clicks `Modal.Confirm` from a text field or the dialog itself. Enter on a button, link or `role="button"` (Cancel included) activates that element instead; a `<textarea>`, a `<select>`, an `<input>` of type checkbox / radio / file / button / submit / reset, a contenteditable element and the header keep their own Enter. |
+| `Tab` · `Shift+Tab` | Cycles focus inside the dialog. |
+
+### ARIA
 - `role="dialog"`, `aria-modal="true"`, named by Title (or `aria-label`), described by Description.
 - Focus moves into the dialog on open (an `autoFocus` field wins) and returns to the opener on close — also after a scrim click (foundation §8).
-- Escape closes (`closeOnEscape`); Enter clicks `Modal.Confirm` except when focus is in a `<textarea>`, a `<select>`, an `<input>` of type checkbox / radio / file / button / submit / reset, a contenteditable element, inside the header, or on the Confirm element itself. A plain `<button>` in the body does not block it.
+- The page behind is `inert` and its scroll is locked.
 - Only the topmost layer reacts: a Select open inside the dialog closes first.
-- `labels.close` — `"Закрыть"`: `aria-label` of the header close button.
 
-## Examples
-| File | Scenario | When to use this pattern |
+### Labels
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+| Key | Default | Used for |
 |---|---|---|
-| [link.tsx](examples/link.tsx) | Full anatomy: icon header, body with a copyable link, two equal actions | Default dialog shape |
-| [sizes.tsx](examples/sizes.tsx) | `size` s · m · l · xl and the footer layout per size | Choosing the width |
-| [states.tsx](examples/states.tsx) | Destructive confirm without body (`tone="danger"`, no scrim close, loading) and a header-only notice | Delete confirmations |
-| [composition.tsx](examples/composition.tsx) | Settings form with an inline error, Select and Switch | Short edit forms |
-| [controlled.tsx](examples/controlled.tsx) | `open` from code without Modal.Trigger | Route / store / timer driven dialogs |
-| [features.tsx](examples/features.tsx) | Long scrolling body; portal into a custom `container` | Long text, custom mount node |
+| `close` | `"Закрыть"` | `aria-label` of the header close button. |
 
-```tsx
-import { Button, Modal } from "prime-ui-kit";
-
-export function Example() {
-  return (
-    <Modal.Root>
-      <Modal.Trigger>
-        <Button.Root>Открыть</Button.Root>
-      </Modal.Trigger>
-      <Modal.Content size="s">
-        <Modal.Header>
-          <Modal.Title>Сохранить изменения?</Modal.Title>
-        </Modal.Header>
-        <Modal.Footer>
-          <Modal.Close>
-            <Button.Root variant="outline" tone="neutral">
-              Отмена
-            </Button.Root>
-          </Modal.Close>
-          <Modal.Confirm>
-            <Button.Root>Сохранить</Button.Root>
-          </Modal.Confirm>
-        </Modal.Footer>
-      </Modal.Content>
-    </Modal.Root>
-  );
-}
-```
+## Examples
+| Example | Shows |
+|---|---|
+| [overview.tsx](examples/overview.tsx) | A trigger opens a dialog with a title, a field and two actions; Enter presses the confirm — `Modal.Trigger`, `Modal.Confirm`. |
+| [structure.tsx](examples/structure.tsx) | Optional parts: an icon tile with a header-only notice, and a header with a footer but no body — `Modal.Icon`, `Modal.Body`, `Modal.Footer`. |
+| [sizes.tsx](examples/sizes.tsx) | Every width; s and m fill the footer with equal buttons, l and xl align them to the end — `size`. |
+| [long-content.tsx](examples/long-content.tsx) | A long body scrolls on its own while the header and the footer stay in place — `Modal.Body`. |
+| [custom-container.tsx](examples/custom-container.tsx) | The dialog portals into a given node instead of the document body — `container`. |
+| [dismiss.tsx](examples/dismiss.tsx) | A destructive confirm closes only from its buttons, and not at all while the request runs — `closeOnOutsideClick`, `closeOnEscape`. |
+| [controlled-open.tsx](examples/controlled-open.tsx) | The parent owns the open state and opens the dialog from code, without a trigger — `open`, `onOpenChange`. |
+| [in-form.tsx](examples/in-form.tsx) | A settings form in a dialog: the footer button submits the form and an empty name keeps it open — `Modal.Body`, `Modal.Footer`, `error`. |
 
 ## Mistakes
 - Destructive confirm that closes on a stray scrim click → `closeOnOutsideClick={false}`.
@@ -230,4 +209,5 @@ export function Example() {
 - Long multi-section forms in a modal → use Drawer.
 
 ## Related
-[Drawer](../drawer/COMPONENT.md) · [Popover](../popover/COMPONENT.md) · [CommandMenu](../command-menu/COMPONENT.md) · [Button](../button/COMPONENT.md)
+- **Built from:** [Button](../button/COMPONENT.md) (header close button), [ScrollContainer](../scroll-container/COMPONENT.md) (`Modal.Body`)
+- **See also:** [Drawer](../drawer/COMPONENT.md), [Popover](../popover/COMPONENT.md), [CommandMenu](../command-menu/COMPONENT.md)

package/src/components/modal/examples/{controlled.tsx → controlled-open.tsx}

@@ -1,21 +1,15 @@
-/** Controlled dialog without Modal.Trigger: the parent owns `open` and opens it from code. Use when a route, store or timer decides when the dialog shows. */
-import { Button, Modal, Typography } from "prime-ui-kit";
+/** The parent owns the open state and opens the dialog from code, without a trigger — `open`, `onOpenChange`. */
+import { Button, Modal } from "prime-ui-kit";
 import * as React from "react";
 
-import styles from "./examples.module.css";
-
-export default function ModalControlledExample() {
+export default function ModalControlledOpenExample() {
   const [open, setOpen] = React.useState(false);
 
   return (
-    <div className={styles.row}>
+    <>
       <Button.Root variant="soft" tone="neutral" onClick={() => setOpen(true)}>
-        Открыть из кода
+        Сымитировать конец сессии
       </Button.Root>
-      <Typography.Root as="span" variant="body-s" tone="secondary">
-        open = {String(open)}
-      </Typography.Root>
-
       <Modal.Root open={open} onOpenChange={setOpen}>
         <Modal.Content size="s">
           <Modal.Header>
@@ -34,6 +28,6 @@ export default function ModalControlledExample() {
           </Modal.Footer>
         </Modal.Content>
       </Modal.Root>
-    </div>
+    </>
   );
 }

package/src/components/modal/examples/custom-container.tsx

@@ -0,0 +1,29 @@
+/** The dialog portals into a given node instead of the document body — `container`. */
+import { Button, Modal } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+export default function ModalCustomContainerExample() {
+  const [host, setHost] = React.useState<HTMLDivElement | null>(null);
+
+  return (
+    <div ref={setHost} className={styles.portalHost}>
+      {host ? (
+        <Modal.Root>
+          <Modal.Trigger>
+            <Button.Root variant="soft" tone="neutral">
+              Открыть внутри блока
+            </Button.Root>
+          </Modal.Trigger>
+          <Modal.Content container={host} size="s">
+            <Modal.Header>
+              <Modal.Title>Свой контейнер</Modal.Title>
+              <Modal.Description>Диалог смонтирован внутрь этого блока.</Modal.Description>
+            </Modal.Header>
+          </Modal.Content>
+        </Modal.Root>
+      ) : null}
+    </div>
+  );
+}

package/src/components/modal/examples/dismiss.tsx

@@ -0,0 +1,54 @@
+/** A destructive confirm closes only from its buttons, and not at all while the request runs — `closeOnOutsideClick`, `closeOnEscape`. */
+import { Button, Icon, Modal } from "prime-ui-kit";
+import * as React from "react";
+
+export default function ModalDismissExample() {
+  const [open, setOpen] = React.useState(false);
+  const [deleting, setDeleting] = React.useState(false);
+
+  const remove = () => {
+    setDeleting(true);
+    window.setTimeout(() => {
+      setDeleting(false);
+      setOpen(false);
+    }, 1200);
+  };
+
+  return (
+    <Modal.Root
+      open={open}
+      onOpenChange={setOpen}
+      closeOnOutsideClick={false}
+      closeOnEscape={!deleting}
+    >
+      <Modal.Trigger>
+        <Button.Root variant="outline" tone="danger">
+          Удалить проект
+        </Button.Root>
+      </Modal.Trigger>
+      <Modal.Content size="s">
+        <Modal.Header showClose={!deleting}>
+          <Modal.Icon tone="danger">
+            <Icon name="action.delete" />
+          </Modal.Icon>
+          <Modal.Title>Удалить «Сайт компании»?</Modal.Title>
+          <Modal.Description>
+            Задачи, файлы и история будут удалены без возможности восстановления.
+          </Modal.Description>
+        </Modal.Header>
+        <Modal.Footer>
+          <Modal.Close>
+            <Button.Root variant="outline" tone="neutral" disabled={deleting}>
+              Отмена
+            </Button.Root>
+          </Modal.Close>
+          <Modal.Confirm>
+            <Button.Root tone="danger" loading={deleting} onClick={remove}>
+              Удалить
+            </Button.Root>
+          </Modal.Confirm>
+        </Modal.Footer>
+      </Modal.Content>
+    </Modal.Root>
+  );
+}

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

@@ -1,37 +1,21 @@
-/* Layout for the Modal examples: layout only, text goes through Typography. */
+/* Layout of the Modal scenarios: semantic tokens only. */
 
-.row {
-  display: flex;
-  flex-wrap: wrap;
-  align-items: center;
-  justify-content: center;
-  gap: var(--prime-space-3);
-}
-
-/* Field groups breathe a little more than plain body blocks. */
+/* in-form.tsx: field → field 20 (foundation §1). */
 .form {
   display: flex;
   flex-direction: column;
   gap: var(--prime-space-5);
 }
 
-.field {
-  display: flex;
-  flex-direction: column;
-  gap: var(--prime-control-m-label-gap);
-}
-
+/* custom-container.tsx: a bounded block (§4) takes the host's card fill so it reads in both themes. */
 .portalHost {
   position: relative;
   box-sizing: border-box;
   display: flex;
-  flex-direction: column;
-  align-items: center;
-  gap: var(--prime-space-3);
+  justify-content: center;
   width: 100%;
   padding: var(--prime-space-4);
   border-radius: var(--prime-card-radius);
-  /* A bounded block (§4): the host's card fill, so it reads on the stage in both themes. */
   background: var(--prime-color-card-bg);
   box-shadow: var(--prime-card-shadow);
 }

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

@@ -0,0 +1,78 @@
+/** A settings form in a dialog: the footer button submits the form and an empty name keeps it open — `Modal.Body`, `Modal.Footer`, `error`. */
+import { Button, Icon, Input, Modal, Select, Switch } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+export default function ModalInFormExample() {
+  const formId = React.useId();
+  const [open, setOpen] = React.useState(false);
+  const [error, setError] = React.useState<string>();
+
+  const submit = (event: React.FormEvent<HTMLFormElement>) => {
+    event.preventDefault();
+    const name = String(new FormData(event.currentTarget).get("name") ?? "").trim();
+    if (!name) {
+      setError("Введите название проекта");
+      return;
+    }
+    setOpen(false);
+  };
+
+  return (
+    <Modal.Root
+      open={open}
+      onOpenChange={(next) => {
+        setOpen(next);
+        if (!next) setError(undefined);
+      }}
+    >
+      <Modal.Trigger>
+        <Button.Root variant="soft" tone="neutral">
+          Настройки проекта
+        </Button.Root>
+      </Modal.Trigger>
+      <Modal.Content>
+        <Modal.Header>
+          <Modal.Icon>
+            <Icon name="nav.layoutGrid" />
+          </Modal.Icon>
+          <Modal.Title>Настройки проекта</Modal.Title>
+          <Modal.Description>Изменения увидят все участники команды.</Modal.Description>
+        </Modal.Header>
+        <Modal.Body>
+          <form id={formId} className={styles.form} noValidate onSubmit={submit}>
+            <Input.Root label="Название" required error={error} reserveSupportRow>
+              <Input.Wrapper>
+                <Input.Field name="name" defaultValue="Сайт компании" autoFocus />
+              </Input.Wrapper>
+            </Input.Root>
+            <Select.Root label="Ответственный" defaultValue="anna">
+              <Select.Trigger>
+                <Select.Value />
+              </Select.Trigger>
+              <Select.Content>
+                <Select.Item value="anna">Анна Смирнова</Select.Item>
+                <Select.Item value="igor">Игорь Петров</Select.Item>
+                <Select.Item value="olga">Ольга Ким</Select.Item>
+              </Select.Content>
+            </Select.Root>
+            <Switch.Root name="notify" defaultChecked>
+              <Switch.Label>Уведомлять участников об изменениях</Switch.Label>
+            </Switch.Root>
+          </form>
+        </Modal.Body>
+        <Modal.Footer>
+          <Modal.Close>
+            <Button.Root variant="outline" tone="neutral">
+              Отмена
+            </Button.Root>
+          </Modal.Close>
+          <Button.Root type="submit" form={formId}>
+            Сохранить
+          </Button.Root>
+        </Modal.Footer>
+      </Modal.Content>
+    </Modal.Root>
+  );
+}