@stack-spot/portal-layout 0.0.65 → 1.0.0-dev.1768482785050

package/src/components/menu/types.ts

@@ -1,5 +1,5 @@
+import { Action } from '@stack-spot/portal-components/SelectionList'
 import { ReactElement, ReactNode } from 'react'
-import { Action } from '../types'
 
 interface BaseMenuItem {
   hidden?: boolean,
@@ -19,47 +19,111 @@ interface BaseMenuItem {
 }
 
 export interface ItemGroup extends BaseMenuItem {
+  /**
+   * The label for this group.
+   */
   label: string,
+  /**
+   * The items in this group.
+   */
   children: MenuItem[],
+  /**
+   * Whether it should start opened or not.
+   */
   open?: boolean,
+  showAsTitle?: boolean,
 }
 
 export interface MenuAction extends Action, BaseMenuItem {
+  /**
+   * Whether this menu item is currently active or not.
+   */
   active?: boolean,
 }
 
 export type MenuItem = ItemGroup | MenuAction
 
-export interface MenuButton extends Action {
-  icon?: ReactElement,
-}
-
 export interface SelectorItem extends Action {
+  /**
+   * A unique id for this item.
+   */
   key: string,
+  /**
+   * An icon to place at the left side of the item.
+   */
   icon?: ReactElement,
 }
 
 export interface Selector {
+  /**
+   * The current value. Must correspond to a `key` in `options`.
+   */
   value?: string,
+  /**
+   * A series of options to show in the selector.
+   */
   options: SelectorItem[],
+  /**
+   * An extra button to show after the list of options.
+   */
   button?: Action,
+  /**
+   * A title of this selector.
+   */
   title?: string,
+  /**
+   * A subtitle for this selector.
+   */
   subtitle?: string,
+  /**
+   * Whether or not the options for this selector are loading.
+   */
   loading?: boolean,
 }
 
 export interface MenuSectionContent {
+  /**
+   * A link to go back.
+   */
   goBack?: Action,
+  /**
+   * A title for this menu.
+   */
   title?: string,
+  /**
+   * A subtitle for this menu.
+   */
   subtitle?: string,
+  /**
+   * A custom React Node to add right after the menu title.
+   */
   afterTitle?: React.ReactNode,
+  /**
+   * A page selector.
+   */
   pageSelector?: Selector,
+  /**
+   * The menu options, may contain subgroups.
+   */
   options?: MenuItem[],
+  /**
+   * Whether or not the options for this menu are loading.
+   */
   loading?: boolean,
+  /**
+   * An error to show instead of the menu.
+   */
   error?: string,
 }
 
 export interface MenuSection extends Action {
+  /**
+   * Type should not be present in menu section items
+   */
+  type?: never,
+  /**
+   * The icon for this section.
+   */
   icon: ReactElement,
   /**
    * The content or a function that creates the content.
@@ -74,32 +138,173 @@ export interface MenuSection extends Action {
    * This should be used when the content you want to render is not the default content
    */
   customContent?: ReactNode,
+  /**
+   * Whether or not this section is currently active.
+   */
   active?: boolean,
-  onOpen?: () => void,
+  /**
+   * A css class to pass to the <li> tag.
+   */
+  className?: string,
+  hidden?: boolean,
+  /**
+   * The items in this group. This property will create a accordion to include the items
+   */
+  children?: MenuSection[],
+  /**
+   * initial value to accordion when using children prop
+   */
+  open?: boolean,
+  /**
+   * Badge to show at the right of the item.
+   */
+  badge?: ReactElement,
+  /**
+   * If true, when the section menu is collapsed, if this item has children, it will be replaced by its children and lose the
+   * collapse/expand behavior.
+   * @default true
+   */
+  replaceWithChildrenWhenCollapsed?: boolean,
+}
+
+export interface MenuSectionCustomItem {
+  /**
+   * Type to indicate the element is a custom item.
+   */
+  type: 'custom-element',
+  /**
+   * Children to be rendered
+   */
+  children?: ReactNode,
+  /**
+   * A css class to pass to the <div> tag.
+   */
   className?: string,
+  /**
+   * A boolean indicating whether or not the element should be visible.
+   */
   hidden?: boolean,
+  /**
+   * The icon for this section.
+   */
+  icon: ReactElement,
+
+  content?: never,
+  customContent?: never,
+  active?: never,
+  open?: never,
+  badge?: never,
+  label?: never,
+  onClick?: never,
+  href?: never,
+  target?: never,
+  lang?: never,
+  hrefLang?: never,
+  title?: never,
 }
 
 interface BaseMenuProps {
-  sections?: MenuSection[],
+  /**
+   * The sections of the menu.
+   */
+  sections?: (MenuSection | MenuSectionCustomItem)[],
+  /**
+   * The content of the menu as a React Element. Use this to create anything you want as the menu content, but prefer using `content`
+   * instead, which is a predefined menu.
+   */
   customContent?: ReactNode,
+  /**
+   * Options for the settings button.
+   */
   settings?: {
+    /**
+     * Whether or not to show the settings button.
+     */
+    show?: boolean,
+    /**
+     * A function to call when the button is clicked.
+     */
+    onClick?: () => void,
+    /**
+     * A url to go to when the button is clicked.
+     */
+    href?: string,
+    /**
+     * Whether or not this button represents the page currently active.
+     */
+    active?: boolean,
+    /**
+     * A css class to pass to the button.
+     */
+    className?: string,
+  },
+  /**
+   * Options for the rate button.
+   */
+  rateUs?: {
+    /**
+     * Whether or not to show the rate button.
+     */
+    show?: boolean,
+    /**
+     * A function to call when the button is clicked.
+     */
+    onClick?: () => void,
+    /**
+     * A url to go to when the button is clicked.
+     */
+    href?: string,
+    /**
+     * Whether or not this button represents the page currently active.
+     */
+    active?: boolean,
+    /**
+     * A css class to pass to the button.
+     */
+    className?: string,
+  },
+  /**
+   * Options for the contact us button.
+   */
+  contactUs?: {
+    /**
+     * Whether or not to show the rate button.
+     */
     show?: boolean,
+    /**
+     * A function to call when the button is clicked.
+     */
     onClick?: () => void,
+    /**
+     * A url to go to when the button is clicked.
+     */
     href?: string,
+    /**
+     * Whether or not this button represents the page currently active.
+     */
     active?: boolean,
+    /**
+     * A css class to pass to the button.
+     */
     className?: string,
+    /**
+     * Target of the URL to open.
+     */
+    target?: React.AnchorHTMLAttributes<HTMLAnchorElement>['target'],
   },
 }
 
 export interface MenuPropsWithStaticContent extends BaseMenuProps {
+  /**
+   * The config for creating the menu content.
+   */
   content?: MenuSectionContent,
 }
 
 export interface MenuPropsWithDynamicContent extends BaseMenuProps {
   /**
-   * The function that creates the content. It will be called only when the content is rendered, i.e. only when the content really needs to
-   * be rendered.
+   * The function that creates a config to render a menu content. It will be called only when the content is rendered, i.e. only when the
+   * content really needs to be rendered.
    * 
    * Tip: this function can be a React Hook.
    */
@@ -108,6 +313,13 @@ export interface MenuPropsWithDynamicContent extends BaseMenuProps {
    * Identifies each content that might be rendered by the menu. This prevents React Hook errors when the content is a React Hook function.
    */
   contentKey: React.Key,
+  /**
+   * The function that creates a config to render a third level nav menu content. It will be called only when the content is rendered,
+   * i.e. only when the content really needs to be rendered.
+   * 
+   * Tip: this function can be a React Hook.
+   */
+  innerContent?: MenuSectionContent | (() => MenuSectionContent | undefined),
 }
 
 export type MenuProps = MenuPropsWithStaticContent | MenuPropsWithDynamicContent

package/src/components/tour/StepContainer.tsx

@@ -0,0 +1,92 @@
+import { theme } from '@stack-spot/portal-theme'
+import React, { 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,
+  /**
+   * The CSS 'right' property to adjust the horizontal position of the overlay.
+   */
+  right?: React.CSSProperties['right'],
+  /**
+   * The CSS 'top' property to adjust the vertical position of the overlay.
+   */
+  top?: React.CSSProperties['top'],
+  /**
+   * 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 = 'bottom', top, right, children }: StepContainerProps) => {
+  const { closeTour } = useTour()
+  return (
+    <BoxWithPointingArrow $position={position} $top={top} $right={right}>
+      <StepTitle title={title} onClose={() => closeTour()} />
+      {children}
+      <StepNavigation stepKey={stepKey} {...(customNavigation || {})} />
+    </BoxWithPointingArrow>
+  )
+}
+
+export type PointingArrowPosition = 'right' | 'top' | 'left' | 'bottom'
+
+const BoxWithPointingArrow = styled.div < {
+  $position: PointingArrowPosition,
+  $top?: React.CSSProperties['top'],
+  $right?: React.CSSProperties['right'],
+} > `
+  position: relative;
+  width: 100%;
+  background-color: ${theme.color.inverse[500]};
+  &::after {
+    content: '';
+    position: absolute;
+    border-width: 10px;
+    border-style: solid;
+    border-color: transparent;
+    border-right-color: ${theme.color.inverse[500]};
+    ${({ $position, $top }) => $position === 'right' ?
+    `
+      top: ${$top || '16px'};
+      right: 100%;
+    ` : ''}
+    ${({ $position, $right }) => $position === 'top' ?
+    `
+    top: 100%;
+    right: ${$right || '16px'};
+    transform: rotate(-90deg);
+    ` : ''}
+    ${({ $position, $top }) => $position === 'left' ?
+    `
+      top: ${$top || '16px'};
+      left: 100%;
+      transform: rotate(180deg);
+    ` : ''}
+    ${({ $position, $right }) => $position === 'bottom' ?
+    `
+    bottom: 100%;
+    right: ${$right || '16px'};
+    transform: rotate(90deg);
+    ` : ''}
+  }
+`

package/src/components/tour/StepNavigation.tsx

@@ -0,0 +1,72 @@
+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">
+    { steps.length > 1 &&
+      <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,28 @@
+import { Flex, IconBox, Text } from '@citric/core'
+import { TimesMini } from '@citric/icons'
+import { IconButton } from '@citric/ui'
+
+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} px={5} py={3} flexWrap="nowrap" justifyContent="space-between" alignItems="center">
+    <Text appearance="body2" colorScheme="inverse.contrastText" weight="medium"> {title} </Text>
+    <IconButton onClick={onClose} sx={{ r: 'full', p: 0 }} >
+      <IconBox size="xs" colorIcon="inverse.contrastText">
+        <TimesMini />
+      </IconBox>
+    </IconButton>
+  </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 { useTour } from './hook'
+export { TourConfig, TourConfigListener, tourManager, TourStep, WelcomeTour } from './manager'
+export { StepContainer } from './StepContainer'
+export { getTourCookie, hasFinishedTourStep, isNewTourStep, StackspotTourStep, tourStepBuilder } from './utils'
+

package/src/components/tour/manager.tsx

@@ -0,0 +1,119 @@
+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,
+  closeTour: () => 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),
+      closeTour: () => this.closeTour(),
+    }
+    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()
+  }
+
+  closeTour() {
+    this.steps.forEach((step) => step.selector && finishTourStep(step.selector))
+    this._currentStep = this.steps.length
+    this.notify()
+  }
+
+  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 }
+