@astryxdesign/core 0.4.1 → 0.4.2-canary.464a445

package/src/Chat/Chat.doc.mjs

@@ -67,6 +67,7 @@ export const docs = {
       { guidance: true, description: 'Use the group prop on bubbles (first, middle, last) when a single sender sends multiple consecutive messages; it tightens corner radius to visually connect them.' },
       { guidance: true, description: 'Use ChatSystemMessage with variant="divider" for date separators and default for inline status notices like joins, leaves, or topic changes.' },
       { guidance: true, description: 'Put name on the first bubble and metadata on the last bubble in a message so they align with the bubble\'s inline padding.' },
+      { guidance: true, description: 'Wrap custom in-message content (cards, attachments, citations) in a ghost bubble so it aligns with the bubble text column; add width="100%" when it should span the full message column instead of the default bubble width cap.' },
       { guidance: true, description: 'Provide an emptyState prop so new users see a clear prompt to start a conversation instead of a blank screen.' },
       { guidance: true, description: 'Use the ghost bubble variant for AI-style responses that show rich content like code blocks or markdown without a visible boundary.' },
       { guidance: false, description: 'Don\'t use ChatSystemMessage for sender content; it has no avatar, alignment, or bubble. Use ChatMessage with a sender role instead.' },
@@ -84,7 +85,7 @@ export const docs = {
       { name: 'Empty state', required: false, description: 'Centered placeholder shown when no messages exist. Use EmptyState for a consistent look.' },
       { name: 'Avatar', required: false, description: 'A sender avatar rendered beside the message. Typically Avatar with size="md". Hidden for system messages.' },
       { name: 'Name', required: false, description: 'Sender name above the message body. Place on the bubble when using bubbles, or on the message wrapper for raw content.' },
-      { name: 'Content', required: true, description: 'The message body: one or more ChatMessageBubble elements, or any free-form ReactNode like images or tool calls.' },
+      { name: 'Content', required: true, description: 'The message body: one or more ChatMessageBubble elements, or any free-form ReactNode like images or tool calls. Wrap non-bubble content in a ghost bubble to align it with the bubble text column.' },
       { name: 'Metadata', required: false, description: 'Timestamp, delivery status, and footer actions below the message. Place on the last bubble or on the message wrapper.' },
     ],
   },
