@jalalix/mui 0.1.0 → 0.2.0

package/AdapterJalaliX.d.ts

@@ -0,0 +1,352 @@
+import JalaliX from '@jalalix/typescript';
+import type { AdapterFormats, AdapterOptions, DateBuilderReturnType, FieldFormatTokenMap, MuiPickersAdapter, PickerValidDate, PickersTimezone } from '@mui/x-date-pickers/models';
+declare module '@mui/x-date-pickers/models' {
+    interface PickerValidDateLookup {
+        jalalix: JalaliX;
+    }
+}
+/**
+ * MUI X Date Pickers adapter backed by `@jalalix/typescript`.
+ *
+ * Implements {@link MuiPickersAdapter} with Jalali (Persian / Shamsi) calendar
+ * semantics: months are Jalali, the week starts on Saturday, and format tokens
+ * follow JalaliX (`YYYY`, `MMM`, `WN`, etc.).
+ *
+ * Pass to `LocalizationProvider`:
+ * ```ts
+ * <LocalizationProvider dateAdapter={AdapterJalaliX}>
+ * ```
+ *
+ * @example
+ * ```ts
+ * const adapter = new AdapterJalaliX({ locale: 'fa', formats: { keyboardDate: 'YYYY/MM/DD' } })
+ * const today = adapter.date()
+ * adapter.format(today, 'fullDate')
+ * ```
+ */
+export declare class AdapterJalaliX implements MuiPickersAdapter {
+    isMUIAdapter: boolean;
+    isTimezoneCompatible: boolean;
+    lib: string;
+    locale?: string;
+    formats: AdapterFormats;
+    escapedCharacters: {
+        start: string;
+        end: string;
+    };
+    formatTokenMap: FieldFormatTokenMap;
+    /**
+     * Creates a JalaliX-backed MUI pickers adapter.
+     * @param options - Adapter options.
+     * @param options.locale - Locale code (e.g. `'fa'`, `'en'`); affects 12-hour cycle detection.
+     * @param options.formats - Partial overrides for {@link AdapterFormats} keys (e.g. `keyboardDate`).
+     */
+    constructor({ locale, formats }?: AdapterOptions<string, never>);
+    private asJalaliX;
+    /** Applies IANA / alias timezone via JalaliX (instant-preserving). */
+    private withTimezone;
+    /**
+     * Sets Jalali Y/M/D and wall clock in the value's active timezone.
+     * Month is 0-based (Farvardin = 0), matching MUI / `Date`.
+     */
+    private setJalaliParts;
+    /** Sets wall clock fields in the active timezone (defaults fill from current wall time). */
+    private withWallTime;
+    private weekDayName;
+    private weekDayLetter;
+    /**
+     * Builds a JalaliX date from a value, or returns “now” / `null`.
+     * @param value - ISO/string/timestamp to parse; `undefined` -> now; `null` -> `null`.
+     * @param timezone - MUI timezone (`'default'`, `'system'`, or IANA name).
+     * @returns A {@link JalaliX} instance, `null`, or an invalid date on parse failure.
+     */
+    date: <T extends string | null | undefined>(value?: T, timezone?: PickersTimezone) => DateBuilderReturnType<T>;
+    /**
+     * Returns an invalid JalaliX date (`NaN` timestamp) for failed parses.
+     * @returns Invalid {@link JalaliX} instance.
+     */
+    getInvalidDate: () => JalaliX;
+    /**
+     * Resolves the timezone string for a picker value.
+     * @param value - Date value, or `null`.
+     * @returns IANA timezone, `'default'` if `value` is null, or `'system'` on error.
+     */
+    getTimezone: (value: PickerValidDate | null) => string;
+    /**
+     * Returns a copy of `value` in the given timezone (instant-preserving).
+     * @param value - Source date.
+     * @param timezone - Target timezone (`'default'` / `'system'` / IANA / `'UTC'`).
+     * @returns JalaliX in the requested timezone.
+     */
+    setTimezone: (value: PickerValidDate, timezone: PickersTimezone) => JalaliX;
+    /**
+     * Converts a picker value to a native JavaScript `Date`.
+     * @param value - Picker date.
+     * @returns Equivalent `Date` (same epoch ms).
+     */
+    toJsDate: (value: PickerValidDate) => Date;
+    /**
+     * Parses a user-entered string with the given format into a JalaliX date.
+     * Uses {@link JalaliX.parseJalali} for common `YYYY/MM/DD` keyboard formats;
+     * otherwise tokenizes `format` (Persian digits accepted).
+     * @param value - Input string (empty -> `null`).
+     * @param format - Format pattern (e.g. `'YYYY/MM/DD'`, `'D MMM YYYY'`).
+     * @returns Parsed {@link JalaliX}, `null` if empty, or an invalid date on failure.
+     */
+    parse: (value: string, format: string) => JalaliX | null;
+    private parseWithFormat;
+    /**
+     * @returns Active locale code, or `'fa'` when unset.
+     */
+    getCurrentLocaleCode: () => string;
+    /**
+     * Whether the current locale prefers a 12-hour clock (`en*` -> true).
+     * @returns `true` for English locales; otherwise `false`.
+     */
+    is12HourCycleInCurrentLocale: () => boolean;
+    /**
+     * Normalizes MUI/localized format aliases to JalaliX tokens
+     * (`MMMM`->`MMM`, `dddd`/`ddd`->`WN`, word-boundary `dd`->`WL`).
+     * @param format - Format string from formats map or field props.
+     * @returns Expanded format string for {@link formatByString} / {@link parse}.
+     */
+    expandFormat: (format: string) => string;
+    /**
+     * @param value - Value to validate.
+     * @returns Whether `value` is a valid {@link JalaliX} / Date.
+     */
+    isValid: (value: PickerValidDate | null) => value is PickerValidDate;
+    /**
+     * Formats a date using a named key from {@link formats}.
+     * @param value - Date to format.
+     * @param formatKey - Key in {@link AdapterFormats} (e.g. `'fullDate'`, `'keyboardDate'`).
+     * @returns Formatted string.
+     */
+    format: (value: PickerValidDate, formatKey: keyof AdapterFormats) => string;
+    /**
+     * Formats a date with an explicit JalaliX format string.
+     * Protects weekday tokens (`WN`/`WL`) that would otherwise collide with week-number `W`.
+     * @param value - Date to format.
+     * @param formatString - Pattern (e.g. `'YYYY/MM/DD'`, `'WN D MMM YYYY'`).
+     * @returns Formatted string.
+     */
+    formatByString: (value: PickerValidDate, formatString: string) => string;
+    /**
+     * Localizes digits for field display (Western -> Persian; `,` -> `،`).
+     * @param numberToFormat - Digit string from MUI fields.
+     * @returns String with Persian numerals.
+     */
+    formatNumber: (numberToFormat: string) => string;
+    /**
+     * @param value - First date (or `null`).
+     * @param comparing - Second date (or `null`).
+     * @returns `true` if both null or same epoch ms.
+     */
+    isEqual: (value: PickerValidDate | null, comparing: PickerValidDate | null) => boolean;
+    /** @returns Whether both dates share the same Jalali year. */
+    isSameYear: (value: PickerValidDate, comparing: PickerValidDate) => boolean;
+    /** @returns Whether both dates share the same Jalali year and month. */
+    isSameMonth: (value: PickerValidDate, comparing: PickerValidDate) => boolean;
+    /** @returns Whether both dates fall on the same Jalali calendar day. */
+    isSameDay: (value: PickerValidDate, comparing: PickerValidDate) => boolean;
+    /** @returns Whether both dates share the same day and hour. */
+    isSameHour: (value: PickerValidDate, comparing: PickerValidDate) => boolean;
+    /** @returns Whether `value` is strictly after `comparing` by timestamp. */
+    isAfter: (value: PickerValidDate, comparing: PickerValidDate) => boolean;
+    /** @returns Whether `value`'s Jalali year is after `comparing`'s. */
+    isAfterYear: (value: PickerValidDate, comparing: PickerValidDate) => boolean;
+    /** @returns Whether `value`'s calendar day is after `comparing`'s. */
+    isAfterDay: (value: PickerValidDate, comparing: PickerValidDate) => boolean;
+    /** @returns Whether `value` is strictly before `comparing` by timestamp. */
+    isBefore: (value: PickerValidDate, comparing: PickerValidDate) => boolean;
+    /** @returns Whether `value`'s Jalali year is before `comparing`'s. */
+    isBeforeYear: (value: PickerValidDate, comparing: PickerValidDate) => boolean;
+    /** @returns Whether `value`'s calendar day is before `comparing`'s. */
+    isBeforeDay: (value: PickerValidDate, comparing: PickerValidDate) => boolean;
+    /**
+     * @param value - Date to test.
+     * @param range - Inclusive `[start, end]` bounds.
+     * @returns Whether `value` lies within the range by timestamp.
+     */
+    isWithinRange: (value: PickerValidDate, range: [PickerValidDate, PickerValidDate]) => boolean;
+    /**
+     * @param value - Reference date.
+     * @returns Start of that Jalali year (Farvardin 1, 00:00:00.000).
+     */
+    startOfYear: (value: PickerValidDate) => JalaliX;
+    /**
+     * @param value - Reference date.
+     * @returns Start of that Jalali month (day 1, 00:00:00.000).
+     */
+    startOfMonth: (value: PickerValidDate) => JalaliX;
+    /**
+     * Persian week starts on Saturday.
+     * @param value - Reference date.
+     * @returns Start of that week (Saturday 00:00:00.000).
+     */
+    startOfWeek: (value: PickerValidDate) => JalaliX;
+    /**
+     * @param value - Reference date.
+     * @returns Same calendar day at 00:00:00.000 local wall time.
+     */
+    startOfDay: (value: PickerValidDate) => JalaliX;
+    /**
+     * @param value - Reference date.
+     * @returns End of that Jalali year (last moment of Esfand).
+     */
+    endOfYear: (value: PickerValidDate) => JalaliX;
+    /**
+     * @param value - Reference date.
+     * @returns End of that Jalali month (23:59:59.999 on the last day).
+     */
+    endOfMonth: (value: PickerValidDate) => JalaliX;
+    /**
+     * Persian week ends on Friday.
+     * @param value - Reference date.
+     * @returns End of that week (Friday 23:59:59.999).
+     */
+    endOfWeek: (value: PickerValidDate) => JalaliX;
+    /**
+     * @param value - Reference date.
+     * @returns Same calendar day at 23:59:59.999 local wall time.
+     */
+    endOfDay: (value: PickerValidDate) => JalaliX;
+    /**
+     * @param value - Source date.
+     * @param amount - Years to add (may be negative).
+     * @returns New JalaliX with year adjusted.
+     */
+    addYears: (value: PickerValidDate, amount: number) => JalaliX;
+    /**
+     * Adds months with day clamping to the target month length.
+     * @param value - Source date.
+     * @param amount - Months to add (may be negative).
+     * @returns New JalaliX with month adjusted.
+     */
+    addMonths: (value: PickerValidDate, amount: number) => JalaliX;
+    /**
+     * @param value - Source date.
+     * @param amount - Weeks to add (may be negative).
+     * @returns New JalaliX with days shifted by `amount * 7`.
+     */
+    addWeeks: (value: PickerValidDate, amount: number) => JalaliX;
+    /**
+     * Adds calendar days (wall time preserved via JalaliX timezone-aware setters).
+     * @param value - Source date.
+     * @param amount - Days to add (may be negative).
+     * @returns New JalaliX with day adjusted.
+     */
+    addDays: (value: PickerValidDate, amount: number) => JalaliX;
+    /**
+     * @param value - Source date.
+     * @param amount - Hours to add (may be negative).
+     * @returns New JalaliX with timestamp shifted by hours.
+     */
+    addHours: (value: PickerValidDate, amount: number) => JalaliX;
+    /**
+     * @param value - Source date.
+     * @param amount - Minutes to add (may be negative).
+     * @returns New JalaliX with timestamp shifted by minutes.
+     */
+    addMinutes: (value: PickerValidDate, amount: number) => JalaliX;
+    /**
+     * @param value - Source date.
+     * @param amount - Seconds to add (may be negative).
+     * @returns New JalaliX with timestamp shifted by seconds.
+     */
+    addSeconds: (value: PickerValidDate, amount: number) => JalaliX;
+    /** @returns Jalali year. */
+    getYear: (value: PickerValidDate) => number;
+    /**
+     * 0-based Jalali month (0 = Farvardin).
+     * @returns Month index 0–11.
+     */
+    getMonth: (value: PickerValidDate) => number;
+    /** @returns Day of month (1–31). */
+    getDate: (value: PickerValidDate) => number;
+    /** @returns Hours (0–23). */
+    getHours: (value: PickerValidDate) => number;
+    /** @returns Minutes (0–59). */
+    getMinutes: (value: PickerValidDate) => number;
+    /** @returns Seconds (0–59). */
+    getSeconds: (value: PickerValidDate) => number;
+    /** @returns Milliseconds (0–999). */
+    getMilliseconds: (value: PickerValidDate) => number;
+    /**
+     * @param value - Source date.
+     * @param year - Jalali year to set.
+     * @returns New JalaliX with year replaced (month/day/time preserved).
+     */
+    setYear: (value: PickerValidDate, year: number) => JalaliX;
+    /**
+     * @param value - Source date.
+     * @param month - 0-based Jalali month (0 = Farvardin).
+     * @returns New JalaliX with month replaced.
+     */
+    setMonth: (value: PickerValidDate, month: number) => JalaliX;
+    /**
+     * @param value - Source date.
+     * @param date - Day of month to set.
+     * @returns New JalaliX with day replaced.
+     */
+    setDate: (value: PickerValidDate, date: number) => JalaliX;
+    /**
+     * @param value - Source date.
+     * @param hours - Hours to set (0–23).
+     * @returns New JalaliX with hours replaced.
+     */
+    setHours: (value: PickerValidDate, hours: number) => JalaliX;
+    /**
+     * @param value - Source date.
+     * @param minutes - Minutes to set.
+     * @returns New JalaliX with minutes replaced.
+     */
+    setMinutes: (value: PickerValidDate, minutes: number) => JalaliX;
+    /**
+     * @param value - Source date.
+     * @param seconds - Seconds to set.
+     * @returns New JalaliX with seconds replaced.
+     */
+    setSeconds: (value: PickerValidDate, seconds: number) => JalaliX;
+    /**
+     * @param value - Source date.
+     * @param milliseconds - Milliseconds to set.
+     * @returns New JalaliX with milliseconds replaced.
+     */
+    setMilliseconds: (value: PickerValidDate, milliseconds: number) => JalaliX;
+    /**
+     * Days in the Jalali month of `value` (31 / 30 / 29–30 for Esfand).
+     * @param value - Reference date.
+     * @returns Day count for that month.
+     */
+    getDaysInMonth: (value: PickerValidDate) => number;
+    /**
+     * Builds the month grid as weeks (Saturday-start) for calendar UIs.
+     * @param value - Any date in the target month.
+     * @returns Array of weeks; each week is seven {@link JalaliX} days.
+     */
+    getWeekArray: (value: PickerValidDate) => JalaliX[][];
+    /**
+     * @param value - Reference date.
+     * @returns Jalali week-of-year (1–53).
+     */
+    getWeekNumber: (value: PickerValidDate) => number;
+    /**
+     * 1-based day of week with Saturday as the first day (Persian week).
+     * @param value - Reference date.
+     * @returns 1 (Saturday) … 7 (Friday).
+     */
+    getDayOfWeek: (value: PickerValidDate) => number;
+    /**
+     * Lists year-start dates from `start` through `end` (inclusive range walk).
+     * @param range - `[start, end]` picker dates.
+     * @returns One {@link JalaliX} per year at start-of-year.
+     */
+    getYearRange: ([start, end]: [PickerValidDate, PickerValidDate]) => JalaliX[];
+    /**
+     * Optional helper for older pickers / custom UIs.
+     * @param ampm - `'am'` or `'pm'`.
+     * @returns Persian meridiem (`ق.ظ.` / `ب.ظ.`).
+     */
+    getMeridiemText: (ampm: 'am' | 'pm') => string;
+}

