@workday/canvas-kit-preview-react 8.0.0-alpha.254-next.23 → 8.0.0-alpha.428-next.2

package/form-field/lib/FormFieldLabel.tsx

@@ -1,31 +1,26 @@
 import React from 'react';
 
-import {createSubcomponent, ExtractProps, useTheme} from '@workday/canvas-kit-react/common';
-import {HStack, StackSpacing} from '@workday/canvas-kit-react/layout';
+import {createSubcomponent, useTheme} from '@workday/canvas-kit-react/common';
+import {Flex, FlexProps} from '@workday/canvas-kit-react/layout';
 import {LabelText, Text} from '@workday/canvas-kit-react/text';
 import {useFormFieldLabel, useFormFieldModel} from './hooks';
 
-export interface FormFieldLabelProps extends Omit<ExtractProps<typeof HStack, never>, 'spacing'> {
+export interface FormFieldLabelProps extends FlexProps {
   /**
    * The text of the label.
    */
   children: React.ReactNode;
-  /**
-   * When the input is required, this is spacing between label and asterisk.
-   * @default xxxs
-   */
-  spacing?: StackSpacing;
 }
 
 export const FormFieldLabel = createSubcomponent('label')({
   displayName: 'FormField.Label',
   modelHook: useFormFieldModel,
   elemPropsHook: useFormFieldLabel,
-})<FormFieldLabelProps>(({spacing = 'xxxs', children, ...elemProps}, Element, model) => {
+})<FormFieldLabelProps>(({gap = 'xxxs', children, ...elemProps}, Element, model) => {
   const theme = useTheme();
 
   return (
-    <HStack as={Element} spacing={spacing} minWidth="180px" {...elemProps}>
+    <Flex as={Element} gap={gap} minWidth="180px" {...elemProps}>
       <LabelText as="span" fontWeight="medium">
         {children}
       </LabelText>
@@ -40,6 +35,6 @@ export const FormFieldLabel = createSubcomponent('label')({
           *
         </Text>
       )}
-    </HStack>
+    </Flex>
   );
 });

package/form-field/lib/hooks/useFormFieldModel.tsx

@@ -5,7 +5,6 @@ export const useFormFieldModel = createModelHook({
     /**
      * Optional flag to denote if this field has an error to display. When true the `FormField.Input` will have
      * `required` set to true, and usually some subcomponents will have a error color applied.
-     * @default false
      */
     hasError: false,
     /**
@@ -16,13 +15,12 @@ export const useFormFieldModel = createModelHook({
      * - `FormField.Hint` will set `id` to `hint-${id}`
      *
      * If a value is not provided, a unique id will be automatically created by `useUniqueId()`.
-     * @default `useUniqueId()`
+     * @default {useUniqueId}
      */
     id: '',
     /**
      * Optional flag to denote if this field is required. When true the `FormField.Input` will have
      * `required` set to true, and an asterisk will be appended to the `FormField.Label`.
-     * @default false
      */
     isRequired: false,
   },

package/form-field/lib/hooks/useFormFieldOrientation.tsx

@@ -1,4 +1,4 @@
-import {StackSpacing, StackProps} from '@workday/canvas-kit-react/layout';
+import {FlexProps} from '@workday/canvas-kit-react/layout';
 import {space} from '@workday/canvas-kit-react/tokens';
 
 /**
@@ -6,21 +6,21 @@ import {space} from '@workday/canvas-kit-react/tokens';
  */
 export const useFormFieldOrientation = (orientation: 'horizontal' | 'vertical') => {
   let layoutProps: {
-    flexDirection: StackProps['flexDirection'];
-    alignItems: StackProps['alignItems'];
-    spacing: StackSpacing;
+    flexDirection: FlexProps['flexDirection'];
+    alignItems: FlexProps['alignItems'];
+    gap: FlexProps['gap'];
   };
 
   if (orientation === 'horizontal') {
     layoutProps = {
       flexDirection: 'row',
-      spacing: space.l,
+      gap: space.l,
       alignItems: 'center',
     };
   } else {
     layoutProps = {
       flexDirection: 'column',
-      spacing: space.xxxs,
+      gap: space.xxxs,
       alignItems: 'flex-start',
     };
   }

package/menu/lib/Menu.tsx

@@ -9,8 +9,8 @@ import {hideMouseFocus, GrowthBehavior, generateUniqueId} from '@workday/canvas-
 /**
  * ### Deprecated Menu
  *
- * As of Canvas Kit v8, Menu is being soft-deprecated.
- * It will be hard-deprecated (completely removed) in v9. Please see the
+ * As of Canvas Kit v8, Menu is being deprecated.
+ * It will be removed in v10. Please see the
  * [upgrade guide](https://workday.github.io/canvas-kit/?path=/story/welcome-upgrade-guides-v8-0--page)
  * for more information.
  */
@@ -57,8 +57,8 @@ export interface DeprecatedMenuProps
 /**
  * ### Deprecated Menu State
  *
- * As of Canvas Kit v8, Menu is being soft-deprecated.
- * It will be hard-deprecated (completely removed) in v9. Please see the
+ * As of Canvas Kit v8, Menu is being deprecated.
+ * It will be removed in v10. Please see the
  * [upgrade guide](https://workday.github.io/canvas-kit/?path=/story/welcome-upgrade-guides-v8-0--page)
  * for more information.
  */
@@ -78,12 +78,19 @@ const List = styled('ul')({
 });
 
 /**
- * ### Deprecated Menu
+ * As of Canvas Kit v8, Menu is being deprecated.
+ * It will be removed in v10. Please see the [upgrade
+ * guide](https://workday.github.io/canvas-kit/?path=/story/welcome-upgrade-guides-v8-0--page) for
+ * more information.
  *
- * As of Canvas Kit v8, this component is being soft-deprecated.
- * It will be hard-deprecated (completely removed) in v9. Please see the
- * [upgrade guide](https://workday.github.io/canvas-kit/?path=/story/welcome-upgrade-guides-v8-0--page)
- * for more information.
+ * `DeprecatedMenu` renders a styled `<ul role="menu">` element within a {@link Card} and follows
+ * the [Active Menu
+ * pattern](https://www.w3.org/TR/wai-aria-practices/examples/menu-button/menu-button-actions-active-descendant.html)
+ * using `aria-activedescendant`.
+ *
+ * Undocumented props are spread to the underlying `<ul>` element.
+ *
+ * @deprecated
  */
 export class DeprecatedMenu extends React.Component<DeprecatedMenuProps, DeprecatedMenuState> {
   private id = generateUniqueId();

package/menu/lib/MenuItem.tsx

@@ -14,8 +14,8 @@ import {SystemIcon, SystemIconProps} from '@workday/canvas-kit-react/icon';
 /**
  * ### Deprecated Menu Item Props
  *
- * As of Canvas Kit v8, Menu is being soft-deprecated.
- * It will be hard-deprecated (completely removed) in v9. Please see the
+ * As of Canvas Kit v8, Menu is being deprecated.
+ * It will be removed in v10. Please see the
  * [upgrade guide](https://workday.github.io/canvas-kit/?path=/story/welcome-upgrade-guides-v8-0--page)
  * for more information.
  */
@@ -254,12 +254,22 @@ const scrollIntoViewIfNeeded = (elem: HTMLElement, centerIfNeeded = true): void
 };
 
 /**
- * ### Deprecated Menu Item
+ * `DeprecatedMenuItem` renders an `<li>` element with the correct attributes to ensure it is
+ * accessible. If you choose to implement your own custom menu items, be sure to use semantic `<li>`
+ * elements with the following attributes:
  *
- * As of Canvas Kit v8, Menu is being soft-deprecated.
- * It will be hard-deprecated (completely removed) in v9. Please see the
- * [upgrade guide](https://workday.github.io/canvas-kit/?path=/story/welcome-upgrade-guides-v8-0--page)
- * for more information.
+ * - `role="menuitem"`
+ * - `tabindex={-1}`
+ * - `id`s following this pattern: `${MenuId}-${index}`
+ *
+ * As of Canvas Kit v8, Menu is being deprecated.
+ * It will be removed in v10. Please see the [upgrade
+ * guide](https://workday.github.io/canvas-kit/?path=/story/welcome-upgrade-guides-v8-0--page) for
+ * more information.
+ *
+ * Undocumented props are spread to the underlying `<li>` element.
+ *
+ * @deprecated
  */
 export class DeprecatedMenuItem extends React.Component<DeprecatedMenuItemProps> {
   ref = React.createRef<HTMLLIElement>();
@@ -301,12 +311,13 @@ export class DeprecatedMenuItem extends React.Component<DeprecatedMenuItemProps>
 
     return (
       <>
-        {hasDivider && <Divider />}
+        {hasDivider && <Divider aria-hidden="true" />}
         <Item
           ref={this.ref}
           tabIndex={-1}
           id={id}
           role={isHeader ? 'presentation' : role}
+          aria-hidden={isHeader ? true : undefined}
           onClick={this.handleClick}
           aria-disabled={isDisabled ? true : undefined}
           isDisabled={!!isDisabled}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@workday/canvas-kit-preview-react",
-  "version": "8.0.0-alpha.254-next.23+2fa69377",
+  "version": "8.0.0-alpha.428-next.2+2c79134a",
   "description": "Canvas Kit Preview is made up of components that have the full design and a11y review, are part of the DS ecosystem and are approved for use in product. The API's could be subject to change, but not without strong communication and migration strategies.",
   "author": "Workday, Inc. (https://www.workday.com)",
   "license": "Apache-2.0",
@@ -41,21 +41,20 @@
     "workday"
   ],
   "peerDependencies": {
-    "react": "^17.0 || ^18.0"
+    "react": ">=16.14"
   },
   "dependencies": {
     "@emotion/react": "^11.7.1",
     "@emotion/styled": "^11.6.0",
-    "@workday/canvas-kit-react": "^8.0.0-alpha.254-next.23+2fa69377",
+    "@workday/canvas-kit-react": "^8.0.0-alpha.428-next.2+2c79134a",
     "@workday/canvas-system-icons-web": "^3.0.0",
     "@workday/design-assets-types": "^0.2.8"
   },
   "devDependencies": {
     "@workday/canvas-accent-icons-web": "^3.0.0",
-    "@workday/canvas-kit-labs-react": "^8.0.0-alpha.254-next.23+2fa69377",
     "formik": "^2.2.9",
     "react-hook-form": "7.36.1",
     "yup": "^0.32.11"
   },
-  "gitHead": "2fa69377808c5dd76337d1b34dbd4ede07c7e1c4"
+  "gitHead": "2c79134aa48ef0efde9cdf883b529b8157337a28"
 }

package/pill/lib/Pill.tsx

@@ -9,7 +9,7 @@ import {
   styled,
   StyledType,
 } from '@workday/canvas-kit-react/common';
-import {BoxProps, boxStyleFn, HStack, Stack} from '@workday/canvas-kit-react/layout';
+import {BoxProps, boxStyleFn, Flex} from '@workday/canvas-kit-react/layout';
 import {borderRadius, colors, space, type} from '@workday/canvas-kit-react/tokens';
 
 import {usePillModel} from './usePillModel';
@@ -160,14 +160,113 @@ const StyledNonInteractivePill = styled(StyledBasePill)<StyledType>({
   position: 'relative',
 });
 
+/**
+ * By default, a `Pill` renders an interactive element that accepts subcomponents. By "interactive"
+ * we mean that the Pill container is a focusable element (a `<button>`). All leading elements
+ * (icons or avatars) are intended to be descriptive, helping support the label. They should not
+ * receive focus.
+ *
+ * `Pill` is the container component. It also provides a React context model for its subcomponents.
+ * Based on the `variant` prop this component will render different styled `Pill`s.
+ *
+ * Example of read only:
+ *
+ * ```tsx
+ * <Pill variant="readOnly">This is a read only</Pill>
+ * ```
+ *
+ * Example of interactive:
+ *
+ * ```tsx
+ * <Pill onClick={() => console.log('clicked')}>
+ *   <Pill.Avatar /> Regina Skeltor
+ * </Pill>
+ * ```
+ *
+ * Example of removable:
+ *
+ * ```tsx
+ * <Pill variant="removable">
+ *   <Pill.Avatar /> Regina Skeltor
+ *   <Pill.IconButton onClick={() => console.log('clicked')} />
+ * </Pill>
+ * ```
+ *
+ * If you set the `Pill` `variant` to `removable`, it will render a `<span>` element. You can then
+ * provide a `Pill.IconButton` that acts as the focus target. This creates a smaller, more
+ * intentional click target that prevents users from accidentally deleting an item.
+ *
+ * ```tsx
+ * <Pill variant="removable">
+ *   Shoes
+ *   <Pill.IconButton onClick={() => console.log('handle remove')} />
+ * </Pill>
+ * ```
+ */
 export const Pill = createContainer('button')({
+  displayName: 'Pill',
   modelHook: usePillModel,
   subComponents: {
-    Icon: PillIcon,
+    /**
+     * This component renders an avatar. It supports all props of the `Avatar` component.
+     *
+     * ```tsx
+     * <Pill variant="removable">
+     *   <Pill.Avatar url={avatarUrl} />
+     *   Regina Skeltor
+     *   <Pill.IconButton onClick={() => console.log('handle remove')} />
+     * </Pill>
+     * ```
+     */
     Avatar: PillAvatar,
+    /**
+     * This component renders its `children` as the count.
+     *
+     * ```tsx
+     * <Pill onClick={() => console.warn('clicked')}>
+     *   Shoes
+     *   <Pill.Count>30</Pill.Count>
+     * </Pill>
+     * ```
+     */
     Count: PillCount,
-    Label: PillLabel,
+    /**
+     * This component renders an `icon`. It not be used with the `default` styling – not `readOnly`
+     * or `removable` variants. By default it renders a `plusIcon` but it can be overridden by
+     * providing an icon to the `icon` prop.
+     *
+     * ```tsx
+     * <Pill onClick={() => console.warn('clicked')}>
+     *   <Pill.Icon />
+     *   <Pill.Label>Regina Skeltor</Pill.Label>
+     * </Pill>
+     * ```
+     */
+    Icon: PillIcon,
+    /**
+     * This component renders a custom icon button. It is only intended to be used with the
+     * `removable` variant. By default, it renders a `xSmallIcon` but can be overridden by providing
+     * an icon to the `icon` prop.
+     *
+     * ```tsx
+     * <Pill variant="removable">
+     *   Pink Shirts
+     *   <Pill.IconButton onClick={() => console.warn('clicked')} />
+     * </Pill>
+     * ```
+     */
     IconButton: PillIconButton,
+    /**
+     * This component renders a `<span>` that automatically handles overflow by rendering a tooltip.
+     * There's no need to use this component directly since the overflow is handled for you automatically.
+     *
+     * ```tsx
+     * <Pill variant="readOnly">
+     *   <Pill.Label>Read-only</Pill.Label>
+     * </Pill>
+     * ```
+     */
+    Label: PillLabel,
   },
 })<PillProps>(({variant = 'default', maxWidth, ...elemProps}, Element, model) => {
   return (
@@ -190,18 +289,18 @@ export const Pill = createContainer('button')({
           {...elemProps}
           disabled={model.state.disabled}
         >
-          <HStack spacing="xxxs" display="inline-flex" alignItems="center">
+          <Flex gap="xxxs" display="inline-flex" alignItems="center">
             {React.Children.map(elemProps.children, (child, index) => {
               if (typeof child === 'string') {
                 return <PillLabel key={index}>{child}</PillLabel>;
               }
               return (
-                <Stack.Item key={index} display="inline-flex">
+                <Flex.Item key={index} display="inline-flex">
                   {child}
-                </Stack.Item>
+                </Flex.Item>
               );
             })}
-          </HStack>
+          </Flex>
         </StyledBasePill>
       )}
       {variant === 'removable' && (
@@ -211,14 +310,14 @@ export const Pill = createContainer('button')({
           variant={variant}
           {...elemProps}
         >
-          <HStack spacing="xxxs" display="inline-flex" alignItems="center" justifyContent="center">
+          <Flex gap="xxxs" display="inline-flex" alignItems="center" justifyContent="center">
             {React.Children.map(elemProps.children, (child, index) => {
               if (typeof child === 'string') {
                 return <PillLabel key={index}>{child}</PillLabel>;
               }
-              return <Stack.Item key={index}>{child}</Stack.Item>;
+              return <Flex.Item key={index}>{child}</Flex.Item>;
             })}
-          </HStack>
+          </Flex>
         </StyledNonInteractivePill>
       )}
     </>

package/pill/lib/PillCount.tsx

@@ -25,7 +25,7 @@ export const PillCount = createComponent('span')({
         height={22}
         minWidth={22}
         padding={`0  ${space.xxxs}`}
-        marginInlineEnd={`-${space.xxs}`} // Remove padding from HStack on the right side
+        marginInlineEnd={`-${space.xxs}`} // Remove excess margin at the end
         marginInlineStart={`${space.xxxs}`}
         backgroundColor={colors.soap500}
         data-count="ck-pill-count"

package/pill/lib/PillIcon.tsx

@@ -21,7 +21,7 @@ export const PillIcon = createSubcomponent('span')({
 })<PillIconProps>(({size, icon, ...elemProps}, Element) => {
   return (
     <SystemIcon
-      marginInlineStart={`-${space.xxxs}`} // remove padding on the left from HStack
+      marginInlineStart={`-${space.xxxs}`} // remove excess margin from the start
       display="flex"
       as={Element}
       size={20}

package/segmented-control/index.ts

@@ -1,2 +1,4 @@
 export * from './lib/SegmentedControl';
 export * from './lib/hooks/useSegmentedControlModel';
+export * from './lib/hooks/useSegmentedControlItem';
+export {useSegmentedControlList} from './lib/SegmentedControlList';

package/segmented-control/lib/SegmentedControl.tsx

@@ -9,11 +9,47 @@ export interface SegmentedControlProps {
   children: React.ReactNode;
 }
 
+/**
+ * `SegmentedControl` is a container component that is responsible for creating a
+ * {@link SegmentedControlModel} and sharing it with its subcomponents using React context. It does
+ * not represent a real element.
+ *
+ * ```tsx
+ * <SegmentedControl items={[]}>{Child components}</SegmentedControl>
+ * ```
+ *
+ * Alternatively, you may pass in a model using the [hoisted model
+ * pattern](/getting-started/for-developers/resources/compound-components/#configuring-a-model).
+ *
+ * ```tsx
+ * const model = useSegmentedControlModel({
+ *   items: [],
+ * });
+ *
+ * <SegmentedControl model={model}>{Child components}</SegmentedControl>;
+ * ```
+ */
 export const SegmentedControl = createContainer()({
   displayName: 'SegmentedControl',
   modelHook: useSegmentedControlModel,
   subComponents: {
+    /**
+     * `SegmentedControl.List` renders {@link Grid} under the hood. It is a container for
+     * {@link SegmentedControlItem SegmentedControl.Item} subcomponents.
+     *
+     * ```tsx
+     * <SegmentedControl.List>{SegmentedControl.Items}</SegmentedControl.List>
+     * ```
+     */
     List: SegmentedControlList,
+    /**
+     * `SegmentedControl.Item` is a `button` element built on `BaseButton`. `SegmentedControl.Item`
+     * has a `data-id` prop to handle `onSelect` properly.
+     *
+     * ```tsx
+     * <SegmentedControl.Item data-id="table">Table</SegmentedControl.Item>
+     * ```
+     */
     Item: SegmentedControlItem,
   },
 })<SegmentedControlProps>(({children}) => {

package/segmented-control/lib/SegmentedControlList.tsx

@@ -15,7 +15,7 @@ export interface SegmentedControlListProps<T = any>
   children: ((item: T) => React.ReactNode) | React.ReactNode;
 }
 
-const useSegmentedControlList = createElemPropsHook(useSegmentedControlModel)(
+export const useSegmentedControlList = createElemPropsHook(useSegmentedControlModel)(
   ({state: {orientation, disabled, items}}) => {
     const directionName = orientation === 'vertical' ? 'Row' : 'Column';
     return {

package/segmented-control/lib/hooks/useSegmentedControlItem.tsx

@@ -11,11 +11,7 @@ import {useSegmentedControlModel} from './useSegmentedControlModel';
 export const useSegmentedControlItem = composeHooks(
   useListItemSelect,
   createElemPropsHook(useSegmentedControlModel)(
-    (
-      model,
-      _?: React.Ref<HTMLElement>,
-      elemProps: {'data-id'?: string; children?: React.ReactNode} = {}
-    ) => {
+    (model, _, elemProps: {'data-id'?: string; children?: React.ReactNode} = {}) => {
       const name = elemProps['data-id'] || '';
       const selected = !!name && isSelected(name, model.state);