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

package/docs/chart.md

@@ -0,0 +1,187 @@
+<!-- index: ./index.md -->
+# chart
+
+`data-ui="chart"` · Line, bar, area, pie and scatter charts.
+
+## Import
+
+```ts
+import { SlChart, SlChartTooltip, provideChartDefaults, preloadChartEngine } from '@slotted/angular/chart';
+```
+
+Selector: `figure[slChart]` · exportAs: `slChart`
+
+## Minimal example
+
+Excerpt — not a complete module
+
+```html
+<figure
+  slChart
+  title="Receita"
+  [data]="monthly"
+  [series]="revenue"
+  [x]="{ field: 'month' }"
+></figure>
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | figure | yes |
+| `header` | figcaption | no |
+| `title` | div | no |
+| `description` | div | no |
+| `help` | button | no |
+| `help-content` | div | no |
+| `actions` | div | no |
+| `toolbar` | div | no |
+| `zoom-reset` | button | no |
+| `view-toggle` | button | no |
+| `fullscreen-toggle` | button | no |
+| `menu-trigger` | button | no |
+| `menu` | div | no |
+| `menu-item` | button | no |
+| `legend` | div | no |
+| `legend-item` | button | no |
+| `legend-marker` | span | no |
+| `legend-label` | span | no |
+| `legend-value` | span | no |
+| `legend-more` | button | no |
+| `plot` | div | yes |
+| `canvas` | div | yes |
+| `crosshair` | div | no |
+| `marker` | span | no |
+| `center` | div | no |
+| `center-value` | span | no |
+| `center-label` | span | no |
+| `tooltip` | div | no |
+| `tooltip-title` | div | no |
+| `tooltip-item` | div | no |
+| `tooltip-marker` | span | no |
+| `tooltip-label` | span | no |
+| `tooltip-value` | span | no |
+| `tooltip-total` | div | no |
+| `skeleton` | div | no |
+| `empty` | div | no |
+| `error` | div | no |
+| `summary` | div | yes |
+| `table-region` | div | no |
+| `table` | table | no |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `data` | `readonly ChartRecord[]` | [] | slChart | One record per category or per point. Fields are named by x and by each series |
+| `series` | `readonly ChartSeries[]` | [] | slChart | What is drawn: kind, field, label, and how. Order is legend order and colour order |
+| `x` | `ChartXAxis` | — | slChart | The category field, and its type (category, time, value), label, format and extent |
+| `y` | `ChartYAxis \| [ChartYAxis, ChartYAxis]` | — | slChart | The value axis, or the start and end axes: label, format, scale, extent |
+| `min` | `number` | — | x, y | The lowest value the axis must hold. The data widens the extent, never narrows it |
+| `max` | `number` | — | x, y | The highest value the axis must hold |
+| `scale` | `'linear' \| 'log'` | linear | y | A logarithmic value axis |
+| `orientation` | `'vertical' \| 'horizontal'` | vertical | slChart | Which way categories run. Horizontal bars for a ranking with long names |
+| `stackMode` | `'normal' \| 'percent'` | normal | slChart | How series that share a stack add up: to a total, or to 100 % |
+| `curve` | `'linear' \| 'monotone' \| 'step'` | linear | series | How a line or an area passes through its points |
+| `stroke` | `'solid' \| 'dashed'` | solid | series | A dashed line for a reference |
+| `markers` | `'none' \| 'last' \| 'all'` | none | series | Dots on a line: none, the last point, or every point |
+| `annotations` | `readonly ChartAnnotation[]` | — | slChart | Lines and bands on either axis, labelled, in a tone. On the category axis a value names a category by its key or its x value; one that names none is not drawn |
+| `recordKey` | `string` | — | slChart | The field that names a record when x is a value axis, for points and selection |
+| `locale` | `string` | — | slChart | BCP 47, for every number and date; the language in force when absent |
+| `title` | `string` | — | slChart | The caption, and the plot’s accessible name. Taken from the native title attribute, which the figure does not keep |
+| `description` | `string` | — | slChart | One line under the title |
+| `help` | `string` | — | slChart | A note behind an information control beside the title |
+| `messages` | `Partial<ChartMessages>` | — | slChart | Words laid over the language in force, key by key: every word the chart writes or says, with {slots} |
+| `size` | `'sm' \| 'md' \| 'lg'` | md | slChart | The plot height: 192, 256 or 384 pixels |
+| `variant` | `'plain' \| 'card'` | plain | slChart | On the page’s surface, or on its own card that fills its grid cell |
+| `palette` | `'categorical' \| 'sequential' \| 'focus'` | categorical | slChart | Which ramp the eight slots take |
+| `toolbar` | `'visible' \| 'hover' \| 'none'` | visible | slChart | When the toolbar shows: always, on hover or focus within, or never |
+| `grid` | `'horizontal' \| 'vertical' \| 'both' \| 'none'` | horizontal | slChart | Which grid lines are drawn |
+| `texture` | `boolean` | false | slChart | A pattern per slot, as a second channel beside colour |
+| `renderer` | `'auto' \| 'svg' \| 'canvas'` | auto | slChart | SVG, or canvas past a few thousand points |
+| `sampling` | `'auto' \| 'none'` | auto | slChart | Downsamples a long line for the screen; the table keeps every value |
+| `animate` | `boolean` | true | slChart | Transitions; off under reduced motion regardless |
+| `legend` | `boolean` | true | slChart | Whether the legend is drawn |
+| `legendInteractive` | `boolean` | true | slChart | Legend items as toggles, or as a static key |
+| `legendValues` | `boolean` | false | slChart | Each item’s value at the active point, or its last |
+| `legendOverflow` | `'collapse' \| 'wrap'` | collapse | slChart | One line and +N, or as many lines as it takes |
+| `trigger` | `'axis' \| 'item' \| 'none'` | axis | slChart | What the tooltip reads: the category, the point, or nothing. item for pie and scatter |
+| `tooltip` | `ChartTooltipSettings` | — | slChart | sort, total and indicator for the default tooltip |
+| `indicator` | `'dot' \| 'line' \| 'none'` | dot | tooltip | The mark beside each tooltip row |
+| `sort` | `'none' \| 'asc' \| 'desc'` | none | tooltip | Tooltip rows in series order, or by value |
+| `zoomable` | `boolean` | false | slChart | Drag, Ctrl+wheel and + − 0 zoom the x axis |
+| `selectable` | `boolean` | false | slChart | A click or Enter selects a point |
+| `loading` | `boolean` | false | slChart | The skeleton of the kind being loaded, in the plot’s box |
+| `error` | `boolean` | false | slChart | The data did not arrive |
+| `hidden` | `model<readonly string[]>` | [] | slChart | The series ids the legend hides; bind [(hidden)] to own it |
+| `activePoint` | `model<ChartPoint \| null>` | null | slChart | The point being read; bind [(activePoint)] to share it between charts |
+| `selection` | `model<ChartPoint \| null>` | null | slChart | The selected point |
+| `zoom` | `model<ChartZoom>` | { start: 0, end: 1 } | slChart | The visible fraction of the x domain |
+| `tableOpen` | `model<boolean>` | false | slChart | Whether the plot shows the table |
+| `fullscreen` | `model<boolean>` | false | slChart | Whether the chart has the screen |
+| `slChartTooltip` | `ng-template, let-context let-model="model"` | — | slChart | The tooltip’s content; the box, placement and dock stay |
+| `slChartLegendItem` | `ng-template, let-entry let-value="value" let-current="current"` | — | slChart | One legend item’s content; the toggle and its wiring stay |
+| `slChartCenter` | `ng-template, let-model` | — | slChart | The middle of a donut |
+| `slChartEmpty` | `ng-template, let-reason ('no-data' \| 'all-hidden')` | — | slChart | The empty state |
+| `slChartError` | `ng-template` | — | slChart | The error state |
+| `slChartActions` | `content projection` | — | slChart | The consumer’s own controls, before the toolbar |
+| `extendOption` | `(option) => option` | — | slChart | The engine’s option before it is drawn: the escape hatch for what the contract does not say |
+| `#chart="slChart"` | `SlChart` | — | Template | focus(), resetZoom(), toDataURL() and toCsv() |
+| `provideChartDefaults` | `ChartDefaults` | — | Application | size, variant, palette, toolbar, renderer, grid, legendOverflow, tooltip and animate, once; an input still wins |
+| `CHART_ENGINE` | `InjectionToken` | mountChartEngine | Application | The engine the chart mounts; a test provides a recording one |
+| `preloadChartEngine` | `(kinds?: ChartKind[]) => Promise<void>` | — | Application | Fetches the engine chunks ahead of the first chart, in a route resolver |
+
+## Events
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `hiddenChange, hiddenChangeRequest` | `readonly string[], ChangeRequest<readonly string[]>` | The request before a series is hidden or shown from the legend, from “Show all”, or isolated with Shift; the model change after it commits. Reasons: pointer, keyboard, programmatic. cancel() refuses it. |
+| `activePointChange, activePointChangeRequest` | `ChartPoint \| null, ChangeRequest<ChartPoint \| null>` | When the pointer or the arrows reach a point, and when it leaves: pointer, keyboard, blur, escape. The value two charts share to move together. |
+| `selectionChange, selectionChangeRequest` | `ChartPoint \| null, ChangeRequest<ChartPoint \| null>` | With selectable, on a click or Enter on a point, and on Escape: pointer, keyboard, escape, programmatic. |
+| `zoomChange, zoomChangeRequest` | `ChartZoom, ChangeRequest<ChartZoom>` | With zoomable, on a drag, a wheel with Ctrl, + or −, 0 or the reset control: pointer, keyboard, clear, escape, programmatic. |
+| `tableOpenChange, tableOpenChangeRequest` | `boolean, ChangeRequest<boolean>` | Before the plot switches between the drawing and the table: pointer, keyboard, escape, programmatic. |
+| `fullscreenChange, fullscreenChangeRequest` | `boolean, ChangeRequest<boolean>` | Before the chart takes or gives back the screen, and when the browser leaves full screen on its own: pointer, keyboard, escape, programmatic. |
+| `retry` | `void` | On the retry action of the error state. |
+
+## Axes and defaults
+
+| Axis | Values | Default |
+| --- | --- | --- |
+| `kind` | `line`, `area`, `bar`, `pie`, `scatter` | — |
+| `size` | `sm`, `md`, `lg` | `md` |
+| `orientation` | `vertical`, `horizontal` | `vertical` |
+| `stackMode` | `normal`, `percent` | `normal` |
+| `curve` | `linear`, `monotone`, `step` | `linear` |
+| `stroke` | `solid`, `dashed` | `solid` |
+| `markers` | `none`, `last`, `all` | `none` |
+| `grid` | `horizontal`, `vertical`, `both`, `none` | `horizontal` |
+| `trigger` | `axis`, `item`, `none` | `axis` |
+| `indicator` | `dot`, `line`, `none` | `dot` |
+| `sort` | `none`, `asc`, `desc` | `none` |
+| `renderer` | `auto`, `svg`, `canvas` | `auto` |
+| `scale` | `linear`, `log` | — |
+| `xType` | `category`, `time`, `value` | — |
+| `tone` | `neutral`, `accent`, `secondary`, `success`, `warning`, `danger` | — |
+| `slot` | `1`, `2`, `3`, `4`, `5`, `6`, `7`, `8` | — |
+| `variant` | `plain`, `card` | `plain` |
+| `toolbar` | `visible`, `hover`, `none` | `visible` |
+| `palette` | `categorical`, `sequential`, `focus` | `categorical` |
+| `legendOverflow` | `collapse`, `wrap` | `collapse` |
+
+## Rules
+
+- The figure is named by its caption, and the plot is one tab stop with role="group", aria-roledescription="chart", the title as its name and a generated summary as its description: kind, series, points, and the range, minimum and maximum of each series.
+- Inside the plot the keyboard follows an adaptation of the APG Grid pattern: Left and Right move along the categories, Up and Down between series, Home and End to the ends, Page keys by a tenth; Enter selects, + − and 0 zoom, Escape clears. The tooltip is aria-hidden, and a polite live region says the point reached — only the last one, so holding an arrow does not queue twelve sentences.
+- The legend is a toolbar of toggle buttons with a roving tab stop: aria-pressed says whether a series is drawn, Enter hides it, Shift+Enter shows it alone, and the live region confirms the change.
+- Every chart has a table view with the same numbers in their formats, reachable from the toolbar or the menu; it is the complete reading for anyone the drawing does not serve.
+- Colour is never the only channel: series differ in stroke and marker shape, texture adds a pattern per slot, and under forced colours the drawing is redrawn in system colours with the legend markers kept by mask.
+- The eight slots of the data scale keep adjacent colours apart under simulated protanopia and deuteranopia in every scheme, and each clears 3:1 against the surface.
+
+## Tokens
+
+`--slotted-border-strong`, `--slotted-border-subtle`, `--slotted-border-width-medium`, `--slotted-border-width-thick`, `--slotted-border-width-thin`, `--slotted-chart-area-opacity`, `--slotted-chart-axis-color`, `--slotted-chart-band-color`, `--slotted-chart-bar-radius`, `--slotted-chart-card-padding-block`, `--slotted-chart-card-padding-inline`, `--slotted-chart-card-radius`, `--slotted-chart-color-1`, `--slotted-chart-color-2`, `--slotted-chart-color-3`, `--slotted-chart-color-4`, `--slotted-chart-color-5`, `--slotted-chart-color-6`, `--slotted-chart-color-7`, `--slotted-chart-color-8`, `--slotted-chart-crosshair-color`, `--slotted-chart-focus-color`, `--slotted-chart-gap`, `--slotted-chart-grid-color`, `--slotted-chart-inset`, `--slotted-chart-label-color`, `--slotted-chart-label-size`, `--slotted-chart-line-width`, `--slotted-chart-marker-size`, `--slotted-chart-plot-block-size`, `--slotted-chart-plot-block-size-lg`, `--slotted-chart-plot-block-size-sm`, `--slotted-chart-radius`, `--slotted-chart-reference-color`, `--slotted-chart-sequential-color`, `--slotted-chart-skeleton-hole`, `--slotted-chart-surface`, `--slotted-chart-tooltip-surface`, `--slotted-control-border-color`, `--slotted-control-font-size-sm`, `--slotted-control-gap-md`, `--slotted-control-gap-sm`, `--slotted-control-height-sm`, `--slotted-control-inner-size-sm`, `--slotted-control-radius`, `--slotted-data-1`, `--slotted-data-2`, `--slotted-data-3`, `--slotted-data-4`, `--slotted-data-5`, `--slotted-data-6`, `--slotted-data-7`, `--slotted-data-8`, `--slotted-duration-instant`, `--slotted-duration-long`, `--slotted-duration-short`, `--slotted-easing-standard`, `--slotted-focus-ring-color`, `--slotted-focus-ring-offset`, `--slotted-focus-ring-width`, `--slotted-font-family-heading`, `--slotted-font-family-sans`, `--slotted-font-size-2xl`, `--slotted-font-size-lg`, `--slotted-font-size-md`, `--slotted-font-size-sm`, `--slotted-font-size-xl`, `--slotted-font-size-xs`, `--slotted-font-weight-medium`, `--slotted-font-weight-semibold`, `--slotted-line-height-2xl`, `--slotted-line-height-lg`, `--slotted-line-height-md`, `--slotted-line-height-sm`, `--slotted-line-height-xs`, `--slotted-radius-full`, `--slotted-radius-lg`, `--slotted-radius-md`, `--slotted-radius-sm`, `--slotted-radius-xs`, `--slotted-shadow-md`, `--slotted-space-1`, `--slotted-space-12`, `--slotted-space-2`, `--slotted-space-3`, `--slotted-space-4`, `--slotted-space-5`, `--slotted-space-6`, `--slotted-space-8`, `--slotted-space-9`, `--slotted-surface`, `--slotted-surface-raised`, `--slotted-target-comfortable`, `--slotted-target-min`, `--slotted-text`, `--slotted-text-muted`, `--slotted-tone-accent-text`, `--slotted-tone-danger-text`, `--slotted-tone-secondary-subtle-hover`, `--slotted-tone-secondary-surface`, `--slotted-tone-secondary-text`, `--slotted-tone-success-text`, `--slotted-tone-warning-text`, `--slotted-z-index-overlay`, `--slotted-z-index-popover`
+
+## Examples
+
+See [chart.examples.md](./chart.examples.md).