@strapi/admin 4.15.0-alpha.0 → 4.15.0

package/admin/src/components/GuidedTour/Modal.tsx

@@ -0,0 +1,303 @@
+import * as React from 'react';
+
+import {
+  Box,
+  Button,
+  Flex,
+  FocusTrap,
+  IconButton,
+  Portal,
+  Typography,
+} from '@strapi/design-system';
+import { LinkButton } from '@strapi/design-system/v2';
+import { GuidedTourContextValue, pxToRem, useGuidedTour, useTracking } from '@strapi/helper-plugin';
+import { ArrowRight, Cross } from '@strapi/icons';
+import get from 'lodash/get';
+import { MessageDescriptor, useIntl } from 'react-intl';
+import { NavLink } from 'react-router-dom';
+import styled from 'styled-components';
+
+import { LAYOUT_DATA, STATES } from './constants';
+import { Number, VerticalDivider } from './Ornaments';
+
+/* -------------------------------------------------------------------------------------------------
+ * GuidedTourModal
+ * -----------------------------------------------------------------------------------------------*/
+
+const GuidedTourModal = () => {
+  const {
+    currentStep,
+    guidedTourState,
+    setCurrentStep,
+    setStepState,
+    isGuidedTourVisible,
+    setSkipped,
+  } = useGuidedTour();
+  const { formatMessage } = useIntl();
+  const { trackUsage } = useTracking();
+
+  if (!currentStep || !isGuidedTourVisible) {
+    return null;
+  }
+
+  const stepData = get(LAYOUT_DATA, currentStep);
+  const sectionKeys = Object.keys(guidedTourState);
+  const [sectionName, stepName] = currentStep.split('.') as [
+    keyof GuidedTourContextValue['guidedTourState'],
+    string
+  ];
+  const sectionIndex = sectionKeys.indexOf(sectionName);
+  const stepIndex = Object.keys(guidedTourState[sectionName]).indexOf(stepName);
+  const hasSectionAfter = sectionIndex < sectionKeys.length - 1;
+  const hasStepAfter = stepIndex < Object.keys(guidedTourState[sectionName]).length - 1;
+
+  const handleCtaClick = () => {
+    setStepState(currentStep, true);
+    trackUsage(stepData.trackingEvent);
+
+    setCurrentStep(null);
+  };
+
+  const handleSkip = () => {
+    setSkipped(true);
+    setCurrentStep(null);
+    trackUsage('didSkipGuidedtour');
+  };
+
+  return (
+    <Portal>
+      <ModalWrapper onClick={handleCtaClick} padding={8} justifyContent="center">
+        <FocusTrap onEscape={handleCtaClick}>
+          <Flex
+            direction="column"
+            alignItems="stretch"
+            background="neutral0"
+            width={pxToRem(660)}
+            shadow="popupShadow"
+            hasRadius
+            padding={4}
+            gap={8}
+            role="dialog"
+            aria-modal
+            onClick={(e) => e.stopPropagation()}
+          >
+            <Flex justifyContent="flex-end">
+              <IconButton
+                onClick={handleCtaClick}
+                aria-label={formatMessage({
+                  id: 'app.utils.close-label',
+                  defaultMessage: 'Close',
+                })}
+              >
+                <Cross />
+              </IconButton>
+            </Flex>
+            <Box
+              paddingLeft={7}
+              paddingRight={7}
+              paddingBottom={!hasStepAfter && !hasSectionAfter ? 8 : 0}
+            >
+              <GuidedTourStepper
+                title={stepData.title}
+                cta={'cta' in stepData ? stepData.cta : undefined}
+                onCtaClick={handleCtaClick}
+                sectionIndex={sectionIndex}
+                stepIndex={stepIndex}
+                hasSectionAfter={hasSectionAfter}
+              >
+                <GuidedTourContent {...stepData.content} />
+              </GuidedTourStepper>
+            </Box>
+            {!(!hasStepAfter && !hasSectionAfter) && (
+              <Flex justifyContent="flex-end">
+                <Button variant="tertiary" onClick={handleSkip}>
+                  {formatMessage({
+                    id: 'app.components.GuidedTour.skip',
+                    defaultMessage: 'Skip the tour',
+                  })}
+                </Button>
+              </Flex>
+            )}
+          </Flex>
+        </FocusTrap>
+      </ModalWrapper>
+    </Portal>
+  );
+};
+
+const ModalWrapper = styled(Flex)`
+  position: fixed;
+  z-index: 4;
+  inset: 0;
+  /* this is theme.colors.neutral800 with opacity */
+  background: ${({ theme }) => `${theme.colors.neutral800}1F`};
+`;
+
+/* -------------------------------------------------------------------------------------------------
+ * GuidedTourStepper
+ * -----------------------------------------------------------------------------------------------*/
+
+interface GuidedTourStepperProps {
+  title: MessageDescriptor;
+  children: React.ReactNode;
+  cta?: {
+    title: MessageDescriptor;
+    target?: string;
+  };
+  onCtaClick: () => void;
+  sectionIndex: number;
+  stepIndex: number;
+  hasSectionAfter: boolean;
+}
+
+const GuidedTourStepper = ({
+  title,
+  children,
+  cta,
+  onCtaClick,
+  sectionIndex,
+  stepIndex,
+  hasSectionAfter,
+}: GuidedTourStepperProps) => {
+  const { formatMessage } = useIntl();
+
+  const hasSectionBefore = sectionIndex > 0;
+  const hasStepsBefore = stepIndex > 0;
+  const nextSectionIndex = sectionIndex + 1;
+
+  return (
+    <>
+      <Flex alignItems="stretch">
+        <Flex marginRight={8} justifyContent="center" minWidth={pxToRem(30)}>
+          {hasSectionBefore && <VerticalDivider state={STATES.IS_DONE} minHeight={pxToRem(24)} />}
+        </Flex>
+        <Typography variant="sigma" textColor="primary600">
+          {formatMessage({
+            id: 'app.components.GuidedTour.title',
+            defaultMessage: '3 steps to get started',
+          })}
+        </Typography>
+      </Flex>
+      <Flex>
+        <Flex marginRight={8} minWidth={pxToRem(30)}>
+          <Number
+            state={hasStepsBefore ? STATES.IS_DONE : STATES.IS_ACTIVE}
+            paddingTop={3}
+            paddingBottom={3}
+          >
+            {sectionIndex + 1}
+          </Number>
+        </Flex>
+        <Typography variant="alpha" fontWeight="bold" textColor="neutral800" as="h3" id="title">
+          {formatMessage(title)}
+        </Typography>
+      </Flex>
+      <Flex alignItems="stretch">
+        <Flex marginRight={8} direction="column" justifyContent="center" minWidth={pxToRem(30)}>
+          {hasSectionAfter && (
+            <>
+              <VerticalDivider state={STATES.IS_DONE} />
+              {hasStepsBefore && (
+                <Number state={STATES.IS_ACTIVE} paddingTop={3}>
+                  {nextSectionIndex + 1}
+                </Number>
+              )}
+            </>
+          )}
+        </Flex>
+        <Box>
+          {children}
+          {cta &&
+            (cta.target ? (
+              <LinkButton
+                as={NavLink}
+                endIcon={<ArrowRight />}
+                onClick={onCtaClick}
+                // @ts-expect-error - types are not inferred correctly through the as prop.
+                to={cta.target}
+              >
+                {formatMessage(cta.title)}
+              </LinkButton>
+            ) : (
+              <Button endIcon={<ArrowRight />} onClick={onCtaClick}>
+                {formatMessage(cta.title)}
+              </Button>
+            ))}
+        </Box>
+      </Flex>
+      {hasStepsBefore && hasSectionAfter && (
+        <Box paddingTop={3}>
+          <Flex marginRight={8} justifyContent="center" width={pxToRem(30)}>
+            <VerticalDivider state={STATES.IS_DONE} minHeight={pxToRem(24)} />
+          </Flex>
+        </Box>
+      )}
+    </>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * GuidedTourContent
+ * -----------------------------------------------------------------------------------------------*/
+
+interface GuidedTourContentProps
+  extends Required<Pick<MessageDescriptor, 'defaultMessage' | 'id'>> {}
+
+const GuidedTourContent = ({ id, defaultMessage }: GuidedTourContentProps) => {
+  const { formatMessage } = useIntl();
+
+  return (
+    <Flex direction="column" alignItems="stretch" gap={4} paddingBottom={6}>
+      {formatMessage(
+        { id, defaultMessage },
+        {
+          documentationLink: DocumentationLink,
+          b: Bold,
+          p: Paragraph,
+          light: Light,
+          ul: List,
+          li: ListItem,
+        }
+      )}
+    </Flex>
+  );
+};
+
+const DocumentationLink = (children: React.ReactNode) => (
+  <Typography
+    as="a"
+    textColor="primary600"
+    target="_blank"
+    rel="noopener noreferrer"
+    href="https://docs.strapi.io/developer-docs/latest/developer-resources/database-apis-reference/rest-api.html#api-parameters"
+  >
+    {children}
+  </Typography>
+);
+
+const Bold = (children: React.ReactNode) => (
+  <Typography fontWeight="semiBold">{children}</Typography>
+);
+
+const Paragraph = (children: React.ReactNode) => <Typography>{children}</Typography>;
+
+const Light = (children: React.ReactNode) => (
+  <Typography textColor="neutral600">{children}</Typography>
+);
+
+const List = (children: React.ReactNode) => (
+  <Box paddingLeft={6}>
+    <ul>{children}</ul>
+  </Box>
+);
+
+const LiStyled = styled.li`
+  list-style: disc;
+  &::marker {
+    color: ${({ theme }) => theme.colors.neutral800};
+  }
+`;
+
+const ListItem = (children: React.ReactNode) => <LiStyled>{children}</LiStyled>;
+
+export { GuidedTourModal };

package/admin/src/components/GuidedTour/Ornaments.tsx

@@ -0,0 +1,74 @@
+import { Box, BoxProps, Flex, FlexProps, Typography } from '@strapi/design-system';
+import { pxToRem } from '@strapi/helper-plugin';
+import { Check } from '@strapi/icons';
+
+import { STATES, States } from './constants';
+
+/* -------------------------------------------------------------------------------------------------
+ * Number
+ * -----------------------------------------------------------------------------------------------*/
+
+interface NumberProps extends FlexProps {
+  children: number;
+  state: States;
+}
+
+const Number = ({ children, state, ...props }: NumberProps) => {
+  return state === STATES.IS_DONE || state === STATES.IS_ACTIVE ? (
+    <Flex
+      background="primary600"
+      padding={2}
+      borderRadius="50%"
+      width={pxToRem(30)}
+      height={pxToRem(30)}
+      justifyContent="center"
+      {...props}
+    >
+      {state === STATES.IS_DONE ? (
+        <Check aria-hidden width={pxToRem(16)} color="neutral0" />
+      ) : (
+        <Typography fontWeight="semiBold" textColor="neutral0">
+          {children}
+        </Typography>
+      )}
+    </Flex>
+  ) : (
+    <Flex
+      borderColor="neutral500"
+      borderWidth="1px"
+      borderStyle="solid"
+      padding={2}
+      borderRadius="50%"
+      width={pxToRem(30)}
+      height={pxToRem(30)}
+      justifyContent="center"
+      {...props}
+    >
+      <Typography fontWeight="semiBold" textColor="neutral600">
+        {children}
+      </Typography>
+    </Flex>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * VerticalDivider
+ * -----------------------------------------------------------------------------------------------*/
+
+interface VerticalDividerProps extends BoxProps {
+  state: States;
+}
+
+const VerticalDivider = ({ state, ...props }: VerticalDividerProps) => (
+  <Box
+    width={pxToRem(2)}
+    height="100%"
+    background={state === STATES.IS_NOT_DONE ? 'neutral300' : 'primary500'}
+    hasRadius
+    minHeight={state === STATES.IS_ACTIVE ? pxToRem(85) : pxToRem(65)}
+    {...props}
+  />
+);
+
+export { Number, VerticalDivider };
+export type { NumberProps, VerticalDividerProps };

package/admin/src/components/GuidedTour/Provider.tsx

@@ -0,0 +1,253 @@
+import * as React from 'react';
+
+import {
+  GuidedTourContextValue,
+  GuidedTourProvider as GuidedTourProviderComponent,
+  GuidedTourSectionKey,
+  GuidedTourStep,
+  GuidedTourStepKey,
+  auth,
+} from '@strapi/helper-plugin';
+import produce from 'immer';
+import get from 'lodash/get';
+import set from 'lodash/set';
+
+/* -------------------------------------------------------------------------------------------------
+ * GuidedTourProvider
+ * -----------------------------------------------------------------------------------------------*/
+
+interface GuidedTourProviderProps {
+  children: React.ReactNode;
+}
+
+const GuidedTourProvider = ({ children }: GuidedTourProviderProps) => {
+  const [{ currentStep, guidedTourState, isGuidedTourVisible, isSkipped }, dispatch] =
+    React.useReducer(reducer, initialState, initialiseState);
+
+  const setCurrentStep = (step: SetCurrentStepAction['step']) => {
+    // if step is null it is intentional, we need to dispatch it
+    if (step !== null) {
+      const isStepAlreadyDone = get(guidedTourState, step);
+      const [sectionName, stepName] = step.split('.') as [GuidedTourSectionKey, GuidedTourStepKey];
+      const sectionArray = Object.entries(guidedTourState[sectionName]);
+
+      const currentStepIndex = sectionArray.findIndex(([key]) => key === stepName);
+      const previousSteps = sectionArray.slice(0, currentStepIndex);
+
+      const isStepToShow = previousSteps.every(([, sectionValue]) => sectionValue);
+
+      if (isStepAlreadyDone || isSkipped || !isStepToShow) {
+        return null;
+      }
+    }
+
+    auth.set(null, 'GUIDED_TOUR_CURRENT_STEP', true);
+
+    return dispatch({
+      type: 'SET_CURRENT_STEP',
+      step,
+    });
+  };
+
+  const setGuidedTourVisibility = (value: SetGuidedTourVisibilityAction['value']) => {
+    dispatch({
+      type: 'SET_GUIDED_TOUR_VISIBILITY',
+      value,
+    });
+  };
+
+  const setStepState = (currentStep: GuidedTourStep, value: SetStepStateAction['value']) => {
+    addCompletedStep(currentStep);
+
+    dispatch({
+      type: 'SET_STEP_STATE',
+      currentStep,
+      value,
+    });
+  };
+
+  const startSection = (sectionName: GuidedTourSectionKey) => {
+    const sectionSteps = guidedTourState[sectionName];
+
+    if (sectionSteps) {
+      const guidedTourArray = Object.entries(guidedTourState);
+
+      // Find current section position in the guidedTourArray
+      // Get only previous sections based on current section position
+      const currentSectionIndex = guidedTourArray.findIndex(([key]) => key === sectionName);
+      const previousSections = guidedTourArray.slice(0, currentSectionIndex);
+
+      // Check if every steps from previous section are done
+      const isSectionToShow = previousSections.every(([, sectionValue]) =>
+        Object.values(sectionValue).every(Boolean)
+      );
+
+      const [firstStep] = Object.keys(sectionSteps) as [GuidedTourStepKey];
+      const isFirstStepDone = sectionSteps[firstStep];
+
+      if (isSectionToShow && !currentStep && !isFirstStepDone) {
+        setCurrentStep(`${sectionName}.${firstStep}`);
+      }
+    }
+  };
+
+  const setSkipped = (value: SetSkippedAction['value']) => {
+    auth.set(value, 'GUIDED_TOUR_SKIPPED', true);
+
+    dispatch({
+      type: 'SET_SKIPPED',
+      value,
+    });
+  };
+
+  return (
+    <GuidedTourProviderComponent
+      guidedTourState={guidedTourState}
+      currentStep={currentStep}
+      setCurrentStep={setCurrentStep}
+      setGuidedTourVisibility={setGuidedTourVisibility}
+      setSkipped={setSkipped}
+      setStepState={setStepState}
+      startSection={startSection}
+      isGuidedTourVisible={isGuidedTourVisible}
+      isSkipped={isSkipped}
+    >
+      {children}
+    </GuidedTourProviderComponent>
+  );
+};
+
+type State = Pick<
+  GuidedTourContextValue,
+  'guidedTourState' | 'currentStep' | 'isGuidedTourVisible' | 'isSkipped'
+>;
+
+const initialState = {
+  currentStep: null,
+  guidedTourState: {
+    contentTypeBuilder: {
+      create: false,
+      success: false,
+    },
+    contentManager: {
+      create: false,
+      success: false,
+    },
+    apiTokens: {
+      create: false,
+      success: false,
+    },
+  },
+  isGuidedTourVisible: false,
+  isSkipped: false,
+} satisfies State;
+
+interface SetCurrentStepAction {
+  type: 'SET_CURRENT_STEP';
+  step: GuidedTourStep | null;
+}
+
+interface SetStepStateAction {
+  type: 'SET_STEP_STATE';
+  currentStep: GuidedTourStep;
+  value: boolean;
+}
+
+interface SetSkippedAction {
+  type: 'SET_SKIPPED';
+  value: boolean;
+}
+
+interface SetGuidedTourVisibilityAction {
+  type: 'SET_GUIDED_TOUR_VISIBILITY';
+  value: boolean;
+}
+
+type Action =
+  | SetCurrentStepAction
+  | SetStepStateAction
+  | SetSkippedAction
+  | SetGuidedTourVisibilityAction;
+
+const reducer: React.Reducer<State, Action> = (state: State = initialState, action: Action) =>
+  produce(state, (draftState) => {
+    switch (action.type) {
+      case 'SET_CURRENT_STEP': {
+        draftState.currentStep = action.step;
+        break;
+      }
+      case 'SET_STEP_STATE': {
+        const [section, step] = action.currentStep.split('.') as [
+          GuidedTourSectionKey,
+          GuidedTourStepKey
+        ];
+        draftState.guidedTourState[section][step] = action.value;
+        break;
+      }
+      case 'SET_SKIPPED': {
+        draftState.isSkipped = action.value;
+        break;
+      }
+      case 'SET_GUIDED_TOUR_VISIBILITY': {
+        draftState.isGuidedTourVisible = action.value;
+        break;
+      }
+      default: {
+        return draftState;
+      }
+    }
+  });
+
+const initialiseState = (initialState: State) => {
+  const copyInitialState = { ...initialState };
+  const guidedTourLocaleStorage = auth.get('GUIDED_TOUR_COMPLETED_STEPS');
+  const currentStepLocaleStorage = auth.get('GUIDED_TOUR_CURRENT_STEP');
+  const skippedLocaleStorage = auth.get('GUIDED_TOUR_SKIPPED');
+
+  if (Array.isArray(guidedTourLocaleStorage)) {
+    guidedTourLocaleStorage.forEach((step) => {
+      const [sectionName, stepName] = step.split('.');
+      set(copyInitialState, ['guidedTourState', sectionName, stepName], true);
+    });
+  }
+
+  // if current step when initializing mark it as done
+  if (currentStepLocaleStorage) {
+    const [sectionName, stepName] = currentStepLocaleStorage.split('.') as [
+      GuidedTourSectionKey,
+      GuidedTourStepKey
+    ];
+    set(copyInitialState, ['guidedTourState', sectionName, stepName], true);
+
+    addCompletedStep(currentStepLocaleStorage as GuidedTourStep);
+
+    auth.set(null, 'GUIDED_TOUR_CURRENT_STEP', true);
+  }
+
+  if (skippedLocaleStorage !== null) {
+    set(copyInitialState, 'isSkipped', skippedLocaleStorage);
+  }
+
+  return copyInitialState;
+};
+
+/**
+ * @description Add a completed step to the local storage if it does not already exist.
+ */
+const addCompletedStep = (completedStep: GuidedTourStep) => {
+  const currentSteps = auth.get('GUIDED_TOUR_COMPLETED_STEPS') ?? [];
+
+  if (!Array.isArray(currentSteps)) {
+    return;
+  }
+
+  const isAlreadyStored = currentSteps.includes(completedStep);
+
+  if (isAlreadyStored) {
+    return;
+  }
+
+  auth.set([...currentSteps, completedStep], 'GUIDED_TOUR_COMPLETED_STEPS', true);
+};
+
+export { GuidedTourProvider };

package/admin/src/components/GuidedTour/{layout.js → constants.ts}

@@ -1,4 +1,4 @@
-const layout = {
+const LAYOUT_DATA = {
   contentTypeBuilder: {
     home: {
       title: {
@@ -157,6 +157,16 @@ const layout = {
       trackingEvent: 'didGenerateGuidedTourApiTokens',
     },
   },
-};
+} as const;
 
-export default layout;
+const STATES = {
+  IS_DONE: 'IS_DONE',
+  IS_ACTIVE: 'IS_ACTIVE',
+  IS_NOT_DONE: 'IS_NOT_DONE',
+} as const;
+
+type LayoutData = typeof LAYOUT_DATA;
+type States = keyof typeof STATES;
+
+export { LAYOUT_DATA, STATES };
+export type { LayoutData, States };