prime-ui-kit 0.9.0 → 0.9.2

package/src/components/timeline/COMPONENT.md

@@ -1,18 +1,18 @@
 # Timeline
 
 **Category:** data-display
+**Kind:** composite
 
 > An event feed: dots on a thin line, event title and date, an optional amount on the right, grouped under labels.
 
 ## When to use
 - Activity or operation history with dates and amounts (payments, rentals, orders).
 - Maintenance / audit history with intervals between events (`Timeline.Gap`).
-- A selectable list of events where the row opens details (`onClick`, `href`, `asChild`).
+- A list of events where a row opens details (`onClick`, `href`, `asChild`).
 
 ## When not to use
 - Steps of a process the user goes through → use [Stepper](../stepper/COMPONENT.md).
 - Records with many attributes to compare or sort → use [DataTable](../data-table/COMPONENT.md).
-- A short list of recent events inside a dashboard card without a line → `Card variant="list"` from [Card](../card/COMPONENT.md).
 - Transient system messages → use [Notification](../notification/COMPONENT.md).
 
 ## Import
@@ -23,269 +23,158 @@ import { Timeline } from "prime-ui-kit";
 ## Anatomy
 ```
 Timeline.Root                    size container, sets the tier
-└── Timeline.Group label         labelled <ol>; the line runs from its first dot to its last
-    ├── Timeline.Item            <li> + row (div | button | a | asChild element) with the dot
-    │   ├── Timeline.Title       first line
-    │   ├── Timeline.Meta        second line (date, relative time)
-    │   │   └── Timeline.MetaPrimary   emphasized part (or <strong>)
-    │   └── Timeline.Value       trailing amount
-    │       └── Timeline.ValueMeta     second line under the amount
-    └── Timeline.Gap             <li>: interval between events (dashed segment, hollow dot)
+└─ Timeline.Group label          labelled <ol>; the line runs from its first dot to its last
+   ├─ Timeline.Item              <li> + row (div | button | a | asChild element) with the dot
+   │  ├─ Timeline.Title          first line
+   │  ├─ Timeline.Meta           second line (date)
+   │  │  └─ Timeline.MetaPrimary emphasized part
+   │  └─ Timeline.Value          trailing amount
+   │     └─ Timeline.ValueMeta   second line under the amount
+   └─ Timeline.Gap               <li>: interval between events (dashed segment, hollow dot)
+      └─ Timeline.GapMeta        caption on the right («сейчас»)
 ```
 
 ## API
 
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 ### Timeline.Root
-`<div>`. Forwards `ref`. Provides `size` to nested controls.
+`ref` → `HTMLDivElement`. A size container that sets the tier for every group and row.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `"m"` | Tier of text, dots and row rhythm. |
-| `highlight` | `"selected" \| "hover"` | `"selected"` | Who gets the highlighted look: the `active` row, or the row under the pointer / with keyboard focus. |
-| `children` | `ReactNode` | — (required) | `Timeline.Group` elements. |
-| `className` | `string` | — | Extra class. |
-
-+ native `<div>` props except `children`.
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `"m"` | Text, dot and row rhythm: rows 40 · 52 · 64 · 68 · 76 px. |
+| `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "children">` | — | `children` (`Timeline.Group`), `className` and the other div attributes. |
 
 ### Timeline.Group
-Renders `<div>` (label) + `<ol>`. Forwards `ref` to the `<ol>`; native props go to the `<ol>`.
+`ref` → `HTMLOListElement`. A labelled `<ol>` of events; the line runs from its first dot to its last.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `label` | `ReactNode` | — | Group heading; labels the list via `aria-labelledby`. |
-| `children` | `ReactNode` | — (required) | `Timeline.Item` and `Timeline.Gap`. |
-| `className` | `string` | — | Class on the `<ol>`. |
-
-+ native `<ol>` props except `children`.
+| `label` | `ReactNode` | — | Group heading («Недавно»); names the list via `aria-labelledby`. |
+| `…rest` | `Omit<OlHTMLAttributes<HTMLOListElement>, "children">` | — | `children` (`Timeline.Item`, `Timeline.Gap`), `className` and the other ol attributes. |
 
 ### Timeline.Item
