prime-ui-kit 0.9.3 → 0.11.0

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>
+  );
+}

package/src/components/sparkline/COMPONENT.md

@@ -3,16 +3,18 @@
 **Category:** data-display
 **Kind:** primitive
 
-> A small line chart with its headline — the latest value, its change against the point before and its date — where any point can be scrubbed.
+> A small line or bar chart with its headline — the value at rest, its change against the point before and its date — where any point can be scrubbed.
 
 ## When to use
 - A metric card on a dashboard: revenue, orders, sign-ups over the last days or weeks.
 - A trend next to a number where the shape matters more than exact axes.
+- Values with a sign by period — profit, net new customers (`variant="bars"`: up when positive, down when negative), with the current period highlighted (`highlight`).
 - A detail page header that shows how a value moved.
 
 ## When not to use
-- Exact values on axes, several series, or a legend → a full chart library; Sparkline has no axes.
+- Exact values on axes, several series, or a legend → a full chart library on the kit's chart palette (`chartColors`); Sparkline has no axes.
 - Progress toward a goal → [ProgressBar](../progress-bar/COMPONENT.md) or [ProgressCircle](../progress-circle/COMPONENT.md).
+- Shares of categories or a ranking → [ProgressBar](../progress-bar/COMPONENT.md) with `segments` or `layout="rows"`.
 - A list of values to compare → [DataTable](../data-table/COMPONENT.md).
 
 ## Import
@@ -22,11 +24,13 @@ import { Sparkline, type SparklinePoint } from "prime-ui-kit";
 
 ## Anatomy
 ```
-Sparkline              <div>; the headline and the chart
+Sparkline              <div>; the headline and the chart; aria-busy while loading
 ├─ head                title (label) · date of the shown point
 ├─ value row           value (rolling digits when settled) · change Badge with the trend arrow
-└─ plot                role="slider" over the svg line and area
-   └─ cursor           guide line and dot of the shown point (aria-hidden)
+└─ plot                role="slider" over the chart
+   ├─ line:            svg line and area + cursor (guide line and dot, aria-hidden)
+   └─ bars:            zero line (chart axis) + a slot per point with its bar (aria-hidden)
+loading:               Skeletons of the date, the value line and the plot
 ```
 
 ## API
@@ -34,46 +38,66 @@ Sparkline              <div>; the headline and the chart
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
 
 ### Sparkline
-`ref` → `HTMLDivElement` (the root). A headline (title · date, value · change) over a line chart; the chart is a `role="slider"` that picks a point.
+`ref` → `HTMLDivElement` (the root). A headline (title · date, value · change) over a line or bar chart; the chart is a `role="slider"` that picks a point. The change hides when a percentage means nothing (the previous value is 0 or the sign flips).
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `data` | `SparklinePoint[]` | — (required) | Points oldest first, `{ label, value }`; `label` names the point («8 окт»). Two or more draw a line. A new array cross-fades the line in. |
 | `label` | `string` | — (required) | Visible title above the value and the accessible name of the chart. |
+| `variant` | `"line" \| "bars"` | `"line"` | `line` — a line over a soft area; `bars` — a bar per point standing on a zero line: up when positive, down (danger) when negative, the value end rounded. |
+| `highlight` | `number` | `the latest point` | Index of the point at rest (the current month): the headline shows it when nobody scrubs and leaving the chart returns to it; `bars` draw the other bars quieter. |
+| `loading` | `boolean` | `false` | The series is on its way: Skeletons of the date, the value and the plot that cross-fade into the data; the title stays, the root is `aria-busy` and the chart is not focusable yet. |
 | `formatValue` | `(value: number) => string` | `Russian digit groups` | Display of a value in the headline and the spoken point («312 400 ₽»). |
 | `labels` | `Partial<SparklineLabels>` | — | Built-in strings, see Labels. |
 | `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "children">` | — | `className`, `data-*` and the other div attributes on the root. |
 
 ## Variants
-No variants: one accent line on the surface it sits on. Put it in a `Card` for a dashboard tile.
+
+### variant
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `line` | an accent line over a soft area, a dot on the shown point | a continuous trend (daily revenue) | yes |
+| `bars` | a bar per point from a zero line (`--prime-color-chart-axis`): accent up, danger down, value end rounded | values by period, especially with a sign (monthly profit) | |
+
+### Flags
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `highlight` | the headline rests on that point; in `bars` the other bars are quieter | the current period is not the last point (a year with empty months ahead) | the latest point |
+| `loading` | Skeletons of the date, the value and the plot | the series is on its way | `false` |
+
+Put it in a `Card` for a dashboard tile.
 
 ## States
 | State | Driven by | DOM |
 |---|---|---|
