@mittwald/flow-react-components 1.2.0-next.1 → 1.2.0-next.10

package/MIGRATION.md

@@ -21,6 +21,11 @@ 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.
 
+Every command on this page is written with `npx`, because a generated file
+cannot know your package manager. Substitute the equivalent if yours differs:
+`pnpm dlx`, `yarn dlx` (Yarn Classic has no `dlx` — it uses `npx`), or `bun x`.
+The CLI's own output does detect it and prints the right form.
+
 ---
 
 <a id="use-design-tokens-build-metadata-removed"></a>
@@ -99,8 +104,16 @@ tracked the selection both go away.
 ```
 
 **Setting a value.** The selection feeds a form or a setting. Use a
-`RadioGroup`: each `Segment` becomes a `Radio`, everything else — `Label`,
-`FieldDescription`, `FieldError`, the React Hook Form binding — stays as it is.
+`RadioGroup`: each `Segment` becomes a `RadioButton`, everything else — `Label`,
+`FieldDescription`, `FieldError`, `value`/`defaultValue`/`onChange`, the React
+Hook Form binding — stays as it is.
+
+This direction is a rename, not a restructure. The types line up:
+`SegmentedControlProps` and `RadioGroupProps` both extend
+`Omit<Aria.RadioGroupProps, "children">`, and `SegmentProps` and
+`RadioButtonProps` are the same type (`RadioButtonProps` is declared as
+`RadioProps`, which is identical to `SegmentProps`). Only
+`containerBreakpointSize` has no counterpart — see the note at the end.
 
 ```diff
 - <SegmentedControl defaultValue="debit">
@@ -108,15 +121,56 @@ tracked the selection both go away.
     <Label>Zahlungsart</Label>
 -   <Segment value="debit">Lastschrift</Segment>
 -   <Segment value="invoice">Rechnung</Segment>
