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

package/docs/toast.md

@@ -0,0 +1,311 @@
+<!-- index: ./index.md -->
+# toast
+
+`data-ui="toast"` · Temporary notification with optional action.
+
+## Import
+
+```ts
+import {
+  provideToastDefaults,
+  SlToastActions,
+  SlToastContent,
+  SlToastDescription,
+  SlToastItem,
+  SlToastRegion,
+  SlToastService,
+  SlToastTitle,
+} from '@slotted/angular/toast';
+```
+
+Selector: `sl-toast-region` · exportAs: `slToastRegion`
+
+## Minimal example
+
+Example
+
+```ts
+import { Component, inject } from '@angular/core';
+import { SlButton } from '@slotted/angular/button';
+import { SlToastRegion, SlToastService } from '@slotted/angular/toast';
+
+@Component({
+  selector: 'app-toast-basic',
+  imports: [SlButton, SlToastRegion],
+  template: `
+    <!-- Once, near the root of the application. -->
+    <sl-toast-region />
+    <button slButton type="button" (click)="save()">Save draft</button>
+  `,
+})
+export class ToastBasic {
+  private readonly toasts = inject(SlToastService);
+
+  save(): void {
+    this.toasts.show({ title: 'Draft saved', description: 'Everything since 2:02 PM is saved.' });
+  }
+}
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | section | yes |
+| `list` | ol | yes |
+| `item` | li | no |
+| `icon` | span | no |
+| `content` | div | no |
+| `title` | div, or the element slToastTitle is written on | no |
+| `description` | p, or the element slToastDescription is written on | no |
+| `actions` | div | no |
+| `close` | button | no |
+| `progress` | div | no |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `placement` | `'top-start' \| 'top' \| 'top-end' \| 'bottom-start' \| 'bottom' \| 'bottom-end'` | bottom-end | sl-toast-region | Which edge the region sits at, named logically so a right-to-left document mirrors it |
+| `attach` | `'portal' \| 'viewport' \| 'inline'` | portal | sl-toast-region | Where the region is rendered: at the end of the document carrying the theme it came from, fixed where it was written, or absolute against the nearest positioned ancestor |
+| `stacking` | `'list' \| 'stack'` | list | sl-toast-region | A column of messages at their own height, or a pile that opens when the pointer is over it or the keyboard inside it |
+| `limit` | `number` | 3 | sl-toast-region | How many messages are on screen at once. What arrives past it waits, and what is already there stays |
+| `duration` | `number` | 5000 | sl-toast-region, show() | Milliseconds on screen, counted from the moment a message becomes visible. 0 never expires |
+| `swipe` | `boolean` | true | sl-toast-region | Lets a message be dragged toward the edge the placement names. A drag that starts on a control never becomes a swipe |
+| `pauseOnHover` | `boolean` | true | sl-toast-region | The pointer over the region holds every clock. Focus inside it holds them too, and that one is not an axis: switching it off would expire the message under the keyboard using it |
+| `pauseWhenHidden` | `boolean` | true | sl-toast-region | A hidden tab holds every clock. A five-second message shown to a tab nobody is looking at was never shown |
+| `hotkey` | `string` | F6 | sl-toast-region | The key that moves focus into the region, written the way a reader says it — F6, Alt+T, Shift+F8 |
+| `messages` | `Partial<ToastMessages>` | — | sl-toast-region | Words laid over the language in force, key by key: the name a reader finds the region by in their landmark list, and what the hotkey lands in (label), and what each close control announces (close) |
+| `tone` | `'accent' \| 'secondary' \| 'success' \| 'warning' \| 'danger'` | accent | SlToastService.show | Which of the five semantic colours the message speaks in, and which mark it draws |
+| `variant` | `'raised' \| 'soft' \| 'solid'` | raised | SlToastService.show | How that colour is painted. raised keeps the neutral surface and puts the tone in the mark, which is what a box floating over unknown content should do |
+| `priority` | `'polite' \| 'assertive'` | polite | SlToastService.show | How loudly the announcer says it. Never inferred from the tone: a danger message a background job produced must not cut into a sentence |
+| `dismissible` | `boolean` | true | SlToastService.show | Renders the control that closes the message. A touch reader has no Escape key, so the pointer needs a target |
+| `progress` | `boolean` | false | SlToastService.show | Draws how much of the duration is left. It is off by default because a message with no duration has nothing to draw |
+| `toasts` | `readonly ToastMessage[]` | — | sl-toast-region | The queue the page owns. Passing it puts the region in controlled mode for good, and the family then only asks |
+| `defaultToasts` | `readonly ToastMessage[]` | — | sl-toast-region | The queue an uncontrolled region starts from, read once. A later change to it is not silently adopted |
+| `title` | `string` | — | SlToastService.show | The message’s name. A string here is also what the announcer says, unless announcement states otherwise |
+| `description` | `string` | — | SlToastService.show | The message. Joined to the title for the announcement when both are strings |
+| `announcement` | `string` | — | SlToastService.show | What a reader hears. State it when the body is a component of the page’s own: a rendered node cannot be read from the store, so a message that says nothing here is shown and not spoken |
+| `loading` | `boolean` | false | SlToastService.show | Waiting on a promise. It draws no countdown and is given no duration, and the mark slot holds whatever the page put there |
+| `body` | `TemplateRef<{ $implicit: ToastMessage }>` | — | SlToastService.show | Replaces the message’s whole body, keeping the box, the tone, the clock and the keyboard. Rendered through NgTemplateOutlet, so it is lazy and the message is in its context |
+| `hideIcon` | `boolean` | false | SlToastService.show | Draws no mark at all. The words then start at the box’s own inset rather than one gap further in |
+| `actions` | `TemplateRef<{ $implicit: ToastMessage }>` | — | SlToastService.show | The page’s own controls, under the words. A message that has them is given no duration unless one is stated |
+| `id` | `string` | — | SlToastService.show | Showing a message whose id is already in the queue updates that message in place rather than adding a second one |
+| `container` | `Element \| null` | — | sl-toast-region | The element a portalled region is placed inside, for an application shell that owns its own stacking context |
+| `body` | `ng-template` | — | SlToastService.show | The message a page draws itself. The clock, the exit, the swipe, the keyboard and the announcement stay the family’s; NgTemplateOutlet renders the template per message and only when the message exists |
+| `slToastItem` | `directive on an li` | — | a page’s own list | Everything about a message that is behaviour rather than markup. A page that renders SlToastService.visible() itself puts this on its own li and keeps the timer, the exit, the swipe and Escape |
+| `SlToastService` | `providedIn: root` | — | anywhere | show, update, dismiss, clear, pauseAll, resumeAll and promise, plus visible, queued and paused as signals. It is where Angular Material’s consumers already reach, and it is injectable from an interceptor or a resolver |
+| `provideToastDefaults` | `(defaults) => Provider` | — | an application or a route | Sets every axis once for every region and message under it; an explicit value on one message still wins. A component-level provider gives one subtree a queue of its own |
+| `exportAs` | `'slToastRegion'` | — | a template | Reaches the region instance: visible(), queued(), paused() and focus(), which sends the keyboard to the newest message |
+| `slToastTitle, slToastDescription, slToastActions, slToastClose, slToastIcon, slToastProgress` | `directives` | — | a page’s own body | The part names, and nothing else. The geometry, the tone and the states belong to the item and the region, so a directive that repeated any of them would be a second place to change them |
+
+## Events
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `onToastsChange` | `(toasts, request)` | Asks to change the queue. The first argument is the queue as it will be; the request carries the value it replaces, the reason — programmatic, dismiss, escape, keyboard, pointer, timeout or clear — the originating event, and cancel(). Calling cancel() refuses the change and nothing moves. |
+| `onStatusChange` | `(status, message)` | Per message, passed to the call that showed it. Reports visible when it reaches the screen, closing when it has left the queue and is still leaving the document, and removed once it is gone. |
+
+## Axes and defaults
+
+| Axis | Values | Default |
+| --- | --- | --- |
+| `placement` | `top-start`, `top`, `top-end`, `bottom-start`, `bottom`, `bottom-end` | `bottom-end` |
+| `attach` | `portal`, `viewport`, `inline` | `portal` |
+| `stacking` | `list`, `stack` | `list` |
+| `tone` | `accent`, `secondary`, `success`, `warning`, `danger` | `accent` |
+| `variant` | `raised`, `soft`, `solid` | `raised` |
+| `priority` | `polite`, `assertive` | `polite` |
+| `dismissible` | `true`, `false` | `true` |
+| `swipe` | `true`, `false` | `true` |
+| `progress` | `true`, `false` | `false` |
+| `pauseOnHover` | `true`, `false` | `true` |
+| `pauseWhenHidden` | `true`, `false` | `true` |
+
+## Rules
+
+- There is no toast pattern in the WAI-ARIA Authoring Practices. The closest official guidance is the Alert Pattern (w3.org/WAI/ARIA/apg/patterns/alert/), and this family departs from it twice, both times on purpose. The visible message carries no live role, and the family binds keys the pattern says it should not — because the pattern’s table is empty for a message that holds no controls, and every toast worth shipping holds at least a Close.
+- The region is a landmark and the announcement is made elsewhere. A live role on a box holding a Close and an Undo is read with both buttons inside the sentence, and a live region created in the same task as its text is silent under ARIA 1.2 §6.4 — which is exactly what a message that has just been added is. packages/core/src/live-announcer builds its regions before any message exists, deduplicates, and spaces two announcements so the second is not lost.
+- A message that renders content of its own announces the string passed as announcement, and nothing at all when none is passed. A rendered node cannot be read out of the store, and guessing at it would announce markup.
+- The pattern’s one prose rule is kept without exception: a message arriving never moves focus. The reader moves it, with F6, and Shift+F6 is their browser’s own landmark navigation. Escape closes the message the keyboard is inside and hands it back to where it came from.
+- When the message holding focus is taken away — by its own control, or by the page’s state — focus goes to the next message, then to the element it came from. Only React Aria answers this at all, and only for its own close button; here it is `packages/core/src/focus/removal-focus`, which both bindings compose.
+- WCAG 2.2 SC 2.2.1 is the criterion a timer answers, and the family takes the first of the criterion’s six ways out: the limit can be turned off before a reader meets it, by setting duration to 0 on ToastDefaultsProvider for the whole application. Putting that switch in front of the reader is the application’s work, not the family’s.
+- A message that carries an action is given no duration unless one is stated, and a message waiting on a promise is given none either. Angular Material states the first rule and is alone in it; five surveyed implementations ship the action and the timer and leave the combination to the consumer.
+- Every tone with a severity carries a mark as well as a colour, and secondary carries none: a neutral note has no severity to state. Under forced colours the five grounds become one system colour, so the mark, and its absence on a note, is the only thing distinguishing a failure from a note — WCAG 2.2 1.4.1.
+- The region takes no pointer events and each message takes its own, so a region pinned over a page never eats a press meant for the page. Every surveyed implementation does this and none of them says so, which is how a consumer finds a dead corner in their own application.
+
+## Tokens
+
+`--slotted-border-subtle`, `--slotted-border-width-thin`, `--slotted-control-font-family`, `--slotted-control-font-size-md`, `--slotted-control-icon-size-md`, `--slotted-control-inner-size-md`, `--slotted-control-radius`, `--slotted-control-transition-duration`, `--slotted-control-transition-easing`, `--slotted-duration-long`, `--slotted-duration-medium`, `--slotted-duration-short`, `--slotted-easing-enter`, `--slotted-easing-exit`, `--slotted-easing-standard`, `--slotted-focus-ring-color`, `--slotted-focus-ring-offset`, `--slotted-focus-ring-width`, `--slotted-font-family-heading`, `--slotted-font-family-sans`, `--slotted-font-weight-semibold`, `--slotted-line-height-md`, `--slotted-radius-lg`, `--slotted-shadow-md`, `--slotted-space-1`, `--slotted-space-2`, `--slotted-space-3`, `--slotted-space-4`, `--slotted-space-5`, `--slotted-space-6`, `--slotted-space-7`, `--slotted-surface-raised`, `--slotted-target-comfortable`, `--slotted-target-min`, `--slotted-text`, `--slotted-text-muted`, `--slotted-toast-actions-gap`, `--slotted-toast-border-color`, `--slotted-toast-border-width`, `--slotted-toast-close-radius`, `--slotted-toast-close-size`, `--slotted-toast-column-gap`, `--slotted-toast-font-family`, `--slotted-toast-gap`, `--slotted-toast-measure`, `--slotted-toast-offset`, `--slotted-toast-padding-block`, `--slotted-toast-padding-inline`, `--slotted-toast-progress-size`, `--slotted-toast-radius`, `--slotted-toast-row-gap`, `--slotted-toast-shadow`, `--slotted-toast-stack-fade`, `--slotted-toast-stack-step`, `--slotted-toast-state-layer-active`, `--slotted-toast-state-layer-hover`, `--slotted-toast-surface`, `--slotted-toast-text`, `--slotted-toast-text-gap`, `--slotted-toast-text-muted`, `--slotted-toast-title-font-family`, `--slotted-toast-title-font-weight`, `--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-danger-on-solid`, `--slotted-tone-danger-solid`, `--slotted-tone-danger-surface`, `--slotted-tone-danger-text`, `--slotted-tone-secondary-border`, `--slotted-tone-secondary-on-solid`, `--slotted-tone-secondary-solid`, `--slotted-tone-secondary-surface`, `--slotted-tone-secondary-text`, `--slotted-tone-success-border`, `--slotted-tone-success-on-solid`, `--slotted-tone-success-solid`, `--slotted-tone-success-surface`, `--slotted-tone-success-text`, `--slotted-tone-warning-border`, `--slotted-tone-warning-on-solid`, `--slotted-tone-warning-solid`, `--slotted-tone-warning-surface`, `--slotted-tone-warning-text`, `--slotted-z-index-toast`
+
+## Examples
+
+### Playground
+
+One region with every axis on it, driven by the controls below the canvas. The messages here are given no duration so the page has something to show; an application states one, or lets the default of five seconds stand.
+
+Excerpt — not a complete module
+
+```ts
+// The region once, near the root: <sl-toast-region />
+// The service from anywhere — a component, an interceptor, a resolver.
+const toasts = inject(SlToastService);
+
+toasts.show({
+  title: 'Draft saved',
+  description: 'Everything since 2:02 PM is saved.',
+});
+```
+
+### What the message is about
+
+Five tones and five marks. The mark is the answer to WCAG 2.2 1.4.1: read in greyscale, or under forced colours where every ground becomes one system colour, the silhouette is the only thing left to tell a failure from a note.
+
+Excerpt — not a complete module
+
+```ts
+// accent is information, secondary a neutral note, success something
+// finished, warning something that needs attention, danger something failed.
+this.toasts.show({ title: 'Could not send', tone: 'danger' });
+```
+
+### How that tone is painted
+
+raised is the default and the one the other message families do not have: a toast floats over content this family does not own, so the tone is in the mark and the box keeps the neutral raised surface. soft and solid are for a region inside a page’s own chrome.
+
+Excerpt — not a complete module
+
+```ts
+this.toasts.show({ title: 'Invoice sent', tone: 'success', variant: 'raised' });
+this.toasts.show({ title: 'Invoice sent', tone: 'success', variant: 'soft' });
+this.toasts.show({ title: 'Sending failed', tone: 'danger', variant: 'solid' });
+```
+
+### Which corner the region owns
+
+Six placements, all written in logical properties: bottom-end is the bottom right of this page and the bottom left of the same page in Arabic. Switch the direction in the toolbar and the region moves with the text.
+
+Excerpt — not a complete module
+
+```html
+<sl-toast-region placement="top-end" />
+```
+
+### How long a message stays
+
+The bar reads the same number the timer does. Hover the region and both stop together — the clock also stops while focus is inside it and while the tab is hidden, and it resumes on what was left rather than starting again.
+
+Excerpt — not a complete module
+
+```ts
+this.toasts.show({ title: 'Exported', duration: 8000, progress: true });
+
+// 0 never expires. A message that must be answered rather than read is one
+// of the two cases the family gives no duration to on its own.
+this.toasts.show({ title: 'Session expired', tone: 'danger', duration: 0 });
+```
+
+### A message the reader can act on
+
+A message that carries an action is given no duration unless one is stated: Angular Material is the only surveyed implementation that states the rule, and a reader on their way to Undo must not watch it disappear. Press Undo and the message closes with it.
+
+Excerpt — not a complete module
+
+```html
+<!-- The controls are a template, rendered per message, with the message
+     in its context. It is what makes the toast wait: a message that carries
+     one is given no duration unless the call states one. -->
+<ng-template #undo let-message>
+  <button slButton size="sm" (click)="restore(message.id)">Undo</button>
+</ng-template>
+```
+
+### A message that follows a promise
+
+One message from start to finish: it begins as loading with no duration and no countdown, and the same element becomes the success or the failure. Replacing it with a second message would make a reader hear the sentence twice.
+
+Excerpt — not a complete module
+
+```ts
+this.toasts.promise(this.publish(), {
+  loading: { title: 'Publishing' },
+  success: (version) => ({ title: `Version ${version} is live`, tone: 'success' }),
+  error: { title: 'Publishing failed', tone: 'danger' },
+});
+```
+
+### More messages than the screen
+
+Past the limit a message waits, and what is already on screen stays — a reader half way through one does not lose it to something that arrived after. A waiting message has no clock at all: its duration starts when it appears.
+
+Excerpt — not a complete module
+
+```html
+<sl-toast-region [limit]="2" />
+```
+
+### A pile that opens
+
+Four messages at full height fill a phone. stack puts them one behind another at the edge the placement names and opens the pile when the pointer is over it or the keyboard is inside — the same two conditions that stop the clock, because both mean the reader is reading.
+
+Excerpt — not a complete module
+
+```html
+<sl-toast-region stacking="stack" />
+```
+
+### The ways a message leaves
+
+Four, and each carries its own reason: the close control says dismiss, Escape inside the message says escape, a swipe toward the edge says pointer, and the timer says timeout. A page that has to tell them apart reads the reason rather than guessing.
+
+Excerpt — not a complete module
+
+```html
+<sl-toast-region (toastsChange)="onToastsChange($event)" />
+
+<!-- onToastsChange(request: ChangeRequest<readonly ToastMessage[]>) {
+       if (request.reason === 'timeout') return;
+       this.remember(request.reason);
+     } -->
+```
+
+### Reaching the messages from the keyboard
+
+A message arriving never moves focus — the APG’s Alert pattern is explicit about it. F6 is what the reader presses to get there, Tab walks the controls, and Escape closes the message and hands the keyboard back to where it came from.
+
+Excerpt — not a complete module
+
+```html
+<sl-toast-region hotkey="Alt+T" />
+```
+
+### Content the family did not choose
+
+A digest no language can break, a title that doubled in translation, and a message with no mark at all. Nothing is removed from the document to make any of them fit: the whole string stays selectable and findable by a page search.
+
+Excerpt — not a complete module
+
+```ts
+this.toasts.show({
+  title: 'Deployment rejected',
+  description: digest,
+  tone: 'danger',
+  duration: 0,
+});
+```
+
+### A message a page draws itself
+
+The region hands each message to a function and keeps everything that is behaviour: the clock, the exit, the swipe, the keyboard and the announcement. What the page writes is the body, and it can be anything at all.
+
+Excerpt — not a complete module
+
+```html
+<!-- The body is an ng-template carried by the message, rendered per
+     message and lazily, with the message in its context. -->
+<ng-template #body let-message>
+  <div slToastContent>
+    <div slToastTitle>{{ message.data.title }}</div>
+  </div>
+</ng-template>
+```