@stack-spot/citric-react 0.1.0

package/src/components/Select/types.ts

@@ -0,0 +1,121 @@
+import { HTMLExtension, WithColorScheme } from '../../types'
+
+interface CommonSelectProps<T> extends WithColorScheme {
+  /**
+   * All the items (options) to render.
+   */
+  options: T[],
+  /**
+   * If the value is undefined or "", an empty option is rendered. This option will disappear as soon as a valid option is selected, unless
+   * "required" is set to false.
+   */
+  value?: T,
+  /**
+   * Called whenever the selected option changes.
+   * @param value the currently selected item.
+   */
+  onChange?: (value: T | undefined) => 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?: (value: T) => string,
+  /**
+   * 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?: (value: T) => string | number | undefined,
+  /**
+   * Whether or not this input is required. This is also used to figure out if an empty option should be rendered or not.
+   * 
+   * An empty option is rendered whenever "required" is false or "value" is "" or undefined.
+   * @default true
+   */
+  required?: boolean,
+  /**
+   * Whether or not to show a loading feedback to the user.
+   * 
+   * Attention: selects that are loading should normally also be disabled.
+   */
+  loading?: boolean,
+  /**
+   * Whether or not this field is disabled.
+   * @default false
+   */
+  disabled?: boolean,
+  /**
+   * Function to run when the element receives focus. If the native select element received focus, a Select element is the target, otherwise
+   * the wrapping div element is.
+   * 
+   * If `rich` is false, the target will always be a select element.
+   */
+  onFocus?: React.EventHandler<React.FocusEvent<HTMLDivElement | HTMLSelectElement>>,
+  /**
+   * Function to run when the element loses focus. If the native select element received focus, a Select element is the target, otherwise
+   * the wrapping div element is.
+   * 
+   * If `rich` is false, the target will always be a select element.
+   */
+  onBlur?: React.EventHandler<React.FocusEvent<HTMLDivElement | HTMLSelectElement>>,
+  /**
+   * If the type is "simple", the native select element is rendered.
+   * 
+   * If the type is "rich", a custom select is rendered and more options are enabled, like "searchable".
+   * 
+   * @default 'rich'
+   */
+  type?: 'simple' | 'rich',
+}
+
+export interface SimpleSelectProps<T> extends CommonSelectProps<T> {
+  type: 'simple',
+}
+
+export interface RichSelectProps<T> extends CommonSelectProps<T> {
+  type?: 'rich',
+  /**
+   * Whether or not to render a search field. The search is based on the value returned by `renderLabel`.
+   * 
+   * @default false
+   */
+  searchable?: boolean,
+  /**
+   * A function to render the option in the selectable list.
+   * 
+   * The `renderLabel` function is used if this is not provided.
+   * @param value the option.
+   * @returns the React Node.
+   */
+  renderOption?: (value: T) => React.ReactNode,
+  /**
+   * A function to render the selected option in the header.
+   * 
+   * The `renderOption` function is used if this is not provided.
+   * @param value the option.
+   * @returns the React Node.
+   */
+  renderHeader?: (value: T | undefined) => React.ReactNode,
+  /**
+   * The maximum height of the options list in pixels.
+   * 
+   * @default 300
+   */
+  maxHeight?: number,
+  /**
+   * Whether or not to show the arrow inside the select's header.
+   * @default true
+   */
+  showArrow?: boolean,
+}
+
+export type BaseSelectProps<T> = SimpleSelectProps<T> | RichSelectProps<T>
+
+export type SelectProps<T> = HTMLExtension<'div', BaseSelectProps<T>, 'onChange' | 'children'>

package/src/components/SelectBox.tsx

