@mittwald/flow-react-components 1.1.0-next.9 → 1.1.1

package/MIGRATION.md

@@ -1,31 +1,74 @@
 # Migrations
 
+<!-- AUTO-GENERATED by `pnpm nx build codemods` — do not edit.
+     Source: packages/codemods/src/migrations/<id>/entry.md -->
+
 Entries are sorted by version, newest first. Find the version you are coming
 from and work your way up.
 
-Catching up across many versions? One codemod runs every `0.2.0-alpha` migration
-transform, in the order the changes were released:
+Catching up across several versions? One command bumps every Flow dependency and
+runs the codemod of every migration up to the version it lands on:
 
 ```shell
-npx jscodeshift \
-  -t https://raw.githubusercontent.com/mittwald/flow/refs/heads/main/packages/codemods/src/transforms/flowAlphaAll.ts \
-  --parser tsx \
-  src
+npx @mittwald/flow-codemods@latest upgrade
+```
+
+It is not the whole migration. Most entries below have no codemod and have to be
+done by hand — the command prints those when it is done. It lists migrations
+older than your current version too: nothing records which ones you already
+performed, and re-running a codemod is a no-op.
+
+It refuses to run on a dirty working tree (`--allow-dirty` overrides that) and
+rewrites files in place, so review the diff afterwards.
+
+---
+
+<a id="use-design-tokens-build-metadata-removed"></a>
+
+## useDesignTokens(): no longer returns style-dictionary build metadata
+
+**Since `1.0.16`** · migration · manual change
+
+The hook imported the design tokens' full style-dictionary output, which carries
+`filePath`, `isSource`, `original`, `name`, `attributes` and `key` on every one
+of the 1538 tokens. That metadata is 94 % of the payload and meant nothing in a
+browser — it put 1.37 MB of JavaScript into every bundle that touched the
+package. The hook now reads a runtime build of the same tokens.
+
+Every token keeps `value` and `path`, unchanged and with identical values, so
+the common access patterns are untouched:
+
+```tsx
+const tokens = useDesignTokens();
+tokens["loading-spinner"]["transition-duration"].value; // still works
+tokens.axis.color.path; // still works
 ```
 
-Replace `src` with your sources folder. It changes files in place — run it on a
-clean git state and review the diff afterwards.
+Only the build metadata is gone. If you read one of those fields, take it from
+`@mittwald/flow-design-tokens/json/all-light.json` (or `all-dark.json`) directly
+— that artifact is unchanged. Do not import it into browser code; it is the
+reason this change exists.
 
-The entries below still name their individual codemod, so you can apply a single
-change on its own. Everything without a codemod has to be done by hand, and the
-`0.1.0` → `0.2.0` codemod is not part of `flowAlphaAll` — run that one
-separately, and only when coming from `0.1.0`.
+```diff
+- const source = useDesignTokens().button["corner-radius"].filePath;
++ import tokens from "@mittwald/flow-design-tokens/json/all-light.json";
++ const source = tokens.button["corner-radius"].filePath;
+```
+
+**Apply:** Only affects code reading `filePath`, `isSource`, `original`, `name`,
+`attributes` or `key` off a token returned by `useDesignTokens()`. Those fields
+are gone; read them from `@mittwald/flow-design-tokens/json/all-light.json` (or
+`all-dark.json`) instead, and never from browser code. `value` and `path` are
+unchanged — code using only those needs no change.
 
 ---
 
-## From version `0.2.0-alpha.1055` to `>=0.2.0-alpha.1056`
+<a id="segmented-control-deprecated"></a>
+
+## SegmentedControl deprecated
 
-### SegmentedControl deprecated
+**Since `0.2.0-alpha.1056`** · deprecation · manual change · also applies to
+`@mittwald/flow-remote-react-components`
 
 `SegmentedControl` and `Segment` are deprecated. The component covered two
 different jobs, and each already has its own component in Flow. Which
@@ -84,11 +127,18 @@ The `containerBreakpointSize` property has no counterpart: `Tabs` collapse on
 their own when the available width runs out, and a `RadioGroup` stacks its
 options anyway.
 
