@acronis-platform/ui-react 5.0.0 → 5.1.1

package/dist/llms/bar-chart.md

@@ -1,6 +1,6 @@
 # BarChart
 
-> A typed bar-chart composition over the shared `Chart` primitives. Takes `data` + `config` + a set of series `dataKeys` and renders a themed recharts `BarChart` inside a `ChartContainer`, with tooltip and legend chrome. Two variant axes: `orientation` (vertical / horizontal bars) and `layout` (grouped / stacked). Ported from the apps/demo `BarChartPlayground`.
+> Two renderings behind one name, selected by `orientation`. `vertical` (the default) is a typed bar-chart composition over the shared `Chart` primitives: `data` + `config` + a set of series `dataKeys` become a themed recharts `BarChart` inside a `ChartContainer`, with tooltip and legend chrome, grouped or stacked by `layout`. `horizontal` is a labelled proportional bar list — one row per `items` entry carrying its label, value, share of `max`, and a track bar — with no axes, grid, or recharts at all.
 
 **Status:** draft · **Category:** data-display · **Since:** v0.57.0
 
@@ -18,10 +18,19 @@ import { BarChart } from '@acronis-platform/ui-react'
   data={data}
   dataKeys={['desktop', 'mobile']}
   xKey="month"
-  orientation="vertical"
   layout="grouped"
   className="h-[320px] w-[560px]"
 />
