@mamrp/components 1.0.34 → 1.0.36

package/dist/selectors/index.d.mts

@@ -0,0 +1,227 @@
+import * as React from 'react';
+import { Control } from 'react-hook-form';
+
+interface OptionType$1 {
+    title: string;
+    key: string | number;
+    [x: string]: any;
+}
+interface AutocompleteRenderOptionState {
+    inputValue: string;
+    index: number;
+    selected: boolean;
+}
+interface MultipleSelectChipProps$1<T extends OptionType$1> {
+    name: string;
+    control: Control<any>;
+    label?: string;
+    data?: T[];
+    isLoading?: boolean;
+    disabled?: boolean;
+    size?: "small" | "medium";
+    clear?: boolean;
+    renderOption?: (props: React.HTMLAttributes<HTMLLIElement>, option: T, state: AutocompleteRenderOptionState) => React.ReactNode;
+}
+/**
+ * 📦 MultipleSelector — کامپوننت انتخاب چندگزینه‌ای پیشرفته
+ *
+ * @component MultipleSelector
+ *
+ * @template T — نوع داده‌ی گزینه‌ها که باید شامل فیلدهای `title` و `key` باشد.
+ *
+ * @param {string} name - نام فیلد در فرم (برای ثبت در react-hook-form).
+ * @param {Control<any>} control - کنترل فرم از کتابخانه react-hook-form.
+ * @param {string} [label] - برچسب ورودی.
+ * @param {T[]} [data] - آرایه‌ای از گزینه‌ها که هر کدام باید شامل `title` (نمایش) و `key` (شناسه یکتا) باشد.
+ * @param {boolean} [isLoading=false] - حالت لودینگ برای نمایش اسپینر در ورودی.
+ * @param {boolean} [disabled=false] - غیرفعال‌کردن ورودی.
+ * @param {"small" | "medium"} [size="medium"] - سایز ورودی MUI Autocomplete.
+ * @param {boolean} [clear=false] - اگر `false` باشد، قابلیت پاک کردن کامل (Clearable) غیرفعال می‌شود.
+ * @param {(props: React.HTMLAttributes<HTMLLIElement>, option: T, state: AutocompleteRenderOptionState) => React.ReactNode} [renderOption] - تابع سفارشی برای رندر هر آیتم در لیست انتخاب.
+ *
+ * @description
+ * این کامپوننت یک `Autocomplete` چندگزینه‌ای با قابلیت‌های زیر است:
+ * - اتصال مستقیم به `react-hook-form` (با استفاده از Controller)
+ * - انتخاب همه (`انتخاب همه`) یا پاک کردن همه (`پاک کردن همه`)
+ * - نمایش تعداد آیتم‌های انتخاب شده به جای تگ‌های جداگانه
+ * - پشتیبانی از حالت لودینگ و غیرفعال بودن
+ * - امکان سفارشی‌سازی رندر آیتم‌ها (`renderOption`)
+ * - آیکون‌های سفارشی برای انتخاب‌ها و گزینه‌های ویژه
+ * - جلوگیری از بستن لیست هنگام انتخاب آیتم‌ها (`disableCloseOnSelect`)
+ * - مدیریت موقعیت Popper با MUI modifiers
+ *
+ * @returns {Array<string | number>} آرایه‌ای از کلیدهای آیتم‌های انتخاب شده.
+ *
+ * @example
+ * ```tsx
+ * import { useForm, Controller } from "react-hook-form";
+ *
+ * type MyOption = { title: string; key: number };
+ *
+ * const options: MyOption[] = [
+ *   { title: "محصول ۱", key: 1 },
+ *   { title: "محصول ۲", key: 2 },
+ * ];
+ *
+ * export default function MyForm() {
+ *   const { control, handleSubmit } = useForm({ defaultValues: { productIds: [] } });
+ *
+ *   const onSubmit = (data: any) => {
+ *     console.log("انتخاب شده‌ها:", data.productIds);
+ *   };
+ *
+ *   return (
+ *     <form onSubmit={handleSubmit(onSubmit)}>
+ *       <MultipleSelector<MyOption>
+ *         name="productIds"
+ *         label="محصولات"
+ *         control={control}
+ *         data={options}
+ *         isLoading={false}
+ *         size="small"
+ *         renderOption={(props, option, state) => (
+ *           <li {...props} key={option.key}>
+ *             <strong style={{ color: state.selected ? "green" : "black" }}>
+ *               {option.title}
+ *             </strong>
+ *           </li>
+ *         )}
+ *       />
+ *       <button type="submit">ثبت</button>
+ *     </form>
+ *   );
+ * }
+ * ```
+ */
+declare function MultiCheckSelector<T extends OptionType$1>({ name, control, label, data, isLoading, disabled, size, clear, renderOption, }: MultipleSelectChipProps$1<T>): React.JSX.Element;
+
+interface OptionType {
+    title: string;
+    key: string | number;
+    [x: string]: any;
+}
+interface MultipleSelectChipProps<T extends OptionType> {
+    name: string;
+    control: Control<any>;
+    label?: string;
+    data?: T[];
+    isLoading?: boolean;
+    disabled?: boolean;
+    size?: "small" | "medium";
+    clear?: boolean;
+    renderOption?: (props: React.HTMLAttributes<HTMLLIElement>, option: T) => React.ReactNode;
+}
+/**
+ * 📦 کامپوننت انتخاب چند گزینه‌ای با پشتیبانی از react-hook-form و MUI Autocomplete
+ *
+ * @component MultipleSelector
+ *
+ * @param {string} name - نام فیلدی که در فرم ثبت می‌شود.
+ * @param {string} [label] - برچسب نمایشی برای فیلد.
+ * @param {Control<any>} control - کنترل فرم از react-hook-form.
+ * @param {{ title: string; key: string | number }[]} [data] - لیستی از گزینه‌ها شامل `title` (متن) و `key` (مقدار).
+ * @param {boolean} [isLoading=false] - آیا داده‌ها در حال بارگذاری هستند.
+ * @param {boolean} [disabled=false] - غیرفعال‌سازی ورودی.
+ * @param {"small" | "medium"} [size="medium"] - سایز ورودی.
+ * @param {boolean} [clear=false] - آیا امکان پاک کردن وجود دارد یا نه.
+ * @param {string} [tooltip] - متن راهنما هنگام هاور.
+ * @param {(props, option) => React.ReactNode} [renderOption] - تابعی سفارشی برای رندر آیتم‌ها در لیست.
+ *
+ * @returns {Array<{ key: string | number }>} لیستی از آیتم‌های انتخاب‌شده ( فقط آیدی‌ها).
+ *
+ * @example
+ * ```tsx
+ * <MultipleSelector<{title:string; key:number;}>
+ *   name="productIds"
+ *   label="محصولات"
+ *   control={control}
+ *   data={[{ title: "محصول ۱", key: 1 }, { title: "محصول ۲", key: 2 }]}
+ * />
+ * ```
+ *
+ * @description
+ * کامپوننتی چندانتخابی با قابلیت انتخاب همه‌ی موارد، سفارشی‌سازی گزینه‌ها،
+ * نمایش راهنمای هاور، و بازگرداندن لیست کامل از آبجکت‌های انتخاب‌شده.
+ *
+ * برای سفارشی‌سازی نحوه نمایش آیتم‌ها:
+ * ```tsx
+ * renderOption={(props, option) => (
+ *   <li {...props} key={`${option.key}`}>
+ *     <span style={{ color: "green" }}>{option.title}</span>
+ *   </li>
+ * )}
+ * ```
+ */
+declare function MultipleSelector<T extends OptionType>({ name, control, label, data, isLoading, disabled, size, clear, renderOption, }: MultipleSelectChipProps<T>): React.JSX.Element;
+
+interface BaseOption {
+    key: number | string | "false" | true;
+    title: string | number;
+    [x: string]: any;
+}
+interface SeacrchableSelectChipProps<T extends BaseOption = BaseOption> {
+    name: string;
+    control: Control<any>;
+    label?: string;
+    data?: T[];
+    isLoading?: boolean;
+    disabled?: boolean;
+    size?: "small" | "medium";
+    clear?: boolean;
+    onChangeHandler?: (value: any, onChange: (data: any) => void) => void;
+    valueHandler?: (value: any) => any;
+    onFilterOptions: (inputValue: string) => void;
+    renderOption?: (props: React.HTMLAttributes<HTMLLIElement>, option: T) => React.ReactNode;
+}
+/**
+ * 🔍 کامپوننت انتخاب تکی با قابلیت جست‌وجو، پشتیبانی از react-hook-form و MUI Autocomplete
+ *
+ * @component SeacrchableSelector
+ *
+ * @template T - نوع گزینه‌ها که باید شامل `key` و `title` باشد.
+ *
+ * @param {string} name - نام فیلدی که در فرم ثبت می‌شود.
+ * @param {string} [label] - برچسب نمایشی برای فیلد.
+ * @param {Control<any>} control - کنترل فرم از `react-hook-form`.
+ * @param {T[]} [data] - لیستی از گزینه‌ها شامل `key` و `title` به عنوان مقدار و متن نمایشی.
+ * @param {boolean} [isLoading=false] - وضعیت بارگذاری (مثلاً هنگام فراخوانی API).
+ * @param {boolean} [disabled=false] - غیرفعال بودن فیلد.
+ * @param {"small" | "medium"} [size="medium"] - اندازه ورودی.
+ * @param {boolean} [clear=false] - فعال بودن امکان پاک‌کردن مقدار انتخاب‌شده.
+ * @param {(value: any, onChange: (data: any) => void) => void} [onChangeHandler] - تابع هندل انتخاب گزینه (در صورت نیاز به کنترل خارجی).
+ * @param {(value: any) => string} [valueHandler] - تابع تبدیل مقدار ذخیره‌شده در فرم به مقدار نمایشی در input (مثلاً عنوان).
+ * @param {(inputValue: string) => void} [onFilterOptions] - تابعی برای هندل کردن فیلتر شدن داده‌ها هنگام تایپ کاربر (مثلاً برای fetch کردن).
+ * @param {(props: React.HTMLAttributes<HTMLLIElement>, option: T) => React.ReactNode} [renderOption] - تابعی سفارشی برای رندر آیتم‌ها در لیست.
+ *
+ * @returns {string | number | null} مقدار انتخاب‌شده (کلید گزینه یا null)
+ *
+ * @example
+ * ```tsx
+ * <SeacrchableSelector<{ title: string; key: number }>
+ *   name="categoryId"
+ *   label="دسته‌بندی"
+ *   control={control}
+ *   data={[{ title: "کتاب", key: 1 }, { title: "لوازم تحریر", key: 2 }]}
+ *   onFilterOptions={(input) => fetchUsers(input)}
+ * />
+ * ```
+ *
+ * @description
+ * این کامپوننت یک ورودی انتخاب‌گر تکی با قابلیت جست‌وجو و پشتیبانی از مقدار دلخواه کاربر (`freeSolo`) است.
+ * قابلیت‌هایی مانند بارگذاری داده، سفارشی‌سازی نمایش گزینه‌ها، هماهنگ‌سازی با فرم، پاک‌سازی انتخاب، و پشتیبانی از جست‌وجوی سمت سرور را نیز داراست.
+ *
+ * اگر `freeSolo` فعال باشد، می‌توان مقادیر تایپ‌شده را نیز ذخیره کرد. مقدار خروجی معمولاً `key` گزینه انتخاب‌شده است،
+ * مگر اینکه کاربر متنی وارد کند که در لیست نباشد (در این صورت می‌توان آن را مستقیم ذخیره کرد).
+ *
+ * برای سفارشی‌سازی گزینه‌ها:
+ * ```tsx
+ * renderOption={(props, option) => (
+ *   <li {...props} key={option.key}>
+ *     <b>{option.title}</b>
+ *   </li>
+ * )}
+ * ```
+ */
+declare function SearchableSelector<T extends BaseOption = BaseOption>({ name, control, label, data, isLoading, disabled, size, clear, onChangeHandler, valueHandler, onFilterOptions, renderOption, }: SeacrchableSelectChipProps<T>): React.JSX.Element;
+
+export { MultiCheckSelector, MultipleSelector, SearchableSelector };

