@stack-spot/citric-react 0.1.0

package/src/components/Overlay/types.ts

@@ -0,0 +1,71 @@
+import { OverlayOptions } from '../../overlay'
+import { HTMLExtension } from '../../types'
+
+export type TriggerOn = 'hover' | 'click'
+
+export interface BaseOverlayProps<T extends keyof React.JSX.IntrinsicElements> extends Omit<OverlayOptions<T>, 'target'> {
+  /**
+   * When should the overlay element be created? When the child is clicked or when the child is hovered?
+   * 
+   * Accessibility:
+   * Click = focus + press enter to open; focus + enter to close OR esc.
+   * Hover = focus to open; blur to close.
+   * 
+   * @default 'hover'
+   */
+  triggerOn?: TriggerOn,
+  /**
+   * TODO: not implemented yet.
+   * 
+   * Only valid if `triggerOn` is "hover".
+   * 
+   * If the overlay is hidden right after the mouse leaves the element, then it becomes impossible to interact with anything inside the
+   * tooltip. This sets a delay for the overlay to disappear, giving it time for the user to hover the overlay or gocus one of its children,
+   * which will prevent it from closing.
+   * 
+   * When `hoverDelayMS` is greater then zero, the hover effect is also applied to the overlay itself instead of just the child element.
+   * 
+   * When set to "auto", a hover delay of 1 second will be used if the overlay contains any focusable element.
+   * 
+   * @default 'auto'
+   */
+  hoverDelayMS?: number | 'auto',
+  /**
+   * TODO: not implemented yet.
+   * 
+   * - Never: the focus won't changes when the overlay opens.
+   * - All: the focus always changes when the overlay opens (given there's a focusable element in the overlay).
+   * - Keyboard (default): the focus only changes when the overlay is opened via the keyboard.
+   * 
+   * The first focusable element in the overlay will be focused as soon as it's rendered. When it's closed, the child element
+   * (`children`) regains focus.
+   * 
+   * The focus control will be such that, after the last element in the overlay is focused, the next focus will move to the child element
+   * (`children`).
+   * 
+   * If the overlay has no focusable element, this properties makes no difference.
+   * 
+   * Attention: focusable elements inside the overlay can be ignored by setting `auto-focus` to false.
+   * 
+   * @default 'keyboard'
+   */
+  autoFocusBehavior?: 'never' | 'always' | 'keyboard',
+  /**
+   * The element to receive the overlay.
+   */
+  children: React.ReactElement,
+  /**
+   * Function to run when the child is rendered. It receives the child element as a parameter.
+   * 
+   * This is useful for easily adding attributes to the element (mainly accessibility ones).
+   * @param element the child element, the one that receives the overlay.
+   */
+  onRenderChild?: (element: HTMLElement) => void,
+}
+
+export type OverlayProps<T extends keyof React.JSX.IntrinsicElements> =
+  HTMLExtension<'div', BaseOverlayProps<T>, 'children' | 'content'>
+
+export interface OverlayController {
+  close: () => Promise<void>,
+}

package/src/components/Pagination.tsx

