Support @include directives in QSS templates

Allow a .qss.in template to pull in another with @include "nav.qss.in",
so styling can be split per GUI area instead of living in one file.
Includes are resolved before token substitution, so included files use
{{token}} placeholders exactly like the base template.

Includes may nest; circular references raise QssProcessingError instead
of recursing until the stack is exhausted.

Author: kaamyashinde

src/ert/gui/theme_manager/qss_processing.py

@@ -6,6 +6,7 @@
 from .theme_utils import ColorTheme, read_theming_resource
 
 _TOKEN_PATTERN = re.compile(r"\{\{([a-z0-9\-]+)\}\}")
+_INCLUDE_PATTERN = re.compile(r'^@include\s+"(.+?)"', re.MULTILINE)
 
 _BASE_TEMPLATE = "base"
 
@@ -22,6 +23,27 @@ def read_qss_stylesheet_file(template_name: str) -> str:
     )
 
 
+def resolve_includes(template: str, *, _seen: frozenset[str] | None = None) -> str:
+    """Replace ``@include "file.qss.in"`` lines with the file's content.
+
+    Supports recursive includes and detects circular references.
+    """
+    if _seen is None:
+        _seen = frozenset()
+
+    def _replacer(match: re.Match[str]) -> str:
+        filename = match.group(1)
+        stem = filename.removesuffix(".qss.in")
+        if stem in _seen:
+            raise QssProcessingError(
+                f"Circular @include detected: {stem} is already being processed"
+            )
+        content = read_qss_stylesheet_file(stem)
+        return resolve_includes(content, _seen=_seen | {stem})
+
+    return _INCLUDE_PATTERN.sub(_replacer, template)
+
+
 def substitute_tokens(template: str, tokens: dict[str, str]) -> str:
     """Replace all {{token-name}} placeholders with values from the token dict."""
     for name, value in tokens.items():
@@ -37,5 +59,6 @@ def substitute_tokens(template: str, tokens: dict[str, str]) -> str:
 def process_qss(theme: ColorTheme) -> str:
     """Load tokens for the given theme and produce a fully-resolved QSS string."""
     raw = read_qss_stylesheet_file(_BASE_TEMPLATE)
+    resolved = resolve_includes(raw)
     tokens = load_tokens(theme)
-    return substitute_tokens(raw, tokens)
+    return substitute_tokens(resolved, tokens)

tests/ert/unit_tests/gui/theme_manager/test_qss_processing.py

@@ -7,6 +7,7 @@
     QssProcessingError,
     process_qss,
     read_qss_stylesheet_file,
+    resolve_includes,
     substitute_tokens,
 )
 from ert.gui.theme_manager.theme_utils import ColorTheme
@@ -143,3 +144,85 @@ def test_that_qss_processing_error_is_an_exception() -> None:
     assert issubclass(QssProcessingError, Exception)
     err = QssProcessingError("boom")
     assert str(err) == "boom"
+
+
+def test_that_resolve_includes_replaces_include_directive_with_file_content(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setattr(
+        qss_mod,
+        "read_theming_resource",
+        lambda *, filename, resource_kind: "/* sidebar styles */",
+    )
+    template = 'before\n@include "sidebar.qss.in"\nafter'
+    result = resolve_includes(template)
+    assert result == "before\n/* sidebar styles */\nafter"
+
+
+def test_that_resolve_includes_handles_multiple_includes(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    contents = {
+        "qss_stylesheet/sidebar.qss.in": "sidebar",
+        "qss_stylesheet/nav.qss.in": "nav",
+    }
+    monkeypatch.setattr(
+        qss_mod,
+        "read_theming_resource",
+        lambda *, filename, resource_kind: contents[filename],
+    )
+    template = '@include "sidebar.qss.in"\n@include "nav.qss.in"'
+    result = resolve_includes(template)
+    assert result == "sidebar\nnav"
+
+
+def test_that_resolve_includes_supports_nested_includes(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    contents = {
+        "qss_stylesheet/outer.qss.in": '@include "inner.qss.in"',
+        "qss_stylesheet/inner.qss.in": "inner-content",
+    }
+    monkeypatch.setattr(
+        qss_mod,
+        "read_theming_resource",
+        lambda *, filename, resource_kind: contents[filename],
+    )
+    template = '@include "outer.qss.in"'
+    result = resolve_includes(template)
+    assert result == "inner-content"
+
+
+def test_that_resolve_includes_detects_circular_references(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    contents = {
+        "qss_stylesheet/a.qss.in": '@include "b.qss.in"',
+        "qss_stylesheet/b.qss.in": '@include "a.qss.in"',
+    }
+    monkeypatch.setattr(
+        qss_mod,
+        "read_theming_resource",
+        lambda *, filename, resource_kind: contents[filename],
+    )
+    template = '@include "a.qss.in"'
+    with pytest.raises(QssProcessingError, match="Circular @include"):
+        resolve_includes(template)
+
+
+def test_that_resolve_includes_returns_template_unchanged_when_no_includes() -> None:
+    template = "QWidget { color: black; }"
+    assert resolve_includes(template) == template
+
+
+def test_that_resolve_includes_raises_file_not_found_for_missing_include(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    def _raise(*, filename: str, resource_kind: str) -> str:
+        raise FileNotFoundError(f"not found: {resource_kind}")
+
+    monkeypatch.setattr(qss_mod, "read_theming_resource", _raise)
+
+    template = '@include "missing.qss.in"'
+    with pytest.raises(FileNotFoundError):
+        resolve_includes(template)