مرجع API

كل تصدير في @kkwaenggwari/animated-chorus مع props وأنواعه وقيمه الافتراضية. والأسماء نفسها تعمل على الويب وفي React Native.

تصفية17 API

الأرقام والنصوص

MotionNumber

رقم تتدحرج خاناته كالعجلات.

Prop	النوع	الافتراضي	الوصف
`value`	`number \| bigint \| string`	`—`إلزامي	الرقم، أو نص رقمي نسّقته أنت.
`mode`	`'replace' \| 'roll'`	`'replace'`	ينقل `replace` كل خانة متغيّرة خطوة واحدة؛ ويمر `roll` عبر الأرقام بينها.
`direction`	`'auto' \| 'digit' \| 'up' \| 'down'`	`'auto'`	يتبع `auto` تغيّر المقدار فتتدحرج الخانات المحمولة في اتجاه واحد؛ ويقارن `digit` كل خانة بمفردها.
`stagger`	`number`	`45`	مللي ثوانٍ بين الخانات المتغيّرة، من الآحاد إلى الخارج. والموجة كلها محدودة المدة.
`format`	`(value) => string \| Intl.NumberFormatOptions`		دالة تعيد النص المراد عرضه، أو خيارات `Intl.NumberFormat` (مع `intl`).
`intl`	`boolean`	`false`	استخدم `Intl.NumberFormat` المدمج. معطّل افتراضيًا كي لا تحتاج أي بيئة تشغيل إلى `Intl`.
`locale`	`string \| string[]`		اللغة المحلية لـ `intl`.
`prefix`	`string`		نص قبل الرقم.
`suffix`	`string`		نص بعد الرقم.
`transition`	`Transition`	`spring`	منحنى توقيت `{ duration, easing }` أو نابض `{ tempo: 'spring', spring }`. تحتفظ النوابض بزخمها عند المقاطعة.
`onMotionComplete`	`(value) => void`		يعمل مع القيمة بعد استقرار الخانات.

صفحة المكوّن ومنصة التجربة

MotionText

نص يتحرك حين يتغيّر: النص الرقمي يتدحرج خانةً خانة، والنص الآخر يتبدّل.

Prop	النوع	الافتراضي	الوصف
`children`	`ReactNode`		النص المراد عرضه.
`as`	`element`	`'span'`	العنصر المراد عرضه.
`transition`	`Transition`	`spring`	منحنى توقيت `{ duration, easing }` أو نابض `{ tempo: 'spring', spring }`. تحتفظ النوابض بزخمها عند المقاطعة.
`onMotionComplete`	`(text) => void`		يعمل حين تستقر الحركة.

صفحة المكوّن ومنصة التجربة

MotionStream

نص متدفق يُكشف بإيقاع ثابت يلحق بالدفعات.

Prop	النوع	الافتراضي	الوصف
`text`	`string`	`—`إلزامي	النص حتى الآن. يُكشف النص المتنامي بإيقاع ثابت؛ وإعادة الكتابة تكمل من البداية المشتركة.
`speed`	`number`	`90`	معدّل الكشف الأساسي بالأحرف في الثانية.
`catchUp`	`number`	`900`	يُكشف النص المتراكم خلال نحو هذا العدد من المللي ثواني بالتسريع.
`initial`	`boolean`	`false`	اكشف أيضًا النص الموجود عند التركيب (وإلا يظهر دفعة واحدة).
`effect`	`'fade' \| 'none'`	`'fade'`	يُظهر `fade` الأحرف الجديدة بالتدريج؛ ويعرضها `none` مباشرة.
`children`	`(visible: string) => ReactNode`		دالة تتلقى النص بالإيقاع المضبوط، مثلًا لعرض Markdown.
`as`	`element`	`'span'`	العنصر المراد عرضه.
`onMotionComplete`	`(text) => void`		يعمل كلما لحق الكشف بـ `text`.

صفحة المكوّن ومنصة التجربة

المحتوى والحجم

MotionSwap

محتوى يتبدّل بتلاشٍ متقاطع بينما يتغيّر حجم العنصر.

