components/switch-reason/switch-reason.react.tsx

Functions

Imports

It imports components/button/button.react.tsx, components/switch-reason/switch-reason.ts, components/switch/switch.ts. No module of this repo imports it.

Source

1import { useEffect, useId, useRef, useState, type FormEvent, type KeyboardEvent, type ReactNode } from "react";
2import { Button } from "../button/button.react.tsx";
3import { stateWord } from "../switch/switch.ts";
4import { MISSING, failedMessage, reasonLabel, verbFor } from "./switch-reason.ts";
5
6export interface SwitchWithReasonProps {
7  // A fixed noun: "Improve loop".
8  label: string;
9  // The thing switched as it reads in the reason's label: "the improve loop". Defaults to label.
10  name?: string;
11  // The label's first words, given where the next state is known: "Pausing sample-d". Reads
12  // "<verb>. Reason:". Defaults to "Turning <name> on" or "off".
13  verb?: (next: boolean) => string;
14  checked: boolean;
15  // Saves the change with its reason (write the audit row here). The switch moves when it
16  // resolves; a rejection keeps the reason open with the error. Offer Undo through the
17  // message region once it resolves.
18  onApply: (checked: boolean, reason: string) => Promise<void>;
19  placeholder?: string;
20  // Shown beside the switch while no reason is being asked for: "Paused: looking at a regression".
21  note?: ReactNode;
22}
23
24export function SwitchWithReason({ label, name, verb, checked, onApply, placeholder, note }: SwitchWithReasonProps) {
25  const base = useId();
26  const reasonId = `${base}-why`;
27  const errorId = `${base}-err`;
28  const keysId = `${base}-keys`;
29  const noun = name ?? label;
30  const [on, setOn] = useState(checked);
31  const [asking, setAsking] = useState(false);
32  // The state the flip asks for, fixed when the reason opens, so a poll that lands meanwhile
33  // and moves the switch cannot turn "off" into "on".
34  const [target, setTarget] = useState(false);
35  const [reason, setReason] = useState("");
36  const [error, setError] = useState<string | null>(null);
37  const [pending, setPending] = useState(false);
38  const switchRef = useRef<HTMLInputElement>(null);
39  const reasonRef = useRef<HTMLInputElement>(null);
40  const alive = useRef(true);
41  const next = asking ? target : !on;
42
43  useEffect(() => setOn(checked), [checked]);
44  useEffect(() => {
45    alive.current = true;
46    return () => {
47      alive.current = false;
48    };
49  }, []);
50  useEffect(() => {
51    if (asking) reasonRef.current?.focus();
52  }, [asking]);
53
54  const ask = () => {
55    if (asking) {
56      reasonRef.current?.focus();
57      return;
58    }
59    setTarget(!on);
60    setReason("");
61    setError(null);
62    setAsking(true);
63  };
64  const close = () => {
65    setAsking(false);
66    setReason("");
67    setError(null);
68    switchRef.current?.focus();
69  };
70  const submit = async (e: FormEvent<HTMLFormElement>) => {
71    e.preventDefault();
72    if (pending) return;
73    // Read from the field too, so a value filled in without an input event counts.
74    const text = (reasonRef.current?.value ?? reason).trim();
75    if (!text) {
76      setError(MISSING);
77      reasonRef.current?.focus();
78      return;
79    }
80    setError(null);
81    setPending(true);
82    try {
83      await onApply(target, text);
84      if (!alive.current) return;
85      setPending(false);
86      setOn(target);
87      close();
88    } catch (err) {
89      if (!alive.current) return;
90      setPending(false);
91      setError(failedMessage(noun, target, err));
92      reasonRef.current?.focus();
93    }
94  };
95  // Held while the request runs, so its answer is not hidden. Stopped here either way, so an
96  // Esc that cancels the reason does not also close a panel the switch sits in.
97  const onKey = (e: KeyboardEvent<HTMLFormElement>) => {
98    if (e.key !== "Escape") return;
99    e.preventDefault();
100    e.stopPropagation();
101    if (!pending) close();
102  };
103
104  return (
105    <div className="cap-switch-reason">
106      <label className="cap-switch">
107        {/* Controlled: a click or Space asks why, and React keeps the switch where it was. */}
108        <input ref={switchRef} type="checkbox" role="switch" aria-busy={pending || undefined} checked={on} onChange={ask} />{" "}
109        {label}{" "}
110        <span className="cap-switch-state" aria-hidden="true">
111          {stateWord(on)}
112        </span>
113      </label>
114      {!asking && note ? <span className="cap-switch-reason-note">{note}</span> : null}
115      <form className="cap-switch-reason-form" hidden={!asking} noValidate aria-busy={pending || undefined} onSubmit={submit} onKeyDown={onKey}>
116        <div className="cap-field">
117          <label className="cap-switch-reason-label" htmlFor={reasonId}>
118            {reasonLabel(verb ? verb(next) : verbFor(noun, next))}
119          </label>
120          <input
121            ref={reasonRef}
122            className="cap-input"
123            id={reasonId}
124            autoComplete="off"
125            required
126            readOnly={pending}
127            placeholder={placeholder}
128            value={reason}
129            onChange={(e) => setReason(e.target.value)}
130            aria-invalid={error ? true : undefined}
131            aria-describedby={error ? `${errorId} ${keysId}` : keysId}
132          />
133          <p className="cap-field-error" id={errorId} role={error ? "alert" : undefined} hidden={!error}>
134            {error}
135          </p>
136        </div>
137        <div className="cap-switch-reason-actions">
138          <Button type="submit" variant="primary" pending={pending}>
139            Apply
140          </Button>
141          <Button onClick={() => (pending ? undefined : close())}>Cancel</Button>
142        </div>
143        <span className="cap-switch-reason-keys" id={keysId}>
144          <kbd>Enter</kbd> applies, <kbd>Esc</kbd> cancels. The reason is recorded with the change.
145        </span>
146      </form>
147    </div>
148  );
149}