✨ OmniHelper.js: مكتبة JavaScript الشاملة ✨

نظرة عامة (Overview) 🚀

OmniHelper.js ليست مجرد مكتبة مساعدة أخرى؛ إنها صندوق أدوات متكامل مصمم بعناية فائقة لتبسيط رحلة تطوير JavaScript. تهدف هذه المكتبة إلى أن تكون الحل الأمثل الذي يغنيك عن استخدام العديد من المكتبات الصغيرة المتفرقة في مشاريعك.

توفر OmniHelper.js مجموعة واسعة من الوظائف الأساسية والمتقدمة، بدءًا من تحويل البيانات الذكي، مروراً بـ التسجيل الملون والمُنظَّم (Smart Logging)، وصولاً إلى الرسوم المتحركة الدقيقة (Micro Animations) وإشعارات التنبيه الأنيقة (Toast Notifications)، بالإضافة إلى مجموعة غنية من الأدوات العامة المتنوعة.

💡 ميزة جوهرية: تم بناء المكتبة بالاعتماد على JavaScript الخالص، مما يعني أنها لا تتطلب أي تبعيات خارجية أو أطر عمل. تعمل بسلاسة تامة في بيئات المتصفح (Browser) وتطبيقات Node.js، مما يجعلها مناسبة لأي نوع من مشاريع JavaScript.

المطور (The Architect) 👨‍💻

تم تطوير هذه المكتبة المتميزة بواسطة:

محمد أشرف (Mohamed Ashraf)

للتواصل والدعم، يمكنكم زيارة صفحته على فيسبوك: https://www.facebook.com/share/1Gf47LvFjv/

التثبيت والاستخدام (Installation & Usage) 🛠️

ابدأ باستخدام OmniHelper.js في مشروعك بخطوات بسيطة وواضحة:

1. في بيئة المتصفح (Browser Environment)

قم بإضافة وسم script التالي إلى ملف HTML الخاص بك:

<script src="OmniHelper.js"></script>

2. في بيئة Node.js

يمكنك استيراد المكتبة واستخدامها مباشرةً:

const OmniHelper = require('./OmniHelper.js');

الوحدات الرئيسية (Core Modules) 🧩

تنقسم المكتبة إلى خمس وحدات رئيسية، كل منها متخصص في مجال معين لتقديم أقصى درجات الكفاءة والتنظيم:

1. محول البيانات (Data Transformer) 🔄

توفر هذه الوحدة وظائف قوية ومرنة لمعالجة وتحويل هياكل البيانات المعقدة، بما في ذلك المصفوفات (Arrays)، الكائنات (Objects)، وبيانات JSON.

| الوظيفة | الوصف | | :--- | :--- | | transform(data, transformerFn) | تطبيق دالة تحويل على البيانات المُعطاة. | | map(data, callback) | تطبيق دالة رد نداء على كل عنصر في مصفوفة أو كائن. | | filter(data, predicate) | تصفية مصفوفة أو كائن بناءً على دالة شرطية. | | flatten(data, depth) | تسطيح هياكل البيانات المتداخلة إلى عمق محدد. | | groupBy(array, key) | تجميع عناصر المصفوفة بناءً على مفتاح محدد. | | sortBy(array, key, order) | فرز عناصر المصفوفة تصاعدياً أو تنازلياً. | | deepParse(jsonString, defaultValue) | تحليل سلسلة JSON مع معالجة الأخطاء. | | serialize(data, indent) | تحويل البيانات إلى سلسلة JSON مع خيار التنسيق الجميل. | | convertType(value, targetType) | تحويل قيمة إلى نوع بيانات محدد. |

أمثلة على الاستخدام:

// تحويل البيانات
OmniHelper.Data.transform(5, function(n) { return n * 2; }); // 10

// التصفية
OmniHelper.Data.filter([1, 2, 3, 4, 5], function(n) { return n > 2; }); // [3, 4, 5]

// التجميع
OmniHelper.Data.groupBy([ /* ... */ ], 'category');

2. المسجل الذكي (Smart Logger) 📝

لجعل عملية تصحيح الأخطاء (Debugging) أكثر فعالية ومتعة، توفر هذه الوحدة تسجيلًا مُحسَّنًا للوحدة الطرفية (Console) مع دعم الألوان، الفئات، وخيارات التنسيق المتنوعة.

| الوظيفة | الوصف | | :--- | :--- | | log(message, type, data) | تسجيل رسالة بنوع محدد وبيانات اختيارية. | | info(message, data) | تسجيل رسالة معلوماتية. | | success(message, data) | تسجيل رسالة نجاح. | | warn(message, data) | تسجيل رسالة تحذير. | | error(message, data) | تسجيل رسالة خطأ. | | debug(message, data) | تسجيل رسالة تصحيح. | | table(data, columns) | عرض البيانات في شكل جدول مُنظَّم. | | group(name, collapsed) | إنشاء مجموعة قابلة للطي في الوحدة الطرفية. | | time(name) / timeEnd(name) | قياس وتسجيل الوقت المستغرق للعمليات. | | clear() | مسح محتويات الوحدة الطرفية. |

أمثلة على الاستخدام:

