Feat/tutorial provider

.gitignore

@@ -13,6 +13,9 @@
 # testing
 /coverage
 
+# Webstorm user specific settings
+.idea/workspace.xml
+
 # production
 /build
 /storybook-static

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@equinor/amplify-components",
-  "version": "6.2.7",
+  "version": "6.3.0",
   "description": "Frontend Typescript components for the Amplify team",
   "main": "dist/esm/index.js",
   "types": "dist/types/index.d.ts",

src/api/index.ts

@@ -8,8 +8,12 @@ export { request } from './core/request';
 export type { OpenAPIConfig } from './core/OpenAPI';
 
 export type { Feature } from './models/Feature';
+export type { CustomTutorialStep } from './models/CustomTutorialStep';
+export type { GenericTutorialStep } from './models/GenericTutorialStep';
+export type { Tutorial } from './models/Tutorial';
 export type { FeatureToggleDto } from './models/FeatureToggleDto';
 export type { GraphUser } from './models/GraphUser';
 export type { ServiceNowIncidentResponse } from './models/ServiceNowIncidentResponse';
 export type { ServiceNowIncidentAttachmentResponse } from './models/ServiceNowIncidentAttachmentResponse';
+export { TutorialPosition } from './models/TutorialPosition';
 export { ServiceNowUrgency } from './models/ServiceNowUrgency';

src/api/models/CustomTutorialStep.ts

@@ -0,0 +1,10 @@
+/* generated using openapi-typescript-codegen -- do no edit */
+/* istanbul ignore file */
+/* tslint:disable */
+/* eslint-disable */
+
+import { TutorialStepBase } from './TutorialStepBase';
+
+export type CustomTutorialStep = TutorialStepBase & {
+  key: string;
+};

src/api/models/GenericTutorialStep.ts

@@ -0,0 +1,13 @@
+/* generated using openapi-typescript-codegen -- do no edit */
+/* istanbul ignore file */
+/* tslint:disable */
+/* eslint-disable */
+
+import { TutorialStepBase } from './TutorialStepBase';
+
+export type GenericTutorialStep = TutorialStepBase & {
+  title: string;
+  body: string;
+  key?: undefined;
+  imgUrl?: string;
+};

src/api/models/Tutorial.ts

@@ -0,0 +1,19 @@
+/* generated using openapi-typescript-codegen -- do no edit */
+/* istanbul ignore file */
+/* tslint:disable */
+/* eslint-disable */
+
+import { CustomTutorialStep } from './CustomTutorialStep';
+import { GenericTutorialStep } from './GenericTutorialStep';
+
+export type Tutorial = {
+  id: string;
+  name: string;
+  shortName: string;
+  path: string;
+  application: string;
+  steps: Array<CustomTutorialStep | GenericTutorialStep>;
+  showInProd: boolean;
+  willPopUp: boolean;
+  dynamicPositioning?: boolean | null;
+};

src/api/models/TutorialPosition.ts

@@ -0,0 +1,12 @@
+/* generated using openapi-typescript-codegen -- do no edit */
+/* istanbul ignore file */
+/* tslint:disable */
+/* eslint-disable */
+
+export enum TutorialPosition {
+    TOP_LEFT = 'TOP_LEFT',
+    TOP_RIGHT = 'TOP_RIGHT',
+    BOTTOM_LEFT = 'BOTTOM_LEFT',
+    BOTTOM_RIGHT = 'BOTTOM_RIGHT',
+    CENTER = 'CENTER',
+}

src/api/models/TutorialStepBase.ts

@@ -0,0 +1,10 @@
+/* generated using openapi-typescript-codegen -- do no edit */
+/* istanbul ignore file */
+/* tslint:disable */
+/* eslint-disable */
+
+import type { TutorialPosition } from './TutorialPosition';
+
+export type TutorialStepBase = {
+  position?: TutorialPosition;
+};

src/api/services/TutorialService.ts

@@ -0,0 +1,36 @@
+/* generated using openapi-typescript-codegen -- do no edit */
+/* istanbul ignore file */
+/* tslint:disable */
+/* eslint-disable */
+import type { Tutorial } from '../models/Tutorial';
+
+import type { CancelablePromise } from '../core/CancelablePromise';
+import { OpenAPI_Portal_Prod } from '../core/OpenAPI';
+import { request as __request } from '../core/request';
+
+export class TutorialService {
+  /**
+   * Gets all tutorials for Application
+   * @param applicationName
+   * @returns Tutorial Success
+   * @throws ApiError
+   */
+  public static getTutorialsForApplication(
+    applicationName: string
+  ): CancelablePromise<Array<Tutorial>> {
+    return __request(OpenAPI_Portal_Prod, {
+      method: 'GET',
+      url: '/api/v1/Tutorial/{applicationName}',
+      path: {
+        applicationName: applicationName,
+      },
+    });
+  }
+
+  public static getTutorialSasToken(): CancelablePromise<string> {
+    return __request(OpenAPI_Portal_Prod, {
+      method: 'GET',
+      url: '/api/v1/Tutorial/SASToken',
+    });
+  }
+}

