playbook_ui 16.9.0 → 16.10.0.pre.alpha.PLAY3053advancedtablebottompinnedrowsreact17469

data/app/pb_kits/playbook/pb_popover/_popover.tsx

@@ -1,5 +1,5 @@
 /* eslint-disable react/no-multi-comp */
-import React, { useEffect, useRef, useState } from "react";
+import React, { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import ReactDOM from "react-dom";
 import {
   Popper,
@@ -20,6 +20,11 @@ import {
 import classnames from "classnames";
 import { globalProps, GlobalProps } from "../utilities/globalProps";
 import { uniqueId } from '../utilities/object';
+import { DialogContext, DialogContextValue } from "../pb_dialog/_dialog_context";
+import {
+  PB_FLOATING_OWNER_ATTR,
+  isPortaledFloatingKitInteraction,
+} from "../utilities/floatingPortalHosts";
 
 type ModifiedGlobalProps = Omit<GlobalProps, 'minWidth' | 'maxHeight' | 'minHeight'>
 
@@ -112,6 +117,17 @@ const Popover = (props: PbPopoverProps) => {
       : filteredGlobalProps
   const overflowHandling = maxHeight || maxWidth ? "overflow_handling" : "";
   const zIndexStyle = zIndex ? { zIndex: zIndex } : {};
+
+  const [selectMenuPortalTarget, setSelectMenuPortalTarget] =
+    useState<HTMLElement | null>(null);
+  const floatingRootRef = useCallback((node: HTMLElement | null) => {
+    setSelectMenuPortalTarget(node);
+  }, []);
+
+  const menuPortalApi: DialogContextValue = useMemo(
+    () => ({ selectMenuPortalTarget }),
+    [selectMenuPortalTarget],
+  );
   const widthHeightStyles = () => {
     return Object.assign(
       {},
@@ -152,17 +168,30 @@ const Popover = (props: PbPopoverProps) => {
             <div
                 className={classnames(`${buildCss("pb_popover_tooltip")} show`)}
             >
-              <div
-                  className={classnames(
-                    "pb_popover_body",
-                    popoverSpacing,
-                    overflowHandling
-                  )}
-                  id={targetId}
-                  style={widthHeightStyles()}
-              >
-                {children}
-              </div>
+            <div
+                className={classnames("pb_popover_body", popoverSpacing)}
+                id={targetId}
+                style={widthHeightStyles()}
+                {...(targetId ? { [PB_FLOATING_OWNER_ATTR]: targetId } : {})}
+            >
+              <DialogContext.Provider value={menuPortalApi}>
+                <div
+                    className={classnames(
+                      "pb_popover_scroll_region",
+                      overflowHandling,
+                    )}
+                >
+                  {children}
+                </div>
+                <div
+                    aria-hidden="true"
+                    className="pb_popover_floating_root"
+                    data-pb-dialog-floating-root="true"
+                    {...(targetId ? { [PB_FLOATING_OWNER_ATTR]: targetId } : {})}
+                    ref={floatingRootRef}
+                />
+              </DialogContext.Provider>
+            </div>
             </div>
           </div>
         );
@@ -211,12 +240,14 @@ const PbReactPopover = (props: PbPopoverProps): React.ReactElement => {
     // that the old listener is removed and the new listener is
     // updated with the targetId.
     const handleClick = (e: MouseEvent) => {
-      const target = e.target as HTMLElement
+      const targetEl =
+        e.target instanceof Element ? (e.target as HTMLElement) : null
 
       const targetIsPopover =
-        target.closest("#" + targetId) !== null;
+        (targetEl?.closest("#" + targetId) !== null) ||
+        isPortaledFloatingKitInteraction(e.target, targetId, e.clientX, e.clientY);
       const targetIsReference =
-        target.closest("#reference-" + targetId) !== null;
+        targetEl?.closest("#reference-" + targetId) !== null;
 
       const shouldClose = () => {
         setTimeout(() => shouldClosePopoverRef.current(true), 0);
@@ -227,9 +258,11 @@ const PbReactPopover = (props: PbPopoverProps): React.ReactElement => {
           if (!targetIsPopover && !targetIsReference) shouldClose();
           break;
         case "inside":
+          if (isPortaledFloatingKitInteraction(e.target, targetId, e.clientX, e.clientY)) return
           if (targetIsPopover) shouldClose();
           break;
         case "any":
+          if (isPortaledFloatingKitInteraction(e.target, targetId, e.clientX, e.clientY)) return
           if (targetIsPopover || !targetIsPopover && !targetIsReference) shouldClose();
           break;
       }
@@ -287,7 +320,7 @@ const PbReactPopover = (props: PbPopoverProps): React.ReactElement => {
                 )}
             </>
           ) : (
-            { popoverComponent }
+            popoverComponent
           ))}
       </>
     </PopperManager>

data/app/pb_kits/playbook/pb_popover/docs/_playground.json

@@ -1,104 +1,213 @@
 {
-  "template": "<Popover{{props}}>{{children}}</Popover>",
+  "template": "<PbReactPopover\n      reference={popoverReference}\n      shouldClosePopover={handleShouldClosePopover}\n      show={showPopover}{{props}}\n  >\n    {{children}}\n  </PbReactPopover>",
   "propTargets": {},
   "defaults": {
     "appendTo": "body",
-    "closeOnClick": "none",
-    "offset": false,
+    "closeOnClick": "outside",
+    "offset": true,
     "show": false,
-    "shouldClosePopover": "noop"
+    "shouldClosePopover": "noop",
+    "placement": "top"
   },
   "children": {
     "editable": true,
-    "default": "Popover body"
+    "default": "I'm a popover. I can show content of any size."
   },
   "groups": [
     {
       "name": "Behavior",
       "props": [
         "placement",
-        "show",
         "closeOnClick",
-        "reference",
-        "shouldClosePopover"
+        "offset",
+        "appendTo"
       ]
     },
     {
-      "name": "Appearance",
+      "name": "Size and Layering",
       "props": [
-        "offset",
-        "appendTo"
+        "width",
+        "maxHeight",
+        "maxWidth",
+        "zIndex"
       ]
     }
   ],
   "presets": [
     {
-      "name": "Open — top",
+      "name": "Default",
       "props": {
-        "placement": "top",
-        "show": true
+        "closeOnClick": "outside",
+        "placement": "top"
       },
-      "children": "Popover on top"
+      "children": "I'm a popover. I can show content of any size."
     },
     {
-      "name": "Open — bottom",
+      "name": "Bottom",
       "props": {
-        "placement": "bottom",
-        "show": true
+        "closeOnClick": "outside",
+        "offset": true,
+        "placement": "bottom"
       },
       "children": "Popover on bottom"
     },
     {
-      "name": "Open — left",
+      "name": "Right",
       "props": {
-        "placement": "left",
-        "show": true
+        "closeOnClick": "outside",
+        "offset": true,
+        "placement": "right"
       },
-      "children": "Popover on the left"
+      "children": "Popover on the right"
     },
     {
-      "name": "Open — right",
+      "name": "Right Start",
       "props": {
-        "placement": "right",
-        "show": true
+        "closeOnClick": "outside",
+        "offset": true,
+        "placement": "right-start"
       },
-      "children": "Popover on the right"
+      "children": "Popover aligned to the start of the right side"
     },
     {
-      "name": "Closed",
+      "name": "Right End",
       "props": {
-        "placement": "bottom",
-        "show": false
+        "closeOnClick": "outside",
+        "offset": true,
+        "placement": "right-end"
       },
-      "children": "Trigger content"
+      "children": "Popover aligned to the end of the right side"
     },
     {
-      "name": "With offset",
+      "name": "Actionable Content",
       "props": {
-        "placement": "bottom",
-        "show": true,
-        "offset": true
+        "closeOnClick": "inside",
+        "offset": true,
+        "placement": "top"
       },
-      "children": "Extra spacing from the trigger"
+      "children": "<Body textAlign=\"center\">\n  <Button\n      onClick={() => alert('Example action')}\n      text=\"Learn More\"\n  />\n</Body>"
     },
     {
-      "name": "Close on outside click",
+      "name": "Scrollable",
       "props": {
-        "placement": "bottom",
-        "show": true,
-        "closeOnClick": "outside"
+        "closeOnClick": "any",
+        "maxHeight": "150px",
+        "maxWidth": "240px",
+        "offset": true,
+        "placement": "top"
       },
-      "children": "Click outside to dismiss"
+      "children": "<Flex orientation=\"column\">\n  <Body\n      marginBottom=\"sm\"\n      text=\"Long popover content can scroll when maxHeight is set. Keep the width constrained so the popover remains readable near the trigger.\"\n  />\n  <Title\n      size={4}\n      text=\"Scrollable content\"\n  />\n</Flex>"
+    },
+    {
+      "name": "Custom Z Index",
+      "props": {
+        "closeOnClick": "outside",
+        "offset": true,
+        "placement": "top",
+        "zIndex": 3
+      },
+      "children": "I have a custom z-index of 3"
+    },
+    {
+      "name": "Append To Parent",
+      "props": {
+        "appendTo": "parent",
+        "closeOnClick": "outside",
+        "offset": true,
+        "placement": "bottom"
+      },
+      "children": "This popover is appended to the trigger parent."
     }
   ],
   "conditionals": {},
   "hints": {
-    "show_popover": {
-      "when": {
-        "show": false
-      },
-      "message": "Set show to true in the playground to render the popover content.",
+    "reference": {
+      "when": {},
+      "message": "The playground wraps Popover with local state, a CircleIconButton reference, and shouldClosePopover so closeOnClick can update the open state.",
+      "type": "info"
+    },
+    "close_inside": {
+      "presetName": "Actionable Content",
+      "message": "closeOnClick inside closes the popover after a click inside its body, which works well for button-style popovers.",
       "type": "info"
+    },
+    "list": {
+      "presetName": "List",
+      "message": "Popover children can be composed from other kits, such as List and ListItem.",
+      "type": "info"
+    },
+    "scrollable": {
+      "presetName": "Scrollable",
+      "message": "maxHeight and maxWidth constrain large popover content and enable overflow handling.",
+      "type": "info"
+    },
+    "z_index": {
+      "presetName": "Custom Z Index",
+      "message": "zIndex is useful when a popover must sit above nearby positioned content.",
+      "type": "info"
+    },
+    "append_to_parent": {
+      "presetName": "Append To Parent",
+      "message": "appendTo can be body, parent, or a selector. Use parent when the popover should stay inside the trigger's local stacking context.",
+      "type": "info"
+    }
+  },
+  "wrapper": "const PopoverPlayground = () => {\n  const [showPopover, setShowPopover] = useState(true)\n\n  const handleTogglePopover = () => {\n    setShowPopover((open) => !open)\n  }\n\n  const handleShouldClosePopover = (shouldClose) => {\n    setShowPopover(!shouldClose)\n  }\n\n  const popoverReference = (\n    <CircleIconButton\n        icon=\"info\"\n        onClick={handleTogglePopover}\n        variant=\"secondary\"\n    />\n  )\n\n  return (\n    <Flex\n        justify=\"center\"\n        minHeight=\"260px\"\n        orientation=\"row\"\n        vertical=\"center\"\n        width=\"100%\"\n    >\n      {{component}}\n    </Flex>\n  )\n}\n\n<PopoverPlayground />",
+  "externalImports": [
+    "import React, { useState } from 'react'"
+  ],
+  "customProps": {
+    "placement": {
+      "type": "enum",
+      "platforms": [
+        "react"
+      ],
+      "values": [
+        "top",
+        "top-start",
+        "top-end",
+        "bottom",
+        "bottom-start",
+        "bottom-end",
+        "left",
+        "left-start",
+        "left-end",
+        "right",
+        "right-start",
+        "right-end"
+      ]
+    },
+    "width": {
+      "type": "string",
+      "platforms": [
+        "react"
+      ],
+      "default": ""
+    },
+    "maxHeight": {
+      "type": "string",
+      "platforms": [
+        "react"
+      ],
+      "default": ""
+    },
+    "maxWidth": {
+      "type": "string",
+      "platforms": [
+        "react"
+      ],
+      "default": ""
+    },
+    "zIndex": {
+      "type": "number",
+      "platforms": [
+        "react"
+      ]
     }
-  }
+  },
+  "hiddenProps": [
+    "reference",
+    "shouldClosePopover",
+    "show"
+  ]
 }

data/app/pb_kits/playbook/pb_popover/docs/_playground.overrides.json

@@ -1,66 +1,198 @@
 {
+  "template": "<PbReactPopover\n      reference={popoverReference}\n      shouldClosePopover={handleShouldClosePopover}\n      show={showPopover}{{props}}\n  >\n    {{children}}\n  </PbReactPopover>",
+  "wrapper": "const PopoverPlayground = () => {\n  const [showPopover, setShowPopover] = useState(true)\n\n  const handleTogglePopover = () => {\n    setShowPopover((open) => !open)\n  }\n\n  const handleShouldClosePopover = (shouldClose) => {\n    setShowPopover(!shouldClose)\n  }\n\n  const popoverReference = (\n    <CircleIconButton\n        icon=\"info\"\n        onClick={handleTogglePopover}\n        variant=\"secondary\"\n    />\n  )\n\n  return (\n    <Flex\n        justify=\"center\"\n        minHeight=\"260px\"\n        orientation=\"row\"\n        vertical=\"center\"\n        width=\"100%\"\n    >\n      {{component}}\n    </Flex>\n  )\n}\n\n<PopoverPlayground />",
+  "externalImports": [
+    "import React, { useState } from 'react'"
+  ],
   "children": {
-    "default": "Popover body"
+    "editable": true,
+    "default": "I'm a popover. I can show content of any size."
+  },
+  "customProps": {
+    "placement": {
+      "type": "enum",
+      "platforms": ["react"],
+      "values": [
+        "top",
+        "top-start",
+        "top-end",
+        "bottom",
+        "bottom-start",
+        "bottom-end",
+        "left",
+        "left-start",
+        "left-end",
+        "right",
+        "right-start",
+        "right-end"
+      ]
+    },
+    "width": {
+      "type": "string",
+      "platforms": ["react"],
+      "default": ""
+    },
+    "maxHeight": {
+      "type": "string",
+      "platforms": ["react"],
+      "default": ""
+    },
+    "maxWidth": {
+      "type": "string",
+      "platforms": ["react"],
+      "default": ""
+    },
+    "zIndex": {
+      "type": "number",
+      "platforms": ["react"]
+    }
+  },
+  "hiddenProps": [
+    "reference",
+    "shouldClosePopover",
+    "show"
+  ],
+  "defaults": {
+    "closeOnClick": "outside",
+    "offset": true,
+    "placement": "top"
   },
   "groups": [
     {
       "name": "Behavior",
       "props": [
         "placement",
-        "show",
         "closeOnClick",
-        "reference",
-        "shouldClosePopover"
+        "offset",
+        "appendTo"
       ]
     },
-    { "name": "Appearance", "props": ["offset", "appendTo"] }
+    {
+      "name": "Size and Layering",
+      "props": [
+        "width",
+        "maxHeight",
+        "maxWidth",
+        "zIndex"
+      ]
+    }
   ],
   "presets": [
     {
-      "name": "Open — top",
-      "props": { "placement": "top", "show": true },
-      "children": "Popover on top"
+      "name": "Default",
+      "props": {
+        "closeOnClick": "outside",
+        "placement": "top"
+      },
+      "children": "I'm a popover. I can show content of any size."
     },
     {
-      "name": "Open — bottom",
-      "props": { "placement": "bottom", "show": true },
+      "name": "Bottom",
+      "props": {
+        "closeOnClick": "outside",
+        "offset": true,
+        "placement": "bottom"
+      },
       "children": "Popover on bottom"
     },
     {
-      "name": "Open — left",
-      "props": { "placement": "left", "show": true },
-      "children": "Popover on the left"
+      "name": "Right",
+      "props": {
+        "closeOnClick": "outside",
+        "offset": true,
+        "placement": "right"
+      },
+      "children": "Popover on the right"
     },
     {
-      "name": "Open — right",
-      "props": { "placement": "right", "show": true },
-      "children": "Popover on the right"
+      "name": "Right Start",
+      "props": {
+        "closeOnClick": "outside",
+        "offset": true,
+        "placement": "right-start"
+      },
+      "children": "Popover aligned to the start of the right side"
+    },
+    {
+      "name": "Right End",
+      "props": {
+        "closeOnClick": "outside",
+        "offset": true,
+        "placement": "right-end"
+      },
+      "children": "Popover aligned to the end of the right side"
     },
     {
-      "name": "Closed",
-      "props": { "placement": "bottom", "show": false },
-      "children": "Trigger content"
+      "name": "Actionable Content",
+      "props": {
+        "closeOnClick": "inside",
+        "offset": true,
+        "placement": "top"
+      },
+      "children": "<Body textAlign=\"center\">\n  <Button\n      onClick={() => alert('Example action')}\n      text=\"Learn More\"\n  />\n</Body>"
     },
     {
-      "name": "With offset",
-      "props": { "placement": "bottom", "show": true, "offset": true },
-      "children": "Extra spacing from the trigger"
+      "name": "Scrollable",
+      "props": {
+        "closeOnClick": "any",
+        "maxHeight": "150px",
+        "maxWidth": "240px",
+        "offset": true,
+        "placement": "top"
+      },
+      "children": "<Flex orientation=\"column\">\n  <Body\n      marginBottom=\"sm\"\n      text=\"Long popover content can scroll when maxHeight is set. Keep the width constrained so the popover remains readable near the trigger.\"\n  />\n  <Title\n      size={4}\n      text=\"Scrollable content\"\n  />\n</Flex>"
     },
     {
-      "name": "Close on outside click",
+      "name": "Custom Z Index",
       "props": {
-        "placement": "bottom",
-        "show": true,
-        "closeOnClick": "outside"
+        "closeOnClick": "outside",
+        "offset": true,
+        "placement": "top",
+        "zIndex": 3
       },
-      "children": "Click outside to dismiss"
+      "children": "I have a custom z-index of 3"
+    },
+    {
+      "name": "Append To Parent",
+      "props": {
+        "appendTo": "parent",
+        "closeOnClick": "outside",
+        "offset": true,
+        "placement": "bottom"
+      },
+      "children": "This popover is appended to the trigger parent."
     }
   ],
   "conditionals": {},
   "hints": {
-    "show_popover": {
-      "when": { "show": false },
-      "message": "Set show to true in the playground to render the popover content.",
+    "reference": {
+      "when": {},
+      "message": "The playground wraps Popover with local state, a CircleIconButton reference, and shouldClosePopover so closeOnClick can update the open state.",
+      "type": "info"
+    },
+    "close_inside": {
+      "presetName": "Actionable Content",
+      "message": "closeOnClick inside closes the popover after a click inside its body, which works well for button-style popovers.",
+      "type": "info"
+    },
+    "list": {
+      "presetName": "List",
+      "message": "Popover children can be composed from other kits, such as List and ListItem.",
+      "type": "info"
+    },
+    "scrollable": {
+      "presetName": "Scrollable",
+      "message": "maxHeight and maxWidth constrain large popover content and enable overflow handling.",
+      "type": "info"
+    },
+    "z_index": {
+      "presetName": "Custom Z Index",
+      "message": "zIndex is useful when a popover must sit above nearby positioned content.",
+      "type": "info"
+    },
+    "append_to_parent": {
+      "presetName": "Append To Parent",
+      "message": "appendTo can be body, parent, or a selector. Use parent when the popover should stay inside the trigger's local stacking context.",
       "type": "info"
     }
   }

data/app/pb_kits/playbook/pb_popover/docs/_popover_list.jsx

@@ -19,18 +19,16 @@ const PopoverWithButton = (props) => {
         onClick={handleTogglePopover}
         variant="secondary"
     >
-      <Flex align="center">
+      <Flex 
+          align="center"
+          gap="xxs" 
+      >
         {"Filter By"}
-        <Flex
-            className={showPopover ? "fa-flip-vertical" : ""}
-            display="inline_flex"
-        >
-          <Icon
-              fixedWidth
-              icon="angle-down"
-              margin-left="xxs"
-          />
-        </Flex>
+        <Icon
+            fixedWidth
+            flip={showPopover ? "vertical" : "none"}
+            icon="angle-down"
+        />
       </Flex>
     </Button>
   )