@twoux/ui 0.0.0-stage → 0.1.1

package/agent/docs-md/chart-donut.md

@@ -0,0 +1,90 @@
+# Donut chart
+
+Two to five parts of one total at a single moment, with the total in the centre and every segment labelled with its count and share. Most of the time a bar chart is better.
+
+Kind: component · Group: Data visualisation · Status: built, import from @twoux/ui
+
+## When to use
+
+- When the question is how one total splits at one moment, and there are two to five parts: open roles by work pattern (On site, Hybrid, Remote (UK)).
+- When the total itself is worth showing, which the centre of the donut holds.
+
+## When not to use
+
+- For change over time. Use the Line chart card, or the Stacked area chart for parts over time.
+- For more than five parts. Use a horizontal Bar chart sorted by size.
+- When parts are close in size and the difference matters, such as 31% against 34%. Angles are hard to compare; use a Bar chart.
+- For one value against a goal, such as 18 of 25 roles filled. Use the Stat card with comparison.
+- For ordered stages such as Applied to Offer. Use the Funnel.
+
+## Structure
+
+1. Title and subtitle (the moment or period)
+2. Ring of segments starting at 12 o'clock, clockwise, with a 2px surface-colour gap between segments
+3. Centre: total value and a one or two word unit ("412 candidates")
+4. Segment labels: name, count, share
+5. Legend, required when any part is zero
+6. Details popover on hover or select
+
+## Guidelines
+
+- Order segments clockwise from 12 o'clock, largest first, unless the parts have their own order (Junior, Mid, Senior), in which case keep that order.
+- Colour segments with categorical colours in fixed order from colour 1. Never give each slice a colour chosen by meaning.
+- Label every segment with its count and share, so the chart reads without hovering.
+- A part with a value of zero has no segment but stays in the legend, so people can see it was counted.
+- Keep a minimum segment size so a small part stays visible and selectable, and show its true share in the label.
+- When people filter parts out, recalculate the centre total and every share.
+
+## Content
+
+- Segment labels read count, unit, share: "124 candidates, 30%".
+- Centre text is the total and a short unit: "412" over "candidates". One or two words only.
+- Title is a noun phrase that names the whole: "Open roles by work pattern".
+- If a name must be cut, keep the part that tells it apart: "…Designer, Leeds" rather than "Junior Product…".
+
+## Accessibility
+
+- Description: "Donut chart showing open roles by work pattern, today." The Table view lists each part with count and share.
+- Segments are identified by their printed labels and the legend, never by colour alone.
+- Segments reach 3:1 against the background, and the 2px gap keeps neighbours apart.
+- Arrow keys move between segments and show each one's details in the popover.
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| Tab | Focus the chart, then the legend items |
+| ← → | Move to the previous or next segment |
+| Enter | Pin the details popover |
+| Esc | Close the popover |
+
+## Examples
+
+### sources
+
+```tsx
+import { ChartFrame, DonutChart } from "@twoux/ui";
+
+export const meta = { title: "Where applicants come from", description: "Two to five parts of one whole, each labelled with its count and share. For more parts, or to compare sizes closely, use a bar chart.", order: 1 };
+
+export default function Example() {
+	return (
+		<ChartFrame className="w-full max-w-xl" title="Applications by source" description="This month">
+			<DonutChart totalLabel="applications" aria-label="Applications by source" segments={[
+				{ id: "board", label: "Job boards", value: 312 },
+				{ id: "site", label: "Careers page", value: 164 },
+				{ id: "ref", label: "Referrals", value: 71 },
+				{ id: "agency", label: "Agencies", value: 48 },
+			]} />
+		</ChartFrame>
+	);
+}
+```
+
+## Related
+
+- Bar chart
+- Stat card with comparison
+- Stacked area chart
+- Data visualisation colours
+- Data visualisation

package/agent/docs-md/chart-drill-down.md

