Dokumentacja API

Każdy eksport @kkwaenggwari/animated-chorus z props, typami i wartościami domyślnymi. Te same nazwy działają w sieci i w React Native.

FiltrAPI: 17

Liczby i tekst

MotionNumber

Liczba, której cyfry obracają się jak kółka.

Prop	Typ	Domyślnie	Opis
`value`	`number \| bigint \| string`	`—`wymagane	Liczba lub sformatowany przez ciebie tekst liczbowy.
`mode`	`'replace' \| 'roll'`	`'replace'`	`replace` przesuwa każdą zmienioną cyfrę o jeden krok; `roll` przechodzi przez cyfry pośrednie.
`direction`	`'auto' \| 'digit' \| 'up' \| 'down'`	`'auto'`	`auto` podąża za zmianą wielkości, więc przeniesienia przewijają się w jedną stronę; `digit` porównuje każdą cyfrę osobno.
`stagger`	`number`	`45`	Milisekundy między zmienionymi cyframi, od jedności na zewnątrz. Cała fala jest ograniczona w czasie.
`format`	`(value) => string \| Intl.NumberFormatOptions`		Funkcja zwracająca tekst do pokazania lub opcje `Intl.NumberFormat` (z `intl`).
`intl`	`boolean`	`false`	Użyj wbudowanego `Intl.NumberFormat`. Domyślnie wyłączone, więc żadne środowisko nie potrzebuje `Intl`.
`locale`	`string \| string[]`		Locale dla `intl`.
`prefix`	`string`		Tekst przed liczbą.
`suffix`	`string`		Tekst po liczbie.
`transition`	`Transition`	`spring`	Krzywa timing `{ duration, easing }` lub sprężyna `{ tempo: 'spring', spring }`. Sprężyny zachowują pęd po przerwaniu.
`onMotionComplete`	`(value) => void`		Uruchamia się z wartością, gdy cyfry się ułożą.

Strona komponentu i stanowisko

MotionText

Tekst animowany przy zmianie: tekst liczbowy przewija się cyfra po cyfrze, inny się zamienia.

Prop	Typ	Domyślnie	Opis
`children`	`ReactNode`		Tekst do pokazania.
`as`	`element`	`'span'`	Element do wyrenderowania.
`transition`	`Transition`	`spring`	Krzywa timing `{ duration, easing }` lub sprężyna `{ tempo: 'spring', spring }`. Sprężyny zachowują pęd po przerwaniu.
`onMotionComplete`	`(text) => void`		Uruchamia się, gdy ruch się ułoży.

Strona komponentu i stanowisko

MotionStream

Tekst strumieniowany odsłaniany w równym tempie, który nadrabia serie.

Prop	Typ	Domyślnie	Opis
`text`	`string`	`—`wymagane	Dotychczasowy tekst. Rosnący tekst odsłania się w równym tempie; przepisanie kontynuuje od wspólnego początku.
`speed`	`number`	`90`	Bazowa prędkość odsłaniania w znakach na sekundę.
`catchUp`	`number`	`900`	Zaległość jest odsłaniana w mniej więcej tylu milisekundach dzięki przyspieszeniu.
`initial`	`boolean`	`false`	Odsłaniaj też tekst obecny przy montażu (w przeciwnym razie pokazuje się od razu).
`effect`	`'fade' \| 'none'`	`'fade'`	`fade` wprowadza nowe znaki stopniowo; `none` pokazuje je od razu.
`children`	`(visible: string) => ReactNode`		Funkcja dostająca tekst w wyrównanym tempie, na przykład do renderowania Markdown.
`as`	`element`	`'span'`	Element do wyrenderowania.
`onMotionComplete`	`(text) => void`		Uruchamia się za każdym razem, gdy odsłanianie dogoni `text`.

Strona komponentu i stanowisko

Treść i rozmiar

MotionSwap

Treść przenikająca się, gdy element zmienia rozmiar.

