@stack-spot/portal-components 0.0.18 → 1.0.1

package/package.json

@@ -1,22 +1,31 @@
 {
   "name": "@stack-spot/portal-components",
-  "version": "0.0.18",
+  "version": "1.0.1",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js",
+    "./Breadcrumb": "./dist/components/Breadcrumb/index.js",
+    "./ErrorFeedback": "./dist/components/ErrorFeedback.js",
+    "./SelectionList": "./dist/components/SelectionList.js",
+    "./Tour": "./dist/components/Tour/index.js",
+    "./svg": "./dist/svg/index.js",
+    "./anchor": "./dist/context/anchor.js"
+  },
   "scripts": {
-    "build": "tsc && tsc-esm-fix --target='dist'",
-    "lint": "eslint . --ext ts,tsx --report-unused-disable-directives --max-warnings 0"
+    "build": "rimraf dist && tsc && tsc-esm-fix --target='dist'",
+    "lint": "eslint . --ext ts,tsx --report-unused-disable-directives --max-warnings 0",
+    "check-tree-shaking": "agadoo"
   },
   "peerDependencies": {
-    "@citric/core": ">=6.0.0",
-    "@citric/icons": ">=5.4.0",
-    "@citric/ui": ">=5.4.0",
-    "@stack-spot/portal-theme": ">=1.0.0",
-    "@stack-spot/portal-translate": ">=1.0.0",
-    "react": ">=18.2.0",
-    "react-dom": ">=18.2.0",
-    "styled-components": ">=6.1.10"
+    "@citric/core": "^6.0.0",
+    "@citric/icons": "^5.4.0 || ^6.0.0",
+    "@citric/ui": "^5.4.0 || ^6.0.0",
+    "@stack-spot/portal-theme": "^1.0.0",
+    "@stack-spot/portal-translate": "^1.0.0",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0"
   },
   "devDependencies": {
     "@types/lodash": "^4.14.202",
@@ -25,6 +34,7 @@
     "@types/reactour": "^1.18.5",
     "@typescript-eslint/eslint-plugin": "^6.10.0",
     "@typescript-eslint/parser": "^6.10.0",
+    "agadoo": "^3.0.0",
     "eslint": "^8.53.0",
     "eslint-plugin-filenames": "^1.3.2",
     "eslint-plugin-import": "^2.29.0",
@@ -33,12 +43,13 @@
     "eslint-plugin-react": "^7.33.2",
     "eslint-plugin-react-hooks": "^4.6.0",
     "eslint-plugin-react-refresh": "^0.4.4",
+    "rimraf": "^5.0.7",
+    "styled-components": "6.1.10",
     "tsc-esm-fix": "^2.20.26",
     "typescript": "^5.2.2"
   },
   "dependencies": {
     "lodash": "^4.17.21",
-    "react-toastify": "^9.1.3",
     "reactour": "^1.19.3"
   }
 }

package/readme.md

@@ -1,24 +1,69 @@
 # Components
-Although this lib is called components, it may also contain hooks and containers.
+A collection of UI components, hooks, SVG images, utilities and variables shared among Stackspot web projects.
 
-This library was made in order to share common components, containers and hooks among Stack Spot projects.
-
-What about the Design System (DS)? Some components here may be upgraded to the design system level eventually. But this is a place where we can have any kind of component, despite it belonging to a DS or not.
+What about the Design System (DS)? Some components here may be upgraded to the design system level eventually. But this is a place where we
+can have any kind of component, despite it belonging to a DS or not.
 
 ## Presentation components
 These are pure functions, i.e. they rely only in their inputs to render the UI. Furthermore, they don't have any collateral effect.
 
-Exceptions: translations are the only exception here. These components can access the current language without having it passed as parameter.
-
-- BreadcrumbList: renders a list of breadcrumb navigation items.
-
-## Containers
-Containers are components that can access more than what has been passed as parameter. They can also have collateral effects.
+Exceptions: translations are the only exception here. These components can access the current language without having it passed as
+parameter.
 