Prop	النوع	الافتراضي	الوصف
`value`	`unknown`		هوية المحتوى؛ والقيمة الجديدة تبدّله. الأبناء النصية هي هويتها.
`children`	`ReactNode`		المحتوى.
`as`	`element`	`'span'`	العنصر المراد عرضه.
`inline`	`boolean`	`as === 'span'`	يتحجّم `true` حسب المحتوى (تسميات، أيقونات)؛ ويملأ `false` عرض الأب ويحرّك الارتفاع.
`align`	`'start' \| 'center' \| 'end'`	`'center'`	أين يقع المحتوى أثناء تغيّر الحجم.
`effect`	`'fade' \| 'up' \| 'down' \| 'scale'`	`'fade'`	كيف يدخل المحتوى ويخرج: `up` يصعد، و`down` يهبط، و`scale` يكبر.
`transition`	`Transition`	`spring`	منحنى توقيت `{ duration, easing }` أو نابض `{ tempo: 'spring', spring }`. تحتفظ النوابض بزخمها عند المقاطعة.
`onMotionComplete`	`(value) => void`		يعمل حين تستقر الحركة.

صفحة المكوّن ومنصة التجربة

MotionHeight

يحرّك الارتفاع حسب المحتوى: الطي والفتح وتغيّرات المحتوى.

Prop	النوع	الافتراضي	الوصف
`open`	`boolean`	`true`	يطوي `false` إلى ارتفاع صفري؛ ويبقى المحتوى مركّبًا لكنه مخفي وخامل.
`children`	`ReactNode`		المحتوى.
`as`	`element`	`'div'`	العنصر المراد عرضه.
`transition`	`Transition`	`spring`	منحنى توقيت `{ duration, easing }` أو نابض `{ tempo: 'spring', spring }`. تحتفظ النوابض بزخمها عند المقاطعة.
`onMotionComplete`	`(open) => void`		يعمل مع `open` بعد استقرار الارتفاع.

صفحة المكوّن ومنصة التجربة

MotionPresence

يُبقي المحتوى مركّبًا أثناء دخوله وخروجه بحركة.

Prop	النوع	الافتراضي	الوصف
`present`	`boolean`	`—`إلزامي	أظهر المحتوى أو أخفه. غيّر هذا بدل الإزالة.
`enter`	`Pose`	`{ opacity: 1, translateY: 0 }`	الوضعية في السكون.
`exit`	`Pose`	`{ opacity: 0, translateY: -12 }`	الوضعية التي يغادر بها المحتوى ويدخل منها.
`as`	`element`	`'div'`	العنصر المراد عرضه.
`transition`	`Transition`	`spring`	منحنى توقيت `{ duration, easing }` أو نابض `{ tempo: 'spring', spring }`. تحتفظ النوابض بزخمها عند المقاطعة.
`onExitComplete`	`() => void`		يعمل بعد أن يغادر المحتوى ويُزال.

صفحة المكوّن ومنصة التجربة

الاختيار والصفحات

MotionHighlight

عناصر من البيانات مع تمييز واحد ينتقل إلى العنصر المختار.

Prop	النوع	الافتراضي	الوصف
`items`	`readonly T[]`	`—`إلزامي	مصفوفة بياناتك.
`value`	`key \| null`	`—`إلزامي	مفتاح العنصر المميَّز؛ و`null` يخفي التمييز.
`onValueChange`	`(key, item) => void`		يعمل مع المفتاح والعنصر حين يُضغط عنصر.
`getKey`	`(item) => string \| number`	`item.id`	تعيد مفتاحًا فريدًا ثابتًا لعنصر. افتراضيًا `item.id`، أو العنصر نفسه للنصوص والأرقام.
`renderItem`	`(item, { selected, index }) => ReactNode`	`item.label`	يرسم عنصرًا؛ ويتلقى ما إذا كان مختارًا.
`hover`	`boolean`	`false`	اتبع المؤشر فوق العناصر وعُد إلى `value` عند المغادرة (الويب).
`itemAs`	`element`	`'button'`	العنصر لكل بند.
`itemClassName`	`string`		صنف لعنصر كل بند؛ ويضبط `itemStyle` نمطه المضمّن.
`highlightClassName`	`string`		صنف التمييز؛ ويضبط `highlightStyle` نمطه المضمّن.
`transition`	`Transition`	`spring`	منحنى توقيت `{ duration, easing }` أو نابض `{ tempo: 'spring', spring }`. تحتفظ النوابض بزخمها عند المقاطعة.

