components/switch-reason/switch-reason.ts

Functions

Imports

It imports components/field/field.ts, components/switch/switch.ts. Imported by components/switch-reason/switch-reason.react.tsx.

Source

1// The automation switch's behaviour. Clicking the switch, or Space on it, does not move it:
2// it opens a one-line reason beside it. Enter applies (a reason is required), Esc cancels
3// and returns focus to the switch. On apply it dispatches `cap:switch-applied` with
4// { checked, reason, waitUntil }, and the switch moves: at once, or, when a listener calls
5// waitUntil(promise), once that promise resolves. The app writes its audit row there and
6// offers Undo through the message region.
7//
8// The flow is the Capsid Portal's ui/Switch.tsx (AutomationSwitch and ReasonForm, #216),
9// without its API calls: the app's own listener does the sending.
10
11import { clearError, showError } from "../field/field.ts";
12import { setBusy as setSwitchBusy, setSwitch } from "../switch/switch.ts";
13
14export { setSwitch };
15
16export const EVENT = "cap:switch-applied";
17export const MISSING = "Type a reason. It is recorded with the change.";
18
19export interface SwitchAppliedDetail {
20  // The state the switch is moving to.
21  checked: boolean;
22  reason: string;
23  // Hold the switch until the app has saved the change. A rejection keeps the reason open
24  // with the error beside it.
25  waitUntil(promise: Promise<unknown>): void;
26}
27
28// What the reason is for, as the label's first words: "Turning seat start on". The label
29// reads "<verb>. Reason:". An app with a better verb ("Pausing sample-d") sets data-verb-on
30// and data-verb-off on the root.
31export function verbFor(name: string, checked: boolean): string {
32  return `Turning ${name} ${checked ? "on" : "off"}`;
33}
34
35export function reasonLabel(verb: string): string {
36  return `${verb}. Reason:`;
37}
38
39export function failedMessage(name: string, checked: boolean, err: unknown): string {
40  const why = err instanceof Error && err.message ? ` ${err.message}` : "";
41  return `Could not turn ${name} ${checked ? "on" : "off"}.${why} Try again, or press Esc to cancel.`;
42}
43
44interface Parts {
45  sw: HTMLInputElement;
46  label: HTMLElement;
47  form: HTMLFormElement;
48  reason: HTMLInputElement;
49  ask: HTMLElement;
50  apply: HTMLButtonElement | null;
51  cancel: HTMLElement | null;
52}
53
54function partsOf(root: HTMLElement): Parts | null {
55  const sw = root.querySelector<HTMLInputElement>("input[role='switch']");
56  const label = sw?.closest<HTMLElement>(".cap-switch");
57  const form = root.querySelector<HTMLFormElement>("form.cap-switch-reason-form");
58  const reason = form?.querySelector<HTMLInputElement>("input.cap-input");
59  const ask = form?.querySelector<HTMLElement>(".cap-switch-reason-label");
60  if (!sw || !label || !form || !reason || !ask) return null;
61  return {
62    sw,
63    label,
64    form,
65    reason,
66    ask,
67    apply: form.querySelector<HTMLButtonElement>("button[type='submit']"),
68    cancel: form.querySelector<HTMLElement>("[data-cap-part='cancel']"),
69  };
70}
71
72// Attaches to every [data-cap="switch-reason"] under root that is not attached yet.
73// data-name on the root is the thing switched, as it reads in the label ("the improve
74// loop"); without it, the switch's label is used. Returns a function that detaches them all.
75export function enhance(root: ParentNode = document): () => void {
76  const undo: Array<() => void> = [];
77  for (const el of root.querySelectorAll<HTMLElement>("[data-cap='switch-reason']:not([data-cap-ready])")) {
78    const p = partsOf(el);
79    if (!p) continue;
80    el.dataset.capReady = "";
81    const { sw, label, form, reason, ask, apply, cancel } = p;
82    const name = el.dataset.name ?? label.textContent?.replace(/\s+(On|Off)\s*$/, "").trim() ?? "this";
83    const verb = (next: boolean) => (next ? el.dataset.verbOn : el.dataset.verbOff) ?? verbFor(name, next);
84    form.noValidate = true;
85    let busy = false;
86    // The state the flip asks for, fixed when the field opens, so a poll that lands
87    // meanwhile and moves the switch cannot turn "off" into "on".
88    let target: boolean | null = null;
89
90    const setBusy = (on: boolean) => {
91      busy = on;
92      reason.readOnly = on;
93      setSwitchBusy(label, on);
94      if (on) {
95        form.setAttribute("aria-busy", "true");
96        apply?.setAttribute("aria-busy", "true");
97      } else {
98        form.removeAttribute("aria-busy");
99        apply?.removeAttribute("aria-busy");
100      }
101    };
102    // `next` is where the switch would move. A checkbox flips before its click handlers run
103    // and is put back when one cancels the click, so inside the handler sw.checked already
104    // holds the next state.
105    const open = (next: boolean) => {
106      if (!form.hidden) return reason.focus();
107      target = next;
108      reason.value = "";
109      clearError(reason);
110      ask.textContent = reasonLabel(verb(next));
111      form.hidden = false;
112      reason.focus();
113    };
114    const close = () => {
115      form.hidden = true;
116      target = null;
117      reason.value = "";
118      clearError(reason);
119      sw.focus();
120    };
121
122    // A click (and Space, which clicks) would move the switch: stop it and ask instead.
123    const onSwitchClick = (e: MouseEvent) => {
124      const next = sw.checked;
125      e.preventDefault();
126      open(next);
127    };
128    // Held while the request runs, so its answer is not hidden. Stopped here either way, so
129    // an Esc that cancels the reason does not also close a panel the switch sits in.
130    const onKey = (e: KeyboardEvent) => {
131      if (e.key !== "Escape") return;
132      e.preventDefault();
133      e.stopPropagation();
134      if (!busy) close();
135    };
136    const onCancel = () => {
137      if (!busy) close();
138    };
139    const onSubmit = (e: SubmitEvent) => {
140      e.preventDefault();
141      if (busy) return;
142      // Read from the field, so a value filled in without an input event counts.
143      const text = reason.value.trim();
144      if (!text) {
145        showError(reason, MISSING, true);
146        reason.focus();
147        return;
148      }
149      const next = target ?? !sw.checked;
150      const held: Array<Promise<unknown>> = [];
151      const detail: SwitchAppliedDetail = { checked: next, reason: text, waitUntil: (promise) => void held.push(promise) };
152      el.dispatchEvent(new CustomEvent<SwitchAppliedDetail>(EVENT, { bubbles: true, detail }));
153      const done = () => {
154        setSwitch(label, next);
155        close();
156      };
157      if (held.length === 0) {
158        done();
159        return;
160      }
161      clearError(reason);
162      setBusy(true);
163      Promise.all(held).then(
164        () => {
165          setBusy(false);
166          done();
167        },
168        (err: unknown) => {
169          setBusy(false);
170          showError(reason, failedMessage(name, next, err), true);
171          reason.focus();
172        },
173      );
174    };
175
176    sw.addEventListener("click", onSwitchClick);
177    form.addEventListener("keydown", onKey);
178    form.addEventListener("submit", onSubmit);
179    cancel?.addEventListener("click", onCancel);
180    undo.push(() => {
181      sw.removeEventListener("click", onSwitchClick);
182      form.removeEventListener("keydown", onKey);
183      form.removeEventListener("submit", onSubmit);
184      cancel?.removeEventListener("click", onCancel);
185      delete el.dataset.capReady;
186    });
187  }
188  return () => undo.forEach((f) => f());
189}