@imfusion/web-ui 0.11.1-dev.55.gecb71e07 → 0.11.1-dev.56.gc2cf627a

package/CHANGELOG.md

@@ -102,6 +102,11 @@
   - Forms use TanStack Form: `imf-web-ui-ux` names it for every form, the `imf-web-ui-conventions` `validation` topic
     validates user input in the form's validators with the Zod schema, and `imf-web-ui-audit` reports a form whose state and
     validation are written by hand.
+  - The `imf-web-ui-conventions` `react` topic splits into `composition`, `state`, and `effects`, and each rule names the
+    React version it needs. New rules from react.dev: pure render, no component defined inside another, no `ref.current`
+    during render, `ref` as a prop, `useId` for accessibility ids, error boundaries around UI units, one `status` over
+    exclusive booleans, pure reducers, no object or function effect dependencies, and `useEffectEvent` for values an effect
+    should not react to. React's `<form action>`, `useActionState`, and `useOptimistic` are the fallbacks without TanStack.
   - `web-ui-dev-new-component`, `web-ui-dev-update-component`, and `web-ui-dev-design-component` draft on the shared
     Web UI Component Drafts canvas: a block per component on its Storybook group's page, one row per fidelity rung.
   - `web-ui-dev-new-component` and `web-ui-dev-update-component` wait for the user to approve the design on the canvas

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imfusion/web-ui",
-  "version": "0.11.1-dev.55.gecb71e07",
+  "version": "0.11.1-dev.56.gc2cf627a",
   "description": "The official Web UI component library for ImFusion web apps",
   "author": "ImFusion GmbH",
   "homepage": "https://imfusion.com",

package/src/llms/skills/imf-web-ui-conventions/templates/AUDIT_CHECKLIST.md

@@ -2,7 +2,8 @@
 
 One block per topic, one box per topic section. Check a box only after checking that section's rules against the repo. A full
 audit checks every box; a scoped audit names its topics first and checks only their blocks. Blocks mirror each topic's `##`
-sections one to one — change a topic's sections and this file follows in the same commit.
+sections one to one, and a topic split into a folder gets one `###` block per subtopic — change a topic's sections and this
+file follows in the same commit.
 
 ## Library setup — `library-setup`
 
@@ -35,10 +36,23 @@ sections one to one — change a topic's sections and this file follows in the s
 
 ## React — `react`
 
+### Composition — `react/composition`
+
 - [ ] Composition: pages (smart containers), partials, dumb components
 - [ ] Compose, don't configure
+- [ ] Render rules
+
+### State — `react/state`
+
 - [ ] Put state where its truth lives
+- [ ] State shape
+- [ ] Fallbacks without TanStack
+
+### Effects — `react/effects`
+
 - [ ] Effects: last resort, and named
+- [ ] Dependencies
+- [ ] Effect Events for values the effect should not react to
 
 ## Components — `components`
 

package/src/llms/skills/imf-web-ui-conventions/topics/react/composition.md