@@ -0,0 +1,72 @@
+# Chart drill-down
+
+Select a point on a chart to see what makes it up, then narrow the chart or the whole page to that point, with every applied filter shown as a pill you can remove.
+
+Kind: pattern · Group: Patterns: data and dashboards
+
+**Problem:** A hiring lead sees applications drop on 12 Oct and wants to know why. Without a way in from the chart, they rebuild the same filters by hand on another page and lose the thread.
+
+**Solution:** Offer three levels and pick one per chart. A breakdown in the details popover answers most questions. If more is needed, a footer in the pinned popover filters either this chart or the whole page, never both on one page. Filters land as pills in the filter bar, write to the URL and come off with one click.
+
+**Built from:** Line chart card, Bar chart, Stacked area chart, Donut chart, Filter pills and filter bar, Breakdown table, List table, Popover rules
+
+## How it works
+
+1. Hover or move the crosshair to a point; the details popover shows each series' value. Select it or press Enter to pin the popover.
+2. Breakdown: under a value, list up to seven parts that make it up, such as applications on 12 Oct by listing. More than seven ends with a link: "View all 14 in table".
+3. Link either the part's name to its record or its value to a filtered List table, never both.
+4. Chart drill-down: the popover footer has a title saying where the filter goes ("Filter this chart"), the chosen point as read-only values ("Date 12 Oct"), an optional select ("Team"), and one button.
+5. Page drill-down: the same footer, titled "Filter this page", applies the values to the page's filter bar so every chart and table updates.
+6. Every applied value appears as a pill ("Date is 12 Oct") and in the URL, so Clear filters, removing a pill or Back returns to the default view.
+
+## When to use
+
+- When people look at charts to investigate: a spike, a drop or an outlier they need to explain.
+- Page drill-down on dashboards where several charts and a table share filters, such as a hiring overview by team and location.
+
+## When not to use
+
+- Do not mix chart drill-down and page drill-down on the same page. Pick one; two levels of filters conflict.
+- For a chart with one series and nothing beneath it. The tooltip is enough.
+- On a Board item people rearrange: send them to the full report page instead of filtering inside a tile.
+
+## Guidelines
+
+- Always say which filters a drill-down will apply and where, before it runs.
+- Pre-filled values from the selected point are read-only in the popover; only the optional extra choice is editable.
+- Filtering is a reversible view change, so it needs no confirmation and no Undo toast: the pill and Back undo it.
+- A pinned popover follows Popover rules: one open at a time, never cut off, Esc closes it and returns focus to the point.
+- Popover footers hold at most two buttons; more go in a menu.
+- The popover breakdown is never the only place a value lives. The Breakdown table under the chart holds the same split.
+
+## Content
+
+- Footer title names the target: "Filter this chart" or "Filter this page". Description lists what will apply: "Date is 12 Oct and Team is Design."
+- Button names the action and target: "Filter chart", "Filter page". Not "Apply" or "Submit".
+- Breakdown rows read as key and value: "Junior Product Designer, Leeds  18".
+
+## Accessibility
+
+- Enter on a focused point pins the popover; Tab moves through its links, select and button; Esc closes it and returns focus to the same point.
+- The popover is labelled by the point it describes: "Applications, 12 Oct".
+- After a drill-down applies, announce the new state politely: "Filtered to 12 Oct. 3 charts updated."
+- Read-only values are text, not disabled inputs, so they are read in full and not skipped.
+
+## Do
+
+- Do show every drill-down filter as a pill in the filter bar.
+- Do cap a popover breakdown at seven items with a link to the rest.
+- Do keep the drill-down state in the URL.
+
+## Don't
+
+- Don't offer chart and page drill-down on the same page.
+- Don't link both the name and the value in a breakdown row.
+- Don't apply filters from a hover; only from a pinned popover and a button.
+
+## Related
+
+- Data visualisation
+- Filtering and search
+- Comparison over time
+- Record detail: side panel, overlay or full page

package/agent/docs-md/chart-funnel.md

