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

package/src/DateTimeInput/DateTimeInput.tsx

@@ -146,6 +146,18 @@ export type {
 const HORIZONTAL_SEGMENT_BASIS = 196;
 
 const styles = stylex.create({
+  // The shared disabled style drops the focus ring; restore it while a
+  // control inside the field holds focus (spec:AST-085 FR6). Defaults repeat it.
+  disabledFocusRing: {
+    borderColor: {
+      default: colorVars['--color-border-emphasized'],
+      ':focus-within': colorVars['--color-accent'],
+    },
+    boxShadow: {
+      default: 'none',
+      ':focus-within': `inset 0px 0px 0px 2px ${colorVars['--color-accent-muted']}`,
+    },
+  },
   row: {
     display: 'flex',
     flexWrap: 'wrap',
@@ -332,12 +344,12 @@ export interface DateTimeInputProps extends Omit<
   /**
    * Explains why the input is disabled. When set together with
    * `isDisabled`, the input shows a tooltip with this text on hover and
-   * keyboard focus, and the date and time fields stay focusable (via
-   * `aria-disabled`) so the reason is discoverable by keyboard and assistive
-   * technology. Typing and calendar activation stay blocked.
+   * keyboard focus, and the date and time fields are described by it, so the
+   * reason is discoverable by keyboard and assistive technology. Typing and
+   * calendar activation stay blocked.
    *
-   * Use this instead of wrapping a disabled input in `Tooltip` — disabled
-   * controls don't emit the pointer events an external tooltip needs.
+   * Use this instead of wrapping a disabled input in `Tooltip`, so the
+   * reason is tied to the field.
    *
    * @example
    * ```
@@ -1032,7 +1044,7 @@ function PointerDateTimeField({
 
   const handleDateInputChange = useCallback(
     (e: React.ChangeEvent<HTMLInputElement>) => {
-      // With a disabledMessage the input drops `disabled` for focusability, so
+      // The input is never natively disabled (AST-085 FR1), so
       // guard value mutation explicitly (readOnly also blocks typing).
       if (isEffectivelyDisabled) {
         return;
@@ -1338,7 +1350,7 @@ function PointerDateTimeField({
   // --- Time handlers ---
   const handleTimeInputChange = useCallback(
     (e: React.ChangeEvent<HTMLInputElement>) => {
-      // With a disabledMessage the input drops `disabled` for focusability, so
+      // The input is never natively disabled (AST-085 FR1), so
       // guard value mutation explicitly (readOnly also blocks typing).
       if (isEffectivelyDisabled) {
         return;
@@ -1452,7 +1464,8 @@ function PointerDateTimeField({
       // window uses those same arrows to navigate candidates, so guard the
       // composing keydown (fires before compositionend) to avoid stealing them
       // mid-composition. See utils/ime.ts.
-      if (isImeKeyEvent(e.nativeEvent)) {
+      // A disabled or busy field steps nothing, so it announces nothing (FR2).
+      if (isImeKeyEvent(e.nativeEvent) || isEffectivelyDisabled) {
         return;
       }
 
@@ -1664,6 +1677,7 @@ function PointerDateTimeField({
               sizeStyles[size],
               styles.dateWrapper,
               isEffectivelyDisabled && inputWrapperStyles.disabled,
+              isEffectivelyDisabled && styles.disabledFocusRing,
               status && inputStatusBorderStyles[status.type],
               status &&
                 !isEffectivelyDisabled &&
@@ -1682,7 +1696,7 @@ function PointerDateTimeField({
               max={calendarMax}
               isDateDisabled={isDateDisabled}
               isEffectivelyDisabled={isEffectivelyDisabled}
-              hasDisabledMessage={showsDisabledMessage}
+              isFocusableDisabled
               isEffectivelyRequired={isEffectivelyRequired}
               isBusy={isBusy}
               statusType={status?.type}
@@ -1691,7 +1705,7 @@ function PointerDateTimeField({
                 ...controlProps,
                 'aria-labelledby': controlLabelledBy,
                 onBlur: onBlurProp,
-                onClick: onClickProp,
+                onClick: isEffectivelyDisabled ? undefined : onClickProp,
                 onKeyDown: onKeyDownProp,
               }}
             />
@@ -1700,7 +1714,13 @@ function PointerDateTimeField({
               <button
                 type="button"
                 onClick={handleCalendarToggle}
-                disabled={isEffectivelyDisabled}
+                aria-disabled={isEffectivelyDisabled || undefined}
+                // A tab stop while disabled too, so it carries the reason (FR5).
+                aria-describedby={
+                  showsDisabledMessage
+                    ? disabledMessageTooltip.describedBy
+                    : undefined
+                }
                 aria-label={
                   popover.isOpen
                     ? t('@astryx.dateInput.toggleCalendarClose')
@@ -1735,17 +1755,16 @@ function PointerDateTimeField({
                 value={dateDisplayValue}
                 onChange={handleDateInputChange}
                 onBlur={chainEventHandlers(handleDateBlur, onBlurProp)}
-                onClick={chainEventHandlers(handleDateInputClick, onClickProp)}
+                onClick={
+                  isEffectivelyDisabled
+                    ? undefined
+                    : chainEventHandlers(handleDateInputClick, onClickProp)
+                }
                 onKeyDown={chainEventHandlers(handleDateKeyDown, onKeyDownProp)}
                 aria-labelledby={controlLabelledBy}
                 placeholder={placeholder}
-                // With a disabledMessage the input keeps focusability via
-                // aria-disabled so the reason is focus-discoverable; typing is
-                // blocked with readOnly and the mutation guards, and calendar
-                // activation is blocked by the isEffectivelyDisabled guards.
-                disabled={isEffectivelyDisabled && !showsDisabledMessage}
-                aria-disabled={showsDisabledMessage ? 'true' : undefined}
-                readOnly={showsDisabledMessage || undefined}
+                aria-disabled={isEffectivelyDisabled ? 'true' : undefined}
+                readOnly={isEffectivelyDisabled || undefined}
                 aria-describedby={ariaDescribedBy}
                 aria-required={isEffectivelyRequired ? 'true' : undefined}
                 aria-invalid={
@@ -1807,6 +1826,7 @@ function PointerDateTimeField({
               sizeStyles[size],
               styles.timeWrapper,
               isEffectivelyDisabled && inputWrapperStyles.disabled,
+              isEffectivelyDisabled && styles.disabledFocusRing,
               status && inputStatusBorderStyles[status.type],
               status &&
                 !isEffectivelyDisabled &&
@@ -1830,7 +1850,7 @@ function PointerDateTimeField({
               max={timeMax}
               hourFormat={hourFormat}
               isEffectivelyDisabled={isEffectivelyDisabled}
-              hasDisabledMessage={showsDisabledMessage}
+              isFocusableDisabled
               isEffectivelyRequired={isEffectivelyRequired}
               isBusy={isBusy}
               statusType={status?.type}
@@ -1882,12 +1902,8 @@ function PointerDateTimeField({
                     ? timeOptionId(activeTimeIndex)
                     : undefined
                 }
-                // With a disabledMessage the input keeps focusability via
-                // aria-disabled so the reason is focus-discoverable; typing is
-                // blocked with readOnly and the mutation guards.
-                disabled={isEffectivelyDisabled && !showsDisabledMessage}
-                aria-disabled={showsDisabledMessage ? 'true' : undefined}
-                readOnly={showsDisabledMessage || undefined}
+                aria-disabled={isEffectivelyDisabled ? 'true' : undefined}
+                readOnly={isEffectivelyDisabled || undefined}
                 aria-label={resolvedTimeLabel}
                 aria-describedby={ariaDescribedBy}
                 aria-required={isEffectivelyRequired ? 'true' : undefined}

package/src/DateTimeInput/DateTimeInputTouch.test.tsx

@@ -987,6 +987,30 @@ describe('DateTimeInput touch surface', () => {
   });
 });
 
+describe('DateTimeInput touch surface: disabled without a reason', () => {
+  it('stays focusable and inert, and skips a caller onClick (AST-085 FR1, FR2)', () => {
+    const onClick = vi.fn();
+    render(
+      <DateTimeInput
+        label="Meeting"
+        isDisabled
+        onClick={onClick}
+        onChange={() => {}}
+      />,
+    );
+    for (const field of [dateField(), timeField()]) {
+      expect(field).not.toHaveAttribute('disabled');
+      expect(field).toHaveAttribute('aria-disabled', 'true');
+      field.focus();
+      expect(field).toHaveFocus();
+      fireEvent.click(field);
+      fireEvent.keyDown(field, {key: 'Enter'});
+      expect(field).toHaveAttribute('aria-expanded', 'false');
+    }
+    expect(onClick).not.toHaveBeenCalled();
+  });
+});
+
 describe('DateTimeInput touch surface: no stale commit', () => {
   // Records what each commit painted, so a value that is corrected one render
   // later (by an effect) shows up as a stale intermediate frame.

package/src/DateTimeInput/NativeDateSegment.tsx

@@ -60,7 +60,8 @@ export type NativeDateSegmentProps = {
   max?: ISODateString;
   isDateDisabled: (date: ReturnType<typeof plainDateFromISO>) => boolean;
   isEffectivelyDisabled: boolean;
-  hasDisabledMessage: boolean;
+  /** While disabled, stay focusable: aria-disabled and readOnly, not `disabled`. */
+  isFocusableDisabled: boolean;
   isEffectivelyRequired: boolean;
   isBusy: boolean;
   statusType?: InputStatusType;
@@ -87,7 +88,7 @@ export function NativeDateSegment({
   max,
   isDateDisabled,
   isEffectivelyDisabled,
-  hasDisabledMessage,
+  isFocusableDisabled,
   isEffectivelyRequired,
   isBusy,
   statusType,
@@ -262,7 +263,7 @@ export function NativeDateSegment({
       <button
         type="button"
         onClick={openPicker}
-        disabled={isEffectivelyDisabled}
+        aria-disabled={isEffectivelyDisabled || undefined}
         aria-label={t('@astryx.dateInput.openCalendar')}
         tabIndex={-1}
         {...stylex.props(
@@ -290,9 +291,11 @@ export function NativeDateSegment({
           onBlur={chainEventHandlers(handleBlur, onBlurProp)}
           min={min}
           max={max}
-          disabled={isEffectivelyDisabled && !hasDisabledMessage}
-          aria-disabled={hasDisabledMessage ? 'true' : undefined}
-          readOnly={hasDisabledMessage || undefined}
+          disabled={isEffectivelyDisabled && !isFocusableDisabled}
+          aria-disabled={
+            isEffectivelyDisabled && isFocusableDisabled ? 'true' : undefined
+          }
+          readOnly={(isEffectivelyDisabled && isFocusableDisabled) || undefined}
           aria-describedby={ariaDescribedBy}
           aria-required={isEffectivelyRequired ? 'true' : undefined}
           aria-invalid={

package/src/DateTimeInput/NativePickerSegments.test.tsx

@@ -161,6 +161,37 @@ describe('DateTimeInput nativePicker', () => {
     expect(getNativeTimeInput()).toBeInTheDocument();
   });
 
+  it('keeps disabled native controls focusable and inert (AST-085 FR1, FR2)', () => {
+    stubPointer(true);
+    const onClick = vi.fn();
+    render(
+      <DateTimeInput
+        label="Meeting"
+        isDisabled
+        onClick={onClick}
+        onChange={() => {}}
+      />,
+    );
+    for (const input of [getNativeDateInput(), getNativeTimeInput()]) {
+      expect(input).not.toHaveAttribute('disabled');
+      expect(input).toHaveAttribute('aria-disabled', 'true');
+      expect(input).toHaveAttribute('readonly');
+      input.focus();
+      expect(input).toHaveFocus();
+    }
+    fireEvent.click(getNativeDateInput());
+    expect(onClick).not.toHaveBeenCalled();
+  });
+
+  it('leaves enabled native controls editable (AST-043)', () => {
+    stubPointer(true);
+    render(<DateTimeInput label="Meeting" onChange={() => {}} />);
+    for (const input of [getNativeDateInput(), getNativeTimeInput()]) {
+      expect(input).not.toHaveAttribute('readonly');
+      expect(input).not.toHaveAttribute('aria-disabled');
+    }
+  });
+
   it('drops in-page popup ARIA because the OS owns both pickers', () => {
     stubPointer(true);
     render(<DateTimeInput label="Meeting" onChange={() => {}} />);

package/src/DateTimeInput/NativeTimeSegment.tsx

@@ -80,7 +80,8 @@ export type NativeTimeSegmentProps = {
   max?: ISOTimeString;
   hourFormat: '12h' | '24h';
   isEffectivelyDisabled: boolean;
-  hasDisabledMessage: boolean;
+  /** While disabled, stay focusable: aria-disabled and readOnly, not `disabled`. */
+  isFocusableDisabled: boolean;
   isEffectivelyRequired: boolean;
   isBusy: boolean;
   statusType?: InputStatusType;
@@ -112,7 +113,7 @@ export function NativeTimeSegment({
   max,
   hourFormat,
   isEffectivelyDisabled,
-  hasDisabledMessage,
+  isFocusableDisabled,
   isEffectivelyRequired,
   isBusy,
   statusType,
@@ -285,7 +286,7 @@ export function NativeTimeSegment({
       <button
         type="button"
         onClick={openPicker}
-        disabled={isEffectivelyDisabled}
+        aria-disabled={isEffectivelyDisabled || undefined}
         aria-label={openPickerLabel}
         tabIndex={-1}
         {...stylex.props(
@@ -309,9 +310,11 @@ export function NativeTimeSegment({
           min={min}
           max={max}
           step={60}
-          disabled={isEffectivelyDisabled && !hasDisabledMessage}
-          aria-disabled={hasDisabledMessage ? 'true' : undefined}
-          readOnly={hasDisabledMessage || undefined}
+          disabled={isEffectivelyDisabled && !isFocusableDisabled}
+          aria-disabled={
+            isEffectivelyDisabled && isFocusableDisabled ? 'true' : undefined
+          }
+          readOnly={(isEffectivelyDisabled && isFocusableDisabled) || undefined}
           // The segment's own label applies only when nothing else names it;
           // otherwise a caller aria-label from the spread above stays.
           aria-label={

package/src/DateTimeInput/TouchDateTimeField.tsx

@@ -159,6 +159,17 @@ const sizeStyles = stylex.create({
 const HORIZONTAL_SEGMENT_BASIS = 196;
 
 const styles = stylex.create({
+  // Same as DateTimeInput's: the focus ring for a focused disabled field.
+  disabledFocusRing: {
+    borderColor: {
+      default: colorVars['--color-border-emphasized'],
+      ':focus-within': colorVars['--color-accent'],
+    },
+    boxShadow: {
+      default: 'none',
+      ':focus-within': `inset 0px 0px 0px 2px ${colorVars['--color-accent-muted']}`,
+    },
+  },
   iconButton: {
     display: 'flex',
     alignItems: 'center',
@@ -1330,6 +1341,7 @@ export function TouchDateTimeField({
               sizeStyles[size],
               styles.touchDateWrapper,
               isEffectivelyDisabled && inputWrapperStyles.disabled,
+              isEffectivelyDisabled && styles.disabledFocusRing,
               status && inputStatusBorderStyles[status.type],
               status &&
                 !isEffectivelyDisabled &&
@@ -1340,7 +1352,7 @@ export function TouchDateTimeField({
           <button
             type="button"
             onClick={() => openSheet('date')}
-            disabled={isEffectivelyDisabled}
+            aria-disabled={isEffectivelyDisabled || undefined}
             aria-label={t('@astryx.dateInput.openCalendar')}
             tabIndex={-1}
             {...stylex.props(
@@ -1367,7 +1379,11 @@ export function TouchDateTimeField({
             readOnly
             inputMode="none"
             onChange={() => {}}
-            onClick={chainEventHandlers(() => openSheet('date'), onClickProp)}
+            onClick={
+              isEffectivelyDisabled
+                ? undefined
+                : chainEventHandlers(() => openSheet('date'), onClickProp)
+            }
             onKeyDown={chainEventHandlers(
               (event: React.KeyboardEvent<HTMLInputElement>) =>
                 handleInputKeyDown(event, 'date'),
@@ -1375,8 +1391,7 @@ export function TouchDateTimeField({
             )}
             aria-labelledby={controlLabelledBy}
             placeholder={placeholder}
-            disabled={isEffectivelyDisabled && !showsDisabledMessage}
-            aria-disabled={showsDisabledMessage ? 'true' : undefined}
+            aria-disabled={isEffectivelyDisabled ? 'true' : undefined}
             aria-describedby={ariaDescribedBy}
             aria-required={isEffectivelyRequired ? 'true' : undefined}
             aria-invalid={status?.type === 'error' ? 'true' : undefined}
@@ -1417,6 +1432,7 @@ export function TouchDateTimeField({
               sizeStyles[size],
               styles.touchTimeWrapper,
               isEffectivelyDisabled && inputWrapperStyles.disabled,
+              isEffectivelyDisabled && styles.disabledFocusRing,
               status && inputStatusBorderStyles[status.type],
               status &&
                 !isEffectivelyDisabled &&
@@ -1427,7 +1443,7 @@ export function TouchDateTimeField({
           <button
             type="button"
             onClick={() => openSheet('time')}
-            disabled={isEffectivelyDisabled}
+            aria-disabled={isEffectivelyDisabled || undefined}
             aria-label={t('@astryx.dateTimeInput.openTimePicker', {
               label: resolvedTimeLabel,
             })}
@@ -1456,8 +1472,7 @@ export function TouchDateTimeField({
             onClick={() => openSheet('time')}
             onKeyDown={event => handleInputKeyDown(event, 'time')}
             placeholder={timePlaceholder}
-            disabled={isEffectivelyDisabled && !showsDisabledMessage}
-            aria-disabled={showsDisabledMessage ? 'true' : undefined}
+            aria-disabled={isEffectivelyDisabled ? 'true' : undefined}
             aria-label={resolvedTimeLabel}
             aria-describedby={ariaDescribedBy}
             aria-required={isEffectivelyRequired ? 'true' : undefined}

package/src/Dialog/Dialog.test.tsx

@@ -286,6 +286,45 @@ describe('Dialog', () => {
     });
   });
 
+  describe('a cancel from inside the dialog', () => {
+    // A file input fires a bubbling `cancel` at itself when its picker is
+    // dismissed (Escape, or Cancel in the chooser). It reaches the <dialog>
+    // like a close request but is not one.
+    function DialogWithFilePicker({onOpenChange}: {onOpenChange: () => void}) {
+      return (
+        <Dialog isOpen onOpenChange={onOpenChange} aria-label="Upload">
+          <input type="file" aria-label="Picture" />
+        </Dialog>
+      );
+    }
+
+    it('stays open when a file picker inside it is dismissed', () => {
+      const onOpenChange = vi.fn();
+      render(<DialogWithFilePicker onOpenChange={onOpenChange} />);
+
+      const fromPicker = new Event('cancel', {bubbles: true, cancelable: true});
+      screen.getByLabelText('Picture').dispatchEvent(fromPicker);
+
+      expect(onOpenChange).not.toHaveBeenCalled();
+      expect(fromPicker.defaultPrevented).toBe(false);
+    });
+
+    it('still closes on its own close request', () => {
+      const onOpenChange = vi.fn();
+      render(<DialogWithFilePicker onOpenChange={onOpenChange} />);
+
+      screen
+        .getByLabelText('Picture')
+        .dispatchEvent(new Event('cancel', {bubbles: true, cancelable: true}));
+      screen
+        .getByRole('dialog')
+        .dispatchEvent(new Event('cancel', {cancelable: true}));
+
+      expect(onOpenChange).toHaveBeenCalledTimes(1);
+      expect(onOpenChange).toHaveBeenCalledWith(false);
+    });
+  });
+
   describe('IME composition', () => {
     // A CJK user presses Escape to cancel a half-formed character several times
     // a sentence. jsdom models neither composition nor the close watcher, so

package/src/Dialog/Dialog.tsx

@@ -643,11 +643,16 @@ export function Dialog({
   // Escape presses the stack owns never arrive here — it preventDefault()s
   // those, which suppresses the close watcher.
   //
-  // Always preventDefault so the browser cannot close a controlled <dialog>
-  // behind React's back, then answer the request with the stack's own rules:
-  // only the top-most layer dismisses, a `required` dialog swallows it, and
-  // nothing dismisses while an IME composition is in progress.
+  // A `cancel` that bubbles up from inside is not a close request for this
+  // dialog: a file input fires one when its picker is dismissed. It is left
+  // alone. Otherwise always preventDefault so the browser cannot close a
+  // controlled <dialog> behind React's back, then answer the request with the
+  // stack's own rules: only the top-most layer dismisses, a `required` dialog
+  // swallows it, and nothing dismisses while an IME composition is in progress.
   const handleCancel = (event: React.SyntheticEvent<HTMLDialogElement>) => {
+    if (event.target !== event.currentTarget) {
+      return;
+    }
     event.preventDefault();
     if (!shouldDismissOnCloseRequest()) {
       return;

package/src/DropdownMenu/DropdownMenu.spec.md

@@ -86,7 +86,7 @@ Consumer migration instructions belong in consumer docs and release notes.
 ## Public concepts
 
 Consumer props, item shapes, subcomponents, and presentation policy remain
-documented in `DropdownMenu.doc.mjs` and the subcomponent docs. Three component-local concepts are added, by DEC-2, DEC-3 and DEC-8; each
+documented in `DropdownMenu.doc.mjs` and the subcomponent docs. Four component-local concepts are added, by DEC-2, DEC-3, DEC-8 and proposed DEC-13; each
 keeps its released default.
 
 | Concept           | Closed values or states                                  | Meaning                                                                                                                                                                                          | Availability by variant/orientation/state | Default  | Owner                    | Stability | Invalid-value behavior                              |
@@ -94,6 +94,7 @@ keeps its released default.
 | Menu height cap   | `menuMaxHeight`: a number of pixels                      | Lifts the 300px cap for a menu that must fit its rows; the viewport still bounds it.                                                                                                             | Pointer presentation                      | `300px`  | `component:DropdownMenu` | stable    | Ignored by the touch sheet.                         |
 | Trigger source    | `button` (Button props) or `renderTrigger` (render prop) | Which control the menu hangs off. `trigger` receives `DropdownMenuTriggerProps` — the press model, keyboard opens, toggle click and ARIA wiring — and names the menu.                            | Both presentations                        | `button` | `component:DropdownMenu` | stable    | Both given: `trigger` wins and a dev warning fires. |
 | Header and footer | `header`, `footer`: any React node                       | Content above and below the rows, beside the menu inside the same popover or sheet — never inside the `role="menu"` element. With either, the pointer popover is a modal dialog around the menu. | Both presentations                        | none     | `component:DropdownMenu` | stable    | A false or empty value renders no region.           |
+| Sub-menu regions  | `header`, `footer` on a sub-menu: any React node         | Content above and below a sub-menu's rows, beside its menu inside its own surface; with either, that surface is a modal dialog named by the row (proposed FR20).                                 | Popover presentation                      | none     | `component:DropdownMenu` | proposed  | A false or empty value renders no region.           |
 
 ## Behavioral and layout contract
 
@@ -119,6 +120,7 @@ keeps its released default.
 | FR15                  | With `header` or `footer`, the pointer popover is a `role="dialog"` with `aria-modal="true"`, named like the menu, holding the header, then the `role="menu"` element, then the footer; the menu element holds only its rows. The trigger says `aria-haspopup="dialog"` and its `aria-controls` names the popover that holds the dialog. A region keeps its own keys and presses: neither the menu's key handling nor its press model claims an event that begins there. The menu is one Tab stop between the regions. Tab and Shift+Tab move through the header's controls, the menu, then the footer's controls, and wrap at either end; a control that is hidden, or under a hidden ancestor within its region, is not a stop. From a row, or a row of an open sub-menu, Tab and Shift+Tab close every open flyout and continue from the menu's stop. With no other stop, focus stays in the menu. Escape closes from anywhere in the popover, and focus returns to the trigger. The bottom sheet, already a dialog, shows the header above the actions and the footer below them. Without either prop, the menu renders and behaves exactly as it does without them: no dialog, `aria-haspopup="menu"`, and Tab closes the menu. | DEC-8, DEC-10, docs, and tests                                                                                                                                                | Proposed; awaiting owner approval                                                 |
 | FR16                  | `DropdownMenuCheckboxItem` MUST expose one `menuitemcheckbox` row whose `aria-checked` equals its controlled value; enabled activation reports `!value`, stays open by default, and composes consumer click and pointer-move handlers with owned activation and hover focus. Disabled activation calls no consumer activation handler.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Released subcomponent API; `architecture:public-component-api/INV5–INV8`; `DropdownMenuSelectable.test.tsx`                                                                   | Verified current behavior; consumer handlers are preserved                        |
 | FR17                  | Disabled menu rows SHOULD remain keyboard-discoverable while activation stays blocked. Current shared `useListFocus` deliberately skips every `aria-disabled` row, including checkbox items.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | WAI-ARIA Menu pattern; current shared navigation source/tests                                                                                                                 | Objective mismatch; shared mechanism remains undecided in OQ1                     |
+| FR20                  | With `header` or `footer` on a sub-menu (`DropdownMenuSubMenu`), its surface is a modal dialog named by its row (AR7), holding the header, the sub-menu's `role="menu"` (rows only), then the footer. It sits in a host `DropdownMenu` renders beside its menu, never inside a menu; under a root with no such host (`ContextMenu`) the sub-menu shows its rows alone. On a fine pointer the dialog is the flyout; on a compact touch display, the drilled-in view, which replaces the root's menu and regions until popped. A region keeps its own keys and presses. The rows are one Tab stop: Tab and Shift+Tab walk the header's controls, the rows, then the footer's, and wrap; from a deeper flyout, that flyout closes and the walk goes on from the rows. An open lands as for any sub-menu (FR11, FR12), not on a region. Escape in the dialog, outside an IME composition and unless a control there handled it, returns focus to the row and leaves the root open. A pointer leaving the flyout keeps it open until focus leaves, and it closes with the flyout holding its row. Without either prop nothing changes.                                                                                                    | Proposed DEC-13; FR15; AR5                                                                                                                                                    | Proposed; verified in jsdom and Chromium, pending owner review                    |
 
 ### Allowed variation
 
@@ -200,13 +202,20 @@ visibility helper.
   trigger keeps `aria-expanded`; its `aria-haspopup` says `dialog`, and its
   `aria-controls` names the popover that holds the dialog rather than the
   menu, as Popover's own trigger does.
-
 - **AR6 — Checkbox rows remain one control.** The row owns
   `menuitemcheckbox`, its accessible name, checked state, focus, and activation;
   Indicator's checkbox marker is decorative. Disabled activation is inert.
   Current shared navigation skips disabled rows instead of making them
   discoverable as the WAI-ARIA Menu pattern recommends; FR17 and OQ1 retain that
   gap without inventing a component-local focus path.
+- **AR7 (proposed) — A sub-menu with a header or footer adopts the same APG
+  Dialog (Modal) parts for its own surface** (`spec:AST-020/FR15`):
+  `role="dialog"`, `aria-modal="true"`, and an accessible name, its row's;
+  focus moves into the dialog on open, to the sub-menu's first row or its
+  menu as FR11 and FR12 already state; Tab and Shift+Tab cycle within it
+  (FR20); Escape closes it and focus returns to the row. The sub-menu's menu
+  inside keeps AR3. The row keeps `aria-expanded`; its `aria-haspopup` says
+  `dialog` and its `aria-controls` names the dialog.
 
 ## Design relationships
 
@@ -324,6 +333,7 @@ than adding a DropdownMenu-owned heading target.
 | FR15                | `DropdownMenu.test.tsx` header and footer suite; `__tests__/MenuHeaderFooter.a11y.chromium.spec.ts` in real Chromium                                                                                                                                                                                                                                                                                                                                                                                                                                                   | dialog role, modality, name and trigger wiring; regions outside the menu element; typing in a header field; Tab walk header → menu → footer with wrap at both ends; Tab and Shift+Tab from an open sub-menu; hidden and hidden-wrapper controls; Escape from the header; a finger tap on a footer button; bottom sheet order; no regions | A region rendered inside the menu element, a popover with regions that is not a named modal dialog, a trigger still saying `aria-haspopup="menu"` with regions, a header key taken by typeahead, a Tab that leaves the dialog or closes it, focus stranded outside the dialog, or a footer tap swallowed by the press model fails. |
 | FR16                | `DropdownMenuSelectable.test.tsx`, source inspection, scoped `pr-a11y` over the `a11y/Checkbox pattern` stories, and owned Storybook states                                                                                                                                                                                                                                                                                                                                                                                                                            | checked, unchecked, disabled, caller click/pointer handlers, marker size and ownership                                                                                                                                                                                                                                                   | A dropped consumer handler, wrong checked state, nested semantic checkbox, disabled activation, or menu that closes by default fails.                                                                                                                                                                                              | `audit:DropdownMenuCheckboxItem/behavior`      |
 | FR17, AR6           | Shared navigation source and DropdownMenu keyboard tests                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | disabled checkbox row first, middle, and last                                                                                                                                                                                                                                                                                            | Current tests prove the shared hook skips the row; no keyboard-discoverability proof exists until OQ1 is settled.                                                                                                                                                                                                                  | `audit:DropdownMenuCheckboxItem/accessibility` |
+| FR20, AR7           | `DropdownMenuSubMenu.test.tsx` "header and footer" suite; `ContextMenu.test.tsx` rows-alone case; `__tests__/SubMenuHeaderFooter.a11y.chromium.spec.ts` in real Chromium (fine pointer, coarse pointer)                                                                                                                                                                                                                                                                                                                                                                | flyout and phone view; dialog role, name, row wiring; regions outside menus; Tab walk and wrap from a field, row, deeper flyout; field keys, presses; Escape, IME and handled Escapes; keyboard open; pointer leaving, focus in then out; parent closing a nested flyout; view tracking its regions; ContextMenu rows alone              | A region inside a menu element, a surface with regions that is not a named modal dialog, a row still saying `aria-haspopup="menu"`, a field key taken by the menu, a Tab that leaves or closes the dialog, a flyout closed under focus by a pointer leaving, a flyout outliving its parent, or the root menu beside a view, fails. | `audit:DropdownMenu/behavior`                  |
 
 ## Decision log
 
@@ -541,3 +551,24 @@ the menu. Tab and Shift+Tab wrap within the dialog, as the APG Dialog
 pattern requires; Escape and a press outside close it. Without either prop
 the component is unchanged: a Menu Button whose Tab closes the menu. Rejected:
 closing on Tab past either end, which leaves a modal dialog by Tab.
+
+### DEC-13 (proposed) — A sub-menu's header and footer make its surface a dialog beside the menu
+
+**Reference:** `component:DropdownMenu/DEC-13`
+**Decider:** proposed by `vjeux`, 2026-10-14; pending owner review
+
+A filter field above a sub-menu's rows, or a door below them, is a control
+that is not a menu item, so DEC-8 and DEC-10 apply to the sub-menu's own
+surface as they apply to the root's: the sub-menu's menu holds only its rows,
+and the surface around it is a named modal dialog whose Tab order wraps. A
+flyout renders inside the menu that holds its row, so a dialog there would
+still sit inside that menu; the `DropdownMenu` therefore renders a host beside its menu,
+inside its popover, and a sub-menu with regions renders its surface there (the
+flyout layer, or the drilled-in view, which then takes the root menu's place).
+Rendered there, a flyout no longer hides with the flyout that holds its row,
+so it closes with it. The pointer leaving that flyout does not close it while
+focus is inside, because what was typed into its field would go with it.
+Rejected: regions inside the flyout beside the sub-menu's menu,
+which puts them inside the parent menu; a separate DropdownMenu for the level,
+which loses the row, the drill-in and the single press model; and closing the
+flyout when the pointer leaves it as any flyout does.