@misoto22/design 0.3.1 → 0.6.0

package/dist/agent/TreemapChart.md

@@ -0,0 +1,52 @@
+# TreemapChart
+
+Part of a whole, when the whole has too many parts for a pie — and the parts nest.
+
+- Group: Charts
+- Import: `import { TreemapChart } from '@misoto22/design'`
+- Version: 0.6.0
+- Docs: https://ui.misoto22.com/components/treemap-chart/
+- Related: pie-chart, bar-chart
+
+## When to reach for it
+
+Fifty items where a pie fails at six. Under a dozen items with a ranking to read, a BarChart’s length is the more precise encoding.
+
+## Accessibility
+
+- title is required. The table view lists the LEAVES with the path that names them: a nested tree read row by row is not something anyone can follow.
+- Area is the encoding, so the data must be non-negative and must sum to something the reader recognises as the whole.
+- The gap between tiles is a surface-coloured stroke rather than a smaller rect — a treemap whose parts do not touch stops reading as a partition.
+
+## TreemapChart
+
+Part of a whole, when the whole has too many parts for a pie — and the parts nest. A treemap encodes value as AREA, which the eye reads worse than length but far better than angle, and it is the only form here that stays readable at fifty items. Two rules make it honest: no negative values (an area cannot be negative), and the tiles have to sum to something a reader recognises as the whole. Reach for `<BarChart>` when there are under a dozen items and the ranking matters — a bar's length is the more precise encoding, and a treemap's layout deliberately does not order its tiles by value alone.
+
+### Props
+
+- `config` — `ChartConfig` default `{}`. Tile names → their label and paint. Optional: the ramp covers unnamed tiles.
+- `data` (required) — `TreemapNode[]`. The tree. One level is a flat set of tiles; two is a nested treemap.
+- `title` (required) — `string`. What the chart shows, in a sentence a reader could act on. Required, and announced to a screen reader even when it is not printed.
+- `showTitle` — `boolean`. Prints the title above the plot instead of hiding it from sight.
+- `description` — `ReactNode`. A line under the title — the unit, the window, the caveat.
+- `className` — `string`. Merged onto the figure, last, so a call site can size or space it.
+- `variant` — `TreemapVariant` default `'ramp'`.
+- `dataKey` — `string` default `'size'`. The leaf field holding each tile's number.
+- `aspectRatio` — `number` default `4 / 3`. How square the tiles are pushed to be. Recharts' own squarify parameter.
+- `showLabels` — `boolean` default `true`. Prints each tile's name on it, where the tile is big enough to hold it.
+- `children` — `ReactNode`. The hover panel.
+- `chartProps` — `TreemapExtras`.
+- `hideDataTable` — `boolean` default `false`. Drops the hidden table view. Only correct when the page prints the data itself.
+
+## Types
+
+- `TreemapVariant` = `'ramp' | 'nested'`
+- `TreemapExtras` = `Omit<ComponentProps<typeof RechartsTreemap>, 'data' | 'dataKey'>`
+
+## Examples
+
+```tsx
+<TreemapChart title="Bundle size by package" data={packages} showLabels>
+  <TreemapChart.Tooltip />
+</TreemapChart>
+```

package/dist/agent/WaterfallChart.md

