@xsolla/xui-date-picker 0.184.0 → 0.185.1

package/README.md

@@ -58,6 +58,7 @@ import {
 } from '@xsolla/xui-date-picker';
 import type {
   DatePickerProps,
+  DatePickerPlacement,
   DateRangeType,
   CalendarProps,
   DualCalendarProps,
@@ -99,7 +100,8 @@ const [date, setDate] = useState<Date | null>(null);
 | `size` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | `'md'` | Input size. |
 | `disabled` | `boolean` | `false` | Disable the input. |
 | `backgroundColor` | `string` | — | Custom background colour for the input. |
-| `dropdownPosition` | `'left' \| 'right'` | `'left'` | Align the calendar dropdown to the left or right edge of 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. |
 | `locale` | `CalendarLocaleType` | `'enUS'` | `date-fns` locale identifier. |
 | `firstDayOfWeek` | `number` | — | First day of the week (0 = Sunday … 6 = Saturday). |
 | `initialMonth` | `Date` | — | Month shown on first render. |
@@ -150,6 +152,10 @@ Re-exported from `@xsolla/xui-calendar`. Preset chips bar (e.g. "Last 7 days", "
 
 ```ts
 type DateRangeType = [Date | null, Date | null];
+
+type DatePickerSide = 'top' | 'bottom' | 'left' | 'right';
+type DatePickerAlignment = 'start' | 'center' | 'end';
+type DatePickerPlacement = DatePickerSide | `${DatePickerSide}-${DatePickerAlignment}`;
 ```
 
 ## Examples
@@ -180,7 +186,7 @@ const [end, setEnd] = useState<Date | null>(null);
 
 <DatePicker
   variant="dual"
-  dropdownPosition="right"
+  placement="bottom-end"
   startDate={start}
   endDate={end}
   onChange={(range) => {
@@ -191,6 +197,29 @@ const [end, setEnd] = useState<Date | null>(null);
 />;
 ```
 
+### Placement and autoflip
+
+```tsx
+const [date, setDate] = useState<Date | null>(null);
+
+// Default: the calendar auto-flips based on available viewport space.
+<DatePicker selectedDate={date} onChange={(d) => setDate(d as Date | null)} />;
+
+// Force a side with `placement`.
+<DatePicker
+  placement="top"
+  selectedDate={date}
+  onChange={(d) => setDate(d as Date | null)}
+/>;
+
+// Force a side and alignment (here: opens upward, right-aligned).
+<DatePicker
+  placement="top-end"
+  selectedDate={date}
+  onChange={(d) => setDate(d as Date | null)}
+/>;
+```
+
 ### Preset chips
 
 ```tsx

package/native/index.d.mts

@@ -1,10 +1,23 @@
 import { CalendarProps, CalendarLocaleType } from '@xsolla/xui-calendar';
 export { Calendar, CalendarChipOption, CalendarChips, CalendarChipsProps, CalendarGrid, CalendarGridProps, CalendarHeader, CalendarHeaderProps, CalendarLocaleType, CalendarProps, DualCalendar, DualCalendarProps } from '@xsolla/xui-calendar';
 import * as react from 'react';
+import { ReactNode, FocusEvent, MouseEvent, KeyboardEvent, ClipboardEvent } from 'react';
 import { ThemeMode, ProductContext } from '@xsolla/xui-core';
 
 type DateRangeType = [Date | null, Date | null];
 type DatePickerDropdownPosition = "left" | "right";
+/** Side the calendar opens toward, relative to the input. */
+type DatePickerSide = "top" | "bottom" | "left" | "right";
+/** Alignment along the chosen side. `start`/`end` map to the leading/trailing edge. */
+type DatePickerAlignment = "start" | "center" | "end";
+/**
+ * Where the calendar opens, following the Floating UI / `ContextMenuPlacement`
+ * convention: a {@link DatePickerSide} optionally suffixed with an alignment
+ * (`-start` | `-center` | `-end`). A bare side aligns to `start` (top/bottom:
+ * left edge; left/right: top edge). For `top`/`bottom` the suffix sets the
+ * horizontal edge; for `left`/`right` it sets the vertical edge.
+ */
+type DatePickerPlacement = DatePickerSide | `${DatePickerSide}-${DatePickerAlignment}`;
 interface DatePickerProps extends Omit<CalendarProps, "onChange"> {
     /**
      * Calendar variant: "single" shows a single month, "dual" shows two months side-by-side.
@@ -19,6 +32,12 @@ interface DatePickerProps extends Omit<CalendarProps, "onChange"> {
      * Placeholder text for the input
      */
     placeholder?: string;
+    /**
+     * date-fns format string used to both render and parse the field's text value
+     * (e.g. `"dd/MM/yyyy"`). Applies to each date in a range. Defaults to
+     * `"MM/dd/yyyy"`.
+     */
+    dateFormat?: string;
     /**
      * Size of the input
      */
@@ -32,9 +51,64 @@ interface DatePickerProps extends Omit<CalendarProps, "onChange"> {
      */
     backgroundColor?: string;
     /**
-     * Horizontal alignment of the calendar dropdown relative to the input.
+     * Trailing icon shown inside the field. Defaults to a calendar icon
+     * (`icon_calendar--line`). Pass `null` to hide it.
+     */
+    iconRight?: ReactNode;
+    /**
+     * Optional leading icon shown inside the field.
+     */
+    iconLeft?: ReactNode;
+    /**
+     * Highlights the field as invalid (error state).
+     */
+    error?: boolean;
+    /**
+     * Error message shown below the field. Also puts the field in the error state.
+     */
+    errorMessage?: string;
+    /**
+     * When a chip is selected, show its label in the field (e.g. "Last 30 days").
+     * Set to `false` to show the resolved date/range instead. Defaults to `true`.
+     */
+    showChipLabel?: boolean;
+    /** Renders the field read-only: it can open the calendar but not be edited. */
+    readOnly?: boolean;
+    /** Called on field focus (invoked before the picker's own focus handling). */
+    onFocus?: (e: FocusEvent<HTMLInputElement>) => void;
+    /** Called on field blur (invoked before the picker's own blur handling). */
+    onBlur?: (e: FocusEvent<HTMLInputElement>) => void;
+    /** Called on field click (invoked before the picker's own click handling). */
+    onClick?: (e: MouseEvent<HTMLInputElement>) => void;
+    /**
+     * Called on field keydown before the picker's own handling; call
+     * `e.preventDefault()` to suppress the built-in segment editing for that key.
+     */
+    onKeyDown?: (e: KeyboardEvent<HTMLInputElement>) => void;
+    /**
+     * Called on field paste before the picker's own handling; call
+     * `e.preventDefault()` to suppress the built-in parse.
+     */
+    onPaste?: (e: ClipboardEvent<HTMLInputElement>) => void;
+    /**
+     * Horizontal alignment of the calendar for `top`/`bottom` placements. Retained
+     * as a fallback: applied only when `placement` has no alignment suffix, so
+     * existing usage keeps working.
+     *
+     * @deprecated Use the `placement` alignment suffix instead (e.g. `bottom-end`).
      */
     dropdownPosition?: DatePickerDropdownPosition;
+    /**
+     * Where the calendar opens, e.g. `"bottom"`, `"bottom-start"`, `"top-end"`,
+     * `"right"`. Follows the same `{side}[-alignment]` convention as
+     * `ContextMenuPlacement`. A bare side aligns to `start`; add `-start`,
+     * `-center`, or `-end` to align along that side. When omitted, the calendar
+     * measures the available viewport space when it opens and automatically flips
+     * to the best direction (prefers `"bottom"`, then `"top"`, then `"left"`,
+     * then `"right"`), also flipping the horizontal edge so it stays on screen.
+     * When set, the calendar always opens at that placement. Web only.
+     */
+    placement?: DatePickerPlacement;
     /** Test ID for testing frameworks */
     testID?: string;
     /** Theme mode for the calendar overlay. Defaults to themeMode when not set. */
@@ -46,5 +120,75 @@ interface DatePickerProps extends Omit<CalendarProps, "onChange"> {
 declare const DatePicker: react.ForwardRefExoticComponent<DatePickerProps & react.RefAttributes<any>>;
 
 declare function formatDate(date: Date, formatStr: string, locale?: CalendarLocaleType): string;
+type DateSegmentType = "day" | "month" | "year";
+/** A date broken into editable parts; `null` means "not yet filled". */
+interface DateParts {
+    day: number | null;
+    month: number | null;
+    year: number | null;
+}
+/** A rendered segment's character span within the field text. */
+interface SegmentRange {
+    type: DateSegmentType;
+    start: number;
+    end: number;
+    filled: boolean;
+}
+type FormatToken = {
+    kind: "segment";
+    type: DateSegmentType;
+} | {
+    kind: "literal";
+    text: string;
+};
+/** Split a date format into ordered segment tokens and literal separators. */
+declare function parseDateFormat(format: string): FormatToken[];
+declare function datePartsFromDate(date: Date | null | undefined): DateParts;
+/** Assemble a `Date`, or null if any part is missing or the date is invalid. */
+declare function datePartsToDate(parts: DateParts): Date | null;
+declare function isDatePartsComplete(parts: DateParts): boolean;
+/** Clamp a raw numeric segment value into its valid range. */
+declare function clampDatePart(type: DateSegmentType, value: number, parts: DateParts): number;
+/** Step a numeric segment value, wrapping within its range (day/month) or ±1 (year). */
+declare function stepDatePart(type: DateSegmentType, current: number, delta: number, parts: DateParts): number;
+/**
+ * Render `parts` into field text using `format`, returning each segment's char
+ * range. Filled parts are zero-padded; unfilled parts show a token placeholder
+ * (`dd`/`mm`/`yyyy`). `active`, when set, renders the raw in-progress buffer for
+ * the segment currently being typed.
+ */
+declare function buildSegmentedValue(format: string, parts: DateParts, active?: {
+    type: DateSegmentType;
+    buffer: string;
+}): {
+    text: string;
+    ranges: SegmentRange[];
+};
+/** Whether a first digit rules out a valid second digit (for early auto-commit). */
+declare function isSegmentComplete(type: DateSegmentType, buffer: string): boolean;
+interface DateSegment {
+    type: DateSegmentType;
+    /** Inclusive character index of the segment's first digit in `value`. */
+    start: number;
+    /** Exclusive character index one past the segment's last digit. */
+    end: number;
+}
+/** Number of days in the given month (0-indexed) of the given year. */
+declare function daysInMonth(year: number, monthIndex: number): number;
+/**
+ * Locate the day/month/year segments within a formatted date `value` by walking
+ * the `format` string in parallel: `d`/`M`/`y` token runs consume the matching
+ * digit run in `value`, other characters are treated as literal separators.
+ * Works for any token order (e.g. `MM/dd/yyyy`, `dd/MM/yyyy`, `yyyy-MM-dd`) and
+ * both fixed- and variable-width tokens. Returns segments in display order.
+ */
+declare function getDateSegments(format: string, value: string): DateSegment[];
+/**
+ * Step a single date segment by `delta`, isolated to that field (no carry):
+ * day wraps within the current month, month wraps within the year (day clamped
+ * to the new month's length), year increments freely. Mirrors the segment wrap
+ * behaviour of the InputTime segments.
+ */
+declare function stepDateSegment(date: Date, type: DateSegmentType, delta: number): Date;
 
-export { DatePicker, type DatePickerDropdownPosition, type DatePickerProps, type DateRangeType, formatDate };
+export { type DateParts, DatePicker, type DatePickerAlignment, type DatePickerDropdownPosition, type DatePickerPlacement, type DatePickerProps, type DatePickerSide, type DateRangeType, type DateSegment, type DateSegmentType, type SegmentRange, buildSegmentedValue, clampDatePart, datePartsFromDate, datePartsToDate, daysInMonth, formatDate, getDateSegments, isDatePartsComplete, isSegmentComplete, parseDateFormat, stepDatePart, stepDateSegment };

package/native/index.d.ts

@@ -1,10 +1,23 @@
 import { CalendarProps, CalendarLocaleType } from '@xsolla/xui-calendar';
 export { Calendar, CalendarChipOption, CalendarChips, CalendarChipsProps, CalendarGrid, CalendarGridProps, CalendarHeader, CalendarHeaderProps, CalendarLocaleType, CalendarProps, DualCalendar, DualCalendarProps } from '@xsolla/xui-calendar';
 import * as react from 'react';
+import { ReactNode, FocusEvent, MouseEvent, KeyboardEvent, ClipboardEvent } from 'react';
 import { ThemeMode, ProductContext } from '@xsolla/xui-core';
 
 type DateRangeType = [Date | null, Date | null];
 type DatePickerDropdownPosition = "left" | "right";
+/** Side the calendar opens toward, relative to the input. */
+type DatePickerSide = "top" | "bottom" | "left" | "right";
+/** Alignment along the chosen side. `start`/`end` map to the leading/trailing edge. */
+type DatePickerAlignment = "start" | "center" | "end";
+/**
+ * Where the calendar opens, following the Floating UI / `ContextMenuPlacement`
+ * convention: a {@link DatePickerSide} optionally suffixed with an alignment
+ * (`-start` | `-center` | `-end`). A bare side aligns to `start` (top/bottom:
+ * left edge; left/right: top edge). For `top`/`bottom` the suffix sets the
+ * horizontal edge; for `left`/`right` it sets the vertical edge.
+ */
+type DatePickerPlacement = DatePickerSide | `${DatePickerSide}-${DatePickerAlignment}`;
 interface DatePickerProps extends Omit<CalendarProps, "onChange"> {
     /**
      * Calendar variant: "single" shows a single month, "dual" shows two months side-by-side.
@@ -19,6 +32,12 @@ interface DatePickerProps extends Omit<CalendarProps, "onChange"> {
      * Placeholder text for the input
      */
     placeholder?: string;
+    /**
+     * date-fns format string used to both render and parse the field's text value
+     * (e.g. `"dd/MM/yyyy"`). Applies to each date in a range. Defaults to
+     * `"MM/dd/yyyy"`.
+     */
+    dateFormat?: string;
     /**
      * Size of the input
      */
@@ -32,9 +51,64 @@ interface DatePickerProps extends Omit<CalendarProps, "onChange"> {
      */
     backgroundColor?: string;
     /**
-     * Horizontal alignment of the calendar dropdown relative to the input.
+     * Trailing icon shown inside the field. Defaults to a calendar icon
+     * (`icon_calendar--line`). Pass `null` to hide it.
+     */
+    iconRight?: ReactNode;
+    /**
+     * Optional leading icon shown inside the field.
+     */
+    iconLeft?: ReactNode;
+    /**
+     * Highlights the field as invalid (error state).
+     */
+    error?: boolean;
+    /**
+     * Error message shown below the field. Also puts the field in the error state.
+     */
+    errorMessage?: string;
+    /**
+     * When a chip is selected, show its label in the field (e.g. "Last 30 days").
+     * Set to `false` to show the resolved date/range instead. Defaults to `true`.
+     */
+    showChipLabel?: boolean;
+    /** Renders the field read-only: it can open the calendar but not be edited. */
+    readOnly?: boolean;
+    /** Called on field focus (invoked before the picker's own focus handling). */
+    onFocus?: (e: FocusEvent<HTMLInputElement>) => void;
+    /** Called on field blur (invoked before the picker's own blur handling). */
+    onBlur?: (e: FocusEvent<HTMLInputElement>) => void;
+    /** Called on field click (invoked before the picker's own click handling). */
+    onClick?: (e: MouseEvent<HTMLInputElement>) => void;
+    /**
+     * Called on field keydown before the picker's own handling; call
+     * `e.preventDefault()` to suppress the built-in segment editing for that key.
+     */
+    onKeyDown?: (e: KeyboardEvent<HTMLInputElement>) => void;
+    /**
+     * Called on field paste before the picker's own handling; call
+     * `e.preventDefault()` to suppress the built-in parse.
+     */
+    onPaste?: (e: ClipboardEvent<HTMLInputElement>) => void;
+    /**
+     * Horizontal alignment of the calendar for `top`/`bottom` placements. Retained
+     * as a fallback: applied only when `placement` has no alignment suffix, so
+     * existing usage keeps working.
+     *
+     * @deprecated Use the `placement` alignment suffix instead (e.g. `bottom-end`).
      */
     dropdownPosition?: DatePickerDropdownPosition;
+    /**
+     * Where the calendar opens, e.g. `"bottom"`, `"bottom-start"`, `"top-end"`,
+     * `"right"`. Follows the same `{side}[-alignment]` convention as
+     * `ContextMenuPlacement`. A bare side aligns to `start`; add `-start`,
+     * `-center`, or `-end` to align along that side. When omitted, the calendar
+     * measures the available viewport space when it opens and automatically flips
+     * to the best direction (prefers `"bottom"`, then `"top"`, then `"left"`,
+     * then `"right"`), also flipping the horizontal edge so it stays on screen.
+     * When set, the calendar always opens at that placement. Web only.
+     */
+    placement?: DatePickerPlacement;
     /** Test ID for testing frameworks */
     testID?: string;
     /** Theme mode for the calendar overlay. Defaults to themeMode when not set. */
@@ -46,5 +120,75 @@ interface DatePickerProps extends Omit<CalendarProps, "onChange"> {
 declare const DatePicker: react.ForwardRefExoticComponent<DatePickerProps & react.RefAttributes<any>>;
 
 declare function formatDate(date: Date, formatStr: string, locale?: CalendarLocaleType): string;
+type DateSegmentType = "day" | "month" | "year";
+/** A date broken into editable parts; `null` means "not yet filled". */
+interface DateParts {
+    day: number | null;
+    month: number | null;
+    year: number | null;
+}
+/** A rendered segment's character span within the field text. */
+interface SegmentRange {
+    type: DateSegmentType;
+    start: number;
+    end: number;
+    filled: boolean;
+}
+type FormatToken = {
+    kind: "segment";
+    type: DateSegmentType;
+} | {
+    kind: "literal";
+    text: string;
+};
+/** Split a date format into ordered segment tokens and literal separators. */
+declare function parseDateFormat(format: string): FormatToken[];
+declare function datePartsFromDate(date: Date | null | undefined): DateParts;
+/** Assemble a `Date`, or null if any part is missing or the date is invalid. */
+declare function datePartsToDate(parts: DateParts): Date | null;
+declare function isDatePartsComplete(parts: DateParts): boolean;
+/** Clamp a raw numeric segment value into its valid range. */
+declare function clampDatePart(type: DateSegmentType, value: number, parts: DateParts): number;
+/** Step a numeric segment value, wrapping within its range (day/month) or ±1 (year). */
+declare function stepDatePart(type: DateSegmentType, current: number, delta: number, parts: DateParts): number;
+/**
+ * Render `parts` into field text using `format`, returning each segment's char
+ * range. Filled parts are zero-padded; unfilled parts show a token placeholder
+ * (`dd`/`mm`/`yyyy`). `active`, when set, renders the raw in-progress buffer for
+ * the segment currently being typed.
+ */
+declare function buildSegmentedValue(format: string, parts: DateParts, active?: {
+    type: DateSegmentType;
+    buffer: string;
+}): {
+    text: string;
+    ranges: SegmentRange[];
+};
+/** Whether a first digit rules out a valid second digit (for early auto-commit). */
+declare function isSegmentComplete(type: DateSegmentType, buffer: string): boolean;
+interface DateSegment {
+    type: DateSegmentType;
+    /** Inclusive character index of the segment's first digit in `value`. */
+    start: number;
+    /** Exclusive character index one past the segment's last digit. */
+    end: number;
+}
+/** Number of days in the given month (0-indexed) of the given year. */
+declare function daysInMonth(year: number, monthIndex: number): number;
+/**
+ * Locate the day/month/year segments within a formatted date `value` by walking
+ * the `format` string in parallel: `d`/`M`/`y` token runs consume the matching
+ * digit run in `value`, other characters are treated as literal separators.
+ * Works for any token order (e.g. `MM/dd/yyyy`, `dd/MM/yyyy`, `yyyy-MM-dd`) and
+ * both fixed- and variable-width tokens. Returns segments in display order.
+ */
+declare function getDateSegments(format: string, value: string): DateSegment[];
+/**
+ * Step a single date segment by `delta`, isolated to that field (no carry):
+ * day wraps within the current month, month wraps within the year (day clamped
+ * to the new month's length), year increments freely. Mirrors the segment wrap
+ * behaviour of the InputTime segments.
+ */
+declare function stepDateSegment(date: Date, type: DateSegmentType, delta: number): Date;
 
-export { DatePicker, type DatePickerDropdownPosition, type DatePickerProps, type DateRangeType, formatDate };
+export { type DateParts, DatePicker, type DatePickerAlignment, type DatePickerDropdownPosition, type DatePickerPlacement, type DatePickerProps, type DatePickerSide, type DateRangeType, type DateSegment, type DateSegmentType, type SegmentRange, buildSegmentedValue, clampDatePart, datePartsFromDate, datePartsToDate, daysInMonth, formatDate, getDateSegments, isDatePartsComplete, isSegmentComplete, parseDateFormat, stepDatePart, stepDateSegment };