@stack-spot/portal-components 0.0.17 → 1.0.0

package/src/components/SelectionList.tsx

@@ -0,0 +1,361 @@
+import { Flex, IconBox, Text } from '@citric/core'
+import { ArrowLeft, Check, ChevronRight } from '@citric/icons'
+import { IconButton } from '@citric/ui'
+import { WithStyle, listToClass, theme } from '@stack-spot/portal-theme'
+import { Dictionary, useTranslate } from '@stack-spot/portal-translate'
+import { ReactElement, useCallback, useEffect, useMemo, useState } from 'react'
+import { styled } from 'styled-components'
+import { AnchorComponent, useAnchorTag } from '../context/anchor'
+import { useKeyboardControls } from '../hooks/keyboard'
+
+interface CustomLabel {
+  /**
+   * A unique identifier for this label. This is also used to read this label to screen readers.
+   */
+  id: string,
+  /**
+   * A custom label that can be made up of any React component.
+   */
+  element: React.ReactNode,
+}
+
+export interface Action {
+  /**
+   * The label of the action.
+   */
+  label: string | CustomLabel,
+  /**
+   * Function to run on a click.
+   */
+  onClick?: () => void,
+  /**
+   * URL to open on a click.
+   */
+  href?: string,
+  /**
+   * Target of the URL to open.
+   */
+  target?: React.AnchorHTMLAttributes<HTMLAnchorElement>['target'],
+}
+
+interface ItemWithIcon {
+  /**
+   * An Icon to appear at the left of the item.
+   */
+  icon?: React.ReactElement,
+  /**
+   * An Icon to appear at the right of the item.
+   */
+  iconRight?: React.ReactElement,
+}
+
+export interface ListAction extends ItemWithIcon, Action {
+  /**
+   * Whether or not this option is currently active.
+   */
+  active?: boolean,
+  /**
+   * Icon to render when this option is active.
+   */
+  iconActive?: React.ReactElement,
+}
+
+interface ListGroup {
+  /**
+   * If this group is rendered as a section with its items right below it or a collapsible, which requires a click to open a submenu.
+   */
+  type?: 'section' | 'collapsible',
+  /**
+   * The items of this group.
+   */
+  children: ListItem[],
+}
+
+interface ListSection extends ListGroup {
+  type: 'section',
+  /**
+   * The section's title.
+   */
+  label?: string,
+}
+
+interface ListCollapsible extends ListGroup, ItemWithIcon {
+  type?: 'collapsible',
+  /**
+   * The title of the collapsible menu.
+   */
+  label: string,
+}
+
+type ListItem = ListSection | ListCollapsible | ListAction
+
+interface CurrentItemList {
+  items: ListItem[],
+  label?: string,
+  parent?: CurrentItemList,
+}
+
+const ANIMATION_DURATION_MS = 300
+const MAX_HEIGHT_TRANSITION = `max-height ease-in ${ANIMATION_DURATION_MS / 1000}s`
+
+export interface SelectionListProps extends WithStyle {
+  /**
+   * The id of this selection list. This is important for accessibility. Be sure to link it to the aria-controls tag of the element who 
+   * controls the visibility of this selection list.
+   */
+  id: string,
+  /**
+   * Whether or not the selection list is visible.
+   */
+  visible?: boolean,
+  /**
+   * The options in the selection list.
+   */
+  items: ListItem[],
+  /**
+   * Function to run when the selection list is hidden/closed.
+   */
+  onHide?: () => void,
+  /**
+   * The maximum height for the selection list.
+   * @default "300px"
+   */
+  maxHeight?: string,
+  /**
+   * A React element to render right before the items.
+   */
+  before?: ReactElement,
+  /**
+   * A React element to render right after the items.
+   */
+  after?: ReactElement,
+  /**
+   * Whether or not this list should be scrollable.
+   */
+  scroll?: boolean,
+}
+
+interface RenderOptions {
+  setCurrent: (current: CurrentItemList) => void,
+  controllerId?: string,
+  onClose?: () => void,
+  Link: AnchorComponent,
+}
+
+const SelectionBox = styled.div<{ $maxHeight: string, $scroll?: boolean }>`
+  max-height: 0;
+  overflow-y: ${({ $scroll }) => $scroll ? 'auto' : 'hidden'};
+  overflow-x: hidden;
+  transition: ${MAX_HEIGHT_TRANSITION}, visibility 0s ${ANIMATION_DURATION_MS / 1000}s;
+  z-index: 1;
+  box-shadow: 4px 4px 48px #000;
+  border-radius: 0.5rem;
+  visibility: hidden;
+
+  .selection-list-content {
+    display: flex;
+    flex-direction: column;
+    background: ${theme.color.light['500']};
+    border-radius: 0.5rem;
+    border: 1px solid ${theme.color.light['600']};
+    background-color: ${theme.color.light['300']};
+  }
+
+  .section-title, li > a {
+    height: 40px;
+    padding: 0 8px;
+    display: flex;
+    flex-direction: row;
+    align-items: center;
+  }
+
+  li > a {
+    gap: 4px;
+    transition: background-color 0.2s;
+    &:hover, &:focus {
+      background: ${theme.color.light['400']};
+    }
+    .label {
+      flex: 1;
+      white-space: nowrap;
+      overflow: hidden;
+      text-overflow: ellipsis;
+    }
+  }
+
+  li.section {
+    border-bottom: 2px solid ${theme.color.light['600']};
+    &:last-child {
+      border-bottom: none;
+    }
+  }
+
+  &.visible {
+    max-height: ${({ $maxHeight }) => $maxHeight};
+    visibility: visible;
+    transition: ${MAX_HEIGHT_TRANSITION};
+  }
+`
+
+function renderAction({
+  label, href, onClick, icon, iconRight, active, target, iconActive = <Check />,
+}: ListAction, { onClose, Link }: RenderOptions) {
+  function handleClick() {
+    onClick?.()
+    onClose?.()
+  }
+
+  const isTextLabel = typeof label === 'string'
+
+  return (
+    <li key={isTextLabel ? label : label.id} className="action">
+      <Link href={href} onClick={handleClick} target={target} tabIndex={0} aria-selected={active}>
+        {icon && <IconBox>{icon}</IconBox>}
+        {isTextLabel ? <Text appearance="body2" className="label">{label}</Text> : label.element}
+        {iconRight && <IconBox>{iconRight}</IconBox>}
+        {active && <IconBox>{iconActive}</IconBox>}
+      </Link>
+    </li>
+  )
+}
+
+function renderCollapsible({ label, icon, iconRight, children }: ListCollapsible, { setCurrent, controllerId, Link }: RenderOptions) {
+  function handleClick(ev: React.MouseEvent) {
+    // accessibility: this will tell the screen reader the section was expanded before this link is removed from the DOM.
+    (ev.target as HTMLElement)?.setAttribute?.('aria-expanded', 'true')
+    setCurrent({ items: children, label })
+  }
+  return (
+    <li key={label} className="collapsible">
+      <Link onClick={handleClick} tabIndex={0} aria-expanded={false} aria-controls={controllerId}>
+        {icon && <IconBox>{icon}</IconBox>}
+        <Text appearance="body2" className="label">{label}</Text>
+        {iconRight && <IconBox>{iconRight}</IconBox>}
+        <IconBox><ChevronRight /></IconBox>
+      </Link>
+    </li>
+  )
+}
+
+function renderSection({ label, children }: ListSection, options: RenderOptions) {
+  return (
+    <li key={label ?? children.map(c => c.label).join('-')} className="section">
+      {label && <Text appearance="overheader2" colorScheme="primary" className="section-title">{label}</Text>}
+      <ul>{children.map(i => renderItem(i, options))}</ul>
+    </li>
+  )
+}
+
+function renderItem(item: ListItem, options: RenderOptions) {
+  if ('children' in item) {
+    return item.type === 'section' ? renderSection(item, options) : renderCollapsible(item, options)
+  }
+  return renderAction(item, options)
+}
+
+/**
+ * Renders a component that allows the selection of one item. The list is show/hidden according to the prop `visible`.
+ * 
+ * The items in this list can be grouped into multiple sections. Sections may be displayed on a column (section) or might replace the
+ * current list of options with another list of options (collapsible).
+ * 
+ * This component implements keyboard controls and accessibility features.
+ * @param props the component's props {@link SelectionListProps}.
+ */
+export const SelectionList = ({
+  id, items, className, style, visible = true, maxHeight = '300px', onHide, before, after, scroll,
+}: SelectionListProps) => {
+  const Link = useAnchorTag()
+  const t = useTranslate(dictionary)
+  const [current, setCurrent] = useState<CurrentItemList>({ items })
+  const { keyboardControlledElement: wrapper, attachKeyboardListeners, detachKeyboardListeners } = useKeyboardControls(
+    { onPressEscape: onHide, querySelectors: 'li.action a, li.collapsible a, button' },
+  )
+
+  const listItems = useMemo(
+    () => current.items.map(i => renderItem(
+      i,
+      {
+        setCurrent: (next: CurrentItemList) => setCurrent({ ...next, parent: current }),
+        onClose: onHide,
+        controllerId: id,
+        Link,
+      },
+    )),
+    [current],
+  )
+
+  const hide = useCallback((event: Event) => {
+    const target = (event.target as HTMLElement | null)
+    // if the element is not in the DOM anymore, we'll consider the click was inside the selection list
+    const isClickInsideSelectionList = !target?.isConnected || wrapper.current?.contains(target)
+    const isAction = target?.classList?.contains('action') || !!target?.closest('.action')
+    if (!isClickInsideSelectionList || isAction) onHide?.()
+  }, [])
+
+  useEffect(() => {
+    if (visible) {
+      setCurrent({ items })
+      attachKeyboardListeners()
+      if (onHide) setTimeout(() => document.addEventListener('click', hide), 50)
+    }
+    else {
+      detachKeyboardListeners()
+      document.removeEventListener('click', hide)
+    }
+  }, [visible])
+
+  return (
+    <SelectionBox
+      id={id}
+      ref={wrapper}
+      $maxHeight={maxHeight}
+      style={style}
+      className={listToClass(['selection-list', visible ? 'visible' : undefined, className])}
+      $scroll={scroll}
+      aria-hidden={!visible}
+    >
+      <div className="selection-list-content">
+        {before}
+        {current.parent
+          ? (
+            <Flex mt={5} mb={1} alignItems="center">
+              <IconButton
+                onClick={(ev) => {
+                  // accessibility: this will tell the screen reader the section was collapsed before this button is removed from the DOM.
+                  (ev.target as HTMLElement)?.setAttribute?.('aria-expanded', 'false')
+                  setCurrent(current.parent ?? { items })
+                }}
+                sx={{ mr: 3 }}
+                title={t.back}
+                aria-controls={id}
+                aria-expanded={true}
+              >
+                <ArrowLeft />
+              </IconButton>
+              <Text appearance="microtext1">{current.label}</Text>
+            </Flex>
+          )
+          : undefined
+        }
+        <ul>
+          {listItems}
+          {after &&
+            <li className="action">
+              {after}
+            </li>
+          }
+        </ul>
+      </div>
+    </SelectionBox>
+  )
+}
+
+const dictionary = {
+  en: {
+    back: 'Go back',
+  },
+  pt: {
+    back: 'Voltar',
+  },
+} satisfies Dictionary