@@ -0,0 +1,62 @@
+# WaterfallChart
+
+How a total got from one figure to another.
+
+- Group: Charts
+- Import: `import { WaterfallChart } from '@misoto22/design'`
+- Version: 0.6.0
+- Docs: https://ui.misoto22.com/components/waterfall-chart/
+- Related: bar-chart, funnel-chart
+
+## When to reach for it
+
+“Why did this change”, where the contributions can be negative. A pie cannot hold a negative slice; a BarChart is right when the parts need not add up to the gap between two totals.
+
+## Accessibility
+
+- The connectors draw the steps as a sequence, and most breakdowns are not sequential — churn and expansion in the same month are simultaneous, and a reader takes the leftmost bar as the first cause. Where the order is arbitrary, say so in description.
+- Intermediate bars are floating lengths read against no baseline, so a small step high up the cascade is hard to compare with a large one near zero. Total bars sit on the axis and are the only ones a reader can read absolutely.
+- Direction is carried by the label’s sign and the bar’s texture as well as its position, so the reading survives greyscale and forced colours.
+- A closing bar with no value is computed from the deltas, which keeps the arithmetic in the data rather than in the caller’s head.
+
+## WaterfallChart
+
+How a total got from one figure to another — an opening balance, the signed contributions that moved it, and where it closed. The form for "why did this change", which a pair of bars cannot answer and a pie chart answers wrongly, because contributions can be NEGATIVE and a slice cannot. Reach for `<BarChart>` when the parts do not have to add up to the gap between two totals, and for `<FunnelChart>` when the quantity only ever shrinks. **The connectors are the claim to be careful about.** They draw the steps as a sequence — this happened, then this — and most breakdowns are not sequential at all: churn and expansion in the same month are simultaneous, and the order they are listed in is an editorial choice. The arithmetic survives any order; the STORY does not, and a reader will take the leftmost bar as the first cause. Two related traps: the intermediate bars are floating lengths read against no baseline, so a small step high up the cascade is hard to compare with a large one near zero; and any step that is itself a net of two larger opposing movements is invisible as such. Where the order is arbitrary, say so in the `description`. Recharts earns its place for the axes, grid and tooltip. Each bar is a floating range — from the running total to the new one — with a custom shape over it, because Recharts has no waterfall mark and the connectors have to be drawn from the same geometry as the bars they join.
+
+### Props
+
+- `config` — `ChartConfig` default `DEFAULT_CONFIG`. The single series — its label and its paint. Only the FIRST entry is read; a waterfall has one quantity and as many bars as it has steps.
+- `data` (required) — `WaterfallStep[]`. The steps, in the order they are applied. Order is the arithmetic: the chart does not sort, because a different order is a different total at every intermediate bar.
+- `title` (required) — `string`. What the chart shows, in a sentence a reader could act on. Required, and announced to a screen reader even when it is not printed.
+- `showTitle` — `boolean`. Prints the title above the plot instead of hiding it from sight.
+- `description` — `ReactNode`. A line under the title — the unit, the window, the caveat.
+- `children` (required) — `ReactNode`. The composed parts — axes, grid, tooltip, and `<WaterfallChart.Bars>`.
+- `className` — `string`. Merged onto the figure, last, so a call site can size or space it.
+- `chartProps` — `ComponentProps<typeof RechartsBarChart>`. Escape hatch onto the raw Recharts chart element.
+- `formatValue` — `(value: number) => string` default `defaultTick`. Formats every number the chart prints — ticks, labels, tooltip, table.
+- `hideDataTable` — `boolean` default `false`. Drops the hidden table view. Only correct when the page prints the data itself.
+- `empty` — `ChartEmptyProps | false`. What the chart shows when it has nothing to draw. `false` keeps the axes, for a chart whose emptiness is itself the reading.
+
+## Types
+
+- `WaterfallStepType` = `'delta' | 'total'`
+- `WaterfallDirection` = `'increase' | 'decrease' | 'total'`
+
+## Examples
+
+```tsx
+<WaterfallChart title="Revenue bridge, FY25" data={steps}>
+  <WaterfallChart.Grid />
+  <WaterfallChart.XAxis />
+  <WaterfallChart.YAxis label="AUD" />
+  <WaterfallChart.Tooltip />
+  <WaterfallChart.Bars showValues />
+</WaterfallChart>
+const steps = [
+  { name: 'FY24', value: 1200, type: 'total' as const },
+  { name: 'New', value: 340 },
+  { name: 'Churn', value: -180 },
+  // No value: the closing bar is whatever the deltas add up to.
+  { name: 'FY25', type: 'total' as const },
+]
+```