[Feature] Collapse managed resources under business roles in the matrix

[robb536]

Is your feature request related to a problem? Please describe.
Business roles and their underlying managed resources are currently shown together in the matrix. This makes the matrix harder to read, because users see both the business role and the related resources at the same time. For role mining, this can feel redundant and creates visual noise.

Describe the solution you'd like
Add the ability to fold or collapse the combination of a business role and its underlying managed resources. When collapsed, only the business role should remain visible in the matrix. Users should be able to expand it again when they need to inspect the underlying resources.

Describe alternatives you've considered
Not applicable. This is a point solution for improving readability in the role mining matrix.

Additional context
This feature is intended for users who perform role mining. The issue occurs during use of the matrix, where both the business role and the underlying managed resources are shown. This request is not related to any open or closed issues.

[WimvandenHeijkant]

Hi @robb536 👋 Makes sense — the business role + its managed resources create noise. A few questions to pin the behaviour. A screenshot of the matrix marked up how you'd want it collapsed would help.

1. Default state: arrive collapsed (role only) or expanded?
2. Persistence: should collapse/expand choices stick per user (like row order), or reset each visit?
3. Generality: just business-role → managed-resources, or should the same collapse apply to other parent/child groupings (e.g. an application and its app-roles)?
4. Must-not-break: staircase sort, counts, export?
5. Imagine it's done: what's "perfect", what's "not quite"?

[robb536]

1. expanded
2. stick
3. start with business-role → managed-resources
4. yes
5. perfect: when you can fold until you only see business roles als resources not in a role

[github-actions]

Hi @robb536 — thanks for the crisp answers. They pinned everything the interview needed (default expanded, choices stick, scope deliberately limited to business-role → managed resources, staircase/counts/export must not break, and "perfect" = fold until only business roles and resources not in a role remain). I ran the build-readiness probe against the live code and schema; no open questions remain for you. The spec below is certified and moves to the Product-Board value gate.

---

📋 Certified spec — Fold managed resources under business roles in the matrix

What will be built

In the per-subject matrix (MatrixView), every business-role row visible in the grid gets a fold chevron. Folding it hides the rows of the resources that business role contains (the Contains children it grants), leaving the business-role row itself with a small "⊞ N resources folded" chip. Unfolding restores them. A "Fold roles" / "Unfold roles" toolbar pair (next to the existing Fold columns / Expand all controls) folds/unfolds every business role at once — one click reaches your "perfect" state: only business-role rows plus resources not granted by any role. Default state is expanded; fold choices persist per user per matrix (versioned localStorage keyed by the matrix filter — the exact mechanism custom row order already uses).

No API or schema change. The parent→child mapping is already modelled (ResourceRelationships, relationshipType='Contains') and already delivered to the matrix client via GET /api/access-package-groups (the accessPackageGroups prop MatrixView receives today for the SOLL columns). Folding is presentation state, the same tier as the existing column fold and nested-group expand — no data-model gap is being papered over.

One behaviour change to ratify (D2 below)

The probe found that today a business role's own row does not sit next to its resources: the AP-staircase sort buckets only the contained resources, so the business-role row itself falls into the "unmanaged" region at the bottom of the grid. Folding is spatially incoherent if the parent row is 200 rows away from its children. The spec therefore promotes each business-role row to sit directly above its resources' staircase bucket. Children keep their existing order — this is additive, and it's the one visible default-ordering change (requires the documented ROW_ORDER_VERSION bump so stale saved orders are discarded, per useMatrixRowOrder.js).

Decisions register (proposed — bulk-ratify at approval)

#	Decision	Owner
D1	Fold is pure view state: it hides rows, changes no counts, no fetch, no export. The Excel export keeps exporting the full row set — consistent with the existing column fold and nested expand, which the export also ignores.	Requestor
D2	Business-role row promoted to the top of its AP staircase bucket; ROW_ORDER_VERSION bumped.	Designer
D3	A resource contained in several business roles is hidden only when all of its containing business-role rows present in the grid are collapsed (an expanded role always shows its resources).	Requestor
D4	Fold affordance exists only on business-role rows present in the grid. If a role has no visible holders (no row), its resources stay visible — nothing vanishes without a visible parent.	Data-quality
D5	Persistence = versioned localStorage per matrix filter (per browser — same reach as the existing sticky row order; roaming server-side prefs are out of scope).	Architect
D6	A collapsed business-role row's cells are unchanged — they keep showing who holds the role and how. The fold does not roll child assignments up into the parent row.	Requestor
D7	Scope: the per-subject MatrixView only. The rotated and layered/rollup views are untouched (phase-2 if wanted).	Requestor (your Q3 choice)
D8	GroupOwnership rows are not folded — they are HasOwnership siblings, not Contains children of the role.	Architect
D9	Fold composes with the All / Governed / Non-governed / Gaps toggles: it is applied after those filters in the row pipeline (alongside nested-row injection).	Architect

