@veracity/vui 1.5.0 → 1.6.0

package/src/tutorial/tutorial.types.ts

@@ -0,0 +1,69 @@
+import React from 'react'
+import { Placement } from 'tippy.js'
+
+export type TutorialDataStep = {
+  /** title of step */
+  title: string
+  /** description of step */
+  description: string
+  /** Read more link */
+  readMoreLink?: string
+}
+
+export type TutorialProps = {
+  /** Target element for the tutorial */
+  children: React.ReactNode
+  /** Custom class name */
+  className?: string
+  /** An id for further handling with localStorage */
+  id: string
+  /** A general tutorial description */
+  description?: string
+  /** Invoked once the dismiss button clicked. */
+  onDismiss?: () => void
+  /** Invoked once the finish button clicked. */
+  onFinish?: () => void
+  /** Popover placement */
+  placement?: Placement
+  /** Link to page where user can read more */
+  readMoreLink?: string
+  /** An array of steps */
+  steps: TutorialDataStep[]
+  /** A general tutorial title */
+  title: string
+}
+
+export type TutorialCardProps = {
+  /** Custom class name */
+  className?: string
+  /** The card title */
+  title: string
+  /** Steps of the card */
+  steps: TutorialDataStep[]
+  /** Callback for the dismiss button click. */
+  onDismiss?: () => void
+  /** Callback for the finish button click. */
+  onFinish?: () => void
+  /** Description of feature */
+  description?: string
+  /** Link to page where they can read more */
+  readMoreLink?: string
+}
+
+export type TutorialStepProps = {
+  /** If the step is active or not */
+  active: boolean
+  /** Title of step */
+  title: string
+  /** Description of step */
+  description: string
+  /** Link to page where user can read more */
+  readMoreLink?: string
+}
+
+export type TutorialStepWrapper = {
+  key: number
+  step: TutorialDataStep
+}
+
+export type CloseEvent = 'dismissed' | 'finished'

package/src/tutorial/tutorialCard.tsx

