@xeplr/ui-account 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Xeplr
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@xeplr/ui-account",
+  "version": "1.0.0",
+  "description": "Account UI: auth, profile, RBAC admin, tenant management — React controller hooks and designs",
+  "type": "module",
+  "main": "src/index.js",
+  "files": ["src/"],
+  "keywords": ["auth", "account", "profile", "react", "hooks", "login", "register", "rbac", "multi-tenancy"],
+  "author": "xeplr",
+  "license": "MIT",
+  "repository": { "type": "git", "url": "https://github.com/Xeplr/xeplr-ui-account" },
+  "publishConfig": { "access": "public" },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0",
+    "react-router-dom": "^6.0.0 || ^7.0.0"
+  }
+}

package/src/AccessContext.jsx

@@ -0,0 +1,125 @@
+import { createContext, useContext, useState, useEffect } from 'react';
+import { getToken, getUser } from './token.js';
+import { logoutUser } from './api.js';
+
+const AccessContext = createContext(null);
+
+/**
+ * AccessProvider — wraps your app to provide access state.
+ *
+ * On mount, loads access from localStorage (set during login).
+ * Provides helpers: hasPage, hasApi, hasMenu, hasElement, hasRole.
+ *
+ * Usage:
+ *   <AccessProvider>
+ *     <App />
+ *   </AccessProvider>
+ */
+export function AccessProvider({ children }) {
+  const [access, setAccessState] = useState(() => {
+    const raw = localStorage.getItem('access');
+    return raw ? JSON.parse(raw) : null;
+  });
+
+  const [user, setUserState] = useState(() => getUser());
+  const [authenticated, setAuthenticated] = useState(() => !!getToken());
+
+  function setAccess(accessObj) {
+    if (accessObj) {
+      localStorage.setItem('access', JSON.stringify(accessObj));
+    } else {
+      localStorage.removeItem('access');
+    }
+    setAccessState(accessObj);
+  }
+
+  function setUser(userObj) {
+    if (userObj) {
+      localStorage.setItem('user', JSON.stringify(userObj));
+    } else {
+      localStorage.removeItem('user');
+    }
+    setUserState(userObj);
+  }
+
+  function logout() {
+    logoutUser(); // clears localStorage + best-effort server-side cleanup
+    localStorage.removeItem('access');
+    setAccessState(null);
+    setUserState(null);
+    setAuthenticated(false);
+  }
+
+  function onLogin(result) {
+    // result = { accessToken, refreshToken, user, access } from login API
+    setAuthenticated(true);
+    setUser(result.user);
+    setAccess(result.access);
+  }
+
+  // Access checkers
+  function hasPage(pageName) {
+    if (!access) return false;
+    return access.pages && access.pages.includes(pageName);
+  }
+
+  function hasApi(apiName) {
+    if (!access) return false;
+    return access.apis && access.apis.includes(apiName);
+  }
+
+  function hasMenu(menuName) {
+    if (!access) return false;
+    return access.menus && access.menus.includes(menuName);
+  }
+
+  function hasElement(elementName) {
+    if (!access) return false;
+    return access.elements && access.elements.includes(elementName);
+  }
+
+  function hasRole(roleName) {
+    if (!access) return false;
+    return access.roles && access.roles.includes(roleName);
+  }
+
+  const value = {
+    user,
+    access,
+    authenticated,
+    onLogin,
+    logout,
+    setAccess,
+    hasPage,
+    hasApi,
+    hasMenu,
+    hasElement,
+    hasRole
+  };
+
+  return (
+    <AccessContext.Provider value={value}>
+      {children}
+    </AccessContext.Provider>
+  );
+}
+
+/**
+ * Hook to access the auth/access context.
+ * Returns null if no AccessProvider is present (safe to call unconditionally).
+ */
+export function useAccess() {
+  return useContext(AccessContext);
+}
+
+/**
+ * Strict version — throws if no AccessProvider.
+ * Use in components that require access control (ProtectedRoute, AccessGuard).
+ */
+export function useAccessStrict() {
+  const ctx = useContext(AccessContext);
+  if (!ctx) {
+    throw new Error('useAccessStrict must be used within an <AccessProvider>');
+  }
+  return ctx;
+}

package/src/AccessGuard.jsx

