components/message/message.react.tsx

Functions

Imports

It imports components/message/message.ts. Imported by components/content/content.react.tsx, components/history-list/examples.tsx, components/history-list/history-list.react.tsx, components/media-library/examples.tsx, components/mentions-list/examples.tsx, components/posts-list/examples.tsx.

Source

1import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState, type ReactNode, type RefObject } from "react";
2import { CLEARS_AFTER_MS, GLYPHS, currentUndo, isUndoKey, kindOf, lasting, newMessage, resolveFocus, undoErrorText, undoneText, withMessage, type Message, type SayOptions } from "./message.ts";
3
4export type { Message, SayOptions };
5
6export interface MessageApi {
7  // Says a message in the page's region. Does not move focus. A plain result replaces the
8  // plain result before it; a warning, a failure and a failed Undo stay until dismissed.
9  say: (text: string, opts?: SayOptions) => void;
10  // Says that something did not happen and has no control beside it to say so (a failed
11  // copy, a failed refresh). Stays until dismissed.
12  fail: (text: string) => void;
13  // Clears every message, lasting ones too.
14  dismiss: () => void;
15}
16
17interface Settle {
18  to?: HTMLElement | null;
19  id?: number;
20  origin?: boolean;
21}
22
23interface Ctx extends MessageApi {
24  messages: Message[];
25  runUndo: (id?: number) => void;
26  dismissOne: (id: number) => void;
27  regionRef: RefObject<HTMLDivElement | null>;
28}
29
30const MessageContext = createContext<Ctx | null>(null);
31
32export interface MessageProviderProps {
33  children: ReactNode;
34  // Renders the region after the children. Pass false and place <MessageRegion /> where
35  // the page's results should show.
36  region?: boolean;
37  // `z` runs the current Undo. False when the app's single-key shortcuts are switched off.
38  undoKey?: boolean;
39}
40
41export function MessageProvider({ children, region = true, undoKey = true }: MessageProviderProps) {
42  const [messages, setMessages] = useState<Message[]>([]);
43  // The truth between renders: an Undo that finishes later reads the list as it is then.
44  const live = useRef<Message[]>([]);
45  const nextId = useRef(1);
46  const origin = useRef<Element | null>(null);
47  const regionRef = useRef<HTMLDivElement | null>(null);
48  const timers = useRef(new Map<number, number>());
49  // Where focus goes after the render that removes the button that had it.
50  const settle = useRef<Settle | null>(null);
51
52  const commit: (next: Message[], s?: Settle) => void = useCallback((next: Message[], s?: Settle) => {
53    if (s?.to || regionRef.current?.contains(document.activeElement)) settle.current = s ?? {};
54    live.current = next;
55    setMessages(next);
56    const ids = new Set(next.map((m) => m.id));
57    for (const [id, t] of timers.current) {
58      if (!ids.has(id)) {
59        window.clearTimeout(t);
60        timers.current.delete(id);
61      }
62    }
63    for (const m of next) {
64      if (!m.clears || timers.current.has(m.id)) continue;
65      const id = m.id;
66      timers.current.set(
67        id,
68        window.setTimeout(() => {
69          timers.current.delete(id);
70          commit(
71            live.current.filter((x) => x.id !== id),
72            { origin: true },
73          );
74        }, CLEARS_AFTER_MS),
75      );
76    }
77  }, []);
78
79  useEffect(() => {
80    const t = timers.current;
81    return () => {
82      for (const id of t.values()) window.clearTimeout(id);
83      t.clear();
84    };
85  }, []);
86
87  const say = useCallback(
88    (text: string, opts: SayOptions = {}) => {
89      const active = document.activeElement;
90      if (active && active !== document.body && !regionRef.current?.contains(active)) origin.current = active;
91      commit(withMessage(live.current, newMessage(nextId.current++, text, opts)));
92    },
93    [commit],
94  );
95  const fail = useCallback((text: string) => say(text, { failure: true }), [say]);
96  const dismiss = useCallback(() => commit([], { origin: true }), [commit]);
97  const dismissOne = useCallback(
98    (id: number) => {
99      if (live.current.find((m) => m.id === id)?.busy) return;
100      commit(
101        live.current.filter((m) => m.id !== id),
102        { origin: true },
103      );
104    },
105    [commit],
106  );
107
108  const runUndo = useCallback(
109    async (id?: number) => {
110      const m = id === undefined ? currentUndo(live.current) : live.current.find((x) => x.id === id);
111      if (!m?.undo || m.busy) return;
112      const run = m.undo;
113      commit(live.current.map((x) => (x.id === m.id ? { ...x, busy: true, error: null } : x)));
114      try {
115        await run();
116      } catch (err) {
117        // Nothing was undone, so Undo stays available, and the message says why. It stays too.
118        if (live.current.some((x) => x.id === m.id)) commit(live.current.map((x) => (x.id === m.id ? { ...x, busy: false, error: undoErrorText(err) } : x)));
119        return;
120      }
121      const to = resolveFocus(m.returnFocus);
122      // The Undo may have said something itself, which replaced this message.
123      if (!live.current.some((x) => x.id === m.id)) return;
124      const said = undoneText(m.text, m.undone);
125      if (m.warning !== null) {
126        // A result that carried a warning keeps it, without its Undo; the Undo's own result arrives beside it.
127        const kept = live.current.map((x) => (x.id === m.id ? { ...x, undo: null, busy: false, error: null } : x));
128        commit(withMessage(kept, newMessage(nextId.current++, said)), { to, id: m.id });
129      } else {
130        commit(
131          live.current.map((x) => (x.id === m.id ? newMessage(m.id, said) : x)),
132          { to, id: m.id },
133        );
134      }
135    },
136    [commit],
137  );
138
139  // After a render that removed the focused button, focus goes where the caller said, else
140  // to that message's Dismiss, else back to the control that caused the message, else the
141  // main region.
142  useEffect(() => {
143    const s = settle.current;
144    if (!s) return;
145    settle.current = null;
146    if (s.to) return s.to.focus();
147    const region = regionRef.current;
148    if (region?.contains(document.activeElement)) return;
149    const back = origin.current instanceof HTMLElement && origin.current.isConnected ? origin.current : null;
150    if (s.origin) return (back ?? document.querySelector<HTMLElement>("main"))?.focus();
151    const own = s.id === undefined ? null : region?.querySelector<HTMLElement>(`[data-id="${s.id}"] [data-cap-part="dismiss"]`);
152    const any = own ?? region?.querySelector<HTMLElement>("[data-cap-part='dismiss']");
153    if (any) return any.focus();
154    (back ?? document.querySelector<HTMLElement>("main"))?.focus();
155  }, [messages]);
156
157  // `z` runs the current Undo.
158  const hasUndo = !!currentUndo(messages);
159  useEffect(() => {
160    if (!undoKey || !hasUndo) return;
161    const onKey = (e: KeyboardEvent) => {
162      if (!isUndoKey(e)) return;
163      e.preventDefault();
164      void runUndo();
165    };
166    document.addEventListener("keydown", onKey);
167    return () => document.removeEventListener("keydown", onKey);
168  }, [undoKey, hasUndo, runUndo]);
169
170  const value = useMemo<Ctx>(() => ({ say, fail, dismiss, messages, runUndo, dismissOne, regionRef }), [say, fail, dismiss, messages, runUndo, dismissOne]);
171  return (
172    <MessageContext.Provider value={value}>
173      {children}
174      {region ? <MessageRegion /> : null}
175    </MessageContext.Provider>
176  );
177}
178
179export function useMessage(): MessageApi {
180  const ctx = useContext(MessageContext);
181  if (!ctx) throw new Error("useMessage needs a <MessageProvider> above it.");
182  return { say: ctx.say, fail: ctx.fail, dismiss: ctx.dismiss };
183}
184
185// The same API, or null when no <MessageProvider> is above: for a component that says its
186// results in the page's region when there is one and works without it (a form that posts).
187export function useOptionalMessage(): MessageApi | null {
188  const ctx = useContext(MessageContext);
189  return ctx ? { say: ctx.say, fail: ctx.fail, dismiss: ctx.dismiss } : null;
190}
191
192// The region itself. One per page. It has no data-cap attribute, so the plain behaviour
193// module never attaches to a region React owns.
194export function MessageRegion() {
195  const ctx = useContext(MessageContext);
196  if (!ctx) throw new Error("MessageRegion needs a <MessageProvider> above it.");
197  const { messages, runUndo, dismissOne, regionRef } = ctx;
198  return (
199    // aria-atomic is false so a new message is read by itself and the ones before it are not read again.
200    <div className="cap-message" role="status" aria-label="Results and failures" aria-atomic="false" ref={regionRef}>
201      {/* A new id per message is a new element, so the same words are announced again. */}
202      {messages.map((m) => (
203        <div key={m.id} className="cap-message-item" data-cap-part="item" data-id={m.id} data-lasting={lasting(m) ? "" : undefined} data-kind={kindOf(m)}>
204          <svg className="cap-message-glyph" viewBox="0 0 16 16" aria-hidden="true" focusable="false" dangerouslySetInnerHTML={{ __html: GLYPHS[kindOf(m)] }} />
205          <p className="cap-message-text" data-cap-part="text">
206            <span data-cap-part="said" role={m.failure ? "alert" : undefined}>
207              {m.text}
208            </span>
209            {m.warning !== null ? (
210              <span className="cap-message-warning">
211                {" "}
212                <b>Warning:</b> {m.warning}
213              </span>
214            ) : null}
215            {m.error !== null ? (
216              <span className="cap-message-error" role="alert">
217                {m.error}
218              </span>
219            ) : null}
220          </p>
221          {m.undo ? (
222            <button type="button" className="cap-link-btn cap-message-undo" data-cap-part="undo" aria-busy={m.busy || undefined} onClick={() => void runUndo(m.id)}>
223              <span>{m.busy ? "Undoing..." : "Undo"}</span> <kbd aria-hidden="true">z</kbd>
224            </button>
225          ) : null}
226          {!m.clears ? (
227            <button type="button" className="cap-btn cap-message-dismiss" data-cap-part="dismiss" aria-disabled={m.busy || undefined} onClick={() => dismissOne(m.id)}>
228              Dismiss
229            </button>
230          ) : null}
231        </div>
232      ))}
233    </div>
234  );
235}