@xsolla/xui-date-picker 0.149.1 → 0.151.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +167 -134
  2. package/package.json +5 -5
package/README.md CHANGED
@@ -1,170 +1,203 @@
1
- # Date Picker
1
+ # DatePicker
2
2
 
3
- A cross-platform React date picker component with an input field that opens a calendar dropdown for date selection. The calendar is provided by `@xsolla/xui-calendar`.
3
+ A cross-platform date picker with an input field that opens a single- or dual-month calendar dropdown for date or range selection.
4
4
 
5
5
  ## Installation
6
6
 
7
7
  ```bash
8
8
  npm install @xsolla/xui-date-picker
9
- # or
10
- yarn add @xsolla/xui-date-picker
11
9
  ```
12
10
 
13
- > The `Calendar`, `DualCalendar`, `CalendarChips`, and related components are available from `@xsolla/xui-calendar` and are re-exported from this package for backward compatibility. For standalone calendar usage (without the input), install `@xsolla/xui-calendar` directly.
14
-
15
- ## Demo
16
-
17
- ### Single Date Selection
11
+ ## Imports
18
12
 
19
13
  ```tsx
20
- import * as React from 'react';
21
- import { DatePicker } from '@xsolla/xui-date-picker';
22
-
23
- export default function SingleDate() {
24
- const [date, setDate] = React.useState<Date | null>(null);
25
-
26
- return (
27
- <DatePicker
28
- selectedDate={date}
29
- onChange={(newDate) => setDate(newDate as Date)}
30
- placeholder="Select a date"
31
- />
32
- );
33
- }
14
+ import {
15
+ DatePicker,
16
+ Calendar,
17
+ DualCalendar,
18
+ CalendarHeader,
19
+ CalendarGrid,
20
+ CalendarChips,
21
+ formatDate,
22
+ } from '@xsolla/xui-date-picker';
23
+ import type {
24
+ DatePickerProps,
25
+ DateRangeType,
26
+ CalendarProps,
27
+ DualCalendarProps,
28
+ CalendarChipOption,
29
+ CalendarChipsProps,
30
+ CalendarGridProps,
31
+ CalendarHeaderProps,
32
+ CalendarLocaleType,
33
+ } from '@xsolla/xui-date-picker';
34
34
  ```
35
35
 
36
- ### Date Range Selection
36
+ `Calendar`, `DualCalendar` and friends are re-exported from `@xsolla/xui-calendar`. For standalone calendar usage, depend on `@xsolla/xui-calendar` directly.
37
+
38
+ ## Quick start
37
39
 
38
40
  ```tsx
39
- import * as React from 'react';
40
- import { DatePicker } from '@xsolla/xui-date-picker';
41
-
42
- export default function DateRange() {
43
- const [startDate, setStartDate] = React.useState<Date | null>(null);
44
- const [endDate, setEndDate] = React.useState<Date | null>(null);
45
-
46
- return (
47
- <DatePicker
48
- selectsRange
49
- startDate={startDate}
50
- endDate={endDate}
51
- onChange={(range) => {
52
- const [start, end] = range as [Date | null, Date | null];
53
- setStartDate(start);
54
- setEndDate(end);
55
- }}
56
- />
57
- );
58
- }
41
+ const [date, setDate] = useState<Date | null>(null);
42
+
43
+ <DatePicker
44
+ selectedDate={date}
45
+ onChange={(d) => setDate(d as Date | null)}
46
+ placeholder="Select a date"
47
+ />;
59
48
  ```
60
49
 
61
- ### With Preset Chips
50
+ ## API Reference
62
51
 
