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

package/docs/chart.examples.md

@@ -0,0 +1,582 @@
+<!-- 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
+
+```html
+<figure slChart title="Receita e custo" [data]="monthly" [series]="series" [x]="x" [y]="y"></figure>
+```
+
+### 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
+
+```html
+<figure slChart title="Sessões por canal" [data]="sessions" [series]="stackedAreas"></figure>
+```
+
+### 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
+
+```html
+<figure slChart title="Pedidos por canal" [data]="orders" [series]="channels"></figure>
+```
+
+### 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
+
+```html
+<figure
+  slChart
+  orientation="horizontal"
+  title="Receita por região"
+  [data]="regions"
+  [series]="ranking"
+></figure>
+```
+
+### 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
+
+```html
+<figure slChart title="Pedidos por canal" [data]="orders" [series]="stackedBars"></figure>
+```
+
+### 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
+
+```html
+<figure
+  slChart
+  stackMode="percent"
+  title="Participação por canal"
+  [data]="orders"
+  [series]="stackedAreas"
+></figure>
+```
+
+### 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
+
+```html
+<figure slChart title="Receita e meta" [data]="monthly" [series]="barAndTarget"></figure>
+```
+
+### 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
+
+```html
+<figure
+  slChart
+  title="Pedidos e margem"
+  [data]="monthly"
+  [series]="ordersAndMargin"
+  [y]="[orders, margin]"
+></figure>
+```
+
+### 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
+
+```html
+<figure
+  slChart
+  title="Sessões diárias"
+  [data]="daily"
+  [series]="sessions"
+  [x]="{ field: 'day', type: 'time' }"
+></figure>
+```
+
+### 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
+
+```html
+<figure
+  slChart
+  title="Usuários ativos"
+  [data]="users"
+  [series]="series"
+  [y]="{ scale: 'log' }"
+></figure>
+```
+
+### 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
+
+```html
+<figure
+  slChart
+  title="Receita por região"
+  [data]="regions"
+  [series]="pie"
+  [x]="{ field: 'region' }"
+></figure>
+```
+
+### A donut with the total inside
+
+innerRadius opens the middle and the center holds the total; a slChartCenter template replaces it, here with the resolution rate.
+
+Excerpt — not a complete module
+
+```html
+<figure slChart title="Tickets por estado" [data]="tickets" [series]="donut">
+  <ng-template slChartCenter let-model>
+    <span data-part="center-value">{{ resolved(model) }}</span>
+    <span data-part="center-label">resolvidos</span>
+  </ng-template>
+</figure>
+```
+
+### 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
+
+```html
+<figure
+  slChart
+  recordKey="id"
+  title="Esforço e impacto"
+  [data]="work"
+  [series]="groups"
+  [x]="effort"
+></figure>
+```
+
+### 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
+
+```html
+<figure
+  slChart
+  recordKey="id"
+  title="Esforço, impacto e clientes"
+  [data]="work"
+  [series]="bubbles"
+></figure>
+```
+
+### 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
+
+```html
+<figure
+  slChart
+  title="Receita contra a meta"
+  [annotations]="annotations"
+  [data]="monthly"
+  [series]="revenue"
+></figure>
+```
+
+### 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
+
+```html
+<figure
+  slChart
+  title="Canais de aquisição"
+  [data]="sessions"
+  [series]="channels"
+  [(hidden)]="hidden"
+></figure>
+```
+
+### 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
+
+```html
+<figure
+  slChart
+  legendValues
+  title="Canais de aquisição"
+  [data]="sessions"
+  [series]="channels"
+></figure>
+```
+
+### 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
+
+```html
+<figure
+  slChart
+  trigger="axis"
+  [tooltip]="{ sort: 'desc' }"
+  [data]="sessions"
+  [series]="channels"
+></figure>
+<figure slChart trigger="item" [data]="sessions" [series]="channels"></figure>
+<figure slChart legendValues trigger="none" [data]="sessions" [series]="channels"></figure>
+```
+
+### A tooltip of your own
+
+A slChartTooltip template 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
+
+```html
+<figure slChart title="Receita mensal" [data]="monthly" [series]="revenue">
+  <ng-template slChartTooltip let-context let-model="model">
+    <div data-part="tooltip-title">{{ context.title }}</div>
+    <div data-part="tooltip-item">{{ change(context, model) }}</div>
+  </ng-template>
+</figure>
+```
+
+### 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
+
+```html
+<figure
+  slChart
+  selectable
+  title="Receita mensal"
+  [data]="monthly"
+  [series]="revenue"
+  [(selection)]="selected"
+></figure>
+```
+
+### 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
+
+```html
+<figure
+  slChart
+  zoomable
+  title="Sessões diárias"
+  [data]="daily"
+  [series]="sessions"
+  [(zoom)]="zoom"
+></figure>
+```
+
+### Charts that move together
+
+Two charts share one active point through the two-way value: the pointer on either draws the crosshair on both.
+
+Excerpt — not a complete module
+
+```html
+<figure
+  slChart
+  title="Receita"
+  [data]="monthly"
+  [series]="revenue"
+  [(activePoint)]="point"
+></figure>
+<figure slChart title="Pedidos" [data]="monthly" [series]="orders" [(activePoint)]="point"></figure>
+```
+
+### 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
+
+```html
+<figure slChart size="sm" [data]="monthly" [series]="revenue"></figure>
+<figure slChart size="md" [data]="monthly" [series]="revenue"></figure>
+<figure slChart size="lg" [data]="monthly" [series]="revenue"></figure>
+```
+
+### 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
+
+```html
+<figure
+  slChart
+  legendOverflow="wrap"
+  title="Onze canais"
+  [data]="sessions"
+  [series]="eleven"
+></figure>
+```
+
+### 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
+
+```html
+<figure
+  slChart
+  renderer="auto"
+  sampling="auto"
+  zoomable
+  [data]="latency"
+  [series]="series"
+></figure>
+```
+
+### 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
+
+```html
+<figure slChart title="Lacunas" [data]="withGaps" [series]="broken"></figure>
+<figure slChart title="Lacunas ligadas" [data]="withGaps" [series]="connected"></figure>
+```
+
+### 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
+
+```html
+<figure slChart title="Resultado mensal" [data]="result" [series]="operatingAndFx"></figure>
+```
+
+### 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
+
+```html
+<figure slChart [title]="longTitle" [data]="segments" [series]="series"></figure>
+```
+
+### 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
+
+```html
+<figure slChart texture title="Pedidos por canal" [data]="orders" [series]="channels"></figure>
+```
+
+### 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
+
+```html
+<figure
+  slChart
+  title="Pedidos por canal"
+  [data]="orders()"
+  [loading]="pending()"
+  [series]="channels"
+></figure>
+```
+
+### 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
+
+```html
+<figure slChart title="Reembolsos" [data]="[]" [series]="refunds"></figure>
+```
+
+### 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
+
+```html
+<figure
+  slChart
+  title="Canais"
+  [data]="sessions"
+  [series]="channels"
+  [hidden]="['c0', 'c1', 'c2']"
+></figure>
+```
+
+### The data did not arrive
+
+error replaces the drawing with a message and the action that asks again; the header and the box stay where they were.
+
+Excerpt — not a complete module
+
+```html
+<figure
+  slChart
+  title="Conversão"
+  [data]="monthly"
+  [error]="failed()"
+  [series]="conversion"
+  (retry)="reload()"
+></figure>
+```
+
+### 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
+
+```html
+<div slGrid [columns]="4" [gap]="4">
+  <figure
+    slChart
+    size="sm"
+    variant="card"
+    title="Receita"
+    [data]="monthly"
+    [series]="revenue"
+  ></figure>
+  <figure slChart loading size="sm" variant="card" title="Pedidos" [series]="channels"></figure>
+</div>
+```
+
+### 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
+
+```html
+<figure slChart variant="plain" [data]="monthly" [series]="revenue"></figure>
+<figure slChart variant="card" [data]="monthly" [series]="revenue"></figure>
+```
+
+### 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
+
+```html
+<figure slChart toolbar="visible" zoomable [data]="daily" [series]="sessions"></figure>
+<figure slChart toolbar="hover" [data]="daily" [series]="sessions"></figure>
+<figure slChart toolbar="none" [data]="daily" [series]="sessions"></figure>
+```
+
+### The whole screen
+
+The full-screen control takes the viewport; Escape or the same control gives the tile its place back. Bound two-way, the page can open it from its own button.
+
+Excerpt — not a complete module
+
+```html
+<figure slChart title="Receita" [data]="monthly" [series]="revenue" [(fullscreen)]="presenting">
+  <button slChartActions type="button" (click)="presenting.set(true)">Apresentar</button>
+</figure>
+```
+
+### 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
+
+```html
+<figure slChart palette="categorical" [data]="sessions" [series]="channels"></figure>
+<figure slChart palette="sequential" [data]="regions" [series]="ranking"></figure>
+<figure slChart palette="focus" [data]="sessions" [series]="channels"></figure>
+```
+
+### 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
+
+```html
+<figure
+  slChart
+  help="Receita reconhecida no mês, sem impostos."
+  title="Receita"
+  [data]="monthly"
+  [series]="revenue"
+></figure>
+```
+
+### 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 slChartActions projects the consumer’s own controls.
+
+Excerpt — not a complete module
+
+```html
+<figure slChart title="Receita e custo" [data]="monthly" [series]="series" [(tableOpen)]="asTable">
+  <button slChartActions type="button">12 meses</button>
+</figure>
+```
+
+### 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
+
+```ts
+provideSlotted({ locale: 'pt-BR', catalogs: { 'pt-BR': PT_BR } });
+```