@xeplr/ui-account 1.0.0 → 1.0.1

package/src/pages.jsx

@@ -1,3 +1,4 @@
+import { memo } from 'react';
 import { useLoginController } from './useLoginController.js';
 import { useRegisterController } from './useRegisterController.js';
 import { useForgotPasswordController } from './useForgotPasswordController.js';
@@ -8,85 +9,131 @@ 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';
+import { useNavController } from './useNavController.js';
+import { LoginSample, RegisterSample, ForgotPasswordSample, ResetPasswordSample, ActivateSample, NotActivatedSample, ChangePasswordSample, ProfileSample, UserRolesMatrixSample, AccessMatrixSample, MasterSettingsSample, NavTopSample, NavDrawer } 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, NAV_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.
+ * Ready-made pages: controller (the logic) + sample design (the look), wired together.
+ *
+ * Every page takes an optional `design` prop — pass your OWN design component to
+ * re-skin the page while keeping the framework's controller + validation. The design
+ * receives the controller's output as props (the same contract the sample honours), e.g.
+ * LoginSample gets { email, setEmail, password, setPassword, error, loading, handleSubmit }.
+ *
+ *   <LoginPage design={MyLogin} onSuccess={...} />   // my look, framework logic
+ *   <LoginPage onSuccess={...} />                     // framework look
+ *
+ * Any other props (onSuccess, etc.) flow through to the controller.
  */
 
