@astryxdesign/core 0.2.0-canary.ea693ac → 0.2.0-canary.fc53ff7

package/dist/hooks/useContainerReveal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useContainerReveal.d.ts","sourceRoot":"","sources":["../../src/hooks/useContainerReveal.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAsB,KAAK,aAAa,EAAC,MAAM,OAAO,CAAC;AA0C9D,MAAM,WAAW,yBAAyB;IACxC;;;;;OAKG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,oBAAoB;IACnC;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED,MAAM,WAAW,wBAAwB;IACvC,4EAA4E;IAC5E,iBAAiB,EAAE,MAAM;QAAC,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,aAAa,CAAA;KAAC,CAAC;IACrE,mDAAmD;IACnD,qBAAqB,EAAE,CACrB,OAAO,CAAC,EAAE,oBAAoB,KAC3B;QAAC,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,aAAa,CAAA;KAAC,CAAC;CAClD;AAID;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,GAAE,yBAA8B,GACtC,wBAAwB,CAiD1B"}

package/dist/hooks/useContainerReveal.js

@@ -0,0 +1,123 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useContainerReveal.ts
+ * @input Uses React, the generated marker pool, useDevWarning
+ * @output Exports useContainerReveal — a headless hover/focus reveal primitive
+ * @position Core hook. Consumed by any component that reveals (or conceals)
+ *   content when its container is hovered or focused — e.g. Thumbnail's remove
+ *   button, TreeList row actions.
+ *
+ * Gives a container a scoped hover/focus-within trigger that reveals or
+ * conceals content inside it, entirely in CSS (no hover state in JS, no
+ * re-render on hover). The caller authors NO StyleX: the hook hands out a
+ * marker + matching reveal styles from a pre-compiled pool.
+ *
+ * ACCESSIBILITY (WCAG 2.2 by construction):
+ * - Revealed content is visually hidden at rest via the clip recipe, so it
+ *   stays in the accessibility tree and tab order — never display:none.
+ * - Keyboard: revealed on :focus-within, so tabbing in shows it.
+ * - Touch: always visible on coarse pointers; never gated behind hover.
+ * - Concealed (inverted) content is a mouse-only visual swap: it ignores
+ *   :focus-within (a keyboard user must never watch content vanish) and stays
+ *   visible on touch and in the a11y tree.
+ * - Motion: honors prefers-reduced-motion.
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/hooks/index.ts (export)
+ * - containerReveal.pool.stylex.ts (if the slot shape changes)
+ */
+import { useState, useEffect } from 'react';
+import * as stylex from '@stylexjs/stylex';
+import { POOL, POOL_SIZE } from "./containerReveal.pool.stylex.js";
+import { useDevWarning } from "./useDevWarning.js";
+
+// Module-level free-list. Each mounted, enabled useContainerReveal claims a
+// distinct pool slot so that any two CONCURRENTLY mounted containers — in
+// particular a nested container inside another's revealed content — get
+// different markers and cannot leak hover/focus into one another. Slots are
+// returned on unmount. Sibling containers that would only ever collide when
+// the pool is exhausted are harmless (a sibling is never an ancestor), so the
+// pool only needs to cover the number of concurrently mounted containers, not
+// instances over time.
+const claimed = new Array(POOL_SIZE).fill(false);
+function claimSlot() {
+  for (let i = 0; i < POOL_SIZE; i++) {
+    if (!claimed[i]) {
+      claimed[i] = true;
+      return {
+        index: i,
+        isExhausted: false
+      };
+    }
+  }
+  // Exhausted: fall back to slot 0. Safe for siblings (a sibling is never an
+  // ancestor); only nesting deeper than POOL_SIZE could reintroduce a leak.
+  // Surfaced via useDevWarning so the pool can be grown.
+  return {
+    index: 0,
+    isExhausted: true
+  };
+}
+function releaseSlot(index, isExhausted) {
+  // A fallback claim never owned the slot exclusively; leave it as-is.
+  if (!isExhausted) {
+    claimed[index] = false;
+  }
+}
+const EMPTY = Object.freeze({});
+
+/**
+ * Scoped, CSS-only hover/focus reveal for content inside a container.
+ *
+ * @example
+ * ```tsx
+ * const {getContainerProps, getContentRevealProps} = useContainerReveal({
+ *   isEnabled: revealOn === 'hover',
+ * });
+ *
+ * <div {...mergeProps(getContainerProps(), stylex.props(styles.row))}>
+ *   {label}
+ *   <span {...mergeProps(getContentRevealProps(), stylex.props(styles.actions))}>
+ *     {actions}
+ *   </span>
+ * </div>
+ * ```
+ */
+export function useContainerReveal(options = {}) {
+  const {
+    isEnabled = true
+  } = options;
+
+  // Claim a slot for this container's lifetime. Assigned in the initializer
+  // (not the render body) and released on unmount so the free-list stays
+  // effect-scoped and StrictMode-safe.
+  const [claim] = useState(() => isEnabled ? claimSlot() : null);
+  useEffect(() => {
+    if (claim == null) {
+      return;
+    }
+    return () => releaseSlot(claim.index, claim.isExhausted);
+  }, [claim]);
+  useDevWarning('useContainerReveal', `More than ${POOL_SIZE} reveal containers are mounted at once; nested ` + `containers beyond the pool may share a marker. Add markers to ` + `containerReveal.pool.stylex.ts and raise POOL_SIZE.`, claim?.isExhausted ?? false);
+  if (claim == null) {
+    return {
+      getContainerProps: () => EMPTY,
+      getContentRevealProps: () => EMPTY
+    };
+  }
+  const slot = POOL[claim.index];
+  return {
+    getContainerProps: () => stylex.props(slot.marker),
+    getContentRevealProps: (contentOptions = {}) => {
+      const {
+        isRevealInverted = false,
+        isLayoutPreserved = false
+      } = contentOptions;
+      const style = isRevealInverted ? isLayoutPreserved ? slot.concealLayoutPreserved : slot.conceal : isLayoutPreserved ? slot.revealLayoutPreserved : slot.reveal;
+      return stylex.props(style);
+    }
+  };
+}