-Renders `<li>` with a row element. Forwards `ref` to the row (`<div>`, `<button>`, `<a>` or the `asChild` element).
+`ref` → the row element. An `<li>` with a row: `<div>`, `<button>` (`onClick`), `<a>` (`href`) or your element (`asChild`); the dot is prepended. The row under the pointer or keyboard focus is highlighted (pill, accent title and dot).
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `color` | `PaletteColor` (`"gray" \| "blue" \| "green" \| "orange" \| "red" \| "yellow" \| "purple" \| "sky" \| "pink" \| "teal"`) | `"blue"` | Decorative dot hue at reduced emphasis (55%). Ignored when `tone` is set. |
+| `color` | `"gray" \| "blue" \| "green" \| "orange" \| "red" \| "yellow" \| "purple" \| "sky" \| "pink" \| "teal"` | `"blue"` | Decorative dot hue for categories, at reduced emphasis. |
 | `tone` | `"neutral" \| "accent" \| "success" \| "warning" \| "danger" \| "info"` | — | Status dot color at full emphasis; wins over `color`. |
-| `active` | `boolean` | `false` | Highlighted / selected row: `data-state="active"`, `aria-current="true"`. |
-| `href` | `string` | — | Renders the row as `<a>`. |
-| `asChild` | `boolean` | `false` | Renders the row as the single child element (router link); the dot is prepended to its children. |
-| `onClick` | `React.MouseEventHandler<HTMLElement>` | — | Renders the row as `<button type="button">` (unless `href` / `asChild`). |
-| `target` / `rel` / `download` | anchor attributes | — | Passed to the row (for `href`). |
-| `children` | `ReactNode` | — (required) | `Timeline.Title`, `Timeline.Meta`, `Timeline.Value`. |
-| `className` | `string` | — | Class on the row. |
-
-+ native HTML props of the row except `children`, `color`, `onClick`.
-
-### Timeline.Title
-`<span>`. No ref forwarding.
+| `onClick` | `MouseEventHandler<HTMLElement>` | — | Renders the row as a `<button>`. |
+| `href` | `string` | — | Renders the row as a link (with `target`, `rel`, `download`). |
+| `asChild` | `boolean` | `false` | Renders the row as the single child element (a router link). |
+| `…rest` | `Omit<HTMLAttributes<HTMLElement>, "children" \| "color" \| "onClick">` | — | `children` (Title, Meta, Value), `className` and the other row attributes. |
 
-| Prop | Type | Default | Description |
-|---|---|---|---|
-| `children` | `ReactNode` | — (required) | Event text; weight 500, wraps when narrow. |
-| `className` | `string` | — | Extra class. |
-
-+ native `<span>` props except `children`.
-
-### Timeline.Meta
-`<span>`. No ref forwarding.
+### Timeline.Title · Timeline.Meta · Timeline.MetaPrimary
+`ref` → `HTMLSpanElement`. `<span>` lines: the event (medium, accent on the highlighted row, wraps), the muted date line with tabular numbers, and its emphasized part.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `children` | `ReactNode` | — (required) | Date and relative time; muted, `tabular-nums`. `<strong>` inside is emphasized like `MetaPrimary`. |
-| `className` | `string` | — | Extra class. |
-
-+ native `<span>` props except `children`.
+| `…rest` | `HTMLAttributes<HTMLSpanElement>` | — | `children`, `className` and the other span attributes. |
 
-### Timeline.MetaPrimary
-`<span>`. No ref forwarding.
+### Timeline.Value · Timeline.ValueMeta
+`ref` → `HTMLSpanElement`. `<span>`: the trailing amount (right-aligned, tabular) and a muted second line under it. Moves under the meta below 20rem.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `children` | `ReactNode` | — (required) | Emphasized part of the meta line: primary text, weight 500. |
-| `className` | `string` | — | Extra class. |
+| `tone` | `"neutral" \| "accent" \| "success" \| "warning" \| "danger" \| "info"` | `"neutral"` | Value: text color (income `success`, refund `danger`). |
+| `…rest` | `HTMLAttributes<HTMLSpanElement>` | — | `children`, `className` and the other span attributes. |
 
