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

package/dist/docs/toast.md

@@ -0,0 +1,308 @@
+<!-- index: ./index.md -->
+# toast
+
+`data-ui="toast"` · Temporary notification with optional action.
+
+## Import
+
+```tsx
+import {
+  Toast,
+  ToastActions,
+  ToastClose,
+  ToastContent,
+  ToastDefaultsProvider,
+  ToastDescription,
+  ToastRegion,
+  ToastTitle,
+  toast,
+} from '@slotted/react';
+```
+
+## Minimal example
+
+Example
+
+```tsx
+import { Button } from '@slotted/react/button';
+import { toast, ToastRegion } from '@slotted/react/toast';
+
+export default function ToastBasic() {
+  return (
+    <>
+      {/* Once, near the root of the application. */}
+      <ToastRegion />
+      <Button
+        onClick={() =>
+          toast.show({ title: 'Draft saved', description: 'Everything since 2:02 PM is saved.' })
+        }
+      >
+        Save draft
+      </Button>
+    </>
+  );
+}
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | section | yes |
+| `list` | ol | yes |
+| `item` | li | no |
+| `icon` | span | no |
+| `content` | div | no |
+| `title` | div, or the element render returns | no |
+| `description` | p, or the element render returns | 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 | ToastRegion | Which edge the region sits at, named logically so a right-to-left document mirrors it |
+| `attach` | `'portal' \| 'viewport' \| 'inline'` | portal | ToastRegion | 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 | ToastRegion | 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 | ToastRegion | How many messages are on screen at once. What arrives past it waits, and what is already there stays |
+| `duration` | `number` | 5000 | ToastRegion, toast.show | Milliseconds on screen, counted from the moment a message becomes visible. 0 never expires |
+| `swipe` | `boolean` | true | ToastRegion | 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 | ToastRegion | 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 | ToastRegion | A hidden tab holds every clock. A five-second message shown to a tab nobody is looking at was never shown |
+| `hotkey` | `string` | F6 | ToastRegion | The key that moves focus into the region, written the way a reader says it — F6, Alt+T, Shift+F8 |
+| `messages` | `Partial<ToastMessages>` | — | ToastRegion | 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 | toast.show | Which of the five semantic colours the message speaks in, and which mark it draws |
+| `variant` | `'raised' \| 'soft' \| 'solid'` | raised | toast.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 | toast.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 | toast.show | Renders the control that closes the message. A touch reader has no Escape key, so the pointer needs a target |
+| `progress` | `boolean` | false | toast.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[]` | — | ToastRegion | The queue the page owns. Passing it puts the region in controlled mode for good, and the family then only asks |
+| `defaultToasts` | `readonly ToastMessage[]` | — | ToastRegion | The queue an uncontrolled region starts from, read once. A later change to it is not silently adopted |
+| `title` | `ReactNode` | — | toast.show | The message’s name. A string here is also what the announcer says, unless announcement states otherwise |
+| `description` | `ReactNode` | — | toast.show | The message. Joined to the title for the announcement when both are strings |
+| `announcement` | `string` | — | toast.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 | toast.show | Waiting on a promise. It draws no countdown and is given no duration, and the mark slot holds whatever the page put there |
+| `icon` | `ReactNode` | — | toast.show | Replaces the tone’s mark, keeping its box and its place on the message’s first line. Angular projects a template instead |
+| `hideIcon` | `boolean` | false | toast.show | Draws no mark at all. The words then start at the box’s own inset rather than one gap further in |
+| `actions` | `ReactNode` | — | toast.show | The page’s own controls, under the words. A message that has them is given no duration unless one is stated |
+| `id` | `string` | — | toast.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` | — | ToastRegion | The element a portalled region is placed inside, for an application shell that owns its own stacking context |
+| `children` | `(message) => ReactNode` | — | ToastRegion | Renders each message itself. The clock, the exit, the swipe, the keyboard and the announcement are still the family’s; what the page writes is the body |
+| `render` | `(props) => ReactNode` | — | ToastContent, ToastTitle, ToastDescription, ToastActions, ToastClose | Substitutes the rendered element of a part and hands it every data attribute |
+| `toast` | `Toaster` | — | anywhere | The shared imperative facade: show, update, dismiss, clear, pauseAll, resumeAll and promise. It is a plain object rather than a hook, because a message is shown from an interceptor or a saga that is nowhere near a component |
+| `createToaster` | `() => Toaster` | — | an application | A queue of its own, for a shell that needs two regions — a global one and one for a canvas. ToasterProvider says which region renders it |
+| `ToastDefaultsProvider` | `{ placement, attach, stacking, tone, variant, limit, duration, hotkey, … }` | — | a subtree | Sets every axis once for every region and every message under it; an explicit value on one message still wins |
+| `useToastQueue` | `() => { visible, queued, paused }` | — | inside a region | How many messages are on screen, how many are waiting and whether the clocks are held, for a page that wants to say so |
+
+## 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.
+- 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
+
+```tsx
+// Once, near the root of the application.
+<ToastRegion />;
+
+// From anywhere at all — an event handler, an interceptor, a saga.
+toast.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
+
+```tsx
+// accent is information, secondary a neutral note, success something
+// finished, warning something that needs attention, danger something failed.
+toast.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
+
+```tsx
+toast.show({ title: 'Invoice sent', tone: 'success', variant: 'raised' });
+toast.show({ title: 'Invoice sent', tone: 'success', variant: 'soft' });
+toast.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
+
+```tsx
+<ToastRegion 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
+
+```tsx
+toast.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.
+toast.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
+
+```tsx
+const id = toast.show({
+  title: 'Message archived',
+  actions: <Button onClick={() => restore(id)}>Undo</Button>,
+});
+```
+
+### 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
+
+```tsx
+toast.promise(publish(), {
+  loading: { title: 'Publishing', icon: <Spinner size="sm" /> },
+  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
+
+```tsx
+<ToastRegion 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
+
+```tsx
+<ToastRegion 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
+
+```tsx
+<ToastRegion
+  onToastsChange={(toasts, request) => {
+    if (request.reason === 'timeout') return;
+    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
+
+```tsx
+<ToastRegion 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
+
+```tsx
+toast.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
+
+```tsx
+<ToastRegion>
+  {(message) => (
+    <Toast key={message.id} message={message}>
+      <ToastContent>
+        <ToastTitle>{message.data.title}</ToastTitle>
+      </ToastContent>
+    </Toast>
+  )}
+</ToastRegion>;
+```