prime-ui-kit 0.10.0 → 0.11.1

package/src/components/slider/COMPONENT.md

@@ -39,18 +39,21 @@ Slider                 field frame (FieldFrame): className, ref, rest
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
 
 ### Slider
-`ref` → `HTMLDivElement` (the field frame). A framed field like every other: the label row with the value, a native `<input type="range">` (transparent, on top) over the visual track, fill and thumb, then the hint or the error. Field-root rule: `className`, `ref` and the rest go to the frame; `id` and `aria-label` to the range input.
+`ref` → `HTMLDivElement` (the field frame). A framed field: the label row with the value, a native `<input type="range">` over the visual track, then the hint or the error. `id` and `aria-label` go to the range input.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `value` | `number` | — | Controlled value; clamped to `min`…`max`. |
 | `defaultValue` | `number` | `min` | Initial value when uncontrolled. |
 | `onValueChange` | `(value: number) => void` | — | Called with the new number while dragging and on every key step. |
+| `onCommit` | `(value: number) => void \| Promise<void>` | — | The value the person settled on, once after a drag or a key step. Save here, not in `onValueChange`. Return the save's promise: the thumb dims until it settles; on reject the value goes back. |
+| `name` | `string` | — | Name of the range input, submitted with a form. |
 | `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`. |
 | `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. |
 | `label` | `ReactNode` | — | Visible label linked to the range input (`<label htmlFor>`). Without it, set `aria-label`. |
 | `required` | `boolean` | — | Red `*` after the label (`aria-hidden`); a range always has a value, so there is no native `required`. |
@@ -80,7 +83,7 @@ Everything derives from the tier track thickness T (`--prime-control-<tier>-trac
 | `l` | 7px track, 31.5×21 thumb, 14/20 label | spacious settings pages | |
 | `xl` | 8px track, 36×24 thumb, 14/20 label | touch-first screens | |
 
-**Sizes:** the slider fills its container and never gets narrower than 192px (like a native range); the tier changes the track, the thumb and the label / value text. Use the same tier as the other fields of the form.
+**Sizes:** the slider fills its container; the tier changes the track, the thumb and the label / value text. Use the same tier as the other fields of the form.
 
 ### tone
 | Value | Looks like | Use when | Default |