63
- ```tsx
64
- import * as React from 'react';
65
- import { DatePicker } from '@xsolla/xui-date-picker';
52
+ ### `<DatePicker>`
66
53
 
67
- const chips = [
68
- { label: 'Today', value: 'today' },
69
- { label: 'Last 7 days', value: 'last7' },
70
- { label: 'Last 30 days', value: 'last30' },
71
- ];
54
+ | Prop | Type | Default | Description |
55
+ | --- | --- | --- | --- |
56
+ | `variant` | `'single' \| 'dual'` | `'single'` | Single-month or dual-month calendar; `'dual'` forces range mode. |
57
+ | `selectedDate` | `Date \| null` | — | Selected date for single mode. |
58
+ | `startDate` | `Date \| null` | — | Range start date. |
59
+ | `endDate` | `Date \| null` | — | Range end date. |
60
+ | `selectsRange` | `boolean` | `false` | Enable range selection. |
61
+ | `onChange` | `(date: Date \| DateRangeType) => void` | — | Fired when the date or range changes. |
62
+ | `placeholder` | `string` | `'MM/DD/YYYY'` | Placeholder for the input. |
63
+ | `size` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | `'md'` | Input size. |
64
+ | `disabled` | `boolean` | `false` | Disable the input. |
65
+ | `backgroundColor` | `string` | — | Custom background colour for the input. |
66
+ | `locale` | `CalendarLocaleType` | `'enUS'` | `date-fns` locale identifier. |
67
+ | `firstDayOfWeek` | `number` | — | First day of the week (0 = Sunday … 6 = Saturday). |
68
+ | `initialMonth` | `Date` | — | Month shown on first render. |
69
+ | `month` | `Date` | — | Controlled month. |
70
+ | `minDate` | `Date \| null` | — | Minimum selectable date. |
71
+ | `maxDate` | `Date \| null` | — | Maximum selectable date. |
72
+ | `chips` | `CalendarChipOption[]` | — | Preset range chips above the calendar. |
73
+ | `activeChip` | `string \| null` | — | Currently active chip value. |
74
+ | `onChipSelect` | `(value: string \| null) => void` | — | Fired when a chip is selected. |
75
+ | `topContent` | `(api: { close: () => void }) => ReactNode` | — | Custom content above the calendar. |
76
+ | `bottomContent` | `(api: { close: () => void }) => ReactNode` | — | Custom content below the calendar. |
77
+ | `contextMenuMaxHeight` | `number` | — | Max height for the month/year context menus. |
78
+ | `testID` | `string` | — | Test identifier. |
79
+
80
+ `DatePicker` extends `CalendarProps` (excluding `onChange`).
81
+
82
+ Inherits `ThemeOverrideProps` (`themeMode`, `themeProductContext`).
83
+
84
+ ### `<Calendar>`
85
+
86
+ Re-exported from `@xsolla/xui-calendar`. Standalone single-month calendar.
87
+
88
+ ### `<DualCalendar>`
89
+
90
+ Re-exported from `@xsolla/xui-calendar`. Two-month calendar for range selection.
91
+
92
+ ### `<CalendarHeader>`
93
+
94
+ Re-exported from `@xsolla/xui-calendar`. Month/year header with navigation controls.
95
+
96
+ ### `<CalendarGrid>`
97
+
98
+ Re-exported from `@xsolla/xui-calendar`. Day grid; takes `currentMonth` and selection props.
72
99
 
73
- export default function WithChips() {
74
- const [date, setDate] = React.useState<Date | null>(null);
75
- const [activeChip, setActiveChip] = React.useState<string | null>('last30');
76
-
77
- return (
78
- <DatePicker
79
- selectedDate={date}
80
- onChange={(newDate) => setDate(newDate as Date)}
81
- chips={chips}
82
- activeChip={activeChip}
83
- onChipSelect={setActiveChip}
84
- />
85
- );
86
- }
100
+ ### `<CalendarChips>`
101
+
102
+ Re-exported from `@xsolla/xui-calendar`. Preset chips bar (e.g. "Last 7 days", "This month").
103
+
104
+ ### Utilities
105
+
106
+ | Export | Type | Description |
107
+ | --- | --- | --- |
108
+ | `formatDate` | `(date: Date, formatStr: string, locale?: CalendarLocaleType) => string` | Format a date with a `date-fns` locale identifier. |
109
+
110
+ ### Types
111
+
112
+ ```ts
113
+ type DateRangeType = [Date | null, Date | null];
87
114
  ```
88
115
 
89
- ### Different Sizes
116
+ ## Examples
117
+
118
+ ### Range selection
90
119
 
91
120
  ```tsx
