@workday/canvas-kit-docs 6.1.5 → 6.3.0-next.0

package/dist/commonjs/lib/specs.js

@@ -6013,7 +6013,7 @@ module.exports = {specifications: [
               },
               {
                 "type": "describe",
-                "name": "when the \"Delete\" button is hovered",
+                "name": "when the \"Some Text\" text is hovered",
                 "children": [
                   {
                     "type": "it",

package/dist/es6/lib/specs.js

@@ -6013,7 +6013,7 @@ module.exports = {specifications: [
               },
               {
                 "type": "describe",
-                "name": "when the \"Delete\" button is hovered",
+                "name": "when the \"Some Text\" text is hovered",
                 "children": [
                   {
                     "type": "it",

package/dist/mdx/TESTING.mdx

@@ -29,7 +29,7 @@ do. A "test" simply has to pass. A specification requires meaning.
 test('SomeComponent should render correctly', async () => {
   const {getByTestId} = render(<SomeComponent data-testid="test" text="foo" />);
 
-  const component = await getByTestId('test');
+  const component = getByTestId('test');
 
   expect(component.textContent).toEqual('foo');
   expect(component.getAttribute('aria-label')).toEqual('foo');
@@ -53,14 +53,14 @@ describe('SomeComponent', () => {
   it('should render the "text" prop as the text', async () => {
     const {getByTestId} = render(<SomeComponent data-testid="test" text="foo" />);
 
-    const component = await getByTestId('test');
+    const component = getByTestId('test');
     expect(component).toHaveTextContent('foo');
   });
 
   it('should render the "text" prop as an aria-label for accessibility', async () => {
     const {getByTestId} = render(<SomeComponent data-testid="test" text="foo" />);
 
-    const component = await getByTestId('test');
+    const component = getByTestId('test');
     expect(component).toHaveAttribute('aria-label', 'foo');
   });
 });
@@ -124,8 +124,8 @@ const {getByTestId} = render(
   </SomeComponent>
 );
 
-const component = await getByTestId('container');
-const child = await getByTestId('test');
+const component = getByTestId('container');
+const child = getByTestId('test');
 
 expect(component).toContainElement(child);
 ```
@@ -136,6 +136,30 @@ specification is met). Also this example will have a more useful failure message
 `.toContainElement` has the context that it is expecting an element in another element vs a match of
 a string.
 
+### Snapshot tests
+
+Canvas Kit does not contain DOM-based snapshot tests and uses [Visual Tests](#visual-tests) instead.
+DOM snapshots failures are often difficult to parse. Humans tend to be better at noticing and
+discerning visual changes than changes to a DOM structure.
+
+If your project uses snapshot tests and Canvas Kit, chances are you'll run into issues with changing
+ids and other ARIA attributes. Canvas Kit generates unique ids that are different every time the
+page loads. This can be a problem with snapshot tests. To fix this, you'll need to add special code
+to your test bootstrap file. For example:
+
+```ts
+import {setUniqueSeed, resetUniqueIdCount} from '@workday/canvas-kit-react/common';
+
+beforeEach(() => {
+  setUniqueSeed('a'); // set a static seed
+  resetUniqueIdCount(); // reset the id counter before every test
+});
+```
+
+This will ensure snapshot tests have stable ids for each snapshot. It is still possible to get ids
+changing if you add an additional component that uses id generation - subsequent ids will be
+different, but this will prevent snapshot tests that don't have any changes from showing diffs.
+
 ## Functional tests
 
 Canvas Kit uses [Cypress][https://cypress.io] for browser-based behavior testing (additional info:

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.3.0-next.0+6e10a940",
   "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.3.0-next.0+6e10a940"
   },
   "devDependencies": {
     "fs-extra": "^10.0.0",
@@ -58,5 +58,5 @@
     "mkdirp": "^1.0.3",
     "typescript": "^3.8.3"
   },
-  "gitHead": "33b9994408c63b78923a201af73d8c2e6f7e5914"
+  "gitHead": "6e10a940283828fb6e34b23598a917a478bbabd6"
 }