Skip to content

Commit d931c72

Browse files
authored
EPBDS-16211: fix the findings the TypeScript migration left open (#148)
## What changes **The findings the TypeScript migration left open, fixed in one PR.** Each was recorded in `docs/UPGRADE-PLAN.md` as found and left for a change of its own. Each record is now marked with its outcome. ### Bugs a host could see **A `float` Dropdown keeps its label above the selected value.** - The wrapper computed `done` from `props.value`. But `value` had already been taken out of the rest bag, so `props.value` was always `undefined`, and `done` was always false. - So the stylesheet's completed state (`.input--wrapper.done` in `input.less`) never applied: - the label of a `float` dropdown fell back over the selection it named; - a filled multiple selection kept its border. - `done` now comes from the value the parent controls. An empty selection, an empty string, `null`, and a field with an error are still not completed; `0` is a value. - The bug predates the modernization: the code came in with it. - New suite, `Dropdown.done-state.test.js`: 2 of its 8 tests fail on the previous code. The rest pin the boundaries. - jsdom cannot lay out, so the tests assert the class the stylesheet selects on, not the label's position. No tracked meta has a `float` dropdown. - **The full-DOM snapshots were regenerated for the 5 examples that changed.** The diff is 6 lines, and in each one a dropdown wrapper gains `done`. The contract's header records the regeneration, as it asks. The same snapshot holds on React 16, 17, 18 and 19. - **One existing test pinned the bug, and it is rewritten.** `Dropdown.test.js` said "does NOT auto-set done class in standalone mode", and its comment claimed that a form wrapper supplies `props.value`. It does not: measured across the corpus, no dropdown inside a form was `done` either. **`validate: 'password'` no longer throws on a server without a strength checker.** - In a browser, `Active.passwordCheck` falls back to "skip" until zxcvbn loads. - On a server it returns what the host assigned, and `undefined` otherwise. `_envs` pins that undefined, and the rule called it anyway, throwing `TypeError: Active.passwordCheck is not a function`. - `passStrength` now skips the check when no checker is configured. The registry's contract is left as it was. - Reproduced on master first. A server render did not throw, because validators do not run there; any validation in Node did. - New `validationRules.server.test.js` (node environment): 1 of its 3 tests fails on the previous code. **The validation-errors summary is headed "Please complete:".** - `validationErrorsTooltip` rendered "Untranslated" above the list. The phrase lived in `form/translations.js`, which nothing imported, and E2 deleted that file. - It is now registered beside its one reader, as the components register theirs. - New test in `utils.field-lifecycle.test.js`; it fails on the previous code. **A Table with `colGroup` no longer logs React's missing-`key` warning.** - Each `<col>` gets its position as its key; the columns are the meta's, in its order. - The new test has a file of its own: React warns once per component and module, so a test placed after another render would pass whatever the code does. ### Dead code and dead checks - **The options `popupOpen` handed `popupAlert` are gone.** Every path passed a popup's own props merged with the options it was opened with. No version of `popupAlert` ever read them; the first, in 2020, took `(title, content)` as this one does. Behaviour is unchanged. `docs/SUPPORTED-VIEWS.md` now says what a popup reads (`title` and `items`) and which `popupOpen` options are read (`relativeIndex` and `relativePath`). - **Five `utils` exports with no caller are deleted, with their tests:** `optionsFrom`, `enumFrom`, `localise`, `fileFormatNormalized` and `LANGUAGE_LEVEL`. Only their own tests used them; the library exports nothing but the component. - **The examples suite allows no console error at all.** Its allowlist had five entries left. Measured on React 16.14, 17.0.2, 18.3.1 and 19.3.0, none matched anything. An allowlist that matches nothing hides the next real warning of the same shape. ### `static/images/flags/` is no longer shipped This is the maintainers' decision. - **The folder was 266 of the tarball's 289 files and 41% of its unpacked size**, and nothing in the library read it. - **A host that links a flag** from its own markup or a meta `Image` now ships its own copy. The changelog and the README say so. - **The copy rule is removed,** and `pl.svg` leaves the required files. - **The budgets are lowered to the new baseline.** The old limits would not have noticed the folder coming back. - **`check-package-budget.js` gains `MUST_NOT_SHIP`.** It fails a tarball that carries the folder again, by name. I proved it with a flag put back into `static/`. - The source files stay in `public/`, which is the demo's. ### The engine is held to the published host interface (item 9) The host's props reach the engine through one cast in `main.tsx`. So nothing checked that what the engine calls a host with, and what it hands a host, is what `contract.ts` publishes. `contract.agreement.ts` now asserts it, and it found two disagreements: - **`downloadFile`:** the engine typed the host's answer as a whole fetch `Response`. The contract promises `blob()`, which is all the engine reads, and the engine now asks for exactly that. - **The `onError` report:** React's `ErrorInfo` types `componentStack` as possibly missing (`@types/react` 18 and 19), and the contract promises a string. The boundary now passes it on as a string, `''` should React give none. A new test calls the boundary directly with no stack, because no render makes React omit one; it fails on the previous code. There are five assertions: `downloadFile`, `uploadFile`, `updateExperienceData`, the error report, and the meta problem. I broke each one on purpose, and each failed at its own line. ### Found, and left open **`getValidationErrors`** hands a host each field's error as the validator returned it, typed `text: unknown`, while the contract publishes `text: string`. A custom validator that returns an object reaches the host as an object. This needs your decision rather than a fix: - converting the error would change what hosts receive; - loosening the contract would break a host that reads `text` as a string. ## Measured | | master | this PR | |---|---|---| | corpus, 38 examples: commits at mount / `translate` calls | 107 / 1012 | 107 / 1012 | | on an edit: commits / `translate` calls | 27 / 64 | 27 / 64 | | DOM after mount | | 6 dropdown wrappers in 5 examples gain `done`; nothing else differs | | DOM after an edit | | identical, all 38 | | tarball | 289 files, 5.6 MB unpacked, 1.4 MB packed | 23 files, 3.3 MB unpacked, 0.85 MB packed | | `dist/index.js` | 311,535 bytes | 311,559 bytes | The 24 bytes are the registered phrase and the stack normalization, less the dead popup argument. The deleted `utils` exports were never in the bundle. Both bundles were built from `git archive` copies in directories of the same name length. ## Gates All exited 0 on the second full run, on this branch: - `lint:js`, `lint:css`, `typecheck`, `typecheck:contract`; - `docs:props:check`, `docs:views:check`, `css:fixture:check`; - `test:env-flags`, `build`; - `test:coverage`, thresholds included (`Render.tsx`, `Dropdown.tsx`, `definitions.ts` stay at 100%); - `test:pack`, `test:pack:peers`, `test:types`; - `test:react16`, `test:react17`, `test:react19`, 2854 tests each, with no worker crash; - `test:e2e`, 41 tests; - the manifest contract. **The first full run is not counted, and here is why.** It ran before the DOM snapshots and the old Dropdown test were updated, so the same 6 tests failed on every leg. On React 16 a jest worker also died with SIGSEGV in `rules.popup-actions.test.js`, which is the known V8 crash (nodejs/node#62393). The second run, of everything, had no crash. The suite went from 2855 to 2854 tests: 14 new ones, and 15 that tested the deleted `utils` exports. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
1 parent f0d2f75 commit d931c72

32 files changed

Lines changed: 346 additions & 388 deletions

‎CLAUDE.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,7 @@ The modernization roadmap (React 17/18 upgrade, `semantic-ui-react` exit, projec
3737

3838
### Dual build targets
3939

40-
1. **Library** (`src/library/`) — Entry point `src/library/index.ts`, built via `webpack.library.config.mjs` to `dist/`. Exports the `UIRender` component as UMD. `react`, `react-dom`, and `moment` are externalized (peer dependencies — the host app provides them), and so is `react/jsx-runtime`: JSX compiles to it (`babel.config.js` uses the automatic runtime), and a bundled copy would create elements through a different React than the host's. CSS is compiled from LESS and the real stylesheets, fonts and images ship **once** in the root `static/` folder — that is the payload hosts copy to their web root, because a name-only `Image` loads from `/static/images/<name>` (`FILE.PATH_IMAGES`; the library build bakes `process.env` to `{NODE_ENV: 'production'}` on purpose, so no homepage reaches it — `src/core/common/variables/index.js` applies the homepage prefix only when one is set). `dist/static/all.css` and `font.css` are one-line `@import` re-exports of it, so bundler imports of the dist path keep working; `semantic.css` is a 0-byte stub in both places. Packaging is gated by `npm run test:pack` (budgets + a packed-tarball server-render smoke) — never re-add an asset copy under `dist/static/`, the duplicate guard fails the build.
40+
1. **Library** (`src/library/`) — Entry point `src/library/index.ts`, built via `webpack.library.config.mjs` to `dist/`. Exports the `UIRender` component as UMD. `react`, `react-dom`, and `moment` are externalized (peer dependencies — the host app provides them), and so is `react/jsx-runtime`: JSX compiles to it (`babel.config.js` uses the automatic runtime), and a bundled copy would create elements through a different React than the host's. CSS is compiled from LESS and the real stylesheets and fonts ship **once** in the root `static/` folder — that is the payload hosts copy to their web root. No images ship: `static/images/flags/` stopped on 2026-10-01 (`docs/UPGRADE-PLAN.md` §10), and `npm run test:pack:budget` fails a tarball that carries it again. A name-only `Image` loads the HOST's `/static/images/<name>` (`FILE.PATH_IMAGES`; the library build bakes `process.env` to `{NODE_ENV: 'production'}` on purpose, so no homepage reaches it — `src/core/common/variables/index.ts` applies the homepage prefix only when one is set). `dist/static/all.css` and `font.css` are one-line `@import` re-exports of it, so bundler imports of the dist path keep working; `semantic.css` is a 0-byte stub in both places. Packaging is gated by `npm run test:pack` (budgets + a packed-tarball server-render smoke) — never re-add an asset copy under `dist/static/`, the duplicate guard fails the build.
4141
2. **Demo app** (`src/demo/`) — Entry chain `src/demo/index.js` → `src/demo/main.jsx` (`createRoot`) → `src/demo/App.jsx`, built via `webpack.demo.config.mjs`. Used for development and GitHub Pages demo. The three entry files moved out of the `src/` root at §9.9-H3 so the top level reads `core/ | demo/ | library/ | style/` and the library/demo boundary is visible from the directory listing alone. Note it says `createRoot`, not `ReactDOM.render` — the demo mounts through the React 18 root API. It renders under `<StrictMode>` since §9.3 step 7; `src/demo/examples/__tests__/examples.strict-mode.test.js` pins that every example renders and behaves the same with it and without it.
4242

4343
### Core rendering engine (`src/core/engine/`)

‎README.md‎

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -78,14 +78,18 @@ import 'eis-ui-render/static/all.css' // or 'eis-ui-render/dist/static/all.css
7878
import 'eis-ui-render/static/font.css' // icon font — only if the host does not provide its own
7979
```
8080

81-
An `Image` given only a `name` loads it from `/static/images/<name>`, relative to the host's web
82-
root, so those files must be reachable there. Copy the package's `static/` folder into the web root
83-
as part of the build; it is self-contained:
81+
Copy the package's `static/` folder into the web root as part of the build. It holds the
82+
stylesheets and the icon font, and is self-contained:
8483

8584
```bash
8685
cp -R node_modules/eis-ui-render/static ./public/
8786
```
8887

88+
An `Image` given only a `name` loads it from `/static/images/<name>`, relative to the host's web
89+
root. The package ships no images, so those files are the host's own. Earlier releases also
90+
carried `static/images/flags/`, 266 country-flag SVGs that nothing in the library used; a host that
91+
links them now ships its own copy.
92+
8993
A host that serves `static/` under a sub-path or a CDN sets `path` (or `src`) on the `Image` in its
9094
meta; the library build fixes its environment at build time, so no host environment variable reaches
9195
it. Releases 0.32.4 to 0.34.3 resolved a name-only `Image` to a page-relative

‎docs/SUPPORTED-PROPS.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -203,7 +203,7 @@ THE ARITHMETIC, derived from the installed `semantic-ui-react` rather than estim
203203

204204
### `Dropdown` — in-house, no semantic-ui-react
205205

206-
`src/core/components/Dropdown.tsx`, 364 lines. Replaced the wrapper in §9.7-F1 step 3 part 2.
206+
`src/core/components/Dropdown.tsx`, 369 lines. Replaced the wrapper in §9.7-F1 step 3 part 2.
207207

208208
The wrapper already owned the external API: the `onChange(value, name, event)` signature, option sanitisation, case-insensitive dedup on addition, and the cascading reset are all wrapper code, and none of it moved. Only the `<DropDown/>` element at the bottom changed — it is now the in-house `Listbox`, under the same import alias. Two entry points, and they differ: `mapper.tsx` imports the memoised default export for `view: "Dropdown"`, while `modules/form/inputs/DropdownField.ts` imports the NAMED export for `view: "Select"` — which is the majority path.
209209

‎docs/SUPPORTED-VIEWS.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -60,7 +60,7 @@ Two consequences worth knowing before authoring meta:
6060
| `Label` | `FIELD.TYPE.LABEL` | `Label` | `mapper.tsx` switch | A `<label>` element wrapping `items` as its children. |
6161
| `List` | `FIELD.TYPE.LIST` | `List` | `mapper.tsx` switch | Renders the node data array through `renderItem` inside a vertical container. Aliases: `ColList`, `VerticalList`. `RowList` and `HorizontalList` are the horizontal form. |
6262
| `PieChart` | `FIELD.TYPE.PIE_CHART` | `PieChart` | `mapper.tsx` switch | Pie or donut chart drawn as inline SVG from the node data. `mapItems` maps each datum onto the chart shape; `legends`, `pointers` and `sort` control labelling and order. |
63-
| `Popup` | `FIELD.TYPE.POPUP` | `PopupContent` | `mapper.tsx` switch | Registers its `items` on the render instance under `id` and renders nothing in place; the content is mounted only when the `popupOpen` action opens it. An `id` containing `{...}` is kept as a template and interpolated at open time, so one declaration can serve many rows. |
63+
| `Popup` | `FIELD.TYPE.POPUP` | `PopupContent` | `mapper.tsx` switch | Registers its `items` on the render instance under `id` and renders nothing in place; the content is mounted only when the `popupOpen` action opens it. An `id` containing `{...}` is kept as a template and interpolated at open time, so one declaration can serve many rows. The popup shows the node's `title` above its `items`; no other key of the node has an effect. |
6464
| `ProgressSteps` | `FIELD.TYPE.PROGRESS_STEPS` | `ProgressSteps` | `mapper.tsx` switch | Step indicator whose items each carry `step`, `label` and `content`, any of which may itself be a view declaration. |
6565
| `Row` | `FIELD.TYPE.ROW` | `Row` | `mapper.tsx` switch | Horizontal flex container that renders `items` as its children. Alias: `HorizontalLayout`. |
6666
| `RowList` | `FIELD.TYPE.ROW_LIST` | `List` | `mapper.tsx` switch | Renders the node data array through `renderItem` inside a horizontal container. Alias: `HorizontalList`. Same component as `List`, with the `row` flag set. |
@@ -117,7 +117,7 @@ A name that is not below stays an unresolved string rather than raising.
117117
| `fetch` | `FIELD.ACTION.FETCH` | `engine/rules.tsx` | The global `fetch`. |
118118
| `onApplyPeriods` | `FIELD.ACTION.ON_APPLY_PERIODS` | `engine/rules.tsx` | Sends all form data to the host `updateExperienceData` API call and restarts the form with the normalized response. Does nothing when the host supplies no `updateExperienceData`; failures open an error popup. |
119119
| `popup` | `FIELD.ACTION.POPUP` | `engine/rules.tsx` | Opens an alert popup with the given title and content. |
120-
| `popupOpen` | `FIELD.ACTION.POPUP_OPEN` | `engine/rules.tsx` | Opens the content registered by a `Popup` node with the given `id`. Event arguments are filtered out, and the row index is forwarded so fields inside the popup address the row that opened it. |
120+
| `popupOpen` | `FIELD.ACTION.POPUP_OPEN` | `engine/rules.tsx` | Opens the content registered by a `Popup` node with the given `id`. Event arguments are filtered out, and the row index is forwarded so fields inside the popup address the row that opened it. Of an options object after the `id`, only `relativeIndex` and `relativePath` are read, for a template popup's row. |
121121
| `removeData` | `FIELD.ACTION.REMOVE_DATA` | `engine/rules.tsx` | Removes the current row from the parent instance `dataKind` array through the parent form array mutator. Warns and does nothing when the node has no parent instance and form. |
122122
| `reset` | `FIELD.ACTION.RESET` | `engine/rules.tsx` | Resets the form to its initial values. |
123123
| `setState` | `FIELD.ACTION.SET_STATE` | `engine/rules.tsx` | Writes the incoming value into the render instance state at the path given as the argument, for example `setState,active.tab`. This is the channel `{state.…}` templates and `showIf` read; a `Dropdown` or `Select` with a `name` and no `onChange` gets `setState,<name>` installed automatically. |

0 commit comments

Comments
 (0)