# WP3 — Redesign `/core/roles` permission editor (FE)

## Goal
Replace the flat one-checkbox-per-permission list with a fast, usable **resource × action matrix** where every permission shows an **info** (what it does), grouped by module, with search, presets, live coverage-lint, a "by-screen" mode, and an "API only — no screen yet" badge for permissions with no FE surface. Full replacement of the current permission-picker panel; **keep everything else** (role cards list, clone, name/scope/home-page fields, nav-customization tab, module-activation filtering, protected-role handling, validation). Consumes the WP1 catalog metadata with graceful fallback.

## Exact files
- **Modify:** `/home/moonui2/public_html/moon-erp/src/app/features/roles/roles.component.ts` / `.html` / `.scss` (current: 623 / 300 / 333 lines).
  - Keep: `filteredPermissionGroups` (module-activation), `translateModule`, `translateRoleName`, role list, scope/home-page, nav tab, save flow, protected roles.
  - Replace: the flat accordion permission list (`roles.component.html:202-230`) with the matrix.
  - `translatePermission()` (ts:547-571) becomes the FALLBACK label when catalog `label_ar/desc_ar` are absent.
- **Reference pattern (read, reuse generously):** `/home/moonui2/public_html/moon-erp/src/app/features/lis/roles/lis-roles.component.{ts,html,scss}` — it already has by-screen mode, presets (`applyPreset`), and `coverageWarnings()`. Generalize its approach to all modules.
- **Design source (the approved shape):** `knowledge-base/plans/permissions-screen-redesign-analysis.html` §9 (Fable mockup) + `/tmp/claude-0/.../scratchpad/fable-roles-mockup.html`. Match that layout: module rail + toolbar (search + quick filters + mode toggle) + presets row + resource×action matrix + info popover + coverage-lint footer.
- **i18n:** add any new keys to `src/assets/i18n/{ar,en}.json` (`ROLES.*` — e.g. `ROLES.MATRIX_VIEW`, `ROLES.BY_SCREEN`, `ROLES.API_ONLY`, `ROLES.COVERAGE_WARN`, preset labels). Keep `ROLES.DESCRIPTIONS.*` as the FE i18n fallback layer (optional).

## Interfaces
- **Consumes from WP1:** `GET /core/permissions` → `{ data: { <module>: [ { key, label, label_ar?, label_en?, desc_ar?, desc_en?, danger?, kind?, resource? } ] } }`. Build the matrix by grouping each module's permissions by `resource` (derive resource+action from the key `module.resource.action` when `resource` field is absent), columns = canonical actions (view/create/update/delete/approve/post + "other"). Show `desc_*` in the info popover; `danger` → red cell; missing catalog fields → compose label via the old `translatePermission()`.
- **"API only" badge:** a permission is API-only when it has no FE gate anywhere. WP3 doesn't need to compute the full 144 live; a simple heuristic (module has no route/menu in the app, e.g. webstore/qms/crm/cmms/nphies/einvoicing + inventory.costing) OR a static list from the analysis is acceptable for the badge. Keep grantable.

## Acceptance criteria
- [ ] Matrix renders: resource rows × action columns, tri-state resource checkbox, column "select all", module rail, module select-all, n/m badges.
- [ ] Every permission shows an info (tooltip/popover) with its description; danger actions visually distinct.
- [ ] Search filters by resource/action/description; quick filters (selected / danger) work; module rail navigates.
- [ ] "By-screen" mode toggle present (may reuse/adapt LIS by-screen for at least the priority modules; graceful if catalog screen data is partial).
- [ ] Coverage-lint strip shows missing hidden dependencies where known (reuse LIS `coverageWarnings` generalization) — non-blocking if data absent.
- [ ] "API only — no screen yet" badge on API-only permissions; they remain grantable.
- [ ] Saving a role writes the SAME payload as today (no change to the save contract); existing role edit/clone/scope/home-page/nav tab all still work.
- [ ] Fallback: a permission with no catalog metadata still renders with a readable label (no raw key shown).

## Tests
- FE: `ng build` green. Manual owner test on `/app` (build + deploy `/app` after this WP — owner tests live). No FE unit runner in this project.

## Flags
- **[FIN]** — pivotal UI/shared core (governs how ALL permissions are granted). Fable/advisor consult on the final interaction model before finalizing.
- **Migration:** none.

## Out of scope
- Do NOT change the save payload / role API. Do NOT change `permission.service.ts` matching. Do NOT do the `*appCan` button hardening (WP4). Do NOT remove the nav-customization tab or scope/home-page fields.