+
+<BarChart
+  orientation="horizontal"
+  palette={{ type: 'status' }}
+  items={[
+    { label: 'Critical', value: 6, tone: { status: 'danger' } },
+    { label: 'High', value: 9, tone: { status: 'warning' } },
+  ]}
+  max={29}
+/>
 ```
 
 A typed bar-chart built on the shared `Chart` primitives. Give it `data`, a
@@ -42,6 +51,8 @@ Series colors come from the `palette` prop — a dataviz palette resolving to th
 
 ## When not to use
 
+- A ranked breakdown where each row needs its own label, value, and percentage
+  — that is `orientation="horizontal"`, not a chart.
 - A single metric or KPI — use a `Tag`, `Badge`, or plain text.
 - Trends over a continuous dimension — prefer a line/area chart.
 - Part-to-whole of a single total — consider a pie/donut chart.
@@ -49,10 +60,48 @@ Series colors come from the `palette` prop — a dataviz palette resolving to th
 
 ## Variants
 
-| Axis          | Values                    | Effect                                                 |
-| ------------- | ------------------------- | ------------------------------------------------------ |
-| `orientation` | `vertical` · `horizontal` | Bars grow up (category on x) vs right (category on y). |
-| `layout`      | `grouped` · `stacked`     | Series side-by-side vs summed on a shared stack.       |
+| Axis          | Values                    | Effect                                                    |
+| ------------- | ------------------------- | --------------------------------------------------------- |
+| `orientation` | `vertical` · `horizontal` | The recharts chart vs the labelled proportional bar list. |
+| `layout`      | `grouped` · `stacked`     | Vertical only: series side-by-side vs summed on a stack.  |
+
+`orientation` is not a direction knob on one drawing — it picks which of two
+renderings you get, and the two take different props. See **Horizontal** below.
+
+## Horizontal
+
+`orientation="horizontal"` renders a labelled proportional bar list instead of a
+chart: one row per `items` entry (`{ label, value, color }`), each showing its
+label, its formatted value, its share of `max`, and a track filled to that
+share. There are no axes, no grid, and no recharts — just Base UI's `Meter`
+primitive per row, so each carries `role="meter"` and its numbers reach the
+accessibility tree.
+
+`max` defaults to the sum of every `items[].value`, which makes each row its
+share of the whole. Pass an explicit `max` when the rows are shares of a total
+they do not add up to. `valueFormatter` formats the number, `showTooltip`
+toggles the per-row hover card, and `tooltip` replaces its content.
+
+```tsx
+<BarChart
+  orientation="horizontal"
+  items={[
+    {
+      label: 'Critical',
+      value: 6,
+      color: 'var(--ui-background-status-strong-danger)',
+    },
+    {
+      label: 'High',
+      value: 9,
+      color: 'var(--ui-background-status-strong-warning)',
+    },
+  ]}
+  max={29}
+/>
+```
+
+Everything below applies to the default (`vertical`) chart only.
 
 ## Highlighting a range
 
@@ -109,24 +158,28 @@ across brands until the real data-viz palette lands.
 
 | Prop | Type | Default | Required | Description |
 |------|------|---------|----------|-------------|
-| `orientation` | `'vertical' | 'horizontal'` | `'vertical'` | no | Direction the bars grow. `vertical` = bars rise (category on the x-axis); `horizontal` = bars extend rightward (category on the y-axis). |
-| `layout` | `'grouped' | 'stacked'` | `'grouped'` | no | How multiple series are arranged. `grouped` = side-by-side bars; `stacked` = segments summed on a shared `stackId`. |
-| `data` | `ReadonlyArray<Record<string, string | number>>` | — | yes | Row-per-category data — each row holds `xKey` plus one numeric field per series. |
-| `config` | `ChartConfig` | — | yes | Series take their colour from the container's `palette`; each entry maps a data key to a `label` and an optional `tone`. Resolved into the `--color-<key>` custom properties the bars fill from. |
-| `dataKeys` | `string[]` | — | yes | Series to plot — one bar per key. Each must exist in `config` and every data row. |
-| `xKey` | `string` | — | yes | The category dimension key shared across rows. |
-| `referenceLine` | `Line | Line[]  where Line = { value?: number; average?: boolean | string; label?: string }` | — | no | One or more dashed reference/average lines on the value axis (Y for vertical bars, X for horizontal). Pass a single object or an array. Per line, a fixed `value` wins; otherwise the mean of one series (`average: '<key>'`) or of every plotted series (`average: true`). An optional `label` captions each. |
+| `orientation` | `'vertical' | 'horizontal'` | `'vertical'` | no | Which of the two renderings to use. `vertical` (the default) draws the chart: bars rising from a category x-axis, with axes, grid, tooltip and legend. `horizontal` draws a labelled proportional bar list instead — one row per `items` entry, no axes or grid. The two modes take different props: `data`/`config`/`dataKeys`/`xKey` and every chart knob below apply only to `vertical`; `items`, `max`, `valueFormatter` and `tooltip` only to `horizontal`. |
+| `items` | `Array<{ label: string; value: number; color?: string; tone?: { status: ChartStatusTone }; forecast?: number }>` | — | no | Required when `orientation="horizontal"`. One row per entry — each renders as a labelled proportional bar carrying its value and share of `max`. Provide `color` (any CSS color; prefer a `--ui-*` token) when no `palette` is used, or `tone` together with `palette` to resolve the color from the palette. `color` and `tone` may both be set; `color` takes precedence. Optional `forecast`: projected total value — renders a translucent bar (30% opacity) extending beyond the actual value; the actual bar renders solid on top. Ignored when `forecast <= value`. ARIA values reflect the actual value; `aria-valuetext` also mentions the forecast. Ignored when `orientation="vertical"`. |
+| `max` | `number` | — | no | `orientation="horizontal"` only. Upper bound the item values are shares of. Defaults to the sum of every `items[].value`. |
+| `valueFormatter` | `(value: number) => string` | — | no | `orientation="horizontal"` only. Formats the numeric value in each row's label. Defaults to `toLocaleString()`. |
+| `tooltip` | `ReactNode` | — | no | `orientation="horizontal"` only. Tooltip content shared by every row, replacing the default (swatch + label + value of max + percentage). Ignored when `showTooltip` is false. |
+| `palette` | `ChartPalette` | — | no | `orientation="horizontal"` only. Dataviz palette to resolve each item's color from. When provided, each `items` entry should carry a `tone` (and can omit `color`). Colors are resolved in the same order and with the same tone rules as the vertical chart — `status` tones pick a specific stop, slot-less items consume the next available stop. |
+| `layout` | `'grouped' | 'stacked'` | `'grouped'` | no | Vertical only. How multiple series are arranged. `grouped` = side-by-side bars; `stacked` = segments summed on a shared `stackId`. |
+| `data` | `ReadonlyArray<Record<string, string | number>>` | — | no | Required when `orientation="vertical"`. Row-per-category data — each row holds `xKey` plus one numeric field per series. |
+| `config` | `ChartConfig` | — | no | Required when `orientation="vertical"`. Series take their colour from the container's `palette`; each entry maps a data key to a `label` and an optional `tone`. Resolved into the `--color-<key>` custom properties the bars fill from. |
+| `dataKeys` | `string[]` | — | no | Required when `orientation="vertical"`. Series to plot — one bar per key. Each must exist in `config` and every data row. |
+| `xKey` | `string` | — | no | Required when `orientation="vertical"`. The category dimension key shared across rows. |
+| `referenceLine` | `Line | Line[]  where Line = { value?: number; average?: boolean | string; label?: string }` | — | no | One or more dashed reference/average lines on the value (Y) axis. Pass a single object or an array. Per line, a fixed `value` wins; otherwise the mean of one series (`average: '<key>'`) or of every plotted series (`average: true`). An optional `label` captions each. Vertical only. |
 | `xAxisLabel` | `string` | — | no | Title rendered beneath the horizontal (X) axis. |
 | `yAxisLabel` | `string` | — | no | Title rendered beside the vertical (Y) axis (rotated). |
-| `xUnit` | `string` | — | no | Unit suffix appended to X-axis tick values (recharts `unit`); applies when the X axis is numeric (horizontal orientation). |
-| `yUnit` | `string` | — | no | Unit suffix appended to Y-axis tick values (recharts `unit`); applies when the Y axis is numeric (vertical orientation). |
+| `yUnit` | `string` | — | no | Unit suffix appended to Y-axis tick values (recharts `unit`) — the Y axis is the numeric one. |
 | `referenceArea` | `Area | Area[]  where Area = { from?: string | number; to?: string | number; label?: string; highlightTicks?: boolean; divider?: boolean }` | — | no | One or more shaded bands behind a range of categories — e.g. a forecast period. `from`/`to` are inclusive and take either the category's value or its 0-based row index; an omitted bound runs to that end of the data. The category ticks under a band pick up the accent styling unless `highlightTicks` is false, and `divider` adds a dashed rule on the band's leading edge for a forecast hand-off. |
 | `barSettings` | `Record<string, { from?: string | number; to?: string | number; fill?: string; opacity?: number; dashed?: boolean; shape?: BarShape; background?: boolean | string }>` | — | no | Per-series style override for a range of categories, keyed by `dataKeys` entry — e.g. a projection tail that reads translucent and dashed over its own track. `background` takes `true` for a full-height track or a data field name to cap it at that row's value (the headroom up to an upper bound, which stacks on the bar and so needs `layout="grouped"`). Bars outside the range, and series with no entry, render normally. |
-| `barRadius` | `number` | `4` | no | Corner radius on the growing end of each bar (0 for square corners). |
+| `barRadius` | `number` | `8` | no | Corner radius on the growing end of each bar (0 for square corners). |
 | `barShape` | `'rounded' | 'pill' | 'gradient' | 'pattern'` | `'rounded'` | no | How every bar is painted: the growing end rounded by `barRadius`, a capsule, a fade of the series color, or diagonal hatching in it. Per-range overrides come from `barSettings`. |
-| `barSize` | `number` | — | no | Fixed bar thickness in px; unset, recharts sizes bars from the available width. |
+| `barSize` | `number` | `8` | no | Fixed bar thickness in px; unset, recharts sizes bars from the available width. |
 | `maxBarSize` | `number` | — | no | Upper bound on the computed bar thickness, in px. |
-| `barGap` | `number | string` | — | no | Gap between the bars of one category, in px or a percentage string. |
+| `barGap` | `number | string` | `4` | no | Gap between the bars of one category, in px or a percentage string. |
 | `barCategoryGap` | `number | string` | — | no | Gap between category groups, in px or a percentage string. |
 | `minPointSize` | `number` | — | no | Minimum rendered length for a non-zero bar, in px, so tiny values stay visible. |
 | `showBackground` | `boolean` | `false` | no | Draw a full-height track behind every bar. |
@@ -134,7 +187,7 @@ across brands until the real data-viz palette lands.
 | `showActiveBar` | `boolean` | `false` | no | Highlight the hovered bar. |
 | `activeBar` | `{ fill?: string; opacity?: number }` | — | no | Painting of the hovered bar when `showActiveBar` is on; defaults to the series color. |
 | `showGrid` | `boolean` | `true` | no | Render the CartesianGrid. |
-| `showTooltip` | `boolean` | `true` | no | Render the hover tooltip. |
+| `showTooltip` | `boolean` | `true` | no | Render the hover tooltip — recharts' for `vertical`, the per-row tooltip for `horizontal`. |
 | `showLegend` | `boolean` | `true` | no | Render the legend. |
 | `tooltipContent` | `ReactElement | ((props) => ReactNode)` | — | no | Replace the default tooltip. Pass a configured ChartTooltipContent (from this library) — e.g. with a formatter / labelFormatter — to customize the tooltip content without composing recharts. Ignored when showTooltip is false. |
 | `showXAxis` | `boolean` | `true` | no | Render the X axis (its ticks and title). Set false to hide it. |
@@ -143,9 +196,9 @@ across brands until the real data-viz palette lands.
 | `yTickFormatter` | `(value: number | string, index?: number) => string` | — | no | Format each Y-axis tick value (see xTickFormatter). |
 | `xAxisAngle` | `number` | — | no | Rotate the X-axis tick labels by this many degrees (a negative angle tilts them up toward the right); the tick anchor + axis height adjust. |
 | `xAxisInterval` | `number | 'preserveStart' | 'preserveEnd' | 'preserveStartEnd' | 'equidistantPreserveStart'` | — | no | X-axis tick density — a recharts placement strategy, or a fixed number of ticks to skip between two rendered ones (recharts interval: 0 shows every tick, 1 every other one, 2 every third). |
-| `yAxisTickCount` | `number` | — | no | Desired number of ticks on the value axis (recharts tickCount; a hint, not exact). Applies to whichever axis holds the values — Y for most charts, X for BarChart with orientation="horizontal". |
-| `yAxisDomain` | `'auto' | 'dataMin-dataMax' | 'zero'` | — | no | Value-axis domain preset — auto (fit the data at both ends; the axis need not include 0), zero (anchor the axis at 0, which is also recharts' behaviour when the prop is omitted), or dataMin-dataMax (tight to the data, no padding). Applies to whichever axis holds the values — Y for most charts, X for BarChart with orientation="horizontal". |
-| `gridDashed` | `boolean` | — | no | Draw grid lines dashed instead of solid. |
+| `yAxisTickCount` | `number` | — | no | Desired number of ticks on the value (Y) axis (recharts tickCount; a hint, not exact). |
+| `yAxisDomain` | `'auto' | 'dataMin-dataMax' | 'zero'` | — | no | Value-axis domain preset — auto (fit the data at both ends; the axis need not include 0), zero (anchor the axis at 0, which is also recharts' behaviour when the prop is omitted), or dataMin-dataMax (tight to the data, no padding). Applies to the value (Y) axis. |
+| `gridDashed` | `boolean` | `true` | no | Draw grid lines dashed instead of solid. |
 | `gridHorizontal` | `boolean` | — | no | Show horizontal grid lines (defaults to the chart's own default when unset). |
 | `gridVertical` | `boolean` | — | no | Show vertical grid lines (defaults to the chart's own default when unset). |
 | `animate` | `boolean` | `false` | no | Enable entrance animation. Off by default so output/baselines are unchanged. |
@@ -153,7 +206,7 @@ across brands until the real data-viz palette lands.
 | `animationBegin` | `number` | — | no | Delay before the animation starts, in ms. |
 | `animationEasing` | `'ease' | 'ease-in' | 'ease-out' | 'ease-in-out' | 'linear'` | — | no | Easing curve. |
 | `showLabels` | `boolean` | `false` | no | Render a value label on each bar segment. |
-| `labelPosition` | `'top' | 'bottom' | 'left' | 'right' | 'center' | 'insideTop' | 'insideBottom' | 'insideLeft' | 'insideRight' | 'insideStart' | 'insideEnd'` | — | no | Where the value labels sit. Defaults to the bar's growing end — top for vertical bars, right for horizontal — or center when layout is stacked. |
+| `labelPosition` | `'top' | 'bottom' | 'left' | 'right' | 'center' | 'insideTop' | 'insideBottom' | 'insideLeft' | 'insideRight' | 'insideStart' | 'insideEnd'` | — | no | Where the value labels sit. Defaults to the bar's growing end (top), or center when layout is stacked. |
 | `labelFormatter` | `(value) => string` | — | no | Format each label value (reuses the tick formatters). |
 | `showBrush` | `boolean` | `false` | no | Render a range brush beneath the chart — drag a handle (or the selected window) to zoom the series into a slice of the data. |
 | `brushHeight` | `number` | `28` | no | Height of the brush strip in px. A non-positive value falls back to the default rather than erasing the brush. |
@@ -176,18 +229,45 @@ Scenario: Render bars from data and config
 
 ```gherkin
 Scenario: Vertical orientation (default)
