@astryxdesign/core 0.1.6 → 0.1.7-canary.04cd8f7

package/src/DropdownMenu/DropdownMenuRadioGroup.tsx

@@ -0,0 +1,119 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file DropdownMenuRadioGroup.tsx
+ * @output DropdownMenuRadioGroup — a single-select group of menu items.
+ * @position Sub-component; wraps DropdownMenuRadioItem inside a DropdownMenu.
+ *
+ * Owns single-selection state (value/onChange) for its child
+ * DropdownMenuRadioItems and exposes it via context. Renders role="group" with
+ * an accessible name so the radios are announced as a set. Keyboard navigation
+ * comes from the parent DropdownMenu's useListFocus, which matches
+ * menuitemradio rows.
+ */
+
+import {useMemo, type ReactNode} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import {spacingVars} from '../theme/tokens.stylex';
+import {mergeProps} from '../utils';
+import type {BaseProps} from '../BaseProps';
+import {
+  DropdownMenuRadioGroupContext,
+  type DropdownMenuRadioGroupContextValue,
+} from './DropdownMenuContext';
+
+const styles = stylex.create({
+  // Match the menu's own inter-item rhythm (2px) so grouped radio items keep
+  // the same gap as ungrouped items instead of sitting flush against each
+  // other inside the role="group" wrapper.
+  group: {
+    display: 'flex',
+    flexDirection: 'column',
+    gap: spacingVars['--spacing-0-5'],
+  },
+});
+
+export interface DropdownMenuRadioGroupProps extends Omit<
+  BaseProps,
+  'onChange'
+> {
+  /**
+   * The currently selected value in the group. Pass `undefined` when nothing
+   * is selected yet.
+   */
+  value: string | undefined;
+  /**
+   * Callback fired when the selected value changes.
+   */
+  onChange: (value: string) => void;
+  /**
+   * Accessible label for the group. Required (together with `aria-labelledby`,
+   * one of the two) so screen readers announce the radios as a named set,
+   * e.g. "Sort by".
+   */
+  'aria-label'?: string;
+  /**
+   * The id of an element that labels the group, as an alternative to
+   * `aria-label`.
+   */
+  'aria-labelledby'?: string;
+  /**
+   * Whether selecting a value closes the menu. Radio items default to closing
+   * on selection (a single-choice commit), unlike checkbox items which stay
+   * open.
+   * @default true
+   */
+  hasCloseOnSelect?: boolean;
+  /**
+   * The `DropdownMenuRadioItem`s that make up the group.
+   */
+  children: ReactNode;
+}
+
+/**
+ * A single-select group of radio menu items (role="group" of menuitemradio).
+ *
+ * @example
+ * ```
+ *  * import {
+ *   DropdownMenuRadioGroup,
+ *   DropdownMenuRadioItem,
+ * } from '@astryxdesign/core/DropdownMenu';
+ *
+ * <DropdownMenu button={{label: 'Sort'}}>
+ *   <DropdownMenuRadioGroup value={sort} onChange={setSort} aria-label="Sort by">
+ *     <DropdownMenuRadioItem value="newest" label="Newest" />
+ *     <DropdownMenuRadioItem value="oldest" label="Oldest" />
+ *   </DropdownMenuRadioGroup>
+ * </DropdownMenu>
+ * ```
+ */
+export function DropdownMenuRadioGroup({
+  value,
+  onChange,
+  hasCloseOnSelect = true,
+  children,
+  className,
+  style,
+  ...rest
+}: DropdownMenuRadioGroupProps) {
+  const contextValue = useMemo<DropdownMenuRadioGroupContextValue>(
+    () => ({value, onChange, hasCloseOnSelect}),
+    [value, onChange, hasCloseOnSelect],
+  );
+
+  return (
+    <div
+      {...rest}
+      role="group"
+      {...mergeProps(stylex.props(styles.group), {className, style})}>
+      <DropdownMenuRadioGroupContext value={contextValue}>
+        {children}
+      </DropdownMenuRadioGroupContext>
+    </div>
+  );
+}
+
+DropdownMenuRadioGroup.displayName = 'DropdownMenuRadioGroup';

package/src/DropdownMenu/DropdownMenuRadioItem.doc.mjs

