@stack-spot/citric-react 0.1.0

package/src/components/Button.tsx

@@ -0,0 +1,88 @@
+import { listToClass } from '@stack-spot/portal-theme'
+import { useState } from 'react'
+import { useCitricController } from '../context/hooks'
+import { HTMLExtension, WithColorScheme } from '../types'
+import { CitricComponent } from './CitricComponent'
+import { ProgressCircular } from './ProgressCircular'
+
+export interface BaseButtonProps extends WithColorScheme {
+  /**
+   * - contained for buttons with background;
+   * - outlined for transparent buttons with borders;
+   * - text for buttons with no borders or background.
+   * @default 'contained'
+   */
+  appearance?: 'outlined' | 'text' | 'contained',
+  /**
+   * Size of the button.
+   * @default 'md'
+   */
+  size?: 'sm' | 'md' | 'lg',
+  /**
+   * Animated text to show on when the button is clicked.
+   */
+  feedback?: string,
+  /**
+   * Whether or not to show a loading feedback instead of the button's content.
+   * 
+   * Buttons in the loading state are also disabled.
+   */
+  loading?: boolean,
+  /**
+   * Function to run when the button is clicked. If this function returns a promise, the button will automatically show a loading feedback
+   * until the promise completes.
+   */
+  onClick?: (event: React.MouseEvent<HTMLButtonElement, MouseEvent>) => any,
+  /**
+   * Whether or not a click in this button should generate analytics data.
+   * 
+   * This only takes effect if there's a CitricController in React's context. The value of `analytics` is passed to the function
+   * `onClickButton` of the controller.
+   * 
+   * @default false
+   */
+  analytics?: boolean,
+}
+
+export type ButtonProps = HTMLExtension<'button', BaseButtonProps, 'onClick'>
+
+export const Button = (
+  { appearance, size, feedback, loading, disabled, onClick, className, children, type = 'button', analytics, ...props }: ButtonProps,
+) => {
+  const citric = useCitricController()
+  const [waiting, setWaiting] = useState(false)
+  const busy = loading || waiting
+
+  async function handleClick(e: React.MouseEvent<HTMLButtonElement, MouseEvent>) {
+    const result = onClick?.(e)
+    citric?.onClickButton?.(e, analytics ?? false)
+    if (result instanceof Promise) {
+      setWaiting(true)
+      try {
+        await result
+      } catch { /* empty */ }
+      setWaiting(false)
+    }
+  }
+
+  return (
+    <CitricComponent
+      tag="button"
+      component="button"
+      className={listToClass([size, appearance, className])}
+      data-feedback={feedback}
+      onClick={handleClick}
+      aria-busy={busy}
+      disabled={disabled || busy}
+      type={type}
+      {...props}
+    >
+      {busy ? <div>{children}</div> : children}
+      {busy && (
+        <div className="loader">
+          <ProgressCircular size="sm" />
+        </div>
+      )}
+    </CitricComponent>
+  )
+}

package/src/components/Card.tsx

@@ -0,0 +1,32 @@
+import { listToClass } from '@stack-spot/portal-theme'
+import { HTMLExtension, WithColorScheme } from '../types'
+import { CitricComponent } from './CitricComponent'
+
+export interface BaseCardProps extends WithColorScheme {
+  onClick?: (event: React.MouseEvent<HTMLDivElement>) => void,
+  /**
+   * The size of the card.
+   * 
+   * @default 'md'
+   */
+  size?: 'xxs' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'xxl',
+  /**
+   * The background color level. The main color will depend on the "colorScheme", which is "light" by default.
+   * 
+   * @default 300
+   */
+  bgLevel?: 300 | 400 | 500 | 600, 
+}
+
+export type CardProps = HTMLExtension<'div', BaseCardProps>
+
+export const Card = ({ onClick, size, bgLevel, className, children, ...props }: CardProps) => (
+  <CitricComponent
+    tag="div"
+    component="card"
+    className={listToClass([onClick && 'clickable', size, bgLevel && `bg-${bgLevel}`, className])}
+    {...props}
+  >
+    {children}
+  </CitricComponent>
+)