-+   <Radio value="debit">Lastschrift</Radio>
-+   <Radio value="invoice">Rechnung</Radio>
++   <RadioButton value="debit">Lastschrift</RadioButton>
++   <RadioButton value="invoice">Rechnung</RadioButton>
     <FieldDescription>Jederzeit änderbar</FieldDescription>
 - </SegmentedControl>
 + </RadioGroup>
 ```
 
-There is no codemod. Both replacements change the structure, and picking the
-right one is a decision per usage, not a rename.
+**Always `RadioButton`, not `Radio`.** A `RadioGroup` also accepts a plain
+`Radio`, and it takes the same props, so both would compile — but `RadioButton`
+is the replacement for a `Segment`. The appearance still changes: `RadioButton`
+does not reproduce the segmented control's joined row, which came from
+`Segment`'s own `flex: 1` and collapsed borders. See the
+[RadioGroup docs](https://flow.mittwald.de/components/form-controls/radio-group).
+
+#### Three things the Tabs direction changes
+
+**The controlled-state props are named differently.** `SegmentedControl` takes
+`value` / `defaultValue` / `onChange` (it is a radio group); `Tabs` takes
+`selectedKey` / `defaultSelectedKey` / `onSelectionChange`. Nothing carries over
+by name here, unlike the `RadioGroup` direction.
+
+**The group `Label`.** `SegmentedControl` is a form field — it wraps
+react-aria's `RadioGroup` — so a `<Label>` inside it is a field label. `Tabs`
+has no equivalent slot, and a tab list labels itself through its tab titles. The
+`Label` therefore cannot move into `Tabs`, but its text has somewhere to go:
+
+- into the surrounding `Section`'s `Heading`, when the group wants a visible
+  title
+- into `aria-label` on `Tabs`, when it does not — that names the tab list for
+  screen readers without showing the name
+- nowhere, when the surrounding heading already names the group
+
+A `Label` on its own is **not** a signal that the usage was a `RadioGroup` case
+— plenty of content switchers were authored with one, because the component
+required a field label.
+
+**Panels that register form fields.** Moving the switched-in content into a
+`Tab` does not change when it mounts. `Tab` renders its panel with
+`shouldForceMount` and wraps `Content` and `Section` in
+`<Activity isActive={…}>`, so every tab's subtree is mounted and keeps its state
+— an inactive tab is hidden, not unmounted. React Hook Form fields inside a tab
+stay registered across a tab switch, exactly as they did as siblings below a
+`SegmentedControl`.
+
+There is no codemod, and the reason is the choice rather than the edit. Which
+replacement is right cannot be decided from the source: a value-setting usage
+and a content switcher look alike at the call site, and only the surrounding
+intention separates them. The `RadioGroup` direction would be mechanical **once
+that decision is made** — if you have many usages that all go that way, a
+find-and-replace of `SegmentedControl`/`Segment` gets you most of it.
 
 `SegmentedControl` and `Segment` (and the `flr-segmented-control` /
 `flr-segment` remote elements) keep working unchanged and will be removed in a
@@ -128,8 +182,18 @@ 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.
+displayed content, or with `RadioGroup` when it sets a value. Pick per usage.
+The two directions cost very different amounts of work. Towards `RadioGroup` it
+is a prop-compatible rename: `SegmentedControl` → `RadioGroup` and `Segment` →
+`RadioButton` (always `RadioButton`, not `Radio`; it takes exactly `Segment`'s
+props), with `value`/`defaultValue`/`onChange` and a `Label` child all carrying
+over. Only `containerBreakpointSize` has no counterpart, and the joined row is
+not reproduced. Towards `Tabs` it is structural: the state props are
+`selectedKey`/`defaultSelectedKey` rather than `value`/`defaultValue`, there is
+no `Label` slot (the group label moves to the surrounding `Heading`, or to
+`aria-label` on `Tabs` when it should not be visible, or goes away), and the
+switched panels move inside the tabs — where they stay mounted, so form fields
+in them keep their registration.
 
 ---
 
@@ -353,6 +417,94 @@ npx @mittwald/flow-codemods@latest password-tools-subpath-renamed src
 
 ---
 
+<a id="tabs-navigation-usage-to-tab-navigation"></a>
+
+## Tabs restyled; navigation usage moves to TabNavigation
+
+**Since `0.2.0-alpha.977`** · migration · manual change · also applies to
+`@mittwald/flow-remote-react-components`
+
+`Tabs` restyled: the tab list now fills the available width with equal-size tabs
+and a shared, animated indicator that slides between them, instead of the
+previous fit-content tabs that each carried their own hover/pressed/selected
+background. Nothing else about `Tabs` changed — same props, same panels, same
+collapsing behavior. If `Tabs` switches content within a page, there is nothing
+to do; the new look applies on upgrade.
+
+**Real navigation has a proper home now.** React Aria's `Tab` (which `TabTitle`
+extends) accepts the same routing props as a plain link — `href`, `target`,
+`routerOptions`, … — so a `Tabs` could always double as a navigation control:
+give a `TabTitle` an `href` and selecting it pushed a real route change while
+the row still looked and behaved like tabs otherwise. That usage only reached
+for `Tabs` because nothing else looked right for it. Now there is
+`TabNavigation`, introduced in the same version specifically for this case — and
+it keeps the visual language the old `Tabs` used to have.
+
+```diff
+- <Tabs selectedKey={pathname}>
+-   <Tab id="/apps">
+-     <TabTitle href="/apps">Apps</TabTitle>
+-   </Tab>
+-   <Tab id="/container">
+-     <TabTitle href="/container">Container</TabTitle>
+-   </Tab>
+- </Tabs>
++ <TabNavigation aria-label="Projekt-Navigation">
++   <Link href="/apps" aria-current={pathname === "/apps" ? "page" : undefined}>
++     Apps
++   </Link>
++   <Link
++     href="/container"
++     aria-current={pathname === "/container" ? "page" : undefined}
++   >
++     Container
++   </Link>
++ </TabNavigation>
+```
+
+#### What moves and what doesn't
+
+**The children.** `Tab` / `TabTitle` / the panel disappear; `TabNavigation`
+takes plain `Link` children directly. There is no panel, because the destination
+page's content lives on that route, not inside the component.
+
+**The active state.** `selectedKey` / `defaultSelectedKey` / `onSelectionChange`
+have no counterpart — `TabNavigation` does not track selection itself. Each
+`Link` marks itself current with `aria-current="page"`, which the app's router
+already knows how to derive (e.g. from the current pathname), the same way it
+would for any other navigation link.
+
+**Status icons.** An `AlertIcon` moves from inside `TabTitle` to inside the
+`Link`.
+
+**Collapsing.** The two do this differently. `Tabs` collapses all at once: as
+soon as any tab stops fitting, the whole tab list turns into a single button
+showing the active tab, which opens every tab in a context menu. `TabNavigation`
+collapses incrementally: links are hidden one by one as space runs out, and only
+those that no longer fit move into the "More" button's menu — the rest stay
+visible as ordinary links.
+
+There is no codemod: only the surrounding code knows whether a given `Tabs`
+usage was real navigation (an `href` on `TabTitle`, or a route push from
+`onSelectionChange`) or a genuine content switcher that merely looked similar
+before this change — the two are indistinguishable from the source alone.
+
+**Apply:** Tabs' rendering changed: the tab list now fills the available width
+with equal-size tabs and a shared, animated indicator that slides between them,
+replacing the previous fit-content tabs that each carried their own
+hover/pressed/selected background. Nothing else about `Tabs` changed, and a
+`Tabs` that switches content within a page needs no code change — the new look
+applies on upgrade. Where `Tabs` was used to fake real navigation instead — a
+`TabTitle` given an `href` (`Aria.Tab`'s routing props: `href`, `target`,
+`routerOptions`, …) so selecting it pushed a real route change — replace it with
+`TabNavigation`: plain `Link` children instead of `Tab`/`TabTitle`/panels,
+`aria-current="page"` on the active `Link` instead of
+`selectedKey`/`defaultSelectedKey`/`onSelectionChange`. `TabNavigation` keeps
+the visual language the old `Tabs` used to have, because it now owns that use
+case.
+
+---
+
 <a id="table-column-width-props"></a>
 
 ## TableColumn: `maxWidth` removed, `width` and `minWidth` retyped
@@ -774,9 +926,41 @@ 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`.
+#### The type changed too
+
+`onAction` is typed `ActionFn`, which is `(...args: unknown[]) => unknown`. A
+function that declares a parameter of any narrower type is not assignable to it,
+because the parameter would receive `unknown`:
+
+```
+Type '(options?: CloseOptions | undefined) => void' is not assignable to type 'ActionFn'.
+  Types of parameters 'options' and 'args' are incompatible.
+    Type 'unknown' is not assignable to type 'CloseOptions | undefined'.
+```
+
+Wrap the call instead of passing the reference:
+
+```diff
+- <Action onAction={controller.close}>
++ <Action onAction={() => controller.close()}>
+```
 
-**Apply:** Rename the `action` prop on `Action` to `onAction`.
+Only function **references** are affected. An inline arrow
+(`onAction={() => …}`), a zero-parameter function, and anything already
+accepting `unknown` are all fine.
+
+A codemod renames the prop. It deliberately does not wrap: whether the
+referenced function declares a parameter cannot be decided from the source —
+that needs type information — and wrapping everything would silently drop the
+arguments `Action` passes to handlers that do accept them.
+
+**Apply:** Rename the `action` prop on `Action` to `onAction`. Not only a
+rename: the new prop is typed `ActionFn` (`(...args: unknown[]) => unknown`), so
+a function _reference_ that declares a parameter no longer type-checks and needs
+wrapping — `onAction={() => controller.close()}` rather than
+`onAction={controller.close}`. Check every site where you passed a reference
+rather than an inline arrow; the codemod renames the prop but cannot decide this
+one from the source.
 
 ```shell
 npx @mittwald/flow-codemods@latest action-prop-to-on-action src