@workday/canvas-kit-docs 7.0.0-alpha.89-next.16 → 7.0.0-alpha.92-next.19

package/dist/commonjs/lib/specs.js

@@ -1302,6 +1302,137 @@ module.exports = {specifications: [
   {
     "type": "file",
     "name": "Menu.spec.ts",
+    "children": [
+      {
+        "type": "describe",
+        "name": "Menu",
+        "children": [
+          {
+            "type": "describe",
+            "name": "given the [Components/Popups/Menu/React, Basic] story is rendered",
+            "children": [
+              {
+                "type": "it",
+                "name": "should pass axe checks"
+              },
+              {
+                "type": "it",
+                "name": "should have aria-haspopup set to true"
+              },
+              {
+                "type": "it",
+                "name": "should have aria-expanded set to false"
+              },
+              {
+                "type": "it",
+                "name": "should not show a menu"
+              },
+              {
+                "type": "describe",
+                "name": "when the \"Open Menu\" button is clicked",
+                "children": [
+                  {
+                    "type": "it",
+                    "name": "should set aria-expanded to true"
+                  },
+                  {
+                    "type": "it",
+                    "name": "should show menu"
+                  },
+                  {
+                    "type": "it",
+                    "name": "should transfer focus to the first menu item"
+                  },
+                  {
+                    "type": "describe",
+                    "name": "when escape key is pressed",
+                    "children": [
+                      {
+                        "type": "it",
+                        "name": "should have aria-expanded set to false"
+                      },
+                      {
+                        "type": "it",
+                        "name": "should not show a menu"
+                      },
+                      {
+                        "type": "it",
+                        "name": "return focus to the \"Open Menu\" button"
+                      }
+                    ]
+                  },
+                  {
+                    "type": "describe",
+                    "name": "when down arrow key is pressed",
+                    "children": [
+                      {
+                        "type": "it",
+                        "name": "should transfer focus to the second item"
+                      },
+                      {
+                        "type": "describe",
+                        "name": "when the enter key is pressed",
+                        "children": [
+                          {
+                            "type": "it",
+                            "name": "should have aria-expanded set to false"
+                          },
+                          {
+                            "type": "it",
+                            "name": "should not show a menu"
+                          },
+                          {
+                            "type": "it",
+                            "name": "should select the second item"
+                          }
+                        ]
+                      }
+                    ]
+                  },
+                  {
+                    "type": "describe",
+                    "name": "when the second item is clicked",
+                    "children": [
+                      {
+                        "type": "it",
+                        "name": "should have aria-expanded set to false"
+                      },
+                      {
+                        "type": "it",
+                        "name": "should not show a menu"
+                      },
+                      {
+                        "type": "it",
+                        "name": "should select the second item"
+                      }
+                    ]
+                  },
+                  {
+                    "type": "describe",
+                    "name": "when the user types a printable character \"t\"",
+                    "children": []
+                  },
+                  {
+                    "type": "describe",
+                    "name": "when up arrow key is pressed",
+                    "children": [
+                      {
+                        "type": "it",
+                        "name": "should focus on the last option"
+                      }
+                    ]
+                  }
+                ]
+              }
+            ]
+          }
+        ]
+      }
+    ]
+  },
+  {
+    "type": "file",
+    "name": "MenuPreview.spec.ts",
     "children": [
       {
         "type": "describe",

package/dist/es6/lib/specs.js

@@ -1302,6 +1302,137 @@ module.exports = {specifications: [
   {
     "type": "file",
     "name": "Menu.spec.ts",
+    "children": [
+      {
+        "type": "describe",
+        "name": "Menu",
+        "children": [
+          {
+            "type": "describe",
+            "name": "given the [Components/Popups/Menu/React, Basic] story is rendered",
+            "children": [
+              {
+                "type": "it",
+                "name": "should pass axe checks"
+              },
+              {
+                "type": "it",
+                "name": "should have aria-haspopup set to true"
+              },
+              {
+                "type": "it",
+                "name": "should have aria-expanded set to false"
+              },
+              {
+                "type": "it",
+                "name": "should not show a menu"
+              },
+              {
+                "type": "describe",
+                "name": "when the \"Open Menu\" button is clicked",
+                "children": [
+                  {
+                    "type": "it",
+                    "name": "should set aria-expanded to true"
+                  },
+                  {
+                    "type": "it",
+                    "name": "should show menu"
+                  },
+                  {
+                    "type": "it",
+                    "name": "should transfer focus to the first menu item"
+                  },
+                  {
+                    "type": "describe",
+                    "name": "when escape key is pressed",
+                    "children": [
+                      {
+                        "type": "it",
+                        "name": "should have aria-expanded set to false"
+                      },
+                      {
+                        "type": "it",
+                        "name": "should not show a menu"
+                      },
+                      {
+                        "type": "it",
+                        "name": "return focus to the \"Open Menu\" button"
+                      }
+                    ]
+                  },
+                  {
+                    "type": "describe",
+                    "name": "when down arrow key is pressed",
+                    "children": [
+                      {
+                        "type": "it",
+                        "name": "should transfer focus to the second item"
+                      },
+                      {
+                        "type": "describe",
+                        "name": "when the enter key is pressed",
+                        "children": [
+                          {
+                            "type": "it",
+                            "name": "should have aria-expanded set to false"
+                          },
+                          {
+                            "type": "it",
+                            "name": "should not show a menu"
+                          },
+                          {
+                            "type": "it",
+                            "name": "should select the second item"
+                          }
+                        ]
+                      }
+                    ]
+                  },
+                  {
+                    "type": "describe",
+                    "name": "when the second item is clicked",
+                    "children": [
+                      {
+                        "type": "it",
+                        "name": "should have aria-expanded set to false"
+                      },
+                      {
+                        "type": "it",
+                        "name": "should not show a menu"
+                      },
+                      {
+                        "type": "it",
+                        "name": "should select the second item"
+                      }
+                    ]
+                  },
+                  {
+                    "type": "describe",
+                    "name": "when the user types a printable character \"t\"",
+                    "children": []
+                  },
+                  {
+                    "type": "describe",
+                    "name": "when up arrow key is pressed",
+                    "children": [
+                      {
+                        "type": "it",
+                        "name": "should focus on the last option"
+                      }
+                    ]
+                  }
+                ]
+              }
+            ]
+          }
+        ]
+      }
+    ]
+  },
+  {
+    "type": "file",
+    "name": "MenuPreview.spec.ts",
     "children": [
       {
         "type": "describe",

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

@@ -5,6 +5,7 @@ Below are the breaking changes made in Canvas Kit v7. Please
 any questions about the update.
 
 - [Codemod](#codemod)
+- [Infrastructure](#infrastructure)
 - [Component Deprecations](#component-deprecations)
 - [Component Promotions](#component-promotion)
 - [Buttons](#buttons)
@@ -16,6 +17,7 @@ any questions about the update.
 - [Popup Cards](#popup-cards)
 - [Popper Props Update](#popper-props-update)
 - [Component Promotions](#component-promotion)
+- [Model Changes](#model-changes)
 - [Token Updates](#token-updates)
   - [Depth Tokens](#depth-tokens)
 
@@ -45,6 +47,19 @@ rollback more easily if necessary.**
 encounter any issues or use cases that we've missed. The `@workday/canvas-kit-codemod` package will
 help us maintain additional codemod transforms to make future migrations easier.
 
+## Infrastructure
+
+## Infrastructure Upgrades
+
+Breaking:
+
+- v7 now requires Typescript 4.1 and has dropped support for Typescript 3.5-3.9. Previously we used
+  `downlevel-dts` to support Typescript 3.5+ while using Typescript 3.8 features, but
+  `downlevel-dts` does not support the Typescript 4.1 features we use. Typescript 4.1 was release in
+  November, 2020 and we feel it is time to move forward. Reach out if you experience issues
+  upgrading your Typescript version. In our experience, Typescript 4.1 found a few more errors that
+  Typescript 3.8 did not, but the upgrade was manageable.
+
 ## Component Deprecations
 
 ### Deprecation Types
@@ -330,7 +345,7 @@ system.
 
 ## Segmented Control
 
-Segmente Control use to work when rendering `IconButton` as children. This has now moved to a
+Segmented Control use to work when rendering `IconButton` as children. This has now moved to a
 compound component and removed the use of `IconButton`.
 
 ### Breaking Change
@@ -463,6 +478,44 @@ If your code contains any hacks to make a `Modal` overflow, these hacks should n
 `max-height` of the `Modal.Body` element using calculations. These should be removed. The
 `Popup.Card` now has a max height and the `Popup.Body` height is automatically calculated.
 
+### Popup.Body
+
+The `Popup.Body` is now an overflow container. This means 2 things:
+
+- `Popup.Body` will scroll if the contents are too big to fit in the page
+- `Popup.Body` will hide focus rings that render outside the overflow container
+
+Our examples contained some buttons inside the `Body` element and had focus rings cut off. The
+adjustment is to move the buttons outside the `Body` element. This is most likely the desired
+structure anyways since the buttons will not scroll with the overflowed `Body` content.
+
+Before:
+
+```tsx
+<Modal.Card>
+  <Modal.Body>
+    Body Contents
+    <HStack spacing="s">
+      {/*will scroll with the body*/}
+      <Modal.CloseButton as={PrimaryButton}>Delete</Modal.CloseButton>
+      <Modal.CloseButton>Cancel</Modal.CloseButton>
+    </HStack>
+  </Modal.Body>
+</Modal.Card>
+```
+
+After:
+
+```tsx
+<Modal.Card>
+  <Modal.Body>Body Contents</Modal.Body>
+  <HStack spacing="s">
+    <Modal.CloseButton as={PrimaryButton}>Delete</Modal.CloseButton>
+    <Modal.CloseButton>Cancel</Modal.CloseButton>
+  </HStack>
+</Modal.Card>
+```
+
 ## Popper Props Update
 
 We removed the `containerElement` prop from Popper component because it's no longer needed with
@@ -482,6 +535,263 @@ main `react` package.
 - `Flex` was promoted from `@workday/canvas-kit-labs/layout` to `@workday/canvas-kit-react/layout`
 - `Stack` was promoted from `@workday/canvas-kit-labs/layout` to `@workday/canvas-kit-react/layout`
 
+## Model Changes
+
+### Guards and Callbacks
+
+We changed the signature of model event guards and callbacks. In v6, the parameters were in an
+object. This has a less than ideal developer experience as intellisense isn't engaged immediately
+and we don't plan on adding any additional parameters to guard and callback functions. We've removed
+the object wrapper.
+
+🤖 The codemod handles these changes automatically.
+
+Before:
+
+```tsx
+const model = useTabsModel({
+  onSelect({data: {id}, prevState}) {
+    console.log(id, prevState);
+  },
+});
+```
+
+After:
+
+```tsx
+const model = useTabsModel({
+  onSelect({id}, prevState) {
+    console.log(id, prevState);
+  },
+});
+```
+
+### Model Implementation
+
+If you don't extend models, you can skip this section.
+
+In v6 we supported Typescript 3.8 which limited the way types could be inferred and defined. Canvas
+Kit v7 now requires Typescript 4.1 which introduced
+[Template Literal Types](https://www.typescriptlang.org/docs/handbook/2/template-literal-types.html).
+This means that the guards and callbacks no longer need to be manually defined via an `eventMap`.
+Event maps were a stopgap, were manual, and prone to errors in defining them. Not all events had
+guards or callbacks there's no check other than manual review to ensure the existence of an event
+callback or guard. Template Literal Types allow us to properly type guards and callbacks without
+event maps. The previous types forced `data` to be an object. We've since dropped that restriction.
+You can still only pass a single argument to events. If you need additional information, use an
+object.
+
+This change also allowed us to remove a lot of boilerplate associated with models without
+sacrificing type safety. This change doesn't effect most use cases, but will effect those whole
+extended a model. We created a new utility function called `createModelHook` that helps set up
+types.
+
+Before:
+
+```ts
+export type MyState = {
+  value: string;
+};
+
+export type MyEvents = {
+  updateValue(data: {value: string}): void; // enforced that `data` is an object even if we only need to pass a string
+};
+
+export type MyModel = Model<MyState, MyEvents>;
+
+export const myEventMap = createEventMap<MyEvents>()({
+  guards: {
+    shouldUpdateValue: 'updateValue', // easy to forget or make a mistake on guard name
+  },
+  callbacks: {
+    onUpdateValue: 'updateValue',
+  },
+});
+
+export type MyBaseConfig = {
+  initialValue?: string;
+};
+
+export type MyConfig = MyBaseConfig & Partial<ToModelConfig<MyState, MyEvents, typeof myEventMap>>;
+
+const useMyModel = (config: MyConfig = {}): MyModel => {
+  const [value, setValue] = React.useState(config.initialValue || '');
+
+  const state = {value};
+
+  // useEventMap is used to wrap the event object with guards and callbacks according to the event map
+  const events = useEventMap(myEventMap, state, config, {
+    updateValue(data) {
+      setValue(data.value);
+    },
+  });
+
+  return {state, events};
+};
+```
+
+After:
+
+```tsx
+const useMyModel = createModelHook({
+  defaultConfig: {
+    initialValue: '',
+  },
+})(config => {
+  const [value, setValue] = React.useState(config.initialValue); // default is already handled
+
+  const state = {value};
+
+  const events = {
+    updateValue(value: string) {
+      // doesn't need to be an object anymore
+      setValue(value);
+    },
+  };
+
+  return {state, events};
+});
+```
+
+Notice the large reduction in Typescript type boilerplate. In this example, the only place that
+Typescript syntax exists is in the `updateValue` function definition. This allows better collocating
+of types and values. Also notice that `useEventMap` doesn't need to be used anymore. The
+`createModelHook` will automatically wrap the `events` returned to call guards and callbacks when
+appropriate. Today this is done via creating a new events object. Once we drop IE11 support, this
+can be done via a proxy instead. The `createModelHook` handles all type inference so we don't have
+to explicitly type everything. Also `createModelHook` attaches React Context directly to the hook
+along with `defaultConfig` and `requiredConfig` for model extension.
+
+If you extended a model, you'll notice all those types are no longer being exported. You'll have to
+use this new utility function. Here's an example we found in the wild:
+
+```tsx
+import {
+  BasePopupModelConfig,
+  createEventMap,
+  Model,
+  popupEventMap,
+  PopupEvents,
+  PopupModelConfig,
+  PopupState,
+  ToModelConfig,
+  useCloseOnEscape,
+  useEventMap,
+  useFocusTrap,
+  useInitialFocus,
+  usePopupModel,
+  useReturnFocus,
+} from '@workday/canvas-kit-react';
+
+type MyModalState = PopupState & {
+  showOverlay: boolean;
+};
+
+type MyModalEvents = PopupEvents;
+
+const myModalEventMap = createEventMap<MyModalEvents>()({
+  guards: {
+    ...popupEventMap.guards,
+  },
+  callbacks: {
+    ...popupEventMap.callbacks,
+  },
+});
+
+type MyBaseModalConfig = BasePopupModelConfig & {
+  showOverlay?: boolean;
+};
+
+type MyModalModel = Model<MyModalState, MyModalEvents>;
+
+type MyConfig = MyBaseConfig &
+  Partial<ToModelConfig<MyModalState, MyModalEvents, typeof myModalEventMap>>;
+
+export const useMyModalModel = (config: MyConfig = {}): MyModalModel => {
+  const [showOverlay] = React.useState(config.showOverlay ?? true);
+
+  const model = usePopupModel({
+    ...config,
+    // hook up to a redux store
+    onShow(...params) {
+      dispatch(setIsModalOpen(true));
+      config?.onShow?.(...params);
+    },
+    onHide(...params) {
+      dispatch(setIsModalOpen(false));
+      config?.onShow?.(...params);
+    },
+  });
+
+  useInitialFocus(model);
+  useReturnFocus(model);
+  useFocusTrap(model);
+  useCloseOnEscape(model);
+
+  const state = {
+    ...model.state,
+    showOverlay,
+  };
+
+  const events = useEventMap(myEventMap, state, config, {
+    ...model.events,
+  });
+
+  return {state, events};
+};
+```
+
+After:
+
+```ts
+import {
+  useCloseOnEscape,
+  useEventMap,
+  useFocusTrap,
+  useInitialFocus,
+  usePopupModel,
+  useReturnFocus,
+} from '@workday/canvas-kit-react';
+
+const useMyModalModel = createModelHook({
+  defaultConfig: {
+    ...usePopupModel.defaultConfig,
+    showOverlay: true,
+  },
+  requiredConfig: usePopupModel.requiredConfig,
+  contextOverride: usePopupModel.Context, // needed to make sure this model uses the same context as the popup model, otherwise it will create a new one
+})(config => {
+  // `mergeConfig` takes care of the manual merging we were doing earlier
+  const model = usePopupModel(
+    usePopupModel.mergeConfig(config, {
+      // hook up to a redux store
+      onShow() {
+        dispatch(setIsModalOpen(true));
+      },
+      onHide() {
+        dispatch(setIsModalOpen(false));
+      },
+    })
+  );
+
+  useInitialFocus(model);
+  useReturnFocus(model);
+  useFocusTrap(model);
+  useCloseOnEscape(model);
+
+  const state = {
+    ...model.state,
+    showOverlay,
+  };
+
+  return {...model, state};
+});
+```
+
+All the cumbersome type boilerplate went away. Also all the type imports went away. The code is more
+focused on your unique logic and less on boilerplate. Unfortunately, this change doesn't have a
+codemod. While possible, this code isn't very common and the codemod would be very complex.
+
 ## Token Updates
 
 ### Depth Tokens

package/dist/mdx/changelog.stories.mdx

@@ -1,4 +1,5 @@
 import Changelog from '../../../CHANGELOG.md';
 import Markdown from '../../../utils/storybook/Markdown.tsx';
 
+
 <Markdown content={Changelog} />

package/dist/mdx/preview-react/form-field/examples/Custom.tsx

@@ -5,13 +5,12 @@ import {
   useFormFieldLabel,
   useFormFieldModel,
   useFormFieldOrientation,
-  FormFieldModelContext,
 } from '@workday/canvas-kit-preview-react/form-field';
 import {useModelContext} from '@workday/canvas-kit-react/common';
 import {Stack} from '@workday/canvas-kit-react/layout';
 
 const Label = ({model, children}) => {
-  const localModel = useModelContext(FormFieldModelContext, model);
+  const localModel = useModelContext(useFormFieldModel.Context, model);
   const props = useFormFieldLabel(localModel);
 
   return (
@@ -23,14 +22,14 @@ const Label = ({model, children}) => {
 };
 
 const Hint = ({model, children}) => {
-  const localModel = useModelContext(FormFieldModelContext, model);
+  const localModel = useModelContext(useFormFieldModel.Context, model);
   const props = useFormFieldHint(localModel);
 
   return <span {...props}>{children}</span>;
 };
 
 const Input = ({model, ...elementProps}) => {
-  const localModel = useModelContext(FormFieldModelContext, model);
+  const localModel = useModelContext(useFormFieldModel.Context, model);
   const props = useFormFieldInput(localModel, elementProps);
 
   return <input type="text" required={model.state.isRequired ? true : false} {...props} />;

package/dist/mdx/preview-react/menu/Menu.mdx

@@ -113,4 +113,4 @@ Undocumented props are spread to the underlying `<li>` element.
 
 ## Specifications
 
-<Specifications file="Menu.spec.ts" name="Menu" />
+<Specifications file="MenuPreview.spec.ts" name="Menu" />

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

@@ -3,7 +3,6 @@ import {
   setupIcon,
   uploadCloudIcon,
   userIcon,
-  extLinkIcon,
   taskContactIcon,
 } from '@workday/canvas-system-icons-web';
 import {Menu, MenuItem} from '@workday/canvas-kit-preview-react/menu';