@workday/canvas-kit-docs 5.3.0-next.3 → 5.3.0-next.32

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,
@@ -52,7 +53,7 @@ The `Popup` component is a generic
 [Compound Component](/getting-started/for-developers/resources/compound-components/) that is used to
 build popup UIs that are not already covered by Canvas Kit.
 
-### Basic
+### Basic Example
 
 The Popup has no pre-defined behaviors built in, therefore the `usePopupModel` must always be used
 to create a new `model`. This `model` is then used by all behavior hooks to apply additional popup
@@ -63,7 +64,7 @@ popup behaviors. For accessibility, these behaviors should be included most of t
 
 <ExampleCodeBlock code={Basic} />
 
-### Initial focus
+### Initial Focus
 
 If you want focus to move to a specific element when the popup is opened, set the `initialFocusRef`
 of the model. Check with accessibility before doing this. The following example sets the focus on
@@ -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.
@@ -153,7 +173,7 @@ The Popup component automatically handles right-to-left rendering.
 
 ## Components
 
-## Popper
+### Popper
 
 A thin wrapper component around the Popper.js positioning engine. For reference:
 https://popper.js.org/. `Popper` also automatically works with the `PopupStack` system. `Popper` has
@@ -169,7 +189,7 @@ PopupModel or any associate popup [hooks](#hooks).
 > element was rendered and that's where extra props were spread to. In v5+, you can provide your own
 > element if you wish.
 
-## Popup
+### Popup
 
 This component is a container component that has no semantic element. It provides a React Context
 model for all Popup subcomponents. If you manually pass a `model` to all subcomponents, this
@@ -189,7 +209,7 @@ container component isn't needed.
 
 <ArgsTable of={Popup} />
 
-## Popup.Target
+### Popup.Target
 
 A `Popup.Target` is any element that is meant to show the Popup. The default component rendered by
 this component is a `SecondaryButton` element. You can override this by passing the desired
@@ -217,7 +237,7 @@ used, which is `SecondaryButton`. If you don't want any styling, you can do the
 To add your own styling, you could either add a `css` prop, or make a styled button and pass that
 styled component via the `as` prop.
 
-## Popup.Popper
+### Popup.Popper
 
 A `Popup.Popper` is a [Popper](#popper) component that is hooked up to the `PopupModel`
 automatically. The behavior hook used is called `usePopupPopper`.
@@ -229,7 +249,7 @@ automatically. The behavior hook used is called `usePopupPopper`.
 
 <ArgsTable of={Popup.Popper} />
 
-## Popup.Card
+### Popup.Card
 
 A `Popup.Card` is a wrapper around the `Card` component, but hooked up to a `PopupModel`. By
 default, this element has a `role=dialog` and an `aria-labelledby`. The behavior hook used is called
@@ -237,7 +257,7 @@ default, this element has a `role=dialog` and an `aria-labelledby`. The behavior
 
 <ArgsTable of={Popup.Card} />
 
-## Popup.CloseButton
+### Popup.CloseButton
 
 A `Popup.CloseButton` is a button that will hide a popup. By default, this is a `SecondaryButton`
 component, but `as` can be used to render any button element (i.e `<DeleteButton>` or
@@ -245,14 +265,14 @@ component, but `as` can be used to render any button element (i.e `<DeleteButton
 
 <ArgsTable of={Popup.CloseButton} />
 
-## Popup.CloseIcon
+### Popup.CloseIcon
 
 A `Popup.CloseIcon` is an icon button that is the `X` in the top of a popup. It will hide a popup
 when clicked. The behavior hook used is called `usePopupCloseButton`.
 
 <ArgsTable of={Popup.CloseIcon} />
 
-## Popup.Heading
+### Popup.Heading
 
 A `Popup.Heading` is a wrapper around `Card.Heading` that connect the heading to a `PopupModel`. It
 will add an `id` to the element that match the `aria-labelledby` that is applied to the `Popup.Card`
@@ -260,29 +280,29 @@ element for accessibility. The behavior hook used is called `usePopupHeading`.
 
 <ArgsTable of={Popup.Heading} />
 
-## Popup.Body
+### Popup.Body
 
 A `Popup.Body` is a thin wrapper around `Card.Body` and doesn't actually take a model. It adds
 `body` styling and nothing else.
 
 <ArgsTable of={Popup.Body} />
 
-## Popup Model
+## Model
 
 The PopupModel contains all state and events needed for Popup behaviors and components. It composes
 a `DisclosureModel` for showing and hiding content.
 
-### Popup Model State
+### Config
 
-<ArgsTable of={PopupStateComponent} />
+<ArgsTable of={PopupModelConfigComponent} />
 
-### Popup Model Events
+### State
 
-<ArgsTable of={PopupEventsComponent} />
+<ArgsTable of={PopupStateComponent} />
 
-### Popup Model Config
+### Events
 
-<ArgsTable of={PopupModelConfigComponent} />
+<ArgsTable of={PopupEventsComponent} />
 
 ## Hooks
 
@@ -325,7 +345,7 @@ return (
 );
 ```
 
-## useAssistiveHideSiblings
+### useAssistiveHideSiblings
 
 ```ts
 useAssistiveHideSiblings(model: PopupModel): {}
@@ -341,7 +361,7 @@ VoiceOver for example.
 
 This should be used on popup elements that need to hide content (i.e. Modals).
 
-## useBringToTopOnClick
+### useBringToTopOnClick
 
 ```ts
 useBringToTopOnClick(model: PopupModel): {}
@@ -355,7 +375,7 @@ like a Modal.
 
 This should be used on popup elements that are meant to persist (i.e. Windows).
 
-## useCloseOnEscape
+### useCloseOnEscape
 
 ```ts
 useCloseOnEscape(model: PopupModel): {}
@@ -367,7 +387,7 @@ provided model's `state.stackRef` element is the topmost in the stack.
 This should be used with popup elements that are dismissible like Tooltips, Modals, non-modal
 dialogs, dropdown menus, etc.
 
-## useCloseOnOutsideClick
+### useCloseOnOutsideClick
 
 ```ts
 useCloseOnOutsideClick(model: PopupModel): {}
@@ -382,7 +402,7 @@ This should be used with popup elements that are dismissible like Modals, non-mo
 dropdown menus, etc. Tooltips and hierarchical menus should use `useAlwaysCloseOnClickOutside`
 instead.
 
-## useAlwaysCloseOnOutsideClick
+### useAlwaysCloseOnOutsideClick
 
 ```ts
 useAlwaysCloseOnOutsideClick(model: PopupModel): {}
@@ -396,7 +416,16 @@ 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).
 
-## useDisableBodyScroll
+### 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
 useDisableBodyScroll(model: PopupModel): {}
@@ -408,7 +437,7 @@ page scrolling while the popup is visible.
 This should be used with popup elements that hide all other content and force the user to accept or
 dismiss the popup before continuing (i.e. Modals).
 
-## useFocusRedirect
+### useFocusRedirect
 
 ```ts
 useFocusRedirect(model: PopupModel): {}
@@ -426,7 +455,7 @@ hook does no provide `aria-owns` and this must be provided yourself. Requires
 
 This should be used with non-modal dialogs.
 
-## useFocusTrap
+### useFocusTrap
 
 ```ts
 useFocusTrap(model: PopupModel): {}
@@ -440,7 +469,11 @@ with [useInitialFocus](#useinitialfocus) and [useReturnFocus](#usereturnfocus).
 
 This should be used on popup elements that need to hide content (i.e. Modals).
 
-## useInitialFocus
+### 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
@@ -449,7 +482,11 @@ reader users alike. This should be used with [useFocusRedirect](#usefocusredirec
 This should be used for popups that have focusable elements inside, like Modals, non-modal dialogs,
 menus, etc.
 
-## useReturnFocus
+### 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)
@@ -457,7 +494,32 @@ or [useFocusTrap](#usefocustrap) for a complete focus management solution.
 
 This should ble used on popup elements that use [useInitialFocus](#useinitialfocus).
 
-## usePopupPopper
+### 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
 usePopupPopper(model: PopupModel, elemProps: {}, ref: React.Ref<any>): {}
@@ -466,7 +528,7 @@ usePopupPopper(model: PopupModel, elemProps: {}, ref: React.Ref<any>): {}
 Adds the necessary props to a `Popper` component. Used by the [Popup.Popper](#popuppopper)
 subcomponent.
 
-## usePopupCard
+### usePopupCard
 
 ```ts
 usePopupCard(model: PopupModel, elemProps: {}, ref: React.Ref<any>): {}
@@ -474,7 +536,7 @@ usePopupCard(model: PopupModel, elemProps: {}, ref: React.Ref<any>): {}
 
 Adds the necessary props to a `Card` component. Used by the [Popup.Card](#popupcard) subcomponent.
 
-## usePopupCloseButton
+### usePopupCloseButton
 
 ```ts
 usePopupCloseButton(model: PopupModel, elemProps: {}, ref: React.Ref<any>): {}
@@ -484,18 +546,16 @@ Adds the necessary props to a close button component. Used by the
 [Popup.CloseButton](#popupclosebutton) subcomponent and [Popup.CloseIcon](#popupcloseicon)
 subcomponent.
 
-````
-
-## usePopupHeading
+### usePopupHeading
 
 ```ts
 usePopupHeading(model: PopupModel, elemProps: {}, ref: React.Ref<any>): {}
-````
+```
 
 Adds the necessary props to a `Heading` component. Used by the [Popup.Heading](#popupheading)
 subcomponent.
 
-## usePopupTarget
+### usePopupTarget
 
 ```ts
 usePopupTarget(model: PopupModel, elemProps: {}, ref: React.Ref<any>): {}

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/dist/mdx/react/radio/examples/Alert.tsx

@@ -14,13 +14,13 @@ export default () => {
       error={FormField.ErrorType.Alert}
       hintId="hint-alert"
       hintText="Deep Dish is no longer available. Please select a different crust."
-      label="Choose your pizza crust"
+      label="Choose Your Pizza Crust"
       useFieldset={true}
     >
       <RadioGroup name="crust" onChange={handleChange} value={value}>
-        <Radio disabled={true} label="Deep Dish (Sold Out)" value="deep-dish" />
+        <Radio disabled={true} label="Deep dish (sold out)" value="deep-dish" />
         <Radio label="Thin" value="thin" />
-        <Radio label="Gluten Free" value="gluten-free" />
+        <Radio label="Gluten free" value="gluten-free" />
         <Radio label="Cauliflower" value="cauliflower" />
       </RadioGroup>
     </FormField>

package/dist/mdx/react/radio/examples/Basic.tsx

@@ -10,11 +10,11 @@ export default () => {
   };
 
   return (
-    <FormField label="Choose your pizza crust" useFieldset={true}>
+    <FormField label="Choose Your Pizza Crust" useFieldset={true}>
       <RadioGroup name="crust" onChange={handleChange} value={value}>
-        <Radio label="Deep Dish" value="deep-dish" />
+        <Radio label="Deep dish" value="deep-dish" />
         <Radio label="Thin" value="thin" />
-        <Radio label="Gluten Free" value="gluten-free" />
+        <Radio label="Gluten free" value="gluten-free" />
         <Radio label="Cauliflower" value="cauliflower" />
       </RadioGroup>
     </FormField>

package/dist/mdx/react/radio/examples/Disabled.tsx

@@ -10,11 +10,11 @@ export default () => {
   };
 
   return (
-    <FormField label="Choose your pizza crust" useFieldset={true}>
+    <FormField label="Choose Your Pizza Crust" useFieldset={true}>
       <RadioGroup name="crust" onChange={handleChange} value={value}>
-        <Radio label="Deep Dish" value="deep-dish" />
+        <Radio label="Deep dish" value="deep-dish" />
         <Radio label="Thin" value="thin" />
-        <Radio disabled={true} label="Gluten Free (Sold Out)" value="gluten-free" />
+        <Radio disabled={true} label="Gluten free (sold out)" value="gluten-free" />
         <Radio label="Cauliflower" value="cauliflower" />
       </RadioGroup>
     </FormField>

package/dist/mdx/react/radio/examples/Error.tsx

@@ -14,13 +14,13 @@ export default () => {
       error={FormField.ErrorType.Error}
       hintId="hint-error"
       hintText="Deep Dish is no longer available. Please select a different crust."
-      label="Choose your pizza crust"
+      label="Choose Your Pizza Crust"
       useFieldset={true}
     >
       <RadioGroup name="crust" onChange={handleChange} value={value}>
-        <Radio disabled={true} label="Deep Dish (Sold Out)" value="deep-dish" />
+        <Radio disabled={true} label="Deep dish (sold out)" value="deep-dish" />
         <Radio label="Thin" value="thin" />
-        <Radio label="Gluten Free" value="gluten-free" />
+        <Radio label="Gluten free" value="gluten-free" />
         <Radio label="Cauliflower" value="cauliflower" />
       </RadioGroup>
     </FormField>

package/dist/mdx/react/radio/examples/LabelPosition.tsx

@@ -11,14 +11,14 @@ export default () => {
 
   return (
     <FormField
-      label="Choose your pizza crust"
+      label="Choose Your Pizza Crust"
       labelPosition={FormField.LabelPosition.Left}
       useFieldset={true}
     >
       <RadioGroup name="crust" onChange={handleChange} value={value}>
-        <Radio label="Deep Dish" value="deep-dish" />
+        <Radio label="Deep dish" value="deep-dish" />
         <Radio label="Thin" value="thin" />
-        <Radio label="Gluten Free" value="gluten-free" />
+        <Radio label="Gluten free" value="gluten-free" />
         <Radio label="Cauliflower" value="cauliflower" />
       </RadioGroup>
     </FormField>

package/dist/mdx/react/radio/examples/NoValue.tsx

@@ -12,11 +12,11 @@ export default () => {
 
   return (
     <>
-      <FormField label="Choose your pizza crust" useFieldset={true}>
+      <FormField label="Choose Your Pizza Crust" useFieldset={true}>
         <RadioGroup name="crust" onChange={handleChange} value={value}>
-          <Radio label="Deep Dish" />
+          <Radio label="Deep dish" />
           <Radio label="Thin" />
-          <Radio label="Gluten Free" />
+          <Radio label="Gluten free" />
           <Radio label="Cauliflower" />
         </RadioGroup>
       </FormField>

package/dist/mdx/react/radio/examples/RefForwarding.tsx

@@ -17,11 +17,11 @@ export default () => {
 
   return (
     <>
-      <FormField label="Choose your pizza crust" useFieldset={true}>
+      <FormField label="Choose Your Pizza Crust" useFieldset={true}>
         <RadioGroup name="crust" onChange={handleChange} value={value}>
-          <Radio label="Deep Dish" value="deep-dish" />
+          <Radio label="Deep dish" value="deep-dish" />
           <Radio label="Thin" value="thin" />
-          <Radio label="Gluten Free" ref={glutenFreeRef} value="gluten-free" />
+          <Radio label="Gluten free" ref={glutenFreeRef} value="gluten-free" />
           <Radio label="Cauliflower" value="cauliflower" />
         </RadioGroup>
       </FormField>

package/dist/mdx/react/radio/examples/Required.tsx

@@ -10,11 +10,11 @@ export default () => {
   };
 
   return (
-    <FormField label="Choose your pizza crust" required={true} useFieldset={true}>
+    <FormField label="Choose Your Pizza Crust" required={true} useFieldset={true}>
       <RadioGroup name="crust" onChange={handleChange} value={value}>
-        <Radio label="Deep Dish" value="deep-dish" />
+        <Radio label="Deep dish" value="deep-dish" />
         <Radio label="Thin" value="thin" />
-        <Radio label="Gluten Free" value="gluten-free" />
+        <Radio label="Gluten free" value="gluten-free" />
         <Radio label="Cauliflower" value="cauliflower" />
       </RadioGroup>
     </FormField>

package/dist/mdx/react/segmented-control/SegmentedControl.mdx

@@ -27,6 +27,6 @@ indexes and omit the `value` field. It is strongly recommended to not mix these
 
 ## Props
 
-Undocumented props are spread to the underlying container `div` element.
+Undocumented props are spread to the underlying container `<div>` element.
 
 <ArgsTable of={SegmentedControl} />