prime-ui-kit 0.9.3 → 0.11.0

package/dist/skill/reference/components/slider/examples/value-format.tsx

@@ -0,0 +1,32 @@
+/** Units in the shown value that are also read by screen readers — `formatValue`, `showValue`. */
+import { Slider } from "prime-ui-kit";
+
+const RUB = new Intl.NumberFormat("ru-RU", {
+  style: "currency",
+  currency: "RUB",
+  maximumFractionDigits: 0,
+});
+
+export default function SliderValueFormatExample() {
+  return (
+    <>
+      <Slider
+        label="Температура на складе"
+        min={2}
+        max={25}
+        defaultValue={8}
+        showValue
+        formatValue={(value) => `${value} °C`}
+      />
+      <Slider
+        label="Бюджет кампании в месяц"
+        min={0}
+        max={200000}
+        step={5000}
+        defaultValue={45000}
+        showValue
+        formatValue={(value) => RUB.format(value)}
+      />
+    </>
+  );
+}

package/dist/skill/reference/components/slider/examples/variants.tsx

@@ -0,0 +1,23 @@
+/** Every fill color; accent by default, semantic tones when the value carries meaning — `tone`. */
+import { Slider } from "prime-ui-kit";
+
+const TONE_ROWS = [
+  ["accent", "neutral", "success"],
+  ["warning", "danger", "info"],
+] as const;
+
+export default function SliderVariantsExample() {
+  return (
+    <>
+      {TONE_ROWS.map((row) => (
+        <div key={row[0]}>
+          {row.map((tone) => (
+            <div key={tone}>
+              <Slider tone={tone} label={tone} showValue defaultValue={60} />
+            </div>
+          ))}
+        </div>
+      ))}
+    </>
+  );
+}

package/dist/skill/reference/components/smart-filter/COMPONENT.md