+**Apply:** Replace `SegmentedControl` with `Tabs` when the selection switches
+displayed content, or with `RadioGroup` when it sets a value. Pick per usage —
+this is a structural change, not a rename.
+
 ---
 
-## From version `0.2.0-alpha.1046` to `>=0.2.0-alpha.1047`
+<a id="align-to-combine"></a>
+
+## Align renamed to Combine
 
-### Align renamed to Combine
+**Since `0.2.0-alpha.1047`** · migration · codemod available · also applies to
+`@mittwald/flow-remote-react-components`
 
 `Align` is now called `Combine`. The old name suggested a generic alignment tool
 and clashed with the `align` property of `Flex`; the component actually gives
@@ -106,27 +156,26 @@ known combinations of components a fixed, correct arrangement.
 `Align` (and the `flr-align` remote element) keeps working unchanged, logs a
 deprecation warning at runtime, and will be removed in a future major version.
 
-A codemod renames `Align` to `Combine` and `AlignProps` to `CombineProps`:
-
-```shell
-npx jscodeshift \
-  -t https://raw.githubusercontent.com/mittwald/flow/refs/heads/main/packages/codemods/src/transforms/flowAlphaAlignToCombine.ts \
-  --parser tsx \
-  src
-```
-
-Replace `src` with your sources folder.
-
 The component tokens were renamed along with the component
 (`--align--avatar-text--spacing` is now `--combine--avatar-text--spacing`), and
 so were the CSS class names (`.flow--align` is now `.flow--combine`). Both are
 internal and not covered by Semantic Versioning.
 
+**Apply:** Rename `Align` to `Combine` and `AlignProps` to `CombineProps`, for
+named, aliased and namespace imports from a Flow package.
+
+```shell
+npx @mittwald/flow-codemods@latest align-to-combine src
+```
+
 ---
 
-## From version `0.2.0-alpha.1045` to `>=0.2.0-alpha.1046`
+<a id="button-color-accent-to-success"></a>
 
-### Button: color `accent` renamed to `success`
+## Button: color `accent` renamed to `success`
+
+**Since `0.2.0-alpha.1046`** · migration · codemod available · also applies to
+`@mittwald/flow-remote-react-components`
 
 The button color `accent` is now called `success` — the name says what the color
 means instead of how it looks.
@@ -138,16 +187,7 @@ means instead of how it looks.
 
 `color="accent"` keeps working and logs a deprecation warning, but will be
 removed in a future release. A codemod rewrites it on `Button` and
-`SubmitButton`:
-
-```shell
-npx jscodeshift \
-  -t https://raw.githubusercontent.com/mittwald/flow/refs/heads/main/packages/codemods/src/transforms/flowAlphaButtonColorAccentToSuccess.ts \
-  --parser tsx \
-  src
-```
-
-Replace `src` with your sources folder.
+`SubmitButton`.
 
 The CSS class and the design tokens are renamed **without** a fallback — update
 them by hand if you use `@mittwald/flow-stylesheet` or the token CSS variables
@@ -167,37 +207,63 @@ The same rename applies to every `--button--accent-{solid,plain,soft,outline}-*`
 variable. `Chat`'s internal class `flow--chat--accent-button` became
 `flow--chat--success-button`.
 
+**Apply:** Rename `color="accent"` to `color="success"` on `Button` and
+`SubmitButton`. Also update the CSS class `flow--button--accent` to
+`flow--button--success` and every
+`--button--accent-{solid,plain,soft,outline}-*` design token to its `success`
+counterpart if you use `@mittwald/flow-stylesheet` or the token CSS variables
+directly — those have no fallback.
+
+```shell
+npx @mittwald/flow-codemods@latest button-color-accent-to-success src
+```
+
 ---
 
-## From version `0.2.0-alpha.1007` to `>=0.2.0-alpha.1016`
+<a id="tooltip-trigger-delay-type"></a>
+
+## TooltipTrigger changed delay type
 
-### TooltipTrigger changed delay type
+**Since `0.2.0-alpha.1016`** · migration · manual change · also applies to
+`@mittwald/flow-remote-react-components`
 
