@umriss-ui/charts 0.41.0 → 0.42.0

package/CHANGELOG.md

@@ -4,11 +4,12 @@ This document describes what changes for **callers** of the package: exports,
 props, behaviour.
 
 **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.
+when something is repaired. The six packages are released in step, and a rename
+keeps its old name for one further minor, with a warning, before the minor after
+it removes the name ([the upgrade promise, ADR-0066](../../docs/adr/0066-one-number-peers-over-the-minor-a-rename-lives-one-minor.md)).
+**Whatever changes existing behaviour stands under a heading "Changed" of its
+own**, no matter which digit rose, with a `Migration:` line. Whoever reads only
+one section before an upgrade reads that one.
 
 From 0.34.0 the packages share one number - five, and six from 0.40.0, when the dashboard joined: they are released together, and a package without a change of its own still gets a heading for it.
 
@@ -29,6 +30,23 @@ interface was still expected to move before `0.3.0`.
 
 ---
 
+## 0.42.0 – A chart under test in jsdom (Oct. 2026)
+
+### Added
+
+- **A chart is testable in jsdom.** The new "Testing" section gives the Vitest and Jest lines in full - a charts-only application installs no core - with a setup file whose ResizeObserver reports a fixed size and whose `getContext` stub keeps jsdom quiet; `.` and `./wording/de` carry a `default` condition for Jest's resolver. The release check runs a test of a legend and the data table from those blocks under both runners.
+- **The README names `--u-chart-1` to `--u-chart-6`** as the palette a brand changes, beside core's brand file.
+- **TypeScript 5.4 or newer**, stated in the Install section (the declarations use `NoInfer`); the release check compiles a strict consumer under 5.4 as well as the current TypeScript.
+
+## 0.41.1 – The documentation runs where the code is (Oct. 2026)
+
+### Changed
+
+- **The documentation is no longer hosted.** The site on GitHub Pages is gone, and the package's `homepage` now names its README on GitHub. The running documentation of this version opens from a checkout of the tag `charts-v0.41.1` with `pnpm install` and `pnpm start`, at `http://localhost:4170/umriss-ui/` - the repository README says how, under "See it running".
+  - Migration: nothing to change; a bookmark or link to the old hosted site no longer resolves - open the documentation from a checkout of the tag, as described above.
+- **`docs/llms-full.md` in the package stands on its own:** a link to another page points at that page's heading in the same file, a link to a place on the site that the file does not hold keeps only its text, and ADR-0032 is linked at this version's tag.
+  - Migration: nothing to change; look at any tool that read `docs/llms-full.md` and followed its links to the site, which now find the heading in the same file.
+
 ## 0.41.0 – Limits read as values, and Jest loads the charts (Oct. 2026)
 
 ### Fixed

package/README.md

@@ -16,7 +16,7 @@ lint rule over `packages/charts/src/**` holds that fast.
 pnpm add @umriss-ui/charts
 ```
 
-React 19 or newer as a peer, and nothing else. `@umriss-ui/core` is **not** a
+React 19 or newer as a peer, and nothing else. TypeScript 5.4 or newer (the declarations use `NoInfer`). `@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).
 
@@ -24,8 +24,11 @@ The package ships ES2022 syntax; an application that serves older browsers
 transpiles it itself.
 
 Every entry, `./wording/de` included, begins with `"use client"`, the directive a framework
-with Server Components reads to treat a module as client code. No test runs
-inside such a framework: the charts are rendered to a string in a test.
+with Server Components reads to treat a module as client code. A chart is declared by its hook,
+`useChart`, so the declaration lives in a Client Component file: a Server Component renders that
+file and hands it the rows. On a server a chart gives its labelled frame and an empty canvas; the
+drawing arrives after mount. No test runs inside such a framework: the charts are rendered to a
+string in a test.
 
 ## The smallest chart that runs
 
@@ -98,7 +101,8 @@ wins. `@umriss-ui/charts/styles.css` stays exported for setups that link
 stylesheets by hand.
 
 **Colours** come from `--uc-*` variables that fall back to the tokens of
-`@umriss-ui/core` where they exist and to literals where they do not. **Light and
+`@umriss-ui/core` where they exist and to literals where they do not. The palette is `--u-chart-1` to
+`--u-chart-6`; core's README holds a brand file that sets them, light and dark. **Light and
 dark** follow the application's `color-scheme`: the canvas colours are resolved
 anew when the root element's attributes or the system preference change;
 `invalidateTheme()` covers a switch made on another ancestor. **Fonts** are not
