@astryxdesign/core 0.4.7 → 0.5.0-canary.009bcb3

package/src/Layer/useLayer.test.tsx

@@ -12,11 +12,20 @@
 import {describe, it, expect, vi, afterEach} from 'vitest';
 import {render, act, fireEvent, waitFor} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
-import {useLayer, getPositionTryFallbacks} from './useLayer';
+import * as stylex from '@stylexjs/stylex';
+import {
+  useKeepLayerOpenProps,
+  useLayer,
+  useLayerInternal,
+  getPositionTryFallbacks,
+} from './useLayer';
+import {typeScaleVars} from '../theme/tokens.stylex';
 import type {
   LayerPlacement,
   LayerAlignment,
   ContextRenderProps,
+  ContextLayerReturn,
+  FixedLayerReturn,
 } from './useLayer';
 
 function mockCSSStyleDeclaration(
@@ -500,20 +509,6 @@ describe('useLayer', () => {
   });
 
   describe('when the Popover API is supported', () => {
-    it('declares body type instead of inheriting the host context', () => {
-      const {container} = render(
-        <div style={{fontSize: '30px', lineHeight: '3'}}>
-          <LayerHarness onReady={() => {}} />
-        </div>,
-      );
-
-      const layer = container.querySelector('[popover]') as HTMLElement;
-      expect(layer).toHaveStyle({
-        fontSize: 'var(--text-body-size)',
-        lineHeight: 'var(--text-body-leading)',
-      });
-    });
-
     it('calls showPopover/hidePopover on show/hide', () => {
       const showSpy = vi.fn();
       const hideSpy = vi.fn();
@@ -614,6 +609,66 @@ async function openAndGetStyle(ui: React.ReactElement): Promise<string> {
   return popover?.getAttribute('style') ?? '';
 }
 
+describe('typography baseline', () => {
+  const overrideStyles = stylex.create({
+    supporting: {fontSize: typeScaleVars['--text-supporting-size']},
+  });
+
+  function TypographyHarness({
+    ambientFontSize,
+    xstyle,
+  }: {
+    ambientFontSize: string;
+    xstyle?: ContextRenderProps['xstyle'];
+  }) {
+    const layer = useLayer({mode: 'context'});
+    return (
+      <div style={{fontSize: ambientFontSize, lineHeight: '3'}}>
+        <button type="button" ref={layer.ref} onClick={layer.show}>
+          trigger
+        </button>
+        {layer.render(<span>content</span>, {xstyle})}
+      </div>
+    );
+  }
+
+  async function openAndGetType(ui: React.ReactElement) {
+    const user = userEvent.setup();
+    const {container, getByRole} = render(ui);
+    await user.click(getByRole('button', {name: 'trigger'}));
+    const el = container.querySelector('[popover]') as HTMLElement;
+    const computed = window.getComputedStyle(el);
+    return {fontSize: computed.fontSize, lineHeight: computed.lineHeight};
+  }
+
+  // jsdom resolves no var() indirection, so the token reference is what the
+  // assertion can see — the point is that a declaration exists at all, since
+  // an absent one is exactly what let the ambient size through.
+  it.each(['13px', '20px'])(
+    'takes the body role rather than the surrounding %s',
+    async ambientFontSize => {
+      expect(
+        await openAndGetType(
+          <TypographyHarness ambientFontSize={ambientFontSize} />,
+        ),
+      ).toEqual({
+        fontSize: 'var(--text-body-size)',
+        lineHeight: 'var(--text-body-leading)',
+      });
+    },
+  );
+
+  it('still lets a consumer xstyle set its own size', async () => {
+    const {fontSize} = await openAndGetType(
+      <TypographyHarness
+        ambientFontSize="13px"
+        xstyle={overrideStyles.supporting}
+      />,
+    );
+    expect(fontSize).toBe('var(--text-supporting-size)');
+  });
+});
+
 describe('useLayer context positioning', () => {
   // The mapping uses the self-* logical keyword family, so the emitted
   // string is direction-independent by construction: the browser resolves
@@ -873,3 +928,257 @@ describe('useLayer context positioning', () => {
     expect(style).not.toContain('position-anchor');
   });
 });
+
+describe('useLayer public return types', () => {
+  it('keeps dismissal helpers internal', () => {
+    const contextHasKeepOpenProps: 'keepOpenProps' extends keyof ContextLayerReturn
+      ? true
+      : false = false;
+    const fixedHasKeepOpenProps: 'keepOpenProps' extends keyof FixedLayerReturn
+      ? true
+      : false = false;
+    const contextHasGuard: 'wasJustDismissed' extends keyof ContextLayerReturn
+      ? true
+      : false = false;
+    const fixedHasGuard: 'wasJustDismissed' extends keyof FixedLayerReturn
+      ? true
+      : false = false;
+
+    expect(contextHasKeepOpenProps).toBe(false);
+    expect(fixedHasKeepOpenProps).toBe(false);
+    expect(contextHasGuard).toBe(false);
+    expect(fixedHasGuard).toBe(false);
+  });
+});
+
+describe('internal keep-open props (controls on the trigger, #5004)', () => {
+  function ClearableTriggerHarness() {
+    const layer = useLayer({mode: 'context'});
+    const keepOpenProps = useKeepLayerOpenProps(layer.id, layer.isOpen);
+    return (
+      <>
+        <button type="button" ref={layer.ref} onClick={layer.show}>
+          Trigger
+        </button>
+        <button type="button" {...keepOpenProps}>
+          Clear
+        </button>
+        {layer.render(<span>Layer content</span>, {placement: 'below'})}
+      </>
+    );
+  }
+
+  it('names the control an invoker for the duration of the press', async () => {
+    const user = userEvent.setup();
+    const {container, getByRole} = render(<ClearableTriggerHarness />);
+    const clear = getByRole('button', {name: 'Clear'});
+
+    await user.click(getByRole('button', {name: 'Trigger'}));
+    const popover = container.querySelector('[popover]') as HTMLElement;
+
+    await user.pointer({keys: '[MouseLeft>]', target: clear});
+    expect(clear.getAttribute('popovertarget')).toBe(popover.id);
+
+    await user.pointer({keys: '[/MouseLeft]', target: clear});
+    expect(clear).not.toHaveAttribute('popovertarget');
+  });
+
+  it('takes the invoker off when the press ends in pointercancel', async () => {
+    const user = userEvent.setup();
+    const {container, getByRole} = render(<ClearableTriggerHarness />);
+    const clear = getByRole('button', {name: 'Clear'});
+
+    await user.click(getByRole('button', {name: 'Trigger'}));
+    const popover = container.querySelector('[popover]') as HTMLElement;
+
+    await user.pointer({keys: '[MouseLeft>]', target: clear});
+    expect(clear.getAttribute('popovertarget')).toBe(popover.id);
+
+    // A touch the browser claims — for a scroll, for the platform's long-press
+    // menu — ends here, and no pointerup ever arrives.
+    await act(async () => {
+      document.dispatchEvent(new Event('pointercancel'));
+      await new Promise(resolve => {
+        window.setTimeout(resolve, 0);
+      });
+    });
+
+    expect(clear).not.toHaveAttribute('popovertarget');
+  });
+
+  it('leaves the control alone while the layer is closed', async () => {
+    const user = userEvent.setup();
+    const {getByRole} = render(<ClearableTriggerHarness />);
+    const clear = getByRole('button', {name: 'Clear'});
+
+    await user.click(clear);
+
+    expect(clear).not.toHaveAttribute('popovertarget');
+  });
+
+  it("cancels the invoker's own toggle so the press cannot close the layer", async () => {
+    const user = userEvent.setup();
+    const {container, getByRole} = render(<ClearableTriggerHarness />);
+    await user.click(getByRole('button', {name: 'Trigger'}));
+    const popover = container.querySelector('[popover]') as HTMLElement;
+    const clear = getByRole('button', {name: 'Clear'});
+
+    const click = new MouseEvent('click', {bubbles: true, cancelable: true});
+    await act(async () => {
+      clear.setAttribute('popovertarget', popover.id);
+      clear.dispatchEvent(click);
+    });
+
+    expect(click.defaultPrevented).toBe(true);
+    expect(clear).not.toHaveAttribute('popovertarget');
+  });
+});
+
+describe('wasJustDismissed (light dismiss vs. the trigger click, #5004)', () => {
+  function GuardedTriggerHarness() {
+    const layer = useLayerInternal({mode: 'context'});
+    return (
+      <>
+        <button
+          type="button"
+          ref={layer.ref}
+          onClick={() => {
+            if (layer.wasJustDismissed()) {
+              return;
+            }
+            if (layer.isOpen) {
+              layer.hide();
+            } else {
+              layer.show();
+            }
+          }}>
+          Trigger
+        </button>
+        <span data-testid="state">{layer.isOpen ? 'open' : 'closed'}</span>
+        {layer.render(<span>Layer content</span>, {placement: 'below'})}
+      </>
+    );
+  }
+
+  /**
+   * The browser closing the layer itself: it hides the element and queues a
+   * `toggle` event, which is what reaches React — before the click, on the
+   * engines that lose the race.
+   */
+  function lightDismiss(container: HTMLElement) {
+    const popover = container.querySelector('[popover]') as HTMLElement;
+    act(() => {
+      popover.dispatchEvent(
+        Object.assign(new Event('toggle'), {
+          oldState: 'open',
+          newState: 'closed',
+        }),
+      );
+    });
+  }
+
+  it('absorbs the trigger click that follows a light dismiss', async () => {
+    const user = userEvent.setup();
+    const {container, getByRole, getByTestId} = render(
+      <GuardedTriggerHarness />,
+    );
+    const trigger = getByRole('button', {name: 'Trigger'});
+
+    await user.click(trigger);
+    expect(getByTestId('state')).toHaveTextContent('open');
+
+    // The next press reaches the browser dismissal before its click.
+    fireEvent.pointerDown(trigger);
+    lightDismiss(container);
+    fireEvent.click(trigger);
+
+    expect(getByTestId('state')).toHaveTextContent('closed');
+  });
+
+  it('acts on a deliberate second press', async () => {
+    const user = userEvent.setup();
+    const {container, getByRole, getByTestId} = render(
+      <GuardedTriggerHarness />,
+    );
+    const trigger = getByRole('button', {name: 'Trigger'});
+
+    await user.click(trigger);
+    fireEvent.pointerDown(trigger);
+    lightDismiss(container);
+    fireEvent.click(trigger);
+    // A press of its own — a new gesture, however soon it lands.
+    await user.click(trigger);
+
+    expect(getByTestId('state')).toHaveTextContent('open');
+  });
+
+  it('leaves a programmatic hide unguarded', async () => {
+    const user = userEvent.setup();
+    const {getByRole, getByTestId} = render(<GuardedTriggerHarness />);
+    const trigger = getByRole('button', {name: 'Trigger'});
+
+    // Three presses with no browser-initiated close between them.
+    await user.click(trigger);
+    await user.click(trigger);
+    await user.click(trigger);
+
+    expect(getByTestId('state')).toHaveTextContent('open');
+  });
+
+  it('acts on a synthesized click after a stopped click-first dismissal', async () => {
+    const user = userEvent.setup();
+    const {container, getByRole, getByTestId} = render(
+      <GuardedTriggerHarness />,
+    );
+    const trigger = getByRole('button', {name: 'Trigger'});
+
+    await user.click(trigger);
+    fireEvent.pointerDown(document.body);
+    document.body.addEventListener('click', event => event.stopPropagation(), {
+      once: true,
+    });
+    fireEvent.click(document.body);
+    lightDismiss(container);
+    expect(getByTestId('state')).toHaveTextContent('closed');
+
+    // Chromium delivers the dismissing click before the queued toggle. A later
+    // bare click is a new activation even though it has no pointerdown.
+    act(() => {
+      trigger.click();
+    });
+
+    expect(getByTestId('state')).toHaveTextContent('open');
+  });
+
+  /** A trigger that calls show()/hide() directly, checking nothing. */
+  function PlainTriggerHarness() {
+    const layer = useLayerInternal({mode: 'context'});
+    return (
+      <>
+        <button
+          type="button"
+          ref={layer.ref}
+          onClick={() => (layer.isOpen ? layer.hide() : layer.show())}>
+          Trigger
+        </button>
+        <span data-testid="state">{layer.isOpen ? 'open' : 'closed'}</span>
+        {layer.render(<span>Layer content</span>, {placement: 'below'})}
+      </>
+    );
+  }
+
+  it('absorbs the click for a trigger that never calls wasJustDismissed', async () => {
+    const user = userEvent.setup();
+    const {container, getByRole, getByTestId} = render(<PlainTriggerHarness />);
+    const trigger = getByRole('button', {name: 'Trigger'});
+
+    await user.click(trigger);
+    expect(getByTestId('state')).toHaveTextContent('open');
+
+    fireEvent.pointerDown(trigger);
+    lightDismiss(container);
+    fireEvent.click(trigger);
+
+    expect(getByTestId('state')).toHaveTextContent('closed');
+  });
+});

package/src/Layer/useLayer.tsx

@@ -5,7 +5,7 @@
 /**
  * @file useLayer.tsx
  * @input Uses React hooks, Popover API, CSS anchor positioning, typography tokens
- * @output Exports useLayer hook for layer positioning and visibility
+ * @output Exports the public useLayer hook plus internal trigger helpers.
  * @position Core layer utility; used by useHoverCard, useTooltip, etc.
  *
  * SYNC: When modified, update:
@@ -18,6 +18,7 @@ import React, {
   useCallback,
   useEffect,
   useId,
+  useMemo,
   useRef,
   useState,
   type ReactNode,
@@ -27,6 +28,7 @@ import * as stylex from '@stylexjs/stylex';
 import type {StyleXStyles} from '@stylexjs/stylex';
 import {createPortal} from 'react-dom';
 import {addAnchorName, removeAnchorName} from './anchorName';
+import {currentGesture, currentGestureHasClicked} from './gestureCounter';
 import {resolveLayerPortalTarget} from './layerHost';
 import {typeScaleVars, typographyVars} from '../theme/tokens.stylex';
 import {overlayPaddingReset} from '../Layout/padding.stylex';
@@ -72,6 +74,18 @@ const styles = stylex.create({
   }),
 });
 
+/**
+ * Props for a control that sits on the trigger but must not dismiss the layer.
+ */
+interface KeepLayerOpenProps {
+  onPointerDown: React.PointerEventHandler<HTMLElement>;
+  /**
+   * Capture phase, so spreading these props never collides with the control's
+   * own `onClick`.
+   */
+  onClickCapture: React.MouseEventHandler<HTMLElement>;
+}
+
 /**
  * Position placement relative to anchor.
  * Logical: start/end resolve against the popover's own inherited direction
@@ -326,6 +340,13 @@ export interface FixedLayerReturn {
   render: (children: ReactNode, props: FixedRenderProps) => ReactNode;
 }
 
+interface InternalLayerFields {
+  wasJustDismissed: () => boolean;
+}
+
+type InternalContextLayerReturn = ContextLayerReturn & InternalLayerFields;
+type InternalFixedLayerReturn = FixedLayerReturn & InternalLayerFields;
+
 function toCssLength(value: number | string): string {
   return typeof value === 'number' ? `${value}px` : value;
 }
@@ -437,6 +458,51 @@ export function getPositionTryFallbacks(
   return `${flips}, ${same} span-top, ${same} span-bottom, ${opposite} span-top, ${opposite} span-bottom`;
 }
 
+/**
+ * Internal props for controls that sit beside an open layer. This stays out of
+ * the public useLayer/usePopover return types until the input family adopts it.
+ */
+export function useKeepLayerOpenProps(
+  id: string,
+  isOpen: boolean,
+): KeepLayerOpenProps {
+  const isOpenRef = useRef(isOpen);
+  isOpenRef.current = isOpen;
+
+  return useMemo(
+    () => ({
+      onPointerDown: (event: React.PointerEvent<HTMLElement>) => {
+        if (!isOpenRef.current) {
+          return;
+        }
+        // The browser reads the invoker relationship at both ends of the press.
+        const control = event.currentTarget;
+        const doc = control.ownerDocument;
+        control.setAttribute('popovertarget', id);
+        const onPressEnd = () => {
+          doc.removeEventListener('pointerup', onPressEnd);
+          doc.removeEventListener('pointercancel', onPressEnd);
+          // Light dismiss runs as the pointerup default action after listeners.
+          doc.defaultView?.setTimeout(() => {
+            control.removeAttribute('popovertarget');
+          }, 0);
+        };
+        doc.addEventListener('pointerup', onPressEnd);
+        doc.addEventListener('pointercancel', onPressEnd);
+      },
+      onClickCapture: (event: React.MouseEvent<HTMLElement>) => {
+        const control = event.currentTarget;
+        if (control.hasAttribute('popovertarget')) {
+          // Being an invoker would otherwise toggle the layer shut.
+          event.preventDefault();
+          control.removeAttribute('popovertarget');
+        }
+      },
+    }),
+    [id],
+  );
+}
+
 /**
  * Core layer hook that handles popover behavior and positioning.
  *
@@ -451,11 +517,9 @@ export function getPositionTryFallbacks(
  * {layer.render(<Content />, { placement: 'above', alignment: 'center' })}
  * ```
  */
-export function useLayer(options: ContextLayerOptions): ContextLayerReturn;
-export function useLayer(options: FixedLayerOptions): FixedLayerReturn;
-export function useLayer(
+function useLayerImplementation(
   options: ContextLayerOptions | FixedLayerOptions,
-): ContextLayerReturn | FixedLayerReturn {
+): InternalContextLayerReturn | InternalFixedLayerReturn {
   const {mode, onShow, onHide, lightDismiss = false} = options;
   const lazyMount = mode === 'context' ? (options.lazyMount ?? false) : false;
   const id = useId();
@@ -485,6 +549,17 @@ export function useLayer(
   // stale-closure reads of the previous isOpen value.
   const isOpenRef = useRef(false);
 
+  // The gesture during which the browser last closed this layer on its own.
+  // Read through wasJustDismissed by triggers deciding whether a click is
+  // theirs to act on.
+  const dismissedByGestureRef = useRef<number | null>(null);
+  const forgetDismissalRef = useRef<(() => void) | null>(null);
+
+  const wasJustDismissed = useCallback(() => {
+    const gesture = currentGesture();
+    return dismissedByGestureRef.current === gesture;
+  }, []);
+
   const showPopoverElement = useCallback((popover: HTMLElement) => {
     // Finding infra-4: the Popover API is unsupported on Safari <17 and
     // Firefox <125. On those browsers `showPopover` does not exist, so fall
@@ -548,6 +623,11 @@ export function useLayer(
   }, [mode, lazyMount]);
 
   const show = useCallback(() => {
+    // Every caller lands here, so this is where the dismissing press is
+    // absorbed: opening now would reopen the popup that same press closed.
+    if (wasJustDismissed()) {
+      return;
+    }
     // A context popover left over until React commits a previous hide must not
     // be reopened. The synchronous mount ref is the source of truth.
     const candidate = popoverRef.current;
@@ -569,12 +649,18 @@ export function useLayer(
     requestContextMount,
     showPopoverElement,
     isCurrentContextPopover,
+    wasJustDismissed,
   ]);
 
   const hide = useCallback(() => {
     pendingShowRef.current = false;
     if (isOpenRef.current) {
       const el = popoverRef.current;
+      // Clear the open state BEFORE hiding: hidePopover fires `toggle`, and
+      // the reconciler below reads this ref to tell the browser's own
+      // dismissals from ours.
+      openedPopoverRef.current = null;
+      isOpenRef.current = false;
       // See finding infra-4 note in `show`: mirror the same guard on hide so
       // unsupported browsers degrade gracefully instead of throwing.
       if (el) {
@@ -584,8 +670,6 @@ export function useLayer(
           el.style.display = 'none';
         }
       }
-      openedPopoverRef.current = null;
-      isOpenRef.current = false;
       setIsOpen(false);
       onHide?.();
     }
@@ -610,6 +694,51 @@ export function useLayer(
         }
       : undefined;
 
+  // Arm only when the dismissing gesture's click is still ahead of us. Some
+  // engines deliver click first; in that order there is nothing left to absorb.
+  const rememberDismissal = useCallback((doc: Document) => {
+    forgetDismissalRef.current?.();
+    if (currentGestureHasClicked()) {
+      return;
+    }
+    dismissedByGestureRef.current = currentGesture();
+    const view = doc.defaultView;
+    let forgetTimer: number | null = null;
+    const forget = () => {
+      dismissedByGestureRef.current = null;
+      doc.removeEventListener('click', scheduleForget, true);
+      if (forgetTimer !== null) {
+        view?.clearTimeout(forgetTimer);
+        forgetTimer = null;
+      }
+      if (forgetDismissalRef.current === forget) {
+        forgetDismissalRef.current = null;
+      }
+    };
+    const scheduleForget = () => {
+      doc.removeEventListener('click', scheduleForget, true);
+      // The next task keeps the dismissal armed through React's click handler.
+      if (view) {
+        forgetTimer = view.setTimeout(() => {
+          forgetTimer = null;
+          if (forgetDismissalRef.current === forget) {
+            forget();
+          }
+        }, 0);
+      } else {
+        forget();
+      }
+    };
+    doc.addEventListener('click', scheduleForget, true);
+    forgetDismissalRef.current = forget;
+  }, []);
+
+  useEffect(() => {
+    // Install capture-phase gesture tracking before the first interaction.
+    currentGesture();
+    return () => forgetDismissalRef.current?.();
+  }, []);
+
   // Reconcile browser-initiated closes (light-dismiss, popover="auto" stack
   // eviction). These are the only cases where the DOM mutates without going
   // through our show/hide — we sync React state back to match.
@@ -626,12 +755,15 @@ export function useLayer(
       if (toggleEvent.newState === 'closed' && isOpenRef.current) {
         openedPopoverRef.current = null;
         isOpenRef.current = false;
+        rememberDismissal(
+          (e.currentTarget as HTMLElement | null)?.ownerDocument ?? document,
+        );
         setIsOpen(false);
         onHide?.();
         clearContextMount();
       }
     },
-    [onHide, clearContextMount],
+    [onHide, clearContextMount, rememberDismissal],
   );
 
   // Ref callback for popover element — sets up the `toggle` listener.
@@ -872,6 +1004,7 @@ export function useLayer(
       show,
       hide,
       isOpen,
+      wasJustDismissed,
       id,
       render: renderContext,
     };
@@ -882,7 +1015,30 @@ export function useLayer(
     show,
     hide,
     isOpen,
+    wasJustDismissed,
     id,
     render: renderFixed,
   };
 }
+
+export function useLayer(options: ContextLayerOptions): ContextLayerReturn;
+export function useLayer(options: FixedLayerOptions): FixedLayerReturn;
+export function useLayer(
+  options: ContextLayerOptions | FixedLayerOptions,
+): ContextLayerReturn | FixedLayerReturn {
+  const {wasJustDismissed: _, ...layer} = useLayerImplementation(options);
+  return layer;
+}
+
+/** @internal Shared with usePopover; not exported from the package barrel. */
+export function useLayerInternal(
+  options: ContextLayerOptions,
+): InternalContextLayerReturn;
+export function useLayerInternal(
+  options: FixedLayerOptions,
+): InternalFixedLayerReturn;
+export function useLayerInternal(
+  options: ContextLayerOptions | FixedLayerOptions,
+): InternalContextLayerReturn | InternalFixedLayerReturn {
+  return useLayerImplementation(options);
+}