-Numeric delay values are no longer accepted; only string literals are valid.
+Numeric delay values are no longer accepted; only the string literals
+`"default"` (400ms) and `"long"` (1500ms) are valid. Pick by what the element
+needs, not by rounding the old number to the nearest preset — a former
+`delay={500}` is closer to `"long"` numerically, but if the element is an
+icon-only button that cannot be understood without the tooltip, `"default"` is
+still the right choice.
 
 ```diff
 - <TooltipTrigger delay={300} />
 + <TooltipTrigger delay="default" />
+```
 
-- <TooltipTrigger delay={500} />
+For an icon-only button that needs the tooltip to be understood.
+
+```diff
+- <TooltipTrigger delay={2000} />
 + <TooltipTrigger delay="long" />
 ```
 
-## From version `0.2.0-alpha.1004` to `>=0.2.0-alpha.1005`
+For supplementary information on an element that is already labeled.
 
-### Closing a Modal with unsaved changes is confirmed by default
+**Apply:** Replace every numeric `delay` value on `TooltipTrigger` with one of
+the two string literals: `"default"` (400ms) or `"long"` (1500ms). Pick by
+intent, not by which number is closer — `"default"` is for elements that cannot
+be understood without the tooltip (icon-only buttons), `"long"` is for
+supplementary information on elements that are already labeled. A previous
+numeric value is not a reliable guide: `delay={500}` maps to `"default"`
+(400ms), not `"long"` (1500ms), if the element still needs the tooltip to be
+understood.
 
-A `Modal` that contains a react-hook-form `<Form>` now asks for confirmation
-before it closes while the form is _dirty_ — previously this required the
-`requireCloseModalConfirmationOnUnsavedChanges` flag. After a successful submit
-or a `form.reset()` the modal closes right away, and actions in the
-`<ActionGroup />` as well as the close button in the heading still close it
-immediately.
+---
 
-Nothing to do if you had the flag enabled. To keep the previous behavior, switch
-the default off (see below).
+<a id="flags-to-component-defaults-provider"></a>
+
+## `flags` is replaced by the ComponentDefaultsProvider
 
-### `flags` is replaced by the ComponentDefaultsProvider
+**Since `0.2.0-alpha.1005`** · deprecation · manual change
 
 The global `flags` object is deprecated. Application-wide defaults are defined
 with the `<ComponentDefaultsProvider />` instead, which additionally works per
@@ -224,11 +290,75 @@ Assigning a flag keeps working — it acts as the application-wide default below
 the provider and logs a deprecation warning — but the flags will be removed in a
 future release.
 
+**Apply:** Replace assignments to the global `flags` object with an equivalent
+`<ComponentDefaultsProvider defaults={{ ... }} />` wrapping the app, or the
+subtree the default should apply to.
+
+---
+
+<a id="modal-unsaved-changes-confirmation"></a>
+
+## Closing a Modal with unsaved changes is confirmed by default
+
+**Since `0.2.0-alpha.1005`** · migration · no code change needed · also applies
+to `@mittwald/flow-remote-react-components`
+
+A `Modal` that contains a react-hook-form `<Form>` now asks for confirmation
+before it closes while the form is _dirty_ — previously this required the
+`requireCloseModalConfirmationOnUnsavedChanges` flag. After a successful submit
+or a `form.reset()` the modal closes right away, and actions in the
+`<ActionGroup />` as well as the close button in the heading still close it
+immediately.
+
+Nothing to do if you had the flag enabled. To keep the previous behavior, switch
+the default off (see below).
+
+**Apply:** No code change required — if you had
+`requireCloseModalConfirmationOnUnsavedChanges` enabled, the new default matches
+it. To keep the previous behaviour (closing without confirmation), set
+`Form: { confirmModalCloseOnUnsavedChanges: false }` via
+`<ComponentDefaultsProvider />`, or its deprecated equivalent, the
+`flags.requireCloseModalConfirmationOnUnsavedChanges = false` assignment.
+
 ---
 
-## From version `0.2.0-alpha.933` to `>=0.2.0-alpha.956`
+<a id="password-tools-subpath-renamed"></a>
 
