@mittwald/flow-react-components 1.1.18 → 1.1.20

package/AGENTS.md

@@ -342,6 +342,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.

package/MIGRATION.md

@@ -28,6 +28,68 @@ 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>
 
 ## useDesignTokens(): no longer returns style-dictionary build metadata