@snapdragonsnursery/react-components 1.0.4 → 1.0.5

package/README.md

@@ -12,52 +12,466 @@ Reusable React components for Snapdragons projects.
 Install via npm (local path or published package):
 
 ```
-npm install /path/to/react-components
+npm install @snapdragonsnursery/react-components
 ```
 
-Or, if published:
+## Required Dependencies
 
+Your project must have the following installed:
+
+### Core Dependencies
+
+```bash
+npm install react react-dom
+npm install @azure/msal-browser @azure/msal-react
+npm install @headlessui/react @heroicons/react
 ```
-npm install snaps-react-components
+
+### CSS Framework (Required for AuthButtons styling)
+
+```bash
+npm install -D tailwindcss postcss autoprefixer
+npx tailwindcss init -p
 ```
 
-## Peer Dependencies
+## Complete Setup Guide for New Projects
 
-Your project must have the following installed:
-- `react` (>=18)
-- `react-dom` (>=18)
-- `@azure/msal-react` (>=1.0.0)
+### 1. Install Dependencies
 
-## Usage
+```bash
+# Core authentication dependencies
+npm install @azure/msal-browser @azure/msal-react
+
+# UI dependencies for AuthButtons
+npm install @headlessui/react @heroicons/react
+
+# Tailwind CSS (required for styling)
+npm install -D tailwindcss postcss autoprefixer
+npx tailwindcss init -p
+
+# Install this component library
+npm install @snapdragonsnursery/react-components
+```
 