@@ -0,0 +1,134 @@
+import { listToClass } from '@stack-spot/portal-theme'
+import { useMemo } from 'react'
+import { HTMLExtension, WithColorPalette, WithColorScheme } from '../types'
+import { defaultRenderKey, defaultRenderLabel } from '../utils/options'
+import { CitricComponent } from './CitricComponent'
+import { layout } from './layout'
+
+export interface SelectBoxLabel {
+  icon?: React.ReactElement,
+  title: string,
+  description?: string,
+}
+
+export interface CommonSelectBoxProps<T> extends WithColorPalette, WithColorScheme {
+  /**
+   * If multiple is true, checkboxes will be rendered instead of radio buttons.
+   * 
+   * @default false
+   */
+  multiple?: boolean,
+  /**
+   * The name for all checkboxes or radio buttons.
+   */
+  name?: string,
+  /**
+   * The options to show as select boxes.
+   */
+  options: T[],
+  /**
+   * A function that returns the data to render a select box for an option.
+   * 
+   * @default "extracts the title by converting the option to a string"
+   */
+  renderLabel?: (option: T) => SelectBoxLabel,
+  /**
+   * A function that returns a unique identifier for an option.
+   * 
+   * @default "if the option is a string, uses it as the key. Otherwise, the key won't be specified."
+   */
+  renderKey?: (option: T) => string | number | undefined,
+  /**
+   * A function that receives an option and decides if it's disabled or not.
+   */
+  isDisabled?: (option: T) => boolean,
+  /**
+   * Whether to render a row (horizontal) or a column (vertical).
+   * 
+   * @default 'horizontal'
+   */
+  direction?: 'horizontal' | 'vertical',
+  /**
+   * The background color level.
+   * 
+   * @default 300
+   */
+  bgLevel?: 300 | 400 | 500 | 600 | 700,
+}
+
+interface CheckboxProps<T> extends CommonSelectBoxProps<T> {
+  multiple: true,
+  value?: T[],
+  onChange?: (value: T[]) => void,
+}
+
+interface RadioProps<T> extends CommonSelectBoxProps<T> {
+  multiple?: false,
+  value?: T,
+  onChange?: (value: T) => void,
+}
+
+export type BaseSelectBoxProps<T> = RadioProps<T> | CheckboxProps<T>
+
+export type SelectBoxProps<T> = HTMLExtension<'div', BaseSelectBoxProps<T>, 'onChange'>
+
+export function SelectBox<T>({
+  multiple,
+  name,
+  value,
+  options,
+  onChange,
+  renderLabel = o => ({ title: defaultRenderLabel(o) }),
+  renderKey = defaultRenderKey,
+  isDisabled,
+  className,
+  style,
+  direction,
+  bgLevel,
+  colorPalette,
+  colorScheme,
+  ...props
+}: SelectBoxProps<T>) {
+  const items = useMemo(() => {
+    const valueAsArray = value ? (Array.isArray(value) ? value : [value]) : []
+    const valueKeys = valueAsArray.map(renderKey)
+    return options.map((o) => {
+      const key = renderKey(o)
+      const label = renderLabel(o)
+      return (
+        <CitricComponent key={key} tag="label" component="select-box" className={bgLevel ? `bg-${bgLevel}` : undefined}>
+          <input
+            type={multiple ? 'checkbox' : 'radio'}
+            name={name}
+            value={key}
+            checked={value ? valueKeys.includes(key) : undefined}
+            disabled={isDisabled?.(o)}
+            onChange={onChange ? (e) => {
+              if (multiple) {
+                onChange(e.target.checked ? [...valueAsArray, o] : valueAsArray.filter(v => renderKey(v) !== key)) 
+              } else {
+                onChange(o)
+              }
+            } : undefined}
+          />
+          <div className="option">
+            {label.icon}
+            <p className="title">{label.title}</p>
+            {label.description && <p className="description">{label.description}</p>}
+          </div>
+        </CitricComponent>
+      )
+    })
+  }, [options, value, name, multiple, bgLevel])
+  return (
+    <div
+      data-color-palette={colorPalette}
+      data-color-scheme={colorScheme}
+      className={listToClass([className, direction === 'vertical' ? layout.column : layout.row])}
+      style={{ gap: '5px', ...style }}
+      {...props}
+    >
+      {items}
+    </div>
+  )
+}

