@xsolla/xui-date-picker 0.218.1 → 0.219.0

package/README.md

@@ -95,11 +95,15 @@ const [date, setDate] = useState<Date | null>(null);
 | `startDate` | `Date \| null` | — | Range start date. |
 | `endDate` | `Date \| null` | — | Range end date. |
 | `selectsRange` | `boolean` | `false` | Enable range selection. |
-| `onChange` | `(date: Date \| DateRangeType) => void` | — | Fired when the date or range changes. |
+| `onChange` | `(date: Date \| DateRangeType) => void` | — | Fired when the date or range changes. Range mode also reports an emptied range as `[null, null]`; single mode never reports "no date" here — see [Clearing](#clearing). |
+| `label` | `string` | — | Label rendered above the field, in the same style as `Select`'s label. |
 | `placeholder` | `string` | `'Choose a date'` / `'Choose a date range'` | Placeholder for the input, shown while it is empty. Not derived from `dateFormat`. |
 | `dateFormat` | `string` | `'MM/dd/yyyy'` | `date-fns` format used to render and parse the field. Numeric tokens only — see [Date formats](#date-formats). |
 | `size` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | `'md'` | Input size. |
 | `disabled` | `boolean` | `false` | Disable the input. |
+| `readOnly` | `boolean` | `false` | The field can open the calendar but not be edited. |
+| `clearable` | `boolean` | `false` | Show a clear (✕) control inside the field once it holds a value — see [Clearing](#clearing). |
+| `onClear` | `() => void` | — | Fired after the `clearable` control empties the field. The only clear signal in single-date mode. |
 | `backgroundColor` | `string` | — | Custom background colour for the input. |
 | `dropdownPosition` | `'left' \| 'right'` | `'left'` | **Deprecated** — use the alignment suffix on `placement` (`dropdownPosition="right"` → `placement="bottom-end"`). Still honoured as a fallback when `placement` has no suffix. |
 | `placement` | `DatePickerPlacement` | auto | Where the calendar opens, as `{side}[-alignment]` — same `{side}-{start\|center\|end}` convention as `ContextMenuPlacement`. A bare side aligns to `start`. When omitted, the calendar measures viewport space on open and auto-flips, preferring `bottom` → `top` → `left` → `right`, also flipping the cross-axis edge to stay on screen. When set, it always opens at that placement. Web only. |
@@ -124,6 +128,39 @@ const [date, setDate] = useState<Date | null>(null);
 
 Inherits `ThemeOverrideProps` (`themeMode`, `themeProductContext`).
 
+### Clearing
+
+`clearable` adds a clear (✕) control inside the field, to the left of the calendar icon. It appears once the field holds a value and is suppressed while the field is `disabled` or `readOnly`.
+
+**The clear signal differs by mode.** Range mode can express an empty value in `onChange` — it already reports half-picked ranges as `[start, end]` with nulls — so clearing fires `onChange([null, null])`. Single mode cannot: `onChange` takes a `Date`, and widening it to `Date | null` would break the handler signature of every existing consumer. Clearing a single date therefore fires **`onClear` only**. Wire `onClear` whenever you pass `clearable` in single mode, or the clear will not reach your state.
+
+```tsx
+const [date, setDate] = useState<Date | null>(new Date());
+
+<DatePicker
+  clearable
+  label="Published date"
+  selectedDate={date}
+  onChange={(d) => setDate(d as Date)}
+  onClear={() => setDate(null)}
+/>;
+```
+
+```tsx
+const [range, setRange] = useState<DateRangeType>([null, null]);
+
+<DatePicker
+  variant="dual"
+  clearable
+  label="Report period"
+  startDate={range[0]}
+  endDate={range[1]}
+  onChange={(value) => setRange(value as DateRangeType)}
+/>;
+```
+
+A cleared field stays empty until the props change or the user types again — blur does not put the previous value back. The same holds for a value you clear **from outside** while the calendar is open: the field adopts it on blur rather than re-emitting the date it was showing.
+
 ### Date formats
 
 The field is edited segment by segment (type digits, arrow-step a segment, tab between them), so `dateFormat` supports **numeric tokens only** — exactly three, in any order, with anything between them treated as a literal separator:
@@ -338,3 +375,4 @@ const [date, setDate] = useState<Date | null>(null);
 - Calendar dates are navigable via keyboard; selected dates are announced to screen readers.
 - Focus is restored to the input when the calendar closes.
 - Dates outside `minDate`/`maxDate` are disabled.
+- The clear control is a real `button` with its own focus stop; clearing keeps focus on the field.

package/native/index.d.mts

@@ -38,12 +38,24 @@ interface DatePickerProps extends Omit<CalendarProps, "onChange"> {
      * {@link DateRangeType} tuple whenever the picker is in range mode
      * (`variant="dual"` or `selectsRange`). Either side of the tuple can be
      * `null` while a range is only half-picked.
+     *
+     * Note the asymmetry when the field is emptied via {@link clearable}: range
+     * mode reports `[null, null]` here, but single mode has no `null` in this
+     * signature, so use {@link onClear} to observe a single-date clear.
      */
     onChange?: (date: Date | DateRangeType) => void;
     /**
      * Placeholder text for the input
      */
     placeholder?: string;
+    /**
+     * Label rendered above the field, in the same style as `Select`'s label.
+     *
+     * Forwarded to the underlying `Input`. It used to work only by accident —
+     * unknown props were spread onto the field — which meant consumers had to
+     * cast to pass it, and it also leaked onto the calendar overlay (XUITSD-97).
+     */
+    label?: string;
     /** `date-fns` format for the field, defaulting to `"MM/dd/yyyy"`. Numeric `d`/`dd`, `M`/`MM` and `y`/`yyyy` tokens only, in any order (mind the casing — `mm` is minutes); anything else warns in development and falls back to the default. */
     dateFormat?: string;
     /**
@@ -67,6 +79,23 @@ interface DatePickerProps extends Omit<CalendarProps, "onChange"> {
      * Optional leading icon shown inside the field.
      */
     iconLeft?: ReactNode;
+    /**
+     * Shows a clear (✕) control inside the field, to the left of the calendar
+     * icon, whenever the field holds a value. Works in single and range mode,
+     * and is suppressed while the field is `disabled` or `readOnly`.
+     *
+     * Clearing empties the field, drops any active chip, and reports the new
+     * value: range mode fires `onChange([null, null])`; single mode fires
+     * {@link onClear} only, because `onChange` cannot express "no date". The
+     * cleared field is not reverted on blur — it stands until the props change.
+     */
+    clearable?: boolean;
+    /**
+     * Called when the field is emptied via the {@link clearable} control, after
+     * the field has been cleared. This is the only clear signal in single-date
+     * mode; in range mode `onChange([null, null])` fires as well.
+     */
+    onClear?: () => void;
     /**
      * Highlights the field as invalid (error state).
      */

package/native/index.d.ts

@@ -38,12 +38,24 @@ interface DatePickerProps extends Omit<CalendarProps, "onChange"> {
      * {@link DateRangeType} tuple whenever the picker is in range mode
      * (`variant="dual"` or `selectsRange`). Either side of the tuple can be
      * `null` while a range is only half-picked.
+     *
+     * Note the asymmetry when the field is emptied via {@link clearable}: range
+     * mode reports `[null, null]` here, but single mode has no `null` in this
+     * signature, so use {@link onClear} to observe a single-date clear.
      */
     onChange?: (date: Date | DateRangeType) => void;
     /**
      * Placeholder text for the input
      */
     placeholder?: string;
+    /**
+     * Label rendered above the field, in the same style as `Select`'s label.
+     *
+     * Forwarded to the underlying `Input`. It used to work only by accident —
+     * unknown props were spread onto the field — which meant consumers had to
+     * cast to pass it, and it also leaked onto the calendar overlay (XUITSD-97).
+     */
+    label?: string;
     /** `date-fns` format for the field, defaulting to `"MM/dd/yyyy"`. Numeric `d`/`dd`, `M`/`MM` and `y`/`yyyy` tokens only, in any order (mind the casing — `mm` is minutes); anything else warns in development and falls back to the default. */
     dateFormat?: string;
     /**
@@ -67,6 +79,23 @@ interface DatePickerProps extends Omit<CalendarProps, "onChange"> {
      * Optional leading icon shown inside the field.
      */
     iconLeft?: ReactNode;
+    /**
+     * Shows a clear (✕) control inside the field, to the left of the calendar
+     * icon, whenever the field holds a value. Works in single and range mode,
+     * and is suppressed while the field is `disabled` or `readOnly`.
+     *
+     * Clearing empties the field, drops any active chip, and reports the new
+     * value: range mode fires `onChange([null, null])`; single mode fires
+     * {@link onClear} only, because `onChange` cannot express "no date". The
+     * cleared field is not reverted on blur — it stands until the props change.
+     */
+    clearable?: boolean;
+    /**
+     * Called when the field is emptied via the {@link clearable} control, after
+     * the field has been cleared. This is the only clear signal in single-date
+     * mode; in range mode `onChange([null, null])` fires as well.
+     */
+    onClear?: () => void;
     /**
      * Highlights the field as invalid (error state).
      */

package/native/index.js

@@ -84,6 +84,7 @@ var toGapValue = (gap) => {
   const asNumber = Number(gap);
   return Number.isFinite(asNumber) ? asNumber : void 0;
 };
+var toNativeDisplay = (display) => display === "none" ? "none" : void 0;
 var Box = ({
   children,
   onPress,
@@ -115,6 +116,7 @@ var Box = ({
   marginBottom,
   marginLeft,
   marginRight,
+  display,
   flexDirection,
   flexWrap,
   alignItems,
@@ -178,6 +180,7 @@ var Box = ({
     marginBottom,
     marginLeft,
     marginRight,
+    display: toNativeDisplay(display),
     flexDirection,
     flexWrap,
     alignItems,
@@ -638,6 +641,9 @@ var DatePicker = (0, import_react.forwardRef)(
     overlayThemeProductContext,
     iconRight = /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(CalendarFieldIcon, {}),
     iconLeft,
+    label,
+    clearable = false,
+    onClear,
     error,
     errorMessage,
     readOnly,
@@ -659,6 +665,7 @@ var DatePicker = (0, import_react.forwardRef)(
       () => isRange ? [datePartsFromDate(startDate), datePartsFromDate(endDate)] : [datePartsFromDate(selectedDate)],
       [isRange, startDate, endDate, selectedDate]
     );
+    const propKey = `${selectedDate?.getTime() ?? ""}|${startDate?.getTime() ?? ""}|${endDate?.getTime() ?? ""}|${isRange}`;
     const [open, setOpen] = (0, import_react.useState)(false);
     const [groups, setGroups] = (0, import_react.useState)(propGroups);
     const [edit, setEdit] = (0, import_react.useState)(null);
@@ -674,6 +681,15 @@ var DatePicker = (0, import_react.forwardRef)(
     const inputRef = (0, import_react.useRef)(null);
     const chipSelectionRef = (0, import_react.useRef)(false);
     const suppressReopenRef = (0, import_react.useRef)(false);
+    const sessionRef = (0, import_react.useRef)({
+      dirty: false,
+      cleared: false,
+      propKey
+    });
+    const markDirty = () => {
+      sessionRef.current.dirty = true;
+      sessionRef.current.cleared = false;
+    };
     const activeChipValue = activeChip !== void 0 ? activeChip : internalChip;
     const chipLabel = showChipLabel && activeChipValue && chips ? chips.find((c) => c.value === activeChipValue)?.label : void 0;
     const isWithinBounds = (date) => {
@@ -733,6 +749,7 @@ var DatePicker = (0, import_react.forwardRef)(
     );
     const showMask = hasAnyFilled || focused && isWeb;
     const inputValue = chipLabel ?? (showMask ? composed.text : "");
+    const showClear = clearable && editable && (hasAnyFilled || !!chipLabel);
     const orderedSegments = () => composeField().segments;
     const firstSegmentKey = () => {
       const first = orderedSegments()[0];
@@ -775,6 +792,7 @@ var DatePicker = (0, import_react.forwardRef)(
       if (start || end) applySelection([start, end], false);
     };
     const commitPart = (group, type, rawValue) => {
+      markDirty();
       const clamped = clampDatePart(type, rawValue, groups[group]);
       const next = groups.map((g, i) => {
         if (i !== group) return g;
@@ -823,6 +841,7 @@ var DatePicker = (0, import_react.forwardRef)(
         setEdit(null);
         if (committed !== null) advance(active);
       } else {
+        markDirty();
         setEdit({ group: active.group, type: active.type, buffer });
       }
     };
@@ -860,6 +879,7 @@ var DatePicker = (0, import_react.forwardRef)(
       e.preventDefault();
       const active = activeSegment ?? firstSegmentKey();
       if (!active) return;
+      markDirty();
       const sameActive = edit && edit.group === active.group && edit.type === active.type;
       if (sameActive && edit.buffer.length > 0) {
         const buffer = edit.buffer.slice(0, -1);
@@ -911,6 +931,11 @@ var DatePicker = (0, import_react.forwardRef)(
         suppressReopenRef.current = false;
         return;
       }
+      sessionRef.current = {
+        dirty: false,
+        cleared: sessionRef.current.cleared,
+        propKey
+      };
       setFocused(true);
       setOpen(true);
       if (isWeb && editable) setActiveSegment(firstSegmentKey());
@@ -927,7 +952,19 @@ var DatePicker = (0, import_react.forwardRef)(
       onBlurProp?.(e);
       setFocused(false);
       setActiveSegment(null);
+      if (sessionRef.current.propKey !== propKey && !sessionRef.current.dirty) {
+        sessionRef.current = { dirty: false, cleared: false, propKey };
+        setEdit(null);
+        setParseError(null);
+        setGroups(propGroups());
+        return;
+      }
       if (!editable) return;
+      if (sessionRef.current.cleared && !sessionRef.current.dirty) {
+        setEdit(null);
+        setParseError(null);
+        return;
+      }
       let next = groups;
       if (edit) {
         const clamped = clampDatePart(
@@ -984,6 +1021,7 @@ var DatePicker = (0, import_react.forwardRef)(
         setParseError("Date must be within the allowed range");
         return;
       }
+      markDirty();
       setParseError(null);
       setEdit(null);
       setGroups(next);
@@ -994,13 +1032,29 @@ var DatePicker = (0, import_react.forwardRef)(
       setInternalChip(value);
       onChipSelect?.(value);
     };
+    const handleClear = () => {
+      const next = isRange ? [datePartsFromDate(null), datePartsFromDate(null)] : [datePartsFromDate(null)];
+      sessionRef.current.dirty = false;
+      sessionRef.current.cleared = true;
+      setGroups(next);
+      setEdit(null);
+      setParseError(null);
+      setInternalChip(null);
+      onChipSelect?.(null);
+      if (isWeb && editable) setActiveSegment(firstSegmentKey());
+      onClear?.();
+      if (isRange) {
+        const emptyRange = [null, null];
+        onChange?.(emptyRange);
+      }
+    };
     const handleDateChange = (date) => applySelection(date, closeOnComplete);
     const closePanel = (0, import_react.useCallback)(() => setOpen(false), []);
     const renderTopContent = topContent ? () => topContent({ close: closePanel }) : void 0;
     const renderBottomContent = bottomContent ? () => bottomContent({ close: closePanel }) : void 0;
-    const propKey = `${selectedDate?.getTime() ?? ""}|${startDate?.getTime() ?? ""}|${endDate?.getTime() ?? ""}|${isRange}`;
     (0, import_react.useEffect)(() => {
       if (focused) return;
+      sessionRef.current = { dirty: false, cleared: false, propKey };
       setGroups(propGroups());
       setEdit(null);
       setParseError(null);
@@ -1177,6 +1231,7 @@ var DatePicker = (0, import_react.forwardRef)(
               ...rest,
               ref: inputRef,
               size,
+              label,
               placeholder: placeholder || (isRange ? "Choose a date range" : "Choose a date"),
               value: inputValue,
               readOnly,
@@ -1187,6 +1242,8 @@ var DatePicker = (0, import_react.forwardRef)(
               onPaste: handlePaste,
               iconRight,
               iconLeft,
+              extraClear: showClear,
+              onRemove: handleClear,
               error: error || !!parseError,
               errorMessage: parseError ?? errorMessage,
               backgroundColor,