-+ native `<span>` props except `children`.
-
-### Timeline.Value
-`<span>`. No ref forwarding.
-
-| Prop | Type | Default | Description |
-|---|---|---|---|
-| `tone` | `"neutral" \| "accent" \| "success" \| "warning" \| "danger" \| "info"` | `"neutral"` | Text color of the amount. |
-| `children` | `ReactNode` | — (required) | Amount, optionally followed by `Timeline.ValueMeta`. |
-| `className` | `string` | — | Extra class. |
-
-+ native `<span>` props except `children`.
-
-### Timeline.ValueMeta
-`<span>`. No ref forwarding.
+### Timeline.Gap
+`ref` → `HTMLDivElement`. An `<li>` interval between events: a shorter row with a hollow dot on a dashed segment and a muted caption.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `children` | `ReactNode` | — (required) | Second line under the amount (category, unit): meta size, muted. |
-| `className` | `string` | — | Extra class. |
+| `tone` | `"neutral" \| "accent" \| "success" \| "warning" \| "danger" \| "info"` | `"neutral"` | Caption and dot color; `warning` / `danger` flag a long interval. |
+| `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "children">` | — | `children` (the interval caption and an optional `Timeline.GapMeta`), `className` and the other div attributes. |
 
-+ native `<span>` props except `children`.
-
-### Timeline.Gap
-Renders `<li>` + `<div>`. Forwards `ref` to the `<div>`.
+### Timeline.GapMeta
+`ref` → `HTMLSpanElement`. A caption on the right of the gap («сейчас»), in the gap tone.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `tone` | `"neutral" \| "accent" \| "success" \| "warning" \| "danger" \| "info"` | `"neutral"` | Caption and hollow dot color. |
-| `trailing` | `ReactNode` | — | Caption on the right («сейчас»). |
-| `children` | `ReactNode` | — (required) | Interval caption («40 дней · 2 200 км без обслуживания»). |
-| `className` | `string` | — | Class on the `<div>`. |
-
-+ native `<div>` props except `children`.
+| `…rest` | `HTMLAttributes<HTMLSpanElement>` | — | `children`, `className` and the other span attributes. |
 
 ## Variants
 
 ### size
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
-| `xs` | Rows 40, title 12/16, meta caption, dot 8, label caption | Very dense side panels | |
-| `s` | Rows 52, title 13/20, meta caption, label body-s | Side panels, drawers | |
-| `m` | Rows 64, title 14/20, meta body-s 13/20, dot 10, label title-s | Page content and cards | yes |
-| `l` | Rows 68, title 16/24, meta body-m, dot 12, label title-m | Spacious feeds | |
-| `xl` | Rows 76, title 16/24, larger paddings, dot 12, label title-m | Large detail pages | |
+| `xs` | rows 40, title 12/16, dot 8 | very dense side panels | |
+| `s` | rows 52, title 13/20 | side panels, drawers | |
+| `m` | rows 64, title 14/20, dot 10 | page content and cards | yes |
+| `l` · `xl` | rows 68 / 76, title 16/24, dot 12 | spacious feeds, detail pages | |
 
-### highlight
+### color (Item)
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
-| `selected` | The `active` row has a `fill-subtle-active` pill (radius 12), accent title and dot; interactive rows get a faint `fill-subtle` hover | A row selects a detail view and the selection persists | yes |
-| `hover` | The row under the pointer or with keyboard focus gets the pill, accent title and dot, transiently; `active` keeps only `aria-current` | Rows are links that open a page | |
+| `blue` | blue dot at reduced emphasis | default category | yes |
+| `gray` · `green` · `orange` · `red` · `yellow` · `purple` · `sky` · `pink` · `teal` | dot in the hue | categories | |
 
