prime-ui-kit 0.14.0 → 0.16.0

package/src/components/sheet/examples/header-actions.tsx

@@ -0,0 +1,75 @@
+/** The courier is at the door: an icon tile heads the sheet, the payment status and a ⋯ menu sit before the close button, and two equal buttons fill the footer — `Sheet.Icon`, `Sheet.Actions`, `layout`. */
+import { Badge, Button, ConfirmDialog, Dropdown, Icon, Sheet, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+/** Pretends to refuse the order on the server. */
+function refuseOrder() {
+  return new Promise((resolve) => setTimeout(resolve, 900));
+}
+
+export default function SheetHeaderActionsExample() {
+  const [open, setOpen] = React.useState(false);
+  const [refusing, setRefusing] = React.useState(false);
+
+  return (
+    <Sheet.Root open={open} onOpenChange={setOpen}>
+      <Sheet.Trigger>
+        <Button.Root variant="soft" tone="neutral">
+          Курьер на месте
+        </Button.Root>
+      </Sheet.Trigger>
+      <Sheet.Content>
+        <Sheet.Header>
+          <Sheet.Icon tone="info">
+            <Icon name="object.truck" />
+          </Sheet.Icon>
+          <Sheet.Title>Курьер у двери</Sheet.Title>
+          <Sheet.Description>Заказ № 1042 · 3 коробки</Sheet.Description>
+          <Sheet.Actions>
+            <Badge.Root tone="success">Оплачен</Badge.Root>
+            <Dropdown.Root>
+              <Dropdown.Trigger>
+                <Button.Root variant="ghost" tone="neutral" aria-label="Действия с заказом">
+                  <Button.Icon>
+                    <Icon name="action.more" />
+                  </Button.Icon>
+                </Button.Root>
+              </Dropdown.Trigger>
+              <Dropdown.Content>
+                <Dropdown.Item>Позвонить курьеру</Dropdown.Item>
+                <Dropdown.Item>Перенести доставку</Dropdown.Item>
+                <Dropdown.Separator />
+                <Dropdown.Item tone="danger" onSelect={() => setRefusing(true)}>
+                  Отказаться от заказа
+                </Dropdown.Item>
+              </Dropdown.Content>
+            </Dropdown.Root>
+          </Sheet.Actions>
+        </Sheet.Header>
+        <Sheet.Body>
+          <Typography variant="body-m" tone="secondary">
+            Проверьте коробки при курьере: после приёмки претензии к упаковке не принимаются.
+          </Typography>
+        </Sheet.Body>
+        <Sheet.Footer layout="fill">
+          <Sheet.Close>
+            <Button.Root variant="outline" tone="neutral">
+              Позже
+            </Button.Root>
+          </Sheet.Close>
+          <Sheet.Close>
+            <Button.Root>Принять заказ</Button.Root>
+          </Sheet.Close>
+        </Sheet.Footer>
+        <ConfirmDialog.Root
+          open={refusing}
+          onOpenChange={setRefusing}
+          title="Отказаться от заказа № 1042?"
+          description="Курьер увезёт коробки обратно, деньги вернутся в течение трёх дней."
+          confirmLabel="Отказаться"
+          onConfirm={() => refuseOrder().then(() => setOpen(false))}
+        />
+      </Sheet.Content>
+    </Sheet.Root>
+  );
+}

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

@@ -1,5 +1,6 @@
 /** Actions with an order raised from the bottom edge: a header names the order, a column of actions follows, and each action closes the sheet — `Sheet.Trigger`, `Sheet.Header`, `Sheet.Close`. */
-import { Button, Icon, Sheet } from "prime-ui-kit";
+import { Button, ConfirmDialog, Icon, Sheet } from "prime-ui-kit";
+import * as React from "react";
 
 import styles from "./examples.module.css";
 
@@ -9,9 +10,16 @@ const ACTIONS = [
   { label: "Скопировать ссылку", icon: "action.copy" },
 ] as const;
 
+/** Pretends to cancel the order on the server. */
+function cancelOrder() {
+  return new Promise((resolve) => setTimeout(resolve, 900));
+}
+
 export default function SheetOverviewExample() {
+  const [open, setOpen] = React.useState(false);
+
   return (
-    <Sheet.Root>
+    <Sheet.Root open={open} onOpenChange={setOpen}>
       <Sheet.Trigger>
         <Button.Root variant="soft" tone="neutral">
           Действия с заказом
@@ -34,14 +42,21 @@ export default function SheetOverviewExample() {
                 </Button.Root>
               </Sheet.Close>
             ))}
-            <Sheet.Close>
-              <Button.Root variant="ghost" tone="danger" fullWidth>
-                <Button.Icon>
-                  <Icon name="action.delete" />
-                </Button.Icon>
-                Отменить заказ
-              </Button.Root>
-            </Sheet.Close>
+            <ConfirmDialog.Root
+              title="Отменить заказ № 1042?"
+              description="Клиент получит уведомление, а оплата вернётся на карту."
+              confirmLabel="Отменить заказ"
+              onConfirm={() => cancelOrder().then(() => setOpen(false))}
+            >
+              <ConfirmDialog.Trigger>
+                <Button.Root variant="ghost" tone="danger" fullWidth>
+                  <Button.Icon>
+                    <Icon name="action.delete" />
+                  </Button.Icon>
+                  Отменить заказ
+                </Button.Root>
+              </ConfirmDialog.Trigger>
+            </ConfirmDialog.Root>
           </div>
         </Sheet.Body>
       </Sheet.Content>

package/src/components/skeleton/COMPONENT.md

@@ -37,7 +37,7 @@ Skeleton           <span aria-hidden="true">; data-shape, data-size
 | 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. |
+| `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. |
 
@@ -65,16 +65,20 @@ Skeleton           <span aria-hidden="true">; 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`.
+- 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). Every size default — the `max-width: 100%` cap too — has zero specificity, so a `className` always wins.
+- Height: text and control come from the tier (the shared tier table, `internal/fieldTier`); a `block` fills its container — an absolutely placed media box too — or takes a height from `className`.
 - Inside a sized host (a DataTable, a Popover, a field tier) `size` follows the host tier.
 
 ## Accessibility
 
 ### Keyboard
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 No keyboard interaction.
 
 ### ARIA
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 - 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.
@@ -100,5 +104,5 @@ No `labels`.
 - Returning to a skeleton on every refresh of data already shown → keep the data, set `aria-busy`.
 
 ## Related
