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

package/pagination/lib/Pagination/GoTo/Label.tsx

@@ -1,20 +1,31 @@
 import * as React from 'react';
 import {PaginationModel} from '../types';
 import {LabelText} from '@workday/canvas-kit-react/text';
+import {createComponent} from '@workday/canvas-kit-react/common';
+import {PaginationContext} from '../usePaginationModel';
 
-export interface GoToLabelProps
-  extends Omit<React.LabelHTMLAttributes<HTMLLabelElement>, 'children'> {
-  model: PaginationModel;
+export interface GoToLabelProps {
   /**
    * Accepts child elements or a render prop.
    */
   children?: (model: PaginationModel) => React.ReactNode | React.ReactNode;
 }
 
-export const GoToLabel = ({model, children, ...elemProps}: GoToLabelProps) => {
-  return (
-    <LabelText typeLevel="subtext.medium" variant="hint" whiteSpace="nowrap" {...elemProps}>
-      {typeof children === 'function' ? children(model) : children}
-    </LabelText>
-  );
-};
+export const GoToLabel = createComponent('label')({
+  displayName: 'Pagination.GoToLabel',
+  Component({children, ...elemProps}: GoToLabelProps, ref, Element) {
+    const model = React.useContext(PaginationContext);
+    return (
+      <LabelText
+        ref={ref}
+        as={Element}
+        typeLevel="subtext.medium"
+        variant="hint"
+        whiteSpace="nowrap"
+        {...elemProps}
+      >
+        {typeof children === 'function' ? children(model) : children}
+      </LabelText>
+    );
+  },
+});

package/pagination/lib/Pagination/GoTo/TextInput.tsx

@@ -1,16 +1,20 @@
 import * as React from 'react';
 
 import {TextInput, TextInputProps} from '@workday/canvas-kit-react/text-input';
+import {createComponent} from '@workday/canvas-kit-react/common';
+
+import {GoToContext} from './useGoToForm';
 
 export type GoToTextInputProps = TextInputProps & {
   'aria-label': string;
   value?: string | number;
 };
 
-export const GoToTextInput = ({
-  'aria-label': ariaLabel,
-  value = '',
-  ...elemProps
-}: GoToTextInputProps) => {
-  return <TextInput aria-label={ariaLabel} size={1} value={value} width={55} {...elemProps} />;
-};
+export const GoToTextInput = createComponent('input')({
+  displayName: 'Pagination.GoToTextInput',
+  Component(elemProps: GoToTextInputProps, ref, Element) {
+    const {inputProps} = React.useContext(GoToContext);
+
+    return <TextInput ref={ref} as={Element} size={1} width={55} {...inputProps} {...elemProps} />;
+  },
+});

package/pagination/lib/Pagination/GoTo/useGoToForm.tsx

@@ -7,8 +7,10 @@ export interface UseGoToFormConfig {
   onSubmit?: (event: React.FormEvent<HTMLFormElement>) => void;
 }
 
+export const GoToContext = React.createContext({} as ReturnType<typeof useGoToForm>);
+
 export const useGoToForm = ({onSubmit, model}: UseGoToFormConfig = {} as UseGoToFormConfig) => {
-  const [value, setValue] = React.useState<number>();
+  const [value, setValue] = React.useState<number>(model.state.currentPage);
 
   React.useEffect(() => {
     if (value !== undefined && model.state.currentPage !== value) {

package/pagination/lib/Pagination/Nav.tsx

@@ -5,11 +5,10 @@ export interface PaginationNavProps extends Omit<FlexProps, 'as'> {
   'aria-label': string;
 }
 
-export const PaginationNav = ({'aria-label': ariaLabel, ...elemProps}: PaginationNavProps) => {
+export const PaginationNav = (elemProps: PaginationNavProps) => {
   return (
     <Flex
       as="nav"
-      aria-label={ariaLabel}
       display="inline-flex"
       flexDirection="column"
       alignItems="center"

package/pagination/lib/Pagination/PageButton.tsx

@@ -1,9 +1,14 @@
 import * as React from 'react';
-import {EmotionCanvasTheme, styled, useTheme} from '@workday/canvas-kit-react/common';
+import {
+  EmotionCanvasTheme,
+  styled,
+  useTheme,
+  createComponent,
+} from '@workday/canvas-kit-react/common';
 import {borderRadius, colors, space} from '@workday/canvas-kit-react/tokens';
 import {BaseButton} from '@workday/canvas-kit-react/button';
 
-import {PaginationModel} from './types';
+import {PaginationContext} from './usePaginationModel';
 
 const StyledPageButton = styled(BaseButton)<{toggled?: boolean}>(
   {
@@ -48,36 +53,34 @@ const getPaginationButtonColors = (toggled: boolean, theme: EmotionCanvasTheme)
   };
 };
 
-export type PageButtonProps = React.ButtonHTMLAttributes<HTMLButtonElement> & {
-  model: PaginationModel;
+export interface PageButtonProps {
   pageNumber: number;
-};
+  children?: React.ReactNode;
+}
 
-export const PageButton = ({
-  model,
-  onClick,
-  pageNumber,
-  children,
-  ...elemProps
-}: PageButtonProps) => {
-  const isCurrentPage = pageNumber === model.state.currentPage;
-  const theme = useTheme();
+export const PageButton = createComponent('button')({
+  displayName: 'Pagination.PageButton',
+  Component({pageNumber, children, ...elemProps}: PageButtonProps) {
+    const model = React.useContext(PaginationContext);
+    const isCurrentPage = pageNumber === model.state.currentPage;
+    const theme = useTheme();
 
-  const handleClick = (e: React.MouseEvent<HTMLButtonElement, MouseEvent>) => {
-    onClick?.(e);
-    model.events.goTo(pageNumber);
-  };
+    const handleClick = (e: React.MouseEvent<HTMLButtonElement, MouseEvent>) => {
+      (elemProps as any).onClick?.(e);
+      model.events.goTo(pageNumber);
+    };
 
-  return (
-    <StyledPageButton
-      aria-current={isCurrentPage ? 'page' : undefined}
-      colors={getPaginationButtonColors(isCurrentPage, theme)}
-      aria-pressed={undefined}
-      onClick={handleClick}
-      toggled={isCurrentPage}
-      {...elemProps}
-    >
-      {children || pageNumber}
-    </StyledPageButton>
-  );
-};
+    return (
+      <StyledPageButton
+        aria-current={isCurrentPage ? 'page' : undefined}
+        colors={getPaginationButtonColors(isCurrentPage, theme)}
+        aria-pressed={undefined}
+        onClick={handleClick}
+        toggled={isCurrentPage}
+        {...elemProps}
+      >
+        {children || pageNumber}
+      </StyledPageButton>
+    );
+  },
+});

package/pagination/lib/Pagination/PageList.tsx

@@ -2,31 +2,45 @@ import * as React from 'react';
 
 import {PaginationModel} from './types';
 import {ListItem, ListItemProps} from './common/List';
-import {HStack, HStackProps} from '@workday/canvas-kit-react/layout';
+import {Flex, FlexProps} from '@workday/canvas-kit-react/layout';
+import {createComponent} from '@workday/canvas-kit-react/common';
+import {PaginationContext} from './usePaginationModel';
 
-export interface PageListProps extends Omit<HStackProps, 'as' | 'spacing' | 'children'> {
-  model: PaginationModel;
+export interface PageListProps extends Omit<FlexProps, 'as' | 'children'> {
+  model?: PaginationModel;
   children?: (model: PaginationModel) => React.ReactNode[] | React.ReactNode;
 }
 
-export const PageList = ({model, children, ...elemProps}: PageListProps) => {
-  return (
-    <HStack
-      margin="zero"
-      as="ol"
-      role="list"
-      paddingLeft="zero"
-      paddingRight="zero"
-      spacing="xxxs"
-      {...elemProps}
-    >
-      {typeof children === 'function' ? children(model) : children}
-    </HStack>
-  );
-};
+export const PageList = createComponent('ol')({
+  displayName: 'Pagination.PageList',
+  Component({children, ...elemProps}: PageListProps, ref, Element) {
+    const model = React.useContext(PaginationContext);
+    return (
+      <Flex
+        ref={ref}
+        as={Element}
+        margin="zero"
+        role="list"
+        paddingLeft="zero"
+        paddingRight="zero"
+        gap="xxxs"
+        {...elemProps}
+      >
+        {typeof children === 'function' ? children(model) : children}
+      </Flex>
+    );
+  },
+});
 
-export type PageListItemProps = ListItemProps;
+export interface PageListItemProps extends ListItemProps {}
 
-export const PageListItem = ({children, ...elemProps}: PageListItemProps) => {
-  return <ListItem {...elemProps}>{children}</ListItem>;
-};
+export const PageListItem = createComponent('li')({
+  displayName: 'Pagination.PageListItem',
+  Component({children, ...elemProps}: PageListItemProps, ref, Element) {
+    return (
+      <ListItem ref={ref} as={Element} {...elemProps}>
+        {children}
+      </ListItem>
+    );
+  },
+});

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,
+  },
+});