@xsolla/xui-calendar 0.117.0-pr187.1773275482

package/README.md

@@ -0,0 +1,218 @@
+# Calendar
+
+A cross-platform React calendar component supporting single date selection, date range selection, preset date chips, and a dual (side-by-side) calendar layout.
+
+## Installation
+
+```bash
+npm install @xsolla/xui-calendar
+# or
+yarn add @xsolla/xui-calendar
+```
+
+## Demo
+
+### Single Date Selection
+
+```tsx
+import * as React from 'react';
+import { Calendar } from '@xsolla/xui-calendar';
+
+export default function SingleDate() {
+  const [date, setDate] = React.useState<Date | null>(null);
+
+  return (
+    <Calendar
+      selectedDate={date}
+      onChange={(newDate) => setDate(newDate as Date)}
+    />
+  );
+}
+```
+
+### Date Range Selection
+
+```tsx
+import * as React from 'react';
+import { Calendar } from '@xsolla/xui-calendar';
+
+export default function DateRange() {
+  const [startDate, setStartDate] = React.useState<Date | null>(null);
+  const [endDate, setEndDate] = React.useState<Date | null>(null);
+
+  return (
+    <Calendar
+      selectsRange
+      startDate={startDate}
+      endDate={endDate}
+      onChange={(range) => {
+        const [start, end] = range as [Date | null, Date | null];
+        setStartDate(start);
+        setEndDate(end);
+      }}
+    />
+  );
+}
+```
+
+### With Preset Chips
+
+```tsx
+import * as React from 'react';
+import { Calendar } from '@xsolla/xui-calendar';
+
+const chips = [
+  { label: 'Today', value: 'today' },
+  { label: 'Last 7 days', value: 'last7' },
+  { label: 'Last 30 days', value: 'last30' },
+  { label: 'Last 90 days', value: 'last90' },
+];
+
+export default function WithChips() {
+  const [date, setDate] = React.useState<Date | null>(null);
+  const [activeChip, setActiveChip] = React.useState<string | null>('last30');
+
+  return (
+    <Calendar
+      selectedDate={date}
+      onChange={(newDate) => setDate(newDate as Date)}
+      chips={chips}
+      activeChip={activeChip}
+      onChipSelect={setActiveChip}
+    />
+  );
+}
+```
+
+### Dual Calendar (Side-by-Side)
+
+```tsx
+import * as React from 'react';
+import { DualCalendar } from '@xsolla/xui-calendar';
+
+export default function DualRange() {
+  const [startDate, setStartDate] = React.useState<Date | null>(null);
+  const [endDate, setEndDate] = React.useState<Date | null>(null);
+
+  return (
+    <DualCalendar
+      startDate={startDate}
+      endDate={endDate}
+      onChange={(dates) => {
+        const [start, end] = dates;
+        setStartDate(start);
+        setEndDate(end);
+      }}
+    />
+  );
+}
+```
+
+## Anatomy
+
+```
++---------------------------------------+
+|  [Custom top-content]                 |  <- topContent slot
+|  [Today] [Last 7d] [Last 30d] ...    |  <- CalendarChips
+|  <- [Month ▾] [Year ▾] ->            |  <- CalendarHeader
+|  SU  MO  TU  WE  TH  FR  SA         |  <- CalendarGrid weekday row
+|  29  30  31   1   2   3   4          |
+|   5   6   7   8   9  10  11          |
+|  12  13  14 [15]  16  17  18         |  <- [15] = today/selected
+|  23  20  21  22  23  24  25          |
+|  26  27  28  29  30   1   2          |
+|  [Custom bottom-content]             |  <- bottomContent slot
++---------------------------------------+
+```
+
+## API Reference
+
+### Calendar
+
+| Prop | Type | Default | Description |
+| :--- | :--- | :------ | :---------- |
+| selectedDate | `Date \| null` | - | Selected date for single mode. |
+| startDate | `Date \| null` | - | Start date for range mode. |
+| endDate | `Date \| null` | - | End date for range mode. |
+| selectsRange | `boolean` | `false` | Enable date range selection. |
+| onChange | `(date: Date \| [Date, Date]) => void` | - | Date change callback. |
+| locale | `string` | `"enUS"` | Date-fns locale identifier. |
+| firstDayOfWeek | `number` | `0` | First day of week (0=Sun, 6=Sat). |
+| initialMonth | `Date` | - | Initial month to display. |
+| month | `Date` | - | Controlled month to display. |
+| minDate | `Date \| null` | - | Minimum selectable date. |
+| maxDate | `Date \| null` | - | Maximum selectable date. |
+| chips | `CalendarChipOption[]` | - | Preset date range chips. |
+| activeChip | `string \| null` | - | Currently active chip value. |
+| onChipSelect | `(value: string) => void` | - | Chip selection callback. |
+| topContent | `({ close }) => ReactNode` | - | Custom content above chips. |
+| bottomContent | `({ close }) => ReactNode` | - | Custom content below grid. |
+| contextMenuMaxHeight | `number` | - | Max height for month/year dropdowns. |
+| testID | `string` | - | Test identifier. |
+
+### DualCalendar
+
+| Prop | Type | Default | Description |
+| :--- | :--- | :------ | :---------- |
+| startDate | `Date \| null` | - | Start date of selected range. |
+| endDate | `Date \| null` | - | End date of selected range. |
+| onChange | `(dates: [Date, Date]) => void` | - | Range change callback. |
+| locale | `string` | `"enUS"` | Date-fns locale identifier. |
+| firstDayOfWeek | `number` | `0` | First day of week (0=Sun, 6=Sat). |
+| initialMonth | `Date` | - | Initial month for left calendar. |
+| month | `Date` | - | Controlled month for left calendar. |
+| minDate | `Date \| null` | - | Minimum selectable date. |
+| maxDate | `Date \| null` | - | Maximum selectable date. |
+| chips | `CalendarChipOption[]` | - | Shared preset date range chips. |
+| activeChip | `string \| null` | - | Currently active chip value. |
+| onChipSelect | `(value: string) => void` | - | Chip selection callback. |
+| topContent | `({ close }) => ReactNode` | - | Custom content above chips. |
+| bottomContent | `({ close }) => ReactNode` | - | Custom content below grids. |
+| contextMenuMaxHeight | `number` | - | Max height for month/year dropdowns. |
+| testID | `string` | - | Test identifier. |
+
+### CalendarChips
+
+| Prop | Type | Default | Description |
+| :--- | :--- | :------ | :---------- |
+| chips | `CalendarChipOption[]` | required | Array of chip options. |
+| activeChip | `string \| null` | - | Currently active chip value. |
+| onChipSelect | `(value: string) => void` | - | Chip selection callback. |
+| testID | `string` | - | Test identifier. |
+
+### CalendarChipOption
+
+```ts
+interface CalendarChipOption {
+  label: string;
+  value: string;
+}
+```
+
+### CalendarGrid
+
+| Prop | Type | Default | Description |
+| :--- | :--- | :------ | :---------- |
+| currentMonth | `Date` | required | The month to render. |
+| locale | `string` | `"enUS"` | Date-fns locale identifier. |
+| firstDayOfWeek | `number` | `0` | First day of week. |
+| selectsRange | `boolean` | `false` | Enable range mode. |
+| minDate | `Date \| null` | - | Minimum selectable date. |
+| maxDate | `Date \| null` | - | Maximum selectable date. |
+| startDate | `Date \| null` | - | Range start date. |
+| endDate | `Date \| null` | - | Range end date. |
+| selectedDate | `Date \| null` | - | Selected date (single mode). |
+| selectingRange | `Date \| null` | - | Intermediate range selection. |
+| onDayPress | `(date: Date) => void` | - | Day press callback. |
+| testID | `string` | - | Test identifier. |
+
+## Platform Support
+
+This package works on both **web** and **React Native**. All components use cross-platform primitives (`Box`, `Text`) and avoid DOM-specific APIs.
+
+## Accessibility
+
+- Navigation buttons have aria-labels ("Previous month", "Next month")
+- Month and year selectors are accessible via Select component
+- Day cells support keyboard navigation
+- Chip selection follows radio-group pattern (single active item)

