chore(release): v1.4.9 — honour ModelAdmin.actions 'target' classification (#615)

Patch — SPA honours the new `target` field from API 1.0.6.

Author: MartinCastroAlvarez

README.md

@@ -422,18 +422,38 @@ class InvoiceAdmin(admin.ModelAdmin):
 
 ### Add custom admin actions
 
+One `actions = (...)` declaration. The API classifies each callable by signature and the SPA renders it on the right surface — **changelist** (multi-select bulk run) or **detail page** (single-object button) — automatically:
+
 ```python
 class InvoiceAdmin(admin.ModelAdmin):
-    actions = ["mark_paid"]
+    actions = ("mark_paid", "regenerate_pdf")
 
+    # Third parameter is `queryset` → batch shape.
+    # Renders on the changelist with multi-select.
     @admin.action(description="Mark selected as paid")
     def mark_paid(self, request, queryset):
         queryset.update(status="paid", paid_at=timezone.now())
+
+    # Third parameter named `obj_id` (or annotated `str`/`int`/Model)
+    # → detail shape. Renders as a button on the single-invoice
+    # detail page header.
+    @admin.action(description="Regenerate PDF")
+    def regenerate_pdf(self, request, obj_id: str):
+        invoice = self.model.objects.get(pk=obj_id)
+        invoice.regenerate_pdf()
+        self.message_user(request, f"Regenerated PDF for #{invoice.pk}.")
 ```
 
-The SPA renders a bulk-actions menu and posts to the same
-`ModelAdmin.actions` machinery — same signatures, same audit
-trail.
+Classifier rules (api 1.0.6+):
+
+| Third parameter | Target | Where it renders |
+|---|---|---|
+| name `queryset` / `qs`, or `QuerySet` annotation | `batch` | Changelist multi-select |
+| name `obj_id` / `object_id` / `pk` / `id` / `object_pk` | `detail` | Detail page header |
+| annotation `str` / `int` / `Model` subclass | `detail` | Detail page header |
+| anything else | `batch` (default, preserves stock Django) | Changelist multi-select |
+
+Same `@admin.action` decorator on both. Same `ModelAdmin.actions` tuple. Same audit trail. **No `django-object-actions`, no `change_actions = (...)` redeclaration** — the signature is the wire.
 
 ### Per-row permission gating
 
@@ -538,14 +558,11 @@ customisations.
 
 ---
 
-## Feature status (alpha — currently `0.2.0a*` on PyPI)
+## Feature status
 
-The **backend** — the `ModelAdmin`-driven REST API — is the stable,
-complete surface and the table below tracks it. The **React SPA** that
-consumes it is in active development; to keep this README from drifting,
-per-feature *SPA* (UI) status is **not** duplicated here — it is tracked
-live in the [frontend implementation tracker (#160)](https://github.com/MartinCastroAlvarez/django-admin-react/issues/160)
-and the [project board](https://github.com/users/MartinCastroAlvarez/projects/3).
+All three packages are **Production / Stable** on PyPI. The
+`ModelAdmin`-driven REST API + the React SPA + the MCP adapter
+all share the v1 wire contract. Per-feature live status below.
 
 | `ModelAdmin` surface                                   | Backend (REST API)                                              |
 | ------------------------------------------------------ | --------------------------------------------------------------- |
@@ -554,7 +571,7 @@ and the [project board](https://github.com/users/MartinCastroAlvarez/projects/3)
 | `list_filter` (boolean / choice / FK / date / Simple)  | ✅                                                              |
 | `date_hierarchy`                                       | ✅                                                              |
 | `list_editable` + bulk PATCH                           | ✅                                                              |
-| `actions` (custom + bulk runner)                       | ✅                                                              |
+| `actions` — batch + detail (signature-classified)      | ✅                                                              |
 | `autocomplete_fields` / `raw_id_fields`                | ✅                                                              |
 | `ManyToManyField` read + write                         | ✅                                                              |
 | `inlines` (TabularInline / StackedInline) — read + write | ✅                                                            |
@@ -569,9 +586,7 @@ and the [project board](https://github.com/users/MartinCastroAlvarez/projects/3)
 | OpenAPI 3.1 schema at `/api/v1/schema/`                | ✅                                                              |
 | PWA manifest + service worker (cache-purge on logout)  | ✅                                                              |
 
-✅ = shipped in the current alpha. 🟡 = not yet built (tracked). This
-column is the **backend** capability only — for which surfaces the React
-UI renders today, see the [frontend tracker (#160)](https://github.com/MartinCastroAlvarez/django-admin-react/issues/160).
+✅ = shipped. 🟡 = not yet built (tracked).
 
 ---
 

examples/fintech/admin.py

@@ -23,39 +23,62 @@ class TransactionAdmin(admin.ModelAdmin):
     date_hierarchy = "posted_at"
     autocomplete_fields = ("account",)
     readonly_fields = ("reference",)
-    # Stock Django admin actions (`@admin.action`). They surface on the
-    # changelist (multi-pk runs) AND the SPA's detail page header
-    # (single-pk runs) — no `django-object-actions` mixin, no
-    # `change_actions = [...]` redeclaration. One source of truth for
-    # everything the consumer wants to expose as an action.
-    actions = ("mark_reconciled", "recompute_reference")
+    # Stock Django admin actions (`@admin.action`). Same `actions = (...)`
+    # declaration, two render surfaces — the API (1.0.6+) inspects each
+    # callable's third-parameter NAME / ANNOTATION and classifies it:
+    #
+    #   - `mark_reconciled(self, request, queryset)`     → batch
+    #     → renders on the changelist with multi-select.
+    #   - `reprocess(self, request, obj_id: str)`        → detail
+    #     → renders as a button on the single-object detail page.
+    #
+    # Same admin declaration. One actions tuple. Signature decides
+    # where the SPA renders the button.
+    actions = ("mark_reconciled", "recompute_reference", "reprocess")
 
     @admin.action(description="Mark as reconciled")
     def mark_reconciled(self, request, queryset):
-        """Tag every row in the queryset as reconciled.
+        """Changelist (`batch`) action — operates on every selected row.
 
-        Demo no-op: the model has no `reconciled` flag yet — this
-        exists so the SPA's detail page has a stock-Django-admin
-        action to render. A real ModelAdmin would update the row
-        and message the user.
+        Demo no-op: the model has no `reconciled` flag yet, so this
+        just message_users the count. Renders on the changelist
+        because the third parameter is named `queryset`.
         """
         count = queryset.count()
         self.message_user(request, f"Marked {count} transaction(s) as reconciled.")
 
     @admin.action(description="Recompute reference")
     def recompute_reference(self, request, queryset):
-        """Roll the ``reference`` field on each row in the queryset.
-
-        Demo: bumps ``reference`` to ``TXN-RECOMP-<stamp>-<i>`` so the
-        operator can see the action ran end-to-end on the SPA.
-        """
+        """Changelist (`batch`) action — bumps every selected row's
+        ``reference`` so the operator can see the action ran end-to-end
+        from the changelist."""
         from datetime import datetime, timezone as tz
         stamp = datetime.now(tz.utc).strftime("%Y%m%d%H%M%S")
         for i, row in enumerate(queryset):
             row.reference = f"TXN-RECOMP-{stamp}-{i:02d}"
             row.save(update_fields=["reference"])
         self.message_user(request, f"Recomputed reference on {queryset.count()} row(s).")
 
+    @admin.action(description="Reprocess this transaction")
+    def reprocess(self, request, obj_id: str):
+        """Detail-page (`detail`) action — operates on the single
+        object behind the detail view.
+
+        Renders on the SPA's detail page header (not on the
+        changelist) because the third parameter is annotated `str`
+        and named `obj_id` — both signals tell the API's classifier
+        the action expects a single object id, not a queryset.
+
+        Demo: writes a `reference` tag so the operator can see the
+        action ran end-to-end without leaving the detail view.
+        """
+        from datetime import datetime, timezone as tz
+        stamp = datetime.now(tz.utc).strftime("%Y%m%d%H%M%S")
+        row = Transaction.objects.get(pk=obj_id)
+        row.reference = f"TXN-REPROC-{stamp}"
+        row.save(update_fields=["reference"])
+        self.message_user(request, f"Reprocessed transaction {row.pk}.")
+
 
 @admin.register(Statement)
 class StatementAdmin(admin.ModelAdmin):

frontend/apps/web/src/pages/DetailPage.tsx

@@ -291,7 +291,20 @@ export function DetailPage({
                 action the user isn't allowed to. On success we re-fetch the
                 detail payload (computed/readonly fields may have changed) and
                 navigate if the action returned a redirect. No full reload. */}
-            {(data.object_actions ?? []).map((action) => (
+            {/* Render ONLY `target === 'detail'` actions here
+                (api 1.0.6+ #603 revised). The same `data.object_actions`
+                wire field carries every `ModelAdmin.actions` entry; the
+                signature-inspection classifier on the API marks the
+                ones whose third parameter is a single object id as
+                `detail` and the queryset-shaped ones as `batch`. The
+                changelist runner endpoint handles both shapes, but we
+                only want the single-pk-callable ones reachable from
+                the detail page header. Back-compat: a pre-1.0.6 API
+                omits `target` — fall through to NOT showing anything
+                (the legacy/stock Django shape was batch-only). */}
+            {(data.object_actions ?? [])
+              .filter((action) => action.target === 'detail')
+              .map((action) => (
               <ObjectActionButton
                 key={action.name}
                 action={action}

frontend/apps/web/src/pages/ListPage.tsx

@@ -474,7 +474,15 @@ export function ListPage() {
   const filters = data.filters ?? [];
   // Count of list_filters currently applied (drives the empty-state copy).
   const activeFilterCount = filters.filter((f) => activeFilters[f.name]).length;
-  const actions = data.actions ?? [];
+  // Changelist actions = only those classified `batch` by the API
+  // (api 1.0.6+ #603 revised). `detail`-target actions live on the
+  // single-object page; rendering them here would let the operator
+  // run a single-pk-shaped callable across a multi-row selection,
+  // which would 400. Back-compat: pre-1.0.6 API omits `target`;
+  // treat the absence as `batch` so older servers keep working.
+  const actions = (data.actions ?? []).filter(
+    (a) => a.target === undefined || a.target === 'batch',
+  );
   const canRunActions = actions.length > 0 && data.permissions.change;
 
   // Select-all-across-pages (#386). The total matching the current filter

frontend/packages/api/src/contract.ts

@@ -257,12 +257,28 @@ export interface FilterDescriptor {
   selected?: string | null;
 }
 
-/** One bulk action surfaced from `ModelAdmin.actions`. */
+/**
+ * One action surfaced from `ModelAdmin.actions`. The API classifies
+ * each registered callable by signature (api 1.0.6+, #603 revised):
+ *
+ * - `batch` — third parameter is the changelist queryset
+ *   (stock Django `def my_action(self, request, queryset)`). Renders
+ *   on the **changelist** with multi-select.
+ * - `detail` — third parameter is a single object id (parameter
+ *   named `obj_id` / `pk` / etc., or annotated `str` / `int` /
+ *   `Model`). Renders on the **single-object detail page**.
+ *
+ * Older API versions (<1.0.6) omit the `target` field; callers
+ * should default to `'batch'` for back-compat.
+ */
 export interface ActionDescriptor {
   name: string;
   label: string;
   description: string;
   requires_confirmation?: boolean;
+  /** Render surface for this action (api 1.0.6+). Absent on older
+   *  servers; treat as `'batch'` (the legacy/stock Django shape). */
+  target?: 'batch' | 'detail';
 }
 
 /** Result of running a bulk action (contract §5.4). */
@@ -284,16 +300,15 @@ export interface ActionRunResponse {
 }
 
 /**
- * One object-level change-page action (#236) — the django-object-actions
- * `change_actions` affordance, surfaced on the detail response only when
- * the admin opts in (duck-typed; no hard dependency). The SPA renders a
- * button per entry next to Edit/Delete.
+ * One detail-page action descriptor. As of api 1.0.6+ (#603 revised),
+ * `data.object_actions` on the detail response uses the same
+ * descriptor shape as `data.actions` on the list response — the API
+ * builds both from `actions_payload(...)` and classifies each by
+ * signature (`target: 'batch' | 'detail'`). `ObjectActionDescriptor`
+ * is kept as an alias for backwards-compat with the v1.0.2 → v1.4.7
+ * `<ObjectActionButton>` consumer that still imports the name.
  */
-export interface ObjectActionDescriptor {
-  name: string;
-  label: string;
-  description?: string;
-}
+export type ObjectActionDescriptor = ActionDescriptor;
 
 /**
  * Result of running one object action

poetry.lock

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "django-admin-react"
-version = "1.4.8"
+version = "1.4.9"
 description = "A drop-in React single-page admin for Django, driven entirely by ModelAdmin."
 authors = ["django-admin-react contributors"]
 license = "MIT"
@@ -49,7 +49,7 @@ django = ">=5.0,<7.0"
 # React SPA super-layer over `django-admin-rest-api`. The package's URLs
 # are included by `django_admin_react.urls`, and consumers add
 # `"django_admin_rest_api"` to `INSTALLED_APPS` alongside this package.
-django-admin-rest-api = "^1.0.5"
+django-admin-rest-api = "^1.0.6"
 # `django-admin-mcp-api` — MCP-protocol adapter over the same REST API
 # so agents reach the SAME `ModelAdmin`-driven surface. Wire-protocol-only
 # layer; adds NO new functionality, permissions, or validation.