@justeattakeaway/pie-tooltip 0.2.0 → 0.3.0

package/README.md

@@ -35,11 +35,11 @@ Ideally, you should install the component using the **`@justeattakeaway/pie-webc
 
 ### Controlled component
 
-`pie-tooltip` is a controlled component. It never writes to its own `isOpen`.
+`pie-tooltip` is a controlled component. It never writes to its own `isOpen`, and it never opens or closes itself.
 
 1. You own `isOpen`.
-2. You listen for `pie-tooltip-close`.
-3. You pass the value back.
+2. You listen for `pie-tooltip-open` and `pie-tooltip-close`.
+3. You pass the value back to open/close the tooltip.
 
 ### Properties
 
@@ -55,6 +55,7 @@ Ideally, you should install the component using the **`@justeattakeaway/pie-webc
 | `heading` | Any string | The text to display in the panel's heading. In dialog mode this also provides the panel's accessible name. | `undefined` |
 | `headingLevel` | `h2`, `h3`, `h4`, `h5`, `h6` | The HTML heading tag to use for the panel's heading. | `h2` |
 | `aria` | `{ close?: string, label?: string }` | `close` names the close button. `label` names the panel in dialog mode when no `heading` is provided. | `undefined` |
+| `triggers` | Array of `hover`, `focus`, `click` | Which interactions request that the panel opens and closes. A configured interaction emits an event; it never changes the panel's state on its own. Empty by default, so no interaction is watched at all. Configure `hover` and `focus` together for keyboard reachability. | `[]` |
 
 ### Slots
 
@@ -67,7 +68,8 @@ Ideally, you should install the component using the **`@justeattakeaway/pie-webc
 
 | Event | Type | Description |
 |---|---|---|
-| `pie-tooltip-close` | `Event` | Emitted when the close button is clicked. Set `isOpen` to `false` in response. Bubbles and is composed. |
+| `pie-tooltip-open` | `Event` | Emitted when a configured trigger asks for the panel. Set `isOpen` to `true` in response. Bubbles and is composed. |
+| `pie-tooltip-close` | `Event` | Emitted when the close button is clicked, or when a configured trigger asks to dismiss the panel. Set `isOpen` to `false` in response. Bubbles and is composed. |
 
 ### CSS Variables
 
@@ -84,7 +86,7 @@ Set both on the `pie-tooltip` element itself.
 
 ## Positioning
 
-The component projects itself over the trigger's box and places the panel against that box in CSS. The trigger is found by `id`, so `pie-tooltip` can sit anywhere in the DOM, but reading and tab order follow DOM order, so place it immediately after its trigger.
+Place the tooltip next to its trigger element in the DOM for the best accessibility practice. The `position` element will place the tooltip near to the trigger based on which value is provided.
 
 `position` names a side and, optionally, an alignment along the opposite axis:
 
@@ -95,7 +97,7 @@ left     left-start     left-end
 right    right-start    right-end
 ```
 
-In right-to-left languages, everything on the inline axis mirrors. The alignments follow the reading direction, so `top-start` aligns against the right-hand edge, and `left` and `right` swap: a panel asked for on the left appears on the right. The `-start` and `-end` alignments of `left` and `right` are on the block axis, which has no direction to mirror, so only the side moves. None of this needs configuration or any JavaScript awareness of direction.
+In right-to-left languages, everything on the inline axis mirrors. The alignments follow the reading direction, so `top-start` aligns against the right-hand edge, and `left` and `right` swap: a panel asked for on the left appears on the right. The `-start` and `-end` alignments of `left` and `right` are on the block axis, which has no direction to mirror, so only the side moves.
 
 ## Sizing
 
@@ -131,8 +133,12 @@ A close button does not make the panel a dialog. Only the `action` slot does.
 - Keeps the panel clear of the trigger at every placement, so the panel cannot obscure a focused trigger (WCAG 2.4.11).
 - Wraps content.
 