-### Item `color`
-| Value | Looks like | Use when | Default |
-|---|---|---|---|
-| `blue` | Blue dot at 55% | Default category | yes |
-| `gray` | Gray dot | Neutral / system events | |
-| `green` | Green dot | Category hue | |
-| `orange` | Orange dot | Category hue | |
-| `red` | Red dot | Category hue (repairs, incidents) | |
-| `yellow` | Yellow dot | Category hue | |
-| `purple` | Purple dot | Category hue | |
-| `sky` | Sky dot | Category hue | |
-| `pink` | Pink dot | Category hue | |
-| `teal` | Teal dot | Category hue | |
-
-### Item `tone`
-| Value | Looks like | Use when | Default |
-|---|---|---|---|
-| `neutral` | Muted-text dot | A status without meaning (draft) | — (unset: `color` is used) |
-| `accent` | Accent dot | Current / pending action | |
-| `success` | Success dot | Paid, completed | |
-| `warning` | Warning dot | Overdue, needs attention | |
-| `danger` | Danger dot | Refund, failure | |
-| `info` | Info (sky) dot | Informational system events | |
-
-### Value `tone`
+### tone (Item · Value · Gap)
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
-| `neutral` | Primary text, weight 500 | Plain amounts | yes |
-| `accent` | Accent text | Highlighted amount | |
-| `success` | Success text | Income | |
-| `warning` | Warning text | Amount at risk | |
-| `danger` | Danger text | Expense / refund | |
-| `info` | Info text | Informational amount | |
-
-### Gap `tone`
-| Value | Looks like | Use when | Default |
-|---|---|---|---|
-| `neutral` | Muted caption and hollow dot on a dashed segment | Normal interval | yes |
-| `accent` | Accent caption and dot | Waiting on an action | |
-| `success` | Success caption and dot | Interval within norms | |
-| `warning` | Warning caption and dot | Interval too long | |
-| `danger` | Danger caption and dot | Critical interval | |
-| `info` | Info caption and dot | Informational note | |
-
-### Row element (structural)
-| Value | Looks like | Use when | Default |
-|---|---|---|---|
-| none of `onClick` / `href` / `asChild` | Static `<div>` row | Read-only feed | yes |
-| `onClick` | `<button>` row, pointer cursor, hover wash, inset focus ring | Selecting a row | |
-| `href` | `<a>` row | Row opens a page | |
-| `asChild` | Your element (router link) | Client-side routing | |
-
-**Combinations**
-- Recommended: `color` for categories in read-only feeds; `tone` on Item + Value together for statuses (`success` income, `danger` refund); `highlight="hover"` with `href` rows; `Gap tone="warning"` for too-long intervals.
-- Allowed but rare: `tone` on Value only (keep the dot categorical).
-- Avoid: `color` and `tone` together on one item (`tone` wins silently); more than one `active` row; `highlight="hover"` with `onClick` selection (selection becomes invisible).
+| `neutral` | muted dot / primary value / muted gap caption | a status without meaning | Value, Gap |
+| `accent` | accent | a pending action | |
+| `success` | success | paid, income | |
+| `warning` | warning | overdue, a too-long interval | |
+| `danger` | danger | refund, failure | |
+| `info` | info | informational events | |
 
-**Sizes**
-Default `m` rows are 64px. Inside a Card use `m`; in a 320–375px drawer `s`.
-
-**Hierarchy**
-One `active` row at most; amounts are the only right-aligned content; use group labels instead of extra headings.
+On an Item `tone` wins over `color` and shows at full emphasis.
 
 ## States
-| State / attribute | Element | Driven by |
+| State | Driven by | DOM |
 |---|---|---|
-| `data-size`, `data-highlight` | Root | `size`, `highlight` |
-| `data-state="active" \| "inactive"` | `<li>` and row | `active` |
-| `aria-current="true"` | row | `active` |
-| `data-color` | row | `color` (only when no `tone`) |
-| `data-tone` | row / Value / Gap row | `tone` (Value always has it, default `neutral`; Gap default `neutral`) |
-| `data-interactive="true"` | row | `onClick`, `href` or `asChild` |
-| hover / focus-visible | interactive row | `fill-subtle` wash (or the full highlight with `highlight="hover"`), inset focus ring |
+| tier | `size` | `data-size` on the root |
+| highlighted | pointer over the row, keyboard focus | `:hover`, `:focus-visible`: `fill-subtle-active` pill, accent title and dot (a `tone` keeps its dot) |
+| dot color | `color` / `tone` | `data-color` (without a tone) or `data-tone` |
+| interactive | `onClick`, `href`, `asChild` | `data-interactive`; pointer cursor, inset focus ring |
 
-Selection is controlled by the parent through `active`; Timeline keeps no state.
+Timeline keeps no state and has no persistent selection: every row is highlighted only while it is under the pointer or focused.
 
 ## Layout & spacing
-- The root fills its width and is a size container; give it a definite width (`width: min(100%, 30rem)`), a shrink-wrapped parent collapses it.
-- Group label → first row `--prime-space-2` (m); group → group `--prime-space-4`.
-- Row grid: dot column · text · value. Below 20rem of root width the value moves under the meta line.
+- The root is a size container: give it a definite width (`width: min(100%, 30rem)`).
+- Row grid: dot column · text · value; below 20rem of root width the value moves under the meta line.
+- Rows touch so the line is continuous; group → group `--prime-space-4`.
 - Inside a Card put it in `Card.Body`; the card owns the padding.
-- Rows touch (no gap) so the line is continuous; the line stops at each dot edge.
 
 ## Accessibility
