Feature/tcoz dev updated (#1051)

* Update README.md

Some notes for people that might want to run full-on native, with detail about how Mac hijacks port 7000 and how to get around it.

* Revert "Update README.md"

This reverts commit 096887c26d.

* README update and native code patch

Some details for user that might be running Python3, Mac, and want to run everything locally/natively.

* Implement basic tooltips

Uses MUI tooltip, as it behaves more predictably with existing styling, and enables top-level theme config.

Top-level configuration for all MUI components can be controlled via overriding the existing theme. See index.tsx. This could be done per user for customization, etc.

Enabling JSON module imports in tsconfig.json seemed to fix the error in ReactDiagramEditor

* get docs from main that have already been merged from tcoz and tweaked

* created SpiffTooltip component so we can change how tooltips operate across the board w/ burnettk

* update tooltip title copy

* remove arrow not needed in caller

* types and wording

---------

Co-authored-by: Tim Consolazio <tcoz@tcoz.com>
Co-authored-by: burnettk <burnettk@users.noreply.github.com>
Co-authored-by: jasquat <jasquat@users.noreply.github.com>

spiffworkflow-frontend/src/components/NavigationBar.tsx

@@ -31,6 +31,7 @@ import { DOCUMENTATION_URL, SPIFF_ENVIRONMENT } from '../config';
 import appVersionInfo from '../helpers/appVersionInfo';
 import { slugifyString } from '../helpers';
 import ExtensionUxElementForDisplay from './ExtensionUxElementForDisplay';
+import SpiffTooltip from './SpiffTooltip';
 
 type OwnProps = {
   extensionUxElements?: UiSchemaUxElement[] | null;
@@ -192,12 +193,14 @@ export default function NavigationBar({ extensionUxElements }: OwnProps) {
               {(secretAllowed: boolean) => {
                 if (secretAllowed || authenticationAllowed) {
                   return (
-                    <HeaderMenuItem
-                      href="/configuration"
-                      isCurrentPage={isActivePage('/configuration')}
-                    >
-                      Configuration
-                    </HeaderMenuItem>
+                    <SpiffTooltip title="Manage Secrets and Authentication information for Service Tasks">
+                      <HeaderMenuItem
+                        href="/configuration"
+                        isCurrentPage={isActivePage('/configuration')}
+                      >
+                        Configuration
+                      </HeaderMenuItem>
+                    </SpiffTooltip>
                   );
                 }
                 return null;
@@ -216,13 +219,15 @@ export default function NavigationBar({ extensionUxElements }: OwnProps) {
       setActiveKey(navItemPage);
     }
     return (
-      <HeaderMenuItem
-        href={navItemPage}
-        isCurrentPage={isActivePage(navItemPage)}
-        data-qa={`extension-${slugifyString(uxElement.label)}`}
-      >
-        {uxElement.label}
-      </HeaderMenuItem>
+      <SpiffTooltip title={uxElement?.tooltip}>
+        <HeaderMenuItem
+          href={navItemPage}
+          isCurrentPage={isActivePage(navItemPage)}
+          data-qa={`extension-${slugifyString(uxElement.label)}`}
+        >
+          {uxElement.label}
+        </HeaderMenuItem>
+      </SpiffTooltip>
     );
   };
 
@@ -232,45 +237,55 @@ export default function NavigationBar({ extensionUxElements }: OwnProps) {
     }
     return (
       <>
-        <HeaderMenuItem href="/" isCurrentPage={isActivePage('/')}>
-          Home
-        </HeaderMenuItem>
-        <Can I="GET" a={targetUris.processGroupListPath} ability={ability}>
-          <HeaderMenuItem
-            href={processGroupPath}
-            isCurrentPage={isActivePage(processGroupPath)}
-            data-qa="header-nav-processes"
-          >
-            Processes
+        <SpiffTooltip title="View and start Process Instances">
+          <HeaderMenuItem href="/" isCurrentPage={isActivePage('/')}>
+            <div>Home</div>
           </HeaderMenuItem>
+        </SpiffTooltip>
+        <Can I="GET" a={targetUris.processGroupListPath} ability={ability}>
+          <SpiffTooltip title="Find and organize Process Groups and Process Models">
+            <HeaderMenuItem
+              href={processGroupPath}
+              isCurrentPage={isActivePage(processGroupPath)}
+              data-qa="header-nav-processes"
+            >
+              Processes
+            </HeaderMenuItem>
+          </SpiffTooltip>
         </Can>
         <Can
           I="POST"
           a={targetUris.processInstanceListForMePath}
           ability={ability}
         >
-          <HeaderMenuItem
-            href="/process-instances"
-            isCurrentPage={isActivePage('/process-instances')}
-          >
-            Process Instances
-          </HeaderMenuItem>
+          <SpiffTooltip title="List of active and completed Process Instances">
+            <HeaderMenuItem
+              href="/process-instances"
+              isCurrentPage={isActivePage('/process-instances')}
+            >
+              Process Instances
+            </HeaderMenuItem>
+          </SpiffTooltip>
         </Can>
         <Can I="GET" a={targetUris.messageInstanceListPath} ability={ability}>
-          <HeaderMenuItem
-            href="/messages"
-            isCurrentPage={isActivePage('/messages')}
-          >
-            Messages
-          </HeaderMenuItem>
+          <SpiffTooltip title="Browse messages being sent and received">
+            <HeaderMenuItem
+              href="/messages"
+              isCurrentPage={isActivePage('/messages')}
+            >
+              Messages
+            </HeaderMenuItem>
+          </SpiffTooltip>
         </Can>
         <Can I="GET" a={targetUris.dataStoreListPath} ability={ability}>
-          <HeaderMenuItem
-            href="/data-stores"
-            isCurrentPage={isActivePage('/data-stores')}
-          >
-            Data Stores
-          </HeaderMenuItem>
+          <SpiffTooltip title="Browse data that has been saved to Data Stores">
+            <HeaderMenuItem
+              href="/data-stores"
+              isCurrentPage={isActivePage('/data-stores')}
+            >
+              Data Stores
+            </HeaderMenuItem>
+          </SpiffTooltip>
         </Can>
         {configurationElement()}
         <ExtensionUxElementForDisplay

spiffworkflow-frontend/src/components/ProcessInstanceListTabs.tsx

@@ -5,6 +5,7 @@ import { useNavigate } from 'react-router-dom';
 import { usePermissionFetcher } from '../hooks/PermissionService';
 import { useUriListForPermissions } from '../hooks/UriListForPermissions';
 import { PermissionsToCheck } from '../interfaces';
+import SpiffTooltip from './SpiffTooltip';
 
 type OwnProps = {
   variant: string;
@@ -28,35 +29,38 @@ export default function ProcessInstanceListTabs({ variant }: OwnProps) {
   return (
     <Tabs selectedIndex={selectedTabIndex}>
       <TabList aria-label="List of tabs">
-        <Tab
-          title="Only show process instances for the current user."
-          data-qa="process-instance-list-for-me"
-          onClick={() => {
-            navigate('/process-instances/for-me');
-          }}
-        >
-          For Me
-        </Tab>
-        <Can I="GET" a={targetUris.processInstanceListPath} ability={ability}>
+        <SpiffTooltip title="Only show process instances for the current user">
           <Tab
-            title="Show all process instances for all users."
-            data-qa="process-instance-list-all"
+            data-qa="process-instance-list-for-me"
             onClick={() => {
-              navigate('/process-instances/all');
+              navigate('/process-instances/for-me');
             }}
           >
-            All
+            For Me
           </Tab>
+        </SpiffTooltip>
+        <Can I="GET" a={targetUris.processInstanceListPath} ability={ability}>
+          <SpiffTooltip title="Show process instances for all users">
+            <Tab
+              data-qa="process-instance-list-all"
+              onClick={() => {
+                navigate('/process-instances/all');
+              }}
+            >
+              All
+            </Tab>
+          </SpiffTooltip>
         </Can>
-        <Tab
-          title="Search for a process instance by id."
-          data-qa="process-instance-list-find-by-id"
-          onClick={() => {
-            navigate('/process-instances/find-by-id');
-          }}
-        >
-          Find By Id
-        </Tab>
+        <SpiffTooltip title="Search for a process instance by id">
+          <Tab
+            data-qa="process-instance-list-find-by-id"
+            onClick={() => {
+              navigate('/process-instances/find-by-id');
+            }}
+          >
+            Find By Id
+          </Tab>
+        </SpiffTooltip>
       </TabList>
     </Tabs>
   );

spiffworkflow-frontend/src/components/ReactDiagramEditor.tsx

@@ -38,7 +38,6 @@ import 'dmn-js-properties-panel/dist/assets/properties-panel.css';
 import spiffworkflow from 'bpmn-js-spiffworkflow/app/spiffworkflow';
 import 'bpmn-js-spiffworkflow/app/css/app.css';
 
-// @ts-expect-error TS(7016) FIXME
 import spiffModdleExtension from 'bpmn-js-spiffworkflow/app/spiffworkflow/moddle/spiffworkflow.json';
 
 // @ts-expect-error TS(7016) FIXME

spiffworkflow-frontend/src/components/SpiffTabs.tsx

@@ -2,6 +2,7 @@ import { useEffect, useState } from 'react';
 import { useLocation, useNavigate } from 'react-router-dom';
 import { Tabs, TabList, Tab } from '@carbon/react';
 import { SpiffTab } from '../interfaces';
+import SpiffTooltip from './SpiffTooltip';
 
 type OwnProps = {
   tabs: SpiffTab[];
@@ -24,7 +25,11 @@ export default function SpiffTabs({ tabs }: OwnProps) {
 
   const tabComponents = tabs.map((spiffTab: SpiffTab) => {
     return (
-      <Tab onClick={() => navigate(spiffTab.path)}>{spiffTab.display_name}</Tab>
+      <SpiffTooltip title={spiffTab?.tooltip}>
+        <Tab onClick={() => navigate(spiffTab.path)}>
+          {spiffTab.display_name}
+        </Tab>
+      </SpiffTooltip>
     );
   });
 

spiffworkflow-frontend/src/components/SpiffTooltip.tsx

@@ -0,0 +1,18 @@
+// carbon shifts everything but mui doesn't
+// import { Tooltip } from '@carbon/react';
+
+import { Tooltip } from '@mui/material';
+import { ReactElement } from 'react';
+
+interface OwnProps {
+  title?: string;
+  children: ReactElement;
+}
+
+export default function SpiffTooltip({ title, children }: OwnProps) {
+  return (
+    <Tooltip title={title} arrow>
+      {children}
+    </Tooltip>
+  );
+}

spiffworkflow-frontend/src/components/TaskRouteTabs.tsx

@@ -9,9 +9,21 @@ export default function TaskRouteTabs() {
   }
 
   const spiffTabs: SpiffTab[] = [
-    { path: '/tasks/in-progress', display_name: 'In Progress' },
-    { path: '/tasks/completed-instances', display_name: 'Completed' },
-    { path: '/tasks/create-new-instance', display_name: 'Start New +' },
+    {
+      path: '/tasks/in-progress',
+      display_name: 'In Progress',
+      tooltip: 'View running Processes',
+    },
+    {
+      path: '/tasks/completed-instances',
+      display_name: 'Completed',
+      tooltip: 'View completed Processes',
+    },
+    {
+      path: '/tasks/create-new-instance',
+      display_name: 'Start New +',
+      tooltip: 'Find and start a new Process',
+    },
   ];
   return <SpiffTabs tabs={spiffTabs} />;
 }

spiffworkflow-frontend/src/extension_ui_schema_interfaces.ts

@@ -63,6 +63,7 @@ export interface UiSchemaUxElement {
   page: string;
   display_location: UiSchemaDisplayLocation;
   location_specific_configs?: UiSchemaLocationSpecificConfig;
+  tooltip?: string;
 }
 
 export interface UiSchemaForm {

spiffworkflow-frontend/src/index.tsx

@@ -1,19 +1,51 @@
 import React from 'react';
 import * as ReactDOMClient from 'react-dom/client';
+import { createTheme, ThemeProvider } from '@mui/material/styles';
 import App from './App';
 
 import './index.scss';
 import './index.css';
-
 import reportWebVitals from './reportWebVitals';
 
 // @ts-expect-error TS(2345) FIXME: Argument of type 'HTMLElement | null' is not assig... Remove this comment to see the full error message
 const root = ReactDOMClient.createRoot(document.getElementById('root'));
 
+/**
+ * Creates an instance of the MUI theme that can be fed to the top-level ThemeProvider.
+ * Nested ThemeProviders can be used to override specific components.
+ * This override implements a tooltip that fits the overall app theme.
+ */
+const defaultTheme = createTheme();
+const overrideTheme = createTheme({
+  components: {
+    MuiTooltip: {
+      styleOverrides: {
+        arrow: {
+          '&::before': {
+            color: '#F5F5F5',
+            border: '1px solid grey',
+          },
+        },
+        tooltip: {
+          fontSize: '.8em',
+          color: 'black',
+          backgroundColor: '#F5F5F5',
+          padding: '5px',
+          border: '1px solid  grey',
+        },
+      },
+    },
+  },
+});
+
 const doRender = () => {
   root.render(
     <React.StrictMode>
-      <App />
+      <ThemeProvider theme={defaultTheme}>
+        <ThemeProvider theme={overrideTheme}>
+          <App />
+        </ThemeProvider>
+      </ThemeProvider>
     </React.StrictMode>
   );
 };

spiffworkflow-frontend/src/interfaces.ts

@@ -492,6 +492,7 @@ export interface KeyboardShortcuts {
 export interface SpiffTab {
   path: string;
   display_name: string;
+  tooltip?: string;
 }
 
 export interface SpiffTableHeader {

spiffworkflow-frontend/tsconfig.json

@@ -7,6 +7,7 @@
     "skipLibCheck": true,
     "strict": true,
     "target": "es2021",
+    "resolveJsonModule": true,
   },
   "include": ["src/**/*"]
 }