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

package/docs/segmented-control.md

@@ -0,0 +1,240 @@
+<!-- index: ./index.md -->
+# segmented-control
+
+`data-ui="segmented-control"` · Row of exclusive options, one selected.
+
+## Import
+
+```ts
+import {
+  provideSegmentedControlDefaults,
+  SlSegment,
+  SlSegmentedControl,
+  SlSegmentIcon,
+} from '@slotted/angular/segmented-control';
+```
+
+Selector: `[slSegmentedControl]` · exportAs: `slSegmentedControl`
+
+## Minimal example
+
+Excerpt — not a complete module
+
+```html
+<div slSegmentedControl aria-label="Período do gráfico" defaultValue="week">
+  <label slSegment value="day">Dia</label>
+  <label slSegment value="week">Semana</label>
+  <label slSegment value="month">Mês</label>
+</div>
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | the consumer’s own element, with slSegmentedControl on it | yes |
+| `indicator` | span | no |
+| `item` | label, with slSegment on it | yes |
+| `control` | input type="radio" | yes |
+| `icon` | the consumer’s own element, with slSegmentIcon on it | no |
+| `label` | span | yes |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `value` | `string` | — | slSegmentedControl | Present means the consumer owns the choice, for the life of the component. Absent, the control owns it and starts from defaultValue |
+| `defaultValue` | `string` | — | slSegmentedControl | What an uncontrolled control starts from, read once in ngOnInit. A later change to it does not silently become new state |
+| `name` | `string` | — | slSegmentedControl | The submission name the segments share, and the reason the platform treats them as one radio group. Generated when none is written, from an application-scoped factory so the server and the client agree |
+| `size` | `'sm' \| 'md' \| 'lg'` | md | slSegmentedControl | The control step. The track measures its segments back from it, so the whole control is exactly as tall as the field beside it |
+| `orientation` | `'horizontal' \| 'vertical'` | horizontal | slSegmentedControl | How the segments flow and which way the thumb travels. A horizontal set writes aria-orientation, because radiogroup already implies vertical |
+| `condense` | `'none' \| 'icons'` | none | slSegmentedControl | What the control does when it is narrower than its labels need. icons keeps the marks and hides the words, and makes the control take its parent’s width so there is a width to ask a question about |
+| `fullWidth` | `boolean` | false | slSegmentedControl | Whether the equal columns spread across the whole line. Left alone every column is the widest label’s |
+| `disabled` | `boolean` | false | slSegmentedControl | Unstated rather than false, so the control defers to the field around it and to a form that disables it. Stated, it reaches every radio as the native attribute |
+| `readOnly` | `boolean` | — | slSegmentedControl | Enforced by the family, because a radio ignores readonly: the change is refused on the click a pointer and Space share, and the control keeps its colours and its tab stops |
+| `invalid` | `boolean` | — | slSegmentedControl | Writes aria-invalid and data-invalid, and points the focus ring at the danger step so the outline and its shadow move together |
+| `required` | `boolean` | — | slSegmentedControl | Writes aria-required on the control, and is what validate() answers for the set: “choose one” is a fact about the group and not about any one segment |
+| `value, on slSegment` | `string` | — | slSegment | What this segment selects, and what the control’s value holds. It is required: a segment with no value is a choice a reader cannot make |
+| `disabled, on slSegment` | `boolean` | — | slSegment | One segment out of action while the rest of the control stays live |
+| `slSegment` | `directive on a label` | — | the consumer’s element | The segment is a directive, so the label is the consumer’s own: every attribute, every listener and every structural directive around it stay exactly as they were written. The radio inside it is the family’s and is not substitutable |
+| `slSegmentIcon` | `directive on any element` | — | inside a segment | The mark, projected into the segment and hidden from the reading order. An ng-icon, an inline svg or a span all work and none of them loses its own semantics |
+| `exportAs` | `'slSegmentedControl' \| 'slSegment'` | — | a template reference | Reaches the instance, so a template can read selection(), checkedIndex() or a segment’s checked() without the component owning a second copy of the state |
+| `provideSegmentedControlDefaults()` | `(defaults: Partial<SegmentedControlDefaults>) => Provider` | — | an injector | The four decisions an application takes once, at the root or on one route. size is outranked by the field around the control |
+| `formControl, ngModel` | `ControlValueAccessor, Validator` | — | slSegmentedControl | The control belongs in a reactive form and in a template form: it writes the value, reports touched on blur, answers setDisabledState, and validates required over the set |
+
+## Events
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `valueChange` | `ChangeRequest<string \| undefined>` | Before the value moves. The request carries the new value, the value it replaces — undefined while nothing has been chosen — the reason, the originating event, and cancel(), which refuses the move before anything commits and puts every element back. |
+| `click, focus, blur, on each segment` | `the element’s own events` | Whenever that segment’s label fires them. The segment is a directive on the consumer’s own element, so every listener the consumer bound is on the element itself; blur also marks the form control touched. |
+
+## Axes and defaults
+
+| Axis | Values | Default |
+| --- | --- | --- |
+| `size` | `sm`, `md`, `lg` | `md` |
+| `orientation` | `horizontal`, `vertical` | `horizontal` |
+| `condense` | `none`, `icons` | `none` |
+
+## Rules
+
+- The pattern is the WAI-ARIA APG’s Radio Group (w3.org/WAI/ARIA/apg/patterns/radio/), and its entire keyboard table is the platform’s: Tab lands on the checked segment or on the first when none is checked, Space checks the focused one, both pairs of arrows move focus and the choice together, the set wraps, and disabled segments are skipped — including the arrow directions of a right-to-left document.
+- A segment is a real input type="radio" and not a button. Primer builds the row of buttons and pays one tab stop per segment where the pattern gives one for the set; Angular Material writes radiogroup around children carrying aria-pressed, which is a group whose role and children disagree. The family whose items are buttons is toggle-group, and the difference a reader feels is the arrows.
+- The role is withdrawn inside a field group, whose fieldset and legend already name the set, and a role the consumer wrote on the host survives both — it is read with HostAttributeToken before the host bindings write.
+- The ring is drawn on the segment and put out on the radio that holds the focus, so the family never paints two rings in two colours. It sits on the segment’s own edge, because the segments are flush inside the track and an offset ring would be drawn across the neighbour beside it.
+- Read-only has no platform answer for a radio, so it is enforced: the change is refused on the click a pointer and Space share, aria-readonly announces it, and the control keeps its tab stops and its full contrast. A refused change also puts the neighbour back, because the platform restores only the element that was clicked.
+- The thumb is shorter than the control it lives in, so the radio reaches the track’s own edge and the target is the control’s height rather than the thumb’s. With the segment never narrower than 24 CSS pixels, WCAG 2.2 SC 2.5.8 holds at the smallest step and the tightest density.
+
+## Tokens
+
+`--slotted-border-subtle`, `--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-font-weight`, `--slotted-control-gap-lg`, `--slotted-control-gap-md`, `--slotted-control-gap-sm`, `--slotted-control-height-lg`, `--slotted-control-height-md`, `--slotted-control-height-sm`, `--slotted-control-icon-size-lg`, `--slotted-control-icon-size-md`, `--slotted-control-icon-size-sm`, `--slotted-control-invalid-edge-width`, `--slotted-control-letter-spacing`, `--slotted-control-line-height`, `--slotted-control-padding-inline-lg`, `--slotted-control-padding-inline-md`, `--slotted-control-padding-inline-sm`, `--slotted-control-radius`, `--slotted-control-shadow`, `--slotted-control-surface`, `--slotted-control-transition-duration`, `--slotted-control-transition-easing`, `--slotted-disabled-background`, `--slotted-disabled-border`, `--slotted-disabled-foreground`, `--slotted-duration-instant`, `--slotted-duration-medium`, `--slotted-easing-standard`, `--slotted-focus-ring-color`, `--slotted-focus-ring-color-invalid`, `--slotted-focus-ring-width`, `--slotted-radius-xs`, `--slotted-segmented-control-active-background`, `--slotted-segmented-control-background`, `--slotted-segmented-control-border-color`, `--slotted-segmented-control-checked-color`, `--slotted-segmented-control-color`, `--slotted-segmented-control-disabled-border-color`, `--slotted-segmented-control-disabled-color`, `--slotted-segmented-control-disabled-indicator-background`, `--slotted-segmented-control-divider-color`, `--slotted-segmented-control-hover-background`, `--slotted-segmented-control-indicator-background`, `--slotted-segmented-control-indicator-border-color`, `--slotted-segmented-control-inset`, `--slotted-segmented-control-invalid-border-color`, `--slotted-segmented-control-invalid-edge-width`, `--slotted-segmented-control-invalid-focus-ring-color`, `--slotted-segmented-control-radius`, `--slotted-segmented-control-shadow`, `--slotted-space-1`, `--slotted-target-min`, `--slotted-text`, `--slotted-tone-accent-border`, `--slotted-tone-accent-subtle-active`, `--slotted-tone-accent-text`, `--slotted-tone-danger-border`, `--slotted-tone-secondary-subtle-active`, `--slotted-tone-secondary-subtle-hover`
+
+## Examples
+
+### The three control steps
+
+Each step reads the control scale and the track measures its segments back from it, so the whole control is as tall as the text field and the button beside it at every size.
+
+Excerpt — not a complete module
+
+```html
+<div slSegmentedControl aria-label="Visualização" size="sm" defaultValue="grid">
+  <label slSegment value="grid">Grade</label>
+  <label slSegment value="list">Lista</label>
+</div>
+```
+
+### Along the line, or down the page
+
+The thumb travels on whichever axis the segments do, and the platform moves the choice with both pairs of arrows because the set is radios sharing one name.
+
+Excerpt — not a complete module
+
+```html
+<div slSegmentedControl aria-label="Pagamento" orientation="vertical" defaultValue="invoice">
+  <label slSegment value="card">Cartão</label>
+  <label slSegment value="invoice">Boleto</label>
+</div>
+```
+
+### Every state the contract declares
+
+Hover, focus, one segment unavailable, the whole control unavailable, read-only and invalid. Read-only keeps its colours and refuses the change; only disabled loses them.
+
+Excerpt — not a complete module
+
+```html
+<div slSegmentedControl aria-label="Plano" defaultValue="starter">
+  <label slSegment value="starter">Inicial</label>
+  <label slSegment value="enterprise" disabled>Corporativo</label>
+</div>
+```
+
+### Marks without words
+
+A segment with only a mark draws square and takes its accessible name from an aria-label, which the family reads from the host and writes onto the radio that holds the focus.
+
+Excerpt — not a complete module
+
+```html
+<div slSegmentedControl aria-label="Alinhamento" defaultValue="center">
+  <label slSegment value="start" aria-label="Início">
+    <ng-icon slSegmentIcon name="lucideAlignLeft" />
+  </label>
+</div>
+```
+
+### Narrower than its words
+
+Below the width its labels need, a control told to condense keeps its marks and hides its words — hidden, never removed, so every segment is announced the same at every width.
+
+Excerpt — not a complete module
+
+```html
+<div slSegmentedControl aria-label="Relatório" condense="icons" defaultValue="table">
+  <label slSegment value="table">
+    <ng-icon slSegmentIcon name="lucideTable" />
+    Tabela
+  </label>
+</div>
+```
+
+### Content width, or the whole line
+
+Left alone every column is the widest label’s, which is the rule Carbon states; fullWidth spreads the same equal columns across the line it is given.
+
+Excerpt — not a complete module
+
+```html
+<div slSegmentedControl aria-label="Entrega" fullWidth defaultValue="afternoon">
+  <label slSegment value="morning">Manhã</label>
+  <label slSegment value="afternoon">Tarde</label>
+</div>
+```
+
+### Inside a field
+
+The control takes its step, its unavailable state and its description from the field around it, and gives the field back a control to name — the label points at the set, not at one segment.
+
+Excerpt — not a complete module
+
+```html
+<div slField>
+  <label slFieldLabel>Moeda da fatura</label>
+  <div slSegmentedControl name="currency" defaultValue="brl">
+    <label slSegment value="brl">BRL</label>
+    <label slSegment value="usd">USD</label>
+  </div>
+  <p slFieldDescription>A conversão usa a cotação do dia da emissão.</p>
+</div>
+```
+
+### In a reactive form, and validated
+
+The control is a ControlValueAccessor and a Validator: the form holds the value, and “choose one” is answered by the set rather than by any single segment that cannot see it.
+
+Excerpt — not a complete module
+
+```html
+<div slSegmentedControl aria-label="Moeda" required [formControl]="currency">
+  <label slSegment value="brl">BRL</label>
+  <label slSegment value="usd">USD</label>
+</div>
+```
+
+### Content the family did not choose
+
+A label longer than its column, a five-segment set in a narrow frame, and a right-to-left string inside a left-to-right page. Each clips at the ellipsis and keeps its whole text.
+
+Excerpt — not a complete module
+
+```html
+<div slSegmentedControl aria-label="Frequência" fullWidth defaultValue="now">
+  <label slSegment value="now">Imediatamente</label>
+  <label slSegment value="digest">Uma vez por dia, no resumo da noite</label>
+</div>
+```
+
+### The directive on the consumer’s own element, and the defaults once
+
+Every part is a directive, so the element is always the consumer’s; provideSegmentedControlDefaults states the axes once for a whole application or one route.
+
+Excerpt — not a complete module
+
+```ts
+providers: [provideSegmentedControlDefaults({ size: 'sm', fullWidth: true })];
+```
+
+### The keyboard, key by key
+
+Tab lands on the checked segment; both pairs of arrows move focus and the choice together and wrap at the ends; Space checks the focused one. Every row of it is the platform’s.
+
+Excerpt — not a complete module
+
+```html
+<div slSegmentedControl aria-label="Envio">
+  <label slSegment value="standard">Padrão</label>
+  <label slSegment value="express">Expresso</label>
+</div>
+```