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

package/docs/slider.md

@@ -0,0 +1,261 @@
+<!-- index: ./index.md -->
+# slider
+
+`data-ui="slider"` · Picks a value or range along a track.
+
+## Import
+
+```ts
+import { provideSliderDefaults, SlSlider } from '@slotted/angular/slider';
+```
+
+Selector: `[slSlider]` · exportAs: `slSlider`
+
+## Minimal example
+
+Excerpt — not a complete module
+
+```html
+<div slField>
+  <label slFieldLabel>Volume</label>
+  <div slSlider [defaultValue]="40" [max]="1" [step]="0.01" [format]="percent"></div>
+  <p slFieldDescription>Vale para todos os alertas do aplicativo.</p>
+</div>
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | the element carrying slSlider | yes |
+| `output` | output | no |
+| `control` | div | yes |
+| `track` | div | yes |
+| `indicator` | div | yes |
+| `mark` | span | no |
+| `mark-label` | span | no |
+| `thumb` | div | yes |
+| `input` | input[type=range] | yes |
+| `bubble` | span | no |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `value` | `number \| number[]` | — | slSlider | Present means the consumer owns the value, for the life of the component. An array makes a range, and the shape handed in is the shape every request carries back |
+| `defaultValue` | `number \| number[]` | 0 | slSlider | What an uncontrolled slider starts from, read once. A native form reset returns to it |
+| `min` | `number` | 0 | slSlider | The smallest value the scale holds, and where the step grid starts |
+| `max` | `number` | 100 | slSlider | The largest value the scale holds |
+| `step` | `number` | 1 | slSlider | The amount the arrows move by, and the grid a track press snaps to. A step of nought or less makes the scale continuous |
+| `largeStep` | `number` | step * 10 | slSlider | The amount Shift and the page keys move by. It is the family’s rather than the browser’s, because Chrome moves Page Up by a tenth of the range and Firefox by one step |
+| `minStepsBetween` | `number` | 0 | slSlider | How many steps must stay between two neighbouring thumbs. It becomes each input’s own min and max, so the clamping is the platform’s and the announced range is right |
+| `origin` | `'min' \| 'max' \| number` | min | slSlider | Where the filled portion starts. A point on the scale makes a balance control that fills outward from it |
+| `marks` | `number[] \| { value, label? }[]` | — | slSlider | The ticks beside the rail. A mark that carries a label reserves the room for it and becomes the thumb’s aria-valuetext at that value |
+| `format` | `Intl.NumberFormatOptions` | — | slSlider | How the value is written, in the read-out, in the bubble and in aria-valuetext. Currency and percent are formattings of one numeric type, not types of their own |
+| `locale` | `string` | the language in force | slSlider | BCP 47. It decides the decimal separator, the grouping and the numbering system |
+| `orientation` | `'horizontal' \| 'vertical'` | horizontal | slSlider, provideSliderDefaults | Which axis the scale runs along. A vertical scale puts its minimum at the bottom |
+| `size` | `'sm' \| 'md' \| 'lg'` | md | slSlider, provideSliderDefaults | The type step, read from the field first when there is one, then from the token. The thumb, the type and the target grow with it and the rail does not |
+| `valueLabel` | `'auto' \| 'always' \| 'none'` | auto | slSlider, provideSliderDefaults | When the value stands on the thumb. none withdraws the read-out as well, which is what a scale whose values are words needs |
+| `thumbLabels` | `string[]` | — | slSlider | The accessible name of each thumb, in order. A range whose two thumbs share one name gives a reader two sliders called the same thing |
+| `disabled` | `boolean` | from the field, or false | slSlider | Unstated rather than false, so the control defers to the field around it. Stated, it wins, and it is the native attribute on every thumb. A reactive form’s own disable() answers it too |
+| `readOnly` | `boolean` | from the field, or false | slSlider | Unstated rather than false. input[type=range] has no readonly, so the family refuses every pointer and key change and writes aria-readonly instead. The value stays focusable and stays submitted |
+| `invalid` | `boolean` | from the field, or false | slSlider | Unstated rather than false. Writes aria-invalid on every thumb and data-invalid on the root |
+| `required` | `boolean` | — | slSlider | The element’s own attribute, passed through and never written by the family. A field marks necessity with aria-required instead, because the native attribute engages browser constraint validation |
+| `name / form / id / aria-label` | `attribute` | — | slSlider | Read with HostAttributeToken before any binding computes, so a static attribute a consumer wrote survives. name and form reach every thumb’s input, so a range submits two values under one name |
+| `exportAs` | `'slSlider'` | — | the template | Reaches the instance, and through it focusThumb(index) and sliderElement — the one action a value cannot express and the element it acts on |
+| `ControlValueAccessor` | `formControl, formControlName, ngModel` | — | slSlider | The component is the control. A reactive form owns the value, disable() reaches the whole scale, and Angular 22’s Signal Forms bind through the same accessor, so [field] works with no second integration |
+| `provideSliderDefaults` | `{ size, orientation, valueLabel }` | — | an injector | The three decisions an application takes once. The locale comes from the language in force (provideSlotted) |
+| `slField` | `the field around it` | — | an ancestor | What the control reads to wire itself: the identifier, the description and the four shared states. A control that wires itself cannot be written wrong |
+| `styleUrl` | `the one authored stylesheet` | — | slSlider | ViewEncapsulation.None over packages/styles/src/slider/slider.css — the same file React imports, so the two bindings cannot drift apart visually |
+
+## Events
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `valueChange` | `ChangeRequest<number \| number[]>` | Before the value moves, once per step and once per pointer sample. The request carries the new value, the value it replaces, the reason — "pointer", "keyboard" or "programmatic" — the originating event, and cancel(), which refuses the move before anything commits. There is no [(value)]: a two-way binding has one slot and can carry none of those, and a form gets the same movement through ControlValueAccessor. |
+| `valueCommit` | `number \| number[]` | Once, when a drag ends or a key settles the value. A drag emits a hundred changes and one commit, and this is the one to save on, to fetch on, and to put in a history entry. |
+| `ControlValueAccessor` | `the control’s own value` | Whenever the value moves under formControl, formControlName or ngModel. setDisabledState is answered as well, so a form that disables the control disables the whole scale. |
+
+## Axes and defaults
+
+| Axis | Values | Default |
+| --- | --- | --- |
+| `size` | `sm`, `md`, `lg` | `md` |
+| `orientation` | `horizontal`, `vertical` | `horizontal` |
+| `valueLabel` | `auto`, `always`, `none` | `auto` |
+
+## Rules
+
+- The pattern is the WAI-ARIA APG’s Slider and Slider (Multi-Thumb) (w3.org/WAI/ARIA/apg/patterns/slider/), and the role comes from the platform: every thumb is an input[type=range], the element Angular Material’s own slider uses, so role="slider", aria-valuenow, aria-valuemin and aria-valuemax are the element’s own and cannot drift from it. The element is opacity: 0 and pointer-events: none — invisible and unhittable, never hidden: it keeps focus, the tab order and its place in the accessibility tree.
+- Each thumb’s own min and max follow its neighbour, which is the multi-thumb pattern’s requirement that the announced range of a dependent slider be updated when the value changes. The tab order stays the array’s order however the thumbs move, which is the pattern’s second requirement.
+- The whole keyboard table is the family’s: arrows by step, Shift and the page keys by largeStep, Home and End to this thumb’s own bounds. The inline arrows follow the reading direction and the block arrows do not — a scale has a direction and bidi is not it — which is what the pattern’s note about reversing the direction means in a mirrored document.
+- aria-valuetext carries the formatted string, because aria-valuenow alone announces 1480 for a scale showing R$ 1.480,00. A mark that carries a label becomes that string at its own value, which is exactly the case the pattern names for the property.
+- aria-required, never the native required. The native attribute engages browser constraint validation and changes submit behaviour, which the library must not impose as a side effect of describing a field. disabled is native, because that is what the word means; readonly is not, because input[type=range] does not answer it.
+- The target is the band rather than the thumb: it is floored at 24 CSS pixels in the cross axis, which is WCAG 2.2 SC 2.5.8, and a press anywhere on it moves the nearest thumb and starts a drag.
+- Nothing is said by colour alone. Invalid is announced by aria-invalid and said in words by the field’s error, and in the high-contrast scheme the rail is a white channel with a black edge so the fill is still visible inside it.
+
+## Tokens
+
+`--slotted-border-strong`, `--slotted-border-width-thick`, `--slotted-border-width-thin`, `--slotted-control-border-color`, `--slotted-control-border-width`, `--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-icon-size-lg`, `--slotted-control-icon-size-md`, `--slotted-control-icon-size-sm`, `--slotted-control-invalid-edge-width`, `--slotted-control-shadow`, `--slotted-control-shadow-focus-geometry`, `--slotted-control-transition-duration`, `--slotted-control-transition-easing`, `--slotted-disabled-background`, `--slotted-disabled-border`, `--slotted-disabled-foreground`, `--slotted-focus-ring-color`, `--slotted-focus-ring-color-invalid`, `--slotted-focus-ring-offset`, `--slotted-focus-ring-width`, `--slotted-font-size-xs`, `--slotted-font-weight-medium`, `--slotted-line-height-sm`, `--slotted-line-height-xs`, `--slotted-radius-full`, `--slotted-radius-sm`, `--slotted-slider-bubble-background`, `--slotted-slider-bubble-color`, `--slotted-slider-color`, `--slotted-slider-disabled-border-color`, `--slotted-slider-disabled-indicator-color`, `--slotted-slider-disabled-thumb-color`, `--slotted-slider-disabled-track-color`, `--slotted-slider-indicator-color`, `--slotted-slider-invalid-edge-width`, `--slotted-slider-invalid-focus-ring-color`, `--slotted-slider-invalid-indicator-color`, `--slotted-slider-invalid-thumb-border-color`, `--slotted-slider-length`, `--slotted-slider-mark-color`, `--slotted-slider-mark-label-color`, `--slotted-slider-output-color`, `--slotted-slider-readonly-indicator-color`, `--slotted-slider-readonly-thumb-border-color`, `--slotted-slider-thumb-border-color`, `--slotted-slider-thumb-color`, `--slotted-slider-thumb-hover-background`, `--slotted-slider-thumb-shadow`, `--slotted-slider-thumb-size`, `--slotted-slider-track-border-color`, `--slotted-slider-track-color`, `--slotted-slider-track-size`, `--slotted-space-1`, `--slotted-space-2`, `--slotted-space-3`, `--slotted-surface`, `--slotted-surface-inverse`, `--slotted-surface-sunken`, `--slotted-target-min`, `--slotted-text`, `--slotted-text-inverse`, `--slotted-text-muted`, `--slotted-tone-accent-solid`, `--slotted-tone-accent-surface`, `--slotted-tone-danger-border`, `--slotted-tone-danger-solid`
+
+## Examples
+
+### The step the control sits at
+
+Three steps, and inside a field the control takes the field’s rather than its own. Only the thumb, the type and the target grow: the rail keeps its weight, because a rail is a line and not a control.
+
+Excerpt — not a complete module
+
+```html
+<div slSlider size="sm" [defaultValue]="25"></div>
+<div slSlider size="md" [defaultValue]="50"></div>
+<div slSlider size="lg" [defaultValue]="75"></div>
+
+<!-- Inside a field the field decides, and the control follows. -->
+<div slField size="sm">
+  <div slSlider [defaultValue]="40"></div>
+</div>
+```
+
+### Which axis the scale runs along
+
+A vertical scale puts its minimum at the bottom, where the browser’s own vertical range input puts it. The arrows follow: Up increases in both orientations, and only the inline pair mirrors in a right-to-left document.
+
+Excerpt — not a complete module
+
+```html
+<div slSlider orientation="vertical" aria-label="Agudos" [defaultValue]="70"></div>
+<div slSlider orientation="vertical" aria-label="Médios" [defaultValue]="35"></div>
+<div slSlider orientation="vertical" aria-label="Graves" [defaultValue]="50"></div>
+```
+
+### Two thumbs, and the distance between them
+
+An array of values makes a range. Each thumb’s own min and max follow its neighbour, so the two cannot cross and a screen reader is told the range each one actually has — which is what the multi-thumb pattern requires and what clamping in script leaves wrong.
+
+Excerpt — not a complete module
+
+```html
+<div
+  slSlider
+  name="preco"
+  [defaultValue]="[240, 780]"
+  [max]="1000"
+  [step]="10"
+  [minStepsBetween]="2"
+  [thumbLabels]="['Preço mínimo', 'Preço máximo']"
+></div>
+```
+
+### A scale a reader can read
+
+Marks are ruler ticks beside the rail rather than dots on it, so a tick never has to be legible against the fill and against the empty channel at once. A label of two words wraps rather than running into its neighbour, and one long word overflows its box rather than being clipped: nothing on this scale leaves the DOM.
+
+Excerpt — not a complete module
+
+```html
+<div slSlider [defaultValue]="50" [step]="25" [marks]="quality"></div>
+
+<!-- Numbers alone draw ticks and reserve no room for labels. -->
+<div slSlider [defaultValue]="6" [max]="10" [marks]="[2, 4, 6, 8]"></div>
+```
+
+### Where the fill starts
+
+A gain control is not a volume: nought is in the middle and the fill runs outward from it in whichever direction the value went. origin takes a point on the scale as well as either of its ends.
+
+Excerpt — not a complete module
+
+```html
+<div slSlider [defaultValue]="3" [min]="-10" [max]="10" [origin]="0" [marks]="zero"></div>
+```
+
+### What the value is written as
+
+The number is a domain value and the string is a formatting of it, through the same Intl.NumberFormat the number field uses — so a currency on a slider and a currency in a field beside it cannot disagree about a decimal comma.
+
+Excerpt — not a complete module
+
+```html
+<div
+  slSlider
+  locale="pt-BR"
+  [defaultValue]="1480"
+  [max]="4000"
+  [step]="20"
+  [format]="{ currency: 'BRL', style: 'currency' }"
+></div>
+```
+
+### Where the number stands
+
+auto shows the bubble while a thumb is dragged or focused, always keeps it there, and none withdraws both the bubble and the read-out. The room the bubble stands in is reserved either way, so nothing moves when a drag begins.
+
+Excerpt — not a complete module
+
+```html
+<div slSlider valueLabel="auto" [defaultValue]="40"></div>
+<div slSlider valueLabel="always" [defaultValue]="40"></div>
+
+<!-- A value that is a sentence belongs in a label of the consumer's own. -->
+<div slSlider valueLabel="none" [defaultValue]="2" [max]="2" [marks]="entregas"></div>
+```
+
+### Every state the family paints
+
+Hover lifts the thumb’s fill, press grows it, focus rings it. Invalid reddens the fill and the thumb and retargets the ring; read-only steps the scale onto a neutral ink and keeps every value legible; disabled mutes all of it and answers nothing.
+
+Excerpt — not a complete module
+
+```html
+<div slSlider [defaultValue]="62"></div>
+<div slSlider invalid [defaultValue]="92"></div>
+<div slSlider readOnly [defaultValue]="30"></div>
+<div slSlider disabled [defaultValue]="30"></div>
+```
+
+### Content the family did not choose
+
+A five-label scale at 240 pixels, a mark label of four words, a negative range and a value written in a locale that groups with a full stop. Nothing is truncated and nothing is taken out of the DOM.
+
+Excerpt — not a complete module
+
+```html
+<div
+  slSlider
+  locale="pt-BR"
+  [defaultValue]="[-1480, 2960]"
+  [min]="-4000"
+  [max]="4000"
+  [step]="20"
+  [thumbLabels]="['Saldo mínimo', 'Saldo máximo']"
+></div>
+```
+
+### In a field, in a reactive form, and beside a number
+
+The label, the description, the error and the identifier arrive from the field with nothing written. formControl puts the value in a reactive form, name submits one value per thumb, and a number field beside the scale is the pairing the guide recommends when precision matters.
+
+Excerpt — not a complete module
+
+```html
+<div slField [invalid]="true">
+  <label slFieldLabel>Participação</label>
+  <div slSlider name="participacao" [formControl]="share" #scale="slSlider"></div>
+  <p slFieldError>A participação não pode passar de noventa por cento.</p>
+</div>
+
+<button slButton type="button" (click)="scale.focusThumb(0)">Ir ao valor</button>
+```
+
+### What the keyboard does, and which arrows mirror
+
+Arrows step, Shift and the page keys move by the large amount, Home and End reach this thumb’s own bounds rather than the scale’s. The family binds the table itself because browsers disagree about Page Up on a range input.
+
+Excerpt — not a complete module
+
+```html
+<!-- ArrowRight/ArrowLeft follow the reading direction; ArrowUp/ArrowDown do not. -->
+<!-- Shift or PageUp/PageDown: largeStep. Home: this thumb's min. End: its max. -->
+<div slSlider [defaultValue]="[20, 80]" [step]="1" [largeStep]="10"></div>
+```