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

package/docs/rating.md

@@ -0,0 +1,435 @@
+<!-- index: ./index.md -->
+# rating
+
+`data-ui="rating"` · Star rating input, display and summary.
+
+## Import
+
+```ts
+import {
+  provideRating,
+  SlRating,
+  SlRatingCaption,
+  SlRatingDisplay,
+  SlRatingSummary,
+  SlRatingSymbol,
+} from '@slotted/angular/rating';
+```
+
+Selector: `div[slRating]` · exportAs: `slRating`
+
+Selector: `div[slRatingDisplay]` · exportAs: `slRatingDisplay`
+
+Selector: `section[slRatingSummary]` · exportAs: `slRatingSummary`
+
+## Minimal example
+
+Excerpt — not a complete module
+
+```html
+<div slRating aria-label="Qualidade do som" [(value)]="nota">
+  <ng-template slRatingCaption let-value="value" let-preview="preview">
+    {{ palavras[preview ?? value ?? 0] }}
+  </ng-template>
+</div>
+```
+
+## Anatomy
+
+### rating
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | the div carrying slRating | yes |
+| `symbols` | div | yes |
+| `item` | span | yes |
+| `input` | input type="radio", one per step | yes |
+| `symbol` | span, holding slIcon and the star glyph | yes |
+| `fill` | span, holding the same glyph | yes |
+| `value` | span aria-hidden="true" | no |
+
+### ratingDisplay
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | the div carrying slRatingDisplay | yes |
+| `symbols` | div | yes |
+| `item` | span | yes |
+| `symbol` | span, holding slIcon and the star glyph | yes |
+| `fill` | span, holding the same glyph | yes |
+| `value` | span aria-hidden="true" | no |
+| `histogram` | span aria-hidden="true" | no |
+| `bar` | span | no |
+| `count` | span aria-hidden="true" | no |
+
+### ratingSummary
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | the section carrying slRatingSummary | yes |
+| `aggregate` | div | yes |
+| `value` | span | no |
+| `scale` | span | no |
+| `insight` | span data-tone | no |
+| `count` | span | yes |
+| `distribution` | ul aria-label | no |
+| `level` | button aria-pressed, or div role="group" | no |
+| `level-label` | span | no |
+| `track` | span aria-hidden="true" | no |
+| `indicator` | span | no |
+| `level-count` | span | no |
+| `plot` | div | no |
+| `field` | div | no |
+| `columns` | div | no |
+| `column` | button aria-pressed, or div role="group" | no |
+| `bar` | span | no |
+| `interval` | span aria-hidden="true" | no |
+| `mean` | span aria-hidden="true" | no |
+| `mean-label` | span | no |
+| `axis` | div aria-hidden="true" | no |
+| `tick` | span | no |
+| `tick-label` | span | no |
+| `tick-share` | span | no |
+| `sentiment` | p | no |
+| `bucket` | span data-tone | no |
+| `swatch` | span aria-hidden="true" | no |
+
+## Props
+
+### rating
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `value` | `model<number \| null>` | null | SlRating | The rating, null for none. Put on the grid of the scale when drawn: 7 of 5 is 5, 3,2 on whole steps is 4, NaN is none |
+| `max` | `number` | 5 | SlRating, provideRating | How many symbols the row has |
+| `step` | `1 \| 0.5` | 1 | SlRating | The smallest move. A half adds a second radio per symbol; smaller fractions are refused because a third of a star is below the minimum target |
+| `clearable` | `boolean` | true | SlRating, provideRating | Whether a press on the checked radio, Backspace or Delete empty the value, with the reason clear |
+| `size` | `'sm' \| 'md' \| 'lg'` | md | SlRating, provideRating | The step of the symbols and the caption. Read from the field or field group first |
+| `tone` | `'accent' \| 'success' \| 'warning' \| 'danger'` | warning | SlRating, provideRating | The colour of a lit symbol. secondary is outside the axis: its solid step is a ground, and a lit star in it reads as unlit |
+| `name` | `string` | generated | SlRating | The submission name every radio shares. Generated when none is written, because an unnamed set of radios is not a group |
+| `form` | `string` | — | SlRating | The form the radios belong to when the rating sits outside it |
+| `disabled` | `boolean` | from the field, or false | SlRating | Native on every radio: the row leaves the tab order. A disabled form control sets it too |
+| `readOnly` | `boolean` | from the field, or false | SlRating | The platform has no read-only radio, so the press and the keys are refused and aria-readonly is announced; every radio stays focusable |
+| `invalid` | `boolean` | from the field, or false | SlRating | Writes aria-invalid and data-invalid, which reddens the edge of every symbol |
+| `required` | `boolean` | from the field, or false | SlRating | Writes aria-required and makes the Validator demand a value. Never the native attribute, which would engage browser constraint validation |
+| `messages` | `Partial<RatingMessages>` | — | SlRating | Words laid over the language in force, key by key. itemLabel names each radio: "{value} out of {max}" |
+| `locale` | `string` | the language in force | SlRating | The locale the radio names are written in: "3,5 de 5" in pt-BR, "3.5 de 5" in en |
+| `slRatingCaption` | `directive` | — | an element or an ng-template | The caption in the value part. On an ng-template its context is { value, preview }, and it is rendered again whenever either moves |
+| `slRatingSymbol` | `directive` | — | an ng-template | Replaces the star in both the symbol and the fill parts. Its context is { index, fill } |
+| `exportAs="slRating"` | `SlRating` | — | a template | Reaches the instance: focus() puts focus on the checked radio, or on the first when none is checked; current() reads the value on the grid of the scale |
+| `ControlValueAccessor and Validator` | `formControl, formControlName, ngModel` | — | the host element | Both on the root, so a form binding goes where the directive is written. The integration React has no equivalent of |
+| `provideRating()` | `{ size, tone, max, clearable, insightThresholds }` | — | an injector | The decisions an application takes once, for all three members. insightThresholds merges key by key; an instance input always wins. The words and the locale come from provideSlotted |
+| `aria-label, aria-describedby, role` | `string` | — | the host element | Static attributes the consumer writes are read before the host bindings; aria-describedby is merged with the field’s description and error |
+
+### ratingDisplay
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `value` | `number` | — | SlRatingDisplay | The number drawn. Any fraction; clamped to the scale, NaN drawn as nought |
+| `max` | `number` | 5 | SlRatingDisplay, provideRating | How many symbols the scale has |
+| `size` | `'sm' \| 'md' \| 'lg'` | md | SlRatingDisplay, provideRating | The step of the symbols and the text |
+| `tone` | `'accent' \| 'success' \| 'warning' \| 'danger'` | warning | SlRatingDisplay, provideRating | The colour of the lit share |
+| `variant` | `'full' \| 'compact' \| 'histogram'` | full | SlRatingDisplay | Every symbol; one lit star with the number; or one star, the number and the distribution |
+| `count` | `number` | — | SlRatingDisplay | How many readings. Written beside the stars and in the accessible name |
+| `distribution` | `readonly number[]` | — | SlRatingDisplay | Counts per level, lowest first, drawn by the histogram variant |
+| `showValue` | `boolean` | true | SlRatingDisplay | Whether the number is written beside the stars |
+| `messages` | `Partial<RatingMessages>` | — | SlRatingDisplay | Words laid over the language in force, key by key: displayLabel and displayLabelWithCount name the image |
+| `locale` | `string` | the language in force | SlRatingDisplay | The locale the number and the count are written in |
+| `aria-label` | `string` | displayLabel | the host element | A static name the consumer writes wins over the family’s sentence |
+| `provideRating()` | `{ size, tone, max }` | — | an injector | Shared with the other two members |
+
+### ratingSummary
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `counts` | `readonly number[]` | — | SlRatingSummary | How many readings each level holds, lowest first. Negative and fractional counts are dropped to their whole non-negative part |
+| `max` | `number` | 5 | SlRatingSummary, provideRating | How many levels the scale has. A level missing from counts holds none; a count past it is dropped |
+| `variant` | `'bars' \| 'spectrum'` | bars | SlRatingSummary | One bar per level, or columns over the scale with the mean, its interval and the buckets |
+| `filterable` | `boolean` | false | SlRatingSummary | Each level or column becomes a toggle button, disabled with zero readings |
+| `selectedLevels` | `model<readonly number[]>` | [] | SlRatingSummary | The pressed levels, ascending. Two-way; every move is asked first |
+| `insightThresholds` | `Partial<RatingInsightThresholds>` | { divided: 0.25, few: 30, margin: 0.5, consensus: 0.8 } | SlRatingSummary, provideRating | Where each conclusion is drawn, merged key by key. margin also decides when the spectrum says its mean is uncertain |
+| `showInsight` | `boolean` | true | SlRatingSummary | Whether the spectrum draws its conclusion. The bars variant draws none |
+| `size` | `'sm' \| 'md' \| 'lg'` | md | SlRatingSummary, provideRating | The step of the text and the rows |
+| `tone` | `'accent' \| 'success' \| 'warning' \| 'danger'` | warning | SlRatingSummary, provideRating | The colour of the stars and the bars |
+| `messages` | `Partial<RatingMessages>` | — | SlRatingSummary | Words laid over the language in force, key by key — every sentence of the summary: summaryCount, summaryEmpty, spectrumCount, spectrumUncertain, levelLabel, distributionLabel, the buckets and the four conclusions |
+| `locale` | `string` | the language in force | SlRatingSummary | The locale every number is written in |
+| `exportAs="slRatingSummary"` | `SlRatingSummary` | — | a template | Reaches the instance: summary() is the whole summariseRatings result, for a caption of one’s own |
+| `provideRating()` | `{ size, tone, max, insightThresholds }` | — | an injector | Shared with the other two members |
+
+## Events
+
+### rating
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `[(value)] and (valueChangeRequest)` | `number \| null, and ChangeRequest<number \| null>` | The request is emitted before the value moves, with the value asked for, the one it replaces, the reason — pointer, keyboard or clear — the event, and cancel(). A request nobody cancelled moves the model, which emits valueChange for the two-way binding. A value equal to the one held is never requested. |
+| `(previewChange)` | `number \| null` | When the pointer enters a radio, with its value, and null when it leaves the rating. It moves nothing the consumer owns, so it is an event and not a model. |
+| `ControlValueAccessor and Validator` | `number \| null` | Whenever the value moves under formControl, formControlName or ngModel. A radio that loses focus marks the control touched, and required reports { required: true } while the value is null. |
+
+### ratingSummary
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `[(selectedLevels)] and (selectedLevelsChangeRequest)` | `readonly number[], and ChangeRequest<readonly number[]>` | The request is emitted before the pressed levels move, with the levels asked for in ascending order, the ones they replace, the reason — pointer, or keyboard for Space and Enter — the event and cancel(). A request nobody cancelled moves the model. |
+
+## Axes and defaults
+
+| Axis | Values | Default |
+| --- | --- | --- |
+| `size` | `sm`, `md`, `lg` | `md` |
+| `tone` | `accent`, `success`, `warning`, `danger` | `warning` |
+| `variant` | `full`, `compact`, `histogram` | `full`, `bars` |
+| `summaryVariant` | `bars`, `spectrum` | — |
+
+## Rules
+
+- The pattern is the WAI-ARIA APG Rating Radio Group example: a radiogroup of native radios, each named "3 de 5" by aria-label. Tab lands on the checked radio or on the first, and Space checks — both the platform’s, because the radios share a name.
+- The arrows are the family’s and they do not wrap: the APG radio example wraps from the last star to the first, and a rating that falls from five to one on one key too many is the defect the APG slider example, Ark, MUI and Mantine all avoid. Home and End reach both ends; PageUp and PageDown are declined, because ten symbols are crossed key by key.
+- The caption is aria-hidden, because the checked radio already announces the value; the glyphs are aria-hidden inside slIcon. Read-only is enforced by refusing the press and the keys, and every radio keeps its tab stop, its focus ring and its contrast.
+- In the light and dark schemes a lit star measures 1,53:1 against the page, the ReUI yellow the family adopted; the value is never left to colour alone, because it is always in the accessible name and usually written beside the row. The high-contrast scheme and forced colours draw a solid edge around every star.
+- The display is one image, role="img", named by its whole value and its count: "Avaliação 4,6 de 5, 1.284 avaliações". The stars, the number and the count inside it are aria-hidden, so a screen reader hears one sentence rather than five images and two numbers.
+- A name the consumer writes as a static aria-label wins, which is how a histogram row says "opiniões divididas" as well as the mean.
+- The number is always written beside the stars unless showValue is false, because a lit share of a star is not a readable quantity for anyone, at any contrast.
+- The summary is a section named by the consumer’s aria-label, so it is a region a screen reader can reach by landmark. The figure is plain text, and the stars inside the aggregate are one image named by the mean.
+- Each level is named whole — "5 estrelas: 1.052 avaliações, 82%" — and the bar, the axis and the mean mark are aria-hidden, because the name already carries what they draw.
+- A filterable level is a native toggle button with aria-pressed, so Space and Enter press it; a level with no readings is disabled rather than offered as a filter that returns nothing.
+- The conclusion and the three buckets are words, not colours: the tone of the pill and of each swatch repeats a sentence that is already written.
+
+## Tokens
+
+`--slotted-border-strong`, `--slotted-border-subtle`, `--slotted-border-width-thick`, `--slotted-border-width-thin`, `--slotted-control-font-family`, `--slotted-control-font-size-lg`, `--slotted-control-font-size-md`, `--slotted-control-font-size-sm`, `--slotted-control-gap-lg`, `--slotted-control-gap-md`, `--slotted-control-gap-sm`, `--slotted-control-height-sm`, `--slotted-control-icon-size-sm`, `--slotted-control-invalid-edge-width`, `--slotted-control-transition-duration`, `--slotted-control-transition-easing`, `--slotted-disabled-background`, `--slotted-disabled-foreground`, `--slotted-duration-instant`, `--slotted-duration-long`, `--slotted-duration-medium`, `--slotted-duration-short`, `--slotted-easing-enter`, `--slotted-easing-exit`, `--slotted-easing-standard`, `--slotted-focus-ring-color`, `--slotted-focus-ring-color-invalid`, `--slotted-focus-ring-offset`, `--slotted-focus-ring-width`, `--slotted-font-size-4xl`, `--slotted-font-size-xs`, `--slotted-font-weight-medium`, `--slotted-font-weight-regular`, `--slotted-font-weight-semibold`, `--slotted-highlight-tint-opacity`, `--slotted-line-height-4xl`, `--slotted-line-height-md`, `--slotted-line-height-xs`, `--slotted-radius-full`, `--slotted-radius-sm`, `--slotted-radius-xs`, `--slotted-rating-active-background`, `--slotted-rating-bar-color`, `--slotted-rating-bar-size`, `--slotted-rating-edge`, `--slotted-rating-empty-color`, `--slotted-rating-gap`, `--slotted-rating-hover-background`, `--slotted-rating-invalid-color`, `--slotted-rating-invalid-edge-width`, `--slotted-rating-lit-color`, `--slotted-rating-symbol-size`, `--slotted-space-1`, `--slotted-space-10`, `--slotted-space-12`, `--slotted-space-2`, `--slotted-space-3`, `--slotted-space-4`, `--slotted-space-5`, `--slotted-space-6`, `--slotted-space-7`, `--slotted-space-8`, `--slotted-space-9`, `--slotted-surface-inverse`, `--slotted-target-comfortable`, `--slotted-target-min`, `--slotted-text`, `--slotted-text-inverse`, `--slotted-text-muted`, `--slotted-tone-accent-solid`, `--slotted-tone-danger-border`, `--slotted-tone-danger-solid`, `--slotted-tone-danger-surface`, `--slotted-tone-danger-text`, `--slotted-tone-secondary-border`, `--slotted-tone-secondary-subtle-active`, `--slotted-tone-secondary-subtle-hover`, `--slotted-tone-secondary-surface`, `--slotted-tone-success-border`, `--slotted-tone-success-solid`, `--slotted-tone-success-surface`, `--slotted-tone-success-text`, `--slotted-tone-warning-border`, `--slotted-tone-warning-solid`, `--slotted-tone-warning-surface`, `--slotted-tone-warning-text`
+
+## Examples
+
+### Half a star at a time
+
+With step 0.5 each star holds two radios, and the inline-start half of the star asks for the half value. The arrow keys stop ten times on five stars, and each radio is named "3,5 de 5" in the locale.
+
+Excerpt — not a complete module
+
+```html
+<div slRating aria-label="Conforto" [step]="0.5" [value]="3.5"></div>
+```
+
+### Read-only, disabled and invalid
+
+Read-only keeps every tab stop and the lit stars, because the value is real, and refuses the press; disabled removes the row from the tab order; invalid reddens the edge and announces aria-invalid.
+
+Excerpt — not a complete module
+
+```html
+<div slRating aria-label="Nota publicada" readOnly [value]="4"></div>
+<div slRating aria-label="Nota bloqueada" disabled [value]="2"></div>
+<div slRating aria-label="Nota obrigatória" invalid required></div>
+```
+
+### In a field, and in a reactive form
+
+The field supplies the label, the description, the error and the size; the rating is the value accessor and the validator, so required means "choose a rating" and the error appears once the form is touched.
+
+Excerpt — not a complete module
+
+```html
+<div slField required>
+  <label slFieldLabel>Qualidade do som</label>
+  <div slRating formControlName="som"></div>
+  <p slFieldError>Escolha uma nota.</p>
+</div>
+```
+
+### Words for each value, and a scale of ten
+
+The caption is the consumer’s: a word per star on a scale of five, the number on a scale of ten. Each radio’s own name comes from the itemLabel message, which a provider or one instance may reword.
+
+Excerpt — not a complete module
+
+```html
+<div
+  slRating
+  aria-label="Recomendaria a um amigo"
+  [max]="10"
+  [messages]="{ itemLabel: 'Nota {value} de {max}' }"
+>
+  <ng-template slRatingCaption let-value="value" let-preview="preview">
+    {{ preview ?? value ?? 'Sem nota' }}
+  </ng-template>
+</div>
+```
+
+### The keys, which stop at both ends
+
+The arrows raise and lower by one step and stop at the first and the last, Home and End reach both ends, and Backspace or Delete empty a clearable rating. In a right-to-left page the inline arrows swap.
+
+Excerpt — not a complete module
+
+```html
+<!-- ArrowRight/ArrowUp +1 · ArrowLeft/ArrowDown −1 · Home · End
+     Backspace/Delete empty it when clearable -->
+<div slRating aria-label="Atendimento" [value]="3"></div>
+```
+
+### A finger dragged along the row
+
+A touch or a pen dragged along the stars checks the one under it, read by ratingAtPoint, and the root carries data-dragging so the fill follows without its transition. The row keeps vertical panning; a mouse does not scrub.
+
+Excerpt — not a complete module
+
+```html
+<div slRating aria-label="Bateria" size="lg" [(value)]="nota"></div>
+```
+
+### Playground
+
+One display with every axis on it. Move the value by a tenth and watch the last star: the display draws any fraction, because nothing here is a target.
+
+Excerpt — not a complete module
+
+```html
+<div slRatingDisplay [value]="4.6" [count]="1284"></div>
+```
+
+### Any fraction of a star
+
+Each item reads --slotted-rating-fill from ratingFills: 4,6 lights six tenths of the fifth star, 2,25 a quarter of the third. The number beside the stars is always to one place.
+
+Excerpt — not a complete module
+
+```html
+<div slRatingDisplay [value]="4.6"></div>
+<div slRatingDisplay [value]="2.25"></div>
+```
+
+### One star, for a row or a card
+
+compact draws one lit star, the number and the count — the form a product card or a table cell has room for. The name still says the whole value and the scale.
+
+Excerpt — not a complete module
+
+```html
+<div slRatingDisplay variant="compact" size="sm" [value]="4.6" [count]="1284"></div>
+```
+
+### The mean, and the spread behind it
+
+histogram adds one bar per level, each over the largest. Two products at 3,3 read differently: one split between ones and fives, the other spread evenly — which a mean alone would hide.
+
+Excerpt — not a complete module
+
+```html
+<div
+  slRatingDisplay
+  variant="histogram"
+  aria-label="Média 3,3 de 5, 8 avaliações, opiniões divididas"
+  [value]="3.3"
+  [count]="8"
+  [distribution]="[3, 0, 1, 0, 4]"
+></div>
+```
+
+### How many readings the number is made of
+
+count writes the grouped number beside the stars and joins the accessible name through displayLabelWithCount. A rating with no readings says 0,0 and (0) rather than hiding.
+
+Excerpt — not a complete module
+
+```html
+<div slRatingDisplay [value]="4.6" [count]="1284"></div>
+<div slRatingDisplay [value]="0" [count]="0"></div>
+```
+
+### Content the family did not choose
+
+A scale of ten in a narrow column shrinks each star rather than wrapping the row, a count of twelve million is grouped in the locale, and the row mirrors in a right-to-left page.
+
+Excerpt — not a complete module
+
+```html
+<div slRatingDisplay [max]="10" [value]="8.2" [count]="12408117"></div>
+```
+
+### Playground
+
+The aggregate beside one bar per level, highest first. The two blocks stand side by side while both fit and stack when they do not; narrow the window to see the break.
+
+Excerpt — not a complete module
+
+```html
+<section
+  slRatingSummary
+  aria-label="Avaliações dos clientes"
+  [counts]="[9, 18, 47, 158, 1052]"
+></section>
+```
+
+### Levels that filter the reviews
+
+filterable turns each level into a toggle button with aria-pressed; the pressed levels are selectedLevels, asked for first through selectedLevelsChangeRequest. A level nobody chose is disabled, because a filter that returns nothing is a dead end.
+
+Excerpt — not a complete module
+
+```html
+<section
+  slRatingSummary
+  aria-label="Filtrar avaliações"
+  filterable
+  [counts]="contagens"
+  [(selectedLevels)]="niveis"
+></section>
+```
+
+### The spectrum: spread, mean and margin
+
+The same counts as columns over the scale, lowest first, with the mean and its 95% interval laid over them and the readings split into positive, neutral and negative. Eight readings at 3,3 say "média incerta, entre 2,0 e 4,5".
+
+Excerpt — not a complete module
+
+```html
+<section
+  slRatingSummary
+  variant="spectrum"
+  aria-label="Resumo das avaliações"
+  filterable
+  [counts]="[9, 18, 47, 158, 1052]"
+></section>
+```
+
+### One conclusion, the first that holds
+
+Divided when both ends hold a quarter each, few below thirty readings or with a margin of half a level, consensus when four fifths are positive, mixed otherwise. The pill belongs to the spectrum; insightThresholds moves each line; showInsight false removes it.
+
+Excerpt — not a complete module
+
+```html
+<section
+  slRatingSummary
+  variant="spectrum"
+  aria-label="Avaliações"
+  [counts]="[40, 12, 10, 14, 60]"
+  [insightThresholds]="{ divided: 0.3 }"
+></section>
+```
+
+### Nobody has rated it yet
+
+With zero readings the figure and the scale are omitted — a missing mean is not nought — the stars are unlit, the count says "Ainda sem avaliações", and no conclusion is drawn.
+
+Excerpt — not a complete module
+
+```html
+<section slRatingSummary aria-label="Sem avaliações" [counts]="[0, 0, 0, 0, 0]"></section>
+```
+
+### In a narrow column
+
+In a 360-pixel column the aggregate stacks above the distribution and every row of bars keeps its label, its bar and its count aligned with the rows above it.
+
+Excerpt — not a complete module
+
+```html
+<section
+  slRatingSummary
+  size="sm"
+  aria-label="Avaliações"
+  [counts]="[9, 18, 47, 158, 1052]"
+></section>
+```