@astryxdesign/core 0.5.2-canary.c9c8564 → 0.5.2-canary.e4f8e4e

package/src/Popover/Popover.tsx

@@ -4,8 +4,8 @@
 
 /**
  * @file Popover.tsx
- * @input Uses React, usePopover hook
- * @output Exports Popover component for click-triggered popovers
+ * @input Uses React layout measurement and the usePopover hook
+ * @output Exports Popover with viewport fitting and conditional overflow
  * @position Layer component; declarative wrapper around usePopover hook
  *
  * For hover-triggered overlays, use HoverCard instead.
@@ -20,6 +20,7 @@
 import React, {
   useCallback,
   useRef,
+  useState,
   type ReactElement,
   type ReactNode,
 } from 'react';
@@ -27,7 +28,7 @@ import {useIsomorphicLayoutEffect} from '../hooks/useIsomorphicLayoutEffect';
 import * as stylex from '@stylexjs/stylex';
 import {devWarn} from '../utils/devWarning';
 import type {BaseProps} from '../BaseProps';
-import {usePopover} from './usePopover';
+import {usePopoverInternal} from './usePopover';
 import type {LayerAlignment, LayerPlacement} from '../Layer/useLayer';
 import {layerAnimations} from '../Layer/layerAnimations.stylex';
 import {spacingVars} from '../theme/tokens.stylex';
@@ -38,6 +39,14 @@ import {InteractiveRoleContext} from '../InteractiveRoleContext/InteractiveRoleC
 // =============================================================================
 
 const BUTTON_SELECTOR = 'button, [role="button"]';
+const POPOVER_VIEWPORT_GUTTER = spacingVars['--spacing-4'];
+const POPOVER_MAX_INLINE_SIZE = `calc(100vi - max(${POPOVER_VIEWPORT_GUTTER}, env(safe-area-inset-left, 0px)) - max(${POPOVER_VIEWPORT_GUTTER}, env(safe-area-inset-right, 0px)))`;
+const POPOVER_MAX_INLINE_SIZE_FALLBACK = `calc(100vw - ${POPOVER_VIEWPORT_GUTTER} - ${POPOVER_VIEWPORT_GUTTER})`;
+const POPOVER_MAX_BLOCK_SIZE = `calc(100dvb - max(${POPOVER_VIEWPORT_GUTTER}, env(safe-area-inset-top, 0px)) - max(${POPOVER_VIEWPORT_GUTTER}, env(safe-area-inset-bottom, 0px)))`;
+const POPOVER_MAX_BLOCK_SIZE_FALLBACK = `calc(100vh - ${POPOVER_VIEWPORT_GUTTER} - ${POPOVER_VIEWPORT_GUTTER})`;
+const POPOVER_POSITION_AREA_MAX_INLINE_SIZE = `calc(100% - max(${POPOVER_VIEWPORT_GUTTER}, env(safe-area-inset-left, 0px), env(safe-area-inset-right, 0px)))`;
+const POPOVER_POSITION_AREA_MAX_INLINE_SIZE_FALLBACK = `calc(100% - ${POPOVER_VIEWPORT_GUTTER})`;
+const POPOVER_INLINE_EDGE_GUTTER = `max(${POPOVER_VIEWPORT_GUTTER}, env(safe-area-inset-left, 0px), env(safe-area-inset-right, 0px))`;
 
 /**
  * Find the trigger button inside a container element.
@@ -61,9 +70,9 @@ function findTriggerButton(el: HTMLElement): HTMLElement | null {
 export interface PopoverTriggerRenderProps {
   /** Ref callback — attach to the trigger element for anchor positioning. */
   ref: (el: HTMLElement | null) => void;
-  /** Toggle the popover open/closed. */
-  onClick: () => void;
-  /** ARIA attribute: indicates the element triggers a dialog. */
+  /** Toggle the popover open/closed. Pass the click event through so pointer and keyboard focus behavior can differ. */
+  onClick: (event?: {detail: number}) => void;
+  /** ARIA attribute: indicates the trigger opens a dialog-style popover. */
   'aria-haspopup': 'dialog';
   /** ARIA attribute: whether the popover is currently open. */
   'aria-expanded': boolean;
@@ -198,7 +207,9 @@ export interface PopoverProps extends Pick<
   closeButtonLabel?: string;
 
   /**
-   * Whether to auto-focus the first focusable element when the popover opens.
+   * Whether to move focus into the popover when it opens. Keyboard activation
+   * focuses the first content control; pointer activation focuses the labeled
+   * dialog container so an action does not appear preselected.
    * Set to `false` for inline showcases or documentation previews.
    * @default true
    */