package/src/components/Skeleton.tsx

@@ -0,0 +1,41 @@
+import { listToClass } from '@stack-spot/portal-theme'
+import { HTMLExtension } from '../types'
+import { CitricComponent } from './CitricComponent'
+
+export interface BaseSkeletonProps {
+  /**
+   * The skeleton's appearance.
+   * 
+   * @default 'square'
+   */
+  appearance?: 'square' | 'circle',
+  /**
+   * The skeleton's width.
+   * 
+   * @default "the available width if 'square', 50px if 'circle'".
+   */
+  width?: string,
+  /**
+   * The skeleton's width.
+   * 
+   * @default "32px if 'square', 50px if 'circle'".
+   */
+  height?: string,
+  /**
+   * The background color level.
+   * 
+   * @default 500
+   */
+  bgLevel?: 400 | 500 | 600, 
+}
+
+export type SkeletonProps = HTMLExtension<'div', BaseSkeletonProps, 'children'>
+
+export const Skeleton = ({ appearance, className, style, width, height, bgLevel, ...props }: SkeletonProps) =>
+  <CitricComponent
+    tag="div"
+    component="skeleton"
+    className={listToClass([appearance, bgLevel && `bg-${bgLevel}`, className])}
+    style={{ width, height, ...style }}
+    {...props}
+  />

package/src/components/Slider.tsx

@@ -0,0 +1,77 @@
+import { listToClass } from '@stack-spot/portal-theme'
+import { HTMLExtension, WithColorPalette, WithColorScheme } from '../types'
+import { applyCSSVariable } from '../utils/css'
+import { CitricComponent } from './CitricComponent'
+
+export interface BaseSliderProps extends WithColorScheme, WithColorPalette {
+  value: number,
+  /**
+   * The minimum value in the numeric range.
+   * 
+   * @default 0
+   */
+  min?: number,
+  /**
+   * The maximum value in the numeric range.
+   * 
+   * @default 100
+   */
+  max?: number,
+  onChange: (value: number) => void,
+  /**
+   * When should we render the current value of the input?
+   * 
+   * @default 'always'
+   */
+  showValue?: 'always' | 'hover' | 'never',
+  /**
+   * A function to customize how the value of the input is rendered.
+   * 
+   * @default "{value}% if 'min' and 'max' are not provided. {value} otherwise."
+   */
+  renderValue?: (value: number) => string,
+}
+
+export type SliderProps =  HTMLExtension<'input', BaseSliderProps, 'children' | 'type' | 'value' | 'onChange'>
+
+export const Slider = (
+  { value, onChange, min, max, style, showValue, renderValue, colorPalette, colorScheme, className, ...props }: SliderProps,
+) => {
+  const percent = Math.floor((value / ((max ?? 100) - (min ?? 0))) * 100)
+  style = applyCSSVariable(style, 'percent', percent)
+  const rangeProps = {
+    value,
+    min,
+    max,
+    onChange: (e: React.ChangeEvent<HTMLInputElement>) => onChange(parseInt(e.target.value)),
+    ...props,
+  }  
+
+  return showValue === 'never'
+    ? <CitricComponent
+      tag="input"
+      type="range"
+      component="slider"
+      style={style}
+      className={className}
+      colorPalette={colorPalette}
+      colorScheme={colorScheme}
+      {...rangeProps}
+    />
+    : (
+      <CitricComponent
+        tag="div"
+        component="labeled-slider"
+        style={style}
+        colorPalette={colorPalette}
+        colorScheme={colorScheme}
+        className={listToClass([className, showValue === 'hover' && 'value-on-hover'])}
+      >
+        <input type="range" {...rangeProps} />
+        <div className="value">
+          {renderValue ? renderValue(value) : `${value}${min === undefined && max === undefined ? '%' : ''}`}
+        </div>
+      </CitricComponent>
+    )
+}
+