Prop	Typ	Domyślnie	Opis
`value`	`unknown`		Tożsamość treści; nowa wartość ją zamienia. Dzieci będące zwykłym tekstem są własną tożsamością.
`children`	`ReactNode`		Treść.
`as`	`element`	`'span'`	Element do wyrenderowania.
`inline`	`boolean`	`as === 'span'`	`true` dopasowuje rozmiar do treści (etykiety, ikony); `false` wypełnia szerokość rodzica i animuje wysokość.
`align`	`'start' \| 'center' \| 'end'`	`'center'`	Gdzie znajduje się treść podczas zmiany rozmiaru.
`effect`	`'fade' \| 'up' \| 'down' \| 'scale'`	`'fade'`	Jak treść wchodzi i wychodzi: `up` unosi się, `down` opada, `scale` rośnie.
`transition`	`Transition`	`spring`	Krzywa timing `{ duration, easing }` lub sprężyna `{ tempo: 'spring', spring }`. Sprężyny zachowują pęd po przerwaniu.
`onMotionComplete`	`(value) => void`		Uruchamia się, gdy ruch się ułoży.

Strona komponentu i stanowisko

MotionHeight

Animuje wysokość do treści: zwijanie, rozwijanie i zmiany treści.

Prop	Typ	Domyślnie	Opis
`open`	`boolean`	`true`	`false` zwija do zerowej wysokości; treść pozostaje zamontowana, ale ukryta i nieaktywna.
`children`	`ReactNode`		Treść.
`as`	`element`	`'div'`	Element do wyrenderowania.
`transition`	`Transition`	`spring`	Krzywa timing `{ duration, easing }` lub sprężyna `{ tempo: 'spring', spring }`. Sprężyny zachowują pęd po przerwaniu.
`onMotionComplete`	`(open) => void`		Uruchamia się z `open`, gdy wysokość się ułoży.

Strona komponentu i stanowisko

MotionPresence

Utrzymuje treść zamontowaną, gdy animuje się wejście i wyjście.

Prop	Typ	Domyślnie	Opis
`present`	`boolean`	`—`wymagane	Pokaż lub ukryj treść. Zmieniaj to zamiast odmontowywać.
`enter`	`Pose`	`{ opacity: 1, translateY: 0 }`	Poza w spoczynku.
`exit`	`Pose`	`{ opacity: 0, translateY: -12 }`	Poza, z którą treść wychodzi i z której wchodzi.
`as`	`element`	`'div'`	Element do wyrenderowania.
`transition`	`Transition`	`spring`	Krzywa timing `{ duration, easing }` lub sprężyna `{ tempo: 'spring', spring }`. Sprężyny zachowują pęd po przerwaniu.
`onExitComplete`	`() => void`		Uruchamia się, gdy treść odejdzie i zostanie usunięta.

Strona komponentu i stanowisko

Wybór i strony

MotionHighlight

Elementy z danych z jednym wyróżnieniem, które przesuwa się do wybranego elementu.

Prop	Typ	Domyślnie	Opis
`items`	`readonly T[]`	`—`wymagane	Twoja tablica danych.
`value`	`key \| null`	`—`wymagane	Klucz wyróżnionego elementu; `null` ukrywa wyróżnienie.
`onValueChange`	`(key, item) => void`		Uruchamia się z kluczem i elementem po naciśnięciu elementu.
`getKey`	`(item) => string \| number`	`item.id`	Zwraca unikalny, stabilny klucz elementu. Domyślnie `item.id`, a dla ciągów i liczb sam element.
`renderItem`	`(item, { selected, index }) => ReactNode`	`item.label`	Rysuje element; dostaje informację, czy jest wybrany.
`hover`	`boolean`	`false`	Podążaj za wskaźnikiem nad elementami i wróć do `value` po wyjściu (sieć).
`itemAs`	`element`	`'button'`	Element dla każdej pozycji.
`itemClassName`	`string`		Klasa dla elementu każdej pozycji; `itemStyle` ustawia jego styl inline.
`highlightClassName`	`string`		Klasa wyróżnienia; `highlightStyle` ustawia jego styl inline.
`transition`	`Transition`	`spring`	Krzywa timing `{ duration, easing }` lub sprężyna `{ tempo: 'spring', spring }`. Sprężyny zachowują pęd po przerwaniu.

