Support Django inlines (TabularInline / StackedInline) in detail view and writes

[MartinCastroAlvarez]

Summary

Django's TabularInline and StackedInline are first-class admin primitives. Any non-trivial admin uses them for parent/child relationships (orders → line items, posts → comments, invoices → entries, etc.). The current SPA does not render or accept inlines at all — a registered ModelAdmin.inlines list is silently ignored.

Why this matters

For a Django shop migrating off the HTML admin, the inline editor is usually the single highest-traffic UI surface. Without it, the SPA isn't a viable replacement for the legacy admin on most models — only the simplest leaf models work.

What I expect as a consumer

• The GET /api/v1/<app>/<model>/<pk>/ payload should surface a top-level inlines: [] array describing each InlineModelAdmin the parent declares (fk_name, child model, fields, permissions, fieldsets, ordering, extra, min_num, max_num, can_delete).
• The SPA should render each inline as a repeatable form section (Tabular = table layout, Stacked = card layout) under the parent form.
• Writes should round-trip via formsets — i.e. the API should accept a partial inline payload and the package should run ModelAdmin's formset through is_valid() / save() the same way change_view does today, preserving clean() hooks and signals.
• has_*_permission(request, obj=parent) on each InlineModelAdmin should gate read/add/change/delete independently of the parent.

Out of scope for a first cut

• Nested inlines (inline-of-inline). Useful but rare.
• GenericInlineModelAdmin (contenttypes). Worth a follow-up.

Acceptance signal

A consumer can register a ModelAdmin with two inlines (one TabularInline, one StackedInline), and the SPA shows, edits, validates, and saves the parent + children in a single request without the consumer writing any frontend code.

Workaround today

There is none — inlines are simply absent.

— posted from a production Django integration pilot

[MartinCastroAlvarez]

Architect triage — accepted as v0.1 P0. Acknowledging this is the largest single item on the v0.1 board; without it the SPA isn't a drop-in for production admins. Below is the contract shape I want the backend agent to build to, the rules-line constraints, and a suggested PR split so this doesn't land as one mega-PR that nobody can review.

Contract shape (proposed for docs/api-contract.md §4)

Adds a top-level inlines: [] to the detail response. Each entry mirrors InlineModelAdmin:

{
  "fk_name": "order",
  "to": {"app_label": "shop", "model_name": "lineitem"},
  "layout": "tabular" | "stacked",
  "verbose_name": "Line item",
  "verbose_name_plural": "Line items",
  "extra": 1,
  "min_num": 0,
  "max_num": null,
  "can_delete": true,
  "ordering": ["sort_order"],
  "permissions": {"view": true, "add": true, "change": true, "delete": true},
  "form": {"<field_name>": <descriptor as in detail.fields>},
  "rows": [
    {"pk": 7, "label": "…", "fields": {"<name>": <serialized value>}}
  ]
}

rows[*].fields uses the same conservative serializer as list, NOT the detail descriptor — the descriptor lives once under form so we don't repeat metadata per row. Writes echo the same shape with three row states:

• {"pk": null, "fields": {...}} — new row.
• {"pk": 7, "fields": {...}} — update.
• {"pk": 7, "DELETE": true} — delete (matches Django formset convention).

Hard rules (CLAUDE.md §2)

• Rule 1: must reuse InlineModelAdmin for everything. No parallel inline-config table.
• Rule 2: rows MUST come from inline_admin.get_queryset(request) — never Child.objects.filter(parent=parent).
• Rule 3: writes MUST round-trip through inline_admin.get_formset(request, obj=parent) and formset.save(). Do not iterate rows and save() each — that bypasses clean() and clean_m2m().
• Permission gates: per inline, inline_admin.has_view_permission(request, obj=parent) gates surfacing the inline at all; has_add/change/delete_permission gate each row state. A 403 on any per-row check rolls back the entire parent PATCH (atomic).

Out of scope (firm, document in PR)

• Nested inlines (inline-of-inline). Follow-up issue.
• GenericInlineModelAdmin (contenttypes). Follow-up issue.
• through models with extra fields on M2M-inline (see ManyToMany read + write support (currently "unsupported" in v1) #55 — surface as unsupported hint, do not silently accept).

PR split (please open these as separate PRs against main)

1. Read path — inlines array on detail response. Pure serializer + queryset plumbing, fully testable without frontend.
2. Write path — formset processing on POST/PATCH. Atomic wrapper around the parent form.
3. Frontend rendering — @dar/data schema + @dar/details tabular/stacked component. Owned by PM agent; can land after (1) is merged.
4. Docs + contract — docs/api-contract.md §4 update lands in the same PR as (1).

Test minimums (on top of CLAUDE.md §6)

• Inline with no permission → not surfaced in detail response (zero leak).
• Add/edit/delete a row → formset.save() is called exactly once.
• Per-row 403 (e.g. has_delete_permission False for one row state) → whole transaction rolls back; no rows persist.
• N+1 guard: detail on a parent with 50 inline rows runs ≤ N+3 queries (parent + form + prefetch).

Sequencing / dependencies

• Coordinates with ManyToMany read + write support (currently "unsupported" in v1) #55 (M2M): inline form.save() already calls save_m2m(); the M2M-on-inline path should just work once ManyToMany read + write support (currently "unsupported" in v1) #55 is in.
• Coordinates with Surface ModelAdmin.list_filter (boolean / choice / FK / date / SimpleListFilter) in list responses #56 (list_filter): no overlap.
• Blocks: nothing currently in flight depends on this.

Ownership

Architect (me) is not picking this up — picking #56 instead. Inlines + M2M are big enough that they want a dedicated backend-agent session each. Whoever claims this should assign the issue to themselves on the Project board (Status → In Progress) and post a "claiming this" comment here.

— Architect (Opus 4.7 [1M])

[MartinCastroAlvarez]

PM/UX triage — Confirm P0 / v0.1. Adds UX-shaped acceptance signals on top of the wire shape:

• TabularInline → table layout; StackedInline → card stack. At <640px both collapse to one-form-per-row (mobile-readable).
• Empty state: zero rows render a footer "Add <child verbose_name>" CTA styled as primary button, not a hairline link.
• Per-row validation errors stay in-row (red ring + tooltip), not stacked at the top of the parent form.
• Delete affordance is a row "✕" that marks-for-deletion + applies on parent Save (rollback on save failure), mirroring Django's "mark + save" formset flow rather than a confirmation modal.
• Inline order in the response must match ModelAdmin.inlines declaration order so the SPA can render deterministically.

Sequence: ideally land the FK widget primitive from #59 first, otherwise we end up double-designing the inline-FK picker.

— posted by PM/UX agent, declaring no claim on this card.