-| at rest | — | the latest point; the value rolls its digits when `data` changes |
-| scrubbing | pointer or touch over the plot | `data-scrubbing` on the root; the cursor and the headline follow the pointer with no easing (direct manipulation), digits change in place |
-| keyboard | arrows, Home, End on the focused plot | `aria-valuenow` / `aria-valuetext`; the cursor glides to the point (`base` · emphasized) |
-| settle | pointer leaves, touch ends, focus leaves | the cursor glides back to the latest point |
-| new series | a new `data` array | the line cross-fades in (swap motion); the trend arrow turns half a turn between up and down |
+| at rest | — | the latest point or `highlight`; the value rolls its digits when `data` changes |
+| scrubbing | pointer, touch or the arrow keys | `data-scrubbing` on the root; the cursor (or the bar under the pointer) and the headline follow with no easing (direct manipulation), digits change in place |
+| keyboard | arrows, Home, End on the focused plot | `aria-valuenow` / `aria-valuetext`, `data-scrubbing`; the cursor moves to the point at once (keyboard steps are high-frequency); in `bars` the current bar keeps its fill, the others go quiet (`fast` opacity) |
+| settle | pointer leaves, touch ends, focus leaves | back to the point at rest |
+| change hidden | the first point, the previous value is 0, or the sign flips | no change Badge: a percentage would mean nothing |
+| new series | a new `data` array | the chart cross-fades in (swap motion); the trend arrow turns half a turn between up and down |
+| loading | `loading` | `aria-busy` on the root; Skeletons in place of the date, the value and the plot; no slider until the data comes; the data cross-fades in |
 
 ## Layout & spacing
 - Takes the width of its container; the plot is 80 px high and inset by the dot radius so the cursor is never clipped.
+- Bars share the width equally, 4 px apart; the zero line sits where 0 falls on the scale (the bottom when every value is positive).
 - In a dashboard, wrap it in `Card.Root` + `Card.Body`; several cards go in a grid.
-- Below 320 px the value row wraps the change badge under the value.
+- When the value row does not fit (a narrow card), the change badge wraps under the value.
 
 ## Accessibility
 
 ### Keyboard
 | Key | Action |
 |---|---|
-| `←` · `→` | Previous or next point. |
+| `←` · `→` · `↓` · `↑` | Previous or next point: `←` / `↓` back, `→` / `↑` forward, as on a slider. |
 | `Home` · `End` | First or last point. |
-| `Tab` | Focuses the chart; leaving focus returns to the latest point. |
+| `Tab` | Focuses the chart; leaving focus returns to the point at rest (the latest or `highlight`). |
 
 ### ARIA
-- The plot is `role="slider"` named by `label`; `aria-valuetext` speaks the point («8 окт: 312 400 ₽», `labels.point`).
-- The headline with the latest value and change reads as plain text.
-- The change carries a sign and an arrow, never color alone.
+- The plot is `role="slider"` named by `label`; `aria-valuetext` speaks the point («8 окт: 312 400 ₽», `labels.point`). The headline is the tooltip of the chart: the value of the point under the pointer or the arrows, in text.
+- The headline with the value and change reads as plain text.
+- The change carries a sign and an arrow, never color alone; a negative bar goes down, not only red.
+- While `loading` the root is `aria-busy` and the chart is not in the tab order yet.
 
 ### Labels
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
@@ -86,13 +110,18 @@ No variants: one accent line on the surface it sits on. Put it in a `Card` for a
 | Example | Shows |
 |---|---|
 | [overview.tsx](examples/overview.tsx) | Revenue for 30 days in a dashboard card: drag across the chart, the headline follows and the trend arrow turns — `data`, `label`, `formatValue`. |
+| [variants.tsx](examples/variants.tsx) | The same week as a line and as bars from zero — `variant`. |
+| [states.tsx](examples/states.tsx) | While the series loads the date, the value and the plot are Skeletons in their own places; the title stays — `loading`. |
+| [signed-bars.tsx](examples/signed-bars.tsx) | Monthly profit with a sign: losses go below the zero line, the current month rests highlighted and any bar shows its value under the pointer or the arrows — `variant`, `highlight`. |
 | [period.tsx](examples/period.tsx) | Another period swaps the series: the line cross-fades in and the headline digits roll to the new total — `data`. |
 
 ## Mistakes
 - A new array on every render (`data={rows.map(...)}` inline) → the line cross-fades on every render; memoize the series.
 - Formatting inside `label` of a point («312 400 ₽») → the point label is its name («8 окт»); format values with `formatValue`.
 - A Sparkline without a container width (inside an inline flex row) → give it a width or put it in a `Card`.
