feat: add visibleFirst

.prettierrc

@@ -3,5 +3,6 @@
   "semi": true,
   "singleQuote": true,
   "tabWidth": 2,
-  "trailingComma": "all"
+  "trailingComma": "all",
+  "jsxSingleQuote": false
 }

docs/demos/visible-fallback.md

@@ -0,0 +1,8 @@
+---
+title: Visible Fallback
+nav:
+  title: Demo
+  path: /demo
+---
+
+<code src="../examples/visible-fallback.tsx"></code>

docs/examples/visible-fallback.tsx

@@ -0,0 +1,109 @@
+/* eslint no-console:0 */
+import type { AlignType, TriggerRef } from 'rc-trigger';
+import Trigger from 'rc-trigger';
+import React from 'react';
+import '../../assets/index.less';
+
+const builtinPlacements: Record<string, AlignType> = {
+  top: {
+    points: ['bc', 'tc'],
+    overflow: {
+      adjustX: true,
+      adjustY: true,
+    },
+    offset: [0, 0],
+    htmlRegion: 'visibleFirst',
+  },
+  bottom: {
+    points: ['tc', 'bc'],
+    overflow: {
+      adjustX: true,
+      adjustY: true,
+    },
+    offset: [0, 0],
+    htmlRegion: 'visibleFirst',
+  },
+};
+
+export default () => {
+  const [enoughTop, setEnoughTop] = React.useState(true);
+
+  const triggerRef = React.useRef<TriggerRef>();
+
+  React.useEffect(() => {
+    triggerRef.current?.forceAlign();
+  }, [enoughTop]);
+
+  return (
+    <React.StrictMode>
+      <p>`visibleFirst` should not show in hidden region if still scrollable</p>
+
+      <label>
+        <input
+          type="checkbox"
+          checked={enoughTop}
+          onChange={() => setEnoughTop((v) => !v)}
+        />
+        Enough Top (Placement: bottom)
+      </label>
+
+      <div
+        style={{
+          position: 'absolute',
+          left: '50%',
+          top: `calc(100vh - 100px - 90px - 50px)`,
+          transform: 'translateX(-50%)',
+          boxShadow: '0 0 1px blue',
+          overflow: 'hidden',
+          width: 500,
+          height: 1000,
+        }}
+      >
+        <Trigger
+          arrow
+          action="click"
+          popupVisible
+          ref={triggerRef}
+          popup={
+            <div
+              style={{
+                background: 'yellow',
+                border: '1px solid blue',
+                width: 300,
+                height: 100,
+                opacity: 0.9,
+                boxSizing: 'border-box',
+              }}
+            >
+              Should Always place bottom
+            </div>
+          }
+          getPopupContainer={(n) => n.parentNode as any}
+          popupStyle={{ boxShadow: '0 0 5px red' }}
+          popupPlacement={enoughTop ? 'bottom' : 'top'}
+          builtinPlacements={builtinPlacements}
+          stretch="minWidth"
+        >
+          <span
+            style={{
+              background: 'green',
+              color: '#FFF',
+              opacity: 0.9,
+              display: 'flex',
+              alignItems: 'center',
+              justifyContent: 'center',
+              width: 100,
+              height: 100,
+              position: 'absolute',
+              left: '50%',
+              top: enoughTop ? 200 : 90,
+              transform: 'translateX(-50%)',
+            }}
+          >
+            Target
+          </span>
+        </Trigger>
+      </div>
+    </React.StrictMode>
+  );
+};

src/hooks/useAlign.ts