-### TableColumn: `maxWidth` removed, `width` and `minWidth` retyped
+## `password-tools` entry renamed to `mittwald-password-tools-js`
+
+**Since `0.2.0-alpha.1000`** · migration · codemod available
+
+The subpath export carrying the `@mittwald/password-tools-js` integration is
+called `@mittwald/flow-react-components/mittwald-password-tools-js`. Between
+`0.2.0-alpha.913` and `0.2.0-alpha.999` it was called
+`@mittwald/flow-react-components/password-tools`; `0.2.0-alpha.1000` reverted
+that name.
+
+```diff
+- import { Rule } from "@mittwald/flow-react-components/password-tools";
++ import { Rule } from "@mittwald/flow-react-components/mittwald-password-tools-js";
+```
+
+Only code written against a version inside that window is affected. There is no
+deprecation path and no fallback: a subpath export that no longer exists is a
+hard `TS2307` ("Cannot find module") and fails the build.
+
+**Apply:** Replace the import path
+`@mittwald/flow-react-components/password-tools` with
+`@mittwald/flow-react-components/mittwald-password-tools-js`.
+
+```shell
+npx @mittwald/flow-codemods@latest password-tools-subpath-renamed src
+```
+
+---
+
+<a id="table-column-width-props"></a>
+
+## TableColumn: `maxWidth` removed, `width` and `minWidth` retyped
+
+**Since `0.2.0-alpha.956`** · migration · manual change · also applies to
+`@mittwald/flow-remote-react-components`
 
 `maxWidth` has been removed. `width` and `minWidth` are now typed as
 `number | string`: they no longer accept `null`, and the previous
@@ -244,32 +374,33 @@ Percentage, pixel and `fr` values keep working as strings or numbers
 (`width="50%"`, `width="200fr"`, `width={300}`). Where you passed `null` to mean
 "no explicit width", omit the prop instead.
 
+**Apply:** Remove `maxWidth` from every `TableColumn`. Where `width` or
+`minWidth` was `null`, omit the prop instead — the type no longer accepts
+`null`, only `number | string`.
+
 ---
 
-## From version `0.2.0-alpha.857` to `>=0.2.0-alpha.866`
+<a id="table-render-prop-removed"></a>
+
+## Table: `render` prop removed
 
-### Table: `render` prop removed
+**Since `0.2.0-alpha.866`** · migration · manual change · also applies to
+`@mittwald/flow-remote-react-components`
 
 The `render` escape hatch on `Table` has been removed. Compose the table from
 `TableHeader`, `TableColumn`, `TableBody`, `TableRow` and `TableCell` instead.
 
+**Apply:** Replace the `render` escape hatch on `Table` with a composition of
+`TableHeader`, `TableColumn`, `TableBody`, `TableRow` and `TableCell`.
+
 ---
 
-## From version `0.2.0-alpha.837` to `>=0.2.0-alpha.846`
+<a id="color-primary-to-default"></a>
 
-### TableCell: `render` prop removed
+## Breadcrumb, HeaderNavigation, Heading, IllustratedMessage, and Link: color property "primary" renamed to "default"
 
-The `render` escape hatch on `TableCell` has been removed. Provide the cell
-content as children instead.
-
-```diff
-- <TableCell render={(cell) => <CustomCell {...cell} />} />
-+ <TableCell>
-+  <CustomCell />
-+ </TableCell>
-```
-
-### Breadcrumb, HeaderNavigation, Heading, IllustratedMessage, and Link: color property "primary" renamed to "default"
+**Since `0.2.0-alpha.846`** · migration · codemod available · also applies to
+`@mittwald/flow-remote-react-components`
 
 The `color="primary"` property has been renamed to `color="default"`.
 