package/AdapterJalaliX.js

@@ -0,0 +1,755 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AdapterJalaliX = void 0;
+const typescript_1 = __importDefault(require("@jalalix/typescript"));
+const MONTH_NAMES = ['فروردین', 'اردیبهشت', 'خرداد', 'تیر', 'مرداد', 'شهریور', 'مهر', 'آبان', 'آذر', 'دی', 'بهمن', 'اسفند'];
+const WEEKDAY_NAMES = ['شنبه', 'یکشنبه', 'دوشنبه', 'سه شنبه', 'چهار شنبه', 'پنج شنبه', 'جمعه'];
+const WEEKDAY_LETTERS = ['ش', 'ی', 'د', 'س', 'چ', 'پ', 'ج'];
+const formatTokenMap = {
+    // Year
+    YY: 'year',
+    YYYY: { sectionType: 'year', contentType: 'digit', maxLength: 4 },
+    // Month
+    M: { sectionType: 'month', contentType: 'digit', maxLength: 2 },
+    MM: 'month',
+    MMM: { sectionType: 'month', contentType: 'letter' },
+    MMMM: { sectionType: 'month', contentType: 'letter' },
+    // Day of the month
+    D: { sectionType: 'day', contentType: 'digit', maxLength: 2 },
+    DD: 'day',
+    // Day of the week (JalaliX tokens)
+    WN: { sectionType: 'weekDay', contentType: 'letter' },
+    wn: { sectionType: 'weekDay', contentType: 'letter' },
+    WL: { sectionType: 'weekDay', contentType: 'letter' },
+    wl: { sectionType: 'weekDay', contentType: 'letter' },
+    dddd: { sectionType: 'weekDay', contentType: 'letter' },
+    ddd: { sectionType: 'weekDay', contentType: 'letter' },
+    dd: { sectionType: 'weekDay', contentType: 'letter' },
+    d: { sectionType: 'weekDay', contentType: 'digit', maxLength: 2 },
+    // Meridiem
+    A: 'meridiem',
+    a: 'meridiem',
+    // Hours
+    H: { sectionType: 'hours', contentType: 'digit', maxLength: 2 },
+    HH: 'hours',
+    h: { sectionType: 'hours', contentType: 'digit', maxLength: 2 },
+    hh: 'hours',
+    // Minutes
+    m: { sectionType: 'minutes', contentType: 'digit', maxLength: 2 },
+    mm: 'minutes',
+    // Seconds
+    s: { sectionType: 'seconds', contentType: 'digit', maxLength: 2 },
+    ss: 'seconds'
+};
+const defaultFormats = {
+    year: 'YYYY',
+    month: 'MMM',
+    monthShort: 'MMM',
+    dayOfMonth: 'D',
+    dayOfMonthFull: 'D',
+    weekday: 'WN',
+    weekdayShort: 'WL',
+    hours24h: 'HH',
+    hours12h: 'hh',
+    meridiem: 'A',
+    minutes: 'mm',
+    seconds: 'ss',
+    fullDate: 'WN D MMM YYYY',
+    keyboardDate: 'YYYY/MM/DD',
+    shortDate: 'D MMM',
+    normalDate: 'D MMM',
+    normalDateWithWeekday: 'WN، D MMM',
+    fullTime12h: 'hh:mm A',
+    fullTime24h: 'HH:mm',
+    keyboardDateTime12h: 'YYYY/MM/DD hh:mm A',
+    keyboardDateTime24h: 'YYYY/MM/DD HH:mm'
+};
+/**
+ * MUI X Date Pickers adapter backed by `@jalalix/typescript`.
+ *
+ * Implements {@link MuiPickersAdapter} with Jalali (Persian / Shamsi) calendar
+ * semantics: months are Jalali, the week starts on Saturday, and format tokens
+ * follow JalaliX (`YYYY`, `MMM`, `WN`, etc.).
+ *
+ * Pass to `LocalizationProvider`:
+ * ```ts
+ * <LocalizationProvider dateAdapter={AdapterJalaliX}>
+ * ```
+ *
+ * @example
+ * ```ts
+ * const adapter = new AdapterJalaliX({ locale: 'fa', formats: { keyboardDate: 'YYYY/MM/DD' } })
+ * const today = adapter.date()
+ * adapter.format(today, 'fullDate')
+ * ```
+ */
+class AdapterJalaliX {
+    /**
+     * Creates a JalaliX-backed MUI pickers adapter.
+     * @param options - Adapter options.
+     * @param options.locale - Locale code (e.g. `'fa'`, `'en'`); affects 12-hour cycle detection.
+     * @param options.formats - Partial overrides for {@link AdapterFormats} keys (e.g. `keyboardDate`).
+     */
+    constructor({ locale, formats } = {}) {
+        // Always `true` — marks this as an MUI X date adapter.
+        this.isMUIAdapter = true;
+        // Adapter supports MUI timezone APIs (`date`, `setTimezone`, etc.).
+        this.isTimezoneCompatible = true;
+        // Library id registered with MUI (`jalalix`).
+        this.lib = 'jalalix';
+        // Characters that escape literal text inside format strings (`[` … `]`).
+        this.escapedCharacters = { start: '[', end: ']' };
+        // Token -> section mapping used by MUI field components.
+        this.formatTokenMap = formatTokenMap;
+        this.asJalaliX = (value) => {
+            if (value instanceof typescript_1.default)
+                return value;
+            return typescript_1.default.create(value);
+        };
+        /** Applies IANA / alias timezone via JalaliX (instant-preserving). */
+        this.withTimezone = (value, timezone = 'default') => {
+            return value.setTimezone(timezone);
+        };
+        /**
+         * Sets Jalali Y/M/D and wall clock in the value's active timezone.
+         * Month is 0-based (Farvardin = 0), matching MUI / `Date`.
+         */
+        this.setJalaliParts = (value, year, month, date, hours = 12, minutes = 0, seconds = 0, ms = 0) => {
+            const result = this.asJalaliX(value).clone();
+            result.setFullYear(year, month, date);
+            result.setHours(hours, minutes, seconds, ms);
+            return result;
+        };
+        /** Sets wall clock fields in the active timezone (defaults fill from current wall time). */
+        this.withWallTime = (value, hours, minutes, seconds, ms) => {
+            const current = this.asJalaliX(value).clone();
+            current.setHours(hours, minutes !== null && minutes !== void 0 ? minutes : current.getMinutes(), seconds !== null && seconds !== void 0 ? seconds : current.getSeconds(), ms !== null && ms !== void 0 ? ms : current.getMilliseconds());
+            return current;
+        };
+        this.weekDayName = (value) => WEEKDAY_NAMES[this.getDayOfWeek(value) - 1];
+        this.weekDayLetter = (value) => WEEKDAY_LETTERS[this.getDayOfWeek(value) - 1];
+        /**
+         * Builds a JalaliX date from a value, or returns “now” / `null`.
+         * @param value - ISO/string/timestamp to parse; `undefined` -> now; `null` -> `null`.
+         * @param timezone - MUI timezone (`'default'`, `'system'`, or IANA name).
+         * @returns A {@link JalaliX} instance, `null`, or an invalid date on parse failure.
+         */
+        this.date = (value, timezone = 'default') => {
+            if (value === null)
+                return null;
+            if (value === undefined) {
+                return this.withTimezone(new typescript_1.default(), timezone);
+            }
+            try {
+                return this.withTimezone(typescript_1.default.create(value), timezone);
+            }
+            catch (_a) {
+                return this.getInvalidDate();
+            }
+        };
+        /**
+         * Returns an invalid JalaliX date (`NaN` timestamp) for failed parses.
+         * @returns Invalid {@link JalaliX} instance.
+         */
+        this.getInvalidDate = () => new typescript_1.default(Number.NaN);
+        /**
+         * Resolves the timezone string for a picker value.
+         * @param value - Date value, or `null`.
+         * @returns IANA timezone, `'default'` if `value` is null, or `'system'` on error.
+         */
+        this.getTimezone = (value) => {
+            if (value == null)
+                return 'default';
+            try {
+                return this.asJalaliX(value).getTimezone();
+            }
+            catch (_a) {
+                return 'system';
+            }
+        };
+        /**
+         * Returns a copy of `value` in the given timezone (instant-preserving).
+         * @param value - Source date.
+         * @param timezone - Target timezone (`'default'` / `'system'` / IANA / `'UTC'`).
+         * @returns JalaliX in the requested timezone.
+         */
+        this.setTimezone = (value, timezone) => {
+            return this.asJalaliX(value).setTimezone(timezone);
+        };
+        /**
+         * Converts a picker value to a native JavaScript `Date`.
+         * @param value - Picker date.
+         * @returns Equivalent `Date` (same epoch ms).
+         */
+        this.toJsDate = (value) => new Date(this.asJalaliX(value).getTime());
+        /**
+         * Parses a user-entered string with the given format into a JalaliX date.
+         * Uses {@link JalaliX.parseJalali} for common `YYYY/MM/DD` keyboard formats;
+         * otherwise tokenizes `format` (Persian digits accepted).
+         * @param value - Input string (empty -> `null`).
+         * @param format - Format pattern (e.g. `'YYYY/MM/DD'`, `'D MMM YYYY'`).
+         * @returns Parsed {@link JalaliX}, `null` if empty, or an invalid date on failure.
+         */
+        this.parse = (value, format) => {
+            if (value === '')
+                return null;
+            const normalized = typescript_1.default.fromPersian(String(value)).trim();
+            const expanded = this.expandFormat(format);
+            // Fast path: JalaliX native parse for common keyboard formats
+            if (/^YYYY[/.-]MM[/.-]DD(?:[ T]HH:mm(?::ss)?)?$/.test(expanded.replace(/\s+/g, ' ').trim()) || /^YYYY[/.-]MM[/.-]DD$/.test(expanded)) {
+                try {
+                    return typescript_1.default.parseJalali(normalized);
+                }
+                catch (_a) {
+                    return this.getInvalidDate();
+                }
+            }
+            return this.parseWithFormat(normalized, expanded);
+        };
+        this.parseWithFormat = (value, format) => {
+            const tokenOrder = [];
+            let regexSource = '';
+            let i = 0;
+            const tokens = [
+                { key: 'YYYY', pattern: '(\\d{4})' },
+                { key: 'MMMM', pattern: `(${MONTH_NAMES.join('|')})` },
+                { key: 'MMM', pattern: `(${MONTH_NAMES.join('|')})` },
+                { key: 'MM', pattern: '(\\d{1,2})' },
+                { key: 'DD', pattern: '(\\d{1,2})' },
+                { key: 'HH', pattern: '(\\d{1,2})' },
+                { key: 'hh', pattern: '(\\d{1,2})' },
+                { key: 'mm', pattern: '(\\d{1,2})' },
+                { key: 'ss', pattern: '(\\d{1,2})' },
+                { key: 'A', pattern: '(ق\\.ظ\\.|ب\\.ظ\\.|AM|PM|am|pm)' },
+                { key: 'a', pattern: '(ق\\.ظ\\.|ب\\.ظ\\.|AM|PM|am|pm)' },
+                { key: 'YY', pattern: '(\\d{2})' },
+                { key: 'M', pattern: '(\\d{1,2})' },
+                { key: 'D', pattern: '(\\d{1,2})' },
+                { key: 'H', pattern: '(\\d{1,2})' },
+                { key: 'h', pattern: '(\\d{1,2})' },
+                { key: 'm', pattern: '(\\d{1,2})' },
+                { key: 's', pattern: '(\\d{1,2})' }
+            ];
+            while (i < format.length) {
+                if (format[i] === this.escapedCharacters.start) {
+                    const end = format.indexOf(this.escapedCharacters.end, i + 1);
+                    if (end === -1) {
+                        regexSource += escapeRegExp(format[i]);
+                        i += 1;
+                        continue;
+                    }
+                    regexSource += escapeRegExp(format.slice(i + 1, end));
+                    i = end + 1;
+                    continue;
+                }
+                const matched = tokens.find(token => format.startsWith(token.key, i));
+                if (matched) {
+                    tokenOrder.push(matched);
+                    regexSource += matched.pattern;
+                    i += matched.key.length;
+                    continue;
+                }
+                regexSource += escapeRegExp(format[i]);
+                i += 1;
+            }
+            const match = value.match(new RegExp(`^${regexSource}$`));
+            if (!match)
+                return this.getInvalidDate();
+            let year = new typescript_1.default().getFullYear();
+            let month = 1;
+            let day = 1;
+            let hours = 0;
+            let minutes = 0;
+            let seconds = 0;
+            let isPM = null;
+            let hour12 = null;
+            tokenOrder.forEach((token, index) => {
+                const raw = match[index + 1];
+                switch (token.key) {
+                    case 'YYYY':
+                        year = Number(raw);
+                        break;
+                    case 'YY':
+                        year = 1400 + Number(raw);
+                        break;
+                    case 'MMMM':
+                    case 'MMM': {
+                        const monthIndex = MONTH_NAMES.indexOf(raw);
+                        if (monthIndex >= 0)
+                            month = monthIndex + 1;
+                        break;
+                    }
+                    case 'MM':
+                    case 'M':
+                        month = Number(raw);
+                        break;
+                    case 'DD':
+                    case 'D':
+                        day = Number(raw);
+                        break;
+                    case 'HH':
+                    case 'H':
+                        hours = Number(raw);
+                        break;
+                    case 'hh':
+                    case 'h':
+                        hour12 = Number(raw);
+                        break;
+                    case 'mm':
+                    case 'm':
+                        minutes = Number(raw);
+                        break;
+                    case 'ss':
+                    case 's':
+                        seconds = Number(raw);
+                        break;
+                    case 'A':
+                    case 'a':
+                        isPM = /ب\.ظ\.|pm/i.test(raw);
+                        break;
+                    default:
+                        break;
+                }
+            });
+            if (hour12 !== null) {
+                if (isPM === true && hour12 < 12)
+                    hours = hour12 + 12;
+                else if (isPM === false && hour12 === 12)
+                    hours = 0;
+                else
+                    hours = hour12;
+            }
+            if (month < 1 || month > 12 || day < 1 || day > 31)
+                return this.getInvalidDate();
+            const output = new typescript_1.default();
+            output.setFullYear(year, month - 1, day);
+            output.setHours(hours, minutes, seconds, 0);
+            return output;
+        };
+        /**
+         * @returns Active locale code, or `'fa'` when unset.
+         */
+        this.getCurrentLocaleCode = () => this.locale || 'fa';
+        /**
+         * Whether the current locale prefers a 12-hour clock (`en*` -> true).
+         * @returns `true` for English locales; otherwise `false`.
+         */
+        this.is12HourCycleInCurrentLocale = () => {
+            const locale = this.getCurrentLocaleCode().toLowerCase();
+            return locale.startsWith('en');
+        };
+        /**
+         * Normalizes MUI/localized format aliases to JalaliX tokens
+         * (`MMMM`->`MMM`, `dddd`/`ddd`->`WN`, word-boundary `dd`->`WL`).
+         * @param format - Format string from formats map or field props.
+         * @returns Expanded format string for {@link formatByString} / {@link parse}.
+         */
+        this.expandFormat = (format) => {
+            // JalaliX has no localized meta-tokens (L/LL/LT); keep format as-is aside from MMMM->MMM.
+            return format
+                .replace(/MMMM/g, 'MMM')
+                .replace(/dddd/g, 'WN')
+                .replace(/ddd/g, 'WN')
+                .replace(/\bdd\b/g, 'WL');
+        };
+        /**
+         * @param value - Value to validate.
+         * @returns Whether `value` is a valid {@link JalaliX} / Date.
+         */
+        this.isValid = (value) => {
+            if (value == null)
+                return false;
+            return typescript_1.default.isValidDate(this.asJalaliX(value));
+        };
+        /**
+         * Formats a date using a named key from {@link formats}.
+         * @param value - Date to format.
+         * @param formatKey - Key in {@link AdapterFormats} (e.g. `'fullDate'`, `'keyboardDate'`).
+         * @returns Formatted string.
+         */
+        this.format = (value, formatKey) => {
+            return this.formatByString(value, this.formats[formatKey]);
+        };
+        /**
+         * Formats a date with an explicit JalaliX format string.
+         * Protects weekday tokens (`WN`/`WL`) that would otherwise collide with week-number `W`.
+         * @param value - Date to format.
+         * @param formatString - Pattern (e.g. `'YYYY/MM/DD'`, `'WN D MMM YYYY'`).
+         * @returns Formatted string.
+         */
+        this.formatByString = (value, formatString) => {
+            const date = this.asJalaliX(value);
+            const expanded = this.expandFormat(formatString);
+            // JalaliX replaces bare `W` (week number) before `WN`/`WL`, so protect weekday tokens.
+            const placeholders = [];
+            const ph = (text) => {
+                const i = placeholders.length;
+                placeholders.push(text);
+                return `\uE100${i}\uE101`;
+            };
+            const safe = expanded
+                .replace(/WN/g, () => ph(this.weekDayName(date)))
+                .replace(/wn/g, () => ph(this.weekDayName(date)))
+                .replace(/WL/g, () => ph(this.weekDayLetter(date)))
+                .replace(/wl/g, () => ph(this.weekDayLetter(date)));
+            let output = date.format(safe);
+            placeholders.forEach((text, i) => {
+                output = output.replace(new RegExp(`\uE100${i}\uE101`, 'g'), () => text);
+            });
+            return output;
+        };
+        /**
+         * Localizes digits for field display (Western -> Persian; `,` -> `،`).
+         * @param numberToFormat - Digit string from MUI fields.
+         * @returns String with Persian numerals.
+         */
+        this.formatNumber = (numberToFormat) => typescript_1.default.toPersian(numberToFormat).replace(/,/g, '،');
+        /**
+         * @param value - First date (or `null`).
+         * @param comparing - Second date (or `null`).
+         * @returns `true` if both null or same epoch ms.
+         */
+        this.isEqual = (value, comparing) => {
+            if (value === null && comparing === null)
+                return true;
+            if (value === null || comparing === null)
+                return false;
+            return this.asJalaliX(value).getTime() === this.asJalaliX(comparing).getTime();
+        };
+        /** @returns Whether both dates share the same Jalali year. */
+        this.isSameYear = (value, comparing) => {
+            return this.getYear(value) === this.getYear(comparing);
+        };
+        /** @returns Whether both dates share the same Jalali year and month. */
+        this.isSameMonth = (value, comparing) => {
+            return this.isSameYear(value, comparing) && this.getMonth(value) === this.getMonth(comparing);
+        };
+        /** @returns Whether both dates fall on the same Jalali calendar day. */
+        this.isSameDay = (value, comparing) => {
+            return this.isSameMonth(value, comparing) && this.getDate(value) === this.getDate(comparing);
+        };
+        /** @returns Whether both dates share the same day and hour. */
+        this.isSameHour = (value, comparing) => {
+            return this.isSameDay(value, comparing) && this.getHours(value) === this.getHours(comparing);
+        };
+        /** @returns Whether `value` is strictly after `comparing` by timestamp. */
+        this.isAfter = (value, comparing) => {
+            return this.asJalaliX(value).getTime() > this.asJalaliX(comparing).getTime();
+        };
+        /** @returns Whether `value`'s Jalali year is after `comparing`'s. */
+        this.isAfterYear = (value, comparing) => {
+            return this.getYear(value) > this.getYear(comparing);
+        };
+        /** @returns Whether `value`'s calendar day is after `comparing`'s. */
+        this.isAfterDay = (value, comparing) => {
+            return !this.isSameDay(value, comparing) && this.isAfter(this.startOfDay(value), this.startOfDay(comparing));
+        };
+        /** @returns Whether `value` is strictly before `comparing` by timestamp. */
+        this.isBefore = (value, comparing) => {
+            return this.asJalaliX(value).getTime() < this.asJalaliX(comparing).getTime();
+        };
+        /** @returns Whether `value`'s Jalali year is before `comparing`'s. */
+        this.isBeforeYear = (value, comparing) => {
+            return this.getYear(value) < this.getYear(comparing);
+        };
+        /** @returns Whether `value`'s calendar day is before `comparing`'s. */
+        this.isBeforeDay = (value, comparing) => {
+            return !this.isSameDay(value, comparing) && this.isBefore(this.startOfDay(value), this.startOfDay(comparing));
+        };
+        /**
+         * @param value - Date to test.
+         * @param range - Inclusive `[start, end]` bounds.
+         * @returns Whether `value` lies within the range by timestamp.
+         */
+        this.isWithinRange = (value, range) => {
+            const time = this.asJalaliX(value).getTime();
+            return time >= this.asJalaliX(range[0]).getTime() && time <= this.asJalaliX(range[1]).getTime();
+        };
+        /**
+         * @param value - Reference date.
+         * @returns Start of that Jalali year (Farvardin 1, 00:00:00.000).
+         */
+        this.startOfYear = (value) => {
+            return this.setJalaliParts(value, this.getYear(value), 0, 1, 0, 0, 0, 0);
+        };
+        /**
+         * @param value - Reference date.
+         * @returns Start of that Jalali month (day 1, 00:00:00.000).
+         */
+        this.startOfMonth = (value) => {
+            return this.setJalaliParts(value, this.getYear(value), this.getMonth(value), 1, 0, 0, 0, 0);
+        };
+        /**
+         * Persian week starts on Saturday.
+         * @param value - Reference date.
+         * @returns Start of that week (Saturday 00:00:00.000).
+         */
+        this.startOfWeek = (value) => {
+            const dayOfWeek = this.getDayOfWeek(value);
+            return this.startOfDay(this.addDays(value, 1 - dayOfWeek));
+        };
+        /**
+         * @param value - Reference date.
+         * @returns Same calendar day at 00:00:00.000 local wall time.
+         */
+        this.startOfDay = (value) => {
+            return this.withWallTime(value, 0, 0, 0, 0);
+        };
+        /**
+         * @param value - Reference date.
+         * @returns End of that Jalali year (last moment of Esfand).
+         */
+        this.endOfYear = (value) => {
+            return this.endOfMonth(this.setJalaliParts(value, this.getYear(value), 11, 1, 12, 0, 0, 0));
+        };
+        /**
+         * @param value - Reference date.
+         * @returns End of that Jalali month (23:59:59.999 on the last day).
+         */
+        this.endOfMonth = (value) => {
+            const days = this.getDaysInMonth(value);
+            return this.setJalaliParts(value, this.getYear(value), this.getMonth(value), days, 23, 59, 59, 999);
+        };
+        /**
+         * Persian week ends on Friday.
+         * @param value - Reference date.
+         * @returns End of that week (Friday 23:59:59.999).
+         */
+        this.endOfWeek = (value) => {
+            const dayOfWeek = this.getDayOfWeek(value);
+            return this.endOfDay(this.addDays(value, 7 - dayOfWeek));
+        };
+        /**
+         * @param value - Reference date.
+         * @returns Same calendar day at 23:59:59.999 local wall time.
+         */
+        this.endOfDay = (value) => {
+            return this.withWallTime(value, 23, 59, 59, 999);
+        };
+        /**
+         * @param value - Source date.
+         * @param amount - Years to add (may be negative).
+         * @returns New JalaliX with year adjusted.
+         */
+        this.addYears = (value, amount) => this.setYear(value, this.getYear(value) + amount);
+        /**
+         * Adds months with day clamping to the target month length.
+         * @param value - Source date.
+         * @param amount - Months to add (may be negative).
+         * @returns New JalaliX with month adjusted.
+         */
+        this.addMonths = (value, amount) => {
+            const current = this.asJalaliX(value);
+            const totalMonths = this.getYear(current) * 12 + this.getMonth(current) + amount;
+            const year = Math.floor(totalMonths / 12);
+            const month = ((totalMonths % 12) + 12) % 12;
+            const maxDay = this.getDaysInMonth(this.setJalaliParts(current, year, month, 1, 12));
+            const day = Math.min(this.getDate(current), maxDay);
+            return this.setJalaliParts(current, year, month, day, current.getHours(), current.getMinutes(), current.getSeconds(), current.getMilliseconds());
+        };
+        /**
+         * @param value - Source date.
+         * @param amount - Weeks to add (may be negative).
+         * @returns New JalaliX with days shifted by `amount * 7`.
+         */
+        this.addWeeks = (value, amount) => this.addDays(value, amount * 7);
+        /**
+         * Adds calendar days (wall time preserved via JalaliX timezone-aware setters).
+         * @param value - Source date.
+         * @param amount - Days to add (may be negative).
+         * @returns New JalaliX with day adjusted.
+         */
+        this.addDays = (value, amount) => {
+            return this.asJalaliX(value).clone().addDays(amount);
+        };
+        /**
+         * @param value - Source date.
+         * @param amount - Hours to add (may be negative).
+         * @returns New JalaliX with timestamp shifted by hours.
+         */
+        this.addHours = (value, amount) => {
+            const result = this.asJalaliX(value).clone();
+            result.setTime(result.getTime() + amount * 3600000);
+            return result;
+        };
+        /**
+         * @param value - Source date.
+         * @param amount - Minutes to add (may be negative).
+         * @returns New JalaliX with timestamp shifted by minutes.
+         */
+        this.addMinutes = (value, amount) => {
+            const result = this.asJalaliX(value).clone();
+            result.setTime(result.getTime() + amount * 60000);
+            return result;
+        };
+        /**
+         * @param value - Source date.
+         * @param amount - Seconds to add (may be negative).
+         * @returns New JalaliX with timestamp shifted by seconds.
+         */
+        this.addSeconds = (value, amount) => {
+            const result = this.asJalaliX(value).clone();
+            result.setTime(result.getTime() + amount * 1000);
+            return result;
+        };
+        /** @returns Jalali year. */
+        this.getYear = (value) => this.asJalaliX(value).getFullYear();
+        /**
+         * 0-based Jalali month (0 = Farvardin).
+         * @returns Month index 0–11.
+         */
+        this.getMonth = (value) => this.asJalaliX(value).getMonth() - 1;
+        /** @returns Day of month (1–31). */
+        this.getDate = (value) => this.asJalaliX(value).getDate();
+        /** @returns Hours (0–23). */
+        this.getHours = (value) => this.asJalaliX(value).getHours();
+        /** @returns Minutes (0–59). */
+        this.getMinutes = (value) => this.asJalaliX(value).getMinutes();
+        /** @returns Seconds (0–59). */
+        this.getSeconds = (value) => this.asJalaliX(value).getSeconds();
+        /** @returns Milliseconds (0–999). */
+        this.getMilliseconds = (value) => this.asJalaliX(value).getMilliseconds();
+        /**
+         * @param value - Source date.
+         * @param year - Jalali year to set.
+         * @returns New JalaliX with year replaced (month/day/time preserved).
+         */
+        this.setYear = (value, year) => {
+            const current = this.asJalaliX(value);
+            return this.setJalaliParts(current, year, current.getMonth() - 1, current.getDate(), current.getHours(), current.getMinutes(), current.getSeconds(), current.getMilliseconds());
+        };
+        /**
+         * @param value - Source date.
+         * @param month - 0-based Jalali month (0 = Farvardin).
+         * @returns New JalaliX with month replaced.
+         */
+        this.setMonth = (value, month) => {
+            const current = this.asJalaliX(value);
+            return this.setJalaliParts(current, current.getFullYear(), month, current.getDate(), current.getHours(), current.getMinutes(), current.getSeconds(), current.getMilliseconds());
+        };
+        /**
+         * @param value - Source date.
+         * @param date - Day of month to set.
+         * @returns New JalaliX with day replaced.
+         */
+        this.setDate = (value, date) => {
+            const current = this.asJalaliX(value);
+            return this.setJalaliParts(current, current.getFullYear(), current.getMonth() - 1, date, current.getHours(), current.getMinutes(), current.getSeconds(), current.getMilliseconds());
+        };
+        /**
+         * @param value - Source date.
+         * @param hours - Hours to set (0–23).
+         * @returns New JalaliX with hours replaced.
+         */
+        this.setHours = (value, hours) => this.withWallTime(value, hours);
+        /**
+         * @param value - Source date.
+         * @param minutes - Minutes to set.
+         * @returns New JalaliX with minutes replaced.
+         */
+        this.setMinutes = (value, minutes) => {
+            const current = this.asJalaliX(value);
+            return this.withWallTime(current, current.getHours(), minutes);
+        };
+        /**
+         * @param value - Source date.
+         * @param seconds - Seconds to set.
+         * @returns New JalaliX with seconds replaced.
+         */
+        this.setSeconds = (value, seconds) => {
+            const current = this.asJalaliX(value);
+            return this.withWallTime(current, current.getHours(), current.getMinutes(), seconds);
+        };
+        /**
+         * @param value - Source date.
+         * @param milliseconds - Milliseconds to set.
+         * @returns New JalaliX with milliseconds replaced.
+         */
+        this.setMilliseconds = (value, milliseconds) => {
+            const current = this.asJalaliX(value);
+            return this.withWallTime(current, current.getHours(), current.getMinutes(), current.getSeconds(), milliseconds);
+        };
+        /**
+         * Days in the Jalali month of `value` (31 / 30 / 29–30 for Esfand).
+         * @param value - Reference date.
+         * @returns Day count for that month.
+         */
+        this.getDaysInMonth = (value) => {
+            const month = this.getMonth(value); // 0-based
+            if (month <= 5)
+                return 31;
+            if (month <= 10)
+                return 30;
+            // Esfand: leap years have 30 days
+            const probe = this.asJalaliX(value).clone();
+            probe.setFullYear(this.getYear(value), 11, 30);
+            return probe.getMonth() === 12 && probe.getDate() === 30 ? 30 : 29;
+        };
+        /**
+         * Builds the month grid as weeks (Saturday-start) for calendar UIs.
+         * @param value - Any date in the target month.
+         * @returns Array of weeks; each week is seven {@link JalaliX} days.
+         */
+        this.getWeekArray = (value) => {
+            const start = this.startOfWeek(this.startOfMonth(value));
+            const end = this.endOfWeek(this.endOfMonth(value));
+            let count = 0;
+            let current = start;
+            const nestedWeeks = [];
+            while (!this.isAfter(current, end)) {
+                const weekNumber = Math.floor(count / 7);
+                nestedWeeks[weekNumber] = nestedWeeks[weekNumber] || [];
+                nestedWeeks[weekNumber].push(current);
+                current = this.addDays(current, 1);
+                count += 1;
+            }
+            return nestedWeeks;
+        };
+        /**
+         * @param value - Reference date.
+         * @returns Jalali week-of-year (1–53).
+         */
+        this.getWeekNumber = (value) => this.asJalaliX(value).getWeekOfYear();
+        /**
+         * 1-based day of week with Saturday as the first day (Persian week).
+         * @param value - Reference date.
+         * @returns 1 (Saturday) … 7 (Friday).
+         */
+        this.getDayOfWeek = (value) => {
+            const day = this.asJalaliX(value).getDay();
+            return day === 0 ? 7 : day;
+        };
+        /**
+         * Lists year-start dates from `start` through `end` (inclusive range walk).
+         * @param range - `[start, end]` picker dates.
+         * @returns One {@link JalaliX} per year at start-of-year.
+         */
+        this.getYearRange = ([start, end]) => {
+            const startDate = this.startOfYear(start);
+            const endDate = this.endOfYear(end);
+            const years = [];
+            let current = startDate;
+            while (this.isBefore(current, endDate)) {
+                years.push(current);
+                current = this.addYears(current, 1);
+            }
+            return years;
+        };
+        /**
+         * Optional helper for older pickers / custom UIs.
+         * @param ampm - `'am'` or `'pm'`.
+         * @returns Persian meridiem (`ق.ظ.` / `ب.ظ.`).
+         */
+        this.getMeridiemText = (ampm) => (ampm === 'am' ? 'ق.ظ.' : 'ب.ظ.');
+        if (locale !== undefined)
+            this.locale = locale;
+        this.formats = Object.assign(Object.assign({}, defaultFormats), formats);
+    }
+}
+exports.AdapterJalaliX = AdapterJalaliX;
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Release Notes
+All notable changes to this package will be documented in this file.
+
+## 0.2.0
+- Support `@mui/x-date-pickers` **v9** (peer range: ^6 || ^7 || ^8 || ^9)
+- Dev/types aligned with latest MUI X Date Pickers adapter interface
+- Wired timezone APIs to `@jalalix/typescript` ^0.8.0 instant-preserving IANA model
+- Simplified day/time helpers (no `Date.prototype` midnight workarounds)
+- Documented `DateTimeField` `timezone` usage
+- Initial `AdapterJalaliX` for MUI X Date Pickers (`@mui/x-date-pickers` ^6 || ^7 || ^8)
+- Jalali calendar via `@jalalix/typescript` (^0.7.0)
+- Default keyboard formats: `YYYY/MM/DD`, `YYYY/MM/DD HH:mm`
+- Persian month/weekday names and optional Persian digits via `formatNumber`
+
+## 0.1.0
+- Initial commit