-  Given orientation is "vertical"
-  Then bars grow upward
+  Given orientation is omitted or "vertical"
+  Then the recharts chart renders
+  And bars grow upward
   And the category axis (xKey) is the x-axis and the value axis is the y-axis
   And the grid draws horizontal lines
 ```
 
 ```gherkin
 Scenario: Horizontal orientation
-  Given orientation is "horizontal"
-  Then bars extend rightward (recharts layout="vertical")
-  And the category axis (xKey) is the y-axis and the value axis is the x-axis
-  And the grid draws vertical lines
+  Given orientation is "horizontal" and items is a list of { label, value, color }
+  Then no chart renders — one labelled bar row renders per item
+  And each row shows its label, its formatted value, and its share of max
+  And each row exposes role="meter" with aria-valuenow and aria-valuemax
+  And the track fills to value/max in the item's own color
+```
+
+```gherkin
+Scenario: Horizontal orientation without an explicit max
+  Given orientation is "horizontal" and max is omitted
+  Then max falls back to the sum of every items[].value
+  And each row's percentage is its share of that total
+```
+
+```gherkin
+Scenario: Horizontal item with forecast
+  Given orientation is "horizontal" and an item has forecast greater than value
+  Then a translucent bar (30% opacity) extends from the actual value to the forecast
+  And the actual bar renders solid on top
+  And aria-valuetext includes the forecast value
+  And aria-valuenow reflects the actual value only
+  But when forecast is omitted or less than or equal to value, no forecast bar renders
+```
+
+```gherkin
+Scenario: Horizontal palette-driven colors
+  Given orientation is "horizontal" and a palette is set
+  Then each item's color is resolved through the palette machinery
+  And an item with a tone resolves to the palette's tone-specific token
+  And an explicit item.color still overrides the resolved palette color
 ```
 
 ```gherkin