package/dist/hooks/useInputStatusIcon.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useInputStatusIcon.d.ts","sourceRoot":"","sources":["../../src/hooks/useInputStatusIcon.tsx"],"names":[],"mappings":"AAmCA,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,OAAO,CAAC;AAErC,OAAO,EAAsB,KAAK,QAAQ,EAAC,MAAM,SAAS,CAAC;AAC3D,OAAO,KAAK,EAAC,kBAAkB,EAAC,MAAM,4BAA4B,CAAC;AACnE,OAAO,KAAK,EAAC,WAAW,EAAkB,MAAM,gBAAgB,CAAC;AAsDjE,MAAM,WAAW,yBAAyB;IACxC,2DAA2D;IAC3D,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,yDAAyD;IACzD,aAAa,CAAC,EAAE,kBAAkB,CAAC;IACnC,+EAA+E;IAC/E,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,+CAA+C;IAC/C,IAAI,CAAC,EAAE,QAAQ,CAAC;CACjB;AAED,MAAM,WAAW,wBAAwB;IACvC;;;;;OAKG;IACH,UAAU,EAAE,SAAS,CAAC;IACtB;;;;;;;OAOG;IACH,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;CACjC;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,EACjC,MAAM,EACN,aAA0B,EAC1B,SAAiB,EACjB,IAAW,GACZ,EAAE,yBAAyB,GAAG,wBAAwB,CA2FtD"}
+{"version":3,"file":"useInputStatusIcon.d.ts","sourceRoot":"","sources":["../../src/hooks/useInputStatusIcon.tsx"],"names":[],"mappings":"AAmCA,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,OAAO,CAAC;AAErC,OAAO,EAAsB,KAAK,QAAQ,EAAC,MAAM,SAAS,CAAC;AAC3D,OAAO,KAAK,EAAC,kBAAkB,EAAC,MAAM,4BAA4B,CAAC;AACnE,OAAO,KAAK,EAAC,WAAW,EAAkB,MAAM,gBAAgB,CAAC;AAuDjE,MAAM,WAAW,yBAAyB;IACxC,2DAA2D;IAC3D,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,yDAAyD;IACzD,aAAa,CAAC,EAAE,kBAAkB,CAAC;IACnC,+EAA+E;IAC/E,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,+CAA+C;IAC/C,IAAI,CAAC,EAAE,QAAQ,CAAC;CACjB;AAED,MAAM,WAAW,wBAAwB;IACvC;;;;;OAKG;IACH,UAAU,EAAE,SAAS,CAAC;IACtB;;;;;;;OAOG;IACH,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;CACjC;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,EACjC,MAAM,EACN,aAA0B,EAC1B,SAAiB,EACjB,IAAW,GACZ,EAAE,yBAAyB,GAAG,wBAAwB,CAqGtD"}

