@sableui/react 0.2.0 → 0.3.0

package/llms/components/entity.md

@@ -2,7 +2,7 @@
 
 **Status:** stable
 
-A list-row record: leading visual + title/subtitle column + trailing action, with truncating text. Presentational by default (no hover); `interactive` rows gain the hover highlight, focus ring, and keyboard activation. Compact/comfortable density.
+A list-row record: leading visual + title/subtitle column + trailing action, with truncating text. Presentational by default (no hover); `interactive` rows gain the hover highlight, focus ring, and keyboard activation, and `selected` marks the current one. Compact/comfortable density.
 
 **Keywords:** entity, identity, object, avatar row
 
@@ -28,6 +28,7 @@ Use Entity to show a compact identity block for a person, organization, file, pr
 | action | ReactNode | — | Trailing slot — typically a ghost icon Button or a StatusDot. |
 | interactive | boolean | false | Make the whole row a target: the leading visual and text become a native <button> whose hit area stretches over the row (focus ring, Enter/Space). The action stays outside it. Requires onSelect. |
 | onSelect | () => void | — | Activation handler for an interactive row (fired on click and Enter/Space). Required when interactive. |
+| selected | boolean | false | Interactive rows only: the current row of a selectable list (the record open in a list–detail view). Sets aria-current="true" on the row's button and paints the selected fill, a step off the surface the row sits on, which holds on hover. |
 | density | "compact" \| "comfortable" | "compact" | Row padding: compact (12px × 10px, the default) or comfortable (16px × 12px), on the spacing scale. The insets read --entity-px / --entity-py first, which CardList sets from the card's own padding so rows in a card line up with its header. |
 
 ## Variants
@@ -36,13 +37,14 @@ Use Entity to show a compact identity block for a person, organization, file, pr
 
 ## Tokens used
 
-`muted`, `foreground`, `muted-foreground`, `ring`
+`accent`, `accent-foreground`, `foreground`, `muted-foreground`, `ring`
 
 ## Accessibility
 
 - Default rows are presentational layout; semantics come from the content you place in title/subtitle/action.
 - interactive rows render a real <button> around the leading visual and text, with its ::after stretched over the whole row — native focus, a focus-visible ring, and Enter/Space. The action slot sits outside that button and above the overlay, so a Button there stays valid HTML and keeps its own clicks.
 - Give any interactive action an accessible label (e.g. aria-label on a ghost icon Button).
+- A selected row announces aria-current="true" on its button, so the current record is spoken, not only shown by its fill.
 
 ## Related
 

package/llms/components/line-chart.md