@@ -241,6 +252,62 @@ const styles = stylex.create({
   anchorWrapper: {
     display: 'inline-flex',
   },
+  viewportFit: {
+    boxSizing: 'border-box',
+    maxBlockSize: stylex.firstThatWorks(
+      POPOVER_MAX_BLOCK_SIZE,
+      POPOVER_MAX_BLOCK_SIZE_FALLBACK,
+    ),
+  },
+  viewportAligned: {
+    maxInlineSize: stylex.firstThatWorks(
+      POPOVER_POSITION_AREA_MAX_INLINE_SIZE,
+      POPOVER_POSITION_AREA_MAX_INLINE_SIZE_FALLBACK,
+    ),
+  },
+  viewportStart: {
+    marginInlineEnd: POPOVER_INLINE_EDGE_GUTTER,
+  },
+  viewportEnd: {
+    marginInlineStart: POPOVER_INLINE_EDGE_GUTTER,
+  },
+  viewportBlockStart: {
+    marginBlockEnd: `max(${POPOVER_VIEWPORT_GUTTER}, env(safe-area-inset-bottom, 0px))`,
+  },
+  viewportBlockEnd: {
+    marginBlockStart: `max(${POPOVER_VIEWPORT_GUTTER}, env(safe-area-inset-top, 0px))`,
+  },
+  viewportCentered: {
+    marginInlineStart: POPOVER_INLINE_EDGE_GUTTER,
+    marginInlineEnd: POPOVER_INLINE_EDGE_GUTTER,
+    maxInlineSize: stylex.firstThatWorks(
+      POPOVER_MAX_INLINE_SIZE,
+      POPOVER_MAX_INLINE_SIZE_FALLBACK,
+    ),
+  },
+  viewportBlockCentered: {
+    marginBlockStart: `max(${POPOVER_VIEWPORT_GUTTER}, env(safe-area-inset-top, 0px))`,
+    marginBlockEnd: `max(${POPOVER_VIEWPORT_GUTTER}, env(safe-area-inset-bottom, 0px))`,
+    maxInlineSize: stylex.firstThatWorks(
+      POPOVER_MAX_INLINE_SIZE,
+      POPOVER_MAX_INLINE_SIZE_FALLBACK,
+    ),
+  },
+  surfaceViewportFit: {
+    boxSizing: 'border-box',
+    maxInlineSize: stylex.firstThatWorks(
+      POPOVER_MAX_INLINE_SIZE,
+      POPOVER_MAX_INLINE_SIZE_FALLBACK,
+    ),
+    maxBlockSize: stylex.firstThatWorks(
+      POPOVER_MAX_BLOCK_SIZE,
+      POPOVER_MAX_BLOCK_SIZE_FALLBACK,
+    ),
+  },
+  surfaceScrollable: {
+    overflow: 'auto',
+    overscrollBehavior: 'contain',
+  },
   // Content padding, applied to the popup surface so a theme's `padding`
   // replaces it instead of nesting inside it.
   contentPadding: {
@@ -252,8 +319,19 @@ const styles = stylex.create({
   customWidth: (width: string | number) => ({
     width: typeof width === 'number' ? `${width}px` : width,
   }),
-  matchTrigger: {
-    minWidth: 'anchor-size(width)',
+  matchTriggerAligned: {
+    minWidth: stylex.firstThatWorks(
+      `min(anchor-size(width), ${POPOVER_POSITION_AREA_MAX_INLINE_SIZE})`,
+      `min(anchor-size(width), ${POPOVER_POSITION_AREA_MAX_INLINE_SIZE_FALLBACK})`,
+      'anchor-size(width)',
+    ),
+  },
+  matchTriggerCentered: {
+    minWidth: stylex.firstThatWorks(
+      `min(anchor-size(width), ${POPOVER_MAX_INLINE_SIZE})`,
+      `min(anchor-size(width), ${POPOVER_MAX_INLINE_SIZE_FALLBACK})`,
+      'anchor-size(width)',
+    ),
   },
 });
 
@@ -320,6 +398,8 @@ export function Popover({
   'data-testid': testId,
 }: PopoverProps): ReactElement {
   const wrapperRef = useRef<HTMLDivElement>(null);
+  const measurementFrameRef = useRef<number | null>(null);
+  const [hasOverflow, setHasOverflow] = useState(false);
   const isControlled = isOpen !== undefined;
 
   const handlePopoverShow = useCallback(() => {
@@ -330,7 +410,7 @@ export function Popover({
     onOpenChange?.(false);
   }, [onOpenChange]);
 
-  const popover = usePopover({
+  const popover = usePopoverInternal({
     dialogLabel: label,
     role,
     isModal,
@@ -343,21 +423,113 @@ export function Popover({
     // it is the element the `popover` theme target has to sit on — a target on
     // the content div inside it styles a box that paints nothing.
     surfaceTarget: 'popover',
-    xstyle: [styles.contentPadding, xstyle],
+    xstyle: [
+      styles.contentPadding,
+      styles.surfaceViewportFit,
+      hasOverflow && styles.surfaceScrollable,
+      xstyle,
+    ],
     className,
     style,
     onShow: handlePopoverShow,
     onHide: handlePopoverHide,
   });
 
-  // Shared handler for click events on the trigger button.
-  const handleTriggerClick = useCallback(() => {
-    if (!isEnabled) {
+  const measureOverflow = useCallback(() => {
+    const surface = popover.contentRef.current;
+    if (!surface) {
+      return;
+    }
+    const nextHasOverflow =
+      surface.scrollHeight > surface.clientHeight + 1 ||
+      surface.scrollWidth > surface.clientWidth + 1;
+    // eslint-disable-next-line @eslint-react/set-state-in-effect -- DOM overflow measurement controls whether this surface becomes a scroll container
+    setHasOverflow(current =>
+      current === nextHasOverflow ? current : nextHasOverflow,
+    );
+  }, [popover.contentRef]);
+
+  const scheduleOverflowMeasurement = useCallback(() => {
+    if (measurementFrameRef.current != null) {
+      return;
+    }
+    measurementFrameRef.current = window.requestAnimationFrame(() => {
+      measurementFrameRef.current = null;
+      measureOverflow();
+    });
+  }, [measureOverflow]);
+
+  useIsomorphicLayoutEffect(() => {
+    if (!popover.isOpen) {
+      return;
+    }
+    const surface = popover.contentRef.current;
+    if (!surface) {
+      return;
+    }
+    measureOverflow();
+    const resizeObserver =
+      typeof ResizeObserver === 'undefined'
+        ? null
+        : new ResizeObserver(scheduleOverflowMeasurement);
+    const mutationObserver =
+      typeof MutationObserver === 'undefined'
+        ? null
+        : new MutationObserver(scheduleOverflowMeasurement);
+    resizeObserver?.observe(surface);
+    mutationObserver?.observe(surface, {
+      childList: true,
+      characterData: true,
+      subtree: true,
+    });
+    surface.addEventListener('load', scheduleOverflowMeasurement, true);
+    window.addEventListener('resize', scheduleOverflowMeasurement);
+    window.visualViewport?.addEventListener(
+      'resize',
+      scheduleOverflowMeasurement,
+    );
+    return () => {
+      resizeObserver?.disconnect();
+      mutationObserver?.disconnect();
+      surface.removeEventListener('load', scheduleOverflowMeasurement, true);
+      window.removeEventListener('resize', scheduleOverflowMeasurement);
+      window.visualViewport?.removeEventListener(
+        'resize',
+        scheduleOverflowMeasurement,
+      );
+      if (measurementFrameRef.current != null) {
+        window.cancelAnimationFrame(measurementFrameRef.current);
+        measurementFrameRef.current = null;
+      }
+    };
+  }, [measureOverflow, popover.isOpen, scheduleOverflowMeasurement]);
+
+  useIsomorphicLayoutEffect(() => {
+    if (!popover.isOpen) {
       return;
     }
-    // `toggle` absorbs a click that belongs to its own light dismiss.
-    popover.toggle();
-  }, [isEnabled, popover]);
+    scheduleOverflowMeasurement();
+  }, [content, popover.isOpen, scheduleOverflowMeasurement]);
+
+  // Shared handler for click events on the trigger button.
+  const handleTriggerClick = useCallback(
+    (event?: {detail: number}) => {
+      if (!isEnabled) {
+        return;
+      }
+      // Pointer/touch activation should not make the first action look
+      // preselected. Keep focus inside the modal dialog by focusing its
+      // labeled container; keyboard and AT activation still focus the first
+      // content control and expose the expected focus ring.
+      popover.toggleWithOptions({
+        focusTarget:
+          role === 'dialog' && event != null && event.detail > 0
+            ? 'container'
+            : 'first',
+      });
+    },
+    [isEnabled, popover, role],
+  );
 
   // Shared handler for keydown events on role="button" elements.
   // Native <button> synthesizes click on Enter/Space, but role="button"
@@ -503,7 +675,27 @@ export function Popover({
   }, [isOpen, isControlled, popover]);
 
   // Determine popover xstyle
-  const popoverXstyle = width ? styles.customWidth(width) : styles.matchTrigger;
+  const popoverSizeXstyle = width
+    ? styles.customWidth(width)
+    : alignment === 'center'
+      ? styles.matchTriggerCentered
+      : styles.matchTriggerAligned;
+  const isSidePlacement = placement === 'start' || placement === 'end';
+  const popoverViewportXstyle =
+    alignment === 'center'
+      ? isSidePlacement
+        ? styles.viewportBlockCentered
+        : styles.viewportCentered
+      : [
+          styles.viewportAligned,
+          isSidePlacement
+            ? alignment === 'start'
+              ? styles.viewportBlockStart
+              : styles.viewportBlockEnd
+            : alignment === 'start'
+              ? styles.viewportStart
+              : styles.viewportEnd,
+        ];
 
   // Sibling mode: render only the popover (no wrapper needed)
   if (anchorRef && children == null) {
@@ -513,7 +705,12 @@ export function Popover({
           placement,
           alignment,
           offset: spacingVars['--spacing-1'],
-          xstyle: [popoverXstyle, layerAnimations[placement]],
+          xstyle: [
+            styles.viewportFit,
+            popoverViewportXstyle,
+            popoverSizeXstyle,
+            layerAnimations[placement],
+          ],
         })}
       </>
     );
@@ -538,7 +735,12 @@ export function Popover({
           placement,
           alignment,
           offset: spacingVars['--spacing-1'],
-          xstyle: [popoverXstyle, layerAnimations[placement]],
+          xstyle: [
+            styles.viewportFit,
+            popoverViewportXstyle,
+            popoverSizeXstyle,
+            layerAnimations[placement],
+          ],
         })}
       </>
     );
@@ -556,7 +758,12 @@ export function Popover({
         placement,
         alignment,
         offset: spacingVars['--spacing-1'],
-        xstyle: [popoverXstyle, layerAnimations[placement]],
+        xstyle: [
+          styles.viewportFit,
+          popoverViewportXstyle,
+          popoverSizeXstyle,
+          layerAnimations[placement],
+        ],
       })}
     </>
   );

package/src/Popover/usePopover.tsx

@@ -28,6 +28,7 @@ import {
   shadowVars,
 } from '../theme/tokens.stylex';
 import {Button} from '../Button';
+import {FOCUSABLE_SELECTOR} from '../hooks/focusableSelector';
 import {rtlStyles} from '../utils';
 import {useTranslator} from '../i18n';
 import {useDevWarning} from '../hooks/useDevWarning';
@@ -35,6 +36,29 @@ import {mergeProps} from '../utils/mergeProps';
 import {themeProps} from '../utils/themeProps';
 import {stableClassName} from '../naming';
 
+const FALLBACK_CLOSE_SELECTOR = '[data-astryx-popover-fallback-close]';
+
+function attemptFocus(element: HTMLElement): boolean {
+  try {
+    element.focus();
+  } catch {
+    // Ignore non-focusable elements; the caller will try the next target.
+  }
+  return document.activeElement === element;
+}
+
+function focusFirstContentControl(container: HTMLElement): boolean {
+  const focusable = Array.from(
+    container.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTOR),
+  ).filter(element => element.closest(FALLBACK_CLOSE_SELECTOR) == null);
+  for (const element of focusable) {
+    if (attemptFocus(element)) {
+      return true;
+    }
+  }
+  return false;
+}
+
 const styles = stylex.create({
   // Default popover surface — background, radius, shadow.
   // Applied automatically unless hasSurface is false.
@@ -48,6 +72,11 @@ const styles = stylex.create({
   // Focus trap container
   contentWrapper: {
     position: 'relative',
+    // Pointer-open dialog popovers park focus on this wrapper so the first
+    // action does not look selected. The wrapper itself is not an action and
+    // should not receive the browser's default focus ring; interactive
+    // descendants retain their normal focus-visible treatment.
+    outline: 'none',
   },
   // Hidden close button wrapper - sr-only until focused, then positioned below
   // popover. Inline-axis centering (+ the translateY(100%) that drops it below
@@ -296,6 +325,10 @@ export interface UsePopoverReturn {
 
 interface InternalUsePopoverReturn extends UsePopoverReturn {
   wasJustDismissed: () => boolean;
+  toggleWithOptions: (options?: {
+    skipAutoFocus?: boolean;
+    focusTarget?: 'first' | 'container';
+  }) => void;
 }
 
 /**
@@ -368,6 +401,7 @@ function usePopoverImplementation(
 
   // Track whether to skip auto-focus for the current open event
   const skipAutoFocusRef = useRef(false);
+  const focusTargetRef = useRef<'first' | 'container'>('first');
 
   // Core layer for popover positioning
   const layer = useLayerInternal({
@@ -385,19 +419,44 @@ function usePopoverImplementation(
     onEscape: hasEscapeDismiss || hasLightDismiss ? layer.hide : undefined,
   });
 
+  const focusInitialTarget = useCallback(() => {
+    const container = contentRef.current;
+    if (!container) {
+      return;
+    }
+    if (focusFirstContentControl(container)) {
+      return;
+    }
+    if (role === 'dialog') {
+      attemptFocus(container);
+      return;
+    }
+    focusFirst();
+  }, [contentRef, focusFirst, role]);
+
   // Auto-focus first element when popover opens (unless skipped)
   useEffect(() => {
     if (layer.isOpen && hasAutoFocus && !skipAutoFocusRef.current) {
       // Use requestAnimationFrame to ensure DOM is ready
       requestAnimationFrame(() => {
-        focusFirst();
+        const container = contentRef.current;
+        if (
+          focusTargetRef.current === 'container' &&
+          role === 'dialog' &&
+          container
+        ) {
+          attemptFocus(container);
+        } else {
+          focusInitialTarget();
+        }
       });
     }
-    // Reset the skip flag after the effect runs
+    // Reset per-open focus preferences after the popover closes.
     if (!layer.isOpen) {
       skipAutoFocusRef.current = false;
+      focusTargetRef.current = 'first';
     }
-  }, [layer.isOpen, hasAutoFocus, focusFirst]);
+  }, [contentRef, layer.isOpen, hasAutoFocus, focusInitialTarget, role]);
 
   // Combined ref for trigger element (layer anchor + our ref)
   const triggerRef = useCallback(
@@ -410,24 +469,35 @@ function usePopoverImplementation(
 
   // Show function with optional skipAutoFocus
   const show = useCallback(
-    (showOptions?: {skipAutoFocus?: boolean}) => {
+    (showOptions?: {
+      skipAutoFocus?: boolean;
+      focusTarget?: 'first' | 'container';
+    }) => {
       skipAutoFocusRef.current = showOptions?.skipAutoFocus ?? false;
+      focusTargetRef.current = showOptions?.focusTarget ?? 'first';
       layer.show();
     },
     [layer],
   );
 
   // Toggle function
-  const toggle = useCallback(() => {
-    if (layer.wasJustDismissed()) {
-      return;
-    }
-    if (layer.isOpen) {
-      layer.hide();
-    } else {
-      show();
-    }
-  }, [layer, show]);
+  const toggleWithOptions = useCallback(
+    (showOptions?: {
+      skipAutoFocus?: boolean;
+      focusTarget?: 'first' | 'container';
+    }) => {
+      if (layer.wasJustDismissed()) {
+        return;
+      }
+      if (layer.isOpen) {
+        layer.hide();
+      } else {
+        show(showOptions);
+      }
+    },
+    [layer, show],
+  );
+  const toggle = useCallback(() => toggleWithOptions(), [toggleWithOptions]);
 
   // ARIA attributes for the trigger
   const triggerProps = {
@@ -465,6 +535,7 @@ function usePopoverImplementation(
             role={role === 'dialog' ? 'dialog' : undefined}
             aria-modal={role === 'dialog' && isModal ? true : undefined}
             aria-label={role === 'dialog' ? dialogLabel : undefined}
+            tabIndex={role === 'dialog' ? -1 : undefined}
             {...mergeProps(
               {...surfaceProps, className: surfaceClassName},
               stylex.props(
@@ -478,6 +549,7 @@ function usePopoverImplementation(
             {children}
             {hasCloseButton && (
               <div
+                data-astryx-popover-fallback-close=""
                 {...stylex.props(
                   styles.closeButtonWrapper,
                   rtlStyles.centerInline('100%'),
@@ -517,6 +589,7 @@ function usePopoverImplementation(
     show,
     hide: layer.hide,
     toggle,
+    toggleWithOptions,
     wasJustDismissed: layer.wasJustDismissed,
     isOpen: layer.isOpen,
     id: layer.id,
@@ -526,7 +599,11 @@ function usePopoverImplementation(
 }
 
 export function usePopover(options: UsePopoverOptions = {}): UsePopoverReturn {
-  const {wasJustDismissed: _, ...popover} = usePopoverImplementation(options);
+  const {
+    wasJustDismissed: _,
+    toggleWithOptions: __,
+    ...popover
+  } = usePopoverImplementation(options);
   return popover;
 }