OmniHelper.Log.success('تم حفظ البيانات بنجاح! 🎉');
OmniHelper.Log.error('فشل في تحميل البيانات', { retry: true });
OmniHelper.Log.time('معالجة البيانات');
// ... بعض العمليات
OmniHelper.Log.timeEnd('معالجة البيانات'); // يسجل الوقت المنقضي

3. الرسوم المتحركة الدقيقة (Micro Animations) 🎬

تتيح لك هذه الوحدة تطبيق رسوم متحركة سلسة على عناصر DOM باستخدام JavaScript الخالص، دون الحاجة إلى الاعتماد على CSS أو مكتبات رسوم متحركة خارجية.

| الوظيفة | الوصف | | :--- | :--- | | animate(...) | الدالة الرئيسية لتحريك أي خاصية CSS. | | fadeIn(...) | إظهار العنصر تدريجياً. | | fadeOut(...) | إخفاء العنصر تدريجياً. | | slideDown(...) | تحريك ارتفاع العنصر للأسفل. | | slideUp(...) | تحريك ارتفاع العنصر للأعلى. | | slideToggle(...) | تبديل بين slideDown و slideUp. | | bounce(...) | تطبيق تأثير الارتداد. | | shake(...) | تطبيق تأثير الاهتزاز. | | pulse(...) | تطبيق تأثير النبض. | | zoomIn(...) | تكبير العنصر. | | zoomOut(...) | تصغير العنصر. | | rotate(...) | تدوير العنصر. | | translate(...) | تحريك العنصر أفقياً وعمودياً. | | scale(...) | تغيير حجم العنصر. | | stop(element) | إيقاف جميع الرسوم المتحركة على العنصر. |

أمثلة على الاستخدام:

OmniHelper.Anim.fadeIn('.modal', 300, function() {
    console.log('النافذة الآن مرئية.');
});

OmniHelper.Anim.shake('.input-field', 2, 400);

4. إشعارات التنبيه (Notifier) 🔔

توفر هذه الوحدة إشعارات "توست" (Toast Notifications) أنيقة وجذابة تظهر على الصفحة لأحداث مختلفة، دون الحاجة إلى أي تنسيقات CSS إضافية.

| الوظيفة | الوصف | | :--- | :--- | | notify(message, type, duration, position) | عرض إشعار بنوع وموقع محددين. | | info(message, duration) | عرض إشعار معلوماتي. | | success(message, duration) | عرض إشعار نجاح. | | warning(message, duration) | عرض إشعار تحذير. | | error(message, duration) | عرض إشعار خطأ. | | removeAll() | إزالة جميع الإشعارات النشطة. | | setDefaultOptions(options) | تعيين الخيارات الافتراضية للإشعارات. |

أمثلة على الاستخدام:

OmniHelper.Notify.notify('تمت العملية بنجاح! ✅', 'success', 3000, 'top-right');
OmniHelper.Notify.error('فشل الاتصال بالخادم 🛑');

5. الأدوات العامة (Utility Functions) 💡

مجموعة شاملة من الوظائف المساعدة التي تغطي مهام البرمجة الشائعة، بما في ذلك معالجة البيانات، التحقق من الصحة (Validation)، التنسيق، والتعامل مع DOM.

| الفئة | الوظائف البارزة | | :--- | :--- | | التحكم في التدفق | debounce, throttle, sleep, retry, memoize, once, waitFor | | البيانات والكائنات | deepClone, deepMerge, pick, omit, get, set, has, isEmpty, isEqual | | المصفوفات | random, shuffle, unique, chunk, compact, sum, mean, keyBy | | السلاسل النصية | capitalize, camelCase, kebabCase, snakeCase, startCase, truncate, repeat, pad | | التحقق والتنسيق | generateUUID, isValidEmail, isValidURL, isValidPhone, isValidDate, formatDate, formatNumber, formatCurrency, formatPercent | | التشفير والهروب | encodeBase64, decodeBase64, escapeHtml, unescapeHtml | | بيئة التشغيل | detectBrowser, detectOS, detectDevice | | التخزين وDOM | getCookie, setCookie, deleteCookie, getStorage, setStorage, removeStorage, clearStorage, downloadFile, copyToClipboard, getSelectionText, addEventListener, querySelector, closest, parents, siblings, next, prev, createElement, setAttributes, addClass, removeClass, toggleClass, hasClass, getData, setStyle, getDimensions, isVisible, isInViewport, onLoad, onDOMReady |

أمثلة على الاستخدام:

// منع التنفيذ المتكرر (Debounce)
const debouncedSearch = OmniHelper.Utils.debounce(function(query) {
    console.log('البحث عن:', query);
}, 300);

// التحقق من البريد الإلكتروني
OmniHelper.Utils.isValidEmail('[email protected]'); // true

// التنسيق كعملة
OmniHelper.Utils.formatCurrency(1234.56, 'USD', 'en-US'); // '$1,234.56'

الترخيص (License) 📜

هذه المكتبة مفتوحة المصدر (Open Source) ومتاحة للجميع، ويمكنك استخدامها بحرية تامة في أي مشروع، سواء كان تجارياً أو شخصياً. نحن نؤمن بمشاركة المعرفة!

الدعم والتواصل (Support & Contact) 🤝

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

• فيسبوك: https://www.facebook.com/share/1Gf47LvFjv/

نحن هنا لمساعدتك في بناء مشاريعك العظيمة! 🌟