# Wiki TimeAr

## مقدمة
مكتبة بسيطة تهدف إلى تحويل التواريخ أو الأوقات إلى نصوص عربية طبيعية وواضحة، خاصة في السياقات المتعلقة بالوقت النسبي. على سبيل المثال: "الآن"، "منذ دقيقة"، "بعد ساعتين"، أو "منذ 3 أيام".

الهدف الأساسي من هذه المكتبة هو أن يكون العرض العربي أسهل وأكثر إنسانية في التطبيقات، دون الحاجة إلى بناء منطق تفاعل زمني يدوي في كل مرة.

## لماذا هذه المكتبة بالذات ؟

غالبًا ما تحتاج واجهات التطبيقات إلى أن تعرض الوقت بشكل إنساني، لا كما هي القيم الخام من الخادم أو من النظام. بدلًا من إظهار تاريخ كامل أو وقت تقني، من المفيد أن يرى المستخدم نصًا مثل:

- الآن
- منذ 10 دقائق
- بعد ساعة
- منذ يومين

هذا النوع من النصوص يجعل التطبيق أكثر سلاسة ووضوحًا، خاصة عند استخدامه داخل لوحات التحكم أو الأنظمة التي تتطلب تفاعل عربي.

## التثبيت

```bash
npm install time-ar
```

## الاستخدام الأساسي

```ts
import timeAr from "time-ar";

const t = timeAr();
const output = t.getTimeAr("21-03-2026", t.format.shortDate);

console.log(output);
```

## الـ `timeAr()`

عند استدعاء الدالة الرئيسية، يتم إرجاع كائن يحتوي على ثلاثة أجزاء رئيسية:

```ts
const time = timeAr();
```

### 1) `format`

يحتوي هذا الكائن على جميع تنسيقات التاريخ المتاحة لك، بحيث يمكنك تمريرها مباشرة إلى `getTimeAr`.

```ts
const t = timeAr();
console.log(t.format.shortDate);
console.log(t.format.fullDateTime);
```

### 2) `setTimezone(timezone)`

تستخدم هذه الدالة لتغيير المنطقة الزمنية الافتراضية داخل المكتبة.

```ts
const t = timeAr();
t.setTimezone("Asia/Riyadh");
```

إذا كانت المنطقة الزمنية غير موجودة، سيتم إلقاء خطأ واضح.

### 3) `getTimeAr(time, timeFormat)`

هذه هي الوظيفة الأساسية في المكتبة. تأخذ تاريخًا أو نصًا وتعيد نصًا عربيًا يصف الزمن النسبي.

```ts
const t = timeAr();

const a = t.getTimeAr("21-03-2026 14:30:00", t.format.fullDateTime);
```

### أنواع المدخلات

```ts
Date
string
```

عند تمرير نص، يجب أن يكون مطابقًا للتنسيق الذي تضعه في `timeFormat`.

## تنسيقات التاريخ المدعومة

| المفتاح          | التنسيق                   | مثال                   |
| ---------------- | ------------------------- | ---------------------- |
| `shortDate`      | `DD-MM-YYYY`              | `21-03-2026`           |
| `longDate`       | `MMMM D, YYYY`            | `March 21, 2026`       |
| `shortTime`      | `HH:mm`                   | `14:30`                |
| `longTime`       | `HH:mm:ss`                | `14:30:15`             |
| `fullDateTime`   | `DD-MM-YYYY HH:mm:ss`     | `21-03-2026 14:30:15`  |
| `monthDay`       | `MMMM D`                  | `March 21`             |
| `monthYear`      | `MMMM YYYY`               | `March 2026`           |
| `dayMonthYear`   | `DD/MM/YYYY`              | `21/03/2026`           |
| `iso8601`        | `YYYY-MM-DDTHH:mm:ssZ[Z]` | `2026-03-21T14:30:15Z` |
| `time12h`        | `hh:mm A`                 | `02:30 PM`             |
| `time12hSeconds` | `hh:mm:ss A`              | `02:30:15 PM`          |

## أمثلة على المخرجات

```ts
const t = timeAr();

// مثال: منذ 3 أيام
console.log(t.getTimeAr("2026-09-13T14:30:15Z", t.format.iso8601));
```

النتائج المختلفة تعتمد على الوقت الحالي والمنطقة الزمنية المحددة.

## التعامل مع المناطق الزمنية

من المفضل ضبط المنطقة الزمنية عند بدء استخدام المكتبة إذا كان التطبيق يعمل عبر مناطق مختلفة.

```ts
const t = timeAr();
t.setTimezone("UTC");
```

أو:

```ts
const t = timeAr();
t.setTimezone("Asia/Riyadh");
```

## ملاحظات تنفيذية

- المكتبة صُممت خصيصًا لعرض الوقت النسبي بالعربية.
- تعمل على حساب الفرق بين الوقت الحالي والوقت المطلوب.
- عند تمرير نصوص، يجب أن يطابق المدخل التنسيق المحدد بشكل كامل.
- إذا كانت قيمة التاريخ غير صالحة، سيتم إلقاء خطأ واضح.

## مثال كامل

```ts
import timeAr from "time-ar";

const t = timeAr();

t.setTimezone("Asia/Riyadh");

console.log(t.getTimeAr("21-03-2026 14:30:00", t.format.fullDateTime));
console.log(t.getTimeAr("2026-03-21T14:30:15Z", t.format.iso8601));
```

## الخلاصة

TimeAr تبسط عرض الوقت بالعربية بطريقة طبيعية وسريعة، وهي مناسبة للمشاريع الصغيرة والمتوسطة التي تحتاج عرضًا إنسانيًا بدلًا من القيم الزمنية التقنية فقط.

إذا أردت، يمكن توسيع المكتبة لاحقًا لتشمل:

- دعم المزيد من اللغات
- تنسيقات عربية أكثر احترافية
- دعم نطاقات زمنية أكبر
- اختبارات تلقائية شاملة