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

package/docs/event-calendar.md

@@ -0,0 +1,201 @@
+<!-- index: ./index.md -->
+# event-calendar
+
+`data-ui="event-calendar"` · Month, week, day and list views of events.
+
+## Import
+
+```ts
+import {
+  SlEventCalendar,
+  SlEventCalendarActions,
+  SlEventCalendarDayContent,
+  SlEventCalendarDetail,
+  SlEventCalendarEmpty,
+  SlEventCalendarError,
+  SlEventCalendarEvent,
+  provideEventCalendarDefaults,
+} from '@slotted/angular/event-calendar';
+import { wallClockIn } from '@slotted/core/date';
+```
+
+Selector: `[slEventCalendar]` · exportAs: `slEventCalendar`
+
+## Minimal example
+
+Excerpt — not a complete module
+
+```html
+<div
+  slEventCalendar
+  [calendars]="calendars"
+  [events]="events"
+  selectionMode="range"
+  timeZone="America/Sao_Paulo"
+  (rangeChange)="fetch($event)"
+>
+  <ng-template slEventCalendarDetail let-occurrence
+    ><app-event-summary [occurrence]="occurrence"
+  /></ng-template>
+</div>
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | div slEventCalendar | yes |
+| `header` | div | no |
+| `title` | div role=heading (aria-level = level) | yes |
+| `navigation` | div role=group | yes |
+| `previous` | button | yes |
+| `today` | button | yes |
+| `next` | button | yes |
+| `views` | div holding slSegmentedControl | no |
+| `filter` | button [slMenuTriggerFor] and its sl-menu | no |
+| `actions` | div | no |
+| `body` | div | yes |
+| `loader` | div holding slProgressBar | 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` | div role=heading (aria-level = 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[]` | [] | slEventCalendar | The consumer’s events; a start without a time is all-day |
+| `calendars` | `readonly EventCalendarCalendar[]` | [] | slEventCalendar | Key, label and an optional colour slot 1–8 |
+| `date` | `model<PlainDate \| undefined>` | — | slEventCalendar | The day the calendar is on; [(date)] two-way |
+| `defaultDate` | `PlainDate` | today in timeZone | slEventCalendar | Read once; pass it when rendering on a server |
+| `view` | `model<EventCalendarView \| undefined>` | month | slEventCalendar | [(view)] two-way; unbound opens on the first of views |
+| `defaultView` | `EventCalendarView` | views[0] | slEventCalendar | Read once |
+| `views` | `readonly EventCalendarView[]` | month,week,day,list | slEventCalendar | The switcher, in order |
+| `visibleCalendars` | `model<readonly string[] \| undefined>` | — | slEventCalendar | Keys drawn; [(visibleCalendars)] two-way |
+| `defaultVisibleCalendars` | `readonly string[]` | every calendar | slEventCalendar | Read once |
+| `selectionMode` | `'none' \| 'range'` | none | slEventCalendar | Whether empty time can be chosen |
+| `selection` | `model<EventCalendarSelection \| null \| undefined>` | — | slEventCalendar | The chosen stretch; [(selection)] two-way |
+| `defaultSelection` | `EventCalendarSelection \| null` | null | slEventCalendar | Read once |
+| `openEvent` | `model<string \| null \| undefined>` | — | slEventCalendar | The open occurrence’s key; [(openEvent)] two-way |
+| `defaultOpenEvent` | `string \| null` | null | slEventCalendar | Read once |
+| `filter` | `(occurrence) => boolean` | — | slEventCalendar | Keeps an occurrence when true |
+| `editable` | `boolean \| (occurrence) => boolean` | false | slEventCalendar | Events move and resize, by dragging or by Alt and the arrows |
+| `canDrop` | `(change) => boolean` | — | slEventCalendar | Whether a destination is allowed, asked with the change eventChangeRequest would carry |
+| `workingHours` | `readonly WorkingHours[]` | [] | slEventCalendar | Shades the time outside them |
+| `header` | `boolean` | true | slEventCalendar | false draws none, for a calendar driven from outside |
+| `loading` | `boolean` | false | slEventCalendar | Events are coming; the grid stays |
+| `loadingDelay` | `number` | 200 | slEventCalendar, provideEventCalendarDefaults | Milliseconds before the indicator shows |
+| `loadingMinDuration` | `number` | 400 | slEventCalendar, provideEventCalendarDefaults | Milliseconds it holds once shown |
+| `level` | `number` | 2 | slEventCalendar | The title’s heading level; list days are one below |
+| `compact` | `'list' \| 'keep'` | list | slEventCalendar, provideEventCalendarDefaults | Month and week below 600 pixels |
+| `dayHours` | `readonly [number, number]` | 0,24 | slEventCalendar, provideEventCalendarDefaults | The first visible hour and the hour the grid stops at |
+| `scrollTime` | `PlainTime` | 07:00 | slEventCalendar, provideEventCalendarDefaults | Where the hours open |
+| `slotDuration` | `number` | 30 | slEventCalendar, provideEventCalendarDefaults | Minutes between rules, 5 to 120, and the step of a selection, a drag and Alt with an arrow |
+| `maxEvents` | `number` | 3 | slEventCalendar, provideEventCalendarDefaults | Lanes a month day draws before +N |
+| `maxColumns` | `number` | 6 | slEventCalendar, provideEventCalendarDefaults | Columns a cluster takes before +N, never more than fit at 56 pixels each |
+| `weekends` | `'shown' \| 'hidden'` | shown | slEventCalendar, provideEventCalendarDefaults | A working week |
+| `weekNumbers` | `boolean` | false | slEventCalendar, provideEventCalendarDefaults | ISO week numbers in the month |
+| `fixedWeeks` | `boolean` | false | slEventCalendar, provideEventCalendarDefaults | Six rows in every month |
+| `listRange` | `'week' \| 'month'` | week | slEventCalendar, provideEventCalendarDefaults | The period of the list view |
+| `locale` | `string` | provideSlotted | slEventCalendar | BCP 47; decides the first day and the clock. Unset, the language in force decides |
+| `timeZone` | `string` | runtime | slEventCalendar, provideEventCalendarDefaults | Today, now and the gutter’s label |
+| `firstDayOfWeek` | `number` | locale | slEventCalendar, provideEventCalendarDefaults | 0 is Sunday |
+| `hourCycle` | `'h12' \| 'h23'` | locale | slEventCalendar, provideEventCalendarDefaults | The clock |
+| `messages` | `Partial<EventCalendarMessages>` | — | slEventCalendar | Words laid over the language in force, key by key; a group (previous, next, view, empty) is laid over entry by entry |
+| `ng-template[slEventCalendarEvent]` | `TemplateRef<{ $implicit, layout, date, time }>` | — | content | Replaces an event’s content, not its element |
+| `ng-template[slEventCalendarDetail]` | `TemplateRef<{ $implicit, close }>` | — | content | Given, the family hosts the detail popover |
+| `ng-template[slEventCalendarContextMenu]` | `TemplateRef<{ $implicit: EventCalendarContextTarget }>` | — | content | Given, the body is a context-menu target; the target is { kind: "event", occurrence } or { kind: "slot", slot } |
+| `[slEventCalendarContextMenuFor]` | `(target) => boolean` | every target | content | The targets that have a menu; the others keep the browser’s own |
+| `ng-template[slEventCalendarDayContent]` | `TemplateRef<{ $implicit: PlainDate, view }>` | — | content | Writes into every day header |
+| `[slEventCalendarActions]` | `element` | — | content | Projected at the end of the header |
+| `[slEventCalendarEmpty]` | `element` | — | content | Projected after the list’s empty sentence |
+| `[slEventCalendarError]` | `element` | — | content | Projected above the grid |
+| `exportAs` | `slEventCalendar` | — | slEventCalendar | focus(), focusDate(date), focusEvent(key), scrollToTime(time), currentView() |
+
+## Events
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `dateRequest` | `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; [(date)] then stays. |
+| `viewRequest` | `ChangeRequest<EventCalendarView>` | Before the view moves: the switcher, or a day number drilling into the day. |
+| `visibleCalendarsRequest` | `ChangeRequest<readonly string[]>` | Before a calendar is shown or hidden from the filter menu (pointer, keyboard). |
+| `selectionRequest` | `ChangeRequest<EventCalendarSelection \| null>` | Before the chosen stretch moves: a drag (pointer), Space or Shift and the arrows (keyboard), Escape (escape). |
+| `openEventRequest` | `ChangeRequest<string \| null>` | Before an event opens or closes: a press (pointer, keyboard), the close button (dismiss), Escape (escape), a press outside (outsidePress), close() (programmatic). |
+| `eventChangeRequest` | `ChangeRequest<{ key, event, occurrence, recurring, kind, start, end }>` | 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. |
+| `rangeChange` | `{ start: PlainDate; end: PlainDate; view }` | After the period in view changes, the first render included. A fact to fetch by. |
+
+## 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.
+- Every event is named by its own content and a visually hidden continuation: the whole range, the calendar, the 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 heading and 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 title and the list days are role="heading" with aria-level from the level input, because an Angular template cannot choose an element’s tag at run time; the React binding writes h2 to h6. Both expose the same heading to a screen reader.
+- 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 a context menu template, 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/docs/field-group.json

@@ -0,0 +1,333 @@
+{
+  "family": "field-group",
+  "ui": "field-group",
+  "binding": "angular",
+  "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  SlFieldGroup,\n  SlFieldGroupDescription,\n  SlFieldGroupError,\n  SlFieldGroupLegend,\n} from '@slotted/angular/field-group';",
+        "selector": "fieldset[slFieldGroup]",
+        "exportAs": "slFieldGroup"
+      },
+      "anatomy": [
+        {
+          "part": "root",
+          "element": "the fieldset the consumer wrote",
+          "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[slFieldGroupLegend]",
+          "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, drawn 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, drawn by the group around everything projected into it",
+          "required": true,
+          "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": "slFieldGroup",
+          "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": "slFieldGroup",
+          "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": "slFieldGroup",
+          "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": "slFieldGroup",
+          "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 token",
+          "appliesTo": "slFieldGroup",
+          "description": "Provided to every field inside. The group has no label of its own, so this is the one input it carries only to pass on"
+        },
+        {
+          "name": "required",
+          "type": "boolean",
+          "defaultValue": "—",
+          "appliesTo": "slFieldGroup",
+          "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": "slFieldGroup",
+          "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": "slFieldGroup",
+          "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": "slFieldGroup",
+          "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": "slFieldGroup",
+          "description": "A static attribute, read with HostAttributeToken, that becomes the base for <id>-legend, <id>-description and <id>-error. Generated by an application-scoped factory when unstated"
+        },
+        {
+          "name": "tone",
+          "type": "'accent' | 'secondary' | 'success' | 'warning' | 'danger'",
+          "defaultValue": "secondary on slFieldGroupDescription, danger on slFieldGroupError",
+          "appliesTo": "slFieldGroupDescription, slFieldGroupError",
+          "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": "slFieldGroupDescription, slFieldGroupError",
+          "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": "slFieldGroupDescription, slFieldGroupError",
+          "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": "slFieldGroupDescription, slFieldGroupError",
+          "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": "exportAs=\"slFieldGroup\"",
+          "type": "SlFieldGroup",
+          "defaultValue": "—",
+          "appliesTo": "slFieldGroup",
+          "description": "Hands the template the instance, so a page can point its own element at ids().legend, ids().description or ids().error. There is no imperative method beyond it: the group holds no state and moves nothing"
+        },
+        {
+          "name": "ng-content",
+          "type": "projected content",
+          "defaultValue": "—",
+          "appliesTo": "slFieldGroup",
+          "description": "The legend and the two message markers are selected by name; everything else is projected into the content element, so a group holds fields, checkboxes or another group as written"
+        },
+        {
+          "name": "SlFieldDefaultsSource",
+          "type": "abstract class",
+          "defaultValue": "—",
+          "appliesTo": "slFieldGroup",
+          "description": "What the group answers for the fields under it. It is a method rather than a value handed over once, because Angular creates every directive a template declares before it binds any input"
+        },
+        {
+          "name": "provideFieldDefaults()",
+          "type": "{ size, labelPlacement, necessity, disabled, readOnly }",
+          "defaultValue": "—",
+          "appliesTo": "an application or a route",
+          "description": "The same five decisions, taken once for the whole application. A group overrides them for its own subtree, and an outer group for an inner one"
+        }
+      ],
+      "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": "html",
+      "source": "<fieldset slFieldGroup>\n  <legend slFieldGroupLegend>Endereço de cobrança</legend>\n  <span slFieldGroupDescription>Precisamos dele para emitir a nota fiscal.</span>\n  <div slField>\n    <label slFieldLabel>Logradouro</label>\n    <input slFieldControl />\n  </div>\n</fieldset>\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": "html",
+      "source": "<fieldset slFieldGroup orientation=\"horizontal\">\n  <legend slFieldGroupLegend>Vigência do contrato</legend>\n  <div slField>…</div>\n  <div slField>…</div>\n</fieldset>\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": "html",
+      "source": "<fieldset slFieldGroup disabled>\n  <legend slFieldGroupLegend>Repasse automático</legend>\n  <div slField>…</div>\n</fieldset>\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": "html",
+      "source": "<fieldset slFieldGroup invalid required>\n  <legend slFieldGroupLegend>Nacionalidade</legend>\n  <span slFieldGroupDescription>Marque todas as que se aplicam.</span>\n  <span slFieldGroupError>Escolha ao menos uma nacionalidade.</span>\n  <label for=\"nat-br\"><input id=\"nat-br\" type=\"checkbox\" /> Brasileira</label>\n</fieldset>\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": "html",
+      "source": "<fieldset slFieldGroup size=\"sm\" labelPlacement=\"side\">\n  <div slField>…</div>\n  <div slField size=\"lg\">…</div>\n</fieldset>\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": "html",
+      "source": "<fieldset slFieldGroup required necessity=\"words\">\n  <legend slFieldGroupLegend><h1>Qual é a sua nacionalidade?</h1></legend>\n</fieldset>\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; exportAs hands the template the identifiers the group derived, and the content slot holds anything — checkboxes written directly, not one field each.",
+      "language": "html",
+      "source": "<fieldset slFieldGroup size=\"sm\">\n  <fieldset slFieldGroup necessity=\"none\" orientation=\"horizontal\">\n    <legend slFieldGroupLegend>Vigência</legend>\n    <div slField>…</div>\n  </fieldset>\n</fieldset>\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": "html",
+      "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"
+    }
+  ]
+}