feat(Tooltip, HoverCard, cli): deprecate touchTrigger="tap" (DEP-0016), with its upgrade codemod

.changeset/hover-card-trigger-behavior.md

@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[feat] HoverCard (and `useHoverCard`) take `triggerBehavior` (type `HoverCardTriggerBehavior`): `adaptive`, the default and the released behavior, where hover and focus preview the card and a tap opens it unless the trigger performs an action of its own; `hover`, where hover and focus preview it and touch never opens it; or `toggle`, where hover and focus still preview it and a click, a tap, Enter, or Space on a button trigger pins it open, and the same press closes it. A pinned card stays until Escape, a second press, a press outside, or focus leaving; a press on its own content keeps it, and it takes Escape before the layer beneath it. The press stops at its trigger, so a clickable row, card, or label around it does nothing, and the trigger's own handlers still run. The trigger reports `aria-expanded` and `aria-controls`, and the card's `label` (else its text) is announced once when it pins, inside a modal too (`component:HoverCard` FR9 and FR10). On a trigger that is not a button, a labelled card keeps its own popup state and tap-only opening; `touchTrigger` decides taps only under `adaptive`; `hover` and `toggle` ignore it.
+
+@vjeux

.changeset/touch-trigger-tap-deprecated.md

@@ -0,0 +1,8 @@
+---
+'@astryxdesign/core': patch
+'@astryxdesign/cli': patch
+---
+
+[feat] `touchTrigger="tap"` on Tooltip, HoverCard, `useTooltip` and `useHoverCard` is deprecated in favor of `triggerBehavior="toggle"` (DEP-0016); `touchTrigger` remains supported until the next minor; only `"tap"` is deprecated now. It keeps working as released, and beside `triggerBehavior="hover"` or `"toggle"`, `touchTrigger` is ignored. A `tap` call resolves to a `@deprecated` signature, so editors mark it with its replacement, and the docs name it. `astryx upgrade` rewrites static `touchTrigger="tap"` to `triggerBehavior="toggle"` on an icon or span trigger with no `role`, `tabIndex`, event handler, or spread props, and removes static `touchTrigger="auto"` where no props are spread; a rewritten trigger keeps its production behavior, tap-only opening, and in development it logs the warning that only a button trigger pins. Every other `tap` site keeps its prop with a TODO naming the manual migration, and the upgrade lists each one with its file and line among the manual migrations it cannot make: a button, a link, an element with a `role`, `tabIndex`, event handler, or spread props, a trigger whose layer repeats its own text, a `useTooltip` or `useHoverCard` options object, an element it cannot identify, a computed value, or spread props, even beside a static `triggerBehavior="toggle"`. A core codemod reports such a site by passing a `ManualMigrationRequired` to `api.report`, and still keeps its changes to the file. The table-comparison page template now uses the toggle; its modality rail becomes a button so it can pin its explanation.
+
+@vjeux

.changeset/trigger-behavior-toggle.md

@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[feat] Tooltip (and `useTooltip`) take `triggerBehavior` (type `TooltipTriggerBehavior`): `adaptive`, the default and the released behavior, where hover and focus preview the tooltip and a tap opens it unless the trigger performs an action of its own; `hover`, where hover and focus preview it and no touch or pen tap opens it; or `toggle`, where hover and focus still preview it and a click, a tap, Enter, or Space on a button trigger pins it open, and the same press closes it. A pinned tooltip stays until Escape, a second press, a press outside, or focus leaving, and it takes Escape before the layer beneath it. The press stops at its trigger, so a clickable row, card, or label around it does nothing, and the trigger's own handlers still run. With `anchorRef`, or `useTooltip` with a caller's trigger, nothing is rendered around the trigger to stop it: the trigger's own `onClick` runs, Astryx clickable rows, cards, and containers ignore the press, and a plain `onClick` element around the trigger receives it unless the trigger's `onClick` stops it. The trigger reports `aria-expanded` and `aria-controls`, and the tooltip's text is announced once when it pins, inside a modal too (`component:Tooltip` FR9 and FR10). A trigger that is not a button gets a development warning and keeps tap-only opening; `touchTrigger` decides taps only under `adaptive`; `hover` and `toggle` ignore it.
+
+@vjeux

apps/storybook/stories/TooltipToggleBehaviorA11y.stories.tsx