@@ -0,0 +1,235 @@
+# SmartFilter
+
+**Category:** selection
+**Kind:** composite
+
+> 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.
+- 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).
+- 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,
+  isSmartFilterRange,
+  matchesSmartFilter,
+  resolveSmartFilterValues,
+} from "prime-ui-kit";
+```
+
+## Anatomy
+```
+SmartFilter.Root                  state + context (flex column)
+├─ 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
+```
+The toolbar and the chips are separate parts so a page can put them in different places; both only need to be inside `Root`.
+
+## API
+
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+### SmartFilter.Root
+`ref` → `HTMLDivElement`. A `<div>` (flex column) with the state and the context; sets `data-size`.
+
+| 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` | — | 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. |
+| `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. |
+| `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. |
+
+### 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.
+
+| 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
+`ref` → `HTMLDivElement`. A `<div>` of applied filters as removable Badges with «Добавить фильтр» and «Сбросить все»; renders nothing without filters.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "children">` | — | `className` and the other attributes of the chips row. |
+
+### 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 |
+|---|---|---|---|
+| `key` | `string` | — (required) | Key of the field in the value. |
+| `label` | `string` | — (required) | Field name in the panel and the chips. |
+| `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 · 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
+
+### size
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `xs` | toolbar 28; value and filter tags 20 (tags never go below `s`) | dense table toolbars | |
+| `s` | toolbar 32; tags 20 | compact toolbars | |
+| `m` | toolbar 36; tags 24 | most pages | yes |
+| `l` | toolbar 40; tags 28 | roomier pages | |
+| `xl` | toolbar 48; tags 32 | hero search | |
+
+In the tag row «Добавить фильтр» is a pressable gray Badge of the tag tier and «Сбросить все» a
+neutral LinkButton with the tags' text size, at the end of the row: every element of the row has the
+same height and type.
+
+### field `finite`
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `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 |
+|---|---|---|
+| 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 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 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
+
+### Keyboard
+| Key | Action |
+|---|---|
+| `Tab` | Moves through the panel values and their «−» (shown on focus). |
+| `Enter` · `Space` | Shows only this value; pressing again clears it. |
+| `Shift + Enter` | Hides the value. |
+| `Enter` · `Escape` | In the search, close the panel. |
+
+### ARIA
+- 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
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+| Key | Default | Used for |
+|---|---|---|
+| `filter` | `"Фильтр"` | Filter button and panel name. |
+| `searchPlaceholder` | `"Поиск"` | Placeholder and name of the search. |
+| `clearSearch` | `"Очистить поиск"` | Name of the search clear button. |
+| `searchText` | `"Искать «{query}»"` | The text search row while typing. |
+| `noMatches` | `"{fields} — нет совпадений"` | Fields with nothing found while typing (compact EmptyPage). |
+| `hint` | `"Нажмите значение, чтобы показать только его; «−» справа — скрыть"` | Panel footer hint. |
+| `count` | `"Фильтров: {count}"` | Panel footer counter. |
+| `reset` | `"Сбросить"` | Panel footer reset. |
+| `more` | `"Ещё {count}"` | Collapsed values of a field. |
+| `add` | `"Добавить фильтр"` | Chips row: opens the panel. |
+| `clearAll` | `"Сбросить все"` | Chips row: clears every field. |
+| `showValue` | `"Показать только {value}"` | Title of a value. |
+| `hideValue` | `"Скрыть {value}"` | Name of the «−» of a value. |
+| `unhideValue` | `"Не скрывать {value}"` | Name of the «−» of a hidden value. |
+| `not` | `"НЕ"` | Prefix of a hidden value. |
+| `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 |
+|---|---|
+| [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; 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), [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/dist/skill/reference/components/smart-filter/examples/controlled.tsx

@@ -0,0 +1,48 @@
+/** A saved view sets the value from outside; the selection is read back as the list to ask the server for — `value`, `onValueChange`, `resolveSmartFilterValues`. */
+import {
+  Button,
+  resolveSmartFilterValues,
+  SmartFilter,
+  type SmartFilterField,
+  type SmartFilterValue,
+  Typography,
+} from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+const METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE"];
+
+const FIELDS: SmartFilterField[] = [
+  { key: "method", label: "Метод", options: METHODS.map((v) => ({ value: v, label: v })) },
+];
+
+const ONLY_PUT: SmartFilterValue = { method: { include: ["PUT"], exclude: [] } };
+const NO_READS: SmartFilterValue = { method: { include: [], exclude: ["GET", "POST"] } };
+
+export default function SmartFilterControlledExample() {
+  const [value, setValue] = React.useState<SmartFilterValue>({});
+
+  return (
+    <div className={styles.stack}>
+      <SmartFilter.Root fields={FIELDS} value={value} onValueChange={setValue}>
+        <SmartFilter.Toolbar />
+        <SmartFilter.Chips />
+      </SmartFilter.Root>
+      <div className={styles.views}>
+        <Button.Root variant="soft" tone="neutral" size="s" onClick={() => setValue(ONLY_PUT)}>
+          Только PUT
+        </Button.Root>
+        <Button.Root variant="soft" tone="neutral" size="s" onClick={() => setValue(NO_READS)}>
+          Без GET и POST
+        </Button.Root>
+        <Button.Root variant="ghost" tone="neutral" size="s" onClick={() => setValue({})}>
+          Сбросить
+        </Button.Root>
+      </div>
+      <Typography as="span" variant="code" tone="secondary">
+        {`method: ${JSON.stringify(resolveSmartFilterValues(value.method, METHODS))}`}
+      </Typography>
+    </div>
+  );
+}

package/dist/skill/reference/components/smart-filter/examples/examples.module.css

@@ -0,0 +1,56 @@
+/* Layout of the SmartFilter scenarios: semantic tokens only. */
+
+.stack {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-space-4);
+  width: 100%;
+  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;
+  align-items: center;
+  gap: var(--prime-space-3);
+  width: 100%;
+  min-width: 0;
+}
+
+.route {
+  flex: 1;
+  min-width: 0;
+}
+
+.views {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--prime-space-2);
+}
+
+/* 320 px: the smallest supported viewport. */
+.narrow {
+  width: min(100%, calc(var(--prime-space-20) * 4));
+  min-width: 0;
+}

package/dist/skill/reference/components/smart-filter/examples/many-values.tsx

@@ -0,0 +1,53 @@
+/** 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`. */
+import { Icon, SmartFilter, type SmartFilterField } from "prime-ui-kit";
+
+const SERVICES = [
+  "access-policy",
+  "billing",
+  "catalog",
+  "checkout",
+  "conformance",
+  "delivery",
+  "events",
+  "go-events",
+  "http-gateway",
+  "inventory",
+  "loyalty",
+  "notifications",
+  "orders",
+  "payments",
+  "pricing",
+  "reports",
+  "rpc-gateway",
+  "search",
+  "users",
+  "workflow",
+];
+
+const DEGRADED = new Set(["checkout", "events", "pricing"]);
+
+const FIELDS: SmartFilterField[] = [
+  {
+    key: "service",
+    label: "Сервис",
+    finite: false,
+    options: SERVICES.map((name) => ({
+      value: name,
+      label: name,
+      icon: DEGRADED.has(name) ? <Icon name="status.warning" tone="warning" /> : undefined,
+    })),
+  },
+];
+
+export default function SmartFilterManyValuesExample() {
+  return (
+    <SmartFilter.Root
+      fields={FIELDS}
+      collapsedLimit={8}
+      defaultValue={{ service: { include: [], exclude: ["events"] } }}
+    >
+      <SmartFilter.Toolbar />
+      <SmartFilter.Chips />
+    </SmartFilter.Root>
+  );
+}

package/dist/skill/reference/components/smart-filter/examples/narrow.tsx

