@workday/canvas-kit-docs 6.1.5 → 6.2.3

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/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.5",
+  "version": "6.2.3",
   "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.5"
+    "@workday/canvas-kit-react": "^6.2.3"
   },
   "devDependencies": {
     "fs-extra": "^10.0.0",
@@ -58,5 +58,5 @@
     "mkdirp": "^1.0.3",
     "typescript": "^3.8.3"
   },
-  "gitHead": "33b9994408c63b78923a201af73d8c2e6f7e5914"
+  "gitHead": "64f8a882e13dacffa99b98da64243f0bfabb5365"
 }