-- Each group is an `<ol>` labelled by its heading (`aria-labelledby`); items are `<li>`.
-- The dot is `aria-hidden`; meaning must be in the title or meta text, not only in the dot color.
-- `active` sets `aria-current="true"`.
-- Interactive rows are native `<button>` / `<a>` (one Tab stop per row, Enter / Space); the focus ring is drawn inside the row.
-- No `labels` keys.
 
-## Examples
-| File | Scenario | When to use this pattern |
-|---|---|---|
-| [activity-feed.tsx](examples/activity-feed.tsx) | «Недавно» group with an `active` row | Operation histories with amounts |
-| [service-history.tsx](examples/service-history.tsx) | `Timeline.Gap` intervals, `trailing`, `tone="warning"`, `ValueMeta` | Maintenance and audit histories |
-| [selectable.tsx](examples/selectable.tsx) | `onClick` rows, controlled `active`, `tone` on dot and amount | Selecting a row for details |
-| [hover-highlight.tsx](examples/hover-highlight.tsx) | `highlight="hover"` with `href` rows | Rows that open pages |
-| [in-card.tsx](examples/in-card.tsx) | Two groups in `Card.Body`, dot `color` | Dashboard activity widgets |
-| [colors-and-tones.tsx](examples/colors-and-tones.tsx) | All `color` hues; every `tone` on Item, Value and Gap | Choosing dot and status colors |
-| [sizes.tsx](examples/sizes.tsx) | Tiers xs–xl | Choosing density |
-| [narrow.tsx](examples/narrow.tsx) | 375px and 280px widths | Mobile layouts |
+### Keyboard
+| Key | Action |
+|---|---|
+| `Tab` | Interactive rows are one Tab stop each; the focus ring is drawn inside the row. |
+| `Enter` · `Space` | Activates a button row; Enter opens a link row. |
 
-```tsx
-import { Timeline } from "prime-ui-kit";
+### ARIA
+- Each group is an `<ol>` labelled by its heading (`aria-labelledby`); events are `<li>`.
+- The dot is `aria-hidden`: put the status into the title or meta, not only the dot color.
 
-export function PaymentsFeed() {
-  return (
-    <Timeline.Root>
-      <Timeline.Group label="Недавно">
-        <Timeline.Item tone="success">
-          <Timeline.Title>Оплата получена · Иван К.</Timeline.Title>
-          <Timeline.Meta>
-            <Timeline.MetaPrimary>07.10.26</Timeline.MetaPrimary> · 2 ч. назад
-          </Timeline.Meta>
-          <Timeline.Value tone="success">+6 300 ₽</Timeline.Value>
-        </Timeline.Item>
-      </Timeline.Group>
-    </Timeline.Root>
-  );
-}
-```
+### Labels
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+No `labels`.
+
+## Examples
+| Example | Shows |
+|---|---|
+| [overview.tsx](examples/overview.tsx) | An operations feed: one labelled group, a line through the dots, the row under the pointer highlighted — `Timeline.Group`, `Timeline.Value`. |
+| [variants.tsx](examples/variants.tsx) | Dot hues for categories at reduced emphasis, and status tones on items, values and gaps at full emphasis — `color`, `tone`. |
+| [sizes.tsx](examples/sizes.tsx) | Every tier scales text, dot and row rhythm, rows 40 to 76 px — `size`. |
+| [structure.tsx](examples/structure.tsx) | A service history with intervals between events, a caption on the right of a gap and a second value line — `Timeline.Gap`, `Timeline.GapMeta`, `Timeline.ValueMeta`. |
+| [links.tsx](examples/links.tsx) | Rows that open an operation page become links, one Tab stop each with a focus ring — `href`. |
+| [narrow.tsx](examples/narrow.tsx) | At 375 px the title wraps and the amount stays right; below 20rem of its own width the amount moves under the meta line. |
 
 ## Mistakes
 - `Timeline.Item` outside `Timeline.Group` → items are `<li>`; always wrap them in a group.
