@umriss-ui/calculation 0.2.4 → 0.3.0

package/docs/llms-full.md

@@ -0,0 +1,1083 @@
+# @umriss-ui/calculation 0.3.0
+
+> The umriss calculation - a derivation written as it is shown, evaluated by the library, folded and read line by line.
+
+Install with `pnpm add @umriss-ui/calculation`. This text is generated from the package's demo (https://romanhaendler.github.io/umriss-ui/calculation/): every page with its import line, its examples - the source exactly as it runs, with the package name where the demo imports its own source - its props tables generated from the code, and why it is built the way it is. The pages index stands in https://romanhaendler.github.io/umriss-ui/calculation/llms.txt.
+
+## Writing a calculation
+
+Two forms written as elements: a tree for a figure put together from factors, a chain for a sheet read top to bottom.
+
+### Calculation
+
+How a figure came about, as a statement down to the numbers it came from - evaluated by the library, never handed in.
+
+```ts
+import { Calculation, Given, Sum, Product, Quotient, Ref, Chain, Plus, Interim } from "@umriss-ui/calculation";
+```
+
+Demo page: https://romanhaendler.github.io/umriss-ui/calculation/#/calculation
+
+#### Examples
+
+##### Two numbers and a sum
+
+```tsx
+import { Calculation, Given, Sum } from "@umriss-ui/calculation";
+
+/* The smallest calculation there is: two givens and the operator that joins
+   them. The result stands beneath its operands under a rule, and the double
+   rule says that this is where the calculation ends. Nothing here is typed in
+   twice - the 1,000 is computed by the calculation, never handed to it. */
+export default function FirstSum() {
+  return (
+    <Calculation aria-label="Output of press 3, Tuesday">
+      <Sum label="Output, Tuesday" unit="pcs">
+        <Given label="Early shift" value={512} unit="pcs" />
+        <Given label="Late shift" value={488} unit="pcs" />
+      </Sum>
+    </Calculation>
+  );
+}
+```
+
+##### OEE of an early shift
+
+```tsx
+import { Calculation, Difference, Given, Product, Quotient, Ref } from "@umriss-ui/calculation";
+
+/* A tree: overall equipment effectiveness as availability × performance ×
+   quality, each derived from the shift's numbers. The three factors stand
+   above the result, each folded, with the formula it hides beneath its name;
+   click a name to open it.
+
+   Planned production time, run time and total count are each used twice. They
+   are defined once, where they belong, and stand elsewhere as a `<Ref>` - a
+   reference shows the quantity's name and number, never its derivation again.
+   Hover a line and its operands and every place it is used light up. */
+export default function Oee() {
+  return (
+    <Calculation aria-label="OEE, early shift">
+      <Product label="OEE" format="percent" target={0.85}>
+        <Quotient label="Availability" format="percent">
+          <Difference id="runtime" label="Run time" unit="min">
+            <Given id="planned" label="Planned production time" value={450} unit="min" />
+            <Given label="Downtime" value={38} unit="min" />
+          </Difference>
+          <Ref to="planned" />
+        </Quotient>
+        <Quotient label="Performance" format="percent">
+          <Product label="Ideal run time" unit="min">
+            <Given label="Ideal cycle time" value={0.8} unit="min/pc" />
+            <Given id="total" label="Total count" value={480} unit="pcs" />
+          </Product>
+          <Ref to="runtime" />
+        </Quotient>
+        <Quotient label="Quality" format="percent">
+          <Given label="Good count" value={461} unit="pcs" />
+          <Ref to="total" />
+        </Quotient>
+      </Product>
+    </Calculation>
+  );
+}
+```
+
+##### A costing sheet
+
+```tsx
+import { Calculation, Chain, Given, Interim, Plus, Product, Ref, Times } from "@umriss-ui/calculation";
+
+/* The same calculation read the other way: as a chain, top to bottom, the way
+   a costing sheet stands on paper. Each line works its operand into the value
+   before it, and an `<Interim>` names that value where it stands.
+
+   The chain stands open, as on paper: lines, a rule, the interim, and on.
+   A surcharge on an earlier line is a `<Plus>` holding a product with a
+   `<Ref>` - the overhead is 120 % of the direct labour, not of the running
+   value - and that product is a tree: it folds, showing the formula it hides,
+   and opens beneath its line on a click. */
+export default function CostingSheet() {
+  return (
+    <Calculation aria-label="Offer price, order A-2041">
+      <Chain>
+        <Given id="material" label="Direct material" value={1840} unit="€" decimals={2} />
+        <Plus>
+          <Product label="Material overhead" unit="€" decimals={2}>
+            <Given label="Material overhead rate" value={0.12} format="percent" />
+            <Ref to="material" />
+          </Product>
+        </Plus>
+        <Interim label="Material cost" unit="€" decimals={2} />
+        <Plus id="labour" label="Direct labour" value={960} unit="€" decimals={2} />
+        <Plus>
+          <Product label="Production overhead" unit="€" decimals={2}>
+            <Given label="Production overhead rate" value={1.2} format="percent" />
+            <Ref to="labour" />
+          </Product>
+        </Plus>
+        <Interim id="production" label="Production cost" unit="€" decimals={2} />
+        <Plus>
+          <Product label="Administration and sales overhead" unit="€" decimals={2}>
+            <Given label="Overhead rate" value={0.15} format="percent" />
+            <Ref to="production" />
+          </Product>
+        </Plus>
+        <Interim label="Cost price" unit="€" decimals={2} />
+        <Times label="Profit mark-up" value={1.08} />
+        <Interim label="Net offer price" unit="€" decimals={2} target={5000} />
+      </Chain>
+    </Calculation>
+  );
+}
+```
+
+#### API
+
+##### `CalculationProps`
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `children` (required) | `ReactNode` | — | The result: exactly one quantity - a tree (`<Sum>`, `<Difference>`, `<Product>`, `<Quotient>` with their operands, `<Given>` as leaves) or a `<Chain>`, the two mixing freely; `<Ref>` for a quantity defined elsewhere. |
+
+Also takes every attribute of the rendered element – without `children`.
+
+#### Why it is like this
+
+##### The library computes what it shows
+
+There is no prop for a result. Every number on a derived line is computed with the operator the line names, by the calculation itself - so a page cannot say "412 ÷ 450" beside a figure that was computed from something else. That is also why there is no formula text and no operator of your own: a written-out operation the library did not perform could say something the number does not.
+
+##### Written as it is shown
+
+The nesting is the fold structure and the child order is the operand order. A quantity used twice is defined once, where you place it, and stands everywhere else as a `<Ref>`. What TypeScript cannot check - a reference to nothing, a circle through references, a wrapper component the calculation cannot look into - fails on the first render with a message saying which. See `docs/adr/0027-a-calculation-is-written-as-it-is-shown.md`.
+
+### Tree
+
+Sum, difference, product and quotient, each holding its operands - and a quantity used twice, defined once.
+
+```ts
+import { Sum, Difference, Product, Quotient, Ref } from "@umriss-ui/calculation";
+```
+
+Demo page: https://romanhaendler.github.io/umriss-ui/calculation/#/tree
+
+#### Examples
+
+##### A share with a target
+
+```tsx
+import { Calculation, Given, Quotient } from "@umriss-ui/calculation";
+
+/* `format="percent"` presents a plain ratio as per cent - the quotient stays
+   0.9604 in every operation. The target is assessed through core's
+   `assess()` and stands beneath the number: missed, never violated. */
+export default function ShareWithTarget() {
+  return (
+    <Calculation aria-label="First-pass yield, press 3">
+      <Quotient label="First-pass yield" format="percent" target={0.95}>
+        <Given label="Good parts" value={461} unit="pcs" />
+        <Given label="Parts made" value={480} unit="pcs" />
+      </Quotient>
+    </Calculation>
+  );
+}
+```
+
+##### A difference of three
+
+```tsx
+import { Calculation, Difference, Given } from "@umriss-ui/calculation";
+
+/* `<Difference>` takes the first operand and subtracts every other: a − b − c.
+   Each operand after the first carries its minus in the operator column. */
+export default function DifferenceOfThree() {
+  return (
+    <Calculation aria-label="Planned production time, early shift">
+      <Difference label="Planned production time" unit="min">
+        <Given label="Shift length" value={480} unit="min" />
+        <Given label="Breaks" value={30} unit="min" />
+        <Given label="Planned maintenance" value={20} unit="min" />
+      </Difference>
+    </Calculation>
+  );
+}
+```
+
+##### A product with units
+
+```tsx
+import { Calculation, Given, Product } from "@umriss-ui/calculation";
+
+/* A unit is a label the caller writes; nothing converts or checks it. The
+   product of kW and h is written as kWh because the caller says so - the
+   calculation does no unit algebra, and does not pretend to. `decimals` fixes
+   the places shown; the operation uses the full value. */
+export default function ProductWithUnits() {
+  return (
+    <Calculation aria-label="Energy of the furnace, one shift">
+      <Product label="Energy, one shift" unit="kWh" decimals={1}>
+        <Given label="Mean power" value={86.35} unit="kW" />
+        <Given label="Hours at temperature" value={7.25} unit="h" />
+      </Product>
+    </Calculation>
+  );
+}
+```
+
+##### A quantity used twice
+
+```tsx
+import { Calculation, Given, Product, Quotient, Ref } from "@umriss-ui/calculation";
+
+/* The material per part enters both products. It is defined once, where it
+   first belongs, and stands as a `<Ref>` in the second place: a reference
+   shows the quantity's name and number, in italics, never its derivation
+   again. Open both products and hover either place - both light up. */
+export default function UsedTwice() {
+  return (
+    <Calculation aria-label="Material lost to scrap, week 12">
+      <Quotient label="Material lost to scrap" format="percent" decimals={2}>
+        <Product label="Scrap cost" unit="€" decimals={2}>
+          <Given label="Scrapped parts" value={38} unit="pcs" />
+          <Given id="material" label="Material per part" value={2.8} unit="€" decimals={2} />
+        </Product>
+        <Product label="Material cost" unit="€" decimals={2}>
+          <Given label="Parts made" value={1278} unit="pcs" />
+          <Ref to="material" />
+        </Product>
+      </Quotient>
+    </Calculation>
+  );
+}
+```
+
+##### First-pass yield across three stations
+
+```tsx
+import { Calculation, Given, Product, Quotient } from "@umriss-ui/calculation";
+
+/* A product of three quotients, one per station, each built from the
+   station's own counts - the rolled throughput yield. Every factor stands
+   folded with its formula beneath it; open one to redo it. */
+
+const STATIONS = [
+  { name: "Turning", good: 982, made: 1000 },
+  { name: "Grinding", good: 961, made: 982 },
+  { name: "Final inspection", good: 948, made: 961 },
+];
+
+export default function FirstPassYield() {
+  return (
+    <Calculation aria-label="Rolled throughput yield, shaft line">
+      <Product label="Rolled throughput yield" format="percent" target={0.95}>
+        {STATIONS.map((station) => (
+          <Quotient key={station.name} label={`Yield, ${station.name.toLowerCase()}`} format="percent">
+            <Given label={`Good, ${station.name.toLowerCase()}`} value={station.good} unit="pcs" />
+            <Given label={`Into ${station.name.toLowerCase()}`} value={station.made} unit="pcs" />
+          </Quotient>
+        ))}
+      </Product>
+    </Calculation>
+  );
+}
+```
+
+##### Energy per piece, with a limit
+
+```tsx
+import { Calculation, Given, Quotient, Sum } from "@umriss-ui/calculation";
+
+/* Three meters summed and divided by the good pieces. The limit is assessed
+   through core's `assess()`: the verdict stands as a word beneath the number,
+   never as a colour alone. */
+export default function EnergyPerPiece() {
+  return (
+    <Calculation aria-label="Energy per good piece, hall 2">
+      <Quotient
+        label="Energy per good piece"
+        unit="kWh/pc"
+        decimals={3}
+        limits={[{ value: 0.45, side: "upper", severity: "warning" }]}
+      >
+        <Sum label="Energy, hall 2" unit="kWh">
+          <Given label="Presses" value={1840} unit="kWh" />
+          <Given label="Compressed air" value={612} unit="kWh" />
+          <Given label="Lighting and HVAC" value={295} unit="kWh" />
+        </Sum>
+        <Given label="Good pieces" value={5920} unit="pcs" />
+      </Quotient>
+    </Calculation>
+  );
+}
+```
+
+#### API
+
+##### `OperatorProps`
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `children` | `ReactNode` | — | The operands, in order: quantities, givens and references. |
+| `label` (required) | `string` | — | What the quantity is called. It stands on its line, wherever it is an operand, and in the accessible sentence. From `QuantityProps`. |
+| `id` | `string` | — | Makes the quantity referable: `<Ref to>` stands for it elsewhere. Needed only for a quantity used more than once. From `QuantityProps`. |
+| `unit` | `string` | — | A label written after the number - "min", "pcs", "€". Never converted and never checked; the calculation does no unit algebra. From `QuantityProps`. |
+| `format` | `"percent"` | — | `percent` presents a plain ratio as per cent: 0.916 is shown as 91.6 %. The quantity stays a ratio in every operation. From `QuantityProps`. |
+| `decimals` | `number` | — | Fixed number of fraction digits as shown. Rounding happens only in presentation; every operation uses the full value. Without it: one digit for a percentage, at most two for a derived number, and a given as it was given. From `QuantityProps`. |
+| `target` | `number` | — | The value this quantity is meant to reach - missed, never violated. From `QuantityProps`. |
+| `limits` | `readonly Limit[]` | — | Bounds the quantity is assessed against, through core's `assess()`. From `QuantityProps`. |
+| `explanation` | `string` | — | A sentence of plain text beside the line: why the quantity is here, or what it means. From `QuantityProps`. |
+| `aside` | `ReactNode` | — | Content of the caller's own beside the line - a sparkline, a link. It never takes part in the calculation. From `QuantityProps`. |
+
+##### `RefProps`
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `to` (required) | `string` | — | The `id` of the quantity this reference stands for. |
+
+### Chain
+
+A sheet read top to bottom: each line worked into the value before it, and interims naming the value where they stand.
+
+```ts
+import { Chain, Plus, Minus, Times, DividedBy, Interim } from "@umriss-ui/calculation";
+```
+
+Demo page: https://romanhaendler.github.io/umriss-ui/calculation/#/chain
+
+#### Examples
+
+##### A payslip
+
+```tsx
+import { Calculation, Chain, Given, Interim, Minus, Plus, Product, Ref, Sum } from "@umriss-ui/calculation";
+
+/* A chain as a payslip reads: the gross salary, each deduction on a line of
+   its own with its minus, and the net salary only once they all stand. A
+   chain in view never folds - it is the working itself.
+
+   What a reader should see only on request goes into ONE line as a tree: the
+   four social security contributions are a `<Sum>` held by a `<Minus>`. The
+   line shows their total and the formula it hides; a click opens the four
+   beneath it, each computed from its rate and the gross salary. */
+
+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>
+  );
+}
+```
+
+##### Net weight
+
+```tsx
+import { Calculation, Chain, Given, Interim, Minus } from "@umriss-ui/calculation";
+
+/* The simplest chain: a first quantity with no operator, lines that take
+   something away, and an `<Interim>` that names the value. `<Minus>` and
+   `<Plus>` take a label and a value directly - a given written in place. */
+export default function NetWeight() {
+  return (
+    <Calculation aria-label="Net weight, delivery 4471">
+      <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>
+  );
+}
+```
+
+##### The cost of a shift
+
+```tsx
+import { Calculation, Chain, Given, Interim, Minus, Plus } from "@umriss-ui/calculation";
+
+/* A flat chain of cost items, plus and minus mixed: a credit for energy fed
+   back is taken away where it stands. Written as a tree this would be one
+   `<Sum>` whose line repeats all seven names; as a chain every item is a line
+   of its own, and the interim is the sum a reader looks for. */
+export default function ShiftCost() {
+  return (
+    <Calculation aria-label="Cost of the early shift, line 2">
+      <Chain>
+        <Given label="Operators" value={1152} unit="€" decimals={2} />
+        <Plus label="Shift supervisor" value={264} unit="€" decimals={2} />
+        <Plus label="Energy" value={418.4} unit="€" decimals={2} />
+        <Plus label="Compressed air" value={96.2} unit="€" decimals={2} />
+        <Plus label="Tooling wear" value={185} unit="€" decimals={2} />
+        <Plus label="Cleaning" value={48} unit="€" decimals={2} />
+        <Minus label="Energy fed back" value={37.6} unit="€" decimals={2} />
+        <Interim label="Cost of the shift" unit="€" decimals={2} />
+      </Chain>
+    </Calculation>
+  );
+}
+```
+
+##### Fifteen items from data
+
+```tsx
+import { Calculation, Chain, Given, Interim, Plus } from "@umriss-ui/calculation";
+
+/* `.map` over data inside a chain: each cost item becomes a `<Plus>`, and all
+   fifteen stand in view above their interim. Where only the total should show
+   until a reader asks, the items go into one line as a `<Sum>` instead - as
+   the payslip does with its contributions; folded, such a line says how many
+   operands it holds rather than a formula of fifteen terms. */
+
+const ITEMS = [
+  ["Steel sheet", 412.8],
+  ["Tube 40×2", 186.4],
+  ["Flat bar", 94.1],
+  ["Screws M8", 22.6],
+  ["Nuts M8", 9.8],
+  ["Washers", 4.2],
+  ["Hinges", 61.5],
+  ["Gas springs", 88],
+  ["Seals", 17.3],
+  ["Powder coating", 143.9],
+  ["Primer", 38.5],
+  ["Labels", 6.4],
+  ["Packaging", 29.7],
+  ["Pallet", 14],
+  ["Freight", 120],
+] as const;
+
+export default function FifteenItems() {
+  const [[firstName, firstAmount], ...rest] = ITEMS;
+  return (
+    <Calculation aria-label="Bought-in cost, order A-2052">
+      <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="Bought-in cost" unit="€" decimals={2} />
+      </Chain>
+    </Calculation>
+  );
+}
+```
+
+##### Mark-up and VAT
+
+```tsx
+import { Calculation, Chain, Given, Interim, Plus, Times } from "@umriss-ui/calculation";
+
+/* A chain has no precedence: every line works into the value before it. So a
+   `<Times>` stands alone between two named values - directly after an
+   interim and directly before the next. Writing it after a `<Plus>` fails on
+   the first render; nobody multiplies a number they have not seen. */
+export default function MarkUpAndVat() {
+  return (
+    <Calculation aria-label="Price of a spare part">
+      <Chain>
+        <Given label="Cost price" value={148.2} unit="€" decimals={2} />
+        <Plus label="Handling" value={12} unit="€" decimals={2} />
+        <Interim label="Cost with handling" 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>
+  );
+}
+```
+
+##### A chain inside a tree
+
+```tsx
+import { Calculation, Chain, Given, Interim, Minus, Plus, Quotient, Ref } from "@umriss-ui/calculation";
+
+/* The two forms mix. Here a quotient's numerator is a chain: the net output of
+   a line, from what it made to what could be shipped. As an operand the chain
+   folds and stands for its last interim; opened, it stands whole beneath that
+   line, indented, every interim in view. The denominator is the chain's own
+   first line, referred to by its id. */
+export default function ChainInATree() {
+  return (
+    <Calculation aria-label="Shipping yield, line 4">
+      <Quotient label="Shipping yield" format="percent" target={0.97}>
+        <Chain>
+          <Given id="made" label="Parts made" value={2400} unit="pcs" />
+          <Minus label="Scrap" value={41} unit="pcs" />
+          <Minus label="Held for inspection" value={26} unit="pcs" />
+          <Plus label="Released after rework" value={18} unit="pcs" />
+          <Interim label="Parts shipped" unit="pcs" />
+        </Chain>
+        <Ref to="made" />
+      </Quotient>
+    </Calculation>
+  );
+}
+```
+
+##### An energy balance with limits
+
+```tsx
+import { Calculation, Chain, Given, Interim, Minus, Plus } from "@umriss-ui/calculation";
+
+/* Interims take targets and limits like any quantity. The balance of a hall:
+   what came in, what went out, and what is left unaccounted for - a number
+   that should be small. Its limit is assessed; the verdict stands beneath it
+   as a word. */
+export default function EnergyBalance() {
+  return (
+    <Calculation aria-label="Energy balance, hall 2, week 12">
+      <Chain>
+        <Given label="Grid supply" value={48200} unit="kWh" />
+        <Plus label="Photovoltaics" value={6150} unit="kWh" />
+        <Interim label="Energy in" unit="kWh" />
+        <Minus label="Presses" value={31480} unit="kWh" />
+        <Minus label="Compressed air" value={9820} unit="kWh" />
+        <Minus label="Heating and ventilation" value={8870} unit="kWh" />
+        <Minus label="Lighting" value={2210} unit="kWh" />
+        <Interim
+          label="Unaccounted for"
+          unit="kWh"
+          limits={[
+            { value: 1500, side: "upper", severity: "warning" },
+            { value: 3000, side: "upper", severity: "alarm" },
+          ]}
+        />
+      </Chain>
+    </Calculation>
+  );
+}
+```
+
+#### API
+
+##### `ChainProps`
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `children` | `ReactNode` | — | The operands, top to bottom: a first quantity with no operator, then `Plus`, `Minus`, `Times` and `DividedBy` with their operands and `Interim`s naming the value where they stand. The last line is an `Interim`; a `Times` or `DividedBy` stands alone between two named values. |
+
+##### `ChainOperandProps`
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `label` | `string` | — | The operand's name, where the line is a given written in place. Left out where the line holds a quantity as its child. |
+| `value` | `number \| null` | — | The operand's number, where the line is a given written in place. Absent as for a `Given`: the line and every interim after it are absent, with the reason. |
+| `children` | `ReactNode` | — | Instead of `label` and `value`: exactly one quantity - a tree, a `<Ref>` or a `<Chain>`. |
+| `source` | `string` | — | Where the number came from: a system, a report, a person. From `GivenProps`. |
+| `asOf` | `Date \| number` | — | When the number was true - not when it was fetched. From `GivenProps`. |
+| `ages` | `FreshnessAges` | — | The ages at which `asOf` turns stale and lost. With both, the given carries a freshness through core; with `asOf` alone, only the time. From `GivenProps`. |
+| `id` | `string` | — | Makes the quantity referable: `<Ref to>` stands for it elsewhere. Needed only for a quantity used more than once. From `QuantityProps`. |
+| `unit` | `string` | — | A label written after the number - "min", "pcs", "€". Never converted and never checked; the calculation does no unit algebra. From `QuantityProps`. |
+| `format` | `"percent"` | — | `percent` presents a plain ratio as per cent: 0.916 is shown as 91.6 %. The quantity stays a ratio in every operation. From `QuantityProps`. |
+| `decimals` | `number` | — | Fixed number of fraction digits as shown. Rounding happens only in presentation; every operation uses the full value. Without it: one digit for a percentage, at most two for a derived number, and a given as it was given. From `QuantityProps`. |
+| `target` | `number` | — | The value this quantity is meant to reach - missed, never violated. From `QuantityProps`. |
+| `limits` | `readonly Limit[]` | — | Bounds the quantity is assessed against, through core's `assess()`. From `QuantityProps`. |
+| `explanation` | `string` | — | A sentence of plain text beside the line: why the quantity is here, or what it means. From `QuantityProps`. |
+| `aside` | `ReactNode` | — | Content of the caller's own beside the line - a sparkline, a link. It never takes part in the calculation. From `QuantityProps`. |
+
+##### `QuantityProps`
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `label` (required) | `string` | — | What the quantity is called. It stands on its line, wherever it is an operand, and in the accessible sentence. |
+| `id` | `string` | — | Makes the quantity referable: `<Ref to>` stands for it elsewhere. Needed only for a quantity used more than once. |
+| `unit` | `string` | — | A label written after the number - "min", "pcs", "€". Never converted and never checked; the calculation does no unit algebra. |
+| `format` | `"percent"` | — | `percent` presents a plain ratio as per cent: 0.916 is shown as 91.6 %. The quantity stays a ratio in every operation. |
+| `decimals` | `number` | — | Fixed number of fraction digits as shown. Rounding happens only in presentation; every operation uses the full value. Without it: one digit for a percentage, at most two for a derived number, and a given as it was given. |
+| `target` | `number` | — | The value this quantity is meant to reach - missed, never violated. |
+| `limits` | `readonly Limit[]` | — | Bounds the quantity is assessed against, through core's `assess()`. |
+| `explanation` | `string` | — | A sentence of plain text beside the line: why the quantity is here, or what it means. |
+| `aside` | `ReactNode` | — | Content of the caller's own beside the line - a sparkline, a link. It never takes part in the calculation. |
+
+#### Why it is like this
+
+##### No precedence, and a times alone
+
+A chain works every line into the value before it, strictly in order - the way a costing sheet is read. There is no precedence, so `a + b × c` would mean `(a + b) × c` here and `a + (b × c)` in a reader's head. Rather than explain that, the chain makes it unwritable: a `<Times>` or `<DividedBy>` stands alone between two named values, and anything else fails on the first render. Nobody multiplies a number they have not seen.
+
+##### A chain does not fold
+
+A chain is the working itself - folded to its interims it would only repeat the numbers and hide the steps it exists to show. So a chain in view stands open, and what a reader should see only on request goes into one line as a tree: a `<Sum>` of contributions held by a `<Minus>` folds like any tree, and opens beneath its line. Whoever writes the chain decides, line by line, what is always in view.
+
+##### Only an interim shows the running value
+
+A line shows its own number. A running value without a name is a number nobody can quote; where you want to see it, set an `<Interim>`. See `docs/adr/0028-a-calculation-is-a-tree-or-a-chain.md`.
+
+### Given
+
+The numbers a calculation starts from: where they came from, how old they are, and the language they are read in.
+
+```ts
+import { Given } from "@umriss-ui/calculation";
+```
+
+Demo page: https://romanhaendler.github.io/umriss-ui/calculation/#/given
+
+#### Examples
+
+##### Where a number came from
+
+```tsx
+import { useState } from "react";
+import { Sparkline } from "@umriss-ui/core";
+import { Calculation, Given, Quotient } from "@umriss-ui/calculation";
+
+/* A given can say where it came from and when it was true. With `ages` it
+   carries a freshness, as a Stat does: fresh, stale or lost - beside the
+   number, never instead of its verdict. `explanation` is a sentence of plain
+   text, and `aside` holds content of your own - here the last shifts'
+   scrap as a sparkline. Neither takes part in the calculation. */
+
+const AGES = { stale: 15 * 60_000, lost: 60 * 60_000 };
+
+export default function WhereItCameFrom() {
+  const [now] = useState(() => Date.now());
+  return (
+    <Calculation aria-label="Scrap rate, press 3">
+      <Quotient
+        label="Scrap rate"
+        format="percent"
+        limits={[{ value: 0.03, side: "upper", severity: "warning" }]}
+        explanation="Scrapped parts over every part the press made."
+        aside={<Sparkline data={[0.021, 0.024, 0.019, 0.028, 0.033, 0.036]} aria-hidden="true" />}
+      >
+        <Given label="Scrapped parts" value={18} unit="pcs" source="Quality station QS-2" asOf={now - 4 * 60_000} ages={AGES} />
+        <Given label="Parts made" value={512} unit="pcs" source="Press counter" asOf={now - 22 * 60_000} ages={AGES} />
+      </Quotient>
+    </Calculation>
+  );
+}
+```
+
+##### An as-of time without ages
+
+```tsx
+import { Calculation, Given, Product } from "@umriss-ui/calculation";
+
+/* `asOf` alone states when the number was true, as a time. With `ages` as
+   well, the given carries a freshness through core, as a `Stat` does - the
+   library has no default ages, because "stale" at a furnace means something
+   else than on a monthly report. */
+export default function AsOf() {
+  return (
+    <Calculation aria-label="Value of the stock, bar steel">
+      <Product label="Value of the stock" unit="€" decimals={2}>
+        <Given label="Bar steel in stock" value={18.4} unit="t" source="Stocktaking" asOf={new Date(2026, 2, 13, 16, 0)} />
+        <Given label="Price" value={812} unit="€/t" source="Price list 2026-Q1" asOf={new Date(2026, 0, 2, 8, 0)} />
+      </Product>
+    </Calculation>
+  );
+}
+```
+
+##### In German
+
+```tsx
+import { LanguageProvider } from "@umriss-ui/core";
+import { GERMAN_FORMATS, GERMAN_WORDING } from "@umriss-ui/core/wording/de";
+import { Calculation, Chain, Given, Interim, Plus, Product, Ref } from "@umriss-ui/calculation";
+
+/* The operator words, the reasons for absence, the approximation note and the
+   disclosure labels are core's wording, English by default and German behind
+   the subpath (ADR-0019). The numbers follow the formats: 1.840,00 €. The
+   labels are yours and stay as you write them. */
+export default function InGerman() {
+  return (
+    <LanguageProvider wording={GERMAN_WORDING} formats={GERMAN_FORMATS}>
+      <Calculation aria-label="Materialkosten, Auftrag A-2041">
+        <Chain>
+          <Given id="mek" label="Materialeinzelkosten" value={1840} unit="€" decimals={2} />
+          <Plus>
+            <Product label="Materialgemeinkosten" unit="€" decimals={2}>
+              <Given label="Zuschlagssatz" value={0.12} format="percent" />
+              <Ref to="mek" />
+            </Product>
+          </Plus>
+          <Interim label="Materialkosten" unit="€" decimals={2} />
+        </Chain>
+      </Calculation>
+    </LanguageProvider>
+  );
+}
+```
+
+#### API
+
+##### `GivenProps`
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `value` (required) | `number \| null \| undefined` | — | The number the calculation starts from. Absent (`null`, `undefined`, not finite) makes every quantity that depends on it absent, with the reason - never zero. |
+| `source` | `string` | — | Where the number came from: a system, a report, a person. |
+| `asOf` | `Date \| number` | — | When the number was true - not when it was fetched. |
+| `ages` | `FreshnessAges` | — | The ages at which `asOf` turns stale and lost. With both, the given carries a freshness through core; with `asOf` alone, only the time. |
+| `label` (required) | `string` | — | What the quantity is called. It stands on its line, wherever it is an operand, and in the accessible sentence. From `QuantityProps`. |
+| `id` | `string` | — | Makes the quantity referable: `<Ref to>` stands for it elsewhere. Needed only for a quantity used more than once. From `QuantityProps`. |
+| `unit` | `string` | — | A label written after the number - "min", "pcs", "€". Never converted and never checked; the calculation does no unit algebra. From `QuantityProps`. |
+| `format` | `"percent"` | — | `percent` presents a plain ratio as per cent: 0.916 is shown as 91.6 %. The quantity stays a ratio in every operation. From `QuantityProps`. |
+| `decimals` | `number` | — | Fixed number of fraction digits as shown. Rounding happens only in presentation; every operation uses the full value. Without it: one digit for a percentage, at most two for a derived number, and a given as it was given. From `QuantityProps`. |
+| `target` | `number` | — | The value this quantity is meant to reach - missed, never violated. From `QuantityProps`. |
+| `limits` | `readonly Limit[]` | — | Bounds the quantity is assessed against, through core's `assess()`. From `QuantityProps`. |
+| `explanation` | `string` | — | A sentence of plain text beside the line: why the quantity is here, or what it means. From `QuantityProps`. |
+| `aside` | `ReactNode` | — | Content of the caller's own beside the line - a sparkline, a link. It never takes part in the calculation. From `QuantityProps`. |
+
+## In practice
+
+What a calculation does when the numbers are not what they should be, and two figures worked in full.
+
+### What can go wrong
+
+A missing number, a division by zero, rounded figures that do not add up, and an alarm folded out of sight.
+
+```ts
+import { Calculation } from "@umriss-ui/calculation";
+```
+
+Demo page: https://romanhaendler.github.io/umriss-ui/calculation/#/what-can-go-wrong
+
+#### Examples
+
+##### A missing number
+
+```tsx
+import { Calculation, Difference, Given, Product, Quotient, Ref } from "@umriss-ui/calculation";
+
+/* The downtime has not been booked yet. It shows as missing - and so does
+   every figure that depends on it, each with the reason, up to the result.
+   Nothing is carried on as zero: an OEE computed with no downtime would be a
+   number, and a wrong one. */
+export default function Missing() {
+  return (
+    <Calculation aria-label="OEE, late shift">
+      <Product label="OEE" format="percent" target={0.85}>
+        <Quotient label="Availability" format="percent">
+          <Difference id="runtime" label="Run time" unit="min">
+            <Given id="planned" label="Planned production time" value={450} unit="min" />
+            <Given label="Downtime" value={null} unit="min" />
+          </Difference>
+          <Ref to="planned" />
+        </Quotient>
+        <Quotient label="Performance" format="percent">
+          <Product label="Ideal run time" unit="min">
+            <Given label="Ideal cycle time" value={0.8} unit="min/pc" />
+            <Given id="total" label="Total count" value={455} unit="pcs" />
+          </Product>
+          <Ref to="runtime" />
+        </Quotient>
+        <Quotient label="Quality" format="percent">
+          <Given label="Good count" value={441} unit="pcs" />
+          <Ref to="total" />
+        </Quotient>
+      </Product>
+    </Calculation>
+  );
+}
+```
+
+##### A division by zero
+
+```tsx
+import { Calculation, Given, Quotient, Sum } from "@umriss-ui/calculation";
+
+/* A machine that did not run has no output per hour - not zero, and not
+   infinity. The quotient is absent with its own reason, and so is everything
+   that depends on it. */
+export default function DivisionByZero() {
+  return (
+    <Calculation aria-label="Output per hour, cell 7">
+      <Sum label="Output per hour, cell 7" unit="pcs/h">
+        <Quotient label="Robot A" unit="pcs/h">
+          <Given label="Parts, robot A" value={412} unit="pcs" />
+          <Given label="Hours run, robot A" value={7.5} unit="h" />
+        </Quotient>
+        <Quotient label="Robot B" unit="pcs/h">
+          <Given label="Parts, robot B" value={0} unit="pcs" />
+          <Given label="Hours run, robot B" value={0} unit="h" />
+        </Quotient>
+      </Sum>
+    </Calculation>
+  );
+}
+```
+
+##### When the rounded figures do not add up
+
+```tsx
+import { Calculation, Given, Product, Quotient, Sum } from "@umriss-ui/calculation";
+
+/* Every operation uses the full value; rounding happens only on the screen.
+   Three shares of 33.3 % each add up to 100 % - not to the 99.9 % a reader
+   gets from the rounded figures. The line says so with "≈" and a note,
+   instead of leaving the reader to find it. */
+export default function Rounding() {
+  return (
+    <Calculation aria-label="Shares of the shift">
+      <Sum label="All three lines" format="percent">
+        {["Line 1", "Line 2", "Line 3"].map((line) => (
+          <Quotient key={line} label={`Share of ${line}`} format="percent">
+            <Product label={`Hours on ${line}`} unit="h">
+              <Given label="Machines" value={2} />
+              <Given label="Hours each" value={4} unit="h" />
+            </Product>
+            <Given label="Hours in the shift" value={24} unit="h" />
+          </Quotient>
+        ))}
+      </Sum>
+    </Calculation>
+  );
+}
+```
+
+##### A limit violated deep inside
+
+```tsx
+import { Calculation, Chain, Given, Interim, Plus, Product } from "@umriss-ui/calculation";
+
+/* The scrap rate on line 2 is beyond its alarm limit, inside a folded line.
+   The folded line says so quietly - "Inside: Alarm limit exceeded" - without
+   taking on the alarm's colour itself: its own number is not the one in
+   alarm. Open it to find the line that is. */
+export default function LimitInside() {
+  const scrapLimits = [{ value: 0.03, side: "upper" as const, severity: "alarm" as const }];
+  return (
+    <Calculation aria-label="Scrap cost, hall 1">
+      <Chain>
+        <Product label="Scrap cost, line 1" unit="€" decimals={2}>
+          <Given label="Scrap rate, line 1" value={0.018} format="percent" limits={scrapLimits} />
+          <Given label="Material, line 1" value={24800} unit="€" decimals={2} />
+        </Product>
+        <Plus>
+          <Product label="Scrap cost, line 2" unit="€" decimals={2}>
+            <Given label="Scrap rate, line 2" value={0.041} format="percent" limits={scrapLimits} />
+            <Given label="Material, line 2" value={19650} unit="€" decimals={2} />
+          </Product>
+        </Plus>
+        <Interim label="Scrap cost, hall 1" unit="€" decimals={2} />
+      </Chain>
+    </Calculation>
+  );
+}
+```
+
+### Worked examples
+
+The cost per piece of a production order and the OEE of a hall - some fifty quantities each, from data.
+
+```ts
+import { Calculation, Chain, Given, Ref } from "@umriss-ui/calculation";
+```
+
+Demo page: https://romanhaendler.github.io/umriss-ui/calculation/#/worked-examples
+
+#### Examples
+
+##### The cost per piece of a production order
+
+```tsx
+import { Calculation, Chain, Given, Interim, Plus, Product, Quotient, Ref, Sum, Times } from "@umriss-ui/calculation";
+
+/* Everything at once, as an order is actually costed. The bill of material
+   and the routing come from data; each becomes a tree of its own - quantity
+   times price, minutes times the machine's rate per minute - and the two
+   trees are lines of the costing sheet. Setup is spread over the lot size,
+   the scrap surcharge and the overheads refer back to named interims, and the
+   sheet ends in a net and a gross price.
+
+   The scrap rate is three days old: its line says so, beside the number, and
+   keeps its verdict. Some fifty quantities: the sheet itself stands open, a
+   dozen lines, and every tree in it waits folded until a reader asks. */
+
+const BILL_OF_MATERIAL = [
+  { part: "Steel sheet 2 mm", quantity: 1.84, unit: "kg", price: 1.35 },
+  { part: "Tube 40×2", quantity: 0.62, unit: "m", price: 4.1 },
+  { part: "Hinge", quantity: 2, unit: "pcs", price: 1.9 },
+  { part: "Gas spring", quantity: 1, unit: "pcs", price: 6.4 },
+  { part: "Screw M8×20", quantity: 8, unit: "pcs", price: 0.07 },
+  { part: "Powder, RAL 7016", quantity: 0.21, unit: "kg", price: 9.8 },
+];
+
+const ROUTING = [
+  { station: "Laser cutting", minutes: 2.4, rate: 96 },
+  { station: "Bending", minutes: 1.8, rate: 72 },
+  { station: "Welding", minutes: 4.2, rate: 84 },
+  { station: "Powder coating", minutes: 1.5, rate: 60 },
+  { station: "Assembly", minutes: 3.0, rate: 54 },
+];
+
+const AGES = { stale: 24 * 3_600_000, lost: 14 * 24 * 3_600_000 };
+
+export default function CostPerPiece() {
+  return (
+    <Calculation aria-label="Cost per piece, order A-2041, lot of 250">
+      <Chain>
+        <Sum id="material" label="Direct material" unit="€" decimals={2}>
+          {BILL_OF_MATERIAL.map((line) => (
+            <Product key={line.part} label={line.part} unit="€" decimals={2}>
+              <Given label={`Quantity, ${line.part}`} value={line.quantity} unit={line.unit} />
+              <Given label={`Price, ${line.part}`} value={line.price} unit={`€/${line.unit}`} />
+            </Product>
+          ))}
+        </Sum>
+        <Plus>
+          <Product label="Material overhead" unit="€" decimals={2}>
+            <Given label="Material overhead rate" value={0.12} format="percent" source="Cost centre accounting 2026" />
+            <Ref to="material" />
+          </Product>
+        </Plus>
+        <Interim label="Material cost" unit="€" decimals={2} />
+        <Plus>
+          <Sum label="Machine time" unit="€" decimals={2}>
+            {ROUTING.map((step) => (
+              <Product key={step.station} label={step.station} unit="€" decimals={2}>
+                <Given label={`Minutes, ${step.station.toLowerCase()}`} value={step.minutes} unit="min" decimals={1} />
+                <Quotient label={`Rate per minute, ${step.station.toLowerCase()}`} unit="€/min" decimals={3}>
+                  <Given label={`Machine hour rate, ${step.station.toLowerCase()}`} value={step.rate} unit="€/h" />
+                  <Given label="Minutes per hour" value={60} unit="min/h" />
+                </Quotient>
+              </Product>
+            ))}
+          </Sum>
+        </Plus>
+        <Plus>
+          <Quotient label="Setup per piece" unit="€" decimals={2}>
+            <Product label="Setup cost" unit="€" decimals={2}>
+              <Given label="Setup time" value={1.5} unit="h" />
+              <Given label="Setup rate" value={78} unit="€/h" />
+            </Product>
+            <Given label="Lot size" value={250} unit="pcs" />
+          </Quotient>
+        </Plus>
+        <Interim id="production" label="Production cost" unit="€" decimals={2} />
+        <Plus>
+          <Product label="Scrap surcharge" unit="€" decimals={2}>
+            <Given
+              label="Scrap rate"
+              value={0.032}
+              format="percent"
+              source="MES, last 30 days"
+              asOf={new Date(2026, 2, 14, 6, 0)}
+              ages={AGES}
+            />
+            <Ref to="production" />
+          </Product>
+        </Plus>
+        <Plus>
+          <Product label="Administration and sales overhead" unit="€" decimals={2}>
+            <Given label="Overhead rate" value={0.14} format="percent" source="Cost centre accounting 2026" />
+            <Ref to="production" />
+          </Product>
+        </Plus>
+        <Interim label="Cost price" unit="€" decimals={2} />
+        <Times label="Profit mark-up" value={1.1} decimals={2} />
+        <Interim label="Net price per piece" unit="€" decimals={2} target={85} />
+        <Times label="VAT factor" value={1.19} />
+        <Interim label="Gross price per piece" unit="€" decimals={2} />
+      </Chain>
+    </Calculation>
+  );
+}
+```
+
+##### OEE of a hall, weighted by planned time
+
+```tsx
+import { Calculation, Difference, Given, Product, Quotient, Ref, Sum } from "@umriss-ui/calculation";
+
+/* Three lines, each with its own OEE derived from its own counts, weighted by
+   how long each was planned to run. A tree three levels deep, built from
+   data, each line's quantities named once and referred to by id - and line
+   C's downtime has not been booked. Its OEE is missing, so is
+   the hall's, and every line on the way says why; lines A and B stand as
+   they are. Nothing is averaged over a gap as if it were zero. */
+
+interface Line {
+  name: string;
+  planned: number;
+  downtime: number | null;
+  idealCycle: number;
+  total: number;
+  good: number;
+}
+
+const LINES: Line[] = [
+  { name: "A", planned: 450, downtime: 38, idealCycle: 0.8, total: 480, good: 461 },
+  { name: "B", planned: 450, downtime: 62, idealCycle: 1.2, total: 300, good: 291 },
+  { name: "C", planned: 240, downtime: null, idealCycle: 0.5, total: 402, good: 395 },
+];
+
+function lineOee(line: Line) {
+  const n = line.name;
+  return (
+    <Product key={n} label={`Weighted OEE, line ${n}`} unit="min">
+      <Product label={`OEE, line ${n}`} format="percent">
+        <Quotient label={`Availability, line ${n}`} format="percent">
+          <Difference id={`runtime-${n}`} label={`Run time, line ${n}`} unit="min">
+            <Given id={`planned-${n}`} label={`Planned time, line ${n}`} value={line.planned} unit="min" />
+            <Given label={`Downtime, line ${n}`} value={line.downtime} unit="min" source="Shift log" />
+          </Difference>
+          <Ref to={`planned-${n}`} />
+        </Quotient>
+        <Quotient label={`Performance, line ${n}`} format="percent">
+          <Product label={`Ideal run time, line ${n}`} unit="min">
+            <Given label={`Ideal cycle time, line ${n}`} value={line.idealCycle} unit="min/pc" />
+            <Given id={`total-${n}`} label={`Total count, line ${n}`} value={line.total} unit="pcs" />
+          </Product>
+          <Ref to={`runtime-${n}`} />
+        </Quotient>
+        <Quotient label={`Quality, line ${n}`} format="percent">
+          <Given label={`Good count, line ${n}`} value={line.good} unit="pcs" />
+          <Ref to={`total-${n}`} />
+        </Quotient>
+      </Product>
+      <Ref to={`planned-${n}`} />
+    </Product>
+  );
+}
+
+export default function HallOee() {
+  return (
+    <Calculation aria-label="OEE of hall 2, early shift">
+      <Quotient label="OEE, hall 2" format="percent" target={0.8}>
+        <Sum label="Weighted OEE, all lines" unit="min">
+          {LINES.map(lineOee)}
+        </Sum>
+        <Sum label="Planned time, all lines" unit="min">
+          {LINES.map((line) => (
+            <Ref key={line.name} to={`planned-${line.name}`} />
+          ))}
+        </Sum>
+      </Quotient>
+    </Calculation>
+  );
+}
+```