@@ -150,8 +154,7 @@ next kind to come (ADR-0059).
 
 ## More
 
-* The demo: <https://romanhaendler.github.io/umriss-ui/charts/>, or locally
-  `pnpm dev:charts` (port 4174). It is the documentation — every page
+* The demo, in a checkout: `pnpm dev:charts` (port 4174). It is the documentation — every page
   shows running examples with their source and the props table generated from
   `src/`, each prop linked to the examples that show it. An API index lists
   every export, and one search finds across all five packages.
@@ -159,14 +162,86 @@ next kind to come (ADR-0059).
 * **For a coding agent**: `docs/llms-full.md` inside the installed package —
   the demo as one Markdown file, pinned to the installed version: every page
   with its examples' source, its props tables and why it is built as it is,
-  and an index of every export with its comment and its declaration. Each
-  page also has a Markdown twin online; for the latest version:
-  <https://romanhaendler.github.io/umriss-ui/charts/llms.txt>.
+  and an index of every export with its comment and its declaration. The running documentation of a version is opened as [the repository README describes](https://github.com/romanhaendler/umriss-ui#see-it-running): check out the tag `<package>-v<version>`, then `pnpm start`.
 * [`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 five packages share.
 
+## Testing
+
+Tested: Vitest 5 and Jest 30 (with babel-jest), both on jsdom. happy-dom and Jest 29 may work and are
+not promised. `check:dist` runs a test of the installed package in a Vitest project and a Jest project
+that hold exactly the files below. A chart-only application installs no core, so the lines are given in
+full here.
+
+**Vitest** needs one line, `server.deps.inline`: Vitest hands a dependency to Node, and Node cannot
+import the stylesheet that the package's JavaScript imports (`Unknown file extension ".css"`). Inlined,
+Vitest's own pipeline handles it.
+
+```ts vitest.config.ts
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    environment: "jsdom",
+    globals: true,
+    setupFiles: ["./umriss.setup.js"],
+    server: { deps: { inline: [/@umriss-ui/] } },
+  },
+});
+```
+
+**Jest** needs two settings: `moduleNameMapper` maps every stylesheet to an empty module, and
+`transformIgnorePatterns` lets babel-jest compile the package, which ships ES modules. Babel's config
+must apply to `node_modules`, so it is a root `babel.config.*`, not a `.babelrc`.
+
+```js jest.config.cjs
+module.exports = {
+  testEnvironment: "jsdom",
+  setupFilesAfterEnv: ["<rootDir>/umriss.setup.js"],
+  moduleNameMapper: { "\\.css$": "<rootDir>/css-stub.cjs" },
+  transformIgnorePatterns: ["/node_modules/(?!(@umriss-ui)/)"],
+};
+```
+
+```js css-stub.cjs
+module.exports = {};
+```
+
+```js babel.config.cjs
+module.exports = {
+  presets: [
+    ["@babel/preset-env", { targets: { node: "current" } }],
+    ["@babel/preset-react", { runtime: "automatic" }],
+  ],
+};
+```
+
+**Next.js** with `next/jest`: put the umriss packages in `transpilePackages`; the preset stubs the
+stylesheets and compiles the packages itself.
+
+**The setup file** gives jsdom what a chart needs to lay out. jsdom measures nothing, so the
+`ResizeObserver` reports a fixed size (600 x 280) for whatever it observes; without a size the chart
+stays empty, and neither the legend nor "Show data" appears. jsdom has no canvas, so `getContext`
+returns `null`, which a chart copes with. The file is the same for both runners:
+
+```js umriss.setup.js
+globalThis.ResizeObserver = class {
+  constructor(callback) {
+    this.callback = callback;
+  }
+  observe(target) {
+    const box = { inlineSize: 600, blockSize: 280 };
+    this.callback([{ target, contentRect: { width: 600, height: 280 }, contentBoxSize: [box] }], this);
+  }
+  unobserve() {}
+  disconnect() {}
+};
+
+HTMLCanvasElement.prototype.getContext = () => null;
+```
+
 ## Licence
 
 MIT — see [`LICENSE`](LICENSE).