-- A process with steps («Шаг 1 из 3») → use Stepper.
-- Status only by dot color → put the status in the title or meta too.
-- `<div onClick>` inside an item for selection → pass `onClick` to `Timeline.Item` (native button, focus ring).
-- `Timeline.Root` inside a shrink-wrapped flex parent → give it a width; the size container collapses otherwise.
-- Custom dashed separators between events → use `Timeline.Gap`.
+- A process with steps → use Stepper.
+- Status only by dot color → put it in the title or meta too.
+- `<div onClick>` inside an item → pass `onClick` to `Timeline.Item` (native button, focus ring).
+- `Timeline.Root` in a shrink-wrapped flex parent → give it a width.
+- Using the timeline to pick a row (a selected / current state) → it has none; use a list with selection (`Select`, `DataTable` row selection) or `Tabs`.
 
 ## Related
-- [Stepper](../stepper/COMPONENT.md) — process steps.
-- [DataTable](../data-table/COMPONENT.md) — tabular records.
-- [Card](../card/COMPONENT.md) — host for feed widgets.
+- **Built from:** —
+- **See also:** [Stepper](../stepper/COMPONENT.md), [DataTable](../data-table/COMPONENT.md), [Card](../card/COMPONENT.md)

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

@@ -1,6 +1,7 @@
-/* The root is a size container: give it a definite width, a shrink-wrapped container collapses. */
+/* Layout of the Timeline scenarios. The root is a size container: give it a definite width,
+   a shrink-wrapped container collapses. */
 
-/* 30rem. */
+/* 30rem feed. */
 .feed {
   width: min(100%, calc(var(--prime-space-24) * 5));
 }
@@ -13,28 +14,12 @@
   min-width: 0;
 }
 
-/* Caption above a feed: the gap replaces a bottom margin on the caption. */
-.cell {
-  display: grid;
-  gap: var(--prime-space-3);
-  min-width: 0;
-}
-
-.card {
-  width: min(100%, calc(var(--prime-space-24) * 5));
-}
-
-/* 375px phone width. */
+/* narrow.tsx: a 375px phone column. */
 .phone {
-  box-sizing: border-box;
-  display: grid;
-  gap: var(--prime-space-3);
   width: min(100%, calc(var(--prime-space-1) * 93.75));
 }
 
-/* 280px: below the 20rem container breakpoint. */
+/* narrow.tsx: 280px, below the 20rem container breakpoint. */
 .narrow {
-  display: grid;
-  gap: var(--prime-space-3);
   width: min(100%, calc(var(--prime-space-10) * 7));
 }

package/src/components/timeline/examples/links.tsx

@@ -0,0 +1,28 @@
+/** Rows that open an operation page become links, one Tab stop each with a focus ring — `href`. */
+import { Timeline } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const EVENTS = [
+  { id: "rent-ivan", title: "Аренда закончилась · Иван К.", date: "21.09.26", value: "+6 300 ₽" },
+  { id: "oil", title: "ТО: замена масла", date: "10.09.26", value: "−689 ₽" },
+  { id: "wash", title: "Мойка и химчистка салона", date: "01.09.26", value: "−450 ₽" },
+];
+
+export default function TimelineLinksExample() {
+  return (
+    <Timeline.Root className={styles.feed}>
+      <Timeline.Group label="Операции">
+        {EVENTS.map((event) => (
+          <Timeline.Item key={event.id} href={`#${event.id}`}>
+            <Timeline.Title>{event.title}</Timeline.Title>
+            <Timeline.Meta>
+              <Timeline.MetaPrimary>{event.date}</Timeline.MetaPrimary>
+            </Timeline.Meta>
+            <Timeline.Value>{event.value}</Timeline.Value>
+          </Timeline.Item>
+        ))}
+      </Timeline.Group>
+    </Timeline.Root>
+  );
+}

package/src/components/timeline/examples/narrow.tsx

@@ -1,49 +1,41 @@
-/** At 375px the title wraps and the amount stays on the right; below 20rem of its own width (container query) the amount moves under the meta line. Use to check mobile layouts. */
-
-import { Timeline, Typography } from "prime-ui-kit";
+/** At 375 px the title wraps and the amount stays right; below 20rem of its own width the amount moves under the meta line. */
+import { Timeline } from "prime-ui-kit";
 
 import styles from "./examples.module.css";
 
