@dakkiin/eida 0.1.0 → 0.1.1

package/README.md

@@ -0,0 +1,244 @@
+# @dakkiin/eida
+
+Utility helpers for common Enjaz/Eida frontend formatting tasks:
+
+- date formatting with consistent placeholders
+- currency conversion with direct rates or base-currency quotes
+- Arabic number-to-words spelling
+
+The package is distributed as ESM and typed with TypeScript declarations.
+
+## Installation
+
+```bash
+npm install @dakkiin/eida
+```
+
+`vue` is declared as a peer dependency.
+
+## Quick Start
+
+```ts
+import { useFormatDate, useCurrency, useNumbersToWords } from '@dakkiin/eida'
+
+const { toDDMMYYYY, toDateTime12h } = useFormatDate()
+const { convertCurrency, roundMoney } = useCurrency()
+const { spell } = useNumbersToWords()
+
+console.log(toDDMMYYYY('2026-06-16')) // 16/06/2026
+console.log(toDateTime12h('2026-06-16T13:45:00')) // 16/06/2026 01:45 PM
+
+const iqd = convertCurrency({
+  amount: 100,
+  from: 'USD',
+  to: 'IQD',
+  directRate: 1480
+})
+console.log(iqd) // 148000
+console.log(roundMoney(iqd, 0)) // 148000
+
+console.log(spell(1250)) // Arabic words for 1250
+```
+
+## Exports
+
+The package exports:
+
+- `useFormatDate`
+- `useCurrency`
+- `useNumbersToWords`
+- utility functions from currency module, including `convertCurrency`, `convertCurrencyWithDirectRate`, `convertCurrencyViaBase`, `roundMoney`, and `sameCurrency`
+
+---
+
+## Date Formatting (`useFormatDate`)
+
+```ts
+import { useFormatDate } from '@dakkiin/eida'
+
+const { toDDMMYY, toDDMMYYYY, toDateTime, toDateTime12h } = useFormatDate()
+```
+
+### `toDDMMYY(date)`
+
+- Input: `string | Date | null | undefined`
+- Output format: `DD/MM/YY`
+- Fallback when input is empty: `--/--/--`
+
+Example:
+
+```ts
+toDDMMYY('2026-06-16') // 16/06/26
+```
+
+### `toDDMMYYYY(date)`
+
+- Input: `string | Date | null | undefined`
+- Output format: `DD/MM/YYYY`
+- Fallback when input is empty: `--/--/----`
+
+Example:
+
+```ts
+toDDMMYYYY('2026-06-16') // 16/06/2026
+```
+
+### `toDateTime(date)`
+
+- Input: `string | Date | null | undefined`
+- Output format: `DD/MM/YYYY HH:mm` (24-hour)
+- Fallback when input is empty: `--/--/---- --:--`
+
+Example:
+
+```ts
+toDateTime('2026-06-16T13:45:00') // 16/06/2026 13:45
+```
+
+### `toDateTime12h(date)`
+
+- Input: `string | Date | null | undefined`
+- Output format: `DD/MM/YYYY hh:mm AM|PM` (12-hour)
+- Fallback when input is empty: `--/--/---- --:-- --`
+
+Example:
+
+```ts
+toDateTime12h('2026-06-16T13:45:00') // 16/06/2026 01:45 PM
+```
+
+### Notes
+
+- Date parsing relies on JavaScript `Date` behavior.
+- Invalid date strings can produce implementation-dependent output, so prefer ISO date inputs where possible.
+
+---
+
+## Currency Utilities (`useCurrency`)
+
+```ts
+import { useCurrency } from '@dakkiin/eida'
+
+const {
+  convertCurrency,
+  convertCurrencyWithDirectRate,
+  convertCurrencyViaBase,
+  roundMoney
+} = useCurrency()
+```
+
+### 1) Direct rate conversion
+
+Use `convertCurrencyWithDirectRate(amount, from, to, directRate)` when you already have one cross rate:
+
+- Formula: `amount * directRate`
+- `directRate` means: **units of `to` per 1 unit of `from`**
+- If `from` and `to` are the same (case-insensitive), original amount is returned.
+
+Example:
+
+```ts
+convertCurrencyWithDirectRate(100, 'USD', 'IQD', 1480) // 148000
+```
+
+### 2) Base-currency quote conversion
+
+Use `convertCurrencyViaBase(amount, from, to, baseCurrency, quotes)` when rates are defined against one base currency.
+
+Quote rule:
+
+- `quotes[currency] = units of currency per 1 baseCurrency`
+
+Example with base `USD`:
+
+```ts
+const quotes = { IQD: 1480, EUR: 0.92 }
+
+convertCurrencyViaBase(100, 'USD', 'IQD', 'USD', quotes) // 148000
+convertCurrencyViaBase(1480, 'IQD', 'USD', 'USD', quotes) // 1
+```
+
+### 3) Unified API
+
+Use `convertCurrency(options)` with either:
+
+- direct shape: `{ amount, from, to, directRate }`
+- base shape: `{ amount, from, to, baseCurrency, quotes }`
+
+Examples:
+
+```ts
+convertCurrency({
+  amount: 100,
+  from: 'USD',
+  to: 'IQD',
+  directRate: 1480
+})
+
+convertCurrency({
+  amount: 1480,
+  from: 'IQD',
+  to: 'USD',
+  baseCurrency: 'USD',
+  quotes: { IQD: 1480 }
+})
+```
+
+### `roundMoney(value, fractionDigits = 2)`
+
+Rounds using `Math.round`.
+
+```ts
+roundMoney(10.236) // 10.24
+roundMoney(10.236, 1) // 10.2
+```
+
+### Validation behavior
+
+- Non-finite amounts return `NaN`.
+- Invalid or missing rates/quotes throw `RangeError`.
+- Calling `convertCurrency` without a valid shape throws `TypeError`.
+
+---
+
+## Arabic Number Spelling (`useNumbersToWords`)
+
+```ts
+import { useNumbersToWords } from '@dakkiin/eida'
+
+const { spell } = useNumbersToWords()
+```
+
+### `spell(value)`
+
+- Input: `number`
+- Output: Arabic text representation of the integer value
+- Uses `Math.abs` + `Math.round` internally
+- Returns empty string for `0` and other falsy input values
+- Supports large numbers up to trillions based on current implementation rules
+
+Examples:
+
+```ts
+spell(1) // "واحد"
+spell(12) // "اثنى عشر"
+spell(1250) // Arabic phrase for 1250
+spell(-42.4) // Arabic phrase for 42 (rounded absolute value)
+```
+
+---
+
+## TypeScript
+
+Types are shipped from `dist/*.d.ts`, so imported APIs are strongly typed by default.
+
+## Build
+
+```bash
+npm run build
+```
+
+## License
+
+`UNLICENSED`
+

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@dakkiin/eida",
   "type": "module",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "private": false,
   "description": "Enjaz eida formatting utilities (dates, currency, Arabic number words)",
   "license": "UNLICENSED",