@@ -0,0 +1,201 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file TooltipToggleBehaviorA11y.stories.tsx
+ * @input Uses Tooltip, HoverCard, Button, ClickableCard and Layout from core
+ * @output The fixtures the toggle-behavior proofs drive in a real browser: a
+ *   button whose only job is its tooltip, the same trigger inside a clickable
+ *   card, an anchored trigger with its own click handler inside a clickable
+ *   card, a trigger whose tooltip opens on no focus, one trigger per
+ *   `triggerBehavior` value, and an unlabelled HoverCard of two paragraphs on
+ *   a button.
+ * @position The reproduction path for the `triggerBehavior="toggle"` cases in
+ *   `packages/core/src/Layer/__tests__/TouchTrigger.a11y.chromium.spec.ts`
+ *   (`component:Tooltip` FR9, FR10; `component:HoverCard` FR9, FR10;
+ *   `docs/specs/AST-009/spec.md` FR30: a
+ *   browser claim is checked against a checked-in story).
+ *
+ * SYNC: The spec navigates to these story ids by name. Nothing at compile
+ *   time catches a renamed export — the Chromium spec does, when it finds no
+ *   story.
+ */
+
+import {useRef, useState} from 'react';
+import type {Meta, StoryObj} from '@storybook/react';
+import {Button} from '@astryxdesign/core/Button';
+import {ClickableCard} from '@astryxdesign/core/ClickableCard';
+import {HoverCard} from '@astryxdesign/core/HoverCard';
+import {VStack} from '@astryxdesign/core/Layout';
+import {Tooltip} from '@astryxdesign/core/Tooltip';
+
+const meta: Meta = {
+  title: 'a11y/Tooltip toggle behavior',
+  // Driven by the toggle-behavior spec, not photographed: the states under test
+  // are pins and closes across presses, which no single frame shows.
+  tags: ['no-visual'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'A button whose only job is its tooltip takes `triggerBehavior="toggle"`: a click, a tap, Enter, or Space pins the tooltip, and the same press closes it. Inside a clickable card, the press stops at the trigger.',
+      },
+    },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj;
+
+/** A press pins the tooltip open; the same press, Escape, or a press outside closes it. */
+export const ButtonToggle: Story = {
+  render: () => (
+    <div style={{padding: 100}}>
+      <Tooltip
+        content="Rows are ranked by how many places import the icon"
+        placement="above"
+        triggerBehavior="toggle">
+        <Button label="What is this?" variant="secondary">
+          ?
+        </Button>
+      </Tooltip>
+    </div>
+  ),
+};
+
+function InAClickableCardRender() {
+  const [opened, setOpened] = useState(0);
+  return (
+    <div style={{padding: 100, maxWidth: 360}}>
+      <VStack gap={2}>
+        <ClickableCard label="Icon usage" onClick={() => setOpened(n => n + 1)}>
+          <VStack gap={2}>
+            Icon usage
+            <Tooltip
+              content="Rows are ranked by how many places import the icon"
+              placement="above"
+              triggerBehavior="toggle">
+              <Button label="What is this?" variant="secondary">
+                ?
+              </Button>
+            </Tooltip>
+          </VStack>
+        </ClickableCard>
+        <span>Card opened {opened} times</span>
+      </VStack>
+    </div>
+  );
+}
+
+/** A press on the trigger pins its tooltip and stops there: the card does not open. */
+export const InAClickableCard: Story = {
+  render: () => <InAClickableCardRender />,
+};
+
+function AnchoredActionInACardRender() {
+  const [opened, setOpened] = useState(0);
+  const [pressed, setPressed] = useState(0);
+  const anchorRef = useRef<HTMLButtonElement>(null);
+  return (
+    <div style={{padding: 100, maxWidth: 360}}>
+      <VStack gap={2}>
+        <ClickableCard label="Icon usage" onClick={() => setOpened(n => n + 1)}>
+          <VStack gap={2}>
+            Icon usage
+            <Button
+              ref={anchorRef}
+              label="What is this?"
+              variant="secondary"
+              onClick={() => setPressed(n => n + 1)}>
+              ?
+            </Button>
+            <Tooltip
+              anchorRef={anchorRef}
+              content="Rows are ranked by how many places import the icon"
+              placement="above"
+              triggerBehavior="toggle"
+            />
+          </VStack>
+        </ClickableCard>
+        <span>Card opened {opened} times</span>
+        <span>Button pressed {pressed} times</span>
+      </VStack>
+    </div>
+  );
+}
+
+/**
+ * An anchored trigger with its own click handler, in a clickable card: the
+ * pinning press runs the trigger's own handler, and the card ignores it.
+ */
+export const AnchoredActionInACard: Story = {
+  render: () => <AnchoredActionInACardRender />,
+};
+
+/** A tooltip that opens on no focus: focus moving to another control still closes a pin. */
+export const FocusTriggerNever: Story = {
+  render: () => (
+    <div style={{padding: 100}}>
+      <VStack gap={2}>
+        <Tooltip
+          content="Rows are ranked by how many places import the icon"
+          placement="above"
+          triggerBehavior="toggle"
+          focusTrigger="never">
+          <Button label="What is this?" variant="secondary">
+            ?
+          </Button>
+        </Tooltip>
+        <Button label="Next" variant="secondary">
+          Next
+        </Button>
+      </VStack>
+    </div>
+  ),
+};
+
+/** One info-only trigger per `triggerBehavior` value: a tap opens, never opens, or pins. */
+export const TriggerBehaviors: Story = {
+  render: () => (
+    <div style={{padding: 100}}>
+      <VStack gap={4}>
+        <Tooltip content="Adaptive: a tap opens it" triggerBehavior="adaptive">
+          <span tabIndex={0}>Adaptive term</span>
+        </Tooltip>
+        <Tooltip content="Hover: touch never opens it" triggerBehavior="hover">
+          <span tabIndex={0}>Hover term</span>
+        </Tooltip>
+        <Tooltip content="Toggle: a press pins it" triggerBehavior="toggle">
+          <Button label="Toggle term" variant="secondary">
+            ?
+          </Button>
+        </Tooltip>
+      </VStack>
+    </div>
+  ),
+};
+
+/**
+ * An unlabelled card of two paragraphs on a button: a press pins it, its text
+ * is announced with the paragraphs apart, and a press on that text, which
+ * moves focus to no element, keeps it pinned.
+ */
+export const HoverCardToggle: Story = {
+  render: () => (
+    <div style={{padding: 100}}>
+      <HoverCard
+        content={
+          <>
+            <p>Ada Lovelace</p>
+            <p>Analyst, Payments</p>
+          </>
+        }
+        placement="below"
+        triggerBehavior="toggle">
+        <Button label="Ada" variant="secondary">
+          Ada
+        </Button>
+      </HoverCard>
+    </div>
+  ),
+};