django-admin-react 0.2.0a6__tar.gz → 0.2.0a7__tar.gz

{django_admin_react-0.2.0a6 → django_admin_react-0.2.0a7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: django-admin-react
-Version: 0.2.0a6
+Version: 0.2.0a7
 Summary: A drop-in React single-page admin for Django, driven entirely by ModelAdmin.
 License: MIT
 Keywords: django,admin,react,spa,tailwind
@@ -152,6 +152,10 @@ DJANGO_ADMIN_REACT = {
     "BRAND_LOGO_URL": None,     # str | None — used as the favicon and
                                 # the sidebar logo. Absolute URL or a
                                 # path under your STATIC_URL.
+    "PRIMARY_COLOR": "#2563eb", # accent for primary buttons, links, and
+                                # active states. Hex only (validated);
+                                # injected as the --dar-primary CSS var, so
+                                # rebranding needs no React rebuild.
 }
 ```
 
@@ -193,6 +197,52 @@ brand. No flash of the package's defaults.
   `AUTH_USER_MODEL`, custom `AUTHENTICATION_BACKENDS`, and custom
   `AdminSite.has_permission`.
 
+### Production: static files (and media for file uploads)
+
+The wheel ships the pre-built bundle under the package's `static/` and
+serves it through `{% static %}`. With `DEBUG = True`, Django's
+staticfiles app serves it automatically — nothing to do. **In
+production** you collect + serve static files like any Django app:
+
+```python
+# settings.py
+STATIC_URL = "/static/"
+STATIC_ROOT = BASE_DIR / "staticfiles"   # where collectstatic gathers files
+```
+
+```bash
+python manage.py collectstatic --no-input
+```
+
+Then serve `STATIC_ROOT` from your web server / CDN — or let
+[WhiteNoise](https://whitenoise.readthedocs.io/) do it:
+
+```python
+MIDDLEWARE = [
+    "django.middleware.security.SecurityMiddleware",
+    "whitenoise.middleware.WhiteNoiseMiddleware",   # right after SecurityMiddleware
+    # ...
+]
+```
+
+> If the SPA shell loads but its JS/CSS 404 (blank page, console errors),
+> this `collectstatic` step is what's missing.
+
+**File / image fields.** Editing `FileField` / `ImageField` needs
+Django's media settings:
+
+```python
+# settings.py
+MEDIA_URL = "/media/"
+MEDIA_ROOT = BASE_DIR / "media"
+```
+
+Uploads go through your configured file storage
+(`STORAGES["default"]` / `DEFAULT_FILE_STORAGE`); in production serve
+`MEDIA_ROOT` from your web server or object storage as usual.
+
+> ⚠️ **Serving user-uploaded media has security implications** (access-gating, stored-file XSS). See [`SECURITY.md` §9](SECURITY.md) before exposing `MEDIA_URL` in production — `FileField`/`ImageField` are writable.
+
 ### Running side-by-side with the legacy admin
 
 A common rollout: keep `/admin/` on the legacy HTML admin, mount the

{django_admin_react-0.2.0a6 → django_admin_react-0.2.0a7}/README.md

@@ -121,6 +121,10 @@ DJANGO_ADMIN_REACT = {
     "BRAND_LOGO_URL": None,     # str | None — used as the favicon and
                                 # the sidebar logo. Absolute URL or a
                                 # path under your STATIC_URL.
+    "PRIMARY_COLOR": "#2563eb", # accent for primary buttons, links, and
+                                # active states. Hex only (validated);
+                                # injected as the --dar-primary CSS var, so
+                                # rebranding needs no React rebuild.
 }
 ```
 
@@ -162,6 +166,52 @@ brand. No flash of the package's defaults.
   `AUTH_USER_MODEL`, custom `AUTHENTICATION_BACKENDS`, and custom
   `AdminSite.has_permission`.
 
+### Production: static files (and media for file uploads)
+
+The wheel ships the pre-built bundle under the package's `static/` and
+serves it through `{% static %}`. With `DEBUG = True`, Django's
+staticfiles app serves it automatically — nothing to do. **In
+production** you collect + serve static files like any Django app:
+
+```python
+# settings.py
+STATIC_URL = "/static/"
+STATIC_ROOT = BASE_DIR / "staticfiles"   # where collectstatic gathers files
+```
+
+```bash
+python manage.py collectstatic --no-input
+```
+
+Then serve `STATIC_ROOT` from your web server / CDN — or let
+[WhiteNoise](https://whitenoise.readthedocs.io/) do it:
+
+```python
+MIDDLEWARE = [
+    "django.middleware.security.SecurityMiddleware",
+    "whitenoise.middleware.WhiteNoiseMiddleware",   # right after SecurityMiddleware
+    # ...
+]
+```
+
+> If the SPA shell loads but its JS/CSS 404 (blank page, console errors),
+> this `collectstatic` step is what's missing.
+
+**File / image fields.** Editing `FileField` / `ImageField` needs
+Django's media settings:
+
+```python
+# settings.py
+MEDIA_URL = "/media/"
+MEDIA_ROOT = BASE_DIR / "media"
+```
+
+Uploads go through your configured file storage
+(`STORAGES["default"]` / `DEFAULT_FILE_STORAGE`); in production serve
+`MEDIA_ROOT` from your web server or object storage as usual.
+
+> ⚠️ **Serving user-uploaded media has security implications** (access-gating, stored-file XSS). See [`SECURITY.md` §9](SECURITY.md) before exposing `MEDIA_URL` in production — `FileField`/`ImageField` are writable.
+
 ### Running side-by-side with the legacy admin
 
 A common rollout: keep `/admin/` on the legacy HTML admin, mount the

{django_admin_react-0.2.0a6 → django_admin_react-0.2.0a7}/django_admin_react/api/filters.py

@@ -92,6 +92,38 @@ def _safe_get_field(model: type[Model], name: str) -> Field | None:
     return field if isinstance(field, Field) else None
 
 
+def _resolve_field_path(model: type[Model], path: str) -> Field | None:
+    """Resolve a ``list_filter`` entry to its leaf model ``Field``.
+
+    Handles a plain field name (``"status"``) and a **related-field path**
+    that spans relations (``"author__is_active"`` / ``"order__customer__country"``):
+    each non-final segment must be a relation we can traverse, and the
+    final segment is the leaf field whose *type* drives the descriptor and
+    whose value the ORM filters on (Django applies ``filter(path=value)``
+    natively). Transform lookups (``__year`` / ``__gte`` / ``__icontains``)
+    are not fields and resolve to ``None`` — a separate follow-up (#440).
+    Reverse / generic relations collapse to ``None``, like ``_safe_get_field``.
+    """
+    parts = path.split("__")
+    current: type[Model] = model
+    field: Field | None = None
+    for index, part in enumerate(parts):
+        try:
+            candidate = current._meta.get_field(part)
+        except Exception:
+            return None
+        if not isinstance(candidate, Field):
+            return None
+        field = candidate
+        if index < len(parts) - 1:
+            # Non-final segment must be a relation we can step into.
+            related = getattr(candidate, "related_model", None)
+            if related is None or isinstance(related, str):
+                return None
+            current = related
+    return field
+
+
 def _spec_for_boolean(field_name: str, field: Any) -> dict[str, Any]:
     return {
         "name": field_name,
@@ -169,6 +201,15 @@ def _spec_for_fk(
         payload["choices"] = [
             {"value": obj.pk, "label": label_for(obj)} for obj in base_qs[:_FK_FILTER_MAX_OPTIONS]
         ]
+    elif admin_site is not None:
+        # High-cardinality target (#282): don't inline; hint the SPA to use
+        # the autocomplete endpoint for this filter — but only when the
+        # target admin declares ``search_fields`` (autocomplete 400s
+        # otherwise). The endpoint is already staff-gated and runs the
+        # target's own ``get_search_results``; this is purely a UI hint.
+        target_admin = admin_site._registry.get(related)
+        if target_admin is not None and getattr(target_admin, "search_fields", None):
+            payload["autocomplete"] = True
     return payload
 
 
@@ -267,9 +308,17 @@ def filters_payload(
         if is_sensitive_field_name(field_name):
             continue
 
-        field = _safe_get_field(model, field_name)
+        # Resolve a plain field OR a related-field path (#440). The
+        # descriptor `name` stays the full path so the SPA round-trips
+        # `?<path>=<value>` and the ORM filters natively.
+        field = _resolve_field_path(model, field_name)
         if field is None:
             continue
+        # Defense-in-depth: a path can end in a sensitive leaf
+        # (`author__password`) even when the path string itself didn't trip
+        # the denylist — drop it.
+        if is_sensitive_field_name(field.name):
+            continue
         if isinstance(field, BooleanField):
             out.append(_spec_for_boolean(field_name, field))
         elif isinstance(field, ForeignKey):
@@ -327,9 +376,14 @@ def apply_filters(queryset: QuerySet, model_admin: ModelAdmin, request: HttpRequ
         if raw_value is None or raw_value == "":
             continue
 
-        field = _safe_get_field(model, field_name)
+        # Resolve a plain field OR a related-field path (#440); the leaf
+        # field's type picks the coercion below, while the full path is the
+        # lookup the ORM applies (`filter(author__is_active=True)`).
+        field = _resolve_field_path(model, field_name)
         if field is None:
             continue
+        if is_sensitive_field_name(field.name):
+            continue
 
         try:
             if isinstance(field, BooleanField):

{django_admin_react-0.2.0a6 → django_admin_react-0.2.0a7}/django_admin_react/api/registry.py

@@ -319,6 +319,10 @@ def save_options(
       flag (default True): after a "Save as new", whether the SPA
       lands on the new object's change view (True) or the changelist
       (False).
+    - ``save_on_top`` — the raw ``ModelAdmin.save_on_top`` flag (default
+      False): when True, the SPA mirrors the save-button row at the top
+      of the form too, matching Django's change-form layout (#251).
+      Purely presentational — button visibility is unchanged.
 
     ``has_editable_inline_admin_formsets`` is **not** factored in here
     (the package's inline write-half is tracked under #54). Until that
@@ -330,6 +334,7 @@ def save_options(
     is_add = not is_change
     save_as = bool(getattr(model_admin, "save_as", False))
     save_as_continue = bool(getattr(model_admin, "save_as_continue", True))
+    save_on_top = bool(getattr(model_admin, "save_on_top", False))
 
     has_add = bool(model_admin.has_add_permission(request))
     has_change = bool(model_admin.has_change_permission(request, obj))
@@ -351,6 +356,7 @@ def save_options(
         "show_save_as_new": show_save_as_new,
         "save_as": save_as,
         "save_as_continue": save_as_continue,
+        "save_on_top": save_on_top,
     }
 
 

{django_admin_react-0.2.0a6 → django_admin_react-0.2.0a7}/django_admin_react/api/views/actions.py

@@ -32,6 +32,7 @@ from __future__ import annotations
 from typing import Any
 
 from django.contrib.admin.utils import model_format_dict
+from django.contrib.messages import get_messages
 from django.db import transaction
 from django.http import HttpRequest
 from django.http import HttpResponse
@@ -131,17 +132,26 @@ class ActionView(View):
         with transaction.atomic():
             result = action_callable(model_admin, request, queryset)
 
+        # Surface any messages the action queued via
+        # ``ModelAdmin.message_user`` (#442) so the SPA can toast them —
+        # iterating ``get_messages`` consumes them, so they don't also leak
+        # into the session for the next page render. ``level_tag`` is
+        # Django's "success" / "info" / "warning" / "error" / "debug".
+        messages = [
+            {"level": m.level_tag or "info", "message": str(m)} for m in get_messages(request)
+        ]
+
         # Django admin's action contract: the callable may return an
         # ``HttpResponse`` (typically a redirect to a confirmation
         # page) — we surface that as a JSON envelope so the SPA can
         # follow it without parsing HTML.
         if isinstance(result, HttpResponse):
             body: dict[str, Any] = {"redirect": result["Location"]} if "Location" in result else {}
-            body.update({"executed": True, "action": action_name})
+            body.update({"executed": True, "action": action_name, "messages": messages})
             response = JsonResponse(body, status=200)
         else:
             response = JsonResponse(
-                {"executed": True, "action": action_name, "pks": list(pks)},
+                {"executed": True, "action": action_name, "pks": list(pks), "messages": messages},
                 status=200,
             )
         response["Cache-Control"] = "no-store"

{django_admin_react-0.2.0a6 → django_admin_react-0.2.0a7}/django_admin_react/api/views/create_form.py

@@ -19,6 +19,11 @@ from __future__ import annotations
 
 from typing import Any
 
+from django.core.exceptions import ValidationError
+from django.db.models import FileField
+from django.db.models import ForeignKey
+from django.db.models import ManyToManyField
+from django.db.models import Model
 from django.http import HttpRequest
 from django.http import HttpResponse
 from django.http import JsonResponse
@@ -30,6 +35,9 @@ from django_admin_react.api.registry import get_admin_site
 from django_admin_react.api.registry import model_permissions
 from django_admin_react.api.registry import resolve_model
 from django_admin_react.api.registry import save_options
+from django_admin_react.api.serializers import safe_get_field
+from django_admin_react.api.serializers import serialize_fk_value
+from django_admin_react.api.serializers import serialize_value
 from django_admin_react.api.views.detail import _descriptor_for
 from django_admin_react.api.views.detail import _fieldsets_payload
 from django_admin_react.api.views.detail import _visible_field_names
@@ -69,10 +77,17 @@ class AddFormView(View):
 
         visible_names = _visible_field_names(model_admin, request, None)
         readonly = set(model_admin.get_readonly_fields(request, None) or ())
+        # Initial overlay (#444): Django's add view seeds the form with
+        # ``get_changeform_initial_data(request)`` — which, by default,
+        # reflects ``request.GET`` so a link like ``/add/?status=open``
+        # (and the "save and add another" prefill) lands pre-filled, and
+        # which a ModelAdmin may override. Build the form with that
+        # initial, exactly how ``_changeform_view`` does.
+        initial = _changeform_initial(model_admin, request)
         # The ADD form — change=False, obj=None — exactly how Django's
         # add view constructs it (``ModelAdmin._changeform_view`` with
         # add=True passes change=False).
-        form = model_admin.get_form(request, obj=None, change=False)()
+        form = model_admin.get_form(request, obj=None, change=False)(initial=initial)
 
         fields: dict[str, dict[str, Any]] = {}
         for name in visible_names:
@@ -87,6 +102,14 @@ class AddFormView(View):
                 request=request,
             )
 
+        # Overlay the initial values onto the descriptors. Done as a
+        # second pass (rather than mutating ``obj``) so the shared
+        # descriptor builder stays untouched and a bad initial can never
+        # 500 the form: each value is coerced through the add-form's own
+        # field, so FKs resolve against the admin-scoped ``ModelChoiceField``
+        # queryset (rule 2) and an invalid initial is simply ignored.
+        _overlay_initial(fields, model, form, initial, admin_site, request)
+
         payload = {
             "app_label": model._meta.app_label,
             "model_name": model._meta.model_name,
@@ -110,6 +133,73 @@ class AddFormView(View):
         return response
 
 
+def _changeform_initial(model_admin: Any, request: HttpRequest) -> dict[str, Any]:
+    """Return ``get_changeform_initial_data(request)`` as a safe dict (#444).
+
+    Django's default reads ``request.GET`` (so ``?field=value`` links
+    prefill) and an admin may override it to inject defaults. A buggy
+    override must not 500 the form, so a non-dict or a raised exception
+    degrades to "no prefill".
+    """
+    try:
+        data = model_admin.get_changeform_initial_data(request)
+    except Exception:  # pragma: no cover — admin author error
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def _overlay_initial(
+    fields: dict[str, dict[str, Any]],
+    model: type[Model],
+    form: Any,
+    initial: dict[str, Any],
+    admin_site: Any,
+    request: HttpRequest,
+) -> None:
+    """Overlay add-form initial values onto the field descriptors (#444).
+
+    Only fields that are both rendered (in ``fields``) and present in the
+    add form are touched — an initial for an excluded/sensitive field is
+    ignored, since that field isn't in the payload to begin with. Each
+    value is coerced through the form field's ``to_python`` so it matches
+    exactly what Django would render into the widget:
+
+    - FK → the form's ``ModelChoiceField.queryset`` resolves the pk to an
+      instance (admin-scoped, rule 2), serialized as the ``{id, label}``
+      envelope; an unknown/invalid pk raises and is ignored (no 500).
+    - scalar / choice / bool / date → coerced and re-serialized in place.
+    - M2M / File → skipped: neither is meaningfully settable on the
+      unsaved add instance, and GET-param prefill of them is not a thing
+      Django's add view does either.
+
+    Any coercion error leaves the field's default value untouched.
+    """
+    for name, raw in initial.items():
+        descriptor = fields.get(name)
+        if descriptor is None:
+            continue
+        field = safe_get_field(model, name)
+        form_field = form.fields.get(name)
+        if field is None or form_field is None:
+            continue
+        if isinstance(field, ManyToManyField | FileField):
+            continue
+        # Coercion failures (a bad FK pk, an unparseable date) are the
+        # expected outcome of a hand-crafted prefill URL — narrow the
+        # catch to what ``to_python`` raises so a real bug still surfaces,
+        # and leave the field's default value in place.
+        try:
+            if isinstance(field, ForeignKey):
+                related = form_field.to_python(raw)
+                descriptor["value"] = serialize_fk_value(
+                    related, admin_site=admin_site, request=request
+                )
+            else:
+                descriptor["value"] = serialize_value(form_field.to_python(raw), field=field)
+        except (ValidationError, ValueError, TypeError):
+            continue
+
+
 def _prepopulated_payload(
     model_admin: Any,
     request: HttpRequest,

{django_admin_react-0.2.0a6 → django_admin_react-0.2.0a7}/django_admin_react/api/views/detail.py

@@ -131,6 +131,11 @@ def _build_payload(
         "fields": _fields_payload(model, model_admin, obj, request, visible_names, admin_site),
         "inlines": inlines_payload(model_admin, obj, request, admin_site),
         "view_on_site_url": _view_on_site_url(model_admin, obj),
+        # empty_value_display (#251): the admin's configured placeholder for
+        # empty/null values (ModelAdmin override → AdminSite default "-"), so
+        # the SPA renders it instead of a hardcoded em-dash. ``str()`` keeps
+        # it a plain string on the wire (it's a SafeString in Django).
+        "empty_value_display": str(model_admin.get_empty_value_display()),
     }
 
 
@@ -207,7 +212,9 @@ def _fieldsets_payload(
     except Exception:
         raw = ()
     if not raw:
-        return [{"title": None, "fields": visible_names, "field_rows": [[n] for n in visible_names]}]
+        return [
+            {"title": None, "fields": visible_names, "field_rows": [[n] for n in visible_names]}
+        ]
 
     visible_set = set(visible_names)
     payload: list[dict[str, Any]] = []
@@ -333,7 +340,7 @@ def _descriptor_for(
         form_field.help_text if form_field is not None else ""
     )
 
-    return field_metadata(
+    descriptor = field_metadata(
         model_field,
         label=_field_label(model_admin, model, name),
         required=required,
@@ -341,6 +348,17 @@ def _descriptor_for(
         help_text=str(help_text),
         value=value,
     )
+    # radio_fields (#251): when the admin lists this choice/FK field in
+    # ``radio_fields``, hint the SPA to render radios instead of a select.
+    # Presentational only — no permission/value change.
+    if name in (getattr(model_admin, "radio_fields", None) or {}):
+        descriptor["widget"] = "radio"
+    # raw_id_fields (#251): FK/M2M fields the admin lists here render as a
+    # pk input + lookup instead of a full select (for high-cardinality
+    # relations). ``elif`` so ``radio_fields`` wins if a field is in both.
+    elif name in (getattr(model_admin, "raw_id_fields", None) or ()):
+        descriptor["widget"] = "raw_id"
+    return descriptor
 
 
 def _readonly_callable_descriptor(

{django_admin_react-0.2.0a6 → django_admin_react-0.2.0a7}/django_admin_react/api/views/list.py

@@ -39,6 +39,7 @@ from django_admin_react.api.permissions import is_admin_user
 from django_admin_react.api.registry import get_admin_site
 from django_admin_react.api.registry import model_permissions
 from django_admin_react.api.registry import resolve_model
+from django_admin_react.api.serializers import field_type_for
 from django_admin_react.api.serializers import label_for
 from django_admin_react.api.serializers import safe_get_field
 from django_admin_react.api.serializers import serialize_fk_value
@@ -191,7 +192,21 @@ class ListView(View):
             "pk_field": model._meta.pk.name,
             "permissions": model_permissions(model_admin, request),
             "columns": columns,
+            # list_display_links (#251): the column name(s) that link to the
+            # detail page — ``ModelAdmin.get_list_display_links`` (defaults to
+            # the first column; ``[]`` when the admin set
+            # ``list_display_links = None`` to disable linking). The SPA links
+            # exactly these columns. Callable list_display entries are dropped
+            # (only string column names round-trip).
+            "list_display_links": [
+                name
+                for name in (model_admin.get_list_display_links(request, list_display) or ())
+                if isinstance(name, str)
+            ],
             "search_fields": list(model_admin.search_fields or ()),
+            # ModelAdmin.search_help_text (#445): shown under the search box,
+            # matching Django's changelist. Empty string when unset.
+            "search_help_text": str(getattr(model_admin, "search_help_text", "") or ""),
             "filters": filters_payload(model_admin, request, admin_site=admin_site),
             "actions": actions_payload(model_admin, request),
             "page": page,
@@ -205,6 +220,10 @@ class ListView(View):
             # "Show all N" control only when ``total`` is at/below this cap,
             # matching Django's changelist (#385).
             "list_max_show_all": list_max_show_all,
+            # empty_value_display (#251): the admin's placeholder for empty
+            # cells (ModelAdmin override → AdminSite default "-"), so the SPA
+            # renders it instead of a hardcoded em-dash.
+            "empty_value_display": str(model_admin.get_empty_value_display()),
             "results": results,
         }
         date_hierarchy = date_hierarchy_payload(
@@ -299,9 +318,15 @@ def _columns_payload(
 ) -> list[dict[str, Any]]:
     """Build the ``columns[]`` payload for the list response.
 
-    Each entry has ``{name, label, sortable, editable}``. Labels
-    resolve through Django's ``label_for_field`` so admin-customised
-    labels (verbose name, ``short_description``, etc.) are honored.
+    Each entry has ``{name, label, sortable, editable}`` plus a
+    ``type`` (the closed v1 field vocabulary) whenever the column maps
+    to a concrete model field — so the SPA can format ``datetime`` /
+    ``date`` / ``time`` cells for display instead of dumping raw ISO
+    (#413). ``list_display`` callables / display methods have no field
+    and so carry no ``type``; the SPA falls back to the plain string.
+    Labels resolve through Django's ``label_for_field`` so
+    admin-customised labels (verbose name, ``short_description``, etc.)
+    are honored.
     ``editable`` is derived from ``ModelAdmin.list_editable`` — the
     SPA renders the cell as an in-place editor when ``True`` and
     submits changes via the bulk PATCH endpoint (Issue #61). The
@@ -322,14 +347,19 @@ def _columns_payload(
             label = label_for_field(name, model_admin.model, model_admin)
         except Exception:  # pragma: no cover — defensive
             label = name
-        payload.append(
-            {
-                "name": name,
-                "label": str(label),
-                "sortable": name in sortable,
-                "editable": name in editable,
-            }
-        )
+        entry: dict[str, Any] = {
+            "name": name,
+            "label": str(label),
+            "sortable": name in sortable,
+            "editable": name in editable,
+        }
+        # Only concrete model fields carry a type; a ``list_display``
+        # callable / display method resolves to ``None`` and the key is
+        # omitted (the SPA then renders the value as a plain string).
+        field = safe_get_field(model_admin.model, name) if isinstance(name, str) else None
+        if field is not None:
+            entry["type"] = field_type_for(field)
+        payload.append(entry)
     return payload
 
 

{django_admin_react-0.2.0a6 → django_admin_react-0.2.0a7}/django_admin_react/static/admin_react/.vite/manifest.json

@@ -1,11 +1,11 @@
 {
   "index.html": {
-    "file": "assets/index-CgWOpEY8.js",
+    "file": "assets/index-BK8mlqvA.js",
     "name": "index",
     "src": "index.html",
     "isEntry": true,
     "css": [
-      "assets/index-Beowap5h.css"
+      "assets/index-BVqO3W_r.css"
     ]
   }
 }