prime-ui-kit 0.9.0 → 0.9.2

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

@@ -1,25 +1,21 @@
-/** Empty, filled, error, read-only and disabled fields. Use it to check every state of a multi-line field. */
+/** A default field next to a read-only and a disabled one — `readOnly`, `disabled`. */
 import { Textarea } from "prime-ui-kit";
-import styles from "./examples.module.css";
 
 export default function TextareaStatesExample() {
   return (
-    <div className={styles.pair}>
-      <Textarea.Root label="Пустое" placeholder="Начните печатать" />
-      <Textarea.Root label="Заполненное" defaultValue="Позвоните за час до доставки." />
-      <Textarea.Root label="Ошибка" defaultValue="—" error="Опишите причину возврата." />
+    <>
+      <Textarea.Root label="default" placeholder="Причина возврата" />
       <Textarea.Root
-        label="Только чтение"
+        label="readOnly"
         readOnly
-        defaultValue="Заявка закрыта 12 марта."
-        hint="Текст можно выделить и скопировать."
+        defaultValue="Заявка закрыта 12 марта: товар принят на склад."
       />
       <Textarea.Root
-        label="Отключено"
+        label="disabled"
         disabled
-        placeholder="Недоступно"
-        hint="Поле станет доступно после выбора заказа."
+        placeholder="Причина возврата"
+        hint="Станет доступно после выбора заказа"
       />
-    </div>
+    </>
   );
 }

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

@@ -0,0 +1,34 @@
+/** Required and optional markers, a hint, an error and a support row that does not shift — `required`, `optional`, `hint`, `error`, `reserveSupportRow`. */
+import { Button, Textarea } from "prime-ui-kit";
+import * as React from "react";
+
+export default function TextareaValidationExample() {
+  const [checked, setChecked] = React.useState(false);
+
+  return (
+    <>
+      <Textarea.Root
+        label="Описание задачи"
+        required
+        defaultValue="Подготовить акт сверки с поставщиком за третий квартал."
+        hint="Исполнитель увидит его в карточке задачи"
+      />
+      <Textarea.Root
+        label="Причина отказа"
+        required
+        defaultValue="Нет"
+        error="Опишите причину хотя бы в 20 символах"
+      />
+      <Textarea.Root
+        label="Комментарий для бухгалтерии"
+        optional
+        reserveSupportRow
+        defaultValue="Оплата частями"
+        error={checked ? "Укажите номер договора" : undefined}
+      />
+      <Button.Root variant="soft" tone="neutral" onClick={() => setChecked((value) => !value)}>
+        {checked ? "Сбросить проверку" : "Проверить комментарий"}
+      </Button.Root>
+    </>
+  );
+}

package/src/components/textarea/examples/without-focus-ring.tsx

@@ -0,0 +1,12 @@
+/** A single reply composer where the caret and the lighter fill show focus — `focusRing`. */
+import { Textarea } from "prime-ui-kit";
+
+export default function TextareaWithoutFocusRingExample() {
+  return (
+    <Textarea.Root
+      focusRing={false}
+      aria-label="Ответ клиенту"
+      placeholder="Напишите ответ клиенту"
+    />
+  );
+}

package/src/components/thumbnail/COMPONENT.md