package/README.md

@@ -1 +1,61 @@
-# Jalali X - MUI
+# JalaliX
+
+Jalali (Persian/Shamsi) adapter for [MUI X Date Pickers](https://mui.com/x/react-date-pickers/), powered by [`@jalalix/typescript`](https://www.npmjs.com/package/@jalalix/typescript).
+
+## Install
+
+```bash
+npm install @jalalix/mui @jalalix/typescript @mui/x-date-pickers
+```
+
+Peer dependencies: `react` (^17 || ^18 || ^19) and `@mui/x-date-pickers` (^6 || ^7 || ^8 || ^9).
+
+## Usage
+
+```tsx
+import { LocalizationProvider } from '@mui/x-date-pickers/LocalizationProvider'
+import { DateTimeField } from '@mui/x-date-pickers/DateTimeField'
+import { DatePicker } from '@mui/x-date-pickers/DatePicker'
+import { AdapterJalaliX, JalaliX } from '@jalalix/mui'
+
+export function App() {
+	return (
+		<LocalizationProvider dateAdapter={AdapterJalaliX} adapterLocale="fa">
+			<DateTimeField defaultValue={new JalaliX()} />
+			<DatePicker label="تاریخ" />
+		</LocalizationProvider>
+	)
+}
+```
+
+Keyboard formats default to Jalali-friendly patterns such as `YYYY/MM/DD` and `YYYY/MM/DD HH:mm`. Month names and weekdays render in Persian via JalaliX.
+
+## Timezone
+
+`AdapterJalaliX` is timezone-compatible (`isTimezoneCompatible = true`). It delegates to `@jalalix/typescript` **instant-preserving** IANA zones:
+
+- `getTimezone(value)` / `setTimezone(value, tz)` use JalaliX
+- Aliases: `default` / `local` / `system` -> host IANA; `utc` / `gmt` -> `UTC`
+- Changing timezone keeps the same Unix instant; wall/Jalali display updates
+
+```tsx
+<LocalizationProvider dateAdapter={AdapterJalaliX}>
+	<DateTimeField timezone="Asia/Tehran" />
+</LocalizationProvider>
+```
+
+Requires `@jalalix/typescript` ^0.8.0. Compatible with MUI X Date Pickers **v6–v9** (tested against v9).
+
+## API
+
+```ts
+import { AdapterJalaliX, JalaliX } from '@jalalix/mui'
+import type { JalaliDate, JalaliOptions, JalaliFormatOptions } from '@jalalix/mui'
+```
+
+- `AdapterJalaliX` — `MuiPickersAdapter` implementation (`lib: 'jalalix'`)
+- `JalaliX` — re-export of `@jalalix/typescript`
+
+## License
+
+MIT

package/index.d.ts

@@ -0,0 +1,4 @@
+/** MUI X Date Pickers adapter for JalaliX — see {@link AdapterJalaliX}. */
+export { AdapterJalaliX } from './AdapterJalaliX';
+export { default as JalaliX } from '@jalalix/typescript';
+export type { JalaliOptions, JalaliFormatOptions, JalaliDate } from './index.types';

package/index.js

@@ -1 +1,11 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JalaliX = exports.AdapterJalaliX = void 0;
+/** MUI X Date Pickers adapter for JalaliX — see {@link AdapterJalaliX}. */
+var AdapterJalaliX_1 = require("./AdapterJalaliX");
+Object.defineProperty(exports, "AdapterJalaliX", { enumerable: true, get: function () { return AdapterJalaliX_1.AdapterJalaliX; } });
+var typescript_1 = require("@jalalix/typescript");
+Object.defineProperty(exports, "JalaliX", { enumerable: true, get: function () { return __importDefault(typescript_1).default; } });

package/index.types.d.ts

@@ -0,0 +1,17 @@
+export type JalaliDate = {
+    year: number;
+    month: number;
+    day: number;
+    hours: number;
+    min: number;
+    sec: number;
+    ms: number;
+    isLeapYear: boolean;
+};
+export type JalaliOptions = {
+    timezone?: string;
+};
+export type JalaliFormatOptions = {
+    calendar?: 'jalali' | 'gregorian';
+    persianDigits?: boolean;
+};

package/index.types.js

@@ -1 +1,2 @@
 "use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -1,11 +1,11 @@
 {
 	"name": "@jalalix/mui",
-	"version": "0.1.0",
+	"version": "0.2.0",
 	"private": false,
 	"main": "index.js",
 	"module": "index.js",
 	"types": "index.d.ts",
-	"description": "",
+	"description": "Jalali adapter for MUI X Date Pickers using @jalalix/typescript",
 	"author": "Hossein Maklavani <hos.mohamadi@gmail.com> (https://maklavani.dev)",
 	"contributors": [
 		{
@@ -14,14 +14,11 @@
 			"url": "https://maklavani.dev"
 		}
 	],
-	"scripts": {
-		"dev": "nodemon src/index.ts",
-		"build": "npm run remove && tsc --build tsconfig.json",
-		"remove": "ts-node scripts/remove.mjs"
-	},
 	"license": "MIT",
 	"keywords": [
 		"mui",
+		"mui-x",
+		"date-pickers",
 		"jalali",
 		"jalalix",
 		"persian",
@@ -29,7 +26,8 @@
 		"khorshidi",
 		"calendar",
 		"date",
-		"typescript"
+		"typescript",
+		"react"
 	],
 	"repository": {
 		"type": "git",
@@ -45,21 +43,54 @@
 		"url": "https://github.com/jalalix/mui/issues"
 	},
 	"homepage": "https://jalalix.com",
+	"scripts": {
+		"dev": "nodemon --exec \"node --experimental-strip-types\" src/index.ts",
+		"build": "npm run remove && tsc -p tsconfig.json",
+		"remove": "node scripts/remove.mjs",
+		"prepublishOnly": "npm run build"
+	},
+	"dependencies": {
+		"@jalalix/typescript": "^0.8.0"
+	},
+	"peerDependencies": {
+		"@mui/x-date-pickers": "^6.0.0 || ^7.0.0 || ^8.0.0 || ^9.0.0",
+		"react": "^17.0.0 || ^18.0.0 || ^19.0.0"
+	},
+	"peerDependenciesMeta": {
+		"react": {
+			"optional": true
+		}
+	},
+	"devDependencies": {
+		"@mui/x-date-pickers": "^9.18.0",
+		"@types/react": "^19.0.0",
+		"nodemon": "^3.1.14",
+		"react": "^19.0.0",
+		"react-dom": "^19.0.0",
+		"rimraf": "^6.1.4",
+		"typescript": "^7.0.2"
+	},
+	"engines": {
+		"node": ">=18"
+	},
+	"exports": {
+		".": {
+			"types": "./index.d.ts",
+			"require": "./index.js",
+			"import": "./index.js",
+			"default": "./index.js"
+		}
+	},
+	"sideEffects": false,
 	"files": [
+		"AdapterJalaliX.d.ts",
+		"AdapterJalaliX.js",
 		"index.d.ts",
 		"index.js",
 		"index.types.d.ts",
 		"index.types.js",
 		"LICENSE",
-		"README.md"
-	],
-	"dependencies": {
-		"@jalalix/typescript": "^0.3.0"
-	},
-	"devDependencies": {
-		"nodemon": "^3.1.10",
-		"rimraf": "^6.0.1",
-		"ts-node": "^10.9.2",
-		"typescript": "^5.8.3"
-	}
+		"README.md",
+		"CHANGELOG.md"
+	]
 }