react-modular-datepicker 0.0.2-canary.4 → 0.0.2

package/README.md

@@ -1,2 +1,218 @@
 # react-modular-datepicker
- A headless datepicker
+
+A modular, lightweight, and type-safe React datepicker library. Whether you need a fully-featured calendar component or a headless hook to build your own UI, `react-modular-datepicker` has you covered.
+
+## Strengths
+
+- 🏗️ **Headless & Modular**: Use the `useDates` hook for complete control over your UI, or the `Calendar` component for a beautiful, ready-to-use setup.
+- 🪶 **Lightweight**: Small footprint with a pluggable adapter system (defaults to Day.js).
+- 🛡️ **Type-safe**: Written in TypeScript for a great developer experience.
+- 🎨 **Fully Customizable**: Style everything via Tailwind CSS or custom class names.
+- 🌍 **Localized**: Easy internationalization support with `dayjs` or custom adapters.
+- ⚡ **Feature-rich**: Single, multiple, and range selection modes, min/max dates, disabled dates, and more.
+
+---
+
+## API Reference
+
+### Imports
+
+```tsx
+import {
+  Calendar,
+  useDates,
+  Dates,
+  Day,
+  DayjsAdapter,
+  defaultAdapter
+} from 'react-modular-datepicker';
+```
+
+### `Calendar` Component
+
+The primary component for a ready-to-use calendar.
+
+| Prop | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `date` | `Date` | `new Date()` | The initial date/month to display. |
+| `selected` | `Date \| Date[] \| Range` | `undefined` | The currently selected date(s). |
+| `selectionMode` | `'single' \| 'range' \| 'multiple'` | `'single'` | The selection behavior. |
+| `onChange` | `(selected: any) => void` | `undefined` | Callback triggered when the selection changes. |
+| `minDate` | `Date` | `undefined` | The earliest selectable date. |
+| `maxDate` | `Date` | `undefined` | The latest selectable date. |
+| `disabledDates` | `Date[]` | `undefined` | An array of dates that should be disabled. |
+| `monthsToDisplay` | `number` | `1` | Number of months to show simultaneously. |
+| `firstDayOfWeek` | `number` | `0` | The first day of the week (0=Sun, 1=Mon, ...). |
+| `showOutsideDays` | `boolean` | `false` | Whether to show days from the previous/next months. |
+| `classNames` | `CalendarClassNames` | `undefined` | Custom classes for styling various parts of the UI. |
+| `locale` | `string` | `undefined` | Locale for date formatting (e.g., 'fr', 'es'). |
+| `translations` | `Partial<Translations>` | `undefined` | Custom translation strings for "Back" and "Forward". |
+| `adapter` | `DateAdapter` | `defaultAdapter` | The date management adapter (e.g., DayjsAdapter). |
+
+### `useDates` Hook
+
+The logic core of the library. It handles selection, navigation, and grid generation.
+
+```typescript
+const {
+  calendars,
+  getDateProps,
+  getBackProps,
+  getForwardProps,
+  setOffset
+} = useDates(props: UseDatesProps);
+```
+
+**`UseDatesProps`** includes all props from `Calendar` (except `classNames`, `locale`, `translations`) plus:
+- `onDateSelected`: `(dateObj: DateObj, event: any) => void`
+- `onOffsetChanged`: `(newOffset: number) => void`
+- `modifiers`: `Record<string, (date: Date) => boolean>`
+
+### Main Types
+
+#### `DateObj`
+Represents a single day in the calendar grid.
+- `date`: `Date`
+- `selected`: `boolean`
+- `selectable`: `boolean`
+- `today`: `boolean`
+- `prevMonth`/`nextMonth`: `boolean` (if outside current month)
+- `isRangeStart`/`isRangeEnd`/`isRangeBetween`/`isRangeHovering`: `boolean`
+- `modifiers`: `string[]`
+
+#### `Calendar`
+Represents a month grid.
+- `month`: `number` (0-11)
+- `year`: `number`
+- `weeks`: `(DateObj | null)[][]`
+
+---
+
+## Recipes
+
+<details>
+<summary><b>Basic Selection</b></summary>
+A simple single-date selection calendar.
+
+```tsx
+import { Calendar } from 'react-modular-datepicker';
+import 'react-modular-datepicker/dist/index.css';
+
+function BasicExample() {
+  return <Calendar onChange={(date) => console.log(date)} />;
+}
+```
+
+</details>
+
+<details>
+<summary><b>Range Selection</b></summary>
+Select a start and end date with a beautiful hover preview.
+
+```tsx
+<Calendar
+  selectionMode="range"
+  monthsToDisplay={2}
+  onChange={(range) => console.log(range)}
+/>
+```
+
+</details>
+
+<details>
+<summary><b>Multiple Selection</b></summary>
+Select as many dates as you want.
+
+```tsx
+<Calendar
+  selectionMode="multiple"
+  onChange={(dates) => console.log(dates)}
+/>
+```
+
+</details>
+
+<details>
+<summary><b>Headless Usage</b></summary>
+Complete freedom over your UI using the `useDates` hook.
+
+```tsx
+const { calendars, getDateProps } = useDates({ selectionMode: 'single' });
+
+return (
+  <div className="grid grid-cols-7">
+    {calendars[0].weeks.flat().map((dateObj, i) => (
+      dateObj ? (
+        <button key={i} {...getDateProps({ dateObj })}>
+          {dateObj.date.getDate()}
+        </button>
+      ) : <div key={i} />
+    ))}
+  </div>
+);
+```
+
+</details>
+
+<details>
+<summary><b>Custom Styling</b></summary>
+Easily customize the look and feel using the `classNames` prop.
+
+```tsx
+<Calendar
+  classNames={{
+    root: 'bg-indigo-900 text-white',
+    day: {
+      selected: 'bg-pink-500 text-white',
+      today: 'border-pink-500 text-pink-500',
+    }
+  }}
+/>
+```
+
+</details>
+
+---
+
+## Contributors
+
+We welcome contributions! Here’s how you can get started:
+
+### Installation
+
+1. Clone the repository.
+2. Install dependencies:
+   ```bash
+   pnpm install
+   ```
+
+### Development
+
+Start the development server with the example app:
+```bash
+pnpm run dev
+```
+This runs `vite` in watch mode for the library and starts the Next.js example app at `http://localhost:3000`.
+
+### Testing
+
+Run end-to-end tests using Playwright:
+```bash
+pnpm run test:e2e
+```
+
+### Documentation & Examples
+
+- To update documentation, edit the `README.md`.
+- To add or modify examples, check the `examples/` directory.
+
+### Building
+
+Build the package for production:
+```bash
+pnpm run build
+```
+
+---
+
+License: MIT

