עיון ב־API

כל export של @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[]`		Locale עבור `intl`.
`prefix`	`string`		טקסט לפני המספר.
`suffix`	`string`		טקסט אחרי המספר.
`transition`	`Transition`	`spring`	עקומת timing `{ duration, easing }` או קפיץ `{ tempo: 'spring', spring }`. קפיצים שומרים על התנופה שלהם כשמפריעים להם.
`onMotionComplete`	`(value) => void`		רץ עם הערך ברגע שהספרות התייצבו.

עמוד הרכיב ושולחן העבודה

MotionText

טקסט שזז כשהוא משתנה: טקסט מספרי מתגלגל ספרה אחר ספרה, טקסט אחר מתחלף.

Prop	טיפוס	ברירת מחדל	תיאור
`children`	`ReactNode`		הטקסט להצגה.
`as`	`element`	`'span'`	האלמנט לרינדור.
`transition`	`Transition`	`spring`	עקומת timing `{ 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`	עקומת timing `{ duration, easing }` או קפיץ `{ tempo: 'spring', spring }`. קפיצים שומרים על התנופה שלהם כשמפריעים להם.
`onMotionComplete`	`(value) => void`		רץ כשהתנועה מתייצבת.

עמוד הרכיב ושולחן העבודה

MotionHeight

מנפיש גובה לפי התוכן: קיפול, פתיחה ושינויי תוכן.

Prop	טיפוס	ברירת מחדל	תיאור
`open`	`boolean`	`true`	`false` מקפל לגובה אפס; התוכן נשאר מורכב אבל מוסתר ולא פעיל.
`children`	`ReactNode`		התוכן.
`as`	`element`	`'div'`	האלמנט לרינדור.
`transition`	`Transition`	`spring`	עקומת timing `{ duration, easing }` או קפיץ `{ tempo: 'spring', spring }`. קפיצים שומרים על התנופה שלהם כשמפריעים להם.
`onMotionComplete`	`(open) => void`		רץ עם `open` ברגע שהגובה התייצב.

עמוד הרכיב ושולחן העבודה

MotionPresence

שומר תוכן מורכב בזמן שהוא נכנס ויוצא בתנועה.

Prop	טיפוס	ברירת מחדל	תיאור
`present`	`boolean`	`—`חובה	להציג או להסתיר את התוכן. שנו את זה במקום להסיר.
`enter`	`Pose`	`{ opacity: 1, translateY: 0 }`	ה־pose במנוחה.
`exit`	`Pose`	`{ opacity: 0, translateY: -12 }`	ה־pose שבו התוכן יוצא וממנו הוא נכנס.
`as`	`element`	`'div'`	האלמנט לרינדור.
`transition`	`Transition`	`spring`	עקומת timing `{ 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`		class לאלמנט של כל פריט; `itemStyle` מגדיר את הסגנון המוטבע שלו.
`highlightClassName`	`string`		class להדגשה; `highlightStyle` מגדיר את הסגנון המוטבע שלה.
`transition`	`Transition`	`spring`	עקומת timing `{ 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`		class לאלמנט של כל פריט; `itemStyle` מגדיר את הסגנון המוטבע שלו.
`transition`	`Transition`	`spring`	עקומת timing `{ 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`		class לאלמנט של כל פריט; `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`		class לאלמנט של כל פריט; `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`		class לתוכן השורה; `contentStyle` מגדיר את הסגנון המוטבע שלו.
`transition`	`Transition`	`spring`	עקומת timing `{ duration, easing }` או קפיץ `{ tempo: 'spring', spring }`. קפיצים שומרים על התנופה שלהם כשמפריעים להם.

עמוד הרכיב ושולחן העבודה

MotionHold

לחיצה ממושכת לאישור; שחרור מוקדם מחזיר אחורה.

Prop	טיפוס	ברירת מחדל	תיאור
`children`	`ReactNode`		תווית הכפתור.
`onConfirm`	`() => void`		רץ ברגע שההחזקה הושלמה.
`duration`	`number`	`1200`	מילישניות שצריך להחזיק את הלחיצה.
`disabled`	`boolean`	`false`	מכבה את הכפתור.
`fillClassName`	`string`		class למילוי שגדל; `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`		class לרקע; `backdropStyle` מגדיר את הסגנון המוטבע שלו.
`transition`	`Transition`	`spring`	עקומת timing `{ 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`	עקומת timing `{ 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`	עקומת timing `{ 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`	עקומת timing `{ duration, easing }` או קפיץ `{ tempo: 'spring', spring }`. קפיצים שומרים על התנופה שלהם כשמפריעים להם.

עמוד הרכיב ושולחן העבודה

מעברים

motionTokens

ערכים מוכנים לכל prop של transition.

Prop	טיפוס	ברירת מחדל	תיאור
`duration`	`{ instant, fast, normal, slow }`	`0 · 140 · 280 · 520`	משכים במילישניות.
`easing`	`{ ease, easeOut, expoOut, backOut }`	`Transition`	מעברי timing עם משך ועקומה בעלת שם.
`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} />
    </>
  );
}