@workday/canvas-kit-react 8.5.0-339-next.0 → 8.5.0-342-next.2

package/pagination/lib/Pagination/common/utils/helpers.ts

@@ -1,52 +1,82 @@
 /**
- * Returns the last page for the total results
+ * This function takes the number of results per page and the total count of results and returns the
+ * last page number. Here's an example:
+ *
+ * Given there are 10 results per page, and there are 128 total results, the function will return 13.
+ *
+ * ```ts
+ * const lastPage = getLastPage(10, 128); //=> 13
+ * ```
+ *
  * @param resultCount number of results per page
  * @param totalCount total number of results
- * @example
- * const lastPage = getLastPage(10, 120); //=> 12
  */
 export function getLastPage(resultCount: number, totalCount: number): number {
   return Math.ceil(totalCount / resultCount);
 }
 
 /**
- * Returns the first number in the pagination range
+ * This function takes the pagination range and returns its minimum value. Here's an example:
+ *
+ * Given the pagination range is 1-5, the function will return 1.
+ *
+ * ```ts
+ * const range = [1, 2, 3, 4, 5];
+ * const rangeMin = getRangeMin(range); //=> 1
+ * ```
  * @param range the range of numbers for the pagination component
- * @example
- * const rangeMin = getRangeMin([1,2,3,4,5]) //=> 1
  */
 export function getRangeMin(range: number[]): number {
   return range[0];
 }
 
 /**
- * Returns the last number in the pagination range
+ * This function takes the pagination range and returns its maximum value. Here's an example:
+ *
+ * Given the pagination range is 1-5, the function will return 5.
+ *
+ * ```ts
+ * const range = [1, 2, 3, 4, 5];
+ * const rangeMin = getRangeMax(range); //=> 5
+ * ```
  * @param range the range of numbers for the pagination component
- * @example
- * const rangeMax = getRangeMax([1,2,3,4,5]) //=> 5
  */
 export function getRangeMax(range: number[]): number {
   return range[range.length - 1];
 }
 
 /**
- * Returns the first page number for the visible results
+ * This function takes the current page, and number of results per page, and returns the minimum value
+ * for that page. Here's an example:
+ *
+ * Given there are 10 results per page, and the current page is 5, the function will return 41.
+ *
+ * ```ts
+ * const pageMin = getVisibleResultsMin(5, 10); //=> 41
+ * ```
  * @param currentPage current page for the range
  * @param resultCount number of results per page
- * @example
- * const pageMin = getVisibleResultsMin(5, 10); //=> 41
  */
 export function getVisibleResultsMin(currentPage: number, resultCount: number): number {
   return currentPage * resultCount - resultCount + 1;
 }
 
 /**
- * Returns the last page number for the visible results
+ * This function takes the current page, number of results per page, and the total number of results,
+ * and returns the maximum value for that page. Here's an example:
+ *
+ * Given there are 10 results per page, the current page is 5, and there are 42 results total, the
+ * function will return 42.
+ *
+ * ```ts
+ * const currentPage = 5;
+ * const resultCount = 10;
+ * const totalCount = 42;
+ * const pageMax = getVisibleResultsMax(currentPage, resultCount, totalCount); //=> 42
+ * ```
  * @param currentPage current page for the range
  * @param resultCount number of results per page
  * @param totalCount total number of results
- * @example
- * const pageMax = getVisiblePageMax(5,10,100); //=> 50
  */
 export function getVisibleResultsMax(
   currentPage: number,

package/pagination/lib/Pagination/usePaginationModel.ts

@@ -4,6 +4,8 @@ import {buildPageRange} from './buildPageRange';
 import {getRangeMax, getRangeMin} from './common/utils/helpers';
 import {PaginationModel} from './types';
 
+export const PaginationContext = React.createContext({} as PaginationModel);
+
 export type UsePaginationModelConfig = {
   /**
    * The page number for the last page (it can also be used as a total page
@@ -31,13 +33,8 @@ export type UsePaginationModelConfig = {
   rangeSize?: number;
 };
 
-export const usePaginationModel = ({
-  firstPage = 1,
-  initialCurrentPage = 1,
-  lastPage,
-  rangeSize = 5,
-  onPageChange,
-}: UsePaginationModelConfig): PaginationModel => {
+export const usePaginationModel = (config: UsePaginationModelConfig): PaginationModel => {
+  const {firstPage = 1, initialCurrentPage = 1, lastPage, rangeSize = 5, onPageChange} = config;
   const [currentPage, setCurrentPage] = React.useState(initialCurrentPage);
 
   const changePage = (page: number) => {

package/popup/lib/Popper.tsx

@@ -2,7 +2,7 @@ import * as React from 'react';
 import * as ReactDOM from 'react-dom';
 import * as PopperJS from '@popperjs/core';
 
-export type Placement = PopperJS.Placement;
+export type Placement = `${PopperJS.Placement}`; // Use template literals to make documentation list them out
 export type PopperOptions = PopperJS.Options;
 
 import {usePopupStack} from './hooks';
@@ -68,6 +68,21 @@ export interface PopperProps {
   popperInstanceRef?: React.Ref<PopperJS.Instance>;
 }
 
+/**
+ * A thin wrapper component around the Popper.js positioning engine. For reference:
+ * https://popper.js.org/. `Popper` also automatically works with the {@link PopupStack} system.
+ * `Popper` has no UI and will render any children to the `body` element and position around a
+ * provided `anchorElement`.
+ *
+ * Prefer using {@link PopupPopper Popup.Popper} instead. Use this to make Popups that don't utilize
+ * a PopupModel or any associate popup [hooks](#hooks).
+ *
+ * > **Note:** `Popper` renders any children to a `div` element created by the `PopupStack`. This
+ * > element is not controlled by React, so any extra element props will _not_ be forwarded. The
+ * > `ref` will point to the `div` element created by the `PopupStack`, however. In v4, an extra
+ * > `div` element was rendered and that's where extra props were spread to. In v5+, you can provide
+ * > your own element if you wish.
+ */
 export const Popper = React.forwardRef<HTMLDivElement, PopperProps>(
   ({portal = true, open = true, ...elemProps}: PopperProps, ref) => {
     if (!open) {

package/popup/lib/Popup.tsx

@@ -18,16 +18,97 @@ export interface PopupProps {
   children: React.ReactNode;
 }
 
+/**
+ * This component is a container component that has no semantic element. It provides a React Context
+ * model for all Popup subcomponents. A `model` can be manually passed to subcomponents to override
+ * the model context.
+ *
+ * ```tsx
+ * // using Popup
+ * <Popup model={model}>
+ *   <Popup.Target /> // no model here
+ * </Popup>
+ *
+ * // using models on subcomponents
+ * <>
+ *   <Popup.Target model={model} />
+ * </>
+ * ```
+ */
 export const Popup = createContainer()({
   displayName: 'Popup',
   modelHook: usePopupModel,
   subComponents: {
-    Heading: PopupHeading,
-    Body: PopupBody,
-    Card: PopupCard,
-    CloseIcon: PopupCloseIcon,
+    /**
+     * A `Popup.Target` is any element that is meant to show the Popup. The default component
+     * rendered by this component is a {@link SecondaryButton} element. You can override this by
+     * passing the desired component via `as`. Many examples above use `as={DeleteButton}`. If you
+     * want to render a {@link TertiaryButton} instead, use `as={TertiaryButton}`. The behavior hook
+     * used is called {@link usePopupTarget}.
+     *
+     * ```tsx
+     * const model = usePopupModel();
+     *
+     * // using this component
+     * <Popup.Target>Show Popup</PopupTarget>
+     *
+     * // using props instead
+     * const popupTargetButtonProps = usePopupTarget(model);
+     * <SecondaryButton {...popupTargetButtonProps}>Show Popup</SecondaryButton>
+     * ```
+     *
+     * `Popup.Target` doesn't provide any styling by default. All styling comes from the default
+     * component used, which is {@link SecondaryButton}. If you don't want any styling, you can do
+     * the following:
+     *
+     * ```tsx
+     * <Popup.Target as="button">Open</Popup.Target>
+     * ```
+     *
+     * To add your own styling, you could either add a `css` prop, or make a styled button and pass
+     * that styled component via the `as` prop.
+     */
     Target: PopupTarget,
+    /**
+     * A `Popup.Popper` is a {@link Popper} component that is hooked up to the {@link PopupModel}
+     * automatically. The behavior hook used is called {@link usePopupPopper}.
+     *
+     * > **Note:** `Popup.Popper` renders any children to a `div` element created by the
+     * > {@link PopupStack}. This element is not controlled by React, so any extra element props
+     * > will _not_ be forwarded. The `ref` will point to the `div` element created by the
+     * > `PopupStack`, however. If you wish to add extra props to an element, add them to the
+     * > {@link PopupCard Popup.Card} instead.
+     */
     Popper: PopupPopper,
+    /**
+     * A `Popup.Card` is a wrapper around the {@link Card} component, but hooked up to a
+     * {@link PopupModel}. By default, this element has a `role=dialog` and an `aria-labelledby`.
+     * The behavior hook used is called {@link usePopupCard}.
+     */
+    Card: PopupCard,
+    /**
+     * A `Popup.CloseIcon` is an icon button that is the `X` in the top of a popup. It will hide a
+     * popup when clicked. The behavior hook used is called {@link usePopupCloseButton}.
+     */
+    CloseIcon: PopupCloseIcon,
+    /**
+     * A `Popup.Heading` is a wrapper around {@link CardHeading Card.Heading} that connect the
+     * heading to a {@link PopupModel}. It will add an `id` to the element that match the
+     * `aria-labelledby` that is applied to the `Popup.Card` element for accessibility. The behavior
+     * hook used is called {@link usePopupHeading}.
+     */
+    Heading: PopupHeading,
+    /**
+     * A `Popup.Body` is a thin wrapper around {@link CardBody Card.Body} and doesn't actually take
+     * a model. It adds `body` styling and nothing else.
+     */
+    Body: PopupBody,
+    /**
+     * A `Popup.CloseButton` is a button that will hide a popup. By default, this is a
+     * {@link SecondaryButton} component, but `as` can be used to render any button element (i.e
+     * {@link DeleteButton} or {@link PrimaryButton}). The behavior hook used is called
+     * {@link usePopupCloseButton}.
+     */
     CloseButton: PopupCloseButton,
   },
 })<PopupProps>(({children}: PopupProps) => {

package/popup/lib/hooks/useBringToTopOnClick.ts

@@ -6,10 +6,10 @@ import {usePopupModel} from './usePopupModel';
 
 /**
  * This hook will bring an element to the top of the stack when any element inside the provided
- * PopupModel's `state.stackRef` element is clicked. If `Popup.Popper` was used or `PopupStack.add`
- * provided an `owner`, all "child" popups will also be brought to the top. A "child" popup is a
- * Popup that was opened from another Popup. Usually this is a Tooltip or Select component inside
- * something like a Modal.
+ * {@link PopupModel}'s `state.stackRef` element is clicked. If {@link PopupPopper Popup.Popper} was
+ * used or `PopupStack.add` provided an `owner`, all "child" popups will also be brought to the top.
+ * A "child" popup is a Popup that was opened from another Popup. Usually this is a Tooltip or
+ * Select component inside something like a Modal.
  *
  * This should be used on popup elements that are meant to persist (i.e. Windows).
  */

package/popup/lib/hooks/useCloseOnEscape.ts

@@ -6,8 +6,8 @@ import {createElemPropsHook} from '@workday/canvas-kit-react/common';
 import {usePopupModel} from './usePopupModel';
 
 /**
- * Registers global detection of the Escape key. It will only call the PopupModel's `hide` event if the
- * provided model's `state.stackRef` element is the topmost in the stack.
+ * Registers global detection of the Escape key. It will only call the {@link PopupModel}'s `hide`
+ * event if the provided model's `state.stackRef` element is the topmost in the stack.
  *
  * This should be used with popup elements that are dismissible like Tooltips, Modals, non-modal
  * dialogs, dropdown menus, etc.

package/popup/lib/hooks/useCloseOnOutsideClick.ts

@@ -6,14 +6,14 @@ import {createElemPropsHook} from '@workday/canvas-kit-react/common';
 import {usePopupModel} from './usePopupModel';
 
 /**
- * Registers global listener for all clicks. It will only call the PopupModel's `hide` event if the
- * click happened outside the PopupModel's `state.stackRef` element and its children _and_ the
- * provided `stackRef` element is the topmost element with this behavior applied in the stack. Adds
- * a `data-behavior-click-outside-close="topmost"` attribute to ensure proper functionality.
+ * Registers global listener for all clicks. It will only call the {@link PopupModel}'s `hide` event
+ * if the click happened outside the PopupModel's `state.stackRef` element and its children _and_
+ * the provided `stackRef` element is the topmost element with this behavior applied in the stack.
+ * Adds a `data-behavior-click-outside-close="topmost"` attribute to ensure proper functionality.
  *
  * This should be used with popup elements that are dismissible like Modals, non-modal dialogs,
- * dropdown menus, etc. Tooltips and hierarchical menus should use `useAlwaysCloseOnClickOutside`
- * instead.
+ * dropdown menus, etc. Tooltips and hierarchical menus should use
+ * {@link useAlwaysCloseOnClickOutside} instead.
  */
 export const useCloseOnOutsideClick = createElemPropsHook(usePopupModel)(model => {
   const onClick = React.useCallback(

package/popup/lib/hooks/useInitialFocus.tsx

@@ -11,8 +11,8 @@ import {usePopupModel} from './usePopupModel';
 
 /**
  * Moves focus within the popup when the popup becomes visible. This is useful for keyboard and
- * screen reader users alike. This should be used with `useFocusRedirect` or `useFocusTrap` for a
- * complete focus management solution.
+ * screen reader users alike. This should be used with {@link useFocusRedirect} or
+ * {@link useFocusTrap} for a complete focus management solution.
  *
  * This should be used for popups that have focusable elements inside, like Modals, non-modal
  * dialogs, menus, etc.

package/popup/lib/hooks/usePopupCard.ts

@@ -3,7 +3,7 @@ import {createElemPropsHook} from '@workday/canvas-kit-react/common';
 import {usePopupModel} from './usePopupModel';
 
 /**
- * Adds the necessary props to a `Card` component. Used by the `Popup.Card` subcomponent.
+ * Adds the necessary props to a {@link PopupCard Popup.Card} subcomponent.
  */
 export const usePopupCard = createElemPropsHook(usePopupModel)(({state}) => {
   return {

package/popup/lib/hooks/usePopupCloseButton.ts

@@ -2,8 +2,9 @@ import {createElemPropsHook} from '@workday/canvas-kit-react/common';
 import {usePopupModel} from './usePopupModel';
 
 /**
- * Adds the necessary props to a close button component. Used by the `Popup.CloseButton`
- * subcomponent and `Popup.CloseIcon` subcomponent.
+ * Adds the necessary props to a close button component. Used by the
+ * {@link PopupCloseButton Popup.CloseButton} subcomponent and
+ * {@link PopupCloseIcon Popup.CloseIcon} subcomponent.
  */
 export const usePopupCloseButton = createElemPropsHook(usePopupModel)(({events}) => {
   return {

package/popup/lib/hooks/usePopupHeading.ts

@@ -2,7 +2,7 @@ import {createElemPropsHook} from '@workday/canvas-kit-react/common';
 import {usePopupModel} from './usePopupModel';
 
 /**
- * Adds the necessary props to the `Heading` component. Used by the `Popup.Heading` subcomponent.
+ * Adds the necessary props to the {@link PopupHeading Popup.Heading} subcomponent.
  */
 export const usePopupHeading = createElemPropsHook(usePopupModel)(({state}) => {
   return {

package/popup/lib/hooks/usePopupPopper.ts

@@ -4,7 +4,8 @@ import React from 'react';
 import {Placement} from '../Popper';
 
 /**
- * Hooks a Popper up to a PopupModel
+ * Adds the necessary props to a {@link Popper} component. Used by the
+ * {@link PopupPopper Popup.Popper} subcomponent.
  */
 export const usePopupPopper = createElemPropsHook(usePopupModel)(({state, events}, ref) => {
   const elementRef = useForkRef(ref, state.stackRef);

package/popup/lib/hooks/usePopupStack.ts

@@ -4,38 +4,46 @@ import {PopupStack} from '@workday/canvas-kit-popup-stack';
 import {useLocalRef, useIsRTL} from '@workday/canvas-kit-react/common';
 
 /**
- * This hook should not be used directly. Use the `Popper` component instead.
+ * **Note:** If you're using {@link Popper}, you do not need to use this hook directly.
  *
- * This hook will add the `stackRef` element to the Popup stack on mount and remove on unmount. If
- * you use `Popper`, the popper `stackRef` is automatically added/removed from the Popup stack. The
- * Popup stack is required for proper z-index values to ensure Popups are rendered correct. It is
+ * This hook will add the `stackRef` element to the {@link PopupStack} on mount and remove on unmount. If
+ * you use `Popper`, the popper `stackRef` is automatically added/removed from the `PopupStack`. The
+ * `PopupStack` is required for proper z-index values to ensure Popups are rendered correct. It is
  * also required for global listeners like click outside or escape key closing a popup. Without the
- * Popup stack, all popups will close rather than only the topmost one.
+ * `PopupStack`, all popups will close rather than only the topmost one.
  *
- * If `forwardRef` is provided, it will be the same as `stackRef`. If `forwardRef` is not provided`,
+ * If `ref` is provided, it will be the same as `stackRef`. If `ref` is not provided`,
  * this hook will create one and return it.
  *
  * This hook should be used by all stacked UIs unless using the `Popper` component.
  *
- * @param forwardRef This ref will be managed by the PopupStack and should not be managed by React. Do
+ * ```tsx
+ * const model = usePopupModel();
+ * usePopupStack(model.state.stackRef, model.state.targetRef);
+ *
+ * // add some popup functionality
+ * useCloseOnOutsideClick(model);
+ * useCloseOnEscape(model);
+ *
+ * return (
+ *   <>
+ *     <button ref={model.state.targetRef}>Open Popup</button>
+ *     {model.state.visibility !== 'hidden'
+ *       ? ReactDOM.createPortal(<div>Popup Contents</div>, model.state.stackRef.current)
+ *       : null}
+ *   </>
+ * );
+ * ```
+ *
+ * @param ref This ref will be managed by the PopupStack and should not be managed by React. Do
  * not apply this stackRef to a React element. Doing so will result in an error. Instead, use this
  * `stackRef` directly with `ReactDOM.createPortal(<YourComponent>, stackRef.current!)`. This is
  * definitely strange for React code, but is necessary for the PopupStack to remain framework
- * agnostic and flexible to integrate with existing popup stack systems. If not provided, this hook
+ * agnostic and flexible to integrate with existing `PopupStack` systems. If not provided, this hook
  * will create one and return that `stackRef` instead.
- *
  * @param target Usually the trigger of a popup. This will fix `bringToTop` and should be provided
  * by all ephemeral-type popups (like Tooltips, Select menus, etc). It will also add in clickOutside
  * detection.
- *
- * @example
- * // must be part of a component life-cycle. Use `Popup.Popper` otherwise.
- * const model = usePopupModel({visibility: 'visible'})
- * usePopupStack(model.state.stackRef)
- *
- * // add some popup functionality
- * useCloseOnOutsideClick(model)
- * useCloseOnEscape(model)
  */
 export const usePopupStack = <E extends HTMLElement>(
   ref?: React.Ref<E>,

package/popup/lib/hooks/usePopupTarget.ts

@@ -2,7 +2,7 @@ import {createElemPropsHook, useForkRef} from '@workday/canvas-kit-react/common'
 import {usePopupModel} from './usePopupModel';
 
 /**
- * Adds the necessary props to a `Target` component. Used by the Popup.Target subcomponent.
+ * Adds the necessary props to a {@link PopupTarget Popup.Target} subcomponent.
  */
 export const usePopupTarget = createElemPropsHook(usePopupModel)(({events, state}, ref) => {
   const elementRef = useForkRef(ref, state.targetRef);

package/popup/lib/hooks/useReturnFocus.tsx

@@ -33,8 +33,8 @@ function getFocusableElement(element: Element | null): Element | null {
 
 /**
  * Returns focus to the target element when the popup is hidden. This works well with
- * `useInitialFocus`. This should be used with `useFocusRedirect` or `useFocusTrap` for a complete
- * focus management solution.
+ * {@link useInitialFocus}. This should be used with {@link useFocusRedirect} or
+ * {@link useFocusTrap} for a complete focus management solution.
  *
  * This should be used on popup elements that use `useInitialFocus`.
  */

package/radio/lib/RadioGroup.tsx

@@ -67,7 +67,7 @@ const Container = styled('div')<Pick<RadioGroupProps, 'error' | 'grow' | 'theme'
   }
 );
 
-class RadioGroup extends React.Component<RadioGroupProps> {
+export class RadioGroup extends React.Component<RadioGroupProps> {
   static ErrorType = ErrorType;
 
   render(): React.ReactNode {
@@ -120,5 +120,3 @@ class RadioGroup extends React.Component<RadioGroupProps> {
 }
 
 RadioGroup.ErrorType = ErrorType;
-
-export {RadioGroup};

package/select/lib/Select.tsx

@@ -118,22 +118,9 @@ const SelectWrapper = styled('div')<Pick<SelectProps, 'grow' | 'disabled'>>(
 
 export const Select = createComponent('select')({
   displayName: 'Select',
-  Component: (
-    {disabled = false, error, grow, children, value, onChange, ...elemProps}: SelectProps,
-    ref,
-    Element
-  ) => (
+  Component: ({disabled = false, grow, children, ...elemProps}: SelectProps, ref, Element) => (
     <SelectWrapper grow={grow} disabled={disabled}>
-      <StyledSelect
-        as={Element}
-        disabled={disabled}
-        grow={grow}
-        error={error}
-        ref={ref}
-        value={value}
-        onChange={onChange}
-        {...elemProps}
-      >
+      <StyledSelect as={Element} disabled={disabled} grow={grow} ref={ref} {...elemProps}>
         {children}
       </StyledSelect>
       <SelectDropdownIcon

package/skeleton/lib/skeleton.tsx

@@ -39,6 +39,19 @@ const SkeletonAnimator = styled('div')<SkeletonProps & StyledType>({
   position: 'relative',
 });
 
+/**
+ * Skeleton subcomponents **must** be wrapped by the `Skeleton` container component.
+ *
+ * ```tsx
+ * <Skeleton>
+ *   <Skeleton.Header />
+ *   <Skeleton.Text />
+ * </Skeleton>
+ * ```
+ *
+ * `Skeleton` places its children in a container element with `aria-hidden` set to `true` and
+ * announces itself using a visually hidden element.
+ */
 export const Skeleton = createComponent('div')({
   displayName: 'Skeleton',
   Component: (
@@ -53,8 +66,21 @@ export const Skeleton = createComponent('div')({
     </SkeletonAnimator>
   ),
   subComponents: {
+    /**
+     * `Skeleton.Header` renders a placeholder for header content such as headings.
+     */
     Header: SkeletonHeader,
-    Shape: SkeletonShape,
+    /**
+     * `Skeleton.Text` renders a placeholder for text content such as paragraphs. Each placeholder
+     * line has a width of `100%` and a fixed height of `21px`, with the last line having a width of
+     * `60%` if there are multiple lines.
+     */
     Text: SkeletonText,
+    /**
+     * `Skeleton.Shape` renders a placeholder for graphic elements such as icons, avatars and small
+     * images. Set the `height`, `width`, and `borderRadius` props of the `Skeleton.Shape` to create
+     * various rectangular and circular shapes.
+     */
+    Shape: SkeletonShape,
   },
 });

package/tabs/lib/Tabs.tsx

@@ -19,29 +19,121 @@ export interface TabsProps {
   children: React.ReactNode;
 }
 
+/**
+ * `Tabs` is a container component that is responsible for creating a {@link TabsModel} and sharing
+ * it with its subcomponents using React context. It does not represent a real element.
+ *
+ * ```tsx
+ * <Tabs onSelect={data => console.log('Selected tab', data.id)}>
+ *   {child components}
+ * </Tabs>
+ * ```
+ *
+ * Alternatively, you may pass in a model using the hoisted model pattern.
+ *
+ * ```tsx
+ * const model = useTabsModel({
+ *   onSelect(data) {
+ *     console.log('Activated Tab', data.id);
+ *   },
+ * });
+ *
+ * <Tabs model={model}>{child components}</Tabs>
+ * ```
+ *
+ * See [Configuring a
+ * Model](/getting-started/for-developers/resources/compound-components/#configuring-a-model) for
+ * more information on model configuration.
+ */
 export const Tabs = createContainer()({
   displayName: 'Tabs',
   modelHook: useTabsModel,
   subComponents: {
+    /**
+     * `Tabs.List` is a `<div role="tablist">` element. It is a container for {@link TabsItem Tabs.Item}
+     * subcomponents.
+     *
+     * ```tsx
+     * <Tabs.List>{Tabs.Items}</Tabs.List>
+     * ```
+     */
     List: TabsList,
+    /**
+     * `Tabs.Item` is a `<button role="tab">` element. Each `Tabs.Item` is associated with a
+     * `Tabs.Panel` either by a `data-id` attribute or by the position in the list. If a `data-id`
+     * is provided, it must match the `data-id` passed to the corresponding `Tabs.Panel` component.
+     *
+     * ```tsx
+     * <Tabs.Item data-id="first">First Tab</Tabs.Item>
+     * ```
+     */
     Item: TabsItem,
+    /**
+     * `Tabs.Panel` is a `<div role="tabpanel">` element. It is focusable by default. Each
+     * `Tabs.Panel` is controlled by a `Tabs.Item` either by a `data-id` attribute or by the
+     * position in the list. If a `data-id` is provided, it must match the `data-id` passed to the
+     * corresponding `Tabs.Item` component.
+     *
+     * ```tsx
+     * <Tabs.Panel data-id="first">
+     *   {contents of tab panel}
+     * </Tabs.Panel>
+     * ```
+     */
     Panel: TabsPanel,
+    /**
+     * Optional subcomponent of tabs that makes dealing with dynamic tabs easier. `Tabs.Panels` only
+     * works if the model is given an array of items.
+     *
+     * ```tsx
+     * const items = [{ id: '1', name: 'first' }]
+     * <Tabs items={items}>
+     *   {tab list}
+     *   <Tabs.Panels>
+     *     {item => <Tabs.Panel>Contents of {item.name}</Tabs.Panel>}
+     *   </Tabs.Panels>
+     * </Tabs>
+     * ```
+     */
     Panels: TabsPanels,
+    /**
+     * The overflow button of a `Tabs.List`. When a tab list overflows, this overflow button is
+     * rendered. Overflow only works when the model is given an array of `items`.
+     *
+     * ```tsx
+     * <Tabs items={items}>
+     *   <Tabs.List overflowButton={
+     *     <Tabs.OverflowButton>More</Tabs.OverflowButton>
+     *   }>
+     *     {dynamic tab items}
+     *   </Tabs.List>
+     * </Tabs>
+     * ```
+     */
     OverflowButton: TabsOverflowButton,
+    /**
+     * @deprecated Use `Tabs.Menu.Popper` instead
+     */
     MenuPopper: TabsMenuPopper,
     /**
      * The overflow menu of the Tabs component. If there isn't enough room to render all the tab
      * items, the extra tabs that don't fit will be overflowed into this menu.
-     * @example
+     *
+     * ```tsx
      * <Tabs.Menu.Popper>
      *   <Tabs.Menu.Card>
      *     <Tabs.Menu.List>
-     *       {(item: MyTabItem) => <Tabs.Menu.Item data-id={item.id}>{item.text}</Tabs.Menu.Item>}
+     *       {(item: MyTabItem) => <Tabs.Menu.Item data-id={item.id}>
+     *         {item.text}
+     *       </Tabs.Menu.Item>}
      *     </Tabs.Menu.List>
      *   </Tabs.Menu.Card>
      * </Tabs.Menu.Popper>
+     * ```
      */
-    Menu,
+    // We don't use shorthand here for documentation. The shorthand will give the `Tabs.Menu` the
+    // JSDoc of `Menu` instead of `Tabs.Menu`
+    Menu: Menu,
   },
 })<TabsProps>(({children}, _, model) => {
   return <Menu model={model.menu}>{children}</Menu>;