@mittwald/flow-react-components 1.2.0-next.4 → 1.2.0-next.41

package/AGENTS.md

@@ -158,6 +158,15 @@ Remote generation details:
   output, because the host has to call it: that needs an eager slot or
   `@flr-ignore-props`. `checkSerializableProps` **fails generation** on any such
   prop, so a new one cannot ship.
+- **A function property's return value is a Promise on the host.** Functions do
+  cross — as thread proxies — but calling one is a round trip. Type the return
+  as `Promise<T> | T` and await it on the host (`ChartTooltip`'s formatters), or
+  keep the prop off the remote surface with `@flr-ignore-props` (`XAxis`/`YAxis`
+  `tickFormatter`). A host that reads the result synchronously gets the Promise
+  itself — recharts concatenated it into every tick as `[object Promise]`.
+  `checkSerializableProps` fails generation on a new one; the pre-existing set
+  is listed in `acknowledgedValueReturningProps`, which can neither grow nor go
+  stale.
 - `@flr-ignore-props` excludes props that must not cross the remote boundary —
   either because they cannot be serialized, or because they could do **too much
   on the host side**. A global ignore list lives in
@@ -229,6 +238,17 @@ if ("action" in props) {
   Group repeated variants in local mixins.
 - Structure sections with comments: `/* Elements */`, `/* States */`,
   `/* Size */`, `/* Variants */`.
+- **A `z-index` is scoped by the nearest ancestor stacking context** — mark that
+  element `isolation: isolate` explicitly. `position: relative`, a scroll
+  container (`overflow: auto`) and a flex/grid parent are **not** stacking
+  contexts, so without it the value competes with the whole page instead of the
+  siblings it was written for. A `transform` animation in between is one only
+  _while it runs_, so the scope otherwise changes with the animation state.
+  Isolating does not reorder anything inside the component: among positioned
+  siblings, `z-index: auto` and a `0`-equivalent stacking context paint in the
+  same step, in tree order. The exception is an element portalled into
+  `document.body` (`NotificationContainer`) — that one sits in the root stacking
+  context by construction and cannot be scoped; say so in a comment.
 - **Overriding a dependency that injects its own stylesheet** (CodeMirror,
   react-easy-crop, FontAwesome) needs `@layer flow.unlayered { … }`: their
   `<style>` elements are unlayered, and unlayered CSS beats layered CSS
@@ -342,6 +362,19 @@ Easy-to-miss conventions not spelled out above. Full details and examples in
   must affect layout.
 - **Controllers coexist with declarative props** — overlay-like APIs support
   controlled/uncontrolled props _and_ a controller object, not one or the other.
+- **A component without `value` and without `defaultValue` still has to render
+  as controlled** — react-aria's `useControlledState` reads only `undefined` as
+  uncontrolled. A component that mirrors the value in its own state therefore
+  hands react-aria `undefined` on the first render and a real value after the
+  first change: the value changes owner mid-flight, and React and react-aria
+  warn `A component changed from uncontrolled to controlled`. Pass a sentinel
+  instead of `undefined` — `null` where "nothing selected yet" is representable
+  (`Tabs`' `selectedKey`), otherwise the type's empty value (`""` for text,
+  `NaN` for a number, `null` for a date range — `useControlledHostValueProps`'
+  `emptyValue`). Mind `??` once the sentinel is `null`: a caller-supplied `null`
+  must not fall through to `defaultValue`. Nothing breaks visibly, and a
+  component holding its own document state (`CodeEditor`) does not even warn —
+  it changes owner silently.
 - **Complex behavior is split by vocabulary** — `components/` for render,
   `hooks/` for behavior, `lib/` for pure transforms, `models/` for durable
   state.
@@ -360,6 +393,20 @@ Easy-to-miss conventions not spelled out above. Full details and examples in
   icon-only padding silently do not apply. Wrap it — `<Icon><IconFoo /></Icon>`
   — as the [Icon page](https://flow.mittwald.de/components/content/icon)
   documents. Nothing errors: types, lint and the console stay clean.
+- **A collection child is rendered twice** — react-aria renders the children of
+  a collection (`Select`, `ComboBox`, `Autocomplete`, `Menu`, `ListBox`, `Tree`,
+  …) once into its hidden collection document and once for real. Both renders
+  are full component instances, so anything derived per instance happens twice
+  for one logical element: `useId` returns two ids, effects run twice, and every
+  registration into shared state lands twice. Whatever such a child registers
+  therefore needs an id derived from the element itself, not a generated one —
+  options pass their collection key as the tunnel's `staticEntryId`
+  (`Option/optionsTunnel.ts`), and a new tunnelled collection child must do the
+  same. Without it the tunnel exit renders each child twice: the keys stay
+  unique, so the DOM and the tests look right, but the collection holds two
+  nodes per key and its `prevKey`/`nextKey` chain closes into a ring — `ArrowUp`
+  on the first item wraps to the last, and react-stately's focus restoration
+  walks `getKeyBefore` forever and freezes the tab (#3146).
 - **Universal exports are deliberately explicit** — remote-safe values and their
   types are curated in `flr-universal.ts` independently of the main public
   surface; adding to `public.ts` does not add them there.

package/MIGRATION.md

@@ -21,6 +21,73 @@ 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="option-value-inferred-from-mixed-children"></a>
+
+## Option: value is inferred from mixed children
+
+**Since `1.1.12`** · migration · no code change needed · also applies to
+`@mittwald/flow-remote-react-components`
+
+An `Option` used to infer its `textValue` — and, through it, its `value` — only
+when its children were exactly one text node. Text next to any element left both
+undefined, so react-aria assigned the option a key off a render-order counter:
+
+```tsx
+<Select>
+  <Option>
+    Millennium Falcon <Badge>Latest</Badge>
+  </Option>
+  <Option>X-Wing</Option>
+</Select>
+```
+
+| Option                        | key before     | key now             |
+| ----------------------------- | -------------- | ------------------- |
+| `Millennium Falcon` + `Badge` | `react-aria-1` | `Millennium Falcon` |
+| `X-Wing`                      | `X-Wing`       | `X-Wing`            |
+
+The key is what the field reports as its selected value and what `defaultValue`
+has to match, so the old key made the field submit a meaningless string, could
+not be preselected, and shifted when unrelated markup around it changed.
+
+Only text that is a child itself contributes — text inside an element child does
+not, so the option above is `"Millennium Falcon"` and not
+`"Millennium Falcon Latest"`.
+
+An `Option` with no text among its children at all still has no key to infer,
+and now says so on the console instead of failing silently:
+
+```tsx
+// logs: An <Option> has no 'value' and none could be inferred from its children…
+<Option>
+  <Text>Millennium Falcon</Text>
+</Option>
+```
+
+Give those options a `value`:
+
+```diff
+- <Option>
++ <Option value="millennium-falcon">
+    <Text>Millennium Falcon</Text>
+  </Option>
+```
+
+**Apply:** No code change required for the option itself. An `Option` whose
+children are text plus an element — text and a `Badge`, text and an icon — now
+carries that text as its key, where it previously fell back to react-aria's
+generated `react-aria-N`. Check anywhere such a key was read back: a stored or
+server-side selection, a `defaultValue`/`value` matched against it, or a test
+asserting on it. Pass an explicit `value` to pin the key to something other than
+the display text.
+
 ---
 
 <a id="use-design-tokens-build-metadata-removed"></a>
@@ -412,11 +479,99 @@ 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
 
-**Since `0.2.0-alpha.956`** · migration · manual change · also applies to
+**Since `0.2.0-alpha.956`** · migration · codemod available · also applies to
 `@mittwald/flow-remote-react-components`
 
 `maxWidth` has been removed. `width` and `minWidth` are now typed as
@@ -433,9 +588,24 @@ 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.
 
+A codemod removes `maxWidth` — the prop is gone from the type, so an explicit
+attribute is wrong at any value, an expression included — and removes a `width`
+or `minWidth` written as the literal `null`.
+
+It declines what it cannot decide from the source: `width={maybeNull}` could be
+anything at runtime, and a spread's contents are invisible. Both keep their
+props and need a look by hand.
+
 **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`.
+`null`, only `number | string`. A codemod does both for the cases it can decide
+from the source. Two it declines: a `width`/`minWidth` whose value is an
+expression (`width={maybeNull}`), and a spread that might carry `maxWidth`
+(`<TableColumn {...props} />`). Check those by hand.
+
+```shell
+npx @mittwald/flow-codemods@latest table-column-width-props src
+```
 
 ---
 
@@ -856,18 +1026,39 @@ 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.
+A codemod renames the prop and wraps the reference.
+
+Whether a reference _needs_ wrapping is not decidable from the source — that
+needs type information. Performing the wrap does not need it: `() => fn()` calls
+what `Action` would have called, and `onAction` takes no arguments. So the wrap
+fixes the reference that needed it and changes nothing for the rest, which makes
+the decision unnecessary.
+
+Wrapped: a plain identifier and a member expression (`close`,
+`controller.close`, `this.handleSave`). Left alone: an arrow function and a
+function expression, which already are the handler; a call (`makeHandler()`,
+`close.bind(controller)`), which produces it; and anything that is not one
+reference (`isOpen ? close : open`, `onClose ?? noop`, `controller?.close`).
+
+Two wraps are worth a look afterwards. A handler that read the event `Action`
+forwards — undocumented, but it does forward the trigger's event — stops
+receiving it. And `onAction={props.onAction}`, where the reference may be
+`undefined`: passing it was fine, calling it is not, so TypeScript now reports
+the call and wants a guard.
 
 **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.
+`onAction={controller.close}`. A codemod does both. It wraps every bare
+reference (`close`, `controller.close`), because the wrap is a no-op for a
+reference that did not need it. It leaves a value that already is the handler or
+produces one — an arrow function, a function expression, a call like
+`makeHandler()` or `close.bind(controller)` — and anything that is not one
+reference, such as `isOpen ? close : open` or `controller?.close`. Two wraps to
+look at afterwards: a handler that read the event `Action` forwards stops
+receiving it, and a possibly-undefined reference (`onAction={props.onAction}`)
+becomes a call TypeScript rejects — add the guard it asks for.
 
 ```shell
 npx @mittwald/flow-codemods@latest action-prop-to-on-action src
@@ -977,7 +1168,7 @@ npx @mittwald/flow-codemods@latest imports-to-package-root src
 
 ## Renamed CSS export
 
-**Since `0.1.0-alpha.292`** · migration · manual change
+**Since `0.1.0-alpha.292`** · migration · codemod available
 
 The CSS export `@mittwald/flow-react-components/styles` has renamed to the more
 precise name `@mittwald/flow-react-components/all.css`, because the file
@@ -990,5 +1181,15 @@ as well. A documentation on how to use them is planned.
 + import "@mittwald/flow-react-components/all.css";
 ```
 
+A codemod rewrites the specifier in every JavaScript and TypeScript form that
+names a module. It cannot reach a `.css` or `.scss` file, so an `@import` of the
+old path there needs a manual search.
+
 **Apply:** Replace the import `@mittwald/flow-react-components/styles` with
-`@mittwald/flow-react-components/all.css`.
+`@mittwald/flow-react-components/all.css`. A codemod does this for JavaScript
+and TypeScript files. An `@import` of the old path inside a `.css` or `.scss`
+file is not covered — search for it by hand.
+
+```shell
+npx @mittwald/flow-codemods@latest renamed-css-export src
+```