@@ -280,22 +411,45 @@ The `color="primary"` property has been renamed to `color="default"`.
 
 A codemod rewrites `color="primary"` to `color="default"` on these five
 components (and leaves other components such as `Button`, where `"primary"` is
-still valid, untouched):
+still valid, untouched).
+
+**Apply:** Rewrite `color="primary"` to `color="default"` on `Breadcrumb`,
+`HeaderNavigation`, `Heading`, `IllustratedMessage`, and `Link` only — leave
+`Button` (and any other component where `"primary"` is still valid) untouched.
 
 ```shell
-npx jscodeshift \
-  -t https://raw.githubusercontent.com/mittwald/flow/refs/heads/main/packages/codemods/src/transforms/flowAlphaColorPrimaryToDefault.ts \
-  --parser tsx \
-  src
+npx @mittwald/flow-codemods@latest color-primary-to-default src
+```
+
+---
+
+<a id="table-cell-render-prop-removed"></a>
+
+## TableCell: `render` prop removed
+
+**Since `0.2.0-alpha.846`** · migration · manual change · also applies to
+`@mittwald/flow-remote-react-components`
+
+The `render` escape hatch on `TableCell` has been removed. Provide the cell
+content as children instead.
+
+```diff
+- <TableCell render={(cell) => <CustomCell {...cell} />} />
++ <TableCell>
++  <CustomCell />
++ </TableCell>
 ```
 
-Replace `src` with your sources folder.
+**Apply:** Provide the cell content as children of `TableCell` instead of a
+`render` function.
 
 ---
 
-## From version `0.2.0-alpha.801` to `>=0.2.0-alpha.802`
+<a id="password-tools-rule"></a>
+
+## password-tools: `AsyncRule` and `SyncRule` replaced by `Rule`
 
-### password-tools: `AsyncRule` and `SyncRule` replaced by `Rule`
+**Since `0.2.0-alpha.802`** · migration · codemod available
 
 The `@mittwald/flow-react-components/mittwald-password-tools-js` entry no longer
 exports `AsyncRule` and `SyncRule`. The underlying `@mittwald/password-tools-js`
@@ -309,11 +463,71 @@ merged both into a single abstract `Rule`.
 A custom rule extends `Rule` and may return its result synchronously or as a
 promise — the distinction the two classes used to encode is gone.
 
+A codemod replaces both names. A file that imported both — or one of them next
+to `Rule` — ends up with a single import.
+
+**Apply:** Replace `AsyncRule` and `SyncRule` imports from
+`@mittwald/flow-react-components/mittwald-password-tools-js` with `Rule`. Update
+custom rule classes to extend `Rule` instead.
+
+```shell
+npx @mittwald/flow-codemods@latest password-tools-rule src
+```
+
 ---
 
-## From version `0.2.0-alpha.779` to `>=0.2.0-alpha.780`
+<a id="accent-box-color-to-background-color"></a>
 
-### CartesianChart
+## AccentBox.color is now a declaration for foreground
+
+**Since `0.2.0-alpha.786`** · migration · codemod available · also applies to
+`@mittwald/flow-remote-react-components`
+
+The `color` property now controls foreground colors. Use the `backgroundColor`
+property to set the background color instead.
+
+```diff
+- <AccentBox color="gradient">
++ <AccentBox backgroundColor="gradient" />
+```
+
+`color` did not go away, it changed meaning — so this is not a rename. It used
+to accept `"blue" | "green" | "gradient" | "neutral"` and now accepts
+`"default" | "dark" | "light" | "dark-static" | "light-static"`.
+
+A codemod decides per value: a value from the new foreground union stays on
+`color`, every other literal moves to `backgroundColor`. Two cases stay
+untouched, because neither can be decided from the value alone — check them by
+hand:
+
+- `color={expression}`, where the same expression means the background in old
+  code and the foreground in new code.
+- An element that already carries `backgroundColor`, where moving `color` there
+  would overwrite the explicit value.
+
+One value changes what you see: the runtime fallback maps `"neutral"`,
+`"gradient"` and `"green"` onto the background, but not `"blue"`, so
+`<AccentBox color="blue">` currently renders the neutral background. The codemod
+turns it into `backgroundColor="blue"`, which restores the blue one.
+
+**Apply:** Move every `color` value that is not one of
+`"default" | "dark" | "light" | "dark-static" | "light-static"` to
+`backgroundColor` instead. Review `color={expression}` and any element that
+already has `backgroundColor` by hand — neither can be decided from the value
+alone.
+
+```shell
+npx @mittwald/flow-codemods@latest accent-box-color-to-background-color src
+```
+
+---
+
+<a id="cartesian-chart-restructured"></a>
+
+## CartesianChart
+
+**Since `0.2.0-alpha.780`** · migration · manual change · also applies to
+`@mittwald/flow-remote-react-components`
 
 > If you're using a _Function_ in the `dataKey` - you need to define a
 > `dataKeyLabel` as well.