@@ -210,23 +210,39 @@ export default function useAlign(
       const targetWidth = targetRect.width;
 
       // Get bounding of visible area
-      let visibleArea =
-        placementInfo.htmlRegion === 'scroll'
-          ? // Scroll region should take scrollLeft & scrollTop into account
-            {
-              left: -scrollLeft,
-              top: -scrollTop,
-              right: scrollWidth - scrollLeft,
-              bottom: scrollHeight - scrollTop,
-            }
-          : {
-              left: 0,
-              top: 0,
-              right: clientWidth,
-              bottom: clientHeight,
-            };
-
-      visibleArea = getVisibleArea(visibleArea, scrollerList);
+      const visibleRegion = {
+        left: 0,
+        top: 0,
+        right: clientWidth,
+        bottom: clientHeight,
+      };
+
+      const scrollRegion = {
+        left: -scrollLeft,
+        top: -scrollTop,
+        right: scrollWidth - scrollLeft,
+        bottom: scrollHeight - scrollTop,
+      };
+
+      let { htmlRegion } = placementInfo;
+      const VISIBLE = 'visible' as const;
+      const VISIBLE_FIRST = 'visibleFirst' as const;
+      if (htmlRegion !== 'scroll' && htmlRegion !== VISIBLE_FIRST) {
+        htmlRegion = VISIBLE;
+      }
+      const isVisibleFirst = htmlRegion === VISIBLE_FIRST;
+
+      const scrollRegionArea = getVisibleArea(scrollRegion, scrollerList);
+      const visibleRegionArea = getVisibleArea(visibleRegion, scrollerList);
+
+      const visibleArea =
+        htmlRegion === VISIBLE ? visibleRegionArea : scrollRegionArea;
+
+      // When set to `visibleFirst`,
+      // the check `adjust` logic will use `visibleRegion` for check first.
+      const adjustCheckVisibleArea = isVisibleFirst
+        ? visibleRegionArea
+        : visibleArea;
 
       // Reset back
       popupElement.style.left = originLeft;
@@ -279,17 +295,21 @@ export default function useAlign(
 
       // ============== Intersection ===============
       // Get area by position. Used for check if flip area is better
-      function getIntersectionVisibleArea(offsetX: number, offsetY: number) {
+      function getIntersectionVisibleArea(
+        offsetX: number,
+        offsetY: number,
+        area = visibleArea,
+      ) {
         const l = popupRect.x + offsetX;
         const t = popupRect.y + offsetY;
 
         const r = l + popupWidth;
         const b = t + popupHeight;
 
-        const visibleL = Math.max(l, visibleArea.left);
-        const visibleT = Math.max(t, visibleArea.top);
-        const visibleR = Math.min(r, visibleArea.right);
-        const visibleB = Math.min(b, visibleArea.bottom);
+        const visibleL = Math.max(l, area.left);
+        const visibleT = Math.max(t, area.top);
+        const visibleR = Math.min(r, area.right);
+        const visibleB = Math.min(b, area.bottom);
 
         return Math.max(0, (visibleR - visibleL) * (visibleB - visibleT));
       }
@@ -299,6 +319,13 @@ export default function useAlign(
         nextOffsetY,
       );
 
+      // As `visibleFirst`, we prepare this for check
+      const originIntersectionRecommendArea = getIntersectionVisibleArea(
+        nextOffsetX,
+        nextOffsetY,
+        visibleRegionArea,
+      );
+
       // ========================== Overflow ===========================
       const targetAlignPointTL = getAlignPoint(targetRect, ['t', 'l']);
       const popupAlignPointTL = getAlignPoint(popupRect, ['t', 'l']);
@@ -338,7 +365,8 @@ export default function useAlign(
       if (
         needAdjustY &&
         popupPoints[0] === 't' &&
-        (nextPopupBottom > visibleArea.bottom || prevFlipRef.current.bt)
+        (nextPopupBottom > adjustCheckVisibleArea.bottom ||
+          prevFlipRef.current.bt)
       ) {
         let tmpNextOffsetY: number = nextOffsetY;
 
@@ -349,9 +377,23 @@ export default function useAlign(
             targetAlignPointTL.y - popupAlignPointBR.y - popupOffsetY;
         }
 
+        const newVisibleArea = getIntersectionVisibleArea(
+          nextOffsetX,
+          tmpNextOffsetY,
+        );
+        const newVisibleRecommendArea = getIntersectionVisibleArea(
+          nextOffsetX,
+          tmpNextOffsetY,
+          visibleRegionArea,
+        );
+
         if (
-          getIntersectionVisibleArea(nextOffsetX, tmpNextOffsetY) >=
-          originIntersectionVisibleArea
+          // Of course use larger one
+          newVisibleArea > originIntersectionVisibleArea ||
+          (newVisibleArea === originIntersectionVisibleArea &&
+            (!isVisibleFirst ||
+              // Choose recommend one
+              newVisibleRecommendArea >= originIntersectionRecommendArea))
         ) {
           prevFlipRef.current.bt = true;
           nextOffsetY = tmpNextOffsetY;
@@ -369,7 +411,7 @@ export default function useAlign(
       if (
         needAdjustY &&
         popupPoints[0] === 'b' &&
-        (nextPopupY < visibleArea.top || prevFlipRef.current.tb)
+        (nextPopupY < adjustCheckVisibleArea.top || prevFlipRef.current.tb)
       ) {
         let tmpNextOffsetY: number = nextOffsetY;
 
@@ -380,9 +422,23 @@ export default function useAlign(
             targetAlignPointBR.y - popupAlignPointTL.y - popupOffsetY;
         }
 
+        const newVisibleArea = getIntersectionVisibleArea(
+          nextOffsetX,
+          tmpNextOffsetY,
+        );
+        const newVisibleRecommendArea = getIntersectionVisibleArea(
+          nextOffsetX,
+          tmpNextOffsetY,
+          visibleRegionArea,
+        );
+
         if (
-          getIntersectionVisibleArea(nextOffsetX, tmpNextOffsetY) >=
-          originIntersectionVisibleArea
+          // Of course use larger one
+          newVisibleArea > originIntersectionVisibleArea ||
+          (newVisibleArea === originIntersectionVisibleArea &&
+            (!isVisibleFirst ||
+              // Choose recommend one
+              newVisibleRecommendArea >= originIntersectionRecommendArea))
         ) {
           prevFlipRef.current.tb = true;
           nextOffsetY = tmpNextOffsetY;
@@ -406,7 +462,8 @@ export default function useAlign(
       if (
         needAdjustX &&
         popupPoints[1] === 'l' &&
-        (nextPopupRight > visibleArea.right || prevFlipRef.current.rl)
+        (nextPopupRight > adjustCheckVisibleArea.right ||
+          prevFlipRef.current.rl)
       ) {
         let tmpNextOffsetX: number = nextOffsetX;
 
@@ -417,9 +474,23 @@ export default function useAlign(
             targetAlignPointTL.x - popupAlignPointBR.x - popupOffsetX;
         }
 
+        const newVisibleArea = getIntersectionVisibleArea(
+          tmpNextOffsetX,
+          nextOffsetY,
+        );
+        const newVisibleRecommendArea = getIntersectionVisibleArea(
+          tmpNextOffsetX,
+          nextOffsetY,
+          visibleRegionArea,
+        );
+
         if (
-          getIntersectionVisibleArea(tmpNextOffsetX, nextOffsetY) >=
-          originIntersectionVisibleArea
+          // Of course use larger one
+          newVisibleArea > originIntersectionVisibleArea ||
+          (newVisibleArea === originIntersectionVisibleArea &&
+            (!isVisibleFirst ||
+              // Choose recommend one
+              newVisibleRecommendArea >= originIntersectionRecommendArea))
         ) {
           prevFlipRef.current.rl = true;
           nextOffsetX = tmpNextOffsetX;
@@ -437,7 +508,7 @@ export default function useAlign(
       if (
         needAdjustX &&
         popupPoints[1] === 'r' &&
-        (nextPopupX < visibleArea.left || prevFlipRef.current.lr)
+        (nextPopupX < adjustCheckVisibleArea.left || prevFlipRef.current.lr)
       ) {
         let tmpNextOffsetX: number = nextOffsetX;
 
@@ -448,9 +519,23 @@ export default function useAlign(
             targetAlignPointBR.x - popupAlignPointTL.x - popupOffsetX;
         }
 
+        const newVisibleArea = getIntersectionVisibleArea(
+          tmpNextOffsetX,
+          nextOffsetY,
+        );
+        const newVisibleRecommendArea = getIntersectionVisibleArea(
+          tmpNextOffsetX,
+          nextOffsetY,
+          visibleRegionArea,
+        );
+
         if (
-          getIntersectionVisibleArea(tmpNextOffsetX, nextOffsetY) >=
-          originIntersectionVisibleArea
+          // Of course use larger one
+          newVisibleArea > originIntersectionVisibleArea ||
+          (newVisibleArea === originIntersectionVisibleArea &&
+            (!isVisibleFirst ||
+              // Choose recommend one
+              newVisibleRecommendArea >= originIntersectionRecommendArea))
         ) {
           prevFlipRef.current.lr = true;
           nextOffsetX = tmpNextOffsetX;

src/index.tsx

@@ -386,7 +386,7 @@ export function generateTrigger(
 
     useLayoutEffect(() => {
       triggerAlign();
-    }, [mousePos]);
+    }, [mousePos, popupPlacement]);
 
     // When no builtinPlacements and popupAlign changed
     useLayoutEffect(() => {

src/interface.ts

@@ -52,10 +52,17 @@ export interface AlignType {
   autoArrow?: boolean;
   /**
    * Config visible region check of html node. Default `visible`:
-   *  - `visible`: The visible region of user browser window. Use `clientHeight` for check.
-   *  - `scroll`: The whole region of the html scroll area. Use `scrollHeight` for check.
+   *  - `visible`:
+   *    The visible region of user browser window.
+   *    Use `clientHeight` for check.
+   *    If `visible` region not satisfy, fallback to `scroll`.
+   *  - `scroll`:
+   *    The whole region of the html scroll area.
+   *    Use `scrollHeight` for check.
+   *  - `visibleFirst`:
+   *    Similar to `visible`, but if `visible` region not satisfy, fallback to `scroll`.
    */
-  htmlRegion?: 'visible' | 'scroll';
+  htmlRegion?: 'visible' | 'scroll' | 'visibleFirst';
   /**
    * Whether use css right instead of left to position
    */