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

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
 

package/CHANGELOG.md

@@ -3,6 +3,12 @@
 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.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/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`