@@ -403,37 +617,38 @@ const ExampleChart = typedCartesianChart<ChartData>();
 </ExampleChart.Chart>
 ```
 
----
-
-## From version `0.2.0-alpha.777` to `>=0.2.0-alpha.786`
-
-### AccentBox.color is now a declaration for foreground
-
-The `color` property now controls foreground colors. Use the `backgroundColor`
-property to set the background color instead.
-
-```diff
-- <AccentBox color="gradient">
-+ <AccentBox backgroundColor="gradient" />
-```
+**Apply:** Add `dataKeyLabel` wherever a `dataKey` is a function — a string
+`dataKey` already sets it automatically. Where a `tickFormatter` or other
+callback relied on the argument being `any`, add an explicit type check (for
+example `instanceof Date`), or switch to `typedCartesianChart<T>()` for a chart
+whose callbacks are typed from your own data shape.
 
 ---
 
-## From version `0.2.0-alpha.747` to `>=0.2.0-alpha.756`
+<a id="code-block-syntax-highlighter-removed"></a>
+
+## Removed the underlying react-syntax-highlighter library from CodeBlock
 
-### Removed the underlying react-syntax-highlighter library from CodeBlock
+**Since `0.2.0-alpha.756`** · migration · manual change · also applies to
+`@mittwald/flow-remote-react-components`
 
 We've replaced the `react-syntax-highlighter` library, which means many
 properties have been removed and the remaining ones have been simplified. See
 the
-[CodeBlock documentation](https://flow.mittwald.de/04-components/content/code-block/overview)
+[CodeBlock documentation](https://flow.mittwald.de/components/content/code-block)
 for details on what's now supported.
 
+**Apply:** Check every `CodeBlock` usage against the current props (see the
+[CodeBlock documentation](https://flow.mittwald.de/components/content/code-block))
+and remove or replace props the new implementation does not support.
+
 ---
 
-## From version `0.2.0-alpha.711` to `>=0.2.0-alpha.712`
+<a id="muted-action-error-to-abort-action-error"></a>
+
+## `MutedActionError` renamed to `AbortActionError`
 
-### `MutedActionError` renamed to `AbortActionError`
+**Since `0.2.0-alpha.712`** · migration · codemod available
 
 The error that aborts an `Action` without reporting a failure is now called
 `AbortActionError`. Its static helpers were renamed along with it.
@@ -456,11 +671,46 @@ There is no alias for the old name. The thrown error's `name` changed from
 `"MutedActionError"` to `"AbortActionError"` as well — update any code that
 matches on it.
 
+A codemod renames the class and both static helpers. It also rewrites an
+`error.name === "MutedActionError"` comparison, but only in a file that imports
+the class — a check living anywhere else cannot be recognised, so grep for the
+string once when you are done.
+
+**Apply:** Rename `MutedActionError` to `AbortActionError`, `isMutedActionError`
+to `isAbortActionError`, and `rethrowIfNotMuted` to `rethrowIfNotAborted`.
+Update any `error.name === "MutedActionError"` comparison to
+`"AbortActionError"`.
+
+```shell
+npx @mittwald/flow-codemods@latest muted-action-error-to-abort-action-error src
+```
+
+---
+
+<a id="overlay-controller-add-on-close-return-type"></a>
+
+## OverlayController.addOnClose / addOnOpen return type changed
+
+**Since `0.2.0-alpha.696`** · migration · manual change · also applies to
+`@mittwald/flow-remote-react-components`
+
+The return type changed from `() => void` to `() => unknown`
+
+**Apply:** No type change needed: the return type widened from `() => void` to
+`() => unknown`, and a `() => void` callback stays assignable. Instead, check
+every callback passed to `addOnClose`/`addOnOpen` for one that can return
+`false` — for example an arrow function whose body is an expression evaluating
+to `false`. `executeHandlers` now treats any handler returning `false` as a veto
+and cancels the close/open. A callback that returned `false` incidentally, with
+no intent to block anything, now silently cancels closes.
+
 ---
 
-## From version `0.2.0-alpha.693` to `>=0.2.0-alpha.694`
+<a id="form-resets-after-modal-close"></a>
 
-### Form: resets itself after the surrounding modal closes
+## Form: resets itself after the surrounding modal closes
+
+**Since `0.2.0-alpha.694`** · migration · no code change needed
 
 A react-hook-form `<Form>` inside a `Modal` now resets to its default values
 once the modal has closed. Previously it kept what the user had entered, so
@@ -476,19 +726,18 @@ Opt out per form with the new `autoReset` prop:
 `autoReset` also takes an object (`autoReset={{ onAfterModalClose: false }}`) so
 further reset triggers can be added without another prop.
 
----
-
-## From version `0.2.0-alpha.676` to `>=0.2.0-alpha.696`
-
-### OverlayController.addOnClose / addOnOpen return type changed
-
-The return type changed from `() => void` to `() => unknown`
+**Apply:** No code change required. To keep the previous behaviour (the form
+keeping what the user entered), pass `autoReset={false}` (or
+`autoReset={{ onAfterModalClose: false }}`) to `Form`.
 
 ---
 
-## From version `0.2.0-alpha.667` to `>=0.2.0-alpha.676`
+<a id="cartesian-chart-empty-view"></a>
+
+## CartesianChart.emptyView changed
 
-### CartesianChart.emptyView changed
+**Since `0.2.0-alpha.676`** · migration · manual change · also applies to
+`@mittwald/flow-remote-react-components`
 
 Component references are no longer accepted for `emptyView` - must be a rendered
 element now.
@@ -498,11 +747,17 @@ element now.
 + <CartesianChart emptyView={<EmptyState />} />
 ```
 
