import "capsomer/tokens.css";
import "capsomer/approval-sheet.css";
import { ApprovalSheet } from "capsomer/react/approval-sheet";
Usage
<button type="button" class="cap-btn" data-cap-opens="approve-sheet">Review 2 gates</button>
<dialog class="cap-dialog cap-approval" data-cap="approval-sheet" data-size="lg" data-cap-modal-lock data-cap-destructive
id="approve-sheet" aria-labelledby="ap-title" aria-describedby="ap-lead">
<form class="cap-approval-form">
<div class="cap-dialog-header">
<h2 class="cap-dialog-title" id="ap-title">2 gates are waiting</h2>
<p class="cap-dialog-description" id="ap-lead">Each command runs once, when approved. Uncheck a gate you are not ready for; it stays waiting.</p>
</div>
<div class="cap-dialog-body cap-approval-gates" data-flush role="group" aria-label="Gates waiting for approval">
<fieldset class="cap-approval-gate">
<legend class="cap-approval-job">Deploy web to production</legend>
<p class="cap-approval-meta">job_8c21 in web, waiting 26 minutes</p>
<pre class="cap-approval-cmd"><code>npx wrangler deploy --env production</code></pre>
<label class="cap-check"><input type="checkbox" data-cap-part="include" name="gate" value="job_8c21" checked> Include this gate</label>
<div class="cap-field"><label class="cap-field-label" for="ap-c1">Comment (optional)</label><textarea class="cap-input" id="ap-c1" data-cap-part="comment" rows="2"></textarea></div>
</fieldset>
[more gates]
</div>
<div class="cap-approval-error" data-cap-part="error" hidden>
<div class="cap-alert" data-tone="crit" role="alert"><span data-cap-part="error-text"></span></div>
</div>
<div class="cap-dialog-footer" data-align="between">
<button type="button" class="cap-btn" data-cap-part="cancel" autofocus>Cancel</button>
<p class="cap-approval-none" id="ap-none" data-cap-part="none" hidden>Choose at least one gate.</p>
<button type="submit" class="cap-btn" data-variant="primary" data-cap-part="approve"><span data-cap-part="approve-label">Approve 2 gates</span></button>
</div>
</form>
</dialog>
Examples
One gate unchecked
<main class="specimen-page">
<h1>Queue</h1>
<p>2 gates are waiting for approval.</p>
<p><button type="button" class="cap-btn" data-cap-opens="ap-one">Review 2 gates</button></p>
</main>
<dialog class="cap-dialog cap-approval" data-cap="approval-sheet" data-size="lg" data-cap-modal-lock data-cap-destructive id="ap-one" aria-labelledby="ap-one-title" aria-describedby="ap-one-lead" data-specimen-open>
<form class="cap-approval-form">
<div class="cap-dialog-header">
<h2 class="cap-dialog-title" id="ap-one-title">2 gates are waiting</h2>
<p class="cap-dialog-description" id="ap-one-lead">Each command runs once, when approved. Uncheck a gate you are not ready for; it stays waiting.</p>
</div>
<div class="cap-dialog-body cap-approval-gates" data-flush role="group" aria-label="Gates waiting for approval">
<fieldset class="cap-approval-gate">
<legend class="cap-approval-job">Deploy web to production</legend>
<p class="cap-approval-meta">job_8c21 in web, waiting 26 minutes</p>
<pre class="cap-approval-cmd"><code>npx wrangler deploy --env production --var RELEASE:a91c4e0</code></pre>
<label class="cap-check"><input type="checkbox" data-cap-part="include" name="gate" value="job_8c21" checked /> Include this gate</label>
<div class="cap-field"><label class="cap-field-label" for="ap-one-c1">Comment (optional)</label><textarea class="cap-input" id="ap-one-c1" data-cap-part="comment" rows="2">Checked the preview at a91c4e0.</textarea></div>
</fieldset>
<fieldset class="cap-approval-gate">
<legend class="cap-approval-job">Run the docs migration 0008</legend>
<p class="cap-approval-meta">job_41fe in docs, waiting 9 minutes</p>
<pre class="cap-approval-cmd"><code>npx wrangler d1 migrations apply docs-db --remote</code></pre>
<label class="cap-check"><input type="checkbox" data-cap-part="include" name="gate" value="job_41fe" /> Include this gate</label>
<div class="cap-field"><label class="cap-field-label" for="ap-one-c2">Comment (optional)</label><textarea class="cap-input" id="ap-one-c2" data-cap-part="comment" rows="2"></textarea></div>
</fieldset>
</div>
<div class="cap-approval-error" data-cap-part="error" hidden>
<div class="cap-alert" data-tone="crit" role="alert"><span data-cap-part="error-text"></span></div>
</div>
<div class="cap-dialog-footer" data-align="between">
<button type="button" class="cap-btn" data-cap-part="cancel" autofocus>Cancel</button>
<p class="cap-approval-none" id="ap-one-none" data-cap-part="none" hidden>Choose at least one gate.</p>
<button type="submit" class="cap-btn" data-variant="primary" data-cap-part="approve"><span data-cap-part="approve-label">Approve 1 gate</span></button>
</div>
</form>
</dialog>
Pending: the approval is in flight
<main class="specimen-page">
<h1>Queue</h1>
<p>2 gates are waiting for approval.</p>
<p><button type="button" class="cap-btn" data-cap-opens="ap-pend">Review 2 gates</button></p>
</main>
<dialog class="cap-dialog cap-approval" data-cap="approval-sheet" data-size="lg" data-cap-modal-lock data-cap-destructive id="ap-pend" aria-labelledby="ap-pend-title" aria-describedby="ap-pend-lead" aria-busy="true" data-specimen-open>
<form class="cap-approval-form">
<div class="cap-dialog-header">
<h2 class="cap-dialog-title" id="ap-pend-title">2 gates are waiting</h2>
<p class="cap-dialog-description" id="ap-pend-lead">Each command runs once, when approved. Uncheck a gate you are not ready for; it stays waiting.</p>
</div>
<div class="cap-dialog-body cap-approval-gates" data-flush role="group" aria-label="Gates waiting for approval">
<fieldset class="cap-approval-gate" disabled>
<legend class="cap-approval-job">Deploy web to production</legend>
<p class="cap-approval-meta">job_8c21 in web, waiting 26 minutes</p>
<pre class="cap-approval-cmd"><code>npx wrangler deploy --env production --var RELEASE:a91c4e0</code></pre>
<label class="cap-check"><input type="checkbox" data-cap-part="include" name="gate" value="job_8c21" checked /> Include this gate</label>
<div class="cap-field"><label class="cap-field-label" for="ap-pend-c1">Comment (optional)</label><textarea class="cap-input" id="ap-pend-c1" data-cap-part="comment" rows="2"></textarea></div>
</fieldset>
<fieldset class="cap-approval-gate" disabled>
<legend class="cap-approval-job">Run the docs migration 0008</legend>
<p class="cap-approval-meta">job_41fe in docs, waiting 9 minutes</p>
<pre class="cap-approval-cmd"><code>npx wrangler d1 migrations apply docs-db --remote</code></pre>
<label class="cap-check"><input type="checkbox" data-cap-part="include" name="gate" value="job_41fe" checked /> Include this gate</label>
<div class="cap-field"><label class="cap-field-label" for="ap-pend-c2">Comment (optional)</label><textarea class="cap-input" id="ap-pend-c2" data-cap-part="comment" rows="2"></textarea></div>
</fieldset>
</div>
<div class="cap-approval-error" data-cap-part="error" hidden>
<div class="cap-alert" data-tone="crit" role="alert"><span data-cap-part="error-text"></span></div>
</div>
<div class="cap-dialog-footer" data-align="between">
<button type="button" class="cap-btn" data-cap-part="cancel" aria-disabled="true" autofocus>Cancel</button>
<p class="cap-approval-none" id="ap-pend-none" data-cap-part="none" hidden>Choose at least one gate.</p>
<button type="submit" class="cap-btn" data-variant="primary" data-cap-part="approve" aria-busy="true"><span class="cap-btn-spinner" aria-hidden="true"></span><span data-cap-part="approve-label">Approving 2 gates</span></button>
</div>
</form>
</dialog>
Error: the approval failed
<main class="specimen-page">
<h1>Queue</h1>
<p>2 gates are waiting for approval.</p>
<p><button type="button" class="cap-btn" data-cap-opens="ap-err">Review 2 gates</button></p>
</main>
<dialog class="cap-dialog cap-approval" data-cap="approval-sheet" data-size="lg" data-cap-modal-lock data-cap-destructive id="ap-err" aria-labelledby="ap-err-title" aria-describedby="ap-err-lead" data-specimen-open>
<form class="cap-approval-form">
<div class="cap-dialog-header">
<h2 class="cap-dialog-title" id="ap-err-title">2 gates are waiting</h2>
<p class="cap-dialog-description" id="ap-err-lead">Each command runs once, when approved. Uncheck a gate you are not ready for; it stays waiting.</p>
</div>
<div class="cap-dialog-body cap-approval-gates" data-flush role="group" aria-label="Gates waiting for approval">
<fieldset class="cap-approval-gate">
<legend class="cap-approval-job">Deploy web to production</legend>
<p class="cap-approval-meta">job_8c21 in web, waiting 27 minutes</p>
<pre class="cap-approval-cmd"><code>npx wrangler deploy --env production --var RELEASE:a91c4e0</code></pre>
<label class="cap-check"><input type="checkbox" data-cap-part="include" name="gate" value="job_8c21" checked /> Include this gate</label>
<div class="cap-field"><label class="cap-field-label" for="ap-err-c1">Comment (optional)</label><textarea class="cap-input" id="ap-err-c1" data-cap-part="comment" rows="2"></textarea></div>
</fieldset>
<fieldset class="cap-approval-gate">
<legend class="cap-approval-job">Run the docs migration 0008</legend>
<p class="cap-approval-meta">job_41fe in docs, waiting 10 minutes</p>
<pre class="cap-approval-cmd"><code>npx wrangler d1 migrations apply docs-db --remote</code></pre>
<label class="cap-check"><input type="checkbox" data-cap-part="include" name="gate" value="job_41fe" checked /> Include this gate</label>
<div class="cap-field"><label class="cap-field-label" for="ap-err-c2">Comment (optional)</label><textarea class="cap-input" id="ap-err-c2" data-cap-part="comment" rows="2"></textarea></div>
</fieldset>
</div>
<div class="cap-approval-error" data-cap-part="error">
<div class="cap-alert" data-tone="crit" role="alert"><span data-cap-part="error-text">Could not approve: the queue did not answer in 10 seconds. Nothing was approved. Try again.</span></div>
</div>
<div class="cap-dialog-footer" data-align="between">
<button type="button" class="cap-btn" data-cap-part="cancel" autofocus>Cancel</button>
<p class="cap-approval-none" id="ap-err-none" data-cap-part="none" hidden>Choose at least one gate.</p>
<button type="submit" class="cap-btn" data-variant="primary" data-cap-part="approve"><span data-cap-part="approve-label">Approve 2 gates</span></button>
</div>
</form>
</dialog>
Comfortable density, one gate
<main class="specimen-page">
<h1>Queue</h1>
<p>1 gate is waiting for approval.</p>
<p><button type="button" class="cap-btn" data-cap-opens="ap-comfy">Review 1 gate</button></p>
</main>
<dialog class="cap-dialog cap-approval" data-cap="approval-sheet" data-size="lg" data-density="comfortable" data-cap-modal-lock data-cap-destructive id="ap-comfy" aria-labelledby="ap-comfy-title" aria-describedby="ap-comfy-lead" data-specimen-open>
<form class="cap-approval-form">
<div class="cap-dialog-header">
<h2 class="cap-dialog-title" id="ap-comfy-title">1 gate is waiting</h2>
<p class="cap-dialog-description" id="ap-comfy-lead">Each command runs once, when approved. Uncheck a gate you are not ready for; it stays waiting.</p>
</div>
<div class="cap-dialog-body cap-approval-gates" data-flush role="group" aria-label="Gates waiting for approval">
<fieldset class="cap-approval-gate">
<legend class="cap-approval-job">Deploy web to production</legend>
<p class="cap-approval-meta">job_8c21 in web, waiting 26 minutes</p>
<pre class="cap-approval-cmd"><code>npx wrangler deploy --env production --var RELEASE:a91c4e0</code></pre>
<label class="cap-check"><input type="checkbox" data-cap-part="include" name="gate" value="job_8c21" checked /> Include this gate</label>
<div class="cap-field"><label class="cap-field-label" for="ap-comfy-c1">Comment (optional)</label><textarea class="cap-input" id="ap-comfy-c1" data-cap-part="comment" rows="2"></textarea></div>
</fieldset>
</div>
<div class="cap-approval-error" data-cap-part="error" hidden>
<div class="cap-alert" data-tone="crit" role="alert"><span data-cap-part="error-text"></span></div>
</div>
<div class="cap-dialog-footer" data-align="between">
<button type="button" class="cap-btn" data-cap-part="cancel" autofocus>Cancel</button>
<p class="cap-approval-none" id="ap-comfy-none" data-cap-part="none" hidden>Choose at least one gate.</p>
<button type="submit" class="cap-btn" data-variant="primary" data-cap-part="approve"><span data-cap-part="approve-label">Approve 1 gate</span></button>
</div>
</form>
</dialog>
API reference
ApprovalSheet
Prop
Type
Required
Does
open
boolean
Yes
gates
Gate[]
Yes
onApprove
(gates: GateChoice[]) => void | Promise<void>
Yes
Performs the approval. A returned promise holds the sheet pending until it settles: on success the sheet closes, on failure its message shows beside the buttons.
onClose
() => void
Yes
Called when the sheet closes, by Cancel, Esc or a successful approval.
lead
string
Functions
Function
Signature
Does
approveLabel
(n: number, pending?: boolean): string
"Approve 2 gates", "Approve 1 gate"; while in flight, "Approving 2 gates".
titleText
(n: number): string
The sheet's title: "2 gates are waiting", "1 gate is waiting".
selection
(dialog: Element): GateChoice[]
The gates checked in a sheet, each with its comment (trimmed; empty when none).
isPending
(dialog: Element): boolean
update
(dialog: Element): void
Brings the Approve button's label, its disabled-with-reason state and the reason in line with the checkboxes.
setPending
(dialog: Element, on: boolean): void
While a request is in flight: Approve shows its spinner and "Approving", Cancel and the gates are held, and Esc and the backdrop do nothing (the dialog is busy).
setError
(dialog: Element, message: string | null): void
Shows what went wrong, beside the buttons, as an alert; null clears it.
Opens the sheet as a modal dialog. Focus starts on Cancel (its autofocus, and the destructive rule); opener gets focus back when the sheet closes.
close
(dialog: HTMLDialogElement): void
Closes the sheet unless a request is in flight.
enhance
(root?: ParentNode): () => void
Attaches to every <dialog data-cap="approval-sheet"> under root, and to any button with data-cap-opens="<the dialog's id>". Approving dispatches a bubbling "cap-approve" event on the dialog with { gates }; the app calls setPending(dialog, true), then closes the sheet or calls setError(dialog, "...") and setPending(dialog, false).
Parts and data attributes
Class
Is
.cap-approval-cmd
its own class
.cap-approval-error
its own class
.cap-approval-form
the root
.cap-approval-gate
its own class
.cap-approval-gates
its own class
.cap-approval-job
its own class
.cap-approval-meta
its own class
.cap-approval-none
its own class
Accessibility
Key
Does
Tab, Shift Tab
Moves through the gates' checkboxes and comments, then Cancel and Approve
Space on a checkbox
Includes or leaves out that gate; Approve's count follows
Enter on Approve
Approves the chosen gates; nothing when none is chosen
Enter or Space on Cancel
Closes the sheet; focus returns to its button
Esc
Closes the sheet, except while an approval is in flight
The dialog is named by its title; each gate is a group named by its job.
The disabled Approve stays in the tab order with its reason as its description.
The error is role="alert" and stays until the next attempt.
Esc is held while pending by stopping the keydown as well as the cancel event, because Chrome skips the cancel event when the page has had no user activation since the last close request.
Forced colors: the dialog's edge (shared) and the command box keep a border.