@xeplr/ui-account 1.0.0

package/src/designs/theme.css

@@ -0,0 +1,231 @@
+/*
+ * xeplr Theme System
+ *
+ * Usage:
+ *   1. Wrap your app in <ThemeProvider> (or just add a class to a container)
+ *   2. Apply class: <div class="xeplr-theme-dark"> ... </div>
+ *   3. All xeplr-ui-* components inside will pick up the theme
+ *
+ * Extending:
+ *   Define your own theme by creating a class with the same variables:
+ *
+ *     .xeplr-theme-corporate {
+ *       --xeplr-bg-primary: #f8f9fa;
+ *       --xeplr-bg-secondary: #ffffff;
+ *       ... etc
+ *     }
+ *
+ *   Then use <ThemeProvider theme="corporate"> or class="xeplr-theme-corporate"
+ */
+
+/* ─── Dark ─── */
+.xeplr-theme-dark {
+  /* Backgrounds */
+  --xeplr-bg-primary: #1a1a1a;
+  --xeplr-bg-secondary: #222222;
+  --xeplr-bg-tertiary: #2a2a2a;
+  --xeplr-bg-hover: #2a2a2a;
+  --xeplr-bg-active: #1a1a2a;
+  --xeplr-bg-overlay: rgba(0, 0, 0, 0.5);
+
+  /* Text */
+  --xeplr-text-primary: #e0e0e0;
+  --xeplr-text-secondary: #aaaaaa;
+  --xeplr-text-muted: #777777;
+  --xeplr-text-disabled: #555555;
+
+  /* Borders */
+  --xeplr-border-primary: #333333;
+  --xeplr-border-secondary: #2a2a2a;
+  --xeplr-border-focus: #646cff;
+
+  /* Accent */
+  --xeplr-accent: #646cff;
+  --xeplr-accent-hover: #535bf2;
+  --xeplr-accent-text: #ffffff;
+  --xeplr-accent-muted: #4a4a8a;
+
+  /* Semantic */
+  --xeplr-success: #6bcc6b;
+  --xeplr-success-bg: #1a2a1a;
+  --xeplr-success-border: #4aaf4a;
+  --xeplr-danger: #ff6b6b;
+  --xeplr-danger-bg: #3d1111;
+  --xeplr-danger-border: #5a1a1a;
+  --xeplr-warning: #ffaa33;
+  --xeplr-warning-bg: #2a2200;
+  --xeplr-info: #6db3ff;
+  --xeplr-info-bg: #1a2233;
+  --xeplr-info-border: #4a9eff;
+
+  /* Inputs */
+  --xeplr-input-bg: #2a2a2a;
+  --xeplr-input-border: #444444;
+  --xeplr-input-text: #e0e0e0;
+  --xeplr-input-placeholder: #666666;
+
+  /* Tags / Badges */
+  --xeplr-tag-bg: #2a2a3a;
+  --xeplr-tag-border: #3a3a5a;
+  --xeplr-tag-text: #9999cc;
+  --xeplr-badge-bg: #2a2a2a;
+  --xeplr-badge-text: #666666;
+
+  /* Shadows */
+  --xeplr-shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.3);
+  --xeplr-shadow-md: 0 4px 12px rgba(0, 0, 0, 0.4);
+  --xeplr-shadow-lg: 0 8px 24px rgba(0, 0, 0, 0.5);
+}
+
+/* ─── Light ─── */
+.xeplr-theme-light {
+  --xeplr-bg-primary: #fafafa;
+  --xeplr-bg-secondary: #f5f5f5;
+  --xeplr-bg-tertiary: #ffffff;
+  --xeplr-bg-hover: #f0f0f0;
+  --xeplr-bg-active: #f0f0ff;
+  --xeplr-bg-overlay: rgba(0, 0, 0, 0.15);
+
+  --xeplr-text-primary: #333333;
+  --xeplr-text-secondary: #666666;
+  --xeplr-text-muted: #999999;
+  --xeplr-text-disabled: #cccccc;
+
+  --xeplr-border-primary: #dddddd;
+  --xeplr-border-secondary: #eeeeee;
+  --xeplr-border-focus: #646cff;
+
+  --xeplr-accent: #646cff;
+  --xeplr-accent-hover: #535bf2;
+  --xeplr-accent-text: #ffffff;
+  --xeplr-accent-muted: #b0b0e0;
+
+  --xeplr-success: #2d7d2d;
+  --xeplr-success-bg: #e8f5e8;
+  --xeplr-success-border: #3d9e3d;
+  --xeplr-danger: #cc0000;
+  --xeplr-danger-bg: #ffe0e0;
+  --xeplr-danger-border: #f5c6c6;
+  --xeplr-warning: #e67e00;
+  --xeplr-warning-bg: #fff3e0;
+  --xeplr-info: #2a6cb5;
+  --xeplr-info-bg: #e8f0ff;
+  --xeplr-info-border: #3b8bdb;
+
+  --xeplr-input-bg: #ffffff;
+  --xeplr-input-border: #cccccc;
+  --xeplr-input-text: #333333;
+  --xeplr-input-placeholder: #aaaaaa;
+
+  --xeplr-tag-bg: #eeeeff;
+  --xeplr-tag-border: #ddddee;
+  --xeplr-tag-text: #5555cc;
+  --xeplr-badge-bg: #eeeeee;
+  --xeplr-badge-text: #888888;
+
+  --xeplr-shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.06);
+  --xeplr-shadow-md: 0 4px 12px rgba(0, 0, 0, 0.08);
+  --xeplr-shadow-lg: 0 8px 24px rgba(0, 0, 0, 0.12);
+}
+
+/* ─── Medium (balanced gray) ─── */
+.xeplr-theme-medium {
+  --xeplr-bg-primary: #2c2c2e;
+  --xeplr-bg-secondary: #3a3a3c;
+  --xeplr-bg-tertiary: #48484a;
+  --xeplr-bg-hover: #3a3a3c;
+  --xeplr-bg-active: #2c2c3e;
+  --xeplr-bg-overlay: rgba(0, 0, 0, 0.35);
+
+  --xeplr-text-primary: #e5e5e7;
+  --xeplr-text-secondary: #b0b0b2;
+  --xeplr-text-muted: #8e8e93;
+  --xeplr-text-disabled: #636366;
+
+  --xeplr-border-primary: #48484a;
+  --xeplr-border-secondary: #3a3a3c;
+  --xeplr-border-focus: #7b7fff;
+
+  --xeplr-accent: #7b7fff;
+  --xeplr-accent-hover: #6a6ef0;
+  --xeplr-accent-text: #ffffff;
+  --xeplr-accent-muted: #5a5a9a;
+
+  --xeplr-success: #7cd87c;
+  --xeplr-success-bg: #253025;
+  --xeplr-success-border: #5aaa5a;
+  --xeplr-danger: #ff7070;
+  --xeplr-danger-bg: #402020;
+  --xeplr-danger-border: #6a2a2a;
+  --xeplr-warning: #ffbb55;
+  --xeplr-warning-bg: #352a10;
+  --xeplr-info: #7abcff;
+  --xeplr-info-bg: #202a3a;
+  --xeplr-info-border: #5aaaee;
+
+  --xeplr-input-bg: #3a3a3c;
+  --xeplr-input-border: #555558;
+  --xeplr-input-text: #e5e5e7;
+  --xeplr-input-placeholder: #777777;
+
+  --xeplr-tag-bg: #3a3a4a;
+  --xeplr-tag-border: #4a4a5a;
+  --xeplr-tag-text: #aaaadd;
+  --xeplr-badge-bg: #3a3a3c;
+  --xeplr-badge-text: #8e8e93;
+
+  --xeplr-shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.2);
+  --xeplr-shadow-md: 0 4px 12px rgba(0, 0, 0, 0.3);
+  --xeplr-shadow-lg: 0 8px 24px rgba(0, 0, 0, 0.35);
+}
+
+/* ─── Bright (vibrant, energetic) ─── */
+.xeplr-theme-bright {
+  --xeplr-bg-primary: #ffffff;
+  --xeplr-bg-secondary: #f0f2ff;
+  --xeplr-bg-tertiary: #ffffff;
+  --xeplr-bg-hover: #e8ebff;
+  --xeplr-bg-active: #e0e4ff;
+  --xeplr-bg-overlay: rgba(50, 50, 100, 0.15);
+
+  --xeplr-text-primary: #1a1a2e;
+  --xeplr-text-secondary: #444466;
+  --xeplr-text-muted: #888899;
+  --xeplr-text-disabled: #bbbbcc;
+
+  --xeplr-border-primary: #d0d4ee;
+  --xeplr-border-secondary: #e0e4f4;
+  --xeplr-border-focus: #5b5fff;
+
+  --xeplr-accent: #5b5fff;
+  --xeplr-accent-hover: #4a4ef0;
+  --xeplr-accent-text: #ffffff;
+  --xeplr-accent-muted: #c0c2f0;
+
+  --xeplr-success: #1aaa55;
+  --xeplr-success-bg: #e0fae8;
+  --xeplr-success-border: #2ecc71;
+  --xeplr-danger: #e53e3e;
+  --xeplr-danger-bg: #ffe8e8;
+  --xeplr-danger-border: #fc8181;
+  --xeplr-warning: #dd8800;
+  --xeplr-warning-bg: #fff6e0;
+  --xeplr-info: #3182ce;
+  --xeplr-info-bg: #e0efff;
+  --xeplr-info-border: #63b3ed;
+
+  --xeplr-input-bg: #ffffff;
+  --xeplr-input-border: #c0c4dd;
+  --xeplr-input-text: #1a1a2e;
+  --xeplr-input-placeholder: #999aab;
+
+  --xeplr-tag-bg: #ebebff;
+  --xeplr-tag-border: #d0d0ee;
+  --xeplr-tag-text: #5555aa;
+  --xeplr-badge-bg: #e8eaff;
+  --xeplr-badge-text: #6666aa;
+
+  --xeplr-shadow-sm: 0 1px 3px rgba(90, 90, 180, 0.08);
+  --xeplr-shadow-md: 0 4px 12px rgba(90, 90, 180, 0.1);
+  --xeplr-shadow-lg: 0 8px 24px rgba(90, 90, 180, 0.15);
+}