@@ -0,0 +1,54 @@
+# React composition
+
+Which role a component plays, and how parts combine.
+
+## Composition: pages (smart containers), partials, dumb components
+
+- **Pages** live in `routes/`. They load data, read URL state, coordinate actions, and compose the view. Route files hold the
+  search schema, loaders, and pending, error, and not-found components. They do not own component CSS. Route-local views and
+  forms live in the route's `-` folder, as [project-structure.md](../project-structure.md) describes, and that folder's
+  `.module.css` files are component styles.
+- **Partials** are compositions that more than one route uses, extracted because they read as a unit. They have light logic
+  and no styling of their own.
+- **Layout components** arrange content with `Stack`, `Row`, grids, and token gaps, and wrap long-form text in `Prose`.
+- **Dumb components** receive data and callbacks, render UI, and own their styles. They do not fetch, route, or contain
+  business rules.
+
+```tsx
+function UserCard({ name, onEdit }: { name: string; onEdit: () => void }) {
+  return (
+    <Card.Root>
+      <Typo.P>{name}</Typo.P>
+      <Button onClick={onEdit}>Edit</Button>
+    </Card.Root>
+  );
+}
+```
+
+## Compose, don't configure
+
+Compose small parts instead of making one component configurable through many boolean props. Lift shared state to the nearest
+common parent.
+
+## Render rules
+
+These come from react.dev and hold for every component. Each names the React version it needs.
+
+- **Render is pure (any version).** Never mutate props, state, context, or a value created before render. Mutating an object
+  the same render just created is fine.
+- **No component defined inside another (any version).** A nested definition gets a new identity each render, so React
+  remounts it and its state resets. Define it at module level and pass data as props.
+- **No `ref.current` during render (any version).** Read and write refs in effects and handlers, except for a lazy init. A
+  value that shapes the output belongs in state.
+- **`ref` is a prop (React 19+).** Accept `ref` like any other prop in your own components; don't wrap them in `forwardRef`.
+- **`useId` for accessibility ids (React 18+).** Use it for `htmlFor`, `aria-describedby`, and similar. Never use it for list
+  keys, and never hardcode its output in tests or selectors.
+- **Error boundaries around UI units (any version).** Wrap a page section or widget, not every component. A boundary does not
+  catch errors from event handlers or async code; TanStack Query and Router surface those.
+- **With the React Compiler on, no manual memoization by default.** `useMemo`, `useCallback`, and `React.memo` are only for a
+  measured case.
+
+See [Keeping Components Pure](https://react.dev/learn/keeping-components-pure),
+[Preserving and Resetting State](https://react.dev/learn/preserving-and-resetting-state),
+[Referencing Values with Refs](https://react.dev/learn/referencing-values-with-refs), and
+[`useId`](https://react.dev/reference/react/useId).

package/src/llms/skills/imf-web-ui-conventions/topics/react/effects.md

@@ -0,0 +1,59 @@
+# React effects
+
+When an effect is the right tool, and how to write the ones that stay.
+
+## Effects: last resort, and named
+
+Use `useEffect` only to synchronize with something outside React. Do not use it for derived values, event responses, or
+server sync.
+
+A genuine effect belongs in a named custom hook. If it stays inline, name the callback:
+
+```tsx
+useEffect(
+  function syncDocumentTitle() {
+    document.title = title;
+  },
+  [title]
+);
+```
+
+Destructure a primitive before putting it in an effect dependency array. Keep the returned query or route object intact
+elsewhere so its namespace remains visible.
+
+## Dependencies
+
+- **No objects or functions as dependencies (any version).** They are new each render, so the effect re-runs every time.
+  Create them inside the effect, move them outside the component, or depend on the primitive they read.
+- **Hidden `<Activity>` cleans up effects (React 19.2+).** A hidden subtree unmounts its effects and re-runs them when shown.
+  Don't rely on an effect running while its UI is hidden.
+
+See [Removing Effect Dependencies](https://react.dev/learn/removing-effect-dependencies).
+
+## Effect Events for values the effect should not react to
+
+When an effect reads a value it should not react to, such as a callback prop or a setting used only once something happens,
+move that logic into `useEffectEvent` (React 19.2+) instead of adding the value to the dependencies, mirroring it in a ref,
+or suppressing the lint rule. Call the Effect Event only from inside the effect, and never use it to drop a value that should
+re-run the effect. See [`useEffectEvent`](https://react.dev/reference/react/useEffectEvent).
+
+```tsx
+const onConnected = useEffectEvent(function notifyConnected() {
+  if (!muted) toast("Connected");
+});
+
+useEffect(
+  function connectToRoom() {
+    const connection = createConnection(roomId);
+    connection.on("connected", onConnected);
+    connection.connect();
+
+    return function disconnectFromRoom() {
+      connection.disconnect();
+    };
+  },
+  [roomId]
+);
+```
+
+Read the React documentation when an effect decision is unclear.

package/src/llms/skills/imf-web-ui-conventions/topics/react/state.md

@@ -0,0 +1,41 @@
+# React state
+
+Where each piece of state lives.
+
+## Put state where its truth lives
+
+Choose the first suitable level:
+
+1. **URL state**: filters, sort, pagination, and active tab. Use TanStack Router search params and validate them.
+2. **Server state**: API data. Use TanStack Query; do not copy it into `useState`.
+3. **Subtree state**: state shared by a subtree and reset when it leaves. Use React context.
+4. **Client state**: app-wide persistent state. Use TanStack Store only when the earlier levels do not fit.
+5. **Local state**: one component's open state, draft, or input value. Use `useState`.
+
+Shape state so it is not redundant or duplicated. Validate a form draft when it becomes a submitted domain value.
+
+## State shape
+
+- **One status, not exclusive booleans (any version).** `status: "idle" | "saving" | "error"` instead of `isSaving` and
+  `isError` that can both be true. Merge state variables that always change together.
+- **Reducers are pure (any version).** No requests, toasts, or timers inside a reducer. Dispatch one action per user
+  interaction, from the event handler.
+- **Slow renders (React 18+).** Keep text input state out of a transition. When a slow list follows a prop or hook value,
+  render it from `useDeferredValue(value)`.
+
+See [Choosing the State Structure](https://react.dev/learn/choosing-the-state-structure) and
+[Extracting State Logic into a Reducer](https://react.dev/learn/extracting-state-logic-into-a-reducer).
+
+## Fallbacks without TanStack
+
+TanStack Form and Query are the default. A project without them uses React's own tools:
+
+- **Forms (React 19+):** `<form action={fn}>` needs no `preventDefault` and resets uncontrolled fields on success. Read
+  `useFormStatus` only in a child of the form. `useActionState` holds the result; dispatch it manually only inside an Action
+  or `startTransition`.
+- **Optimistic updates (React 19+):** `useOptimistic`, with the setter called only inside an Action. Once the save succeeds,
+  the parent's value is the truth again.
+
+See [`<form>`](https://react.dev/reference/react-dom/components/form),
+[`useActionState`](https://react.dev/reference/react/useActionState), and
+[`useOptimistic`](https://react.dev/reference/react/useOptimistic).

package/src/llms/skills/imf-web-ui-conventions/topics/react.md

@@ -1,65 +1,12 @@
 # React
 
 Keep data flow one-way and components focused. Pages decide how data is loaded; presentational components decide how it
-looks.
+looks. Read the subtopic that matches the task.
 
-## Composition: pages (smart containers), partials, dumb components
+| Subtopic                            | Read when                                                       |
+| ----------------------------------- | --------------------------------------------------------------- |
+| [composition](react/composition.md) | Deciding a component's role, or composing parts.                |
+| [state](react/state.md)             | Deciding where state lives.                                     |
+| [effects](react/effects.md)         | Writing or reviewing `useEffect`, or reading values in effects. |
 
-- **Pages** live in `routes/`. They load data, read URL state, coordinate actions, and compose the view. Route files hold the
-  search schema, loaders, and pending, error, and not-found components. They do not own component CSS. Route-local views and
-  forms live in the route's `-` folder, as [project-structure.md](project-structure.md) describes, and that folder's
-  `.module.css` files are component styles.
-- **Partials** are compositions that more than one route uses, extracted because they read as a unit. They have light logic
-  and no styling of their own.
-- **Layout components** arrange content with `Stack`, `Row`, grids, and token gaps, and wrap long-form text in `Prose`.
-- **Dumb components** receive data and callbacks, render UI, and own their styles. They do not fetch, route, or contain
-  business rules.
-
-```tsx
-function UserCard({ name, onEdit }: { name: string; onEdit: () => void }) {
-  return (
-    <Card.Root>
-      <Typo.P>{name}</Typo.P>
-      <Button onClick={onEdit}>Edit</Button>
-    </Card.Root>
-  );
-}
-```
-
-## Compose, don't configure
-
-Compose small parts instead of making one component configurable through many boolean props. Lift shared state to the nearest
-common parent.
-
-## Put state where its truth lives
-
-Choose the first suitable level:
-
-1. **URL state**: filters, sort, pagination, and active tab. Use TanStack Router search params and validate them.
-2. **Server state**: API data. Use TanStack Query; do not copy it into `useState`.
-3. **Subtree state**: state shared by a subtree and reset when it leaves. Use React context.
-4. **Client state**: app-wide persistent state. Use TanStack Store only when the earlier levels do not fit.
-5. **Local state**: one component's open state, draft, or input value. Use `useState`.
-
-Shape state so it is not redundant or duplicated. Validate a form draft when it becomes a submitted domain value.
-
-## Effects: last resort, and named
-
-Use `useEffect` only to synchronize with something outside React. Do not use it for derived values, event responses, or
-server sync.
-
-A genuine effect belongs in a named custom hook. If it stays inline, name the callback:
-
-```tsx
-useEffect(
-  function syncDocumentTitle() {
-    document.title = title;
-  },
-  [title]
-);
-```
-
-Destructure a primitive before putting it in an effect dependency array. Keep the returned query or route object intact
-elsewhere so its namespace remains visible.
-
-Read the React documentation when a decomposition or effect decision is unclear.
+Read the React documentation when a decomposition decision is unclear.

package/src/llms/skills/imf-web-ui-conventions/topics/validation.md

@@ -59,4 +59,5 @@ Use `.catch()` for malformed values that can safely fall back. Use `.default()`
 
 Build forms with TanStack Form and validate user input in the form's validators with the Zod schema, so a field error and the
 submitted value's type come from one schema. Field values held in `useState` and checked by hand with `safeParse` are a gap,
-even when the project's other forms do the same.
+even when the project's other forms do the same. A project without TanStack Form follows the fallback in
+[react/state.md](react/state.md#fallbacks-without-tanstack).