prime-ui-kit 0.7.13 → 0.9.1

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

@@ -1,48 +1,34 @@
-.stack {
+/* Layout of the Select scenarios: semantic tokens only. */
+
+/* in-form.tsx: field → field 20, group → actions 32 (foundation §1). */
+.form {
   display: flex;
   flex-direction: column;
-  gap: var(--prime-sys-spacing-s);
-}
-
-.stackNarrow {
-  width: 100%;
-  max-width: calc(var(--prime-sys-unit-1rem) * 22);
-}
-
-.fullWidthShell {
-  box-sizing: border-box;
-  width: 100%;
-  max-width: calc(var(--prime-sys-unit-1rem) * 20);
+  gap: var(--prime-space-8);
+  width: min(100%, var(--prime-modal-width-m));
 }
 
-.field {
+.formHeader {
   display: flex;
   flex-direction: column;
-  gap: var(--prime-sys-spacing-xs);
-  width: 100%;
-  max-width: calc(var(--prime-sys-unit-1rem) * 22);
-  min-width: 0;
+  gap: var(--prime-space-1);
 }
 
-.fieldFullBleed {
-  display: flex;
-  flex-direction: column;
-  gap: var(--prime-sys-spacing-xs);
-  width: 100%;
-  min-width: 0;
-  max-width: none;
+.formFields {
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  align-items: start;
+  gap: var(--prime-space-5) var(--prime-space-4);
 }
 
-.form {
+.formActions {
   display: flex;
-  flex-direction: column;
-  gap: var(--prime-sys-spacing-m);
-  width: 100%;
-  max-width: calc(var(--prime-sys-unit-1rem) * 28);
-  min-width: 0;
+  justify-content: flex-end;
+  gap: var(--prime-space-2);
 }
 
-.caption {
-  margin: 0;
-  color: var(--prime-sys-color-content-secondary);
+@media (max-width: 639px) {
+  .formFields {
+    grid-template-columns: minmax(0, 1fr);
+  }
 }

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

@@ -0,0 +1,66 @@
+/** Regional settings form: the required country is checked on submit, the error replaces the hint — `required`, `error`, `hint`. */
+import { Button, Select, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+export default function SelectInFormExample() {
+  const [country, setCountry] = React.useState("");
+  const [error, setError] = React.useState<string>();
+
+  const submit = (event: React.FormEvent<HTMLFormElement>) => {
+    event.preventDefault();
+    setError(country ? undefined : "Выберите страну");
+  };
+
+  return (
+    <form className={styles.form} noValidate onSubmit={submit}>
+      <div className={styles.formHeader}>
+        <Typography as="h3" variant="title-m">
+          Региональные настройки
+        </Typography>
+        <Typography as="p" variant="body-s" tone="secondary">
+          Влияют на валюту, формат дат и время в отчётах.
+        </Typography>
+      </div>
+      <div className={styles.formFields}>
+        <Select.Root
+          label="Страна"
+          required
+          error={error}
+          placeholder="Выберите страну"
+          value={country}
+          onValueChange={(value) => {
+            setCountry(value);
+            setError(undefined);
+          }}
+        >
+          <Select.Trigger>
+            <Select.Value />
+          </Select.Trigger>
+          <Select.Content>
+            <Select.Item value="ru">Россия</Select.Item>
+            <Select.Item value="kz">Казахстан</Select.Item>
+            <Select.Item value="am">Армения</Select.Item>
+          </Select.Content>
+        </Select.Root>
+        <Select.Root label="Часовой пояс" hint="Время в отчётах и уведомлениях" defaultValue="msk">
+          <Select.Trigger>
+            <Select.Value />
+          </Select.Trigger>
+          <Select.Content>
+            <Select.Item value="kal">Калининград, UTC+2</Select.Item>
+            <Select.Item value="msk">Москва, UTC+3</Select.Item>
+            <Select.Item value="ekb">Екатеринбург, UTC+5</Select.Item>
+          </Select.Content>
+        </Select.Root>
+      </div>
+      <div className={styles.formActions}>
+        <Button.Root variant="ghost" tone="neutral" type="reset">
+          Отменить
+        </Button.Root>
+        <Button.Root type="submit">Сохранить</Button.Root>
+      </div>
+    </form>
+  );
+}

package/src/components/select/examples/multiple.tsx

@@ -0,0 +1,26 @@
+/** Several values: checkboxes in the list, the list stays open on a pick, labels joined in the trigger — `multiple`. */
+import { Select } from "prime-ui-kit";
+
+export default function SelectMultipleExample() {
+  return (
+    <Select.Root
+      label="Отделы"
+      multiple
+      defaultValue={["eng", "design"]}
+      placeholder="Выберите отделы"
+    >
+      <Select.Trigger>
+        <Select.Value />
+      </Select.Trigger>
+      <Select.Content>
+        <Select.Item value="eng">Разработка</Select.Item>
+        <Select.Item value="design">Дизайн</Select.Item>
+        <Select.Item value="sales">Продажи</Select.Item>
+        <Select.Item value="support">Поддержка</Select.Item>
+        <Select.Item value="hr" disabled>
+          HR — нет доступа
+        </Select.Item>
+      </Select.Content>
+    </Select.Root>
+  );
+}

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

@@ -0,0 +1,17 @@
+/** A labelled field with a placeholder; picking an option closes the list and shows its label — `label`, `placeholder`. */
+import { Select } from "prime-ui-kit";
+
+export default function SelectOverviewExample() {
+  return (
+    <Select.Root label="Роль в проекте" placeholder="Выберите роль">
+      <Select.Trigger>
+        <Select.Value />
+      </Select.Trigger>
+      <Select.Content>
+        <Select.Item value="viewer">Наблюдатель</Select.Item>
+        <Select.Item value="editor">Редактор</Select.Item>
+        <Select.Item value="admin">Администратор</Select.Item>
+      </Select.Content>
+    </Select.Root>
+  );
+}

package/src/components/select/examples/rich-options.tsx

@@ -0,0 +1,72 @@
+/** Options with a picture, a second line and a price; the trigger draws the picked option with the same parts — `renderValue`, `Select.ItemText`, `Select.ItemDescription`, `Select.ItemMeta`. */
+import { Icon, type PaletteColor, Select, Thumbnail } from "prime-ui-kit";
+
+type Tariff = { value: string; title: string; terms: string; price: string; color: PaletteColor };
+
+const TARIFFS: Tariff[] = [
+  {
+    value: "courier",
+    title: "Курьер",
+    terms: "Завтра, 10:00–18:00",
+    price: "450 ₽",
+    color: "blue",
+  },
+  {
+    value: "express",
+    title: "Экспресс",
+    terms: "Сегодня за 2 часа",
+    price: "890 ₽",
+    color: "orange",
+  },
+  { value: "pickup", title: "Пункт выдачи", terms: "Через 2 дня", price: "190 ₽", color: "green" },
+  {
+    value: "freight",
+    title: "Грузовой",
+    terms: "От 3 дней, до 1 т",
+    price: "2 400 ₽",
+    color: "purple",
+  },
+];
+
+const BY_VALUE = new Map(TARIFFS.map((tariff) => [tariff.value, tariff]));
+
+export default function SelectRichOptionsExample() {
+  return (
+    <Select.Root label="Доставка" defaultValue="courier" placeholder="Выберите тариф">
+      <Select.Trigger>
+        <Select.Value
+          renderValue={({ value, label }) => {
+            const tariff = BY_VALUE.get(value);
+            return (
+              <>
+                <Thumbnail.Root color={tariff?.color}>
+                  <Thumbnail.Fallback>
+                    <Icon name="object.truck" />
+                  </Thumbnail.Fallback>
+                </Thumbnail.Root>
+                <Select.ItemText>{label}</Select.ItemText>
+                <Select.ItemDescription>
+                  {tariff?.terms} · {tariff?.price}
+                </Select.ItemDescription>
+              </>
+            );
+          }}
+        />
+      </Select.Trigger>
+      <Select.Content>
+        {TARIFFS.map((tariff) => (
+          <Select.Item key={tariff.value} value={tariff.value}>
+            <Thumbnail.Root color={tariff.color}>
+              <Thumbnail.Fallback>
+                <Icon name="object.truck" />
+              </Thumbnail.Fallback>
+            </Thumbnail.Root>
+            <Select.ItemText>{tariff.title}</Select.ItemText>
+            <Select.ItemDescription>{tariff.terms}</Select.ItemDescription>
+            <Select.ItemMeta>{tariff.price}</Select.ItemMeta>
+          </Select.Item>
+        ))}
+      </Select.Content>
+    </Select.Root>
+  );
+}

package/src/components/select/examples/searchable.tsx

@@ -0,0 +1,42 @@
+/** A long list with a search field: options match their label and keywords, groups and the separator hide while searching — `searchable`, `keywords`, `Select.Group`. */
+import { Select } from "prime-ui-kit";
+
+const RUSSIA = [
+  { value: "msk", label: "Москва", keywords: "moscow" },
+  { value: "spb", label: "Санкт-Петербург", keywords: "питер spb" },
+  { value: "nsk", label: "Новосибирск", keywords: "" },
+  { value: "ekb", label: "Екатеринбург", keywords: "екб" },
+  { value: "kzn", label: "Казань", keywords: "" },
+  { value: "nnv", label: "Нижний Новгород", keywords: "нн" },
+];
+
+export default function SelectSearchableExample() {
+  return (
+    <Select.Root
+      label="Город доставки"
+      placeholder="Выберите город"
+      labels={{ search: "Найти город" }}
+    >
+      <Select.Trigger>
+        <Select.Value />
+      </Select.Trigger>
+      <Select.Content searchable>
+        <Select.Group label="Россия">
+          {RUSSIA.map((city) => (
+            <Select.Item key={city.value} value={city.value} keywords={city.keywords}>
+              {city.label}
+            </Select.Item>
+          ))}
+        </Select.Group>
+        <Select.Separator />
+        <Select.Group label="Казахстан">
+          <Select.Item value="ala">Алматы</Select.Item>
+          <Select.Item value="ast">Астана</Select.Item>
+          <Select.Item value="shy" disabled>
+            Шымкент — скоро
+          </Select.Item>
+        </Select.Group>
+      </Select.Content>
+    </Select.Root>
+  );
+}

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

@@ -0,0 +1,23 @@
+/** Every size tier; the label, the list rows and the hint take the tier of the field — `size`. */
+import { Select } from "prime-ui-kit";
+
+const SIZES = ["xs", "s", "m", "l", "xl"] as const;
+
+export default function SelectSizesExample() {
+  return (
+    <>
+      {SIZES.map((size) => (
+        <Select.Root key={size} size={size} label={size} defaultValue="week">
+          <Select.Trigger>
+            <Select.Value />
+          </Select.Trigger>
+          <Select.Content>
+            <Select.Item value="day">За день</Select.Item>
+            <Select.Item value="week">За неделю</Select.Item>
+            <Select.Item value="month">За месяц</Select.Item>
+          </Select.Content>
+        </Select.Root>
+      ))}
+    </>
+  );
+}

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

@@ -0,0 +1,67 @@
+/** A default field next to a disabled, a loading, an invalid one and a list with nothing in it — `disabled`, `loading`, `invalid`, `labels`. */
+import { Select } from "prime-ui-kit";
+
+const ROLES = [
+  { value: "viewer", label: "Наблюдатель" },
+  { value: "editor", label: "Редактор" },
+  { value: "admin", label: "Администратор" },
+];
+
+export default function SelectStatesExample() {
+  return (
+    <>
+      <Select.Root label="default" defaultValue="editor">
+        <Select.Trigger>
+          <Select.Value />
+        </Select.Trigger>
+        <Select.Content>
+          {ROLES.map((role) => (
+            <Select.Item key={role.value} value={role.value}>
+              {role.label}
+            </Select.Item>
+          ))}
+        </Select.Content>
+      </Select.Root>
+      <Select.Root label="disabled" defaultValue="viewer" disabled>
+        <Select.Trigger>
+          <Select.Value />
+        </Select.Trigger>
+        <Select.Content>
+          {ROLES.map((role) => (
+            <Select.Item key={role.value} value={role.value}>
+              {role.label}
+            </Select.Item>
+          ))}
+        </Select.Content>
+      </Select.Root>
+      <Select.Root label="loading" placeholder="Загружаем роли…" loading>
+        <Select.Trigger>
+          <Select.Value />
+        </Select.Trigger>
+        <Select.Content>{null}</Select.Content>
+      </Select.Root>
+      <Select.Root label="invalid" placeholder="Выберите роль" invalid>
+        <Select.Trigger>
+          <Select.Value />
+        </Select.Trigger>
+        <Select.Content>
+          {ROLES.map((role) => (
+            <Select.Item key={role.value} value={role.value}>
+              {role.label}
+            </Select.Item>
+          ))}
+        </Select.Content>
+      </Select.Root>
+      <Select.Root
+        label="labels.empty"
+        placeholder="Нет доступных команд"
+        labels={{ empty: "Команд пока нет" }}
+      >
+        <Select.Trigger>
+          <Select.Value />
+        </Select.Trigger>
+        <Select.Content>{null}</Select.Content>
+      </Select.Root>
+    </>
+  );
+}

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

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

package/src/components/select/examples/with-icon.tsx

@@ -0,0 +1,35 @@
+/** A leading icon in the trigger and an icon before every option label — `Select.TriggerIcon`, `Select.ItemIcon`. */
+import { Icon, Select } from "prime-ui-kit";
+import * as React from "react";
+
+const ACCESS = [
+  { value: "public", label: "Виден в поиске", icon: "action.search" },
+  { value: "invite", label: "Только по приглашению", icon: "field.email" },
+  { value: "private", label: "Только участники", icon: "status.locked" },
+] as const;
+
+export default function SelectWithIconExample() {
+  const [access, setAccess] = React.useState<string>("invite");
+  const selected = ACCESS.find((option) => option.value === access) ?? ACCESS[1];
+
+  return (
+    <Select.Root label="Доступ к проекту" value={access} onValueChange={setAccess}>
+      <Select.Trigger>
+        <Select.TriggerIcon>
+          <Icon name={selected.icon} />
+        </Select.TriggerIcon>
+        <Select.Value />
+      </Select.Trigger>
+      <Select.Content>
+        {ACCESS.map((option) => (
+          <Select.Item key={option.value} value={option.value}>
+            <Select.ItemIcon>
+              <Icon name={option.icon} />
+            </Select.ItemIcon>
+            {option.label}
+          </Select.Item>
+        ))}
+      </Select.Content>
+    </Select.Root>
+  );
+}

package/src/components/skeleton/COMPONENT.md

@@ -0,0 +1,104 @@
+# Skeleton
+
+**Category:** feedback
+**Kind:** primitive
+
+> A placeholder in the shape of the content that is loading — text lines, a control, an avatar, a block — so the layout is in place before the data arrives.
+
+## When to use
+- A region whose content has a known shape is loading: a list, a card, a profile, a form with saved values.
+- The loading state inside [Crossfade](../crossfade/COMPONENT.md): the skeleton holds the data's geometry and cross-fades into it.
+- First load of a page section, when the structure is known before the values.
+
+## When not to use
+- Loading with no shape to hold (a button waiting for its request, a status line) → [Spinner](../spinner/COMPONENT.md), or `loading` on [Button](../button/COMPONENT.md).
+- A known progress (upload, steps) → [ProgressBar](../progress-bar/COMPONENT.md) or [ProgressCircle](../progress-circle/COMPONENT.md).
+- A table loading its rows → `loading` on [DataTable](../data-table/COMPONENT.md); it renders skeleton rows of its columns itself.
+- Data already on screen being refreshed → keep it and set `aria-busy`; do not swap it back to a skeleton.
+
+## Import
+```tsx
+import { Skeleton } from "prime-ui-kit";
+```
+
+## Anatomy
+```
+Skeleton           <span aria-hidden="true">; data-shape, data-size
+└─ line × lines    shape="text" only: one line box per line, a rounded bar in its middle
+```
+
+## API
+
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+### Skeleton
+`ref` → `HTMLSpanElement`. A pulsing placeholder in the shape of loading content; `aria-hidden="true"`.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `shape` | `"text" \| "control" \| "circle" \| "block"` | `"text"` | `text` — lines of the tier's text; `control` — a field or button of the tier; `circle` — an avatar of the tier; `block` — a box that fills its container (image, chart, card). |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `host tier, else "m"` | Tier of the text line (control text size and line height), the control height or the avatar size. |
+| `lines` | `number` | `1` | `text` only: number of lines; the last of several is 60% wide. |
+| `…rest` | `Omit<HTMLAttributes<HTMLSpanElement>, "children">` | — | `className` (width, height of a `block`), `data-*` and the other span attributes. |
+
+## Variants
+
+### shape
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `text` | rounded bars on the tier's text line boxes; the last of several lines is 60% wide | titles, names, descriptions, cells | yes |
+| `control` | a block of the tier's control height and radius, full width | fields, buttons, selects of a form | |
+| `circle` | a circle of the tier's avatar size | avatars, round icons | |
+| `block` | a radius-l block that fills its container (at least 64px high) | images, covers, charts, whole cards | |
+
+### size
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `xs` · `s` · `m` · `l` · `xl` | text: the control text size and line height of the tier; control: the control height; circle: the avatar size | the tier of the content it stands for | host tier, else `m` |
+
+## States
+| State | Driven by | DOM |
+|---|---|---|
+| pulsing | mounted | opacity eases 1 → 0.4 and back (`slow × 5`, `standard`, alternate) |
+| reduced motion | `prefers-reduced-motion: reduce` | no pulse: the placeholder stands still and stays visible |
+| shape / size | `shape`, `size` | `data-shape`, `data-size` |
+
+## Layout & spacing
+- Put skeletons in the real layout of the content: the same grid, gaps and paddings, so the swap to data moves nothing.
+- Width: a text line and a control fill their container; narrow them with a `className` (a label is shorter than its field, an amount shorter than a name). Shape defaults have zero specificity, so a `className` always wins.
+- Height: text and control come from the tier; a `block` fills its container or takes a height from `className`.
+- Inside a sized host (a DataTable, a Popover, a field tier) `size` follows the host tier.
+
+## Accessibility
+
+### Keyboard
+No keyboard interaction.
+
+### ARIA
+- Decorative: `aria-hidden="true"`, screen readers skip it.
+- The loading region announces itself: `aria-busy` on it (Crossfade, a card, a form) and, when the wait matters, a `role="status"` text.
+- Under `prefers-reduced-motion` the placeholder does not pulse.
+
+### 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 project card while it loads: the cover, the author and two lines of text take the room of the real content — `shape`, `lines`. |
+| [sizes.tsx](examples/sizes.tsx) | Every tier of a text line, a control and an avatar circle: the placeholder matches the content of that tier — `size`, `shape`. |
+| [form.tsx](examples/form.tsx) | A settings form while its values load: labels are short text lines, fields and the button are controls of the same tier — `shape`. |
+| [with-crossfade.tsx](examples/with-crossfade.tsx) | A list that reloads: placeholder rows of the same geometry cross-fade into the data, nothing jumps — `Crossfade`, `state`. |
+
+## Mistakes
+- A hand-drawn grey box with its own `@keyframes` → use `Skeleton`.
+- A spinner in the middle of an empty card while its list loads → skeleton rows of that list.
+- Skeletons of a different geometry than the data (one tall block for three rows) → the swap jumps; mirror the rows.
+- Swapping a skeleton for data without `Crossfade` → wrap the region: `Crossfade state={loading ? "loading" : "ready"}`.
+- Returning to a skeleton on every refresh of data already shown → keep the data, set `aria-busy`.
+
+## Related
+- **Built from:** —
+- **See also:** [Crossfade](../crossfade/COMPONENT.md), [Spinner](../spinner/COMPONENT.md), [DataTable](../data-table/COMPONENT.md), [EmptyPage](../empty-page/COMPONENT.md)

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

@@ -0,0 +1,89 @@
+/* Layout of the Skeleton scenarios: semantic tokens only. */
+
+.card {
+  width: min(100%, calc(var(--prime-space-24) * 3.5));
+}
+
+.content {
+  display: grid;
+  gap: var(--prime-space-4);
+}
+
+.cover {
+  height: calc(var(--prime-space-24) + var(--prime-space-12));
+}
+
+.author {
+  display: flex;
+  align-items: center;
+  gap: var(--prime-space-3);
+}
+
+.form {
+  display: grid;
+  gap: var(--prime-space-5);
+  width: min(100%, calc(var(--prime-space-24) * 4));
+}
+
+.field {
+  display: grid;
+  gap: var(--prime-space-2);
+}
+
+/* A label is shorter than its field. */
+.label {
+  width: 40%;
+}
+
+/* The placeholder of the submit button: a button, not a full-width field. */
+.button {
+  width: calc(var(--prime-space-24) + var(--prime-space-8));
+}
+
+.stack {
+  display: grid;
+  justify-items: start;
+  gap: var(--prime-space-4);
+  width: min(100%, calc(var(--prime-space-24) * 5));
+}
+
+.stack > * {
+  justify-self: stretch;
+}
+
+.stack > :first-child {
+  justify-self: start;
+}
+
+.list {
+  display: grid;
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+/* Data rows and their placeholders share one row geometry, so the swap does not move anything. */
+.row {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--prime-space-4);
+  padding-block: var(--prime-space-3);
+  border-bottom: var(--prime-border-width) solid var(--prime-color-border-subtle);
+}
+
+.row:last-child {
+  border-bottom: 0;
+}
+
+.payer {
+  width: 55%;
+}
+
+.amount {
+  width: 20%;
+}
+
+.sum {
+  font-variant-numeric: tabular-nums;
+}