@stack-spot/portal-components 0.0.17 → 1.0.0-dev.1768482754546

package/src/components/SelectionList.tsx

@@ -0,0 +1,427 @@
+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?: (event?: React.MouseEvent) => void,
+  /**
+   * URL to open on a click.
+   */
+  href?: string,
+  /**
+   * Target of the URL to open.
+   */
+  target?: React.AnchorHTMLAttributes<HTMLAnchorElement>['target'],
+  /**
+   * Language of the linked document.
+   */
+  lang?: React.AnchorHTMLAttributes<HTMLAnchorElement>['lang'],
+  /**
+   * Language of the destination URL.
+   */
+  hrefLang?: React.AnchorHTMLAttributes<HTMLAnchorElement>['hrefLang'],
+  /**
+   * The title of the action. 
+   */
+  title?: string,
+}
+
+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,
+  /**
+   * A class to be added to this item.
+   */
+  className?: string,
+  /**
+ * Defines the ARIA role of the element for accessibility purposes. Example: "button", "dialog", etc.
+ */
+  role?: string,
+}
+
+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[],
+  /**
+  * A class to be added to this item.
+  */
+  className?: string,
+}
+
+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,
+  /**
+   * Show list as card
+   */
+  showListAsCard?: boolean,
+}
+
+interface RenderOptions {
+  setCurrent: (current: CurrentItemList) => void,
+  controllerId?: string,
+  onClose?: () => void,
+  Link: AnchorComponent,
+}
+
+const SelectionBox = styled.div<{ $maxHeight: string, $scroll?: boolean, $showListAsCard?: 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;
+    border-radius: 0.5rem;
+    background-color: ${theme.color.light['300']};
+    padding-inline: ${({ $showListAsCard }) => $showListAsCard ? '8px' : '0'};
+  }
+
+  .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.action {
+    background-color: ${({ $showListAsCard }) => $showListAsCard ? theme.color.light['400'] : ''};
+    border:  ${({ $showListAsCard }) => '1px solid' + $showListAsCard ? theme.color.light['500'] : 'transparent'};
+    border-radius: ${({ $showListAsCard }) => $showListAsCard ? '4px' : '0'};
+    margin-bottom: ${({ $showListAsCard }) => $showListAsCard ? '8px' : '0'};
+  }
+
+  li.section {
+    border-bottom: 2px solid;
+    border-bottom-color: ${({ $showListAsCard }) => $showListAsCard ? 'transparent' : 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 />,
+  className = '', lang, hrefLang, title, role = 'link',
+}: ListAction, { onClose, Link }: RenderOptions) {
+  function handleClick(event: React.MouseEvent) {
+    onClick?.(event)
+    onClose?.()
+  }
+
+  const isTextLabel = typeof label === 'string'
+
+  return (
+    <li key={isTextLabel ? label : label.id} className="action" title={title}>
+      <Link href={href} onClick={handleClick} target={target} tabIndex={0} aria-current={active && 'page'}
+        className={className} lang={lang} hrefLang={hrefLang} role={role}>
+        {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, className = '', 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} className={className} 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, className = '', children }: ListSection, options: RenderOptions) {
+  return (
+    <li key={label ?? children.map(c => c.label).join('-')} className={`${className} section`}>
+      {label && <Text appearance="overheader2" colorScheme="light.700" 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, showListAsCard,
+}: 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],
+  )
+
+  useEffect(() => {
+    const selectionBox = wrapper.current
+    if (!selectionBox) return
+
+    const handleTransitionEnd = () => {
+      selectionBox.style.overflow = 'auto'
+    }
+
+    selectionBox.addEventListener('transitionend', handleTransitionEnd)
+
+    return () => {
+      selectionBox.removeEventListener('transitionend', handleTransitionEnd)
+    }
+  }, [])
+
+  const handleExpand = () => {
+    const selectionBox = wrapper.current
+    if (selectionBox) {
+      selectionBox.style.overflow = 'hidden'
+    }
+  }
+
+  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')
+    const isInsideTour = !!target?.closest('#___reactour')
+    if (!isInsideTour && (!isClickInsideSelectionList || isAction)) onHide?.()
+  }, [])
+
+  useEffect(() => {
+    handleExpand()
+    function removeListeners() {
+      detachKeyboardListeners()
+      document.removeEventListener('click', hide)
+    }
+    if (visible) {
+      setCurrent({ items })
+      attachKeyboardListeners()
+      if (onHide) setTimeout(() => document.addEventListener('click', hide), 50)
+    } else {
+      removeListeners()
+    }
+    return () => removeListeners()
+  }, [visible, items])
+
+  return (
+    <SelectionBox
+      id={id}
+      ref={wrapper}
+      $maxHeight={maxHeight}
+      style={style}
+      className={listToClass(['selection-list', visible ? 'visible' : undefined, className])}
+      $scroll={scroll}
+      aria-hidden={!visible}
+      $showListAsCard={showListAsCard}
+    >
+      <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/StatusCircle.tsx

@@ -0,0 +1,67 @@
+import { OneOfColorSchemesWithVariants, OneOfPalettesWithVariants, Theme } from '@citric/core'
+import { getColor } from '@citric/core/dist/utils/theme'
+import { Tooltip } from '@citric/ui'
+import styled from 'styled-components'
+
+type Color = OneOfColorSchemesWithVariants | OneOfPalettesWithVariants
+
+export type Status = 'success' | 'warning' | 'danger' | 'unknown' | 'progress'
+
+interface Props {
+  /** The status of the component which determines its color */
+  status?: Status,
+  /** Tooltip text to be displayed on hover */
+  tooltip?: string,
+}
+
+const statusToColor: Record<Status, Color> = {
+  success: 'success.500',
+  warning: 'warning.500',
+  danger: 'danger.500',
+  progress: 'secondary.500',
+  unknown: 'light.contrastText',
+}
+
+/**
+ * Get the color corresponding to the status.
+ *
+ * @param {Theme} theme - The theme object.
+ * @param {Status} [status] - The status of the component.
+ * @returns {string} The color corresponding to the status.
+ */
+function getColorFromStatus(theme: Theme, status?: Status) {
+  const colorName = status && status in statusToColor ? statusToColor[status] : statusToColor.unknown
+  return getColor(theme, colorName)
+}
+
+interface WithTooltip {
+  /** Tooltip text to be displayed on hover */
+  tooltip?: string,
+  /** Additional class names for the component */
+  className?: string,
+  /** Inline styles for the component */
+  style?: React.CSSProperties,
+}
+
+/**
+ * CircleWithTooltip component that displays a circle with an optional tooltip.
+ *
+ * @param props the component's props {@link WithTooltip}.
+ */
+const CircleWithTooltip = ({ tooltip, className, style }: WithTooltip) => {
+  const circle = <div style={style} className={className}></div>
+  return tooltip && tooltip.length ? <Tooltip text={tooltip}>{circle}</Tooltip> : circle
+}
+
+/**
+ * Renders a component that displays a colored circle based on the status.
+ * It also supports an optional tooltip.
+ *
+ * @param props the component's props {@link Props}.
+ */
+export const StatusCircle = styled(CircleWithTooltip)<Props>`
+  background-color: ${({ status, theme }) => getColorFromStatus(theme as any, status)};
+  width: 12px;
+  height: 12px;
+  border-radius: 50%;
+`

package/src/components/Stepper/Navigation.tsx

@@ -0,0 +1,97 @@
+import { Button, Flex, Text } from '@citric/core'
+import { Dictionary, useTranslate } from '@stack-spot/portal-translate'
+import { FC, useContext } from 'react'
+import { styled } from 'styled-components'
+import { ButtonProps } from '@citric/core/dist/Button'
+import { useLoadingComponent } from '../../context/loading'
+import { StepperContext } from './Stepper'
+
+export interface StepperNavigationProps extends ButtonProps{
+  /**
+   * Prop used to pass specific text to the next button.
+   */
+  nextButtonText?: string,
+  /**
+   * Function that is rendered when pressing the skip button.
+   */
+  onSkip?: () => void,
+  /**
+   * Boolean that is used as a conditional to appear the skip button.
+   */
+  canSkip?: boolean,
+  /**
+   * Boolean that is used as a conditional to appear the loading icon in next button.
+   */
+  isLoading?: boolean,
+  /**
+   * Function that is rendered when pressing the back button.
+   */
+  onGoBack?: () => void,
+  /**
+   * Function that is rendered when pressing the next button.
+   */
+  onSubmit?: () => void,
+}
+
+const Wrapper = styled(Flex)`
+  width: 100%;
+  justify-content: space-between;
+`
+
+/**
+ * Renders a component that represents the stepper component's navigation buttons, containing the button options (back, skip, and next).
+ * 
+ * The component stepper wraps this component.
+ */
+
+export const StepperNavigation: FC<Omit<StepperNavigationProps, 'children'>> = (
+  { nextButtonText, onSkip, onGoBack, canSkip = false, isLoading, disabled, onSubmit }) => {
+  const t = useTranslate(dictionary)
+  const { goToNextStep, goToPreviousStep } = useContext(StepperContext)
+  const Loading = useLoadingComponent()
+
+  return (
+    <Wrapper>
+      <Button
+        appearance="contained"
+        colorScheme="inverse"
+        onClick={() => {
+          onGoBack && onGoBack()
+          goToPreviousStep()
+        }}
+      >
+        {t.back}
+      </Button>
+      <Flex>
+        {canSkip && (
+          <Button
+            appearance="text"
+            colorScheme="inverse"
+            onClick={() => {
+              onSkip && onSkip()
+              goToNextStep()
+            }}
+          >
+            {t.skip}
+          </Button>
+        )}
+        <Button type="submit" onClick={onSubmit} sx={{ position: 'relative' }} disabled={isLoading || disabled}>
+          <Text as="span" sx={{ visibility: isLoading ? 'hidden' : 'visible' }}>{nextButtonText ?? t.next}</Text>
+          {isLoading && Loading}
+        </Button>
+      </Flex>
+    </Wrapper>
+  )}
+
+const dictionary = {
+  en: {
+    back: 'Back',
+    skip: 'Skip',
+    next: 'Next',
+  },
+  pt: {
+    back: 'Voltar',
+    skip: 'Pular',
+    next: 'Próximo',
+  },
+} satisfies Dictionary

package/src/components/Stepper/Step.tsx

@@ -0,0 +1,30 @@
+import { Box } from '@citric/core'
+import { FC, PropsWithChildren } from 'react'
+import { styled } from 'styled-components'
+
+export interface StepProps extends PropsWithChildren {
+  /**
+   * Name given to the step.
+   */
+  name: string,
+  /**
+   * Title given to the step.
+   */
+  title: string,
+}
+
+const Wrapper = styled(Box)`
+  width: 100%;
+`
+
+/**
+ * Renders a component that represents the body of a step within the stepper component.
+ * 
+ * The component stepper wraps this component.
+ */
+
+export const Step: FC<StepProps> = ({ children }) => (
+  <Wrapper>
+    {children}
+  </Wrapper>
+)