@chayns-components/typewriter 5.0.52 → 5.0.53-alpha.1

package/lib/types/components/typewriter/Typewriter.d.ts

@@ -4,104 +4,113 @@ import { CursorType } from '../../types/cursor';
 import { TypewriterDelay, TypewriterSpeed } from '../../types/speed';
 export type TypewriterProps = {
     /**
-     * The number of characters that will be animated per animation cycle.
+     * The number of characters that will be animated per animation step.
+     *
+     * The step is advanced by the requestAnimationFrame-driven scheduler. When
+     * `shouldCalcAutoSpeed` is enabled, the component may override this value dynamically.
      */
     animationSteps?: number;
     /**
-     * The text to type
+     * The content to type.
+     *
+     * Strings are animated directly. React elements and arrays are rendered to HTML first so the
+     * typewriter can preserve nested markup and inline components.
      */
     children: ReactElement | ReactElement[] | string | string[];
     /**
-     * The type of the cursor. Use the CursorType enum for this prop.
+     * The type of the cursor. Use the `CursorType` enum for this prop.
      */
     cursorType?: CursorType;
     /**
      * The delay in milliseconds before the next text is shown.
-     * This prop is only used if multiple texts are given.
+     *
+     * This prop is only used when `children` is an array.
      */
     nextTextDelay?: TypewriterDelay;
     /**
-     * Function that is executed when the typewriter animation has finished. This function will not
-     * be executed if multiple texts are used.
+     * Function that is executed when the entire typewriter animation has finished.
+     *
+     * This callback is not used while more texts are still queued.
      */
     onFinish?: VoidFunction;
     /**
-     * Function that is executed when the reset animation has finished. This function will not be
-     * executed if `shouldUseResetAnimation` is not set to `true`.
+     * Function that is executed when the reset animation has finished.
+     *
+     * This callback only runs when `shouldUseResetAnimation` is enabled.
      */
     onResetAnimationEnd?: VoidFunction;
     /**
-     * Function that is executed when the reset animation has started. This function will not be
-     * executed if `shouldUseResetAnimation` is not set to `true`.
+     * Function that is executed when the reset animation has started.
+     *
+     * This callback only runs when `shouldUseResetAnimation` is enabled.
      */
     onResetAnimationStart?: VoidFunction;
     /**
-     * Function that is executed when the typing animation has finished. If multiple texts are given,
-     * this function will be executed for each text.
+     * Function that is executed when the typing animation has finished.
+     *
+     * If multiple texts are given, this function will be executed for each text.
      */
     onTypingAnimationEnd?: VoidFunction;
     /**
-     * Function that is executed when the typing animation has started. If multiple texts are given,
-     * this function will be executed for each text.
+     * Function that is executed when the typing animation has started.
+     *
+     * If multiple texts are given, this function will be executed for each text.
      */
     onTypingAnimationStart?: VoidFunction;
     /**
-     * Pseudo-element to be rendered invisible during animation to define the size of the element
-     * for the typewriter effect. By default, the "children" is used for this purpose.
+     * Invisible content that defines the reserved layout size while the animation is running.
+     *
+     * When omitted, the visible `children` are used as the layout template.
      */
     pseudoChildren?: ReactElement | string;
     /**
      * Waiting time in milliseconds before the typewriter resets the text.
-     * This prop is only used if multiple texts are given.
+     *
+     * This prop is only used when `children` is an array.
      */
     resetDelay?: TypewriterDelay;
     /**
-     * The reset speed of the animation. Use the TypewriterSpeed enum for this prop.
+     * The reset speed of the animation. Use the `TypewriterSpeed` enum for this prop.
      */
     resetSpeed?: TypewriterSpeed | number;
     /**
-     * Specifies whether the cursor should be forced to animate even if no text is currently animated.
+     * Keeps the cursor animated even if the current text is not actively changing.
      */
     shouldForceCursorAnimation?: boolean;
     /**
-     * Specifies whether the cursor should be hidden
+     * Hides the cursor entirely.
      */
     shouldHideCursor?: boolean;
     /**
-     * Whether the content should remain a single line.
+     * Keeps the content on a single line and applies ellipsis overflow handling.
      */
     shouldRemainSingleLine?: boolean;
     /**
-     * Specifies whether the children should be sorted randomly if there are multiple texts.
-     * This makes the typewriter start with a different text each time and also changes them
-     * in a random order.
+     * Randomizes the order of `children` when multiple texts are provided.
      */
     shouldSortChildrenRandomly?: boolean;
     /**
-     * Specifies whether the animation should use its full height or the height of the current
-     * chunk.
+     * Makes the hidden sizing text follow the currently revealed chunk instead of the full content.
      */
     shouldUseAnimationHeight?: boolean;
     /**
-     * Whether the animation speed should be calculated with the chunk interval.
+     * Derives the typing cadence from the observed streaming rate.
      */
     shouldCalcAutoSpeed?: boolean;
     /**
-     * Sets how long the animation should last when `shouldCalcAutoSpeed` is enabled in milliseconds.
-     * When chunks are streamed, this value will only be used for the initial speed and then change to the speed characters are added at
+     * Base factor used to initialize the auto-speed EMA.
      */
     autoSpeedBaseFactor?: number;
     /**
-     * Specifies whether the reset of the text should be animated with a backspace animation for
-     * multiple texts.
+     * Animates the reset between multiple texts with a backspace-like effect.
      */
     shouldUseResetAnimation?: boolean;
     /**
-     * Whether the typewriter should wait for new content
+     * Keeps the typewriter active while waiting for new content to arrive.
      */
     shouldWaitForContent?: boolean;
     /**
-     * The speed of the animation. Use the TypewriterSpeed enum for this prop.
+     * The speed of the animation. Use the `TypewriterSpeed` enum for this prop.
      */
     speed?: TypewriterSpeed | number;
     /**
@@ -109,7 +118,7 @@ export type TypewriterProps = {
      */
     startDelay?: TypewriterDelay;
     /**
-     * The style of the typewriter text element
+     * Inline styles for the visible text element.
      */
     textStyle?: CSSPropertiesWithVars;
 };

