Skip to content

Automation switch

A switch that starts or stops automation.

<div class="cap-switch-reason" data-cap="switch-reason" data-name="the improve loop" id="sr-loop">
  <label class="cap-switch"><input type="checkbox" role="switch" checked /> Improve loop <span class="cap-switch-state" aria-hidden="true">On</span></label>
  <span class="cap-switch-reason-note" id="sr-loop-note">Runs on the subscription.</span>
  <form class="cap-switch-reason-form" hidden>
    <div class="cap-field">
      <label class="cap-switch-reason-label" for="sr-loop-why">Turning the improve loop off. Reason:</label>
      <input class="cap-input" id="sr-loop-why" autocomplete="off" required aria-describedby="sr-loop-keys" />
      <p class="cap-field-error" id="sr-loop-err" hidden></p>
    </div>
    <div class="cap-switch-reason-actions">
      <button type="submit" class="cap-btn" data-variant="primary"><span class="cap-btn-spinner" aria-hidden="true"></span><span class="cap-btn-label">Apply</span></button>
      <button type="button" class="cap-btn" data-cap-part="cancel">Cancel</button>
    </div>
    <span class="cap-switch-reason-keys" id="sr-loop-keys"><kbd>Enter</kbd> applies, <kbd>Esc</kbd> cancels. The reason is recorded with the change.</span>
  </form>
  <p role="status" id="sr-loop-said"></p>
</div>

Installation

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

enhance();

Usage

<div class="cap-switch-reason" data-cap="switch-reason" data-name="the improve loop">
  <label class="cap-switch"><input type="checkbox" role="switch" checked /> Improve loop <span class="cap-switch-state" aria-hidden="true">On</span></label>
  <span class="cap-switch-reason-note">Runs on the subscription.</span>
  <form class="cap-switch-reason-form" hidden>
    <div class="cap-field">
      <label class="cap-switch-reason-label" for="loop-why">Turning the improve loop off. Reason:</label>
      <input class="cap-input" id="loop-why" autocomplete="off" required aria-describedby="loop-why-keys" />
      <p class="cap-field-error" id="loop-why-e" hidden></p>
    </div>
    <div class="cap-switch-reason-actions">
      <button type="submit" class="cap-btn" data-variant="primary"><span class="cap-btn-spinner" aria-hidden="true"></span><span class="cap-btn-label">Apply</span></button>
      <button type="button" class="cap-btn" data-cap-part="cancel">Cancel</button>
    </div>
    <span class="cap-switch-reason-keys" id="loop-why-keys"><kbd>Enter</kbd> applies, <kbd>Esc</kbd> cancels. The reason is recorded with the change.</span>
  </form>
</div>
import { enhance, setSwitch } from "capsomer/behavior/switch-reason";
import { say } from "capsomer/behavior/message";
enhance();
loop.addEventListener("cap:switch-applied", (e) => {
  e.detail.waitUntil(
    api.setLoop(e.detail.checked, e.detail.reason).then((result) =>
      say(result.summary, { warning: result.warning, undo: () => api.undoLoop(), returnFocus: loop.querySelector("input") }),
    ),
  );
});
<SwitchWithReason label="Improve loop" name="the improve loop" checked={loopOn} onApply={(on, why) => api.setLoop(on, why)} note="Runs on the subscription." />
<ReasonForm open={pending != null} verb={`Changing the overnight run to run on ${pending}`} onApply={(why) => api.setRunsOn(pending, why)} onCancel={() => setPending(null)} />

Examples

Off (live, with its own verb)

<div class="cap-switch-reason" data-cap="switch-reason" data-name="nightly backups" data-verb-on="Enabling nightly backups" data-verb-off="Pausing nightly backups" id="sr-backups">
  <label class="cap-switch"><input type="checkbox" role="switch" /> Nightly backups <span class="cap-switch-state" aria-hidden="true">Off</span></label>
  <form class="cap-switch-reason-form" hidden>
    <div class="cap-field">
      <label class="cap-switch-reason-label" for="sr-backups-why">Enabling nightly backups. Reason:</label>
      <input class="cap-input" id="sr-backups-why" autocomplete="off" required aria-describedby="sr-backups-keys" />
      <p class="cap-field-error" id="sr-backups-err" hidden></p>
    </div>
    <div class="cap-switch-reason-actions">
      <button type="submit" class="cap-btn" data-variant="primary"><span class="cap-btn-spinner" aria-hidden="true"></span><span class="cap-btn-label">Apply</span></button>
      <button type="button" class="cap-btn" data-cap-part="cancel">Cancel</button>
    </div>
    <span class="cap-switch-reason-keys" id="sr-backups-keys"><kbd>Enter</kbd> applies, <kbd>Esc</kbd> cancels. The reason is recorded with the change.</span>
  </form>