@@ -0,0 +1,71 @@
+# Funnel
+
+Horizontal bars for ordered stages (views, applies, interviews, offers) that show each stage's count and its rate from the stage before, darkest to lightest.
+
+Kind: component · Group: Data visualisation · Status: built, import from @twoux/ui
+
+## When to use
+
+- Showing ordered stages where people care how many make it from one step to the next.
+- Comparing amounts at each stage, which simple bars make quick to read.
+
+## When not to use
+
+- For unordered categories. Use the TwoUX Bar chart.
+- For change over time. Use the TwoUX Line chart card.
+
+## Structure
+
+1. Title and subtitle (scope, starting count)
+2. Stage label
+3. Bar (length by count)
+4. Count
+5. Rate from the previous stage
+
+## Guidelines
+
+- Encode counts as bar length from a shared left edge; length is judged accurately.
+- Show each stage's rate from the stage before; that is the number people act on.
+- Stages go darkest to lightest in one hue, following order.
+- Write counts beside bars so colour and length are not the only cues.
+- Show the four states: skeleton bars while loading, empty, no match with Clear filters, error with Try again.
+- A stage's count links to the List table filtered to that stage, so people go from "Interviewed 42" to those 42 candidates.
+- Do not use a donut for stages; order is the point and a ring loses it.
+
+## Content
+
+- Stage names are the steps people use, "Viewed", "Applied", "Interviewed".
+- The subtitle states the base, "from 6,840 views".
+- Write rates as percentages with the same decimals on every stage.
+
+## Accessibility
+
+- 1.1.1 Non-text Content: the accessible name lists each stage with its count.
+- 1.4.11 Non-text Contrast: the lightest stage bar still reaches 3:1, or the printed count carries the value.
+- 1.3.1 Info and Relationships: stages are in reading order in the markup.
+- Stage links are named by stage and count: "View 42 interviewed candidates".
+- Arrow keys move between stages when the funnel is focused.
+
+## Examples
+
+### pipeline
+
+```tsx
+import { ChartFrame, Funnel } from "@twoux/ui";
+
+export const meta = { title: "Hiring funnel", description: "Ordered stages as horizontal bars. Each stage shows its count and the share that moved on from the stage before.", order: 1 };
+
+export default function Example() {
+	return (
+		<ChartFrame className="w-full max-w-2xl" title="Pipeline, this quarter" description="All listings">
+			<Funnel aria-label="Hiring funnel this quarter" stages={[{ label: "Viewed", value: 8420 }, { label: "Applied", value: 595 }, { label: "Screened", value: 126 }, { label: "Interviewed", value: 48 }, { label: "Offered", value: 9 }]} />
+		</ChartFrame>
+	);
+}
+```
+
+## Related
+
+- Bar chart
+- Stat card with comparison
+- Data visualisation colours

package/agent/docs-md/chart-heatmap.md