package/native/index.d.mts

@@ -0,0 +1,211 @@
+import * as react from 'react';
+import react__default, { ReactNode } from 'react';
+import * as locales from 'date-fns/locale';
+
+type CalendarLocaleType = keyof typeof locales;
+interface CalendarChipOption {
+    label: string;
+    value: string;
+}
+interface CalendarChipsProps {
+    /**
+     * Array of chip options to display.
+     */
+    chips: CalendarChipOption[];
+    /**
+     * The currently active chip value.
+     */
+    activeChip?: string | null;
+    /**
+     * Callback fired when a chip is selected.
+     */
+    onChipSelect?: (value: string) => void;
+    /**
+     * Test ID for testing frameworks
+     */
+    testID?: string;
+}
+interface CalendarGridProps {
+    currentMonth: Date;
+    locale?: CalendarLocaleType;
+    firstDayOfWeek?: number;
+    selectsRange?: boolean;
+    minDate?: Date | null;
+    maxDate?: Date | null;
+    startDate?: Date | null;
+    endDate?: Date | null;
+    selectedDate?: Date | null;
+    selectingRange?: Date | null;
+    onDayPress?: (date: Date) => void;
+    testID?: string;
+}
+interface CalendarHeaderProps {
+    monthDate: Date;
+    decreaseMonth: () => void;
+    increaseMonth: () => void;
+    changeYear: (year: number) => void;
+    changeMonth: (month: number) => void;
+    prevMonthButtonDisabled?: boolean;
+    nextMonthButtonDisabled?: boolean;
+    locale: CalendarLocaleType;
+    minDate?: Date | null;
+    maxDate?: Date | null;
+    contextMenuMaxHeight?: number;
+}
+interface CalendarProps {
+    locale?: CalendarLocaleType;
+    /**
+     * The day to use as first day of the week, starting from 0 (Sunday) to 6 (Saturday).
+     */
+    firstDayOfWeek?: number;
+    /**
+     * The month to display in the calendar at first render.
+     */
+    initialMonth?: Date;
+    /**
+     * The month to display in the calendar.
+     */
+    month?: Date;
+    /**
+     * Select in range mode for calendar
+     */
+    selectsRange?: boolean;
+    /**
+     * The minimum selectable date
+     */
+    minDate?: Date | null;
+    /**
+     * The maximum selectable date
+     */
+    maxDate?: Date | null;
+    /**
+     * For range mode. Start date in selected period
+     */
+    startDate?: Date | null;
+    /**
+     * For range mode. End date in selected period
+     */
+    endDate?: Date | null;
+    /**
+     * The selected date
+     */
+    selectedDate?: Date | null;
+    /**
+     * Property sets the maximum height of a context menus for selecting month and year.
+     */
+    contextMenuMaxHeight?: number;
+    /**
+     * Returns custom content to display above the calendar's date picker.
+     */
+    topContent?: (datePicker: {
+        close: () => void;
+    }) => ReactNode;
+    /**
+     * Returns custom content to display beneath the calendar's date picker.
+     */
+    bottomContent?: (datePicker: {
+        close: () => void;
+    }) => ReactNode;
+    /**
+     * Preset chip options displayed above the calendar header.
+     */
+    chips?: CalendarChipOption[];
+    /**
+     * The currently active chip value.
+     */
+    activeChip?: string | null;
+    /**
+     * Callback fired when a chip is selected.
+     */
+    onChipSelect?: (value: string) => void;
+    /**
+     * Test ID for testing frameworks
+     */
+    testID?: string;
+    /**
+     * Callback fired when the date changes
+     */
+    onChange?: (date: Date | [Date | null, Date | null]) => void;
+}
+interface DualCalendarProps {
+    locale?: CalendarLocaleType;
+    /**
+     * The day to use as first day of the week, starting from 0 (Sunday) to 6 (Saturday).
+     */
+    firstDayOfWeek?: number;
+    /**
+     * The month to display in the left calendar at first render.
+     */
+    initialMonth?: Date;
+    /**
+     * The month to display in the left calendar (controlled).
+     */
+    month?: Date;
+    /**
+     * The minimum selectable date
+     */
+    minDate?: Date | null;
+    /**
+     * The maximum selectable date
+     */
+    maxDate?: Date | null;
+    /**
+     * Start date of the selected range
+     */
+    startDate?: Date | null;
+    /**
+     * End date of the selected range
+     */
+    endDate?: Date | null;
+    /**
+     * Property sets the maximum height of a context menus for selecting month and year.
+     */
+    contextMenuMaxHeight?: number;
+    /**
+     * Returns custom content to display above the calendars.
+     */
+    topContent?: (datePicker: {
+        close: () => void;
+    }) => ReactNode;
+    /**
+     * Returns custom content to display beneath the calendars.
+     */
+    bottomContent?: (datePicker: {
+        close: () => void;
+    }) => ReactNode;
+    /**
+     * Preset chip options displayed above the calendar headers.
+     */
+    chips?: CalendarChipOption[];
+    /**
+     * The currently active chip value.
+     */
+    activeChip?: string | null;
+    /**
+     * Callback fired when a chip is selected.
+     */
+    onChipSelect?: (value: string) => void;
+    /**
+     * Test ID for testing frameworks
+     */
+    testID?: string;
+    /**
+     * Callback fired when the date range changes.
+     */
+    onChange?: (dates: [Date | null, Date | null]) => void;
+}
+
+declare const Calendar: react.ForwardRefExoticComponent<CalendarProps & react.RefAttributes<any>>;
+
+declare const DualCalendar: react.ForwardRefExoticComponent<DualCalendarProps & react.RefAttributes<any>>;
+
+declare const CalendarHeader: react__default.FC<CalendarHeaderProps>;
+
+declare const CalendarGrid: react__default.FC<CalendarGridProps>;
+
+declare const CalendarChips: react__default.FC<CalendarChipsProps>;
+
+declare function formatDate(date: Date, formatStr: string, locale?: CalendarLocaleType): string;
+declare function getMonthInLocale(month: number, locale?: CalendarLocaleType): string;
+
+export { Calendar, type CalendarChipOption, CalendarChips, type CalendarChipsProps, CalendarGrid, type CalendarGridProps, CalendarHeader, type CalendarHeaderProps, type CalendarLocaleType, type CalendarProps, DualCalendar, type DualCalendarProps, formatDate, getMonthInLocale };

