@stack-spot/portal-layout 1.1.2 → 2.0.1

package/src/components/tour/StepContainer.tsx

@@ -0,0 +1,83 @@
+import { theme } from '@stack-spot/portal-theme'
+import { ReactNode } from 'react'
+import { styled } from 'styled-components'
+import { NavigationProps, StepNavigation } from './StepNavigation'
+import { StepTitle } from './StepTitle'
+import { useTour } from './hook'
+
+interface StepContainerProps {
+  children: ReactNode,
+  /**
+   * The unique identifier for the step.
+   */
+  stepKey: string,
+  /**
+   * The title for the step.
+   */
+  title: string,
+  /**
+   * The position of the tour overlay related to the content being explained.
+   */
+  position: PointingArrowPosition,
+  /**
+   * A customizable set of buttons for navigating the tour steps.
+   */
+  customNavigation?: Omit<NavigationProps, 'stepKey'>,
+}
+
+/**
+ * Tutorial: the overlay component for showing a step on React Tour.
+ * @param props the react props for the component {@link StepContainerProps}.
+ */
+export const StepContainer = ({ title, stepKey, customNavigation, position, children }: StepContainerProps) => {
+  const { finishStep } = useTour()
+  return <BoxWithPointingArrow $position={position}>
+    <StepTitle title={title} onClose={() => finishStep(stepKey)} />
+    {children}
+    <StepNavigation stepKey={stepKey} {...(customNavigation || {})} />
+  </BoxWithPointingArrow>
+}
+
+export type PointingArrowPosition = 'right' | 'top' | 'left' | 'bottom'
+
+const BoxWithPointingArrow = styled.div < {
+  $position: PointingArrowPosition,
+  $top?: string,
+  $right?: string,
+} > `
+  position: relative;
+  width: 100%;
+  background-color: ${theme.color.inverse[500]};
+  &::after {
+    content: '';
+    position: absolute;
+    border-width: 10px;
+    border-style: solid;
+    border-color: transparent;
+    margin-top: -5px;
+    border-right-color: ${theme.color.inverse[500]};
+    ${({ $position, $top }) => $position === 'right' ?
+    `
+      top: ${$top || '16px'};
+      left: -18px;
+    ` : ''}
+    ${({ $position, $right }) => $position === 'top' ?
+    `
+    bottom: 96%;
+    right: ${$right || '16px'};
+    transform: rotate(90deg);
+    ` : ''}
+    ${({ $position, $top }) => $position === 'left' ?
+    `
+      top: ${$top || '16px'};
+      right: -18px;
+      transform: rotate(180deg);
+    ` : ''}
+    ${({ $position, $right }) => $position === 'bottom' ?
+    `
+    top: -13px;
+    right: ${$right || '16px'};
+    transform: rotate(90deg);
+    ` : ''}
+  }
+`

package/src/components/tour/StepNavigation.tsx

@@ -0,0 +1,70 @@
+import { Button, Flex, Text } from '@citric/core'
+import '@stack-spot/portal-theme/dist/theme.css'
+import { useTranslate } from '@stack-spot/portal-translate'
+import { useTour } from './hook'
+
+interface CustomNavigationButton {
+  /**
+   * The text content to render.
+   */
+  text: string,
+  onClick?: () => void,
+}
+
+export interface NavigationProps {
+  /**
+   * The unique identifier of the step.
+   */
+  stepKey: string,
+  /**
+   * The text and click handler for the button "next".
+   */
+  nextButton?: CustomNavigationButton,
+  /**
+   * The text and click handler for the button "previous".
+   */
+  prevButton?: CustomNavigationButton,
+}
+
+/**
+ * Tutorial: the component in a React Tour overlay that shows the next and previous buttons (for step navigation).
+ * @param props the react props for the component {@link NavigationProps}.
+ */
+export const StepNavigation = ({ stepKey, nextButton, prevButton }: NavigationProps) => {
+  const { currentStep, steps, prevStep, finishStep } = useTour()
+  const t = useTranslate(translations)
+
+  return <Flex w={12} px={5} py={2} mt="-1px" bg="inverse.500" justifyContent="space-between" alignItems="center">
+    <Text appearance="microtext1" colorScheme="inverse.contrastText">{currentStep + 1} {t.of} {steps.length}</Text>
+    <Flex sx={{ gap: '8px' }}>
+      {currentStep >= 1 &&
+        <Button sx={{ paddingInline: '20px' }} onClick={() => {
+          prevStep?.()
+          prevButton?.onClick?.()
+        }} size="sm" appearance="text" colorScheme="light">
+          {prevButton?.text || t.back}
+        </Button>}
+      <Button sx={{ paddingInline: '20px' }} onClick={() => {
+        nextButton?.onClick?.()
+        finishStep(stepKey)
+      }} size="sm" colorScheme="light">
+        {nextButton?.text || (currentStep < steps.length - 1 ? t.next : t.done)}
+      </Button>
+    </Flex>
+  </Flex>
+}
+
+const translations = {
+  en: {
+    of: 'of',
+    back: 'Back',
+    next: 'Next',
+    done: 'Done',
+  },
+  pt: {
+    of: 'de',
+    back: 'Voltar',
+    next: 'Próximo',
+    done: 'Finalizado',
+  },
+}

