docs(props): add props documentation (#1545)

.github/workflows/release.yml

@@ -110,16 +110,3 @@ jobs:
         uses: actions/download-artifact@v2
         with:
           name: build-artifacts
-
-      - name: Generate Documentation
-        env:
-          STORYBOOK_URL: 'https://shoreline.storybook.vtex.com'
-        run: |
-          if git log -1 --pretty=%B | grep -q "\[skip-ci\]"; then
-            exit 0
-          fi
-          git pull --rebase
-          pnpm run gen:docs
-          git add ./packages/docs
-          git commit -m "docs: generate documentation from $GITHUB_SHA [skip-ci]" --allow-empty
-          git push -u origin main --force

package.json

@@ -27,7 +27,6 @@
     "version": "lerna run version",
     "lint:css": "stylelint \"**/*.css\"",
     "chromatic": "chromatic --exit-zero-on-changes --build-script-name=build:storybook",
-    "gen:docs": "npm --prefix packages/docs-generator run start",
     "gen:component": "plop component",
     "create:icon": "plop icon",
     "create:icon-variant": "plop icon-variant",

packages/components/src/alert/alert.tsx

@@ -47,7 +47,7 @@ export const Alert = forwardRef<HTMLDivElement, AlertProps>(function Alert(
   )
 })
 
