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

package/dist/docs/radio-group.examples.md

@@ -0,0 +1,582 @@
+<!-- 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
+
+```tsx
+<RadioGroup defaultValue="standard" name="shipping">
+  <Radio value="standard">Entrega padrão</Radio>
+  <Radio value="express">Entrega expressa</Radio>
+  <Radio value="pickup">Retirar na loja</Radio>
+</RadioGroup>;
+```
+
+### 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
+
+```tsx
+import { FieldGroup, FieldGroupContent, FieldGroupLegend } from '@slotted/react/field-group';
+import { Radio, RadioGroup } from '@slotted/react/radio-group';
+
+export default function RadioGroupOrientation() {
+  return (
+    <FieldGroup>
+      <FieldGroupLegend>Report period</FieldGroupLegend>
+      <FieldGroupContent>
+        <RadioGroup orientation="horizontal" defaultValue="month">
+          <Radio value="day">Day</Radio>
+          <Radio value="week">Week</Radio>
+          <Radio value="month">Month</Radio>
+          <Radio value="quarter">Quarter</Radio>
+          <Radio value="year">Year</Radio>
+        </RadioGroup>
+      </FieldGroupContent>
+    </FieldGroup>
+  );
+}
+```
+
+### 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
+
+```tsx
+<RadioGroup defaultValue="team" name="plan" variant="tile">
+  <Grid minItemWidth="sm">
+    <Radio description="Até três projetos e um assento." value="starter">
+      Starter
+    </Radio>
+    <Radio description="Projetos sem limite e dez assentos." value="team">
+      Team
+    </Radio>
+  </Grid>
+</RadioGroup>;
+```
+
+### 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
+
+```tsx
+import { FieldGroup, FieldGroupContent, FieldGroupLegend } from '@slotted/react/field-group';
+import { Radio, RadioGroup } from '@slotted/react/radio-group';
+import { Stack } from '@slotted/react/stack';
+
+export default function RadioGroupSizes() {
+  return (
+    <Stack gap={5}>
+      <FieldGroup size="sm">
+        <FieldGroupLegend>Count by</FieldGroupLegend>
+        <FieldGroupContent>
+          <RadioGroup orientation="horizontal" defaultValue="cases">
+            <Radio value="cases">Cases</Radio>
+            <Radio value="units">Units</Radio>
+          </RadioGroup>
+        </FieldGroupContent>
+      </FieldGroup>
+      <FieldGroup size="md">
+        <FieldGroupLegend>Payment terms</FieldGroupLegend>
+        <FieldGroupContent>
+          <RadioGroup orientation="horizontal" defaultValue="net-30">
+            <Radio value="net-30">Net 30</Radio>
+            <Radio value="net-60">Net 60</Radio>
+          </RadioGroup>
+        </FieldGroupContent>
+      </FieldGroup>
+      <FieldGroup size="lg">
+        <FieldGroupLegend>Account type</FieldGroupLegend>
+        <FieldGroupContent>
+          <RadioGroup orientation="horizontal" defaultValue="business">
+            <Radio value="business">Business</Radio>
+            <Radio value="personal">Personal</Radio>
+          </RadioGroup>
+        </FieldGroupContent>
+      </FieldGroup>
+    </Stack>
+  );
+}
+```
+
+### 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
+
+```tsx
+import {
+  FieldGroup,
+  FieldGroupContent,
+  FieldGroupDescription,
+  FieldGroupError,
+  FieldGroupLegend,
+} from '@slotted/react/field-group';
+import { Radio, RadioGroup } from '@slotted/react/radio-group';
+import { Stack } from '@slotted/react/stack';
+
+export default function RadioGroupStates() {
+  return (
+    <Stack gap={6}>
+      <FieldGroup required>
+        <FieldGroupLegend>Payment terms</FieldGroupLegend>
+        <FieldGroupError>Choose the payment terms for this customer.</FieldGroupError>
+        <FieldGroupContent>
+          <RadioGroup invalid orientation="horizontal">
+            <Radio value="net-30">Net 30</Radio>
+            <Radio value="net-60">Net 60</Radio>
+            <Radio value="prepaid">Prepaid</Radio>
+          </RadioGroup>
+        </FieldGroupContent>
+      </FieldGroup>
+      <FieldGroup readOnly>
+        <FieldGroupLegend>Warehouse</FieldGroupLegend>
+        <FieldGroupDescription>Stock is reserved once the order is picked.</FieldGroupDescription>
+        <FieldGroupContent>
+          <RadioGroup orientation="horizontal" defaultValue="seattle">
+            <Radio value="seattle">Seattle</Radio>
+            <Radio value="tacoma">Tacoma</Radio>
+          </RadioGroup>
+        </FieldGroupContent>
+      </FieldGroup>
+      <FieldGroup disabled>
+        <FieldGroupLegend>Return method</FieldGroupLegend>
+        <FieldGroupDescription>Returns open when the order is delivered.</FieldGroupDescription>
+        <FieldGroupContent>
+          <RadioGroup orientation="horizontal" defaultValue="drop-off">
+            <Radio value="drop-off">Drop-off</Radio>
+            <Radio value="pickup">Pickup</Radio>
+          </RadioGroup>
+        </FieldGroupContent>
+      </FieldGroup>
+    </Stack>
+  );
+}
+```
+
+### 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
+
+```tsx
+<RadioGroup labelPlacement="end" defaultValue="card" />;
+<RadioGroup labelPlacement="start" defaultValue="card" />;
+
+// Never inherited from a field: that family's labelPlacement answers
+// where a field's label sits relative to its control.
+```
+
+### 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
+
+```tsx
+<RadioGroup defaultValue="monthly">
+  <Radio description="Cobrado todo dia 5, sem multa de cancelamento." value="monthly">
+    Mensal
+  </Radio>
+  <Radio description="Dois meses de desconto, cobrados na contratação." value="yearly">
+    Anual
+  </Radio>
+</RadioGroup>;
+```
+
+### Inside a group of fields
+
+The fieldset and its legend are what group and name the set, so the group withdraws its own radiogroup role rather than announcing the same set twice under the same name.
+
+Excerpt — not a complete module
+
+```tsx
+<FieldGroup required>
+  <FieldGroupLegend>Forma de pagamento</FieldGroupLegend>
+  <RadioGroup defaultValue="card" name="payment">
+    <Radio value="card">Cartão</Radio>
+    <Radio value="pix">Pix</Radio>
+  </RadioGroup>
+</FieldGroup>;
+```
+
+### 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
+
+```tsx
+<RadioGroup defaultValue="a">
+  <Radio description="O círculo continua na primeira linha do rótulo." value="a">
+    Autorizo o compartilhamento dos dados de entrega com a transportadora responsável pela última
+    etapa do trajeto.
+  </Radio>
+  <Radio dir="rtl" value="b">
+    أوافق على مشاركة بيانات التسليم مع شركة الشحن.
+  </Radio>
+</RadioGroup>;
+```
+
+### Setting it once, and reaching past it
+
+The provider carries the three decisions an application takes once, render substitutes both roots so a set can be a real list, and useRadioGroup reads the same state an item reads.
+
+Excerpt — not a complete module
+
+```tsx
+<RadioGroupDefaultsProvider orientation="horizontal" size="sm">
+  <RadioGroup defaultValue="a" />
+</RadioGroupDefaultsProvider>;
+
+<RadioGroup render={(props) => <ul {...props} />} defaultValue="a">
+  <Radio render={(props) => <li {...props} />} value="a">
+    Um item
+  </Radio>
+</RadioGroup>;
+```
+
+### 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
+
+```tsx
+// 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.
+<RadioGroup name="shipping">
+  <Radio value="standard">Padrão</Radio>
+  <Radio value="express">Expressa</Radio>
+</RadioGroup>;
+```
+
+### controlled.tsx
+
+Example
+
+```tsx
+import { useState } from 'react';
+import { FieldGroup, FieldGroupContent, FieldGroupLegend } from '@slotted/react/field-group';
+import { Radio, RadioGroup } from '@slotted/react/radio-group';
+import { Stack } from '@slotted/react/stack';
+
+const TOTALS: Record<string, string> = {
+  usd: '$1,240.00',
+  eur: '€1,147.00',
+  gbp: '£982.00',
+};
+
+export default function RadioGroupControlled() {
+  const [currency, setCurrency] = useState('usd');
+
+  return (
+    <Stack gap={4}>
+      <FieldGroup>
+        <FieldGroupLegend>Invoice currency</FieldGroupLegend>
+        <FieldGroupContent>
+          <RadioGroup orientation="horizontal" value={currency} onValueChange={setCurrency}>
+            <Radio value="usd">USD</Radio>
+            <Radio value="eur">EUR</Radio>
+            <Radio value="gbp">GBP</Radio>
+          </RadioGroup>
+        </FieldGroupContent>
+      </FieldGroup>
+      <span>Invoice total: {TOTALS[currency]}</span>
+    </Stack>
+  );
+}
+```
+
+### defaults.tsx
+
+Example
+
+```tsx
+import { FieldGroup, FieldGroupContent, FieldGroupLegend } from '@slotted/react/field-group';
+import { Radio, RadioGroup, RadioGroupDefaultsProvider } from '@slotted/react/radio-group';
+import { Stack } from '@slotted/react/stack';
+
+export default function RadioGroupDefaults() {
+  return (
+    <RadioGroupDefaultsProvider orientation="horizontal">
+      <Stack gap={5}>
+        <FieldGroup>
+          <FieldGroupLegend>Status</FieldGroupLegend>
+          <FieldGroupContent>
+            <RadioGroup defaultValue="all">
+              <Radio value="all">All</Radio>
+              <Radio value="open">Open</Radio>
+              <Radio value="paid">Paid</Radio>
+              <Radio value="overdue">Overdue</Radio>
+            </RadioGroup>
+          </FieldGroupContent>
+        </FieldGroup>
+        <FieldGroup>
+          <FieldGroupLegend>Channel</FieldGroupLegend>
+          <FieldGroupContent>
+            <RadioGroup defaultValue="all">
+              <Radio value="all">All</Radio>
+              <Radio value="online">Online</Radio>
+              <Radio value="retail">Retail</Radio>
+              <Radio value="wholesale">Wholesale</Radio>
+            </RadioGroup>
+          </FieldGroupContent>
+        </FieldGroup>
+      </Stack>
+    </RadioGroupDefaultsProvider>
+  );
+}
+```
+
+### descriptions.tsx
+
+Example
+
+```tsx
+import { FieldGroup, FieldGroupContent, FieldGroupLegend } from '@slotted/react/field-group';
+import { Radio, RadioGroup } from '@slotted/react/radio-group';
+
+export default function RadioGroupDescriptions() {
+  return (
+    <FieldGroup>
+      <FieldGroupLegend>Billing cycle</FieldGroupLegend>
+      <FieldGroupContent>
+        <RadioGroup defaultValue="monthly">
+          <Radio value="monthly" description="Billed on the 5th of each month. Cancel any time.">
+            Monthly
+          </Radio>
+          <Radio value="yearly" description="Two months free, billed once when you subscribe.">
+            Yearly
+          </Radio>
+        </RadioGroup>
+      </FieldGroupContent>
+    </FieldGroup>
+  );
+}
+```
+
+### disabled-option.tsx
+
+Example
+
+```tsx
+import { FieldGroup, FieldGroupContent, FieldGroupLegend } from '@slotted/react/field-group';
+import { Radio, RadioGroup } from '@slotted/react/radio-group';
+
+export default function RadioGroupDisabledOption() {
+  return (
+    <FieldGroup>
+      <FieldGroupLegend>Carrier</FieldGroupLegend>
+      <FieldGroupContent>
+        <RadioGroup defaultValue="ups">
+          <Radio value="ups">UPS Ground</Radio>
+          <Radio value="fedex">FedEx 2Day</Radio>
+          <Radio value="dhl" disabled description="Does not deliver to Anchorage, AK.">
+            DHL Express
+          </Radio>
+        </RadioGroup>
+      </FieldGroupContent>
+    </FieldGroup>
+  );
+}
+```
+
+### label-placement.tsx
+
+Example
+
+```tsx
+import { FieldGroup, FieldGroupContent, FieldGroupLegend } from '@slotted/react/field-group';
+import { Radio, RadioGroup } from '@slotted/react/radio-group';
+
+export default function RadioGroupLabelPlacement() {
+  return (
+    <FieldGroup>
+      <FieldGroupLegend>Send the stock report</FieldGroupLegend>
+      <FieldGroupContent>
+        <RadioGroup labelPlacement="start" defaultValue="monday">
+          <Radio value="daily">Every morning</Radio>
+          <Radio value="monday">Every Monday</Radio>
+          <Radio value="never">Never</Radio>
+        </RadioGroup>
+      </FieldGroupContent>
+    </FieldGroup>
+  );
+}
+```
+
+### refuse.tsx
+
+Example
+
+```tsx
+import { useState } from 'react';
+import {
+  FieldGroup,
+  FieldGroupContent,
+  FieldGroupDescription,
+  FieldGroupError,
+  FieldGroupLegend,
+} from '@slotted/react/field-group';
+import { Radio, RadioGroup } from '@slotted/react/radio-group';
+
+const SEATS_IN_USE = 8;
+
+export default function RadioGroupRefuse() {
+  const [notice, setNotice] = useState('');
+
+  return (
+    <FieldGroup>
+      <FieldGroupLegend>Plan</FieldGroupLegend>
+      <FieldGroupDescription>This workspace has {SEATS_IN_USE} seats in use.</FieldGroupDescription>
+      <FieldGroupError tone="warning" live="polite" reserve>
+        {notice}
+      </FieldGroupError>
+      <FieldGroupContent>
+        <RadioGroup
+          defaultValue="team"
+          onValueChange={(value, request) => {
+            if (value === 'starter') {
+              request.cancel();
+              setNotice(`Starter includes one seat. Remove ${SEATS_IN_USE - 1} seats first.`);
+              return;
+            }
+            setNotice('');
+          }}
+        >
+          <Radio value="starter">Starter, one seat</Radio>
+          <Radio value="team">Team, ten seats</Radio>
+          <Radio value="business">Business, unlimited seats</Radio>
+        </RadioGroup>
+      </FieldGroupContent>
+    </FieldGroup>
+  );
+}
+```
+
+### standalone.tsx
+
+Example
+
+```tsx
+import { Radio, RadioGroup } from '@slotted/react/radio-group';
+
+export default function RadioGroupStandalone() {
+  return (
+    <RadioGroup aria-label="Chart range" orientation="horizontal" size="sm" defaultValue="30">
+      <Radio value="7">7 days</Radio>
+      <Radio value="30">30 days</Radio>
+      <Radio value="90">90 days</Radio>
+    </RadioGroup>
+  );
+}
+```
+
+### tiles.tsx
+
+Example
+
+```tsx
+import { FieldGroup, FieldGroupContent, FieldGroupLegend } from '@slotted/react/field-group';
+import { Grid } from '@slotted/react/grid';
+import { Radio, RadioGroup } from '@slotted/react/radio-group';
+
+export default function RadioGroupTiles() {
+  return (
+    <FieldGroup>
+      <FieldGroupLegend>Plan</FieldGroupLegend>
+      <FieldGroupContent>
+        <RadioGroup name="plan" variant="tile" defaultValue="team">
+          <Grid minItemWidth="xs">
+            <Radio value="starter" description="$0 per month. Three projects and one seat.">
+              Starter
+            </Radio>
+            <Radio value="team" description="$49 per month. Unlimited projects and ten seats.">
+              Team
+            </Radio>
+            <Radio value="business" description="$199 per month. Single sign-on and audit logs.">
+              Business
+            </Radio>
+          </Grid>
+        </RadioGroup>
+      </FieldGroupContent>
+    </FieldGroup>
+  );
+}
+```
+
+### validation.tsx
+
+Example
+
+```tsx
+import { useState, type SubmitEvent } from 'react';
+import { Button } from '@slotted/react/button';
+import {
+  FieldGroup,
+  FieldGroupContent,
+  FieldGroupError,
+  FieldGroupLegend,
+} from '@slotted/react/field-group';
+import { Inline } from '@slotted/react/inline';
+import { Radio, RadioGroup } from '@slotted/react/radio-group';
+import { Stack } from '@slotted/react/stack';
+
+export default function RadioGroupValidation() {
+  const [reason, setReason] = useState<string | undefined>(undefined);
+  const [submitted, setSubmitted] = useState(false);
+  const missing = submitted && reason === undefined;
+
+  const submit = (event: SubmitEvent<HTMLFormElement>) => {
+    event.preventDefault();
+    setSubmitted(true);
+  };
+
+  return (
+    <form noValidate onSubmit={submit}>
+      <Stack gap={4}>
+        <FieldGroup required>
+          <FieldGroupLegend>Return reason</FieldGroupLegend>
+          <FieldGroupError live="polite" reserve>
+            {missing ? 'Choose why the order is coming back.' : ''}
+          </FieldGroupError>
+          <FieldGroupContent>
+            <RadioGroup
+              invalid={missing ? true : undefined}
+              value={reason}
+              onValueChange={setReason}
+            >
+              <Radio value="damaged">Damaged in transit</Radio>
+              <Radio value="wrong-item">Wrong item shipped</Radio>
+              <Radio value="not-needed">No longer needed</Radio>
+            </RadioGroup>
+          </FieldGroupContent>
+        </FieldGroup>
+        <Inline gap={3} align="center">
+          <Button type="submit">Request return</Button>
+          {submitted && reason !== undefined ? <span role="status">Return requested.</span> : null}
+        </Inline>
+      </Stack>
+    </form>
+  );
+}
+```