+**Apply:** Wrap the `emptyView` value in JSX — `emptyView={<EmptyState />}`
+instead of `emptyView={EmptyState}`.
+
 ---
 
-## From version `0.2.0-alpha.637` to `>=0.2.0-alpha.646`
+<a id="action-prop-to-on-action"></a>
 
-### Action: `action` renamed to `onAction`
+## Action: `action` renamed to `onAction`
+
+**Since `0.2.0-alpha.646`** · migration · codemod available · also applies to
+`@mittwald/flow-remote-react-components`
 
 `Action`'s `action` prop is now called `onAction`, which matches the naming of
 every other event prop in Flow.
@@ -519,32 +774,61 @@ prop. At runtime the old prop still works: `Action` maps it to `onAction` and
 logs a deprecation warning, and an explicit `onAction` wins. The fallback will
 be removed in a future major version.
 
-A codemod renames the prop on `Action`:
+A codemod renames the prop on `Action`.
+
+**Apply:** Rename the `action` prop on `Action` to `onAction`.
 
 ```shell
-npx jscodeshift \
-  -t https://raw.githubusercontent.com/mittwald/flow/refs/heads/main/packages/codemods/src/transforms/flowAlphaActionPropToOnAction.ts \
-  --parser tsx \
-  src
+npx @mittwald/flow-codemods@latest action-prop-to-on-action src
 ```
 
-Replace `src` with your sources folder.
+---
 
-### Removed ResetButton and SubmitButton Interfaces
+<a id="button-props-interfaces"></a>
+
+## Removed ResetButton and SubmitButton Interfaces
+
+**Since `0.2.0-alpha.646`** · migration · codemod available
 
 The `RemoteButtonElementProps`, `ResetButtonProps`, and `SubmitButtonProps`
 interfaces have been removed. Use `ButtonProps` instead.
 
