docs: إضافة أمثلة إستخدام للدوال

src/line/func/create.js

@@ -7,6 +7,22 @@
  * إنشاء كائن مستقيم بناءً على الخيارات المقدمة
  * @param {LineOptions} options @defaultValue { dis: 1, end: 1, spacing: 1, count: 2, neg: false }
  * @returns {Line}
+ * @throws إذا كانت الخيارات غير صالحة
+ * @example
+ * const line = Line.create.one({ end: -10 })
+ * // line = { neg: true, count: 2, dis: 10, spacing: 10, end: -10, min: -10, max: 0, points: [0, -10] }
+ * @example
+ * const line = Line.create.one({ end: -10, count: 3 })
+ * // line = { neg: true, count: 3, dis: 10, spacing: 5, end: -10, min: -10, max: 0, points: [0, -5, -10] }
+ * @example
+ * const line = Line.create.one({ dis: 10, neg: true })
+ * // line = { neg: true, count: 2, dis: 10, spacing: 10, end: -10, min: -10, max: 0, points: [0, -10] }
+ * @example
+ * const line = Line.create.one({ dis: 10, count: 3, neg: true })
+ * // line = { neg: true, count: 3, dis: 10, spacing: 5, end: -10, min: -10, max: 0, points: [0, -5, -10] }
+ * @example
+ * const line = Line.create.one({ spacing: 5, count: 3, neg: true })
+ * // line = { neg: true, count: 3, dis: 10, spacing: 5, end: -10, min: -10, max: 0, points: [0, -5, -10] }
  */
 export function one({ dis = 1, end = 1, spacing = 1, count = 2, neg = false }) {
   // التحقق من القيم المقدمة
@@ -71,6 +87,12 @@ export function one({ dis = 1, end = 1, spacing = 1, count = 2, neg = false }) {
  * حساب مواضع جميع النقاط على الخط، مع ضبط اختياري للفواصل
  * @param {PointsOptions} options عدد النقاط @defaultValue { spacing: 1, count: 2, sort: zero }
  * @returns {Point[]} مصفوفة من المواضع لكل نقطة على المستقيم
+ * @throws إذا كان الخيار المقدم للترتيب غير صالح
+ * @example
+ * const points = Line.create.points({ count: 5, spacing: 2, sort: 'zero'})
+ * // points = [0, 2, -2, 4, -4] ('zero' sort)
+ * // points = [-4, -2, 0, 2, 4] ('neg' sort)
+ * // points = [4, 2, 0, -2, -4] ('pos' sort)
  */
 export function points({ count = 2, spacing = 1, sort = 'zero' }) {
   // تهيئة مصفوفة لتخزين المواضع المحسوبة لكل نقطة

src/line/func/point.js

@@ -6,6 +6,14 @@
  * @param {Line} line - المستقيم المراد التحقق عليه
  * @param {Point} point - النقطة المراد التحقق منها
  * @returns {boolean} - يعيد صحيح إذا كانت النقطة داخل المستقيم، خلاف ذلك يعيد خطأ
+ * @example
+ * const line = Line.create.one({ end: 10 })
+ * const pointInLine = inside(line, 5)
+ * // pointInLine = true
+ * @example
+ * const line = Line.create.one({ end: 10 })
+ * const pointInLine = inside(line, 15)
+ * // pointInLine = false
  */
 export function inside({ min, max }, point) {
   // أعد صحيح إذا كانت النقطة داخل النطاق
@@ -17,8 +25,24 @@ export function inside({ min, max }, point) {
  * @param {Line} line - المستقيم المراد التحرك عليه
  * @param {Point} current - الموضع الحالي
  * @param {Point} step - مقدار الخطوة الواحدة للتحرك بها
- * @param {boolean} [inverse=false] - عكس إتجاه الحركة على المستقيم. @default false
- * @returns {Point} - يعيد الموضع الجديد بعد التحرك
+ * @param {boolean} [inverse=false] - عكس إتجاه الحركة على المستقيم. @defaultValue false
+ * @returns {Point} يعيد الموضع الجديد بعد التحرك
+ * @example <caption>تحريك النقطة للأمام على مستقيم موجب</caption>
+ * const line = Line.create.one({ end: 10 })
+ * const newCurrent = move(line, 3, 2)
+ * // newCurrent = 5
+ * @example <caption>تحريك النقطة للخلف على مستقيم موجب</caption>
+ * const line = Line.create.one({ end: 10 })
+ * const newCurrent = move(line, 3, 2, true)
+ * // newCurrent = 1
+ * @example <caption>تحريك النقطة للأمام على مستقيم سالب</caption>
+ * const line = Line.create.one({ end: -10 })
+ * const newCurrent = move(line, -3, 2)
+ * // newCurrent = -1
+ * @example <caption>تحريك النقطة للخلف على مستقيم سالب</caption>
+ * const line = Line.create.one({ end: -10 })
+ * const newCurrent = move(line, -3, 2, true)
+ * // newCurrent = -5
  */
 export function move({ min, max, neg }, current, step, inverse = false) {
   // إذا كانت الخطوة تساوي صفرًا، أعد الموضع الحالي دون تغييره

src/line/func/time.js

@@ -2,32 +2,48 @@
 /** @typedef {import("../imports.js").Point} Point */
 
 /**
- * تحويل قيمة نقطة إلى نسبة مئوية على مستقيم
+ * تحويل قيمة نقطة إلى نسبة أحادية على مستقيم
  * @param {Line} line
  * @param {Point} point
  * @returns {Point}
+ * @example
+ * const line = Line.create.one({ end: 10 })
+ * const t = Line.time.to(line, 5)
+ * // t = 0.5
+ * @example
+ * const line = Line.create.one({ end: -10 })
+ * const t = Line.time.to(line, -5)
+ * // t = 0.5
  */
 export function to({ dis, neg, end }, point) {
   // إذا كانت النقطة عند البداية، إرجاع 0 إذا لم يكن سالباً، وإرجاع 1 إذا كان سالباً
   if (point === 0) return neg ? 1 : 0
   // إذا كانت النقطة عند النهاية، إرجاع 1 إذا لم يكن سالباً، وإرجاع 0 إذا كان سالباً
   if (point === end) return neg ? 0 : 1
-  // حساب النسبة المئوية للنقطة على المستقيم
-  return (point / dis) * (neg ? -1 : 1)
+  // حساب النسبة الأحادية للنقطة على المستقيم
+  return neg ? -(point / dis) : point / dis
 }
 
 /**
  * تقييد قيمة النقطة بين 0 و 1
  * @param {Line} line
  * @param {Point} point
  * @returns {Point}
+ * @example
+ * const line = Line.create.one({ end: 10 })
+ * const t = Line.time.to(line, 15)
+ * // t = 1
+ * @example
+ * const line = Line.create.one({ end: 10 })
+ * const t = Line.time.to.clamp(line, -5)
+ * // t = 0
  */
 to.clamp = function (line, point) {
   // إذا كانت النقطة أكبر من الحد الأقصى، إرجاع 1
   if (point >= line.max) return 1
   // إذا كانت النقطة أقل من الحد الأدنى، إرجاع 0
   if (point <= line.min) return 0
-  // حساب النسبة المئوية المقيدة للنقطة على المستقيم
+  // حساب النسبة الأحادية المقيدة للنقطة على المستقيم
   return to(line, point)
 }
 
@@ -36,11 +52,15 @@ to.clamp = function (line, point) {
  * @param {Line} line
  * @param {Point} point
  * @returns {Point}
+ * @example
+ * const line = Line.create.one({ end: 10 })
+ * const t = Line.time.to.clamp.min(line, -5)
+ * // t = 0
  */
 to.clamp.min = function (line, point) {
   // إذا كانت النقطة أقل من الحد الأدنى، إرجاع 0
   if (point <= line.min) return 0
-  // حساب النسبة المئوية المقيدة للنقطة على المستقيم
+  // حساب النسبة الأحادية المقيدة للنقطة على المستقيم
   return to(line, point)
 }
 
@@ -49,19 +69,31 @@ to.clamp.min = function (line, point) {
  * @param {Line} line
  * @param {Point} point
  * @returns {Point}
+ * @example
+ * const line = Line.create.one({ end: 10 })
+ * const t = Line.time.to.clamp.max(line, 15)
+ * // t = 1
  */
 to.clamp.max = function (line, point) {
   // إذا كانت النقطة أكبر من الحد الأقصى، إرجاع 1
   if (point >= line.max) return 1
-  // حساب النسبة المئوية المقيدة للنقطة على المستقيم
+  // حساب النسبة الأحادية المقيدة للنقطة على المستقيم
   return to(line, point)
 }
 
 /**
- * تحويل نسبة مئوية إلى نقطة على المستقيم
+ * تحويل نسبة أحادية إلى نقطة على المستقيم
  * @param {Line} line
  * @param {Point} t بين 0 و 1، شامل ال1
  * @returns {Point}
+ * @example
+ * const line = Line.create.one({ end: 10 })
+ * const t = Line.time.from(line, 0.5)
+ * // t = 5
+ * @example
+ * const line = Line.create.one({ end: -10 })
+ * const t = Line.time.from(line, 0.5)
+ * // t = -5
  */
 export function from(line, t) {
   // إذا كانت النسبة 1، إرجاع الحد الأقصى
@@ -70,56 +102,77 @@ export function from(line, t) {
   if (t === 0) return from.min(line)
 
   const { dis, neg } = line
+
   // حساب النقطة بناءً على النسبة المئوية
   if (neg) return -(dis - dis * t)
   else return dis * t
 }
 
 /**
- * تقييد النسبة المئوية بين 0 و 1
+ * تقييد النسبة الأحادية بين 0 و 1
  * @param {Line} line
  * @param {Point} t بين 0 و 1، شامل ال1
  * @returns {Point}
+ * @example
+ * const line = Line.create.one({ end: 10 })
+ * const t = Line.time.from.clamp(line, 1.5)
+ * // t = 10
+ * @example
+ * const line = Line.create.one({ end: 10 })
+ * const t = Line.time.from.clamp(line, -0.5)
+ * // t = 0
  */
 from.clamp = function (line, t) {
   // إذا كانت النسبة أكبر من أو تساوي 1، إرجاع الحد الأقصى
   if (t >= 1) return from.max(line)
   // إذا كانت النسبة أقل من أو تساوي 0، إرجاع الحد الأدنى
   if (t <= 0) return from.min(line)
-  // حساب النقطة بناءً على النسبة المئوية المقيدة
+  // حساب النقطة بناءً على النسبة الأحادية المقيدة
   return from(line, t)
 }
 
 /**
- * تقييد النسبة المئوية لتكون أقل من أو تساوي 1
+ * تقييد النسبة الأحادية لتكون أقل من أو تساوي 1
  * @param {Line} line
  * @param {Point} t بين 0 و 1، شامل ال1
  * @returns {Point}
+ * @example
+ * const line = Line.create.one({ end: 10 })
+ * const t = Line.time.from.clamp.max(line, 1.5)
+ * // t = 10
  */
 from.clamp.max = function (line, t) {
   // إذا كانت النسبة أكبر من أو تساوي 1، إرجاع الحد الأقصى
   if (t >= 1) return from.max(line)
-  // حساب النقطة بناءً على النسبة المئوية
+  // حساب النقطة بناءً على النسبة الأحادية
   return from(line, t)
 }
 
 /**
- * تقييد النسبة المئوية لتكون أكبر من أو تساوي 0
+ * تقييد النسبة الأحادية لتكون أكبر من أو تساوي 0
  * @param {Line} line
  * @param {Point} t بين 0 و 1، شامل ال1
  * @returns {Point}
+ * @example
+ * const line = Line.create.one({ end: 10 })
+ * const t = Line.time.from.clamp.min(line, -0.5)
+ * // t = 0
  */
 from.clamp.min = function (line, t) {
   // إذا كانت النسبة أقل من أو تساوي 0، إرجاع الحد الأدنى
   if (t <= 0) return from.min(line)
-  // حساب النقطة بناءً على النسبة المئوية
+  // حساب النقطة بناءً على النسبة الأحادية
   return from(line, t)
 }
 
 /**
  * إرجاع النقطة عند منتصف المستقيم
  * @param {Line} line
  * @returns {Point}
+ * @example
+ * const line = Line.create.one({ end: 10 })
+ * const t = Line.time.from.center(line)
+ * // t = 5
  */
 from.center = function (line) {
   return from(line, 0.5)
@@ -129,6 +182,10 @@ from.center = function (line) {
  * إرجاع الحد الأدنى للنقطة على المستقيم
  * @param {Line} line
  * @returns {Point}
+ * @example
+ * const line = Line.create.one({ end: 10 })
+ * const t = Line.time.from.min(line)
+ * // t = 0
  */
 from.min = function ({ dis, neg }) {
   // note: أسرع من استدعاء `from(line, 0)`
@@ -139,6 +196,10 @@ from.min = function ({ dis, neg }) {
  * إرجاع الحد الأقصى للنقطة على المستقيم
  * @param {Line} line
  * @returns {Point}
+ * @example
+ * const line = Line.create.one({ end: 10 })
+ * const t = Line.time.from.max(line)
+ * // t = 10
  */
 from.max = function ({ dis, neg }) {
   // note: أسرع من استدعاء `from(line, 1)`