docs(react-infobutton): Adding component's spec

packages/react-components/react-infobutton/Spec.md

@@ -1,63 +1,151 @@
 # @fluentui/react-infobutton Spec
 
+Convergence epic issue: [#25062](https://github.com/microsoft/fluentui/issues/25062)
+
 ## Background
 
-_Description and use cases of this component_
+An InfoButton provides a way for users to get more information about a particular UI element. It is a button containing an icon that, when clicked, displays a Popover with the additional information. InfoButton may contain focusable items inside the Popover.
+
+Because the Popover isn't always visible, it should not contain information that people must know in order to complete the field.
+
+### Anatomy
+
+![Anatomy](./etc/images/anatomy.png)
 
 ## Prior Art
 
-_Include background research done for this component_
+| Name | library | Notes |
+| --------------------------------------------------- | ------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| IconButtonTooltip | [Carbon Design System](https://www.carbondesignsystem.com/components/tooltip/usage) | This is an example within the tooltip component. |
+| Tooltip with card appearance and general tooltip | [EverGreen](https://evergreen.segment.com/components/tooltip) | This are examples within the tooltip component. This library doesn't use a button, instead just an icon. |
+| Input and guidance to add info button | [Salesforce](https://www.lightningdesignsystem.com/components/input/) | This component lives within Input and shows how to build an info button instead. |
+| TextField with example on how to add an info button | [v8](https://developer.microsoft.com/en-us/fluentui#/controls/web/textfield) | This is just an example and on how to implement it. |
+| ContextualHelp | [React Spectrum](https://react-spectrum.adobe.com/react-spectrum/ContextualHelp.html) | It's a full component and uses a Popover instead of tooltip. |
 
-- _Link to Open UI research_
-- _Link to comparison of v7 and v0_
-- _Link to GitHub epic issue for the converged component_
+#### Comparison with v0 and v8
+
+- v0 does not have an InfoButton component.
+- v8 does not have an InfoButton component, but does have a TextField component that has an example of how to add an info button to a TextField, see "Prior Art" section above for more details.
 
 ## Sample Code
 
-_Provide some representative example code that uses the proposed API for the component_
+```jsx
+<InfoButton content="This is some additional information." />
+```
 
 ## Variants
 
-_Describe visual or functional variants of this control, if applicable. For example, a slider could have a 2D variant._
+Visual (only the button has a variant)
+
+- `transparent` (default)
+
+![transparent](./etc/images/transparent-infobutton.png)
 
 ## API
 
-_List the **Props** and **Slots** proposed for the component. Ideally this would just be a link to the component's `.types.ts` file_
+#### Props
+
+```ts
+export type InfoButtonSlots = {
+ root: NonNullable<Slot<'button'>>;
+
+ /**
+ * The Popover element that wraps the content and root. Use this slot to pass props to the Popover.
+ */
+ popover: NonNullable<Slot<PopoverProps>>;
+
+ /**
+ * The content to be displayed in the PopoverSurface when the button is pressed.
+ */
+ content: NonNullable<Slot<typeof PopoverSurface>>;
+};
+
+/**
+ * InfoButton Props
+ */
+export type InfoButtonProps = ComponentProps<Partial<InfoButtonSlots>>;
+
+/**
+ * State used in rendering InfoButton
+ */
+export type InfoButtonState = ComponentState<InfoButtonSlots>;
+```
 
 ## Structure
 
-- _**Public**_
-- _**Internal**_
-- _**DOM** - how the component will be rendered as HTML elements_
+_**Public**_
+
+```jsx
+<InfoButton
+ content={
+ <>
+ Popover above-start lorem ipsum dolor sit amet consectetur.
+ <Link href="https://react.fluentui.dev">Learn more</Link>
+ </>
+ }
+/>
+```
+
+_**Internal**_
+
+```jsx
+return (
+ <slots.popover {...(slotProps.popover as PopoverProps)}>
+ <PopoverTrigger>
+ <slots.root {...slotProps.root} />
+ </PopoverTrigger>
+ <slots.content {...slotProps.content} />
+ </slots.popover>
+);
+```
+
+_**DOM**_
+
+```html
+<button type="button" class="fui-Button fui-InfoButton__button">
+ <!-- icon -->
+</button>
+
+<!-- on document.body -->
+<div role="tooltip" class="fui-PopoverSurface fui-InfoButton__content">
+ Popover above-start lorem ipsum dolor sit amet consectetur.
+ <a href="https://react.fluentui.dev">Learn more</a>
+</div>
+```
 
 ## Migration
 
-_Describe what will need to be done to upgrade from the existing implementations:_
-
-- _Migration from v8_
-- _Migration from v0_
+There's no migration guide as `v0` and `v8` do not have an InfoButton component.
 
 ## Behaviors
 
-_Explain how the component will behave in use, including:_
+> Note: The behavior will change when used in conjunction with the `Field` component. It is mentioned that when a form has many InfoButtons, it may be better to not make a full tab stop in the button. The idea is to have each field have a "shortcut" that will let you focus on the infobutton. This will be implemented by Field if needed.
 
 - _Component States_
+ - Popover open: The Popover is open and content visible.
 - _Interaction_
  - _Keyboard_
+ - `Enter` or `Space` key: Opens the Popover.
+ - Focusable items in Popover: Item should trap focus within the Popover.
+ - No focusable items in Popover: Focus should stay on the button.
+ - `Escape` key: Closes the Popover.
  - _Cursor_
+ - `Click`: Opens the Popover.
+ - `Click` outside of Popover: Closes the Popover.
  - _Touch_
+ - `Tap`: Opens the Popover.
+ - `Tap` outside of Popover: Closes the Popover.
  - _Screen readers_
+ - When screen reader is on the button, it should announce that it is a button, that it can be used to open a Popover, and read out the aria-label of the button.
+ - When screen reader is on the Popover, it should announce that it is a dialog, and read out the content of the Popover.
 
 ## Accessibility
 
-Base accessibility information is included in the design document. After the spec is filled and review, outcomes from it need to be communicated to design and incorporated in the design document.
-
-- Decide whether to use **native element** or folow **ARIA** and provide reasons
-- Identify the **[ARIA](https://www.w3.org/TR/wai-aria-practices-1.2/) pattern** and, if the component is listed there, follow its specification as possible.
-- Identify accessibility **variants**, the `role` ([ARIA roles](https://www.w3.org/TR/wai-aria-1.1/#role_definitions)) of the component, its `slots` and `aria-*` props.
-- Describe the **keyboard navigation**: Tab Oder and Arrow Key Navigation. Describe any other keyboard **shortcuts** used
-- Specify texts for **state change announcements** - [ARIA live regions
- ](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Live_Regions) (number of available items in dropdown, error messages, confirmations, ...)
-- Identify UI parts that appear on **hover or focus** and specify keyboard and screen reader interaction with them
-- List cases when **focus** needs to be **trapped** in sections of the UI (for dialogs and popups or for hierarchical navigation)
-- List cases when **focus** needs to be **moved programatically** (if parts of the UI are appearing/disappearing or other cases)
+- `role="tooltip"` is used on the PopoverSurface.
+- Tab order
+ - When tabbing through the page, the button should be a tab stop.
+ - When focused on the button, pressing `Enter` or `Space` should open the Popover.
+ - If the popover does not contain any focusable items, focus should stay on the button.
+ - When focused on the button, pressing `Escape` should close the Popover.
+ - When the Popover is open and it has focusable items, tabbing should move to the next focusable item.
+ - When focused on an item inside the Popover, pressing `Escape` should close the Popover and return to the button.