@@ -0,0 +1,76 @@
+# Heatmap
+
+A grid of two dimensions (such as team by weekday) shaded in one hue from light to dark, with every cell showing its number and a legend under the grid.
+
+Kind: component · Group: Data visualisation · Status: built, import from @twoux/ui
+
+## When to use
+
+- Showing a quantity across two dimensions at once, such as when people apply by team and weekday.
+- Spotting patterns and hot spots matters more than reading exact values; the printed numbers cover exact reading.
+
+## When not to use
+
+- When people must compare exact amounts; colour is a poor encoding of magnitude. Use the TwoUX Bar chart or Breakdown table.
+- For one dimension over time. Use the TwoUX Line chart card.
+
+## Structure
+
+1. Title and subtitle
+2. Row labels (team)
+3. Column labels (weekday)
+4. Cells with value text
+5. Legend: Fewer to More ramp, under the grid
+
+## Guidelines
+
+- One hue, light for low and dark for high, never a rainbow.
+- Every cell shows its number, so colour is never the only cue.
+- Avoid red and green together; for diverging values use blue against orange or red.
+- Separate neighbouring cells with a gap in the surface colour.
+- Put the legend under the grid.
+- While loading, show the grid with empty cells and labels; on error replace the grid with the error state and Try again; with no data, an empty state.
+- Missing cells show a dash and "No data" in the tooltip, never the lightest step, which would read as low.
+- Selecting a cell can drill down to the list behind it, such as candidates who applied to Design on Mondays, as a filtered List table.
+
+## Content
+
+- Legend ends say "Fewer" and "More", not colour names.
+- Title says what is counted; subtitle gives the period, "Applies by team and weekday, last 30 days".
+- Choose text colour per cell so numbers stay readable on dark steps.
+
+## Accessibility
+
+- 1.4.1 Use of Color: values are printed in the cells, which is the sufficient technique of adding text.
+- 1.4.11 Non-text Contrast: heat maps can fall under the essential exception, but because the cells show values TwoUX does not depend on it.
+- 1.1.1 and WAI complex images: give a short alternative and a table of the values.
+- The grid is keyboard reachable: Tab to the grid, arrow keys move cell to cell, and each cell is announced with row, column and value.
+- Accessible description: "Heatmap showing applies by team and weekday, last 30 days."
+
+## Examples
+
+### weekday
+
+```tsx
+import { ChartFrame, Heatmap } from "@twoux/ui";
+
+export const meta = { title: "When candidates apply", description: "One hue from light to dark, a legend from fewer to more, and every value in the cell's accessible name. Zero is grey, not the lightest step.", order: 1 };
+
+const DAYS = ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"];
+const TEAMS = ["Design", "Engineering", "Data", "People"];
+const V = [[12, 18, 15, 14, 9, 2, 4], [31, 36, 33, 29, 21, 6, 9], [7, 9, 11, 8, 6, 0, 1], [4, 6, 5, 7, 3, 0, 0]];
+
+export default function Example() {
+	return (
+		<ChartFrame className="w-full max-w-2xl" title="Applications by weekday" description="Last 4 weeks, by team">
+			<Heatmap rows={TEAMS} columns={DAYS} values={V} aria-label="Applications by team and weekday" />
+		</ChartFrame>
+	);
+}
+```
+
+## Related
+
+- Data visualisation colours
+- Breakdown table
+- Bar chart

package/agent/docs-md/chart-histogram.md

