@stack-spot/citric-react 0.22.0 → 0.24.0

package/src/components/FormGroup.tsx

@@ -26,6 +26,18 @@ export interface BaseFormGroupProps {
 
 export type FormGroupProps = React.JSX.IntrinsicElements['div'] & BaseFormGroupProps
 
+/**
+ * A form group renders everything a field in a form needs: the input, its label, a tooltip (help), an error and a remark (warning).
+ * 
+ * Labels, errors, tooltips and warnings are only rendered when they're strings with at least one character.
+ * 
+ * @example
+ * ```
+ * <FormGroup label="Birth Date" help="The date when you were born" error="The date you typed is invalid!">
+ *   <Input type="date" />
+ * </FormGroup>
+ * ```
+ */
 export const FormGroup = withRef(({ error, help, label, warning, className, children, ...props }: FormGroupProps) => (
   <CitricComponent tag="div" component="form-group" className={listToClass([className, error && 'error'])} {...props}>
     <label>

package/src/components/IconBox.tsx

@@ -59,41 +59,72 @@ export interface BaseIconBoxProps<T extends IconBoxTag, G extends IconGroup> ext
 
 export type IconBoxProps<T extends IconBoxTag, G extends IconGroup> = Omit<HTMLTag[T], 'children'> & BaseIconBoxProps<T, G>
 
-function _IconBox<T extends IconBoxTag = 'i', G extends IconGroup = 'outline'>(
-  { group, icon, tag, appearance, size, className, analytics, onClick, feedback, ...props }: IconBoxProps<T, G>,
-) {
-  const citric = useCitricController()
+/**
+ * Renders a wrapper for an icon. The icon must specified by the properties "icon" and "group", this component accepts no children.
+ * 
+ * If you don't need the icon to be rendered within a box, consider using the component "Icon" directly.
+ * 
+ * Hover and focus effects are applied if the IconBox is focusable.
+ * 
+ * @example
+ * ```
+ * <IconBox icon="Search" colorScheme="primary" />
+ * ```
+ */
+export const IconBox = withRef(
+  function IconBox<T extends IconBoxTag = 'i', G extends IconGroup = 'outline'>(
+    { group, icon, tag, appearance, size, className, analytics, onClick, feedback, ...props }: IconBoxProps<T, G>,
+  ) {
+    props['aria-label'] ||= props.title // accessibility
+    const citric = useCitricController()
 
-  function handleClick(e: React.MouseEvent<any>) {
-    onClick?.(e)
-    if (tag === 'button') citric?.onClickButton?.(e, analytics ?? false)
-    else if (tag === 'a') citric?.onClickLink?.(e, analytics ?? false)
-  }
+    function handleClick(e: React.MouseEvent<any>) {
+      onClick?.(e)
+      if (tag === 'button') citric?.onClickButton?.(e, analytics ?? false)
+      else if (tag === 'a') citric?.onClickLink?.(e, analytics ?? false)
+    }
 
-  return <CitricComponent
-    tag={(tag || 'i') as any}
-    component="icon-box"
-    className={listToClass(['citric-icon', group || 'outline', icon, appearance, size, className])}
-    data-feedback={feedback || undefined}
-    onClick={['button', 'a'].includes(tag ?? '') ? handleClick : onClick}
-    {...props}
-  />
-}
+    return <CitricComponent
+      tag={(tag || 'i') as any}
+      component="icon-box"
+      className={listToClass(['citric-icon', group || 'outline', icon, appearance, size, className])}
+      data-feedback={feedback || undefined}
+      onClick={['button', 'a'].includes(tag ?? '') ? handleClick : onClick}
+      {...props}
+    />
+  },
+)
 
 /**
- * Shortcut to `<IconBox tag="button" />`
+ * A shortcut for `<IconBox tag="button">`.
+ * 
+ * Whenever a button is clicked, the function `onClickButton` of the nearest CitricController is called with the event and the value of the
+ * prop `analytics`.
+ * 
+ * @example
+ * ```
+ * <IconButton icon="Search" />
+ * ```
  */
-function _IconButton<G extends IconGroup = 'outline'>({ type, ...props }: Omit<IconBoxProps<'button', G>, 'tag'>) {
-  return <IconBox {...props} tag="button" type={type || 'button' } />
-}
+export const IconButton = withRef(
+  function IconButton<G extends IconGroup = 'outline'>({ type, ...props }: Omit<IconBoxProps<'button', G>, 'tag'>) {
+    return <IconBox {...props} tag="button" type={type || 'button' } />
+  },
+)
 
 /**
- * Shortcut to `<IconBox tag="a" />`
+ * A shortcut for `<IconBox tag="a">`.
+ * 
+ * Whenever a link is clicked, the function `onClickLink` of the nearest CitricController is called with the event and the value of the
+ * prop `analytics`.
+ * 
+ * @example
+ * ```
+ * <IconLink icon="Search" href="#" />
+ * ```
  */
-function _IconLink<G extends IconGroup = 'outline'>(props: Omit<IconBoxProps<'a', G>, 'tag'>) {
-  return <IconBox {...props} tag="a" />
-}
-
-export const IconBox = withRef(_IconBox)
-export const IconButton = withRef(_IconButton)
-export const IconLink = withRef(_IconLink)
+export const IconLink = withRef(
+  function IconLink<G extends IconGroup = 'outline'>(props: Omit<IconBoxProps<'a', G>, 'tag'>) {
+    return <IconBox {...props} tag="a" />
+  },
+)

package/src/components/ImageBox.tsx

@@ -49,41 +49,71 @@ export interface BaseImageBoxProps<T extends ImageBoxTag> extends WithColorPalet
 
 export type ImageBoxProps<T extends ImageBoxTag> = HTMLTag[T] & BaseImageBoxProps<T>
 
-function _ImageBox<T extends ImageBoxTag = 'div'>(
-  { tag, appearance, size, className, analytics, onClick, feedback, ...props }: ImageBoxProps<T>,
-) {
-  const citric = useCitricController()
+/**
+ * Renders a wrapper for its child (normally an image). The image will be resized and cropped to fit the container. The image is not cropped
+ * if the property "feedback" is set.
+ * 
+ * Hover and focus effects are applied if the ImageBox is focusable.
+ * 
+ * @example
+ * ```
+ * <ImageBox><img src="https://images.com/myimage.png" /></ImageBox>
+ * ```
+ */
+export const ImageBox = withRef(
+  function ImageBox<T extends ImageBoxTag = 'div'>(
+    { tag, appearance, size, className, analytics, onClick, feedback, ...props }: ImageBoxProps<T>,
+  ) {
+    props['aria-label'] ||= props.title // accessibility
+    const citric = useCitricController()
 
-  function handleClick(e: React.MouseEvent<any>) {
-    onClick?.(e)
-    if (tag === 'button') citric?.onClickButton?.(e, analytics ?? false)
-    else if (tag === 'a') citric?.onClickLink?.(e, analytics ?? false)
-  }
+    function handleClick(e: React.MouseEvent<any>) {
+      onClick?.(e)
+      if (tag === 'button') citric?.onClickButton?.(e, analytics ?? false)
+      else if (tag === 'a') citric?.onClickLink?.(e, analytics ?? false)
+    }
 
-  return <CitricComponent
-    tag={(tag || 'i') as any}
-    component="icon-box"
-    className={listToClass([appearance, size, className])}
-    data-feedback={feedback || undefined}
-    onClick={['button', 'a'].includes(tag ?? '') ? handleClick : onClick}
-    {...props}
-  />
-}
+    return <CitricComponent
+      tag={(tag || 'i') as any}
+      component="icon-box"
+      className={listToClass([appearance, size, className])}
+      data-feedback={feedback || undefined}
+      onClick={['button', 'a'].includes(tag ?? '') ? handleClick : onClick}
+      {...props}
+    />
+  },
+)
 
 /**
- * Shortcut to `<ImageBox tag="button" />`
+ * A shortcut for `<ImageBox tag="button">`.
+ * 
+ * Whenever a button is clicked, the function `onClickButton` of the nearest CitricController is called with the event and the value of the
+ * prop `analytics`.
+ * 
+ * @example
+ * ```
+ * <ImageButton><img src="https://images.com/myimage.png" /></ImageButton>
+ * ```
  */
-function _ImageButton(props: Omit<ImageBoxProps<'button'>, 'tag'>) {
-  return <ImageBox {...props} tag="button" type={props.type || 'button'} />
-}
+export const ImageButton = withRef(
+  function ImageButton(props: Omit<ImageBoxProps<'button'>, 'tag'>) {
+    return <ImageBox {...props} tag="button" type={props.type || 'button'} />
+  },
+)
 
 /**
- * Shortcut to `<ImageBox tag="a" />`
+ * A shortcut for `<ImageBox tag="a">`.
+ * 
+ * Whenever a link is clicked, the function `onClickLink` of the nearest CitricController is called with the event and the value of the
+ * prop `analytics`.
+ * 
+ * @example
+ * ```
+ * <ImageLink href="#"><img src="https://images.com/myimage.png" /></ImageButton>
+ * ```
  */
-function _ImageLink(props: Omit<ImageBoxProps<'a'>, 'tag'>) {
-  return <ImageBox {...props} tag="a" />
-}
-
-export const ImageBox = withRef(_ImageBox)
-export const ImageButton = withRef(_ImageButton)
-export const ImageLink = withRef(_ImageLink)
+export const ImageLink = withRef(
+  function ImageLink(props: Omit<ImageBoxProps<'a'>, 'tag'>) {
+    return <ImageBox {...props} tag="a" />
+  },
+)

package/src/components/ImageWithFallback.tsx

@@ -5,12 +5,30 @@ import { getStyleFromProps } from '../utils/css'
 import { Skeleton } from './Skeleton'
 
 export interface BaseImageWithFallbackProps extends Pick<WithStyleShortcuts, 'w' | 'h' | 'radius' | 'bg'> {
+  /**
+   * The react element to fallback to if the image can't be rendered.
+   */
   fallback: React.ReactNode,
+  /**
+   * Whether or not to show a skeleton when the image is still loading.
+   * @default false
+   */
   showLoading?: boolean,
 }
 
 export type ImageWithFallbackProps = JSX.IntrinsicElements['img'] & BaseImageWithFallbackProps
 
+/**
+ * Attempts to render an image. If it succeeds, the image is displayed, otherwise, a fallback is rendered.
+ * 
+ * This is very useful if the value of "src" may be empty or if it may be broken. Instead of rendering nothing or the default browser error,
+ * it renders the fallback passed as parameter.
+ * 
+ * @example
+ * ```
+ * <ImageWithFallback src={item.image} fallback={<Icon icon="Agent" />} />
+ * ```
+ */
 export const ImageWithFallback = (
   { onLoad, onError, className, style: ogStyle, fallback, showLoading, w, h, radius, bg, ...props }: ImageWithFallbackProps,
 ) => {

package/src/components/Input.tsx

@@ -17,19 +17,33 @@ export interface BaseInputProps<T extends SupportedInputType> extends WithColorS
 export type InputProps<T extends SupportedInputType = 'text'> = 
   ControlledInput & BaseInputProps<T> & { type?: T }
 
-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)
+/**
+ * Renders a input.
+ * 
+ * Attention: "onChange" doesn't receive an event, instead, it receives the new value of the input: a string, unless "type" is "number",
+ * in this case, it receives a number.
+ * 
+ * @example
+ * 
+ * ```
+ * const [value, setValue] = useState('')
+ * 
+ * return <Input value={value} onChange={setValue} />
+ * ```
+ */
+export const Input = withRef(
+  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} />
-}
-
-export const Input = withRef(_Input)
+    return <CitricComponent tag="input" component="input" type={type} value={value} onChange={handleChange} {...props} />
+  },
+)

