Closes: #15165 - HTMX partial fieldset re-rendering for HTMXSelect forms

[bctiemann]

Closes: #15165

Summary

Replaces the full #form_fields swap with targeted per-fieldset swaps for all HTMXSelect fields where it is safe to do so, eliminating the visible flash on large forms when a select value changes.

How it works

• FieldSet gains an optional fieldset_id= parameter that renders as the HTML id on the fieldset <div>.
• HTMXSelect gains an optional hx_fieldset_id= parameter. When set, the widget emits hx-select and retargets hx-target to the named fieldset instead of #form_fields. hx-include remains #form_fields so all field values are submitted and server-side dependent-field resolution continues to work correctly.
• No view or server-side template changes are required — the server still returns the full form HTML; HTMX's hx-select extracts only the matching element on the client side.

Forms updated

Form	Trigger field	Target fieldset
InterfaceForm	mode	dot1q-switching
VMInterfaceForm	mode	dot1q-switching
CableForm	a_terminations_type / b_terminations_type	cable-side-a / cable-side-b (hand-rolled template)
ModuleTypeForm	profile	profile-attributes (dynamic fieldset)
ScopedForm mixin	scope_type	scope (applied to ClusterForm, WirelessLANForm, PrefixForm)
VLANGroupForm	scope_type	scope
ServiceForm	parent_object_type	service
CircuitTerminationForm	termination_type	circuit-termination
CircuitGroupAssignmentForm	member_type	circuit-group-assignment
VirtualCircuitTerminationForm	role	virtual-circuit-termination
TunnelCreateForm	termination1_type / termination2_type	tunnel-termination1 / tunnel-termination2
TunnelTerminationForm	type	tunnel-termination
EventRuleForm	action_type	event-rule-action

Forms intentionally left on full-form swap

Three forms keep HTMXSelect() without hx_fieldset_id because changing their trigger field adds or removes entire fieldsets dynamically — a partial swap would silently miss those additions. Each is annotated with an inline comment explaining the constraint:

• CustomFieldForm — type change dynamically adds/removes Validation, Related Object, and Choices fieldsets via self.fieldsets = ... in __init__
• DataSourceForm — type change conditionally appends a Backend Parameters fieldset
• VirtualMachineForm — virtual_machine_type populates defaults across both the Virtual Machine and Resources fieldsets

Notes

• FieldSet.id must be a valid CSS identifier (start with a letter). The inline docstring notes this constraint.
• The CableForm change targets <div> elements in dcim/htmx/cable_edit.html directly (that form uses a hand-rolled HTMX template rather than the fieldset rendering system).
• Bulk-edit forms (ScopedBulkEditForm, CircuitTerminationBulkEditForm, VLANGroupBulkEditForm) already use an explicit hx-select targeting #form_fields for a different purpose and are unchanged.

Test plan

• InterfaceForm: change 802.1Q Mode — only the 802.1Q Switching fieldset updates; no full-form flash
• CableForm: change A Side type — only A Side updates; B Side is unaffected
• CableForm: change B Side type independently
• ModuleTypeForm: switch profile — only Profile & Attributes fieldset re-renders; dynamically added attribute fields appear correctly
• utilities test suite (314 tests): all pass
• dcim form tests (30 tests): all pass

🤖 Generated with Claude Code

---

Addendum — Review feedback (Jun 9)

Two naming improvements made in response to Jeremy's review:

FieldSet: fieldset_id → html_id

The parameter name was redundant given it lives on a class already called FieldSet. Renamed to html_id throughout — rendering.py, form_helpers templatetag, render_fieldset.html, all call sites in forms, and tests.

HTMXSelect: split hx_target_id / hx_fieldset_id into hx_include_id / hx_target_id

Jeremy asked why hx_target_id couldn't simply be overridden instead of needing a separate hx_fieldset_id. The reason: the original hx_target_id controlled both hx-include (the form data source) and the default hx-target. Overriding it would also scope hx-include to just the fieldset, dropping the rest of the form data and breaking server-side dependent-field resolution.

Fixed by separating the two concerns explicitly:

Parameter	Controls	Default
hx_include_id	hx-include — which container's fields are submitted	'form_fields'
hx_target_id	hx-target + hx-select — which element to swap	None (falls back to hx_include_id)

Jeremy's instinct is now correct: HTMXSelect(hx_target_id='dot1q-switching') does exactly what was expected — hx-include stays #form_fields while hx-target and hx-select narrow to #dot1q-switching.

All call sites, tests, and the ScopedForm runtime guard updated accordingly. The inline comments referencing the old hx_fieldset_id name updated to hx_target_id.

[bctiemann]

@claude /review

[github-actions]

Claude finished @bctiemann's task in 4m 13s —— View job

---

PR Review: feat(ui): HTMX partial fieldset re-rendering for HTMXSelect forms

Todo List

• Gather context and understand the PR
• Read changed files
• Analyze code quality and correctness
• Check test coverage
• Post review feedback

---

Overview

This PR replaces full #form_fields swaps with targeted per-fieldset outerHTML swaps for HTMXSelect fields, eliminating the visible flash on large forms when a select value changes. The mechanism is clean:

• FieldSet gains an optional fieldset_id= parameter rendered as an HTML id on the <div>
• HTMXSelect gains hx_fieldset_id=; when set it emits hx-target, hx-select, and hx-swap=outerHTML; hx-include still covers #form_fields so all field values travel to the server
• No server-side view or template logic changes needed — the server continues returning the full form; HTMX extracts only the matching element client-side

The interaction with the pre-existing hx-disinherit="hx-select hx-swap" on #form_fields (in templates/generic/object_edit.html:65) is correctly handled, since the widget now sets these attributes explicitly on the <select> element rather than relying on inheritance.