Time-travel criteria

• Delighted: one click on "Fold roles" leaves exactly business-role rows + resources no role grants; per-role chevrons work individually; my folds are still there when I come back to the same matrix; staircase, drag order, counts panel and Excel export behave exactly as before.
• Disappointed (= reject): folding changes any number in the counts panel or export; a resource shared by two roles disappears while one of its roles is still expanded; fold state leaks between different matrix filters; the parent row is nowhere near its folded children.

Fixture-backed acceptance criteria

Fixture (exists in / topped up into the demo dataset): BR1 Contains {G1, G2}, BR2 Contains {G2, G3}, G4 in no role; user u1 holds BR1 (governed), u2 has Direct on G1 and G3.

1. BR1's row shows a fold chevron; clicking it hides the G1 and G2 rows and shows "2 resources folded" on BR1. Counts panel, AP columns and cell badges are byte-identical before/after.
2. With BR1 collapsed and BR2 expanded, G2 stays visible (D3); collapsing BR2 too hides G2 and G3.
3. "Fold roles" leaves exactly the BR1, BR2 and G4 rows (plus any ownership rows); "Unfold roles" restores everything.
4. Reload the page with the same matrix → fold state restored; open a different matrix filter → independent (expanded) state.
5. Excel export after folding is identical to the export before folding (D1).
6. A matrix containing no business-role rows shows no chevrons and no Fold/Unfold roles buttons (zero case).
7. If BR1 has no visible holders (row absent), G1/G2 keep no-fold behaviour and stay visible (D4).
8. A folded child's own expanded nested sub-rows disappear with it and reappear on unfold.
9. Drag-reorder still works; the staircase renders with each BR row atop its bucket; previously-saved custom orders are discarded once (version bump).
10. Chevron button has an accessible name ("Fold business role resources" / "Unfold …"), renders correctly in dark mode, and meets AA contrast.

Implementation & delivery (one PR)

• New app/ui/src/hooks/useBusinessRoleFold.js — parent→children map from accessPackageGroups, fold set, D3/D4 logic, versioned persistence. Fully unit-testable pure logic (ratchets coverage up).
• MatrixView.jsx — wire the hook into the row pipeline + staircase promotion (file is 1091 lines against a grandfathered 1170 ceiling; the wiring is small and all logic lives in the new hook, so the file-length ratchet holds).
• matrix/MatrixGroupRow.jsx — chevron + folded-count chip on business-role rows (no clash with the nested-expand chevron: business roles are never principals, so groupsWithNested never matches them).
• matrix/MatrixToolbar.jsx — "Fold roles" / "Unfold roles" (mirroring the existing Fold/Unfold columns pair).
• hooks/useMatrixRowOrder.js — ROW_ORDER_VERSION 6 → 7.
• Tests: hook unit tests (fold set, multi-parent, persistence versioning, filter isolation) + MatrixView.mount.test.jsx / toolbar mount-test extensions; the JSX render body falls under the accepted e2e-covered blind spot ([CI] Diff-coverage (UI) blind spot on pure-JSX page shells (UsersPage, detail & matrix views) #725).
• Docs: new "Business-role fold" subsection in docs/architecture/matrix.md; changelog fragment under changes/.
• Validation data: full demo dataset load per DoR D1 (its governance sync provides business roles with Contains grants); top up a BR2-style overlapping role if the demo data lacks one.

Backlog context

• [FEATURE] Separate Resources and Roles #869 Separate Resources and Roles (awaiting-requestor) — adjacent intent, different mechanism (type separation vs. hierarchy fold); no overlap, both can land.
• [FEATURE] Group Category missing from matrix view #870 (Group Category column), [UX] Rework the matrix Apply/Save verbs + 'Not saved' badge #768/[UX] Rotated matrix: hide/disable dropped controls + signal reduced mode #769 (matrix UX), [Perf] Cursor/keyset pagination for the flat matrix grid #788/[Perf] Virtualize matrix columns #789/[Perf] Paginate group-members/assignments endpoints + fix MatrixView O(n^2) count loop #796 (matrix perf) — orthogonal; note the fold is render-only and does not shrink the fetch, so it is not a perf fix.

---

Verdict: CERTIFIED — no open functional questions; decisions D1–D9 are defended from the live code/schema and batched here for one-shot ratification at the value gate. Routing to awaiting-approval.

[github-actions]

🗳️ @WimvandenHeijkant @TaekeK @robb536 — ready for the value gate. Review & approve to build → (open the run → Review deployments → approve build-approval). Nothing runs or spends until you do.