</div>

Off, with what it is doing beside it

<div class="cap-switch-reason">
  <label class="cap-switch"><input type="checkbox" role="switch" /> Namespace example.org <span class="cap-switch-state" aria-hidden="true">Off</span></label>
  <span class="cap-switch-reason-note" id="sr-note-text">Paused: looking at a regression.</span>
</div>

Asking for a reason

<div class="cap-switch-reason">
  <label class="cap-switch"><input type="checkbox" role="switch" checked /> Deploy on push <span class="cap-switch-state" aria-hidden="true">On</span></label>
  <form class="cap-switch-reason-form">
    <div class="cap-field">
      <label class="cap-switch-reason-label" for="sr-ask-why">Turning deploy on push off. Reason:</label>
      <input class="cap-input" id="sr-ask-why" autocomplete="off" required aria-describedby="sr-ask-keys" value="Holding releases until the DNS move is done" />
    </div>
    <div class="cap-switch-reason-actions">
      <button type="submit" class="cap-btn" data-variant="primary"><span class="cap-btn-spinner" aria-hidden="true"></span><span class="cap-btn-label">Apply</span></button>
      <button type="button" class="cap-btn">Cancel</button>
    </div>
    <span class="cap-switch-reason-keys" id="sr-ask-keys"><kbd>Enter</kbd> applies, <kbd>Esc</kbd> cancels. The reason is recorded with the change.</span>
  </form>
</div>

Reason missing

<div class="cap-switch-reason">
  <label class="cap-switch"><input type="checkbox" role="switch" /> Mention sync <span class="cap-switch-state" aria-hidden="true">Off</span></label>
  <form class="cap-switch-reason-form">
    <div class="cap-field">
      <label class="cap-switch-reason-label" for="sr-miss-why">Turning mention sync on. Reason:</label>
      <input class="cap-input" id="sr-miss-why" autocomplete="off" required aria-invalid="true" aria-describedby="sr-miss-err sr-miss-keys" />
      <p class="cap-field-error" id="sr-miss-err">Type a reason. It is recorded with the change.</p>
    </div>
    <div class="cap-switch-reason-actions">
      <button type="submit" class="cap-btn" data-variant="primary"><span class="cap-btn-spinner" aria-hidden="true"></span><span class="cap-btn-label">Apply</span></button>
      <button type="button" class="cap-btn">Cancel</button>
    </div>
    <span class="cap-switch-reason-keys" id="sr-miss-keys"><kbd>Enter</kbd> applies, <kbd>Esc</kbd> cancels. The reason is recorded with the change.</span>
  </form>
</div>

Applying

<div class="cap-switch-reason">
  <label class="cap-switch"><input type="checkbox" role="switch" aria-busy="true" checked /> Agent access for billing-driver <span class="cap-switch-state" aria-hidden="true">On</span></label>
  <form class="cap-switch-reason-form" aria-busy="true">
    <div class="cap-field">
      <label class="cap-switch-reason-label" for="sr-pend-why">Turning agent access for billing-driver off. Reason:</label>
      <input class="cap-input" id="sr-pend-why" autocomplete="off" required readonly aria-describedby="sr-pend-keys" value="It pushed to the wrong branch twice" />
    </div>
    <div class="cap-switch-reason-actions">
      <button type="submit" class="cap-btn" data-variant="primary" aria-busy="true" id="sr-pend-apply"><span class="cap-btn-spinner" aria-hidden="true"></span><span class="cap-btn-label">Apply</span></button>
      <button type="button" class="cap-btn">Cancel</button>
    </div>
    <span class="cap-switch-reason-keys" id="sr-pend-keys"><kbd>Enter</kbd> applies, <kbd>Esc</kbd> cancels. The reason is recorded with the change.</span>
  </form>
</div>

Could not apply

