@mamrp/components 1.3.2 → 1.4.1

package/dist/date-pickers/index.d.mts

@@ -0,0 +1,391 @@
+import React__default from 'react';
+import { Control } from 'react-hook-form';
+import { DateView } from '@mui/x-date-pickers';
+import { Moment } from 'moment-jalaali';
+
+/**
+ * DateRangePicker - کامپوننت پیشرفته انتخاب بازه تاریخ شمسی
+ *
+ * یک کامپوننت کامل و حرفه‌ای برای انتخاب بازه تاریخ با پشتیبانی از تقویم فارسی/شمسی
+ * این کامپوننت از کتابخانه‌های MUI، moment-jalaali و react-icons استفاده می‌کند
+ *
+ * @version 3.0.0
+ * @author Frontend Team
+ * @since 2024
+ * @updated October 2025
+ *
+ * ویژگی‌های کلیدی:
+ * ✅ پشتیبانی کامل از تقویم شمسی (فارسی)
+ * ✅ انتخاب بازه تاریخ با نمایش visual و range highlighting
+ * ✅ Responsive design - سازگار با موبایل و دسکتاپ (breakpoint: 700px)
+ * ✅ سه حالت نمایش: تقویم popup، DatePicker جداگانه، یا تک/دوتایی
+ * ✅ تب‌های هوشمند: حالت خودکار و دستی برای انتخاب تاریخ
+ * ✅ آیکون‌های حرفه‌ای React Icons در تمام بخش‌ها
+ * ✅ آیکون پاک کردن در input با UX بهبود یافته
+ * ✅ سفارشی‌سازی کامل استایل و رنگ‌بندی
+ * ✅ پشتیبانی از validation با React Hook Form
+ * ✅ قابلیت تنظیم محدوده تاریخ (min/max)
+ * ✅ حالت loading و disabled
+ * ✅ چندین حالت text alignment (left, center, right)
+ * ✅ لیست ماه‌ها به صورت 3 ستونی با CSS Grid
+ * ✅ هایلایت روزهای جمعه، امروز و بازه انتخاب شده
+ * ✅ انیمیشن و hover effects
+ * ✅ تغییر خودکار تب در حالت دستی
+ * ✅ عدم بسته شدن پنجره بعد از پاک کردن
+ * ✅ راهنمای هوشمند برای کاربر
+ *
+ * نحوه استفاده:
+ * ```tsx
+ * import DateRangePicker from './components/date-range-picker';
+ * import { useForm } from 'react-hook-form';
+ *
+ * const MyComponent = () => {
+ *   const { control } = useForm();
+ *
+ *   return (
+ *     <DateRangePicker
+ *       fromDate="startDate"
+ *       toDate="endDate"
+ *       control={control}
+ *       label="انتخاب بازه تاریخ"
+ *       persian={true}
+ *       align="center"
+ *       clear={true}
+ *       dualCalendar={false}  // جدید: کنترل تقویم دوم
+ *       singleCalendar={false}
+ *       useMobilePickers={false}
+ *     />
+ *   );
+ * };
+ * ```
+ *
+ * مثال‌های مختلف:
+ *
+ * 1. حالت پایه (پیش‌فرض - تک تقویم با تب‌های هوشمند):
+ * ```tsx
+ * <DateRangePicker
+ *   fromDate="from"
+ *   toDate="to"
+ *   control={control}
+ * />
+ * ```
+ *
+ * 2. فعال کردن تقویم دوم:
+ * ```tsx
+ * <DateRangePicker
+ *   fromDate="from"
+ *   toDate="to"
+ *   control={control}
+ *   dualCalendar={true}  // تقویم دوم فعال می‌شود
+ * />
+ * ```
+ *
+ * 3. تک تقویم بدون تب‌های هوشمند:
+ * ```tsx
+ * <DateRangePicker
+ *   fromDate="from"
+ *   toDate="to"
+ *   control={control}
+ *   singleCalendar={true}
+ * />
+ * ```
+ *
+ * 4. حالت DatePicker جداگانه:
+ * ```tsx
+ * <DateRangePicker
+ *   fromDate="from"
+ *   toDate="to"
+ *   control={control}
+ *   useMobilePickers={true}
+ * />
+ * ```
+ *
+ * 5. با محدودیت تاریخ و سفارشی‌سازی:
+ * ```tsx
+ * <DateRangePicker
+ *   fromDate="from"
+ *   toDate="to"
+ *   control={control}
+ *   minDate={moment().subtract(1, 'year')}
+ *   maxDate={moment()}
+ *   label="بازه زمانی گزارش"
+ *   size="small"
+ *   align="center"
+ *   dualCalendar={true}
+ * />
+ * ```
+ *
+ * ویژگی‌های تب‌های هوشمند (جدید در v3.0):
+ *
+ * ```tsx
+ * // حالت هوشمند (پیش‌فرض): 🤖
+ * // - خودکار تشخیص می‌دهد کاربر کدام تاریخ را می‌خواهد
+ * // - اولین کلیک: تاریخ شروع ← تب "تا تاریخ" فعال
+ * // - دومین کلیک: تاریخ پایان (با تشخیص ترتیب)
+ * // - کلیک سوم: شروع مجدد
+ *
+ * // حالت دستی: 👤
+ * // - کاربر خودش تب را انتخاب می‌کند
+ * // - بعد از انتخاب "از تاریخ" ← خودکار به "تا تاریخ" می‌رود
+ * // - بعد از انتخاب "تا تاریخ" ← خودکار به "از تاریخ" برمی‌گردد
+ * ```
+ *
+ * آیکون‌های استفاده شده (React Icons):
+ *
+ * ```tsx
+ * // Input Icons:
+ * MdCalendarToday  // آیکون تقویم
+ * MdClear          // آیکون پاک کردن
+ *
+ * // Tab Icons:
+ * MdSmartToy       // حالت هوشمند
+ * MdPerson         // حالت دستی
+ * MdDateRange      // از تاریخ
+ * MdEvent          // تا تاریخ
+ *
+ * // Guide Icons:
+ * MdGpsFixed       // راهنمای انتخاب
+ * MdCheckCircle    // تأیید انتخاب
+ * ```
+ *
+ * @interface DateRangePickerProps
+ * @property {string} fromDate - نام فیلد تاریخ شروع در form
+ * @property {string} toDate - نام فیلد تاریخ پایان در form
+ * @property {Control<any>} control - React Hook Form control object
+ * @property {DateView[]} [fromViews] - نماهای قابل نمایش برای تاریخ شروع (پیش‌فرض: ["year", "month", "day"])
+ * @property {DateView} [fromOpenTo] - نمای ابتدایی برای تاریخ شروع (پیش‌فرض: "day")
+ * @property {DateView[]} [toViews] - نماهای قابل نمایش برای تاریخ پایان (پیش‌فرض: ["year", "month", "day"])
+ * @property {DateView} [toOpenTo] - نمای ابتدایی برای تاریخ پایان (پیش‌فرض: "day")
+ * @property {string} [label] - برچسب فیلد (پیش‌فرض: "انتخاب بازه")
+ * @property {"small" | "medium"} [size] - اندازه فیلد (پیش‌فرض: "medium")
+ * @property {boolean} [disabled] - غیرفعال کردن کامپوننت (پیش‌فرض: false)
+ * @property {boolean} [persian] - استفاده از تاریخ فارسی (پیش‌فرض: true)
+ * @property {"right" | "center" | "left"} [align] - تراز متن (پیش‌فرض: "left")
+ * @property {boolean} [isLoading] - نمایش حالت loading (پیش‌فرض: false)
+ * @property {Moment} [minDate] - حداقل تاریخ قابل انتخاب
+ * @property {Moment} [maxDate] - حداکثر تاریخ قابل انتخاب
+ * @property {boolean} [clear] - نمایش دکمه پاک کردن (پیش‌فرض: true)
+ * @property {boolean} [singleCalendar] - نمایش تک تقویم بدون تب‌ها (پیش‌فرض: false)
+ * @property {boolean} [useMobilePickers] - استفاده از DatePicker جداگانه (پیش‌فرض: false)
+ * @property {boolean} [dualCalendar] - فعال‌سازی تقویم دوم (پیش‌فرض: false)
+ *
+ * منطق نمایش تقویم‌ها:
+ * - اگر dualCalendar = true ← دو تقویم کنار هم
+ * - اگر singleCalendar = true ← تک تقویم بدون تب
+ * - اگر useMobilePickers = true ← دو DatePicker جداگانه
+ * - پیش‌فرض ← تک تقویم با تب‌های هوشمند
+ *
+ * نکات مهم:
+ * - کامپوننت خودکار mobile detection دارد (breakpoint: 700px)
+ * - در حالت موبایل، تقویم‌ها responsive می‌شوند
+ * - فرمت خروجی همیشه "YYYY-MM-DD" است
+ * - روزهای جمعه با رنگ قرمز نمایش داده می‌شوند
+ * - امکان انتخاب بازه با کلیک و visual feedback وجود دارد
+ * - validation errors از React Hook Form پشتیبانی می‌شود
+ * - آیکون پاک کردن فقط در صورت وجود تاریخ نمایش داده می‌شود
+ * - پاک کردن از داخل popup، پنجره را نمی‌بندد
+ * - پاک کردن از input icon، پنجره را باز نمی‌کند
+ *
+ * Dependencies:
+ * - @mui/material
+ * - @mui/x-date-pickers
+ * - @mui/x-date-pickers/AdapterMomentJalaali
+ * - moment-jalaali
+ * - react-hook-form
+ * - react-icons/md
+ *
+ * @example
+ * // استفاده در فرم با تمام قابلیت‌ها
+ * const form = useForm({
+ *   defaultValues: {
+ *     startDate: '',
+ *     endDate: ''
+ *   }
+ * });
+ *
+ * // حالت پیش‌فرض با تب‌های هوشمند
+ * <DateRangePicker
+ *   fromDate="startDate"
+ *   toDate="endDate"
+ *   control={form.control}
+ *   label="انتخاب دوره زمانی"
+ * />
+ *
+ * // حالت dual calendar
+ * <DateRangePicker
+ *   fromDate="startDate"
+ *   toDate="endDate"
+ *   control={form.control}
+ *   dualCalendar={true}
+ *   label="انتخاب بازه با دو تقویم"
+ * />
+ */
+
+interface DateRangePickerProps {
+    fromDate: string;
+    toDate: string;
+    fromViews?: DateView[] | undefined;
+    fromOpenTo?: DateView | undefined;
+    toViews?: DateView[] | undefined;
+    toOpenTo?: DateView | undefined;
+    control: Control<any>;
+    label?: string;
+    size?: "small" | "medium";
+    disabled?: boolean;
+    persian?: boolean;
+    align?: "right" | "center" | "left";
+    isLoading?: boolean;
+    minDate?: Moment;
+    maxDate?: Moment;
+    clear?: boolean;
+    singleCalendar?: boolean;
+    useMobilePickers?: boolean;
+    dualCalendar?: boolean;
+}
+/**
+ * DateRangePicker - کامپوننت انتخاب بازه تاریخ شمسی
+ *
+ * یک کامپوننت پیشرفته و کامل برای انتخاب بازه تاریخ با پشتیبانی از تقویم فارسی/شمسی
+ * این کامپوننت از کتابخانه‌های MUI و moment-jalaali استفاده می‌کند
+ *
+ * @version 2.0.0
+ * @author Frontend MAMRP Team
+ * @since 2024
+ *
+ *
+ * نحوه استفاده:
+ * ```tsx
+ * import DateRangePicker from './components/date-range-picker';
+ * import { useForm } from 'react-hook-form';
+ *
+ * const MyComponent = () => {
+ *   const { control } = useForm();
+ *
+ *   return (
+ *     <DateRangePicker
+ *       fromDate="startDate"
+ *       toDate="endDate"
+ *       control={control}
+ *       label="انتخاب بازه تاریخ"
+ *       persian={true}
+ *       align="center"
+ *       clear={true}
+ *       singleCalendar={false}
+ *       useMobilePickers={false}
+ *     />
+ *   );
+ * };
+ * ```
+ *
+ * مثال‌های مختلف:
+ *
+ * 1. حالت پایه:
+ * ```tsx
+ * <DateRangePicker
+ *   fromDate="from"
+ *   toDate="to"
+ *   control={control}
+ * />
+ * ```
+ *
+ * 2. با تک تقویم:
+ * ```tsx
+ * <DateRangePicker
+ *   fromDate="from"
+ *   toDate="to"
+ *   control={control}
+ *   singleCalendar={true}
+ * />
+ * ```
+ *
+ * 3. با DatePicker جداگانه:
+ * ```tsx
+ * <DateRangePicker
+ *   fromDate="from"
+ *   toDate="to"
+ *   control={control}
+ *   useMobilePickers={true}
+ * />
+ * ```
+ *
+ * 4. با محدودیت تاریخ:
+ * ```tsx
+ * <DateRangePicker
+ *   fromDate="from"
+ *   toDate="to"
+ *   control={control}
+ *   minDate={moment().subtract(1, 'year')}
+ *   maxDate={moment()}
+ * />
+ * ```
+ *
+ * 5. سفارشی‌سازی کامل:
+ * ```tsx
+ * <DateRangePicker
+ *   fromDate="startDate"
+ *   toDate="endDate"
+ *   control={control}
+ *   label="بازه زمانی گزارش"
+ *   size="small"
+ *   align="center"
+ *   persian={true}
+ *   clear={true}
+ *   disabled={false}
+ *   isLoading={false}
+ *   singleCalendar={false}
+ *   useMobilePickers={false}
+ *   fromViews={["year", "month", "day"]}
+ *   fromOpenTo="day"
+ *   toViews={["year", "month", "day"]}
+ *   toOpenTo="day"
+ * />
+ * ```
+ *
+ * @interface DateRangePickerProps
+ * @property {string} fromDate - نام فیلد تاریخ شروع در form
+ * @property {string} toDate - نام فیلد تاریخ پایان در form
+ * @property {Control<any>} control - React Hook Form control object
+ * @property {DateView[]} [fromViews] - نماهای قابل نمایش برای تاریخ شروع (پیش‌فرض: ["year", "month", "day"])
+ * @property {DateView} [fromOpenTo] - نمای ابتدایی برای تاریخ شروع (پیش‌فرض: "day")
+ * @property {DateView[]} [toViews] - نماهای قابل نمایش برای تاریخ پایان (پیش‌فرض: ["year", "month", "day"])
+ * @property {DateView} [toOpenTo] - نمای ابتدایی برای تاریخ پایان (پیش‌فرض: "day")
+ * @property {string} [label] - برچسب فیلد (پیش‌فرض: "انتخاب بازه")
+ * @property {"small" | "medium"} [size] - اندازه فیلد (پیش‌فرض: "medium")
+ * @property {boolean} [disabled] - غیرفعال کردن کامپوننت (پیش‌فرض: false)
+ * @property {boolean} [persian] - استفاده از تاریخ فارسی (پیش‌فرض: true)
+ * @property {"right" | "center" | "left"} [align] - تراز متن (پیش‌فرض: "left")
+ * @property {boolean} [isLoading] - نمایش حالت loading (پیش‌فرض: false)
+ * @property {Moment} [minDate] - حداقل تاریخ قابل انتخاب
+ * @property {Moment} [maxDate] - حداکثر تاریخ قابل انتخاب
+ * @property {boolean} [clear] - نمایش دکمه پاک کردن (پیش‌فرض: true)
+ * @property {boolean} [singleCalendar] - نمایش تک تقویم به جای دوتایی (پیش‌فرض: false)
+ * @property {boolean} [useMobilePickers] - استفاده از DatePicker جداگانه به جای popup (پیش‌فرض: false)
+ *
+ * نکات مهم:
+ * - کامپوننت خودکار mobile detection دارد (breakpoint: 700px)
+ * - در حالت موبایل، تقویم‌ها responsive می‌شوند
+ * - فرمت خروجی همیشه "YYYY-MM-DD" است
+ * - روزهای جمعه با رنگ قرمز نمایش داده می‌شوند
+ * - امکان انتخاب بازه با کلیک و drag وجود دارد
+ * - validation errors از React Hook Form پشتیبانی می‌شود
+ *
+ *
+ * @example
+ * // استفاده در فرم ساده
+ * const form = useForm({
+ *   defaultValues: {
+ *     startDate: '',
+ *     endDate: ''
+ *   }
+ * });
+ *
+ * <DateRangePicker
+ *   fromDate="startDate"
+ *   toDate="endDate"
+ *   control={form.control}
+ *   label="انتخاب دوره زمانی"
+ * />
+ */
+declare const DateRangePicker: React__default.FC<DateRangePickerProps>;
+
+export { DateRangePicker };