@@ -0,0 +1,101 @@
+# LineChart
+
+**Status:** beta
+
+Lines over a sequence — for comparing how measures move. Smooth, linear or step curves, optional dots (coloured by series or by category) and value labels. Lines draw on as the chart scrolls into view.
+
+**Keywords:** chart, line, trend, time series, graph, compare, analytics, dashboard
+
+## Usage
+
+Use LineChart to compare how two or more measures change over the same sequence, or to show one trend precisely (with dots and labels). Unlike AreaChart, its value axis is fitted to the data rather than forced to zero, so small movements stay visible — say so if the axis is shown.
+
+### Best practices
+
+- Do: Turn on dots and labels for six or fewer points, when the exact values are the story.
+- Do: Use curve="step" for values that hold until they change — prices, plan tiers, headcount.
+- Don't: Plot unordered categories (channels, products) as a line — the line implies a path between them; use BarChart.
+- Don't: Use it for data-heavy views — streaming or real-time data, thousands of points, zoom and brushing, trading charts. Those belong on a charting library (Recharts, visx, ECharts); Sable's charts are for dashboards, landing pages and decks.
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| data | Record<string, unknown>[] | — | The rows, in order along the category axis. |
+| index | string | — | The datum field naming each row's category (a month, a day, a channel). |
+| series | { key: string; label: string; tone?: ChartTone; color?: string; icon?: string }[] | — | The measures to plot: the datum field, its name in the legend/tooltip/table, and its colour (a tone by role, or any CSS colour). Omitted, series take the chart palette in order: --chart-1 … --chart-8, validated for colour-blind separation in light and dark; a theme may override the set. |
+| label | string | — | What the chart shows. Its accessible name and the caption of the data table assistive tech reads. |
+| className | string | "h-60" | Sizes the chart (plot + legend). Set a height: `h-72`, `aspect-video h-auto`. |
+| valueFormatter | (value: number) => string | — | Format values everywhere (axis, labels, tooltip, table) — units like "$12,480". Default: compact on the axis, full elsewhere. |
+| indexFormatter | (value: string) => string | — | Shorten category labels on the axis ("January" → "Jan"); the tooltip keeps the full value. |
+| locale | string | runtime locale | BCP 47 locale for default number and date formatting. |
+| tooltip | boolean \| { indicator?: "dot" \| "line" \| "dashed" \| "none"; hideLabel?: boolean; labelFormatter?: (label, datum) => ReactNode; showTotal?: boolean } | true | Show a tooltip on hover and keyboard focus, or configure it: the row marker, hiding the heading, rewriting it, adding a Total row. |
+| legend | boolean | true when there is more than one series | Show the legend under the chart. |
+| grid | boolean | true (false for horizontal bars) | Hairline gridlines along the value axis. |
+| xAxis | boolean | true for columns; false for horizontal bars | The horizontal axis. |
+| yAxis | boolean | false for columns; true for horizontal bars | The vertical axis. |
+| animate | boolean | true | Play the arrival once the chart scrolls into view. Reduced motion shows the finished chart. |
+| activeIndex | number \| null | — | The highlighted row (controlled); `null` for none. |
+| defaultActiveIndex | number \| null | — | The row highlighted at first — a tooltip already open before anyone hovers. |
+| onActiveIndexChange | (index: number \| null) => void | — | Called as the pointer or keyboard moves between rows. |
+| curve | "smooth" \| "linear" \| "step" | "smooth" | How the line runs between points. `smooth` is monotone: it never overshoots a value the data does not contain. |
+| dots | boolean | false | Mark every data point with a dot. |
+| colorBy | "series" \| "index" | "series" | Colour the dots by series, or each by its category. |
+| labels | boolean | false | Print each point's value above it. |
+
+## Tokens used
+
+`tone-edition`, `tone-collectible`, `tone-standard`, `tone-info`, `tone-warning`, `primary`, `muted-foreground`, `border`, `popover`, `popover-foreground`, `foreground`, `background`
+
+## Motion
+
+- **arrival** · Line · _custom (outside the recipe layer)_ — Once on screen each line draws on from the first point (stroke-dashoffset), series staggered, then the dots and labels fade in. On the motion tokens; reduced motion shows the finished chart.
+- **response** · Cursor + tooltip · _no motion_ — Hover and focus move the cursor and tooltip instantly — a lagging cursor reads as a slow chart.
+- **transition** · Line + dots · _custom (outside the recipe layer)_ — Geometry eases from the old shape to the new one through a CSS `d` transition on the motion tokens (no recipe animates path geometry); browsers without `d` transitions update in place.
+- **activity** · LineChart · _no motion_ — A chart has no indeterminate state; show a Skeleton while the data loads.
+
+## Accessibility
+
+- The drawing is aria-hidden; the same numbers are in a visually hidden data table (captioned by `label`) that the chart is aria-describedby, so assistive tech reads values, not shapes.
+- With a tooltip, the chart is one tab stop (role=group, aria-roledescription="chart"): arrow keys, Home and End step through the data, Escape clears, and each step is announced in a polite live region.
+- Colour is never the only key: series are named in the legend, tooltip and table.
+
+## Related
+
+- Components: AreaChart, BarChart, Sparkline, Card
+
+## Examples
+
+### Compare two series
+
+```tsx
+import { LineChart } from "@sableui/react"
+
+<LineChart
+	label="Desktop and mobile visitors"
+	data={visitors}
+	index="month"
+	series={[
+		{ key: "desktop", label: "Desktop", tone: "primary" },
+		{ key: "mobile", label: "Mobile", tone: "info" },
+	]}
+	indexFormatter={(m) => m.slice(0, 3)}
+/>
+```
+
+### Dots and labels
+
+```tsx
+import { LineChart } from "@sableui/react"
+
+<LineChart
+	label="Desktop visitors"
+	data={visitors}
+	index="month"
+	series={[{ key: "desktop", label: "Desktop" }]}
+	curve="linear"
+	dots
+	labels
+	grid={false}
+/>
+```

package/llms/components/menu.md

@@ -65,7 +65,7 @@ Use Menu for a compact list of actions opened from a visible trigger.
 
 ## Related
 
-- Components: ContextMenu, DotsMenu
+- Components: ContextMenu, OverflowMenu
 
 ## Examples
 

package/llms/components/{dots-menu.md → overflow-menu.md}