package/src/components/tour/StepTitle.tsx

@@ -0,0 +1,27 @@
+import { Button, Flex, IconBox, Text } from '@citric/core'
+import { TimesMini } from '@citric/icons'
+
+interface StepTitleProps {
+  /**
+   * The step's title.
+   */
+  title: string,
+  /**
+   * A function to run once the step is closed.
+   */
+  onClose?: () => void,
+}
+
+/**
+ * Tutorial: the component in a React Tour overlay that renders the title.
+ * @param props the react props for the component {@link StepTitleProps}.
+ */
+export const StepTitle = ({ title, onClose }: StepTitleProps) =>
+  <Flex w={12} pl={5} py={3} flexWrap="nowrap" justifyContent="space-between" alignItems="center">
+    <Text appearance="body2" colorScheme="inverse.contrastText" weight="medium"> {title} </Text>
+    <Button appearance="text" size="sm" onClick={() => onClose?.()} sx={{ ':hover': { borderColor: 'transparent !important' } }}>
+      <IconBox size="xs" colorIcon="inverse.contrastText">
+        <TimesMini />
+      </IconBox>
+    </Button>
+  </Flex>

package/src/components/tour/hook.ts

@@ -0,0 +1,12 @@
+import { useEffect, useState } from 'react'
+import { TourConfigExtra, tourManager } from './manager'
+
+export const useTour = () => {
+  const [tourConfig, setTourConfig] = useState<TourConfigExtra>(tourManager.config)
+
+  useEffect(() => tourManager.subscribe((config) => {
+    setTourConfig(config)
+  }), [])
+
+  return tourConfig
+}

package/src/components/tour/index.ts

@@ -0,0 +1,6 @@
+
+export { StepContainer } from './StepContainer'
+export { useTour } from './hook'
+export { TourConfig, TourConfigListener, TourStep, WelcomeTour, tourManager } from './manager'
+export { StackspotTourStep, hasFinishedTourStep, isNewTourStep, tourStepBuilder } from './utils'
+

package/src/components/tour/manager.tsx

