Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

fix(FieldLabel): a tap on the label's info icon opens its help without activating the control (#9089)

Christopher Chedeaucfbc66fb77e7
diff --git a/.changeset/fieldlabel-info-icon-tap.md b/.changeset/fieldlabel-info-icon-tap.md
new file mode 100644
index 0000000000..db84de8dbf
--- /dev/null
+++ b/.changeset/fieldlabel-info-icon-tap.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[feat] FieldLabel: a tap on the label's info icon (`labelTooltip`) opens its help without also toggling or focusing the control (`component:FieldLabel` FR9). Before, the tap that opened the help also activated the label's control, as a tap anywhere on a native label does: on a touch screen it focused the field, raising the keyboard, or toggled the switch or checkbox the label names, an unintended second action. Now a tap by finger or pen opens the help alone; a mouse click on the icon still activates the control like the rest of the label, and hover still shows the help.
+
+@vjeux
diff --git a/packages/core/src/Field/Field.doc.mjs b/packages/core/src/Field/Field.doc.mjs
index dc5a0acaf9..741a2864c6 100644
--- a/packages/core/src/Field/Field.doc.mjs
+++ b/packages/core/src/Field/Field.doc.mjs
@@ -120,7 +120,8 @@ export const docs = {
{
name: 'labelTooltip',
type: 'string',
- description: 'Tooltip text to display in an info icon at the end of the label.',
+ description:
+ 'Tooltip text to display in an info icon at the end of the label. Hover shows it; on a touch screen a tap on the icon opens it without focusing the field, while a mouse click on the icon focuses the field like the rest of the label.',
},
{
name: 'status',
diff --git a/packages/core/src/Field/FieldLabel.doc.mjs b/packages/core/src/Field/FieldLabel.doc.mjs
index 0246259854..def017bf56 100644
--- a/packages/core/src/Field/FieldLabel.doc.mjs
+++ b/packages/core/src/Field/FieldLabel.doc.mjs
@@ -72,7 +72,8 @@ export const docs = {
{
name: 'labelTooltip',
type: 'string',
- description: 'Tooltip text for the info icon after the label.',
+ description:
+ 'Tooltip text for the info icon after the label. Hover shows it; on a touch screen a tap on the icon opens it without focusing the field or toggling the control, while a mouse click on the icon activates the control like the rest of the label.',
},
{
name: 'description',
@@ -176,7 +177,8 @@ export const docsZh = {
{
name: 'labelTooltip',
type: 'string',
- description: '标签后信息图标的工具提示文本。',
+ description:
+ '标签后信息图标的工具提示文本。悬停即可显示;在触摸屏上点按图标即可打开,不会聚焦字段或切换控件;用鼠标点击图标则与点击标签其他部分一样激活控件。',
},
{
name: 'description',
diff --git a/packages/core/src/Field/FieldLabel.spec.md b/packages/core/src/Field/FieldLabel.spec.md
index 48b84addf7..ecc40a708b 100644
--- a/packages/core/src/Field/FieldLabel.spec.md
+++ b/packages/core/src/Field/FieldLabel.spec.md
@@ -15,6 +15,7 @@ verified_by:
packages/core/src/Field/FieldLabel.test.tsx,
packages/core/src/FormLayout/FormLayout.test.tsx,
packages/core/src/Field/__tests__/FieldLabelAudit.a11y.chromium.spec.ts,
+ packages/core/src/Field/__tests__/FieldLabelTap.a11y.chromium.spec.ts,
packages/core/src/theme/themingTargets.test.ts,
packages/core/src/docPropReferences.test.ts,
packages/core/src/docPropLiterals.test.ts,
@@ -37,15 +38,15 @@ system_specs: [spec:AST-020/FR1]
## Contract at a glance
-| Area | Contract |
-| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Public contract | `FieldLabel` renders a visible or visually hidden label group for one control or a caller-labelled group, with optional description, optionality indicator, icon, tooltip, label-element BaseProps, and label-element ref. |
-| Behavior | Single-control mode uses a native label; group mode uses a labelled span. A description adds a wrapper div, while caller props and ref stay on the inner label element. Description clicks forward only to one associated control. |
-| End-user impact | People can identify a control or group, hear supporting text separately from its name, and activate eligible controls from the complete visible label area. The current tooltip remains unavailable to keyboard and screen-reader users. |
-| Builder impact | Builders provide stable control and description IDs, select group mode when labelling a composite, and wire `aria-labelledby` or `aria-describedby` on the controlled surface. |
-| Compatibility/readiness | Records shipped behavior; no API, default, or DOM change. Group mode renders a span while public types promise label props and ref, and the tooltip icon exposes its content only to a pointer; both are listed under Current-state impact. |
-| Review checks | Reject a lost native/group association, nested description in the accessible name, forwarded clicks from group or interactive description content, dropped label-element props/ref, hidden tooltip content, or undocumented public prop. |
-| Governing rules | Established public interface; HTML label semantics; WCAG 2.2 SC 2.1.1, SC 4.1.2; `architecture:public-component-api/INV1,INV5–INV9,INV12`; `architecture:component-theming-surface/INV3–INV7`; `spec:AST-020/FR1`. |
+| Area | Contract |
+| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract | `FieldLabel` renders a visible or visually hidden label group for one control or a caller-labelled group, with optional description, optionality indicator, icon, tooltip, label-element BaseProps, and label-element ref. |
+| Behavior | Single-control mode uses a native label; group mode uses a labelled span. A description adds a wrapper div, while caller props and ref stay on the inner label element. Description clicks forward only to one associated control. |
+| End-user impact | People can identify a control or group, hear supporting text separately from its name, and activate eligible controls from the complete visible label area; a tap on the tooltip's info icon opens or closes the tooltip instead (DEC-1). The current tooltip remains unavailable to keyboard and screen-reader users. |
+| Builder impact | Builders provide stable control and description IDs, select group mode when labelling a composite, and wire `aria-labelledby` or `aria-describedby` on the controlled surface. |
+| Compatibility/readiness | Records shipped behavior and DEC-1; no API, default, or DOM change. Group mode renders a span while public types promise label props and ref, and the tooltip icon exposes its content only to a pointer; both are listed under Current-state impact. |
+| Review checks | Reject a lost native/group association, nested description in the accessible name, forwarded clicks from group or interactive description content, dropped label-element props/ref, hidden tooltip content, or undocumented public prop. |
+| Governing rules | Established public interface; HTML label semantics; WCAG 2.2 SC 2.1.1, SC 4.1.2; `architecture:public-component-api/INV1,INV5–INV9,INV12`; `architecture:component-theming-surface/INV3–INV7`; `spec:AST-020/FR1`. |
This table is a review projection; the body below is authoritative.
@@ -56,9 +57,9 @@ This table is a review projection; the body below is authoritative.
## Compatibility and migration
- Released default preserved: yes.
-- Compatibility class: records shipped behavior; no public prop, default, export, or DOM change.
+- Compatibility class: records shipped behavior and DEC-1; no public prop, default, export, or DOM change.
- Controlled/uncontrolled behavior: not applicable.
-- Migration decision: none; the ref typing is OQ1.
+- Migration decision: DEC-1 needs no caller change; the ref typing is OQ1.
## Ownership boundary
@@ -79,15 +80,15 @@ This table is a review projection; the body below is authoritative.
## Public concepts
-| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |
-| ---------------------- | ----------------------------------------------- | ----------------------------------------------------------------------------------------- | ----------------------------------------- | -------------- | ---------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------ |
-| label mode | single control; group | Chooses a native `<label htmlFor>` or a `<span>` referenced through `aria-labelledby`. | All uses. | single control | `component:FieldLabel` | released | Boolean-constrained; see OQ1 for root/ref typing. |
-| label visibility | visible; visually hidden | Keeps label and description accessible while removing their layout space when hidden. | Both label modes. | visible | `component:FieldLabel` | released | Boolean-constrained. |
-| optionality marker | none; optional; required | Shows the localized exception to FormLayout's form-level optionality default. | Visible and hidden labels. | none | `component:FieldLabel` | released | When both booleans are true, optional wins visibly, unless FormLayout's default is optional, which suppresses it and shows required. |
-| leading icon | absent; icon type; rendered node | Adds visual content before the label text. | Both label modes. | absent | `component:FieldLabel` | released | Rendered through the shared icon slot. |
-| explanatory tooltip | absent; localized string | Adds the shared info-icon anchor and tooltip surface after the label. | Both label modes. | absent | `component:FieldLabel` | released | The anchor is pointer-only (FR8 gap). |
-| supporting description | absent; rendered node with optional explicit ID | Keeps supporting content separate from the accessible name and available for description. | Both label modes. | absent | `component:FieldLabel` | released | Missing ID leaves association to the caller. |
-| description activation | forwarding; non-forwarding | For one control, noninteractive description clicks mirror native-label activation. | Single mode only. | forwarding | `component:FieldLabel` | released | Group mode and interactive descendants do not forward. |
+| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |
+| ---------------------- | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- | -------------- | ---------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| label mode | single control; group | Chooses a native `<label htmlFor>` or a `<span>` referenced through `aria-labelledby`. | All uses. | single control | `component:FieldLabel` | released | Boolean-constrained; see OQ1 for root/ref typing. |
+| label visibility | visible; visually hidden | Keeps label and description accessible while removing their layout space when hidden. | Both label modes. | visible | `component:FieldLabel` | released | Boolean-constrained. |
+| optionality marker | none; optional; required | Shows the localized exception to FormLayout's form-level optionality default. | Visible and hidden labels. | none | `component:FieldLabel` | released | When both booleans are true, optional wins visibly, unless FormLayout's default is optional, which suppresses it and shows required. |
+| leading icon | absent; icon type; rendered node | Adds visual content before the label text. | Both label modes. | absent | `component:FieldLabel` | released | Rendered through the shared icon slot. |
+| explanatory tooltip | absent; localized string | Adds the shared info-icon anchor and tooltip surface after the label; a tap on the icon opens or closes the tooltip without activating the control (FR9). | Both label modes. | absent | `component:FieldLabel` | released | The anchor is pointer-only (FR8 gap). |
+| supporting description | absent; rendered node with optional explicit ID | Keeps supporting content separate from the accessible name and available for description. | Both label modes. | absent | `component:FieldLabel` | released | Missing ID leaves association to the caller. |
+| description activation | forwarding; non-forwarding | For one control, noninteractive description clicks mirror native-label activation. | Single mode only. | forwarding | `component:FieldLabel` | released | Group mode and interactive descendants do not forward. |
## Behavioral and layout contract
@@ -101,6 +102,7 @@ This table is a review projection; the body below is authoritative.
| FR6 | Accepted data, ARIA, DOM, class, style, event, and `xstyle` inputs compose on the label element without replacing the component-owned target or association. When a description renders, the outer wrapper is layout-only and caller props stay on the inner label element. | `architecture:public-component-api/INV5–INV7` |
| FR7 | The public ref and label-element props MUST describe the element FieldLabel renders in each mode; which root element and public type group mode uses is OQ1. Implementation gap: group mode renders a `<span>` while the public BaseProps and ref types are fixed to `HTMLLabelElement`. | `architecture:public-component-api/INV8,INV9`; current runtime/types |
| FR8 | The optional tooltip's explanatory content MUST be reachable by keyboard (WCAG 2.2 SC 2.1.1) and its trigger MUST have an accessible name and role (WCAG 2.2 SC 4.1.2). Implementation gap: it anchors to an anonymous, nonfocusable info icon, so the content is pointer-only. | WCAG 2.2 SC 2.1.1, SC 4.1.2; `spec:AST-020/FR1` |
+| FR9 | A tap on the tooltip's info icon, by finger or pen, opens or closes the tooltip as `component:Tooltip` FR5 states under `touchTrigger="tap"`, and does not activate the associated control. A mouse click on the icon activates the control like the rest of the label, and hover shows the tooltip. | DEC-1 |
### Allowed variation
@@ -157,6 +159,7 @@ No current repository design record governs component-local visual tuning. The i
| FR6, ORD2 | `FieldLabel.test.tsx` ref, layout-item, and label-target cases; `themingTargets.test.ts` | Ref; composed target; with a description wrapper | A dropped ref or a lost `field-label` target fails; a rendered class absent from the documented targets fails. Evidence gap: no test asserts caller class, style, `xstyle`, data, and event props on the inner label element with a description wrapper. | `audit:FieldLabel/api` |
| FR7 | Evidence gap: no type test pins the public ref and props against the rendered group span | — | — | `audit:FieldLabel/api` |
| FR8, AR5 | `FieldLabelAudit.a11y.chromium.spec.ts` tooltip-anchor count | Tooltip present | The audit records the one anonymous, nonfocusable anchor; it changes when the FR8 gap closes. | `audit:FieldLabel/accessibility` |
+| FR9 | `FieldLabel.test.tsx` finger-tap, pen-tap, and mouse-click checkbox cases; `FieldLabelTap.a11y.chromium.spec.ts` touch-tap and mouse-click text-field cases | Checkbox; text field | A tap that toggles or focuses the control, or a mouse click that does not activate it, fails. | `audit:FieldLabel/accessibility` |
| PR1 | Evidence gap: no test asserts the absence of retained resources | — | — | `audit:FieldLabel/code-health` |
| Documentation | `docPropLiterals.test.ts`; `docPropReferences.test.ts` | Documented props and defaults | A documented literal or prop reference that drifts from the source type fails. | `audit:FieldLabel/docs` |
| RTL applicability | `apps/storybook/rtl-audit/verified-not-applicable.json` entry for `core/FieldLabel` | Checked-in FieldLabel stories | A story that gains directional placement or behavior makes the not-applicable entry stale. | `audit:FieldLabel/i18n-rtl` |
@@ -171,7 +174,13 @@ No current repository design record governs component-local visual tuning. The i
## Decision log
-No component-local decision. The label-element and ref typing is OQ1.
+- **DEC-1 — A tap on the info icon is for its help.** A tap on the
+ tooltip's info icon, by finger or pen, opens or closes the tooltip and does not
+ activate the label's control, so asking for help never toggles a switch or
+ focuses a field. A mouse click on the icon keeps native label activation,
+ and hover shows the help. Rejected: leaving the tap to the label.
+
+The label-element and ref typing is OQ1.
## Open questions
diff --git a/packages/core/src/Field/FieldLabel.test.tsx b/packages/core/src/Field/FieldLabel.test.tsx
index b35f31844e..e5ce6f7754 100644
--- a/packages/core/src/Field/FieldLabel.test.tsx
+++ b/packages/core/src/Field/FieldLabel.test.tsx
@@ -9,13 +9,14 @@
* SYNC: When FieldLabel.tsx changes, update tests to match new behavior
*/
-import {describe, it, expect, vi} from 'vitest';
-import {render, screen} from '@testing-library/react';
+import {describe, it, expect, vi, beforeEach, afterEach} from 'vitest';
+import {render, screen, fireEvent, waitFor} from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import {TestIcon} from '../__tests__/TestIcon';
import {InternationalizationProvider} from '../i18n';
import {FieldLabel} from './FieldLabel';
import {themeProps} from '../utils/themeProps';
+import {__resetInteractionModalityForTest} from '../utils/interactionModality';
describe('FieldLabel', () => {
it('renders label text', () => {
@@ -137,6 +138,119 @@ describe('FieldLabel', () => {
expect(document.querySelector('svg')).toBeInTheDocument();
});
+ describe('labelTooltip under each pointer', () => {
+ const originalShowPopover = HTMLElement.prototype.showPopover;
+ const originalHidePopover = HTMLElement.prototype.hidePopover;
+ const originalMatches = HTMLElement.prototype.matches;
+ beforeEach(() => {
+ __resetInteractionModalityForTest();
+ // jsdom has no Popover API: keep the open state where the test reads it.
+ HTMLElement.prototype.showPopover = function (this: HTMLElement) {
+ this.setAttribute('popover-open', '');
+ };
+ HTMLElement.prototype.hidePopover = function (this: HTMLElement) {
+ this.removeAttribute('popover-open');
+ };
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
+ (HTMLElement.prototype as any).matches = function (
+ this: HTMLElement,
+ selector: string,
+ ): boolean {
+ return selector === ':popover-open'
+ ? this.hasAttribute('popover-open')
+ : originalMatches.call(this, selector);
+ };
+ });
+ afterEach(() => {
+ HTMLElement.prototype.showPopover = originalShowPopover;
+ HTMLElement.prototype.hidePopover = originalHidePopover;
+ HTMLElement.prototype.matches = originalMatches;
+ });
+
+ /** A finger's (or a pen's) tap, in the order a browser dispatches it. */
+ const tap = (element: HTMLElement, pointerType = 'touch') => {
+ fireEvent.pointerEnter(element, {pointerType});
+ fireEvent.pointerDown(element, {pointerType});
+ fireEvent.pointerUp(element, {pointerType});
+ fireEvent.mouseEnter(element);
+ fireEvent.click(element);
+ };
+
+ /** The info icon the help tooltip is attached to, inside the label. */
+ const infoIcon = (labelText: string) =>
+ screen
+ .getByText(labelText)
+ .closest('label')
+ ?.querySelector('[aria-describedby]') as HTMLElement;
+
+ it('opens the help on a tap of its icon and leaves a checkbox alone', async () => {
+ render(
+ <>
+ <FieldLabel
+ label="Notifications"
+ inputID="notify"
+ labelTooltip="Sends one digest a day"
+ />
+ <input type="checkbox" id="notify" />
+ </>,
+ );
+
+ tap(infoIcon('Notifications'));
+
+ await waitFor(() => {
+ expect(screen.getByRole('tooltip', {hidden: true})).toHaveAttribute(
+ 'popover-open',
+ );
+ });
+ // The tap asked for the help, not for the label's control.
+ expect(screen.getByRole('checkbox')).not.toBeChecked();
+ });
+
+ it('opens the help on a pen tap of its icon and leaves a checkbox alone', async () => {
+ render(
+ <>
+ <FieldLabel
+ label="Alerts"
+ inputID="alerts"
+ labelTooltip="Only for failed runs"
+ />
+ <input type="checkbox" id="alerts" />
+ </>,
+ );
+
+ tap(infoIcon('Alerts'), 'pen');
+
+ await waitFor(() => {
+ expect(screen.getByRole('tooltip', {hidden: true})).toHaveAttribute(
+ 'popover-open',
+ );
+ });
+ expect(screen.getByRole('checkbox')).not.toBeChecked();
+ });
+
+ it('leaves a mouse click on its icon to the label, which toggles a checkbox', () => {
+ render(
+ <>
+ <FieldLabel
+ label="Auto-save"
+ inputID="autosave"
+ labelTooltip="Saves each change as you type"
+ />
+ <input type="checkbox" id="autosave" />
+ </>,
+ );
+
+ const icon = infoIcon('Auto-save');
+ fireEvent.pointerDown(icon, {pointerType: 'mouse'});
+ fireEvent.pointerUp(icon, {pointerType: 'mouse'});
+ fireEvent.click(icon);
+
+ // A mouse click anywhere on a native label, its info icon included,
+ // activates the label's control.
+ expect(screen.getByRole('checkbox')).toBeChecked();
+ });
+ });
+
describe('description click forwarding', () => {
// Renders a real control with the target id so click-forwarding has
// something to hit, alongside the label whose description forwards clicks.
diff --git a/packages/core/src/Field/FieldLabel.tsx b/packages/core/src/Field/FieldLabel.tsx
index ecdf44e7ce..7ee7cc4d3b 100644
--- a/packages/core/src/Field/FieldLabel.tsx
+++ b/packages/core/src/Field/FieldLabel.tsx
@@ -16,7 +16,15 @@
* - /packages/core/locales/en.json (@astryx.field.required / @astryx.field.optional)
*/
-import {use, useMemo, useRef, type ReactNode, type RefObject} from 'react';
+import {
+ use,
+ useMemo,
+ useRef,
+ type MouseEvent,
+ type PointerEvent,
+ type ReactNode,
+ type RefObject,
+} from 'react';
import * as stylex from '@stylexjs/stylex';
import type {BaseProps} from '../BaseProps';
import {mergeProps} from '../utils/mergeProps';
@@ -31,6 +39,7 @@ import {
import {Icon, renderIconSlot} from '../Icon/Icon';
import type {IconType} from '../Icon';
import {Tooltip} from '../Tooltip/Tooltip';
+import {TOUCH_POINTER_TYPES} from '../Layer/useTouchTrigger';
import {useTranslator} from '../i18n/useTranslator';
import {themeProps} from '../utils/themeProps';
import {useInputContainer} from '../hooks/useInputContainer';
@@ -256,6 +265,22 @@ export function FieldLabel({
// a ref-shaped object, since FieldLabel points at the control by id rather
// than holding a ref to it.
const descriptionRef = useRef<HTMLSpanElement>(null);
+ // A tap on the info icon asks for the help, so it stops there: it does not
+ // go on to activate the label's control, as a press anywhere else on the
+ // label would (focus the field, toggle a switch). A mouse click on the icon
+ // keeps that native activation, and hover shows the help.
+ const iconPressIsTapRef = useRef(false);
+ const handleIconPointerDown = (event: PointerEvent<Element>) => {
+ // A finger or a pen: the pointers whose tap the shared touch trigger
+ // answers, so the ones whose tap opens or closes the help.
+ iconPressIsTapRef.current = TOUCH_POINTER_TYPES.has(event.pointerType);
+ };
+ const handleIconClick = (event: MouseEvent<Element>) => {
+ if (iconPressIsTapRef.current) {
+ event.preventDefault();
+ }
+ iconPressIsTapRef.current = false;
+ };
const controlRef = useMemo<RefObject<HTMLElement | null>>(
() => ({
get current() {
@@ -285,8 +310,17 @@ export function FieldLabel({
</span>
)}
{labelTooltip && (
- <Tooltip content={labelTooltip} placement="above">
- <Icon icon="info" size="sm" color="inherit" />
+ // The icon's one job is to reveal the help, so a tap on it opens or
+ // closes the help (`touchTrigger="tap"`), although it sits inside a
+ // `<label>`.
+ <Tooltip content={labelTooltip} placement="above" touchTrigger="tap">
+ <Icon
+ icon="info"
+ size="sm"
+ color="inherit"
+ onPointerDown={handleIconPointerDown}
+ onClick={handleIconClick}
+ />
</Tooltip>
)}
</>
diff --git a/packages/core/src/Field/__tests__/FieldLabelTap.a11y.chromium.spec.ts b/packages/core/src/Field/__tests__/FieldLabelTap.a11y.chromium.spec.ts
new file mode 100644
index 0000000000..e87985bea7
--- /dev/null
+++ b/packages/core/src/Field/__tests__/FieldLabelTap.a11y.chromium.spec.ts
@@ -0,0 +1,80 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file FieldLabelTap.a11y.chromium.spec.ts
+ * @input The `Core/FieldLabel` States story in a built Storybook, in Chromium:
+ * the Nickname field, whose label carries a `labelTooltip` info icon.
+ * @output Real-browser proof of FieldLabel FR9: a touch tap on the info icon
+ * shows its help and leaves the text field unfocused, while a mouse click on
+ * the icon focuses the field like a click anywhere else on the label.
+ * @position Run with `pnpm test:a11y-contract`. Focus from label activation
+ * needs a real browser: jsdom's label activation never focuses a text input.
+ */
+
+import {expect, test, type Locator, type Page} from '@playwright/test';
+import {
+ DEFAULT_STORYBOOK_DIR,
+ serveStorybook,
+ type StaticServer,
+} from '@astryxdesign/a11y-spec/storybook';
+
+const STORY = 'core-fieldlabel--states';
+const HELP = 'This name is shown to collaborators.';
+const FIELD_ID = 'field-label-optional';
+
+let storybook: StaticServer;
+
+test.beforeAll(async () => {
+ storybook = await serveStorybook(DEFAULT_STORYBOOK_DIR);
+});
+
+test.afterAll(async () => {
+ await storybook?.close();
+});
+
+/** Opens the story and returns the Nickname label's info icon. */
+async function openInfoIcon(page: Page): Promise<Locator> {
+ await page.goto(`${storybook.origin}/iframe.html?id=${STORY}&viewMode=story`);
+ const icon = page.locator(`label[for="${FIELD_ID}"] [aria-describedby]`);
+ await icon.waitFor();
+ return icon;
+}
+
+async function focusedId(page: Page): Promise<string> {
+ return page.evaluate(() => document.activeElement?.id ?? '');
+}
+
+test.describe('a touch tap on the info icon', () => {
+ test.use({
+ hasTouch: true,
+ isMobile: true,
+ viewport: {width: 390, height: 844},
+ });
+
+ test('shows the help and leaves the field unfocused', async ({page}) => {
+ const icon = await openInfoIcon(page);
+ const box = await icon.boundingBox();
+ if (box == null) {
+ throw new Error('the info icon has no layout box');
+ }
+ await page.touchscreen.tap(box.x + box.width / 2, box.y + box.height / 2);
+
+ await expect(
+ page.getByRole('tooltip').filter({hasText: HELP}),
+ ).toBeVisible();
+ // The tap asked for the help, so the label did not go on to focus its
+ // field (which on a phone would raise the keyboard over the help).
+ expect(await focusedId(page)).not.toBe(FIELD_ID);
+ });
+});
+
+test.describe('a mouse click on the info icon', () => {
+ test('focuses the field, like a click anywhere else on the label', async ({
+ page,
+ }) => {
+ const icon = await openInfoIcon(page);
+ await icon.click();
+
+ await expect.poll(async () => focusedId(page)).toBe(FIELD_ID);
+ });
+});
diff --git a/packages/core/src/Layer/useTouchTrigger.ts b/packages/core/src/Layer/useTouchTrigger.ts
index d9299a7b90..02c9243c57 100644
--- a/packages/core/src/Layer/useTouchTrigger.ts
+++ b/packages/core/src/Layer/useTouchTrigger.ts
@@ -61,7 +61,7 @@ export type LayerTouchTrigger = 'auto' | 'tap' | 'none';
* does, on a device where `(hover: hover)` matches — and only becomes a tap
* once it lands. See `handlePointerEnter`.
*/
-const TOUCH_POINTER_TYPES = new Set(['touch', 'pen']);
+export const TOUCH_POINTER_TYPES = new Set(['touch', 'pen']);
/**
* ARIA roles that make an element do something when activated. An explicit