@stack-spot/portal-components 2.26.0 → 2.27.0

package/src/components/form/SearchInput.tsx

@@ -1,69 +1,69 @@
-import { Box, IconBox, Input } from '@citric/core'
-import { Filter, Times } from '@citric/icons'
-import { FieldAddon, FieldGroup, IconButton } from '@citric/ui'
-import { Dictionary, useTranslate } from '@stack-spot/portal-translate'
-import { debounce } from 'lodash'
-import { useCallback, useState } from 'react'
-
-export const SearchInput = ({
-  searchText,
-  defaultValue,
-  disabled = false,
-  onChange,
-  style,
-  className,
-}: {
-  searchText: string,
-  defaultValue?: string,
-  disabled?: boolean,
-  onChange: (value?: string) => void,
-  style?: React.CSSProperties,
-  className?: string,
-}) => {
-  const [value, setValue] = useState(defaultValue)
-  const runOnChange = useCallback(debounce(onChange, 800), [onChange])
-  const t = useTranslate(dictionary)
-
-  return (
-    <Box sx={{ position: 'relative' }} style={style} className={className}>
-      <FieldGroup>
-        <FieldAddon>
-          <IconBox size="xs" colorIcon="light.700">
-            <Filter />
-          </IconBox>
-        </FieldAddon>
-        <Input
-          value={value}
-          placeholder={searchText}
-          onChange={(e) => {
-            setValue(e.target.value)
-            runOnChange(e.target.value)
-          }}
-          disabled={disabled}
-          maxLength={255}
-        />
-      </FieldGroup>
-      {!!value && (
-        <IconButton
-          sx={{ position: 'absolute', right: '20px', top: '50%', transform: 'translate(50%, -50%)' }}
-          onClick={() => {
-            setValue('')
-            runOnChange('')
-          }}
-          aria-label={t.ariaClearField}
-        >
-          <Times />
-        </IconButton>
-      )}
-    </Box>
-  )
-}
-
-const dictionary = {
-  en: {
-    ariaClearField: 'Clear field',
-  },
-  pt: {
-    ariaClearField: 'Limpar campo',
-  },
-} satisfies Dictionary
+import { Box, IconBox, Input } from '@citric/core'
+import { Filter, Times } from '@citric/icons'
+import { FieldAddon, FieldGroup, IconButton } from '@citric/ui'
+import { Dictionary, useTranslate } from '@stack-spot/portal-translate'
+import { debounce } from 'lodash'
+import { useCallback, useState } from 'react'
+
+export const SearchInput = ({
+  searchText,
+  defaultValue,
+  disabled = false,
+  onChange,
+  style,
+  className,
+}: {
+  searchText: string,
+  defaultValue?: string,
+  disabled?: boolean,
+  onChange: (value?: string) => void,
+  style?: React.CSSProperties,
+  className?: string,
+}) => {
+  const [value, setValue] = useState(defaultValue)
+  const runOnChange = useCallback(debounce(onChange, 800), [onChange])
+  const t = useTranslate(dictionary)
+
+  return (
+    <Box sx={{ position: 'relative' }} style={style} className={className}>
+      <FieldGroup>
+        <FieldAddon>
+          <IconBox size="xs" colorIcon="light.700">
+            <Filter />
+          </IconBox>
+        </FieldAddon>
+        <Input
+          value={value}
+          placeholder={searchText}
+          onChange={(e) => {
+            setValue(e.target.value)
+            runOnChange(e.target.value)
+          }}
+          disabled={disabled}
+          maxLength={255}
+        />
+      </FieldGroup>
+      {!!value && (
+        <IconButton
+          sx={{ position: 'absolute', right: '20px', top: '50%', transform: 'translate(50%, -50%)' }}
+          onClick={() => {
+            setValue('')
+            runOnChange('')
+          }}
+          aria-label={t.ariaClearField}
+        >
+          <Times />
+        </IconButton>
+      )}
+    </Box>
+  )
+}
+
+const dictionary = {
+  en: {
+    ariaClearField: 'Clear field',
+  },
+  pt: {
+    ariaClearField: 'Limpar campo',
+  },
+} satisfies Dictionary