@@ -0,0 +1,38 @@
+/** A 320 px column: the search shrinks next to the filter button and the tags wrap under them — `size`. */
+import { SmartFilter, type SmartFilterField } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const FIELDS: SmartFilterField[] = [
+  {
+    key: "status",
+    label: "Статус",
+    options: [
+      { value: "new", label: "Новые" },
+      { value: "paid", label: "Оплаченные" },
+      { value: "refund", label: "Возвраты" },
+    ],
+  },
+  {
+    key: "city",
+    label: "Город",
+    finite: false,
+    options: ["Москва", "Казань", "Самара", "Пермь"].map((v) => ({ value: v, label: v })),
+  },
+];
+
+const APPLIED = {
+  status: { include: ["paid"], exclude: [] },
+  city: { include: [], exclude: ["Самара"] },
+};
+
+export default function SmartFilterNarrowExample() {
+  return (
+    <div className={styles.narrow}>
+      <SmartFilter.Root fields={FIELDS} size="s" defaultValue={APPLIED}>
+        <SmartFilter.Toolbar />
+        <SmartFilter.Chips />
+      </SmartFilter.Root>
+    </div>
+  );
+}

package/dist/skill/reference/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/dist/skill/reference/components/smart-filter/examples/overview.tsx

@@ -0,0 +1,109 @@
+/** 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`. */
+import {
+  Badge,
+  Card,
+  matchesSmartFilter,
+  SmartFilter,
+  type SmartFilterField,
+  type SmartFilterValue,
+  Typography,
+} from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+const METHOD_COLOR = {
+  GET: "green",
+  POST: "blue",
+  PUT: "orange",
+  PATCH: "purple",
+  DELETE: "red",
+} as const;
+
+const REQUESTS = [
+  { id: 1, route: "/orders", method: "GET", service: "orders", state: "active" },
+  { id: 2, route: "/orders", method: "POST", service: "orders", state: "active" },
+  { id: 3, route: "/orders/:id", method: "PUT", service: "orders", state: "inactive" },
+  { id: 4, route: "/catalog/items", method: "GET", service: "catalog", state: "active" },
+  { id: 5, route: "/catalog/items/:id", method: "PATCH", service: "catalog", state: "active" },
+  { id: 6, route: "/billing/invoices", method: "GET", service: "billing", state: "active" },
+  {
+    id: 7,
+    route: "/billing/invoices/:id",
+    method: "DELETE",
+    service: "billing",
+    state: "inactive",
+  },
+  { id: 8, route: "/events/subscribe", method: "POST", service: "events", state: "active" },
+] as const;
+
+const asOptions = (values: readonly string[]) => values.map((v) => ({ value: v, label: v }));
+
+const FIELDS: SmartFilterField[] = [
+  {
+    key: "service",
+    label: "Сервис",
+    finite: false,
+    options: asOptions(["billing", "catalog", "events", "orders"]),
+  },
+  { key: "method", label: "Метод", options: asOptions(["GET", "POST", "PUT", "PATCH", "DELETE"]) },
+  {
+    key: "state",
+    label: "Состояние",
+    options: [
+      { value: "active", label: "Активные" },
+      { value: "inactive", label: "Неактивные" },
+    ],
+  },
+];
+
+export default function SmartFilterOverviewExample() {
+  const [value, setValue] = React.useState<SmartFilterValue>({});
+  const [search, setSearch] = React.useState("");
+
+  const found = REQUESTS.filter(
+    (request) =>
+      matchesSmartFilter(value.service, request.service) &&
+      matchesSmartFilter(value.method, request.method) &&
+      matchesSmartFilter(value.state, request.state) &&
+      request.route.toLowerCase().includes(search.trim().toLowerCase()),
+  );
+
+  return (
+    <div className={styles.stack}>
+      <SmartFilter.Root
+        fields={FIELDS}
+        value={value}
+        onValueChange={setValue}
+        search={search}
+        onSearchChange={setSearch}
+      >
+        <SmartFilter.Toolbar />
+        <SmartFilter.Chips />
+      </SmartFilter.Root>
+      <Card.Root variant="list">
+        <Card.Header>
+          <Card.Title>Запросы</Card.Title>
+          <Typography as="span" variant="caption" tone="muted">
+            {found.length} из {REQUESTS.length}
+          </Typography>
+        </Card.Header>
+        <Card.List>
+          {found.map((request) => (
+            <Card.ListItem key={request.id}>
+              <span className={styles.request}>
+                <Badge.Root color={METHOD_COLOR[request.method]}>{request.method}</Badge.Root>
+                <Typography as="span" variant="code" className={styles.route} truncate>
+                  {request.route}
+                </Typography>
+                <Typography as="span" variant="caption" tone="muted">
+                  {request.service}
+                </Typography>
+              </span>
+            </Card.ListItem>
+          ))}
+        </Card.List>
+      </Card.Root>
+    </div>
+  );
+}