An open source design system that's fully customizable and agent ready
TypeScript
spec(Tooltip, HoverCard): the touchTrigger codemod is available before the 0.8.0 removal (#9417)
Cindy Zhang0de0e75d7be7
diff --git a/docs/specs/components/HoverCard/HoverCard.spec.md b/docs/specs/components/HoverCard/HoverCard.spec.mdindex a078589db2..c6ebe12fa9 100644--- a/docs/specs/components/HoverCard/HoverCard.spec.md+++ b/docs/specs/components/HoverCard/HoverCard.spec.md@@ -42,7 +42,7 @@ system_specs: [spec:AST-003, spec:AST-017]| Public contract | `HoverCard` with `children` (trigger), `content`, `label`, `placement` (`above`), `alignment` (`center`), `delay` (300), `hideDelay` (200), `focusTrigger`, `triggerBehavior` (`adaptive`), `touchTrigger` (`tap` deprecated by `component:Tooltip` DEP-0016), `isEnabled`, `isOpen`, `isDefaultOpen`, `onOpenChange`, and `hasHoverIndication`; target `hover-card`. `useHoverCard` takes the same `triggerBehavior` and `touchTrigger`. || Behavior | A floating card of rich, possibly interactive content anchored to a trigger. It opens on hover after `delay`, on focus, and on a qualifying tap, stays open while the pointer is on the trigger or card, and closes on leave, Escape, or a tap outside. With `label` it is a named dialog the trigger advertises; without, a group that describes the trigger. With `triggerBehavior="hover"`, touch never opens it. With `triggerBehavior="toggle"`, hover and focus preview it, and a click, tap, Enter, or Space on a button trigger pins it open until Escape, a second press, a press outside, or focus leaving. || End-user impact | Mouse, keyboard, and touch users can open the preview, move into it to use its actions, and dismiss it; screen-reader users hear it as a named popup dialog or as the trigger's description. With the toggle, a pinned card stays open while people read or use it, whatever the pointer does. |-| Builder impact | A trigger whose information lives only in the card passes `triggerBehavior="toggle"` and a button trigger (DEC-1). `touchTrigger="tap"` callers migrate by trigger kind: the deprecating release's codemod rewrites icon and span triggers and reports the rest (`component:Tooltip` DEP-0016), and `component:Tooltip` CLN-0024 names each remaining kind's replacement at the next minor. |+| Builder impact | A trigger whose information lives only in the card passes `triggerBehavior="toggle"` and a button trigger (DEC-1). `touchTrigger="tap"` callers migrate by trigger kind: the deprecating release's codemod, an opt-in early migration when run explicitly, rewrites icon and span triggers and reports the rest (`component:Tooltip` DEP-0016), and `component:Tooltip` CLN-0024 names each remaining kind's replacement in 0.8.0, whose upgrade runs the codemod again. || Compatibility/readiness | Additive `triggerBehavior`, default `adaptive`, the released behavior; `touchTrigger="tap"` deprecated and `touchTrigger` removed at the next minor, `triggerBehavior="adaptive"` keeping its `auto` behavior and `triggerBehavior="hover"` its `none` behavior (`component:Tooltip` DEP-0016, CLN-0024). FR9, FR10, and AR3 are not yet built; eight further implementation gaps (see Current-state impact). || Review checks | Reject an unnamed `dialog`, a card that cannot be hovered or dismissed (WCAG 1.4.13), Escape in the page that also closes a layer underneath, or `aria-expanded` set on a trigger whose role does not support it, a pinned card that closes on pointer leave, or a non-button toggle trigger without the development warning. || Governing rules | WCAG 1.4.13, 2.1.1; `family:overlay-dismissal`; `spec:AST-003` FR4; `spec:AST-017` (deprecation); `architecture:public-component-api` INV9, INV21; `architecture:layer-runtime`; `architecture:interaction-modality`; `architecture:component-theming-surface`. |@@ -78,9 +78,11 @@ Consumer usage lives in `HoverCard.doc.mjs`.`onOpenChange(false)` without closing itself (FR7); under`triggerBehavior="toggle"` a press on a controlled card reports the toggledvalue through `onOpenChange` and does not change the state itself (FR9)-- Migration decision: `component:Tooltip` DEP-0016, then CLN-0024 in the next- minor; both cover HoverCard's and `useHoverCard`'s `touchTrigger`, with the- same codemods, and CLN-0024 brings FR5's walk to `adaptive`+- Migration decision: `component:Tooltip` DEP-0016, whose `touchTrigger` to+ `triggerBehavior` codemod is an opt-in early migration from the deprecating release, then CLN-0024 in+ 0.8.0, whose upgrade runs that codemod again with the removal; both cover+ HoverCard's and `useHoverCard`'s `touchTrigger`, and CLN-0024 brings FR5's+ walk to `adaptive`Consumer migration instructions belong in consumer docs and release notes.diff --git a/docs/specs/components/Tooltip/Tooltip.spec.md b/docs/specs/components/Tooltip/Tooltip.spec.mdindex c5aadb3d32..5d6090222b 100644--- a/docs/specs/components/Tooltip/Tooltip.spec.md+++ b/docs/specs/components/Tooltip/Tooltip.spec.md@@ -45,7 +45,7 @@ system_specs: [spec:AST-003, spec:AST-017]| Public contract | `Tooltip` with `content`, `children` or `anchorRef`, `placement` (`above`), `alignment` (`center`), `delay` (200), `hideDelay` (0), `focusTrigger` (`auto`), `triggerBehavior` (`adaptive`), `touchTrigger` (`auto`; `tap` deprecated by DEP-0016), `isEnabled`, `isOpen`, `isDefaultOpen`, `onOpenChange`, and `hasHoverIndication`; target `tooltip`. `useTooltip` takes the same `triggerBehavior` and `touchTrigger`. || Behavior | A `role="tooltip"` layer that describes its trigger. It opens on hover after `delay`, on keyboard focus, and on a qualifying tap; it stays open while the pointer moves onto it, and closes on leave, Escape, or pressing the trigger (a press that focuses a text field reopens it). With `triggerBehavior="hover"`, no touch or pen tap opens it. With `triggerBehavior="toggle"`, hover and focus preview it, and a click, tap, Enter, or Space on a button trigger pins it open until Escape, a second press, a press outside, or focus leaving. || End-user impact | Mouse, keyboard, and touch users can each reveal the hint, move onto it, and dismiss it; screen-reader users hear it as the trigger's description. With the toggle, people on touch, keyboard, or a screen reader can keep it open to read it, and hear it once when it pins. |-| Builder impact | A trigger whose information lives only in the tooltip passes `triggerBehavior="toggle"` and a button trigger (DEC-1). `touchTrigger="tap"` callers migrate by trigger kind: the deprecating release's codemod rewrites icon and span triggers and reports the rest (DEP-0016), and CLN-0024 names each remaining kind's replacement at the next minor. |+| Builder impact | A trigger whose information lives only in the tooltip passes `triggerBehavior="toggle"` and a button trigger (DEC-1). `touchTrigger="tap"` callers migrate by trigger kind: the deprecating release's codemod, an opt-in early migration when run explicitly, rewrites icon and span triggers and reports the rest (DEP-0016), and CLN-0024 names each remaining kind's replacement in 0.8.0, whose upgrade runs the codemod again. || Compatibility/readiness | Additive `triggerBehavior`, default `adaptive`, the released behavior; `touchTrigger="tap"` deprecated (DEP-0016); `touchTrigger` is removed at the next minor, `triggerBehavior="adaptive"` keeping its `auto` behavior and `triggerBehavior="hover"` its `none` behavior (CLN-0024). FR9, FR10, and AR6 are not yet built; nine further implementation gaps (see Current-state impact). || Review checks | Reject a tooltip that cannot be hovered or dismissed (WCAG 1.4.13), one that opens on a tap's focus or on pointer focus of a trigger that is not a text field, a lost `aria-describedby` link, a pinned tooltip that closes on pointer leave or lets Escape pass to the layer beneath, a toggle without `aria-expanded`, or a non-button toggle trigger without the development warning. || Governing rules | WCAG 1.4.13, 2.1.1; `family:overlay-dismissal`; `spec:AST-003` FR4; `spec:AST-017` (deprecation); `architecture:public-component-api` INV9, INV21; `architecture:layer-runtime`; `architecture:interaction-modality`; `architecture:component-theming-surface`. |@@ -81,26 +81,28 @@ in `Tooltip.doc.mjs`.`onOpenChange(false)` without closing itself (FR7); under`triggerBehavior="toggle"` a press on a controlled tooltip reports the toggledvalue through `onOpenChange` and does not change the state itself (FR9)-- Migration decision: DEP-0016, then CLN-0024 in the next minor+- Migration decision: DEP-0016, whose `touchTrigger` to `triggerBehavior`+ codemod is an opt-in early migration from the deprecating release, then CLN-0024 in 0.8.0, whose+ upgrade runs that codemod again with the removal### DEP-0016 — Deprecate `touchTrigger="tap"`-| Field | Value |-| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |-| id | `DEP-0016` |-| cleanup | `CLN-0024` |-| package | `@astryxdesign/core` |-| surface | `touchTrigger="tap"` on `Tooltip`, `HoverCard`, `useTooltip`, and `useHoverCard`; `touchTrigger` remains supported until the next minor; only `"tap"` is deprecated now |-| old contract | Every completed tap opens the layer, even on a trigger that performs its own action; a mouse click, Enter, or Space does not keep it open |-| replacement | `triggerBehavior="toggle"`: a tap still opens the layer, and a click, Enter, or Space pins it too (FR9); a non-button trigger keeps tap-only opening (FR9) |-| direct authority | `component:Tooltip` DEC-1 and `component:HoverCard` DEC-1. Owner: `cixzhang` |-| warning | Static `@deprecated` metadata on the `tap` value; consumer docs and the release notes name `DEP-0016` and `triggerBehavior="toggle"`. No runtime warning (`spec:AST-017` FR29, FR29a). When `touchTrigger` is given beside `triggerBehavior="hover"` or `"toggle"`, `triggerBehavior` wins |-| migration | Mechanical only where the result is observably the same: on a trigger that is statically a non-interactive element, such as an icon or a span, `triggerBehavior="toggle"` replaces `touchTrigger="tap"`. That rewrite keeps every production behavior because FR9 keeps a non-button toggle trigger on tap-only opening, as `touchTrigger="tap"` does; in development such a trigger also gets FR9's warning, which points its caller to a button trigger. On a trigger whose tooltip repeats its own text, a button, a link, or an element the codemod cannot identify, the toggle changes what a click, Enter, or Space does (and on a button adds `aria-expanded`), so the caller migrates by hand; the deprecated `tap` keeps working until CLN-0024 |-| codemod | An `astryx upgrade` codemod staged in `packages/cli/assets/codemods/transforms/next/`, with tests and fixtures, checked by the codemod verify workflow, and available in the release that deprecates `tap`: it rewrites static `touchTrigger="tap"` to `triggerBehavior="toggle"` only where the trigger is statically a non-interactive icon or span, which FR9 keeps on tap-only opening, reports every other `touchTrigger="tap"` site (an own-text trigger, a button, a link, or an unknown element) with a manual-migration note and leaves it unchanged, removes static `touchTrigger="auto"`, and reports spreads and dynamic values it cannot prove (`spec:AST-017` FR29c, FR29d) |-| downstream | In the deprecating release, Core FieldLabel's info icon moves from `touchTrigger="tap"` to `component:InfoTip` with `triggerBehavior="toggle"` (`component:FieldLabel` FR9), and Lab InfoTip and the CLI page templates migrate too, the templates to a button trigger with `triggerBehavior="toggle"` so they carry no development warning (`spec:AST-017` FR29c); docs, stories, templates, and examples teach only `triggerBehavior` |-| transition | no prior transition |-| state | `proposed` |-| target plan | `CLN-0024` in the next minor release |+| Field | Value |+| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| id | `DEP-0016` |+| cleanup | `CLN-0024` |+| package | `@astryxdesign/core` |+| surface | `touchTrigger="tap"` on `Tooltip`, `HoverCard`, `useTooltip`, and `useHoverCard`; `touchTrigger` remains supported until the next minor; only `"tap"` is deprecated now |+| old contract | Every completed tap opens the layer, even on a trigger that performs its own action; a mouse click, Enter, or Space does not keep it open |+| replacement | `triggerBehavior="toggle"`: a tap still opens the layer, and a click, Enter, or Space pins it too (FR9); a non-button trigger keeps tap-only opening (FR9) |+| direct authority | `component:Tooltip` DEC-1 and `component:HoverCard` DEC-1. Owner: `cixzhang` |+| warning | Static `@deprecated` metadata on the `tap` value; consumer docs and the release notes name `DEP-0016` and `triggerBehavior="toggle"`. No runtime warning (`spec:AST-017` FR29, FR29a). When `touchTrigger` is given beside `triggerBehavior="hover"` or `"toggle"`, `triggerBehavior` wins |+| migration | Mechanical only where the result is observably the same: on a trigger that is statically a non-interactive element, such as an icon or a span, `triggerBehavior="toggle"` replaces `touchTrigger="tap"`. That rewrite keeps every production behavior because FR9 keeps a non-button toggle trigger on tap-only opening, as `touchTrigger="tap"` does; in development such a trigger also gets FR9's warning, which points its caller to a button trigger. On a trigger whose tooltip repeats its own text, a button, a link, or an element the codemod cannot identify, the toggle changes what a click, Enter, or Space does (and on a button adds `aria-expanded`), so the caller migrates by hand; the deprecated `tap` keeps working until CLN-0024 |+| codemod | An `astryx upgrade` codemod staged in `packages/cli/assets/codemods/transforms/next/`, with tests and fixtures, checked by the codemod verify workflow, and available in the release that deprecates `tap`: it rewrites static `touchTrigger="tap"` to `triggerBehavior="toggle"` only where the trigger is statically a non-interactive icon or span, which FR9 keeps on tap-only opening, reports every other `touchTrigger="tap"` site (an own-text trigger, a button, a link, or an unknown element) with a manual-migration note and leaves it unchanged, removes static `touchTrigger="auto"`, since the default `adaptive` reproduces it, rewrites static `touchTrigger="none"` to `triggerBehavior="hover"`, which keeps its behavior, and reports spreads and dynamic values it cannot prove (`spec:AST-017` FR29c, FR29d). It is usable from that release as an opt-in early migration: a caller who runs `astryx upgrade` explicitly moves every `touchTrigger` site to `triggerBehavior` before the removal, each rewrite keeping that release's behavior, and a caller who does not keeps `touchTrigger` working until 0.8.0. 0.8.0's upgrade runs the same codemod again with CLN-0024's removal, there applying CLN-0024's recorded kinds |+| downstream | In the deprecating release, Core FieldLabel's info icon moves from `touchTrigger="tap"` to `component:InfoTip` with `triggerBehavior="toggle"` (`component:FieldLabel` FR9), and Lab InfoTip and the CLI page templates migrate too, the templates to a button trigger with `triggerBehavior="toggle"` so they carry no development warning (`spec:AST-017` FR29c); docs, stories, templates, and examples teach only `triggerBehavior` |+| transition | no prior transition |+| state | `proposed` |+| target plan | `CLN-0024` in 0.8.0, the next minor release |### CLN-0024 — Remove `touchTrigger`@@ -110,9 +112,9 @@ in `Tooltip.doc.mjs`.| lifecycle | `DEP-0016` || delta | `touchTrigger` is removed from `Tooltip`, `HoverCard`, `useTooltip`, and `useHoverCard`; `touchTrigger` remains supported until the next minor; only `"tap"` is deprecated now (DEP-0016). `triggerBehavior` alone then decides what a tap does, with `adaptive`, `hover`, and `toggle`, default `adaptive`: `adaptive` keeps the released `touchTrigger="auto"` (a tap opens the layer unless the trigger performs its own action, and no press pins it), `hover` keeps the released `touchTrigger="none"` (no touch or pen tap opens the layer, and no press pins it), and `toggle` is unchanged and replaces `touchTrigger="tap"`. `adaptive` gains FR5's walk: a tap that already acts on a control around the trigger does not open the layer. A hint-only trigger inside a control migrates by declaring `triggerBehavior="toggle"`, which no codemod can decide; Astryx's own info-only triggers (InfoTip, FieldLabel's info button, and a standalone StatusDot) declare it before this minor; a StatusDot inside a button, link, menu item, or option stays an image whose status the host's accessible name carries. One prop decides what a press does || replacement | `touchTrigger="none"` becomes `triggerBehavior="hover"`, under which no touch or pen tap opens the layer, and `touchTrigger="auto"` becomes the default `triggerBehavior="adaptive"`. Each remaining `touchTrigger="tap"` site has a named replacement (`spec:AST-017` FR8): a button or link whose only job is its tooltip takes `triggerBehavior="toggle"`, so its tooltip keeps a touch path; a button or link with its own action whose accessible name already carries the layer's text drops `tap` and keeps the default `adaptive`, so a tap performs the action and opens no layer (`architecture:interaction-modality` INV4's case); any other button or link with its own action moves the layer's information to an adjacent info trigger that declares `triggerBehavior="toggle"`, such as an InfoTip, or into its visible label, so that information keeps a touch path, and then drops `tap`; a trigger whose tooltip repeats its own text takes `triggerBehavior="toggle"` (FR9's own-text exception); an unknown element is reported for a manual choice (`architecture:interaction-modality` INV4) |-| codemod | The minor's `astryx upgrade` codemod, with tests and fixtures: `touchTrigger="auto"` is removed, since the default `adaptive` reproduces it; `touchTrigger="none"` becomes `triggerBehavior="hover"`; an explicit `triggerBehavior="hover"` or `"toggle"` is kept and any `touchTrigger` beside it removed, and beside an explicit `triggerBehavior="adaptive"` the `touchTrigger` value maps as stated here and replaces it; a remaining `touchTrigger="tap"` becomes `triggerBehavior="toggle"` on an icon or span trigger and on an own-text trigger the codemod can identify; every button and link `tap` site is reported with the options in its note (`triggerBehavior="toggle"` when the trigger's only job is its layer; remove `tap` and keep the default `adaptive` when the trigger's accessible name already carries the layer's text; otherwise move the information to an adjacent InfoTip or the visible label, then remove `tap`), since no static check tells them apart, and every other remaining `tap` site is reported; spreads and dynamic values are reported |+| codemod | DEP-0016's codemod, which callers could already run early, run again by 0.8.0's `astryx upgrade`, with tests and fixtures: `touchTrigger="auto"` is removed, since the default `adaptive` reproduces it; `touchTrigger="none"` becomes `triggerBehavior="hover"`; an explicit `triggerBehavior="hover"` or `"toggle"` is kept and any `touchTrigger` beside it removed, and beside an explicit `triggerBehavior="adaptive"` the `touchTrigger` value maps as stated here and replaces it; a remaining `touchTrigger="tap"` becomes `triggerBehavior="toggle"` on an icon or span trigger and on an own-text trigger the codemod can identify; every button and link `tap` site is reported with the options in its note (`triggerBehavior="toggle"` when the trigger's only job is its layer; remove `tap` and keep the default `adaptive` when the trigger's accessible name already carries the layer's text; otherwise move the information to an adjacent InfoTip or the visible label, then remove `tap`), since no static check tells them apart, and every other remaining `tap` site is reported; spreads and dynamic values are reported || rollback | Restore `touchTrigger` and the final-patch `triggerBehavior="adaptive"`, without FR5's walk, from the final-patch baseline |-| state | `pending` — lands in a declared minor with its `[breaking]` Changeset |+| state | `pending` — lands in 0.8.0, a declared minor, with its `[breaking]` Changeset |Consumer migration instructions belong in consumer docs and release notes.