@umriss-ui/charts 0.3.0-rc.0

package/CHANGELOG.md

@@ -0,0 +1,158 @@
+# Changes to `@umriss-ui/charts`
+
+This document describes what changes for **callers** of the package: exports,
+props, behaviour. What was worked on in the repository — rebuilds, tests,
+decisions that are invisible from outside — stands in the repository's journal
+(`docs/journal.md`) and in the specs under `.scratch/`.
+
+**The numbers.** The middle digit rises when something is added; the last one
+when something is repaired. As long as the first digit is `0`, no number
+promises compatibility — which is why a rule stronger than the figure applies as
+well: **whatever changes existing behaviour stands under a heading "Changed" of
+its own**, no matter which digit rose. Whoever reads only one section before an
+upgrade reads that one.
+
+**Names read forwards.** Where an entry describes a name that has since been
+renamed, it is named here as it is called today; names that were removed stand
+as they stood.
+
+The versions 0.1.0 and 0.2.0 were reconstructed afterwards, out of the
+specs; the document itself came into being only with
+`library-audit` 08. They are grouped by unit of delivery, not by commit, and were
+never published.
+
+**Release candidates.** `0.3.0-rc.0` is the first version for the registry, under
+the tag `next` rather than `latest`: `pnpm add @umriss-ui/charts@next`. A release
+candidate promises nothing a `0.x` does not already fail to promise; it says the
+interface is still expected to move before `0.3.0`.
+
+---
+
+## 0.3.0-rc.0 – One language, one scope (Sep. 2026)
+
+Delivery report for `.scratch/english-and-umriss-ui/spec.md`, the charts' share.
+
+- **The package is called `@umriss-ui/charts`.** The npm scope moved from
+  `@umriss/*` to `@umriss-ui/*`, which is the org actually secured for this
+  library. The sibling package `@umriss/ui` is `@umriss-ui/core` and lies at
+  `packages/core`; `@umriss/table` is `@umriss-ui/table`. Nothing was ever
+  published under the old names — all three returned 404 from the registry — so
+  there is no alias and no deprecation window, and the version number stays where
+  it is.
+- **Every identifier and every document in the workspace is English** (ADR-0018,
+  which supersedes ADR-0015). For a caller of this package that changes little,
+  because its exported names were English already; what changed is the inside —
+  the pure modules' internal identifiers, the long prose headers that carry the
+  design reasoning, and the demo. The headers were translated, not shortened.
+- **The library ships two wordings, English by default** (ADR-0019). That
+  concerns `@umriss-ui/core`, whose German moved to the subpath
+  `@umriss-ui/core/wording/de`. This package is untouched by it and stays
+  untouched by it: it has no text layer at all, and every string it draws comes
+  from the caller — the one reason `pareto` has no default name for its remainder
+  and `ControlChart` no default labels.
+- **`@umriss-ui/charts` still depends on nothing**, and will keep depending on
+  nothing (ADR-0016). "Core" names the package one installs first, not a layer
+  this package sits on.
+- The licence is MIT, and a `LICENSE` file ships in the package.
+
+### Changed — the limit model's values
+
+`Verdict` is `"ok" | "unknown" | "warning" | "alarm"`, `Severity` is
+`"warning" | "alarm"`, `Side` is `"upper" | "lower"`, and the fields of `Limit`,
+`LimitSet` and `Assessment` are `value`, `side`, `severity`, `limits`, `target`,
+`verdict`, `limit`, `excess`, `deviation`.
+
+ADR-0006 holds this model twice — once here, once in `@umriss-ui/core` — and the
+copies are pinned together by a runtime conformance test that compares both
+results structurally rather than importing either. The two packages, the shared
+case table and that test therefore moved in a single commit; a divergence stays a
+red test and not a report from the field.
+
+`--uc-color-alarm` is unchanged. What moved beside the model is
+`.kc-limit-label[data-severity="warnung"]`, which now reads `"warning"` — the
+same word `tone` has carried all along.
+
+## 0.3.0-rc.0 – Where the library contradicted itself (Sep. 2026)
+
+Delivery report for `.scratch/library-audit/spec.md`, tickets 03 and 05.
+
+### Changed
+
+**The package brings no text along any more.** It has no text layer, and four
+German defaults stood there regardless:
+
+- `ControlChart` no longer labels the control limits without being told to —
+  previously `"OEG"` and `"UEG"`. Whoever wants the labels passes
+  `labelUpper`/`labelLower`.
+- The scatter of the violations was called `` `${name} – Regelverletzung` ``. It
+  is now called what `violationName` says, and without a statement not at all —
+  a `Legend` then carries it as "Series n".
+- `pareto` has no default name for the remainder any more (previously
+  `"Sonstige"`). Whoever names `collectRank` names `remainderName` with it — in
+  the type (`ParetoSettings`) and in DEV as an error. `paretoDefaults` no longer
+  contains `remainderName`.
+- The labelling of an operating-time axis without a `tickFormat` of its own is
+  `dd.MM. HH:mm`, set by hand. Previously it came out of
+  `toLocaleString(undefined, …)` and looked different on every machine.
+- `"Series n"` remains the last resort for a series without a `name`, but warns
+  once in DEV.
+
+**A series keeps its colour.** The palette followed the position in the
+registration; a series that unregistered and registered again landed at the back,
+and every series of the chart changed colour. The palette now follows the `name`:
+on first mounting as before in JSX order, after that a returning series gets its
+colour back. A series without a `name` still takes the colour of its position and
+warns in DEV when that shifts. Drawing happens unchanged in registration order.
+
+**`role="img"` and `aria-label` stand at the plot area** (`.kc-plot`), no longer
+at the root. The root contains the legend, and the descendants of an image are
+presentation to a screen reader — the legend was unreachable. Whoever looked for
+the role at `.kc-root` finds it one level deeper.
+
+### New
+
+- `ControlChart violationName`.
+- The type `ParetoSettings`: what a call of `pareto` may specify.
+
+## 0.2.0 – Limits, states, instruments (Aug. 2026)
+
+Delivery report for `.scratch/judging-values/spec.md`,
+`.scratch/shopfloor-instruments/spec.md` and
+`.scratch/plant-at-a-glance/spec.md`, the charts' share. The decisions stand in
+ADR-0006 to ADR-0011.
+
+### New
+
+- **Three series kinds:** `StateBand` (one state per interval, ADR-0007),
+  `Matrix` (one value per cell, with `DEFAULT_GRADIENT` as the colouring) and
+  `Span` (an interval with an explicit end on a lane).
+- **`LimitLine` and `LimitBand`:** a limit as a rule with severity and role
+  (specification, control limit, zone), which draws the value range of its axis.
+- **`ControlChart`:** the control chart as a composition out of `Line`,
+  `LimitLine` and `Scatter` (ADR-0008), and with it the pure modules
+  `controlLimits`, `zones`, the four rules and `violations`.
+- **The operating-time axis:** `calendar` on `XAxis`/`YAxis` and the pure modules
+  out of `operatingTime.ts` — wall clock ↔ operating time, ticks, breaks.
+- **`pareto`** as a pure module.
+- **The limit as a rule:** `assess` and `verdictWeight` with their types — the
+  same rule as in `@umriss-ui/core`, deliberately there twice (ADR-0006).
+
+Nothing changes in the behaviour of the four existing series kinds.
+
+## 0.1.0 – Takeover state and mixed series kinds (Aug. 2026)
+
+The number stood at `0.1.0` the whole time; it covers the takeover state
+(packages C.1–C.7) and `.scratch/mixed-series-kinds/`.
+
+### New
+
+- `Chart` with two canvas layers and one HTML layer above them, `XAxis`/`YAxis`
+  with axis bands on all four sides, `Tooltip`, `Legend`, `LinearScale` and
+  `invalidateTheme`.
+- Four series kinds mixable within one chart: `Line`, `Scatter`, `Area` with a
+  baseline, and `Bar` on the numeric X axis (ADR-0002).
+
+### Changed
+
+**`LineChart` is called `Chart`** and is generic over the series kinds within it
+(`mixed-series-kinds` 01). The takeover state knew only lines.