@@ -0,0 +1,81 @@
+# Histogram
+
+How values spread: touching columns, one per equal bin, counted on one axis, with an optional dashed marker such as the median.
+
+Kind: component · Group: Data visualisation · Status: built, import from @twoux/ui
+
+## When to use
+
+- Seeing the shape of a distribution, such as salary offers, where an average hides the tail.
+- Checking whether most values sit in a range before setting a threshold.
+
+## When not to use
+
+- To compare distributions of several groups. Use the TwoUX Box plot.
+- For counts by named category. Use the TwoUX Bar chart.
+
+## Structure
+
+1. Title and subtitle
+2. Y axis: count
+3. Columns, one per bin, 2px gaps
+4. X axis: bin edges and title with unit
+5. Optional dashed marker with label
+6. Tooltip: range, count, share
+
+## Guidelines
+
+- Use equal, round bin widths and say the width in the subtitle or table.
+- Columns touch with a 2px surface gap, because bins are continuous.
+- The y axis starts at zero and counts; there is one axis only.
+- Mark the median or a threshold with a dashed grey line and a text label.
+- Use ChartFrame for the four states: loading keeps the frame, an error says what failed with Try again, an empty period says so, and no match offers Clear filters.
+
+## Content
+
+- X axis title names the measure and unit, such as Annual salary offered.
+- Count label is the plural noun of what is counted (offers).
+
+## Accessibility
+
+- 1.1.1 and WAI complex images: the chart has a short generated summary as its accessible name and a Table view with every value.
+- 2.1.1 Keyboard: the chart is one tab stop; arrow keys move between marks and show the same tooltip as hover.
+- 1.4.13 Content on Hover or Focus: the tooltip never covers the mark it describes, stays while the pointer is over the chart and closes with Esc.
+- Accessible description: "Histogram showing salary offers in £5k bins, last 12 months."
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| Tab | Focus the chart |
+| ← → ↑ ↓ | Move to the previous or next mark and show its values |
+| Home End | Jump to the first or last mark |
+| Esc | Hide the tooltip |
+
+## Examples
+
+### salary-offers
+
+```tsx
+import { binValues, ChartFrame, Histogram, histogramTable } from "@twoux/ui";
+
+export const meta = { title: "Salary offers", description: "140 offers in £5k bins with the median marked. The shape shows the long tail a single average hides.", order: 1 };
+
+const OFFERS = [23000, 27000, 28500, 29500, 30000, 30000, 30000, 30000, 31500, 32500, 33000, 33500, 33500, 34000, 34000, 35500, 36000, 36000, 36500, 37000, 37500, 38000, 38000, 38000, 38000, 38500, 38500, 39000, 39500, 40000, 40000, 40500, 40500, 40500, 40500, 41000, 41000, 41000, 41500, 41500, 42000, 42500, 42500, 43000, 43000, 43000, 43500, 43500, 43500, 44000, 44000, 45000, 45000, 45500, 45500, 46500, 46500, 46500, 47000, 49500, 50000, 50500, 50500, 50500, 50500, 51000, 51000, 51000, 51500, 51500, 52000, 52500, 53000, 53500, 53500, 53500, 54000, 54000, 54500, 55000, 55000, 55000, 55000, 55500, 56000, 56500, 57000, 57500, 57500, 57500, 57500, 57500, 58000, 58000, 58500, 59000, 60000, 62000, 62000, 62000, 62500, 62500, 63000, 63000, 63000, 63000, 63500, 64000, 64500, 65000, 65000, 65500, 66000, 67000, 67500, 68000, 68000, 68000, 70000, 70500, 75500, 75500, 76000, 76500, 76500, 77500, 78500, 79500, 79500, 79500, 82500, 83000, 83500, 83500, 88000, 91000, 92000, 93500, 101500, 104000];
+const BINS = binValues(OFFERS, { binWidth: 5000, start: 20000 });
+const gbp = (n: number) => `£${n / 1000}k`;
+
+export default function Example() {
+	return (
+		<ChartFrame className="w-full" title="Salary offers" description="Offers made, last 12 months" table={histogramTable(BINS, gbp, "Salary")}>
+			<Histogram bins={BINS} format={gbp} xTitle="Annual salary offered" countLabel="offers" marker={{ value: 52000, label: "Median £52k" }} aria-label="Salary offers, last 12 months" />
+		</ChartFrame>
+	);
+}
+```
+
+## Related
+
+- Box plot
+- Bar chart
+- Scatter chart

package/agent/docs-md/chart-map.md