package/src/components/Checkbox.tsx

@@ -0,0 +1,36 @@
+import { HTMLExtension, WithColorScheme } from '../types'
+import { CitricComponent } from './CitricComponent'
+
+export interface BaseCheckboxProps extends WithColorScheme {
+  /**
+   * "checkbox" for common check boxes, "switch" for toggles.
+   * @default 'checkbox' 
+   */
+  appearance?: 'checkbox' | 'switch',
+  value?: boolean,
+  onChange?: (value: boolean) => void,
+  children?: React.ReactNode,
+}
+
+export type CheckboxProps = HTMLExtension<'input', BaseCheckboxProps, 'type' | 'onChange' | 'value'>
+
+export const Checkbox = (
+  { appearance = 'checkbox', value, onChange, colorScheme, children, className, style, ...props }: CheckboxProps,
+) => {
+  const handleChange = onChange ? () => onChange(!value) : undefined
+  return children ? (
+    <CitricComponent tag="label" component={`${appearance}-row`} colorScheme={colorScheme} style={style} className={className}>
+      <input type="checkbox" checked={value} onChange={handleChange} {...props} />
+      {children}
+    </CitricComponent>
+  ) : <CitricComponent
+    tag="input"
+    type="checkbox"
+    component={appearance}
+    checked={value}
+    onChange={handleChange}
+    className={className}
+    style={style}
+    {...props}
+  />
+}

package/src/components/CheckboxGroup.tsx

