@astryxdesign/core 0.7.7-canary.bf14580 → 0.7.7-canary.c19ca12

package/src/DateInput/MonthScroller.tsx

@@ -38,6 +38,7 @@ import {
   useRef,
   useState,
 } from 'react';
+import {flushSync} from 'react-dom';
 import * as stylex from '@stylexjs/stylex';
 import {useCalendarDays} from '../Calendar';
 import {useDirection, useLocale} from '../i18n';
@@ -62,7 +63,11 @@ import {
   plainDateToISO,
   DATE_FORMAT_WITH_WEEKDAY,
 } from '../utils';
-import {reducedMotionFade} from '../motion/reducedMotion';
+import {
+  playReducedMotionDip,
+  reducedMotionFade,
+  type ReducedMotionDip,
+} from '../motion/reducedMotion';
 import {dateInputTouchSizes, dateInputTouchGeometry} from './tokens.stylex';
 import {useOwnScrollGesture} from './useOwnScrollGesture';
 import {useScrollSettle} from './useScrollSettle';
@@ -434,17 +439,12 @@ export function MonthScroller({
 
   // The Reduced Motion dip of a step on a touch screen, owned here so a
   // second step or the unmount clears it.
-  const dipRef = useRef<{animation: Animation; timer: number} | null>(null);
+  const dipRef = useRef<ReducedMotionDip | null>(null);
   const stopDip = useCallback(() => {
-    const dip = dipRef.current;
-    if (dip != null) {
-      window.clearTimeout(dip.timer);
-      dip.animation.cancel();
-      dipRef.current = null;
-    }
+    dipRef.current?.cancel();
+    dipRef.current = null;
   }, []);
-  // Synchronizes with the dip's timer and animation: neither outlives the
-  // scroller.
+  // Synchronizes with the dip's animations: they do not outlive the scroller.
   useEffect(() => stopDip, [stopDip]);
 
   const scrollToMonth = useCallback(
@@ -505,18 +505,14 @@ export function MonthScroller({
           land();
           return;
         }
-        // A second step within the dip has replaced the first (above): only
-        // its scroll lands, at its own dip's middle.
-        dipRef.current = {
-          animation: scroller.animate(
-            [{opacity: 1}, {opacity: 0}, {opacity: 1}],
-            {duration: fade.duration, easing: fade.easing},
-          ),
-          timer: window.setTimeout(() => {
-            dipRef.current = null;
-            land();
-          }, fade.duration / 2),
-        };
+        // A newer step replaces this one: only its scroll lands.
+        dipRef.current = playReducedMotionDip(scroller, fade, () => {
+          dipRef.current = null;
+          // The fade-in starts as soon as this returns. So render now: the
+          // scroll lands in the layout effect, before the fade-in.
+          // eslint-disable-next-line @eslint-react/dom-no-flush-sync -- the month must change before the dip's fade-in starts
+          flushSync(land);
+        });
         return;
       }
       steeredRowRef.current = row;

package/src/DateInput/Wheel.tsx

@@ -49,7 +49,11 @@ import {
   durationVars,
 } from '../theme/tokens.stylex';
 import {focusOutlineStyles} from '../utils';
-import {reducedMotionFade} from '../motion/reducedMotion';
+import {
+  playReducedMotionDip,
+  reducedMotionFade,
+  type ReducedMotionDip,
+} from '../motion/reducedMotion';
 import {dateInputTouchSizes, dateInputTouchGeometry} from './tokens.stylex';
 import {useOwnScrollGesture} from './useOwnScrollGesture';
 import {usePointerDragScroll} from './usePointerDragScroll';
@@ -331,19 +335,19 @@ export function Wheel({
   // once on a fine one.
   const lastPointerRef = useRef<string | null>(null);
 
-  // A reduced-motion dip whose rows have not landed yet: its timer and the
-  // row it lands on. While one is pending the rows stay put for it, so they
-  // never move at full opacity, and a further step retargets it.
-  const pendingFadeRef = useRef<{timer: number; top: number} | null>(null);
+  // A reduced-motion dip whose rows have not landed yet: the row they land
+  // on. While one is pending the rows stay put for it, so they never move at
+  // full opacity, and a further step retargets it.
+  const pendingFadeRef = useRef<{top: number} | null>(null);
   // The running dip, so a step during its fade-in starts the next one where
   // the column is.
-  const dipRef = useRef<Animation | null>(null);
+  const dipRef = useRef<ReducedMotionDip | null>(null);
+  // Synchronizes with the dip's animations: an unmounted wheel lands nothing.
   useEffect(
     () => () => {
-      if (pendingFadeRef.current != null) {
-        window.clearTimeout(pendingFadeRef.current.timer);
-        pendingFadeRef.current = null;
-      }
+      pendingFadeRef.current = null;
+      dipRef.current?.cancel();
+      dipRef.current = null;
     },
     [],
   );
@@ -368,19 +372,15 @@ export function Wheel({
           ? reducedMotionFade(scroller, {touchRelease})
           : null;
       const pending = pendingFadeRef.current;
+      // A change that lands now replaces a pending landing. Its dip goes on
+      // and fades back in.
       if (fadeTiming == null) {
-        if (pending != null) {
-          window.clearTimeout(pending.timer);
-          pendingFadeRef.current = null;
-        }
+        pendingFadeRef.current = null;
         scroller.scrollTo({top, behavior});
         return;
       }
       if (fadeTiming.duration === 0 || typeof scroller.animate !== 'function') {
-        if (pending != null) {
-          window.clearTimeout(pending.timer);
-          pendingFadeRef.current = null;
-        }
+        pendingFadeRef.current = null;
         scroller.scrollTo({top, behavior: 'auto'});
         return;
       }
@@ -389,26 +389,24 @@ export function Wheel({
         pending.top = top;
         return;
       }
-      const {duration, easing} = fadeTiming;
       // A step during the last dip's fade-in starts the new dip at the
       // column's current opacity, not at full opacity. A leaving element fades
       // out from where it is.
       const shown = Number.parseFloat(getComputedStyle(scroller).opacity);
       dipRef.current?.cancel();
-      dipRef.current = scroller.animate(
-        [
-          {opacity: Number.isFinite(shown) ? shown : 1, easing},
-          {opacity: 0, easing},
-          {opacity: 1},
-        ],
-        {duration, easing: 'linear'},
-      );
-      const landing = {top, timer: 0};
-      landing.timer = window.setTimeout(() => {
-        pendingFadeRef.current = null;
-        scroller.scrollTo({top: landing.top, behavior: 'auto'});
-      }, duration / 2);
+      const landing = {top};
       pendingFadeRef.current = landing;
+      dipRef.current = playReducedMotionDip(
+        scroller,
+        fadeTiming,
+        () => {
+          if (pendingFadeRef.current === landing) {
+            pendingFadeRef.current = null;
+            scroller.scrollTo({top: landing.top, behavior: 'auto'});
+          }
+        },
+        Number.isFinite(shown) ? shown : 1,
+      );
     },
     [itemBlockSize],
   );

package/src/Dialog/Dialog.tsx

@@ -81,7 +81,10 @@ import {themeProps} from '../utils/themeProps';
 import type {DialogVariantMap} from './index';
 import {focusOutlineProps} from '../utils/focusOutline.stylex';
 import {useInteractionModalityTracking} from '../utils/interactionModality';
-import {focusForLastInput, isFocusLost} from '../utils/focusReturn';
+import {
+  focusForLastInput,
+  prepareFocusReturnOnRemoval,
+} from '../utils/focusReturn';
 import {ModalAnnounceProvider} from '../hooks/ModalAnnounceProvider';
 
 import {useMergedRefs} from '../hooks/useMergedRefs';
@@ -653,39 +656,15 @@ export function Dialog({
   }, [isOpen, isInline]);
 
   // A dialog that unmounts while open (rendered only while open, or removed
-  // with the rest of a view) never runs the close branch above, and removing a
-  // <dialog> does not run the browser's own focus return. Focus left inside
-  // it, or dropped to the body by the removal, goes back to the opener.
+  // with the rest of a view) never runs the close branch above. Focus the
+  // removal lost goes back to the opener.
   useEffect(() => {
-    if (isInline) {
+    const dialog = dialogRef.current;
+    if (isInline || dialog == null) {
       return;
     }
-    const dialog = dialogRef.current;
-    // Read now: a removed iframe's document has no window, so its frame
-    // element can no longer be found once the dialog is gone.
-    const host = dialog?.ownerDocument.defaultView?.frameElement ?? null;
-    return () => {
-      const trigger = triggerElementRef.current;
-      if (dialog == null || trigger == null) {
-        return;
-      }
-      // Checked once the commit has finished: StrictMode's simulated unmount
-      // leaves the dialog in the document, and only a real removal returns
-      // focus.
-      queueMicrotask(() => {
-        if (dialog.isConnected || !trigger.isConnected) {
-          return;
-        }
-        // isFocusLost reads the dialog's own document. For a dialog in an
-        // iframe, the document that hosts the frame must also have lost focus
-        // or keep it on that frame, wherever the opener is: a control the
-        // user pressed outside the frame to remove the dialog, or the frame
-        // itself, keeps its focus.
-        if (isFocusLost(dialog) && (host == null || isFocusLost(host))) {
-          focusForLastInput(trigger);
-        }
-      });
-    };
+    const returnFocusOnRemoval = prepareFocusReturnOnRemoval(dialog);
+    return () => returnFocusOnRemoval(triggerElementRef.current);
   }, [isInline]);
 
   // Host app-global surfaces (toasts) inside this modal while it is open, so

package/src/Field/Field.tsx

@@ -25,11 +25,11 @@ import {FieldStatus} from '../FieldStatus/FieldStatus';
 import {useFieldStatusAnnouncement} from '../FieldStatus/useFieldStatusAnnouncement';
 import {spacingVars, borderVars, sizeVars} from '../theme/tokens.stylex';
 import type {IconType} from '../Icon';
-import {mergeProps} from '../utils';
+import {mergeProps} from '../utils/mergeProps';
 import {useDevWarning} from '../hooks/useDevWarning';
 import {FormLayoutContext} from '../FormLayout/FormLayoutContext';
 import {Text} from '../Text/Text';
-import {VisuallyHidden} from '../VisuallyHidden';
+import {VisuallyHidden} from '../VisuallyHidden/VisuallyHidden';
 import {themeProps} from '../utils/themeProps';
 import type {FieldStatusPlacement} from './fieldStatusPlacement';
 

package/src/HoverCard/HoverCard.doc.mjs

@@ -98,7 +98,8 @@ export const docs = {
         {
           name: 'focusTrigger',
           type: "'auto' | 'always' | 'never'",
-          description: 'Controls when focus events trigger the hover card.',
+          description:
+            'When focus should open the hover card. auto opens when the trigger itself takes focus, or focus lands inside a trigger that is focusable at that moment, so a roving-tabindex member opens when the arrow keys reach it.',
           default: "'auto'",
         },
         {
@@ -303,7 +304,8 @@ export const docsZh = {
         {
           name: 'focusTrigger',
           type: "'auto' | 'always' | 'never'",
-          description: '控制焦点事件何时触发悬浮卡片。',
+          description:
+            '焦点何时打开悬浮卡片。auto 在触发元素自身获得焦点，或焦点落在当时可聚焦的触发元素内部时打开，因此方向键到达漫游 tabindex 成员时也会打开。',
           default: "'auto'",
         },
         {

package/src/HoverCard/HoverCard.tsx

@@ -16,7 +16,14 @@
  * - /packages/cli/assets/templates/blocks/components/HoverCard/ (showcase blocks)
  */
 
-import {useCallback, useRef, type ReactElement, type ReactNode} from 'react';
+import {
+  useCallback,
+  useRef,
+  useState,
+  type ReactElement,
+  type ReactNode,
+} from 'react';
+import {observeMutations} from '../utils/sharedMutationObserver';
 import {useIsomorphicLayoutEffect} from '../hooks/useIsomorphicLayoutEffect';
 import * as stylex from '@stylexjs/stylex';
 import {
@@ -148,9 +155,10 @@ export interface HoverCardProps extends Pick<
 
   /**
    * When to trigger on focus:
-   * - `auto`: Only if element is naturally focusable
-   * - `always`: Always attach focus listeners
-   * - `never`: Never attach focus listeners (for composite widgets)
+   * - `auto`: focus on the trigger itself, or within a trigger that is
+   *   focusable when focus arrives
+   * - `always`: focus on the trigger or anything inside it
+   * - `never`: never on focus (for composite widgets)
    *
    * @default 'auto'
    */
@@ -303,6 +311,28 @@ export function HoverCard({
     onHide: handleHide,
   });
 
+  // The wrapper's first element is the trigger, and it can be replaced after
+  // mount: by new children, or by a child component that swaps its own root
+  // without a render here. Syncs with the DOM: on a replacement the wiring
+  // below re-runs, so the old element is released before the new one is wired.
+  const [triggerReplacements, setTriggerReplacements] = useState(0);
+  const observedTriggerRef = useRef<Element | null>(null);
+  useIsomorphicLayoutEffect(() => {
+    const wrapper = wrapperRef.current;
+    if (textOnly || wrapper == null) {
+      return;
+    }
+    observedTriggerRef.current = wrapper.firstElementChild;
+    return observeMutations(wrapper, {childList: true}, () => {
+      const trigger = wrapper.firstElementChild;
+      if (trigger === observedTriggerRef.current) {
+        return;
+      }
+      observedTriggerRef.current = trigger;
+      setTriggerReplacements(count => count + 1);
+    });
+  }, [textOnly]);
+
   // For element children with display:contents, attach ref to first child
   useIsomorphicLayoutEffect(() => {
     if (textOnly) {
@@ -407,6 +437,7 @@ export function HoverCard({
     hoverCard.id,
     hoverCard.isOpen,
     hoverCard.describedBy,
+    triggerReplacements,
   ]);
 
   // While closed, useLayer leaves only an inert <template> marker at this JSX

package/src/HoverCard/useHoverCard.doc.mjs

@@ -5,37 +5,159 @@ export const docs = {
   name: 'useHoverCard',
   displayName: 'useHoverCard',
   group: 'HoverCard',
-  keywords: ['hovercard', 'hover', 'preview', 'card', 'tooltip', 'popup', 'floating', 'anchor'],
+  keywords: [
+    'hovercard',
+    'hover',
+    'preview',
+    'card',
+    'tooltip',
+    'popup',
+    'floating',
+    'anchor',
+  ],
   params: [
-    {name: 'placement', type: "'above' | 'below' | 'start' | 'end'", description: "Position relative to the trigger. Logical: start/end resolve against the popover\'s own inherited direction (RTL mirrors in pure CSS).", default: "'above'"},
-    {name: 'alignment', type: "'start' | 'center' | 'end'", description: "Alignment along the placement axis. Logical: start/end resolve against the popover\'s own inherited direction (RTL mirrors in pure CSS).", default: "'center'"},
-    {name: 'delay', type: 'number', description: 'Delay before showing the hover card on hover, in milliseconds.', default: '300'},
-    {name: 'hideDelay', type: 'number', description: 'Delay before hiding after mouse or focus leaves, in milliseconds.', default: '200'},
-    {name: 'focusTrigger', type: "'auto' | 'always' | 'never'", description: 'When focus should open the hover card. auto only attaches focus listeners to naturally focusable elements.', 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 (an aria-disabled control performs none); tap always opens; none never opens on touch.', default: "'auto'"},
-    {name: 'isEnabled', type: 'boolean', description: 'Whether hover and focus triggers are enabled.', default: 'true'},
-    {name: 'label', type: 'string', description: 'Accessible name for the hover card popup. When provided, the popup is exposed as a named role="dialog"; when omitted, it falls back to role="group" (a group may validly be unnamed).'},
-    {name: 'isOpen', type: 'boolean', description: 'Controlled open state. true force-shows, false force-hides, undefined lets hover/focus manage visibility.'},
-    {name: 'isDefaultOpen', type: 'boolean', description: 'Whether the hover card should be shown on mount.', default: 'false'},
-    {name: 'onShow', type: '() => void', description: 'Callback fired when the hover card becomes visible.'},
-    {name: 'onHide', type: '() => void', description: 'Callback fired when the hover card is hidden.'},
+    {
+      name: 'placement',
+      type: "'above' | 'below' | 'start' | 'end'",
+      description:
+        "Position relative to the trigger. Logical: start/end resolve against the popover\'s own inherited direction (RTL mirrors in pure CSS).",
+      default: "'above'",
+    },
+    {
+      name: 'alignment',
+      type: "'start' | 'center' | 'end'",
+      description:
+        "Alignment along the placement axis. Logical: start/end resolve against the popover\'s own inherited direction (RTL mirrors in pure CSS).",
+      default: "'center'",
+    },
+    {
+      name: 'delay',
+      type: 'number',
+      description:
+        'Delay before showing the hover card on hover, in milliseconds.',
+      default: '300',
+    },
+    {
+      name: 'hideDelay',
+      type: 'number',
+      description:
+        'Delay before hiding after mouse or focus leaves, in milliseconds.',
+      default: '200',
+    },
+    {
+      name: 'focusTrigger',
+      type: "'auto' | 'always' | 'never'",
+      description:
+        'When focus should open the hover card. auto opens when the trigger itself takes focus, or focus lands inside a trigger that is focusable at that moment, so a roving-tabindex member opens when the arrow keys reach it.',
+      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 (an aria-disabled control performs none); tap always opens; none never opens on touch.',
+      default: "'auto'",
+    },
+    {
+      name: 'isEnabled',
+      type: 'boolean',
+      description: 'Whether hover and focus triggers are enabled.',
+      default: 'true',
+    },
+    {
+      name: 'label',
+      type: 'string',
+      description:
+        'Accessible name for the hover card popup. When provided, the popup is exposed as a named role="dialog"; when omitted, it falls back to role="group" (a group may validly be unnamed).',
+    },
+    {
+      name: 'isOpen',
+      type: 'boolean',
+      description:
+        'Controlled open state. true force-shows, false force-hides, undefined lets hover/focus manage visibility.',
+    },
+    {
+      name: 'isDefaultOpen',
+      type: 'boolean',
+      description: 'Whether the hover card should be shown on mount.',
+      default: 'false',
+    },
+    {
+      name: 'onShow',
+      type: '() => void',
+      description: 'Callback fired when the hover card becomes visible.',
+    },
+    {
+      name: 'onHide',
+      type: '() => void',
+      description: 'Callback fired when the hover card is hidden.',
+    },
   ],
   returns: [
-    {name: 'ref', type: 'RefCallback<HTMLElement>', description: 'Combined ref that sets both position and interaction on the same trigger element.'},
-    {name: 'positionRef', type: 'RefCallback<HTMLElement>', description: 'Ref for the positioning anchor element. Use when position and interaction live on different elements.'},
-    {name: 'interactionRef', type: 'RefCallback<HTMLElement>', description: 'Ref for the hover/focus interaction element. Use with positionRef for split trigger patterns.'},
-    {name: 'anchorId', type: 'string', description: 'CSS anchor name for advanced positioning cases.'},
-    {name: 'describedBy', type: 'string', description: 'ID to compose into aria-describedby on the trigger.'},
-    {name: 'renderHoverCard', type: "(children: ReactNode, props?: Omit<ContextRenderProps, 'positioning'>) => ReactNode", description: 'Render function for the anchor-positioned hover card content. The positioning opt-out is excluded: the hover card always derives its position from placement/alignment.'},
-    {name: 'show', type: '() => void', description: 'Imperatively show the hover card immediately.'},
-    {name: 'hide', type: '() => void', description: 'Imperatively hide the hover card immediately.'},
+    {
+      name: 'ref',
+      type: 'RefCallback<HTMLElement>',
+      description:
+        'Combined ref that sets both position and interaction on the same trigger element.',
+    },
+    {
+      name: 'positionRef',
+      type: 'RefCallback<HTMLElement>',
+      description:
+        'Ref for the positioning anchor element. Use when position and interaction live on different elements.',
+    },
+    {
+      name: 'interactionRef',
+      type: 'RefCallback<HTMLElement>',
+      description:
+        'Ref for the hover/focus interaction element. Use with positionRef for split trigger patterns.',
+    },
+    {
+      name: 'anchorId',
+      type: 'string',
+      description: 'CSS anchor name for advanced positioning cases.',
+    },
+    {
+      name: 'describedBy',
+      type: 'string',
+      description: 'ID to compose into aria-describedby on the trigger.',
+    },
+    {
+      name: 'renderHoverCard',
+      type: "(children: ReactNode, props?: Omit<ContextRenderProps, 'positioning'>) => ReactNode",
+      description:
+        'Render function for the anchor-positioned hover card content. The positioning opt-out is excluded: the hover card always derives its position from placement/alignment.',
+    },
+    {
+      name: 'show',
+      type: '() => void',
+      description: 'Imperatively show the hover card immediately.',
+    },
+    {
+      name: 'hide',
+      type: '() => void',
+      description: 'Imperatively hide the hover card immediately.',
+    },
   ],
   usage: {
-    description: 'Headless hook for hover-triggered floating cards. Builds on useLayer with hover/focus intent detection, configurable delays, safe hover behavior, and accessible aria-describedby linking. Use for rich previews on hover when you need full control over the trigger or rendered content.',
+    description:
+      'Headless hook for hover-triggered floating cards. Builds on useLayer with hover/focus intent detection, configurable delays, safe hover behavior, and accessible aria-describedby linking. Use for rich previews on hover when you need full control over the trigger or rendered content.',
     bestPractices: [
-      {guidance: true, description: 'Use for rich content previews such as user profiles, entity summaries, and link previews.'},
-      {guidance: true, description: 'Prefer the HoverCard component for standard trigger-content pairs; use the hook for custom trigger patterns.'},
-      {guidance: false, description: 'Use for simple text hints: use Tooltip or useTooltip instead.'},
+      {
+        guidance: true,
+        description:
+          'Use for rich content previews such as user profiles, entity summaries, and link previews.',
+      },
+      {
+        guidance: true,
+        description:
+          'Prefer the HoverCard component for standard trigger-content pairs; use the hook for custom trigger patterns.',
+      },
+      {
+        guidance: false,
+        description:
+          'Use for simple text hints: use Tooltip or useTooltip instead.',
+      },
     ],
   },
   relatedComponents: ['HoverCard', 'Tooltip', 'Popover'],
@@ -46,17 +168,24 @@ export const docs = {
 
 /** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
 export const docsDense = {
-  description: 'Headless hover-triggered floating cards. Builds on useLayer w/ hover/focus intent, delays, safe hover behavior, aria-describedby. Use for rich previews when trigger/content rendering needs full control.',
+  description:
+    'Headless hover-triggered floating cards. Builds on useLayer w/ hover/focus intent, delays, safe hover behavior, aria-describedby. Use for rich previews when trigger/content rendering needs full control.',
   paramDescriptions: {
-    placement: 'position relative to trigger. logical: start/end follow the popover\'s inherited direction (RTL mirrors).',
-    alignment: 'alignment along placement axis. logical: start/end follow the popover\'s inherited direction (RTL mirrors).',
+    placement:
+      "position relative to trigger. logical: start/end follow the popover's inherited direction (RTL mirrors).",
+    alignment:
+      "alignment along placement axis. logical: start/end follow the popover's inherited direction (RTL mirrors).",
     delay: 'show delay in ms.',
     hideDelay: 'hide delay after mouse/focus leave in ms.',
-    focusTrigger: 'when focus opens hover card; auto = naturally focusable elements only.',
-    touchTrigger: 'tap behavior with no hover; auto = tap unless trigger acts, tap = always, none = never.',
+    focusTrigger:
+      'when focus opens hover card; auto = focus on the trigger, or inside a trigger focusable when focus arrives.',
+    touchTrigger:
+      'tap behavior with no hover; auto = tap unless trigger acts, tap = always, none = never.',
     isEnabled: 'whether hover/focus triggers are enabled.',
-    label: 'accessible name for popup. with label: named role="dialog"; without: role="group".',
-    isOpen: 'controlled open state: true force-show, false force-hide, undefined unmanaged.',
+    label:
+      'accessible name for popup. with label: named role="dialog"; without: role="group".',
+    isOpen:
+      'controlled open state: true force-show, false force-hide, undefined unmanaged.',
     isDefaultOpen: 'show on mount.',
     onShow: 'fires when hover card becomes visible.',
     onHide: 'fires when hover card hides.',
@@ -72,11 +201,24 @@ export const docsDense = {
     hide: 'hide immediately.',
   },
   usage: {
-    description: 'Headless hover-triggered floating cards. Builds on useLayer w/ hover/focus intent, delays, safe hover behavior, aria-describedby. Use for rich previews when trigger/content rendering needs full control.',
+    description:
+      'Headless hover-triggered floating cards. Builds on useLayer w/ hover/focus intent, delays, safe hover behavior, aria-describedby. Use for rich previews when trigger/content rendering needs full control.',
     bestPractices: [
-      {guidance: true, description: 'Use for rich previews: profiles, entity summaries, link previews.'},
-      {guidance: true, description: 'Prefer HoverCard for standard trigger-content pairs; use hook for custom trigger patterns.'},
-      {guidance: false, description: 'Use for simple text hints: use Tooltip / useTooltip instead.'},
+      {
+        guidance: true,
+        description:
+          'Use for rich previews: profiles, entity summaries, link previews.',
+      },
+      {
+        guidance: true,
+        description:
+          'Prefer HoverCard for standard trigger-content pairs; use hook for custom trigger patterns.',
+      },
+      {
+        guidance: false,
+        description:
+          'Use for simple text hints: use Tooltip / useTooltip instead.',
+      },
     ],
   },
 };