package/src/components/Link.tsx

@@ -23,6 +23,12 @@ export interface BaseLinkProps extends WithColor {
 
 export type LinkProps = React.JSX.IntrinsicElements['a'] & BaseLinkProps
 
+/**
+ * Renders an html anchor by default, the actual component to render may be set on a CitricController, through the function `renderLink`.
+ * 
+ * Whenever a link is clicked, the function `onClickLink` of the nearest CitricController is called with the event and the value of the
+ * prop `analytics`.
+ */
 export const Link = withRef(({ appearance, color, style, className, children, onClick, analytics, ...props }: LinkProps) => {
   const citric = useCitricController()
   const linkProps = {

package/src/components/MenuOverlay/index.tsx

@@ -5,6 +5,26 @@ import { Overlay } from '../Overlay'
 import { Menu } from './Menu'
 import { MenuOverlayProps } from './types'
 
+/**
+ * Creates a menu overlay for its child element. Whenever the child element is clicked, the menu appears. Closing the menu is also handled
+ * by this component.
+ * 
+ * The menu is defined by the property "items" and can contain sections and sub menus.
+ * 
+ * If no child is provided, a button with the vertical ellipsis icon is rendered.
+ * 
+ * @example
+ * 
+ * ```
+ * const items: MenuItem[] = useMemo([
+ *   { label: 'View', href: `/resource/${id}` },
+ *   { label: 'Edit', onClick: () => editResource(id) },
+ *   { label: 'Remove', onClick: () => removeResource(id), style: { color: theme.color.danger[500] } },
+ * ], [id])
+ * 
+ * return <MenuOverlay items={items}><IconButton icon="Plus" /></MenuOverlay>
+ * ```
+ */
 export const MenuOverlay = ({
   id, items, appearance, bgLevel, header, roundedItems, showBorders, showShadows, spaced, menuClass, menuStyle, children, ...props
 }: MenuOverlayProps) => {

package/src/components/Overlay/index.tsx

@@ -21,6 +21,23 @@ const arbitraryRenderTime = 20
  * hidden by the scroll.
  * TODO: use React Portal to implement overlays. The current implementation will lose every React context in the tree.
  */
+
+/**
+ * Creates an overlay for the child component. The overlay can be any React element. The overlay can be triggered by "click" or "hover"
+ * (default).
+ * 
+ * @example
+ * 
+ * ```
+ * const overlay = <Card>Hey, this is my overlay!</Card>
+ * 
+ * return (
+ *   <Overlay content={overlay} attributes={{ style: { margin: '20px' } }}>
+ *     <Button>Hover to see the overlay</Button>
+ *   </Overlay>
+ * )
+ * ```
+ */
 export function Overlay<T extends keyof HTMLTag>({
   tag,
   children,

package/src/components/Pagination.tsx

@@ -4,6 +4,17 @@ import { withRef } from '../utils/react'
 import { CitricComponent } from './CitricComponent'
 import { IconButton } from './IconBox'
 
+export interface PaginationValue {
+  /**
+   * The first page is 1. If "0" is provided, it will be treated as if it was "1".
+   */
+  page: number,
+  /**
+   * The current number of items in a page.
+   */
+  size: number,
+}
+
 export interface BasePaginationProps {
   /**
    * The options for the page size.
@@ -16,60 +27,72 @@ export interface BasePaginationProps {
    */
   totalPages: number,
   /**
-   * The first page is 1. If "0" is provided, it will be treated as if it was "1".
+   * The current page and page size.
    */
-  page: number,
-  /**
-   * The current number of items in a page.
-   */
-  pageSize: number,
+  value: PaginationValue,
   /**
    * Function to run whenever the page size or current page changes.
    */
-  onChange: (page: number, size: number) => void,
+  onChange: (value: PaginationValue) => void,
 }
 
 export type PaginationProps = Omit<React.JSX.IntrinsicElements['div'], 'onChange'> & BasePaginationProps
 
+/**
+ * Renders a pagination UI, letting the user chose one among multiple pages. This is generally rendered at the bottom of a table.
+ * 
+ * @example
+ * ```
+ * const [pageData, setPageData] = useState({ page: 1, size: 10 })
+ * return <Pagination
+ *   value={pageData}
+ *   totalPages={50}
+ *   onChange={setPageData}
+ * />
+ * ```
+ */
 export const Pagination = withRef((
-  { pageSizeOptions = [10, 20, 30], pageSize, totalPages, page, onChange, ...props }: PaginationProps,
+  { pageSizeOptions = [10, 20, 30], totalPages, value, onChange, ...props }: PaginationProps,
 ) => {
   const t = useTranslate(dictionary)
-  const sizeOptions = useMemo(() => pageSizeOptions.map(o => <option key={o} selected={pageSize === o}>{o}</option>), [pageSizeOptions])
+  const sizeOptions = useMemo(
+    () => pageSizeOptions.map(o => <option key={o} selected={value.size === o}>{o}</option>),
+    [pageSizeOptions],
+  )
   const pageOptions = useMemo(() => {
     const options: React.ReactElement[] = []
     for (let i = 1; i <= totalPages; i++) {
-      options.push(<option key={i} value={i} selected={page === i}>{i}</option>)
+      options.push(<option key={i} value={i} selected={value.page === i}>{i}</option>)
     }
     return options
-  }, [page, totalPages])
+  }, [value.page, totalPages])
 
   return (
     <CitricComponent tag="div" component="pagination" {...props}>
       <div className="page-size">
         <label>
           {t.itemsPerPage}:
-          <select name="itemsPerPage" onChange={e => onChange(page, parseInt(e.target.value))}>{sizeOptions}</select>
+          <select name="itemsPerPage" onChange={e => onChange({ page: value.page, size: parseInt(e.target.value) })}>{sizeOptions}</select>
         </label>
       </div>
       <div className="page-number">
         <label>
-          <select name="page" onChange={e => onChange(parseInt(e.target.value), pageSize)}>{pageOptions}</select>
+          <select name="page" onChange={e => onChange({ page: parseInt(e.target.value), size: value.size })}>{pageOptions}</select>
         </label>
         {totalPages > 1 ? interpolate(t.ofTotalPlural, totalPages) : t.ofTotalSingular}
         <IconButton
           icon="ChevronLeft"
           aria-label="previous"
           title="previous"
-          disabled={page === 1}
-          onClick={() => onChange(page - 1, pageSize)}
+          disabled={value.page === 1}
+          onClick={() => onChange({ page: value.page - 1, size: value.size })}
         />
         <IconButton
           icon="ChevronRight"
           aria-label="next"
           title="next"
-          disabled={page === totalPages}
-          onClick={() => onChange(page + 1, pageSize)}
+          disabled={value.page === totalPages}
+          onClick={() => onChange({ page: value.page + 1, size: value.size })}
         />
       </div>
     </CitricComponent>

package/src/components/ProgressBar.tsx

@@ -20,6 +20,20 @@ export interface BaseProgressBarProps extends WithColorScheme, WithColorPalette
 
 export type ProgressBarProps = React.JSX.IntrinsicElements['div'] & BaseProgressBarProps
 
+/**
+ * Shows a progress bar. This can indicate a loading state or the progress of a task. When "progress" is not set, the bar is animated,
+ * indicating a busy state.
+ * 
+ * @example
+ * A simple loading with a Progress Bar.
+ * ```
+ * <ProgressBar />
+ * ```
+ * A Progress Bar that is 50% complete.
+ * ```
+ * <ProgressBar progress={50} />
+ * ```
+ */
 export const ProgressBar = withRef(({ progress, speed, style, className, ...props }: ProgressBarProps) =>
   <CitricComponent
     tag="div"

package/src/components/ProgressCircular.tsx

@@ -20,6 +20,20 @@ export interface BaseProgressCircularProps extends WithColorScheme, WithColorPal
 
 export type ProgressCircularProps = React.JSX.IntrinsicElements['div'] & BaseProgressCircularProps
 
+/**
+ * Shows a circular progress. This can indicate a loading state (spinner) or the progress of a task. When "progress" is not set, the
+ * spinner is animated, indicating a busy state.
+ * 
+ * @example
+ * A simple loading with a Progress Circular.
+ * ```
+ * <ProgressCircular />
+ * ```
+ * A Progress Circular that is 50% complete.
+ * ```
+ * <ProgressCircular progress={50} />
+ * ```
+ */
 export const ProgressCircular = withRef(({ progress, size, style, className, ...props }: ProgressCircularProps) =>
   <CitricComponent
     tag="div"

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)} />