@@ -0,0 +1,111 @@
+import WelcomeTour, { ReactourProps, ReactourStep } from 'reactour'
+import { StackspotTourStep, finishTourStep, isNewTourStep, tourStepBuilder } from './utils'
+
+export type TourConfig = Omit<ReactourProps, 'children'>
+export type TourStep = ReactourStep
+
+/**
+ * Tutorial: the default configuration for a React Tour.
+ */
+const defaultTourConfig: TourConfig = Object.freeze({
+  steps: [],
+  isOpen: true,
+  onRequestClose: () => '',
+  showButtons: false,
+  showNavigation: false,
+  showNavigationNumber: false,
+  showNumber: false,
+  showCloseButton: false,
+  disableFocusLock: true,
+})
+
+
+export type TourConfigExtra = TourConfig & {
+  currentStep: number,
+  finishStep: (stepSelector: string) => void,
+  addStep: (step: StackspotTourStep) => void,
+}
+
+type TourConfigListener = (config: TourConfigExtra) => void
+
+
+/**
+ * TourManager: provides state management for React Tour.
+ */
+class TourManager {
+
+  private _steps: TourStep[] = []
+  private _currentStep = 0
+  private observers: TourConfigListener[] = []
+
+  get config(): TourConfigExtra {
+    const config = {
+      ...defaultTourConfig,
+      goToStep: this._currentStep,
+      update: `${this._currentStep}`,
+      steps: this._steps,
+      isOpen: !!this._steps.length && (this._currentStep < this._steps.length),
+      currentStep: this._currentStep,
+      nextStep: () => this.nextStep(),
+      prevStep: () => this.prevStep(),
+      finishStep: (stepSelector: string) => this.finishStep(stepSelector),
+      addStep: (step: StackspotTourStep) => this.addStep(step),
+    }
+    return config
+  }
+
+  get currentStep() {
+    return this._currentStep
+  }
+
+  get steps() {
+    return this._steps
+  }
+
+  addStep(step: StackspotTourStep) {
+    this.addRawStep(tourStepBuilder(step))
+  }
+
+  addRawStep(step: TourStep) {
+    const stepAlreadyAdded = this._steps.some(it => it.selector == step.selector)
+    if (!stepAlreadyAdded && isNewTourStep(step)) {
+      this._steps = [...this._steps, step]
+      this.notify()
+    }
+  }
+
+  nextStep() {
+    this._currentStep = this._currentStep + 1
+    this.notify()
+  }
+
+  prevStep() {
+    this._currentStep = this._currentStep - 1
+    this.notify()
+  }
+
+  finishStep(stepSelector: string) {
+    finishTourStep(stepSelector)
+    this.nextStep()
+  }
+
+  subscribe(updateFn: TourConfigListener) {
+    this.observers.push(updateFn)
+    this.notify()
+    return () => this.pullListener(updateFn)
+  }
+
+  private pullListener(updateFn: TourConfigListener) {
+    this.observers = this.observers.filter((obs) => obs !== updateFn)
+  }
+
+  private notify() {
+    this.observers.forEach((updateFn) => updateFn(this.config))
+  }
+
+}
+
+const tourManager = new TourManager()
+
+export { TourConfigListener, WelcomeTour, tourManager }
+

package/src/components/tour/utils.tsx

@@ -0,0 +1,100 @@
+import { getCookie, setCookie } from '@stack-spot/portal-components'
+import { theme } from '@stack-spot/portal-theme'
+import { ReactNode } from 'react'
+import { ReactourStep } from 'reactour'
+import { PointingArrowPosition, StepContainer } from './StepContainer'
+import { NavigationProps } from './StepNavigation'
+
+const TOUR_COOKIE = 'guided-tour-global'
+
+const defaultExpires = new Date()
+defaultExpires.setFullYear(new Date().getFullYear() + 1)
+
+const getTourCookie = () => {
+  const currentTourObject = getCookie(TOUR_COOKIE)
+  return currentTourObject ? currentTourObject.split(',') : []
+}
+
+/**
+ * Tutorial: marks the tour step as finished. This sets a cookie, preventing the tour from showing again.
+ * @param key the identifier for the step to mark as finished.
+ */
+export const finishTourStep = (key: string) => {
+  const finishedTours: string[] = getTourCookie()
+  if (!finishedTours.includes(key)) finishedTours.push(key)
+  setCookie(TOUR_COOKIE, finishedTours.toString(), { expires: defaultExpires.toUTCString() })
+}
+
+/**
+ * Tutorial: verifies if the React Tour step has not finished yet.
+ * 
+ * A step has not finished if the array stored as a cookie doesn't include the string value of `step.selector`.
+ * @param step the step config.
+ * @returns true if the step has not yet been marked as finished. False otherwise.
+ */
+export const isNewTourStep = (step: ReactourStep) => !hasFinishedTourStep(`${step.selector}`)
+
+/**
+ * Tutorial: verifies if the key passed as parameter refers to a React Tour step that has already finished.
+ * 
+ * The key refers to a finished step if the array stored as a cookie includes it.
+ * If the cookie is set to 'disabled', then the step will be considered finished.Particularly useful in scenarios like e2e tests.
+ * @param key the step's identifier to check.
+ * @returns true if the key refers to a finished step. False otherwise.
+ */
+export const hasFinishedTourStep = (key: string) => {
+  const tourCookie = getTourCookie()
+  return tourCookie.includes(key) || tourCookie[0] === 'disabled'
+}
+
+export interface StackspotTourStep extends ReactourStep {
+  /**
+   * The step's title.
+   */
+  title: string,
+  /**
+   * The unique identifier for the step (key).
+   */
+  selector: string,
+  /**
+   * The step's content.
+   */
+  content: ReactNode,
+  /**
+   * A set of properties for customizing the next and previous buttons.
+   */
+  customNavigation?: NavigationProps,
+}
+
+/**
+ * Tutorial: utility for building a React Tour step. This already includes some default configuration for tours in Stackspot.
+ * @param options the options for building the step: {@link StackspotTourStep}. 
+ * @returns the React Tour step.
+ */
+export const tourStepBuilder = ({
+  selector,
+  position,
+  title,
+  content,
+  style,
+  customNavigation,
+  ...rest
+}: StackspotTourStep): ReactourStep => ({
+  selector,
+  content: (<StepContainer
+    stepKey={selector}
+    position={position as PointingArrowPosition}
+    title={title}
+    customNavigation={customNavigation}>
+    {content}
+  </StepContainer>),
+  position,
+  style: {
+    backgroundColor: theme.color.inverse[500],
+    width: '256px',
+    padding: 0,
+    top: ['right', 'left'].includes(position as PointingArrowPosition) ? '-3px' : '0',
+    ...(style || {}),
+  },
+  ...(rest || {}),
+})

