Merge pull request #1704 from adevinta/add-missing-comments

docs: add missing comments to props (types)

packages/components/badge/src/BadgeItem.styles.tsx

@@ -7,6 +7,9 @@ export const styles = cva(
   ['inline-flex h-fit', 'empty:p-none', 'text-center font-bold', 'rounded-full box-content'],
   {
     variants: {
+      /**
+       * Visual color appearance of the component.
+       */
       intent: makeVariants<
         'intent',
         [
@@ -33,10 +36,16 @@ export const styles = cva(
         surface: ['bg-surface', 'text-on-surface', 'border-on-surface'],
         basic: ['bg-basic', 'text-on-basic', 'border-on-basic'],
       }),
+      /**
+       * Size of the component.
+       */
       size: makeVariants<'size', ['sm', 'md']>({
         sm: ['text-small', 'px-[var(--sz-6)] py-[var(--sz-2)]', 'empty:h-sz-12 empty:w-sz-12'],
         md: ['text-caption', 'px-md py-sm', 'empty:h-sz-16 empty:w-sz-16'],
       }),
+      /**
+       * Type of the component.
+       */
       type: {
         relative: ['absolute right-none translate-x-2/4 -translate-y-2/4 border-md'],
         standalone: [],

packages/components/button/src/Button.styles.tsx

@@ -40,7 +40,6 @@ export const buttonStyles = cva(
         ghost: [],
         contrast: ['bg-surface'],
       }),
-
       /**
        * Color scheme of the button.
        */
@@ -70,19 +69,22 @@ export const buttonStyles = cva(
         neutral: [],
         surface: [],
       }),
-
+      /**
+       * Size of the button.
+       */
       size: makeVariants<'size', ['sm', 'md', 'lg']>({
         sm: ['min-w-sz-32', 'h-sz-32'],
         md: ['min-w-sz-44', 'h-sz-44'],
         lg: ['min-w-sz-56', 'h-sz-56'],
       }),
-
+      /**
+       * Shape of the button.
+       */
       shape: makeVariants<'shape', ['rounded', 'square', 'pill']>({
         rounded: ['rounded-lg'],
         square: ['rounded-none'],
         pill: ['rounded-full'],
       }),
-
       /**
        * Disable the button, preventing user interaction and adding opacity.
        */

packages/components/button/src/Button.tsx

@@ -25,6 +25,9 @@ export interface ButtonProps
    * **Please note that using this can result in layout shifting when the Button goes from loading state to normal state.**
    */
   loadingText?: string
+  /**
+   * Placement for the spinner.
+   */
   spinnerPlacement?: 'left' | 'right'
 }
 

packages/components/checkbox/src/CheckboxGroup.styles.ts

@@ -2,6 +2,9 @@ import { cva, VariantProps } from 'class-variance-authority'
 
 export const checkboxGroupStyles = cva(['flex'], {
   variants: {
+    /**
+     * Prop to set the orientation of the checkbox group which could be `vertical` or `horizontal`.
+     */
     orientation: {
       vertical: ['flex-col', 'gap-lg'],
       horizontal: ['gap-xl'],

packages/components/checkbox/src/CheckboxInput.styles.ts

@@ -11,6 +11,9 @@ export const checkboxInputStyles = cva(
   ],
   {
     variants: {
+      /**
+       * Color scheme of the checkbox.
+       */
       intent: makeVariants<
         'intent',
         ['main', 'support', 'accent', 'basic', 'success', 'alert', 'error', 'info', 'neutral']

packages/components/chip/src/Chip.tsx

@@ -22,7 +22,7 @@ export interface ChipProps
    */
   asChild?: boolean
   /**
-   * event handler fired each clicking event
+   * Event handler fired each clicking event
    */
   onClick?: (
     event: React.MouseEvent<HTMLButtonElement, MouseEvent>,

packages/components/dialog/src/Dialog.tsx

@@ -3,7 +3,28 @@ import { type ReactElement } from 'react'
 
 import { DialogProvider } from './DialogContext'
 
-export type DialogProps = RadixDialog.DialogProps
+export interface DialogProps {
+  /**
+   * Children of the component.
+   */
+  children?: RadixDialog.DialogProps['children']
+  /**
+   * Specifies if the dialog is open or not.
+   */
+  open?: RadixDialog.DialogProps['open']
+  /**
+   * Default open state.
+   */
+  defaultOpen?: RadixDialog.DialogProps['defaultOpen']
+  /**
+   * Handler executen on every dialog open state change.
+   */
+  onOpenChange?: RadixDialog.DialogProps['onOpenChange']
+  /**
+   * Specifies if the dialog is a modal.
+   */
+  modal?: RadixDialog.DialogProps['modal']
+}
 
 export const Dialog = ({ children, ...rest }: DialogProps): ReactElement => (
   <DialogProvider>

packages/components/dialog/src/DialogTrigger.tsx

@@ -2,7 +2,16 @@ import * as RadixDialog from '@radix-ui/react-dialog'
 import { ElementRef, forwardRef, type ReactElement } from 'react'
 
 type TriggerElement = ElementRef<typeof RadixDialog.Trigger>
-export type TriggerProps = RadixDialog.DialogTriggerProps
+export interface TriggerProps {
+  /**
+   * Children of the component.
+   */
+  children?: React.ReactNode
+  /**
+   * Change the component to the HTML tag or custom component of the only child.
+   */
+  asChild?: RadixDialog.DialogTriggerProps['asChild']
+}
 
 export const Trigger = forwardRef<TriggerElement, TriggerProps>(
   (props: TriggerProps, ref): ReactElement => <RadixDialog.Trigger ref={ref} {...props} />

packages/components/drawer/src/Drawer.tsx

@@ -1,7 +1,36 @@
 import * as RadixDrawer from '@radix-ui/react-dialog'
 import { type ReactElement } from 'react'
 
-export type DrawerProps = RadixDrawer.DialogProps
+export interface DrawerProps {
+  /**
+   * Children of the component.
+   */
+  children?: RadixDrawer.DialogProps['children']
+  /**
+   * Specifies if the dialog is open or not.
+   */
+  open?: RadixDrawer.DialogProps['open']
+  /**
+   * Default open state.
+   */
+  defaultOpen?: RadixDrawer.DialogProps['defaultOpen']
+  /**
+   * Handler executed on every dialog open state change.
+   */
+  onOpenChange?: RadixDrawer.DialogProps['onOpenChange']
+  /**
+   * Specifies if the dialog is a modal.
+   */
+  modal?: RadixDrawer.DialogProps['modal']
+}
+
+export interface DialogProps {
+  children?: React.ReactNode
+  open?: boolean
+  defaultOpen?: boolean
+  onOpenChange?(open: boolean): void
+  modal?: boolean
+}
 
 export const Drawer = ({ children, ...rest }: DrawerProps): ReactElement => (
   <RadixDrawer.Root {...rest}>{children}</RadixDrawer.Root>

packages/components/drawer/src/DrawerTrigger.tsx

@@ -2,7 +2,12 @@ import * as RadixDrawer from '@radix-ui/react-dialog'
 import { ElementRef, forwardRef, type ReactElement } from 'react'
 
 type TriggerElement = ElementRef<typeof RadixDrawer.Trigger>
-export type DrawerTriggerProps = RadixDrawer.DialogTriggerProps
+export interface DrawerTriggerProps extends RadixDrawer.DialogTriggerProps {
+  /**
+   * Change the component to the HTML tag or custom component of the only child. This will merge the original component props with the props of the supplied element/component and change the underlying DOM node.
+   */
+  asChild?: boolean
+}
 
 export const DrawerTrigger = forwardRef<TriggerElement, DrawerTriggerProps>(
   (props: DrawerTriggerProps, ref): ReactElement => <RadixDrawer.Trigger ref={ref} {...props} />

packages/components/form-field/src/FormField.tsx

@@ -13,7 +13,13 @@ export interface FormFieldProps
    * Change the component to the HTML tag or custom component of the only child. This will merge the original component props with the props of the supplied element/component and change the underlying DOM node.
    */
   asChild?: boolean
+  /**
+   * When `true`, prevents the user from interacting.
+   */
   disabled?: boolean
+  /**
+   * Sets the component as interactive or not.
+   */
   readOnly?: boolean
 }
 

packages/components/icon-button/src/IconButton.styles.tsx

@@ -3,6 +3,9 @@ import { cva, VariantProps } from 'class-variance-authority'
 
 export const iconButtonStyles = cva(['px-none'], {
   variants: {
+    /**
+     * Sets the size of the icon.
+     */
     size: makeVariants<'size', ['sm', 'md', 'lg']>({
       sm: ['text-body-1'],
       md: ['text-body-1'],

packages/components/icon/src/Icon.styles.tsx

@@ -3,6 +3,9 @@ import { cva, VariantProps } from 'class-variance-authority'
 
 export const iconStyles = cva(['fill-current'], {
   variants: {
+    /**
+     * Color scheme of the icon.
+     */
     intent: makeVariants<
       'intent',
       [
@@ -29,6 +32,9 @@ export const iconStyles = cva(['fill-current'], {
       info: ['text-info'],
       neutral: ['text-neutral'],
     }),
+    /**
+     * Sets the size of the icon.
+     */
     size: makeVariants<'size', ['current', 'sm', 'md', 'lg', 'xl']>({
       current: ['u-current-font-size'],
       sm: ['w-sz-16', 'h-sz-16'],

packages/components/input/src/Input.styles.ts

@@ -21,10 +21,16 @@ export const inputStyles = cva(
   ],
   {
     variants: {
+      /**
+       * Change the component to the HTML tag or custom component of the only child.
+       */
       asChild: {
         true: ['min-h-sz-44'],
         false: ['h-sz-44'],
       },
+      /**
+       * Color scheme of the button.
+       */
       intent: {
         neutral: [
           'border-outline',
@@ -35,19 +41,34 @@ export const inputStyles = cva(
         alert: ['border-alert', 'focus:ring-alert'],
         error: ['border-error', 'focus:ring-error'],
       },
+      /**
+       * Sets if there is an addon before the input text.
+       */
       hasLeadingAddon: {
         true: ['rounded-l-none'],
         false: ['rounded-l-lg'],
       },
+      /**
+       * Sets if there is an addon after the input text.
+       */
       hasTrailingAddon: {
         true: ['rounded-r-none'],
         false: ['rounded-r-lg'],
       },
+      /**
+       * Sets if there is an icon before the input text.
+       */
       hasLeadingIcon: {
         true: ['pl-3xl'],
         false: ['pl-lg'],
       },
+      /**
+       * Sets if there is an icon after the input text.
+       */
       hasTrailingIcon: { true: '' },
+      /**
+       * Sets if there is a button to clear the input text.
+       */
       hasClearButton: { true: '' },
     },
     compoundVariants: [

packages/components/input/src/InputAddon.styles.ts

@@ -10,19 +10,31 @@ export const inputAddonStyles = cva(
   ],
   {
     variants: {
+      /**
+       * Change the component to the HTML tag or custom component of the only child.
+       */
       asChild: { false: ['flex', 'items-center', 'px-lg'] },
       intent: {
         neutral: 'border-outline',
         error: 'border-error',
         alert: 'border-alert',
         success: 'border-success',
       },
+      /**
+       * Disable the input addon, preventing user interaction and adding opacity.
+       */
       disabled: {
         true: ['pointer-events-none !border-outline'],
       },
+      /**
+       * Changes input addon styles based on the read only status from the input.
+       */
       readOnly: {
         true: [],
       },
+      /**
+       * Main style of the input addon.
+       */
       design: {
         text: '',
         solid: '',

packages/components/input/src/InputGroup.styles.ts

@@ -2,6 +2,9 @@ import { cva, VariantProps } from 'class-variance-authority'
 
 export const inputGroupStyles = cva(['relative inline-flex w-full'], {
   variants: {
+    /**
+     * When `true`, prevents the user from interacting.
+     */
     disabled: {
       true: [
         'cursor-not-allowed',
@@ -15,6 +18,9 @@ export const inputGroupStyles = cva(['relative inline-flex w-full'], {
       ],
       false: 'after:hidden',
     },
+    /**
+     * Sets the component as interactive or not.
+     */
     readOnly: {
       true: [
         'relative',

packages/components/input/src/InputGroup.tsx

@@ -27,7 +27,13 @@ import { InputGroupContext } from './InputGroupContext'
 import { InputStateIndicator } from './InputStateIndicator'
 
 export interface InputGroupProps extends ComponentPropsWithoutRef<'div'>, InputGroupStylesProps {
+  /**
+   * Use `state` prop to assign a specific state to the group, choosing from: `error`, `alert` and `success`. By doing so, the outline styles will be updated, and a state indicator will be displayed accordingly.
+   */
   state?: 'error' | 'alert' | 'success'
+  /**
+   * Function handler to be executed after the input has been cleared.
+   */
   onClear?: () => void
 }
 

packages/components/progress/src/ProgressIndicator.styles.ts

@@ -2,6 +2,9 @@ import { cva, VariantProps } from 'class-variance-authority'
 
 export const progressIndicatorStyles = cva(['h-full w-full', 'transition-transform duration-400'], {
   variants: {
+    /**
+     * Color scheme of the progress component.
+     */
     intent: {
       basic: ['bg-basic'],
       main: ['bg-main'],
@@ -13,10 +16,16 @@ export const progressIndicatorStyles = cva(['h-full w-full', 'transition-transfo
       info: ['bg-info'],
       neutral: ['bg-neutral'],
     },
+    /**
+     * Shape of the progress component.
+     */
     shape: {
       square: [],
       rounded: ['rounded-sm'],
     },
+    /**
+     * Sets if the progress value is not determinated.
+     */
     isIndeterminate: {
       true: ['absolute', '-translate-x-1/2', 'animate-standalone-indeterminate-bar'],
       false: [],

packages/components/radio-group/src/RadioInput.styles.ts

@@ -15,6 +15,9 @@ export const radioInputVariants = cva(
   ],
   {
     variants: {
+      /**
+       * Color scheme of the radio input.
+       */
       intent: makeVariants<
         'intent',
         ['main', 'support', 'accent', 'basic', 'success', 'alert', 'error', 'info', 'neutral']