@@ -0,0 +1,165 @@
+# Map chart
+
+Regions shaded by a rate in five steps of one hue, or circles sized by an amount at places. For questions where location itself matters; missing regions are hatched and labelled No data.
+
+Kind: component · Group: Data visualisation · Status: built, import from @twoux/ui
+
+## When to use
+
+- When where something happens is the question: clusters, neighbours, regions with nothing, such as trial conversion by country.
+- Placing amounts at locations, such as ARR by customer head office city, with circles sized by value.
+
+## When not to use
+
+- To compare amounts or rank countries. Use a Bar chart or a Ranked list: lengths are read more exactly than shades, and small countries don't disappear.
+- For raw counts across regions of very different size or population, as shading. Normalise to a rate or per head, or use markers.
+- For change over time. Use a Line chart card; a map shows one moment.
+
+## Structure
+
+1. Title and subtitle
+2. Regions from your TopoJSON, thin borders
+3. Shading in five classed steps, or circles sized by value
+4. Hatched fill for regions with no data
+5. Legend: bin ranges and No data
+6. Details: name, value, share of total, rank
+7. Pinned details with a drill-down button
+8. Note listing values with no shape on the map
+
+## Guidelines
+
+- Shade by a rate, a share or a per-head figure; put raw counts and amounts on markers, where circle area grows with value.
+- One measure per map: values or markers, never both.
+- Colour is five classed steps of one hue (q1 to q5), darkest for the highest in light, lightest in dark. The legend shows the range of each step.
+- Regions with no value are hatched and labelled No data in the legend. Never draw them as zero or in the lowest step.
+- Join values by feature id (ISO 3166-1 numeric in world-atlas), not by name; names differ between sources.
+- Values with no shape on the map, such as Singapore at 1:110m, are listed under the map and stay in the table.
+- Use Equal Earth for the world so areas are not inflated towards the poles; leave Antarctica out unless it matters.
+- For drill-down, a pinned region offers one button that says where the filter lands (Filter page) and adds a pill to the filter bar.
+- Use ChartFrame for the four states and the Table view (mapTable).
+
+## Content
+
+- Title names the measure and period: "Trial conversion by country", subtitle "Paid accounts per 100 trials, July to September".
+- Legend ranges read "Under 5%", "5% to 10%", "20% and over". Missing regions read "No data".
+- Turn off share of total for rates and averages; a share of a sum of rates means nothing.
+
+## Accessibility
+
+- 1.1.1 and WAI complex images: the map's accessible name is a generated summary (label, number of regions, top three, how many have no data), and the Table view lists every value.
+- 2.1.1 Keyboard: the map is one tab stop; arrow keys move between regions with data, highest value first, and show the same details as hover.
+- 1.4.13 Content on Hover or Focus: details sit beside the region, stay while the pointer is over the map and close with Esc.
+- 1.4.1 Use of Color: values are in the details, legend ranges and table; No data has a pattern as well as a colour.
+- Accessible description: "Map showing trial conversion by country, July to September."
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| Tab | Focus the map |
+| ← → ↑ ↓ | Move to the next or previous region with data, highest value first, and show its details |
+| Home End | Jump to the highest or lowest value |
+| Enter | Pin the details; focus moves to the drill-down button when there is one |
+| Esc | Close the details and return focus to the map |
+
+## Examples
+
+### arr-by-city
+
+```tsx
+import { ChartFrame, MapChart, mapTable } from "@twoux/ui";
+import world from "world-atlas/countries-110m.json";
+
+export const meta = { title: "ARR by customer location", description: "Raw amounts go on markers, never as shading: circle area grows with ARR, so London and New York stand out without painting all of the UK or the US.", order: 2 };
+
+const gbp = (n: number) => `£${(n / 1_000_000).toFixed(1)}m`;
+// Annual recurring revenue by the city of the customer's head office.
+const ARR = [
+	{ id: "lon", label: "London", lon: -0.13, lat: 51.51, value: 4_820_000 },
+	{ id: "man", label: "Manchester", lon: -2.24, lat: 53.48, value: 910_000 },
+	{ id: "dub", label: "Dublin", lon: -6.26, lat: 53.35, value: 1_340_000 },
+	{ id: "ber", label: "Berlin", lon: 13.4, lat: 52.52, value: 2_150_000 },
+	{ id: "ams", label: "Amsterdam", lon: 4.9, lat: 52.37, value: 1_620_000 },
+	{ id: "par", label: "Paris", lon: 2.35, lat: 48.86, value: 1_280_000 },
+	{ id: "sto", label: "Stockholm", lon: 18.07, lat: 59.33, value: 740_000 },
+	{ id: "nyc", label: "New York", lon: -74.0, lat: 40.71, value: 3_960_000 },
+	{ id: "sfo", label: "San Francisco", lon: -122.42, lat: 37.77, value: 2_480_000 },
+	{ id: "tor", label: "Toronto", lon: -79.38, lat: 43.65, value: 860_000 },
+	{ id: "syd", label: "Sydney", lon: 151.21, lat: -33.87, value: 1_050_000 },
+	{ id: "sin", label: "Singapore", lon: 103.82, lat: 1.35, value: 690_000 },
+];
+
+export default function Example() {
+	return (
+		<ChartFrame className="w-full" title="ARR by customer location" description="Head office city, as of 30 September" table={mapTable(ARR, { format: gbp, first: "City", valueLabel: "ARR" })} height={260}>
+			<MapChart topology={world} object="countries" exclude={["010"]} markers={ARR} format={gbp} valueLabel="ARR" aria-label="Map showing ARR by customer head office city, as of 30 September" />
+		</ChartFrame>
+	);
+}
+```
+
+### trial-conversion
+
+```tsx
+import * as React from "react";
+import { ChartFrame, FilterBar, FilterPill, MapChart, mapTable } from "@twoux/ui";
+import world from "world-atlas/countries-110m.json";
+
+export const meta = { title: "Trial conversion by country", description: "A rate, so countries of different size compare fairly. Arrow keys move from highest to lowest; Enter pins the details and offers Filter page.", order: 1 };
+
+// Trials that became paid accounts, per 100 trials, last quarter. ISO 3166-1 numeric ids.
+const RATES = [
+	{ id: "826", label: "United Kingdom", value: 18.4 },
+	{ id: "372", label: "Ireland", value: 21.2 },
+	{ id: "276", label: "Germany", value: 14.9 },
+	{ id: "250", label: "France", value: 11.3 },
+	{ id: "528", label: "Netherlands", value: 19.7 },
+	{ id: "752", label: "Sweden", value: 16.1 },
+	{ id: "724", label: "Spain", value: 8.2 },
+	{ id: "616", label: "Poland", value: 9.6 },
+	{ id: "840", label: "United States", value: 15.8 },
+	{ id: "124", label: "Canada", value: 13.4 },
+	{ id: "484", label: "Mexico", value: 5.1 },
+	{ id: "076", label: "Brazil", value: 6.7 },
+	{ id: "356", label: "India", value: 4.3 },
+	{ id: "392", label: "Japan", value: 7.9 },
+	{ id: "036", label: "Australia", value: 17.2 },
+	{ id: "710", label: "South Africa", value: 6.0 },
+	{ id: "702", label: "Singapore", value: 22.5 },
+];
+const pctFmt = (n: number) => `${n.toFixed(1)}%`;
+
+export default function Example() {
+	const [country, setCountry] = React.useState<string[]>([]);
+	const options = RATES.map((r) => ({ value: r.id, label: r.label }));
+	return (
+		<div className="grid w-full gap-3">
+			<FilterBar>
+				<FilterPill field="Country" options={options} selected={country} onChange={setCountry} />
+			</FilterBar>
+			<ChartFrame className="w-full" title="Trial conversion by country" description="Paid accounts per 100 trials, July to September" table={mapTable(RATES, { format: pctFmt, share: false, first: "Country", valueLabel: "Conversion" })} height={260}>
+				<MapChart
+					topology={world}
+					object="countries"
+					exclude={["010"]}
+					values={RATES}
+					format={pctFmt}
+					share={false}
+					valueLabel="Conversion"
+					filterField="Country"
+					onSelect={(r) => setCountry([r.id])}
+					aria-label="Map showing trial conversion by country, July to September"
+				/>
+			</ChartFrame>
+		</div>
+	);
+}
+```
+
+## Related
+
+- Bar chart
+- Ranked list
+- Heatmap
+- Chart drill-down
+- Filter pills and filter bar

