@mittwald/flow-react-components 0.2.0-alpha.932 → 0.2.0-alpha.945

package/AGENTS.md

@@ -25,8 +25,8 @@ src/components/Button/
 └── *.browser.test.tsx       # behavior tests (when behavior is non-trivial)
 ```
 
-The barrel exports the view first (only on `@flr-generate` components), then
-the component:
+The barrel exports the view first (only on `@flr-generate` components), then the
+component:
 
 ```ts
 export * from "./view";
@@ -51,7 +51,8 @@ import {
 } from "@/lib/componentFactory/flowComponent";
 
 export interface ButtonProps
-  extends PropsWithChildren<Omit<Aria.ButtonProps, "children">>,
+  extends
+    PropsWithChildren<Omit<Aria.ButtonProps, "children">>,
     FlowComponentProps<HTMLButtonElement> {
   /** The color of the button. @default "primary" */
   color?: "primary" | "accent" | "secondary" | "danger";
@@ -71,21 +72,21 @@ Conventions:
 - Props type is exported as `<Name>Props`; it extends the wrapped React Aria
   props plus `FlowComponentProps<RefElement>`.
 - **Ref as prop** (React 19) — no `forwardRef`.
-- `options.type`: `"ui"` (default — gets props-context isolation),
-  `"layout"`, or `"provider"`. The factory applies `ClearPropsContext`
-  isolation for UI components itself — don't add extra clearing casually.
+- `options.type`: `"ui"` (default — gets props-context isolation), `"layout"`,
+  or `"provider"`. The factory applies `ClearPropsContext` isolation for UI
+  components itself — don't add extra clearing casually.
 - The registered name must match the component/directory name, and the props
   type must be registered in `src/components/propTypes/index.ts`
-  (`FlowComponentPropsTypes`) — `flowComponent` names are typed as `keyof`
-  of that hand-maintained registry, so a missing entry fails the typecheck.
+  (`FlowComponentPropsTypes`) — `flowComponent` names are typed as `keyof` of
+  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.
 
 ## PropsContext — contextual composability
 
 `PropsContext` makes components adapt **automatically** when composed inside
-other components: they receive default prop values and, mainly, CSS classes
-from their surroundings. This is the backbone of Flow's composability.
+other components: they receive default prop values and, mainly, CSS classes from
+their surroundings. This is the backbone of Flow's composability.
 
 ```tsx
 // IllustratedMessage.tsx — every <Icon> inside renders large:
@@ -102,44 +103,50 @@ return (
 ```
 
 - Contexts **nest** (a context can configure props contexts of nested
-  components) and support **dynamic props**:
-  `dynamic((localProps) => value)` derives values from the consumer's props.
+  components) and support **dynamic props**: `dynamic((localProps) => value)`
+  derives values from the consumer's props.
 - Local props always win over context props.
-- Although exported, `PropsContext` is **primarily an internal API** — prefer
-  it for intra-Flow composition, not as a consumer-facing feature.
+- Although exported, `PropsContext` is **primarily an internal API** — prefer it
+  for intra-Flow composition, not as a consumer-facing feature.
 - **Only put remote-capable components into a `PropsContext`** — non-remote
   components break remote rendering.
 - When parent context must not leak into a component's children, use targeted
   clearing, e.g. `wrapWith: <ClearPropsContext />` (see `Modal.tsx`).
 
+Why this works the way it does across the remote boundary:
+[docs/remote-ui.md](../../docs/remote-ui.md).
+
 ## Views — remote-transparent composition
 
-Components tagged `/** @flr-generate all */` get a generated view
-(`view.ts` + `src/views/<Name>View.tsx`). **Inside `flr-universal` components,
-compose other Flow components through their views** (`@/views/*`) — a view
-automatically switches to the remote counterpart in a remote context:
+Components tagged `/** @flr-generate all */` get a generated view (`view.ts` +
+`src/views/<Name>View.tsx`). **Inside `flr-universal` components, compose other
+Flow components through their views** (`@/views/*`) — a view automatically
+switches to the remote counterpart in a remote context:
 
 ```tsx
-import ButtonView from "@/views/ButtonView";   // ✓ works local and remote
-import { Button } from "@/components/Button";  // ✗ host-only in remote context
+import ButtonView from "@/views/ButtonView"; // ✓ works local and remote
+import { Button } from "@/components/Button"; // ✗ host-only in remote context
 ```
 