@@ -0,0 +1,93 @@
+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 BaseCheckboxGroupProps<T = any> extends WithColorScheme {
+  /**
+   * "checkbox" for common check boxes, "switch" for toggles.
+   * @default 'checkbox'
+   */
+  appearance?: 'checkbox' | 'switch',
+  /**
+   * The field name.
+   */
+  name?: string,
+  /**
+   * All items corresponding to the selected checkboxes.
+   */
+  value: T[],
+  /**
+   * All the items (checkboxes) to render.
+   */
+  options: T[],
+  /**
+   * Called whenever the selected checkboxes changes.
+   * @param value the currently selected items.
+   */
+  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 CheckboxGroupProps<T> = HTMLExtension<'div', BaseCheckboxGroupProps<T>, 'onChange'>
+
+export function CheckboxGroup<T>({
+  appearance = 'checkbox',
+  name,
+  value = [],
+  options,
+  onChange,
+  renderLabel = defaultRenderLabel,
+  renderKey = defaultRenderKey,
+  isDisabled,
+  colorScheme,
+  style,
+  ...props
+}: CheckboxGroupProps<T>) {
+  const items = useMemo(() => {
+    const valueKeys = value.map(renderKey)
+    return options.map((o) => {
+      const key = renderKey(o)
+      return (
+        <CitricComponent tag="label" component={`${appearance}-row`} key={key} colorScheme={colorScheme}>
+          <input
+            type="checkbox"
+            name={name}
+            value={key}
+            checked={value.includes(o) || (!isNil(key) && valueKeys.includes(key))}
+            onChange={(e) => onChange?.(e.target.checked ? [...(value ?? []), o] : (value?.filter(item => item != o) ?? []))}
+            disabled={isDisabled?.(o)}
+          />
+          {renderLabel(o)}
+        </CitricComponent>
+      )
+    })
+  }, [options, value, name, colorScheme, appearance])
+  return <Column {...props} style={{ gap: '8px', ...style }}>{items}</Column>
+}

package/src/components/Circle.tsx

@@ -0,0 +1,26 @@
+import { listToClass } from '@stack-spot/portal-theme'
+import { HTMLExtension, WithColorPalette, WithColorScheme } from '../types'
+import { CitricComponent } from './CitricComponent'
+
+export interface BaseCircleProps extends WithColorPalette, WithColorScheme {
+  /**
+   * Whether or not to show borders.
+   * 
+   * @default false
+   */
+  showBorders?: boolean,
+  /**
+   * The size of the circle.
+   * 
+   * @default 'xs'
+   */
+  size?: 'xxs' | 'xs' | 'sm' | 'lg' | 'xl' | 'xxl',
+}
+
+export type CircleProps = HTMLExtension<'div', BaseCircleProps>
+
+export const Circle = ({ showBorders, className, size, children, ...props }: CircleProps) => (
+  <CitricComponent tag="div" component="circle" className={listToClass([className, showBorders && 'bordered', size])} {...props}>
+    {children}
+  </CitricComponent>
+)

package/src/components/CitricComponent.ts

@@ -0,0 +1,34 @@
+import { createElement, forwardRef } from 'react'
+import { WithColorPalette, WithColorScheme } from '../types'
+
+export type CitricComponentName = 'alert' | 'avatar' | 'badge' | 'blockquote' | 'breadcrumb' | 'button' | 'card' | 'checkbox' |
+  'checkbox-row' | 'divider' | 'field-group' | 'form-group' | 'form' | 'icon-box' | 'input' | 'link' | 'pagination' | 'progress-bar' |
+  'progress-circular' | 'radio' | 'radio-row' | 'rating' | 'select' | 'select-box' | 'skeleton' | 'slider' | 'switch' | 'switch-row' |
+  'table' | 'tabs' | 'accordion' | 'favorite' | 'textarea' | 'avatar-group' | 'labeled-slider' | 'rich-select' | 'tooltip' | 'menu' |
+  'circle'
+
+interface CustomProps<T extends keyof JSX.IntrinsicElements> extends WithColorScheme, WithColorPalette {
+  tag: T,
+  component: CitricComponentName,
+} 
+
+type Props<T extends keyof JSX.IntrinsicElements> = CustomProps<T> & JSX.IntrinsicElements[T]
+
+interface CitricComponentType {
+  <T extends keyof JSX.IntrinsicElements>(props: Props<T>): React.ReactNode,
+}
+
+export function asCitricProps({ colorScheme, colorPalette, component, ...props }: Omit<Props<any>, 'tag'>) {
+  const citricProps: Record<string, any> = { ...props, 'data-citric': component }
+  if (colorScheme) citricProps['data-color-scheme'] = colorScheme
+  if (colorPalette) citricProps['data-color-palette'] = colorPalette
+  return citricProps
+}
+
+// eslint-disable-next-line react/display-name
+export const CitricComponent: CitricComponentType = forwardRef<Props<any>, any>(
+  (props, ref) => {
+    const { tag, ...citricProps } = asCitricProps(props)
+    return createElement(tag, { ...citricProps, ref })
+  },
+)

package/src/components/Divider.tsx

@@ -0,0 +1,22 @@
+import { listToClass } from '@stack-spot/portal-theme'
+import { HTMLExtension, WithColorScheme } from '../types'
+import { CitricComponent } from './CitricComponent'
+
+export interface BaseDividerProps extends WithColorScheme {
+  /**
+   * @default 'horizontal'
+   */
+  direction?: 'horizontal' | 'vertical',
+  /**
+   * @default 'sm'
+   */
+  size?: 'sm' | 'md' | 'lg',
+}
+
+export type DividerProps = HTMLExtension<'hr', BaseDividerProps>
+
+export const Divider = ({ size, direction, className, children, ...props }: DividerProps) => (
+  <CitricComponent tag="hr" component="divider" className={listToClass([className, size, direction])} {...props}>
+    {children}
+  </CitricComponent>
+)

package/src/components/ErrorBoundary.tsx

@@ -0,0 +1,62 @@
+import { Component } from 'react'
+import { CitricContext } from '../context/CitricContext'
+import { ErrorMessage } from './ErrorMessage'
+
+interface State {
+  error?: any,
+}
+
+interface Props {
+  children: React.ReactNode,
+  /**
+   * Sets a default error string when a string is provided.
+   * 
+   * Replaces the error component, if a function is provided.
+   */
+  message?: React.ReactNode | ((error: any) => React.ReactNode),
+}
+
+/**
+ * An Error Boundary that renders an error feedback instead of its content if any of its children throws.
+ */
+export class ErrorBoundary extends Component<Props, State> {
+  static contextType = CitricContext
+  declare context: React.ContextType<typeof CitricContext>
+
+  constructor(props: Props) {
+    super(props)
+    this.state = {}
+  }
+
+  static getDerivedStateFromError(error: any) {
+    return { error }
+  }
+
+  componentDidCatch(error: any, errorInfo: any) {
+    this.context?.onError?.(error)
+    // eslint-disable-next-line no-console
+    console.error(error, errorInfo)
+  }
+
+  componentDidUpdate(prevProps: Readonly<Props>) {
+    if (this.state.error && this.props.children !== prevProps.children) {
+      this.setState({})
+    }
+  }
+
+  private renderCustomErrorUI() {
+    return this.context?.renderError?.(this.state.error)
+  }
+
+  private renderErrorUI() {
+    if (typeof this.props.message === 'function') return this.props.message(this.state.error)
+    return (this.props.message || !this.context?.renderError)
+      ? <ErrorMessage error={this.props.message || this.state.error} />
+      : this.renderCustomErrorUI()
+  }
+
+
+  render() {
+    return this.state.error ? this.renderErrorUI() : this.props.children
+  }
+}

package/src/components/ErrorMessage.tsx

@@ -0,0 +1,11 @@
+import { Icon } from '@stack-spot/citric-icons'
+import { theme } from '@stack-spot/portal-theme'
+import { Row } from './layout'
+import { Text } from './Text'
+
+export const ErrorMessage = ({ error }: { error: any }) => (
+  <Row gap="18px" p="20px" justifyContent="center">
+    <Icon icon="TimesCircle" size="xl" style={{ color: theme.color.danger[500] }} />
+    <Text style={{ margin: '80px' }}>{error.message || `${error}`}</Text>
+  </Row>
+)

package/src/components/FallbackBoundary.tsx

@@ -0,0 +1,29 @@
+import { Suspense } from 'react'
+import { ErrorBoundary } from './ErrorBoundary'
+import { Center } from './layout'
+import { ProgressCircular } from './ProgressCircular'
+
+interface Props {
+  /**
+   * Replaces the error message with this text.
+   */
+  message?: string,
+  children: React.ReactNode,
+}
+
+const loading = (
+  <Center flex={1} p="80px" data-test-hint="loading">
+    <ProgressCircular />
+  </Center>
+)
+
+/**
+ * Fallbacks for errors and loadings (suspense).
+ */
+export const FallbackBoundary = ({ children, message }: Props) => (
+  <ErrorBoundary message={message}>
+    <Suspense fallback={loading}>
+      {children}
+    </Suspense>
+  </ErrorBoundary>
+)

package/src/components/Favorite.tsx

@@ -0,0 +1,37 @@
+import { listToClass } from '@stack-spot/portal-theme'
+import { HTMLExtension } from '../types'
+import { CitricComponent } from './CitricComponent'
+
+type FavoriteAppearance = 'square' | 'circle' | 'text'
+
+export interface BaseFavoriteProps {
+  value: boolean | undefined,
+  /**
+   * Size of the button.
+   * 
+   * @default 'md'
+   */
+  size?: 'sm' | 'md' | 'lg' | 'fit-parent',
+  /**
+   * Button appearance.
+   * 
+   * @default 'text'
+   */
+  appearance?: FavoriteAppearance,
+  onChange: (value: boolean) => void,
+  isLoading?: boolean,
+}
+
+export type FavoriteProps = HTMLExtension<'input', BaseFavoriteProps, 'type' | 'checked' | 'onChange' | 'size' | 'value'>
+
+export const Favorite = ({ value, size, appearance, onChange, isLoading, className, ...props }: FavoriteProps) =>
+  <CitricComponent
+    tag="input"
+    type="checkbox"
+    component="favorite"
+    className={listToClass([appearance, size, className])}
+    checked={!!value}
+    onChange={() => onChange(!value)}
+    aria-busy={isLoading}
+    {...props}
+  />

package/src/components/FieldGroup.tsx

@@ -0,0 +1,22 @@
+import { listToClass } from '@stack-spot/portal-theme'
+import { HTMLExtension } from '../types'
+import { CitricComponent } from './CitricComponent'
+
+export interface BaseFieldGroupProps {
+  /**
+   * When this is true, the component will automatically mark the addons.
+   * 
+   * When this is false, you must add the class "addon" manually to each of the addons.
+   * 
+   * @default true 
+   */
+  auto?: boolean,
+}
+
+export type FieldGroupProps = HTMLExtension<'div', BaseFieldGroupProps>
+
+export const FieldGroup = ({ auto = true, className, children, ...props }: FieldGroupProps) => (
+  <CitricComponent tag="div" component="field-group" className={listToClass([className, auto && 'auto'])} {...props}>
+    {children}
+  </CitricComponent>
+)

package/src/components/Form.tsx

@@ -0,0 +1,17 @@
+import { listToClass } from '@stack-spot/portal-theme'
+import { CitricComponent } from './CitricComponent'
+
+export type FormProps = JSX.IntrinsicElements['form']
+export type ButtonGroupProps = JSX.IntrinsicElements['div']
+
+export const Form = ({ children, ...props }: FormProps) => (
+  <CitricComponent tag="form" component="form" {...props}>
+    {children}
+  </CitricComponent>
+)
+
+export const ButtonGroup = ({ className, children, ...props }: ButtonGroupProps) => (
+  <div className={listToClass([className, 'button-group'])} {...props}>
+    {children}
+  </div>
+)

package/src/components/FormGroup.tsx

@@ -0,0 +1,45 @@
+import { listToClass } from '@stack-spot/portal-theme'
+import { HTMLExtension } from '../types'
+import { CitricComponent } from './CitricComponent'
+import { IconButton } from './IconBox'
+import { Text } from './Text'
+import { Tooltip } from './Tooltip'
+
+export interface BaseFormGroupProps {
+  /**
+   * The error string to show, if any. The empty string is equivalent to undefined, i.e. no errors.
+   */
+  error?: string,
+  /**
+   * The input's label.
+   */
+  label?: string,
+  /**
+   * A help string, to show as a tooltip.
+   */
+  help?: string,
+  /**
+   * A warning string, to show right below the field, at all times.
+   */
+  warning?: string,
+}
+
+export type FormGroupProps = HTMLExtension<'div', BaseFormGroupProps>
+
+export const FormGroup = ({ error, help, label, warning, className, children, ...props }: FormGroupProps) => (
+  <CitricComponent tag="div" component="form-group" className={listToClass([className, error && 'error'])} {...props}>
+    <label>
+      {help ? (
+        <div className="row">
+          <Text>{label}</Text>
+          <Tooltip content={help}>
+            <IconButton icon="InfoCircle" size="xs" />
+          </Tooltip>
+        </div>
+      ): label}
+      {children}
+      <div className="feedback">{error}</div>
+      {warning && <div className="warning">{warning}</div>}
+    </label>
+  </CitricComponent>
+)

package/src/components/IconBox.tsx

@@ -0,0 +1,78 @@
+import { IconGroup, IconOwnProps } from '@stack-spot/citric-icons'
+import { listToClass } from '@stack-spot/portal-theme'
+import { useCallback } from 'react'
+import { useCitricController } from '../context/hooks'
+import { HTMLExtension, WithColorPalette, WithColorScheme } from '../types'
+import { CitricComponent } from './CitricComponent'
+
+type IconBoxTag = 'a' | 'button' | 'i' | 'span' | 'div'
+
+export interface BaseIconBoxProps<T extends IconBoxTag, G extends IconGroup> extends IconOwnProps<G>, WithColorScheme, WithColorPalette {
+  /**
+   * The HTML element to render.
+   * 
+   * @default 'i'
+   */
+  tag?: T,
+  /**
+   * The box appearance.
+   * 
+   * @default 'circle'
+   */
+  appearance?: 'circle' | 'square',
+  /**
+   * Size of the box.
+   * 
+   * @default 'sm'
+   */
+  size?: 'xs' | 'sm' | 'md' | 'lg',
+  /**
+   * Only valid if `tag` is "button" or "a".
+   * 
+   * Whether or not a click in this button/link should generate analytics data.
+   * 
+   * This only takes effect if there's a CitricController in React's context. The value of `analytics` is passed to the function
+   * `onClickButton/onClickLink` of the controller.
+   * 
+   * @default false
+   */
+  analytics?: boolean,
+}
+
+export type IconBoxProps<T extends IconBoxTag, G extends IconGroup> = HTMLExtension<T, BaseIconBoxProps<T, G>>
+
+export function IconBox<T extends IconBoxTag = 'i', G extends IconGroup = 'outline'>(
+  { group, icon, tag, colorScheme, colorPalette, appearance, size, className, analytics, onClick, ...props }: IconBoxProps<T, G>,
+) {
+  const citric = useCitricController()
+
+  const handleClick = useCallback((e: React.MouseEvent<any>) => {
+    onClick?.(e)
+    if (tag === 'button') citric?.onClickButton?.(e, analytics ?? false)
+    else if (tag === 'a') citric?.onClickLink?.(e, analytics ?? false)
+  }, [tag])
+
+  return <CitricComponent
+    tag={(tag || 'i') as any}
+    component="icon-box"
+    className={listToClass(['citric-icon', group || 'outline', icon, appearance, size, className])}
+    colorScheme={colorScheme}
+    colorPalette={colorPalette}
+    onClick={['button', 'a'].includes(tag ?? '') ? handleClick : onClick}
+    {...props}
+  />
+}
+
+/**
+ * Shortcut to <IconBox tag="button" />
+ */
+export function IconButton<G extends IconGroup = 'outline'>(props: Omit<IconBoxProps<'button', G>, 'tag'>) {
+  return IconBox({ ...props, tag: 'button', type: props.type || 'button' })
+}
+
+/**
+ * Shortcut to <IconBox tag="a" />
+ */
+export function IconLink<G extends IconGroup = 'outline'>(props: Omit<IconBoxProps<'a', G>, 'tag'>) {
+  return IconBox({ ...props, tag: 'a' })
+}

package/src/components/Input.tsx

@@ -0,0 +1,32 @@
+import { HTMLExtension, WithColorScheme } from '../types'
+import { CitricComponent } from './CitricComponent'
+
+export type SupportedInputType = 'color' | 'date' | 'datetime-local' | 'email' | 'month' | 'number' | 'password' | 'search' | 'tel' | 
+  'text' | 'time' | 'url' | 'week'
+
+export interface BaseInputProps<T extends SupportedInputType> extends WithColorScheme {
+  /**
+   * @default 'text'
+   */
+  type?: T,
+  value?: T extends 'number' ? number : string,
+  onChange?: (value: T extends 'number' ? (number | undefined) : string) => void,
+}
+
+export type InputProps<T extends SupportedInputType = 'text'> = 
+  HTMLExtension<'input', BaseInputProps<T> & { type?: T }, 'type' | 'value' | 'onChange'>
+
+export function Input<T extends SupportedInputType = 'text'>({ type, value, onChange, ...props }: InputProps<T>) {
+  function handleChange(e: React.ChangeEvent<HTMLInputElement>) {
+    if (!onChange) return
+    const newValue = e.target.value
+    if (type === 'number') {
+      const parsed = newValue ? parseFloat(newValue) : undefined
+      onChange(parsed as any)
+    } else {
+      onChange(newValue as any)
+    }
+  }
+
+  return <CitricComponent tag="input" component="input" type={type} value={value} onChange={handleChange} {...props} />
+}