@mittwald/flow-react-components 0.2.0-alpha.946 → 0.2.0-alpha.955

package/AGENTS.md

@@ -5,7 +5,7 @@ Component patterns for the core package. Read the
 Definition of Done, workflow).
 
 > **Full pattern catalog:** [PATTERNS.md](./PATTERNS.md) lists every convention
-> (182 patterns) with per-pattern applicability (when to use / when not), a
+> (184 patterns) with per-pattern applicability (when to use / when not), a
 > canonical example each, and a decision cheat-sheet. This guide covers the
 > must-know core; look there when deciding between two approaches.
 
@@ -81,6 +81,10 @@ Conventions:
   that hand-maintained registry, so a missing entry fails the typecheck.
 - Most components wrap `react-aria-components` primitives; expose ARIA props
   directly only where React Aria lacks the behavior.
+- **Keep the returned JSX readable.** Lift computed nodes (icon, label, tooltip
+  text) and non-trivial conditionals into named consts above the `return`; the
+  returned tree should stay scannable — no large inline ternaries or deep logic
+  in the markup. Split a growing tree into subcomponents.
 
 ## PropsContext — contextual composability
 

package/CHANGELOG.md

@@ -3,6 +3,42 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [0.2.0-alpha.955](https://github.com/mittwald/flow/compare/0.2.0-alpha.954...0.2.0-alpha.955) (2026-07-24)
+
+**Note:** Version bump only for package @mittwald/flow-react-components
+
+# [0.2.0-alpha.954](https://github.com/mittwald/flow/compare/0.2.0-alpha.953...0.2.0-alpha.954) (2026-07-24)
+
+**Note:** Version bump only for package @mittwald/flow-react-components
+
+# [0.2.0-alpha.953](https://github.com/mittwald/flow/compare/0.2.0-alpha.952...0.2.0-alpha.953) (2026-07-24)
+
+**Note:** Version bump only for package @mittwald/flow-react-components
+
+# [0.2.0-alpha.952](https://github.com/mittwald/flow/compare/0.2.0-alpha.951...0.2.0-alpha.952) (2026-07-24)
+
+**Note:** Version bump only for package @mittwald/flow-react-components
+
+# [0.2.0-alpha.951](https://github.com/mittwald/flow/compare/0.2.0-alpha.950...0.2.0-alpha.951) (2026-07-24)
+
+**Note:** Version bump only for package @mittwald/flow-react-components
+
+# [0.2.0-alpha.950](https://github.com/mittwald/flow/compare/0.2.0-alpha.949...0.2.0-alpha.950) (2026-07-24)
+
+**Note:** Version bump only for package @mittwald/flow-react-components
+
+# [0.2.0-alpha.949](https://github.com/mittwald/flow/compare/0.2.0-alpha.948...0.2.0-alpha.949) (2026-07-24)
+
+**Note:** Version bump only for package @mittwald/flow-react-components
+
+# [0.2.0-alpha.948](https://github.com/mittwald/flow/compare/0.2.0-alpha.947...0.2.0-alpha.948) (2026-07-24)
+
+**Note:** Version bump only for package @mittwald/flow-react-components
+
+# [0.2.0-alpha.947](https://github.com/mittwald/flow/compare/0.2.0-alpha.946...0.2.0-alpha.947) (2026-07-24)
+
+**Note:** Version bump only for package @mittwald/flow-react-components
+
 # [0.2.0-alpha.946](https://github.com/mittwald/flow/compare/0.2.0-alpha.945...0.2.0-alpha.946) (2026-07-24)
 
 ### Bug Fixes

package/PATTERNS.md

@@ -124,6 +124,12 @@ and consistency enforced by tooling, not maintained by hand.
   `src/components/Button/Button.tsx:112`
   - ✓ root styling combines base, variants, state, and consumer classes.
   - ✗ a single invariant class → pass it directly.
+- **Readable JSX via extracted expressions** — lift computed nodes (icon, label,
+  tooltip text) and non-trivial conditionals into named consts above the
+  `return`; the returned tree stays scannable — no large inline ternaries, no
+  deep logic in the markup. `src/components/Button/Button.tsx:168`
+  - ✓ markup mixes conditional content or several computed values.
+  - ✗ a single self-evident inline expression → keep it inline.
 - **Helpers outside the component** `[undocumented]` — hookless pure
   helpers/constants live above the component const.
   `src/components/Button/Button.tsx:45`
@@ -442,10 +448,17 @@ and consistency enforced by tooling, not maintained by hand.
   colors/sizes/radii. `src/components/Button/Button.module.scss:8`
   - ✓ colors/spacing/type/radii/shadow/size.
   - ✗ a structural CSS keyword or genuine calculation → CSS directly.
+  - `rem` vs `px`: see [design-tokens/AGENTS.md](../design-tokens/AGENTS.md) —
+    text-proportional spacing/sizing → `size-rem`, fixed values → `size-px`.
 - **No invented base values** — compose existing tokens; add component tokens
   only with a design.
   - ✓ values composed from approved tokens.
   - ✗ a missing design decision → ask UX / add an approved component token.
+- **Own the decision in a component token** `[undocumented]` — reference a
+  component-namespaced token for a value that expresses this component's design
+  decision, even when a similar global token exists.
+  - ✓ a value is this component's design choice → component token.
+  - ✗ a genuinely systemic concept (separator, focus ring) → the shared token.
 - **Shared `focus` mixin** — `@use "@/styles/mixins/focus"`.
   `src/components/Button/Button.module.scss:32`
   - ✓ an interactive element needs the system focus ring.
@@ -948,3 +961,7 @@ Quick answers to the highest-frequency choices when authoring a component:
   otherwise one colocated file.
 - **Structure that's only spacing/alignment** → Flow layout primitives; a raw
   wrapper only for semantics or component-owned integration.
+- **JSX getting dense** → extract computed nodes/conditionals into named consts
+  before `return`; split a growing tree into subcomponents.
+- **Sizing/spacing token unit** → text-proportional → `size-rem`; fixed →
+  `size-px` (see design-tokens/AGENTS.md).