@mittwald/flow-react-components 0.2.0-alpha.1003 → 0.2.0-alpha.1005

package/AGENTS.md

@@ -196,6 +196,15 @@ if ("action" in props) {
   Group repeated variants in local mixins.
 - Structure sections with comments: `/* Elements */`, `/* States */`,
   `/* Size */`, `/* Variants */`.
+- **Overriding a dependency that injects its own stylesheet** (CodeMirror,
+  react-easy-crop, FontAwesome) needs `@layer flow.unlayered { … }`: their
+  `<style>` elements are unlayered, and unlayered CSS beats layered CSS
+  regardless of specificity, so a normal rule never applies in
+  `all-layered.css`. Only for the library's own `:global()` selectors — the
+  `flow/unlayered-third-party-only` lint rule enforces that, because the marker
+  costs consumers the layer-based overridability of the rule. New or changed
+  rendered behavior here gets a test in `src/tests/layered/`, which runs against
+  the layered variant; the default browser project cannot see this class of bug.
 
 ## Testing — the actual bar
 
@@ -255,8 +264,18 @@ props to hide.
 
 ## Misc
 
-- Feature flags: `src/flags.ts` holds a few behavior toggles; there is no formal
-  policy around them.
+- Application-wide component defaults: `ComponentDefaultsProvider`
+  (`src/components/ComponentDefaultsProvider/`) is where a behavior default that
+  an application should be able to set **once** belongs. Add the setting to the
+  `ComponentDefaults` interface plus its built-in value in
+  `builtInComponentDefaults`, and read it with `useComponentDefaults("<Name>")`
+  at the place that decides. Resolution order: local prop → provider →
+  deprecated `flags` → built-in default. This is not a replacement for
+  `PropsContext`: a UI component clears the props context for its children, so
+  PropsContext cannot carry an app-wide default past the first UI ancestor.
+- Feature flags: `src/flags.ts` is the deprecated predecessor of the
+  `ComponentDefaultsProvider`. Assigned flags still act as an application-wide
+  default (and warn via `useWarnDeprecation`); do not add new ones.
 - `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

package/CHANGELOG.md

@@ -3,6 +3,18 @@
 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.1005](https://github.com/mittwald/flow/compare/0.2.0-alpha.1004...0.2.0-alpha.1005) (2026-08-06)
+
+### Features
+
+* **components:** add ComponentDefaultsProvider for application-wide defaults ([#2796](https://github.com/mittwald/flow/issues/2796)) ([c043f6c](https://github.com/mittwald/flow/commit/c043f6c89b2aa2bb669355014698e57cd81ea796))
+
+# [0.2.0-alpha.1004](https://github.com/mittwald/flow/compare/0.2.0-alpha.1003...0.2.0-alpha.1004) (2026-08-06)
+
+### Bug Fixes
+
+* **components:** make third-party style overrides work in the layered stylesheet ([#2799](https://github.com/mittwald/flow/issues/2799)) ([ab20016](https://github.com/mittwald/flow/commit/ab2001688a279dc0194845f0da53342db12a574b))
+
 # [0.2.0-alpha.1003](https://github.com/mittwald/flow/compare/0.2.0-alpha.1002...0.2.0-alpha.1003) (2026-08-06)
 
 ### Bug Fixes

package/MIGRATION.md

@@ -1,5 +1,46 @@
 # Migrations
 
+## From version `0.2.0-alpha.1004` to `>=0.2.0-alpha.1005`
+
+### Closing a Modal with unsaved changes is confirmed by default
+
+A `Modal` that contains a react-hook-form `<Form>` now asks for confirmation
+before it closes while the form is _dirty_ — previously this required the
+`requireCloseModalConfirmationOnUnsavedChanges` flag. After a successful submit
+or a `form.reset()` the modal closes right away, and actions in the
+`<ActionGroup />` as well as the close button in the heading still close it
+immediately.
+
+Nothing to do if you had the flag enabled. To keep the previous behavior, switch
+the default off (see below).
+
+### `flags` is replaced by the ComponentDefaultsProvider
+
+The global `flags` object is deprecated. Application-wide defaults are defined
+with the `<ComponentDefaultsProvider />` instead, which additionally works per
+subtree:
+
+```diff
+- import { flags } from "@mittwald/flow-react-components";
+-
+- flags.requireCloseModalConfirmationOnUnsavedChanges = false;
+- flags.disableInitialListSuspenseBoundaries = true;
++ import { ComponentDefaultsProvider } from "@mittwald/flow-react-components";
++
++ <ComponentDefaultsProvider
++   defaults={{
++     Form: { confirmModalCloseOnUnsavedChanges: false },
++     List: { disableInitialSuspenseBoundary: true },
++   }}
++ >
++   <App />
++ </ComponentDefaultsProvider>
+```
+
+Assigning a flag keeps working — it acts as the application-wide default below
+the provider and logs a deprecation warning — but the flags will be removed in a
+future release.
+
 ## From version `0.2.0-alpha.779` to `>=0.2.0-alpha.780`
 
 ### CartesianChart

package/PATTERNS.md

@@ -503,9 +503,29 @@ and consistency enforced by tooling, not maintained by hand.
   - ✓ styling genuinely depends on rendered composition.
   - ✗ the condition exists as state/props → apply a class.
 - **Global `:global()` third-party** — target embedded third-party DOM under the
-  root. `src/components/CodeEditor/CodeEditor.module.scss:35`
+  root. `src/components/CodeEditor/CodeEditor.module.scss:47`
   - ✓ scoped styles must reach third-party widget classes.
   - ✗ Flow-owned elements → module classes/contextual styling.
+- **Unlayered escape hatch (`@layer flow.unlayered`)** — take a third-party
+  override out of every cascade layer.
+  `src/components/CodeEditor/CodeEditor.module.scss:44`
+  - ✓ the library injects its own stylesheet at runtime and its declarations
+    would otherwise win: unlayered CSS beats layered CSS regardless of
+    specificity, so a layered override never applies in `all-layered.css`.
+    Confirmed injectors: CodeMirror, react-easy-crop, FontAwesome
+    (`autoAddCss`).
+  - ✗ the library sets **inline styles** → no layer helps; ✗ it only sets SVG
+    presentation attributes → author CSS already wins, no hatch needed
+    (`recharts` ships no CSS at all); ✗ Flow-owned classes → the
+    `flow/unlayered-third-party-only` lint rule rejects it, because the marker
+    costs consumers the layer-based overridability of that rule.
+  - Prefer one block per component at the end of the file; mark at the leaf only
+    where a block would duplicate scaffolding, e.g. rules inside a Sass mixin
+    (`src/components/Icon/Icon.module.scss:24`).
+  - Mark the whole override block, not single declarations — a dependency can
+    add a colliding declaration in any patch release.
+  - Rationale and build mechanics:
+    [ADR 0001, Amendment 2026-08-05](../../docs/adr/0001-css-cascade-layers-in-the-stylesheet.md#amendment-2026-08-05--unlayered-escape-hatch-for-third-party-css).
 - **Global `.flow--…` descendant selectors** `[undocumented]` — coordinate
   independently rendered descendants.
   `src/components/LayoutCard/LayoutCard.module.scss:16`