@@ -223,9 +303,8 @@ Scenario: Legend
 ```gherkin
 Scenario: Fixed reference line
   Given referenceLine is { value: 250, label: "Target" }
-  Then a dashed line draws across the value axis at 250
+  Then a horizontal dashed line draws across the value (y) axis at 250
   And it is captioned "Target"
-  And for horizontal orientation the line is vertical (on the x-axis), else horizontal (on the y-axis)
 ```
 
 ```gherkin
@@ -302,7 +381,7 @@ Scenario: Address a range by index or by value
 Scenario: Mark the hand-off into a forecast
   Given a referenceArea entry sets divider: true
   Then a dashed rule draws on the band's leading edge
-  And it follows the category axis — the band's left edge for vertical bars, its top edge for horizontal ones
+  And it follows the category (x) axis — the band's left edge
 ```
 
 ```gherkin
@@ -354,6 +433,9 @@ Scenario: Active bar on hover
 
 ## Accessibility
 
+Everything below the "Horizontal" heading applies to
+`orientation="horizontal"`; the rest describes the default chart.
+
 - recharts' `accessibilityLayer` is **on by default** (recharts v3), giving the
   chart keyboard focus and an accessible description of the plotted points.
 - The **range brush** (`showBrush`) is the only interactive control these charts
@@ -400,7 +482,24 @@ Scenario: Active bar on hover
 - Watch recharts issue [#4809](https://github.com/recharts/recharts/issues/4809)
   on the a11y layer for heavily-customized charts.
 
+## Horizontal
+
+- Each row is Base UI's `Meter.Root`, so it carries `role="meter"` with
+  `aria-valuenow` / `aria-valuemax` and an `aria-valuetext` reading the
+  formatted value, the max, and the percentage — the numbers are in the
+  accessibility tree, not only in the picture.
+- The row's accessible name comes from its `Meter.Label`, which renders the
+  caller's `label`. There is no fallback string to localize.
+- A row takes focus (`tabindex="0"`) **only** when `showTooltip` is on, so the
+  tooltip is reachable without a pointer. A meter is not a control, so it is
+  deliberately out of the tab order when there is nothing to reveal.
+- The percentage and the value are rendered as text next to every bar, so the
+  track's fill is never the only channel carrying the number. `color` is
+  caller-supplied — it still needs 3:1 against the track, and it must not be the
+  only thing telling two rows apart.
+
 ## Contrast
 
 Chart chrome meets contrast in both themes via the semantic tokens. Bar fills
-come from `config` and are the caller's responsibility.
+come from `config` (vertical) or `items[].color` (horizontal) and are the
+caller's responsibility.

package/dist/llms/card-widget-carousel.md

@@ -0,0 +1,252 @@
+# CardWidgetCarousel
+
+> A horizontal scroll carousel that holds a row of action-widget cards and exposes floating Previous/Next chevron buttons to navigate the view. The carousel shell manages scroll; the individual cards are passed as `children`. Ships with a companion `CardWidget` component (same barrel) — a status-colored card with icon box, optional skeleton, and footer slot.
+
+**Status:** ready · **Category:** data-display · **Since:** v5.1.0
+
+## Import
+
+```tsx
+import { CardWidgetCarousel, CardWidget } from '@acronis-platform/ui-react'
+```
+
+## Quick example
+
+```tsx
+<CardWidgetCarousel nextLabel="Next" prevLabel="Previous">
+  <CardWidget
+    header="Phishing attacks"
+    status="danger"
+    icon={<WarningIcon size={16} />}
+    title="Phishing attack detected"
+    metric="$15K"
+    caption="Projected new MRR"
+    footer={<Button variant="ghost">Review</Button>}
+  />
+  <CardWidget header="Loading…" status="info" skeleton />
+</CardWidgetCarousel>
+```
+
+A horizontal scroll carousel that holds a row of AI action-widget cards and
+provides floating Previous/Next chevron buttons to navigate the view.
+
+## When to use
+
+- Displaying three or more AI-generated action cards in a constrained horizontal
+  space (e.g. a dashboard widget row) where all cards cannot be visible at once.
+- Any context where a horizontal scroll rail with progressive disclosure (one
+  click = one card step) is the intended interaction.
+
+## When not to use
+
+- Full-page media galleries or image sliders — use a dedicated media carousel.
+- Fewer than two cards that all fit in the available width — a plain flex row
+  without navigation buttons is simpler.
+
+## Parts
+
+| Part          | Description                                                                                                                                                                                 |
+| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `track`       | Horizontally scrollable flex row. Pass cards as direct children.                                                                                                                            |
+| `prev-button` | Circular 48 × 48 px `<button>` overlaid at the leading edge. Retreats the track by one card (288 px) + one gap (16 px). Disabled and invisible (`aria-disabled`, `opacity-0`) at the start. |
+| `next-button` | Circular 48 × 48 px `<button>` overlaid at the trailing edge. Advances the track by one card (288 px) + one gap (16 px). Disabled and invisible at the end.                                 |
+
+## Usage
+
+```tsx
+import { CardWidgetCarousel, CardWidget } from '@acronis-platform/ui-react';
+
+<CardWidgetCarousel nextLabel="Next" prevLabel="Previous">
+  <CardWidget
+    header="Phishing attacks"
+    status="danger"
+    icon={<WarningIcon size={16} />}
+    title="Phishing attack detected"
+    metric="$15K"
+    caption="Projected new MRR"
+    footer={<Button variant="ghost">Review</Button>}
+  />
+  <CardWidget header="Loading…" status="info" skeleton />
+</CardWidgetCarousel>;
+```
+
+## Companion: CardWidget
+
+`CardWidget` is the companion card exported from the same barrel. It composes
+`Card` + `CardHeader` + `CardContent` + `CardFooter`, fixing its width at
+288 px, and adds:
+
+- **Status-colored icon box** — driven by the `status` prop (`'danger'`,
+  `'warning'`, `'info'`), using `--ui-background-status-*` and
+  `--ui-glyph-on-status-*` tokens.
+- **Skeleton loading** — pass `skeleton` to show animated placeholder lines
+  instead of body content. Bars inherit the status color.
+- **Flexible footer** — pass any `ReactNode` via `footer` (action buttons,
+  CTAs). Omit to hide the footer entirely.
+
+### CardWidget props
+
+| Prop           | Type                              | Default     | Description                                         |
+| -------------- | --------------------------------- | ----------- | --------------------------------------------------- |
+| `status`       | `'danger' \| 'warning' \| 'info'` | `'info'`    | Semantic status — drives the icon-box colors.       |
+| `icon`         | `ReactNode`                       | —           | 16 px icon inside the status-colored box.           |
+| `header`       | `string`                          | —           | Card header title.                                  |
+| `title`        | `string`                          | —           | Insight title (14 px, semibold).                    |
+| `description`  | `string`                          | —           | Supporting text (12 px).                            |
+| `metric`       | `ReactNode`                       | —           | Primary value (24 px, semibold).                    |
+| `caption`      | `string`                          | —           | Small caption beside the metric (12 px).            |
+| `skeleton`     | `boolean`                         | `false`     | Animated placeholder lines instead of body content. |
+| `loadingLabel` | `string`                          | `'Loading'` | `aria-label` for the skeleton loading indicator.    |
+| `footer`       | `ReactNode`                       | —           | Action buttons in the card footer.                  |
+
+## Child card sizing
+
+Each child card should be **288 px wide** (`w-72`) and `shrink-0` so the
+scroll step (304 px) aligns to exactly one card width. `CardWidget` enforces
+this by default.
+
+## RTL
+
+Both chevron icons flip (`rtl:rotate-180`) and the scroll direction reverses
+automatically when an ancestor has `dir="rtl"`.
+
+## Localization
+
+The `nextLabel` (default `'Next'`) and `prevLabel` (default `'Previous'`) props
+are `aria-label` values on the navigation buttons. Override them when deploying
+in a non-English context.
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `nextLabel` | `string` | `'Next'` | no | Accessible label for the Next chevron button (`aria-label`). Localize when deploying in a non-English context. |
+| `prevLabel` | `string` | `'Previous'` | no | Accessible label for the Previous chevron button (`aria-label`). Localize when deploying in a non-English context. |
+
+## Content slots
+
+| Slot | Description |
+|------|-------------|
+| `children` | The individual action cards — typically `CardWidget` instances (the companion component exported from the same barrel) or any card-shaped `ReactNode`. Each card should have a fixed width of 288 px so the carousel's scroll step (304 px = 288 + 16 gap) aligns correctly. `CardWidget` provides a status-colored icon box, optional skeleton loading state, and a flexible footer slot; its props are `status` (`'danger' | 'warning' | 'info'`), `icon`, `header`, `title`, `description`, `metric`, `caption`, `skeleton`, `loadingLabel`, and `footer`. |
+
+## Behavior
+
+### Scroll — Next button
+
+**Given** a `CardWidgetCarousel` whose track overflows (more cards than visible area)
+**When** the user activates the Next button (pointer click or Enter/Space via keyboard focus)
+**Then** the scroll track advances by one card width + gap (304 px) towards the trailing edge
+with a smooth scroll animation.
+
+**Given** the carousel is in an RTL context (`dir="rtl"` on an ancestor)
+**When** the user activates the Next button
+**Then** the track scrolls 304 px towards the logical start (i.e. visually to the left in RTL)
+so that the next card slides into view from the start edge.
+
+### Scroll — Previous button
+
+**Given** a `CardWidgetCarousel` whose track has been scrolled past the start
+**When** the user activates the Previous button (pointer click or Enter/Space via keyboard focus)
+**Then** the scroll track moves back by one card width + gap (304 px) towards the leading edge
+with a smooth scroll animation.
+
+**Given** the carousel is in an RTL context (`dir="rtl"` on an ancestor)
+**When** the user activates the Previous button
+**Then** the track scrolls 304 px towards the logical end (i.e. visually to the right in RTL)
+so that the previous card slides into view from the end edge.
+
+### Button visibility
+
+Both navigation buttons are always present in the DOM to preserve keyboard
+focus. At scroll boundaries they are `aria-disabled="true"` and visually
+hidden (`opacity-0`, `pointer-events-none`).
+
+**Given** the track is at the start (scroll position = 0)
+**When** the carousel renders
+**Then** the Next button is enabled; the Previous button is disabled and invisible.
+
+**Given** the track is scrolled partway through
+**When** the carousel renders
+**Then** both the Previous and Next buttons are enabled and visible.
+
+**Given** the track is scrolled to the end (scroll position + client width >= scroll width)
+**When** the carousel renders
+**Then** the Previous button is enabled; the Next button is disabled and invisible.
+
+### Dynamic children
+
+**Given** a `CardWidgetCarousel` whose children change at runtime (e.g. async data load)
+**When** children are added or removed from the track
+**Then** the button disabled/visible state updates automatically via a
+`MutationObserver` watching the track's `childList`.
+
+### Overflow behavior
+
+**Given** a `CardWidgetCarousel` with fewer or equal cards than the visible area can show
+**When** a navigation button is clicked
+**Then** `scrollBy` is still called; the browser clamps the position at the scroll boundary
+with no visual jank.
+
+### Pointer interaction behind the overlay
+
+**Given** a card is partially obscured by a 180 px overlay panel (start or end)
+**When** the user clicks on the visible portion of the card
+**Then** the click reaches the card (the overlay panel has `pointer-events: none`;
+only the navigation buttons have `pointer-events: auto`).
+
+## Accessibility
+
+## ARIA
+
+- The Previous `<button>` carries an `aria-label` sourced from the `prevLabel`
+  prop (default `'Previous'`). Localize this string for non-English deployments.
+- The Next `<button>` carries an `aria-label` sourced from the `nextLabel` prop
+  (default `'Next'`). Localize this string for non-English deployments.
+- At scroll boundaries a button is marked `aria-disabled="true"` (not removed
+  from the DOM), so assistive technology still discovers it and announces its
+  disabled state.
+- The scroll track (`div`) has no ARIA role. Screen readers traverse the child
+  cards directly since they are standard HTML elements.
+
+## Keyboard
+
+| Key           | Target                      | Effect                                                        |
+| ------------- | --------------------------- | ------------------------------------------------------------- |
+| Tab           | Previous / Next button      | Moves keyboard focus onto either button (both always in DOM). |
+| Enter / Space | Navigation button (focused) | Advances or retreats the scroll track by one step.            |
+| Enter / Space | Disabled button (focused)   | No-op — the click handler is guarded.                         |
+
+Both buttons are native `<button>` elements, so Enter and Space activation follow
+the UA's default behavior without custom `keydown` handling. Disabled buttons use
+`aria-disabled` (not `disabled`) to remain in the tab order and preserve focus.
+
+## Focus management
+
+- Both navigation buttons are always present in the DOM. When a button becomes
+  disabled at a scroll boundary, focus is not lost — the button stays focusable
+  via `aria-disabled` (rather than being unmounted).
+- Both navigation buttons have a visible focus ring using `focus-visible:ring-2`
+  bound to `--ui-focus-primary`. The ring is suppressed for pointer interactions
+  (`:focus-visible` only).
+
+## Screen reader
+
+- Screen readers can navigate to and activate each navigation button by label.
+  A disabled button is announced as "Previous, button, disabled" (or "Next").
+- The scrollable track (`overflow-x: auto`, hidden scrollbar) does not expose
+  a scroll role; assistive technology reads through the children sequentially.
+  For very long lists of cards, consider complementing the carousel with a
+  "See all" link so AT users can reach all items without repeated button presses.
+
+## Contrast
+
+- Both navigation buttons use `--ui-background-surface-primary` (white / dark
+  surface). The chevron icon inherits the default text color from the token
+  pipeline, which meets WCAG AA contrast against that surface.
+
+## CardWidget — skeleton loading
+
+- When `skeleton` is true, the loading placeholder has `role="status"` with an
+  `aria-label` sourced from the `loadingLabel` prop (default `'Loading'`), so
+  assistive technology announces the loading state. Localize `loadingLabel` for
+  non-English deployments. The animated pulse bars inside are decorative.

package/dist/llms/category-bar.md

@@ -44,8 +44,8 @@ Segment colors come from the `palette` prop — a dataviz palette resolving to t
 
 ## When not to use
 
-- Ranked single values that each need their own labelled row — use `Meter`
-  stacked into a bar list.
+- Ranked single values that each need their own labelled row — use
+  `BarChart` with `orientation="horizontal"`.
 - Precise value comparison across many categories — a bar chart reads better.
 - A flow across two or more levels — use `SankeyChart`.
 - More than ~6 segments, or very uneven values — thin slivers become unreadable;

package/dist/llms/chart-state.md

@@ -72,8 +72,10 @@ function Sales({ status, data, config, refetch }) {
 ```
 
 The three states share one compact layout: a leading glyph (spinner / inbox /
-warning) over a centered label. Pass `message` to override a state's default
-label, and `action` to add a retry affordance to the error state.
+warning) over a centered label. Pass `description` to override a state's default
+label, and `action` to add a retry affordance to the error state. Long unbroken
+error descriptions (CTI paths, API URLs) wrap at word boundaries and scroll
+vertically when they exceed the slot height.
 
 ## Props
 
