panelui-native 0.28.1 → 0.32.0

package/src/components/popover/index.tsx

@@ -44,6 +44,7 @@ import {
 } from 'react';
 import {
   Pressable,
+  ScrollView,
   useWindowDimensions,
   View,
   type LayoutChangeEvent,
@@ -228,6 +229,40 @@ export interface PopoverContentProps extends ViewProps {
    * content into a column.
    */
   minWidth?: number;
+  /**
+   * Ceiling for the panel's height, in pixels. Always clamped to the room
+   * inside the safe area, which is also the default — a panel is never
+   * positioned so that part of it falls off the screen, because the part that
+   * falls off cannot be scrolled back into view.
+   */
+  maxHeight?: number;
+  /**
+   * Scroll the panel's body when it is taller than `maxHeight`.
+   *
+   * Off by default, because a popover is usually a paragraph or a short form
+   * and a scroller around either one only adds a bounce. Worth turning on for
+   * a list of unknown length, which is the case where the cap actually bites.
+   *
+   * The spacing between children moves to the scroller's content when this is
+   * set; `className` still dresses the panel itself.
+   */
+  scrollable?: boolean;
+  /**
+   * Drop the panel's own surface — its background, border, radius, padding and
+   * shadow — and keep only its position and its size. For a caller that draws
+   * the surface itself, so that something can be put *behind* the content
+   * rather than layered on top of a background that is already painted.
+   *
+   * The panel is still clipped to a rounded rectangle, because a surface drawn
+   * inside it has to have something to be clipped by.
+   */
+  unstyled?: boolean;
+  /**
+   * A layer drawn inside the panel, behind its content — and, crucially,
+   * outside its scroller, so that a surface does not scroll away with the rows
+   * on top of it. Pair it with `unstyled` to own the panel's appearance.
+   */
+  background?: ReactNode;
   /** Tap outside the panel closes it. Default true. */
   dismissible?: boolean;
   /**
@@ -247,6 +282,10 @@ function PopoverContent({
   alignOffset = 0,
   width = 'content-fit',
   minWidth,
+  maxHeight,
+  scrollable = false,
+  unstyled = false,
+  background,
   dismissible = true,
   blur = false,
   children,
@@ -303,6 +342,17 @@ function PopoverContent({
       ? Math.min(Math.max(requestedWidth, minWidth), available)
       : requestedWidth;
 
+  /*
+   * The cap is what keeps a tall panel reachable. `place` clamps the panel
+   * inside the bounds, but a panel taller than the bounds cannot be clamped
+   * into them — it gets pinned to the top edge and the rest runs off the
+   * bottom of the screen, where there is no way to get at it. Capping the
+   * height first means the clamp always has a solution, and `scrollable`
+   * hands the overflow back to the finger.
+   */
+  const room = bounds.bottom - bounds.top;
+  const resolvedMaxHeight = maxHeight === undefined ? room : Math.min(maxHeight, room);
+
   const position =
     trigger && size
       ? place({ trigger, size, placement, align, offset, alignOffset, bounds })
@@ -434,6 +484,7 @@ function PopoverContent({
               top: position?.top ?? -9999,
               left: position?.left ?? -9999,
               maxWidth: bounds.right - bounds.left,
+              maxHeight: resolvedMaxHeight,
               width: resolvedWidth,
             }}
           >
@@ -441,12 +492,28 @@ function PopoverContent({
               accessibilityViewIsModal
               style={[panelStyle, style]}
               className={cn(
-                'gap-1.5 rounded-2xl border border-border bg-popover p-4 shadow-lg',
+                // `unstyled` keeps the clip and drops everything that paints,
+                // so a caller can put its own layer underneath the content.
+                unstyled
+                  ? 'overflow-hidden rounded-2xl'
+                  : 'rounded-2xl border border-border bg-popover p-4 shadow-lg',
+                // The gap belongs to whichever view actually holds the
+                // children — on the panel normally, on the scroller's content
+                // when there is one, since the scroller is then the panel's
+                // only child and a gap around it spaces nothing.
+                scrollable ? 'overflow-hidden' : 'gap-1.5',
                 className
               )}
               {...props}
             >
-              {textChildren(children)}
+              {background}
+              {scrollable ? (
+                <ScrollView bounces={false} showsVerticalScrollIndicator={false}>
+                  <View className="gap-1.5">{textChildren(children)}</View>
+                </ScrollView>
+              ) : (
+                textChildren(children)
+              )}
             </Animated.View>
           </Animated.View>
         </View>