@@ -0,0 +1,150 @@
+# Thumbnail
+
+**Category:** data-display
+**Kind:** primitive
+
+> A preview of an object — product, vehicle, file, cover — at a fixed aspect ratio, with a colored icon fallback.
+
+## When to use
+- An object next to its name in a table cell or list row (vehicle, product, document).
+- Covers in a card grid or gallery (`fullWidth`).
+- Any picture of a thing, with a fallback while it loads or when there is none.
+
+## When not to use
+- A person or an organization's account → use [Avatar](../avatar/COMPONENT.md).
+- An illustration in an empty state → use [EmptyPage](../empty-page/COMPONENT.md).
+- A metric tile with an icon → use [Card](../card/COMPONENT.md).
+
+## Import
+```tsx
+import { Thumbnail } from "prime-ui-kit";
+```
+
+## Anatomy
+```
+Thumbnail.Root          frame: tier height, width from ratio, radius, palette fill; image load state
+├─ Thumbnail.Image      <img>, covers the frame; fades in when loaded, hidden on error
+└─ Thumbnail.Fallback   icon or short label on the fill, under the image
+```
+
+## API
+
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+### Thumbnail.Root
+`ref` → `HTMLDivElement`. The frame: height of the tier, width from `ratio`, radius, palette fill; tracks the image load for the Fallback.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `"m"` | Height 24 · 32 · 40 · 48 · 64 px, radius 4 · 6 · 8 · 8 · 12; width follows `ratio`. |
+| `ratio` | `"1:1" \| "4:3" \| "3:2" \| "16:9" \| "3:4"` | `"1:1"` | Aspect ratio, width ÷ height. |
+| `color` | `"gray" \| "blue" \| "green" \| "orange" \| "red" \| "yellow" \| "purple" \| "sky" \| "pink" \| "teal"` | `"gray"` | Fallback fill and icon hue; a color that means something (category, vehicle color). |
+| `variant` | `"soft" \| "solid"` | `"soft"` | Fallback fill: a soft tint with a hue icon, or a solid hue with a contrasting icon. |
+| `fullWidth` | `boolean` | `false` | Fills the container width (cards, galleries); the height follows `ratio`. |
+| `ring` | `boolean` | `false` | A faint inner ring, for photos with a white background on a light surface. |
+| `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `className`, `aria-label` + `role` for a fallback-only thumbnail, and the other div attributes. |
+
+### Thumbnail.Image
+`ref` → `HTMLImageElement`. The picture; hidden while it loads and after an error, so the Fallback shows through. A new `src` starts again.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `src` | `string` | — (required) | Image URL. |
+| `alt` | `string` | `""` | Empty when the text next to the thumbnail names the object, otherwise a description. |
+| `fit` | `"cover" \| "contain"` | `"cover"` | `cover` crops to fill; `contain` shows the whole image on the fallback fill (logos). |
+| `…rest` | `Omit<ImgHTMLAttributes<HTMLImageElement>, "src" \| "alt">` | — | `className`, `onLoad`, `onError` and the other img attributes. |
+
+### Thumbnail.Fallback
+`ref` → `HTMLSpanElement`. A `<span>` with an icon (sized to the tier) or a short label on the fill; `aria-hidden` once the image has loaded.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `HTMLAttributes<HTMLSpanElement>` | — | `children`, `className` and the other span attributes. |
+
+## Variants
+
+### variant
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `soft` | palette tint, hue icon | lists, tables | yes |
+| `solid` | saturated hue, contrasting icon | the hue is the object's own color (a red bike) | |
+
+### color
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `gray` | neutral fill | no meaningful color | yes |
+| `blue` · `green` · `orange` · `red` · `yellow` · `purple` · `sky` · `pink` · `teal` | hue fill | category or object color | |
+
+### size
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `xs` | 24px high, radius 4 | dense rows | |
+| `s` | 32px high, radius 6 | compact lists | |
+| `m` | 40px high, radius 8 | two-line table cells | yes |
+| `l` | 48px high, radius 8 | list rows with more text | |
+| `xl` | 64px high, radius 12 | detail headers | |
+
+### ratio
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `1:1` | square | logos, product packshots | yes |
+| `4:3` · `3:2` | photo | photos | |
+| `16:9` | wide | vehicles, video covers | |
+| `3:4` | portrait | documents, book covers | |
+
+### Flags
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `fullWidth` | takes the container width, height from `ratio` | card covers, galleries | `false` |
+| `ring` | faint inner ring | white-background photos on a light surface | `false` |
+
+## States
+| State | Driven by | DOM |
+|---|---|---|
+| no image | only Fallback | fill + icon or label |
+| loading | `Thumbnail.Image` mounted | image `data-status="loading"` (transparent), Fallback visible |
+| loaded | image `load` | `data-status="loaded"`, the image fades in; Fallback `aria-hidden` |
+| error | image `error` | `data-status="error"`, image hidden, Fallback visible |
+| frame | props | `data-size`, `data-ratio`, `data-color`, `data-variant`, `data-full-width`, `data-ring` |
+
+## Layout & spacing
+- Thumbnail + text in a row: flex, `align-items: center`, gap `--prime-space-3`; the text column `min-width: 0` with `truncate`.
+- In a table the row grows to the thumbnail; never shrink the thumbnail to the row.
+- Card covers: `fullWidth` inside the card body, gap `--prime-space-3` to the title.
+- No outline by default: the fill separates the preview.
+
+## Accessibility
+
+### Keyboard
+No keyboard interaction.
+
+### ARIA
+- Next to a name the thumbnail is decorative: keep `alt=""` (default) and mark fallback icons `aria-hidden`.
+- Alone: give `Thumbnail.Image` a descriptive `alt`, or `role="img"` + `aria-label` on Root for a fallback-only thumbnail.
+- No behaviour of its own: wrap it in a link or button when it opens the object.
+
+### 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 vehicle next to its name: the photo with an icon fallback underneath — `Thumbnail.Image`, `Thumbnail.Fallback`, `ratio`. |
+| [variants.tsx](examples/variants.tsx) | The fallback fill: a soft tint or a solid hue, in a color that means something — `variant`, `color`. |
+| [sizes.tsx](examples/sizes.tsx) | Every height tier, 24 to 64 px; `m` fits a two-line table cell — `size`. |
+| [states.tsx](examples/states.tsx) | No image (an icon or a short label on the fill) and an image that fails and falls back by itself. |
+| [ratios.tsx](examples/ratios.tsx) | Every aspect ratio at the same height; keep one ratio per list — `ratio`. |
+| [ring.tsx](examples/ring.tsx) | A faint inner ring for a white-background photo on a light surface, where the edge would vanish — `ring`. |
+| [full-width.tsx](examples/full-width.tsx) | Covers in a card grid take the card width and keep 16:9, so every cover has one height — `fullWidth`. |
+
+## Mistakes
+- `Avatar` for a product or vehicle → a circle crops the object; use `Thumbnail`.
+- A `div` with a background image and fixed sizes → use `Thumbnail.Root` with `ratio` and `size`.
+- Width or height in CSS → change `size`, `ratio` or `fullWidth`.
+- No `Thumbnail.Fallback` → a broken image leaves an empty box; always add an icon.
+
+## Related
+- **Built from:** —
+- **See also:** [Avatar](../avatar/COMPONENT.md), [Card](../card/COMPONENT.md), [DataTable](../data-table/COMPONENT.md), [Select](../select/COMPONENT.md)

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

@@ -0,0 +1,45 @@
+/* Layout of the Thumbnail scenarios: semantic tokens only. */
+
+/* ratios.tsx, ring.tsx: thumbnails with captions in one line. */
+.row {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: flex-end;
+  justify-content: center;
+  gap: var(--prime-space-6);
+}
+
+.cell {
+  display: grid;
+  justify-items: center;
+  gap: var(--prime-space-2);
+}
+
+/* overview.tsx: thumbnail + text in a list row. */
+.entity {
+  display: flex;
+  align-items: center;
+  gap: var(--prime-space-3);
+  width: min(100%, var(--prime-modal-width-s));
+  min-width: 0;
+}
+
+.entityText {
+  display: grid;
+  gap: var(--prime-space-1);
+  min-width: 0;
+}
+
+/* full-width.tsx: a card grid. */
+.grid {
+  display: grid;
+  gap: var(--prime-space-4);
+  width: 100%;
+  grid-template-columns: repeat(auto-fill, minmax(min(100%, calc(var(--prime-space-16) * 3)), 1fr));
+}
+
+.cardContent {
+  display: grid;
+  gap: var(--prime-space-3);
+  min-width: 0;
+}

package/src/components/thumbnail/examples/full-width.tsx

@@ -0,0 +1,48 @@
+/** Covers in a card grid take the card width and keep 16:9, so every cover has one height — `fullWidth`. */
+import { Bike } from "lucide-react";
+import { Card, createIcon, type PaletteColor, Thumbnail, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const IconBike = createIcon(Bike);
+
+const BIKES: { id: string; title: string; meta: string; color: PaletteColor; photo?: string }[] = [
+  { id: "1", title: "Honda ADV 350", meta: "2026 · 5672", color: "red" },
+  {
+    id: "2",
+    title: "Yamaha NMAX 155",
+    meta: "2026 · 1408",
+    color: "gray",
+    photo: "https://picsum.photos/seed/nmax/640/360",
+  },
+  { id: "3", title: "Honda PCX 160", meta: "2025 · 9031", color: "blue" },
+];
+
+export default function ThumbnailFullWidthExample() {
+  return (
+    <div className={styles.grid}>
+      {BIKES.map((bike) => (
+        <Card.Root key={bike.id} variant="panel">
+          <Card.Body>
+            <div className={styles.cardContent}>
+              <Thumbnail.Root ratio="16:9" color={bike.color} fullWidth>
+                {bike.photo ? <Thumbnail.Image src={bike.photo} /> : null}
+                <Thumbnail.Fallback>
+                  <IconBike />
+                </Thumbnail.Fallback>
+              </Thumbnail.Root>
+              <div className={styles.entityText}>
+                <Typography as="h3" variant="title-s" truncate>
+                  {bike.title}
+                </Typography>
+                <Typography variant="caption" tone="secondary">
+                  {bike.meta}
+                </Typography>
+              </div>
+            </div>
+          </Card.Body>
+        </Card.Root>
+      ))}
+    </div>
+  );
+}

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

@@ -0,0 +1,31 @@
+/** A vehicle next to its name: the photo with an icon fallback underneath — `Thumbnail.Image`, `Thumbnail.Fallback`, `ratio`. */
+import { Bike } from "lucide-react";
+import { createIcon, Thumbnail, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+/** A domain glyph the kit lacks, turned into a kit icon once. */
+const IconBike = createIcon(Bike);
+
+const PHOTO = "https://picsum.photos/seed/nmax/320/180";
+
+export default function ThumbnailOverviewExample() {
+  return (
+    <div className={styles.entity}>
+      <Thumbnail.Root ratio="16:9" color="gray">
+        <Thumbnail.Image src={PHOTO} />
+        <Thumbnail.Fallback>
+          <IconBike />
+        </Thumbnail.Fallback>
+      </Thumbnail.Root>
+      <div className={styles.entityText}>
+        <Typography variant="body-m" weight="medium" truncate>
+          Yamaha NMAX 155 · 2026
+        </Typography>
+        <Typography variant="caption" tone="secondary" truncate>
+          Серый · Пробег 3 200 км
+        </Typography>
+      </div>
+    </div>
+  );
+}

package/src/components/thumbnail/examples/ratios.tsx

@@ -0,0 +1,25 @@
+/** Every aspect ratio at the same height; keep one ratio per list — `ratio`. */
+import { Icon, Thumbnail, type ThumbnailRatio, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const RATIOS: ThumbnailRatio[] = ["1:1", "4:3", "3:2", "16:9", "3:4"];
+
+export default function ThumbnailRatiosExample() {
+  return (
+    <div className={styles.row}>
+      {RATIOS.map((ratio) => (
+        <div key={ratio} className={styles.cell}>
+          <Thumbnail.Root size="xl" ratio={ratio} color="blue">
+            <Thumbnail.Fallback>
+              <Icon name="object.image" />
+            </Thumbnail.Fallback>
+          </Thumbnail.Root>
+          <Typography as="span" variant="caption" tone="muted">
+            {ratio}
+          </Typography>
+        </div>
+      ))}
+    </div>
+  );
+}

package/src/components/thumbnail/examples/ring.tsx

@@ -0,0 +1,29 @@
+/** A faint inner ring for a white-background photo on a light surface, where the edge would vanish — `ring`. */
+import { Thumbnail, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const PHOTO = "https://picsum.photos/seed/studio-white/320/240?grayscale";
+
+export default function ThumbnailRingExample() {
+  return (
+    <div className={styles.row}>
+      <div className={styles.cell}>
+        <Thumbnail.Root ratio="4:3" size="xl">
+          <Thumbnail.Image src={PHOTO} />
+        </Thumbnail.Root>
+        <Typography as="span" variant="caption" tone="muted">
+          Без кольца
+        </Typography>
+      </div>
+      <div className={styles.cell}>
+        <Thumbnail.Root ratio="4:3" size="xl" ring>
+          <Thumbnail.Image src={PHOTO} />
+        </Thumbnail.Root>
+        <Typography as="span" variant="caption" tone="muted">
+          С кольцом
+        </Typography>
+      </div>
+    </div>
+  );
+}

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

@@ -0,0 +1,23 @@
+/** Every height tier, 24 to 64 px; `m` fits a two-line table cell — `size`. */
+import { Icon, Thumbnail, Typography } from "prime-ui-kit";
+
+const SIZES = ["xs", "s", "m", "l", "xl"] as const;
+
+export default function ThumbnailSizesExample() {
+  return (
+    <div>
+      {SIZES.map((size) => (
+        <div key={size}>
+          <Thumbnail.Root size={size} ratio="4:3" color="orange">
+            <Thumbnail.Fallback>
+              <Icon name="object.package" />
+            </Thumbnail.Fallback>
+          </Thumbnail.Root>
+          <Typography as="span" variant="caption" tone="muted">
+            {size}
+          </Typography>
+        </div>
+      ))}
+    </div>
+  );
+}

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

@@ -0,0 +1,38 @@
+/** No image (an icon or a short label on the fill) and an image that fails and falls back by itself. */
+import { Icon, Thumbnail, Typography } from "prime-ui-kit";
+
+export default function ThumbnailStatesExample() {
+  return (
+    <div>
+      <div>
+        <Thumbnail.Root ratio="4:3" size="l" color="green">
+          <Thumbnail.Fallback>
+            <Icon name="object.package" />
+          </Thumbnail.Fallback>
+        </Thumbnail.Root>
+        <Typography as="span" variant="caption" tone="muted">
+          icon
+        </Typography>
+      </div>
+      <div>
+        <Thumbnail.Root ratio="3:4" size="l" color="purple">
+          <Thumbnail.Fallback>PDF</Thumbnail.Fallback>
+        </Thumbnail.Root>
+        <Typography as="span" variant="caption" tone="muted">
+          label
+        </Typography>
+      </div>
+      <div>
+        <Thumbnail.Root ratio="4:3" size="l">
+          <Thumbnail.Image src="/missing-image.jpg" />
+          <Thumbnail.Fallback>
+            <Icon name="object.document" />
+          </Thumbnail.Fallback>
+        </Thumbnail.Root>
+        <Typography as="span" variant="caption" tone="muted">
+          error
+        </Typography>
+      </div>
+    </div>
+  );
+}

package/src/components/thumbnail/examples/variants.tsx

@@ -0,0 +1,28 @@
+/** The fallback fill: a soft tint or a solid hue, in a color that means something — `variant`, `color`. */
+import { Icon, Thumbnail, Typography } from "prime-ui-kit";
+
+const COLORS = ["gray", "blue", "green", "orange", "red"] as const;
+const VARIANTS = ["soft", "solid"] as const;
+
+export default function ThumbnailVariantsExample() {
+  return (
+    <>
+      {VARIANTS.map((variant) => (
+        <div key={variant}>
+          {COLORS.map((color) => (
+            <div key={color}>
+              <Thumbnail.Root variant={variant} color={color}>
+                <Thumbnail.Fallback>
+                  <Icon name="object.package" />
+                </Thumbnail.Fallback>
+              </Thumbnail.Root>
+              <Typography as="span" variant="caption" tone="muted">
+                {variant} · {color}
+              </Typography>
+            </div>
+          ))}
+        </div>
+      ))}
+    </>
+  );
+}