@skdx/react 0.26.0 → 0.28.0

package/dist/date-picker/primitives.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Advanced primitives for `DatePicker` — the parts the recipe composes.
+ *
+ * @example
+ * ```tsx
+ * import { DatePicker, DatePickerCalendar, DatePickerClose, DatePickerContent, DatePickerPortal, DatePickerTrigger } from '@skdx/react/primitives/date-picker';
+ *
+ * <DatePicker value={date} onValueChange={setDate}>
+ *   <DatePickerTrigger>Pick a date</DatePickerTrigger>
+ *   <DatePickerPortal>
+ *     <DatePickerContent>
+ *       <DatePickerCalendar />
+ *       <DatePickerClose>Done</DatePickerClose>
+ *     </DatePickerContent>
+ *   </DatePickerPortal>
+ * </DatePicker>
+ * ```
+ */
+export { DatePicker } from './DatePicker.js';
+export { DatePickerCalendar } from './DatePickerCalendar.js';
+export { DatePickerClose } from './DatePickerClose.js';
+export { DatePickerContent } from './DatePickerContent.js';
+export { DatePickerInput } from './DatePickerInput.js';
+export { DatePickerPortal } from './DatePickerPortal.js';
+export { DatePickerTimeField } from './DatePickerTimeField.js';
+export { DatePickerTrigger } from './DatePickerTrigger.js';
+export type { DatePickerCalendarProps, DatePickerCloseProps, DatePickerContentProps, DatePickerHandle, DatePickerInputProps, DatePickerPortalProps, DatePickerProps, DatePickerTimeFieldProps, DatePickerTriggerProps, } from './types.js';

package/dist/date-picker/types.d.cts

@@ -1,192 +1,198 @@
 import type * as React from 'react';
-import type { CalendarProps, CalendarSelectionMode, CalendarValue } from '../calendar/index.cjs';
+import type { CalendarProps, CalendarSelectionMode, CalendarValue, CalendarValueInput } from '../calendar/index.cjs';
 import type { DateFieldProps } from '../date-field/index.cjs';
 import type { TimeFieldProps } from '../time-field/index.cjs';
 import type { Granularity } from '../utils/dateSegments.cjs';
 import type { FormValidityHandle } from '../utils/formControl.cjs';
+import type { PassThroughProps } from '../utils/passThrough.cjs';
 import type { PopperContentProps } from '../utils/popper.cjs';
 import type { PortalProps } from '../utils/portal.cjs';
 import type { PrimitivePropsWithRef } from '../utils/primitive.cjs';
 import type { FocusOutsideEvent, InteractOutsideEvent } from '../utils/useDismiss.cjs';
+import type { AutoFocusEvent } from '../utils/useFocusTrap.cjs';
 /** @internal Shared state distributed from {@link DatePicker} to its parts via context. Not part of the public API. */
 export interface DatePickerContextValue {
     triggerRef: React.RefObject<HTMLButtonElement | null>;
     contentRef: React.RefObject<HTMLDivElement | null>;
     contentId: string;
+    triggerId: string;
     value: CalendarValue;
     selectionMode: CalendarSelectionMode;
     granularity: Granularity;
+    /** Whether a completed selection dismisses the popup. */
+    closeOnSelect: boolean;
     onValueChange: (value: CalendarValue) => void;
     open: boolean;
     onOpenChange: (open: boolean) => void;
     disabled: boolean;
+    /** Whether all editable parts refuse edits but stay focusable. */
+    readOnly: boolean;
+    /** Whether picker paints as failing validation. */
+    invalid: boolean;
 }