package/dist/hooks/useInputStatusIcon.js

@@ -38,6 +38,7 @@ import { useTooltip } from "../Tooltip/index.js";
 import { useTranslator } from "../i18n/index.js";
 import "../theme/tokens.stylex.js";
 import { colorVars, radiusVars } from "../theme/tokens.stylex.js";
+import { themeProps } from "../utils/themeProps.js";
 
 /**
  * Maps each status type to its glyph. Shared so every input shows the same icon
@@ -128,6 +129,16 @@ export function useInputStatusIcon({
     icon: STATUS_ICON[status.type],
     size: size,
     color: status.type
+    // Stable theme target on the status glyph itself, so a theme can restyle
+    // just this icon (color, size) — and each status — via `defineTheme`.
+    // Same-element rules in @layer astryx-theme win over the icon's own base
+    // width/height/fontSize, which a field-level target could not reach.
+    // Shared by the attached and tooltip variants across all bordered inputs.
+    ,
+    ...themeProps('input-status-icon', {
+      size,
+      status: status.type
+    })
   });
 
   // Attached (and tooltip-without-message) variants: plain, non-interactive

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/core",
-  "version": "0.2.0-canary.ea693ac",
+  "version": "0.2.0-canary.fc53ff7",
   "displayName": "Astryx Core",
   "description": "The component library. Accessible, themeable React components with built-in spacing, dark mode, and StyleX styling.",
   "author": "Meta Open Source",

package/src/DropdownMenu/DropdownMenuSubMenu.test.tsx

@@ -8,7 +8,7 @@
 
 import {describe, it, expect, vi, beforeEach} from 'vitest';
 import {useState} from 'react';
-import {render, screen, waitFor} from '@testing-library/react';
+import {render, screen, waitFor, fireEvent} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {DropdownMenu} from './DropdownMenu';
 import {DropdownMenuItem} from './DropdownMenuItem';
@@ -510,6 +510,34 @@ describe('DropdownMenuSubMenu accessibility (WCAG 2.2 / APG)', () => {
     expect(onPick).toHaveBeenCalledWith('data');
   });
 
+  // Regression: hovering the submenu trigger while a sibling item still holds
+  // focus must move the single focus-driven highlight onto the trigger — not
+  // leave two items highlighted at once (the trigger via :hover, the sibling
+  // via :focus). Mirrors DropdownMenuItem's hover-focus behavior.
+  it('moves focus to the submenu trigger on hover, keeping a single highlight', async () => {
+    const user = userEvent.setup();
+    render(<MoveMenu />);
+    await user.click(screen.getByRole('button', {name: /Actions/}));
+
+    const rename = screen.getByRole('menuitem', {
+      name: 'Rename',
+      hidden: true,
+    });
+    const trigger = screen.getByRole('menuitem', {
+      name: /Move to/,
+      hidden: true,
+    });
+
+    rename.focus();
+    expect(rename).toHaveFocus();
+
+    // A mouse hover over the submenu trigger moves focus onto it, so the single
+    // focus-driven highlight follows the pointer instead of leaving two.
+    fireEvent.pointerMove(trigger, {pointerType: 'mouse'});
+    expect(trigger).toHaveFocus();
+    expect(rename).not.toHaveFocus();
+  });
+
   // 1.4.13 Content on Hover or Focus: the flyout stays open while the pointer
   // is over it (moving onto the flyout must not dismiss it).
   it('keeps the flyout open while the pointer is over it', async () => {

package/src/DropdownMenu/DropdownMenuSubMenu.tsx

@@ -44,6 +44,7 @@ import React, {
   useMemo,
   useRef,
   useState,
+  type PointerEvent,
   type ReactNode,
 } from 'react';
 import * as stylex from '@stylexjs/stylex';
@@ -78,6 +79,7 @@ import {
   useDropdownMenuContext,
   type DropdownMenuContextValue,
 } from './DropdownMenuContext';
+import {focusMenuItemOnHover} from './menuItemHover';
 
 const triggerStyles = stylex.create({
   root: {
@@ -93,11 +95,6 @@ const triggerStyles = stylex.create({
       default: 'transparent',
       ':focus': colorVars['--color-overlay-hover'],
     },
-    ':hover': {
-      '@media (hover: hover)': {
-        backgroundColor: colorVars['--color-overlay-hover'],
-      },
-    },
     border: 'none',
     cursor: 'pointer',
     textAlign: 'start',
@@ -393,6 +390,16 @@ export function DropdownMenuSubMenu(
     [isDisabled, open],
   );
 
+  // Move the single focus-driven highlight onto the trigger as the pointer
+  // enters it, so a sibling item that still holds focus doesn't stay
+  // highlighted alongside the hovered trigger. This is separate from the
+  // hover-open intent (onMouseEnter/onMouseLeave) — the flyout still opens on
+  // the hover delay; this only keeps the highlight single.
+  const handlePointerMove = useCallback(
+    (e: PointerEvent<HTMLElement>) => focusMenuItemOnHover(e, isDisabled),
+    [isDisabled],
+  );
+
   // Enter/Space activate the focused row; typeahead jumps by first character;
   // the close key (Left, or Right in RTL) returns focus to the trigger;
   // arrows/Home/End defer to useListFocus (RTL-aware).
@@ -494,6 +501,7 @@ export function DropdownMenuSubMenu(
         data-testid={testId}
         onMouseEnter={triggerProps.onMouseEnter}
         onMouseLeave={triggerProps.onMouseLeave}
+        onPointerMove={handlePointerMove}
         startContent={
           icon
             ? renderIconSlot(icon, {size: 'sm', color: 'secondary'})

package/src/DropdownMenu/menuItemHover.ts

@@ -16,6 +16,7 @@
  * - /packages/core/src/DropdownMenu/DropdownMenuItem.tsx
  * - /packages/core/src/DropdownMenu/DropdownMenuCheckboxItem.tsx
  * - /packages/core/src/DropdownMenu/DropdownMenuRadioItem.tsx
+ * - /packages/core/src/DropdownMenu/DropdownMenuSubMenu.tsx
  */
 
 import type {PointerEvent} from 'react';