@@ -112,8 +114,19 @@ label, and `action` to add a retry affordance to the error state.
 ### Layout
 
 - **Given** any state, **when** placed in a sized slot (the same box a chart
-  would occupy), **then** the block fills it (`size-full`) and centers its
-  content, with a `min-h-32` floor so it stays legible in an unsized parent.
+  would occupy), **then** the block fills it (`size-full`) with a `min-h-32`
+  floor so it stays legible in an unsized parent.
+- **Given** `state="loading"` or `state="empty"`, **when** rendered, **then**
+  the content is vertically centered in the slot (`justify-center`).
+- **Given** `state="error"`, **when** the description is short enough to fit,
+  **then** the content is vertically centered via auto margins (`my-auto`).
+- **Given** `state="error"` with a long unbroken `description` (e.g. CTI error
+  paths, API URLs), **when** the text overflows the slot height, **then** the
+  auto margins collapse and the icon stays anchored at the top, with vertical
+  scroll (`overflow-y: auto`) so the full diagnostic text is accessible. Long
+  unbroken strings wrap at word boundaries (`overflow-wrap: break-word`),
+  breaking mid-word only when a single token cannot fit on one line.
+  `overflow-x: hidden` prevents any horizontal scrollbar.
 
 ### Per-type empty states
 

