react-native-glitter 1.0.3 → 1.0.5

package/README.md

@@ -167,6 +167,9 @@ function ControlledGlitter() {
 | `iterations` | `number` | `-1` | Number of animation cycles (-1 for infinite) |
 | `onAnimationStart` | `() => void` | - | Callback when animation starts |
 | `onAnimationComplete` | `() => void` | - | Callback when all iterations complete |
+| `testID` | `string` | - | Test ID for e2e testing |
+| `accessibilityLabel` | `string` | - | Accessibility label for screen readers |
+| `accessible` | `boolean` | `true` | Whether the component is accessible |
 
 ## Examples
 
@@ -261,6 +264,44 @@ function ControlledGlitter() {
 </Glitter>
 ```
 
+## Ref API
+
+You can control the animation programmatically using a ref:
+
+```tsx
+import { useRef } from 'react';
+import { Glitter, type GlitterRef } from 'react-native-glitter';
+
+function MyComponent() {
+  const glitterRef = useRef<GlitterRef>(null);
+
+  const handleStart = () => glitterRef.current?.start();
+  const handleStop = () => glitterRef.current?.stop();
+  const handleRestart = () => glitterRef.current?.restart();
+  const checkStatus = () => console.log(glitterRef.current?.isAnimating());
+
+  return (
+    <>
+      <Glitter ref={glitterRef} active={false}>
+        <View style={styles.box} />
+      </Glitter>
+      <Button title="Start" onPress={handleStart} />
+      <Button title="Stop" onPress={handleStop} />
+      <Button title="Restart" onPress={handleRestart} />
+    </>
+  );
+}
+```
+
+### Ref Methods
+
+| Method | Return | Description |
+|--------|--------|-------------|
+| `start()` | `void` | Start the shimmer animation |
+| `stop()` | `void` | Stop the shimmer animation |
+| `restart()` | `void` | Restart the animation from the beginning |
+| `isAnimating()` | `boolean` | Check if animation is currently running |
+
 ## TypeScript
 
 This library is written in TypeScript and includes type definitions:
@@ -269,6 +310,7 @@ This library is written in TypeScript and includes type definitions:
 import {
   Glitter,
   type GlitterProps,
+  type GlitterRef,
   type GlitterMode,
   type GlitterPosition,
   type GlitterDirection,

package/lib/module/index.js

@@ -1,5 +1,5 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useEffect, useRef, useState, useCallback, useMemo, memo, } from 'react';
+import { useEffect, useRef, useState, useCallback, useMemo, memo, useImperativeHandle, forwardRef, } from 'react';
 import { View, Animated, StyleSheet, Easing, } from 'react-native';
 function generateGlitterOpacities(count, peak = 1) {
     const opacities = [];
@@ -52,7 +52,7 @@ const HEIGHT_MULTIPLIER = 1.5;
 const NORMAL_FADE_RATIO = (HEIGHT_MULTIPLIER - 1) / HEIGHT_MULTIPLIER / 2;
 const ANIMATED_SEGMENTS = generateVerticalSegments(0.25);
 const NORMAL_SEGMENTS = generateVerticalSegments(NORMAL_FADE_RATIO);
-function GlitterComponent({ children, duration = 1500, delay = 400, color = 'rgba(255, 255, 255, 0.8)', angle = 20, shimmerWidth = 60, active = true, style, easing, mode = 'normal', position = 'center', direction = 'left-to-right', iterations = -1, onAnimationStart, onAnimationComplete, }) {
+function GlitterComponent({ children, duration = 1500, delay = 400, color = 'rgba(255, 255, 255, 0.8)', angle = 20, shimmerWidth = 60, active = true, style, easing, mode = 'normal', position = 'center', direction = 'left-to-right', iterations = -1, onAnimationStart, onAnimationComplete, testID, accessibilityLabel, accessible = true, }, ref) {
     const animatedValue = useRef(new Animated.Value(0)).current;
     const [containerWidth, setContainerWidth] = useState(0);
     const [containerHeight, setContainerHeight] = useState(0);
@@ -68,6 +68,23 @@ function GlitterComponent({ children, duration = 1500, delay = 400, color = 'rgb
         currentIterationRef.current?.stop();
         currentIterationRef.current = null;
     }, []);
+    const restartAnimation = useCallback(() => {
+        stopAnimation();
+        animatedValue.setValue(0);
+        // Trigger re-render to start animation
+        setContainerWidth((prev) => prev);
+    }, [stopAnimation, animatedValue]);
+    useImperativeHandle(ref, () => ({
+        start: () => {
+            if (!isAnimatingRef.current && containerWidth > 0) {
+                // Force start by triggering the effect
+                setContainerWidth((prev) => prev);
+            }
+        },
+        stop: stopAnimation,
+        restart: restartAnimation,
+        isAnimating: () => isAnimatingRef.current,
+    }), [stopAnimation, restartAnimation, containerWidth]);
     const startAnimation = useCallback(() => {
         if (!active || containerWidth === 0)
             return;
@@ -198,7 +215,7 @@ function GlitterComponent({ children, duration = 1500, delay = 400, color = 'rgb
                 : [],
         },
     ], [layerWidth, lineHeight, isAnimated, transformOriginOffset, scaleY]);
-    return (_jsxs(View, { style: [styles.container, style], onLayout: onLayout, children: [children, active && containerWidth > 0 && containerHeight > 0 && (_jsx(Animated.View, { style: shimmerContainerStyle, pointerEvents: "none", children: _jsx(View, { style: rotationWrapperStyle, children: shimmerLayers.map((layer, layerIndex) => (_jsx(Animated.View, { style: getShimmerLineStyle(layer.position), children: segments.map((segment, vIndex) => (_jsx(View, { style: [
+    return (_jsxs(View, { style: [styles.container, style], onLayout: onLayout, testID: testID, accessibilityLabel: accessibilityLabel, accessible: accessible, children: [children, active && containerWidth > 0 && containerHeight > 0 && (_jsx(Animated.View, { style: shimmerContainerStyle, pointerEvents: "none", children: _jsx(View, { style: rotationWrapperStyle, children: shimmerLayers.map((layer, layerIndex) => (_jsx(Animated.View, { style: getShimmerLineStyle(layer.position), children: segments.map((segment, vIndex) => (_jsx(View, { style: [
                                 styles.segment,
                                 {
                                     height: lineHeight * segment.heightRatio,
@@ -231,5 +248,6 @@ const styles = StyleSheet.create({
         width: '100%',
     },
 });
-export const Glitter = memo(GlitterComponent);
+const ForwardedGlitter = forwardRef(GlitterComponent);
+export const Glitter = memo(ForwardedGlitter);
 export default Glitter;

package/lib/typescript/src/index.d.ts

@@ -1,4 +1,4 @@
-import { type ReactNode, type ReactElement } from 'react';
+import { type ReactNode } from 'react';
 import { type StyleProp, type ViewStyle } from 'react-native';
 export type GlitterMode = 'normal' | 'expand' | 'shrink';
 export type GlitterPosition = 'top' | 'center' | 'bottom';
@@ -19,7 +19,23 @@ export interface GlitterProps {
     iterations?: number;
     onAnimationStart?: () => void;
     onAnimationComplete?: () => void;
+    /** Test ID for e2e testing */
+    testID?: string;
+    /** Accessibility label for screen readers */
+    accessibilityLabel?: string;
+    /** Whether the component is accessible (default: true) */
+    accessible?: boolean;
 }
-declare function GlitterComponent({ children, duration, delay, color, angle, shimmerWidth, active, style, easing, mode, position, direction, iterations, onAnimationStart, onAnimationComplete, }: GlitterProps): ReactElement;
-export declare const Glitter: import("react").MemoExoticComponent<typeof GlitterComponent>;
+/** Ref methods exposed by Glitter component */
+export interface GlitterRef {
+    /** Start the shimmer animation */
+    start: () => void;
+    /** Stop the shimmer animation */
+    stop: () => void;
+    /** Restart the shimmer animation from the beginning */
+    restart: () => void;
+    /** Check if animation is currently running */
+    isAnimating: () => boolean;
+}
+export declare const Glitter: import("react").NamedExoticComponent<GlitterProps & import("react").RefAttributes<GlitterRef>>;
 export default Glitter;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-glitter",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "A beautiful shimmer/glitter effect component for React Native. Add a sparkling diagonal shine animation to any component!",
   "main": "./lib/module/index.js",
   "types": "./lib/typescript/src/index.d.ts",

package/src/index.tsx

@@ -5,8 +5,11 @@ import {
   useCallback,
   useMemo,
   memo,
+  useImperativeHandle,
+  forwardRef,
   type ReactNode,
   type ReactElement,
+  type ForwardedRef,
 } from 'react';
 import {
   View,
@@ -40,6 +43,24 @@ export interface GlitterProps {
   iterations?: number;
   onAnimationStart?: () => void;
   onAnimationComplete?: () => void;
+  /** Test ID for e2e testing */
+  testID?: string;
+  /** Accessibility label for screen readers */
+  accessibilityLabel?: string;
+  /** Whether the component is accessible (default: true) */
+  accessible?: boolean;
+}
+
+/** Ref methods exposed by Glitter component */
+export interface GlitterRef {
+  /** Start the shimmer animation */
+  start: () => void;
+  /** Stop the shimmer animation */
+  stop: () => void;
+  /** Restart the shimmer animation from the beginning */
+  restart: () => void;
+  /** Check if animation is currently running */
+  isAnimating: () => boolean;
 }
 
 function generateGlitterOpacities(count: number, peak: number = 1): number[] {
@@ -108,23 +129,29 @@ const NORMAL_FADE_RATIO = (HEIGHT_MULTIPLIER - 1) / HEIGHT_MULTIPLIER / 2;
 const ANIMATED_SEGMENTS = generateVerticalSegments(0.25);
 const NORMAL_SEGMENTS = generateVerticalSegments(NORMAL_FADE_RATIO);
 
-function GlitterComponent({
-  children,
-  duration = 1500,
-  delay = 400,
-  color = 'rgba(255, 255, 255, 0.8)',
-  angle = 20,
-  shimmerWidth = 60,
-  active = true,
-  style,
-  easing,
-  mode = 'normal',
-  position = 'center',
-  direction = 'left-to-right',
-  iterations = -1,
-  onAnimationStart,
-  onAnimationComplete,
-}: GlitterProps): ReactElement {
+function GlitterComponent(
+  {
+    children,
+    duration = 1500,
+    delay = 400,
+    color = 'rgba(255, 255, 255, 0.8)',
+    angle = 20,
+    shimmerWidth = 60,
+    active = true,
+    style,
+    easing,
+    mode = 'normal',
+    position = 'center',
+    direction = 'left-to-right',
+    iterations = -1,
+    onAnimationStart,
+    onAnimationComplete,
+    testID,
+    accessibilityLabel,
+    accessible = true,
+  }: GlitterProps,
+  ref: ForwardedRef<GlitterRef>
+): ReactElement {
   const animatedValue = useRef(new Animated.Value(0)).current;
   const [containerWidth, setContainerWidth] = useState(0);
   const [containerHeight, setContainerHeight] = useState(0);
@@ -145,6 +172,29 @@ function GlitterComponent({
     currentIterationRef.current = null;
   }, []);
 
+  const restartAnimation = useCallback(() => {
+    stopAnimation();
+    animatedValue.setValue(0);
+    // Trigger re-render to start animation
+    setContainerWidth((prev) => prev);
+  }, [stopAnimation, animatedValue]);
+
+  useImperativeHandle(
+    ref,
+    () => ({
+      start: () => {
+        if (!isAnimatingRef.current && containerWidth > 0) {
+          // Force start by triggering the effect
+          setContainerWidth((prev) => prev);
+        }
+      },
+      stop: stopAnimation,
+      restart: restartAnimation,
+      isAnimating: () => isAnimatingRef.current,
+    }),
+    [stopAnimation, restartAnimation, containerWidth]
+  );
+
   const startAnimation = useCallback(() => {
     if (!active || containerWidth === 0) return;
 
@@ -332,7 +382,13 @@ function GlitterComponent({
   );
 
   return (
-    <View style={[styles.container, style]} onLayout={onLayout}>
+    <View
+      style={[styles.container, style]}
+      onLayout={onLayout}
+      testID={testID}
+      accessibilityLabel={accessibilityLabel}
+      accessible={accessible}
+    >
       {children}
       {active && containerWidth > 0 && containerHeight > 0 && (
         <Animated.View style={shimmerContainerStyle} pointerEvents="none">
@@ -389,6 +445,7 @@ const styles = StyleSheet.create({
   },
 });
 
-export const Glitter = memo(GlitterComponent);
+const ForwardedGlitter = forwardRef(GlitterComponent);
+export const Glitter = memo(ForwardedGlitter);
 
 export default Glitter;