package/src/Field/Field.doc.mjs

@@ -30,6 +30,10 @@ export const docs = {
       {className: 'astryx-field', visualProps: ['layout']},
       {className: 'astryx-field-label'},
       {className: 'astryx-field-status', visualProps: ['type', 'variant']},
+      {
+        className: 'astryx-input-status-icon',
+        visualProps: ['size', 'status'],
+      },
     ],
     vars: [
       {name: '--_field-radius', description: 'Border radius of input fields', default: 'var(--radius-element)', private: true},

package/src/FieldStatus/FieldStatus.doc.mjs

@@ -12,6 +12,7 @@ export const docs = {
   theming: {
     targets: [
       {className: 'astryx-field-status', visualProps: ['type', 'variant']},
+      {className: 'astryx-field-status-icon', visualProps: ['type']},
     ],
   },
   props: [

package/src/FieldStatus/FieldStatus.test.tsx

@@ -372,6 +372,67 @@ describe('FieldStatus', () => {
     });
   });
 
+  describe('field-status-icon theme target', () => {
+    // The stable theme target lands on the detached message box's leading glyph
+    // itself, so a theme can restyle (e.g. resize) just this icon via
+    // `defineTheme`. It reflects the status type as a data attribute so themes
+    // can target per status, mirroring the parent astryx-field-status.
+    const getStatusIcon = (root: HTMLElement): HTMLElement => {
+      const icon = root.querySelector('.astryx-field-status-icon');
+      if (icon == null) {
+        throw new Error('status icon not found');
+      }
+      return icon as HTMLElement;
+    };
+
+    it('renders the target on the detached leading icon', () => {
+      render(
+        <FieldStatus
+          type="error"
+          message="msg"
+          variant="detached"
+          data-testid="fs"
+        />,
+      );
+      const icon = getStatusIcon(screen.getByTestId('fs'));
+      expect(icon).toHaveClass('astryx-field-status-icon');
+      expect(icon).toHaveClass('astryx-icon');
+      expect(icon).toHaveAttribute('data-type', 'error');
+    });
+
+    it('reflects the status type per status', () => {
+      for (const type of ['error', 'warning', 'success'] as const) {
+        const {unmount} = render(
+          <FieldStatus
+            type={type}
+            message="msg"
+            variant="detached"
+            data-testid="fs"
+          />,
+        );
+        expect(getStatusIcon(screen.getByTestId('fs'))).toHaveAttribute(
+          'data-type',
+          type,
+        );
+        unmount();
+      }
+    });
+
+    it('does not render the target for the attached variant', () => {
+      render(
+        <FieldStatus
+          type="error"
+          message="msg"
+          variant="attached"
+          data-testid="fs"
+        />,
+      );
+      expect(
+        screen.getByTestId('fs').querySelector('.astryx-field-status-icon'),
+      ).toBeNull();
+    });
+  });
+
   describe('edge cases', () => {
     it('renders an empty message without crashing', () => {
       render(<FieldStatus type="error" message="" data-testid="fs" />);

package/src/FieldStatus/FieldStatus.tsx

@@ -56,8 +56,8 @@ const styles = stylex.create({
     paddingBlockStart: `calc(${spacingVars['--spacing-1-5']} + ${spacingVars['--spacing-2']})`,
     paddingBlockEnd: spacingVars['--spacing-2'],
     paddingInline: spacingVars['--spacing-2'],
-    borderBottomLeftRadius: radiusVars['--radius-element'],
-    borderBottomRightRadius: radiusVars['--radius-element'],
+    borderEndStartRadius: radiusVars['--radius-element'],
+    borderEndEndRadius: radiusVars['--radius-element'],
   },
   detached: {
     marginTop: spacingVars['--spacing-1'],
@@ -216,7 +216,18 @@ export function FieldStatus({
       {variant === 'detached' ? (
         <span {...stylex.props(styles.detachedContent)}>
           <span {...stylex.props(styles.detachedIcon)}>
-            <Icon icon={statusIconMap[type]} size="sm" color="inherit" />
+            <Icon
+              icon={statusIconMap[type]}
+              size="sm"
+              color="inherit"
+              // Stable theme target on the detached message box's leading glyph
+              // itself, so a theme can restyle just this icon (color, size) —
+              // and each status — via `defineTheme`. Same-element rules in
+              // @layer astryx-theme win over the icon's own base
+              // width/height/fontSize, which a field-level target could not
+              // reach.
+              {...themeProps('field-status-icon', {type})}
+            />
           </span>
           <span>{message}</span>
         </span>

package/src/MultiSelector/MultiSelector.tsx

@@ -119,11 +119,12 @@ const styles = stylex.create({
     lineHeight: 'inherit',
     color: 'inherit',
     cursor: 'pointer',
-    outline: {
-      default: 'none',
-      ':focus-visible': `${borderVars['--border-width']} solid ${colorVars['--color-accent']}`,
-    },
-    outlineOffset: '0',
+    // The wrapper (inputWrapperStyles.base) renders the focus ring via
+    // :focus-within when this button is focused, matching
+    // TextInput/NumberInput/Selector. The button must not draw its own
+    // :focus-visible outline or the two stack into a doubled ring over the
+    // trigger.
+    outline: 'none',
     borderRadius: radiusVars['--radius-element'],
   },
   triggerPlaceholder: {

package/src/Thumbnail/Thumbnail.tsx

@@ -39,11 +39,11 @@ import {Skeleton} from '../Skeleton';
 import {Spinner} from '../Spinner';
 import {Tooltip} from '../Tooltip/Tooltip';
 import {useDevWarning} from '../hooks/useDevWarning';
+import {useContainerReveal} from '../hooks/useContainerReveal';
 import type {BaseProps} from '../BaseProps';
 import {mergeProps} from '../utils';
 import {themeProps} from '../utils/themeProps';
 import {useTranslator} from '../i18n';
-import {thumbnailScope} from './thumbnail.markers.stylex';
 
 export interface ThumbnailProps extends BaseProps<HTMLDivElement> {
   /** Ref forwarded to the root element */
@@ -236,28 +236,6 @@ const styles = stylex.create({
     zIndex: 1,
     lineHeight: 0,
   },
-  // showRemoveOn="hover": the remove button is hidden at rest and revealed
-  // when the thumbnail is hovered or when focus enters it (keyboard). Only
-  // opacity is animated — the button stays mounted and focusable so tabbing
-  // to it triggers the :focus-within reveal. Any touch-capable device (incl.
-  // hybrid laptops that also report hover) keeps the button visible so the
-  // remove path is never gated behind an unavailable hover.
-  removeOnHover: {
-    opacity: {
-      default: 0,
-      [stylex.when.ancestor(':hover', thumbnailScope)]: {
-        '@media (hover: hover)': 1,
-      },
-      [stylex.when.ancestor(':focus-within', thumbnailScope)]: 1,
-      '@media (any-pointer: coarse)': 1,
-    },
-    transitionProperty: 'opacity',
-    transitionDuration: {
-      default: durationVars['--duration-fast'],
-      '@media (prefers-reduced-motion: reduce)': '0s',
-    },
-    transitionTimingFunction: easeVars['--ease-standard'],
-  },
 });
 
 // =============================================================================
@@ -326,6 +304,9 @@ export function Thumbnail({
   const isInteractive = onClick != null && !isDisabled && !isLoading;
   const hasRemove = onRemove != null && !isDisabled;
   const isHoverReveal = hasRemove && showRemoveOn === 'hover';
+  const {getContainerProps, getContentRevealProps} = useContainerReveal({
+    isEnabled: isHoverReveal,
+  });
   const accessibleName =
     label && alt
       ? `${label} — ${alt}`
@@ -377,9 +358,12 @@ export function Thumbnail({
 
   const removeButtonEl = hasRemove ? (
     <div
-      {...stylex.props(
-        styles.removeSlot,
-        isHoverReveal && styles.removeOnHover,
+      {...mergeProps(
+        stylex.props(styles.removeSlot),
+        // The remove button is absolutely positioned in the corner, so it is
+        // already out of flow — an opacity-only reveal (layout preserved)
+        // matches its overlay placement instead of the clip recipe.
+        isHoverReveal ? getContentRevealProps({isLayoutPreserved: true}) : {},
       )}>
       <Button
         icon={<Icon icon="close" size="xsm" />}
@@ -410,12 +394,14 @@ export function Thumbnail({
       )}
       {...props}>
       <div
-        {...stylex.props(
-          styles.imageContainer,
-          isHoverReveal && thumbnailScope,
-          isInteractive && styles.interactive,
-          isInteractive && styles.overlay,
-          isInteractive && styles.hoverOnPointer,
+        {...mergeProps(
+          stylex.props(
+            styles.imageContainer,
+            isInteractive && styles.interactive,
+            isInteractive && styles.overlay,
+            isInteractive && styles.hoverOnPointer,
+          ),
+          isHoverReveal ? getContainerProps() : {},
         )}>
         {isInteractive ? (
           <button

package/src/TopNav/TopNavMegaMenu.tsx

@@ -123,6 +123,18 @@ const styles = stylex.create({
       transform: 'translateY(-4px)',
     },
   },
+  // Clamp the anchored layer to the space available below the nav so a tall
+  // menu never runs off the bottom of the viewport. The layer is positioned
+  // with position-area: self-block-end, so its containing block spans from
+  // the nav's block-end to the viewport edge — 100% is exactly that space.
+  // The layer is a flex column so panelContainer can shrink and scroll its
+  // own content, keeping the surface radius/shadow static at the edges.
+  // Internal scroll is a stopgap until the mobile bottom-sheet lands.
+  panelViewportFit: {
+    display: 'flex',
+    flexDirection: 'column',
+    maxHeight: `calc(100% - ${spacingVars['--spacing-3']})`,
+  },
   // Visual styles for the panel content container.
   panelContainer: {
     backgroundColor: colorVars['--color-background-popover'],
@@ -132,6 +144,11 @@ const styles = stylex.create({
     borderRadius: radiusVars['--radius-container'],
     boxShadow: shadowVars['--shadow-low'],
     overflow: 'hidden',
+    // Allow the container to shrink inside the height-clamped layer so its
+    // content (panelContent) can scroll rather than overflow the viewport.
+    display: 'flex',
+    flexDirection: 'column',
+    minHeight: 0,
   },
   panelContent: {
     display: 'flex',
@@ -139,7 +156,14 @@ const styles = stylex.create({
     gap: spacingVars['--spacing-6'],
     paddingBlock: spacingVars['--spacing-3'],
     paddingInline: spacingVars['--spacing-3'],
-    maxWidth: 960,
+    // Clamp to the viewport (minus a gutter) so the anchored panel never
+    // overflows the screen edge on narrow viewports; caps at 960px otherwise.
+    maxWidth: `min(960px, calc(100dvw - ${spacingVars['--spacing-4']}))`,
+    boxSizing: 'border-box',
+    // Scroll internally when the menu is taller than the available space
+    // below the nav (paired with panelViewportFit on the layer).
+    overflowY: 'auto',
+    overscrollBehavior: 'contain',
   },
   menuWrapper: {
     flexGrow: 2,
@@ -484,7 +508,7 @@ function DefaultMegaMenu({
         {
           placement: 'below',
           alignment: slot,
-          xstyle: styles.panelAnimation,
+          xstyle: [styles.panelAnimation, styles.panelViewportFit],
         },
       )}
     </>