-We don't have any containers yet.
+- `BreadcrumbList`: renders a list of breadcrumb navigation items. Must be imported from `@stack-spot/portal-components/Breadcrumb`.
+- `StepContainer`, `TourProvider`, `TourStep`: components related to React Tour, i.e. the tutorial engine used by Stackspot. Must be imported
+from `@stack-spot/portal-components/Tour`.
+- `BannerWarning`: a yellow alert box with an exclamation icon and the content passed as parameter. Used for warning messages.
+- `ChatBot`: an orange circular button that can toggle the chat window from Service Now. The button has a chat icon when the window is
+closed and a close icon when it's open.
+- `ErrorFeedback`: a box with an icon and an error message. This is used for giving error feedbacks to the user.
+- `SelectionList`: a selection UI that allows the selection of one single item. These items can be divided in sections (groups). This
+component is highly customizable and has lots of accessibility features implemented.
+- `AnchorProvider`: a way to provide an anchor component (links) to be used by Stackspot libraries. This allows these libraries not to be
+coupled with an specific React navigators. To retrieve the component, use `useLinkComponent`. Must be imported from
+`@stack-spot/portal-components/anchor`.
 
 ## Hooks
 These are useful react hooks shared among the StackSpot portals.
 
-- `useEffectOnce()`: runs an effect only once, when the component is mounted. This prevents React from running the effect twice when in development mode.
-- `useTitleEffect(title)`: changes the title for the current page. The title is returned to its original value as soon as the component is unmounted.
+- `useEffectOnce()`: runs an effect only once, when the component is mounted. This prevents React from running the effect twice when in
+development mode.
+- `useTitleEffect(title)`: changes the title for the current page. The title is returned to its original value as soon as the component is
+unmounted.
+- `useCheckTextOverflow()`: checks if the text fits completely in the space available.
+- `useLinkComponent()`: retrieves the anchor component declared at the closest `AnchorProvider`. If no component was provided, returns a
+component that renders the HTML `<a>` tag directly. This is useful for integration with navigators for React. Must be imported from
+`@stack-spot/portal-components/anchor`.
+- `useKeyboardControls(options)`: creates listeners for controlling a Menu UI through the keyboard (up, down, tab, esc, enter).
+- `useServiceNowEffect(options)`, `useServiceNowChatButtonVisibility()`: Service Now hooks (chat capabilities).
+- `useTour()`: retrieves data related to the current step of React Tour (tutorial). Must be imported from
+`@stack-spot/portal-components/Tour`.
+
+## SVG images
+Some SVG images are exported as React components at `@stack-spot/portal-components/svg`.
+
+## Utilities and variables
+These are useful functions shared among the StackSpot portals.
+
+#### Accessibility
+- `focusNextIgnoringChildren(element)`: focus the next element in the hierarchy, ignoring the children of the element passed as parameter.
+- `focusFirstChild(element, options)`: focus the first child of element that is focusable according to the options.
+- `isFocusable(element)`: checks if the element can receive focus.
+- `focusAccessibleElement(element)`: tries to focus the element passed as parameter, but if it's not focusable, finds another element to
+focus according to accessibility rules.
+
+#### Cookie
+- `setupCookies(domainRegex)`: setup a domain regex for the cookies. Use this if the domain is different than localhost or *.stackspot.com.
+- `getCookies()`: retrieves an object with all the cookies.
+- `getCookie(name)`: same as `getCookies()[name]`. 
+- `setCookie(name, value)`: sets the value of a cookie.
+- `removeCookie(name)`: removes a cookie.
+
+#### Other
+- `isNewTourStep(step)`, `hasFinishedTourStep(key)`, `tourStepBuilder(options)`, `defaultTourConfig`: related to React Tour (tutorial).
+- `openServiceNowChat()`, `serviceNowDictionary`: related to Service Now chat service.
+
+# Developer notes
+- Since not every component in this library will be used by every project. This library must be tree-shakeable! Before committing, make sure
+`pnpm check-tree-shaking` passes.
+ 

