@workday/canvas-kit-docs 6.1.3 → 6.2.1

package/dist/mdx/5.0-MIGRATION-GUIDE.mdx

@@ -10,6 +10,7 @@ any questions about the update.
   - [Canvas Kit Preview](#canvas-kit-preview)
   - [Type Deprecations and Hierarchy Updates](#type-deprecations-and-hierarchy-updates)
   - [Canvas Kit CSS Maintenance Mode](#canvas-kit-css-maintenance-mode)
+  - [Prop Interfaces](#prop-interfaces)
 - [Component Changes](#component-changes)
   - [Component Promotions](#component-promotions)
   - [Core](#core)
@@ -423,6 +424,59 @@ provide more focused support and to dedicate our efforts to making bigger and be
 our most used components: Canvas Kit React. If you have questions or concerns, please
 [let us know](https://github.com/Workday/canvas-kit/issues/new?labels=&template=question.md).
 
+### Prop Interfaces
+
+Many components were updated to be polymorphic using the `createComponent` utility function. Most
+components in Canvas Kit extend from an HTML interface and spread extra props onto the HTML element.
+Since these components are now polymorphic, the exported props no longer extend from an HTML
+interface since the HTML interface is now determined by an optional `as` prop. It is common to wrap
+Canvas Kit components with your own component and extend from the Canvas Kit component's prop
+interface. To support this use-case in addition to polymorphic prop interfaces, `ExtractProp` was
+introduced. `ExtractProp` understands these polymorphic components and will return the base props in
+addition to the HTML interface. There is an optional second argument that can override the default
+HTML interface if your wrapper component uses the `as`.
+
+```tsx
+// v4
+import {TextInput, TextInputProps} from '@workday/canvas-kit-react-text-input';
+
+const FancyTextInput: React.FC<TextInputProps> = props => <TextInput {...props} />;
+
+// v5
+import {TextInput} from '@workday/canvas-kit-react/text-input';
+import {ExtractProps} from '@workday/canvas-kit-react/common';
+
+const FancyTextInput: React.FC<ExtractProps<typeof TextInput>> = props => {};
+
+// v5 via createComponent
+import {TextInput} from '@workday/canvas-kit-react/text-input';
+import {createComponent} from '@workday/canvas-kit-react/common';
+
+const FancyTextInput = createComponent(TextInput)({
+  displayName: 'FancyTextInput',
+  Component((props) => <TextInput {...props} />)
+})
+```
+
+Components that made this change:
+
+- Button
+- IconButton
+- Card
+- Hyperlink
+- Select
+- TextArea
+- TextInput
+- Checkbox
+- Radio
+- ColorInput
+- ColorPreview
+- Modal
+- Popup
+- Skeleton
+- Tabs
+- Toast
+
 ## Component Changes
 
 ### Component Promotions
@@ -799,20 +853,25 @@ Button prop interface and accesses properties like `onClick`, you'll need to pro
 attribute yourself in order to avoid TypeScript issues (this doesn't affect runtime). This is not
 code-moddable since intent cannot be pre-determined.
 
+#### Props
+
+The exported props no longer extend from the `HTMLButtonElement` interface. Use
+[ExtractProps](#prop-interfaces) instead.
+
 ```tsx
 interface MyButtonProps extends ButtonProps {}
 
 // onClick no longer exists in `ButtonProps`, so TypeScript will complain about onClick not
 // existing in `MyButtonProps` (`onClick` does exist as a prop on `<Button>`, however)
 const MyButton = ({children, onClick}: MyButtonProps) => (
-  <Button onClick={onClick}>{children}</Button>
+  <SecondaryButton onClick={onClick}>{children}</SecondaryButton>
 );
 
 // After
-interface MyButtonProps extends ButtonProps, React.ButtonHTMLAttributes<HTMLButtonElement> {}
+interface MyButtonProps extends ExtractProps<typeof SecondaryButton> {}
 
 // After (alternate fix)
-interface MyButtonProps extends ButtonProps {
+interface MyButtonProps extends ExtractProps<> {
   onClick?: React.MouseEventHandler<HTMLButtonElement>;
 }
 ```
@@ -881,6 +940,21 @@ const props = {
 import {Card} from './Card' // where `Card` is a re-exported Canvas Kit `Card`
 ```
 
+#### Props
+
+The exported props no longer extend from the `HTMLDivElement` interface. Use
+[ExtractProps](#prop-interfaces) instead.
+
+```tsx
+// NOT handled by the codemod
+
+// v4
+interface MyCard extends CardProps {}
+
+// v5
+interface MyCard extends ExtractProps<typeof Card>
+```
+
 ---
 
 ### Inputs
@@ -924,14 +998,14 @@ element that `inputRef` was applied to previously. Select and Select (Preview) d
 `inputRef` in v4, but now support `ref` in v5. See each component's documentation for information on
 which element `ref` is forwarded to for that particular component.
 
+#### Props
+
 Input component prop interfaces no longer extend directly from their underlying element interface
 (e.g. `TextInputProps` no longer extends from `React.InputHTMLAttributes<HTMLInputElement>`).
 `createComponent` returns a component that determines the element interface via the `as` prop. This
 is why input component props no longer contain an element interface directly. If you extend from an
 input component prop interface, or have code that uses an input component prop interface and
-accesses properties like `onClick`, you'll need to provide the input attribute yourself in order to
-avoid TypeScript issues (this doesn't affect runtime). This is not code-moddable since intent cannot
-be pre-determined.
+accesses properties like `onClick`, you'll need to use [ExtractProps](#prop-interfaces) instead.
 
 ```tsx
 interface MyTextInputProps extends TextInputProps {}
@@ -941,7 +1015,7 @@ interface MyTextInputProps extends TextInputProps {}
 const MyTextInput = ({onClick}: MyTextInputProps) => <TextInput onClick={onClick} />;
 
 // Fix
-interface MyTextInputProps extends TextInputProps, React.InputHTMLAttributes<HTMLInputElement> {}
+interface MyTextInputProps extends ExtractProps<typeof TextInput> {}
 
 // Alternate fix
 interface MyTextInputProps extends TextInputProps {

package/dist/mdx/preview-react/menu/examples/ContextMenu.tsx

@@ -8,6 +8,7 @@ import {
   usePopupModel,
   useAlwaysCloseOnOutsideClick,
   useCloseOnEscape,
+  useTransferOnFullscreenExit,
 } from '@workday/canvas-kit-react/popup';
 
 const ContextMenuTarget = createComponent('div')({
@@ -40,6 +41,7 @@ export default () => {
 
   useAlwaysCloseOnOutsideClick(model);
   useCloseOnEscape(model);
+  useTransferOnFullscreenExit(model);
 
   return (
     <Popup model={model}>

package/dist/mdx/react/_examples/CookieBanner.mdx

@@ -0,0 +1,8 @@
+import Basic from './examples/CookieBanner';
+
+
+# Canvas Kit Examples
+
+## CookieBanner
+
+<ExampleCodeBlock code={Basic} />

package/dist/mdx/react/_examples/examples/CookieBanner.tsx

@@ -0,0 +1,97 @@
+import * as React from 'react';
+
+import {createComponent, styled, StyledType} from '@workday/canvas-kit-react/common';
+import {colors, commonColors, depth, type, space} from '@workday/canvas-kit-react/tokens';
+import {PrimaryButton, TertiaryButton} from '@workday/canvas-kit-react/button';
+
+const CookieBannerItem = createComponent('div')({
+  displayName: 'CookieBanner.Item',
+  Component: ({isRow, ...elProps}: ItemProps, ref) => (
+    <BannerItem ref={ref} isRow={isRow} {...elProps} />
+  ),
+});
+
+const CookieBanner = createComponent('div')({
+  displayName: 'CookieBanner',
+  Component: (props: BannerProps, ref, Element) => <Banner ref={ref} as={Element} {...props} />,
+  subComponents: {Item: CookieBannerItem},
+});
+
+export default () => {
+  const DefaultNotice = `We use cookies to ensure that we give you the best experience on our website. 
+    If you continue without changing your settings, we'll assume that you are willing to receive cookies.`;
+
+  return (
+    <ExampleContainer>
+      <CookieBanner isClosed={false}>
+        <CookieBanner.Item>{DefaultNotice}</CookieBanner.Item>
+        <CookieBanner.Item isRow>
+          <TertiaryButton>Settings</TertiaryButton>
+          <PrimaryButton>Continue</PrimaryButton>
+        </CookieBanner.Item>
+      </CookieBanner>
+    </ExampleContainer>
+  );
+};
+
+interface BannerProps {
+  isClosed?: boolean;
+}
+
+interface ItemProps {
+  isRow?: boolean;
+}
+
+const ExampleContainer = styled('div')({
+  minHeight: 84,
+  margin: space.xs,
+  position: 'relative',
+});
+
+const Banner = styled('div')<BannerProps & StyledType>(
+  type.levels.subtext.medium,
+  {
+    backgroundColor: commonColors.background,
+    borderTop: `1px solid ${colors.soap400}`,
+    display: 'flex',
+    ...depth[1],
+    padding: space.m,
+    alignItems: 'center',
+    justifyContent: 'space-between',
+    position: 'absolute',
+    bottom: 0,
+    left: 0,
+    right: 0,
+    zIndex: 99,
+    transition: 'transform 0.2s ease-out',
+    '@media (max-width: 450px)': {
+      flexDirection: 'column',
+      alignItems: 'stretch',
+      textAlign: 'center',
+      padding: `${space.s} 0`,
+    },
+  },
+  ({isClosed}) => isClosed && {transform: 'translateY(100%)'}
+);
+
+const BannerItem = styled('div')<ItemProps & StyledType>(
+  {
+    marginLeft: space.s,
+    marginRight: space.s,
+    '@media (max-width: 450px)': {
+      '&:not(:first-of-type)': {
+        marginTop: space.s,
+        '> *': {
+          flex: 1,
+        },
+      },
+    },
+  },
+  ({isRow}) =>
+    isRow && {
+      display: 'flex',
+      '> *': {
+        marginLeft: space.s,
+      },
+    }
+);

package/dist/mdx/react/popup/Popup.mdx

@@ -9,6 +9,7 @@ import FocusRedirect from './examples/FocusRedirect';
 import FocusTrap from './examples/FocusTrap';
 import RTL from './examples/RTL';
 import CustomTarget from './examples/CustomTarget';
+import FullScreen from './examples/FullScreen';
 import {
   PopupModelConfigComponent,
   PopupStateComponent,
@@ -143,6 +144,25 @@ requires a `label` prop.
 
 <ExampleCodeBlock code={CustomTarget} />
 
+### Full Screen API
+
+By default, popups are created as children of the `document.body` element, but the `PopupStack`
+supports the [Fullscreen API](https://developer.mozilla.org/en-US/docs/Web/API/Fullscreen_API). When
+fullscreen is entered, the `PopupStack` will automatically create a new stacking context for all
+future popups. Any existing popups will disappear, but not be removed. They disappear because the
+fullscreen API is only showing content within the fullscreen element. There are instances where a
+popup may not close when fullscreen is exited:
+
+- The escape key is used to exit fullscreen
+- There is a button to exit fullscreen, but the popup doesn't use `useCloseOnOutsideClick`
+
+If fullscreen is exited, popups within the fullscreen stacking context are not removed or
+transferred automatically. If you do not handle this case, the popup may not render correctly. This
+example shows a popup that closes when fullscreen is entered/exited and another popup that transfers
+the popup's stack context when entering/exiting fullscreen.
+
+<ExampleCodeBlock code={FullScreen} />
+
 ### RTL
 
 The Popup component automatically handles right-to-left rendering.
@@ -396,6 +416,15 @@ stack. This is useful for Tooltips or hierarchical menus. Adds a
 This should be used with popup elements that should close no matter their position in the stack
 (i.e. Tooltips).
 
+### useCloseOnFullscreenExit
+
+```ts
+useCloseOnFullscreenExit(model: PopupModel): {}
+```
+
+Closes the popup when fullscreen is exited. Entering/exiting fullscreen changes the context of the
+entire screen. This should be added to popup types that are very context sensitive like Tooltips.
+
 ### useDisableBodyScroll
 
 ```ts
@@ -442,6 +471,10 @@ This should be used on popup elements that need to hide content (i.e. Modals).
 
 ### useInitialFocus
 
+```ts
+useInitialFocus(model: PopupModel): {}
+```
+
 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](#usefocusredirect) or
 [useFocusTrap](#usefocustrap) for a complete focus management solution.
@@ -451,12 +484,41 @@ menus, etc.
 
 ### useReturnFocus
 
+```ts
+useReturnFocus(model: PopupModel): {}
+```
+
 Returns focus to the target element when the popup is hidden. This works well with
 [useInitialFocus](#useinitialfocus). This should be used with [useFocusRedirect](#usefocusredirect)
 or [useFocusTrap](#usefocustrap) for a complete focus management solution.
 
 This should ble used on popup elements that use [useInitialFocus](#useinitialfocus).
 
+### useTransferOnFullscreenEnter
+
+```ts
+useTransferOnFullscreenEnter(model: PopupModel): {}
+```
+
+Makes the popup transfer to the fullscreen element when fullscreen is entered. Without this, the
+popup would seem to disappear because the popup container element is not a child of the fullscreen
+element.
+
+Don't use this in conjunction with a hook that will close the popup when entering fullscreen. Doing
+so would open the popup when the intention was to close it.
+
+### useTransferOnFullscreenExit
+
+```ts
+useTransferOnFullscreenExit(model: PopupModel): {}
+```
+
+Makes the popup transfer to fullscreen when fullscreen is exited. Without this hook, the popup would
+not operate correctly with other popups on the screen.
+
+Don't use this in conjunction with a hook that will close the popup when exiting fullscreen. Doing
+so would open the popup when the intention was to close it.
+
 ### usePopupPopper
 
 ```ts

package/dist/mdx/react/popup/examples/FullScreen.tsx

@@ -0,0 +1,115 @@
+import * as React from 'react';
+
+import {SecondaryButton} from '@workday/canvas-kit-react/button';
+import {
+  Popup,
+  useCloseOnEscape,
+  useCloseOnOutsideClick,
+  useFocusTrap,
+  useInitialFocus,
+  useReturnFocus,
+  usePopupModel,
+  useCloseOnFullscreenExit,
+  useTransferOnFullscreenExit,
+  useTransferOnFullscreenEnter,
+} from '@workday/canvas-kit-react/popup';
+import {HStack, Flex} from '@workday/canvas-kit-labs-react/layout';
+import {useIsFullscreen} from '@workday/canvas-kit-react/common';
+import screenfull from 'screenfull';
+
+const SelfClosePopup = () => {
+  const model = usePopupModel();
+
+  useCloseOnOutsideClick(model);
+  useCloseOnEscape(model);
+  useInitialFocus(model);
+  useReturnFocus(model);
+  useFocusTrap(model);
+  useCloseOnFullscreenExit(model);
+
+  return (
+    <Popup model={model}>
+      <Popup.Target>Open Self-close Popup</Popup.Target>
+      <Popup.Popper>
+        <Popup.Card width={400} padding="s">
+          <Popup.CloseIcon aria-label="Close" />
+          <Popup.Heading>Self-close Popup</Popup.Heading>
+          <Popup.Body>
+            <p>
+              When in fullscreen, the escape key will be highjacked by the browser to exit
+              fullscreen and <code>useCloseOnEscape</code> hook will not receive the escape key. To
+              close when fullscreen is exited, use the <code>useCloseOnFullscreenExit</code> hook.
+            </p>
+          </Popup.Body>
+          <Popup.CloseButton>Close</Popup.CloseButton>
+        </Popup.Card>
+      </Popup.Popper>
+    </Popup>
+  );
+};
+
+const TransferClosePopup = () => {
+  const model = usePopupModel();
+
+  useCloseOnEscape(model);
+  useInitialFocus(model);
+  useReturnFocus(model);
+  useFocusTrap(model);
+  useTransferOnFullscreenEnter(model);
+  useTransferOnFullscreenExit(model);
+
+  return (
+    <Popup model={model}>
+      <Popup.Target>Open Transfer Popup</Popup.Target>
+      <Popup.Popper>
+        <Popup.Card width={400} padding="s">
+          <Popup.CloseIcon aria-label="Close" />
+          <Popup.Heading>Transfer Popup</Popup.Heading>
+          <Popup.Body>
+            <p>
+              When in fullscreen, the escape key will be highjacked by the browser to exit
+              fullscreen and <code>useCloseOnEscape</code> hook will not receive the escape key. To
+              close when fullscreen is exited, use the <code>useTransferOnFullscreenExit</code>{' '}
+              hook.
+            </p>
+          </Popup.Body>
+          <Popup.CloseButton>Close</Popup.CloseButton>
+        </Popup.Card>
+      </Popup.Popper>
+    </Popup>
+  );
+};
+
+export default () => {
+  // you could make this a hook depending on which fullscreen library your application uses
+  const fullscreenElementRef = React.useRef<HTMLDivElement>();
+  const isFullscreen = useIsFullscreen();
+
+  const enterFullScreen = () => {
+    screenfull.request(fullscreenElementRef.current);
+  };
+
+  const exitFullscreen = () => {
+    screenfull.exit();
+  };
+
+  return (
+    <>
+      <SecondaryButton onClick={enterFullScreen}>Open Fullscreen</SecondaryButton>
+      <Flex
+        ref={fullscreenElementRef}
+        alignItems="center"
+        justifyContent="center"
+        background="white"
+      >
+        <HStack spacing="s">
+          <SelfClosePopup />
+          <TransferClosePopup />
+          {isFullscreen ? (
+            <SecondaryButton onClick={exitFullscreen}>Exit fullscreen</SecondaryButton>
+          ) : null}
+        </HStack>
+      </Flex>
+    </>
+  );
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@workday/canvas-kit-docs",
-  "version": "6.1.3",
+  "version": "6.2.1",
   "description": "Documentation components of Canvas Kit components",
   "author": "Workday, Inc. (https://www.workday.com)",
   "license": "Apache-2.0",
@@ -50,7 +50,7 @@
   ],
   "dependencies": {
     "@storybook/csf": "0.0.1",
-    "@workday/canvas-kit-react": "^6.1.3"
+    "@workday/canvas-kit-react": "^6.2.1"
   },
   "devDependencies": {
     "fs-extra": "^10.0.0",
@@ -58,5 +58,5 @@
     "mkdirp": "^1.0.3",
     "typescript": "^3.8.3"
   },
-  "gitHead": "729934bb558b985af2b20a0444a4042c73adbaae"
+  "gitHead": "5182205f93321ee45e30db5458ae7e4a9775d7d3"
 }