<div class="cap-switch-reason">
  <label class="cap-switch"><input type="checkbox" role="switch" checked /> Weekly digest <span class="cap-switch-state" aria-hidden="true">On</span></label>
  <form class="cap-switch-reason-form">
    <div class="cap-field">
      <label class="cap-switch-reason-label" for="sr-fail-why">Turning the weekly digest off. Reason:</label>
      <input class="cap-input" id="sr-fail-why" autocomplete="off" required aria-invalid="true" aria-describedby="sr-fail-err sr-fail-keys" value="Nobody reads it in August" />
      <p class="cap-field-error" id="sr-fail-err">Could not turn the weekly digest off. The Portal did not answer. Try again, or press Esc to cancel.</p>
    </div>
    <div class="cap-switch-reason-actions">
      <button type="submit" class="cap-btn" data-variant="primary"><span class="cap-btn-spinner" aria-hidden="true"></span><span class="cap-btn-label">Apply</span></button>
      <button type="button" class="cap-btn">Cancel</button>
    </div>
    <span class="cap-switch-reason-keys" id="sr-fail-keys"><kbd>Enter</kbd> applies, <kbd>Esc</kbd> cancels. The reason is recorded with the change.</span>
  </form>
</div>

Comfortable density

<div data-density="comfortable">
  <div class="cap-switch-reason">
    <label class="cap-switch"><input type="checkbox" role="switch" checked /> Deploy on push <span class="cap-switch-state" aria-hidden="true">On</span></label>
    <form class="cap-switch-reason-form">
      <div class="cap-field">
        <label class="cap-switch-reason-label" for="sr-comf-why">Turning deploy on push off. Reason:</label>
        <input class="cap-input" id="sr-comf-why" autocomplete="off" required />
      </div>
      <div class="cap-switch-reason-actions">
        <button type="submit" class="cap-btn" data-variant="primary">Apply</button>
        <button type="button" class="cap-btn">Cancel</button>
      </div>
    </form>
  </div>
</div>

API reference

ReasonForm

PropTypeRequiredDoes
openbooleanYesShown and focused while true; hidden (and cleared for next time) while false.
verbstringYesThe label's first words: "Changing the overnight run to run on API". Reads "<verb>. Reason:".
onApply(reason: string) => Promise<void>YesSaves the change with its reason. A rejection keeps the form open with the error.
onCancel() => voidYesCancel, or Esc. Return focus to the control that opened the form here.
failed(err: unknown) => stringThe words for a rejection. Defaults to the error's own message.
idstringThe reason field's id; one is made up when left out.
placeholderstring
onPendingChange(pending: boolean) => voidTold when a request starts and ends, so the control beside the form can show it is busy.

SwitchWithReason

PropTypeRequiredDoes
labelstringYesA fixed noun: "Improve loop".
namestringThe thing switched as it reads in the reason's label: "the improve loop". Defaults to label.
verb(next: boolean) => stringThe label's first words, given where the next state is known: "Pausing sample-d". Reads "<verb>. Reason:". Defaults to "Turning <name> on" or "off".
checkedbooleanYes
onApply(checked: boolean, reason: string) => Promise<void>YesSaves the change with its reason (write the audit row here). The switch moves when it resolves; a rejection keeps the reason open with the error. Offer Undo through the message region once it resolves.
placeholderstring
noteReactNodeShown beside the switch while no reason is being asked for: "Paused: looking at a regression".
idstringThe switch's id, for an app that focuses it again (after an Undo) or presses it from a command. The reason field is "<id>-why".

Functions

FunctionSignatureDoes
verbFor(name: string, checked: boolean): stringWhat the reason is for, as the label's first words: "Turning seat start on". The label reads "<verb>. Reason:". An app with a better verb ("Pausing sample-d") sets data-verb-on and data-verb-off on the root.
reasonLabel(verb: string): string
failedMessage(name: string, checked: boolean, err: unknown): string
enhance(root?: ParentNode): () => voidAttaches to every [data-cap="switch-reason"] under root that is not attached yet. data-name on the root is the thing switched, as it reads in the label ("the improve loop"); without it, the switch's label is used. Returns a function that detaches them all.

Parts and data attributes

ClassIs
.cap-switch-reasonthe root
.cap-switch-reason-actionsa part
.cap-switch-reason-forma part
.cap-switch-reason-keysa part
.cap-switch-reason-labela part
.cap-switch-reason-notea part
StateRead from
[hidden]an attribute

Accessibility

KeyDoes
Space on the switchOpens the reason beside it and moves focus into it; the switch does not move
Enter in the reasonApplies: the switch moves and focus returns to it. With no reason, an error appears beside the field
Esc in the formCancels and returns focus to the switch, which has not moved. Held while the request runs
  • The label is the reason field's name, so it is read on focus. The keys hint is its description.
  • An error after Enter is announced (role="alert") and is the field's description.
  • Pending, the switch and the form are aria-busy, Apply keeps its name and width and shows the spinner, and the switch is not disabled.
  • Forced colors: the switch's own rules apply; the form has no edge of its own.