@justeattakeaway/pie-tooltip 0.3.0 → 0.4.0

package/README.md

@@ -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` |
@@ -99,6 +99,17 @@ 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.
 
+### 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
 
 | `size` | Behaviour |

package/custom-elements.json

@@ -343,6 +343,14 @@
               "privacy": "private",
               "default": "true"
             },
+            {
+              "kind": "field",
+              "name": "_resolvedPosition",
+              "type": {
+                "text": "TooltipProps['position'] | undefined"
+              },
+              "privacy": "private"
+            },
             {
               "kind": "field",
               "name": "_clippedTriggerElement",
@@ -361,6 +369,33 @@
               "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",
@@ -404,20 +439,20 @@
             },
             {
               "kind": "field",
-              "name": "_shouldResolveOverlayMode",
+              "name": "_hoverCloseTimer",
               "type": {
-                "text": "boolean"
+                "text": "ReturnType<typeof setTimeout> | undefined"
               },
-              "privacy": "private",
-              "default": "false"
+              "privacy": "private"
             },
             {
               "kind": "field",
-              "name": "_hoverCloseTimer",
+              "name": "_openedByClick",
               "type": {
-                "text": "ReturnType<typeof setTimeout> | undefined"
+                "text": "boolean"
               },
-              "privacy": "private"
+              "privacy": "private",
+              "default": "false"
             },
             {
               "kind": "field",
@@ -478,6 +513,76 @@
                 }
               }
             },
+            {
+              "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",

package/dist/index.d.ts

@@ -59,15 +59,19 @@ export declare class PieTooltip extends PieElement implements TooltipProps {
     private _hasActionContent;
     private _isPositioned;
     private _isAnchorVisible;
+    private _resolvedPosition;
     private _clippedTriggerElement;
     private _triggerClippers;
+    private _overlayClippers;
+    private _collisionSignature;
+    private _overlayModeDirty;
     private _triggerTrackingController;
     private _interactionController;
     private _directionObserver;
     private _triggerObserver;
     private _reanchorFrame;
-    private _shouldResolveOverlayMode;
     private _hoverCloseTimer;
+    private _openedByClick;
     static styles: CSSResult;
     private get _mode();
     protected firstUpdated(): void;
@@ -78,6 +82,10 @@ export declare class PieTooltip extends PieElement implements TooltipProps {
     private resolveMode;
     private resolveOverlayMode;
     private projectOverTrigger;
+    private resolveCollision;
+    private _setResolvedPosition;
+    private _getCollisionBoundary;
+    private _getCandidatePositions;
     private _refreshTriggerClippers;
     private handleCloseButtonClick;
     private _getTriggerElement;
@@ -110,7 +118,10 @@ export declare interface TooltipProps {
      */
     isOpen?: boolean;
     /**
-     * The side of the trigger the panel sits on, and its alignment along the cross axis.
+     * The preferred side of the trigger the panel sits on, and its alignment along the cross axis.
+     * The component repositions the panel automatically — flipping to the opposite side and/or
+     * shifting its alignment — when the preferred position would collide with the viewport or with
+     * a clipping scroll container. This behaviour cannot be disabled.
      */
     position?: typeof positions[number];
     /**