package/dist/llms/line-chart.md

@@ -108,12 +108,13 @@ across brands until the real data-viz palette lands.
 | `yAxisLabel` | `string` | — | no | Title rendered beside the vertical (Y) axis (rotated). |
 | `yUnit` | `string` | — | no | Unit suffix appended to Y-axis tick values (recharts `unit`); the X axis is categorical. |
 | `strokeWidth` | `number` | `2` | no | Stroke width of each line. |
-| `showDots` | `boolean` | `true` | no | Render a dot at each data point. |
+| `showDots` | `boolean` | `false` | no | Render a dot at each data point. |
 | `dotSize` | `number` | `3` | no | Radius of each point's dot, in px. Its hover dot is 2px larger. |
 | `showActiveDot` | `boolean` | — | no | Enlarge the hovered point's dot. Defaults to following `showDots`, so set it explicitly for a hover-only line (dots off, active dot on) or a static-only line (dots on, active dot off). |
 | `lineSettings` | `Record<string, { color?: string; strokeWidth?: number; dashed?: boolean; curveType?: CurveType; showDots?: boolean; dotSize?: number; showLabel?: boolean; labelPosition?: LabelPosition }>` | — | no | Per-series style override keyed by `dataKeys` entry — anything unset falls back to the chart-wide prop, so an entry states only what differs. A series listed in `comparisonKeys` keeps its dashed, dimmed, dot-less treatment: `color` / `strokeWidth` / `curveType` still apply to it, but `showDots` / `dotSize` do not. |
 | `referenceLine` | `Line | Line[]  where Line = { value?: number; average?: boolean | string; label?: string; labelPosition?: 'top' | 'insideTopLeft' | 'insideTopRight' | 'insideBottomLeft' | 'insideBottomRight' }` | — | no | One or more dashed reference/average lines on the value axis. Pass a single object or an array. Per line, a fixed `value` wins; otherwise the mean of one series (`average: '<key>'`) or of every plotted series (`average: true`, which includes any `comparisonKeys` overlay). An optional `label` captions each, at the rule's top right unless `labelPosition` moves it away from a series it would sit on. The same config shape as `BarChart` / `AreaChart`. |
 | `connectNulls` | `boolean` | `false` | no | Bridge `null` gaps in the data instead of breaking the line. |