---

Strengths

Elegant design. No server-side changes needed. The change is entirely additive and backward-compatible — existing FieldSets and HTMXSelect instances without the new parameters are completely unaffected.

Good documentation of exceptions. The inline comments on CustomFieldForm, DataSourceForm, and VirtualMachineForm are exactly the right approach — explaining why they cannot use partial swaps rather than just leaving them as is.

Consistent application. All HTMXSelect widgets in the codebase have been audited and appropriately updated or annotated. The PR description table is a useful reference.

Test coverage. FieldSetTestCase and HTMXSelectTestCase in utilities/tests/test_forms.py cover the new widget attributes correctly.

---

Issues and Suggestions

1. Implicit contract for ScopedForm consumers (mild concern)

ScopedForm.scope_type at dcim/forms/mixins.py:31 hardwires hx_fieldset_id='scope', relying on every consumer to declare FieldSet(..., fieldset_id='scope'). Currently all three consumers (ClusterForm, WirelessLANForm, PrefixForm) do this correctly. But the only enforcement is a code comment. A future consumer that omits fieldset_id='scope' will silently get broken HTMX behavior — the swap targets a non-existent #scope element and does nothing (no error, no warning).

Suggestion: Promote the constraint to the ScopedForm class docstring, or add a __init_subclass__ check in debug mode.

# In ScopedForm or its __init__
def __init__(self, *args, **kwargs):
    super().__init__(*args, **kwargs)
    if settings.DEBUG:
        has_scope_fieldset = any(
            getattr(fs, 'fieldset_id', None) == 'scope'
            for fs in getattr(self, 'fieldsets', [])
        )
        if not has_scope_fieldset:
            import warnings
            warnings.warn(
                f"{self.__class__.__name__} uses ScopedForm but declares no "
                "FieldSet with fieldset_id='scope'; HTMX partial swap will fail silently.",
                stacklevel=2,
            )

Fix this →

---

2. No validation of fieldset_id as a valid CSS identifier (minor)

The docstring for FieldSet documents the constraint ("Must be a valid CSS identifier: start with a letter…"), but passing fieldset_id='123-bad' renders id="123-bad" in the HTML and hx-target="#123-bad" on the widget, both of which silently fail in a CSS selector context. A DEBUG-mode re.match check in FieldSet.__init__() would surface this early during development.

import re

def __init__(self, *items, name=None, fieldset_id=None):
    if fieldset_id is not None and settings.DEBUG:
        if not re.match(r'^[a-zA-Z][a-zA-Z0-9_-]*$', fieldset_id):
            raise ValueError(f"fieldset_id {fieldset_id!r} is not a valid CSS identifier")
    self.items = items
    self.name = name
    self.fieldset_id = fieldset_id

Fix this →

---

3. hx_target_id naming overlap in HTMXSelect (nit, pre-existing)

In utilities/forms/widgets/select.py:64, hx_target_id is used as both the hx-include container and the fallback hx-target when hx_fieldset_id is absent. The dual role of the same parameter makes the initialiser slightly harder to read. This is pre-existing behaviour; not a blocker for this PR.

---

4. ServiceForm single-fieldset observation (not an issue, just noting)

ServiceForm has a single fieldset_id='service' that contains all form fields (ipam/forms/model_forms.py:808–814). Swapping #service vs the full #form_fields is technically a smaller swap only if #form_fields contains outer chrome (e.g., custom fields, comments) outside the fieldset. The correctness is not affected, but the UX gain is minimal if all fields live in one fieldset. Still a valid use of the pattern.

---

Test Coverage

The unit tests at utilities/tests/test_forms.py:631–659 are correct and cover:

• FieldSet.fieldset_id defaults to None
• FieldSet.fieldset_id is stored
• HTMXSelect() (no hx_fieldset_id) targets #form_fields, no hx-select/hx-swap
• HTMXSelect(hx_fieldset_id=...) sets hx-target, hx-select, hx-swap=outerHTML
• hx-include remains #form_fields regardless of hx_fieldset_id

The tests are purely attribute-level (not end-to-end render tests), which is appropriate given that no template logic changed.

---

Summary

The implementation is clean, minimal, and correct. The two items worth acting on before merge are:

1. The implicit ScopedForm consumer contract — a comment upgrade or a light DEBUG-mode assertion would prevent future silent breakage
2. The fieldset_id CSS identifier constraint — enforcing it even in a simple DEBUG-mode check would prevent confusing failures

Neither is a blocker, but both would improve maintainability. All existing consumers are correctly wired. The code is ready to merge pending those considerations.

[bctiemann]

Addressed the two actionable items.

[bctiemann]

Thanks for the thorough review — addressed in the latest push:

• Dropped the errant HTMXSelect from VirtualCircuitTerminationForm.role
• Fixed the three stale hx_fieldset_id comments → hx_target_id
• Added html_id='scope' to PrefixBulkAddForm's Scope fieldset and html_id='service' to ServiceCreateForm's Application Service fieldset

Two open points worth a word:

Auto-generating slugified IDs for FieldSets: I lean toward keeping them explicit for this PR. Auto-generation is appealing, but it would require updating every hx_target_id value in every form and every HTMX hx-target attribute in templates to use the new fieldset-* prefix — a wider blast radius than seems right for a follow-up. Happy to do it as a separate cleanup if you'd prefer consistency over explicitness.

termination_type required=False: The underlying model field is a nullable FK (null=True, blank=True on CircuitTermination.termination_type), so a circuit termination can legitimately be saved with no termination target at all. The required=False corrects what was a latent mismatch with the model — the form was previously required=True by default even though the DB allows null. The form's clean() already handles the "type selected but no termination" case; the only new behaviour is allowing both to be blank.