package/agent/docs-md/chart-mixed.md

@@ -0,0 +1,88 @@
+# Bar and line chart
+
+One bar series with one to three lines on the same y-axis and unit, such as weekly applications as bars and their four-week average as a line.
+
+Kind: component · Group: Data visualisation · Status: built, import from @twoux/ui
+
+## When to use
+
+- When a count and a reference for that count share a unit: hires per month as bars, planned hires per month as a line.
+- When volume per period is the main reading and the line adds the trend, such as applications per week with the four-week average.
+
+## When not to use
+
+- When the two measures have different units or scales, such as applications (count) and conversion to interview (%). Use two charts side by side; never a second y-axis.
+- When every series is the same kind of measure, such as applications for three listings. Use the Line chart card or grouped bars.
+- For a fixed target that does not change by period. Use a threshold line on the Bar chart instead.
+
+## Structure
+
+1. Title and subtitle
+2. Plot: one y-axis, zero baseline, bars for the main measure
+3. Line or lines (2px) for a related measure in the same unit: average, plan or previous period
+4. Legend: bar swatch and line swatch with names
+5. Crosshair tooltip with each series at the hovered period
+6. Optional threshold: dashed line with a text label
+
+## Guidelines
+
+- Only one series is drawn as bars. Lines carry up to three related series, so the chart stays within four series in all.
+- Bars start at zero, so the shared axis starts at zero too.
+- Bars use categorical colour 1; lines use the next colours in order. A previous-period line stays the dashed grey from the Period comparison pattern.
+- Draw lines on top of bars and put a marker on each line point so it stays visible where it crosses a bar.
+- Show missing periods as gaps in the line and no bar, not as zero.
+- If the line and the bars stop sharing a unit after a change in the data, split the chart. Do not add a right-hand axis.
+
+## Content
+
+- Name each series by role: "Hires", "Plan", "4-week average". The legend says which is the bar and which is the line through its swatch.
+- Axis title states the shared unit once: "Applications". No unit on the y-axis for time.
+- Title is a noun phrase naming the main measure: "Hires against plan".
+
+## Accessibility
+
+- Description names both marks: "Bar and line chart showing hires per month against plan, last 12 months."
+- Bars and lines differ by shape, not only by colour, and the tooltip names every series.
+- Bars and lines reach 3:1 against the background; the line marker keeps 3:1 where it sits on a bar.
+- The Table view has one column per series with the same names as the legend.
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| Tab | Focus the plot, then each legend item |
+| ← → | Move to the previous or next period |
+| Enter | Pin the tooltip |
+| Esc | Close the tooltip |
+
+## Examples
+
+### applications-target
+
+```tsx
+import { CartesianChart, ChartFrame, ChartLegend, type ChartSeries, chartTable, seriesColor } from "@twoux/ui";
+import { WEEKS } from "../chart-card-line/data";
+
+export const meta = { title: "Applications against the average", description: "Bars for this period, a line for the 8-week average, and a dashed target. All three share one axis and one unit; different units would need two charts.", order: 1 };
+
+const SERIES: ChartSeries[] = [
+	{ id: "apps", label: "Applications", type: "bar", data: [151, 170, 168, 188, 204, 219, 218, 250] },
+	{ id: "avg", label: "8-week average", type: "line", data: [160, 163, 165, 171, 178, 186, 192, 196] },
+];
+
+export default function Example() {
+	return (
+		<ChartFrame className="w-full" title="Applications per week" description="Against the rolling average and the target" table={chartTable("Week", WEEKS, SERIES)} legend={<ChartLegend items={SERIES.map((s, i) => ({ id: s.id, label: s.label, color: seriesColor(i), shape: s.type === "line" ? "line" : "box" }))} />}>
+			<CartesianChart kind="mixed" x={WEEKS} series={SERIES} threshold={{ value: 220, label: "Target 220" }} aria-label="Applications per week with average and target" />
+		</ChartFrame>
+	);
+}
+```
+
+## Related
+
+- Bar chart
+- Line chart card
+- Stat card with comparison
+- Data visualisation colours
+- Data visualisation