# Given

> Package `@umriss-ui/calculation`, version 0.40.0. Demo page: <https://romanhaendler.github.io/umriss-ui/calculation/given/>. Every page in one line: [llms.txt](https://romanhaendler.github.io/umriss-ui/calculation/llms.txt); every page in full: [llms-full.txt](https://romanhaendler.github.io/umriss-ui/calculation/llms-full.txt).

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

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

Demo page: https://romanhaendler.github.io/umriss-ui/calculation/given/

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](https://github.com/romanhaendler/umriss-ui/blob/main/docs/adr/0019-two-wordings-ship-english-is-the-default.md)).

## 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.

```tsx
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.

```tsx
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](https://github.com/romanhaendler/umriss-ui/blob/main/docs/adr/0019-two-wordings-ship-english-is-the-default.md)); your labels stay as you write them.

```tsx
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](https://romanhaendler.github.io/umriss-ui/calculation/calculation/#keyboard-calculation) apply here.

## API

### `GivenProps`

| Prop | Type | Default | Description |
|---|---|---|---|
| `value` *required* | `number \| null \| undefined \| `[`MetricValues`](https://romanhaendler.github.io/umriss-ui/calculation/given/#type-MetricValues) | — | The number the calculation starts from. Absent (`null`, `undefined`, not finite) makes every quantity that depends on it absent, with the reason - never zero. Where the calculation has `metrics`, an object with a number for each metric id instead; absence then stays in its metric.<br>Shown in: [Say where a number came from](https://romanhaendler.github.io/umriss-ui/calculation/given/#where-it-came-from), [State when a number was true](https://romanhaendler.github.io/umriss-ui/calculation/given/#as-of), [Read in German](https://romanhaendler.github.io/umriss-ui/calculation/given/#in-german) and 50 more |
| `source` | `string` | — | Where the number came from: a system, a report, a person.<br>Shown in: [Say where a number came from](https://romanhaendler.github.io/umriss-ui/calculation/given/#where-it-came-from), [State when a number was true](https://romanhaendler.github.io/umriss-ui/calculation/given/#as-of), [Staff movement as a chain (Metrics)](https://romanhaendler.github.io/umriss-ui/calculation/metrics/#staff-movement) and 8 more |
| `asOf` | `Date \| number` | — | When the number was true - not when it was fetched.<br>Shown in: [Say where a number came from](https://romanhaendler.github.io/umriss-ui/calculation/given/#where-it-came-from), [State when a number was true](https://romanhaendler.github.io/umriss-ui/calculation/given/#as-of), [The cost per stop of a day's tours (Worked examples)](https://romanhaendler.github.io/umriss-ui/calculation/worked-examples/#cost-per-tour) |
| `ages` | [`FreshnessAges`](https://romanhaendler.github.io/umriss-ui/calculation/given/#type-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.<br>Shown in: [Say where a number came from](https://romanhaendler.github.io/umriss-ui/calculation/given/#where-it-came-from), [The cost per stop of a day's tours (Worked examples)](https://romanhaendler.github.io/umriss-ui/calculation/worked-examples/#cost-per-tour) |
| `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`.<br>Shown in: [Say where a number came from](https://romanhaendler.github.io/umriss-ui/calculation/given/#where-it-came-from), [State when a number was true](https://romanhaendler.github.io/umriss-ui/calculation/given/#as-of), [Read in German](https://romanhaendler.github.io/umriss-ui/calculation/given/#in-german) and 50 more |
| `id` | `string` | — | Makes the quantity referable: `<Ref to>` stands for it elsewhere. Needed only for a quantity used more than once. From `QuantityProps`.<br>Shown in: [Read in German](https://romanhaendler.github.io/umriss-ui/calculation/given/#in-german), [The availability of a service (Installation)](https://romanhaendler.github.io/umriss-ui/calculation/installation/#availability), [Write a tree (Calculation)](https://romanhaendler.github.io/umriss-ui/calculation/calculation/#oee) and 10 more |
| `unit` | `string` | — | A label written after the number - "min", "pcs", "€". Never converted and never checked; the calculation does no unit algebra. From `QuantityProps`.<br>Shown in: [Say where a number came from](https://romanhaendler.github.io/umriss-ui/calculation/given/#where-it-came-from), [State when a number was true](https://romanhaendler.github.io/umriss-ui/calculation/given/#as-of), [Read in German](https://romanhaendler.github.io/umriss-ui/calculation/given/#in-german) and 42 more |
| `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`.<br>Shown in: [Say where a number came from](https://romanhaendler.github.io/umriss-ui/calculation/given/#where-it-came-from), [Read in German](https://romanhaendler.github.io/umriss-ui/calculation/given/#in-german), [The availability of a service (Installation)](https://romanhaendler.github.io/umriss-ui/calculation/installation/#availability) and 17 more |
| `decimals` | `number` | one digit for a percentage, at most two for a derived number, a given as it was given | Fixed number of fraction digits as shown. Rounding happens only in presentation; every operation uses the full value. From `QuantityProps`.<br>Shown in: [Say where a number came from](https://romanhaendler.github.io/umriss-ui/calculation/given/#where-it-came-from), [State when a number was true](https://romanhaendler.github.io/umriss-ui/calculation/given/#as-of), [Read in German](https://romanhaendler.github.io/umriss-ui/calculation/given/#in-german) and 29 more |
| `target` | `number` | — | The value this quantity is meant to reach - missed, never violated. From `QuantityProps`.<br>Shown in: [The availability of a service (Installation)](https://romanhaendler.github.io/umriss-ui/calculation/installation/#availability), [Write a tree (Calculation)](https://romanhaendler.github.io/umriss-ui/calculation/calculation/#oee), [Density (Calculation)](https://romanhaendler.github.io/umriss-ui/calculation/calculation/#density) and 6 more |
| `limits` | `readonly `[`Limit`](https://romanhaendler.github.io/umriss-ui/calculation/given/#type-Limit)`[]` | — | Bounds the quantity is assessed against, through core's `assess()`. From `QuantityProps`.<br>Shown in: [Say where a number came from](https://romanhaendler.github.io/umriss-ui/calculation/given/#where-it-came-from), [Density (Calculation)](https://romanhaendler.github.io/umriss-ui/calculation/calculation/#density), [Hold a figure to its limits (Tree)](https://romanhaendler.github.io/umriss-ui/calculation/tree/#limits) and 5 more |
| `explanation` | `string` | — | A sentence of plain text beside the line: why the quantity is here, or what it means. From `QuantityProps`.<br>Shown in: [Say where a number came from](https://romanhaendler.github.io/umriss-ui/calculation/given/#where-it-came-from), [A number one metric does not have (Metrics)](https://romanhaendler.github.io/umriss-ui/calculation/metrics/#not-recorded), [Staff movement as a chain (Metrics)](https://romanhaendler.github.io/umriss-ui/calculation/metrics/#staff-movement) and 2 more |
| `aside` | `ReactNode` | — | Content of the caller's own beside the line - a sparkline, a link. It never takes part in the calculation. From `QuantityProps`.<br>Shown in: [Say where a number came from](https://romanhaendler.github.io/umriss-ui/calculation/given/#where-it-came-from) |
| `emphasis` | `"strong" \| "muted"` | — | How much the line stands out among the others ([ADR-0049](https://github.com/romanhaendler/umriss-ui/blob/main/docs/adr/0049-a-sum-takes-rows-from-data.md)): `strong` to be read first, `muted` to recede - a muted line still counts in full. Not on the Result, which is already the heaviest line. From `QuantityProps`.<br>Shown in: [A stronger line (Calculation)](https://romanhaendler.github.io/umriss-ui/calculation/calculation/#a-stronger-line), [A quieter line (Calculation)](https://romanhaendler.github.io/umriss-ui/calculation/calculation/#a-quieter-line), [Emphasis inside a group (Calculation)](https://romanhaendler.github.io/umriss-ui/calculation/calculation/#emphasis-inside-a-group) |
| `rule` | `"above"` | — | `above` rules the line off from the ones before it, where a section starts that is not an interim. Not on the Result. From `QuantityProps`.<br>Shown in: [A rule above (Calculation)](https://romanhaendler.github.io/umriss-ui/calculation/calculation/#a-rule-above), [Emphasis inside a group (Calculation)](https://romanhaendler.github.io/umriss-ui/calculation/calculation/#emphasis-inside-a-group) |

### Types on this page

#### `MetricValues`

A given's numbers where the calculation has metrics: one per metric id,
`null` where the number is absent.

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

#### `FreshnessAges`

From `@umriss-ui/core`.

The two ages at which a value changes its state, in milliseconds. Both
bounds belong to the older state: exactly five minutes old is already
`stale`.

`alt <= lost` is the sensible order. Stated the other way round, the
harder statement still wins - the middle state simply falls away.

| Prop | Type | Default | Description |
|---|---|---|---|
| `stale` *required* | `number` | — | From this age on the value counts as stale, but keeps its verdict. |
| `lost` *required* | `number` | — | From this age on the connection counts as disconnected. |

#### `Limit`

From `@umriss-ui/core`.

A bound: a value, a side, a severity.

No tolerance band as input. A band is derived - two limits of equal
severity on opposite sides enclose one - and as an input type it would
force a `null` on one edge in the one-sided case.

| Prop | Type | Default | Description |
|---|---|---|---|
| `value` *required* | `number` | — | <br>Shown in: [Say where a number came from](https://romanhaendler.github.io/umriss-ui/calculation/given/#where-it-came-from), [Density (Calculation)](https://romanhaendler.github.io/umriss-ui/calculation/calculation/#density), [Hold a figure to its limits (Tree)](https://romanhaendler.github.io/umriss-ui/calculation/tree/#limits) and 3 more |
| `side` *required* | [`Side`](https://romanhaendler.github.io/umriss-ui/calculation/given/#type-Side)<br>`"upper" \| "lower"` | — | <br>Shown in: [Say where a number came from](https://romanhaendler.github.io/umriss-ui/calculation/given/#where-it-came-from), [Density (Calculation)](https://romanhaendler.github.io/umriss-ui/calculation/calculation/#density), [Hold a figure to its limits (Tree)](https://romanhaendler.github.io/umriss-ui/calculation/tree/#limits) and 3 more |
| `severity` *required* | [`Severity`](https://romanhaendler.github.io/umriss-ui/calculation/given/#type-Severity)<br>`"warning" \| "alarm"` | — | <br>Shown in: [Say where a number came from](https://romanhaendler.github.io/umriss-ui/calculation/given/#where-it-came-from), [Density (Calculation)](https://romanhaendler.github.io/umriss-ui/calculation/calculation/#density), [Hold a figure to its limits (Tree)](https://romanhaendler.github.io/umriss-ui/calculation/tree/#limits) and 3 more |

#### `Side`

From `@umriss-ui/core`.

Whether a limit is an upper or a lower bound.

```ts
type Side = "upper" | "lower";
```

#### `Severity`

From `@umriss-ui/core`.

How seriously a violation weighs: one severity that advises and one that
calls for action. Exactly two; for a third distinction one sets a
second limit.

```ts
type Severity = "warning" | "alarm";
```