@@ -0,0 +1,35 @@
+import { useAccessStrict } from './AccessContext.jsx';
+
+/**
+ * AccessGuard — conditionally renders children based on access.
+ *
+ * Props:
+ *   element  - element name to check (from uiElements table)
+ *   menu     - menu name to check (from menus table)
+ *   page     - page name to check (from uiPages table)
+ *   role     - role name to check
+ *   fallback - what to render if no access (default: null)
+ *
+ * Usage:
+ *   <AccessGuard element="btn-delete-user">
+ *     <button onClick={handleDelete}>Delete User</button>
+ *   </AccessGuard>
+ *
+ *   <AccessGuard menu="admin-nav">
+ *     <AdminNavigation />
+ *   </AccessGuard>
+ *
+ *   <AccessGuard role="admin" fallback={<span>No access</span>}>
+ *     <AdminTools />
+ *   </AccessGuard>
+ */
+export function AccessGuard({ children, element, menu, page, role, fallback = null }) {
+  const { hasElement, hasMenu, hasPage, hasRole } = useAccessStrict();
+
+  if (element && !hasElement(element)) return fallback;
+  if (menu && !hasMenu(menu)) return fallback;
+  if (page && !hasPage(page)) return fallback;
+  if (role && !hasRole(role)) return fallback;
+
+  return children;
+}

package/src/ProtectedRoute.jsx

@@ -0,0 +1,55 @@
+import { Navigate } from 'react-router-dom';
+import { useAccessStrict } from './AccessContext.jsx';
+
+/**
+ * ProtectedRoute — guards a route based on auth and access.
+ *
+ * Props:
+ *   page        - page name to check (from uiPages table). Optional.
+ *   roles       - array of role names, user must have at least one. Optional.
+ *   loginPath   - redirect path if not authenticated (default: /auth/login)
+ *   deniedPath  - redirect path if no access (default: /auth/login)
+ *   children    - the page component to render
+ *
+ * Behavior:
+ *   - No token → redirect to loginPath
+ *   - page prop set + user doesn't have that page → redirect to deniedPath
+ *   - roles prop set + user doesn't have any of those roles → redirect to deniedPath
+ *   - Otherwise → render children
+ *
+ * Usage:
+ *   // Any authenticated user
+ *   <ProtectedRoute><Dashboard /></ProtectedRoute>
+ *
+ *   // Must have access to this page (DB-driven)
+ *   <ProtectedRoute page="/dashboard"><Dashboard /></ProtectedRoute>
+ *
+ *   // Must have admin role
+ *   <ProtectedRoute roles={['admin']}><AdminPanel /></ProtectedRoute>
+ */
+export function ProtectedRoute({
+  children,
+  page,
+  roles,
+  loginPath = '/auth/login',
+  deniedPath = '/auth/login'
+}) {
+  const { authenticated, hasPage, hasRole } = useAccessStrict();
+
+  if (!authenticated) {
+    return <Navigate to={loginPath} replace />;
+  }
+
+  if (page && !hasPage(page)) {
+    return <Navigate to={deniedPath} replace />;
+  }
+
+  if (roles && roles.length > 0) {
+    const hasAny = roles.some(r => hasRole(r));
+    if (!hasAny) {
+      return <Navigate to={deniedPath} replace />;
+    }
+  }
+
+  return children;
+}

package/src/ThemeContext.jsx

@@ -0,0 +1,84 @@
+import { createContext, useContext, useState, useCallback, useEffect } from 'react';
+
+var STORAGE_KEY = 'xeplr-theme';
+var DEFAULT_THEME = 'dark';
+var BUILT_IN_THEMES = ['dark', 'light', 'medium', 'bright'];
+
+var ThemeContext = createContext(null);
+
+/**
+ * ThemeProvider — wraps your app to provide theme state.
+ *
+ * Props:
+ *   theme       — initial theme name (default: 'dark', or last saved)
+ *   persist     — save to localStorage (default: true)
+ *   children    — React children
+ *
+ * The provider applies a `xeplr-theme-{name}` class to a wrapper div.
+ * Any xeplr-ui component inside will pick up the theme via CSS variables.
+ *
+ * Usage:
+ *   <ThemeProvider theme="dark">
+ *     <App />
+ *   </ThemeProvider>
+ *
+ * Custom themes:
+ *   1. Define `.xeplr-theme-corporate { --xeplr-bg-primary: ...; }` in your CSS
+ *   2. Use <ThemeProvider theme="corporate">
+ */
+export function ThemeProvider({ theme: initialTheme, persist = true, children }) {
+  var [theme, setThemeState] = useState(function() {
+    if (persist) {
+      try {
+        var saved = localStorage.getItem(STORAGE_KEY);
+        if (saved) return saved;
+      } catch (e) {}
+    }
+    return initialTheme || DEFAULT_THEME;
+  });
+
+  var setTheme = useCallback(function(newTheme) {
+    setThemeState(newTheme);
+    if (persist) {
+      try { localStorage.setItem(STORAGE_KEY, newTheme); } catch (e) {}
+    }
+  }, [persist]);
+
+  var value = {
+    theme: theme,
+    setTheme: setTheme,
+    themes: BUILT_IN_THEMES,
+    className: 'xeplr-theme-' + theme,
+  };
+
+  return (
+    <ThemeContext.Provider value={value}>
+      <div className={'xeplr-theme-' + theme}>
+        {children}
+      </div>
+    </ThemeContext.Provider>
+  );
+}
+
+/**
+ * useTheme — access current theme and setter.
+ *
+ * Returns null if no ThemeProvider is wrapping the app.
+ * Use useThemeStrict() if you want it to throw.
+ *
+ * Returns: { theme, setTheme, themes, className }
+ */
+export function useTheme() {
+  return useContext(ThemeContext);
+}
+
+/**
+ * useThemeStrict — throws if no ThemeProvider found.
+ */
+export function useThemeStrict() {
+  var ctx = useContext(ThemeContext);
+  if (!ctx) throw new Error('[xeplr] useThemeStrict() must be used inside <ThemeProvider>');
+  return ctx;
+}
+
+export { BUILT_IN_THEMES, DEFAULT_THEME };

