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

package/docs/radio-group.examples.md

@@ -0,0 +1,626 @@
+<!-- index: ./index.md -->
+# radio-group
+
+`data-ui="radio-group"` · Set of radios for one choice.
+
+## Examples
+
+### Playground
+
+One set with every axis on it, driven by the controls below the canvas. Tab into it once: the whole group is a single stop, and the arrows move the choice from there.
+
+Excerpt — not a complete module
+
+```html
+<div slRadioGroup name="shipping" defaultValue="standard">
+  <div slRadio value="standard">Entrega padrão</div>
+  <div slRadio value="express">Entrega expressa</div>
+  <div slRadio value="pickup">Retirar na loja</div>
+</div>
+```
+
+### How the choices flow
+
+A horizontal set wraps rather than scrolling or clipping, and aria-orientation is written only where the group owns its role — on an element with no role the attribute describes nothing.
+
+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-orientation',
+  imports: [SlFieldGroup, SlFieldGroupLegend, SlRadio, SlRadioGroup],
+  template: `
+    <fieldset slFieldGroup>
+      <legend slFieldGroupLegend>Report period</legend>
+      <div slRadioGroup orientation="horizontal" defaultValue="month">
+        <div slRadio value="day">Day</div>
+        <div slRadio value="week">Week</div>
+        <div slRadio value="month">Month</div>
+        <div slRadio value="quarter">Quarter</div>
+        <div slRadio value="year">Year</div>
+      </div>
+    </fieldset>
+  `,
+})
+export class RadioGroupOrientation {}
+```
+
+### The plan picker, which is what tiles are for
+
+An exclusive set of framed choices is the case Cloudscape built a whole Tiles family for and Carbon a selectable Tile. Here it is one axis on the group: each item becomes the surface, the arrow keys and the roving tab stop stay the platform’s, and Grid gives the row equal widths and equal heights.
+
+Excerpt — not a complete module
+
+```html
+<div slRadioGroup name="plan" variant="tile" defaultValue="team">
+  <div slGrid minItemWidth="sm">
+    <div slRadio value="starter">
+      Starter
+      <p slRadioDescription>Até três projetos e um assento.</p>
+    </div>
+    <div slRadio value="team">
+      Team
+      <p slRadioDescription>Projetos sem limite e dez assentos.</p>
+    </div>
+  </div>
+</div>
+```
+
+### The step the set sits at
+
+The circle is the control glyph scale, so the three steps shrink together with the type and the gap when the toolbar switches to dense — and every label keeps its 24-pixel target at every one of them.
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlFieldGroup, SlFieldGroupLegend } from '@slotted/angular/field-group';
+import { SlRadio, SlRadioGroup } from '@slotted/angular/radio-group';
+import { SlStack } from '@slotted/angular/stack';
+
+@Component({
+  selector: 'app-radio-group-sizes',
+  imports: [SlFieldGroup, SlFieldGroupLegend, SlRadio, SlRadioGroup, SlStack],
+  template: `
+    <div slStack [gap]="5">
+      <fieldset slFieldGroup size="sm">
+        <legend slFieldGroupLegend>Count by</legend>
+        <div slRadioGroup orientation="horizontal" defaultValue="cases">
+          <div slRadio value="cases">Cases</div>
+          <div slRadio value="units">Units</div>
+        </div>
+      </fieldset>
+      <fieldset slFieldGroup size="md">
+        <legend slFieldGroupLegend>Payment terms</legend>
+        <div slRadioGroup orientation="horizontal" defaultValue="net-30">
+          <div slRadio value="net-30">Net 30</div>
+          <div slRadio value="net-60">Net 60</div>
+        </div>
+      </fieldset>
+      <fieldset slFieldGroup size="lg">
+        <legend slFieldGroupLegend>Account type</legend>
+        <div slRadioGroup orientation="horizontal" defaultValue="business">
+          <div slRadio value="business">Business</div>
+          <div slRadio value="personal">Personal</div>
+        </div>
+      </fieldset>
+    </div>
+  `,
+})
+export class RadioGroupSizes {}
+```
+
+### Every state the set paints
+
+Read-only keeps every tab stop and the chosen item keeps its accent, because the value is real; disabled loses both. A single unavailable option dims from its own element’s state rather than from the group’s.
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import {
+  SlFieldGroup,
+  SlFieldGroupDescription,
+  SlFieldGroupError,
+  SlFieldGroupLegend,
+} from '@slotted/angular/field-group';
+import { SlRadio, SlRadioGroup } from '@slotted/angular/radio-group';
+import { SlStack } from '@slotted/angular/stack';
+
+@Component({
+  selector: 'app-radio-group-states',
+  imports: [
+    SlFieldGroup,
+    SlFieldGroupDescription,
+    SlFieldGroupError,
+    SlFieldGroupLegend,
+    SlRadio,
+    SlRadioGroup,
+    SlStack,
+  ],
+  template: `
+    <div slStack [gap]="6">
+      <fieldset slFieldGroup required>
+        <legend slFieldGroupLegend>Payment terms</legend>
+        <span slFieldGroupError>Choose the payment terms for this customer.</span>
+        <div slRadioGroup invalid orientation="horizontal">
+          <div slRadio value="net-30">Net 30</div>
+          <div slRadio value="net-60">Net 60</div>
+          <div slRadio value="prepaid">Prepaid</div>
+        </div>
+      </fieldset>
+      <fieldset slFieldGroup readOnly>
+        <legend slFieldGroupLegend>Warehouse</legend>
+        <span slFieldGroupDescription>Stock is reserved once the order is picked.</span>
+        <div slRadioGroup orientation="horizontal" defaultValue="seattle">
+          <div slRadio value="seattle">Seattle</div>
+          <div slRadio value="tacoma">Tacoma</div>
+        </div>
+      </fieldset>
+      <fieldset slFieldGroup disabled>
+        <legend slFieldGroupLegend>Return method</legend>
+        <span slFieldGroupDescription>Returns open when the order is delivered.</span>
+        <div slRadioGroup orientation="horizontal" defaultValue="drop-off">
+          <div slRadio value="drop-off">Drop-off</div>
+          <div slRadio value="pickup">Pickup</div>
+        </div>
+      </fieldset>
+    </div>
+  `,
+})
+export class RadioGroupStates {}
+```
+
+### Which side of its label the circle is on
+
+start pushes every circle to the end of the row, and the column is a fraction rather than each label’s own width because a column of controls has to line up with itself.
+
+Excerpt — not a complete module
+
+```html
+<div slRadioGroup labelPlacement="end" defaultValue="card">
+  <div slRadio value="card">Cartão</div>
+</div>
+
+<div slRadioGroup labelPlacement="start" defaultValue="card">
+  <div slRadio value="card">Cartão</div>
+</div>
+```
+
+### Saying more about one option
+
+The description belongs to the item and reaches only that item’s control, so a reader on the second option hears the second sentence rather than everything the set has to say.
+
+Excerpt — not a complete module
+
+```html
+<div slRadioGroup defaultValue="monthly">
+  <div slRadio value="monthly">
+    Mensal
+    <p slRadioDescription>Cobrado todo dia 5, sem multa de cancelamento.</p>
+  </div>
+  <div slRadio value="yearly">
+    Anual
+    <p slRadioDescription>Dois meses de desconto, cobrados na contratação.</p>
+  </div>
+</div>
+```
+
+### Inside a group of fields, and in a reactive form
+
+The fieldset and its legend are what group and name the set, so the group withdraws its own radiogroup role — and the same element takes formControlName, because the accessor and the validator both live on the root.
+
+Excerpt — not a complete module
+
+```html
+<fieldset slFieldGroup required>
+  <legend slFieldGroupLegend>Forma de pagamento</legend>
+  <div slRadioGroup required formControlName="payment">
+    <div slRadio value="card">Cartão</div>
+    <div slRadio value="pix">Pix</div>
+  </div>
+</fieldset>
+```
+
+### Content the family did not choose
+
+An option that wraps to three lines keeps its circle on the first of them, an unbroken token breaks instead of taking the page with it, and a right-to-left label mirrors the whole row.
+
+Excerpt — not a complete module
+
+```html
+<div slRadioGroup defaultValue="a">
+  <div slRadio value="a">
+    Autorizo o compartilhamento dos dados de entrega com a transportadora.
+    <p slRadioDescription>O círculo continua na primeira linha do rótulo.</p>
+  </div>
+  <div slRadio value="b" dir="rtl">أوافق على مشاركة بيانات التسليم.</div>
+</div>
+```
+
+### Setting it once, and reaching past it
+
+The token carries the three decisions an application takes once, exportAs reaches both instances, and the root is the consumer’s own element — so a set of choices can be a real list.
+
+Excerpt — not a complete module
+
+```html
+<ul slRadioGroup class="slotted-demo-list" defaultValue="a">
+  <li slRadio value="a">Um item</li>
+  <li slRadio value="b">E outro abaixo dele</li>
+</ul>
+```
+
+### The APG table, implemented by the platform
+
+Tab lands on the chosen item or on the first, the arrows move focus and selection together in both axes, the set wraps at both ends, and disabled options are skipped — none of it written here.
+
+Excerpt — not a complete module
+
+```html
+<!-- Native radios in one form owner with one name already implement the
+     whole APG table, in a right-to-left document too. The group generates
+     a name when the consumer writes none, because an unnamed set is not a
+     set — the price is that such a group inside a form submits under a
+     generated key. -->
+<div slRadioGroup name="shipping">
+  <div slRadio value="standard">Padrão</div>
+  <div slRadio value="express">Expressa</div>
+</div>
+```
+
+### controlled.ts
+
+Example
+
+```ts
+import { Component, computed, signal } from '@angular/core';
+import { SlFieldGroup, SlFieldGroupLegend } from '@slotted/angular/field-group';
+import { SlRadio, SlRadioGroup } from '@slotted/angular/radio-group';
+import { SlStack } from '@slotted/angular/stack';
+
+const TOTALS: Record<string, string> = {
+  usd: '$1,240.00',
+  eur: '€1,147.00',
+  gbp: '£982.00',
+};
+
+@Component({
+  selector: 'app-radio-group-controlled',
+  imports: [SlFieldGroup, SlFieldGroupLegend, SlRadio, SlRadioGroup, SlStack],
+  template: `
+    <div slStack [gap]="4">
+      <fieldset slFieldGroup>
+        <legend slFieldGroupLegend>Invoice currency</legend>
+        <div
+          slRadioGroup
+          orientation="horizontal"
+          [value]="currency()"
+          (valueChange)="currency.set($event.value ?? 'usd')"
+        >
+          <div slRadio value="usd">USD</div>
+          <div slRadio value="eur">EUR</div>
+          <div slRadio value="gbp">GBP</div>
+        </div>
+      </fieldset>
+      <span>Invoice total: {{ total() }}</span>
+    </div>
+  `,
+})
+export class RadioGroupControlled {
+  readonly currency = signal('usd');
+  readonly total = computed(() => TOTALS[this.currency()]);
+}
+```
+
+### defaults.ts
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlFieldGroup, SlFieldGroupLegend } from '@slotted/angular/field-group';
+import { provideRadioGroupDefaults, SlRadio, SlRadioGroup } from '@slotted/angular/radio-group';
+import { SlStack } from '@slotted/angular/stack';
+
+@Component({
+  selector: 'app-radio-group-defaults',
+  imports: [SlFieldGroup, SlFieldGroupLegend, SlRadio, SlRadioGroup, SlStack],
+  providers: [provideRadioGroupDefaults({ orientation: 'horizontal' })],
+  template: `
+    <div slStack [gap]="5">
+      <fieldset slFieldGroup>
+        <legend slFieldGroupLegend>Status</legend>
+        <div slRadioGroup defaultValue="all">
+          <div slRadio value="all">All</div>
+          <div slRadio value="open">Open</div>
+          <div slRadio value="paid">Paid</div>
+          <div slRadio value="overdue">Overdue</div>
+        </div>
+      </fieldset>
+      <fieldset slFieldGroup>
+        <legend slFieldGroupLegend>Channel</legend>
+        <div slRadioGroup defaultValue="all">
+          <div slRadio value="all">All</div>
+          <div slRadio value="online">Online</div>
+          <div slRadio value="retail">Retail</div>
+          <div slRadio value="wholesale">Wholesale</div>
+        </div>
+      </fieldset>
+    </div>
+  `,
+})
+export class RadioGroupDefaults {}
+```
+
+### descriptions.ts
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlFieldGroup, SlFieldGroupLegend } from '@slotted/angular/field-group';
+import { SlRadio, SlRadioDescription, SlRadioGroup } from '@slotted/angular/radio-group';
+
+@Component({
+  selector: 'app-radio-group-descriptions',
+  imports: [SlFieldGroup, SlFieldGroupLegend, SlRadio, SlRadioDescription, SlRadioGroup],
+  template: `
+    <fieldset slFieldGroup>
+      <legend slFieldGroupLegend>Billing cycle</legend>
+      <div slRadioGroup defaultValue="monthly">
+        <div slRadio value="monthly">
+          Monthly
+          <p slRadioDescription>Billed on the 5th of each month. Cancel any time.</p>
+        </div>
+        <div slRadio value="yearly">
+          Yearly
+          <p slRadioDescription>Two months free, billed once when you subscribe.</p>
+        </div>
+      </div>
+    </fieldset>
+  `,
+})
+export class RadioGroupDescriptions {}
+```
+
+### disabled-option.ts
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlFieldGroup, SlFieldGroupLegend } from '@slotted/angular/field-group';
+import { SlRadio, SlRadioDescription, SlRadioGroup } from '@slotted/angular/radio-group';
+
+@Component({
+  selector: 'app-radio-group-disabled-option',
+  imports: [SlFieldGroup, SlFieldGroupLegend, SlRadio, SlRadioDescription, SlRadioGroup],
+  template: `
+    <fieldset slFieldGroup>
+      <legend slFieldGroupLegend>Carrier</legend>
+      <div slRadioGroup defaultValue="ups">
+        <div slRadio value="ups">UPS Ground</div>
+        <div slRadio value="fedex">FedEx 2Day</div>
+        <div slRadio value="dhl" disabled>
+          DHL Express
+          <p slRadioDescription>Does not deliver to Anchorage, AK.</p>
+        </div>
+      </div>
+    </fieldset>
+  `,
+})
+export class RadioGroupDisabledOption {}
+```
+
+### label-placement.ts
+
+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-label-placement',
+  imports: [SlFieldGroup, SlFieldGroupLegend, SlRadio, SlRadioGroup],
+  template: `
+    <fieldset slFieldGroup>
+      <legend slFieldGroupLegend>Send the stock report</legend>
+      <div slRadioGroup labelPlacement="start" defaultValue="monday">
+        <div slRadio value="daily">Every morning</div>
+        <div slRadio value="monday">Every Monday</div>
+        <div slRadio value="never">Never</div>
+      </div>
+    </fieldset>
+  `,
+})
+export class RadioGroupLabelPlacement {}
+```
+
+### refuse.ts
+
+Example
+
+```ts
+import { Component, signal } from '@angular/core';
+import type { ChangeRequest } from '@slotted/core/state';
+import {
+  SlFieldGroup,
+  SlFieldGroupDescription,
+  SlFieldGroupError,
+  SlFieldGroupLegend,
+} from '@slotted/angular/field-group';
+import { SlRadio, SlRadioGroup } from '@slotted/angular/radio-group';
+
+const SEATS_IN_USE = 8;
+
+@Component({
+  selector: 'app-radio-group-refuse',
+  imports: [
+    SlFieldGroup,
+    SlFieldGroupDescription,
+    SlFieldGroupError,
+    SlFieldGroupLegend,
+    SlRadio,
+    SlRadioGroup,
+  ],
+  template: `
+    <fieldset slFieldGroup>
+      <legend slFieldGroupLegend>Plan</legend>
+      <span slFieldGroupDescription>This workspace has {{ seatsInUse }} seats in use.</span>
+      <span slFieldGroupError tone="warning" live="polite" reserve>{{ notice() }}</span>
+      <div slRadioGroup defaultValue="team" (valueChange)="request($event)">
+        <div slRadio value="starter">Starter, one seat</div>
+        <div slRadio value="team">Team, ten seats</div>
+        <div slRadio value="business">Business, unlimited seats</div>
+      </div>
+    </fieldset>
+  `,
+})
+export class RadioGroupRefuse {
+  readonly seatsInUse = SEATS_IN_USE;
+  readonly notice = signal('');
+
+  request(request: ChangeRequest<string | undefined>): void {
+    if (request.value === 'starter') {
+      request.cancel();
+      this.notice.set(`Starter includes one seat. Remove ${SEATS_IN_USE - 1} seats first.`);
+      return;
+    }
+    this.notice.set('');
+  }
+}
+```
+
+### standalone.ts
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlRadio, SlRadioGroup } from '@slotted/angular/radio-group';
+
+@Component({
+  selector: 'app-radio-group-standalone',
+  imports: [SlRadio, SlRadioGroup],
+  template: `
+    <div slRadioGroup aria-label="Chart range" orientation="horizontal" size="sm" defaultValue="30">
+      <div slRadio value="7">7 days</div>
+      <div slRadio value="30">30 days</div>
+      <div slRadio value="90">90 days</div>
+    </div>
+  `,
+})
+export class RadioGroupStandalone {}
+```
+
+### tiles.ts
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlFieldGroup, SlFieldGroupLegend } from '@slotted/angular/field-group';
+import { SlGrid } from '@slotted/angular/grid';
+import { SlRadio, SlRadioDescription, SlRadioGroup } from '@slotted/angular/radio-group';
+
+@Component({
+  selector: 'app-radio-group-tiles',
+  imports: [SlFieldGroup, SlFieldGroupLegend, SlGrid, SlRadio, SlRadioDescription, SlRadioGroup],
+  template: `
+    <fieldset slFieldGroup>
+      <legend slFieldGroupLegend>Plan</legend>
+      <div slRadioGroup name="plan" variant="tile" defaultValue="team">
+        <div slGrid minItemWidth="xs">
+          <div slRadio value="starter">
+            Starter
+            <p slRadioDescription>$0 per month. Three projects and one seat.</p>
+          </div>
+          <div slRadio value="team">
+            Team
+            <p slRadioDescription>$49 per month. Unlimited projects and ten seats.</p>
+          </div>
+          <div slRadio value="business">
+            Business
+            <p slRadioDescription>$199 per month. Single sign-on and audit logs.</p>
+          </div>
+        </div>
+      </div>
+    </fieldset>
+  `,
+})
+export class RadioGroupTiles {}
+```
+
+### validation.ts
+
+Example
+
+```ts
+import { Component, signal } from '@angular/core';
+import { FormControl, ReactiveFormsModule } from '@angular/forms';
+import { SlButton } from '@slotted/angular/button';
+import { SlFieldGroup, SlFieldGroupError, SlFieldGroupLegend } from '@slotted/angular/field-group';
+import { SlInline } from '@slotted/angular/inline';
+import { SlRadio, SlRadioGroup } from '@slotted/angular/radio-group';
+import { SlStack } from '@slotted/angular/stack';
+
+@Component({
+  selector: 'app-radio-group-validation',
+  imports: [
+    ReactiveFormsModule,
+    SlButton,
+    SlFieldGroup,
+    SlFieldGroupError,
+    SlFieldGroupLegend,
+    SlInline,
+    SlRadio,
+    SlRadioGroup,
+    SlStack,
+  ],
+  template: `
+    <form novalidate (submit)="submit($event)">
+      <div slStack [gap]="4">
+        <fieldset slFieldGroup required>
+          <legend slFieldGroupLegend>Return reason</legend>
+          <span slFieldGroupError live="polite" reserve>{{
+            missing ? 'Choose why the order is coming back.' : ''
+          }}</span>
+          <div slRadioGroup [formControl]="reason" [invalid]="missing ? true : undefined">
+            <div slRadio value="damaged">Damaged in transit</div>
+            <div slRadio value="wrong-item">Wrong item shipped</div>
+            <div slRadio value="not-needed">No longer needed</div>
+          </div>
+        </fieldset>
+        <div slInline [gap]="3" align="center">
+          <button slButton type="submit">Request return</button>
+          @if (submitted() && reason.valid) {
+            <span role="status">Return requested.</span>
+          }
+        </div>
+      </div>
+    </form>
+  `,
+})
+export class RadioGroupValidation {
+  /* The group is the form control and its validator: inside a required field
+     group, an empty value fails with { required: true }. */
+  readonly reason = new FormControl<string | null>(null);
+  readonly submitted = signal(false);
+
+  get missing(): boolean {
+    return this.submitted() && this.reason.invalid;
+  }
+
+  submit(event: Event): void {
+    event.preventDefault();
+    this.submitted.set(true);
+  }
+}
+```