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

package/docs/radio-group.md

@@ -0,0 +1,112 @@
+<!-- index: ./index.md -->
+# radio-group
+
+`data-ui="radio-group"` · Set of radios for one choice.
+
+## Import
+
+```ts
+import {
+  provideRadioGroupDefaults,
+  SlRadio,
+  SlRadioDescription,
+  SlRadioGroup,
+} from '@slotted/angular/radio-group';
+```
+
+Selector: `[slRadioGroup]` · exportAs: `slRadioGroup`
+
+## Minimal example
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlFieldGroup, SlFieldGroupLegend } from '@slotted/angular/field-group';
+import { SlRadio, SlRadioGroup } from '@slotted/angular/radio-group';
+
+@Component({
+  selector: 'app-radio-group-basic',
+  imports: [SlFieldGroup, SlFieldGroupLegend, SlRadio, SlRadioGroup],
+  template: `
+    <fieldset slFieldGroup>
+      <legend slFieldGroupLegend>Delivery speed</legend>
+      <div slRadioGroup name="delivery" defaultValue="standard">
+        <div slRadio value="standard">Standard, 3 to 5 business days</div>
+        <div slRadio value="express">Express, next business day</div>
+        <div slRadio value="same-day">Same day, Seattle only</div>
+      </div>
+    </fieldset>
+  `,
+})
+export class RadioGroupBasic {}
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | the element carrying slRadioGroup | yes |
+| `item` | the element carrying slRadio | yes |
+| `control` | input type="radio", in the item’s template | yes |
+| `indicator` | span | yes |
+| `label` | label, in the item’s template | no |
+| `description` | the element carrying slRadioDescription | no |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `value` | `string` | — | SlRadioGroup | The controlled value. When present, the consumer owns the choice. When absent, the radio group owns it and starts from defaultValue, or from the form control bound to the root. |
+| `defaultValue` | `string` | — | SlRadioGroup | The value an uncontrolled group starts from, read once when the directive initialises. Left unset, nothing is chosen and Tab lands on the first item, as the WAI-ARIA Authoring Practices recommend for a set with no default. |
+| `name` | `string` | generated | SlRadioGroup | The submission name every item shares, which is what makes the platform treat the items as one set. Generated when unset, because the platform groups radios by name within a form. |
+| `variant` | `'plain' \| 'tile'` | plain | SlRadioGroup, provideRadioGroupDefaults | How every item is drawn. tile frames each item and makes its whole surface the target; the inputs still share a name, so the arrow keys, the wrap and the single tab stop do not change. Arranging the tiles is left to Grid. |
+| `orientation` | `'vertical' \| 'horizontal'` | vertical | SlRadioGroup, provideRadioGroupDefaults | How the choices flow. A horizontal set wraps instead of scrolling, and aria-orientation is written only where the group carries the radiogroup role. |
+| `size` | `'sm' \| 'md' \| 'lg'` | md | SlRadioGroup, provideRadioGroupDefaults | The type step, passed to every item. A field or field group around the radio group decides it first, then the provider. The circle follows the control glyph scale, which the theme restates per density. |
+| `labelPlacement` | `'end' \| 'start'` | end | SlRadioGroup, provideRadioGroupDefaults | Which side of its label each circle is on, set once for the set so the circles line up. |
+| `disabled` | `boolean` | from the field, or false | SlRadioGroup, SlRadio | Unset rather than false. Reaches every item as the native attribute, which also makes the browser skip the item with the arrow keys. Set it on one SlRadio to disable that option alone. A disabled form control disables the group as well. |
+| `readOnly` | `boolean` | from the field, or false | SlRadioGroup | Unset rather than false. A radio has no native readonly, so the radio group refuses every activation and writes aria-readonly; every item keeps its tab stop, its focus ring and its contrast. |
+| `invalid` | `boolean` | from the field, or false | SlRadioGroup | Unset rather than false. Writes aria-invalid on the group and data-invalid on the root, which draws every circle in the danger tone with a thicker edge. |
+| `required` | `boolean` | from the field, or false | SlRadioGroup | Unset rather than false. Writes aria-required on the group and makes its validator demand a value, never the native required, which would turn on browser constraint validation. |
+| `value, on SlRadio` | `string` | — | SlRadio | What this item selects, and the value the group holds when it is chosen. Required: an item with no value is a choice nobody can make. |
+| `slRadioDescription` | `directive` | — | a projected element | Help text under the item’s label, wired with aria-describedby, so it describes that item and not the set. |
+| `exportAs="slRadioGroup" / "slRadio"` | `SlRadioGroup / SlRadio` | — | a template | Reaches either instance. inputElement on an item is its input, which already has focus() and click(), so there is no imperative handle. |
+| `ControlValueAccessor and Validator` | `formControl, formControlName, ngModel` | — | the host element | Both are on the group’s root, so a form binding goes on the element that already carries slRadioGroup. required becomes a validator over the set; React has no equivalent. |
+| `provideRadioGroupDefaults()` | `{ size, variant, orientation, labelPlacement }` | — | an injector | The four decisions an application takes once for every radio group under the injector. A field or field group around a radio group decides size before the token. |
+| `the host element` | `any element` | — | SlRadioGroup, SlRadio | Each root is the consumer’s own element, one more element than React renders: a set of choices can be a ul with each item written as an li. |
+| `role` | `string` | radiogroup, or none inside a field group | the host element | A role written as a static attribute wins over both, because it is read before the host binding computes. |
+
+## Events
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `(valueChange)` | `ChangeRequest<string \| undefined>` | Before the value moves. request.value is the new value and request.previous the value it replaces, which is undefined while nothing is chosen, the state the WAI-ARIA Authoring Practices ask a group to start in. request.reason is pointer or keyboard, request.source is the originating event, and request.cancel() refuses the move before anything commits, including the platform’s own selection. There is no [(value)], because a two-way binding carries only the value and none of the rest of the request. |
+| `ControlValueAccessor and Validator` | `string` | Whenever the value moves under a formControl, formControlName or ngModel written on the root. The radio group also validates the set: when required, it fails with { required: true } while nothing is chosen, because “choose one” is a fact about the group and not about any one option. |
+
+## Axes and defaults
+
+| Axis | Values | Default |
+| --- | --- | --- |
+| `size` | `sm`, `md`, `lg` | `md` |
+| `variant` | `plain`, `tile` | `plain` |
+| `orientation` | `vertical`, `horizontal` | `vertical` |
+| `labelPlacement` | `end`, `start` | `end` |
+
+## Rules
+
+- The radio group follows the WAI-ARIA Authoring Practices Radio Group pattern (w3.org/WAI/ARIA/apg/patterns/radio/), and the platform implements its whole keyboard table: Tab lands on the checked item, or on the first when none is checked; Space checks the focused item; the arrow keys move focus and selection together on both axes; the set wraps at both ends; disabled items are skipped. Native radios that share a name within one form provide all of it, including the arrow directions of a right-to-left document.
+- This is why the items share a name, and why one is generated when none is written: the platform groups radios by name within a form, so radios without a shared name are not a set. The cost is that an unnamed radio group inside a form submits under a generated key.
+- Each item takes its accessible name from its own label, through for pointing at an identifier the component generates. The group takes its name from the field group’s legend or, outside a field group, from an aria-label the consumer writes. Inside a field group the radiogroup role is withdrawn, so the set is not announced twice.
+- The group writes aria-required, never the native required on an item, and its validator, not any one item, demands a value, because “choose one” is a fact about the set. disabled is native, because the native attribute is also what makes the browser skip the option with the arrow keys.
+- A radio has no native read-only state, so the radio group enforces one: it refuses the activation, aria-readonly announces it on the group, and every item keeps its tab stop, its focus ring and its full contrast. The chosen option keeps its accent, because the value is real.
+- Refusing the activation is not enough on its own. The HTML standard’s canceled activation behaviour restores the clicked radio but not the neighbour it unchecked, so the radio group writes every element from the value afterwards. Without that, a controlled group that refused a change would show no choice at all.
+- The invalid state does not rely on colour alone. In the high-contrast scheme the theme paints the danger border in the same colour as every other border, so the circle also thickens its edge. The sentence that says what is wrong is the field group’s error.
+- The target is larger than the circle. A 24-pixel square around the circle meets WCAG 2.2 SC 2.5.8 at every size and density, while the circle is 14 pixels at size="sm"; the label extends the target to the end of the text, and the hover wash covers exactly that area. The row keeps its line height: the target is drawn around the circle, not laid out beside it.
+
+## Tokens
+
+`--slotted-border-strong`, `--slotted-border-width-medium`, `--slotted-border-width-thick`, `--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-invalid-edge-width`, `--slotted-control-label-gap-lg`, `--slotted-control-label-gap-md`, `--slotted-control-label-gap-sm`, `--slotted-control-padding-inline-lg`, `--slotted-control-padding-inline-md`, `--slotted-control-padding-inline-sm`, `--slotted-control-shadow`, `--slotted-control-transition-duration`, `--slotted-control-transition-easing`, `--slotted-disabled-background`, `--slotted-disabled-border`, `--slotted-disabled-foreground`, `--slotted-duration-medium`, `--slotted-focus-ring-color`, `--slotted-focus-ring-color-invalid`, `--slotted-focus-ring-offset`, `--slotted-focus-ring-width`, `--slotted-font-size-xs`, `--slotted-line-height-md`, `--slotted-line-height-xs`, `--slotted-radio-group-active-background`, `--slotted-radio-group-background`, `--slotted-radio-group-border-color`, `--slotted-radio-group-border-width`, `--slotted-radio-group-checked-active-border-color`, `--slotted-radio-group-checked-border-color`, `--slotted-radio-group-checked-hover-border-color`, `--slotted-radio-group-color`, `--slotted-radio-group-description-color`, `--slotted-radio-group-description-font-size`, `--slotted-radio-group-disabled-background`, `--slotted-radio-group-disabled-border-color`, `--slotted-radio-group-disabled-color`, `--slotted-radio-group-disabled-mark-color`, `--slotted-radio-group-gap`, `--slotted-radio-group-halo-color`, `--slotted-radio-group-hover-border-color`, `--slotted-radio-group-invalid-border-color`, `--slotted-radio-group-invalid-checked-border-color`, `--slotted-radio-group-invalid-edge-width`, `--slotted-radio-group-invalid-focus-ring-color`, `--slotted-radio-group-invalid-mark-color`, `--slotted-radio-group-line-height`, `--slotted-radio-group-mark-color`, `--slotted-radio-group-readonly-background`, `--slotted-radio-group-size`, `--slotted-radio-group-tile-active-background`, `--slotted-radio-group-tile-background`, `--slotted-radio-group-tile-border-color`, `--slotted-radio-group-tile-checked-background`, `--slotted-radio-group-tile-checked-border-color`, `--slotted-radio-group-tile-checked-hover-border-color`, `--slotted-radio-group-tile-description-gap`, `--slotted-radio-group-tile-disabled-background`, `--slotted-radio-group-tile-disabled-border-color`, `--slotted-radio-group-tile-hover-background`, `--slotted-radio-group-tile-hover-border-color`, `--slotted-radio-group-tile-inset`, `--slotted-radio-group-tile-invalid-border-color`, `--slotted-radio-group-tile-invalid-checked-background`, `--slotted-radio-group-tile-invalid-checked-border-color`, `--slotted-radio-group-tile-radius`, `--slotted-radio-group-tile-readonly-background`, `--slotted-radio-group-tile-readonly-border-color`, `--slotted-radius-full`, `--slotted-radius-md`, `--slotted-selection-halo-opacity`, `--slotted-selection-size-lg`, `--slotted-selection-size-md`, `--slotted-selection-size-sm`, `--slotted-space-2`, `--slotted-space-3`, `--slotted-surface`, `--slotted-target-min`, `--slotted-text`, `--slotted-text-muted`, `--slotted-tone-accent-border`, `--slotted-tone-accent-solid`, `--slotted-tone-accent-solid-active`, `--slotted-tone-accent-solid-hover`, `--slotted-tone-accent-subtle-active`, `--slotted-tone-accent-subtle-hover`, `--slotted-tone-accent-surface`, `--slotted-tone-accent-text`, `--slotted-tone-danger-border`, `--slotted-tone-danger-solid`, `--slotted-tone-danger-surface`, `--slotted-tone-secondary-subtle-hover`
+
+## Examples
+
+See [radio-group.examples.md](./radio-group.examples.md).