@team-codeme/crud-forge 0.0.0-stage → 1.0.1

package/src/templates/angular/iam/role-permission-matrix.component.ts.ejs

@@ -0,0 +1,800 @@
+import { Component, OnInit, inject, signal, computed } from '@angular/core';
+import { CommonModule, NgTemplateOutlet } from '@angular/common';
+import { RouterLink, Router, ActivatedRoute } from '@angular/router';
+import { HttpClient } from '@angular/common/http';
+import { MatButtonModule } from '@angular/material/button';
+import { MatIconModule } from '@angular/material/icon';
+import { MatSnackBar, MatSnackBarModule } from '@angular/material/snack-bar';
+import { MatProgressSpinnerModule } from '@angular/material/progress-spinner';
+import { MatPaginatorModule, PageEvent } from '@angular/material/paginator';
+import { forkJoin, of, from } from 'rxjs';
+import { catchError, concatMap, finalize, map, toArray } from 'rxjs/operators';
+import { RolePermissionSkeletonComponent } from '@/app/core/user-management/shared/role-permission-skeleton.component';
+import { formatRoleDisplayName } from '@/app/core/user-management/shared/role-display.util';
+import {
+    buildScreenComponentClusters,
+    filterMatrixClusters,
+    getCleanScreenId,
+    getCleanScreenName,
+    GroupedScreenCluster,
+    highlightMatrixText,
+    parseCsvComponentToScreenMap,
+    parseCsvRegistry,
+} from '@/app/core/user-management/shared/screen-matrix.util';
+import {
+    buildMatrixHierarchy,
+    filterMatrixHierarchy,
+    matchClusterForHierarchySearch,
+    MatrixHierarchyItem,
+    MatrixPageGroup,
+} from '@/app/core/user-management/shared/matrix-hierarchy.util';
+import {
+    filterEssentialComponentIds,
+    isSensitiveComponentId,
+} from '@/app/core/user-management/shared/screen-navigation-map';
+import { ScreenNavigationRegistry } from '@/app/core/user-management/shared/screen-navigation.registry';
+import {
+  playPermissionGrantSound,
+  playPermissionRevokeSound,
+} from '@/app/core/user-management/shared/permission-matrix-sound';
+import {
+  KeycloakAdminService,
+  RoleRepresentation,
+  UserAttributes,
+  isScreenPermissionGranted,
+  isComponentPermissionGranted,
+  normalizeUserAttributes,
+  revokeScreenGrant,
+  AccessCtrlPipe,
+} from '@/app/core/auth';
+
+export type GroupedScreen = GroupedScreenCluster;
+
+@Component({
+    selector: 'app-role-permission-matrix',
+    standalone: true,
+    host: {
+        class: 'flex flex-col flex-1 min-h-0 min-w-0 h-full w-full overflow-hidden'
+    },
+    imports: [
+        AccessCtrlPipe,
+        CommonModule,
+        NgTemplateOutlet,
+        RouterLink,
+        MatButtonModule,
+        MatIconModule,
+        MatSnackBarModule,
+        MatProgressSpinnerModule,
+        MatPaginatorModule,
+        RolePermissionSkeletonComponent
+    ],
+    templateUrl: './role-permission-matrix.component.html',
+    styleUrl: './role-permission-matrix.component.scss'
+})
+export class RolePermissionMatrixComponent implements OnInit {
+    readonly SCREEN = 'role-permission-matrix';
+    private keycloakAdminService = inject(KeycloakAdminService);
+            private snackBar = inject(MatSnackBar);
+    private http = inject(HttpClient);
+    private screenNavigation = inject(ScreenNavigationRegistry);
+        
+    private readonly collapsedStorageKey = 'role-permission-matrix-collapsed-screens';
+    private readonly paginationStorageKey = 'role-permission-matrix-pagination';
+
+    private router = inject(Router);
+    private route = inject(ActivatedRoute);
+
+    allRoles = signal<RoleRepresentation[]>([]);
+            filteredRoleName = signal<string | null>(null);
+
+    readonly IGNORED_REALM_ROLES = new Set(
+        ['offline_access', 'default-roles-jhipster', 'uma_authorization', 'default-roles-siis-dev', 'role_user', 'role_admin', 'ghost_account'].map(
+            (s) => s.toLowerCase()
+        )
+    );
+
+    roles = computed(() => {
+        const roleFilter = this.filteredRoleName();
+                        const list = this.allRoles();
+        const filtered = list.filter(
+            (r) => r.name
+                && !this.IGNORED_REALM_ROLES.has(r.name.toLowerCase())
+                                        );
+        if (roleFilter) {
+            return filtered.filter(r => r.name === roleFilter);
+        }
+        return filtered;
+    });
+
+    screensData = signal<GroupedScreen[]>([]);
+    collapsedScreens = signal<Record<string, boolean>>({});
+    
+    // Search & Pagination Signals
+    searchScope = signal<'ALL' | 'SCREEN'>('SCREEN');
+    searchTerm = signal<string>('');
+    pageSize = signal<number>(100);
+    currentPage = signal<number>(0);
+    /** Floating filter: when true, table shows only screens already enabled for visible role(s). */
+    showEnabledOnly = signal<boolean>(false);
+    
+    // Role name → Keycloak role permission attributes
+    rolePermissionMap = signal<Record<string, UserAttributes>>({});
+
+    isLoading = signal<boolean>(true);
+    isSaving = signal<boolean>(false);
+    isProcessingToggle = signal<Record<string, boolean>>({});
+
+    isAnyToggleProcessing = computed(() => {
+        const map = this.isProcessingToggle();
+        return Object.values(map).some(Boolean);
+    });
+
+    isUiLocked = computed(() => {
+        return this.isLoading() || this.isSaving();
+    });
+
+    getScreenToggleKey(roleName: string, screenId: String | string): string {
+        return `${roleName}_screen_${String(screenId)}`;
+    }
+
+    getComponentToggleKey(roleName: string, componentId: String | string): string {
+        return `${roleName}_${String(componentId)}`;
+    }
+
+    isToggleProcessing(toggleKey: string): boolean {
+        return Boolean(this.isProcessingToggle()[toggleKey]);
+    }
+
+    isScreenToggleDisabled(roleName: string, group: GroupedScreen): boolean {
+        return this.isUiLocked() || this.isToggleProcessing(this.getScreenToggleKey(roleName, group.screen.screenId || ''));
+    }
+
+    isComponentToggleDisabled(roleName: string, componentId: String | string, group: GroupedScreen): boolean {
+        return this.isUiLocked()
+            || !this.isClusterScreenPermissionMapped(roleName, group)
+            || this.isToggleProcessing(this.getComponentToggleKey(roleName, componentId));
+    }
+
+    formatRoleName(roleName: string | null | undefined): string {
+        return formatRoleDisplayName(roleName);
+    }
+
+    getCleanScreenName = getCleanScreenName;
+    getCleanScreenId = getCleanScreenId;
+
+    /** Flat clusters → generated page hierarchy (from sync) + remaining A–Z rows. */
+    hierarchyData = computed(() =>
+        buildMatrixHierarchy(this.screensData(), this.screenNavigation.pages())
+    );
+
+    filteredHierarchyData = computed(() => {
+        const searched = filterMatrixHierarchy(
+            this.hierarchyData(),
+            this.searchTerm(),
+            this.searchScope(),
+            (group, search, scope) =>
+                matchClusterForHierarchySearch(group, search, scope, filterMatrixClusters)
+        );
+        if (!this.showEnabledOnly()) {
+            return searched;
+        }
+        const visibleRoles = this.roles();
+        return searched.filter((item) => {
+            if (item.kind === 'flat') {
+                return visibleRoles.some((role) =>
+                    this.isClusterScreenPermissionMapped(role.name || '', item.group)
+                );
+            }
+            return visibleRoles.some(
+                (role) =>
+                    this.isClusterScreenPermissionMapped(role.name || '', item.host) ||
+                    item.embeds.some((embed) =>
+                        this.isClusterScreenPermissionMapped(role.name || '', embed)
+                    )
+            );
+        });
+    });
+
+    filteredScreensData = computed(() => {
+
+        const searched = filterMatrixClusters(this.screensData(), this.searchTerm(), this.searchScope());
+        if (!this.showEnabledOnly()) {
+            return searched;
+        }
+        const visibleRoles = this.roles();
+        return searched.filter((group) =>
+            visibleRoles.some((role) => this.isClusterScreenPermissionMapped(role.name || '', group))
+        );
+    });
+
+    enabledScreenCount = computed(() => {
+        const groups = filterMatrixClusters(this.screensData(), '', 'SCREEN');
+        const visibleRoles = this.roles();
+        return groups.filter((group) =>
+            visibleRoles.some((role) => this.isClusterScreenPermissionMapped(role.name || '', group))
+        ).length;
+    });
+
+    onSearchScopeChange(event: Event, searchInput: HTMLInputElement) {
+        const select = event.target as HTMLSelectElement;
+        const next = select.value as 'ALL' | 'SCREEN';
+        if (next === this.searchScope()) {
+            return;
+        }
+        this.searchScope.set(next);
+        this.searchTerm.set('');
+        searchInput.value = '';
+        this.currentPage.set(0);
+    }
+
+    toggleShowEnabledOnly(): void {
+        this.showEnabledOnly.update((v) => !v);
+        this.currentPage.set(0);
+    }
+
+    paginatedHierarchyData = computed(() => {
+        const data = this.filteredHierarchyData();
+        const size = this.pageSize();
+        const page = this.currentPage();
+        const start = page * size;
+        return data.slice(start, start + size);
+    });
+
+    // Slice filtered data by page size & index
+    paginatedScreensData = computed(() => {
+        const data = this.filteredScreensData();
+        const size = this.pageSize();
+        const page = this.currentPage();
+        const start = page * size;
+        return data.slice(start, start + size);
+    });
+
+    ngOnInit(): void {
+        this.loadPaginationPreferences();
+
+        // Listen to role filter query parameter
+        this.route.queryParams.subscribe(params => {
+            const roleParam = params['role'];
+            if (roleParam) {
+                this.filteredRoleName.set(roleParam);
+            } else {
+                this.filteredRoleName.set(null);
+            }
+        });
+
+        this.loadRolesAndMappings();
+    }
+
+    clearRoleFilter(): void {
+        this.filteredRoleName.set(null);
+        this.router.navigate([], {
+            relativeTo: this.route,
+            queryParams: { role: null },
+            queryParamsHandling: 'merge'
+        });
+    }
+
+    private loadPaginationPreferences(): void {
+        if (typeof localStorage !== 'undefined') {
+            try {
+                const raw = localStorage.getItem(this.paginationStorageKey);
+                if (raw) {
+                    const parsed = JSON.parse(raw);
+                    if (parsed && typeof parsed.pageSize === 'number') {
+                        this.pageSize.set(parsed.pageSize);
+                    }
+                    if (parsed && typeof parsed.currentPage === 'number') {
+                        this.currentPage.set(parsed.currentPage);
+                    }
+                }
+            } catch (e) {
+                console.error('Failed to load pagination preferences', e);
+            }
+        }
+    }
+
+    onSearchTermChange(event: Event): void {
+        const val = (event.target as HTMLInputElement).value;
+        this.searchTerm.set(val);
+        this.currentPage.set(0); // Reset page to 0 on search
+    }
+
+    clearSearch() {
+        this.searchTerm.set('');
+        this.currentPage.set(0);
+    }
+
+    onPageChange(event: PageEvent): void {
+        this.currentPage.set(event.pageIndex);
+        this.pageSize.set(event.pageSize);
+        this.savePaginationPreferences(event.pageSize, event.pageIndex);
+    }
+
+    private savePaginationPreferences(pageSize: number, currentPage: number): void {
+        if (typeof localStorage !== 'undefined') {
+            try {
+                localStorage.setItem(
+                    this.paginationStorageKey,
+                    JSON.stringify({ pageSize, currentPage })
+                );
+            } catch (e) {
+                console.error('Failed to save pagination preferences', e);
+            }
+        }
+    }
+
+    highlightText(text: String | null | undefined): string {
+        return highlightMatrixText(text, this.searchTerm());
+    }
+
+    isSensitiveComponent = isSensitiveComponentId;
+
+    pageCollapseKey(page: MatrixPageGroup): string {
+        return `page:${page.page.hostScreenId}`;
+    }
+
+    embedCollapseKey(page: MatrixPageGroup, embed: GroupedScreen): string {
+        return `embed:${page.page.hostScreenId}:${embed.cleanScreenId}`;
+    }
+
+    isPageCollapsed(page: MatrixPageGroup): boolean {
+        return this.isScreenCollapsed(this.pageCollapseKey(page));
+    }
+
+    togglePageCollapse(page: MatrixPageGroup): void {
+        this.toggleScreenCollapse(this.pageCollapseKey(page));
+    }
+
+    isEmbedCollapsed(page: MatrixPageGroup, embed: GroupedScreen): boolean {
+        return this.isScreenCollapsed(this.embedCollapseKey(page, embed));
+    }
+
+    toggleEmbedCollapse(page: MatrixPageGroup, embed: GroupedScreen): void {
+        this.toggleScreenCollapse(this.embedCollapseKey(page, embed));
+    }
+
+    trackHierarchyItem(item: MatrixHierarchyItem): string {
+        if (item.kind === 'page') {
+            return `page:${item.page.hostScreenId}`;
+        }
+        return `flat:${item.group.cleanScreenId}`;
+    }
+
+    isPageEssentialsProcessing(roleName: string, page: MatrixPageGroup): boolean {
+        return this.isToggleProcessing(`page-essentials_${roleName}_${page.page.hostScreenId}`);
+    }
+
+
+    toggleScreenCollapse(screenId: String | null | undefined): void {
+        const id = screenId ? String(screenId) : '';
+        if (!id) return;
+        const current = this.collapsedScreens();
+        const nextState = !this.isScreenCollapsed(id);
+        const updated = {
+            ...current,
+            [id]: nextState
+        };
+        this.collapsedScreens.set(updated);
+        
+        if (typeof localStorage !== 'undefined') {
+            try {
+                localStorage.setItem(this.collapsedStorageKey, JSON.stringify(updated));
+            } catch (e) {
+                console.error(e);
+            }
+        }
+    }
+
+    isScreenCollapsed(screenId: String | null | undefined): boolean {
+        const id = screenId ? String(screenId) : '';
+        
+        if (this.searchTerm().trim()) {
+            return false;
+        }
+        
+        // Default to true (collapsed) if not explicitly tracked
+        const current = this.collapsedScreens();
+        return current[id] !== false;
+    }
+
+    loadRolesAndMappings(): void {
+        this.isLoading.set(true);
+        forkJoin({
+            roles: this.keycloakAdminService.getRealmRoles(),
+            csv: this.http.get('assets/screen-components.csv', { responseType: 'text' }).pipe(catchError(() => of(''))),
+        }).subscribe({
+            next: (res) => {
+                const allRoles = res.roles || [];
+                this.allRoles.set(allRoles);
+
+                const csvRows = parseCsvRegistry(res.csv);
+                const csvComponentToScreenMap = parseCsvComponentToScreenMap(res.csv);
+                const screens: never[] = [];
+                const components: never[] = [];
+                if (typeof localStorage !== 'undefined') {
+                    try {
+                        localStorage.removeItem(this.collapsedStorageKey);
+                    } catch (e) {
+                        console.error(e);
+                    }
+                }
+
+                this.collapsedScreens.set({});
+                this.screensData.set(
+                    buildScreenComponentClusters(screens, components, csvComponentToScreenMap, csvRows)
+                );
+
+                const roleFilter = this.filteredRoleName();
+                const rolesForMatrix = allRoles.filter(
+                    (r) => r.name
+                        && !this.IGNORED_REALM_ROLES.has(r.name.toLowerCase())
+                );
+                const rolesToLoad = roleFilter
+                    ? rolesForMatrix.filter((r) => r.name === roleFilter)
+                    : rolesForMatrix;
+
+                if (rolesToLoad.length === 0) {
+                    this.rolePermissionMap.set({});
+                    this.isLoading.set(false);
+                    return;
+                }
+
+                const attrsByRole: Record<string, UserAttributes> = {};
+                rolesToLoad.forEach((role) => {
+                    if (role.name) {
+                        attrsByRole[role.name] = normalizeUserAttributes(role.attributes || {});
+                    }
+                });
+
+                const rolesNeedingFetch = rolesToLoad.filter((role) => {
+                    if (!role.name) {
+                        return false;
+                    }
+                    const attrs = attrsByRole[role.name] || {};
+                    return Object.keys(attrs).filter((k) => k !== 'parentRole').length === 0;
+                });
+
+                if (rolesNeedingFetch.length === 0) {
+                    this.rolePermissionMap.set(attrsByRole);
+                    this.isLoading.set(false);
+                    return;
+                }
+
+                forkJoin(
+                    rolesNeedingFetch.map((role) =>
+                        this.keycloakAdminService.getRealmRolePermissionAttributes(role.name!).pipe(
+                            map((attrs: UserAttributes) => ({ name: role.name!, attrs })),
+                            catchError(() => of({ name: role.name!, attrs: {} as UserAttributes }))
+                        )
+                    )
+                ).subscribe({
+                    next: (roleAttrsList) => {
+                        roleAttrsList.forEach(({ name, attrs }: { name: string; attrs: UserAttributes }) => {
+                            attrsByRole[name] = attrs;
+                        });
+                        this.rolePermissionMap.set(attrsByRole);
+                        this.isLoading.set(false);
+                    },
+                    error: (err) => {
+                        console.error(err);
+                        this.rolePermissionMap.set(attrsByRole);
+                        this.snackBar.open('Failed to load role attributes for permission matrix.', 'Close', { duration: 3000 });
+                        this.isLoading.set(false);
+                    },
+                });
+            },
+            error: (err) => {
+                console.error(err);
+                this.snackBar.open('Failed to load access control mapping grid.', 'Close', { duration: 3000 });
+                this.isLoading.set(false);
+            }
+        });
+    }
+
+    private getRoleAttrs(roleName: string): UserAttributes {
+        return this.rolePermissionMap()[roleName] || {};
+    }
+
+    private setLocalRoleAttr(roleName: string, attributes: UserAttributes): void {
+        this.rolePermissionMap.update((current) => ({
+            ...current,
+            [roleName]: attributes,
+        }));
+    }
+
+    isClusterScreenPermissionMapped(roleName: string | null | undefined, group: GroupedScreen): boolean {
+        try {
+            const attributes = this.getRoleAttrs(roleName || '');
+            return isScreenPermissionGranted(attributes, group.cleanScreenId)
+                || group.screenIds.some((screenId) => isScreenPermissionGranted(attributes, screenId));
+        } catch (err) {
+            console.error('Screen permission check failed', err);
+            return false;
+        }
+    }
+
+    isClusterComponentPermissionMapped(roleName: string | null | undefined, group: GroupedScreen, componentId: String | null | undefined): boolean {
+        try {
+            if (!this.isClusterScreenPermissionMapped(roleName, group)) {
+                return false;
+            }
+            const attributes = this.getRoleAttrs(roleName || '');
+            const cId = componentId ? String(componentId) : '';
+            return isComponentPermissionGranted(attributes, cId, group.cleanScreenId)
+                || group.screenIds.some((screenId) => isComponentPermissionGranted(attributes, cId, screenId));
+        } catch (err) {
+            console.error('Component permission check failed', err);
+            return false;
+        }
+    }
+
+    toggleScreenPermission(roleName: string | null | undefined, group: GroupedScreen): void {
+        const rName = roleName || '';
+        const sId = String(group.screen.screenId || '');
+        if (!rName || !sId || this.isUiLocked()) {
+            return;
+        }
+
+        const currentlyGranted = this.isClusterScreenPermissionMapped(rName, group);
+
+        this.executeToggleScreenPermission(rName, group, currentlyGranted);
+    }
+
+    private executeToggleScreenPermission(rName: string, group: GroupedScreen, currentlyGranted: boolean): void {
+        const sId = String(group.screen.screenId || '');
+        const toggleKey = this.getScreenToggleKey(rName, sId);
+        this.isProcessingToggle.update((v) => ({ ...v, [toggleKey]: true }));
+
+        const componentIds = filterEssentialComponentIds(
+            group.components.map((c) => String(c.componentId || '')).filter(Boolean)
+        );
+
+        const currentAttributes = this.getRoleAttrs(rName);
+        const updatedAttributes = currentlyGranted
+            ? revokeScreenGrant(currentAttributes, group.screenIds, componentIds)
+            : { ...currentAttributes };
+        if (!currentlyGranted) {
+            const existingScreenValues = Array.isArray(updatedAttributes[sId]) ? updatedAttributes[sId] : [];
+            const existingScreens = Array.isArray(updatedAttributes['screens']) ? updatedAttributes['screens'] : [];
+            updatedAttributes[sId] = Array.from(
+                new Set([...existingScreenValues, 'true', ...componentIds])
+            );
+            updatedAttributes['screens'] = Array.from(new Set([...existingScreens, sId]));
+            componentIds.forEach((id) => {
+                if (id) {
+                    updatedAttributes[id] = ['true'];
+                }
+            });
+        }
+
+        this.keycloakAdminService.setRoleScreenPermission(rName, sId, !currentlyGranted, componentIds, false, group.screenIds).pipe(
+            finalize(() => {
+                this.isProcessingToggle.update((v) => ({ ...v, [toggleKey]: false }));
+            })
+        ).subscribe({
+            next: (result) => {
+                const synced = result?.synced ?? 0;
+                const failed = result?.failed ?? 0;
+                const total = result?.total ?? 0;
+                // Change the controlled toggle only after Keycloak confirms the update.
+                this.setLocalRoleAttr(rName, updatedAttributes);
+                if (!currentlyGranted) {
+                    this.snackBar.open(`Screen access granted for ${this.formatRoleName(rName)}.`, 'Close', { duration: 2000 });
+                    playPermissionGrantSound();
+                } else {
+                    this.snackBar.open(`Screen access revoked for ${this.formatRoleName(rName)}.`, 'Close', { duration: 2000 });
+                    playPermissionRevokeSound();
+                }
+                if (total > 0 && failed > 0) {
+                    this.snackBar.open(
+                        `Synced ${synced}/${total} users (${failed} failed).`,
+                        'Close',
+                        { duration: 4000 }
+                    );
+                }
+                this.refreshRoleAttributes(rName);
+                this.syncRoleHoldersInBackground(rName);
+            },
+            error: (err) => {
+                console.error(err);
+                this.snackBar.open('Failed to update screen permission on role.', 'Close', { duration: 3000 });
+            },
+        });
+    }
+
+    togglePermission(
+        roleName: string | null | undefined,
+        componentId: String | null | undefined,
+        group: GroupedScreen
+    ): void {
+        const rName = roleName || '';
+        const cId = componentId ? String(componentId) : '';
+        const sId = String(group.screen.screenId || '');
+        if (!rName || !cId || this.isUiLocked()) {
+            return;
+        }
+
+        const currentlyGranted = this.isClusterComponentPermissionMapped(rName, group, cId);
+
+        if (!currentlyGranted && !this.isClusterScreenPermissionMapped(rName, group)) {
+            this.snackBar.open('Cannot grant component access. Please enable screen access first.', 'Close', {
+                duration: 3000,
+            });
+            return;
+        }
+
+        this.executeTogglePermission(rName, cId, sId, group.screenIds, currentlyGranted);
+    }
+
+    private executeTogglePermission(
+        rName: string,
+        cId: string,
+        sId: string,
+        relatedScreenIds: string[],
+        currentlyGranted: boolean
+    ): void {
+        const toggleKey = this.getComponentToggleKey(rName, cId);
+        this.isProcessingToggle.update((v) => ({ ...v, [toggleKey]: true }));
+
+        const updatedAttributes = { ...this.getRoleAttrs(rName) };
+        if (currentlyGranted) {
+            delete updatedAttributes[cId];
+            relatedScreenIds.forEach((screenId) => {
+                if (updatedAttributes[screenId]) {
+                    updatedAttributes[screenId] = (updatedAttributes[screenId] || []).filter((entry) => entry !== cId);
+                    if (updatedAttributes[screenId].length === 0) delete updatedAttributes[screenId];
+                }
+            });
+        } else {
+            updatedAttributes[cId] = ['true'];
+            if (sId) {
+                const existing = updatedAttributes[sId] || [];
+                updatedAttributes[sId] = Array.from(
+                    new Set([...(existing.includes('true') ? ['true'] : []), ...existing.filter((v) => v !== 'true'), cId])
+                );
+            }
+        }
+
+        this.keycloakAdminService.setRoleComponentPermission(rName, cId, sId, !currentlyGranted, false, relatedScreenIds).pipe(
+            finalize(() => {
+                this.isProcessingToggle.update((v) => ({ ...v, [toggleKey]: false }));
+            })
+        ).subscribe({
+            next: (result) => {
+                const synced = result?.synced ?? 0;
+                const failed = result?.failed ?? 0;
+                const total = result?.total ?? 0;
+                // Change the controlled toggle only after Keycloak confirms the update.
+                this.setLocalRoleAttr(rName, updatedAttributes);
+                if (!currentlyGranted) {
+                    this.snackBar.open(`Access granted for ${this.formatRoleName(rName)}.`, 'Close', { duration: 2000 });
+                    playPermissionGrantSound();
+                } else {
+                    this.snackBar.open(`Access revoked for ${this.formatRoleName(rName)}.`, 'Close', { duration: 2000 });
+                    playPermissionRevokeSound();
+                }
+                if (total > 0 && failed > 0) {
+                    this.snackBar.open(
+                        `Synced ${synced}/${total} users (${failed} failed).`,
+                        'Close',
+                        { duration: 4000 }
+                    );
+                }
+                this.refreshRoleAttributes(rName);
+                this.syncRoleHoldersInBackground(rName);
+            },
+            error: (err) => {
+                console.error(err);
+                this.snackBar.open('Failed to update component permission on role.', 'Close', { duration: 3000 });
+            },
+        });
+    }
+
+    private refreshRoleAttributes(roleName: string): void {
+        // Own role attributes only. The parent-role union would paint a revoked
+        // screen back on after Keycloak has already saved the revoke.
+        this.keycloakAdminService.getRealmRoleByName(roleName).subscribe({
+            next: (role) => this.setLocalRoleAttr(roleName, normalizeUserAttributes(role?.attributes || {})),
+            error: (err) => console.error(`Failed to refresh attributes for ${roleName}`, err),
+        });
+    }
+
+    private syncRoleHoldersInBackground(roleName: string): void {
+        this.keycloakAdminService.syncAllRoleHoldersPermissions(roleName).subscribe({
+            next: ({ synced, failed, total }) => {
+                if (total > 0 && failed > 0) {
+                    this.snackBar.open(
+                        `Permission sync completed for ${synced}/${total} users (${failed} failed).`,
+                        'Close',
+                        { duration: 4000 }
+                    );
+                }
+            },
+            error: (err) => {
+                console.error(`Failed to sync role holders for ${roleName}:`, err);
+                this.snackBar.open(
+                    `Permission saved, but background user sync failed for ${this.formatRoleName(roleName)}.`,
+                    'Close',
+                    { duration: 4000 }
+                );
+            },
+        });
+    }
+
+    /**
+     * Enable host + embeds with non-sensitive buttons only.
+     * Delete / approve / reject / finalize stay off until toggled explicitly.
+     */
+    grantPageEssentials(roleName: string | null | undefined, page: MatrixPageGroup): void {
+        const rName = roleName || '';
+        if (!rName || this.isUiLocked()) {
+            return;
+        }
+        const groups = [page.host, ...page.embeds];
+        const toGrant = groups.filter((group) => !this.isClusterScreenPermissionMapped(rName, group));
+        if (toGrant.length === 0) {
+            this.snackBar.open(
+                'Page essentials already granted. Enable sensitive actions individually if needed.',
+                'Close',
+                { duration: 3000 }
+            );
+            return;
+        }
+        const batchKey = `page-essentials_${rName}_${page.page.hostScreenId}`;
+        this.isProcessingToggle.update((v) => ({ ...v, [batchKey]: true }));
+        from(toGrant)
+            .pipe(
+                concatMap((group) => {
+                    const sId = String(group.screen.screenId || '');
+                    const componentIds = filterEssentialComponentIds(
+                        group.components.map((c) => String(c.componentId || '')).filter(Boolean)
+                    );
+                    const currentAttributes = this.getRoleAttrs(rName);
+                    const updatedAttributes = { ...currentAttributes };
+                    const existingScreenValues = Array.isArray(updatedAttributes[sId])
+                        ? updatedAttributes[sId]
+                        : [];
+                    const existingScreens = Array.isArray(updatedAttributes['screens'])
+                        ? updatedAttributes['screens']
+                        : [];
+                    updatedAttributes[sId] = Array.from(
+                        new Set([...existingScreenValues, 'true', ...componentIds])
+                    );
+                    updatedAttributes['screens'] = Array.from(new Set([...existingScreens, sId]));
+                    componentIds.forEach((id) => {
+                        updatedAttributes[id] = ['true'];
+                    });
+                    return this.keycloakAdminService
+                        .setRoleScreenPermission(rName, sId, true, componentIds, false, group.screenIds)
+                        .pipe(
+                            map(() => {
+                                this.setLocalRoleAttr(rName, updatedAttributes);
+                                return sId;
+                            })
+                        );
+                }),
+                toArray(),
+                finalize(() => {
+                    this.isProcessingToggle.update((v) => ({ ...v, [batchKey]: false }));
+                })
+            )
+            .subscribe({
+                next: (granted) => {
+                    this.snackBar.open(
+                        `Granted page essentials for ${this.formatRoleName(rName)} (${granted.length} screen${granted.length === 1 ? '' : 's'}; sensitive actions excluded).`,
+                        'Close',
+                        { duration: 3500 }
+                    );
+                    playPermissionGrantSound();
+                    this.refreshRoleAttributes(rName);
+                    this.syncRoleHoldersInBackground(rName);
+                },
+                error: (err) => {
+                    console.error(err);
+                    this.snackBar.open('Failed to grant page essentials.', 'Close', { duration: 3000 });
+                    this.refreshRoleAttributes(rName);
+                },
+            });
+    }
+
+}