Skip to content

Calculator

A form drawn from a list of fields beside a result computed on the server, working with script off.

<div class="cap-calculator" id="calc-live" data-cap="calculator" data-calculator="transfer">
  <form class="cap-calculator-form" method="get" action="./states.html">
    <div class="cap-field">
      <label class="cap-field-label" for="live-visits">Visits per month</label>
      <p class="cap-field-help" id="live-visits-help">25000 or 2.5 x 10<sup>4</sup>.</p>
      <input class="cap-input" id="live-visits" name="visits" type="text" inputmode="decimal" autocomplete="off" spellcheck="false" value="25000" aria-describedby="live-visits-help" />
    </div>
    <div class="cap-field">
      <label class="cap-field-label" for="live-weight">Page weight<span class="cap-calculator-unit"> (KB)</span></label>
      <p class="cap-field-help" id="live-weight-help">Default: <a href="https://example.com/reports/page-weight">Example Co annual report</a>.</p>
      <input class="cap-input" id="live-weight" name="weight" type="text" inputmode="decimal" autocomplete="off" spellcheck="false" value="1800" aria-describedby="live-weight-help" />
    </div>
    <button type="submit" class="cap-btn" data-variant="secondary">Calculate</button>
  </form>
  <div class="cap-calculator-output">
    <div class="cap-calculator-status" role="status"><p class="cap-calculator-answer">Monthly transfer: <strong>45 GB per month</strong></p></div>
    <div class="cap-calculator-detail"><div class="cap-calculator-section"><h3>Monthly transfer</h3><ol class="cap-calculator-steps"><li>Data per month: 25,000 visits x 1,800 KB = 4.5 x 10<sup>7</sup> KB.</li><li>In gigabytes: 4.5 x 10<sup>7</sup> KB / 10<sup>6</sup> = 45 GB.</li></ol><p class="cap-calculator-note">1 GB is 10<sup>6</sup> KB here, as hosts bill it.</p></div></div>
  </div>
</div>

Installation

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

enhance();

Usage

<div class="cap-calculator" data-cap="calculator" data-calculator="transfer">
  <form class="cap-calculator-form" method="get" action="/tools/transfer">
    <div class="cap-field">
      <label class="cap-field-label" for="transfer-weight">Page weight<span class="cap-calculator-unit"> (KB)</span></label>
      <p class="cap-field-help" id="transfer-weight-help">Default: <a href="/reports/page-weight">Annual report</a>.</p>
      <input class="cap-input" id="transfer-weight" name="weight" type="text" inputmode="decimal" autocomplete="off" spellcheck="false" value="1800" aria-describedby="transfer-weight-help" />
    </div>
    <button type="submit" class="cap-btn" data-variant="secondary">Calculate</button>
  </form>
  <div class="cap-calculator-output">
    <div class="cap-calculator-status" role="status"><p class="cap-calculator-answer">Monthly transfer: <strong>45 GB per month</strong></p></div>
    <div class="cap-calculator-detail">
      <div class="cap-calculator-section"><h3>Monthly transfer</h3><ol class="cap-calculator-steps"><li>…</li></ol><p class="cap-calculator-note">…</p></div>
    </div>
  </div>
</div>
type CalculatorResult =
  | { ok: true; sections: Array<{ heading: string; result?: string; steps: string[]; notes?: string[] }> }
  | { ok: false; error: string };
import { Calculator } from "capsomer/react/calculator";
import { initialValues } from "capsomer/behavior/calculator";

<Calculator id="transfer" action="/tools/transfer" fields={FIELDS} values={initialValues(FIELDS, params)} run={runTransfer} />

Examples

A value it cannot use

<div class="cap-calculator" id="calc-error">
  <form class="cap-calculator-form" method="get" action="./states.html">
    <div class="cap-field">
      <label class="cap-field-label" for="err-visits">Visits per month</label>
      <p class="cap-field-help" id="err-visits-help">25000 or 2.5 x 10<sup>4</sup>.</p>
      <input class="cap-input" id="err-visits" name="visits" type="text" inputmode="decimal" autocomplete="off" spellcheck="false" value="0" aria-describedby="err-visits-help" />
    </div>
    <div class="cap-field">
      <label class="cap-field-label" for="err-weight">Page weight<span class="cap-calculator-unit"> (KB)</span></label>
      <p class="cap-field-help" id="err-weight-help">Default: <a href="https://example.com/reports/page-weight">Example Co annual report</a>.</p>
      <input class="cap-input" id="err-weight" name="weight" type="text" inputmode="decimal" autocomplete="off" spellcheck="false" value="1800" aria-describedby="err-weight-help" />
    </div>
    <button type="submit" class="cap-btn" data-variant="secondary">Calculate</button>
  </form>
  <div class="cap-calculator-output">
    <div class="cap-calculator-status" role="status"><p class="cap-calculator-error">Enter the visits per month, greater than 0.</p></div>
    <div class="cap-calculator-detail"></div>
  </div>