+Why this works the way it does across the remote boundary:
+[docs/remote-ui.md](../../docs/remote-ui.md).
+
 Remote generation details:
 
 - `@flr-generate all` on the component const marks it for generation.
 - `@flr-ignore-props` excludes props that must not cross the remote boundary —
-  either because they cannot be serialized, or because they could do **too
-  much on the host side**. A global ignore list lives in
+  either because they cannot be serialized, or because they could do **too much
+  on the host side**. A global ignore list lives in
   `dev/remote-components-generator/config.ts`: `style` and
-  `dangerouslySetInnerHTML` are always ignored for safety; `ref`,
-  `controller`, `tunnel`, `key`, `children`, `wrapWith` because they don't
-  serialize. Use the per-component tag for additional cases (see
-  `TunnelEntry.tsx`).
+  `dangerouslySetInnerHTML` are always ignored for safety; `ref`, `controller`,
+  `tunnel`, `key`, `children`, `wrapWith` because they don't serialize. Use the
+  per-component tag for additional cases (see `TunnelEntry.tsx`).
 - After changing props of an `@flr-generate` component:
   `pnpm nx build:remote-components components` and **commit** the results
   (view.ts, `src/views/*`, `remote-*/src/auto-generated/**`).
-- Props of these components are consumed by mStudio extension developers —
-  no breaking changes; deprecate instead:
+- Props of these components are consumed by mStudio extension developers — no
+  breaking changes; deprecate instead. Why this matters:
+  [docs/remote-ui.md](../../docs/remote-ui.md).
 
 ```tsx
 const warnDeprecation = useWarnDeprecation();
@@ -150,8 +157,8 @@ if ("action" in props) {
 
 ## Styling
 
-- One `<Name>.module.scss` per component. Scoped class names are generated
-  from the component's **path** (`dev/vite/cssModuleClassNameGenerator.ts`) —
+- One `<Name>.module.scss` per component. Scoped class names are generated from
+  the component's **path** (`dev/vite/cssModuleClassNameGenerator.ts`) —
   deliberately semantic CSS that could be used standalone. Never bypass CSS
   modules for component roots (the global reset targets `flow--` classes).
 - Root class is the lower-camel component name (`.button`); modifier classes
@@ -159,8 +166,8 @@ if ("action" in props) {
 - Class composition with `clsx`, consumer `className` appended last:
   `clsx(styles.button, styles[size], styles[color], className)`.
 - **Use design-token CSS variables** — global (`--font-size-text--m`) or
-  component-namespaced (`--button--corner-radius`). No hard-coded colors,
-  sizes, radii.
+  component-namespaced (`--button--corner-radius`). No hard-coded colors, sizes,
+  radii.
 - Shared mixins via `@use "@/styles/mixins/…"`: `focus` (focus ring),
   `formControl` (border/color/interaction states of form fields), `ellipsis`.
   Group repeated variants in local mixins.
@@ -169,12 +176,12 @@ if ("action" in props) {
 
 ## Testing — the actual bar
 
-| Artifact | When |
-| --- | --- |
-| `stories/Default.stories.tsx` | **Always.** Realistic args, controls, meaningful variants. Story title category matches the docs (`Actions/…`, `Form Controls/…`, `Overlays/…`, `Status/…`). |
+| Artifact                                   | When                                                                                                                                                                                     |
+| ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `stories/Default.stories.tsx`              | **Always.** Realistic args, controls, meaningful variants. Story title category matches the docs (`Actions/…`, `Form Controls/…`, `Overlays/…`, `Status/…`).                             |
 | `*.browser.test.tsx` (vitest browser mode) | Component has real **behavior**: interaction, controlled state, async flows, form integration, controllers. Render with `vitest-browser-react`, interact via `userEvent`, query by role. |
-| `*.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. |
+| `*.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.                                                                                                  |
 
 Run: `pnpm nx test:unit components`,
 `pnpm nx test:browser components --browser.name=webkit`. Browser tests need
@@ -183,10 +190,10 @@ Run: `pnpm nx test:unit components`,
 ## i18n & a11y
 
 - Component-internal UI text lives in colocated `locales/de-DE.locale.json`
-  **and** `locales/en-US.locale.json` — always add both languages. The
-  strings support ICU MessageFormat (variables, `plural`, `select` — see
-  `PasswordCreationField/locales/` for real usage). Import the files with a
-  glob import and consume them via the Flow hook:
+  **and** `locales/en-US.locale.json` — always add both languages. The strings
+  support ICU MessageFormat (variables, `plural`, `select` — see
+  `PasswordCreationField/locales/` for real usage). Import the files with a glob
+  import and consume them via the Flow hook:
 
   ```tsx
   import locales from "./locales/*.locale.json";