+It does not touch the trigger, and it does not move focus. The component never writes attributes to the element named by `trigger`, and never calls `focus()` on anything. Both are yours to declare: see [Wiring the trigger](#wiring-the-trigger) and [Managing focus](#managing-focus).
+
 ### What you need to do
 
+- **Wire the trigger yourself.** The ARIA attributes that connect the trigger to the panel are yours to set. See [Wiring the trigger](#wiring-the-trigger) for what to set and when.
+- **Move focus yourself in dialog mode.** The panel holds focusable content, so opening it should move focus in and closing it should put focus back. See [Managing focus](#managing-focus).
 - **Give the trigger its own accessible name.** The tooltip is a description and never supplies a name. An icon-only trigger must set its own label; `pie-icon-button` already requires `aria.label`.
 - **Use a natively interactive element as the trigger**, a button or a link, so focus and click behave correctly.
 - **Own `isOpen`.** Listen for `pie-tooltip-close` and set `isOpen` to `false` in response.
@@ -142,6 +148,167 @@ A close button does not make the panel a dialog. Only the `action` slot does.
 - **Provide a translated `aria.close`** whenever `isDismissible` is set.
 - **Keep tooltip-mode content short and supplementary.** Anything essential or interactive belongs in dialog mode, or inline in the page.
 
+### Wiring the trigger
+
+The trigger lives outside the tooltip and the component leaves it untouched, so you declare the relationship. What to set depends on the mode.
+
+| ARIA | Set it when | Value |
+|---|---|---|
+| `haspopup` | Dialog mode, so the trigger announces that it opens a dialog | `dialog` |
+| `expanded` | You toggle the panel from the trigger with a click or a tap | Your `isOpen` value |
+| `describedby` | Tooltip mode, and the trigger is a plain HTML element | The `id` of the element you put in the `content` slot |
+
+Leave `expanded` off a hover-only or focus-only panel. Nothing is being toggled, so it has nothing to describe. There is no `controls` in the table because it adds nothing here: the description already carries the relationship, and support for it is patchy.
+
+#### A description cannot cross a shadow boundary
+
+`aria.describedby` takes an `id`, and an `id` only resolves inside the tree of the element that references it. The element you put in the `content` slot stays in your light DOM, so a plain `<button>` in the same document resolves it. The `<button>` inside `pie-icon-button` does not: it cannot see an `id` in your document, so `aria.describedby` is unusable for this purpose even though the property exists.
+
+There is no way around this from outside the component. When the trigger is a PIE component and the panel is a plain tooltip, put the information in the trigger's name with `aria.label` instead, as in the first example below. It is the only route that reaches a screen reader.
+
+Dialog mode is unaffected, because the panel is named by `heading` and needs no description at all.
+
+#### A tooltip panel on an icon trigger
+
+`hover` and `focus` together give the panel to both pointer and keyboard users. Nothing is toggled, so there is no `expanded`, and the name carries the content because a description cannot reach the button inside the trigger.
+
+```js
+// main.js
+import '@justeattakeaway/pie-webc/components/tooltip.js';
+import '@justeattakeaway/pie-webc/components/icon-button.js';
+import '@justeattakeaway/pie-icons-webc/dist/IconInfoCircle.js';
+
+const trigger = document.querySelector('#delivery-info');
+const panel = document.querySelector('#delivery-panel');
+
+trigger.aria = { label: 'Delivery times: orders placed before 6pm arrive today' };
+panel.triggers = ['hover', 'focus'];
+
+panel.addEventListener('pie-tooltip-open', () => { panel.isOpen = true; });
+panel.addEventListener('pie-tooltip-close', () => { panel.isOpen = false; });
+```
+
+```html
+<script type="module" src="/main.js"></script>
+
+<pie-icon-button id="delivery-info" variant="outline">
+  <icon-info-circle></icon-info-circle>
+</pie-icon-button>
+
+<pie-tooltip id="delivery-panel" trigger="delivery-info" type="icon">
+  <span slot="content">Orders placed before 6pm arrive today.</span>
+</pie-tooltip>
+```
+
+The two handlers are the whole contract. Without them the panel never opens, because the component only ever asks.
+
+#### A dialog panel toggled from the trigger
+
+Filling the `action` slot makes the panel a dialog, so the trigger gets `haspopup` and, because a click toggles it, `expanded`. Both track the same state you already own.
+
+```jsx
+import { useRef, useState } from 'react';
+import { PieButton } from '@justeattakeaway/pie-webc/react/button.js';
+import { PieIconButton } from '@justeattakeaway/pie-webc/react/icon-button.js';
+import { PieTooltip } from '@justeattakeaway/pie-webc/react/tooltip.js';
+import { IconInfoCircle } from '@justeattakeaway/pie-icons-webc/dist/react/IconInfoCircle.js';
+
+export function DeliveryTimes () {
+  const [isOpen, setIsOpen] = useState(false);
+  const triggerRef = useRef(null);
+  const actionRef = useRef(null);
+
+  const open = () => {
+    setIsOpen(true);
+    // The panel is only focusable once it has rendered and been positioned.
+    requestAnimationFrame(() => actionRef.current?.focus({ preventScroll: true }));
+  };
+
+  const close = () => {
+    // Only reclaim focus if it is still inside the panel. Closing on a hover-away or a
+    // click elsewhere must not yank focus from whatever the user has moved on to.
+    const panelHadFocus = document.activeElement?.closest('pie-tooltip');
+
+    setIsOpen(false);
+
+    if (panelHadFocus) {
+      triggerRef.current?.focus({ preventScroll: true });
+    }
+  };
+
+  return (
+    <>
+      <PieIconButton
+        id="delivery-info"
+        ref={triggerRef}
+        variant="outline"
+        aria={{
+          label: 'Delivery times',
+          haspopup: 'dialog',
+          expanded: isOpen,
+        }}>
+        <IconInfoCircle />
+      </PieIconButton>
+
+      <PieTooltip
+        trigger="delivery-info"
+        heading="Delivery times"
+        isOpen={isOpen}
+        isDismissible
+        aria={{ close: 'Close' }}
+        triggers={['click']}
+        onPieTooltipOpen={open}
+        onPieTooltipClose={close}>
+        <span slot="content">Orders placed before 6pm arrive today.</span>
+        <PieButton slot="action" size="xsmall" ref={actionRef} onClick={close}>
+          Got it
+        </PieButton>
+      </PieTooltip>
+    </>
+  );
+}
+```
+
+`isDismissible` and Escape both route through `onPieTooltipClose`, so a single `close` covers the close button, Escape, a click outside and the action button.
+
+The `closest('pie-tooltip')` check works because `document.activeElement` reports the outermost shadow host, so focus on the close button inside the panel's shadow root reads as the `pie-tooltip` element itself. Focus on your slotted action button reports that button, whose `closest` finds the same panel. One check covers both. See [Managing focus](#managing-focus).
+
+#### Driving the panel without `triggers`
+
+Leave `triggers` unset when the panel's timing is not an interaction with its trigger, such as a step in an onboarding tour. Nothing is watched, so `pie-tooltip-open` never fires and `expanded` has nothing to describe. The close button still emits `pie-tooltip-close`.
+
+Escape is watched only while at least one trigger is configured, so a panel driven this way needs its own key handling if you want Escape to dismiss it.
+
+```html
+<template>
+  <pie-icon-button
+    id="delivery-info"
+    variant="outline"
+    :aria="{ label: 'Delivery times' }">
+    <icon-info-circle />
+  </pie-icon-button>
+
+  <pie-tooltip
+    trigger="delivery-info"
+    heading="Delivery times"
+    :isOpen="isOpen"
+    isDismissible
+    :aria="{ close: 'Close' }"
+    @pie-tooltip-close="isOpen = false">
+    <span slot="content">Orders placed before 6pm arrive today.</span>
+  </pie-tooltip>
+</template>
+```
+
+### Managing focus
+
+In tooltip mode there is nothing to do. A tooltip must not take focus, and the close button that `isDismissible` renders is reachable by tabbing.
+
+In dialog mode you own two moments:
+
+- **On open, move focus into the panel.** Wait for the panel to render and be positioned first, because a `visibility: hidden` element cannot take focus. `await panel.updateComplete` followed by one animation frame is enough.
+- **On close, put focus back**, but only if focus was still inside the panel. Closing on a hover-away or a click elsewhere must not pull focus away from whatever the user has moved on to.
+
 ## Usage Examples
 
 **For HTML:**
@@ -149,6 +316,10 @@ A close button does not make the panel a dialog. Only the `action` slot does.
 ```js
 // import as module into a js file e.g. main.js
 import '@justeattakeaway/pie-webc/components/tooltip.js'
+import '@justeattakeaway/pie-webc/components/button.js'
+
+// `aria` takes an object, so it is set as a property rather than an attribute.
+document.querySelector('#delivery-panel').aria = { close: 'Close' };
 ```
 
 ```html
@@ -160,7 +331,7 @@ import '@justeattakeaway/pie-webc/components/tooltip.js'
 ```html
 <pie-button id="delivery-info">Delivery times</pie-button>
 
-<pie-tooltip trigger="delivery-info" isOpen isDismissible>
+<pie-tooltip id="delivery-panel" trigger="delivery-info" isOpen isDismissible>
   <span slot="content">Orders placed before 6pm arrive today.</span>
 </pie-tooltip>
 ```
@@ -218,7 +389,19 @@ export function DeliveryTimes () {
 
 Filling the `action` slot switches the panel to a non-modal dialog, which then needs an accessible name.
 
+```js
+document.querySelector('#delivery-info').aria = {
+  label: 'Delivery times',
+  haspopup: 'dialog',
+  expanded: true,
+};
+```
+
 ```html
+<pie-icon-button id="delivery-info" variant="outline">
+  <icon-info-circle></icon-info-circle>
+</pie-icon-button>
+
 <pie-tooltip trigger="delivery-info" isOpen heading="Delivery times">
   <span slot="content">Orders placed before 6pm arrive today.</span>
   <pie-button slot="action" size="xsmall">Next</pie-button>

package/custom-elements.json

@@ -52,6 +52,14 @@
           },
           "default": "['h2', 'h3', 'h4', 'h5', 'h6']"
         },
+        {
+          "kind": "variable",
+          "name": "triggers",
+          "type": {
+            "text": "['hover', 'focus', 'click']"
+          },
+          "default": "['hover', 'focus', 'click']"
+        },
         {
           "kind": "variable",
           "name": "modes",
@@ -77,6 +85,11 @@
           },
           "default": "'c-tooltip'"
         },