package/native/index.d.ts

@@ -0,0 +1,211 @@
+import * as react from 'react';
+import react__default, { ReactNode } from 'react';
+import * as locales from 'date-fns/locale';
+
+type CalendarLocaleType = keyof typeof locales;
+interface CalendarChipOption {
+    label: string;
+    value: string;
+}
+interface CalendarChipsProps {
+    /**
+     * Array of chip options to display.
+     */
+    chips: CalendarChipOption[];
+    /**
+     * The currently active chip value.
+     */
+    activeChip?: string | null;
+    /**
+     * Callback fired when a chip is selected.
+     */
+    onChipSelect?: (value: string) => void;
+    /**
+     * Test ID for testing frameworks
+     */
+    testID?: string;
+}
+interface CalendarGridProps {
+    currentMonth: Date;
+    locale?: CalendarLocaleType;
+    firstDayOfWeek?: number;
+    selectsRange?: boolean;
+    minDate?: Date | null;
+    maxDate?: Date | null;
+    startDate?: Date | null;
+    endDate?: Date | null;
+    selectedDate?: Date | null;
+    selectingRange?: Date | null;
+    onDayPress?: (date: Date) => void;
+    testID?: string;
+}
+interface CalendarHeaderProps {
+    monthDate: Date;
+    decreaseMonth: () => void;
+    increaseMonth: () => void;
+    changeYear: (year: number) => void;
+    changeMonth: (month: number) => void;
+    prevMonthButtonDisabled?: boolean;
+    nextMonthButtonDisabled?: boolean;
+    locale: CalendarLocaleType;
+    minDate?: Date | null;
+    maxDate?: Date | null;
+    contextMenuMaxHeight?: number;
+}
+interface CalendarProps {
+    locale?: CalendarLocaleType;
+    /**
+     * The day to use as first day of the week, starting from 0 (Sunday) to 6 (Saturday).
+     */
+    firstDayOfWeek?: number;
+    /**
+     * The month to display in the calendar at first render.
+     */
+    initialMonth?: Date;
+    /**
+     * The month to display in the calendar.
+     */
+    month?: Date;
+    /**
+     * Select in range mode for calendar
+     */
+    selectsRange?: boolean;
+    /**
+     * The minimum selectable date
+     */
+    minDate?: Date | null;
+    /**
+     * The maximum selectable date
+     */
+    maxDate?: Date | null;
+    /**
+     * For range mode. Start date in selected period
+     */
+    startDate?: Date | null;
+    /**
+     * For range mode. End date in selected period
+     */
+    endDate?: Date | null;
+    /**
+     * The selected date
+     */
+    selectedDate?: Date | null;
+    /**
+     * Property sets the maximum height of a context menus for selecting month and year.
+     */
+    contextMenuMaxHeight?: number;
+    /**
+     * Returns custom content to display above the calendar's date picker.
+     */
+    topContent?: (datePicker: {
+        close: () => void;
+    }) => ReactNode;
+    /**
+     * Returns custom content to display beneath the calendar's date picker.
+     */
+    bottomContent?: (datePicker: {
+        close: () => void;
+    }) => ReactNode;
+    /**
+     * Preset chip options displayed above the calendar header.
+     */
+    chips?: CalendarChipOption[];
+    /**
+     * The currently active chip value.
+     */
+    activeChip?: string | null;
+    /**
+     * Callback fired when a chip is selected.
+     */
+    onChipSelect?: (value: string) => void;
+    /**
+     * Test ID for testing frameworks
+     */
+    testID?: string;
+    /**
+     * Callback fired when the date changes
+     */
+    onChange?: (date: Date | [Date | null, Date | null]) => void;
+}
+interface DualCalendarProps {
+    locale?: CalendarLocaleType;
+    /**
+     * The day to use as first day of the week, starting from 0 (Sunday) to 6 (Saturday).
+     */
+    firstDayOfWeek?: number;
+    /**
+     * The month to display in the left calendar at first render.
+     */
+    initialMonth?: Date;
+    /**
+     * The month to display in the left calendar (controlled).
+     */
+    month?: Date;
+    /**
+     * The minimum selectable date
+     */
+    minDate?: Date | null;
+    /**
+     * The maximum selectable date
+     */
+    maxDate?: Date | null;
+    /**
+     * Start date of the selected range
+     */
+    startDate?: Date | null;
+    /**
+     * End date of the selected range
+     */
+    endDate?: Date | null;
+    /**
+     * Property sets the maximum height of a context menus for selecting month and year.
+     */
+    contextMenuMaxHeight?: number;
+    /**
+     * Returns custom content to display above the calendars.
+     */
+    topContent?: (datePicker: {
+        close: () => void;
+    }) => ReactNode;
+    /**
+     * Returns custom content to display beneath the calendars.
+     */
+    bottomContent?: (datePicker: {
+        close: () => void;
+    }) => ReactNode;
+    /**
+     * Preset chip options displayed above the calendar headers.
+     */
+    chips?: CalendarChipOption[];
+    /**
+     * The currently active chip value.
+     */
+    activeChip?: string | null;
+    /**
+     * Callback fired when a chip is selected.
+     */
+    onChipSelect?: (value: string) => void;
+    /**
+     * Test ID for testing frameworks
+     */
+    testID?: string;
+    /**
+     * Callback fired when the date range changes.
+     */
+    onChange?: (dates: [Date | null, Date | null]) => void;
+}
+
+declare const Calendar: react.ForwardRefExoticComponent<CalendarProps & react.RefAttributes<any>>;
+
+declare const DualCalendar: react.ForwardRefExoticComponent<DualCalendarProps & react.RefAttributes<any>>;
+
+declare const CalendarHeader: react__default.FC<CalendarHeaderProps>;
+
+declare const CalendarGrid: react__default.FC<CalendarGridProps>;
+
+declare const CalendarChips: react__default.FC<CalendarChipsProps>;
+
+declare function formatDate(date: Date, formatStr: string, locale?: CalendarLocaleType): string;
+declare function getMonthInLocale(month: number, locale?: CalendarLocaleType): string;
+
+export { Calendar, type CalendarChipOption, CalendarChips, type CalendarChipsProps, CalendarGrid, type CalendarGridProps, CalendarHeader, type CalendarHeaderProps, type CalendarLocaleType, type CalendarProps, DualCalendar, type DualCalendarProps, formatDate, getMonthInLocale };