@@ -1,20 +1,20 @@
-# DotsMenu
+# OverflowMenu
 
 **Status:** stable
 
 An overflow ellipsis icon button that opens a Menu. Composes our Menu + Button + Icon — pass MenuItems as children and it wires the ghost icon trigger, accessible label, and portal-rendered content. All keyboard, focus, and dismissal behavior comes through Menu.
 
-**Keywords:** dots menu, more actions, overflow, kebab
+**Keywords:** dots menu, more actions, ellipsis, kebab
 
 ## Usage
 
-Use DotsMenu for compact overflow actions when the primary action is already visible elsewhere.
+Use OverflowMenu for compact overflow actions when the primary action is already visible elsewhere.
 
 ### Best practices
 
 - Do: Use it for secondary commands that belong to a row, card, or toolbar item.
 - Do: Keep labels explicit so the icon-only trigger does not obscure the command meaning.
-- Don't: Do not hide the most important or most frequent action inside DotsMenu.
+- Don't: Do not hide the most important or most frequent action inside OverflowMenu.
 - Don't: Do not use it as the only affordance on a touch surface. It is revealed on hover in most layouts, and hover does not exist on touch — pair it with a visible action or make it always-visible there.
 
 ## Props
@@ -24,7 +24,7 @@ Use DotsMenu for compact overflow actions when the primary action is already vis
 | children | ReactNode | — | The menu rows — MenuItem / MenuSeparator / MenuGroup, etc. Rendered inside MenuContent. |
 | align | 'start' \| 'center' \| 'end' | end | Alignment of the popup along its side. Overflow menus typically right-align under the trigger; 'start' anchors the popup's left edge to the trigger instead. |
 | label | string | More actions | Accessible label (aria-label) for the icon-only trigger button. |
-| icon | string | ellipsis | Semantic icon name rendered in the trigger. |
+| icon | string | ellipsis | Semantic icon name rendered in the trigger, always at the solid weight. |
 | size | 'icon' \| 'icon-sm' \| 'icon-xs' | icon | The trigger's rung on the icon-button ladder. 'icon' for a card or page header; 'icon-sm' or 'icon-xs' in a list row or dense toolbar, so the trigger does not set the row height. |
 
 ## Variants
@@ -50,15 +50,15 @@ Use DotsMenu for compact overflow actions when the primary action is already vis
 ### Basic
 
 ```tsx
-import { DotsMenu, MenuItem, MenuSeparator } from "@sableui/react"
+import { MenuItem, MenuSeparator, OverflowMenu } from "@sableui/react"
 
-<DotsMenu label="Post actions"><MenuItem>Edit</MenuItem><MenuItem>Share</MenuItem><MenuSeparator /><MenuItem variant="destructive">Delete</MenuItem></DotsMenu>
+<OverflowMenu label="Post actions"><MenuItem>Edit</MenuItem><MenuItem>Share</MenuItem><MenuSeparator /><MenuItem variant="destructive">Delete</MenuItem></OverflowMenu>
 ```
 
 ### With leading icons
 
 ```tsx
-import { DotsMenu, Icon, MenuItem, MenuSeparator } from "@sableui/react"
+import { Icon, MenuItem, MenuSeparator, OverflowMenu } from "@sableui/react"
 
-<DotsMenu><MenuItem><Icon name="check" className="text-sm" />Mark as read</MenuItem><MenuSeparator /><MenuItem variant="destructive"><Icon name="xmark" className="text-sm" />Delete</MenuItem></DotsMenu>
+<OverflowMenu><MenuItem><Icon name="check" className="text-sm" />Mark as read</MenuItem><MenuSeparator /><MenuItem variant="destructive"><Icon name="xmark" className="text-sm" />Delete</MenuItem></OverflowMenu>
 ```

package/llms/components/pie-chart.md