package/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c) 2026 Roman Händler
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,109 @@
+# @umriss-ui/charts
+
+Canvas-based charts for data-dense applications: few chart kinds, each one drawn
+properly. Lines, areas, bars, scatters, state bands, matrices and spans compose
+into one chart on shared axes — together with the instruments a plant screen is
+made of: limit lines and bands, a control chart, a Pareto and an operating-time
+axis.
+
+The package depends on **nothing but React**, and it will keep doing so (R-1.2).
+It brings no component library, no date library and no chart framework, and the
+lint rule over `packages/charts/src/**` holds that fast.
+
+## Install
+
+```bash
+pnpm add @umriss-ui/charts@next
+```
+
+The package is a **release candidate**, published under the tag `next`. As long
+as no released version exists, npm points `latest` at the candidate too — a plain
+`pnpm add @umriss-ui/charts` installs it as well.
+
+React 18 or 19 as a peer, and nothing else. `@umriss-ui/core` is **not** a
+dependency and not a peer dependency — if an application uses both packages, it
+does so because it chose to, not because this one required it (ADR-0020).
+
+No fonts are shipped either. The charts use Geist when the application loads it
+(`@fontsource/geist-sans`, `@fontsource/geist-mono`) and the system fonts
+otherwise.
+
+## The smallest chart that runs
+
+```tsx
+import { Chart, Line, XAxis, YAxis, Tooltip } from "@umriss-ui/charts";
+import "@umriss-ui/charts/styles.css";
+
+interface Point {
+  t: number;
+  a: number;
+}
+
+const DATA: Point[] = [
+  { t: 0, a: 12 },
+  { t: 1, a: 18 },
+  { t: 2, a: 15 },
+  { t: 3, a: 24 },
+];
+
+export function Course() {
+  return (
+    <Chart data={DATA} height={280} ariaLabel="Course of one series">
+      <XAxis accessor={(d: Point) => d.t} label="Index" />
+      <YAxis accessor={(d: Point) => d.a} />
+      <Line accessor={(d: Point) => d.a} name="Series A" />
+      <Tooltip />
+    </Chart>
+  );
+}
+```
+
+A series is an element, not an entry in a configuration object: the order in the
+JSX decides what lies over what, and at the same time the palette colour.
+
+## The stylesheet
+
+```ts
+import "@umriss-ui/charts/styles.css";
+```
+
+The axes, ticks, legend and tooltip are DOM and take their values from the
+stylesheet; only the series themselves are drawn on canvas. The JavaScript loads
+no CSS of its own, so the application imports the stylesheet itself.
+
+## What it can do
+
+* **Seven series kinds** in one chart on shared axes: `Line`, `Area`, `Bar`,
+  `Scatter`, `StateBand`, `Matrix`, `Span`.
+* **Several axes per orientation**, each with its own extent; only the first
+  registered axis per orientation draws a grid.
+* **The instruments**: `LimitLine` and `LimitBand`, `ControlChart` with its four
+  rule violations, `pareto()` with a collected remainder, and an operating-time
+  axis that takes the empty hours out and marks every removed span.
+* **The pure modules are exported**, not hidden: `assess`, `controlLimits`,
+  `zones`, `violations`, `pareto`, `operatingCalendar` and the rest. Whoever
+  wants to draw something other than the composition offers should reach the
+  arithmetic without rebuilding it.
+* **Performance, measured rather than claimed.** Three series of 100,000 points
+  each: 10.5 ms materialisation, 10.8 ms series draw, 60 FPS on hover; at three
+  million points, 49.8 ms and 49.6 ms. The measuring run, its conditions and the
+  mixed series set stand in [`docs/capabilities.md`](docs/capabilities.md).
+
+What it deliberately cannot do — zoom and pan, animations, stacking, a category
+scale, horizontal bars — stands in the same record, with the reason.
+
+## More
+
+* The demo: <https://romanhaendler.github.io/umriss-ui/charts/>, or locally
+  `pnpm dev:charts` (port 4174). It is the documentation — every page
+  shows running examples with their source and the props table generated from
+  `src/`.
+* [`CHANGELOG.md`](CHANGELOG.md) — what changes for a caller.
+* [`docs/capabilities.md`](docs/capabilities.md) — every capability with the
+  level at which it is proved.
+* [`../../docs/design-language.md`](../../docs/design-language.md) — the design
+  language all three packages share.
+
+## Licence
+
+MIT — see [`LICENSE`](LICENSE).