Strona komponentu i stanowisko

MotionPager

Strony z danych przewijane gestem.

Prop	Typ	Domyślnie	Opis
`items`	`readonly T[]`	`—`wymagane	Twoja tablica danych.
`index`	`number`		Pokazywana strona. Pomiń ją, by pager zarządzał własną.
`defaultIndex`	`number`	`0`	Strona początkowa, gdy `index` nie jest kontrolowany.
`onIndexChange`	`(index, item) => void`		Uruchamia się z indeksem i elementem, gdy tylko przesunięcie, klawisz lub gest kółka się ułoży.
`getKey`	`(item) => string \| number`	`item.id`	Zwraca unikalny, stabilny klucz elementu. Domyślnie `item.id`, a dla ciągów i liczb sam element.
`renderItem`	`(item, { index, active }) => ReactNode`	`item.label`	Rysuje stronę; dostaje jej indeks i informację, czy jest aktywna.
`gap`	`number`	`0`	Odstęp między stronami w pikselach.
`itemClassName`	`string`		Klasa dla elementu każdej pozycji; `itemStyle` ustawia jego styl inline.
`transition`	`Transition`	`spring`	Krzywa timing `{ duration, easing }` lub sprężyna `{ tempo: 'spring', spring }`. Sprężyny zachowują pęd po przerwaniu.

Strona komponentu i stanowisko

Listy

MotionList

Lista z kluczami z danych, która animuje tylko to, co się zmieniło.

Prop	Typ	Domyślnie	Opis
`items`	`readonly T[]`	`—`wymagane	Twoja tablica danych.
`getKey`	`(item) => string \| number`	`item.id`	Zwraca unikalny, stabilny klucz elementu. Domyślnie `item.id`, a dla ciągów i liczb sam element.
`renderItem`	`(item, index) => ReactNode`	`item.label`	Rysuje element.
`as`	`element`	`'div'`	Element do wyrenderowania.
`itemAs`	`element`	`'li' \| 'div'`	Element dla każdej pozycji.
`itemClassName`	`string`		Klasa dla elementu każdej pozycji; `itemStyle` ustawia jego styl inline.
`effect`	`'rise' \| 'fade' \| 'scale' \| 'slide'`	`'rise'`	Jak elementy wchodzą i wychodzą.
`distance`	`number`	`16`	Droga `rise` i `slide` w pikselach.
`stagger`	`number`	`40`	Milisekundy między wchodzącymi elementami.
`order`	`'forward' \| 'reverse'`	`'forward'`	Kierunek kaskady.
`present`	`boolean`	`true`	`false` animuje wyjście wszystkich elementów, zachowując układ; `true` je przywraca.
`initial`	`boolean`	`true`	Odtwórz wejście przy montażu listy.
`playKey`	`string \| number`		Jej zmiana odtwarza wejście ponownie.
`transition`	`Transition`	`spring`	Przejście dla elementów wchodzących i wychodzących.
`layoutTransition`	`Transition`	`spring`	Przejście dla elementów przechodzących na nowe pozycje.

Strona komponentu i stanowisko

MotionReorder

Przeciągnij, by zmienić kolejność listy lub siatki, z przesuwaniem klawiaturą.