@@ -0,0 +1,103 @@
+# PieChart
+
+**Status:** beta
+
+Parts of a whole as slices: a pie or donut, concentric rings for several measures, a total in the hole, slice labels inside or out, and an active slice that pulls outward. Slices sweep in clockwise as the chart scrolls into view.
+
+**Keywords:** chart, pie, donut, doughnut, share, proportion, breakdown, parts, whole
+
+## Usage
+
+Use PieChart for a share of one total across two to six categories — traffic sources, a budget split, survey answers. A donut leaves room for the total in the middle (`centerLabel`). With more categories, or to compare values precisely, use BarChart; for a breakdown inside a stat card, SegmentedBar is lighter.
+
+### Best practices
+
+- Do: Put the total, or the headline slice, in a donut's centerLabel.
+- Do: Configure slice names, tones and icons with categories, keyed by each slice's value in the data.
+- Don't: Use more than six slices — merge the tail into "Other" or use BarChart.
+- Don't: Use it for data-heavy views — streaming or real-time data, thousands of points, zoom and brushing, trading charts. Those belong on a charting library (Recharts, visx, ECharts); Sable's charts are for dashboards, landing pages and decks.
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| data | Record<string, unknown>[] | — | One row per slice. |
+| index | string | — | The datum field naming each slice. |
+| valueKey | string \| string[] | — | The datum field holding each slice's amount — or several fields, drawn as concentric rings, outer first. |
+| label | string | — | What the chart shows. Its accessible name and the caption of the data table assistive tech reads. |
+| categories | Record<string, { label?: string; tone?: ChartTone; color?: string; icon?: string }> | — | Labels, tones and icons per slice, keyed by the slice's name. Unlisted slices take the tones in order. |
+| className | string | "h-64" | Sizes the chart. Set a height. |
+| donut | boolean \| number | false | Cut out the middle: `true` for a ring at 60% of the radius, or a ratio (0–0.9). |
+| centerLabel | { value: string; label?: string } | — | A value and caption in the hole of a donut. |
+| separator | boolean | true | A hairline in the surface colour between slices. |
+| labels | "none" \| "outside" \| "inside" | "none" | Label each slice outside the pie or inside it. |
+| labelContent | "value" \| "percent" \| "name" | "value" | What a slice label says. |
+| legend | boolean | true unless slices are labelled | Show the legend. |
+| tooltip | boolean \| { indicator?: "dot" \| "line" \| "dashed" \| "none"; hideLabel?: boolean; labelFormatter?: (label, datum) => ReactNode; showTotal?: boolean } | true | Show a tooltip on hover and keyboard focus, or configure it: the row marker, hiding the heading, rewriting it, adding a Total row. |
+| valueFormatter | (value: number) => string | — | Format values everywhere (axis, labels, tooltip, table) — units like "$12,480". Default: compact on the axis, full elsewhere. |
+| locale | string | runtime locale | BCP 47 locale for default number and date formatting. |
+| animate | boolean | true | Sweep the slices in clockwise when the chart scrolls into view. |
+| activeIndex | number \| null | — | The highlighted row (controlled); `null` for none. |
+| defaultActiveIndex | number \| null | — | The row highlighted at first — a tooltip already open before anyone hovers. |
+| onActiveIndexChange | (index: number \| null) => void | — | Called as the pointer or keyboard moves between rows. |
+
+## Tokens used
+
+`tone-edition`, `tone-collectible`, `tone-standard`, `tone-info`, `tone-warning`, `primary`, `muted-foreground`, `border`, `popover`, `popover-foreground`, `foreground`, `background`
+
+## Motion
+
+- **arrival** · Slices · _custom (outside the recipe layer)_ — Once on screen the slices are revealed by a mask that sweeps clockwise from 12 o'clock — the whole is read as it fills. On the motion tokens; reduced motion shows the finished chart.
+- **response** · Active slice · _no motion_ — The hovered slice pulls outward and the rest dim at once; the geometry change itself eases (see transition).
+- **transition** · Slices · _custom (outside the recipe layer)_ — Geometry eases from the old shape to the new one through a CSS `d` transition on the motion tokens (no recipe animates path geometry); browsers without `d` transitions update in place.
+- **activity** · PieChart · _no motion_ — A chart has no indeterminate state; show a Skeleton while the data loads.
+
+## Accessibility
+
+- The drawing is aria-hidden; the same numbers are in a visually hidden data table (captioned by `label`) that the chart is aria-describedby, so assistive tech reads values, not shapes.
+- With a tooltip, the chart is one tab stop (role=group, aria-roledescription="chart"): arrow keys, Home and End step through the data, Escape clears, and each step is announced in a polite live region.
+- Colour is never the only key: series are named in the legend, tooltip and table.
+
+## Related
+
+- Components: SegmentedBar, RadialChart, BarChart, Card
+
+## Examples
+
+### Donut with a total
+
+```tsx
+import { PieChart } from "@sableui/react"
+
+const sources = [
+	{ source: "Search", visitors: 275 },
+	{ source: "Direct", visitors: 200 },
+	{ source: "Social", visitors: 187 },
+	{ source: "Email", visitors: 90 },
+]
+
+<PieChart
+	label="Visitors by source"
+	data={sources}
+	index="source"
+	valueKey="visitors"
+	donut
+	centerLabel={{ value: "752", label: "Visitors" }}
+/>
+```
+
+### Labelled slices
+
+```tsx
+import { PieChart } from "@sableui/react"
+
+<PieChart
+	label="Share of visitors by source"
+	data={sources}
+	index="source"
+	valueKey="visitors"
+	labels="outside"
+	labelContent="percent"
+	categories={{ Search: { tone: "primary" }, Email: { tone: "neutral" } }}
+/>
+```

