@workday/canvas-kit-react 9.0.0-alpha.338-next.5 → 9.0.0-alpha.348-next.3

package/pagination/lib/Pagination/Pagination.tsx

@@ -1,165 +1,282 @@
 import * as React from 'react';
-import {TertiaryButtonProps} from '@workday/canvas-kit-react/button';
+import {createComponent} from '@workday/canvas-kit-react/common';
+import {Flex, FlexProps} from '@workday/canvas-kit-react/layout';
 
 import {PaginationModel} from './types';
-import {usePaginationModel, UsePaginationModelConfig} from './usePaginationModel';
+import {
+  usePaginationModel,
+  UsePaginationModelConfig,
+  PaginationContext,
+} from './usePaginationModel';
 
-import {PaginationNav, PaginationNavProps} from './Nav';
 import {
   JumpToFirstButton,
   StepToPreviousButton,
   StepToNextButton,
   JumpToLastButton,
-  Controls,
-  ControlsProps,
+  PaginationControls,
 } from './Controls';
 
-import {PageList, PageListProps, PageListItem, PageListItemProps} from './PageList';
-import {PageButton, PageButtonProps} from './PageButton';
-
-import {GoTo} from './GoTo';
-import {GoToFormProps} from './GoTo/Form';
-import {GoToLabelProps} from './GoTo/Label';
-import {GoToTextInputProps} from './GoTo/TextInput';
+import {PageList, PageListItem} from './PageList';
+import {PageButton} from './PageButton';
+import {AdditionalDetails} from './AdditionalDetails';
+import {GoToForm} from './GoTo/Form';
+import {GoToTextInput} from './GoTo/TextInput';
+import {GoToLabel} from './GoTo/Label';
 
-import {AdditionalDetails, AdditionalDetailsProps} from './AdditionalDetails';
+export {PaginationContext};
 
