feat(Tooltip): triggerBehavior="toggle" pins the tooltip on a press

.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,151 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file TooltipToggleBehaviorA11y.stories.tsx
+ * @input Uses Tooltip, 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, and a trigger whose tooltip opens on no focus.
+ * @position The reproduction path for the `triggerBehavior="toggle"` cases in
+ *   `packages/core/src/Layer/__tests__/TouchTrigger.a11y.chromium.spec.ts`
+ *   (`component:Tooltip` 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 {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>
+  ),
+};