package/src/components/BannerWarning.tsx

@@ -2,6 +2,12 @@ import { Flex, IconBox, Text } from '@citric/core'
 import { ExclamationTriangle } from '@citric/icons'
 import { Alert } from '@citric/ui'
 
+/**
+ * A styled and non-dismissible alert box for showing important warnings for the user.
+ * 
+ * This renders a yellow box with an exclamation icon. The content passed as parameter is placed on the right of the icon. 
+ * @param props an object containing the content (children) to show inside the alert box.
+ */
 export const BannerWarning = ({ children }: { children: React.ReactNode }) => (
   <Flex sx={{ position: 'fixed', top: 0, zIndex: '999', w: 12, left: 0 }}>
     <Alert colorScheme="warning" sx={{ p: 2, w: 12, justifyContent: 'center', height: ['60px', '100px'] }}>

package/src/components/Breadcrumb/index.tsx

@@ -2,6 +2,7 @@ import { Text } from '@citric/core'
 import { Skeleton } from '@citric/ui'
 import { last } from 'lodash'
 import { useEffect, useMemo } from 'react'
+import { useAnchorTag } from '../../context/anchor'
 import { titleEffect } from '../../hooks/title'
 import { Box } from './styled'
 
@@ -20,10 +21,6 @@ interface BreadcrumbItem {
    * If this route is accessible, the link to it.
    */
   href?: string,
-  /**
-   * Anchor from Citron to be used
-   */
-  anchorTag?: AnchorComponent,
 }
 
 interface Props {
@@ -45,16 +42,20 @@ interface Props {
    */
   shouldUpdatePageTitle?: boolean,
   /**
-   * Anchor from Citron to be used
+   * Key of the current page. If an item has this key, it won't be rendered as a link and will be marked as active.
    */
-  anchorTag?: AnchorComponent,
+  currentPageKey?: string,
+}
+
+interface ItemProps extends Pick<Props, 'currentPageKey'> {
+  item: BreadcrumbItem,
 }
 
-const BreadcrumbItem = ({ label, href, anchorTag }: BreadcrumbItem) => {
+const BreadcrumbItem = ({ item: { label, href, key }, currentPageKey }: ItemProps) => {
   const text = <Text appearance="breadcrumb">{label}</Text>
-  const anchor: AnchorComponent = props => <a {...props} href={href}>{text}</a>
-  const LinkAnchor = anchorTag ?? anchor
-  return href ? <LinkAnchor href={href}>{text}</LinkAnchor> : text
+  const Link = useAnchorTag()
+  const shouldBeLink = href && currentPageKey != key
+  return <li>{shouldBeLink ? <Link href={href}>{text}</Link> : text}</li>
 }
 
 /**
@@ -62,9 +63,10 @@ const BreadcrumbItem = ({ label, href, anchorTag }: BreadcrumbItem) => {
  * 
  * If the breadcrumb is obtained asynchronously, pass `isLoading = true` in order to show a loading feedback.
  */
-export const BreadcrumbList = ({ items, isLoading, shouldUpdatePageTitle, anchorTag }: Props) => {
-  const listItems = useMemo(() => items.map(item =>
-    <li key={item.key || item.label}><BreadcrumbItem anchorTag={anchorTag}  {...item} /></li>), [items, anchorTag],
+export const BreadcrumbList = ({ items, isLoading, shouldUpdatePageTitle, currentPageKey }: Props) => {  
+  const listItems = useMemo(
+    () => items.map(item => <BreadcrumbItem key={item.key || item.label} item={item} currentPageKey={currentPageKey} />),
+    [items],
   )
   useEffect(() => {
     const title = last(items)?.label

package/src/components/Breadcrumb/styled.ts

@@ -2,7 +2,8 @@ import { getFontAppearance } from '@citric/core/dist/utils/theme'
 import { theme } from '@stack-spot/portal-theme'
 import { styled } from 'styled-components'
 
-export const Box = styled.nav`
+// the type below should be inferred, but a bug in TS+PNPM prevents it: https://github.com/microsoft/TypeScript/issues/42873
+export const Box: React.FC<React.DetailedHTMLProps<React.HTMLAttributes<HTMLElement>, HTMLElement>> = styled.nav`
   margin-bottom: 24px;
   
   ul {

package/src/components/ChatBot.tsx

@@ -1,6 +1,9 @@
 import { Button, Flex, IconBox, Styles } from '@citric/core'
 import { QuestionAnswer, Times } from '@citric/icons'
-import { addOrRemoveServiceNowLauncher, getServiceNowLauncher } from '../hooks/service-now'
+import { getServiceNowLauncher, hideChatWindow, showChatWindow } from '../hooks/service-now'
+
+export const CHAT_BUTTON_ID = 'service-now-button'
+export const CHAT_BUTTON_WRAPPER_ID = 'service-now-content'
 
 const styles: Styles = {
   content: {
@@ -44,24 +47,29 @@ const styles: Styles = {
   },
 }
 
+/**
+ * A button for opening or closing the service-now chat window.
+ * 
+ * This is a circular orange button with a chat icon if the chat window is closed or a close icon if the chat window is open.
+ */
 export const ChatBot = () => {
   const handleOpenChatBot = () => {
     const chatIframe = getServiceNowLauncher()
     if (chatIframe) {
-      const isShow = chatIframe.classList.contains('show')
-      if (isShow) {
-        addOrRemoveServiceNowLauncher('remove')
+      const isVisible = chatIframe.classList.contains('show')
+      if (isVisible) {
+        hideChatWindow()
       } else {
-        addOrRemoveServiceNowLauncher('add')
+        showChatWindow()
       }
     }
   }
 
   return (
-    <Flex id="service-now-content" sx={styles.content}>
+    <Flex id={CHAT_BUTTON_WRAPPER_ID} sx={styles.content}>
       <Button
         onClick={handleOpenChatBot}
-        id="service-now-button"
+        id={CHAT_BUTTON_ID}
         sx={styles.button}
       >
         <IconBox

package/src/components/ErrorFeedback.tsx

@@ -0,0 +1,135 @@
+import { Box, Button, Container, Flex, LinkBox, Text } from '@citric/core'
+import { Dictionary, useTranslate } from '@stack-spot/portal-translate'
+import { useState } from 'react'
+import { Forbidden } from '../svg/Forbidden'
+import { Logo } from '../svg/Logo'
+import { NotFound } from '../svg/NotFound'
+import { ServerError } from '../svg/ServerError'
+import { Unauthenticated } from '../svg/Unauthenticated'
+
+const imageStyle: React.CSSProperties = {
+  width: '200px',
+  height: '200px',
+}
+
+const imageMap: Record<number, React.ReactElement> = {
+  401: <Unauthenticated style={imageStyle} />,
+  403: <Forbidden style={imageStyle} />,
+  404: <NotFound style={imageStyle} />,
+}
+
+export interface ErrorDescription {
+  /**
+   * The HTTP Error code if this is a network error.
+   */
+  code?: number,
+  /**
+   * The error message.
+   */
+  message?: string,
+  /**
+   * Whether or not the application is in debug mode.
+   */
+  debug?: boolean,
+}
+
+/**
+ * A box with an icon and an error message. This is used for giving error feedbacks to the user.
+ * 
+ * If the application is in debug mode, a button is rendered to show the error message.
+ * 
+ * @param options the error code, the error message and whether or not the application is in debug mode.
+ */
+export const ErrorFeedback = ({ code = 0, message, debug }: ErrorDescription) => {
+  const t = useTranslate(dictionary) as Record<string, string>
+  const [showDetails, setShowDetails] = useState(false)
+
+  return (
+    <Box bg="light.400">
+      <Container>
+        <Flex alignItems="center" sx={{ padding: 12 }}>
+          <Box width={5} sx={{ display: ['block', 'none'] }}>
+            <Flex justifyContent="flex-end" pr={20}>
+              {imageMap[code] ?? <ServerError style={imageStyle} />}
+            </Flex>
+          </Box>
+          <Box width={[7, 12]}> 
+            <LinkBox href="/">
+              <Logo style={{ width: '130px', height: '30px' }} />
+            </LinkBox>
+            <Box w={[7, 12]}>
+              <Text appearance="h4" mt={5} colorScheme="inverse">
+                {code ? `${code}. ` : ''}
+                <Text appearance="h4" as="span" colorScheme="light.700">
+                  {t[`${code}.title`]}
+                </Text>
+              </Text>
+
+              <Text appearance="body1" mt={5} colorScheme="inverse">
+                {t[`${code}.description`]}
+              </Text>
+
+              <Text appearance="body1" colorScheme="light.700" mt={1}>
+                {t[`${code}.help`]}
+              </Text>
+              {debug && message && (
+                <Button appearance="outlined" colorScheme="inverse" onClick={() => setShowDetails(v => !v)}>
+                  {showDetails ? t.hideDetails : t.showDetails}
+                </Button>
+              )}
+              {showDetails && (
+                <Box bg="danger" mt={8} p={4} sx={{ borderRadius: '5px' }}>
+                  <Text appearance="microtext1" colorScheme="danger.contrastText">{message}</Text>
+                </Box>
+              )}
+            </Box>
+          </Box>
+        </Flex>
+      </Container>
+    </Box>
+  )
+}
+
+const dictionary = {
+  en: {
+    altLogo: 'Logo Stackspot',
+    '0.title': 'Unknown client error',
+    '0.description': 'An unknown error happened while trying to load the resource.',
+    '0.help': 'Reload the page and, if it still doesn\'t work, report the error the Stackspot team.',
+    '401.title': 'Not authorized',
+    '401.description': 'There was a failure loading credentials for this page.',
+    '401.help': 'Check if the URL is correct or clear your cache and cookies from your browser and try again.',
+    '403.title': 'Private access',
+    '403.description': 'The page you have tried to visit is private.',
+    '403.help': 'Log in with another account or request access from the person who manages your organization.',
+    '404.title': 'Resource not found',
+    '404.description': 'This resource no longer exists.',
+    '404.help': 'Please try again or request a new URL from the person who manages your organization.',
+    '500.title': 'Server error',
+    '500.description':
+      "We have identified a problem with the server, but don't worry. We are already investigating what happened.",
+    '500.help': 'Please try again after a few minutes.',
+    showDetails: 'Show Details',
+    hideDetails: 'Hide Details',
+  },
+  pt: {
+    altLogo: 'Logo Stackspot',
+    '0.title': 'Erro desconhecido (cliente)',
+    '0.description': 'Um erro desconhecido aconteceu ao carregar o recurso',
+    '0.help': 'Recarregue a página e, se ainda não funcionar, reporte o problema para o time da Stackspot.',
+    '401.title': 'Não autorizado',
+    '401.description': 'Houve uma falha no carregamento de credenciais dessa página.',
+    '401.help': 'Verifique se a URL está correta ou limpe o cache e os cookies de seu navegador e tente novamente.',
+    '403.title': 'Acesso privado',
+    '403.description': '"A página que você tentou visualizar é particular."',
+    '403.help': 'Solicite acesso com o administrador da sua organização.',
+    '404.title': 'Recurso não encontrado',
+    '404.description': 'Este recurso não existe mais.',
+    '404.help': 'Tente novamente ou fale com o administrador da sua organização.',
+    '500.title': 'Erro ao exibir o recurso',
+    '500.description': 'Mas não se preocupe, já estamos investigando o que aconteceu.',
+    '500.help': 'Tente novamente após alguns minutos.',
+    showDetails: 'Ver Detalhes',
+    hideDetails: 'Esconder Detalhes',
+  },
+} satisfies Dictionary