package/dist/adapters/dayjs.d.ts

@@ -0,0 +1,21 @@
+import { Dayjs } from 'dayjs';
+import { DateAdapter } from '../types';
+export declare class DayjsAdapter implements DateAdapter<Dayjs> {
+    date(value?: any): Dayjs;
+    add(date: Dayjs, amount: number, unit: 'day' | 'month' | 'year'): Dayjs;
+    subtract(date: Dayjs, amount: number, unit: 'day' | 'month' | 'year'): Dayjs;
+    startOf(date: Dayjs, unit: 'day' | 'month' | 'year'): Dayjs;
+    endOf(date: Dayjs, unit: 'day' | 'month' | 'year'): Dayjs;
+    isBefore(date: Dayjs, comparison: Dayjs, unit?: 'day' | 'month' | 'year'): boolean;
+    isAfter(date: Dayjs, comparison: Dayjs, unit?: 'day' | 'month' | 'year'): boolean;
+    isSame(date: Dayjs, comparison: Dayjs, unit?: 'day' | 'month' | 'year'): boolean;
+    set(date: Dayjs, unit: 'day' | 'month' | 'year', value: number): Dayjs;
+    get(date: Dayjs, unit: 'day' | 'month' | 'year'): number;
+    format(date: Dayjs, formatStr: string, locale?: string): string;
+    getDaysInMonth(date: Dayjs): number;
+    toDate(date: Dayjs): Date;
+    diff(date: Dayjs, comparison: Dayjs, unit: 'month' | 'year'): number;
+    getMonths(locale?: string): string[];
+    getWeekdays(locale?: string): string[];
+}
+export declare const defaultAdapter: DayjsAdapter;

package/dist/classNames.d.ts