package/lib/types/components/typewriter/useTypewriterAnimation.d.ts

@@ -0,0 +1,30 @@
+import type { MouseEvent, MutableRefObject } from 'react';
+import { CursorType } from '../../types/cursor';
+export type UseTypewriterAnimationOptions = {
+    areMultipleChildrenGiven: boolean;
+    charactersCount: number;
+    cursorType: CursorType;
+    onAdvanceText?: VoidFunction;
+    nextTextDelay: number;
+    onResetAnimationEnd?: VoidFunction;
+    onResetAnimationStart?: VoidFunction;
+    onTypingAnimationEnd?: VoidFunction;
+    onTypingAnimationStart?: VoidFunction;
+    resetDelay: number;
+    resetSpeed: number;
+    shouldUseResetAnimation: boolean;
+    shouldWaitForContent?: boolean;
+    speed: number;
+    startDelay: number;
+    textContentLength: number;
+    autoSpeedRef: MutableRefObject<number | undefined>;
+    autoStepsRef: MutableRefObject<number>;
+};
+export type UseTypewriterAnimationResult = {
+    handleClick: (event: MouseEvent) => void;
+    isResetAnimationActive: boolean;
+    shownCharCount: number;
+    shouldPreventBlinkingCursor: boolean;
+};
+declare const useTypewriterAnimation: ({ areMultipleChildrenGiven, charactersCount, cursorType, onAdvanceText, nextTextDelay, onResetAnimationEnd, onResetAnimationStart, onTypingAnimationEnd, onTypingAnimationStart, resetDelay, resetSpeed, shouldUseResetAnimation, shouldWaitForContent, speed, startDelay, textContentLength, autoSpeedRef, autoStepsRef, }: UseTypewriterAnimationOptions) => UseTypewriterAnimationResult;
+export default useTypewriterAnimation;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@chayns-components/typewriter",
-    "version": "5.0.52",
+    "version": "5.0.53-alpha.1",
     "description": "A set of beautiful React components for developing your own applications with chayns.",
     "sideEffects": false,
     "browserslist": [
@@ -83,5 +83,5 @@
     "publishConfig": {
         "access": "public"
     },
-    "gitHead": "3a3e55778a44dd7ecac7aa4d8acb6ab4eebea1c0"
+    "gitHead": "69820ddb1ce53b30c0c6dba7b03c89f04e7b89cf"
 }