@@ -199,19 +206,19 @@ Run: `pnpm nx test:unit components`,
   initially: every `locales/` directory in the package gets the new file.
 - Icon-only buttons get a localized `aria-label`; decorative icons are
   `aria-hidden` (the `Icon` component handles this when no label is given).
-- Form fields wire label/description/error via `useFieldComponent`
-  (generates ids, sets `aria-describedby`).
+- Form fields wire label/description/error via `useFieldComponent` (generates
+  ids, sets `aria-describedby`).
 
 ## 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. |
+| 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.                                                                                                  |
 | `./nextjs`, `./react-hook-form`, `./password-tools` | 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` | Bundled stylesheet. |
-| `./doc-properties` | Generated prop metadata for the docs site. |
+| `./all.css`                                         | Bundled stylesheet.                                                                                                                                                                         |
+| `./doc-properties`                                  | Generated prop metadata for the docs site.                                                                                                                                                  |
 
 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
@@ -219,14 +226,14 @@ props to hide.
 
 ## Misc
 
-- Feature flags: `src/flags.ts` holds a few behavior toggles; there is no
-  formal policy around them.
+- Feature flags: `src/flags.ts` holds a few behavior toggles; there is no formal
+  policy around them.
 - `SettingsProvider` (`src/components/SettingsProvider/`) is the built-in
   persistence for component settings (e.g. `List` remembering its view
   settings), with pluggable backends (localStorage by default). Internal
   component infrastructure — extension developers don't need it.
-- `stories/lib.tsx` holds story-only fixtures — never import it from
-  component code.
+- `stories/lib.tsx` holds story-only fixtures — never import it from component
+  code.
 - Storybook discovers all `src/**/*.stories.tsx` automatically; there is no
   registry to update.
 
@@ -235,12 +242,12 @@ props to hide.
 Easy-to-miss conventions not spelled out above. Full details and examples in
 [PATTERNS.md](./PATTERNS.md).
 
-- **`PropsContext` is structural, not just styling** — nested entries,
-  `dynamic` children, semantic defaults (icon size, heading level, status), and
-  contextual `wrapWith` define much of a composite's internal API.
+- **`PropsContext` is structural, not just styling** — nested entries, `dynamic`
+  children, semantic defaults (icon size, heading level, status), and contextual
+  `wrapWith` define much of a composite's internal API.
 - **The factory supplies hidden infrastructure** — memoization, nested-context
-  preservation, slot propagation, UI isolation, and tunnel entry/provider
-  wiring are all automatic consequences of `flowComponent`; don't rebuild them.
+  preservation, slot propagation, UI isolation, and tunnel entry/provider wiring
+  are all automatic consequences of `flowComponent`; don't rebuild them.
 - **Raw string children get `Text`-normalized** where typography is
   context-driven (detect raw strings, wrap in `Text`); explicit structured
   children are left intact.
@@ -248,7 +255,7 @@ Easy-to-miss conventions not spelled out above. Full details and examples in
   still use `:global(.flow--…)` when independently rendered Flow descendants
   must affect layout.
 - **Controllers coexist with declarative props** — overlay-like APIs support
-  controlled/uncontrolled props *and* a controller object, not one or the other.
+  controlled/uncontrolled props _and_ a controller object, not one or the other.
 - **Complex behavior is split by vocabulary** — `components/` for render,
   `hooks/` for behavior, `lib/` for pure transforms, `models/` for durable
   state.
@@ -258,8 +265,8 @@ Easy-to-miss conventions not spelled out above. Full details and examples in
 - **The empty `Default` story is intentional** — realistic args and rendering
   live in the typed `meta`, so `export const Default: Story = {}` is the norm.
 - **CSS leans on modern relational/low-specificity selectors** — `:has`,
-  `:where`, logical properties, data attributes, and container boundaries
-  reduce the need for runtime styling props.
-- **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.
+  `:where`, logical properties, data attributes, and container boundaries reduce
+  the need for runtime styling props.
+- **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.

package/CHANGELOG.md

@@ -3,6 +3,71 @@
 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.945](https://github.com/mittwald/flow/compare/0.2.0-alpha.944...0.2.0-alpha.945) (2026-07-23)
+
+**Note:** Version bump only for package @mittwald/flow-react-components
+
+# [0.2.0-alpha.944](https://github.com/mittwald/flow/compare/0.2.0-alpha.943...0.2.0-alpha.944) (2026-07-23)
+
+**Note:** Version bump only for package @mittwald/flow-react-components
+
+# [0.2.0-alpha.943](https://github.com/mittwald/flow/compare/0.2.0-alpha.942...0.2.0-alpha.943) (2026-07-23)
+
+**Note:** Version bump only for package @mittwald/flow-react-components
+
+# [0.2.0-alpha.942](https://github.com/mittwald/flow/compare/0.2.0-alpha.941...0.2.0-alpha.942) (2026-07-23)
+
+**Note:** Version bump only for package @mittwald/flow-react-components
+
+# [0.2.0-alpha.941](https://github.com/mittwald/flow/compare/0.2.0-alpha.940...0.2.0-alpha.941) (2026-07-23)
+
+### Bug Fixes
+
+* **CodeBlock:** fix undefined max height in code block ([8773c73](https://github.com/mittwald/flow/commit/8773c73c7ca63cf3b69a5177712ed8a34bed4fd0))
+* require Node >= 24 (the tested and supported runtime) ([7f9a8ec](https://github.com/mittwald/flow/commit/7f9a8ec0b34fc9db009dc330a3632e3b1ee41eea))
+
+# [0.2.0-alpha.940](https://github.com/mittwald/flow/compare/0.2.0-alpha.939...0.2.0-alpha.940) (2026-07-23)
+
+### Features
+
+* **Table:** add configurable column widths ([#2682](https://github.com/mittwald/flow/issues/2682)) ([c0b9a45](https://github.com/mittwald/flow/commit/c0b9a45a89f75246cead39a940a8e23d65acf160))
+
+# [0.2.0-alpha.939](https://github.com/mittwald/flow/compare/0.2.0-alpha.938...0.2.0-alpha.939) (2026-07-23)
+
+**Note:** Version bump only for package @mittwald/flow-react-components
+
+# [0.2.0-alpha.938](https://github.com/mittwald/flow/compare/0.2.0-alpha.937...0.2.0-alpha.938) (2026-07-23)
+
+### Performance Improvements
+
+* **List:** memoize items so they don't re-render when loading more ([#2677](https://github.com/mittwald/flow/issues/2677)) ([deb547a](https://github.com/mittwald/flow/commit/deb547a07849ce89a59bca9aab7e3a5e33812b54))
+
+# [0.2.0-alpha.937](https://github.com/mittwald/flow/compare/0.2.0-alpha.936...0.2.0-alpha.937) (2026-07-22)
+
+### Bug Fixes
+
+* **PasswordCreationField:** fix overflow ([#2686](https://github.com/mittwald/flow/issues/2686)) ([e668e98](https://github.com/mittwald/flow/commit/e668e98b3bd91a4e06089fc3ec21cb5ca2703d70))
+
+# [0.2.0-alpha.936](https://github.com/mittwald/flow/compare/0.2.0-alpha.935...0.2.0-alpha.936) (2026-07-22)
+
+**Note:** Version bump only for package @mittwald/flow-react-components
+
+# [0.2.0-alpha.935](https://github.com/mittwald/flow/compare/0.2.0-alpha.934...0.2.0-alpha.935) (2026-07-22)
+
+### Bug Fixes
+
+* **Modal:** keep mobile modals with forms usable when the virtual keyboard opens ([#2423](https://github.com/mittwald/flow/issues/2423)) ([#2671](https://github.com/mittwald/flow/issues/2671)) ([5b1b856](https://github.com/mittwald/flow/commit/5b1b8563d6e5e7a0a5c046620104480f1f7620cd))
+
+# [0.2.0-alpha.934](https://github.com/mittwald/flow/compare/0.2.0-alpha.933...0.2.0-alpha.934) (2026-07-21)
+
+### Features
+
+* **components:** add reusable slim scrollbar mixin and apply to scroll containers ([#2672](https://github.com/mittwald/flow/issues/2672)) ([a06dd9a](https://github.com/mittwald/flow/commit/a06dd9a4e88899612eba19a21f6464ba0a98167e))
+
+# [0.2.0-alpha.933](https://github.com/mittwald/flow/compare/0.2.0-alpha.932...0.2.0-alpha.933) (2026-07-21)
+
+**Note:** Version bump only for package @mittwald/flow-react-components
+
 # [0.2.0-alpha.932](https://github.com/mittwald/flow/compare/0.2.0-alpha.931...0.2.0-alpha.932) (2026-07-21)
 
 **Note:** Version bump only for package @mittwald/flow-react-components

package/PATTERNS.md

@@ -19,6 +19,63 @@ not guarantees. Never edit generated files (`view.ts`, `src/views/`,
 
 ---
 
+## Guiding principles
+
+The **why** behind the concrete rules below. When a specific pattern is unclear
+or a new situation isn't covered, fall back to these; the numbered sections are
+these principles applied. (`→` points to the sections each one mostly governs.)
+
+1. **Composition is the architecture.** `PropsContext` is the backbone —
+   components adapt to their surroundings automatically (classes, icon size,
+   heading level) instead of the consumer wiring everything. When a parent
+   shapes its descendants, do it through context, not child-cloning or
+   prop-drilling. → §3.
+2. **Build on standards; don't reinvent accessibility.** Nearly everything wraps
+   `react-aria-components`; expose ARIA directly only where react-aria has a
+   gap. Accessibility is non-negotiable: semantic roots, labels for icon-only
+   controls, `aria-hidden` for decoration, generated `id` / `aria-describedby`.
+   → §1, §8.
+3. **A factory hides the infrastructure — convention over configuration.**
+   `flowComponent` supplies memoization, context isolation, slot/tunnel wiring,
+   and `wrapWith`; never rebuild it by hand. Ref-as-prop (no `forwardRef`),
+   forward `...rest`, defaults in destructuring. The payoff: every component
+   looks the same. → §1.
+4. **Single source of truth; generate what's derivable.** Tokens, views, icons,
+   the `propTypes` registry, and doc-properties are generated and committed,
+   never hand-maintained twice. (It's why this catalog is _referenced_ from
+   `AGENTS.md`, not duplicated into it.) → §4, §5.
+5. **The public API is a contract — extend, don't break.** Export surfaces
+   (`public.ts`, `flr-universal.ts`, `internal.ts`) are curated by hand. Remote
+   props for extension developers are additive; deprecate with
+   `useWarnDeprecation` instead of renaming/removing. JSDoc + `@default` /
+   `@internal` _is_ the API's documentation. → §5, §2, §4.
+6. **Design comes from UX — base tokens are taboo.** Never hard-code
+   colors/sizes/radii; compose existing design tokens, and add component tokens
+   only with an established design. → §6.
+7. **TypeScript is a contract, kept precise.** `interface` for a component's own
+   extensible prop shape; a `type` alias for
+   intersections/`Omit`/`Pick`/generics. Types are tested (`*.test-types.tsx`),
+   and names derive from the registry rather than parallel unions. → §2, §11.
+8. **Enforce consistency with tooling, not discipline.** Prefer an
+   ESLint/Prettier rule + autofix over hundreds of hand edits. Write
+   self-explanatory code with minimal comments. → §12.
+9. **Colocate by role.** `components/` (render), `hooks/` (behavior), `lib/`
+   (pure transforms), `models/` (durable state), `locales/`, `stories/`.
+   Cross-cutting imports use the `@/` alias; a component's own feature stays
+   relative. → §7, §12.
+10. **Effort scales with risk.** Testing bar: a story always, a browser test for
+    real behavior, a unit test for pure logic, a type test for generics. i18n
+    always ships both `de-DE` and `en-US` (ICU). Reach for modern CSS (`:where`,
+    `:has`, logical properties, container queries, `data-*` state) before adding
+    runtime styling props. → §11, §9, §6.
+
+**In one sentence:** composable, accessibility-first React components built on
+react-aria, unified by a factory, backed by a generated single source of truth,
+with a public API treated as a contract and visual design driven by UX tokens —
+and consistency enforced by tooling, not maintained by hand.
+
+---
+
 ## 1. Component definition
 
 - **Factory registration** — public Flow components via