+        {
+          "kind": "variable",
+          "name": "ON_TOOLTIP_OPEN_EVENT",
+          "default": "`${componentSelector}-open`"
+        },
         {
           "kind": "variable",
           "name": "ON_TOOLTIP_CLOSE_EVENT",
@@ -132,6 +145,14 @@
             "module": "src/defs.js"
           }
         },
+        {
+          "kind": "js",
+          "name": "triggers",
+          "declaration": {
+            "name": "triggers",
+            "module": "src/defs.js"
+          }
+        },
         {
           "kind": "js",
           "name": "modes",
@@ -156,6 +177,14 @@
             "module": "src/defs.js"
           }
         },
+        {
+          "kind": "js",
+          "name": "ON_TOOLTIP_OPEN_EVENT",
+          "declaration": {
+            "name": "ON_TOOLTIP_OPEN_EVENT",
+            "module": "src/defs.js"
+          }
+        },
         {
           "kind": "js",
           "name": "ON_TOOLTIP_CLOSE_EVENT",
@@ -262,6 +291,16 @@
               "privacy": "public",
               "attribute": "aria"
             },
+            {
+              "kind": "field",
+              "name": "triggers",
+              "type": {
+                "text": "TooltipProps['triggers']"
+              },
+              "privacy": "public",
+              "default": "[]",
+              "attribute": "triggers"
+            },
             {
               "kind": "field",
               "name": "_assignedActionElements",
@@ -295,6 +334,33 @@
               "privacy": "private",
               "default": "false"
             },