-/** Props for the {@link DatePicker} root. */
-export interface DatePickerProps {
+/** Props for the {@link DatePicker} root. Standard attributes ({@link PassThroughProps}) land on the derived `DatePickerTrigger`. */
+export interface DatePickerProps extends PassThroughProps {
     /**
-     * The trigger and portal — the popup's own DOM (calendar, close button) is
-     * rendered by {@link DatePickerPortal} elsewhere.
-     * @default undefined — renders nothing if omitted.
+     * Replaces derived anatomy entirely; omitted, derives trigger, portal, popup, calendar, fields.
+     * @default undefined
      */
     children?: React.ReactNode;
     /**
-     * How many dates the composed calendar selects at once, which decides the
-     * shape of `value` — see {@link CalendarSelectionMode}. Also decides when
-     * the popup auto-closes: immediately in `single`, once the range is closed
-     * in `range`, never in `multiple`.
+     * Derived trigger placeholder (ignored when `children` replaces anatomy).
+     * @default 'Select date'
+     */
+    placeholder?: string;
+    /**
+     * BCP 47 locale tag for trigger formatting (ignored when `children` replaces).
+     * @default undefined — runtime's default.
+     */
+    locale?: string;
+    /**
+     * Whether derived popup includes typed-entry date field (single-mode only).
+     * @default false
+     */
+    showInput?: boolean;
+    /**
+     * How many dates calendar selects (decides `value` shape and auto-close).
      * @default 'single'
      */
     selectionMode?: CalendarSelectionMode;
     /**
-     * How precise the selected value is, forwarded to `DatePickerInput` and
-     * `DatePickerTimeField`. Anything past `'day'` puts the picker in date-time
-     * mode: the popup no longer closes on a calendar selection, because the user
-     * still has a time to set.
+     * Value precision; past `'day'` puts picker in date-time mode.
      * @default 'day'
      */
     granularity?: Granularity;
     /**
-     * Current selection, for controlled usage. Pair with `onValueChange`. Its
-     * shape follows `selectionMode`.
-     * @default undefined — uncontrolled, tracks its own selection internally.
+     * Current selection for controlled usage; shape follows `selectionMode` (ISO-8601 strings also accepted).
+     * @default undefined — uncontrolled.
      */
-    value?: CalendarValue;
+    value?: CalendarValueInput;
     /**
-     * Initial selection, for uncontrolled usage. Its shape follows `selectionMode`.
-     * @default undefined — nothing selected.
+     * Initial selection for uncontrolled usage (same shape and forms as `value`).
+     * @default undefined
      */
-    defaultValue?: CalendarValue;
+    defaultValue?: CalendarValueInput;
     /**
-     * Fires with the whole new selection whenever it changes.
-     * @default undefined — no-op if omitted.
+     * Fires with new selection when changed.
+     * @default undefined — no-op.
      */
     onValueChange?: (value: CalendarValue) => void;
     /**
-     * Whether the popup is open, for controlled usage. Pair with `onOpenChange`.
-     * @default undefined — uncontrolled, tracks its own open state internally.
+     * Whether popup is open for controlled usage; pair with `onOpenChange`.
+     * @default undefined — uncontrolled.
      */
     open?: boolean;
     /**
-     * Initial open state, for uncontrolled usage.
+     * Initial open state for uncontrolled usage.
      * @default false
      */
     defaultOpen?: boolean;
     /**
-     * Fires with the new open state whenever it changes, controlled or not.
-     * @default undefined — no-op if omitted.
+     * Fires with new open state on change.
+     * @default undefined — no-op.
      */
     onOpenChange?: (open: boolean) => void;
     /**
-     * Fires with the new open state once the change has finished on screen —
-     * after `DatePickerContent`'s enter or exit animation ends, or as soon as it
-     * has settled when the popup declares no animation. Use it for work that must
-     * not race the transition; use `onOpenChange` for work that must not wait for it.
-     * @default undefined — no-op if omitted.
+     * Fires once open-state change finishes (after animation ends).
+     * @default undefined — no-op.
      */
     onOpenChangeComplete?: (open: boolean) => void;
     /**
-     * Form field name. The selection is submitted under it as local-time
-     * `YYYY-MM-DD` strings, exactly like `<input type="date">` — one entry in
-     * `single` mode, one entry per date in `multiple`, and start then end (two
-     * entries under the same name) in `range`.
-     * @default undefined — the picker submits nothing.
+     * Form field name; selection submits as local-time `YYYY-MM-DD` strings like `<input type="date">`.
+     * @default undefined
      */
     name?: string;
     /**
-     * Marks the picker required: with nothing selected it reports `valueMissing`
-     * and blocks submission. A range still anchored on its start counts as
-     * nothing selected. Only meaningful alongside `name`.
+     * Form id picker submits into (only meaningful with `name`).
+     * @default undefined
+     */
+    form?: string;
+    /**
+     * Marks picker required; reports `valueMissing` and blocks submission without selection.
      * @default false
      */
     required?: boolean;
     /**
-     * Disables the trigger and prevents the popup opening — including through
-     * `open`/`defaultOpen`, since a disabled control that can still be driven
-     * open from a prop is not disabled.
-     *
-     * Mirrors `Select` and `TreeSelect`, whose triggers share `_trigger.css`'s
-     * disabled treatment with this one and reach it through the same
-     * `data-disabled` the trigger publishes.
+     * Disables trigger and prevents popup opening.
      * @default false
      */
     disabled?: boolean;
+    /**
+     * Whether completed selection dismisses popup (single immediate, range once second date, never multiple).
+     * @default true
+     */
+    closeOnSelect?: boolean;
+    /**
+     * Makes picker non-editable; trigger still opens, everything focusable, no selection changes.
+     * @default false
+     */
+    readOnly?: boolean;
+    /**
+     * Marks picker invalid (`data-invalid` on trigger/content, `aria-invalid="true"` on trigger).
+     * @default false
+     */
+    invalid?: boolean;
 }
-/** Props for {@link DatePickerTrigger}, the button that opens/closes the popup. */
+/** Props for {@link DatePickerTrigger}}, button opening/closing popup. */
 export interface DatePickerTriggerProps extends PrimitivePropsWithRef<'button'> {
 }
-/** Props for {@link DatePickerPortal}, which teleports its content to `document.body` while open. */
+/** Props for {@link DatePickerPortal}}, teleports content to `document.body` while open. */
 export interface DatePickerPortalProps extends PortalProps {
     /**
-     * Render (and mount `DatePickerContent`) even while closed, instead of
-     * unmounting. Useful for animation libraries that need the outgoing
-     * content present in the DOM during an exit transition.
+     * Keep portal mounted while closed (useful for animation libraries needing outgoing content during exit).
      * @default false
      */
     forceMount?: boolean;
 }
-/**
- * Props for {@link DatePickerContent}, the popup panel. Extends
- * {@link PopperContentProps} (`side`, `align`, `sideOffset`, `alignOffset`,
- * `avoidCollisions`, `collisionPadding`) for floating-ui positioning relative
- * to the trigger — note `DatePickerContent` defaults `sideOffset` to `4`
- * instead of the popper base default of `0`.
- */
+/** Props for {@link DatePickerContent}}, popup panel (extends popper positioning, `sideOffset` defaults to 4). */
 export interface DatePickerContentProps extends PopperContentProps {
     /**
-     * Keep this panel mounted even while closed, instead of unmounting it.
+     * Keep panel mounted even while popup is closed.
      * @default false
      */
     forceMount?: boolean;
     /**
-     * Called when Escape is pressed while the content has focus; closes the popup unless `event.preventDefault()` is called.
-     * @default undefined — no-op if omitted.
+     * Fires on Escape (call `preventDefault()` to prevent close).
+     * @default undefined — no-op.
      */
     onEscapeKeyDown?: (event: KeyboardEvent) => void;
     /**
-     * Called on pointerdown outside the content; closes the popup unless `event.preventDefault()` is called.
-     * @default undefined — no-op if omitted.
+     * Fires on pointerdown outside (call `preventDefault()` to prevent close).
+     * @default undefined — no-op.
      */
     onPointerDownOutside?: (event: PointerEvent) => void;
     /**
-     * Called when focus moves to an element outside the content; closes the popup unless `event.preventDefault()` is called. Receives a cancelable stand-in carrying the original `focusin` as its `detail`, since `focusin` itself cannot be canceled.
-     * @default undefined — no-op if omitted.
+     * Fires on focus outside (call `preventDefault()` to prevent close; receives cancelable stand-in).
+     * @default undefined — no-op.
      */
     onFocusOutside?: (event: FocusOutsideEvent) => void;
     /**
-     * Called for either kind of outside interaction — pointerdown or focus — immediately before the specific handler above and with the same event, so one `event.preventDefault()` here vetoes the dismissal whichever way it was triggered.
-     * @default undefined — no-op if omitted.
+     * Fires for any outside interaction before specific handler.
+     * @default undefined — no-op.
      */
     onInteractOutside?: (event: InteractOutsideEvent) => void;
+    /**
+     * Fires before focus moves into popup on open (to selected date or today; call `preventDefault()` to prevent).
+     * @default undefined — no-op.
+     */
+    onOpenAutoFocus?: (event: AutoFocusEvent) => void;
+    /**
+     * Fires before focus returns to trigger on inside close (call `preventDefault()` to suppress; not fired for outside dismissal).
+     * @default undefined — no-op.
+     */
+    onCloseAutoFocus?: (event: AutoFocusEvent) => void;
 }
-/**
- * Props for {@link DatePickerCalendar} — identical to {@link CalendarProps},
- * minus the wiring `DatePickerCalendar` provides itself
- * (`value`/`onValueChange`/`selectionMode`, all owned by the `DatePicker`
- * root).
- */
+/** Props for {@link DatePickerCalendar}}, like {@link CalendarProps}} minus root-owned wiring. */
 export interface DatePickerCalendarProps extends Omit<CalendarProps, 'value' | 'onValueChange' | 'selectionMode'> {
 }
-/** Props for {@link DatePickerClose}, a button that closes the popup without changing the selection. */
+/** Props for {@link DatePickerClose}}, button closing popup without changing selection. */
 export interface DatePickerCloseProps extends PrimitivePropsWithRef<'button'> {
 }
-/**
- * Props for {@link DatePickerInput} — identical to {@link DateFieldProps},
- * minus the wiring `DatePickerInput` provides itself
- * (`value`/`onValueChange`/`granularity`, all owned by the `DatePicker` root).
- */
+/** Props for {@link DatePickerInput}}, like {@link DateFieldProps}} minus root-owned wiring. */
 export interface DatePickerInputProps extends Omit<DateFieldProps, 'value' | 'defaultValue' | 'onValueChange' | 'granularity'> {
 }
-/**
- * Props for {@link DatePickerTimeField} — identical to {@link TimeFieldProps},
- * minus the wiring `DatePickerTimeField` provides itself
- * (`value`/`onValueChange`/`granularity`).
- */
+/** Props for {@link DatePickerTimeField}}, like {@link TimeFieldProps}} minus component-owned wiring. */
 export interface DatePickerTimeFieldProps extends Omit<TimeFieldProps, 'value' | 'defaultValue' | 'onValueChange' | 'granularity'> {
 }
-/**
- * What {@link DatePicker}'s forwarded ref carries. The root renders no DOM of
- * its own besides its mirrored inputs, so the ref is these two
- * constraint-validation methods and nothing else —
- * `React.useRef<DatePickerHandle>(null)`.
- */
+/** {@link DatePicker}}'s forwarded ref (root renders no DOM beyond mirrored inputs, just constraint-validation methods). */
 export type DatePickerHandle = FormValidityHandle;

package/dist/date-picker/types.d.ts

@@ -1,192 +1,198 @@
 import type * as React from 'react';
-import type { CalendarProps, CalendarSelectionMode, CalendarValue } from '../calendar/index.js';
+import type { CalendarProps, CalendarSelectionMode, CalendarValue, CalendarValueInput } from '../calendar/index.js';
 import type { DateFieldProps } from '../date-field/index.js';
 import type { TimeFieldProps } from '../time-field/index.js';
 import type { Granularity } from '../utils/dateSegments.js';
 import type { FormValidityHandle } from '../utils/formControl.js';
+import type { PassThroughProps } from '../utils/passThrough.js';
 import type { PopperContentProps } from '../utils/popper.js';
 import type { PortalProps } from '../utils/portal.js';
 import type { PrimitivePropsWithRef } from '../utils/primitive.js';
 import type { FocusOutsideEvent, InteractOutsideEvent } from '../utils/useDismiss.js';
+import type { AutoFocusEvent } from '../utils/useFocusTrap.js';
 /** @internal Shared state distributed from {@link DatePicker} to its parts via context. Not part of the public API. */
 export interface DatePickerContextValue {
     triggerRef: React.RefObject<HTMLButtonElement | null>;
     contentRef: React.RefObject<HTMLDivElement | null>;
     contentId: string;
+    triggerId: string;
     value: CalendarValue;
     selectionMode: CalendarSelectionMode;
     granularity: Granularity;
+    /** Whether a completed selection dismisses the popup. */
+    closeOnSelect: boolean;
     onValueChange: (value: CalendarValue) => void;
     open: boolean;
     onOpenChange: (open: boolean) => void;
     disabled: boolean;
+    /** Whether all editable parts refuse edits but stay focusable. */
+    readOnly: boolean;
+    /** Whether picker paints as failing validation. */
+    invalid: boolean;
 }
-/** Props for the {@link DatePicker} root. */
-export interface DatePickerProps {
+/** Props for the {@link DatePicker} root. Standard attributes ({@link PassThroughProps}) land on the derived `DatePickerTrigger`. */
+export interface DatePickerProps extends PassThroughProps {
     /**
-     * The trigger and portal — the popup's own DOM (calendar, close button) is
-     * rendered by {@link DatePickerPortal} elsewhere.
-     * @default undefined — renders nothing if omitted.
+     * Replaces derived anatomy entirely; omitted, derives trigger, portal, popup, calendar, fields.
+     * @default undefined
      */
     children?: React.ReactNode;
     /**
-     * How many dates the composed calendar selects at once, which decides the
-     * shape of `value` — see {@link CalendarSelectionMode}. Also decides when
-     * the popup auto-closes: immediately in `single`, once the range is closed
-     * in `range`, never in `multiple`.
+     * Derived trigger placeholder (ignored when `children` replaces anatomy).
+     * @default 'Select date'
+     */
+    placeholder?: string;
+    /**
+     * BCP 47 locale tag for trigger formatting (ignored when `children` replaces).
+     * @default undefined — runtime's default.
+     */
+    locale?: string;
+    /**
+     * Whether derived popup includes typed-entry date field (single-mode only).
+     * @default false
+     */
+    showInput?: boolean;
+    /**
+     * How many dates calendar selects (decides `value` shape and auto-close).
      * @default 'single'
      */
     selectionMode?: CalendarSelectionMode;
     /**
-     * How precise the selected value is, forwarded to `DatePickerInput` and
-     * `DatePickerTimeField`. Anything past `'day'` puts the picker in date-time
-     * mode: the popup no longer closes on a calendar selection, because the user
-     * still has a time to set.
+     * Value precision; past `'day'` puts picker in date-time mode.
      * @default 'day'
      */
     granularity?: Granularity;
     /**
-     * Current selection, for controlled usage. Pair with `onValueChange`. Its
-     * shape follows `selectionMode`.
-     * @default undefined — uncontrolled, tracks its own selection internally.
+     * Current selection for controlled usage; shape follows `selectionMode` (ISO-8601 strings also accepted).
+     * @default undefined — uncontrolled.
      */
-    value?: CalendarValue;
+    value?: CalendarValueInput;
     /**
-     * Initial selection, for uncontrolled usage. Its shape follows `selectionMode`.
-     * @default undefined — nothing selected.
+     * Initial selection for uncontrolled usage (same shape and forms as `value`).
+     * @default undefined
      */
-    defaultValue?: CalendarValue;
+    defaultValue?: CalendarValueInput;
     /**
-     * Fires with the whole new selection whenever it changes.
-     * @default undefined — no-op if omitted.
+     * Fires with new selection when changed.
+     * @default undefined — no-op.
      */
     onValueChange?: (value: CalendarValue) => void;
     /**
-     * Whether the popup is open, for controlled usage. Pair with `onOpenChange`.
-     * @default undefined — uncontrolled, tracks its own open state internally.
+     * Whether popup is open for controlled usage; pair with `onOpenChange`.
+     * @default undefined — uncontrolled.
      */
     open?: boolean;
     /**
-     * Initial open state, for uncontrolled usage.
+     * Initial open state for uncontrolled usage.
      * @default false
      */
     defaultOpen?: boolean;
     /**
-     * Fires with the new open state whenever it changes, controlled or not.
-     * @default undefined — no-op if omitted.
+     * Fires with new open state on change.
+     * @default undefined — no-op.
      */
     onOpenChange?: (open: boolean) => void;
     /**
-     * Fires with the new open state once the change has finished on screen —
-     * after `DatePickerContent`'s enter or exit animation ends, or as soon as it
-     * has settled when the popup declares no animation. Use it for work that must
-     * not race the transition; use `onOpenChange` for work that must not wait for it.
-     * @default undefined — no-op if omitted.
+     * Fires once open-state change finishes (after animation ends).
+     * @default undefined — no-op.
      */
     onOpenChangeComplete?: (open: boolean) => void;
     /**
-     * Form field name. The selection is submitted under it as local-time
-     * `YYYY-MM-DD` strings, exactly like `<input type="date">` — one entry in
-     * `single` mode, one entry per date in `multiple`, and start then end (two
-     * entries under the same name) in `range`.
-     * @default undefined — the picker submits nothing.
+     * Form field name; selection submits as local-time `YYYY-MM-DD` strings like `<input type="date">`.
+     * @default undefined
      */
     name?: string;
     /**
-     * Marks the picker required: with nothing selected it reports `valueMissing`
-     * and blocks submission. A range still anchored on its start counts as
-     * nothing selected. Only meaningful alongside `name`.
+     * Form id picker submits into (only meaningful with `name`).
+     * @default undefined
+     */
+    form?: string;
+    /**
+     * Marks picker required; reports `valueMissing` and blocks submission without selection.
      * @default false
      */
     required?: boolean;
     /**
-     * Disables the trigger and prevents the popup opening — including through
-     * `open`/`defaultOpen`, since a disabled control that can still be driven
-     * open from a prop is not disabled.
-     *
-     * Mirrors `Select` and `TreeSelect`, whose triggers share `_trigger.css`'s
-     * disabled treatment with this one and reach it through the same
-     * `data-disabled` the trigger publishes.
+     * Disables trigger and prevents popup opening.
      * @default false
      */
     disabled?: boolean;
+    /**
+     * Whether completed selection dismisses popup (single immediate, range once second date, never multiple).
+     * @default true
+     */
+    closeOnSelect?: boolean;
+    /**
+     * Makes picker non-editable; trigger still opens, everything focusable, no selection changes.
+     * @default false
+     */
+    readOnly?: boolean;
+    /**
+     * Marks picker invalid (`data-invalid` on trigger/content, `aria-invalid="true"` on trigger).
+     * @default false
+     */
+    invalid?: boolean;
 }
-/** Props for {@link DatePickerTrigger}, the button that opens/closes the popup. */
+/** Props for {@link DatePickerTrigger}}, button opening/closing popup. */
 export interface DatePickerTriggerProps extends PrimitivePropsWithRef<'button'> {
 }
-/** Props for {@link DatePickerPortal}, which teleports its content to `document.body` while open. */
+/** Props for {@link DatePickerPortal}}, teleports content to `document.body` while open. */
 export interface DatePickerPortalProps extends PortalProps {
     /**
-     * Render (and mount `DatePickerContent`) even while closed, instead of
-     * unmounting. Useful for animation libraries that need the outgoing
-     * content present in the DOM during an exit transition.
+     * Keep portal mounted while closed (useful for animation libraries needing outgoing content during exit).
      * @default false
      */
     forceMount?: boolean;
 }
-/**
- * Props for {@link DatePickerContent}, the popup panel. Extends
- * {@link PopperContentProps} (`side`, `align`, `sideOffset`, `alignOffset`,
- * `avoidCollisions`, `collisionPadding`) for floating-ui positioning relative
- * to the trigger — note `DatePickerContent` defaults `sideOffset` to `4`
- * instead of the popper base default of `0`.
- */
+/** Props for {@link DatePickerContent}}, popup panel (extends popper positioning, `sideOffset` defaults to 4). */
 export interface DatePickerContentProps extends PopperContentProps {
     /**
-     * Keep this panel mounted even while closed, instead of unmounting it.
+     * Keep panel mounted even while popup is closed.
      * @default false
      */
     forceMount?: boolean;
     /**
-     * Called when Escape is pressed while the content has focus; closes the popup unless `event.preventDefault()` is called.
-     * @default undefined — no-op if omitted.
+     * Fires on Escape (call `preventDefault()` to prevent close).
+     * @default undefined — no-op.
      */
     onEscapeKeyDown?: (event: KeyboardEvent) => void;
     /**
-     * Called on pointerdown outside the content; closes the popup unless `event.preventDefault()` is called.
-     * @default undefined — no-op if omitted.
+     * Fires on pointerdown outside (call `preventDefault()` to prevent close).
+     * @default undefined — no-op.
      */
     onPointerDownOutside?: (event: PointerEvent) => void;
     /**
-     * Called when focus moves to an element outside the content; closes the popup unless `event.preventDefault()` is called. Receives a cancelable stand-in carrying the original `focusin` as its `detail`, since `focusin` itself cannot be canceled.
-     * @default undefined — no-op if omitted.
+     * Fires on focus outside (call `preventDefault()` to prevent close; receives cancelable stand-in).
+     * @default undefined — no-op.
      */
     onFocusOutside?: (event: FocusOutsideEvent) => void;
     /**
-     * Called for either kind of outside interaction — pointerdown or focus — immediately before the specific handler above and with the same event, so one `event.preventDefault()` here vetoes the dismissal whichever way it was triggered.
-     * @default undefined — no-op if omitted.
+     * Fires for any outside interaction before specific handler.
+     * @default undefined — no-op.
      */
     onInteractOutside?: (event: InteractOutsideEvent) => void;
+    /**
+     * Fires before focus moves into popup on open (to selected date or today; call `preventDefault()` to prevent).
+     * @default undefined — no-op.
+     */
+    onOpenAutoFocus?: (event: AutoFocusEvent) => void;
+    /**
+     * Fires before focus returns to trigger on inside close (call `preventDefault()` to suppress; not fired for outside dismissal).
+     * @default undefined — no-op.
+     */
+    onCloseAutoFocus?: (event: AutoFocusEvent) => void;
 }
-/**
- * Props for {@link DatePickerCalendar} — identical to {@link CalendarProps},
- * minus the wiring `DatePickerCalendar` provides itself
- * (`value`/`onValueChange`/`selectionMode`, all owned by the `DatePicker`
- * root).
- */
+/** Props for {@link DatePickerCalendar}}, like {@link CalendarProps}} minus root-owned wiring. */
 export interface DatePickerCalendarProps extends Omit<CalendarProps, 'value' | 'onValueChange' | 'selectionMode'> {
 }
-/** Props for {@link DatePickerClose}, a button that closes the popup without changing the selection. */
+/** Props for {@link DatePickerClose}}, button closing popup without changing selection. */
 export interface DatePickerCloseProps extends PrimitivePropsWithRef<'button'> {
 }
-/**
- * Props for {@link DatePickerInput} — identical to {@link DateFieldProps},
- * minus the wiring `DatePickerInput` provides itself
- * (`value`/`onValueChange`/`granularity`, all owned by the `DatePicker` root).
- */
+/** Props for {@link DatePickerInput}}, like {@link DateFieldProps}} minus root-owned wiring. */
 export interface DatePickerInputProps extends Omit<DateFieldProps, 'value' | 'defaultValue' | 'onValueChange' | 'granularity'> {
 }
-/**
- * Props for {@link DatePickerTimeField} — identical to {@link TimeFieldProps},
- * minus the wiring `DatePickerTimeField` provides itself
- * (`value`/`onValueChange`/`granularity`).
- */
+/** Props for {@link DatePickerTimeField}}, like {@link TimeFieldProps}} minus component-owned wiring. */
 export interface DatePickerTimeFieldProps extends Omit<TimeFieldProps, 'value' | 'defaultValue' | 'onValueChange' | 'granularity'> {
 }
-/**
- * What {@link DatePicker}'s forwarded ref carries. The root renders no DOM of
- * its own besides its mirrored inputs, so the ref is these two
- * constraint-validation methods and nothing else —
- * `React.useRef<DatePickerHandle>(null)`.
- */
+/** {@link DatePicker}}'s forwarded ref (root renders no DOM beyond mirrored inputs, just constraint-validation methods). */
 export type DatePickerHandle = FormValidityHandle;