Adding Unavailable Menu Item docs (#4763)

* Adding Unavailable Menu Item docs

* removing similar text

* rewording two concepts

* fix spelling mistakes

Co-authored-by: Michael Jordan <[email protected]>

* Adding more explanation in a couple cases

* using the Unavailable Items as the name

* switching the order of two paragraphs

* update docs and types

* fix props table

* update types and docs table

* address review comments

---------

Co-authored-by: Michael Jordan <[email protected]>
Co-authored-by: Reid Barber <[email protected]>
Co-authored-by: Daniel Lu <[email protected]>
Co-authored-by: Robert Snow <[email protected]>

Author: 5 people

packages/@react-spectrum/menu/docs/MenuTrigger.mdx

@@ -10,8 +10,9 @@ governing permissions and limitations under the License. */}
 import {Layout} from '@react-spectrum/docs';
 export default Layout;
 
+import contextualHelpTriggerTypes from 'docs:@react-spectrum/menu/src/ContextualHelpTrigger.tsx';
 import docs from 'docs:@react-spectrum/menu';
-import {HeaderInfo, PropTable, PageDescription} from '@react-spectrum/docs';
+import {HeaderInfo, PropTable, PageDescription, VersionBadge} from '@react-spectrum/docs';
 import packageData from '@react-spectrum/menu/package.json';
 import {Keyboard} from '@react-spectrum/text';
 
@@ -33,7 +34,7 @@ keywords: [menu, dropdown, action menu]
 
 <HeaderInfo
   packageData={packageData}
-  componentNames={['MenuTrigger', 'Menu']}
+  componentNames={['MenuTrigger', 'Menu', 'ContextualHelpTrigger']}
   sourceData={[
     {type: 'Spectrum', url: 'https://spectrum.adobe.com/page/popover/'}
   ]}
@@ -121,10 +122,74 @@ import {Text} from '@react-spectrum/text';
 </MenuTrigger>
 ```
 
+## Unavailable Items <VersionBadge version="alpha" style={{marginLeft: 4, verticalAlign: 'bottom'}} />
+
+ContextualHelpTrigger disables a menu item's action and replaces it with a popover with information on why the item is unavailable and may link users to more information elsewhere.
+
+The ContextualHelpTrigger accepts exactly
+two children: the Item which triggers opening of the Dialog and the Dialog itself. The trigger must be
+the first child passed into the ContextualHelpTrigger and should be an Item. Similar to
+ContextualHelp, the layout of the Dialog is very deliberate. See [ContextualHelp](ContextualHelp.html#content) for further explanation.
+
+By default, a ContextualHelpTrigger's Dialog is opened by hovering, pressing the trigger element or activating
+it via the <Keyboard>Space</Keyboard>, <Keyboard>Enter</Keyboard>, or <Keyboard>Right Arrow</Keyboard> keys.
+Hovering another item or pressing the <Keyboard>Esc</Keyboard> key will close the Dialog and leave the Menu open.
+
+Setting the `isUnavailable` prop on the ContextualHelpTrigger makes a Menu Item unavailable and enables the Dialog with contextual help, allowing for programmatic control.
+
+Note that the Menu's `onAction` and `onSelectionChange`
+callbacks will not fire for items made unavailable by a ContextualHelpTrigger.
+
+The example below illustrates how one would setup a MenuTrigger to use ContextualHelpTrigger.
+
+```tsx example
+import {ContextualHelpTrigger} from '@react-spectrum/menu';
+import {Dialog} from '@react-spectrum/dialog';
+import {Heading} from '@react-spectrum/text';
+import {Content} from '@react-spectrum/view';
+
+<MenuTrigger>
+  <ActionButton>Edit</ActionButton>
+  <Menu>
+    <Item key="undo">Undo</Item>
+    <Item key="redo">Redo</Item>
+    <ContextualHelpTrigger isUnavailable>
+      <Item key="cut">Cut</Item>
+      <Dialog>
+        <Heading>Cut</Heading>
+        <Content>Please select text for 'Cut' to be enabled.</Content>
+      </Dialog>
+    </ContextualHelpTrigger>
+    <ContextualHelpTrigger isUnavailable>
+      <Item key="copy">Copy</Item>
+      <Dialog>
+        <Heading>Copy</Heading>
+        <Content>Please select text for 'Copy' to be enabled.</Content>
+      </Dialog>
+    </ContextualHelpTrigger>
+    <ContextualHelpTrigger>
+      <Item key="paste">Paste</Item>
+      <Dialog>
+        <Heading>Paste</Heading>
+        <Content>You have nothing to 'Paste'.</Content>
+      </Dialog>
+    </ContextualHelpTrigger>
+  </Menu>
+</MenuTrigger>
+```
+
 ## Props
 
+### MenuTrigger props
 <PropTable component={docs.exports.MenuTrigger} links={docs.links} />
 
+### ContextualHelpTrigger Props
+<PropTable component={{
+  props: {
+    properties: Object.fromEntries(Object.entries(docs.exports.SpectrumMenuDialogTriggerProps.properties))
+  }
+}} links={contextualHelpTriggerTypes.links} />
+
 ## Visual options
 
 ### Align and direction

packages/@react-spectrum/menu/src/ContextualHelpTrigger.tsx

@@ -19,12 +19,17 @@ import {Modal, Popover} from '@react-spectrum/overlays';
 import React, {Key, ReactElement, useRef} from 'react';
 import {useOverlayTriggerState} from '@react-stately/overlays';
 
-export interface SpectrumMenuDialogTriggerProps<T> extends ItemProps<T> {
+interface MenuDialogTriggerProps<T> extends ItemProps<T> {
+  /** Whether the menu item is currently unavailable. */
   isUnavailable?: boolean,
+  /** The triggering Item and the Dialog, respectively. */
+  children: [ReactElement, ReactElement],
   targetKey: Key
 }
 
-function ContextualHelpTrigger<T>(props: SpectrumMenuDialogTriggerProps<T>): ReactElement {
+export interface SpectrumMenuDialogTriggerProps<T> extends Omit<MenuDialogTriggerProps<T>, 'targetKey' | 'title' | 'textValue' | 'childItems' | 'hasChildItems'> {}
+
+function ContextualHelpTrigger<T>(props: MenuDialogTriggerProps<T>): ReactElement {
   let {isUnavailable} = props;
 
   let triggerRef = useRef<HTMLLIElement>(null);
@@ -114,5 +119,5 @@ ContextualHelpTrigger.getCollectionNode = function* getCollectionNode<T>(props:
   };
 };
 
-let _Item = ContextualHelpTrigger as <T>(props: ItemProps<T> & {isUnavailable?: boolean}) => JSX.Element;
+let _Item = ContextualHelpTrigger as <T>(props: SpectrumMenuDialogTriggerProps<T>) => JSX.Element;
 export {_Item as ContextualHelpTrigger};