-function Rows() {
-  return (
-    <Timeline.Group label="Недавно">
-      <Timeline.Item>
-        <Timeline.Title>Аренда закончилась · Марина Л.</Timeline.Title>
-        <Timeline.Meta>
-          <Timeline.MetaPrimary>17.07.26</Timeline.MetaPrimary> · 81 д. назад
-        </Timeline.Meta>
-        <Timeline.Value>+9 450 ฿</Timeline.Value>
-      </Timeline.Item>
-      <Timeline.Item active>
-        <Timeline.Title>ТО: замена масла и фильтров, проверка тормозов</Timeline.Title>
-        <Timeline.Meta>
-          <Timeline.MetaPrimary>10.09.26</Timeline.MetaPrimary> · 26 д. назад
-        </Timeline.Meta>
-        <Timeline.Value>−689 ฿</Timeline.Value>
-      </Timeline.Item>
-    </Timeline.Group>
-  );
-}
+const WIDTHS = [
+  { id: "phone", className: styles.phone, label: "375 px" },
+  { id: "narrow", className: styles.narrow, label: "280 px" },
+];
+
+const EVENTS = [
+  { id: 1, title: "Аренда закончилась · Марина Л.", date: "17.07.26", value: "+9 450 ₽" },
+  {
+    id: 2,
+    title: "ТО: замена масла и фильтров, проверка тормозов",
+    date: "10.09.26",
+    value: "−689 ₽",
+  },
+];
 
 export default function TimelineNarrowExample() {
   return (
     <div className={styles.stack}>
-      <div className={styles.phone}>
-        <Typography.Root variant="caption" tone="muted">
-          375px
-        </Typography.Root>
-        <Timeline.Root>
-          <Rows />
-        </Timeline.Root>
-      </div>
-      <div className={styles.narrow}>
-        <Typography.Root variant="caption" tone="muted">
-          280px
-        </Typography.Root>
-        <Timeline.Root>
-          <Rows />
+      {WIDTHS.map((width) => (
+        <Timeline.Root key={width.id} className={width.className}>
+          <Timeline.Group label={width.label}>
+            {EVENTS.map((event) => (
+              <Timeline.Item key={event.id}>
+                <Timeline.Title>{event.title}</Timeline.Title>
+                <Timeline.Meta>
+                  <Timeline.MetaPrimary>{event.date}</Timeline.MetaPrimary>
+                </Timeline.Meta>
+                <Timeline.Value>{event.value}</Timeline.Value>
+              </Timeline.Item>
+            ))}
+          </Timeline.Group>
         </Timeline.Root>
-      </div>
+      ))}
     </div>
   );
 }

package/src/components/timeline/examples/{activity-feed.tsx → overview.tsx}

@@ -1,47 +1,39 @@
-/** Activity feed: a «Недавно» group, the line joins the first and last dots, the `active` row gets the pill with accent title and dot. Use for operation histories with amounts. */
-
+/** An operations feed: one labelled group, a line through the dots, the row under the pointer highlighted — `Timeline.Group`, `Timeline.Value`. */
 import { Timeline } from "prime-ui-kit";
 
 import styles from "./examples.module.css";
 
-const events = [
+const EVENTS = [
   {
     id: 1,
     title: "Аренда закончилась · Иван К.",
     date: "21.09.26",
     ago: "15 д. назад",
-    value: "+6 300 ฿",
+    value: "+6 300 ₽",
   },
-  { id: 2, title: "ТО: замена масла", date: "10.09.26", ago: "26 д. назад", value: "−689 ฿" },
+  { id: 2, title: "ТО: замена масла", date: "10.09.26", ago: "26 д. назад", value: "−689 ₽" },
   {
     id: 3,
     title: "Аренда закончилась · Сергей М.",
     date: "04.09.26",
     ago: "32 д. назад",
-    value: "+13 500 ฿",
+    value: "+13 500 ₽",
   },
   {
     id: 4,
     title: "Аренда закончилась · Амир Х.",
     date: "30.07.26",
     ago: "68 д. назад",
-    value: "+5 400 ฿",
-  },
-  {
-    id: 5,
-    title: "Аренда закончилась · Марина Л.",
-    date: "17.07.26",
-    ago: "81 д. назад",
-    value: "+9 450 ฿",
+    value: "+5 400 ₽",
   },
 ];
 
-export default function TimelineActivityFeedExample() {
+export default function TimelineOverviewExample() {
   return (
     <Timeline.Root className={styles.feed}>
       <Timeline.Group label="Недавно">
-        {events.map((event) => (
-          <Timeline.Item key={event.id} active={event.id === 2}>
+        {EVENTS.map((event) => (
+          <Timeline.Item key={event.id}>
             <Timeline.Title>{event.title}</Timeline.Title>
             <Timeline.Meta>
               <Timeline.MetaPrimary>{event.date}</Timeline.MetaPrimary> · {event.ago}