package/dist/selectors/index.d.ts

@@ -0,0 +1,227 @@
+import * as React from 'react';
+import { Control } from 'react-hook-form';
+
+interface OptionType$1 {
+    title: string;
+    key: string | number;
+    [x: string]: any;
+}
+interface AutocompleteRenderOptionState {
+    inputValue: string;
+    index: number;
+    selected: boolean;
+}
+interface MultipleSelectChipProps$1<T extends OptionType$1> {
+    name: string;
+    control: Control<any>;
+    label?: string;
+    data?: T[];
+    isLoading?: boolean;
+    disabled?: boolean;
+    size?: "small" | "medium";
+    clear?: boolean;
+    renderOption?: (props: React.HTMLAttributes<HTMLLIElement>, option: T, state: AutocompleteRenderOptionState) => React.ReactNode;
+}
+/**
+ * 📦 MultipleSelector — کامپوننت انتخاب چندگزینه‌ای پیشرفته
+ *
+ * @component MultipleSelector
+ *
+ * @template T — نوع داده‌ی گزینه‌ها که باید شامل فیلدهای `title` و `key` باشد.
+ *
+ * @param {string} name - نام فیلد در فرم (برای ثبت در react-hook-form).
+ * @param {Control<any>} control - کنترل فرم از کتابخانه react-hook-form.
+ * @param {string} [label] - برچسب ورودی.
+ * @param {T[]} [data] - آرایه‌ای از گزینه‌ها که هر کدام باید شامل `title` (نمایش) و `key` (شناسه یکتا) باشد.
+ * @param {boolean} [isLoading=false] - حالت لودینگ برای نمایش اسپینر در ورودی.
+ * @param {boolean} [disabled=false] - غیرفعال‌کردن ورودی.
+ * @param {"small" | "medium"} [size="medium"] - سایز ورودی MUI Autocomplete.
+ * @param {boolean} [clear=false] - اگر `false` باشد، قابلیت پاک کردن کامل (Clearable) غیرفعال می‌شود.
+ * @param {(props: React.HTMLAttributes<HTMLLIElement>, option: T, state: AutocompleteRenderOptionState) => React.ReactNode} [renderOption] - تابع سفارشی برای رندر هر آیتم در لیست انتخاب.
+ *
+ * @description
+ * این کامپوننت یک `Autocomplete` چندگزینه‌ای با قابلیت‌های زیر است:
+ * - اتصال مستقیم به `react-hook-form` (با استفاده از Controller)
+ * - انتخاب همه (`انتخاب همه`) یا پاک کردن همه (`پاک کردن همه`)
+ * - نمایش تعداد آیتم‌های انتخاب شده به جای تگ‌های جداگانه
+ * - پشتیبانی از حالت لودینگ و غیرفعال بودن
+ * - امکان سفارشی‌سازی رندر آیتم‌ها (`renderOption`)
+ * - آیکون‌های سفارشی برای انتخاب‌ها و گزینه‌های ویژه
+ * - جلوگیری از بستن لیست هنگام انتخاب آیتم‌ها (`disableCloseOnSelect`)
+ * - مدیریت موقعیت Popper با MUI modifiers
+ *
+ * @returns {Array<string | number>} آرایه‌ای از کلیدهای آیتم‌های انتخاب شده.
+ *
+ * @example
+ * ```tsx
+ * import { useForm, Controller } from "react-hook-form";
+ *
+ * type MyOption = { title: string; key: number };
+ *
+ * const options: MyOption[] = [
+ *   { title: "محصول ۱", key: 1 },
+ *   { title: "محصول ۲", key: 2 },
+ * ];
+ *
+ * export default function MyForm() {
+ *   const { control, handleSubmit } = useForm({ defaultValues: { productIds: [] } });
+ *
+ *   const onSubmit = (data: any) => {
+ *     console.log("انتخاب شده‌ها:", data.productIds);
+ *   };
+ *
+ *   return (
+ *     <form onSubmit={handleSubmit(onSubmit)}>
+ *       <MultipleSelector<MyOption>
+ *         name="productIds"
+ *         label="محصولات"
+ *         control={control}
+ *         data={options}
+ *         isLoading={false}
+ *         size="small"
+ *         renderOption={(props, option, state) => (
+ *           <li {...props} key={option.key}>
+ *             <strong style={{ color: state.selected ? "green" : "black" }}>
+ *               {option.title}
+ *             </strong>
+ *           </li>
+ *         )}
+ *       />
+ *       <button type="submit">ثبت</button>
+ *     </form>
+ *   );
+ * }
+ * ```
+ */
+declare function MultiCheckSelector<T extends OptionType$1>({ name, control, label, data, isLoading, disabled, size, clear, renderOption, }: MultipleSelectChipProps$1<T>): React.JSX.Element;
+
+interface OptionType {
+    title: string;
+    key: string | number;
+    [x: string]: any;
+}
+interface MultipleSelectChipProps<T extends OptionType> {
+    name: string;
+    control: Control<any>;
+    label?: string;
+    data?: T[];
+    isLoading?: boolean;
+    disabled?: boolean;
+    size?: "small" | "medium";
+    clear?: boolean;
+    renderOption?: (props: React.HTMLAttributes<HTMLLIElement>, option: T) => React.ReactNode;
+}
+/**
+ * 📦 کامپوننت انتخاب چند گزینه‌ای با پشتیبانی از react-hook-form و MUI Autocomplete
+ *
+ * @component MultipleSelector
+ *
+ * @param {string} name - نام فیلدی که در فرم ثبت می‌شود.
+ * @param {string} [label] - برچسب نمایشی برای فیلد.
+ * @param {Control<any>} control - کنترل فرم از react-hook-form.
+ * @param {{ title: string; key: string | number }[]} [data] - لیستی از گزینه‌ها شامل `title` (متن) و `key` (مقدار).
+ * @param {boolean} [isLoading=false] - آیا داده‌ها در حال بارگذاری هستند.
+ * @param {boolean} [disabled=false] - غیرفعال‌سازی ورودی.
+ * @param {"small" | "medium"} [size="medium"] - سایز ورودی.
+ * @param {boolean} [clear=false] - آیا امکان پاک کردن وجود دارد یا نه.
+ * @param {string} [tooltip] - متن راهنما هنگام هاور.
+ * @param {(props, option) => React.ReactNode} [renderOption] - تابعی سفارشی برای رندر آیتم‌ها در لیست.
+ *
+ * @returns {Array<{ key: string | number }>} لیستی از آیتم‌های انتخاب‌شده ( فقط آیدی‌ها).
+ *
+ * @example
+ * ```tsx
+ * <MultipleSelector<{title:string; key:number;}>
+ *   name="productIds"
+ *   label="محصولات"
+ *   control={control}
+ *   data={[{ title: "محصول ۱", key: 1 }, { title: "محصول ۲", key: 2 }]}
+ * />
+ * ```
+ *
+ * @description
+ * کامپوننتی چندانتخابی با قابلیت انتخاب همه‌ی موارد، سفارشی‌سازی گزینه‌ها،
+ * نمایش راهنمای هاور، و بازگرداندن لیست کامل از آبجکت‌های انتخاب‌شده.
+ *
+ * برای سفارشی‌سازی نحوه نمایش آیتم‌ها:
+ * ```tsx
+ * renderOption={(props, option) => (
+ *   <li {...props} key={`${option.key}`}>
+ *     <span style={{ color: "green" }}>{option.title}</span>
+ *   </li>
+ * )}
+ * ```
+ */
+declare function MultipleSelector<T extends OptionType>({ name, control, label, data, isLoading, disabled, size, clear, renderOption, }: MultipleSelectChipProps<T>): React.JSX.Element;
+
+interface BaseOption {
+    key: number | string | "false" | true;
+    title: string | number;
+    [x: string]: any;
+}
+interface SeacrchableSelectChipProps<T extends BaseOption = BaseOption> {
+    name: string;
+    control: Control<any>;
+    label?: string;
+    data?: T[];
+    isLoading?: boolean;
+    disabled?: boolean;
+    size?: "small" | "medium";
+    clear?: boolean;
+    onChangeHandler?: (value: any, onChange: (data: any) => void) => void;
+    valueHandler?: (value: any) => any;
+    onFilterOptions: (inputValue: string) => void;
+    renderOption?: (props: React.HTMLAttributes<HTMLLIElement>, option: T) => React.ReactNode;
+}
+/**
+ * 🔍 کامپوننت انتخاب تکی با قابلیت جست‌وجو، پشتیبانی از react-hook-form و MUI Autocomplete
+ *
+ * @component SeacrchableSelector
+ *
+ * @template T - نوع گزینه‌ها که باید شامل `key` و `title` باشد.
+ *
+ * @param {string} name - نام فیلدی که در فرم ثبت می‌شود.
+ * @param {string} [label] - برچسب نمایشی برای فیلد.
+ * @param {Control<any>} control - کنترل فرم از `react-hook-form`.
+ * @param {T[]} [data] - لیستی از گزینه‌ها شامل `key` و `title` به عنوان مقدار و متن نمایشی.
+ * @param {boolean} [isLoading=false] - وضعیت بارگذاری (مثلاً هنگام فراخوانی API).
+ * @param {boolean} [disabled=false] - غیرفعال بودن فیلد.
+ * @param {"small" | "medium"} [size="medium"] - اندازه ورودی.
+ * @param {boolean} [clear=false] - فعال بودن امکان پاک‌کردن مقدار انتخاب‌شده.
+ * @param {(value: any, onChange: (data: any) => void) => void} [onChangeHandler] - تابع هندل انتخاب گزینه (در صورت نیاز به کنترل خارجی).
+ * @param {(value: any) => string} [valueHandler] - تابع تبدیل مقدار ذخیره‌شده در فرم به مقدار نمایشی در input (مثلاً عنوان).
+ * @param {(inputValue: string) => void} [onFilterOptions] - تابعی برای هندل کردن فیلتر شدن داده‌ها هنگام تایپ کاربر (مثلاً برای fetch کردن).
+ * @param {(props: React.HTMLAttributes<HTMLLIElement>, option: T) => React.ReactNode} [renderOption] - تابعی سفارشی برای رندر آیتم‌ها در لیست.
+ *
+ * @returns {string | number | null} مقدار انتخاب‌شده (کلید گزینه یا null)
+ *
+ * @example
+ * ```tsx
+ * <SeacrchableSelector<{ title: string; key: number }>
+ *   name="categoryId"
+ *   label="دسته‌بندی"
+ *   control={control}
+ *   data={[{ title: "کتاب", key: 1 }, { title: "لوازم تحریر", key: 2 }]}
+ *   onFilterOptions={(input) => fetchUsers(input)}
+ * />
+ * ```
+ *
+ * @description
+ * این کامپوننت یک ورودی انتخاب‌گر تکی با قابلیت جست‌وجو و پشتیبانی از مقدار دلخواه کاربر (`freeSolo`) است.
+ * قابلیت‌هایی مانند بارگذاری داده، سفارشی‌سازی نمایش گزینه‌ها، هماهنگ‌سازی با فرم، پاک‌سازی انتخاب، و پشتیبانی از جست‌وجوی سمت سرور را نیز داراست.
+ *
+ * اگر `freeSolo` فعال باشد، می‌توان مقادیر تایپ‌شده را نیز ذخیره کرد. مقدار خروجی معمولاً `key` گزینه انتخاب‌شده است،
+ * مگر اینکه کاربر متنی وارد کند که در لیست نباشد (در این صورت می‌توان آن را مستقیم ذخیره کرد).
+ *
+ * برای سفارشی‌سازی گزینه‌ها:
+ * ```tsx
+ * renderOption={(props, option) => (
+ *   <li {...props} key={option.key}>
+ *     <b>{option.title}</b>
+ *   </li>
+ * )}
+ * ```
+ */
+declare function SearchableSelector<T extends BaseOption = BaseOption>({ name, control, label, data, isLoading, disabled, size, clear, onChangeHandler, valueHandler, onFilterOptions, renderOption, }: SeacrchableSelectChipProps<T>): React.JSX.Element;
+
+export { MultiCheckSelector, MultipleSelector, SearchableSelector };