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

package/dist/docs/event-calendar.md

@@ -0,0 +1,188 @@
+<!-- index: ./index.md -->
+# event-calendar
+
+`data-ui="event-calendar"` · Month, week, day and list views of events.
+
+## Import
+
+```tsx
+import { EventCalendar, EventCalendarDefaultsProvider, SlottedProvider } from '@slotted/react';
+import type { CalendarEvent } from '@slotted/react';
+import { wallClockIn } from '@slotted/core/date';
+```
+
+## Minimal example
+
+Excerpt — not a complete module
+
+```tsx
+<EventCalendar
+  calendars={calendars}
+  events={events}
+  onRangeChange={fetchRange}
+  renderEventDetail={(occurrence) => <EventSummary occurrence={occurrence} />}
+  selectionMode="range"
+  timeZone="America/Sao_Paulo"
+/>;
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | div | yes |
+| `header` | div | no |
+| `title` | h2 (level) | yes |
+| `navigation` | div role=group | yes |
+| `previous` | button | yes |
+| `today` | button | yes |
+| `next` | button | yes |
+| `views` | div holding a SegmentedControl | no |
+| `filter` | button, the Menu trigger | no |
+| `actions` | div | no |
+| `body` | div | yes |
+| `loader` | div holding a ProgressBar | yes |
+| `error` | div | no |
+| `month` | table role=grid | no |
+| `weekdays` | tr | no |
+| `week-number-header` | th | no |
+| `weekday` | th, or span in a column header | no |
+| `week` | tr | no |
+| `week-number` | th scope=row | no |
+| `day` | td role=gridcell | no |
+| `day-header` | div | no |
+| `day-number` | button | no |
+| `day-content` | div | no |
+| `day-events` | div | no |
+| `event` | a with href, button without | yes |
+| `event-time` | span | no |
+| `event-title` | span | yes |
+| `event-location` | span | no |
+| `event-meta` | span, visually hidden | yes |
+| `resize-handle` | span aria-hidden | no |
+| `continuation` | span, visually hidden | no |
+| `more` | button | no |
+| `time-grid` | div role=grid | no |
+| `time-head` | div role=rowgroup | no |
+| `columns` | div role=row | no |
+| `zone` | div role=columnheader | no |
+| `column-header` | div role=columnheader | no |
+| `offset-change` | span role=note | no |
+| `all-day-row` | div role=row | no |
+| `all-day-label` | div role=rowheader | no |
+| `all-day-cell` | div role=gridcell | no |
+| `scroller` | div role=rowgroup | no |
+| `time-row` | div role=row | no |
+| `gutter` | div role=rowheader | no |
+| `hour` | span | no |
+| `column` | div role=gridcell | no |
+| `off-hours` | div aria-hidden | no |
+| `now` | div aria-hidden | no |
+| `offset-line` | div aria-hidden | no |
+| `selection` | div aria-hidden | no |
+| `list` | div | no |
+| `list-day` | section | no |
+| `list-day-heading` | h3 (level + 1) | no |
+| `detail-day` | span | no |
+| `detail-range` | span | no |
+| `list-weekday` | span | no |
+| `list-date` | span | no |
+| `list-events` | ul role=list | no |
+| `empty` | div | no |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `events` | `readonly CalendarEvent[]` | — | EventCalendar | The consumer’s events; a start without a time is all-day |
+| `calendars` | `readonly EventCalendarCalendar[]` | [] | EventCalendar | Key, label and an optional colour slot 1–8 |
+| `date` | `PlainDate` | — | EventCalendar | The day the calendar is on; present means controlled |
+| `defaultDate` | `PlainDate` | today in timeZone | EventCalendar | Read once; pass it when rendering on a server |
+| `view` | `'month' \| 'week' \| 'day' \| 'list'` | month | EventCalendar | Present means controlled; uncontrolled opens on the first of views |
+| `defaultView` | `EventCalendarView` | views[0] | EventCalendar | Read once |
+| `views` | `readonly EventCalendarView[]` | month,week,day,list | EventCalendar | The switcher, in order |
+| `visibleCalendars` | `readonly string[]` | — | EventCalendar | Keys drawn; present means controlled |
+| `defaultVisibleCalendars` | `readonly string[]` | every calendar | EventCalendar | Read once |
+| `selectionMode` | `'none' \| 'range'` | none | EventCalendar | Whether empty time can be chosen |
+| `selection` | `EventCalendarSelection \| null` | — | EventCalendar | The chosen stretch; present means controlled |
+| `defaultSelection` | `EventCalendarSelection \| null` | null | EventCalendar | Read once |
+| `openEvent` | `string \| null` | — | EventCalendar | The open occurrence’s key; present means controlled |
+| `defaultOpenEvent` | `string \| null` | null | EventCalendar | Read once |
+| `renderEventDetail` | `(occurrence, { close }) => ReactNode` | — | EventCalendar | Given, the family hosts the detail popover |
+| `renderContextMenu` | `(target) => ReactNode` | — | EventCalendar | Given, the body is a context-menu target; target is { kind: "event", occurrence } or { kind: "slot", slot }; nothing returned keeps the browser’s menu |
+| `renderEvent` | `(occurrence, { layout, date, content }) => ReactNode` | — | EventCalendar | Replaces an event’s content, not its element |
+| `renderDayContent` | `(date, { view }) => ReactNode` | — | EventCalendar | Writes into every day header |
+| `filter` | `(occurrence) => boolean` | — | EventCalendar | Keeps an occurrence when true |
+| `editable` | `boolean \| (occurrence) => boolean` | false | EventCalendar | Events move and resize, by dragging or by Alt and the arrows |
+| `canDrop` | `(change) => boolean` | — | EventCalendar | Whether a destination is allowed, asked with the change onEventChange would receive |
+| `workingHours` | `readonly WorkingHours[]` | [] | EventCalendar | Shades the time outside them |
+| `actions` | `ReactNode` | — | EventCalendar | At the end of the header |
+| `header` | `boolean` | true | EventCalendar | false draws none, for a calendar driven from outside |
+| `empty` | `ReactNode` | — | EventCalendar | After the list’s empty sentence |
+| `error` | `ReactNode` | — | EventCalendar | Above the grid |
+| `loading` | `boolean` | false | EventCalendar | Events are coming; the grid stays |
+| `loadingDelay` | `number` | 200 | EventCalendar, EventCalendarDefaultsProvider | Milliseconds before the indicator shows |
+| `loadingMinDuration` | `number` | 400 | EventCalendar, EventCalendarDefaultsProvider | Milliseconds it holds once shown |
+| `level` | `2 \| 3 \| 4 \| 5` | 2 | EventCalendar | The title’s heading level; list days are one below |
+| `compact` | `'list' \| 'keep'` | list | EventCalendar, EventCalendarDefaultsProvider | Month and week below 600 pixels |
+| `dayHours` | `readonly [number, number]` | 0,24 | EventCalendar, EventCalendarDefaultsProvider | The first visible hour and the hour the grid stops at |
+| `scrollTime` | `PlainTime` | 07:00 | EventCalendar, EventCalendarDefaultsProvider | Where the hours open |
+| `slotDuration` | `number` | 30 | EventCalendar, EventCalendarDefaultsProvider | Minutes between rules, 5 to 120, and the step of a selection, a drag and Alt with an arrow |
+| `maxEvents` | `number` | 3 | EventCalendar, EventCalendarDefaultsProvider | Lanes a month day draws before +N |
+| `maxColumns` | `number` | 6 | EventCalendar, EventCalendarDefaultsProvider | Columns a cluster takes before +N, never more than fit at 56 pixels each |
+| `weekends` | `'shown' \| 'hidden'` | shown | EventCalendar, EventCalendarDefaultsProvider | A working week |
+| `weekNumbers` | `boolean` | false | EventCalendar, EventCalendarDefaultsProvider | ISO week numbers in the month |
+| `fixedWeeks` | `boolean` | false | EventCalendar, EventCalendarDefaultsProvider | Six rows in every month |
+| `listRange` | `'week' \| 'month'` | week | EventCalendar, EventCalendarDefaultsProvider | The period of the list view |
+| `locale` | `string` | SlottedProvider | EventCalendar | BCP 47; decides the first day and the clock. Unset, the language in force decides |
+| `timeZone` | `string` | runtime | EventCalendar, EventCalendarDefaultsProvider | Today, now and the gutter’s label |
+| `firstDayOfWeek` | `number` | locale | EventCalendar, EventCalendarDefaultsProvider | 0 is Sunday |
+| `hourCycle` | `'h12' \| 'h23'` | locale | EventCalendar, EventCalendarDefaultsProvider | The clock |
+| `messages` | `Partial<EventCalendarMessages>` | — | EventCalendar | Words laid over the language in force, key by key; a group (previous, next, view, empty) is laid over entry by entry |
+| `render` | `(props: EventCalendarRootProps) => ReactNode` | — | EventCalendar | Substitutes the root element |
+| `ref` | `Ref<EventCalendarHandle>` | — | EventCalendar | element, focus(), focusDate(date), focusEvent(key), scrollToTime(time) |
+| `native props` | `ComponentPropsWithoutRef<"div">` | — | EventCalendar | id, className, data-*, aria-* and handlers reach the root; onKeyDown and onPointerDown run after the family’s own |
+
+## Events
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `onDateChange` | `(date: PlainDate, request: ChangeRequest<PlainDate>)` | Before the day moves: Previous, Next, Today, a day number (pointer, keyboard), an arrow or Page key (keyboard), focusDate (programmatic). cancel() refuses it. |
+| `onViewChange` | `(view, request: ChangeRequest<EventCalendarView>)` | Before the view moves: the switcher, or a day number drilling into the day. |
+| `onVisibleCalendarsChange` | `(keys: readonly string[], request)` | Before a calendar is shown or hidden from the filter menu (pointer, keyboard). |
+| `onSelectionChange` | `(selection: EventCalendarSelection \| null, request)` | Before the chosen stretch moves: a drag (pointer), Space or Shift and the arrows (keyboard), Escape (escape). Not emitted for an equal stretch. |
+| `onOpenEventChange` | `(key: string \| null, request)` | Before an event opens or closes: a press (pointer, keyboard), the close button (dismiss), Escape (escape), a press outside the popover (outsidePress), close() (programmatic). |
+| `onEventChange` | `(change: { key, event, occurrence, recurring, kind, start, end }, request)` | Before an event moves or its end does: a drag released (pointer), Alt or Alt+Shift with an arrow (keyboard). start and end are in the kind the event holds. Not a model: the application answers by changing events. |
+| `onRangeChange` | `({ start: PlainDate, end: PlainDate, view })` | After the period in view changes, the first render included. A fact to fetch by, not a model. |
+
+## Axes and defaults
+
+| Axis | Values | Default |
+| --- | --- | --- |
+| `view` | `month`, `week`, `day`, `list` | `month` |
+| `weekends` | `shown`, `hidden` | `shown` |
+| `listRange` | `week`, `month` | `week` |
+| `compact` | `list`, `keep` | `list` |
+| `selectionMode` | `none`, `range` | `none` |
+| `weekNumbers` | `off`, `on` | `false` |
+| `fixedWeeks` | `off`, `on` | `false` |
+| `status` | `confirmed`, `tentative`, `cancelled` | — |
+| `color` | `1`, `2`, `3`, `4`, `5`, `6`, `7`, `8` | — |
+
+## Rules
+
+- No Authoring Practices pattern covers a calendar of events. The month and the week are the layout grid of the Grid pattern with the day as its cell: one cell holds the tab stop, arrows move the day, Enter goes into the day’s widgets and Escape or F2 comes back out, which is the pattern’s own answer for a cell holding several widgets.
+- Every event is named by its own content — its time, its title — and a visually hidden continuation of the whole range, its calendar, its status and whether it repeats. Position and colour state nothing the words do not; a multi-day bar is heard as continuing on each day it crosses.
+- The title is a polite live region, so paging by key announces the new period; a chosen stretch is announced once through the shared live announcer, and a wait once when its indicator appears.
+- The list is not a grid: each day is a section named by its heading and every event is in the tab order, because a list read top to bottom has no second axis. Below 600 pixels the month and the week become that list, and the view the reader chose does not change.
+- Every move a pointer makes has a key: with an editable event focused, Alt and the arrows move it a slot or a day, and Alt with Shift moves its end. The request is announced once with the title and the new range, and focus stays on the event where it lands. A destination canDrop refuses is passed over for the next allowed one; with none in reach the event stays and the refusal is announced.
+- With renderContextMenu, Shift+F10 and the ContextMenu key open the menu on the focused event, or on the selection or the day of the focused cell; the menu is named by the event’s title or the stretch in words, and closing it returns focus to where it was.
+- No single-letter shortcut is bound: a calendar lives in a page with shortcuts of its own, and a bare letter in a grid collides with a screen reader’s quick navigation.
+
+## Tokens
+
+`--slotted-border-strong`, `--slotted-border-subtle`, `--slotted-border-width-medium`, `--slotted-border-width-thick`, `--slotted-border-width-thin`, `--slotted-control-border-color`, `--slotted-control-font-family`, `--slotted-control-font-size-md`, `--slotted-control-font-size-sm`, `--slotted-control-gap-md`, `--slotted-control-height-md`, `--slotted-control-height-sm`, `--slotted-control-icon-size-md`, `--slotted-control-inner-size-lg`, `--slotted-control-inner-size-md`, `--slotted-control-inner-size-sm`, `--slotted-control-padding-inline-md`, `--slotted-control-radius`, `--slotted-control-shadow`, `--slotted-control-surface`, `--slotted-control-transition-duration`, `--slotted-control-transition-easing`, `--slotted-data-1`, `--slotted-data-2`, `--slotted-data-3`, `--slotted-data-4`, `--slotted-data-5`, `--slotted-data-6`, `--slotted-data-7`, `--slotted-data-8`, `--slotted-duration-instant`, `--slotted-duration-short`, `--slotted-easing-enter`, `--slotted-easing-exit`, `--slotted-event-calendar-background`, `--slotted-event-calendar-event-radius`, `--slotted-event-calendar-hour-size`, `--slotted-event-calendar-now-color`, `--slotted-event-calendar-off-background`, `--slotted-event-calendar-rule-color`, `--slotted-event-calendar-selection-background`, `--slotted-event-calendar-selection-border-color`, `--slotted-event-calendar-today-background`, `--slotted-event-calendar-today-color`, `--slotted-focus-ring-color`, `--slotted-focus-ring-offset`, `--slotted-focus-ring-width`, `--slotted-font-family-heading`, `--slotted-font-family-sans`, `--slotted-font-size-lg`, `--slotted-font-size-md`, `--slotted-font-size-sm`, `--slotted-font-size-xs`, `--slotted-font-weight-medium`, `--slotted-font-weight-regular`, `--slotted-font-weight-semibold`, `--slotted-line-height-lg`, `--slotted-line-height-sm`, `--slotted-line-height-xs`, `--slotted-radius-full`, `--slotted-radius-sm`, `--slotted-shadow-md`, `--slotted-shadow-sm`, `--slotted-space-1`, `--slotted-space-10`, `--slotted-space-11`, `--slotted-space-12`, `--slotted-space-2`, `--slotted-space-3`, `--slotted-space-4`, `--slotted-space-5`, `--slotted-space-6`, `--slotted-space-9`, `--slotted-surface`, `--slotted-target-min`, `--slotted-text`, `--slotted-text-muted`, `--slotted-tone-accent-border`, `--slotted-tone-accent-on-solid`, `--slotted-tone-accent-solid`, `--slotted-tone-accent-surface`, `--slotted-tone-accent-text`, `--slotted-tone-danger-border`, `--slotted-tone-secondary-subtle-active`, `--slotted-tone-secondary-subtle-hover`
+
+## Examples
+
+See [event-calendar.examples.md](./event-calendar.examples.md).

package/dist/docs/field-group.json

@@ -0,0 +1,331 @@
+{
+  "family": "field-group",
+  "ui": "field-group",
+  "binding": "react",
+  "catalog": {
+    "group": "Forms",
+    "summary": "Fieldset that groups related fields."
+  },
+  "axes": {
+    "size": [
+      "sm",
+      "md",
+      "lg"
+    ],
+    "orientation": [
+      "vertical",
+      "horizontal"
+    ],
+    "necessity": [
+      "mark",
+      "optional",
+      "words",
+      "none"
+    ]
+  },
+  "members": {
+    "fieldGroup": {
+      "nativeElement": "fieldset",
+      "defaults": {
+        "size": "md",
+        "orientation": "vertical",
+        "necessity": "mark"
+      },
+      "capabilities": [
+        "appearance",
+        "orientation",
+        "size",
+        "live",
+        "disabled",
+        "invalid",
+        "required",
+        "readOnly",
+        "wiring"
+      ],
+      "states": [
+        "default",
+        "disabled",
+        "invalid",
+        "required",
+        "readonly"
+      ],
+      "parts": [
+        "root",
+        "legend",
+        "mark",
+        "content"
+      ]
+    }
+  },
+  "docs": {
+    "fieldGroup": {
+      "imports": {
+        "source": "import {\n  FieldGroup,\n  FieldGroupContent,\n  FieldGroupDescription,\n  FieldGroupError,\n  FieldGroupLegend,\n} from '@slotted/react';"
+      },
+      "anatomy": [
+        {
+          "part": "root",
+          "element": "fieldset, or the element render returns",
+          "required": true,
+          "purpose": "The group. A native fieldset, so the group role arrives from the platform and disabled disables every control inside it with nothing passed down. Carries data-ui=\"field-group\", the axes, and the four state attributes."
+        },
+        {
+          "part": "legend",
+          "element": "legend",
+          "required": false,
+          "purpose": "The name of the set, and the platform’s own naming element — the technique the APG’s naming practice calls for under its Rule 3. It holds whatever the page puts in it, including the page’s own heading."
+        },
+        {
+          "part": "mark",
+          "element": "span, inside the legend",
+          "required": false,
+          "purpose": "The necessity marker the legend draws itself, in the same three forms a field label draws: an asterisk, the words, or nothing."
+        },
+        {
+          "part": "content",
+          "element": "div, or the element render returns",
+          "required": false,
+          "purpose": "The box that lays the fields out, and the element orientation arranges. It exists because a legend inside a grid or flex container is laid out by rules of its own in every engine, so the fieldset stays a block."
+        }
+      ],
+      "api": [
+        {
+          "name": "size",
+          "type": "'sm' | 'md' | 'lg'",
+          "defaultValue": "md",
+          "appliesTo": "FieldGroup",
+          "description": "The type step of the legend, and the step provided to every field inside. The legend reads the control type scale one step above the labels under it, so a group in a dense table shrinks with them"
+        },
+        {
+          "name": "orientation",
+          "type": "'vertical' | 'horizontal'",
+          "defaultValue": "vertical",
+          "appliesTo": "FieldGroup",
+          "description": "How the fields inside flow. A row wraps rather than squeezing, so a field keeps enough width to hold what is being typed into it"
+        },
+        {
+          "name": "necessity",
+          "type": "'mark' | 'optional' | 'words' | 'none'",
+          "defaultValue": "mark",
+          "appliesTo": "FieldGroup",
+          "description": "How the set’s necessity is said on its legend — an asterisk, (optional) on an optional set only, both words, or nothing — and the style provided to every field inside"
+        },
+        {
+          "name": "messages",
+          "type": "Partial<FieldMessages>",
+          "defaultValue": "—",
+          "appliesTo": "FieldGroup",
+          "description": "Words laid over the language in force for the legend’s necessity word (optional, required); a field inside states its own"
+        },
+        {
+          "name": "labelPlacement",
+          "type": "'top' | 'side'",
+          "defaultValue": "from the field provider",
+          "appliesTo": "FieldGroup",
+          "description": "Provided to every field inside. The group has no label of its own, so this is the one axis it carries only to pass on"
+        },
+        {
+          "name": "required",
+          "type": "boolean",
+          "defaultValue": "—",
+          "appliesTo": "FieldGroup",
+          "description": "Draws the necessity marker on the legend. It is deliberately not provided to the fields: required is a fact about one value, and a section cannot know it"
+        },
+        {
+          "name": "invalid",
+          "type": "boolean",
+          "defaultValue": "—",
+          "appliesTo": "FieldGroup",
+          "description": "Unstated rather than false. Writes data-invalid on the fieldset, for the case a single field cannot state — “choose at least one” is a fact about the set"
+        },
+        {
+          "name": "disabled",
+          "type": "boolean",
+          "defaultValue": "—",
+          "appliesTo": "FieldGroup",
+          "description": "The native attribute on the fieldset, which disables every control inside with nothing passed down, and is also provided to the fields so their labels are muted"
+        },
+        {
+          "name": "readOnly",
+          "type": "boolean",
+          "defaultValue": "—",
+          "appliesTo": "FieldGroup",
+          "description": "Provided to every field inside. There is no native readonly on a fieldset, so this one is passed on rather than applied"
+        },
+        {
+          "name": "id",
+          "type": "string",
+          "defaultValue": "generated",
+          "appliesTo": "FieldGroup",
+          "description": "The base for <id>-legend, <id>-description and <id>-error. Generated with useId when unstated"
+        },
+        {
+          "name": "tone",
+          "type": "'accent' | 'secondary' | 'success' | 'warning' | 'danger'",
+          "defaultValue": "secondary on FieldGroupDescription, danger on FieldGroupError",
+          "appliesTo": "FieldGroupDescription, FieldGroupError",
+          "description": "Both messages are inline-message roots and take its five tones, so a warning about a whole section is the same part in another tone"
+        },
+        {
+          "name": "mark",
+          "type": "'glyph' | 'dot' | 'none'",
+          "defaultValue": "none",
+          "appliesTo": "FieldGroupDescription, FieldGroupError",
+          "description": "Which mark the message draws. A group’s messages draw none, the same as the fields inside it: the tone is said by the ink and the weight of the sentence. glyph asks for the tone’s own silhouette and dot for one neutral bullet"
+        },
+        {
+          "name": "live",
+          "type": "'off' | 'polite' | 'assertive'",
+          "defaultValue": "off",
+          "appliesTo": "FieldGroupDescription, FieldGroupError",
+          "description": "Whether the message announces itself when it arrives. off by default, because a message already on the page when it loads is announced by nothing"
+        },
+        {
+          "name": "reserve",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "FieldGroupDescription, FieldGroupError",
+          "description": "Holds one line box open whether or not there is a message, so the fields below do not move when the error arrives"
+        }
+      ],
+      "composition": [
+        {
+          "name": "render",
+          "type": "(props) => ReactNode",
+          "defaultValue": "—",
+          "appliesTo": "FieldGroup, FieldGroupLegend, FieldGroupContent",
+          "description": "Substitutes the rendered element and hands it every attribute. A ul for the content, a div for the group when a fieldset is not wanted. The props are typed against HTMLAttributes<HTMLElement> so they can be spread onto any element, and a substituted element takes the consumer’s own ref"
+        },
+        {
+          "name": "FieldGroupContent",
+          "type": "ReactNode",
+          "defaultValue": "—",
+          "appliesTo": "FieldGroup",
+          "description": "The box that lays the fields out. It is a part rather than an implicit wrapper because a legend inside a grid or flex container is laid out by rules of its own in every engine"
+        },
+        {
+          "name": "children",
+          "type": "ReactNode",
+          "defaultValue": "—",
+          "appliesTo": "FieldGroupContent",
+          "description": "Anything the set holds: fields, or checkboxes written directly. A checkbox has its own label beside its box, so wrapping each one in a field would give it two"
+        },
+        {
+          "name": "useFieldGroup()",
+          "type": "() => FieldGroupContextValue | undefined",
+          "defaultValue": "—",
+          "appliesTo": "any component inside a FieldGroup",
+          "description": "The three identifiers, the step and the necessity style, for a part of your own. undefined outside a group"
+        }
+      ],
+      "events": [],
+      "accessibility": [
+        "The role and the name both come from the platform. A native fieldset carries the group role and a native legend names it, which is the technique the APG’s Providing Accessible Names and Descriptions practice calls for under its Rule 3, prefer native techniques — so the family writes no role and no aria-label.",
+        "aria-describedby goes on the fieldset rather than on each control. GOV.UK’s error-message-with-legend example is the same arrangement: a reader entering any control in the group hears the group’s hint and its error once, from the element that names them both.",
+        "disabled is the native attribute, and the platform propagates it. Every control inside a disabled fieldset is removed from the tab order and from submission by the browser, with nothing passed down. What the family adds is the muting of the legend and of the fields’ labels, because a label is not a control and nothing in the attribute reaches it.",
+        "The legend holds a heading when the page has one. On a page asking a single question GOV.UK recommends the legend contain the page’s h1, so a reader hears the question once rather than twice; the family removes the heading’s block break and its margins and leaves its type alone, because a page heading is a page’s decision rather than a control’s.",
+        "required marks the legend and stops there. It is a fact about one value, and a section cannot know which of its fields carry it — so the group draws the marker on its own name and provides nothing to the fields.",
+        "A checkbox or a radio belongs directly in the content. Each already has its own label beside its box, and wrapping it in a field would give it two names — which is why the demonstrations here write them directly and the group is the thing that names the set."
+      ]
+    }
+  },
+  "tokens": [
+    "--slotted-control-font-family",
+    "--slotted-control-font-size-lg",
+    "--slotted-control-font-size-md",
+    "--slotted-control-font-size-sm",
+    "--slotted-control-transition-duration",
+    "--slotted-control-transition-easing",
+    "--slotted-disabled-foreground",
+    "--slotted-field-group-content-gap",
+    "--slotted-field-group-field-gap",
+    "--slotted-field-group-font-family",
+    "--slotted-field-group-legend-color",
+    "--slotted-field-group-legend-font-weight",
+    "--slotted-field-group-line-height",
+    "--slotted-field-group-mark-color",
+    "--slotted-field-group-mark-gap",
+    "--slotted-field-group-mark-text-color",
+    "--slotted-field-group-message-gap",
+    "--slotted-field-group-track-min",
+    "--slotted-font-family-heading",
+    "--slotted-font-family-sans",
+    "--slotted-font-size-xs",
+    "--slotted-font-weight-medium",
+    "--slotted-font-weight-regular",
+    "--slotted-font-weight-semibold",
+    "--slotted-line-height-sm",
+    "--slotted-space-2",
+    "--slotted-space-6",
+    "--slotted-space-7",
+    "--slotted-text",
+    "--slotted-text-muted",
+    "--slotted-tone-danger-text"
+  ],
+  "examples": [
+    {
+      "id": "playground",
+      "title": "Playground",
+      "note": "A group with its legend, its help and two fields, driven by the controls below the canvas. Switch orientation to horizontal and narrow the window to see the row wrap rather than squeeze.",
+      "language": "tsx",
+      "source": "<FieldGroup>\n  <FieldGroupLegend>Endereço de cobrança</FieldGroupLegend>\n  <FieldGroupDescription>Precisamos dele para emitir a nota fiscal.</FieldGroupDescription>\n  <FieldGroupContent>\n    <Field>\n      <FieldLabel>Logradouro</FieldLabel>\n      <FieldControl />\n    </Field>\n  </FieldGroupContent>\n</FieldGroup>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "orientation",
+      "title": "A column of fields, or a row",
+      "note": "A row wraps rather than squeezing: each field keeps enough width to hold a date or a document number, and drops to the next line instead of clipping what is being typed into it.",
+      "language": "tsx",
+      "source": "<FieldGroup orientation=\"horizontal\">\n  <FieldGroupLegend>Vigência do contrato</FieldGroupLegend>\n  <FieldGroupContent>\n    <Field>…</Field>\n    <Field>…</Field>\n  </FieldGroupContent>\n</FieldGroup>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "states",
+      "title": "Disabled by the platform, invalid by the group",
+      "note": "Nothing is passed down for disabled: the browser disables every control inside a disabled fieldset. What the family adds is the muting of the words — a legend is not a control, and a section that turned off while keeping its name at full strength reads as available.",
+      "language": "tsx",
+      "source": "// The native attribute. Every control inside is disabled by the browser.\n<FieldGroup disabled>\n  <FieldGroupLegend>Repasse automático</FieldGroupLegend>\n  <FieldGroupContent>…</FieldGroupContent>\n</FieldGroup>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "messages",
+      "title": "What is said about the set, before the set",
+      "note": "The description and the error come between the legend and the fields — where GOV.UK’s fieldset example puts them, and the opposite of where a single field puts its own. Both ids go on the fieldset, so a reader entering any control hears them once.",
+      "language": "tsx",
+      "source": "<FieldGroup invalid required>\n  <FieldGroupLegend>Nacionalidade</FieldGroupLegend>\n  <FieldGroupDescription>Marque todas as que se aplicam.</FieldGroupDescription>\n  <FieldGroupError>Escolha ao menos uma nacionalidade.</FieldGroupError>\n  <FieldGroupContent>…</FieldGroupContent>\n</FieldGroup>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "provision",
+      "title": "One attribute instead of one per field",
+      "note": "The group answers for every field inside it — the step, the placement, the necessity style, both words, disabled and read-only. A field that states its own still wins, which is the same rule a control follows against its field.",
+      "language": "tsx",
+      "source": "<FieldGroup labelPlacement=\"side\" size=\"sm\">\n  <FieldGroupContent>\n    <Field>…</Field>\n    <Field size=\"lg\">…</Field>\n  </FieldGroupContent>\n</FieldGroup>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "content",
+      "title": "A legend that is also the page heading",
+      "note": "GOV.UK recommends it on a page asking one question, so a reader hears the question once rather than twice. The heading keeps its own type and loses only the block break that would drop the necessity words onto a line of their own.",
+      "language": "tsx",
+      "source": "<FieldGroup required necessity=\"words\">\n  <FieldGroupLegend>\n    <h1>Qual é a sua nacionalidade?</h1>\n  </FieldGroupLegend>\n  <FieldGroupContent>…</FieldGroupContent>\n</FieldGroup>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "composition",
+      "title": "Composition and escape hatches",
+      "note": "A group inside a group inherits what the outer one decided and restates the rest; render substitutes any part’s element, and the group holds anything — checkboxes written directly, not one field each.",
+      "language": "tsx",
+      "source": "<FieldGroup size=\"sm\">\n  <FieldGroup necessity=\"none\">\n    <FieldGroupContent render={(props) => <ul {...props} />}>…</FieldGroupContent>\n  </FieldGroup>\n</FieldGroup>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "accessibility",
+      "title": "What a reader hears on entering the set",
+      "note": "Tab into any control: the group’s name and its description are read before the control’s own, because both live on the fieldset rather than on each control. No ARIA is written for either.",
+      "language": "tsx",
+      "source": "<fieldset data-ui=\"field-group\" data-part=\"root\" aria-describedby=\"nat-description nat-error\">\n  <legend data-part=\"legend\">Nacionalidade</legend>\n</fieldset>;\n",
+      "verdict": "excerpt"
+    }
+  ]
+}