Chain

A sheet read top to bottom (a running calculation): each line worked into the value before it, and interims naming the value where they stand. Reach for it for invoices, budgets and cost sheets.

import { Chain, Plus, Minus, Times, DividedBy, Interim } from "@umriss-ui/calculation";

A chain has no precedence: every line works into the value before it, strictly in order. So Times and DividedBy stand alone between two named values; anything else fails on the first render.

A chain in view stands open – it is the working itself. What should show only on request goes into one line as a tree, which folds. Only an Interim shows the running value (ADR-0028).

Examples

Take amounts away from a first quantity

A chain starts with a quantity without operator; Minus and Plus take a label and a value directly, and an Interim ends it.

import { Calculation, Chain, Given, Interim, Minus } from "@umriss-ui/calculation";

export default function NetWeight() {
  return (
    <Calculation aria-label="Net weight, shipment FP-1004223">
      <Chain>
        <Given label="Gross weight" value={1250} unit="kg" decimals={1} />
        <Minus label="Pallet" value={25} unit="kg" decimals={1} />
        <Minus label="Crates" value={144} unit="kg" decimals={1} />
        <Minus label="Packaging" value={11.5} unit="kg" decimals={1} />
        <Interim label="Net weight" unit="kg" decimals={1} />
      </Chain>
    </Calculation>
  );
}

Mix additions and deductions

Where a figure is a list of items, write each as a line of its own; a credit is a Minus where it stands.

import { Calculation, Chain, Given, Interim, Minus, Plus } from "@umriss-ui/calculation";

export default function TourCost() {
  return (
    <Calculation aria-label="Cost of tour T-01, Tuesday">
      <Chain>
        <Given label="Driver, 6.5 h" value={224.25} unit="€" decimals={2} />
        <Plus label="Diesel" value={13.89} unit="€" decimals={2} />
        <Plus label="Van, one day" value={58} unit="€" decimals={2} />
        <Plus label="Tolls" value={9.4} unit="€" decimals={2} />
        <Plus label="Parking" value={6} unit="€" decimals={2} />
        <Minus label="Fuel card rebate" value={0.7} unit="€" decimals={2} />
        <Interim label="Cost of the tour" unit="€" decimals={2} />
      </Chain>
    </Calculation>
  );
}

Multiply between two interims

A chain has no precedence, so Times and DividedBy stand alone between two interims; after a Plus they fail on the first render.

import { Calculation, Chain, Given, Interim, Plus, Times } from "@umriss-ui/calculation";

export default function MarkUpAndVat() {
  return (
    <Calculation aria-label="Price of a workshop day">
      <Chain>
        <Given label="Two facilitators, one day" value={960} unit="€" decimals={2} />
        <Plus label="Room and materials" value={180} unit="€" decimals={2} />
        <Interim label="Cost of the day" unit="€" decimals={2} />
        <Times label="Mark-up" value={1.25} />
        <Interim label="Net price" unit="€" decimals={2} />
        <Times label="VAT factor" value={1.19} />
        <Interim label="Gross price" unit="€" decimals={2} />
      </Chain>
    </Calculation>
  );
}

Fold a group of lines into one

A chain in view never folds; to show items only on request, put them into one line as a tree: a Sum held by a Minus – a Minus, because contributions are positive by nature. Rows of either sign from data go into a Plus instead; the page Rows from data shows every case.

import { Calculation, Chain, Given, Interim, Minus, Plus, Product, Ref, Sum } from "@umriss-ui/calculation";

const CONTRIBUTIONS = [
  { name: "Pension insurance", rate: 0.093 },
  { name: "Unemployment insurance", rate: 0.013 },
  { name: "Health insurance", rate: 0.082 },
  { name: "Long-term care insurance", rate: 0.017 },
];

export default function Payslip() {
  return (
    <Calculation aria-label="Payslip, March">
      <Chain>
        <Given id="gross" label="Gross salary" value={4200} unit="€" decimals={2} />
        <Minus label="Income tax" value={612.5} unit="€" decimals={2} />
        <Minus label="Church tax" value={49} unit="€" decimals={2} />
        <Minus>
          <Sum label="Social security contributions" unit="€" decimals={2}>
            {CONTRIBUTIONS.map((contribution) => (
              <Product key={contribution.name} label={contribution.name} unit="€" decimals={2}>
                <Given label={`Rate, ${contribution.name.toLowerCase()}`} value={contribution.rate} format="percent" />
                <Ref to="gross" />
              </Product>
            ))}
          </Sum>
        </Minus>
        <Interim label="Net salary" unit="€" decimals={2} />
        <Minus label="Capital-forming benefits" value={40} unit="€" decimals={2} />
        <Plus label="Travel allowance" value={60} unit="€" decimals={2} />
        <Interim label="Amount paid out" unit="€" decimals={2} />
      </Chain>
    </Calculation>
  );
}