@@ -0,0 +1,67 @@
+export interface DayClassNames {
+    day?: string;
+    selected?: string;
+    unselected?: string;
+    disabled?: string;
+    rangeStart?: string;
+    rangeEnd?: string;
+    rangeBetween?: string;
+    rangeHovering?: string;
+    [key: string]: string | undefined;
+}
+export declare const defaultClassNames: {
+    root: string;
+    header: string;
+    calendarsContainer: string;
+    calendarContainer: string;
+    weekdayGrid: string;
+    weekday: string;
+    daysGrid: string;
+    footer: string;
+    navButton: string;
+    monthYearContainer: string;
+    monthYearLabel: string;
+    monthYearButton: string;
+    day: {
+        day: string;
+        selected: string;
+        unselected: string;
+        disabled: string;
+        rangeStart: string;
+        rangeEnd: string;
+        rangeBetween: string;
+        rangeHovering: string;
+    };
+    monthsGrid: string;
+    monthButton: string;
+    monthButtonSelected: string;
+    monthButtonUnselected: string;
+    yearsGrid: string;
+    yearButton: string;
+    yearButtonSelected: string;
+    yearButtonUnselected: string;
+};
+export interface CalendarClassNames {
+    root?: string;
+    header?: string;
+    calendarsContainer?: string;
+    calendarContainer?: string;
+    weekdayGrid?: string;
+    weekday?: string;
+    daysGrid?: string;
+    footer?: string;
+    navButton?: string;
+    monthYearContainer?: string;
+    monthYearLabel?: string;
+    monthYearButton?: string;
+    day?: DayClassNames;
+    monthsGrid?: string;
+    monthButton?: string;
+    monthButtonSelected?: string;
+    monthButtonUnselected?: string;
+    yearsGrid?: string;
+    yearButton?: string;
+    yearButtonSelected?: string;
+    yearButtonUnselected?: string;
+}
+export declare const mergeClassNames: (custom?: CalendarClassNames) => Required<CalendarClassNames>;

package/dist/components/Calendar.d.ts

@@ -0,0 +1,14 @@
+import { default as React } from 'react';
+import { UseDatesProps } from '../useDates';
+import { Translations } from '../i18n';
+import { DateObj, CalendarClassNames } from '../types';
+interface CalendarProps extends UseDatesProps {
+    classNames?: CalendarClassNames;
+    locale?: string;
+    translations?: Partial<Translations>;
+    header?: React.ReactNode | ((props: any) => React.ReactNode);
+    footer?: React.ReactNode;
+    renderDayTooltip?: (dateObj: DateObj) => React.ReactNode;
+}
+export declare const Calendar: React.FC<CalendarProps>;
+export {};

package/dist/components/CalendarHeader.d.ts

@@ -0,0 +1,19 @@
+import { default as React } from 'react';
+import { Calendar, CalendarClassNames } from '../types';
+export interface HeaderProps {
+    calendars: Calendar[];
+    getBackProps: (args: any) => any;
+    getForwardProps: (args: any) => any;
+    setView: (view: 'days' | 'months' | 'years') => void;
+    monthNames: string[];
+    t: {
+        back: string;
+        forward: string;
+    };
+    classNames: Required<CalendarClassNames>;
+    slideDirection?: 'left' | 'right' | null;
+    currentView?: 'days' | 'months' | 'years';
+}
+export declare const ChevronLeftIcon: () => React.JSX.Element;
+export declare const ChevronRightIcon: () => React.JSX.Element;
+export declare const CalendarHeader: React.FC<HeaderProps>;

package/dist/components/Day.d.ts

@@ -0,0 +1,13 @@
+import { default as React } from 'react';
+import { CalendarClassNames, DateObj } from '../types';
+interface DayProps {
+    dateObj: DateObj | null;
+    getDateProps: (args: {
+        dateObj: DateObj;
+        [key: string]: any;
+    }) => any;
+    tooltip?: React.ReactNode;
+    classNames: Required<CalendarClassNames>;
+}
+export declare const Day: React.FC<DayProps>;
+export {};

package/dist/components/MonthSelection.d.ts

@@ -0,0 +1,13 @@
+import { default as React } from 'react';
+import { CalendarClassNames } from '../types';
+interface MonthSelectionProps {
+    year: number;
+    month: number;
+    monthNames: string[];
+    minDate?: Date | null;
+    maxDate?: Date | null;
+    onMonthSelect: (month: number) => void;
+    classNames: Required<CalendarClassNames>;
+}
+export declare const MonthSelection: React.FC<MonthSelectionProps>;
+export {};

package/dist/components/YearSelection.d.ts

@@ -0,0 +1,12 @@
+import { default as React } from 'react';
+import { CalendarClassNames, DateAdapter } from '../types';
+interface YearSelectionProps {
+    year: number;
+    minDate?: Date | null;
+    maxDate?: Date | null;
+    adapter: DateAdapter;
+    onYearSelect: (year: number) => void;
+    classNames: Required<CalendarClassNames>;
+}
+export declare const YearSelection: React.FC<YearSelectionProps>;
+export {};

package/dist/i18n.d.ts

@@ -0,0 +1,9 @@
+import { DateAdapter } from './types';
+export interface Translations {
+    months: string[];
+    weekdays: string[];
+    back: string;
+    forward: string;
+}
+export declare function getDefaults(adapter?: DateAdapter, locale?: string): Translations;
+export declare function getTranslations(adapter?: DateAdapter, locale?: string, custom?: Partial<Translations>): Translations;