From c5bc2cccb671d193680267320028a422143e9883 Mon Sep 17 00:00:00 2001
From: Martin Castro Laminrs <mcastro@laminr.ai>
Date: Sun, 31 May 2026 12:24:10 +0200
Subject: [PATCH] feat(spa): read --dar-primary from
 AdminSite.site_primary_color (#631)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Mirrors how `BRAND_TITLE` / `BRAND_LOGO_URL` already fall through to
`AdminSite.site_header` / `site_logo`: a consumer with a custom
`AdminSite` subclass can now brand the whole admin (legacy + SPA)
from one place — set `site_primary_color` on the AdminSite, skip
the `settings.DJANGO_ADMIN_REACT["PRIMARY_COLOR"]` dance.

Resolution order (per-deployment override → structural default →
built-in fallback):

  1. `DJANGO_ADMIN_REACT["PRIMARY_COLOR"]` setting, when set.
  2. `admin_site.site_primary_color` attr.
  3. `DEFAULT_PRIMARY_COLOR` (= `#2563eb`, unchanged).

Every layer runs through the existing hex-regex gate, so CSS
injection is impossible at any source — same trust boundary as
before.

DEFAULTS["PRIMARY_COLOR"] flipped from `"#2563eb"` to `None` so the
resolver can distinguish "consumer set this" from "default is in
effect"; the actual fallback hex now lives in a re-exported
`DEFAULT_PRIMARY_COLOR` constant.

Locked by three new tests in `test_spa_index.py`:
  - AdminSite attr is honoured when no setting is configured.
  - Explicit setting wins over the AdminSite attr.
  - Non-hex AdminSite attr can't inject CSS — falls through to default.

Closes #631.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 django_admin_react/conf.py  | 21 ++++++++++---
 django_admin_react/views.py | 27 +++++++++++++----
 tests/test_spa_index.py     | 59 +++++++++++++++++++++++++++++++++++++
 3 files changed, 97 insertions(+), 10 deletions(-)

diff --git a/django_admin_react/conf.py b/django_admin_react/conf.py
index ec8819d..5a123ab 100644
--- a/django_admin_react/conf.py
+++ b/django_admin_react/conf.py
@@ -20,6 +20,12 @@
 
 from django.conf import settings as django_settings
 
+# Built-in fallback for the ``--dar-primary`` accent color when the
+# consumer hasn't set ``PRIMARY_COLOR`` AND their ``AdminSite`` has no
+# ``site_primary_color`` attribute. Re-exported so ``views.py`` can
+# pick up the same constant instead of stringifying its own.
+DEFAULT_PRIMARY_COLOR = "#2563eb"
+
 DEFAULTS: dict[str, Any] = {
     "ADMIN_SITE": "django.contrib.admin.site",
     # The list page size derives from the model's
@@ -59,9 +65,16 @@
     # ``--dar-primary`` CSS variable so a consumer can brand the admin with
     # no React rebuild. Must be a hex color (``#rgb`` / ``#rgba`` /
     # ``#rrggbb`` / ``#rrggbbaa``); anything else is rejected at render and
-    # falls back to this default, since the value is written into a
-    # ``<style>`` block and must not be able to inject CSS.
-    "PRIMARY_COLOR": "#2563eb",
+    # falls back to ``DEFAULT_PRIMARY_COLOR`` below, since the value is
+    # written into a ``<style>`` block and must not be able to inject CSS.
+    #
+    # ``None`` (default) means "consumer didn't explicitly set this" — the
+    # SPA reads ``site_primary_color`` off the configured ``AdminSite``
+    # next, then falls back to ``DEFAULT_PRIMARY_COLOR``. Mirrors
+    # ``BRAND_TITLE`` / ``BRAND_LOGO_URL``: setting wins as the
+    # per-deployment override, AdminSite attr is the structural default,
+    # built-in default last (#631).
+    "PRIMARY_COLOR": None,
     # ``REACT_LOGIN`` — React-rendered login is the **default** so the
     # SPA fully replaces the Django admin URL surface end-to-end (owner
     # directive 2026-05-28). ``SpaIndexView`` serves the React shell to
@@ -149,7 +162,7 @@ class _PackageSettings:
     ENABLE_PROFILING: bool = DEFAULTS["ENABLE_PROFILING"]
     BRAND_TITLE: str | None = DEFAULTS["BRAND_TITLE"]
     BRAND_LOGO_URL: str | None = DEFAULTS["BRAND_LOGO_URL"]
-    PRIMARY_COLOR: str = DEFAULTS["PRIMARY_COLOR"]
+    PRIMARY_COLOR: str | None = DEFAULTS["PRIMARY_COLOR"]
     REACT_LOGIN: bool = DEFAULTS["REACT_LOGIN"]
     API_URL_PREFIX: str | None = DEFAULTS["API_URL_PREFIX"]
     LEGACY_ADMIN_URL_PREFIX: str | None = DEFAULTS["LEGACY_ADMIN_URL_PREFIX"]
diff --git a/django_admin_react/views.py b/django_admin_react/views.py
index 9421ac5..effa5c5 100644
--- a/django_admin_react/views.py
+++ b/django_admin_react/views.py
@@ -115,7 +115,7 @@ def get(self, request: HttpRequest, *args: Any, **kwargs: Any) -> HttpResponse:
                 "brand_title": _resolve_brand_title(admin_site),
                 "tab_title": _resolve_tab_title(admin_site),
                 "brand_logo_url": _resolve_brand_logo(admin_site),
-                "primary_color": _resolve_primary_color(),
+                "primary_color": _resolve_primary_color(admin_site),
                 "initial_theme": _resolve_initial_theme(request),
             },
         )
