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

package/src/FormLayout/FormLayout.test.tsx

@@ -16,6 +16,8 @@ import {FormLayout} from './FormLayout';
 import {FormLayoutContext} from './FormLayoutContext';
 import type {FormLayoutDirection} from './FormLayoutContext';
 import {Field} from '../Field';
+import {TextInput} from '../TextInput';
+import {CheckboxInput} from '../CheckboxInput';
 
 // Helper component to read context
 function DirectionReader() {
@@ -23,6 +25,12 @@ function DirectionReader() {
   return <span data-testid="direction">{direction}</span>;
 }
 
+// Helper component to read the defaultOptionality context value
+function OptionalityReader() {
+  const {defaultOptionality} = use(FormLayoutContext);
+  return <span data-testid="optionality">{defaultOptionality ?? 'unset'}</span>;
+}
+
 describe('FormLayout', () => {
   // ─── Basic rendering ────────────────────────────────────────────────────
 
@@ -154,6 +162,178 @@ describe('FormLayout', () => {
     expect(screen.getByTestId('inner-child-2')).toBeInTheDocument();
   });
 
+  // ─── defaultOptionality context propagation ─────────────────────────────
+
+  it('leaves defaultOptionality unset by default', () => {
+    render(
+      <FormLayout>
+        <OptionalityReader />
+      </FormLayout>,
+    );
+    expect(screen.getByTestId('optionality')).toHaveTextContent('unset');
+  });
+
+  it('provides defaultOptionality="optional" to children', () => {
+    render(
+      <FormLayout defaultOptionality="optional">
+        <OptionalityReader />
+      </FormLayout>,
+    );
+    expect(screen.getByTestId('optionality')).toHaveTextContent('optional');
+  });
+
+  it('provides defaultOptionality="required" to children', () => {
+    render(
+      <FormLayout defaultOptionality="required">
+        <OptionalityReader />
+      </FormLayout>,
+    );
+    expect(screen.getByTestId('optionality')).toHaveTextContent('required');
+  });
+
+  it('an inner layout shadows the outer defaultOptionality', () => {
+    render(
+      <FormLayout defaultOptionality="optional">
+        <FormLayout defaultOptionality="required">
+          <OptionalityReader />
+        </FormLayout>
+      </FormLayout>,
+    );
+    expect(screen.getByTestId('optionality')).toHaveTextContent('required');
+  });
+
+  // ─── defaultOptionality indicator behavior (through Field) ───────────────
+  //
+  // The rule: only the *exception* is marked. A field that restates the form
+  // default shows nothing; a deviation shows its indicator.
+
+  it('optional default: only isRequired fields show an indicator', () => {
+    render(
+      <FormLayout defaultOptionality="optional">
+        <Field label="Bio" inputID="bio">
+          <input id="bio" />
+        </Field>
+        <Field label="Nickname" inputID="nick" isOptional>
+          <input id="nick" />
+        </Field>
+        <Field label="Email" inputID="email" isRequired>
+          <input id="email" />
+        </Field>
+      </FormLayout>,
+    );
+    // Plain + isOptional match the default → nothing shown.
+    expect(screen.queryByText(/Optional/)).not.toBeInTheDocument();
+    // isRequired deviates → the required indicator shows.
+    expect(screen.getByText(/Required/)).toBeInTheDocument();
+  });
+
+  it('required default: only isOptional fields show an indicator', () => {
+    render(
+      <FormLayout defaultOptionality="required">
+        <Field label="Name" inputID="name">
+          <input id="name" />
+        </Field>
+        <Field label="Email" inputID="email" isRequired>
+          <input id="email" />
+        </Field>
+        <Field label="Nickname" inputID="nick" isOptional>
+          <input id="nick" />
+        </Field>
+      </FormLayout>,
+    );
+    // Plain + isRequired match the default → nothing shown.
+    expect(screen.queryByText(/Required/)).not.toBeInTheDocument();
+    // isOptional deviates → the optional indicator shows.
+    expect(screen.getByText(/Optional/)).toBeInTheDocument();
+  });
+
+  it('unset default preserves per-field indicators (backwards compatible)', () => {
+    render(
+      <FormLayout>
+        <Field label="Email" inputID="email" isRequired>
+          <input id="email" />
+        </Field>
+        <Field label="Nickname" inputID="nick" isOptional>
+          <input id="nick" />
+        </Field>
+      </FormLayout>,
+    );
+    expect(screen.getByText(/Required/)).toBeInTheDocument();
+    expect(screen.getByText(/Optional/)).toBeInTheDocument();
+  });
+
+  // ─── defaultOptionality aria-required resolution ─────────────────────────
+  //
+  // The indicator is suppressed for the unmarked majority, so the matching
+  // `aria-required` must still be exposed — otherwise a sighted user reads a
+  // field as required (form default, no indicator) while a screen reader hears
+  // "not required". Native `required` stays bound to the explicit prop so a
+  // layout default never switches on browser validation.
+
+  it('required default: an unmarked input still exposes aria-required', () => {
+    render(
+      <FormLayout defaultOptionality="required">
+        <TextInput label="Name" value="" onChange={() => {}} />
+      </FormLayout>,
+    );
+    expect(screen.getByLabelText('Name')).toHaveAttribute(
+      'aria-required',
+      'true',
+    );
+  });
+
+  it('required default: an isOptional input is not aria-required', () => {
+    render(
+      <FormLayout defaultOptionality="required">
+        <TextInput label="Nickname" value="" onChange={() => {}} isOptional />
+      </FormLayout>,
+    );
+    expect(screen.getByRole('textbox')).not.toHaveAttribute('aria-required');
+  });
+
+  it('optional default: an unmarked input is not aria-required', () => {
+    render(
+      <FormLayout defaultOptionality="optional">
+        <TextInput label="Bio" value="" onChange={() => {}} />
+      </FormLayout>,
+    );
+    expect(screen.getByLabelText('Bio')).not.toHaveAttribute('aria-required');
+  });
+
+  it('no layout: an unmarked input is not aria-required (backwards compatible)', () => {
+    render(<TextInput label="Solo" value="" onChange={() => {}} />);
+    expect(screen.getByLabelText('Solo')).not.toHaveAttribute('aria-required');
+  });
+
+  it('required default resolves aria-required without native required', () => {
+    render(
+      <FormLayout defaultOptionality="required">
+        <CheckboxInput label="Terms" value={false} onChange={() => {}} />
+      </FormLayout>,
+    );
+    const checkbox = screen.getByRole('checkbox', {name: 'Terms'});
+    // Announced as required (form default)…
+    expect(checkbox).toHaveAttribute('aria-required', 'true');
+    // …but the native `required` attribute is not switched on by the layout.
+    expect(checkbox).not.toHaveAttribute('required');
+  });
+
+  it('explicit isRequired still drives native required under a layout', () => {
+    render(
+      <FormLayout defaultOptionality="required">
+        <CheckboxInput
+          label="Consent"
+          value={false}
+          onChange={() => {}}
+          isRequired
+        />
+      </FormLayout>,
+    );
+    const checkbox = screen.getByRole('checkbox', {name: 'Consent'});
+    expect(checkbox).toHaveAttribute('aria-required', 'true');
+    expect(checkbox).toHaveAttribute('required');
+  });
+
   // ─── Snapshot tests ─────────────────────────────────────────────────────
 
   it('matches snapshot for vertical direction', () => {
@@ -223,10 +403,7 @@ describe('FormLayout', () => {
   it('horizontal-labels with Field: label and input wrapper are siblings under display:contents', () => {
     render(
       <FormLayout direction="horizontal-labels" data-testid="layout">
-        <Field
-          label="Username"
-          inputID="username"
-          data-testid="username-field">
+        <Field label="Username" inputID="username" data-testid="username-field">
           <input id="username" data-testid="username-input" />
         </Field>
       </FormLayout>,

package/src/FormLayout/FormLayout.tsx

@@ -10,7 +10,10 @@
  *
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/FormLayout/FormLayout.test.tsx (tests for new/changed behavior)
+ * - /packages/core/src/FormLayout/FormLayoutContext.ts (context value shape)
+ * - /packages/core/src/FormLayout/FormLayout.doc.mjs (props table)
  * - /packages/core/src/FormLayout/index.ts (exports if types change)
+ * - /packages/core/src/Field/FieldLabel.tsx (defaultOptionality indicator resolution)
  * - /apps/storybook/stories/FormLayout.stories.tsx (storybook stories)
  * - /packages/cli/assets/templates/blocks/components/FormLayout/ (showcase blocks)
  */
@@ -19,7 +22,11 @@ import {useMemo, type ReactNode} from 'react';
 import type {BaseProps} from '../BaseProps';
 import * as stylex from '@stylexjs/stylex';
 import {spacingVars} from '../theme/tokens.stylex';
-import {FormLayoutContext, type FormLayoutDirection} from './FormLayoutContext';
+import {
+  FormLayoutContext,
+  type FormLayoutDirection,
+  type FormOptionality,
+} from './FormLayoutContext';
 import {mergeProps} from '../utils';
 import {themeProps} from '../utils/themeProps';
 
@@ -82,6 +89,26 @@ export interface FormLayoutProps extends BaseProps<HTMLDivElement> {
    * @default 'vertical'
    */
   direction?: FormLayoutDirection;
+
+  /**
+   * Which state the form treats as its default, so only the *exception*
+   * carries a visible optional/required indicator. It also resolves each
+   * field's `aria-required` so the unmarked majority is still announced
+   * correctly — but only `aria-required`, never the native `required`
+   * attribute, so a layout default can't switch on browser validation.
+   *
+   * - `'optional'` — fields read as optional; only a field with `isRequired`
+   *   shows an indicator (the "required" one).
+   * - `'required'` — fields read as required; only a field with `isOptional`
+   *   shows an indicator (the "optional" one). Fields without `isOptional`
+   *   expose `aria-required` even though they show no indicator.
+   * - unset — today's behavior: `isRequired` and `isOptional` each show their
+   *   own indicator independently.
+   *
+   * A field that merely restates the default (e.g. `isOptional` under
+   * `'optional'`) shows nothing. An inner `FormLayout` shadows an outer one.
+   */
+  defaultOptionality?: FormOptionality;
 }
 
 // =============================================================================
@@ -109,13 +136,17 @@ export interface FormLayoutProps extends BaseProps<HTMLDivElement> {
 export function FormLayout({
   children,
   direction = 'vertical',
+  defaultOptionality,
   xstyle,
   className,
   style,
   ref,
   ...props
 }: FormLayoutProps) {
-  const contextValue = useMemo(() => ({direction}), [direction]);
+  const contextValue = useMemo(
+    () => ({direction, defaultOptionality}),
+    [direction, defaultOptionality],
+  );
 
   return (
     <FormLayoutContext value={contextValue}>

package/src/FormLayout/FormLayoutContext.ts

@@ -5,10 +5,13 @@
 /**
  * @file FormLayoutContext.ts
  * @input Uses React createContext
- * @output Exports FormLayoutContext and FormLayoutDirection type
- * @position Context for form layout direction detection
+ * @output Exports FormLayoutContext, FormLayoutDirection, and FormOptionality types
+ * @position Context for form layout direction + default-optionality detection
  *
  * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/FormLayout/FormLayout.tsx (prop + context value)
+ * - /packages/core/src/Field/FieldLabel.tsx (indicator resolution)
+ * - /packages/core/src/FormLayout/index.ts (exports if types change)
  */
 
 import {createContext} from 'react';
@@ -22,15 +25,27 @@ import {createContext} from 'react';
  *   of their inputs (settings/admin panel pattern).
  */
 export type FormLayoutDirection =
-  | 'vertical'
-  | 'horizontal'
-  | 'horizontal-labels';
+  'vertical' | 'horizontal' | 'horizontal-labels';
 
 /**
- * Context for detecting which form layout direction a component is rendered in.
- * Children can use this to adapt their rendering based on the parent layout.
+ * Which state a form treats as its default, so only the *exception* carries a
+ * visible optional/required indicator.
+ *
+ * - `'optional'` — fields are optional unless a field opts into `isRequired`;
+ *   only required fields show an indicator.
+ * - `'required'` — fields are required unless a field opts into `isOptional`;
+ *   only optional fields show an indicator.
+ */
+export type FormOptionality = 'optional' | 'required';
+
+/**
+ * Context for detecting which form layout a component is rendered in. Children
+ * can use this to adapt their rendering based on the parent layout — direction
+ * for spatial arrangement, and `defaultOptionality` so a field can suppress the
+ * indicator that merely restates the form-wide default.
  */
 export const FormLayoutContext = createContext<{
   direction: FormLayoutDirection;
+  defaultOptionality?: FormOptionality;
 }>({direction: 'vertical'});
 FormLayoutContext.displayName = 'FormLayoutContext';

package/src/FormLayout/index.ts

@@ -13,5 +13,5 @@
 
 export {FormLayout} from './FormLayout';
 export type {FormLayoutProps} from './FormLayout';
-export type {FormLayoutDirection} from './FormLayoutContext';
+export type {FormLayoutDirection, FormOptionality} from './FormLayoutContext';
 export {FormLayoutContext} from './FormLayoutContext';

package/src/HoverCard/HoverCard.doc.mjs

@@ -73,6 +73,13 @@ export const docs = {
           description: 'Controls when focus events trigger the hover card.',
           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 (a button, link, or form control), whose tap belongs to the control. tap always opens. none never opens on touch. A tap-opened card is dismissed by a tap outside it.',
+          default: "'auto'",
+        },
         {
           name: 'isEnabled',
           type: 'boolean',
@@ -111,6 +118,7 @@ export const docs = {
       { guidance: true, description: 'Keep content supplementary; hover cards should enhance understanding without blocking the primary workflow.' },
       { guidance: true, description: 'Provide a dashed underline on text triggers so users know the element is hoverable.' },
       { guidance: true, description: 'Use the hook API (useHoverCard) when you need more control over timing or placement.' },
+      { guidance: true, description: 'Leave touchTrigger on auto so a tap opens the card on triggers that do nothing else, and stays out of the way on triggers that perform an action.' },
       { guidance: false, description: 'Place critical actions or required information inside a hover card; users may miss content that only appears on hover.' },
       { guidance: false, description: 'Use a hover card when a simple Tooltip or Popover would suffice.' },
       { guidance: false, description: 'Use a HoverCard for content the user must interact with; it disappears when the cursor leaves.' },
@@ -188,6 +196,13 @@ export const docsZh = {
           description: '控制焦点事件何时触发悬浮卡片。',
           default: "'auto'",
         },
+        {
+          name: 'touchTrigger',
+          type: "'auto' | 'tap' | 'none'",
+          description:
+            '在没有悬停的触摸设备上，轻点的行为。auto：轻点即打开，除非触发元素本身会执行操作（按钮、链接、表单控件），此时轻点归该控件所有。tap：始终轻点打开。none：触摸永不打开。轻点打开的卡片可通过点击卡片外部关闭。',
+          default: "'auto'",
+        },
         {
           name: 'isEnabled',
           type: 'boolean',
@@ -226,6 +241,7 @@ export const docsZh = {
       { guidance: true, description: 'Keep content supplementary; hover cards should enhance understanding without blocking the primary workflow.' },
       { guidance: true, description: 'Provide a dashed underline on text triggers so users know the element is hoverable.' },
       { guidance: true, description: 'Use the hook API (useHoverCard) when you need more control over timing or placement.' },
+      { guidance: true, description: 'Leave touchTrigger on auto so a tap opens the card on triggers that do nothing else, and stays out of the way on triggers that perform an action.' },
       { guidance: false, description: 'Place critical actions or required information inside a hover card; users may miss content that only appears on hover.' },
       { guidance: false, description: 'Use a hover card when a simple Tooltip or Popover would suffice.' },
       { guidance: false, description: 'Use a HoverCard for content the user must interact with; it disappears when the cursor leaves.' },
@@ -244,6 +260,7 @@ export const docsDense = {
       { guidance: true, description: 'Keep content supplementary; hover cards should enhance understanding without blocking the primary workflow.' },
       { guidance: true, description: 'Provide a dashed underline on text triggers so users know the element is hoverable.' },
       { guidance: true, description: 'Use the hook API (useHoverCard) when you need more control over timing or placement.' },
+      { guidance: true, description: 'Leave touchTrigger on auto so a tap opens the card on triggers that do nothing else, and stays out of the way on triggers that perform an action.' },
       { guidance: false, description: 'Place critical actions or required information inside a hover card; users may miss content that only appears on hover.' },
       { guidance: false, description: 'Use a hover card when a simple Tooltip or Popover would suffice.' },
       { guidance: false, description: 'Use a HoverCard for content the user must interact with; it disappears when the cursor leaves.' },
@@ -263,6 +280,7 @@ export const docsDense = {
         delay: 'Show delay in ms.',
         hideDelay: 'Hide delay in ms.',
         focusTrigger: 'Controls when focus events trigger hover card.',
+        touchTrigger: 'Tap behavior where there is no hover. auto = tap opens unless the trigger acts (button/link/control); tap = always opens; none = never on touch. Tap-opened cards close on a tap outside.',
         isEnabled: 'Enable/disable hover + focus triggers.',
         label: 'Accessible name for the popup. With label: named role="dialog"; without: role="group".',
         onOpenChange: 'Callback when visibility changes; true=shown, false=hidden.',

package/src/HoverCard/HoverCard.test.tsx

@@ -25,6 +25,7 @@ import {StrictMode} from 'react';
 import {Button} from '../Button/Button';
 import {Theme, defineTheme} from '../theme';
 import {HoverCard} from './HoverCard';
+import {__resetInteractionModalityForTest} from '../utils/interactionModality';
 
 // Store original matches to restore later
 const originalMatches = HTMLElement.prototype.matches;
@@ -804,4 +805,192 @@ describe('HoverCard', () => {
       container.remove();
     });
   });
+
+  describe('touch', () => {
+    // The modality is document-global; a tap in one case must not decide the
+    // next one's answer.
+    beforeEach(() => {
+      __resetInteractionModalityForTest();
+    });
+
+    /** A tap: the pointer sequence a finger produces before hover is faked. */
+    const tap = (element: HTMLElement) => {
+      // A finger's arrival fires pointerenter too, and that is the path a pen
+      // must not take — cover it here rather than starting at pointerdown.
+      fireEvent.pointerEnter(element, {pointerType: 'touch'});
+      fireEvent.pointerDown(element, {pointerType: 'touch'});
+      fireEvent.pointerUp(element, {pointerType: 'touch'});
+      // Touch synthesizes hover after the press; the card must not act on it.
+      fireEvent.mouseEnter(element);
+    };
+
+    it('opens on a tap when the trigger performs no action', async () => {
+      const onOpenChange = vi.fn();
+      render(
+        <HoverCard
+          content={<span>Card content</span>}
+          onOpenChange={onOpenChange}
+          delay={300}>
+          Ruby Cheung
+        </HoverCard>,
+      );
+
+      tap(screen.getByText('Ruby Cheung'));
+
+      // Immediately: a tap is a decision, not hover intent, so no delay applies.
+      await waitFor(() => {
+        expect(onOpenChange).toHaveBeenCalledWith(true);
+      });
+    });
+
+    it('stays shut on a tap when the trigger performs an action', async () => {
+      const onOpenChange = vi.fn();
+      render(
+        <HoverCard
+          content={<span>Card content</span>}
+          onOpenChange={onOpenChange}
+          delay={0}>
+          <button type="button">Save</button>
+        </HoverCard>,
+      );
+
+      const trigger = screen.getByRole('button', {name: 'Save'});
+      tap(trigger);
+      // A tap focuses what it activates; that focus must not reopen the card.
+      fireEvent.focusIn(trigger);
+
+      await new Promise(resolve => setTimeout(resolve, 50));
+      expect(onOpenChange).not.toHaveBeenCalledWith(true);
+    });
+
+    it('opens on a tap of an action trigger when touchTrigger is "tap"', async () => {
+      const onOpenChange = vi.fn();
+      render(
+        <HoverCard
+          content={<span>Card content</span>}
+          onOpenChange={onOpenChange}
+          touchTrigger="tap"
+          delay={0}>
+          <button type="button">Details</button>
+        </HoverCard>,
+      );
+
+      tap(screen.getByRole('button', {name: 'Details'}));
+
+      await waitFor(() => {
+        expect(onOpenChange).toHaveBeenCalledWith(true);
+      });
+    });
+
+    it('survives a tap on its own content', async () => {
+      const onOpenChange = vi.fn();
+      render(
+        <HoverCard
+          content={<button type="button">Follow</button>}
+          onOpenChange={onOpenChange}
+          delay={0}
+          hideDelay={0}>
+          Ruby Cheung
+        </HoverCard>,
+      );
+
+      tap(screen.getByText('Ruby Cheung'));
+      await waitFor(() => {
+        expect(onOpenChange).toHaveBeenCalledWith(true);
+      });
+      onOpenChange.mockClear();
+
+      const action = await screen.findByRole('button', {
+        name: 'Follow',
+        hidden: true,
+      });
+      fireEvent.pointerDown(action, {pointerType: 'touch'});
+
+      await new Promise(resolve => setTimeout(resolve, 50));
+      expect(onOpenChange).not.toHaveBeenCalledWith(false);
+    });
+
+    it('closes on a tap outside', async () => {
+      const onOpenChange = vi.fn();
+      render(
+        <>
+          <HoverCard
+            content={<span>Card content</span>}
+            onOpenChange={onOpenChange}
+            delay={0}
+            hideDelay={0}>
+            Ruby Cheung
+          </HoverCard>
+          <button type="button">Elsewhere</button>
+        </>,
+      );
+
+      tap(screen.getByText('Ruby Cheung'));
+      await waitFor(() => {
+        expect(onOpenChange).toHaveBeenCalledWith(true);
+      });
+
+      fireEvent.pointerDown(screen.getByRole('button', {name: 'Elsewhere'}), {
+        pointerType: 'touch',
+      });
+
+      await waitFor(() => {
+        expect(onOpenChange).toHaveBeenCalledWith(false);
+      });
+    });
+
+    it('closes on a second tap of the trigger', async () => {
+      const onOpenChange = vi.fn();
+      render(
+        <HoverCard
+          content={<span>Card content</span>}
+          onOpenChange={onOpenChange}
+          delay={0}
+          hideDelay={0}>
+          Ruby Cheung
+        </HoverCard>,
+      );
+
+      const trigger = screen.getByText('Ruby Cheung');
+      tap(trigger);
+      await waitFor(() => {
+        expect(onOpenChange).toHaveBeenCalledWith(true);
+      });
+
+      tap(trigger);
+      await waitFor(() => {
+        expect(onOpenChange).toHaveBeenCalledWith(false);
+      });
+    });
+
+    it('ignores the focus a tap leaves behind, but not keyboard focus', async () => {
+      const onOpenChange = vi.fn();
+      render(
+        <HoverCard
+          content={<span>Card content</span>}
+          onOpenChange={onOpenChange}
+          delay={0}>
+          <button type="button">Save</button>
+        </HoverCard>,
+      );
+
+      const trigger = screen.getByRole('button', {name: 'Save'});
+      // The tap goes to the button, as `auto` decides for an action trigger —
+      // and the focus it leaves behind must not put the card over the control
+      // the user just pressed.
+      tap(trigger);
+      fireEvent.focusIn(trigger);
+      await new Promise(resolve => setTimeout(resolve, 50));
+      expect(onOpenChange).not.toHaveBeenCalledWith(true);
+
+      // Reaching for the keyboard ends the touch interaction: the same trigger,
+      // focused by Tab, still opens.
+      fireEvent.keyDown(document, {key: 'Tab'});
+      fireEvent.focusIn(trigger);
+
+      await waitFor(() => {
+        expect(onOpenChange).toHaveBeenCalledWith(true);
+      });
+    });
+  });
 });

package/src/HoverCard/HoverCard.tsx

@@ -18,12 +18,19 @@
 import {useCallback, useRef, type ReactElement, type ReactNode} from 'react';
 import {useIsomorphicLayoutEffect} from '../hooks/useIsomorphicLayoutEffect';
 import * as stylex from '@stylexjs/stylex';
-import {useHoverCard, type HoverCardFocusTrigger} from './useHoverCard';
+import {
+  useHoverCard,
+  type HoverCardFocusTrigger,
+  type HoverCardTouchTrigger,
+} from './useHoverCard';
 import type {LayerAlignment, LayerPlacement} from '../Layer/useLayer';
 import type {BaseProps} from '../BaseProps';
 import {colorVars, spacingVars} from '../theme/tokens.stylex';
 
-export type {HoverCardFocusTrigger} from './useHoverCard';
+export type {
+  HoverCardFocusTrigger,
+  HoverCardTouchTrigger,
+} from './useHoverCard';
 
 const styles = stylex.create({
   wrapperContents: {
@@ -88,6 +95,17 @@ export interface HoverCardProps extends Pick<
    */
   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.
@@ -174,6 +192,7 @@ export function HoverCard({
   delay = 300,
   hideDelay = 200,
   focusTrigger = 'auto',
+  touchTrigger = 'auto',
   isEnabled = true,
   label,
   onOpenChange,
@@ -206,6 +225,7 @@ export function HoverCard({
     delay,
     hideDelay,
     focusTrigger,
+    touchTrigger,
     isEnabled,
     label,
     isOpen,

package/src/HoverCard/index.ts

@@ -15,6 +15,7 @@
 export {useHoverCard} from './useHoverCard';
 export type {
   HoverCardFocusTrigger,
+  HoverCardTouchTrigger,
   HoverCardOptions,
   HoverCardReturn,
 } from './useHoverCard';