@mittwald/flow-react-components 1.6.0-next.4 → 1.6.0-next.40

package/AGENTS.md

@@ -333,6 +333,28 @@ if ("action" in props) {
 | `*.test.ts(x)` (unit)                      | Pure logic in `src/lib/` or component utility functions.                                                                                                                                 |
 | `*.test-types.tsx`                         | Generic/typed public APIs — `expectTypeOf` plus `@ts-expect-error` negative assertions.                                                                                                  |
 
+A bug fix gets a regression test when it changes behavior this table covers, or
+rendered output the visual suite covers
+(`packages/remote-react-components/src/tests/visual`, see Definition of Done
+item 4 in the
+[root AGENTS.md](https://github.com/mittwald/flow/blob/main/AGENTS.md#definition-of-done--component-work))
+— not by default. Leave out:
+
+- **Wiring of a single prop** — "the consumer `className` reaches the root",
+  "`aria-label` is forwarded". A test for one prop is arbitrary: every other
+  prop would need the same. A whole class of wiring bugs (`className` merge
+  order, a props spread) belongs in a lint rule or a shared contract helper like
+  `testFormFieldContract`.
+- **A spy on a function prop the component consumes** — `sortBy`, `filterBy`, a
+  formatter. Assert the result it produces, not that it ran. `on*` event props
+  are the exception: the call is what the consumer observes, so a spy is the
+  assertion.
+- **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](#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
 install the Playwright browsers for you **locally**; `pnpm test:browser:prepare`
@@ -404,75 +426,15 @@ Four traps cost time in every new browser test:
   technology lands on (the input or the group), spread after `rest`: its
   `aria-describedby` references the error only while one is rendered and already
   contains the consumer's own ids. See
-  [Building a form field](#building-a-form-field).
+  [FORM_FIELDS.md](https://github.com/mittwald/flow/blob/main/packages/components/FORM_FIELDS.md).
 
 ## Building a form field
 
 A form field is any component a user enters a value with — anything that calls
-`useFieldComponent`. It supports the whole contract below, end to end: prop →
-behavior → styling → `Label` state → test. Gaps in existing fields are tracked
-in #3368.
-
-| Aspect                          | Requirement                                                                                                                                                                                                                     |
-| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `isDisabled`                    | Control is not operable (`disabled` or `aria-disabled`), disabled styling via the `formControl` mixin, `Label` disabled. Every inner button too.                                                                                |
-| `isReadOnly`                    | Value cannot change, control still focusable and submitted. Native `readonly` / react-aria's `isReadOnly` where it exists, otherwise `aria-readonly` — never by disabling the control. Inner buttons that change the value off. |
-| `isRequired`                    | `required` or `aria-required` on the control; `Label` drops its "optional" marker (`useFieldComponent` does that).                                                                                                              |
-| `isInvalid`                     | `aria-invalid` on the control, invalid styling, `FieldError` rendered and linked.                                                                                                                                               |
-| `validationBehavior`            | `"native"` blocks form submission on a constraint violation, `"aria"` does not. react-hook-form's `Field` passes `"aria"`.                                                                                                      |
-| `Label` / `FieldDescription`    | Children slots via `useFieldComponent`; `Label` names the control. `controlProps` (with `aria-describedby`) land on the **focusable control** (or the group of a grouped control), not on a wrapper `div`.                      |
-| `name` / `form`                 | The value is in the `FormData` of the surrounding (or `form`-referenced) form. A custom control renders a hidden input.                                                                                                         |
-| `defaultValue` / `value`        | Both work; `onChange` reports user changes with the field's own value type (a `number` field reports a `number`).                                                                                                               |
-| `ref`                           | Points at the focusable control — react-hook-form focuses it on a validation error.                                                                                                                                             |
-| `autoFocus`, `onFocus`/`onBlur` | Reach the focusable control. react-hook-form marks a field touched via `onBlur`.                                                                                                                                                |
-
-An exception needs a reason that holds for the field's nature (a `Slider` always
-has a value, so it has no required state) — not "not implemented yet".
-
-Checklist beyond the component itself:
-
-- **Contract test.** Call `testFormFieldContract`
-  (`src/tests/formFieldContract/`) in the field's `*.browser.test.tsx`. The
-  adapter renders the field, names its control, two values (the first one
-  submits an entry, the two submit different entries), their `FormData` entries
-  and a user interaction that changes the value. The interaction passes `force`
-  on, so the test can also try it on a disabled or read-only field.
-  `getValueButtons` narrows the inner buttons a read-only field turns off; it
-  defaults to all. Justified exceptions go in `exceptions` with their reason. An
-  excepted aspect must fail on one of its own expectations — once it passes, or
-  fails on a lookup or a timeout instead, the run fails:
-
-  ```tsx
-  testFormFieldContract("TextField", {
-    render: (props) => <TextField {...props} />,
-    getControl: (screen) => screen.getByRole("textbox"),
-    values: ["foo", "bar"],
-    toFormValue: (value) => value,
-    changeValue: async (screen, { force }) => {
-      await userEvent.fill(screen.getByRole("textbox"), "bar", { force });
-    },
-  });
-  ```
-
-  It checks behavior and ARIA, not looks — the disabled, read-only and invalid
-  states also get scenarios in the field's visual test
-  (`packages/remote-react-components/src/tests/visual`).
-
-- **react-hook-form.** Register the field in the props context of
-  `src/integrations/react-hook-form/components/Field/Field.tsx`. `Field` passes
-  `name`, `value` and `defaultValue` together, `onChange`, `onBlur`, `ref`,
-  `form`, `isRequired`, `isReadOnly`, `isInvalid` and `validationBehavior` —
-  spread the rest props through instead of destructuring a fixed list, or they
-  are dropped silently. A field whose value prop is not `value` gets it mapped
-  there (`selectedKey` for `ComboBox`, `isSelected` for `Checkbox`). `Field`
-  does not pass `isDisabled` yet (#3368).
-- **Remote.** A field that mirrors its value with `useControlledHostValueProps`
-  passes the type's empty value (see the controlled-from-the-first-render
-  convention below). A text input among them also needs its `flr-*` tag in
-  `controlledComponentNames`
-  (`packages/remote-react-components/src/lib/createRemoteComponent.ts`), or it
-  drops characters under fast typing
-  ([docs/remote-ui.md](https://github.com/mittwald/flow/blob/main/docs/remote-ui.md)).
+`useFieldComponent`. Building or changing one → read
+[FORM_FIELDS.md](https://github.com/mittwald/flow/blob/main/packages/components/FORM_FIELDS.md):
+the contract it supports end to end, `testFormFieldContract`, and the
+react-hook-form and remote wiring.
 
 ## Every remote binding reads this package
 
@@ -513,29 +475,12 @@ to make a rule stick.
 
 ## Public API surfaces
 
-| Export                                                          | Contents                                                                                                                                                                                                                                            |
-| --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `.` (default)                                                   | Everything listed **manually** in `src/components/public.ts` — new public components must be added there.                                                                                                                                           |
-| `./internal`                                                    | Advanced internals (`flowComponent`, prop helper types, …).                                                                                                                                                                                         |
-| `./flr-universal`                                               | Curated subset that works local _and_ remote. Adding to `public.ts` does **not** add here.                                                                                                                                                          |
-| `./tunnel`                                                      | `@mittwald/react-tunnel` re-exported (`src/index/tunnel.ts`) plus `getTunnelProviderId`, so a consumer's own tunnels share Flow's module instance instead of creating a second React context.                                                       |
-| `./nextjs`, `./react-hook-form`, `./mittwald-password-tools-js` | Integrations (`src/integrations/`): wrappers around third-party dependencies that not every consumer should pay for — they get their own export entry instead of entering the core surface.                                                         |
-| `./all.css`, `./all-layered.css`                                | Bundled stylesheet, plain and `@layer`-wrapped.                                                                                                                                                                                                     |
-| `./component-index`                                             | Generated consumer-facing index: every public component with its status and its own props (`dev/component-index/`). What the docs site's prop tables read, and the one prop dataset a consumer's agent should use.                                  |
-| `./doc-properties`                                              | `react-docgen-typescript` output in its raw `ComponentDoc[]` shape, filtered to the props a consumer can act on. Prefer `./component-index`. The unfiltered dump the generators above read is `.cache/doc-properties.json`, which is not published. |
-
-**Adding any new export entry?** Add the subpath to `keptSubpaths` in
-`packages/codemods/src/migrations/imports-to-package-root/transform.ts`. That
-codemod collapses subpath imports onto the package root with a catch-all `else`,
-so a subpath that is not listed gets flattened onto a root that does not export
-its names. The guard beside the transform fails the codemods unit tests when you
-forget.
-
-**Adding a new integration export entry?** Also register it in the component
-status registry so it is covered: add the entry to `STATUS_EXPORT_ENTRIES`
-(`dev/status-registry/exportEntries.ts`) — the `FlowExportEntry` union and the
-registry regenerate from it. A generation-time guard fails if an entry resolves
-to zero components.
+Adding or changing an export entry (`.`, `./internal`, `./flr-universal`, an
+integration, a stylesheet or data entry) → read
+[EXPORTS.md](https://github.com/mittwald/flow/blob/main/packages/components/EXPORTS.md):
+what each entry holds and the registries a new one has to join.
+
+## Prop JSDoc
 
 Prop JSDoc feeds the generated `doc-properties.json` and the docs site: write
 doc comments on public props, use `@default` for defaults and `@internal` for
@@ -638,3 +583,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

package/USAGE.md

@@ -32,8 +32,8 @@ Start with these:
   `/raw/foundations/structure/spacing.md` — how layout and spacing are meant to
   be composed
 - the templates — see [Start from a template](#start-from-a-template)
-- `/raw/foundations/content-guidelines/error-handling.md` — preventing and
-  presenting errors
+- `/raw/foundations/content-guidelines/fehlermeldungen.md` — where errors appear
+  and how to word them
 - `/raw/foundations/content-guidelines/sprach-guide.md` — UI wording
 - `/raw/get-started/versioning.md` — what you may depend on
 
@@ -252,6 +252,11 @@ Also:
 - Do not hand-roll feedback for async work — `Action` wraps a button and renders
   its pending, success and failure states; `List` covers loading and empty
   states; `Skeleton` and `SkeletonText` are the placeholders.
+- Keep `List` items cheap: give `List.Item` and `List.TableRow`
+  `renderDependencies` (every value the render function reads besides the item),
+  and keep modals and data loading at list level instead of per item — every
+  item pays for what it contains (`/raw/components/list/list.md`, section
+  "Performance").
 - Write UI text in German following the Sprach-Guide; component-internal text is
   already translated (de-DE, en-US) via `TranslationProvider`.