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

package/docs/field-group.md

@@ -0,0 +1,181 @@
+<!-- index: ./index.md -->
+# field-group
+
+`data-ui="field-group"` · Fieldset that groups related fields.
+
+## Import
+
+```ts
+import {
+  SlFieldGroup,
+  SlFieldGroupDescription,
+  SlFieldGroupError,
+  SlFieldGroupLegend,
+} from '@slotted/angular/field-group';
+```
+
+Selector: `fieldset[slFieldGroup]` · exportAs: `slFieldGroup`
+
+## Minimal example
+
+Excerpt — not a complete module
+
+```html
+<fieldset slFieldGroup>
+  <legend slFieldGroupLegend>Endereço de cobrança</legend>
+  <span slFieldGroupDescription>Precisamos dele para emitir a nota fiscal.</span>
+  <div slField>
+    <label slFieldLabel>Logradouro</label>
+    <input slFieldControl />
+  </div>
+</fieldset>
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | the fieldset the consumer wrote | yes |
+| `legend` | legend[slFieldGroupLegend] | no |
+| `mark` | span, drawn inside the legend | no |
+| `content` | div, drawn by the group around everything projected into it | yes |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `size` | `'sm' \| 'md' \| 'lg'` | md | slFieldGroup | 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 |
+| `orientation` | `'vertical' \| 'horizontal'` | vertical | slFieldGroup | 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 |
+| `necessity` | `'mark' \| 'optional' \| 'words' \| 'none'` | mark | slFieldGroup | 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 |
+| `messages` | `Partial<FieldMessages>` | — | slFieldGroup | Words laid over the language in force for the legend’s necessity word (optional, required); a field inside states its own |
+| `labelPlacement` | `'top' \| 'side'` | from the field token | slFieldGroup | 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 |
+| `required` | `boolean` | — | slFieldGroup | 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 |
+| `invalid` | `boolean` | — | slFieldGroup | 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 |
+| `disabled` | `boolean` | — | slFieldGroup | 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 |
+| `readOnly` | `boolean` | — | slFieldGroup | Provided to every field inside. There is no native readonly on a fieldset, so this one is passed on rather than applied |
+| `id` | `string` | generated | slFieldGroup | 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 |
+| `tone` | `'accent' \| 'secondary' \| 'success' \| 'warning' \| 'danger'` | secondary on slFieldGroupDescription, danger on slFieldGroupError | slFieldGroupDescription, slFieldGroupError | 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 |
+| `mark` | `'glyph' \| 'dot' \| 'none'` | none | slFieldGroupDescription, slFieldGroupError | 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 |
+| `live` | `'off' \| 'polite' \| 'assertive'` | off | slFieldGroupDescription, slFieldGroupError | 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 |
+| `reserve` | `boolean` | false | slFieldGroupDescription, slFieldGroupError | Holds one line box open whether or not there is a message, so the fields below do not move when the error arrives |
+| `exportAs="slFieldGroup"` | `SlFieldGroup` | — | slFieldGroup | 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 |
+| `ng-content` | `projected content` | — | slFieldGroup | 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 |
+| `SlFieldDefaultsSource` | `abstract class` | — | slFieldGroup | 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 |
+| `provideFieldDefaults()` | `{ size, labelPlacement, necessity, disabled, readOnly }` | — | an application or a route | 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 |
+
+## Axes and defaults
+
+| Axis | Values | Default |
+| --- | --- | --- |
+| `size` | `sm`, `md`, `lg` | `md` |
+| `orientation` | `vertical`, `horizontal` | `vertical` |
+| `necessity` | `mark`, `optional`, `words`, `none` | `mark` |
+
+## Rules
+
+- 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
+
+### A column of fields, or a row
+
+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.
+
+Excerpt — not a complete module
+
+```html
+<fieldset slFieldGroup orientation="horizontal">
+  <legend slFieldGroupLegend>Vigência do contrato</legend>
+  <div slField>…</div>
+  <div slField>…</div>
+</fieldset>
+```
+
+### Disabled by the platform, invalid by the group
+
+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.
+
+Excerpt — not a complete module
+
+```html
+<fieldset slFieldGroup disabled>
+  <legend slFieldGroupLegend>Repasse automático</legend>
+  <div slField>…</div>
+</fieldset>
+```
+
+### What is said about the set, before the set
+
+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.
+
+Excerpt — not a complete module
+
+```html
+<fieldset slFieldGroup invalid required>
+  <legend slFieldGroupLegend>Nacionalidade</legend>
+  <span slFieldGroupDescription>Marque todas as que se aplicam.</span>
+  <span slFieldGroupError>Escolha ao menos uma nacionalidade.</span>
+  <label for="nat-br"><input id="nat-br" type="checkbox" /> Brasileira</label>
+</fieldset>
+```
+
+### One attribute instead of one per field
+
+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.
+
+Excerpt — not a complete module
+
+```html
+<fieldset slFieldGroup size="sm" labelPlacement="side">
+  <div slField>…</div>
+  <div slField size="lg">…</div>
+</fieldset>
+```
+
+### A legend that is also the page heading
+
+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.
+
+Excerpt — not a complete module
+
+```html
+<fieldset slFieldGroup required necessity="words">
+  <legend slFieldGroupLegend><h1>Qual é a sua nacionalidade?</h1></legend>
+</fieldset>
+```
+
+### Composition and escape hatches
+
+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.
+
+Excerpt — not a complete module
+
+```html
+<fieldset slFieldGroup size="sm">
+  <fieldset slFieldGroup necessity="none" orientation="horizontal">
+    <legend slFieldGroupLegend>Vigência</legend>
+    <div slField>…</div>
+  </fieldset>
+</fieldset>
+```
+
+### What a reader hears on entering the set
+
+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.
+
+Excerpt — not a complete module
+
+```html
+<fieldset data-ui="field-group" data-part="root" aria-describedby="nat-description nat-error">
+  <legend data-part="legend">Nacionalidade</legend>
+</fieldset>
+```