@@ -0,0 +1,80 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+  name: 'DropdownMenuRadioItem',
+  subComponentOf: 'DropdownMenu',
+  displayName: 'Dropdown Menu Radio Item',
+  isHiddenFromOverview: true,
+  description:
+    'A single option in a DropdownMenuRadioGroup (role="menuitemradio"). Must be used inside a DropdownMenuRadioGroup.',
+  props: [
+    {
+      name: 'value',
+      type: 'string',
+      description:
+        "The value this item represents within its group. The group's value matches against this to determine the checked state.",
+    },
+    {
+      name: 'label',
+      type: 'ReactNode',
+      description: 'Primary label text identifying the option.',
+    },
+    {
+      name: 'description',
+      type: 'ReactNode',
+      description: 'Secondary description text displayed below the label.',
+    },
+    {
+      name: 'icon',
+      type: 'IconType',
+      description:
+        'Icon to display before the label. See `npx astryx docs icons` for valid semantic names.',
+    },
+    {
+      name: 'isDisabled',
+      type: 'boolean',
+      default: 'false',
+      description:
+        'Whether this individual radio item is disabled. Disabled items stay focusable (via aria-disabled) so they remain discoverable by keyboard and assistive technology, but selection is blocked.',
+    },
+    {
+      name: 'endContent',
+      type: 'ReactNode',
+      description:
+        'Content to render after the label and description, such as a badge or metadata.',
+    },
+  ],
+};
+
+export const docsZh = {
+  name: 'DropdownMenuRadioItem',
+  isHiddenFromOverview: true,
+  displayName: 'Dropdown Menu Radio Item',
+  description:
+    'DropdownMenuRadioGroup 中的单个选项（role="menuitemradio"）。必须在 DropdownMenuRadioGroup 内使用。',
+  propDescriptions: {
+    value: '该项在组内代表的值。组的 value 与之匹配以确定勾选状态。',
+    label: '标识该选项的主标签文本。',
+    description: '显示在标签下方的次要描述文本。',
+    icon: '显示在标签前的图标。',
+    isDisabled: '该单选项是否禁用。',
+    endContent: '在标签和描述之后渲染的内容。',
+  },
+};
+
+export const docsDense = {
+  name: 'DropdownMenuRadioItem',
+  isHiddenFromOverview: true,
+  displayName: 'Dropdown Menu Radio Item',
+  description: 'one option in a DropdownMenuRadioGroup (menuitemradio)',
+  propDescriptions: {
+    value: "item's value within the group (matched vs group value)",
+    label: 'primary label text',
+    description: 'secondary text below label',
+    icon: 'icon before label',
+    isDisabled: 'disabled; stays focusable via aria-disabled',
+    endContent: 'content after label+description',
+  },
+};

package/src/DropdownMenu/DropdownMenuRadioItem.tsx