صفحة المكوّن ومنصة التجربة

MotionPager

صفحات قابلة للسحب من البيانات.

Prop	النوع	الافتراضي	الوصف
`items`	`readonly T[]`	`—`إلزامي	مصفوفة بياناتك.
`index`	`number`		الصفحة المعروضة. اتركها ليحتفظ مقلّب الصفحات بصفحته.
`defaultIndex`	`number`	`0`	الصفحة الأولى حين لا يكون `index` متحكَّمًا به.
`onIndexChange`	`(index, item) => void`		يعمل مع الفهرس والعنصر بمجرد أن تستقر سحبة أو مفتاح أو إيماءة عجلة.
`getKey`	`(item) => string \| number`	`item.id`	تعيد مفتاحًا فريدًا ثابتًا لعنصر. افتراضيًا `item.id`، أو العنصر نفسه للنصوص والأرقام.
`renderItem`	`(item, { index, active }) => ReactNode`	`item.label`	يرسم صفحة؛ ويتلقى فهرسها وما إذا كانت نشطة.
`gap`	`number`	`0`	المسافة بين الصفحات بالبكسل.
`itemClassName`	`string`		صنف لعنصر كل بند؛ ويضبط `itemStyle` نمطه المضمّن.
`transition`	`Transition`	`spring`	منحنى توقيت `{ duration, easing }` أو نابض `{ tempo: 'spring', spring }`. تحتفظ النوابض بزخمها عند المقاطعة.

صفحة المكوّن ومنصة التجربة

القوائم

MotionList

قائمة ذات مفاتيح من البيانات لا تحرّك إلا ما تغيّر.

Prop	النوع	الافتراضي	الوصف
`items`	`readonly T[]`	`—`إلزامي	مصفوفة بياناتك.
`getKey`	`(item) => string \| number`	`item.id`	تعيد مفتاحًا فريدًا ثابتًا لعنصر. افتراضيًا `item.id`، أو العنصر نفسه للنصوص والأرقام.
`renderItem`	`(item, index) => ReactNode`	`item.label`	يرسم عنصرًا.
`as`	`element`	`'div'`	العنصر المراد عرضه.
`itemAs`	`element`	`'li' \| 'div'`	العنصر لكل بند.
`itemClassName`	`string`		صنف لعنصر كل بند؛ ويضبط `itemStyle` نمطه المضمّن.
`effect`	`'rise' \| 'fade' \| 'scale' \| 'slide'`	`'rise'`	كيف تدخل العناصر وتخرج.
`distance`	`number`	`16`	مسافة `rise` و`slide` بالبكسل.
`stagger`	`number`	`40`	مللي ثوانٍ بين العناصر الداخلة.
`order`	`'forward' \| 'reverse'`	`'forward'`	اتجاه التتابع.
`present`	`boolean`	`true`	يحرّك `false` كل العناصر خارجة مع الحفاظ على التخطيط؛ ويعيدها `true`.
`initial`	`boolean`	`true`	شغّل الدخول حين تُركَّب القائمة.
`playKey`	`string \| number`		تغييره يعيد تشغيل الدخول.
`transition`	`Transition`	`spring`	الانتقال للعناصر الداخلة والخارجة.
`layoutTransition`	`Transition`	`spring`	الانتقال للعناصر المنزلقة إلى مواضع جديدة.

صفحة المكوّن ومنصة التجربة

MotionReorder

اسحب لإعادة ترتيب قائمة أو شبكة، مع تحريك بلوحة المفاتيح.

