@justeattakeaway/pie-tooltip 0.2.0 → 0.4.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
 
@@ -47,7 +47,7 @@ Ideally, you should install the component using the **`@justeattakeaway/pie-webc
 |---|---|---|---|
 | `trigger` | Any string | The `id` of the element the panel is anchored to. The trigger lives elsewhere in the DOM and is never slotted into the tooltip. | `undefined` |
 | `isOpen` | `true`, `false` | When true, the panel is visible. The component never writes to this property. | `false` |
-| `position` | `top`, `top-start`, `top-end`, `bottom`, `bottom-start`, `bottom-end`, `left`, `left-start`, `left-end`, `right`, `right-start`, `right-end` | The side of the trigger the panel sits on, and its alignment along the cross axis. | `top` |
+| `position` | `top`, `top-start`, `top-end`, `bottom`, `bottom-start`, `bottom-end`, `left`, `left-start`, `left-end`, `right`, `right-start`, `right-end` | The preferred side of the trigger the panel sits on, and its alignment along the cross axis. The panel repositions itself when this would collide with the viewport or a clipping scroll container. | `top` |
 | `size` | `default`, `fit-to-content`, `fill-container` | How the panel sizes itself. `default` is a fixed 280px and wraps, `fit-to-content` is as wide as its content, and `fill-container` matches the inline size of the trigger's parent element. Not applied when `type` is `icon`. | `default` |
 | `variant` | `default`, `inverse` | The colour treatment of the panel. `default` is the dark panel, `inverse` the light one. | `default` |
 | `type` | `default`, `icon` | The presentation of the panel. `icon` is the compact treatment intended for icon triggers: it has no arrow and is always as wide as its content, so `size` and `--tooltip-width` have no effect on it. | `default` |
@@ -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,18 @@ 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.
+
+### Collision detection
+
+`position` is a preference, not a guarantee. Before the panel is shown, and on every scroll, resize or direction change while it is open, the component measures the panel against the space available and repositions it if the preferred position would collide.
+
+- It flips to the opposite side first: `top` to `bottom`, and so on.
+- It then tries the remaining sides.
+- Within a side, it shifts the alignment (for example `top-start` to `top-end`) so the panel stays fully in view.
+- If no position fits entirely, it uses whichever position shows the most of the panel.
+
+The available space is the viewport, narrowed by any ancestor that clips the panel. Collision detection is always on and cannot be disabled.
 
 ## Sizing
 
@@ -131,8 +144,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 +159,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 +327,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 +342,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 +400,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,68 @@
               "privacy": "private",
               "default": "false"
             },
+            {
+              "kind": "field",
+              "name": "_isAnchorVisible",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "private",
+              "default": "true"
+            },
+            {
+              "kind": "field",
+              "name": "_resolvedPosition",
+              "type": {
+                "text": "TooltipProps['position'] | undefined"
+              },
+              "privacy": "private"
+            },
+            {
+              "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": "_overlayClippers",
+              "type": {
+                "text": "Array<Element>"
+              },
+              "privacy": "private",
+              "default": "[]"
+            },
+            {
+              "kind": "field",
+              "name": "_collisionSignature",
+              "type": {
+                "text": "string | null"
+              },
+              "privacy": "private",
+              "default": "null"
+            },
+            {
+              "kind": "field",
+              "name": "_overlayModeDirty",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "private",
+              "default": "true"
+            },
             {
               "kind": "field",
               "name": "_triggerTrackingController",
@@ -303,6 +404,14 @@
               },
               "privacy": "private"
             },
+            {
+              "kind": "field",
+              "name": "_interactionController",
+              "type": {
+                "text": "AbortController | undefined"
+              },
+              "privacy": "private"
+            },
             {
               "kind": "field",
               "name": "_directionObserver",
@@ -311,6 +420,14 @@
               },
               "privacy": "private"
             },
+            {
+              "kind": "field",
+              "name": "_triggerObserver",
+              "type": {
+                "text": "ResizeObserver | undefined"
+              },
+              "privacy": "private"
+            },
             {
               "kind": "field",
               "name": "_reanchorFrame",
@@ -322,7 +439,15 @@
             },
             {
               "kind": "field",
-              "name": "_shouldResolveOverlayMode",
+              "name": "_hoverCloseTimer",
+              "type": {
+                "text": "ReturnType<typeof setTimeout> | undefined"
+              },
+              "privacy": "private"
+            },
+            {
+              "kind": "field",
+              "name": "_openedByClick",
               "type": {
                 "text": "boolean"
               },
@@ -388,6 +513,86 @@
                 }
               }
             },
+            {
+              "kind": "method",
+              "name": "resolveCollision",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "anchorRect",
+                  "type": {
+                    "text": "DOMRect"
+                  }
+                }
+              ]
+            },
+            {
+              "kind": "method",
+              "name": "_setResolvedPosition",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "position",
+                  "type": {
+                    "text": "TooltipProps['position']"
+                  }
+                }
+              ]
+            },
+            {
+              "kind": "method",
+              "name": "_getCollisionBoundary",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "DOMRect | null"
+                }
+              }
+            },
+            {
+              "kind": "method",
+              "name": "_getCandidatePositions",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "Array<{ side: TooltipSide; alignment: TooltipAlignment }>"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "preferredSide",
+                  "type": {
+                    "text": "TooltipSide"
+                  }
+                },
+                {
+                  "name": "preferredAlignment",
+                  "type": {
+                    "text": "TooltipAlignment"
+                  }
+                }
+              ]
+            },
+            {
+              "kind": "method",
+              "name": "_refreshTriggerClippers",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              }
+            },
             {
               "kind": "method",
               "name": "handleCloseButtonClick",
@@ -398,6 +603,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 +699,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 +759,14 @@
                 "text": "TooltipProps['aria']"
               },
               "fieldName": "aria"
+            },
+            {
+              "name": "triggers",
+              "type": {
+                "text": "TooltipProps['triggers']"
+              },
+              "default": "[]",
+              "fieldName": "triggers"
             }
           ],
           "superclass": {