@@ -315,19 +315,34 @@ def _resolve_brand_logo(admin_site: Any) -> str | None:
 _HEX_COLOR_RE = re.compile(r"^#(?:[0-9a-fA-F]{3,4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$")
 
 
-def _resolve_primary_color() -> str:
+def _resolve_primary_color(admin_site: Any) -> str:
     """The validated accent color injected as ``--dar-primary``.
 
+    Resolution order — matches ``BRAND_TITLE`` / ``BRAND_LOGO_URL`` so a
+    consumer with a custom ``AdminSite`` can brand the whole admin
+    (legacy + SPA) from one place without a settings entry (#631):
+
+    1. ``DJANGO_ADMIN_REACT["PRIMARY_COLOR"]`` — explicit per-deployment
+       override.
+    2. ``admin_site.site_primary_color`` — convention for shops with a
+       custom ``AdminSite`` subclass (``site_header`` / ``site_logo``
+       pattern). Stock Django has no such attribute; consumers add it.
+    3. The package default (``#2563eb``).
+
     The value lands inside a ``<style>`` block in the SPA template, where
     HTML-escaping does NOT prevent CSS injection (``}``/``;`` aren't
-    HTML-special). So only a strict hex color is allowed; anything else
-    (or a non-string) falls back to the default. This is a trust boundary
-    even though the value comes from the consumer's own settings.
+    HTML-special). So only a strict hex color is allowed at every layer;
+    anything else (or a non-string) falls through to the next step and
+    eventually the default. This is a trust boundary even though the
+    value comes from the consumer's own settings / site attribute.
     """
     configured = dar_conf.PRIMARY_COLOR
     if isinstance(configured, str) and _HEX_COLOR_RE.match(configured.strip()):
         return configured.strip()
-    return dar_conf.DEFAULTS["PRIMARY_COLOR"]
+    site_color = getattr(admin_site, "site_primary_color", None)
+    if isinstance(site_color, str) and _HEX_COLOR_RE.match(site_color.strip()):
+        return site_color.strip()
+    return dar_conf.DEFAULT_PRIMARY_COLOR
 
 
 def _resolve_initial_theme(request: HttpRequest) -> str | None:
diff --git a/tests/test_spa_index.py b/tests/test_spa_index.py
index 385a1bc..10e8781 100644
--- a/tests/test_spa_index.py
+++ b/tests/test_spa_index.py
@@ -508,6 +508,65 @@ def test_primary_color_non_hex_value_cannot_inject_css(superuser_client: Client)
         assert "--dar-primary: #2563eb;" in html
 
 
+@pytest.mark.django_db
+def test_primary_color_falls_back_to_admin_site_attr(superuser_client: Client) -> None:
+    """When `PRIMARY_COLOR` is unset, the SPA reads `site_primary_color`
+    off the AdminSite — mirrors `site_header` / `site_logo` so a consumer
+    with a custom AdminSite can brand from one place (#631)."""
+    with override_settings(DJANGO_ADMIN_REACT={}):
+        _reload_conf()
+        original = getattr(default_admin_site, "site_primary_color", None)
+        default_admin_site.site_primary_color = "#10b981"  # emerald
+        try:
+            html = superuser_client.get(ROOT_URL).content.decode("utf-8")
+            assert "--dar-primary: #10b981;" in html
+        finally:
+            if original is None:
+                del default_admin_site.site_primary_color
+            else:
+                default_admin_site.site_primary_color = original
+
+
+@pytest.mark.django_db
+def test_primary_color_setting_wins_over_admin_site_attr(superuser_client: Client) -> None:
+    """Explicit `PRIMARY_COLOR` setting overrides `site_primary_color` —
+    the setting is the per-deployment override, the attr is the
+    structural default. Same precedence as `BRAND_TITLE` (#631)."""
+    with override_settings(DJANGO_ADMIN_REACT={"PRIMARY_COLOR": "#ff8800"}):
+        _reload_conf()
+        original = getattr(default_admin_site, "site_primary_color", None)
+        default_admin_site.site_primary_color = "#10b981"
+        try:
+            html = superuser_client.get(ROOT_URL).content.decode("utf-8")
+            assert "--dar-primary: #ff8800;" in html
+            assert "#10b981" not in html
+        finally:
+            if original is None:
+                del default_admin_site.site_primary_color
+            else:
+                default_admin_site.site_primary_color = original
+
+
+@pytest.mark.django_db
+def test_primary_color_admin_site_non_hex_is_rejected(superuser_client: Client) -> None:
+    """A non-hex `site_primary_color` on the AdminSite still can't inject
+    CSS — same regex gate as `PRIMARY_COLOR`. Falls through to the
+    default (#437 / #631)."""
+    with override_settings(DJANGO_ADMIN_REACT={}):
+        _reload_conf()
+        original = getattr(default_admin_site, "site_primary_color", None)
+        default_admin_site.site_primary_color = "red; } body { display: none } :root {"
+        try:
+            html = superuser_client.get(ROOT_URL).content.decode("utf-8")
+            assert "display: none" not in html
+            assert "--dar-primary: #2563eb;" in html
+        finally:
+            if original is None:
+                del default_admin_site.site_primary_color
+            else:
+                default_admin_site.site_primary_color = original
+
+
 @pytest.mark.django_db
 def test_brand_logo_url_renders_favicon_and_meta(superuser_client: Client) -> None:
     """`BRAND_LOGO_URL` populates both the `<link rel="icon">` and the