package/src/components/{tour → Tour}/StepContainer.tsx

@@ -7,12 +7,28 @@ import { useTour } from './context'
 
 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}>

package/src/components/{tour → Tour}/StepNavigation.tsx

@@ -4,9 +4,33 @@ import { useTranslate } from '@stack-spot/portal-translate'
 import { useTour } from './context'
 import { finishTourStep } from './utils'
 
-type CustomNavigationButton = { text: string, onClick?: () => void }
-export type NavigationProps = { stepKey: string, nextButton?: CustomNavigationButton, prevButton?: CustomNavigationButton }
+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, nextStep, prevStep } = useTour()
   const t = useTranslate({ en: { of: 'of', back: 'back' }, pt: { of: 'de', back: 'voltar' } })

package/src/components/{tour → Tour}/StepTitle.tsx

@@ -1,11 +1,21 @@
 import { Button, Flex, IconBox, Text } from '@citric/core'
 import { TimesMini } from '@citric/icons'
 
-type StepTitleProps = {
+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>

package/src/components/{tour → Tour}/context.tsx

@@ -4,6 +4,9 @@ import { finishTourStep } from './utils'
 
 type TourConfig = Omit<ReactourProps, 'children'>
 
+/**
+ * Tutorial: the default configuration for a React Tour.
+ */
 export const defaultTourConfig: TourConfig = Object.freeze({
   steps: [],
   isOpen: true,
@@ -21,6 +24,10 @@ const TourContext = createContext<{ tourConfig: TourConfig, currentStep: number
   currentStep: 0,
 })
 
+/**
+ * Tutorial: provides the configuration for React Tour.
+ * @param props the configuration for the tour and the content to render.
+ */
 export const TourProvider = ({ config, children }: { config: TourConfig, children: ReactNode }) => {
   const [currentStep, setCurrentStep] = useState<number>(0)
   const tourConfig: TourConfig = {
@@ -41,6 +48,10 @@ export const TourProvider = ({ config, children }: { config: TourConfig, childre
   </TourContext.Provider>
 }
 
+/**
+ * Tutorial: retrieves data related to the current step of React Tour.
+ * @returns an object with all the information related to the steps of React Tour.
+ */
 export const useTour = () => {
   const { currentStep, tourConfig: { nextStep, prevStep, steps } } = useContext(TourContext)
   return {

package/src/components/{tour → Tour}/index.ts

@@ -2,6 +2,6 @@ import { ReactourProps, ReactourStep } from 'reactour'
 
 export { StepContainer } from './StepContainer'
 export { TourProvider, defaultTourConfig, useTour } from './context'
-export { isNewTourStep, tourStepBuilder } from './utils'
+export { hasFinishedTourStep, isNewTourStep, tourStepBuilder } from './utils'
 export { ReactourStep as TourStep }
 export type TourProps = Partial<Omit<ReactourProps, 'children'>> & { steps: ReactourStep[] }

package/src/components/Tour/utils.tsx

@@ -0,0 +1,93 @@
+import { theme } from '@stack-spot/portal-theme'
+import { ReactNode } from 'react'
+import { ReactourStep } from 'reactour'
+import { getCookie, setCookie } from '../../utils/cookie'
+import { PointingArrowPosition, StepContainer } from './StepContainer'
+import { NavigationProps } from './StepNavigation'
+
+const TOUR_COOKIE = 'guided-tour-global'
+
+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())
+}
+
+/**
+ * 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.
+ * @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) => getTourCookie().includes(key)
+
+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/context/anchor.tsx

@@ -0,0 +1,37 @@
+import { createContext, useContext } from 'react'
+
+export type AnchorComponent = (props: React.AnchorHTMLAttributes<HTMLAnchorElement>) => React.ReactElement
+
+interface AnchorContext {
+  /**
+   * The component to render by a layout component a link is needed.
+   * @default <a>
+   */
+  anchorTag?: AnchorComponent,
+}
+
+const context = createContext<AnchorContext>({})
+
+const Anchor: AnchorComponent = props => <a {...props} />
+
+/**
+ * Some components need to create HTML anchors (links) to other pages in the website. These links, sometimes, must to be managed by a 
+ * navigator for React. Since we don't want to couple this library with any specific navigator, you can provide your own component for
+ * creating links, it must follow the same interface of the HTML's `a` tag.
+ * 
+ * If this is not used, the tag `<a>` is used by default.
+ * @param props the anchor component (anchorTag) and the content to render (children).
+ */
+export const AnchorProvider = ({ children, ...props }: Required<AnchorContext> & { children: React.ReactNode }) => (
+  <context.Provider value={props}>{children}</context.Provider>
+)
+
+/**
+ * A React hook for retrieving the Link (anchor) component.
+ * @returns the link component declared at {@link AnchorProvider} or a component that renders the tag <a> from HTML if no link component was
+ * provided.
+ */
+export function useAnchorTag(): AnchorComponent {
+  const { anchorTag } = useContext(context)
+  return anchorTag ?? Anchor
+}