Prop	النوع	الافتراضي	الوصف
`items`	`readonly T[]`		العناصر، حين تتحكم أنت في الترتيب.
`defaultItems`	`readonly T[]`	`[]`	العناصر الأولى، حين يحتفظ المكوّن بالترتيب.
`onItemsChange`	`(items, { reason, key }) => void`		يعمل مع الترتيب الجديد وما إذا جاء من سحب أو إفلات أو لوحة المفاتيح.
`getKey`	`(item) => string \| number`	`item`	تعيد مفتاحًا فريدًا لعنصر. افتراضيًا العنصر نفسه.
`renderItem`	`(item, { index, dragging }) => ReactNode`	`item.label`	يرسم عنصرًا؛ ويتلقى فهرسه وما إذا كان يُسحب.
`reorder`	`'live' \| 'drop'`	`'live'`	يحرّك `live` العناصر الأخرى أثناء السحب؛ وينتظر `drop` الإفلات.
`layout`	`'list' \| 'grid'`	`'grid'`	`list` أو `grid`.
`columns`	`number`	`3`	الأعمدة في الشبكة.
`gap`	`number`	`12`	المسافة بين العناصر بالبكسل.
`disabled`	`boolean`	`false`	يعطّل السحب.
`duration`	`number`	`260`	مللي ثوانٍ لتنحّي العناصر.
`itemClassName`	`string`		صنف لعنصر كل بند؛ ويضبط `itemStyle` نمطه المضمّن.

صفحة المكوّن ومنصة التجربة

الإيماءات

MotionSwipe

صف يُظهر الإجراءات بسحب أفقي ويمكن سحبه بعيدًا.

Prop	النوع	الافتراضي	الوصف
`children`	`ReactNode`		محتوى الصف.
`startActions`	`ReactNode`		تظهر في بداية السطر حين يُسحب الصف نحو النهاية.
`endActions`	`ReactNode`		تظهر في نهاية السطر حين يُسحب الصف نحو البداية.
`dismiss`	`'start' \| 'end' \| 'both'`		الجوانب التي يزيل فيها السحب الطويل أو الرمية الصف.
`onDismiss`	`(side) => void`		يعمل بعد انزلاق الصف خارجًا وطيّه؛ أزل العنصر من بياناتك هنا.
`onOpenChange`	`(side \| null) => void`		يعمل مع الجانب المفتوح، أو `null` حين يُغلق الصف.
`disabled`	`boolean`	`false`	يعطّل السحب.
`contentClassName`	`string`		صنف محتوى الصف؛ ويضبط `contentStyle` نمطه المضمّن.
`transition`	`Transition`	`spring`	منحنى توقيت `{ duration, easing }` أو نابض `{ tempo: 'spring', spring }`. تحتفظ النوابض بزخمها عند المقاطعة.

صفحة المكوّن ومنصة التجربة

MotionHold

اضغط مطوّلًا للتأكيد؛ والإفلات المبكر يعيده إلى الوراء.

Prop	النوع	الافتراضي	الوصف
`children`	`ReactNode`		تسمية الزر.
`onConfirm`	`() => void`		يعمل بعد اكتمال الضغط المطوّل.
`duration`	`number`	`1200`	مللي ثوانٍ يجب أن يستمر فيها الضغط.
`disabled`	`boolean`	`false`	يعطّل الزر.
`fillClassName`	`string`		صنف التعبئة المتنامية؛ ويضبط `fillStyle` نمطها المضمّن.

صفحة المكوّن ومنصة التجربة

الطبقات العلوية

MotionSheet

لوحة سفلية أو علوية أو درج جانبي مع نقاط توقف.

Prop	النوع	الافتراضي	الوصف
`open`	`boolean`	`false`	هل اللوحة ظاهرة.
`onOpenChange`	`(open) => void`		يعمل مع `false` حين تُغلق اللوحة بالسحب أو النقر أو Escape.
`detents`	`(number \| 'content')[]`	`['content']`	أحجام السكون: كسر من الشاشة، أو بالبكسل، أو `'content'`.
`detent`	`number`		فهرس نقطة التوقف المتحكَّم به.
`defaultDetent`	`number`	`0`	فهرس نقطة التوقف المستخدم عند الفتح من دون `detent`.
`onDetentChange`	`(index) => void`		يعمل مع فهرس نقطة التوقف التي تستقر عليها اللوحة.
`side`	`'bottom' \| 'top' \| 'start' \| 'end'`	`'bottom'`	الحافة التي تأتي منها اللوحة.
`modal`	`boolean`	`true`	يضيف خلفية، ويُبقي التركيز داخلها، ويجعل الصفحة خاملة.
`dismissible`	`boolean`	`true`	السحب بعد أصغر نقطة توقف والخلفية وEscape تغلقها.
`backdropClassName`	`string`		صنف الخلفية؛ ويضبط `backdropStyle` نمطها المضمّن.
`transition`	`Transition`	`spring`	منحنى توقيت `{ duration, easing }` أو نابض `{ tempo: 'spring', spring }`. تحتفظ النوابض بزخمها عند المقاطعة.