package/src/adminApi.js

@@ -0,0 +1,68 @@
+import { authFetch } from './api.js';
+
+/**
+ * Admin API — model layer for RBAC management.
+ * Pure logic, no React dependency.
+ */
+
+export function getUsers() {
+  return authFetch('/auth/api/admin/users');
+}
+
+export function getRoles() {
+  return authFetch('/auth/api/admin/roles');
+}
+
+export function getAccessItems() {
+  return authFetch('/auth/api/admin/access-items');
+}
+
+export function toggleUserRole({ userId, roleId, assign }) {
+  return authFetch('/auth/api/admin/user-role', {
+    method: 'POST',
+    body: JSON.stringify({ userId, roleId, assign }),
+  });
+}
+
+export function toggleAccessRole({ type, itemId, roleId, assign }) {
+  return authFetch('/auth/api/admin/access-role', {
+    method: 'POST',
+    body: JSON.stringify({ type, itemId, roleId, assign }),
+  });
+}
+
+export function toggleModuleRole({ module, action, roleId, assign }) {
+  return authFetch('/auth/api/admin/module-role', {
+    method: 'POST',
+    body: JSON.stringify({ module, action, roleId, assign }),
+  });
+}
+
+// ─── Tenant management (Super Admin) ───
+
+export function getTenants(level) {
+  var url = '/auth/api/admin/tenants';
+  if (level) url += '?level=' + level;
+  return authFetch(url);
+}
+
+export function saveTenant(data) {
+  return authFetch('/auth/api/admin/tenants', {
+    method: 'POST',
+    body: JSON.stringify(data),
+  });
+}
+
+export function deleteTenant(id) {
+  return authFetch('/auth/api/admin/tenants/delete', {
+    method: 'POST',
+    body: JSON.stringify({ id }),
+  });
+}
+
+export function assignUserTenant({ userId, tenantId, level }) {
+  return authFetch('/auth/api/admin/tenants/assign-user', {
+    method: 'POST',
+    body: JSON.stringify({ userId, tenantId, level }),
+  });
+}

package/src/api.js