package/src/index.ts

@@ -7,6 +7,7 @@ export { PortalSwitcher } from './components/PortalSwitcher'
 export { ActionItem, MenuContent, MenuGroup, Title } from './components/menu/MenuContent'
 export { MenuSections } from './components/menu/MenuSections'
 export * from './components/menu/types'
+export * from './components/tour'
 export * from './components/types'
 export * from './elements'
 export * from './errors'

package/src/layout.css

@@ -27,7 +27,7 @@ body {
   display: flex;
   flex-direction: column;
   flex: 1;
-  background: var(--light-400);
+  background: var(--light-300);
   font: var(--font);
   color: var(--light-contrastText);
 }

package/dist/components/tour/PortalSwitcherStep.d.ts

@@ -1,8 +0,0 @@
-import { TourStep } from '@stack-spot/portal-components/Tour';
-/**
- * Tutorial: a React hook for retrieving the React Tour step that explains how the portal switcher works. The portal switcher is a component
- * at the top left corner of the layout (header) that allows the user to switch between the different Stackspot portals.
- * @returns the React Tour step for the PortalSwitcher.
- */
-export declare const usePortalSwitcherStep: () => TourStep;
-//# sourceMappingURL=PortalSwitcherStep.d.ts.map

package/dist/components/tour/PortalSwitcherStep.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"PortalSwitcherStep.d.ts","sourceRoot":"","sources":["../../../src/components/tour/PortalSwitcherStep.tsx"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAmB,MAAM,oCAAoC,CAAA;AAG9E;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,QAAO,QAgBxC,CAAA"}

package/dist/components/tour/PortalSwitcherStep.js

@@ -1,34 +0,0 @@
-import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
-import { Box, Image, Text } from '@citric/core';
-import { tourStepBuilder } from '@stack-spot/portal-components/Tour';
-import { useTranslate } from '@stack-spot/portal-translate';
-/**
- * Tutorial: a React hook for retrieving the React Tour step that explains how the portal switcher works. The portal switcher is a component
- * at the top left corner of the layout (header) that allows the user to switch between the different Stackspot portals.
- * @returns the React Tour step for the PortalSwitcher.
- */
-export const usePortalSwitcherStep = () => {
-    const t = useTranslate(translations);
-    return tourStepBuilder({
-        selector: '.portal-switcher',
-        title: t.title,
-        content: _jsxs(_Fragment, { children: [_jsx(Image, { src: "https://marketing.stackspot.com/switch-v2.gif", alt: t.imageAlt }), _jsx(Box, { px: 5, py: 3, children: _jsx(Text, { appearance: "microtext1", colorScheme: "inverse.contrastText", children: t.description }) })] }),
-        position: 'right',
-        style: {
-            width: '300px',
-        },
-    });
-};
-const translations = {
-    en: {
-        title: 'Expand Your Horizons with Stackspot',
-        description: 'Easily switch between EDP and AI to enhance your projects. Access a wide range of resources with just one click and take your projects to a new level of efficiency. Start your journey now!',
-        imageAlt: 'GIF describing how to use product switcher and navigate between AI and EDP portals',
-    },
-    pt: {
-        title: 'Expanda Seus Horizontes com Stackspot',
-        description: 'Troque facilmente entre EDP e AI para aprimorar seus projetos. Acesse uma ampla gama de recursos com apenas um clique e leve seus projetos para um novo nível de eficiência. Comece sua jornada agora!',
-        imageAlt: 'GIF mostrando como usar o alternador de produtos e navegar entre os portais AI e EDP',
-    },
-};
-//# sourceMappingURL=PortalSwitcherStep.js.map

package/dist/components/tour/PortalSwitcherStep.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"PortalSwitcherStep.js","sourceRoot":"","sources":["../../../src/components/tour/PortalSwitcherStep.tsx"],"names":[],"mappings":";AAAA,OAAO,EAAE,GAAG,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,cAAc,CAAA;AAC/C,OAAO,EAAY,eAAe,EAAE,MAAM,oCAAoC,CAAA;AAC9E,OAAO,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAA;AAE3D;;;;GAIG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,GAAa,EAAE;IAClD,MAAM,CAAC,GAAG,YAAY,CAAC,YAAY,CAAC,CAAA;IACpC,OAAO,eAAe,CAAC;QACrB,QAAQ,EAAE,kBAAkB;QAC5B,KAAK,EAAE,CAAC,CAAC,KAAK;QACd,OAAO,EAAE,8BACP,KAAC,KAAK,IAAC,GAAG,EAAC,+CAA+C,EAAC,GAAG,EAAE,CAAC,CAAC,QAAQ,GAAI,EAC9E,KAAC,GAAG,IAAC,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,YACf,KAAC,IAAI,IAAC,UAAU,EAAC,YAAY,EAAC,WAAW,EAAC,sBAAsB,YAAE,CAAC,CAAC,WAAW,GAAQ,GACnF,IACL;QACH,QAAQ,EAAE,OAAO;QACjB,KAAK,EAAE;YACL,KAAK,EAAE,OAAO;SACf;KACF,CAAC,CAAA;AACJ,CAAC,CAAA;AAED,MAAM,YAAY,GAAG;IACnB,EAAE,EAAE;QACF,KAAK,EAAE,qCAAqC;QAC5C,WAAW,EAAE,8LAA8L;QAC3M,QAAQ,EAAE,oFAAoF;KAC/F;IACD,EAAE,EAAE;QACF,KAAK,EAAE,uCAAuC;QAC9C,WAAW,EAAE,wMAAwM;QACrN,QAAQ,EAAE,sFAAsF;KACjG;CACF,CAAA"}

