@proyecto-viviana/solidaria-components 0.4.0 → 0.5.0

package/src/DatePicker.tsx

@@ -20,13 +20,19 @@ import {
 import { Portal } from "solid-js/web";
 import {
   createDatePicker,
+  createDateField,
   createDateRangePicker,
+  createEnterAnimation,
+  createFocusRing,
+  createHover,
   createPopover,
+  mergeProps,
   FocusScope,
   useUNSAFE_PortalContext,
   type AriaDatePickerProps,
   type AriaDateRangePickerProps,
   type DatePickerState as AriaDatePickerState,
+  type PlacementAxis,
 } from "@proyecto-viviana/solidaria";
 import {
   createDateFieldState,
@@ -176,6 +182,25 @@ export interface DatePickerButtonRenderProps {
   isDisabled: boolean;
   /** Whether the calendar is open. */
   isOpen: boolean;
+  /**
+   * Whether the button is currently pressed. Provided by the single
+   * DatePicker (fed from `createDatePicker().isButtonPressed()`); the range
+   * variant does not yet publish press state, so this is optional.
+   */
+  isPressed?: boolean;
+  /**
+   * Whether the button is hovered. Fed from the trigger's own `createHover`;
+   * mirrors RAC `Button`'s `isHovered` renderProp so the styled S2
+   * `baseColor("gray-100")` hover-step background compiles into the className.
+   */
+  isHovered?: boolean;
+  /**
+   * Whether the button is keyboard-focused (focus-visible). Fed from
+   * `createFocusRing`; mirrors RAC `Button`'s `isFocusVisible` so the styled
+   * S2 `focusRing()` outline (a renderProps-gated class, not a CSS
+   * `[data-focus-visible]` selector) compiles into the className.
+   */
+  isFocusVisible?: boolean;
 }
 
 export interface DatePickerButtonProps extends SlotProps {
@@ -187,6 +212,12 @@ export interface DatePickerButtonProps extends SlotProps {
   style?: StyleOrFunction<DatePickerButtonRenderProps>;
   /** Whether the button is disabled. */
   isDisabled?: boolean;
+  /**
+   * Ref callback for the underlying button element. Mirrors S2's CalendarButton,
+   * whose `buttonRef` feeds `pressScale(buttonRef)`; the styled layer forwards a
+   * setter here so it can size the press transform against the real element.
+   */
+  ref?: (element: HTMLButtonElement) => void;
 }
 
 export interface DateRangePickerButtonProps extends DatePickerButtonProps {}
@@ -454,6 +485,23 @@ function DatePickerInner<T extends DateValue = CalendarDate>(
     isDateDisabled: stateProps.isDateDisabled,
   });
 
+  // RAC's useDatePicker re-mounts a FRESH useCalendarState every popover open
+  // and passes autoFocus:true, so useCalendarState seeds isFocused=true and the
+  // focused cell auto-focuses (useCalendarState.mjs line 80:
+  // `useState(props.autoFocus || false)`). The port SHARES one persistent
+  // calendarState across opens, so isFocused would stay whatever it last was
+  // (false after the first close). Mirror the fresh-mount behavior by flagging
+  // the shared state focused on each false->true open transition; the
+  // CalendarCell focus effect then pulls DOM focus to the value/today cell.
+  let wasOpen = false;
+  createEffect(() => {
+    const open = datePickerState.isOpen();
+    if (open && !wasOpen) {
+      calendarState.setFocused(true);
+    }
+    wasOpen = open;
+  });
+
   // Create date picker ARIA props
   const pickerAria = createDatePicker(
     () => ({
@@ -464,6 +512,18 @@ function DatePickerInner<T extends DateValue = CalendarDate>(
     fieldState as unknown as DateFieldState<DateValue>,
     overlayState as AriaDatePickerState,
     calendarState as unknown as CalendarState<DateValue>,
+    () => fieldRef(),
+  );
+
+  // The composed picker's fieldProps (stamped role="presentation") are fed
+  // through createDateField — mirroring RAC's DateField consuming
+  // useDatePicker().fieldProps. This is what actually names the segments and
+  // publishes the value description through the shared hookData WeakMap; without
+  // it the segments would be unnamed and carry no selected-date announcement.
+  const fieldAria = createDateField(
+    () => pickerAria.fieldProps,
+    fieldState as unknown as DateFieldState<DateValue>,
+    () => fieldRef(),
   );
 
   const contextValue: DatePickerContextValue = {
@@ -518,18 +578,35 @@ function DatePickerInner<T extends DateValue = CalendarDate>(
         <DateFieldContext.Provider
           value={{
             state: fieldState as unknown as DateFieldState<DateValue>,
+            // Read through getters so the DateInput/DateSegment consumers see the
+            // LIVE memo values (createDescription appends the value-description id
+            // via a deferred effect; froze snapshots would miss it). inputProps are
+            // the createDateField group props (role="presentation" here), which name
+            // the segments — NOT the raw pickerAria.fieldProps.
             aria: {
-              labelProps: pickerAria.labelProps,
-              inputProps: pickerAria.fieldProps,
-              descriptionProps: pickerAria.descriptionProps,
-              errorMessageProps: pickerAria.errorMessageProps,
+              get labelProps() {
+                return pickerAria.labelProps;
+              },
+              get inputProps() {
+                return fieldAria.fieldProps;
+              },
+              get descriptionProps() {
+                return pickerAria.descriptionProps;
+              },
+              get errorMessageProps() {
+                return pickerAria.errorMessageProps;
+              },
             },
           }}
         >
           <CalendarContext.Provider value={calendarState as unknown as CalendarState<DateValue>}>
+            {/* BARE ROLELESS root — mirrors RAC `DatePicker`'s outer `<div>`. The
+              * presentation FieldGroup shell (rendered as a child via
+              * `DatePickerFieldGroup`) is what carries `pickerAria.groupProps`
+              * (role="presentation" + label/describedby + arrow-nav/press). A
+              * described node here would be a spurious AX entry the S2 oracle lacks. */}
             <div
               ref={setFieldRef}
-              {...pickerAria.groupProps}
               class={renderProps.class()}
               style={renderProps.style()}
               data-disabled={dataAttr(fieldState.isDisabled())}
@@ -649,6 +726,10 @@ function DateRangePickerInner<T extends DateValue = CalendarDate>(
   };
 
   let triggerRef: HTMLElement | null = null;
+  // The roleless root element — scopes the shared segment focus manager and the
+  // outer arrow-navigation across BOTH fields, mirroring the single DatePicker's
+  // `fieldRef`.
+  const [fieldRef, setFieldRef] = createSignal<HTMLDivElement | null>(null);
   const overlayState = {
     get isOpen() {
       return isOpen();
@@ -683,6 +764,21 @@ function DateRangePickerInner<T extends DateValue = CalendarDate>(
     },
   });
 
+  // Mirror the single DatePicker: RAC re-mounts a FRESH useRangeCalendarState
+  // per popover open with autoFocus:true, so isFocused seeds true and the focused
+  // cell auto-focuses AND publishes its range-selection prompt describedby
+  // ("Click to start selecting date range"). The port shares one persistent
+  // range state across opens, so flag it focused on each false->true open
+  // transition to reproduce that behavior.
+  let wasRangeOpen = false;
+  createEffect(() => {
+    const open = overlayState.isOpen;
+    if (open && !wasRangeOpen) {
+      calendarState.setFocused(true);
+    }
+    wasRangeOpen = open;
+  });
+
   const isInvalid = createMemo(
     () =>
       Boolean((rest as { isInvalid?: boolean }).isInvalid) ||
@@ -767,14 +863,36 @@ function DateRangePickerInner<T extends DateValue = CalendarDate>(
     }),
     calendarState as unknown as RangeCalendarState<DateValue>,
     overlayState as AriaDatePickerState,
+    () => fieldRef(),
+  );
+
+  // Each range field's presentation field props (stamped role="presentation" +
+  // the SHARED focus manager) are fed through createDateField — mirroring RAC's
+  // two `<DateInput>`s consuming useDateRangePicker().start/endFieldProps. This
+  // names the segments ("month, Start Date" / "month, End Date") and publishes
+  // them through the shared hookData WeakMap; the shared focus manager makes arrow
+  // keys and auto-advance walk across the start/end boundary.
+  const startFieldAria = createDateField(
+    () => pickerAria.startFieldProps,
+    startFieldState as unknown as DateFieldState<DateValue>,
+    () => fieldRef(),
+  );
+  const endFieldAria = createDateField(
+    () => pickerAria.endFieldProps,
+    endFieldState as unknown as DateFieldState<DateValue>,
+    () => fieldRef(),
   );
 
   const startFieldContext: DateRangePickerFieldContextValue = {
     state: startFieldState as unknown as DateFieldState<DateValue>,
     aria: {
       labelProps: {},
+      // The DateInput group carries createDateField's fieldProps (role="presentation"
+      // + arrow-nav bubbling + unicode-bidi isolate), mirroring the standalone
+      // DateField's `inputProps ← fieldProps` mapping. NO hiddenInputProps — the
+      // range owner renders its HiddenDateInput siblings below.
       get inputProps() {
-        return pickerAria.startInputProps;
+        return startFieldAria.fieldProps;
       },
       get descriptionProps() {
         return pickerAria.descriptionProps;
@@ -790,7 +908,7 @@ function DateRangePickerInner<T extends DateValue = CalendarDate>(
     aria: {
       labelProps: {},
       get inputProps() {
-        return pickerAria.endInputProps;
+        return endFieldAria.fieldProps;
       },
       get descriptionProps() {
         return pickerAria.descriptionProps;
@@ -841,8 +959,15 @@ function DateRangePickerInner<T extends DateValue = CalendarDate>(
         <RangeCalendarContext.Provider
           value={calendarState as unknown as RangeCalendarState<DateValue>}
         >
+          {/* BARE ROLELESS root — mirrors RAC `DateRangePicker`'s outer `<div>`.
+            * The presentation FieldGroup shell (rendered as a child via the styled
+            * DateRangeDisplay) is what carries `pickerAria.groupProps` (role=
+            * "presentation" + label/describedby + outer arrow-nav/press). A described
+            * or role="group" node here would be a spurious AX entry the S2 oracle
+            * lacks. The ref scopes the shared segment focus manager across both
+            * fields (see createDateRangePicker). */}
           <div
-            {...pickerAria.groupProps}
+            ref={setFieldRef}
             class={renderProps.class()}
             style={renderProps.style()}
             data-disabled={dataAttr(calendarState.isDisabled())}
@@ -907,9 +1032,31 @@ function DateRangePickerInner<T extends DateValue = CalendarDate>(
 export function DatePickerButton(props: DatePickerButtonProps): JSX.Element {
   const context = useDatePickerContext();
 
+  // Mirror RAC's `buttonProps.isDisabled = props.isDisabled || props.isReadOnly`
+  // (a read-only picker can't open its calendar) — `createDatePicker` computes
+  // this as `isButtonDisabled()`. Reading `fieldState.isDisabled()` alone would
+  // miss the read-only case (read-only ≠ disabled on the field), so the trigger
+  // would paint enabled while the S2 oracle dims it.
+  const isDisabled = () => context.pickerAria.isButtonDisabled() || (props.isDisabled ?? false);
+
+  // Mirror RAC: the trigger is a `<Button>` whose own `useFocusRing`/`useHover`/
+  // `usePress` drive its interaction paint state. The press signal is owned by
+  // `createDatePicker` (`isButtonPressed`); focus-visible and hover are wired
+  // here so the S2 `focusRing()`/`baseColor()` selectors (`data-focus-visible`,
+  // `data-hovered`, `data-pressed`) resolve exactly as they do upstream.
+  const { isFocused, isFocusVisible, focusProps } = createFocusRing();
+  const { isHovered, hoverProps } = createHover({
+    get isDisabled() {
+      return isDisabled();
+    },
+  });
+
   const renderValues = createMemo<DatePickerButtonRenderProps>(() => ({
-    isDisabled: context.fieldState.isDisabled() || (props.isDisabled ?? false),
+    isDisabled: isDisabled(),
     isOpen: context.overlayState.isOpen,
+    isPressed: context.pickerAria.isButtonPressed(),
+    isHovered: isHovered(),
+    isFocusVisible: isFocusVisible(),
   }));
 
   const renderProps = useRenderProps(
@@ -932,17 +1079,30 @@ export function DatePickerButton(props: DatePickerButtonProps): JSX.Element {
     return props.children ?? "📅";
   };
 
+  const buttonProps = createMemo(() =>
+    mergeProps(
+      context.pickerAria.buttonProps as Record<string, unknown>,
+      focusProps as Record<string, unknown>,
+      hoverProps as Record<string, unknown>,
+    ),
+  );
+
   return (
     <button
       ref={(el) => {
         context.setTriggerRef(el);
+        props.ref?.(el);
       }}
-      {...context.pickerAria.buttonProps}
+      {...buttonProps()}
       class={renderProps.class()}
       style={renderProps.style()}
-      disabled={context.fieldState.isDisabled() || props.isDisabled}
-      data-disabled={dataAttr(context.fieldState.isDisabled() || props.isDisabled)}
+      disabled={isDisabled()}
+      data-disabled={dataAttr(isDisabled())}
       data-open={dataAttr(context.overlayState.isOpen)}
+      attr:data-hovered={isHovered() ? "true" : undefined}
+      attr:data-focused={isFocused() ? "true" : undefined}
+      attr:data-focus-visible={isFocusVisible() ? "true" : undefined}
+      attr:data-pressed={context.pickerAria.isButtonPressed() ? "true" : undefined}
     >
       {getChildren()}
     </button>
@@ -952,9 +1112,30 @@ export function DatePickerButton(props: DatePickerButtonProps): JSX.Element {
 export function DateRangePickerButton(props: DateRangePickerButtonProps): JSX.Element {
   const context = useDateRangePickerContext();
 
+  // Mirror RAC's `buttonProps.isDisabled = props.isDisabled || props.isReadOnly`
+  // (a read-only picker can't open its calendar) — `createDateRangePicker` computes
+  // this as `isButtonDisabled()`. Reading `calendarState.isDisabled()` alone would
+  // miss the read-only case, so the trigger would paint enabled while S2 dims it.
+  const isDisabled = () => context.pickerAria.isButtonDisabled() || (props.isDisabled ?? false);
+
+  // Mirror RAC: the trigger is a `<Button>` whose own `useFocusRing`/`useHover`/
+  // `usePress` drive its interaction paint state. The press signal is owned by
+  // `createDateRangePicker` (`isButtonPressed`); focus-visible and hover are wired
+  // here so the S2 `focusRing()`/`baseColor()` selectors (`data-focus-visible`,
+  // `data-hovered`, `data-pressed`) resolve exactly as they do upstream.
+  const { isFocused, isFocusVisible, focusProps } = createFocusRing();
+  const { isHovered, hoverProps } = createHover({
+    get isDisabled() {
+      return isDisabled();
+    },
+  });
+
   const renderValues = createMemo<DatePickerButtonRenderProps>(() => ({
-    isDisabled: context.calendarState.isDisabled() || (props.isDisabled ?? false),
+    isDisabled: isDisabled(),
     isOpen: context.overlayState.isOpen,
+    isPressed: context.pickerAria.isButtonPressed(),
+    isHovered: isHovered(),
+    isFocusVisible: isFocusVisible(),
   }));
 
   const renderProps = useRenderProps(
@@ -976,26 +1157,56 @@ export function DateRangePickerButton(props: DateRangePickerButtonProps): JSX.El
     return props.children ?? "📅";
   };
 
+  const buttonProps = createMemo(() =>
+    mergeProps(
+      context.pickerAria.buttonProps as Record<string, unknown>,
+      focusProps as Record<string, unknown>,
+      hoverProps as Record<string, unknown>,
+    ),
+  );
+
   return (
     <button
-      ref={(el) => context.setTriggerRef(el)}
-      {...context.pickerAria.buttonProps}
+      ref={(el) => {
+        context.setTriggerRef(el);
+        props.ref?.(el);
+      }}
+      {...buttonProps()}
       class={renderProps.class()}
       style={renderProps.style()}
-      disabled={context.calendarState.isDisabled() || props.isDisabled}
-      data-disabled={dataAttr(context.calendarState.isDisabled() || props.isDisabled)}
+      disabled={isDisabled()}
+      data-disabled={dataAttr(isDisabled())}
       data-open={dataAttr(context.overlayState.isOpen)}
+      attr:data-hovered={isHovered() ? "true" : undefined}
+      attr:data-focused={isFocused() ? "true" : undefined}
+      attr:data-focus-visible={isFocusVisible() ? "true" : undefined}
+      attr:data-pressed={context.pickerAria.isButtonPressed() ? "true" : undefined}
     >
       {getChildren()}
     </button>
   );
 }
 
+/**
+ * Render props for the popover surface, mirroring RAC `Popover`'s
+ * enter/exit/placement renderProps. The styled layer keys the S2
+ * opacity/translate enter transition on these (a renderProps-gated class, not a
+ * CSS `[data-entering]` selector).
+ */
+export interface DatePickerContentRenderProps {
+  /** Whether the popover is playing its enter transition (`data-entering`). */
+  isEntering: boolean;
+  /** Whether the popover is playing its exit transition (`data-exiting`). */
+  isExiting: boolean;
+  /** The resolved placement axis, for the direction-dependent translate. */
+  placement: PlacementAxis | null;
+}
+
 export interface DatePickerContentProps extends SlotProps {
   /** The children of the component. */
   children?: JSX.Element;
-  /** The CSS className for the element. */
-  class?: string;
+  /** The CSS className for the element, or a function of the render props. */
+  class?: string | ((renderProps: DatePickerContentRenderProps) => string);
   /** The inline style for the element. */
   style?: JSX.CSSProperties;
 }
@@ -1023,10 +1234,12 @@ export interface DatePickerDescriptionProps {
 
 export function DatePickerDescription(props: DatePickerDescriptionProps): JSX.Element {
   const context = useDatePickerContext();
+  // Rendered as <span> (→ AX role "text"), mirroring S2's <Text slot="description">
+  // and the standalone DateFieldDescription — NOT a <p> (paragraph).
   return (
-    <p {...context.pickerAria.descriptionProps} class={props.class}>
+    <span {...context.pickerAria.descriptionProps} class={props.class}>
       {props.children}
-    </p>
+    </span>
   );
 }
 
@@ -1037,10 +1250,12 @@ export interface DatePickerErrorMessageProps {
 
 export function DatePickerErrorMessage(props: DatePickerErrorMessageProps): JSX.Element {
   const context = useDatePickerContext();
+  // Rendered as <span> (→ AX role "text"), mirroring S2's <FieldError> and the
+  // standalone DateFieldErrorMessage — NOT a <p> and NOT role="alert".
   return (
-    <p {...context.pickerAria.errorMessageProps} class={props.class}>
+    <span {...context.pickerAria.errorMessageProps} class={props.class}>
       {props.children}
-    </p>
+    </span>
   );
 }
 
@@ -1065,10 +1280,12 @@ export interface DateRangePickerDescriptionProps {
 
 export function DateRangePickerDescription(props: DateRangePickerDescriptionProps): JSX.Element {
   const context = useDateRangePickerContext();
+  // Rendered as <span> (→ AX role "text"), mirroring S2's <Text slot="description">
+  // and the single DatePickerDescription — NOT a <p> (paragraph).
   return (
-    <p {...context.pickerAria.descriptionProps} class={props.class}>
+    <span {...context.pickerAria.descriptionProps} class={props.class}>
       {props.children}
-    </p>
+    </span>
   );
 }
 
@@ -1079,10 +1296,12 @@ export interface DateRangePickerErrorMessageProps {
 
 export function DateRangePickerErrorMessage(props: DateRangePickerErrorMessageProps): JSX.Element {
   const context = useDateRangePickerContext();
+  // Rendered as <span> (→ AX role "text"), mirroring S2's <FieldError> and the
+  // single DatePickerErrorMessage — NOT a <p> and NOT role="alert".
   return (
-    <p {...context.pickerAria.errorMessageProps} class={props.class}>
+    <span {...context.pickerAria.errorMessageProps} class={props.class}>
       {props.children}
-    </p>
+    </span>
   );
 }
 
@@ -1106,13 +1325,16 @@ function createEscapeDismissFallback(isOpen: () => boolean, close: () => void):
 export function DatePickerContent(props: DatePickerContentProps): JSX.Element {
   const context = useDatePickerContext();
   const portalContext = useUNSAFE_PortalContext();
-  let contentRef: HTMLDivElement | undefined;
+  // A signal (not a plain `let`) so the enter-animation effect re-runs when the
+  // section mounts on open — `createEnterAnimation` reads this to know the
+  // element exists before removing the initial `data-entering` styles.
+  const [contentRef, setContentRef] = createSignal<HTMLElement>();
   const portalContainer = () => portalContext.getContainer?.() ?? undefined;
 
   const popoverAria = createPopover(
     {
       triggerRef: () => context.triggerRef()?.parentElement ?? context.triggerRef(),
-      popoverRef: () => contentRef ?? null,
+      popoverRef: () => contentRef() ?? null,
       placement: "bottom start",
       offset: 8,
       isNonModal: false,
@@ -1128,6 +1350,35 @@ export function DatePickerContent(props: DatePickerContentProps): JSX.Element {
 
   createEscapeDismissFallback(() => context.overlayState.isOpen, context.overlayState.close);
 
+  // Mirror S2's `<Popover>` enter transition (RAC `useEnterAnimation`): the
+  // surface mounts carrying `data-entering` (opacity 0 + a small placement-ward
+  // translate), which an effect removes on the next frame so the CSS transition
+  // plays. The exit half is out of scope for this unit — the popover unmounts on
+  // close (no `isOpen || isExiting` gate), so `isExiting` stays false; only the
+  // enter motion is certified (D2).
+  const isEntering = createEnterAnimation(contentRef, () => context.overlayState.isOpen);
+
+  const renderProps = (): DatePickerContentRenderProps => ({
+    isEntering: isEntering(),
+    isExiting: false,
+    // Seed the base placement so the ENTER frame already carries the
+    // placement-ward `translate` (S2's popover motion is placement-gated:
+    // `translateY: { placement: { bottom: { isEntering: -4 } } }`). RAC resolves
+    // placement in a `useLayoutEffect` BEFORE the first paint, so no painted
+    // frame is ever null-placement; the port's positioning `createEffect` lands
+    // one frame later, so without this seed the entering frame drops `translateY`
+    // and only `opacity` transitions (D2 caught the missing translate). The
+    // desired placement is `bottom start` (see `createPopover` above), so the
+    // base axis is always `bottom` until the measure refines it.
+    placement: popoverAria.placement() ?? "bottom",
+  });
+
+  const resolvedClass = (): string => {
+    const c = props.class;
+    if (typeof c === "function") return c(renderProps());
+    return c ?? "solidaria-DatePickerContent";
+  };
+
   const cleanPopoverProps = () => {
     const {
       style: _style,
@@ -1147,28 +1398,39 @@ export function DatePickerContent(props: DatePickerContentProps): JSX.Element {
     };
   };
 
-  // Return focus to trigger when overlay closes
-  createEffect(() => {
-    const open = context.overlayState.isOpen;
-    if (!open) {
-      requestAnimationFrame(() => context.triggerRef()?.focus());
-    }
-  });
+  // Close-focus restoration is delegated to the overlay's `FocusScope`
+  // (`restoreFocus`) — exactly as RAC's DatePicker does, and as certified Select
+  // and Menu do. The prior ad-hoc effect (`if (!open) triggerRef().focus()`)
+  // fired once on mount with `open === false`, stealing focus to the trigger and
+  // painting a phantom focus ring at rest.
 
   return (
     <Show when={context.overlayState.isOpen}>
       <Portal mount={portalContainer()}>
         <FocusScope contain restoreFocus>
+          {/* Un-folded to mirror S2's `<Popover>` DOM. The OUTER role-null `<div>`
+            * is the positioned surface that carries the enter motion + chrome —
+            * this is the element RAC/S2 animate (`AriaPopover`'s div: role null, no
+            * tabindex, accessible name computed from the calendar's textContent).
+            * A nested `role="dialog"` element (RAC's `Dialog`, which S2's
+            * CalendarPopover wraps the Calendar in) carries the dialog semantics.
+            * Folding both onto one `<section role="dialog">` made D2 animate the
+            * dialog node instead of the role-null div; the role-null wrapper is
+            * pruned from the AX tree so D5/D6 are unaffected. */}
           <div
-            ref={contentRef}
+            ref={setContentRef}
             {...cleanPopoverProps()}
-            {...context.pickerAria.dialogProps}
-            tabIndex={-1}
-            class={props.class ?? "solidaria-DatePickerContent"}
+            class={resolvedClass()}
             style={mergedStyle()}
-            data-placement={popoverAria.placement() ?? undefined}
+            data-placement={popoverAria.placement() ?? "bottom"}
+            data-entering={dataAttr(isEntering())}
           >
-            {props.children}
+            {/* RAC's `Dialog` renders a `<section role="dialog">` by default — the
+              * D5 roving trail records this element's tag, so it must be `section`
+              * (a `<div>` here regressed the focus-trail tag match). */}
+            <section {...context.pickerAria.dialogProps} tabIndex={-1}>
+              {props.children}
+            </section>
           </div>
         </FocusScope>
       </Portal>
@@ -1179,13 +1441,16 @@ export function DatePickerContent(props: DatePickerContentProps): JSX.Element {
 export function DateRangePickerContent(props: DateRangePickerContentProps): JSX.Element {
   const context = useDateRangePickerContext();
   const portalContext = useUNSAFE_PortalContext();
-  let contentRef: HTMLDivElement | undefined;
+  // A signal (not a plain `let`) so the enter-animation effect re-runs when the
+  // surface mounts on open — `createEnterAnimation` reads this to know the
+  // element exists before removing the initial `data-entering` styles.
+  const [contentRef, setContentRef] = createSignal<HTMLElement>();
   const portalContainer = () => portalContext.getContainer?.() ?? undefined;
 
   const popoverAria = createPopover(
     {
       triggerRef: () => context.triggerRef()?.parentElement ?? context.triggerRef(),
-      popoverRef: () => contentRef ?? null,
+      popoverRef: () => contentRef() ?? null,
       placement: "bottom start",
       offset: 8,
       isNonModal: false,
@@ -1201,6 +1466,26 @@ export function DateRangePickerContent(props: DateRangePickerContentProps): JSX.
 
   createEscapeDismissFallback(() => context.overlayState.isOpen, context.overlayState.close);
 
+  // Mirror S2's `<Popover>` enter transition (RAC `useEnterAnimation`): the
+  // surface mounts carrying `data-entering` (opacity 0 + a small placement-ward
+  // translate), which an effect removes on the next frame so the CSS transition
+  // plays. Only the enter half is certified (D2) — the popover unmounts on close.
+  const isEntering = createEnterAnimation(contentRef, () => context.overlayState.isOpen);
+
+  const renderProps = (): DatePickerContentRenderProps => ({
+    isEntering: isEntering(),
+    isExiting: false,
+    // Seed the base placement so the ENTER frame already carries the
+    // placement-ward `translate` (see the single DatePickerContent note).
+    placement: popoverAria.placement() ?? "bottom",
+  });
+
+  const resolvedClass = (): string => {
+    const c = props.class;
+    if (typeof c === "function") return c(renderProps());
+    return c ?? "solidaria-DateRangePickerContent";
+  };
+
   const cleanPopoverProps = () => {
     const {
       style: _style,
@@ -1220,28 +1505,31 @@ export function DateRangePickerContent(props: DateRangePickerContentProps): JSX.
     };
   };
 
-  // Return focus to trigger when overlay closes
-  createEffect(() => {
-    const open = context.overlayState.isOpen;
-    if (!open) {
-      requestAnimationFrame(() => context.triggerRef()?.focus());
-    }
-  });
+  // Close-focus restoration is delegated to the overlay's `FocusScope`
+  // (`restoreFocus`) — see the single-value `DatePickerContent` note. The prior
+  // ad-hoc effect fired on mount and painted a phantom focus ring at rest.
 
   return (
     <Show when={context.overlayState.isOpen}>
       <Portal mount={portalContainer()}>
         <FocusScope contain restoreFocus>
+          {/* Un-folded to mirror S2's `<Popover>` DOM (see DatePickerContent).
+            * OUTER role-null `<div>` = positioned surface carrying the enter
+            * motion + chrome (the element RAC/S2 animate; pruned from the AX
+            * tree). Nested `<section role="dialog">` carries the dialog
+            * semantics — the D5 roving trail records this tag, so it must be
+            * `section`, not a folded `div`. */}
           <div
-            ref={contentRef}
+            ref={setContentRef}
             {...cleanPopoverProps()}
-            {...context.pickerAria.dialogProps}
-            tabIndex={-1}
-            class={props.class ?? "solidaria-DateRangePickerContent"}
+            class={resolvedClass()}
             style={mergedStyle()}
-            data-placement={popoverAria.placement() ?? undefined}
+            data-placement={popoverAria.placement() ?? "bottom"}
+            data-entering={dataAttr(isEntering())}
           >
-            {props.children}
+            <section {...context.pickerAria.dialogProps} tabIndex={-1}>
+              {props.children}
+            </section>
           </div>
         </FocusScope>
       </Portal>

package/src/DateRangePickerContext.tsx

@@ -11,6 +11,8 @@ export interface DateRangePickerFieldContextValue {
   aria: {
     labelProps: Record<string, unknown>;
     inputProps: Record<string, unknown>;
+    /** Optional hidden validation <input> props (unused by the range fields). */
+    hiddenInputProps?: Record<string, unknown>;
     descriptionProps: Record<string, unknown>;
     errorMessageProps: Record<string, unknown>;
   };

package/src/Disclosure.tsx

@@ -406,6 +406,10 @@ export function DisclosureTrigger(props: DisclosureTriggerProps): JSX.Element {
       {...mergeProps(domProps() as Record<string, unknown>, getButtonProps(), cleanFocusProps())}
       ref={(el) => assignRef(local.ref, el)}
       type="button"
+      // Mirror react-aria's `useFocusable` (useFocusable.tsx:114-118): always emit
+      // an explicit tabIndex so the native trigger is a real, discoverable tab stop
+      // (Safari won't focus a native button otherwise). Disabled → attribute absent.
+      tabindex={isDisabled() ? undefined : 0}
       class={local.class}
       style={local.style}
       data-expanded={dataAttr(isExpanded())}