package/llms/components/radar-chart.md

@@ -0,0 +1,106 @@
+# RadarChart
+
+**Status:** beta
+
+Several measures compared around a centre: one polygon per series over a polygon or circular web, filled or outline only, with optional dots, a radius scale and a tinted web. Polygons grow from the centre as the chart scrolls into view.
+
+**Keywords:** chart, radar, spider, web, profile, skills, comparison, polar
+
+## Usage
+
+Use RadarChart to compare the shape of a profile across five to eight dimensions — skills, product scores, a cycle of months — for one to three series. The shape is the message; for exact values or more than three series, BarChart is easier to read.
+
+### Best practices
+
+- Do: Keep every spoke on the same scale and direction (more is better on all of them).
+- Do: Use filled={false} when two polygons overlap heavily, so both outlines stay visible.
+- Don't: Use fewer than five spokes — three or four make a triangle or square that says little; use BarChart.
+- Don't: Use it for data-heavy views — streaming or real-time data, thousands of points, zoom and brushing, trading charts. Those belong on a charting library (Recharts, visx, ECharts); Sable's charts are for dashboards, landing pages and decks.
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| data | Record<string, unknown>[] | — | One row per spoke. |
+| index | string | — | The datum field naming each spoke. |
+| series | { key: string; label: string; tone?: ChartTone; color?: string; icon?: string }[] | — | The measures to plot: the datum field, its name in the legend/tooltip/table, and its colour (a tone by role, or any CSS colour). Omitted, series take the chart palette in order: --chart-1 … --chart-8, validated for colour-blind separation in light and dark; a theme may override the set. |
+| label | string | — | What the chart shows. Its accessible name and the caption of the data table assistive tech reads. |
+| className | string | "h-72" | Sizes the chart. Set a height. |
+| grid | "polygon" \| "circle" \| "none" | "polygon" | The web behind the polygons. |
+| gridFill | boolean | false | Tint the web's outer area. |
+| filled | boolean | true | Fill each polygon; `false` draws outlines only. |
+| dots | boolean | false | Mark every vertex with a dot. |
+| radiusAxis | boolean | false | Print the ring values along the top spoke. |
+| legend | boolean | true when there is more than one series | Show the legend. |
+| tooltip | boolean \| { indicator?: "dot" \| "line" \| "dashed" \| "none"; hideLabel?: boolean; labelFormatter?: (label, datum) => ReactNode; showTotal?: boolean } | true | Show a tooltip on hover and keyboard focus, or configure it: the row marker, hiding the heading, rewriting it, adding a Total row. |
+| valueFormatter | (value: number) => string | — | Format values everywhere (axis, labels, tooltip, table) — units like "$12,480". Default: compact on the axis, full elsewhere. |
+| locale | string | runtime locale | BCP 47 locale for default number and date formatting. |
+| animate | boolean | true | Grow the polygons from the centre when the chart scrolls into view. |
+| activeIndex | number \| null | — | The highlighted row (controlled); `null` for none. |
+| defaultActiveIndex | number \| null | — | The row highlighted at first — a tooltip already open before anyone hovers. |
+| onActiveIndexChange | (index: number \| null) => void | — | Called as the pointer or keyboard moves between rows. |
+
+## Tokens used
+
+`tone-edition`, `tone-collectible`, `tone-standard`, `tone-info`, `tone-warning`, `primary`, `muted-foreground`, `border`, `popover`, `popover-foreground`, `foreground`, `background`
+
+## Motion
+
+- **arrival** · Polygon · _custom (outside the recipe layer)_ — Once on screen each polygon grows from the centre and fades in, series staggered, on the emphasized easing. On the motion tokens; reduced motion shows the finished chart.
+- **response** · Active spoke · _no motion_ — The hovered spoke's vertices and label highlight at once.
+- **transition** · Polygon · _custom (outside the recipe layer)_ — Geometry eases from the old shape to the new one through a CSS `d` transition on the motion tokens (no recipe animates path geometry); browsers without `d` transitions update in place.
+- **activity** · RadarChart · _no motion_ — A chart has no indeterminate state; show a Skeleton while the data loads.
+
+## Accessibility
+
+- The drawing is aria-hidden; the same numbers are in a visually hidden data table (captioned by `label`) that the chart is aria-describedby, so assistive tech reads values, not shapes.
+- With a tooltip, the chart is one tab stop (role=group, aria-roledescription="chart"): arrow keys, Home and End step through the data, Escape clears, and each step is announced in a polite live region.
+- Colour is never the only key: series are named in the legend, tooltip and table.
+
+## Related
+
+- Components: BarChart, LineChart, Card
+
+## Examples
+
+### Two profiles
+
+```tsx
+import { RadarChart } from "@sableui/react"
+
+const scores = [
+	{ skill: "Speed", a: 86, b: 65 },
+	{ skill: "Quality", a: 72, b: 90 },
+	{ skill: "Support", a: 64, b: 80 },
+	{ skill: "Price", a: 90, b: 55 },
+	{ skill: "Docs", a: 70, b: 85 },
+	{ skill: "Ecosystem", a: 60, b: 75 },
+]
+
+<RadarChart
+	label="Product scores compared"
+	data={scores}
+	index="skill"
+	series={[
+		{ key: "a", label: "Atlas" },
+		{ key: "b", label: "Beacon" },
+	]}
+/>
+```
+
+### Circular web, outlines only
+
+```tsx
+import { RadarChart } from "@sableui/react"
+
+<RadarChart
+	label="Atlas scores"
+	data={scores}
+	index="skill"
+	series={[{ key: "a", label: "Atlas" }]}
+	grid="circle"
+	gridFill
+	filled={false}
+	dots
+/>
+```