-function getIcon(variant: AlertVariant = 'informational') {
+function getIcon(variant: AlertOptions['variant'] = 'informational') {
   switch (variant) {
     case 'informational': {
       return <IconInfoFill />
@@ -67,20 +67,16 @@ function getIcon(variant: AlertVariant = 'informational') {
   }
 }
 
-export type AlertVariant = 'informational' | 'success' | 'critical' | 'warning'
-
-export interface AlertProps extends ComponentPropsWithoutRef<'div'> {
+export interface AlertOptions {
   /**
    * Variants of the alert, one of: informational, success, critical, warning.
    * @default 'informational'
    */
-  variant?: AlertVariant
+  variant?: 'informational' | 'success' | 'critical' | 'warning'
   /**
    * Callback fired when the alert is dismissed.
    */
   onDismiss?: MouseEventHandler<HTMLButtonElement>
-  /**
-   * The content of the alert.
-   */
-  children?: React.ReactNode
 }
+
+export type AlertProps = AlertOptions & ComponentPropsWithoutRef<'div'>

packages/components/src/alert/stories/alert.play.stories.tsx

@@ -1,12 +1,11 @@
 import React from 'react'
 
-import type { AlertProps, AlertVariant } from '../index'
+import type { AlertProps } from '../index'
 import { Alert } from '../index'
 import { Text } from '../../text'
 import { Button } from '../../button'
-import type { StoryObj } from '@storybook/react'
 
-const variants: AlertVariant[] = [
+const variants: Array<AlertProps['variant']> = [
   'success',
   'critical',
   'warning',
@@ -43,7 +42,7 @@ export default {
   parameters: {
     chromatic: { disableSnapshot: true },
   },
-} as StoryObj<StoryArgs>
+}
 
 interface StoryArgs extends AlertProps {
   withAction: boolean

packages/components/src/bleed/bleed.tsx

@@ -41,7 +41,7 @@ export const Bleed = forwardRef<HTMLDivElement, BleedProps>(function Bleed(
   )
 })
 
-export interface BleedProps extends ComponentPropsWithoutRef<'div'> {
+export interface BleedOptions {
   /**
    * Top bleed
    * @default '$space-0'
@@ -63,3 +63,5 @@ export interface BleedProps extends ComponentPropsWithoutRef<'div'> {
    */
   end?: string
 }
+
+export type BleedProps = BleedOptions & ComponentPropsWithoutRef<'div'>

packages/components/src/button/button.tsx

@@ -66,7 +66,10 @@ function spanizeString(children: ReactNode) {
   })
 }
 
-export interface ButtonProps extends ComponentPropsWithoutRef<'button'> {
+export interface ButtonOptions {
+  /**
+   * Button contents
+   */
   children: ReactNode
   /**
    * Increase or decrease padding.
@@ -94,3 +97,5 @@ export interface ButtonProps extends ComponentPropsWithoutRef<'button'> {
    */
   asChild?: boolean
 }
+
+export type ButtonProps = ButtonOptions & ComponentPropsWithoutRef<'button'>

packages/components/src/center/center.tsx

@@ -22,10 +22,12 @@ export const Center = forwardRef<HTMLDivElement, CenterProps>(function Center(
   return <Comp data-sl-center ref={ref} {...domProps} />
 })
 
-export interface CenterProps extends ComponentPropsWithoutRef<'div'> {
+export interface CenterOptions {
   /**
    * Children composition
    * @default false
    */
   asChild?: boolean
 }
+
+export type CenterProps = CenterOptions & ComponentPropsWithoutRef<'div'>

packages/components/src/checkbox/checkbox-group.tsx

@@ -54,7 +54,7 @@ export const CheckboxGroup = forwardRef<HTMLInputElement, CheckboxGroupProps>(
   }
 )
 
-export interface CheckboxGroupProps extends ComponentPropsWithoutRef<'div'> {
+export interface CheckboxGroupOptions extends ComponentPropsWithoutRef<'div'> {
   /**
    * Whether the checkbox group is in an error state
    */
@@ -77,3 +77,6 @@ export interface CheckboxGroupProps extends ComponentPropsWithoutRef<'div'> {
    */
   horizontal?: boolean
 }
+
+export type CheckboxGroupProps = CheckboxGroupOptions &
+  ComponentPropsWithoutRef<'div'>

packages/components/src/checkbox/checkbox.tsx

@@ -1,10 +1,13 @@
-import React, { forwardRef } from 'react'
-import { useMergeRef } from '@vtex/shoreline-utils'
+import React, { forwardRef, useMemo, useRef } from 'react'
+import { useMergeRef, mergeProps, useId } from '@vtex/shoreline-utils'
 import { IconCheckSmall, IconMinusSmall } from '@vtex/shoreline-icons'
-
 import { VisuallyHidden } from '@vtex/shoreline-primitives'
-import { useAriaCheckbox } from './use-aria-checkbox'
-import type { AriaCheckboxProps } from './use-aria-checkbox'
+import type { ComponentPropsWithoutRef, Ref } from 'react'
+import { useToggleState } from '@react-stately/toggle'
+import { useCheckbox as useReactAriaCheckbox } from '@react-aria/checkbox'
+import { useFocusRing } from '@react-aria/focus'
+import type { AnyObject } from '@vtex/shoreline-utils'
+
 import { Text } from '../text'
 
 /**
@@ -21,7 +24,7 @@ export const Checkbox = forwardRef<HTMLDivElement, CheckboxProps>(
       isIndeterminate,
       isFocusVisible,
       isDisabled,
-    } = useAriaCheckbox(props)
+    } = useCheckbox(props)
 
     return (
       <label data-sl-checkbox>
@@ -57,4 +60,92 @@ export const Checkbox = forwardRef<HTMLDivElement, CheckboxProps>(
   }
 )
 
-export type CheckboxProps = AriaCheckboxProps
+export function useCheckbox(props: CheckboxProps): AriaCheckbox {
+  const {
+    id: defaultId,
+    indeterminate = false,
+    disabled,
+    checked,
+    defaultChecked,
+    required,
+    onFocus,
+    onBlur,
+    onChange,
+    ...rest
+  } = props
+
+  const typeUnsafe: AnyObject = {
+    onFocus,
+    onBlur,
+  }
+
+  const { isFocusVisible, focusProps } = useFocusRing()
+  const id = useId(defaultId)
+  const inputRef = useRef<HTMLInputElement>(null)
+
+  const state = useToggleState({
+    isSelected: checked,
+    defaultSelected: defaultChecked,
+    isDisabled: disabled,
+    isRequired: required,
+    onChange: (checked) =>
+      onChange?.({
+        target: {
+          value: checked,
+          checked,
+        },
+      } as any),
+    ...typeUnsafe,
+    ...rest,
+  })
+
+  const { inputProps } = useReactAriaCheckbox(
+    {
+      id,
+      isIndeterminate: indeterminate,
+      isDisabled: disabled,
+      ...typeUnsafe,
+      ...rest,
+    },
+    state,
+    inputRef
+  )
+
+  const isChecked = useMemo(
+    () => state.isSelected && !indeterminate,
+    [state.isSelected, indeterminate]
+  )
+
+  return {
+    inputRef,
+    isChecked,
+    isFocusVisible,
+    isIndeterminate: indeterminate,
+    isDisabled: inputProps.disabled ?? false,
+    inputProps: mergeProps(inputProps, focusProps),
+  }
+}
+
+export interface AriaCheckbox {
+  inputRef: Ref<HTMLInputElement>
+  isChecked: boolean
+  isFocusVisible: boolean
+  isIndeterminate: boolean
+  isDisabled: boolean
+  inputProps: ComponentPropsWithoutRef<'input'>
+}
+
+export interface CheckboxOptions {
+  /**
+   * Indicates the indeterminate state
+   * @default
+   */
+  indeterminate?: boolean
+  /**
+   * Indicator value
+   */
+  value?: string
+}
+
+export type CheckboxProps = CheckboxOptions &
+  Omit<ComponentPropsWithoutRef<'input'>, 'value'>

packages/components/src/checkbox/stories/checkbox.show.stories.tsx

@@ -20,7 +20,6 @@ export function Show() {
         <Checkbox indeterminate disabled>
           Indeterminate and disabled
         </Checkbox>
-        <Checkbox>{<VisuallyHidden>With Error</VisuallyHidden>}</Checkbox>
       </Stack>
       <Stack space="5rem">
         <CheckboxGroup label="Options">

packages/components/src/index.ts

@@ -57,7 +57,7 @@ export type {
   VisuallyHiddenProps,
 } from '@vtex/shoreline-primitives'
 export { Alert } from './alert'
-export type { AlertProps, AlertVariant } from './alert'
+export type { AlertProps } from './alert'
 export { Bleed } from './bleed'
 export type { BleedProps } from './bleed'
 export { Button } from './button'

packages/docs/.gitignore

@@ -2,4 +2,7 @@
 .sentryclirc
 
 # auto-generated examples
-__examples__/
+__examples__/
+
+# auto-generated props
+__props__/

packages/docs/components/props-docs/index.ts

@@ -0,0 +1 @@
+export * from './props-docs'