+| `projectionStart` | `string | number` | — | no | The category value (matching an `xKey` entry) at which the projection zone starts. Ticks from this point onward render in the disabled text color. The actual series are clipped to the left of the boundary; a dashed, dot-less projection continuation renders on the right. Comparison series (`comparisonKeys`) are excluded from the projection split and render unclipped across the full width. |
 | `showGrid` | `boolean` | `true` | no | Render the CartesianGrid. |
 | `showTooltip` | `boolean` | `true` | no | Render the hover tooltip. |
 | `showLegend` | `boolean` | `true` | no | Render the legend. |

package/dist/llms/metric.md

@@ -57,7 +57,7 @@ GROSS MARGIN                 [Last 30 days]   ← label + caption
 ## Composition
 
 Metric is a Card. Put the trend in the `trend` slot (a `TrendIndicator`), a
-timeframe in `caption` (a `Tag`), and drop a chart / `Meter` breakdown /
+timeframe in `caption` (a `Tag`), and drop a chart / labelled-bar breakdown /
 `Separator` / insight line into `children`:
 
 ```tsx
@@ -76,11 +76,16 @@ timeframe in `caption` (a `Tag`), and drop a chart / `Meter` breakdown /
     />
   }
 >
-  <Meter
-    label="Healthy"
-    value={46}
+  <BarChart
+    orientation="horizontal"
+    items={[
+      {
+        label: 'Healthy',
+        value: 46,
+        color: 'var(--ui-background-status-strong-success)',
+      },
+    ]}
     max={54}
-    color="var(--ui-background-status-strong-success)"
   />
   <Separator className="my-3" />
   <p>+3 customers predicted at-risk within 30 days.</p>