</div>

React, embedded in another page

<div data-mount="react"></div>

API reference

Calculator

PropTypeRequiredDoes
idstringYesKeys the ids, so one calculator can sit on a page several times ("loan-step-3").
actionstringYesThe page that answers the form with script off: the form is a plain GET to it.
fieldsCalculatorField[]Yes
valuesRecord<string, string>YesThe opening values, usually from the address (initialValues(fields, params)).
runCalculatorRunYesThe site's arithmetic: values in, a result out. It runs on the server and on every input.
calculatorstringThe name a site's enhance() call looks up run by, on a page that is not hydrated.
embeddedbooleanInside another page (a procedure step): the form still submits to action, but typing does not write the address.
submitLabelstring
childrenReactNodeShown after the result: a note, or a link to the calculator's own page (alone on its line, so a whole target: data-link="next", components/link).

Functions

FunctionSignatureDoes
textParts(line: string): TextPart[]A line with each 10^n split out as a power: "1 x 10^-3" is "1 x 10" and a superscript "−3".
lineNodes(line: string): (string | ViewNode)[]A line as view nodes, its powers as sup.
resultView(result: CalculatorResult): { summary: (string | ViewNode)[]; detail: ViewNode[]; }What a result looks like, as plain nodes. summary is the one line per section the status region announces; detail is the worked steps under it. An error is the summary alone.
checkTag(tag: string): "div" | "p" | "span" | "h3" | "h4" | "ol" | "ul" | "li" | "strong" | "em" | "sup" | "sub" | "code"Throws on a tag outside VIEW_TAGS: a bug in the site's tree, never something to draw.
buildNode(node: string | ViewNode, doc?: Document): NodeA view node as DOM: elements and text nodes, no markup string.
formValues(form: HTMLFormElement, fields: string[]): Record<string, string>The form's values for the given fields, as strings, cut at 40 characters as the address is.
initialValues(fields: CalculatorField[], params?: URLSearchParams | undefined): Record<string, string>The values for fields: the address's where it has them, each field's opening value where not. Cut at 40 characters, so a long query string cannot make a long page.
attach(root: HTMLElement, run: CalculatorRun): () => voidWires one calculator: recomputes on every input with run, writes the result into its status and detail regions, and (unless it is data-embedded) writes the values to the address, so a copied URL shows the same calculation. Enter or Calculate recomputes in place.
enhance(root?: Element | Document | DocumentFragment, runs?: Record<string, CalculatorRun>): () => voidAttaches to every [data-cap="calculator"] under root not yet attached, each with the run its data-calculator names in runs. A calculator with no run is an error, not a silent dead form. The root is Element | Document | DocumentFragment, not ParentNode: under @cloudflare/workers-types an HTMLFormElement does not type as a ParentNode.

Parts and data attributes

ClassIs
.cap-calculatorthe root
.cap-calculator-answera part
.cap-calculator-errora part
.cap-calculator-forma part
.cap-calculator-notea part
.cap-calculator-outputa part
.cap-calculator-sectiona part
.cap-calculator-statusa part
.cap-calculator-stepsa part
.cap-calculator-unita part

Accessibility

KeyDoes
TabMoves through the fields, their source links and Calculate
Typing in a fieldRecomputes the result at once
Enter in a field, or CalculateRecomputes in place (with script off, loads the answer)
  • Every field has a visible label with its unit, and its help is its description (aria-describedby).
  • The status region is announced politely when the answer changes; the worked steps are a numbered list under a heading for each section.
  • Screen readers: no manual NVDA or VoiceOver run, by decision (2026-11-07); the automated browser checks and a front-end review stand in. Automated: see the site's Tests page.