Given

The numbers a calculation starts from (inputs, leaves): where they came from, when they were true, and whether they are still fresh.

import { Given } from "@umriss-ui/calculation";

A given with asOf and ages carries a freshness through core, as a Stat does – beside the number, never instead of its verdict. There are no default ages.

The operator words, the reasons for absence and the number formats are core's wording; German comes from @umriss-ui/core/wording/de (ADR-0019).

Examples

Say where a number came from

source, asOf and ages give a given its origin and freshness; explanation and aside stand beside a line without taking part.

import { useState } from "react";
import { Sparkline } from "@umriss-ui/core";
import { Calculation, Given, Quotient } from "@umriss-ui/calculation";

const AGES = { stale: 15 * 60_000, lost: 60 * 60_000 };

export default function WhereItCameFrom() {
  const [now] = useState(() => Date.now());
  return (
    <Calculation aria-label="Error rate of Checkout, last five minutes">
      <Quotient
        label="Error rate, Checkout"
        format="percent"
        decimals={2}
        limits={[{ value: 0.01, side: "upper", severity: "warning" }]}
        explanation="Failed requests over every request in the last five minutes."
        aside={<Sparkline data={[0.0012, 0.0015, 0.0011, 0.0019, 0.0264, 0.0287]} aria-hidden="true" />}
      >
        <Given label="Failed requests" value={118} unit="requests" source="Load balancer logs" asOf={now - 4 * 60_000} ages={AGES} />
        <Given label="Requests" value={4390} unit="requests" source="Request counter" asOf={now - 22 * 60_000} ages={AGES} />
      </Quotient>
    </Calculation>
  );
}

State when a number was true

asOf alone shows the time a number held; there are no default ages, because stale means different things on different screens.

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

export default function AsOf() {
  return (
    <Calculation aria-label="Licence cost, design tool, March">
      <Product label="Licence cost, March" unit="€" decimals={2}>
        <Given label="Seats in use" value={12} unit="seats" source="Admin console" asOf={new Date(2026, 2, 13, 16, 0)} />
        <Given label="Price per seat" value={45} unit="€/seat" decimals={2} source="Contract with Nimbrel Software" asOf={new Date(2026, 0, 2, 8, 0)} />
      </Product>
    </Calculation>
  );
}

Read in German

Operator words, reasons and number formats come from core's LanguageProvider (ADR-0019); your labels stay as you write them.

import { LanguageProvider } from "@umriss-ui/core";
import { GERMAN_FORMATS, GERMAN_WORDING } from "@umriss-ui/core/wording/de";
import { Calculation, Chain, Given, Interim, Minus, Product, Ref } from "@umriss-ui/calculation";

export default function InGerman() {
  return (
    <LanguageProvider wording={GERMAN_WORDING} formats={GERMAN_FORMATS}>
      <Calculation aria-label="Rechnung INV-26-0317, Messestand">
        <Chain>
          <Given id="stand" label="Messestand, 3 Tage" value={12400} unit="€" decimals={2} />
          <Minus>
            <Product label="Rabatt" unit="€" decimals={2}>
              <Given label="Rabattsatz" value={0.05} format="percent" />
              <Ref to="stand" />
            </Product>
          </Minus>
          <Interim label="Nettobetrag" unit="€" decimals={2} />
        </Chain>
      </Calculation>
    </LanguageProvider>
  );
}

Keyboard

The keys of Calculation apply here.

API

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

type Side = "upper" | "lower";

type Severity = "warning" | "alarm";

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