@astryxdesign/core 0.4.4 → 0.4.5-canary.013e728

package/src/HoverCard/useHoverCard.doc.mjs

@@ -12,6 +12,7 @@ export const docs = {
     {name: 'delay', type: 'number', description: 'Delay before showing the hover card on hover, in milliseconds.', default: '300'},
     {name: 'hideDelay', type: 'number', description: 'Delay before hiding after mouse or focus leaves, in milliseconds.', default: '200'},
     {name: 'focusTrigger', type: "'auto' | 'always' | 'never'", description: 'When focus should open the hover card. auto only attaches focus listeners to naturally focusable elements.', default: "'auto'"},
+    {name: 'touchTrigger', type: "'auto' | 'tap' | 'none'", description: 'What a tap does where there is no hover. auto opens on tap unless the trigger performs an action of its own; tap always opens; none never opens on touch.', default: "'auto'"},
     {name: 'isEnabled', type: 'boolean', description: 'Whether hover and focus triggers are enabled.', default: 'true'},
     {name: 'label', type: 'string', description: 'Accessible name for the hover card popup. When provided, the popup is exposed as a named role="dialog"; when omitted, it falls back to role="group" (a group may validly be unnamed).'},
     {name: 'isOpen', type: 'boolean', description: 'Controlled open state. true force-shows, false force-hides, undefined lets hover/focus manage visibility.'},
@@ -52,6 +53,7 @@ export const docsDense = {
     delay: 'show delay in ms.',
     hideDelay: 'hide delay after mouse/focus leave in ms.',
     focusTrigger: 'when focus opens hover card; auto = naturally focusable elements only.',
+    touchTrigger: 'tap behavior with no hover; auto = tap unless trigger acts, tap = always, none = never.',
     isEnabled: 'whether hover/focus triggers are enabled.',
     label: 'accessible name for popup. with label: named role="dialog"; without: role="group".',
     isOpen: 'controlled open state: true force-show, false force-hide, undefined unmanaged.',

package/src/HoverCard/useHoverCard.tsx

@@ -4,8 +4,8 @@
 
 /**
  * @file useHoverCard.ts
- * @input Uses useLayer, React hooks
- * @output Exports useHoverCard hook for hover/focus triggered layers
+ * @input Uses useLayer, useTouchTrigger, React hooks
+ * @output Exports useHoverCard hook for hover/focus/tap triggered layers
  * @position Layer hook; builds on useLayer for hover card behavior
  *
  * SYNC: When modified, update:
@@ -26,6 +26,10 @@ import {
   type LayerAlignment,
   type LayerPlacement,
 } from '../Layer/useLayer';
+import {
+  useTouchTrigger,
+  type LayerTouchTrigger,
+} from '../Layer/useTouchTrigger';
 import {layerAnimations} from '../Layer/layerAnimations.stylex';
 import {
   colorVars,
@@ -58,6 +62,11 @@ const styles = stylex.create({
  */
 export type HoverCardFocusTrigger = 'auto' | 'always' | 'never';
 
+/**
+ * Touch trigger behavior for hover cards
+ */
+export type HoverCardTouchTrigger = LayerTouchTrigger;
+
 export interface HoverCardOptions {
   /**
    * Position placement relative to anchor
@@ -93,6 +102,17 @@ export interface HoverCardOptions {
    */
   focusTrigger?: HoverCardFocusTrigger;
 
+  /**
+   * What a tap does on a touch pointer, where there is no hover:
+   * - `auto`: tap opens the card, unless the trigger performs an action of its
+   *   own (a button, a link, a form control) — that tap belongs to the control
+   * - `tap`: tap always opens the card, even on a trigger that acts
+   * - `none`: touch never opens the card
+   *
+   * @default 'auto'
+   */
+  touchTrigger?: HoverCardTouchTrigger;
+
   /**
    * Whether the hover card is enabled.
    * When false, hover/focus triggers are disabled.
@@ -240,6 +260,7 @@ export function useHoverCard(options: HoverCardOptions = {}): HoverCardReturn {
     delay = 300,
     hideDelay = 200,
     focusTrigger = 'auto',
+    touchTrigger = 'auto',
     isEnabled = true,
     label,
     isOpen,
@@ -276,6 +297,30 @@ export function useHoverCard(options: HoverCardOptions = {}): HoverCardReturn {
     }
   }, []);
 
+  // Touch resolves immediately: the hover delays exist to filter out a pointer
+  // passing across the trigger, and a tap is never that.
+  const showNow = useCallback(() => {
+    clearTimeouts();
+    layer.show();
+  }, [clearTimeouts, layer]);
+
+  const hideNow = useCallback(() => {
+    clearTimeouts();
+    isHoveringContentRef.current = false;
+    layer.hide();
+  }, [clearTimeouts, layer]);
+
+  const touch = useTouchTrigger({
+    touchTrigger,
+    isEnabled,
+    isControlled: isOpen !== undefined,
+    isOpen: layer.isOpen,
+    layerId: layer.id,
+    triggerRef,
+    show: showNow,
+    hide: hideNow,
+  });
+
   // Schedule show with delay (suppressed when isOpen is false)
   const scheduleShow = useCallback(() => {
     if (!isEnabled || isOpen === false) {
@@ -303,17 +348,42 @@ export function useHoverCard(options: HoverCardOptions = {}): HoverCardReturn {
 
   // Event handlers
   const handleMouseEnter = useCallback(() => {
+    // A tap synthesizes mouseenter. On touch the tap path owns the decision,
+    // so hover must not also fire — without this a hover card opens on every
+    // tap of its trigger and has nothing to close it.
+    if (touch.isTouchPointerRef.current) {
+      return;
+    }
     scheduleShow();
-  }, [scheduleShow]);
+  }, [touch, scheduleShow]);
 
   const handleMouseLeave = useCallback(() => {
+    // On touch the synthesized mouseleave arrives with the next tap elsewhere,
+    // which the outside-tap dismissal already handles.
+    if (touch.isTouchPointerRef.current) {
+      return;
+    }
     scheduleHide();
-  }, [scheduleHide]);
+  }, [touch, scheduleHide]);
+
+  // Tap-to-open on touch; on a mouse this does nothing and hover still rules.
+  const handlePointerDown = useCallback(
+    (event: PointerEvent) => {
+      touch.handlePointerDown(event);
+    },
+    [touch],
+  );
 
   const handleFocusIn = useCallback(() => {
     if (!isEnabled) {
       return;
     }
+    // A tap focuses the trigger it activates. Opening on that focus would
+    // reinstate exactly the behavior the touch path just decided against —
+    // and on an action trigger it covers the thing the user tapped.
+    if (touch.isTouchInteraction()) {
+      return;
+    }
     // Skip showing if we're in the middle of an Escape dismiss
     if (isEscapeDismissingRef.current) {
       isEscapeDismissingRef.current = false;
@@ -321,7 +391,7 @@ export function useHoverCard(options: HoverCardOptions = {}): HoverCardReturn {
     }
     clearTimeouts();
     layer.show();
-  }, [isEnabled, clearTimeouts, layer]);
+  }, [isEnabled, touch, clearTimeouts, layer]);
 
   const handleFocusOut = useCallback(
     (e: FocusEvent) => {
@@ -346,13 +416,15 @@ export function useHoverCard(options: HoverCardOptions = {}): HoverCardReturn {
         e.stopPropagation();
         // Hide immediately without refocusing (we're already on trigger)
         clearTimeouts();
+        touch.clearTapOpen();
         layer.hide();
       }
     },
-    [clearTimeouts, layer],
+    [touch, clearTimeouts, layer],
   );
 
   // Interaction ref that handles event listeners only
+  const {handlePointerEnter} = touch;
   const interactionRef: RefCallback<HTMLElement> = useCallback(
     (el: HTMLElement | null) => {
       // Cleanup previous element
@@ -365,12 +437,24 @@ export function useHoverCard(options: HoverCardOptions = {}): HoverCardReturn {
           handleFocusOut as EventListener,
         );
         triggerRef.current.removeEventListener('keydown', handleKeyDown);
+        triggerRef.current.removeEventListener(
+          'pointerenter',
+          handlePointerEnter,
+        );
+        triggerRef.current.removeEventListener(
+          'pointerdown',
+          handlePointerDown,
+        );
       }
 
       if (el) {
-        // Attach hover listeners
+        // Attach hover listeners. `pointerenter` runs before the synthesized
+        // `mouseenter` a tap produces, which is what lets the hover path know
+        // it is looking at a finger.
+        el.addEventListener('pointerenter', handlePointerEnter);
         el.addEventListener('mouseenter', handleMouseEnter);
         el.addEventListener('mouseleave', handleMouseLeave);
+        el.addEventListener('pointerdown', handlePointerDown);
 
         // Attach focus listeners based on focusTrigger option
         const shouldAttachFocus =
@@ -395,6 +479,8 @@ export function useHoverCard(options: HoverCardOptions = {}): HoverCardReturn {
       handleFocusIn,
       handleFocusOut,
       handleKeyDown,
+      handlePointerEnter,
+      handlePointerDown,
     ],
   );
 
@@ -475,10 +561,18 @@ export function useHoverCard(options: HoverCardOptions = {}): HoverCardReturn {
         <div
           {...stylex.props(styles.content)}
           onMouseEnter={() => {
+            // Touch synthesizes these over the card too; letting a tap inside
+            // register as "hovering content" would block every later hide.
+            if (touch.isTouchPointerRef.current) {
+              return;
+            }
             isHoveringContentRef.current = true;
             clearTimeouts();
           }}
           onMouseLeave={() => {
+            if (touch.isTouchPointerRef.current) {
+              return;
+            }
             isHoveringContentRef.current = false;
             scheduleHide();
           }}
@@ -490,6 +584,7 @@ export function useHoverCard(options: HoverCardOptions = {}): HoverCardReturn {
               isEscapeDismissingRef.current = true;
               // Hide immediately
               clearTimeouts();
+              touch.clearTapOpen();
               layer.hide();
               // Refocus the trigger
               triggerRef.current?.focus();
@@ -526,6 +621,7 @@ export function useHoverCard(options: HoverCardOptions = {}): HoverCardReturn {
       clearTimeouts,
       scheduleHide,
       popoverXstyle,
+      touch,
     ],
   );
 

package/src/Item/Item.doc.mjs

@@ -40,6 +40,7 @@ export const docs = {
         {name: 'density', type: "'compact' | 'balanced' | 'spacious'", description: 'Spacing density. "compact" uses 4px block padding, "balanced" uses 8px, and "spacious" uses 12px block and inline padding.', default: "'balanced'"},
         {name: 'labelLines', type: 'number', description: 'Max lines before label truncates with ellipsis.'},
         {name: 'descriptionLines', type: 'number', description: 'Max lines before description truncates with ellipsis.'},
+        {name: 'layout', type: "'stacked' | 'inline'", description: 'How the label and description sit together. stacked puts the description on its own line below the label; inline keeps both on one line, description ellipsizing first, so the row fits a fixed-height host.', default: "'stacked'"},
         {name: 'onClick', type: '(event: MouseEvent) => void', description: 'Click handler. Makes the item clickable with button semantics.'},
         {name: 'interactiveRef', type: 'RefObject<HTMLElement | null>', description: 'Ref to a nested control (e.g. a checkbox in startContent) that owns the item\'s keyboard access and action. The row becomes an enlarged click/tap target that delegates surface clicks to it (useClickableContainer) and renders no invisible button/anchor, so the row adds no second tab stop (WCAG 4.1.2). Mutually exclusive with onClick/href; those are ignored when set.'},
         {name: 'href', type: 'string', description: 'Link URL. Makes the item a link via an invisible anchor element.'},

package/src/Item/Item.test.tsx

@@ -508,4 +508,54 @@ describe('Item', () => {
     expect(screen.getByText('Alice')).toBeInTheDocument();
     expect(screen.getByText(/commented/)).toBeInTheDocument();
   });
+  it('puts the label and description in one row when layout is inline', () => {
+    const stacked = render(
+      <Item label="Private" description="Only members can access" />,
+    );
+    const stackedRow = screen.getByText('Private').parentElement;
+    stacked.unmount();
+
+    render(
+      <Item
+        label="Private"
+        description="Only members can access"
+        layout="inline"
+      />,
+    );
+    const inlineRow = screen.getByText('Private').parentElement;
+
+    // Same container, different styling: the shared content box switches from
+    // a column to a row, so its class list must differ from the stacked one.
+    expect(inlineRow?.className).not.toBe(stackedRow?.className);
+  });
+
+  it('ellipsizes a ReactNode description when layout is inline', () => {
+    // A stacked ReactNode description is left alone (it may wrap); an inline
+    // one is one line by definition, so it truncates like a string does.
+    const stacked = render(
+      <Item
+        label="Private"
+        description={<span>Only members can access</span>}
+      />,
+    );
+    const stackedDescription = screen.getByText('Only members can access')
+      .parentElement?.className;
+    stacked.unmount();
+
+    render(
+      <Item
+        label="Private"
+        description={<span>Only members can access</span>}
+        layout="inline"
+      />,
+    );
+    expect(
+      screen.getByText('Only members can access').parentElement?.className,
+    ).not.toBe(stackedDescription);
+  });
+
+  it('ignores inline layout when there is no description', () => {
+    render(<Item label="Private" layout="inline" />);
+    expect(screen.getByText('Private')).toBeInTheDocument();
+  });
 });

package/src/Item/Item.tsx

@@ -106,6 +106,15 @@ export interface ItemProps extends BaseProps<HTMLElement> {
    */
   descriptionLines?: number;
 
+  /**
+   * How the label and description sit together. `stacked` puts the description
+   * on its own line below the label; `inline` keeps both on one line, with the
+   * description ellipsizing first, so the row fits a fixed-height host.
+   *
+   * @default 'stacked'
+   */
+  layout?: 'stacked' | 'inline';
+
   /**
    * Click handler. Makes the item clickable with button semantics.
    */
@@ -213,7 +222,7 @@ const styles = stylex.create({
     transitionTimingFunction: easeVars['--ease-standard'],
     backgroundColor: {
       default: 'transparent',
-      ':hover': {
+      ':hover:where(:not(:disabled,[aria-disabled="true"]))': {
         '@media (hover: hover)': colorVars['--color-overlay-hover'],
       },
       ':active': colorVars['--color-overlay-pressed'],
@@ -264,6 +273,25 @@ const styles = stylex.create({
     minWidth: 0,
     textAlign: 'start',
   },
+  // `layout="inline"`: label and description share one line, so the row fits a
+  // fixed-height host such as a Selector trigger inside an InputGroup.
+  inlineContent: {
+    flexDirection: 'row',
+    // Centered, not baseline-aligned: two different font sizes on a shared
+    // baseline make a line box taller than either line, which would push a
+    // fixed-height host (a Selector trigger) a pixel off its size token.
+    alignItems: 'center',
+    columnGap: spacingVars['--spacing-1'],
+  },
+  inlineLabel: {
+    flexShrink: 0,
+  },
+  // The description yields width first, so the label — the part that identifies
+  // the item — is the last thing to ellipsize.
+  inlineDescription: {
+    flexShrink: 1,
+    minWidth: 0,
+  },
   label: {
     // Falls back to the primary text token; a parent (e.g. a destructive menu
     // item) can recolor the label by setting --_item-label-color.
@@ -358,6 +386,7 @@ export function Item({
   density = 'balanced',
   labelLines,
   descriptionLines,
+  layout = 'stacked',
   onClick,
   interactiveRef,
   href,
@@ -420,12 +449,16 @@ export function Item({
         ? styles.labelSingleTruncate
         : null;
 
+  // Inline rows are one line by definition, so the description always
+  // ellipsizes there — a ReactNode description cannot wrap the row open.
+  const isInline = layout === 'inline' && description != null;
+
   const descriptionTruncateStyle =
     descriptionLines != null
       ? descriptionLines === 1
         ? styles.descriptionSingleTruncate
         : styles.descriptionMultiTruncate
-      : isStringDescription
+      : isStringDescription || isInline
         ? styles.descriptionSingleTruncate
         : null;
 
@@ -434,6 +467,7 @@ export function Item({
       <span
         {...stylex.props(
           styles.label,
+          isInline && styles.inlineLabel,
           labelTruncateStyle,
           labelLines != null &&
             labelLines > 1 &&
@@ -445,6 +479,7 @@ export function Item({
         <span
           {...stylex.props(
             styles.description,
+            isInline && styles.inlineDescription,
             descriptionTruncateStyle,
             descriptionLines != null &&
               descriptionLines > 1 &&
@@ -481,6 +516,7 @@ export function Item({
         <span
           {...stylex.props(
             styles.content,
+            isInline && styles.inlineContent,
             isDisabled && styles.disabledContent,
           )}>
           {labelAndDescription}
@@ -494,6 +530,7 @@ export function Item({
           tabIndex={isDisabled ? -1 : undefined}
           {...stylex.props(
             styles.invisibleAnchor,
+            isInline && styles.inlineContent,
             isDisabled && styles.disabledContent,
           )}>
           {labelAndDescription}
@@ -505,6 +542,7 @@ export function Item({
           disabled={isDisabled}
           {...stylex.props(
             styles.invisibleButton,
+            isInline && styles.inlineContent,
             isDisabled && styles.disabledContent,
           )}>
           {labelAndDescription}
@@ -513,6 +551,7 @@ export function Item({
         <span
           {...stylex.props(
             styles.content,
+            isInline && styles.inlineContent,
             isDisabled && styles.disabledContent,
           )}>
           {labelAndDescription}

package/src/Layer/index.ts

@@ -29,6 +29,14 @@ export type {
   FixedLayerReturn,
 } from './useLayer';
 
+// Shared touch behavior for the hover layers
+export {useTouchTrigger, isActionTrigger} from './useTouchTrigger';
+export type {
+  LayerTouchTrigger,
+  UseTouchTriggerOptions,
+  UseTouchTriggerReturn,
+} from './useTouchTrigger';
+
 // Layer provider
 export {LayerProvider} from './LayerProvider';
 export type {LayerProviderProps} from './LayerProvider';
@@ -50,6 +58,7 @@ export type {
 export {useHoverCard, HoverCard} from '../HoverCard';
 export type {
   HoverCardFocusTrigger,
+  HoverCardTouchTrigger,
   HoverCardOptions,
   HoverCardReturn,
   HoverCardProps,
@@ -59,6 +68,7 @@ export type {
 export {useTooltip, Tooltip} from '../Tooltip';
 export type {
   TooltipFocusTrigger,
+  TooltipTouchTrigger,
   TooltipOptions,
   TooltipReturn,
   TooltipProps,

package/src/Layer/useLayer.tsx

@@ -29,6 +29,7 @@ import {createPortal} from 'react-dom';
 import {addAnchorName, removeAnchorName} from './anchorName';
 import {resolveLayerPortalTarget} from './layerHost';
 import {typeScaleVars, typographyVars} from '../theme/tokens.stylex';
+import {overlayPaddingReset} from '../Layout/padding.stylex';
 
 const styles = stylex.create({
   // Base reset for all layers
@@ -771,7 +772,12 @@ export function useLayer(
             : styles.offsetInline(toCssLength(offset))
           : null;
 
-      const stylexResult = stylex.props(styles.base, offsetStyle, xstyle);
+      const stylexResult = stylex.props(
+        styles.base,
+        overlayPaddingReset.reset,
+        offsetStyle,
+        xstyle,
+      );
       const combinedClassName = extraClassName
         ? `${extraClassName} ${stylexResult.className ?? ''}`
         : stylexResult.className;
@@ -835,7 +841,12 @@ export function useLayer(
         left: x,
       };
 
-      const stylexResult = stylex.props(styles.base, styles.fixed, xstyle);
+      const stylexResult = stylex.props(
+        styles.base,
+        overlayPaddingReset.reset,
+        styles.fixed,
+        xstyle,
+      );
       const combinedClassName = extraClassName
         ? `${extraClassName} ${stylexResult.className ?? ''}`
         : stylexResult.className;

package/src/Layer/useTouchTrigger.test.ts

@@ -0,0 +1,70 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file useTouchTrigger.test.ts
+ * @input Uses vitest, isActionTrigger
+ * @output Unit tests for the action-trigger rule behind touchTrigger="auto"
+ * @position Testing; validates useTouchTrigger.ts implementation
+ *
+ * SYNC: When useTouchTrigger.ts changes, update tests to match new behavior
+ *
+ * The tap-versus-suppress decision rests entirely on this predicate, and it is
+ * the part a new element type silently falls through. The per-component tests
+ * (Tooltip.test.tsx, HoverCard.test.tsx) cover the gestures it feeds.
+ */
+
+import {describe, it, expect} from 'vitest';
+import {isActionTrigger} from './useTouchTrigger';
+
+function element(html: string): HTMLElement {
+  const host = document.createElement('div');
+  host.innerHTML = html;
+  return host.firstElementChild as HTMLElement;
+}
+
+describe('isActionTrigger', () => {
+  it.each([
+    ['<button type="button">Save</button>'],
+    ['<input type="text" />'],
+    ['<select></select>'],
+    ['<textarea></textarea>'],
+    ['<summary>More</summary>'],
+    ['<label>Name</label>'],
+    ['<a href="/somewhere">Link</a>'],
+  ])('treats %s as an action', html => {
+    expect(isActionTrigger(element(html))).toBe(true);
+  });
+
+  it.each([
+    ['<span>Plain text</span>'],
+    ['<svg></svg>'],
+    ['<abbr title="what">WCAG</abbr>'],
+    // An anchor without href is a link that goes nowhere.
+    ['<a>Not a link</a>'],
+  ])('treats %s as inert', html => {
+    expect(isActionTrigger(element(html))).toBe(false);
+  });
+
+  it('reads an explicit role over the tag it sits on', () => {
+    expect(isActionTrigger(element('<span role="button">Go</span>'))).toBe(
+      true,
+    );
+    // Scenery: the role says this button is not the control it looks like.
+    expect(
+      isActionTrigger(element('<button role="presentation">x</button>')),
+    ).toBe(false);
+  });
+
+  it('does not treat mere focusability as an action', () => {
+    // The wrapper a text-only Tooltip renders: reachable by keyboard so the
+    // hint is not mouse-only, and it still does nothing when activated.
+    expect(isActionTrigger(element('<span tabindex="0">Term</span>'))).toBe(
+      false,
+    );
+  });
+
+  it('treats a contenteditable surface as an action', () => {
+    const editable = element('<div contenteditable="true"></div>');
+    expect(isActionTrigger(editable)).toBe(true);
+  });
+});