Prop	Typ	Domyślnie	Opis
`items`	`readonly T[]`		Elementy, gdy to ty kontrolujesz kolejność.
`defaultItems`	`readonly T[]`	`[]`	Elementy początkowe, gdy kolejność trzyma komponent.
`onItemsChange`	`(items, { reason, key }) => void`		Uruchamia się z nową kolejnością i informacją, czy pochodzi z przeciągania, upuszczenia czy klawiatury.
`getKey`	`(item) => string \| number`	`item`	Zwraca unikalny klucz elementu. Domyślnie sam element.
`renderItem`	`(item, { index, dragging }) => ReactNode`	`item.label`	Rysuje element; dostaje jego indeks i informację, czy jest przeciągany.
`reorder`	`'live' \| 'drop'`	`'live'`	`live` przesuwa inne elementy podczas przeciągania; `drop` czeka na upuszczenie.
`layout`	`'list' \| 'grid'`	`'grid'`	`list` lub `grid`.
`columns`	`number`	`3`	Kolumny w siatce.
`gap`	`number`	`12`	Odstęp między elementami w pikselach.
`disabled`	`boolean`	`false`	Wyłącza przeciąganie.
`duration`	`number`	`260`	Milisekundy, w których elementy robią miejsce.
`itemClassName`	`string`		Klasa dla elementu każdej pozycji; `itemStyle` ustawia jego styl inline.

Strona komponentu i stanowisko

Gesty

MotionSwipe

Wiersz odsłaniający akcje poziomym przesunięciem, który można odrzucić.

Prop	Typ	Domyślnie	Opis
`children`	`ReactNode`		Treść wiersza.
`startActions`	`ReactNode`		Odsłaniane na początku wiersza, gdy przeciąga się go w stronę końca.
`endActions`	`ReactNode`		Odsłaniane na końcu wiersza, gdy przeciąga się go w stronę początku.
`dismiss`	`'start' \| 'end' \| 'both'`		Strony, po których długie przesunięcie lub rzut usuwa wiersz.
`onDismiss`	`(side) => void`		Uruchamia się po wysunięciu i zwinięciu wiersza; tu usuń element ze swoich danych.
`onOpenChange`	`(side \| null) => void`		Uruchamia się z otwartą stroną lub `null`, gdy wiersz się zamyka.
`disabled`	`boolean`	`false`	Wyłącza przesuwanie.
`contentClassName`	`string`		Klasa dla treści wiersza; `contentStyle` ustawia jej styl inline.
`transition`	`Transition`	`spring`	Krzywa timing `{ duration, easing }` lub sprężyna `{ tempo: 'spring', spring }`. Sprężyny zachowują pęd po przerwaniu.

Strona komponentu i stanowisko

MotionHold

Naciśnij i przytrzymaj, by potwierdzić; wczesne puszczenie cofa.

Prop	Typ	Domyślnie	Opis
`children`	`ReactNode`		Etykieta przycisku.
`onConfirm`	`() => void`		Uruchamia się po zakończeniu przytrzymania.
`duration`	`number`	`1200`	Milisekundy, przez które trzeba przytrzymać.
`disabled`	`boolean`	`false`	Wyłącza przycisk.
`fillClassName`	`string`		Klasa dla rosnącego wypełnienia; `fillStyle` ustawia jego styl inline.

Strona komponentu i stanowisko

Nakładki

MotionSheet

Arkusz dolny, górny lub szuflada boczna z punktami zatrzymania.

Prop	Typ	Domyślnie	Opis
`open`	`boolean`	`false`	Czy arkusz jest widoczny.
`onOpenChange`	`(open) => void`		Uruchamia się z `false`, gdy arkusz zostaje zamknięty przeciągnięciem, dotknięciem lub klawiszem Escape.
`detents`	`(number \| 'content')[]`	`['content']`	Rozmiary spoczynku: ułamek ekranu, piksele lub `'content'`.
`detent`	`number`		Kontrolowany indeks punktu zatrzymania.
`defaultDetent`	`number`	`0`	Indeks punktu zatrzymania przy otwarciu bez `detent`.
`onDetentChange`	`(index) => void`		Uruchamia się z indeksem punktu zatrzymania, na którym arkusz się układa.
`side`	`'bottom' \| 'top' \| 'start' \| 'end'`	`'bottom'`	Krawędź, z której wysuwa się arkusz.
`modal`	`boolean`	`true`	Dodaje tło, trzyma fokus w środku i czyni stronę nieaktywną.
`dismissible`	`boolean`	`true`	Przeciągnięcie poza najmniejszy punkt zatrzymania, tło i Escape go zamykają.
`backdropClassName`	`string`		Klasa tła; `backdropStyle` ustawia jego styl inline.
`transition`	`Transition`	`spring`	Krzywa timing `{ duration, easing }` lub sprężyna `{ tempo: 'spring', spring }`. Sprężyny zachowują pęd po przerwaniu.

