Skip to content

Commit

Permalink
feat: onFinish prop for timer mode
Browse files Browse the repository at this point in the history
  • Loading branch information
@rgommezz
rgommezz committed Jan 12, 2023
1 parent b69535c commit 3332d07
Show file tree
Hide file tree
Showing 6 changed files with 1,326 additions and 1,294 deletions.
26 changes: 14 additions & 12 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@
A React Native Stopwatch/Timer component that empowers **reanimated worklets** to smoothly animate the digits change. Cross-platform, performant, with all **layout animations executed on the UI thread at 60FPS**. Compatible with Expo.

It works in two modes:

- **Stopwatch**: The timer starts counting up from 0 (default).
- **Timer**: The timer starts counting down from a given time. Use the `initialTimeInMs` prop to activate this mode.

Expand Down Expand Up @@ -58,19 +59,20 @@ return <StopwatchTimer ref={stopwatchTimerRef} />;

## Props

| Name | Required | Type | Description |
|----------------------|----------|------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `animationDuration` | no | `number` | The enter/exit animation duration in milliseconds of a digit. Defaults to `80` |
| `animationDelay` | no | `number` | The enter/exit animation delay in milliseconds of a digit. Defaults to `0` |
| `animationDistance` | no | `number` | The enter/exit animation vertical distance in dp of a digit. Defaults to `120` |
| `containerStyle` | no | `StyleProp<ViewStyle>` | The style of the stopwatch/timer `View` container |
| `digitStyle` | no | `StyleProp<TextStyle>` | Extra style applied to each digit, excluding separators (`:` and `,`). This is useful if the `fontFamily` has different widths per digit, to avoid an unpleasant fluctuation of the total component width as it runs. Check the example app where this is used on iOS's default San Francisco font, that presents this issue. |
| `initialTimeInMs` | no | `number` | If you want to **use it as a timer**, set this value |
| `leadingZeros` | no | `1` or `2` | The number of zeros for the minutes. Defaults to 1 |
| Name | Required | Type | Description |
|----------------------| -------- |-----------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `animationDuration` | no | `number` | The enter/exit animation duration in milliseconds of a digit. Defaults to `80` |
| `animationDelay` | no | `number` | The enter/exit animation delay in milliseconds of a digit. Defaults to `0` |
| `animationDistance` | no | `number` | The enter/exit animation vertical distance in dp of a digit. Defaults to `120` |
| `containerStyle` | no | `StyleProp<ViewStyle>` | The style of the stopwatch/timer `View` container |
| `digitStyle` | no | `StyleProp<TextStyle>` | Extra style applied to each digit, excluding separators (`:` and `,`). This is useful if the `fontFamily` has different widths per digit, to avoid an unpleasant fluctuation of the total component width as it runs. Check the example app where this is used on iOS's default San Francisco font, that presents this issue. |
| `initialTimeInMs` | no | `number` | If you want to **use it as a timer**, set this value |
| `leadingZeros` | no | `1` or `2` | The number of zeros for the minutes. Defaults to 1 |
| `enterAnimationType` | no | `'slide-in-up' or 'slide-in-down'` | Whether the new digit should enter from the top or the bottom |
| `separatorStyle` | no | `StyleProp<TextStyle>` | Extra style applied only to separators. In this case, the colon (`:`) and the comma (`,`) |
| `textCharStyle` | no | `StyleProp<TextStyle>` | The style applied to each individual character of the stopwatch/timer |
| `trailingZeros` | no | `0`, `1` or `2` | If `0`, the component will only display seconds and minutes. If `1`, the component will display seconds, minutes and hundredth of ms. If `2`, the component will display seconds, minutes and tens of ms. Defaults to `1` |
| `separatorStyle` | no | `StyleProp<TextStyle>` | Extra style applied only to separators. In this case, the colon (`:`) and the comma (`,`) |
| `onFinish` | no | `() => void` | Callback executed when the timer reaches 0 (only when working in timer mode and `initialTimeInMs` prop is provided) |
| `textCharStyle` | no | `StyleProp<TextStyle>` | The style applied to each individual character of the stopwatch/timer |
| `trailingZeros` | no | `0`, `1` or `2` | If `0`, the component will only display seconds and minutes. If `1`, the component will display seconds, minutes and hundredth of ms. If `2`, the component will display seconds, minutes and tens of ms. Defaults to `1` |

## Methods

