@astryxdesign/core 0.7.1-canary.ff40b78 → 0.7.1

package/src/ContextMenu/ContextMenu.tsx

@@ -3,8 +3,8 @@
 
 /**
  * @file ContextMenu.tsx
- * @input Uses React, StyleX, useLayer, BottomSheet, useListFocus, and the
- *   shared menu-presentation resolver
+ * @input Uses React, StyleX, useLayer, shared layer dismissal, BottomSheet,
+ *   useListFocus, and the shared menu-presentation resolver
  * @output Exports ContextMenu with cursor-popover and touch-sheet presentations
  * @position Core implementation; consumed by index.ts
  *
@@ -50,6 +50,8 @@ import {Button} from '../Button';
 import {Heading} from '../Heading';
 import {Icon} from '../Icon';
 import {useLayer} from '../Layer/useLayer';
+import {LayerDepthProvider} from '../Layer/LayerDepthContext';
+import {useLayerDismissal} from '../Layer/useLayerDismissal';
 import {MenuBottomSheetActionList} from '../DropdownMenu/MenuBottomSheetActionList';
 import {renderDropdownItems} from '../DropdownMenu/renderDropdownItems';
 import {
@@ -77,7 +79,7 @@ import {
   easeVars,
   shadowVars,
 } from '../theme/tokens.stylex';
-import {mergeProps, isImeKeyEvent, rtlStyles} from '../utils';
+import {mergeProps, rtlStyles} from '../utils';
 import type {BaseProps} from '../BaseProps';
 import type {StyleXStyles} from '../theme/types';
 import {themeProps} from '../utils/themeProps';
@@ -313,6 +315,11 @@ export function ContextMenu({
   style,
   xstyle,
   triggerXstyle,
+  onContextMenu: onContextMenuProp,
+  onTouchStart: onTouchStartProp,
+  onTouchMove: onTouchMoveProp,
+  onTouchEnd: onTouchEndProp,
+  onTouchCancel: onTouchCancelProp,
   'data-testid': testId,
   ...rest
 }: ContextMenuProps) {
@@ -346,7 +353,6 @@ export function ContextMenu({
   // Element focused before the menu opened, restored when it closes so focus
   // does not fall to <body> after Escape or outside-click dismissal.
   const triggerFocusRef = useRef<HTMLElement | null>(null);
-  const sheetHeadingRef = useRef<HTMLHeadingElement>(null);
 
   const [isOpen, setIsOpen] = useState(false);
   const [submenuPath, setSubmenuPath] = useState<ContextMenuItemData[]>([]);
@@ -406,15 +412,14 @@ export function ContextMenu({
     [closeMenu],
   );
 
-  useEffect(() => {
-    if (!isOpen || submenuPath.length === 0) {
-      return;
-    }
-    const frame = requestAnimationFrame(() => {
-      sheetHeadingRef.current?.focus({preventScroll: true});
-    });
-    return () => cancelAnimationFrame(frame);
-  }, [isOpen, submenuPath.length]);
+  const setSheetHeadingRef = useCallback(
+    (node: HTMLHeadingElement | null) => {
+      if (node && isOpen && submenuPath.length > 0) {
+        node.focus({preventScroll: true});
+      }
+    },
+    [isOpen, submenuPath.length],
+  );
 
   const {
     listRef,
@@ -429,7 +434,14 @@ export function ContextMenu({
     // Menus wrap from the last row to the first and back.
     wrap: true,
     hasPaging: true,
-    onEscape: closeMenu,
+  });
+
+  // Join the shared stack so an Escape press dismisses exactly one top-most
+  // surface. BottomSheet owns its own dismissal path.
+  useLayerDismissal({
+    isActive: isOpen && !usesBottomSheet,
+    onDismiss: closeMenu,
+    getContainer: () => listRef.current,
   });
 
   // Typeahead over the enabled menu items, matched on each row's LABEL alone.
@@ -465,32 +477,6 @@ export function ContextMenu({
     };
   }, [isOpen, closeMenu, listRef, usesBottomSheet]);
 
-  // Dismiss on Escape from anywhere while open. The menu div's own onKeyDown
-  // only fires when focus is inside the menu; a document-level listener is
-  // kept as a reliable fallback Escape path (e.g. if focus has moved out of
-  // the menu). Guards against IME composition-cancel.
-  useEffect(() => {
-    if (!isOpen || usesBottomSheet) {
-      return;
-    }
-    const handleEscape = (e: KeyboardEvent) => {
-      if (e.key !== 'Escape') {
-        return;
-      }
-      if (isImeKeyEvent(e)) {
-        // Ignore Escape that is committing/cancelling an IME composition;
-        // see utils/ime.ts for why.
-        return;
-      }
-      e.preventDefault();
-      closeMenu();
-    };
-    document.addEventListener('keydown', handleEscape);
-    return () => {
-      document.removeEventListener('keydown', handleEscape);
-    };
-  }, [isOpen, closeMenu, usesBottomSheet]);
-
   const listKeyDown = useCallback(
     (e: React.KeyboardEvent) => {
       // A submenu flyout renders inline inside this menu; its key events bubble
@@ -601,7 +587,12 @@ export function ContextMenu({
   // held long enough (see useLongPress for timer/move-cancel/cleanup logic).
   // The hook also returns the imperative start/moveTo/cancel API the menu press
   // model drives; only its four touch handlers belong on the trigger element.
-  const longPress = useLongPress({
+  const {
+    onTouchStart: handleLongPressTouchStart,
+    onTouchMove: handleLongPressTouchMove,
+    onTouchEnd: handleLongPressTouchEnd,
+    onTouchCancel: handleLongPressTouchCancel,
+  } = useLongPress({
     disabled: isDisabled,
     onLongPress: useCallback(
       (point: {x: number; y: number}) => {
@@ -616,6 +607,45 @@ export function ContextMenu({
     ),
   });
 
+  // ContextMenu owns invocation and long-press cleanup. Consumer handlers are
+  // notified too, but preventing their default does not cancel component-owned
+  // behavior that the public API does not promise as cancelable.
+  const handleTriggerContextMenu = useCallback(
+    (event: React.MouseEvent<HTMLElement>) => {
+      handleContextMenu(event);
+      onContextMenuProp?.(event);
+    },
+    [handleContextMenu, onContextMenuProp],
+  );
+  const handleTriggerTouchStart = useCallback(
+    (event: React.TouchEvent<HTMLElement>) => {
+      handleLongPressTouchStart(event);
+      onTouchStartProp?.(event);
+    },
+    [handleLongPressTouchStart, onTouchStartProp],
+  );
+  const handleTriggerTouchMove = useCallback(
+    (event: React.TouchEvent<HTMLElement>) => {
+      handleLongPressTouchMove(event);
+      onTouchMoveProp?.(event);
+    },
+    [handleLongPressTouchMove, onTouchMoveProp],
+  );
+  const handleTriggerTouchEnd = useCallback(
+    (event: React.TouchEvent<HTMLElement>) => {
+      handleLongPressTouchEnd();
+      onTouchEndProp?.(event);
+    },
+    [handleLongPressTouchEnd, onTouchEndProp],
+  );
+  const handleTriggerTouchCancel = useCallback(
+    (event: React.TouchEvent<HTMLElement>) => {
+      handleLongPressTouchCancel();
+      onTouchCancelProp?.(event);
+    },
+    [handleLongPressTouchCancel, onTouchCancelProp],
+  );
+
   const popoverXstyle = menuWidth
     ? styles.popoverCustomWidth(menuWidth)
     : styles.popover;
@@ -702,7 +732,7 @@ export function ContextMenu({
             />
           )}
           <Heading
-            ref={sheetHeadingRef}
+            ref={setSheetHeadingRef}
             level={3}
             tabIndex={-1}
             xstyle={[
@@ -731,11 +761,11 @@ export function ContextMenu({
       <TriggerElement
         ref={useMergedRefs(ref, triggerRef)}
         {...triggerProps}
-        onContextMenu={handleContextMenu}
-        onTouchStart={longPress.onTouchStart}
-        onTouchMove={longPress.onTouchMove}
-        onTouchEnd={longPress.onTouchEnd}
-        onTouchCancel={longPress.onTouchCancel}
+        onContextMenu={handleTriggerContextMenu}
+        onTouchStart={handleTriggerTouchStart}
+        onTouchMove={handleTriggerTouchMove}
+        onTouchEnd={handleTriggerTouchEnd}
+        onTouchCancel={handleTriggerTouchCancel}
         data-testid={testId}
         {...stylex.props(
           styles.trigger,
@@ -768,7 +798,7 @@ export function ContextMenu({
           </LazyMenuBottomSheet>
         </Suspense>
       ) : (
-        layer.render(renderedMenu, {
+        layer.render(<LayerDepthProvider>{renderedMenu}</LayerDepthProvider>, {
           placement: 'below',
           alignment: 'start',
           xstyle: [popoverXstyle, layerAnimations.below],

package/src/DateInput/DateInput.doc.mjs

@@ -182,12 +182,36 @@ export const docs = {
       description:
         'StyleX styles for the Field box around the label, control, and status. containerClassName and containerStyle take a class name and inline styles for the same box. No effect (development warning) where no Field box renders: inside InputGroup (style the group) and in a horizontal-labels FormLayout.',
     },
+    {
+      name: 'containerClassName',
+      type: 'string',
+      description:
+        'Class name for the Field box. Same targeting as containerXstyle.',
+    },
+    {
+      name: 'containerStyle',
+      type: 'CSSProperties',
+      description:
+        'Inline styles for the Field box. Same targeting as containerXstyle.',
+    },
     {
       name: 'controlXstyle',
       type: 'StyleXStyles',
       description:
         'StyleX styles for the visual control box: the bordered element that holds the text, icons, and end controls, never the native input. controlClassName and controlStyle take a class name and inline styles for the same box. Replaces root xstyle, className, and style, which this component does not accept.',
     },
+    {
+      name: 'controlClassName',
+      type: 'string',
+      description:
+        'Class name for the visual control box. Same targeting as controlXstyle.',
+    },
+    {
+      name: 'controlStyle',
+      type: 'CSSProperties',
+      description:
+        'Inline styles for the visual control box. Same targeting as controlXstyle.',
+    },
   ],
   theming: {
     targets: [
@@ -503,12 +527,32 @@ export const docsZh = {
       description:
         '作用于包含标签、控件和状态的 Field 容器的 StyleX 样式；containerClassName 与 containerStyle 以类名和内联样式作用于同一容器。没有 Field 容器时（InputGroup 内或 horizontal-labels FormLayout 中）不生效，并在开发环境发出警告。',
     },
+    {
+      name: 'containerClassName',
+      type: 'string',
+      description: 'Field 容器的类名，作用目标同 containerXstyle。',
+    },
+    {
+      name: 'containerStyle',
+      type: 'CSSProperties',
+      description: 'Field 容器的内联样式，作用目标同 containerXstyle。',
+    },
     {
       name: 'controlXstyle',
       type: 'StyleXStyles',
       description:
         '作用于可见控件框（带边框、包含文本、图标和末端控件的元素，而非原生 input）的 StyleX 样式；controlClassName 与 controlStyle 以类名和内联样式作用于同一元素。本组件不接受根级 xstyle、className 和 style。',
     },
+    {
+      name: 'controlClassName',
+      type: 'string',
+      description: '可见控件框的类名，作用目标同 controlXstyle。',
+    },
+    {
+      name: 'controlStyle',
+      type: 'CSSProperties',
+      description: '可见控件框的内联样式，作用目标同 controlXstyle。',
+    },
   ],
   theming: {
     targets: [
@@ -615,7 +659,15 @@ export const docsDense = {
       "deprecated, use presentation: 'touch'='adaptive-native', 'always'='native', 'never'='adaptive-bottom-sheet'. still works as released; presentation wins if both set.",
     containerXstyle:
       'Field box (label+control+status); also containerClassName/containerStyle. no effect in InputGroup or horizontal-labels FormLayout',
+    containerClassName:
+      'class name for the Field box; same target as containerXstyle',
+    containerStyle:
+      'inline styles for the Field box; same target as containerXstyle',
     controlXstyle:
       'visual control box (border/bg/icons), never the native input; also controlClassName/controlStyle. no root xstyle/className/style',
+    controlClassName:
+      'class name for the visual control box; same target as controlXstyle',
+    controlStyle:
+      'inline styles for the visual control box; same target as controlXstyle',
   },
 };

package/src/DateInput/DateInput.spec.md

@@ -13,6 +13,7 @@ review_triggers: [public-api, behavior, layout, theming, accessibility]
 verified_by:
   [
     packages/core/src/DateInput/DateInput.test.tsx,
+    packages/core/src/DateInput/DateInput.fr10.test.tsx,
     packages/core/src/DateInput/DateInputTouch.test.tsx,
     packages/core/src/DateInput/NativeDateField.test.tsx,
     packages/core/src/DateInput/Presentation.test.tsx,
@@ -48,7 +49,7 @@ compatibility promise, ownership boundary, or visual direction.
 | Builder impact          | Existing native DateInput `changeAction` handlers now run after `onChange` and receive optimistic busy feedback. No API or migration work is required.                                                                        |
 | Compatibility/readiness | Compatible patch correction under the current input-field family rule. Released defaults and controlled ownership are preserved; exact-head browser evidence remains audit evidence rather than product authority.            |
 | Review checks           | Reject a surface-mapping change, lost constraint, callback-order change, unlabeled field, unreachable disabled reason, changed close behavior, or a theming target placed on the wrong owner.                                 |
-| Governing rules         | `spec:AST-043/FR1–FR5`; `family:input-fields/FR1–FR6, FR8–FR9`; `family:overlay-dismissal/FR1–FR7`, including its recorded BottomSheet adoption gap; the three architecture records linked above.                             |
+| Governing rules         | `spec:AST-043/FR1–FR5`; `family:input-fields/FR1–FR6, FR8–FR10`; `family:overlay-dismissal/FR1–FR7`, including its recorded BottomSheet adoption gap; the three architecture records linked above.                            |
 
 This table is a review projection; the body below is authoritative only after this
 record becomes `current`.
@@ -211,6 +212,15 @@ approved policy.
 - **AR7 — Directionality.** DateInput's own calendar and clear controls exchange logical
   inline sides in RTL while preserving their labels and meanings; Calendar navigation
   remains owned and verified by `component:Calendar`.
+- **AR8 — The month scroller is an APG grid** (`spec:AST-020/FR15`), as one
+  composite control: each mounted month pane of the touch calendar's scroller
+  is a `role="grid"` named for its month, with rows of `role="gridcell"` days,
+  at most one day per pane holding a Tab stop,
+  `aria-selected` on the chosen day; ArrowLeft and ArrowRight move by a day
+  following the reading direction, ArrowUp and ArrowDown by a week, Home and End
+  to the ends of the week, PageUp and PageDown by a month, and Enter or Space
+  picks the focused day. Implementation gap: PageUp/PageDown do not page by a
+  month.
 
 ## Design relationships
 
@@ -249,14 +259,15 @@ approved policy.
 
 The `date-input` target owns the composite field surface. The
 `date-input-toggle-icon` target reflects collapsed and expanded states on the icon
-itself. The deprecated `date-input-clear-icon` alias remains compatibility metadata;
-the shared `input-clear-icon` target owns current clear-glyph theming.
+itself. The shared `input-clear-icon` target owns clear-glyph theming; DateInput adds no
+clear-glyph target of its own.
 
 ## Family and system relationships
 
 - `family:input-fields` owns stable field sizing, end-control space, grouped
-  adaptation, disabled reasons, loading, Transition Actions, status placement, and
-  the iOS-only focus-zoom floor; DateInput adopts every listed concept.
+  adaptation, disabled reasons, loading, Transition Actions, status placement,
+  base-prop and part-styling targets, and the iOS-only focus-zoom floor; DateInput
+  adopts every listed concept.
 - `family:overlay-dismissal` owns topmost Popover and BottomSheet dismissal. DateInput's
   Popover path uses the shared owner; its bottom-sheet path inherits BottomSheet's
   recorded adoption gap. DateInput owns only selection, open-state requests, and focus
@@ -271,16 +282,17 @@ the shared `input-clear-icon` target owns current clear-glyph theming.
 
 ## Verification map
 
-| Contract                                             | Verification                                                                   | Representative states                                                                                    | Mutation or failure expectation                                                                    | Audit section                   |
-| ---------------------------------------------------- | ------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | ------------------------------- |
-| FR1, FR5–FR8, FR10–FR12; AR1–AR4                     | `DateInput.test.tsx`                                                           | empty, valued, typing, invalid, constrained, open, disabled, busy, clear, status, grouped                | Value, callbacks, ARIA, disabled guard, focus, or shared-field composition drifts                  | `audit:DateInput/pointer-field` |
-| FR2–FR4                                              | `Presentation.test.tsx`, `NativeDateField.test.tsx`, `DateInputTouch.test.tsx` | every presentation, omitted props, every deprecated mapping, dual props, fine/coarse, touchscreen laptop | A value resolves to the wrong surface, width affects modality, or legacy behavior wins incorrectly | `audit:DateInput/presentation`  |
-| FR5–FR7; AR1, AR3–AR5                                | `NativeDateField.test.tsx`                                                     | empty, valued, focused, constrained, disabled, clear, formatted, locale                                  | Native commit, overlay, label, constraint, or focus reconciliation drifts                          | `audit:DateInput/native`        |
-| FR1, FR4–FR7, FR9, FR11–FR12; AR1, AR4, AR6; PR1–PR2 | `DateInputTouch.test.tsx`                                                      | closed/open, month grid, selection correction, wheels, bounds, keyboard, swipe, mouse drag, clear, busy  | Touch value parity, bounded rendering, focus, semantics, or gesture ownership drifts               | `audit:DateInput/touch`         |
-| FR2–FR3, FR6                                         | `DateInput.doc.mjs`, Storybook controls, `scripts/check-knowledge.mjs`         | five presentation values, deprecated prop, named formats, English and Chinese docs                       | Source, docs, types, or default mappings disagree                                                  | `audit:DateInput/docs-api`      |
-| Theming anatomy                                      | `DateInput.test.tsx`, `themingTargets.test.ts`, generated probe theme          | root size/status/disabled, toggle state, shared clear target                                             | Target class or state is missing, undocumented, or placed on the wrong element                     | `audit:DateInput/theming`       |
-| FR8; AR2                                             | `apps/storybook/stories/DateInput.stories.tsx`, component-scoped axe           | open Calendar dialog plus closed field states                                                            | Important popup semantics stay unreachable to the browser audit                                    | `audit:DateInput/a11y`          |
-| AR7                                                  | `apps/storybook/rtl-audit/targets.json`, component RTL audit                   | calendar and clear controls in LTR and RTL                                                               | DateInput-owned controls fail to exchange logical inline order                                     | `audit:DateInput/rtl`           |
+| Contract                                             | Verification                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | Representative states                                                                                    | Mutation or failure expectation                                                                                                                         | Audit section                   |
+| ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- |
+| FR1, FR5–FR8, FR10–FR12; AR1–AR4                     | `DateInput.test.tsx`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | empty, valued, typing, invalid, constrained, open, disabled, busy, clear, status, grouped                | Value, callbacks, ARIA, disabled guard, focus, or shared-field composition drifts                                                                       | `audit:DateInput/pointer-field` |
+| FR2–FR4                                              | `Presentation.test.tsx`, `NativeDateField.test.tsx`, `DateInputTouch.test.tsx`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | every presentation, omitted props, every deprecated mapping, dual props, fine/coarse, touchscreen laptop | A value resolves to the wrong surface, width affects modality, or legacy behavior wins incorrectly                                                      | `audit:DateInput/presentation`  |
+| FR5–FR7; AR1, AR3–AR5                                | `NativeDateField.test.tsx`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | empty, valued, focused, constrained, disabled, clear, formatted, locale                                  | Native commit, overlay, label, constraint, or focus reconciliation drifts                                                                               | `audit:DateInput/native`        |
+| FR1, FR4–FR7, FR9, FR11–FR12; AR1, AR4, AR6; PR1–PR2 | `DateInputTouch.test.tsx`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | closed/open, month grid, selection correction, wheels, bounds, keyboard, swipe, mouse drag, clear, busy  | Touch value parity, bounded rendering, focus, semantics, or gesture ownership drifts                                                                    | `audit:DateInput/touch`         |
+| FR2–FR3, FR6                                         | `DateInput.doc.mjs`, Storybook controls, `scripts/check-knowledge.mjs`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | five presentation values, deprecated prop, named formats, English and Chinese docs                       | Source, docs, types, or default mappings disagree                                                                                                       | `audit:DateInput/docs-api`      |
+| Theming anatomy                                      | `DateInput.test.tsx`, `themingTargets.test.ts`, generated probe theme                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | root size/status/disabled, toggle state, shared clear target                                             | Target class or state is missing, undocumented, or placed on the wrong element                                                                          | `audit:DateInput/theming`       |
+| FR8; AR2                                             | `apps/storybook/stories/DateInput.stories.tsx`, component-scoped axe                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | open Calendar dialog plus closed field states                                                            | Important popup semantics stay unreachable to the browser audit                                                                                         | `audit:DateInput/a11y`          |
+| AR7                                                  | `apps/storybook/rtl-audit/targets.json`, component RTL audit                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | calendar and clear controls in LTR and RTL                                                               | DateInput-owned controls fail to exchange logical inline order                                                                                          | `audit:DateInput/rtl`           |
+| AR8                                                  | `DateInputTouch.test.tsx` calendar-surface suite ("mounts a window of months around the visible one, not the whole century" for the named grids, "moves keyboard focus by date, across the month boundary", "moves a week at a time with the vertical arrows", "leaves exactly one day per month tab-reachable", "gives a spilled date no tab stop in the pane that borrows it", "disables days outside min/max and refuses to commit them", "follows the reading direction under RTL: ArrowLeft moves to the next day", "moves keyboard focus by date, across the month boundary" (the real day, not the spill copy)); ArrowUp, Home/End, Page and activation keys under the Grid accessibility contract (`internal/a11y-spec`, pending) | LTR and RTL; month boundary; selected day; today                                                         | A day loses its gridcell role or selection, two days in one pane hold a Tab stop, or an arrow, Home/End, Page or activation key stops moving or picking | `audit:DateInput/accessibility` |
 
 ## Decision log
 

package/src/DateInput/DateInput.test.tsx

@@ -9,6 +9,7 @@
  * SYNC: When DateInput.tsx changes, update tests to match new behavior
  */
 
