Skip to content

Message

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>

Installation

// package.json: "capsomer": "github:DrDustinEdwards/capsomer#v0.152.2"
import "capsomer/tokens.css";
import "capsomer/base.css";
import "capsomer/message.css";
import { enhance } from "capsomer/behavior/message";

enhance();

Usage

<div class="cap-message" data-cap="message" role="status" aria-label="Results and failures" aria-atomic="false"></div>
<div class="cap-message-item" data-cap-part="item" data-id="1" data-lasting data-kind="warning">
  <svg class="cap-message-glyph" viewBox="0 0 16 16" aria-hidden="true" focusable="false">[glyph]</svg>
  <p class="cap-message-text" data-cap-part="text">
    <span data-cap-part="said">Seat start is on.</span>
    <span class="cap-message-warning"> <b>Warning:</b> the audit row naming you was not written.</span>
    <span class="cap-message-error" role="alert" hidden></span>
  </p>
  <button type="button" class="cap-link-btn cap-message-undo" data-cap-part="undo"><span>Undo</span> <kbd aria-hidden="true">z</kbd></button>
  <button type="button" class="cap-btn cap-message-dismiss" data-cap-part="dismiss">Dismiss</button>
</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>

A message with Undo

<main>
  <div class="specimen-page">
    <h1>Mentions</h1>
    <p>3 waiting.</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>

After Undo

<main>
  <div class="specimen-page">
    <h1>Mentions</h1>
    <p>4 waiting.</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 result with a warning: it stays

<main>
  <div class="specimen-page">
    <h1>Namespaces</h1>
    <p>Seat start is on.</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 warning stays through the next result

<main>
  <div class="specimen-page">
    <h1>Namespaces</h1>
    <p>Seat start is off again.</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 failure with no control beside it

<main>
  <div class="specimen-page">
    <h1>Overview</h1>
    <p>Showing data from 4 minutes ago.</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>

Undo could not run: it stays, with the reason

<main>
  <div class="specimen-page">
    <h1>Mentions</h1>
    <p>3 waiting.</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>

Comfortable density: a result with Undo

<main>
  <div class="specimen-page">
    <h1>Mentions</h1>
    <p>3 waiting.</p>
  </div>
  <div class="message-sample" data-density="comfortable">
    <div class="cap-message" data-cap="message" role="status" aria-label="Results and failures" aria-atomic="false"></div>
  </div>
</main>

Try it: act, then Undo with z or the button

<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

PropTypeRequiredDoes
childrenReactNodeYes
regionbooleanRenders the region after the children. Pass false and place <MessageRegion /> where the page's results should show.
undoKeybooleanz runs the current Undo. False when the app's single-key shortcuts are switched off.

MessageRegion

Functions

FunctionSignatureDoes
useMessage(): MessageApi
useOptionalMessage(): MessageApi | nullThe 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).
newMessage(id: number, text: string, opts?: SayOptions): Message
lasting(m: Pick<Message, "error" | "warning" | "failure">): booleanWhether a message stays when the next one arrives.
withMessage(all: Message[], m: Message): Message[]The region after m arrives: it first, then every lasting message before it.
undoneText(text: string, undone?: string | undefined): string
undoErrorText(err: unknown): stringAn Undo that threw: nothing was undone, so Undo stays and this says why.
resolveFocus(f: ReturnFocus | undefined): HTMLElement | null
isUndoKey(e: KeyboardEvent): booleanz alone: no Ctrl, Alt, Meta or Shift, not a held repeat, not typed into a field.
currentUndo(all: Message[]): Message | undefinedThe message z would undo: the newest one with an Undo that is not already running.
glyphSvg(inner: string, size?: number): SVGSVGElementA 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.
messageKind(m: Pick<Message, "error" | "warning" | "failure">): MessageKindWhat 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): voidSays 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): voidSays that something did not happen. Stays until dismissed.
dismiss(): voidClears 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): voidThe 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): () => voidAttaches 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

ClassIs
.cap-messagethe root
.cap-message-dismissa part
.cap-message-errora part
.cap-message-glypha part
.cap-message-itema part
.cap-message-texta part
.cap-message-undoa part
AttributeValues
data-kindfailure warning
data-lastingpresent or absent
StateRead from
[aria-busy="true"]an attribute
[aria-disabled="true"]an attribute

Accessibility

KeyDoes
zRuns 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 UndoRuns Undo; focus moves to the control that was undone, else to that message's Dismiss
Enter or Space on DismissClears 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).