package/llms/components/radial-chart.md

@@ -0,0 +1,102 @@
+# RadialChart
+
+**Status:** beta
+
+Progress or share as rings: one ring per row against a muted track, a full circle or a gauge (`sweep`), one ring split between rows (`stacked`), ring labels and a value in the middle. Rings draw round as the chart scrolls into view.
+
+**Keywords:** chart, radial, ring, gauge, progress, goal, score, activity rings, donut
+
+## Usage
+
+Use RadialChart for progress toward goals (several rings), a single score or usage gauge (`sweep={180}` with `centerLabel`), or a split of one total along a gauge (`stacked`). For one reading in a form or settings row, Meter's ring shape is lighter.
+
+### Best practices
+
+- Do: Set max to the goal, so a full ring means "done".
+- Do: Pair a gauge with centerLabel stating the value in words or units.
+- Don't: Compare more than four rings — inner rings are shorter for the same value, which misleads; use BarChart.
+- Don't: Use it for data-heavy views — streaming or real-time data, thousands of points, zoom and brushing, trading charts. Those belong on a charting library (Recharts, visx, ECharts); Sable's charts are for dashboards, landing pages and decks.
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| data | Record<string, unknown>[] | — | One row per ring, outermost first. |
+| index | string | — | The datum field naming each ring. |
+| valueKey | string | — | The datum field holding each ring's amount. |
+| label | string | — | What the chart shows. Its accessible name and the caption of the data table assistive tech reads. |
+| categories | Record<string, { label?: string; tone?: ChartTone; color?: string; icon?: string }> | — | Labels, tones and icons per ring, keyed by the ring's name. |
+| className | string | "h-64" | Sizes the chart. Set a height. |
+| max | number | the largest value (stacked: the total; labelled: the largest value ÷ 0.75, leaving room for the labels) | The value a full ring stands for. |
+| sweep | number | 360 | How far round a full ring runs, in degrees: 360 for a circle, 180 for a gauge. |
+| stacked | boolean | false | Split ONE ring between the rows instead of a ring each. |
+| track | boolean | true | Draw each ring's full track behind it. |
+| labels | boolean | false | Name each ring at its start. |
+| centerLabel | { value: string; label?: string } | — | A value and caption in the middle. |
+| legend | boolean | true unless rings are labelled | Show the legend. |
+| tooltip | boolean \| { indicator?: "dot" \| "line" \| "dashed" \| "none"; hideLabel?: boolean; labelFormatter?: (label, datum) => ReactNode; showTotal?: boolean } | true | Show a tooltip on hover and keyboard focus, or configure it: the row marker, hiding the heading, rewriting it, adding a Total row. |
+| valueFormatter | (value: number) => string | — | Format values everywhere (axis, labels, tooltip, table) — units like "$12,480". Default: compact on the axis, full elsewhere. |
+| locale | string | runtime locale | BCP 47 locale for default number and date formatting. |
+| animate | boolean | true | Draw the rings round from their start when the chart scrolls into view. |
+| activeIndex | number \| null | — | The highlighted row (controlled); `null` for none. |
+| defaultActiveIndex | number \| null | — | The row highlighted at first — a tooltip already open before anyone hovers. |
+| onActiveIndexChange | (index: number \| null) => void | — | Called as the pointer or keyboard moves between rows. |
+
+## Tokens used
+
+`tone-edition`, `tone-collectible`, `tone-standard`, `tone-info`, `tone-warning`, `primary`, `muted-foreground`, `border`, `popover`, `popover-foreground`, `foreground`, `background`
+
+## Motion
+
+- **arrival** · Ring · _custom (outside the recipe layer)_ — Once on screen each ring draws round from its start (stroke-dashoffset on a round-capped arc), staggered outside in. On the motion tokens; reduced motion shows the finished chart.
+- **response** · Active ring · _no motion_ — The hovered ring stays full strength and the others dim at once.
+- **transition** · Ring · _custom (outside the recipe layer)_ — Geometry eases from the old shape to the new one through a CSS `d` transition on the motion tokens (no recipe animates path geometry); browsers without `d` transitions update in place.
+- **activity** · RadialChart · _no motion_ — A chart has no indeterminate state; show a Skeleton while the data loads.
+
+## Accessibility
+
+- The drawing is aria-hidden; the same numbers are in a visually hidden data table (captioned by `label`) that the chart is aria-describedby, so assistive tech reads values, not shapes.
+- With a tooltip, the chart is one tab stop (role=group, aria-roledescription="chart"): arrow keys, Home and End step through the data, Escape clears, and each step is announced in a polite live region.
+- Colour is never the only key: series are named in the legend, tooltip and table.
+
+## Related
+
+- Components: Meter, PieChart, Progress, Card
+
+## Examples
+
+### Goal rings
+
+```tsx
+import { RadialChart } from "@sableui/react"
+
+<RadialChart
+	label="Weekly goals"
+	data={[
+		{ goal: "Move", progress: 82 },
+		{ goal: "Exercise", progress: 64 },
+		{ goal: "Stand", progress: 91 },
+	]}
+	index="goal"
+	valueKey="progress"
+	max={100}
+	labels
+/>
+```
+
+### Gauge with a value
+
+```tsx
+import { RadialChart } from "@sableui/react"
+
+<RadialChart
+	label="Plan usage"
+	data={[{ plan: "Used", gb: 7.2 }]}
+	index="plan"
+	valueKey="gb"
+	max={10}
+	sweep={180}
+	centerLabel={{ value: "7.2 GB", label: "of 10 GB" }}
+	legend={false}
+/>
+```

