@workday/canvas-kit-react 7.1.4 → 7.2.0-427-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,18 +33,16 @@ 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) => {
-    onPageChange?.(page);
-
+    // Don't fire an `onPageChange` event if the page number is the same as the current page.
+    // `setCurrentPage` doesn't need this check, because React won't update the state if the values are the same.
+    if (currentPage !== page) {
+      onPageChange?.(page);
+    }
     setCurrentPage(page);
   };
 

package/pagination/package.json

@@ -1,5 +1,6 @@
 {
   "main": "../dist/commonjs/pagination",
   "module": "../dist/es6/pagination",
-  "sideEffects": false
+  "sideEffects": false,
+  "types": "../dist/es6/pagination"
 }

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</Popup.Target>
+     *
+     * // 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/PopupBody.tsx

@@ -8,5 +8,5 @@ export const PopupBody = createSubcomponent('div')({
   displayName: 'Popup.Body',
   modelHook: usePopupModel,
 })<ExtractProps<typeof Card.Body>>(elemProps => {
-  return <Card.Body overflowY="auto" {...elemProps} />;
+  return <Card.Body overflowY="auto" padding="xxs" {...elemProps} />;
 });

package/popup/lib/PopupCard.tsx

@@ -2,7 +2,7 @@ import * as React from 'react';
 import {keyframes} from '@emotion/react';
 
 import {Card} from '@workday/canvas-kit-react/card';