src/components/DataDisplay/Tutorial/Tutorial.tsx

@@ -17,7 +17,11 @@ export type TutorialProps = {
   imageSource?: string;
   tutorialIntro: string;
 };
-
+/**
+ * @deprecated since version 6.3.0. We use TutorialProvider instead, and add tutorials to a database on amplify-portal.
+ * You can read a small guide in the front-end docs on the JS devops (JS devops -> Overview -> Wiki -> Documentation ->
+ * Front-end docs -> Guides -> Creating tutorial for TutorialProvider)
+ */
 const Tutorial = forwardRef<HTMLDivElement, TutorialProps>(
   ({ steps, tutorialTitle, tutorialIntro, imageSource }, ref) => {
     const { showTutorialIntro, setTutorialStep, setShowTutorialIntro } =

src/providers/TutorialProvider/TutorialDialog.tsx

@@ -0,0 +1,183 @@
+import { CSSProperties, FC, useMemo } from 'react';
+
+import { Button, Typography } from '@equinor/eds-core-react';
+
+import { useTutorial } from './TutorialProvider';
+import {
+  DIALOG_EDGE_MARGIN,
+  TUTORIAL_LOCALSTORAGE_VALUE_STRING,
+} from './TutorialProvider.const';
+import { useGetTutorialSasToken } from './TutorialProvider.hooks';
+import {
+  DialogActions,
+  DialogContent,
+  DialogImage,
+  DialogWrapper,
+  NavigateSteps,
+  StyledTutorialDialog,
+} from './TutorialProvider.styles';
+import { getBestPositionWithoutOverlap } from './TutorialProvider.utils';
+import TutorialStepIndicator from './TutorialStepIndicator';
+import { TutorialPosition } from 'src/api';
+
+const TutorialDialog: FC = () => {
+  const { data: sasToken } = useGetTutorialSasToken();
+
+  const {
+    activeTutorial,
+    currentStep,
+    setCurrentStep,
+    setActiveTutorial,
+    dialogRef,
+    allElementsToHighlight,
+    customStepComponents,
+    isLastStep,
+    currentStepObject,
+    setAllElementsToHighlight,
+    shortNameFromParams,
+    viewportWidth,
+    clearSearchParam,
+  } = useTutorial();
+
+  const dialogContent = useMemo(() => {
+    if (!currentStepObject) return;
+    if (currentStepObject.key && customStepComponents) {
+      return customStepComponents.find(
+        (step) => step.key === currentStepObject.key
+      )?.element;
+    } else if (
+      currentStepObject.key === undefined ||
+      currentStepObject.key === null
+    ) {
+      return (
+        <>
+          <Typography>{currentStepObject.title}</Typography>
+          <Typography>{currentStepObject.body}</Typography>
+          {currentStepObject.imgUrl && sasToken && (
+            <DialogImage
+              data-testid="tutorial-image"
+              alt="tutorial-image"
+              src={`${currentStepObject.imgUrl}?${sasToken}`}
+            />
+          )}
+        </>
+      );
+    }
+  }, [currentStepObject, customStepComponents, sasToken]);
+
+  const dialogPosition: TutorialPosition | undefined = useMemo(() => {
+    if (
+      !activeTutorial ||
+      !viewportWidth ||
+      !allElementsToHighlight ||
+      !dialogRef.current
+    )
+      return;
+    if (activeTutorial.steps[currentStep].position)
+      return activeTutorial.steps[currentStep].position;
+    if (activeTutorial.dynamicPositioning) {
+      return getBestPositionWithoutOverlap(
+        allElementsToHighlight[currentStep].getBoundingClientRect(),
+        dialogRef.current.getBoundingClientRect()
+      );
+    }
+    return TutorialPosition.BOTTOM_RIGHT;
+  }, [
+    activeTutorial,
+    viewportWidth,
+    allElementsToHighlight,
+    dialogRef,
+    currentStep,
+  ]);
+
+  const dialogPositionStyle: CSSProperties | undefined = useMemo(() => {
+    if (!dialogPosition || dialogPosition === TutorialPosition.CENTER) return;
+    switch (dialogPosition as TutorialPosition) {
+      case TutorialPosition.TOP_LEFT:
+        return {
+          marginTop: `${DIALOG_EDGE_MARGIN}px`,
+          marginLeft: `${DIALOG_EDGE_MARGIN}px`,
+        };
+      case TutorialPosition.TOP_RIGHT:
+        return {
+          marginTop: `${DIALOG_EDGE_MARGIN}px`,
+          marginRight: `${DIALOG_EDGE_MARGIN}px`,
+        };
+      case TutorialPosition.BOTTOM_LEFT:
+        return {
+          marginBottom: `${DIALOG_EDGE_MARGIN}px`,
+          marginLeft: `${DIALOG_EDGE_MARGIN}px`,
+        };
+      case TutorialPosition.BOTTOM_RIGHT:
+      default:
+        return {
+          marginBottom: `${DIALOG_EDGE_MARGIN}px`,
+          marginRight: `${DIALOG_EDGE_MARGIN}px`,
+        };
+    }
+  }, [dialogPosition]);
+
+  const stopTutorial = () => {
+    if (shortNameFromParams) clearSearchParam();
+    if (activeTutorial) {
+      window.localStorage.setItem(
+        activeTutorial?.shortName,
+        TUTORIAL_LOCALSTORAGE_VALUE_STRING
+      );
+      setActiveTutorial(undefined);
+      dialogRef.current?.close();
+      setCurrentStep(0);
+      setAllElementsToHighlight(undefined);
+    }
+  };
+  const handleOnSkip = () => {
+    stopTutorial();
+  };
+
+  const handleOnPrev = () => {
+    setCurrentStep((prev) => prev - 1);
+  };
+
+  const handleOnNext = () => {
+    if (isLastStep) {
+      stopTutorial();
+      return;
+    }
+    setCurrentStep((prev) => prev + 1);
+  };
+
+  return (
+    <DialogWrapper>
+      <StyledTutorialDialog
+        data-testid="tutorial-dialog"
+        ref={dialogRef}
+        style={dialogPositionStyle ?? undefined}
+      >
+        <DialogContent>
+          {dialogContent}
+          <TutorialStepIndicator
+            steps={activeTutorial?.steps ?? []}
+            currentStep={currentStep}
+          />
+          <DialogActions>
+            <Button variant="ghost" onClick={handleOnSkip}>
+              Skip
+            </Button>
+            <NavigateSteps>
+              {currentStep && currentStep !== 0 ? (
+                <Button variant="ghost" onClick={handleOnPrev}>
+                  Previous
+                </Button>
+              ) : null}
+              <Button variant="outlined" onClick={handleOnNext}>
+                {isLastStep ? 'Done' : 'Next'}
+              </Button>
+            </NavigateSteps>
+          </DialogActions>
+        </DialogContent>
+      </StyledTutorialDialog>
+    </DialogWrapper>
+  );
+};
+
+export default TutorialDialog;

src/providers/TutorialProvider/TutorialProvider.const.ts

@@ -0,0 +1,8 @@
+export const HIGHLIGHT_PADDING = 8;
+export const DIALOG_EDGE_MARGIN = 24;
+export const TUTORIAL_SEARCH_PARAM_KEY = 'tutorial';
+export const TUTORIAL_LOCALSTORAGE_VALUE_STRING = 'hasCompletedTutorial';
+export const TUTORIAL_HIGHLIGHTER_DATATEST_ID = 'tutorial-highlighter';
+
+export const GET_TUTORIALS_FOR_APP = 'getTutorialsForApp';
+export const GET_TUTORIALS_SAS_TOKEN = 'getTutorialsSasToken';

src/providers/TutorialProvider/TutorialProvider.hooks.ts

@@ -0,0 +1,24 @@
+import { useQuery } from '@tanstack/react-query';
+
+import {
+  GET_TUTORIALS_FOR_APP,
+  GET_TUTORIALS_SAS_TOKEN,
+} from './TutorialProvider.const';
+import { TutorialService } from 'src/api/services/TutorialService';
+import { environment } from 'src/utils';
+
+const { getAppName } = environment;
+
+export const useGetTutorialsForApp = () => {
+  const appName = getAppName(import.meta.env.VITE_NAME);
+  return useQuery({
+    queryKey: [GET_TUTORIALS_FOR_APP, appName],
+    queryFn: () => TutorialService.getTutorialsForApplication(appName),
+  });
+};
+export const useGetTutorialSasToken = () => {
+  return useQuery({
+    queryKey: [GET_TUTORIALS_SAS_TOKEN],
+    queryFn: () => TutorialService.getTutorialSasToken(),
+  });
+};