Contextual Help Documentation #2352 (#2831)

Author: arumsey

packages/@react-spectrum/contextualhelp/docs/ContextualHelp.mdx

@@ -0,0 +1,128 @@
+{/* Copyright 2022 Adobe. All rights reserved.
+This file is licensed to you under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License. You may obtain a copy
+of the License at http://www.apache.org/licenses/LICENSE-2.0
+Unless required by applicable law or agreed to in writing, software distributed under
+the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+OF ANY KIND, either express or implied. See the License for the specific language
+governing permissions and limitations under the License. */}
+
+import {Layout} from '@react-spectrum/docs';
+export default Layout;
+
+import docs from 'docs:@react-spectrum/contextualhelp';
+import {HeaderInfo, PropTable, PageDescription} from '@react-spectrum/docs';
+import packageData from '@react-spectrum/contextualhelp/package.json';
+
+```jsx import
+import {ContextualHelp} from '@react-spectrum/contextualhelp';
+import {Content, Footer} from '@react-spectrum/view';
+import {Heading, Text} from '@react-spectrum/text';
+import {Link} from '@react-spectrum/link';
+import {Flex} from '@react-spectrum/layout';
+```
+
+---
+category: Overlays
+keywords: [popover, field, input]
+after_version: 3.0.0-alpha.1
+---
+
+# ContextualHelp
+
+<PageDescription>{docs.exports.ContextualHelp.description}</PageDescription>
+
+<HeaderInfo
+  packageData={packageData}
+  componentNames={['ContextualHelp']}
+  sourceData={[]} />
+
+## Example
+
+```tsx example
+<ContextualHelp variant="info">
+  <Heading>Need help?</Heading>
+  <Content><Text>If you're having issues accessing your account, contact our customer support team for help.</Text></Content>
+</ContextualHelp>
+```
+
+## Content
+
+Unlike [Dialog](Dialog.html), the layout in ContextualHelp is very deliberate. Every ContextualHelp component is triggered as a popover where the
+trigger element is a quiet action button with either a help or info icon. Much like [Dialog](Dialog.html), however, ContextualHelp has sections that
+can be populated by providing the following components to your ContextualHelp as children:
+[Heading](Heading.html) (title), [Content](Content.html) (body), and [Footer](Footer.html) (link).
+Each of these components are required in a Spectrum compliant ContextualHelp except for `Footer` since including a link is optional.
+
+```tsx example
+<ContextualHelp variant="help">
+  <Heading>What is a segment?</Heading>
+  <Content><Text>Segments identify who your visitors are, what devices and services they use, where they navigated from, and much more.</Text></Content>
+  <Footer><Link>Learn more about segments</Link></Footer>
+</ContextualHelp>
+```
+
+## Placement
+
+ContextualHelp supports [Dialog placement](./DialogTrigger.html#dialog-placement) options for when the positioning of the popover needs to customized.
+
+```tsx example
+<ContextualHelp variant="info" placement="top start">
+  <Heading>Placement</Heading>
+  <Content><Text>The placement of this contextual help popover has been customized to use top start.</Text></Content>
+</ContextualHelp>
+```
+
+## Events
+
+ContextualHelp accepts an `onOpenChange` prop, triggered when the ContextualHelp's popover opens or closes.
+
+The example below uses `onOpenChange` to update a separate element with the current open state of the Dialog.
+
+```tsx example
+function Example() {
+  let [state, setState] = React.useState(false);
+
+  return (
+    <Flex alignItems="center" gap="size-100">
+      <ContextualHelp variant="info" onOpenChange={(isOpen) => setState(isOpen)}>
+        <Heading>Permission required</Heading>
+        <Content><Text>Your admin must grant you permission before you can create a segment.</Text></Content>
+      </ContextualHelp>
+      <Text>Current open state: {state.toString()}</Text>
+    </Flex>
+  );
+}
+```
+
+## Props
+
+<PropTable component={docs.exports.ContextualHelp} links={docs.links} />
+
+## Visual options
+
+### Info
+
+Use the info icon for brief, specific, contextual guidance. This is best for supplemental or nice-to-know information,
+in-line with a label or a component (if there is no label). The content for an info icon’s popover should be [instructive](https://spectrum.adobe.com/page/voice-and-tone/#Tone-spectrum) in tone.
+
+```tsx example
+<ContextualHelp variant="info">
+  <Heading>Permission required</Heading>
+  <Content><Text>Your admin must grant you permission before you can create a segment.</Text></Content>
+</ContextualHelp>
+```
+
+### Help
+
+Use the help icon for content that offers more detailed, in-depth guidance about a task, UI element, tool, or keyboard shortcuts.
+This may include an image, video, or link and should be [helpful](https://spectrum.adobe.com/page/voice-and-tone/#Tone-spectrum) in tone.
+
+```tsx example
+<ContextualHelp variant="help">
+  <Heading>What is a segment?</Heading>
+  <Content><Text>Segments identify who your visitors are, what devices and services they use, where they navigated from, and much more.</Text></Content>
+  <Footer><Link>Learn more about segments</Link></Footer>
+</ContextualHelp>
+```
+

packages/@react-spectrum/contextualhelp/src/contextualhelp.css

@@ -30,7 +30,7 @@
 
 }
 
-.react-spectrum-ContextualHelp-dialog {
+.react-spectrum-ContextualHelp-dialog.react-spectrum-ContextualHelp-dialog {
   width: var(--spectrum-contexualhelp-dialog-width);
   --spectrum-dialog-padding-x: var(--spectrum-contextualhelp-dialog-padding);
   --spectrum-dialog-padding-y: var(--spectrum-contextualhelp-dialog-padding);