-
Notifications
You must be signed in to change notification settings - Fork 249
feat(tooltip): documentation, consumer migration guide #6345
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
+515
−52
Merged
Changes from all commits
Commits
Show all changes
17 commits
Select commit
Hold shift + click to select a range
89b00b7
feat(tooltip): add tests
5t3ph 7a97f7b
feat(tooltip): code conformance
5t3ph d8ed6a6
feat(tooltip): documentation
5t3ph 0722db7
feat(tooltip): add consumer migration guide
5t3ph b65ae53
feat(tooltip): enable event tracking in Actions panel; test for all e…
5t3ph 5518081
fix(tooltip): resolve test timeout
5t3ph 2460440
fix(tooltip): fix 1st-gen warning test for self-managed
5t3ph a9bb9e7
Merge branch 'seckles/tooltip-code-styles-tests' of https://github.co…
5t3ph c121f1d
fix(tooltip): remove reference to console.log
5t3ph c6bbb27
feat(tooltip): support `labeling` attribute
5t3ph 92cdaa9
feat(tooltip): update migration plan for `labeling`
5t3ph 81e099d
fix(tooltip): update Button type cast
5t3ph 4d28886
feat(tooltip): harden `transitionDuration` check
5t3ph 3dc9c3f
fix(tooltip): add aria-label due to axe-core limitation
5t3ph 9f73308
Merge branch 'seckles/tooltip-code-styles-tests' of https://github.co…
5t3ph ba73d86
feat(tooltip): add `labeling` into a11y story
5t3ph cb82664
Merge branch 'swc-2017/tooltip' of https://github.com/adobe/spectrum-…
5t3ph File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
283 changes: 283 additions & 0 deletions
283
2nd-gen/packages/swc/components/tooltip/migration-guide.mdx
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,283 @@ | ||
| import { Meta } from '@storybook/addon-docs/blocks'; | ||
|
|
||
| <Meta title="Tooltip/Migration guide" /> | ||
|
|
||
| # Tooltip migration guide | ||
|
|
||
| Replace `<sp-tooltip>` with `<swc-tooltip>`, update the import, rename the tag, update event listeners, and change the authoring pattern so the tooltip is a sibling of the trigger rather than nested inside it. | ||
|
|
||
| <div | ||
| style={{ | ||
| borderLeft: '4px solid #2680eb', | ||
| background: 'rgba(38, 128, 235, 0.10)', | ||
| padding: '12px 16px', | ||
| margin: '16px 0', | ||
| borderRadius: '4px', | ||
| }} | ||
| > | ||
| <strong>ℹ️ Initial release scope.</strong> This release delivers the tag | ||
| rename, variant and event API changes, ARIA relationship wiring via{' '} | ||
| <code>for</code>, and native <code>{'popover="auto"'}</code> open/close | ||
| behavior.{' '} | ||
| <strong> | ||
| Automatic hover/focus trigger wiring and viewport-aware pixel positioning | ||
| are not yet available. | ||
| </strong>{' '} | ||
| They require <code>HoverController</code> and <code>PlacementController</code> | ||
| , which ship in a future release. Until then, control visibility via the{' '} | ||
| <code>open</code> property and position the tooltip with a helper library like | ||
| Floating UI. | ||
| </div> | ||
|
|
||
| ## Installation | ||
|
|
||
| ```bash | ||
| # Remove | ||
| yarn remove @spectrum-web-components/tooltip | ||
|
|
||
| # Add | ||
| yarn add @adobe/spectrum-wc | ||
| ``` | ||
|
|
||
| Update your import: | ||
|
|
||
| ```js | ||
| // Before | ||
| import '@spectrum-web-components/tooltip/sp-tooltip.js'; | ||
|
|
||
| // After | ||
| import '@adobe/spectrum-wc/components/tooltip/swc-tooltip.js'; | ||
| ``` | ||
|
|
||
| > `@adobe/spectrum-wc` is a monolithic package. Importing via subpath (e.g. `@adobe/spectrum-wc/components/tooltip/swc-tooltip.js`) registers and loads only that component's bundle. | ||
|
|
||
| ## What changed | ||
|
|
||
| ### Renamed | ||
|
|
||
| | Area | Spectrum 1 (`sp-tooltip`) | Spectrum 2 (`swc-tooltip`) | | ||
| | ------------------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------ | | ||
| | Tag | `sp-tooltip` | `swc-tooltip` | | ||
| | Import path | `@spectrum-web-components/tooltip/sp-tooltip.js` | `@adobe/spectrum-wc/components/tooltip/swc-tooltip.js` | | ||
| | `variant` | `'info'` | `'informative'` | | ||
| | `swc-open` / `swc-close` events | `sp-opened` / `sp-closed` | `swc-open`, `swc-after-open`, `swc-close`, `swc-after-close` | | ||
| | Trigger wiring attribute | `self-managed` | `for="[id]"` declares the trigger relationship and wires ARIA now. Automatic hover/focus open/close ships in a future release. | | ||
|
|
||
| ### Added in Spectrum 2 | ||
|
|
||
| | Addition | Notes | | ||
| | ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | ||
| | `for` attribute | Declares the trigger relationship by ID. Required for ARIA wiring and (in the additive phase) automatic hover/focus open/close. | | ||
| | `manual` boolean attribute | Opt out of automatic controller wiring; consumer manages open/close via the `open` property. ARIA wiring still fires on `open` change. | | ||
| | Logical placements: `start`, `end` | RTL-aware inline placement values; physical values (`top`, `bottom`, `left`, `right`) are unchanged. | | ||
| | `delay` attribute | Warm-up/cooldown duration in ms (default 1500). `delay="0"` shows immediately. **Additive phase:** active when `HoverController` ships. | | ||
| | `labeling` boolean attribute | Switches ARIA wiring to `ariaLabelledByElements` for icon-only triggers. **Additive phase.** | | ||
| | `swc-after-open` / `swc-after-close` events | Fire after the open/close transition completes. | | ||
|
|
||
| ### Removed in Spectrum 2 | ||
|
|
||
| | Removed | Replacement | | ||
| | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | | ||
| | `slot="icon"` | No replacement. Remove all icon content from tooltips; Spectrum 2 tooltip is text-only. | | ||
| | `variant="positive"` | Use `variant="informative"`, `variant="neutral"`, or `variant="negative"` as content warrants. | | ||
| | `variant="info"` | Renamed to `variant="informative"`. | | ||
| | `self-managed` attribute | Removed. Automatic trigger wiring is the default. Add `for="[id]"` to the tooltip pointing to the trigger's `id`. | | ||
| | `sp-opened` / `sp-closed` events | Replace with `swc-open` and `swc-close`. The timing also changes; see [step 4](#4-update-event-listeners). | | ||
| | `--mod-tooltip-*` CSS custom properties | No `--mod-*` pass-through in Spectrum 2. See [Styling](#styling). | | ||
|
|
||
| ## Update your code | ||
|
|
||
| ### 1. Update the import | ||
|
|
||
| ```js | ||
| // Before | ||
| import '@spectrum-web-components/tooltip/sp-tooltip.js'; | ||
|
|
||
| // After | ||
| import '@adobe/spectrum-wc/components/tooltip/swc-tooltip.js'; | ||
| ``` | ||
|
|
||
| ### 2. Rename the tag and fix variant values | ||
|
|
||
| ```html | ||
| <!-- Before --> | ||
| <sp-tooltip variant="info">Save your changes</sp-tooltip> | ||
| <sp-tooltip variant="positive">Upload complete</sp-tooltip> | ||
| <sp-tooltip>No changes yet</sp-tooltip> | ||
|
|
||
| <!-- After --> | ||
| <swc-tooltip variant="informative">Save your changes</swc-tooltip> | ||
| <!-- positive has no direct equivalent; choose based on content meaning --> | ||
| <swc-tooltip variant="informative">Upload complete</swc-tooltip> | ||
| <swc-tooltip>No changes yet</swc-tooltip> | ||
| ``` | ||
|
|
||
| ### 3. Remove icon slot content | ||
|
|
||
| Spectrum 2 tooltip does not render icons. Remove all `slot="icon"` content. | ||
|
|
||
| ```html | ||
| <!-- Before --> | ||
| <sp-tooltip variant="info"> | ||
| <sp-icon-info slot="icon"></sp-icon-info> | ||
| Learn more | ||
| </sp-tooltip> | ||
|
|
||
| <!-- After --> | ||
| <swc-tooltip variant="informative">Learn more</swc-tooltip> | ||
| ``` | ||
|
|
||
| ### 4. Update event listeners | ||
|
|
||
| Replace `sp-opened`/`sp-closed` with `swc-open` and `swc-close`. Use `swc-after-open` and `swc-after-close` when you need to act after the open or close transition completes. | ||
|
|
||
| **Timing change:** In Spectrum 1, events fired from the internal overlay bridge. In Spectrum 2, they fire from native `popover` lifecycle hooks (`beforetoggle` / `transitionend`). Code that depended on the exact timing relative to DOM paint or transition frames may need adjustment. | ||
|
|
||
| ```js | ||
| // Before | ||
| tooltip.addEventListener('sp-opened', handleOpen); | ||
| tooltip.addEventListener('sp-closed', handleClose); | ||
|
|
||
| // After | ||
| tooltip.addEventListener('swc-open', handleOpen); // fires before transition | ||
| tooltip.addEventListener('swc-after-open', handleOpen); // fires after transition completes | ||
| tooltip.addEventListener('swc-close', handleClose); | ||
| tooltip.addEventListener('swc-after-close', handleClose); | ||
| ``` | ||
|
|
||
| ### 5. Change the authoring pattern | ||
|
|
||
| In Spectrum 1, `<sp-tooltip>` was typically nested inside the trigger and required the `self-managed` attribute. In Spectrum 2, the tooltip is authored as a **sibling** of the trigger. Add an `id` to the trigger element and a `for` attribute on the tooltip referencing that `id`. | ||
|
|
||
| ```html | ||
| <!-- Before (Spectrum 1 pattern: tooltip nested inside trigger, self-managed) --> | ||
| <sp-action-button> | ||
| Save | ||
| <sp-tooltip self-managed placement="top">Save your changes</sp-tooltip> | ||
| </sp-action-button> | ||
|
|
||
| <!-- After (Spectrum 2 pattern: tooltip is a sibling; id + for wire the relationship) --> | ||
| <swc-action-button id="save-btn">Save</swc-action-button> | ||
| <swc-tooltip for="save-btn" placement="top">Save your changes</swc-tooltip> | ||
| ``` | ||
|
|
||
| The tooltip may be placed anywhere in the same document tree root; it does not need to be immediately adjacent to the trigger. | ||
|
|
||
| **For cross-shadow-root triggers** where `getElementById` cannot reach the trigger, set the `triggerElement` property directly instead of using `for`: | ||
|
|
||
| ```js | ||
| const tooltip = document.querySelector('#my-tip'); | ||
| tooltip.triggerElement = shadowRoot.querySelector('#the-trigger'); | ||
| ``` | ||
|
|
||
| <div | ||
| style={{ | ||
| borderLeft: '4px solid #2680eb', | ||
| background: 'rgba(38, 128, 235, 0.10)', | ||
| padding: '12px 16px', | ||
| margin: '16px 0', | ||
| borderRadius: '4px', | ||
| }} | ||
| > | ||
| <strong> | ||
| ℹ️ What <code>for</code> does in this release. | ||
| </strong>{' '} | ||
| Setting <code>{'for="[id]"'}</code> establishes the ARIA relationship between | ||
| the trigger and tooltip. It does <strong>not</strong> yet open or close the | ||
| tooltip automatically on hover or focus. Until automatic trigger wiring ships, | ||
| you must control visibility manually (see step 6 below). | ||
| </div> | ||
|
|
||
| ### 6. Manage open/close until automatic wiring ships | ||
|
|
||
| In this release, automatic hover/focus open/close is not active. Implement `mouseenter`/`mouseleave` and `focusin`/`focusout` listeners yourself. Keep `for` set so the ARIA relationship is always established when the tooltip opens. | ||
|
|
||
| When automatic wiring ships in a future release, remove these manual listeners; `for` will drive open/close automatically. Add `manual` to the tooltip only when you need to permanently opt out of automatic wiring at that point. | ||
|
|
||
| ```html | ||
| <!-- After (current release: manual event wiring required) --> | ||
| <button id="save-btn">Save</button> | ||
| <swc-tooltip for="save-btn" placement="top" id="save-tip"> | ||
| Save your changes | ||
| </swc-tooltip> | ||
| <script> | ||
| const btn = document.querySelector('#save-btn'); | ||
| const tip = document.querySelector('#save-tip'); | ||
| btn.addEventListener('mouseenter', () => { | ||
| tip.open = true; | ||
| }); | ||
| btn.addEventListener('mouseleave', () => { | ||
| tip.open = false; | ||
| }); | ||
| btn.addEventListener('focusin', () => { | ||
| tip.open = true; | ||
| }); | ||
| btn.addEventListener('focusout', () => { | ||
| tip.open = false; | ||
| }); | ||
| </script> | ||
| ``` | ||
|
|
||
| ## Accessibility | ||
|
|
||
| - **Trigger relationship:** Set `for="[trigger-id]"` on every `<swc-tooltip>`. Without it, the ARIA relationship between the tooltip and its trigger is not established, and screen readers will not associate the tooltip text with the trigger. See [step 5](#5-change-the-authoring-pattern). | ||
| - **Icon-only triggers:** Add `accessible-label` to the trigger (2nd-gen SWC components) or `aria-label` (native elements) so the trigger has an accessible name independent of the tooltip. The tooltip describes; it does not name. See [step 5](#5-change-the-authoring-pattern). | ||
| - **No interactive content in tooltips:** `role="tooltip"` prohibits interactive elements (links, buttons, inputs) inside the tooltip. Refactor those patterns to `<swc-popover>` or a dialog component. | ||
| - **Non-interactive triggers:** Tooltips must be attached to focusable elements. Static text, decorative icons, and non-interactive elements are not valid tooltip triggers; use contextual help instead. | ||
| - **Touch and mobile:** `<swc-tooltip>` is hover/focus only. For touch-accessible disclosure, use `<swc-popover>` or contextual help. | ||
| - **`popover="auto"` auto-stack change:** Opening a `<swc-tooltip>` closes other open `auto` popovers (menus, pickers). This differs from the Spectrum 1 `type="hint"` isolation behavior, which left menus and pickers open. This is expected behavior, not a bug. | ||
|
|
||
| ## Styling | ||
|
|
||
| Spectrum 1 `--mod-tooltip-*` CSS custom properties are **not** supported in Spectrum 2. Spectrum 2 exposes one public custom property. | ||
|
|
||
| {/* @todo Replace the inline-styled callouts in this section with `<swc-inline-alert>` once it is migrated to Spectrum 2. */} | ||
|
|
||
| <div | ||
| style={{ | ||
| borderLeft: '4px solid #dba842', | ||
| background: 'rgba(219, 168, 66, 0.12)', | ||
| padding: '12px 16px', | ||
| margin: '16px 0', | ||
| borderRadius: '4px', | ||
| }} | ||
| > | ||
| <strong>⚠️ Breaking change.</strong> Spectrum 1{' '} | ||
| <code>{'--mod-tooltip-*'}</code> properties <strong>do not apply</strong> to{' '} | ||
| <code>{'<swc-tooltip>'}</code>. Remove every <code>{'--mod-tooltip-*'}</code>{' '} | ||
| override. The only public custom property in Spectrum 2 is listed below. | ||
| </div> | ||
|
|
||
| {/* @todo Replace the Description column with the `@cssproperty` JSDoc descriptions from `<swc-tooltip>`'s CEM entry once they are added in a follow-up PR. */} | ||
|
|
||
| | Custom property | Description | | ||
| | -------------------------------- | ---------------------------------------------------------------------------------------- | | ||
| | `--swc-tooltip-background-color` | Background color of the tooltip bubble. Overrides the variant-specific background color. | | ||
|
|
||
| <div | ||
| style={{ | ||
| borderLeft: '4px solid #e34850', | ||
| background: 'rgba(227, 72, 80, 0.10)', | ||
| padding: '12px 16px', | ||
| margin: '16px 0', | ||
| borderRadius: '4px', | ||
| }} | ||
| > | ||
| <strong>🚫 Do not target internals.</strong> Internal classes,{' '} | ||
| <code>{'--_swc-tooltip-*'}</code> private properties, and shadow DOM are{' '} | ||
| <strong>not public API</strong>. Styling applied to them will break without | ||
| warning on minor releases. | ||
| </div> | ||
|
|
||
| ## Checklist | ||
|
|
||
| - [ ] Update imports from `@spectrum-web-components/tooltip` to `@adobe/spectrum-wc` | ||
| - [ ] Rename all `<sp-tooltip>` to `<swc-tooltip>` | ||
| - [ ] Replace `variant="info"` with `variant="informative"` | ||
| - [ ] Replace `variant="positive"` with `variant="informative"`, `variant="neutral"`, or `variant="negative"` as appropriate | ||
| - [ ] Remove all `slot="icon"` content from tooltips | ||
| - [ ] Replace `sp-opened`/`sp-closed` event listeners with `swc-open`/`swc-close` (and `swc-after-open`/`swc-after-close` where needed) | ||
| - [ ] Remove `self-managed` from all tooltips; add `id` to the trigger and `for="[id]"` to the tooltip | ||
| - [ ] Confirm no tooltip is nested inside its trigger element | ||
| - [ ] Add `mouseenter`/`mouseleave` and `focusin`/`focusout` listeners to control `open` until automatic wiring ships | ||
| - [ ] Remove all `--mod-tooltip-*` CSS overrides |
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This is nice, but I feel like our whole SB customization needs some love 😛 cc: @caseyisonit