package/llms/components/segmented-bar.md

@@ -0,0 +1,102 @@
+# SegmentedBar
+
+**Status:** stable
+
+One bar split into the parts of a whole — revenue by type, storage by kind, results by outcome. Segments size by their share of the total; the bar is one labelled image to assistive tech.
+
+**Keywords:** breakdown, stacked, segmented, proportion, split, distribution, category, bar, share
+
+## Usage
+
+Use SegmentedBar when a stat card or row needs to show how a total divides into a few categories. Pair it with a legend you compose (StatusDot + label + share), placed where the card has room. For one reading against a range (storage used, quota), use Meter; for task completion, use Progress.
+
+### Best practices
+
+- Do: Keep it to two to six segments and give the same category the same tone everywhere it appears.
+- Do: Show the legend's shares in text ("42%") — colour identifies a segment, but the number is what a reader compares.
+- Don't: Use it for a single value against a limit; that is Meter, which carries the meter role and its value.
+- Don't: Rely on tone order alone to tell segments apart; a legend row per segment, with its label, is required.
+
+### Anatomy
+
+| Part | Required | Description |
+| --- | --- | --- |
+| Track | yes | The rounded bar; segments fill it edge to edge with a hairline gap. |
+| Segment | yes | One category, sized by its share of the total and filled with its tone. |
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| segments | { label: string; value: number; tone?: SegmentedBarTone }[] | — | The categories, left to right. Values in any unit; zero or negative values are skipped. |
+| label | string | — | What the bar breaks down. Prefixes the accessible summary of every segment's share. |
+| size | "sm" \| "md" \| "lg" | "md" | Bar thickness — the same rails as Meter and Progress. |
+| locale | string | runtime locale | Locale for the spoken percentages. |
+
+## Variants
+
+- **size**: sm, md, lg
+- **tone**: edition, collectible, standard, info, primary, neutral, success, warning, destructive
+
+## Tokens used
+
+`tone-edition`, `tone-collectible`, `tone-standard`, `tone-info`, `primary`, `muted-foreground`, `success`, `tone-warning`, `destructive`
+
+## Motion
+
+- **arrival** · SegmentedBar · _no motion_ — A breakdown is a reading, present with the card that reports it; growing the segments in on load would act out a change that did not happen.
+- **response** · SegmentedBar · _no motion_ — It reports and accepts no input.
+- **transition** · Segment · _custom (outside the recipe layer)_ — Each segment's share and colour ease on the motion tokens when the data changes (no recipe animates flex-grow), so the reader sees which part grew.
+- **activity** · SegmentedBar · _no motion_ — No indeterminate state — an unknown breakdown is not drawn.
+
+## Accessibility
+
+- Rendered role=img with an aria-label built from `label` and each segment's share ("Revenue by type: Editions 42%, Collectibles 27%"), so the whole breakdown is read in one stop.
+- Colour alone does not identify a segment: always show a legend with each segment's label beside the bar.
+
+## Related
+
+- Components: Meter, Progress, StatusDot, Card
+- Patterns: DashboardPage
+
+## Examples
+
+### With a legend
+
+```tsx
+import { SegmentedBar, Stack, StatusDot } from "@sableui/react"
+
+const sales = [
+	{ label: "Editions", value: 42, tone: "edition" },
+	{ label: "Collectibles", value: 27, tone: "collectible" },
+	{ label: "Standard", value: 19, tone: "standard" },
+] as const
+
+<Stack gap={3}>
+	<SegmentedBar label="Revenue by type" segments={[...sales]} size="lg" />
+	<ul className="flex flex-col gap-1.5">
+		{sales.map((s) => (
+			<li key={s.label} className="flex items-center gap-2 text-body-sm">
+				<StatusDot tone={s.tone} />
+				<span className="flex-1 text-muted-foreground">{s.label}</span>
+				<span className="text-mono-caption">{s.value}%</span>
+			</li>
+		))}
+	</ul>
+</Stack>
+```
+
+### Test results — status tones
+
+```tsx
+import { SegmentedBar } from "@sableui/react"
+
+<SegmentedBar
+	label="Test results"
+	segments={[
+		{ label: "Passed", value: 412, tone: "success" },
+		{ label: "Flaky", value: 9, tone: "warning" },
+		{ label: "Failed", value: 3, tone: "destructive" },
+	]}
+/>
+```