-- **Built from:** —
+- **Built from:** `internal/fieldClasses` (the tier table)
 - **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

@@ -57,9 +57,7 @@
 
 .list {
   display: grid;
-  margin: 0;
-  padding: 0;
-  list-style: none;
+  gap: var(--prime-space-3);
 }
 
 /* Data rows and their placeholders share one row geometry, so the swap does not move anything. */
@@ -68,12 +66,6 @@
   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 {
@@ -83,7 +75,3 @@
 .amount {
   width: 20%;
 }
-
-.sum {
-  font-variant-numeric: tabular-nums;
-}

package/src/components/skeleton/examples/with-crossfade.tsx

@@ -41,25 +41,25 @@ export default function SkeletonWithCrossfadeExample() {
         </Card.Header>
         <Card.Body>
           <Crossfade state={loading ? "loading" : "ready"} aria-busy={loading}>
-            <ul className={styles.list}>
+            <div className={styles.list}>
               {PAYMENTS.map((payment) =>
                 loading ? (
-                  <li key={payment.id} className={styles.row}>
+                  <div key={payment.id} className={styles.row}>
                     <Skeleton className={styles.payer} />
                     <Skeleton className={styles.amount} />
-                  </li>
+                  </div>
                 ) : (
-                  <li key={payment.id} className={styles.row}>
+                  <div key={payment.id} className={styles.row}>
                     <Typography as="span" variant="body-m">
                       {payment.payer}
                     </Typography>
-                    <Typography as="span" variant="body-m" className={styles.sum}>
+                    <Typography as="span" variant="body-m" numeric="tabular">
                       {payment.amount}
                     </Typography>
-                  </li>
+                  </div>
                 ),
               )}
-            </ul>
+            </div>
           </Crossfade>
         </Card.Body>
       </Card.Root>

package/src/components/slider/COMPONENT.md

@@ -51,7 +51,7 @@ Slider                 field frame (FieldFrame): className, ref, rest
 | `min` | `number` | `0` | Lower bound. |
 | `max` | `number` | `100` | Upper bound. |
 | `step` | `number` | `1` | Step of the keyboard and of the snapping; fractions allowed. |
-| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `host tier, else "m"` | Tier of the track thickness T (thumb 4.5T × 3T), the label, the value and the hint. Without it the tier of its host (a form, a panel), else `m`. |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | host tier, else `"m"` | Tier of the track thickness T (thumb 4.5T × 3T), the label, the value and the hint. Without it the tier of its host (a form, a panel), else `m`. |
 | `tone` | `"neutral" \| "accent" \| "success" \| "warning" \| "danger" \| "info"` | `"accent"` | Color of the filled part of the track. |
 | `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | `vertical` — the track stands upright, minimum at the bottom: a level beside a button, a mixer column. |
 | `disabled` | `boolean` | — | Muted track and thumb, dimmed label and value, no interaction. |
@@ -73,7 +73,7 @@ Slider                 field frame (FieldFrame): className, ref, rest
 No `variant` / `color`.
 
 ### size
-Everything derives from the tier track thickness T (`--prime-control-<tier>-track`, shared with ProgressBar): the thumb is a 4.5T × 3T capsule, so the control scales as one shape.
+Everything derives from the tier track thickness T (`--field-track` of the field tier, shared with ProgressBar): the thumb is a 4.5T × 3T capsule, so the control scales as one shape.
 
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
@@ -108,6 +108,7 @@ Tone never carries meaning alone: the label names what the value means.
 |---|---|---|---|
 | `showValue` | the value at the right end of the label row, `text-secondary`, tabular nums | the number matters (price, temperature, percent) | `false` |
 | `disabled` | muted track, flat thumb, dimmed label and value | the setting is unavailable | — |
+| `required` / `optional` | red `*` / muted «необязательно» after the label | mark the minority of the form (a range always has a value, so `required` only marks it) | — |
 
 **Combinations**
 - `showValue` + `formatValue` for any value with a unit; `formatValue` alone only changes `aria-valuetext`.
@@ -132,12 +133,14 @@ Controlled: `value` + `onValueChange`. Uncontrolled: `defaultValue` (falls back
 ## Layout & spacing
 - Fills its container; place it in a grid column to limit the width.
 - Label row → track: tier `label-gap`; label and value share a baseline, the value is pinned right. Track → hint / error: tier `hint-gap` (FieldFrame, like every field).
-- Between sliders in a form: `--prime-space-5`.
-- With a paired input: grid `minmax(0, 1fr)` + a fixed column, `align-items: end`, gap `--prime-space-4`.
+- Sliders of a form stack in a label-less [Fieldset](../fieldset/COMPONENT.md) (20 apart).
+- With a paired input: grid `minmax(0, 1fr)` + a fixed column, `align-items: end`, a 16 gap.
 
 ## Accessibility
 
 ### Keyboard
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 | Key | Action |
 |---|---|
 | `ArrowRight` · `ArrowUp` | Increases the value by `step`. |
@@ -146,6 +149,8 @@ Controlled: `value` + `onValueChange`. Uncontrolled: `defaultValue` (falls back
 | `Home` · `End` | Jumps to `min` / `max`. |
 
 ### ARIA
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 - A native `<input type="range">` (`role="slider"`) on top of the visual layer.
 - `label` is a `<label htmlFor>`; otherwise `aria-label` is required.
 - `orientation="vertical"` turns the native range with `writing-mode`, so ↑ / ↓ and the pointer work natively; the input has `aria-orientation="vertical"`.
@@ -166,13 +171,14 @@ Controlled: `value` + `onValueChange`. Uncontrolled: `defaultValue` (falls back
 | [overview.tsx](examples/overview.tsx) | A labelled slider with its current value — `label`, `showValue`. |
 | [variants.tsx](examples/variants.tsx) | Every fill color; accent by default, semantic tones when the value carries meaning — `tone`. |
 | [sizes.tsx](examples/sizes.tsx) | Every size; the thumb, the label and the value grow with the tier — `size`. |
-| [states.tsx](examples/states.tsx) | The fill at both ends and a disabled slider — `disabled`. |
+| [states.tsx](examples/states.tsx) | The fill at both ends, an invalid slider and a disabled one — `invalid`, `disabled`. |
 | [orientation.tsx](examples/orientation.tsx) | Notification levels as a row of upright sliders, minimum at the bottom — `orientation`. |
 | [value-format.tsx](examples/value-format.tsx) | Units in the shown value that are also read by screen readers — `formatValue`, `showValue`. |
 | [range-step.tsx](examples/range-step.tsx) | Own bounds and a coarse or fractional step; a slider without a visible label — `min`, `max`, `step`, `aria-label`. |
 | [hint-and-error.tsx](examples/hint-and-error.tsx) | A slider framed like every field: required marker, a hint, and an error in its place — `required`, `hint`, `error`, `optional`. |
 | [autosave.tsx](examples/autosave.tsx) | A setting saved once the thumb is let go, not on every step: the thumb waits dimmed while it saves, and a value the server refuses glides back — `onCommit`, `hint`, `error`. |
 | [controlled.tsx](examples/controlled.tsx) | The parent owns the value and shares it with a number field for exact entry — `value`, `onValueChange`. |
+| [in-form.tsx](examples/in-form.tsx) | Campaign limits submitted with the form by `name`, a calm note confirms the save — `name`, `label`. |
 
 ## Mistakes
 - `<Slider.Root>` → the slider is a single export: `<Slider />`.
@@ -182,5 +188,5 @@ Controlled: `value` + `onValueChange`. Uncontrolled: `defaultValue` (falls back
 - Saving a setting in `onValueChange` → it fires on every step of a drag; save in `onCommit`.
 
 ## Related
-- **Built from:** the field frame — [Label](../label/COMPONENT.md) (`label`) and [Hint](../hint/COMPONENT.md) (`hint`, `error`)
+- **Built from:** the field frame — [Label](../label/COMPONENT.md) (`label`) and [Hint](../hint/COMPONENT.md) (`hint`, `error`), [VisuallyHidden](../visually-hidden/COMPONENT.md)
 - **See also:** [ProgressBar](../progress-bar/COMPONENT.md) (the same track scale), [Input](../input/COMPONENT.md), [SegmentedControl](../segmented-control/COMPONENT.md)

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

@@ -1,11 +1,10 @@
 /* Layout of the Slider scenarios: semantic tokens only. */
 
-/* hint-and-error.tsx: fields of a form column, field → field 24. */
-.column {
-  display: flex;
-  flex-direction: column;
-  gap: var(--prime-space-6);
-  width: min(100%, var(--prime-modal-width-s));
+/* in-form.tsx: the fields (a Fieldset), then the submit row (group → actions 32). */
+.form {
+  display: grid;
+  gap: var(--prime-space-8);
+  width: min(100%, var(--prime-layout-form-width-s));
 }
 
 /* controlled.tsx: the slider takes the row, the number field a fixed column. */
@@ -14,7 +13,7 @@
   grid-template-columns: minmax(0, 1fr) var(--prime-space-24);
   align-items: end;
   gap: var(--prime-space-4);
-  width: min(100%, var(--prime-modal-width-s));
+  width: min(100%, var(--prime-layout-form-width-s));
 }
 
 /* orientation.tsx: upright sliders side by side, a mixer row. */
@@ -22,3 +21,11 @@
   display: flex;
   gap: var(--prime-space-8);
 }
+
+/* in-form.tsx: the submit row after the fields, the note beside the button. */
+.actions {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: var(--prime-space-3);
+}

package/src/components/slider/examples/hint-and-error.tsx

@@ -1,14 +1,12 @@
 /** A slider framed like every field: required marker, a hint, and an error in its place — `required`, `hint`, `error`, `optional`. */
-import { Slider } from "prime-ui-kit";
+import { Fieldset, Slider } from "prime-ui-kit";
 import * as React from "react";
 
-import styles from "./examples.module.css";
-
 export default function SliderHintAndErrorExample() {
   const [budget, setBudget] = React.useState(80);
 
   return (
-    <div className={styles.column}>
+    <Fieldset aria-label="Бюджет кампании">
       <Slider
         label="Бюджет кампании, тыс. ₽"
         required
@@ -28,6 +26,6 @@ export default function SliderHintAndErrorExample() {
         defaultValue={30}
         hint="По умолчанию показы распределяются равномерно"
       />
-    </div>
+    </Fieldset>
   );
 }

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

@@ -0,0 +1,49 @@
+/** Campaign limits submitted with the form by `name`, a calm note confirms the save — `name`, `label`. */
+import { Button, Fieldset, Slider, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+export default function SliderInFormExample() {
+  const [saved, setSaved] = React.useState<string>();
+
+  const submit = (event: React.FormEvent<HTMLFormElement>) => {
+    event.preventDefault();
+    const data = new FormData(event.currentTarget);
+    setSaved(
+      `Сохранено: показов в день — ${data.get("dailyCap")}, ставка — ${data.get("bidShare")}%.`,
+    );
+  };
+
+  return (
+    <form className={styles.form} noValidate onSubmit={submit}>
+      <Fieldset aria-label="Лимиты кампании">
+        <Slider
+          label="Показов одному клиенту в день"
+          name="dailyCap"
+          min={1}
+          max={10}
+          defaultValue={3}
+          showValue
+          onValueChange={() => setSaved(undefined)}
+        />
+        <Slider
+          label="Доля бюджета на ставки, %"
+          name="bidShare"
+          step={5}
+          defaultValue={40}
+          showValue
+          onValueChange={() => setSaved(undefined)}
+        />
+      </Fieldset>
+      <div className={styles.actions}>
+        <Button.Root type="submit">Сохранить лимиты</Button.Root>
+        {saved ? (
+          <Typography as="p" variant="body-s" tone="secondary" role="status">
+            {saved}
+          </Typography>
+        ) : null}
+      </div>
+    </form>
+  );
+}

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

@@ -1,4 +1,4 @@
-/** The fill at both ends and a disabled slider — `disabled`. */
+/** The fill at both ends, an invalid slider and a disabled one — `invalid`, `disabled`. */
 import { Slider } from "prime-ui-kit";
 
 export default function SliderStatesExample() {
@@ -10,6 +10,9 @@ export default function SliderStatesExample() {
       <div>
         <Slider label="max" showValue defaultValue={100} />
       </div>
+      <div>
+        <Slider label="invalid" showValue defaultValue={90} invalid />
+      </div>
       <div>
         <Slider label="disabled" showValue defaultValue={35} disabled />
       </div>

package/src/components/smart-filter/COMPONENT.md

@@ -59,11 +59,11 @@ The toolbar and the chips are separate parts so a page can put them in different
 | `search` | `string` | — | Search text, controlled. |
 | `defaultSearch` | `string` | `""` | Initial search text, uncontrolled. |
 | `onSearchChange` | `(search: string) => void` | — | Every keystroke; debounce in the owner when it asks a server. |
-| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `"m"` | Tier of the filter button, the search, the tags and the panel. |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | host tier, else `"m"` | Tier of the filter button, the search, the tags and the panel. Without it the tier of its host, else `m`. |
 | `collapsedLimit` | `number` | `12` | Values of one field shown before «Ещё N» (not while searching). |
 | `labels` | `Partial<SmartFilterLabels>` | — | Built-in strings, see Labels. |
-| `className` | `string` | — | Class on the root. |
 | `children` | `ReactNode` | — (required) | `SmartFilter.Toolbar` and `SmartFilter.Chips`, anywhere inside. |
+| `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "children" \| "defaultValue" \| "onChange">` | — | `className` and the other div attributes. |
 
 ### SmartFilter.Toolbar
 `ref` → `HTMLDivElement`. A `<div>`: the search Input first, then the filter Button (a count Badge while filters apply); the anchor of the panel, a flush Popover.
@@ -80,10 +80,12 @@ The toolbar and the chips are separate parts so a page can put them in different
 |---|---|---|---|
 | `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "children">` | — | `className` and the other attributes of the chips row. |
 
-### SmartFilterField
+### Types
+
+#### `SmartFilterField`
 One entry of `fields`: data, not a part. Selected values missing from `options` stay visible so they can be removed.
 
-| Prop | Type | Default | Description |
+| Field | Type | Default | Description |
 |---|---|---|---|
 | `key` | `string` | — (required) | Key of the field in the value. |
 | `label` | `string` | — (required) | Field name in the panel and the chips. |
@@ -91,10 +93,24 @@ One entry of `fields`: data, not a part. Selected values missing from `options`
 | `options` | `{ value: string; label: string; icon?: ReactNode; group?: string }[]` | — (required) | `options` fields: values; `icon` is a decorative kit Icon before the label; values with one `group` stay together under that heading, groups in the order they first appear. |
 | `finite` | `boolean` | `true` | `options` fields: a fixed set — hiding every value is refused. `false` for an open set (services, users). |
 | `multiple` | `boolean` | `true` | `options` fields: many values at once. `false` — one value and no hiding: a press picks only that value, a second press clears it (an API that takes one value per field). |
-| `formatValue` | `(value: number) => string` | `Russian digit groups` | `range` fields: a bound in the chip («1 000 ₽»). |
+| `formatValue` | `(value: number) => string` | Russian digit groups | `range` fields: a bound in the chip («1 000 ₽»). |
+
+### Functions
+
+#### `matchesSmartFilter(entry, item)`
+`(entry: SmartFilterFieldValue \| undefined, item: string \| number \| Date \| null \| undefined) => boolean`
+
+Checks one item's value against a field's entry on the client; an empty entry matches everything.
+
+#### `resolveSmartFilterValues(entry, all)`
+`(entry: SmartFilterFieldValue \| undefined, all: readonly string[]) => string[]`
 
-### matchesSmartFilter · resolveSmartFilterValues · isSmartFilterRange
-Helpers. `matchesSmartFilter(entry, item)` checks one item's value on the client. `resolveSmartFilterValues(entry, all)` turns a fixed field into the list of values to ask a server for. `isSmartFilterRange(entry)` tells a range from a selection.
+Turns a fixed field's entry into the list of values to ask a server for.
+
+#### `isSmartFilterRange(entry)`
+`(entry: SmartFilterFieldValue \| undefined) => entry is SmartFilterRange<number> \| SmartFilterRange<Date>`
+
+Tells a range entry from a selection.
 
 ## Variants
 
@@ -141,7 +157,7 @@ same height and type.
 |---|---|---|
 | closed / open | filter button, search focus | button `aria-expanded`; the panel is a Popover below the toolbar |
 | value neutral | no selection | gray Badge |
-| value shown | press | blue Badge, `aria-pressed="true"`, `data-mode="include"` |
+| value shown | press | the Badge's pressed (selected) look, `aria-pressed="true"`, `data-mode="include"` |
 | value hidden | «−», Alt+click, Shift+Enter | red Badge with «НЕ», `data-mode="exclude"`; its «−» stays visible and unhides |
 | cannot hide | last value of a `finite` field | the «−» is disabled |
 | searching | `search` | only matching values, the match in `accent-text` (a `<mark>`); fields with nothing found in a compact EmptyPage; the «Искать» row closes the panel |
@@ -151,10 +167,10 @@ same height and type.
 | no filters | empty value | no count on the button, no Chips |
 
 ## Layout & spacing
-- The panel is a flush Popover as wide as the toolbar; every section is a full-width row with its own padding (`--prime-space-3` × `--prime-space-4`, footer `--prime-space-2` × `--prime-space-4`), Dividers run edge to edge, the field label column is `--prime-space-24`.
-- The toolbar is one row of controls (`--prime-space-2` gap): the search first, growing from 9rem (`--prime-space-24` × 1.5), then the filter button at its own width. When less than 9rem is left beside the button, the button moves under the search; every row stays one control high. Search first, filter second — the active filters (`SmartFilter.Chips`) sit right under them.
+- The panel is a flush Popover as wide as the toolbar; every section is a full-width row with its own padding (`--prime-space-3` × `--prime-space-4`, footer `--prime-space-2` × `--prime-space-4`), Dividers run edge to edge, the field label column is `--prime-space-24`; a row narrower than 24rem stacks the label over the values (an intrinsic wrap, no breakpoint).
+- The toolbar is one row of controls (`--prime-space-2` gap): the search first, growing from 9rem (`--prime-space-24` × 1.5), then the filter button at its own width. When less than 9rem is left beside the button, the button moves under the search; every row stays one control high. Search first, filter second — the active filters (`SmartFilter.Chips`) sit under them.
 - Chips are Badges of the toolbar tier on the badge scale (`xs` → `s`), so a tag sits lower than the controls above it; «Добавить фильтр» is a tag of the same tier and «Сбросить все» a LinkButton with the tag's text size.
-- Values and chips wrap with `--prime-space-2` gaps; «Сбросить все» is pushed to the end.
+- Values and chips wrap with `--prime-space-2` gaps; «Сбросить все» is pushed to the end. The chips row rises in with the first filter and closes up in place with the last (`partPresence`).
 - Option groups stack `--prime-space-3` apart, a caption `--prime-space-1` above each group's values. A range row holds two equal Inputs with a dash between them, centred on the field label.
 - While typing a search a range row stays only when its field name matches.
 - The root is a flex column (`--prime-space-3`): Toolbar, then Chips.
@@ -162,6 +178,8 @@ same height and type.
 ## Accessibility
 
 ### Keyboard
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 | Key | Action |
 |---|---|
 | `Tab` | Moves through the panel values and their «−» (shown on focus). |
@@ -170,6 +188,8 @@ same height and type.
 | `Enter` · `Escape` | In the search, close the panel. |
 
 ### ARIA
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 - The filter button has `aria-expanded` and `aria-haspopup="dialog"`; the panel is a non-modal `role="dialog"` named by a visually hidden `labels.filter` title.
 - Values are toggle buttons with `aria-pressed`; the «−» has its own name (`labels.hideValue` / `labels.unhideValue`); a hidden value carries the «НЕ» text, so meaning is never in color alone.
 - Fields with nothing found are announced through `role="status"`.
@@ -213,7 +233,7 @@ same height and type.
 | [overview.tsx](examples/overview.tsx) | Filters above a request list: the filter button and the search, applied filters as tags, rows narrowed by the value and the text — `fields`, `value`, `search`, `matchesSmartFilter`. |
 | [sizes.tsx](examples/sizes.tsx) | Every size tier: the filter button, the search, the tags and the panel follow one tier — `size`. |
 | [many-values.tsx](examples/many-values.tsx) | An open set of twenty services, degraded ones marked with an icon, collapsed after eight; typing narrows the panel and marks the match in accent — `finite`, `icon`, `collapsedLimit`. |
-| [ranges.tsx](examples/ranges.tsx) | Deals narrowed by an amount from–to and a period from the calendar; each range is one readable chip — `kind`, `formatValue`, `matchesSmartFilter`. |
+| [ranges.tsx](examples/ranges.tsx) | Deals narrowed by an amount from–to and a period from the calendar; each range is one readable chip, and the bounds go to the server as from / to parameters — `kind`, `formatValue`, `matchesSmartFilter`, `isSmartFilterRange`. |
 | [single-value.tsx](examples/single-value.tsx) | For an API that takes one value per field: the filter button without a search, a press picks only that value and nothing can be hidden — `searchable`, `multiple`. |
 | [option-groups.tsx](examples/option-groups.tsx) | Values of different kinds in one field: owner types and people under their own headings — `options`, `group`. |
 | [controlled.tsx](examples/controlled.tsx) | A saved view sets the value from outside; the selection is read back as the list to ask the server for — `value`, `onValueChange`, `resolveSmartFilterValues`. |
@@ -231,5 +251,5 @@ same height and type.
 - Cutting the «−» and the search off on the client for a one-value API → `multiple: false` and `searchable={false}`.
 
 ## Related
-- **Built from:** [Button](../button/COMPONENT.md), [Badge](../badge/COMPONENT.md), [Input](../input/COMPONENT.md), [Datepicker](../datepicker/COMPONENT.md), [Popover](../popover/COMPONENT.md), [Divider](../divider/COMPONENT.md), [Kbd](../kbd/COMPONENT.md), [EmptyPage](../empty-page/COMPONENT.md), [LinkButton](../link-button/COMPONENT.md), [Typography](../typography/COMPONENT.md), Icon (`action.search`, `action.filter`, `action.add`, `nav.chevronDown`)
+- **Built from:** [Button](../button/COMPONENT.md), [Badge](../badge/COMPONENT.md), [Input](../input/COMPONENT.md), [Datepicker](../datepicker/COMPONENT.md), [Popover](../popover/COMPONENT.md), [Divider](../divider/COMPONENT.md), [Kbd](../kbd/COMPONENT.md), [EmptyPage](../empty-page/COMPONENT.md), [LinkButton](../link-button/COMPONENT.md), [Typography](../typography/COMPONENT.md), Icon (`action.search`, `action.filter`, `action.add`, `nav.chevronDown`), [VisuallyHidden](../visually-hidden/COMPONENT.md)
 - **See also:** [PageToolbar](../page-toolbar/COMPONENT.md), [TagSelect](../tag-select/COMPONENT.md), [DataTable](../data-table/COMPONENT.md)

package/src/components/smart-filter/examples/controlled.tsx

@@ -30,13 +30,13 @@ export default function SmartFilterControlledExample() {
         <SmartFilter.Chips />
       </SmartFilter.Root>
       <div className={styles.views}>
-        <Button.Root variant="soft" tone="neutral" size="s" onClick={() => setValue(ONLY_PUT)}>
+        <Button.Root variant="soft" tone="neutral" onClick={() => setValue(ONLY_PUT)}>
           Только PUT
         </Button.Root>
-        <Button.Root variant="soft" tone="neutral" size="s" onClick={() => setValue(NO_READS)}>
+        <Button.Root variant="soft" tone="neutral" onClick={() => setValue(NO_READS)}>
           Без GET и POST
         </Button.Root>
-        <Button.Root variant="ghost" tone="neutral" size="s" onClick={() => setValue({})}>
+        <Button.Root variant="ghost" tone="neutral" onClick={() => setValue({})}>
           Сбросить
         </Button.Root>
       </div>

package/src/components/smart-filter/examples/examples.module.css

@@ -8,27 +8,6 @@
   min-width: 0;
 }
 
-/* sizes.tsx: one tier per block, its caption right under it, blocks apart. */
-.sizes {
-  display: flex;
-  flex-direction: column;
-  gap: var(--prime-space-8);
-  width: 100%;
-  min-width: 0;
-}
-
-.size {
-  display: flex;
-  flex-direction: column;
-  align-items: center;
-  gap: var(--prime-space-2);
-  min-width: 0;
-}
-
-.size > :first-child {
-  align-self: stretch;
-}
-
 /* A request row in the list: method, route (takes the room), service. */
 .request {
   display: flex;