feat(tooltip): documentation, consumer migration guide

1st-gen/packages/tooltip/test/tooltip.test.ts

@@ -271,7 +271,7 @@ describe('Tooltip', () => {
       consoleWarnStub.restore();
     });
 
-    it('warns when incorrectly using `self-managed`', async () => {
+    it('warns when using the deprecated `self-managed` attribute', async () => {
       const el = await fixture<Tooltip>(html`
         <sp-tooltip variant="negative" self-managed>Help text.</sp-tooltip>
       `);
@@ -281,8 +281,8 @@ describe('Tooltip', () => {
       expect(consoleWarnStub.called).to.be.true;
       const spyCall = consoleWarnStub.getCall(0);
       expect(
-        (spyCall.args[0] as string).includes('Self-managed'),
-        'confirm dev warning message includes `Self-managed`'
+        (spyCall.args[0] as string).includes('self-managed'),
+        'confirm dev warning message includes `self-managed`'
       ).to.be.true;
       expect(
         spyCall.args[spyCall.args.length - 1],
@@ -291,7 +291,7 @@ describe('Tooltip', () => {
         data: {
           localName: 'sp-tooltip',
           type: 'api',
-          level: 'high',
+          level: 'deprecation',
         },
       });
     });

2nd-gen/packages/core/components/tooltip/Tooltip.base.ts

@@ -63,7 +63,7 @@ export abstract class TooltipBase extends SpectrumElement {
 
   /**
    * The preferred placement of the tooltip relative to its trigger.
-   * Applies a CSS class for tip direction; pixel positioning requires `PlacementController` (additive phase).
+   * Controls the tip direction via the reflected `placement` attribute; pixel positioning requires `PlacementController` (additive phase).
    *
    * @default 'top'
    */
@@ -81,15 +81,15 @@ export abstract class TooltipBase extends SpectrumElement {
   /**
    * The `id` of the trigger element in the same document tree root.
    * Resolved via `getRootNode().getElementById(this.for)`.
-   * Active from the initial release; drives ARIA relationship wiring on `open` change.
+   * Drives ARIA relationship wiring on `open` change.
    */
   @property({ attribute: 'for', type: String })
   public for: string | undefined;
 
   /**
    * Explicit trigger element reference. Overrides `for` when set.
    * Use for cross-shadow-root triggers or programmatic insertion where `getElementById` is scoped to the wrong root.
-   * Setter only — no HTML attribute.
+   * Setter only; no HTML attribute.
    *
    * @default null
    */
@@ -99,8 +99,8 @@ export abstract class TooltipBase extends SpectrumElement {
   /**
    * Duration in milliseconds of the warm-up delay before the tooltip shows on pointer hover.
    * Set to `0` to show immediately on hover. Keyboard focus (`focusin` when `:focus-visible`)
-   * always shows the tooltip immediately regardless of this value. The cooldown duration (before the next hover must wait again)
-   * matches this value. Warm-up/cooldown state is shared across all tooltips in the same document,
+   * always shows the tooltip immediately regardless of this value. The cooldown duration after the
+   * pointer leaves the trigger matches this value. Warm-up/cooldown state is shared across all tooltips in the same document,
    * so moving quickly between adjacent triggers (e.g. a toolbar) shows each subsequent tooltip
    * immediately after the first warm-up elapses.
    *
@@ -248,6 +248,13 @@ export abstract class TooltipBase extends SpectrumElement {
     this.dispatchAfterEvent(this.open);
   };
 
+  // Allows Escape behavior to be testable, does not interfere with native popover dismissal
+  private readonly handleKeyDown = (event: KeyboardEvent): void => {
+    if (event.key === 'Escape' && this.open) {
+      this.open = false;
+    }
+  };
+
   protected override updated(changedProperties: PropertyValues): void {
     super.updated(changedProperties);
     if (changedProperties.has('open')) {
@@ -269,12 +276,14 @@ export abstract class TooltipBase extends SpectrumElement {
     this.addEventListener('beforetoggle', this.handleBeforeToggle);
     this.addEventListener('toggle', this.handleToggle);
     this.addEventListener('transitionend', this.handleTransitionEnd);
+    document.addEventListener('keydown', this.handleKeyDown);
   }
 
   public override disconnectedCallback(): void {
     super.disconnectedCallback();
     this.removeEventListener('beforetoggle', this.handleBeforeToggle);
     this.removeEventListener('toggle', this.handleToggle);
     this.removeEventListener('transitionend', this.handleTransitionEnd);
+    document.removeEventListener('keydown', this.handleKeyDown);
   }
 }

2nd-gen/packages/swc/.storybook/preview-head.html

@@ -116,7 +116,25 @@
     }
 
     h4 {
-      font-size: var(--swc-heading-size-s) !important;
+      font-size: var(--swc-heading-size-xs) !important;
+    }
+
+    kbd {
+      line-height: 1;
+      margin: 0px 2px;
+      padding: 3px 5px;
+      white-space: nowrap;
+      border-radius: 3px;
+      font-size: 12px;
+      border: 1px solid rgb(147, 158, 172);
+      border-inline-end-width: 2px;
+      border-block-end-width: 2px;
+      color: rgba(46, 51, 56, 0.9);
+      background-color: rgb(246, 249, 252);
+      font-family:
+        ui-monospace, Menlo, Monaco, 'Roboto Mono', 'Oxygen Mono',
+        'Ubuntu Monospace', 'Source Code Pro', 'Droid Sans Mono', 'Courier New',
+        monospace !important;
     }
 
     :is(html, p, li, ul, ol) {

2nd-gen/packages/swc/.storybook/preview.ts

@@ -248,6 +248,7 @@ const preview = {
               'Tools vs packages',
               'Writing migration guides',
               'Focus management',
+              'Changelog strategy',
             ],
             'Style guide',
             [
@@ -390,6 +391,11 @@ const preview = {
                 ['Rendering and styling migration analysis'],
                 'Field label',
                 ['Rendering and styling migration analysis'],
+                'Grid',
+                [
+                  'Accessibility migration analysis',
+                  'Rendering and styling migration analysis',
+                ],
                 'Help text',
                 ['Rendering and styling migration analysis'],
                 'Illustrated message',
@@ -436,6 +442,7 @@ const preview = {
                 'Popover',
                 [
                   'Accessibility migration analysis',
+                  'Migration plan',
                   'Rendering and styling migration analysis',
                 ],
                 'Progress bar',

2nd-gen/packages/swc/components/tooltip/Tooltip.ts

@@ -27,7 +27,12 @@ import styles from './tooltip.css';
  *
  * @slot - Text label displayed in the tooltip.
  *
- * @cssprop --swc-tooltip-background-color - Background color of the tooltip bubble. Defaults to the neutral background color token.
+ * @cssprop --swc-tooltip-background-color - Background color of the tooltip bubble. Overrides the variant-specific background color.
+ *
+ * @fires swc-open - Dispatched when the tooltip begins to open, before the transition plays.
+ * @fires swc-close - Dispatched when the tooltip begins to close, before the transition plays.
+ * @fires swc-after-open - Dispatched after the tooltip finishes opening, once the transition completes.
+ * @fires swc-after-close - Dispatched after the tooltip finishes closing, once the transition completes.
  */
 export class Tooltip extends TooltipBase {
   // ──────────────────────────────