@@ -0,0 +1,232 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file DropdownMenuRadioItem.tsx
+ * @input React, stylex, Item + Icon + DropdownMenu context + tokens from core
+ * @output DropdownMenuRadioItem — a single option in a radio group.
+ * @position Sub-component; must be used inside a DropdownMenuRadioGroup.
+ *
+ * A menu item representing one option in a single-select group
+ * (role="menuitemradio"). The row owns the role and aria-checked; there is no
+ * nested native <input> (per the WAI-ARIA menuitemradio pattern). Selection
+ * state + onChange come from DropdownMenuRadioGroupContext. Keyboard nav +
+ * Enter/Space activation come from the parent DropdownMenu.
+ *
+ * The round radio visual (circle + center dot) is decorative (aria-hidden) —
+ * the row owns the checked state. Its size is derived from the menu's item size
+ * and it swaps to the inline-end of the row on coarse-pointer (touch) devices
+ * via CSS `order`. The dot is a shaped element, not an icon (a filled circle
+ * has no registry glyph).
+ */
+
+import {useCallback, type ReactNode} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import {renderIconSlot, type IconType} from '../Icon';
+import {Item} from '../Item';
+import {useDropdownMenuContext} from './DropdownMenuContext';
+import {
+  colorVars,
+  spacingVars,
+  durationVars,
+  easeVars,
+  borderVars,
+} from '../theme/tokens.stylex';
+import {mergeProps, themeProps} from '../utils';
+import type {BaseProps} from '../BaseProps';
+import {useDropdownMenuRadioGroupContext} from './DropdownMenuContext';
+
+const styles = stylex.create({
+  root: {
+    width: '100%',
+    borderRadius: `max(0px, calc(var(--_dropdown-menu-radius, ${spacingVars['--spacing-2']}) - var(--_dropdown-menu-padding, ${spacingVars['--spacing-1']})))`,
+    color: colorVars['--color-text-primary'],
+    backgroundColor: {
+      default: 'transparent',
+      ':focus': colorVars['--color-overlay-hover'],
+      ':hover': colorVars['--color-overlay-hover'],
+    },
+    cursor: 'pointer',
+    outline: 'none',
+  },
+  disabled: {
+    opacity: 0.5,
+    cursor: 'not-allowed',
+  },
+  // Rendered in Item's `marker` slot as a raw flex child. On touch it moves to
+  // the inline-end of the row via `order`.
+  circle: {
+    display: 'flex',
+    alignItems: 'center',
+    justifyContent: 'center',
+    flexShrink: 0,
+    boxSizing: 'border-box',
+    borderWidth: borderVars['--border-width'],
+    borderStyle: 'solid',
+    borderRadius: '50%',
+    transitionProperty: 'background-color, border-color',
+    transitionDuration: {
+      default: durationVars['--duration-fast'],
+      '@media (prefers-reduced-motion: reduce)': '0s',
+    },
+    transitionTimingFunction: easeVars['--ease-standard'],
+    order: {
+      default: 0,
+      '@media (pointer: coarse)': 1,
+    },
+    marginInlineStart: {
+      default: 0,
+      '@media (pointer: coarse)': 'auto',
+    },
+  },
+  unchecked: {
+    borderColor: colorVars['--color-border-emphasized'],
+    backgroundColor: colorVars['--color-background-surface'],
+  },
+  checked: {
+    borderColor: colorVars['--color-accent'],
+    backgroundColor: colorVars['--color-accent'],
+  },
+  dot: {
+    borderRadius: '50%',
+    backgroundColor: colorVars['--color-on-accent'],
+  },
+});
+
+const circleSizeStyles = stylex.create({
+  sm: {width: 18, height: 18},
+  md: {width: 22, height: 22},
+});
+
+const dotSizeStyles = stylex.create({
+  sm: {width: 6, height: 6},
+  md: {width: 8, height: 8},
+});
+
+export interface DropdownMenuRadioItemProps extends Omit<
+  BaseProps,
+  'role' | 'aria-checked' | 'tabIndex'
+> {
+  /**
+   * The value this item represents within its group. The group's `value`
+   * matches against this to determine the checked state.
+   */
+  value: string;
+  /**
+   * Primary label text identifying the option.
+   */
+  label: ReactNode;
+  /**
+   * Secondary description text displayed below the label.
+   */
+  description?: ReactNode;
+  /**
+   * Icon to display before the label. Accepts a semantic icon name (see
+   * `npx astryx docs icons`) or a rendered node.
+   */
+  icon?: ReactNode | IconType;
+  /**
+   * Whether this individual radio item is disabled. Disabled items stay
+   * focusable (via `aria-disabled`) so they remain discoverable by keyboard
+   * and assistive technology, but selection is blocked.
+   * @default false
+   */
+  isDisabled?: boolean;
+  /**
+   * Content to render after the label and description, such as a badge or
+   * metadata.
+   */
+  endContent?: ReactNode;
+}
+
+/**
+ * A single option in a DropdownMenuRadioGroup (role="menuitemradio").
+ *
+ * @example
+ * ```
+ * <DropdownMenuRadioGroup value={sort} onChange={setSort} aria-label="Sort by">
+ *   <DropdownMenuRadioItem value="newest" label="Newest" />
+ *   <DropdownMenuRadioItem value="oldest" label="Oldest" icon="clock" />
+ * </DropdownMenuRadioGroup>
+ * ```
+ */
+export function DropdownMenuRadioItem({
+  value,
+  label,
+  description,
+  icon,
+  isDisabled = false,
+  endContent,
+  xstyle,
+  className,
+  style,
+  ...rest
+}: DropdownMenuRadioItemProps) {
+  const menuCtx = useDropdownMenuContext();
+  const groupCtx = useDropdownMenuRadioGroupContext();
+  if (!groupCtx) {
+    throw new Error(
+      'DropdownMenuRadioItem must be used within a DropdownMenuRadioGroup',
+    );
+  }
+  const menuSize = menuCtx?.menuSize ?? 'md';
+  const controlSize = menuSize === 'sm' ? 'sm' : 'md';
+  const isChecked = groupCtx.value === value;
+
+  const handleClick = useCallback(() => {
+    if (isDisabled) {
+      return;
+    }
+    groupCtx.onChange(value);
+    if (groupCtx.hasCloseOnSelect) {
+      menuCtx?.closeMenu();
+    }
+  }, [isDisabled, groupCtx, value, menuCtx]);
+
+  return (
+    <Item
+      {...rest}
+      role="menuitemradio"
+      aria-checked={isChecked}
+      tabIndex={isDisabled ? undefined : -1}
+      marker={
+        <span
+          aria-hidden="true"
+          {...mergeProps(
+            themeProps('dropdown-menu-radio', {
+              size: controlSize,
+              checked: isChecked ? 'checked' : null,
+              disabled: isDisabled ? 'disabled' : null,
+            }),
+            stylex.props(
+              styles.circle,
+              circleSizeStyles[controlSize],
+              isChecked ? styles.checked : styles.unchecked,
+            ),
+          )}>
+          {isChecked && (
+            <span {...stylex.props(styles.dot, dotSizeStyles[controlSize])} />
+          )}
+        </span>
+      }
+      startContent={
+        icon
+          ? renderIconSlot(icon, {size: 'sm', color: 'secondary'})
+          : undefined
+      }
+      label={label}
+      description={description}
+      endContent={endContent}
+      onClick={handleClick}
+      isDisabled={isDisabled}
+      xstyle={[styles.root, isDisabled && styles.disabled, xstyle]}
+      {...mergeProps(themeProps('dropdown-menu-item', {size: menuSize}), {
+        className,
+        style,
+      })}
+    />
+  );
+}
+
+DropdownMenuRadioItem.displayName = 'DropdownMenuRadioItem';

