@astryxdesign/core 0.7.2 → 0.7.3-canary.02f5fe4

package/src/CheckboxInput/CheckboxInput.test.tsx

@@ -278,7 +278,7 @@ describe('CheckboxInput', () => {
     );
     const checkbox = screen.getByRole('checkbox');
     expect(checkbox).toBeChecked();
-    expect(checkbox).toBeDisabled();
+    expect(checkbox).toHaveAttribute('aria-disabled', 'true');
     expect(checkbox).toHaveAttribute('type', 'checkbox');
   });
 
@@ -588,16 +588,55 @@ describe('CheckboxInput', () => {
       expect(checkbox).not.toBeChecked();
     });
 
-    it('remains natively disabled when disabled without a reason', () => {
+    it('stays focusable via aria-disabled when disabled without a reason', async () => {
+      const user = userEvent.setup();
+      const onChange = vi.fn();
+      const onClick = vi.fn();
+      render(
+        <form>
+          <CheckboxInput
+            label="Accept terms"
+            value={false}
+            onChange={onChange}
+            onClick={onClick}
+            htmlName="terms"
+            isRequired
+            isDisabled
+          />
+        </form>,
+      );
+      const checkbox = screen.getByRole('checkbox');
+      expect(checkbox).not.toHaveAttribute('disabled');
+      expect(checkbox).toHaveAttribute('aria-disabled', 'true');
+      await user.tab();
+      expect(checkbox).toHaveFocus();
+      await user.keyboard(' ');
+      await user.click(checkbox);
+      expect(onChange).not.toHaveBeenCalled();
+      expect(onClick).not.toHaveBeenCalled();
+      expect(checkbox).not.toBeChecked();
+      const form = checkbox.closest('form')!;
+      expect(form.checkValidity()).toBe(true);
+      expect([...new FormData(form).keys()]).toEqual([]);
+    });
+
+    it('keeps a disabled indeterminate checkbox mixed after Space or a click', async () => {
+      const user = userEvent.setup();
       render(
         <CheckboxInput
-          label="Accept terms"
-          value={false}
+          label="Select all"
+          value="indeterminate"
           onChange={() => {}}
           isDisabled
         />,
       );
-      expect(screen.getByRole('checkbox')).toBeDisabled();
+      const checkbox = screen.getByRole<HTMLInputElement>('checkbox');
+      expect(checkbox.indeterminate).toBe(true);
+      await user.tab();
+      await user.keyboard(' ');
+      fireEvent.click(checkbox);
+      expect(checkbox.indeterminate).toBe(true);
+      expect(checkbox).not.toBeChecked();
     });
   });
   describe('form participation', () => {

package/src/CheckboxInput/CheckboxInput.tsx

@@ -19,7 +19,6 @@
 import {
   useId,
   useCallback,
-  use,
   useOptimistic,
   useRef,
   useTransition,
@@ -52,7 +51,6 @@ import {usePressFeedback} from '../hooks/usePressFeedback';
 import {useResolvedRequired} from '../hooks/useResolvedRequired';
 import {useIndicator} from '../Indicator';
 import {themeProps} from '../utils/themeProps';
-import {CheckboxListContext} from '../CheckboxList/CheckboxListContext';
 
 import {useMergedRefs} from '../hooks/useMergedRefs';
 
@@ -354,21 +352,10 @@ export function CheckboxInput({
   const [optimisticValue, setOptimisticValue] = useOptimistic(value);
   const isBusy = isLoading || optimisticValue !== value;
 
-  // Disabled-reason tooltip. Disabled controls swallow pointer events, so the
-  // tooltip listeners attach to the checkbox row (which already exists) and the
-  // native checkbox stays perceivable via aria-disabled instead of the disabled
-  // attribute. Value mutation is blocked by the isDisabled guard in onChange.
+  // A disabled checkbox stays focusable via aria-disabled instead of the
+  // native disabled attribute (spec:AST-085 FR1). Value mutation is blocked by
+  // the click and onChange guards on the input.
   const showsDisabledMessage = isDisabled && !!disabledMessage;
-  // Keep the native checkbox focusable via aria-disabled either when it renders
-  // its own reason tooltip, or when it sits in a CheckboxList whose whole-group
-  // `disabledMessage` (shown on the group container) needs each checkbox to
-  // stay keyboard-perceivable. The group signals this through context rather
-  // than a public prop.
-  const checkboxListContext = use(CheckboxListContext);
-  const isFocusableDisabled =
-    isDisabled &&
-    (showsDisabledMessage ||
-      (checkboxListContext?.hasDisabledMessage ?? false));
   const disabledMessageTooltip = useTooltip({
     placement: 'above',
     // The container row is not naturally focusable; focusin bubbles up from the
@@ -384,7 +371,7 @@ export function CheckboxInput({
   // `opacity: 0`, and only the indicator's own element can shape the outline
   // to match it. See useIndicatorFocusRing.
   const indicatorRef = useRef<HTMLSpanElement>(null);
-  const {focusProps} = useIndicatorFocusRing(indicatorRef, isDisabled);
+  const {focusProps} = useIndicatorFocusRing(indicatorRef);
 
   const isIndeterminate = optimisticValue === 'indeterminate';
   const isChecked = optimisticValue === true;
@@ -471,22 +458,25 @@ export function CheckboxInput({
             )}
             id={id}
             type="checkbox"
-            // Withhold the name while disabled: with a disabledMessage the
-            // input stays focusable (not natively disabled), and a disabled
-            // control must not submit.
+            // Withhold the name while disabled: the input stays focusable (not
+            // natively disabled), and a disabled control must not submit.
             name={isDisabled ? undefined : htmlName}
             checked={isChecked}
-            // With a disabledMessage the checkbox keeps focusability via
-            // aria-disabled so the reason is focus-discoverable; toggling is
-            // still blocked by the isDisabled guard in onChange below.
-            disabled={isDisabled && !isFocusableDisabled}
-            aria-disabled={isFocusableDisabled ? 'true' : undefined}
-            form={isFocusableDisabled ? '' : undefined}
+            aria-disabled={isDisabled ? 'true' : undefined}
+            // Detached from its form while disabled, so it neither submits nor
+            // blocks submission through `required` (spec:AST-085 FR3).
+            form={isDisabled ? '' : undefined}
+            // Native `disabled` suppressed onClick (FR2); preventDefault here
+            // would desync React's controlled checked state.
+            onClick={isDisabled ? undefined : rest.onClick}
             readOnly={isReadOnly}
             required={isRequired}
             aria-required={isEffectivelyRequired ? 'true' : undefined}
             onChange={e => {
               if (isDisabled || isBusy || isReadOnly) {
+                // Activation clears the native mixed state; React restores
+                // only `checked`, so restore `indeterminate` too.
+                e.target.indeterminate = isIndeterminate;
                 return;
               }
               const checked = e.target.checked;

package/src/CheckboxInput/__tests__/Checkbox.a11y.states.ts

@@ -125,8 +125,8 @@ export const CHECKBOX_BINDING_STATES = [
   {
     id: 'input-disabled',
     binding: 'CheckboxInput',
-    summary: 'a natively disabled checkbox outside the tab sequence',
-    facts: facts({operable: false, focusable: false, disabled: true}),
+    summary: 'a disabled checkbox that keeps its tab stop',
+    facts: facts({operable: false, focusable: true, disabled: true}),
     visibleLabel: 'Managed setting',
     storyId: 'a11y-checkbox-pattern--input-disabled',
   },
@@ -269,7 +269,7 @@ export const CHECKBOX_BINDING_STATES = [
     id: 'list-item-disabled',
     binding: 'CheckboxListItem',
     summary: 'an individually disabled list item',
-    facts: facts({operable: false, focusable: false, disabled: true}),
+    facts: facts({operable: false, focusable: true, disabled: true}),
     visibleLabel: 'SMS',
     visibleLabelSelector: '[data-a11y-visible-label]',
     storyId: 'a11y-checkbox-pattern--list-item-disabled',

package/src/CheckboxList/CheckboxList.test.tsx

@@ -288,8 +288,9 @@ describe('CheckboxList', () => {
       </CheckboxList>,
     );
     const checkboxes = screen.getAllByRole('checkbox');
-    expect(checkboxes[0]).toBeDisabled();
-    expect(checkboxes[1]).toBeDisabled();
+    expect(checkboxes[0]).toHaveAttribute('aria-disabled', 'true');
+    expect(checkboxes[1]).toHaveAttribute('aria-disabled', 'true');
+    expect(checkboxes[0]).not.toHaveAttribute('disabled');
   });
 
   it('does not call onChange when group is disabled', () => {
@@ -317,8 +318,9 @@ describe('CheckboxList', () => {
       </CheckboxList>,
     );
     const checkboxes = screen.getAllByRole('checkbox');
-    expect(checkboxes[0]).not.toBeDisabled();
-    expect(checkboxes[1]).toBeDisabled();
+    expect(checkboxes[0]).not.toHaveAttribute('aria-disabled');
+    expect(checkboxes[1]).toHaveAttribute('aria-disabled', 'true');
+    expect(checkboxes[1]).not.toHaveAttribute('disabled');
   });
 
   it('throws when item has no value prop inside collection-mode CheckboxList', () => {
@@ -1137,7 +1139,7 @@ describe('CheckboxListItem ARIA props', () => {
       expect(onChange).not.toHaveBeenCalled();
     });
 
-    it('keeps checkboxes natively disabled when disabled without a reason', () => {
+    it('keeps checkboxes focusable via aria-disabled when disabled without a reason', () => {
       render(
         <CheckboxList
           label="Notifications"
@@ -1149,7 +1151,8 @@ describe('CheckboxListItem ARIA props', () => {
         </CheckboxList>,
       );
       for (const checkbox of screen.getAllByRole('checkbox', h)) {
-        expect(checkbox).toBeDisabled();
+        expect(checkbox).not.toHaveAttribute('disabled');
+        expect(checkbox).toHaveAttribute('aria-disabled', 'true');
       }
     });
   });

package/src/ClickableCard/ClickableCard.doc.mjs

@@ -24,7 +24,7 @@ export const docs = {
     {name: 'onClick', type: '(event: MouseEvent) => void', description: 'Click handler: fires on card surface only.'},
     {name: 'href', type: 'string', description: 'Navigation URL. Plain, new-tab, Cmd/Ctrl-click, and middle-click activation all follow the shared navigation rule described on the Link `href` prop.'},
     {name: 'target', type: 'string', description: 'Link target.', default: "'_self'"},
-    {name: 'isDisabled', type: 'boolean', description: 'Disables the card, removes a link destination, and leaves the card out of the tab order.', default: 'false'},
+    {name: 'isDisabled', type: 'boolean', description: 'Disables the card and removes a link destination; the card keeps its tab stop and is announced as disabled.', default: 'false'},
     {name: 'children', type: 'ReactNode', description: 'Card content.'},
     {name: 'padding', type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10', description: 'Inner padding.', default: '4'},
     {name: 'variant', type: "'default' | 'transparent' | 'muted' | 'blue' | 'cyan' | 'gray' | 'green' | 'orange' | 'pink' | 'purple' | 'red' | 'teal' | 'yellow'", description: 'Background color variant.', default: "'default'"},
@@ -75,7 +75,7 @@ export const docsDense = {
     onClick: 'click handler: fires on card surface only',
     href: 'navigation URL; every activation follows the shared navigation rule (see Link href)',
     target: 'link target',
-    isDisabled: 'disables card, removes link destination, and leaves tab order',
+    isDisabled: 'disables card, removes link destination, keeps tab stop',
     padding: 'inner padding',
     variant: 'background color variant',
     elevation: 'resting shadow depth: none|low|med|high; often raised to signal clickability',

package/src/ClickableCard/ClickableCard.test.tsx

@@ -129,7 +129,7 @@ describe('ClickableCard', () => {
     expect(link).toHaveAttribute('target', '_blank');
   });
 
-  it('disabled button is disabled and the surface runs nothing', () => {
+  it('disabled button stays focusable and the surface runs nothing', () => {
     const handleClick = vi.fn();
     render(
       <ClickableCard label="Disabled" onClick={handleClick} isDisabled>
@@ -137,13 +137,14 @@ describe('ClickableCard', () => {
       </ClickableCard>,
     );
     const button = screen.getByRole('button', {name: 'Disabled'});
-    expect(button).toBeDisabled();
+    expect(button).not.toHaveAttribute('disabled');
+    expect(button).toHaveAttribute('aria-disabled', 'true');
     fireEvent.click(screen.getByText('Content'));
     fireEvent.click(button);
     expect(handleClick).not.toHaveBeenCalled();
   });
 
-  it('disabled link has no live destination, leaves the tab order, and runs nothing', () => {
+  it('disabled link has no live destination, keeps its tab stop, and runs nothing', () => {
     const handleClick = vi.fn();
     render(
       <ClickableCard
@@ -157,7 +158,7 @@ describe('ClickableCard', () => {
     );
     const link = screen.getByRole('link', {name: 'Disabled link'});
     expect(link).toHaveAttribute('aria-disabled', 'true');
-    expect(link).toHaveAttribute('tabindex', '-1');
+    expect(link).toHaveAttribute('tabindex', '0');
     expect(link).not.toHaveAttribute('href');
     expect(link).not.toHaveAttribute('target');
     expect(fireEvent.click(link)).toBe(false);

package/src/ClickableCard/ClickableCard.tsx

@@ -51,6 +51,7 @@ import {interactionOverlayStyles} from '../utils/interactionOverlay.stylex';
 import {usePressFeedback} from '../hooks/usePressFeedback';
 
 import {useMergedRefs} from '../hooks/useMergedRefs';
+import {disabledInteractionProps} from '../utils/disabledInteraction';
 // =============================================================================
 // Styles — only the interactive layer, Card handles everything else
 // =============================================================================
@@ -210,8 +211,8 @@ export interface ClickableCardProps extends BaseProps {
 
   /**
    * Set to true to disable the card.
-   * Disabled action cards use a native disabled button. Disabled link cards
-   * render no live destination, leave the tab order, and expose aria-disabled.
+   * Disabled cards keep their tab stop and expose aria-disabled; activation is
+   * blocked, and disabled link cards render no live destination.
    */
   isDisabled?: boolean;
 
@@ -255,10 +256,6 @@ export interface ClickableCardProps extends BaseProps {
 // Component
 // =============================================================================
 
-function preventDisabledLinkClick(event: MouseEvent<HTMLAnchorElement>): void {
-  event.preventDefault();
-}
-
 /**
  * An interactive card that acts as a single navigation or action target.
  *
@@ -376,11 +373,12 @@ export function ClickableCard({
           ref={interactiveRef as React.Ref<HTMLAnchorElement>}
           href={isDisabled ? undefined : href}
           target={isDisabled ? undefined : target}
-          onClick={isDisabled ? preventDisabledLinkClick : undefined}
           role={isDisabled ? 'link' : undefined}
+          {...(isDisabled ? disabledInteractionProps() : null)}
           aria-label={label}
           aria-disabled={isDisabled || undefined}
-          tabIndex={isDisabled ? -1 : 0}
+          // A disabled card keeps its Tab stop (spec:AST-085 FR1).
+          tabIndex={0}
           {...stylex.props(styles.srOnly)}
         />
       ) : (
@@ -388,8 +386,10 @@ export function ClickableCard({
           ref={interactiveRef as React.Ref<HTMLButtonElement>}
           type="button"
           aria-label={label}
-          disabled={isDisabled}
+          aria-disabled={isDisabled || undefined}
           onClick={onClickProp}
+          // Focusable while disabled (FR1), but inert (FR2).
+          {...(isDisabled ? disabledInteractionProps() : null)}
           {...stylex.props(styles.srOnly)}
         />
       )}

package/src/CodeBlock/CodeBlock.highlightStyles.test.tsx

@@ -0,0 +1,87 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file CodeBlock.highlightStyles.test.tsx
+ * @input Uses vitest, @testing-library/react, CodeBlock, a mocked CSS Custom Highlight API
+ * @output Tests that the ::highlight() rules exist before a commit's layout effects run
+ * @position Performance regression evidence. Rules inserted after layout
+ *   effects make the browser restyle the whole document a second time once
+ *   any layout effect has read style, so their insertion point is pinned here.
+ */
+
+import {useLayoutEffect} from 'react';
+import {cleanup, render} from '@testing-library/react';
+import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest';
+
+class MockHighlight extends Set<Range> {}
+const realCss = globalThis.CSS;
+
+const STYLE_SELECTOR = 'style[data-astryx-highlight-styles]';
+
+beforeEach(() => {
+  // A fresh module instance, so the once-per-document insertion flag starts
+  // unset in every test.
+  vi.resetModules();
+  document.head.querySelectorAll(STYLE_SELECTOR).forEach(el => el.remove());
+  const highlights = new Map<string, MockHighlight>();
+  globalThis.CSS = {
+    escape: realCss.escape,
+    highlights: {
+      get: (name: string) => highlights.get(name),
+      set: (name: string, h: MockHighlight) => highlights.set(name, h),
+    } as unknown as HighlightRegistry,
+  } as typeof CSS;
+  vi.stubGlobal('Highlight', MockHighlight);
+});
+
+afterEach(() => {
+  cleanup();
+  globalThis.CSS = realCss;
+  vi.unstubAllGlobals();
+});
+
+describe('CodeBlock ::highlight() rules', () => {
+  it('are in the document before layout effects in the same commit run', async () => {
+    const {CodeBlock} = await import('./CodeBlock');
+    const seen: boolean[] = [];
+    function LayoutReader() {
+      useLayoutEffect(() => {
+        seen.push(document.head.querySelector(STYLE_SELECTOR) != null);
+      }, []);
+      return null;
+    }
+    render(
+      <>
+        <CodeBlock code="const a = 1;" language="ts" highlightMode="ranges" />
+        <LayoutReader />
+      </>,
+    );
+    expect(seen).toEqual([true]);
+  });
+
+  it('are inserted once for many code blocks', async () => {
+    const {CodeBlock} = await import('./CodeBlock');
+    render(
+      <>
+        {Array.from({length: 20}, (_, i) => (
+          <CodeBlock
+            key={i}
+            code={`const v${i} = ${i};`}
+            language="ts"
+            highlightMode="ranges"
+          />
+        ))}
+      </>,
+    );
+    expect(document.head.querySelectorAll(STYLE_SELECTOR)).toHaveLength(1);
+  });
+
+  it('are not inserted by range highlighting without the Highlight API', async () => {
+    vi.stubGlobal('Highlight', undefined);
+    const {CodeBlock} = await import('./CodeBlock');
+    render(
+      <CodeBlock code="const a = 1;" language="ts" highlightMode="ranges" />,
+    );
+    expect(document.head.querySelector(STYLE_SELECTOR)).toBeNull();
+  });
+});

package/src/CodeBlock/CodeBlock.tsx

@@ -803,11 +803,21 @@ function RangeCodeContent({
 }) {
   const codeRef = useRef<HTMLElement>(null);
 
+  // Insert the ::highlight() rules before the commit's layout reads, as the
+  // span path does. Inserted later, the new rules restyle the whole document
+  // a second time after any layout read in the same commit has already
+  // styled it, which on a long page full of code blocks costs a full style
+  // recalculation.
+  useInsertionEffect(() => {
+    if (hasHighlightAPI()) {
+      ensureHighlightStyles();
+    }
+  }, []);
+
   useEffect(() => {
     if (!hasHighlightAPI()) {
       return;
     }
-    ensureHighlightStyles();
 
     const codeEl = codeRef.current;
     if (!codeEl || tokenLines.length === 0) {

package/src/ComplexSelector/ComplexSelector.focusableDisabled.test.tsx

@@ -0,0 +1,76 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file ComplexSelector.focusableDisabled.test.tsx
+ * @input Uses vitest, @testing-library/react, ComplexSelector
+ * @output Conformance tests for spec:AST-085 FR1, FR2 and FR4 on ComplexSelector
+ * @position Testing; validates the disabled trigger of ComplexSelector.tsx
+ */
+
+import {describe, it, expect, vi} from 'vitest';
+import {act, render, screen} from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import {ComplexSelector} from './ComplexSelector';
+
+function Harness(props: {
+  isDisabled: boolean;
+  onClick?: () => void;
+  onKeyDown?: () => void;
+}) {
+  return (
+    <>
+      <button type="button">Before</button>
+      <ComplexSelector label="View options" value={[]} {...props}>
+        {() => <button type="button">Apply</button>}
+      </ComplexSelector>
+      <button type="button">After</button>
+    </>
+  );
+}
+
+const trigger = () => screen.getByRole('button', {name: 'View options'});
+
+describe('ComplexSelector disabled (spec:AST-085)', () => {
+  it('FR1: renders no native disabled and keeps its tab stop', async () => {
+    const user = userEvent.setup();
+    const {container} = render(<Harness isDisabled />);
+    expect(container.querySelector('[disabled]')).toBeNull();
+    expect(trigger()).toHaveAttribute('aria-disabled', 'true');
+    await user.click(screen.getByRole('button', {name: 'Before'}));
+    await user.tab();
+    expect(trigger()).toHaveFocus();
+    await user.tab();
+    expect(screen.getByRole('button', {name: 'After'})).toHaveFocus();
+  });
+
+  it('FR2: no press or key opens it or reaches a caller or ancestor handler', async () => {
+    const user = userEvent.setup();
+    const onClick = vi.fn();
+    const onKeyDown = vi.fn();
+    const onAncestorClick = vi.fn();
+    render(
+      <div onClick={onAncestorClick}>
+        <Harness isDisabled onClick={onClick} onKeyDown={onKeyDown} />
+      </div>,
+    );
+    await user.click(trigger());
+    await user.click(trigger().parentElement!);
+    trigger().focus();
+    for (const key of ['{Enter}', ' ', '{ArrowDown}']) {
+      await user.keyboard(key);
+    }
+    expect(trigger()).toHaveAttribute('aria-expanded', 'false');
+    expect(screen.queryByRole('dialog')).toBeNull();
+    expect(onClick).not.toHaveBeenCalled();
+    expect(onKeyDown).not.toHaveBeenCalled();
+    expect(onAncestorClick).not.toHaveBeenCalled();
+  });
+
+  it('FR4: keeps focus when it becomes disabled while focused', () => {
+    const {rerender} = render(<Harness isDisabled={false} />);
+    act(() => trigger().focus());
+    rerender(<Harness isDisabled />);
+    expect(trigger()).toHaveFocus();
+    expect(trigger()).toHaveAttribute('aria-disabled', 'true');
+  });
+});

package/src/ComplexSelector/ComplexSelector.tsx

@@ -609,10 +609,24 @@ export function ComplexSelector<Value>({
     event: React.KeyboardEvent<HTMLElement>,
   ) => {
     handleTriggerKeyDown(event);
-    onKeyDownProp?.(event);
+    // A disabled trigger keeps its tab stop but invokes no callback
+    // (`spec:AST-085` FR2).
+    if (!isDisabled) {
+      onKeyDownProp?.(event);
+    }
+  };
+  // A press on a disabled control reaches no handler, the component's or an
+  // ancestor's, as with a natively disabled button (`spec:AST-085` FR2).
+  const swallowDisabledPress = (event: React.MouseEvent<HTMLElement>) => {
+    event.preventDefault();
+    event.stopPropagation();
   };
   const handleControlBoxClick = useCallback(
     (event: React.MouseEvent<HTMLDivElement>) => {
+      if (isDisabled) {
+        event.stopPropagation();
+        return;
+      }
       if (triggerRef.current?.contains(event.target as Node)) {
         return;
       }
@@ -620,7 +634,7 @@ export function ComplexSelector<Value>({
       // press on the trigger itself, caller `onClick` included.
       triggerRef.current?.click();
     },
-    [],
+    [isDisabled],
   );
 
   useImperativeHandle(
@@ -767,8 +781,11 @@ export function ComplexSelector<Value>({
           aria-required={isEffectivelyRequired ? 'true' : undefined}
           aria-invalid={status?.type === 'error' ? 'true' : undefined}
           aria-busy={isBusy || undefined}
-          disabled={isDisabled}
-          onClick={handleTriggerButtonClick}
+          // A disabled trigger keeps its tab stop and says so through
+          // aria-disabled (`spec:AST-085` FR1). Its press runs neither the
+          // caller's handler nor the toggle (FR2).
+          aria-disabled={isDisabled ? 'true' : undefined}
+          onClick={isDisabled ? swallowDisabledPress : handleTriggerButtonClick}
           onKeyDown={handleTriggerButtonKeyDown}
           {...stylex.props(styles.trigger)}>
           <span {...stylex.props(styles.triggerText)}>{triggerContent}</span>

package/src/ContextMenu/ContextMenu.test.tsx

@@ -24,6 +24,7 @@ import {
   ContextMenuRadioItem,
 } from './index';
 import {DropdownMenuItem} from '../DropdownMenu/DropdownMenuItem';
+import {DropdownMenuSubMenu} from '../DropdownMenu/DropdownMenuSubMenu';
 import {Divider} from '../Divider';
 import {useLayerDismissal} from '../Layer/useLayerDismissal';
 import {warmMenuBottomSheet} from '../DropdownMenu/__tests__/warmMenuBottomSheet';
@@ -706,6 +707,46 @@ describe('ContextMenu dividers', () => {
 });
 
 describe('ContextMenu compound mode', () => {
+  it('shows a sub-menu with a header or footer as its rows alone, and says why in development', async () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    try {
+      render(
+        <ContextMenu
+          menuContent={
+            <>
+              <DropdownMenuItem label="Rename" onClick={() => {}} />
+              <DropdownMenuSubMenu
+                label="Labels"
+                header={<input aria-label="Filter labels" />}
+                footer={<button type="button">Create label</button>}>
+                <DropdownMenuItem label="Bug" onClick={() => {}} />
+              </DropdownMenuSubMenu>
+            </>
+          }>
+          <div>Right-click me</div>
+        </ContextMenu>,
+      );
+      fireEvent.contextMenu(screen.getByText('Right-click me'));
+      const row = screen.getByRole('menuitem', {name: /Labels/, hidden: true});
+      // No region can sit outside this menu, so none renders inside it.
+      expect(row).toHaveAttribute('aria-haspopup', 'menu');
+      fireEvent.click(row, {detail: 1});
+      await waitFor(() => expect(row).toHaveAttribute('aria-expanded', 'true'));
+      expect(screen.queryByRole('dialog', {hidden: true})).toBeNull();
+      expect(
+        screen.queryByRole('textbox', {name: 'Filter labels', hidden: true}),
+      ).toBeNull();
+      expect(
+        screen.getByRole('menuitem', {name: 'Bug', hidden: true}),
+      ).toBeInTheDocument();
+      expect(warn).toHaveBeenCalledWith(
+        expect.stringContaining('DropdownMenuSubMenu: header and footer'),
+      );
+    } finally {
+      warn.mockRestore();
+    }
+  });
+
   it('renders menuContent as menu items', () => {
     render(
       <ContextMenu