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

package/dist/es6/tooltip/lib/useTooltip.js

@@ -77,19 +77,24 @@ export function useTooltip(_a) {
     useCloseOnFullscreenExit(popupModel);
     useCloseOnTargetHidden(popupModel);
     var visible = popupModel.state.visibility !== 'hidden';
+    var targetProps = {
+        // extra description of the target element for assistive technology
+        'aria-describedby': type === 'describe' && visible ? id : undefined,
+        // This will replace the accessible name of the target element
+        'aria-label': type === 'label' ? titleText : undefined,
+        onMouseEnter: onOpenFromTarget,
+        onMouseLeave: onHide,
+        onMouseDown: onMouseDown,
+        onFocus: onFocus,
+        onBlur: onHide,
+    };
+    // remove `aria-describedby` if undefined to not override what's provided
+    if (targetProps['aria-describedby'] === undefined) {
+        delete targetProps['aria-describedby'];
+    }
     return {
         /** Mix these properties into the target element. **Must be an Element** */
-        targetProps: {
-            // extra description of the target element for assistive technology
-            'aria-describedby': type === 'describe' && visible ? id : undefined,
-            // This will replace the accessible name of the target element
-            'aria-label': type === 'label' ? titleText : undefined,
-            onMouseEnter: onOpenFromTarget,
-            onMouseLeave: onHide,
-            onMouseDown: onMouseDown,
-            onFocus: onFocus,
-            onBlur: onHide,
-        },
+        targetProps: targetProps,
         /** Mix these properties into the `Popper` component */
         popperProps: {
             open: visible,

package/form-field/lib/FormField.tsx

@@ -136,7 +136,7 @@ const FormFieldInputContainer = styled('div')<GrowthBehavior & FormFieldLabelPos
   }
 );
 
-class FormField extends React.Component<React.PropsWithChildren<FormFieldProps>> {
+export class FormField extends React.Component<React.PropsWithChildren<FormFieldProps>> {
   static LabelPosition = FormFieldLabelPosition;
   static ErrorType = ErrorType;
 
@@ -237,5 +237,3 @@ class FormField extends React.Component<React.PropsWithChildren<FormFieldProps>>
 
 FormField.LabelPosition = FormFieldLabelPosition;
 FormField.ErrorType = ErrorType;
-
-export {FormField};

package/icon/lib/SystemIcon.tsx

@@ -57,7 +57,6 @@ export interface SystemIconProps
    * The size of the SystemIcon in `px`.
    */
   size?: number | string | undefined;
-  className?: string; //investigate more
 }
 
 export const systemIconStyles = ({

package/layout/README.md

@@ -141,17 +141,11 @@ Default: `12`
 # Flex
 
 View the
-[documentation for Flex](http://workday.github.io/canvas-kit/?path=/docs/components-containers-layout-flex--usage)
-on Storybook.
-
-# Stack
-
-View the
-[documentation for Stack](http://workday.github.io/canvas-kit/?path=/docs/components-containers-layout-stack--basic-stack)
+[documentation for Flex](https://workday.github.io/canvas-kit/?path=/docs/components-containers-flex--basic)
 on Storybook.
 
 # Box
 
 View the
-[documentation for Stack](http://workday.github.io/canvas-kit/?path=/docs/components-containers-layout-box--as#box)
+[documentation for Box](https://workday.github.io/canvas-kit/?path=/docs/components-containers-box--basic)
 on Storybook.

package/layout/lib/utils/border/color.ts

@@ -4,40 +4,40 @@ import {SystemPropValues} from '../systemProps';
 /** style props to set CSS border color properties */
 export type BorderColorStyleProps = {
   /**
-   * - sets [CSS border-color property]((https://developer.mozilla.org/en-US/docs/Web/CSS/border-color)
+   * - sets [CSS border-color property](https://developer.mozilla.org/en-US/docs/Web/CSS/border-color)
    * - system tokens: `color`
    */
   borderColor?: SystemPropValues['color'];
   /**
-   * - sets [CSS border-top-color property]((https://developer.mozilla.org/en-US/docs/Web/CSS/border-top-color)
+   * - sets [CSS border-top-color property](https://developer.mozilla.org/en-US/docs/Web/CSS/border-top-color)
    * - system tokens: `color`
    */
   borderTopColor?: SystemPropValues['color'];
   /**
-   * - sets [CSS border-right-color property]((https://developer.mozilla.org/en-US/docs/Web/CSS/border-right-color)
+   * - sets [CSS border-right-color property](https://developer.mozilla.org/en-US/docs/Web/CSS/border-right-color)
    * - no bidirectional support
    * - system tokens: `color`
    */
   borderRightColor?: SystemPropValues['color'];
   /**
-   * - sets [CSS border-bottom-color property]((https://developer.mozilla.org/en-US/docs/Web/CSS/border-bottom-color)
+   * - sets [CSS border-bottom-color property](https://developer.mozilla.org/en-US/docs/Web/CSS/border-bottom-color)
    * - system tokens: `color`
    */
   borderBottomColor?: SystemPropValues['color'];
   /**
-   * - sets [CSS border-left-color property]((https://developer.mozilla.org/en-US/docs/Web/CSS/border-left-color)
+   * - sets [CSS border-left-color property](https://developer.mozilla.org/en-US/docs/Web/CSS/border-left-color)
    * - no bidirectional support
    * - system tokens: `color`
    */
   borderLeftColor?: SystemPropValues['color'];
   /**
-   * - sets [CSS border-inline-start-color property ]((https://developer.mozilla.org/en-US/docs/Web/CSS/border-inline-start-color)
+   * - sets [CSS border-inline-start-color property ](https://developer.mozilla.org/en-US/docs/Web/CSS/border-inline-start-color)
    * - bidirectional support
    * - system tokens: `color`
    */
   borderInlineStartColor?: SystemPropValues['color'];
   /**
-   * - sets [CSS border-inline-end-color property ]((https://developer.mozilla.org/en-US/docs/Web/CSS/border-inline-end-color)
+   * - sets [CSS border-inline-end-color property ](https://developer.mozilla.org/en-US/docs/Web/CSS/border-inline-end-color)
    * - bidirectional support
    * - system tokens: `color`
    */

package/layout/lib/utils/layout.ts

@@ -5,7 +5,7 @@ import {SystemPropValues} from './systemProps';
 
 /** style props to for CSS layout properties */
 export type LayoutStyleProps = {
-  /** sets [CSS display property](https://developer.mozilla.org/en-US/docs/Web/CSS/displaydisplay) */
+  /** sets [CSS display property](https://developer.mozilla.org/en-US/docs/Web/CSS/display) */
   display?: Property.Display;
   /**
    * - sets [CSS height property](https://developer.mozilla.org/en-US/docs/Web/CSS/height)

package/menu/lib/Menu.tsx

@@ -18,9 +18,15 @@ export interface MenuProps {
 }
 
 /**
- * An accessible dropdown menu component. A dropdown menu usually contains a target element that
- * opens to a menu.
- * @example
+ * `Menu` is a combination of a popup and a list. It usually has some type of target element that
+ * expands/collapses the menu and a `menu` role and and several `menuitem` roles. Focus is managed
+ * using [roving tabindex](https://w3c.github.io/aria-practices/#kbd_roving_tabindex) for maximum
+ * compatibility. A `Menu` can have two modes: `single` and `multiple`. This mode determines both
+ * how many items can be selected as well as the default behavior when a `menuitem` is clicked. For
+ * the `single` mode, selecting a `menuitem` will select and close the menu. For the `multiple`
+ * mode, clicking a `menuitem` will toggle selection and will not close the menu.
+ *
+ * ```tsx
  * <Menu>
  *   <Menu.Target>Open</Menu.Target>
  *   <Menu.Popper>
@@ -32,11 +38,29 @@ export interface MenuProps {
  *     </Menu.Card>
  *   </Menu.Popper>
  * </Menu>
+ * ```
  */
 export const Menu = createContainer()({
   displayName: 'Menu',
   modelHook: useMenuModel,
   subComponents: {
+    /**
+     * `Menu.Target` is similar to all {@link PopupTarget Popup.Target} types. The component only
+     * provides behavior and no styling. The `as` prop is used to determine which component is
+     * rendered. This component should forward the `ref` and apply any additional props directly to
+     * an element. The default `as` is a {@link SecondaryButton}. Any Canvas Kit component should
+     * work with an `as`.
+     *
+     * An example changing to a {@link PrimaryButton}
+     *
+     * ```tsx
+     * <Menu.Target as={PrimaryButton}>Primary Button Text</Menu.Target>
+     * ```
+     *
+     * This element will apply `aria-haspopup` and `aria-expanded` to inform screen readers there's
+     * a popup associated with the element.
+     */
+    Target: MenuTarget,
     /**
      * The menu card is a non-semantic element used to give the dropdown menu its distinct visual
      * cue that the dropdown menu is floating above other content. A menu card usually contains a
@@ -47,7 +71,7 @@ export const Menu = createContainer()({
      * The menu list follows the Collections API. A list can either contain static items
      * or a render prop and `items` to the model.
      *
-     * @example
+     * ```tsx
      * const MyComponent = () => {
      *   const model = useMenuModel({
      *     items: [
@@ -64,6 +88,7 @@ export const Menu = createContainer()({
      *     </Menu>
      *   )
      * }
+     * ```
      */
     List: MenuList,
     /**
@@ -73,13 +98,16 @@ export const Menu = createContainer()({
      */
     Item: MenuItem,
     Divider: MenuDivider,
-    Target: MenuTarget,
+    /**
+     * A `Menu.TargetContext` is the same as a {@link MenuTarget Menu.Target}, except it adds a
+     * `context` event handler instead of a `click` handler to trigger context menus.
+     */
     TargetContext: MenuTargetContext,
     /**
-     * The "Popper" of a menu. The popper will appear around the `Menu.Target`. It renders a `div`
-     * element that is portalled to the `document.body` which is controlled by the `PopupStack. The
-     * `PopupStack` is not part of React. This means no extra props given to this component will be
-     * forwarded to the `div` element, but the `ref` will be forwarded.
+     * The "Popper" of a menu. The popper will appear around the {@link MenuTarget Menu.Target}. It
+     * renders a `div` element that is portalled to the `document.body` which is controlled by the
+     * {@link PopupStack}. The `PopupStack` is not part of React. This means no extra props given to
+     * this component will be forwarded to the `div` element, but the `ref` will be forwarded.
      */
     Popper: MenuPopper,
   },

package/menu/lib/MenuTarget.tsx

@@ -14,7 +14,7 @@ export interface MenuTargetProps {
   children?: React.ReactNode;
 }
 
-const useMenuTargetBase = createElemPropsHook(useMenuModel)(model => {
+export const useMenuTargetBase = createElemPropsHook(useMenuModel)(model => {
   return {
     id: model.state.id,
     'aria-haspopup': 'true',

package/modal/lib/Modal.tsx

@@ -9,18 +9,89 @@ import {ModalHeading} from './ModalHeading';
 import {ModalOverflowOverlay} from './ModalOverflowOverlay';
 import {ModalBody} from './ModalBody';
 
+/**
+ * This component is the container component and does not render any semantic elements. It provides
+ * a React Context model for the `Modal` subcomponents. If you manually pass a `model` to all
+ * subcomponents, this container component isn't needed. If you do not pass a `model`, the `Modal`
+ * container component will build a default one using `useModalModel`. `Modal` is a composition of a
+ * {@link Popup} component and has a similar structure to `Popup`.
+ */
 export const Modal = createContainer()({
   displayName: 'Modal',
   modelHook: useModalModel,
   subComponents: {
-    Body: ModalBody,
-    Card: ModalCard,
-    CloseIcon: Popup.CloseIcon,
+    /**
+     * The `Modal.Target` is any element that is meant to show the Modal. 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 an icon button instead, pass an icon to the the `icon` prop and pass no
+     * children to the button. The `Modal.Target` is an alias for {@link PopupTarget Popup.Target}
+     * and uses the `usePopupTarget` hook, which provides a `ref` and an `onClick`. The provided
+     * `ref` will be used to return focus to this element when the Modal is closed. If the provided
+     * component does not forward the `ref` to an element, the fallback is to capture an element in
+     * the `onClick`. This can be overridden by providing a `returnFocusRef` to the model.
+     */
     Target: Popup.Target,
-    Heading: ModalHeading,
+    /**
+     * The `Modal.Overlay` is the component that hooks a Modal up to the {@link PopupStack} as well
+     * as the semi-transparent overlay commonly used with modals. Internally, the `Modal.Overlay`
+     * component uses two `div` elements to ensure proper rendering of the `Modal` content. The
+     * default element is a `div` element and can be changed via the `as` prop.
+     */
     Overlay: ModalOverlay,
-    OverflowOverlay: ModalOverflowOverlay,
+    /**
+     * The `Modal.Card` is wraps a {@link PopupCard Popup.Card} which wraps a {@link Card}. It is
+     * the `role="dialog"` element and is uses `useModalCard` behavior hook which sets
+     * `aria-modal="true"` and sets the `aria-labelledby` that points to the `id` of the
+     * {@link ModalHeading Modal.Heading}. If you don't use a `Modal.Heading`, add an `aria-label`
+     * instead. The default element is a `div` and can be changed via the `as` prop.
+     */
+    Card: ModalCard,
+    /**
+     * The `Modal.Heading` semantically labels the Modal via adding an `id` that the
+     * {@link ModalCard Modal.Card} points to via `aria-labelledby`. If this component is not used,
+     * you must add an `aria-label` to the `Modal.Card` to label the Modal for screen reader users.
+     * This component uses the `useModalHeading` behavior hook which sets an `id` and also does some
+     * focus management logic for situations where there is no
+     * {@link ModalCloseIcon Modal.CloseIcon} component used. Please use `Modal.Heading` and don't
+     * use your own unless you also use the `useModalHeading` hook in your component. Consult
+     * accessibility if you cannot use this component. The default element is an `h2` and can be
+     * changed via the `as` prop.
+     */
+    Heading: ModalHeading,
+    /**
+     * The `Modal.CloseIcon` is the 'X' icon in the top corner of a Modal. It always requires an
+     * `aria-label` which must be translated. It uses the `usePopupCloseIcon` which adds an
+     * `onClick` that will close the Modal. The default component rendered is an
+     * {@link TertiaryButton} with just an icon that can be changed via the `as`. All props that
+     * `TertiaryButton` takes are also available by default.
+     */
+    CloseIcon: Popup.CloseIcon,
+    /**
+     * The `Modal.CloseButton` is a convenience component that attaches an `onClick` listener to
+     * close the Modal. It uses the `usePopupCloseButton` behavior hook which adds an `onClick` that
+     * calls `model.events.hide()`. If you don't use this component, you'll have to add your own
+     * `onClick` and you'll have to hoist the model. The default component rendered is a
+     * {@link SecondaryButton} and can be changed via the `as` prop. This component doesn't contain
+     * any styles and will take on the styles of the component given to it. For example,
+     * `as={DeleteButton}` will render a delete button. `as={TertiaryButton}` with no children and
+     * an `icon` will render a {@link TertiaryButton} styled icon button. If you give it a base
+     * element like `as="button"`, you are responsible for styling the element. You can add your own
+     * `onClick` to perform side effects. Your callback will be merged with the `onClick` that
+     * closes the Modal.
+     */
     CloseButton: Popup.CloseButton,
+    Body: ModalBody,
+    /**
+     * If content is large, scrolling the entire overlay container is an option. Use the
+     * `Modal.OverflowOverlay` component instead of the {@link ModalOverlay Modal.Overlay}
+     * component. The {@link ModalCard Modal.Card}'s `maxHeight` and `height` will need to be reset
+     * to `inherit` to prevent any internal overflow.
+     *
+     * This component should be used in place of the {@link ModalOverlay Modal.Overlay} component if
+     * full body overflow is desired.
+     */
+    OverflowOverlay: ModalOverflowOverlay,
   },
 })<ExtractProps<typeof Dialog, never>>(elemProps => {
   return <>{elemProps.children}</>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@workday/canvas-kit-react",
-  "version": "9.0.0-alpha.338-next.5+fb2aa9bc",
+  "version": "9.0.0-alpha.348-next.3+62cb7fef",
   "description": "The parent module that contains all Workday Canvas Kit React components",
   "author": "Workday, Inc. (https://www.workday.com)",
   "license": "Apache-2.0",
@@ -49,7 +49,7 @@
     "@emotion/styled": "^11.6.0",
     "@popperjs/core": "^2.5.4",
     "@workday/canvas-colors-web": "^2.0.0",
-    "@workday/canvas-kit-popup-stack": "^9.0.0-alpha.338-next.5+fb2aa9bc",
+    "@workday/canvas-kit-popup-stack": "^9.0.0-alpha.348-next.3+62cb7fef",
     "@workday/canvas-system-icons-web": "^3.0.0",
     "@workday/design-assets-types": "^0.2.8",
     "chroma-js": "^2.1.0",
@@ -67,5 +67,5 @@
     "@workday/canvas-accent-icons-web": "^3.0.0",
     "@workday/canvas-applet-icons-web": "^2.0.0"
   },
-  "gitHead": "fb2aa9bcbecaf55a5a8b6b01964b54f8c7519dd7"
+  "gitHead": "62cb7fefb41fcc2ba937163d06d22deb7bf77203"
 }

package/pagination/lib/Pagination/AdditionalDetails.tsx

@@ -1,14 +1,19 @@
 import * as React from 'react';
 import {type, space, typeColors} from '@workday/canvas-kit-react/tokens';
-import {accessibleHide, styled, StyledType} from '@workday/canvas-kit-react/common';
+import {
+  accessibleHide,
+  styled,
+  StyledType,
+  createComponent,
+} from '@workday/canvas-kit-react/common';
 
 import {PaginationModel} from './types';
 import {Flex, FlexProps} from '@workday/canvas-kit-react/layout';
 import {useLiveRegion} from './common/useLiveRegion';
+import {PaginationContext} from './usePaginationModel';
 
 export interface AdditionalDetailsProps extends Omit<FlexProps, 'children'> {
   children: (model: PaginationModel) => React.ReactNode | React.ReactNode;
-  model: PaginationModel;
   shouldAnnounceToScreenReader?: boolean;
   shouldHideDetails?: boolean;
 }
@@ -28,22 +33,27 @@ const StyledAdditionalDetails = styled(Flex)<
   }
 });
 
-export const AdditionalDetails = ({
-  model,
-  children,
-  shouldAnnounceToScreenReader,
-  ...elemProps
-}: AdditionalDetailsProps) => {
-  const liveRegionProps = useLiveRegion({shouldAnnounceToScreenReader});
+export const AdditionalDetails = createComponent('div')({
+  displayName: 'Pagination.AdditionalDetails',
+  Component(
+    {children, shouldAnnounceToScreenReader, ...elemProps}: AdditionalDetailsProps,
+    ref,
+    Element
+  ) {
+    const model = React.useContext(PaginationContext);
+    const liveRegionProps = useLiveRegion({shouldAnnounceToScreenReader});
 
-  return (
-    <StyledAdditionalDetails
-      {...type.levels.subtext.medium}
-      color={typeColors.hint}
-      {...liveRegionProps}
-      {...elemProps}
-    >
-      {typeof children === 'function' ? children(model) : children}
-    </StyledAdditionalDetails>
-  );
-};
+    return (
+      <StyledAdditionalDetails
+        ref={ref}
+        as={Element}
+        {...type.levels.subtext.medium}
+        color={typeColors.hint}
+        {...liveRegionProps}
+        {...elemProps}
+      >
+        {typeof children === 'function' ? children(model) : children}
+      </StyledAdditionalDetails>
+    );
+  },
+});