@@ -0,0 +1,137 @@
+import React, { useEffect, useState } from 'react'
+
+import { Box, Button, Card, H3, Icon, T } from '../index'
+import { TutorialCardProps, TutorialDataStep, TutorialStepWrapper } from './tutorial.types'
+import { TutorialStep } from './tutorialStep'
+
+export function TutorialCard({
+  className,
+  description,
+  title,
+  readMoreLink,
+  steps: propsSteps = [],
+  onDismiss,
+  onFinish
+}: TutorialCardProps) {
+  const [started, setStarted] = useState<boolean>(false)
+  const [steps, setSteps] = useState<TutorialStepWrapper[]>([])
+  const [activeStep, setActiveStep] = useState<number>(0)
+
+  useEffect(() => {
+    if (title && propsSteps.length) {
+      const s = propsSteps.map((step, key) => ({ active: false, step, key }))
+
+      const finalStep: TutorialDataStep = {
+        title: `Completed!`,
+        description: `${readMoreLink ? 'To learn more, please visit:' : 'Thank you!'}`
+      }
+
+      if (readMoreLink) finalStep.readMoreLink = readMoreLink
+
+      setSteps([...s, { step: finalStep, key: propsSteps.length }])
+    }
+  }, [title, propsSteps])
+
+  const isStartStep = activeStep === 0
+  const isFinalStep = activeStep === propsSteps.length
+  const decrementStep = () => setActiveStep(activeStep - 1)
+  const incrementStep = () => setActiveStep(activeStep + 1)
+
+  return (
+    <Card bg="blue.100" className={className} color="white" column justifyContent="space-between" minH={200} w={450}>
+      <Box
+        alignContent="center"
+        alignItems="center"
+        display="flex"
+        flex={0}
+        flexDirection="row"
+        flexGrow={0}
+        justifyContent="space-between"
+        m={2}
+        mb={1}
+        minH="48px"
+        row
+        style={{ WebkitFlexGrow: '0' }}
+      >
+        <H3>{title}</H3>
+        {!isFinalStep && (
+          <Button color="white" hoverColor="prussian.80" icon="falTimes" onClick={onDismiss} scale={2} variant="text" />
+        )}
+      </Box>
+      <Box column flex={5} hidden={started} mx={2}>
+        <T flexGrow={1}>{description}</T>
+        <Box alignItems="center" flexDirection="row-reverse" row>
+          <Button bg="white" color="prussian.80" float="right" mb={0} onClick={() => setStarted(true)} pb={0}>
+            Let&apos;s get started!
+          </Button>
+        </Box>
+      </Box>
+      <Box flex={5} hidden={!started} mx={2} row>
+        {steps?.map?.(s => (
+          <TutorialStep
+            active={s.key === activeStep}
+            description={s.step.description}
+            key={s.step.title}
+            readMoreLink={s.step.readMoreLink}
+            title={s.step.title}
+          />
+        ))}
+      </Box>
+      <Box
+        alignItems="center"
+        flex={0}
+        flexGrow={0}
+        hidden={!started}
+        justifyContent="space-between"
+        m={2}
+        mt={0}
+        row
+        style={{ WebkitFlexGrow: '0' }}
+      >
+        <Button
+          color="white"
+          disabled={isStartStep}
+          disabledBg="blue.100"
+          disabledBorderColor="blue.100"
+          disabledColor="prussian.80"
+          focusBorderColor="none"
+          hoverBg="none"
+          hoverBorder="none"
+          hoverBorderColor="blue.100"
+          icon="falArrowLeft"
+          onClick={decrementStep}
+          scale={2}
+          transition="none"
+          variant="text"
+          w="80"
+        />
+
+        <Box className="vuiTutorialStepDots">
+          {steps?.map?.(s => (
+            <Icon color={s.key === activeStep ? 'white' : 'grey.70'} key={s.key} name="cusDotFull" />
+          ))}
+        </Box>
+
+        {isFinalStep ? (
+          <Button bg="white" color="prussian.80" hoverBg="blue.30" hoverColor="prussian.80" onClick={onFinish}>
+            Finish
+          </Button>
+        ) : (
+          <Button
+            color="white"
+            focusBorderColor="none"
+            hoverBg="none"
+            hoverBorder="none"
+            hoverBorderColor="blue.100"
+            icon="falArrowRight"
+            onClick={incrementStep}
+            scale={2}
+            transition="none"
+            variant="text"
+            w="80"
+          />
+        )}
+      </Box>
+    </Card>
+  )
+}

package/src/tutorial/tutorialStep.tsx

@@ -0,0 +1,20 @@
+import React from 'react'
+
+import { H5, P, v } from '../index'
+import { TutorialStepProps } from './tutorial.types'
+
+export const TutorialStep = ({ active, description, readMoreLink, title }: TutorialStepProps) => (
+  <v.div className="vui-tutorialStep" hidden={!active} pb={2}>
+    <H5 fontWeight="medium" mb={1}>
+      {title}
+    </H5>
+    <P>{description}</P>
+    {!!readMoreLink && (
+      <P>
+        <v.a href={readMoreLink} textDecoration="underline">
+          {readMoreLink}
+        </v.a>
+      </P>
+    )}
+  </v.div>
+)

package/src/tutorial/useTutorial.ts

@@ -0,0 +1,16 @@
+import { useEffect, useState } from 'react'
+
+import { CloseEvent } from './tutorial.types'
+
+export const useTutorial = (tutorialId: string) => {
+  const [isVisible, setIsVisible] = useState<boolean>(false)
+  const localStorageId = `vuiTutorial-${tutorialId}`
+
+  useEffect(() => {
+    setIsVisible(!window.localStorage.getItem(localStorageId))
+  }, [])
+
+  const saveDisplayed = (e: CloseEvent) => window.localStorage.setItem(localStorageId, e)
+
+  return { isVisible, setIsVisible, saveDisplayed }
+}