@slotted/react 0.0.0-stage → 0.1.0-beta.1

package/dist/docs/chart.examples.md

@@ -0,0 +1,538 @@
+<!-- index: ./index.md -->
+# chart
+
+`data-ui="chart"` · Line, bar, area, pie and scatter charts.
+
+## Examples
+
+### Lines for a trend
+
+Revenue and cost with a marker on the last point, and the target dashed in the neutral tone so it reads as a reference before its colour does.
+
+Excerpt — not a complete module
+
+```tsx
+<Chart
+  data={monthly}
+  series={[
+    { kind: 'line', field: 'revenue', label: 'Receita', markers: 'last' },
+    { kind: 'line', field: 'cost', label: 'Custo', markers: 'last' },
+    { kind: 'line', field: 'target', label: 'Meta', tone: 'neutral', stroke: 'dashed' },
+  ]}
+  title="Receita e custo"
+  x={{ field: 'month', label: 'Mês' }}
+  y={{ format: brlThousands }}
+/>;
+```
+
+### Areas, stacked and smoothed
+
+Three channels stacked with a monotone curve: the wash sits under each line and the tooltip adds the stack’s total.
+
+Excerpt — not a complete module
+
+```tsx
+<Chart
+  data={sessions}
+  series={channels.map((channel) => ({
+    ...channel,
+    kind: 'area',
+    stack: 'canal',
+    curve: 'monotone',
+  }))}
+  title="Sessões por canal"
+  x={{ field: 'month' }}
+/>;
+```
+
+### Grouped bars
+
+Three channels side by side in each month; the band under the pointer lights the whole category, not one bar.
+
+Excerpt — not a complete module
+
+```tsx
+<Chart data={orders} series={channels} title="Pedidos por canal" x={{ field: 'month' }} />;
+```
+
+### A ranking reads across
+
+Horizontal bars with value labels: long category names get the room a vertical axis cannot give them.
+
+Excerpt — not a complete module
+
+```tsx
+<Chart
+  data={regions}
+  orientation="horizontal"
+  series={[{ kind: 'bar', field: 'value', label: 'Receita', labels: true }]}
+  title="Receita por região"
+  x={{ field: 'region' }}
+/>;
+```
+
+### Bars stacked into a total
+
+Series that share a stack id pile up; the tooltip lists each and closes with the total of the pile.
+
+Excerpt — not a complete module
+
+```tsx
+<Chart {...orders} series={channels.map((channel) => ({ ...channel, stack: 'total' }))} />;
+```
+
+### Shares of a whole
+
+stackMode="percent" draws each month as 100 %, so a channel growing in share reads even when the total falls.
+
+Excerpt — not a complete module
+
+```tsx
+<Chart
+  data={orders}
+  series={channels.map((channel) => ({ ...channel, kind: 'area', stack: 'total' }))}
+  stackMode="percent"
+  title="Participação por canal"
+  x={{ field: 'month' }}
+/>;
+```
+
+### Bars and a line on one axis
+
+Revenue as bars and the target as a dashed line with markers: one kind per meaning, one scale for both.
+
+Excerpt — not a complete module
+
+```tsx
+const series: ChartSeries[] = [
+  { kind: 'bar', field: 'revenue', label: 'Receita' },
+  {
+    kind: 'line',
+    field: 'target',
+    label: 'Meta',
+    tone: 'neutral',
+    stroke: 'dashed',
+    markers: 'all',
+  },
+];
+```
+
+### Two units, two axes
+
+Orders on the start axis and margin in percent on the end one; each axis is named at its own top, so neither needs the legend to be read.
+
+Excerpt — not a complete module
+
+```tsx
+<Chart
+  data={monthly}
+  series={[
+    { kind: 'bar', field: 'orders', label: 'Pedidos' },
+    { kind: 'line', field: 'margin', label: 'Margem', axis: 'end', markers: 'all' },
+  ]}
+  title="Pedidos e margem"
+  x={{ field: 'month' }}
+  y={[{ label: 'Pedidos' }, { label: 'Margem', format: { style: 'percent' } }]}
+/>;
+```
+
+### Dates on a time axis
+
+Forty days of sessions: ticks fall on real dates, gaps in the calendar stay gaps, and the dates are wall-clock days, not shifted by the reader’s time zone.
+
+Excerpt — not a complete module
+
+```tsx
+<Chart
+  data={daily}
+  series={[{ kind: 'area', field: 'sessions', label: 'Sessões' }]}
+  title="Sessões diárias"
+  x={{ field: 'day', type: 'time' }}
+/>;
+```
+
+### Growth by orders of magnitude
+
+Active users doubling each month on a logarithmic scale: a steady rate is a straight line, and the early months are not flattened into the floor.
+
+Excerpt — not a complete module
+
+```tsx
+<Chart {...users} y={{ scale: 'log', format: { notation: 'compact' } }} />;
+```
+
+### Parts of a whole
+
+Revenue by region with labels outside the slices; the tooltip adds each slice’s share of the total.
+
+Excerpt — not a complete module
+
+```tsx
+<Chart
+  data={regions}
+  series={[{ kind: 'pie', field: 'value', label: 'Receita', labels: true }]}
+  title="Receita por região"
+  x={{ field: 'region' }}
+/>;
+```
+
+### A donut with the total inside
+
+innerRadius opens the middle, and the center holds the total; legendValues puts each slice’s value beside its name.
+
+Excerpt — not a complete module
+
+```tsx
+<Chart
+  data={tickets}
+  legendValues
+  series={[{ kind: 'pie', field: 'n', label: 'Tickets', innerRadius: 0.64 }]}
+  title="Tickets por estado"
+  x={{ field: 'status' }}
+/>;
+```
+
+### Two measures of each record
+
+Sixty tickets by effort and impact in two groups; the tooltip follows the point, not the axis, because a value axis has no categories to gather.
+
+Excerpt — not a complete module
+
+```tsx
+<Chart
+  data={tickets}
+  recordKey="id"
+  series={[
+    { kind: 'scatter', field: 'product', label: 'Produto' },
+    { kind: 'scatter', field: 'infra', label: 'Infraestrutura' },
+  ]}
+  title="Esforço e impacto"
+  x={{ field: 'effort', type: 'value', label: 'Esforço (h)' }}
+/>;
+```
+
+### A third measure as size
+
+sizeField scales each dot by the customers affected, by area rather than radius, so twice the customers reads as twice the ink.
+
+Excerpt — not a complete module
+
+```tsx
+const product: ChartSeries = {
+  kind: 'scatter',
+  field: 'product',
+  label: 'Produto',
+  sizeField: 'customers',
+};
+```
+
+### Targets, ranges and events
+
+A band for the tolerance range, a line for the annual target and a vertical line on the month the campaign started — each labelled on the plot.
+
+Excerpt — not a complete module
+
+```tsx
+const annotations: ChartAnnotation[] = [
+  { kind: 'band', from: 55, to: 70, label: 'Tolerância', tone: 'success' },
+  { kind: 'line', value: 80, label: 'Meta anual', tone: 'danger' },
+  { kind: 'line', axis: 'x', value: 'jun', label: 'Campanha' },
+];
+```
+
+### A legend that toggles
+
+Click a series to hide it, Shift+click to show it alone; arrows move along the legend. The legend holds one line: narrower than its items, the ones that do not fit wait behind +N.
+
+Excerpt — not a complete module
+
+```tsx
+const [hidden, setHidden] = useState<readonly string[]>([]);
+
+<Chart {...channels} hidden={hidden} onHiddenChange={setHidden} title="Canais de aquisição" />;
+```
+
+### Values in the legend
+
+Each legend item carries its series’ value at the active point, and the last value when nothing is active — a readout that never covers the drawing.
+
+Excerpt — not a complete module
+
+```tsx
+<Chart {...channels} legendValues title="Canais de aquisição" />;
+```
+
+### Three ways to read a point
+
+trigger="axis" lists every series at the category, sorted here by value; "item" shows only the one under the pointer; "none" leaves the reading to the legend values.
+
+Excerpt — not a complete module
+
+```tsx
+<Chart {...channels} tooltip={{ sort: 'desc' }} trigger="axis" />;
+<Chart {...channels} trigger="item" />;
+<Chart {...channels} legendValues trigger="none" />;
+```
+
+### A tooltip of your own
+
+renderTooltip replaces the content and keeps the box, the placement and the dock: this one says the change against the previous month in the tone of its sign.
+
+Excerpt — not a complete module
+
+```tsx
+<Chart
+  {...revenue}
+  renderTooltip={(context, model) => <MonthOverMonth context={context} model={model} />}
+/>;
+```
+
+### Choosing a point
+
+selectable makes a click or Enter pin a point; the others dim, and the selection is a value the page can use to filter the table below it.
+
+Excerpt — not a complete module
+
+```tsx
+const [selected, setSelected] = useState<ChartPoint | null>(null);
+
+<Chart {...revenue} onSelectionChange={setSelected} selectable selection={selected} />;
+```
+
+### Zooming a long range
+
+Drag across the plot, wheel with Ctrl, or press + and − with the plot focused; 0 or the reset control gives the whole range back.
+
+Excerpt — not a complete module
+
+```tsx
+<Chart {...daily} defaultZoom={{ start: 0.35, end: 0.7 }} zoomable />;
+```
+
+### Charts that move together
+
+Two charts share one active point through the controlled value: the pointer on either draws the crosshair on both.
+
+Excerpt — not a complete module
+
+```tsx
+const [point, setPoint] = useState<ChartPoint | null>(null);
+
+<Chart {...revenue} activePoint={point} onActivePointChange={setPoint} />;
+<Chart {...orders} activePoint={point} onActivePointChange={setPoint} />;
+```
+
+### Three heights
+
+sm is 192 pixels of plot for a dashboard tile, md 256 for a page section, lg 384 for the chart a page is about. The width is always the container’s.
+
+Excerpt — not a complete module
+
+```tsx
+<Chart {...revenue} size="sm" />;
+<Chart {...revenue} size="md" />;
+<Chart {...revenue} size="lg" />;
+```
+
+### More series than slots
+
+Eleven channels over eight colour slots: the first eight take the palette, the rest take the overflow neutral, and the legend says which is which.
+
+Excerpt — not a complete module
+
+```tsx
+<Chart {...elevenChannels} title="Onze canais" />;
+```
+
+### Twelve thousand samples
+
+Latency sampled every second: the renderer switches to canvas, the line is downsampled for the screen, and the table still holds every value.
+
+Excerpt — not a complete module
+
+```tsx
+<Chart {...latency} renderer="auto" sampling="auto" zoomable />;
+```
+
+### Missing values stay missing
+
+A null breaks the line on the left; connectNulls bridges it on the right, for a series where the gap is a sampling artefact rather than a fact.
+
+Excerpt — not a complete module
+
+```tsx
+const revenue: ChartSeries = {
+  kind: 'line',
+  field: 'revenue',
+  label: 'Receita',
+  connectNulls: true,
+};
+```
+
+### Values below zero
+
+Monthly result with its exchange component: a stack splits by sign, so losses hang from the baseline and gains grow from it.
+
+Excerpt — not a complete module
+
+```tsx
+const series: ChartSeries[] = [
+  { kind: 'bar', field: 'operating', label: 'Operacional', stack: 'r' },
+  { kind: 'bar', field: 'fx', label: 'Câmbio', stack: 'r', tone: 'warning' },
+];
+```
+
+### Content the family did not choose
+
+A title of fifteen words, category names of seven, a series named with markup: the title wraps, names on the axis and in the legend truncate with the whole name kept, and markup is text, never HTML.
+
+Excerpt — not a complete module
+
+```tsx
+<Chart {...segments} title={longTitle} />;
+```
+
+### Texture as a second channel
+
+texture adds a pattern per slot, so a series is told apart in print, in greyscale or by a reader who does not see the difference between two hues.
+
+Excerpt — not a complete module
+
+```tsx
+<Chart {...orders} texture />;
+```
+
+### Waiting, in the shape of what is coming
+
+The skeleton is the kind being loaded — bars, a line, a ring — over axis lines, in the plot’s own box, with one line of legend: nothing moves when the data arrives.
+
+Excerpt — not a complete module
+
+```tsx
+<Chart {...orders} loading={query.isPending} />;
+```
+
+### Nothing to show
+
+An empty series renders a message in the same box the drawing would take, never a blank plot and never an axis with nothing on it.
+
+Excerpt — not a complete module
+
+```tsx
+<Chart data={[]} series={revenueSeries} title="Receita" x={{ field: 'month' }} />;
+```
+
+### Every series hidden
+
+Hiding the last series is allowed and says so, with “Show all” to undo it; the legend stays, so each series can come back one by one.
+
+Excerpt — not a complete module
+
+```tsx
+<Chart {...channels} defaultHidden={['c0', 'c1', 'c2']} />;
+```
+
+### The data did not arrive
+
+error replaces the drawing with a message and, when onRetry is given, the action that asks again; the header and the box stay where they were.
+
+Excerpt — not a complete module
+
+```tsx
+<Chart {...revenue} error={query.isError} onRetry={() => query.refetch()} />;
+```
+
+### A row of tiles
+
+Four cards in one row: with and without a description, loading, a donut, eight series. Every tile is one height and every plot starts on one line.
+
+Excerpt — not a complete module
+
+```tsx
+<Grid columns={4} gap={4}>
+  <Chart {...revenue} description="Últimos 12 meses" size="sm" variant="card" />
+  <Chart {...orders} loading size="sm" variant="card" />
+</Grid>;
+```
+
+### On the page, or as a card
+
+plain sits on the page’s own surface for a report; card draws its own surface, border and padding, and fills the grid cell it is given.
+
+Excerpt — not a complete module
+
+```tsx
+<Chart {...revenue} variant="plain" />;
+<Chart {...revenue} variant="card" />;
+```
+
+### The controls, and when to show them
+
+visible keeps the toolbar in view; hover shows it on pointer or focus inside the chart; below 480 pixels only the menu remains and holds the rest.
+
+Excerpt — not a complete module
+
+```tsx
+<Chart {...daily} toolbar="visible" zoomable />;
+<Chart {...daily} toolbar="hover" />;
+<Chart {...daily} toolbar="none" />;
+```
+
+### The whole screen
+
+The full-screen control takes the viewport with the browser’s own API; Escape or the same control gives the tile its place back, and the page scrolls to where it was.
+
+Excerpt — not a complete module
+
+```tsx
+const [full, setFull] = useState(false);
+
+<Chart {...revenue} fullscreen={full} onFullscreenChange={setFull} />;
+```
+
+### Colour from the design system
+
+categorical tells series apart, sequential orders them by one hue for ranked data, focus draws the first series in colour and the rest in neutral. slot and tone pin a series to a colour.
+
+Excerpt — not a complete module
+
+```tsx
+<Chart {...channels} palette="categorical" />;
+<Chart {...ranked} palette="sequential" />;
+<Chart {...channels} palette="focus" />;
+
+const cost: ChartSeries = { kind: 'line', field: 'cost', label: 'Custo', slot: 5 };
+const target: ChartSeries = { kind: 'line', field: 'target', label: 'Meta', tone: 'neutral' };
+```
+
+### A note behind the title
+
+help puts an information control beside the title; its note opens on click or Enter, anchored to it, and closes on Escape or outside.
+
+Excerpt — not a complete module
+
+```tsx
+<Chart {...revenue} help="Receita reconhecida no mês, sem impostos. Atualizada às 6h." />;
+```
+
+### The same data as a table
+
+The table view opens inside the plot’s box so a card keeps its height; CSV and image downloads sit in the menu, and actions composes the consumer’s own.
+
+Excerpt — not a complete module
+
+```tsx
+<Chart {...revenue} actions={<PeriodPicker />} defaultTableOpen />;
+```
+
+### What a reader hears
+
+The plot is one tab stop named by the title and described by a generated summary; arrows walk the points, and the live region says the last one reached, not each one passed.
+
+Excerpt — not a complete module
+
+```tsx
+<SlottedProvider locale="pt-BR" catalogs={{ 'pt-BR': PT_BR }}>
+  <App />
+</SlottedProvider>;
+```