-export const PaginationContext = React.createContext({} as PaginationModel);
-
-type PaginationConfigurationProps = PaginationNavProps & {
-  lastPage: number;
+export type PaginationProps = PaginationNavProps & {
+  lastPage?: number;
   firstPage?: number;
   initialCurrentPage?: number;
   rangeSize?: number;
-  model?: never;
+  model?: PaginationModel;
   onPageChange?: (pageNumber: number) => void;
 };
 
-type PaginationModelProps = PaginationNavProps & {
-  lastPage?: never;
-  firstPage?: never;
-  initialCurrentPage?: never;
-  rangeSize?: never;
-  model: PaginationModel;
-  onPageChange?: never;
-};
-
 function useDefaultModel<T, C>(model: T | undefined, config: C, fn: (config: C) => T) {
   return model || fn(config);
 }
 
-export type PaginationProps = PaginationConfigurationProps | PaginationModelProps;
-
-export const Pagination = (props: PaginationProps) => {
-  const model = useDefaultModel(props.model, props as UsePaginationModelConfig, usePaginationModel);
-
-  const {
-    'aria-label': ariaLabel,
-    children,
-    lastPage,
-    firstPage,
-    initialCurrentPage,
-    rangeSize,
-    onPageChange,
-    ...restProps
-  } = props;
-
-  return (
-    <PaginationContext.Provider value={model}>
-      <PaginationNav aria-label={ariaLabel} {...restProps}>
-        {children}
-      </PaginationNav>
-    </PaginationContext.Provider>
-  );
-};
-
-Pagination.Controls = (props: ControlsProps) => {
-  return <Controls {...props} />;
-};
-
-Pagination.JumpToFirstButton = (
-  props: TertiaryButtonProps & React.ButtonHTMLAttributes<HTMLButtonElement>
-) => {
-  // The linter doesn't recognize the dot syntax, so we're disabling the rule
-  // eslint-disable-next-line react-hooks/rules-of-hooks
-  const model = React.useContext(PaginationContext);
-  return <JumpToFirstButton model={model} {...props} />;
-};
-
-Pagination.StepToPreviousButton = (
-  props: TertiaryButtonProps & React.ButtonHTMLAttributes<HTMLButtonElement>
-) => {
-  // The linter doesn't recognize the dot syntax, so we're disabling the rule
-  // eslint-disable-next-line react-hooks/rules-of-hooks
-  const model = React.useContext(PaginationContext);
-  return <StepToPreviousButton model={model} {...props} />;
-};
-
-Pagination.StepToNextButton = (
-  props: TertiaryButtonProps & React.ButtonHTMLAttributes<HTMLButtonElement>
-) => {
-  // The linter doesn't recognize the dot syntax, so we're disabling the rule
-  // eslint-disable-next-line react-hooks/rules-of-hooks
-  const model = React.useContext(PaginationContext);
-  return <StepToNextButton model={model} {...props} />;
-};
-
-Pagination.JumpToLastButton = (
-  props: TertiaryButtonProps & React.ButtonHTMLAttributes<HTMLButtonElement>
-) => {
-  // The linter doesn't recognize the dot syntax, so we're disabling the rule
-  // eslint-disable-next-line react-hooks/rules-of-hooks
-  const model = React.useContext(PaginationContext);
-  return <JumpToLastButton model={model} {...props} />;
-};
-
-Pagination.PageList = (props: Omit<PageListProps, 'model'>) => {
-  // The linter doesn't recognize the dot syntax, so we're disabling the rule
-  // eslint-disable-next-line react-hooks/rules-of-hooks
-  const model = React.useContext(PaginationContext);
-  return <PageList model={model} {...props} />;
-};
-
-Pagination.PageListItem = (props: PageListItemProps) => {
-  return <PageListItem {...props} />;
-};
-
-Pagination.PageButton = ({
-  'aria-label': ariaLabel,
-  ...elemProps
-}: Omit<PageButtonProps, 'model'>) => {
-  // The linter doesn't recognize the dot syntax, so we're disabling the rule
-  // eslint-disable-next-line react-hooks/rules-of-hooks
-  const model = React.useContext(PaginationContext);
-  return <PageButton aria-label={ariaLabel} model={model} {...elemProps} />;
-};
-
-Pagination.AdditionalDetails = (props: Omit<AdditionalDetailsProps, 'model'>) => {
-  // The linter doesn't recognize the dot syntax, so we're disabling the rule
-  // eslint-disable-next-line react-hooks/rules-of-hooks
-  const model = React.useContext(PaginationContext);
-  return <AdditionalDetails model={model} {...props} />;
-};
-
-Pagination.GoToForm = ({children}: GoToFormProps) => {
-  // The linter doesn't recognize the dot syntax, so we're disabling the rule
-  // eslint-disable-next-line react-hooks/rules-of-hooks
-  const model = React.useContext(PaginationContext);
-  return (
-    <GoTo model={model}>
-      <GoTo.Form>{children}</GoTo.Form>
-    </GoTo>
-  );
-};
+export interface PaginationNavProps extends FlexProps {
+  'aria-label': string;
+}
 
-Pagination.GoToTextInput = (props: GoToTextInputProps) => {
-  return <GoTo.TextInput {...props} />;
-};
+/**
+ * `Pagination` is a container component rendered as a `<nav>` element that is responsible for creating
+ * a `PaginationModel` and sharing it with its subcomponents using React context.
+ *
+ * ```tsx
+ * <Pagination
+ *   aria-label="Pagination"
+ *   lastPage={100}
+ *   initialCurrentPage={6}
+ *   rangeSize={3}
+ *   onPageChange={pageNumber => console.log(pageNumber)}
+ * >
+ *   {Child components}
+ * </Pagination>
+ * ```
+ *
+ * Alternatively, you may pass in a model using the hoisted model pattern.
+ *
+ * ```tsx
+ * const model = usePaginationModel({
+ *   lastPage: 100,
+ *   initialCurrentPage: 6,
+ *   rangeSize: 3,
+ *   onPageChange: pageNumber => console.log(pageNumber),
+ * });
+ *
+ * return (
+ *   <Pagination aria-label="Pagination" model={model}>
+ *     {Child components}
+ *   </Pagination>
+ * );
+ * ```
+ */
+export const Pagination = createComponent('nav')({
+  displayName: 'Pagination',
+  Component(props: PaginationProps, ref, Element) {
+    const model = useDefaultModel(
+      props.model,
+      props as UsePaginationModelConfig,
+      usePaginationModel
+    );
 
-Pagination.GoToLabel = (props: Omit<GoToLabelProps, 'model'>) => {
-  // The linter doesn't recognize the dot syntax, so we're disabling the rule
-  // eslint-disable-next-line react-hooks/rules-of-hooks
-  const model = React.useContext(PaginationContext);
+    const {lastPage, firstPage, initialCurrentPage, rangeSize, onPageChange, ...elemProps} = props;
 
-  return <GoTo.Label model={model} {...props} />;
-};
+    return (
+      <PaginationContext.Provider value={model}>
+        <Flex
+          ref={ref}
+          as={Element}
+          display="inline-flex"
+          flexDirection="column"
+          alignItems="center"
+          {...elemProps}
+        />
+      </PaginationContext.Provider>
+    );
+  },
+  subComponents: {
+    /**
+     * `Pagination.Controls` provides proper alignment and spacing between elements inside
+     * `Pagination`. It does not handle any internal business logic or state.
+     *
+     * ```tsx
+     * <Pagination.Controls>{Child components}</Pagination.Controls>
+     * ```
+     */
+    Controls: PaginationControls,
+    /**
+     * `Pagination.JumpToFirstButton` is a {@link TertiaryButton} that subscribes to the
+     * `Pagination` context. This allows it to know when to disable and set `currentPage` to the
+     * first page.
+     *
+     * Note that you must set `aria-label` to meet accessibility standards. We recommend setting it
+     * to `First` or the translated equivalent.
+     *
+     * ```tsx
+     * <Pagination.JumpToFirstButton aria-label="First" />
+     * ```
+     */
+    JumpToFirstButton,
+    /**
+     * `Pagination.StepToPreviousButton` is a {@link TertiaryButton} that renders an icon that
+     * subscribes to the `Pagination` context. This allows it to know when to disable and decrement
+     * the `currentPage`.
+     *
+     * Note that you must set `aria-label` to meet accessibility standards. We recommend setting it
+     * to `Previous` or the translated equivalent.
+     *
+     * ```tsx
+     * <Pagination.StepToPreviousButton aria-label="Previous" />
+     * ```
+     */
+    StepToPreviousButton,
+    /**
+     * `Pagination.StepToNextButton` is a {@link TertiaryButton} that subscribes to the `Pagination`
+     * context. This allows it to know when to disable and increment the `currentPage`.
+     *
+     * Note that you must set `aria-label` to meet accessibility standards. We recommend setting it
+     * to `Next` or the translated equivalent.
+     *
+     * ```tsx
+     * <Pagination.StepToNextButton aria-label="Next" />
+     * ```
+     */
+    StepToNextButton,
+    /**
+     * `Pagination.JumpToLastButton` is a {@link TertiaryButton} that renders an icon that
+     * subscribes to the `Pagination` context. This allows it to know when to disable and set
+     * `currentPage` to the last page.
+     *
+     * Note that you must set `aria-label` to meet accessibility standards. We recommend setting it
+     * to `Last` or the translated equivalent.
+     *
+     * ```tsx
+     * <Pagination.JumpToLastButton aria-label="Last" />
+     * ```
+     */
+    JumpToLastButton,
+    /**
+     * `Pagination.PageList` subscribes to the `Pagination` context. This allows it generate the
+     * `range` of page numbers. It also handles spacing between the child elements.
+     *
+     * This component will accept either child elements or a render prop. In most cases, you'll want
+     * to use the render prop so you can access the `Pagination` model in order to generate the
+     * proper list items.
+     *
+     * ```tsx
+     * <Pagination.PageList>
+     *   {({state}) =>
+     *     state.range.map(pageNumber => (
+     *       <Pagination.PageListItem key={pageNumber}>
+     *         <Pagination.PageButton aria-label={`Page ${pageNumber}`} pageNumber={pageNumber} />
+     *       </Pagination.PageListItem>
+     *     ))
+     *   }
+     * </Pagination.PageList>
+     * ```
+     */
+    PageList,
+    /**
+     * `Pagination.PageListItem` provides a semantic child element for the `PageList` component and
+     * is important for accessibility. It does not handle any internal business logic or state.
+     *
+     * ```tsx
+     * <Pagination.PageListItem>{Child element}</Pagination.PageListItem>
+     * ```
+     */
+    PageListItem,
+    /**
+     * `Pagination.PageButton` subscribes to the `Pagination` context. This allows it to update the
+     * `currentPage` and set the `toggled` styling when it is the current item.
+     *
+     * `Pagination.PageButton` will render `pageNumber` as its children.
+     *
+     * ```tsx
+     * <Pagination.PageButton aria-label="Page 2" pageNumber={2} />
+     * ```
+     *
+     * Note that you must set `aria-label` to meet accessibility standards. We recommend setting it
+     * to `Page ${pageNumber}` or the translated equivalent.
+     */
+    PageButton,
+    /**
+     * `Pagination.GoToForm` is a wrapper for a React context provider rendered as a `<form>`
+     * element. Child components such as {@link GoToTextInput Pagination.GoToTextInput} and
+     * {@link GoToLabel Pagination.GoToLabel} subscribe to that context to manage the form state and
+     * behavior as well as update the `currentPage` in the `Pagination` component.
+     *
+     * ```tsx
+     * <Pagination.GoToForm>{Child elements}</Pagination.GoToForm>
+     * ```
+     */
+    GoToForm,
+    /**
+     * `Pagination.GoToTextInput` is a {@link TextInput}.
+     *
+     * ```tsx
+     * <Pagination.GoToTextInput aria-label="Go to page number" />
+     * ```
+     *
+     * Note that you must set `aria-label` to meet accessibility standards. We recommend setting it
+     * to `Go to page number` or the translated equivalent.
+     */
+    GoToTextInput,
+    /**
+     * `Pagination.GoToLabel` subscribes to the `Pagination` context. This allows it to pass the
+     * `Pagination` context to child elements.
+     *
+     * This component will accept either child elements or a render prop. In most cases, you'll want
+     * to use the render prop so you can access the `Pagination` model when generating the label
+     * text.
+     *
+     * ```tsx
+     * <Pagination.GoToLabel>{({state}) => `of ${state.lastPage} pages`}</Pagination.GoToLabel>
+     * ```
+     */
+    GoToLabel,
+    /**
+     * `Pagination.AdditionalDetails` subscribes to the `Pagination` context. This allows it to pass
+     * the `Pagination` context to child elements. It is also an `aria-live` region that announces
+     * the current page update to screen readers.
+     *
+     * `Pagination.AdditionalDetails` must be included in your `Pagination` component to meet
+     * accessibility standards (with one exception, see below). If you wish to prevent it from
+     * displaying, you may set its `shouldHideDetails` prop to `true`. The visually hidden region
+     * will still be accessible to screen readers.
+     *
+     * If you have multiple `Pagination` components sharing the same state and rendered on the same
+     * page, you may do either of the following to prevent screen readers from announcing the same
+     * update multiple times:
+     *
+     * - Exclude `Pagination.AdditionalDetails` from all but one of the `Pagination` components.
+     *   This is the one case where you may exclude `Pagination.AdditionalDetails` from a
+     *   `Pagination` component.
+     * - Include `Pagination.AdditionalDetails` in every `Pagination` component (i.e., you want it
+     *   to be visible for every component), but set the `shouldAnnounceToScreenReader` prop to
+     *   `false` on all but one of them.
+     *
+     * This component will accept either child elements or a render prop. In most cases, you'll want
+     * to use the render prop so you can access the `Pagination` model in order to generate the
+     * appropriate text.
+     *
+     * ```tsx
+     * <Pagination.AdditionalDetails>
+     *   {({state}) =>
+     *     `${getVisibleResultsMin(state.currentPage, resultCount)}-${getVisibleResultsMax(
+     *       state.currentPage,
+     *       resultCount,
+     *       totalCount
+     *     )} of ${totalCount} results`
+     *   }
+     * </Pagination.AdditionalDetails>
+     * ```
+     */
+    AdditionalDetails,
+  },
+});

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) => {