package/src/components/SmartTable.tsx

@@ -0,0 +1,148 @@
+import { useMemo } from 'react'
+import { BaseTableProps, SortingDirection, Table, TableProps, Th, Tr } from './Table'
+
+export type TableColumn<T> = {
+  /**
+   * A unique identifier for the column.
+   */
+  key: string,
+  /**
+   * A label to use as the column's header.
+   * 
+   * If not provided, the key will be used.
+   */
+  label?: React.ReactNode,
+  /**
+   * A custom render function. It receives the item (row) and must return a React node.
+   * 
+   * If not provided, the value of `item[key]` will be converted to a string and used. If it's undefined, an empty string is rendered.
+   * 
+   * @param item the current item.
+   * @returns the React Node to render.
+   */
+  render?: (item: T) => React.ReactNode,
+  /**
+   * What to do when the header is clicked (sorting)
+   */
+  onSort?: (value: SortingDirection | undefined) => void,
+  /**
+   * Which is the current direction of the sorting? Only relevant if 'onSort' is set.
+   * 
+   * @default 'desc'
+   */
+  direction?: SortingDirection,
+  /**
+   * Additional properties for the "th" corresponding to this column.
+   */
+  th?: Omit<JSX.IntrinsicElements['th'], 'children'>,
+  /**
+   * Additional properties for the "td" corresponding to this column.
+   */
+  td?: Omit<JSX.IntrinsicElements['td'], 'children'>,
+}
+
+interface ExtraSmartTableProps<T extends Record<string, any>> {
+  /**
+   * An array where each item is a row in the table.
+   */
+  data: T[],
+  /**
+   * A function to generate a unique key for each item. If not provided, the item's index will be used.
+   * @param item
+   * @returns a unique key
+   */
+  keygen?: (item: T) => React.Key,
+  /**
+   * The columns to display in the table.
+   * 
+   * Attention: always save your columns with `useMemo` to avoid unnecessary rerenders.
+   */
+  columns: TableColumn<T>[],
+  /**
+   * If set, an extra row and column for each item is rendered. The extra row is collapsed by default and can be expanded through a button
+   * that is placed in the extra column.
+   * 
+   * The extra row is, effectively, an accordion. The content of this accordion is defined by whatever this function returns.
+   * 
+   * @param item the current item.
+   * @returns the React Node to render.
+   */
+  renderAccordion?: (item: T) => React.ReactNode,
+  /**
+   * What should make the accordions expand or contract? A click on a button in the last column or a click anywhere in the row?
+   * 
+   * Only valid if `renderAccordion` is set.
+   * 
+   * @default 'button'
+   */
+  accordionTrigger?: 'button' | 'row',
+  /**
+   * The maximum height for accordion rows.
+   * 
+   * @default '200px'
+   */
+  accordionMaxHeight?: string,
+}
+
+export type BaseSmartTableProps<T extends Record<string, any>> = BaseTableProps & ExtraSmartTableProps<T>
+
+export type SmartTableProps<T extends Record<string, any>> = Omit<TableProps, 'children'> & ExtraSmartTableProps<T>
+
+export function SmartTable<T extends Record<string, any>>(
+  { data, keygen, columns, renderAccordion, accordionTrigger, accordionMaxHeight, id, ...props }: SmartTableProps<T>,
+) {
+  id = useMemo(() => id || `${Math.random()}`, [id])
+
+  const headers = useMemo(
+    () => columns.map((c) => (
+      <Th {...c.th} key={c.key} onSort={c.onSort} direction={c.direction} tabIndex={c.onSort ? 0 : undefined}>
+        {c.label ?? c.key}
+      </Th>
+    )),
+    [columns],
+  )
+
+  const rows = useMemo(
+    () => data.map((item, index) => {
+      const key = keygen ? keygen(item) : index
+      const accordionContent = renderAccordion?.(item)
+      const row = (
+        <Tr key={key} accordionTrigger={accordionContent ? accordionTrigger : undefined}>
+          {columns.map(c => <td {...c.td} key={c.key}>{c.render ? c.render(item) : (item[c.key] || '')}</td>)}
+          {renderAccordion && (
+            <td>
+              {accordionContent && (
+                <input
+                  type="checkbox"
+                  aria-controls={`${id}-${key}`}
+                  onKeyDown={e => e.key === 'Enter' && e.target instanceof HTMLElement && e.target.click()}
+                />
+              )}
+            </td>
+          )}
+        </Tr>
+      )
+      return renderAccordion ? (
+        <tbody key={`${key}-group`}>
+          {row}
+          <Tr id={`${id}-${key}`} accordion accordionMaxHeight={accordionMaxHeight}>
+            <td colSpan={columns.length + 1}><div>{accordionContent}</div></td>
+          </Tr>
+        </tbody>
+      ) : row
+    }),
+    [columns, data, !!renderAccordion, accordionTrigger],
+  )
+
+  return (
+    <Table id={id} accordionRows={!!renderAccordion} {...props}>
+      <thead>
+        <tr>
+          {headers}
+          {renderAccordion && <th></th>}
+        </tr>
+      </thead>
+      {renderAccordion ? rows : <tbody>{rows}</tbody>}
+    </Table>
+  )
+}

