Add Missing JSDocs and Docsite Links (#6666)

Co-authored-by: Segun Adebayo <joseshegs@gmail.com>
chakra-ui · Sep 12, 2022 · 3e1b3f6 · 3e1b3f6 · vercel · Sep 12, 2022
1 parent d380a37
commit 3e1b3f6
Show file tree

Hide file tree

Showing 59 changed files with 240 additions and 9 deletions.
diff --git a/.changeset/tricky-squids-kneel.md b/.changeset/tricky-squids-kneel.md
@@ -0,0 +1,38 @@
+---
+"@chakra-ui/alert": patch
+"@chakra-ui/button": patch
+"@chakra-ui/checkbox": patch
+"@chakra-ui/close-button": patch
+"@chakra-ui/editable": patch
+"@chakra-ui/form-control": patch
+"@chakra-ui/icon": patch
+"@chakra-ui/input": patch
+"@chakra-ui/layout": patch
+"@chakra-ui/media-query": patch
+"@chakra-ui/menu": patch
+"@chakra-ui/modal": patch
+"@chakra-ui/pin-input": patch
+"@chakra-ui/popover": patch
+"@chakra-ui/radio": patch
+"@chakra-ui/select": patch
+"@chakra-ui/skeleton": patch
+"@chakra-ui/skip-nav": patch
+"@chakra-ui/stat": patch
+"@chakra-ui/switch": patch
+"@chakra-ui/system": patch
+"@chakra-ui/table": patch
+"@chakra-ui/tabs": patch
+"@chakra-ui/toast": patch
+"@chakra-ui/visually-hidden": patch
+"@chakra-ui/react-use-controllable-state": patch
+"@chakra-ui/react-use-disclosure": patch
+"@chakra-ui/hooks": patch
+---
+
+Add missing component/function docs and relative docsite links.
+
+Ensures that all Components, functions, and hooks that have detailed pages on
+the Chakra site have corresponding JSDocs and links back to the docsite via IDE
+intellisense.
+
+Includes adding or fixing links within these docs to related WAI-ARIA patterns.
diff --git a/packages/components/accordion/src/accordion.tsx b/packages/components/accordion/src/accordion.tsx
@@ -34,6 +34,7 @@ export interface AccordionProps
  *
  * It wraps all accordion items in a `div` for better grouping.
  * @see Docs https://chakra-ui.com/accordion
+ * @see WAI-ARIA https://www.w3.org/WAI/ARIA/apg/patterns/accordion/
  */
 export const Accordion = forwardRef<AccordionProps, "div">(function Accordion(
   { children, reduceMotion, ...props },

diff --git a/packages/components/accordion/src/use-accordion.ts b/packages/components/accordion/src/use-accordion.ts
@@ -41,6 +41,8 @@ export interface UseAccordionProps {
 /**
  * useAccordion hook provides all the state and focus management logic
  * for accordion items.
+ *
+ * @see WAI-ARIA https://www.w3.org/WAI/ARIA/apg/patterns/accordion/
  */
 export function useAccordion(props: UseAccordionProps) {
   const {

diff --git a/packages/components/alert/src/alert.tsx b/packages/components/alert/src/alert.tsx
@@ -33,6 +33,9 @@ export interface AlertProps
 /**
  * Alert is used to communicate the state or status of a
  * page, feature or action
+ *
+ * @see Docs https://chakra-ui.com/docs/components/alert
+ * @see WAI-ARIA https://www.w3.org/WAI/ARIA/apg/patterns/alert/
  */
 export const Alert = forwardRef<AlertProps, "div">(function Alert(props, ref) {
   const { status = "info", addRole = true, ...rest } = omitThemingProps(props)

diff --git a/packages/components/breadcrumb/src/breadcrumb.tsx b/packages/components/breadcrumb/src/breadcrumb.tsx
@@ -22,6 +22,7 @@ export interface BreadcrumbProps
  * It renders a `nav` element with `aria-label` set to `Breadcrumb`
  *
  * @see Docs https://chakra-ui.com/breadcrumb
+ * @see WAI-ARIA https://www.w3.org/WAI/ARIA/apg/patterns/breadcrumb/
  */
 export const Breadcrumb = forwardRef<BreadcrumbProps, "nav">(
   function Breadcrumb(props, ref) {

diff --git a/packages/components/button/src/button.tsx b/packages/components/button/src/button.tsx
@@ -22,6 +22,12 @@ export interface ButtonProps
     ButtonOptions,
     ThemingProps<"Button"> {}
 
+/**
+ * Button component is used to trigger an action or event, such as submitting a form, opening a Dialog, canceling an action, or performing a delete operation.
+ *
+ * @see Docs https://chakra-ui.com/docs/components/button
+ * @see WAI-ARIA https://www.w3.org/WAI/ARIA/apg/patterns/button/
+ */
 export const Button = forwardRef<ButtonProps, "button">((props, ref) => {
   const group = useButtonGroup()
   const styles = useStyleConfig("Button", { ...group, ...props })

diff --git a/packages/components/button/src/icon-button.tsx b/packages/components/button/src/icon-button.tsx
@@ -27,6 +27,11 @@ export interface IconButtonProps extends BaseButtonProps {
   "aria-label": string
 }
 
+/**
+ * Icon button renders an icon within a button.
+ *
+ * @see Docs https://chakra-ui.com/docs/components/icon-button
+ */
 export const IconButton = forwardRef<IconButtonProps, "button">(
   (props, ref) => {
     const { icon, children, isRound, "aria-label": ariaLabel, ...rest } = props

diff --git a/packages/components/checkbox/src/checkbox.tsx b/packages/components/checkbox/src/checkbox.tsx
@@ -57,6 +57,7 @@ export interface CheckboxProps
  * multiple values from several options.
  *
  * @see Docs https://chakra-ui.com/checkbox
+ * @see WAI-ARIA https://www.w3.org/WAI/ARIA/apg/patterns/checkbox/
  */
 export const Checkbox = forwardRef<CheckboxProps, "input">(function Checkbox(
   props,

diff --git a/packages/components/checkbox/src/use-checkbox-group.ts b/packages/components/checkbox/src/use-checkbox-group.ts
@@ -13,6 +13,9 @@ function isInputEvent(value: any): value is { target: HTMLInputElement } {
  * for a group of checkboxes.
  *
  * It is consumed by the `CheckboxGroup` component
+ *
+ * @see Docs https://chakra-ui.com/docs/hooks/use-checkbox-group
+ * @see WAI-ARIA https://www.w3.org/WAI/ARIA/apg/patterns/checkbox/
  */
 export function useCheckboxGroup(props: UseCheckboxGroupProps = {}) {
   const {

diff --git a/packages/components/checkbox/src/use-checkbox.ts b/packages/components/checkbox/src/use-checkbox.ts
@@ -16,6 +16,7 @@ import { CheckboxState, UseCheckboxProps } from "./checkbox-types"
  * for a checkbox. It is consumed by the `Checkbox` component
  *
  * @see Docs https://chakra-ui.com/checkbox#hooks
+ * @see WAI-ARIA https://www.w3.org/WAI/ARIA/apg/patterns/checkbox/
  */
 export function useCheckbox(props: UseCheckboxProps = {}) {
   const formControlProps = useFormControlProps(props)

diff --git a/packages/components/close-button/src/close-button.tsx b/packages/components/close-button/src/close-button.tsx
@@ -34,6 +34,8 @@ export interface CloseButtonProps
  *
  * It is used to handle the close functionality in feedback and overlay components
  * like Alerts, Toasts, Drawers and Modals.
+ *
+ * @see Docs https://chakra-ui.com/docs/components/close-button
  */
 export const CloseButton = forwardRef<CloseButtonProps, "button">(
   function CloseButton(props, ref) {

diff --git a/packages/components/editable/src/editable.tsx b/packages/components/editable/src/editable.tsx
@@ -39,6 +39,8 @@ export interface EditableProps
  *
  * The wrapper that provides context and logic for all editable
  * components. It renders a `div`
+ *
+ * @see Docs https://chakra-ui.com/docs/components/editable
  */
 export const Editable = forwardRef<EditableProps, "div">(function Editable(
   props,

diff --git a/packages/components/form-control/src/form-control.tsx b/packages/components/form-control/src/form-control.tsx
@@ -211,6 +211,8 @@ export interface FormControlProps
  *
  * This is commonly used in form elements such as `input`,
  * `select`, `textarea`, etc.
+ *
+ * @see Docs https://chakra-ui.com/docs/components/form-control
  */
 export const FormControl = forwardRef<FormControlProps, "div">(
   function FormControl(props, ref) {

diff --git a/packages/components/icon/src/icon.tsx b/packages/components/icon/src/icon.tsx
@@ -29,6 +29,11 @@ export interface IconProps
   extends Omit<React.SVGAttributes<SVGElement>, keyof ChakraProps>,
     ChakraProps {}
 
+/**
+ * The Icon component renders as an svg element to help define your own custom components.
+ *
+ * @see Docs https://chakra-ui.com/docs/components/icon#using-the-icon-component
+ */
 export const Icon = forwardRef<IconProps, "svg">((props, ref) => {
   const {
     as: element,

diff --git a/packages/components/input/src/input.tsx b/packages/components/input/src/input.tsx
@@ -40,6 +40,8 @@ export interface InputProps
  * Input
  *
  * Element that allows users enter single valued data.
+ *
+ * @see Docs https://chakra-ui.com/docs/components/input
  */
 export const Input = forwardRef<InputProps, "input">(function Input(
   props,

diff --git a/packages/components/layout/src/container.tsx b/packages/components/layout/src/container.tsx
@@ -25,6 +25,8 @@ export interface ContainerProps
  * to keep its content centered.
  *
  * It also sets a default max-width of `60ch` (60 characters).
+ *
+ * @see Docs https://chakra-ui.com/docs/components/container
  */
 export const Container = forwardRef<ContainerProps, "div">(function Container(
   props,

diff --git a/packages/components/layout/src/heading.tsx b/packages/components/layout/src/heading.tsx
@@ -12,6 +12,13 @@ export interface HeadingProps
   extends HTMLChakraProps<"h2">,
     ThemingProps<"Heading"> {}
 
+/**
+ * `Heading` is used to render semantic HTML heading elements.
+ *
+ * By default, renders as `h2` with themantic size `xl`
+ *
+ * @see Docs https://chakra-ui.com/docs/components/heading
+ */
 export const Heading = forwardRef<HeadingProps, "h2">(function Heading(
   props,
   ref,

diff --git a/packages/components/layout/src/highlight.tsx b/packages/components/layout/src/highlight.tsx
@@ -68,6 +68,11 @@ export const Mark = forwardRef<MarkProps, "mark">(function Mark(props, ref) {
   )
 })
 
+/**
+ * `Highlight` allows you to highlight substrings of a text.
+ *
+ * @see Docs https://chakra-ui.com/docs/components/highlight
+ */
 export function Highlight(props: HighlightProps): JSX.Element {
   const { children, query, styles } = props
 

diff --git a/packages/components/layout/src/stack/h-stack.tsx b/packages/components/layout/src/stack/h-stack.tsx
@@ -4,6 +4,8 @@ import { Stack, StackProps } from "./stack"
 
 /**
  * A view that arranges its children in a horizontal line.
+ *
+ * @see Docs https://chakra-ui.com/docs/components/stack
  */
 export const HStack = forwardRef<StackProps, "div">((props, ref) => (
   <Stack align="center" {...props} direction="row" ref={ref} />

diff --git a/packages/components/layout/src/stack/v-stack.tsx b/packages/components/layout/src/stack/v-stack.tsx
@@ -4,6 +4,8 @@ import { Stack, StackProps } from "./stack"
 
 /**
  * A view that arranges its children in a vertical line.
+ *
+ * @see Docs https://chakra-ui.com/docs/components/stack
  */
 export const VStack = forwardRef<StackProps, "div">((props, ref) => (
   <Stack align="center" {...props} direction="column" ref={ref} />

diff --git a/packages/components/media-query/src/hide.tsx b/packages/components/media-query/src/hide.tsx
@@ -4,6 +4,11 @@ import { ShowProps } from "./show"
 
 export type HideProps = ShowProps
 
+/**
+ * `Hide` wraps a component to not render if the provided media query matches.
+ *
+ * @see Docs https://chakra-ui.com/docs/components/show-hide
+ */
 export function Hide(props: HideProps) {
   const { children, ssr } = props
   const query = useQuery(props)

diff --git a/packages/components/media-query/src/media-query.hook.ts b/packages/components/media-query/src/media-query.hook.ts
@@ -2,6 +2,8 @@ import { useMediaQuery, UseMediaQueryOptions } from "./use-media-query"
 
 /**
  * React hook used to get the user's animation preference.
+ *
+ * @see Docs https://chakra-ui.com/docs/hooks/use-prefers-reduced-motion
  */
 export function usePrefersReducedMotion(
   options?: UseMediaQueryOptions,

diff --git a/packages/components/media-query/src/show.tsx b/packages/components/media-query/src/show.tsx
@@ -21,6 +21,11 @@ export interface ShowProps {
   children?: React.ReactNode
 }
 
+/**
+ * `Show` wraps a component to render if the provided media query matches.
+ *
+ * @see Docs https://chakra-ui.com/docs/components/show-hide
+ */
 export function Show(props: ShowProps) {
   const { children, ssr } = props
   const query = useQuery(props)

diff --git a/packages/components/media-query/src/use-breakpoint-value.ts b/packages/components/media-query/src/use-breakpoint-value.ts
@@ -13,6 +13,8 @@ import { useBreakpoint, UseBreakpointOptions } from "./use-breakpoint"
  *
  * @example
  * const width = useBreakpointValue({ base: '150px', md: '250px' })
+ *
+ * @see Docs https://chakra-ui.com/docs/hooks/use-breakpoint-value
  */
 export function useBreakpointValue<T = any>(
   values: Partial<Record<string, T>> | T[],

diff --git a/packages/components/media-query/src/use-media-query.ts b/packages/components/media-query/src/use-media-query.ts
@@ -11,6 +11,8 @@ export type UseMediaQueryOptions = {
  *
  * @param query the media query to match
  * @param options the media query options { fallback, ssr }
+ *
+ * @see Docs https://chakra-ui.com/docs/hooks/use-media-query
  */
 export function useMediaQuery(
   query: string | string[],

diff --git a/packages/components/menu/src/menu-button.tsx b/packages/components/menu/src/menu-button.tsx
@@ -25,6 +25,8 @@ const StyledMenuButton = forwardRef<MenuButtonProps, "button">((props, ref) => {
 
 /**
  * The trigger for the menu list. Must be a direct child of `Menu`.
+ *
+ * @see WAI-ARIA https://www.w3.org/WAI/ARIA/apg/patterns/menubutton/
  */
 export const MenuButton = forwardRef<MenuButtonProps, "button">(
   (props, ref) => {

diff --git a/packages/components/menu/src/menu.tsx b/packages/components/menu/src/menu.tsx
@@ -37,6 +37,8 @@ export interface MenuProps extends UseMenuProps, ThemingProps<"Menu"> {
 /**
  * Menu provides context, state, and focus management
  * to its sub-components. It doesn't render any DOM node.
+ *
+ * @see Docs https://chakra-ui.com/docs/components/menu
  */
 export const Menu: React.FC<MenuProps> = (props) => {
   const { children } = props

diff --git a/packages/components/modal/src/alert-dialog.tsx b/packages/components/modal/src/alert-dialog.tsx
@@ -6,6 +6,12 @@ export interface AlertDialogProps extends Omit<ModalProps, "initialFocusRef"> {
   leastDestructiveRef: NonNullable<ModalProps["initialFocusRef"]>
 }
 
+/**
+ * `AlertDialog` component is used interrupt the user with a mandatory confirmation or action.
+ *
+ * @see Docs https://chakra-ui.com/docs/components/alert-dialog
+ * @see WAI-ARIA https://www.w3.org/WAI/ARIA/apg/patterns/alertdialog/
+ */
 export function AlertDialog(props: AlertDialogProps) {
   const { leastDestructiveRef, ...rest } = props
   return <Modal {...rest} initialFocusRef={leastDestructiveRef} />

diff --git a/packages/components/modal/src/drawer.tsx b/packages/components/modal/src/drawer.tsx
@@ -47,6 +47,12 @@ export interface DrawerProps
       "scrollBehavior" | "motionPreset" | "isCentered" | keyof ThemingProps
     > {}
 
+/**
+ * The Drawer component is a panel that slides out from the edge of the screen.
+ * It can be useful when you need users to complete a task or view some details without leaving the current page.
+ *
+ * @see Docs https://chakra-ui.com/docs/components/drawer
+ */
 export function Drawer(props: DrawerProps) {
   const {
     isOpen,

diff --git a/packages/components/modal/src/modal.tsx b/packages/components/modal/src/modal.tsx
@@ -131,6 +131,9 @@ const [ModalContextProvider, useModalContext] = createContext<ModalContext>({
  * to all other modal components.
  *
  * It doesn't render any DOM node.
+ *
+ * @see Docs https://chakra-ui.com/docs/components/modal
+ * @see WAI-ARIA https://www.w3.org/WAI/ARIA/apg/patterns/dialogmodal/
  */
 export const Modal: React.FC<ModalProps> = (props) => {
   const {

diff --git a/packages/components/number-input/src/use-number-input.ts b/packages/components/number-input/src/use-number-input.ts
@@ -132,7 +132,7 @@ type InputSelection = { start: number | null; end: number | null }
  * It returns prop getters you can use to build your own
  * custom number inputs.
  *
- * @see WAI-ARIA https://www.w3.org/TR/wai-aria-practices-1.1/#spinbutton
+ * @see WAI-ARIA https://www.w3.org/WAI/ARIA/apg/patterns/spinbutton/
  * @see Docs     https://www.chakra-ui.com/useNumberInput
  * @see WHATWG   https://html.spec.whatwg.org/multipage/input.html#number-state-(type=number)
  */

diff --git a/packages/components/pin-input/src/pin-input.tsx b/packages/components/pin-input/src/pin-input.tsx
@@ -42,6 +42,11 @@ export interface PinInputProps
   children: React.ReactNode
 }
 
+/**
+ * The `PinInput` component is similar to the Input component, but is optimized for entering sequences of digits quickly.
+ *
+ * @see Docs https://chakra-ui.com/docs/components/pin-input
+ */
 export function PinInput(props: PinInputProps) {
   const styles = useStyleConfig("PinInput", props)
 

diff --git a/packages/components/popover/src/popover.tsx b/packages/components/popover/src/popover.tsx
@@ -24,6 +24,8 @@ export interface PopoverProps extends UsePopoverProps, ThemingProps<"Popover"> {
 /**
  * Popover is used to bring attention to specific user interface elements,
  * typically to suggest an action or to guide users through a new experience.
+ *
+ * @see Docs https://chakra-ui.com/docs/components/popover
  */
 export function Popover(props: PopoverProps) {
   const styles = useMultiStyleConfig("Popover", props)

diff --git a/packages/components/radio/src/use-radio-group.ts b/packages/components/radio/src/use-radio-group.ts
@@ -49,7 +49,9 @@ export interface UseRadioGroupProps {
 }
 
 /**
- * React hook to manage a group of radio inputs
+ * `useRadioGroup` is a custom hook that provides all the state management logic for a group of radios.
+ *
+ * @see Docs https://chakra-ui.com/docs/hooks/use-radio-group
  */
 export function useRadioGroup(props: UseRadioGroupProps = {}) {
   const {

diff --git a/packages/components/radio/src/use-radio.ts b/packages/components/radio/src/use-radio.ts
@@ -80,6 +80,11 @@ export interface RadioState {
   isRequired: boolean | undefined
 }
 
+/**
+ * `useRadio` is a custom hook used to provide radio functionality, as well as state and focus management to custom radio components when using it.
+ *
+ * @see Docs https://chakra-ui.com/docs/hooks/use-radio
+ */
 export function useRadio(props: UseRadioProps = {}) {
   const {
     defaultChecked,

diff --git a/packages/components/select/src/select.tsx b/packages/components/select/src/select.tsx
@@ -67,6 +67,8 @@ export interface SelectProps
 
 /**
  * React component used to select one item from a list of options.
+ *
+ * @see Docs https://chakra-ui.com/docs/components/select
  */
 export const Select = forwardRef<SelectProps, "select">((props, ref) => {
   const styles = useMultiStyleConfig("Select", props)