Strona komponentu i stanowisko

MotionZoom

Obraz powiększający się od miejsca, w którym jest, aż wypełni ekran.

Prop	Typ	Domyślnie	Opis
`src`	`string`		Obraz pokazywany w miejscu.
`zoomSrc`	`string`		Większy obraz pokazywany, gdy się wczyta; zachowaj te same proporcje.
`margin`	`number`	`24`	Odstęp wokół powiększonego obrazu w pikselach.
`disabled`	`boolean`	`false`	Wyłącza powiększanie.
`onZoomChange`	`(zoomed) => void`		Uruchamia się z `true` po powiększeniu i `false` po zamknięciu.
`backdropStyle`	`CSSProperties`		Styl inline tła.
`transition`	`Transition`	`spring`	Krzywa timing `{ duration, easing }` lub sprężyna `{ tempo: 'spring', spring }`. Sprężyny zachowują pęd po przerwaniu.

Strona komponentu i stanowisko

Postęp

ProgressBar

Kontrolowana linia postępu ze stanem nieokreślonym.

Prop	Typ	Domyślnie	Opis
`value`	`number \| null`		Postęp od `0` do `max`; `null` oznacza stan nieokreślony.
`max`	`number`	`100`	Wartość oznaczająca ukończenie.
`color`	`string`	`'currentColor'`	Kolor wypełnienia.
`trackColor`	`string`	`'#e7ece9'`	Kolor toru.
`thickness`	`number`	`8`	Grubość linii w pikselach.
`direction`	`'ltr' \| 'rtl'`	`'ltr'`	Wypełnianie od lewej (`ltr`) lub od prawej (`rtl`).
`transition`	`Transition`	`spring`	Krzywa timing `{ duration, easing }` lub sprężyna `{ tempo: 'spring', spring }`. Sprężyny zachowują pęd po przerwaniu.

Strona komponentu i stanowisko

ProgressRing

Kontrolowany pierścień postępu ze stanem nieokreślonym.

Prop	Typ	Domyślnie	Opis
`value`	`number \| null`		Postęp od `0` do `max`; `null` oznacza stan nieokreślony.
`max`	`number`	`100`	Wartość oznaczająca ukończenie.
`size`	`number`	`96`	Średnica w pikselach.
`thickness`	`number`	`8`	Grubość pierścienia w pikselach.
`color`	`string`	`'currentColor'`	Kolor łuku.
`trackColor`	`string`	`'#e7ece9'`	Kolor toru.
`children`	`ReactNode`		Etykieta pokazywana w środku.
`transition`	`Transition`	`spring`	Krzywa timing `{ duration, easing }` lub sprężyna `{ tempo: 'spring', spring }`. Sprężyny zachowują pęd po przerwaniu.

Strona komponentu i stanowisko

Przejścia

motionTokens

Gotowe wartości dla dowolnego propa transition.

Prop	Typ	Domyślnie	Opis
`duration`	`{ instant, fast, normal, slow }`	`0 · 140 · 280 · 520`	Czasy trwania w milisekundach.
`easing`	`{ ease, easeOut, expoOut, backOut }`	`Transition`	Przejścia timing z czasem trwania i nazwaną krzywą.
`spring`	`{ quick, basic, gentle, bouncy }`	`Transition`	Przejścia sprężynowe, od szybkich i sztywnych po łagodne i sprężyste.

Przejścia

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} />
    </>
  );
}