@umriss-ui/calculation 0.6.1 → 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (7) hide show
  1. package/CHANGELOG.md +24 -0
  2. package/README.md +4 -0
  3. package/dist/calculation.css +1 -1
  4. package/dist/calculation.js +392 -391
  5. package/dist/index.d.ts +6 -1
  6. package/docs/llms-full.md +117 -39
  7. package/package.json +3 -3
package/dist/index.d.ts CHANGED
@@ -10,7 +10,7 @@ import { ReactNode } from 'react';
10
10
  operation it shows, the number cannot disagree with the lines above it.
11
11
  Every tree below the outermost statement starts folded and opens beneath
12
12
  the row that is clicked. */
13
- export declare function Calculation({ children, className, style, metrics, ...rest }: CalculationProps): JSX.Element;
13
+ export declare function Calculation({ children, className, style, metrics, density, ...rest }: CalculationProps): JSX.Element;
14
14
 
15
15
  /** `className` and `style` size and place the surface; every other attribute -
16
16
  `aria-label` first of all - lands on the list the surface holds. */
@@ -26,6 +26,11 @@ export declare interface CalculationProps extends Omit<HTMLAttributes<HTMLUListE
26
26
  metric's. A calculation with metrics only adds and subtracts, and
27
27
  assesses no target or limits. */
28
28
  metrics?: readonly Metric[];
29
+ /** `"compact"` sets the lines as close as a compact table's rows: smaller
30
+ type and less room above and below, under a finger still tall enough to
31
+ tap. Columns, folding and wording stay as they are.
32
+ @default the density of the `UmrissProvider`, else `"regular"` */
33
+ density?: "regular" | "compact";
29
34
  }
30
35
 
31
36
  /** A calculation read top to bottom, as on paper. */
package/docs/llms-full.md CHANGED
@@ -1,4 +1,4 @@
1
- # @umriss-ui/calculation 0.6.1
1
+ # @umriss-ui/calculation 0.7.0
2
2
 
3
3
  > React calculation view for data-dense applications - a derivation written as it is shown, evaluated by the library, folded and read line by line.
4
4
 
@@ -1492,6 +1492,48 @@ export default function EmphasisInsideAGroup() {
1492
1492
  }