@@ -0,0 +1,196 @@
+import { getToken, setToken, getRefreshToken, setRefreshToken, clearAuth } from './token.js';
+
+let _baseUrl = '';
+let _onSessionExpired = null;
+let _refreshPromise = null;
+
+/**
+ * Configure the auth API base URL.
+ * @param {string} baseUrl - e.g. 'http://localhost:19001'
+ * @param {object} [options]
+ * @param {function} [options.onSessionExpired] - Called when refresh token also fails (full logout)
+ */
+export function configure(baseUrl, options = {}) {
+  _baseUrl = baseUrl;
+  _onSessionExpired = options.onSessionExpired || null;
+}
+
+function getBaseUrl() {
+  return _baseUrl || '';
+}
+
+/**
+ * Refresh the access token using the stored refresh token.
+ * Returns true if refresh succeeded, false if session is dead.
+ * Deduplicates concurrent refresh calls.
+ */
+async function refreshAccessToken() {
+  // If a refresh is already in flight, wait for it
+  if (_refreshPromise) return _refreshPromise;
+
+  _refreshPromise = (async () => {
+    const refreshToken = getRefreshToken();
+    if (!refreshToken) return false;
+
+    try {
+      const res = await fetch(`${getBaseUrl()}/auth/api/refresh`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ refreshToken }),
+      });
+
+      if (!res.ok) {
+        clearAuth();
+        if (_onSessionExpired) _onSessionExpired();
+        return false;
+      }
+
+      const data = await res.json();
+      setToken(data.accessToken);
+      setRefreshToken(data.refreshToken);
+      return true;
+    } catch (e) {
+      clearAuth();
+      if (_onSessionExpired) _onSessionExpired();
+      return false;
+    }
+  })();
+
+  try {
+    return await _refreshPromise;
+  } finally {
+    _refreshPromise = null;
+  }
+}
+
+/**
+ * Authenticated fetch with auto-refresh.
+ * Attaches Bearer token, retries once on 401 after refreshing.
+ */
+export async function authFetch(endpoint, options = {}) {
+  const url = endpoint.startsWith('http') ? endpoint : `${getBaseUrl()}${endpoint}`;
+
+  const headers = {
+    'Content-Type': 'application/json',
+    ...options.headers,
+  };
+
+  const token = getToken();
+  if (token) {
+    headers['Authorization'] = `Bearer ${token}`;
+  }
+
+  // Attach active tenant from session
+  try {
+    var tenantRaw = localStorage.getItem('xeplr:activeTenant');
+    if (tenantRaw) {
+      var tenant = JSON.parse(tenantRaw);
+      if (tenant && tenant.id) headers['X-Tenant-Id'] = tenant.id;
+    }
+  } catch (e) {}
+
+  let res = await fetch(url, { ...options, headers });
+
+  // If 401, try refreshing the token and retry once
+  if (res.status === 401) {
+    const refreshed = await refreshAccessToken();
+    if (refreshed) {
+      headers['Authorization'] = `Bearer ${getToken()}`;
+      res = await fetch(url, { ...options, headers });
+    }
+  }
+
+  const data = await res.json();
+  if (!res.ok) {
+    throw new Error(data.error || 'Something went wrong');
+  }
+  return data;
+}
+
+/**
+ * Unauthenticated request (for login, register, etc.)
+ */
+async function request(endpoint, options = {}) {
+  const res = await fetch(`${getBaseUrl()}${endpoint}`, {
+    headers: { 'Content-Type': 'application/json' },
+    ...options,
+  });
+  const data = await res.json();
+  if (!res.ok) {
+    throw new Error(data.error || 'Something went wrong');
+  }
+  return data;
+}
+
+export function registerUser({ email, password, name, phoneNumber }) {
+  return request('/auth/api/register', {
+    method: 'POST',
+    body: JSON.stringify({ email, password, name, phoneNumber }),
+  });
+}
+
+export function activateAccount(token) {
+  return request('/auth/api/activate?token=' + encodeURIComponent(token));
+}
+
+export function loginUser({ email, password }) {
+  return request('/auth/api/login', {
+    method: 'POST',
+    body: JSON.stringify({ email, password }),
+  });
+}
+
+export function forgotPassword({ email }) {
+  return request('/auth/api/forgot-password', {
+    method: 'POST',
+    body: JSON.stringify({ email }),
+  });
+}
+
+export function resetPassword({ token, newPassword }) {
+  return request('/auth/api/reset-password', {
+    method: 'POST',
+    body: JSON.stringify({ token, newPassword }),
+  });
+}
+
+export function changePassword({ currentPassword, newPassword }) {
+  return authFetch('/auth/api/change-password', {
+    method: 'POST',
+    body: JSON.stringify({ currentPassword, newPassword }),
+  });
+}
+
+export function getProfile() {
+  return authFetch('/auth/api/profile');
+}
+
+export function updateProfile(fields) {
+  return authFetch('/auth/api/profile', {
+    method: 'PUT',
+    body: JSON.stringify(fields),
+  });
+}
+
+export function getMyTenants() {
+  return authFetch('/auth/api/my-tenants');
+}
+
+export function logoutUser() {
+  const refreshToken = getRefreshToken();
+  const accessToken = getToken();
+
+  clearAuth();
+
+  // Best-effort server-side cleanup
+  if (refreshToken) {
+    const headers = { 'Content-Type': 'application/json' };
+    if (accessToken) headers['Authorization'] = `Bearer ${accessToken}`;
+
+    fetch(`${getBaseUrl()}/auth/api/logout`, {
+      method: 'POST',
+      headers,
+      body: JSON.stringify({ refreshToken }),
+    }).catch(() => {});
+  }
+}