prime-ui-kit 0.9.0 → 0.9.2

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>
+  );
+}

package/src/components/modal/examples/long-content.tsx

@@ -0,0 +1,52 @@
+/** A long body scrolls on its own while the header and the footer stay in place — `Modal.Body`. */
+import { Button, Modal, Typography } from "prime-ui-kit";
+
+const TERMS = [
+  "Исполнитель обрабатывает персональные данные только для оказания услуги.",
+  "Данные не передаются третьим лицам без письменного согласия заказчика.",
+  "Доступ к данным получают только сотрудники, которым он нужен для работы.",
+  "Резервные копии хранятся в зашифрованном виде в дата-центрах на территории РФ.",
+  "Заказчик может запросить выгрузку своих данных в течение 10 рабочих дней.",
+  "По запросу заказчика данные удаляются в течение 30 дней после расторжения договора.",
+  "О каждом инциденте безопасности исполнитель сообщает заказчику в течение 24 часов.",
+  "Журналы доступа хранятся не меньше одного года и выдаются по запросу.",
+  "Исполнитель ежегодно проходит внешний аудит защиты информации.",
+  "Субподрядчики допускаются только с согласия заказчика и на тех же условиях.",
+  "Изменения условий публикуются за 30 дней до вступления в силу.",
+  "Споры решаются в арбитражном суде по месту нахождения исполнителя.",
+];
+
+export default function ModalLongContentExample() {
+  return (
+    <Modal.Root>
+      <Modal.Trigger>
+        <Button.Root variant="soft" tone="neutral">
+          Условия обработки данных
+        </Button.Root>
+      </Modal.Trigger>
+      <Modal.Content size="l">
+        <Modal.Header>
+          <Modal.Title>Условия обработки данных</Modal.Title>
+          <Modal.Description>Редакция от 1 октября 2026 года</Modal.Description>
+        </Modal.Header>
+        <Modal.Body>
+          {TERMS.map((line) => (
+            <Typography key={line} variant="body-m" tone="secondary">
+              {line}
+            </Typography>
+          ))}
+        </Modal.Body>
+        <Modal.Footer>
+          <Modal.Close>
+            <Button.Root variant="outline" tone="neutral">
+              Не сейчас
+            </Button.Root>
+          </Modal.Close>
+          <Modal.Close>
+            <Button.Root>Принимаю</Button.Root>
+          </Modal.Close>
+        </Modal.Footer>
+      </Modal.Content>
+    </Modal.Root>
+  );
+}

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

@@ -0,0 +1,35 @@
+/** A trigger opens a dialog with a title, a field and two actions; Enter presses the confirm — `Modal.Trigger`, `Modal.Confirm`. */
+import { Button, Input, Modal } from "prime-ui-kit";
+
+export default function ModalOverviewExample() {
+  return (
+    <Modal.Root>
+      <Modal.Trigger>
+        <Button.Root>Пригласить участника</Button.Root>
+      </Modal.Trigger>
+      <Modal.Content>
+        <Modal.Header>
+          <Modal.Title>Пригласить в проект</Modal.Title>
+          <Modal.Description>Отправим приглашение на рабочую почту.</Modal.Description>
+        </Modal.Header>
+        <Modal.Body>
+          <Input.Root label="Рабочая почта">
+            <Input.Wrapper>
+              <Input.Field type="email" placeholder="name@company.ru" autoFocus />
+            </Input.Wrapper>
+          </Input.Root>
+        </Modal.Body>
+        <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>
+  );
+}

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

@@ -1,8 +1,6 @@
-/** Modal.Content widths s · m · l · xl; s/m fill the footer with equal buttons, l/xl align them to the end. Pick the narrowest size the content fits. */
+/** Every width; s and m fill the footer with equal buttons, l and xl align them to the end — `size`. */
 import { Button, Modal, Typography } from "prime-ui-kit";
 