package/dist/charts.css

@@ -0,0 +1 @@
+.kc-root{--uc-color-axis: var(--u-edge-color-strong, rgba(23, 23, 23, .17));--uc-color-grid: var(--u-hairline, rgba(23, 23, 23, .06));--uc-color-text: var(--u-color-text-muted, #71717a);--uc-color-bg: var(--u-color-surface, #ffffff);--uc-font: var( --u-font-sans, "Geist Sans", "Geist", -apple-system, "Segoe UI", system-ui, sans-serif );--uc-font-mono: var( --u-font-mono, "Geist Mono", ui-monospace, "Cascadia Mono", "Consolas", monospace );--uc-color-warning: var(--u-color-warning, #8a5c00);--uc-color-alarm: var(--u-color-danger, #b13636);--uc-color-ok: var(--u-color-success, #217a4b);--uc-series-1: var(--u-chart-1, #2563eb);--uc-series-2: var(--u-chart-2, #db2777);--uc-series-3: var(--u-chart-3, #059669);--uc-series-4: var(--u-chart-4, #d97706);--uc-series-5: var(--u-chart-5, #7c3aed);--uc-series-6: var(--u-chart-6, #0891b2);--uc-size-tick: 11.5px;--uc-size-title: 12px;--uc-size-legend: 12.5px;--uc-radius: 6px;--uc-shadow: 0 1px 2px rgba(0, 0, 0, .06), 0 4px 12px rgba(0, 0, 0, .08);position:relative;display:flex;flex-direction:column;font-family:var(--uc-font);color:var(--uc-color-text);font-variant-numeric:tabular-nums;font-feature-settings:"tnum" 1}.kc-plot{position:relative;flex:1 1 auto;min-height:0;min-width:0}.kc-plot>canvas{position:absolute;top:0;right:0;bottom:0;left:0;display:block;pointer-events:none}.kc-axes{position:absolute;top:0;right:0;bottom:0;left:0;pointer-events:none}.kc-axis{position:absolute}.kc-axis-line{position:absolute;background:var(--uc-color-axis)}.kc-axis-y>.kc-axis-line{top:0;width:1px;height:100%}.kc-axis-left>.kc-axis-line{right:0}.kc-axis-right>.kc-axis-line{left:0}.kc-axis-x>.kc-axis-line{left:0;width:100%;height:1px}.kc-axis-bottom>.kc-axis-line{top:0}.kc-axis-top>.kc-axis-line{bottom:0}.kc-tick{position:absolute}.kc-axis-y>.kc-tick{left:0;right:0;height:1px}.kc-axis-x>.kc-tick{top:0;bottom:0;width:1px}.kc-tick-mark{position:absolute;background:var(--uc-color-axis)}.kc-axis-y>.kc-tick>.kc-tick-mark{top:0;width:5px;height:1px}.kc-axis-left>.kc-tick>.kc-tick-mark{right:0}.kc-axis-right>.kc-tick>.kc-tick-mark{left:0}.kc-axis-x>.kc-tick>.kc-tick-mark{left:0;width:1px;height:5px}.kc-axis-bottom>.kc-tick>.kc-tick-mark{top:0}.kc-axis-top>.kc-tick>.kc-tick-mark{bottom:0}.kc-tick-label{position:absolute;white-space:pre;font-size:var(--uc-size-tick);line-height:1.25;letter-spacing:.005em;color:var(--uc-color-text)}.kc-axis-y>.kc-tick>.kc-tick-label{top:50%;transform:translateY(-50%)}.kc-axis-left>.kc-tick>.kc-tick-label{text-align:right}.kc-axis-right>.kc-tick>.kc-tick-label{text-align:left}.kc-axis-title{position:absolute;white-space:pre;font-size:var(--uc-size-title);line-height:1.25;letter-spacing:.01em;color:var(--uc-color-text)}.kc-axis-x>.kc-axis-title{left:0;right:0;text-align:center}.kc-axis-bottom>.kc-axis-title{bottom:0}.kc-axis-top>.kc-axis-title{top:0}.kc-axis-y>.kc-axis-title{top:50%;writing-mode:vertical-rl}.kc-axis-left>.kc-axis-title{left:0;transform:translateY(-50%) rotate(180deg)}.kc-axis-right>.kc-axis-title{right:0;transform:translateY(-50%)}.kc-legend{display:flex;flex-wrap:wrap;gap:4px 14px;font-size:var(--uc-size-legend);line-height:1.35;color:var(--uc-color-text)}.kc-legend-top{order:-1;padding-bottom:8px}.kc-legend-bottom{order:1;padding-top:8px}.kc-legend-item{display:inline-flex;align-items:center;gap:6px;cursor:default}.kc-legend-chip{display:inline-block;width:10px;height:10px;border-radius:2px}.kc-tooltip{position:absolute;top:0;left:0;z-index:2;pointer-events:none;opacity:0;transition:opacity 80ms ease-out;min-width:96px;padding:7px 9px;border:1px solid var(--uc-color-axis);border-radius:var(--uc-radius);background:var(--uc-color-bg);box-shadow:var(--uc-shadow);font-size:12px;line-height:1.35;color:var(--uc-color-text)}.kc-tooltip-head{font-family:var(--uc-font-mono);font-size:11.5px;letter-spacing:.01em;padding-bottom:5px;margin-bottom:5px;border-bottom:1px solid var(--uc-color-grid)}.kc-tooltip-list{display:grid;grid-template-columns:auto 1fr auto;gap:3px 8px;align-items:center}.kc-tooltip-row{display:contents}.kc-tooltip-chip{width:8px;height:8px;border-radius:2px}.kc-tooltip-name{white-space:nowrap}.kc-tooltip-value{font-family:var(--uc-font-mono);text-align:right;white-space:nowrap}@media(prefers-reduced-motion:reduce){.kc-tooltip{transition:none}}.kc-measure{position:absolute;top:0;left:0;right:auto;bottom:auto;transform:none;visibility:hidden;pointer-events:none;white-space:pre;writing-mode:horizontal-tb}.kc-limit-label{position:absolute;font-size:var(--uc-size-tick);line-height:1.25;white-space:nowrap;font-variant-numeric:tabular-nums;background:var(--uc-color-bg);padding:0 2px}.kc-limit-label[data-severity=warning]{color:var(--uc-color-warning)}.kc-limit-label[data-severity=alarm]{color:var(--uc-color-alarm)}.kc-limit-label[data-role=control],.kc-limit-label[data-role=zone]{color:var(--uc-color-text)}.kc-axis-y .kc-limit-label{transform:translateY(-50%)}.kc-axis-left .kc-limit-label{right:9px}.kc-axis-right .kc-limit-label{left:9px}.kc-break{position:absolute;top:0;width:7px;height:9px;margin-left:-3.5px;color:var(--uc-color-text)}.kc-break:before,.kc-break:after{content:"";position:absolute;top:0;width:1px;height:9px;background:currentColor;opacity:.55;transform:skew(-20deg)}.kc-break:before{left:1px}.kc-break:after{left:4px}