Expand Down
1 change: 0 additions & 1 deletion example/src/App.tsx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,6 @@ export default function App() {
})}
textCharStyle={styles.stopWatchChar}
trailingZeros={2}
initialTimeInMs={30 * 1000}
/>
<View style={styles.buttonsContainer}>
{/** @ts-ignore */}
Expand Down
4 changes: 4 additions & 0 deletions package.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -56,6 +56,7 @@
"@react-native-community/eslint-config": "^3.0.2",
"@release-it/conventional-changelog": "^5.0.0",
"@types/jest": "^28.1.2",
"@types/lodash.throttle": "^4.1.7",
"@types/react": "~17.0.21",
"@types/react-native": "0.70.0",
"commitlint": "^17.0.2",
Expand Down Expand Up @@ -157,5 +158,8 @@
}
]
]
},
"dependencies": {
"lodash.throttle": "^4.1.1"
}
}
27 changes: 16 additions & 11 deletions src/StopwatchTimer.tsx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,19 +22,19 @@ const DEFAULT_ANIMATION_DURATION = 200;

export interface StopwatchTimerProps {
/**
* The enter/exit animation duration in milliseconds of a stopwatch digit.
* The enter/exit animation duration in milliseconds of a digit.
*/
animationDuration?: number;
/**
* The enter/exit animation delay in milliseconds of a stopwatch digit.
* The enter/exit animation delay in milliseconds of a digit.
*/
animationDelay?: number;
/**
* The enter/exit animation distance in dp of a stopwatch digit.
* The enter/exit animation distance in dp of a digit.
*/
animationDistance?: number;
/**
* The style of the stopwatch View container.
* The style of the component View container.
*/
containerStyle?: StyleProp<ViewStyle>;
/**
Expand All @@ -53,32 +53,36 @@ export interface StopwatchTimerProps {
* Whether the new digit should enter from the top or the bottom.
*/
enterAnimationType?: 'slide-in-up' | 'slide-in-down';
/**
* Callback executed when the timer reaches 0 (only when working in timer mode and initialTimeInMs is provided).
*/
onFinish?: () => void;
/**
* Extra style applied only to separators. In this case, the colon (:) and the comma (,)
*/
separatorStyle?: StyleProp<TextStyle>;
/**
* The style applied to each individual character of the stopwatch.
* The style applied to each individual character of the stopwatch/timer.
*/
textCharStyle?: StyleProp<TextStyle>;
/**
* If 0, the stopwatch will only display seconds and minutes.
* If 1, the stopwatch will display seconds, minutes and hundredth of ms.
* If 0, the component will only display seconds and minutes.
* If 1, the component will display seconds, minutes and hundredth of ms.
*/
trailingZeros?: 0 | 1 | 2;
}

export interface StopwatchTimerMethods {
/**
* Starts the stopwatch or resumes it if paused. Has no effect if the stopwatch is already running.
* Starts the stopwatch/timer or resumes it if paused. Has no effect if the stopwatch/timer is already running.
*/
play: () => void;
/**
* Pauses the stopwatch and returns the current elapsed time in milliseconds.
* Pauses the stopwatch/timer and returns the current elapsed time in milliseconds.
*/
pause: () => number;
/**
* Resets the stopwatch.
* Resets the stopwatch/timer.
*/
reset: () => void;
/**
Expand All @@ -97,6 +101,7 @@ function Stopwatch(
digitStyle,
initialTimeInMs,
leadingZeros = 1,
onFinish,
separatorStyle,
textCharStyle,
trailingZeros = 1,
Expand All @@ -112,7 +117,7 @@ function Stopwatch(
reset,
pause,
getSnapshot,
} = useTimer(initialTimeInMs);
} = useTimer(initialTimeInMs, onFinish);

useImperativeHandle(ref, () => ({
play,
Expand Down
16 changes: 13 additions & 3 deletions src/useTimer.ts
View file
Original file line number Diff line number Diff line change
@@ -1,13 +1,22 @@
import { useEffect, useRef, useState } from 'react';
import { useEffect, useMemo, useRef, useState } from 'react';
import throttle from 'lodash.throttle';

/**
* A custom hook that handles the state for the timer
*/
const useTimer = (initialTimeInMs: number = 0) => {
const useTimer = (
initialTimeInMs: number = 0,
onFinish: () => void = () => null
) => {
const [elapsedInMs, setElapsedInMs] = useState(0);
const startTime = useRef<number | null>(null);
const pausedTime = useRef<number | null>(null);
const intervalId = useRef<NodeJS.Timer | null>(null);
const throttledOnFinish = useMemo(
() => throttle(onFinish, 100, { trailing: false }),
// eslint-disable-next-line react-hooks/exhaustive-deps
[]
);

useEffect(() => {
// Ensure that the timer is reset when the initialTimeInMs changes
Expand All @@ -20,8 +29,9 @@ const useTimer = (initialTimeInMs: number = 0) => {
if (initialTimeInMs > 0 && elapsedInMs >= initialTimeInMs) {
removeInterval();
setElapsedInMs(initialTimeInMs);
throttledOnFinish();
}
}, [elapsedInMs, initialTimeInMs]);
}, [elapsedInMs, initialTimeInMs, throttledOnFinish]);

function getSnapshot() {
return Math.abs(initialTimeInMs - elapsedInMs);
Expand Down
Loading

0 comments on commit 3332d07

Please sign in to comment.