@stack-spot/citric-react 0.21.0 → 0.23.0

package/src/components/RadioGroup.tsx

@@ -67,42 +67,65 @@ export interface BaseRadioGroupProps<T> extends WithColorScheme {
 
 export type RadioGroupProps<T> = Omit<React.JSX.IntrinsicElements['div'], 'onChange' | 'children'> & BaseRadioGroupProps<T>
 
-function _RadioGroup<T>({
-  name,
-  value,
-  options,
-  onChange,
-  renderLabel = defaultRenderLabel,
-  renderKey = defaultRenderKey,
-  renderItem,
-  isDisabled,
-  colorScheme,
-  style,
-  ...props
-}: RadioGroupProps<T>) {
-  const items = useMemo(() => {
-    const valueKey = value ? renderKey(value) : undefined
-    return options.map((o) => {
-      const key = renderKey(o)
-      const radio = <CitricComponent
-        tag="input"
-        component="radio"
-        type="radio"
-        name={name}
-        value={key}
-        checked={value === o || (!isNil(key) && valueKey === key)}
-        onChange={() => onChange?.(o)}
-        disabled={isDisabled?.(o)}
-      />
-      return renderItem ? renderItem(radio, o) : (
-        <CitricComponent tag="label" component="radio-row" key={key} colorScheme={colorScheme}>
-          {radio}
-          {renderLabel(o)}
-        </CitricComponent>
-      )
-    })
-  }, [options, value, name, colorScheme])
-  return <Column {...props} style={{ gap: '8px', ...style }}>{items}</Column>
-}
-
-export const RadioGroup = withRef(_RadioGroup)
+/**
+ * Renders a list of radio button for single-selection. One radio button is rendered for each option.
+ * 
+ * Attention: single radio buttons don't make sense, this is why they're not provided by this library.
+ * 
+ * This component can be heavily customized via its properties. Check the storybook for complex examples.
+ * 
+ * Tip: if you need to implement features like "search", use the hook `useRadioGroupControls`.
+ * 
+ * @example
+ * 
+ * ```
+ * const options = useMemo(() => [
+ *   { id: 1, name: 'Option 1' },
+ *   { id: 2, name: 'Option 2' },
+ *   { id: 3, name: 'Option 3' },
+ * ], [])
+ * 
+ * const [value, setValue] = useState<(typeof options)[number] | undefined>()
+ * 
+ * return <RadioGroup options={options} renderLabel={o => o.name} renderKey={o => o.id} value={value} setValue={setValue} />
+ * ```
+ */
+export const RadioGroup = withRef(
+  function RadioGroup<T>({
+    name,
+    value,
+    options,
+    onChange,
+    renderLabel = defaultRenderLabel,
+    renderKey = defaultRenderKey,
+    renderItem,
+    isDisabled,
+    colorScheme,
+    style,
+    ...props
+  }: RadioGroupProps<T>) {
+    const items = useMemo(() => {
+      const valueKey = value ? renderKey(value) : undefined
+      return options.map((o) => {
+        const key = renderKey(o)
+        const radio = <CitricComponent
+          tag="input"
+          component="radio"
+          type="radio"
+          name={name}
+          value={key}
+          checked={value === o || (!isNil(key) && valueKey === key)}
+          onChange={() => onChange?.(o)}
+          disabled={isDisabled?.(o)}
+        />
+        return renderItem ? renderItem(radio, o) : (
+          <CitricComponent tag="label" component="radio-row" key={key} colorScheme={colorScheme}>
+            {radio}
+            {renderLabel(o)}
+          </CitricComponent>
+        )
+      })
+    }, [options, value, name, colorScheme])
+    return <Column {...props} style={{ gap: '8px', ...style }}>{items}</Column>
+  },
+)

package/src/components/Rating.tsx

@@ -14,6 +14,16 @@ export interface BaseRatingProps {
 
 export type RatingProps = Omit<React.JSX.IntrinsicElements['div'], 'onChange' | 'children'> & BaseRatingProps
 
+/**
+ * Renders a 5 star rating UI. The user can select 1 to 5 stars.
+ * 
+ * @example
+ * ```
+ * const [value, setValue] = useState<RatingValue | undefined>()
+ * return <Rating value={value} setValue={setValue} />
+ * ```
+ * In the example above, `RatingValue` is any integer from 1 to 5.
+ */
 export const Rating = withRef(({ value, onChange, name, ...props }: RatingProps) => (
   <CitricComponent tag="div" component="rating" {...props}>
     <input type="radio" value="1" name={name} checked={value === 5} onChange={() => onChange(5)} />

package/src/components/Select/RichSelect.tsx

@@ -10,204 +10,207 @@ import { ProgressCircular } from '../ProgressCircular'
 import { SimpleSelect } from './SimpleSelect'
 import { SelectProps } from './types'
 
-function _RichSelect<T>({
-  ref,
-  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 element = ref ?? _element
-  const [open, setOpen] = useState(false)
-  const [focused, setFocused] = useState(false)
-  const t = useTranslate(dictionary)
+export const RichSelect = withRef(
+  function RichSelect<T>({
+    ref,
+    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 element = ref ?? _element
+    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)}>{renderLabel(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])
+    const change = useCallback((option: T | undefined) => () => {
+      onChange?.(option)
+      setOpen(false)
+    }, [])
 
-  /* 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()
+    const renderedOptions = useMemo(() => {
+      const items = required ? [] : [<li key="" className="empty" onClick={change(undefined)}>{renderLabel(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>,
+          )
         }
-        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))
+      })
+      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 })
+          }
         }
-        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)
+        /* keyboard and mouse controls */
+        const listenToMouse = (event: Event) => {
+          if (!selectionPanel?.contains(event.target as HTMLElement)) {
+            setOpen(false)
           }
         }
-        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)
+        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)
           }
         }
-        if (event.key === 'Enter') {
-          setTimeout(() => getCurrent()?.click(), 0)
+        // below, we wait 20ms so the same click that opened the select doesn't close it. Removing it will cause problems with selects under
+        // labels.
+        setTimeout(() => document.addEventListener('click', listenToMouse), 20)
+        document.addEventListener('keydown', listenToKeyboard)
+        return () => {
+          document.removeEventListener('click', listenToMouse)
+          document.removeEventListener('keydown', listenToKeyboard)
+          getCurrent()?.classList.remove('focused')
         }
       }
-      // below, we wait 20ms so the same click that opened the select doesn't close it. Removing it will cause problems with selects under
-      // labels.
-      setTimeout(() => document.addEventListener('click', listenToMouse), 20)
-      document.addEventListener('keydown', listenToKeyboard)
-      return () => {
-        document.removeEventListener('click', listenToMouse)
-        document.removeEventListener('keydown', listenToKeyboard)
-        getCurrent()?.classList.remove('focused')
-      }
-    }
-  }, [open])
+    }, [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)
+    /* 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)
+        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)
+          }
         }
-        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)
         }
       }
-      document.addEventListener('click', listenToMouse)
-      document.addEventListener('keydown', listenToKeyboard)
-      return () => {
-        document.removeEventListener('click', listenToMouse)
-        document.removeEventListener('keydown', listenToKeyboard)
-      }
-    }
-  }, [focused])
+    }, [focused])
 
-  useEffect(() => {
-    if (disabled) {
-      setOpen(false)
-      setFocused(false)
-    }
-  }, [disabled])
+    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
+    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}
       >
-        {(renderHeader?.(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>
-  )
-}
+        <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) ?? 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: {
@@ -217,5 +220,3 @@ const dictionary = {
     empty: 'Vazio',
   },
 }
-
-export const RichSelect = withRef(_RichSelect)

package/src/components/Select/SimpleSelect.tsx

@@ -5,69 +5,69 @@ import { CitricComponent } from '../CitricComponent'
 import { ProgressCircular } from '../ProgressCircular'
 import { SelectProps } from './types'
 
-export function _SimpleSelect<T>({
-  ref,
-  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 - (e.target.options.length > options.length ? 1 : 0)
-    onChange?.(selectedIndex >= 0 ? options[selectedIndex] : undefined)
-  }, [options])
+export const SimpleSelect = withRef(
+  function SimpleSelect<T>({
+    ref,
+    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 - (e.target.options.length > options.length ? 1 : 0)
+      onChange?.(selectedIndex >= 0 ? options[selectedIndex] : undefined)
+    }, [options])
 
-  const renderedOptions = useMemo(() => {
-    const items = (!value || !required) ? [<option key="">{renderLabel(undefined)}</option>] : []
-    options.forEach((o) => {
-      const key = renderKey(o)
-      items.push(
-        <option key={key} value={key}>
-          {renderLabel(o)}
-        </option>,
-      )
-    })
-    return items
-  }, [options, value, required])
+    const renderedOptions = useMemo(() => {
+      const items = (!value || !required) ? [<option key="">{renderLabel(undefined)}</option>] : []
+      options.forEach((o) => {
+        const key = renderKey(o)
+        items.push(
+          <option key={key} value={key}>
+            {renderLabel(o)}
+          </option>,
+        )
+      })
+      return items
+    }, [options, value, required])
 
-  return wrap === false ? (
-    <CitricComponent
-      tag="select"
-      ref={ref as MutableRefObject<HTMLSelectElement | null>}
-      required={required}
-      onChange={handleChange}
-      disabled={disabled || loading}
-      component="select"
-      onFocus={onFocus}
-      onBlur={onBlur}
-      value={value ? renderKey(value) : ''}
-    >
-      {renderedOptions}
-    </CitricComponent>
-  ) : (
-    <CitricComponent ref={ref as MutableRefObject<HTMLDivElement | null>} tag="div" component="select" aria-busy={loading} {...props}>
-      <select
-        value={value ? renderKey(value) : undefined}
+    return wrap === false ? (
+      <CitricComponent
+        tag="select"
+        ref={ref as MutableRefObject<HTMLSelectElement | null>}
         required={required}
         onChange={handleChange}
         disabled={disabled || loading}
+        component="select"
         onFocus={onFocus}
         onBlur={onBlur}
+        value={value ? renderKey(value) : ''}
       >
         {renderedOptions}
-      </select>
-      {loading && <ProgressCircular className="loader" size="xs" />}
-    </CitricComponent>
-  )
-}
-
-export const SimpleSelect = withRef(_SimpleSelect)
+      </CitricComponent>
+    ) : (
+      <CitricComponent ref={ref as MutableRefObject<HTMLDivElement | null>} tag="div" component="select" aria-busy={loading} {...props}>
+        <select
+          value={value ? renderKey(value) : undefined}
+          required={required}
+          onChange={handleChange}
+          disabled={disabled || loading}
+          onFocus={onFocus}
+          onBlur={onBlur}
+        >
+          {renderedOptions}
+        </select>
+        {loading && <ProgressCircular className="loader" size="xs" />}
+      </CitricComponent>
+    )
+  },
+)