+            {
+              "kind": "field",
+              "name": "_isAnchorVisible",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "private",
+              "default": "true"
+            },
+            {
+              "kind": "field",
+              "name": "_clippedTriggerElement",
+              "type": {
+                "text": "Element | null"
+              },
+              "privacy": "private",
+              "default": "null"
+            },
+            {
+              "kind": "field",
+              "name": "_triggerClippers",
+              "type": {
+                "text": "Array<Element>"
+              },
+              "privacy": "private",
+              "default": "[]"
+            },
             {
               "kind": "field",
               "name": "_triggerTrackingController",
@@ -303,6 +369,14 @@
               },
               "privacy": "private"
             },
+            {
+              "kind": "field",
+              "name": "_interactionController",
+              "type": {
+                "text": "AbortController | undefined"
+              },
+              "privacy": "private"
+            },
             {
               "kind": "field",
               "name": "_directionObserver",
@@ -311,6 +385,14 @@
               },
               "privacy": "private"
             },
+            {
+              "kind": "field",
+              "name": "_triggerObserver",
+              "type": {
+                "text": "ResizeObserver | undefined"
+              },
+              "privacy": "private"
+            },
             {
               "kind": "field",
               "name": "_reanchorFrame",
@@ -329,6 +411,14 @@
               "privacy": "private",
               "default": "false"
             },