92
- import * as React from 'react';
93
- import { DatePicker } from '@xsolla/xui-date-picker';
94
-
95
- export default function Sizes() {
96
- return (
97
- <div style={{ display: 'flex', flexDirection: 'column', gap: 16 }}>
98
- <DatePicker size="sm" placeholder="Small" />
99
- <DatePicker size="md" placeholder="Medium" />
100
- <DatePicker size="lg" placeholder="Large" />
101
- </div>
102
- );
103
- }
121
+ const [start, setStart] = useState<Date | null>(null);
122
+ const [end, setEnd] = useState<Date | null>(null);
123
+
124
+ <DatePicker
125
+ selectsRange
126
+ startDate={start}
127
+ endDate={end}
128
+ onChange={(range) => {
129
+ const [s, e] = range as DateRangeType;
130
+ setStart(s);
131
+ setEnd(e);
132
+ }}
133
+ />;
104
134
  ```
105
135
 
106
- ### Standalone Calendar
136
+ ### Dual calendar
137
+
138
+ ```tsx
139
+ const [start, setStart] = useState<Date | null>(null);
140
+ const [end, setEnd] = useState<Date | null>(null);
141
+
142
+ <DatePicker
143
+ variant="dual"
144
+ startDate={start}
145
+ endDate={end}
146
+ onChange={(range) => {
147
+ const [s, e] = range as DateRangeType;
148
+ setStart(s);
149
+ setEnd(e);
150
+ }}
151
+ />;
152
+ ```
107
153
 
108
- For standalone calendar usage, import from `@xsolla/xui-calendar`:
154
+ ### Preset chips
109
155
 
110
156
  ```tsx
