@snapdragonsnursery/react-components 1.0.2 → 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.2",
+  "version": "1.0.5",
   "description": "",
   "main": "src/index.js",
   "scripts": {
@@ -19,6 +19,8 @@
   },
   "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 {
@@ -7,34 +24,20 @@ import {
   clearUserContext,
 } from "./telemetry";
 import ThemeToggle from "./ThemeToggle";
+import { Menu } from "@headlessui/react";
+import { createPopper } from "@popperjs/core";
 
 const isMobile = window.innerWidth < 640;
 
 function AuthButtons({ theme, setTheme, authState, setAuthState }) {
   const [isLoggingIn, setIsLoggingIn] = useState(false);
   const [profilePicture, setProfilePicture] = useState(null);
-  const [showProfileMenu, setShowProfileMenu] = useState(false);
-  const menuRef = useRef();
   const isLocalhost = window.location.hostname === "localhost";
 
   // Use MSAL hooks - parent app should ensure MSAL is initialized
   const { instance, accounts } = useMsal();
   const isAuthenticated = useIsAuthenticated();
 
-  // Close profile menu when clicking outside
-  useEffect(() => {
-    const handleClickOutside = (event) => {
-      if (menuRef.current && !menuRef.current.contains(event.target)) {
-        setShowProfileMenu(false);
-      }
-    };
-
-    document.addEventListener("mousedown", handleClickOutside);
-    return () => {
-      document.removeEventListener("mousedown", handleClickOutside);
-    };
-  }, []);
-
   // Update auth state when MSAL state changes
   useEffect(() => {
     if (instance) {
@@ -213,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">
@@ -250,51 +306,51 @@ function AuthButtons({ theme, setTheme, authState, setAuthState }) {
   }
 
   return (
-    <div className="relative">
-      {/* Profile picture as trigger */}
-      {profilePicture ? (
-        <img
-          src={profilePicture}
-          alt={`${displayName}'s profile picture`}
-          className="w-8 h-8 rounded-full object-cover border-2 border-blue-500 cursor-pointer"
-          onClick={() => setShowProfileMenu((v) => !v)}
-        />
-      ) : (
-        <div
-          className="w-8 h-8 rounded-full bg-blue-500 flex items-center justify-center cursor-pointer border-2 border-blue-500"
-          onClick={() => setShowProfileMenu((v) => !v)}
+    <div className="relative inline-block text-left">
+      <div>
+        <Menu.Button
+          as="div"
+          ref={buttonRef}
+          className="focus:outline-none"
+          onClick={() => setMenuOpen((open) => !open)}
         >
-          <span className="text-white text-sm font-medium">
-            {displayName
-              .split(" ")
-              .map((n) => n[0])
-              .join("")
-              .toUpperCase()
-              .slice(0, 2)}
-          </span>
-        </div>
-      )}
-      {showProfileMenu && (
+          {profilePicture ? (
+            <img
+              src={profilePicture}
+              alt={`${displayName}'s profile picture`}
+              className="w-8 h-8 rounded-full object-cover border-2 border-blue-500 cursor-pointer"
+            />
+          ) : (
+            <div className="w-8 h-8 rounded-full bg-blue-500 flex items-center justify-center cursor-pointer border-2 border-blue-500">
+              <span className="text-white text-sm font-medium">
+                {displayName
+                  .split(" ")
+                  .map((n) => n[0])
+                  .join("")
+                  .toUpperCase()
+                  .slice(0, 2)}
+              </span>
+            </div>
+          )}
+        </Menu.Button>
+      </div>
+      {menuOpen && (
         <div
           ref={menuRef}
-          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"
+          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>
-          {/* Theme toggle inside dropdown */}
           <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 hover:bg-gray-100 dark:hover:bg-gray-700 transition-colors"
-            onClick={() => {
-              setShowProfileMenu(false);
-              handleLogout();
-            }}
+            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">
-              {/* Logout icon */}
               <svg
                 className="w-5 h-5"
                 fill="none"

package/src/ThemeToggleTest.jsx

@@ -0,0 +1,37 @@
+import React, { useState } from "react";
+import ThemeToggle from "./ThemeToggle";
+
+export default function ThemeToggleTest() {
+  const [theme, setTheme] = useState("system");
+
+  return (
+    <div
+      style={{
+        minHeight: "100vh",
+        background:
+          theme === "dark"
+            ? "#1a202c"
+            : theme === "light"
+            ? "#f9fafb"
+            : "#e5e7eb",
+        display: "flex",
+        alignItems: "center",
+        justifyContent: "center",
+        transition: "background 0.3s",
+      }}
+    >
+      <div style={{ width: 300 }}>
+        <ThemeToggle theme={theme} setTheme={setTheme} />
+        <div
+          style={{
+            marginTop: 24,
+            textAlign: "center",
+            color: theme === "dark" ? "#fff" : "#222",
+          }}
+        >
+          <strong>Current theme:</strong> {theme}
+        </div>
+      </div>
+    </div>
+  );
+}

package/src/index.js

@@ -1,4 +1,5 @@
 export { default as AuthButtons } from "./AuthButtons";
 export { default as ThemeToggle } from "./ThemeToggle";
 export { default as ChildSearchModal } from "./ChildSearchModal";
+export { default as ThemeToggleTest } from "./ThemeToggleTest";
 export { configureTelemetry } from "./telemetry";