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

package/dist/docs/section.md

@@ -0,0 +1,224 @@
+<!-- index: ./index.md -->
+# section
+
+`data-ui="section"` · Titled block of content within a page.
+
+## Import
+
+```tsx
+import { Section, SectionHeader, SectionTitle, SectionEyebrow, SectionHeading, SectionDescription, SectionActions, SectionBody, SectionDefaultsProvider } from '@slotted/react';
+```
+
+## Minimal example
+
+Excerpt — not a complete module
+
+```tsx
+<Section>
+  <SectionHeader>
+    <SectionTitle>
+      <SectionHeading>Itens do pedido</SectionHeading>
+    </SectionTitle>
+  </SectionHeader>
+  <SectionBody>…</SectionBody>
+</Section>;
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | section, or the element render returns | yes |
+| `header` | div | no |
+| `title` | div | no |
+| `eyebrow` | span | no |
+| `heading` | h1 to h6, from the outline or level, or the element render returns | no |
+| `description` | p | no |
+| `actions` | div | no |
+| `body` | div | yes |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `size` | `'sm' \| 'md' \| 'lg'` | md | Section, SectionDefaultsProvider | The step the heading sits at, on the type scale, independent of its rank |
+| `level` | `'auto' \| '1' \| '2' \| '3' \| '4' \| '5' \| '6'` | auto | Section | The rank of the heading. auto takes the one typography’s outline gives: h2 directly in a page, one deeper inside another section |
+| `divider` | `boolean` | false | Section, SectionDefaultsProvider | A rule under the header, for a page where space alone does not separate |
+| `ground` | `'none' \| 'surface'` | none | Section, SectionDefaultsProvider | none is transparent; surface paints the raised surface with a subtle edge and the large radius — no shadow, no hover, no action, because a section is not a card |
+| `sticky` | `boolean` | false | Section, SectionDefaultsProvider | The header stays under the page chrome while the body scrolls, painted in the page’s ground. Without a page it sticks to the top of whatever scrolls |
+| `id` | `string` | from useId | Section | The identifier a hash link reaches. The heading’s own id is derived from it |
+| `render` | `(props) => ReactNode` | — | every part | Substitutes the element and hands it every attribute. A heading rendered into another element keeps its rank through role="heading" and aria-level |
+| `ref` | `Ref<HTMLElement>` | — | every part | Reaches the element itself; no imperative handle is invented for a family with no state |
+| `useSection()` | `() => SectionContextValue` | — | inside Section | What the parts read: the rank, the heading’s identifier, and registerHeading, which is how the root learns it has a name |
+| `SectionDefaultsProvider` | `{ size, divider, ground, sticky }` | — | a subtree | The four decisions an application takes once. A section that states any of them itself still wins |
+| `HeadingLevel` | `from @slotted/react/typography` | — | around a subtree | The outline context the section reads. The body is already one step deeper; wrap a subtree in it to step the outline yourself |
+
+## Axes and defaults
+
+| Axis | Values | Default |
+| --- | --- | --- |
+| `size` | `sm`, `md`, `lg` | `md` |
+| `level` | `auto`, `1`, `2`, `3`, `4`, `5`, `6` | `auto` |
+| `divider` | `false`, `true` | `false` |
+| `ground` | `none`, `surface` | `none` |
+| `sticky` | `false`, `true` | `false` |
+
+## Rules
+
+- The practice is the WAI-ARIA APG’s Landmark Regions (w3.org/WAI/ARIA/apg/practices/landmark-regions/): a section element with an accessible name is a region landmark. The root is aria-labelledby its heading once one is rendered, so a section with a heading appears in the landmark list under the heading’s words, and one without a heading is a plain section that clutters nothing.
+- The rank is real. The heading renders h1 to h6 from the outline typography keeps — h2 directly in a page body, one deeper inside another section’s body — and level overrides it. A heading rendered into another element through render carries role="heading" and aria-level, so the outline survives an editable or linked title.
+- The body is one HeadingLevel deeper, which is what keeps a nested section, a collapsible or a table caption at the right rank without either family reading the other. The HTML Standard requires each heading to be at most one deeper than the one before, and stepping by exactly one is the only way to hold that in a tree assembled from components.
+- The root carries a scroll margin the height of the page chrome, so a hash link to the section lands under the header rather than behind it. The id comes from useId or the consumer, and the heading’s id is derived from it, so an anchor-nav family later has both to reach.
+- Nothing here is interactive. The actions slot holds the consumer’s own controls, in the page tab sequence like any other; the sticky header is CSS and takes no focus.
+
+## Tokens
+
+`--slotted-border-subtle`, `--slotted-border-width-thin`, `--slotted-control-gap-md`, `--slotted-font-family-heading`, `--slotted-font-family-sans`, `--slotted-font-size-lg`, `--slotted-font-size-md`, `--slotted-font-size-sm`, `--slotted-font-size-xl`, `--slotted-font-size-xs`, `--slotted-font-weight-semibold`, `--slotted-line-height-lg`, `--slotted-line-height-md`, `--slotted-line-height-sm`, `--slotted-line-height-xl`, `--slotted-line-height-xs`, `--slotted-page-ground`, `--slotted-radius-lg`, `--slotted-section-border`, `--slotted-section-description-measure`, `--slotted-section-gap`, `--slotted-section-heading-size-lg`, `--slotted-section-heading-size-md`, `--slotted-section-heading-size-sm`, `--slotted-section-inset`, `--slotted-section-radius`, `--slotted-section-surface`, `--slotted-space-1`, `--slotted-space-3`, `--slotted-space-4`, `--slotted-space-5`, `--slotted-space-6`, `--slotted-surface`, `--slotted-surface-raised`, `--slotted-text`, `--slotted-text-muted`, `--slotted-z-index-sticky`
+
+## Examples
+
+### Every part, written out
+
+The eyebrow with the count, the heading, the description under it, two actions at the end of the row, and the body with the table. The section is a region named by its heading.
+
+Excerpt — not a complete module
+
+```tsx
+<Section divider id="itens">
+  <SectionHeader>
+    <SectionTitle>
+      <SectionEyebrow>36 itens</SectionEyebrow>
+      <SectionHeading>Itens do pedido</SectionHeading>
+      <SectionDescription>Quantidades conforme a cotação aceite.</SectionDescription>
+    </SectionTitle>
+    <SectionActions>
+      <Button size="sm" variant="outline">
+        Exportar
+      </Button>
+    </SectionActions>
+  </SectionHeader>
+  <SectionBody>
+    <Table>…</Table>
+  </SectionBody>
+</Section>;
+```
+
+### The rank is the outline’s
+
+Three sections nested: h2 directly in the page, h3 inside it, h4 inside that — none of them told. level="5" on the last one overrides the outline and typography warns in development about a skip.
+
+Excerpt — not a complete module
+
+```tsx
+<Section>
+  <SectionHeading>Frota</SectionHeading>
+  <SectionBody>
+    <Section>
+      <SectionHeading>Veículos pesados</SectionHeading>
+    </Section>
+  </SectionBody>
+</Section>;
+```
+
+### The step the heading sits at
+
+sm for a group inside a form, md for a section of a page, lg for the one section a screen is about. The step is a size on the type scale and says nothing about the rank.
+
+Excerpt — not a complete module
+
+```tsx
+<Section level="3" size="lg">
+  …
+</Section>;
+```
+
+### Space, a rule, or a surface
+
+Three sections on the page’s sunken canvas: separated by the stack’s gap alone, by a divider under the header, and by a surface with an edge and a radius — no shadow, no hover, because a section is not a card.
+
+Excerpt — not a complete module
+
+```tsx
+<Section ground="surface">…</Section>;
+```
+
+### A header that stays
+
+Scroll the screen: each section’s header stops under the page chrome and the next one pushes it away. Pin the page header and they all stop lower, because the page publishes where its chrome ends. A sticky section republishes it for its body as page plus header, so layers add up: a section in a section, a table in that.
+
+Excerpt — not a complete module
+
+```tsx
+<Section sticky>…</Section>;
+```
+
+### A section inside a section
+
+The fleet, its heavy vehicles, the tractors: three depths, three ranks, and every rule the family owns reaches its parts with a child combinator, so the outer header styles nothing of the inner one.
+
+Excerpt — not a complete module
+
+```tsx
+<Section size="lg">
+  <SectionHeading>Frota</SectionHeading>
+  <SectionBody>
+    <Section>
+      <SectionHeading>Veículos pesados</SectionHeading>
+      <SectionBody>
+        <Section size="sm">
+          <SectionHeading>Cavalos mecânicos</SectionHeading>
+        </Section>
+      </SectionBody>
+    </Section>
+  </SectionBody>
+</Section>;
+```
+
+### Content the family did not choose
+
+A nine-word heading wraps, a long eyebrow wraps in small capitals, a translated description keeps its measure, and a header with no actions leaves no vacancy at the end of the row.
+
+Excerpt — not a complete module
+
+```tsx
+<SectionHeading>
+  Requisitos de homologação, garantia, recapagem e descarte ambientalmente adequado dos pneus
+  fornecidos
+</SectionHeading>;
+```
+
+### A section with a table, a list and a form in it
+
+The body holds other families and steps the outline for them: the table’s caption, the collapsible’s header and the form’s legend all sit one rank under the section. Scroll and the sticky header stays over all of it.
+
+Excerpt — not a complete module
+
+```tsx
+<SectionBody>
+  <Table stickyHeader stickyTo="page">
+    …
+  </Table>
+</SectionBody>;
+```
+
+### Setting it once, and reaching past it
+
+The provider carries size, divider, ground and sticky for every section under it; render turns the heading into a link while the family keeps the rank and the identifier; a hash link reaches the root by its id.
+
+Excerpt — not a complete module
+
+```tsx
+<SectionDefaultsProvider divider size="sm">
+  <Section>…</Section>
+</SectionDefaultsProvider>;
+```
+
+### What a reader hears
+
+A section with a heading is a region in the landmark list, named by the heading; one without a heading is a plain section, absent from it. Jump to a section by hash and it lands under the page chrome, not behind it.
+
+Excerpt — not a complete module
+
+```tsx
+<a href="#historico">Ir ao histórico</a>;
+```

package/dist/docs/segmented-control.json

@@ -0,0 +1,435 @@
+{
+  "family": "segmented-control",
+  "ui": "segmented-control",
+  "binding": "react",
+  "catalog": {
+    "group": "Forms",
+    "summary": "Row of exclusive options, one selected."
+  },
+  "axes": {
+    "size": [
+      "sm",
+      "md",
+      "lg"
+    ],
+    "orientation": [
+      "horizontal",
+      "vertical"
+    ],
+    "condense": [
+      "none",
+      "icons"
+    ]
+  },
+  "members": {
+    "segmentedControl": {
+      "nativeElement": "div",
+      "defaults": {
+        "size": "md",
+        "orientation": "horizontal",
+        "condense": "none",
+        "fullWidth": false,
+        "disabled": false
+      },
+      "capabilities": [
+        "selection",
+        "orientation",
+        "size",
+        "appearance",
+        "content",
+        "fullWidth",
+        "disabled",
+        "invalid",
+        "required",
+        "readOnly",
+        "wiring"
+      ],
+      "states": [
+        "default",
+        "hover",
+        "active",
+        "focus-visible",
+        "checked",
+        "disabled",
+        "invalid",
+        "readonly"
+      ],
+      "parts": [
+        "root",
+        "indicator",
+        "item",
+        "control",
+        "icon",
+        "label"
+      ]
+    }
+  },
+  "docs": {
+    "segmentedControl": {
+      "imports": {
+        "source": "import { Segment, SegmentedControl, SegmentedControlDefaultsProvider } from '@slotted/react';"
+      },
+      "anatomy": [
+        {
+          "part": "root",
+          "element": "div, or the element render returns",
+          "required": true,
+          "purpose": "The track. It carries role=\"radiogroup\", data-ui=\"segmented-control\", the axes, and the two numbers the thumb is made of — the count of segments and the index of the checked one. It is exactly one control tall, so it lines up beside a field in a form."
+        },
+        {
+          "part": "indicator",
+          "element": "span",
+          "required": false,
+          "purpose": "The thumb. One column wide, moved by its own width times the checked index, so nothing is read from layout and the first server-rendered paint is already right. It is absent while nothing is checked, so the first selection fades it in rather than sliding it from an edge."
+        },
+        {
+          "part": "item",
+          "element": "label, or the element Segment’s render returns",
+          "required": true,
+          "purpose": "One segment, and the whole hit area of its radio. It carries data-checked and data-disabled, and a rule on its leading edge that gives way around the thumb."
+        },
+        {
+          "part": "control",
+          "element": "input type=\"radio\"",
+          "required": true,
+          "purpose": "The radio. Visually hidden and left where it is, covering the segment and reaching the track’s own edge so the target is the control’s height. Sharing one name is what buys the platform’s whole keyboard model; it is deliberately not substitutable."
+        },
+        {
+          "part": "icon",
+          "element": "span",
+          "required": false,
+          "purpose": "The mark a segment was given, sized from the control glyph scale and hidden from the reading order. It is what stays when the control condenses."
+        },
+        {
+          "part": "label",
+          "element": "span",
+          "required": true,
+          "purpose": "The words. Present at every width — under data-condense=\"icons\" they are hidden visually and kept in the DOM, so the accessible name of a segment does not change with the width of its container."
+        }
+      ],
+      "api": [
+        {
+          "name": "value",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "SegmentedControl",
+          "description": "Present means the consumer owns the choice, for the life of the component. Absent, the control owns it and starts from defaultValue"
+        },
+        {
+          "name": "defaultValue",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "SegmentedControl",
+          "description": "What an uncontrolled control starts from, read once. A later change to it does not silently become new state"
+        },
+        {
+          "name": "name",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "SegmentedControl",
+          "description": "The submission name the segments share, and the reason the platform treats them as one radio group. Generated when none is written, and the cost is that such a control submits under a generated key"
+        },
+        {
+          "name": "size",
+          "type": "'sm' | 'md' | 'lg'",
+          "defaultValue": "md",
+          "appliesTo": "SegmentedControl",
+          "description": "The control step. The track measures its segments back from it, so the whole control is exactly as tall as the field beside it"
+        },
+        {
+          "name": "orientation",
+          "type": "'horizontal' | 'vertical'",
+          "defaultValue": "horizontal",
+          "appliesTo": "SegmentedControl",
+          "description": "How the segments flow and which way the thumb travels. A horizontal set writes aria-orientation, because radiogroup already implies vertical"
+        },
+        {
+          "name": "condense",
+          "type": "'none' | 'icons'",
+          "defaultValue": "none",
+          "appliesTo": "SegmentedControl",
+          "description": "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"
+        },
+        {
+          "name": "fullWidth",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "SegmentedControl",
+          "description": "Whether the equal columns spread across the whole line. Left alone every column is the widest label’s"
+        },
+        {
+          "name": "disabled",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "SegmentedControl",
+          "description": "Unstated rather than false, so the control defers to the field around it. Stated, it reaches every radio as the native attribute, which is also what makes the browser skip it with the arrows"
+        },
+        {
+          "name": "readOnly",
+          "type": "boolean",
+          "defaultValue": "—",
+          "appliesTo": "SegmentedControl",
+          "description": "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"
+        },
+        {
+          "name": "invalid",
+          "type": "boolean",
+          "defaultValue": "—",
+          "appliesTo": "SegmentedControl",
+          "description": "Writes aria-invalid and data-invalid, and points the focus ring at the danger step so the outline and its shadow move together"
+        },
+        {
+          "name": "required",
+          "type": "boolean",
+          "defaultValue": "—",
+          "appliesTo": "SegmentedControl",
+          "description": "Writes aria-required on the control rather than the native attribute on a radio, so describing a field does not change what submitting the form does"
+        },
+        {
+          "name": "value, on Segment",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "Segment",
+          "description": "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"
+        },
+        {
+          "name": "icon, on Segment",
+          "type": "ReactNode",
+          "defaultValue": "—",
+          "appliesTo": "Segment",
+          "description": "The mark drawn before the words, and what stays when the control condenses"
+        },
+        {
+          "name": "disabled, on Segment",
+          "type": "boolean",
+          "defaultValue": "—",
+          "appliesTo": "Segment",
+          "description": "One segment out of action while the rest of the control stays live"
+        }
+      ],
+      "composition": [
+        {
+          "name": "render",
+          "type": "(props: SegmentedControlRootProps | SegmentRootProps) => ReactNode",
+          "defaultValue": "—",
+          "appliesTo": "SegmentedControl, Segment",
+          "description": "Substitutes either root and hands it every attribute. The radio is fixed: a segment that became a button or a link would lose the semantics this family exists to have, and a row that navigates is tabs"
+        },
+        {
+          "name": "ref",
+          "type": "Ref<HTMLDivElement> | Ref<HTMLInputElement>",
+          "defaultValue": "—",
+          "appliesTo": "SegmentedControl, Segment",
+          "description": "Reaches the element — the track, or that segment’s radio. focus() and click() are the element’s own, so no imperative handle is invented"
+        },
+        {
+          "name": "useSegmentedControl()",
+          "type": "() => SegmentedControlContextValue",
+          "defaultValue": "—",
+          "appliesTo": "inside a SegmentedControl",
+          "description": "What a segment reads to know whether it is checked and how to ask for a change. It throws outside a control rather than rendering something that behaves like nothing"
+        },
+        {
+          "name": "SegmentedControlDefaultsProvider",
+          "type": "{ condense, fullWidth, orientation, size }",
+          "defaultValue": "—",
+          "appliesTo": "a subtree",
+          "description": "The four decisions an application takes once. size is outranked by the field around the control"
+        },
+        {
+          "name": "role",
+          "type": "string",
+          "defaultValue": "radiogroup, or none inside a field group",
+          "appliesTo": "SegmentedControl",
+          "description": "A consumer’s own wins over both. The role is withdrawn inside a field group, whose fieldset and legend already name the set"
+        }
+      ],
+      "events": [
+        {
+          "name": "onValueChange",
+          "payload": "(value: string, request: ChangeRequest<string | undefined>)",
+          "when": "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, including the platform’s own selection."
+        },
+        {
+          "name": "onChange, onClick, onFocus, onBlur, on each segment",
+          "payload": "the element’s own events",
+          "when": "Whenever that segment’s radio fires them. The family composes with a consumer’s handler rather than replacing it: the consumer’s runs first, and always runs. Calling preventDefault() in onClick stops the change as well."
+        }
+      ],
+      "accessibility": [
+        "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.",
+        "That is why the segments share a name, and why one is generated when none is written: grouping is by name within the form owner, so an unnamed set is not a set. The value reaches FormData with no wiring, which is what makes this the family for a choice a form submits.",
+        "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 rather than off it, 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 — it must not be mistaken for an unavailable one.",
+        "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.",
+        "Condensing hides the words and keeps them: the accessible name of every segment is the same whether the control has room for its labels or not."
+      ]
+    }
+  },
+  "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": [
+    {
+      "id": "playground",
+      "title": "Playground",
+      "note": "One control with every axis on it, driven by the controls below the canvas. Tab into it once, then use the arrows: they move focus and the choice together, because the segments are radios.",
+      "language": "tsx",
+      "source": "<SegmentedControl aria-label=\"Período do gráfico\" defaultValue=\"week\">\n  <Segment value=\"day\">Dia</Segment>\n  <Segment value=\"week\">Semana</Segment>\n  <Segment value=\"month\">Mês</Segment>\n</SegmentedControl>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "sizes",
+      "title": "The three control steps",
+      "note": "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.",
+      "language": "tsx",
+      "source": "<SegmentedControl aria-label=\"Visualização\" defaultValue=\"grid\" size=\"sm\">\n  <Segment value=\"grid\">Grade</Segment>\n  <Segment value=\"list\">Lista</Segment>\n</SegmentedControl>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "orientation",
+      "title": "Along the line, or down the page",
+      "note": "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.",
+      "language": "tsx",
+      "source": "<SegmentedControl aria-label=\"Pagamento\" defaultValue=\"invoice\" orientation=\"vertical\">\n  <Segment value=\"card\">Cartão</Segment>\n  <Segment value=\"transfer\">Transferência</Segment>\n  <Segment value=\"invoice\">Boleto</Segment>\n</SegmentedControl>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "states",
+      "title": "Every state the contract declares",
+      "note": "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.",
+      "language": "tsx",
+      "source": "<SegmentedControl aria-label=\"Plano\" defaultValue=\"starter\">\n  <Segment value=\"starter\">Inicial</Segment>\n  <Segment value=\"team\">Equipe</Segment>\n  <Segment disabled value=\"enterprise\">\n    Corporativo\n  </Segment>\n</SegmentedControl>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "iconOnly",
+      "title": "Marks without words",
+      "note": "A segment with only a mark draws square and takes its accessible name from an aria-label on its radio, which is the one thing the family cannot supply for a consumer’s own artwork.",
+      "language": "tsx",
+      "source": "<SegmentedControl aria-label=\"Alinhamento\" defaultValue=\"center\">\n  <Segment aria-label=\"Início\" icon={<AlignStartIcon />} value=\"start\" />\n  <Segment aria-label=\"Centro\" icon={<AlignCenterIcon />} value=\"center\" />\n</SegmentedControl>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "condense",
+      "title": "Narrower than its words",
+      "note": "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.",
+      "language": "tsx",
+      "source": "<SegmentedControl aria-label=\"Relatório\" condense=\"icons\" defaultValue=\"table\">\n  <Segment icon={<TableIcon />} value=\"table\">\n    Tabela\n  </Segment>\n  <Segment icon={<ChartIcon />} value=\"chart\">\n    Gráfico\n  </Segment>\n</SegmentedControl>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "width",
+      "title": "Content width, or the whole line",
+      "note": "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.",
+      "language": "tsx",
+      "source": "<SegmentedControl aria-label=\"Entrega\" defaultValue=\"afternoon\" fullWidth>\n  <Segment value=\"morning\">Manhã</Segment>\n  <Segment value=\"afternoon\">Tarde</Segment>\n  <Segment value=\"evening\">Noite</Segment>\n</SegmentedControl>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "field",
+      "title": "Inside a field",
+      "note": "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.",
+      "language": "tsx",
+      "source": "<Field>\n  <FieldLabel>Moeda da fatura</FieldLabel>\n  <SegmentedControl defaultValue=\"brl\" name=\"currency\">\n    <Segment value=\"brl\">BRL</Segment>\n    <Segment value=\"usd\">USD</Segment>\n  </SegmentedControl>\n  <FieldDescription>A conversão usa a cotação do dia da emissão.</FieldDescription>\n</Field>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "form",
+      "title": "In a form, and submitted",
+      "note": "The segments are real radios sharing one name, so the value reaches FormData with no wiring at all — and required puts the browser’s own constraint validation behind it.",
+      "language": "tsx",
+      "source": "<form\n  onSubmit={(event) => {\n    event.preventDefault();\n    const data = new FormData(event.currentTarget);\n    console.log(data.get('currency'));\n  }}\n>\n  <SegmentedControl aria-label=\"Moeda\" defaultValue=\"brl\" name=\"currency\">\n    <Segment value=\"brl\">BRL</Segment>\n    <Segment value=\"usd\">USD</Segment>\n  </SegmentedControl>\n</form>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "content",
+      "title": "Content the family did not choose",
+      "note": "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.",
+      "language": "tsx",
+      "source": "<SegmentedControl aria-label=\"Frequência\" defaultValue=\"now\" fullWidth>\n  <Segment value=\"now\">Imediatamente</Segment>\n  <Segment value=\"digest\">Uma vez por dia, no resumo da noite</Segment>\n</SegmentedControl>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "composition",
+      "title": "Substituting a root, and setting the defaults once",
+      "note": "render hands the track every attribute it was going to write; the provider states the axes once for a whole application. The radio itself is fixed, and the page says why.",
+      "language": "tsx",
+      "source": "<SegmentedControlDefaultsProvider fullWidth size=\"sm\">\n  <SegmentedControl aria-label=\"Visualização\" render={(props) => <nav {...props} />}>\n    <Segment value=\"grid\">Grade</Segment>\n  </SegmentedControl>\n</SegmentedControlDefaultsProvider>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "keyboard",
+      "title": "The keyboard, key by key",
+      "note": "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.",
+      "language": "tsx",
+      "source": "<SegmentedControl aria-label=\"Envio\">\n  <Segment value=\"standard\">Padrão</Segment>\n  <Segment value=\"express\">Expresso</Segment>\n</SegmentedControl>;\n",
+      "verdict": "excerpt"
+    }
+  ]
+}