@stack-spot/portal-components

Components

A collection of UI components, hooks, SVG images, utilities and variables shared among Stackspot web 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.

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. Must be imported from @stack-spot/portal-components/Breadcrumb.
• 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.
• 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).

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.