-import {space, type, CanvasSpaceKeys} from '@workday/canvas-kit-react/tokens';
+import {space, type} from '@workday/canvas-kit-react/tokens';
 import {
   styled,
   TransformOrigin,
@@ -12,12 +12,13 @@ import {
   useConstant,
   createSubcomponent,
 } from '@workday/canvas-kit-react/common';
-import {Stack, StackStyleProps} from '@workday/canvas-kit-react/layout';
+import {Flex, FlexStyleProps} from '@workday/canvas-kit-react/layout';
 
 import {getTransformFromPlacement} from './getTransformFromPlacement';
 import {usePopupCard, usePopupModel} from './hooks';
 
-export interface PopupCardProps extends ExtractProps<typeof Card, never>, Partial<StackStyleProps> {
+export type FlexAndBoxProps = ExtractProps<typeof Card, never> & FlexStyleProps;
+export interface PopupCardProps extends FlexAndBoxProps {
   children?: React.ReactNode;
 }
 
@@ -38,15 +39,22 @@ const popupAnimation = (transformOrigin: TransformOrigin) => {
 
 const StyledPopupCard = styled(Card)<
   StyledType & {width?: number | string; transformOrigin?: TransformOrigin}
->(type.levels.subtext.large, ({transformOrigin}) => {
+>(({transformOrigin, theme}) => {
   if (transformOrigin == null) {
     return {};
   }
+
   return {
     animation: popupAnimation(transformOrigin),
     animationDuration: '150ms',
     animationTimingFunction: 'ease-out',
     transformOrigin: `${transformOrigin.vertical} ${transformOrigin.horizontal}`,
+    [theme.canvas.breakpoints.down('s')]: {
+      animation: popupAnimation({vertical: 'bottom', horizontal: 'center'}),
+      animationDuration: '150ms',
+      animationTimingFunction: 'ease-out',
+      transformOrigin: 'bottom center',
+    },
     // Allow overriding of animation in special cases
     '.wd-no-animation &': {
       animation: 'none',
@@ -54,6 +62,35 @@ const StyledPopupCard = styled(Card)<
   };
 });
 
+function getSpace(value?: string | number) {
+  if (value && value in space) {
+    return space[value as keyof typeof space];
+  } else {
+    return value;
+  }
+}
+
+function getMaxHeight(margin?: string | number) {
+  // set the default margin offset to space.xl
+  let marginOffset: string | number = space.xl;
+
+  if (margin) {
+    // parse the margin prop
+    if (typeof margin === 'string') {
+      const marginValues = margin.split(' ');
+      const marginTop = getSpace(marginValues[0]);
+      // If provided, use the specific margin-bottom in the shorthand, otherwise use the margin-top value
+      const marginBottom = getSpace(marginValues[2]) || marginTop;
+
+      marginOffset = `(${marginTop} + ${marginBottom})`;
+    } else {
+      // if margin is a number, double it to get the offset
+      marginOffset = `${margin * 2}px`;
+    }
+  }
+  return `calc(100vh - ${marginOffset})`;
+}
+
 export const PopupCard = createSubcomponent('div')({
   displayName: 'Popup.Card',
   modelHook: usePopupModel,
@@ -63,24 +100,21 @@ export const PopupCard = createSubcomponent('div')({
     return getTransformFromPlacement(model.state.placement || 'bottom');
   }, [model.state.placement]);
 
-  // As is a Stack that will render an element of `Element`
-  const As = useConstant(() => Stack.as(Element));
-
+  // As is a Flex that will render an element of `Element`
+  const As = useConstant(() => Flex.as(Element));
   return (
     <StyledPopupCard
       as={As}
       transformOrigin={transformOrigin}
       position="relative"
-      padding="l"
       depth={5}
       maxWidth={`calc(100vw - ${space.l})`}
-      spacing={0}
       flexDirection="column"
       minHeight={0}
-      maxHeight={`calc(100vh - ${
-        elemProps.margin ? space[elemProps.margin as CanvasSpaceKeys] || elemProps.margin : space.xl
-      } * 2)`}
-      overflowY="auto" // force IE11 to limit the flex size of the card. Without this, the body isn't allowed to overflow properly: https://github.com/philipwalton/flexbugs/issues/216#issuecomment-453053557
+      padding="m"
+      maxHeight={getMaxHeight(elemProps.margin)}
+      overflowY="auto"
+      {...type.levels.subtext.large}
       {...elemProps}
     >
       {children}

package/popup/lib/PopupCloseButton.tsx

@@ -14,5 +14,9 @@ export const PopupCloseButton = createSubcomponent(SecondaryButton)({
   modelHook: usePopupModel,
   elemPropsHook: usePopupCloseButton,
 })<PopupCloseButtonProps>(({children, ...elemProps}: PopupCloseButtonProps, Element) => {
-  return <Element {...elemProps}>{children}</Element>;
+  return (
+    <Element type="button" {...elemProps}>
+      {children}
+    </Element>
+  );
 });

package/popup/lib/PopupCloseIcon.tsx

@@ -1,30 +1,29 @@
 import React from 'react';
 
 import {xIcon} from '@workday/canvas-system-icons-web';
-import {
-  styled,
-  createSubcomponent,
-  StyledType,
-  ExtractProps,
-} from '@workday/canvas-kit-react/common';
+import {createSubcomponent, ExtractProps} from '@workday/canvas-kit-react/common';
 import {TertiaryButton} from '@workday/canvas-kit-react/button';
+import {space} from '@workday/canvas-kit-react/tokens';
 
 import {usePopupCloseButton, usePopupModel} from './hooks';
 
-const closeIconSpacing = 4;
-
 export interface PopupCloseIconProps extends ExtractProps<typeof TertiaryButton, never> {}
 
-const StyledCloseIcon = styled(TertiaryButton)<StyledType & PopupCloseIconProps>({
-  position: 'absolute',
-  right: closeIconSpacing,
-  top: closeIconSpacing,
-});
-
 export const PopupCloseIcon = createSubcomponent('button')({
   displayName: 'Popup.CloseIcon',
   modelHook: usePopupModel,
   elemPropsHook: usePopupCloseButton,
 })<PopupCloseIconProps>(({children, ...elemProps}, Element) => {
-  return <StyledCloseIcon as={Element} size="medium" icon={xIcon} {...elemProps} />;
+  return (
+    <TertiaryButton
+      as={Element}
+      size="medium"
+      icon={xIcon}
+      type="button"
+      position="absolute"
+      right={space.xxxs}
+      top={space.xxxs}
+      {...elemProps}
+    />
+  );
 });

package/popup/lib/PopupHeading.tsx

@@ -15,7 +15,7 @@ export const PopupHeading = createSubcomponent('h2')({
   elemPropsHook: usePopupHeading,
 })<PopupHeadingProps>(({children, ...elemProps}, Element) => {
   return (
-    <Card.Heading as={Element} marginBottom="s" {...elemProps}>
+    <Card.Heading as={Element} marginBottom="xxs" padding="xxs" {...elemProps}>
       {children}
     </Card.Heading>
   );

package/popup/lib/PopupPopper.tsx

@@ -3,9 +3,9 @@ import * as React from 'react';
 import {createSubcomponent} from '@workday/canvas-kit-react/common';
 
 import {usePopupModel, usePopupPopper} from './hooks';
-import {Placement, PopperOptions, Popper} from './Popper';
+import {Placement, PopperOptions, Popper, PopperProps} from './Popper';
 
-export interface PopupPopperProps {
+export interface PopupPopperProps extends PopperProps {
   /**
    * The placement of the `Popper` contents relative to the `anchorElement`. Accepts `auto`, `top`,
    * `right`, `bottom`, or `left`. Each placement can also be modified using any of the following
@@ -17,7 +17,6 @@ export interface PopupPopperProps {
    * The additional options passed to the Popper's `popper.js` instance.
    */
   popperOptions?: Partial<PopperOptions>;
-  children?: React.ReactNode;
 }
 
 export const PopupPopper = createSubcomponent('div')({

package/popup/lib/hooks/index.ts

@@ -4,6 +4,7 @@ export * from './useBringToTopOnClick';
 export * from './useCloseOnEscape';
 export * from './useCloseOnFullscreenExit';
 export * from './useCloseOnOutsideClick';
+export * from './useCloseOnTargetHidden';
 export * from './useDisableBodyScroll';
 export * from './useFocusRedirect';
 export * from './useFocusTrap';

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/useCloseOnFullscreenExit.ts

@@ -12,7 +12,7 @@ import {usePopupModel} from './usePopupModel';
  */
 export const useCloseOnFullscreenExit = createElemPropsHook(usePopupModel)(model => {
   const handler = React.useCallback(
-    event => {
+    (event: any) => {
       if (!screenfull.isFullscreen) {
         model.events.hide(event);
       }

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/useCloseOnTargetHidden.ts

@@ -0,0 +1,66 @@
+import React from 'react';
+
+import {createElemPropsHook} from '@workday/canvas-kit-react/common';
+import {usePopupModel} from '@workday/canvas-kit-react/popup';
+
+function getScrollParent(element: HTMLElement): HTMLElement {
+  if (element === document.body || !element.parentElement) {
+    return element;
+  }
+  const styles = getComputedStyle(element);
+
+  if (
+    styles.overflowY === 'scroll' ||
+    styles.overflowY === 'auto' ||
+    styles.overflowX === 'scroll' ||
+    styles.overflowX === 'auto'
+  ) {
+    return element;
+  }
+
+  return getScrollParent(element.parentElement);
+}
+
+/**
+ * Sets up an
+ * [IntersectionObserver](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API)
+ * for the target element. When the target is detected as being less than 50% visible, the popup
+ * will close. Most likely, this will happen if the user scrolls an overflowed content area of the
+ * page and the target is no longer visible.
+ *
+ * This should be used with popup elements that are transitory like Tooltips and dropdown menus.
+ */
+export const useCloseOnTargetHidden = createElemPropsHook(usePopupModel)(model => {
+  const visible = model.state.visibility !== 'hidden';
+
+  const callback: IntersectionObserverCallback = React.useCallback(
+    entries => {
+      if (entries[0].intersectionRatio < 0.5) {
+        model.events.hide();
+      }
+    },
+    [model.events]
+  );
+
+  React.useLayoutEffect(() => {
+    if (!visible || !model.state.targetRef.current) {
+      return;
+    }
+
+    const target = model.state.targetRef.current;
+    const scrollParent = getScrollParent(target);
+
+    // eslint-disable-next-line compat/compat
+    const observer = new IntersectionObserver(callback, {
+      root: scrollParent,
+      threshold: 0.5,
+    });
+
+    observer.observe(model.state.targetRef.current);
+    return () => {
+      observer.disconnect();
+    };
+  }, [callback, model.state.targetRef, visible]);
+
+  return {};
+});

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 {