docs(edit-content): spec for #37192 relationship field picker and related-list fixes

[adrianjm-dotCMS]

PR 1 of 2 — spec only. No code. Per Spec-Kit, this carries spec.md alone and needs approval (not merge) before planning starts. Implementation lands in PR 2, branched off this one.

Resolves the specification for #37192.

Proposed Changes

• Adds specs/37192-relationship-field-assetpicker/spec.md — 36 functional requirements, 43 acceptance scenarios across 6 user stories. One file, no code.

What the spec says

It splits #37192 into two independent bodies of work that happen to share a field:

A · The "Add Relationships" picker (US 1–3)

• Moves onto the shared search surface: full-width search bar + filter chips (site/folder, Locale). No folder-tree sidebar — the folder scope is a chip, per the design artboard.
• Searches through api/v1/drive/search, replacing the relationship-specific search path.
• It is a selection editor, not an add-only dialog: opens with already-related items checked, unchecking removes, confirming leaves the relationship equal to the selection.
• The confirm action is never disabled — confirming with an empty selection unrelates everything.
• Keeps its own paging.

B · The related-content list in the form (US 4–6)

• Loses its 6-row paging; renders 40 rows plus a "Load more" control, following the Key/Value field precedent (Refactor shared Key/Value field to new design across edit content, field variables, and apps portlet #37191). Withholding is a rendering limit only — the value always holds every item.
• Hover-only drag handle, right-aligned Status column, single-column form max width (New Edit Content: apply field padding (18px) and form max-width (720px/1000px) guidelines #36615).

Decisions worth a reviewer's eye

Three scope questions had no safe default and were settled before writing:

Question	Settled as
How much of the AssetPicker shell is adopted?	Shared search + chips + table + paging. No sidebar — settled by the design.
How is multi-select satisfied?	It already exists: dot-folder-list-view defaults to selectionMode: 'multiple' and Content Drive already holds a set. Configuration, not a new capability — the AssetPicker's single-slot selection is untouched.
What bounds the form's list without paging?	40 + "Load more" (#37191 precedent).

One deliberate addition beyond the issue's original ACs: the confirm action is never disabled. The issue said nothing about it; it is the only reading consistent with "unchecking a row removes it". The issue's acceptance criteria were updated to match before opening this PR.

Out of scope (recorded so PR 2 isn't reviewed against them)

• Relationship field UI refinements: Content Drive chip colors, Locales tag column, hint & empty-state, showFields #36155 — chip colors, Locales column, hint, empty state, showFields. Separate issue by an explicit scope decision.
• Any backend change. Frontend-only against existing contracts — no new endpoint, no request/response change, so no Integration or Postman coverage.
• The legacy Dojo edit contentlet (New AssetPicker must not be used in the legacy Dojo editor — pick the picker per host (WYSIWYG, Block Editor, File/Image) #37132) and the "New content" path.

Checklist

• Tests — n/a for a spec PR. The spec's Suggested Tests drive PR 2, where TDD gates apply (constitution Principle V).
• Translations — n/a, no user-facing strings in this PR.
• Security Implications Contemplated — none. Documentation only; no code, no endpoint, no data path.

Additional Info

⚠️ The design canvas could not be opened while writing this spec (it needs a session). It was written against a screenshot of the "Add Relationships" artboard supplied by the author. Visual requirements are therefore stated as observable behavior, with the design named as the visual authority in the Assumptions section. If the canvas contradicts any acceptance scenario behaviorally, that is a spec amendment before /speckit-plan — please flag it if you can see the canvas.

The spec also assumes api/v1/drive/search can already answer "content of type X across the site" with the filters the picker needs, since the issue reuses it as-is and lists no backend work. If a needed filter proves unreachable, that is a finding for the plan phase, not a silent scope expansion.

🤖 Generated with Claude Code

This PR fixes: #37192

[claude]

Claude finished @adrianjm-dotCMS's task in 1m 9s —— View job

---

Spec Review — specs/37192-relationship-field-assetpicker/spec.md

This is a spec-only PR, so I reviewed for internal consistency, contradictions, ambiguity, and cross-reference correctness rather than code. The spec is unusually thorough and the A/B scope split is clean. Two cross-reference errors are worth correcting before /speckit-plan reads it, since they invert which requirement is being cited.

New Issues

• 🟡 Medium: specs/37192-relationship-field-assetpicker/spec.md:322 — The "Unchecking every row" edge case cites FR-012 for "the action is never disabled":

  This spec changes that (FR-012): the action is never disabled, and confirming with an empty selection clears the relationship.

  But FR-012 (line 380) is "Confirming MUST leave the field's related content equal to the picker's selection…". The "never disabled" requirement is FR-013 (line 383). This should cite FR-013. Fix this →

• 🟡 Medium: specs/37192-relationship-field-assetpicker/spec.md:377 — The FR-011 rationale cites FR-013 as the requirement it protects:

  This is the requirement that keeps FR-013 safe. … without this requirement an item the editor never scrolled to would be dropped on confirm.

  The described failure ("dropped on confirm") is about confirmation reconciling against the whole selection — that is FR-012 (line 380), not FR-013 (confirm-never-disabled). This should cite FR-012. Together with the finding above, these two look like a straight FR-012 ↔ FR-013 swap. Fix this →

Notes (non-blocking, not spec-file issues)

• The PR description says "36 functional requirements", but the spec defines FR-001 through FR-037 (37). Numbering is sequential with no gaps or dupes; just the description count is off by one.

Everything else checks out: the A/B split (picker keeps paging via FR-017; form list drops it via FR-021 and gains Load more via FR-022–FR-024) is internally consistent, FR ↔ acceptance-scenario mapping is coherent, the FR-007/FR-016 single-cardinality reconciliation is explicit, and the out-of-scope list (#36155, backend, legacy Dojo, "New content") is recorded clearly. The two /speckit-plan deferrals (drive/search filter reachability, shared browse-state carrying a set) are flagged as assumptions rather than silently assumed, which is the right call.
· issue-37192-relationship-field-assetpicker