eis-ui-render 0.34.3 → 0.35.0

package/README.md

@@ -5,42 +5,400 @@ Check the [docs](https://eisgroup.github.io/ui-render/configuration) folder to g
 
 https://eisgroup.github.io/ui-render/
 
+## Supported `view` names
+
+[`docs/SUPPORTED-VIEWS.md`](docs/SUPPORTED-VIEWS.md) lists every name a `meta.json` may use — the
+`view` of a node, the value of a `render*` attribute, and the action names accepted by `onClick`,
+`onChange` and `onDone` — and puts any view that is declared as a constant but that no resolver case
+handles in a table of its own. The page is generated from the `FIELD` constants plus the resolver
+source, so run `npm run docs:views` after adding or removing either; a contract test fails while the
+page and the source disagree.
+
+## Supported props on `Table`, `Tooltip` and `Select` / `Dropdown`
+
+[`docs/SUPPORTED-PROPS.md`](docs/SUPPORTED-PROPS.md) documents the prop surface of the three views
+the `semantic-ui-react` exit replaced, split by what actually happens to each prop: consumed by our
+component, stripped before the DOM, or deliberately dropped. All three — `Table`, `Tooltip` and
+`Select`/`Dropdown` — are in-house now, and no file in `src` references the package by any
+mechanism, so the page reads as a record of what each component emits and what it no longer accepts
+rather than as a parity checklist. It is generated from the component source and the call sites —
+run `npm run docs:props` after changing one — and a contract test additionally checks it against the
+example corpus.
+
 ## Installation (consumer)
 
 `eis-ui-render` declares the following **peer dependencies**. The host application must install
-them explicitly — they are not bundled. Versions matter: keeping a single shared instance of
-React and Moment in the application is required for the library to work correctly.
+them explicitly — they are not bundled. React must remain a single shared instance, while Moment
+must be supplied by the host because the library build externalizes it. The bundle also imports
+`react/jsx-runtime`, which every React in the range ships, from the host's React: a build that
+aliases `react` to one copy must alias `react/jsx-runtime` the same way.
 
 | Package | Required version | Why it must be a peer |
 |---|---|---|
-| `react` | `^16.14.0` | A second copy of React in the tree triggers `Invalid hook call` and breaks Context (forms, providers). pnpm with strict node_modules will not deduplicate copies across non-overlapping ranges. |
-| `react-dom` | `^16.14.0` | Must come from the same install as `react` for the renderer pair to match. |
-| `moment` | `~2.29.4` | The library renders dates and accepts `moment` instances on its API. If the application also uses Moment with a different copy, `value instanceof moment` checks fail (silent UI bugs in date pickers). |
+| `react` | `^16.14.0 \|\| ^17.0.0 \|\| ^18.0.0 \|\| ^19.0.0` | A second copy of React in the tree triggers `Invalid hook call` and breaks Context (forms, providers). pnpm with strict node_modules will not deduplicate copies across non-overlapping ranges. |
+| `react-dom` | `^16.14.0 \|\| ^17.0.0 \|\| ^18.0.0 \|\| ^19.0.0` | Must use the same major version as `react` so the renderer pair matches. |
+| `moment` | `^2.29.4` | The library externalizes Moment and uses it for date pickers and formatters, so the host must provide a compatible 2.x version. |
 
 Install (npm):
 
 ```bash
-npm install eis-ui-render react@^16.14.0 react-dom@^16.14.0 moment@~2.29.4
+npm install eis-ui-render react@^18.0.0 react-dom@^18.0.0 moment@^2.29.4
 ```
 
 Install (pnpm) — note that with `auto-install-peers=false` (the strict default in some setups)
 peer dependencies are **not installed automatically**, so they must be listed explicitly:
 
 ```bash
-pnpm add eis-ui-render react@^16.14.0 react-dom@^16.14.0 moment@~2.29.4
+pnpm add eis-ui-render react@^18.0.0 react-dom@^18.0.0 moment@^2.29.4
 ```
 
+React 16.14, 17 and 19 hosts are supported as well, and may keep matching `react@^16.14.0`,
+`react@^17.0.0` or `react@^19.0.0` dependencies. The library is developed against React 18.3, and the
+whole test suite runs on 16.14, 17, 18 and 19 in CI.
+
 If the host project relies on transitive copies of `react`/`react-dom`/`moment` from another
 package instead of declaring them directly, pnpm in isolated mode will not resolve our peer
 through them — the application must declare these three packages itself.
 
 Other libraries previously listed as peer dependencies (`final-form`, `final-form-arrays`,
-`react-final-form`, `react-final-form-arrays`, `prop-types`) are now bundled as regular
-dependencies of `eis-ui-render`, so the host project does not need to install them.
+`react-final-form`, `react-final-form-arrays`) are bundled into `dist/index.js`, and the package
+declares no dependencies of its own, so the host project installs nothing beside the three peers.
+`prop-types`, also listed once, is not used at all any more: the props are TypeScript types.
+
+`eis-ui-render` is consumed by a bundler — imported as a React component into a host application. Dropping
+`dist/index.js` into a page with a `<script>` tag is **not supported**: the UMD global lookup never matched
+React's real global name, so it has never worked.
+
+The bundle is built for current browsers: the last two versions of Chrome, Edge and Firefox, and the last
+two major versions of Safari, on macOS and on iOS (`browserslist` in `package.json`). That is what the host
+applications support, so an older browser is not a target.
+
+## Styles and assets (consumer)
+
+The library entry deliberately does not inject CSS, so the host loads the stylesheet itself. Both
+paths below work and resolve to the same rules — `dist/static/all.css` and `font.css` are one-line
+`@import` re-exports, so the bytes ship only once (`semantic.css` is an empty stub in both folders):
+
+```js
+import 'eis-ui-render/static/all.css'   // or 'eis-ui-render/dist/static/all.css'
+import 'eis-ui-render/static/font.css'  // icon font — only if the host does not provide its own
+```
+
+Copy the package's `static/` folder into the web root as part of the build. It holds the
+stylesheets and the icon font, and is self-contained:
+
+```bash
+cp -R node_modules/eis-ui-render/static ./public/
+```
+
+An `Image` given only a `name` loads it from `/static/images/<name>`, relative to the host's web
+root, with the name lower-cased and each whitespace character replaced by `-`. The package ships no
+images, so those files are the host's own. Earlier releases also carried `static/images/flags/`, 266
+country-flag SVGs that nothing in the library used; a host that links them now ships its own copy.
+
+A host that serves `static/` under a sub-path or a CDN sets `path` (the images folder, ending in `/`,
+which the name is appended to) or `src` on the `Image` in its meta; the library build fixes its
+environment at build time, so no host environment variable reaches it. Releases 0.32.4 to 0.34.3
+resolved a name-only `Image` to a page-relative `undefined/static/images/<name>` instead, which 404s.
+
+## The meta.json contract (consumer)
+
+The package ships the UI declaration contract as a JSON Schema (draft 2020-12) at
+`eis-ui-render/meta.schema.json`, so `meta.json` authors get autocomplete and validation in
+their editor instead of discovering a typo at render time.
+
+The quickest way in is a pointer inside the file itself — no workspace configuration, and it
+works in VS Code and the JetBrains IDEs alike:
+
+```json
+{
+  "$schema": "./node_modules/eis-ui-render/meta.schema.json",
+  "view": "Col",
+  "items": [{ "view": "Text", "name": "customer.name" }]
+}
+```
+
+Or map it once for every meta file, in `.vscode/settings.json`:
+
+```json
+{
+  "json.schemas": [
+    {
+      "fileMatch": ["**/*_meta.json", "**/meta.json"],
+      "url": "./node_modules/eis-ui-render/meta.schema.json"
+    }
+  ]
+}
+```
+
+The schema is **permissive on purpose**. Component attributes are forwarded to the underlying
+React component, so nodes accept properties the schema does not list, and `view`, render-method,
+action and normalizer names suggest the built-in vocabulary without rejecting an unlisted string —
+the renderer accepts those too. What the schema does constrain is the handful of shapes the engine
+genuinely requires (`items`/`headers`/`extraItems`/`extraHeaders` must be arrays, `name` must be a
+string), each of which is otherwise a render-time crash, plus the type of a few attributes the engine
+reads, such as `relativeData` and `showIf`, and the format of `metaVersion`.
+
+`$schema` is stripped before rendering, so adding it changes no output. So is a `_comment` attribute
+on any node, a note for the next author; the schema does not declare it, so an editor will not
+suggest it.
+
+### Dev-mode validation
+
+The same rules run at runtime behind an opt-in prop. It is off by default and walks nothing until
+asked, so it costs a default host nothing:
+
+```jsx
+<UIRender data={data} meta={meta} validateMeta={process.env.NODE_ENV !== 'production'} />
+```
+
+Each problem is reported to `console.warn` on one line, naming the JSON path of the offending
+node rather than leaving a stack trace inside a minified bundle:
+
+```text
+[ui-render] meta error at "items[3].items[0].name": name must be a string key path, got number …
+[ui-render] meta warning at "headers[2].renderCell": unknown render method "double5" …
+```
+
+`error` means the engine will fail on that node; `warning` means it will render, but silently
+degraded — an unknown `view` becomes a "field does not exist" placeholder, an unknown
+`render*` method falls back to plain text, and a prop the select, table or tooltip no longer reads
+(`DROPPED_PROP`, see `docs/SUPPORTED-PROPS.md`) is ignored. Upgrading from 0.34, turn it on once
+to find those. Pass a function instead of `true` to collect the
+problems yourself (`validateMeta={problems => …}`), and keep it a stable reference: the check runs
+again whenever `meta` or this prop changes identity. The reporter never throws into the host
+application, whatever it finds.
+
+### Contract version
+
+`meta.json` may declare an optional root-level `metaVersion` (`"MAJOR"` or `"MAJOR.MINOR"`) to
+record which contract it was authored against. The current contract version is **`2`**.
+
+Version `2` changed one thing: a table header without a `label` shows no text, where `1` showed its
+`id`. The `id` stays as hidden text, which names the column for screen readers. A header that should
+show text needs a `label`.
+
+- **Absence means "current"** — the file targets whatever contract the installed
+  `eis-ui-render` implements. That is the right choice when meta and library ship together, and
+  it is why no existing `meta.json` has to declare one.
+- **MAJOR** changes only for a change that would break existing meta; **MINOR** for additive
+  ones. Declaring a version equal to or below what the library implements is always compatible.
+- The engine **ignores the value** and strips the field before rendering: declaring it never
+  changes output. Dev-mode validation is the only thing that reads it, and only to report a
+  malformed value, a major version newer than the installed library implements, or a `metaVersion`
+  placed on a nested node, where it means nothing.
+
+There is no negotiation beyond that, deliberately: the field exists so a future contract change
+can be additive and announced, not so hosts can request a different renderer.
+
+Note the unrelated legacy `version` attribute seen in older meta files: it is not a contract
+version (existing files use it both as a producer version at the root and as a node label deeper
+in the tree), the engine discards it, and new files should use `metaVersion`.
+
+## Security model (consumer)
+
+**A meta is code, not content.** Load only metas you would trust as much as your own code: the
+renderer does what a meta tells it to.
+
+- **It sets attributes on the elements it renders, raw HTML included.** A `Text` node with
+  `dangerouslySetInnerHTML: {__html: "…"}` renders that HTML. The renderer checks no URL scheme
+  in an attribute a meta gives.
+- **It calls functions.** A meta calls the actions the renderer has built in, the `methods` you
+  pass and the `apiCalls` you hand it, whenever it declares. One built-in action is `fetch`:
+  `{name: "fetch", mapArgs: ["https://…", options]}` calls the page's `fetch` with that URL and
+  those options.
+- **Data is text, unless a meta makes it an attribute.** A value from `data` renders as text,
+  which React escapes. A meta that binds one to an attribute with `{name: "path"}` sets the value
+  there as it is.
+- **Upload checks run in the browser only.** `formats` and `maxSize` decide what the drop zone
+  accepts, and your `uploadFile` receives the files as the user chose them. Check their type and
+  size again on your server.
+- **Downloads come from your `downloadFile`.** The renderer requests no URL for one: it saves what
+  your function answers through a temporary `<a download>`.
+
+To report a vulnerability, see [SECURITY.md](SECURITY.md).
+
+## Renderer configuration (consumer)
+
+Four props configure how values are formatted and how the shell is labelled. They are
+published to every component the renderer draws, so a nested `Table` cell honours them
+exactly like a top-level field:
+
+```jsx
+<UIRender data={data} meta={meta} dateFormat="DD/MM/YYYY" currency="EUR" language="fr" locale="fr-FR" />
+```
+
+| Prop | Default | Effect |
+|---|---|---|
+| `dateFormat` | `MM-DD-YYYY` | [`moment` format tokens](https://momentjs.com/docs/#/displaying/format/) for every date the renderer **displays** (an ISO value in a `Text` node, a `render*: "Date"` value) and **edits** (the date picker's display and parsing) |
+| `currency` | `USD` | published as a CSS class on the renderer's shell (`.app.EUR`), for currency-specific styling |
+| `language` | `en` | published as a CSS class on the renderer's shell (`.app.lang--fr`). Where `locale` names no moment locale you loaded, it names the one a date field's month and day names are in. A change renders again every text the document translated, in the new language (see [Switching language](#switching-language-while-a-document-is-on-the-page)) |
+| `locale` | none: the browser's | the [language tag](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl#locales_argument) numbers are **displayed** in: their decimal and grouping separators. A Java-style `de_DE` is read as `de-DE`. It also names the moment locale a date field's month and day names are in (see [Translating the built-in texts](#translating-the-built-in-texts-consumer)) |
+
+Each is merged, not replaced: passing only `dateFormat` leaves the others at their defaults.
+`currency` is **not** `meta.currencyCode` — that one selects the currency symbol
+the `Currency` value renderer prints, in either form (`"Currency"` or `{"name": "Currency"}`), and is
+declared in meta rather than passed as a prop.
+
+`locale` is where a host passes its user's number format. With `locale="de-DE"`:
+
+- the `Currency`, `Float`, `Double5` and `Percent` renderers, a `Counter`, a pie chart's values and a
+  slider's labels write `1.234,5`;
+- a number shown as it is, by a `Text` node or in short form (a pie chart's total, an upload's size limit),
+  takes the decimal separator only: `1234,5`, `1,2k`.
+
+Number **inputs** take and show a point either way. Without `locale`, or with a value that is no language
+tag, numbers show as they did before the prop existed: the renderers in the browser's locale, every other
+number with a point.
+
+> These props used to be accepted and then silently ignored — every date rendered as
+> `MM-DD-YYYY` whatever was passed. If your application has been passing `dateFormat` and
+> compensating for it elsewhere, it now takes effect.
+
+## Translating the built-in texts (consumer)
+
+Your `translate` prop is handed the labels, titles and options of a meta, and the values a document
+shows as text. Some texts are UI Render's own: a select's `Select`, a popup's `Ok`, the validation
+messages, the upload's and the table's texts, a date field's calendar, the names screen readers give
+the controls, and the `Total` under a pie chart's total. `translate` is asked for each of them under a
+key of its own, `ui-render:<ID>`, so an i18next-based host translates them by registering a
+`ui-render` namespace:
+
+```js
+i18next.addResourceBundle('de', 'ui-render', {
+    OK: 'OK',
+    REQUIRED: 'Pflichtfeld',
+    MUST_BE_MINIMUM: 'Mindestens {min}',
+    SELECT: 'Bitte wählen',
+    TOTAL: 'Gesamt',
+})
+```
+
+[`docs/BUILT-IN-PHRASES.md`](docs/BUILT-IN-PHRASES.md) lists every id with its English text and
+where it shows, and the package's types list the ids as `UIRender.UIRenderPhraseId`.
+
+When a key is missing, UI Render shows its English text. It takes what `translate` answers as a
+translation only when that is a non-empty string other than the key itself (`ui-render:TOTAL`, which
+an i18next-based host answers for a key it does not have) or the key without its namespace (`TOTAL`,
+which plain i18next answers). So a host with no `ui-render` namespace, or with no `translate`, sees
+these texts in English. Each key is asked for once, and what comes back is shown as it is: neither
+the English text nor your translation goes to `translate` again.
+
+A text may have a placeholder, written `{name}`. UI Render fills it after your translation comes
+back, so keep it in single braces in your translation, or leave it out. A few fill it with an element
+of their own, such as the file name in bold in `FILE_MUST_BE_UNDER`: your translation decides where it
+goes.
+
+The validation messages reach `getValidationErrors` as the field shows them, in your language. A
+required field is the exception: it is reported as `<Field Name> is Required`, with the name taken from
+the field's `name`, as before.
+
+A date field's calendar asks for its texts the same way: `TODAY`, and the names a screen reader gives
+its buttons, such as `PREVIOUS_MONTH` and `CHOOSE_A_YEAR`. Its month and day names come from moment
+instead, and so do the month names of a date whose `dateFormat` names the month (`DD MMMM YYYY`). They
+are in the moment locale your `locale` prop names, `de` for `de-DE`, or else the one your `language`
+names, and the calendar's weeks start as that locale starts them. What a user types is read in that
+locale too: a German field takes `15 März 2024`, not `15 Mar 2024`. moment is your dependency, and its
+locale data is yours to load before the document renders:
+
+```js
+import 'moment/locale/de'
+```
+
+Without it, the names stay English. moment's global locale plays no part, so documents in two
+languages can share a page; a `Text` that shows a date still follows it. Loading a moment locale makes
+it moment's global locale too, so call `moment.locale()` afterwards if your page needs another.
+
+### Switching language while a document is on the page
+
+Pass your current language as `language`. When your `translate` stays the same function as the
+language changes, as i18next's own `t` does, `language` is what tells the document:
+
+```jsx
+// `t` is one function for the life of the page, and answers in the language your i18n is in now.
+<UIRender meta={meta} data={data} translate={t} language={currentLanguage} />
+```
+
+When `language` changes, the document renders again every text it translated, in the language
+`translate` answers in now: the labels, titles, placeholders and options of the meta, the table
+headers, the values it shows as text, a popup's title and content, and the built-in texts, the
+validation messages under the fields and a date field's calendar included. A date field's month and
+day names follow `language` too, where it is what names their moment locale. Nothing is mounted
+again: what the user typed, the fields they left and the errors they see stay as they are.
+`getValidationErrors` is handed the errors again when they read differently in the new language.
+
+A new `translate` does the same, so a host whose `translate` is a new function for each language,
+such as one from i18next's `getFixedT`, need not pass `language`. Keep `translate` the same function
+between renders otherwise: every new one renders every text of the document again. Wrap one you
+write inline in `useCallback`.
+
+## Error reporting (consumer)
+
+The renderer catches a failure per node rather than letting one bad declaration blank the
+page: the failing node is replaced by a one-line diagnostic and everything around it keeps
+rendering. Pass `onError` to receive the same diagnostic as a structured report:
+
+```jsx
+<UIRender data={data} meta={meta} onError={report => Sentry.captureException(report.error, {
+    extra: { metaPath: report.path, componentStack: report.errorInfo.componentStack },
+})} />
+```
+
+```js
+{
+  error,      // the thrown value
+  errorInfo,  // React's {componentStack}
+  path,       // JSON path of the node in `meta`, e.g. 'items[3].items[0]' ('' = the root)
+  props,      // that node's resolved props: its meta declaration plus what the engine added
+  message,    // the one-line diagnostic, also rendered in place of the failed node
+}
+```
+
+`path` is the point of the report — a stack trace out of a minified bundle names React
+internals, while `items[3].items[0]` names the declaration to go and fix. It is exact for a
+failure inside the component a node resolved to; for a failure the renderer hits while
+preparing a node (a malformed `items`, say) it names the closest enclosing node, which is
+the most precise position available.
+
+The library logs the report itself as well, so `onError` adds a channel rather than
+silencing the console. It never has to be defensive: a reporter that throws is caught, and
+the render failure is still reported.
+
+## Several documents on one page (consumer)
+
+Each `UIRender` on a page keeps what it owns to itself:
+
+- its form data, and the validation errors `getValidationErrors` reports, which reach the
+  document that owns the field;
+- its popup, which opens in its own shell, under its own `language` and `currency` classes;
+- its `translate`, when it was given one: what it translates, it translates with that function
+  and never with another document's, its popup's title, message and Ok included.
+
+Two things are shared with the rest of the page:
+
+- **A document without `translate` uses another's.** It translates with the function of the
+  last document constructed with one, as every document did in 0.34, or shows its text as
+  given when no document has one. Give each document its own `translate` when they differ.
+- **An id a field derives is unique on the page, not only in its document.** A field with no
+  `id` in meta takes its `name` for one, or one made from its `label`. When another element on
+  the page already has that id, from another document or from a name the same document repeats
+  (the nested rows of a `dataKind`), the field takes `<id>-2`, `<id>-3` and so on, and its label
+  and help text follow it. The field that had the id first keeps it, so a page with one
+  document that repeats no name renders the ids it always did. An `id` given in meta is kept
+  as given: give one wherever the host needs a fixed id. Each document's popup root follows
+  the same rule: `render-popup-root`, then `render-popup-root-2`.
 
 ## Development Installation
 
-1. Install [Node.js](https://nodejs.org/), if you haven't already (version v22).
+The published package declares `engines.node >= 22`: that is the floor for *consuming* it. Node 22 is the oldest
+line still supported upstream, and CI server-renders the packed package on it. On an older Node, npm warns at
+install, and refuses to install where `engine-strict` is set. Building this repository is a different matter and
+uses the version in `.nvmrc`, which is what CI installs: Babel 8, which compiles it, needs Node 24.11 or later.
+
+1. Install [Node.js](https://nodejs.org/), if you haven't already — use the version in `.nvmrc` (v24).
+   Node 24.14.0 comes with npm 11.9.0, the version `package.json` pins in `packageManager`. npm itself
+   ignores that field. Corepack reads it once it is enabled for npm (`corepack enable npm`), and then
+   runs exactly that version. CI does not enable corepack: it runs the npm that comes with its Node 24.
 2. Navigate to project root folder and install dependencies by running this command in terminal:
 
 ### `npm install`
@@ -51,11 +409,29 @@ In the project directory, you can run:
 
 ### `npm run start`
 
-Runs the app in the development mode.<br>
-Open [http://localhost:3001](http://localhost:3001) to view it in Chrome browser, then activate LiveReload extension.
+Runs the demo in development mode on [http://localhost:3001](http://localhost:3001).
 
-The page will reload if you make edits.<br>
-You will also see any lint errors in the console.
+Edits apply in place through React Fast Refresh, without a reload. Compile errors show in the
+terminal and over the page; lint does not run here, so run `npm run lint:js` for it.
+
+### `npm run test:e2e`
+
+Runs the browser leg of the contract suite (Playwright, Chromium) over a production build of the
+demo. It records what the tooltip actually does in a real browser — where the bubble lands relative
+to its trigger, whether it flips at a viewport edge, whether it is clipped, whether our CSS paints
+it — which is the class of fact the jsdom suites cannot express at all. It also drives the keyboard
+through the tooltip, the dropdown, the tabs, an Expand title and the upload drop zone, and the views
+a user acts on: the date input's calendar, the popup, the slider, a toggle, a checkbox, the dropdown
+by pointer, table sorting and pages, and progress steps. `e2e/view-coverage.js` names, for each
+`view`, the tests that drive it or why none needs to, and a contract test keeps that map complete.
+
+Run `npm run test:e2e:install` once per machine first: it downloads Chromium into the Playwright
+cache (~570 MB on disk). That download is deliberately **not** wired into `npm install`, so a plain
+`npm ci` costs nothing extra for anyone who never runs this leg.
+
+Specs live in `e2e/`; every expected value is in `e2e/reference.js`, tagged as a reference (current
+behaviour, expected to change), an invariant (must not change), or a pinned defect. Read that file
+before changing an assertion.
 
 ### Live build mode
 
@@ -65,11 +441,28 @@ You will also see any lint errors in the console.
 
 ### How to publish the library
 
-- Run `npm run build-lib`
-- Login to npm `npm login`
-- Publish new version `npm publish`
+- Bump the package version with `npm version patch` (or `minor`, `major`, or an explicit version).
+  This also synchronizes every tracked `data-version` attribute.
+- Inspect the package contents with `npm pack --dry-run`.
+  The `prepack` lifecycle verifies version synchronization, checks that the generated
+  `docs/SUPPORTED-VIEWS.md` and `docs/SUPPORTED-PROPS.md` are current, and builds the library
+  automatically.
+- The build writes what the bundle carries from other packages into `dist/`: the licence file of
+  each one in `THIRD-PARTY-LICENSES.txt`, and a CycloneDX SBOM in `sbom.cdx.json`. A bundled package
+  with no licence file fails the build.
+- Verify the artifact with `npm run test:pack`. It enforces the packaging budgets and then packs,
+  extracts and server-renders the tarball in a throwaway consumer that has only the three peer
+  dependencies available. CI runs both gates on every pull request. After a build,
+  `npm run test:pack:peers` repeats that server render against React 16.14, 17 and 19, and CI runs
+  it too.
+- Login to npm with `npm login` if needed.
+- Publish the verified version with `npm publish`. The same `prepack` checks and build run again
+  immediately before npm creates the published package.
+
+Do not edit the version in `package.json` manually: use `npm version` so source metadata, the
+release commit, and the Git tag stay in sync.
 
 ### How to publish on GitHub Pages
 
 - Run `npm run build` to prepare artifacts
-- Run `npm run deploy` to upload artifacts to GitHub
+- Run `npm run deploy` to upload artifacts to GitHub

package/THIRD-PARTY-NOTICES.md

@@ -0,0 +1,127 @@
+# Third-party notices
+
+`eis-ui-render` is licensed under Apache-2.0 (see `LICENSE`). It also distributes CSS derived from
+the third-party works below, in `static/all.css` and in the sources under `src/style/`.
+
+The JavaScript bundle, `dist/index.js`, carries third-party packages as well. Their licence files are
+not transcribed here: the build writes them into `dist/THIRD-PARTY-LICENSES.txt`, from the packages
+webpack actually bundles. It also lists every third-party component, the CSS below included, in the
+CycloneDX SBOM `dist/sbom.cdx.json` (`scripts/third-party-inventory.js`).
+
+This file exists because §9.7-F1 step 4 copies compiled `semantic-ui-less` CSS into this repository
+rather than importing it from `node_modules`. While the CSS was imported, each module carried its
+own `/*!` banner into the build and the banners survived minification. Once the CSS is vendored,
+nothing keeps those banners current automatically, so the notices are recorded here — and here
+rather than in `static/all.css`, which is a build artifact and is gitignored.
+
+`float-label-css` is not vendored but adapted: `src/style/components/input.less` rewrites its float-label
+technique in our own LESS, so its notice is recorded here as well.
+
+**The icon font is not listed, and why.** `iconsOpenL` (`src/style/fonts/icons/`, shipped in
+`static/fonts/icons/`) was generated with the IcoMoon app from a single icon set of this project's own:
+`selection.json` holds its 85 glyphs, named for this project (`logo`, `logo-brand`, `dropdown-chevron`…).
+The set was exported without IcoMoon's metadata (`includeMetadata: false`), so it records no icon
+library and no licence for any glyph, and the font itself says only "Generated by IcoMoon". If a glyph
+turns out to come from an icon library, its licence belongs in this file.
+
+The licence texts below are transcribed verbatim from the upstream repositories, fetched rather
+than recalled.
+
+---
+
+## Semantic UI (`semantic-ui-less` 2.5.0) — MIT
+
+Derived CSS: the compiled output of `definitions/globals/reset` and `definitions/modules/dropdown`.
+
+**On the copyright holder, stated plainly because the upstream record is incomplete.** The
+`semantic-ui-less` package ships no licence file at all; its `package.json` declares
+`"license": "MIT"` and `"author": "Jack Lukic <jack@semantic-ui.com>"`. The licence text below is
+taken from the Semantic-Org/Semantic-UI repository, which is the source these LESS definitions are
+published from — and that file **contains no `Copyright (c)` line of its own**, only the permission
+text. It is reproduced here exactly as upstream publishes it, with the author recorded from the
+package manifest rather than invented.
+
+```
+# The MIT License
+
+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 THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+```
+
+Author, per the `package.json` of `semantic-ui-less` 2.5.0, which is no longer installed here: Jack Lukic <jack@semantic-ui.com>.
+Source: https://github.com/Semantic-Org/Semantic-UI-LESS — licence text from
+https://github.com/Semantic-Org/Semantic-UI/blob/master/LICENSE
+
+---
+
+## normalize.css v7.0.0 — MIT
+
+Derived CSS: `definitions/globals/reset` in `semantic-ui-less` is largely normalize.css, and its
+own one-line banner (`normalize.css v7.0.0 | MIT License | github.com/necolas/normalize.css`)
+travels into our compiled output.
+
+```
+# The MIT License (MIT)
+
+Copyright © Nicolas Gallagher and Jonathan Neal
+
+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 THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```
+
+Source: https://github.com/necolas/normalize.css
+
+---
+
+## float-label-css 1.0.2 — MIT
+
+Derived CSS: the float-label rules of `src/style/components/input.less` (`.input--wrapper.float`). They
+adapt the technique of its `scss/float-label.scss` to LESS: the label sits over the field while its
+placeholder is shown and the field is not focused (`:placeholder-shown:not(:focus) ~ label`), and floats
+above it otherwise.
+
+```
+MIT License
+
+Copyright (c) 2016 Anton Staroverov
+
+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 THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```
+
+Source: https://github.com/anyblades/float-label-css, published as `tonystar/float-label-css` until the
+repository moved; licence text from its `LICENSE`, version from npm (`float-label-css@1.0.2`, the last
+release, from 2017).