Merged feature/workflows-support into integration

added tests around filter criteria paster tool

.circleci/config.yml

@@ -115,7 +115,7 @@ workflows:
           context: [ qqq-maven-registry-credentials, kingsrook-slack, build-qqq-sample-app ]
           filters:
             branches:
-              ignore: /(main|integration.*)/
+              ignore: /(main|dev|integration.*)/
             tags:
               ignore: /(version|snapshot)-.*/
   deploy:
@@ -124,7 +124,7 @@ workflows:
           context: [ qqq-maven-registry-credentials, kingsrook-slack, build-qqq-sample-app ]
           filters:
             branches:
-              only: /(main|integration.*)/
+              only: /(main|dev|integration.*)/
             tags:
               only: /(version|snapshot)-.*/
 

.gitignore

@@ -5,6 +5,7 @@
 .yalc*
 yalc.lock
 .env
+/certs
 
 # dependencies
 /node_modules

cypress.config.ts

@@ -1,12 +0,0 @@
-import {defineConfig} from "cypress";
-
-export default defineConfig({
-   e2e: {
-      viewportHeight: 1000,
-      viewportWidth: 1200,
-      setupNodeEvents(on, config)
-      {
-      // implement node event listeners here
-      },
-   },
-});

package.json

@@ -6,7 +6,7 @@
       "@auth0/auth0-react": "1.10.2",
       "@emotion/react": "11.7.1",
       "@emotion/styled": "11.6.0",
-      "@kingsrook/qqq-frontend-core": "1.0.97",
+      "@kingsrook/qqq-frontend-core": "1.0.124",
       "@mui/icons-material": "5.4.1",
       "@mui/material": "5.11.1",
       "@mui/styles": "5.11.1",
@@ -36,6 +36,9 @@
       "html-to-text": "^9.0.5",
       "http-proxy-middleware": "2.0.6",
       "jwt-decode": "3.1.2",
+      "lodash": "4.17.21",
+      "oidc-client-ts": "2.4.1",
+      "react-oidc-context": "2.3.1",
       "rapidoc": "9.3.4",
       "react": "18.0.0",
       "react-ace": "10.1.0",
@@ -44,6 +47,7 @@
       "react-dnd": "16.0.1",
       "react-dnd-html5-backend": "16.0.1",
       "react-dom": "18.0.0",
+      "react-dropzone": "14.3.5",
       "react-ga4": "2.1.0",
       "react-github-btn": "1.2.1",
       "react-google-drive-picker": "^1.2.0",
@@ -59,7 +63,7 @@
       "build": "react-scripts build",
       "clean": "rm -rf node_modules package-lock.json lib",
       "eject": "react-scripts eject",
-      "clean-and-install": "rm -rf node_modules/ && rm -rf package-lock.json && rm -rf lib/ && npm install --legacy-peer-deps",
+      "clean-and-install": "rm -rf node_modules/ && rm -rf package-lock.json && rm -rf lib/ && npm install --legacy-peer-deps && npm dedupe --force",
       "npm-install": "npm install --legacy-peer-deps",
       "prepublishOnly": "tsc -p ./ --outDir lib/",
       "start": "BROWSER=none react-scripts --max-http-header-size=65535 start",

pom.xml

@@ -29,7 +29,7 @@
    <packaging>jar</packaging>
 
    <properties>
-      <revision>0.20.0-SNAPSHOT</revision>
+      <revision>0.26.0-SNAPSHOT</revision>
 
       <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
       <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
@@ -66,7 +66,13 @@
       <dependency>
          <groupId>com.kingsrook.qqq</groupId>
          <artifactId>qqq-backend-core</artifactId>
-         <version>0.20.0-20240308.165846-65</version>
+         <version>0.26.0-integration-20250529-234230</version>
+      </dependency>
+      <dependency>
+         <groupId>com.kingsrook.qqq</groupId>
+         <artifactId>qqq-middleware-javalin</artifactId>
+         <optional>true</optional>
+         <version>0.26.0-integration-20250529-234230</version>
       </dependency>
       <dependency>
          <groupId>org.slf4j</groupId>
@@ -154,11 +160,11 @@
                   <versionTagPrefix>version-</versionTagPrefix>
                </gitFlowConfig>
                <skipFeatureVersion>true</skipFeatureVersion> <!-- Keep feature names out of versions -->
-               <postReleaseGoals>install</postReleaseGoals>  <!-- Let CI run deploys -->
                <commitDevelopmentVersionAtStart>true</commitDevelopmentVersionAtStart>
                <versionDigitToIncrement>1</versionDigitToIncrement> <!-- In general, we update the minor -->
                <versionProperty>revision</versionProperty>
                <skipUpdateVersion>true</skipUpdateVersion>
+               <skipTestProject>true</skipTestProject> <!-- we allow CI to do the tests -->
             </configuration>
          </plugin>
 

src/App.tsx

@@ -19,7 +19,6 @@
  * along with this program.  If not, see <https://www.gnu.org/licenses/>.
  */
 
-import {useAuth0} from "@auth0/auth0-react";
 import {QException} from "@kingsrook/qqq-frontend-core/lib/exceptions/QException";
 import {QAppNodeType} from "@kingsrook/qqq-frontend-core/lib/model/metaData/QAppNodeType";
 import {QAppTreeNode} from "@kingsrook/qqq-frontend-core/lib/model/metaData/QAppTreeNode";
@@ -29,16 +28,20 @@ import {QInstance} from "@kingsrook/qqq-frontend-core/lib/model/metaData/QInstan
 import {QProcessMetaData} from "@kingsrook/qqq-frontend-core/lib/model/metaData/QProcessMetaData";
 import {QTableMetaData} from "@kingsrook/qqq-frontend-core/lib/model/metaData/QTableMetaData";
 import Avatar from "@mui/material/Avatar";
+import Box from "@mui/material/Box";
 import CssBaseline from "@mui/material/CssBaseline";
 import Icon from "@mui/material/Icon";
 import {ThemeProvider} from "@mui/material/styles";
 import {LicenseInfo} from "@mui/x-license-pro";
 import CommandMenu from "CommandMenu";
-import jwt_decode from "jwt-decode";
 import QContext from "QContext";
+import useAnonymousAuthenticationModule from "qqq/authorization/anonymous/useAnonymousAuthenticationModule";
+import useAuth0AuthenticationModule from "qqq/authorization/auth0/useAuth0AuthenticationModule";
+import useOAuth2AuthenticationModule from "qqq/authorization/oauth2/useOAuth2AuthenticationModule";
 import Sidenav from "qqq/components/horseshoe/sidenav/SideNav";
 import theme from "qqq/components/legacy/Theme";
-import {setMiniSidenav, setOpenConfigurator, useMaterialUIController} from "qqq/context";
+import {getBannerClassName, getBannerStyles, getBanner, makeBannerContent} from "qqq/components/misc/Banners";
+import {setMiniSidenav, useMaterialUIController} from "qqq/context";
 import AppHome from "qqq/pages/apps/Home";
 import NoApps from "qqq/pages/apps/NoApps";
 import ProcessRun from "qqq/pages/processes/ProcessRun";
@@ -49,6 +52,7 @@ import EntityEdit from "qqq/pages/records/edit/RecordEdit";
 import RecordQuery from "qqq/pages/records/query/RecordQuery";
 import RecordDeveloperView from "qqq/pages/records/view/RecordDeveloperView";
 import RecordView from "qqq/pages/records/view/RecordView";
+import RecordViewByUniqueKey from "qqq/pages/records/view/RecordViewByUniqueKey";
 import GoogleAnalyticsUtils, {AnalyticsModel} from "qqq/utils/GoogleAnalyticsUtils";
 import Client from "qqq/utils/qqq/Client";
 import ProcessUtils from "qqq/utils/qqq/ProcessUtils";
@@ -61,10 +65,14 @@ import {Md5} from "ts-md5/dist/md5";
 const qController = Client.getInstance();
 export const SESSION_UUID_COOKIE_NAME = "sessionUUID";
 
-export default function App()
+interface Props
 {
-   const [cookies, setCookie, removeCookie] = useCookies([SESSION_UUID_COOKIE_NAME]);
-   const {user, getAccessTokenSilently, logout} = useAuth0();
+   authenticationMetaData: QAuthenticationMetaData;
+}
+
+export default function App({authenticationMetaData}: Props)
+{
+   const [, , removeCookie] = useCookies([SESSION_UUID_COOKIE_NAME]);
    const [loadingToken, setLoadingToken] = useState(false);
    const [isFullyAuthenticated, setIsFullyAuthenticated] = useState(false);
    const [profileRoutes, setProfileRoutes] = useState({});
@@ -73,68 +81,20 @@ export default function App()
    const [needLicenseKey, setNeedLicenseKey] = useState(true);
    const [loggedInUser, setLoggedInUser] = useState({} as { name?: string, email?: string });
    const [defaultRoute, setDefaultRoute] = useState("/no-apps");
+   const [earlyReturnForAuth, setEarlyReturnForAuth] = useState(null as JSX.Element);
+
+   const {setupSession: auth0SetupSession, logout: auth0Logout} = useAuth0AuthenticationModule({setIsFullyAuthenticated, setLoggedInUser, setEarlyReturnForAuth});
+   const {setupSession: oauth2SetupSession, logout: oauth2Logout} = useOAuth2AuthenticationModule({setIsFullyAuthenticated, setLoggedInUser, setEarlyReturnForAuth, inOAuthContext: authenticationMetaData.type === "OAUTH2"});
+   const {setupSession: anonymousSetupSession, logout: anonymousLogout} = useAnonymousAuthenticationModule({setIsFullyAuthenticated, setLoggedInUser, setEarlyReturnForAuth});
 
    /////////////////////////////////////////////////////////
    // tell the client how to do a logout if it sees a 401 //
    /////////////////////////////////////////////////////////
-   Client.setUnauthorizedCallback(() =>
-   {
-      logout();
-   });
-
-   const shouldStoreNewToken = (newToken: string, oldToken: string): boolean =>
-   {
-      if (!cookies[SESSION_UUID_COOKIE_NAME])
-      {
-         console.log("No session uuid cookie - so we should store a new one.");
-         return (true);
-      }
-
-      if (!oldToken)
-      {
-         console.log("No accessToken in localStorage - so we should store a new one.");
-         return (true);
-      }
-
-      try
-      {
-         const oldJSON: any = jwt_decode(oldToken);
-         const newJSON: any = jwt_decode(newToken);
-
-         ////////////////////////////////////////////////////////////////////////////////////
-         // if the old (local storage) token is expired, then we need to store the new one //
-         ////////////////////////////////////////////////////////////////////////////////////
-         const oldExp = oldJSON["exp"];
-         if (oldExp * 1000 < (new Date().getTime()))
-         {
-            console.log("Access token in local storage was expired - so we should store a new one.");
-            return (true);
-         }
-
-         ////////////////////////////////////////////////////////////////////////////////////////////////
-         // remove the exp & iat values from what we compare - as they are always different from auth0 //
-         // note, this is only deleting them from what we compare, not from what we'd store.           //
-         ////////////////////////////////////////////////////////////////////////////////////////////////
-         delete newJSON["exp"];
-         delete newJSON["iat"];
-         delete oldJSON["exp"];
-         delete oldJSON["iat"];
-
-         const different = JSON.stringify(newJSON) !== JSON.stringify(oldJSON);
-         if (different)
-         {
-            console.log("Latest access token from auth0 has changed vs localStorage - so we should store a new one.");
-         }
-         return (different);
-      }
-      catch (e)
-      {
-         console.log("Caught in shouldStoreNewToken: " + e);
-      }
-
-      return (true);
-   };
+   Client.setUnauthorizedCallback(() => doLogout());
 
+   /////////////////////////////////////////////////
+   // deal with making sure user is authenticated //
+   /////////////////////////////////////////////////
    useEffect(() =>
    {
       if (loadingToken)
@@ -145,65 +105,17 @@ export default function App()
 
       (async () =>
       {
-         const authenticationMetaData: QAuthenticationMetaData = await qController.getAuthenticationMetaData();
-
          if (authenticationMetaData.type === "AUTH_0")
          {
-            /////////////////////////////////////////
-            // use auth0 if auth type is ... auth0 //
-            /////////////////////////////////////////
-            try
-            {
-               console.log("Loading token from auth0...");
-               const accessToken = await getAccessTokenSilently();
-
-               const lsAccessToken = localStorage.getItem("accessToken");
-               if (shouldStoreNewToken(accessToken, lsAccessToken))
-               {
-                  console.log("Sending accessToken to backend, requesting a sessionUUID...");
-                  const {uuid: newSessionUuid, values} = await qController.manageSession(accessToken, null);
-
-                  /////////////////////////////////////////////////////////////////////////////////////////////////////////////
-                  // the request to the backend should send a header to set the cookie, so we don't need to do it ourselves. //
-                  /////////////////////////////////////////////////////////////////////////////////////////////////////////////
-                  // setCookie(SESSION_UUID_COOKIE_NAME, newSessionUuid, {path: "/"});
-
-                  localStorage.setItem("accessToken", accessToken);
-                  localStorage.setItem("sessionValues", JSON.stringify(values));
-                  console.log("Got new sessionUUID from backend, and stored new accessToken");
-               }
-               else
-               {
-                  console.log("Using existing sessionUUID cookie");
-               }
-
-               setIsFullyAuthenticated(true);
-               qController.setGotAuthentication();
-
-               setLoggedInUser(user);
-               console.log("Token load complete.");
-            }
-            catch (e)
-            {
-               console.log(`Error loading token: ${JSON.stringify(e)}`);
-               qController.clearAuthenticationMetaDataLocalStorage();
-               localStorage.removeItem("accessToken");
-               removeCookie(SESSION_UUID_COOKIE_NAME, {path: "/"});
-               logout();
-               return;
-            }
+            await auth0SetupSession();
+         }
+         else if (authenticationMetaData.type === "OAUTH2")
+         {
+            await oauth2SetupSession();
          }
          else if (authenticationMetaData.type === "FULLY_ANONYMOUS" || authenticationMetaData.type === "MOCK")
          {
-            /////////////////////////////////////////////
-            // use a random token if anonymous or mock //
-            /////////////////////////////////////////////
-            console.log("Generating random token...");
-            setIsFullyAuthenticated(true);
-            qController.setGotAuthentication();
-            setCookie(SESSION_UUID_COOKIE_NAME, Md5.hashStr(`${new Date()}`), {path: "/"});
-            console.log("Token generation complete.");
-            return;
+            await anonymousSetupSession();
          }
          else
          {
@@ -219,13 +131,36 @@ export default function App()
       (async () =>
       {
          const metaData: QInstance = await qController.loadMetaData();
-         LicenseInfo.setLicenseKey(metaData.environmentValues.get("MATERIAL_UI_LICENSE_KEY") || process.env.REACT_APP_MATERIAL_UI_LICENSE_KEY);
+         LicenseInfo.setLicenseKey(metaData.environmentValues?.get("MATERIAL_UI_LICENSE_KEY") || process.env.REACT_APP_MATERIAL_UI_LICENSE_KEY);
          setNeedLicenseKey(false);
       })();
    }
 
+   /***************************************************************************
+    ** call appropriate logout function based on authentication meta data type
+    ***************************************************************************/
+   function doLogout()
+   {
+      if (authenticationMetaData?.type === "AUTH_0")
+      {
+         auth0Logout();
+      }
+      else if (authenticationMetaData?.type === "OAUTH2")
+      {
+         oauth2Logout();
+      }
+      else if (authenticationMetaData?.type === "FULLY_ANONYMOUS" || authenticationMetaData?.type === "MOCK")
+      {
+         anonymousLogout();
+      }
+      else
+      {
+         console.log(`No logout callback for authentication type [${authenticationMetaData?.type}].`);
+      }
+   }
+
    const [controller, dispatch] = useMaterialUIController();
-   const {miniSidenav, direction, layout, openConfigurator, sidenavColor} = controller;
+   const {miniSidenav, direction, sidenavColor} = controller;
    const [onMouseEnter, setOnMouseEnter] = useState(false);
    const {pathname} = useLocation();
    const [queryParams] = useSearchParams();
@@ -392,6 +327,13 @@ export default function App()
                   component: <RecordView table={table} />,
                });
 
+               routeList.push({
+                  name: `${app.label} View`,
+                  key: `${app.name}.view`,
+                  route: `${path}/key`,
+                  component: <RecordViewByUniqueKey table={table} />,
+               });
+
                routeList.push({
                   name: `${app.label}`,
                   key: `${app.name}.edit`,
@@ -435,23 +377,57 @@ export default function App()
                   });
                });
 
-               const runRecordScriptProcess = metaData.processes.get("runRecordScript");
-               if (runRecordScriptProcess)
+               const materialDashboardInstanceMetaData = metaData.supplementalInstanceMetaData?.get("materialDashboard");
+               if (materialDashboardInstanceMetaData)
                {
-                  const process = runRecordScriptProcess;
-                  routeList.push({
-                     name: process.label,
-                     key: process.name,
-                     route: `${path}/${process.name}`,
-                     component: <RecordQuery table={table} key={`${table.name}-${process.name}`} launchProcess={process} />,
-                  });
+                  const processNamesToAddToAllQueryAndViewScreens = materialDashboardInstanceMetaData.processNamesToAddToAllQueryAndViewScreens;
+                  if (processNamesToAddToAllQueryAndViewScreens)
+                  {
+                     for (let processName of processNamesToAddToAllQueryAndViewScreens)
+                     {
+                        const process = metaData.processes.get(processName);
+                        if (process)
+                        {
+                           routeList.push({
+                              name: process.label,
+                              key: process.name,
+                              route: `${path}/${process.name}`,
+                              component: <RecordQuery table={table} key={`${table.name}-${process.name}`} launchProcess={process} />,
+                           });
 
-                  routeList.push({
-                     name: process.label,
-                     key: `${app.name}/${process.name}`,
-                     route: `${path}/:id/${process.name}`,
-                     component: <RecordView table={table} launchProcess={process} />,
-                  });
+                           routeList.push({
+                              name: process.label,
+                              key: `${app.name}/${process.name}`,
+                              route: `${path}/:id/${process.name}`,
+                              component: <RecordView table={table} launchProcess={process} />,
+                           });
+                        }
+                     }
+                  }
+               }
+               else
+               {
+                  ////////////////
+                  // deprecated //
+                  ////////////////
+                  const runRecordScriptProcess = metaData.processes.get("runRecordScript");
+                  if (runRecordScriptProcess)
+                  {
+                     const process = runRecordScriptProcess;
+                     routeList.push({
+                        name: process.label,
+                        key: process.name,
+                        route: `${path}/${process.name}`,
+                        component: <RecordQuery table={table} key={`${table.name}-${process.name}`} launchProcess={process} />,
+                     });
+
+                     routeList.push({
+                        name: process.label,
+                        key: `${app.name}/${process.name}`,
+                        route: `${path}/:id/${process.name}`,
+                        component: <RecordView table={table} launchProcess={process} />,
+                     });
+                  }
                }
 
                const reportsForTable = ProcessUtils.getReportsForTable(metaData, table.name, true);
@@ -511,11 +487,10 @@ export default function App()
                }
             }
 
-            let profileRoutes = {};
             const gravatarBase = "https://www.gravatar.com/avatar/";
             const hash = Md5.hashStr(loggedInUser?.email || "user");
             const profilePicture = `${gravatarBase}${hash}`;
-            profileRoutes = {
+            const profileRoutes = {
                type: "collapse",
                name: loggedInUser?.name ?? "Anonymous",
                key: "username",
@@ -584,10 +559,7 @@ export default function App()
                   localStorage.removeItem("accessToken");
                   removeCookie(SESSION_UUID_COOKIE_NAME, {path: "/"});
 
-                  //////////////////////////////////////////////////////
-                  // todo - this is auth0 logout... make more generic //
-                  //////////////////////////////////////////////////////
-                  logout();
+                  doLogout();
                   return;
                }
             }
@@ -595,7 +567,9 @@ export default function App()
       })();
    }, [needToLoadRoutes, isFullyAuthenticated]);
 
-   // Open sidenav when mouse enter on mini sidenav
+   ///////////////////////////////////////////////////
+   // Open sidenav when mouse enter on mini sidenav //
+   ///////////////////////////////////////////////////
    const handleOnMouseEnter = () =>
    {
       if (miniSidenav && !onMouseEnter)
@@ -605,7 +579,9 @@ export default function App()
       }
    };
 
-   // Close sidenav when mouse leave mini sidenav
+   /////////////////////////////////////////////////
+   // Close sidenav when mouse leave mini sidenav //
+   /////////////////////////////////////////////////
    const handleOnMouseLeave = () =>
    {
       if (onMouseEnter)
@@ -615,16 +591,14 @@ export default function App()
       }
    };
 
-   // Change the openConfigurator state
-   const handleConfiguratorOpen = () => setOpenConfigurator(dispatch, !openConfigurator);
-
-   // Setting the dir attribute for the body element
    useEffect(() =>
    {
       document.body.setAttribute("dir", direction);
    }, [direction]);
 
-   // Setting page scroll to 0 when changing the route
+   //////////////////////////////////////////////////////
+   // Setting page scroll to 0 when changing the route //
+   //////////////////////////////////////////////////////
    useEffect(() =>
    {
       document.documentElement.scrollTop = 0;
@@ -664,14 +638,14 @@ export default function App()
    const [dotMenuOpen, setDotMenuOpen] = useState(false);
    const [keyboardHelpOpen, setKeyboardHelpOpen] = useState(false);
    const [helpHelpActive] = useState(queryParams.has("helpHelp"));
-   const [userId, setUserId] = useState(user?.email);
+   const [userId, setUserId] = useState(loggedInUser?.email);
 
    useEffect(() =>
    {
-      setUserId(user?.email)
-   }, [user]);
+      setUserId(loggedInUser?.email);
+   }, [loggedInUser]);
+
 
-   
    const [googleAnalyticsUtils] = useState(new GoogleAnalyticsUtils());
 
    /*******************************************************************************
@@ -679,9 +653,35 @@ export default function App()
     *******************************************************************************/
    function recordAnalytics(model: AnalyticsModel)
    {
-      googleAnalyticsUtils.recordAnalytics(model)
+      googleAnalyticsUtils.recordAnalytics(model);
    }
 
+   ///////////////////////////////////////////////////////////////////
+   // if any of the auth/session setup code determined that we need //
+   // to render something and return early - then do so here.       //
+   ///////////////////////////////////////////////////////////////////
+   if (earlyReturnForAuth)
+   {
+      return (earlyReturnForAuth);
+   }
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   function banner(): JSX.Element | null
+   {
+      const banner = getBanner(metaData?.branding, "QFMD_TOP_OF_SITE");
+
+      if (!banner)
+      {
+         return (null);
+      }
+
+      return (<Box className={getBannerClassName(banner)} sx={{display: "flex", justifyContent: "center", padding: "0.5rem", position: "sticky", top: "0", zIndex: 1, ...getBannerStyles(banner)}}>
+         {makeBannerContent(banner)}
+      </Box>);
+   }
 
    return (
 
@@ -710,6 +710,7 @@ export default function App()
             <ThemeProvider theme={theme}>
                <CssBaseline />
                <CommandMenu metaData={metaData} />
+               {banner()}
                <Sidenav
                   color={sidenavColor}
                   icon={branding.icon}
@@ -719,6 +720,7 @@ export default function App()
                   routes={sideNavRoutes}
                   onMouseEnter={handleOnMouseEnter}
                   onMouseLeave={handleOnMouseLeave}
+                  logout={doLogout}
                />
                <Routes>
                   <Route path="*" element={<Navigate to={defaultRoute} />} />

src/CommandMenu.tsx

@@ -36,7 +36,7 @@ import Icon from "@mui/material/Icon";
 import Typography from "@mui/material/Typography";
 import {makeStyles} from "@mui/styles";
 import {Command} from "cmdk";
-import React, {useContext, useEffect, useRef} from "react";
+import React, {useContext, useEffect, useRef, useState} from "react";
 import {useNavigate} from "react-router-dom";
 import QContext from "QContext";
 import HistoryUtils, {QHistoryEntry} from "qqq/utils/HistoryUtils";
@@ -62,16 +62,21 @@ const useStyles = makeStyles((theme: any) => ({
    }
 }));
 
+const A_FIRST = -1;
+const B_FIRST = 1;
+
 const CommandMenu = ({metaData}: Props) =>
 {
+   const [searchString, setSearchString] = useState("");
+
    const navigate = useNavigate();
    const pathParts = location.pathname.replace(/\/+$/, "").split("/");
 
-   const {accentColor, tableMetaData, dotMenuOpen, setDotMenuOpen, keyboardHelpOpen, setKeyboardHelpOpen, setTableMetaData, tableProcesses} = useContext(QContext);
+   const {accentColor, tableMetaData, dotMenuOpen, setDotMenuOpen, keyboardHelpOpen, setKeyboardHelpOpen, setTableMetaData, tableProcesses, recordAnalytics} = useContext(QContext);
 
    const classes = useStyles();
 
-   function evalueKeyPress(e: KeyboardEvent)
+   function evaluateKeyPress(e: KeyboardEvent)
    {
       ///////////////////////////////////////////////////////////////////////////
       // if a dot pressed, not from a "text" element, then toggle command menu //
@@ -82,6 +87,7 @@ const CommandMenu = ({metaData}: Props) =>
          if (e.key === "." && !keyboardHelpOpen)
          {
             e.preventDefault();
+            recordAnalytics({category: "globalEvents", action: "dotMenuKeyboardShortcut"});
             setDotMenuOpen(true);
          }
          else if (e.key === "?" && !dotMenuOpen)
@@ -107,20 +113,20 @@ const CommandMenu = ({metaData}: Props) =>
 
       const down = (e: KeyboardEvent) =>
       {
-         evalueKeyPress(e);
-      }
+         evaluateKeyPress(e);
+      };
 
-      document.addEventListener("keydown", down)
+      document.addEventListener("keydown", down);
       return () =>
       {
-         document.removeEventListener("keydown", down)
-      }
-   }, [tableMetaData, dotMenuOpen, keyboardHelpOpen])
+         document.removeEventListener("keydown", down);
+      };
+   }, [tableMetaData, dotMenuOpen, keyboardHelpOpen]);
 
    useEffect(() =>
    {
       setDotMenuOpen(false);
-   }, [location.pathname])
+   }, [location.pathname]);
 
    function goToItem(path: string)
    {
@@ -162,73 +168,117 @@ const CommandMenu = ({metaData}: Props) =>
       return (null);
    }
 
+
+   /*******************************************************************************
+    ** sort a section (e.g, tables, apps).
+    **
+    ** put labels that start-with the search word first.
+    *******************************************************************************/
+   function comparator(labelA: string, labelB: string)
+   {
+      if (searchString != "")
+      {
+         let aStartsWith = labelA.toLowerCase().startsWith(searchString.toLowerCase());
+         let bStartsWith = labelB.toLowerCase().startsWith(searchString.toLowerCase());
+
+         if (aStartsWith && !bStartsWith)
+         {
+            return A_FIRST;
+         }
+         else if (bStartsWith && !aStartsWith)
+         {
+            return B_FIRST;
+         }
+
+         const indexOfSpace = searchString.indexOf(" ");
+         if (indexOfSpace > 0)
+         {
+            aStartsWith = labelA.toLowerCase().startsWith(searchString.substring(0, indexOfSpace).toLowerCase());
+            bStartsWith = labelB.toLowerCase().startsWith(searchString.substring(0, indexOfSpace).toLowerCase());
+
+            if (aStartsWith && !bStartsWith)
+            {
+               return A_FIRST;
+            }
+            else if (bStartsWith && !aStartsWith)
+            {
+               return B_FIRST;
+            }
+         }
+      }
+
+      return (labelA.localeCompare(labelB));
+   }
+
+
    /*******************************************************************************
     **
     *******************************************************************************/
    function ActionsSection()
    {
-      let tableNames : string[]= [];
+      let tableNames: string[] = [];
       metaData.tables.forEach((value: QTableMetaData, key: string) =>
       {
          tableNames.push(value.name);
-      })
-      tableNames = tableNames.sort((a: string, b:string) =>
+      });
+      tableNames = tableNames.sort((a: string, b: string) =>
       {
          const labelA = metaData.tables.get(a).label ?? "";
          const labelB = metaData.tables.get(b).label ?? "";
-         return (labelA.localeCompare(labelB));
-      })
+         return comparator(labelA, labelB);
+      });
 
       const path = location.pathname;
-      return tableMetaData && !path.endsWith("/edit") && !path.endsWith("/create") && !path.endsWith("#audit") && ! path.endsWith("copy") &&
+      return tableMetaData && !path.endsWith("/edit") && !path.endsWith("/create") && !path.endsWith("#audit") && !path.endsWith("copy") &&
          (
             <Command.Group heading={`${tableMetaData.label} Actions`}>
                {
                   tableMetaData.capabilities.has(Capability.TABLE_INSERT) && tableMetaData.insertPermission &&
-               <Command.Item onSelect={() => goToItem(`${pathParts.slice(0, -1).join("/")}/create`)} key={`${tableMetaData.label}-new`} value="New"><Icon sx={{color: accentColor}}>add</Icon>New</Command.Item>
+                  <Command.Item onSelect={() => goToItem(`${pathParts.slice(0, -1).join("/")}/create`)} key={`${tableMetaData.label}-new`} value="New"><Icon sx={{color: accentColor}}>add</Icon>New</Command.Item>
                }
                {
                   tableMetaData.capabilities.has(Capability.TABLE_INSERT) && tableMetaData.insertPermission &&
-               <Command.Item onSelect={() => goToItem(`${pathParts.join("/")}/copy`)} key={`${tableMetaData.label}-copy`} value="Copy"><Icon sx={{color: accentColor}}>copy</Icon>Copy</Command.Item>
+                  <Command.Item onSelect={() => goToItem(`${pathParts.join("/")}/copy`)} key={`${tableMetaData.label}-copy`} value="Copy"><Icon sx={{color: accentColor}}>copy</Icon>Copy</Command.Item>
                }
                {
                   tableMetaData.capabilities.has(Capability.TABLE_UPDATE) && tableMetaData.editPermission &&
-               <Command.Item onSelect={() => goToItem(`${pathParts.join("/")}/edit`)} key={`${tableMetaData.label}-edit`} value="Edit"><Icon sx={{color: accentColor}}>edit</Icon>Edit</Command.Item>
+                  <Command.Item onSelect={() => goToItem(`${pathParts.join("/")}/edit`)} key={`${tableMetaData.label}-edit`} value="Edit"><Icon sx={{color: accentColor}}>edit</Icon>Edit</Command.Item>
                }
                {
                   metaData && metaData.tables.has("audit") &&
-               <Command.Item onSelect={() => goToItem(`${pathParts.join("/")}#audit`)} key={`${tableMetaData.label}-audit`} value="Audit"><Icon sx={{color: accentColor}}>checklist</Icon>Audit</Command.Item>
+                  <Command.Item onSelect={() => goToItem(`${pathParts.join("/")}#audit`)} key={`${tableMetaData.label}-audit`} value="Audit"><Icon sx={{color: accentColor}}>checklist</Icon>Audit</Command.Item>
                }
                {
                   tableProcesses && tableProcesses.length > 0 &&
-               (
-                  tableProcesses.map((process) => (
-                     <Command.Item onSelect={() => goToItem(`${pathParts.join("/")}/${process.name}`)} key={`${process.name}`} value={`${process.label}`}><Icon sx={{color: accentColor}}>{getIconName(process.iconName, "play_arrow")}</Icon>{process.label}</Command.Item>
-                  ))
-               )
+                  (
+                     tableProcesses.map((process) => (
+                        <Command.Item onSelect={() => goToItem(`${pathParts.join("/")}/${process.name}`)} key={`${process.name}`} value={`${process.label}`}><Icon sx={{color: accentColor}}>{getIconName(process.iconName, "play_arrow")}</Icon>{process.label}</Command.Item>
+                     ))
+                  )
                }
                <Command.Separator />
             </Command.Group>
          );
    }
 
+
    /*******************************************************************************
     **
     *******************************************************************************/
    function TablesSection()
    {
-      let tableNames : string[]= [];
+      let tableNames: string[] = [];
       metaData.tables.forEach((value: QTableMetaData, key: string) =>
       {
          tableNames.push(value.name);
-      })
-      tableNames = tableNames.sort((a: string, b:string) =>
+      });
+      tableNames = tableNames.sort((a: string, b: string) =>
       {
          const labelA = metaData.tables.get(a).label ?? "";
          const labelB = metaData.tables.get(b).label ?? "";
-         return (labelA.localeCompare(labelB));
-      })
-      return(
+         return comparator(labelA, labelB);
+      });
+      return (
          <Command.Group heading="Tables">
             {
                tableNames.map((tableName: string, index: number) =>
@@ -243,6 +293,7 @@ const CommandMenu = ({metaData}: Props) =>
       );
    }
 
+
    /*******************************************************************************
     **
     *******************************************************************************/
@@ -252,16 +303,16 @@ const CommandMenu = ({metaData}: Props) =>
       metaData.apps.forEach((value: QAppMetaData, key: string) =>
       {
          appNames.push(value.name);
-      })
+      });
 
-      appNames = appNames.sort((a: string, b:string) =>
+      appNames = appNames.sort((a: string, b: string) =>
       {
          const labelA = getFullAppLabel(metaData.appTree, a, 1, "") ?? "";
          const labelB = getFullAppLabel(metaData.appTree, b, 1, "") ?? "";
-         return (labelA.localeCompare(labelB));
-      })
+         return comparator(labelA, labelB);
+      });
 
-      return(
+      return (
          <Command.Group heading="Apps">
             {
                appNames.map((appName: string, index: number) =>
@@ -276,33 +327,37 @@ const CommandMenu = ({metaData}: Props) =>
       );
    }
 
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
    function RecentlyViewedSection()
    {
       const history = HistoryUtils.get();
       const options = [] as any;
       history.entries.reverse().forEach((entry, index) =>
          options.push({label: `${entry.label} index`, id: index, key: index, path: entry.path, iconName: entry.iconName})
-      )
+      );
 
       let appNames: string[] = [];
       metaData.apps.forEach((value: QAppMetaData, key: string) =>
       {
          appNames.push(value.name);
-      })
+      });
 
-      appNames = appNames.sort((a: string, b:string) =>
+      appNames = appNames.sort((a: string, b: string) =>
       {
          const labelA = metaData.apps.get(a).label ?? "";
          const labelB = metaData.apps.get(b).label ?? "";
-         return (labelA.localeCompare(labelB));
-      })
+         return comparator(labelA, labelB);
+      });
 
       const entryMap = new Map<string, boolean>();
-      return(
+      return (
          <Command.Group heading="Recently Viewed Records">
             {
                history.entries.reverse().map((entry: QHistoryEntry, index: number) =>
-                  ! entryMap.has(entry.label) && entryMap.set(entry.label, true) && (
+                  !entryMap.has(entry.label) && entryMap.set(entry.label, true) && (
                      <Command.Item onSelect={() => goToItem(`${entry.path}`)} key={`${entry.label}-${index}`} value={entry.label}><Icon sx={{color: accentColor}}>{entry.iconName}</Icon>{entry.label}</Command.Item>
                   )
                )
@@ -311,29 +366,101 @@ const CommandMenu = ({metaData}: Props) =>
       );
    }
 
-   const containerElement = useRef(null)
+   const containerElement = useRef(null);
 
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
    function closeKeyboardHelp()
    {
       setKeyboardHelpOpen(false);
    }
 
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
    function closeDotMenu()
    {
       setDotMenuOpen(false);
    }
 
+
+   /*******************************************************************************
+    ** filter function for cmd-k library
+    **
+    *******************************************************************************/
+   function doFilter(value: string, search: string)
+   {
+      setSearchString(search);
+
+      /////////////////////
+      // split on spaces //
+      /////////////////////
+      const searchParts = search.toLowerCase().split(" ");
+      if (searchParts.length == 1)
+      {
+         //////////////////////////////////////////////
+         // if only 1 word, just do an includes test //
+         //////////////////////////////////////////////
+         return (value.toLowerCase().includes(search.toLowerCase()) ? 1 : 0);
+      }
+      else
+      {
+         ////////////////////////////////////////
+         // else split the value on spaces too //
+         ////////////////////////////////////////
+         const valueParts = value.toLowerCase().split(" ");
+         if (searchParts.length > valueParts.length)
+         {
+            //////////////////////////////////////////////////////////////////////////////////
+            // if there are more words in the search than in the value, then it can't match //
+            // e.g. "order c" can't ever match, say "order"                                 //
+            //////////////////////////////////////////////////////////////////////////////////
+            return (0);
+         }
+
+         /////////////////////////////////////////////////////////////////////////////////////////////////////////////
+         // iterate over the search parts - if any don't match the corresponding value parts, then it's a non-match //
+         /////////////////////////////////////////////////////////////////////////////////////////////////////////////
+         let valueIndex = 0;
+         for (let i = 0; i < searchParts.length; i++)
+         {
+            let foundMatch = false;
+            for (; valueIndex < valueParts.length; valueIndex++)
+            {
+               if (valueParts[valueIndex].includes(searchParts[i]))
+               {
+                  foundMatch = true;
+                  break;
+               }
+            }
+
+            if (!foundMatch)
+            {
+               return (0);
+            }
+         }
+
+         /////////////////////////////////
+         // if no failure, return a hit //
+         /////////////////////////////////
+         return (1);
+      }
+   }
+
    return (
       <React.Fragment>
          <Box ref={containerElement} className="raycast" sx={{position: "relative", zIndex: 10_000}}>
             {
                <Dialog open={dotMenuOpen} onClose={closeDotMenu}>
-                  <Command.Dialog open={dotMenuOpen} onOpenChange={setDotMenuOpen} container={containerElement.current} label="Test Global Command Menu">
+                  <Command.Dialog open={dotMenuOpen} onOpenChange={setDotMenuOpen} container={containerElement.current} filter={(value, search) => doFilter(value, search)}>
                      <Box sx={{display: "flex"}}>
-                        <Command.Input placeholder="Search for Tables, Actions, or Recently Viewed Items..."/>
+                        <Command.Input placeholder="Search for Tables, Actions, or Recently Viewed Items..." />
                         <Button onClick={closeDotMenu}><Icon>close</Icon></Button>
                      </Box>
-                     <Command.Loading  />
+                     <Command.Loading />
                      <Command.Separator />
                      <Command.List>
                         <Command.Empty>No results found.</Command.Empty>
@@ -381,6 +508,6 @@ const CommandMenu = ({metaData}: Props) =>
             </Dialog>
          }
       </React.Fragment>
-   )
-}
+   );
+};
 export default CommandMenu;

src/index.tsx

@@ -19,116 +19,104 @@
  * along with this program.  If not, see <https://www.gnu.org/licenses/>.
  */
 
-import {Auth0Provider} from "@auth0/auth0-react";
 import {QAuthenticationMetaData} from "@kingsrook/qqq-frontend-core/lib/model/metaData/QAuthenticationMetaData";
 import React from "react";
+import ReactDOM from "react-dom";
 import {createRoot} from "react-dom/client";
 import {BrowserRouter, useNavigate, useSearchParams} from "react-router-dom";
 import App from "App";
 import "qqq/styles/qqq-override-styles.css";
 import "qqq/styles/globals.scss";
 import "qqq/styles/raycast.scss";
-import HandleAuthorizationError from "HandleAuthorizationError";
-import ProtectedRoute from "qqq/authorization/auth0/ProtectedRoute";
+import useAnonymousAuthenticationModule from "qqq/authorization/anonymous/useAnonymousAuthenticationModule";
+import useAuth0AuthenticationModule from "qqq/authorization/auth0/useAuth0AuthenticationModule";
+import useOAuth2AuthenticationModule from "qqq/authorization/oauth2/useOAuth2AuthenticationModule";
 import {MaterialUIControllerProvider} from "qqq/context";
 import Client from "qqq/utils/qqq/Client";
 
+
+/////////////////////////////////////////////////////////////////////////////////
+// Expose React and ReactDOM as globals, for use by dynamically loaded modules //
+/////////////////////////////////////////////////////////////////////////////////
+(window as any).React = React;
+(window as any).ReactDOM = ReactDOM;
+
 const qController = Client.getInstance();
 
-if(document.location.search && document.location.search.indexOf("clearAuthenticationMetaDataLocalStorage") > -1)
+if (document.location.search && document.location.search.indexOf("clearAuthenticationMetaDataLocalStorage") > -1)
 {
-   qController.clearAuthenticationMetaDataLocalStorage()
+   qController.clearAuthenticationMetaDataLocalStorage();
 }
 
-const authenticationMetaDataPromise: Promise<QAuthenticationMetaData> = qController.getAuthenticationMetaData()
+const authenticationMetaDataPromise: Promise<QAuthenticationMetaData> = qController.getAuthenticationMetaData();
 
 authenticationMetaDataPromise.then((authenticationMetaData) =>
 {
-   // @ts-ignore
-   function Auth0ProviderWithRedirectCallback({children, ...props})
-   {
-      const navigate = useNavigate();
-      const [searchParams] = useSearchParams();
 
-      // @ts-ignore
-      const onRedirectCallback = (appState) =>
-      {
-         navigate((appState && appState.returnTo) || window.location.pathname);
-      };
-      if (searchParams.get("error"))
-      {
-         return (
-            // @ts-ignore
-            <Auth0Provider {...props}>
-               <HandleAuthorizationError errorMessage={searchParams.get("error_description")} />
-            </Auth0Provider>
-         );
-      }
-      else
-      {
-         return (
-            // @ts-ignore
-            <Auth0Provider onRedirectCallback={onRedirectCallback} {...props}>
-               {children}
-            </Auth0Provider>
-         );
-      }
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   function Auth0RouterBody()
+   {
+      const {renderAppWrapper} = useAuth0AuthenticationModule({});
+      return (renderAppWrapper(authenticationMetaData));
    }
 
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   function OAuth2RouterBody()
+   {
+      const {renderAppWrapper} = useOAuth2AuthenticationModule({inOAuthContext: false});
+      return (renderAppWrapper(authenticationMetaData, (
+         <MaterialUIControllerProvider>
+            <App authenticationMetaData={authenticationMetaData} />
+         </MaterialUIControllerProvider>
+      )));
+   }
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   function AnonymousRouterBody()
+   {
+      const {renderAppWrapper} = useAnonymousAuthenticationModule({});
+      return (renderAppWrapper(authenticationMetaData, (
+         <MaterialUIControllerProvider>
+            <App authenticationMetaData={authenticationMetaData} />
+         </MaterialUIControllerProvider>
+      )));
+   }
+
+
    const container = document.getElementById("root");
    const root = createRoot(container);
 
    if (authenticationMetaData.type === "AUTH_0")
    {
-      // @ts-ignore
-      let domain: string = authenticationMetaData.data.baseUrl;
-
-      // @ts-ignore
-      const clientId = authenticationMetaData.data.clientId;
-
-      // @ts-ignore
-      const audience = authenticationMetaData.data.audience;
-
-      if(!domain || !clientId)
-      {
-         root.render(
-            <div>Error:  AUTH0 authenticationMetaData is missing domain [{domain}] and/or clientId [{clientId}].</div>
-         );
-         return;
-      }
-
-      if(domain.endsWith("/"))
-      {
-         /////////////////////////////////////////////////////////////////////////////////////
-         // auth0 lib fails if we have a trailing slash.  be a bit more graceful than that. //
-         /////////////////////////////////////////////////////////////////////////////////////
-         domain = domain.replace(/\/$/, "");
-      }
-
-      root.render(
-         <BrowserRouter>
-            <Auth0ProviderWithRedirectCallback
-               domain={domain}
-               clientId={clientId}
-               audience={audience}
-               redirectUri={`${window.location.origin}/`}
-            >
-               <MaterialUIControllerProvider>
-                  <ProtectedRoute component={App} />
-               </MaterialUIControllerProvider>
-            </Auth0ProviderWithRedirectCallback>
-         </BrowserRouter>
-      );
+      root.render(<BrowserRouter>
+         <Auth0RouterBody />
+      </BrowserRouter>);
+   }
+   else if (authenticationMetaData.type === "OAUTH2")
+   {
+      root.render(<BrowserRouter>
+         <OAuth2RouterBody />
+      </BrowserRouter>);
+   }
+   else if (authenticationMetaData.type === "FULLY_ANONYMOUS" || authenticationMetaData.type === "MOCK")
+   {
+      root.render(<BrowserRouter>
+         <AnonymousRouterBody />
+      </BrowserRouter>);
    }
    else
    {
-      root.render(
-         <BrowserRouter>
-            <MaterialUIControllerProvider>
-               <App />
-            </MaterialUIControllerProvider>
-         </BrowserRouter>
-      );
+      root.render(<div>
+         Error: Unknown authenticationMetaData type: [{authenticationMetaData.type}].
+      </div>);
    }
 
-})
+});

src/main/java/com/kingsrook/qqq/frontend/materialdashboard/actions/formadjuster/FormAdjusterInput.java

@@ -0,0 +1,164 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+package com.kingsrook.qqq.frontend.materialdashboard.actions.formadjuster;
+
+
+import java.io.Serializable;
+import java.util.Map;
+
+
+/*******************************************************************************
+ **
+ *******************************************************************************/
+public class FormAdjusterInput
+{
+   private String event;
+   private String fieldName;
+
+   private Serializable              newValue;
+   private Map<String, Serializable> allValues;
+
+
+
+   /*******************************************************************************
+    ** Getter for event
+    *******************************************************************************/
+   public String getEvent()
+   {
+      return (this.event);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for event
+    *******************************************************************************/
+   public void setEvent(String event)
+   {
+      this.event = event;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for event
+    *******************************************************************************/
+   public FormAdjusterInput withEvent(String event)
+   {
+      this.event = event;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for fieldName
+    *******************************************************************************/
+   public String getFieldName()
+   {
+      return (this.fieldName);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for fieldName
+    *******************************************************************************/
+   public void setFieldName(String fieldName)
+   {
+      this.fieldName = fieldName;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for fieldName
+    *******************************************************************************/
+   public FormAdjusterInput withFieldName(String fieldName)
+   {
+      this.fieldName = fieldName;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for newValue
+    *******************************************************************************/
+   public Serializable getNewValue()
+   {
+      return (this.newValue);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for newValue
+    *******************************************************************************/
+   public void setNewValue(Serializable newValue)
+   {
+      this.newValue = newValue;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for newValue
+    *******************************************************************************/
+   public FormAdjusterInput withNewValue(Serializable newValue)
+   {
+      this.newValue = newValue;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for allValues
+    *******************************************************************************/
+   public Map<String, Serializable> getAllValues()
+   {
+      return (this.allValues);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for allValues
+    *******************************************************************************/
+   public void setAllValues(Map<String, Serializable> allValues)
+   {
+      this.allValues = allValues;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for allValues
+    *******************************************************************************/
+   public FormAdjusterInput withAllValues(Map<String, Serializable> allValues)
+   {
+      this.allValues = allValues;
+      return (this);
+   }
+
+}

src/main/java/com/kingsrook/qqq/frontend/materialdashboard/actions/formadjuster/FormAdjusterInterface.java

@@ -0,0 +1,39 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+package com.kingsrook.qqq.frontend.materialdashboard.actions.formadjuster;
+
+
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+
+
+/*******************************************************************************
+ ** interface to be implemented by application-specific form-adjusters
+ *******************************************************************************/
+public interface FormAdjusterInterface
+{
+
+   /***************************************************************************
+    *
+    ***************************************************************************/
+   FormAdjusterOutput execute(FormAdjusterInput input) throws QException;
+
+}

src/main/java/com/kingsrook/qqq/frontend/materialdashboard/actions/formadjuster/FormAdjusterOutput.java

@@ -0,0 +1,165 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+package com.kingsrook.qqq.frontend.materialdashboard.actions.formadjuster;
+
+
+import java.io.Serializable;
+import java.util.Map;
+import java.util.Set;
+import com.kingsrook.qqq.backend.core.model.metadata.frontend.QFrontendFieldMetaData;
+
+
+/*******************************************************************************
+ **
+ *******************************************************************************/
+public class FormAdjusterOutput
+{
+   private Map<String, QFrontendFieldMetaData> updatedFieldMetaData      = null;
+   private Map<String, Serializable>           updatedFieldValues        = null;
+   private Map<String, String>                 updatedFieldDisplayValues = null;
+   private Set<String>                         fieldsToClear             = null;
+
+
+
+   /*******************************************************************************
+    ** Getter for updatedFieldValues
+    *******************************************************************************/
+   public Map<String, Serializable> getUpdatedFieldValues()
+   {
+      return (this.updatedFieldValues);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for updatedFieldValues
+    *******************************************************************************/
+   public void setUpdatedFieldValues(Map<String, Serializable> updatedFieldValues)
+   {
+      this.updatedFieldValues = updatedFieldValues;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for updatedFieldValues
+    *******************************************************************************/
+   public FormAdjusterOutput withUpdatedFieldValues(Map<String, Serializable> updatedFieldValues)
+   {
+      this.updatedFieldValues = updatedFieldValues;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for fieldsToClear
+    *******************************************************************************/
+   public Set<String> getFieldsToClear()
+   {
+      return (this.fieldsToClear);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for fieldsToClear
+    *******************************************************************************/
+   public void setFieldsToClear(Set<String> fieldsToClear)
+   {
+      this.fieldsToClear = fieldsToClear;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for fieldsToClear
+    *******************************************************************************/
+   public FormAdjusterOutput withFieldsToClear(Set<String> fieldsToClear)
+   {
+      this.fieldsToClear = fieldsToClear;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for updatedFieldMetaData
+    *******************************************************************************/
+   public Map<String, QFrontendFieldMetaData> getUpdatedFieldMetaData()
+   {
+      return (this.updatedFieldMetaData);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for updatedFieldMetaData
+    *******************************************************************************/
+   public void setUpdatedFieldMetaData(Map<String, QFrontendFieldMetaData> updatedFieldMetaData)
+   {
+      this.updatedFieldMetaData = updatedFieldMetaData;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for updatedFieldMetaData
+    *******************************************************************************/
+   public FormAdjusterOutput withUpdatedFieldMetaData(Map<String, QFrontendFieldMetaData> updatedFieldMetaData)
+   {
+      this.updatedFieldMetaData = updatedFieldMetaData;
+      return (this);
+   }
+
+
+   /*******************************************************************************
+    ** Getter for updatedFieldDisplayValues
+    *******************************************************************************/
+   public Map<String, String> getUpdatedFieldDisplayValues()
+   {
+      return (this.updatedFieldDisplayValues);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for updatedFieldDisplayValues
+    *******************************************************************************/
+   public void setUpdatedFieldDisplayValues(Map<String, String> updatedFieldDisplayValues)
+   {
+      this.updatedFieldDisplayValues = updatedFieldDisplayValues;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for updatedFieldDisplayValues
+    *******************************************************************************/
+   public FormAdjusterOutput withUpdatedFieldDisplayValues(Map<String, String> updatedFieldDisplayValues)
+   {
+      this.updatedFieldDisplayValues = updatedFieldDisplayValues;
+      return (this);
+   }
+
+
+}

src/main/java/com/kingsrook/qqq/frontend/materialdashboard/actions/formadjuster/FormAdjusterRegistry.java

@@ -0,0 +1,149 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+package com.kingsrook.qqq.frontend.materialdashboard.actions.formadjuster;
+
+
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import com.kingsrook.qqq.backend.core.actions.customizers.QCodeLoader;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.logging.QLogger;
+import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
+import com.kingsrook.qqq.backend.core.model.metadata.code.QCodeReference;
+import com.kingsrook.qqq.backend.core.utils.ClassPathUtils;
+import com.kingsrook.qqq.backend.javalin.QJavalinMetaData;
+import com.kingsrook.qqq.frontend.materialdashboard.model.metadata.MaterialDashboardFieldMetaData;
+import com.kingsrook.qqq.middleware.javalin.metadata.JavalinRouteProviderMetaData;
+
+
+/*******************************************************************************
+ ** Class that stores code-references for the application's defined fromAdjusters
+ ** This class also, when registering its first formAdjuster, adds the route to
+ ** the javalin instance to service form-adjuster calls from the frontend.
+ *******************************************************************************/
+public class FormAdjusterRegistry
+{
+   private static final QLogger LOG = QLogger.getLogger(FormAdjusterRegistry.class);
+
+   private static boolean   didRegisterRouteProvider = false;
+   private static QInstance lastRegisteredQInstance  = null;
+
+   private static Map<String, QCodeReference> onChangeAdjusters = new HashMap<>();
+   private static Map<String, QCodeReference> onLoadAdjusters   = new HashMap<>();
+
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   public static void registerFormAdjusters(QInstance qInstance, MaterialDashboardFieldMetaData materialDashboardFieldMetaData) throws QException
+   {
+      //////////////////////////////////////////////////////////////////////////////////////////////////////////////
+      // support hot-swaps, by checking if the input qInstance is different from one we previously registered for //
+      //////////////////////////////////////////////////////////////////////////////////////////////////////////////
+      if(didRegisterRouteProvider && lastRegisteredQInstance != qInstance)
+      {
+         didRegisterRouteProvider = false;
+         onChangeAdjusters.clear();
+         onLoadAdjusters.clear();
+      }
+
+      /////////////////////////////////////////////////////////////////////////////////////
+      // if we need to register the javalin router, do so (only once per qInstance)      //
+      // note, javalin is optional dep, so make sure it's available before try to use it //
+      /////////////////////////////////////////////////////////////////////////////////////
+      if(!didRegisterRouteProvider)
+      {
+         if(ClassPathUtils.isClassAvailable(QJavalinMetaData.class.getName()))
+         {
+            QJavalinMetaData javalinMetaData = QJavalinMetaData.ofOrWithNew(qInstance);
+            javalinMetaData.withRouteProvider(new JavalinRouteProviderMetaData()
+               .withHostedPath("/material-dashboard-backend/form-adjuster/{identifier}/{event}")
+               .withMethods(List.of("POST"))
+               .withProcessName(RunFormAdjusterProcess.NAME)
+            );
+
+            qInstance.add(new RunFormAdjusterProcess().produce(qInstance));
+         }
+
+         didRegisterRouteProvider = true;
+         lastRegisteredQInstance = qInstance;
+      }
+
+      ////////////////////////////////////////////////////////////////
+      // add the code-references to the map of registered adjusters //
+      ////////////////////////////////////////////////////////////////
+      String identifier = materialDashboardFieldMetaData.getFormAdjusterIdentifier();
+
+      QCodeReference onChangeCode = materialDashboardFieldMetaData.getOnChangeFormAdjuster();
+      if(onChangeCode != null)
+      {
+         if(onChangeAdjusters.containsKey(identifier))
+         {
+            LOG.warn("Attempt to register more than one onChangeFormAdjuster with identifier: " + identifier);
+         }
+         onChangeAdjusters.put(identifier, onChangeCode);
+      }
+
+      QCodeReference onLoadCode = materialDashboardFieldMetaData.getOnLoadFormAdjuster();
+      if(onLoadCode != null)
+      {
+         if(onLoadAdjusters.containsKey(identifier))
+         {
+            LOG.warn("Attempt to register more than one onLoadFormAdjuster with identifier: " + identifier);
+         }
+         onLoadAdjusters.put(identifier, onLoadCode);
+      }
+   }
+
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   static FormAdjusterInterface getOnChangeAdjuster(String identifier)
+   {
+      QCodeReference codeReference = onChangeAdjusters.get(identifier);
+      if(codeReference != null)
+      {
+         return QCodeLoader.getAdHoc(FormAdjusterInterface.class, codeReference);
+      }
+      return (null);
+   }
+
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   static FormAdjusterInterface getOnLoadAdjuster(String identifier)
+   {
+      QCodeReference codeReference = onLoadAdjusters.get(identifier);
+      if(codeReference != null)
+      {
+         return QCodeLoader.getAdHoc(FormAdjusterInterface.class, codeReference);
+      }
+      return (null);
+   }
+
+}

src/main/java/com/kingsrook/qqq/frontend/materialdashboard/actions/formadjuster/RunFormAdjusterProcess.java

@@ -0,0 +1,123 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+package com.kingsrook.qqq.frontend.materialdashboard.actions.formadjuster;
+
+
+import java.io.Serializable;
+import java.util.Collections;
+import java.util.Map;
+import com.fasterxml.jackson.core.type.TypeReference;
+import com.kingsrook.qqq.backend.core.actions.processes.BackendStep;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.logging.QLogger;
+import com.kingsrook.qqq.backend.core.model.actions.processes.RunBackendStepInput;
+import com.kingsrook.qqq.backend.core.model.actions.processes.RunBackendStepOutput;
+import com.kingsrook.qqq.backend.core.model.metadata.MetaDataProducerInterface;
+import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
+import com.kingsrook.qqq.backend.core.model.metadata.code.QCodeReference;
+import com.kingsrook.qqq.backend.core.model.metadata.permissions.PermissionLevel;
+import com.kingsrook.qqq.backend.core.model.metadata.permissions.QPermissionRules;
+import com.kingsrook.qqq.backend.core.model.metadata.processes.QBackendStepMetaData;
+import com.kingsrook.qqq.backend.core.model.metadata.processes.QProcessMetaData;
+import com.kingsrook.qqq.backend.core.utils.JsonUtils;
+import com.kingsrook.qqq.backend.core.utils.StringUtils;
+import com.kingsrook.qqq.middleware.javalin.routeproviders.ProcessBasedRouterPayload;
+import static com.kingsrook.qqq.backend.core.logging.LogUtils.logPair;
+
+
+/*******************************************************************************
+ ** process that looks up a form adjuster from the registry, and then runs it
+ *******************************************************************************/
+public class RunFormAdjusterProcess implements BackendStep, MetaDataProducerInterface<QProcessMetaData>
+{
+   public static final String NAME = "MaterialDashboardRunFormAdjusterProcess";
+
+   private static final QLogger LOG = QLogger.getLogger(RunFormAdjusterProcess.class);
+
+   public static final String EVENT_ON_LOAD   = "onLoad";
+   public static final String EVENT_ON_CHANGE = "onChange";
+
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   @Override
+   public QProcessMetaData produce(QInstance qInstance) throws QException
+   {
+      return new QProcessMetaData()
+         .withName(NAME)
+         .withPermissionRules(new QPermissionRules().withLevel(PermissionLevel.NOT_PROTECTED))
+         .withStep(new QBackendStepMetaData()
+            .withName("execute")
+            .withCode(new QCodeReference(getClass())));
+   }
+
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   @Override
+   public void run(RunBackendStepInput runBackendStepInput, RunBackendStepOutput runBackendStepOutput) throws QException
+   {
+      ProcessBasedRouterPayload payload = runBackendStepInput.getProcessPayload(ProcessBasedRouterPayload.class);
+
+      String identifier = payload.getPathParams().get("identifier");
+      String event      = payload.getPathParams().get("event");
+
+      try
+      {
+         FormAdjusterInterface formAdjuster = switch(event)
+         {
+            case EVENT_ON_CHANGE -> FormAdjusterRegistry.getOnChangeAdjuster(identifier);
+            case EVENT_ON_LOAD -> FormAdjusterRegistry.getOnLoadAdjuster(identifier);
+            default -> throw new QException("Unknown event type: " + event);
+         };
+
+         if(formAdjuster == null)
+         {
+            throw new QException("No form adjuster found for identifier: " + identifier + " and event: " + event);
+         }
+
+         FormAdjusterInput input = new FormAdjusterInput();
+         input.setEvent(event);
+         input.setFieldName(payload.getFormParam("fieldName"));
+         input.setNewValue(payload.getFormParam("newValue"));
+
+         String                    allValuesJson = payload.getFormParam("allValues");
+         Map<String, Serializable> allValues     = StringUtils.hasContent(allValuesJson) ? JsonUtils.toObject(allValuesJson, new TypeReference<>() {}) : Collections.emptyMap();
+         input.setAllValues(allValues);
+
+         FormAdjusterOutput output = formAdjuster.execute(input);
+
+         payload.setResponseString(JsonUtils.toJson(output));
+         runBackendStepOutput.setProcessPayload(payload);
+      }
+      catch(Exception e)
+      {
+         LOG.warn("Error running form adjuster process", e, logPair("identifier", identifier), logPair("event", event));
+         throw new QException("Error running form adjuster process: " + e.getMessage(), e);
+      }
+   }
+
+}

src/main/java/com/kingsrook/qqq/frontend/materialdashboard/model/metadata/MaterialDashboardBannerSlots.java

@@ -1,6 +1,6 @@
 /*
  * QQQ - Low-code Application Framework for Engineers.
- * Copyright (C) 2021-2022.  Kingsrook, LLC
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
  * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
  * contact@kingsrook.com
  * https://github.com/Kingsrook/
@@ -19,20 +19,18 @@
  * along with this program.  If not, see <https://www.gnu.org/licenses/>.
  */
 
-import {useAuth0} from "@auth0/auth0-react";
-import {Button} from "@mui/material";
-import React from "react";
+package com.kingsrook.qqq.frontend.materialdashboard.model.metadata;
 
-function AuthenticationButton()
+
+import com.kingsrook.qqq.backend.core.model.metadata.branding.BannerSlot;
+
+
+/*******************************************************************************
+ **
+ *******************************************************************************/
+public enum MaterialDashboardBannerSlots implements BannerSlot
 {
-   const {loginWithRedirect, logout, isAuthenticated} = useAuth0();
-
-   if (isAuthenticated)
-   {
-      return <Button onClick={() => logout({returnTo: window.location.origin})}>Log Out</Button>;
-   }
-
-   return <Button onClick={() => loginWithRedirect()}>Log In</Button>;
+   QFMD_TOP_OF_SITE,
+   QFMD_TOP_OF_BODY,
+   QFMD_SIDE_NAV_UNDER_LOGO
 }
-
-export default AuthenticationButton;

src/main/java/com/kingsrook/qqq/frontend/materialdashboard/model/metadata/MaterialDashboardFieldMetaData.java

@@ -0,0 +1,244 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+package com.kingsrook.qqq.frontend.materialdashboard.model.metadata;
+
+
+import java.util.Set;
+import com.kingsrook.qqq.backend.core.instances.QInstanceValidator;
+import com.kingsrook.qqq.backend.core.logging.QLogger;
+import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
+import com.kingsrook.qqq.backend.core.model.metadata.code.QCodeReference;
+import com.kingsrook.qqq.backend.core.model.metadata.fields.QFieldMetaData;
+import com.kingsrook.qqq.backend.core.model.metadata.fields.QSupplementalFieldMetaData;
+import com.kingsrook.qqq.backend.core.utils.StringUtils;
+import com.kingsrook.qqq.frontend.materialdashboard.actions.formadjuster.FormAdjusterInterface;
+import com.kingsrook.qqq.frontend.materialdashboard.actions.formadjuster.FormAdjusterRegistry;
+
+
+/*******************************************************************************
+ **
+ *******************************************************************************/
+public class MaterialDashboardFieldMetaData extends QSupplementalFieldMetaData
+{
+   public static final String TYPE = "materialDashboard";
+
+   private static final QLogger LOG = QLogger.getLogger(MaterialDashboardFieldMetaData.class);
+
+   private String         formAdjusterIdentifier               = null;
+   private QCodeReference onChangeFormAdjuster                 = null;
+   private QCodeReference onLoadFormAdjuster                   = null;
+   private Set<String>    fieldsToDisableWhileRunningAdjusters = null;
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   @Override
+   public boolean includeInFrontendMetaData()
+   {
+      return (true);
+   }
+
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   @Override
+   public String getType()
+   {
+      return TYPE;
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for onChangeFormAdjuster
+    *******************************************************************************/
+   public QCodeReference getOnChangeFormAdjuster()
+   {
+      return (this.onChangeFormAdjuster);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for onChangeFormAdjuster
+    *******************************************************************************/
+   public void setOnChangeFormAdjuster(QCodeReference onChangeFormAdjuster)
+   {
+      this.onChangeFormAdjuster = onChangeFormAdjuster;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for onChangeFormAdjuster
+    *******************************************************************************/
+   public MaterialDashboardFieldMetaData withOnChangeFormAdjuster(QCodeReference onChangeFormAdjuster)
+   {
+      this.onChangeFormAdjuster = onChangeFormAdjuster;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for onLoadFormAdjuster
+    *******************************************************************************/
+   public QCodeReference getOnLoadFormAdjuster()
+   {
+      return (this.onLoadFormAdjuster);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for onLoadFormAdjuster
+    *******************************************************************************/
+   public void setOnLoadFormAdjuster(QCodeReference onLoadFormAdjuster)
+   {
+      this.onLoadFormAdjuster = onLoadFormAdjuster;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for onLoadFormAdjuster
+    *******************************************************************************/
+   public MaterialDashboardFieldMetaData withOnLoadFormAdjuster(QCodeReference onLoadFormAdjuster)
+   {
+      this.onLoadFormAdjuster = onLoadFormAdjuster;
+      return (this);
+   }
+
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   @Override
+   public void enrich(QInstance qInstance, QFieldMetaData fieldMetaData)
+   {
+      try
+      {
+         FormAdjusterRegistry.registerFormAdjusters(qInstance, this);
+      }
+      catch(Exception e)
+      {
+         LOG.warn("Error enriching MaterialDashboardFieldMetaData", e);
+      }
+   }
+
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   @Override
+   public void validate(QInstance qInstance, QFieldMetaData fieldMetaData, QInstanceValidator qInstanceValidator)
+   {
+      String prefix = "MaterialDashboardFieldMetaData for field [" + fieldMetaData.getName() + "]";
+
+      boolean needsFormAdjusterIdentifer = false;
+      if(onChangeFormAdjuster != null)
+      {
+         needsFormAdjusterIdentifer = true;
+         qInstanceValidator.validateSimpleCodeReference(prefix + ", onChangeFormAdjuster", onChangeFormAdjuster, FormAdjusterInterface.class);
+      }
+
+      if(onLoadFormAdjuster != null)
+      {
+         needsFormAdjusterIdentifer = true;
+         qInstanceValidator.validateSimpleCodeReference(prefix + ", onLoadFormAdjuster", onLoadFormAdjuster, FormAdjusterInterface.class);
+      }
+
+      if(needsFormAdjusterIdentifer)
+      {
+         qInstanceValidator.assertCondition(StringUtils.hasContent(formAdjusterIdentifier), prefix + ", formAdjusterIdentifier is required if using any FormAdjusters");
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for formAdjusterIdentifier
+    *******************************************************************************/
+   public String getFormAdjusterIdentifier()
+   {
+      return (this.formAdjusterIdentifier);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for formAdjusterIdentifier
+    *******************************************************************************/
+   public void setFormAdjusterIdentifier(String formAdjusterIdentifier)
+   {
+      this.formAdjusterIdentifier = formAdjusterIdentifier;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for formAdjusterIdentifier
+    *******************************************************************************/
+   public MaterialDashboardFieldMetaData withFormAdjusterIdentifier(String formAdjusterIdentifier)
+   {
+      this.formAdjusterIdentifier = formAdjusterIdentifier;
+      return (this);
+   }
+
+
+   /*******************************************************************************
+    ** Getter for fieldsToDisableWhileRunningAdjusters
+    *******************************************************************************/
+   public Set<String> getFieldsToDisableWhileRunningAdjusters()
+   {
+      return (this.fieldsToDisableWhileRunningAdjusters);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for fieldsToDisableWhileRunningAdjusters
+    *******************************************************************************/
+   public void setFieldsToDisableWhileRunningAdjusters(Set<String> fieldsToDisableWhileRunningAdjusters)
+   {
+      this.fieldsToDisableWhileRunningAdjusters = fieldsToDisableWhileRunningAdjusters;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for fieldsToDisableWhileRunningAdjusters
+    *******************************************************************************/
+   public MaterialDashboardFieldMetaData withFieldsToDisableWhileRunningAdjusters(Set<String> fieldsToDisableWhileRunningAdjusters)
+   {
+      this.fieldsToDisableWhileRunningAdjusters = fieldsToDisableWhileRunningAdjusters;
+      return (this);
+   }
+
+
+}

src/main/java/com/kingsrook/qqq/frontend/materialdashboard/model/metadata/MaterialDashboardInstanceMetaData.java

@@ -0,0 +1,113 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2023.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+package com.kingsrook.qqq.frontend.materialdashboard.model.metadata;
+
+
+import java.util.ArrayList;
+import java.util.List;
+import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
+import com.kingsrook.qqq.backend.core.model.metadata.QSupplementalInstanceMetaData;
+
+
+/*******************************************************************************
+ ** table-level meta-data for this module (handled as QSupplementalTableMetaData)
+ *******************************************************************************/
+public class MaterialDashboardInstanceMetaData implements QSupplementalInstanceMetaData
+{
+   public static final String TYPE = "materialDashboard";
+
+   private List<String> processNamesToAddToAllQueryAndViewScreens = new ArrayList<>();
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   @Override
+   public String getName()
+   {
+      return (TYPE);
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public static MaterialDashboardInstanceMetaData ofOrWithNew(QInstance qInstance)
+   {
+      MaterialDashboardInstanceMetaData supplementalMetaData = (MaterialDashboardInstanceMetaData) qInstance.getSupplementalMetaData(TYPE);
+      if(supplementalMetaData == null)
+      {
+         supplementalMetaData = new MaterialDashboardInstanceMetaData();
+         qInstance.withSupplementalMetaData(supplementalMetaData);
+      }
+
+      return (supplementalMetaData);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for processNamesToAddToAllQueryAndViewScreens
+    *******************************************************************************/
+   public List<String> getProcessNamesToAddToAllQueryAndViewScreens()
+   {
+      return (this.processNamesToAddToAllQueryAndViewScreens);
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public void addProcessNameToAddToAllQueryAndViewScreens(String processNamesToAddToAllQueryAndViewScreens)
+   {
+      if(this.processNamesToAddToAllQueryAndViewScreens == null)
+      {
+         this.processNamesToAddToAllQueryAndViewScreens = new ArrayList<>();
+      }
+      this.processNamesToAddToAllQueryAndViewScreens.add(processNamesToAddToAllQueryAndViewScreens);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for processNamesToAddToAllQueryAndViewScreens
+    *******************************************************************************/
+   public void setProcessNamesToAddToAllQueryAndViewScreens(List<String> processNamesToAddToAllQueryAndViewScreens)
+   {
+      this.processNamesToAddToAllQueryAndViewScreens = processNamesToAddToAllQueryAndViewScreens;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for processNamesToAddToAllQueryAndViewScreens
+    *******************************************************************************/
+   public MaterialDashboardInstanceMetaData withProcessNamesToAddToAllQueryAndViewScreens(List<String> processNamesToAddToAllQueryAndViewScreens)
+   {
+      this.processNamesToAddToAllQueryAndViewScreens = processNamesToAddToAllQueryAndViewScreens;
+      return (this);
+   }
+
+}

src/main/java/com/kingsrook/qqq/frontend/materialdashboard/model/metadata/MaterialDashboardTableMetaData.java

@@ -134,17 +134,36 @@ public class MaterialDashboardTableMetaData extends QSupplementalTableMetaData
 
       for(FieldRule fieldRule : CollectionUtils.nonNullList(fieldRules))
       {
-         qInstanceValidator.assertCondition(fieldRule.getTrigger() != null, prefix + "has a fieldRule without a trigger");
-         qInstanceValidator.assertCondition(fieldRule.getAction() != null, prefix + "has a fieldRule without an action");
+         validateFieldRule(qInstance, tableMetaData, qInstanceValidator, fieldRule, prefix);
+      }
+   }
 
-         if(qInstanceValidator.assertCondition(StringUtils.hasContent(fieldRule.getSourceField()), prefix + "has a fieldRule without a sourceField"))
-         {
-            qInstanceValidator.assertNoException(() -> tableMetaData.getField(fieldRule.getSourceField()), prefix + "has a fieldRule with an unrecognized sourceField: " + fieldRule.getSourceField());
-         }
 
-         if(qInstanceValidator.assertCondition(StringUtils.hasContent(fieldRule.getTargetField()), prefix + "has a fieldRule without a targetField"))
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   static void validateFieldRule(QInstance qInstance, QTableMetaData tableMetaData, QInstanceValidator qInstanceValidator, FieldRule fieldRule, String prefix)
+   {
+      qInstanceValidator.assertCondition(fieldRule.getTrigger() != null, prefix + "has a fieldRule without a trigger");
+      qInstanceValidator.assertCondition(fieldRule.getAction() != null, prefix + "has a fieldRule without an action");
+
+      if(qInstanceValidator.assertCondition(StringUtils.hasContent(fieldRule.getSourceField()), prefix + "has a fieldRule without a sourceField"))
+      {
+         qInstanceValidator.assertNoException(() -> tableMetaData.getField(fieldRule.getSourceField()), prefix + "has a fieldRule with an unrecognized sourceField: " + fieldRule.getSourceField());
+      }
+
+      if(StringUtils.hasContent(fieldRule.getTargetField()))
+      {
+         qInstanceValidator.assertNoException(() -> tableMetaData.getField(fieldRule.getTargetField()), prefix + "has a fieldRule with an unrecognized targetField: " + fieldRule.getTargetField());
+      }
+
+      if(StringUtils.hasContent(fieldRule.getTargetWidget()))
+      {
+         if(qInstanceValidator.assertCondition(qInstance.getWidget(fieldRule.getTargetWidget()) != null, prefix + "has a widgetRule with an unrecognized targetWidget: " + fieldRule.getTargetWidget()))
          {
-            qInstanceValidator.assertNoException(() -> tableMetaData.getField(fieldRule.getTargetField()), prefix + "has a fieldRule with an unrecognized targetField: " + fieldRule.getTargetField());
+            qInstanceValidator.assertCondition(CollectionUtils.nonNullList(tableMetaData.getSections()).stream().anyMatch(s -> fieldRule.getTargetWidget().equals(s.getWidgetName())),
+               prefix + "has a widgetRule with a targetWidget which is not used in any sections on the table");
          }
       }
    }

src/main/java/com/kingsrook/qqq/frontend/materialdashboard/model/metadata/fieldrules/FieldRule.java

@@ -38,6 +38,8 @@ public class FieldRule implements Serializable
    private FieldRuleAction  action;
    private String           targetField;
 
+   private String targetWidget;
+
 
 
    /*******************************************************************************
@@ -162,4 +164,35 @@ public class FieldRule implements Serializable
       return (this);
    }
 
+
+
+   /*******************************************************************************
+    ** Getter for targetWidget
+    *******************************************************************************/
+   public String getTargetWidget()
+   {
+      return (this.targetWidget);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for targetWidget
+    *******************************************************************************/
+   public void setTargetWidget(String targetWidget)
+   {
+      this.targetWidget = targetWidget;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for targetWidget
+    *******************************************************************************/
+   public FieldRule withTargetWidget(String targetWidget)
+   {
+      this.targetWidget = targetWidget;
+      return (this);
+   }
+
 }

src/main/java/com/kingsrook/qqq/frontend/materialdashboard/model/metadata/fieldrules/FieldRuleAction.java

@@ -27,5 +27,6 @@ package com.kingsrook.qqq.frontend.materialdashboard.model.metadata.fieldrules;
  *******************************************************************************/
 public enum FieldRuleAction
 {
-   CLEAR_TARGET_FIELD
+   CLEAR_TARGET_FIELD,
+   RELOAD_WIDGET
 }

src/qqq/authorization/anonymous/useAnonymousAuthenticationModule.tsx

@@ -0,0 +1,82 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+import {QAuthenticationMetaData} from "@kingsrook/qqq-frontend-core/lib/model/metaData/QAuthenticationMetaData";
+import {SESSION_UUID_COOKIE_NAME} from "App";
+import Client from "qqq/utils/qqq/Client";
+import {useCookies} from "react-cookie";
+import {Md5} from "ts-md5/dist/md5";
+
+const qController = Client.getInstance();
+
+interface Props
+{
+   setIsFullyAuthenticated?: (is: boolean) => void;
+   setLoggedInUser?: (user: any) => void;
+   setEarlyReturnForAuth?: (element: JSX.Element | null) => void;
+}
+
+/***************************************************************************
+ ** hook for working with the anonymous authentication module
+ ***************************************************************************/
+export default function useAnonymousAuthenticationModule({setIsFullyAuthenticated, setLoggedInUser, setEarlyReturnForAuth}: Props)
+{
+   const [cookies, setCookie, removeCookie] = useCookies([SESSION_UUID_COOKIE_NAME]);
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   const setupSession = async () =>
+   {
+      console.log("Generating random token...");
+      setIsFullyAuthenticated(true);
+      Client.setGotAuthenticationInAllControllers();
+      setCookie(SESSION_UUID_COOKIE_NAME, Md5.hashStr(`${new Date()}`), {path: "/"});
+      console.log("Token generation complete.");
+   };
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   const logout = () =>
+   {
+      qController.clearAuthenticationMetaDataLocalStorage();
+      removeCookie(SESSION_UUID_COOKIE_NAME, {path: "/"});
+   };
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   const renderAppWrapper = (authenticationMetaData: QAuthenticationMetaData, children: JSX.Element): JSX.Element =>
+   {
+      return children;
+   };
+
+
+   return {
+      setupSession,
+      logout,
+      renderAppWrapper
+   };
+
+}

src/qqq/authorization/auth0/useAuth0AuthenticationModule.tsx

@@ -0,0 +1,253 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+import {Auth0Provider, useAuth0} from "@auth0/auth0-react";
+import {QAuthenticationMetaData} from "@kingsrook/qqq-frontend-core/lib/model/metaData/QAuthenticationMetaData";
+import App, {SESSION_UUID_COOKIE_NAME} from "App";
+import HandleAuthorizationError from "HandleAuthorizationError";
+import jwt_decode from "jwt-decode";
+import ProtectedRoute from "qqq/authorization/auth0/ProtectedRoute";
+import {MaterialUIControllerProvider} from "qqq/context";
+import Client from "qqq/utils/qqq/Client";
+import {useCookies} from "react-cookie";
+import {useNavigate, useSearchParams} from "react-router-dom";
+
+const qController = Client.getInstance();
+const qControllerV1 = Client.getInstanceV1();
+
+interface Props
+{
+   setIsFullyAuthenticated?: (is: boolean) => void;
+   setLoggedInUser?: (user: any) => void;
+   setEarlyReturnForAuth?: (element: JSX.Element | null) => void;
+}
+
+/***************************************************************************
+ ** hook for working with the Auth0 authentication module
+ ***************************************************************************/
+export default function useAuth0AuthenticationModule({setIsFullyAuthenticated, setLoggedInUser}: Props)
+{
+   const {user: auth0User, getAccessTokenSilently: auth0GetAccessTokenSilently, logout: useAuth0Logout} = useAuth0();
+
+   const [cookies, removeCookie] = useCookies([SESSION_UUID_COOKIE_NAME]);
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   const shouldStoreNewToken = (newToken: string, oldToken: string): boolean =>
+   {
+      if (!cookies[SESSION_UUID_COOKIE_NAME])
+      {
+         console.log("No session uuid cookie - so we should store a new one.");
+         return (true);
+      }
+
+      if (!oldToken)
+      {
+         console.log("No accessToken in localStorage - so we should store a new one.");
+         return (true);
+      }
+
+      try
+      {
+         const oldJSON: any = jwt_decode(oldToken);
+         const newJSON: any = jwt_decode(newToken);
+
+         ////////////////////////////////////////////////////////////////////////////////////
+         // if the old (local storage) token is expired, then we need to store the new one //
+         ////////////////////////////////////////////////////////////////////////////////////
+         const oldExp = oldJSON["exp"];
+         if (oldExp * 1000 < (new Date().getTime()))
+         {
+            console.log("Access token in local storage was expired - so we should store a new one.");
+            return (true);
+         }
+
+         ////////////////////////////////////////////////////////////////////////////////////////////////
+         // remove the exp & iat values from what we compare - as they are always different from auth0 //
+         // note, this is only deleting them from what we compare, not from what we'd store.           //
+         ////////////////////////////////////////////////////////////////////////////////////////////////
+         delete newJSON["exp"];
+         delete newJSON["iat"];
+         delete oldJSON["exp"];
+         delete oldJSON["iat"];
+
+         const different = JSON.stringify(newJSON) !== JSON.stringify(oldJSON);
+         if (different)
+         {
+            console.log("Latest access token from auth0 has changed vs localStorage - so we should store a new one.");
+         }
+         return (different);
+      }
+      catch (e)
+      {
+         console.log("Caught in shouldStoreNewToken: " + e);
+      }
+
+      return (true);
+   };
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   const setupSession = async () =>
+   {
+      try
+      {
+         console.log("Loading token from auth0...");
+         const accessToken = await auth0GetAccessTokenSilently();
+
+         const lsAccessToken = localStorage.getItem("accessToken");
+         if (shouldStoreNewToken(accessToken, lsAccessToken))
+         {
+            console.log("Sending accessToken to backend, requesting a sessionUUID...");
+            const {uuid: values} = await qController.manageSession(accessToken, null);
+
+            localStorage.setItem("accessToken", accessToken);
+            localStorage.setItem("sessionValues", JSON.stringify(values));
+            console.log("Got new sessionUUID from backend, and stored new accessToken");
+         }
+         else
+         {
+            console.log("Using existing sessionUUID cookie");
+         }
+
+         setIsFullyAuthenticated(true);
+         Client.setGotAuthenticationInAllControllers();
+
+         setLoggedInUser(auth0User);
+         console.log("Token load complete.");
+      }
+      catch (e)
+      {
+         console.log(`Error loading token: ${JSON.stringify(e)}`);
+         qController.clearAuthenticationMetaDataLocalStorage();
+         localStorage.removeItem("accessToken");
+         removeCookie(SESSION_UUID_COOKIE_NAME, {path: "/"});
+         useAuth0Logout();
+         return;
+      }
+   };
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   const logout = () =>
+   {
+      useAuth0Logout({returnTo: window.location.origin});
+   };
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   // @ts-ignore
+   function Auth0ProviderWithRedirectCallback({children, ...props})
+   {
+      const navigate = useNavigate();
+      const [searchParams] = useSearchParams();
+
+      // @ts-ignore
+      const onRedirectCallback = (appState) =>
+      {
+         navigate((appState && appState.returnTo) || window.location.pathname);
+      };
+      if (searchParams.get("error"))
+      {
+         return (
+            // @ts-ignore
+            <Auth0Provider {...props}>
+               <HandleAuthorizationError errorMessage={searchParams.get("error_description")} />
+            </Auth0Provider>
+         );
+      }
+      else
+      {
+         return (
+            // @ts-ignore
+            <Auth0Provider onRedirectCallback={onRedirectCallback} {...props}>
+               {children}
+            </Auth0Provider>
+         );
+      }
+   }
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   const renderAppWrapper = (authenticationMetaData: QAuthenticationMetaData): JSX.Element =>
+   {
+      // @ts-ignore
+      let domain: string = authenticationMetaData.data.baseUrl;
+
+      // @ts-ignore
+      const clientId = authenticationMetaData.data.clientId;
+
+      // @ts-ignore
+      const audience = authenticationMetaData.data.audience;
+
+      if (!domain || !clientId)
+      {
+         return (
+            <div>Error: AUTH0 authenticationMetaData is missing baseUrl [{domain}] and/or clientId [{clientId}].</div>
+         );
+      }
+
+      if (domain.endsWith("/"))
+      {
+         /////////////////////////////////////////////////////////////////////////////////////
+         // auth0 lib fails if we have a trailing slash.  be a bit more graceful than that. //
+         /////////////////////////////////////////////////////////////////////////////////////
+         domain = domain.replace(/\/$/, "");
+      }
+
+      /***************************************************************************
+       ** simple Functional Component to wrap the <App> and pass the authentication-
+       ** MetaData prop in, so a simple Component can be passed into ProtectedRoute
+       ***************************************************************************/
+      function WrappedApp()
+      {
+         return <App authenticationMetaData={authenticationMetaData} />
+      }
+
+      return (
+         <Auth0ProviderWithRedirectCallback
+            domain={domain}
+            clientId={clientId}
+            audience={audience}
+            redirectUri={`${window.location.origin}/`}>
+            <MaterialUIControllerProvider>
+               <ProtectedRoute component={WrappedApp} />
+            </MaterialUIControllerProvider>
+         </Auth0ProviderWithRedirectCallback>
+      );
+   };
+
+
+   return {
+      setupSession,
+      logout,
+      renderAppWrapper
+   };
+
+}

src/qqq/authorization/oauth2/useOAuth2AuthenticationModule.tsx

@@ -0,0 +1,188 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+import {QAuthenticationMetaData} from "@kingsrook/qqq-frontend-core/lib/model/metaData/QAuthenticationMetaData";
+import {SESSION_UUID_COOKIE_NAME} from "App";
+import Client from "qqq/utils/qqq/Client";
+import {useCookies} from "react-cookie";
+import {AuthContextProps, AuthProvider, useAuth} from "react-oidc-context";
+import {useNavigate, useSearchParams} from "react-router-dom";
+
+const qController = Client.getInstance();
+
+interface Props
+{
+   setIsFullyAuthenticated?: (is: boolean) => void;
+   setLoggedInUser?: (user: any) => void;
+   setEarlyReturnForAuth?: (element: JSX.Element | null) => void;
+   inOAuthContext: boolean;
+}
+
+/***************************************************************************
+ ** hook for working with the OAuth2  authentication module
+ ***************************************************************************/
+export default function useOAuth2AuthenticationModule({setIsFullyAuthenticated, setLoggedInUser, setEarlyReturnForAuth, inOAuthContext}: Props)
+{
+   ///////////////////////////////////////////////////////////////////////////////////////
+   // the useAuth hook should only be called if we're inside the <AuthProvider> element //
+   // so on the page that uses this hook to call renderAppWrapper, we aren't in that    //
+   // element/context, thus, don't call that hook.                                      //
+   ///////////////////////////////////////////////////////////////////////////////////////
+   const authOidc: AuthContextProps | null = inOAuthContext ? useAuth() : null;
+
+   const [cookies, removeCookie] = useCookies([SESSION_UUID_COOKIE_NAME]);
+   const [searchParams] = useSearchParams();
+   const navigate = useNavigate();
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   const setupSession = async () =>
+   {
+      try
+      {
+         const preSigninRedirectPathnameKey = "oauth2.preSigninRedirect.pathname";
+         if (window.location.pathname == "/token")
+         {
+            ///////////////////////////////////////////////////////////////////////////
+            // if we're at a path of /token, get code & state params, look up values //
+            // from that state in local storage, and make a post to the backend to   //
+            // with these values - which will itself talk to the identity provider   //
+            // to get an access token, and ultimately a session.                     //
+            ///////////////////////////////////////////////////////////////////////////
+            const code = searchParams.get("code");
+            const state = searchParams.get("state");
+            const oidcString = localStorage.getItem(`oidc.${state}`);
+            if (oidcString)
+            {
+               const oidcObject = JSON.parse(oidcString) as { [name: string]: any };
+               console.log(oidcObject);
+               const manageSessionRequestBody = {code: code, codeVerifier: oidcObject.code_verifier, redirectUri: oidcObject.redirect_uri};
+               const {uuid: newSessionUuid, values} = await qController.manageSession(null, null, manageSessionRequestBody);
+               console.log(`we have new session UUID: ${newSessionUuid}`);
+
+               setIsFullyAuthenticated(true);
+               Client.setGotAuthenticationInAllControllers();
+
+               setLoggedInUser(values?.user);
+               console.log("Token load complete.");
+
+               const preSigninRedirectPathname = localStorage.getItem(preSigninRedirectPathnameKey);
+               localStorage.removeItem(preSigninRedirectPathname);
+               navigate(preSigninRedirectPathname ?? "/", {replace: true});
+            }
+            else
+            {
+               ////////////////////////////////////////////
+               // if unrecognized state, render an error //
+               ////////////////////////////////////////////
+               setEarlyReturnForAuth(<div>Login error:  Unrecognized state.  Refresh to try again.</div>);
+            }
+         }
+         else
+         {
+            //////////////////////////////////////////////////////////////////////////
+            // if we have a sessionUUID cookie, try to validate it with the backend //
+            //////////////////////////////////////////////////////////////////////////
+            const sessionUuid = cookies[SESSION_UUID_COOKIE_NAME];
+            if (sessionUuid)
+            {
+               console.log(`we have session UUID: ${sessionUuid} - validating it...`);
+               const {values} = await qController.manageSession(null, sessionUuid, null);
+
+               setIsFullyAuthenticated(true);
+               Client.setGotAuthenticationInAllControllers();
+
+               setLoggedInUser(values?.user);
+               console.log("Token load complete.");
+            }
+            else
+            {
+               /////////////////////////////////////////////////////////////////////////////////////////////////
+               // else no cookie, and not a token url, we need to redirect to the provider's login page       //
+               // capture the path the user was trying to access in local storage, to redirect back to later. //
+               /////////////////////////////////////////////////////////////////////////////////////////////////
+               console.log("Loading token from OAuth2 provider...");
+               console.log(authOidc);
+               localStorage.setItem(preSigninRedirectPathnameKey, window.location.pathname);
+               setEarlyReturnForAuth(<div>Signing in...</div>);
+               authOidc?.signinRedirect();
+            }
+         }
+      }
+      catch (e)
+      {
+         console.log(`Error loading token: ${JSON.stringify(e)}`);
+         logout();
+         return;
+      }
+   };
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   const logout = () =>
+   {
+      qController.clearAuthenticationMetaDataLocalStorage();
+      removeCookie(SESSION_UUID_COOKIE_NAME, {path: "/"});
+      authOidc?.signoutRedirect();
+   };
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   const renderAppWrapper = (authenticationMetaData: QAuthenticationMetaData, children: JSX.Element): JSX.Element =>
+   {
+      const authority: string = authenticationMetaData.data.baseUrl;
+      const clientId = authenticationMetaData.data.clientId;
+
+      if (!authority || !clientId)
+      {
+         return (
+            <div>Error: OAuth2 authenticationMetaData is missing baseUrl [{authority}] and/or clientId [{clientId}].</div>
+         );
+      }
+
+      const oidcConfig =
+         {
+            authority: authority,
+            client_id: clientId,
+            redirect_uri: `${window.location.origin}/token`,
+            response_type: "code",
+            scope: "openid profile email offline_access",
+         };
+
+      return (<AuthProvider {...oidcConfig}>
+         {children}
+      </AuthProvider>
+      );
+   };
+
+
+   return {
+      setupSession,
+      logout,
+      renderAppWrapper
+   };
+
+}

src/qqq/components/buttons/DefaultButtons.tsx

@@ -30,14 +30,17 @@ import MDButton from "qqq/components/legacy/MDButton";
 
 export const standardWidth = "150px";
 
+const standardML = {xs: 1, md: 3};
+
 interface QCreateNewButtonProps
 {
    tablePath: string;
 }
+
 export function QCreateNewButton({tablePath}: QCreateNewButtonProps): JSX.Element
 {
    return (
-      <Box display="inline-block" ml={3} mr={0} width={standardWidth}>
+      <Box display="inline-block" ml={standardML} mr={0} width={standardWidth}>
          <Link to={`${tablePath}/create`}>
             <MDButton variant="gradient" color="info" fullWidth startIcon={<Icon>add</Icon>}>
                Create New
@@ -54,6 +57,7 @@ interface QSaveButtonProps
    onClickHandler?: any,
    disabled: boolean
 }
+
 QSaveButton.defaultProps = {
    label: "Save",
    iconName: "save"
@@ -62,7 +66,7 @@ QSaveButton.defaultProps = {
 export function QSaveButton({label, iconName, onClickHandler, disabled}: QSaveButtonProps): JSX.Element
 {
    return (
-      <Box ml={3} width={standardWidth}>
+      <Box ml={standardML} width={standardWidth}>
          <MDButton type="submit" variant="gradient" color="info" size="small" onClick={onClickHandler} fullWidth startIcon={<Icon>{iconName}</Icon>} disabled={disabled}>
             {label}
          </MDButton>
@@ -72,17 +76,18 @@ export function QSaveButton({label, iconName, onClickHandler, disabled}: QSaveBu
 
 interface QDeleteButtonProps
 {
-   onClickHandler: any
-   disabled?: boolean
+   onClickHandler: any;
+   disabled?: boolean;
 }
 
 QDeleteButton.defaultProps = {
    disabled: false
 };
+
 export function QDeleteButton({onClickHandler, disabled}: QDeleteButtonProps): JSX.Element
 {
    return (
-      <Box ml={3} width={standardWidth}>
+      <Box ml={standardML} width={standardWidth}>
          <MDButton variant="gradient" color="primary" size="small" onClick={onClickHandler} fullWidth startIcon={<Icon>delete</Icon>} disabled={disabled}>
             Delete
          </MDButton>
@@ -93,7 +98,7 @@ export function QDeleteButton({onClickHandler, disabled}: QDeleteButtonProps): J
 export function QEditButton(): JSX.Element
 {
    return (
-      <Box ml={3} width={standardWidth}>
+      <Box ml={standardML} width={standardWidth}>
          <Link to="edit">
             <MDButton variant="gradient" color="dark" size="small" fullWidth startIcon={<Icon>edit</Icon>}>
                Edit
@@ -132,7 +137,7 @@ interface QCancelButtonProps
    onClickHandler: any;
    disabled: boolean;
    label?: string;
-   iconName?: string
+   iconName?: string;
 }
 
 export function QCancelButton({
@@ -140,7 +145,7 @@ export function QCancelButton({
 }: QCancelButtonProps): JSX.Element
 {
    return (
-      <Box ml="auto" width={standardWidth}>
+      <Box ml={standardML} width={standardWidth}>
          <MDButton type="button" variant="outlined" color="dark" size="small" fullWidth startIcon={<Icon>{iconName}</Icon>} onClick={onClickHandler} disabled={disabled}>
             {label}
          </MDButton>
@@ -155,15 +160,15 @@ QCancelButton.defaultProps = {
 
 interface QSubmitButtonProps
 {
-   label?: string
-   iconName?: string
-   disabled: boolean
+   label?: string;
+   iconName?: string;
+   disabled: boolean;
 }
 
 export function QSubmitButton({label, iconName, disabled}: QSubmitButtonProps): JSX.Element
 {
    return (
-      <Box ml={3} width={standardWidth}>
+      <Box ml={standardML} width={standardWidth}>
          <MDButton type="submit" variant="gradient" color="dark" size="small" fullWidth startIcon={<Icon>{iconName}</Icon>} disabled={disabled}>
             {label}
          </MDButton>
@@ -175,3 +180,24 @@ QSubmitButton.defaultProps = {
    label: "Submit",
    iconName: "check",
 };
+
+interface QAlternateButtonProps
+{
+   label: string,
+   iconName?: string,
+   disabled: boolean,
+   onClick?: () => void
+}
+
+export function QAlternateButton({label, iconName, disabled, onClick}: QAlternateButtonProps): JSX.Element
+{
+   return (
+      <Box ml={standardML} width={standardWidth}>
+         <MDButton type="button" variant="gradient" color="secondary" size="small" fullWidth startIcon={iconName && <Icon>{iconName}</Icon>} onClick={onClick} disabled={disabled}>
+            {label}
+         </MDButton>
+      </Box>
+   );
+}
+
+QAlternateButton.defaultProps = {};

src/qqq/components/forms/BooleanFieldSwitch.tsx

@@ -80,11 +80,12 @@ interface Props
    label: string;
    value: boolean;
    isDisabled: boolean;
+   onChangeCallback?: (newValue: any) => void;
 }
 
 
 
-function BooleanFieldSwitch({name, label, value, isDisabled}: Props) : JSX.Element
+function BooleanFieldSwitch({name, label, value, isDisabled, onChangeCallback}: Props) : JSX.Element
 {
    const {setFieldValue} = useFormikContext();
 
@@ -93,6 +94,10 @@ function BooleanFieldSwitch({name, label, value, isDisabled}: Props) : JSX.Eleme
       if(!isDisabled)
       {
          setFieldValue(name, newValue);
+         if(onChangeCallback)
+         {
+            onChangeCallback(newValue);
+         }
          event.stopPropagation();
       }
    }
@@ -100,6 +105,10 @@ function BooleanFieldSwitch({name, label, value, isDisabled}: Props) : JSX.Eleme
    const toggleSwitch = () =>
    {
       setFieldValue(name, !value);
+      if(onChangeCallback)
+      {
+         onChangeCallback(!value);
+      }
    }
 
    const classNullSwitch = (value === null || value == undefined || `${value}` == "") ? "nullSwitch" : "";

src/qqq/components/forms/ChipTextField.tsx

@@ -23,8 +23,10 @@ import {Chip} from "@mui/material";
 import TextField from "@mui/material/TextField";
 import {makeStyles} from "@mui/styles";
 import Downshift from "downshift";
+import {debounce} from "lodash";
 import {arrayOf, func, string} from "prop-types";
-import React, {useEffect, useState} from "react";
+import Client from "qqq/utils/qqq/Client";
+import React, {useEffect, useRef, useState} from "react";
 
 const useStyles = makeStyles((theme: any) => ({
    chip: {
@@ -34,21 +36,107 @@ const useStyles = makeStyles((theme: any) => ({
 
 function ChipTextField({...props})
 {
+   const qController = Client.getInstance();
    const classes = useStyles();
-   const {handleChipChange, label, chipType, disabled, placeholder, chipData, multiline, rows, ...other} = props;
+   const {table, field, handleChipChange, label, chipType, disabled, placeholder, chipData, multiline, rows, ...other} = props;
    const [inputValue, setInputValue] = useState("");
    const [chips, setChips] = useState([]);
+   const [chipColors, setChipColors] = useState([]);
+   const [chipValidity, setChipValidity] = useState([] as boolean[]);
+   const [chipPVSIds, setChipPVSIds] = useState([] as any[]);
+   const [isMakingRequest, setIsMakingRequest] = useState(false);
 
+   ////////////////////////////////////////////////////////////////////
+   // these refs are used for the async api call for possible values //
+   ////////////////////////////////////////////////////////////////////
+   const chipsRef = useRef<string[]>([]);
+
+   /////////////////////////////////////////////////////////////////////////////////////////////
+   // use debounce library to not flood server as user types, wait a second before requesting //
+   /////////////////////////////////////////////////////////////////////////////////////////////
+   async function fetchPVSLabelsAndColorChips()
+   {
+      //////////////////////////////////////////////////////////
+      // make a request for the possible value labels (chips) //
+      //////////////////////////////////////////////////////////
+      setIsMakingRequest(true);
+      const currentChips = chipsRef.current;
+      setChipColors([]);
+
+      ///////////////////////////////////////////////////////////////////////////////
+      // Determine chip colors based on whether each chip value appears in results //
+      ///////////////////////////////////////////////////////////////////////////////
+      const newChipColors = [] as string[];
+      const chipValidity = [] as boolean[];
+      const chipPVSIds = [] as any[];
+
+      ////////////////////////////////////////////////////////////////////////////
+      // make the request for all 'chips' with pagination to handle large sizes //
+      ////////////////////////////////////////////////////////////////////////////
+      const BATCH_SIZE = 250;
+      for (let i = 0; i < currentChips.length; i += BATCH_SIZE)
+      {
+         const batch = currentChips.slice(i, i + BATCH_SIZE);
+         const page = await qController.possibleValues(
+            table.name,
+            null,
+            field.name,
+            "",
+            null,
+            batch
+         );
+         for (let j = 0; j < batch.length; j++)
+         {
+            let found = false;
+            for (let k = 0; k < page.length; k++)
+            {
+               const result = page[k];
+               if (result.label.toLowerCase() === batch[j].toLowerCase())
+               {
+                  chipPVSIds.push(result.id);
+                  newChipColors.push("info");
+                  chipValidity.push(true);
+                  found = true;
+                  break;
+               }
+            }
+
+            if (!found)
+            {
+               chipPVSIds.push(null);
+               chipValidity.push(false);
+               newChipColors.push("error");
+            }
+         }
+      }
+
+      setChipPVSIds(chipPVSIds);
+      setChipColors(newChipColors);
+      setChipValidity(chipValidity);
+      setIsMakingRequest(false);
+   }
+
+   const debouncedApiCall = useRef(debounce(fetchPVSLabelsAndColorChips, 500)).current;
 
    useEffect(() =>
    {
       setChips(chipData);
-   }, [chipData]);
+      chipsRef.current = chipData;
+      determineChipColors();
+
+      if (chipType !== "pvs")
+      {
+         const currentChipValidity = chips.map((chip, i) =>
+            (chipType !== "number" || !Number.isNaN(Number(chips[i])))
+         );
+         setChipValidity(currentChipValidity);
+      }
+   }, [JSON.stringify(chipData), chips]);
 
    useEffect(() =>
    {
-      handleChipChange(chips);
-   }, [chips, handleChipChange]);
+      handleChipChange(isMakingRequest, chipValidity, chipPVSIds);
+   }, [chipValidity, chipPVSIds, isMakingRequest]);
 
    function handleKeyDown(event: any)
    {
@@ -64,13 +152,16 @@ function ChipTextField({...props})
             setInputValue("");
             return;
          }
-         if (!event.target.value.replace(/\s/g, "").length) return;
+         if (!event.target.value.replace(/\s/g, "").length)
+         {
+            return;
+         }
 
+         setInputValue("");
          newChipList.push(event.target.value.trim());
          setChips(newChipList);
-         setInputValue("");
       }
-      else if (chips.length && !inputValue.length && event.key === "Backspace" )
+      else if (chips.length && !inputValue.length && event.key === "Backspace")
       {
          setChips(chips.slice(0, chips.length - 1));
       }
@@ -87,18 +178,26 @@ function ChipTextField({...props})
       setChips(newChipList);
    }
 
-   const handleDelete = (item: any) => () =>
-   {
-      const newChipList = [...chips];
-      newChipList.splice(newChipList.indexOf(item), 1);
-      setChips(newChipList);
-   };
-
    function handleInputChange(event: { target: { value: React.SetStateAction<string>; }; })
    {
       setInputValue(event.target.value);
    }
 
+   function determineChipColors(): any
+   {
+      if (chipType === "pvs")
+      {
+         debouncedApiCall();
+      }
+      else
+      {
+         const newChipColors = chips.map((chip, i) =>
+            (chipType !== "number" || !Number.isNaN(Number(chips[i]))) ? "info" : "error"
+         );
+         setChipColors(newChipColors);
+      }
+   }
+
 
    return (
       <React.Fragment>
@@ -116,7 +215,7 @@ function ChipTextField({...props})
                });
                // @ts-ignore
                return (
-                  <div id="chip-text-field-container" style={{flexWrap: "wrap", display:"flex"}}>
+                  <div id="chip-text-field-container" style={{flexWrap: "wrap", display: "flex"}}>
                      <TextField
                         sx={{width: "99%"}}
                         disabled={disabled}
@@ -125,16 +224,16 @@ function ChipTextField({...props})
                            startAdornment:
                               <div style={{overflowY: "auto", overflowX: "hidden", margin: "-10px", width: "calc(100% + 20px)", padding: "10px", marginBottom: "-20px", height: "calc(100% + 10px)"}}>
                                  {
-                                    chips.map((item, i) => (
+                                    chips.map((item, index) => (
                                        <Chip
-                                          color={(chipType !== "number" || ! Number.isNaN(Number(item))) ? "info" : "error"}
-                                          key={`${item}-${i}`}
+                                          onChange={determineChipColors}
+                                          color={chipColors[index]}
+                                          key={`${item}-${index}`}
                                           variant="outlined"
                                           tabIndex={-1}
                                           label={item}
                                           className={classes.chip}
                                        />
-
                                     ))
                                  }
                               </div>,
@@ -158,6 +257,7 @@ function ChipTextField({...props})
       </React.Fragment>
    );
 }
+
 ChipTextField.defaultProps = {
    chipData: []
 };
@@ -166,4 +266,4 @@ ChipTextField.propTypes = {
    chipData: arrayOf(string)
 };
 
-export default ChipTextField
+export default ChipTextField;

src/qqq/components/forms/DynamicForm.tsx

@@ -19,21 +19,22 @@
  * along with this program.  If not, see <https://www.gnu.org/licenses/>.
  */
 
+import {AdornmentType} from "@kingsrook/qqq-frontend-core/lib/model/metaData/AdornmentType";
 import {QFieldMetaData} from "@kingsrook/qqq-frontend-core/lib/model/metaData/QFieldMetaData";
-import {QFieldType} from "@kingsrook/qqq-frontend-core/lib/model/metaData/QFieldType";
 import {QRecord} from "@kingsrook/qqq-frontend-core/lib/model/QRecord";
-import {colors, Icon, InputLabel} from "@mui/material";
 import Box from "@mui/material/Box";
-import Button from "@mui/material/Button";
 import Grid from "@mui/material/Grid";
-import Tooltip from "@mui/material/Tooltip";
 import {useFormikContext} from "formik";
-import React, {useState} from "react";
 import QDynamicFormField from "qqq/components/forms/DynamicFormField";
+import DynamicFormUtils from "qqq/components/forms/DynamicFormUtils";
 import DynamicSelect from "qqq/components/forms/DynamicSelect";
+import FileInputField from "qqq/components/forms/FileInputField";
 import MDTypography from "qqq/components/legacy/MDTypography";
 import HelpContent from "qqq/components/misc/HelpContent";
-import ValueUtils from "qqq/utils/qqq/ValueUtils";
+import Client from "qqq/utils/qqq/Client";
+import React, {useEffect, useState} from "react";
+
+const qController = Client.getInstance();
 
 interface Props
 {
@@ -48,29 +49,12 @@ interface Props
 
 function QDynamicForm({formData, formLabel, bulkEditMode, bulkEditSwitchChangeHandler, record, helpRoles, helpContentKeyPrefix}: Props): JSX.Element
 {
-   const {formFields, values, errors, touched} = formData;
+   const {formFields: origFormFields, errors, touched} = formData;
+   const {setFieldValue, values} = useFormikContext<Record<string, any>>();
 
-   const formikProps = useFormikContext();
-   const [fileName, setFileName] = useState(null as string);
+   const [formAdjustmentCounter, setFormAdjustmentCounter] = useState(0)
 
-   const fileChanged = (event: React.FormEvent<HTMLInputElement>, field: any) =>
-   {
-      setFileName(null);
-      if (event.currentTarget.files && event.currentTarget.files[0])
-      {
-         setFileName(event.currentTarget.files[0].name);
-      }
-
-      formikProps.setFieldValue(field.name, event.currentTarget.files[0]);
-   };
-
-   const removeFile = (fieldName: string) =>
-   {
-      setFileName(null);
-      formikProps.setFieldValue(fieldName, null);
-      record?.values.delete(fieldName)
-      record?.displayValues.delete(fieldName)
-   };
+   const [formFields, setFormFields] = useState(origFormFields as {[key: string]: any});
 
    const bulkEditSwitchChanged = (name: string, value: boolean) =>
    {
@@ -78,18 +62,211 @@ function QDynamicForm({formData, formLabel, bulkEditMode, bulkEditSwitchChangeHa
    };
 
 
+   /////////////////////////////////////////
+   // run on-load handlers if we have any //
+   /////////////////////////////////////////
+   useEffect(() =>
+   {
+      for (let fieldName in formFields)
+      {
+         const field = formFields[fieldName];
+
+         const materialDashboardFieldMetaData = field.fieldMetaData?.supplementalFieldMetaData?.get("materialDashboard");
+         if(materialDashboardFieldMetaData?.onLoadFormAdjuster)
+         {
+            //////////////////////////////////////////////////////////////////////////////////////////////////////////
+            // todo consider cases with multiple - do they need to list a sequenceNo? do they need to run serially? //
+            //////////////////////////////////////////////////////////////////////////////////////////////////////////
+            considerRunningFormAdjuster("onLoad", fieldName, values[fieldName]);
+         }
+      }
+   }, []);
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   const handleFieldChange = async (fieldName: string, newValue: any) =>
+   {
+      const field = formFields[fieldName];
+      if (!field)
+      {
+         return;
+      }
+
+      //////////////////////////////////////////////////////////////////////
+      // map possible-value objects to ids - also capture their labels... //
+      //////////////////////////////////////////////////////////////////////
+      let actualNewValue = newValue;
+      let possibleValueLabel: string = null;
+      if (field.possibleValueProps)
+      {
+         actualNewValue = newValue ? newValue.id : null;
+         possibleValueLabel = newValue ? newValue.label : null;
+      }
+
+      /////////////////////////////////////////////////////////////////////////////////////////////
+      // make sure formik has the value - and that we capture the possible-value label if needed //
+      /////////////////////////////////////////////////////////////////////////////////////////////
+      setFieldValue(fieldName, actualNewValue);
+      if (field.possibleValueProps)
+      {
+         field.possibleValueProps.initialDisplayValue = possibleValueLabel;
+      }
+
+      ///////////////////////////////////////////
+      // run onChange adjuster if there is one //
+      ///////////////////////////////////////////
+      considerRunningFormAdjuster("onChange", fieldName, actualNewValue);
+   }
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   const considerRunningFormAdjuster = async (event: "onChange" | "onLoad", fieldName: string, newValue: any) =>
+   {
+      const field = formFields[fieldName];
+      if (!field)
+      {
+         return;
+      }
+
+      const materialDashboardFieldMetaData = field.fieldMetaData?.supplementalFieldMetaData?.get("materialDashboard");
+      const adjuster = event == "onChange" ? materialDashboardFieldMetaData?.onChangeFormAdjuster : materialDashboardFieldMetaData?.onLoadFormAdjuster;
+      if (!adjuster)
+      {
+         return;
+      }
+
+      console.log(`Running form adjuster for field ${fieldName} ${event} (value is: ${newValue})`);
+
+      //////////////////////////////////////////////////////////////////
+      // disable fields temporarily while waiting on backend response //
+      //////////////////////////////////////////////////////////////////
+      const fieldNamesToTempDisable: string[] = materialDashboardFieldMetaData?.fieldsToDisableWhileRunningAdjusters ?? []
+      const previousIsEditableValues: {[key: string]: boolean} = {};
+      if(fieldNamesToTempDisable.length > 0)
+      {
+         for (let oldFieldName in formFields)
+         {
+            if (fieldNamesToTempDisable.indexOf(oldFieldName) > -1)
+            {
+               previousIsEditableValues[oldFieldName] = formFields[oldFieldName].isEditable;
+               formFields[oldFieldName].isEditable = false;
+            }
+         }
+
+         setFormAdjustmentCounter(formAdjustmentCounter + 1);
+         setFormFields({...formFields});
+      }
+
+      ////////////////////////////////////////////////////
+      // build request to backend for field adjustments //
+      ////////////////////////////////////////////////////
+      const postBody = new FormData();
+      postBody.append("event", event);
+      postBody.append("fieldName", fieldName);
+      postBody.append("newValue", newValue);
+      postBody.append("allValues", JSON.stringify(values));
+      const response = await qController.axiosRequest(
+         {
+            method: "post",
+            url: `/material-dashboard-backend/form-adjuster/${encodeURIComponent(materialDashboardFieldMetaData.formAdjusterIdentifier)}/${event}`,
+            data: postBody,
+            headers: qController.defaultMultipartFormDataHeaders()
+         });
+      console.log("Form adjuster response: " + JSON.stringify(response));
+
+      ////////////////////////////////////////////////////
+      // un-disable any temp disabled fields from above //
+      ////////////////////////////////////////////////////
+      if(fieldNamesToTempDisable.length > 0)
+      {
+         for (let oldFieldName in formFields)
+         {
+            if (fieldNamesToTempDisable.indexOf(oldFieldName) > -1)
+            {
+               formFields[oldFieldName].isEditable = previousIsEditableValues[oldFieldName];
+            }
+         }
+         setFormFields({...formFields});
+      }
+
+      ///////////////////////////////////////////////////
+      // replace field definitions, if we have updates //
+      ///////////////////////////////////////////////////
+      const updatedFields: { [fieldName: string]: QFieldMetaData } = response.updatedFieldMetaData;
+      if(updatedFields)
+      {
+         for (let updatedFieldName in updatedFields)
+         {
+            const updatedField = new QFieldMetaData(updatedFields[updatedFieldName]);
+            const dynamicField = DynamicFormUtils.getDynamicField(updatedField); // todo dynamicallyDisabledFields? second param...
+
+            const dynamicFieldInObject: any = {};
+            dynamicFieldInObject[updatedFieldName] = dynamicField;
+            let tableName = null;
+            let processName = null;
+            let displayValues = new Map();
+
+            DynamicFormUtils.addPossibleValueProps(dynamicFieldInObject, [updatedFields[updatedFieldName]], tableName, processName, displayValues);
+            for (let oldFieldName in formFields)
+            {
+               if (oldFieldName == updatedFieldName)
+               {
+                  formFields[updatedFieldName] = dynamicField;
+               }
+            }
+         }
+
+         setFormAdjustmentCounter(formAdjustmentCounter + 2);
+         setFormFields({...formFields});
+      }
+
+      /////////////////////////
+      // update field values //
+      /////////////////////////
+      const updatedFieldValues: {[fieldName: string]: any} = response?.updatedFieldValues ?? {};
+      for (let fieldNameToUpdate in updatedFieldValues)
+      {
+         setFieldValue(fieldNameToUpdate, updatedFieldValues[fieldNameToUpdate]);
+         ///////////////////////////////////////////////////////////////////////////////////////
+         // todo - track if a pvs field gets a value, but not a display value, and fetch it?? //
+         ///////////////////////////////////////////////////////////////////////////////////////
+      }
+
+      /////////////////////////////////////////////////
+      // set display values in PVS's if we have them //
+      /////////////////////////////////////////////////
+      const updatedFieldDisplayValues: {[fieldName: string]: any} = response?.updatedFieldDisplayValues ?? {};
+      for (let fieldNameToUpdate in updatedFieldDisplayValues)
+      {
+         const fieldToUpdate = formFields[fieldNameToUpdate];
+         if(fieldToUpdate?.possibleValueProps)
+         {
+            fieldToUpdate.possibleValueProps.initialDisplayValue = updatedFieldDisplayValues[fieldNameToUpdate];
+         }
+      }
+
+      ////////////////////////////////////////
+      // clear field values if we have them //
+      ////////////////////////////////////////
+      const fieldsToClear: string[] = response?.fieldsToClear ?? [];
+      for (let fieldToClear of fieldsToClear)
+      {
+         setFieldValue(fieldToClear, "");
+      }
+   };
+
+
    return (
       <Box>
          <Box lineHeight={0}>
             <MDTypography variant="h5">{formLabel}</MDTypography>
-            {/* TODO - help text
-        <MDTypography variant="button" color="text">
-          Mandatory information
-        </MDTypography>
-        */}
          </Box>
          <Box mt={1.625}>
-            <Grid container spacing={3}>
+            <Grid container lg={12} display="flex" spacing={3}>
                {formFields
                   && Object.keys(formFields).length > 0
                   && Object.keys(formFields).map((fieldName: any) =>
@@ -100,98 +277,82 @@ function QDynamicForm({formData, formLabel, bulkEditMode, bulkEditSwitchChangeHa
                         return null;
                      }
 
+                     const display = field.fieldMetaData?.isHidden ? "none" : "initial";
+
                      if (values[fieldName] === undefined)
                      {
                         values[fieldName] = "";
                      }
 
-                     let formattedHelpContent = <HelpContent helpContents={field.fieldMetaData.helpContents} roles={helpRoles} helpContentKey={`${helpContentKeyPrefix ?? ""}field:${fieldName}`} />;
-                     if(formattedHelpContent)
+                     let formattedHelpContent = <HelpContent helpContents={field?.fieldMetaData?.helpContents} roles={helpRoles} helpContentKey={`${helpContentKeyPrefix ?? ""}field:${fieldName}`} />;
+                     if (formattedHelpContent)
                      {
-                        formattedHelpContent = <Box color="#757575" fontSize="0.875rem" mt="-0.25rem">{formattedHelpContent}</Box>
+                        formattedHelpContent = <Box color="#757575" fontSize="0.875rem" mt="-0.25rem">{formattedHelpContent}</Box>;
                      }
 
-                     const labelElement = <Box fontSize="1rem" fontWeight="500" marginBottom="0.25rem">
-                        <label htmlFor={field.name}>{field.label}</label>
-                     </Box>
+                     const labelElement = <DynamicFormFieldLabel name={field.name} label={field.label} />;
 
+                     let itemLG = (field?.fieldMetaData?.gridColumns && field?.fieldMetaData?.gridColumns > 0) ? field.fieldMetaData.gridColumns : 6;
+                     let itemXS = 12;
+                     let itemSM = 6;
+
+                     /////////////
+                     // files!! //
+                     /////////////
                      if (field.type === "file")
                      {
-                        const pseudoField = new QFieldMetaData({name: fieldName, type: QFieldType.BLOB});
-                        return (
-                           <Grid item xs={12} sm={6} key={fieldName}>
-                              <Box mb={1.5}>
-                                 {labelElement}
-                                 {
-                                    record && record.values.get(fieldName) && <Box fontSize="0.875rem" pb={1}>
-                                       Current File:
-                                       <Box display="inline-flex" pl={1}>
-                                          {ValueUtils.getDisplayValue(pseudoField, record, "view")}
-                                          <Tooltip placement="bottom" title="Remove current file">
-                                             <Icon className="blobIcon" fontSize="small" onClick={(e) => removeFile(fieldName)}>delete</Icon>
-                                          </Tooltip>
-                                       </Box>
-                                    </Box>
-                                 }
-                                 <Box display="flex" alignItems="center">
-                                    <Button variant="outlined" component="label">
-                                       <span style={{color: colors.lightBlue[500]}}>Choose file to upload</span>
-                                       <input
-                                          id={fieldName}
-                                          name={fieldName}
-                                          type="file"
-                                          hidden
-                                          onChange={(event: React.FormEvent<HTMLInputElement>) => fileChanged(event, field)}
-                                       />
-                                    </Button>
-                                    <Box ml={1} fontSize={"1rem"}>
-                                       {fileName}
-                                    </Box>
-                                 </Box>
+                        const fileUploadAdornment = field.fieldMetaData?.getAdornment(AdornmentType.FILE_UPLOAD);
+                        const width = fileUploadAdornment?.values?.get("width") ?? "half";
 
-                                 <Box mt={0.75}>
-                                    <MDTypography component="div" variant="caption" color="error" fontWeight="regular">
-                                       {errors[fieldName] && <span>You must select a file to proceed</span>}
-                                    </MDTypography>
-                                 </Box>
-                              </Box>
+                        if (width == "full")
+                        {
+                           itemSM = 12;
+                           itemLG = 12;
+                        }
+
+                        return (
+                           <Grid item lg={itemLG} xs={itemXS} sm={itemSM} flexDirection="column" key={fieldName + "-" + formAdjustmentCounter}>
+                              {labelElement}
+                              <FileInputField field={field} record={record} errorMessage={errors[fieldName]} />
                            </Grid>
                         );
                      }
 
-                     // possible values!!
-                     if (field.possibleValueProps)
+                     ///////////////////////
+                     // possible values!! //
+                     ///////////////////////
+                     else if (field.possibleValueProps)
                      {
                         const otherValuesMap = field.possibleValueProps.otherValues ?? new Map<string, any>();
                         Object.keys(values).forEach((key) =>
                         {
                            otherValuesMap.set(key, values[key]);
-                        })
+                        });
 
                         return (
-                           <Grid item xs={12} sm={6} key={fieldName}>
+                           <Grid item display={display} lg={itemLG} xs={itemXS} sm={itemSM} key={fieldName + "-" + formAdjustmentCounter}>
                               {labelElement}
                               <DynamicSelect
-                                 tableName={field.possibleValueProps.tableName}
-                                 processName={field.possibleValueProps.processName}
-                                 fieldName={fieldName}
+                                 fieldPossibleValueProps={field.possibleValueProps}
                                  isEditable={field.isEditable}
                                  fieldLabel=""
                                  initialValue={values[fieldName]}
-                                 initialDisplayValue={field.possibleValueProps.initialDisplayValue}
                                  bulkEditMode={bulkEditMode}
                                  bulkEditSwitchChangeHandler={bulkEditSwitchChanged}
                                  otherValues={otherValuesMap}
+                                 useCase="form"
+                                 onChange={(newValue: any) => handleFieldChange(fieldName, newValue)}
                               />
                               {formattedHelpContent}
                            </Grid>
                         );
                      }
 
-                     // todo? inputProps={{ autoComplete: "" }}
-                     // todo? placeholder={password.placeholder}
+                     ///////////////////////
+                     // everything else!! //
+                     ///////////////////////
                      return (
-                        <Grid item xs={12} sm={6} key={fieldName}>
+                        <Grid item display={display} lg={itemLG} xs={itemXS} sm={itemSM} key={fieldName + "-" + formAdjustmentCounter}>
                            {labelElement}
                            <QDynamicFormField
                               id={field.name}
@@ -206,6 +367,7 @@ function QDynamicForm({formData, formLabel, bulkEditMode, bulkEditSwitchChangeHa
                               bulkEditSwitchChangeHandler={bulkEditSwitchChanged}
                               success={`${values[fieldName]}` !== "" && !errors[fieldName] && touched[fieldName]}
                               formFieldObject={field}
+                              onChangeCallback={(newValue) => handleFieldChange(fieldName, newValue)}
                            />
                            {formattedHelpContent}
                         </Grid>
@@ -226,4 +388,19 @@ QDynamicForm.defaultProps = {
    },
 };
 
+
+interface DynamicFormFieldLabelProps
+{
+   name: string;
+   label: string;
+}
+
+export function DynamicFormFieldLabel({name, label}: DynamicFormFieldLabelProps): JSX.Element
+{
+   return (<Box fontSize="1rem" fontWeight="500" marginBottom="0.25rem">
+      <label htmlFor={name}>{label}</label>
+   </Box>);
+}
+
+
 export default QDynamicForm;

src/qqq/components/forms/DynamicFormField.tsx

@@ -19,16 +19,20 @@
  * along with this program.  If not, see <https://www.gnu.org/licenses/>.
  */
 
+import {QPossibleValue} from "@kingsrook/qqq-frontend-core/lib/model/QPossibleValue";
 import {InputAdornment, InputLabel} from "@mui/material";
 import Box from "@mui/material/Box";
 import Switch from "@mui/material/Switch";
 import {ErrorMessage, Field, useFormikContext} from "formik";
-import React, {useState} from "react";
-import AceEditor from "react-ace";
 import colors from "qqq/assets/theme/base/colors";
 import BooleanFieldSwitch from "qqq/components/forms/BooleanFieldSwitch";
+import DynamicFormUtils from "qqq/components/forms/DynamicFormUtils";
+import DynamicSelect from "qqq/components/forms/DynamicSelect";
 import MDInput from "qqq/components/legacy/MDInput";
 import MDTypography from "qqq/components/legacy/MDTypography";
+import React, {useMemo, useState} from "react";
+import AceEditor from "react-ace";
+import {flushSync} from "react-dom";
 
 // Declaring props types for FormField
 interface Props
@@ -39,6 +43,10 @@ interface Props
    value: any;
    type: string;
    isEditable?: boolean;
+   placeholder?: string;
+   backgroundColor?: string;
+
+   onChangeCallback?: (newValue: any) => void;
 
    [key: string]: any;
 
@@ -48,7 +56,7 @@ interface Props
 }
 
 function QDynamicFormField({
-   label, name, displayFormat, value, bulkEditMode, bulkEditSwitchChangeHandler, type, isEditable, formFieldObject, ...rest
+   label, name, displayFormat, value, bulkEditMode, bulkEditSwitchChangeHandler, type, isEditable, placeholder, backgroundColor, formFieldObject, onChangeCallback, ...rest
 }: Props): JSX.Element
 {
    const [switchChecked, setSwitchChecked] = useState(false);
@@ -64,18 +72,30 @@ function QDynamicFormField({
       inputLabelProps.shrink = true;
    }
 
-   const inputProps = {};
+   const inputProps: any = {};
    if (displayFormat && displayFormat.startsWith("$"))
    {
-      // @ts-ignore
       inputProps.startAdornment = <InputAdornment position="start">$</InputAdornment>;
    }
    if (displayFormat && displayFormat.endsWith("%%"))
    {
-      // @ts-ignore
       inputProps.endAdornment = <InputAdornment position="end">%</InputAdornment>;
    }
 
+   if (placeholder)
+   {
+      inputProps.placeholder = placeholder;
+   }
+
+   if (backgroundColor)
+   {
+      inputProps.sx = {
+         "&.MuiInputBase-root": {
+            backgroundColor: backgroundColor
+         }
+      };
+   }
+
    // @ts-ignore
    const handleOnWheel = (e) =>
    {
@@ -85,13 +105,95 @@ function QDynamicFormField({
       }
    };
 
+   ///////////////////////////////////////////////////////////////////////////////////////
+   // check the field meta data for behavior that says to do toUpperCase or toLowerCase //
+   ///////////////////////////////////////////////////////////////////////////////////////
+   let isToUpperCase = useMemo(() => DynamicFormUtils.isToUpperCase(formFieldObject?.fieldMetaData), [formFieldObject]);
+   let isToLowerCase = useMemo(() => DynamicFormUtils.isToLowerCase(formFieldObject?.fieldMetaData), [formFieldObject]);
+
+   ////////////////////////////////////////////////////////////////////////
+   // if the field has a toUpperCase or toLowerCase behavior on it, then //
+   // apply that rule.  But also, to avoid the cursor always jumping to  //
+   // the end of the input, do some manipulation of the selection.       //
+   // See: https://giacomocerquone.com/blog/keep-input-cursor-still      //
+   // Note, we only want an onChange handle if we're doing one of these  //
+   // behaviors, (because teh flushSync is potentially slow).  hence, we //
+   // put the onChange in an object and assign it with a spread          //
+   ////////////////////////////////////////////////////////////////////////
+   let onChange: any = {};
+   if (isToUpperCase || isToLowerCase || onChangeCallback)
+   {
+      onChange.onChange = (e: any) =>
+      {
+         if (isToUpperCase || isToLowerCase)
+         {
+            const beforeStart = e.target.selectionStart;
+            const beforeEnd = e.target.selectionEnd;
+
+            flushSync(() =>
+            {
+               let newValue = e.currentTarget.value;
+               if (isToUpperCase)
+               {
+                  newValue = newValue.toUpperCase();
+               }
+               if (isToLowerCase)
+               {
+                  newValue = newValue.toLowerCase();
+               }
+               setFieldValue(name, newValue);
+               if (onChangeCallback)
+               {
+                  onChangeCallback(newValue);
+               }
+            });
+
+            const input = document.getElementById(name) as HTMLInputElement;
+            if (input)
+            {
+               input.setSelectionRange(beforeStart, beforeEnd);
+            }
+         }
+         else if (onChangeCallback)
+         {
+            onChangeCallback(e.currentTarget.value);
+         }
+      };
+   }
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   function dynamicSelectOnChange(newValue?: QPossibleValue)
+   {
+      if (onChangeCallback)
+      {
+         onChangeCallback(newValue == null ? null : newValue.id);
+      }
+   }
+
    let field;
    let getsBulkEditHtmlLabel = true;
-   if (type === "checkbox")
+   if (formFieldObject.possibleValueProps)
+   {
+      field = (<DynamicSelect
+         name={name}
+         fieldPossibleValueProps={formFieldObject.possibleValueProps}
+         isEditable={!isDisabled}
+         fieldLabel={label}
+         initialValue={value}
+         bulkEditMode={bulkEditMode}
+         bulkEditSwitchChangeHandler={bulkEditSwitchChangeHandler}
+         onChange={dynamicSelectOnChange}
+         // otherValues={otherValuesMap}
+         useCase="form"
+      />);
+   }
+   else if (type === "checkbox")
    {
       getsBulkEditHtmlLabel = false;
       field = (<>
-         <BooleanFieldSwitch name={name} label={label} value={value} isDisabled={isDisabled} />
+         <BooleanFieldSwitch name={name} label={label} value={value} isDisabled={isDisabled} onChangeCallback={onChangeCallback} />
          <Box mt={0.75}>
             <MDTypography component="div" variant="caption" color="error" fontWeight="regular">
                {!isDisabled && <div className="fieldErrorMessage"><ErrorMessage name={name} render={msg => <span data-field-error="true">{msg}</span>} /></div>}
@@ -102,7 +204,7 @@ function QDynamicFormField({
    else if (type === "ace")
    {
       let mode = "text";
-      if(formFieldObject && formFieldObject.languageMode)
+      if (formFieldObject && formFieldObject.languageMode)
       {
          mode = formFieldObject.languageMode;
       }
@@ -119,6 +221,10 @@ function QDynamicFormField({
                onChange={(value: string, event: any) =>
                {
                   setFieldValue(name, value, false);
+                  if (onChangeCallback)
+                  {
+                     onChangeCallback(value);
+                  }
                }}
                setOptions={{useWorker: false}}
                width="100%"
@@ -133,7 +239,7 @@ function QDynamicFormField({
    {
       field = (
          <>
-            <Field {...rest} onWheel={handleOnWheel} name={name} type={type} as={MDInput} variant="outlined" label={label} InputLabelProps={inputLabelProps} InputProps={inputProps} fullWidth disabled={isDisabled}
+            <Field {...rest} {...onChange} onWheel={handleOnWheel} name={name} type={type} as={MDInput} variant="outlined" label={label} InputLabelProps={inputLabelProps} InputProps={inputProps} fullWidth disabled={isDisabled}
                onKeyPress={(e: any) =>
                {
                   if (e.key === "Enter")
@@ -173,7 +279,8 @@ function QDynamicFormField({
                   id={`bulkEditSwitch-${name}`}
                   checked={switchChecked}
                   onClick={bulkEditSwitchChanged}
-                  sx={{top: "-4px",
+                  sx={{
+                     top: "-4px",
                      "& .MuiSwitch-track": {
                         height: 20,
                         borderRadius: 10,

src/qqq/components/forms/DynamicFormUtils.ts

@@ -22,6 +22,7 @@
 import {AdornmentType} from "@kingsrook/qqq-frontend-core/lib/model/metaData/AdornmentType";
 import {QFieldMetaData} from "@kingsrook/qqq-frontend-core/lib/model/metaData/QFieldMetaData";
 import {QFieldType} from "@kingsrook/qqq-frontend-core/lib/model/metaData/QFieldType";
+import {FieldPossibleValueProps} from "qqq/models/fields/FieldPossibleValueProps";
 import * as Yup from "yup";
 
 
@@ -129,18 +130,11 @@ class DynamicFormUtils
 
       if (effectivelyIsRequired)
       {
-         if (field.possibleValueSourceName)
-         {
-            ////////////////////////////////////////////////////////////////////////////////////////////
-            // the "nullable(true)" here doesn't mean that you're allowed to set the field to null... //
-            // rather, it's more like "null is how empty will be treated" or some-such...             //
-            ////////////////////////////////////////////////////////////////////////////////////////////
-            return (Yup.string().required(`${field.label} is required.`).nullable(true));
-         }
-         else
-         {
-            return (Yup.string().required(`${field.label} is required.`));
-         }
+         ////////////////////////////////////////////////////////////////////////////////////////////
+         // the "nullable(true)" here doesn't mean that you're allowed to set the field to null... //
+         // rather, it's more like "null is how empty will be treated" or some-such...             //
+         ////////////////////////////////////////////////////////////////////////////////////////////
+         return (Yup.string().required(`${field.label ?? "This field"} is required.`).nullable(true));
       }
       return (null);
    }
@@ -155,35 +149,54 @@ class DynamicFormUtils
       {
          const field = qFields[i];
 
+         if(!dynamicFormFields[field.name])
+         {
+            continue;
+         }
+
          /////////////////////////////////////////
          // add props for possible value fields //
          /////////////////////////////////////////
-         if (field.possibleValueSourceName && dynamicFormFields[field.name])
+         if (field.possibleValueSourceName || field.inlinePossibleValueSource)
          {
-            let initialDisplayValue = null;
+            let props: FieldPossibleValueProps =
+               {
+                  isPossibleValue: true,
+                  fieldName: field.name,
+                  initialDisplayValue: null
+               }
+
             if (displayValues)
             {
-               initialDisplayValue = displayValues.get(field.name);
+               props.initialDisplayValue = displayValues.get(field.name);
             }
 
-            if (tableName)
+            if(field.inlinePossibleValueSource)
             {
-               dynamicFormFields[field.name].possibleValueProps =
-                  {
-                     isPossibleValue: true,
-                     tableName: tableName,
-                     initialDisplayValue: initialDisplayValue,
-                  };
+               //////////////////////////////////////////////////////////////////////
+               // handle an inline PVS - which is a list of possible value objects //
+               //////////////////////////////////////////////////////////////////////
+               props.possibleValues = field.inlinePossibleValueSource;
+            }
+            else if (tableName)
+            {
+               props.tableName = tableName;
+            }
+            else if (processName)
+            {
+               props.processName = processName;
             }
             else
             {
-               dynamicFormFields[field.name].possibleValueProps =
-                  {
-                     isPossibleValue: true,
-                     processName: processName,
-                     initialDisplayValue: initialDisplayValue,
-                  };
+               props.possibleValueSourceName = field.possibleValueSourceName;
             }
+
+            if(field.possibleValueSourceFilter)
+            {
+               props.possibleValueSourceFilter = field.possibleValueSourceFilter;
+            }
+
+            dynamicFormFields[field.name].possibleValueProps = props;
          }
       }
    }
@@ -202,7 +215,7 @@ class DynamicFormUtils
 
       if (Array.isArray(disabledFields))
       {
-         return (disabledFields.indexOf(fieldName) > -1)
+         return (disabledFields.indexOf(fieldName) > -1);
       }
       else
       {
@@ -210,6 +223,44 @@ class DynamicFormUtils
       }
    }
 
+
+   /***************************************************************************
+    * check if a field has the TO_UPPER_CASE behavior on it.
+    ***************************************************************************/
+   public static isToUpperCase(fieldMetaData: QFieldMetaData): boolean
+   {
+      return this.hasBehavior(fieldMetaData, "TO_UPPER_CASE");
+   }
+
+
+   /***************************************************************************
+    * check if a field has the TO_LOWER_CASE behavior on it.
+    ***************************************************************************/
+   public static isToLowerCase(fieldMetaData: QFieldMetaData): boolean
+   {
+      return this.hasBehavior(fieldMetaData, "TO_LOWER_CASE");
+   }
+
+
+   /***************************************************************************
+    * check if a field has a specific behavior name on it.
+    ***************************************************************************/
+   private static hasBehavior(fieldMetaData: QFieldMetaData, behaviorName: string): boolean
+   {
+      if (fieldMetaData && fieldMetaData.behaviors)
+      {
+         for (let i = 0; i < fieldMetaData.behaviors.length; i++)
+         {
+            if (fieldMetaData.behaviors[i] == behaviorName)
+            {
+               return (true);
+            }
+         }
+      }
+
+      return (false);
+   }
+
 }
 
 export default DynamicFormUtils;

src/qqq/components/forms/DynamicSelect.tsx

@@ -30,20 +30,18 @@ import TextField from "@mui/material/TextField";
 import {ErrorMessage, useFormikContext} from "formik";
 import colors from "qqq/assets/theme/base/colors";
 import MDTypography from "qqq/components/legacy/MDTypography";
+import {FieldPossibleValueProps} from "qqq/models/fields/FieldPossibleValueProps";
 import Client from "qqq/utils/qqq/Client";
 import React, {useEffect, useState} from "react";
 
 interface Props
 {
-   tableName?: string;
-   processName?: string;
-   fieldName?: string;
-   possibleValueSourceName?: string;
+   fieldPossibleValueProps: FieldPossibleValueProps;
    overrideId?: string;
+   name?: string;
    fieldLabel: string;
    inForm: boolean;
    initialValue?: any;
-   initialDisplayValue?: string;
    initialValues?: QPossibleValue[];
    onChange?: any;
    isEditable?: boolean;
@@ -53,16 +51,12 @@ interface Props
    otherValues?: Map<string, any>;
    variant: "standard" | "outlined";
    initiallyOpen: boolean;
+   useCase: "form" | "filter";
 }
 
 DynamicSelect.defaultProps = {
-   tableName: null,
-   processName: null,
-   fieldName: null,
-   possibleValueSourceName: null,
    inForm: true,
    initialValue: null,
-   initialDisplayValue: null,
    initialValues: undefined,
    onChange: null,
    isEditable: true,
@@ -97,51 +91,49 @@ export const getAutocompleteOutlinedStyle = (isDisabled: boolean) =>
          borderColor: inputBorderColor
       }
    });
-}
+};
 
 
 const qController = Client.getInstance();
 
-function DynamicSelect({tableName, processName, fieldName, possibleValueSourceName, overrideId, fieldLabel, inForm, initialValue, initialDisplayValue, initialValues, onChange, isEditable, isMultiple, bulkEditMode, bulkEditSwitchChangeHandler, otherValues, variant, initiallyOpen}: Props)
+function DynamicSelect({fieldPossibleValueProps, overrideId, name, fieldLabel, inForm, initialValue, initialValues, onChange, isEditable, isMultiple, bulkEditMode, bulkEditSwitchChangeHandler, otherValues, variant, initiallyOpen, useCase}: Props)
 {
+   const {fieldName, initialDisplayValue, possibleValueSourceName, possibleValues, processName, tableName} = fieldPossibleValueProps;
+
    const [open, setOpen] = useState(initiallyOpen);
    const [options, setOptions] = useState<readonly QPossibleValue[]>([]);
    const [searchTerm, setSearchTerm] = useState(null);
    const [firstRender, setFirstRender] = useState(true);
-   const [otherValuesWhenResultsWereLoaded, setOtherValuesWhenResultsWereLoaded] = useState(JSON.stringify(Object.fromEntries((otherValues))))
+   const [otherValuesWhenResultsWereLoaded, setOtherValuesWhenResultsWereLoaded] = useState(JSON.stringify(Object.fromEntries((otherValues))));
 
    useEffect(() =>
    {
-      if(tableName && processName)
+      if (tableName && processName)
       {
-         console.log("DynamicSelect - you may not provide both a tableName and a processName")
+         console.log("DynamicSelect - you may not provide both a tableName and a processName");
       }
-      if(tableName && !fieldName)
+      if (tableName && !fieldName)
       {
          console.log("DynamicSelect - if you provide a tableName, you must also provide a fieldName");
       }
-      if(processName && !fieldName)
+      if (processName && !fieldName)
       {
          console.log("DynamicSelect - if you provide a processName, you must also provide a fieldName");
       }
-      if(fieldName && possibleValueSourceName)
-      {
-         console.log("DynamicSelect - if you provide a fieldName and a possibleValueSourceName, the possibleValueSourceName will be ignored");
-      }
-      if(!fieldName && !possibleValueSourceName)
+      if (!fieldName && !possibleValueSourceName)
       {
          console.log("DynamicSelect - you must provide either a fieldName (and a tableName or processName) or a possibleValueSourceName");
       }
-      if(fieldName)
+      if (fieldName && !possibleValueSourceName)
       {
-         if(!tableName || !processName)
+         if (!tableName || !processName)
          {
-            console.log("DynamicSelect - if you provide a fieldName, you must also provide a tableName or processName");
+            console.log("DynamicSelect - if you provide a fieldName and not a possibleValueSourceName, then you must also provide a tableName or processName");
          }
       }
-      if(possibleValueSourceName)
+      if (possibleValueSourceName)
       {
-         if(tableName || processName)
+         if (tableName || processName)
          {
             console.log("DynamicSelect - if you provide a possibleValueSourceName, you should not also provide a tableName or processName");
          }
@@ -175,9 +167,47 @@ function DynamicSelect({tableName, processName, fieldName, possibleValueSourceNa
       setFieldValueRef = setFieldValue;
    }
 
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   const filterInlinePossibleValues = (searchTerm: string, possibleValues: QPossibleValue[]): QPossibleValue[] =>
+   {
+      return possibleValues.filter(pv => pv.label?.toLowerCase().startsWith(searchTerm));
+   };
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   const loadResults = async (): Promise<QPossibleValue[]> =>
+   {
+      if (possibleValues)
+      {
+         return filterInlinePossibleValues(searchTerm, possibleValues);
+      }
+      else
+      {
+         return await qController.possibleValues(
+            {
+               tableName,
+               processName,
+               fieldNameOrPossibleValueSourceName: possibleValueSourceName ?? fieldName,
+               searchTerm: searchTerm ?? "",
+               values: otherValues,
+               useCase,
+               possibleValueSourceFilter: fieldPossibleValueProps.possibleValueSourceFilter
+            });
+      }
+   };
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
    useEffect(() =>
    {
-      if(firstRender)
+      if (firstRender)
       {
          // console.log("First render, so not searching...");
          setFirstRender(false);
@@ -198,9 +228,9 @@ function DynamicSelect({tableName, processName, fieldName, possibleValueSourceNa
       (async () =>
       {
          // console.log(`doing a search with ${searchTerm}`);
-         const results: QPossibleValue[] = await qController.possibleValues(tableName, processName, fieldName ?? possibleValueSourceName, searchTerm ?? "", null, otherValues);
+         const results: QPossibleValue[] = await loadResults();
 
-         if(tableMetaData == null && tableName)
+         if (tableMetaData == null && tableName)
          {
             let tableMetaData: QTableMetaData = await qController.loadTableMetaData(tableName);
             setTableMetaData(tableMetaData);
@@ -211,7 +241,7 @@ function DynamicSelect({tableName, processName, fieldName, possibleValueSourceNa
          // console.log(`${results}`);
          if (active)
          {
-            setOptions([ ...results ]);
+            setOptions([...results]);
          }
       })();
 
@@ -219,50 +249,67 @@ function DynamicSelect({tableName, processName, fieldName, possibleValueSourceNa
       {
          active = false;
       };
-   }, [ searchTerm ]);
+   }, [searchTerm]);
 
-   // todo - finish... call it in onOpen?
+
+   /***************************************************************************
+    ** todo - finish... call it in onOpen?
+    ***************************************************************************/
    const reloadIfOtherValuesAreChanged = () =>
    {
-      if(JSON.stringify(Object.fromEntries(otherValues)) != otherValuesWhenResultsWereLoaded)
+      if (JSON.stringify(Object.fromEntries(otherValues)) != otherValuesWhenResultsWereLoaded)
       {
          (async () =>
          {
             setLoading(true);
             setOptions([]);
+
             console.log("Refreshing possible values...");
-            const results: QPossibleValue[] = await qController.possibleValues(tableName, processName, fieldName ?? possibleValueSourceName, searchTerm ?? "", null, otherValues);
+            const results: QPossibleValue[] = await loadResults();
+
             setLoading(false);
-            setOptions([ ...results ]);
+            setOptions([...results]);
             setOtherValuesWhenResultsWereLoaded(JSON.stringify(Object.fromEntries(otherValues)));
          })();
       }
-   }
+   };
 
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
    const inputChanged = (event: React.SyntheticEvent, value: string, reason: string) =>
    {
       // console.log(`input changed.  Reason: ${reason}, setting search term to ${value}`);
-      if(reason !== "reset")
+      if (reason !== "reset")
       {
          // console.log(` -> setting search term to ${value}`);
          setSearchTerm(value);
       }
    };
 
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
    const handleBlur = (x: any) =>
    {
       setSearchTerm(null);
-   }
+   };
 
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
    const handleChanged = (event: React.SyntheticEvent, value: any | any[], reason: string, details?: string) =>
    {
       // console.log("handleChanged.  value is:");
       // console.log(value);
       setSearchTerm(null);
 
-      if(onChange)
+      if (onChange)
       {
-         if(isMultiple)
+         if (isMultiple)
          {
             onChange(value);
          }
@@ -271,12 +318,16 @@ function DynamicSelect({tableName, processName, fieldName, possibleValueSourceNa
             onChange(value ? new QPossibleValue(value) : null);
          }
       }
-      else if(setFieldValueRef && fieldName)
+      else if (setFieldValueRef && fieldName)
       {
          setFieldValueRef(fieldName, value ? value.id : null);
       }
    };
 
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
    const filterOptions = (options: { id: any; label: string; }[], state: FilterOptionsState<{ id: any; label: string; }>): { id: any; label: string; }[] =>
    {
       /////////////////////////////////////////////////////////////////////////////////
@@ -284,8 +335,12 @@ function DynamicSelect({tableName, processName, fieldName, possibleValueSourceNa
       // get options whose text/label matches the input (e.g., not ids that match)   //
       /////////////////////////////////////////////////////////////////////////////////
       return (options);
-   }
+   };
 
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
    // @ts-ignore
    const renderOption = (props: Object, option: any, {selected}) =>
    {
@@ -293,23 +348,24 @@ function DynamicSelect({tableName, processName, fieldName, possibleValueSourceNa
 
       try
       {
-         const field = tableMetaData?.fields.get(fieldName)
-         if(field)
+         const field = tableMetaData?.fields.get(fieldName);
+         if (field)
          {
             const adornment = field.getAdornment(AdornmentType.CHIP);
-            if(adornment)
+            if (adornment)
             {
-               const color = adornment.getValue("color." + option.id) ?? "default"
+               const color = adornment.getValue("color." + option.id) ?? "default";
                const iconName = adornment.getValue("icon." + option.id) ?? null;
                const iconElement = iconName ? <Icon>{iconName}</Icon> : null;
                content = (<Chip label={option.label} color={color} icon={iconElement} size="small" variant="outlined" sx={{fontWeight: 500}} />);
             }
          }
       }
-      catch(e)
-      { }
+      catch (e)
+      {
+      }
 
-      if(isMultiple)
+      if (isMultiple)
       {
          content = (
             <>
@@ -331,8 +387,12 @@ function DynamicSelect({tableName, processName, fieldName, possibleValueSourceNa
             {content}
          </li>
       );
-   }
+   };
 
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
    const bulkEditSwitchChanged = () =>
    {
       const newSwitchValue = !switchChecked;
@@ -353,7 +413,8 @@ function DynamicSelect({tableName, processName, fieldName, possibleValueSourceNa
    const autocomplete = (
       <Box>
          <Autocomplete
-            id={overrideId ?? fieldName ?? possibleValueSourceName}
+            id={overrideId ?? fieldName ?? possibleValueSourceName ?? "anonymous"}
+            name={name}
             sx={autocompleteSX}
             open={open}
             fullWidth
@@ -361,7 +422,7 @@ function DynamicSelect({tableName, processName, fieldName, possibleValueSourceNa
             {
                setOpen(true);
                // console.log("setting open...");
-               if(options.length == 0)
+               if (options.length == 0)
                {
                   // console.log("no options yet, so setting search term to ''...");
                   setSearchTerm("");
@@ -374,19 +435,19 @@ function DynamicSelect({tableName, processName, fieldName, possibleValueSourceNa
             isOptionEqualToValue={(option, value) => value !== null && value !== undefined && option.id === value.id}
             getOptionLabel={(option) =>
             {
-               if(option === null || option === undefined)
+               if (option === null || option === undefined)
                {
                   return ("");
                }
 
                // @ts-ignore
-               if(option && option.length)
+               if (option && option.length)
                {
                   // @ts-ignore
                   option = option[0];
                }
                // @ts-ignore
-               return option.label
+               return option.label;
             }}
             options={options}
             loading={loading}
@@ -433,7 +494,7 @@ function DynamicSelect({tableName, processName, fieldName, possibleValueSourceNa
             inForm &&
             <Box mt={0.75}>
                <MDTypography component="div" variant="caption" color="error" fontWeight="regular">
-                  {!isDisabled && <div className="fieldErrorMessage"><ErrorMessage name={fieldName ?? possibleValueSourceName} render={msg => <span data-field-error="true">{msg}</span>} /></div>}
+                  {!isDisabled && <div className="fieldErrorMessage"><ErrorMessage name={overrideId ?? fieldName ?? possibleValueSourceName ?? "anonymous"} render={msg => <span data-field-error="true">{msg}</span>} /></div>}
                </MDTypography>
             </Box>
          }
@@ -450,7 +511,8 @@ function DynamicSelect({tableName, processName, fieldName, possibleValueSourceNa
                   id={`bulkEditSwitch-${fieldName}`}
                   checked={switchChecked}
                   onClick={bulkEditSwitchChanged}
-                  sx={{top: "-4px",
+                  sx={{
+                     top: "-4px",
                      "& .MuiSwitch-track": {
                         height: 20,
                         borderRadius: 10,
@@ -469,7 +531,7 @@ function DynamicSelect({tableName, processName, fieldName, possibleValueSourceNa
    else
    {
       return (
-         <Box mb={1.5}>
+         <Box>
             {autocomplete}
          </Box>
       );

src/qqq/components/forms/FileInputField.tsx

@@ -0,0 +1,156 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2024.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+
+import {AdornmentType} from "@kingsrook/qqq-frontend-core/lib/model/metaData/AdornmentType";
+import {QFieldMetaData} from "@kingsrook/qqq-frontend-core/lib/model/metaData/QFieldMetaData";
+import {QFieldType} from "@kingsrook/qqq-frontend-core/lib/model/metaData/QFieldType";
+import {QRecord} from "@kingsrook/qqq-frontend-core/lib/model/QRecord";
+import {Button, colors, Icon} from "@mui/material";
+import Box from "@mui/material/Box";
+import Tooltip from "@mui/material/Tooltip";
+import {useFormikContext} from "formik";
+import MDTypography from "qqq/components/legacy/MDTypography";
+import ValueUtils from "qqq/utils/qqq/ValueUtils";
+import React, {useCallback, useState} from "react";
+import {useDropzone} from "react-dropzone";
+
+interface FileInputFieldProps
+{
+   field: any,
+   record?: QRecord,
+   errorMessage?: any
+}
+
+export default function FileInputField({field, record, errorMessage}: FileInputFieldProps): JSX.Element
+{
+   const [fileName, setFileName] = useState(null as string);
+
+   const formikProps = useFormikContext();
+
+   const fileChanged = (event: React.FormEvent<HTMLInputElement>, field: any) =>
+   {
+      setFileName(null);
+      if (event.currentTarget.files && event.currentTarget.files[0])
+      {
+         setFileName(event.currentTarget.files[0].name);
+      }
+
+      formikProps.setFieldValue(field.name, event.currentTarget.files[0]);
+   };
+
+   const onDrop = useCallback((acceptedFiles: any) =>
+   {
+      setFileName(null);
+      if (acceptedFiles.length && acceptedFiles[0])
+      {
+         setFileName(acceptedFiles[0].name);
+      }
+
+      formikProps.setFieldValue(field.name, acceptedFiles[0]);
+   }, []);
+   const {getRootProps, getInputProps, isDragActive} = useDropzone({onDrop});
+
+
+   const removeFile = (fieldName: string) =>
+   {
+      setFileName(null);
+      formikProps.setFieldValue(fieldName, null);
+      record?.values.delete(fieldName);
+      record?.displayValues.delete(fieldName);
+   };
+
+   const pseudoField = new QFieldMetaData({name: field.name, type: QFieldType.BLOB});
+
+   const fileUploadAdornment = field.fieldMetaData?.getAdornment(AdornmentType.FILE_UPLOAD);
+   const format = fileUploadAdornment?.values?.get("format") ?? "button";
+
+   return (
+      <Box mb={1.5}>
+         {
+            record && record.values.get(field.name) && <Box fontSize="0.875rem" pb={1}>
+               Current File:
+               <Box display="inline-flex" pl={1}>
+                  {ValueUtils.getDisplayValue(pseudoField, record, "view")}
+                  <Tooltip placement="bottom" title="Remove current file">
+                     <Icon className="blobIcon" fontSize="small" onClick={(e) => removeFile(field.name)}>delete</Icon>
+                  </Tooltip>
+               </Box>
+            </Box>
+         }
+
+         {
+            format == "button" &&
+               <Box display="flex" alignItems="center">
+                  <Button variant="outlined" component="label">
+                     <span style={{color: colors.lightBlue[500]}}>Choose file to upload</span>
+                     <input
+                        id={field.name}
+                        name={field.name}
+                        type="file"
+                        hidden
+                        onChange={(event: React.FormEvent<HTMLInputElement>) => fileChanged(event, field)}
+                     />
+                  </Button>
+                  <Box ml={1} fontSize={"1rem"}>
+                     {fileName}
+                  </Box>
+               </Box>
+         }
+
+         {
+            format == "dragAndDrop" &&
+            <>
+               <Box {...getRootProps()} sx={
+                  {
+                     display: "flex",
+                     alignItems: "center",
+                     justifyContent: "center",
+                     width: "100%",
+                     height: "300px",
+                     borderRadius: "2rem",
+                     backgroundColor: isDragActive ? colors.lightBlue[50] : "transparent",
+                     border: `2px ${isDragActive ? "solid" : "dashed"} ${colors.lightBlue[500]}`
+                  }}>
+                  <input {...getInputProps()} />
+                  <Box display="flex" alignItems="center" flexDirection="column">
+                     <Icon sx={{fontSize: "4rem !important", color: colors.lightBlue[500]}}>upload_file</Icon>
+                     <Box>Drag and drop a file</Box>
+                     <Box fontSize="1rem" m="0.5rem">or</Box>
+                     <Box border={`2px solid ${colors.lightBlue[500]}`} mt="0.25rem" padding="0.25rem 1rem" borderRadius="0.5rem" sx={{cursor: "pointer"}} fontSize="1rem">
+                        Browse files
+                     </Box>
+                  </Box>
+               </Box>
+               <Box fontSize={"1rem"} mt="0.25rem">
+                  {fileName}&nbsp;
+               </Box>
+            </>
+         }
+
+         <Box mt={0.75}>
+            <MDTypography component="div" variant="caption" color="error" fontWeight="regular">
+               {errorMessage && <span>{errorMessage}</span>}
+            </MDTypography>
+         </Box>
+      </Box>
+   );
+}

src/qqq/components/horseshoe/Breadcrumbs.tsx

@@ -63,7 +63,7 @@ function QBreadcrumbs({icon, title, route, light}: Props): JSX.Element
    ///////////////////////////////////////////////////////////////////////
    // strip away empty elements of the route (e.g., trailing slash(es)) //
    ///////////////////////////////////////////////////////////////////////
-   if(route.length)
+   if (route.length)
    {
       // @ts-ignore
       route = route.filter(r => r != "");
@@ -74,18 +74,18 @@ function QBreadcrumbs({icon, title, route, light}: Props): JSX.Element
 
    const fullPathToLabel = (fullPath: string, route: string): string =>
    {
-      if(fullPath.endsWith("/"))
+      if (fullPath.endsWith("/"))
       {
          fullPath = fullPath.replace(/\/+$/, "");
       }
 
-      if(pathToLabelMap && pathToLabelMap[fullPath])
+      if (pathToLabelMap && pathToLabelMap[fullPath])
       {
          return pathToLabelMap[fullPath];
       }
 
       return (routeToLabel(route));
-   }
+   };
 
    let pageTitle = branding?.appName ?? "";
    const fullRoutes: string[] = [];
@@ -94,21 +94,24 @@ function QBreadcrumbs({icon, title, route, light}: Props): JSX.Element
    {
       ////////////////////////////////////////////////////////
       // avoid showing "saved view" as a breadcrumb element //
+      // e.g., if at /app/table/savedView/1                 //
       ////////////////////////////////////////////////////////
-      if(routes[i] === "savedView")
+      if (routes[i] === "savedView" && i == routes.length - 1)
       {
          continue;
       }
 
       ///////////////////////////////////////////////////////////////////////
       // avoid showing the table name if it's the element before savedView //
+      // e.g., when at /app/table/savedView/1 (so where i==1)              //
+      // we want to just be showing "App"                                  //
       ///////////////////////////////////////////////////////////////////////
-      if(i < routes.length - 1 && routes[i+1] == "savedView")
+      if (i < routes.length - 1 && routes[i + 1] == "savedView" && i == 1)
       {
          continue;
       }
 
-      if(routes[i] === "")
+      if (routes[i] === "")
       {
          continue;
       }

src/qqq/components/horseshoe/Footer.tsx

@@ -64,13 +64,14 @@ function Footer({company, links}: Props): JSX.Element
       <Box
          width="100%"
          display="flex"
-         flexDirection={{xs: "column", lg: "row"}}
+         flexDirection={{xs: "column", md: "row"}}
          justifyContent="space-between"
          alignItems="center"
          px={1.5}
          style={{
             position: "fixed", bottom: "0px", zIndex: -1, marginBottom: "10px",
          }}
+         left={{xs: "0", xl: "auto"}}
       >
          {
             href && name &&

src/qqq/components/horseshoe/NavBar.tsx

@@ -19,16 +19,16 @@
  * along with this program.  If not, see <https://www.gnu.org/licenses/>.
  */
 
-import {Popper, InputAdornment} from "@mui/material";
+import {Popper, InputAdornment, Box} from "@mui/material";
 import AppBar from "@mui/material/AppBar";
 import Autocomplete from "@mui/material/Autocomplete";
-import Box from "@mui/material/Box";
 import Icon from "@mui/material/Icon";
 import IconButton from "@mui/material/IconButton";
 import ListItemIcon from "@mui/material/ListItemIcon";
+import {Theme} from "@mui/material/styles";
 import TextField from "@mui/material/TextField";
 import Toolbar from "@mui/material/Toolbar";
-import React, {useContext, useEffect, useState} from "react";
+import React, {useContext, useEffect, useRef, useState} from "react";
 import {useLocation, useNavigate} from "react-router-dom";
 import QContext from "QContext";
 import QBreadcrumbs, {routeToLabel} from "qqq/components/horseshoe/Breadcrumbs";
@@ -45,7 +45,8 @@ interface Props
    isMini?: boolean;
 }
 
-interface HistoryEntry {
+interface HistoryEntry
+{
    id: number;
    path: string;
    label: string;
@@ -64,7 +65,7 @@ function NavBar({absolute, light, isMini}: Props): JSX.Element
    const route = useLocation().pathname.split("/").slice(1);
    const navigate = useNavigate();
 
-   const {pageHeader} = useContext(QContext);
+   const {pageHeader, setDotMenuOpen} = useContext(QContext);
 
    useEffect(() =>
    {
@@ -99,7 +100,7 @@ function NavBar({absolute, light, isMini}: Props): JSX.Element
       const options = [] as any;
       history.entries.reverse().forEach((entry, index) =>
          options.push({label: `${entry.label} index`, id: index, key: index, path: entry.path, iconName: entry.iconName})
-      )
+      );
       setHistory(options);
 
       // Remove event listener on cleanup
@@ -111,7 +112,7 @@ function NavBar({absolute, light, isMini}: Props): JSX.Element
    const goToHistory = (path: string) =>
    {
       navigate(path);
-   }
+   };
 
    function buildHistoryEntries()
    {
@@ -119,7 +120,7 @@ function NavBar({absolute, light, isMini}: Props): JSX.Element
       const options = [] as any;
       history.entries.reverse().forEach((entry, index) =>
          options.push({label: entry.label, id: index, key: index, path: entry.path, iconName: entry.iconName})
-      )
+      );
       setHistory(options);
    }
 
@@ -133,12 +134,12 @@ function NavBar({absolute, light, isMini}: Props): JSX.Element
 
    const handleAutocompleteOnChange = (event: any, value: any, reason: any, details: any) =>
    {
-      if(value)
+      if (value)
       {
          goToHistory(value.path);
       }
       setAutocompleteValue(null);
-   }
+   };
 
    const CustomPopper = function (props: any)
    {
@@ -146,8 +147,8 @@ function NavBar({absolute, light, isMini}: Props): JSX.Element
          {...props}
          style={{whiteSpace: "nowrap", width: "auto"}}
          placement="bottom-end"
-      />)
-   }
+      />);
+   };
 
    const renderHistory = () =>
    {
@@ -166,7 +167,7 @@ function NavBar({absolute, light, isMini}: Props): JSX.Element
             PopperComponent={CustomPopper}
             isOptionEqualToValue={(option, value) => option.id === value.id}
             sx={recentlyViewedMenu}
-            renderInput={(params) => <TextField {...params}  label="Recently Viewed Records" InputProps={{
+            renderInput={(params) => <TextField {...params} label="Recently Viewed Records" InputProps={{
                ...params.InputProps,
                endAdornment: (
                   <InputAdornment position="end">
@@ -184,7 +185,7 @@ function NavBar({absolute, light, isMini}: Props): JSX.Element
             )}
          />
       );
-   }
+   };
 
    // Styles for the navbar icons
    const iconsStyle = ({
@@ -210,21 +211,34 @@ function NavBar({absolute, light, isMini}: Props): JSX.Element
    const {pathToLabelMap} = useContext(QContext);
    const fullPathToLabel = (fullPath: string, route: string): string =>
    {
-      if(fullPath.endsWith("/"))
+      if (fullPath.endsWith("/"))
       {
          fullPath = fullPath.replace(/\/+$/, "");
       }
 
-      if(pathToLabelMap && pathToLabelMap[fullPath])
+      if (pathToLabelMap && pathToLabelMap[fullPath])
       {
          return pathToLabelMap[fullPath];
       }
 
       return (routeToLabel(route));
-   }
+   };
 
    const breadcrumbTitle = fullPathToLabel(fullPath, route[route.length - 1]);
 
+   ///////////////////////////////////////////////////////////////////////////////////////////////
+   // set the right-half of the navbar up so that below the 'md' breakpoint, it just disappears //
+   ///////////////////////////////////////////////////////////////////////////////////////////////
+   const navbarRowRight = (theme: Theme, {isMini}: any) =>
+   {
+      return {
+         [theme.breakpoints.down("md")]: {
+            display: "none",
+         },
+         ...navbarRow(theme, isMini)
+      }
+   };
+
    return (
       <AppBar
          position={absolute ? "absolute" : navbarType}
@@ -241,17 +255,22 @@ function NavBar({absolute, light, isMini}: Props): JSX.Element
                <QBreadcrumbs icon="home" title={breadcrumbTitle} route={route} light={light} />
             </Box>
             {isMini ? null : (
-               <Box sx={(theme) => navbarRow(theme, {isMini})}>
-                  <Box pr={0} mr={-2}>
+               <Box sx={(theme) => navbarRowRight(theme, {isMini})}>
+                  <Box mt={"-0.25rem"} pb={"0.75rem"} pr={2} mr={-2} sx={{"& *": {cursor: "pointer !important"}}}>
                      {renderHistory()}
                   </Box>
+                  <Box mt={"-1rem"}>
+                     <IconButton size="small" disableRipple color="inherit" onClick={() => setDotMenuOpen(true)}>
+                        <Icon sx={iconsStyle} fontSize="small">search</Icon>
+                     </IconButton>
+                  </Box>
                </Box>
             )}
          </Toolbar>
          {
             pageHeader &&
             <Box display="flex" justifyContent="space-between">
-               <MDTypography pb="0.5rem" textTransform="capitalize" variant="h3" color={light ? "white" : "dark"} noWrap>
+               <MDTypography pb="0.5rem" variant="h3" color={light ? "white" : "dark"} noWrap>
                   {pageHeader}
                </MDTypography>
             </Box>

src/qqq/components/horseshoe/sidenav/SideNav.tsx

@@ -20,21 +20,22 @@
  */
 
 import {QBrandingMetaData} from "@kingsrook/qqq-frontend-core/lib/model/metaData/QBrandingMetaData";
+import {Button} from "@mui/material";
 import Box from "@mui/material/Box";
 import Divider from "@mui/material/Divider";
 import Icon from "@mui/material/Icon";
 import Link from "@mui/material/Link";
 import List from "@mui/material/List";
-import {ReactNode, useEffect, useReducer, useState} from "react";
-import {NavLink, useLocation} from "react-router-dom";
-import AuthenticationButton from "qqq/components/buttons/AuthenticationButton";
 import SideNavCollapse from "qqq/components/horseshoe/sidenav/SideNavCollapse";
 import SideNavItem from "qqq/components/horseshoe/sidenav/SideNavItem";
 import SideNavList from "qqq/components/horseshoe/sidenav/SideNavList";
 import SidenavRoot from "qqq/components/horseshoe/sidenav/SideNavRoot";
 import sidenavLogoLabel from "qqq/components/horseshoe/sidenav/styles/SideNav";
 import MDTypography from "qqq/components/legacy/MDTypography";
+import {getBannerClassName, getBannerStyles, getBanner, makeBannerContent} from "qqq/components/misc/Banners";
 import {setMiniSidenav, setTransparentSidenav, setWhiteSidenav, useMaterialUIController,} from "qqq/context";
+import {ReactNode, useEffect, useReducer, useState} from "react";
+import {NavLink, useLocation} from "react-router-dom";
 
 
 interface Props
@@ -44,6 +45,7 @@ interface Props
    logo?: string;
    appName?: string;
    branding?: QBrandingMetaData;
+   logout: () => void;
    routes: {
       [key: string]:
          | ReactNode
@@ -66,7 +68,7 @@ interface Props
    [key: string]: any;
 }
 
-function Sidenav({color, icon, logo, appName, branding, routes, ...rest}: Props): JSX.Element
+function Sidenav({color, icon, logo, appName, branding, routes, logout, ...rest}: Props): JSX.Element
 {
    const [openCollapse, setOpenCollapse] = useState<boolean | string>(false);
    const [openNestedCollapse, setOpenNestedCollapse] = useState<boolean | string>(false);
@@ -257,7 +259,7 @@ function Sidenav({color, icon, logo, appName, branding, routes, ...rest}: Props)
                      active={key === collapseName}
                      open={openCollapse === key}
                      noCollapse={noCollapse}
-                     onClick={() => (! noCollapse ? (openCollapse === key ? setOpenCollapse(false) : setOpenCollapse(key)) : null) }
+                     onClick={() => (!noCollapse ? (openCollapse === key ? setOpenCollapse(false) : setOpenCollapse(key)) : null)}
                   >
                      {collapse ? renderCollapse(collapse) : null}
                   </SideNavCollapse>
@@ -300,6 +302,30 @@ function Sidenav({color, icon, logo, appName, branding, routes, ...rest}: Props)
       }
    );
 
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   function EnvironmentBanner({branding}: { branding: QBrandingMetaData }): JSX.Element | null
+   {
+      // deprecated!
+      if (branding && branding.environmentBannerText)
+      {
+         return <Box mt={2} bgcolor={branding.environmentBannerColor} borderRadius={2}>
+            {branding.environmentBannerText}
+         </Box>;
+      }
+
+      const banner = getBanner(branding, "QFMD_SIDE_NAV_UNDER_LOGO");
+      if (banner)
+      {
+         return <Box className={getBannerClassName(banner)} mt={2} borderRadius={2} sx={getBannerStyles(banner)}>
+            {makeBannerContent(banner)}
+         </Box>;
+      }
+
+      return (null);
+   }
+
    return (
       <SidenavRoot
          {...rest}
@@ -330,12 +356,7 @@ function Sidenav({color, icon, logo, appName, branding, routes, ...rest}: Props)
                </Box>
                }
             </Box>
-            {
-               branding && branding.environmentBannerText &&
-               <Box mt={2} bgcolor={branding.environmentBannerColor} borderRadius={2}>
-                  {branding.environmentBannerText}
-               </Box>
-            }
+            <EnvironmentBanner branding={branding} />
          </Box>
          <Divider
             light={
@@ -350,7 +371,7 @@ function Sidenav({color, icon, logo, appName, branding, routes, ...rest}: Props)
                (darkMode && !transparentSidenav && whiteSidenav)
             }
          />
-         <AuthenticationButton />
+         <Button onClick={logout}>Log Out</Button>
       </SidenavRoot>
    );
 }

src/qqq/components/horseshoe/sidenav/SideNavRoot.tsx

@@ -97,6 +97,7 @@ export default styled(Drawer)(({theme, ownerState}: { theme?: Theme | any; owner
          margin: "0",
          borderRadius: "0",
          height: "100%",
+         top: "unset",
 
          ...(miniSidenav ? drawerCloseStyles() : drawerOpenStyles()),
       },

src/qqq/components/misc/Banners.tsx

@@ -0,0 +1,97 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+import {Banner} from "@kingsrook/qqq-frontend-core/lib/model/metaData/Banner";
+import {QBrandingMetaData} from "@kingsrook/qqq-frontend-core/lib/model/metaData/QBrandingMetaData";
+import parse from "html-react-parser";
+
+/////////////////////////////////////////////////////////////////////////////////////////////////////////////
+// One may render a banner using the functions in this file as:                                            //
+//                                                                                                         //
+// const banner = getBanner(branding, "QFMD_SIDE_NAV_UNDER_LOGO");                                         //
+// return (<Box className={getBannerClassName(banner)} sx={{padding: "1rem", ...getBannerStyles(banner)}}> //
+//    {makeBannerContent(banner)}                                                                          //
+// </Box>);                                                                                                //
+/////////////////////////////////////////////////////////////////////////////////////////////////////////////
+
+
+/***************************************************************************
+ **
+ ***************************************************************************/
+export function getBanner(branding: QBrandingMetaData, slot: string): Banner | null
+{
+   if (branding?.banners?.has(slot))
+   {
+      return (branding.banners.get(slot));
+   }
+
+   return (null);
+}
+
+
+/***************************************************************************
+ **
+ ***************************************************************************/
+export function getBannerStyles(banner: Banner)
+{
+   let bgColor = "";
+   let color = "";
+
+   if (banner)
+   {
+      if (banner.backgroundColor)
+      {
+         bgColor = banner.backgroundColor;
+      }
+
+      if (banner.textColor)
+      {
+         bgColor = banner.textColor;
+      }
+   }
+
+   const rest = banner?.additionalStyles ?? {};
+
+   return ({
+      backgroundColor: bgColor,
+      color: color,
+      ...rest
+   });
+}
+
+
+/***************************************************************************
+ **
+ ***************************************************************************/
+export function getBannerClassName(banner: Banner)
+{
+   return `banner ${banner?.severity?.toLowerCase()}`;
+}
+
+
+/***************************************************************************
+ **
+ ***************************************************************************/
+export function makeBannerContent(banner: Banner): JSX.Element
+{
+   return <>{banner?.messageHTML ? parse(banner?.messageHTML) : banner?.messageText}</>;
+}
+

src/qqq/components/misc/ErrorBoundary.tsx

@@ -0,0 +1,74 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2024.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+import React, {Component, ErrorInfo} from "react";
+
+interface Props
+{
+   errorElement?: React.ReactNode;
+   children: React.ReactNode;
+}
+
+interface State
+{
+   hasError: boolean;
+}
+
+/*******************************************************************************
+ ** Component that you can wrap around other components that might throw an error,
+ ** to give some isolation, rather than breaking a whole page.
+ ** Credit: https://medium.com/@bobjunior542/how-to-use-error-boundaries-in-react-js-with-typescript-ee90ec814bf1
+ *******************************************************************************/
+class ErrorBoundary extends Component<Props, State>
+{
+   /***************************************************************************
+    *
+    ***************************************************************************/
+   constructor(props: Props)
+   {
+      super(props);
+      this.state = {hasError: false};
+   }
+
+   /***************************************************************************
+    *
+    ***************************************************************************/
+   componentDidCatch(error: Error, errorInfo: ErrorInfo)
+   {
+      console.error("ErrorBoundary caught an error: ", error, errorInfo);
+      this.setState({hasError: true});
+   }
+
+   /***************************************************************************
+    *
+    ***************************************************************************/
+   render()
+   {
+      if (this.state.hasError)
+      {
+         return this.props.errorElement ?? <span>(Error)</span>;
+      }
+
+      return this.props.children;
+   }
+}
+
+export default ErrorBoundary;

src/qqq/components/misc/FieldAutoComplete.tsx

@@ -20,6 +20,7 @@
  */
 
 
+import {QExposedJoin} from "@kingsrook/qqq-frontend-core/lib/model/metaData/QExposedJoin";
 import {QFieldMetaData} from "@kingsrook/qqq-frontend-core/lib/model/metaData/QFieldMetaData";
 import {QInstance} from "@kingsrook/qqq-frontend-core/lib/model/metaData/QInstance";
 import {QTableMetaData} from "@kingsrook/qqq-frontend-core/lib/model/metaData/QTableMetaData";
@@ -27,25 +28,26 @@ import {Box} from "@mui/material";
 import Autocomplete, {AutocompleteRenderOptionState} from "@mui/material/Autocomplete";
 import Icon from "@mui/material/Icon";
 import TextField from "@mui/material/TextField";
-import React, {ReactNode, useState} from "react";
+import React, {ReactNode, useMemo, useState} from "react";
 
 interface FieldAutoCompleteProps
 {
-   id: string;
-   metaData: QInstance;
-   tableMetaData: QTableMetaData;
-   handleFieldChange: (event: any, newValue: any, reason: string) => void;
-   defaultValue?: { field: QFieldMetaData, table: QTableMetaData, fieldName: string };
-   autoFocus?: boolean;
-   forceOpen?: boolean;
-   hiddenFieldNames?: string[];
-   availableFieldNames?: string[];
-   variant?: "standard" | "filled" | "outlined";
-   label?: string;
-   textFieldSX?: any;
-   autocompleteSlotProps?: any;
-   hasError?: boolean;
-   noOptionsText?: string;
+   id: string,
+   metaData: QInstance,
+   tableMetaData: QTableMetaData,
+   handleFieldChange: (event: any, newValue: any, reason: string) => void,
+   defaultValue?: { field: QFieldMetaData, table: QTableMetaData, fieldName: string },
+   autoFocus?: boolean,
+   forceOpen?: boolean,
+   hiddenFieldNames?: string[],
+   availableFieldNames?: string[],
+   variant?: "standard" | "filled" | "outlined",
+   label?: string,
+   textFieldSX?: any,
+   autocompleteSlotProps?: any,
+   hasError?: boolean,
+   noOptionsText?: string,
+   omitExposedJoins?: string[]
 }
 
 FieldAutoComplete.defaultProps =
@@ -88,7 +90,7 @@ function makeFieldOptionsForTable(tableMetaData: QTableMetaData, fieldOptions: a
 /*******************************************************************************
  ** Component for rendering a list of field names from a table as an auto-complete.
  *******************************************************************************/
-export default function FieldAutoComplete({id, metaData, tableMetaData, handleFieldChange, defaultValue, autoFocus, forceOpen, hiddenFieldNames, availableFieldNames, variant, label, textFieldSX, autocompleteSlotProps, hasError, noOptionsText}: FieldAutoCompleteProps): JSX.Element
+export default function FieldAutoComplete({id, metaData, tableMetaData, handleFieldChange, defaultValue, autoFocus, forceOpen, hiddenFieldNames, availableFieldNames, variant, label, textFieldSX, autocompleteSlotProps, hasError, noOptionsText, omitExposedJoins}: FieldAutoCompleteProps): JSX.Element
 {
    const [selectedFieldName, setSelectedFieldName] = useState(defaultValue ? defaultValue.fieldName : null);
 
@@ -96,11 +98,25 @@ export default function FieldAutoComplete({id, metaData, tableMetaData, handleFi
    makeFieldOptionsForTable(tableMetaData, fieldOptions, false, hiddenFieldNames, availableFieldNames, selectedFieldName);
    let fieldsGroupBy = null;
 
-   if (tableMetaData.exposedJoins && tableMetaData.exposedJoins.length > 0)
+   const availableExposedJoins = useMemo(() =>
    {
-      for (let i = 0; i < tableMetaData.exposedJoins.length; i++)
+      const rs: QExposedJoin[] = []
+      for(let exposedJoin of tableMetaData.exposedJoins ?? [])
       {
-         const exposedJoin = tableMetaData.exposedJoins[i];
+         if(omitExposedJoins?.indexOf(exposedJoin.joinTable.name) > -1)
+         {
+            continue;
+         }
+         rs.push(exposedJoin);
+      }
+      return (rs);
+   }, [tableMetaData, omitExposedJoins]);
+
+   if (availableExposedJoins && availableExposedJoins.length > 0)
+   {
+      for (let i = 0; i < availableExposedJoins.length; i++)
+      {
+         const exposedJoin = availableExposedJoins[i];
          if (metaData.tables.has(exposedJoin.joinTable.name))
          {
             fieldsGroupBy = (option: any) => `${option.table.label} fields`;
@@ -185,7 +201,7 @@ export default function FieldAutoComplete({id, metaData, tableMetaData, handleFi
                {originalEndAdornment}
             </Box>;
 
-            return (<TextField {...params} autoFocus={autoFocus} label={label} variant={variant} sx={textFieldSX} autoComplete="off" type="search" InputProps={inputProps} />)
+            return (<TextField {...params} autoFocus={autoFocus} label={label} variant={variant} sx={textFieldSX} autoComplete="off" type="search" InputProps={inputProps} />);
          }}
          // @ts-ignore
          defaultValue={defaultValue}

src/qqq/components/misc/GotoRecordDialog.tsx

@@ -20,6 +20,7 @@
  */
 
 import {QFieldMetaData} from "@kingsrook/qqq-frontend-core/lib/model/metaData/QFieldMetaData";
+import {QFieldType} from "@kingsrook/qqq-frontend-core/lib/model/metaData/QFieldType";
 import {QInstance} from "@kingsrook/qqq-frontend-core/lib/model/metaData/QInstance";
 import {QTableMetaData} from "@kingsrook/qqq-frontend-core/lib/model/metaData/QTableMetaData";
 import {QTableVariant} from "@kingsrook/qqq-frontend-core/lib/model/metaData/QTableVariant";
@@ -35,11 +36,11 @@ import DialogTitle from "@mui/material/DialogTitle";
 import Grid from "@mui/material/Grid";
 import Icon from "@mui/material/Icon";
 import TextField from "@mui/material/TextField";
-import React, {useState} from "react";
-import {useNavigate} from "react-router-dom";
 import {QCancelButton} from "qqq/components/buttons/DefaultButtons";
 import MDButton from "qqq/components/legacy/MDButton";
 import Client from "qqq/utils/qqq/Client";
+import React, {useState} from "react";
+import {useNavigate} from "react-router-dom";
 
 interface Props
 {
@@ -71,7 +72,12 @@ function hasGotoFieldNames(tableMetaData: QTableMetaData): boolean
 
 function GotoRecordDialog(props: Props): JSX.Element
 {
-   const fields: QFieldMetaData[] = [];
+   ///////////////////////////////////////////////////////////////////////////////////////////////////////////////
+   // this is an array of array of fields.                                                                      //
+   // that is - each entry in the top-level array is a set of fields that can be used together to goto a record //
+   // such as (pkey), (ukey-field1,ukey-field2).                                                                //
+   ///////////////////////////////////////////////////////////////////////////////////////////////////////////////
+   const options: QFieldMetaData[][] = [];
 
    let pkey = props?.tableMetaData?.fields.get(props?.tableMetaData?.primaryKeyField);
    let addedPkey = false;
@@ -82,31 +88,38 @@ function GotoRecordDialog(props: Props): JSX.Element
       {
          for (let i = 0; i < mdbMetaData.gotoFieldNames.length; i++)
          {
-            // todo - multi-field keys!!
-            let fieldName = mdbMetaData.gotoFieldNames[i][0];
-            let field = props.tableMetaData.fields.get(fieldName);
-            if (field)
+            const option: QFieldMetaData[] = [];
+            options.push(option);
+            for (let j = 0; j < mdbMetaData.gotoFieldNames[i].length; j++)
             {
-               fields.push(field);
-
-               if (field.name == pkey.name)
+               let fieldName = mdbMetaData.gotoFieldNames[i][j];
+               let field = props.tableMetaData.fields.get(fieldName);
+               if (field)
                {
-                  addedPkey = true;
+                  option.push(field);
+
+                  if (pkey != null && field.name == pkey.name)
+                  {
+                     addedPkey = true;
+                  }
                }
             }
          }
       }
    }
 
+   //////////////////////////////////////////////////////////////////////////////////////////
+   // if pkey wasn't in the gotoField options meta-data, go ahead add it as an option here //
+   //////////////////////////////////////////////////////////////////////////////////////////
    if (pkey && !addedPkey)
    {
-      fields.unshift(pkey);
+      options.unshift([pkey]);
    }
 
    const makeInitialValues = () =>
    {
       const rs = {} as { [field: string]: string };
-      fields.forEach((field) => rs[field.name] = "");
+      options.forEach((option) => option.forEach((field) => rs[field.name] = ""));
       return (rs);
    };
 
@@ -141,11 +154,16 @@ function GotoRecordDialog(props: Props): JSX.Element
       }
       else if (e.key == "Enter" && targetId?.startsWith("gotoInput-"))
       {
-         const index = targetId?.replaceAll("gotoInput-", "");
+         const parts = targetId?.split(/-/);
+         const index = parts[1];
          document.getElementById("gotoButton-" + index).click();
       }
    };
 
+
+   /***************************************************************************
+    ** event handler for close button
+    ***************************************************************************/
    const closeRequested = () =>
    {
       if (props.mayClose)
@@ -154,10 +172,51 @@ function GotoRecordDialog(props: Props): JSX.Element
       }
    };
 
-   const goClicked = async (fieldName: string) =>
+
+   /*******************************************************************************
+    ** function to say if an option's submit button should be disabled
+    *******************************************************************************/
+   const isOptionSubmitButtonDisabled = (optionIndex: number) =>
+   {
+      let anyFieldsInThisOptionHaveAValue = false;
+
+      options[optionIndex].forEach((field) =>
+      {
+         if (values[field.name])
+         {
+            anyFieldsInThisOptionHaveAValue = true;
+         }
+      });
+
+      if (!anyFieldsInThisOptionHaveAValue)
+      {
+         return (true);
+      }
+      return (false);
+   };
+
+
+   /***************************************************************************
+    ** event handler for clicking an 'option's go/submit button
+    ***************************************************************************/
+   const optionGoClicked = async (optionIndex: number) =>
    {
       setError("");
-      const filter = new QQueryFilter([new QFilterCriteria(fieldName, QCriteriaOperator.EQUALS, [values[fieldName]])], null, null, "AND", null, 10);
+
+      const criteria: QFilterCriteria[] = [];
+      const queryStringParts: string[] = [];
+      options[optionIndex].forEach((field) =>
+      {
+         if (field.type == QFieldType.STRING && !values[field.name])
+         {
+            return;
+         }
+         criteria.push(new QFilterCriteria(field.name, QCriteriaOperator.EQUALS, [values[field.name]]));
+         queryStringParts.push(`${field.name}=${encodeURIComponent(values[field.name])}`);
+      });
+
+      const filter = new QQueryFilter(criteria, null, null, "AND", null, 10);
+
       try
       {
          const queryResult = await qController.query(props.tableMetaData.name, filter, null, props.tableVariant);
@@ -168,12 +227,26 @@ function GotoRecordDialog(props: Props): JSX.Element
          }
          else if (queryResult.length == 1)
          {
-            navigate(`${props.metaData.getTablePathByName(props.tableMetaData.name)}/${encodeURIComponent(queryResult[0].values.get(props.tableMetaData.primaryKeyField))}`);
+            if (options[optionIndex].length == 1 && options[optionIndex][0].name == pkey?.name)
+            {
+               /////////////////////////////////////////////////
+               // navigate by pkey, if that's how we searched //
+               /////////////////////////////////////////////////
+               navigate(`${props.metaData.getTablePathByName(props.tableMetaData.name)}/${encodeURIComponent(queryResult[0].values.get(props.tableMetaData.primaryKeyField))}`);
+            }
+            else
+            {
+               /////////////////////////////////
+               // else navigate by unique-key //
+               /////////////////////////////////
+               navigate(`${props.metaData.getTablePathByName(props.tableMetaData.name)}/key/?${queryStringParts.join("&")}`);
+            }
+
             close();
          }
          else
          {
-            setError("More than 1 record found...");
+            setError("More than 1 record was found...");
             setTimeout(() => setError(""), 3000);
          }
       }
@@ -187,7 +260,7 @@ function GotoRecordDialog(props: Props): JSX.Element
 
    if (props.tableMetaData)
    {
-      if (fields.length == 0 && !error)
+      if (options.length == 0 && !error)
       {
          setError("This table is not configured for this feature.");
       }
@@ -200,31 +273,38 @@ function GotoRecordDialog(props: Props): JSX.Element
          <DialogContent>
             {props.subHeader}
             {
-               fields.map((field, index) =>
-                  (
-                     <Grid key={field.name} container alignItems="center" py={1}>
-                        <Grid item xs={3} textAlign="right" pr={2}>
-                           {field.label}
-                        </Grid>
-                        <Grid item xs={6}>
-                           <TextField
-                              id={`gotoInput-${index}`}
-                              autoFocus={index == 0}
-                              autoComplete="off"
-                              inputProps={{width: "100%"}}
-                              onChange={(e) => handleChange(field.name, e.target.value)}
-                              value={values[field.name]}
-                              sx={{width: "100%"}}
-                              onFocus={event => event.target.select()}
-                           />
-                        </Grid>
-                        <Grid item xs={1} pl={2}>
-                           <MDButton id={`gotoButton-${index}`} type="submit" variant="gradient" color="info" size="small" onClick={() => goClicked(field.name)} fullWidth startIcon={<Icon>double_arrow</Icon>} disabled={`${values[field.name]}`.length == 0}>
-                              Go
-                           </MDButton>
-                        </Grid>
-                     </Grid>
-                  ))
+               options.map((option, optionIndex) =>
+                  <Box key={optionIndex}>
+                     {
+                        option.map((field, index) =>
+                           (
+                              <Grid key={field.name} container alignItems="center" py={1}>
+                                 <Grid item xs={3} textAlign="right" pr={2}>
+                                    {field.label}
+                                 </Grid>
+                                 <Grid item xs={6}>
+                                    <TextField
+                                       id={`gotoInput-${optionIndex}-${index}`}
+                                       autoFocus={optionIndex == 0 && index == 0}
+                                       autoComplete="off"
+                                       inputProps={{width: "100%"}}
+                                       onChange={(e) => handleChange(field.name, e.target.value)}
+                                       value={values[field.name]}
+                                       sx={{width: "100%"}}
+                                       onFocus={event => event.target.select()}
+                                    />
+                                 </Grid>
+                                 <Grid item xs={1} pl={2}>
+                                    {
+                                       (index == option.length - 1) &&
+                                       <MDButton id={`gotoButton-${optionIndex}`} type="submit" variant="gradient" color="info" size="small" onClick={() => optionGoClicked(optionIndex)} fullWidth startIcon={<Icon>double_arrow</Icon>} disabled={isOptionSubmitButtonDisabled(optionIndex)}>Go</MDButton>
+                                    }
+                                 </Grid>
+                              </Grid>
+                           ))
+                     }
+                  </Box>
+               )
             }
             {
                error &&
@@ -282,7 +362,7 @@ export function GotoRecordButton(props: GotoRecordButtonProps): JSX.Element
    return (
       <React.Fragment>
          {
-            props.buttonVisible && hasGotoFieldNames(props.tableMetaData) && <Button onClick={openGoto}>Go To...</Button>
+            props.buttonVisible && hasGotoFieldNames(props.tableMetaData) && <Button onClick={openGoto} sx={{whiteSpace: "nowrap"}}>Go To...</Button>
          }
          <GotoRecordDialog metaData={props.metaData} tableMetaData={props.tableMetaData} tableVariant={props.tableVariant} isOpen={gotoIsOpen} closeHandler={closeGoto} mayClose={props.mayClose} subHeader={props.subHeader} />
       </React.Fragment>

src/qqq/components/misc/HelpContent.tsx

@@ -22,6 +22,7 @@
 import {QHelpContent} from "@kingsrook/qqq-frontend-core/lib/model/metaData/QHelpContent";
 import Box from "@mui/material/Box";
 import parse from "html-react-parser";
+import ErrorBoundary from "qqq/components/misc/ErrorBoundary";
 import React, {useContext} from "react";
 import Markdown from "react-markdown";
 import QContext from "QContext";
@@ -128,6 +129,7 @@ function HelpContent({helpContents, roles, heading, helpContentKey}: Props): JSX
    let selectedHelpContent = getMatchingHelpContent(helpContentsArray, roles);
 
    let content = null;
+   let errorContent = "Error rendering help content.";
    if (helpHelpActive)
    {
       if (!selectedHelpContent)
@@ -135,6 +137,7 @@ function HelpContent({helpContents, roles, heading, helpContentKey}: Props): JSX
          selectedHelpContent = new QHelpContent({content: ""});
       }
       content = selectedHelpContent.content + ` [${helpContentKey ?? "?"}]`;
+      errorContent += ` [${helpContentKey ?? "?"}]`;
    }
    else if(selectedHelpContent)
    {
@@ -148,7 +151,9 @@ function HelpContent({helpContents, roles, heading, helpContentKey}: Props): JSX
    {
       return <Box display="inline" className="helpContent">
          {heading && <span className="header">{heading}</span>}
-         {formatHelpContent(content, selectedHelpContent.format)}
+         <ErrorBoundary errorElement={<i>{errorContent}</i>}>
+            {formatHelpContent(content, selectedHelpContent.format)}
+         </ErrorBoundary>
       </Box>;
    }
 

src/qqq/components/misc/QHierarchyAutoComplete.tsx

@@ -0,0 +1,795 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2024.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+
+import Box from "@mui/material/Box";
+import Button from "@mui/material/Button";
+import FormControlLabel from "@mui/material/FormControlLabel";
+import Icon from "@mui/material/Icon";
+import IconButton from "@mui/material/IconButton";
+import List from "@mui/material/List/List";
+import ListItem, {ListItemProps} from "@mui/material/ListItem/ListItem";
+import Menu from "@mui/material/Menu";
+import Switch from "@mui/material/Switch";
+import TextField from "@mui/material/TextField";
+import Tooltip from "@mui/material/Tooltip/Tooltip";
+import React, {useState} from "react";
+
+export type Option = { label: string, value: string | number, [key: string]: any }
+
+export type Group = { label: string, value: string | number, options: Option[], subGroups?: Group[], [key: string]: any }
+
+type StringOrNumber = string | number
+
+interface QHierarchyAutoCompleteProps
+{
+   idPrefix: string;
+   heading?: string;
+   placeholder?: string;
+   defaultGroup: Group;
+   showGroupHeaderEvenIfNoSubGroups: boolean;
+   optionValuesToHide?: StringOrNumber[];
+   buttonProps: any;
+   buttonChildren: JSX.Element | string;
+   menuDirection: "down" | "up";
+
+   isModeSelectOne?: boolean;
+   keepOpenAfterSelectOne?: boolean;
+   handleSelectedOption?: (option: Option, group: Group) => void;
+
+   isModeToggle?: boolean;
+   toggleStates?: { [optionValue: string]: boolean };
+   disabledStates?: { [optionValue: string]: boolean };
+   tooltips?: { [optionValue: string]: string };
+   handleToggleOption?: (option: Option, group: Group, newValue: boolean) => void;
+
+   optionEndAdornment?: JSX.Element;
+   handleAdornmentClick?: (option: Option, group: Group, event: React.MouseEvent<any>) => void;
+   forceRerender?: number
+}
+
+QHierarchyAutoComplete.defaultProps = {
+   menuDirection: "down",
+   showGroupHeaderEvenIfNoSubGroups: false,
+   isModeSelectOne: false,
+   keepOpenAfterSelectOne: false,
+   isModeToggle: false,
+};
+
+interface GroupWithOptions
+{
+   group?: Group;
+   options: Option[];
+}
+
+
+/***************************************************************************
+ ** a sort of re-implementation of Autocomplete, that can display headers
+ ** & children, which may be collapsable (Is that only for toggle mode?)
+ ** but which also can have adornments that trigger actions, or be in a
+ ** single-click-do-something mode.
+ *
+ ** Originally built just for fields  exposed on a table query screen, but
+ ** then factored out of that for use in bulk-load (where it wasn't based on
+ ** exposed joins).
+ ***************************************************************************/
+export default function QHierarchyAutoComplete({idPrefix, heading, placeholder, defaultGroup, showGroupHeaderEvenIfNoSubGroups, optionValuesToHide, buttonProps, buttonChildren, isModeSelectOne, keepOpenAfterSelectOne, isModeToggle, handleSelectedOption, toggleStates, disabledStates, tooltips, handleToggleOption, optionEndAdornment, handleAdornmentClick, menuDirection, forceRerender}: QHierarchyAutoCompleteProps): JSX.Element
+{
+   const [menuAnchorElement, setMenuAnchorElement] = useState(null);
+   const [searchText, setSearchText] = useState("");
+   const [focusedIndex, setFocusedIndex] = useState(null as number);
+
+   const [optionsByGroup, setOptionsByGroup] = useState([] as GroupWithOptions[]);
+   const [collapsedGroups, setCollapsedGroups] = useState({} as { [groupValue: string | number]: boolean });
+
+   const [lastMouseOverXY, setLastMouseOverXY] = useState({x: 0, y: 0});
+   const [timeOfLastArrow, setTimeOfLastArrow] = useState(0);
+
+   //////////////////
+   // check usages //
+   //////////////////
+   if(isModeSelectOne)
+   {
+      if(!handleSelectedOption)
+      {
+         throw("In QAutoComplete, if isModeSelectOne=true, then a callback for handleSelectedOption must be provided.");
+      }
+   }
+
+   if(isModeToggle)
+   {
+      if(!toggleStates)
+      {
+         throw("In QAutoComplete, if isModeToggle=true, then a model for toggleStates must be provided.");
+      }
+      if(!handleToggleOption)
+      {
+         throw("In QAutoComplete, if isModeToggle=true, then a callback for handleToggleOption must be provided.");
+      }
+   }
+
+   /////////////////////
+   // init some stuff //
+   /////////////////////
+   if (optionsByGroup.length == 0)
+   {
+      collapsedGroups[defaultGroup.value] = false;
+
+      if (defaultGroup.subGroups?.length > 0)
+      {
+         /////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+         // if we have exposed joins, put the table meta data with its fields, and then all of the join tables & fields too //
+         /////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+         optionsByGroup.push({group: defaultGroup, options: getGroupOptionsAsAlphabeticalArray(defaultGroup)});
+
+         for (let i = 0; i < defaultGroup.subGroups?.length; i++)
+         {
+            const subGroup = defaultGroup.subGroups[i];
+            optionsByGroup.push({group: subGroup, options: getGroupOptionsAsAlphabeticalArray(subGroup)});
+
+            collapsedGroups[subGroup.value] = false;
+         }
+      }
+      else
+      {
+         ///////////////////////////////////////////////////////////
+         // no exposed joins - just the table (w/o its meta-data) //
+         ///////////////////////////////////////////////////////////
+         optionsByGroup.push({options: getGroupOptionsAsAlphabeticalArray(defaultGroup)});
+      }
+
+      setOptionsByGroup(optionsByGroup);
+      setCollapsedGroups(collapsedGroups);
+   }
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   function getGroupOptionsAsAlphabeticalArray(group: Group): Option[]
+   {
+      const options: Option[] = [];
+      group.options.forEach(option =>
+      {
+         let fullOptionValue = option.value;
+         if(group.value != defaultGroup.value)
+         {
+            fullOptionValue = `${defaultGroup.value}.${option.value}`;
+         }
+
+         if(optionValuesToHide && optionValuesToHide.indexOf(fullOptionValue) > -1)
+         {
+            return;
+         }
+         options.push(option)
+      });
+      options.sort((a, b) => a.label.localeCompare(b.label));
+      return (options);
+   }
+
+
+   const optionsByGroupToShow: GroupWithOptions[] = [];
+   let maxOptionIndex = 0;
+   optionsByGroup.forEach((groupWithOptions) =>
+   {
+      let optionsToShowForThisGroup = groupWithOptions.options.filter(doesOptionMatchSearchText);
+      if (optionsToShowForThisGroup.length > 0)
+      {
+         optionsByGroupToShow.push({group: groupWithOptions.group, options: optionsToShowForThisGroup});
+         maxOptionIndex += optionsToShowForThisGroup.length;
+      }
+   });
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   function doesOptionMatchSearchText(option: Option): boolean
+   {
+      if (searchText == "")
+      {
+         return (true);
+      }
+
+      const columnLabelMinusTable = option.label.replace(/.*: /, "");
+      if (columnLabelMinusTable.toLowerCase().startsWith(searchText.toLowerCase()))
+      {
+         return (true);
+      }
+
+      try
+      {
+         ////////////////////////////////////////////////////////////
+         // try to match word-boundary followed by the filter text //
+         // e.g., "name" would match "First Name" or "Last Name"   //
+         ////////////////////////////////////////////////////////////
+         const re = new RegExp("\\b" + searchText.toLowerCase());
+         if (columnLabelMinusTable.toLowerCase().match(re))
+         {
+            return (true);
+         }
+      }
+      catch (e)
+      {
+         //////////////////////////////////////////////////////////////////////////////////
+         // in case text is an invalid regex... well, at least do a starts-with match... //
+         //////////////////////////////////////////////////////////////////////////////////
+         if (columnLabelMinusTable.toLowerCase().startsWith(searchText.toLowerCase()))
+         {
+            return (true);
+         }
+      }
+
+      const tableLabel = option.label.replace(/:.*/, "");
+      if (tableLabel)
+      {
+         try
+         {
+            ////////////////////////////////////////////////////////////
+            // try to match word-boundary followed by the filter text //
+            // e.g., "name" would match "First Name" or "Last Name"   //
+            ////////////////////////////////////////////////////////////
+            const re = new RegExp("\\b" + searchText.toLowerCase());
+            if (tableLabel.toLowerCase().match(re))
+            {
+               return (true);
+            }
+         }
+         catch (e)
+         {
+            //////////////////////////////////////////////////////////////////////////////////
+            // in case text is an invalid regex... well, at least do a starts-with match... //
+            //////////////////////////////////////////////////////////////////////////////////
+            if (tableLabel.toLowerCase().startsWith(searchText.toLowerCase()))
+            {
+               return (true);
+            }
+         }
+      }
+
+      return (false);
+   }
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   function openMenu(event: any)
+   {
+      setFocusedIndex(null);
+      setMenuAnchorElement(event.currentTarget);
+      setTimeout(() =>
+      {
+         document.getElementById(`field-list-dropdown-${idPrefix}-textField`).focus();
+         doSetFocusedIndex(0, true);
+      });
+   }
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   function closeMenu()
+   {
+      setMenuAnchorElement(null);
+   }
+
+
+   /*******************************************************************************
+    ** Event handler for toggling an option in toggle mode
+    *******************************************************************************/
+   function handleOptionToggle(event: React.ChangeEvent<HTMLInputElement>, option: Option, group: Group)
+   {
+      event.stopPropagation();
+      handleToggleOption(option, group, event.target.checked);
+   }
+
+
+   /*******************************************************************************
+    ** Event handler for toggling a group in toggle mode
+    *******************************************************************************/
+   function handleGroupToggle(event: React.ChangeEvent<HTMLInputElement>, group: Group)
+   {
+      event.stopPropagation();
+
+      const optionsList = [...group.options.values()];
+      for (let i = 0; i < optionsList.length; i++)
+      {
+         const option = optionsList[i];
+         if (doesOptionMatchSearchText(option))
+         {
+            handleToggleOption(option, group, event.target.checked);
+         }
+      }
+   }
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   function toggleCollapsedGroup(value: string | number)
+   {
+      collapsedGroups[value] = !collapsedGroups[value];
+      setCollapsedGroups(Object.assign({}, collapsedGroups));
+   }
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   function getShownOptionAndGroupByIndex(targetIndex: number): { option: Option, group: Group }
+   {
+      let index = -1;
+      for (let i = 0; i < optionsByGroupToShow.length; i++)
+      {
+         const groupWithOption = optionsByGroupToShow[i];
+         for (let j = 0; j < groupWithOption.options.length; j++)
+         {
+            index++;
+
+            if (index == targetIndex)
+            {
+               return {option: groupWithOption.options[j], group: groupWithOption.group};
+            }
+         }
+      }
+
+      return (null);
+   }
+
+
+   /*******************************************************************************
+    ** event handler for keys presses
+    *******************************************************************************/
+   function keyDown(event: any)
+   {
+      // console.log(`Event key: ${event.key}`);
+      setTimeout(() => document.getElementById(`field-list-dropdown-${idPrefix}-textField`).focus());
+
+      if (isModeSelectOne && event.key == "Enter" && focusedIndex != null)
+      {
+         setTimeout(() =>
+         {
+            event.stopPropagation();
+
+            const {option, group} = getShownOptionAndGroupByIndex(focusedIndex);
+            if (option)
+            {
+               const fullOptionValue = group && group.value != defaultGroup.value ? `${group.value}.${option.value}` : option.value;
+               const isDisabled = disabledStates && disabledStates[fullOptionValue]
+               if(isDisabled)
+               {
+                  return;
+               }
+
+               if(!keepOpenAfterSelectOne)
+               {
+                  closeMenu();
+               }
+
+               handleSelectedOption(option, group ?? defaultGroup);
+
+            }
+         });
+         return;
+      }
+
+      const keyOffsetMap: { [key: string]: number } = {
+         "End": 10000,
+         "Home": -10000,
+         "ArrowDown": 1,
+         "ArrowUp": -1,
+         "PageDown": 5,
+         "PageUp": -5,
+      };
+
+      const offset = keyOffsetMap[event.key];
+      if (offset)
+      {
+         event.stopPropagation();
+         setTimeOfLastArrow(new Date().getTime());
+
+         if (isModeSelectOne)
+         {
+            let startIndex = focusedIndex;
+            if (offset > 0)
+            {
+               /////////////////
+               // a down move //
+               /////////////////
+               if (startIndex == null)
+               {
+                  startIndex = -1;
+               }
+
+               let goalIndex = startIndex + offset;
+               if (goalIndex > maxOptionIndex - 1)
+               {
+                  goalIndex = maxOptionIndex - 1;
+               }
+
+               doSetFocusedIndex(goalIndex, true);
+            }
+            else
+            {
+               ////////////////
+               // an up move //
+               ////////////////
+               let goalIndex = startIndex + offset;
+               if (goalIndex < 0)
+               {
+                  goalIndex = 0;
+               }
+
+               doSetFocusedIndex(goalIndex, true);
+            }
+         }
+      }
+   }
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   function doSetFocusedIndex(i: number, tryToScrollIntoView: boolean): void
+   {
+      if (isModeSelectOne)
+      {
+         setFocusedIndex(i);
+         console.log(`Setting index to ${i}`);
+
+         if (tryToScrollIntoView)
+         {
+            const element = document.getElementById(`field-list-dropdown-${idPrefix}-${i}`);
+            element?.scrollIntoView({block: "center"});
+         }
+      }
+   }
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   function setFocusedOption(option: Option, group: Group, tryToScrollIntoView: boolean)
+   {
+      let index = -1;
+      for (let i = 0; i < optionsByGroupToShow.length; i++)
+      {
+         const groupWithOption = optionsByGroupToShow[i];
+         for (let j = 0; j < groupWithOption.options.length; j++)
+         {
+            const loopOption = groupWithOption.options[j];
+            index++;
+
+            const groupMatches = (group == null || group.value == groupWithOption.group.value);
+            if (groupMatches && option.value == loopOption.value)
+            {
+               doSetFocusedIndex(index, tryToScrollIntoView);
+               return;
+            }
+         }
+      }
+   }
+
+
+   /*******************************************************************************
+    ** event handler for mouse-over the menu
+    *******************************************************************************/
+   function handleMouseOver(event: React.MouseEvent<HTMLAnchorElement> | React.MouseEvent<HTMLDivElement> | React.MouseEvent<HTMLLIElement>, option: Option, group: Group, isDisabled: boolean)
+   {
+      //////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+      // so we're trying to fix the case where, if you put your mouse over an element, but then press up/down arrows,                                     //
+      // where the mouse will become over a different element after the scroll, and the focus will follow the mouse instead of keyboard.                  //
+      // the last x/y isn't really useful, because the mouse generally isn't left exactly where it was when the mouse-over happened (edge of the element) //
+      // but the keyboard last-arrow time that we capture, that's what's actually being useful in here                                                    //
+      //////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+      if (event.clientX == lastMouseOverXY.x && event.clientY == lastMouseOverXY.y)
+      {
+         // console.log("mouse didn't move, so, doesn't count");
+         return;
+      }
+
+      const now = new Date().getTime();
+      // console.log(`Compare now [${now}] to last arrow [${timeOfLastArrow}] (diff: [${now - timeOfLastArrow}])`);
+      if (now < timeOfLastArrow + 300)
+      {
+         // console.log("An arrow event happened less than 300 mills ago, so doesn't count.");
+         return;
+      }
+
+      // console.log("yay, mouse over...");
+      if(isDisabled)
+      {
+         setFocusedIndex(null);
+      }
+      else
+      {
+         setFocusedOption(option, group, false);
+      }
+      setLastMouseOverXY({x: event.clientX, y: event.clientY});
+   }
+
+
+   /*******************************************************************************
+    ** event handler for text input changes
+    *******************************************************************************/
+   function updateSearch(event: React.ChangeEvent<HTMLInputElement>)
+   {
+      setSearchText(event?.target?.value ?? "");
+      doSetFocusedIndex(0, true);
+   }
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   function doHandleAdornmentClick(option: Option, group: Group, event: React.MouseEvent<any>)
+   {
+      console.log("In doHandleAdornmentClick");
+      closeMenu();
+      handleAdornmentClick(option, group, event);
+   }
+
+   /////////////////////////////////////////////////////////
+   // compute the group-level toggle state & count values //
+   /////////////////////////////////////////////////////////
+   const groupToggleStates: { [value: string]: boolean } = {};
+   const groupToggleCounts: { [value: string]: number } = {};
+
+   if (isModeToggle)
+   {
+      const {allOn, count} = getGroupToggleState(defaultGroup, true);
+      groupToggleStates[defaultGroup.value] = allOn;
+      groupToggleCounts[defaultGroup.value] = count;
+
+      for (let i = 0; i < defaultGroup.subGroups?.length; i++)
+      {
+         const subGroup = defaultGroup.subGroups[i];
+         const {allOn, count} = getGroupToggleState(subGroup, false);
+         groupToggleStates[subGroup.value] = allOn;
+         groupToggleCounts[subGroup.value] = count;
+      }
+   }
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   function getGroupToggleState(group: Group, isMainGroup: boolean): {allOn: boolean, count: number}
+   {
+      const optionsList = [...group.options.values()];
+      let allOn = true;
+      let count = 0;
+      for (let i = 0; i < optionsList.length; i++)
+      {
+         const option = optionsList[i];
+         const name = isMainGroup ? option.value : `${group.value}.${option.value}`;
+         if(!toggleStates[name])
+         {
+            allOn = false;
+         }
+         else
+         {
+            count++;
+         }
+      }
+
+      return ({allOn: allOn, count: count});
+   }
+
+
+   let index = -1;
+   const textFieldId = `field-list-dropdown-${idPrefix}-textField`;
+   let listItemPadding = isModeToggle ? "0.125rem" : "0.5rem";
+
+   ///////////////////////////////////////////////////////////////////////////////////////////////////////////////
+   // for z-indexes, we set each table header to i+1, then the fields in that table to i (so they go behind it) //
+   // then we increment i by 2 for the next table (so the next header goes above the previous header)           //
+   // this fixes a thing where, if one table's name wrapped to 2 lines, then when the next table below it would //
+   // come up, if it was only 1 line, then the second line from the previous one would bleed through.           //
+   ///////////////////////////////////////////////////////////////////////////////////////////////////////////////
+   let zIndex = 1;
+
+   return (
+      <>
+         <Button onClick={openMenu} {...buttonProps}>
+            {buttonChildren}
+         </Button>
+         <Menu
+            anchorEl={menuAnchorElement}
+            anchorOrigin={{vertical: menuDirection == "down" ? "bottom" : "top", horizontal: "left"}}
+            transformOrigin={{vertical: menuDirection == "down" ? "top" : "bottom", horizontal: "left"}}
+            open={menuAnchorElement != null}
+            onClose={closeMenu}
+            onKeyDown={keyDown} // this is added here so arrow-key-up/down events don't make the whole menu become "focused" (blue outline).  it works.
+            keepMounted
+         >
+            <Box width={isModeToggle ? "305px" : "265px"} borderRadius={2} className={`fieldListMenuBody fieldListMenuBody-${idPrefix}`}>
+               {
+                  heading &&
+                  <Box px={1} py={0.5} fontWeight={"700"}>
+                     {heading}
+                  </Box>
+               }
+               <Box p={1} pt={0.5}>
+                  <TextField id={textFieldId} variant="outlined" placeholder={placeholder ?? "Search Fields"} fullWidth value={searchText} onChange={updateSearch} onKeyDown={keyDown} inputProps={{sx: {pr: "2rem"}}} />
+                  {
+                     searchText != "" && <IconButton sx={{position: "absolute", right: "0.5rem", top: "0.5rem"}} onClick={() =>
+                     {
+                        updateSearch(null);
+                        document.getElementById(textFieldId).focus();
+                     }}><Icon fontSize="small">close</Icon></IconButton>
+                  }
+               </Box>
+               <Box maxHeight={"445px"} minHeight={"445px"} overflow="auto" mr={"-0.5rem"} sx={{scrollbarGutter: "stable"}}>
+                  <List sx={{px: "0.5rem", cursor: "default"}}>
+                     {
+                        optionsByGroupToShow.map((groupWithOptions) =>
+                        {
+                           let headerContents = null;
+                           const headerGroup = groupWithOptions.group || defaultGroup;
+                           if (groupWithOptions.group || showGroupHeaderEvenIfNoSubGroups)
+                           {
+                              headerContents = (<b>{headerGroup.label}</b>);
+                           }
+
+                           if (isModeToggle)
+                           {
+                              headerContents = (<FormControlLabel
+                                 sx={{display: "flex", alignItems: "flex-start", "& .MuiFormControlLabel-label": {lineHeight: "1.4", fontWeight: "500 !important"}}}
+                                 control={<Switch
+                                    size="small"
+                                    sx={{top: "1px"}}
+                                    checked={toggleStates[headerGroup.value]}
+                                    onChange={(event) => handleGroupToggle(event, headerGroup)}
+                                 />}
+                                 label={<span style={{marginTop: "0.25rem", display: "inline-block"}}><b>{headerGroup.label} Fields</b>&nbsp;<span style={{fontWeight: 400}}>({groupToggleCounts[headerGroup.value]})</span></span>} />);
+                           }
+
+                           if (isModeToggle)
+                           {
+                              headerContents = (
+                                 <>
+                                    <IconButton
+                                       onClick={() => toggleCollapsedGroup(headerGroup.value)}
+                                       sx={{justifyContent: "flex-start", fontSize: "0.875rem", pt: 0.5, pb: 0, mr: "0.25rem"}}
+                                       disableRipple={true}
+                                    >
+                                       <Icon sx={{fontSize: "1.5rem !important", position: "relative", top: "2px"}}>{collapsedGroups[headerGroup.value] ? "expand_less" : "expand_more"}</Icon>
+                                    </IconButton>
+                                    {headerContents}
+                                 </>
+                              );
+                           }
+
+                           let marginLeft = "unset";
+                           if (isModeToggle)
+                           {
+                              marginLeft = "-1rem";
+                           }
+
+                           zIndex += 2;
+
+                           return (
+                              <React.Fragment key={groupWithOptions.group?.value ?? "theGroup"}>
+                                 <>
+                                    {headerContents && <ListItem sx={{position: "sticky", top: -1, zIndex: zIndex + 1, padding: listItemPadding, ml: marginLeft, display: "flex", alignItems: "flex-start", backgroundImage: "linear-gradient(to bottom, rgba(255,255,255,1), rgba(255,255,255,1) 90%, rgba(255,255,255,0))"}}>{headerContents}</ListItem>}
+                                    {
+                                       groupWithOptions.options.map((option) =>
+                                       {
+                                          index++;
+                                          const key = `${groupWithOptions?.group?.value}-${option.value}`;
+
+                                          let label: JSX.Element | string = option.label;
+                                          const fullOptionValue = groupWithOptions.group && groupWithOptions.group.value != defaultGroup.value ? `${groupWithOptions.group.value}.${option.value}` : option.value;
+                                          const isDisabled = disabledStates && disabledStates[fullOptionValue]
+
+                                          if (collapsedGroups[headerGroup.value])
+                                          {
+                                             return (<React.Fragment key={key} />);
+                                          }
+
+                                          let style = {};
+                                          if (index == focusedIndex)
+                                          {
+                                             style = {backgroundColor: "#EFEFEF"};
+                                          }
+
+                                          const onClick: ListItemProps = {};
+                                          if (isModeSelectOne)
+                                          {
+                                             onClick.onClick = () =>
+                                             {
+                                                if(isDisabled)
+                                                {
+                                                   return;
+                                                }
+
+                                                if(!keepOpenAfterSelectOne)
+                                                {
+                                                   closeMenu();
+                                                }
+                                                handleSelectedOption(option, groupWithOptions.group ?? defaultGroup);
+                                             };
+                                          }
+
+                                          if (optionEndAdornment)
+                                          {
+                                             label = <Box width="100%" display="inline-flex" justifyContent="space-between">
+                                                {label}
+                                                <Box onClick={(event) => handleAdornmentClick(option, groupWithOptions.group, event)}>
+                                                   {optionEndAdornment}
+                                                </Box>
+                                             </Box>;
+                                          }
+
+                                          let contents = <>{label}</>;
+                                          let paddingLeft = "0.5rem";
+
+                                          if (isModeToggle)
+                                          {
+                                             contents = (<FormControlLabel
+                                                sx={{display: "flex", alignItems: "flex-start", "& .MuiFormControlLabel-label": {lineHeight: "1.4", color: "#606060", fontWeight: "500 !important"}}}
+                                                control={<Switch
+                                                   size="small"
+                                                   sx={{top: "-3px"}}
+                                                   checked={toggleStates[fullOptionValue]}
+                                                   onChange={(event) => handleOptionToggle(event, option, groupWithOptions.group)}
+                                                />}
+                                                label={label} />);
+                                             paddingLeft = "2.5rem";
+                                          }
+
+                                          const listItem = <ListItem
+                                             key={key}
+                                             id={`field-list-dropdown-${idPrefix}-${index}`}
+                                             sx={{color: isDisabled ? "#C0C0C0" : "#757575", p: 1, borderRadius: ".5rem", padding: listItemPadding, pl: paddingLeft, scrollMarginTop: "3rem", zIndex: zIndex, background: "#FFFFFF", ...style}}
+                                             onMouseOver={(event) => 
+                                             {
+                                                handleMouseOver(event, option, groupWithOptions.group, isDisabled)
+                                             }}
+                                             {...onClick}
+                                          >{contents}</ListItem>;
+
+                                          if(tooltips[fullOptionValue])
+                                          {
+                                             return <Tooltip key={key} title={tooltips[fullOptionValue]} placement="right" enterDelay={500}>{listItem}</Tooltip>
+                                          }
+                                          else
+                                          {
+
+                                             return listItem
+                                          }
+                                       })
+                                    }
+                                 </>
+                              </React.Fragment>
+                           );
+                        })
+                     }
+                     {
+                        index == -1 && <ListItem sx={{p: "0.5rem"}}><i>No options found.</i></ListItem>
+                     }
+                  </List>
+               </Box>
+            </Box>
+         </Menu>
+      </>
+   );
+}

src/qqq/components/misc/RecordSidebar.tsx

@@ -22,7 +22,7 @@
 import {QTableMetaData} from "@kingsrook/qqq-frontend-core/lib/model/metaData/QTableMetaData";
 import {QTableSection} from "@kingsrook/qqq-frontend-core/lib/model/metaData/QTableSection";
 import {QWidgetMetaData} from "@kingsrook/qqq-frontend-core/lib/model/metaData/QWidgetMetaData";
-import Box from "@mui/material/Box";
+import {Box} from "@mui/material";
 import Card from "@mui/material/Card";
 import Icon from "@mui/material/Icon";
 import {Theme} from "@mui/material/styles";
@@ -76,12 +76,12 @@ function QRecordSidebar({tableSections, widgetMetaDataList, light, stickyTop}: P
 
 
    return (
-      <Card sx={{borderRadius: "0.75rem", position: "sticky", top: stickyTop, overflow: "auto", maxHeight: "calc(100vh - 2rem)"}}>
-         <Box component="ul" display="flex" flexDirection="column" p={2} m={0} sx={{listStyle: "none"}}>
+      <Card sx={{borderRadius: "0.75rem", position: "sticky", top: stickyTop, overflow: "hidden", maxHeight: "calc(100vh - 2rem)"}}>
+         <Box component="ul" display="flex" flexDirection="column" p={2} m={0} sx={{listStyle: "none", overflow: "auto", height: "100%"}}>
             {
                sidebarEntries ? sidebarEntries.map((entry: SidebarEntry, key: number) => (
 
-                  <HashLink key={`section-link-${entry.name}`} to={`#${entry.name}`}>
+                  <Box key={`section-link-${entry.name}`} onClick={() => document.getElementById(entry.name).scrollIntoView()} sx={{cursor: "pointer"}}>
                      <Box key={`section-${entry.name}`} component="li" pt={key === 0 ? 0 : 1}>
                         <MDTypography
                            variant="button"
@@ -112,7 +112,7 @@ function QRecordSidebar({tableSections, widgetMetaDataList, light, stickyTop}: P
 
                         </MDTypography>
                      </Box>
-                  </HashLink>
+                  </Box>
                )) : null
             }
          </Box>

src/qqq/components/misc/SavedBulkLoadProfiles.tsx

@@ -0,0 +1,794 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2022.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+import {QController} from "@kingsrook/qqq-frontend-core/lib/controllers/QController";
+import {QInstance} from "@kingsrook/qqq-frontend-core/lib/model/metaData/QInstance";
+import {QTableMetaData} from "@kingsrook/qqq-frontend-core/lib/model/metaData/QTableMetaData";
+import {QJobComplete} from "@kingsrook/qqq-frontend-core/lib/model/processes/QJobComplete";
+import {QJobError} from "@kingsrook/qqq-frontend-core/lib/model/processes/QJobError";
+import {QRecord} from "@kingsrook/qqq-frontend-core/lib/model/QRecord";
+import {Alert, Button} from "@mui/material";
+import Box from "@mui/material/Box";
+import Dialog from "@mui/material/Dialog";
+import DialogActions from "@mui/material/DialogActions";
+import DialogContent from "@mui/material/DialogContent";
+import DialogTitle from "@mui/material/DialogTitle";
+import Divider from "@mui/material/Divider";
+import Icon from "@mui/material/Icon";
+import ListItemIcon from "@mui/material/ListItemIcon";
+import Menu from "@mui/material/Menu";
+import MenuItem from "@mui/material/MenuItem";
+import TextField from "@mui/material/TextField";
+import Tooltip from "@mui/material/Tooltip";
+import {TooltipProps} from "@mui/material/Tooltip/Tooltip";
+import FormData from "form-data";
+import QContext from "QContext";
+import colors from "qqq/assets/theme/base/colors";
+import {QCancelButton, QDeleteButton, QSaveButton} from "qqq/components/buttons/DefaultButtons";
+import {BulkLoadMapping, BulkLoadTableStructure, FileDescription} from "qqq/models/processes/BulkLoadModels";
+import Client from "qqq/utils/qqq/Client";
+import {SavedBulkLoadProfileUtils} from "qqq/utils/qqq/SavedBulkLoadProfileUtils";
+import React, {useContext, useEffect, useRef, useState} from "react";
+import {useLocation} from "react-router-dom";
+
+interface Props
+{
+   metaData: QInstance,
+   tableMetaData: QTableMetaData,
+   tableStructure: BulkLoadTableStructure,
+   currentSavedBulkLoadProfileRecord: QRecord,
+   currentMapping: BulkLoadMapping,
+   bulkLoadProfileOnChangeCallback?: (record: QRecord | null) => void,
+   allowSelectingProfile?: boolean,
+   fileDescription?: FileDescription,
+   bulkLoadProfileResetToSuggestedMappingCallback?: () => void,
+   isBulkEdit?: boolean;
+}
+
+SavedBulkLoadProfiles.defaultProps = {
+   allowSelectingProfile: true
+};
+
+const qController = Client.getInstance();
+
+/***************************************************************************
+ ** menu-button, text elements, and modal(s) that let you work with saved
+ ** bulk-load profiles.
+ ***************************************************************************/
+function SavedBulkLoadProfiles({metaData, tableMetaData, tableStructure, currentSavedBulkLoadProfileRecord, bulkLoadProfileOnChangeCallback, currentMapping, allowSelectingProfile, fileDescription, bulkLoadProfileResetToSuggestedMappingCallback, isBulkEdit}: Props): JSX.Element
+{
+   const [yourSavedBulkLoadProfiles, setYourSavedBulkLoadProfiles] = useState([] as QRecord[]);
+   const [bulkLoadProfilesSharedWithYou, setBulkLoadProfilesSharedWithYou] = useState([] as QRecord[]);
+   const [savedBulkLoadProfilesMenu, setSavedBulkLoadProfilesMenu] = useState(null);
+   const [savedBulkLoadProfilesHaveLoaded, setSavedBulkLoadProfilesHaveLoaded] = useState(false);
+   const [isSubmitting, setIsSubmitting] = useState(false);
+
+   const [savePopupOpen, setSavePopupOpen] = useState(false);
+   const [isSaveAsAction, setIsSaveAsAction] = useState(false);
+   const [isRenameAction, setIsRenameAction] = useState(false);
+   const [isDeleteAction, setIsDeleteAction] = useState(false);
+   const [savedBulkLoadProfileNameInputValue, setSavedBulkLoadProfileNameInputValue] = useState(null as string);
+   const [popupAlertContent, setPopupAlertContent] = useState("");
+
+   const [savedSuccessMessage, setSavedSuccessMessage] = useState(null as string);
+   const [savedFailedMessage, setSavedFailedMessage] = useState(null as string);
+
+   const anchorRef = useRef<HTMLDivElement>(null);
+   const location = useLocation();
+   const [saveOptionsOpen, setSaveOptionsOpen] = useState(false);
+
+   const SAVE_OPTION = "Save...";
+   const DUPLICATE_OPTION = "Duplicate...";
+   const RENAME_OPTION = "Rename...";
+   const DELETE_OPTION = "Delete...";
+   const CLEAR_OPTION = "New Profile";
+   const RESET_TO_SUGGESTION = "Reset to Suggested Mapping";
+
+   const {accentColor, accentColorLight, userId: currentUserId} = useContext(QContext);
+
+   const openSavedBulkLoadProfilesMenu = (event: any) => setSavedBulkLoadProfilesMenu(event.currentTarget);
+   const closeSavedBulkLoadProfilesMenu = () => setSavedBulkLoadProfilesMenu(null);
+
+   ////////////////////////////////////////////////////////////////////////
+   // load records on first run (if user is allowed to select a profile) //
+   ////////////////////////////////////////////////////////////////////////
+   useEffect(() =>
+   {
+      if (allowSelectingProfile)
+      {
+         loadSavedBulkLoadProfiles()
+            .then(() =>
+            {
+               setSavedBulkLoadProfilesHaveLoaded(true);
+            });
+      }
+   }, []);
+
+
+   const baseBulkLoadMapping: BulkLoadMapping = currentSavedBulkLoadProfileRecord ? BulkLoadMapping.fromSavedProfileRecord(tableStructure, currentSavedBulkLoadProfileRecord) : new BulkLoadMapping(tableStructure);
+   const bulkLoadProfileDiffs: any[] = SavedBulkLoadProfileUtils.diffBulkLoadMappings(tableStructure, fileDescription, baseBulkLoadMapping, currentMapping);
+   let bulkLoadProfileIsModified = false;
+   if (bulkLoadProfileDiffs.length > 0)
+   {
+      bulkLoadProfileIsModified = true;
+   }
+
+   /*******************************************************************************
+    ** make request to load all saved profiles from backend
+    *******************************************************************************/
+   async function loadSavedBulkLoadProfiles()
+   {
+      if (!tableMetaData)
+      {
+         return;
+      }
+
+      const formData = new FormData();
+      formData.append("tableName", tableMetaData.name);
+      formData.append("isBulkEdit", isBulkEdit.toString());
+
+      const savedBulkLoadProfiles = await makeSavedBulkLoadProfileRequest("querySavedBulkLoadProfile", formData);
+      const yourSavedBulkLoadProfiles: QRecord[] = [];
+      const bulkLoadProfilesSharedWithYou: QRecord[] = [];
+      for (let i = 0; i < savedBulkLoadProfiles.length; i++)
+      {
+         const record = savedBulkLoadProfiles[i];
+         if (record.values.get("userId") == currentUserId)
+         {
+            yourSavedBulkLoadProfiles.push(record);
+         }
+         else
+         {
+            bulkLoadProfilesSharedWithYou.push(record);
+         }
+      }
+      setYourSavedBulkLoadProfiles(yourSavedBulkLoadProfiles);
+      setBulkLoadProfilesSharedWithYou(bulkLoadProfilesSharedWithYou);
+   }
+
+
+   /*******************************************************************************
+    ** fired when a saved record is clicked from the dropdown
+    *******************************************************************************/
+   const handleSavedBulkLoadProfileRecordOnClick = async (record: QRecord) =>
+   {
+      setSavePopupOpen(false);
+      closeSavedBulkLoadProfilesMenu();
+
+      if (bulkLoadProfileOnChangeCallback)
+      {
+         bulkLoadProfileOnChangeCallback(record);
+      }
+   };
+
+
+   /*******************************************************************************
+    ** fired when a save option is selected from the save... button/dropdown combo
+    *******************************************************************************/
+   const handleDropdownOptionClick = (optionName: string) =>
+   {
+      setSaveOptionsOpen(false);
+      setPopupAlertContent("");
+      closeSavedBulkLoadProfilesMenu();
+      setSavePopupOpen(true);
+      setIsSaveAsAction(false);
+      setIsRenameAction(false);
+      setIsDeleteAction(false);
+
+      switch (optionName)
+      {
+         case SAVE_OPTION:
+            if (currentSavedBulkLoadProfileRecord == null)
+            {
+               setSavedBulkLoadProfileNameInputValue("");
+            }
+            break;
+         case DUPLICATE_OPTION:
+            setSavedBulkLoadProfileNameInputValue("");
+            setIsSaveAsAction(true);
+            break;
+         case CLEAR_OPTION:
+            setSavePopupOpen(false);
+            if (bulkLoadProfileOnChangeCallback)
+            {
+               bulkLoadProfileOnChangeCallback(null);
+            }
+            break;
+         case RESET_TO_SUGGESTION:
+            setSavePopupOpen(false);
+            if (bulkLoadProfileResetToSuggestedMappingCallback)
+            {
+               bulkLoadProfileResetToSuggestedMappingCallback();
+            }
+            break;
+         case RENAME_OPTION:
+            if (currentSavedBulkLoadProfileRecord != null)
+            {
+               setSavedBulkLoadProfileNameInputValue(currentSavedBulkLoadProfileRecord.values.get("label"));
+            }
+            setIsRenameAction(true);
+            break;
+         case DELETE_OPTION:
+            setIsDeleteAction(true);
+            break;
+      }
+   };
+
+
+   /*******************************************************************************
+    ** fired when save or delete button saved on confirmation dialogs
+    *******************************************************************************/
+   async function handleDialogButtonOnClick()
+   {
+      try
+      {
+         setPopupAlertContent("");
+         setIsSubmitting(true);
+
+         const formData = new FormData();
+         if (isDeleteAction)
+         {
+            formData.append("id", currentSavedBulkLoadProfileRecord.values.get("id"));
+            await makeSavedBulkLoadProfileRequest("deleteSavedBulkLoadProfile", formData);
+
+            setSavePopupOpen(false);
+            setSaveOptionsOpen(false);
+
+            await (async () =>
+            {
+               handleDropdownOptionClick(CLEAR_OPTION);
+            })();
+         }
+         else
+         {
+            formData.append("tableName", tableMetaData.name);
+
+            /////////////////////////////////////////////////////////////////////////////////////////
+            // convert the BulkLoadMapping object to a BulkLoadProfile - the thing that gets saved //
+            /////////////////////////////////////////////////////////////////////////////////////////
+            const bulkLoadProfile = currentMapping.toProfile();
+            const mappingJson = JSON.stringify(bulkLoadProfile.profile);
+            formData.append("mappingJson", mappingJson);
+            formData.append("isBulkEdit", isBulkEdit.toString());
+
+            if (isSaveAsAction || isRenameAction || currentSavedBulkLoadProfileRecord == null)
+            {
+               formData.append("label", savedBulkLoadProfileNameInputValue);
+               if (currentSavedBulkLoadProfileRecord != null && isRenameAction)
+               {
+                  formData.append("id", currentSavedBulkLoadProfileRecord.values.get("id"));
+               }
+            }
+            else
+            {
+               formData.append("id", currentSavedBulkLoadProfileRecord.values.get("id"));
+               formData.append("label", currentSavedBulkLoadProfileRecord?.values.get("label"));
+            }
+            const recordList = await makeSavedBulkLoadProfileRequest("storeSavedBulkLoadProfile", formData);
+            await (async () =>
+            {
+               if (recordList && recordList.length > 0)
+               {
+                  setSavedBulkLoadProfilesHaveLoaded(false);
+                  setSavedSuccessMessage("Profile Saved.");
+                  setTimeout(() => setSavedSuccessMessage(null), 2500);
+
+                  if (allowSelectingProfile)
+                  {
+                     loadSavedBulkLoadProfiles();
+                     handleSavedBulkLoadProfileRecordOnClick(recordList[0]);
+                  }
+                  else
+                  {
+                     if (bulkLoadProfileOnChangeCallback)
+                     {
+                        bulkLoadProfileOnChangeCallback(recordList[0]);
+                     }
+                  }
+               }
+            })();
+         }
+
+         setSavePopupOpen(false);
+         setSaveOptionsOpen(false);
+      }
+      catch (e: any)
+      {
+         let message = JSON.stringify(e);
+         if (typeof e == "string")
+         {
+            message = e;
+         }
+         else if (typeof e == "object" && e.message)
+         {
+            message = e.message;
+         }
+
+         setPopupAlertContent(message);
+         console.log(`Setting error: ${message}`);
+      }
+      finally
+      {
+         setIsSubmitting(false);
+      }
+   }
+
+
+   /*******************************************************************************
+    ** stores the current dialog input text to state
+    *******************************************************************************/
+   const handleSaveDialogInputChange = (event: React.ChangeEvent<HTMLTextAreaElement | HTMLInputElement>) =>
+   {
+      setSavedBulkLoadProfileNameInputValue(event.target.value);
+   };
+
+
+   /*******************************************************************************
+    ** closes current dialog
+    *******************************************************************************/
+   const handleSavePopupClose = () =>
+   {
+      setSavePopupOpen(false);
+   };
+
+
+   /*******************************************************************************
+    ** make a request to the backend for various savedBulkLoadProfile processes
+    *******************************************************************************/
+   async function makeSavedBulkLoadProfileRequest(processName: string, formData: FormData): Promise<QRecord[]>
+   {
+      /////////////////////////
+      // fetch saved records //
+      /////////////////////////
+      let savedBulkLoadProfiles = [] as QRecord[];
+      try
+      {
+         //////////////////////////////////////////////////////////////////
+         // we don't want this job to go async, so, pass a large timeout //
+         //////////////////////////////////////////////////////////////////
+         formData.append(QController.STEP_TIMEOUT_MILLIS_PARAM_NAME, 60 * 1000);
+         const processResult = await qController.processInit(processName, formData, qController.defaultMultipartFormDataHeaders());
+         if (processResult instanceof QJobError)
+         {
+            const jobError = processResult as QJobError;
+            throw (jobError.error);
+         }
+         else
+         {
+            const result = processResult as QJobComplete;
+            if (result.values.savedBulkLoadProfileList)
+            {
+               for (let i = 0; i < result.values.savedBulkLoadProfileList.length; i++)
+               {
+                  const qRecord = new QRecord(result.values.savedBulkLoadProfileList[i]);
+                  savedBulkLoadProfiles.push(qRecord);
+               }
+            }
+         }
+      }
+      catch (e)
+      {
+         throw (e);
+      }
+
+      return (savedBulkLoadProfiles);
+   }
+
+   const bulkAction = isBulkEdit ? "Edit" : "Load";
+   const hasStorePermission = metaData?.processes.has("storeSavedBulkLoadProfile");
+   const hasDeletePermission = metaData?.processes.has("deleteSavedBulkLoadProfile");
+   const hasQueryPermission = metaData?.processes.has("querySavedBulkLoadProfile");
+
+   const tooltipMaxWidth = (maxWidth: string) =>
+   {
+      return ({
+         slotProps: {
+            tooltip: {
+               sx: {
+                  maxWidth: maxWidth
+               }
+            }
+         }
+      });
+   };
+
+   const menuTooltipAttribs = {...tooltipMaxWidth("250px"), placement: "left", enterDelay: 1000} as TooltipProps;
+
+   let disabledBecauseNotOwner = false;
+   let notOwnerTooltipText = null;
+   if (currentSavedBulkLoadProfileRecord && currentSavedBulkLoadProfileRecord.values.get("userId") != currentUserId)
+   {
+      disabledBecauseNotOwner = true;
+      notOwnerTooltipText = "You may not save changes to this bulk load profile, because you are not its owner.";
+   }
+
+   const menuWidth = "300px";
+   const renderSavedBulkLoadProfilesMenu = tableMetaData && (
+      <Menu
+         anchorEl={savedBulkLoadProfilesMenu}
+         anchorOrigin={{vertical: "bottom", horizontal: "left",}}
+         transformOrigin={{vertical: "top", horizontal: "left",}}
+         open={Boolean(savedBulkLoadProfilesMenu)}
+         onClose={closeSavedBulkLoadProfilesMenu}
+         keepMounted
+         PaperProps={{style: {maxHeight: "calc(100vh - 200px)", minWidth: menuWidth}}}
+      >
+         {
+            <MenuItem sx={{width: menuWidth}} disabled style={{opacity: "initial"}}><b>Bulk {bulkAction} Profile Actions</b></MenuItem>
+         }
+         {
+            !allowSelectingProfile &&
+            <MenuItem sx={{width: menuWidth}} disabled style={{opacity: "initial", whiteSpace: "wrap", display: "block"}}>
+               {
+                  currentSavedBulkLoadProfileRecord ?
+                     <span>You are using the bulk {bulkAction.toLowerCase()} profile:<br /><b style={{paddingLeft: "1rem"}}>{currentSavedBulkLoadProfileRecord.values.get("label")}</b><br /><br />You can manage this profile on this screen.</span>
+                     : <span>You are not using a saved bulk {bulkAction.toLowerCase()} profile.<br /><br />You can save your profile on this screen.</span>
+               }
+            </MenuItem>
+         }
+         {
+            !allowSelectingProfile && <Divider />
+         }
+         {
+            hasStorePermission &&
+            <Tooltip {...menuTooltipAttribs} title={notOwnerTooltipText ?? <>Save your current mapping, for quick re-use at a later time.<br /><br />You will be prompted to enter a name if you choose this option.</>}>
+               <span>
+                  <MenuItem disabled={disabledBecauseNotOwner} onClick={() => handleDropdownOptionClick(SAVE_OPTION)}>
+                     <ListItemIcon><Icon>save</Icon></ListItemIcon>
+                     {currentSavedBulkLoadProfileRecord ? "Save..." : "Save As..."}
+                  </MenuItem>
+               </span>
+            </Tooltip>
+         }
+         {
+            hasStorePermission && currentSavedBulkLoadProfileRecord != null &&
+            <Tooltip {...menuTooltipAttribs} title={notOwnerTooltipText ?? "Change the name for this saved bulk {bulkAction.toLowerCase()} profile."}>
+               <span>
+                  <MenuItem disabled={currentSavedBulkLoadProfileRecord === null || disabledBecauseNotOwner} onClick={() => handleDropdownOptionClick(RENAME_OPTION)}>
+                     <ListItemIcon><Icon>edit</Icon></ListItemIcon>
+                     Rename...
+                  </MenuItem>
+               </span>
+            </Tooltip>
+         }
+         {
+            hasStorePermission && currentSavedBulkLoadProfileRecord != null &&
+            <Tooltip {...menuTooltipAttribs} title="Save a new copy this bulk {bulkAction.toLowerCase()} profile, with a different name, separate from the original.">
+               <span>
+                  <MenuItem disabled={currentSavedBulkLoadProfileRecord === null} onClick={() => handleDropdownOptionClick(DUPLICATE_OPTION)}>
+                     <ListItemIcon><Icon>content_copy</Icon></ListItemIcon>
+                     Save As...
+                  </MenuItem>
+               </span>
+            </Tooltip>
+         }
+         {
+            hasDeletePermission && currentSavedBulkLoadProfileRecord != null &&
+            <Tooltip {...menuTooltipAttribs} title={notOwnerTooltipText ?? "Delete this saved bulk {bulkAction.toLowerCase()} profile."}>
+               <span>
+                  <MenuItem disabled={currentSavedBulkLoadProfileRecord === null || disabledBecauseNotOwner} onClick={() => handleDropdownOptionClick(DELETE_OPTION)}>
+                     <ListItemIcon><Icon>delete</Icon></ListItemIcon>
+                     Delete...
+                  </MenuItem>
+               </span>
+            </Tooltip>
+         }
+         {
+            allowSelectingProfile &&
+            <Tooltip {...menuTooltipAttribs} title="Create a new blank bulk {bulkAction.toLowerCase()} profile for this table, removing all mappings.">
+               <span>
+                  <MenuItem onClick={() => handleDropdownOptionClick(CLEAR_OPTION)}>
+                     <ListItemIcon><Icon>monitor</Icon></ListItemIcon>
+                     New Bulk {bulkAction} Profile
+                  </MenuItem>
+               </span>
+            </Tooltip>
+         }
+         {
+            allowSelectingProfile &&
+            <Box>
+               {
+                  <Divider />
+               }
+               <MenuItem disabled style={{"opacity": "initial"}}><b>Your Saved Bulk {bulkAction} Profiles</b></MenuItem>
+               {
+                  yourSavedBulkLoadProfiles && yourSavedBulkLoadProfiles.length > 0 ? (
+                     yourSavedBulkLoadProfiles.map((record: QRecord, index: number) =>
+                        <MenuItem sx={{paddingLeft: "50px"}} key={`savedFiler-${index}`} onClick={() => handleSavedBulkLoadProfileRecordOnClick(record)}>
+                           {record.values.get("label")}
+                        </MenuItem>
+                     )
+                  ) : (
+                     <MenuItem disabled sx={{opacity: "1 !important"}}>
+                        <i>You do not have any saved bulk {bulkAction.toLowerCase()} profiles for this table.</i>
+                     </MenuItem>
+                  )
+               }
+               <MenuItem disabled style={{"opacity": "initial"}}><b>Bulk {bulkAction} Profiles Shared with you</b></MenuItem>
+               {
+                  bulkLoadProfilesSharedWithYou && bulkLoadProfilesSharedWithYou.length > 0 ? (
+                     bulkLoadProfilesSharedWithYou.map((record: QRecord, index: number) =>
+                        <MenuItem sx={{paddingLeft: "50px"}} key={`savedFiler-${index}`} onClick={() => handleSavedBulkLoadProfileRecordOnClick(record)}>
+                           {record.values.get("label")}
+                        </MenuItem>
+                     )
+                  ) : (
+                     <MenuItem disabled sx={{opacity: "1 !important"}}>
+                        <i>You do not have any bulk {bulkAction.toLowerCase()} profiles shared with you for this table.</i>
+                     </MenuItem>
+                  )
+               }
+            </Box>
+         }
+      </Menu>
+   );
+
+   let buttonText = `Saved Bulk ${bulkAction} Profiles`;
+   let buttonBackground = "none";
+   let buttonBorder = colors.grayLines.main;
+   let buttonColor = colors.gray.main;
+
+   if (currentSavedBulkLoadProfileRecord)
+   {
+      if (bulkLoadProfileIsModified)
+      {
+         buttonBackground = accentColorLight;
+         buttonBorder = buttonBackground;
+         buttonColor = accentColor;
+      }
+      else
+      {
+         buttonBackground = accentColor;
+         buttonBorder = buttonBackground;
+         buttonColor = "#FFFFFF";
+      }
+   }
+
+   const buttonStyles = {
+      border: `1px solid ${buttonBorder}`,
+      backgroundColor: buttonBackground,
+      color: buttonColor,
+      "&:focus:not(:hover)": {
+         color: buttonColor,
+         backgroundColor: buttonBackground,
+      },
+      "&:hover": {
+         color: buttonColor,
+         backgroundColor: buttonBackground,
+      }
+   };
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   function isSaveButtonDisabled(): boolean
+   {
+      if (isSubmitting)
+      {
+         return (true);
+      }
+
+      const haveInputText = (savedBulkLoadProfileNameInputValue != null && savedBulkLoadProfileNameInputValue.trim() != "");
+
+      if (isSaveAsAction || isRenameAction || currentSavedBulkLoadProfileRecord == null)
+      {
+         if (!haveInputText)
+         {
+            return (true);
+         }
+      }
+
+      return (false);
+   }
+
+   const linkButtonStyle = {
+      minWidth: "unset",
+      textTransform: "none",
+      fontSize: "0.875rem",
+      fontWeight: "500",
+      padding: "0.5rem"
+   };
+
+   return (
+      hasQueryPermission && tableMetaData ? (
+         <>
+            <Box order="1" mr={"0.5rem"}>
+               <Button
+                  onClick={openSavedBulkLoadProfilesMenu}
+                  sx={{
+                     borderRadius: "0.75rem",
+                     textTransform: "none",
+                     fontWeight: 500,
+                     fontSize: "0.875rem",
+                     p: "0.5rem",
+                     ...buttonStyles
+                  }}
+               >
+                  <Icon sx={{mr: "0.5rem"}}>save</Icon>
+                  {buttonText}
+                  <Icon sx={{ml: "0.5rem"}}>keyboard_arrow_down</Icon>
+               </Button>
+               {renderSavedBulkLoadProfilesMenu}
+            </Box>
+            <Box order="3" display="flex" justifyContent="center" flexDirection="column">
+               <Box pl={2} pr={2} fontSize="0.875rem" sx={{display: "flex", alignItems: "center"}}>
+                  {
+                     savedSuccessMessage && <Box color={colors.success.main}>{savedSuccessMessage}</Box>
+                  }
+                  {
+                     savedFailedMessage && <Box color={colors.error.main}>{savedFailedMessage}</Box>
+                  }
+                  {
+                     !currentSavedBulkLoadProfileRecord /*&& bulkLoadProfileIsModified*/ && <>
+                        {
+                           <>
+                              <Tooltip {...tooltipMaxWidth("24rem")} sx={{cursor: "pointer"}} title={<>
+                                 <b>Unsaved Mapping</b>
+                                 <ul style={{padding: "0.5rem 1rem"}}>
+                                    <li>You are not using a saved bulk {bulkAction.toLowerCase()} profile.</li>
+                                    {
+                                       /*bulkLoadProfileDiffs.map((s: string, i: number) => <li key={i}>{s}</li>)*/
+                                    }
+                                 </ul>
+                              </>}>
+                                 <Button disableRipple={true} sx={linkButtonStyle} onClick={() => handleDropdownOptionClick(SAVE_OPTION)}>Save Bulk {bulkAction} Profile As&hellip;</Button>
+                              </Tooltip>
+
+                              {/* vertical rule */}
+                              {allowSelectingProfile && <Box display="inline-block" borderLeft={`1px solid ${colors.grayLines.main}`} height="1rem" width="1px" position="relative" />}
+                           </>
+                        }
+
+                        {/* for the no-profile use-case, don't give a reset-link on screens other than the first (file mapping) one - which is tied to the allowSelectingProfile attribute */}
+                        {allowSelectingProfile && <>
+                           <Box pl="0.5rem">Reset to:</Box>
+                           <Button disableRipple={true} sx={{color: colors.gray.main, ...linkButtonStyle}} onClick={() => handleDropdownOptionClick(CLEAR_OPTION)}>Empty Mapping</Button>
+                           <Box display="inline-block" borderLeft={`1px solid ${colors.grayLines.main}`} height="1rem" width="1px" position="relative" />
+                           <Button disableRipple={true} sx={{color: colors.gray.main, ...linkButtonStyle}} onClick={() => handleDropdownOptionClick(RESET_TO_SUGGESTION)}>Suggested Mapping</Button>
+                        </>}
+
+
+                     </>
+                  }
+                  {
+                     currentSavedBulkLoadProfileRecord && bulkLoadProfileIsModified && <>
+                        <Tooltip {...tooltipMaxWidth("24rem")} sx={{cursor: "pointer"}} title={<>
+                           <b>Unsaved Changes</b>
+                           <ul style={{padding: "0.5rem 1rem"}}>
+                              {
+                                 bulkLoadProfileDiffs.map((s: string, i: number) => <li key={i}>{s}</li>)
+                              }
+                           </ul>
+                           {
+                              notOwnerTooltipText && <i>{notOwnerTooltipText}</i>
+                           }
+                        </>}>
+                           <Box display="inline" sx={{...linkButtonStyle, p: 0, cursor: "default", position: "relative", top: "-1px"}}>{bulkLoadProfileDiffs.length} Unsaved Change{bulkLoadProfileDiffs.length == 1 ? "" : "s"}</Box>
+                        </Tooltip>
+
+                        {disabledBecauseNotOwner ? <>&nbsp;&nbsp;</> : <Button disableRipple={true} sx={linkButtonStyle} onClick={() => handleDropdownOptionClick(SAVE_OPTION)}>Save&hellip;</Button>}
+
+                        {/* vertical rule */}
+                        {/* also, don't give a reset-link on screens other than the first (file mapping) one - which is tied to the allowSelectingProfile attribute */}
+                        {/* partly because it isn't correctly resetting the values, but also because, it's a litle unclear that what, it would reset changes from other screens too?? */}
+                        {
+                           allowSelectingProfile && <>
+                              <Box display="inline-block" borderLeft={`1px solid ${colors.grayLines.main}`} height="1rem" width="1px" position="relative" />
+                              <Button disableRipple={true} sx={{color: colors.gray.main, ...linkButtonStyle}} onClick={() => handleSavedBulkLoadProfileRecordOnClick(currentSavedBulkLoadProfileRecord)}>Reset All Changes</Button>
+                           </>
+                        }
+                     </>
+                  }
+               </Box>
+            </Box>
+            {
+               <Dialog
+                  open={savePopupOpen}
+                  onClose={handleSavePopupClose}
+                  aria-labelledby="alert-dialog-title"
+                  aria-describedby="alert-dialog-description"
+                  onKeyPress={(e) =>
+                  {
+                     ////////////////////////////////////////////////////
+                     // make user actually hit delete button           //
+                     // but for other modes, let Enter submit the form //
+                     ////////////////////////////////////////////////////
+                     if (e.key == "Enter" && !isDeleteAction)
+                     {
+                        handleDialogButtonOnClick();
+                     }
+                  }}
+               >
+                  {
+                     currentSavedBulkLoadProfileRecord ? (
+                        isDeleteAction ? (
+                           <DialogTitle id="alert-dialog-title">Delete Bulk {bulkAction} Profile</DialogTitle>
+                        ) : (
+                           isSaveAsAction ? (
+                              <DialogTitle id="alert-dialog-title">Save Bulk {bulkAction} Profile As</DialogTitle>
+                           ) : (
+                              isRenameAction ? (
+                                 <DialogTitle id="alert-dialog-title">Rename Bulk {bulkAction} Profile</DialogTitle>
+                              ) : (
+                                 <DialogTitle id="alert-dialog-title">Update Existing Bulk {bulkAction} Profile</DialogTitle>
+                              )
+                           )
+                        )
+                     ) : (
+                        <DialogTitle id="alert-dialog-title">Save New Bulk {bulkAction} Profile</DialogTitle>
+                     )
+                  }
+                  <DialogContent sx={{width: "500px"}}>
+                     {popupAlertContent ? (
+                        <Box mb={1}>
+                           <Alert severity="error" onClose={() => setPopupAlertContent("")}>{popupAlertContent}</Alert>
+                        </Box>
+                     ) : ("")}
+                     {
+                        (!currentSavedBulkLoadProfileRecord || isSaveAsAction || isRenameAction) && !isDeleteAction ? (
+                           <Box>
+                              {
+                                 isSaveAsAction ? (
+                                    <Box mb={3}>Enter a name for this new saved bulk {bulkAction.toLowerCase()} profile.</Box>
+                                 ) : (
+                                    <Box mb={3}>Enter a new name for this saved bulk {bulkAction.toLowerCase()} profile.</Box>
+                                 )
+                              }
+                              <TextField
+                                 autoFocus
+                                 name="custom-delimiter-value"
+                                 placeholder={`Bulk ${bulkAction} Profile Name`}
+                                 inputProps={{width: "100%", maxLength: 100}}
+                                 value={savedBulkLoadProfileNameInputValue}
+                                 sx={{width: "100%"}}
+                                 onChange={handleSaveDialogInputChange}
+                                 onFocus={event =>
+                                 {
+                                    event.target.select();
+                                 }}
+                              />
+                           </Box>
+                        ) : (
+                           isDeleteAction ? (
+                              <Box>Are you sure you want to delete the bulk {bulkAction.toLowerCase()} profile {`'${currentSavedBulkLoadProfileRecord?.values.get("label")}'`}?</Box>
+                           ) : (
+                              <Box>Are you sure you want to update the bulk {bulkAction.toLowerCase()} profile {`'${currentSavedBulkLoadProfileRecord?.values.get("label")}'`}?</Box>
+                           )
+                        )
+                     }
+                  </DialogContent>
+                  <DialogActions>
+                     <QCancelButton onClickHandler={handleSavePopupClose} disabled={false} />
+                     {
+                        isDeleteAction ?
+                           <QDeleteButton onClickHandler={handleDialogButtonOnClick} disabled={isSubmitting} />
+                           :
+                           <QSaveButton label="Save" onClickHandler={handleDialogButtonOnClick} disabled={isSaveButtonDisabled()} />
+                     }
+                  </DialogActions>
+               </Dialog>
+            }
+         </>
+      ) : null
+   );
+}
+
+export default SavedBulkLoadProfiles;

src/qqq/components/misc/SavedViews.tsx

@@ -25,7 +25,8 @@ import {QTableMetaData} from "@kingsrook/qqq-frontend-core/lib/model/metaData/QT
 import {QJobComplete} from "@kingsrook/qqq-frontend-core/lib/model/processes/QJobComplete";
 import {QJobError} from "@kingsrook/qqq-frontend-core/lib/model/processes/QJobError";
 import {QRecord} from "@kingsrook/qqq-frontend-core/lib/model/QRecord";
-import {Alert, Box, Button} from "@mui/material";
+import {Alert, Button} from "@mui/material";
+import Box from "@mui/material/Box";
 import Dialog from "@mui/material/Dialog";
 import DialogActions from "@mui/material/DialogActions";
 import DialogContent from "@mui/material/DialogContent";
@@ -94,12 +95,12 @@ function SavedViews({qController, metaData, tableMetaData, currentSavedView, tab
 
    const {accentColor, accentColorLight, userId: currentUserId} = useContext(QContext);
 
-   /////////////////////////////////////////////////////////////////////////////////////////
-   // this component is used by <RecordQuery> - but that component has different usages - //
-   // e.g., the full-fledged query screen, but also, within other screens (e.g., a modal  //
-   // under the ReportSetupWidget).  So, there are some behaviors we only want when we're //
-   // on the full-fledged query screen, such as changing the URL with saved view ids.     //
-   /////////////////////////////////////////////////////////////////////////////////////////
+   /////////////////////////////////////////////////////////////////////////////////////////////
+   // this component is used by <RecordQuery> - but that component has different usages -     //
+   // e.g., the full-fledged query screen, but also, within other screens (e.g., a modal      //
+   // under the FilterAndColumnsSetupWidget).  So, there are some behaviors we only want when //
+   // we're on the full-fledged query screen, such as changing the URL with saved view ids.   //
+   /////////////////////////////////////////////////////////////////////////////////////////////
    const isQueryScreen = queryScreenUsage == "queryScreen";
 
    const openSavedViewsMenu = (event: any) => setSavedViewsMenu(event.currentTarget);

src/qqq/components/processes/BulkLoadFileMappingField.tsx

@@ -0,0 +1,343 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2024.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+
+import {QFieldMetaData} from "@kingsrook/qqq-frontend-core/lib/model/metaData/QFieldMetaData";
+import {Checkbox, FormControlLabel, Radio, Tooltip} from "@mui/material";
+import Autocomplete from "@mui/material/Autocomplete";
+import Box from "@mui/material/Box";
+import Button from "@mui/material/Button";
+import Icon from "@mui/material/Icon";
+import RadioGroup from "@mui/material/RadioGroup";
+import TextField from "@mui/material/TextField";
+import {useFormikContext} from "formik";
+import colors from "qqq/assets/theme/base/colors";
+import QDynamicFormField from "qqq/components/forms/DynamicFormField";
+import DynamicFormUtils from "qqq/components/forms/DynamicFormUtils";
+import {BulkLoadField, FileDescription} from "qqq/models/processes/BulkLoadModels";
+import Client from "qqq/utils/qqq/Client";
+import React, {useEffect, useState} from "react";
+
+interface BulkLoadMappingFieldProps
+{
+   bulkLoadField: BulkLoadField,
+   isRequired: boolean,
+   removeFieldCallback?: () => void,
+   fileDescription: FileDescription,
+   forceParentUpdate?: () => void,
+   isBulkEdit?: boolean
+}
+
+const xIconButtonSX =
+   {
+      border: `1px solid ${colors.grayLines.main} !important`,
+      borderRadius: "0.5rem",
+      textTransform: "none",
+      fontSize: "1rem",
+      fontWeight: "400",
+      width: "30px",
+      minWidth: "30px",
+      height: "2rem",
+      minHeight: "2rem",
+      paddingLeft: 0,
+      paddingRight: 0,
+      marginRight: "0.5rem",
+      marginTop: "0.5rem",
+      color: colors.error.main,
+      "&:hover": {color: colors.error.main},
+      "&:focus": {color: colors.error.main},
+      "&:focus:not(:hover)": {color: colors.error.main},
+   };
+
+const qController = Client.getInstance();
+
+/***************************************************************************
+ ** row for a single field on the bulk load mapping screen.
+ ***************************************************************************/
+export default function BulkLoadFileMappingField({bulkLoadField, isRequired, removeFieldCallback, fileDescription, forceParentUpdate, isBulkEdit}: BulkLoadMappingFieldProps): JSX.Element
+{
+   const columnNames = fileDescription.getColumnNames();
+
+   const [valueType, setValueType] = useState(bulkLoadField.valueType);
+   const [selectedColumn, setSelectedColumn] = useState({label: columnNames[bulkLoadField.columnIndex], value: bulkLoadField.columnIndex});
+   const [selectedColumnInputValue, setSelectedColumnInputValue] = useState(columnNames[bulkLoadField.columnIndex]);
+
+   const [doingInitialLoadOfPossibleValue, setDoingInitialLoadOfPossibleValue] = useState(false);
+   const [everDidInitialLoadOfPossibleValue, setEverDidInitialLoadOfPossibleValue] = useState(false);
+   const [possibleValueInitialDisplayValue, setPossibleValueInitialDisplayValue] = useState(null as string);
+
+   const fieldMetaData = new QFieldMetaData(bulkLoadField.field);
+   const dynamicField = DynamicFormUtils.getDynamicField(fieldMetaData);
+   const dynamicFieldInObject: any = {};
+   dynamicFieldInObject[fieldMetaData["name"]] = dynamicField;
+   DynamicFormUtils.addPossibleValueProps(dynamicFieldInObject, [fieldMetaData], bulkLoadField.tableStructure.tableName, null, null);
+
+   /////////////////////////////////////////////////////////////////////////////////////
+   // deal with dynamically loading the initial default value for a possible value... //
+   /////////////////////////////////////////////////////////////////////////////////////
+   let actuallyDoingInitialLoadOfPossibleValue = doingInitialLoadOfPossibleValue;
+   if (dynamicField.possibleValueProps && bulkLoadField.defaultValue && !doingInitialLoadOfPossibleValue && !everDidInitialLoadOfPossibleValue)
+   {
+      actuallyDoingInitialLoadOfPossibleValue = true;
+      setDoingInitialLoadOfPossibleValue(true);
+      setEverDidInitialLoadOfPossibleValue(true);
+
+      (async () =>
+      {
+         try
+         {
+            const possibleValues = await qController.possibleValues(bulkLoadField.tableStructure.tableName, null, fieldMetaData.name, null, [bulkLoadField.defaultValue], undefined, null, "filter");
+            if (possibleValues && possibleValues.length > 0)
+            {
+               setPossibleValueInitialDisplayValue(possibleValues[0].label);
+            }
+            else
+            {
+               setPossibleValueInitialDisplayValue(null);
+            }
+         }
+         catch (e)
+         {
+            console.log(`Error loading possible value: ${e}`);
+         }
+
+         actuallyDoingInitialLoadOfPossibleValue = false;
+         setDoingInitialLoadOfPossibleValue(false);
+      })();
+   }
+
+   if (dynamicField.possibleValueProps && possibleValueInitialDisplayValue)
+   {
+      dynamicField.possibleValueProps.initialDisplayValue = possibleValueInitialDisplayValue;
+   }
+
+   //////////////////////////////////////////////////////
+   // build array of options for the columns drop down //
+   // don't allow duplicates                           //
+   //////////////////////////////////////////////////////
+   const columnOptions: { value: number, label: string }[] = [];
+   const usedLabels: { [label: string]: boolean } = {};
+   for (let i = 0; i < columnNames.length; i++)
+   {
+      const label = columnNames[i];
+      if (!usedLabels[label])
+      {
+         columnOptions.push({label: label, value: i});
+         usedLabels[label] = true;
+      }
+   }
+
+   //////////////////////////////////////////////////////////////////////
+   // try to pick up changes in the hasHeaderRow toggle from way above //
+   //////////////////////////////////////////////////////////////////////
+   if (bulkLoadField.columnIndex != null && bulkLoadField.columnIndex != undefined && selectedColumn.label && columnNames[bulkLoadField.columnIndex] != selectedColumn.label)
+   {
+      setSelectedColumn({label: columnNames[bulkLoadField.columnIndex], value: bulkLoadField.columnIndex});
+      setSelectedColumnInputValue(columnNames[bulkLoadField.columnIndex]);
+   }
+
+   const mainFontSize = "0.875rem";
+   const smallerFontSize = "0.75rem";
+
+   /////////////////////////////////////////////////////////////////////////////////////////////
+   // some field types get their value from formik.                                           //
+   // so for a pre-populated value, do an on-load useEffect, that'll set the value in formik. //
+   /////////////////////////////////////////////////////////////////////////////////////////////
+   const {setFieldValue} = useFormikContext();
+   useEffect(() =>
+   {
+      if (valueType == "defaultValue")
+      {
+         setFieldValue(`${bulkLoadField.field.name}.defaultValue`, bulkLoadField.defaultValue);
+      }
+   }, []);
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   function columnChanged(event: any, newValue: any, reason: string)
+   {
+      setSelectedColumn(newValue);
+      setSelectedColumnInputValue(newValue == null ? "" : newValue.label);
+
+      bulkLoadField.columnIndex = newValue == null ? null : newValue.value;
+
+      if (fileDescription.hasHeaderRow)
+      {
+         bulkLoadField.headerName = newValue == null ? null : newValue.label;
+      }
+
+      bulkLoadField.error = null;
+      bulkLoadField.warning = null;
+      forceParentUpdate && forceParentUpdate();
+   }
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   function defaultValueChanged(newValue: any)
+   {
+      setFieldValue(`${bulkLoadField.field.name}.defaultValue`, newValue);
+      bulkLoadField.defaultValue = newValue;
+      bulkLoadField.error = null;
+      bulkLoadField.warning = null;
+      forceParentUpdate && forceParentUpdate();
+   }
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   function valueTypeChanged(isColumn: boolean)
+   {
+      const newValueType = isColumn ? "column" : "defaultValue";
+      bulkLoadField.valueType = newValueType;
+      setValueType(newValueType);
+      bulkLoadField.error = null;
+      bulkLoadField.warning = null;
+      forceParentUpdate && forceParentUpdate();
+   }
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   function mapValuesChanged(value: boolean)
+   {
+      bulkLoadField.doValueMapping = value;
+      forceParentUpdate && forceParentUpdate();
+   }
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   function clearIfEmptyChanged(value: boolean)
+   {
+      bulkLoadField.clearIfEmpty = value;
+      forceParentUpdate && forceParentUpdate();
+   }
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   function changeSelectedColumnInputValue(e: React.ChangeEvent<HTMLTextAreaElement | HTMLInputElement>)
+   {
+      setSelectedColumnInputValue(e.target.value);
+   }
+
+   return (<Box py="0.5rem" sx={{borderBottom: "1px solid lightgray", width: "100%", overflow: "auto"}} id={`blfmf-${bulkLoadField.field.name}`}>
+      <Box display="grid" gridTemplateColumns="200px 400px auto" fontSize="1rem" gap="0.5rem" sx={
+         {
+            "& .MuiFormControlLabel-label": {ml: "0 !important", fontWeight: "normal !important", fontSize: mainFontSize}
+         }}>
+
+         <Box display="flex" alignItems="flex-start">
+            {
+               (!isRequired) && <Tooltip placement="bottom" title="Remove this field from your mapping.">
+                  <Button sx={xIconButtonSX} onClick={() => removeFieldCallback()}><Icon>clear</Icon></Button>
+               </Tooltip>
+            }
+            <Box pt="0.625rem">
+               {bulkLoadField.getQualifiedLabel()}
+            </Box>
+         </Box>
+
+         <RadioGroup name="valueType" value={valueType}>
+            <Box>
+               <Box display="flex" alignItems="center" sx={{height: "45px"}}>
+                  <FormControlLabel value="column" control={<Radio size="small" onChange={(event, checked) => valueTypeChanged(checked)} />} label={"File column"} sx={{minWidth: "140px", whiteSpace: "nowrap"}} />
+                  {
+                     valueType == "column" && <Box width="100%">
+                        <Autocomplete
+                           id={bulkLoadField.field.name}
+                           renderInput={(params) => (<TextField {...params} label={""} value={selectedColumnInputValue} onChange={e => changeSelectedColumnInputValue(e)} fullWidth variant="outlined" autoComplete="off" type="search" InputProps={{...params.InputProps}} sx={{"& .MuiOutlinedInput-root": {borderRadius: "0.75rem"}}} />)}
+                           fullWidth
+                           options={columnOptions}
+                           multiple={false}
+                           defaultValue={selectedColumn}
+                           value={selectedColumn}
+                           inputValue={selectedColumnInputValue}
+                           onChange={columnChanged}
+                           getOptionLabel={(option) => typeof (option) == "string" ? option : (option?.label ?? "")}
+                           isOptionEqualToValue={(option, value) => option == null && value == null || option.value == value.value}
+                           renderOption={(props, option, state) => (<li {...props}>{option?.label ?? ""}</li>)}
+                           sx={{"& .MuiOutlinedInput-root": {padding: "0"}}}
+                        />
+                     </Box>
+                  }
+               </Box>
+               <Box display="flex" alignItems="center" sx={{height: "45px"}}>
+                  <FormControlLabel value="defaultValue" control={<Radio size="small" onChange={(event, checked) => valueTypeChanged(!checked)} />} label={"Default value"} sx={{minWidth: "140px", whiteSpace: "nowrap"}} />
+                  {
+                     valueType == "defaultValue" && actuallyDoingInitialLoadOfPossibleValue && <Box width="100%">Loading...</Box>
+                  }
+                  {
+                     valueType == "defaultValue" && !actuallyDoingInitialLoadOfPossibleValue && <Box width="100%">
+                        <QDynamicFormField
+                           name={`${bulkLoadField.field.name}.defaultValue`}
+                           displayFormat={""}
+                           label={""}
+                           formFieldObject={dynamicField}
+                           type={dynamicField.type}
+                           value={bulkLoadField.defaultValue}
+                           onChangeCallback={defaultValueChanged}
+                        />
+                     </Box>
+                  }
+               </Box>
+            </Box>
+            {
+               bulkLoadField.warning &&
+               <Box fontSize={smallerFontSize} color={colors.warning.main} ml="145px" className="bulkLoadFieldError">
+                  {bulkLoadField.warning}
+               </Box>
+            }
+            {
+               bulkLoadField.error &&
+               <Box fontSize={smallerFontSize} color={colors.error.main} ml="145px" className="bulkLoadFieldError">
+                  {bulkLoadField.error}
+               </Box>
+            }
+         </RadioGroup>
+
+         <Box ml="1rem">
+            {
+               valueType == "column" && <>
+                  <Box display="flex" alignItems="center" sx={{height: "45px"}}>
+                     <FormControlLabel value="mapValues" control={<Checkbox size="small" defaultChecked={bulkLoadField.doValueMapping} onChange={(event, checked) => mapValuesChanged(checked)} />} label={"Map values"} sx={{minWidth: "140px", whiteSpace: "nowrap"}} />
+                     {
+                        isBulkEdit && !isRequired && <FormControlLabel value="clearIfEmpty" control={<Checkbox size="small" defaultChecked={bulkLoadField.clearIfEmpty} onChange={(event, checked) => clearIfEmptyChanged(checked)} />} label={"Clear if empty"} sx={{minWidth: "140px", whiteSpace: "nowrap"}} />
+                     }
+                  </Box>
+                  <Box fontSize={mainFontSize} mt="0.5rem">
+                     Preview Values: <span style={{color: "gray"}}>{(fileDescription.getPreviewValues(selectedColumn?.value) ?? [""]).join(", ")}</span>
+                  </Box>
+               </>
+            }
+         </Box>
+
+      </Box>
+   </Box>);
+}

src/qqq/components/processes/BulkLoadFileMappingFields.tsx

@@ -0,0 +1,316 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2024.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+
+import Box from "@mui/material/Box";
+import Icon from "@mui/material/Icon";
+import colors from "qqq/assets/theme/base/colors";
+import QHierarchyAutoComplete, {Group, Option} from "qqq/components/misc/QHierarchyAutoComplete";
+import BulkLoadFileMappingField from "qqq/components/processes/BulkLoadFileMappingField";
+import {BulkLoadField, BulkLoadMapping, FileDescription} from "qqq/models/processes/BulkLoadModels";
+import React, {useEffect, useReducer, useState} from "react";
+
+interface BulkLoadMappingFieldsProps
+{
+   bulkLoadMapping: BulkLoadMapping,
+   fileDescription: FileDescription,
+   forceParentUpdate?: () => void,
+   isBulkEdit?: boolean
+}
+
+
+const ADD_SINGLE_FIELD_TOOLTIP = "Click to add this field to your mapping.";
+const ADD_MANY_FIELD_TOOLTIP = "Click to add this field to your mapping as many times as you need.";
+const ALREADY_ADDED_FIELD_TOOLTIP = "This field has already been added to your mapping.";
+
+/***************************************************************************
+ ** The section of the bulk load mapping screen with all the fields.
+ ***************************************************************************/
+export default function BulkLoadFileMappingFields({bulkLoadMapping, fileDescription, forceParentUpdate, isBulkEdit}: BulkLoadMappingFieldsProps): JSX.Element
+{
+   const [, forceUpdate] = useReducer((x) => x + 1, 0);
+
+   const [forceHierarchyAutoCompleteRerender, setForceHierarchyAutoCompleteRerender] = useState(0);
+
+   ////////////////////////////////////////////
+   // build list of fields that can be added //
+   ////////////////////////////////////////////
+   const [addFieldsGroup, setAddFieldsGroup] = useState({
+      label: bulkLoadMapping.tablesByPath[""]?.label,
+      value: "mainTable",
+      options: [],
+      subGroups: []
+   } as Group);
+   // const [addFieldsToggleStates, setAddFieldsToggleStates] = useState({} as { [name: string]: boolean });
+   const [addFieldsDisableStates, setAddFieldsDisableStates] = useState({} as { [name: string]: boolean });
+   const [tooltips, setTooltips] = useState({} as { [name: string]: string });
+
+   useEffect(() =>
+   {
+      const newDisableStates: { [name: string]: boolean } = {};
+      const newTooltips: { [name: string]: string } = {};
+
+      /////////////////////////////////////////////////////////////////////////////////////////////
+      // do the unused fields array first, as we've got some use-case where i think a field from //
+      // suggested mappings (or profiles?) are in this list, even though they shouldn't be?      //
+      /////////////////////////////////////////////////////////////////////////////////////////////
+      for (let field of bulkLoadMapping.unusedFields)
+      {
+         const qualifiedName = field.getQualifiedName();
+         newTooltips[qualifiedName] = field.isMany() ? ADD_MANY_FIELD_TOOLTIP : ADD_SINGLE_FIELD_TOOLTIP;
+      }
+
+      //////////////////////////////////////////////////
+      // then do all the required & additional fields //
+      //////////////////////////////////////////////////
+      for (let field of [...(bulkLoadMapping.requiredFields ?? []), ...(bulkLoadMapping.additionalFields ?? [])])
+      {
+         const qualifiedName = field.getQualifiedName();
+
+         if (bulkLoadMapping.layout == "WIDE" && field.isMany())
+         {
+            newDisableStates[qualifiedName] = false;
+            newTooltips[qualifiedName] = ADD_MANY_FIELD_TOOLTIP;
+         }
+         else
+         {
+            newDisableStates[qualifiedName] = true;
+            newTooltips[qualifiedName] = ALREADY_ADDED_FIELD_TOOLTIP;
+         }
+      }
+
+      setAddFieldsDisableStates(newDisableStates);
+      setTooltips(newTooltips);
+      setForceHierarchyAutoCompleteRerender(forceHierarchyAutoCompleteRerender + 1);
+
+   }, [bulkLoadMapping, bulkLoadMapping.layout]);
+
+
+   ///////////////////////////////////////////////
+   // initialize this structure on first render //
+   ///////////////////////////////////////////////
+   if (addFieldsGroup.options.length == 0)
+   {
+      for (let qualifiedFieldName in bulkLoadMapping.fieldsByTablePrefix[""])
+      {
+         const bulkLoadField = bulkLoadMapping.fieldsByTablePrefix[""][qualifiedFieldName];
+         const field = bulkLoadField.field;
+         addFieldsGroup.options.push({label: field.label, value: field.name, bulkLoadField: bulkLoadField});
+      }
+
+      for (let prefix in bulkLoadMapping.fieldsByTablePrefix)
+      {
+         if (prefix == "")
+         {
+            continue;
+         }
+
+         const associationOptions: Option[] = [];
+         const tableStructure = bulkLoadMapping.tablesByPath[prefix];
+         addFieldsGroup.subGroups.push({label: tableStructure.label, value: tableStructure.associationPath, options: associationOptions});
+
+         for (let qualifiedFieldName in bulkLoadMapping.fieldsByTablePrefix[prefix])
+         {
+            const bulkLoadField = bulkLoadMapping.fieldsByTablePrefix[prefix][qualifiedFieldName];
+            const field = bulkLoadField.field;
+            associationOptions.push({label: field.label, value: field.name, bulkLoadField: bulkLoadField});
+         }
+      }
+   }
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   function removeField(bulkLoadField: BulkLoadField)
+   {
+      addFieldsDisableStates[bulkLoadField.getQualifiedName()] = false;
+      setAddFieldsDisableStates(Object.assign({}, addFieldsDisableStates));
+
+      if (bulkLoadMapping.layout == "WIDE" && bulkLoadField.isMany())
+      {
+         //////////////////////////////////////////////////////////////////////////
+         // ok, you can add more - so don't disable and don't change the tooltip //
+         //////////////////////////////////////////////////////////////////////////
+      }
+      else
+      {
+         tooltips[bulkLoadField.getQualifiedName()] = ADD_SINGLE_FIELD_TOOLTIP;
+      }
+
+      bulkLoadMapping.removeField(bulkLoadField);
+      forceUpdate();
+      forceParentUpdate();
+      setForceHierarchyAutoCompleteRerender(forceHierarchyAutoCompleteRerender + 1);
+   }
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   function handleToggleField(option: Option, group: Group, newValue: boolean)
+   {
+      const fieldKey = group.value == "mainTable" ? option.value : group.value + "." + option.value;
+
+      // addFieldsToggleStates[fieldKey] = newValue;
+      // setAddFieldsToggleStates(Object.assign({}, addFieldsToggleStates));
+
+      addFieldsDisableStates[fieldKey] = newValue;
+      setAddFieldsDisableStates(Object.assign({}, addFieldsDisableStates));
+
+      const bulkLoadField = bulkLoadMapping.fields[fieldKey];
+      if (bulkLoadField)
+      {
+         if (newValue)
+         {
+            bulkLoadMapping.addField(bulkLoadField);
+         }
+         else
+         {
+            bulkLoadMapping.removeField(bulkLoadField);
+         }
+
+         forceUpdate();
+         forceParentUpdate();
+      }
+   }
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   function handleAddField(option: Option, group: Group)
+   {
+      const fieldKey = group.value == "mainTable" ? option.value : group.value + "." + option.value;
+
+      const bulkLoadField = bulkLoadMapping.fields[fieldKey];
+      if (bulkLoadField)
+      {
+         bulkLoadMapping.addField(bulkLoadField);
+
+         // addFieldsDisableStates[fieldKey] = true;
+         // setAddFieldsDisableStates(Object.assign({}, addFieldsDisableStates));
+
+         if (bulkLoadMapping.layout == "WIDE" && bulkLoadField.isMany())
+         {
+            //////////////////////////////////////////////////////////////////////////
+            // ok, you can add more - so don't disable and don't change the tooltip //
+            //////////////////////////////////////////////////////////////////////////
+         }
+         else
+         {
+            addFieldsDisableStates[fieldKey] = true;
+            setAddFieldsDisableStates(Object.assign({}, addFieldsDisableStates));
+
+            tooltips[fieldKey] = ALREADY_ADDED_FIELD_TOOLTIP;
+         }
+
+         forceUpdate();
+         forceParentUpdate();
+
+         document.getElementById("addFieldsButton")?.scrollIntoView();
+      }
+   }
+
+
+   let buttonBackground = "none";
+   let buttonBorder = colors.grayLines.main;
+   let buttonColor = colors.gray.main;
+
+   const addFieldMenuButtonStyles = {
+      borderRadius: "0.75rem",
+      border: `1px solid ${buttonBorder}`,
+      color: buttonColor,
+      textTransform: "none",
+      fontWeight: 500,
+      fontSize: "0.875rem",
+      p: "0.5rem",
+      backgroundColor: buttonBackground,
+      "&:focus:not(:hover)": {
+         color: buttonColor,
+         backgroundColor: buttonBackground,
+      },
+      "&:hover": {
+         color: buttonColor,
+         backgroundColor: buttonBackground,
+      }
+   };
+
+   return (
+      <>
+         {isBulkEdit ? <h5>Key Fields</h5> : <h5>Required Fields</h5>}
+         <Box pl={"1rem"}>
+            {
+               bulkLoadMapping.requiredFields.length == 0 &&
+               (
+                  isBulkEdit ?
+                     <i style={{fontSize: "0.875rem"}}>Select table key fields to continue.</i>
+                     :
+                     <i style={{fontSize: "0.875rem"}}>There are no required fields in this table.</i>
+               )
+            }
+            {bulkLoadMapping.requiredFields.map((bulkLoadField) => (
+               <BulkLoadFileMappingField
+                  fileDescription={fileDescription}
+                  key={bulkLoadField.getKey()}
+                  bulkLoadField={bulkLoadField}
+                  isRequired={true}
+                  forceParentUpdate={forceParentUpdate}
+                  isBulkEdit={isBulkEdit}
+               />
+            ))}
+         </Box>
+
+         <Box mt="1rem">
+            {isBulkEdit ? <h5>Fields To Update</h5> : <h5>Additional Fields</h5>}
+            <Box pl={"1rem"}>
+               {bulkLoadMapping.additionalFields.map((bulkLoadField) => (
+                  <BulkLoadFileMappingField
+                     fileDescription={fileDescription}
+                     key={bulkLoadField.getKey()}
+                     bulkLoadField={bulkLoadField}
+                     isRequired={false}
+                     removeFieldCallback={() => removeField(bulkLoadField)}
+                     forceParentUpdate={forceParentUpdate}
+                     isBulkEdit={isBulkEdit}
+                  />
+               ))}
+
+               <Box display="flex" pt="1rem" pl="12.5rem">
+                  <QHierarchyAutoComplete
+                     idPrefix="addFieldAutocomplete"
+                     defaultGroup={addFieldsGroup}
+                     menuDirection="up"
+                     buttonProps={{id: "addFieldsButton", sx: addFieldMenuButtonStyles}}
+                     buttonChildren={<><Icon sx={{mr: "0.5rem"}}>add</Icon> Add Fields <Icon sx={{ml: "0.5rem"}}>keyboard_arrow_down</Icon></>}
+                     isModeSelectOne
+                     keepOpenAfterSelectOne
+                     handleSelectedOption={handleAddField}
+                     forceRerender={forceHierarchyAutoCompleteRerender}
+                     disabledStates={addFieldsDisableStates}
+                     tooltips={tooltips}
+                  />
+               </Box>
+            </Box>
+         </Box>
+      </>
+   );
+}
+

src/qqq/components/processes/BulkLoadFileMappingForm.tsx

@@ -0,0 +1,695 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2024.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+import {QFieldMetaData} from "@kingsrook/qqq-frontend-core/lib/model/metaData/QFieldMetaData";
+import {QFieldType} from "@kingsrook/qqq-frontend-core/lib/model/metaData/QFieldType";
+import {QFrontendStepMetaData} from "@kingsrook/qqq-frontend-core/lib/model/metaData/QFrontendStepMetaData";
+import {QInstance} from "@kingsrook/qqq-frontend-core/lib/model/metaData/QInstance";
+import {QProcessMetaData} from "@kingsrook/qqq-frontend-core/lib/model/metaData/QProcessMetaData";
+import {QTableMetaData} from "@kingsrook/qqq-frontend-core/lib/model/metaData/QTableMetaData";
+import {QRecord} from "@kingsrook/qqq-frontend-core/lib/model/QRecord";
+import {Badge, Icon} from "@mui/material";
+import Autocomplete from "@mui/material/Autocomplete";
+import Box from "@mui/material/Box";
+import Grid from "@mui/material/Grid";
+import TextField from "@mui/material/TextField";
+import Tooltip from "@mui/material/Tooltip/Tooltip";
+import {useFormikContext} from "formik";
+import colors from "qqq/assets/theme/base/colors";
+import {DynamicFormFieldLabel} from "qqq/components/forms/DynamicForm";
+import QDynamicFormField from "qqq/components/forms/DynamicFormField";
+import DynamicFormUtils from "qqq/components/forms/DynamicFormUtils";
+import MDTypography from "qqq/components/legacy/MDTypography";
+import HelpContent from "qqq/components/misc/HelpContent";
+import SavedBulkLoadProfiles from "qqq/components/misc/SavedBulkLoadProfiles";
+import BulkLoadFileMappingFields from "qqq/components/processes/BulkLoadFileMappingFields";
+import {BulkLoadField, BulkLoadMapping, BulkLoadProfile, BulkLoadTableStructure, FileDescription, Wrapper} from "qqq/models/processes/BulkLoadModels";
+import {SubFormPreSubmitCallbackResultType} from "qqq/pages/processes/ProcessRun";
+import Client from "qqq/utils/qqq/Client";
+import React, {forwardRef, useEffect, useImperativeHandle, useReducer, useState} from "react";
+import ProcessViewForm from "./ProcessViewForm";
+
+const qController = Client.getInstance();
+
+interface BulkLoadMappingFormProps
+{
+   processValues: any,
+   tableMetaData: QTableMetaData,
+   metaData: QInstance,
+   setActiveStepLabel: (label: string) => void,
+   frontendStep: QFrontendStepMetaData,
+   processMetaData: QProcessMetaData,
+}
+
+
+/***************************************************************************
+ ** process component - screen where user does a bulk-load file mapping.
+ ***************************************************************************/
+const BulkLoadFileMappingForm = forwardRef(({processValues, tableMetaData, metaData, setActiveStepLabel, frontendStep, processMetaData}: BulkLoadMappingFormProps, ref) =>
+{
+   const {setFieldValue} = useFormikContext();
+
+   const savedBulkLoadProfileRecordProcessValue = processValues.savedBulkLoadProfileRecord;
+   const [currentSavedBulkLoadProfile, setCurrentSavedBulkLoadProfile] = useState(savedBulkLoadProfileRecordProcessValue == null ? null : new QRecord(savedBulkLoadProfileRecordProcessValue));
+   const [wrappedCurrentSavedBulkLoadProfile] = useState(new Wrapper<QRecord>(currentSavedBulkLoadProfile));
+
+   const [fieldErrors, setFieldErrors] = useState({} as { [fieldName: string]: string });
+   const [noMappedFieldsError, setNoMappedFieldsError] = useState(null as string);
+
+   const [suggestedBulkLoadProfile] = useState(processValues.suggestedBulkLoadProfile as BulkLoadProfile);
+   const [tableStructure] = useState(processValues.tableStructure as BulkLoadTableStructure);
+   const [bulkLoadMapping, setBulkLoadMapping] = useState(BulkLoadMapping.fromBulkLoadProfile(tableStructure, processValues.bulkLoadProfile, processMetaData.name));
+   const [wrappedBulkLoadMapping] = useState(new Wrapper<BulkLoadMapping>(bulkLoadMapping));
+
+   const [fileDescription] = useState(new FileDescription(processValues.headerValues, processValues.headerLetters, processValues.bodyValuesPreview));
+   fileDescription.setHasHeaderRow(bulkLoadMapping.hasHeaderRow);
+
+   const [, forceUpdate] = useReducer((x) => x + 1, 0);
+
+   /////////////////////////////////////////////////////////////////////////////////////////////////
+   // ok - so - ... Autocomplete, at least as we're using it for the layout field - doesn't like  //
+   // to change its initial value.  So, we want to work hard to force the Header sub-component to //
+   // re-render upon external changes to the layout (e.g., new profile being selected).           //
+   // use this state-counter to make that happen (and let's please never speak of it again).      //
+   /////////////////////////////////////////////////////////////////////////////////////////////////
+   const [rerenderHeader, setRerenderHeader] = useState(1);
+
+   ////////////////////////////////////////////////////////
+   // ref-based callback for integration with ProcessRun //
+   ////////////////////////////////////////////////////////
+   useImperativeHandle(ref, () =>
+   {
+      return {
+         preSubmit(): SubFormPreSubmitCallbackResultType
+         {
+            ///////////////////////////////////////////////////////////////////////////////////////////////
+            // convert the BulkLoadMapping to a BulkLoadProfile - the thing that the backend understands //
+            ///////////////////////////////////////////////////////////////////////////////////////////////
+            const {haveErrors: haveProfileErrors, profile} = wrappedBulkLoadMapping.get().toProfile();
+
+            const values: { [name: string]: any } = {};
+
+            ////////////////////////////////////////////////////
+            // always re-submit the full profile              //
+            // note mostly a copy in BulkLoadValueMappingForm //
+            ////////////////////////////////////////////////////
+            values["version"] = profile.version;
+            values["fieldListJSON"] = JSON.stringify(profile.fieldList);
+            values["savedBulkLoadProfileId"] = wrappedCurrentSavedBulkLoadProfile.get()?.values?.get("id");
+            values["layout"] = wrappedBulkLoadMapping.get().layout;
+            values["hasHeaderRow"] = wrappedBulkLoadMapping.get().hasHeaderRow;
+            values["isBulkEdit"] = wrappedBulkLoadMapping.get().isBulkEdit;
+            values["keyFields"] = wrappedBulkLoadMapping.get().keyFields;
+
+            let haveLocalErrors = false;
+            const fieldErrors: { [fieldName: string]: string } = {};
+            if (!values["layout"])
+            {
+               haveLocalErrors = true;
+               fieldErrors["layout"] = "This field is required.";
+            }
+
+            if (values["hasHeaderRow"] == null || values["hasHeaderRow"] == undefined)
+            {
+               haveLocalErrors = true;
+               fieldErrors["hasHeaderRow"] = "This field is required.";
+            }
+            setFieldErrors(fieldErrors);
+
+            if (values["isBulkEdit"] && (values["keyFields"] == null || values["keyFields"] == undefined))
+            {
+               haveLocalErrors = true;
+               fieldErrors["keyFields"] = "This field is required.";
+            }
+            setFieldErrors(fieldErrors);
+
+            if (wrappedBulkLoadMapping.get().requiredFields.length == 0 && wrappedBulkLoadMapping.get().additionalFields.length == 0)
+            {
+               setNoMappedFieldsError("You must have at least 1 field.");
+               haveLocalErrors = true;
+               setTimeout(() => setNoMappedFieldsError(null), 2500);
+            }
+            else
+            {
+               setNoMappedFieldsError(null);
+            }
+
+            if (haveProfileErrors)
+            {
+               setTimeout(() =>
+               {
+                  document.querySelector(".bulkLoadFieldError")?.scrollIntoView({behavior: "smooth", block: "center", inline: "center"});
+               }, 250);
+            }
+
+            return {maySubmit: !haveProfileErrors && !haveLocalErrors, values};
+         }
+      };
+   });
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   function bulkLoadProfileOnChangeCallback(profileRecord: QRecord | null)
+   {
+      setCurrentSavedBulkLoadProfile(profileRecord);
+      wrappedCurrentSavedBulkLoadProfile.set(profileRecord);
+
+      let newBulkLoadMapping: BulkLoadMapping;
+      if (profileRecord)
+      {
+         newBulkLoadMapping = BulkLoadMapping.fromSavedProfileRecord(processValues.tableStructure, profileRecord);
+      }
+      else
+      {
+         newBulkLoadMapping = new BulkLoadMapping(processValues.tableStructure);
+      }
+
+      handleNewBulkLoadMapping(newBulkLoadMapping);
+   }
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   function bulkLoadProfileResetToSuggestedMappingCallback()
+   {
+      handleNewBulkLoadMapping(BulkLoadMapping.fromBulkLoadProfile(processValues.tableStructure, suggestedBulkLoadProfile, processValues.name));
+   }
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   function handleNewBulkLoadMapping(newBulkLoadMapping: BulkLoadMapping)
+   {
+      const newRequiredFields: BulkLoadField[] = [];
+      for (let field of newBulkLoadMapping.requiredFields)
+      {
+         newRequiredFields.push(BulkLoadField.clone(field));
+      }
+      newBulkLoadMapping.requiredFields = newRequiredFields;
+
+      setBulkLoadMapping(newBulkLoadMapping);
+      wrappedBulkLoadMapping.set(newBulkLoadMapping);
+
+      setFieldValue("isBulkEdit", newBulkLoadMapping.isBulkEdit);
+      setFieldValue("keyFields", newBulkLoadMapping.keyFields);
+      setFieldValue("hasHeaderRow", newBulkLoadMapping.hasHeaderRow);
+      setFieldValue("layout", newBulkLoadMapping.layout);
+
+      setRerenderHeader(rerenderHeader + 1);
+   }
+
+   if (currentSavedBulkLoadProfile)
+   {
+      setActiveStepLabel(`File Mapping / ${currentSavedBulkLoadProfile.values.get("label")}`);
+   }
+   else
+   {
+      setActiveStepLabel("File Mapping");
+   }
+
+   return (<Box>
+
+      <Box py="1rem" display="flex">
+         <SavedBulkLoadProfiles
+            metaData={metaData}
+            tableMetaData={tableMetaData}
+            tableStructure={tableStructure}
+            currentSavedBulkLoadProfileRecord={currentSavedBulkLoadProfile}
+            currentMapping={bulkLoadMapping}
+            bulkLoadProfileOnChangeCallback={bulkLoadProfileOnChangeCallback}
+            bulkLoadProfileResetToSuggestedMappingCallback={bulkLoadProfileResetToSuggestedMappingCallback}
+            fileDescription={fileDescription}
+            isBulkEdit={processValues.isBulkEdit}
+         />
+      </Box>
+
+      <BulkLoadMappingHeader
+         tableMetaData={tableMetaData}
+         isBulkEdit={processValues.isBulkEdit}
+         key={rerenderHeader}
+         bulkLoadMapping={bulkLoadMapping}
+         fileDescription={fileDescription}
+         tableStructure={tableStructure}
+         fileName={processValues.fileBaseName}
+         fieldErrors={fieldErrors}
+         frontendStep={frontendStep}
+         processMetaData={processMetaData}
+         forceParentUpdate={() => forceUpdate()}
+      />
+
+      <Box mt="2rem">
+         <BulkLoadFileMappingFields
+            isBulkEdit={processValues.isBulkEdit}
+            bulkLoadMapping={bulkLoadMapping}
+            fileDescription={fileDescription}
+            forceParentUpdate={() =>
+            {
+               setRerenderHeader(rerenderHeader + 1);
+               forceUpdate();
+            }}
+         />
+         {
+            noMappedFieldsError && <Box color={colors.error.main} textAlign="right">{noMappedFieldsError}</Box>
+         }
+      </Box>
+
+   </Box>);
+
+});
+
+export default BulkLoadFileMappingForm;
+
+
+interface BulkLoadMappingHeaderProps
+{
+   isBulkEdit?: boolean,
+   fileDescription: FileDescription,
+   fileName: string,
+   bulkLoadMapping?: BulkLoadMapping,
+   fieldErrors: { [fieldName: string]: string },
+   tableStructure: BulkLoadTableStructure,
+   forceParentUpdate?: () => void,
+   frontendStep: QFrontendStepMetaData,
+   processMetaData: QProcessMetaData,
+   tableMetaData: QTableMetaData,
+}
+
+/***************************************************************************
+ ** private subcomponent - the header section of the bulk load file mapping screen.
+ ***************************************************************************/
+function BulkLoadMappingHeader({isBulkEdit, fileDescription, fileName, bulkLoadMapping, fieldErrors, tableStructure, forceParentUpdate, frontendStep, processMetaData, tableMetaData}: BulkLoadMappingHeaderProps): JSX.Element
+{
+   const [dynamicField, setDynamicField] = useState(null);
+
+   const viewFields = [
+      new QFieldMetaData({name: "fileName", label: "File Name", type: "STRING"}),
+      new QFieldMetaData({name: "fileDetails", label: "File Details", type: "STRING"}),
+   ];
+
+   const viewValues = {
+      "fileName": fileName,
+      "fileDetails": `${fileDescription.getColumnNames().length} column${fileDescription.getColumnNames().length == 1 ? "" : "s"}`
+   };
+
+   const hasHeaderRowFormField = {name: "hasHeaderRow", label: "Does the file have a header row?", type: "checkbox", isRequired: true, isEditable: true};
+
+   const layoutOptions = [
+      {label: "Flat", id: "FLAT"},
+      {label: "Tall", id: "TALL"},
+      {label: "Wide", id: "WIDE"},
+   ];
+
+   if (!tableStructure.associations)
+   {
+      layoutOptions.splice(1);
+   }
+
+   const selectedLayout = layoutOptions.filter(o => o.id == bulkLoadMapping.layout)[0] ?? null;
+
+   useEffect(() =>
+   {
+      (async () =>
+      {
+         if (isBulkEdit)
+         {
+            /////////////////////////////////////////////////////////////////////////
+            // if doing a bulk edit, the selected keyFields and set as the display //
+            /////////////////////////////////////////////////////////////////////////
+            const displayValues = new Map<string, string>;
+            if (bulkLoadMapping.keyFields)
+            {
+               const possibleValues = await qController.possibleValues(null, processMetaData.name, "tableKeyFields", bulkLoadMapping.keyFields, null);
+               console.log("Received possible values of: " + JSON.stringify(possibleValues));
+               displayValues.set("tableKeyFields", possibleValues[0].label);
+            }
+
+            const tableKeyFieldsField = processMetaData.frontendSteps.find(s => s.name == "fileMapping")?.formFields.find(f => f.name == "tableKeyFields");
+            const newDynamicField = DynamicFormUtils.getDynamicField(tableKeyFieldsField);
+            const dynamicFieldInObject: any = {};
+            dynamicFieldInObject[tableKeyFieldsField["name"]] = newDynamicField;
+            DynamicFormUtils.addPossibleValueProps(dynamicFieldInObject, [tableKeyFieldsField], null, processMetaData.name, displayValues);
+
+            keyFieldsChanged(bulkLoadMapping.keyFields);
+            setDynamicField(newDynamicField);
+            forceParentUpdate();
+         }
+      })();
+   }, [JSON.stringify(bulkLoadMapping)]);
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   function hasHeaderRowChanged(newValue: any)
+   {
+      bulkLoadMapping.hasHeaderRow = newValue;
+      fileDescription.hasHeaderRow = newValue;
+
+      bulkLoadMapping.handleChangeToHasHeaderRow(newValue, fileDescription);
+
+      fieldErrors.hasHeaderRow = null;
+      forceParentUpdate();
+   }
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   function layoutChanged(event: any, newValue: any)
+   {
+      bulkLoadMapping.switchLayout(newValue ? newValue.id : null);
+      fieldErrors.layout = null;
+      forceParentUpdate();
+   }
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   async function keyFieldsChanged(newValue: any)
+   {
+      fieldErrors.keyFields = null;
+
+      if (newValue && newValue.length > 0)
+      {
+         //////////////////////////////////////////////////////////
+         // validate that the fields in the key have been mapped //
+         //////////////////////////////////////////////////////////
+         console.log("Received key fields of: " + newValue);
+         const keyFields = newValue.split("|");
+         const unmappedKeyFields: string[] = [];
+         const requiredFields: BulkLoadField[] = [];
+         const additionalFields: BulkLoadField[] = [];
+
+         ////////////////////////////////////////////////////////////////////////////////////////////////
+         // iterate over all fields in the table, when there are key fields found, make them required, //
+         // otherwise add them to addition fields                                                      //
+         ////////////////////////////////////////////////////////////////////////////////////////////////
+         for (let bulkLoadField of [...bulkLoadMapping.requiredFields, ...bulkLoadMapping.additionalFields])
+         {
+            const qualifiedName = bulkLoadField.getQualifiedName();
+            const keyField = keyFields.find((k: string) => k == qualifiedName);
+            if (keyField)
+            {
+               requiredFields.push(bulkLoadField);
+               var fieldsByTablePrefix = bulkLoadMapping.fieldsByTablePrefix[""][keyField];
+               if (!fieldsByTablePrefix || fieldsByTablePrefix.columnIndex == null)
+               {
+                  unmappedKeyFields.push(tableMetaData.fields.get(keyField).label);
+               }
+            }
+            else
+            {
+               additionalFields.push(bulkLoadField);
+            }
+         }
+
+         bulkLoadMapping.requiredFields = requiredFields;
+         bulkLoadMapping.additionalFields = additionalFields;
+
+         if (unmappedKeyFields.length > 0)
+         {
+            fieldErrors.keyFields = "The following key fields are not mapped: " + unmappedKeyFields.join(", ");
+         }
+
+         bulkLoadMapping.handleChangeToKeyFields(newValue);
+      }
+
+      forceParentUpdate();
+   }
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   function getFormattedHelpContent(fieldName: string): JSX.Element
+   {
+      const field = frontendStep?.formFields?.find(f => f.name == fieldName);
+      let helpRoles = ["PROCESS_SCREEN", "ALL_SCREENS"];
+
+      let formattedHelpContent = <HelpContent helpContents={field?.helpContents} roles={helpRoles} helpContentKey={`process:${processMetaData?.name};field:${fieldName}`} />;
+      if (formattedHelpContent)
+      {
+         const mt = field && field.type == QFieldType.BOOLEAN ? "-0.5rem" : "0.5rem";
+
+         return <Box color="#757575" fontSize="0.875rem" mt={mt}>{formattedHelpContent}</Box>;
+      }
+
+      return null;
+   }
+
+   return (
+      <Box>
+         <h5>File Details</h5>
+         <Box ml="1rem">
+            <ProcessViewForm fields={viewFields} values={viewValues} columns={2} />
+            <BulkLoadMappingFilePreview fileDescription={fileDescription} bulkLoadMapping={bulkLoadMapping} />
+            <Grid container pt="1rem">
+               <Grid item xs={12} md={6}>
+                  <DynamicFormFieldLabel name={hasHeaderRowFormField.name} label={`${hasHeaderRowFormField.label} *`} />
+                  <QDynamicFormField name={hasHeaderRowFormField.name} displayFormat={""} label={""} formFieldObject={hasHeaderRowFormField} type={"checkbox"} value={bulkLoadMapping.hasHeaderRow} onChangeCallback={hasHeaderRowChanged} />
+                  {
+                     fieldErrors.hasHeaderRow &&
+                     <MDTypography component="div" variant="caption" color="error" fontWeight="regular" mt="0.25rem">
+                        {<div className="fieldErrorMessage">{fieldErrors.hasHeaderRow}</div>}
+                     </MDTypography>
+                  }
+                  {getFormattedHelpContent("hasHeaderRow")}
+               </Grid>
+               <Grid item xs={12} md={6}>
+                  {
+                     !isBulkEdit ? (
+                        <>
+                           <DynamicFormFieldLabel name={"layout"} label={"File Layout *"} />
+                           <Autocomplete
+                              id={"layout"}
+                              renderInput={(params) => (<TextField {...params} label={""} fullWidth variant="outlined" autoComplete="off" type="search" InputProps={{...params.InputProps}} sx={{"& .MuiOutlinedInput-root": {borderRadius: "0.75rem"}}} />)}
+                              options={layoutOptions}
+                              multiple={false}
+                              defaultValue={selectedLayout}
+                              onChange={layoutChanged}
+                              getOptionLabel={(option) => typeof (option) == "string" ? option : (option?.label ?? "")}
+                              isOptionEqualToValue={(option, value) => option == null && value == null || option.id == value.id}
+                              renderOption={(props, option, state) => (<li {...props}>{option?.label ?? ""}</li>)}
+                              disableClearable
+                              sx={{"& .MuiOutlinedInput-root": {padding: "0"}}}
+                           />
+                           {
+                              fieldErrors.layout &&
+                              <MDTypography component="div" variant="caption" color="error" fontWeight="regular" mt="0.25rem">
+                                 {<div className="fieldErrorMessage">{fieldErrors.layout}</div>}
+                              </MDTypography>
+                           }
+                           {getFormattedHelpContent("layout")}
+                        </>
+                     ) : (
+                        <>
+                           {
+                              dynamicField &&
+                              <>
+                                 <DynamicFormFieldLabel name={dynamicField.name} label={`${dynamicField.label} *`} />
+                                 <QDynamicFormField name={dynamicField.name} displayFormat={""} label={""} formFieldObject={dynamicField} type={"pvs"} value={bulkLoadMapping.keyFields} onChangeCallback={keyFieldsChanged} />
+                                 {
+                                    fieldErrors.keyFields &&
+                                    <MDTypography component="div" variant="caption" color="error" fontWeight="regular" mt="0.25rem">
+                                       {<div className="fieldErrorMessage">{fieldErrors.keyFields}</div>}
+                                    </MDTypography>
+                                 }
+                                 {getFormattedHelpContent("tableKeyFields")}
+                              </>
+                           }
+                        </>
+                     )
+                  }
+               </Grid>
+            </Grid>
+         </Box>
+      </Box>
+   );
+}
+
+
+interface BulkLoadMappingFilePreviewProps
+{
+   fileDescription: FileDescription,
+   bulkLoadMapping?: BulkLoadMapping
+}
+
+/***************************************************************************
+ ** private subcomponent - the file-preview section of the bulk load file mapping screen.
+ ***************************************************************************/
+function BulkLoadMappingFilePreview({fileDescription, bulkLoadMapping}: BulkLoadMappingFilePreviewProps): JSX.Element
+{
+   const rows: number[] = [];
+   for (let i = 0; i < fileDescription.bodyValuesPreview[0].length; i++)
+   {
+      rows.push(i);
+   }
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   function getValue(i: number, j: number)
+   {
+      const value = fileDescription.bodyValuesPreview[j][i];
+      if (value == null)
+      {
+         return "";
+      }
+
+      //////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+      // this was useful at one point in time when we had an object coming back for xlsx files with many different data types //
+      // we'd see a .string attribute, which would have the value we'd want to show.  not using it now, but keep in case      //
+      //////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+      // @ts-ignore
+      if (value && value.string)
+      {
+         // @ts-ignore
+         return (value.string);
+      }
+      return `${value}`;
+   }
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   function getHeaderColor(count: number): string
+   {
+      if (count > 0)
+      {
+         return "blue";
+      }
+
+      return "black";
+   }
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   function getCursor(count: number): string
+   {
+      if (count > 0)
+      {
+         return "pointer";
+      }
+
+      return "default";
+   }
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   function getColumnTooltip(fields: BulkLoadField[])
+   {
+      return (<Box>
+         This column is mapped to the field{fields.length == 1 ? "" : "s"}:
+         <ul style={{marginLeft: "1rem"}}>
+            {fields.map((field, i) => <li key={i}>{field.getQualifiedLabel()}</li>)}
+         </ul>
+      </Box>);
+   }
+
+   return (
+      <Box sx={{"& table, & td": {border: "1px solid black", borderCollapse: "collapse", padding: "0 0.25rem", fontSize: "0.875rem", whiteSpace: "nowrap"}}}>
+         <Box sx={{width: "100%", overflow: "auto"}}>
+            <table cellSpacing="0" width="100%">
+               <thead>
+                  <tr style={{backgroundColor: "#d3d3d3", height: "1.75rem"}}>
+                     <td></td>
+                     {fileDescription.headerLetters.map((letter, index) =>
+                     {
+                        const fields = bulkLoadMapping.getFieldsForColumnIndex(index);
+                        const count = fields.length;
+
+                        let dupeWarning = <></>;
+                        if (fileDescription.hasHeaderRow && fileDescription.duplicateHeaderIndexes[index])
+                        {
+                           dupeWarning = <Tooltip title="This column header is a duplicate.  Only the first occurrance of it will be used." placement="top" enterDelay={500}>
+                              <Icon color="warning" sx={{p: "0.125rem", mr: "0.25rem"}}>warning</Icon>
+                           </Tooltip>;
+                        }
+
+                        return (<td key={letter} style={{textAlign: "center", color: getHeaderColor(count), cursor: getCursor(count)}}>
+                           <>
+                              {
+                                 count > 0 &&
+                              <Tooltip title={getColumnTooltip(fields)} placement="top" enterDelay={500}>
+                                 <Box>
+                                    {dupeWarning}
+                                    {letter}
+                                    <Badge badgeContent={count} variant={"standard"} color="secondary" sx={{marginTop: ".75rem"}}><Icon></Icon></Badge>
+                                 </Box>
+                              </Tooltip>
+                              }
+                              {
+                                 count == 0 && <Box>{dupeWarning}{letter}</Box>
+                              }
+                           </>
+                        </td>);
+                     })}
+                  </tr>
+               </thead>
+               <tbody>
+                  <tr>
+                     <td style={{backgroundColor: "#d3d3d3", textAlign: "center"}}>1</td>
+
+                     {fileDescription.headerValues.map((value, index) =>
+                     {
+                        const fields = bulkLoadMapping.getFieldsForColumnIndex(index);
+                        const count = fields.length;
+                        const tdStyle = {color: getHeaderColor(count), cursor: getCursor(count), backgroundColor: ""};
+
+                        if (fileDescription.hasHeaderRow)
+                        {
+                           tdStyle.backgroundColor = "#ebebeb";
+
+                           if (count > 0)
+                           {
+                              return <td key={value} style={tdStyle}>
+                                 <Tooltip title={getColumnTooltip(fields)} placement="top" enterDelay={500}><Box>{value}</Box></Tooltip>
+                              </td>;
+                           }
+                           else
+                           {
+                              return <td key={value} style={tdStyle}>{value}</td>;
+                           }
+                        }
+                        else
+                        {
+                           return <td key={value} style={tdStyle}>{value}</td>;
+                        }
+                     }
+                     )}
+                  </tr>
+                  {rows.map((i) => (
+                     <tr key={i}>
+                        <td style={{backgroundColor: "#d3d3d3", textAlign: "center"}}>{i + 2}</td>
+                        {fileDescription.headerLetters.map((letter, j) => <td key={j}>{getValue(i, j)}</td>)}
+                     </tr>
+                  ))}
+               </tbody>
+            </table>
+         </Box>
+      </Box>
+   );
+}
+
+

src/qqq/components/processes/BulkLoadProfileForm.tsx

@@ -0,0 +1,103 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2024.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+import {QInstance} from "@kingsrook/qqq-frontend-core/lib/model/metaData/QInstance";
+import {QTableMetaData} from "@kingsrook/qqq-frontend-core/lib/model/metaData/QTableMetaData";
+import {QRecord} from "@kingsrook/qqq-frontend-core/lib/model/QRecord";
+import Box from "@mui/material/Box";
+import SavedBulkLoadProfiles from "qqq/components/misc/SavedBulkLoadProfiles";
+import {BulkLoadMapping, BulkLoadProfile, BulkLoadTableStructure, FileDescription, Wrapper} from "qqq/models/processes/BulkLoadModels";
+import {SubFormPreSubmitCallbackResultType} from "qqq/pages/processes/ProcessRun";
+import React, {forwardRef, useImperativeHandle, useState} from "react";
+
+interface BulkLoadValueMappingFormProps
+{
+   processValues: any,
+   tableMetaData: QTableMetaData,
+   metaData: QInstance
+}
+
+
+/***************************************************************************
+ ** For review & result screens of bulk load - this process component shows
+ ** the SavedBulkLoadProfiles button.
+ ***************************************************************************/
+const BulkLoadProfileForm = forwardRef(({processValues, tableMetaData, metaData}: BulkLoadValueMappingFormProps, ref) =>
+{
+   const savedBulkLoadProfileRecordProcessValue = processValues.savedBulkLoadProfileRecord;
+   const [savedBulkLoadProfileRecord, setSavedBulkLoadProfileRecord] = useState(savedBulkLoadProfileRecordProcessValue == null ? null : new QRecord(savedBulkLoadProfileRecordProcessValue));
+
+   const [tableStructure] = useState(processValues.tableStructure as BulkLoadTableStructure);
+
+   const [bulkLoadProfile, setBulkLoadProfile] = useState(processValues.bulkLoadProfile as BulkLoadProfile);
+   const [currentMapping, setCurrentMapping] = useState(BulkLoadMapping.fromBulkLoadProfile(tableStructure, bulkLoadProfile));
+   const [wrappedCurrentSavedBulkLoadProfile] = useState(new Wrapper<QRecord>(savedBulkLoadProfileRecord));
+
+   const [fileDescription] = useState(new FileDescription(processValues.headerValues, processValues.headerLetters, processValues.bodyValuesPreview));
+   fileDescription.setHasHeaderRow(currentMapping.hasHeaderRow);
+
+   useImperativeHandle(ref, () =>
+   {
+      return {
+         preSubmit(): SubFormPreSubmitCallbackResultType
+         {
+            const values: { [name: string]: any } = {};
+            values["savedBulkLoadProfileId"] = wrappedCurrentSavedBulkLoadProfile.get()?.values?.get("id");
+
+            return ({maySubmit: true, values});
+         }
+      };
+   });
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   function bulkLoadProfileOnChangeCallback(profileRecord: QRecord | null)
+   {
+      setSavedBulkLoadProfileRecord(profileRecord);
+      wrappedCurrentSavedBulkLoadProfile.set(profileRecord);
+
+      const newBulkLoadMapping = BulkLoadMapping.fromSavedProfileRecord(tableStructure, profileRecord);
+      setCurrentMapping(newBulkLoadMapping);
+   }
+
+
+   return (<Box>
+
+      <Box py="1rem" display="flex">
+         <SavedBulkLoadProfiles
+            metaData={metaData}
+            tableMetaData={tableMetaData}
+            tableStructure={tableStructure}
+            currentSavedBulkLoadProfileRecord={savedBulkLoadProfileRecord}
+            currentMapping={currentMapping}
+            allowSelectingProfile={false}
+            fileDescription={fileDescription}
+            bulkLoadProfileOnChangeCallback={bulkLoadProfileOnChangeCallback}
+            isBulkEdit={processValues.isBulkEdit}
+         />
+      </Box>
+
+   </Box>);
+});
+
+export default BulkLoadProfileForm;

src/qqq/components/processes/BulkLoadValueMappingForm.tsx

@@ -0,0 +1,234 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2024.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+import {QFieldMetaData} from "@kingsrook/qqq-frontend-core/lib/model/metaData/QFieldMetaData";
+import {QInstance} from "@kingsrook/qqq-frontend-core/lib/model/metaData/QInstance";
+import {QTableMetaData} from "@kingsrook/qqq-frontend-core/lib/model/metaData/QTableMetaData";
+import {QRecord} from "@kingsrook/qqq-frontend-core/lib/model/QRecord";
+import Box from "@mui/material/Box";
+import Icon from "@mui/material/Icon";
+import colors from "qqq/assets/theme/base/colors";
+import QDynamicFormField from "qqq/components/forms/DynamicFormField";
+import SavedBulkLoadProfiles from "qqq/components/misc/SavedBulkLoadProfiles";
+import {BulkLoadMapping, BulkLoadProfile, BulkLoadTableStructure, FileDescription, Wrapper} from "qqq/models/processes/BulkLoadModels";
+import {SubFormPreSubmitCallbackResultType} from "qqq/pages/processes/ProcessRun";
+import React, {forwardRef, useEffect, useImperativeHandle, useReducer, useState} from "react";
+
+interface BulkLoadValueMappingFormProps
+{
+   processValues: any,
+   setActiveStepLabel: (label: string) => void,
+   tableMetaData: QTableMetaData,
+   metaData: QInstance,
+   formFields: any[]
+}
+
+
+/***************************************************************************
+ ** process component used in bulk-load - on a screen that gets looped for
+ ** each field whose values are being mapped.
+ ***************************************************************************/
+const BulkLoadValueMappingForm = forwardRef(({processValues, setActiveStepLabel, tableMetaData, metaData, formFields}: BulkLoadValueMappingFormProps, ref) =>
+{
+   const [field, setField] = useState(processValues.valueMappingField ? new QFieldMetaData(processValues.valueMappingField) : null);
+   const [fieldFullName, setFieldFullName] = useState(processValues.valueMappingFullFieldName);
+   const [fileValues, setFileValues] = useState((processValues.fileValues ?? []) as string[]);
+   const [valueErrors, setValueErrors] = useState({} as { [fileValue: string]: any });
+
+   const [bulkLoadProfile, setBulkLoadProfile] = useState(processValues.bulkLoadProfile as BulkLoadProfile);
+
+   const savedBulkLoadProfileRecordProcessValue = processValues.savedBulkLoadProfileRecord;
+   const [savedBulkLoadProfileRecord, setSavedBulkLoadProfileRecord] = useState(savedBulkLoadProfileRecordProcessValue == null ? null : new QRecord(savedBulkLoadProfileRecordProcessValue));
+   const [wrappedCurrentSavedBulkLoadProfile] = useState(new Wrapper<QRecord>(savedBulkLoadProfileRecord));
+
+   const [tableStructure] = useState(processValues.tableStructure as BulkLoadTableStructure);
+
+   const [currentMapping, setCurrentMapping] = useState(initializeCurrentBulkLoadMapping());
+   const [wrappedBulkLoadMapping] = useState(new Wrapper<BulkLoadMapping>(currentMapping));
+
+   const [fileDescription] = useState(new FileDescription(processValues.headerValues, processValues.headerLetters, processValues.bodyValuesPreview));
+   fileDescription.setHasHeaderRow(currentMapping.hasHeaderRow);
+
+   const [, forceUpdate] = useReducer((x) => x + 1, 0);
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   function initializeCurrentBulkLoadMapping(): BulkLoadMapping
+   {
+      const bulkLoadMapping = BulkLoadMapping.fromBulkLoadProfile(tableStructure, bulkLoadProfile, processValues.name);
+
+      if (!bulkLoadMapping.valueMappings[fieldFullName])
+      {
+         bulkLoadMapping.valueMappings[fieldFullName] = {};
+      }
+
+      return (bulkLoadMapping);
+   }
+
+   useEffect(() =>
+   {
+      if (processValues.valueMappingField)
+      {
+         setField(new QFieldMetaData(processValues.valueMappingField));
+      }
+      else
+      {
+         setField(null);
+      }
+   }, [processValues.valueMappingField]);
+
+
+   ////////////////////////////////////////////////////////
+   // ref-based callback for integration with ProcessRun //
+   ////////////////////////////////////////////////////////
+   useImperativeHandle(ref, () =>
+   {
+      return {
+         preSubmit(): SubFormPreSubmitCallbackResultType
+         {
+            const values: { [name: string]: any } = {};
+
+            let anyErrors = false;
+            const mappedValues = currentMapping.valueMappings[fieldFullName];
+            if (field.isRequired)
+            {
+               for (let fileValue of fileValues)
+               {
+                  valueErrors[fileValue] = null;
+                  if (mappedValues[fileValue] == null || mappedValues[fileValue] == undefined || mappedValues[fileValue] == "")
+                  {
+                     valueErrors[fileValue] = "A value is required for this mapping";
+                     anyErrors = true;
+                  }
+               }
+            }
+
+            ///////////////////////////////////////////////////
+            // always re-submit the full profile             //
+            // note mostly a copy in BulkLoadFileMappingForm //
+            ///////////////////////////////////////////////////
+            const {haveErrors, profile} = wrappedBulkLoadMapping.get().toProfile();
+            values["version"] = profile.version;
+            values["fieldListJSON"] = JSON.stringify(profile.fieldList);
+            values["savedBulkLoadProfileId"] = wrappedCurrentSavedBulkLoadProfile.get()?.values?.get("id");
+            values["layout"] = wrappedBulkLoadMapping.get().layout;
+            values["hasHeaderRow"] = wrappedBulkLoadMapping.get().hasHeaderRow;
+
+            values["mappedValuesJSON"] = JSON.stringify(mappedValues);
+
+            return ({maySubmit: !anyErrors, values});
+         }
+      };
+   });
+
+   if (!field)
+   {
+      //////////////////////////////////////////////////////////////////////////////////////
+      // this happens like between steps - render empty rather than a flash of half-stuff //
+      //////////////////////////////////////////////////////////////////////////////////////
+      return (<Box></Box>);
+   }
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   function mappedValueChanged(fileValue: string, newValue: any)
+   {
+      valueErrors[fileValue] = null;
+      if (newValue == null)
+      {
+         delete currentMapping.valueMappings[fieldFullName][fileValue];
+      }
+      else
+      {
+         currentMapping.valueMappings[fieldFullName][fileValue] = newValue;
+      }
+      forceUpdate();
+   }
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   function bulkLoadProfileOnChangeCallback(profileRecord: QRecord | null)
+   {
+      setSavedBulkLoadProfileRecord(profileRecord);
+      wrappedCurrentSavedBulkLoadProfile.set(profileRecord);
+
+      const newBulkLoadMapping = BulkLoadMapping.fromSavedProfileRecord(tableStructure, profileRecord);
+      setCurrentMapping(newBulkLoadMapping);
+      wrappedBulkLoadMapping.set(newBulkLoadMapping);
+   }
+
+
+   setActiveStepLabel(`Value Mapping: ${field.label} (${processValues.valueMappingFieldIndex + 1} of ${processValues.fieldNamesToDoValueMapping?.length})`);
+
+   return (<Box>
+
+      <Box py="1rem" display="flex">
+         <SavedBulkLoadProfiles
+            metaData={metaData}
+            tableMetaData={tableMetaData}
+            tableStructure={tableStructure}
+            currentSavedBulkLoadProfileRecord={savedBulkLoadProfileRecord}
+            currentMapping={currentMapping}
+            allowSelectingProfile={false}
+            bulkLoadProfileOnChangeCallback={bulkLoadProfileOnChangeCallback}
+            fileDescription={fileDescription}
+            isBulkEdit={processValues.isBulkEdit}
+         />
+      </Box>
+
+      {
+         fileValues.map((fileValue, i) => (
+            <Box key={i} py="0.5rem" sx={{borderBottom: "0px solid lightgray", width: "100%", overflow: "auto"}}>
+               <Box display="grid" gridTemplateColumns="40% auto 60%" fontSize="1rem" gap="0.5rem">
+                  <Box mt="0.5rem" textAlign="right">{fileValue}</Box>
+                  <Box mt="0.625rem"><Icon>arrow_forward</Icon></Box>
+                  <Box maxWidth="300px">
+                     <QDynamicFormField
+                        name={`${fieldFullName}.value.${i}`}
+                        displayFormat={""}
+                        label={""}
+                        formFieldObject={formFields[i]}
+                        type={formFields[i].type}
+                        value={currentMapping.valueMappings[fieldFullName][fileValue]}
+                        onChangeCallback={(newValue) => mappedValueChanged(fileValue, newValue)}
+                     />
+                     {
+                        valueErrors[fileValue] &&
+                        <Box fontSize={"0.875rem"} mt={"-0.75rem"} color={colors.error.main}>
+                           {valueErrors[fileValue]}
+                        </Box>
+                     }
+                  </Box>
+               </Box>
+            </Box>
+         ))
+      }
+   </Box>);
+
+});
+
+
+export default BulkLoadValueMappingForm;

src/qqq/components/processes/ProcessSummaryResults.tsx

@@ -84,7 +84,7 @@ function ProcessSummaryResults({
    );
 
    return (
-      <Box m={3} mt={6}>
+      <Box m={{xs: 0, md: 3}} mt={"3rem!important"}>
          <Grid container>
             <Grid item xs={0} lg={2} />
             <Grid item xs={12} lg={8}>

src/qqq/components/processes/ProcessViewForm.tsx

@@ -0,0 +1,71 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2024.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+
+import {AdornmentType} from "@kingsrook/qqq-frontend-core/lib/model/metaData/AdornmentType";
+import {QFieldMetaData} from "@kingsrook/qqq-frontend-core/lib/model/metaData/QFieldMetaData";
+import Grid from "@mui/material/Grid";
+import MDTypography from "qqq/components/legacy/MDTypography";
+import ValueUtils from "qqq/utils/qqq/ValueUtils";
+
+interface ProcessViewFormProps
+{
+   fields: QFieldMetaData[];
+   values: { [fieldName: string]: any };
+   columns?: number;
+}
+
+ProcessViewForm.defaultProps = {
+   columns: 2
+};
+
+/***************************************************************************
+ ** a "view form" within a process step
+ **
+ ***************************************************************************/
+export default function ProcessViewForm({fields, values, columns}: ProcessViewFormProps): JSX.Element
+{
+   const sm = Math.floor(12 / columns);
+
+   return <Grid container>
+      {fields.map((field: QFieldMetaData) => (
+         field.hasAdornment(AdornmentType.ERROR) ? (
+            values[field.name] && (
+               <Grid item xs={12} sm={sm} key={field.name} display="flex" py={1} pr={2}>
+                  <MDTypography variant="button" fontWeight="regular">
+                     {ValueUtils.getValueForDisplay(field, values[field.name], undefined, "view")}
+                  </MDTypography>
+               </Grid>
+            )
+         ) : (
+            <Grid item xs={12} sm={sm} key={field.name} display="flex" py={1} pr={2}>
+               <MDTypography variant="button" fontWeight="bold">
+                  {field.label}
+                  : &nbsp;
+               </MDTypography>
+               <MDTypography variant="button" fontWeight="regular" color="text">
+                  {ValueUtils.getValueForDisplay(field, values[field.name], undefined, "view")}
+               </MDTypography>
+            </Grid>
+         )))
+      }
+   </Grid>;
+}

src/qqq/components/processes/ValidationReview.tsx

@@ -24,29 +24,45 @@ import {QInstance} from "@kingsrook/qqq-frontend-core/lib/model/metaData/QInstan
 import {QProcessMetaData} from "@kingsrook/qqq-frontend-core/lib/model/metaData/QProcessMetaData";
 import {QTableMetaData} from "@kingsrook/qqq-frontend-core/lib/model/metaData/QTableMetaData";
 import {QRecord} from "@kingsrook/qqq-frontend-core/lib/model/QRecord";
-import {Box, Button, FormControlLabel, ListItem, Radio, RadioGroup, Typography} from "@mui/material";
+import {Button, FormControlLabel, ListItem, Radio, RadioGroup, Typography} from "@mui/material";
+import Box from "@mui/material/Box";
 import Grid from "@mui/material/Grid";
 import Icon from "@mui/material/Icon";
 import IconButton from "@mui/material/IconButton";
 import List from "@mui/material/List";
 import ListItemText from "@mui/material/ListItemText";
-import React, {useState} from "react";
 import MDTypography from "qqq/components/legacy/MDTypography";
 import CustomWidthTooltip from "qqq/components/tooltips/CustomWidthTooltip";
+import RecordGridWidget, {ChildRecordListData} from "qqq/components/widgets/misc/RecordGridWidget";
 import {ProcessSummaryLine} from "qqq/models/processes/ProcessSummaryLine";
+import {renderSectionOfFields} from "qqq/pages/records/view/RecordView";
 import Client from "qqq/utils/qqq/Client";
+import TableUtils from "qqq/utils/qqq/TableUtils";
 import ValueUtils from "qqq/utils/qqq/ValueUtils";
+import React, {useEffect, useState} from "react";
 
 interface Props
 {
-   qInstance: QInstance;
-   process: QProcessMetaData;
-   table: QTableMetaData;
-   processValues: any;
-   step: QFrontendStepMetaData;
-   previewRecords: QRecord[];
-   formValues: any;
-   doFullValidationRadioChangedHandler: any
+   qInstance: QInstance,
+   process: QProcessMetaData,
+   table: QTableMetaData,
+   processValues: any,
+   step: QFrontendStepMetaData,
+   previewRecords: QRecord[],
+   formValues: any,
+   doFullValidationRadioChangedHandler: any,
+   loadingRecords?: boolean
+}
+
+////////////////////////////////////////////////////////////////////////////
+// e.g., for bulk-load, where we want to show associations under a record //
+// the processValue will have these data, to drive this screen.           //
+////////////////////////////////////////////////////////////////////////////
+interface AssociationPreview
+{
+   tableName: string;
+   widgetName: string;
+   associationName: string;
 }
 
 /*******************************************************************************
@@ -55,21 +71,76 @@ interface Props
  ** results when they are available.
  *******************************************************************************/
 function ValidationReview({
-   qInstance, process, table = null, processValues, step, previewRecords = [], formValues, doFullValidationRadioChangedHandler,
+   qInstance, process, table = null, processValues, step, previewRecords = [], formValues, doFullValidationRadioChangedHandler, loadingRecords
 }: Props): JSX.Element
 {
    const [previewRecordIndex, setPreviewRecordIndex] = useState(0);
    const [sourceTableMetaData, setSourceTableMetaData] = useState(null as QTableMetaData);
+   const [previewTableMetaData, setPreviewTableMetaData] = useState(null as QTableMetaData);
+   const [childTableMetaData, setChildTableMetaData] = useState({} as { [name: string]: QTableMetaData });
 
-   if(processValues.sourceTable && !sourceTableMetaData)
+   const [associationPreviewsByWidgetName, setAssociationPreviewsByWidgetName] = useState({} as { [widgetName: string]: AssociationPreview });
+
+   if (processValues.sourceTable && !sourceTableMetaData)
    {
       (async () =>
       {
-         const sourceTableMetaData = await Client.getInstance().loadTableMetaData(processValues.sourceTable)
+         const sourceTableMetaData = await Client.getInstance().loadTableMetaData(processValues.sourceTable);
          setSourceTableMetaData(sourceTableMetaData);
       })();
    }
 
+   ////////////////////////////////////////////////////////////////////////////////////////
+   // load meta-data and set up associations-data structure, if so directed from backend //
+   ////////////////////////////////////////////////////////////////////////////////////////
+   useEffect(() =>
+   {
+      if (processValues.formatPreviewRecordUsingTableLayout && !previewTableMetaData)
+      {
+         (async () =>
+         {
+            const previewTableMetaData = await Client.getInstance().loadTableMetaData(processValues.formatPreviewRecordUsingTableLayout);
+            setPreviewTableMetaData(previewTableMetaData);
+         })();
+      }
+
+      try
+      {
+         const previewRecordAssociatedTableNames: string[] = processValues.previewRecordAssociatedTableNames ?? [];
+         const previewRecordAssociatedWidgetNames: string[] = processValues.previewRecordAssociatedWidgetNames ?? [];
+         const previewRecordAssociationNames: string[] = processValues.previewRecordAssociationNames ?? [];
+
+         const associationPreviewsByWidgetName: { [widgetName: string]: AssociationPreview } = {};
+         for (let i = 0; i < Math.min(previewRecordAssociatedTableNames.length, previewRecordAssociatedWidgetNames.length, previewRecordAssociationNames.length); i++)
+         {
+            const associationPreview = {tableName: previewRecordAssociatedTableNames[i], widgetName: previewRecordAssociatedWidgetNames[i], associationName: previewRecordAssociationNames[i]};
+            associationPreviewsByWidgetName[associationPreview.widgetName] = associationPreview;
+         }
+         setAssociationPreviewsByWidgetName(associationPreviewsByWidgetName);
+
+         if (Object.keys(associationPreviewsByWidgetName))
+         {
+            (async () =>
+            {
+               for (let key in associationPreviewsByWidgetName)
+               {
+                  const associationPreview = associationPreviewsByWidgetName[key];
+                  childTableMetaData[associationPreview.tableName] = await Client.getInstance().loadTableMetaData(associationPreview.tableName);
+                  setChildTableMetaData(Object.assign({}, childTableMetaData));
+               }
+            })();
+         }
+      }
+      catch (e)
+      {
+         console.log(`Error setting up association previews: ${e}`);
+      }
+   }, []);
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
    const updatePreviewRecordIndex = (offset: number) =>
    {
       let newIndex = previewRecordIndex + offset;
@@ -85,6 +156,10 @@ function ValidationReview({
       setPreviewRecordIndex(newIndex);
    };
 
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
    const buildDoFullValidationRadioListItem = (value: "true" | "false", labelText: string, tooltipHTML: JSX.Element): JSX.Element =>
    {
       ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
@@ -191,6 +266,7 @@ function ValidationReview({
       </List>
    );
 
+
    const recordPreviewWidget = step.recordListFields && (
       <Box border="1px solid rgb(70%, 70%, 70%)" borderRadius="10px" p={2} mt={2}>
          <Box mx={2} mt={-5} p={1} sx={{width: "fit-content", borderColor: "rgb(70%, 70%, 70%)", borderWidth: "2px", borderStyle: "solid", borderRadius: ".25em", backgroundColor: "#FFFFFF"}} width="initial" color="white">
@@ -200,43 +276,47 @@ function ValidationReview({
             <MDTypography color="body" variant="body2" component="div" mb={2}>
                <Box display="flex">
                   {
-                     processValues?.previewMessage && previewRecords && previewRecords.length > 0 ? (
-                        <>
-                           <i>{processValues?.previewMessage}</i>
-                           <CustomWidthTooltip
-                              title={(
-                                 <div>
-                                    Note that the number of preview records available may be fewer than the total number of records being processed.
-                                 </div>
-                              )}
-                           >
-                              <IconButton sx={{py: 0}}><Icon fontSize="small">info_outlined</Icon></IconButton>
-                           </CustomWidthTooltip>
-                        </>
-                     ) : (
-                        <>
-                           <i>No record previews are available at this time.</i>
-                           <CustomWidthTooltip
-                              title={(
-                                 <div>
-                                    {
-                                       processValues.validationSummary ? (
-                                          <>
-                                             It appears as though this process does not contain any valid records.
-                                          </>
-                                       ) : (
-                                          <>
-                                             If you choose to Perform Validation, and there are any valid records, then you will see a preview here.
-                                          </>
-                                       )
-                                    }
-                                 </div>
-                              )}
-                           >
-                              <IconButton sx={{py: 0}}><Icon fontSize="small">info_outlined</Icon></IconButton>
-                           </CustomWidthTooltip>
-                        </>
-                     )
+                     loadingRecords ? <i>Loading...</i> : <>
+                        {
+                           processValues?.previewMessage && previewRecords && previewRecords.length > 0 ? (
+                              <>
+                                 <i>{processValues?.previewMessage}</i>
+                                 <CustomWidthTooltip
+                                    title={(
+                                       <div>
+                                          Note that the number of preview records available may be fewer than the total number of records being processed.
+                                       </div>
+                                    )}
+                                 >
+                                    <IconButton sx={{py: 0}}><Icon fontSize="small">info_outlined</Icon></IconButton>
+                                 </CustomWidthTooltip>
+                              </>
+                           ) : (
+                              <>
+                                 <i>No record previews are available at this time.</i>
+                                 <CustomWidthTooltip
+                                    title={(
+                                       <div>
+                                          {
+                                             processValues.validationSummary ? (
+                                                <>
+                                                   It appears as though this process does not contain any valid records.
+                                                </>
+                                             ) : (
+                                                <>
+                                                   If you choose to Perform Validation, and there are any valid records, then you will see a preview here.
+                                                </>
+                                             )
+                                          }
+                                       </div>
+                                    )}
+                                 >
+                                    <IconButton sx={{py: 0}}><Icon fontSize="small">info_outlined</Icon></IconButton>
+                                 </CustomWidthTooltip>
+                              </>
+                           )
+                        }
+                     </>
                   }
                </Box>
             </MDTypography>
@@ -244,16 +324,27 @@ function ValidationReview({
                <Box sx={{maxHeight: "calc(100vh - 640px)", overflow: "auto", minHeight: "300px", marginRight: "-40px"}}>
                   <Box sx={{paddingRight: "40px"}}>
                      {
-                        previewRecords && previewRecords[previewRecordIndex] && step.recordListFields.map((field) => (
+                        previewRecords && !processValues.formatPreviewRecordUsingTableLayout && previewRecords[previewRecordIndex] && step.recordListFields.map((field) => (
                            <Box key={field.name} style={{marginBottom: "12px"}}>
                               <b>{`${field.label}:`}</b>
                               {" "}
-                           &nbsp;
+                              &nbsp;
                               {" "}
                               {ValueUtils.getDisplayValue(field, previewRecords[previewRecordIndex], "view")}
                            </Box>
                         ))
                      }
+                     {
+                        previewRecords && processValues.formatPreviewRecordUsingTableLayout && previewRecords[previewRecordIndex] &&
+                        <PreviewRecordUsingTableLayout
+                           index={previewRecordIndex}
+                           record={previewRecords[previewRecordIndex]}
+                           tableMetaData={previewTableMetaData}
+                           qInstance={qInstance}
+                           associationPreviewsByWidgetName={associationPreviewsByWidgetName}
+                           childTableMetaData={childTableMetaData}
+                        />
+                     }
                   </Box>
                </Box>
                {
@@ -273,7 +364,7 @@ function ValidationReview({
    );
 
    return (
-      <Box m={3}>
+      <Box m={{xs: 0, md: 3}} mt={"3rem!important"}>
          <Grid container spacing={2}>
             <Grid item xs={12} lg={6}>
                <MDTypography color="body" variant="button">
@@ -288,4 +379,84 @@ function ValidationReview({
    );
 }
 
+
+
+interface PreviewRecordUsingTableLayoutProps
+{
+   index: number
+   record: QRecord,
+   tableMetaData: QTableMetaData,
+   qInstance: QInstance,
+   associationPreviewsByWidgetName: { [widgetName: string]: AssociationPreview },
+   childTableMetaData: { [name: string]: QTableMetaData },
+}
+
+function PreviewRecordUsingTableLayout({record, tableMetaData, qInstance, associationPreviewsByWidgetName, childTableMetaData, index}: PreviewRecordUsingTableLayoutProps): JSX.Element
+{
+   if (!tableMetaData)
+   {
+      return (<i>Loading...</i>);
+   }
+
+   const renderedSections: JSX.Element[] = [];
+   const tableSections = TableUtils.getSectionsForRecordSidebar(tableMetaData);
+
+   for (let i = 0; i < tableSections.length; i++)
+   {
+      const section = tableSections[i];
+      if (section.isHidden)
+      {
+         continue;
+      }
+
+      if (section.fieldNames)
+      {
+         renderedSections.push(<Box mb="1rem">
+            <Box><h4>{section.label}</h4></Box>
+            <Box ml="1rem">
+               {renderSectionOfFields(section.name, section.fieldNames, tableMetaData, false, record, undefined, {label: {fontWeight: "500"}})}
+            </Box>
+         </Box>);
+      }
+      else if (section.widgetName)
+      {
+         const widget = qInstance.widgets.get(section.widgetName);
+         if (widget)
+         {
+            let data: ChildRecordListData = null;
+            if (associationPreviewsByWidgetName[section.widgetName])
+            {
+               const associationPreview = associationPreviewsByWidgetName[section.widgetName];
+               const associationRecords = record.associatedRecords?.get(associationPreview.associationName) ?? [];
+               data = {
+                  canAddChildRecord: false,
+                  childTableMetaData: childTableMetaData[associationPreview.tableName],
+                  defaultValuesForNewChildRecords: {},
+                  disabledFieldsForNewChildRecords: {},
+                  queryOutput: {records: associationRecords},
+                  totalRows: associationRecords.length,
+                  tablePath: "",
+                  title: "",
+                  viewAllLink: "",
+               };
+
+               renderedSections.push(<Box mb="1rem">
+                  {
+                     data && <Box>
+                        <Box mb="0.5rem"><h4>{section.label}</h4></Box>
+                        <Box pl="1rem">
+                           <RecordGridWidget key={index} data={data} widgetMetaData={widget} disableRowClick gridOnly={true} gridDensity={"compact"} />
+                        </Box>
+                     </Box>
+                  }
+               </Box>);
+            }
+         }
+      }
+   }
+
+   return <>{renderedSections}</>;
+}
+
+
 export default ValidationReview;

src/qqq/components/query/AssignFilterVariable.tsx

@@ -0,0 +1,66 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2023.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+import {QFieldMetaData} from "@kingsrook/qqq-frontend-core/lib/model/metaData/QFieldMetaData";
+import {FilterVariableExpression} from "@kingsrook/qqq-frontend-core/lib/model/query/FilterVariableExpression";
+import Box from "@mui/material/Box";
+import Icon from "@mui/material/Icon";
+import Tooltip from "@mui/material/Tooltip";
+import CriteriaDateField from "qqq/components/query/CriteriaDateField";
+import React, {SyntheticEvent, useState} from "react";
+
+
+export type Expression = FilterVariableExpression;
+
+
+interface AssignFilterButtonProps
+{
+   valueIndex: number;
+   field: QFieldMetaData;
+   valueChangeHandler: (event: React.ChangeEvent | SyntheticEvent, valueIndex?: number | "all", newValue?: any) => void;
+}
+
+CriteriaDateField.defaultProps = {
+   valueIndex: 0,
+   label: "Value",
+   idPrefix: "value-"
+};
+
+export default function AssignFilterVariable({valueIndex, field, valueChangeHandler}: AssignFilterButtonProps): JSX.Element
+{
+   const [isValueAVariable, setIsValueAVariable] = useState(false);
+
+   const handleVariableButtonOnClick = () =>
+   {
+      setIsValueAVariable(!isValueAVariable);
+      const expression = new FilterVariableExpression({fieldName: field.name, valueIndex: valueIndex});
+      valueChangeHandler(null, valueIndex, expression);
+   };
+
+   return <Box display="flex" alignItems="flex-end">
+      <Box>
+         <Tooltip title={`Use a variable as the value for the ${field.label} field`} placement="bottom">
+            <Icon fontSize="small" color="info" sx={{mx: 0.25, cursor: "pointer", position: "relative", top: "2px"}} onClick={handleVariableButtonOnClick}>functions</Icon>
+         </Tooltip>
+      </Box>
+   </Box>;
+}
+

src/qqq/components/query/BasicAndAdvancedQueryControls.tsx

@@ -79,8 +79,12 @@ interface BasicAndAdvancedQueryControlsProps
 
    queryScreenUsage: QueryScreenUsage;
 
+   allowVariables?: boolean;
+
    mode: string;
    setMode: (mode: string) => void;
+
+   omitExposedJoins?: string[];
 }
 
 let debounceTimeout: string | number | NodeJS.Timeout;
@@ -114,7 +118,7 @@ export function getCurrentSortIndicator(queryFilter: QQueryFilter, tableMetaData
  *******************************************************************************/
 const BasicAndAdvancedQueryControls = forwardRef((props: BasicAndAdvancedQueryControlsProps, ref) =>
 {
-   const {metaData, tableMetaData, savedViewsComponent, columnMenuComponent, quickFilterFieldNames, setQuickFilterFieldNames, setQueryFilter, queryFilter, gridApiRef, queryFilterJSON, mode, setMode} = props;
+   const {metaData, tableMetaData, savedViewsComponent, columnMenuComponent, quickFilterFieldNames, setQuickFilterFieldNames, setQueryFilter, queryFilter, gridApiRef, queryFilterJSON, mode, setMode, queryScreenUsage} = props;
 
    /////////////////////
    // state variables //
@@ -181,7 +185,7 @@ const BasicAndAdvancedQueryControls = forwardRef((props: BasicAndAdvancedQueryCo
    {
       // todo - sometimes i want contains instead of equals on strings (client.name, for example...)
       let defaultOperator = field?.possibleValueSourceName ? QCriteriaOperator.IN : QCriteriaOperator.EQUALS;
-      if (field?.type == QFieldType.DATE_TIME || field?.type == QFieldType.DATE)
+      if (field?.type == QFieldType.DATE_TIME)
       {
          defaultOperator = QCriteriaOperator.GREATER_THAN;
       }
@@ -625,6 +629,7 @@ const BasicAndAdvancedQueryControls = forwardRef((props: BasicAndAdvancedQueryCo
          handleSelectedField={handleSetSort}
          fieldEndAdornment={<Box whiteSpace="nowrap"><Icon>arrow_upward</Icon><Icon>arrow_downward</Icon></Box>}
          handleAdornmentClick={handleSetSortArrowClick}
+         omitExposedJoins={props.omitExposedJoins}
       />);
 
    const filterBuilderMouseEvents =
@@ -676,12 +681,14 @@ const BasicAndAdvancedQueryControls = forwardRef((props: BasicAndAdvancedQueryCo
 
                               return (<QuickFilter
                                  key={fieldName}
+                                 allowVariables={props.allowVariables}
                                  fullFieldName={fieldName}
                                  tableMetaData={tableMetaData}
                                  updateCriteria={updateQuickCriteria}
                                  criteriaParam={getQuickCriteriaParam(fieldName)}
                                  fieldMetaData={field}
                                  defaultOperator={defaultOperator}
+                                 queryScreenUsage={queryScreenUsage}
                                  handleRemoveQuickFilterField={null} />);
                            })
                         }
@@ -700,7 +707,9 @@ const BasicAndAdvancedQueryControls = forwardRef((props: BasicAndAdvancedQueryCo
                                  updateCriteria={updateQuickCriteria}
                                  criteriaParam={getQuickCriteriaParam(fieldName)}
                                  fieldMetaData={field}
+                                 allowVariables={props.allowVariables}
                                  defaultOperator={defaultOperator}
+                                 queryScreenUsage={queryScreenUsage}
                                  handleRemoveQuickFilterField={handleRemoveQuickFilterField} />);
                            })
                         }
@@ -715,6 +724,7 @@ const BasicAndAdvancedQueryControls = forwardRef((props: BasicAndAdvancedQueryCo
                               buttonChildren={"Add Filter"}
                               isModeSelectOne={true}
                               handleSelectedField={handleFieldListMenuSelection}
+                              omitExposedJoins={props.omitExposedJoins}
                            />
                         }
                      </>

src/qqq/components/query/CriteriaDateField.tsx

@@ -21,6 +21,7 @@
 
 import {QFieldMetaData} from "@kingsrook/qqq-frontend-core/lib/model/metaData/QFieldMetaData";
 import {QFieldType} from "@kingsrook/qqq-frontend-core/lib/model/metaData/QFieldType";
+import {FilterVariableExpression} from "@kingsrook/qqq-frontend-core/lib/model/query/FilterVariableExpression";
 import {NowExpression} from "@kingsrook/qqq-frontend-core/lib/model/query/NowExpression";
 import {NowWithOffsetExpression, NowWithOffsetOperator, NowWithOffsetUnit} from "@kingsrook/qqq-frontend-core/lib/model/query/NowWithOffsetExpression";
 import {ThisOrLastPeriodExpression, ThisOrLastPeriodOperator, ThisOrLastPeriodUnit} from "@kingsrook/qqq-frontend-core/lib/model/query/ThisOrLastPeriodExpression";
@@ -34,14 +35,14 @@ import MenuItem from "@mui/material/MenuItem";
 import {styled} from "@mui/material/styles";
 import TextField from "@mui/material/TextField";
 import Tooltip, {tooltipClasses, TooltipProps} from "@mui/material/Tooltip";
-import React, {SyntheticEvent, useEffect, useReducer, useState} from "react";
 import AdvancedDateTimeFilterValues from "qqq/components/query/AdvancedDateTimeFilterValues";
 import {QFilterCriteriaWithId} from "qqq/components/query/CustomFilterPanel";
 import {EvaluatedExpression} from "qqq/components/query/EvaluatedExpression";
 import {makeTextField} from "qqq/components/query/FilterCriteriaRowValues";
+import React, {SyntheticEvent, useReducer, useState} from "react";
 
 
-export type Expression = NowWithOffsetExpression | ThisOrLastPeriodExpression | NowExpression;
+export type Expression = NowWithOffsetExpression | ThisOrLastPeriodExpression | NowExpression | FilterVariableExpression;
 
 
 interface CriteriaDateFieldProps
@@ -52,6 +53,7 @@ interface CriteriaDateFieldProps
    field: QFieldMetaData;
    criteria: QFilterCriteriaWithId;
    valueChangeHandler: (event: React.ChangeEvent | SyntheticEvent, valueIndex?: number | "all", newValue?: any) => void;
+   allowVariables?: boolean;
 }
 
 CriteriaDateField.defaultProps = {
@@ -60,19 +62,30 @@ CriteriaDateField.defaultProps = {
    idPrefix: "value-"
 };
 
-export default function CriteriaDateField({valueIndex, label, idPrefix, field, criteria, valueChangeHandler}: CriteriaDateFieldProps): JSX.Element
+export const NoWrapTooltip = styled(({className, children, ...props}: TooltipProps) => (
+   <Tooltip {...props} classes={{popper: className}}>{children}</Tooltip>
+))({
+   [`& .${tooltipClasses.tooltip}`]: {
+      whiteSpace: "nowrap"
+   },
+});
+
+export default function CriteriaDateField({valueIndex, label, idPrefix, field, criteria, valueChangeHandler, allowVariables}: CriteriaDateFieldProps): JSX.Element
 {
+   const [relativeDateTimeOpen, setRelativeDateTimeOpen] = useState(false);
    const [relativeDateTimeMenuAnchorElement, setRelativeDateTimeMenuAnchorElement] = useState(null);
-   const [forceAdvancedDateTimeDialogOpen, setForceAdvancedDateTimeDialogOpen] = useState(false)
+   const [forceAdvancedDateTimeDialogOpen, setForceAdvancedDateTimeDialogOpen] = useState(false);
    const [, forceUpdate] = useReducer((x) => x + 1, 0);
 
    const openRelativeDateTimeMenu = (event: React.MouseEvent<HTMLElement>) =>
    {
+      setRelativeDateTimeOpen(true);
       setRelativeDateTimeMenuAnchorElement(event.currentTarget);
    };
 
    const closeRelativeDateTimeMenu = () =>
    {
+      setRelativeDateTimeOpen(false);
       setRelativeDateTimeMenuAnchorElement(null);
    };
 
@@ -137,20 +150,12 @@ export default function CriteriaDateField({valueIndex, label, idPrefix, field, c
    const isExpression = criteria.values && criteria.values[valueIndex] && criteria.values[valueIndex].type;
    const currentExpression = isExpression ? criteria.values[valueIndex] : null;
 
-   const NoWrapTooltip = styled(({className, children, ...props}: TooltipProps) => (
-      <Tooltip {...props} classes={{popper: className}}>{children}</Tooltip>
-   ))({
-      [`& .${tooltipClasses.tooltip}`]: {
-         whiteSpace: "nowrap"
-      },
-   });
-
    const tooltipMenuItemFromExpression = (valueIndex: number, tooltipPlacement: "left" | "right", expression: Expression) =>
    {
       let startOfPrefix = "";
-      if(expression.type == "ThisOrLastPeriod")
+      if (expression.type == "ThisOrLastPeriod")
       {
-         if(field.type == QFieldType.DATE_TIME || expression.timeUnit != "DAYS")
+         if (field.type == QFieldType.DATE_TIME || expression.timeUnit != "DAYS")
          {
             startOfPrefix = "start of ";
          }
@@ -191,84 +196,120 @@ export default function CriteriaDateField({valueIndex, label, idPrefix, field, c
       setTimeout(() => setForceAdvancedDateTimeDialogOpen(false), 100);
    }
 
+   const makeFilterVariableTextField = (expression: FilterVariableExpression, valueIndex: number = 0, label = "Value", idPrefix = "value-") =>
+   {
+      const clearValue = (event: React.MouseEvent<HTMLAnchorElement> | React.MouseEvent<HTMLButtonElement>, index: number) =>
+      {
+         valueChangeHandler(event, index, "");
+         document.getElementById(`${idPrefix}${criteria.id}`).focus();
+      };
+
+      const inputProps2: any = {};
+      inputProps2.endAdornment = (
+         <InputAdornment position="end">
+            <IconButton sx={{visibility: expression ? "visible" : "hidden"}} onClick={(event) => clearValue(event, valueIndex)}>
+               <Icon>closer</Icon>
+            </IconButton>
+         </InputAdornment>
+      );
+
+      return <NoWrapTooltip title={<EvaluatedExpression field={field} expression={expression} />} placement="bottom" enterDelay={1000} sx={{marginLeft: "-75px !important", marginTop: "-8px !important"}}><TextField
+         id={`${idPrefix}${criteria.id}`}
+         label={label}
+         variant="standard"
+         autoComplete="off"
+         InputProps={{disabled: true, readOnly: true, unselectable: "off", ...inputProps2}}
+         InputLabelProps={{shrink: true}}
+         value="${VARIABLE}"
+         fullWidth
+      /></NoWrapTooltip>;
+   };
+
+
    return <Box display="flex" alignItems="flex-end">
       {
-         isExpression ? makeDateTimeExpressionTextField(criteria.values[valueIndex], valueIndex, label, idPrefix)
-            : makeTextField(field, criteria, valueChangeHandler, valueIndex, label, idPrefix)
+         isExpression ?
+            currentExpression?.type == "FilterVariableExpression" ? (
+               makeFilterVariableTextField(criteria.values[valueIndex], valueIndex, label, idPrefix)
+            ) : (
+               makeDateTimeExpressionTextField(criteria.values[valueIndex], valueIndex, label, idPrefix)
+            )
+            : makeTextField(field, criteria, valueChangeHandler, valueIndex, label, idPrefix, allowVariables)
       }
-      <Box>
-         <Tooltip title={`Choose a common relative ${field.type == QFieldType.DATE ? "date" : "date-time"} expression`} placement="bottom">
-            <Icon fontSize="small" color="info" sx={{mx: 0.25, cursor: "pointer", position: "relative", top: "2px"}} onClick={openRelativeDateTimeMenu}>date_range</Icon>
-         </Tooltip>
-         <Menu
-            open={relativeDateTimeMenuAnchorElement}
-            anchorEl={relativeDateTimeMenuAnchorElement}
-            transformOrigin={{horizontal: "left", vertical: "top"}}
-            onClose={closeRelativeDateTimeMenu}
-         >
-            {
-               field.type == QFieldType.DATE ?
-                  <Box display="flex">
-                     <Box>
-                        {tooltipMenuItemFromExpression(valueIndex, "left", newNowWithOffsetExpression("MINUS", 7, "DAYS"))}
-                        {tooltipMenuItemFromExpression(valueIndex, "left", newNowWithOffsetExpression("MINUS", 14, "DAYS"))}
-                        {tooltipMenuItemFromExpression(valueIndex, "left", newNowWithOffsetExpression("MINUS", 30, "DAYS"))}
-                        {tooltipMenuItemFromExpression(valueIndex, "left", newNowWithOffsetExpression("MINUS", 90, "DAYS"))}
-                        {tooltipMenuItemFromExpression(valueIndex, "left", newNowWithOffsetExpression("MINUS", 180, "DAYS"))}
-                        {tooltipMenuItemFromExpression(valueIndex, "left", newNowWithOffsetExpression("MINUS", 1, "YEARS"))}
-                        <Divider />
-                        <Tooltip title="Define a custom expression" placement="left">
-                           <MenuItem onClick={doForceAdvancedDateTimeDialogOpen}>Custom</MenuItem>
-                        </Tooltip>
+      {
+         (!isExpression || currentExpression?.type != "FilterVariableExpression") && (
+            <><Box>
+               <Tooltip title={`Choose a common relative ${field.type == QFieldType.DATE ? "date" : "date-time"} expression`} placement="bottom">
+                  <Icon fontSize="small" color="info" sx={{mx: 0.25, cursor: "pointer", position: "relative", top: "2px"}} onClick={openRelativeDateTimeMenu}>date_range</Icon>
+               </Tooltip>
+               <Menu
+                  open={relativeDateTimeOpen}
+                  anchorEl={relativeDateTimeMenuAnchorElement}
+                  transformOrigin={{horizontal: "left", vertical: "top"}}
+                  onClose={closeRelativeDateTimeMenu}
+               >
+                  {field.type == QFieldType.DATE ?
+                     <Box display="flex">
+                        <Box>
+                           {tooltipMenuItemFromExpression(valueIndex, "left", newNowWithOffsetExpression("MINUS", 7, "DAYS"))}
+                           {tooltipMenuItemFromExpression(valueIndex, "left", newNowWithOffsetExpression("MINUS", 14, "DAYS"))}
+                           {tooltipMenuItemFromExpression(valueIndex, "left", newNowWithOffsetExpression("MINUS", 30, "DAYS"))}
+                           {tooltipMenuItemFromExpression(valueIndex, "left", newNowWithOffsetExpression("MINUS", 90, "DAYS"))}
+                           {tooltipMenuItemFromExpression(valueIndex, "left", newNowWithOffsetExpression("MINUS", 180, "DAYS"))}
+                           {tooltipMenuItemFromExpression(valueIndex, "left", newNowWithOffsetExpression("MINUS", 1, "YEARS"))}
+                           <Divider />
+                           <Tooltip title="Define a custom expression" placement="left">
+                              <MenuItem onClick={doForceAdvancedDateTimeDialogOpen}>Custom</MenuItem>
+                           </Tooltip>
+                        </Box>
+                        <Box>
+                           {tooltipMenuItemFromExpression(valueIndex, "right", newThisOrLastPeriodExpression("THIS", "DAYS"))}
+                           {tooltipMenuItemFromExpression(valueIndex, "right", newThisOrLastPeriodExpression("LAST", "DAYS"))}
+                           {tooltipMenuItemFromExpression(valueIndex, "right", newThisOrLastPeriodExpression("THIS", "WEEKS"))}
+                           {tooltipMenuItemFromExpression(valueIndex, "right", newThisOrLastPeriodExpression("LAST", "WEEKS"))}
+                           {tooltipMenuItemFromExpression(valueIndex, "right", newThisOrLastPeriodExpression("THIS", "MONTHS"))}
+                           {tooltipMenuItemFromExpression(valueIndex, "right", newThisOrLastPeriodExpression("LAST", "MONTHS"))}
+                           {tooltipMenuItemFromExpression(valueIndex, "right", newThisOrLastPeriodExpression("THIS", "YEARS"))}
+                           {tooltipMenuItemFromExpression(valueIndex, "right", newThisOrLastPeriodExpression("LAST", "YEARS"))}
+                        </Box>
                      </Box>
-                     <Box>
-                        {tooltipMenuItemFromExpression(valueIndex, "right", newThisOrLastPeriodExpression("THIS", "DAYS"))}
-                        {tooltipMenuItemFromExpression(valueIndex, "right", newThisOrLastPeriodExpression("LAST", "DAYS"))}
-                        {tooltipMenuItemFromExpression(valueIndex, "right", newThisOrLastPeriodExpression("THIS", "WEEKS"))}
-                        {tooltipMenuItemFromExpression(valueIndex, "right", newThisOrLastPeriodExpression("LAST", "WEEKS"))}
-                        {tooltipMenuItemFromExpression(valueIndex, "right", newThisOrLastPeriodExpression("THIS", "MONTHS"))}
-                        {tooltipMenuItemFromExpression(valueIndex, "right", newThisOrLastPeriodExpression("LAST", "MONTHS"))}
-                        {tooltipMenuItemFromExpression(valueIndex, "right", newThisOrLastPeriodExpression("THIS", "YEARS"))}
-                        {tooltipMenuItemFromExpression(valueIndex, "right", newThisOrLastPeriodExpression("LAST", "YEARS"))}
-                     </Box>
-                  </Box>
-                  :
-                  <Box display="flex">
-                     <Box>
-                        {tooltipMenuItemFromExpression(valueIndex, "left", newNowWithOffsetExpression("MINUS", 1, "HOURS"))}
-                        {tooltipMenuItemFromExpression(valueIndex, "left", newNowWithOffsetExpression("MINUS", 12, "HOURS"))}
-                        {tooltipMenuItemFromExpression(valueIndex, "left", newNowWithOffsetExpression("MINUS", 24, "HOURS"))}
-                        {tooltipMenuItemFromExpression(valueIndex, "left", newNowWithOffsetExpression("MINUS", 7, "DAYS"))}
-                        {tooltipMenuItemFromExpression(valueIndex, "left", newNowWithOffsetExpression("MINUS", 14, "DAYS"))}
-                        {tooltipMenuItemFromExpression(valueIndex, "left", newNowWithOffsetExpression("MINUS", 30, "DAYS"))}
-                        {tooltipMenuItemFromExpression(valueIndex, "left", newNowWithOffsetExpression("MINUS", 90, "DAYS"))}
-                        {tooltipMenuItemFromExpression(valueIndex, "left", newNowWithOffsetExpression("MINUS", 180, "DAYS"))}
-                        {tooltipMenuItemFromExpression(valueIndex, "left", newNowWithOffsetExpression("MINUS", 1, "YEARS"))}
-                        <Divider />
-                        <Tooltip title="Define a custom expression" placement="left">
-                           <MenuItem onClick={doForceAdvancedDateTimeDialogOpen}>Custom</MenuItem>
-                        </Tooltip>
-                     </Box>
-                     <Box>
-                        {tooltipMenuItemFromExpression(valueIndex, "right", newNowExpression())}
-                        {tooltipMenuItemFromExpression(valueIndex, "right", newThisOrLastPeriodExpression("THIS", "HOURS"))}
-                        {tooltipMenuItemFromExpression(valueIndex, "right", newThisOrLastPeriodExpression("LAST", "HOURS"))}
-                        {tooltipMenuItemFromExpression(valueIndex, "right", newThisOrLastPeriodExpression("THIS", "DAYS"))}
-                        {tooltipMenuItemFromExpression(valueIndex, "right", newThisOrLastPeriodExpression("LAST", "DAYS"))}
-                        {tooltipMenuItemFromExpression(valueIndex, "right", newThisOrLastPeriodExpression("THIS", "WEEKS"))}
-                        {tooltipMenuItemFromExpression(valueIndex, "right", newThisOrLastPeriodExpression("LAST", "WEEKS"))}
-                        {tooltipMenuItemFromExpression(valueIndex, "right", newThisOrLastPeriodExpression("THIS", "MONTHS"))}
-                        {tooltipMenuItemFromExpression(valueIndex, "right", newThisOrLastPeriodExpression("LAST", "MONTHS"))}
-                        {tooltipMenuItemFromExpression(valueIndex, "right", newThisOrLastPeriodExpression("THIS", "YEARS"))}
-                        {tooltipMenuItemFromExpression(valueIndex, "right", newThisOrLastPeriodExpression("LAST", "YEARS"))}
-                     </Box>
-                  </Box>
-            }
-         </Menu>
-      </Box>
-      <Box>
-         <AdvancedDateTimeFilterValues type={field.type} expression={currentExpression} onSave={(expression: any) => saveNewDateTimeExpression(valueIndex, expression)} forcedOpen={forceAdvancedDateTimeDialogOpen} />
-      </Box>
+                     :
+                     <Box display="flex">
+                        <Box>
+                           {tooltipMenuItemFromExpression(valueIndex, "left", newNowWithOffsetExpression("MINUS", 1, "HOURS"))}
+                           {tooltipMenuItemFromExpression(valueIndex, "left", newNowWithOffsetExpression("MINUS", 12, "HOURS"))}
+                           {tooltipMenuItemFromExpression(valueIndex, "left", newNowWithOffsetExpression("MINUS", 24, "HOURS"))}
+                           {tooltipMenuItemFromExpression(valueIndex, "left", newNowWithOffsetExpression("MINUS", 7, "DAYS"))}
+                           {tooltipMenuItemFromExpression(valueIndex, "left", newNowWithOffsetExpression("MINUS", 14, "DAYS"))}
+                           {tooltipMenuItemFromExpression(valueIndex, "left", newNowWithOffsetExpression("MINUS", 30, "DAYS"))}
+                           {tooltipMenuItemFromExpression(valueIndex, "left", newNowWithOffsetExpression("MINUS", 90, "DAYS"))}
+                           {tooltipMenuItemFromExpression(valueIndex, "left", newNowWithOffsetExpression("MINUS", 180, "DAYS"))}
+                           {tooltipMenuItemFromExpression(valueIndex, "left", newNowWithOffsetExpression("MINUS", 1, "YEARS"))}
+                           <Divider />
+                           <Tooltip title="Define a custom expression" placement="left">
+                              <MenuItem onClick={doForceAdvancedDateTimeDialogOpen}>Custom</MenuItem>
+                           </Tooltip>
+                        </Box>
+                        <Box>
+                           {tooltipMenuItemFromExpression(valueIndex, "right", newNowExpression())}
+                           {tooltipMenuItemFromExpression(valueIndex, "right", newThisOrLastPeriodExpression("THIS", "HOURS"))}
+                           {tooltipMenuItemFromExpression(valueIndex, "right", newThisOrLastPeriodExpression("LAST", "HOURS"))}
+                           {tooltipMenuItemFromExpression(valueIndex, "right", newThisOrLastPeriodExpression("THIS", "DAYS"))}
+                           {tooltipMenuItemFromExpression(valueIndex, "right", newThisOrLastPeriodExpression("LAST", "DAYS"))}
+                           {tooltipMenuItemFromExpression(valueIndex, "right", newThisOrLastPeriodExpression("THIS", "WEEKS"))}
+                           {tooltipMenuItemFromExpression(valueIndex, "right", newThisOrLastPeriodExpression("LAST", "WEEKS"))}
+                           {tooltipMenuItemFromExpression(valueIndex, "right", newThisOrLastPeriodExpression("THIS", "MONTHS"))}
+                           {tooltipMenuItemFromExpression(valueIndex, "right", newThisOrLastPeriodExpression("LAST", "MONTHS"))}
+                           {tooltipMenuItemFromExpression(valueIndex, "right", newThisOrLastPeriodExpression("THIS", "YEARS"))}
+                           {tooltipMenuItemFromExpression(valueIndex, "right", newThisOrLastPeriodExpression("LAST", "YEARS"))}
+                        </Box>
+                     </Box>}
+               </Menu>
+            </Box><Box>
+               <AdvancedDateTimeFilterValues type={field.type} expression={currentExpression} onSave={(expression: any) => saveNewDateTimeExpression(valueIndex, expression)} forcedOpen={forceAdvancedDateTimeDialogOpen} />
+            </Box></>
+         )
+      }
    </Box>;
 }
 

src/qqq/components/query/CustomColumnsPanel.tsx

@@ -21,7 +21,9 @@
 
 import {QInstance} from "@kingsrook/qqq-frontend-core/lib/model/metaData/QInstance";
 import {QTableMetaData} from "@kingsrook/qqq-frontend-core/lib/model/metaData/QTableMetaData";
-import {Box, FormControlLabel, FormGroup} from "@mui/material";
+
+import {FormControlLabel, FormGroup} from "@mui/material";
+import Box from "@mui/material/Box";
 import Button from "@mui/material/Button";
 import Icon from "@mui/material/Icon";
 import IconButton from "@mui/material/IconButton";
@@ -56,7 +58,7 @@ export const CustomColumnsPanel = forwardRef<any, GridColumnsPanelProps>(
       const someRef = createRef();
 
       const textRef = useRef(null);
-      const [didInitialFocus, setDidInitialFocus] = useState(false)
+      const [didInitialFocus, setDidInitialFocus] = useState(false);
 
       const [openGroups, setOpenGroups] = useState(props.initialOpenedGroups || {});
       const openGroupsBecauseOfFilter = {} as { [name: string]: boolean };
@@ -71,9 +73,9 @@ export const CustomColumnsPanel = forwardRef<any, GridColumnsPanelProps>(
 
       console.log(`Open groups: ${JSON.stringify(openGroups)}`);
 
-      if(!didInitialFocus)
+      if (!didInitialFocus)
       {
-         if(textRef.current)
+         if (textRef.current)
          {
             textRef.current.select();
             setDidInitialFocus(true);
@@ -189,11 +191,11 @@ export const CustomColumnsPanel = forwardRef<any, GridColumnsPanelProps>(
       ///////////////////////////////////////////////////////////////////////////////////////////////////////
       // always sort columns by label.  note, in future may offer different sorts - here's where to do it. //
       ///////////////////////////////////////////////////////////////////////////////////////////////////////
-      const sortedColumns = [... columns];
+      const sortedColumns = [...columns];
       sortedColumns.sort((a, b): number =>
       {
          return a.headerName.localeCompare(b.headerName);
-      })
+      });
 
       for (let i = 0; i < sortedColumns.length; i++)
       {
@@ -361,7 +363,7 @@ export const CustomColumnsPanel = forwardRef<any, GridColumnsPanelProps>(
       const changeFilterText = (newValue: string) =>
       {
          setFilterText(newValue);
-         props.filterTextChanger(newValue)
+         props.filterTextChanger(newValue);
       };
 
       const filterTextChanged = (event: React.ChangeEvent<HTMLTextAreaElement | HTMLInputElement>) =>

src/qqq/components/query/CustomFilterPanel.tsx

@@ -28,8 +28,8 @@ import Box from "@mui/material/Box";
 import Button from "@mui/material/Button/Button";
 import Icon from "@mui/material/Icon/Icon";
 import {GridFilterPanelProps, GridSlotsComponentsProps} from "@mui/x-data-grid-pro";
-import React, {forwardRef, useReducer} from "react";
 import {FilterCriteriaRow, getDefaultCriteriaValue} from "qqq/components/query/FilterCriteriaRow";
+import React, {forwardRef, useReducer} from "react";
 
 
 declare module "@mui/x-data-grid"
@@ -43,13 +43,14 @@ declare module "@mui/x-data-grid"
       metaData: QInstance;
       queryFilter: QQueryFilter;
       updateFilter: (newFilter: QQueryFilter) => void;
+      omitExposedJoins?: string[]
    }
 }
 
 
 export class QFilterCriteriaWithId extends QFilterCriteria
 {
-   id: number
+   id: number;
 }
 
 
@@ -62,6 +63,7 @@ export const CustomFilterPanel = forwardRef<any, GridFilterPanelProps>(
       const [, forceUpdate] = useReducer((x) => x + 1, 0);
 
       const queryFilter = props.queryFilter;
+
       // console.log(`CustomFilterPanel: filter: ${JSON.stringify(queryFilter)}`);
 
       function focusLastField()
@@ -124,7 +126,7 @@ export const CustomFilterPanel = forwardRef<any, GridFilterPanelProps>(
          }
       }
 
-      if(queryFilter.criteria.length == 1 && !queryFilter.criteria[0].fieldName)
+      if (queryFilter.criteria.length == 1 && !queryFilter.criteria[0].fieldName)
       {
          focusLastField();
       }
@@ -142,7 +144,7 @@ export const CustomFilterPanel = forwardRef<any, GridFilterPanelProps>(
       {
          queryFilter.criteria[index] = newCriteria;
 
-         clearTimeout(debounceTimeout)
+         clearTimeout(debounceTimeout);
          debounceTimeout = setTimeout(() => props.updateFilter(queryFilter), needDebounce ? 500 : 1);
 
          forceUpdate();
@@ -178,6 +180,9 @@ export const CustomFilterPanel = forwardRef<any, GridFilterPanelProps>(
                            updateCriteria={(newCriteria, needDebounce) => updateCriteria(newCriteria, index, needDebounce)}
                            removeCriteria={() => removeCriteria(index)}
                            updateBooleanOperator={(newValue) => updateBooleanOperator(newValue)}
+                           allowVariables={props.allowVariables}
+                           queryScreenUsage={props.queryScreenUsage}
+                           omitExposedJoins={props.omitExposedJoins}
                         />
                         {/*JSON.stringify(criteria)*/}
                      </Box>

src/qqq/components/query/CustomPaginationComponent.tsx

@@ -26,9 +26,9 @@ import Box from "@mui/material/Box";
 import Icon from "@mui/material/Icon";
 import IconButton from "@mui/material/IconButton";
 import {GridRowsProp} from "@mui/x-data-grid-pro";
-import React from "react";
 import CustomWidthTooltip from "qqq/components/tooltips/CustomWidthTooltip";
 import ValueUtils from "qqq/utils/qqq/ValueUtils";
+import React from "react";
 
 interface CustomPaginationProps
 {
@@ -56,7 +56,7 @@ export default function CustomPaginationComponent({tableMetaData, rows, totalRec
          The number of rows shown on this screen may be greater than the number of {tableMetaData?.label} records
          that match your query, because you have included fields from other tables which may have
          more than one record associated with each {tableMetaData?.label}.
-      </>
+      </>;
       let distinctPart = isJoinMany ? (<Box display="inline" component="span" textAlign="right">
          &nbsp;({ValueUtils.safeToLocaleString(distinctRecords)} distinct<CustomWidthTooltip title={tooltipHTML}>
             <IconButton sx={{p: 0, pl: 0.25, mb: 0.25}}><Icon fontSize="small" sx={{fontSize: "1.125rem !important", color: "#9f9f9f"}}>info_outlined</Icon></IconButton>
@@ -66,13 +66,23 @@ export default function CustomPaginationComponent({tableMetaData, rows, totalRec
 
       if (tableMetaData && !tableMetaData.capabilities.has(Capability.TABLE_COUNT))
       {
+         if (loading)
+         {
+            return "Counting...";
+         }
+
+         if (!rows || rows.length == 0)
+         {
+            return "No rows";
+         }
+
          ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
          // to avoid a non-countable table showing (this is what data-grid did) 91-100 even if there were only 95 records, //
          // we'll do this... not quite good enough, but better than the original                                           //
          ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
          if (rows.length > 0 && rows.length < to - from)
          {
-            to = from + rows.length;
+            to = from + (rows.length - 1);
          }
          return (`Showing ${from.toLocaleString()} to ${to.toLocaleString()}`);
       }
@@ -102,14 +112,55 @@ export default function CustomPaginationComponent({tableMetaData, rows, totalRec
       }
    };
 
+   ///////////////////////////////////////////////////////////////////////////////
+   // the `count` param that we pass to <TablePagination> below is very         //
+   // important - it drives which of the < and > (prev & next) buttons are      //
+   // enabled - and, it's a little tricky for tables where we don't do a count. //
+   ///////////////////////////////////////////////////////////////////////////////
+   let countForTablePagination: number;
+   if (tableMetaData && !tableMetaData.capabilities.has(Capability.TABLE_COUNT))
+   {
+      ////////////////////////////////////////////
+      // handle tables where count is disabled. //
+      ////////////////////////////////////////////
+      if(!rows || rows.length == 0)
+      {
+         /////////////////////////////////////////////
+         // if we have no rows, assume a count of 0 //
+         /////////////////////////////////////////////
+         countForTablePagination = 0;
+      }
+      if(rows.length < rowsPerPage)
+      {
+         //////////////////////////////////////////////////////////////////////////////////////////////////
+         // if the # of rows we have is less than the rowsPerPage, assume we're at the end of the query  //
+         // so, setting count to pageNo*rowsPer + rows.length - leaves prev. enabled, but disables next. //
+         //////////////////////////////////////////////////////////////////////////////////////////////////
+         countForTablePagination = (pageNumber * rowsPerPage) + rows.length;
+      }
+      else
+      {
+         ///////////////////////////////////////////////////////////////////////////////////////////////////
+         // else, we don't know how many more pages there could be - so, just assume it's at least 1 more //
+         ///////////////////////////////////////////////////////////////////////////////////////////////////
+         countForTablePagination = ((pageNumber + 1) * rowsPerPage) + 1;
+      }
+   }
+   else
+   {
+      ////////////////////////////////////////////////////////////////////////////////
+      // cases where count is enabled - they work much more like we'd expect:       //
+      // if we don't know totalRecords (probably same as loading?) - use a -1,      //
+      // which lets us see < and > both active;  else, use totalRecords when known. //
+      ////////////////////////////////////////////////////////////////////////////////
+      countForTablePagination = totalRecords === null || totalRecords === undefined ? -1 : totalRecords;
+   }
 
    return (
       <TablePagination
          component="div"
-         sx={{minWidth: "450px"}}
-         // note - passing null here makes the 'to' param in the defaultLabelDisplayedRows also be null,
-         // so pass a sentinel value of -1...
-         count={totalRecords === null || totalRecords === undefined ? -1 : totalRecords}
+         sx={{minWidth: "450px", "& .MuiTablePagination-displayedRows": {minWidth: "110px"}}}
+         count={countForTablePagination}
          page={pageNumber}
          rowsPerPageOptions={[10, 25, 50, 100, 250]}
          rowsPerPage={rowsPerPage}

src/qqq/components/query/EvaluatedExpression.tsx

@@ -21,9 +21,9 @@
 
 import {QFieldMetaData} from "@kingsrook/qqq-frontend-core/lib/model/metaData/QFieldMetaData";
 import {QFieldType} from "@kingsrook/qqq-frontend-core/lib/model/metaData/QFieldType";
-import React, {useEffect, useState} from "react";
 import {Expression} from "qqq/components/query/CriteriaDateField";
 import ValueUtils from "qqq/utils/qqq/ValueUtils";
+import React, {useEffect, useState} from "react";
 
 /*******************************************************************************
  ** Helper component to show value inside tooltips that ticks up every second.
@@ -50,13 +50,18 @@ export function EvaluatedExpression({field, expression}: EvaluatedExpressionProp
       return () => clearInterval(interval);
    }, []);
 
-   return <>{`${evaluateExpression(timeForEvaluations, field, expression)}`}</>;
+   return <span style={{fontVariantNumeric: "tabular-nums"}}>{`${evaluateExpression(timeForEvaluations, field, expression)}`}</span>;
 }
 
 const HOUR_MS = 60 * 60 * 1000;
 const DAY_MS = 24 * 60 * 60 * 1000;
 const evaluateExpression = (time: Date, field: QFieldMetaData, expression: Expression): string =>
 {
+   if (expression.type == "FilterVariableExpression")
+   {
+      return (expression.toString());
+   }
+
    let rs: Date = null;
    if (expression.type == "NowWithOffset")
    {

src/qqq/components/query/FieldListMenu.tsx

@@ -19,6 +19,7 @@
  * along with this program.  If not, see <https://www.gnu.org/licenses/>.
  */
 
+import {QExposedJoin} from "@kingsrook/qqq-frontend-core/lib/model/metaData/QExposedJoin";
 import {QFieldMetaData} from "@kingsrook/qqq-frontend-core/lib/model/metaData/QFieldMetaData";
 import {QTableMetaData} from "@kingsrook/qqq-frontend-core/lib/model/metaData/QTableMetaData";
 import Box from "@mui/material/Box";
@@ -31,28 +32,26 @@ import ListItem, {ListItemProps} from "@mui/material/ListItem/ListItem";
 import Menu from "@mui/material/Menu";
 import Switch from "@mui/material/Switch";
 import TextField from "@mui/material/TextField";
-import React, {useState} from "react";
+import React, {useMemo, useState} from "react";
 
 interface FieldListMenuProps
 {
-   idPrefix: string;
-   heading?: string;
-   placeholder?: string;
-   tableMetaData: QTableMetaData;
-   showTableHeaderEvenIfNoExposedJoins: boolean;
-   fieldNamesToHide?: string[];
-   buttonProps: any;
-   buttonChildren: JSX.Element | string;
-
-   isModeSelectOne?: boolean;
-   handleSelectedField?: (field: QFieldMetaData, table: QTableMetaData) => void;
-
-   isModeToggle?: boolean;
-   toggleStates?: {[fieldName: string]: boolean};
-   handleToggleField?: (field: QFieldMetaData, table: QTableMetaData, newValue: boolean) => void;
-
-   fieldEndAdornment?: JSX.Element
-   handleAdornmentClick?: (field: QFieldMetaData, table: QTableMetaData, event: React.MouseEvent<any>) => void;
+   idPrefix: string,
+   heading?: string,
+   placeholder?: string,
+   tableMetaData: QTableMetaData,
+   showTableHeaderEvenIfNoExposedJoins: boolean,
+   fieldNamesToHide?: string[],
+   buttonProps: any,
+   buttonChildren: JSX.Element | string,
+   isModeSelectOne?: boolean,
+   handleSelectedField?: (field: QFieldMetaData, table: QTableMetaData) => void,
+   isModeToggle?: boolean,
+   toggleStates?: { [fieldName: string]: boolean },
+   handleToggleField?: (field: QFieldMetaData, table: QTableMetaData, newValue: boolean) => void,
+   fieldEndAdornment?: JSX.Element,
+   handleAdornmentClick?: (field: QFieldMetaData, table: QTableMetaData, event: React.MouseEvent<any>) => void,
+   omitExposedJoins?: string[]
 }
 
 FieldListMenu.defaultProps = {
@@ -71,38 +70,52 @@ interface TableWithFields
  ** Component to render a list of fields from a table (and its join tables)
  ** which can be interacted with...
  *******************************************************************************/
-export default function FieldListMenu({idPrefix, heading, placeholder, tableMetaData, showTableHeaderEvenIfNoExposedJoins, buttonProps, buttonChildren, isModeSelectOne, fieldNamesToHide, handleSelectedField, isModeToggle, toggleStates, handleToggleField, fieldEndAdornment, handleAdornmentClick}: FieldListMenuProps): JSX.Element
+export default function FieldListMenu({idPrefix, heading, placeholder, tableMetaData, showTableHeaderEvenIfNoExposedJoins, buttonProps, buttonChildren, isModeSelectOne, fieldNamesToHide, handleSelectedField, isModeToggle, toggleStates, handleToggleField, fieldEndAdornment, handleAdornmentClick, omitExposedJoins}: FieldListMenuProps): JSX.Element
 {
    const [menuAnchorElement, setMenuAnchorElement] = useState(null);
    const [searchText, setSearchText] = useState("");
    const [focusedIndex, setFocusedIndex] = useState(null as number);
 
    const [fieldsByTable, setFieldsByTable] = useState([] as TableWithFields[]);
-   const [collapsedTables, setCollapsedTables] = useState({} as {[tableName: string]: boolean});
+   const [collapsedTables, setCollapsedTables] = useState({} as { [tableName: string]: boolean });
 
    const [lastMouseOverXY, setLastMouseOverXY] = useState({x: 0, y: 0});
-   const [timeOfLastArrow, setTimeOfLastArrow] = useState(0)
+   const [timeOfLastArrow, setTimeOfLastArrow] = useState(0);
+
+   const availableExposedJoins = useMemo(() =>
+   {
+      const rs: QExposedJoin[] = []
+      for(let exposedJoin of tableMetaData.exposedJoins ?? [])
+      {
+         if(omitExposedJoins?.indexOf(exposedJoin.joinTable.name) > -1)
+         {
+            continue;
+         }
+         rs.push(exposedJoin);
+      }
+      return (rs);
+   }, [tableMetaData, omitExposedJoins]);
 
    //////////////////
    // check usages //
    //////////////////
-   if(isModeSelectOne)
+   if (isModeSelectOne)
    {
-      if(!handleSelectedField)
+      if (!handleSelectedField)
       {
-         throw("In FieldListMenu, if isModeSelectOne=true, then a callback for handleSelectedField must be provided.");
+         throw ("In FieldListMenu, if isModeSelectOne=true, then a callback for handleSelectedField must be provided.");
       }
    }
 
-   if(isModeToggle)
+   if (isModeToggle)
    {
-      if(!toggleStates)
+      if (!toggleStates)
       {
-         throw("In FieldListMenu, if isModeToggle=true, then a model for toggleStates must be provided.");
+         throw ("In FieldListMenu, if isModeToggle=true, then a model for toggleStates must be provided.");
       }
-      if(!handleToggleField)
+      if (!handleToggleField)
       {
-         throw("In FieldListMenu, if isModeToggle=true, then a callback for handleToggleField must be provided.");
+         throw ("In FieldListMenu, if isModeToggle=true, then a callback for handleToggleField must be provided.");
       }
    }
 
@@ -113,16 +126,16 @@ export default function FieldListMenu({idPrefix, heading, placeholder, tableMeta
    {
       collapsedTables[tableMetaData.name] = false;
 
-      if (tableMetaData.exposedJoins?.length > 0)
+      if (availableExposedJoins?.length > 0)
       {
          /////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
          // if we have exposed joins, put the table meta data with its fields, and then all of the join tables & fields too //
          /////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
          fieldsByTable.push({table: tableMetaData, fields: getTableFieldsAsAlphabeticalArray(tableMetaData)});
 
-         for (let i = 0; i < tableMetaData.exposedJoins?.length; i++)
+         for (let i = 0; i < availableExposedJoins?.length; i++)
          {
-            const joinTable = tableMetaData.exposedJoins[i].joinTable;
+            const joinTable = availableExposedJoins[i].joinTable;
             fieldsByTable.push({table: joinTable, fields: getTableFieldsAsAlphabeticalArray(joinTable)});
 
             collapsedTables[joinTable.name] = false;
@@ -150,16 +163,16 @@ export default function FieldListMenu({idPrefix, heading, placeholder, tableMeta
       table.fields.forEach(field =>
       {
          let fullFieldName = field.name;
-         if(table.name != tableMetaData.name)
+         if (table.name != tableMetaData.name)
          {
             fullFieldName = `${table.name}.${field.name}`;
          }
 
-         if(fieldNamesToHide && fieldNamesToHide.indexOf(fullFieldName) > -1)
+         if (fieldNamesToHide && fieldNamesToHide.indexOf(fullFieldName) > -1)
          {
             return;
          }
-         fields.push(field)
+         fields.push(field);
       });
       fields.sort((a, b) => a.label.localeCompare(b.label));
       return (fields);
@@ -181,7 +194,7 @@ export default function FieldListMenu({idPrefix, heading, placeholder, tableMeta
    /*******************************************************************************
     **
     *******************************************************************************/
-   function getShownFieldAndTableByIndex(targetIndex: number): {field: QFieldMetaData, table: QTableMetaData}
+   function getShownFieldAndTableByIndex(targetIndex: number): { field: QFieldMetaData, table: QTableMetaData }
    {
       let index = -1;
       for (let i = 0; i < fieldsByTableToShow.length; i++)
@@ -191,9 +204,9 @@ export default function FieldListMenu({idPrefix, heading, placeholder, tableMeta
          {
             index++;
 
-            if(index == targetIndex)
+            if (index == targetIndex)
             {
-               return {field: tableWithField.fields[j], table: tableWithField.table}
+               return {field: tableWithField.fields[j], table: tableWithField.table};
             }
          }
       }
@@ -210,7 +223,7 @@ export default function FieldListMenu({idPrefix, heading, placeholder, tableMeta
       // console.log(`Event key: ${event.key}`);
       setTimeout(() => document.getElementById(`field-list-dropdown-${idPrefix}-textField`).focus());
 
-      if(isModeSelectOne && event.key == "Enter" && focusedIndex != null)
+      if (isModeSelectOne && event.key == "Enter" && focusedIndex != null)
       {
          setTimeout(() =>
          {
@@ -249,13 +262,13 @@ export default function FieldListMenu({idPrefix, heading, placeholder, tableMeta
                /////////////////
                // a down move //
                /////////////////
-               if(startIndex == null)
+               if (startIndex == null)
                {
                   startIndex = -1;
                }
 
                let goalIndex = startIndex + offset;
-               if(goalIndex > maxFieldIndex - 1)
+               if (goalIndex > maxFieldIndex - 1)
                {
                   goalIndex = maxFieldIndex - 1;
                }
@@ -268,7 +281,7 @@ export default function FieldListMenu({idPrefix, heading, placeholder, tableMeta
                // an up move //
                ////////////////
                let goalIndex = startIndex + offset;
-               if(goalIndex < 0)
+               if (goalIndex < 0)
                {
                   goalIndex = 0;
                }
@@ -335,7 +348,7 @@ export default function FieldListMenu({idPrefix, heading, placeholder, tableMeta
       // the last x/y isn't really useful, because the mouse generally isn't left exactly where it was when the mouse-over happened (edge of the element) //
       // but the keyboard last-arrow time that we capture, that's what's actually being useful in here                                                    //
       //////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
-      if(event.clientX == lastMouseOverXY.x && event.clientY == lastMouseOverXY.y)
+      if (event.clientX == lastMouseOverXY.x && event.clientY == lastMouseOverXY.y)
       {
          // console.log("mouse didn't move, so, doesn't count");
          return;
@@ -343,7 +356,7 @@ export default function FieldListMenu({idPrefix, heading, placeholder, tableMeta
 
       const now = new Date().getTime();
       // console.log(`Compare now [${now}] to last arrow [${timeOfLastArrow}] (diff: [${now - timeOfLastArrow}])`);
-      if(now < timeOfLastArrow + 300)
+      if (now < timeOfLastArrow + 300)
       {
          // console.log("An arrow event happened less than 300 mills ago, so doesn't count.");
          return;
@@ -480,7 +493,7 @@ export default function FieldListMenu({idPrefix, heading, placeholder, tableMeta
       for (let i = 0; i < fieldsList.length; i++)
       {
          const field = fieldsList[i];
-         if(doesFieldMatchSearchText(field))
+         if (doesFieldMatchSearchText(field))
          {
             handleToggleField(field, table, event.target.checked);
          }
@@ -491,18 +504,18 @@ export default function FieldListMenu({idPrefix, heading, placeholder, tableMeta
    /////////////////////////////////////////////////////////
    // compute the table-level toggle state & count values //
    /////////////////////////////////////////////////////////
-   const tableToggleStates: {[tableName: string]: boolean} = {};
-   const tableToggleCounts: {[tableName: string]: number} = {};
+   const tableToggleStates: { [tableName: string]: boolean } = {};
+   const tableToggleCounts: { [tableName: string]: number } = {};
 
-   if(isModeToggle)
+   if (isModeToggle)
    {
       const {allOn, count} = getTableToggleState(tableMetaData, true);
       tableToggleStates[tableMetaData.name] = allOn;
       tableToggleCounts[tableMetaData.name] = count;
 
-      for (let i = 0; i < tableMetaData.exposedJoins?.length; i++)
+      for (let i = 0; i < availableExposedJoins?.length; i++)
       {
-         const join = tableMetaData.exposedJoins[i];
+         const join = availableExposedJoins[i];
          const {allOn, count} = getTableToggleState(join.joinTable, false);
          tableToggleStates[join.joinTable.name] = allOn;
          tableToggleCounts[join.joinTable.name] = count;
@@ -513,7 +526,7 @@ export default function FieldListMenu({idPrefix, heading, placeholder, tableMeta
    /*******************************************************************************
     **
     *******************************************************************************/
-   function getTableToggleState(table: QTableMetaData, isMainTable: boolean): {allOn: boolean, count: number}
+   function getTableToggleState(table: QTableMetaData, isMainTable: boolean): { allOn: boolean, count: number }
    {
       const fieldsList = [...table.fields.values()];
       let allOn = true;
@@ -522,7 +535,7 @@ export default function FieldListMenu({idPrefix, heading, placeholder, tableMeta
       {
          const field = fieldsList[i];
          const name = isMainTable ? field.name : `${table.name}.${field.name}`;
-         if(!toggleStates[name])
+         if (!toggleStates[name])
          {
             allOn = false;
          }
@@ -541,7 +554,7 @@ export default function FieldListMenu({idPrefix, heading, placeholder, tableMeta
     *******************************************************************************/
    function toggleCollapsedTable(tableName: string)
    {
-      collapsedTables[tableName] = !collapsedTables[tableName]
+      collapsedTables[tableName] = !collapsedTables[tableName];
       setCollapsedTables(Object.assign({}, collapsedTables));
    }
 
@@ -559,7 +572,7 @@ export default function FieldListMenu({idPrefix, heading, placeholder, tableMeta
 
    let index = -1;
    const textFieldId = `field-list-dropdown-${idPrefix}-textField`;
-   let listItemPadding = isModeToggle ? "0.125rem": "0.5rem";
+   let listItemPadding = isModeToggle ? "0.125rem" : "0.5rem";
 
    ///////////////////////////////////////////////////////////////////////////////////////////////////////////////
    // for z-indexes, we set each table header to i+1, then the fields in that table to i (so they go behind it) //
@@ -607,12 +620,12 @@ export default function FieldListMenu({idPrefix, heading, placeholder, tableMeta
                         {
                            let headerContents = null;
                            const headerTable = tableWithFields.table || tableMetaData;
-                           if(tableWithFields.table || showTableHeaderEvenIfNoExposedJoins)
+                           if (tableWithFields.table || showTableHeaderEvenIfNoExposedJoins)
                            {
                               headerContents = (<b>{headerTable.label} Fields</b>);
                            }
 
-                           if(isModeToggle)
+                           if (isModeToggle)
                            {
                               headerContents = (<FormControlLabel
                                  sx={{display: "flex", alignItems: "flex-start", "& .MuiFormControlLabel-label": {lineHeight: "1.4", fontWeight: "500 !important"}}}
@@ -622,10 +635,10 @@ export default function FieldListMenu({idPrefix, heading, placeholder, tableMeta
                                     checked={tableToggleStates[headerTable.name]}
                                     onChange={(event) => handleTableToggle(event, headerTable)}
                                  />}
-                                 label={<span style={{marginTop: "0.25rem", display: "inline-block"}}><b>{headerTable.label} Fields</b>&nbsp;<span style={{fontWeight: 400}}>({tableToggleCounts[headerTable.name]})</span></span>} />)
+                                 label={<span style={{marginTop: "0.25rem", display: "inline-block"}}><b>{headerTable.label} Fields</b>&nbsp;<span style={{fontWeight: 400}}>({tableToggleCounts[headerTable.name]})</span></span>} />);
                            }
 
-                           if(isModeToggle)
+                           if (isModeToggle)
                            {
                               headerContents = (
                                  <>
@@ -638,11 +651,11 @@ export default function FieldListMenu({idPrefix, heading, placeholder, tableMeta
                                     </IconButton>
                                     {headerContents}
                                  </>
-                              )
+                              );
                            }
 
                            let marginLeft = "unset";
-                           if(isModeToggle)
+                           if (isModeToggle)
                            {
                               marginLeft = "-1rem";
                            }
@@ -652,14 +665,14 @@ export default function FieldListMenu({idPrefix, heading, placeholder, tableMeta
                            return (
                               <React.Fragment key={tableWithFields.table?.name ?? "theTable"}>
                                  <>
-                                    {headerContents && <ListItem sx={{position: "sticky", top: -1, zIndex: zIndex+1, padding: listItemPadding, ml: marginLeft, display: "flex", alignItems: "flex-start", backgroundImage: "linear-gradient(to bottom, rgba(255,255,255,1), rgba(255,255,255,1) 90%, rgba(255,255,255,0))"}}>{headerContents}</ListItem>}
+                                    {headerContents && <ListItem sx={{position: "sticky", top: -1, zIndex: zIndex + 1, padding: listItemPadding, ml: marginLeft, display: "flex", alignItems: "flex-start", backgroundImage: "linear-gradient(to bottom, rgba(255,255,255,1), rgba(255,255,255,1) 90%, rgba(255,255,255,0))"}}>{headerContents}</ListItem>}
                                     {
                                        tableWithFields.fields.map((field) =>
                                        {
                                           index++;
-                                          const key = `${tableWithFields.table?.name}-${field.name}`
+                                          const key = `${tableWithFields.table?.name}-${field.name}`;
 
-                                          if(collapsedTables[headerTable.name])
+                                          if (collapsedTables[headerTable.name])
                                           {
                                              return (<React.Fragment key={key} />);
                                           }
@@ -677,13 +690,13 @@ export default function FieldListMenu({idPrefix, heading, placeholder, tableMeta
                                              {
                                                 closeMenu();
                                                 handleSelectedField(field, tableWithFields.table ?? tableMetaData);
-                                             }
+                                             };
                                           }
 
                                           let label: JSX.Element | string = field.label;
                                           const fullFieldName = tableWithFields.table && tableWithFields.table.name != tableMetaData.name ? `${tableWithFields.table.name}.${field.name}` : field.name;
 
-                                          if(fieldEndAdornment)
+                                          if (fieldEndAdornment)
                                           {
                                              label = <Box width="100%" display="inline-flex" justifyContent="space-between">
                                                 {label}

src/qqq/components/query/FilterCriteriaPaster.tsx

@@ -19,6 +19,10 @@
  * along with this program.  If not, see <https://www.gnu.org/licenses/>.
  */
 
+import {QFieldMetaData} from "@kingsrook/qqq-frontend-core/lib/model/metaData/QFieldMetaData";
+import {QInstance} from "@kingsrook/qqq-frontend-core/lib/model/metaData/QInstance";
+import {QTableMetaData} from "@kingsrook/qqq-frontend-core/lib/model/metaData/QTableMetaData";
+import {QPossibleValue} from "@kingsrook/qqq-frontend-core/lib/model/QPossibleValue";
 import {FormControl, InputLabel, Select, SelectChangeEvent} from "@mui/material";
 import Box from "@mui/material/Box";
 import Card from "@mui/material/Card";
@@ -28,20 +32,26 @@ import Modal from "@mui/material/Modal";
 import TextField from "@mui/material/TextField";
 import Tooltip from "@mui/material/Tooltip";
 import Typography from "@mui/material/Typography";
-import {GridFilterItem} from "@mui/x-data-grid-pro";
-import React, {useEffect, useState} from "react";
 import {QCancelButton, QSaveButton} from "qqq/components/buttons/DefaultButtons";
+
 import ChipTextField from "qqq/components/forms/ChipTextField";
+import HelpContent from "qqq/components/misc/HelpContent";
+import {LoadingState} from "qqq/models/LoadingState";
+import Client from "qqq/utils/qqq/Client";
+import React, {useEffect, useReducer, useState} from "react";
 
 interface Props
 {
    type: string;
    onSave: (newValues: any[]) => void;
+   table?: QTableMetaData;
+   field?: QFieldMetaData;
 }
 
 FilterCriteriaPaster.defaultProps = {};
+const qController = Client.getInstance();
 
-function FilterCriteriaPaster({type, onSave}: Props): JSX.Element
+function FilterCriteriaPaster({table, field, type, onSave}: Props): JSX.Element
 {
    enum Delimiter
    {
@@ -68,6 +78,12 @@ function FilterCriteriaPaster({type, onSave}: Props): JSX.Element
    mainCardStyles.width = "60%";
    mainCardStyles.minWidth = "500px";
 
+   ///////////////////////////////////////////////////////////////////////////////////////////
+   // add a LoadingState object, in case the initial loads (of meta data and view) are slow //
+   ///////////////////////////////////////////////////////////////////////////////////////////
+   const [, forceUpdate] = useReducer((x) => x + 1, 0);
+   const [pageLoadingState, _] = useState(new LoadingState(forceUpdate));
+
    //x const [gridFilterItem, setGridFilterItem] = useState(props.item);
    const [pasteModalIsOpen, setPasteModalIsOpen] = useState(false);
    const [inputText, setInputText] = useState("");
@@ -75,8 +91,13 @@ function FilterCriteriaPaster({type, onSave}: Props): JSX.Element
    const [delimiterCharacter, setDelimiterCharacter] = useState("");
    const [customDelimiterValue, setCustomDelimiterValue] = useState("");
    const [chipData, setChipData] = useState(undefined);
+   const [uniqueCount, setUniqueCount] = useState(undefined);
+   const [chipValidity, setChipValidity] = useState([] as boolean[]);
+   const [chipPVSIds, setChipPVSIds] = useState([] as any[]);
    const [detectedText, setDetectedText] = useState("");
    const [errorText, setErrorText] = useState("");
+   const [saveDisabled, setSaveDisabled] = useState(true);
+   const [metaData, setMetaData] = useState(null as QInstance);
 
    //////////////////////////////////////////////////////////////
    // handler for when paste icon is clicked in 'any' operator //
@@ -92,6 +113,7 @@ function FilterCriteriaPaster({type, onSave}: Props): JSX.Element
       setDelimiter("");
       setDelimiterCharacter("");
       setChipData([]);
+      setChipValidity([]);
       setInputText("");
       setDetectedText("");
       setCustomDelimiterValue("");
@@ -106,18 +128,43 @@ function FilterCriteriaPaster({type, onSave}: Props): JSX.Element
 
    const handleSaveClicked = () =>
    {
-      ////////////////////////////////////////
-      // if numeric remove any non-numerics //
-      ////////////////////////////////////////
+      ///////////////////////////////////////////////////////////////
+      // if numeric remove any non-numerics, or invalid pvs values //
+      ///////////////////////////////////////////////////////////////
       let saveData = [];
+      let usedLabels = new Map<any, boolean>();
       for (let i = 0; i < chipData.length; i++)
       {
-         if (type !== "number" || !Number.isNaN(Number(chipData[i])))
+         if (chipValidity[i] === true)
          {
-            saveData.push(chipData[i]);
+            if (type === "pvs")
+            {
+               /////////////////////////////////////////////
+               // if already used this PVS label, skip it //
+               /////////////////////////////////////////////
+               if (usedLabels.get(chipData[i]) != null)
+               {
+                  continue;
+               }
+
+               saveData.push(new QPossibleValue({id: chipPVSIds[i], label: chipData[i]}));
+               usedLabels.set(chipData[i], true);
+            }
+            else
+            {
+               saveData.push(chipData[i]);
+            }
          }
       }
 
+      //////////////////////////////////////////
+      // for pvs, sort by label before saving //
+      //////////////////////////////////////////
+      if (type === "pvs")
+      {
+         saveData.sort((a: QPossibleValue, b: QPossibleValue) => b.label.localeCompare(a.label));
+      }
+
       onSave(saveData);
 
       clearData();
@@ -214,6 +261,12 @@ function FilterCriteriaPaster({type, onSave}: Props): JSX.Element
 
    useEffect(() =>
    {
+      (async () =>
+      {
+         const metaData = await qController.loadMetaData();
+         setMetaData(metaData);
+      })();
+
       let currentDelimiter = delimiter;
       let currentDelimiterCharacter = delimiterCharacter;
 
@@ -246,10 +299,16 @@ function FilterCriteriaPaster({type, onSave}: Props): JSX.Element
       let parts = inputText.split(regex);
       let chipData = [] as string[];
 
+      /////////////////////////////////////////////////////////////////
+      // use a map to keep track of the counts for each unique value //
+      /////////////////////////////////////////////////////////////////
+      const uniqueValuesMap: { [key: string]: number } = {};
+
       ///////////////////////////////////////////////////////
       // if delimiter is empty string, dont split anything //
       ///////////////////////////////////////////////////////
       setErrorText("");
+      let invalidCount = 0;
       if (currentDelimiterCharacter !== "")
       {
          for (let i = 0; i < parts.length; i++)
@@ -259,152 +318,207 @@ function FilterCriteriaPaster({type, onSave}: Props): JSX.Element
             {
                chipData.push(part);
 
-               ///////////////////////////////////////////////////////////
-               // if numeric, check that first before pushing as a chip //
-               ///////////////////////////////////////////////////////////
-               if (type === "number" && Number.isNaN(Number(part)))
+               ////////////////////////////////////////////////////////////////
+               // if numeric or pvs, check validity and add to invalid count //
+               ////////////////////////////////////////////////////////////////
+               if (chipValidity[i] != null && chipValidity[i] !== true)
                {
-                  setErrorText("Some values are not numbers");
+                  if ((type === "number" && Number.isNaN(Number(part))) || type === "pvs")
+                  {
+                     invalidCount++;
+                  }
+               }
+               else
+               {
+                  let count = uniqueValuesMap[part] == null ? 0 : uniqueValuesMap[part];
+                  uniqueValuesMap[part] = count + 1;
                }
             }
          }
       }
 
+      if (invalidCount > 0)
+      {
+         if (type === "number")
+         {
+            let suffix = invalidCount === 1 ? " value is not a number" : " values are not numbers";
+            setErrorText(invalidCount + suffix + " and will not be added to the filter");
+         }
+         else if (type === "pvs")
+         {
+            let suffix = invalidCount === 1 ? " value was" : " values were";
+            setErrorText(invalidCount + suffix + " not found and will not be added to the filter");
+         }
+      }
+
+      setUniqueCount(Object.keys(uniqueValuesMap).length);
       setChipData(chipData);
 
-   }, [inputText, delimiterCharacter, customDelimiterValue, detectedText]);
+   }, [inputText, delimiterCharacter, customDelimiterValue, detectedText, chipValidity]);
+
+   const slotName = type === "pvs" ? "bulkAddFilterValuesPossibleValueSource" : "bulkAddFilterValues";
+   const helpRoles = ["QUERY_SCREEN"];
+   const formattedHelpContent = <HelpContent helpContents={metaData?.helpContent?.get(slotName)} roles={helpRoles} heading={null} helpContentKey={`instanceLevel:true;slot:${slotName}`} />;
 
    return (
       <Box>
          <Tooltip title="Quickly add many values to your filter by pasting them from a spreadsheet or any other data source.">
-            <Icon onClick={handlePasteClick} fontSize="small" color="info" sx={{mx: 0.25, cursor: "pointer"}}>paste_content</Icon>
+            <Icon className="criteriaPasterButton" onClick={handlePasteClick} fontSize="small" color="info" sx={{mx: 0.25, cursor: "pointer"}}>paste_content</Icon>
          </Tooltip>
          {
             pasteModalIsOpen &&
             (
                <Modal open={pasteModalIsOpen}>
-                  <Box sx={{position: "absolute", overflowY: "auto", width: "100%"}}>
-                     <Box py={3} justifyContent="center" sx={{display: "flex", mt: 8}}>
-                        <Card sx={mainCardStyles}>
-                           <Box p={4} pb={2}>
-                              <Grid container>
-                                 <Grid item pr={3} xs={12} lg={12}>
-                                    <Typography variant="h5">Bulk Add Filter Values</Typography>
-                                    <Typography sx={{display: "flex", lineHeight: "1.7", textTransform: "revert"}} variant="button">
-                                       Paste into the box on the left.
-                                       Review the filter values in the box on the right.
-                                       If the filter values are not what are expected, try changing the separator using the dropdown below.
-                                    </Typography>
+                  <Box>
+                     <Box sx={{position: "absolute", overflowY: "auto", width: "100%"}}>
+                        <Box py={3} justifyContent="center" sx={{display: "flex", mt: 8}}>
+                           <Card sx={mainCardStyles}>
+                              <Box p={4} pb={2}>
+                                 <Grid container>
+                                    <Grid item pr={3} xs={12} lg={12}>
+                                       <Typography variant="h5">Bulk Add Filter Values</Typography>
+                                       {
+                                          formattedHelpContent && <Box sx={{display: "flex", lineHeight: "1.7", textTransform: "none"}}>
+                                             <Typography sx={{display: "flex", lineHeight: "1.7", textTransform: "revert"}} variant="button">
+                                                {formattedHelpContent}
+                                             </Typography>
+                                          </Box>
+                                       }
+                                    </Grid>
+                                 </Grid>
+                              </Box>
+                              <Grid container pl={3} pr={3} justifyContent="center" alignItems="stretch" sx={{display: "flex", height: "100%"}}>
+                                 <Grid item pr={3} xs={6} lg={6} sx={{width: "100%", display: "flex", flexDirection: "column", flexGrow: 1}}>
+                                    <FormControl sx={{m: 1, width: "100%"}}>
+                                       <TextField
+                                          className="criteriaPasterTextArea"
+                                          id="outlined-multiline-static"
+                                          label="PASTE TEXT"
+                                          multiline
+                                          onChange={handleTextChange}
+                                          rows={16}
+                                          value={inputText}
+                                       />
+                                    </FormControl>
+                                 </Grid>
+                                 <Grid item xs={6} lg={6} sx={{display: "flex", flexGrow: 1}}>
+                                    <FormControl sx={{m: 1, width: "100%"}}>
+                                       <ChipTextField
+                                          handleChipChange={(isMakingRequest: boolean, chipValidity: boolean[], chipPVSIds: any[]) =>
+                                          {
+                                             setErrorText("");
+                                             if (isMakingRequest)
+                                             {
+                                                pageLoadingState.setLoading();
+                                             }
+                                             else
+                                             {
+                                                pageLoadingState.setNotLoading();
+                                             }
+                                             setSaveDisabled(isMakingRequest);
+                                             setChipPVSIds(chipPVSIds);
+                                             setChipValidity(chipValidity);
+                                          }}
+                                          table={table}
+                                          field={field}
+                                          chipData={chipData}
+                                          chipValidity={chipValidity}
+                                          chipType={type}
+                                          multiline
+                                          fullWidth
+                                          variant="outlined"
+                                          id="tags"
+                                          rows={0}
+                                          name="tags"
+                                          label="FILTER VALUES REVIEW"
+                                       />
+                                    </FormControl>
                                  </Grid>
                               </Grid>
-                           </Box>
-                           <Grid container pl={3} pr={3} justifyContent="center" alignItems="stretch" sx={{display: "flex", height: "100%"}}>
-                              <Grid item pr={3} xs={6} lg={6} sx={{width: "100%", display: "flex", flexDirection: "column", flexGrow: 1}}>
-                                 <FormControl sx={{m: 1, width: "100%"}}>
-                                    <TextField
-                                       id="outlined-multiline-static"
-                                       label="PASTE TEXT"
-                                       multiline
-                                       onChange={handleTextChange}
-                                       rows={16}
-                                       value={inputText}
-                                    />
-                                 </FormControl>
-                              </Grid>
-                              <Grid item xs={6} lg={6} sx={{display: "flex", flexGrow: 1}}>
-                                 <FormControl sx={{m: 1, width: "100%"}}>
-                                    <ChipTextField
-                                       handleChipChange={() =>
-                                       {
-                                       }}
-                                       chipData={chipData}
-                                       chipType={type}
-                                       multiline
-                                       fullWidth
-                                       variant="outlined"
-                                       id="tags"
-                                       rows={0}
-                                       name="tags"
-                                       label="FILTER VALUES REVIEW"
-                                    />
-                                 </FormControl>
-                              </Grid>
-                           </Grid>
-                           <Grid container pl={3} pr={3} justifyContent="center" alignItems="stretch" sx={{display: "flex", height: "100%"}}>
-                              <Grid item pl={1} pr={3} xs={6} lg={6} sx={{width: "100%", display: "flex", flexDirection: "column", flexGrow: 1}}>
-                                 <Box sx={{display: "inline-flex", alignItems: "baseline"}}>
-                                    <FormControl sx={{mt: 2, width: "50%"}}>
-                                       <InputLabel htmlFor="select-native">
-                                          SEPARATOR
-                                       </InputLabel>
-                                       <Select
-                                          multiline
-                                          native
-                                          value={delimiter}
-                                          onChange={handleDelimiterChange}
-                                          label="SEPARATOR"
-                                          size="medium"
-                                          inputProps={{
-                                             id: "select-native",
-                                          }}
-                                       >
-                                          {delimiterDropdownOptions.map((delimiter) => (
-                                             <option key={delimiter} value={delimiter}>
-                                                {delimiter}
-                                             </option>
-                                          ))}
-                                       </Select>
-                                    </FormControl>
-                                    {delimiter === Delimiter.CUSTOM.valueOf() && (
-
-                                       <FormControl sx={{pl: 2, top: 5, width: "50%"}}>
-                                          <TextField
-                                             name="custom-delimiter-value"
-                                             placeholder="Custom Separator"
-                                             label="Custom Separator"
-                                             variant="standard"
-                                             value={customDelimiterValue}
-                                             onChange={handleCustomDelimiterChange}
-                                             inputProps={{maxLength: 1}}
-                                          />
+                              <Grid container pl={3} pr={3} justifyContent="center" alignItems="stretch" sx={{display: "flex", height: "100%"}}>
+                                 <Grid item pl={1} pr={3} xs={6} lg={6} sx={{width: "100%", display: "flex", flexDirection: "column", flexGrow: 1}}>
+                                    <Box sx={{display: "inline-flex", alignItems: "baseline"}}>
+                                       <FormControl sx={{mt: 2, width: "50%"}}>
+                                          <InputLabel htmlFor="select-native">
+                                             SEPARATOR
+                                          </InputLabel>
+                                          <Select
+                                             multiline
+                                             native
+                                             value={delimiter}
+                                             onChange={handleDelimiterChange}
+                                             label="SEPARATOR"
+                                             size="medium"
+                                             inputProps={{
+                                                id: "select-native",
+                                             }}
+                                          >
+                                             {delimiterDropdownOptions.map((delimiter) => (
+                                                <option key={delimiter} value={delimiter}>
+                                                   {delimiter}
+                                                </option>
+                                             ))}
+                                          </Select>
                                        </FormControl>
-                                    )}
-                                    {inputText && delimiter === Delimiter.DETECT_AUTOMATICALLY.valueOf() && (
+                                       {delimiter === Delimiter.CUSTOM.valueOf() && (
 
-                                       <Typography pl={2} variant="button" sx={{top: "1px", textTransform: "revert"}}>
-                                          <i>{detectedText}</i>
-                                       </Typography>
-                                    )}
-                                 </Box>
+                                          <FormControl sx={{pl: 2, top: 5, width: "50%"}}>
+                                             <TextField
+                                                name="custom-delimiter-value"
+                                                placeholder="Custom Separator"
+                                                label="Custom Separator"
+                                                variant="standard"
+                                                value={customDelimiterValue}
+                                                onChange={handleCustomDelimiterChange}
+                                                inputProps={{maxLength: 1}}
+                                             />
+                                          </FormControl>
+                                       )}
+                                       {inputText && delimiter === Delimiter.DETECT_AUTOMATICALLY.valueOf() && (
+
+                                          <Typography pl={2} variant="button" sx={{top: "1px", textTransform: "revert"}}>
+                                             <i>{detectedText}</i>
+                                          </Typography>
+                                       )}
+                                    </Box>
+                                 </Grid>
+                                 <Grid sx={{display: "flex", justifyContent: "flex-start", alignItems: "flex-start"}} item pl={1} xs={4} lg={4}>
+                                    {
+                                       errorText && chipData.length > 0 && (
+                                          <Box sx={{display: "flex", justifyContent: "flex-start", alignItems: "flex-start"}}>
+                                             <Icon color="error">error</Icon>
+                                             <Typography sx={{paddingLeft: "4px", textTransform: "revert"}} variant="button">{errorText}</Typography>
+                                          </Box>
+                                       )
+                                    }
+                                    {
+                                       pageLoadingState.isLoadingSlow() && (
+                                          <Box sx={{display: "flex", justifyContent: "flex-start", alignItems: "flex-start"}}>
+                                             <Icon color="warning">warning</Icon>
+                                             <Typography sx={{paddingLeft: "4px", textTransform: "revert"}} variant="button">Loading...</Typography>
+                                          </Box>
+                                       )
+                                    }
+                                 </Grid>
+                                 <Grid sx={{display: "flex", justifyContent: "flex-end", alignItems: "flex-start"}} item pr={1} xs={2} lg={2}>
+                                    {
+                                       chipData && chipData.length > 0 && (
+                                          <Typography sx={{textTransform: "revert"}} variant="button">{chipData.length.toLocaleString()} {chipData.length === 1 ? "value" : "values"} {uniqueCount && `(${uniqueCount} unique)`}</Typography>
+                                       )
+                                    }
+                                 </Grid>
                               </Grid>
-                              <Grid sx={{display: "flex", justifyContent: "flex-start", alignItems: "flex-start"}} item pl={1} xs={3} lg={3}>
-                                 {
-                                    errorText && chipData.length > 0 && (
-                                       <Box sx={{display: "flex", justifyContent: "flex-start", alignItems: "flex-start"}}>
-                                          <Icon color="error">error</Icon>
-                                          <Typography sx={{paddingLeft: "4px", textTransform: "revert"}} variant="button">{errorText}</Typography>
-                                       </Box>
-                                    )
-                                 }
-                              </Grid>
-                              <Grid sx={{display: "flex", justifyContent: "flex-end", alignItems: "flex-start"}} item pr={1} xs={3} lg={3}>
-                                 {
-                                    chipData && chipData.length > 0 && (
-                                       <Typography sx={{textTransform: "revert"}} variant="button">{chipData.length.toLocaleString()} {chipData.length === 1 ? "value" : "values"}</Typography>
-                                    )
-                                 }
-                              </Grid>
-                           </Grid>
-                           <Box p={3} pt={0}>
-                              <Grid container pl={1} pr={1} justifyContent="right" alignItems="stretch" sx={{display: "flex-inline "}}>
-                                 <QCancelButton
-                                    onClickHandler={handleCancelClicked}
-                                    iconName="cancel"
-                                    disabled={false} />
-                                 <QSaveButton onClickHandler={handleSaveClicked} label="Add Filters" disabled={false} />
-                              </Grid>
-                           </Box>
-                        </Card>
+                              <Box p={3} pt={0}>
+                                 <Grid container pl={1} pr={1} justifyContent="right" alignItems="stretch" sx={{display: "flex-inline "}}>
+                                    <QCancelButton
+                                       onClickHandler={handleCancelClicked}
+                                       iconName="cancel"
+                                       disabled={false} />
+                                    <QSaveButton onClickHandler={handleSaveClicked} label="Add Values" disabled={saveDisabled} />
+                                 </Grid>
+                              </Box>
+                           </Card>
+                        </Box>
                      </Box>
                   </Box>
                </Modal>

src/qqq/components/query/FilterCriteriaRow.tsx

@@ -33,8 +33,10 @@ import MenuItem from "@mui/material/MenuItem";
 import Select, {SelectChangeEvent} from "@mui/material/Select/Select";
 import TextField from "@mui/material/TextField";
 import Tooltip from "@mui/material/Tooltip";
+import {omit} from "lodash";
 import FieldAutoComplete from "qqq/components/misc/FieldAutoComplete";
 import FilterCriteriaRowValues from "qqq/components/query/FilterCriteriaRowValues";
+import {QueryScreenUsage} from "qqq/pages/records/query/RecordQuery";
 import FilterUtils from "qqq/utils/qqq/FilterUtils";
 import React, {ReactNode, SyntheticEvent, useState} from "react";
 
@@ -72,7 +74,7 @@ export const getValueModeRequiredCount = (valueMode: ValueMode): number =>
       case ValueMode.PVS_MULTI:
          return (null);
    }
-}
+};
 
 export interface OperatorOption
 {
@@ -108,6 +110,7 @@ export const getOperatorOptions = (tableMetaData: QTableMetaData, fieldName: str
          {
             case QFieldType.DECIMAL:
             case QFieldType.INTEGER:
+            case QFieldType.LONG:
                operatorOptions.push({label: "equals", value: QCriteriaOperator.EQUALS, valueMode: ValueMode.SINGLE});
                operatorOptions.push({label: "does not equal", value: QCriteriaOperator.NOT_EQUALS_OR_IS_NULL, valueMode: ValueMode.SINGLE});
                operatorOptions.push({label: "greater than", value: QCriteriaOperator.GREATER_THAN, valueMode: ValueMode.SINGLE});
@@ -183,27 +186,29 @@ export const getOperatorOptions = (tableMetaData: QTableMetaData, fieldName: str
    }
 
    return (operatorOptions);
-}
+};
 
 
 interface FilterCriteriaRowProps
 {
-   id: number;
-   index: number;
-   tableMetaData: QTableMetaData;
-   metaData: QInstance;
-   criteria: QFilterCriteria;
-   booleanOperator: "AND" | "OR" | null;
-   updateCriteria: (newCriteria: QFilterCriteria, needDebounce: boolean) => void;
-   removeCriteria: () => void;
-   updateBooleanOperator: (newValue: string) => void;
+   id: number,
+   index: number,
+   tableMetaData: QTableMetaData,
+   metaData: QInstance,
+   criteria: QFilterCriteria,
+   booleanOperator: "AND" | "OR" | null,
+   updateCriteria: (newCriteria: QFilterCriteria, needDebounce: boolean) => void,
+   removeCriteria: () => void,
+   updateBooleanOperator: (newValue: string) => void,
+   queryScreenUsage?: QueryScreenUsage,
+   allowVariables?: boolean,
+   omitExposedJoins?: string[]
 }
 
 FilterCriteriaRow.defaultProps =
-   {
-   };
+   {};
 
-export function validateCriteria(criteria: QFilterCriteria, operatorSelectedValue?: OperatorOption): {criteriaIsValid: boolean, criteriaStatusTooltip: string}
+export function validateCriteria(criteria: QFilterCriteria, operatorSelectedValue?: OperatorOption): { criteriaIsValid: boolean, criteriaStatusTooltip: string }
 {
    let criteriaIsValid = true;
    let criteriaStatusTooltip = "This condition is fully defined and is part of your filter.";
@@ -213,7 +218,7 @@ export function validateCriteria(criteria: QFilterCriteria, operatorSelectedValu
       return (value === null || value == undefined || String(value).trim() === "");
    }
 
-   if(!criteria)
+   if (!criteria)
    {
       criteriaIsValid = false;
       criteriaStatusTooltip = "This condition is not defined.";
@@ -266,7 +271,7 @@ export function validateCriteria(criteria: QFilterCriteria, operatorSelectedValu
    return {criteriaIsValid, criteriaStatusTooltip};
 }
 
-export function FilterCriteriaRow({id, index, tableMetaData, metaData, criteria, booleanOperator, updateCriteria, removeCriteria, updateBooleanOperator}: FilterCriteriaRowProps): JSX.Element
+export function FilterCriteriaRow({id, index, tableMetaData, metaData, criteria, booleanOperator, updateCriteria, removeCriteria, updateBooleanOperator, queryScreenUsage, allowVariables, omitExposedJoins}: FilterCriteriaRowProps): JSX.Element
 {
    // console.log(`FilterCriteriaRow: criteria: ${JSON.stringify(criteria)}`);
    const [operatorSelectedValue, setOperatorSelectedValue] = useState(null as OperatorOption);
@@ -284,7 +289,7 @@ export function FilterCriteriaRow({id, index, tableMetaData, metaData, criteria,
    let defaultFieldValue;
    let field = null;
    let fieldTable = null;
-   if(criteria && criteria.fieldName)
+   if (criteria && criteria.fieldName)
    {
       [field, fieldTable] = FilterUtils.getField(tableMetaData, criteria.fieldName);
       if (field && fieldTable)
@@ -303,9 +308,9 @@ export function FilterCriteriaRow({id, index, tableMetaData, metaData, criteria,
 
          let newOperatorSelectedValue = operatorOptions.filter(option =>
          {
-            if(option.value == criteria.operator)
+            if (option.value == criteria.operator)
             {
-               if(option.implicitValues)
+               if (option.implicitValues)
                {
                   return (JSON.stringify(option.implicitValues) == JSON.stringify(criteria.values));
                }
@@ -316,7 +321,7 @@ export function FilterCriteriaRow({id, index, tableMetaData, metaData, criteria,
             }
             return (false);
          })[0];
-         if(newOperatorSelectedValue?.label !== operatorSelectedValue?.label)
+         if (newOperatorSelectedValue?.label !== operatorSelectedValue?.label)
          {
             setOperatorSelectedValue(newOperatorSelectedValue);
             setOperatorInputValue(newOperatorSelectedValue?.label);
@@ -379,12 +384,12 @@ export function FilterCriteriaRow({id, index, tableMetaData, metaData, criteria,
    {
       criteria.operator = newValue ? newValue.value : null;
 
-      if(newValue)
+      if (newValue)
       {
          setOperatorSelectedValue(newValue);
          setOperatorInputValue(newValue.label);
 
-         if(newValue.implicitValues)
+         if (newValue.implicitValues)
          {
             criteria.values = newValue.implicitValues;
          }
@@ -393,15 +398,15 @@ export function FilterCriteriaRow({id, index, tableMetaData, metaData, criteria,
          // we've seen cases where switching operators can sometimes put a null in as the first value... //
          // that just causes a bad time (e.g., null pointers in Autocomplete), so, get rid of that.      //
          //////////////////////////////////////////////////////////////////////////////////////////////////
-         if(criteria.values && criteria.values.length == 1 && criteria.values[0] == null)
+         if (criteria.values && criteria.values.length == 1 && criteria.values[0] == null)
          {
             criteria.values = [];
          }
 
-         if(newValue.valueMode && !newValue.implicitValues)
+         if (newValue.valueMode && !newValue.implicitValues)
          {
             const requiredValueCount = getValueModeRequiredCount(newValue.valueMode);
-            if(requiredValueCount != null && criteria.values.length > requiredValueCount)
+            if (requiredValueCount != null && criteria.values.length > requiredValueCount)
             {
                criteria.values.splice(requiredValueCount);
             }
@@ -424,12 +429,12 @@ export function FilterCriteriaRow({id, index, tableMetaData, metaData, criteria,
       // @ts-ignore
       const value = newValue !== undefined ? newValue : event ? event.target.value : null;
 
-      if(!criteria.values)
+      if (!criteria.values)
       {
          criteria.values = [];
       }
 
-      if(valueIndex == "all")
+      if (valueIndex == "all")
       {
          criteria.values = value;
       }
@@ -485,7 +490,7 @@ export function FilterCriteriaRow({id, index, tableMetaData, metaData, criteria,
          </Box>
          <Box display="inline-block" width={250} className="fieldColumn">
             <FieldAutoComplete id={`field-${id}`} metaData={metaData} tableMetaData={tableMetaData} defaultValue={defaultFieldValue} handleFieldChange={handleFieldChange}
-               autocompleteSlotProps={{popper: {className: "filterCriteriaRowColumnPopper", style: {padding: 0, width: "250px"}}}}
+               omitExposedJoins={omitExposedJoins} autocompleteSlotProps={{popper: {className: "filterCriteriaRowColumnPopper", style: {padding: 0, width: "250px"}}}}
             />
          </Box>
          <Box display="inline-block" width={200} className="operatorColumn">
@@ -514,6 +519,8 @@ export function FilterCriteriaRow({id, index, tableMetaData, metaData, criteria,
                field={field}
                table={fieldTable}
                valueChangeHandler={(event, valueIndex, newValue) => handleValueChange(event, valueIndex, newValue)}
+               queryScreenUsage={queryScreenUsage}
+               allowVariables={allowVariables}
             />
          </Box>
          <Box display="inline-block">

src/qqq/components/query/FilterCriteriaRowValues.tsx

@@ -23,19 +23,25 @@
 import {QFieldMetaData} from "@kingsrook/qqq-frontend-core/lib/model/metaData/QFieldMetaData";
 import {QFieldType} from "@kingsrook/qqq-frontend-core/lib/model/metaData/QFieldType";
 import {QTableMetaData} from "@kingsrook/qqq-frontend-core/lib/model/metaData/QTableMetaData";
+import {FilterVariableExpression} from "@kingsrook/qqq-frontend-core/lib/model/query/FilterVariableExpression";
 import Autocomplete from "@mui/material/Autocomplete";
 import Box from "@mui/material/Box";
 import Icon from "@mui/material/Icon";
 import IconButton from "@mui/material/IconButton";
 import InputAdornment from "@mui/material/InputAdornment/InputAdornment";
 import TextField from "@mui/material/TextField";
-import React, {SyntheticEvent, useReducer} from "react";
+import DynamicFormUtils from "qqq/components/forms/DynamicFormUtils";
 import DynamicSelect from "qqq/components/forms/DynamicSelect";
-import CriteriaDateField from "qqq/components/query/CriteriaDateField";
+import AssignFilterVariable from "qqq/components/query/AssignFilterVariable";
+import CriteriaDateField, {NoWrapTooltip} from "qqq/components/query/CriteriaDateField";
 import {QFilterCriteriaWithId} from "qqq/components/query/CustomFilterPanel";
+import {EvaluatedExpression} from "qqq/components/query/EvaluatedExpression";
 import FilterCriteriaPaster from "qqq/components/query/FilterCriteriaPaster";
 import {OperatorOption, ValueMode} from "qqq/components/query/FilterCriteriaRow";
+import {QueryScreenUsage} from "qqq/pages/records/query/RecordQuery";
 import ValueUtils from "qqq/utils/qqq/ValueUtils";
+import React, {SyntheticEvent, useReducer} from "react";
+import {flushSync} from "react-dom";
 
 interface Props
 {
@@ -44,7 +50,9 @@ interface Props
    field: QFieldMetaData;
    table: QTableMetaData;
    valueChangeHandler: (event: React.ChangeEvent | SyntheticEvent, valueIndex?: number | "all", newValue?: any) => void;
-   initiallyOpenMultiValuePvs?: boolean
+   initiallyOpenMultiValuePvs?: boolean;
+   queryScreenUsage?: QueryScreenUsage;
+   allowVariables?: boolean;
 }
 
 FilterCriteriaRowValues.defaultProps =
@@ -52,6 +60,10 @@ FilterCriteriaRowValues.defaultProps =
       initiallyOpenMultiValuePvs: false
    };
 
+
+/***************************************************************************
+ * get the type to use for an <input> from a QFieldMetaData
+ ***************************************************************************/
 export const getTypeForTextField = (field: QFieldMetaData): string =>
 {
    let type = "search";
@@ -72,8 +84,15 @@ export const getTypeForTextField = (field: QFieldMetaData): string =>
    return (type);
 };
 
-export const makeTextField = (field: QFieldMetaData, criteria: QFilterCriteriaWithId, valueChangeHandler?: (event: (React.ChangeEvent | React.SyntheticEvent), valueIndex?: (number | "all"), newValue?: any) => void, valueIndex: number = 0, label = "Value", idPrefix = "value-") =>
+
+/***************************************************************************
+ * Make an <input type=text> (actually, might be a different type, but that's
+ * the gist of it), for a field.
+ ***************************************************************************/
+export const makeTextField = (field: QFieldMetaData, criteria: QFilterCriteriaWithId, valueChangeHandler?: (event: (React.ChangeEvent | React.SyntheticEvent), valueIndex?: (number | "all"), newValue?: any) => void, valueIndex: number = 0, label = "Value", idPrefix = "value-", allowVariables = false) =>
 {
+   const isExpression = criteria.values && criteria.values[valueIndex] && criteria.values[valueIndex].type;
+   const inputId = `${idPrefix}${criteria.id}`;
    let type = getTypeForTextField(field);
    const inputLabelProps: any = {};
 
@@ -88,14 +107,16 @@ export const makeTextField = (field: QFieldMetaData, criteria: QFilterCriteriaWi
       value = ValueUtils.formatDateTimeValueForForm(value);
    }
 
+   /***************************************************************************
+    * Event handler for the clear 'x'.
+    ***************************************************************************/
    const clearValue = (event: React.MouseEvent<HTMLAnchorElement> | React.MouseEvent<HTMLButtonElement>, index: number) =>
    {
       valueChangeHandler(event, index, "");
-      document.getElementById(`${idPrefix}${criteria.id}`).focus();
+      document.getElementById(inputId).focus();
    };
 
 
-
    /*******************************************************************************
     ** Event handler for key-down events - specifically added here, to stop pressing
     ** 'tab' in a date or date-time from closing the quick-filter...
@@ -104,7 +125,7 @@ export const makeTextField = (field: QFieldMetaData, criteria: QFilterCriteriaWi
    {
       if (field.type == QFieldType.DATE || field.type == QFieldType.DATE_TIME)
       {
-         if(e.code == "Tab")
+         if (e.code == "Tab")
          {
             console.log("Tab on date or date-time - don't close me, just move to the next sub-field!...");
             e.stopPropagation();
@@ -112,6 +133,44 @@ export const makeTextField = (field: QFieldMetaData, criteria: QFilterCriteriaWi
       }
    };
 
+
+   /***************************************************************************
+    * make a version of the text field for when the criteria's value is set to
+    * be a "variable"
+    ***************************************************************************/
+   const makeFilterVariableTextField = (expression: FilterVariableExpression, valueIndex: number = 0, label = "Value", idPrefix = "value-") =>
+   {
+      const clearValue = (event: React.MouseEvent<HTMLAnchorElement> | React.MouseEvent<HTMLButtonElement>, index: number) =>
+      {
+         valueChangeHandler(event, index, "");
+         document.getElementById(`${idPrefix}${criteria.id}`).focus();
+      };
+
+      const inputProps2: any = {};
+      inputProps2.endAdornment = (
+         <InputAdornment position="end">
+            <IconButton sx={{visibility: expression ? "visible" : "hidden"}} onClick={(event) => clearValue(event, valueIndex)}>
+               <Icon>closer</Icon>
+            </IconButton>
+         </InputAdornment>
+      );
+
+      return <NoWrapTooltip title={<EvaluatedExpression field={field} expression={expression} />} placement="bottom" enterDelay={1000} sx={{marginLeft: "-75px !important", marginTop: "-8px !important"}}><TextField
+         id={`${idPrefix}${criteria.id}`}
+         label={label}
+         variant="standard"
+         autoComplete="off"
+         InputProps={{disabled: true, readOnly: true, unselectable: "off", ...inputProps2}}
+         InputLabelProps={{shrink: true}}
+         value="${VARIABLE}"
+         fullWidth
+      /></NoWrapTooltip>;
+   };
+
+
+   ///////////////////////////////////////////////////////////////////////////
+   // set up an 'x' icon as an end-adornment, to clear value from the field //
+   ///////////////////////////////////////////////////////////////////////////
    const inputProps: any = {};
    inputProps.endAdornment = (
       <InputAdornment position="end">
@@ -121,23 +180,87 @@ export const makeTextField = (field: QFieldMetaData, criteria: QFilterCriteriaWi
       </InputAdornment>
    );
 
-   return <TextField
-      id={`${idPrefix}${criteria.id}`}
-      label={label}
-      variant="standard"
-      autoComplete="off"
-      type={type}
-      onChange={(event) => valueChangeHandler(event, valueIndex)}
-      onKeyDown={handleKeyDown}
-      value={value}
-      InputLabelProps={inputLabelProps}
-      InputProps={inputProps}
-      fullWidth
-      autoFocus={true}
-   />;
+
+   /***************************************************************************
+    * onChange event handler.  deals with, if the field has a to upper/lower
+    * case rule on it, to apply that transform, and adjust the cursor.
+    * See:  https://giacomocerquone.com/blog/keep-input-cursor-still
+    ***************************************************************************/
+   function onChange(event: any)
+   {
+      const beforeStart = event.target.selectionStart;
+      const beforeEnd = event.target.selectionEnd;
+
+      let isToUpperCase = DynamicFormUtils.isToUpperCase(field);
+      let isToLowerCase = DynamicFormUtils.isToLowerCase(field);
+
+      if (isToUpperCase || isToLowerCase)
+      {
+         flushSync(() =>
+         {
+            let newValue = event.currentTarget.value;
+
+            if (isToUpperCase)
+            {
+               newValue = newValue.toUpperCase();
+            }
+            if (isToLowerCase)
+            {
+               newValue = newValue.toLowerCase();
+            }
+
+            event.currentTarget.value = newValue;
+         });
+
+         const input = document.getElementById(inputId);
+         if (input)
+         {
+            // @ts-ignore
+            input.setSelectionRange(beforeStart, beforeEnd);
+         }
+      }
+
+      valueChangeHandler(event, valueIndex);
+   }
+
+   ////////////////////////
+   // return the element //
+   ////////////////////////
+   return <Box sx={{margin: 0, padding: 0, display: "flex"}}>
+      {
+         isExpression ? (
+            makeFilterVariableTextField(criteria.values[valueIndex], valueIndex, label, idPrefix)
+         ) : (
+            <TextField
+               id={inputId}
+               label={label}
+               variant="standard"
+               autoComplete="off"
+               type={type}
+               onChange={onChange}
+               onKeyDown={handleKeyDown}
+               value={value}
+               InputLabelProps={inputLabelProps}
+               InputProps={inputProps}
+               fullWidth
+               autoFocus={true}
+            />
+         )
+      }
+      {
+         allowVariables && (
+            <AssignFilterVariable field={field} valueChangeHandler={valueChangeHandler} valueIndex={valueIndex} />
+         )
+      }
+   </Box>;
 };
 
-function FilterCriteriaRowValues({operatorOption, criteria, field, table, valueChangeHandler, initiallyOpenMultiValuePvs}: Props): JSX.Element
+
+/***************************************************************************
+ * Component that is the "values" portion of a FilterCriteria Row in the
+ * advanced query filter editor.
+ ***************************************************************************/
+function FilterCriteriaRowValues({operatorOption, criteria, field, table, valueChangeHandler, initiallyOpenMultiValuePvs, queryScreenUsage, allowVariables}: Props): JSX.Element
 {
    const [, forceUpdate] = useReducer((x) => x + 1, 0);
 
@@ -146,6 +269,10 @@ function FilterCriteriaRowValues({operatorOption, criteria, field, table, valueC
       return null;
    }
 
+
+   /***************************************************************************
+    * Callback for the Save button from the paste-values modal
+    ***************************************************************************/
    function saveNewPasterValues(newValues: any[])
    {
       if (criteria.values)
@@ -169,33 +296,38 @@ function FilterCriteriaRowValues({operatorOption, criteria, field, table, valueC
       forceUpdate();
    }
 
+   const isExpression = criteria.values && criteria.values[0] && criteria.values[0].type;
+
+   //////////////////////////////////////////////////////////////////////////////
+   // render different form element9s) based on operator option's "value mode" //
+   //////////////////////////////////////////////////////////////////////////////
    switch (operatorOption.valueMode)
    {
       case ValueMode.NONE:
          return null;
       case ValueMode.SINGLE:
-         return makeTextField(field, criteria, valueChangeHandler);
+         return makeTextField(field, criteria, valueChangeHandler, 0, undefined, undefined, allowVariables);
       case ValueMode.SINGLE_DATE:
-         return <CriteriaDateField field={field} valueChangeHandler={valueChangeHandler} criteria={criteria} />;
+         return <CriteriaDateField field={field} valueChangeHandler={valueChangeHandler} criteria={criteria} allowVariables={allowVariables} />;
       case ValueMode.DOUBLE_DATE:
          return <Box>
-            <CriteriaDateField field={field} valueChangeHandler={valueChangeHandler} criteria={criteria} valueIndex={0} label="From" idPrefix="from-" />
-            <CriteriaDateField field={field} valueChangeHandler={valueChangeHandler} criteria={criteria} valueIndex={1} label="To" idPrefix="to-" />
+            <CriteriaDateField field={field} valueChangeHandler={valueChangeHandler} criteria={criteria} valueIndex={0} label="From" idPrefix="from-" allowVariables={allowVariables} />
+            <CriteriaDateField field={field} valueChangeHandler={valueChangeHandler} criteria={criteria} valueIndex={1} label="To" idPrefix="to-" allowVariables={allowVariables} />
          </Box>;
       case ValueMode.SINGLE_DATE_TIME:
-         return <CriteriaDateField field={field} valueChangeHandler={valueChangeHandler} criteria={criteria} />;
+         return <CriteriaDateField field={field} valueChangeHandler={valueChangeHandler} criteria={criteria} allowVariables={allowVariables} />;
       case ValueMode.DOUBLE_DATE_TIME:
          return <Box>
-            <CriteriaDateField field={field} valueChangeHandler={valueChangeHandler} criteria={criteria} valueIndex={0} label="From" idPrefix="from-" />
-            <CriteriaDateField field={field} valueChangeHandler={valueChangeHandler} criteria={criteria} valueIndex={1} label="To" idPrefix="to-" />
+            <CriteriaDateField field={field} valueChangeHandler={valueChangeHandler} criteria={criteria} valueIndex={0} label="From" idPrefix="from-" allowVariables={allowVariables} />
+            <CriteriaDateField field={field} valueChangeHandler={valueChangeHandler} criteria={criteria} valueIndex={1} label="To" idPrefix="to-" allowVariables={allowVariables} />
          </Box>;
       case ValueMode.DOUBLE:
          return <Box>
             <Box width="50%" display="inline-block">
-               {makeTextField(field, criteria, valueChangeHandler, 0, "From", "from-")}
+               {makeTextField(field, criteria, valueChangeHandler, 0, "From", "from-", allowVariables)}
             </Box>
             <Box width="50%" display="inline-block">
-               {makeTextField(field, criteria, valueChangeHandler, 1, "To", "to-")}
+               {makeTextField(field, criteria, valueChangeHandler, 1, "To", "to-", allowVariables)}
             </Box>
          </Box>;
       case ValueMode.MULTI:
@@ -228,19 +360,29 @@ function FilterCriteriaRowValues({operatorOption, criteria, field, table, valueC
          {
             selectedPossibleValue = criteria.values[0];
          }
-         return <Box mb={-1.5}>
-            <DynamicSelect
-               tableName={table.name}
-               fieldName={field.name}
-               overrideId={field.name + "-single-" + criteria.id}
-               key={field.name + "-single-" + criteria.id}
-               fieldLabel="Value"
-               initialValue={selectedPossibleValue?.id}
-               initialDisplayValue={selectedPossibleValue?.label}
-               inForm={false}
-               onChange={(value: any) => valueChangeHandler(null, 0, value)}
-               variant="standard"
-            />
+         return <Box display="flex">
+            {
+               isExpression ? (
+                  makeTextField(field, criteria, valueChangeHandler, 0, undefined, undefined, allowVariables)
+               ) : (
+                  <Box width={"100%"}>
+                     <DynamicSelect
+                        fieldPossibleValueProps={{tableName: table.name, fieldName: field.name, initialDisplayValue: selectedPossibleValue?.label}}
+                        overrideId={field.name + "-single-" + criteria.id}
+                        key={field.name + "-single-" + criteria.id}
+                        fieldLabel="Value"
+                        initialValue={selectedPossibleValue?.id}
+                        inForm={false}
+                        onChange={(value: any) => valueChangeHandler(null, 0, value)}
+                        variant="standard"
+                        useCase="filter"
+                     />
+                  </Box>
+               )
+            }
+            {
+               allowVariables && !isExpression && <Box mt={2.0}><AssignFilterVariable field={field} valueChangeHandler={valueChangeHandler} valueIndex={0} /></Box>
+            }
          </Box>;
       case ValueMode.PVS_MULTI:
          console.log("Doing pvs multi: " + criteria.values);
@@ -256,24 +398,29 @@ function FilterCriteriaRowValues({operatorOption, criteria, field, table, valueC
                initialValues = criteria.values;
             }
          }
-         return <Box mb={-1.5}>
-            <DynamicSelect
-               tableName={table.name}
-               fieldName={field.name}
-               overrideId={field.name + "-multi-" + criteria.id}
-               key={field.name + "-multi-" + criteria.id}
-               isMultiple
-               fieldLabel="Values"
-               initialValues={initialValues}
-               initiallyOpen={false /*initiallyOpenMultiValuePvs*/}
-               inForm={false}
-               onChange={(value: any) => valueChangeHandler(null, "all", value)}
-               variant="standard"
-            />
+         return <Box display="flex" alignItems="flex-end" className="multiValue">
+            <Box width={"100%"}>
+               <DynamicSelect
+                  fieldPossibleValueProps={{tableName: table.name, fieldName: field.name, initialDisplayValue: null}}
+                  overrideId={field.name + "-multi-" + criteria.id}
+                  key={field.name + "-multi-" + criteria.id + "-" + criteria.values.length}
+                  isMultiple
+                  fieldLabel="Values"
+                  initialValues={initialValues}
+                  initiallyOpen={false /*initiallyOpenMultiValuePvs*/}
+                  inForm={false}
+                  onChange={(value: any) => valueChangeHandler(null, "all", value)}
+                  variant="standard"
+                  useCase="filter"
+               />
+            </Box>
+            <Box>
+               <FilterCriteriaPaster table={table} field={field} type="pvs" onSave={(newValues: any[]) => saveNewPasterValues(newValues)} />
+            </Box>
          </Box>;
    }
 
    return (<br />);
 }
 
-export default FilterCriteriaRowValues;
+export default FilterCriteriaRowValues;

src/qqq/components/query/QueryScreenActionMenu.tsx

@@ -29,9 +29,9 @@ import Icon from "@mui/material/Icon";
 import ListItemIcon from "@mui/material/ListItemIcon";
 import Menu from "@mui/material/Menu";
 import MenuItem from "@mui/material/MenuItem";
+import {QActionsMenuButton} from "qqq/components/buttons/DefaultButtons";
 import React, {useState} from "react";
 import {useNavigate} from "react-router-dom";
-import {QActionsMenuButton} from "qqq/components/buttons/DefaultButtons";
 
 interface QueryScreenActionMenuProps
 {
@@ -40,44 +40,40 @@ interface QueryScreenActionMenuProps
    tableProcesses: QProcessMetaData[];
    bulkLoadClicked: () => void;
    bulkEditClicked: () => void;
+   bulkEditWithFileClicked: () => void;
    bulkDeleteClicked: () => void;
    processClicked: (process: QProcessMetaData) => void;
 }
 
-QueryScreenActionMenu.defaultProps = {
-};
+QueryScreenActionMenu.defaultProps = {};
 
-export default function QueryScreenActionMenu({metaData, tableMetaData, tableProcesses, bulkLoadClicked, bulkEditClicked, bulkDeleteClicked, processClicked}: QueryScreenActionMenuProps): JSX.Element
+export default function QueryScreenActionMenu({metaData, tableMetaData, tableProcesses, bulkLoadClicked, bulkEditClicked, bulkEditWithFileClicked, bulkDeleteClicked, processClicked}: QueryScreenActionMenuProps): JSX.Element
 {
-   const [anchorElement, setAnchorElement] = useState(null)
+   const [anchorElement, setAnchorElement] = useState(null);
 
    const navigate = useNavigate();
 
    const openActionsMenu = (event: any) =>
    {
       setAnchorElement(event.currentTarget);
-   }
+   };
 
    const closeActionsMenu = () =>
    {
       setAnchorElement(null);
-   }
-
-   const pushDividerIfNeeded = (menuItems: JSX.Element[]) =>
-   {
-      if (menuItems.length > 0)
-      {
-         menuItems.push(<Divider key="divider" />);
-      }
    };
 
    const runSomething = (handler: () => void) =>
    {
       closeActionsMenu();
       handler();
-   }
+   };
 
    const menuItems: JSX.Element[] = [];
+
+   //////////////////////////////////////////////////////
+   // start with bulk actions, if user has permissions //
+   //////////////////////////////////////////////////////
    if (tableMetaData.capabilities.has(Capability.TABLE_INSERT) && tableMetaData.insertPermission)
    {
       menuItems.push(<MenuItem key="bulkLoad" onClick={() => runSomething(bulkLoadClicked)}><ListItemIcon><Icon>library_add</Icon></ListItemIcon>Bulk Load</MenuItem>);
@@ -85,25 +81,14 @@ export default function QueryScreenActionMenu({metaData, tableMetaData, tablePro
    if (tableMetaData.capabilities.has(Capability.TABLE_UPDATE) && tableMetaData.editPermission)
    {
       menuItems.push(<MenuItem key="bulkEdit" onClick={() => runSomething(bulkEditClicked)}><ListItemIcon><Icon>edit</Icon></ListItemIcon>Bulk Edit</MenuItem>);
+      menuItems.push(<MenuItem key="bulkEditWithFile" onClick={() => runSomething(bulkEditWithFileClicked)}><ListItemIcon><Icon>edit_note</Icon></ListItemIcon>Bulk Edit With File</MenuItem>);
    }
    if (tableMetaData.capabilities.has(Capability.TABLE_DELETE) && tableMetaData.deletePermission)
    {
       menuItems.push(<MenuItem key="bulkDelete" onClick={() => runSomething(bulkDeleteClicked)}><ListItemIcon><Icon>delete</Icon></ListItemIcon>Bulk Delete</MenuItem>);
    }
 
-   const runRecordScriptProcess = metaData?.processes.get("runRecordScript");
-   if (runRecordScriptProcess)
-   {
-      const process = runRecordScriptProcess;
-      menuItems.push(<MenuItem key={process.name} onClick={() => runSomething(() => processClicked(process))}><ListItemIcon><Icon>{process.iconName ?? "arrow_forward"}</Icon></ListItemIcon>{process.label}</MenuItem>);
-   }
-
-   menuItems.push(<MenuItem key="developerMode" onClick={() => navigate(`${metaData.getTablePathByName(tableMetaData.name)}/dev`)}><ListItemIcon><Icon>code</Icon></ListItemIcon>Developer Mode</MenuItem>);
-
-   if (tableProcesses && tableProcesses.length)
-   {
-      pushDividerIfNeeded(menuItems);
-   }
+   menuItems.push(<Divider key="divider1" />);
 
    tableProcesses.sort((a, b) => a.label.localeCompare(b.label));
    tableProcesses.map((process) =>
@@ -111,11 +96,62 @@ export default function QueryScreenActionMenu({metaData, tableMetaData, tablePro
       menuItems.push(<MenuItem key={process.name} onClick={() => runSomething(() => processClicked(process))}><ListItemIcon><Icon>{process.iconName ?? "arrow_forward"}</Icon></ListItemIcon>{process.label}</MenuItem>);
    });
 
+   menuItems.push(<Divider key="divider2" />);
+
+   ////////////////////////////////////////////
+   // add processes that apply to all tables //
+   ////////////////////////////////////////////
+   const materialDashboardInstanceMetaData = metaData.supplementalInstanceMetaData?.get("materialDashboard");
+   if (materialDashboardInstanceMetaData)
+   {
+      const processNamesToAddToAllQueryAndViewScreens = materialDashboardInstanceMetaData.processNamesToAddToAllQueryAndViewScreens;
+      if (processNamesToAddToAllQueryAndViewScreens)
+      {
+         for (let processName of processNamesToAddToAllQueryAndViewScreens)
+         {
+            const process = metaData?.processes.get(processName);
+            if (process)
+            {
+               menuItems.push(<MenuItem key={process.name} onClick={() => runSomething(() => processClicked(process))}><ListItemIcon><Icon>{process.iconName ?? "arrow_forward"}</Icon></ListItemIcon>{process.label}</MenuItem>);
+            }
+         }
+      }
+   }
+   else
+   {
+      //////////////////////////////////////
+      // deprecated in favor of the above //
+      //////////////////////////////////////
+      const runRecordScriptProcess = metaData?.processes.get("runRecordScript");
+      if (runRecordScriptProcess)
+      {
+         const process = runRecordScriptProcess;
+         menuItems.push(<MenuItem key={process.name} onClick={() => runSomething(() => processClicked(process))}><ListItemIcon><Icon>{process.iconName ?? "arrow_forward"}</Icon></ListItemIcon>{process.label}</MenuItem>);
+      }
+   }
+
+   ////////////////////////////////////////
+   // todo - any conditions around this? //
+   ////////////////////////////////////////
+   menuItems.push(<MenuItem key="developerMode" onClick={() => navigate(`${metaData.getTablePathByName(tableMetaData.name)}/dev`)}><ListItemIcon><Icon>code</Icon></ListItemIcon>Developer Mode</MenuItem>);
+
    if (menuItems.length === 0)
    {
       menuItems.push(<MenuItem key="notAvaialableNow" disabled><ListItemIcon><Icon>block</Icon></ListItemIcon><i>No actions available</i></MenuItem>);
    }
 
+   ////////////////////////////////////////////////////////////////////////////////
+   // remove any duplicated dividers, and any dividers in the first or last slot //
+   ////////////////////////////////////////////////////////////////////////////////
+   for (let i = 0; i < menuItems.length; i++)
+   {
+      if (menuItems[i].type == Divider && (i == 0 || (i > 0 && menuItems[i - 1].type == Divider) || i == menuItems.length - 1))
+      {
+         menuItems.splice(i, 1);
+         i--;
+      }
+   }
+
    return (
       <>
          <QActionsMenuButton isOpen={anchorElement} onClickHandler={openActionsMenu} />
@@ -130,5 +166,5 @@ export default function QueryScreenActionMenu({metaData, tableMetaData, tablePro
             {menuItems}
          </Menu>
       </>
-   )
+   );
 }

src/qqq/components/query/QuickFilter.tsx

@@ -30,14 +30,15 @@ import Box from "@mui/material/Box";
 import Button from "@mui/material/Button";
 import Menu from "@mui/material/Menu";
 import TextField from "@mui/material/TextField";
-import React, {SyntheticEvent, useContext, useReducer, useState} from "react";
 import QContext from "QContext";
 import {QFilterCriteriaWithId} from "qqq/components/query/CustomFilterPanel";
 import {getDefaultCriteriaValue, getOperatorOptions, getValueModeRequiredCount, OperatorOption, validateCriteria} from "qqq/components/query/FilterCriteriaRow";
 import FilterCriteriaRowValues from "qqq/components/query/FilterCriteriaRowValues";
 import XIcon from "qqq/components/query/XIcon";
+import {QueryScreenUsage} from "qqq/pages/records/query/RecordQuery";
 import FilterUtils from "qqq/utils/qqq/FilterUtils";
 import TableUtils from "qqq/utils/qqq/TableUtils";
+import React, {SyntheticEvent, useContext, useEffect, useReducer, useState} from "react";
 
 export type CriteriaParamType = QFilterCriteriaWithId | null | "tooComplex";
 
@@ -50,6 +51,8 @@ interface QuickFilterProps
    updateCriteria: (newCriteria: QFilterCriteria, needDebounce: boolean, doRemoveCriteria: boolean) => void;
    defaultOperator?: QCriteriaOperator;
    handleRemoveQuickFilterField?: (fieldName: string) => void;
+   queryScreenUsage?: QueryScreenUsage;
+   allowVariables?: boolean;
 }
 
 QuickFilter.defaultProps =
@@ -71,7 +74,7 @@ export const quickFilterButtonStyles = {
    minHeight: "auto",
    padding: "0.375rem 0.625rem", whiteSpace: "nowrap",
    marginBottom: "0.5rem"
-}
+};
 
 /*******************************************************************************
  ** Test if a CriteriaParamType represents an actual query criteria - or, if it's
@@ -89,11 +92,11 @@ const criteriaParamIsCriteria = (param: CriteriaParamType): boolean =>
  *******************************************************************************/
 const doesOperatorOptionEqualCriteria = (operatorOption: OperatorOption, criteria: QFilterCriteriaWithId): boolean =>
 {
-   if(operatorOption.value == criteria.operator)
+   if (operatorOption.value == criteria.operator)
    {
-      if(operatorOption.implicitValues)
+      if (operatorOption.implicitValues)
       {
-         if(JSON.stringify(operatorOption.implicitValues) == JSON.stringify(criteria.values))
+         if (JSON.stringify(operatorOption.implicitValues) == JSON.stringify(criteria.values))
          {
             return (true);
          }
@@ -107,7 +110,7 @@ const doesOperatorOptionEqualCriteria = (operatorOption: OperatorOption, criteri
    }
 
    return (false);
-}
+};
 
 
 /*******************************************************************************
@@ -115,31 +118,48 @@ const doesOperatorOptionEqualCriteria = (operatorOption: OperatorOption, criteri
  ** autocomplete), given an array of options, the query's active criteria in this
  ** field, and the default operator to use for this field
  *******************************************************************************/
-const getOperatorSelectedValue = (operatorOptions: OperatorOption[], criteria: QFilterCriteriaWithId, defaultOperator: QCriteriaOperator): OperatorOption =>
+const getOperatorSelectedValue = (operatorOptions: OperatorOption[], criteria: QFilterCriteriaWithId, defaultOperator: QCriteriaOperator, return0thOptionInsteadOfNull: boolean = false): OperatorOption =>
 {
-   if(criteria)
+   if (criteria)
    {
       const filteredOptions = operatorOptions.filter(o => doesOperatorOptionEqualCriteria(o, criteria));
-      if(filteredOptions.length > 0)
+      if (filteredOptions.length > 0)
       {
          return (filteredOptions[0]);
       }
    }
 
    const filteredOptions = operatorOptions.filter(o => o.value == defaultOperator);
-   if(filteredOptions.length > 0)
+   if (filteredOptions.length > 0)
    {
       return (filteredOptions[0]);
    }
 
+   if (return0thOptionInsteadOfNull)
+   {
+      console.log("Returning 0th operator instead of null - this isn't expected, but has been seen to happen - so here's some additional debugging:");
+      try
+      {
+         console.log("Operator options:   " + JSON.stringify(operatorOptions));
+         console.log("Criteria: " + JSON.stringify(criteria));
+         console.log("Default Operator:   " + JSON.stringify(defaultOperator));
+      }
+      catch (e)
+      {
+         console.log(`Error in debug output: ${e}`);
+      }
+
+      return operatorOptions[0];
+   }
+
    return (null);
-}
+};
 
 /*******************************************************************************
  ** Component to render a QuickFilter - that is - a button, with a Menu under it,
  ** with Operator and Value controls.
  *******************************************************************************/
-export default function QuickFilter({tableMetaData, fullFieldName, fieldMetaData, criteriaParam, updateCriteria, defaultOperator, handleRemoveQuickFilterField}: QuickFilterProps): JSX.Element
+export default function QuickFilter({tableMetaData, fullFieldName, fieldMetaData, criteriaParam, updateCriteria, defaultOperator, handleRemoveQuickFilterField, queryScreenUsage, allowVariables}: QuickFilterProps): JSX.Element
 {
    const operatorOptions = fieldMetaData ? getOperatorOptions(tableMetaData, fullFieldName) : [];
    const [_, tableForField] = TableUtils.getFieldAndTable(tableMetaData, fullFieldName);
@@ -154,7 +174,7 @@ export default function QuickFilter({tableMetaData, fullFieldName, fieldMetaData
    const [criteria, setCriteria] = useState(criteriaParamIsCriteria(criteriaParam) ? Object.assign({}, criteriaParam) as QFilterCriteriaWithId : null);
    const [id, setId] = useState(criteriaParamIsCriteria(criteriaParam) ? (criteriaParam as QFilterCriteriaWithId).id : ++seedId);
 
-   const [operatorSelectedValue, setOperatorSelectedValue] = useState(getOperatorSelectedValue(operatorOptions, criteria, defaultOperator));
+   const [operatorSelectedValue, setOperatorSelectedValue] = useState(getOperatorSelectedValue(operatorOptions, criteria, defaultOperator, true));
    const [operatorInputValue, setOperatorInputValue] = useState(operatorSelectedValue?.label);
 
    const {criteriaIsValid, criteriaStatusTooltip} = validateCriteria(criteria, operatorSelectedValue);
@@ -166,6 +186,13 @@ export default function QuickFilter({tableMetaData, fullFieldName, fieldMetaData
    //////////////////////
    const [, forceUpdate] = useReducer((x) => x + 1, 0);
 
+   useEffect(() =>
+   {
+      //////////////////////////////////////////////////////////////////////////////
+      // was not seeing criteria changes take place until watching it stringified //
+      //////////////////////////////////////////////////////////////////////////////
+      setCriteria(criteria);
+   }, [JSON.stringify(criteria)]);
 
    /*******************************************************************************
     **
@@ -190,7 +217,7 @@ export default function QuickFilter({tableMetaData, fullFieldName, fieldMetaData
    //////////////////////////////////////////////////////////////////////////////////////////////////////////////
    if (criteriaParamIsCriteria(criteriaParam) && JSON.stringify(criteriaParam) !== JSON.stringify(criteria))
    {
-      if(isOpen)
+      if (isOpen)
       {
          ////////////////////////////////////////////////////////////////////////////////
          // this was firing too-often for case where:  there was a criteria originally //
@@ -217,12 +244,12 @@ export default function QuickFilter({tableMetaData, fullFieldName, fieldMetaData
     *******************************************************************************/
    const criteriaNeedsReset = (): boolean =>
    {
-      if(criteria != null && criteriaParam == null)
+      if (criteria != null && criteriaParam == null)
       {
          const defaultOperatorOption = operatorOptions.filter(o => o.value == defaultOperator)[0];
-         if(criteria.operator !== defaultOperatorOption?.value || JSON.stringify(criteria.values) !== JSON.stringify(getDefaultCriteriaValue()))
+         if (criteria.operator !== defaultOperatorOption?.value || JSON.stringify(criteria.values) !== JSON.stringify(getDefaultCriteriaValue()))
          {
-            if(isOpen)
+            if (isOpen)
             {
                //////////////////////////////////////////////////////////////////////////////////
                // this was firing too-often for case where:  there was no criteria originally, //
@@ -237,7 +264,7 @@ export default function QuickFilter({tableMetaData, fullFieldName, fieldMetaData
       }
 
       return (false);
-   }
+   };
 
    /*******************************************************************************
     ** Construct a new criteria object - resetting the values tied to the operator
@@ -251,8 +278,8 @@ export default function QuickFilter({tableMetaData, fullFieldName, fieldMetaData
       setOperatorSelectedValue(operatorOption);
       setOperatorInputValue(operatorOption?.label);
       setCriteria(criteria);
-      return(criteria);
-   }
+      return (criteria);
+   };
 
    /*******************************************************************************
     ** event handler to open the menu in response to the button being clicked.
@@ -266,7 +293,7 @@ export default function QuickFilter({tableMetaData, fullFieldName, fieldMetaData
       {
          const element = document.getElementById("value-" + criteria.id);
          element?.focus();
-      })
+      });
    };
 
    /*******************************************************************************
@@ -304,15 +331,15 @@ export default function QuickFilter({tableMetaData, fullFieldName, fieldMetaData
          // we've seen cases where switching operators can sometimes put a null in as the first value... //
          // that just causes a bad time (e.g., null pointers in Autocomplete), so, get rid of that.      //
          //////////////////////////////////////////////////////////////////////////////////////////////////
-         if(criteria.values && criteria.values.length == 1 && criteria.values[0] == null)
+         if (criteria.values && criteria.values.length == 1 && criteria.values[0] == null)
          {
             criteria.values = [];
          }
 
-         if(newValue.valueMode && !newValue.implicitValues)
+         if (newValue.valueMode && !newValue.implicitValues)
          {
             const requiredValueCount = getValueModeRequiredCount(newValue.valueMode);
-            if(requiredValueCount != null && criteria.values.length > requiredValueCount)
+            if (requiredValueCount != null && criteria.values.length > requiredValueCount)
             {
                criteria.values.splice(requiredValueCount);
             }
@@ -345,6 +372,7 @@ export default function QuickFilter({tableMetaData, fullFieldName, fieldMetaData
       // @ts-ignore
       const value = newValue !== undefined ? newValue : event ? event.target.value : null;
 
+      console.log("IN HERE");
       if (!criteria.values)
       {
          criteria.values = [];
@@ -376,13 +404,13 @@ export default function QuickFilter({tableMetaData, fullFieldName, fieldMetaData
     *******************************************************************************/
    const resetCriteria = (e: React.MouseEvent<HTMLSpanElement>) =>
    {
-      if(criteriaIsValid)
+      if (criteriaIsValid)
       {
          e.stopPropagation();
          const newCriteria = makeNewCriteria();
          updateCriteria(newCriteria, false, true);
       }
-   }
+   };
 
    /*******************************************************************************
     ** event handler for clicking the (x) icon that turns off this quick filter field.
@@ -390,17 +418,17 @@ export default function QuickFilter({tableMetaData, fullFieldName, fieldMetaData
     *******************************************************************************/
    const handleTurningOffQuickFilterField = () =>
    {
-      closeMenu()
-      if(handleRemoveQuickFilterField)
+      closeMenu();
+      if (handleRemoveQuickFilterField)
       {
          handleRemoveQuickFilterField(criteria?.fieldName);
       }
-   }
+   };
 
    ////////////////////////////////////////////////////////////////////////////////////
    // if no field was input (e.g., record-query is still loading), return null early //
    ////////////////////////////////////////////////////////////////////////////////////
-   if(!fieldMetaData)
+   if (!fieldMetaData)
    {
       return (null);
    }
@@ -410,10 +438,10 @@ export default function QuickFilter({tableMetaData, fullFieldName, fieldMetaData
    // from the last selected one, then set the state vars that control that autocomplete   //
    //////////////////////////////////////////////////////////////////////////////////////////
    const maybeNewOperatorSelectedValue = getOperatorSelectedValue(operatorOptions, criteria, defaultOperator);
-   if(JSON.stringify(maybeNewOperatorSelectedValue) !== JSON.stringify(operatorSelectedValue))
+   if (JSON.stringify(maybeNewOperatorSelectedValue) !== JSON.stringify(operatorSelectedValue))
    {
-      setOperatorSelectedValue(maybeNewOperatorSelectedValue)
-      setOperatorInputValue(maybeNewOperatorSelectedValue?.label)
+      setOperatorSelectedValue(maybeNewOperatorSelectedValue);
+      setOperatorInputValue(maybeNewOperatorSelectedValue?.label);
    }
 
    /////////////////////////////////////////////////////////////////////////////////////
@@ -431,7 +459,7 @@ export default function QuickFilter({tableMetaData, fullFieldName, fieldMetaData
    const tooltipEnterDelay = 500;
 
    let buttonAdditionalStyles: any = {};
-   let buttonContent = <span>{tableForField?.name != tableMetaData.name ? `${tableForField.label}: ` : ""}{fieldMetaData.label}</span>
+   let buttonContent = <span>{tableForField?.name != tableMetaData.name ? `${tableForField.label}: ` : ""}{fieldMetaData.label}</span>;
    let buttonClassName = "filterNotActive";
    if (criteriaIsValid)
    {
@@ -446,9 +474,9 @@ export default function QuickFilter({tableMetaData, fullFieldName, fieldMetaData
       // don't show the Equals or In operators //
       ///////////////////////////////////////////
       let operatorString = (<>{operatorSelectedValue.label}&nbsp;</>);
-      if(operatorSelectedValue.value == QCriteriaOperator.EQUALS || operatorSelectedValue.value == QCriteriaOperator.IN)
+      if (operatorSelectedValue.value == QCriteriaOperator.EQUALS || operatorSelectedValue.value == QCriteriaOperator.IN)
       {
-         operatorString = (<></>)
+         operatorString = (<></>);
       }
 
       buttonContent = (<><span style={{fontWeight: 700}}>{buttonContent}:</span>&nbsp;<span style={{fontWeight: 400}}>{operatorString}{valuesString}</span></>);
@@ -491,7 +519,7 @@ export default function QuickFilter({tableMetaData, fullFieldName, fieldMetaData
    const xClicked = (e: React.MouseEvent<HTMLSpanElement>) =>
    {
       e.stopPropagation();
-      if(criteriaIsValid)
+      if (criteriaIsValid)
       {
          resetCriteria(e);
       }
@@ -499,12 +527,12 @@ export default function QuickFilter({tableMetaData, fullFieldName, fieldMetaData
       {
          handleTurningOffQuickFilterField();
       }
-   }
+   };
 
    //////////////////////////////
    // return the button & menu //
    //////////////////////////////
-   const widthAndMaxWidth = fieldMetaData?.type == QFieldType.DATE_TIME ? 275 : 250
+   const widthAndMaxWidth = (fieldMetaData?.type == QFieldType.DATE_TIME) ? 315 : 250;
    return (
       <>
          {button}
@@ -541,10 +569,12 @@ export default function QuickFilter({tableMetaData, fullFieldName, fieldMetaData
                </Box>
                <Box width={widthAndMaxWidth} maxWidth={widthAndMaxWidth} className="quickFilter filterValuesColumn">
                   <FilterCriteriaRowValues
+                     queryScreenUsage={queryScreenUsage}
                      operatorOption={operatorSelectedValue}
                      criteria={criteria}
                      field={fieldMetaData}
                      table={tableForField}
+                     allowVariables={allowVariables}
                      valueChangeHandler={(event, valueIndex, newValue) => handleValueChange(event, valueIndex, newValue)}
                      initiallyOpenMultiValuePvs={true} // todo - maybe not?
                   />

src/qqq/components/scripts/ScriptDocsForm.tsx

@@ -49,7 +49,7 @@ function ScriptDocsForm({helpText, exampleCode, aceEditorHeight}: Props): JSX.El
                <Card sx={{width: "100%", height: "100%"}}>
                   <Typography variant="h6" p={2} pb={1}>{heading}</Typography>
                   <Box className="devDocumentation" height="100%">
-                     <Typography variant="body2" sx={{maxWidth: "1200px", margin: "auto", height: "100%"}}>
+                     <Typography variant="body2" sx={{maxWidth: "1200px", margin: "auto", height: "calc(100% - 0.5rem)"}}>
                         <AceEditor
                            mode={mode}
                            theme="github"
@@ -62,7 +62,7 @@ function ScriptDocsForm({helpText, exampleCode, aceEditorHeight}: Props): JSX.El
                            width="100%"
                            showPrintMargin={false}
                            height="100%"
-                           style={{borderBottomRightRadius: "1rem", borderBottomLeftRadius: "1rem"}}
+                           style={{borderBottomRightRadius: "0.75rem", borderBottomLeftRadius: "0.75rem"}}
                         />
                      </Typography>
                   </Box>

src/qqq/components/scripts/ScriptEditor.tsx

@@ -40,16 +40,17 @@ import Snackbar from "@mui/material/Snackbar";
 import TextField from "@mui/material/TextField";
 import Tooltip from "@mui/material/Tooltip";
 import FormData from "form-data";
-import React, {useEffect, useReducer, useRef, useState} from "react";
-import AceEditor from "react-ace";
 import {QCancelButton, QSaveButton} from "qqq/components/buttons/DefaultButtons";
 import DynamicSelect from "qqq/components/forms/DynamicSelect";
 import ScriptDocsForm from "qqq/components/scripts/ScriptDocsForm";
 import ScriptTestForm from "qqq/components/scripts/ScriptTestForm";
 import Client from "qqq/utils/qqq/Client";
 
+import "ace-builds/src-noconflict/ace";
 import "ace-builds/src-noconflict/mode-javascript";
 import "ace-builds/src-noconflict/theme-github";
+import React, {useEffect, useReducer, useRef, useState} from "react";
+import AceEditor from "react-ace";
 import "ace-builds/src-noconflict/ext-language_tools";
 
 export interface ScriptEditorProps
@@ -69,15 +70,15 @@ const qController = Client.getInstance();
 
 function buildInitialFileContentsMap(scriptRevisionRecord: QRecord, scriptTypeFileSchemaList: QRecord[]): { [name: string]: string }
 {
-   const rs: {[name: string]: string} = {};
+   const rs: { [name: string]: string } = {};
 
-   if(!scriptTypeFileSchemaList)
+   if (!scriptTypeFileSchemaList)
    {
       console.log("Missing scriptTypeFileSchemaList");
    }
    else
    {
-      let files = scriptRevisionRecord?.associatedRecords?.get("files")
+      let files = scriptRevisionRecord?.associatedRecords?.get("files");
 
       for (let i = 0; i < scriptTypeFileSchemaList.length; i++)
       {
@@ -88,7 +89,7 @@ function buildInitialFileContentsMap(scriptRevisionRecord: QRecord, scriptTypeFi
          for (let j = 0; j < files?.length; j++)
          {
             let file = files[j];
-            if(file.values.get("fileName") == name)
+            if (file.values.get("fileName") == name)
             {
                contents = file.values.get("contents");
             }
@@ -103,9 +104,9 @@ function buildInitialFileContentsMap(scriptRevisionRecord: QRecord, scriptTypeFi
 
 function buildFileTypeMap(scriptTypeFileSchemaList: QRecord[]): { [name: string]: string }
 {
-   const rs: {[name: string]: string} = {};
+   const rs: { [name: string]: string } = {};
 
-   if(!scriptTypeFileSchemaList)
+   if (!scriptTypeFileSchemaList)
    {
       console.log("Missing scriptTypeFileSchemaList");
    }
@@ -125,21 +126,21 @@ function ScriptEditor({title, scriptId, scriptRevisionRecord, closeCallback, tab
 {
    const [closing, setClosing] = useState(false);
 
-   const [apiName, setApiName] = useState(scriptRevisionRecord ? scriptRevisionRecord.values.get("apiName") : null)
-   const [apiNameLabel, setApiNameLabel] = useState(scriptRevisionRecord ? scriptRevisionRecord.displayValues.get("apiName") : null)
-   const [apiVersion, setApiVersion] = useState(scriptRevisionRecord ? scriptRevisionRecord.values.get("apiVersion") : null)
-   const [apiVersionLabel, setApiVersionLabel] = useState(scriptRevisionRecord ? scriptRevisionRecord.displayValues.get("apiVersion") : null)
+   const [apiName, setApiName] = useState(scriptRevisionRecord ? scriptRevisionRecord.values.get("apiName") : null);
+   const [apiNameLabel, setApiNameLabel] = useState(scriptRevisionRecord ? scriptRevisionRecord.displayValues.get("apiName") : null);
+   const [apiVersion, setApiVersion] = useState(scriptRevisionRecord ? scriptRevisionRecord.values.get("apiVersion") : null);
+   const [apiVersionLabel, setApiVersionLabel] = useState(scriptRevisionRecord ? scriptRevisionRecord.displayValues.get("apiVersion") : null);
 
-   const fileNamesFromSchema = scriptTypeFileSchemaList.map((schemaRecord) => schemaRecord.values.get("name"))
+   const fileNamesFromSchema = scriptTypeFileSchemaList.map((schemaRecord) => schemaRecord.values.get("name"));
    const [availableFileNames, setAvailableFileNames] = useState(fileNamesFromSchema);
-   const [openEditorFileNames, setOpenEditorFileNames] = useState([fileNamesFromSchema[0]])
-   const [fileContents, setFileContents] = useState(buildInitialFileContentsMap(scriptRevisionRecord, scriptTypeFileSchemaList))
-   const [fileTypes, setFileTypes] = useState(buildFileTypeMap(scriptTypeFileSchemaList))
+   const [openEditorFileNames, setOpenEditorFileNames] = useState([fileNamesFromSchema[0]]);
+   const [fileContents, setFileContents] = useState(buildInitialFileContentsMap(scriptRevisionRecord, scriptTypeFileSchemaList));
+   const [fileTypes, setFileTypes] = useState(buildFileTypeMap(scriptTypeFileSchemaList));
    console.log(`file types: ${JSON.stringify(fileTypes)}`);
 
-   const [commitMessage, setCommitMessage] = useState("")
+   const [commitMessage, setCommitMessage] = useState("");
    const [openTool, setOpenTool] = useState(null);
-   const [errorAlert, setErrorAlert] = useState("")
+   const [errorAlert, setErrorAlert] = useState("");
    const [promptForCommitMessageOpen, setPromptForCommitMessageOpen] = useState(false);
    const [, forceUpdate] = useReducer((x) => x + 1, 0);
    const ref = useRef();
@@ -241,19 +242,19 @@ function ScriptEditor({title, scriptId, scriptRevisionRecord, closeCallback, tab
       // need this to make Ace recognize new height.
       setTimeout(() =>
       {
-         window.dispatchEvent(new Event("resize"))
+         window.dispatchEvent(new Event("resize"));
       }, 100);
    };
 
    const saveClicked = (overrideCommitMessage?: string) =>
    {
-      if(!apiName || !apiVersion)
+      if (!apiName || !apiVersion)
       {
-         setErrorAlert("You must select a value for both API Name and API Version.")
+         setErrorAlert("You must select a value for both API Name and API Version.");
          return;
       }
 
-      if(!commitMessage && !overrideCommitMessage)
+      if (!commitMessage && !overrideCommitMessage)
       {
          setPromptForCommitMessageOpen(true);
          return;
@@ -267,18 +268,18 @@ function ScriptEditor({title, scriptId, scriptRevisionRecord, closeCallback, tab
          formData.append("scriptId", scriptId);
          formData.append("commitMessage", overrideCommitMessage ?? commitMessage);
 
-         if(apiName)
+         if (apiName)
          {
             formData.append("apiName", apiName);
          }
 
-         if(apiVersion)
+         if (apiVersion)
          {
             formData.append("apiVersion", apiVersion);
          }
 
 
-         const fileNamesFromSchema = scriptTypeFileSchemaList.map((schemaRecord) => schemaRecord.values.get("name"))
+         const fileNamesFromSchema = scriptTypeFileSchemaList.map((schemaRecord) => schemaRecord.values.get("name"));
          formData.append("fileNames", fileNamesFromSchema.join(","));
 
          for (let fileName in fileContents)
@@ -299,58 +300,58 @@ function ScriptEditor({title, scriptId, scriptRevisionRecord, closeCallback, tab
 
             if (processResult instanceof QJobError)
             {
-               const jobError = processResult as QJobError
-               setErrorAlert(jobError.userFacingError ?? jobError.error)
+               const jobError = processResult as QJobError;
+               setErrorAlert(jobError.userFacingError ?? jobError.error);
                setClosing(false);
                return;
             }
 
             closeCallback(null, "saved", "Saved New Script Version");
          }
-         catch(e)
+         catch (e)
          {
             // @ts-ignore
-            setErrorAlert(e.message ?? "Unexpected error saving script")
+            setErrorAlert(e.message ?? "Unexpected error saving script");
             setClosing(false);
          }
       })();
-   }
+   };
 
    const cancelClicked = () =>
    {
       setClosing(true);
       closeCallback(null, "cancelled");
-   }
+   };
 
    const updateCode = (value: string, event: any, index: number) =>
    {
       fileContents[openEditorFileNames[index]] = value;
       forceUpdate();
-   }
+   };
 
    const updateCommitMessage = (event: React.ChangeEvent<HTMLInputElement>) =>
    {
       setCommitMessage(event.target.value);
-   }
+   };
 
    const closePromptForCommitMessage = (wasSaveClicked: boolean, message?: string) =>
    {
       setPromptForCommitMessageOpen(false);
 
-      if(wasSaveClicked)
+      if (wasSaveClicked)
       {
-         setCommitMessage(message)
+         setCommitMessage(message);
          saveClicked(message);
       }
       else
       {
          setClosing(false);
       }
-   }
+   };
 
    const changeApiName = (apiNamePossibleValue?: QPossibleValue) =>
    {
-      if(apiNamePossibleValue)
+      if (apiNamePossibleValue)
       {
          setApiName(apiNamePossibleValue.id);
       }
@@ -358,11 +359,11 @@ function ScriptEditor({title, scriptId, scriptRevisionRecord, closeCallback, tab
       {
          setApiName(null);
       }
-   }
+   };
 
    const changeApiVersion = (apiVersionPossibleValue?: QPossibleValue) =>
    {
-      if(apiVersionPossibleValue)
+      if (apiVersionPossibleValue)
       {
          setApiVersion(apiVersionPossibleValue.id);
       }
@@ -370,33 +371,33 @@ function ScriptEditor({title, scriptId, scriptRevisionRecord, closeCallback, tab
       {
          setApiVersion(null);
       }
-   }
+   };
 
    const handleSelectingFile = (event: SelectChangeEvent, index: number) =>
    {
-      openEditorFileNames[index] = event.target.value
+      openEditorFileNames[index] = event.target.value;
       setOpenEditorFileNames(openEditorFileNames);
       forceUpdate();
-   }
+   };
 
    const splitEditorClicked = () =>
    {
-      openEditorFileNames.push(availableFileNames[0])
+      openEditorFileNames.push(availableFileNames[0]);
       setOpenEditorFileNames(openEditorFileNames);
       forceUpdate();
-   }
+   };
 
    const closeEditorClicked = (index: number) =>
    {
-      openEditorFileNames.splice(index, 1)
+      openEditorFileNames.splice(index, 1);
       setOpenEditorFileNames(openEditorFileNames);
       forceUpdate();
-   }
+   };
 
    const computeEditorWidth = (): string =>
    {
-      return (100 / openEditorFileNames.length) + "%"
-   }
+      return (100 / openEditorFileNames.length) + "%";
+   };
 
    return (
       <Box className="scriptEditor" sx={{position: "absolute", overflowY: "auto", height: "100%", width: "100%"}} p={6}>
@@ -408,7 +409,7 @@ function ScriptEditor({title, scriptId, scriptRevisionRecord, closeCallback, tab
                {
                   return;
                }
-               setErrorAlert("")
+               setErrorAlert("");
             }} anchorOrigin={{vertical: "top", horizontal: "center"}}>
                <Alert color="error" onClose={() => setErrorAlert("")}>
                   {errorAlert}
@@ -440,10 +441,10 @@ function ScriptEditor({title, scriptId, scriptRevisionRecord, closeCallback, tab
             <Box sx={{height: openTool ? "45%" : "100%"}}>
                <Grid container alignItems="flex-end">
                   <Box maxWidth={"50%"} minWidth={300}>
-                     <DynamicSelect fieldName={"apiName"} initialValue={apiName} initialDisplayValue={apiNameLabel} fieldLabel={"API Name *"} tableName={"scriptRevision"} inForm={false} onChange={changeApiName} />
+                     <DynamicSelect fieldPossibleValueProps={{tableName: "scriptRevision", fieldName: "apiName", initialDisplayValue: apiNameLabel}} initialValue={apiName} fieldLabel={"API Name *"} inForm={false} onChange={changeApiName} useCase="form" />
                   </Box>
                   <Box maxWidth={"50%"} minWidth={300} pl={2}>
-                     <DynamicSelect fieldName={"apiVersion"} initialValue={apiVersion} initialDisplayValue={apiVersionLabel} fieldLabel={"API Version *"} tableName={"scriptRevision"} inForm={false} onChange={changeApiVersion} />
+                     <DynamicSelect fieldPossibleValueProps={{tableName: "scriptRevision", fieldName: "apiVersion", initialDisplayValue: apiVersionLabel}} initialValue={apiVersion} fieldLabel={"API Version *"} inForm={false} onChange={changeApiVersion} useCase="form" />
                   </Box>
                </Grid>
                <Box display="flex" sx={{height: "100%"}}>
@@ -464,19 +465,19 @@ function ScriptEditor({title, scriptId, scriptRevisionRecord, closeCallback, tab
                               <Box>
                                  {
                                     openEditorFileNames.length > 1 &&
-                                       <Tooltip title="Close this editor split" enterDelay={500}>
-                                          <IconButton size="small" onClick={() => closeEditorClicked(index)}>
-                                             <Icon>close</Icon>
-                                          </IconButton>
-                                       </Tooltip>
+                                    <Tooltip title="Close this editor split" enterDelay={500}>
+                                       <IconButton size="small" onClick={() => closeEditorClicked(index)}>
+                                          <Icon>close</Icon>
+                                       </IconButton>
+                                    </Tooltip>
                                  }
                                  {
                                     index == openEditorFileNames.length - 1 &&
-                                       <Tooltip title="Open a new editor split" enterDelay={500}>
-                                          <IconButton size="small" onClick={splitEditorClicked}>
-                                             <Icon>vertical_split</Icon>
-                                          </IconButton>
-                                       </Tooltip>
+                                    <Tooltip title="Open a new editor split" enterDelay={500}>
+                                       <IconButton size="small" onClick={splitEditorClicked}>
+                                          <Icon>vertical_split</Icon>
+                                       </IconButton>
+                                    </Tooltip>
                                  }
                               </Box>
                            </Box>
@@ -526,29 +527,29 @@ function ScriptEditor({title, scriptId, scriptRevisionRecord, closeCallback, tab
                </Grid>
             </Box>
 
-            <CommitMessagePrompt isOpen={promptForCommitMessageOpen} closeHandler={closePromptForCommitMessage}/>
+            <CommitMessagePrompt isOpen={promptForCommitMessageOpen} closeHandler={closePromptForCommitMessage} />
          </Card>
       </Box>
 
    );
 }
 
-function CommitMessagePrompt(props: {isOpen: boolean, closeHandler: (wasSaveClicked: boolean, message?: string) => void})
+function CommitMessagePrompt(props: { isOpen: boolean, closeHandler: (wasSaveClicked: boolean, message?: string) => void })
 {
-   const [commitMessage, setCommitMessage] = useState("No commit message given")
+   const [commitMessage, setCommitMessage] = useState("No commit message given");
 
    const updateCommitMessage = (event: React.ChangeEvent<HTMLInputElement>) =>
    {
       setCommitMessage(event.target.value);
-   }
+   };
 
    const keyPressHandler = (e: React.KeyboardEvent<HTMLDivElement>) =>
    {
-      if(e.key === "Enter")
+      if (e.key === "Enter")
       {
          props.closeHandler(true, commitMessage);
       }
-   }
+   };
 
    return (
       <Dialog
@@ -579,10 +580,10 @@ function CommitMessagePrompt(props: {isOpen: boolean, closeHandler: (wasSaveClic
          </DialogContent>
          <DialogActions>
             <QCancelButton onClickHandler={() => props.closeHandler(false)} disabled={false} />
-            <QSaveButton label="Save" onClickHandler={() => props.closeHandler(true, commitMessage)} disabled={false}/>
+            <QSaveButton label="Save" onClickHandler={() => props.closeHandler(true, commitMessage)} disabled={false} />
          </DialogActions>
       </Dialog>
-   )
+   );
 }
 
 export default ScriptEditor;

src/qqq/components/sharing/ShareModal.tsx

@@ -24,9 +24,8 @@ import {QTableMetaData} from "@kingsrook/qqq-frontend-core/lib/model/metaData/QT
 import {QJobComplete} from "@kingsrook/qqq-frontend-core/lib/model/processes/QJobComplete";
 import {QJobError} from "@kingsrook/qqq-frontend-core/lib/model/processes/QJobError";
 import {QRecord} from "@kingsrook/qqq-frontend-core/lib/model/QRecord";
-import {Alert} from "@mui/material";
+import {Alert, Box} from "@mui/material";
 import Autocomplete from "@mui/material/Autocomplete";
-import Box from "@mui/material/Box";
 import Button from "@mui/material/Button";
 import Card from "@mui/material/Card";
 import Icon from "@mui/material/Icon";
@@ -370,15 +369,15 @@ export default function ShareModal({open, onClose, tableMetaData, record}: Share
             <Card sx={{my: 5, mx: "auto", p: 3}}>
 
                {/* header */}
-               <Box display="flex" flexDirection="row" justifyContent="space-between" alignItems="flex-start">
+               <Box display="flex" flexDirection="row" justifyContent="space-between" alignItems="flex-start" maxWidth="590px">
                   <Typography variant="h4" pb={1} fontWeight="600">
                      Share {tableMetaData.label}: {record?.recordLabel ?? record?.values?.get(tableMetaData.primaryKeyField) ?? "Unknown"}
-                     <Box color={colors.gray.main} pb={"0.5rem"} fontSize={"0.875rem"} fontWeight="400" maxWidth="590px">
+                     <Box color={colors.gray.main} pb={"0.5rem"} fontSize={"0.875rem"} fontWeight="400">
                         {/* todo move to helpContent (what do we attach the meta-data too??) */}
                         Select a user or a group to share this record with.
-                        You can choose if they should only be able to Read the record, or also make Edits to it.
+                        {/*You can choose if they should only be able to Read the record, or also make Edits to it.*/}
                      </Box>
-                     <Box fontSize={14} maxWidth="590px" pb={1} fontWeight="300">
+                     <Box fontSize={14} pb={1} fontWeight="300">
                         {alert && <Alert color="error" onClose={() => setAlert(null)}>{alert}</Alert>}
                         {statusString}
                         {!alert && !statusString && (<>&nbsp;</>)}
@@ -390,19 +389,22 @@ export default function ShareModal({open, onClose, tableMetaData, record}: Share
                <Box pb={3} display="flex" flexDirection="column">
                   {/* row for adding a new share */}
                   <Box display="flex" flexDirection="row" alignItems="center">
-                     <Box width="350px" pr={2} mb={-1.5}>
+                     <Box width="550px" pr={2} mb={-1.5}>
                         <DynamicSelect
-                           possibleValueSourceName={shareableTableMetaData.audiencePossibleValueSourceName}
+                           fieldPossibleValueProps={{possibleValueSourceName: shareableTableMetaData.audiencePossibleValueSourceName, initialDisplayValue: selectedAudienceOption?.label}}
                            fieldLabel="User or Group" // todo should come from shareableTableMetaData
                            initialValue={selectedAudienceOption?.id}
-                           initialDisplayValue={selectedAudienceOption?.label}
                            inForm={false}
                            onChange={handleAudienceChange}
+                           useCase="form"
                         />
                      </Box>
-                     <Box width="180px" pr={2}>
-                        {renderScopeDropdown("new-share-scope", defaultScope, handleScopeChange)}
-                     </Box>
+                     {/*
+                        when turning scope back on, change width of audience box to 350px
+                        <Box width="180px" pr={2}>
+                           {renderScopeDropdown("new-share-scope", defaultScope, handleScopeChange)}
+                        </Box>
+                     */}
                      <Box>
                         <Tooltip title={selectedAudienceId == null ? "Select a user or group to share with." : null}>
                            <span>
@@ -429,8 +431,11 @@ export default function ShareModal({open, onClose, tableMetaData, record}: Share
                               currentShares.map((share) => (
                                  <Box key={share.shareId} display="flex" justifyContent="space-between" alignItems="center" p="0.25rem" pb="0.75rem" fontSize="1rem">
                                     <Box display="flex" alignItems="center">
-                                       <Box width="310px" pl="1rem">{share.audienceLabel}</Box>
-                                       <Box width="160px">{renderScopeDropdown(`scope-${share.shareId}`, getScopeOption(share.scopeId), (event: React.SyntheticEvent, value: any | any[], reason: string) => editingExistingShareScope(share.shareId, value))}</Box>
+                                       <Box width="490px" pl="1rem">{share.audienceLabel}</Box>
+                                       {/*
+                                          when turning scope back on, change width of audience box to 310px
+                                          <Box width="160px">{renderScopeDropdown(`scope-${share.shareId}`, getScopeOption(share.scopeId), (event: React.SyntheticEvent, value: any | any[], reason: string) => editingExistingShareScope(share.shareId, value))}</Box>
+                                       */}
                                     </Box>
                                     <Box pr="1rem">
                                        <Button sx={{...iconButtonSX, ...redIconButton}} onClick={() => removeShare(share.shareId)}><Icon>clear</Icon></Button>

src/qqq/components/widgets/CompositeWidget.tsx

@@ -22,16 +22,25 @@
 
 import {QWidgetMetaData} from "@kingsrook/qqq-frontend-core/lib/model/metaData/QWidgetMetaData";
 import {Box, Skeleton} from "@mui/material";
-import React from "react";
+import Card from "@mui/material/Card";
+import Modal from "@mui/material/Modal";
+import parse from "html-react-parser";
 import {BlockData} from "qqq/components/widgets/blocks/BlockModels";
 import WidgetBlock from "qqq/components/widgets/WidgetBlock";
+import ProcessWidgetBlockUtils from "qqq/pages/processes/ProcessWidgetBlockUtils";
+import React, {useEffect, useState} from "react";
 
 
-interface CompositeData
+export interface CompositeData
 {
+   blockId: string;
    blocks: BlockData[];
    styleOverrides?: any;
-   layout?: string
+   layout?: string;
+   overlayHtml?: string;
+   overlayStyleOverrides?: any;
+   modalMode: string;
+   styles?: any;
 }
 
 
@@ -39,13 +48,15 @@ interface CompositeWidgetProps
 {
    widgetMetaData: QWidgetMetaData;
    data: CompositeData;
+   actionCallback?: (blockData: BlockData, eventValues?: { [name: string]: any }) => boolean;
+   values?: { [key: string]: any };
 }
 
 
 /*******************************************************************************
  ** Widget which is a list of Blocks.
  *******************************************************************************/
-export default function CompositeWidget({widgetMetaData, data}: CompositeWidgetProps): JSX.Element
+export default function CompositeWidget({widgetMetaData, data, actionCallback, values}: CompositeWidgetProps): JSX.Element
 {
    if (!data || !data.blocks)
    {
@@ -57,20 +68,41 @@ export default function CompositeWidget({widgetMetaData, data}: CompositeWidgetP
    ////////////////////////////////////////////////////////////////////////////////////
    let layout = data?.layout;
    let boxStyle: any = {};
-   if (layout == "FLEX_ROW_WRAPPED")
+   if (layout == "FLEX_COLUMN")
+   {
+      boxStyle.display = "flex";
+      boxStyle.flexDirection = "column";
+      boxStyle.flexWrap = "wrap";
+      boxStyle.gap = "0.5rem";
+   }
+   else if (layout == "FLEX_ROW_WRAPPED")
    {
       boxStyle.display = "flex";
       boxStyle.flexDirection = "row";
       boxStyle.flexWrap = "wrap";
       boxStyle.gap = "0.5rem";
    }
+   else if (layout == "FLEX_ROW")
+   {
+      boxStyle.display = "flex";
+      boxStyle.flexDirection = "row";
+      boxStyle.gap = "0.5rem";
+   }
    else if (layout == "FLEX_ROW_SPACE_BETWEEN")
    {
       boxStyle.display = "flex";
       boxStyle.flexDirection = "row";
-      boxStyle.justifyContent = "space-between"
+      boxStyle.justifyContent = "space-between";
       boxStyle.gap = "0.25rem";
    }
+   else if (layout == "FLEX_ROW_CENTER")
+   {
+      boxStyle.display = "flex";
+      boxStyle.flexDirection = "row";
+      boxStyle.justifyContent = "center";
+      boxStyle.gap = "0.25rem";
+      boxStyle.flexWrap = "wrap";
+   }
    else if (layout == "TABLE_SUB_ROW_DETAILS")
    {
       boxStyle.display = "flex";
@@ -90,20 +122,96 @@ export default function CompositeWidget({widgetMetaData, data}: CompositeWidgetP
       boxStyle.borderRadius = "0.5rem";
       boxStyle.background = "#FFFFFF";
    }
-
    if (data?.styleOverrides)
    {
       boxStyle = {...boxStyle, ...data.styleOverrides};
    }
 
-   return (<Box sx={boxStyle} className="compositeWidget">
+   if (data.styles?.backgroundColor)
+   {
+      boxStyle.backgroundColor = ProcessWidgetBlockUtils.processColorFromStyleMap(data.styles.backgroundColor);
+   }
+
+   if (data.styles?.padding)
+   {
+      boxStyle.paddingTop = data.styles?.padding.top + "px"
+      boxStyle.paddingBottom = data.styles?.padding.bottom + "px"
+      boxStyle.paddingLeft = data.styles?.padding.left + "px"
+      boxStyle.paddingRight = data.styles?.padding.right + "px"
+   }
+
+   let overlayStyle: any = {};
+
+   if (data?.overlayStyleOverrides)
+   {
+      overlayStyle = {...overlayStyle, ...data.overlayStyleOverrides};
+   }
+
+   const content = (
+      <>
+         {
+            data?.overlayHtml &&
+            <Box sx={overlayStyle} className="blockWidgetOverlay">{parse(data.overlayHtml)}</Box>
+         }
+         <Box sx={boxStyle} className="compositeWidget">
+            {
+               data.blocks.map((block: BlockData, index) => (
+                  <React.Fragment key={index}>
+                     <WidgetBlock widgetMetaData={widgetMetaData} block={block} actionCallback={actionCallback} values={values} />
+                  </React.Fragment>
+               ))
+            }
+         </Box>
+      </>
+   );
+
+   if (data.modalMode)
+   {
+      const [isModalOpen, setIsModalOpen] = useState(values && (values[data.blockId] == true));
+
+      /***************************************************************************
+       **
+       ***************************************************************************/
+      const controlCallback = (newValue: boolean) =>
       {
-         data.blocks.map((block: BlockData, index) => (
-            <React.Fragment key={index}>
-               <WidgetBlock widgetMetaData={widgetMetaData} block={block} />
-            </React.Fragment>
-         ))
-      }
-   </Box>);
+         setIsModalOpen(newValue);
+      };
+
+      /***************************************************************************
+       **
+       ***************************************************************************/
+      const modalOnClose = (event: object, reason: string) =>
+      {
+         values[data.blockId] = false;
+         setIsModalOpen(false);
+         actionCallback({blockTypeName: "BUTTON", values: {}}, {controlCode: `hideModal:${data.blockId}`});
+      };
+
+      //////////////////////////////////////////////////////////////////////////////////////////
+      // register the control-callback function - so when buttons are clicked, we can be told //
+      //////////////////////////////////////////////////////////////////////////////////////////
+      useEffect(() =>
+      {
+         if (actionCallback)
+         {
+            actionCallback(null, {
+               registerControlCallbackName: data.blockId,
+               registerControlCallbackFunction: controlCallback
+            });
+         }
+      }, []);
+
+      return (<Modal open={isModalOpen} onClose={modalOnClose}>
+         <Box sx={{position: "absolute", overflowY: "auto", maxHeight: "100%", width: "100%"}}>
+            <Card sx={{my: 5, mx: "auto", p: "1rem", maxWidth: "1024px"}}>
+               {content}
+            </Card>
+         </Box>
+      </Modal>);
+   }
+   else
+   {
+      return content;
+   }
 
 }

src/qqq/components/widgets/DashboardWidgets.tsx

@@ -18,15 +18,18 @@
  * along with this program.  If not, see <https://www.gnu.org/licenses/>.
  */
 
+import {QTableMetaData} from "@kingsrook/qqq-frontend-core/lib/model/metaData/QTableMetaData";
 import {QWidgetMetaData} from "@kingsrook/qqq-frontend-core/lib/model/metaData/QWidgetMetaData";
 import {QRecord} from "@kingsrook/qqq-frontend-core/lib/model/QRecord";
 import {Alert, Skeleton} from "@mui/material";
 import Box from "@mui/material/Box";
 import Grid from "@mui/material/Grid";
+import Modal from "@mui/material/Modal";
 import Tab from "@mui/material/Tab";
 import Tabs from "@mui/material/Tabs";
 import parse from "html-react-parser";
 import QContext from "QContext";
+import EntityForm from "qqq/components/forms/EntityForm";
 import MDTypography from "qqq/components/legacy/MDTypography";
 import TabPanel from "qqq/components/misc/TabPanel";
 import BarChart from "qqq/components/widgets/charts/barchart/BarChart";
@@ -36,20 +39,22 @@ import SmallLineChart from "qqq/components/widgets/charts/linechart/SmallLineCha
 import PieChart from "qqq/components/widgets/charts/piechart/PieChart";
 import StackedBarChart from "qqq/components/widgets/charts/StackedBarChart";
 import CompositeWidget from "qqq/components/widgets/CompositeWidget";
+import CustomComponentWidget from "qqq/components/widgets/misc/CustomComponentWidget";
 import DataBagViewer from "qqq/components/widgets/misc/DataBagViewer";
 import DividerWidget from "qqq/components/widgets/misc/Divider";
+import DynamicFormWidget from "qqq/components/widgets/misc/DynamicFormWidget";
 import FieldValueListWidget from "qqq/components/widgets/misc/FieldValueListWidget";
+import FilterAndColumnsSetupWidget from "qqq/components/widgets/misc/FilterAndColumnsSetupWidget";
 import PivotTableSetupWidget from "qqq/components/widgets/misc/PivotTableSetupWidget";
 import QuickSightChart from "qqq/components/widgets/misc/QuickSightChart";
-import RecordGridWidget from "qqq/components/widgets/misc/RecordGridWidget";
-import ReportSetupWidget from "qqq/components/widgets/misc/ReportSetupWidget";
+import RecordGridWidget, {ChildRecordListData} from "qqq/components/widgets/misc/RecordGridWidget";
 import ScriptViewer from "qqq/components/widgets/misc/ScriptViewer";
 import StepperCard from "qqq/components/widgets/misc/StepperCard";
 import USMapWidget from "qqq/components/widgets/misc/USMapWidget";
 import ParentWidget from "qqq/components/widgets/ParentWidget";
 import MultiStatisticsCard from "qqq/components/widgets/statistics/MultiStatisticsCard";
 import StatisticsCard from "qqq/components/widgets/statistics/StatisticsCard";
-import Widget, {HeaderIcon, LabelComponent, WIDGET_DROPDOWN_SELECTION_LOCAL_STORAGE_KEY_ROOT} from "qqq/components/widgets/Widget";
+import Widget, {HeaderIcon, LabelComponent, WIDGET_DROPDOWN_SELECTION_LOCAL_STORAGE_KEY_ROOT, WidgetData} from "qqq/components/widgets/Widget";
 import WidgetBlock from "qqq/components/widgets/WidgetBlock";
 import ProcessRun from "qqq/pages/processes/ProcessRun";
 import Client from "qqq/utils/qqq/Client";
@@ -70,6 +75,9 @@ interface Props
    childUrlParams?: string;
    parentWidgetMetaData?: QWidgetMetaData;
    wrapWidgetsInTabPanels: boolean;
+   actionCallback?: (data: any, eventValues?: { [name: string]: any }) => boolean;
+   initialWidgetDataList: any[];
+   values?: { [key: string]: any };
 }
 
 DashboardWidgets.defaultProps = {
@@ -81,11 +89,14 @@ DashboardWidgets.defaultProps = {
    childUrlParams: "",
    parentWidgetMetaData: null,
    wrapWidgetsInTabPanels: false,
+   actionCallback: null,
+   initialWidgetDataList: null,
+   values: {}
 };
 
-function DashboardWidgets({widgetMetaDataList, tableName, entityPrimaryKey, record, omitWrappingGridContainer, areChildren, childUrlParams, parentWidgetMetaData, wrapWidgetsInTabPanels}: Props): JSX.Element
+function DashboardWidgets({widgetMetaDataList, tableName, entityPrimaryKey, record, omitWrappingGridContainer, areChildren, childUrlParams, parentWidgetMetaData, wrapWidgetsInTabPanels, actionCallback, initialWidgetDataList, values}: Props): JSX.Element
 {
-   const [widgetData, setWidgetData] = useState([] as any[]);
+   const [widgetData, setWidgetData] = useState(initialWidgetDataList == null ? [] as any[] : initialWidgetDataList);
    const [widgetCounter, setWidgetCounter] = useState(0);
    const [, forceUpdate] = useReducer((x) => x + 1, 0);
 
@@ -93,6 +104,11 @@ function DashboardWidgets({widgetMetaDataList, tableName, entityPrimaryKey, reco
    const [haveLoadedParams, setHaveLoadedParams] = useState(false);
    const {accentColor} = useContext(QContext);
 
+   /////////////////////////
+   // modal form controls //
+   /////////////////////////
+   const [showEditChildForm, setShowEditChildForm] = useState(null as any);
+
    let initialSelectedTab = 0;
    let selectedTabKey: string = null;
    if (parentWidgetMetaData && wrapWidgetsInTabPanels)
@@ -113,7 +129,15 @@ function DashboardWidgets({widgetMetaDataList, tableName, entityPrimaryKey, reco
 
    useEffect(() =>
    {
+      if (initialWidgetDataList && initialWidgetDataList.length > 0)
+      {
+         // todo actually, should this check each element of the array, down in the loop?  yeah, when we need to, do it that way.
+         console.log("We already have initial widget data, so not fetching from backend.");
+         return;
+      }
+
       setWidgetData([]);
+
       for (let i = 0; i < widgetMetaDataList.length; i++)
       {
          const widgetMetaData = widgetMetaDataList[i];
@@ -150,7 +174,7 @@ function DashboardWidgets({widgetMetaDataList, tableName, entityPrimaryKey, reco
 
    const reloadWidget = async (index: number, data: string) =>
    {
-      (async () =>
+      await (async () =>
       {
          const urlParams = getQueryParams(widgetMetaDataList[index], data);
          setCurrentUrlParams(urlParams);
@@ -257,11 +281,11 @@ function DashboardWidgets({widgetMetaDataList, tableName, entityPrimaryKey, reco
     ** helper function, to convert values from a QRecord values map to a regular old
     ** js object
     *******************************************************************************/
-   function convertQRecordValuesFromMapToObject(record: QRecord): {[name: string]: any}
+   function convertQRecordValuesFromMapToObject(record: QRecord): { [name: string]: any }
    {
-      const rs: {[name: string]: any} = {};
+      const rs: { [name: string]: any } = {};
 
-      if(record.values)
+      if (record && record.values)
       {
          record.values.forEach((value, key) => rs[key] = value);
       }
@@ -269,6 +293,151 @@ function DashboardWidgets({widgetMetaDataList, tableName, entityPrimaryKey, reco
       return (rs);
    }
 
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   const closeEditChildForm = (event: object, reason: string) =>
+   {
+      if (reason === "backdropClick" || reason === "escapeKeyDown")
+      {
+         return;
+      }
+
+      setShowEditChildForm(null);
+   };
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   function deleteChildRecord(name: string, widgetIndex: number, rowIndex: number)
+   {
+      updateChildRecordList(name, "delete", rowIndex);
+      forceUpdate();
+      actionCallback(widgetData[widgetIndex]);
+   };
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   function openEditChildRecord(name: string, widgetData: any, rowIndex: number)
+   {
+      let defaultValues = widgetData.queryOutput.records[rowIndex].values;
+
+      let disabledFields = widgetData.disabledFieldsForNewChildRecords;
+      if (!disabledFields)
+      {
+         disabledFields = widgetData.defaultValuesForNewChildRecords;
+      }
+
+      doOpenEditChildForm(name, widgetData.childTableMetaData, rowIndex, defaultValues, disabledFields);
+   }
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   function openAddChildRecord(name: string, widgetData: any)
+   {
+      let defaultValues = widgetData.defaultValuesForNewChildRecords;
+
+      let disabledFields = widgetData.disabledFieldsForNewChildRecords;
+      if (!disabledFields)
+      {
+         disabledFields = widgetData.defaultValuesForNewChildRecords;
+      }
+
+      doOpenEditChildForm(name, widgetData.childTableMetaData, null, defaultValues, disabledFields);
+   }
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   function doOpenEditChildForm(widgetName: string, table: QTableMetaData, rowIndex: number, defaultValues: any, disabledFields: any)
+   {
+      const showEditChildForm: any = {};
+      showEditChildForm.widgetName = widgetName;
+      showEditChildForm.table = table;
+      showEditChildForm.rowIndex = rowIndex;
+      showEditChildForm.defaultValues = defaultValues;
+      showEditChildForm.disabledFields = disabledFields;
+      setShowEditChildForm(showEditChildForm);
+   }
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   function submitEditChildForm(values: any, tableName: string)
+   {
+      updateChildRecordList(showEditChildForm.widgetName, showEditChildForm.rowIndex == null ? "insert" : "edit", showEditChildForm.rowIndex, values);
+      let widgetIndex = determineChildRecordListIndex(showEditChildForm.widgetName);
+      actionCallback(widgetData[widgetIndex]);
+   }
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   function determineChildRecordListIndex(widgetName: string): number
+   {
+      let widgetIndex = -1;
+      for (var i = 0; i < widgetMetaDataList.length; i++)
+      {
+         const widgetMetaData = widgetMetaDataList[i];
+         if (widgetMetaData.name == widgetName)
+         {
+            widgetIndex = i;
+            break;
+         }
+      }
+      return (widgetIndex);
+   }
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   function updateChildRecordList(widgetName: string, action: "insert" | "edit" | "delete", rowIndex?: number, values?: any)
+   {
+      ////////////////////////////////////////////////
+      // find the correct child record widget index //
+      ////////////////////////////////////////////////
+      let widgetIndex = determineChildRecordListIndex(widgetName);
+
+      if (!widgetData[widgetIndex].queryOutput.records)
+      {
+         widgetData[widgetIndex].queryOutput.records = [];
+      }
+
+      const newChildListWidgetData: ChildRecordListData = widgetData[widgetIndex];
+      if (!newChildListWidgetData.queryOutput.records)
+      {
+         newChildListWidgetData.queryOutput.records = [];
+      }
+
+      switch (action)
+      {
+         case "insert":
+            newChildListWidgetData.queryOutput.records.push({values: values});
+            break;
+         case "edit":
+            newChildListWidgetData.queryOutput.records[rowIndex] = {values: values};
+            break;
+         case "delete":
+            newChildListWidgetData.queryOutput.records.splice(rowIndex, 1);
+            break;
+      }
+      newChildListWidgetData.totalRows = newChildListWidgetData.queryOutput.records.length;
+      widgetData[widgetIndex] = newChildListWidgetData;
+      setWidgetData(widgetData);
+
+      setShowEditChildForm(null);
+   }
+
+
    const renderWidget = (widgetMetaData: QWidgetMetaData, i: number): JSX.Element =>
    {
       const labelAdditionalComponentsRight: LabelComponent[] = [];
@@ -292,7 +461,7 @@ function DashboardWidgets({widgetMetaDataList, tableName, entityPrimaryKey, reco
       }
 
       return (
-         <Box key={`${widgetMetaData.name}-${i}`} sx={{alignItems: "stretch", flexGrow: 1, display: "flex", marginTop: "0px", paddingTop: "0px", width: "100%", height: "100%"}}>
+         <Box key={`${widgetMetaData.name}-${i}`} sx={{alignItems: "stretch", flexGrow: 1, display: "flex", marginTop: "0px", paddingTop: "0px", width: "100%", height: "100%", flexDirection: widgetMetaData.type == "multiTable" ? "column" : "row"}}>
             {
                haveLoadedParams && widgetMetaData.type === "parentWidget" && (
                   <ParentWidget
@@ -308,7 +477,7 @@ function DashboardWidgets({widgetMetaDataList, tableName, entityPrimaryKey, reco
                )
             }
             {
-               widgetMetaData.type === "alert" && widgetData[i]?.html && (
+               widgetMetaData.type === "alert" && widgetData[i]?.html && !widgetData[i]?.hideWidget && (
                   <Widget
                      omitPadding={true}
                      widgetMetaData={widgetMetaData}
@@ -318,7 +487,16 @@ function DashboardWidgets({widgetMetaDataList, tableName, entityPrimaryKey, reco
                      labelAdditionalComponentsRight={labelAdditionalComponentsRight}
                      labelAdditionalComponentsLeft={labelAdditionalComponentsLeft}
                   >
-                     <Alert severity={widgetData[i]?.alertType?.toLowerCase()}>{parse(widgetData[i]?.html)}</Alert>
+                     <Alert severity={widgetData[i]?.alertType?.toLowerCase()}>
+                        {parse(widgetData[i]?.html)}
+                        {widgetData[i]?.bulletList && (
+                           <div style={{fontSize: "14px"}}>
+                              {widgetData[i].bulletList.map((bullet: string, index: number) =>
+                                 <li key={`widget-${i}-${index}`}>{parse(bullet)}</li>
+                              )}
+                           </div>
+                        )}
+                     </Alert>
                   </Widget>
                )
             }
@@ -342,6 +520,20 @@ function DashboardWidgets({widgetMetaDataList, tableName, entityPrimaryKey, reco
                   />
                )
             }
+            {
+               widgetMetaData.type === "multiTable" && (
+                  widgetData[i]?.tableDataList?.map((tableData: WidgetData, index: number) =>
+                     <Box pb={3} key={`${widgetMetaData.type}-${index}`}>
+                        <TableWidget
+                           widgetMetaData={widgetMetaData}
+                           widgetData={tableData}
+                           reloadWidgetCallback={(data) => reloadWidget(i, data)}
+                           isChild={areChildren}
+                        />
+                     </Box>
+                  )
+               )
+            }
             {
                widgetMetaData.type === "stackedBarChart" && (
                   <Widget
@@ -486,9 +678,7 @@ function DashboardWidgets({widgetMetaDataList, tableName, entityPrimaryKey, reco
             }
             {
                widgetMetaData.type === "divider" && (
-                  <Box>
-                     <DividerWidget />
-                  </Box>
+                  <DividerWidget />
                )
             }
             {
@@ -522,8 +712,15 @@ function DashboardWidgets({widgetMetaDataList, tableName, entityPrimaryKey, reco
                widgetMetaData.type === "childRecordList" && (
                   widgetData && widgetData[i] &&
                   <RecordGridWidget
+                     disableRowClick={widgetData[i]?.disableRowClick}
+                     allowRecordEdit={widgetData[i]?.allowRecordEdit}
+                     allowRecordDelete={widgetData[i]?.allowRecordDelete}
+                     deleteRecordCallback={(rowIndex) => deleteChildRecord(widgetMetaData.name, i, rowIndex)}
+                     editRecordCallback={(rowIndex) => openEditChildRecord(widgetMetaData.name, widgetData[i], rowIndex)}
+                     addNewRecordCallback={widgetData[i]?.isInProcess ? () => openAddChildRecord(widgetMetaData.name, widgetData[i]) : null}
                      widgetMetaData={widgetMetaData}
                      data={widgetData[i]}
+                     parentRecord={record}
                   />
                )
 
@@ -548,7 +745,7 @@ function DashboardWidgets({widgetMetaDataList, tableName, entityPrimaryKey, reco
                      labelAdditionalComponentsRight={labelAdditionalComponentsRight}
                      labelAdditionalComponentsLeft={labelAdditionalComponentsLeft}
                   >
-                     <CompositeWidget widgetMetaData={widgetMetaData} data={widgetData[i]} />
+                     <CompositeWidget widgetMetaData={widgetMetaData} data={widgetData[i]} actionCallback={actionCallback} values={values} />
                   </Widget>
                )
             }
@@ -583,17 +780,37 @@ function DashboardWidgets({widgetMetaDataList, tableName, entityPrimaryKey, reco
                )
             }
             {
-               widgetMetaData.type === "reportSetup" && (
-                  widgetData && widgetData[i] && widgetData[i].queryParams &&
-                  <ReportSetupWidget isEditable={false} widgetMetaData={widgetMetaData} recordValues={convertQRecordValuesFromMapToObject(record)} onSaveCallback={() =>
-                  {}} />
+               widgetMetaData.type === "filterAndColumnsSetup" && (
+                  widgetData && widgetData[i] &&
+                  <FilterAndColumnsSetupWidget isEditable={false} widgetMetaData={widgetMetaData} widgetData={widgetData[i]} recordValues={convertQRecordValuesFromMapToObject(record)} onSaveCallback={(values: { [name: string]: any }) =>
+                  {
+                     if(actionCallback)
+                     {
+                        actionCallback(values)
+                     }
+                  }} />
                )
             }
             {
                widgetMetaData.type === "pivotTableSetup" && (
                   widgetData && widgetData[i] && widgetData[i].queryParams &&
                   <PivotTableSetupWidget isEditable={false} widgetMetaData={widgetMetaData} recordValues={convertQRecordValuesFromMapToObject(record)} onSaveCallback={() =>
-                  {}} />
+                  {
+                  }} />
+               )
+            }
+            {
+               widgetMetaData.type === "dynamicForm" && (
+                  widgetData && widgetData[i] &&
+                  <DynamicFormWidget isEditable={false} widgetMetaData={widgetMetaData} widgetData={widgetData[i]} record={record} recordValues={convertQRecordValuesFromMapToObject(record)} />
+               )
+            }
+            {
+               widgetMetaData.type === "customComponent" && (
+                  widgetData && widgetData[i] &&
+                  <Widget widgetMetaData={widgetMetaData}>
+                     <CustomComponentWidget widgetMetaData={widgetMetaData} widgetData={widgetData[i]} record={record} />
+                  </Widget>
                )
             }
          </Box>
@@ -615,8 +832,28 @@ function DashboardWidgets({widgetMetaDataList, tableName, entityPrimaryKey, reco
 
                   if (!omitWrappingGridContainer)
                   {
-                     // @ts-ignore
-                     renderedWidget = (<Grid id={widgetMetaData.name} item xxl={widgetMetaData.gridColumns ? widgetMetaData.gridColumns : 12} xs={12} sx={{display: "flex", alignItems: "stretch", scrollMarginTop: "100px"}}>
+                     const gridProps: { [key: string]: any } = {};
+
+                     for (let size of ["xs", "sm", "md", "lg", "xl", "xxl"])
+                     {
+                        const key = `gridCols:sizeClass:${size}`;
+                        if (widgetMetaData?.defaultValues?.has(key))
+                        {
+                           gridProps[size] = widgetMetaData?.defaultValues.get(key);
+                        }
+                     }
+
+                     if (!gridProps["xxl"])
+                     {
+                        gridProps["xxl"] = widgetMetaData.gridColumns ? widgetMetaData.gridColumns : 12;
+                     }
+
+                     if (!gridProps["xs"])
+                     {
+                        gridProps["xs"] = 12;
+                     }
+
+                     renderedWidget = (<Grid id={widgetMetaData.name} item {...gridProps} sx={{display: "flex", alignItems: "stretch", scrollMarginTop: "100px"}}>
                         {renderedWidget}
                      </Grid>);
                   }
@@ -667,6 +904,22 @@ function DashboardWidgets({widgetMetaDataList, tableName, entityPrimaryKey, reco
                   </Grid>
                )
             }
+            {
+               showEditChildForm &&
+               <Modal open={showEditChildForm as boolean} onClose={(event, reason) => closeEditChildForm(event, reason)}>
+                  <div className="modalEditForm">
+                     <EntityForm
+                        isModal={true}
+                        closeModalHandler={closeEditChildForm}
+                        table={showEditChildForm.table}
+                        defaultValues={showEditChildForm.defaultValues}
+                        disabledFields={showEditChildForm.disabledFields}
+                        onSubmitCallback={submitEditChildForm}
+                        overrideHeading={`${showEditChildForm.rowIndex != null ? "Editing" : "Creating New"} ${showEditChildForm.table.label}`}
+                     />
+                  </div>
+               </Modal>
+            }
          </>
       ) : null
    );

src/qqq/components/widgets/Widget.tsx

@@ -21,8 +21,7 @@
 
 import {QTableMetaData} from "@kingsrook/qqq-frontend-core/lib/model/metaData/QTableMetaData";
 import {QWidgetMetaData} from "@kingsrook/qqq-frontend-core/lib/model/metaData/QWidgetMetaData";
-import {InputLabel} from "@mui/material";
-import Box from "@mui/material/Box";
+import {Box, InputLabel} from "@mui/material";
 import Button from "@mui/material/Button";
 import Card from "@mui/material/Card";
 import Icon from "@mui/material/Icon";
@@ -196,8 +195,6 @@ export function HeaderLinkButtonComponent({label, onClickCallback, disabled, dis
 }
 
 
-
-
 /*******************************************************************************
  **
  *******************************************************************************/
@@ -220,7 +217,7 @@ export function HeaderToggleComponent({label, getValue, onClickCallback, disable
    const onClick = () =>
    {
       onClickCallback();
-   }
+   };
 
    return (
       <Box alignItems="baseline" mr="-0.75rem">
@@ -236,7 +233,6 @@ export function HeaderToggleComponent({label, getValue, onClickCallback, disable
 }
 
 
-
 /*******************************************************************************
  **
  *******************************************************************************/
@@ -698,7 +694,7 @@ function Widget(props: React.PropsWithChildren<Props>): JSX.Element
    );
 
    let sublabelElement = (
-      <Box height="20px">
+      <Box key="sublabel" height="20px">
          <Typography sx={{position: "relative", top: "-18px"}} variant="caption">
             {props.widgetData?.sublabel}
          </Typography>
@@ -732,7 +728,7 @@ function Widget(props: React.PropsWithChildren<Props>): JSX.Element
       <Box sx={{width: "100%", height: "100%", minHeight: props.widgetMetaData?.minHeight ? props.widgetMetaData?.minHeight : "initial"}}>
          {
             needLabelBox &&
-            <Box display="flex" justifyContent="space-between" alignItems="flex-start" sx={{width: "100%", ...props.labelBoxAdditionalSx}} minHeight={"2.5rem"}>
+            <Box display="flex" justifyContent="space-between" alignItems="flex-start" sx={{width: "100%", ...props.labelBoxAdditionalSx}} minHeight={"2.5rem"} className="widgetLabelBox">
                <Box display="flex" flexDirection="column">
                   <Box display="flex" alignItems="baseline">
                      {
@@ -785,7 +781,7 @@ function Widget(props: React.PropsWithChildren<Props>): JSX.Element
                      }
                      {localLabelAdditionalElementsLeft}
                   </Box>
-                  <Box display="flex">
+                  <Box key="sublabelContainer" display="flex">
                      {
                         hasPermission && props.widgetData?.sublabel && (sublabelElement)
                      }

src/qqq/components/widgets/WidgetBlock.tsx

@@ -22,6 +22,9 @@
 
 import {QWidgetMetaData} from "@kingsrook/qqq-frontend-core/lib/model/metaData/QWidgetMetaData";
 import {Alert, Skeleton} from "@mui/material";
+import ButtonBlock from "qqq/components/widgets/blocks/ButtonBlock";
+import AudioBlock from "qqq/components/widgets/blocks/AudioBlock";
+import InputFieldBlock from "qqq/components/widgets/blocks/InputFieldBlock";
 import React from "react";
 import BigNumberBlock from "qqq/components/widgets/blocks/BigNumberBlock";
 import {BlockData} from "qqq/components/widgets/blocks/BlockModels";
@@ -32,19 +35,22 @@ import TableSubRowDetailRowBlock from "qqq/components/widgets/blocks/TableSubRow
 import TextBlock from "qqq/components/widgets/blocks/TextBlock";
 import UpOrDownNumberBlock from "qqq/components/widgets/blocks/UpOrDownNumberBlock";
 import CompositeWidget from "qqq/components/widgets/CompositeWidget";
+import ImageBlock from "./blocks/ImageBlock";
 
 
 interface WidgetBlockProps
 {
    widgetMetaData: QWidgetMetaData;
    block: BlockData;
+   actionCallback?: (blockData: BlockData, eventValues?: {[name: string]: any}) => boolean;
+   values?: { [key: string]: any };
 }
 
 
 /*******************************************************************************
  ** Component to render a single Block in the widget framework!
  *******************************************************************************/
-export default function WidgetBlock({widgetMetaData, block}: WidgetBlockProps): JSX.Element
+export default function WidgetBlock({widgetMetaData, block, actionCallback, values}: WidgetBlockProps): JSX.Element
 {
    if(!block)
    {
@@ -64,7 +70,7 @@ export default function WidgetBlock({widgetMetaData, block}: WidgetBlockProps):
    if(block.blockTypeName == "COMPOSITE")
    {
       // @ts-ignore - special case for composite type block...
-      return (<CompositeWidget widgetMetaData={widgetMetaData} data={block} />);
+      return (<CompositeWidget widgetMetaData={widgetMetaData} data={block} actionCallback={actionCallback} values={values} />);
    }
 
    switch(block.blockTypeName)
@@ -83,6 +89,14 @@ export default function WidgetBlock({widgetMetaData, block}: WidgetBlockProps):
          return (<DividerBlock widgetMetaData={widgetMetaData} data={block} />);
       case "BIG_NUMBER":
          return (<BigNumberBlock widgetMetaData={widgetMetaData} data={block} />);
+      case "INPUT_FIELD":
+         return (<InputFieldBlock widgetMetaData={widgetMetaData} data={block} actionCallback={actionCallback} />);
+      case "BUTTON":
+         return (<ButtonBlock widgetMetaData={widgetMetaData} data={block} actionCallback={actionCallback} />);
+      case "AUDIO":
+         return (<AudioBlock widgetMetaData={widgetMetaData} data={block} />);
+      case "IMAGE":
+         return (<ImageBlock widgetMetaData={widgetMetaData} data={block} actionCallback={actionCallback} />);
       default:
          return (<Alert sx={{m: "0.5rem"}} color="warning">Unsupported block type: {block.blockTypeName}</Alert>)
    }

src/qqq/components/widgets/WidgetUtils.tsx

@@ -21,14 +21,16 @@
 
 
 import {QWidgetMetaData} from "@kingsrook/qqq-frontend-core/lib/model/metaData/QWidgetMetaData";
+import Box from "@mui/material/Box";
 import Button from "@mui/material/Button";
 import Icon from "@mui/material/Icon";
 import Tooltip from "@mui/material/Tooltip/Tooltip";
 import Typography from "@mui/material/Typography";
-import React from "react";
 import colors from "qqq/assets/theme/base/colors";
 import {WidgetData} from "qqq/components/widgets/Widget";
 import ValueUtils from "qqq/utils/qqq/ValueUtils";
+import React from "react";
+import {Link} from "react-router-dom";
 
 /*******************************************************************************
  ** Utility class used by Widgets
@@ -51,6 +53,17 @@ export class WidgetUtils
    };
 
 
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public static generateLabelLink = (linkText: string, linkURL: string): JSX.Element =>
+   {
+      return (<Box key={1} fontSize="1rem" pl={1} display="inline" position="relative">
+         (<Link to={linkURL}>{linkText}</Link>)
+      </Box>);
+   };
+
+
    /*******************************************************************************
     **
     *******************************************************************************/
@@ -97,4 +110,4 @@ export class WidgetUtils
       return (fileName);
    };
 
-}
+}

src/qqq/components/widgets/blocks/AudioBlock.tsx

@@ -0,0 +1,40 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2024.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+import Box from "@mui/material/Box";
+import BlockElementWrapper from "qqq/components/widgets/blocks/BlockElementWrapper";
+import {StandardBlockComponentProps} from "qqq/components/widgets/blocks/BlockModels";
+import DumpJsonBox from "qqq/utils/DumpJsonBox";
+import React from "react";
+
+/*******************************************************************************
+ ** Block that renders ... an audio tag
+ **
+ ** <audio src=${path} ${autoPlay} ${showControls} />
+ *******************************************************************************/
+export default function AudioBlock({widgetMetaData, data}: StandardBlockComponentProps): JSX.Element
+{
+   return (
+      <BlockElementWrapper metaData={widgetMetaData} data={data} slot="">
+         <audio src={data.values?.path} autoPlay={data.values?.autoPlay} controls={data.values?.showControls} />
+      </BlockElementWrapper>
+   );
+}

src/qqq/components/widgets/blocks/BlockElementWrapper.tsx

@@ -21,18 +21,19 @@
 
 
 import {QWidgetMetaData} from "@kingsrook/qqq-frontend-core/lib/model/metaData/QWidgetMetaData";
-import {Tooltip} from "@mui/material";
-import React, {ReactElement, useContext} from "react";
-import {Link} from "react-router-dom";
+import {Box, Tooltip} from "@mui/material";
 import QContext from "QContext";
 import HelpContent, {hasHelpContent} from "qqq/components/misc/HelpContent";
 import {BlockData, BlockLink, BlockTooltip} from "qqq/components/widgets/blocks/BlockModels";
+import CompositeWidget from "qqq/components/widgets/CompositeWidget";
+import React, {ReactElement, useContext} from "react";
+import {Link} from "react-router-dom";
 
 interface BlockElementWrapperProps
 {
    data: BlockData;
    metaData: QWidgetMetaData;
-   slot: string
+   slot: string;
    linkProps?: any;
    children: ReactElement;
 }
@@ -47,16 +48,16 @@ export default function BlockElementWrapper({data, metaData, slot, linkProps, ch
    let link: BlockLink;
    let tooltip: BlockTooltip;
 
-   if(slot)
+   if (slot)
    {
       link = data.linkMap && data.linkMap[slot.toUpperCase()];
-      if(!link)
+      if (!link)
       {
          link = data.link;
       }
 
       tooltip = data.tooltipMap && data.tooltipMap[slot.toUpperCase()];
-      if(!tooltip)
+      if (!tooltip)
       {
          tooltip = data.tooltip;
       }
@@ -67,9 +68,9 @@ export default function BlockElementWrapper({data, metaData, slot, linkProps, ch
       tooltip = data.tooltip;
    }
 
-   if(!tooltip)
+   if (!tooltip)
    {
-      const helpRoles = ["ALL_SCREENS"]
+      const helpRoles = ["ALL_SCREENS"];
 
       ///////////////////////////////////////////////////////////////////////////////////////////////
       // the full keys in the helpContent table will look like:                                    //
@@ -80,26 +81,39 @@ export default function BlockElementWrapper({data, metaData, slot, linkProps, ch
       const key = data.blockId ? `${data.blockId},${slot}` : slot;
       const showHelp = helpHelpActive || hasHelpContent(metaData?.helpContent?.get(key), helpRoles);
 
-      if(showHelp)
+      if (showHelp)
       {
          const formattedHelpContent = <HelpContent helpContents={metaData?.helpContent?.get(key)} roles={helpRoles} helpContentKey={`widget:${metaData?.name};slot:${key}`} />;
-         tooltip = {title: formattedHelpContent, placement: "bottom"}
+         tooltip = {title: formattedHelpContent, placement: "bottom"};
       }
    }
 
    let rs = children;
 
-   if(link)
+   if (link && link.href)
    {
-      rs = <Link to={link.href} target={link.target} style={{color: "#546E7A"}} {...linkProps}>{rs}</Link>
+      rs = <Link to={link.href} target={link.target} style={{color: "#546E7A"}} {...linkProps}>{rs}</Link>;
    }
 
-   if(tooltip)
+   if (tooltip)
    {
-      let placement = tooltip.placement ? tooltip.placement.toLowerCase() : "bottom"
+      let placement = tooltip.placement ? tooltip.placement.toLowerCase() : "bottom";
 
       // @ts-ignore - placement possible values
-      rs = <Tooltip title={tooltip.title} placement={placement}>{rs}</Tooltip>
+      if (tooltip.blockData)
+      {
+         // @ts-ignore - special case for composite type block...
+         rs = <Tooltip title={
+            <Box sx={{width: "200px"}}>
+               <CompositeWidget widgetMetaData={metaData} data={tooltip?.blockData} />
+            </Box>
+         }>{rs}</Tooltip>;
+      }
+      else
+      {
+         // @ts-ignore - placement possible values
+         rs = <Tooltip title={tooltip.title} placement={placement}>{rs}</Tooltip>;
+      }
    }
 
    return (rs);

src/qqq/components/widgets/blocks/BlockModels.ts

@@ -20,6 +20,7 @@
  */
 
 import {QWidgetMetaData} from "@kingsrook/qqq-frontend-core/lib/model/metaData/QWidgetMetaData";
+import {CompositeData} from "qqq/components/widgets/CompositeWidget";
 
 
 export interface BlockData
@@ -29,16 +30,19 @@ export interface BlockData
 
    tooltip?: BlockTooltip;
    link?: BlockLink;
-   tooltipMap?: {[slot: string]: BlockTooltip};
-   linkMap?: {[slot: string]: BlockLink};
+   tooltipMap?: { [slot: string]: BlockTooltip };
+   linkMap?: { [slot: string]: BlockLink };
 
    values: any;
    styles?: any;
+
+   conditional?: string;
 }
 
 
 export interface BlockTooltip
 {
+   blockData?: CompositeData;
    title: string | JSX.Element;
    placement: string;
 }
@@ -55,5 +59,6 @@ export interface StandardBlockComponentProps
 {
    widgetMetaData: QWidgetMetaData;
    data: BlockData;
+   actionCallback?: (blockData: BlockData, eventValues?: {[name: string]: any}) => boolean;
 }
 

src/qqq/components/widgets/blocks/ButtonBlock.tsx

@@ -0,0 +1,86 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2024.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+import Box from "@mui/material/Box";
+import Icon from "@mui/material/Icon";
+import {standardWidth} from "qqq/components/buttons/DefaultButtons";
+import MDButton from "qqq/components/legacy/MDButton";
+import BlockElementWrapper from "qqq/components/widgets/blocks/BlockElementWrapper";
+import {StandardBlockComponentProps} from "qqq/components/widgets/blocks/BlockModels";
+import React from "react";
+
+
+/*******************************************************************************
+ ** Block that renders ... a button...
+ **
+ *******************************************************************************/
+export default function ButtonBlock({widgetMetaData, data, actionCallback}: StandardBlockComponentProps): JSX.Element
+{
+   const startIcon = data.values.startIcon?.name ? <Icon>{data.values.startIcon.name}</Icon> : null;
+   const endIcon = data.values.endIcon?.name ? <Icon>{data.values.endIcon.name}</Icon> : null;
+
+   function onClick()
+   {
+      if (actionCallback)
+      {
+         actionCallback(data, data.values);
+      }
+      else
+      {
+         console.log("ButtonBlock onClick with no actionCallback present, so, noop");
+      }
+   }
+
+   let buttonVariant: "gradient" | "outlined" | "text" = "gradient";
+   if (data.styles?.format == "outlined")
+   {
+      buttonVariant = "outlined";
+   }
+   else if (data.styles?.format == "text")
+   {
+      buttonVariant = "text";
+   }
+   else if (data.styles?.format == "filled")
+   {
+      buttonVariant = "gradient";
+   }
+
+   // todo - button colors... but to do RGB's, might need to move away from MDButton?
+
+   return (
+      <BlockElementWrapper metaData={widgetMetaData} data={data} slot="">
+         <Box mx={1} my={1} minWidth={standardWidth}>
+            <MDButton
+               type="button"
+               variant={buttonVariant}
+               color="dark"
+               size="small"
+               fullWidth
+               startIcon={startIcon}
+               endIcon={endIcon}
+               onClick={onClick}
+            >
+               {data.values.label ?? "Button"}
+            </MDButton>
+         </Box>
+      </BlockElementWrapper>
+   );
+}

src/qqq/components/widgets/blocks/ImageBlock.tsx

@@ -0,0 +1,59 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2024.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+import Box from "@mui/material/Box";
+import BlockElementWrapper from "qqq/components/widgets/blocks/BlockElementWrapper";
+import {StandardBlockComponentProps} from "qqq/components/widgets/blocks/BlockModels";
+import DumpJsonBox from "qqq/utils/DumpJsonBox";
+import React from "react";
+
+/*******************************************************************************
+ ** Block that renders ... an image tag
+ **
+ ** <audio src=${path} ${autoPlay} ${showControls} />
+ *******************************************************************************/
+export default function AudioBlock({widgetMetaData, data}: StandardBlockComponentProps): JSX.Element
+{
+   let imageStyle: any = {};
+
+   if(data.styles?.width)
+   {
+      imageStyle.width = data.styles?.width;
+   }
+
+   if(data.styles?.height)
+   {
+      imageStyle.height = data.styles?.height;
+   }
+
+   if(data.styles?.bordered)
+   {
+      imageStyle.border = "1px solid #C0C0C0";
+      imageStyle.borderRadius = "0.5rem";
+   }
+
+
+   return (
+      <BlockElementWrapper metaData={widgetMetaData} data={data} slot="">
+         <img src={data.values?.path} alt={data.values?.alt} style={imageStyle} />
+      </BlockElementWrapper>
+   );
+}

src/qqq/components/widgets/blocks/InputFieldBlock.tsx

@@ -0,0 +1,139 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2024.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+import {QFieldMetaData} from "@kingsrook/qqq-frontend-core/lib/model/metaData/QFieldMetaData";
+import Box from "@mui/material/Box";
+import QDynamicFormField from "qqq/components/forms/DynamicFormField";
+import DynamicFormUtils from "qqq/components/forms/DynamicFormUtils";
+import BlockElementWrapper from "qqq/components/widgets/blocks/BlockElementWrapper";
+import {StandardBlockComponentProps} from "qqq/components/widgets/blocks/BlockModels";
+import React, {SyntheticEvent, useState} from "react";
+
+/*******************************************************************************
+ ** Block that renders ... a text input
+ **
+ *******************************************************************************/
+export default function InputFieldBlock({widgetMetaData, data, actionCallback}: StandardBlockComponentProps): JSX.Element
+{
+   const [blurCount, setBlurCount] = useState(0)
+
+   const fieldMetaData = new QFieldMetaData(data.values.fieldMetaData);
+   const dynamicField = DynamicFormUtils.getDynamicField(fieldMetaData);
+
+   let autoFocus = data.values.autoFocus as boolean
+   let value = data.values.value;
+   if(value == null || value == undefined)
+   {
+      value = "";
+   }
+
+   ////////////////////////////////////////////////////////////////////////////////
+   // for an autoFocus field...                                                  //
+   // we're finding that if we blur it when clicking an action button, that      //
+   // an un-desirable "now it's been touched, so show an error" happens.         //
+   // so let us remove the default blur handler, for the first (auto) focus/blur //
+   // cycle, and we seem to have a better time.                                  //
+   ////////////////////////////////////////////////////////////////////////////////
+   let dynamicFormFieldRest: {onBlur?: any, sx?: any} = {}
+   if(autoFocus && blurCount == 0)
+   {
+      dynamicFormFieldRest.onBlur = (event: React.SyntheticEvent) =>
+      {
+         event.stopPropagation();
+         event.preventDefault();
+         setBlurCount(blurCount + 1);
+      }
+   }
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   function eventHandler(event: KeyboardEvent)
+   {
+      if(data.values.submitOnEnter && event.key == "Enter")
+      {
+         // @ts-ignore target.value...
+         const inputValue = event.target.value?.trim()
+
+         // todo - make this behavior opt-in for inputBlocks?
+         if(inputValue && `${inputValue}`.startsWith("->"))
+         {
+            const actionCode = inputValue.substring(2);
+            if(actionCallback)
+            {
+               actionCallback(data, {actionCode: actionCode, _fieldToClearIfError: fieldMetaData.name});
+
+               ///////////////////////////////////////////////////////
+               // return, so we don't submit the actionCode as text //
+               ///////////////////////////////////////////////////////
+               return;
+            }
+         }
+
+         if(fieldMetaData.isRequired && inputValue == "")
+         {
+            console.log("input field is required, but missing value, so not submitting");
+            return;
+         }
+
+         if(actionCallback)
+         {
+            console.log("InputFieldBlock calling actionCallback for submitOnEnter");
+
+            let values: {[name: string]: any} = {};
+            values[fieldMetaData.name] = inputValue;
+
+            actionCallback(data, values);
+         }
+         else
+         {
+            console.log("InputFieldBlock was set as submitOnEnter, but no actionCallback was present, so, noop");
+         }
+      }
+   }
+
+   const labelElement = <Box fontSize="1rem" fontWeight="500" marginBottom="0.25rem">
+      <label htmlFor={fieldMetaData.name}>{fieldMetaData.label}</label>
+   </Box>
+
+   return (
+      <Box mt="0.5rem">
+         <BlockElementWrapper metaData={widgetMetaData} data={data} slot="">
+            <>
+               {labelElement}
+               <QDynamicFormField
+                  name={fieldMetaData.name}
+                  displayFormat={null}
+                  label=""
+                  placeholder={data.values?.placeholder}
+                  backgroundColor="#FFFFFF"
+                  formFieldObject={dynamicField}
+                  type={fieldMetaData.type}
+                  value={value}
+                  autoFocus={autoFocus}
+                  onKeyUp={eventHandler}
+                  {...dynamicFormFieldRest} />
+            </>
+         </BlockElementWrapper>
+      </Box>
+   );
+}

src/qqq/components/widgets/blocks/NumberIconBadgeBlock.tsx

@@ -41,7 +41,7 @@ export default function NumberIconBadgeBlock({widgetMetaData, data}: StandardBlo
          {
             data.values.iconName &&
             <BlockElementWrapper metaData={widgetMetaData} data={data} slot="icon">
-               <Icon style={{color: data.styles.color, fontSize: "1rem", position: "relative", top: "3px"}}>{data.values.iconName}</Icon>
+               <Icon style={{color: data.styles.color, fontSize: "1rem", marginLeft: "2px", position: "relative", top: "4px"}}>{data.values.iconName}</Icon>
             </BlockElementWrapper>
          }
       </div>);

src/qqq/components/widgets/blocks/TextBlock.tsx

@@ -19,8 +19,12 @@
  * along with this program.  If not, see <https://www.gnu.org/licenses/>.
  */
 
+import Box from "@mui/material/Box";
+import Icon from "@mui/material/Icon";
 import BlockElementWrapper from "qqq/components/widgets/blocks/BlockElementWrapper";
 import {StandardBlockComponentProps} from "qqq/components/widgets/blocks/BlockModels";
+import ProcessWidgetBlockUtils from "qqq/pages/processes/ProcessWidgetBlockUtils";
+import React from "react";
 
 /*******************************************************************************
  ** Block that renders ... just some text.
@@ -29,9 +33,132 @@ import {StandardBlockComponentProps} from "qqq/components/widgets/blocks/BlockMo
  *******************************************************************************/
 export default function TextBlock({widgetMetaData, data}: StandardBlockComponentProps): JSX.Element
 {
+   let color = "rgba(0, 0, 0, 0.87)";
+   if (data.styles?.color)
+   {
+      color = ProcessWidgetBlockUtils.processColorFromStyleMap(data.styles.color);
+   }
+
+   let boxStyle = {};
+   if (data.styles?.format == "alert")
+   {
+      boxStyle =
+         {
+            border: `1px solid ${color}`,
+            background: `${color}40`,
+            padding: "0.5rem",
+            borderRadius: "0.5rem",
+         };
+   }
+   else if (data.styles?.format == "banner")
+   {
+      boxStyle =
+         {
+            background: `${color}40`,
+            padding: "0.5rem",
+         };
+   }
+
+   let fontSize = "1rem";
+   if (data.styles?.size)
+   {
+      switch (data.styles.size.toLowerCase())
+      {
+         case "largest":
+            fontSize = "3rem";
+            break;
+         case "headline":
+            fontSize = "2rem";
+            break;
+         case "title":
+            fontSize = "1.5rem";
+            break;
+         case "body":
+            fontSize = "1rem";
+            break;
+         case "smallest":
+            fontSize = "0.75rem";
+            break;
+         default:
+         {
+            if (data.styles.size.match(/^\d+$/))
+            {
+               fontSize = `${data.styles.size}px`;
+            }
+            else
+            {
+               fontSize = "1rem";
+            }
+         }
+      }
+   }
+
+   let fontWeight = "400";
+   if (data.styles?.weight)
+   {
+      switch (data.styles.weight.toLowerCase())
+      {
+         case "thin":
+         case "100":
+            fontWeight = "100";
+            break;
+         case "extralight":
+         case "200":
+            fontWeight = "200";
+            break;
+         case "light":
+         case "300":
+            fontWeight = "300";
+            break;
+         case "normal":
+         case "400":
+            fontWeight = "400";
+            break;
+         case "medium":
+         case "500":
+            fontWeight = "500";
+            break;
+         case "semibold":
+         case "600":
+            fontWeight = "600";
+            break;
+         case "bold":
+         case "700":
+            fontWeight = "700";
+            break;
+         case "extrabold":
+         case "800":
+            fontWeight = "800";
+            break;
+         case "black":
+         case "900":
+            fontWeight = "900";
+            break;
+      }
+   }
+
+   const text = data.values.interpolatedText ?? data.values.text;
+   const lines = text.split("\n");
+
+   const startIcon = data.values.startIcon?.name ? <Icon>{data.values.startIcon.name}</Icon> : null;
+   const endIcon = data.values.endIcon?.name ? <Icon>{data.values.endIcon.name}</Icon> : null;
+
    return (
       <BlockElementWrapper metaData={widgetMetaData} data={data} slot="">
-         <span style={{fontSize: "1.000rem"}}>{data.values.text}</span>
+         <Box display="inline-block" lineHeight="1.2" sx={boxStyle}>
+            <span style={{fontSize: fontSize, color: color, fontWeight: fontWeight}}>
+               {lines.map((line: string, index: number) =>
+                  (
+                     <div key={index}>
+                        <>
+                           {index == 0 && startIcon ? {startIcon} : null}
+                           {line}
+                           {index == lines.length - 1 && endIcon ? {endIcon} : null}
+                        </>
+                     </div>
+                  ))
+               }</span>
+         </Box>
       </BlockElementWrapper>
    );
 }

src/qqq/components/widgets/blocks/UpOrDownNumberBlock.tsx

@@ -58,7 +58,7 @@ export default function UpOrDownNumberBlock({widgetMetaData, data}: StandardBloc
 
    return (
       <>
-         <div style={{display: "flex", flexDirection: data.styles.isStacked ? "column" : "row", alignItems: data.styles.isStacked ? "flex-end" : "baseline"}}>
+         <div style={{display: "flex", flexDirection: data.styles.isStacked ? "column" : "row", alignItems: data.styles.isStacked ? "flex-end" : "baseline", marginLeft: "auto"}}>
 
             <div style={{display: "flex", alignItems: "baseline", fontWeight: 700, fontSize: ".875rem"}}>
                <BlockElementWrapper metaData={widgetMetaData} data={data} slot="number">

src/qqq/components/widgets/misc/CustomComponentWidget.tsx

@@ -0,0 +1,69 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2024.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+
+import {QWidgetMetaData} from "@kingsrook/qqq-frontend-core/lib/model/metaData/QWidgetMetaData";
+import {QRecord} from "@kingsrook/qqq-frontend-core/lib/model/QRecord";
+import {Skeleton} from "@mui/material";
+import Box from "@mui/material/Box";
+import useDynamicComponents from "qqq/utils/qqq/useDynamicComponents";
+import {useEffect, useState} from "react";
+
+
+interface CustomComponentWidgetProps
+{
+   widgetMetaData: QWidgetMetaData;
+   widgetData: any;
+   record: QRecord;
+}
+
+
+CustomComponentWidget.defaultProps = {
+};
+
+
+/*******************************************************************************
+ ** Component to display a custom component - one dynamically loaded.
+ *******************************************************************************/
+export default function CustomComponentWidget({widgetMetaData, widgetData, record}: CustomComponentWidgetProps): JSX.Element
+{
+   const [componentName, setComponentName] = useState(widgetMetaData.defaultValues.get("componentName"));
+   const [componentSourceUrl, setComponentSourceUrl] = useState(widgetMetaData.defaultValues.get("componentSourceUrl"));
+
+   const {loadComponent, hasComponentLoaded, renderComponent} = useDynamicComponents();
+
+   useEffect(() =>
+   {
+      loadComponent(componentName, componentSourceUrl);
+   }, []);
+
+   const props: any =
+      {
+         widgetMetaData: widgetMetaData,
+         widgetData: widgetData,
+         record: record,
+      }
+
+   return (<Box sx={widgetMetaData.defaultValues?.get("sx")}>
+      {hasComponentLoaded(componentName) ? renderComponent(componentName, props) : <Skeleton width="100%" height="100%" />}
+   </Box>);
+}
+

src/qqq/components/widgets/misc/DataBagViewer.tsx

@@ -50,6 +50,7 @@ import DeveloperModeUtils from "qqq/utils/DeveloperModeUtils";
 import Client from "qqq/utils/qqq/Client";
 import ValueUtils from "qqq/utils/qqq/ValueUtils";
 
+import "ace-builds/src-noconflict/ace";
 import "ace-builds/src-noconflict/mode-java";
 import "ace-builds/src-noconflict/mode-javascript";
 import "ace-builds/src-noconflict/mode-json";

src/qqq/components/widgets/misc/Divider.tsx

@@ -19,13 +19,16 @@
  * along with this program.  If not, see <https://www.gnu.org/licenses/>.
  */
 
+import Box from "@mui/material/Box";
 import Divider from "@mui/material/Divider";
 
 
 function DividerWidget(): JSX.Element
 {
    return (
-      <Divider sx={{padding: "1px", background: "red"}}/>
+      <Box pl={3} pt={3} pb={3} width="100%">
+         <Divider sx={{width: "100%", height: "1px", background: "grey"}} />
+      </Box>
    );
 }
 

src/qqq/components/widgets/misc/DynamicFormWidget.tsx

@@ -0,0 +1,265 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2024.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+
+import {QFieldMetaData} from "@kingsrook/qqq-frontend-core/lib/model/metaData/QFieldMetaData";
+import {QWidgetMetaData} from "@kingsrook/qqq-frontend-core/lib/model/metaData/QWidgetMetaData";
+import {QRecord} from "@kingsrook/qqq-frontend-core/lib/model/QRecord";
+import Box from "@mui/material/Box";
+import {FormikContextType, useFormikContext} from "formik";
+import QDynamicForm from "qqq/components/forms/DynamicForm";
+import DynamicFormUtils from "qqq/components/forms/DynamicFormUtils";
+import Widget from "qqq/components/widgets/Widget";
+import {renderSectionOfFields} from "qqq/pages/records/view/RecordView";
+import Client from "qqq/utils/qqq/Client";
+import React, {useEffect, useState} from "react";
+
+
+/*******************************************************************************
+ ** component props
+ *******************************************************************************/
+interface DynamicFormWidgetProps
+{
+   isEditable: boolean;
+   widgetMetaData: QWidgetMetaData;
+   widgetData: any;
+   record: QRecord;
+   recordValues: { [name: string]: any };
+   onSaveCallback?: (values: { [name: string]: any }) => void;
+}
+
+
+/*******************************************************************************
+ ** default values for props
+ *******************************************************************************/
+DynamicFormWidget.defaultProps = {
+   onSaveCallback: null
+};
+
+
+/*******************************************************************************
+ ** Component to display a dynamic form - e.g., on a record edit or view screen,
+ ** or even within a process.
+ *******************************************************************************/
+export default function DynamicFormWidget({isEditable, widgetMetaData, widgetData, record, recordValues, onSaveCallback}: DynamicFormWidgetProps): JSX.Element
+{
+   const [fields, setFields] = useState([] as QFieldMetaData[]);
+
+   const [effectiveIsEditable, setEffectiveIsEditable] = useState(isEditable);
+   if(widgetMetaData.defaultValues.has("isEditable"))
+   {
+      const defaultIsEditableValue = widgetMetaData.defaultValues.get("isEditable")
+      if(defaultIsEditableValue != effectiveIsEditable)
+      {
+         setEffectiveIsEditable(defaultIsEditableValue);
+      }
+   }
+
+   const [dynamicFormFields, setDynamicFormFields] = useState(null as any);
+   const [formValidations, setFormValidations] = useState(null as any);
+
+   const [lastKnowFormValues, setLastKnowFormValues] = useState({} as {[name: string]: any});
+
+
+   //////////////////////////////////////////////////////////////////////////////////////////
+   // on initial load, and any time widgetData changes (e.g., if widget gets re-rendered), //
+   // figure out what our form fields are                                                  //
+   //////////////////////////////////////////////////////////////////////////////////////////
+   useEffect(() =>
+   {
+      setDynamicFormFields({})
+      setFormValidations({})
+
+      if(widgetData && widgetData.fieldList)
+      {
+         const newFields: QFieldMetaData[] = [];
+         for (let i = 0; i < widgetData.fieldList.length; i++)
+         {
+            newFields.push(new QFieldMetaData(widgetData.fieldList[i]));
+         }
+         setFields(newFields);
+
+         if(newFields.length > 0)
+         {
+            const recordOfFieldValues = widgetData.recordOfFieldValues ? new QRecord(widgetData.recordOfFieldValues) : null;
+            const {dynamicFormFields: newDynamicFormFields, formValidations: newFormValidations} = DynamicFormUtils.getFormData(newFields);
+            const defaultDisplayValues = new Map<string,string>(); // todo - seems not right?
+            DynamicFormUtils.addPossibleValueProps(newDynamicFormFields, newFields, recordValues.tableName, null, recordOfFieldValues ? recordOfFieldValues.displayValues : defaultDisplayValues);
+            setDynamicFormFields(newDynamicFormFields)
+            setFormValidations(newFormValidations)
+         }
+
+         setLastKnowFormValues({});
+      }
+      else
+      {
+         setFields([])
+      }
+   }, [widgetData]);
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   function checkForFormValueChanges(formikProps: FormikContextType<any>)
+   {
+      if(!fields || !fields.length)
+      {
+         return;
+      }
+
+      let anyChanged = false;
+      for (let i = 0; i < fields.length; i++)
+      {
+         const name = fields[i].name;
+         if(formikProps.values[name] != lastKnowFormValues[name])
+         {
+            anyChanged = true;
+            lastKnowFormValues[name] = formikProps.values[name];
+         }
+      }
+
+      if(anyChanged)
+      {
+         const mergedDynamicFormValuesIntoFieldName = widgetData.mergedDynamicFormValuesIntoFieldName;
+         if(mergedDynamicFormValuesIntoFieldName && onSaveCallback)
+         {
+            const onSaveCallbackParam: {[name: string]: any} = {};
+            onSaveCallbackParam[mergedDynamicFormValuesIntoFieldName] = JSON.stringify(lastKnowFormValues);
+            onSaveCallback(onSaveCallbackParam);
+         }
+      }
+   }
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   function getInitialValue(fieldName: string)
+   {
+      for (let i = 0; i < fields?.length; i++)
+      {
+         if(fields[i].name == fieldName && fields[i].defaultValue)
+         {
+            return (fields[i].defaultValue)
+         }
+      }
+
+      return (null);
+   }
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   function renderEditForm()
+   {
+      const formikProps = useFormikContext();
+      if(!fields || !fields.length)
+      {
+         return (
+            <Box>
+               <Box fontSize="1rem">{widgetData && widgetData.noFieldsMessage}</Box>
+            </Box>
+         );
+      }
+
+      const formData: any = {};
+      formData.values = formikProps.values;
+      formData.touched = formikProps.touched;
+      formData.errors = formikProps.errors;
+      formData.formFields = {};
+
+      // todo - merge the formValidations object with formik's - maybe in the useEffect where we build it
+      // setValidations(Yup.object().shape(formValidations));
+      // formikProps.validationSchema.
+
+      for (let key of Object.keys(dynamicFormFields))
+      {
+         const dynamicFormField = dynamicFormFields[key];
+         formData.formFields[dynamicFormField.name] = dynamicFormField;
+
+         const initialValue = getInitialValue(dynamicFormField.name);
+         if(initialValue != null)
+         {
+            console.log(`@dk trying to set an initial value [${dynamicFormField.name}] to [${initialValue}]`);
+            // @ts-ignore some any
+            formikProps.initialValues[dynamicFormField.name] = initialValue;
+         }
+      }
+
+      if(formData.values)
+      {
+         checkForFormValueChanges(formikProps);
+      }
+
+      return (
+         <Box>
+            <QDynamicForm formData={formData} record={record} />
+         </Box>
+      );
+   }
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   function renderViewForm()
+   {
+      const fieldNames: string[] = [];
+      const fieldMap: {[name: string]: QFieldMetaData} = {};
+      const fakeRecord = new QRecord(widgetData.recordOfFieldValues ?? {});
+
+      const mergedDynamicFormValuesIntoFieldName = widgetData.mergedDynamicFormValuesIntoFieldName;
+
+      for (let i = 0; i < fields?.length; i++)
+      {
+         const fieldName = fields[i].name;
+         fieldNames.push(fieldName);
+         fieldMap[fieldName] = fields[i];
+
+         if(mergedDynamicFormValuesIntoFieldName && recordValues[mergedDynamicFormValuesIntoFieldName])
+         {
+            fakeRecord.values.set(fieldName, recordValues[mergedDynamicFormValuesIntoFieldName][fieldName]);
+         }
+      }
+
+      const section = renderSectionOfFields(`dynamicFormWidget:${widgetMetaData.name}`, fieldNames, null, false, fakeRecord, fieldMap);
+
+      return (<Box>
+         {section}
+      </Box>);
+   }
+
+
+   ////////////
+   // render //
+   ////////////
+   return (<Widget widgetMetaData={widgetMetaData}>
+      {
+         <React.Fragment>
+            {effectiveIsEditable ? renderEditForm() : renderViewForm()}
+         </React.Fragment>
+      }
+   </Widget>);
+}
+

src/qqq/components/widgets/misc/FilterAndColumnsSetupWidget.tsx

@@ -20,8 +20,11 @@
  */
 
 
+import {ApiVersion} from "@kingsrook/qqq-frontend-core/lib/controllers/QControllerV1";
 import {QTableMetaData} from "@kingsrook/qqq-frontend-core/lib/model/metaData/QTableMetaData";
 import {QWidgetMetaData} from "@kingsrook/qqq-frontend-core/lib/model/metaData/QWidgetMetaData";
+import {QCriteriaOperator} from "@kingsrook/qqq-frontend-core/lib/model/query/QCriteriaOperator";
+import {QFilterCriteria} from "@kingsrook/qqq-frontend-core/lib/model/query/QFilterCriteria";
 import {QQueryFilter} from "@kingsrook/qqq-frontend-core/lib/model/query/QQueryFilter";
 import {Alert, Collapse} from "@mui/material";
 import Box from "@mui/material/Box";
@@ -40,17 +43,20 @@ import QQueryColumns, {Column} from "qqq/models/query/QQueryColumns";
 import RecordQuery from "qqq/pages/records/query/RecordQuery";
 import Client from "qqq/utils/qqq/Client";
 import FilterUtils from "qqq/utils/qqq/FilterUtils";
-import React, {useContext, useEffect, useRef, useState} from "react";
+import TableUtils from "qqq/utils/qqq/TableUtils";
+import React, {useContext, useEffect, useMemo, useRef, useState} from "react";
 
-interface ReportSetupWidgetProps
+interface FilterAndColumnsSetupWidgetProps
 {
-   isEditable: boolean;
-   widgetMetaData: QWidgetMetaData;
-   recordValues: {[name: string]: any};
-   onSaveCallback?: (values: {[name: string]: any}) => void;
+   isEditable: boolean,
+   widgetMetaData: QWidgetMetaData,
+   widgetData: any,
+   recordValues: { [name: string]: any },
+   onSaveCallback?: (values: { [name: string]: any }) => void,
+   label?: string
 }
 
-ReportSetupWidget.defaultProps = {
+FilterAndColumnsSetupWidget.defaultProps = {
    onSaveCallback: null
 };
 
@@ -76,16 +82,31 @@ unborderedButtonSX.opacity = "0.7";
 
 
 const qController = Client.getInstance();
+const qControllerV1 = Client.getInstanceV1();
 
 /*******************************************************************************
  ** Component for editing the main setup of a report - that is: filter & columns
  *******************************************************************************/
-export default function ReportSetupWidget({isEditable, widgetMetaData, recordValues, onSaveCallback}: ReportSetupWidgetProps): JSX.Element
+export default function FilterAndColumnsSetupWidget({isEditable: isEditableProp, widgetMetaData, widgetData, recordValues, onSaveCallback, label}: FilterAndColumnsSetupWidgetProps): JSX.Element
 {
    const [modalOpen, setModalOpen] = useState(false);
+   const [hideColumns] = useState(widgetData?.hideColumns);
+   const [hidePreview] = useState(widgetData?.hidePreview);
+   const [hideSortBy] = useState(widgetData?.hideSortBy);
+   const [isEditable] = useState(widgetData?.overrideIsEditable ?? isEditableProp);
    const [tableMetaData, setTableMetaData] = useState(null as QTableMetaData);
 
+   const [isApiVersioned] = useState(widgetData?.isApiVersioned);
+   const [apiVersion, setApiVersion] = useState(null as ApiVersion | null);
+
+   const [filterFieldName] = useState(widgetData?.filterFieldName ?? "queryFilterJson");
+   const [columnsFieldName] = useState(widgetData?.columnsFieldName ?? "columnsJson");
+
    const [alertContent, setAlertContent] = useState(null as string);
+   const [warning, setWarning] = useState(null as string);
+   const [widgetFailureAlertContent, setWidgetFailureAlertContent] = useState(null as string);
+
+   const omitExposedJoins: string[] = widgetData?.omitExposedJoins ?? [];
 
    //////////////////////////////////////////////////////////////////////////////////////////////////
    // we'll actually keep 2 copies of the query filter around here -                               //
@@ -101,18 +122,47 @@ export default function ReportSetupWidget({isEditable, widgetMetaData, recordVal
    /////////////////////////////
    // load values from record //
    /////////////////////////////
-   let queryFilter = recordValues["queryFilterJson"] && JSON.parse(recordValues["queryFilterJson"]) as QQueryFilter;
+   let columns: QQueryColumns = null;
    let usingDefaultEmptyFilter = false;
-   if(!queryFilter)
+   const rawFilterValueFromRecord = recordValues[filterFieldName];
+   let queryFilter = rawFilterValueFromRecord &&
+      ((typeof rawFilterValueFromRecord == "string" ? JSON.parse(rawFilterValueFromRecord) : rawFilterValueFromRecord) as QQueryFilter);
+   const defaultFilterFields = widgetData?.filterDefaultFieldNames;
+   if (!queryFilter)
    {
       queryFilter = new QQueryFilter();
-      usingDefaultEmptyFilter = true;
+      if (defaultFilterFields?.length == 0)
+      {
+         usingDefaultEmptyFilter = true;
+      }
+   }
+   else
+   {
+      queryFilter = Object.assign(new QQueryFilter(), queryFilter);
    }
 
-   let columns: QQueryColumns = null;
-   if(recordValues["columnsJson"])
+   //////////////////////////////////////////////////////////////////////////////////////////////////////
+   // if there are default fields from which a query should be seeded, add/update the filter with them //
+   //////////////////////////////////////////////////////////////////////////////////////////////////////
+   if (defaultFilterFields?.length > 0)
    {
-      columns = QQueryColumns.buildFromJSON(recordValues["columnsJson"]);
+      defaultFilterFields.forEach((fieldName: string) =>
+      {
+         ////////////////////////////////////////////////////////////////////////////////////////////
+         // if a value for the default field exists, remove the criteria for it in our query first //
+         ////////////////////////////////////////////////////////////////////////////////////////////
+         queryFilter.criteria = queryFilter.criteria?.filter(c => c.fieldName != fieldName);
+
+         if (recordValues[fieldName])
+         {
+            queryFilter.addCriteria(new QFilterCriteria(fieldName, QCriteriaOperator.EQUALS, [recordValues[fieldName]]));
+         }
+      });
+   }
+
+   if (recordValues[columnsFieldName])
+   {
+      columns = QQueryColumns.buildFromJSON(recordValues[columnsFieldName]);
    }
 
    //////////////////////////////////////////////////////////////////////
@@ -120,19 +170,85 @@ export default function ReportSetupWidget({isEditable, widgetMetaData, recordVal
    //////////////////////////////////////////////////////////////////////
    useEffect(() =>
    {
-      if (recordValues["tableName"] && (tableMetaData == null || tableMetaData.name != recordValues["tableName"]))
+      ////////////////////////////////////////////////////////////////////////////////////////
+      // if a default table name specified, use it, otherwise use it from the record values //
+      ////////////////////////////////////////////////////////////////////////////////////////
+      let tableName = widgetData?.tableName;
+      if (!tableName && recordValues["tableName"] && (tableMetaData == null || tableMetaData.name != recordValues["tableName"]))
+      {
+         tableName = recordValues["tableName"];
+      }
+
+      let version: ApiVersion | null = null;
+      if (isApiVersioned)
+      {
+         let apiName = widgetData?.apiName;
+         let apiPath = widgetData?.apiPath;
+         let apiVersion = widgetData?.apiVersion;
+
+         if (!apiName && recordValues["apiName"])
+         {
+            apiName = recordValues["apiName"];
+         }
+
+         if (!apiPath && recordValues["apiPath"])
+         {
+            apiPath = recordValues["apiPath"];
+         }
+
+         if (!apiVersion && recordValues["apiVersion"])
+         {
+            apiVersion = recordValues["apiVersion"];
+         }
+
+         if (!apiName || !apiPath || !apiVersion)
+         {
+            console.log("API Name/Path/Version not set, but widget isApiVersioned, so cannot load table meta data...");
+            return;
+         }
+
+         version = {name: apiName, path: apiPath, version: apiVersion};
+         setApiVersion(version);
+      }
+
+      if (tableName)
       {
          (async () =>
          {
-            const tableMetaData = await qController.loadTableMetaData(recordValues["tableName"])
-            setTableMetaData(tableMetaData);
+            try
+            {
+               const tableMetaData = await qControllerV1.loadTableMetaData(tableName, version);
+               setTableMetaData(tableMetaData);
 
-            const queryFilterForFrontend = Object.assign({}, queryFilter);
-            await FilterUtils.cleanupValuesInFilerFromQueryString(qController, tableMetaData, queryFilterForFrontend)
-            setFrontendQueryFilter(queryFilterForFrontend)
+               const queryFilterForFrontend = Object.assign({}, queryFilter);
+
+               let warnings: string[] = [];
+               for (let i = 0; i < queryFilterForFrontend?.criteria?.length; i++)
+               {
+                  const criteria = queryFilter.criteria[i];
+                  let [field, fieldTable] = TableUtils.getFieldAndTable(tableMetaData, criteria.fieldName);
+                  if(!field)
+                  {
+                     warnings.push("Removing non-existing filter field: " + criteria.fieldName);
+                     queryFilterForFrontend.criteria.splice(i, 1);
+                     i--;
+                  }
+               }
+
+               await FilterUtils.cleanupValuesInFilerFromQueryString(qController, tableMetaData, queryFilterForFrontend);
+               setFrontendQueryFilter(queryFilterForFrontend);
+
+               setWarning(warnings.join("; "));
+            }
+            catch (e)
+            {
+               console.log(e);
+               //@ts-ignore e.message
+               setWidgetFailureAlertContent("Error preparing filter widget: " + (e.message ?? "Details not available."));
+            }
          })();
       }
-   }, [recordValues]);
+   }, [JSON.stringify(recordValues)]);
 
 
    /*******************************************************************************
@@ -140,8 +256,27 @@ export default function ReportSetupWidget({isEditable, widgetMetaData, recordVal
     *******************************************************************************/
    function openEditor()
    {
-      if(recordValues["tableName"])
+      let missingRequiredFields = [] as string[];
+      widgetData?.filterDefaultFieldNames?.forEach((fieldName: string) =>
       {
+         if (!recordValues[fieldName])
+         {
+            missingRequiredFields.push(tableMetaData.fields.get(fieldName).label);
+         }
+      });
+
+      ////////////////////////////////////////////////////////////////////
+      // display an alert and return if any required fields are missing //
+      ////////////////////////////////////////////////////////////////////
+      if (missingRequiredFields.length > 0)
+      {
+         setAlertContent("The following fields must first be selected to edit the filter: '" + missingRequiredFields.join(", ") + "'");
+         return;
+      }
+
+      if (widgetData?.tableName || recordValues["tableName"])
+      {
+         setAlertContent(null);
          setModalOpen(true);
       }
    }
@@ -152,7 +287,7 @@ export default function ReportSetupWidget({isEditable, widgetMetaData, recordVal
     *******************************************************************************/
    function saveClicked()
    {
-      if(!onSaveCallback)
+      if (!onSaveCallback)
       {
          console.log("onSaveCallback was not defined");
          return;
@@ -170,7 +305,10 @@ export default function ReportSetupWidget({isEditable, widgetMetaData, recordVal
       setFrontendQueryFilter(view.queryFilter);
       const filter = FilterUtils.prepQueryFilterForBackend(tableMetaData, view.queryFilter);
 
-      onSaveCallback({queryFilterJson: JSON.stringify(filter), columnsJson: JSON.stringify(view.queryColumns)});
+      const rs: { [key: string]: any } = {};
+      rs[filterFieldName] = JSON.stringify(filter);
+      rs[columnsFieldName] = JSON.stringify(view.queryColumns);
+      onSaveCallback(rs);
 
       closeEditor();
    }
@@ -181,7 +319,7 @@ export default function ReportSetupWidget({isEditable, widgetMetaData, recordVal
     *******************************************************************************/
    function closeEditor(event?: {}, reason?: "backdropClick" | "escapeKeyDown")
    {
-      if(reason == "backdropClick" || reason == "escapeKeyDown")
+      if (reason == "backdropClick" || reason == "escapeKeyDown")
       {
          return;
       }
@@ -195,9 +333,9 @@ export default function ReportSetupWidget({isEditable, widgetMetaData, recordVal
     *******************************************************************************/
    function renderColumn(column: Column): JSX.Element
    {
-      const [field, table] = FilterUtils.getField(tableMetaData, column.name)
+      const [field, table] = FilterUtils.getField(tableMetaData, column.name);
 
-      if(!column || !column.isVisible || column.name == "__check__" || !field)
+      if (!column || !column.isVisible || column.name == "__check__" || !field)
       {
          return (<React.Fragment />);
       }
@@ -213,11 +351,11 @@ export default function ReportSetupWidget({isEditable, widgetMetaData, recordVal
    /*******************************************************************************
     **
     *******************************************************************************/
-   function mayShowQueryPreview(): boolean
+   function mayShowQuery(): boolean
    {
-      if(tableMetaData)
+      if (tableMetaData)
       {
-         if(frontendQueryFilter?.criteria?.length > 0 || frontendQueryFilter?.subFilters?.length > 0)
+         if (frontendQueryFilter?.criteria?.length > 0 || frontendQueryFilter?.subFilters?.length > 0)
          {
             return (true);
          }
@@ -229,13 +367,13 @@ export default function ReportSetupWidget({isEditable, widgetMetaData, recordVal
    /*******************************************************************************
     **
     *******************************************************************************/
-   function mayShowColumnsPreview(): boolean
+   function mayShowColumns(): boolean
    {
-      if(tableMetaData)
+      if (tableMetaData)
       {
-         for(let i = 0; i<columns?.columns?.length; i++)
+         for (let i = 0; i < columns?.columns?.length; i++)
          {
-            if(columns.columns[i].isVisible && columns.columns[i].name != "__check__")
+            if (columns.columns[i].isVisible && columns.columns[i].name != "__check__")
             {
                return (true);
             }
@@ -268,13 +406,26 @@ export default function ReportSetupWidget({isEditable, widgetMetaData, recordVal
    /////////////////////////////////////////////////
    // add link to widget header for opening modal //
    /////////////////////////////////////////////////
-   const selectTableFirstTooltipTitle = tableMetaData ? null : "You must select a table before you can set up your report filters and columns";
-   const labelAdditionalElementsRight: JSX.Element[] = []
-   if(isEditable)
+   const selectTableFirstTooltipTitle = tableMetaData ? null : `You must select a table${isApiVersioned ? " and API details" : ""} before you can set up your filters${hideColumns ? "" : " and columns"}`;
+   const labelAdditionalElementsRight: JSX.Element[] = [];
+   if (isEditable)
    {
-      labelAdditionalElementsRight.push(<HeaderLinkButtonComponent label="Edit Filters and Columns" onClickCallback={openEditor} disabled={tableMetaData == null} disabledTooltip={selectTableFirstTooltipTitle} />)
+      if (!hideColumns)
+      {
+         labelAdditionalElementsRight.push(<HeaderLinkButtonComponent key="filterAndColumnsHeader" label="Edit Filters and Columns" onClickCallback={openEditor} disabled={tableMetaData == null} disabledTooltip={selectTableFirstTooltipTitle} />);
+      }
+      else
+      {
+         labelAdditionalElementsRight.push(<HeaderLinkButtonComponent key="filterAndColumnsHeader" label="Edit Filters" onClickCallback={openEditor} disabled={tableMetaData == null} disabledTooltip={selectTableFirstTooltipTitle} />);
+      }
    }
 
+   if (widgetFailureAlertContent)
+   {
+      return (<Widget widgetMetaData={widgetMetaData}>
+         <Alert severity="error" sx={{mt: 1.5, mb: 0.5}}>{widgetFailureAlertContent}</Alert>
+      </Widget>);
+   }
 
    return (<Widget widgetMetaData={widgetMetaData} labelAdditionalElementsRight={labelAdditionalElementsRight}>
       <React.Fragment>
@@ -287,60 +438,82 @@ export default function ReportSetupWidget({isEditable, widgetMetaData, recordVal
          <Collapse in={Boolean(alertContent)}>
             <Alert severity="error" sx={{mt: 1.5, mb: 0.5}} onClose={() => setAlertContent(null)}>{alertContent}</Alert>
          </Collapse>
+         <Collapse in={Boolean(warning)}>
+            <Alert severity="warning" sx={{mt: 1.5, mb: 0.5}} onClose={() => setWarning(null)}>{warning}</Alert>
+         </Collapse>
          <Box pt="0.5rem">
             <Box display="flex" justifyContent="space-between" alignItems="center">
-               <h5>Query Filter</h5>
-               <Box fontSize="0.75rem" fontWeight="700">{mayShowQueryPreview() && getCurrentSortIndicator(frontendQueryFilter, tableMetaData, null)}</Box>
+               <h5>{label ?? widgetData.label ?? widgetMetaData.label ?? "Query Filter"}</h5>
+               {!hideSortBy && <Box fontSize="0.75rem" fontWeight="700">{mayShowQuery() && getCurrentSortIndicator(frontendQueryFilter, tableMetaData, null)}</Box>}
             </Box>
             {
-               mayShowQueryPreview() &&
+               mayShowQuery() &&
                <AdvancedQueryPreview tableMetaData={tableMetaData} queryFilter={frontendQueryFilter} isEditable={false} isQueryTooComplex={frontendQueryFilter.subFilters?.length > 0} removeCriteriaByIndexCallback={null} />
             }
             {
-               !mayShowQueryPreview() &&
+               !mayShowQuery() &&
                <Box width="100%" sx={{fontSize: "1rem", background: "#FFFFFF"}} minHeight={"2.5rem"} p={"0.5rem"} pb={"0.125rem"} borderRadius="0.75rem" border={`1px solid ${colors.grayLines.main}`}>
                   {
                      isEditable &&
                      <Tooltip title={selectTableFirstTooltipTitle}>
-                        <span><Button disabled={!recordValues["tableName"]} sx={{mb: "0.125rem", ...unborderedButtonSX}} onClick={openEditor}>+ Add Filters</Button></span>
+                        <span><Button disabled={tableMetaData == null} sx={{mb: "0.125rem", ...unborderedButtonSX}} onClick={openEditor}>+ Add Filters</Button></span>
                      </Tooltip>
                   }
                   {
-                     !isEditable && <Box color={colors.gray.main}>Your report has no filters.</Box>
+                     !isEditable && <Box color={colors.gray.main}>No filters are configured.</Box>
                   }
                </Box>
             }
          </Box>
-         <Box pt="1rem">
-            <h5>Columns</h5>
-            <Box display="flex" flexWrap="wrap" fontSize="1rem">
-               {
-                  mayShowColumnsPreview() &&
-                  columns.columns.map((column, i) => <React.Fragment key={i}>{renderColumn(column)}</React.Fragment>)
-               }
-               {
-                  !mayShowColumnsPreview() &&
-                  <Box width="100%" sx={{fontSize: "1rem", background: "#FFFFFF"}} minHeight={"2.375rem"} p={"0.5rem"} pb={"0.125rem"}>
-                     {
-                        isEditable &&
-                        <Tooltip title={selectTableFirstTooltipTitle}>
-                           <span><Button disabled={!recordValues["tableName"]} sx={unborderedButtonSX} onClick={openEditor}>+ Add Columns</Button></span>
-                        </Tooltip>
-                     }
-                     {
-                        !isEditable && <Box color={colors.gray.main}>Your report has no columns.</Box>
-                     }
-                  </Box>
-               }
+         {!hideColumns && (
+            <Box pt="1rem">
+               <h5>Columns</h5>
+               <Box display="flex" flexWrap="wrap" fontSize="1rem">
+                  {
+                     mayShowColumns() && columns &&
+                     columns.columns.map((column, i) => <React.Fragment key={`column-${i}`}>{renderColumn(column)}</React.Fragment>)
+                  }
+                  {
+                     !mayShowColumns() &&
+                     <Box width="100%" sx={{fontSize: "1rem", background: "#FFFFFF"}} minHeight={"2.375rem"} p={"0.5rem"} pb={"0.125rem"}>
+                        {
+                           isEditable &&
+                           <Tooltip title={selectTableFirstTooltipTitle}>
+                              <span><Button disabled={!recordValues["tableName"]} sx={unborderedButtonSX} onClick={openEditor}>+ Add Columns</Button></span>
+                           </Tooltip>
+                        }
+                        {
+                           !isEditable && <Box color={colors.gray.main}>No columns are selected.</Box>
+                        }
+                     </Box>
+                  }
+               </Box>
             </Box>
-         </Box>
+         )}
+         {!hidePreview && !isEditable && frontendQueryFilter && tableMetaData && (
+            <Box pt="1rem">
+               <h5>Preview</h5>
+               <RecordQuery
+                  allowVariables={widgetData?.allowVariables}
+                  ref={recordQueryRef}
+                  table={tableMetaData}
+                  isPreview={true}
+                  usage="reportSetup"
+                  isModal={true}
+                  initialQueryFilter={frontendQueryFilter}
+                  initialColumns={columns}
+                  apiVersion={apiVersion}
+                  omitExposedJoins={omitExposedJoins}
+               />
+            </Box>
+         )}
          {
             modalOpen &&
             <Modal open={modalOpen} onClose={(event, reason) => closeEditor(event, reason)}>
                <div>
                   <Box sx={{position: "absolute", overflowY: "auto", maxHeight: "100%", width: "100%"}}>
                      <Card sx={{m: "2rem", p: "2rem"}}>
-                        <h3>Edit Filters and Columns</h3>
+                        <h3>Edit Filters {hideColumns ? "" : " and Columns"}</h3>
                         {
                            showHelp("modalSubheader") &&
                            <Box color={colors.gray.main} pb={"0.5rem"}>
@@ -349,12 +522,15 @@ export default function ReportSetupWidget({isEditable, widgetMetaData, recordVal
                         }
                         {
                            tableMetaData && <RecordQuery
+                              allowVariables={widgetData?.allowVariables}
                               ref={recordQueryRef}
                               table={tableMetaData}
                               usage="reportSetup"
                               isModal={true}
                               initialQueryFilter={usingDefaultEmptyFilter ? null : frontendQueryFilter}
                               initialColumns={columns}
+                              apiVersion={apiVersion}
+                              omitExposedJoins={omitExposedJoins}
                            />
                         }
 

src/qqq/components/widgets/misc/PivotTableSetupWidget.tsx

@@ -39,9 +39,9 @@ import colors from "qqq/assets/theme/base/colors";
 import {QCancelButton, QSaveButton} from "qqq/components/buttons/DefaultButtons";
 import FieldAutoComplete from "qqq/components/misc/FieldAutoComplete";
 import HelpContent, {hasHelpContent} from "qqq/components/misc/HelpContent";
+import {buttonSX, unborderedButtonSX} from "qqq/components/widgets/misc/FilterAndColumnsSetupWidget";
 import {PivotTableGroupByElement} from "qqq/components/widgets/misc/PivotTableGroupByElement";
 import {PivotTableValueElement} from "qqq/components/widgets/misc/PivotTableValueElement";
-import {buttonSX, unborderedButtonSX} from "qqq/components/widgets/misc/ReportSetupWidget";
 import Widget, {HeaderToggleComponent} from "qqq/components/widgets/Widget";
 import {PivotObjectKey, PivotTableDefinition, PivotTableFunction, pivotTableFunctionLabels, PivotTableGroupBy, PivotTableValue} from "qqq/models/misc/PivotTableDefinitionModels";
 import QQueryColumns from "qqq/models/query/QQueryColumns";
@@ -280,7 +280,7 @@ export default function PivotTableSetupWidget({isEditable, widgetMetaData, recor
       }
 
       modalPivotTableDefinition[rowsOrColumns].push(new PivotTableGroupBy());
-      validateForm()
+      validateForm();
       forceUpdate();
    }
 
@@ -292,7 +292,7 @@ export default function PivotTableSetupWidget({isEditable, widgetMetaData, recor
    {
       updateUsedGroupByFieldNames(modalPivotTableDefinition);
       updateUsedValueFieldNames(modalPivotTableDefinition);
-      validateForm()
+      validateForm();
       forceUpdate();
    }
 
@@ -308,7 +308,7 @@ export default function PivotTableSetupWidget({isEditable, widgetMetaData, recor
       }
 
       modalPivotTableDefinition.values.push(new PivotTableValue());
-      validateForm()
+      validateForm();
       forceUpdate();
    }
 
@@ -319,7 +319,7 @@ export default function PivotTableSetupWidget({isEditable, widgetMetaData, recor
    function removeValue(index: number)
    {
       modalPivotTableDefinition.values.splice(index, 1);
-      validateForm()
+      validateForm();
       forceUpdate();
    }
 
@@ -503,7 +503,7 @@ export default function PivotTableSetupWidget({isEditable, widgetMetaData, recor
    const labelAdditionalElementsRight: JSX.Element[] = [];
    if (isEditable)
    {
-      labelAdditionalElementsRight.push(<HeaderToggleComponent disabled={editPopupDisabled} disabledTooltip={selectTableFirstTooltipTitle ?? selectColumnsFirstTooltipTitle} label="Use Pivot Table?" getValue={() => enabled} onClickCallback={toggleEnabled} />);
+      labelAdditionalElementsRight.push(<HeaderToggleComponent key="pivotTableHeader" disabled={editPopupDisabled} disabledTooltip={selectTableFirstTooltipTitle ?? selectColumnsFirstTooltipTitle} label="Use Pivot Table?" getValue={() => enabled} onClickCallback={toggleEnabled} />);
    }
 
 
@@ -659,7 +659,7 @@ export default function PivotTableSetupWidget({isEditable, widgetMetaData, recor
       // if this isn't a call from the on-submit handler, and we haven't previously attempted a submit, then return w/o setting any alerts //
       // this is like a version of considering "touched"...                                                                                //
       ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
-      if(!submitting && !attemptedSubmit)
+      if (!submitting && !attemptedSubmit)
       {
          return;
       }
@@ -703,7 +703,7 @@ export default function PivotTableSetupWidget({isEditable, widgetMetaData, recor
          // now they've fixed 'em - so go back to a 'clean' state - so if they add more    //
          // boxes, they won't immediately show errors, until a re-submit                   //
          ////////////////////////////////////////////////////////////////////////////////////
-         if(attemptedSubmit)
+         if (attemptedSubmit)
          {
             setAttemptedSubmit(false);
          }

src/qqq/components/widgets/misc/RecordGridWidget.tsx

@@ -28,7 +28,7 @@ import Icon from "@mui/material/Icon";
 import IconButton from "@mui/material/IconButton";
 import Tooltip from "@mui/material/Tooltip/Tooltip";
 import Typography from "@mui/material/Typography";
-import {DataGridPro, GridCallbackDetails, GridEventListener, GridRenderCellParams, GridRowParams, GridToolbarContainer, MuiEvent, useGridApiContext, useGridApiEventHandler} from "@mui/x-data-grid-pro";
+import {DataGridPro, GridCallbackDetails, GridDensity, GridEventListener, GridRenderCellParams, GridRowParams, GridToolbarContainer, MuiEvent, useGridApiContext, useGridApiEventHandler} from "@mui/x-data-grid-pro";
 import Widget, {AddNewRecordButton, LabelComponent, WidgetData} from "qqq/components/widgets/Widget";
 import DataGridUtils from "qqq/utils/DataGridUtils";
 import HtmlUtils from "qqq/utils/HtmlUtils";
@@ -39,45 +39,51 @@ import {Link, useNavigate} from "react-router-dom";
 
 export interface ChildRecordListData extends WidgetData
 {
-   title: string;
-   queryOutput: {records: {values: any}[]}
-   childTableMetaData: QTableMetaData;
-   tablePath: string;
-   viewAllLink: string;
-   totalRows: number;
-   canAddChildRecord: boolean;
-   defaultValuesForNewChildRecords: {[fieldName: string]: any};
-   disabledFieldsForNewChildRecords: {[fieldName: string]: any};
+   title?: string;
+   queryOutput?: { records: { values: any, displayValues?: any } [] };
+   childTableMetaData?: QTableMetaData;
+   tablePath?: string;
+   viewAllLink?: string;
+   totalRows?: number;
+   canAddChildRecord?: boolean;
+   defaultValuesForNewChildRecords?: { [fieldName: string]: any };
+   disabledFieldsForNewChildRecords?: { [fieldName: string]: any };
+   defaultValuesForNewChildRecordsFromParentFields?: { [fieldName: string]: string };
+   omitFieldNames?: string[];
 }
 
 interface Props
 {
-   widgetMetaData: QWidgetMetaData;
-   data: ChildRecordListData;
-   addNewRecordCallback?: () => void;
-   disableRowClick: boolean;
-   allowRecordEdit: boolean;
-   editRecordCallback?: (rowIndex: number) => void;
-   allowRecordDelete: boolean;
-   deleteRecordCallback?: (rowIndex: number) => void;
+   widgetMetaData: QWidgetMetaData,
+   data: ChildRecordListData,
+   addNewRecordCallback?: () => void,
+   disableRowClick: boolean,
+   allowRecordEdit: boolean,
+   editRecordCallback?: (rowIndex: number) => void,
+   allowRecordDelete: boolean,
+   deleteRecordCallback?: (rowIndex: number) => void,
+   gridOnly?: boolean,
+   gridDensity?: GridDensity,
+   parentRecord?: QRecord
 }
 
 RecordGridWidget.defaultProps =
    {
       disableRowClick: false,
       allowRecordEdit: false,
-      allowRecordDelete: false
+      allowRecordDelete: false,
+      gridOnly: false,
    };
 
 const qController = Client.getInstance();
 
-function RecordGridWidget({widgetMetaData, data, addNewRecordCallback, disableRowClick, allowRecordEdit, editRecordCallback, allowRecordDelete, deleteRecordCallback}: Props): JSX.Element
+function RecordGridWidget({widgetMetaData, data, addNewRecordCallback, disableRowClick, allowRecordEdit, editRecordCallback, allowRecordDelete, deleteRecordCallback, gridOnly, gridDensity, parentRecord}: Props): JSX.Element
 {
    const instance = useRef({timer: null});
    const [rows, setRows] = useState([]);
-   const [records, setRecords] = useState([] as QRecord[])
+   const [records, setRecords] = useState([] as QRecord[]);
    const [columns, setColumns] = useState([]);
-   const [allColumns, setAllColumns] = useState([])
+   const [allColumns, setAllColumns] = useState([]);
    const [csv, setCsv] = useState(null as string);
    const [fileName, setFileName] = useState(null as string);
    const [gridMouseDownX, setGridMouseDownX] = useState(0);
@@ -94,12 +100,19 @@ function RecordGridWidget({widgetMetaData, data, addNewRecordCallback, disableRo
          {
             for (let i = 0; i < queryOutputRecords.length; i++)
             {
-               records.push(new QRecord(queryOutputRecords[i]));
+               if (queryOutputRecords[i] instanceof QRecord)
+               {
+                  records.push(queryOutputRecords[i] as QRecord);
+               }
+               else
+               {
+                  records.push(new QRecord(queryOutputRecords[i]));
+               }
             }
          }
 
-         const tableMetaData = new QTableMetaData(data.childTableMetaData);
-         const rows = DataGridUtils.makeRows(records, tableMetaData, true);
+         const tableMetaData = data.childTableMetaData instanceof QTableMetaData ? data.childTableMetaData as QTableMetaData : new QTableMetaData(data.childTableMetaData);
+         const rows = DataGridUtils.makeRows(records, tableMetaData, undefined, true);
 
          /////////////////////////////////////////////////////////////////////////////////
          // note - tablePath may be null, if the user doesn't have access to the table. //
@@ -107,23 +120,36 @@ function RecordGridWidget({widgetMetaData, data, addNewRecordCallback, disableRo
          const childTablePath = data.tablePath ? data.tablePath + (data.tablePath.endsWith("/") ? "" : "/") : data.tablePath;
          const columns = DataGridUtils.setupGridColumns(tableMetaData, childTablePath, null, "bySection");
 
+         if (data.omitFieldNames)
+         {
+            for (let i = 0; i < columns.length; i++)
+            {
+               const column = columns[i];
+               if (data.omitFieldNames.indexOf(column.field) > -1)
+               {
+                  columns.splice(i, 1);
+                  i--;
+               }
+            }
+         }
+
          /////////////////////////////////////////////////////////////////////////////////////////////////////////////
          // capture all-columns to use for the export (before we might splice some away from the on-screen display) //
          /////////////////////////////////////////////////////////////////////////////////////////////////////////////
-         const allColumns = [... columns];
+         const allColumns = [...columns];
          setAllColumns(JSON.parse(JSON.stringify(columns)));
 
          ////////////////////////////////////////////////////////////////
          // do not not show the foreign-key column of the parent table //
          ////////////////////////////////////////////////////////////////
-         if(data.defaultValuesForNewChildRecords)
+         if (data.defaultValuesForNewChildRecords)
          {
             for (let i = 0; i < columns.length; i++)
             {
-               if(data.defaultValuesForNewChildRecords[columns[i].field])
+               if (data.defaultValuesForNewChildRecords[columns[i].field])
                {
                   columns.splice(i, 1);
-                  i--
+                  i--;
                }
             }
          }
@@ -131,7 +157,7 @@ function RecordGridWidget({widgetMetaData, data, addNewRecordCallback, disableRo
          ////////////////////////////////////
          // add actions cell, if available //
          ////////////////////////////////////
-         if(allowRecordEdit || allowRecordDelete)
+         if (allowRecordEdit || allowRecordDelete)
          {
             columns.unshift({
                field: "_actions",
@@ -145,19 +171,19 @@ function RecordGridWidget({widgetMetaData, data, addNewRecordCallback, disableRo
                   return <Box>
                      {allowRecordEdit && <IconButton onClick={() => editRecordCallback(params.row.__rowIndex)}><Icon>edit</Icon></IconButton>}
                      {allowRecordDelete && <IconButton onClick={() => deleteRecordCallback(params.row.__rowIndex)}><Icon>delete</Icon></IconButton>}
-                  </Box>
+                  </Box>;
                })
-            })
+            });
          }
 
          setRows(rows);
-         setRecords(records)
+         setRecords(records);
          setColumns(columns);
 
          let csv = "";
          for (let i = 0; i < allColumns.length; i++)
          {
-            csv += `${i > 0 ? "," : ""}"${ValueUtils.cleanForCsv(allColumns[i].headerName)}"`
+            csv += `${i > 0 ? "," : ""}"${ValueUtils.cleanForCsv(allColumns[i].headerName)}"`;
          }
          csv += "\n";
 
@@ -165,8 +191,8 @@ function RecordGridWidget({widgetMetaData, data, addNewRecordCallback, disableRo
          {
             for (let j = 0; j < allColumns.length; j++)
             {
-               const value = records[i].displayValues.get(allColumns[j].field) ?? records[i].values.get(allColumns[j].field)
-               csv += `${j > 0 ? "," : ""}"${ValueUtils.cleanForCsv(value)}"`
+               const value = records[i].displayValues.get(allColumns[j].field) ?? records[i].values.get(allColumns[j].field);
+               csv += `${j > 0 ? "," : ""}"${ValueUtils.cleanForCsv(value)}"`;
             }
             csv += "\n";
          }
@@ -176,19 +202,19 @@ function RecordGridWidget({widgetMetaData, data, addNewRecordCallback, disableRo
          setCsv(csv);
          setFileName(fileName);
       }
-   }, [data]);
+   }, [JSON.stringify(data?.queryOutput)]);
 
    ///////////////////
    // view all link //
    ///////////////////
    const labelAdditionalElementsLeft: JSX.Element[] = [];
-   if(data && data.viewAllLink)
+   if (data && data.viewAllLink)
    {
       labelAdditionalElementsLeft.push(
-         <Typography variant="body2" p={2} display="inline" fontSize=".875rem" pt="0" position="relative">
+         <Typography key={"viewAllLink"} variant="body2" p={2} display="inline" fontSize=".875rem" pt="0" position="relative">
             <Link to={data.viewAllLink}>View All</Link>
          </Typography>
-      )
+      );
    }
 
    ///////////////////
@@ -200,10 +226,10 @@ function RecordGridWidget({widgetMetaData, data, addNewRecordCallback, disableRo
    {
       isExportDisabled = false;
 
-      if(data.totalRows && data.queryOutput.records.length < data.totalRows)
+      if (data.totalRows && data.queryOutput.records.length < data.totalRows)
       {
-         tooltipTitle = "Export these " + data.queryOutput.records.length + " records."
-         if(data.viewAllLink)
+         tooltipTitle = "Export these " + data.queryOutput.records.length + " records.";
+         if (data.viewAllLink)
          {
             tooltipTitle += "\nClick View All to export all records.";
          }
@@ -212,21 +238,21 @@ function RecordGridWidget({widgetMetaData, data, addNewRecordCallback, disableRo
 
    const onExportClick = () =>
    {
-      if(csv)
+      if (csv)
       {
          HtmlUtils.download(fileName, csv);
       }
       else
       {
-         alert("There is no data available to export.")
+         alert("There is no data available to export.");
       }
-   }
+   };
 
-   if(widgetMetaData?.showExportButton)
+   if (widgetMetaData?.showExportButton)
    {
       labelAdditionalElementsLeft.push(
-         <Typography key={1} variant="body2" px={0} display="inline" position="relative">
-            <Tooltip title={tooltipTitle}><Button sx={{px: 1, py: 0, minWidth: "initial"}} onClick={onExportClick} disabled={isExportDisabled}><Icon sx={{color: "#757575", fontSize: 1.25}}>save_alt</Icon></Button></Tooltip>
+         <Typography key={"exportButton"} variant="body2" px={0} display="inline" position="relative">
+            <Tooltip title={tooltipTitle}><span><Button sx={{px: 1, py: 0, minWidth: "initial"}} onClick={onExportClick} disabled={isExportDisabled}><Icon sx={{color: "#757575", fontSize: 1.25}}>save_alt</Icon></Button></span></Tooltip>
          </Typography>
       );
    }
@@ -234,15 +260,30 @@ function RecordGridWidget({widgetMetaData, data, addNewRecordCallback, disableRo
    ////////////////////
    // add new button //
    ////////////////////
-   const labelAdditionalComponentsRight: LabelComponent[] = []
-   if(data && data.canAddChildRecord)
+   const labelAdditionalComponentsRight: LabelComponent[] = [];
+   if (data && data.canAddChildRecord)
    {
       let disabledFields = data.disabledFieldsForNewChildRecords;
-      if(!disabledFields)
+      if (!disabledFields)
       {
          disabledFields = data.defaultValuesForNewChildRecords;
       }
-      labelAdditionalComponentsRight.push(new AddNewRecordButton(data.childTableMetaData, data.defaultValuesForNewChildRecords, "Add new", disabledFields, addNewRecordCallback))
+
+      const defaultValuesForNewChildRecords = data.defaultValuesForNewChildRecords || {};
+
+      ///////////////////////////////////////////////////////////////////////////////////////
+      // copy values from specified fields in the parent record down into the child record //
+      ///////////////////////////////////////////////////////////////////////////////////////
+      if (data.defaultValuesForNewChildRecordsFromParentFields)
+      {
+         for (let childField in data.defaultValuesForNewChildRecordsFromParentFields)
+         {
+            const parentField = data.defaultValuesForNewChildRecordsFromParentFields[childField];
+            defaultValuesForNewChildRecords[childField] = parentRecord?.values?.get(parentField);
+         }
+      }
+
+      labelAdditionalComponentsRight.push(new AddNewRecordButton(data.childTableMetaData, defaultValuesForNewChildRecords, "Add new", disabledFields, addNewRecordCallback));
    }
 
 
@@ -251,16 +292,16 @@ function RecordGridWidget({widgetMetaData, data, addNewRecordCallback, disableRo
    /////////////////////////////////////////////////////////////////
    const handleRowClick = (params: GridRowParams, event: MuiEvent<React.MouseEvent>, details: GridCallbackDetails) =>
    {
-      if(disableRowClick)
+      if (disableRowClick)
       {
          return;
       }
 
       (async () =>
       {
-         const qInstance = await qController.loadMetaData()
-         let tablePath = qInstance.getTablePathByName(data.childTableMetaData.name)
-         if(tablePath)
+         const qInstance = await qController.loadMetaData();
+         let tablePath = qInstance.getTablePathByName(data.childTableMetaData.name);
+         if (tablePath)
          {
             tablePath = `${tablePath}/${params.row[data.childTableMetaData.primaryKeyField]}`;
             DataGridUtils.handleRowClick(tablePath, event, gridMouseDownX, gridMouseDownY, navigate, instance);
@@ -276,7 +317,7 @@ function RecordGridWidget({widgetMetaData, data, addNewRecordCallback, disableRo
     *******************************************************************************/
    function CustomToolbar()
    {
-      const handleMouseDown: GridEventListener<"cellMouseDown"> = ( params, event, details ) =>
+      const handleMouseDown: GridEventListener<"cellMouseDown"> = (params, event, details) =>
       {
          setGridMouseDownX(event.clientX);
          setGridMouseDownY(event.clientY);
@@ -295,6 +336,62 @@ function RecordGridWidget({widgetMetaData, data, addNewRecordCallback, disableRo
       return (<GridToolbarContainer />);
    }
 
+   let containerPadding = -3;
+   if (data?.isInProcess)
+   {
+      containerPadding = 0;
+   }
+
+
+   const grid = (
+      <DataGridPro
+         autoHeight
+         sx={{
+            borderBottom: "none",
+            borderLeft: "none",
+            borderRight: "none"
+         }}
+         rows={rows}
+         disableSelectionOnClick
+         columns={columns}
+         rowBuffer={10}
+         getRowClassName={(params) => (params.indexRelativeToCurrentPage % 2 === 0 ? "even" : "odd")}
+         onRowClick={handleRowClick}
+         getRowId={(row) => row.__rowIndex}
+         // getRowHeight={() => "auto"} // maybe nice?  wraps values in cells...
+         components={{
+            Toolbar: CustomToolbar
+         }}
+         // pinnedColumns={pinnedColumns}
+         // onPinnedColumnsChange={handlePinnedColumnsChange}
+         // pagination
+         // paginationMode="server"
+         // rowsPerPageOptions={[20]}
+         // sortingMode="server"
+         // filterMode="server"
+         // page={pageNumber}
+         // checkboxSelection
+         rowCount={data && data.totalRows}
+         // onPageSizeChange={handleRowsPerPageChange}
+         // onStateChange={handleStateChange}
+         density={gridDensity ?? "standard"}
+         // loading={loading}
+         // filterModel={filterModel}
+         // onFilterModelChange={handleFilterChange}
+         // columnVisibilityModel={columnVisibilityModel}
+         // onColumnVisibilityModelChange={handleColumnVisibilityChange}
+         // onColumnOrderChange={handleColumnOrderChange}
+         // onSelectionModelChange={selectionChanged}
+         // onSortModelChange={handleSortChange}
+         // sortingOrder={[ "asc", "desc" ]}
+         // sortModel={columnSortModel}
+      />
+   );
+
+   if (gridOnly)
+   {
+      return (grid);
+   }
 
    return (
       <Widget
@@ -304,49 +401,10 @@ function RecordGridWidget({widgetMetaData, data, addNewRecordCallback, disableRo
          labelAdditionalComponentsRight={labelAdditionalComponentsRight}
          labelBoxAdditionalSx={{position: "relative", top: "-0.375rem"}}
       >
-         <Box mx={-2} mb={-3}>
-            <DataGridPro
-               autoHeight
-               sx={{
-                  borderBottom: "none",
-                  borderLeft: "none",
-                  borderRight: "none"
-               }}
-               rows={rows}
-               disableSelectionOnClick
-               columns={columns}
-               rowBuffer={10}
-               getRowClassName={(params) => (params.indexRelativeToCurrentPage % 2 === 0 ? "even" : "odd")}
-               onRowClick={handleRowClick}
-               getRowId={(row) => row.__rowIndex}
-               // getRowHeight={() => "auto"} // maybe nice?  wraps values in cells...
-               components={{
-                  Toolbar: CustomToolbar
-               }}
-               // pinnedColumns={pinnedColumns}
-               // onPinnedColumnsChange={handlePinnedColumnsChange}
-               // pagination
-               // paginationMode="server"
-               // rowsPerPageOptions={[20]}
-               // sortingMode="server"
-               // filterMode="server"
-               // page={pageNumber}
-               // checkboxSelection
-               rowCount={data && data.totalRows}
-               // onPageSizeChange={handleRowsPerPageChange}
-               // onStateChange={handleStateChange}
-               // density={density}
-               // loading={loading}
-               // filterModel={filterModel}
-               // onFilterModelChange={handleFilterChange}
-               // columnVisibilityModel={columnVisibilityModel}
-               // onColumnVisibilityModelChange={handleColumnVisibilityChange}
-               // onColumnOrderChange={handleColumnOrderChange}
-               // onSelectionModelChange={selectionChanged}
-               // onSortModelChange={handleSortChange}
-               // sortingOrder={[ "asc", "desc" ]}
-               // sortModel={columnSortModel}
-            />
+         <Box mx={containerPadding} mb={containerPadding}>
+            <Box>
+               {grid}
+            </Box>
          </Box>
       </Widget>
    );

src/qqq/components/widgets/misc/ScriptViewer.tsx

@@ -393,7 +393,7 @@ export default function ScriptViewer({scriptId, associatedScriptTableName, assoc
    }
 
    return (
-      <Grid container className="scriptViewer" m={-2} pt={4} width={"calc(100% + 2rem)"}>
+      <Grid container className="scriptViewer" my={-3} mx={-3} pt={4} width={"calc(100% + 3rem)"}>
          <Grid item xs={12}>
             <Box>
                {
@@ -530,7 +530,7 @@ export default function ScriptViewer({scriptId, associatedScriptTableName, assoc
                                  </TabPanel>
 
                                  <TabPanel index={2} value={selectedTab}>
-                                    <Box sx={{height: "455px"}} px={2} pb={1}>
+                                    <Box sx={{height: "455px"}} px={2} pt={1}>
                                        <ScriptTestForm scriptId={scriptId}
                                           scriptType={scriptTypeRecord}
                                           tableName={associatedScriptTableName}
@@ -543,7 +543,7 @@ export default function ScriptViewer({scriptId, associatedScriptTableName, assoc
                                  </TabPanel>
 
                                  <TabPanel index={3} value={selectedTab}>
-                                    <Box sx={{height: "455px"}} px={2} pb={1}>
+                                    <Box sx={{height: "455px"}} px={2} pt={1}>
                                        <ScriptDocsForm helpText={scriptTypeRecord?.values.get("helpText")} exampleCode={scriptTypeRecord?.values.get("sampleCode")} />
                                     </Box>
                                  </TabPanel>

src/qqq/components/widgets/tables/DataTable.tsx

@@ -19,19 +19,14 @@
  */
 
 import {QWidgetMetaData} from "@kingsrook/qqq-frontend-core/lib/model/metaData/QWidgetMetaData";
-import {tooltipClasses, TooltipProps} from "@mui/material";
+import {Box, tooltipClasses, TooltipProps} from "@mui/material";
 import Autocomplete from "@mui/material/Autocomplete";
-import Box from "@mui/material/Box";
 import Icon from "@mui/material/Icon";
 import {styled} from "@mui/material/styles";
 import Table from "@mui/material/Table";
-import TableBody from "@mui/material/TableBody";
 import TableContainer from "@mui/material/TableContainer";
-import TableRow from "@mui/material/TableRow";
 import Tooltip from "@mui/material/Tooltip";
 import parse from "html-react-parser";
-import React, {useEffect, useMemo, useState} from "react";
-import {useAsyncDebounce, useExpanded, useGlobalFilter, usePagination, useSortBy, useTable} from "react-table";
 import colors from "qqq/assets/theme/base/colors";
 import MDInput from "qqq/components/legacy/MDInput";
 import MDPagination from "qqq/components/legacy/MDPagination";
@@ -43,6 +38,8 @@ import DefaultCell from "qqq/components/widgets/tables/cells/DefaultCell";
 import ImageCell from "qqq/components/widgets/tables/cells/ImageCell";
 import {TableDataInput} from "qqq/components/widgets/tables/TableCard";
 import WidgetBlock from "qqq/components/widgets/WidgetBlock";
+import React, {useEffect, useMemo, useState} from "react";
+import {useAsyncDebounce, useExpanded, useGlobalFilter, usePagination, useSortBy, useTable} from "react-table";
 
 interface Props
 {
@@ -106,17 +103,17 @@ function DataTable({
    entries = entriesPerPageOptions ? entriesPerPageOptions : ["10", "25", "50", "100"];
 
    let widths = [];
-   for(let i = 0; i<table.columns.length; i++)
+   for (let i = 0; i < table.columns.length; i++)
    {
       const column = table.columns[i];
-      if(column.type !== "hidden")
+      if (column.type !== "hidden")
       {
          widths.push(table.columns[i].width ?? "1fr");
       }
    }
 
    let showExpandColumn = false;
-   if(table.rows)
+   if (table.rows)
    {
       for (let i = 0; i < table.rows.length; i++)
       {
@@ -129,7 +126,7 @@ function DataTable({
    }
 
    const columnsToMemo = [...table.columns];
-   if(showExpandColumn)
+   if (showExpandColumn)
    {
       widths.push("60px");
       columnsToMemo.push(
@@ -166,18 +163,18 @@ function DataTable({
                      })}
                   >
                      {/* float this icon to keep it "out of the flow" - in other words, to keep it from making the row taller than it otherwise would be... */}
-                     <Icon fontSize="medium" sx={{float: "left"}}>{row.isExpanded ? "expand_less" : "chevron_right"}</Icon>
+                     <Icon fontSize="medium" sx={{float: "left"}}>{row.isExpanded ? "expand_less" : "chevron_left"}</Icon>
                   </span>
                ) : null,
          },
       );
    }
 
-   if(table.columnHeaderTooltips)
+   if (table.columnHeaderTooltips)
    {
       for (let column of columnsToMemo)
       {
-         if(table.columnHeaderTooltips[column.accessor])
+         if (table.columnHeaderTooltips[column.accessor])
          {
             column.tooltip = table.columnHeaderTooltips[column.accessor];
          }
@@ -297,7 +294,7 @@ function DataTable({
    }
 
    let visibleFooterRows = 1;
-   if(expanded && expanded[`${table.rows.length-1}`])
+   if (expanded && expanded[`${table.rows.length - 1}`])
    {
       //////////////////////////////////////////////////
       // todo - should count how many are expanded... //
@@ -308,156 +305,152 @@ function DataTable({
    function getTable(includeHead: boolean, rows: any, isFooter: boolean)
    {
       let boxStyle = {};
-      if(fixedStickyLastRow)
+      if (fixedStickyLastRow)
       {
          boxStyle = isFooter
             ? {borderTop: `0.0625rem solid ${colors.grayLines.main};`, backgroundColor: "#EEEEEE"}
-            : {flexGrow: 1, overflowY: "scroll", scrollbarGutter: "stable", marginBottom: "-1px"};
+            : {height: fixedHeight ? `${fixedHeight}px` : "auto", flexGrow: 1, overflowY: "scroll", scrollbarGutter: "stable", marginBottom: "-1px"};
       }
 
       let innerBoxStyle = {};
-      if(fixedStickyLastRow && isFooter)
+      if (fixedStickyLastRow && isFooter)
       {
          innerBoxStyle = {overflowY: "auto", scrollbarGutter: "stable"};
       }
 
+      ///////////////////////////////////////////////////////////////////////////////////
+      // note - at one point, we had the table's sx including: whiteSpace: "nowrap"... //
+      ///////////////////////////////////////////////////////////////////////////////////
       return <Box sx={boxStyle}><Box sx={innerBoxStyle}>
-         <Table {...getTableProps()}>
+         <Table {...getTableProps()} component="div" sx={{display: "grid", gridTemplateRows: "auto", gridTemplateColumns: gridTemplateColumns}}>
             {
                includeHead && (
-                  <Box component="thead" sx={{position: "sticky", top: 0, background: "white", zIndex: 10}}>
-                     {headerGroups.map((headerGroup: any, i: number) => (
-                        <TableRow key={i} {...headerGroup.getHeaderGroupProps()} sx={{display: "grid", gridTemplateColumns: gridTemplateColumns}}>
-                           {headerGroup.headers.map((column: any) => (
-                              column.type !== "hidden" && (
-                                 <DataTableHeadCell
-                                    key={i++}
-                                    {...column.getHeaderProps(isSorted && column.getSortByToggleProps())}
-                                    align={column.align ? column.align : "left"}
-                                    sorted={setSortedValue(column)}
-                                    tooltip={column.tooltip}
-                                 >
-                                    {column.render("header")}
-                                 </DataTableHeadCell>
-                              )
-                           ))}
-                        </TableRow>
-                     ))}
-                  </Box>
+                  headerGroups.map((headerGroup: any, i: number) => (
+                     headerGroup.headers.map((column: any) => (
+                        column.type !== "hidden" && (
+                           <DataTableHeadCell
+                              sx={{position: "sticky", top: 0, background: "white", zIndex: 10, alignItems: "flex-end"}}
+                              key={i++}
+                              {...column.getHeaderProps(isSorted && column.getSortByToggleProps())}
+                              align={column.align ? column.align : "left"}
+                              sorted={setSortedValue(column)}
+                              tooltip={column.tooltip}
+                           >
+                              {column.render("header")}
+                           </DataTableHeadCell>
+                        )
+                     ))
+                  ))
                )
             }
-            <TableBody {...getTableBodyProps()}>
-               {rows.map((row: any, key: any) =>
+            {rows.map((row: any, key: any) =>
+            {
+               prepareRow(row);
+
+               let overrideNoEndBorder = false;
+
+               //////////////////////////////////////////////////////////////////////////////////
+               // don't do an end-border on nested rows - unless they're the last one in a set //
+               //////////////////////////////////////////////////////////////////////////////////
+               if (row.depth > 0)
                {
-                  prepareRow(row);
-
-                  let overrideNoEndBorder = false;
-
-                  //////////////////////////////////////////////////////////////////////////////////
-                  // don't do an end-border on nested rows - unless they're the last one in a set //
-                  //////////////////////////////////////////////////////////////////////////////////
-                  if(row.depth > 0)
+                  overrideNoEndBorder = true;
+                  if (key + 1 < rows.length && rows[key + 1].depth == 0)
                   {
-                     overrideNoEndBorder = true;
-                     if(key + 1 < rows.length && rows[key + 1].depth == 0)
-                     {
-                        overrideNoEndBorder = false;
-                     }
+                     overrideNoEndBorder = false;
                   }
+               }
 
-                  ///////////////////////////////////////
-                  // don't do end-border on the footer //
-                  ///////////////////////////////////////
-                  if(isFooter)
-                  {
-                     overrideNoEndBorder = true;
-                  }
+               ///////////////////////////////////////
+               // don't do end-border on the footer //
+               ///////////////////////////////////////
+               if (isFooter)
+               {
+                  overrideNoEndBorder = true;
+               }
 
-                  let background = "initial";
-                  if(isFooter)
-                  {
-                     background = "#EEEEEE";
-                  }
-                  else if(row.depth > 0 || row.isExpanded)
-                  {
-                     background = "#FAFAFA";
-                  }
+               let background = "initial";
+               if (isFooter)
+               {
+                  background = "#EEEEEE";
+               }
+               else if (row.depth > 0 || row.isExpanded)
+               {
+                  background = "#FAFAFA";
+               }
 
-                  return (
-                     <TableRow sx={{verticalAlign: "top", display: "grid", gridTemplateColumns: gridTemplateColumns, background: background}} key={key} {...row.getRowProps()}>
-                        {row.cells.map((cell: any) => (
-                           cell.column.type !== "hidden" && (
-                              <DataTableBodyCell
-                                 key={key}
-                                 noBorder={noEndBorder || overrideNoEndBorder || row.isExpanded}
-                                 depth={row.depth}
-                                 align={cell.column.align ? cell.column.align : "left"}
-                                 {...cell.getCellProps()}
-                              >
-                                 {
-                                    cell.column.type === "default" && (
-                                       cell.value && "number" === typeof cell.value ? (
-                                          <DefaultCell isFooter={isFooter}>{cell.value.toLocaleString()}</DefaultCell>
-                                       ) : (<DefaultCell isFooter={isFooter}>{cell.render("Cell")}</DefaultCell>)
-                                    )
-                                 }
-                                 {
-                                    cell.column.type === "htmlAndTooltip" && (
-                                       <DefaultCell isFooter={isFooter}>
-                                          <NoMaxWidthTooltip title={parse(row.values["tooltip"])}>
-                                             <Box>
-                                                {parse(cell.value)}
-                                             </Box>
-                                          </NoMaxWidthTooltip>
-                                       </DefaultCell>
-                                    )
-                                 }
-                                 {
-                                    cell.column.type === "html" && (
-                                       <DefaultCell isFooter={isFooter}>{parse(cell.value ?? "")}</DefaultCell>
-                                    )
-                                 }
-                                 {
-                                    cell.column.type === "composite" && (
-                                       <DefaultCell isFooter={isFooter}>
-                                          <CompositeWidget widgetMetaData={widgetMetaData} data={cell.value} />
-                                       </DefaultCell>
-                                    )
-                                 }
-                                 {
-                                    cell.column.type === "block" && (
-                                       <DefaultCell isFooter={isFooter}>
-                                          <WidgetBlock widgetMetaData={widgetMetaData} block={cell.value} />
-                                       </DefaultCell>
-                                    )
-                                 }
-                                 {
-                                    cell.column.type === "image" && row.values["imageTotal"] && (
-                                       <ImageCell imageUrl={row.values["imageUrl"]} label={row.values["imageLabel"]} total={row.values["imageTotal"].toLocaleString()} totalType={row.values["imageTotalType"]} />
-                                    )
-                                 }
-                                 {
-                                    cell.column.type === "image" && !row.values["imageTotal"] && (
-                                       <ImageCell imageUrl={row.values["imageUrl"]} label={row.values["imageLabel"]} />
-                                    )
-                                 }
-                                 {
-                                    (cell.column.id === "__expander") && cell.render("cell")
-                                 }
-                              </DataTableBodyCell>
-                           )
-                        ))}
-                     </TableRow>
-                  );
-               })}
-
-            </TableBody>
+               return (
+                  row.cells.map((cell: any) => (
+                     cell.column.type !== "hidden" && (
+                        <DataTableBodyCell
+                           key={key}
+                           sx={{verticalAlign: "top", background: background}}
+                           noBorder={noEndBorder || overrideNoEndBorder || row.isExpanded}
+                           depth={row.depth}
+                           align={cell.column.align ? cell.column.align : "left"}
+                           {...cell.getCellProps()}
+                        >
+                           {
+                              cell.column.type === "default" && (
+                                 cell.value && "number" === typeof cell.value ? (
+                                    <DefaultCell isFooter={isFooter}>{cell.value.toLocaleString()}</DefaultCell>
+                                 ) : (<DefaultCell isFooter={isFooter}>{cell.render("Cell")}</DefaultCell>)
+                              )
+                           }
+                           {
+                              cell.column.type === "htmlAndTooltip" && (
+                                 <DefaultCell isFooter={isFooter}>
+                                    <NoMaxWidthTooltip title={parse(row.values["tooltip"])}>
+                                       <Box>
+                                          {parse(cell.value)}
+                                       </Box>
+                                    </NoMaxWidthTooltip>
+                                 </DefaultCell>
+                              )
+                           }
+                           {
+                              cell.column.type === "html" && (
+                                 <DefaultCell isFooter={isFooter}>{parse(cell.value ?? "")}</DefaultCell>
+                              )
+                           }
+                           {
+                              cell.column.type === "composite" && (
+                                 <DefaultCell isFooter={isFooter}>
+                                    <CompositeWidget widgetMetaData={widgetMetaData} data={cell.value} />
+                                 </DefaultCell>
+                              )
+                           }
+                           {
+                              cell.column.type === "block" && (
+                                 <DefaultCell isFooter={isFooter}>
+                                    <WidgetBlock widgetMetaData={widgetMetaData} block={cell.value} />
+                                 </DefaultCell>
+                              )
+                           }
+                           {
+                              cell.column.type === "image" && row.values["imageTotal"] && (
+                                 <ImageCell imageUrl={row.values["imageUrl"]} label={row.values["imageLabel"]} total={row.values["imageTotal"].toLocaleString()} totalType={row.values["imageTotalType"]} />
+                              )
+                           }
+                           {
+                              cell.column.type === "image" && !row.values["imageTotal"] && (
+                                 <ImageCell imageUrl={row.values["imageUrl"]} label={row.values["imageLabel"]} />
+                              )
+                           }
+                           {
+                              (cell.column.id === "__expander") && cell.render("cell")
+                           }
+                        </DataTableBodyCell>
+                     )
+                  ))
+               );
+            })}
          </Table>
-      </Box></Box>
+      </Box></Box>;
    }
 
    return (
-      <TableContainer sx={{boxShadow: "none", height: fixedHeight ? `${fixedHeight}px` : "auto"}}>
+      <TableContainer sx={{boxShadow: "none", height: (fixedHeight && !fixedStickyLastRow) ? `${fixedHeight}px` : "auto"}}>
          {entriesPerPage && ((hidePaginationDropdown !== undefined && !hidePaginationDropdown) || canSearch) ? (
             <Box display="flex" justifyContent="space-between" alignItems="center" p={3}>
                {entriesPerPage && (hidePaginationDropdown === undefined || !hidePaginationDropdown) && (

src/qqq/components/widgets/tables/ModalEditForm.tsx

@@ -0,0 +1,96 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2022.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+import {QTableMetaData} from "@kingsrook/qqq-frontend-core/lib/model/metaData/QTableMetaData";
+import Modal from "@mui/material/Modal";
+import EntityForm from "qqq/components/forms/EntityForm";
+import Client from "qqq/utils/qqq/Client";
+import React, {useEffect, useReducer, useState} from "react";
+
+
+////////////////////////////////
+// structure of expected data //
+////////////////////////////////
+export interface ModalEditFormData
+{
+   tableName: string;
+   defaultValues?: { [key: string]: string };
+   disabledFields?: { [key: string]: boolean } | string[];
+   overrideHeading?: string;
+   onSubmitCallback?: (values: any, tableName: String) => void;
+   initialShowModalValue?: boolean;
+}
+
+const qController = Client.getInstance();
+
+function ModalEditForm({tableName, defaultValues, disabledFields, overrideHeading, onSubmitCallback, initialShowModalValue}: ModalEditFormData,): JSX.Element
+{
+   const [showModal, setShowModal] = useState(initialShowModalValue);
+   const [table, setTable] = useState(null as QTableMetaData);
+   const [, forceUpdate] = useReducer((x) => x + 1, 0);
+
+   useEffect(() =>
+   {
+      if (!tableName)
+      {
+         return;
+      }
+
+      (async () =>
+      {
+         const tableMetaData = await qController.loadTableMetaData(tableName);
+         setTable(tableMetaData);
+         forceUpdate();
+      })();
+   }, [tableName]);
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   const closeEditChildForm = (event: object, reason: string) =>
+   {
+      if (reason === "backdropClick" || reason === "escapeKeyDown")
+      {
+         return;
+      }
+
+      setShowModal(null);
+   };
+
+   return (
+      table && showModal &&
+      <Modal open={showModal as boolean} onClose={(event, reason) => closeEditChildForm(event, reason)}>
+         <div className="modalEditForm">
+            <EntityForm
+               isModal={true}
+               closeModalHandler={closeEditChildForm}
+               table={table}
+               defaultValues={defaultValues}
+               disabledFields={disabledFields}
+               onSubmitCallback={onSubmitCallback}
+               overrideHeading={overrideHeading}
+            />
+         </div>
+      </Modal>
+   );
+}
+
+export default ModalEditForm;

src/qqq/components/widgets/tables/TableCard.tsx

@@ -28,13 +28,13 @@ import TableBody from "@mui/material/TableBody";
 import TableContainer from "@mui/material/TableContainer";
 import TableRow from "@mui/material/TableRow";
 import parse from "html-react-parser";
-import React, {useEffect, useState} from "react";
 import MDTypography from "qqq/components/legacy/MDTypography";
 import DataTableBodyCell from "qqq/components/widgets/tables/cells/DataTableBodyCell";
 import DataTableHeadCell from "qqq/components/widgets/tables/cells/DataTableHeadCell";
 import DefaultCell from "qqq/components/widgets/tables/cells/DefaultCell";
 import DataTable from "qqq/components/widgets/tables/DataTable";
 import Client from "qqq/utils/qqq/Client";
+import React, {useEffect, useState} from "react";
 
 
 //////////////////////////////////////
@@ -43,7 +43,7 @@ import Client from "qqq/utils/qqq/Client";
 export interface TableDataInput
 {
    columns: { [key: string]: any }[];
-   columnHeaderTooltips?: { [columnName: string]: string | JSX.Element }
+   columnHeaderTooltips?: { [columnName: string]: string | JSX.Element };
    rows: { [key: string]: any }[];
 }
 
@@ -63,6 +63,7 @@ interface Props
 }
 
 const qController = Client.getInstance();
+
 function TableCard({noRowsFoundHTML, data, rowsPerPage, hidePaginationDropdown, fixedStickyLastRow, fixedHeight, widgetMetaData}: Props): JSX.Element
 {
    const [qInstance, setQInstance] = useState(null as QInstance);
@@ -92,41 +93,25 @@ function TableCard({noRowsFoundHTML, data, rowsPerPage, hidePaginationDropdown,
                />
                : noRowsFoundHTML ?
                   <Box p={3} pt={0} pb={3} sx={{textAlign: "center"}}>
-                     <MDTypography
-                        variant="subtitle2"
-                        color="secondary"
-                        fontWeight="regular"
-                     >
-                        {
-                           noRowsFoundHTML ? (
-                              parse(noRowsFoundHTML)
-                           ) : "No rows found"
-                        }
+                     <MDTypography variant="subtitle2" color="secondary" fontWeight="regular">
+                        {noRowsFoundHTML ? (parse(noRowsFoundHTML)) : "No rows found"}
                      </MDTypography>
                   </Box>
                   :
                   <TableContainer sx={{boxShadow: "none"}}>
-                     <Table>
-                        <Box component="thead">
-                           <TableRow key="header">
-                              {Array(8).fill(0).map((_, i) =>
-                                 <DataTableHeadCell key={`head-${i}`} sorted={false} width="auto" align="center">
-                                    <Skeleton width="100%" />
-                                 </DataTableHeadCell>
-                              )}
-                           </TableRow>
-                        </Box>
-                        <TableBody>
-                           {Array(5).fill(0).map((_, i) =>
-                              <TableRow sx={{verticalAlign: "top"}} key={`row-${i}`}>
-                                 {Array(8).fill(0).map((_, j) =>
-                                    <DataTableBodyCell key={`cell-${i}-${j}`} align="center">
-                                       <DefaultCell isFooter={false}><Skeleton /></DefaultCell>
-                                    </DataTableBodyCell>
-                                 )}
-                              </TableRow>
-                           )}
-                        </TableBody>
+                     <Table component="div" sx={{display: "grid", gridTemplateRows: "auto", gridTemplateColumns: "1fr 1fr 1fr 1fr 1fr 1fr 1fr 1fr"}}>
+                        {Array(8).fill(0).map((_, i) =>
+                           <DataTableHeadCell key={`head-${i}`} sorted={false} width="auto" align="center">
+                              <Skeleton width="100%" />
+                           </DataTableHeadCell>
+                        )}
+                        {Array(5).fill(0).map((_, i) =>
+                           Array(8).fill(0).map((_, j) =>
+                              <DataTableBodyCell key={`cell-${i}-${j}`} align="center">
+                                 <DefaultCell isFooter={false}><Skeleton /></DefaultCell>
+                              </DataTableBodyCell>
+                           )
+                        )}
                      </Table>
                   </TableContainer>
          }

src/qqq/components/widgets/tables/TableWidget.tsx

@@ -23,7 +23,6 @@
 import {QWidgetMetaData} from "@kingsrook/qqq-frontend-core/lib/model/metaData/QWidgetMetaData";
 // @ts-ignore
 import {htmlToText} from "html-to-text";
-import React, {useContext, useEffect, useState} from "react";
 import QContext from "QContext";
 import HelpContent, {hasHelpContent} from "qqq/components/misc/HelpContent";
 import TableCard from "qqq/components/widgets/tables/TableCard";
@@ -31,6 +30,7 @@ import Widget, {WidgetData} from "qqq/components/widgets/Widget";
 import {WidgetUtils} from "qqq/components/widgets/WidgetUtils";
 import HtmlUtils from "qqq/utils/HtmlUtils";
 import ValueUtils from "qqq/utils/qqq/ValueUtils";
+import React, {useContext, useEffect, useState} from "react";
 
 interface Props
 {
@@ -40,8 +40,7 @@ interface Props
    isChild?: boolean;
 }
 
-TableWidget.defaultProps = {
-};
+TableWidget.defaultProps = {};
 
 function TableWidget(props: Props): JSX.Element
 {
@@ -86,7 +85,7 @@ function TableWidget(props: Props): JSX.Element
 
                const cell = rows[i][columns[j].accessor];
                let text = cell;
-               if(columns[j].type != "default")
+               if (columns[j].type != "default")
                {
                   text = htmlToText(cell,
                      {
@@ -105,7 +104,7 @@ function TableWidget(props: Props): JSX.Element
          setCsv(csv);
 
          const fileName = WidgetUtils.makeExportFileName(props.widgetData, props.widgetMetaData);
-         setFileName(fileName)
+         setFileName(fileName);
 
          console.log(`useEffect, setting fileName ${fileName}`);
       }
@@ -114,24 +113,28 @@ function TableWidget(props: Props): JSX.Element
 
    const onExportClick = () =>
    {
-      if(props.widgetData?.csvData)
+      if (props.widgetData?.csvData)
       {
          const csv = WidgetUtils.widgetCsvDataToString(props.widgetData);
          const fileName = WidgetUtils.makeExportFileName(props.widgetData, props.widgetMetaData);
          HtmlUtils.download(fileName, csv);
       }
-      else if(csv)
+      else if (csv)
       {
          HtmlUtils.download(fileName, csv);
       }
       else
       {
-         alert("There is no data available to export.")
+         alert("There is no data available to export.");
       }
-   }
+   };
 
    const labelAdditionalElementsLeft: JSX.Element[] = [];
-   if(props.widgetMetaData?.showExportButton)
+   if (props.widgetData?.linkText && props.widgetData?.linkURL)
+   {
+      labelAdditionalElementsLeft.push(WidgetUtils.generateLabelLink(props.widgetData?.linkText, props.widgetData?.linkURL));
+   }
+   if (props.widgetMetaData?.showExportButton)
    {
       labelAdditionalElementsLeft.push(WidgetUtils.generateExportButton(onExportClick));
    }
@@ -139,14 +142,14 @@ function TableWidget(props: Props): JSX.Element
    //////////////////////////////////////////////////////
    // look for column-header tooltips from helpContent //
    //////////////////////////////////////////////////////
-   const columnHeaderTooltips: {[columnName: string]: JSX.Element} = {}
+   const columnHeaderTooltips: { [columnName: string]: JSX.Element } = {};
    for (let column of props.widgetData?.columns ?? [])
    {
-      const helpRoles = ["ALL_SCREENS"]
+      const helpRoles = ["ALL_SCREENS"];
       const slotName = `columnHeader=${column.accessor}`;
       const showHelp = helpHelpActive || hasHelpContent(props.widgetMetaData?.helpContent?.get(slotName), helpRoles);
 
-      if(showHelp)
+      if (showHelp)
       {
          const formattedHelpContent = <HelpContent helpContents={props.widgetMetaData?.helpContent?.get(slotName)} roles={helpRoles} helpContentKey={`widget:${props.widgetMetaData?.name};slot:${slotName}`} />;
          columnHeaderTooltips[column.accessor] = formattedHelpContent;

src/qqq/components/widgets/tables/cells/DataTableBodyCell.tsx

@@ -19,7 +19,7 @@
  * along with this program.  If not, see <https://www.gnu.org/licenses/>.
  */
 
-import Box from "@mui/material/Box";
+import {Box} from "@mui/material";
 import {Theme} from "@mui/material/styles";
 import colors from "qqq/assets/theme/base/colors";
 import {ReactNode} from "react";
@@ -30,13 +30,14 @@ interface Props
    children: ReactNode;
    noBorder?: boolean;
    align?: "left" | "right" | "center";
+   sx?: any;
 }
 
-function DataTableBodyCell({noBorder, align, children}: Props): JSX.Element
+function DataTableBodyCell({noBorder, align, sx, children}: Props): JSX.Element
 {
    return (
       <Box
-         component="td"
+         component="div"
          textAlign={align}
          py={1.5}
          px={1.5}
@@ -54,7 +55,7 @@ function DataTableBodyCell({noBorder, align, children}: Props): JSX.Element
             },
             "&:last-child": {
                paddingRight: "1rem"
-            }
+            }, ...sx
          })}
       >
          <Box
@@ -72,6 +73,7 @@ function DataTableBodyCell({noBorder, align, children}: Props): JSX.Element
 DataTableBodyCell.defaultProps = {
    noBorder: false,
    align: "left",
+   sx: {}
 };
 
 export default DataTableBodyCell;

src/qqq/components/widgets/tables/cells/DataTableHeadCell.tsx

@@ -44,18 +44,14 @@ function DataTableHeadCell({width, children, sorted, align, tooltip, ...rest}: P
 
    return (
       <Box
-         component="th"
+         component="div"
          width={width}
          py={1.5}
          px={1.5}
          sx={({palette: {light}, borders: {borderWidth}}: Theme) => ({
             borderBottom: `${borderWidth[1]} solid ${colors.grayLines.main}`,
-            "&:nth-of-type(1)": {
-               paddingLeft: "1rem"
-            },
-            "&:last-child": {
-               paddingRight: "1rem"
-            },
+            position: "sticky", top: 0, background: "white",
+            zIndex: 1 // so if body rows scroll behind it, they don't show through
          })}
       >
          <Box

src/qqq/layouts/BaseLayout.tsx

@@ -21,11 +21,12 @@
 
 import {QInstance} from "@kingsrook/qqq-frontend-core/lib/model/metaData/QInstance";
 import Box from "@mui/material/Box";
-import {ReactNode, useEffect, useState} from "react";
 import Footer from "qqq/components/horseshoe/Footer";
 import NavBar from "qqq/components/horseshoe/NavBar";
+import {getBannerClassName, getBannerStyles, getBanner, makeBannerContent} from "qqq/components/misc/Banners";
 import DashboardLayout from "qqq/layouts/DashboardLayout";
 import Client from "qqq/utils/qqq/Client";
+import {ReactNode, useEffect, useState} from "react";
 
 interface Props
 {
@@ -80,12 +81,34 @@ function BaseLayout({stickyNavbar, children}: Props): JSX.Element
       return () => window.removeEventListener("resize", handleTabsOrientation);
    }, [tabsOrientation]);
 
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   function banner(): JSX.Element | null
+   {
+      const banner = getBanner(metaData?.branding, "QFMD_TOP_OF_BODY");
+
+      if (!banner)
+      {
+         return (null);
+      }
+
+      return (<Box className={getBannerClassName(banner)} sx={{display: "flex", justifyContent: "center", padding: "0.5rem", margin: "-20px", marginBottom: "20px", ...getBannerStyles(banner)}}>
+         {makeBannerContent(banner)}
+      </Box>);
+   }
+
+
    return (
-      <DashboardLayout>
-         <NavBar />
-         <Box>{children}</Box>
-         <Footer company={{href: metaData?.branding?.companyUrl, name: metaData?.branding?.companyName}} />
-      </DashboardLayout>
+      <>
+         <DashboardLayout>
+            {banner()}
+            <NavBar />
+            <Box>{children}</Box>
+            <Footer company={{href: metaData?.branding?.companyUrl, name: metaData?.branding?.companyName}} />
+         </DashboardLayout>
+      </>
    );
 }
 

src/qqq/models/fields/FieldPossibleValueProps.ts

@@ -0,0 +1,40 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2024.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+import {QPossibleValue} from "@kingsrook/qqq-frontend-core/lib/model/QPossibleValue";
+import {QQueryFilter} from "@kingsrook/qqq-frontend-core/lib/model/query/QQueryFilter";
+
+/*******************************************************************************
+ ** Properties attached to a (formik?) form field, to denote how it behaves as
+ ** as related to a possible value source.
+ *******************************************************************************/
+export interface FieldPossibleValueProps
+{
+   isPossibleValue?: boolean;
+   possibleValues?: QPossibleValue[];
+   initialDisplayValue: string | null;
+   fieldName?: string;
+   tableName?: string;
+   processName?: string;
+   possibleValueSourceName?: string;
+   possibleValueSourceFilter?: QQueryFilter;
+}
+