@workday/canvas-kit-preview-react 9.0.0-alpha.336-next.6 → 9.0.0-alpha.344-next.3

package/pill/lib/Pill.tsx

@@ -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 (

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/side-panel/lib/SidePanel.tsx

@@ -1,23 +1,16 @@
 /** @jsxRuntime classic */
 /** @jsx jsx */
 import * as React from 'react';
-import {styled, useIsRTL} from '@workday/canvas-kit-react/common';
-import {css, jsx, keyframes, CSSObject} from '@emotion/react';
-import {TertiaryButton, TertiaryButtonProps} from '@workday/canvas-kit-react/button';
-import {space, colors, depth} from '@workday/canvas-kit-react/tokens';
-import {transformationImportIcon} from '@workday/canvas-system-icons-web';
-import {Tooltip} from '@workday/canvas-kit-react/tooltip';
+import {createComponent, styled} from '@workday/canvas-kit-react/common';
+import {jsx, keyframes, CSSObject} from '@emotion/react';
+import {colors, depth} from '@workday/canvas-kit-react/tokens';
+import {SidePanelContext} from './hooks';
+import {SidePanelToggleButton} from './SidePanelToggleButton';
 
 export type SidePanelVariant = 'standard' | 'alternate';
 export type SidePanelTransitionStates = 'collapsed' | 'collapsing' | 'expanded' | 'expanding';
 
-export interface SidePanelProps extends React.HTMLAttributes<HTMLDivElement> {
-  /**
-   * The element the side panel will render as (e.g. 'div').
-   *
-   * @default 'section'
-   */
-  as?: React.ElementType;
+export interface SidePanelProps {
   /**
    * The width of the component (in `px` if it's a `number`) when it is collapsed.
    *
@@ -67,6 +60,9 @@ export interface SidePanelProps extends React.HTMLAttributes<HTMLDivElement> {
    * @param boolean
    */
   touched: boolean;
+  children?: React.ReactNode;
+  onAnimationStart?: React.AnimationEventHandler<HTMLElement>;
+  onAnimationEnd?: React.AnimationEventHandler<HTMLElement>;
 }
 
 const createKeyframes = (from: number | string, to: number | string) => {
@@ -98,172 +94,126 @@ const containerVariantStyle: Record<SidePanelVariant, CSSObject> = {
   },
 };
 
-const Panel = styled('section')<Pick<SidePanelProps, 'as'>>({
+const Panel = styled('section')({
   overflow: 'hidden',
   position: 'relative',
   boxSizing: 'border-box',
   height: '100%',
 });
 
-export const SidePanelContext = React.createContext({
-  state: 'expanded',
-  origin: 'left',
-});
-
-export const SidePanel = ({
-  as = 'section',
-  children,
-  collapsedWidth = 64,
-  expanded = true,
-  expandedWidth = 320,
-  onAnimationEnd,
-  onAnimationStart,
-  onExpandedChange,
-  onStateTransition,
-  origin = 'left',
-  variant = 'standard',
-  touched,
-  ...elemProps
-}: SidePanelProps) => {
-  const [state, setState] = React.useState<SidePanelTransitionStates>(
-    expanded ? 'expanded' : 'collapsed'
-  );
-
-  React.useEffect(() => {
-    if (typeof onExpandedChange !== 'undefined') {
-      onExpandedChange(expanded);
-    }
-  }, [expanded, onExpandedChange]);
-
-  React.useEffect(() => {
-    if (typeof onStateTransition !== 'undefined') {
-      onStateTransition(state);
-    }
-  }, [state, onStateTransition]);
-
-  const motion = {
-    collapse: createKeyframes(expandedWidth, collapsedWidth),
-    expand: createKeyframes(collapsedWidth, expandedWidth),
-  };
-
-  const handleAnimationEnd = (event: React.AnimationEvent<HTMLDivElement>) => {
-    if (event.currentTarget === event.target) {
-      if (event.animationName === motion.collapse.name) {
-        setState('collapsed');
+export const SidePanel = createComponent('section')({
+  displayName: 'SidePanel',
+  Component(
+    {
+      children,
+      collapsedWidth = 64,
+      expanded = true,
+      expandedWidth = 320,
+      onAnimationEnd,
+      onAnimationStart,
+      onExpandedChange,
+      onStateTransition,
+      origin = 'left',
+      variant = 'standard',
+      touched,
+      ...elemProps
+    }: SidePanelProps,
+    ref,
+    Element
+  ) {
+    const [state, setState] = React.useState<SidePanelTransitionStates>(
+      expanded ? 'expanded' : 'collapsed'
+    );
+
+    React.useEffect(() => {
+      if (typeof onExpandedChange !== 'undefined') {
+        onExpandedChange(expanded);
       }
+    }, [expanded, onExpandedChange]);
 
-      if (event.animationName === motion.expand.name) {
-        setState('expanded');
+    React.useEffect(() => {
+      if (typeof onStateTransition !== 'undefined') {
+        onStateTransition(state);
       }
-    }
-
-    if (typeof onAnimationEnd !== 'undefined') {
-      onAnimationEnd(event);
-    }
-  };
-
-  const handleAnimationStart = (event: React.AnimationEvent<HTMLDivElement>) => {
-    if (event.currentTarget === event.target) {
-      if (
-        event.animationName === motion.collapse.name ||
-        event.animationName === motion.expand.name
-      ) {
-        setState(expanded ? 'expanding' : 'collapsing');
+    }, [state, onStateTransition]);
+
+    const motion = {
+      collapse: createKeyframes(expandedWidth, collapsedWidth),
+      expand: createKeyframes(collapsedWidth, expandedWidth),
+    };
+
+    const handleAnimationEnd = (event: React.AnimationEvent<HTMLDivElement>) => {
+      if (event.currentTarget === event.target) {
+        if (event.animationName === motion.collapse.name) {
+          setState('collapsed');
+        }
+
+        if (event.animationName === motion.expand.name) {
+          setState('expanded');
+        }
       }
-    }
 
-    if (typeof onAnimationStart !== 'undefined') {
-      onAnimationStart(event);
-    }
-  };
+      if (typeof onAnimationEnd !== 'undefined') {
+        onAnimationEnd(event);
+      }
+    };
+
+    const handleAnimationStart = (event: React.AnimationEvent<HTMLDivElement>) => {
+      if (event.currentTarget === event.target) {
+        if (
+          event.animationName === motion.collapse.name ||
+          event.animationName === motion.expand.name
+        ) {
+          setState(expanded ? 'expanding' : 'collapsing');
+        }
+      }
 
-  return (
-    <Panel
-      as={as}
-      css={[
-        {
-          width: expanded ? expandedWidth : collapsedWidth,
-          maxWidth: expanded ? expandedWidth : collapsedWidth,
-          // mounted.current will be false on the first render, thus you won't get an unwanted animation here
-          // Will animate again if you force a re-render (like in Storybook)
-          animation: touched
-            ? `${expanded ? motion.expand : motion.collapse} 200ms ease-out`
-            : undefined,
-        },
-        containerVariantStyle[variant],
-      ]}
-      onAnimationEnd={handleAnimationEnd}
-      onAnimationStart={handleAnimationStart}
-      {...elemProps}
-    >
-      <SidePanelContext.Provider
-        value={{
-          state,
-          origin,
-        }}
+      if (typeof onAnimationStart !== 'undefined') {
+        onAnimationStart(event);
+      }
+    };
+
+    return (
+      <Panel
+        ref={ref}
+        as={Element}
+        css={[
+          {
+            width: expanded ? expandedWidth : collapsedWidth,
+            maxWidth: expanded ? expandedWidth : collapsedWidth,
+            // mounted.current will be false on the first render, thus you won't get an unwanted animation here
+            // Will animate again if you force a re-render (like in Storybook)
+            animation: touched
+              ? `${expanded ? motion.expand : motion.collapse} 200ms ease-out`
+              : undefined,
+          },
+          containerVariantStyle[variant],
+        ]}
+        onAnimationEnd={handleAnimationEnd}
+        onAnimationStart={handleAnimationStart}
+        {...elemProps}
       >
-        {children}
-      </SidePanelContext.Provider>
-    </Panel>
-  );
-};
-
-export type ToggleButtonProps = TertiaryButtonProps & {
-  /**
-   * The tooltip text to expand the side panel
-   * @default 'Expand'
-   */
-  tooltipTextExpand?: string;
-  /**
-   * The tooltip text to collapse the side panel
-   * @default 'Collapse'
-   */
-  tooltipTextCollapse?: string;
-};
-
-/**
- * A toggle button styled specifically for the side panel container.
- */
-const ToggleButton = ({
-  variant = undefined,
-  icon = transformationImportIcon,
-  tooltipTextExpand: expandLabel = 'Expand',
-  tooltipTextCollapse: collapseLabel = 'Collapse',
-  ...rest
-}: ToggleButtonProps & React.ButtonHTMLAttributes<HTMLButtonElement>) => {
-  const context = React.useContext(SidePanelContext);
-
-  const useRTLOrigin = () => {
-    const isRTL = useIsRTL();
-    // if the direction is set to RTl, flip the origin
-    if (isRTL) {
-      return context.origin === 'left' ? 'right' : 'left';
-    }
-    // Otherwise, default to returning the origin
-    return context.origin;
-  };
-
-  const rtlOrigin = useRTLOrigin();
-
-  // Note: Depending on the collapsed width, the button could "jump" to it's final position.
-  const buttonStyle = css({
-    position: 'absolute',
-    top: space.m,
-    width: space.l,
-    right: context.state === 'collapsed' ? 0 : rtlOrigin === 'left' ? space.s : undefined,
-    left: context.state === 'collapsed' ? 0 : rtlOrigin === 'right' ? space.s : undefined,
-    margin: context.state === 'collapsed' ? 'auto' : 0, // to override the -8px margin for TertiaryButton.Plain
-    transform:
-      context.state === 'collapsed' || context.state === 'collapsing'
-        ? `scaleX(${rtlOrigin === 'left' ? '1' : '-1'})`
-        : `scaleX(${rtlOrigin === 'left' ? '-1' : '1'})`,
-  });
-
-  return (
-    <Tooltip title={context.state === 'collapsed' ? expandLabel : collapseLabel} type="muted">
-      <TertiaryButton type="button" css={buttonStyle} icon={icon} variant={variant} {...rest} />
-    </Tooltip>
-  );
-};
-
-SidePanel.ToggleButton = ToggleButton;
+        <SidePanelContext.Provider
+          value={{
+            state,
+            origin,
+          }}
+        >
+          {children}
+        </SidePanelContext.Provider>
+      </Panel>
+    );
+  },
+  subComponents: {
+    /**
+     * `SidePanel.ToggleButton` is a control that is meant to toggle between `expanded = true` and
+     * `expanded = false` states. It must be used within the `SidePanel` component as a child. Use
+     * in conjunction with `useSidePanel`'s `controlProps`, otherwise it does not come with explicit
+     * `onClick` handlers.
+     *
+     * For accessibility purposes, it must be the first focusable element. We recommend that you
+     * keep it as the first child of `SidePanel`
+     */
+    ToggleButton: SidePanelToggleButton,
+  },
+});

package/side-panel/lib/SidePanelToggleButton.tsx

@@ -0,0 +1,78 @@
+/** @jsxRuntime classic */
+/** @jsx jsx */
+import * as React from 'react';
+import {createComponent, ExtractProps, useIsRTL} from '@workday/canvas-kit-react/common';
+import {css, jsx} from '@emotion/react';
+import {TertiaryButton} from '@workday/canvas-kit-react/button';
+import {space} from '@workday/canvas-kit-react/tokens';
+import {transformationImportIcon} from '@workday/canvas-system-icons-web';
+import {Tooltip} from '@workday/canvas-kit-react/tooltip';
+import {SidePanelContext} from './hooks';
+
+export interface SidePanelToggleButtonProps extends ExtractProps<typeof TertiaryButton, never> {
+  /**
+   * The tooltip text to expand the side panel
+   */
+  tooltipTextExpand?: string;
+  /**
+   * The tooltip text to collapse the side panel
+   */
+  tooltipTextCollapse?: string;
+}
+
+/**
+ * A toggle button styled specifically for the side panel container.
+ */
+export const SidePanelToggleButton = createComponent('button')({
+  displayName: 'SidePanel.ToggleButton',
+  Component({
+    variant = undefined,
+    icon = transformationImportIcon,
+    tooltipTextExpand = 'Expand',
+    tooltipTextCollapse = 'Collapse',
+    ...elemProps
+  }: SidePanelToggleButtonProps) {
+    const context = React.useContext(SidePanelContext);
+
+    const useRTLOrigin = () => {
+      const isRTL = useIsRTL();
+      // if the direction is set to RTl, flip the origin
+      if (isRTL) {
+        return context.origin === 'left' ? 'right' : 'left';
+      }
+      // Otherwise, default to returning the origin
+      return context.origin;
+    };
+
+    const rtlOrigin = useRTLOrigin();
+
+    // Note: Depending on the collapsed width, the button could "jump" to it's final position.
+    const buttonStyle = css({
+      position: 'absolute',
+      top: space.m,
+      width: space.l,
+      right: context.state === 'collapsed' ? 0 : rtlOrigin === 'left' ? space.s : undefined,
+      left: context.state === 'collapsed' ? 0 : rtlOrigin === 'right' ? space.s : undefined,
+      margin: context.state === 'collapsed' ? 'auto' : 0, // to override the -8px margin for TertiaryButton.Plain
+      transform:
+        context.state === 'collapsed' || context.state === 'collapsing'
+          ? `scaleX(${rtlOrigin === 'left' ? '1' : '-1'})`
+          : `scaleX(${rtlOrigin === 'left' ? '-1' : '1'})`,
+    });
+
+    return (
+      <Tooltip
+        title={context.state === 'collapsed' ? tooltipTextExpand : tooltipTextCollapse}
+        type="muted"
+      >
+        <TertiaryButton
+          type="button"
+          css={buttonStyle}
+          icon={icon}
+          variant={variant}
+          {...elemProps}
+        />
+      </Tooltip>
+    );
+  },
+});

package/side-panel/lib/hooks.ts

@@ -1,5 +1,10 @@
 import * as React from 'react';
 
+export const SidePanelContext = React.createContext({
+  state: 'expanded',
+  origin: 'left',
+});
+
 import {useUniqueId} from '@workday/canvas-kit-react/common';
 /**
  * The optional config options for the `useSidePanel` hook
@@ -77,6 +82,21 @@ export interface ControlProps {
   onClick: () => void;
 }
 
+/**
+ *
+ * This hook manages the state and `aria-` attributes for the SidePanel. It takes an optional
+ * configuration object:
+ *
+ * ```tsx
+ * import {useSidePanel} from '@workday/canvas-kit-preview-react/side-panel';
+ *
+ * const {expanded, setExpanded, panelProps, labelProps, controlProps} = useSidePanel({
+ *   initialExpanded: false,
+ *   panelId: 'custom-panel-id',
+ *   labelId: 'custom-label-id',
+ * });
+ * ```
+ */
 export const useSidePanel = (config?: UseSidePanelProps) => {
   const [touched, setTouched] = React.useState(false);
   const configParams = config

package/status-indicator/index.ts

@@ -1 +1,3 @@
 export * from './lib/StatusIndicator';
+export * from './lib/hooks/useStatusIndicatorModel';
+export {useStatusIndicatorIcon} from './lib/StatusIndicatorIcon';

package/status-indicator/lib/StatusIndicator.tsx

@@ -22,13 +22,39 @@ export const useStatusIndicator = createElemPropsHook(useStatusIndicatorModel)((
   };
 });
 
+/**
+ * `StatusIndicator` is a container component which renders an {@link Flex} under the hood to
+ * apply spacing evenly between its children. It has a default maximum width of `200px`.
+ *
+ * ```tsx
+ * <StatusIndicator emphasis="low" variant="blue">
+ *   {Child components}
+ * </StatusIndicator>
+ * ```
+ */
 export const StatusIndicator = createContainer('div')({
   displayName: 'StatusIndicator',
   modelHook: useStatusIndicatorModel,
   elemPropsHook: useStatusIndicator,
   subComponents: {
-    Icon: StatusIndicatorIcon,
+    /**
+     * `StatusIndicator.Label` renders {@link Text} under the hood. It will apply an ellipsis if its
+     * contents exceed the component's maximum width.
+     *
+     * ```tsx
+     * <StatusIndicator.Label>{The text to be rendered}</StatusIndicator.Label>
+     * ```
+     */
     Label: StatusIndicatorLabel,
+    /**
+     * `StatusIndicator.Icon` renders {@link SystemIcon} under the hood. It's used as a decorative
+     * element to visually support the {@link StatusIndicatorLabel StatusIndicator.Label} text.
+     *
+     * ```tsx
+     * <StatusIndicator.Icon icon={uploadCloudIcon} />
+     * ```
+     */
+    Icon: StatusIndicatorIcon,
   },
 })<StatusIndicatorProps>(({children, ...elemProps}, Element, model) => {
   return (

package/status-indicator/lib/StatusIndicatorIcon.tsx

@@ -72,7 +72,7 @@ export const statusIndicatorColors = {
   },
 };
 
-const useStatusIndicatorIcon = createElemPropsHook(useStatusIndicatorModel)(({state}) => {
+export const useStatusIndicatorIcon = createElemPropsHook(useStatusIndicatorModel)(({state}) => {
   const colors = statusIndicatorColors[state.variant][state.emphasis];
   return {
     color: colors.text,