Build the lines from data

.map inside a chain makes each item a Plus, and all stand in view above their interim.

import { Calculation, Chain, Given, Interim, Plus } from "@umriss-ui/calculation";

const ITEMS = [
  ["Compute, booking API", 4128.4],
  ["Compute, search", 2864.1],
  ["Compute, workers", 1741.9],
  ["Database, primary", 2310],
  ["Database, replicas", 1540],
  ["Object storage", 386.2],
  ["Block storage", 512.8],
  ["Data transfer out", 948.6],
  ["Load balancers", 264],
  ["Queues", 118.3],
  ["Cache cluster", 690],
  ["Log storage", 431.7],
  ["Metrics and traces", 822.5],
  ["Backups", 207.4],
  ["Support plan", 1200],
] as const;

export default function FifteenItems() {
  const [[firstName, firstAmount], ...rest] = ITEMS;
  return (
    <Calculation aria-label="Cloud bill, March">
      <Chain>
        <Given label={firstName} value={firstAmount} unit="€" decimals={2} />
        {rest.map(([name, amount]) => (
          <Plus key={name} label={name} value={amount} unit="€" decimals={2} />
        ))}
        <Interim label="Cloud bill, March" unit="€" decimals={2} />
      </Chain>
    </Calculation>
  );
}

Put a chain inside a tree

As an operand a chain folds and stands for its last interim; opened, it stands whole beneath its line.

import { Calculation, Chain, Given, Interim, Minus, Plus, Quotient, Ref } from "@umriss-ui/calculation";

export default function ChainInATree() {
  return (
    <Calculation aria-label="Delivery rate, North depot, Tuesday">
      <Quotient label="Delivery rate" format="percent" target={0.97}>
        <Chain>
          <Given id="out" label="Parcels out" value={1000} unit="parcels" />
          <Minus label="Failed attempts" value={31} unit="parcels" />
          <Minus label="Refused at the door" value={6} unit="parcels" />
          <Plus label="Delivered on a second run" value={14} unit="parcels" />
          <Interim label="Parcels delivered" unit="parcels" />
        </Chain>
        <Ref to="out" />
      </Quotient>
    </Calculation>
  );
}

Hold an interim to its limits

An Interim takes target and limits like any quantity; here the error budget left is assessed against two lower limits.

import { Calculation, Chain, Given, Interim, Minus, Product } from "@umriss-ui/calculation";

export default function ErrorBudget() {
  return (
    <Calculation aria-label="Error budget of Checkout, March">
      <Chain>
        <Product label="Error budget, March" unit="min" decimals={1}>
          <Given label="Minutes in March" value={44640} unit="min" />
          <Given label="Allowed downtime" value={0.0005} format="percent" decimals={2} />
        </Product>
        <Minus label="INC-1039, payment provider timeouts" value={9} unit="min" decimals={1} />
        <Minus label="INC-1036, failed deploy" value={4} unit="min" decimals={1} />
        <Minus label="INC-1048, card payments time out" value={21} unit="min" decimals={1} />
        <Interim
          label="Budget left"
          unit="min"
          decimals={1}
          limits={[
            { value: 5, side: "lower", severity: "warning" },
            { value: 0, side: "lower", severity: "alarm" },
          ]}
        />
      </Chain>
    </Calculation>
  );
}

When to use something else

• A figure made of factors, folded to its formula → Tree

Keyboard

The keys of Calculation apply here.

API

type MetricValues = Readonly<Record<string, number | null>>;

type Side = "upper" | "lower";

type Severity = "warning" | "alarm";

Known limits

• A chain in view does not fold; as an operand of a tree it folds to its last interim.

What umriss deliberately does not build, and why: ADR-0032.

Every page of @umriss-ui/calculation

Getting started

• Installation

Writing a calculation

• Calculation
• Tree
• Chain
• Rows from data
• Given
• Metrics

In practice

• What can go wrong
• Worked examples

API index

• API index