django-admin-react 0.2.0a1__tar.gz → 0.2.0a2__tar.gz

{django_admin_react-0.2.0a1 → django_admin_react-0.2.0a2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: django-admin-react
-Version: 0.2.0a1
+Version: 0.2.0a2
 Summary: A drop-in React single-page admin for Django, driven entirely by ModelAdmin.
 License: MIT
 Keywords: django,admin,react,spa,tailwind
@@ -75,23 +75,22 @@ permissions at runtime from `GET /api/v1/registry/`. Add a new
 
 ## Screenshots
 
-> The React SPA shell is in flight. The screenshots below show the
-> **example apps** (`examples/library/`, `examples/fintech/`) rendered
-> by the **legacy Django admin** — i.e. the experience this package
-> modernises. Once the SPA's v0.1 implementation closes, this section
-> regenerates from `docs/screenshots/`.
+Real captures of the **django-admin-react SPA** rendering the bundled
+`examples/` apps — driven entirely by each app's `ModelAdmin`.
+Regenerate any time with `scripts/screenshots.sh` (Playwright against a
+throwaway example server).
 
-| Login                                              | Admin index (legacy)                                    |
-| -------------------------------------------------- | ------------------------------------------------------- |
-| ![Login](docs/screenshots/01-admin-login.png)      | ![Admin index](docs/screenshots/02-admin-index.png)     |
+| Sign in (package login)                            | Registry / home                                       |
+| -------------------------------------------------- | ----------------------------------------------------- |
+| ![Sign in](docs/screenshots/01-spa-login.png)      | ![Registry](docs/screenshots/02-spa-registry.png)     |
 
-| Library — list view                                            | Library — detail view                                            |
-| -------------------------------------------------------------- | ---------------------------------------------------------------- |
-| ![Author list](docs/screenshots/03-admin-library-list.png)     | ![Author detail](docs/screenshots/05-admin-library-detail.png)   |
+| List view (`list_display` + search)                     | Detail view                                          |
+| ------------------------------------------------------- | ---------------------------------------------------- |
+| ![List](docs/screenshots/03-spa-list.png)               | ![Detail](docs/screenshots/05-spa-detail.png)        |
 
-| Mobile (375 px) — `list_display` collapsed                          | API: `GET /api/v1/registry/`                                  |
-| ------------------------------------------------------------------- | ------------------------------------------------------------- |
-| ![Mobile list](docs/screenshots/04-admin-library-list-mobile.png)   | ![Registry JSON](docs/screenshots/06-registry-api-json.png)   |
+| Mobile (375 px)                                            | API: `GET /api/v1/registry/`                               |
+| ---------------------------------------------------------- | ---------------------------------------------------------- |
+| ![Mobile](docs/screenshots/04-spa-list-mobile.png)         | ![Registry JSON](docs/screenshots/06-registry-api-json.png) |
 
 Screenshots use deterministic synthetic fixtures (no real names,
 emails, account numbers, or PII).
@@ -174,8 +173,8 @@ the brand title in the sidebar.
 ```python
 # settings.py
 DJANGO_ADMIN_REACT = {
-    "BRAND_TITLE":    "Laminr",
-    "BRAND_LOGO_URL": "/static/laminr/logo.svg",
+    "BRAND_TITLE":    "Acme",
+    "BRAND_LOGO_URL": "/static/acme/logo.svg",
 }
 ```
 

{django_admin_react-0.2.0a1 → django_admin_react-0.2.0a2}/README.md

@@ -44,23 +44,22 @@ permissions at runtime from `GET /api/v1/registry/`. Add a new
 
 ## Screenshots
 
-> The React SPA shell is in flight. The screenshots below show the
-> **example apps** (`examples/library/`, `examples/fintech/`) rendered
-> by the **legacy Django admin** — i.e. the experience this package
-> modernises. Once the SPA's v0.1 implementation closes, this section
-> regenerates from `docs/screenshots/`.
+Real captures of the **django-admin-react SPA** rendering the bundled
+`examples/` apps — driven entirely by each app's `ModelAdmin`.
+Regenerate any time with `scripts/screenshots.sh` (Playwright against a
+throwaway example server).
 
-| Login                                              | Admin index (legacy)                                    |
-| -------------------------------------------------- | ------------------------------------------------------- |
-| ![Login](docs/screenshots/01-admin-login.png)      | ![Admin index](docs/screenshots/02-admin-index.png)     |
+| Sign in (package login)                            | Registry / home                                       |
+| -------------------------------------------------- | ----------------------------------------------------- |
+| ![Sign in](docs/screenshots/01-spa-login.png)      | ![Registry](docs/screenshots/02-spa-registry.png)     |
 
-| Library — list view                                            | Library — detail view                                            |
-| -------------------------------------------------------------- | ---------------------------------------------------------------- |
-| ![Author list](docs/screenshots/03-admin-library-list.png)     | ![Author detail](docs/screenshots/05-admin-library-detail.png)   |
+| List view (`list_display` + search)                     | Detail view                                          |
+| ------------------------------------------------------- | ---------------------------------------------------- |
+| ![List](docs/screenshots/03-spa-list.png)               | ![Detail](docs/screenshots/05-spa-detail.png)        |
 
-| Mobile (375 px) — `list_display` collapsed                          | API: `GET /api/v1/registry/`                                  |
-| ------------------------------------------------------------------- | ------------------------------------------------------------- |
-| ![Mobile list](docs/screenshots/04-admin-library-list-mobile.png)   | ![Registry JSON](docs/screenshots/06-registry-api-json.png)   |
+| Mobile (375 px)                                            | API: `GET /api/v1/registry/`                               |
+| ---------------------------------------------------------- | ---------------------------------------------------------- |
+| ![Mobile](docs/screenshots/04-spa-list-mobile.png)         | ![Registry JSON](docs/screenshots/06-registry-api-json.png) |
 
 Screenshots use deterministic synthetic fixtures (no real names,
 emails, account numbers, or PII).
@@ -143,8 +142,8 @@ the brand title in the sidebar.
 ```python
 # settings.py
 DJANGO_ADMIN_REACT = {
-    "BRAND_TITLE":    "Laminr",
-    "BRAND_LOGO_URL": "/static/laminr/logo.svg",
+    "BRAND_TITLE":    "Acme",
+    "BRAND_LOGO_URL": "/static/acme/logo.svg",
 }
 ```
 

django_admin_react-0.2.0a2/django_admin_react/api/inlines_write.py

@@ -0,0 +1,226 @@
+"""Inline formset write path (Issue #54, write half — PR 2 of the split).
+
+Wire contract: ``docs/api-contract.md`` §5.4 (inline writes).
+
+The read half (#109, ``api/inlines.py``) surfaces each declared
+``InlineModelAdmin`` and its existing rows on the detail response. This
+module is the **write** counterpart: it takes the ``inlines`` block of a
+PATCH/POST payload and round-trips it through Django's own inline
+formset machinery, exactly the way ``ModelAdmin.changeform_view`` does.
+
+Why a formset and not a per-row ``save()`` loop (Architect rule 3):
+iterating rows and calling ``child.save()`` each would bypass the
+formset's ``clean()`` / ``clean_m2m()`` and the inline's
+``save_formset`` hook — losing the consumer's cross-row validation and
+any signals they rely on. We build the real formset, validate it as a
+unit, and call ``model_admin.save_formset(...)``.
+
+Security model (Architect contract + `SECURITY.md` §3):
+
+- **Rule 1** — everything reuses ``InlineModelAdmin``; no parallel
+  inline-config or write path.
+- **Rule 3** — rows round-trip through
+  ``inline.get_formset(request, obj=parent)`` + ``formset.save()``.
+- **Per-row permission gates** — each row's *state* is gated by the
+  inline's own permission method against the **parent** object:
+  - a new row (``pk`` is null) requires ``has_add_permission``;
+  - an edited existing row requires ``has_change_permission``;
+  - a ``DELETE`` row requires ``has_delete_permission``.
+  A single failing gate makes the **whole** PATCH roll back — the
+  caller wraps this in ``transaction.atomic()`` and treats a returned
+  ``PermissionError`` as a 403 that reverts the parent write too.
+- **Deny-by-default lookup** — an ``inlines`` key that doesn't match a
+  declared inline on this parent is rejected (400), never silently
+  ignored (no mass-assignment via an unrecognised prefix).
+
+Out of scope (firm — documented in the PR and the contract):
+
+- Nested inlines (inline-of-inline).
+- ``GenericInlineModelAdmin`` (contenttypes).
+- M2M-through inlines with extra fields (surfaced as ``unsupported`` by
+  the read half; writes are refused here for the same reason).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from django.contrib.admin.options import InlineModelAdmin
+from django.contrib.admin.options import ModelAdmin
+from django.db.models import Model
+from django.forms.models import BaseModelFormSet
+from django.http import HttpRequest
+
+from django_admin_react.api.inlines import _get_inline_instances
+from django_admin_react.api.inlines import _resolve_fk_name
+
+
+class InlinePermissionDenied(Exception):
+    """A per-row state was not permitted for the requesting user.
+
+    Raised (not returned) so the caller's ``transaction.atomic()`` block
+    unwinds the parent write as well — a forbidden inline row must never
+    leave a half-applied PATCH behind. The caller converts this to a 403.
+    """
+
+    def __init__(self, inline_name: str, state: str) -> None:
+        super().__init__(f"inline {inline_name!r}: {state} not permitted")
+        self.inline_name = inline_name
+        self.state = state
+
+
+def _inline_name(inline: InlineModelAdmin, parent: Model) -> str:
+    """The identifier the read half emits for this inline.
+
+    Must match ``inlines.py``'s ``_spec_for_inline`` so the SPA can echo
+    the same key back on write. Kept in one place would be ideal; this
+    mirrors the read-half computation deliberately and the
+    ``test_inline_write_name_matches_read`` regression pins them
+    together.
+    """
+    child_model = inline.model
+    fk_name = _resolve_fk_name(inline, parent)
+    if fk_name is None:
+        return child_model._meta.model_name
+    if hasattr(child_model, fk_name + "_set"):
+        return fk_name
+    return fk_name + "_set"
+
+
+def _formset_data_for(prefix: str, items: list[dict[str, Any]]) -> dict[str, str]:
+    """Translate JSON inline rows into Django formset POST-style data.
+
+    Django's ``BaseModelFormSet`` treats the first ``INITIAL_FORMS``
+    forms as *existing* (keyed by their ``id`` field) and the rest as
+    *new*. So the items are ordered **existing-first** by the caller and
+    ``INITIAL_FORMS`` is set to the count of rows carrying a ``pk``.
+
+    Scalar values are stringified (the form fields coerce them back);
+    ``None`` becomes the empty string the way an empty HTML input would.
+    A truthy ``DELETE`` flag sets the formset's per-form ``DELETE``
+    checkbox.
+    """
+    initial = sum(1 for it in items if it.get("pk") is not None)
+    data: dict[str, str] = {
+        f"{prefix}-TOTAL_FORMS": str(len(items)),
+        f"{prefix}-INITIAL_FORMS": str(initial),
+        f"{prefix}-MIN_NUM_FORMS": "0",
+        f"{prefix}-MAX_NUM_FORMS": "1000",
+    }
+    for i, item in enumerate(items):
+        pk = item.get("pk")
+        if pk is not None:
+            data[f"{prefix}-{i}-id"] = str(pk)
+        for fname, fval in (item.get("fields") or {}).items():
+            data[f"{prefix}-{i}-{fname}"] = "" if fval is None else str(fval)
+        if item.get("DELETE"):
+            data[f"{prefix}-{i}-DELETE"] = "on"
+    return data
+
+
+def _ordered_items(raw_items: Any) -> list[dict[str, Any]]:
+    """Validate + order the incoming row list: existing (``pk``) first.
+
+    Raises ``ValueError`` on a malformed payload (not a list, or a row
+    that isn't an object) so the caller returns a 400 rather than a 500.
+    """
+    if not isinstance(raw_items, list):
+        raise ValueError("inline 'items' must be a list")
+    items: list[dict[str, Any]] = []
+    for row in raw_items:
+        if not isinstance(row, dict):
+            raise ValueError("each inline row must be an object")
+        items.append(row)
+    existing = [it for it in items if it.get("pk") is not None]
+    new = [it for it in items if it.get("pk") is None]
+    return existing + new
+
+
+def _gate_row_states(
+    inline: InlineModelAdmin,
+    parent: Model,
+    request: HttpRequest,
+    items: list[dict[str, Any]],
+    name: str,
+) -> None:
+    """Raise ``InlinePermissionDenied`` if any row state isn't allowed.
+
+    Gates **before** the formset saves so a forbidden state never
+    partially persists. Checks the inline's own permission methods
+    against the parent object (not the parent admin's) per the Architect
+    contract.
+    """
+    wants_add = any(it.get("pk") is None and not it.get("DELETE") for it in items)
+    wants_change = any(it.get("pk") is not None and not it.get("DELETE") for it in items)
+    wants_delete = any(it.get("DELETE") for it in items)
+
+    if wants_add and not inline.has_add_permission(request, parent):
+        raise InlinePermissionDenied(name, "add")
+    if wants_change and not inline.has_change_permission(request, parent):
+        raise InlinePermissionDenied(name, "change")
+    if wants_delete and not inline.has_delete_permission(request, parent):
+        raise InlinePermissionDenied(name, "delete")
+
+
+def apply_inline_writes(
+    model_admin: ModelAdmin,
+    request: HttpRequest,
+    parent: Model,
+    parent_form: Any,
+    inlines_payload: dict[str, Any],
+) -> dict[str, dict[str, Any]] | None:
+    """Validate + save every inline formset in ``inlines_payload``.
+
+    Returns ``None`` on success. On formset validation failure returns
+    an errors dict keyed by inline name (so the caller returns 400 and
+    rolls back). Raises :class:`InlinePermissionDenied` on a forbidden
+    row state (caller → 403 + rollback). Raises ``ValueError`` on a
+    malformed payload shape (caller → 400).
+
+    Must be called **inside** the caller's ``transaction.atomic()``
+    block, after the parent form has saved, so a failure here reverts
+    the parent write too.
+    """
+    if not isinstance(inlines_payload, dict):
+        raise ValueError("'inlines' must be an object keyed by inline name")
+
+    # Map declared inlines by the read-half name so an unknown key is a
+    # 400 (deny-by-default) rather than a silently-ignored payload.
+    inlines = _get_inline_instances(model_admin, parent, request)
+    by_name: dict[str, InlineModelAdmin] = {
+        _inline_name(inline, parent): inline for inline in inlines
+    }
+    unknown = set(inlines_payload) - set(by_name)
+    if unknown:
+        raise ValueError("unknown inline(s): " + ", ".join(sorted(unknown)))
+
+    errors: dict[str, dict[str, Any]] = {}
+
+    for name, block in inlines_payload.items():
+        inline = by_name[name]
+        if not isinstance(block, dict):
+            raise ValueError(f"inline {name!r} must be an object with 'items'")
+        items = _ordered_items(block.get("items", []))
+        if not items:
+            continue
+
+        # Per-row permission gate BEFORE building/saving the formset.
+        _gate_row_states(inline, parent, request, items, name)
+
+        formset_class = inline.get_formset(request, obj=parent)
+        prefix = formset_class.get_default_prefix()
+        formset: BaseModelFormSet = formset_class(
+            data=_formset_data_for(prefix, items),
+            instance=parent,
+            prefix=prefix,
+        )
+        if not formset.is_valid():
+            errors[name] = {"formset": formset.errors, "non_form": list(formset.non_form_errors())}
+            continue
+
+        # Round-trip through the admin's save hook (rule 3) — never a
+        # per-row save loop. ``save_formset`` runs the consumer's
+        # ``save_formset`` override + ``save_m2m`` for the children.
+        model_admin.save_formset(request, parent_form, formset, change=True)
+
+    return errors or None

{django_admin_react-0.2.0a1 → django_admin_react-0.2.0a2}/django_admin_react/api/registry.py

@@ -236,7 +236,9 @@ def _app_verbose_name(app_label: str) -> str:
 # does) or, worse, surface a consumer model whose URL the SPA can
 # never reach. Treat the segment as reserved and 404 instead — same
 # posture as an unregistered model. Closes issue #93.
-RESERVED_APP_LABELS: frozenset[str] = frozenset({"registry", "schema", "session"})
+RESERVED_APP_LABELS: frozenset[str] = frozenset(
+    {"registry", "schema", "session", "login", "logout"}
+)
 
 
 def resolve_model(
@@ -283,3 +285,70 @@ def resolve_model(
 def model_permissions(model_admin: ModelAdmin, request: HttpRequest) -> dict[str, bool]:
     """Public alias for the four ``has_*_permission`` booleans."""
     return _model_permissions(model_admin, request)
+
+
+def save_options(
+    model_admin: ModelAdmin,
+    request: HttpRequest,
+    obj: Model | None = None,
+) -> dict[str, bool]:
+    """Visibility of the four Django save-flow buttons for this view (#154).
+
+    Mirrors the logic Django's ``admin_modify.submit_row`` template tag
+    applies, restricted to the two views this package serves:
+
+    - ``obj is not None`` → **change view** (``add=False, change=True``).
+    - ``obj is None``     → **add/create view** (``add=True, change=False``).
+
+    We compute the flags from ``ModelAdmin`` permission methods +
+    ``ModelAdmin.save_as`` rather than rendering the admin template, so
+    the package never depends on the admin template context. The flag
+    set is the source of truth for which buttons the SPA renders; the
+    SPA never invents a save routing the backend wouldn't allow.
+
+    Returned keys (all booleans):
+
+    - ``show_save`` — the plain "Save" button.
+    - ``show_save_and_continue`` — "Save and continue editing".
+    - ``show_save_and_add_another`` — "Save and add another".
+    - ``show_save_as_new`` — "Save as new" (change view only, and only
+      when ``ModelAdmin.save_as`` is True).
+    - ``save_as`` — the raw ``ModelAdmin.save_as`` flag, surfaced so the
+      SPA knows whether a "Save as new" POST creates a fresh object.
+    - ``save_as_continue`` — the raw ``ModelAdmin.save_as_continue``
+      flag (default True): after a "Save as new", whether the SPA
+      lands on the new object's change view (True) or the changelist
+      (False).
+
+    ``has_editable_inline_admin_formsets`` is **not** factored in here
+    (the package's inline write-half is tracked under #54). Until that
+    lands, ``can_save`` reduces to the object-level change/add
+    permission, which is correct for models without editable inlines —
+    the overwhelming common case.
+    """
+    is_change = obj is not None
+    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))
+
+    has_add = bool(model_admin.has_add_permission(request))
+    has_change = bool(model_admin.has_change_permission(request, obj))
+    has_view = bool(model_admin.has_view_permission(request, obj))
+
+    # Django: can_save = (has_change and change) or (has_add and add).
+    can_save = (has_change and is_change) or (has_add and is_add)
+    # Django: can_save_and_add_another = has_add and (not save_as or add) and can_save.
+    can_add_another = has_add and (not save_as or is_add) and can_save
+    # Django: can_save_and_continue = can_save and has_view (not is_popup; we never pop up).
+    can_continue = can_save and has_view
+    # Django: show_save_as_new = has_change and change and save_as.
+    show_save_as_new = has_change and is_change and save_as
+
+    return {
+        "show_save": can_save,
+        "show_save_and_continue": can_continue,
+        "show_save_and_add_another": can_add_another,
+        "show_save_as_new": show_save_as_new,
+        "save_as": save_as,
+        "save_as_continue": save_as_continue,
+    }

{django_admin_react-0.2.0a1 → django_admin_react-0.2.0a2}/django_admin_react/api/serializers.py

@@ -30,6 +30,7 @@ from django.db.models import Field
 from django.db.models import ForeignKey
 from django.db.models import ManyToManyField
 from django.db.models import Model
+from django.utils.safestring import SafeString
 
 SENSITIVE_NAME_SUBSTRINGS: Final[tuple[str, ...]] = (
     "password",
@@ -71,6 +72,20 @@ def serialize_value(value: Any, field: Field | None = None) -> Any:
         custom = _registered_serializer(field)
         if custom is not None:
             return custom(value)
+    # SafeString FIRST — it subclasses ``str``, so it must be detected
+    # before the plain-``str`` pass-through below. A ``SafeString`` is
+    # produced by ``format_html`` / ``mark_safe``, which is how a
+    # ``ModelAdmin`` ``list_display`` method (or a readonly display
+    # method) opts a value into being rendered as HTML in Django's own
+    # changelist. We mirror that: emit a typed ``{"html": ...}``
+    # envelope so the SPA renders it as markup. A *plain* ``str`` —
+    # e.g. a ``CharField`` containing ``"<script>"`` — is NOT a
+    # ``SafeString`` and stays inert text (rendered escaped by React).
+    # Trust boundary is identical to Django's: the admin author marked
+    # it safe; interpolated args in ``format_html`` are auto-escaped.
+    # See docs/api-contract.md §4 + SECURITY.md (Closes #172).
+    if isinstance(value, SafeString):
+        return {"html": str(value)}
     if value is None or isinstance(value, bool | int | float | str):
         return value
     if isinstance(value, decimal.Decimal):

{django_admin_react-0.2.0a1 → django_admin_react-0.2.0a2}/django_admin_react/api/urls.py

@@ -21,11 +21,15 @@ from django.views.generic import View
 
 from django_admin_react.api.panels import PanelView
 from django_admin_react.api.views.actions import ActionView
+from django_admin_react.api.views.auth import LoginView
+from django_admin_react.api.views.auth import LogoutView
 from django_admin_react.api.views.autocomplete import AutocompleteView
 from django_admin_react.api.views.bulk import BulkUpdateView
 from django_admin_react.api.views.create import CreateView
+from django_admin_react.api.views.delete_preview import DeletePreviewView
 from django_admin_react.api.views.destroy import DestroyView
 from django_admin_react.api.views.detail import DetailView
+from django_admin_react.api.views.history import HistoryView
 from django_admin_react.api.views.list import ListView
 from django_admin_react.api.views.registry import RegistryView
 from django_admin_react.api.views.schema import SchemaView
@@ -77,6 +81,13 @@ class InstanceView(View):
 urlpatterns: list = [
     path("registry/", RegistryView.as_view(), name="registry"),
     path("schema/", SchemaView.as_view(), name="schema"),
+    # Auth endpoints (React-login feature). Single-segment literals, so
+    # they cannot be shadowed by the two-segment ``<app>/<model>/``
+    # pattern below. ``login`` / ``logout`` are also added to
+    # ``RESERVED_APP_LABELS`` so a consumer app named ``login`` can't
+    # collide. CSRF is enforced by middleware (no ``@csrf_exempt``).
+    path("login/", LoginView.as_view(), name="login"),
+    path("logout/", LogoutView.as_view(), name="logout"),
     # Autocomplete is more specific than the collection / instance
     # patterns below — it must be listed FIRST so the literal
     # ``/autocomplete/`` segment isn't swallowed as a ``<str:pk>``.
@@ -112,6 +123,21 @@ urlpatterns: list = [
         PanelView.as_view(),
         name="panel",
     ),
+    # History sub-resource (#155) — LogEntry timeline for one object.
+    # Must precede the instance pattern so ``/history/`` isn't
+    # swallowed as part of the ``<pk>`` route.
+    path(
+        "<str:app_label>/<str:model_name>/<str:pk>/history/",
+        HistoryView.as_view(),
+        name="history",
+    ),
+    # Delete-preview sub-resource (#153) — cascade / protected preview
+    # before the destructive DELETE. Same ordering caveat as above.
+    path(
+        "<str:app_label>/<str:model_name>/<str:pk>/delete-preview/",
+        DeletePreviewView.as_view(),
+        name="delete_preview",
+    ),
     path(
         "<str:app_label>/<str:model_name>/<str:pk>/",
         InstanceView.as_view(),