Skip to content

Approval sheet

Several waiting gates approved together in one modal sheet, each with its command and a comment.

<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-two">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-two" aria-labelledby="ap-two-title" aria-describedby="ap-two-lead" data-specimen-open>
  <form class="cap-approval-form">
    <div class="cap-dialog-header">
      <h2 class="cap-dialog-title" id="ap-two-title">2 gates are waiting</h2>
      <p class="cap-dialog-description" id="ap-two-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-two-c1">Comment (optional)</label><textarea class="cap-input" id="ap-two-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 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-two-c2">Comment (optional)</label><textarea class="cap-input" id="ap-two-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-two-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>

Installation

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

enhance();

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

PropTypeRequiredDoes
openbooleanYes
gatesGate[]Yes
onApprove(gates: GateChoice[]) => void | Promise<void>YesPerforms 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() => voidYesCalled when the sheet closes, by Cancel, Esc or a successful approval.
leadstring

Functions

FunctionSignatureDoes
approveLabel(n: number, pending?: boolean): string"Approve 2 gates", "Approve 1 gate"; while in flight, "Approving 2 gates".
titleText(n: number): stringThe 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): voidBrings the Approve button's label, its disabled-with-reason state and the reason in line with the checkboxes.
setPending(dialog: Element, on: boolean): voidWhile 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): voidShows what went wrong, beside the buttons, as an alert; null clears it.
open(dialog: HTMLDialogElement, opener?: HTMLElement | null | undefined): voidOpens 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): voidCloses the sheet unless a request is in flight.
enhance(root?: ParentNode): () => voidAttaches 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

ClassIs
.cap-approval-cmdits own class
.cap-approval-errorits own class
.cap-approval-formthe root
.cap-approval-gateits own class
.cap-approval-gatesits own class
.cap-approval-jobits own class
.cap-approval-metaits own class
.cap-approval-noneits own class

Accessibility

KeyDoes
Tab, Shift TabMoves through the gates' checkboxes and comments, then Cancel and Approve
Space on a checkboxIncludes or leaves out that gate; Approve's count follows
Enter on ApproveApproves the chosen gates; nothing when none is chosen
Enter or Space on CancelCloses the sheet; focus returns to its button
EscCloses 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.