package/src/components/form/Select/CustomSelect.tsx

@@ -1,232 +1,232 @@
-import { IconBox } from '@citric/core'
-import { ChevronDown } from '@citric/icons'
-import { LoadingCircular } from '@citric/ui'
-import { listToClass } from '@stack-spot/portal-theme'
-import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
-import { delay } from '../../../utils/promise'
-import { SelectBox } from './styled'
-import { CustomSelectProps, GenericAccessibleLabel, KeyOfType } from './types'
-import { parseLabel } from './utils'
-
-function getOptionAsValue<Option, T extends KeyOfType<Option, string> | ((o: NonNullable<Option>) => string)>(
-  option: Option,
-  renderer: T | undefined,
-): string {
-  let result: string | undefined
-  if (typeof renderer === 'function') result = option ? renderer(option) : undefined
-  else if (typeof renderer === 'string') result = option[renderer as keyof Option] as string
-  return result ? result : `${option ?? ''}`
-}
-
-function getOptionAsLabel<
-  Option,
-  T extends KeyOfType<Option, GenericAccessibleLabel> | ((o: NonNullable<Option>) => GenericAccessibleLabel)
->(
-  option: Option,
-  renderer: T | undefined,
-): GenericAccessibleLabel {
-  let result: GenericAccessibleLabel | undefined
-  if (typeof renderer === 'function') result = option ? renderer(option) : undefined
-  else if (typeof renderer === 'string') result = option[renderer as keyof Option] as GenericAccessibleLabel
-  return result ? result : parseLabel(`${option ?? ''}`)
-}
-
-const FakeOption = (
-  { value, label, onChange }: { value: string, label: React.ReactElement, onChange: (event: { target: { value: string } }) => void },
-) => (
-  <li className="option" onClick={() => onChange({ target: { value } })}>
-    {label}
-  </li>
-)
-
-/**
- * Renders a Select component using the Citric Design System.
- * 
- * The styled version of the select component is rendered on top of the default select from the browser. Visual users will use the Citric
- * version of a Select, but blind users, who interacts with the keyboard, will use the default browser select instead, which is already
- * highly optimized for accessibility.
- * 
- * The CustomSelect lets you customize how each option and the selected value are rendered. To do so, use the prop `renderLabel` and
- * `emptyOption`.
- * 
- * If you don't need fully customized labels, check the more simple components: `DetailedSelect` and `Select`.
- * 
- * The CustomSelect expects a {@link GenericAccessibleLabel} to create labels.
- * 
- * Tips:
- * - This is a controlled field. You can't use it any other way. If you're using it with react-hook-form, you need to wrap it under the
- * component `<Controller>` from the same library.
- * - `value` is required and must be of the same type of an item of the array of options. `value` is only optional if `emptyOption` is
- * provided, in this case, an empty option is rendered and the value is undefined when it's selected.
- * - A consequence of the previous rule is that you can't have an empty selection if you don't set a value for `emptyOption`. This
- * component must work exactly like the browser's `select`, so this behavior is intended.
- * - If `renderLabel` or `renderValue` are not provided, this will use the `toString` method of the object.
- * 
- * @example
- * options as an object array
- * ```
- * const options = ['option 1', 'option 2', 'option 3']
- * 
- * function renderCustomLabel(option: string) {
- *   return {
- *     // this is how the option will be rendered in the list
- *     option: (
- *       <div style={{ display: flex, flexDirection: 'row', gap: '5px' }}>
- *         <img src="/my-image.png" width="40px" height="40px" />
- *         <p>An option called {option}</p>
- *       </div>
- *     ),
- *     // this is how the option will be rendered inside the input, when it's the value currently selected.
- *     selected: <p>{option}</p>,
- *     // this a string representation of the option: used for accessibility. This should contain the same information as `option`.
- *     text: `An option called ${option}`,
- *   )
- * }
- * 
- * const MyComponent = {
- *   const [value, setValue] = useState(options[0])
- *   return <CustomSelect options={options} value={value} onChange={setValue} renderLabel={renderCustomLabel} />
- * }
- * ```
- * @example
- * options as an object array
- * ```
- * const options = [{ id: 1, name: 'John', age: 34 }, { id: 2, name: 'Marcia', age: 28 }, { id: 3, name: 'Angeline', age: 58 }]
- * 
- * function renderCustomLabel(option: (typeof options)[number]) {
- *   return {
- *     // this is how the option will be rendered in the list
- *     option: (
- *       <div style={{ display: flex, flexDirection: 'row', gap: '5px' }}>
- *         <img src="/my-image.png" width="40px" height="40px" />
- *         <p>{option.name}, aged {option.age}</p>
- *       </div>
- *     ),
- *     // this is how the option will be rendered inside the input, when it's the value currently selected.
- *     selected: <p>{option}</p>,
- *     // this a string representation of the option: used for accessibility. This should contain the same information as `option`.
- *     text: `${option.name}, aged ${option.age}`,
- *   )
- * }
- * 
- * const MyComponent = {
- *   const [value, setValue] = useState(options[0])
- *   // below, renderValue could be `o => o.id`
- *   return <CustomSelect options={options} value={value} onChange={setValue} renderValue="id" renderLabel={renderCustomLabel} />
- * }
- * ```
- * @param props the component props: {@link CustomSelectProps}.
- */
-export function CustomSelect<T>({
-  onChange, options, value, emptyOption, renderLabel, renderValue, maxItems = 6, onFocus, onBlur, style, className, isLoading, disabled,
-  height = '42px', ...props
-}: CustomSelectProps<T>) {
-  const [open, setOpen] = useState(false)
-  const [focused, setFocused] = useState(false)
-  const fakeSelectRef = useRef<HTMLDivElement>(null)
-  const listHeight = useRef(0)
-  const isDisabled = disabled || isLoading
-  const isMeasuring = useRef(false)
-
-  const onChangeOption = useCallback((event: { target: { value: string } }) => {
-    const value = options?.find(o => getOptionAsValue(o, renderValue) === event.target.value)
-    onChange(value!)
-    setOpen(false)
-  }, [options])
-
-  const onClickOutside = useCallback((event: MouseEvent) => {
-    if (fakeSelectRef.current && !fakeSelectRef.current.contains(event.target as Node)) setOpen(false)
-  }, [])
-
-  const [htmlOptions, fakeOptions] = useMemo(
-    () => (options ?? []).reduce<[React.ReactElement[], React.ReactElement[]]>(([opts, fake], o) => {
-      const id = getOptionAsValue(o, renderValue)
-      const label = getOptionAsLabel(o, renderLabel)
-      return [
-        [...opts, <option key={id} value={id} selected={value === id}>{label.text}</option>],
-        [...fake, <FakeOption key={id} value={id} label={label.option} onChange={onChangeOption} />],
-      ]
-    }, [[], []]),
-    [options, value],
-  )
-
-  function getCurrentValue() {
-    return value === undefined ? '' : getOptionAsValue(value, renderValue)
-  }
-
-  function getCurrentLabel() {
-    return value === undefined ? emptyOption : getOptionAsLabel(value, renderLabel)
-  }
-
-  useEffect(() => {
-    const detach = () => document.removeEventListener('mousedown', onClickOutside)
-    if (open) document.addEventListener('mousedown', onClickOutside)
-    else detach()
-    return detach 
-  }, [open])
-
-  useEffect(() => {
-    async function measure() {
-      // semaphore for controlling concurrence
-      if (isMeasuring.current) return
-      isMeasuring.current = true
-      const list = fakeSelectRef.current?.querySelector('.options')
-      if (!list) return
-      list.setAttribute('inert', '')
-      list.setAttribute('style', 'height: auto')
-      await delay(0)
-      listHeight.current = list.clientHeight
-      await delay(0)
-      list.setAttribute('style', `height: ${open ? listHeight.current : 0}`)
-      list.removeAttribute('inert')
-      isMeasuring.current = false
-    }
-    measure()
-  }, [options, fakeSelectRef.current])
-
-  // replicates the original select effect of the browser to select the first option. This is necessary because we use the default
-  // select element for accessibility, the behavior must not differ.
-  useEffect(() => {
-    if (!value && !emptyOption && options?.length) {
-      onChange(options[0])
-    }
-  }, [options])
-
-  return (
-    <SelectBox style={style} className={className} $maxItems={maxItems} $inputHeight={height}>
-      { /* Screen readers can use the select component from the browser instead of the highly styled component we show. */ }
-      <select
-        {...props}
-        value={getCurrentValue()}
-        onChange={onChangeOption}
-        onFocus={(ev) => {
-          setFocused(true)
-          onFocus?.(ev)
-        }}
-        onBlur={(ev) => {
-          setFocused(false)
-          onBlur?.(ev)
-        }}
-        disabled={isDisabled}
-        aria-busy={isLoading}
-      >
-        {emptyOption === undefined ? null : <option value="" selected={!value}>{emptyOption.text}</option>}
-        {htmlOptions}
-      </select>
-      <div
-        ref={fakeSelectRef}
-        className={listToClass(['fake-select', open && 'open', focused && 'focused', isDisabled && 'disabled'])}
-        aria-hidden
-      >
-        <div className="current-value" onClick={isDisabled ? undefined : () => setOpen(!open)}>
-          {getCurrentLabel()?.selected || getCurrentLabel()?.option || <div></div>}
-          {isLoading ? <LoadingCircular size="sm" /> : <IconBox className="arrow"><ChevronDown /></IconBox>}
-        </div>
-        <ul className="options" style={{ height: open ? listHeight.current : 0 }}>
-          {emptyOption === undefined ? null : <FakeOption value="" label={emptyOption.option} onChange={onChangeOption} />}
-          {fakeOptions}
-        </ul>
-      </div>
-    </SelectBox>
-  )
-}
+import { IconBox } from '@citric/core'
+import { ChevronDown } from '@citric/icons'
+import { LoadingCircular } from '@citric/ui'
+import { listToClass } from '@stack-spot/portal-theme'
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
+import { delay } from '../../../utils/promise'
+import { SelectBox } from './styled'
+import { CustomSelectProps, GenericAccessibleLabel, KeyOfType } from './types'
+import { parseLabel } from './utils'
+
+function getOptionAsValue<Option, T extends KeyOfType<Option, string> | ((o: NonNullable<Option>) => string)>(
+  option: Option,
+  renderer: T | undefined,
+): string {
+  let result: string | undefined
+  if (typeof renderer === 'function') result = option ? renderer(option) : undefined
+  else if (typeof renderer === 'string') result = option[renderer as keyof Option] as string
+  return result ? result : `${option ?? ''}`
+}
+
+function getOptionAsLabel<
+  Option,
+  T extends KeyOfType<Option, GenericAccessibleLabel> | ((o: NonNullable<Option>) => GenericAccessibleLabel)
+>(
+  option: Option,
+  renderer: T | undefined,
+): GenericAccessibleLabel {
+  let result: GenericAccessibleLabel | undefined
+  if (typeof renderer === 'function') result = option ? renderer(option) : undefined
+  else if (typeof renderer === 'string') result = option[renderer as keyof Option] as GenericAccessibleLabel
+  return result ? result : parseLabel(`${option ?? ''}`)
+}
+
+const FakeOption = (
+  { value, label, onChange }: { value: string, label: React.ReactElement, onChange: (event: { target: { value: string } }) => void },
+) => (
+  <li className="option" onClick={() => onChange({ target: { value } })}>
+    {label}
+  </li>
+)
+
+/**
+ * Renders a Select component using the Citric Design System.
+ * 
+ * The styled version of the select component is rendered on top of the default select from the browser. Visual users will use the Citric
+ * version of a Select, but blind users, who interacts with the keyboard, will use the default browser select instead, which is already
+ * highly optimized for accessibility.
+ * 
+ * The CustomSelect lets you customize how each option and the selected value are rendered. To do so, use the prop `renderLabel` and
+ * `emptyOption`.
+ * 
+ * If you don't need fully customized labels, check the more simple components: `DetailedSelect` and `Select`.
+ * 
+ * The CustomSelect expects a {@link GenericAccessibleLabel} to create labels.
+ * 
+ * Tips:
+ * - This is a controlled field. You can't use it any other way. If you're using it with react-hook-form, you need to wrap it under the
+ * component `<Controller>` from the same library.
+ * - `value` is required and must be of the same type of an item of the array of options. `value` is only optional if `emptyOption` is
+ * provided, in this case, an empty option is rendered and the value is undefined when it's selected.
+ * - A consequence of the previous rule is that you can't have an empty selection if you don't set a value for `emptyOption`. This
+ * component must work exactly like the browser's `select`, so this behavior is intended.
+ * - If `renderLabel` or `renderValue` are not provided, this will use the `toString` method of the object.
+ * 
+ * @example
+ * options as an object array
+ * ```
+ * const options = ['option 1', 'option 2', 'option 3']
+ * 
+ * function renderCustomLabel(option: string) {
+ *   return {
+ *     // this is how the option will be rendered in the list
+ *     option: (
+ *       <div style={{ display: flex, flexDirection: 'row', gap: '5px' }}>
+ *         <img src="/my-image.png" width="40px" height="40px" />
+ *         <p>An option called {option}</p>
+ *       </div>
+ *     ),
+ *     // this is how the option will be rendered inside the input, when it's the value currently selected.
+ *     selected: <p>{option}</p>,
+ *     // this a string representation of the option: used for accessibility. This should contain the same information as `option`.
+ *     text: `An option called ${option}`,
+ *   )
+ * }
+ * 
+ * const MyComponent = {
+ *   const [value, setValue] = useState(options[0])
+ *   return <CustomSelect options={options} value={value} onChange={setValue} renderLabel={renderCustomLabel} />
+ * }
+ * ```
+ * @example
+ * options as an object array
+ * ```
+ * const options = [{ id: 1, name: 'John', age: 34 }, { id: 2, name: 'Marcia', age: 28 }, { id: 3, name: 'Angeline', age: 58 }]
+ * 
+ * function renderCustomLabel(option: (typeof options)[number]) {
+ *   return {
+ *     // this is how the option will be rendered in the list
+ *     option: (
+ *       <div style={{ display: flex, flexDirection: 'row', gap: '5px' }}>
+ *         <img src="/my-image.png" width="40px" height="40px" />
+ *         <p>{option.name}, aged {option.age}</p>
+ *       </div>
+ *     ),
+ *     // this is how the option will be rendered inside the input, when it's the value currently selected.
+ *     selected: <p>{option}</p>,
+ *     // this a string representation of the option: used for accessibility. This should contain the same information as `option`.
+ *     text: `${option.name}, aged ${option.age}`,
+ *   )
+ * }
+ * 
+ * const MyComponent = {
+ *   const [value, setValue] = useState(options[0])
+ *   // below, renderValue could be `o => o.id`
+ *   return <CustomSelect options={options} value={value} onChange={setValue} renderValue="id" renderLabel={renderCustomLabel} />
+ * }
+ * ```
+ * @param props the component props: {@link CustomSelectProps}.
+ */
+export function CustomSelect<T>({
+  onChange, options, value, emptyOption, renderLabel, renderValue, maxItems = 6, onFocus, onBlur, style, className, isLoading, disabled,
+  height = '42px', ...props
+}: CustomSelectProps<T>) {
+  const [open, setOpen] = useState(false)
+  const [focused, setFocused] = useState(false)
+  const fakeSelectRef = useRef<HTMLDivElement>(null)
+  const listHeight = useRef(0)
+  const isDisabled = disabled || isLoading
+  const isMeasuring = useRef(false)
+
+  const onChangeOption = useCallback((event: { target: { value: string } }) => {
+    const value = options?.find(o => getOptionAsValue(o, renderValue) === event.target.value)
+    onChange(value!)
+    setOpen(false)
+  }, [options])
+
+  const onClickOutside = useCallback((event: MouseEvent) => {
+    if (fakeSelectRef.current && !fakeSelectRef.current.contains(event.target as Node)) setOpen(false)
+  }, [])
+
+  const [htmlOptions, fakeOptions] = useMemo(
+    () => (options ?? []).reduce<[React.ReactElement[], React.ReactElement[]]>(([opts, fake], o) => {
+      const id = getOptionAsValue(o, renderValue)
+      const label = getOptionAsLabel(o, renderLabel)
+      return [
+        [...opts, <option key={id} value={id} selected={value === id}>{label.text}</option>],
+        [...fake, <FakeOption key={id} value={id} label={label.option} onChange={onChangeOption} />],
+      ]
+    }, [[], []]),
+    [options, value],
+  )
+
+  function getCurrentValue() {
+    return value === undefined ? '' : getOptionAsValue(value, renderValue)
+  }
+
+  function getCurrentLabel() {
+    return value === undefined ? emptyOption : getOptionAsLabel(value, renderLabel)
+  }
+
+  useEffect(() => {
+    const detach = () => document.removeEventListener('mousedown', onClickOutside)
+    if (open) document.addEventListener('mousedown', onClickOutside)
+    else detach()
+    return detach 
+  }, [open])
+
+  useEffect(() => {
+    async function measure() {
+      // semaphore for controlling concurrence
+      if (isMeasuring.current) return
+      isMeasuring.current = true
+      const list = fakeSelectRef.current?.querySelector('.options')
+      if (!list) return
+      list.setAttribute('inert', '')
+      list.setAttribute('style', 'height: auto')
+      await delay(0)
+      listHeight.current = list.clientHeight
+      await delay(0)
+      list.setAttribute('style', `height: ${open ? listHeight.current : 0}`)
+      list.removeAttribute('inert')
+      isMeasuring.current = false
+    }
+    measure()
+  }, [options, fakeSelectRef.current])
+
+  // replicates the original select effect of the browser to select the first option. This is necessary because we use the default
+  // select element for accessibility, the behavior must not differ.
+  useEffect(() => {
+    if (!value && !emptyOption && options?.length) {
+      onChange(options[0])
+    }
+  }, [options])
+
+  return (
+    <SelectBox style={style} className={className} $maxItems={maxItems} $inputHeight={height}>
+      { /* Screen readers can use the select component from the browser instead of the highly styled component we show. */ }
+      <select
+        {...props}
+        value={getCurrentValue()}
+        onChange={onChangeOption}
+        onFocus={(ev) => {
+          setFocused(true)
+          onFocus?.(ev)
+        }}
+        onBlur={(ev) => {
+          setFocused(false)
+          onBlur?.(ev)
+        }}
+        disabled={isDisabled}
+        aria-busy={isLoading}
+      >
+        {emptyOption === undefined ? null : <option value="" selected={!value}>{emptyOption.text}</option>}
+        {htmlOptions}
+      </select>
+      <div
+        ref={fakeSelectRef}
+        className={listToClass(['fake-select', open && 'open', focused && 'focused', isDisabled && 'disabled'])}
+        aria-hidden
+      >
+        <div className="current-value" onClick={isDisabled ? undefined : () => setOpen(!open)}>
+          {getCurrentLabel()?.selected || getCurrentLabel()?.option || <div></div>}
+          {isLoading ? <LoadingCircular size="sm" /> : <IconBox className="arrow"><ChevronDown /></IconBox>}
+        </div>
+        <ul className="options" style={{ height: open ? listHeight.current : 0 }}>
+          {emptyOption === undefined ? null : <FakeOption value="" label={emptyOption.option} onChange={onChangeOption} />}
+          {fakeOptions}
+        </ul>
+      </div>
+    </SelectBox>
+  )
+}