package/src/index.js

@@ -0,0 +1,41 @@
+// API client
+export { configure, registerUser, loginUser, activateAccount, forgotPassword, resetPassword, changePassword, getProfile, updateProfile, logoutUser, getMyTenants, authFetch } from './api.js';
+
+// Token helpers
+export { getToken, setToken, getRefreshToken, setRefreshToken, getUser, setUser, clearAuth, isAuthenticated } from './token.js';
+
+// Controller hooks
+export { useLoginController } from './useLoginController.js';
+export { useRegisterController } from './useRegisterController.js';
+export { useForgotPasswordController } from './useForgotPasswordController.js';
+export { useResetPasswordController } from './useResetPasswordController.js';
+export { useActivateController } from './useActivateController.js';
+export { useChangePasswordController } from './useChangePasswordController.js';
+export { useProfileController } from './useProfileController.js';
+export { useUserRolesController } from './useUserRolesController.js';
+export { useAccessMatrixController } from './useAccessMatrixController.js';
+export { useMasterSettingsController } from './useMasterSettingsController.js';
+export { useTenantController } from './useTenantController.js';
+export { useTenantPickerController, getActiveTenant, setActiveTenant, clearActiveTenant, hasMultipleTenants } from './useTenantPickerController.js';
+
+// Theme
+export { ThemeProvider, useTheme, useThemeStrict, BUILT_IN_THEMES, DEFAULT_THEME } from './ThemeContext.jsx';
+
+// Access control
+export { AccessProvider, useAccess, useAccessStrict } from './AccessContext.jsx';
+export { ProtectedRoute } from './ProtectedRoute.jsx';
+export { AccessGuard } from './AccessGuard.jsx';
+
+// Admin API (model layer for RBAC management)
+export { getUsers, getRoles, getAccessItems, toggleUserRole, toggleAccessRole, toggleModuleRole } from './adminApi.js';
+export { getMasterItems, saveMasterItem, deleteMasterItem, MASTER_TYPES } from './masterApi.js';
+export { getTenants, saveTenant, deleteTenant, assignUserTenant } from './adminApi.js';
+
+// Design validation (use when building custom designs)
+export { useDesignValidator, LOGIN_RULES, REGISTER_RULES, FORGOT_PASSWORD_RULES, RESET_PASSWORD_RULES, CHANGE_PASSWORD_RULES, PROFILE_RULES, USER_ROLES_MATRIX_RULES, ACCESS_MATRIX_RULES, MASTER_SETTINGS_RULES } from './validateDesign.js';
+
+// Sample designs (use as reference or starting point)
+export { LoginSample, RegisterSample, ForgotPasswordSample, ResetPasswordSample, ActivateSample, NotActivatedSample, ChangePasswordSample, ProfileSample, UserRolesMatrixSample, AccessMatrixSample, MasterSettingsSample, TenantSample } from './designs/index.js';
+
+// Ready-made pages (controller + sample design wired together)
+export { LoginPage, RegisterPage, ForgotPasswordPage, ResetPasswordPage, ActivatePage, NotActivatedPage, ChangePasswordPage, ProfilePage, UserRolesPage, AccessMatrixPage, MasterSettingsPage, TenantPage, TenantPickerPage } from './pages.jsx';