+import {useState} from 'react';
 import {describe, it, expect, vi, beforeEach} from 'vitest';
 import {
   render,
@@ -27,6 +28,7 @@ import {InputGroupText} from '../InputGroup/InputGroupText';
 import {defineTheme} from '../theme/defineTheme';
 import {generateThemeCSS} from '../theme/generateThemeRules';
 import {InternationalizationProvider} from '../i18n';
+import type {ISODateString} from '../utils';
 
 function generateThemeTestCSS(theme: Parameters<typeof generateThemeCSS>[0]) {
   const {prose, component} = generateThemeCSS(theme);
@@ -593,6 +595,42 @@ describe('DateInput', () => {
   // Full popover interaction is tested in the browser via Storybook.
 
   describe('hasClear', () => {
+    it('shows no selected calendar days after clearing', async () => {
+      const user = userEvent.setup();
+
+      function ControlledDateInput() {
+        const [value, setValue] = useState<ISODateString | undefined>(
+          '2026-01-01',
+        );
+        return (
+          <DateInput
+            label="Date"
+            value={value}
+            onChange={setValue}
+            min="2026-01-01"
+            max="2026-01-31"
+            presentation="popover"
+            hasClear
+          />
+        );
+      }
+
+      render(<ControlledDateInput />);
+      await user.click(getButton('Open calendar'));
+      await user.click(getButton(/January 15, 2026/));
+      expect(
+        screen.getAllByRole('gridcell', {selected: true, hidden: true}),
+      ).toHaveLength(1);
+
+      await user.click(getButton('Clear Date'));
+      expect(screen.getByRole('combobox')).toHaveValue('');
+      await user.click(getButton('Open calendar'));
+
+      expect(
+        screen.queryAllByRole('gridcell', {selected: true, hidden: true}),
+      ).toHaveLength(0);
+    });
+
     it('shows clear button when hasClear is true and value exists', () => {
       render(
         <DateInput

package/src/DateInput/DateInput.tsx

@@ -910,7 +910,7 @@ function PointerDateField({
         <Calendar
           handleRef={calendarRef}
           mode="single"
-          value={optimisticValue}
+          value={optimisticValue ?? null}
           onChange={handleDateSelect}
           min={min}
           max={max}

package/src/DateInput/DateInputTouch.test.tsx

@@ -1118,6 +1118,28 @@ describe('DateInput — calendar surface', () => {
     last.focus();
     fireEvent.keyDown(last, {key: 'ArrowRight'});
     expect(document.activeElement).toHaveAttribute('data-date', '2026-04-01');
+    // The real April 1, not its dimmed spill copy at the foot of the March
+    // pane (which is disabled and selects nothing).
+    expect(pane('April 2026')).toContainElement(
+      document.activeElement as HTMLElement,
+    );
+    expect(document.activeElement).not.toHaveAttribute('aria-disabled');
+  });
+
+  it('follows the reading direction under RTL: ArrowLeft moves to the next day', () => {
+    renderAndOpen(
+      <InternationalizationProvider locale="en-US" dir="rtl">
+        <Controlled initial="2026-03-10" />
+      </InternationalizationProvider>,
+    );
+    const day = within(pane('March 2026')).getByRole('button', {
+      name: /March 10, 2026/,
+    });
+    day.focus();
+    fireEvent.keyDown(day, {key: 'ArrowLeft'});
+    expect(document.activeElement).toHaveAttribute('data-date', '2026-03-11');
+    fireEvent.keyDown(document.activeElement!, {key: 'ArrowRight'});
+    expect(document.activeElement).toHaveAttribute('data-date', '2026-03-10');
   });
 
   it('moves a week at a time with the vertical arrows', () => {

package/src/DateInput/MonthScroller.tsx

@@ -637,12 +637,16 @@ export function MonthScroller({
       // Column within the displayed week, which is what Home/End move to —
       // not the day of the month.
       const column = (plainDateDayOfWeek(date) - weekStartsOn + 7) % 7;
+      // The horizontal arrows follow the reading direction (APG grid): under
+      // RTL the next day sits to the left.
+      const forward = isRTL ? 'ArrowLeft' : 'ArrowRight';
+      const backward = isRTL ? 'ArrowRight' : 'ArrowLeft';
       switch (event.key) {
-        case 'ArrowLeft':
+        case backward:
           event.preventDefault();
           moveFocus(date, -1);
           break;
-        case 'ArrowRight':
+        case forward:
           event.preventDefault();
           moveFocus(date, 1);
           break;
@@ -666,7 +670,7 @@ export function MonthScroller({
           break;
       }
     },
-    [moveFocus, weekStartsOn],
+    [isRTL, moveFocus, weekStartsOn],
   );
 
   // The focused day may have been in an unmounted pane a frame ago; focus it
@@ -677,8 +681,11 @@ export function MonthScroller({
     if (!shouldRestoreFocusRef.current || focusedISO == null) {
       return;
     }
+    // A date can be mounted twice: as a real day in its own pane and as a
+    // dimmed, disabled spill copy at the edge of a neighbouring pane. Only
+    // the real day may take focus, or Enter and Space would select nothing.
     const target = scrollerRef.current?.querySelector<HTMLElement>(
-      `[data-date="${focusedISO}"]`,
+      `[data-date="${focusedISO}"]:not([data-outside])`,
     );
     if (target != null) {
       shouldRestoreFocusRef.current = false;
@@ -835,6 +842,7 @@ function MonthPane({
                 <button
                   type="button"
                   data-date={day.iso}
+                  data-outside={day.isOutside ? '' : undefined}
                   tabIndex={day.iso === tabbableISO ? 0 : -1}
                   aria-label={plainDateFormat(
                     day.date,

package/src/DateRangeInput/DateRangeInput.test.tsx

@@ -320,6 +320,55 @@ describe('DateRangeInput', () => {
       ).toHaveLength(0);
     });
 
+    it('returns focus to the trigger when the clear button is activated by keyboard', async () => {
+      const user = userEvent.setup();
+      function ControlledDateRangeInput() {
+        const [controlledValue, setControlledValue] =
+          useState<DateRange | null>({
+            start: '2026-01-01',
+            end: '2026-01-03',
+          });
+        return (
+          <DateRangeInput
+            label="Range"
+            value={controlledValue}
+            onChange={setControlledValue}
+          />
+        );
+      }
+      render(<ControlledDateRangeInput />);
+
+      getButton('Clear Range').focus();
+      await user.keyboard('{Enter}');
+
+      expect(queryButton('Clear Range')).not.toBeInTheDocument();
+      expect(getButton(/^Range:/)).toHaveFocus();
+    });
+
+    it('does not move focus to the trigger when the clear button is clicked', async () => {
+      const user = userEvent.setup();
+      function ControlledDateRangeInput() {
+        const [controlledValue, setControlledValue] =
+          useState<DateRange | null>({
+            start: '2026-01-01',
+            end: '2026-01-03',
+          });
+        return (
+          <DateRangeInput
+            label="Range"
+            value={controlledValue}
+            onChange={setControlledValue}
+          />
+        );
+      }
+      render(<ControlledDateRangeInput />);
+
+      await user.click(getButton('Clear Range'));
+
+      expect(queryButton('Clear Range')).not.toBeInTheDocument();
+      expect(getButton(/^Range:/)).not.toHaveFocus();
+    });
+
     it('shows clear button when hasClear is true and value exists', () => {
       const range: DateRange = {
         start: '2026-03-15',

package/src/DateRangeInput/DateRangeInput.tsx

@@ -16,7 +16,14 @@
  * - /packages/cli/assets/templates/blocks/components/DateRangeInput/ (showcase blocks)
  */
 
-import {useId, useCallback, useMemo, useOptimistic, useTransition} from 'react';
+import {
+  useId,
+  useCallback,
+  useMemo,
+  useOptimistic,
+  useRef,
+  useTransition,
+} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import {
   plainDateFromISO,
@@ -68,6 +75,7 @@ import {
 import type {SizeValue} from '../utils/types';
 import {useSize} from '../SizeContext/SizeContext';
 import {useInputStatusIcon} from '../hooks/useInputStatusIcon';
+import {useMergedRefs} from '../hooks/useMergedRefs';
 import {useResolvedRequired} from '../hooks/useResolvedRequired';
 import {themeProps} from '../utils/themeProps';
 import {focusOutlineStyles} from '../utils/focusOutline.stylex';
@@ -624,10 +632,20 @@ export function DateRangeInput({
     [fireChange, popover],
   );
 
+  const triggerRef = useRef<HTMLButtonElement>(null);
+  const triggerButtonRef = useMergedRefs<HTMLButtonElement>(triggerRef, ref);
+
   const handleClear = useCallback(
     (e: React.MouseEvent) => {
       e.stopPropagation();
       fireChange(null);
+      // A keyboard activation (detail 0) leaves focus on the clear button,
+      // which unmounts once the range is null and would drop focus to <body>;
+      // hand it to the trigger. A pointer press never focuses the button, so
+      // there is no focus to repair.
+      if (e.detail === 0) {
+        triggerRef.current?.focus();
+      }
     },
     [fireChange],
   );
@@ -713,7 +731,7 @@ export function DateRangeInput({
         </button>
         <button
           {...controlProps}
-          ref={ref}
+          ref={triggerButtonRef}
           id={id}
           type="button"
           onClick={chainEventHandlers(handleToggle, onClickProp)}