package/src/DropdownMenu/DropdownMenuSelectable.test.tsx

@@ -0,0 +1,163 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file DropdownMenuSelectable.test.tsx
+ * @input vitest, @testing-library/react, DropdownMenu + selectable items
+ * @output Unit tests for DropdownMenuCheckboxItem / RadioGroup / RadioItem (#3829)
+ */
+
+import {describe, it, expect, vi, beforeEach} from 'vitest';
+import {render, screen} from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import {DropdownMenu} from './DropdownMenu';
+import {DropdownMenuCheckboxItem} from './DropdownMenuCheckboxItem';
+import {DropdownMenuRadioGroup} from './DropdownMenuRadioGroup';
+import {DropdownMenuRadioItem} from './DropdownMenuRadioItem';
+
+beforeEach(() => {
+  HTMLElement.prototype.showPopover = vi.fn(function (this: HTMLElement) {
+    this.setAttribute('popover-open', '');
+    const event = new Event('toggle', {bubbles: false});
+    Object.defineProperty(event, 'newState', {value: 'open'});
+    this.dispatchEvent(event);
+  });
+  HTMLElement.prototype.hidePopover = vi.fn(function (this: HTMLElement) {
+    this.removeAttribute('popover-open');
+    const event = new Event('toggle', {bubbles: false});
+    Object.defineProperty(event, 'newState', {value: 'closed'});
+    this.dispatchEvent(event);
+  });
+  const originalMatches = HTMLElement.prototype.matches;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  (HTMLElement.prototype as any).matches = function (
+    selector: string,
+  ): boolean {
+    if (selector === ':popover-open') {
+      return this.hasAttribute('popover-open');
+    }
+    return originalMatches.call(this, selector);
+  };
+});
+
+describe('DropdownMenuCheckboxItem', () => {
+  it('renders role menuitemcheckbox and reflects checked state', async () => {
+    const user = userEvent.setup();
+    render(
+      <DropdownMenu button={{label: 'View'}}>
+        <DropdownMenuCheckboxItem label="Show archived" value={true} />
+      </DropdownMenu>,
+    );
+    await user.click(screen.getByRole('button', {name: /View/}));
+    expect(
+      screen.getByRole('menuitemcheckbox', {
+        name: /Show archived/,
+        hidden: true,
+      }),
+    ).toHaveAttribute('aria-checked', 'true');
+  });
+
+  it('calls onChange with the toggled value on click', async () => {
+    const user = userEvent.setup();
+    const onChangeSpy = vi.fn();
+    render(
+      <DropdownMenu button={{label: 'View'}}>
+        <DropdownMenuCheckboxItem
+          label="Show archived"
+          value={false}
+          onChange={onChangeSpy}
+        />
+      </DropdownMenu>,
+    );
+    await user.click(screen.getByRole('button', {name: /View/}));
+    await user.click(
+      screen.getByRole('menuitemcheckbox', {
+        name: /Show archived/,
+        hidden: true,
+      }),
+    );
+    expect(onChangeSpy).toHaveBeenCalledWith(true);
+  });
+
+  it('does not toggle when disabled', async () => {
+    const user = userEvent.setup();
+    const onChangeSpy = vi.fn();
+    render(
+      <DropdownMenu button={{label: 'View'}}>
+        <DropdownMenuCheckboxItem
+          label="Show archived"
+          value={false}
+          onChange={onChangeSpy}
+          isDisabled
+        />
+      </DropdownMenu>,
+    );
+    await user.click(screen.getByRole('button', {name: /View/}));
+    const item = screen.getByRole('menuitemcheckbox', {
+      name: /Show archived/,
+      hidden: true,
+    });
+    expect(item).toHaveAttribute('aria-disabled', 'true');
+    await user.click(item);
+    expect(onChangeSpy).not.toHaveBeenCalled();
+  });
+});
+
+describe('DropdownMenuRadioGroup / RadioItem', () => {
+  it('renders a named group with radios reflecting the selected value', async () => {
+    const user = userEvent.setup();
+    render(
+      <DropdownMenu button={{label: 'Sort'}}>
+        <DropdownMenuRadioGroup
+          value="newest"
+          onChange={() => {}}
+          aria-label="Sort by">
+          <DropdownMenuRadioItem value="newest" label="Newest" />
+          <DropdownMenuRadioItem value="oldest" label="Oldest" />
+        </DropdownMenuRadioGroup>
+      </DropdownMenu>,
+    );
+    await user.click(screen.getByRole('button', {name: /Sort/}));
+    expect(
+      screen.getByRole('menuitemradio', {name: 'Newest', hidden: true}),
+    ).toHaveAttribute('aria-checked', 'true');
+    expect(
+      screen.getByRole('menuitemradio', {name: 'Oldest', hidden: true}),
+    ).toHaveAttribute('aria-checked', 'false');
+    expect(
+      screen.getByRole('group', {name: 'Sort by', hidden: true}),
+    ).toBeInTheDocument();
+  });
+
+  it('calls onChange with the selected value', async () => {
+    const user = userEvent.setup();
+    const onChange = vi.fn();
+    render(
+      <DropdownMenu button={{label: 'Sort'}}>
+        <DropdownMenuRadioGroup
+          value="newest"
+          onChange={onChange}
+          aria-label="Sort by">
+          <DropdownMenuRadioItem value="newest" label="Newest" />
+          <DropdownMenuRadioItem value="oldest" label="Oldest" />
+        </DropdownMenuRadioGroup>
+      </DropdownMenu>,
+    );
+    await user.click(screen.getByRole('button', {name: /Sort/}));
+    await user.click(
+      screen.getByRole('menuitemradio', {name: 'Oldest', hidden: true}),
+    );
+    expect(onChange).toHaveBeenCalledWith('oldest');
+  });
+
+  it('throws when a radio item is used outside a group', () => {
+    const spy = vi.spyOn(console, 'error').mockImplementation(() => {});
+    expect(() =>
+      render(
+        <DropdownMenu button={{label: 'Sort'}}>
+          <DropdownMenuRadioItem value="x" label="X" />
+        </DropdownMenu>,
+      ),
+    ).toThrow(/DropdownMenuRadioGroup/);
+    spy.mockRestore();
+  });
+});

package/src/DropdownMenu/index.ts

@@ -18,7 +18,27 @@ export {
   type DropdownMenuOption,
 } from './DropdownMenu';
 
+export {DropdownMenuItem, type DropdownMenuItemProps} from './DropdownMenuItem';
+
+// Selectable items — checkbox (independent) and radio (single-select group).
+export {
+  DropdownMenuCheckboxItem,
+  type DropdownMenuCheckboxItemProps,
+} from './DropdownMenuCheckboxItem';
+export {
+  DropdownMenuRadioGroup,
+  type DropdownMenuRadioGroupProps,
+} from './DropdownMenuRadioGroup';
+export {
+  DropdownMenuRadioItem,
+  type DropdownMenuRadioItemProps,
+} from './DropdownMenuRadioItem';
+
+// Menu-coordination context — public so consumers can build custom menu items
+// that read the menu size / close the menu.
 export {
-  DropdownMenuItem,
-  type DropdownMenuItemProps,
-} from './DropdownMenuItem';
+  DropdownMenuContext,
+  useDropdownMenuContext,
+  type DropdownMenuContextValue,
+  type DropdownMenuSize,
+} from './DropdownMenuContext';