-```jsx
-import { AuthButtons, ThemeToggle } from 'react-components';
+### 2. Configure Tailwind CSS
 
-// Example usage in your header:
-<AuthButtons
-  theme={theme}
-  setTheme={setTheme}
-  authState={authState}
-  setAuthState={setAuthState}
-/>
+Update `tailwind.config.js`:
 
-// Standalone theme toggle:
-<ThemeToggle theme={theme} setTheme={setTheme} />
+```javascript
+/** @type {import('tailwindcss').Config} */
+export default {
+  content: ["./index.html", "./src/**/*.{js,ts,jsx,tsx}"],
+  darkMode: "class",
+  theme: {
+    extend: {},
+  },
+  plugins: [],
+};
 ```
 
-- `theme` and `setTheme` should be managed by your app (e.g., via context or state).
-- `authState` and `setAuthState` should be managed by your app, typically using MSAL hooks.
+Update `src/index.css`:
+
+```css
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+/* Your custom styles */
+body {
+  margin: 0;
+  font-family: system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", "Roboto",
+    "Oxygen", "Ubuntu", "Cantarell", "Open Sans", "Helvetica Neue", sans-serif;
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}
+
+#root {
+  min-height: 100vh;
+}
+```
+
+### 3. Create Authentication Configuration
+
+Create `src/utils/authConfig.js`:
+
+```javascript
+import { LogLevel } from "@azure/msal-browser";
+
+export const msalConfig = {
+  auth: {
+    clientId: "2e2d9456-a0b7-4651-a8f8-c979ed1486b0", // Snapdragons Azure AD App
+    authority:
+      "https://login.microsoftonline.com/d098ee48-9874-4959-8229-da24c99c36fb",
+    redirectUri: window.location.origin,
+    postLogoutRedirectUri: window.location.origin,
+    navigateToLoginRequestUrl: false,
+  },
+  cache: {
+    cacheLocation: "sessionStorage",
+    storeAuthStateInCookie: false,
+  },
+  system: {
+    loggerOptions: {
+      loggerCallback: (level, message, containsPii) => {
+        if (containsPii) return;
+        switch (level) {
+          case LogLevel.Error:
+            console.error(message);
+            return;
+          case LogLevel.Warning:
+            console.warn(message);
+            return;
+          default:
+            return;
+        }
+      },
+      logLevel: LogLevel.Warning,
+    },
+  },
+};
+
+export const loginRequest = {
+  scopes: ["User.Read", "email", "profile", "Directory.Read.All"],
+};
+
+export const adminConfig = {
+  adminEmailDomains: [],
+  adminEmails: [
+    "james@snapdragonsnursery.com",
+    "accounts@snapdragonsnursery.com",
+  ],
+  adminGroupIds: [],
+  adminRoles: ["FundingAdmin", "Admin"],
+};
+
+export const isUserAdmin = (account, idTokenClaims = null) => {
+  if (!account) return false;
+  const claims = idTokenClaims || account.idTokenClaims;
+  const email = account.username || claims?.email || claims?.preferred_username;
+
+  if (
+    email &&
+    adminConfig.adminEmailDomains.some((domain) =>
+      email.toLowerCase().endsWith(`@${domain.toLowerCase()}`)
+    )
+  ) {
+    return true;
+  }
+
+  if (
+    email &&
+    adminConfig.adminEmails.some(
+      (adminEmail) => email.toLowerCase() === adminEmail.toLowerCase()
+    )
+  ) {
+    return true;
+  }
+
+  if (claims?.groups && adminConfig.adminGroupIds.length > 0) {
+    const userGroups = Array.isArray(claims.groups)
+      ? claims.groups
+      : [claims.groups];
+    if (
+      userGroups.some((groupId) => adminConfig.adminGroupIds.includes(groupId))
+    ) {
+      return true;
+    }
+  }
+
+  if (claims?.roles && adminConfig.adminRoles.length > 0) {
+    const userRoles = Array.isArray(claims.roles)
+      ? claims.roles
+      : [claims.roles];
+    if (userRoles.some((role) => adminConfig.adminRoles.includes(role))) {
+      return true;
+    }
+  }
+
+  return false;
+};
+```
+
+### 4. Create Authentication Provider
+
+Create `src/utils/AuthProvider.jsx`:
+
+```javascript
+import React, { createContext, useContext, useEffect, useState } from "react";
+import { useMsal, useAccount } from "@azure/msal-react";
+import { isUserAdmin } from "./authConfig";
+
+const AuthContext = createContext();
+
+export const useAuth = () => {
+  const context = useContext(AuthContext);
+  if (!context) {
+    throw new Error("useAuth must be used within an AuthProvider");
+  }
+  return context;
+};
+
+export const AuthProvider = ({ children }) => {
+  const { instance, accounts } = useMsal();
+  const account = useAccount(accounts[0] || {});
+  const [isLoading, setIsLoading] = useState(true);
+  const [userRole, setUserRole] = useState(null);
+
+  useEffect(() => {
+    const checkUserRole = async () => {
+      if (account) {
+        const adminStatus = isUserAdmin(account);
+        setUserRole(adminStatus ? "admin" : "employee");
+      } else {
+        setUserRole(null);
+      }
+      setIsLoading(false);
+    };
+    checkUserRole();
+  }, [account]);
+
+  const login = async () => {
+    try {
+      await instance.loginPopup();
+    } catch (error) {
+      console.error("Login failed:", error);
+      throw error;
+    }
+  };
+
+  const logout = async () => {
+    try {
+      await instance.logoutPopup();
+    } catch (error) {
+      console.error("Logout failed:", error);
+      throw error;
+    }
+  };
+
+  const isAuthenticated = !!account;
+  const isAdmin = userRole === "admin";
+
+  const value = {
+    account,
+    isAuthenticated,
+    isAdmin,
+    userRole,
+    isLoading,
+    login,
+    logout,
+    instance,
+  };
+
+  return <AuthContext.Provider value={value}>{children}</AuthContext.Provider>;
+};
+```
 
-## Telemetry
+### 5. Create Theme Provider
 
-This package includes stub telemetry functions by default. You can replace or extend these in your app as needed by providing your own implementations in place of `src/telemetry.js`.
+Create `src/utils/theme.jsx`:
 
-## Development
+```javascript
+import { createContext, useContext, useEffect, useState } from "react";
 
-- Components are in `src/`.
-- Exported via `src/index.js`.
-- Update or add new components as needed.
+const ThemeContext = createContext();
 