+            {
+              "kind": "field",
+              "name": "_hoverCloseTimer",
+              "type": {
+                "text": "ReturnType<typeof setTimeout> | undefined"
+              },
+              "privacy": "private"
+            },
             {
               "kind": "field",
               "name": "_mode",
@@ -388,6 +478,16 @@
                 }
               }
             },
+            {
+              "kind": "method",
+              "name": "_refreshTriggerClippers",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              }
+            },
             {
               "kind": "method",
               "name": "handleCloseButtonClick",
@@ -398,6 +498,76 @@
                 }
               }
             },
+            {
+              "kind": "method",
+              "name": "_getTriggerElement",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "Element | null"
+                }
+              }
+            },
+            {
+              "kind": "method",
+              "name": "_requestOpen",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              }
+            },
+            {
+              "kind": "method",
+              "name": "_requestClose",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              }
+            },
+            {
+              "kind": "method",
+              "name": "_startHoverCloseTimer",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              }
+            },
+            {
+              "kind": "method",
+              "name": "_cancelHoverCloseTimer",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              }
+            },
+            {
+              "kind": "method",
+              "name": "_rebuildInteractionListeners",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              }
+            },
+            {
+              "kind": "method",
+              "name": "_teardownInteractionListeners",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              }
+            },
             {
               "kind": "method",
               "name": "renderHeading",
@@ -424,7 +594,14 @@
               "type": {
                 "text": "Event"
               },
-              "description": "When the close button is clicked. Set `isOpen` to `false` in response.",
+              "description": "When a configured trigger asks for the panel. Set `isOpen` to `true` in response.",
+              "name": "pie-tooltip-open"
+            },
+            {
+              "type": {
+                "text": "Event"
+              },
+              "description": "When the close button is clicked, or a configured trigger asks to dismiss the panel. Set `isOpen` to `false` in response.",
               "name": "pie-tooltip-close"
             }
           ],
@@ -477,6 +654,14 @@
                 "text": "TooltipProps['aria']"
               },
               "fieldName": "aria"