package/src/masterApi.js

@@ -0,0 +1,28 @@
+import { authFetch } from './api.js';
+
+/**
+ * Master Settings API — model layer for managing auth master data.
+ * Pure logic, no React dependency.
+ */
+
+var TYPES = ['roles', 'apis', 'pages', 'elements', 'menus'];
+
+export function getMasterItems(type) {
+  return authFetch('/auth/api/admin/master/' + type);
+}
+
+export function saveMasterItem(type, data) {
+  return authFetch('/auth/api/admin/master/' + type, {
+    method: 'POST',
+    body: JSON.stringify(data),
+  });
+}
+
+export function deleteMasterItem(type, id) {
+  return authFetch('/auth/api/admin/master/' + type + '/delete', {
+    method: 'POST',
+    body: JSON.stringify({ id }),
+  });
+}
+
+export { TYPES as MASTER_TYPES };

package/src/pages.jsx

@@ -0,0 +1,92 @@
+import { useLoginController } from './useLoginController.js';
+import { useRegisterController } from './useRegisterController.js';
+import { useForgotPasswordController } from './useForgotPasswordController.js';
+import { useResetPasswordController } from './useResetPasswordController.js';
+import { useActivateController } from './useActivateController.js';
+import { useChangePasswordController } from './useChangePasswordController.js';
+import { useProfileController } from './useProfileController.js';
+import { useUserRolesController } from './useUserRolesController.js';
+import { useAccessMatrixController } from './useAccessMatrixController.js';
+import { useMasterSettingsController } from './useMasterSettingsController.js';
+import { useTenantController } from './useTenantController.js';
+import { useTenantPickerController } from './useTenantPickerController.js';
+import { LoginSample, RegisterSample, ForgotPasswordSample, ResetPasswordSample, ActivateSample, NotActivatedSample, ChangePasswordSample, ProfileSample, UserRolesMatrixSample, AccessMatrixSample, MasterSettingsSample, TenantSample, TenantPickerSample } from './designs/index.js';
+import { useDesignValidator, LOGIN_RULES, REGISTER_RULES, FORGOT_PASSWORD_RULES, RESET_PASSWORD_RULES, CHANGE_PASSWORD_RULES, PROFILE_RULES, USER_ROLES_MATRIX_RULES, ACCESS_MATRIX_RULES, MASTER_SETTINGS_RULES } from './validateDesign.js';
+
+/**
+ * Ready-made pages using sample designs.
+ * Use these for quick setup, or build your own with the controllers + your own designs.
+ */
+
+export function LoginPage(props) {
+  var controller = useLoginController(props);
+  var ref = useDesignValidator('LoginPage', LOGIN_RULES);
+  return <div ref={ref}><LoginSample {...controller} /></div>;
+}
+
+export function RegisterPage(props) {
+  var controller = useRegisterController(props);
+  var ref = useDesignValidator('RegisterPage', REGISTER_RULES);
+  return <div ref={ref}><RegisterSample {...controller} /></div>;
+}
+
+export function ForgotPasswordPage() {
+  var controller = useForgotPasswordController();
+  var ref = useDesignValidator('ForgotPasswordPage', FORGOT_PASSWORD_RULES);
+  return <div ref={ref}><ForgotPasswordSample {...controller} /></div>;
+}
+
+export function ResetPasswordPage() {
+  var controller = useResetPasswordController();
+  var ref = useDesignValidator('ResetPasswordPage', RESET_PASSWORD_RULES);
+  return <div ref={ref}><ResetPasswordSample {...controller} /></div>;
+}
+
+export function ActivatePage() {
+  var controller = useActivateController();
+  return <ActivateSample {...controller} />;
+}
+
+export function NotActivatedPage() {
+  return <NotActivatedSample />;
+}
+
+export function ChangePasswordPage(props) {
+  var controller = useChangePasswordController(props);
+  var ref = useDesignValidator('ChangePasswordPage', CHANGE_PASSWORD_RULES);
+  return <div ref={ref}><ChangePasswordSample {...controller} /></div>;
+}
+
+export function ProfilePage(props) {
+  var controller = useProfileController(props);
+  var ref = useDesignValidator('ProfilePage', PROFILE_RULES);
+  return <div ref={ref}><ProfileSample {...controller} /></div>;
+}
+
+export function UserRolesPage(props) {
+  var controller = useUserRolesController(props);
+  var ref = useDesignValidator('UserRolesPage', USER_ROLES_MATRIX_RULES);
+  return <div ref={ref}><UserRolesMatrixSample {...controller} /></div>;
+}
+
+export function AccessMatrixPage(props) {
+  var controller = useAccessMatrixController(props);
+  var ref = useDesignValidator('AccessMatrixPage', ACCESS_MATRIX_RULES);
+  return <div ref={ref}><AccessMatrixSample {...controller} /></div>;
+}
+
+export function MasterSettingsPage(props) {
+  var controller = useMasterSettingsController(props);
+  var ref = useDesignValidator('MasterSettingsPage', MASTER_SETTINGS_RULES);
+  return <div ref={ref}><MasterSettingsSample {...controller} /></div>;
+}
+
+export function TenantPage(props) {
+  var controller = useTenantController(props);
+  return <TenantSample {...controller} />;
+}
+
+export function TenantPickerPage(props) {
+  var controller = useTenantPickerController(props);
+  return <TenantPickerSample {...controller} />;
+}