@@ -0,0 +1,90 @@
+import { Dictionary, interpolate, useTranslate } from '@stack-spot/portal-translate'
+import { useMemo } from 'react'
+import { HTMLExtension } from '../types'
+import { CitricComponent } from './CitricComponent'
+import { IconButton } from './IconBox'
+
+export interface BasePaginationProps {
+  /**
+   * The options for the page size.
+   * 
+   * @default [10, 20, 30]
+   */
+  pageSizeOptions?: number[],
+  /**
+   * Total number of pages
+   */
+  totalPages: number,
+  /**
+   * The first page is 1. If "0" is provided, it will be treated as if it was "1".
+   */
+  page: number,
+  /**
+   * The current number of items in a page.
+   */
+  pageSize: number,
+  /**
+   * Function to run whenever the page size or current page changes.
+   */
+  onChange: (page: number, size: number) => void,
+}
+
+export type PaginationProps = HTMLExtension<'div', BasePaginationProps, 'children' | 'onChange'>
+
+export const Pagination = (
+  { pageSizeOptions = [10, 20, 30], pageSize, totalPages, page, onChange, ...props }: PaginationProps,
+) => {
+  const t = useTranslate(dictionary)
+  const sizeOptions = useMemo(() => pageSizeOptions.map(o => <option key={o} selected={pageSize === o}>{o}</option>), [pageSizeOptions])
+  const pageOptions = useMemo(() => {
+    const options: React.ReactElement[] = []
+    for (let i = 1; i <= totalPages; i++) {
+      options.push(<option key={i} value={i} selected={page === i}>{i}</option>)
+    }
+    return options
+  }, [page, totalPages])
+
+  return (
+    <CitricComponent tag="div" component="pagination" {...props}>
+      <div className="page-size">
+        <label>
+          {t.itemsPerPage}:
+          <select name="itemsPerPage" onChange={e => onChange(page, parseInt(e.target.value))}>{sizeOptions}</select>
+        </label>
+      </div>
+      <div className="page-number">
+        <label>
+          <select name="page" onChange={e => onChange(parseInt(e.target.value), pageSize)}>{pageOptions}</select>
+        </label>
+        {totalPages > 1 ? interpolate(t.ofTotalPlural, totalPages) : t.ofTotalSingular}
+        <IconButton
+          icon="ChevronLeft"
+          aria-label="previous"
+          title="previous"
+          disabled={page === 1}
+          onClick={() => onChange(page - 1, pageSize)}
+        />
+        <IconButton
+          icon="ChevronRight"
+          aria-label="next"
+          title="next"
+          disabled={page === totalPages}
+          onClick={() => onChange(page + 1, pageSize)}
+        />
+      </div>
+    </CitricComponent>
+  )
+}
+
+const dictionary = {
+  en: {
+    itemsPerPage: 'Items per page',
+    ofTotalSingular: 'of 1 page',
+    ofTotalPlural: 'of $0 pages',
+  },
+  pt: {
+    itemsPerPage: 'Itens por página',
+    ofTotalSingular: 'de 1 página',
+    ofTotalPlural: 'de $0 páginas',
+  },
+} satisfies Dictionary

package/src/components/ProgressBar.tsx

@@ -0,0 +1,25 @@
+import { listToClass } from '@stack-spot/portal-theme'
+import { isNil } from 'lodash'
+import { HTMLExtension, WithColorPalette, WithColorScheme } from '../types'
+import { applyCSSVariable } from '../utils/css'
+import { CitricComponent } from './CitricComponent'
+
+export interface BaseProgressBarProps extends WithColorScheme, WithColorPalette {
+  /**
+   * A number varying from 0 to 100.
+   * 
+   * If not provided, the progress will be indeterminate, causing an animation loop.
+   */
+  progress?: number,
+}
+
+export type ProgressBarProps = HTMLExtension<'div', BaseProgressBarProps>
+
+export const ProgressBar = ({ progress, style, className, ...props }: ProgressBarProps) =>
+  <CitricComponent
+    tag="div"
+    component="progress-bar"
+    className={listToClass([className, isNil(progress) && 'indeterminate'])}
+    style={progress === undefined ? style : applyCSSVariable(style, 'progress', progress)}
+    {...props}
+  />

package/src/components/ProgressCircular.tsx

@@ -0,0 +1,29 @@
+import { listToClass } from '@stack-spot/portal-theme'
+import { isNil } from 'lodash'
+import { HTMLExtension, WithColorPalette, WithColorScheme } from '../types'
+import { applyCSSVariable } from '../utils/css'
+import { CitricComponent } from './CitricComponent'
+
+export interface BaseProgressCircularProps extends WithColorScheme, WithColorPalette {
+  /**
+   * A number varying from 0 to 100.
+   * 
+   * If not provided, the progress will be indeterminate, causing an animation loop.
+   */
+  progress?: number,
+  /**
+   * @default 'md'
+   */
+  size?: 'xs' | 'sm' | 'md' | 'lg',
+}
+
+export type ProgressCircularProps = HTMLExtension<'div', BaseProgressCircularProps>
+
+export const ProgressCircular = ({ progress, size, style, className, ...props }: ProgressCircularProps) =>
+  <CitricComponent
+    tag="div"
+    component="progress-circular"
+    className={listToClass([size, className, isNil(progress) && 'indeterminate'])}
+    style={progress === undefined ? style : applyCSSVariable(style, 'progress', progress)}
+    {...props}
+  />

package/src/components/RadioGroup.tsx