+```diff
+- import type { SubmitButtonProps } from "@mittwald/flow-react-components/react-hook-form";
++ import type { ButtonProps } from "@mittwald/flow-react-components";
+```
+
+Note the entry: `ButtonProps` lives in the package root, while the removed names
+came from `react-hook-form`. A codemod moves the import along with the name. It
+covers `@mittwald/flow-react-components` only.
+`@mittwald/flow-remote-react-components` does not export `ButtonProps`, so there
+is nothing to move a remote import onto — pick your own source for the type
+there. `RemoteButtonElementProps` is left alone as well:
+`@mittwald/flow-remote-elements` still exports that name.
+
+**Apply:** Replace `ResetButtonProps`/`SubmitButtonProps` imports from
+`@mittwald/flow-react-components/react-hook-form` with `ButtonProps` from the
+package root. Leave `RemoteButtonElementProps` (from
+`@mittwald/flow-remote-elements`) alone.
+
+```shell
+npx @mittwald/flow-codemods@latest button-props-interfaces src
+```
+
 ---
 
-## From version 0.1.0 to version 0.2.0
+<a id="imports-to-package-root"></a>
+
+## Subpath imports moved to the package root
+
+**Since `0.2.0-alpha.28`** · migration · codemod available
 
 With the latest update to `@mittwald/flow-react-components`, the way package
 exports are handled has changed. You no longer need to specify subdirectories
 explicitly when importing components and utilities. Instead, imports are now
 structured in a more streamlined way.
 
-## Changes in Imports
+### Changes in Imports
 
 Previously, you had to import components and utilities from specific
 subdirectories, like this:
@@ -565,28 +849,14 @@ import { Field } from "@mittwald/flow-react-components/react-hook-form";
 import { Link } from "@mittwald/flow-react-components/nextjs";
 ```
 
-## `tsconfig.json`
+### `tsconfig.json`
 
 Set `"module": "esnext"` in your `tsconfig.json`, if you have trouble with
 missing module exports.
 
-## Migration Steps
+### Migration Steps
 
-### Use Codemod
-
-```shell
-npx jscodeshift \
-  -t https://raw.githubusercontent.com/mittwald/flow/refs/heads/main/packages/codemods/src/transforms/flow020.ts \
-  --parser tsx \
-  src
-```
-
-Replace `src` with your sources folder. If you do not use TypeScript in your
-project, use `--parser jsx`.
-
-See the [docs of jscodeshift](https://jscodeshift.com/run/cli/)
-
-### Do it manually
+#### Do it manually
 
 1. **Update all import statements** in your project according to the new
    structure.
@@ -595,16 +865,28 @@ See the [docs of jscodeshift](https://jscodeshift.com/run/cli/)
 4. **Run your test suite** to ensure no regressions were introduced by the
    migration.
 
-## Benefits of This Change
+This change shipped in `0.2.0-alpha.28`: `0.2.0-alpha.27` still published one
+export entry per component, `alpha.28` published the flat set. Neither `0.1.0`
+nor `0.2.0` was ever released as a stable version — both are alpha-only lines,
+and the first stable release of Flow is `1.0.0`.
+
+**Apply:** Rewrite every subdirectory import from
+`@mittwald/flow-react-components` to the package root, except `react-hook-form`
+and `nextjs`, which move to `@mittwald/flow-react-components/react-hook-form`
+and `@mittwald/flow-react-components/nextjs`. If you hit missing module errors,
+set `"module": "esnext"` in `tsconfig.json`.
 
-- **Simplified import statements** with a clearer structure.
-- **Better maintainability** as package updates no longer require path
-  modifications.
-- **Improved autocompletion support** in modern IDEs.
+```shell
+npx @mittwald/flow-codemods@latest imports-to-package-root src
+```
+
+---
+
+<a id="renamed-css-export"></a>
 
-## From version 0.1.0-alpha.291 to 0.1.0-alpha.292
+## Renamed CSS export
 
-### Renamed CSS export
+**Since `0.1.0-alpha.292`** · migration · manual change
 
 The CSS export `@mittwald/flow-react-components/styles` has renamed to the more
 precise name `@mittwald/flow-react-components/all.css`, because the file
@@ -616,3 +898,6 @@ as well. A documentation on how to use them is planned.
 - import "@mittwald/flow-react-components/styles";
 + import "@mittwald/flow-react-components/all.css";
 ```
+
+**Apply:** Replace the import `@mittwald/flow-react-components/styles` with
+`@mittwald/flow-react-components/all.css`.