package/src/token.js

@@ -0,0 +1,38 @@
+const TOKEN_KEY = 'accessToken';
+const REFRESH_TOKEN_KEY = 'refreshToken';
+const USER_KEY = 'user';
+
+export function getToken() {
+  return localStorage.getItem(TOKEN_KEY);
+}
+
+export function setToken(token) {
+  localStorage.setItem(TOKEN_KEY, token);
+}
+
+export function getRefreshToken() {
+  return localStorage.getItem(REFRESH_TOKEN_KEY);
+}
+
+export function setRefreshToken(token) {
+  localStorage.setItem(REFRESH_TOKEN_KEY, token);
+}
+
+export function getUser() {
+  const raw = localStorage.getItem(USER_KEY);
+  return raw ? JSON.parse(raw) : null;
+}
+
+export function setUser(user) {
+  localStorage.setItem(USER_KEY, JSON.stringify(user));
+}
+
+export function clearAuth() {
+  localStorage.removeItem(TOKEN_KEY);
+  localStorage.removeItem(REFRESH_TOKEN_KEY);
+  localStorage.removeItem(USER_KEY);
+}
+
+export function isAuthenticated() {
+  return !!getToken();
+}

package/src/useAccessMatrixController.js

@@ -0,0 +1,244 @@
+import { useState, useEffect, useMemo, useCallback } from 'react';
+import { getRoles, getAccessItems, toggleModuleRole, toggleAccessRole } from './adminApi.js';
+
+var GROUP_FIELDS = {
+  apis: 'apiGroup',
+  pages: 'uiPagesGroup',
+  elements: 'uiElementsGroup',
+  menus: 'menuGroup',
+};
+
+var TYPES = ['apis', 'pages', 'elements', 'menus'];
+
+var ACTION_ORDER = { view: 0, edit: 1, delete: 2 };
+
+function parseModuleGroup(groupValue) {
+  if (!groupValue) return null;
+  var parts = groupValue.split(':');
+  if (parts.length !== 2 || !parts[0] || !parts[1]) return null;
+  return { module: parts[0], action: parts[1] };
+}
+
+export function useAccessMatrixController() {
+  var [roles, setRoles] = useState([]);
+  var [rawItems, setRawItems] = useState({ apis: [], pages: [], elements: [], menus: [] });
+  var [activeView, setActiveView] = useState('modules');
+  var [search, setSearch] = useState('');
+  var [uncatSubTab, setUncatSubTab] = useState('apis');
+  var [loading, setLoading] = useState(true);
+  var [error, setError] = useState('');
+  var [saving, setSaving] = useState({});
+
+  useEffect(function() {
+    loadData();
+  }, []);
+
+  async function loadData() {
+    setLoading(true);
+    setError('');
+    try {
+      var [rolesData, itemsData] = await Promise.all([getRoles(), getAccessItems()]);
+      setRoles(rolesData.filter(function(r) { return r.name !== 'Super Admin'; }));
+      setRawItems(itemsData);
+    } catch (err) {
+      setError(err.message);
+    } finally {
+      setLoading(false);
+    }
+  }
+
+  // ─── Modules view: aggregate items into module > action > roles ───
+  var modules = useMemo(function() {
+    var moduleMap = {};
+
+    TYPES.forEach(function(type) {
+      var items = rawItems[type] || [];
+      var groupField = GROUP_FIELDS[type];
+
+      items.forEach(function(item) {
+        var parsed = parseModuleGroup(item[groupField]);
+        if (!parsed) return;
+
+        var key = parsed.module;
+        if (!moduleMap[key]) moduleMap[key] = {};
+        if (!moduleMap[key][parsed.action]) {
+          moduleMap[key][parsed.action] = { items: [], roleIds: {} };
+        }
+
+        var entry = moduleMap[key][parsed.action];
+        entry.items.push({ type: type, item: item });
+
+        // Track which roles have ALL items in this group assigned
+        var itemRoleIds = (item.roles || []).map(function(r) { return r.id; });
+        roles.forEach(function(role) {
+          if (entry.roleIds[role.id] === undefined) entry.roleIds[role.id] = { total: 0, assigned: 0 };
+          entry.roleIds[role.id].total++;
+          if (itemRoleIds.indexOf(role.id) !== -1) entry.roleIds[role.id].assigned++;
+        });
+      });
+    });
+
+    // Convert to sorted array
+    var q = search.toLowerCase();
+    var result = Object.keys(moduleMap).sort().filter(function(name) {
+      return !q || name.toLowerCase().includes(q);
+    }).map(function(name) {
+      var actions = Object.keys(moduleMap[name]).sort(function(a, b) {
+        var oa = ACTION_ORDER[a] !== undefined ? ACTION_ORDER[a] : 99;
+        var ob = ACTION_ORDER[b] !== undefined ? ACTION_ORDER[b] : 99;
+        return oa - ob;
+      }).map(function(action) {
+        var data = moduleMap[name][action];
+        return {
+          action: action,
+          itemCount: data.items.length,
+          items: data.items,
+          getRoleState: function(roleId) {
+            var info = data.roleIds[roleId];
+            if (!info || info.total === 0) return 'none';
+            if (info.assigned === info.total) return 'all';
+            if (info.assigned > 0) return 'partial';
+            return 'none';
+          }
+        };
+      });
+
+      return { name: name, actions: actions };
+    });
+
+    return result;
+  }, [rawItems, roles, search]);
+
+  // ─── Uncategorized view: items without module:action group ───
+  var uncategorized = useMemo(function() {
+    var result = {};
+    var q = search.toLowerCase();
+
+    TYPES.forEach(function(type) {
+      var items = rawItems[type] || [];
+      var groupField = GROUP_FIELDS[type];
+
+      result[type] = items.filter(function(item) {
+        var parsed = parseModuleGroup(item[groupField]);
+        if (parsed) return false; // categorized, skip
+        var matchesSearch = !q || (item.name && item.name.toLowerCase().includes(q));
+        return matchesSearch;
+      });
+    });
+
+    return result;
+  }, [rawItems, search]);
+
+  var uncategorizedCount = useMemo(function() {
+    var count = 0;
+    TYPES.forEach(function(type) { count += (uncategorized[type] || []).length; });
+    return count;
+  }, [uncategorized]);
+
+  // ─── Module toggle (bulk) ───
+  var handleModuleToggle = useCallback(async function(moduleName, action, roleId, currentState) {
+    var assign = currentState !== 'all';
+    var key = 'module:' + moduleName + ':' + action + ':' + roleId;
+    setSaving(function(prev) { var next = { ...prev }; next[key] = true; return next; });
+
+    try {
+      await toggleModuleRole({ module: moduleName, action: action, roleId: roleId, assign: assign });
+
+      // Optimistic: update local state
+      setRawItems(function(prev) {
+        var updated = {};
+        TYPES.forEach(function(type) {
+          var groupField = GROUP_FIELDS[type];
+          updated[type] = prev[type].map(function(item) {
+            var parsed = parseModuleGroup(item[groupField]);
+            if (!parsed || parsed.module !== moduleName || parsed.action !== action) return item;
+
+            var newRoles;
+            if (assign) {
+              var hasRole = item.roles && item.roles.some(function(r) { return r.id === roleId; });
+              if (hasRole) return item;
+              var role = roles.find(function(r) { return r.id === roleId; });
+              newRoles = (item.roles || []).concat(role ? [role] : []);
+            } else {
+              newRoles = (item.roles || []).filter(function(r) { return r.id !== roleId; });
+            }
+            return { ...item, roles: newRoles };
+          });
+        });
+        return updated;
+      });
+    } catch (err) {
+      setError(err.message);
+    } finally {
+      setSaving(function(prev) { var next = { ...prev }; delete next[key]; return next; });
+    }
+  }, [roles]);
+
+  // ─── Single item toggle (for uncategorized) ───
+  var handleItemToggle = useCallback(async function(type, itemId, roleId, currentlyAssigned) {
+    var key = 'item:' + type + ':' + itemId + ':' + roleId;
+    setSaving(function(prev) { var next = { ...prev }; next[key] = true; return next; });
+
+    try {
+      await toggleAccessRole({ type: type, itemId: itemId, roleId: roleId, assign: !currentlyAssigned });
+
+      setRawItems(function(prev) {
+        var updated = { ...prev };
+        updated[type] = prev[type].map(function(item) {
+          if (item.id !== itemId) return item;
+          var newRoles;
+          if (currentlyAssigned) {
+            newRoles = item.roles.filter(function(r) { return r.id !== roleId; });
+          } else {
+            var role = roles.find(function(r) { return r.id === roleId; });
+            newRoles = item.roles.concat(role ? [role] : []);
+          }
+          return { ...item, roles: newRoles };
+        });
+        return updated;
+      });
+    } catch (err) {
+      setError(err.message);
+    } finally {
+      setSaving(function(prev) { var next = { ...prev }; delete next[key]; return next; });
+    }
+  }, [roles]);
+
+  function isItemAssigned(item, roleId) {
+    return item.roles && item.roles.some(function(r) { return r.id === roleId; });
+  }
+
+  function isModuleSaving(moduleName, action, roleId) {
+    return !!saving['module:' + moduleName + ':' + action + ':' + roleId];
+  }
+
+  function isItemSaving(type, itemId, roleId) {
+    return !!saving['item:' + type + ':' + itemId + ':' + roleId];
+  }
+
+  var handleViewChange = useCallback(function(view) {
+    setActiveView(view);
+    setSearch('');
+  }, []);
+
+  return {
+    roles,
+    modules,
+    uncategorized,
+    uncategorizedCount,
+    uncatSubTab,
+    setUncatSubTab,
+    activeView,
+    setActiveView: handleViewChange,
+    search,
+    setSearch,
+    loading,
+    error,
+    handleModuleToggle,
+    handleItemToggle,
+    isItemAssigned,
+    isModuleSaving,
+    isItemSaving,
+    reload: loadData,
+  };
+}