package/llms/components/settings-menu.md

@@ -17,7 +17,7 @@ For a cluster of related settings that a reader checks often and changes occasio
 - Do: Use `MenuRadioGroup` + `MenuRadioItem` inside a row for single-choice settings, so the current option is checked rather than merely remembered.
 - Do: Reach for `variant="subtle"` when the trigger sits on a surface where a ghost control would float unanchored — inside a ChatComposer, for instance.
 - Don't: Do not use it for a single setting. One choice is a `Select`; the nesting only earns its cost when there are several related settings to summarise.
-- Don't: Do not put actions in it. Rows change state; a menu that mixes "Effort ›" with "Delete conversation" makes destructive commands look like preferences. That is `Menu` or `DotsMenu`.
+- Don't: Do not put actions in it. Rows change state; a menu that mixes "Effort ›" with "Delete conversation" makes destructive commands look like preferences. That is `Menu` or `OverflowMenu`.
 - Don't: Do not nest more than one level deep. Past that the reader loses the path back, and the thing you have is a settings dialog wearing a menu.
 - Don't: Do not override the upward, end-aligned default without reason. Its home is the bottom of a composer or toolbar, where a downward menu opens off-screen.
 
@@ -69,7 +69,7 @@ For a cluster of related settings that a reader checks often and changes occasio
 
 ## Related
 
-- Components: Menu, DotsMenu, Select, ChatComposer, Popover
+- Components: Menu, OverflowMenu, Select, ChatComposer, Popover
 - Patterns: ChatPanel
 
 ## Examples