package/src/components/tour/PortalSwitcherStep.tsx

@@ -1,39 +0,0 @@
-import { Box, Image, Text } from '@citric/core'
-import { TourStep, tourStepBuilder } from '@stack-spot/portal-components/Tour'
-import { useTranslate } from '@stack-spot/portal-translate'
-
-/**
- * Tutorial: a React hook for retrieving the React Tour step that explains how the portal switcher works. The portal switcher is a component
- * at the top left corner of the layout (header) that allows the user to switch between the different Stackspot portals.
- * @returns the React Tour step for the PortalSwitcher.
- */
-export const usePortalSwitcherStep = (): TourStep => {
-  const t = useTranslate(translations)
-  return tourStepBuilder({
-    selector: '.portal-switcher',
-    title: t.title,
-    content: <>
-      <Image src="https://marketing.stackspot.com/switch-v2.gif" alt={t.imageAlt} />
-      <Box px={5} py={3}>
-        <Text appearance="microtext1" colorScheme="inverse.contrastText">{t.description}</Text>
-      </Box>
-    </>,
-    position: 'right',
-    style: {
-      width: '300px',
-    },
-  })
-}
-
-const translations = {
-  en: {
-    title: 'Expand Your Horizons with Stackspot',
-    description: 'Easily switch between EDP and AI to enhance your projects. Access a wide range of resources with just one click and take your projects to a new level of efficiency. Start your journey now!',
-    imageAlt: 'GIF describing how to use product switcher and navigate between AI and EDP portals',
-  },
-  pt: {
-    title: 'Expanda Seus Horizontes com Stackspot',
-    description: 'Troque facilmente entre EDP e AI para aprimorar seus projetos. Acesse uma ampla gama de recursos com apenas um clique e leve seus projetos para um novo nível de eficiência. Comece sua jornada agora!',
-    imageAlt: 'GIF mostrando como usar o alternador de produtos e navegar entre os portais AI e EDP',
-  },
-}