@astryxdesign/core 0.1.8 → 0.1.9-canary.02ef052

package/src/DateTimeInput/DateTimeInput.test.tsx

@@ -15,6 +15,8 @@ import userEvent from '@testing-library/user-event';
 import {getButton, queryButton} from '../__tests__/fastRoleQueries';
 import {DateTimeInput} from './DateTimeInput';
 import type {ISODateTimeString} from './DateTimeInput';
+import {defineTheme} from '../theme/defineTheme';
+import {generateThemeCSSFlat} from '../theme/generateThemeRules';
 
 describe('DateTimeInput', () => {
   it('renders with label', () => {
@@ -185,6 +187,41 @@ describe('DateTimeInput', () => {
     );
   });
 
+  it('opens the calendar popover on ArrowDown (keyboard, forms-13)', () => {
+    render(<DateTimeInput label="Meeting" onChange={() => {}} />);
+    const input = screen.getByRole('combobox');
+    input.focus();
+    expect(input).toHaveAttribute('aria-expanded', 'false');
+    fireEvent.keyDown(input, {key: 'ArrowDown'});
+    expect(input).toHaveAttribute('aria-expanded', 'true');
+    // skipAutoFocus keeps focus in the input, per the APG date-picker pattern
+    expect(input).toHaveFocus();
+  });
+
+  it('opens the calendar popover on Alt+ArrowDown (keyboard, forms-13)', () => {
+    render(<DateTimeInput label="Meeting" onChange={() => {}} />);
+    const input = screen.getByRole('combobox');
+    fireEvent.keyDown(input, {key: 'ArrowDown', altKey: true});
+    expect(input).toHaveAttribute('aria-expanded', 'true');
+  });
+
+  it('does not open on ArrowDown when disabled', () => {
+    render(<DateTimeInput label="Meeting" isDisabled onChange={() => {}} />);
+    const input = screen.getByRole('combobox');
+    fireEvent.keyDown(input, {key: 'ArrowDown'});
+    expect(input).toHaveAttribute('aria-expanded', 'false');
+  });
+
+  it('does not re-trigger on ArrowDown when the calendar is already open', () => {
+    render(<DateTimeInput label="Meeting" onChange={() => {}} />);
+    const input = screen.getByRole('combobox');
+    fireEvent.keyDown(input, {key: 'ArrowDown'});
+    expect(input).toHaveAttribute('aria-expanded', 'true');
+    // A second ArrowDown is a no-op: the calendar stays open
+    fireEvent.keyDown(input, {key: 'ArrowDown'});
+    expect(input).toHaveAttribute('aria-expanded', 'true');
+  });
+
   it('calendar button is focusable and clickable', () => {
     render(<DateTimeInput label="Meeting" onChange={() => {}} />);
     const button = getButton('Open calendar');
@@ -779,4 +816,114 @@ describe('DateTimeInput', () => {
       expect(onChange.mock.calls[0][0]).toContain('14:31');
     });
   });
+  // ===========================================================================
+  // Segment theme targets (#4075)
+  // ===========================================================================
+
+  describe('segment theme targets', () => {
+    // The root only publishes `astryx-date-time-input`; the date and time
+    // wrappers were anonymous nodes carrying hashed atomic classes only, so a
+    // theme that restyles input geometry through the text-input/date-input/
+    // time-input targets could not reach them and DateTimeInput rendered
+    // shorter than every other input under that theme.
+
+    it('renders the date segment target on the date wrapper', () => {
+      render(<DateTimeInput label="Meeting" onChange={() => {}} />);
+      const wrapper = screen
+        .getByLabelText('Meeting')
+        .closest('.astryx-date-time-input-date-segment');
+
+      expect(wrapper).not.toBeNull();
+      // The wrapper is the input's own container, not an ancestor further up.
+      expect(wrapper).toBe(screen.getByLabelText('Meeting').parentElement);
+    });
+
+    it('renders the time segment target on the time wrapper', () => {
+      render(<DateTimeInput label="Meeting" onChange={() => {}} />);
+      const wrapper = screen
+        .getByLabelText('Meeting time')
+        .closest('.astryx-date-time-input-time-segment');
+
+      expect(wrapper).not.toBeNull();
+      expect(wrapper).toBe(screen.getByLabelText('Meeting time').parentElement);
+    });
+
+    it('reflects size on both segments so themes can restyle geometry', () => {
+      render(<DateTimeInput label="Meeting" size="lg" onChange={() => {}} />);
+
+      const date = screen
+        .getByLabelText('Meeting')
+        .closest('.astryx-date-time-input-date-segment');
+      const time = screen
+        .getByLabelText('Meeting time')
+        .closest('.astryx-date-time-input-time-segment');
+
+      expect(date).toHaveAttribute('data-size', 'lg');
+      expect(date).toHaveClass('lg');
+      expect(time).toHaveAttribute('data-size', 'lg');
+      expect(time).toHaveClass('lg');
+    });
+
+    it('reflects status on both segments, mirroring the root', () => {
+      render(
+        <DateTimeInput
+          label="Meeting"
+          status={{type: 'error', message: 'Required'}}
+          onChange={() => {}}
+        />,
+      );
+
+      const date = screen
+        .getByLabelText('Meeting')
+        .closest('.astryx-date-time-input-date-segment');
+      const time = screen
+        .getByLabelText('Meeting time')
+        .closest('.astryx-date-time-input-time-segment');
+
+      expect(date).toHaveAttribute('data-status', 'error');
+      expect(time).toHaveAttribute('data-status', 'error');
+    });
+
+    it('omits data-status when there is no status, like the root does', () => {
+      render(<DateTimeInput label="Meeting" onChange={() => {}} />);
+
+      const date = screen
+        .getByLabelText('Meeting')
+        .closest('.astryx-date-time-input-date-segment');
+
+      expect(date).not.toHaveAttribute('data-status');
+    });
+
+    it('keeps the root target intact', () => {
+      const {container} = render(
+        <DateTimeInput label="Meeting" onChange={() => {}} />,
+      );
+      // Additive change — the existing root target still renders.
+      expect(container.querySelector('.astryx-date-time-input')).not.toBeNull();
+    });
+
+    it('exposes both segments as themeable defineTheme targets', () => {
+      // jsdom cannot resolve the @layer cascade, so the generated CSS is what
+      // proves a theme can actually reach these nodes.
+      const theme = defineTheme({
+        name: 'date-time-input-segments-test',
+        components: {
+          'date-time-input-date-segment': {
+            base: {blockSize: 'var(--size-element-lg)'},
+            lg: {paddingInline: 'var(--spacing-4)'},
+          },
+          'date-time-input-time-segment': {
+            base: {blockSize: 'var(--size-element-lg)'},
+          },
+        },
+      });
+      const css = generateThemeCSSFlat(theme);
+
+      expect(css).toContain('.astryx-date-time-input-date-segment {');
+      expect(css).toContain('.astryx-date-time-input-date-segment.lg');
+      expect(css).toContain('.astryx-date-time-input-time-segment {');
+      expect(css).toContain('block-size: var(--size-element-lg)');
+      expect(css).toContain('padding-inline: var(--spacing-4)');
+    });
+  });
 });

package/src/DateTimeInput/DateTimeInput.tsx

@@ -27,7 +27,6 @@ import {
   type KeyboardEvent,
 } from 'react';
 import * as stylex from '@stylexjs/stylex';
-import type {IconName} from '../Icon';
 import {
   colorVars,
   sizeVars,
@@ -40,7 +39,6 @@ import {
 import {
   Field,
   type InputStatus,
-  type InputStatusType,
   inputWrapperStyles,
   inputStatusBorderStyles,
   inputStatusHoverShadowStyles,
@@ -54,6 +52,7 @@ import {useCalendarConstraints} from '../Calendar/hooks';
 import {usePopover} from '../Popover';
 import {useTooltip} from '../Tooltip';
 import {useInputContainer} from '../hooks/useInputContainer';
+import {useInputStatusIcon} from '../hooks/useInputStatusIcon';
 import {
   type ISOTimeString,
   parseDateInput,
@@ -470,25 +469,21 @@ export function DateTimeInput({
     isEnabled: showsDisabledMessage,
   });
 
-  const statusIconMap: Record<InputStatusType, IconName> = {
-    warning: 'warning',
-    error: 'error',
-    success: 'success',
-  };
-
-  const statusIconColorMap: Record<
-    InputStatusType,
-    'warning' | 'error' | 'success'
-  > = {
-    warning: 'warning',
-    error: 'error',
-    success: 'success',
-  };
+  // DateTimeInput fixes its status presentation to the detached message box,
+  // so the shared helper suppresses the on-field icon (the message box carries
+  // its own leading glyph). Routed through the helper for consistency with the
+  // rest of the bordered input family.
+  const {statusIcon, describedBy: statusTooltipDescribedBy} =
+    useInputStatusIcon({
+      status,
+      statusVariant: 'detached',
+    });
 
   const ariaDescribedBy =
     [
       description ? descriptionID : null,
       status?.message ? statusMessageID : null,
+      statusTooltipDescribedBy,
       showsDisabledMessage ? disabledMessageTooltip.describedBy : null,
     ]
       .filter(Boolean)
@@ -719,12 +714,22 @@ export function DateTimeInput({
       if (e.key === 'Escape' && popover.isOpen) {
         e.preventDefault();
         popover.hide();
+      } else if (
+        (e.key === 'ArrowDown' || (e.altKey && e.key === 'ArrowDown')) &&
+        !popover.isOpen
+      ) {
+        // APG combobox: ArrowDown (and Alt+ArrowDown) opens the calendar
+        // popover from the keyboard, keeping focus in the input (forms-13).
+        e.preventDefault();
+        if (!isEffectivelyDisabled) {
+          popover.show({skipAutoFocus: true});
+        }
       } else if (e.key === 'Enter') {
         e.preventDefault();
         commitDatePendingInput();
       }
     },
-    [popover, commitDatePendingInput],
+    [popover, commitDatePendingInput, isEffectivelyDisabled],
   );
 
   // --- Time handlers ---
@@ -880,14 +885,22 @@ export function DateTimeInput({
         {/* Date input */}
         <div
           ref={popover.triggerRef}
-          {...stylex.props(
-            inputWrapperStyles.base,
-            sizeStyles[size],
-            styles.dateWrapper,
-            isEffectivelyDisabled && inputWrapperStyles.disabled,
-            status && inputStatusBorderStyles[status.type],
-            status && inputStatusHoverShadowStyles[status.type],
-            status && inputStatusFocusWithinStyles[status.type],
+          {...mergeProps(
+            themeProps('date-time-input-date-segment', {
+              size,
+              status: status?.type ?? null,
+            }),
+            stylex.props(
+              inputWrapperStyles.base,
+              sizeStyles[size],
+              styles.dateWrapper,
+              isEffectivelyDisabled && inputWrapperStyles.disabled,
+              status && inputStatusBorderStyles[status.type],
+              status &&
+                !isEffectivelyDisabled &&
+                inputStatusHoverShadowStyles[status.type],
+              status && inputStatusFocusWithinStyles[status.type],
+            ),
           )}>
           <button
             type="button"
@@ -958,13 +971,7 @@ export function DateTimeInput({
             </button>
           )}
           {isBusy && <Spinner size="sm" />}
-          {status && (
-            <Icon
-              icon={statusIconMap[status.type]}
-              size="md"
-              color={statusIconColorMap[status.type]}
-            />
-          )}
+          {statusIcon}
         </div>
 
         {/* Time input */}
@@ -972,14 +979,22 @@ export function DateTimeInput({
           ref={timeContainerRef}
           onClick={handleTimeWrapperClick}
           onMouseUp={handleTimeWrapperMouseUp}
-          {...stylex.props(
-            inputWrapperStyles.base,
-            sizeStyles[size],
-            styles.timeWrapper,
-            isEffectivelyDisabled && inputWrapperStyles.disabled,
-            status && inputStatusBorderStyles[status.type],
-            status && inputStatusHoverShadowStyles[status.type],
-            status && inputStatusFocusWithinStyles[status.type],
+          {...mergeProps(
+            themeProps('date-time-input-time-segment', {
+              size,
+              status: status?.type ?? null,
+            }),
+            stylex.props(
+              inputWrapperStyles.base,
+              sizeStyles[size],
+              styles.timeWrapper,
+              isEffectivelyDisabled && inputWrapperStyles.disabled,
+              status && inputStatusBorderStyles[status.type],
+              status &&
+                !isEffectivelyDisabled &&
+                inputStatusHoverShadowStyles[status.type],
+              status && inputStatusFocusWithinStyles[status.type],
+            ),
           )}>
           <div {...stylex.props(styles.icon)}>
             <Icon icon="clock" size="sm" color="secondary" />
@@ -1000,7 +1015,9 @@ export function DateTimeInput({
             disabled={isEffectivelyDisabled && !showsDisabledMessage}
             aria-disabled={showsDisabledMessage ? 'true' : undefined}
             readOnly={showsDisabledMessage || undefined}
-            aria-label={timeLabel ?? t('@astryx.dateTimeInput.timeSuffix', {label})}
+            aria-label={
+              timeLabel ?? t('@astryx.dateTimeInput.timeSuffix', {label})
+            }
             aria-describedby={ariaDescribedBy}
             aria-required={isRequired === true ? 'true' : undefined}
             aria-invalid={

package/src/Dialog/Dialog.doc.mjs

@@ -111,7 +111,7 @@ export const docs = {
       { guidance: false, description: 'Use the fullscreen variant for simple confirmations; it is meant for complex content like editors or long forms.' },
     ],
     anatomy: [
-      {name: 'Header', required: true, description: 'Title, optional subtitle, and close button. The title receives focus on open for accessibility.'},
+      {name: 'Header', required: true, description: 'Title, optional subtitle, and close button. The title receives focus on open and labels the dialog via aria-labelledby.'},
       {name: 'Body', required: true, description: 'The main content area: text, forms, lists, or any layout.'},
       {name: 'Footer', required: false, description: 'Action buttons like Save/Cancel or Accept/Decline, aligned to the end.'},
       {name: 'Backdrop', required: true, description: 'Semi-transparent overlay behind the dialog that blocks page interaction.'},
@@ -133,7 +133,7 @@ export const docsZh = {
       { guidance: false, description: 'Use the fullscreen variant for simple confirmations; it is meant for complex content like editors or long forms.' },
     ],
     anatomy: [
-      {name: 'Header', required: true, description: 'Title, optional subtitle, and close button. The title receives focus on open for accessibility.'},
+      {name: 'Header', required: true, description: 'Title, optional subtitle, and close button. The title receives focus on open and labels the dialog via aria-labelledby.'},
       {name: 'Body', required: true, description: 'The main content area: text, forms, lists, or any layout.'},
       {name: 'Footer', required: false, description: 'Action buttons like Save/Cancel or Accept/Decline, aligned to the end.'},
       {name: 'Backdrop', required: true, description: 'Semi-transparent overlay behind the dialog that blocks page interaction.'},

package/src/Dialog/Dialog.test.tsx

@@ -212,10 +212,7 @@ describe('Dialog', () => {
 
   it('forwards additional props to dialog element', () => {
     render(
-      <Dialog
-        isOpen={true}
-        onOpenChange={() => {}}
-        data-testid="custom-dialog">
+      <Dialog isOpen={true} onOpenChange={() => {}} data-testid="custom-dialog">
         Content
       </Dialog>,
     );
@@ -267,6 +264,82 @@ describe('Dialog', () => {
     });
   });
 
+  describe('accessible name', () => {
+    it('is labelled by the DialogHeader title by default', () => {
+      render(
+        <Dialog isOpen={true} onOpenChange={() => {}}>
+          <DialogHeader title="Dialog title" />
+        </Dialog>,
+      );
+      const dialog = screen.getByRole('dialog');
+      const heading = screen.getByRole('heading', {name: 'Dialog title'});
+      expect(heading.id).not.toBe('');
+      expect(dialog).toHaveAttribute('aria-labelledby', heading.id);
+      expect(dialog).toHaveAccessibleName('Dialog title');
+    });
+
+    it('prefers a consumer-provided aria-label over the header title', () => {
+      render(
+        <Dialog isOpen={true} onOpenChange={() => {}} aria-label="Custom name">
+          <DialogHeader title="Dialog title" />
+        </Dialog>,
+      );
+      const dialog = screen.getByRole('dialog');
+      expect(dialog).not.toHaveAttribute('aria-labelledby');
+      expect(dialog).toHaveAccessibleName('Custom name');
+    });
+
+    it('prefers a consumer-provided aria-labelledby over the header title', () => {
+      render(
+        <>
+          <span id="external-label">External name</span>
+          <Dialog
+            isOpen={true}
+            onOpenChange={() => {}}
+            aria-labelledby="external-label">
+            <DialogHeader title="Dialog title" />
+          </Dialog>
+        </>,
+      );
+      const dialog = screen.getByRole('dialog');
+      expect(dialog).toHaveAttribute('aria-labelledby', 'external-label');
+      expect(dialog).toHaveAccessibleName('External name');
+    });
+
+    it('omits aria-labelledby and warns when open with no name source', () => {
+      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+      try {
+        render(
+          <Dialog isOpen={true} onOpenChange={() => {}}>
+            Content
+          </Dialog>,
+        );
+        const dialog = screen.getByRole('dialog');
+        expect(dialog).not.toHaveAttribute('aria-labelledby');
+        expect(warnSpy).toHaveBeenCalledTimes(1);
+        expect(warnSpy).toHaveBeenCalledWith(
+          expect.stringContaining('accessible name'),
+        );
+      } finally {
+        warnSpy.mockRestore();
+      }
+    });
+
+    it('does not warn when the header provides a title', () => {
+      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+      try {
+        render(
+          <Dialog isOpen={true} onOpenChange={() => {}}>
+            <DialogHeader title="Dialog title" />
+          </Dialog>,
+        );
+        expect(warnSpy).not.toHaveBeenCalled();
+      } finally {
+        warnSpy.mockRestore();
+      }
+    });
+  });
+
   describe('inner flex wrapper', () => {
     it('wraps children in a flex container for scroll support', () => {
       render(

package/src/Dialog/Dialog.tsx

@@ -16,7 +16,14 @@
  * - /packages/cli/templates/blocks/components/Dialog/ (showcase blocks)
  */
 
-import {useEffect, useMemo, useRef, type ReactNode} from 'react';
+import {
+  useCallback,
+  useEffect,
+  useId,
+  useMemo,
+  useRef,
+  type ReactNode,
+} from 'react';
 import type {BaseProps} from '../BaseProps';
 import * as stylex from '@stylexjs/stylex';
 import {useScrollLock} from '../hooks/useScrollLock';
@@ -39,6 +46,7 @@ import {
 } from '../Layout/padding.stylex';
 import type {SpacingStep} from '../utils/types';
 import {mergeProps, mergeRefs} from '../utils';
+import {devWarn} from '../utils/devWarning';
 import {DialogContext} from './DialogContext';
 import {themeProps} from '../utils/themeProps';
 
@@ -152,7 +160,13 @@ const styles = stylex.create({
   open: {
     display: 'flex',
     opacity: 1,
-    animationName: enterDirectional,
+    // Disable the entry keyframe animation under
+    // `prefers-reduced-motion: reduce` so the dialog appears instantly
+    // instead of translating/scaling in (same pattern as layerAnimations).
+    animationName: {
+      default: enterDirectional,
+      '@media (prefers-reduced-motion: reduce)': 'none',
+    },
   },
   // Backdrop using ::backdrop pseudo-element
   backdrop: {
@@ -312,6 +326,9 @@ export interface DialogProps extends BaseProps<HTMLDialogElement> {
  *
  * Designed to be used with Layout as its child for structured content.
  * Uses the browser's built-in modal behavior for optimal accessibility.
+ * When a DialogHeader is rendered inside, its title automatically names the
+ * dialog via aria-labelledby; pass `aria-label` or `aria-labelledby` to
+ * override.
  *
  * @example
  * ```
@@ -348,10 +365,47 @@ export function Dialog({
   const paddingToken = spacingStepToToken[effectivePadding] as SpacingToken;
 
   const isFullscreen = variant === 'fullscreen';
-  const dialogContextValue = useMemo(() => ({isInline}), [isInline]);
+
+  // Default accessible name: publish a title id through DialogContext so a
+  // DialogHeader applies it to its heading (mirrors AlertDialog's explicit
+  // useId wiring). Whether to emit the default aria-labelledby is decided
+  // imperatively in the callback ref below by checking whether the title
+  // element actually rendered — so a dialog with no header never points at a
+  // missing id, and we avoid the extra render a registration-via-state effect
+  // would cost at the dialog level.
+  const titleId = useId();
+
+  const dialogContextValue = useMemo(
+    () => ({isInline, titleId}),
+    [isInline, titleId],
+  );
+
+  // Consumer-provided labels always win over the DialogHeader default.
+  const hasConsumerName =
+    props['aria-label'] != null || props['aria-labelledby'] != null;
 
   const dialogRef = useRef<HTMLDialogElement>(null);
 
+  // Callback ref on the <dialog>: sync the default aria-labelledby from the
+  // DialogHeader title (if one rendered) in the same commit, with no second
+  // render. Consumer aria-label/aria-labelledby win — when present we leave
+  // the attribute to the {...safeProps} spread and never touch it here.
+  const attachDialog = useCallback(
+    (node: HTMLDialogElement | null) => {
+      dialogRef.current = node;
+      if (!node || hasConsumerName) {
+        return;
+      }
+      const hasTitle = node.querySelector(`#${CSS.escape(titleId)}`) != null;
+      if (hasTitle) {
+        node.setAttribute('aria-labelledby', titleId);
+      } else {
+        node.removeAttribute('aria-labelledby');
+      }
+    },
+    [titleId, hasConsumerName],
+  );
+
   // Capture the element that was focused when the dialog opened,
   // for directional animation origin and focus restoration on close.
   const triggerElementRef = useRef<HTMLElement | null>(null);
@@ -440,6 +494,29 @@ export function Dialog({
     return () => dialog.removeEventListener('keydown', handleKeyDown);
   }, [isOpen, isInline, allowEscape, onOpenChange]);
 
+  // Dev-time guardrail: an open modal should always have an accessible name.
+  // The header-title check reads the DOM, so this stays in an effect; the ref
+  // keeps it to one warning per component instance.
+  const warnedUnnamedDialogRef = useRef(false);
+  useEffect(() => {
+    const hasHeaderTitle =
+      dialogRef.current?.querySelector(`#${CSS.escape(titleId)}`) != null;
+    if (
+      isOpen &&
+      !isInline &&
+      !hasConsumerName &&
+      !hasHeaderTitle &&
+      !warnedUnnamedDialogRef.current
+    ) {
+      warnedUnnamedDialogRef.current = true;
+      devWarn(
+        'Dialog',
+        'open dialog has no accessible name. Add a DialogHeader ' +
+          'with a `title`, or pass `aria-label`/`aria-labelledby`.',
+      );
+    }
+  }, [isOpen, isInline, hasConsumerName, titleId]);
+
   // Handle backdrop click — when the user clicks the ::backdrop pseudo-element,
   // the event target is the <dialog> element itself; clicks on child content
   // always target the child. This avoids false positives from native browser
@@ -531,7 +608,11 @@ export function Dialog({
           ),
           className,
           style,
-        )}>
+        )}
+        data-testid={
+          (props as Record<string, unknown>)['data-testid'] as
+            string | undefined
+        }>
         {innerContent}
       </div>
     );
@@ -541,7 +622,7 @@ export function Dialog({
 
   return (
     <dialog
-      ref={mergeRefs(ref, dialogRef)}
+      ref={mergeRefs(ref, attachDialog)}
       {...safeProps}
       {...mergeProps(
         themeProps('dialog', {variant}),
@@ -566,6 +647,9 @@ export function Dialog({
       onClick={handleClick}
       onCancel={handleCancel}
       aria-modal="true"
+      // The default aria-labelledby (from a DialogHeader title) is set
+      // imperatively in `attachDialog`; a consumer-provided aria-labelledby
+      // flows through {...safeProps} above and wins.
       {...(purpose === 'required' ? {role: 'alertdialog'} : undefined)}>
       {innerContent}
     </dialog>

package/src/Dialog/DialogContext.ts

@@ -5,8 +5,8 @@
 /**
  * @file DialogContext.ts
  * @input React context
- * @output Internal dialog context for child focus behavior
- * @position Dialog internals; consumed by focus-managing children
+ * @output Internal dialog context for child focus behavior and default labelling
+ * @position Dialog internals; consumed by focus-managing children and DialogHeader
  */
 
 import {createContext, use} from 'react';
@@ -14,6 +14,13 @@ import {createContext, use} from 'react';
 export interface DialogContextValue {
   /** Whether the dialog is rendered inline for docs/showcases. */
   isInline: boolean;
+  /**
+   * Id the DialogHeader title should render with so the dialog can name
+   * itself via aria-labelledby. The dialog detects the title element's
+   * presence directly (via a callback ref), so it only emits aria-labelledby
+   * when the title actually rendered — never pointing at a nonexistent id.
+   */
+  titleId?: string;
 }
 
 export const DialogContext = createContext<DialogContextValue | null>(null);

package/src/Dialog/DialogHeader.doc.mjs

@@ -12,7 +12,7 @@ export const docs = {
     {
       name: 'title',
       type: 'string',
-      description: 'Dialog title (receives focus on open).',
+      description: 'Dialog title (receives focus on open and labels the dialog via aria-labelledby).',
     },
     {
       name: 'subtitle',
@@ -158,7 +158,7 @@ export const docsDense = {
   displayName: 'Dialog Header',
   description: 'dialog header w/ title, optional subtitle, close button, start/end content slots',
   propDescriptions: {
-    title: 'dialog title (receives focus on open)',
+    title: 'dialog title (focused on open; labels dialog via aria-labelledby)',
     subtitle: 'subtitle below title',
     onOpenChange: 'close button callback (omit=no button)',
     startContent: 'content before title (e.g. back button)',