The page's one status region for action results and warnings, never taking focus.
<p>A line above the form that says what the action answered: an error in an alert box, a success in a status box, and nothing visible while there is nothing to say. After each answer with words, focus moves to it. An answer with no sentence (a move that has nothing to report) neither shows nor focuses.</p>
<div data-mount="action"></div>
import { enhance, say, fail } from "capsomer/behavior/message";
enhance();
say("Moved the mention from fieldnotes.example to Trash.", {
undo: () => restore(mention),
undone: "The mention from fieldnotes.example is waiting again.",
returnFocus: binButton,
});
say("Seat start is on.", { undo: () => api.undoSeat(), warning: result.warning });
say("Copied the link to the mention.", { clears: true });
fail("Refresh failed: the watcher pass failed: GitHub answered 502.");
Examples
An error beside its source is not a message
<p>Something that failed, with a control it belongs beside, goes beside that control as an alert, or at the top of the page as a banner that keeps the last good data. See <a href="../banner/states.html">Banner and alert</a>. Only a failure with no place of its own (a failed copy, a failed refresh) goes in this region.</p>
Empty: the region is present and shows nothing
<main>
<div class="specimen-page">
<h1>Mentions</h1>
<p>4 waiting. Nothing has happened yet, so the region below is empty.</p>
</div>
<div class="message-sample">
<div class="cap-message" data-cap="message" role="status" aria-label="Results and failures" aria-atomic="false"></div>
</div>
</main>
A plain message
<main>
<div class="specimen-page">
<h1>Publish</h1>
<p>Ready. Uses the short summary.</p>
</div>
<div class="message-sample">
<div class="cap-message" data-cap="message" role="status" aria-label="Results and failures" aria-atomic="false"></div>
</div>
</main>
<main>
<div class="specimen-page">
<h1>Mentions</h1>
<p>Move a mention to Trash, then press z or Undo. Copy the link to see a message that clears itself.</p>
</div>
<div class="message-sample">
<div class="message-sample-row" id="sample-row" data-undos="0">
<b>fieldnotes.example</b>
<span id="sample-state">Waiting</span>
<button type="button" class="cap-btn" id="sample-bin">Move to Trash</button>
<button type="button" class="cap-btn" id="sample-bin-warned">Move to Trash, audit row missing</button>
<button type="button" class="cap-btn" id="sample-copy">Copy link</button>
<button type="button" class="cap-btn" id="sample-refresh">Refresh, fails</button>
</div>
<label>Note to self <input class="cap-input" id="sample-note" type="text" /></label>
<div class="cap-message" data-cap="message" role="status" aria-label="Results and failures" aria-atomic="false"></div>
</div>
</main>
API reference
MessageProvider
Prop
Type
Required
Does
children
ReactNode
Yes
region
boolean
Renders the region after the children. Pass false and place <MessageRegion /> where the page's results should show.
undoKey
boolean
z runs the current Undo. False when the app's single-key shortcuts are switched off.
MessageRegion
Functions
Function
Signature
Does
useMessage
(): MessageApi
useOptionalMessage
(): MessageApi | null
The same API, or null when no <MessageProvider> is above: for a component that says its results in the page's region when there is one and works without it (a form that posts).
An Undo that threw: nothing was undone, so Undo stays and this says why.
resolveFocus
(f: ReturnFocus | undefined): HTMLElement | null
isUndoKey
(e: KeyboardEvent): boolean
z alone: no Ctrl, Alt, Meta or Shift, not a held repeat, not typed into a field.
currentUndo
(all: Message[]): Message | undefined
The message z would undo: the newest one with an Undo that is not already running.
glyphSvg
(inner: string, size?: number): SVGSVGElement
A 16-unit glyph from one of the drawings above (or any inner SVG), hidden from assistive tech: the word beside it says what it means. The moderation queue and the history list draw theirs with it.
What a message is, for its glyph and its edge: a failure; a warning or an Undo that failed; otherwise a plain result.
say
(text: string, opts?: SayOptions): void
Says a message in the page's region. Does not move focus. A plain result replaces the plain result before it; a warning, a failure and a failed Undo stay.
fail
(text: string): void
Says that something did not happen. Stays until dismissed.
dismiss
(): void
Clears the page's region, lasting messages too.
runUndo
(): Promise<boolean>
Runs the current Undo, once. Returns false when there is nothing to undo.
ensureRegion
(after: Element): void
The page's status region for results and Undo is one; a component that needs it where the page has none yet places one after after.
enhance
(root?: ParentNode): () => void
Attaches to every [data-cap="message"] under root not yet attached: the region is empty and takes the messages said into it, each with its own Undo and Dismiss, and z on the document. z is off while single-key shortcuts are (the shortcuts switch), or for one region with data-cap-undo-key="off". Returns a function that detaches.
Parts and data attributes
Class
Is
.cap-message
the root
.cap-message-dismiss
a part
.cap-message-error
a part
.cap-message-glyph
a part
.cap-message-item
a part
.cap-message-text
a part
.cap-message-undo
a part
Attribute
Values
data-kind
failurewarning
data-lasting
present or absent
State
Read from
[aria-busy="true"]
an attribute
[aria-disabled="true"]
an attribute
Accessibility
Key
Does
z
Runs the newest Undo, once. Ignored in a text field, with Ctrl, Alt, Meta or Shift held, or when there is nothing to undo
Enter or Space on Undo
Runs Undo; focus moves to the control that was undone, else to that message's Dismiss
Enter or Space on Dismiss
Clears that message; focus returns to the control that caused the message
(a message appears)
Focus does not move
(a form action answers)
Focus moves to the action's result line (useActionResult), unless focus says otherwise
role="status" is polite. A new message is read by itself, with the names of its buttons, so a listener hears that Undo is there. A failure and a failed Undo's reason are role="alert" and are announced at once.
The same words said twice are announced twice (every message is a new element).
The z hint is aria-hidden, so the button's name is "Undo".
Text 4.5:1 on its raised background; each message's edge 3:1 (--dim, or --warn when it stays); buttons at least var(--target).