@vue-persian/composables

A comprehensive TypeScript library of Persian language composables for Vue.js 3. This library provides utilities for working with Persian numbers, dates, currency, text normalization, and RTL/LTR direction handling.

Installation

``bash
npm install @vue-persian/composables


or

yarn add @vue-persian/composables

or

pnpm add @vue-persian/composables
`

Features

- Direction Management: Toggle between RTL and LTR directions
- Persian Digits: Convert between Western and Persian numerals
- Number Formatting: Format numbers with Persian digits and separators
- Date Conversion: Work with Jalali (Persian) calendar dates
- Currency Formatting: Format amounts in Rial and Toman
- Text Normalization: Normalize Persian text (Yeh, Keh, ZWNJ)
- Input Handling: Auto-convert and normalize input values

Quick Start

`vue



`

API Documentation

$3

Manages document direction (RTL/LTR).

`typescript
function useDirection(initialDirection?: Direction): {
direction: Ref;
setDirection: (direction: Direction) => void;
toggleDirection: () => void;
isRtl: ComputedRef;
}
`

Example:

`vue

`

$3

Converts between Western and Persian digits.

`typescript
function usePersianDigits(initialValue?: string | number): {
persian: Ref;
western: ComputedRef;
setPersian: (value: string | number) => void;
toWestern: () => string;
hasPersianDigits: ComputedRef;
}
`

Example:

`vue

`

$3

Formats numbers with Persian digits and custom separators.

`typescript
function usePersianNumber(
initialValue?: number | string,
options?: PersianNumberOptions
): {
formatted: ComputedRef;
setNumber: (value: number | string) => void;
}
`

Options:

`typescript
interface PersianNumberOptions {
thousandSeparator?: string; // Default: '٬'
decimalSeparator?: string; // Default: '٫'
prefix?: string;
suffix?: string;
decimals?: number;
}
`

Example:

`vue

`

$3

Works with Jalali (Persian) calendar dates.

`typescript
function usePersianDate(
initialDate?: Date,
options?: PersianDateOptions
): {
persianDate: ComputedRef;
jalali: ComputedRef<{ jy: number; jm: number; jd: number }>;
setToday: () => void;
setJalaliDate: (year: number, month: number, day: number) => void;
toGregorian: () => { gy: number; gm: number; gd: number };
}
`

Options:

`typescript
interface PersianDateOptions {
format?: 'full' | 'long' | 'short' | 'time' | 'datetime';
showYear?: boolean;
showMonth?: boolean;
showDay?: boolean;
showWeekday?: boolean;
}
`

Example:

`vue

`

$3

Formats amounts in Rial and Toman.

`typescript
function usePersianCurrency(
initialAmount?: number,
options?: PersianCurrencyOptions
): {
currency: ComputedRef;
setAmount: (value: number) => void;
convertUnit: () => void;
unitLabel: ComputedRef;
}
`

Options:

`typescript
interface PersianCurrencyOptions {
unit?: 'rial' | 'toman';
separator?: string;
decimals?: number;
showUnit?: boolean;
}
`

Example:

`vue

`

$3

Normalizes Persian text (Yeh, Keh, ZWNJ).

`typescript
function usePersianText(
initialText?: string,
options?: TextNormalizationOptions
): {
normalized: ComputedRef;
yehNormalized: ComputedRef;
kehNormalized: ComputedRef;
zwnjHandled: ComputedRef;
setText: (value: string) => void;
append: (value: string) => void;
}
`

Options:

`typescript
interface TextNormalizationOptions {
normalizeYeh?: boolean;
normalizeKeh?: boolean;
handleZWNJ?: boolean;
}
`

Example:

`vue

`

$3

Handles input with auto-conversion and normalization.

`typescript
function usePersianInput(options?: {
autoConvert?: boolean;
normalize?: boolean;
textOptions?: TextNormalizationOptions;
}): {
value: Ref;
inputAttrs: ComputedRef<{ value: string; dir: 'rtl' }>;
handleInput: (event: Event) => void;
handlePaste: (event: ClipboardEvent) => void;
}
`

Example:

`vue



`

Utility Functions

$3

`typescript
import {
toPersianDigits,
toWesternDigits,
hasPersianDigits,
formatNumber
} from '@vue-persian/composables';

toPersianDigits('123'); // '۱۲۳'
toWesternDigits('۱۲۳'); // '123'
hasPersianDigits('۱۲۳'); // true
formatNumber(1234567, { thousandSeparator: '٬' }); // '۱٬۲۳۴٬۵۶۷'
`

$3

`typescript
import {
normalizeYeh,
normalizeKeh,
handleZWNJ,
normalizePersianText
} from '@vue-persian/composables';

normalizeYeh('سلامي'); // 'سلامی'
normalizeKeh('كتاب'); // 'کتاب'
handleZWNJ('میروم'); // 'می\u200cروم'
normalizePersianText('سلامي كتاب', {
normalizeYeh: true,
normalizeKeh: true
}); // 'سلامی کتاب'
`

Types

`typescript
type Direction = 'rtl' | 'ltr';

interface PersianNumberOptions {
thousandSeparator?: string;
decimalSeparator?: string;
prefix?: string;
suffix?: string;
decimals?: number;
}

interface PersianCurrencyOptions {
unit?: 'rial' | 'toman';
separator?: string;
decimals?: number;
showUnit?: boolean;
}

type DateFormat = 'full' | 'long' | 'short' | 'time' | 'datetime';

interface PersianDateOptions {
format?: DateFormat;
showYear?: boolean;
showMonth?: boolean;
showDay?: boolean;
showWeekday?: boolean;
}

interface TextNormalizationOptions {
normalizeYeh?: boolean;
normalizeKeh?: boolean;
handleZWNJ?: boolean;
}

interface JalaliDate {
jy: number;
jm: number;
jd: number;
}
`

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature`)
5. Open a Pull Request

License

MIT

Acknowledgments

- jalaali-js for Jalali calendar conversion
- Vue.js for the reactive framework