@mittwald/flow-react-components 1.6.0-next.19 → 1.6.0-next.20

package/AGENTS.md

@@ -352,8 +352,8 @@ item 4 in the
 - **Tests that pass without the fix.** Revert the fix and watch the test fail
   before committing it. If it cannot fail, it guards nothing; say in the PR how
   you verified the fix instead. The `optimizeDeps` entry under
-  [Common failures](https://github.com/mittwald/flow/blob/main/AGENTS.md#common-failures)
-  in the root AGENTS.md shows one way a test passes in both directions.
+  [Common failures](#common-failures) below shows one way a test passes in both
+  directions.
 
 Run: `pnpm nx test:unit components`,
 `pnpm nx test:browser components --browser.name=webkit`. The browser targets
@@ -660,3 +660,102 @@ Easy-to-miss conventions not spelled out above. Full details and examples in
 - **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.
+
+## Common failures
+
+Symptom → cause → fix for authoring components. Repo-wide ones are in the
+[root AGENTS.md](https://github.com/mittwald/flow/blob/main/AGENTS.md#common-failures).
+
+- **Symptom:** `test:compile` fails on a new component — the
+  `flowComponent("X", …)` name/props type isn't assignable
+
+  **Cause:** `flowComponent` names are typed as `keyof` a hand-maintained props
+  registry
+
+  **Fix:** Register the props type in
+  `packages/components/src/components/propTypes/index.ts` (see
+  [The flowComponent factory](#the-flowcomponent-factory))
+
+- **Symptom:** `test:compile` fails in unrelated shared code with
+  **`Property 'children' does not exist on type 'Partial<XProps>'`** right after
+  you registered a new component
+
+  **Cause:** `dynamic()` and other shared helpers are typed over the **union of
+  every** registered props type, so code reading `p.children` breaks as soon as
+  one registered component has no `children` (`Field.tsx`,
+  `flowComponent.browser.test.tsx`)
+
+  **Fix:** Declare `children?: never` on the new props type. It keeps the union
+  accessible and documents that the component takes no children — do **not** add
+  a real `children` slot you then ignore
+
+- **Symptom:** A `ReactElement`-valued prop renders fine in the visual suite's
+  **Remote** environment but kills a real remote connection with
+  **`DataCloneError: Symbol(react.transitional.element) could not be cloned`**
+  (the host then shows `Remote rendering failed: Timeout reached`)
+
+  **Cause:** The prop was generated as a **remote property**, and properties
+  travel through `postMessage`/structured clone, which cannot carry a React
+  element. `remote-dom-react` turns an element-valued prop into a slotted child
+  _only_ when the element declares it as a slot
+  (`Element.remoteSlotDefinitions.has(prop)`), and the generator declares a slot
+  only for props typed exactly `ReactNode` or listed in `@flr-slot-props`
+  (`dev/remote-components-generator/lib/propClassifiers.ts`)
+
+  **Fix:** Add `@flr-slot-props <propA>, <propB>` to the component's JSDoc and
+  regenerate — the prop then arrives as a slotted child and any React subtree
+  works, including a raw `<svg>` or a Tabler icon. The visual suite's **Remote**
+  environment does serialize (a MessageChannel through
+  `FlowThreadSerialization`), but `FlowThreadSerialization` drops React values
+  to `null` with a `console.error` before `postMessage` ever sees them — so the
+  suite renders a component missing the prop, not the `DataCloneError`. Read the
+  console, or verify in `apps/remote-dom-demo` over the iframe connection
+
+- **Symptom:** A function prop works locally but its result is garbage remotely
+  — a formatter renders `[object Promise]`, a predicate is always truthy
+
+  **Cause:** The prop is a **remote property**, and
+  `FlowThreadSerialization.isSerializableByBase` accepts any function, so
+  `@quilted/threads` sends it as a proxy. Calling a proxy is a round trip, so
+  the host gets a **Promise**, never the value. Only `on*` events are safe by
+  construction — they are fire-and-forget
+
+  **Fix:** Either type the prop's return as `Promise<T> | T` and have the host
+  `await` it (`ChartTooltip`'s formatters do), or drop it from the remote
+  surface with `@flr-ignore-props` (`XAxis`/`YAxis` `tickFormatter` do) and
+  regenerate. `checkSerializableProps` now fails generation on new ones; the
+  pre-existing set is listed in `acknowledgedValueReturningProps`
+
+- **Symptom:** A `components` browser test keeps **passing** after you change
+  `packages/icons` — including a test written to fail on exactly that change.
+  The build is not the problem: `pnpm nx build icons` runs `tsc` and `dist`
+  holds the new code
+
+  **Cause:** `packages/components/vite.config.ts` lists `@mittwald/flow-icons`
+  in `optimizeDeps.include`, so vite pre-bundles it. The prebundle is keyed on
+  the lockfile and the config, not on the contents of a linked workspace
+  package's `dist` — so a rebuilt `dist` does not invalidate it and the test
+  keeps loading the old bundle
+
+  **Fix:** Delete `packages/components/node_modules/.vite*` after rebuilding.
+  And confirm a new regression test actually fails without its fix: this one
+  passed in both directions, which is the only symptom you get
+
+- **Symptom:** `stylelint` fails with **`flow/no-unknown-global-flow-class`** —
+  a `:global(.flow--…)` name resolves to nothing
+
+  **Cause:** The class-name generator
+  (`packages/components/dev/vite/cssModuleClassNameGenerator.ts`) **drops the
+  suffix when it equals the component name**, so `ColumnLayout`'s
+  `.columnLayout` compiles to `flow--column-layout`, not
+  `flow--column-layout--column-layout`. The names cannot be derived by hand, and
+  a component that moves leaves every reference to it dead
+
+  **Fix:** Copy the name from the component's committed `*.module.d.scss.ts` —
+  that is what the rule checks against — or take the rule's "Did you mean"
+  suggestion. Just added the class? Regenerate the stubs first:
+  `pnpm nx build:scss-types components`. The same applies to ESLint's
+  `flow/no-unknown-flow-class`, which checks hardcoded `flow--…` strings in
+  TS/TSX (#3095). Before the rule (#3091) this class of bug failed completely
+  silently: no build error, no console warning, and the docs site and Storybook
+  kept rendering