-import styles from "./examples.module.css";
-
 const SIZES = [
   { size: "s", width: "440 px — подтверждения" },
   { size: "m", width: "560 px — короткие формы" },
@@ -12,12 +10,12 @@ const SIZES = [
 
 export default function ModalSizesExample() {
   return (
-    <div className={styles.row}>
+    <>
       {SIZES.map(({ size, width }) => (
         <Modal.Root key={size}>
           <Modal.Trigger>
             <Button.Root variant="soft" tone="neutral">
-              Размер {size}
+              {size}
             </Button.Root>
           </Modal.Trigger>
           <Modal.Content size={size}>
@@ -26,10 +24,10 @@ export default function ModalSizesExample() {
               <Modal.Description>{width}</Modal.Description>
             </Modal.Header>
             <Modal.Body>
-              <Typography.Root variant="body-m" tone="secondary">
-                Выбирайте самый узкий размер, в который контент помещается без переносов строк
+              <Typography variant="body-m" tone="secondary">
+                Выбирайте самый узкий размер, в который содержимое помещается без переносов строк
                 формы.
-              </Typography.Root>
+              </Typography>
             </Modal.Body>
             <Modal.Footer>
               <Modal.Close>
@@ -44,6 +42,6 @@ export default function ModalSizesExample() {
           </Modal.Content>
         </Modal.Root>
       ))}
-    </div>
+    </>
   );
 }

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

@@ -0,0 +1,53 @@
+/** 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`. */
+import { Button, Icon, Modal } from "prime-ui-kit";
+
+export default function ModalStructureExample() {
+  return (
+    <>
+      <Modal.Root>
+        <Modal.Trigger>
+          <Button.Root variant="soft" tone="neutral">
+            Выгрузить отчёт
+          </Button.Root>
+        </Modal.Trigger>
+        <Modal.Content size="s">
+          <Modal.Header>
+            <Modal.Icon tone="info">
+              <Icon name="status.info" />
+            </Modal.Icon>
+            <Modal.Title>Отчёт готовится</Modal.Title>
+            <Modal.Description>
+              Пришлём письмо, когда файл можно будет скачать. Обычно это пара минут.
+            </Modal.Description>
+          </Modal.Header>
+        </Modal.Content>
+      </Modal.Root>
+
+      <Modal.Root>
+        <Modal.Trigger>
+          <Button.Root variant="soft" tone="neutral">
+            Опубликовать тариф
+          </Button.Root>
+        </Modal.Trigger>
+        <Modal.Content size="s">
+          <Modal.Header>
+            <Modal.Title>Опубликовать «Бизнес 2026»?</Modal.Title>
+            <Modal.Description>
+              Новые клиенты увидят тариф сразу после публикации.
+            </Modal.Description>
+          </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>
+    </>
+  );
+}

package/src/components/native-select/COMPONENT.md

@@ -0,0 +1,132 @@
+# NativeSelect
+
+**Category:** selection
+**Kind:** field
+
+> The system `<select>` in the kit's field look: the operating system's picker opens on phones.
+
+## When to use
+- Mobile-first forms where the OS picker is easier than a floating list.
+- A short list of plain text options that must post with a form (`name`, FormData).
+- Settings screens where the native control and its keyboard are expected.
+
+## When not to use
+- Options with icons, pictures, descriptions or a search field → use [Select](../select/COMPONENT.md).
+- Several values → use [Select](../select/COMPONENT.md) with `multiple` or [TagSelect](../tag-select/COMPONENT.md).
+- Two to five options that should all be visible → use [Radio](../radio/COMPONENT.md) or [SegmentedControl](../segmented-control/COMPONENT.md).
+
+## Import
+```tsx
+import { NativeSelect } from "prime-ui-kit";
+```
+
+## Anatomy
+```
+NativeSelect          field frame: label row · control · support row
+├── Label             from `label` (required / optional markers)
+├── <select>          the system control, field fill, tier height
+│   └── <option> / <optgroup>   the consumer's children (+ the placeholder option)
+├── chevron           kit icon over the end (aria-hidden)
+└── Hint              from `hint` / `error`
+```
+
+## API
+
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+### NativeSelect
+`ref` → `HTMLSelectElement`. The system `<select>` in the field look with the label row and the support row; the kit chevron over its end. + native `<select>` props except `size` and `multiple`.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `label` | `ReactNode` | — | Field label above; a `<label htmlFor>` of the select. |
+| `hint` | `ReactNode` | — | Support text under the field; linked by `aria-describedby`. |
+| `error` | `ReactNode` | — | Error message; replaces the hint and implies `invalid`. |
+| `required` | `boolean` | `false` | Red `*` after the label and native `required`. |
+| `optional` | `boolean` | — | Muted `labels.optional` after the label. |
+| `invalid` | `boolean` | `false` | Danger inset ring and `aria-invalid`. |
+| `disabled` | `boolean` | `false` | Disabled field fill and text. |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `"m"` | Field tier: height, padding, text; the label and the hint follow it. |
+| `placeholder` | `string` | — | Empty first option shown in the placeholder color while nothing is picked. |
+| `value` | `string` | — | Controlled value (native); with `onValueChange` or `onChange`. |
+| `defaultValue` | `string` | — | Initial value, uncontrolled. |
+| `onValueChange` | `(value: string) => void` | — | Called with the picked value; native `onChange` still fires. |
+| `focusRing` | `boolean` | `true` | `false` hides the visual focus ring (`data-focus-ring="false"`), never focus or the error ring. |
+| `labels` | `Partial<NativeSelectLabels>` | — | Built-in strings, see Labels. |
+| `children` | `ReactNode` | — (required) | Native `<option>` and `<optgroup>` elements. |
+| `…rest` | `Omit<SelectHTMLAttributes<HTMLSelectElement>, "size" \| "multiple">` | — | `id`, `name`, `onChange`, `aria-*`, `className` (on the field wrapper) and the other select attributes. |
+
+## Variants
+One look, the Select trigger's: field fill, inset control border, tier radius; the open list is drawn by the browser and the OS.
+
+### size
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `xs` | 28 high, text 12/16 | Dense toolbars | |
+| `s` | 32 high, text 13/20 | Compact forms | |
+| `m` | 36 high, text 14/20 | Most forms | yes |
+| `l` | 40 high, text 16/24 | Roomy forms | |
+| `xl` | 48 high, text 16/24 | Touch-first screens | |
+
+### Flags
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `required` | red `*` after the label | The form cannot be sent without it | `false` |
+| `optional` | muted «необязательно» | Most fields are required | |
+| `invalid` / `error` | danger inset ring (+ the message) | Validation failed | |
+| `disabled` | disabled fill and text | Not editable now | `false` |
+| `focusRing={false}` | no focus ring | Focus is obvious otherwise | `true` |
+
+## States
+| State | Driven by | DOM |
+|---|---|---|
+| placeholder shown | `placeholder` and no value | the empty first option is selected; placeholder text color |
+| invalid | `invalid` or `error` | `aria-invalid="true"`, `data-invalid="true"` |
+| disabled | `disabled` | native `disabled` |
+| size | `size` | `data-size` |
+| focus ring off | `focusRing={false}` | `data-focus-ring="false"` |
+
+## Layout & spacing
+- Full width of its column; label → field and field → hint gaps come from the tier (`label-gap`, `hint-gap`).
+- The chevron sits padX from the end; the text keeps padX + icon + padX free on that side.
+
+## Accessibility
+
+### Keyboard
+| Key | Action |
+|---|---|
+| `Enter` · `Space` · `ArrowDown` | Open the system list (browser and OS behaviour). |
+| `ArrowUp` · `ArrowDown` | On the closed field change the value (in most browsers). |
+
+### ARIA
+- It is a real `<select>`: the role, the keyboard and the list come from the browser and the OS.
+- `label` is a `<label htmlFor>`; the hint and the error are linked by `aria-describedby`, the error sets `aria-invalid`.
+- The chevron is decorative (`aria-hidden`).
+
+### Labels
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+| Key | Default | Used for |
+|---|---|---|
+| `optional` | `"необязательно"` | Muted marker after the label when `optional`. |
+
+## Examples
+| Example | Shows |
+|---|---|
+| [overview.tsx](examples/overview.tsx) | A labelled system select with a hint; the OS picker opens on phones — `label`, `hint`. |
+| [sizes.tsx](examples/sizes.tsx) | Every size tier; the label and the hint follow the field tier — `size`. |
+| [states.tsx](examples/states.tsx) | A default field next to a disabled and an invalid one — `disabled`, `invalid`. |
+| [validation.tsx](examples/validation.tsx) | Required and optional markers, a hint, and an error that replaces the hint in the same row — `required`, `optional`, `hint`, `error`. |
+| [option-groups.tsx](examples/option-groups.tsx) | Options under group headings with the native optgroup, and a placeholder while nothing is picked — `placeholder`. |
+| [controlled.tsx](examples/controlled.tsx) | The parent owns the value: the plan drives the price under the field — `value`, `onValueChange`. |
+| [in-form.tsx](examples/in-form.tsx) | A delivery form for phones: the native value goes into FormData, the required city is checked on submit — `name`, `required`, `error`. |
+
+## Mistakes
+- `Select.Item` parts as children → NativeSelect takes plain `<option>` / `<optgroup>`.
+- Rich options (icons, descriptions) → the system list cannot draw them; use Select.
+- A placeholder as the only label → keep `label`; the placeholder is just the empty option.
+- Several values with `multiple` → not supported; use Select `multiple` or TagSelect.
+
+## Related
+- **Built from:** [Label](../label/COMPONENT.md), [Hint](../hint/COMPONENT.md) (field frame)
+- **See also:** [Select](../select/COMPONENT.md), [Radio](../radio/COMPONENT.md), [SegmentedControl](../segmented-control/COMPONENT.md)

package/src/components/native-select/examples/controlled.tsx

@@ -0,0 +1,26 @@
+/** The parent owns the value: the plan drives the price under the field — `value`, `onValueChange`. */
+import { NativeSelect, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+const PRICES: Record<string, string> = {
+  free: "0 ₽ в месяц",
+  pro: "990 ₽ в месяц",
+  team: "4 900 ₽ в месяц",
+};
+
+export default function NativeSelectControlledExample() {
+  const [plan, setPlan] = React.useState("pro");
+
+  return (
+    <>
+      <NativeSelect label="Тариф" value={plan} onValueChange={setPlan}>
+        <option value="free">Бесплатный</option>
+        <option value="pro">Профессиональный</option>
+        <option value="team">Командный</option>
+      </NativeSelect>
+      <Typography as="p" variant="body-s" tone="secondary">
+        {PRICES[plan]}
+      </Typography>
+    </>
+  );
+}

package/src/components/native-select/examples/examples.module.css

@@ -0,0 +1,14 @@
+/* Layout of the NativeSelect scenarios: semantic tokens only. */
+
+/* in-form.tsx: a narrow mobile form, field → field 20. */
+.form {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-space-5);
+  width: min(100%, var(--prime-modal-width-s));
+}
+
+.actions {
+  display: flex;
+  justify-content: flex-end;
+}

package/src/components/native-select/examples/in-form.tsx

@@ -0,0 +1,43 @@
+/** A delivery form for phones: the native value goes into FormData, the required city is checked on submit — `name`, `required`, `error`. */
+import { Button, NativeSelect, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+export default function NativeSelectInFormExample() {
+  const [error, setError] = React.useState<string>();
+
+  const submit = (event: React.FormEvent<HTMLFormElement>) => {
+    event.preventDefault();
+    const city = String(new FormData(event.currentTarget).get("city") ?? "");
+    setError(city ? undefined : "Выберите город доставки");
+  };
+
+  return (
+    <form className={styles.form} noValidate onSubmit={submit}>
+      <Typography as="h3" variant="title-m">
+        Доставка
+      </Typography>
+      <NativeSelect
+        name="city"
+        label="Город"
+        required
+        error={error}
+        placeholder="Выберите город"
+        onValueChange={() => setError(undefined)}
+      >
+        <option value="msk">Москва</option>
+        <option value="spb">Санкт-Петербург</option>
+        <option value="kzn">Казань</option>
+      </NativeSelect>
+      <NativeSelect name="slot" label="Время" defaultValue="day">
+        <option value="morning">09:00–12:00</option>
+        <option value="day">12:00–18:00</option>
+        <option value="evening">18:00–21:00</option>
+      </NativeSelect>
+      <div className={styles.actions}>
+        <Button.Root type="submit">Продолжить</Button.Root>
+      </div>
+    </form>
+  );
+}

package/src/components/native-select/examples/option-groups.tsx

@@ -0,0 +1,17 @@
+/** Options under group headings with the native optgroup, and a placeholder while nothing is picked — `placeholder`. */
+import { NativeSelect } from "prime-ui-kit";
+
+export default function NativeSelectOptionGroupsExample() {
+  return (
+    <NativeSelect label="Часовой пояс" placeholder="Выберите пояс">
+      <optgroup label="Европа">
+        <option value="kal">Калининград, UTC+2</option>
+        <option value="msk">Москва, UTC+3</option>
+      </optgroup>
+      <optgroup label="Азия">
+        <option value="ekb">Екатеринбург, UTC+5</option>
+        <option value="nsk">Новосибирск, UTC+7</option>
+      </optgroup>
+    </NativeSelect>
+  );
+}

package/src/components/native-select/examples/overview.tsx

@@ -0,0 +1,16 @@
+/** A labelled system select with a hint; the OS picker opens on phones — `label`, `hint`. */
+import { NativeSelect } from "prime-ui-kit";
+
+export default function NativeSelectOverviewExample() {
+  return (
+    <NativeSelect
+      label="Тема оформления"
+      hint="На телефоне откроется системный список"
+      defaultValue="auto"
+    >
+      <option value="auto">Как в системе</option>
+      <option value="light">Светлая</option>
+      <option value="dark">Тёмная</option>
+    </NativeSelect>
+  );
+}

package/src/components/native-select/examples/sizes.tsx

@@ -0,0 +1,18 @@
+/** Every size tier; the label and the hint follow the field tier — `size`. */
+import { NativeSelect } from "prime-ui-kit";
+
+const SIZES = ["xs", "s", "m", "l", "xl"] as const;
+
+export default function NativeSelectSizesExample() {
+  return (
+    <>
+      {SIZES.map((size) => (
+        <NativeSelect key={size} size={size} label={size} defaultValue="week">
+          <option value="day">За день</option>
+          <option value="week">За неделю</option>
+          <option value="month">За месяц</option>
+        </NativeSelect>
+      ))}
+    </>
+  );
+}

package/src/components/native-select/examples/states.tsx

@@ -0,0 +1,21 @@
+/** A default field next to a disabled and an invalid one — `disabled`, `invalid`. */
+import { NativeSelect } from "prime-ui-kit";
+
+export default function NativeSelectStatesExample() {
+  return (
+    <>
+      <NativeSelect label="default" defaultValue="editor">
+        <option value="viewer">Наблюдатель</option>
+        <option value="editor">Редактор</option>
+      </NativeSelect>
+      <NativeSelect label="disabled" defaultValue="viewer" disabled>
+        <option value="viewer">Наблюдатель</option>
+        <option value="editor">Редактор</option>
+      </NativeSelect>
+      <NativeSelect label="invalid" placeholder="Выберите роль" invalid>
+        <option value="viewer">Наблюдатель</option>
+        <option value="editor">Редактор</option>
+      </NativeSelect>
+    </>
+  );
+}

package/src/components/native-select/examples/validation.tsx

@@ -0,0 +1,26 @@
+/** Required and optional markers, a hint, and an error that replaces the hint in the same row — `required`, `optional`, `hint`, `error`. */
+import { NativeSelect } from "prime-ui-kit";
+
+export default function NativeSelectValidationExample() {
+  return (
+    <>
+      <NativeSelect label="Страна" required hint="Определяет валюту счетов" defaultValue="ru">
+        <option value="ru">Россия</option>
+        <option value="kz">Казахстан</option>
+      </NativeSelect>
+      <NativeSelect
+        label="Ответственный"
+        required
+        error="Назначьте ответственного"
+        placeholder="Не выбран"
+      >
+        <option value="anna">Анна Петрова</option>
+        <option value="ivan">Иван Смирнов</option>
+      </NativeSelect>
+      <NativeSelect label="Отдел" optional placeholder="Не указан">
+        <option value="sales">Продажи</option>
+        <option value="support">Поддержка</option>
+      </NativeSelect>
+    </>
+  );
+}