+            },
+            {
+              "name": "triggers",
+              "type": {
+                "text": "TooltipProps['triggers']"
+              },
+              "default": "[]",
+              "fieldName": "triggers"
             }
           ],
           "superclass": {

package/dist/index.d.ts

@@ -19,7 +19,7 @@ export declare const componentClass = "c-tooltip";
 
 export declare const componentSelector = "pie-tooltip";
 
-export declare type DefaultProps = ComponentDefaultProps<TooltipProps, keyof Omit<TooltipProps, 'trigger' | 'heading' | 'aria'>>;
+export declare type DefaultProps = ComponentDefaultProps<TooltipProps, keyof Omit<TooltipProps, 'trigger' | 'heading' | 'aria' | 'triggers'>>;
 
 export declare const defaultProps: DefaultProps;
 
@@ -33,9 +33,12 @@ export declare const modes: readonly ["tooltip", "dialog"];
 
 export declare const ON_TOOLTIP_CLOSE_EVENT = "pie-tooltip-close";
 
+export declare const ON_TOOLTIP_OPEN_EVENT = "pie-tooltip-open";
+
 /**
  * @tagname pie-tooltip
- * @event {Event} pie-tooltip-close - When the close button is clicked. Set `isOpen` to `false` in response.
+ * @event {Event} pie-tooltip-open - When a configured trigger asks for the panel. Set `isOpen` to `true` in response.
+ * @event {Event} pie-tooltip-close - When the close button is clicked, or a configured trigger asks to dismiss the panel. Set `isOpen` to `false` in response.
  * @slot content - The descriptive content of the panel. Must not contain focusable elements.
  * @slot action - An optional slot for interactive content such as a `pie-button`. Filling this slot switches the panel to a non-modal dialog.
  */
@@ -50,14 +53,21 @@ export declare class PieTooltip extends PieElement implements TooltipProps {
     heading: TooltipProps['heading'];
     headingLevel: "h2" | "h3" | "h4" | "h5" | "h6";
     aria: TooltipProps['aria'];
+    triggers: TooltipProps['triggers'];
     private _assignedActionElements;
     private _originElement;
     private _hasActionContent;
     private _isPositioned;
+    private _isAnchorVisible;
+    private _clippedTriggerElement;
+    private _triggerClippers;
     private _triggerTrackingController;
+    private _interactionController;
     private _directionObserver;
+    private _triggerObserver;
     private _reanchorFrame;
     private _shouldResolveOverlayMode;
+    private _hoverCloseTimer;
     static styles: CSSResult;
     private get _mode();
     protected firstUpdated(): void;
@@ -68,7 +78,15 @@ export declare class PieTooltip extends PieElement implements TooltipProps {
     private resolveMode;
     private resolveOverlayMode;
     private projectOverTrigger;
+    private _refreshTriggerClippers;
     private handleCloseButtonClick;
+    private _getTriggerElement;
+    private _requestOpen;
+    private _requestClose;
+    private _startHoverCloseTimer;
+    private _cancelHoverCloseTimer;
+    private _rebuildInteractionListeners;
+    private _teardownInteractionListeners;
     private renderHeading;
     private renderCloseButton;
     render(): TemplateResult;
@@ -128,8 +146,20 @@ export declare interface TooltipProps {
      * The ARIA labels used for various parts of the tooltip.
      */
     aria?: AriaProps;
+    /**
+     * Which interactions request that the panel opens and closes. The component never opens or
+     * closes itself: a configured interaction emits `pie-tooltip-open` or `pie-tooltip-close`
+     * and the consumer decides whether to honour it by setting `isOpen`. Empty by default, so
+     * no interaction is watched at all. Configure `hover` and `focus` together for keyboard
+     * reachability, and `click` for pointer users.
+     */
+    triggers?: Array<TooltipTrigger>;
 }
 
+export declare type TooltipTrigger = typeof triggers[number];
+
+export declare const triggers: readonly ["hover", "focus", "click"];
+
 export declare const types: readonly ["default", "icon"];
 
 export declare const variants: readonly ["default", "inverse"];