Releases

Highlights

• CoachMark is a new overlay that points at a control on its own — for a feature that is new, moved or easy to miss. It leaves the page usable and can be anchored by id, so an mStudio extension can place one (#3166).
• CartesianChart.Bar adds bar series, stacked or grouped, plus a layout prop that turns the chart on its side for horizontal bars (#2880).
• Badge takes a ContextualHelp directly — no trigger to write, no button to style (#3049).
• Heading places a Button or CopyButton written in its content beside the text, scaled to the heading (#3136).
• List.Item gets a dependencies prop so a stable render function can declare the external state it reads (#3139).
• Every popover now keeps a gap to the viewport edge, and a width you set reaches the content instead of leaving empty background beside it.

CoachMark

A coach mark points at a control the user did not ask about. It opens on its own and stays out of the way: the page below keeps scrolling, focus is left alone, and the hint rides along with its anchor instead of closing at the first scroll. Write it directly behind the element it points at — it then follows that element in the reading order, and the anchor refers to it through aria-details.

Anchor it with anchorRef where you have a ref, or with anchor where you do not. An mStudio extension renders in a different context than the host, so a ref never arrives, but an id does — the coach mark keeps looking until that element appears, which matters because the host materializes the page in pieces.

The component is remote-capable and marked beta.

Dismissal is composed, not configured: wrap the button in an Action — Flow never closes an overlay on your behalf.

Bars in CartesianChart

CartesianChart.Bar renders a bar series. Give several bars the same stackId to stack them; leave it off to group them side by side. Bars pick up the categorical color scale and round their outer corners.

The chart's new layout prop decides which axis is the categorical one. "horizontal" (the default) keeps bars growing upwards; "vertical" turns the chart on its side. XAxis and YAxis follow the layout on their own — only the dataKey moves to whichever axis is the categorical one.

Bar is remote-capable.

Contextual help in a Badge

Write a ContextualHelp into a Badge and the badge supplies the trigger button itself, colored and sized to match:

A ContextualHelpTrigger you write out yourself lands in the same place and is styled the same way, so you keep control of the trigger when you need it.

Buttons in a Heading

A Button or CopyButton written in a heading's content is now placed beside the heading text and scaled to the heading's size — m for the two largest sizes, s below.

Declaring what a list item reads

A List.Item re-renders when its data changes, or when one of its render functions changes identity — which a function written inline in JSX does on every render. A render function with a stable identity (hoisted out of the component, wrapped in useCallback, or reading from an external store) gave the item no signal at all, so it kept the values it first saw. dependencies is how you give it one:

A /tunnel entry point

@mittwald/flow-react-components/tunnel re-exports the @mittwald/react-tunnel API through the very module instance Flow uses. The tunnel's context is module-level, so a consumer's own dependency on @mittwald/react-tunnel becomes a second context as soon as the versions diverge, and entries stop finding Flow's providers. Import from this entry point instead of from the package directly (#3176).

Highlights

• npx @mittwald/flow-codemods@latest upgrade bumps every Flow dependency, installs, and runs the codemods for the range it crossed.
• The new @mittwald/flow-codemods package carries the migration catalogue that MIGRATION.md is generated from — 23 entries, each carrying a codemod where the change can be applied mechanically.
• flow-codemods list <revision> shows what a target version would touch before you commit to it.
• Rating takes a segment count (maxValue), single-segment filling (fill="single"), and individual RatingSegment children with their own icons and labels.
• @mittwald/flow-react-components now ships USAGE.md and a JSON component index, so a coding agent can answer component questions without the docs site.

The upgrade CLI

Upgrading Flow used to mean reading MIGRATION.md, deciding which entries applied to your jump, and running codemods one at a time. The new @mittwald/flow-codemods package does that for you.

upgrade detects your package manager, refuses to run on a dirty working tree (--allow-dirty overrides), and reports every file it declined. --dry writes nothing, --print shows the transformed output, and --json makes list machine-readable.

The catalogue is the single source for both the CLI and MIGRATION.md: an entry describes what changed and how to migrate, and carries a codemod when the change can be decided mechanically. Entries without one still tell you what to do by hand — for those, the prose is the migration.

Rating: segment count, single fill, individual segments

Rating gained maxValue (default 5) for the number of segments, and fill="single" to fill only the selected segment instead of every segment up to it.

For a scale whose segments are not interchangeable, pass RatingSegment children — they define how many segments there are (maxValue no longer applies) and each one takes its own icons and accessible label.

Both the component and RatingSegment work in mStudio extensions.

Documentation a coding agent can read

@mittwald/flow-react-components now ships its own consumer guide, and the docs site is published in machine-readable form.

• USAGE.md, shipped inside the package: how to build an application with Flow — component selection, layout and spacing, what is safe to depend on, and the mistakes that come up most. Available offline, which is what makes it usable from an agent's tool loop.
• @mittwald/flow-react-components/component-index — a JSON index of every public component with its lifecycle status and props.
• The docs site at https://flow.mittwald.de‍ serves /llms.txt, /llms.json, /llms-full.txt, and every page as Markdown at /raw/<path>.md.

Point your agent at USAGE.md and the component index; it stops guessing component names and props.

Highlights

• 1.0.0 carries no breaking change over 0.2.0-alpha.1058. Coming from the last alpha, the upgrade is a version bump and nothing else.
• Semantic Versioning is binding from here on: an incompatible change to the runtime public API only ever ships in a new major (ADR 0005, RFC #2711).
• Deprecate, don't break — an API that is going away stays functional and warns at runtime first. That warning is your lead time before the next major.
• Every @mittwald/flow-* package keeps sharing one version, so the promise reads identically for all of them, @mittwald/flow-remote-react-components included.
• Deliberately not covered, so the design system can keep moving: TypeScript types, CSS class names, design tokens, and the internal DOM structure.
• New docs page under Get Started walks through what the release means per audience and how to catch up from an older alpha.

Deprecations

Nothing is newly deprecated in 1.0.0. What changed is the removal date: every path deprecated during the alpha keeps working and now disappears at 2.0.0, not before.

• Align → Combine (#2871‍)
• SegmentedControl / Segment → Tabs (switching content) or RadioGroup (setting a value) (#2903‍) — not mechanical, the replacement is a decision per usage
• The global flags object → ComponentDefaultsProvider, which also works per subtree (#2796‍)
• Button / SubmitButton: color="accent" → color="success" (#2874‍)
• Action: action → onAction

What the version number now guarantees

An incompatible change to any of these only appears in a new major: the runtime public API of public.ts (which components and exports exist, which props they accept, and the documented behaviour of documented functions), the props of the components in @mittwald/flow-remote-react-components, published icons, and the versioned remote protocol.

Node and React are runtime requirements with explicit rules. The Node floor is the actively supported LTS — currently node >=24 — and dropping a version still inside its LTS window is breaking, while dropping an already-EOL one may ship in a minor. Widening the accepted React range is backwards compatible; raising the minimum is breaking.

TypeScript types stay best-effort and are not covered, so a tsc error can in theory appear in a patch. If that would be expensive for your project, pin exact versions instead of ^ ranges. A deliberate type break still ships a migration note.

One override exists: a component's lifecycle status. A Beta component is exempt from the breaking-change promise while its API is still moving; Stable is the default and fully bound; Deprecated stays covered until it is removed in a major.

What it means for mStudio extensions

The props of the components in @mittwald/flow-remote-react-components are the contract with extension developers and carry the same promise as the React components. The remote protocol is versioned and negotiated when the connection is established, so an extension built against an older Flow keeps running when the mStudio host updates.

@mittwald/ext-bridge shares the version but has its own migration guide and a stricter Node rule: for that package, any raise of the Node floor is a breaking change, regardless of EOL, and its floor may be more conservative than the rest. Since the alpha it requires node >=24 and narrows its React peer range to ^19.2.0. Declared context parameters are typed and optional config values are never null any more, so reading config.containerId no longer needs a runtime narrow (#2889‍).

Migrations

From 0.2.0-alpha.1058 there is nothing to do. Coming from an older alpha, the work sits between the alphas, not in 1.0.0, and none of it is a prerequisite — the old paths still work in 1.x.

Every change that needs an adjustment in your code has a before/after entry in the migration guide of the package it affects:

• @mittwald/flow-react-components‍ — also covers @mittwald/flow-remote-react-components
• @mittwald/ext-bridge‍

Entries are sorted by version, newest first. Find the version you are coming from and work upwards. The oldest 0.2.0-alpha entry is the jump to 0.2.0-alpha.646, so from anything around 0.2.0-alpha.600 the guides are complete.

How to work through them — and the codemod CLI that automates part of it — is on Upgrades‍.