@@ -0,0 +1,87 @@
+import { isNil } from 'lodash'
+import { useMemo } from 'react'
+import { HTMLExtension, WithColorScheme } from '../types'
+import { defaultRenderKey, defaultRenderLabel } from '../utils/options'
+import { CitricComponent } from './CitricComponent'
+import { Column } from './layout'
+
+export interface BaseRadioGroupProps<T> extends WithColorScheme {
+  /**
+   * The field name.
+   */
+  name?: string,
+  /**
+   * The current value.
+   */
+  value?: T,
+  /**
+   * All the items (radio buttons) to render.
+   */
+  options: T[],
+  /**
+   * Called whenever the selected radio button changes.
+   * @param value the currently selected item.
+   */
+  onChange?: (value: T) => void,
+  /**
+   * A function to render the item label.
+   * @example
+   * `(option) => option.name`
+   * @default "the item's toString() result."
+   * @param option the item to render.
+   * @returns a React Node to render.
+   */
+  renderLabel?: (option: T) => React.ReactNode,
+  /**
+   * A function to render the item value, a unique identifier for the option.
+   * @example
+   * `(option) => option.id`
+   * @default "if the item is a string or a number, the stringified item. Otherwise, undefined."
+   * @param option the item to compute a key for.
+   * @returns a string key.
+   */
+  renderKey?: (option: T) => string | number | undefined,
+  /**
+   * If this function returns true for the item, this option is disabled.
+   * @default "nothing is disabled"
+   * @param option the item to calculate "disabled" for.
+   * @returns true if the item should be disabled, false otherwise.
+   */
+  isDisabled?: (option: T) => boolean,
+}
+
+export type RadioGroupProps<T> = HTMLExtension<'div', BaseRadioGroupProps<T>, 'onChange'>
+
+export function RadioGroup<T>({
+  name,
+  value,
+  options,
+  onChange,
+  renderLabel = defaultRenderLabel,
+  renderKey = defaultRenderKey,
+  isDisabled,
+  colorScheme,
+  style,
+  ...props
+}: RadioGroupProps<T>) {
+  const items = useMemo(() => {
+    const valueKey = value ? renderKey(value) : undefined
+    return options.map((o) => {
+      const key = renderKey(o)
+      return (
+        <CitricComponent tag="label" component="radio-row" key={key} colorScheme={colorScheme}>
+          <input
+            type="radio"
+            name={name}
+            value={key}
+            checked={value === o || (!isNil(key) && valueKey === key)}
+            onChange={() => onChange?.(o)}
+            disabled={isDisabled?.(o)}
+          />
+          {renderLabel(o)}
+        </CitricComponent>
+      )
+    })
+  }, [options, value, name, colorScheme])
+  return <Column {...props} style={{ gap: '8px', ...style }}>{items}</Column>
+}

package/src/components/Rating.tsx

@@ -0,0 +1,25 @@
+import { HTMLExtension } from '../types'
+import { CitricComponent } from './CitricComponent'
+
+export type RatingValue = 1 | 2 | 3 | 4 | 5
+
+export interface BaseRatingProps {
+  value: RatingValue | undefined,
+  onChange: (value: RatingValue) => void,
+  /**
+   * The name of this input.
+   */
+  name?: string,
+}
+
+export type RatingProps = HTMLExtension<'div', BaseRatingProps, 'children' | 'onChange'>
+
+export const Rating = ({ value, onChange, name, ...props }: RatingProps) => (
+  <CitricComponent tag="div" component="rating" {...props}>
+    <input type="radio" value="1" name={name} checked={value === 5} onChange={() => onChange(5)} />
+    <input type="radio" value="2" name={name} checked={value === 4} onChange={() => onChange(4)} />
+    <input type="radio" value="3" name={name} checked={value === 3} onChange={() => onChange(3)} />
+    <input type="radio" value="4" name={name} checked={value === 2} onChange={() => onChange(2)} />
+    <input type="radio" value="5" name={name} checked={value === 1} onChange={() => onChange(1)} />
+  </CitricComponent>
+)

package/src/components/Select/RichSelect.tsx