1493
1493
  ```
1494
1494
 
1495
+ ##### Density
1496
+
1497
+ `density="compact"` sets one calculation as close as a compact table; an application that wants it dense everywhere says so once at the `UmrissProvider`, and a calculation's own `density` wins over it.
1498
+
1499
+ ```tsx
1500
+ import { Stack, Text, UmrissProvider } from "@umriss-ui/core";
1501
+ import { Calculation, Given, Sum } from "@umriss-ui/calculation";
1502
+
1503
+ function Downtime({ caption, density }: { caption: string; density?: "regular" | "compact" }) {
1504
+ return (
1505
+ <Stack gap={2}>
1506
+ <Text size="xs" tone="muted">
1507
+ {caption}
1508
+ </Text>
1509
+ <Calculation density={density} aria-label={`Downtime of Checkout in March, ${caption}`}>
1510
+ <Sum label="Downtime" unit="min" target={45}>
1511
+ <Sum label="Unplanned outages" unit="min">
1512
+ <Given label="Database failover" value={11} unit="min" />
1513
+ <Given label="Failed deployment" value={18} unit="min" />
1514
+ </Sum>
1515
+ <Given label="Maintenance window" value={24} unit="min" limits={[{ value: 20, side: "upper", severity: "warning" }]} />
1516
+ <Given label="Certificate renewal" value={12} unit="min" />
1517
+ </Sum>
1518
+ </Calculation>
1519
+ </Stack>
1520
+ );
1521
+ }
1522
+
1523
+ export default function Density() {
1524
+ return (
1525
+ <Stack gap={5}>
1526
+ <Downtime caption="Without a statement: regular" />
1527
+ <Downtime caption='density="compact"' density="compact" />
1528
+ <UmrissProvider density="compact">
1529
+ <Downtime caption="From the UmrissProvider: compact" />
1530
+ <Downtime caption='density="regular" under that provider: regular' density="regular" />
1531
+ </UmrissProvider>
1532
+ </Stack>
1533
+ );
1534
+ }
1535
+ ```
1536
+
1495
1537
  #### When to use something else
1496
1538
 
1497
1539
  - A single figure with its verdict, without the working → `Stat` from @umriss-ui/core
@@ -1518,8 +1560,9 @@ Name the calculation with `aria-label`, which lands on the list; without it a re
1518
1560
 
1519
1561
  | Prop | Type | Default | Description |
1520
1562
  |---|---|---|---|
1521
- | `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.<br>Shown in: [Two numbers and a sum](#/calculation/first-sum), [Write a tree](#/calculation/oee), [Write a chain](#/calculation/invoice) and 48 more |
1522
- | `metrics` | `readonly `[`Metric`](#/metrics/type-Metric)`[]` | — | Several numbers per quantity, side by side - headcount and full-time equivalents of the same teams ([ADR-0038](https://github.com/romanhaendler/umriss-ui/blob/main/docs/adr/0038-a-calculation-can-carry-several-metrics.md)). Every `value` is then an object with a number for each metric id; unit and places are the metric's. A calculation with metrics only adds and subtracts, and assesses no target or limits.<br>Shown in: [Rows of both signs with metrics (Rows from data)](#/rows-from-data/rows-of-both-signs-with-metrics), [Headcount and full-time equivalents (Metrics)](#/metrics/two-teams), [A number one metric does not have (Metrics)](#/metrics/not-recorded) and 4 more |
1563
+ | `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.<br>Shown in: [Two numbers and a sum](#/calculation/first-sum), [Write a tree](#/calculation/oee), [Write a chain](#/calculation/invoice) and 50 more |
1564
+ | `metrics` | `readonly `[`Metric`](#/metrics/type-Metric)`[]` | — | Several numbers per quantity, side by side - headcount and full-time equivalents of the same teams ([ADR-0038](https://github.com/romanhaendler/umriss-ui/blob/main/docs/adr/0038-a-calculation-can-carry-several-metrics.md)). Every `value` is then an object with a number for each metric id; unit and places are the metric's. A calculation with metrics only adds and subtracts, and assesses no target or limits.<br>Shown in: [Rows of both signs with metrics (Rows from data)](#/rows-from-data/rows-of-both-signs-with-metrics), [Headcount and full-time equivalents (Metrics)](#/metrics/two-teams), [A number one metric does not have (Metrics)](#/metrics/not-recorded) and 5 more |
1565
+ | `density` | `"regular" \| "compact"` | the density of the `UmrissProvider`, else `"regular"` | `"compact"` sets the lines as close as a compact table's rows: smaller type and less room above and below, under a finger still tall enough to tap. Columns, folding and wording stay as they are.<br>Shown in: [Density](#/calculation/density), [A dense staff report (Metrics)](#/metrics/compact-report) |
1523
1566
 
1524
1567
  Also takes every attribute of the rendered element – without `children`.
1525
1568
 
@@ -1747,15 +1790,15 @@ The keys of [Calculation](#/calculation/keyboard-calculation) apply here.
1747
1790
 
1748
1791
  | Prop | Type | Default | Description |
1749
1792
  |---|---|---|---|
1750
- | `children` | `ReactNode` | — | The operands, in order: quantities, givens and references.<br>Shown in: [Show a share against a target](#/tree/share-with-target), [Take several amounts away](#/tree/difference-of-three), [Multiply quantities with units](#/tree/product-with-units) and 40 more |
1751
- | `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: [Show a share against a target](#/tree/share-with-target), [Take several amounts away](#/tree/difference-of-three), [Multiply quantities with units](#/tree/product-with-units) and 48 more |
1793
+ | `children` | `ReactNode` | — | The operands, in order: quantities, givens and references.<br>Shown in: [Show a share against a target](#/tree/share-with-target), [Take several amounts away](#/tree/difference-of-three), [Multiply quantities with units](#/tree/product-with-units) and 42 more |
1794
+ | `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: [Show a share against a target](#/tree/share-with-target), [Take several amounts away](#/tree/difference-of-three), [Multiply quantities with units](#/tree/product-with-units) and 50 more |
1752
1795
  | `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: [Use a quantity twice](#/tree/used-twice), [The availability of a service (Installation)](#/installation/availability), [Write a tree (Calculation)](#/calculation/oee) and 10 more |
1753
- | `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: [Show a share against a target](#/tree/share-with-target), [Take several amounts away](#/tree/difference-of-three), [Multiply quantities with units](#/tree/product-with-units) and 41 more |
1796
+ | `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: [Show a share against a target](#/tree/share-with-target), [Take several amounts away](#/tree/difference-of-three), [Multiply quantities with units](#/tree/product-with-units) and 42 more |
1754
1797
  | `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: [Show a share against a target](#/tree/share-with-target), [Use a quantity twice](#/tree/used-twice), [Build operands from data](#/tree/from-data) and 17 more |
1755
1798
  | `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: [Multiply quantities with units](#/tree/product-with-units), [Build operands from data](#/tree/from-data), [Hold a figure to its limits](#/tree/limits) and 29 more |
1756
- | `target` | `number` | — | The value this quantity is meant to reach - missed, never violated. From `QuantityProps`.<br>Shown in: [Show a share against a target](#/tree/share-with-target), [The availability of a service (Installation)](#/installation/availability), [Write a tree (Calculation)](#/calculation/oee) and 5 more |
1757
- | `limits` | `readonly `[`Limit`](#type-Limit)`[]` | — | Bounds the quantity is assessed against, through core's `assess()`. From `QuantityProps`.<br>Shown in: [Hold a figure to its limits](#/tree/limits), [Hold an interim to its limits (Chain)](#/chain/error-budget), [Say where a number came from (Given)](#/given/where-it-came-from) and 4 more |
1758
- | `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 (Given)](#/given/where-it-came-from), [A number one metric does not have (Metrics)](#/metrics/not-recorded), [Staff movement as a chain (Metrics)](#/metrics/staff-movement) and 1 more |
1799
+ | `target` | `number` | — | The value this quantity is meant to reach - missed, never violated. From `QuantityProps`.<br>Shown in: [Show a share against a target](#/tree/share-with-target), [The availability of a service (Installation)](#/installation/availability), [Write a tree (Calculation)](#/calculation/oee) and 6 more |
1800
+ | `limits` | `readonly `[`Limit`](#type-Limit)`[]` | — | Bounds the quantity is assessed against, through core's `assess()`. From `QuantityProps`.<br>Shown in: [Hold a figure to its limits](#/tree/limits), [Density (Calculation)](#/calculation/density), [Hold an interim to its limits (Chain)](#/chain/error-budget) and 5 more |
1801
+ | `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 (Given)](#/given/where-it-came-from), [A number one metric does not have (Metrics)](#/metrics/not-recorded), [Staff movement as a chain (Metrics)](#/metrics/staff-movement) and 2 more |
1759
1802
  | `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 (Given)](#/given/where-it-came-from) |
1760
1803
  | `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)](#/calculation/a-stronger-line), [A quieter line (Calculation)](#/calculation/a-quieter-line), [Emphasis inside a group (Calculation)](#/calculation/emphasis-inside-a-group) |
1761
1804
  | `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)](#/calculation/a-rule-above), [Emphasis inside a group (Calculation)](#/calculation/emphasis-inside-a-group) |
@@ -1781,9 +1824,9 @@ case, not the exception.
1781
1824
 
1782
1825
  | Prop | Type | Default | Description |
1783
1826
  |---|---|---|---|
1784
- | `value` *required* | `number` | — | <br>Shown in: [Hold a figure to its limits](#/tree/limits), [Hold an interim to its limits (Chain)](#/chain/error-budget), [Say where a number came from (Given)](#/given/where-it-came-from) and 2 more |
1785
- | `side` *required* | [`Side`](#type-Side)<br>`"upper" \| "lower"` | — | <br>Shown in: [Hold a figure to its limits](#/tree/limits), [Hold an interim to its limits (Chain)](#/chain/error-budget), [Say where a number came from (Given)](#/given/where-it-came-from) and 2 more |
1786
- | `severity` *required* | [`Severity`](#type-Severity)<br>`"warning" \| "alarm"` | — | <br>Shown in: [Hold a figure to its limits](#/tree/limits), [Hold an interim to its limits (Chain)](#/chain/error-budget), [Say where a number came from (Given)](#/given/where-it-came-from) and 2 more |
1827
+ | `value` *required* | `number` | — | <br>Shown in: [Hold a figure to its limits](#/tree/limits), [Density (Calculation)](#/calculation/density), [Hold an interim to its limits (Chain)](#/chain/error-budget) and 3 more |
1828
+ | `side` *required* | [`Side`](#type-Side)<br>`"upper" \| "lower"` | — | <br>Shown in: [Hold a figure to its limits](#/tree/limits), [Density (Calculation)](#/calculation/density), [Hold an interim to its limits (Chain)](#/chain/error-budget) and 3 more |
1829
+ | `severity` *required* | [`Severity`](#type-Severity)<br>`"warning" \| "alarm"` | — | <br>Shown in: [Hold a figure to its limits](#/tree/limits), [Density (Calculation)](#/calculation/density), [Hold an interim to its limits (Chain)](#/chain/error-budget) and 3 more |
1787
1830
 
1788
1831
  ###### `Side`
1789
1832
 
@@ -2064,16 +2107,16 @@ The keys of [Calculation](#/calculation/keyboard-calculation) apply here.
2064
2107
  | `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.<br>Shown in: [Take amounts away from a first quantity](#/chain/net-weight), [Mix additions and deductions](#/chain/tour-cost), [Multiply between two interims](#/chain/mark-up-and-vat) and 17 more |
2065
2108
  | `value` | `number \| null \| `[`MetricValues`](#type-MetricValues) | — | 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. With `metrics`, an object by metric id, as on a `Given`.<br>Shown in: [Take amounts away from a first quantity](#/chain/net-weight), [Mix additions and deductions](#/chain/tour-cost), [Multiply between two interims](#/chain/mark-up-and-vat) and 17 more |
2066
2109
  | `children` | `ReactNode` | — | Instead of `label` and `value`: exactly one quantity - a tree, a `<Ref>` or a `<Chain>`.<br>Shown in: [Fold a group of lines into one](#/chain/payslip), [Write a chain (Calculation)](#/calculation/invoice), [Emphasis inside a group (Calculation)](#/calculation/emphasis-inside-a-group) and 12 more |
2067
- | `source` | `string` | — | Where the number came from: a system, a report, a person. From `GivenProps`.<br>Shown in: [Say where a number came from (Given)](#/given/where-it-came-from), [State when a number was true (Given)](#/given/as-of), [Staff movement as a chain (Metrics)](#/metrics/staff-movement) and 7 more |
2110
+ | `source` | `string` | — | Where the number came from: a system, a report, a person. From `GivenProps`.<br>Shown in: [Say where a number came from (Given)](#/given/where-it-came-from), [State when a number was true (Given)](#/given/as-of), [Staff movement as a chain (Metrics)](#/metrics/staff-movement) and 8 more |
2068
2111
  | `asOf` | `Date \| number` | — | When the number was true - not when it was fetched. From `GivenProps`.<br>Shown in: [Say where a number came from (Given)](#/given/where-it-came-from), [State when a number was true (Given)](#/given/as-of), [The cost per stop of a day's tours (Worked examples)](#/worked-examples/cost-per-tour) |
2069
2112
  | `ages` | [`FreshnessAges`](#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. From `GivenProps`.<br>Shown in: [Say where a number came from (Given)](#/given/where-it-came-from), [The cost per stop of a day's tours (Worked examples)](#/worked-examples/cost-per-tour) |
2070
2113
  | `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: [Fold a group of lines into one](#/chain/payslip), [Put a chain inside a tree](#/chain/chain-in-a-tree), [The availability of a service (Installation)](#/installation/availability) and 10 more |
2071
- | `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: [Take amounts away from a first quantity](#/chain/net-weight), [Mix additions and deductions](#/chain/tour-cost), [Multiply between two interims](#/chain/mark-up-and-vat) and 41 more |
2114
+ | `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: [Take amounts away from a first quantity](#/chain/net-weight), [Mix additions and deductions](#/chain/tour-cost), [Multiply between two interims](#/chain/mark-up-and-vat) and 42 more |
2072
2115
  | `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: [Fold a group of lines into one](#/chain/payslip), [Put a chain inside a tree](#/chain/chain-in-a-tree), [Hold an interim to its limits](#/chain/error-budget) and 17 more |
2073
2116
  | `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: [Take amounts away from a first quantity](#/chain/net-weight), [Mix additions and deductions](#/chain/tour-cost), [Multiply between two interims](#/chain/mark-up-and-vat) and 29 more |
2074
- | `target` | `number` | — | The value this quantity is meant to reach - missed, never violated. From `QuantityProps`.<br>Shown in: [Put a chain inside a tree](#/chain/chain-in-a-tree), [The availability of a service (Installation)](#/installation/availability), [Write a tree (Calculation)](#/calculation/oee) and 5 more |
2075
- | `limits` | `readonly `[`Limit`](#type-Limit)`[]` | — | Bounds the quantity is assessed against, through core's `assess()`. From `QuantityProps`.<br>Shown in: [Hold an interim to its limits](#/chain/error-budget), [Hold a figure to its limits (Tree)](#/tree/limits), [Say where a number came from (Given)](#/given/where-it-came-from) and 4 more |
2076
- | `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 (Given)](#/given/where-it-came-from), [A number one metric does not have (Metrics)](#/metrics/not-recorded), [Staff movement as a chain (Metrics)](#/metrics/staff-movement) and 1 more |
2117
+ | `target` | `number` | — | The value this quantity is meant to reach - missed, never violated. From `QuantityProps`.<br>Shown in: [Put a chain inside a tree](#/chain/chain-in-a-tree), [The availability of a service (Installation)](#/installation/availability), [Write a tree (Calculation)](#/calculation/oee) and 6 more |
2118
+ | `limits` | `readonly `[`Limit`](#type-Limit)`[]` | — | Bounds the quantity is assessed against, through core's `assess()`. From `QuantityProps`.<br>Shown in: [Hold an interim to its limits](#/chain/error-budget), [Density (Calculation)](#/calculation/density), [Hold a figure to its limits (Tree)](#/tree/limits) and 5 more |
2119
+ | `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 (Given)](#/given/where-it-came-from), [A number one metric does not have (Metrics)](#/metrics/not-recorded), [Staff movement as a chain (Metrics)](#/metrics/staff-movement) and 2 more |
2077
2120
  | `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 (Given)](#/given/where-it-came-from) |
2078
2121
  | `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)](#/calculation/a-stronger-line), [A quieter line (Calculation)](#/calculation/a-quieter-line), [Emphasis inside a group (Calculation)](#/calculation/emphasis-inside-a-group) |
2079
2122
  | `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)](#/calculation/a-rule-above), [Emphasis inside a group (Calculation)](#/calculation/emphasis-inside-a-group) |
@@ -2082,14 +2125,14 @@ The keys of [Calculation](#/calculation/keyboard-calculation) apply here.
2082
2125
 
2083
2126
  | Prop | Type | Default | Description |
2084
2127
  |---|---|---|---|
2085
- | `label` *required* | `string` | — | What the quantity is called. It stands on its line, wherever it is an operand, and in the accessible sentence.<br>Shown in: [Take amounts away from a first quantity](#/chain/net-weight), [Mix additions and deductions](#/chain/tour-cost), [Multiply between two interims](#/chain/mark-up-and-vat) and 48 more |
2128
+ | `label` *required* | `string` | — | What the quantity is called. It stands on its line, wherever it is an operand, and in the accessible sentence.<br>Shown in: [Take amounts away from a first quantity](#/chain/net-weight), [Mix additions and deductions](#/chain/tour-cost), [Multiply between two interims](#/chain/mark-up-and-vat) and 50 more |
2086
2129
  | `id` | `string` | — | Makes the quantity referable: `<Ref to>` stands for it elsewhere. Needed only for a quantity used more than once.<br>Shown in: [Fold a group of lines into one](#/chain/payslip), [Put a chain inside a tree](#/chain/chain-in-a-tree), [The availability of a service (Installation)](#/installation/availability) and 10 more |
2087
- | `unit` | `string` | — | A label written after the number - "min", "pcs", "€". Never converted and never checked; the calculation does no unit algebra.<br>Shown in: [Take amounts away from a first quantity](#/chain/net-weight), [Mix additions and deductions](#/chain/tour-cost), [Multiply between two interims](#/chain/mark-up-and-vat) and 41 more |
2130
+ | `unit` | `string` | — | A label written after the number - "min", "pcs", "€". Never converted and never checked; the calculation does no unit algebra.<br>Shown in: [Take amounts away from a first quantity](#/chain/net-weight), [Mix additions and deductions](#/chain/tour-cost), [Multiply between two interims](#/chain/mark-up-and-vat) and 42 more |
2088
2131
  | `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.<br>Shown in: [Fold a group of lines into one](#/chain/payslip), [Put a chain inside a tree](#/chain/chain-in-a-tree), [Hold an interim to its limits](#/chain/error-budget) and 17 more |
2089
2132
  | `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.<br>Shown in: [Take amounts away from a first quantity](#/chain/net-weight), [Mix additions and deductions](#/chain/tour-cost), [Multiply between two interims](#/chain/mark-up-and-vat) and 29 more |
2090
- | `target` | `number` | — | The value this quantity is meant to reach - missed, never violated.<br>Shown in: [Put a chain inside a tree](#/chain/chain-in-a-tree), [The availability of a service (Installation)](#/installation/availability), [Write a tree (Calculation)](#/calculation/oee) and 5 more |
2091
- | `limits` | `readonly `[`Limit`](#type-Limit)`[]` | — | Bounds the quantity is assessed against, through core's `assess()`.<br>Shown in: [Hold an interim to its limits](#/chain/error-budget), [Hold a figure to its limits (Tree)](#/tree/limits), [Say where a number came from (Given)](#/given/where-it-came-from) and 4 more |
2092
- | `explanation` | `string` | — | A sentence of plain text beside the line: why the quantity is here, or what it means.<br>Shown in: [Say where a number came from (Given)](#/given/where-it-came-from), [A number one metric does not have (Metrics)](#/metrics/not-recorded), [Staff movement as a chain (Metrics)](#/metrics/staff-movement) and 1 more |
2133
+ | `target` | `number` | — | The value this quantity is meant to reach - missed, never violated.<br>Shown in: [Put a chain inside a tree](#/chain/chain-in-a-tree), [The availability of a service (Installation)](#/installation/availability), [Write a tree (Calculation)](#/calculation/oee) and 6 more |
2134
+ | `limits` | `readonly `[`Limit`](#type-Limit)`[]` | — | Bounds the quantity is assessed against, through core's `assess()`.<br>Shown in: [Hold an interim to its limits](#/chain/error-budget), [Density (Calculation)](#/calculation/density), [Hold a figure to its limits (Tree)](#/tree/limits) and 5 more |
2135
+ | `explanation` | `string` | — | A sentence of plain text beside the line: why the quantity is here, or what it means.<br>Shown in: [Say where a number came from (Given)](#/given/where-it-came-from), [A number one metric does not have (Metrics)](#/metrics/not-recorded), [Staff movement as a chain (Metrics)](#/metrics/staff-movement) and 2 more |
2093
2136
  | `aside` | `ReactNode` | — | Content of the caller's own beside the line - a sparkline, a link. It never takes part in the calculation.<br>Shown in: [Say where a number came from (Given)](#/given/where-it-came-from) |
2094
2137
  | `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.<br>Shown in: [A stronger line (Calculation)](#/calculation/a-stronger-line), [A quieter line (Calculation)](#/calculation/a-quieter-line), [Emphasis inside a group (Calculation)](#/calculation/emphasis-inside-a-group) |
2095
2138
  | `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.<br>Shown in: [A rule above (Calculation)](#/calculation/a-rule-above), [Emphasis inside a group (Calculation)](#/calculation/emphasis-inside-a-group) |
@@ -2134,9 +2177,9 @@ case, not the exception.
2134
2177
 
2135
2178
  | Prop | Type | Default | Description |
2136
2179
  |---|---|---|---|
2137
- | `value` *required* | `number` | — | <br>Shown in: [Hold an interim to its limits](#/chain/error-budget), [Hold a figure to its limits (Tree)](#/tree/limits), [Say where a number came from (Given)](#/given/where-it-came-from) and 2 more |
2138
- | `side` *required* | [`Side`](#type-Side)<br>`"upper" \| "lower"` | — | <br>Shown in: [Hold an interim to its limits](#/chain/error-budget), [Hold a figure to its limits (Tree)](#/tree/limits), [Say where a number came from (Given)](#/given/where-it-came-from) and 2 more |
2139
- | `severity` *required* | [`Severity`](#type-Severity)<br>`"warning" \| "alarm"` | — | <br>Shown in: [Hold an interim to its limits](#/chain/error-budget), [Hold a figure to its limits (Tree)](#/tree/limits), [Say where a number came from (Given)](#/given/where-it-came-from) and 2 more |
2180
+ | `value` *required* | `number` | — | <br>Shown in: [Hold an interim to its limits](#/chain/error-budget), [Density (Calculation)](#/calculation/density), [Hold a figure to its limits (Tree)](#/tree/limits) and 3 more |
2181
+ | `side` *required* | [`Side`](#type-Side)<br>`"upper" \| "lower"` | — | <br>Shown in: [Hold an interim to its limits](#/chain/error-budget), [Density (Calculation)](#/calculation/density), [Hold a figure to its limits (Tree)](#/tree/limits) and 3 more |
2182
+ | `severity` *required* | [`Severity`](#type-Severity)<br>`"warning" \| "alarm"` | — | <br>Shown in: [Hold an interim to its limits](#/chain/error-budget), [Density (Calculation)](#/calculation/density), [Hold a figure to its limits (Tree)](#/tree/limits) and 3 more |
2140
2183
 
2141
2184
  ###### `Side`
2142
2185
 
@@ -2714,18 +2757,18 @@ The keys of [Calculation](#/calculation/keyboard-calculation) apply here.
2714
2757
 
2715
2758
  | Prop | Type | Default | Description |
2716
2759
  |---|---|---|---|
2717
- | `value` *required* | `number \| null \| undefined \| `[`MetricValues`](#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](#/given/where-it-came-from), [State when a number was true](#/given/as-of), [Read in German](#/given/in-german) and 48 more |
2718
- | `source` | `string` | — | Where the number came from: a system, a report, a person.<br>Shown in: [Say where a number came from](#/given/where-it-came-from), [State when a number was true](#/given/as-of), [Staff movement as a chain (Metrics)](#/metrics/staff-movement) and 7 more |
2760
+ | `value` *required* | `number \| null \| undefined \| `[`MetricValues`](#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](#/given/where-it-came-from), [State when a number was true](#/given/as-of), [Read in German](#/given/in-german) and 50 more |
2761
+ | `source` | `string` | — | Where the number came from: a system, a report, a person.<br>Shown in: [Say where a number came from](#/given/where-it-came-from), [State when a number was true](#/given/as-of), [Staff movement as a chain (Metrics)](#/metrics/staff-movement) and 8 more |
2719
2762
  | `asOf` | `Date \| number` | — | When the number was true - not when it was fetched.<br>Shown in: [Say where a number came from](#/given/where-it-came-from), [State when a number was true](#/given/as-of), [The cost per stop of a day's tours (Worked examples)](#/worked-examples/cost-per-tour) |
2720
2763
  | `ages` | [`FreshnessAges`](#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](#/given/where-it-came-from), [The cost per stop of a day's tours (Worked examples)](#/worked-examples/cost-per-tour) |
2721
- | `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](#/given/where-it-came-from), [State when a number was true](#/given/as-of), [Read in German](#/given/in-german) and 48 more |
2764
+ | `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](#/given/where-it-came-from), [State when a number was true](#/given/as-of), [Read in German](#/given/in-german) and 50 more |
2722
2765
  | `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](#/given/in-german), [The availability of a service (Installation)](#/installation/availability), [Write a tree (Calculation)](#/calculation/oee) and 10 more |
2723
- | `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](#/given/where-it-came-from), [State when a number was true](#/given/as-of), [Read in German](#/given/in-german) and 41 more |
2766
+ | `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](#/given/where-it-came-from), [State when a number was true](#/given/as-of), [Read in German](#/given/in-german) and 42 more |
2724
2767
  | `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](#/given/where-it-came-from), [Read in German](#/given/in-german), [The availability of a service (Installation)](#/installation/availability) and 17 more |
2725
2768
  | `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](#/given/where-it-came-from), [State when a number was true](#/given/as-of), [Read in German](#/given/in-german) and 29 more |
2726
- | `target` | `number` | — | The value this quantity is meant to reach - missed, never violated. From `QuantityProps`.<br>Shown in: [The availability of a service (Installation)](#/installation/availability), [Write a tree (Calculation)](#/calculation/oee), [Show a share against a target (Tree)](#/tree/share-with-target) and 5 more |
2727
- | `limits` | `readonly `[`Limit`](#type-Limit)`[]` | — | Bounds the quantity is assessed against, through core's `assess()`. From `QuantityProps`.<br>Shown in: [Say where a number came from](#/given/where-it-came-from), [Hold a figure to its limits (Tree)](#/tree/limits), [Hold an interim to its limits (Chain)](#/chain/error-budget) and 4 more |
2728
- | `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](#/given/where-it-came-from), [A number one metric does not have (Metrics)](#/metrics/not-recorded), [Staff movement as a chain (Metrics)](#/metrics/staff-movement) and 1 more |
2769
+ | `target` | `number` | — | The value this quantity is meant to reach - missed, never violated. From `QuantityProps`.<br>Shown in: [The availability of a service (Installation)](#/installation/availability), [Write a tree (Calculation)](#/calculation/oee), [Density (Calculation)](#/calculation/density) and 6 more |
2770
+ | `limits` | `readonly `[`Limit`](#type-Limit)`[]` | — | Bounds the quantity is assessed against, through core's `assess()`. From `QuantityProps`.<br>Shown in: [Say where a number came from](#/given/where-it-came-from), [Density (Calculation)](#/calculation/density), [Hold a figure to its limits (Tree)](#/tree/limits) and 5 more |
2771
+ | `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](#/given/where-it-came-from), [A number one metric does not have (Metrics)](#/metrics/not-recorded), [Staff movement as a chain (Metrics)](#/metrics/staff-movement) and 2 more |
2729
2772
  | `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](#/given/where-it-came-from) |
2730
2773
  | `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)](#/calculation/a-stronger-line), [A quieter line (Calculation)](#/calculation/a-quieter-line), [Emphasis inside a group (Calculation)](#/calculation/emphasis-inside-a-group) |
2731
2774
  | `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)](#/calculation/a-rule-above), [Emphasis inside a group (Calculation)](#/calculation/emphasis-inside-a-group) |
@@ -2770,9 +2813,9 @@ case, not the exception.
2770
2813
 
2771
2814
  | Prop | Type | Default | Description |
2772
2815
  |---|---|---|---|
2773
- | `value` *required* | `number` | — | <br>Shown in: [Say where a number came from](#/given/where-it-came-from), [Hold a figure to its limits (Tree)](#/tree/limits), [Hold an interim to its limits (Chain)](#/chain/error-budget) and 2 more |
2774
- | `side` *required* | [`Side`](#type-Side)<br>`"upper" \| "lower"` | — | <br>Shown in: [Say where a number came from](#/given/where-it-came-from), [Hold a figure to its limits (Tree)](#/tree/limits), [Hold an interim to its limits (Chain)](#/chain/error-budget) and 2 more |
2775
- | `severity` *required* | [`Severity`](#type-Severity)<br>`"warning" \| "alarm"` | — | <br>Shown in: [Say where a number came from](#/given/where-it-came-from), [Hold a figure to its limits (Tree)](#/tree/limits), [Hold an interim to its limits (Chain)](#/chain/error-budget) and 2 more |
2816
+ | `value` *required* | `number` | — | <br>Shown in: [Say where a number came from](#/given/where-it-came-from), [Density (Calculation)](#/calculation/density), [Hold a figure to its limits (Tree)](#/tree/limits) and 3 more |
2817
+ | `side` *required* | [`Side`](#type-Side)<br>`"upper" \| "lower"` | — | <br>Shown in: [Say where a number came from](#/given/where-it-came-from), [Density (Calculation)](#/calculation/density), [Hold a figure to its limits (Tree)](#/tree/limits) and 3 more |
2818
+ | `severity` *required* | [`Severity`](#type-Severity)<br>`"warning" \| "alarm"` | — | <br>Shown in: [Say where a number came from](#/given/where-it-came-from), [Density (Calculation)](#/calculation/density), [Hold a figure to its limits (Tree)](#/tree/limits) and 3 more |
2776
2819
 
2777
2820
  ###### `Side`
2778
2821
 
@@ -3238,6 +3281,41 @@ export default function WholeCompany() {
3238
3281
  }
3239
3282
  ```
3240
3283
 
3284
+ ##### A dense staff report
3285
+
3286
+ `density="compact"` closes up the head and every metric's column with the lines; a note stays beneath its label, and the figures move beneath the labels by the same measure as in a regular report.
3287
+
3288
+ ```tsx
3289
+ import { Calculation, Given, Sum } from "@umriss-ui/calculation";
3290
+ import type { Metric } from "@umriss-ui/calculation";
3291
+
3292
+ const METRICS: Metric[] = [
3293
+ { id: "heads", label: "Headcount", unit: "HC" },
3294
+ { id: "fte", label: "Full-time equivalents", unit: "FTE", decimals: 1 },
3295
+ ];
3296
+
3297
+ export default function CompactReport() {
3298
+ return (
3299
+ <Calculation aria-label="Staff of Tidewell, 17 March" metrics={METRICS} density="compact">
3300
+ <Sum label="Tidewell">
3301
+ <Sum label="Engineering">
3302
+ <Given label="Web team" value={{ heads: 31, fte: 27.5 }} />
3303
+ <Given label="Apps team" value={{ heads: 22, fte: 20 }} />
3304
+ <Given label="Platform team" value={{ heads: 18, fte: 15.8 }} source="HR system" />
3305
+ <Given label="Quality assurance" value={{ heads: 25, fte: 21.2 }} />
3306
+ </Sum>
3307
+ <Sum label="Customer service">
3308
+ <Given label="Service desk" value={{ heads: 40, fte: 31.6 }} />
3309
+ <Given label="Returns" value={{ heads: 18, fte: 14.1 }} />
3310
+ <Given label="Student staff" value={{ heads: 6, fte: null }} explanation="FTE are not recorded for student staff" />
3311
+ </Sum>
3312
+ <Given label="Administration" value={{ heads: 12, fte: 10.4 }} />
3313
+ </Sum>
3314
+ </Calculation>
3315
+ );
3316
+ }
3317
+ ```
3318
+
3241
3319
  #### When to use something else
3242
3320
 
3243
3321
  - A ratio across two metrics, such as FTE per head → a calculation of its own, a `Quotient` of two givens
@@ -3253,10 +3331,10 @@ The keys of [Calculation](#/calculation/keyboard-calculation) apply here.
3253
3331
 
3254
3332
  | Prop | Type | Default | Description |
3255
3333
  |---|---|---|---|
3256
- | `id` *required* | `string` | — | The key of this metric's number in every `value` object.<br>Shown in: [Headcount and full-time equivalents](#/metrics/two-teams), [A number one metric does not have](#/metrics/not-recorded), [Team, cost centre, business line](#/metrics/business-line) and 4 more |
3257
- | `label` *required* | `string` | — | The metric's name, in the head above its column and in each row's sentence.<br>Shown in: [Headcount and full-time equivalents](#/metrics/two-teams), [A number one metric does not have](#/metrics/not-recorded), [Team, cost centre, business line](#/metrics/business-line) and 4 more |
3258
- | `unit` | `string` | — | A label written after the number where a result closes, and beneath the metric's name in the head. Never converted and never checked.<br>Shown in: [Headcount and full-time equivalents](#/metrics/two-teams), [A number one metric does not have](#/metrics/not-recorded), [Team, cost centre, business line](#/metrics/business-line) and 4 more |
3259
- | `decimals` | `number` | a given as it was given, at most two for a derived number | Fixed number of fraction digits as shown, for every quantity of this metric.<br>Shown in: [Headcount and full-time equivalents](#/metrics/two-teams), [A number one metric does not have](#/metrics/not-recorded), [Team, cost centre, business line](#/metrics/business-line) and 4 more |
3334
+ | `id` *required* | `string` | — | The key of this metric's number in every `value` object.<br>Shown in: [Headcount and full-time equivalents](#/metrics/two-teams), [A number one metric does not have](#/metrics/not-recorded), [Team, cost centre, business line](#/metrics/business-line) and 5 more |
3335
+ | `label` *required* | `string` | — | The metric's name, in the head above its column and in each row's sentence.<br>Shown in: [Headcount and full-time equivalents](#/metrics/two-teams), [A number one metric does not have](#/metrics/not-recorded), [Team, cost centre, business line](#/metrics/business-line) and 5 more |
3336
+ | `unit` | `string` | — | A label written after the number where a result closes, and beneath the metric's name in the head. Never converted and never checked.<br>Shown in: [Headcount and full-time equivalents](#/metrics/two-teams), [A number one metric does not have](#/metrics/not-recorded), [Team, cost centre, business line](#/metrics/business-line) and 5 more |
3337
+ | `decimals` | `number` | a given as it was given, at most two for a derived number | Fixed number of fraction digits as shown, for every quantity of this metric.<br>Shown in: [Headcount and full-time equivalents](#/metrics/two-teams), [A number one metric does not have](#/metrics/not-recorded), [Team, cost centre, business line](#/metrics/business-line) and 5 more |
3260
3338
 
3261
3339
  #### Known limits
3262
3340
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@umriss-ui/calculation",
3
- "version": "0.6.1",
3
+ "version": "0.7.0",
4
4
  "description": "React calculation view for data-dense applications - a derivation written as it is shown, evaluated by the library, folded and read line by line.",
5
5
  "license": "MIT",
6
6
  "author": "Roman Händler",
@@ -61,8 +61,8 @@
61
61
  "typescript": "^5.6.3",
62
62
  "vite": "^6.0.0",
63
63
  "vite-plugin-dts": "^4.3.0",
64
- "@umriss-ui/demo": "0.0.0",
65
- "@umriss-ui/core": "0.30.0"
64
+ "@umriss-ui/core": "0.30.0",
65
+ "@umriss-ui/demo": "0.0.0"
66
66
  },
67
67
  "scripts": {
68
68
  "props": "node --disable-warning=ExperimentalWarning --experimental-strip-types demo/props.ts",