@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

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

<template>
  <div>
    <p>{{ persianDigits }}</p>
    <p>{{ formattedNumber }}</p>
    <p>{{ persianDate }}</p>
  </div>
</template>

<script setup lang="ts">
import { usePersianDigits, usePersianNumber, usePersianDate } from '@vue-persian/composables';

const { persian } = usePersianDigits('123');
const { formatted } = usePersianNumber(1234567);
const { persianDate } = usePersianDate();
</script>

API Documentation

useDirection

Manages document direction (RTL/LTR).

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

Example:

<script setup lang="ts">
import { useDirection } from '@vue-persian/composables';

const { direction, setDirection, toggleDirection, isRtl } = useDirection('rtl');
</script>

usePersianDigits

Converts between Western and Persian digits.

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

Example:

<script setup lang="ts">
import { usePersianDigits } from '@vue-persian/composables';

const { persian, western, setPersian } = usePersianDigits('123');
console.log(persian.value); // '۱۲۳'
console.log(western.value); // '123'
</script>

usePersianNumber

Formats numbers with Persian digits and custom separators.

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

Options:

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

Example:

<script setup lang="ts">
import { usePersianNumber } from '@vue-persian/composables';

const { formatted } = usePersianNumber(1234567, {
  thousandSeparator: '٬',
  prefix: '$'
});
console.log(formatted.value); // '$۱٬۲۳۴٬۵۶۷'
</script>

usePersianDate

Works with Jalali (Persian) calendar dates.

function usePersianDate(
  initialDate?: Date,
  options?: PersianDateOptions
): {
  persianDate: ComputedRef<string>;
  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:

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

Example:

<script setup lang="ts">
import { usePersianDate } from '@vue-persian/composables';

const { persianDate, jalali, setToday } = usePersianDate(new Date(), {
  format: 'full'
});
console.log(persianDate.value); // 'یکشنبه ۱ فروردین ۱۴۰۳'
</script>

usePersianCurrency

Formats amounts in Rial and Toman.

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

Options:

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

Example:

<script setup lang="ts">
import { usePersianCurrency } from '@vue-persian/composables';

const { currency, convertUnit } = usePersianCurrency(1000000, {
  unit: 'toman',
  showUnit: true
});
console.log(currency.value); // '۱۰۰٬۰۰۰ تومان'
</script>

usePersianText

Normalizes Persian text (Yeh, Keh, ZWNJ).

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

Options:

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

Example:

<script setup lang="ts">
import { usePersianText } from '@vue-persian/composables';

const { normalized } = usePersianText('سلامي كتاب', {
  normalizeYeh: true,
  normalizeKeh: true
});
console.log(normalized.value); // 'سلامی کتاب'
</script>

usePersianInput

Handles input with auto-conversion and normalization.

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

Example:

<template>
  <input v-bind="inputAttrs" @input="handleInput" @paste="handlePaste" />
</template>

<script setup lang="ts">
import { usePersianInput } from '@vue-persian/composables';

const { inputAttrs, handleInput, handlePaste } = usePersianInput({
  autoConvert: true,
  normalize: true
});
</script>

Utility Functions

Digits

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

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

Text

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

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

Types

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