@@ -0,0 +1,214 @@
+import { listToClass } from '@stack-spot/portal-theme'
+import { useTranslate } from '@stack-spot/portal-translate'
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
+import { applyCSSVariable } from '../../utils/css'
+import { defaultRenderKey, defaultRenderLabel } from '../../utils/options'
+import { CitricComponent } from '../CitricComponent'
+import { Input } from '../Input'
+import { ProgressCircular } from '../ProgressCircular'
+import { SimpleSelect } from './SimpleSelect'
+import { SelectProps } from './types'
+
+export function RichSelect<T>({
+  options,
+  value,
+  onChange,
+  renderLabel = defaultRenderLabel,
+  renderKey = defaultRenderKey,
+  required = true,
+  disabled,
+  loading,
+  renderOption,
+  renderHeader,
+  searchable,
+  maxHeight,
+  style,
+  className,
+  onFocus,
+  onBlur,
+  showArrow,
+  ...props
+}: SelectProps<T> & { type?: 'rich' }) {
+  const [search, setSearch] = useState('')
+  const element = useRef<HTMLDivElement | null>(null)
+  const [open, setOpen] = useState(false)
+  const [focused, setFocused] = useState(false)
+  const t = useTranslate(dictionary)
+
+  const change = useCallback((option: T | undefined) => () => {
+    onChange?.(option)
+    setOpen(false)
+  }, [])
+
+  const renderedOptions = useMemo(() => {
+    const items = required ? [] : [<li key="" className="empty" onClick={change(undefined)}>{t.empty}</li>]
+    options.forEach((o) => {
+      const key = renderKey(o)
+      const label = renderLabel(o)
+      if (!search.trim() || label.toLocaleLowerCase().includes(search.trim().toLocaleLowerCase())) {
+        items.push(
+          <li key={key} onClick={change(o)}>
+            {renderOption?.(o) ?? label}
+          </li>,
+        )
+      }
+    })
+    return items
+  }, [options, value, required, search])
+
+  /* this runs whenever the selection panel is opened */
+  useEffect(() => {
+    if (open) {
+      setSearch('')
+      const selectionPanel = element.current?.querySelector('.selection-panel') as HTMLElement | undefined
+      selectionPanel?.querySelector('ul')?.scrollTo({ top: 0 })
+      const getCurrent = () => selectionPanel?.querySelector('li.focused') as HTMLElement | undefined
+      const scrollTo = (li: HTMLElement) => {
+        const ul = li.closest('ul')
+        if (!ul) return
+        const { top: ulTop, height: ulHeight } = ul.getBoundingClientRect()
+        const { height: liHeight, top: liTop } = li.getBoundingClientRect()
+        const offset = liTop + ul.scrollTop - ulTop
+        if ((ul.scrollTop + ulHeight < offset + liHeight) || ul.scrollTop > offset) {
+          ul.scrollTo({ top: offset })
+        }
+      }
+      /* keyboard and mouse controls */
+      const listenToMouse = (event: Event) => {
+        if (!selectionPanel?.contains(event.target as HTMLElement)) {
+          setOpen(false)
+        }
+      }
+      const listenToKeyboard = (event: KeyboardEvent) => {
+        const isCharacter = event.key.length === 1
+        if (['Escape', 'ArrowUp', 'ArrowDown', 'Enter'].includes(event.key) || (searchable && (isCharacter || event.key === 'Backspace'))) {
+          event.preventDefault()
+          event.stopPropagation()
+        }
+        if (event.key === 'Escape') setOpen(false)
+        if (searchable) {
+          if (isCharacter) setSearch(v => `${v}${event.key}`)
+          if (event.key === 'Backspace') setSearch(v => v.substring(0, v.length - 1))
+        }
+        if (event.key === 'ArrowDown') {
+          const current = getCurrent()
+          const next = (current?.nextElementSibling ?? selectionPanel?.querySelector('li')) as HTMLAreaElement | undefined
+          if (next) {
+            current?.classList.remove('focused')
+            next.classList.add('focused')
+            scrollTo(next)
+          }
+        }
+        if (event.key === 'ArrowUp') {
+          const current = getCurrent()
+          const prev = (current?.previousElementSibling ?? selectionPanel?.querySelector('li:last-child')) as HTMLAreaElement | undefined
+          if (prev) {
+            current?.classList.remove('focused')
+            prev.classList.add('focused')
+            scrollTo(prev)
+          }
+        }
+        if (event.key === 'Enter') {
+          setTimeout(() => getCurrent()?.click(), 0)
+        }
+      }
+    
+      document.addEventListener('click', listenToMouse)
+      document.addEventListener('keydown', listenToKeyboard)
+      return () => {
+        document.removeEventListener('click', listenToMouse)
+        document.removeEventListener('keydown', listenToKeyboard)
+        getCurrent()?.classList.remove('focused')
+      }
+    }
+  }, [open])
+
+  /* this runs whenever the select is focused */
+  useEffect(() => {
+    if (focused) {
+      const listenToMouse = (event: MouseEvent) => {
+        if (!element.current?.contains(event.target as HTMLElement)) {
+          setFocused(false)
+        }
+      }
+      const listenToKeyboard = (event: KeyboardEvent) => {
+        if (['Enter', 'ArrowDown', 'ArrowUp'].includes(event.key)) {
+          event.preventDefault()
+          if (!element.current?.classList.contains('open')) setOpen(true)
+        }
+        if (event.key === 'Tab') {
+          setFocused(false)
+          if (element.current?.classList.contains('open')) setOpen(false)
+        }
+      }
+      document.addEventListener('click', listenToMouse)
+      document.addEventListener('keydown', listenToKeyboard)
+      return () => {
+        document.removeEventListener('click', listenToMouse)
+        document.removeEventListener('keydown', listenToKeyboard)
+      }
+    }
+  }, [focused])
+
+  useEffect(() => {
+    if (disabled) {
+      setOpen(false)
+      setFocused(false)
+    }
+  }, [disabled])
+
+  return (
+    <CitricComponent
+      tag="div"
+      component="rich-select"
+      style={maxHeight ? applyCSSVariable(style, 'max-height', `${maxHeight}px`) : style}
+      className={listToClass([className, showArrow === false && 'hide-arrow', open && 'open', focused && 'focused'])}
+      ref={element}
+      aria-busy={loading}
+      {...props}
+    >
+      <SimpleSelect
+        options={options}
+        value={value}
+        renderLabel={renderLabel}
+        renderKey={renderKey}
+        required={required}
+        disabled={disabled}
+        onChange={onChange}
+        onFocus={onFocus}
+        onBlur={onBlur}
+        wrap={false}
+      />
+      <header
+        onClick={(e) => {
+          if (disabled) return
+          if (!open) e.stopPropagation()
+          setFocused(true)
+          setOpen(true)
+        }}
+        aria-hidden
+      >
+        {renderHeader?.(value) ?? (value ? (renderOption?.(value) ?? renderLabel(value)) : <span></span>)}
+        {loading && <ProgressCircular size="xs" className="loader" />}
+      </header>
+      <div className="selection-panel" aria-hidden>
+        {searchable && <div className="search-bar">
+          <div data-citric="field-group" className="auto">
+            <i data-citric="icon-box" className="citric-icon outline Search"></i>
+            <Input type="search" value={search} onChange={setSearch} tabIndex={-1} />
+          </div>
+        </div>}
+        <ul>{renderedOptions}</ul>
+      </div>
+    </CitricComponent>
+  )
+}
+
+const dictionary = {
+  en: {
+    empty: 'Empty',
+  },
+  pt: {
+    empty: 'Vazio',
+  },
+}