-export function LoginPage(props) {
+export function LoginPage({ design, ...props }) {
   var controller = useLoginController(props);
   var ref = useDesignValidator('LoginPage', LOGIN_RULES);
-  return <div ref={ref}><LoginSample {...controller} /></div>;
+  var View = design || LoginSample;
+  return <div ref={ref}><View {...controller} /></div>;
 }
 
-export function RegisterPage(props) {
+export function RegisterPage({ design, ...props }) {
   var controller = useRegisterController(props);
   var ref = useDesignValidator('RegisterPage', REGISTER_RULES);
-  return <div ref={ref}><RegisterSample {...controller} /></div>;
+  var View = design || RegisterSample;
+  return <div ref={ref}><View {...controller} /></div>;
 }
 
-export function ForgotPasswordPage() {
-  var controller = useForgotPasswordController();
+export function ForgotPasswordPage({ design, ...props }) {
+  var controller = useForgotPasswordController(props);
   var ref = useDesignValidator('ForgotPasswordPage', FORGOT_PASSWORD_RULES);
-  return <div ref={ref}><ForgotPasswordSample {...controller} /></div>;
+  var View = design || ForgotPasswordSample;
+  return <div ref={ref}><View {...controller} /></div>;
 }
 
-export function ResetPasswordPage() {
-  var controller = useResetPasswordController();
+export function ResetPasswordPage({ design, ...props }) {
+  var controller = useResetPasswordController(props);
   var ref = useDesignValidator('ResetPasswordPage', RESET_PASSWORD_RULES);
-  return <div ref={ref}><ResetPasswordSample {...controller} /></div>;
+  var View = design || ResetPasswordSample;
+  return <div ref={ref}><View {...controller} /></div>;
 }
 
-export function ActivatePage() {
-  var controller = useActivateController();
-  return <ActivateSample {...controller} />;
+export function ActivatePage({ design, ...props }) {
+  var controller = useActivateController(props);
+  var View = design || ActivateSample;
+  return <View {...controller} />;
 }
 
-export function NotActivatedPage() {
-  return <NotActivatedSample />;
+export function NotActivatedPage({ design }) {
+  var View = design || NotActivatedSample;
+  return <View />;
 }
 
-export function ChangePasswordPage(props) {
+export function ChangePasswordPage({ design, ...props }) {
   var controller = useChangePasswordController(props);
   var ref = useDesignValidator('ChangePasswordPage', CHANGE_PASSWORD_RULES);
-  return <div ref={ref}><ChangePasswordSample {...controller} /></div>;
+  var View = design || ChangePasswordSample;
+  return <div ref={ref}><View {...controller} /></div>;
 }
 
-export function ProfilePage(props) {
+export function ProfilePage({ design, ...props }) {
   var controller = useProfileController(props);
   var ref = useDesignValidator('ProfilePage', PROFILE_RULES);
-  return <div ref={ref}><ProfileSample {...controller} /></div>;
+  var View = design || ProfileSample;
+  return <div ref={ref}><View {...controller} /></div>;
 }
 
-export function UserRolesPage(props) {
+export function UserRolesPage({ design, ...props }) {
   var controller = useUserRolesController(props);
   var ref = useDesignValidator('UserRolesPage', USER_ROLES_MATRIX_RULES);
-  return <div ref={ref}><UserRolesMatrixSample {...controller} /></div>;
+  var View = design || UserRolesMatrixSample;
+  return <div ref={ref}><View {...controller} /></div>;
 }
 
-export function AccessMatrixPage(props) {
+export function AccessMatrixPage({ design, ...props }) {
   var controller = useAccessMatrixController(props);
   var ref = useDesignValidator('AccessMatrixPage', ACCESS_MATRIX_RULES);
-  return <div ref={ref}><AccessMatrixSample {...controller} /></div>;
+  var View = design || AccessMatrixSample;
+  return <div ref={ref}><View {...controller} /></div>;
 }
 
-export function MasterSettingsPage(props) {
+export function MasterSettingsPage({ design, ...props }) {
   var controller = useMasterSettingsController(props);
   var ref = useDesignValidator('MasterSettingsPage', MASTER_SETTINGS_RULES);
-  return <div ref={ref}><MasterSettingsSample {...controller} /></div>;
+  var View = design || MasterSettingsSample;
+  return <div ref={ref}><View {...controller} /></div>;
 }
 
-export function TenantPage(props) {
-  var controller = useTenantController(props);
-  return <TenantSample {...controller} />;
+// NavPage is memoized — unlike the other pages, it lives in your app's layout
+// route alongside <Outlet/>, so it must not re-render when the routed page
+// changes. Exactly ONE of two things renders, never both: if `drawerItems` is
+// non-empty, the drawer rail (NavDrawer) IS the nav — it hosts settings,
+// notifications, and everything else that would otherwise be in the top bar.
+// Otherwise the top bar (`design`, defaults to NavTopSample) renders alone.
+// `navMiddle` has no equivalent in the drawer (there's no middle slot in a
+// vertical rail) — it's simply unused whenever a drawer is present.
+// See useNavController.js for the drawerItems/settingsOverrides/notifications
+// props this accepts.
+function NavPageImpl({ design, logo, expandedLogo, navMiddle, drawerPromo, ...props }) {
+  var controller = useNavController(props);
+  var ref = useDesignValidator('NavPage', NAV_RULES);
+  var TopBar = design || NavTopSample;
+  var hasDrawer = controller.drawerItems.length > 0;
+  return (
+    <div ref={ref}>
+      {hasDrawer ? (
+        <NavDrawer
+          {...controller}
+          logo={logo}
+          expandedLogo={expandedLogo}
+          drawerPromo={drawerPromo}
+        />
+      ) : (
+        <TopBar
+          {...controller}
+          logo={logo}
+          navMiddle={navMiddle}
+        />
+      )}
+    </div>
+  );
 }
 
-export function TenantPickerPage(props) {
-  var controller = useTenantPickerController(props);
-  return <TenantPickerSample {...controller} />;
-}
+export var NavPage = memo(NavPageImpl);

package/src/useActivateController.js

@@ -1,5 +1,6 @@
 import { useState, useEffect, useRef } from 'react';
 import { useSearchParams } from 'react-router-dom';
+import { raiseSnackbar } from '@xeplr/ui-utils';
 import { activateAccount } from './api.js';
 
 export function useActivateController() {
@@ -11,17 +12,27 @@ export function useActivateController() {
   var called = useRef(false);
 
   useEffect(function() {
-    if (!token || called.current) return;
+    if (!token) {
+      if (!called.current) {
+        called.current = true;
+        raiseSnackbar('Invalid activation link', { design: 'error' });
+      }
+      return;
+    }
+    if (called.current) return;
     called.current = true;
     setLoading(true);
     setError('');
     setSuccess('');
     activateAccount(token)
       .then(function(result) {
-        setSuccess(result.message || 'Account activated successfully');
+        var message = result.message || 'Account activated successfully';
+        setSuccess(message);
+        raiseSnackbar(message, { design: 'success' });
       })
       .catch(function(err) {
         setError(err.message);
+        raiseSnackbar(err.message, { design: 'error' });
       })
       .finally(function() {
         setLoading(false);

package/src/useChangePasswordController.js

@@ -1,4 +1,5 @@
 import { useState } from 'react';
+import { raiseSnackbar } from '@xeplr/ui-utils';
 import { changePassword } from './api.js';
 
 export function useChangePasswordController(options = {}) {
@@ -17,20 +18,25 @@ export function useChangePasswordController(options = {}) {
     setSuccess('');
 
     if (newPassword !== confirmPassword) {
-      setError('Passwords do not match');
+      var mismatchMessage = 'Passwords do not match';
+      setError(mismatchMessage);
+      raiseSnackbar(mismatchMessage, { design: 'error' });
       return;
     }
 
     setLoading(true);
     try {
       var result = await changePassword({ currentPassword, newPassword });
-      setSuccess('Password changed successfully');
+      var message = 'Password changed successfully';
+      setSuccess(message);
+      raiseSnackbar(message, { design: 'success' });
       setCurrentPassword('');
       setNewPassword('');
       setConfirmPassword('');
       if (onSuccess) onSuccess(result);
     } catch (err) {
       setError(err.message);
+      raiseSnackbar(err.message, { design: 'error' });
     } finally {
       setLoading(false);
     }

package/src/useForgotPasswordController.js

@@ -1,4 +1,5 @@
 import { useState } from 'react';
+import { raiseSnackbar } from '@xeplr/ui-utils';
 import { forgotPassword } from './api.js';
 
 export function useForgotPasswordController() {
@@ -15,8 +16,10 @@ export function useForgotPasswordController() {
     try {
       const result = await forgotPassword({ email });
       setSuccess(result.message);
+      raiseSnackbar(result.message, { design: 'success' });
     } catch (err) {
       setError(err.message);
+      raiseSnackbar(err.message, { design: 'error' });
     } finally {
       setLoading(false);
     }

package/src/useLoginController.js

@@ -1,5 +1,6 @@
 import { useState } from 'react';
 import { useNavigate } from 'react-router-dom';
+import { raiseSnackbar } from '@xeplr/ui-utils';
 import { loginUser } from './api.js';
 import { setToken, setRefreshToken } from './token.js';
 import { useAccess } from './AccessContext.jsx';
@@ -37,6 +38,7 @@ export function useLoginController(options = {}) {
         navigate(notActivatedPath);
       } else {
         setError(err.message);
+        raiseSnackbar(err.message, { design: 'error' });
       }
     } finally {
       setLoading(false);

package/src/useNavController.js

@@ -0,0 +1,102 @@
+import { useState, useRef, useEffect, useCallback, useMemo } from 'react';
+import { useAccessStrict } from './AccessContext.jsx';
+import { authPath } from './authRoutes.jsx';
+
+// The built-in settings-dropdown items — seeded via auth's migrations (menus
+// table, see migrations/0006_seed_catalog.sql), not hardcoded here. Maps a
+// seeded menu NAME to the authRoutes key it links to. "Admin" is deliberately
+// NOT here — the framework's builtin section is Profile/Change Password only;
+// an app that wants an Admin link adds it to its own settingsOverrides. Only
+// names present in access.menus (role-filtered, computed at login) render.
+var BUILTIN_SETTINGS_ITEMS = [
+  { menuName: 'Profile', authKey: 'profile' },
+  { menuName: 'Change Password', authKey: 'changePassword' }
+];
+var NOTIFICATIONS_MENU_NAME = 'Notifications';
+
+/**
+ * Nav is self-contained by design: it reads access/user from context (which only
+ * changes on login/logout/access updates) and owns its OWN open/closed UI state.
+ * It never depends on — and never forces a re-render of — whatever page is
+ * currently mounted in the app's <Outlet/>. Keep it that way when extending:
+ * don't lift this state into the app's layout component.
+ *
+ * @param {object} props
+ * @param {Array<{name:string, icon?:string, clickHandler?:Function, group?:string}>} [props.drawerItems] —
+ *   the app's own drawer catalog (each `name` must match a `menus.name` row in
+ *   the auth DB). Passing a non-empty array auto-activates the drawer rail —
+ *   there's no separate flag. `group` is optional; ungrouped items render
+ *   first, grouped ones under their section header (see NavDrawer.jsx).
+ *   Role-filtered via access.menus, same mechanism as the settings items.
+ * @param {Array<{name:string, path:string}>} [props.settingsOverrides] — the app's
+ *   OWN items rendered ABOVE the builtin (Profile/Change Password) section in
+ *   the settings dropdown — this is where an "Admin" link belongs now. Each
+ *   `name` must match a `menus.name` row you've seeded (in YOUR app's
+ *   migrations-auth, not auth's own) — role-filtered via access.menus.
+ * @param {{count?:number, onClick?:Function}} [props.notifications] — the app's feed
+ *   config. Only takes effect if the user's role grants the "Notifications" menu
+ *   (seeded basic-tier, visible to everyone by default) — otherwise the bell is
+ *   hidden regardless of what's passed here.
+ */
+export function useNavController(props) {
+  props = props || {};
+  var accessCtx = useAccessStrict();
+  var access = accessCtx.access || {};
+  var allowedMenus = access.menus || [];
+
+  var [accountOpen, setAccountOpen] = useState(false);
+  var [drawerOpen, setDrawerOpen] = useState(false);
+
+  var accountRef = useRef(null);
+
+  var toggleAccount = useCallback(function() { setAccountOpen(function(v) { return !v; }); }, []);
+  var closeAccount = useCallback(function() { setAccountOpen(false); }, []);
+  var toggleDrawer = useCallback(function() { setDrawerOpen(function(v) { return !v; }); }, []);
+  var closeDrawer = useCallback(function() { setDrawerOpen(false); }, []);
+
+  // Click-outside for the settings menu only — the drawer closes via its own overlay.
+  useEffect(function() {
+    if (!accountOpen) return;
+    function onDocClick(e) {
+      if (accountRef.current && !accountRef.current.contains(e.target)) closeAccount();
+    }
+    document.addEventListener('mousedown', onDocClick);
+    return function() { document.removeEventListener('mousedown', onDocClick); };
+  }, [accountOpen, closeAccount]);
+
+  // Settings dropdown, in render order: app overrides first, then the fixed
+  // builtin section — role-filtered the same way for both.
+  var accountItems = useMemo(function() {
+    var overrides = (props.settingsOverrides || [])
+      .filter(function(item) { return allowedMenus.indexOf(item.name) !== -1; });
+    var builtin = BUILTIN_SETTINGS_ITEMS
+      .filter(function(item) { return allowedMenus.indexOf(item.menuName) !== -1; })
+      .map(function(item) { return { name: item.menuName, path: authPath(item.authKey) }; });
+    return overrides.concat(builtin);
+  }, [allowedMenus, props.settingsOverrides]);
+
+  var notificationsAllowed = allowedMenus.indexOf(NOTIFICATIONS_MENU_NAME) !== -1;
+
+  // Role-filter the app's own drawer catalog down to what this user can actually see.
+  var drawerItems = useMemo(function() {
+    var catalog = props.drawerItems || [];
+    return catalog.filter(function(m) { return allowedMenus.indexOf(m.name) !== -1; });
+  }, [props.drawerItems, allowedMenus]);
+
+  return {
+    user: accessCtx.user,
+    accountItems: accountItems,
+    notifications: notificationsAllowed ? (props.notifications || null) : null,
+    logout: accessCtx.logout,
+
+    accountOpen: accountOpen,
+    toggleAccount: toggleAccount,
+    closeAccount: closeAccount,
+    accountRef: accountRef,
+
+    drawerOpen: drawerOpen,
+    toggleDrawer: toggleDrawer,
+    closeDrawer: closeDrawer,
+    drawerItems: drawerItems
+  };
+}

package/src/useProfileController.js

@@ -1,4 +1,5 @@
 import { useState, useEffect } from 'react';
+import { raiseSnackbar } from '@xeplr/ui-utils';
 import { getProfile, updateProfile } from './api.js';
 
 export function useProfileController(options = {}) {
@@ -25,6 +26,7 @@ export function useProfileController(options = {}) {
       });
     } catch (err) {
       setError(err.message);
+      raiseSnackbar(err.message, { design: 'error' });
     } finally {
       setFetching(false);
     }
@@ -41,10 +43,13 @@ export function useProfileController(options = {}) {
     setLoading(true);
     try {
       var result = await updateProfile(form);
-      setSuccess('Profile updated successfully');
+      var message = 'Profile updated successfully';
+      setSuccess(message);
+      raiseSnackbar(message, { design: 'success' });
       if (onSuccess) onSuccess(result);
     } catch (err) {
       setError(err.message);
+      raiseSnackbar(err.message, { design: 'error' });
     } finally {
       setLoading(false);
     }

package/src/useRegisterController.js

@@ -1,4 +1,5 @@
 import { useState } from 'react';
+import { raiseSnackbar } from '@xeplr/ui-utils';
 import { registerUser } from './api.js';
 
 export function useRegisterController(options = {}) {
@@ -20,11 +21,14 @@ export function useRegisterController(options = {}) {
     setLoading(true);
     try {
       const result = await registerUser(form);
-      setSuccess('Registration successful. Please wait, someone will activate you.');
+      const message = 'Registration successful. Please wait, someone will activate you.';
+      setSuccess(message);
+      raiseSnackbar(message, { design: 'success' });
       setForm({ name: '', email: '', phoneNumber: '', password: '' });
       if (onSuccess) onSuccess(result);
     } catch (err) {
       setError(err.message);
+      raiseSnackbar(err.message, { design: 'error' });
     } finally {
       setLoading(false);
     }

package/src/useResetPasswordController.js

@@ -1,5 +1,6 @@
-import { useState } from 'react';
+import { useState, useEffect, useRef } from 'react';
 import { useSearchParams } from 'react-router-dom';
+import { raiseSnackbar } from '@xeplr/ui-utils';
 import { resetPassword } from './api.js';
 
 export function useResetPasswordController() {
@@ -9,6 +10,14 @@ export function useResetPasswordController() {
   const [error, setError] = useState('');
   const [success, setSuccess] = useState('');
   const [loading, setLoading] = useState(false);
+  const warnedNoToken = useRef(false);
+
+  useEffect(function() {
+    if (!token && !warnedNoToken.current) {
+      warnedNoToken.current = true;
+      raiseSnackbar('Invalid or expired reset link', { design: 'error' });
+    }
+  }, [token]);
 
   async function handleSubmit(e) {
     e.preventDefault();
@@ -18,8 +27,10 @@ export function useResetPasswordController() {
     try {
       const result = await resetPassword({ token, newPassword: password });
       setSuccess(result.message);
+      raiseSnackbar(result.message, { design: 'success' });
     } catch (err) {
       setError(err.message);
+      raiseSnackbar(err.message, { design: 'error' });
     } finally {
       setLoading(false);
     }

package/src/validateDesign.js

@@ -99,3 +99,9 @@ export var MASTER_SETTINGS_RULES = [
   { id: 'xeplr-admin-master-search', label: 'Master search input' },
   { role: 'tablist', label: 'Tab list for master types' }
 ];
+
+// Only the structure common to every Nav design (both Design 1 and Design 2
+// have an account menu; only Design 2 has a drawer, so that isn't required here).
+export var NAV_RULES = [
+  { selector: '[aria-haspopup="menu"]', label: 'Account menu trigger' }
+];

package/src/designs/TenantPickerSample.jsx

@@ -1,39 +0,0 @@
-import './auth.css';
-
-export default function TenantPickerSample({ tenants, loading, error, label, handleSelect, onLogout }) {
-  return (
-    <div className="xeplr-auth-container">
-      <h1>Select {label}</h1>
-      {error && <div className="xeplr-auth-alert xeplr-auth-alert-error">{error}</div>}
-      {loading ? (
-        <p>Loading...</p>
-      ) : tenants.length === 0 ? (
-        <div className="xeplr-auth-alert xeplr-auth-alert-error">
-          No {label.toLowerCase()}s available. Contact your administrator.
-        </div>
-      ) : (
-        <div className="xeplr-tenant-picker">
-          {tenants.map(function(t) {
-            return (
-              <button
-                key={t.id}
-                type="button"
-                className="xeplr-tenant-option"
-                onClick={function() { handleSelect(t); }}
-              >
-                <span className="xeplr-tenant-name">{t.name}</span>
-                {t.code && <span className="xeplr-tenant-code">{t.code}</span>}
-                {t.description && <span className="xeplr-tenant-desc">{t.description}</span>}
-              </button>
-            );
-          })}
-        </div>
-      )}
-      {onLogout && (
-        <div className="xeplr-auth-links">
-          <p><button type="button" onClick={onLogout} style={{ background: 'none', border: 'none', color: 'var(--xeplr-text-muted, #777)', cursor: 'pointer', fontSize: '14px' }}>Sign out</button></p>
-        </div>
-      )}
-    </div>
-  );
-}