From 4632d79046e86a9efec1a938dab44284ac1de51f Mon Sep 17 00:00:00 2001 From: aidendk <103057880+aidendk@users.noreply.github.com> Date: Thu, 16 Jun 2022 14:34:09 -0500 Subject: [PATCH] Spec for nimble-tooltip (#595) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit # Pull Request ## 🤨 Rationale Completed spec for nimble-tooltip (#309) ## ✅ Checklist - [x] I have updated the project documentation to reflect my changes or determined no changes are needed. --- ...-f1b0b2b1-f154-4ace-9825-91316a7e941e.json | 7 ++ .../src/tooltip/tooltip.spec.md | 85 +++++++++++++++++++ 2 files changed, 92 insertions(+) create mode 100644 change/@ni-nimble-components-f1b0b2b1-f154-4ace-9825-91316a7e941e.json create mode 100644 packages/nimble-components/src/tooltip/tooltip.spec.md diff --git a/change/@ni-nimble-components-f1b0b2b1-f154-4ace-9825-91316a7e941e.json b/change/@ni-nimble-components-f1b0b2b1-f154-4ace-9825-91316a7e941e.json new file mode 100644 index 0000000000..d1e55e304f --- /dev/null +++ b/change/@ni-nimble-components-f1b0b2b1-f154-4ace-9825-91316a7e941e.json @@ -0,0 +1,7 @@ +{ + "type": "none", + "comment": "tooltip spec (#309)", + "packageName": "@ni/nimble-components", + "email": "103057880+aidendk@users.noreply.github.com", + "dependentChangeType": "none" +} diff --git a/packages/nimble-components/src/tooltip/tooltip.spec.md b/packages/nimble-components/src/tooltip/tooltip.spec.md new file mode 100644 index 0000000000..1cafdad6ee --- /dev/null +++ b/packages/nimble-components/src/tooltip/tooltip.spec.md @@ -0,0 +1,85 @@ +# Nimble Tooltip + +## Overview + +The `nimble-tooltip` is a popup that displays information related to an element when the element receives keyboard focus or the mouse hovers over it. It typically appears after a small delay and disappears when Escape is pressed or on mouse out. The Nimble tooltip is based upon [FAST's tooltip component](https://github.com/microsoft/fast/tree/master/packages/web-components/fast-foundation/src/tooltip) + +The nimble-tooltip project will first be implemented as a prototype, open issues listed below will be addressed once the prototype is functional. + +### Background + +[Nimble issue #309: Tooltip](https://github.com/ni/nimble/issues/309) + +[Visual desgin spec](https://xd.adobe.com/view/8ce280ab-1559-4961-945c-182955c7780b-d9b1/screen/044414d7-1714-40f2-9679-2ce2c8202d1c/specs/) + +--- + +## Design + +### API + +[FAST tooltip API](https://github.com/microsoft/fast/blob/de7f234ef871204fcac2b5df59433d919809341d/packages/web-components/fast-foundation/src/tooltip/tooltip.spec.md) + +Plan to extend API to support all cases shown in visual design XD document. Will add +once tooltip is sucessfully implemented with one case. + +Plan to first implement the tooltip and let the client choose which type of tooltip (general, error, info) they want +Additional changes to API expected in the future, but will not be included in first pass of implementation. Listed in Future Improvements and Open Issues + +- _Component Name:_ `nimble-tooltip` +- _Properties/Attributes:_ Unchanged +- _Methods:_ Unchanged +- _Events:_ Unchanged +- _CSS Classes and Custom Properties that affect the component:_ None +- _Slots:_ Unchanged +- _Template:_ Unchanged + +### Future Improvements + +Attribute for switching between error and info states of tooltip +Easier integration with other nimble components + +### Angular integration + +An Angular directive will be created for the component. The component will not have form association, so a `ControlValueAccessor` will not be created. + +### Blazor integration + +A Blazor wrapper will be created for the component. + +### Additional requirements + +- _User interaction: Do the FAST component's behaviors match the visual design spec? When they differ, which approach is preferable and why?_ + - No additional requirements +- _Styling: Does FAST provide APIs to achieve the styling in the visual design spec?_ + - FAST API most likely won't be sufficient for creating extra states in spec, will be adressed later on. +- _Testing: Is FAST's coverage sufficient? Should we write any tests beyond Chromatic visual tests?_ + - Will look at options as building, testing may be difficult because only displayed on hover. +- _Documentation: Any requirements besides standard Storybook docs and updating the Example Client App demo?_ + - No additional requirements +- _Tooling: Any new tools, updates to tools, code generation, etc?_ + - No additional requirements +- _Accessibility: keyboard navigation/focus, form input, use with assistive technology, etc._ + - Aria-describedBy recommendation in storybook docs for tooltip for developers +- _Globalization: special RTL handling, swapping of icons/visuals, localization, etc._ + - No additional requirements +- _Performance: does the FAST component meet Nimble's performance requirements?_ + - No additional requirements +- _Security: Any requirements for security?_ + - No additional requirements + +--- + +## Open Issues + +When user is using nimble tooltip and nimble components, is there an easier way to add a tooltip so they wouldn't have to anchor to an html element every time they want a tooltip? + +- Update nimble controls to have tooltip show and be tooltip aware +- Create a tooltip in the shadow dom internally, would not require a separate tooltip element. +- If we don't do anything, at least provide an easy way to create unique ids. + +Can tooltip be found by screen reader? + +For testing, can we force the tooltip to be visible without hover? [Possible Ideas](https://stackoverflow.com/questions/62043424/mock-hover-state-in-storybook) + +Mobile tooltip is not very functional- have to click on button to show tooltip, and clicking away does not make it disappear