صفحة المكوّن ومنصة التجربة

MotionZoom

صورة تتكبّر من مكانها لتملأ الشاشة.

Prop	النوع	الافتراضي	الوصف
`src`	`string`		الصورة المعروضة في مكانها.
`zoomSrc`	`string`		صورة أكبر تُعرض بمجرد تحميلها؛ احتفظ بنسبة الأبعاد نفسها.
`margin`	`number`	`24`	المسافة المتروكة حول الصورة المكبّرة بالبكسل.
`disabled`	`boolean`	`false`	يعطّل التكبير.
`onZoomChange`	`(zoomed) => void`		يعمل مع `true` عند التكبير و`false` عند الإغلاق.
`backdropStyle`	`CSSProperties`		النمط المضمّن للخلفية.
`transition`	`Transition`	`spring`	منحنى توقيت `{ duration, easing }` أو نابض `{ tempo: 'spring', spring }`. تحتفظ النوابض بزخمها عند المقاطعة.

صفحة المكوّن ومنصة التجربة

التقدّم

ProgressBar

خط تقدّم متحكَّم به مع حالة غير محدّدة.

Prop	النوع	الافتراضي	الوصف
`value`	`number \| null`		التقدّم من `0` إلى `max`؛ و`null` غير محدّد.
`max`	`number`	`100`	القيمة التي تعني الاكتمال.
`color`	`string`	`'currentColor'`	لون التعبئة.
`trackColor`	`string`	`'#e7ece9'`	لون المسار.
`thickness`	`number`	`8`	سماكة الخط بالبكسل.
`direction`	`'ltr' \| 'rtl'`	`'ltr'`	التعبئة من اليسار (`ltr`) أو من اليمين (`rtl`).
`transition`	`Transition`	`spring`	منحنى توقيت `{ duration, easing }` أو نابض `{ tempo: 'spring', spring }`. تحتفظ النوابض بزخمها عند المقاطعة.

صفحة المكوّن ومنصة التجربة

ProgressRing

حلقة تقدّم متحكَّم بها مع حالة غير محدّدة.

Prop	النوع	الافتراضي	الوصف
`value`	`number \| null`		التقدّم من `0` إلى `max`؛ و`null` غير محدّد.
`max`	`number`	`100`	القيمة التي تعني الاكتمال.
`size`	`number`	`96`	القطر بالبكسل.
`thickness`	`number`	`8`	سماكة الحلقة بالبكسل.
`color`	`string`	`'currentColor'`	لون القوس.
`trackColor`	`string`	`'#e7ece9'`	لون المسار.
`children`	`ReactNode`		تسمية تظهر في المنتصف.
`transition`	`Transition`	`spring`	منحنى توقيت `{ duration, easing }` أو نابض `{ tempo: 'spring', spring }`. تحتفظ النوابض بزخمها عند المقاطعة.

صفحة المكوّن ومنصة التجربة

الانتقالات

motionTokens

قيم جاهزة لأي خاصية transition.

Prop	النوع	الافتراضي	الوصف
`duration`	`{ instant, fast, normal, slow }`	`0 · 140 · 280 · 520`	مدد بالمللي ثانية.
`easing`	`{ ease, easeOut, expoOut, backOut }`	`Transition`	انتقالات توقيت بمدة ومنحنى مسمّى.
`spring`	`{ quick, basic, gentle, bouncy }`	`Transition`	انتقالات نابضة، من السريعة الحازمة إلى اللطيفة المرتدّة.

الانتقالات

App.jsx

// Web and React Native: the same import.
import { MotionNumber, MotionList } from '@kkwaenggwari/animated-chorus';

export function Score({ points, players }) {
  return (
    <>
      <MotionNumber value={points} />
      <MotionList items={players} renderItem={(player) => player.name} />
    </>
  );
}