111
- import { Calendar, DualCalendar } from '@xsolla/xui-calendar';
157
+ const chips: CalendarChipOption[] = [
158
+ { label: 'Today', value: 'today', days: 0 },
159
+ { label: 'Last 7 days', value: 'last7', days: 7 },
160
+ { label: 'Last 30 days', value: 'last30', days: 30 },
161
+ ];
162
+
163
+ const [activeChip, setActiveChip] = useState<string | null>(null);
164
+ const [date, setDate] = useState<Date | null>(null);
165
+
166
+ <DatePicker
167
+ chips={chips}
168
+ activeChip={activeChip}
169
+ onChipSelect={setActiveChip}
170
+ selectedDate={date}
171
+ onChange={(d) => setDate(d as Date | null)}
172
+ />;
112
173
  ```
113
174
 
114
- ## API Reference
175
+ ### Sizes
115
176
 
116
- ### DatePicker
177
+ ```tsx
178
+ <DatePicker size="xs" placeholder="Extra small" />
179
+ <DatePicker size="sm" placeholder="Small" />
180
+ <DatePicker size="md" placeholder="Medium" />
181
+ <DatePicker size="lg" placeholder="Large" />
182
+ <DatePicker size="xl" placeholder="Extra large" />
183
+ ```
117
184
 
118
- **DatePickerProps:**
185
+ ### Min/max date
119
186
 
120
- | Prop | Type | Default | Description |
121
- | :--- | :--- | :------ | :---------- |
122
- | selectedDate | `Date` | - | Selected date for single mode. |
123
- | startDate | `Date` | - | Start date for range mode. |
124
- | endDate | `Date` | - | End date for range mode. |
125
- | selectsRange | `boolean` | `false` | Enable date range selection. |
126
- | onChange | `(date: Date \| [Date, Date]) => void` | - | Date change callback. |
127
- | size | `"xs" \| "sm" \| "md" \| "lg" \| "xl"` | `"md"` | Input size variant. |
128
- | locale | `string` | `"enUS"` | Date-fns locale identifier. |
129
- | placeholder | `string` | `"MM/DD/YYYY"` | Input placeholder text. |
130
- | minDate | `Date` | - | Minimum selectable date. |
131
- | maxDate | `Date` | - | Maximum selectable date. |
132
- | backgroundColor | `string` | - | Custom background color. |
133
- | chips | `CalendarChipOption[]` | - | Preset date range chips. |
134
- | activeChip | `string \| null` | - | Currently active chip value. |
135
- | onChipSelect | `(value: string) => void` | - | Chip selection callback. |
136
- | testID | `string` | - | Test identifier. |
137
-
138
- ## Date Format
139
-
140
- The component displays dates in `MM/DD/YYYY` format:
141
-
142
- | Mode | Display Format |
143
- | :--- | :------------- |
144
- | Single | `01/15/2024` |
145
- | Range | `01/15/2024 - 01/20/2024` |
146
-
147
- ## Calendar Features
148
-
149
- - **Month navigation**: Previous/next month buttons
150
- - **Year navigation**: Year selection dropdown
151
- - **Today indicator**: Current date is highlighted
152
- - **Selected state**: Selected date(s) have distinct styling
153
- - **Range highlighting**: Dates between start and end are highlighted
154
- - **Disabled dates**: Dates outside min/max range are disabled
155
- - **Preset chips**: Quick-select date ranges (Today, Last 7 days, etc.)
156
-
157
- ## Behavior
158
-
159
- - Calendar opens on input focus
160
- - Calendar closes when a date is selected (single mode)
161
- - Calendar closes when both dates are selected (range mode)
162
- - Clicking outside closes the calendar
163
- - Input value updates immediately on selection
187
+ ```tsx
188
+ const [date, setDate] = useState<Date | null>(null);
189
+
190
+ <DatePicker
191
+ selectedDate={date}
192
+ onChange={(d) => setDate(d as Date | null)}
193
+ minDate={new Date(2024, 0, 1)}
194
+ maxDate={new Date(2024, 11, 31)}
195
+ />;
196
+ ```
164
197
 
165
198
  ## Accessibility
166
199
 
167
- - Input is keyboard accessible
168
- - Calendar dates are navigable via keyboard
169
- - Selected dates are announced to screen readers
170
- - Focus is managed when calendar opens/closes
200
+ - The input is keyboard accessible; the calendar opens on focus.
201
+ - Calendar dates are navigable via keyboard; selected dates are announced to screen readers.
202
+ - Focus is restored to the input when the calendar closes.
203
+ - Dates outside `minDate`/`maxDate` are disabled.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@xsolla/xui-date-picker",
3
- "version": "0.149.1",
3
+ "version": "0.151.0",
4
4
  "main": "./web/index.js",
5
5
  "module": "./web/index.mjs",
6
6
  "types": "./web/index.d.ts",
@@ -13,10 +13,10 @@
13
13
  "test:coverage": "vitest run --coverage"
14
14
  },
15
15
  "dependencies": {
16
- "@xsolla/xui-calendar": "0.149.1",
17
- "@xsolla/xui-core": "0.149.1",
18
- "@xsolla/xui-input": "0.149.1",
19
- "@xsolla/xui-primitives-core": "0.149.1",
16
+ "@xsolla/xui-calendar": "0.151.0",
17
+ "@xsolla/xui-core": "0.151.0",
18
+ "@xsolla/xui-input": "0.151.0",
19
+ "@xsolla/xui-primitives-core": "0.151.0",
20
20
  "date-fns": "^3.0.0"
21
21
  },
22
22
  "peerDependencies": {