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

package/docs/result-state.md

@@ -0,0 +1,286 @@
+<!-- index: ./index.md -->
+# result-state
+
+`data-ui="result-state"` · Empty, no-results, error or success state.
+
+## Import
+
+```ts
+import {
+  provideResultStateDefaults,
+  SlResultState,
+  SlResultStateActions,
+  SlResultStateContent,
+  SlResultStateDescription,
+  SlResultStateFooter,
+  SlResultStateMedia,
+  SlResultStateTitle,
+} from '@slotted/angular/result-state';
+```
+
+Selector: `[slResultState]` · exportAs: `slResultState`
+
+## Minimal example
+
+Excerpt — not a complete module
+
+```html
+<section slResultState status="empty">
+  <div slResultStateContent>
+    <div slResultStateTitle>Nenhum projeto ainda</div>
+    <p slResultStateDescription>Crie um projeto para começar a coletar execuções.</p>
+  </div>
+  <div slResultStateActions>
+    <button slButton type="button">Criar projeto</button>
+  </div>
+</section>
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | section, the element the directive is written on | yes |
+| `media` | div, rendered by the directive | no |
+| `content` | the element slResultStateContent is written on | yes |
+| `title` | the element slResultStateTitle is written on — a div, or an h2 | no |
+| `description` | the element slResultStateDescription is written on — a p | no |
+| `actions` | the element slResultStateActions is written on | no |
+| `footer` | the element slResultStateFooter is written on | no |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `status` | `'empty' \| 'no-results' \| 'not-found' \| 'error' \| 'forbidden' \| 'offline' \| 'success'` | empty | slResultState | What the region is reporting, written on the root as data-status for a page to key its own artwork on. The family paints nothing for it (RS1): what happened is in the title |
+| `reach` | `'inline' \| 'section' \| 'page'` | section | slResultState | The scope the message applies to. inline is a row for a table cell and draws no illustration; page takes the top step of the type scale and draws the illustration half again as large |
+| `align` | `'center' \| 'start'` | center | slResultState | Whether the region reads centred or from the inline edge. start is for a data-dense screen, where a centred column reads as an interruption |
+| `live` | `'off' \| 'polite' \| 'assertive'` | polite | slResultState | Whether the text announces itself. polite writes role="status" on the content part and assertive writes role="alert"; both imply aria-live and aria-atomic, and neither is written on the box |
+| `illustration` | `'none' \| 'tile' \| 'stack' \| 'cards'` | none | slResultState | The drawing the family makes around the projected slResultStateMedia, in the neutral surface and border roles and never in a tone. tile and stack frame a glyph and draw nothing without one; cards draws its lines with or without it; none draws nothing of the family’s own |
+| `slResultStateMedia` | `directive` | — | a projected element | The glyph an illustration is drawn around, or artwork the page supplies under illustration="none". It is projected into the box the family draws, so it keeps the height the reach gives it. React passes a media node instead |
+| `exportAs` | `slResultState` | — | slResultState | Reaches the instance from the template, which is what focus() is called on. It is the reach a template has and React does not: JSX re-renders an input, and a template calls a method |
+| `focus()` | `() => void` | — | slResultState | Sends the keyboard to the region, which carries tabindex="-1". It is the whole imperative surface: the family never moves focus by itself, because moving it unprompted is a change of context nobody asked for |
+| `id` | `string` | — | slResultStateTitle | An identifier the page writes is read with HostAttributeToken before the host binding, kept, and pointed at by the root’s aria-labelledby |
+| `provideResultStateDefaults` | `(defaults: Partial<ResultStateDefaults>) => Provider` | — | an application or a route | Sets status, reach, align, live and illustration once for every region under it; an explicit input on one region still wins |
+| `ng-content` | `projection` | — | slResultState | The parts are directives on the consumer’s own elements, so every one of them is the page’s to choose. Anything placed inside slResultStateContent joins the live region, which is why the actions and the footer are parts of their own |
+| `slContainer, slCard` | `composition` | — | around slResultState | The measure belongs to container and the frame to card. This family caps no width and draws no box, because two families answering one question is two answers |
+
+## Axes and defaults
+
+| Axis | Values | Default |
+| --- | --- | --- |
+| `status` | `empty`, `no-results`, `not-found`, `error`, `forbidden`, `offline`, `success` | `empty` |
+| `reach` | `inline`, `section`, `page` | `section` |
+| `align` | `center`, `start` | `center` |
+| `illustration` | `none`, `tile`, `stack`, `cards` | `none` |
+| `live` | `off`, `polite`, `assertive` | `polite` |
+
+## Rules
+
+- There is no APG pattern for this family: the Authoring Practices list holds no empty, error or result state, and the nearest official guidance is the Region landmark practice, which states that “a region landmark must have a label”. The root is a section and the attribute is written only once a title exists, so an unlabelled region is a plain grouping element rather than a landmark with no name.
+- The box is a landmark, not a live region. MDN’s alert role reference states that the role “should only be used for text content, not interactive elements such as links or buttons”, and this family has a row of buttons in it. The region that announces is slResultStateContent, which holds the title and the description alone; the mark, the actions and the footer are its siblings.
+- live defaults to polite, which is the one place this family and alert disagree. WCAG 2.2’s Understanding document for SC 4.1.3 names this family’s own text as its example: “brief text messages displayed about the completion or status of the search, such as ‘Searching…’, ‘18 results returned’ or ‘No results returned’ would be status updates”. An alert may be a standing notice that was on the page before it loaded; a result is always the outcome of an operation. None of the seven surveyed implementations writes a live role of any kind.
+- Status is never carried by colour alone, because the family paints no colour for it: what happened is in the title and the description, which forced colours leave legible. The illustrations keep the theme’s system-colour mapping under forced colours, so a stack is still three layers and not three outlines laid over one another.
+- The media box is hidden from assistive technology, with the projected glyph, the drawing made around it and any artwork the page supplies. The title and the description already say what the picture says; an illustration that adds information is not decorative, and what it adds belongs in the description.
+- The root carries tabindex="-1" and is not in the tab sequence. A template that has just emptied a table calls focus() on the instance exportAs gives it; the family never does it, because moving focus unprompted is a change of context nobody asked for. A tabindex the page wrote is read with HostAttributeToken and kept.
+- The family holds no mutable value, so it has no model(), no output() and no ControlValueAccessor. Which status a region is in is a fact about the consumer’s own data — a region that decided it would be deciding whether the fetch failed.
+- A region that announces arrives: its words fade in and its drawing assembles, on the entering curve, and a hidden region fades out on the leaving curve. Under reduced motion the drawing arrives assembled. The focus indicator is not animated, because a focus indicator that fades in is one that is not there yet.
+
+## Tokens
+
+`--slotted-border-strong`, `--slotted-border-subtle`, `--slotted-border-width-thin`, `--slotted-control-height-lg`, `--slotted-control-height-md`, `--slotted-control-height-sm`, `--slotted-control-icon-size-lg`, `--slotted-control-icon-size-md`, `--slotted-duration-long`, `--slotted-duration-medium`, `--slotted-duration-short`, `--slotted-easing-enter`, `--slotted-easing-exit`, `--slotted-focus-ring-color`, `--slotted-focus-ring-offset`, `--slotted-focus-ring-width`, `--slotted-font-family-heading`, `--slotted-font-family-sans`, `--slotted-font-size-3xl`, `--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-3xl`, `--slotted-line-height-md`, `--slotted-line-height-sm`, `--slotted-line-height-xl`, `--slotted-radius-lg`, `--slotted-radius-sm`, `--slotted-result-state-actions-block-gap`, `--slotted-result-state-actions-gap`, `--slotted-result-state-column-gap`, `--slotted-result-state-description-font-size`, `--slotted-result-state-font-family`, `--slotted-result-state-media`, `--slotted-result-state-media-size`, `--slotted-result-state-padding-block`, `--slotted-result-state-padding-inline`, `--slotted-result-state-row-gap`, `--slotted-result-state-text-gap`, `--slotted-result-state-title-font-family`, `--slotted-result-state-title-font-size`, `--slotted-result-state-title-font-weight`, `--slotted-result-state-title-letter-spacing`, `--slotted-shadow-sm`, `--slotted-shadow-xs`, `--slotted-space-11`, `--slotted-space-12`, `--slotted-space-2`, `--slotted-space-3`, `--slotted-space-4`, `--slotted-space-5`, `--slotted-space-6`, `--slotted-space-8`, `--slotted-space-9`, `--slotted-surface-raised`, `--slotted-surface-sunken`, `--slotted-text`, `--slotted-text-muted`
+
+## Examples
+
+### What the region is reporting
+
+Seven semantics, seven silhouettes. Read in greyscale, or under forced colours where every ground becomes one system colour, the shape is the only thing left telling an absent collection from a failed request.
+
+Excerpt — not a complete module
+
+```html
+<!-- empty: the collection exists and holds nothing. -->
+<!-- no-results: a query or a filter matched nothing. -->
+<!-- not-found: the thing that was asked for is not here. -->
+<!-- error: a failure the reader can act on. -->
+<!-- forbidden: the reader is not allowed to see it. -->
+<!-- offline: the connection is gone. -->
+<!-- success: the flow finished and there is nothing left to do. -->
+<section slResultState status="no-results"></section>
+```
+
+### How far the region reaches
+
+A row inside a table cell, a panel inside a card, the whole route — the same three words alert uses. The mark is the title’s own size at every reach and stands over the title at section and page; at inline it sits on the message’s first line and the actions join it, and at page the title takes the top step of the type scale.
+
+Excerpt — not a complete module
+
+```html
+<section slResultState reach="inline" status="no-results">
+  <div slResultStateContent>
+    <div slResultStateTitle>Nenhuma linha corresponde ao filtro</div>
+  </div>
+  <div slResultStateActions>
+    <button slButton size="sm" variant="ghost" type="button">Limpar filtros</button>
+  </div>
+</section>
+
+<section slResultState reach="page" status="not-found"></section>
+```
+
+### Centred, or from the inline edge
+
+Carbon left-aligns its empty states inside data-dense views and the other six surveyed implementations centre unconditionally. Both readings are real, and align is one axis rather than a second family.
+
+Excerpt — not a complete module
+
+```html
+<!-- The default, for a panel or a route. -->
+<section slResultState align="center"></section>
+
+<!-- For a data-dense screen, where a centred column reads as an interruption. -->
+<section slResultState align="start" reach="inline"></section>
+```
+
+### The page’s own illustration
+
+The box is sized before anything is in it, so an illustration that has not loaded reserves the space it will occupy and the title below it never moves. Atlassian spends four props on that and Polaris a skeleton with an effect.
+
+Excerpt — not a complete module
+
+```html
+<!-- A title, a description and an action: the family draws no picture. -->
+<section slResultState status="offline"></section>
+
+<!-- The page draws its own, in the box the family keeps. -->
+<section slResultState>
+  <img slResultStateMedia alt="" src="/illustrations/boards.svg" />
+</section>
+
+<!-- Or named in CSS, for a page that skins its states in the theme:
+     [data-ui="result-state"][data-status="offline"] > [data-part="media"] {
+       display: block;
+       --slotted-result-state-media: url("/illustrations/offline.svg");
+     } -->
+```
+
+### A drawing around the page’s glyph
+
+Three drawings in the neutral surface and border roles — a framed tile, three layers leaning back, a stack of cards — made around the projected glyph. None takes a tone, and inline reach draws none. A region that announces assembles its drawing as it arrives; under reduced motion it arrives assembled.
+
+Excerpt — not a complete module
+
+```html
+<section slResultState illustration="stack">
+  <span slIcon slResultStateMedia><svg slGlyph name="bell"></svg></span>
+  <div slResultStateContent>
+    <div slResultStateTitle>Nenhum alerta configurado</div>
+  </div>
+</section>
+
+<!-- A framed tile, and a stack of cards standing in for rows. -->
+<section slResultState illustration="tile">
+  <span slIcon slResultStateMedia><svg slGlyph name="inbox"></svg></span>
+</section>
+<section slResultState illustration="cards">
+  <span slIcon slResultStateMedia><svg slGlyph name="file-text"></svg></span>
+</section>
+
+<!-- The cards draw their two lines with no glyph at all. -->
+<section slResultState illustration="cards"></section>
+```
+
+### The way out of the situation
+
+The controls are the consumer’s own buttons in a part outside the live region — a reader hearing the message is not read two button labels in the middle of it. Narrow the window past 20rem and watch them stack.
+
+Excerpt — not a complete module
+
+```html
+<section slResultState status="error">
+  <div slResultStateContent>
+    <div slResultStateTitle>A execução falhou</div>
+  </div>
+  <div slResultStateActions>
+    <button slButton tone="danger" [loading]="retrying()" type="button">Tentar de novo</button>
+    <button slButton variant="outline" type="button">Abrir registro</button>
+  </div>
+  <div slResultStateFooter>
+    <a slLink href="/docs/retries">Como as tentativas são contadas</a>
+  </div>
+</section>
+```
+
+### What a reader hears, and when
+
+polite by default, which is where this family and alert disagree: WCAG 2.2 SC 4.1.3 names “No results returned” as its own example of a status message. Press the button and the region arrives while the reader is elsewhere.
+
+Excerpt — not a complete module
+
+```html
+<!-- The default. role="status" on the text, which implies aria-live and
+     aria-atomic; the buttons beside it are outside the region. -->
+<section slResultState live="polite" status="no-results"></section>
+
+<!-- role="alert", for a failure the reader has to hear now. -->
+<section slResultState live="assertive" status="error"></section>
+
+<!-- Off, when the page already owns a live region around this one. -->
+<section slResultState live="off"></section>
+```
+
+### Content the family did not choose
+
+A German compound with no break opportunity, a digest no language can break, a title standing alone and a region with no mark — all in a column narrow enough to make each of them a problem.
+
+Excerpt — not a complete module
+
+```html
+<section slResultState status="error">
+  <div slResultStateContent>
+    <div slResultStateTitle>{{ longTranslatedTitle }}</div>
+    <p slResultStateDescription>A execução {{ digest }} falhou.</p>
+  </div>
+</section>
+```
+
+### Composition and escape hatches
+
+Measure belongs to container and the frame to card, so the region caps nothing and draws no box: these two elements are what a consumer writes instead. provideResultStateDefaults sets the axes once for a whole application.
+
+Excerpt — not a complete module
+
+```ts
+bootstrapApplication(App, {
+  providers: [provideResultStateDefaults({ align: 'start', reach: 'inline' })],
+});
+
+// In a template: the measure, the frame, and a title that is a heading.
+// <div slContainer size="measure">
+//   <section slResultState reach="page">
+//     <div slResultStateContent><h2 slResultStateTitle>…</h2></div>
+//   </section>
+// </div>
+```
+
+### The landmark, the region and the keyboard
+
+Tab past the region and then send the keyboard into it: the box is a landmark a reader can jump to, the text is the only thing that announces, and nothing moves focus unless the application asks.
+
+Excerpt — not a complete module
+
+```html
+<!-- A region landmark named "Nada corresponde ao filtro", holding a polite
+     status region. The button is outside it. -->
+<section slResultState #region="slResultState" live="polite">
+  <div slResultStateContent>
+    <div slResultStateTitle>Nada corresponde ao filtro</div>
+  </div>
+  <div slResultStateActions>
+    <button slButton type="button">Limpar filtros</button>
+  </div>
+</section>
+
+<!-- The application decides when the keyboard goes there. The family never does. -->
+<button (click)="region.focus()" type="button">Ir para a mensagem</button>
+```