@stack-spot/portal-layout 0.0.65 → 1.0.0

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,106 @@ 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,
 }
 
 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 {
+  /**
+   * The icon for this section.
+   */
   icon: ReactElement,
   /**
    * The content or a function that creates the content.
@@ -74,32 +133,65 @@ 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,
 }
 
 interface BaseMenuProps {
+  /**
+   * The sections of the menu.
+   */
   sections?: MenuSection[],
+  /**
+   * 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,
   },
 }
 
 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.
    */

package/src/components/tour/PortalSwitcherStep.tsx

@@ -1,6 +1,12 @@
 import { Box, Image, Text } from '@citric/core'
-import { TourStep, tourStepBuilder } from '@stack-spot/portal-components'
+import { TourStep, tourStepBuilder } from '@stack-spot/portal-components/Tour'
 import { useTranslate } from '@stack-spot/portal-translate'
+
+/**
+ * Tutorial: a React hook for retrieving the React Tour step that explains how the portal switcher works. The portal switcher is a component
+ * at the top left corner of the layout (header) that allows the user to switch between the different Stackspot portals.
+ * @returns the React Tour step for the PortalSwitcher.
+ */
 export const usePortalSwitcherStep = (): TourStep => {
   const t = useTranslate(translations)
   return tourStepBuilder({
@@ -19,9 +25,6 @@ export const usePortalSwitcherStep = (): TourStep => {
   })
 }
 
-
-
-
 const translations = {
   en: {
     title: 'Expand Your Horizons with Stackspot',

package/src/components/types.ts

@@ -1,15 +1 @@
-import React, { ReactNode } from 'react'
-
-interface CustomLabel {
-  id: string,
-  element: ReactNode,
-}
-export interface Action {
-  label: string | CustomLabel,
-  onClick?: () => void,
-  href?: string,
-  target?: React.AnchorHTMLAttributes<HTMLAnchorElement>['target'],
-  iconActive?: React.ReactElement,
-}
-
 export type PortalAcronym = 'EDP' | 'AI' | 'HUB'

package/src/dictionary.ts

@@ -17,6 +17,9 @@ const dictionary = {
   },
 } satisfies Dictionary
 
+/**
+ * A global dictionary for layout components.
+ */
 export const useDictionary = () => useTranslate(dictionary)
 
 export function getDictionary() {

package/src/elements.ts

@@ -1,3 +1,6 @@
+/**
+ * The ids of the layout elements.
+ */
 export const elementIds = {
   layout: 'layout',
   backdrop: 'backdrop',
@@ -16,6 +19,9 @@ export const elementIds = {
 export type LayoutElement = keyof typeof elementIds
 export type LayoutElements = Record<LayoutElement, HTMLElement | null>
 
+/**
+ * @returns an object with the html elements of the layout.
+ */
 export function getLayoutElements() {
   return (Object.keys(elementIds) as LayoutElement[]).reduce<LayoutElements>(
     (result, id) => ({ ...result, [id]: document.getElementById(id) }),

package/src/index.ts

@@ -4,14 +4,11 @@ export { Dialog } from './components/Dialog'
 export { Header, HeaderProps } from './components/Header'
 export { OverlayContent } from './components/OverlayContent'
 export { PortalSwitcher } from './components/PortalSwitcher'
-export { ListAction, SelectionList, SelectionListProps } from './components/SelectionList'
-export { Toaster } from './components/Toaster'
 export { ActionItem, MenuContent, MenuGroup, Title } from './components/menu/MenuContent'
 export { MenuSections } from './components/menu/MenuSections'
 export * from './components/menu/types'
 export * from './components/types'
 export * from './elements'
 export * from './errors'
-export { Logo as StackspotLogo } from './svg/Logo'
 export * from './utils'
 

package/src/layout.css

@@ -245,6 +245,7 @@ body {
   pointer-events: none;
   z-index: 1;
   transition: opacity 0.3s;
+  overflow-y: auto;
 }
 
 #menuContentOverlay.visible {
@@ -252,11 +253,6 @@ body {
   pointer-events: auto;
 }
 
-#menuContentOverlay > div {
-  flex: 1;
-  overflow: auto;
-}
-
 #menuContent {
   width: var(--menu-content-width);
   transition: left ease-out var(--menu-animation-duration);

package/src/toaster.tsx

@@ -1,30 +1,94 @@
-import { IconBox, OneOfColorSchemesWithVariants } from '@citric/core'
+import { Flex, IconBox, OneOfColorSchemesWithVariants, Text } from '@citric/core'
 import { CheckCircleFill, ExclamationCircleFill, ExclamationTriangleFill, InfoCircleFill } from '@citric/icons'
+import React from 'react'
 import { toast } from 'react-toastify'
 import 'react-toastify/dist/ReactToastify.css'
 
 type ToastType = 'error' | 'success' | 'warning' | 'info'
 
-interface BaseProps {
+interface BaseOptions {
+  /**
+   * An identifier for the toaster, if not provided, `Math.random()` will be used.
+   * 
+   * The id can be used to programmatically control the toaster.
+   */
+  id?: number | string,
+  /**
+   * The message to show.
+   * Can be either a string or a React element.
+   */
+  message: React.ReactNode,
+  /**
+   * Level/severity of this message.
+   * @default 'info'
+   */
   type?: ToastType,
   /**
    * Seconds until auto-close or false to not auto-close.
-   * @default 3 for success toast and 10 for the others
+   * @default 3s for success toast and 10s for the others
    */
   autoClose?: number | false,
+  /**
+   * If true, `message` must be a React Element and none of the default toaster UI is rendered (title, icon and close button).
+   * @default false
+   */
+  custom?: boolean,
+  /**
+   * Whether or not to close the toaster when the user clicks it.
+   * @default false
+   */
+  closeOnClick?: boolean,
 }
 
-interface BasicMessageProps extends BaseProps {
-  message: string,
+interface ToasterAction {
+  /**
+   * The button's label.
+   */
+  label: string,
+  /**
+   * A function to run once the button is clicked.
+   */
+  onClick?: (event: React.MouseEvent) => void,
+  /**
+   * If this is set, instead of a button, an anchor is rendered with this href.
+   */
+  href?: string,
+  /**
+   * Whether or not to close the toaster once the button is clicked.
+   * @default true
+   */
+  closeOnClick?: boolean,
+}
+
+export interface DefaultToasterOptions extends BaseOptions {
+  /**
+   * The title of the toaster.
+   */
   title?: string,
+  /**
+   * A function to call when the user clicks the toaster. By default, it closes the toaster.
+   */
   onClick?: () => void,
+  /**
+   * A set of buttons (or links/anchors) to show after the message.
+   */
+  actions?: ToasterAction[],
+  custom?: false,
 }
 
-interface RichMessageProps extends BaseProps {
-  content: React.ReactElement,
+export interface CustomToasterOptions extends BaseOptions {
+  /**
+   * The whole content to render inside the toaster.
+   */
+  message: React.ReactElement,
+  custom: true,
+  /**
+   * A close button to render on the top right corner of the toaster. If not provided, a close button won't be rendered.
+   */
+  closeButton?: React.ReactElement,
 }
 
-type Props = BasicMessageProps | RichMessageProps
+export type ToasterOptions = DefaultToasterOptions | CustomToasterOptions | React.ReactNode
 
 const toasterConfig: Record<ToastType, { element: React.ReactElement, color: string, duration: number }> = {
   error: {
@@ -49,28 +113,75 @@ const toasterConfig: Record<ToastType, { element: React.ReactElement, color: str
   },
 }
 
-export function showToaster({ type = 'info', autoClose, ...props }: Props) {
+export function showToaster(defaultToasterConfig: DefaultToasterOptions): number | string
+export function showToaster(customToasterConfig: CustomToasterOptions): number | string
+export function showToaster(message: React.ReactNode): number | string
+export function showToaster(options: ToasterOptions): number | string {
+  const isToasterConfig = options && typeof options === 'object' && 'message' in options
+  const { type = 'info', autoClose, ...opts }: DefaultToasterOptions | CustomToasterOptions = isToasterConfig
+    ? options
+    : { message: options }
   const config = toasterConfig[type]
+  const id = opts.id ?? Math.random()
   const closeTime = autoClose ? autoClose : config.duration
   const bg = `var(--${config.color}-500)`
   const bgDark = `var(--${config.color}-600)`
   const fg = `var(--${config.color}-contrastText)`
+  const actionStyle: React.CSSProperties = {
+    background: 'transparent',
+    border: 'none',
+    padding: 0,
+    color: 'inherit',
+    font: 'inherit',
+    fontWeight: 500,
+    cursor: 'pointer',
+  }
+  const buttons = opts.custom ? null : opts.actions?.map(
+    ({ label, href, onClick, closeOnClick = true }) => (
+      <Text
+        key={label}
+        as={href ? 'a' : 'button'}
+        href={href}
+        style={actionStyle}
+        onClick={(event: React.MouseEvent) => {
+          onClick?.(event)
+          if (closeOnClick) closeReactToaster(id)
+        }}
+      >
+        {label}
+      </Text>
+    ),
+  )
   toast(
-    'message' in props
-      ? <div onClick={props.onClick}><h1 style={{ textTransform: 'capitalize' }}>{props.title ?? type}</h1><p>{props.message}</p></div>
-      : props.content,
+    opts.custom
+      ? opts.message
+      : (
+        <div onClick={opts.onClick}>
+          <h1 style={{ textTransform: 'capitalize' }}>{opts.title ?? type}</h1>
+          {typeof opts.message === 'string' ? <p>{opts.message}</p> : opts.message}
+          {buttons?.length ? <Flex style={{ gap: '12px', marginTop: '12px' }}>{buttons}</Flex> : null}
+        </div>
+      ),
     {
+      toastId: id,
       type,
       autoClose: autoClose === false ? false : closeTime * 1000,
       className: 'main-toaster',
       style: { backgroundColor: bg, color: fg },
       progressStyle: { background: bgDark },
       bodyClassName: 'toast-body',
-      icon: 'message' in props ? () => (
+      icon: opts.custom ? false : () => (
         <IconBox colorIcon={`${config.color}.contrastText` as OneOfColorSchemesWithVariants} size="xs">
           {config.element}
         </IconBox>
-      ) : undefined,
+      ),
+      closeOnClick: opts.closeOnClick ?? false,
+      closeButton: opts.custom ? (opts.closeButton ?? false) : undefined,
     },
   )
+  return id
+}
+
+export function closeReactToaster(id: number | string) {
+  toast.dismiss(id)
 }

package/src/utils.ts

@@ -1,152 +1,19 @@
 import { valueOf } from '@stack-spot/portal-theme'
 import { getLayoutElements } from './elements'
 
-export function valueOfLayoutVar(varname: string): string {
-  const layout = document.getElementById('layout')
-  if (!layout) return ''
-  return valueOf(varname, layout)
-}
-
 /**
- * Important for accessibility.
- * 
- * Makes it so we focus the next focusable element in the DOM hierarchy, disregarding the element passed as parameter and its children.
+ * Gets the value for a css variable of the layout.
  * 
- * If there's no next focusable element, the first focusable of the page will be focused. If the page doesn't contain any focusable
- * element, nothing happens.
- * 
- * @param current the reference element to focus the next. If not provided, will be the currently active element.
- */
-export function focusNextIgnoringChildren(current?: HTMLElement | null) {
-  current = current ?? document.activeElement as HTMLElement
-  while (current && !current.nextElementSibling) {
-    current = current?.parentElement
-  }
-  current = current?.nextElementSibling as HTMLElement
-  while (current && current.tabIndex < 0) {
-    current = (current.children.length ? current.firstChild : current.nextElementSibling) as HTMLElement
-  }
-  if (current) current?.focus?.()
-  else focusFirstChild(document)
-}
-
-type TagPriority = 'a' | 'button' | 'input' | 'textarea' | 'select' | 'other'
-type TagPriorityElement = TagPriority | TagPriority[]
-
-interface FocusOptions {
-  /**
-   * Instead of focusing the first element overall, focus the first according to this list of priorities.
-   */
-  priority?: TagPriorityElement[],
-  /**
-   * Ignores any element that matches this query selector.
-   */
-  ignore?: string,
-}
-
-const selectors: Record<TagPriority, string> = {
-  a: 'a[href]:not(:disabled)',
-  button: 'button:not(:disabled)',
-  input: 'input:not(:disabled):not([type="hidden"])',
-  select: 'textarea:not(:disabled)',
-  textarea: 'select:not(:disabled)',
-  other: '[tabindex]:not([tabindex="-1"])',
-}
-
-/**
- * Checks if an element can receive focus.
+ * Supposing the actual name of the variable is name-of-variable, the value passed to the first parameter (varname) may be: name-of-variable
+ * or --name-of-variable or var(--name-of-variable). All these formats work.
  * 
- * Elements can receive focus only if:
- * - they exist;
- * - they're visible;
- * - they're not disabled;
- * - they are a focusable tag name or have a positive tab index;
- * - they don't have a negative tab index.
- * @param element the element to check.
- * @returns true if the element is focusable, false otherwise.
+ * @param varname the name of css variable.
+ * @returns the value of `varname`.
  */
-export function isFocusable(element?: Element | null) {
-  if (!element) return false
-  // is disabled: return false
-  if (element.ariaDisabled || element.getAttribute('disabled') !== null) return false
-  // is invisible: return false
-  if (!element.checkVisibility({ checkOpacity: true, checkVisibilityCSS: true })) return false
-  // has tab index: return false if negative, true otherwise
-  const tabIndexStr = element.getAttribute('tabindex')
-  const tabIndex = tabIndexStr ? parseInt(tabIndexStr) : undefined
-  if (tabIndex !== undefined) return tabIndex >= 0
-  // check the tag name
-  return ['a', 'button', 'input', 'iframe', 'select', 'textarea'].includes(element.tagName.toLowerCase() ?? '')
-}
-
-/**
- * Focus the element passed as parameter if it can receive focus. Otherwise, decides on another element to focus based on the HTML tree
- * and accessibility attributes.
- * 
- * Decision making:
- * - If the element is focusable, focus it.
- * - If the element is not focusable, check if it has an id and if another element controls it (aria-controls).
- * - If the element is controlled by another, try to focus the controller, based in this same algorithm.
- * - Otherwise, try to focus its parent.
- * 
- * If no focusable element is found. Nothing happens.
- * @param element the element to focus.
- */
-export function focusAccessibleElement(element?: Element | null) {
-  let elementToFocus = element as HTMLElement | null | undefined
-  while (elementToFocus && !isFocusable(elementToFocus)) {
-    const controlledBy = elementToFocus.id ? document.querySelector(`[aria-controls=${elementToFocus.id}]`) : undefined
-    elementToFocus = (controlledBy ?? elementToFocus.parentElement) as HTMLElement | null | undefined
-  }
-  elementToFocus?.focus?.()
-}
-
-/**
- * Focus the first focusable child of the element provided. If the element has no focusable child, nothing happens.
- * 
- * A priority list can be passed in the second parameter, as an option. If it's provided, it will focus the first element according to the
- * list.
- * 
- * An ignore query selector can also be passed in the options parameter. If the first focusable element matches the query selector, the
- * next element is focused instead.
- * 
- * @example
- * Suppose the children of element are: h1, button, p, input, select.
- * 1. We don't pass a priority list. The focused element will be the button.
- * 2. Our priority list is ['button']. The focused element will be the button.
- * 3. Our priority list is ['input', 'button']. The focused element will be the input.
- * 4. Our priority list is ['select', 'input']. The focused element will be the select.
- * 5. Our priority list is [['select', 'input'], 'button']. The focused element will be the input.
- * 
- * @param element the element to search a child to focus.
- * @param options optional.
- */
-export function focusFirstChild(element: HTMLElement | Document | null | undefined, { priority = [], ignore }: FocusOptions = {}) {
-  let focusable: NodeListOf<HTMLElement> | null | undefined
-  let missing: TagPriority[] = ['a', 'button', 'input', 'other', 'select', 'textarea']
-  for (const p of priority) {
-    const tags = Array.isArray(p) ? p : [p]
-    const querySelectors = tags.map(t => {
-      missing = missing.filter(tag => tag != t)
-      return selectors[t]
-    })
-    focusable = element?.querySelectorAll(querySelectors.join(', '))
-    if (focusable) break
-  }
-  if (!focusable) {
-    element?.querySelectorAll(missing.map(t => selectors[t]).join(', '))
-  }
-  let elementToFocus: HTMLElement | undefined
-  for (const f of focusable ?? []) {
-    if (!ignore || !f.matches(ignore)) {
-      const styles = window.getComputedStyle(f)
-      if (styles.display != 'none' && styles.visibility != 'hidden') {
-        elementToFocus = f
-        break
-      }
-    }
-  }
-  elementToFocus?.focus?.()
+export function valueOfLayoutVar(varname: string): string {
+  const layout = document.getElementById('layout')
+  if (!layout) return ''
+  return valueOf(varname, layout)
 }
 
 /**

package/dist/components/BottomNotification.d.ts

@@ -1 +0,0 @@
-//# sourceMappingURL=BottomNotification.d.ts.map

package/dist/components/BottomNotification.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"BottomNotification.d.ts","sourceRoot":"","sources":["../../src/components/BottomNotification.tsx"],"names":[],"mappings":""}

package/dist/components/BottomNotification.js

@@ -1,2 +0,0 @@
-"use strict";
-//# sourceMappingURL=BottomNotification.js.map

package/dist/components/BottomNotification.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"BottomNotification.js","sourceRoot":"","sources":["../../src/components/BottomNotification.tsx"],"names":[],"mappings":""}

package/dist/components/BottomPanel.d.ts

@@ -1 +0,0 @@
-//# sourceMappingURL=BottomPanel.d.ts.map

package/dist/components/BottomPanel.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"BottomPanel.d.ts","sourceRoot":"","sources":["../../src/components/BottomPanel.tsx"],"names":[],"mappings":""}

package/dist/components/BottomPanel.js

@@ -1,2 +0,0 @@
-"use strict";
-//# sourceMappingURL=BottomPanel.js.map

package/dist/components/BottomPanel.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"BottomPanel.js","sourceRoot":"","sources":["../../src/components/BottomPanel.tsx"],"names":[],"mappings":""}