package/src/components/Stepper.tsx

@@ -0,0 +1,142 @@
+import { listToClass } from '@stack-spot/portal-theme'
+import { Dictionary, useTranslate } from '@stack-spot/portal-translate'
+import { useCallback, useEffect, useMemo, useState } from 'react'
+import { HTMLExtension } from '../types'
+import { Button } from './Button'
+import { Column, Row } from './layout'
+import { Tabs } from './Tabs'
+import { TabController } from './Tabs/TabController'
+import { BaseTabsProps, Tab } from './Tabs/types'
+import { findSelectedIndex } from './Tabs/utils'
+
+export interface BaseStepperProps<Key extends string> extends BaseTabsProps<Key> {
+  /**
+   * Should we show buttons to control the step we are in?
+   * 
+   * Set it to false to not show any buttons, set it to true to show a default set of buttons, set it to an object to customize the buttons.
+   * 
+   * @default true
+   */
+  buttons?: boolean | {
+    /**
+     * The text for the previous button.
+     */
+    previous?: string,
+    /**
+     * The text for the next button.
+     */
+    next?: string,
+    /**
+     * The text for the finish button.
+     */
+    finish?: string,
+    /**
+     * The text for the cancel button.
+     */
+    cancel?: string,
+    /**
+     * When set, instead of not showing a previous button in the first step, it shows a cancel button. This function is run whenever the
+     * cancel button is clicked.
+     */
+    onCancel?: () => void,
+    /**
+     * An additional function to run whenever the previous button is clicked. Return false to prevent the default action (going to the
+     * previous step).
+     */
+    onPrevious?: (tab: Key) => void | boolean,
+    /**
+     * An additional function to run whenever the next button is clicked. Return false to prevent the default action (going to the
+     * next step).
+     */
+    onNext?: (tab: Key) => void | boolean,
+    /**
+     * When set, instead of not showing a next button in the final step, it shows a finish button. This function is run whenever the
+     * finish button is clicked.
+     */
+    onFinish?: () => void,
+  },
+}
+
+export type StepperProps<Key extends string> = HTMLExtension<'div', BaseStepperProps<Key>, 'children' | 'value' | 'onChange'>
+
+function getTabsWithDisabled<Key extends string>(tabs: Tab<Key>[], value: Key | undefined) {
+  let index = findSelectedIndex(tabs, value ?? '')
+  if (index < 0) index = 0
+  return tabs.map((t, i) => ({ ...t, disabled: i > index }))
+}
+
+export function Stepper<Key extends string>(
+  { tabs: initialTabs, controller: ctrl, value, onChange, buttons = true, className, ...props }: StepperProps<Key>,
+) {
+  const controller = useMemo(
+    () => ctrl ?? new TabController<Key>(initialTabs.map(t => t.key), value || initialTabs[0]?.key),
+    [],
+  )
+  const [tabs, setTabs] = useState(getTabsWithDisabled(initialTabs, value))
+  const [selectedIndex, setSelectedIndex] = useState(findSelectedIndex(tabs, controller.getValue()))
+  const t = useTranslate(dictionary)
+
+  useEffect(() => controller.onChange((v) => {
+    setSelectedIndex(findSelectedIndex(tabs, v))
+  }), [tabs])
+
+  useEffect(() => controller.onChange((value) => {
+    setTabs(getTabsWithDisabled(initialTabs, value))
+  }), [])
+
+  const onPrevious = useCallback(() => {
+    controller.previous()
+    if (typeof buttons === 'object') buttons.onPrevious?.(controller.getValue())
+  }, [])
+
+  const onNext = useCallback(() => {
+    controller.next()
+    if (typeof buttons === 'object') buttons.onNext?.(controller.getValue())
+  }, [])
+
+  return buttons ? (
+    <Column {...props} className={className} gap="20px">
+      <Tabs tabs={tabs} controller={controller} value={value} onChange={onChange} className="stepper" />
+      <Row justifyContent={(typeof buttons !== 'object' || !buttons.onCancel) && selectedIndex === 0 ? 'end' : 'space-between'}>
+        {selectedIndex === 0 && typeof buttons === 'object' && buttons.onCancel && (
+          <Button onClick={buttons.onCancel} colorScheme="inverse" appearance="outlined">{buttons.cancel || t.cancel}</Button>
+        )}
+        {selectedIndex > 0 && buttons && (
+          <Button onClick={onPrevious} colorScheme="inverse" appearance="outlined">
+            {(typeof buttons === 'object' && buttons.previous) || t.previous}
+          </Button>
+        )}
+        {selectedIndex < tabs.length - 1 && buttons && (
+          <Button onClick={onNext}>
+            {(typeof buttons === 'object' && buttons.next) || t.next}
+          </Button>
+        )}
+        {selectedIndex === tabs.length - 1 && typeof buttons === 'object' && buttons.onFinish && (
+          <Button onClick={buttons.onFinish}>{buttons.finish || t.finish}</Button>
+        )}
+      </Row>
+    </Column>
+  ) : <Tabs
+    tabs={tabs}
+    controller={controller}
+    value={value}
+    onChange={onChange}
+    className={listToClass([className, 'stepper'])}
+    {...props}
+  />
+}
+
+const dictionary = {
+  en: {
+    cancel: 'Cancel',
+    previous: 'Previous',
+    next: 'Next',
+    finish: 'Finish',
+  },
+  pt: {
+    cancel: 'Cancelar',
+    previous: 'Anterior',
+    next: 'Próximo',
+    finish: 'Finalizar',
+  },
+} satisfies Dictionary

package/src/components/Switch.tsx

@@ -0,0 +1,29 @@
+import { HTMLExtension, WithColorScheme } from '../types'
+import { CitricComponent } from './CitricComponent'
+
+interface Props extends WithColorScheme {
+  value?: boolean,
+  onChange?: (value: boolean) => void,
+  children?: React.ReactNode,
+}
+
+export type SwitchProps = HTMLExtension<'input', Props, 'type'>
+
+export const Switch = ({ value, onChange, children, className, style, ...props }: SwitchProps) => {
+  const handleChange = onChange ? () => onChange(!value) : undefined
+  return children ? (
+    <CitricComponent tag="label" component="switch-row" style={style} className={className}>
+      <input type="checkbox" checked={value} onChange={handleChange} {...props} />
+      {children}
+    </CitricComponent>
+  ) : <CitricComponent
+    tag="input"
+    type="checkbox"
+    component="switch"
+    checked={value}
+    onChange={handleChange}
+    className={className}
+    style={style}
+    {...props}
+  />
+}