katex4arabic 1.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (43) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +303 -0
  3. package/dist/cdn/katex-arabic.min.cjs +258 -0
  4. package/dist/cdn/katex-arabic.min.css +9 -0
  5. package/dist/cdn/katex-arabic.min.js +258 -0
  6. package/dist/cdn/katex-arabic.min.mjs +11878 -0
  7. package/dist/lib/arabicFunctions.d.ts +87 -0
  8. package/dist/lib/arabicFunctions.d.ts.map +1 -0
  9. package/dist/lib/arabicNumerals.d.ts +50 -0
  10. package/dist/lib/arabicNumerals.d.ts.map +1 -0
  11. package/dist/lib/arabicSymbols.d.ts +52 -0
  12. package/dist/lib/arabicSymbols.d.ts.map +1 -0
  13. package/dist/lib/cdn.d.ts +18 -0
  14. package/dist/lib/cdn.d.ts.map +1 -0
  15. package/dist/lib/hooks.cjs +41 -0
  16. package/dist/lib/hooks.cjs.map +1 -0
  17. package/dist/lib/hooks.d.cts +61 -0
  18. package/dist/lib/hooks.d.ts +61 -0
  19. package/dist/lib/hooks.d.ts.map +1 -0
  20. package/dist/lib/hooks.mjs +41 -0
  21. package/dist/lib/hooks.mjs.map +1 -0
  22. package/dist/lib/index.cjs +71 -0
  23. package/dist/lib/index.cjs.map +1 -0
  24. package/dist/lib/index.d.cts +53 -0
  25. package/dist/lib/index.d.ts +53 -0
  26. package/dist/lib/index.d.ts.map +1 -0
  27. package/dist/lib/index.mjs +72 -0
  28. package/dist/lib/index.mjs.map +1 -0
  29. package/dist/lib/katex-arabic.css +458 -0
  30. package/dist/lib/protectedRegions.d.ts +26 -0
  31. package/dist/lib/protectedRegions.d.ts.map +1 -0
  32. package/dist/lib/render.cjs +811 -0
  33. package/dist/lib/render.cjs.map +1 -0
  34. package/dist/lib/render.d.ts +65 -0
  35. package/dist/lib/render.d.ts.map +1 -0
  36. package/dist/lib/render.mjs +812 -0
  37. package/dist/lib/render.mjs.map +1 -0
  38. package/dist/lib/rtlRenderer.d.ts +100 -0
  39. package/dist/lib/rtlRenderer.d.ts.map +1 -0
  40. package/dist/lib/types.d.ts +98 -0
  41. package/dist/lib/types.d.ts.map +1 -0
  42. package/docs/INSTALL.md +314 -0
  43. package/package.json +119 -0
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Ahmed Almaghz
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,303 @@
1
+ # KaTeX Arabic 🌙
2
+
3
+ مكتبة احترافية لعرض المعادلات الرياضية بالأسلوب العربي، مبنية على
4
+ [KaTeX](https://katex.org). تحوّل المعادلات اللاتينية إلى شكل عربي قراءةً
5
+ ومظهراً: أرقام عربية-هندية، ترجمة أسماء الدوال والمتغيرات، عكس الرموز
6
+ للتوافق مع الاتجاه من اليمين إلى اليسار — مع تكافؤ بصري مع التنسيق
7
+ اللاتيني في **الشكل والحجم والمحاذاة**.
8
+
9
+ هذا المستودع يحتوي على:
10
+
11
+ - **مكتبة** `src/lib/katex-arabic` — قلب المعالجة العربية (مستقل عن الواجهة).
12
+ - **تطبيق عرض تجريبي** — معرض معادلات، محرر مباشر، مقارنة لاتيني/عربي، وتوثيق.
13
+
14
+ ---
15
+
16
+ ## ✨ المزايا
17
+
18
+ | الميزة | الوصف |
19
+ | --- | --- |
20
+ | 🔢 أرقام عربية | تحويل تلقائي إلى عربية-هندية `٠١٢…٩` أو فارسية `۰۱۲…۹` |
21
+ | 📐 ترجمة الدوال | `sin → جا`، `cos → جتا`، `lim → نها`، `log → لغ` … |
22
+ | 🔤 ترجمة المتغيرات | `x → س`، `y → ص`، `dx → د س`، `e → هـ` … |
23
+ | 🔄 عكس الرموز | تكامل ومجموع وجذر وأقواس ورموز مقارنة معكوسة بصرياً |
24
+ | 🌙 وضع RTL كامل | المعادلة بأكملها تُقرأ من اليمين لليسار |
25
+ | 📏 تكافؤ لاتيني | أحجام وخطوط أساس ومحاذاة مطابقة لتنسيق KaTeX اللاتيني |
26
+ | 🎨 تخصيص بصري | متغيرات CSS + خيار `operatorScale` للتحكم الدقيق |
27
+ | 🛡️ إخفاء آمن | عدم المساس بنصوص `\text{}` وحماية من إعادة المعالجة |
28
+ | ♿ إمكانية وصول | `aria-label`، لوحة مفاتيح، ودعم وضع الطباعة |
29
+
30
+ ---
31
+
32
+ ## 🚀 التشغيل السريع
33
+
34
+ ```bash
35
+ npm install # تثبيت الاعتماديات
36
+ npm run dev # تشغيل بيئة التطوير
37
+ npm run build # بناء تطبيق العرض (ملفات JS/CSS منفصلة)
38
+ npm run build:all # بناء المكتبة القابلة للنشر (JS + أنواع + CSS)
39
+ npm run preview # معاينة البناء
40
+ npm run typecheck # فحص الأنواع (TypeScript)
41
+ npm test # تشغيل الاختبارات (Vitest)
42
+ npm run check # فحص شامل: typecheck + tests + build
43
+ ```
44
+
45
+ > متطلب: Node.js ≥ 18
46
+
47
+ ---
48
+
49
+ ## 📦 التثبيت كحزمة npm
50
+
51
+ > 📖 **دليل التنصيب والاستخدام الكامل**: [docs/INSTALL.md](docs/INSTALL.md)
52
+
53
+ ```bash
54
+ npm install katex-arabic
55
+ ```
56
+
57
+ الحزمة تتطلب `katex` كاعتماد نظير (peer dependency)، و`react` اختيارياً
58
+ لاستخدام الخطاطيف والمكوّنات:
59
+
60
+ ```bash
61
+ npm install katex
62
+ ```
63
+
64
+ ### الاستيراد
65
+
66
+ ```ts
67
+ // الدوال الأساسية
68
+ import { renderArabicToString, renderArabic, processLatex } from 'katex-arabic';
69
+
70
+ // خطاطيف React (اختياري)
71
+ import { useArabicKatex, useArabicKatexResult } from 'katex-arabic/hooks';
72
+
73
+ // ملف الأنماط — يجب استيراده مرة واحدة في تطبيقك
74
+ import 'katex-arabic/katex-arabic.css';
75
+ ```
76
+
77
+ ---
78
+
79
+ ## 🚀 الاستخدام عبر CDN (ملفان فقط — صفر إعداد)
80
+
81
+ تُنشر الحزمة أيضاً كملفين جاهزين للتحميل المباشر — **KaTeX مدمج داخل ملف JS واحد** وغير مطلوب تحميله منفصلاً:
82
+
83
+ **الرابط من مستودع GitHub** (يعمل مباشرة، قبل النشر على npm):
84
+
85
+ ```html
86
+ <!DOCTYPE html>
87
+ <html lang="ar" dir="rtl">
88
+ <head>
89
+ <meta charset="UTF-8">
90
+ <script defer src="https://cdn.jsdelivr.net/gh/AhmedAlmaghz/katex4arabic@main/dist/cdn/katex-arabic.min.js"></script>
91
+ <link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/AhmedAlmaghz/katex4arabic@main/dist/cdn/katex-arabic.min.css">
92
+ </head>
93
+ <body>
94
+ <div id="eq">x^2 + y^2 = z^2</div>
95
+ <script>
96
+ window.addEventListener('DOMContentLoaded', () => {
97
+ KaTeXArabic.render(document.getElementById('eq').textContent.trim(),
98
+ document.getElementById('eq'));
99
+ });
100
+ </script>
101
+ </body>
102
+ </html>
103
+ ```
104
+
105
+ > بعد النشر على npm يعمل الرابط الأقصر أيضاً:
106
+ > `https://cdn.jsdelivr.net/npm/katex-arabic/dist/cdn/katex-arabic.min.js` —
107
+ > مع ملف CSS بنفس المسار، ويعمل `https://cdn.jsdelivr.net/npm/katex-arabic` على نقطة دخول jsDelivr مباشرة.
108
+
109
+ المتغير العمومي `window.KaTeXArabic` بنفس واجهة `katex`:
110
+
111
+ ```js
112
+ const html = KaTeXArabic.renderToString('\\sin^2 x + \\cos^2 x = 1'); // ← افتراضياً: أرقام عربية + جا/جتا + RTL
113
+ KaTeXArabic.render('\\int_0^1 x^2 dx', element); // (latex, element, options?)
114
+ KaTeXArabic.toArabicNumerals('123'); // '١٢٣'
115
+ KaTeXArabic.VERSION; // '1.1.1'
116
+ ```
117
+
118
+ > الدليل التفصيلي: [docs/INSTALL.md](docs/INSTALL.md)
119
+
120
+ ---
121
+
122
+ ## 📁 بنية المشروع
123
+
124
+ ```
125
+ ├── index.html # نقطة الدخول + تحميل الخطوط العربية
126
+ ├── vite.config.ts # إعدادات Vite لتطبيق العرض (React + Tailwind)
127
+ ├── vite.lib.config.ts # إعدادات بناء المكتبة (ESM + CJS)
128
+ ├── tsconfig.lib.json # إعدادات إصدار أنواع TypeScript للمكتبة
129
+ ├── src/
130
+ │ ├── App.tsx # جذر التطبيق وأقسامه
131
+ │ ├── main.tsx # نقطة الإقلاع
132
+ │ ├── index.css # الأنماط العامة (Tailwind + المكوّنات)
133
+ │ ├── katex-arabic.css # نسق عرض المعادلات (يُنسخ إلى dist/lib)
134
+ │ ├── components/ # مكوّنات الواجهة
135
+ │ │ ├── MathEquation.tsx # <MathEquation> / <MathBlock> / <MathInline>
136
+ │ │ ├── OptionsPanel.tsx # لوحة إعدادات العرض
137
+ │ │ ├── LiveEditor.tsx # محرر مباشر مع تحقق فوري
138
+ │ │ ├── ComparisonDemo.tsx # مقارنة لاتيني/عربي
139
+ │ │ └── …
140
+ │ ├── data/examples.ts # معادلات المعرض
141
+ │ └── lib/katex-arabic/ # ★ المكتبة الأساسية
142
+ │ ├── index.ts # الواجهة العامة (public API)
143
+ │ ├── render.ts # دوال العرض (renderToString, render, batch)
144
+ │ ├── rtlRenderer.ts # خط أنابيب المعالجة + القيم الافتراضية
145
+ │ ├── arabicNumerals.ts # تحويل الأرقام وتنسيق الفواصل
146
+ │ ├── arabicFunctions.ts # ترجمة الدوال والمتغيرات والتفاضلات
147
+ │ ├── arabicSymbols.ts # عكس الرموز (مقارنة/أسهم/أقواس)
148
+ │ ├── protectedRegions.ts # حماية نصوص \text{} من المعالجة
149
+ │ ├── hooks.ts # خطاطيف React جاهزة للعرض
150
+ │ ├── types.ts # أنواع TypeScript
151
+ │ └── __tests__/ # اختبارات الوحدات والخط الأنبوبي
152
+ └── package.json
153
+ ```
154
+
155
+ ---
156
+
157
+ ## 💻 استخدام المكتبة
158
+ ### Vanilla JS
159
+
160
+ ```ts
161
+ import { renderArabicToString } from 'katex-arabic';
162
+ import 'katex-arabic/katex-arabic.css';
163
+
164
+ const html = renderArabicToString('\\sin^2(x) + \\cos^2(x) = 1', {
165
+ numerals: 'arabic',
166
+ translateFuncs: true,
167
+ mirrorSymbols: true,
168
+ });
169
+ document.getElementById('eq')!.innerHTML = html;
170
+ ```
171
+
172
+ ### معالجة LaTeX فقط (بدون عرض)
173
+
174
+ ```ts
175
+ import { processLatex, validateLatex } from 'katex-arabic';
176
+
177
+ const processed = processLatex('\\sin(x) + dx');
178
+ // → "\\operatorname{جا}(\\text{س}) + \\text{د}\\text{س}"
179
+
180
+ if (validateLatex('\\frac{1}{2} + x') === null) {
181
+ // الطرح سليم
182
+ }
183
+ ```
184
+
185
+ ### العرض الدفعي (Batch)
186
+
187
+ لعرض قائمة معادلات دفعة واحدة بكفاءة أعلى (خيارات تُحلّل مرة واحدة
188
+ وذاكرة التخزين المؤقت مشتركة):
189
+
190
+ ```ts
191
+ import { renderArabicBatch } from 'katex-arabic';
192
+
193
+ const results = renderArabicBatch(
194
+ ['x = 1', { latex: 'y = 2', options: { numerals: 'latin' } }],
195
+ { numerals: 'arabic' },
196
+ );
197
+ // results[i] = { html, error }
198
+ ```
199
+
200
+ ### التخزين المؤقت والأداء
201
+
202
+ تُخزَّن نتائج العرض داخلياً في ذاكرة LRU (٢٥٦ مدخلاً) بحيث يكون
203
+ إعادة عرض نفس المعادلة بنفس الخيارات شبه مجاني. لمسح الذاكرة
204
+ (مثلاً عند تغيّر الخيارات جذرياً أو في الاختبارات):
205
+
206
+ ```ts
207
+ import { clearRenderCache } from 'katex-arabic';
208
+ clearRenderCache();
209
+ ```
210
+
211
+ > **حماية المدخلات:** أي مدخل أطول من `MAX_INPUT_LENGTH` (٢٠٬٠٠٠ حرف)
212
+ > يُقتَصّ تلقائياً لحماية خط الأنابيب من التكلفة الأسوأ، والمدخلات
213
+ > الفارغة تُعاد كما هي دون معالجة.
214
+
215
+ ### React
216
+
217
+ ```tsx
218
+ import { MathBlock, MathInline } from './components/MathEquation';
219
+
220
+ <MathBlock
221
+ latex="\\int_{0}^{\\infty} e^{-x^2} dx = \\frac{\\sqrt{\\pi}}{2}"
222
+ options={{ numerals: 'arabic', translateFuncs: true }}
223
+ />
224
+
225
+ <p>التعريف هو <MathInline latex="f(x) = x^2" /></p>
226
+ ```
227
+
228
+ ### خطاطيف React
229
+
230
+ ```tsx
231
+ import { useArabicKatex, useArabicKatexResult } from 'katex-arabic/hooks';
232
+
233
+ const html = useArabicKatex('x^2 + y^2', { numerals: 'arabic' });
234
+ const { ok, error } = useArabicKatexResult(latex, options);
235
+ ```
236
+
237
+ ---
238
+
239
+ ## ⚙️ خيارات التهيئة
240
+
241
+ | الخيار | النوع | الافتراضي | الوصف |
242
+ | --- | --- | --- | --- |
243
+ | `numerals` | `arabic \| extended \| latin` | `arabic` | نظام الأرقام المعروض |
244
+ | `formatNumbers` | `boolean` | `true` | فواصل عربية `٬ ٫` في الأعداد |
245
+ | `translateFuncs` | `boolean` | `true` | ترجمة أسماء الدوال |
246
+ | `translateVars` | `boolean` | `true` | ترجمة المتغيرات اللاتينية |
247
+ | `translateDiffs` | `boolean` | `true` | ترجمة التفاضلات `dx → د س` |
248
+ | `mirrorSymbols` | `boolean` | `true` | عكس رموز المقارنة والأسهم |
249
+ | `mirrorBigOperators` | `boolean` | `true` | عكس `∫ Σ ∏` بصرياً |
250
+ | `mirrorSqrt` | `boolean` | `true` | عكس رمز الجذر `√` |
251
+ | `mirrorBrackets` | `boolean` | `true` | عكس الأقواس الزاوية والكبيرة |
252
+ | `direction` | `rtl \| ltr` | `rtl` | اتجاه المعادلة |
253
+ | `fullArabicMode` | `boolean` | `true` | قراءة RTL للمعادلة كاملة |
254
+ | `operatorScale` | `number` | `1.05` | حجم العوامل العربية (0.9–1.25) |
255
+ | `fontFamily` | `string` | `Amiri` | خط النصوص العربية |
256
+ | `displayMode` | `boolean` | `false` | وضع العرض (block) مقابل السطري |
257
+ | `throwOnError` | `boolean` | `false` | إلقاء خطأ بدل العرض الودّي |
258
+ | `customFunctionMap` | `Record` | `{}` | تجاوز ترجمات الدوال |
259
+ | `customVariableMap` | `Record` | `{}` | تجاوز ترجمات المتغيرات |
260
+ | `macros` | `Record` | `{}` | ماكرو KaTeX إضافية |
261
+ | `minRuleThickness` | `number` | `0.04` | سماكة خطوط الكسور |
262
+
263
+ ---
264
+
265
+ ## 🎨 التوافق البصري مع اللاتينية
266
+
267
+ تقوم `katex-arabic.css` بتطبيع مقاييس النصوص العربية لتطابق مخرجات KaTeX
268
+ اللاتينية: خط أساس موحّد، ارتفاع سطر مضبوط، ومنع قصّ النتوءات والحركات.
269
+ لمزيد من الدقة، تتحكم هذه المتغيرات بالتخصيص:
270
+
271
+ | المتغير | الوظيفة | الافتراضي |
272
+ | --- | --- | --- |
273
+ | `--ka-op-scale` | حجم العوامل والنصوص العربية داخل المعادلة | `1.05` |
274
+ | `--ka-font-family` | عائلة خط النصوص العربية | `Amiri` |
275
+ | `--ka-color` | لون المعادلة | `inherit` |
276
+ | `--ka-line-height` | ارتفاع السطر المحيط | `1.6` |
277
+
278
+ ```css
279
+ .math-equation { --ka-op-scale: 1.08; }
280
+ ```
281
+
282
+ قيمة `1.08`–`1.1` تعوّض عادةً الفرق البصري في حجم الحروف بين الخطوط
283
+ العربية و`KaTeX_Main`. تُوسَّط الأسس والأدلة والكسور والجذور والمصفوفات
284
+ على المحور الرياضي، تماماً كما في المعادلة اللاتينية.
285
+
286
+ ---
287
+
288
+ ## 🧪 الاختبارات
289
+
290
+ ```bash
291
+ npm test # تشغيل كامل
292
+ npm run test:watch
293
+ ```
294
+
295
+ تغطي الاختبارات: تحويل الأرقام ذهاباً وإياباً، ترجمة الدوال والمتغيرات
296
+ مع حماية `\text{}`، عكس الرموز، وسلامة خط الأنابيب الكامل مع كل الخيارات.
297
+
298
+ ---
299
+
300
+ ## 📜 الترخيص
301
+
302
+ مفتوح المصدر، مبنية على [KaTeX](https://katex.org) (MIT).
303
+ بواسطة [ِAhmed Almaghz](https://github.com/AhmedAlmaghz/KaTeX4Arabic) - 2026