----
+export function ThemeProvider({ children }) {
+  const [theme, setTheme] = useState("system");
+
+  useEffect(() => {
+    const savedTheme = localStorage.getItem("theme");
+    if (savedTheme && ["light", "dark", "system"].includes(savedTheme)) {
+      setTheme(savedTheme);
+    } else {
+      setTheme("system");
+    }
+  }, []);
+
+  useEffect(() => {
+    const applyTheme = () => {
+      if (theme === "system") {
+        const systemPrefersDark = window.matchMedia(
+          "(prefers-color-scheme: dark)"
+        ).matches;
+        if (systemPrefersDark) {
+          document.documentElement.classList.add("dark");
+        } else {
+          document.documentElement.classList.remove("dark");
+        }
+      } else if (theme === "dark") {
+        document.documentElement.classList.add("dark");
+      } else {
+        document.documentElement.classList.remove("dark");
+      }
+    };
+
+    applyTheme();
+    localStorage.setItem("theme", theme);
+  }, [theme]);
+
+  useEffect(() => {
+    if (theme !== "system") return;
+
+    const mediaQuery = window.matchMedia("(prefers-color-scheme: dark)");
+    const handleChange = () => {
+      if (theme === "system") {
+        if (mediaQuery.matches) {
+          document.documentElement.classList.add("dark");
+        } else {
+          document.documentElement.classList.remove("dark");
+        }
+      }
+    };
+
+    mediaQuery.addEventListener("change", handleChange);
+    return () => mediaQuery.removeEventListener("change", handleChange);
+  }, [theme]);
+
+  return (
+    <ThemeContext.Provider value={{ theme, setTheme }}>
+      {children}
+    </ThemeContext.Provider>
+  );
+}
+
+export function useTheme() {
+  const context = useContext(ThemeContext);
+  if (context === undefined) {
+    throw new Error("useTheme must be used within a ThemeProvider");
+  }
+  return context;
+}
+```
+
+### 6. Setup Main Entry Point
+
+Update `src/main.jsx`:
+
+```javascript
+import React from "react";
+import ReactDOM from "react-dom/client";
+import App from "./App.jsx";
+import "./index.css";
+import { MsalProvider } from "@azure/msal-react";
+import { PublicClientApplication } from "@azure/msal-browser";
+import { msalConfig } from "./utils/authConfig";
+import { AuthProvider } from "./utils/AuthProvider";
+import { ThemeProvider } from "./utils/theme";
+
+const msalInstance = new PublicClientApplication(msalConfig);
+
+ReactDOM.createRoot(document.getElementById("root")).render(
+  <React.StrictMode>
+    <MsalProvider instance={msalInstance}>
+      <AuthProvider>
+        <ThemeProvider>
+          <App />
+        </ThemeProvider>
+      </AuthProvider>
+    </MsalProvider>
+  </React.StrictMode>
+);
+```
+
+### 7. Create Navbar Component
+
+Create `src/components/Navbar.jsx`:
+
+```javascript
+import React, { useState, useEffect } from "react";
+import { AuthButtons } from "@snapdragonsnursery/react-components";
+import { useAuth } from "../utils/AuthProvider";
+import { useTheme } from "../utils/theme";
+
+const Navbar = () => {
+  const { account, userRole, instance } = useAuth();
+  const { theme, setTheme } = useTheme();
+  const [authState, setAuthState] = useState({
+    isAuthenticated: !!account,
+    accountsCount: account ? 1 : 0,
+    account,
+    instance,
+  });
+
+  useEffect(() => {
+    setAuthState({
+      isAuthenticated: !!account,
+      accountsCount: account ? 1 : 0,
+      account,
+      instance,
+    });
+  }, [account, instance]);
+
+  return (
+    <nav className="bg-white dark:bg-gray-800 shadow-md sticky top-0 z-40 px-4 py-2 flex justify-between items-center">
+      <div className="flex items-center space-x-4">
+        <span className="font-bold text-lg text-gray-800 dark:text-gray-100">
+          Your App Name
+        </span>
+      </div>
+      <div className="flex items-center space-x-4">
+        <AuthButtons
+          theme={theme}
+          setTheme={setTheme}
+          authState={authState}
+          setAuthState={setAuthState}
+        />
+      </div>
+    </nav>
+  );
+};
+
+export default Navbar;
+```
+
+### 8. Use in Your App
+
+Update `src/App.jsx`:
+
+```javascript
+import Navbar from "./components/Navbar";
+
+function App() {
+  return (
+    <>
+      <Navbar />
+      {/* Your app content */}
+    </>
+  );
+}
+
+export default App;
+```
+
+## Usage
+
+Once setup is complete, the AuthButtons component will:
+
+- Show a user icon when not authenticated (clickable to login)
+- Show user profile picture or initials when authenticated
+- Provide a dropdown menu with theme toggle and logout option
+- Handle all authentication flows automatically
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Blank icon**: Ensure Tailwind CSS is properly configured and included in your build
+2. **Authentication errors**: Check that all MSAL dependencies are installed and providers are set up correctly
+3. **Theme not working**: Ensure ThemeProvider is wrapping your app and `darkMode: 'class'` is set in Tailwind config
+
+### Required File Structure
+
+```
+src/
+├── utils/
+│   ├── authConfig.js
+│   ├── AuthProvider.jsx
+│   └── theme.jsx
+├── components/
+│   └── Navbar.jsx
+├── main.jsx
+├── App.jsx
+└── index.css
+```
 
-For questions or contributions, contact the Snapdragons development team.
+For questions or contributions, contact the Snapdragons development team.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@snapdragonsnursery/react-components",
-  "version": "1.0.4",
+  "version": "1.0.5",
   "description": "",
   "main": "src/index.js",
   "scripts": {
@@ -20,6 +20,7 @@
   "homepage": "https://github.com/Snapdragons-Nursery/react-components#readme",
   "dependencies": {
     "@headlessui/react": "^2.2.4",
+    "@popperjs/core": "^2.11.8",
     "react": "^18.3.1",
     "react-dom": "^18.3.1"
   },

package/src/AuthButtons.jsx

@@ -1,3 +1,20 @@
+// AuthButtons.jsx
+//
+// Authentication/profile button with dropdown menu for user actions and theme toggle.
+// Uses Popper.js for smart dropdown positioning to prevent overflow.
+//
+// Example usage:
+// import AuthButtons from './AuthButtons';
+// <AuthButtons theme={theme} setTheme={setTheme} authState={authState} setAuthState={setAuthState} />
+//
+// Props:
+// - theme: current theme string
+// - setTheme: function to update theme
+// - authState: authentication state object
+// - setAuthState: function to update auth state
+//
+// The dropdown menu will always remain within the viewport, even if the button is near the edge.
+
 import { useEffect, useState, useRef } from "react";
 import { useMsal, useIsAuthenticated } from "@azure/msal-react";
 import {
@@ -8,6 +25,7 @@ import {
 } from "./telemetry";
 import ThemeToggle from "./ThemeToggle";
 import { Menu } from "@headlessui/react";
+import { createPopper } from "@popperjs/core";
 
 const isMobile = window.innerWidth < 640;
 
@@ -198,6 +216,59 @@ function AuthButtons({ theme, setTheme, authState, setAuthState }) {
   const displayName =
     authState.account?.name ?? authState.account?.idTokenClaims?.name ?? "User";
 
+  // Popper.js refs and logic
+  const buttonRef = useRef(null);
+  const menuRef = useRef(null);
+  const popperInstance = useRef(null);
+
+  // Show/hide state for menu
+  const [menuOpen, setMenuOpen] = useState(false);
+
+  // Setup Popper when menu is open
+  useEffect(() => {
+    if (menuOpen && buttonRef.current && menuRef.current) {
+      popperInstance.current = createPopper(
+        buttonRef.current,
+        menuRef.current,
+        {
+          placement: "bottom-end",
+          modifiers: [
+            { name: "preventOverflow", options: { boundary: "viewport" } },
+            {
+              name: "flip",
+              options: {
+                fallbackPlacements: ["bottom-start", "top-end", "top-start"],
+              },
+            },
+          ],
+        }
+      );
+    }
+    return () => {
+      if (popperInstance.current) {
+        popperInstance.current.destroy();
+        popperInstance.current = null;
+      }
+    };
+  }, [menuOpen]);
+
+  // Close menu on outside click
+  useEffect(() => {
+    if (!menuOpen) return;
+    function handleClick(e) {
+      if (
+        menuRef.current &&
+        !menuRef.current.contains(e.target) &&
+        buttonRef.current &&
+        !buttonRef.current.contains(e.target)
+      ) {
+        setMenuOpen(false);
+      }
+    }
+    document.addEventListener("mousedown", handleClick);
+    return () => document.removeEventListener("mousedown", handleClick);
+  }, [menuOpen]);
+
   if (!authState.account) {
     return (
       <div className="flex items-center gap-2">
@@ -235,9 +306,14 @@ function AuthButtons({ theme, setTheme, authState, setAuthState }) {
   }
 
   return (
-    <Menu as="div" className="relative inline-block text-left">
+    <div className="relative inline-block text-left">
       <div>
-        <Menu.Button className="focus:outline-none">
+        <Menu.Button
+          as="div"
+          ref={buttonRef}
+          className="focus:outline-none"
+          onClick={() => setMenuOpen((open) => !open)}
+        >
           {profilePicture ? (
             <img
               src={profilePicture}
@@ -258,42 +334,42 @@ function AuthButtons({ theme, setTheme, authState, setAuthState }) {
           )}
         </Menu.Button>
       </div>
-      <Menu.Items className="absolute right-0 mt-2 min-w-[220px] max-w-xs w-auto bg-white dark:bg-gray-800 rounded-lg shadow-lg z-50 py-2 border border-gray-200 dark:border-gray-700 focus:outline-none">
-        <div className="px-4 py-2 text-xs text-gray-500 dark:text-gray-300 border-b border-gray-100 dark:border-gray-700">
-          Signed in as <span className="font-semibold">{displayName}</span>
-        </div>
-        <div className="px-4 py-2">
-          <ThemeToggle theme={theme} setTheme={setTheme} />
+      {menuOpen && (
+        <div
+          ref={menuRef}
+          className="z-50 mt-2 min-w-[220px] max-w-xs w-auto bg-white dark:bg-gray-800 rounded-lg shadow-lg py-2 border border-gray-200 dark:border-gray-700 focus:outline-none"
+          style={{ position: "absolute" }}
+        >
+          <div className="px-4 py-2 text-xs text-gray-500 dark:text-gray-300 border-b border-gray-100 dark:border-gray-700">
+            Signed in as <span className="font-semibold">{displayName}</span>
+          </div>
+          <div className="px-4 py-2">
+            <ThemeToggle theme={theme} setTheme={setTheme} />
+          </div>
+          <button
+            className="flex items-center w-full px-4 py-2 text-sm transition-colors hover:bg-gray-100 dark:hover:bg-gray-700"
+            onClick={handleLogout}
+          >
+            <span className="mr-2">
+              <svg
+                className="w-5 h-5"
+                fill="none"
+                stroke="currentColor"
+                viewBox="0 0 24 24"
+              >
+                <path
+                  strokeLinecap="round"
+                  strokeLinejoin="round"
+                  strokeWidth={2}
+                  d="M17 16l4-4m0 0l-4-4m4 4H7m6 4v1a3 3 0 01-3 3H6a3 3 0 01-3-3V7a3 3 0 013-3h4a3 3 0 013 3v1"
+                />
+              </svg>
+            </span>
+            Logout
+          </button>
         </div>
-        <Menu.Item>
-          {({ active }) => (
-            <button
-              className={`flex items-center w-full px-4 py-2 text-sm transition-colors ${
-                active ? "bg-gray-100 dark:bg-gray-700" : ""
-              }`}
-              onClick={handleLogout}
-            >
-              <span className="mr-2">
-                <svg
-                  className="w-5 h-5"
-                  fill="none"
-                  stroke="currentColor"
-                  viewBox="0 0 24 24"
-                >
-                  <path
-                    strokeLinecap="round"
-                    strokeLinejoin="round"
-                    strokeWidth={2}
-                    d="M17 16l4-4m0 0l-4-4m4 4H7m6 4v1a3 3 0 01-3 3H6a3 3 0 01-3-3V7a3 3 0 013-3h4a3 3 0 013 3v1"
-                  />
-                </svg>
-              </span>
-              Logout
-            </button>
-          )}
-        </Menu.Item>
-      </Menu.Items>
-    </Menu>
+      )}
+    </div>
   );
 }