@@ -100,6 +101,7 @@ export const docsZh = {
       { guidance: true, description: '当同一发送者发送多条连续消息时，使用气泡的 group 属性（first、middle、last）来视觉上连接相关消息。' },
       { guidance: true, description: '使用 ChatSystemMessage 的 variant="divider" 作为日期分隔线，使用 default 作为内联状态通知。' },
       { guidance: true, description: '将 name 放在第一个气泡上，metadata 放在最后一个气泡上，使其与气泡的内边距对齐。' },
+      { guidance: true, description: '将自定义消息内容（卡片、附件、引用）包裹在 ghost 变体的气泡中，使其与气泡文本列对齐；需要占满消息列宽度时设置 width="100%"。' },
       { guidance: true, description: '提供 emptyState 属性，让新用户看到开始对话的提示，而不是空白屏幕。' },
       { guidance: true, description: '使用 ghost 气泡变体显示代码块或 Markdown 等富内容，无需可见边界。' },
       { guidance: false, description: '不要将 ChatSystemMessage 用于发送者内容，它没有头像、对齐或气泡。请使用带有发送者角色的 ChatMessage。' },
@@ -131,6 +133,7 @@ export const docsDense = {
       { guidance: true, description: 'Group prop on bubbles (first/middle/last) for consecutive same-sender messages; tightens corner radius.' },
       { guidance: true, description: 'SystemMessage: divider variant for date breaks, default for status notices.' },
       { guidance: true, description: 'Name on first bubble, metadata on last; aligns with bubble inline padding.' },
+      { guidance: true, description: 'Ghost bubble wraps custom content (cards/attachments); width="100%" spans full message column (default cap max(80%,280px)).' },
       { guidance: true, description: 'Provide emptyState so new users see a prompt, not a blank screen.' },
       { guidance: true, description: 'Ghost bubble variant for rich AI content like code/markdown without visible boundary.' },
       { guidance: false, description: 'SystemMessage for sender content: no avatar/alignment/bubble. Use ChatMessage instead.' },

package/src/Chat/ChatMessage.doc.mjs

@@ -17,7 +17,7 @@ export const docs = {
     {
       name: 'children',
       type: 'ReactNode',
-      description: 'Free-form content: bubbles, asset lists, tool calls, images.',
+      description: 'Free-form content: bubbles, asset lists, tool calls, images. Custom (non-bubble) children render flush with the message edge; wrap them in a ghost ChatMessageBubble to align them with the bubble text column.',
       required: true,
     },
     {
@@ -67,7 +67,7 @@ export const docsZh = {
   description: '发送者上下文包装器，根据发送者角色处理头像、名称、元数据和对齐方式。',
   propDescriptions: {
     sender: '消息发送者，控制对齐和布局。',
-    children: '自由内容：气泡、资源列表、工具调用、图片。',
+    children: '自由内容：气泡、资源列表、工具调用、图片。非气泡的自定义子内容默认与消息边缘齐平，可用 ghost 变体的 ChatMessageBubble 包裹使其与气泡文本列对齐。',
     avatar: '消息旁边渲染的头像元素。通常是 Avatar。',
     name: '消息正文上方渲染的发送者名称。当第一个子元素不是气泡时使用。',
     metadata: '消息正文下方渲染的元数据。当最后一个子元素不是气泡时使用。',
@@ -81,7 +81,7 @@ export const docsDense = {
   description: 'sender context wrapper; handles avatar+name+metadata+alignment by sender role',
   propDescriptions: {
     sender: 'who sent; controls alignment+layout',
-    children: 'free-form: bubbles, assets, tool calls, images',
+    children: 'free-form: bubbles, assets, tool calls, images; wrap non-bubble content in a ghost bubble to align with bubble text column',
     avatar: 'avatar element beside msg; typically Avatar',
     name: 'sender name above body; use when first child is raw (not bubble)',
     displayName: 'sender name above body; use when first child is raw (not bubble)',

package/src/Chat/ChatMessage.tsx

@@ -41,6 +41,13 @@ import {useTranslator} from '../i18n';
 export interface ChatMessageProps extends BaseProps<HTMLElement> {
   ref?: React.Ref<HTMLElement>;
   sender: ChatMessageSender;
+  /**
+   * Message body — bubbles, tool calls, images, or any free-form content.
+   * Custom (non-bubble) children render flush with the message edge; wrap
+   * them in a ghost bubble (`<ChatMessageBubble variant="ghost">`) to align
+   * them with the bubble's text column, and add `width="100%"` when they
+   * should span the full message column.
+   */
   children: ReactNode;
   avatar?: ReactNode;
   /**

package/src/Chat/ChatMessageBubble.doc.mjs

@@ -45,6 +45,11 @@ export const docs = {
       type: "'first' | 'middle' | 'last'",
       description: 'Position within a multi-bubble group. Controls corner radius reduction on the sender side. Leave unset for standalone bubbles (full radius).',
     },
+    {
+      name: 'width',
+      type: 'SizeValue',
+      description: 'Width of the bubble (number = pixels, string = used as-is). When set, replaces the default max(80%, 280px) width cap. Combine with variant="ghost" to let custom content (an artifact card, attachments) span the full message column.',
+    },
   ],
 };
 
@@ -59,6 +64,7 @@ export const docsZh = {
     name: '气泡上方渲染的发送者名称，与气泡文本内边距对齐。用于消息中的第一个气泡。',
     metadata: '气泡下方渲染的元数据内容，与气泡文本内边距对齐。用于消息中的最后一个气泡。',
     group: '多气泡组中的位置。控制发送者侧的圆角缩减。',
+    width: '气泡宽度（数字 = 像素，字符串 = 按原样使用）。设置后替代默认的 max(80%, 280px) 宽度上限；与 ghost 变体组合可让自定义内容占满消息列宽度。',
   },
 };
 
@@ -74,5 +80,6 @@ export const docsDense = {
     displayName: 'sender name above bubble, aligned w/ bubble padding',
     metadata: 'metadata below bubble, aligned w/ bubble padding',
     group: 'position in multi-bubble group; controls corner radius reduction',
+    width: 'bubble width (number=px, string=as-is); replaces default max(80%,280px) cap; ghost+width="100%" spans full message column',
   },
 };

package/src/Chat/ChatMessageBubble.test.tsx

@@ -7,6 +7,16 @@ import {ChatMessageBubble} from './ChatMessageBubble';
 import {ChatMessageList} from './ChatMessageList';
 import {ChatMessageMetadata} from './ChatMessageMetadata';
 
+/**
+ * Classes shared between two elements. StyleX emits one atomic class per
+ * style declaration, so two elements share a class exactly when they share
+ * a declaration — e.g. the same density paddingInline.
+ */
+function sharedClasses(a: Element, b: Element): string[] {
+  const bClasses = new Set(Array.from(b.classList));
+  return Array.from(a.classList).filter(c => bClasses.has(c));
+}
+
 describe('ChatMessageBubble', () => {
   it('renders children', () => {
     render(
@@ -29,9 +39,7 @@ describe('ChatMessageBubble', () => {
 
   it('defaults to assistant when no context', () => {
     render(
-      <ChatMessageBubble data-testid="bubble">
-        Standalone
-      </ChatMessageBubble>,
+      <ChatMessageBubble data-testid="bubble">Standalone</ChatMessageBubble>,
     );
     const el = screen.getByTestId('bubble');
     expect(el.className).toContain('assistant');
@@ -41,9 +49,7 @@ describe('ChatMessageBubble', () => {
     render(
       <ChatMessageList density="compact">
         <ChatMessage sender="assistant">
-          <ChatMessageBubble data-testid="bubble">
-            Compact
-          </ChatMessageBubble>
+          <ChatMessageBubble data-testid="bubble">Compact</ChatMessageBubble>
         </ChatMessage>
       </ChatMessageList>,
     );
@@ -59,6 +65,89 @@ describe('ChatMessageBubble', () => {
     );
     expect(screen.getByTestId('my-bubble')).toBeTruthy();
   });
+
+  it('ghost variant aligns custom content with the bubble text column (#2574)', () => {
+    // Repro from the issue: a raw child renders flush with the message
+    // edge — it carries none of the inset the bubble's name slot gets.
+    const {container} = render(
+      <ChatMessage sender="assistant">
+        <ChatMessageBubble name="Navi">Hello</ChatMessageBubble>
+        <div data-testid="raw">Artifact card</div>
+        <ChatMessageBubble variant="ghost" data-testid="ghost">
+          Artifact card
+        </ChatMessageBubble>
+      </ChatMessage>,
+    );
+    const nameSlot = container.querySelector('[data-chat-name]')!;
+    expect(nameSlot).toBeTruthy();
+
+    // Unwrapped custom content: no shared inset — the misalignment case.
+    expect(sharedClasses(screen.getByTestId('raw'), nameSlot)).toEqual([]);
+
+    // Ghost-wrapped content: shares the bubble slot's paddingInline
+    // declaration, so its text column matches the filled bubble exactly.
+    expect(
+      sharedClasses(screen.getByTestId('ghost'), nameSlot).length,
+    ).toBeGreaterThan(0);
+  });
+
+  it('ghost inset tracks message density', () => {
+    const renderAtDensity = (density: 'balanced' | 'spacious') => {
+      const {container} = render(
+        <ChatMessage sender="assistant" density={density}>
+          <ChatMessageBubble name="Navi">Hello</ChatMessageBubble>
+          <ChatMessageBubble variant="ghost" data-testid={`ghost-${density}`}>
+            Card
+          </ChatMessageBubble>
+        </ChatMessage>,
+      );
+      return sharedClasses(
+        screen.getByTestId(`ghost-${density}`),
+        container.querySelector('[data-chat-name]')!,
+      );
+    };
+
+    const balancedInset = renderAtDensity('balanced');
+    const spaciousInset = renderAtDensity('spacious');
+
+    // Both densities align with their own bubble's slot padding...
+    expect(balancedInset.length).toBeGreaterThan(0);
+    expect(spaciousInset.length).toBeGreaterThan(0);
+    // ...and spacious uses a wider inset than balanced.
+    expect(spaciousInset).not.toEqual(balancedInset);
+  });
+
+  it('width prop replaces the default width cap', () => {
+    render(
+      <ChatMessage sender="assistant">
+        <ChatMessageBubble data-testid="capped">Text</ChatMessageBubble>
+        <ChatMessageBubble variant="ghost" width="100%" data-testid="full">
+          Card
+        </ChatMessageBubble>
+      </ChatMessage>,
+    );
+    const capped = screen.getByTestId('capped');
+    const full = screen.getByTestId('full');
+
+    // Default bubbles keep the cap; a width bubble replaces it with none.
+    expect(getComputedStyle(capped).maxWidth).toMatch(/^max\(80%,\s*280px\)$/);
+    expect(getComputedStyle(full).maxWidth).toBe('none');
+    // The dynamic width value is set on the element (string passes through).
+    expect(full.getAttribute('style')).toContain('100%');
+  });
+
+  it('numeric width is treated as pixels', () => {
+    render(
+      <ChatMessage sender="assistant">
+        <ChatMessageBubble width={420} data-testid="fixed">
+          Artifact
+        </ChatMessageBubble>
+      </ChatMessage>,
+    );
+    expect(screen.getByTestId('fixed').getAttribute('style')).toContain(
+      '420px',
+    );
+  });
 });
 
 describe('ChatMessageMetadata', () => {

package/src/Chat/ChatMessageBubble.tsx

@@ -15,6 +15,9 @@
  * - If you use bubbles on one side (e.g. assistant), use them consistently
  *   for all messages on that side. Use `ghost` variant for content that
  *   needs alignment without a visual boundary.
+ * - For custom content (cards, attachments, citations) that should span
+ *   the full message column instead of the default width cap, combine
+ *   `ghost` with `width="100%"` (#2574).
  * - Put `name` on the first bubble in a message, `metadata` on the last.
  * - For unbubbled messages, use ChatMessage's `name` and `metadata`
  *   props instead.
@@ -36,6 +39,7 @@ import {
 } from '../theme/tokens.stylex';
 import {useChatMessageContext} from './ChatContext';
 import {mergeProps} from '../utils';
+import type {SizeValue} from '../utils/types';
 import type {BaseProps} from '../BaseProps';
 import {themeProps} from '../utils/themeProps';
 
@@ -83,6 +87,15 @@ export interface ChatMessageBubbleProps extends BaseProps<HTMLDivElement> {
    * Leave unset for standalone bubbles (full radius).
    */
   group?: 'first' | 'middle' | 'last';
+
+  /**
+   * Width of the bubble.
+   * Numbers are treated as pixels, strings are used as-is (e.g. "100%").
+   * When set, replaces the default `max(80%, 280px)` width cap; leave unset
+   * to keep the cap. Combine with `variant="ghost"` to let custom content
+   * (an artifact card, attachments) span the full message column.
+   */
+  width?: SizeValue;
 }
 
 // =============================================================================
@@ -189,6 +202,16 @@ const styles = stylex.create({
   },
 });
 
+// Dynamic styles for sizing props
+const dynamicStyles = stylex.create({
+  sizing: (width: SizeValue) => ({
+    width,
+    // An explicit width replaces the default cap — a full-column or
+    // fixed-width bubble shouldn't also be clamped by max(80%, 280px).
+    maxWidth: 'none',
+  }),
+});
+
 // =============================================================================
 // Component
 // =============================================================================
@@ -216,6 +239,7 @@ export function ChatMessageBubble({
   name,
   metadata,
   group,
+  width,
   xstyle,
   className,
   style: styleProp,
@@ -292,6 +316,7 @@ export function ChatMessageBubble({
             paddingStyle,
             variant === 'ghost' && styles.paddingBlockNone,
             groupStyle,
+            width != null && dynamicStyles.sizing(width),
             xstyle,
           ),
           className,

package/src/CheckboxInput/CheckboxInput.tsx

@@ -81,6 +81,26 @@ const styles = stylex.create({
     opacity: 0,
     cursor: 'pointer',
     zIndex: 1,
+    minInlineSize: {
+      default: null,
+      '@media (pointer: coarse)': '24px',
+    },
+    minBlockSize: {
+      default: null,
+      '@media (pointer: coarse)': '24px',
+    },
+    insetBlockStart: {
+      default: null,
+      '@media (pointer: coarse)': '50%',
+    },
+    insetInlineStart: {
+      default: null,
+      '@media (pointer: coarse)': '50%',
+    },
+    transform: {
+      default: null,
+      '@media (pointer: coarse)': 'translate(-50%, -50%)',
+    },
   },
   inputDisabled: {
     cursor: 'not-allowed',

package/src/CodeBlock/CodeBlock.doc.mjs

@@ -146,6 +146,9 @@ export const docs = {
       {className: 'astryx-codeblock-title', visualProps: ['size', 'language']},
       {className: 'astryx-codeblock-copy-button'},
     ],
+    vars: [
+      {name: '--_codeblock-gutter-width', description: 'Width of the line-number gutter, computed from the digit count of the last line so the code column starts at a stable offset.', default: '2ch', private: true},
+    ],
   },
   usage: {
     description: 'CodeBlock renders syntax-highlighted code with line numbers, a copy button, and optional collapsible sections. Use CodeBlock for multi-line snippets like source files, terminal commands, and configuration examples. Use Code for inline references to function names, variables, or CLI flags within body text.',

package/src/CommandPalette/CommandPaletteFooter.tsx

@@ -24,6 +24,7 @@ import {
 } from '../theme/tokens.stylex';
 import {Kbd} from '../Kbd';
 import {themeProps} from '../utils/themeProps';
+import {useTranslator} from '../i18n';
 
 const styles = stylex.create({
   footer: {
@@ -85,6 +86,8 @@ export function CommandPaletteFooter({
   style,
   ...props
 }: CommandPaletteFooterProps) {
+  const t = useTranslator();
+
   return (
     <div
       ref={ref}
@@ -100,15 +103,15 @@ export function CommandPaletteFooter({
           <span {...stylex.props(styles.hint)}>
             <Kbd keys="up" />
             <Kbd keys="down" />
-            Navigate
+            {t('@astryx.commandPalette.footer.navigate')}
           </span>
           <span {...stylex.props(styles.hint)}>
             <Kbd keys="enter" />
-            Select
+            {t('@astryx.commandPalette.footer.select')}
           </span>
           <span {...stylex.props(styles.hint)}>
             <Kbd keys="escape" />
-            Close
+            {t('@astryx.commandPalette.footer.close')}
           </span>
         </>
       )}

package/src/DateTimeInput/DateTimeInput.tsx

@@ -594,10 +594,12 @@ export function DateTimeInput({
 
   const resolvedTimePlaceholder = useMemo(() => {
     if (isTimeFocused && !timeDisplayValue) {
-      return hourFormat === '12h' ? 'e.g., 2:30 PM' : 'e.g., 14:30';
+      return hourFormat === '12h'
+        ? t('@astryx.dateTimeInput.timeHint12h')
+        : t('@astryx.dateTimeInput.timeHint24h');
     }
     return timePlaceholder;
-  }, [isTimeFocused, timeDisplayValue, hourFormat, timePlaceholder]);
+  }, [isTimeFocused, timeDisplayValue, hourFormat, timePlaceholder, t]);
 
   // --- Unified change handler ---
   const fireChange = useCallback(

package/src/DropdownMenu/DropdownMenuSubMenu.test.tsx

@@ -8,7 +8,7 @@
 
 import {describe, it, expect, vi, beforeEach} from 'vitest';
 import {useState} from 'react';
-import {render, screen, waitFor, fireEvent} from '@testing-library/react';
+import {render, screen, waitFor, fireEvent, act} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {DropdownMenu} from './DropdownMenu';
 import {DropdownMenuItem} from './DropdownMenuItem';
@@ -708,3 +708,74 @@ describe('DropdownMenuSubMenu theming slots', () => {
     ).toBeInTheDocument();
   });
 });
+
+describe('DropdownMenuSubMenu hover/click guard', () => {
+  it('keeps the flyout open when a hover-open is immediately clicked', async () => {
+    vi.useFakeTimers({shouldAdvanceTime: true});
+    const user = userEvent.setup({advanceTimers: vi.advanceTimersByTime});
+    render(<MoveMenu />);
+
+    await user.click(screen.getByRole('button', {name: /Actions/}));
+    const trigger = screen.getByRole('menuitem', {
+      name: /Move to/,
+      hidden: true,
+    });
+
+    await user.hover(trigger);
+    act(() => {
+      vi.advanceTimersByTime(300);
+    });
+    expect(trigger).toHaveAttribute('aria-expanded', 'true');
+
+    await user.click(trigger);
+    expect(trigger).toHaveAttribute('aria-expanded', 'true');
+    expect(
+      screen.getByRole('menuitem', {name: 'Folder A', hidden: true}),
+    ).toHaveFocus();
+
+    vi.useRealTimers();
+  });
+
+  it('closes on a click that lands well after the hover-open', async () => {
+    vi.useFakeTimers({shouldAdvanceTime: true});
+    const user = userEvent.setup({advanceTimers: vi.advanceTimersByTime});
+    render(<MoveMenu />);
+
+    await user.click(screen.getByRole('button', {name: /Actions/}));
+    const trigger = screen.getByRole('menuitem', {
+      name: /Move to/,
+      hidden: true,
+    });
+
+    await user.hover(trigger);
+    act(() => {
+      vi.advanceTimersByTime(300);
+    });
+    act(() => {
+      vi.advanceTimersByTime(1200);
+    });
+
+    await user.click(trigger);
+    expect(trigger).toHaveAttribute('aria-expanded', 'false');
+
+    vi.useRealTimers();
+  });
+
+  it('moves focus into the flyout synchronously on a click-open', async () => {
+    const user = userEvent.setup();
+    render(<MoveMenu />);
+
+    await user.click(screen.getByRole('button', {name: /Actions/}));
+    const trigger = screen.getByRole('menuitem', {
+      name: /Move to/,
+      hidden: true,
+    });
+
+    await user.click(trigger);
+
+    // No waitFor: a deferred (rAF) focus would fail here.
+    expect(
+      screen.getByRole('menuitem', {name: 'Folder A', hidden: true}),
+    ).toHaveFocus();
+  });
+});

package/src/DropdownMenu/DropdownMenuSubMenu.tsx

@@ -299,12 +299,16 @@ export function DropdownMenuSubMenu(
 
   // Hover-intent: entering the trigger opens after a short delay; leaving
   // either surface closes after a delay. Hover-open does not steal focus.
-  const {triggerProps, contentProps} = useMenuHover<HTMLDivElement>({
-    show: showLayer,
-    hide: hideLayer,
-    isOpen,
-    isEnabled: canOpen,
-  });
+  // Hover intent and the shared hover→click guard only: this level owns its own
+  // click handling, roving focus and typeahead. popover="manual", so the
+  // invoker wiring other consumers need does not apply.
+  const {triggerProps, contentProps, confirmHoverOpen} =
+    useMenuHover<HTMLDivElement>({
+      show: showLayer,
+      hide: hideLayer,
+      isOpen,
+      isEnabled: canOpen,
+    });
 
   const open = useCallback(
     (options?: {focusFirst?: boolean}) => {
@@ -313,18 +317,12 @@ export function DropdownMenuSubMenu(
       }
       layer.show();
       if (options?.focusFirst) {
-        requestAnimationFrame(() => {
-          // Move focus into the flyout. When it has no focusable items yet
-          // (e.g. an async submenu showing only a disabled "Loading…" row via
-          // hasSpinner), focusFirst() finds nothing — fall back to focusing the
-          // flyout container itself so keyboard ownership still transfers off
-          // the parent list. Otherwise the parent would keep focus, letting
-          // arrow keys rove the parent while the empty flyout stays open.
-          const focusedItem = focusFirst();
-          if (!focusedItem) {
-            menuRef.current?.focus();
-          }
-        });
+        // Synchronous by design — see the focus note in useMenuHover. A
+        // still-loading flyout has no focusable item, so fall back to the
+        // container: keyboard ownership must leave the parent list either way.
+        if (!focusFirst()) {
+          menuRef.current?.focus();
+        }
       }
     },
     [canOpen, layer, focusFirst, menuRef],
@@ -354,13 +352,19 @@ export function DropdownMenuSubMenu(
     if (isDisabled) {
       return;
     }
-    // Click toggles the flyout, moving focus into it on open.
+    // Toggles, except for the click that follows a hover-open (#3121).
     if (isOpen) {
+      if (confirmHoverOpen()) {
+        if (!focusFirst()) {
+          menuRef.current?.focus();
+        }
+        return;
+      }
       close({focusTrigger: true});
     } else {
       open({focusFirst: true});
     }
-  }, [isDisabled, isOpen, open, close]);
+  }, [isDisabled, isOpen, open, close, confirmHoverOpen, focusFirst, menuRef]);
 
   const handleTriggerKeyDown = useCallback(
     (e: React.KeyboardEvent) => {

package/src/HoverCard/HoverCard.doc.mjs

@@ -114,7 +114,7 @@ export const docs = {
       { guidance: false, description: 'Place critical actions or required information inside a hover card; users may miss content that only appears on hover.' },
       { guidance: false, description: 'Use a hover card when a simple Tooltip or Popover would suffice.' },
       { guidance: false, description: 'Use a HoverCard for content the user must interact with; it disappears when the cursor leaves.' },
-      { guidance: false, description: 'Nest a HoverCard whose content has block elements directly inside phrasing-only contexts such as a <p>, <label>, or heading. The card renders inline, so block content there is invalid HTML the browser reparents. Wrap the surrounding text in a block element (e.g. a <div>) instead.' },
+      { guidance: true, description: 'Prefer placing HoverCard in a block context rather than directly in a <p>, heading, or link. Those placements are supported when necessary through a corrective portal, but the DOM and tab order may differ.' },
     ],
     anatomy: [
       {name: 'Trigger', required: true, description: 'The element that opens the hover card on hover or focus: a button, link, or inline text.'},
@@ -229,7 +229,7 @@ export const docsZh = {
       { guidance: false, description: 'Place critical actions or required information inside a hover card; users may miss content that only appears on hover.' },
       { guidance: false, description: 'Use a hover card when a simple Tooltip or Popover would suffice.' },
       { guidance: false, description: 'Use a HoverCard for content the user must interact with; it disappears when the cursor leaves.' },
-      { guidance: false, description: 'Nest a HoverCard whose content has block elements directly inside phrasing-only contexts such as a <p>, <label>, or heading. The card renders inline, so block content there is invalid HTML the browser reparents. Wrap the surrounding text in a block element (e.g. a <div>) instead.' },
+      { guidance: true, description: 'Prefer placing HoverCard in a block context rather than directly in a <p>, heading, or link. Those placements are supported when necessary through a corrective portal, but the DOM and tab order may differ.' },
     ],
   },
 };
@@ -247,7 +247,7 @@ export const docsDense = {
       { guidance: false, description: 'Place critical actions or required information inside a hover card; users may miss content that only appears on hover.' },
       { guidance: false, description: 'Use a hover card when a simple Tooltip or Popover would suffice.' },
       { guidance: false, description: 'Use a HoverCard for content the user must interact with; it disappears when the cursor leaves.' },
-      { guidance: false, description: 'Nest a block-content HoverCard directly inside phrasing-only contexts (<p>, <label>, heading); it renders inline so block content is invalid HTML there. Wrap surrounding text in a block element instead.' },
+      { guidance: true, description: 'Prefer a block context over a direct <p>, heading, or link placement. Those placements work when necessary through a corrective portal, but DOM/tab order may differ.' },
     ],
   },
   components: [