package/src/DropdownMenu/menuItemRoles.ts

@@ -0,0 +1,22 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file menuItemRoles.ts
+ * @output Shared menu-item role set + focus selector.
+ * @position Internal; used by DropdownMenu and ContextMenu so their
+ *   roving-focus, typeahead, and Enter/Space activation stay in sync.
+ *
+ * Includes the selectable items (menuitemradio/menuitemcheckbox) alongside
+ * plain menuitem so checkbox/radio rows are reachable by arrow keys, typeahead,
+ * and Enter/Space — not just role="menuitem".
+ */
+
+export const MENU_ITEM_ROLES: ReadonlySet<string> = new Set([
+  'menuitem',
+  'menuitemradio',
+  'menuitemcheckbox',
+]);
+
+export const MENU_ITEM_SELECTOR: string = [...MENU_ITEM_ROLES]
+  .map(role => `[role="${role}"]:not([aria-disabled="true"])`)
+  .join(',');

package/src/EmptyState/EmptyState.doc.mjs

@@ -39,7 +39,7 @@ export const docs = {
       name: 'headingLevel',
       type: '1 | 2 | 3 | 4 | 5 | 6',
       description:
-        'Controls the rendered HTML heading tag (h1-h6) to fit the document outline.',
+        'Controls only the rendered HTML heading tag (h1-h6) so the title fits the document outline. This is a semantic change for accessibility and does not change the visual size of the title, which stays fixed regardless of level.',
       default: '3',
     },
     {
@@ -121,7 +121,7 @@ export const docsZh = {
       name: 'headingLevel',
       type: '1 | 2 | 3 | 4 | 5 | 6',
       description:
-        '控制渲染的 HTML 标题标签（h1-h6），以适配文档大纲。',
+        '仅控制渲染的 HTML 标题标签（h1-h6），使标题适配文档大纲。这是用于无障碍的语义变化，不会改变标题的视觉大小，标题大小始终固定，与级别无关。',
       default: '3',
     },
     {
@@ -173,7 +173,7 @@ export const docsDense = {
   },
   propDescriptions: {
     title: 'Primary msg rendered as heading (h1-h6) inside empty state.',
-    headingLevel: 'Controls HTML heading tag (h1-h6) for document outline.',
+    headingLevel: 'Controls only HTML heading tag (h1-h6) for document outline; does not change visual title size.',
     description: 'Optional secondary text w/ additional context below title.',
     icon: 'Optional icon/illustration above title; rendered decorative (aria-hidden="true").',
     actions: 'Optional action buttons below description; horizontal by default, vertical when isCompact.',

package/src/EmptyState/EmptyState.tsx

@@ -105,7 +105,10 @@ export interface EmptyStateProps extends BaseProps<HTMLDivElement> {
   actions?: ReactNode;
   /**
    * Semantic heading level for the title element.
-   * Controls the rendered HTML tag (h1–h6) to fit the document outline.
+   * Controls only the rendered HTML tag (h1–h6) so the title fits the
+   * document outline. This is a semantic change for accessibility and does
+   * not change the visual size of the title, which stays fixed regardless
+   * of level.
    * @default 3
    */
   headingLevel?: 1 | 2 | 3 | 4 | 5 | 6;