+- A separate tooltip over the bars → the headline already shows the scrubbed point; a floating tooltip would cover the next bar.
+- A grey box while the series loads → `loading`.
 
 ## Related
-- **Built from:** [Badge](../badge/COMPONENT.md)
+- **Built from:** [Badge](../badge/COMPONENT.md) (change), [Skeleton](../skeleton/COMPONENT.md) (loading), `Icon` (trend arrow)
 - **See also:** [Card](../card/COMPONENT.md), [ProgressBar](../progress-bar/COMPONENT.md), [SegmentedControl](../segmented-control/COMPONENT.md)

package/src/components/sparkline/examples/signed-bars.tsx

@@ -0,0 +1,41 @@
+/** Monthly profit with a sign: losses go below the zero line, the current month rests highlighted and any bar shows its value under the pointer or the arrows — `variant`, `highlight`. */
+import { Card, Sparkline, type SparklinePoint } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const PROFIT: SparklinePoint[] = [
+  { label: "янв", value: 420_000 },
+  { label: "фев", value: 310_000 },
+  { label: "мар", value: -120_000 },
+  { label: "апр", value: 180_000 },
+  { label: "мая", value: 540_000 },
+  { label: "июн", value: 610_000 },
+  { label: "июл", value: -60_000 },
+  { label: "авг", value: 280_000 },
+  { label: "сен", value: 470_000 },
+  { label: "окт", value: 390_000 },
+  { label: "ноя", value: 0 },
+  { label: "дек", value: 0 },
+];
+
+/** October is the current month: November and December are still empty. */
+const CURRENT_MONTH = 9;
+
+const formatRubles = (value: number) =>
+  `${value < 0 ? "−" : ""}${Math.abs(value).toLocaleString("ru-RU")} ₽`;
+
+export default function SparklineSignedBarsExample() {
+  return (
+    <Card.Root className={styles.card}>
+      <Card.Body>
+        <Sparkline
+          data={PROFIT}
+          label="Прибыль по месяцам, 2026"
+          variant="bars"
+          highlight={CURRENT_MONTH}
+          formatValue={formatRubles}
+        />
+      </Card.Body>
+    </Card.Root>
+  );
+}

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

@@ -0,0 +1,30 @@
+/** While the series loads the date, the value and the plot are Skeletons in their own places; the title stays — `loading`. */
+import { Sparkline, type SparklinePoint, Typography } from "prime-ui-kit";
+
+const REVENUE: SparklinePoint[] = [
+  { label: "июл", value: 2_840_000 },
+  { label: "авг", value: 3_120_000 },
+  { label: "сен", value: 2_960_000 },
+  { label: "окт", value: 3_410_000 },
+];
+
+const formatRubles = (value: number) => `${value.toLocaleString("ru-RU")} ₽`;
+
+export default function SparklineStatesExample() {
+  return (
+    <div>
+      <div>
+        <Sparkline data={REVENUE} label="Выручка" formatValue={formatRubles} />
+        <Typography as="span" variant="caption" tone="muted">
+          data
+        </Typography>
+      </div>
+      <div>
+        <Sparkline data={[]} label="Выручка" loading />
+        <Typography as="span" variant="caption" tone="muted">
+          loading
+        </Typography>
+      </div>
+    </div>
+  );
+}

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

@@ -0,0 +1,29 @@
+/** The same week as a line and as bars from zero — `variant`. */
+import { Sparkline, type SparklinePoint, Typography } from "prime-ui-kit";
+
+const ORDERS: SparklinePoint[] = [
+  { label: "2 окт", value: 38 },
+  { label: "3 окт", value: 44 },
+  { label: "4 окт", value: 41 },
+  { label: "5 окт", value: 29 },
+  { label: "6 окт", value: 33 },
+  { label: "7 окт", value: 47 },
+  { label: "8 окт", value: 52 },
+];
+
+const VARIANTS = ["line", "bars"] as const;
+
+export default function SparklineVariantsExample() {
+  return (
+    <div>
+      {VARIANTS.map((variant) => (
+        <div key={variant}>
+          <Sparkline data={ORDERS} label="Заказы за неделю" variant={variant} />
+          <Typography as="span" variant="caption" tone="muted">
+            {variant}
+          </Typography>
+        </div>
+      ))}
+    </div>
+  );
+}