Довідник API

Усі експорти @kkwaenggwari/animated-chorus із props, типами й типовими значеннями. Ті самі назви працюють у вебі та React Native.

ФільтрAPI: 17

Числа й текст

MotionNumber

Число, розряди якого крутяться як коліщатка.

Проп	Тип	Типово	Опис
`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`	Крива timing `{ duration, easing }` чи пружина `{ tempo: 'spring', spring }`. Після переривання пружини зберігають інерцію.
`onMotionComplete`	`(value) => void`		Виконується зі значенням, коли розряди зупинилися.

Сторінка компонента й стенд

MotionText

Текст, що анімується під час зміни: числовий прокручується розрядами, решта змінюється.

Проп	Тип	Типово	Опис
`children`	`ReactNode`		Текст для показу.
`as`	`element`	`'span'`	Елемент для рендеру.
`transition`	`Transition`	`spring`	Крива timing `{ duration, easing }` чи пружина `{ tempo: 'spring', spring }`. Після переривання пружини зберігають інерцію.
`onMotionComplete`	`(text) => void`		Виконується, коли рух зупиняється.

Сторінка компонента й стенд

MotionStream

Потоковий текст, що розкривається в рівному темпі й наздоганяє сплески.

Проп	Тип	Типово	Опис
`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

Вміст, що плавно змінюється, поки елемент змінює розмір.

Проп	Тип	Типово	Опис
`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

Анімує висоту за вмістом: згортання, розгортання й зміни вмісту.

Проп	Тип	Типово	Опис
`open`	`boolean`	`true`	`false` згортає до нульової висоти; вміст лишається змонтованим, але прихованим і неактивним.
`children`	`ReactNode`		Вміст.
`as`	`element`	`'div'`	Елемент для рендеру.
`transition`	`Transition`	`spring`	Крива timing `{ duration, easing }` чи пружина `{ tempo: 'spring', spring }`. Після переривання пружини зберігають інерцію.
`onMotionComplete`	`(open) => void`		Виконується з `open`, коли висота зупинилася.

Сторінка компонента й стенд

MotionPresence

Тримає вміст змонтованим, поки він анімовано з’являється й іде.

Проп	Тип	Типово	Опис
`present`	`boolean`	`—`обов’язково	Показати чи приховати вміст. Змінюйте це замість демонтування.
`enter`	`Pose`	`{ opacity: 1, translateY: 0 }`	Поза в спокої.
`exit`	`Pose`	`{ opacity: 0, translateY: -12 }`	Поза, з якою вміст іде й з якої входить.
`as`	`element`	`'div'`	Елемент для рендеру.
`transition`	`Transition`	`spring`	Крива timing `{ duration, easing }` чи пружина `{ tempo: 'spring', spring }`. Після переривання пружини зберігають інерцію.
`onExitComplete`	`() => void`		Виконується після того, як вміст пішов і його видалено.

Сторінка компонента й стенд

Вибір і сторінки

MotionHighlight

Елементи з даних з одним підсвічуванням, що переміщується до вибраного елемента.

Проп	Тип	Типово	Опис
`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`	Крива timing `{ duration, easing }` чи пружина `{ tempo: 'spring', spring }`. Після переривання пружини зберігають інерцію.

Сторінка компонента й стенд

MotionPager

Сторінки з даних, що гортаються.

Проп	Тип	Типово	Опис
`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`	Крива timing `{ duration, easing }` чи пружина `{ tempo: 'spring', spring }`. Після переривання пружини зберігають інерцію.

Сторінка компонента й стенд

Списки

MotionList

Список із ключами з даних, що анімує лише змінене.

Проп	Тип	Типово	Опис
`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

Перестановка списку чи сітки перетягуванням, із переміщенням з клавіатури.

Проп	Тип	Типово	Опис
`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

Рядок, що відкриває дії горизонтальним свайпом і може бути змахнутий.

Проп	Тип	Типово	Опис
`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`	Крива timing `{ duration, easing }` чи пружина `{ tempo: 'spring', spring }`. Після переривання пружини зберігають інерцію.

Сторінка компонента й стенд

MotionHold

Натисніть і втримуйте для підтвердження; раннє відпускання відкочує назад.

Проп	Тип	Типово	Опис
`children`	`ReactNode`		Підпис кнопки.
`onConfirm`	`() => void`		Виконується, коли утримання завершено.
`duration`	`number`	`1200`	Скільки мілісекунд треба утримувати натискання.
`disabled`	`boolean`	`false`	Вимикає кнопку.
`fillClassName`	`string`		Клас для заливки, що росте; `fillStyle` задає її вбудований стиль.

Сторінка компонента й стенд

Оверлеї

MotionSheet

Нижня чи верхня шторка або бічна панель із точками зупинки.

Проп	Тип	Типово	Опис
`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`	Крива timing `{ duration, easing }` чи пружина `{ tempo: 'spring', spring }`. Після переривання пружини зберігають інерцію.

Сторінка компонента й стенд

MotionZoom

Зображення, що збільшується зі свого місця до заповнення екрана.

Проп	Тип	Типово	Опис
`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

Керована лінія прогресу з невизначеним станом.

Проп	Тип	Типово	Опис
`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

Кероване кільце прогресу з невизначеним станом.

Проп	Тип	Типово	Опис
`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

Готові значення для будь-якого пропа transition.

Проп	Тип	Типово	Опис
`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} />
    </>
  );
}