package/src/components/Select/SimpleSelect.tsx

@@ -0,0 +1,66 @@
+import { isNil } from 'lodash'
+import { useCallback, useMemo } from 'react'
+import { defaultRenderKey, defaultRenderLabel } from '../../utils/options'
+import { CitricComponent } from '../CitricComponent'
+import { ProgressCircular } from '../ProgressCircular'
+import { SelectProps } from './types'
+
+export function SimpleSelect<T>({
+  options,
+  value,
+  onChange,
+  renderLabel = defaultRenderLabel,
+  renderKey = defaultRenderKey,
+  required = true,
+  loading,
+  disabled,
+  onBlur,
+  onFocus,
+  wrap,
+  ...props
+}: SelectProps<T> & { wrap?: boolean }) {
+  const handleChange = useCallback((e: React.ChangeEvent<HTMLSelectElement>) => {
+    const selectedIndex = e.target.options.selectedIndex + (required ? 0 : 1)
+    onChange?.(options[selectedIndex])
+  }, [options])
+
+  const renderedOptions = useMemo(() => {
+    const valueKey = value ? renderKey(value) : undefined
+    const items = (!value || !required) ? [<option key=""></option>] : []
+    options.forEach((o) => {
+      const key = renderKey(o)
+      items.push(
+        <option key={key} value={key} selected={o === value || (!isNil(key) && key === valueKey)}>
+          {renderLabel(o)}
+        </option>,
+      )
+    })
+    return items
+  }, [options, value, required])
+
+  const children = <>
+    {required ? undefined : <option></option>}
+    {renderedOptions}
+  </>
+
+  return wrap === false ? (
+    <CitricComponent
+      required={required}
+      onChange={handleChange}
+      disabled={disabled || loading}
+      tag="select"
+      component="select"
+      onFocus={onFocus}
+      onBlur={onBlur}
+    >
+      {children}
+    </CitricComponent>
+  ) : (
+    <CitricComponent tag="div" component="select" aria-busy={loading} {...props}>
+      <select required={required} onChange={handleChange} disabled={disabled || loading} onFocus={onFocus} onBlur={onBlur}>
+        {children}
+      </select>
+      {loading && <ProgressCircular className="loader" size="xs" />}
+    </CitricComponent>
+  )
+}

package/src/components/Select/index.tsx

@@ -0,0 +1,8 @@
+import { RichSelect } from './RichSelect'
+import { SimpleSelect } from './SimpleSelect'
+import { SelectProps } from './types'
+export type * from './types'
+
+export function Select<T>(props: SelectProps<T>) {
+  return props.type === 'simple' ? <SimpleSelect {...props} /> : <RichSelect {...props} />
+}