@mittwald/flow-react-components 1.3.0-next.8 → 1.3.0

package/AGENTS.md

@@ -244,6 +244,26 @@ if ("action" in props) {
   match prop values (`.size-s`, `.primary`).
 - Class composition with `clsx`, consumer `className` appended last:
   `clsx(styles.button, styles[size], styles[color], className)`.
+- **Element-type selectors are a lint error** — `selector-max-type: 0` on
+  `*.module.{css,scss}`, blocking since #3021. Style what the component renders,
+  through its own class. Where the element genuinely carries no class —
+  react-aria internals, third-party svgs, consumer-supplied children, or content
+  the component does not author (`Markdown`, `Text`) — opt out explicitly and
+  name the reason:
+  `// stylelint-disable-next-line selector-max-type -- react-markdown output`.
+  There is no autofix. Two traps when introducing a class instead: a `flow--`
+  class pulls the global reset's
+  `*:where([class*="flow--"] [class*="flow--"]) { font: inherit }`
+  (`src/styles/globals.scss`) onto the element — that reflows `CodeBlock`'s
+  `<pre>`, so it stays an element selector — and a class raises specificity
+  where an element selector deliberately lost a tie (`Modal`'s `> span` against
+  `.flow--heading--heading-content:empty`).
+- **`:global(.flow--…)` names are checked** by
+  `flow/no-unknown-global-flow-class` (`dev/stylelint/`), against the classes
+  the committed `*.module.d.scss.ts` stubs declare, run through the build's own
+  `cssModuleClassNameGenerator`. The reference has to name a class some
+  component actually generates — otherwise the selector matches nothing, which
+  used to fail without a single signal anywhere.
 - **`styles` is precisely typed** by generated `*.module.d.scss.ts` stubs (a
   committed generated artifact — see the root
   [Generated code](https://github.com/mittwald/flow/blob/main/AGENTS.md#generated-code--must-be-committed)
@@ -296,6 +316,38 @@ Run: `pnpm nx test:unit components`,
 `pnpm nx test:browser components --browser.name=webkit`. Browser tests need
 `pnpm test:browser:prepare` once.
 
+**Iterate through nx too**, not with a bare `vitest`. Everything after the `--`
+goes to vitest, so a single file and watch mode have nx targets as well:
+
+```shell
+pnpm nx test:browser components -- src/components/Popover --browser.name=webkit
+pnpm nx test:browser:dev components
+```
+
+Only the nx target's `dependsOn` rebuilds the design tokens the styles entry
+compiles against. A bare `vitest run` skips it and renders against whatever
+`packages/design-tokens/dist` happens to hold — a token added in the same branch
+is simply absent, and CSS drops every declaration referencing it without a
+warning (#3194).
+
+Three traps cost time in every new browser test:
+
+- **Click the label, not the control.** `Checkbox`, `Radio`, `Switch` and
+  `Rating` stack their icons on top of a visually hidden input, so playwright
+  refuses the input with `<svg …> intercepts pointer events`. Query the control
+  by role for assertions and click its label text
+  (`page.getByText(name, { exact: true })`).
+- **Hover needs the pointer modality first.** react-aria only counts a hover as
+  a hover while `getInteractionModality() === "pointer"`, and a freshly loaded
+  page has no modality at all — so `Tooltip` and everything else that opens on
+  hover stays closed no matter how long the test waits. Press something neutral
+  with the mouse once before hovering.
+- **`await render(...)` before any bare DOM query.** A locator assertion polls
+  and waits the first render out; a `document.querySelector` right after
+  `render()` runs before React has committed and reads `null`. That turns an
+  assertion that something is _absent_ into a silent pass, so give any helper
+  that queries the DOM directly a guard that throws when its element is missing.
+
 ## i18n & a11y
 
 - Component-internal UI text lives in colocated `locales/de-DE.locale.json`
@@ -391,7 +443,10 @@ Easy-to-miss conventions not spelled out above. Full details and examples in
   children are left intact.
 - **Semantic generated CSS classes are coordination points** — scoped modules
   still use `:global(.flow--…)` when independently rendered Flow descendants
-  must affect layout.
+  must affect layout. Copy the name from the target component's
+  `*.module.d.scss.ts`; the generator drops a suffix that equals the component
+  name, so a hand-derived name silently matches nothing.
+  `flow/no-unknown-global-flow-class` blocks that.
 - **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

package/USAGE.md

@@ -5,6 +5,10 @@ are changing Flow itself, read [AGENTS.md](./AGENTS.md) instead — the two
 audiences need opposite advice, and applying the contributor patterns in an
 application is the most common mistake made here.
 
+Building an **mStudio extension**? Read the `USAGE.md` of
+`@mittwald/flow-remote-react-components` as well — it covers what differs across
+the remote boundary, starting with the import address.
+
 ## The documentation is machine-readable
 
 The prose that decides most questions — which component covers a use case, how
@@ -13,8 +17,8 @@ published for machine consumption:
 
 | URL                                      | What it is                                                     |
 | ---------------------------------------- | -------------------------------------------------------------- |
-| `https://flow.mittwald.de/llms.txt`      | Index of every page, grouped by section                        |
-| `https://flow.mittwald.de/llms.json`     | Manifest: title, description, page URL, Markdown URL per page  |
+| `https://flow.mittwald.de/llms.txt`      | Index of every page as Markdown links, grouped by section      |
+| `https://flow.mittwald.de/llms.json`     | Manifest: page URL, Markdown URL, remote availability per page |
 | `https://flow.mittwald.de/raw/<path>.md` | One page as Markdown, e.g. `/raw/components/actions/button.md` |
 | `https://flow.mittwald.de/llms-full.txt` | Every page in one file (~1.7 MB)                               |
 
@@ -24,10 +28,14 @@ States, Props) are not translated.
 
 Start with these:
 
-- `/raw/foundations/structure/layout.md` and `spacing.md` — how layout and
-  spacing are meant to be composed
-- `/raw/patterns/patterns/forms.md`, `detail-page.md`, `errorhandling.md`,
-  `list-tile-table.md` — the recurring flows
+- `/raw/foundations/structure/layout.md` and
+  `/raw/foundations/structure/spacing.md` — how layout and spacing are meant to
+  be composed
+- `/raw/templates/bausteine/formular.md`,
+  `/raw/templates/seiten/uebersichtsseite.md`,
+  `/raw/templates/seiten/detailseite.md` — the recurring flows
+- `/raw/foundations/content-guidelines/error-handling.md` — preventing and
+  presenting errors
 - `/raw/foundations/content-guidelines/sprach-guide.md` — UI wording
 - `/raw/get-started/versioning.md` — what you may depend on