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>
Copy
View code
Installation
HTML and CSS React
// 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();Copy
import "capsomer/tokens.css";
import "capsomer/switch-reason.css";
import { ReasonForm, SwitchWithReason } from "capsomer/react/switch-reason";Copy
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>Copy
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") }),
),
);
});Copy
<SwitchWithReason label="Improve loop" name="the improve loop" checked={loopOn} onApply={(on, why) => api.setLoop(on, why)} note="Runs on the subscription." />Copy
<ReasonForm open={pending != null} verb={`Changing the overnight run to run on ${pending}`} onApply={(why) => api.setRunsOn(pending, why)} onCancel={() => setPending(null)} />Copy
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>
Copy
View code
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>
Copy
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>
Copy
View code
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>
Copy
View code
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>
Copy
View code
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>
Copy
View code
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>
Copy
View code
API reference
Prop Type Required Does openbooleanYes Shown and focused while true; hidden (and cleared for next time) while false. verbstringYes The label's first words: "Changing the overnight run to run on API". Reads "<verb>. Reason:". onApply(reason: string) => Promise<void>Yes Saves the change with its reason. A rejection keeps the form open with the error. onCancel() => voidYes Cancel, 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. placeholderstringonPendingChange(pending: boolean) => voidTold when a request starts and ends, so the control beside the form can show it is busy.
SwitchWithReason Prop Type Required Does labelstringYes A 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>Yes Saves 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. placeholderstringnoteReactNodeShown 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 Function Signature Does 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): stringfailedMessage(name: string, checked: boolean, err: unknown): stringenhance(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 Class Is .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
State Read from [hidden]an attribute
Accessibility
Key Does Space on the switch Opens the reason beside it and moves focus into it; the switch does not move Enter in the reason Applies: the switch moves and focus returns to it. With no reason, an error appears beside the field Esc in the form Cancels 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.