@@ -94,6 +97,12 @@ Everything derives from the tier track thickness T (`--prime-control-<tier>-trac
 
 Tone never carries meaning alone: the label names what the value means.
 
+### orientation
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `horizontal` | the track across its container | a value in a form or a panel | yes |
+| `vertical` | the track upright, minimum at the bottom, seven thumbs long at its tier; the label row above it | a level beside a button (a video's sound), a column of a mixer | |
+
 ### Flags
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
@@ -104,18 +113,21 @@ Tone never carries meaning alone: the label names what the value means.
 - `showValue` + `formatValue` for any value with a unit; `formatValue` alone only changes `aria-valuetext`.
 - Neither `label` nor `aria-label` → forbidden (unnamed control).
 - A paired number input with `showValue` → redundant; drop `showValue`.
+- `onValueChange` for a live preview, `onCommit` to save: it fires once on pointer release or key release, only when the value differs from the last commit.
 
 ## States
 | State | Driven by | DOM |
 |---|---|---|
-| default | — | `data-size`, `data-tone`; track `fill-strong`, tone pill up to the thumb centre, opaque thumb |
+| default | — | `data-size`, `data-tone` (`data-orientation="vertical"` when upright); track `fill-strong`, tone pill up to the thumb centre, opaque thumb |
 | hover | pointer (fine pointers only) | light liquid glass: the thumb grows to 110%, turns translucent and slightly frosted |
 | invalid | `invalid` or a non-empty `error` | `data-invalid="true"` on the root, `aria-invalid` on the input; the error replaces the hint, danger focus ring; the control shakes once when an error arrives (`data-shake` on the frame) |
 | pressed | dragging | clear glass: the thumb grows to 125%, the rounded end of the fill shows through |
 | focus-visible | keyboard | outer focus ring around the thumb |
 | disabled | `disabled` | `data-disabled="true"` on the root, native `disabled`; muted track and fill, flat thumb, `cursor: not-allowed` |
+| saving | `onCommit` returned a pending promise | `data-pending="true"` on the root, `aria-busy` on the input; the thumb quiets to 0.6 (`fast`, both ways); the slider stays usable — only the latest commit's answer counts |
+| refused | that promise rejected | the value goes back to the last saved one (`onValueChange` when controlled); `data-settling` glides the thumb and the fill there (`base`, emphasized) |
 
-Controlled: `value` + `onValueChange`. Uncontrolled: `defaultValue` (falls back to `min`).
+Controlled: `value` + `onValueChange`. Uncontrolled: `defaultValue` (falls back to `min`). Both are clamped to `min`…`max`. `onCommit` reports the settled value after a drag or a key step.
 
 ## Layout & spacing
 - Fills its container; place it in a grid column to limit the width.
@@ -136,8 +148,10 @@ Controlled: `value` + `onValueChange`. Uncontrolled: `defaultValue` (falls back
 ### ARIA
 - 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"`.
 - `formatValue` sets `aria-valuetext`, so screen readers announce the unit; the visual `<output>` is `aria-hidden`.
 - `aria-describedby` on the input: your ids + the hint or the error; `aria-invalid` when invalid.
+- While a commit is saved the input has `aria-busy`; say why a refused value went back with `error`.
 
 ### Labels
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
@@ -153,9 +167,11 @@ Controlled: `value` + `onValueChange`. Uncontrolled: `defaultValue` (falls back
 | [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`. |
+| [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`. |
 
 ## Mistakes
@@ -163,6 +179,7 @@ Controlled: `value` + `onValueChange`. Uncontrolled: `defaultValue` (falls back
 - A slider for an exact amount → use `Input type="number"`.
 - `tone="danger"` as the only signal of a dangerous value → say it in the label.
 - No `label` and no `aria-label` → the control has no name.
+- 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`)

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

@@ -0,0 +1,39 @@
+/** 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`. */
+import { Slider } from "prime-ui-kit";
+import * as React from "react";
+
+/** The server saving the reminder lead time a beat later: more than ten days is not allowed. */
+function saveLeadTime(days: number) {
+  return new Promise<void>((resolve, reject) => {
+    setTimeout(() => {
+      if (days > 10) reject(new Error("Тариф позволяет напоминать не раньше чем за 10 дней"));
+      else resolve();
+    }, 600);
+  });
+}
+
+export default function SliderAutosaveExample() {
+  const [error, setError] = React.useState<string>();
+
+  return (
+    <Slider
+      label="Напоминать об оплате счёта"
+      min={1}
+      max={14}
+      defaultValue={3}
+      showValue
+      formatValue={(days) => `за ${days} дн.`}
+      hint="Сохраняется само, когда вы отпустите ползунок"
+      error={error}
+      onCommit={async (days) => {
+        setError(undefined);
+        try {
+          await saveLeadTime(days);
+        } catch (reason) {
+          setError(reason instanceof Error ? reason.message : String(reason));
+          throw reason;
+        }
+      }}
+    />
+  );
+}

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

@@ -16,3 +16,9 @@
   gap: var(--prime-space-4);
   width: min(100%, var(--prime-modal-width-s));
 }
+
+/* orientation.tsx: upright sliders side by side, a mixer row. */
+.levels {
+  display: flex;
+  gap: var(--prime-space-8);
+}

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

@@ -0,0 +1,27 @@
+/** Notification levels as a row of upright sliders, minimum at the bottom — `orientation`. */
+import { Slider } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const LEVELS = [
+  { id: "orders", label: "Заказы", value: 80 },
+  { id: "chat", label: "Чат", value: 55 },
+  { id: "system", label: "Система", value: 30 },
+];
+
+export default function SliderOrientationExample() {
+  return (
+    <div className={styles.levels}>
+      {LEVELS.map((level) => (
+        <Slider
+          key={level.id}
+          orientation="vertical"
+          label={level.label}
+          defaultValue={level.value}
+          formatValue={(value) => `${value} %`}
+          showValue
+        />
+      ))}
+    </div>
+  );
+}

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

@@ -3,31 +3,40 @@
 **Category:** selection
 **Kind:** composite
 
-> A filter bar for lists and tables: a filter button and a search with a panel of values, applied filters as removable tags, and a "show / hide" choice for every value.
+> The search and filter bar of lists and tables: the search first and a filter button with a panel of values and ranges, applied filters as removable tags, and a "show / hide" choice for every value.
 
 ## When to use
 - Narrowing a list, table or log by several fields at once (service, method, status), where the user also types free text.
 - Filters where "everything except this" matters as much as "only this": every value can be shown or hidden.
 - Many values per field (dozens of services): the panel collapses them to «Ещё N» and narrows as the user types.
+- Ranges next to the values: an amount from–to (`kind: "range"`), a period (`kind: "date-range"`), each one readable chip.
+- An API that takes one value per field (`multiple: false`), a screen whose text search lives elsewhere (`searchable={false}`), values of different kinds in one field (`group`).
 
 ## When not to use
 - One field with a few options → use [SegmentedControl](../segmented-control/COMPONENT.md), [Select](../select/COMPONENT.md) or [TagSelect](../tag-select/COMPONENT.md) in the toolbar.
-- Only a text search → use [Input](../input/COMPONENT.md) with a search icon.
+- A search outside a table or list page (inside a picker, a settings section, a panel) → [Input](../input/COMPONENT.md) with a search icon. Over a table or list page the search is SmartFilter even with no fields yet (`fields={[]}`): it grows into filters without a rebuild.
 - Choosing values for a form field → use [TagSelect](../tag-select/COMPONENT.md).
-- Filtering by a range (dates, price) → use [Datepicker](../datepicker/COMPONENT.md) or [Slider](../slider/COMPONENT.md); SmartFilter works on discrete values.
+- One period that drives a whole dashboard → [Datepicker](../datepicker/COMPONENT.md) in the page toolbar; SmartFilter ranges filter rows of a list.
 
 ## Import
 ```tsx
-import { SmartFilter, matchesSmartFilter, resolveSmartFilterValues } from "prime-ui-kit";
+import {
+  SmartFilter,
+  isSmartFilterRange,
+  matchesSmartFilter,
+  resolveSmartFilterValues,
+} from "prime-ui-kit";
 ```
 
 ## Anatomy
 ```
 SmartFilter.Root                  state + context (flex column)
-├─ SmartFilter.Toolbar            [filter Button (count Badge)] [search Input] — the anchor of the panel
+├─ SmartFilter.Toolbar            [search Input (searchable)] [filter Button (count Badge)] — the anchor of the panel
 │  └─ panel                       flush Popover as wide as the toolbar; sections split by Dividers
 │     ├─ query row                ghost Button «Искать «text»» + Kbd ↵, while typing
 │     ├─ field rows               field label · value Badges with a «−» Badge.Action · «Ещё N» Badge
+│     │                           (groups: a caption over each group's values, role="group")
+│     ├─ range rows               field label · Input «от» – Input «до» · or a Datepicker range field
 │     ├─ no matches               compact EmptyPage naming the fields with nothing found
 │     └─ footer                   hint · count · Reset Button
 └─ SmartFilter.Chips              applied filters as removable Badges · add / clear all Buttons
@@ -44,7 +53,7 @@ The toolbar and the chips are separate parts so a page can put them in different
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `fields` | `readonly SmartFilterField[]` | — (required) | Fields of this screen, in display order; empty — only the search. Pass a stable reference. |
-| `value` | `SmartFilterValue` | — | Selection per field key, controlled: `{ include, exclude }` per field. |
+| `value` | `SmartFilterValue` | — | Value per field key, controlled: `{ include, exclude }` for an options field, `{ from, to }` (numbers or dates, `null` — open) for a range field. |
 | `defaultValue` | `SmartFilterValue` | `{}` | Initial selection, uncontrolled. |
 | `onValueChange` | `(value: SmartFilterValue) => void` | — | The whole next value; keys of fields this root does not show are kept. |
 | `search` | `string` | — | Search text, controlled. |
@@ -57,10 +66,11 @@ The toolbar and the chips are separate parts so a page can put them in different
 | `children` | `ReactNode` | — (required) | `SmartFilter.Toolbar` and `SmartFilter.Chips`, anywhere inside. |
 
 ### SmartFilter.Toolbar
-`ref` → `HTMLDivElement`. A `<div>`: the filter Button (a count Badge while filters apply) and a search Input; the anchor of the panel, a flush Popover.
+`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.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
+| `searchable` | `boolean` | `true` | The search input. `false` — the filter button alone; the panel opens at its own width (24rem at most) and lists every field. |
 | `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "children">` | — | `className` and the other attributes of the toolbar. |
 
 ### SmartFilter.Chips
@@ -77,11 +87,14 @@ One entry of `fields`: data, not a part. Selected values missing from `options`
 |---|---|---|---|
 | `key` | `string` | — (required) | Key of the field in the value. |
 | `label` | `string` | — (required) | Field name in the panel and the chips. |
-| `options` | `{ value: string; label: string; icon?: ReactNode }[]` | — (required) | Values; `icon` is a decorative kit Icon before the label. |
-| `finite` | `boolean` | `true` | A fixed set: hiding every value is refused. `false` for an open set (services, users). |
+| `kind` | `"options" \| "range" \| "date-range"` | `"options"` | `options` — values to show or hide; `range` — a number range in two Inputs; `date-range` — a period in the kit Datepicker. A range is one filter and one chip. |
+| `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 ₽»). |
 
-### matchesSmartFilter · resolveSmartFilterValues
-Helpers. `matchesSmartFilter(selection, value)` checks one value on the client (`include` empty = any, `exclude` rejects). `resolveSmartFilterValues(selection, all)` turns a fixed field into the list to ask a server for: «hide» becomes «all except», `[]` — no filter.
+### 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.
 
 ## Variants
 
@@ -104,6 +117,25 @@ same height and type.
 | `true` | the «−» of the last shown value is disabled | fixed sets (method, status) | yes |
 | `false` | every value can be hidden | open sets (services, users) | |
 
+### field `kind`
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `options` | value Badges to show or hide | discrete values | yes |
+| `range` | two Inputs «от» – «до»; chip «Сумма: 1 000–5 000» (`от 1 000`, `до 5 000` with one bound) | amounts, counts | |
+| `date-range` | the kit Datepicker range field; chip in the Datepicker's words («Период: 1–15 мар») | a period | |
+
+### field `multiple`
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `true` | many values, each shown or hidden | most fields | yes |
+| `false` | one value, no «−»: a press picks it, a second press clears it | the API takes one value per field | |
+
+### Toolbar `searchable`
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `true` | search + filter button, the panel as wide as the toolbar | lists with free text | yes |
+| `false` | the filter button alone; the panel at its own width (≤ 24rem) | the search lives elsewhere or there is none | |
+
 ## States
 | State | Driven by | DOM |
 |---|---|---|
@@ -113,13 +145,18 @@ same height and type.
 | 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 |
+| range set | a bound typed (`range`: two Inputs «от» – «до») or a period picked (`date-range`: Datepicker `mode="range"`) | `{ from, to }` in the value; counts as one filter, one blue chip («Сумма: 1 000–5 000», «Период: 1–15 мар»); removing the chip clears both bounds and the inputs |
+| range inverted | `from` above `to` | both bound inputs `aria-invalid` with the danger ring; nothing matches |
+| single value | `multiple: false` | at most one value `aria-pressed`; no «−» |
 | 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 filter button keeps its width, the search grows from 9rem (`--prime-space-24` × 1.5). When less than 9rem is left beside the button, the search moves under it at full width; every row stays one control high.
+- 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.
 - 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.
+- 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.
 
 ## Accessibility
@@ -136,6 +173,8 @@ same height and type.
 - 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"`.
+- Range bounds are inputs named by `labels.fromLabel` / `labels.toLabel` («Сумма, от»); an inverted range marks both `aria-invalid`. A date range is the Datepicker field named by the field label.
+- An option group is a `role="group"` named by its `group`.
 - Every filter tag has a remove button named by `labels.remove`.
 
 ### Labels
@@ -161,6 +200,12 @@ same height and type.
 | `chipInclude` | `"{field}: {value}"` | Text of a «show» tag. |
 | `chipExclude` | `"{field}: не {value}"` | Text of a «hide» tag. |
 | `remove` | `"Убрать фильтр «{value}»"` | Name of a tag's remove button. |
+| `from` | `"от"` | Placeholder of a range's lower bound. |
+| `to` | `"до"` | Placeholder of a range's upper bound. |
+| `fromLabel` | `"{field}, от"` | Accessible name of the lower bound input. |
+| `toLabel` | `"{field}, до"` | Accessible name of the upper bound input. |
+| `rangeFrom` | `"от {value}"` | Chip value of a range with only the lower bound. |
+| `rangeTo` | `"до {value}"` | Chip value of a range with only the upper bound. |
 
 ## Examples
 | Example | Shows |
@@ -168,17 +213,23 @@ 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`. |
+| [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`. |
 | [narrow.tsx](examples/narrow.tsx) | A 320 px column: the search shrinks next to the filter button and the tags wrap under them — `size`. |
 
 ## Mistakes
 - Creating `fields` inline on every render → pass a stable array (a module constant or `useMemo`).
 - A fixed field marked `finite: false` → the user can hide every value and get an empty list.
-- Filtering the list with `includes` → use `matchesSmartFilter` (empty `include` is "any", `exclude` rejects).
-- Sending `include` to a server for a hidden value of a fixed field → use `resolveSmartFilterValues`.
+- Filtering the list with `includes` → use `matchesSmartFilter` (empty `include` is "any", `exclude` rejects; range bounds are inclusive, dates by whole days; an item with no value passes only an empty filter).
+- Sending `include` to a server for a hidden value of a fixed field → use `resolveSmartFilterValues` («hide» becomes «all except», `[]` means no filter).
 - Putting `Chips` outside `SmartFilter.Root` → every part needs the root.
 - A second row of filter buttons next to the toolbar → fields belong in `fields`.
+- An amount or a period in its own Popover beside the toolbar → a `range` / `date-range` field; it gets a chip and the count.
+- One field split in two because its values are of different kinds → one field with `group` on the options.
+- 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), [Popover](../popover/COMPONENT.md), [Divider](../divider/COMPONENT.md), [Kbd](../kbd/COMPONENT.md), [EmptyPage](../empty-page/COMPONENT.md), [Typography](../typography/COMPONENT.md)
-- **See also:** [TagSelect](../tag-select/COMPONENT.md), [DataTable](../data-table/COMPONENT.md)
+- **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`)
+- **See also:** [PageToolbar](../page-toolbar/COMPONENT.md), [TagSelect](../tag-select/COMPONENT.md), [DataTable](../data-table/COMPONENT.md)

package/src/components/smart-filter/examples/option-groups.tsx

@@ -0,0 +1,40 @@
+/** Values of different kinds in one field: owner types and people under their own headings — `options`, `group`. */
+import { SmartFilter, type SmartFilterField } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const FIELDS: SmartFilterField[] = [
+  {
+    key: "owner",
+    label: "Ответственный",
+    finite: false,
+    options: [
+      { value: "me", label: "Я", group: "Кто" },
+      { value: "my-team", label: "Моя команда", group: "Кто" },
+      { value: "nobody", label: "Не назначен", group: "Кто" },
+      { value: "u-anna", label: "Анна Ким", group: "Сотрудники" },
+      { value: "u-oleg", label: "Олег Петров", group: "Сотрудники" },
+      { value: "u-irina", label: "Ирина Соколова", group: "Сотрудники" },
+    ],
+  },
+  {
+    key: "status",
+    label: "Статус",
+    options: [
+      { value: "open", label: "Открыта" },
+      { value: "waiting", label: "Ждёт ответа" },
+      { value: "closed", label: "Закрыта" },
+    ],
+  },
+];
+
+export default function SmartFilterOptionGroupsExample() {
+  return (
+    <div className={styles.stack}>
+      <SmartFilter.Root fields={FIELDS}>
+        <SmartFilter.Toolbar />
+        <SmartFilter.Chips />
+      </SmartFilter.Root>
+    </div>
+  );
+}

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

@@ -0,0 +1,89 @@
+/** Deals narrowed by an amount from–to and a period from the calendar; each range is one readable chip — `kind`, `formatValue`, `matchesSmartFilter`. */
+import {
+  matchesSmartFilter,
+  SmartFilter,
+  type SmartFilterField,
+  type SmartFilterValue,
+  Typography,
+} from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+const formatRubles = (value: number) => `${value.toLocaleString("ru-RU")} ₽`;
+
+const FIELDS: SmartFilterField[] = [
+  { key: "amount", label: "Сумма", kind: "range", formatValue: formatRubles },
+  { key: "closed", label: "Период", kind: "date-range" },
+  {
+    key: "stage",
+    label: "Этап",
+    options: [
+      { value: "proposal", label: "Предложение" },
+      { value: "contract", label: "Договор" },
+      { value: "won", label: "Выиграна" },
+    ],
+  },
+];
+
+const DEALS = [
+  {
+    id: "d-118",
+    client: "ООО «Гранит»",
+    amount: 94_750,
+    closed: new Date(2026, 2, 3),
+    stage: "won",
+  },
+  {
+    id: "d-121",
+    client: "АО «Альфа Медиа»",
+    amount: 380_000,
+    closed: new Date(2026, 2, 12),
+    stage: "contract",
+  },
+  {
+    id: "d-124",
+    client: "ИП Орлов Д. С.",
+    amount: 18_000,
+    closed: new Date(2026, 2, 20),
+    stage: "proposal",
+  },
+  {
+    id: "d-130",
+    client: "ООО «Север»",
+    amount: 1_250_000,
+    closed: new Date(2026, 3, 2),
+    stage: "won",
+  },
+];
+
+const INITIAL: SmartFilterValue = { amount: { from: 50_000, to: 500_000 } };
+
+export default function SmartFilterRangesExample() {
+  const [value, setValue] = React.useState<SmartFilterValue>(INITIAL);
+  const rows = DEALS.filter(
+    (deal) =>
+      matchesSmartFilter(value.amount, deal.amount) &&
+      matchesSmartFilter(value.closed, deal.closed) &&
+      matchesSmartFilter(value.stage, deal.stage),
+  );
+
+  return (
+    <div className={styles.stack}>
+      <SmartFilter.Root fields={FIELDS} value={value} onValueChange={setValue}>
+        <SmartFilter.Toolbar />
+        <SmartFilter.Chips />
+      </SmartFilter.Root>
+      {rows.map((deal) => (
+        <div key={deal.id} className={styles.request}>
+          <Typography as="span" variant="body-m" truncate className={styles.route}>
+            {deal.client}
+          </Typography>
+          <Typography as="span" variant="body-m" tone="secondary">
+            {formatRubles(deal.amount)}
+          </Typography>
+        </div>
+      ))}
+    </div>
+  );
+}

package/src/components/smart-filter/examples/single-value.tsx

@@ -0,0 +1,41 @@
+/** 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`. */
+import { SmartFilter, type SmartFilterField } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const FIELDS: SmartFilterField[] = [
+  {
+    key: "pipeline",
+    label: "Воронка",
+    multiple: false,
+    options: [
+      { value: "b2b", label: "Корпоративные продажи" },
+      { value: "retail", label: "Розница" },
+      { value: "partners", label: "Партнёры" },
+    ],
+  },
+  {
+    key: "period",
+    label: "Срок",
+    multiple: false,
+    options: [
+      { value: "overdue", label: "Просрочены" },
+      { value: "today", label: "Сегодня" },
+      { value: "week", label: "На этой неделе" },
+    ],
+  },
+];
+
+export default function SmartFilterSingleValueExample() {
+  return (
+    <div className={styles.stack}>
+      <SmartFilter.Root
+        fields={FIELDS}
+        defaultValue={{ pipeline: { include: ["b2b"], exclude: [] } }}
+      >
+        <SmartFilter.Toolbar searchable={false} />
+        <SmartFilter.Chips />
+      </SmartFilter.Root>
+    </div>
+  );
+}