@timekeeper-countdown/react 0.1.3 → 0.2.0

package/README.md

@@ -182,6 +182,21 @@ it('counts down when the fake clock advances', async () => {
 
 The hook handles cleanup automatically, so tests do not need to destroy the engine manually.
 
+### Available Testing Utilities
+
+The core package ships several helpers under `@timekeeper-countdown/core/testing-utils`:
+
+- `createFakeTimeProvider(options?)` — controllable clock with `advance()`, `set()`, `reset()`, and `getTime()`.
+- `toTimeProvider(fake)` — adapts a fake clock to the `TimeProvider` interface.
+- `buildSnapshot(options?)` — fabricates `CountdownSnapshot` objects for unit tests without running an engine.
+- `buildSnapshotSequence(options?)` — generates an array of snapshots simulating a countdown progression.
+- `assertSnapshotState(snapshot, expected, message?)` — throws if the snapshot is not in the expected `TimerState`.
+- `assertSnapshotCompleted(snapshot, message?)` — throws if the countdown is not completed.
+- `assertRemainingSeconds(snapshot, expected, tolerance?, message?)` — throws if remaining seconds differ beyond tolerance.
+- `TimerState` — re-exported for convenience (`IDLE`, `RUNNING`, `PAUSED`, `STOPPED`).
+
+See the [core README](https://github.com/eagle-head/timekeeper-countdown/tree/main/packages/core#testing-utilities) or [API Reference](https://eagle-head.github.io/timekeeper-countdown/#/api-reference) for full signatures and examples.
+
 ---
 
 ## Multiple Timers

package/dist/index.cjs

@@ -0,0 +1 @@
+'use strict';var react=require('react'),core=require('@timekeeper-countdown/core');function D(a,h={}){let{autoStart:C=false,tickIntervalMs:c,timeProvider:S,onSnapshot:p,onStateChange:i,onError:d}=h,u=react.useRef({onSnapshot:p,onStateChange:i,onError:d}),l=react.useRef(null),[r,g]=react.useState(()=>core.buildSnapshot(a,a,core.TimerState.IDLE));react.useEffect(()=>{u.current={onSnapshot:p,onStateChange:i,onError:d};},[d,p,i]);let w=react.useMemo(()=>({tickIntervalMs:c,timeProvider:S}),[c,S]);react.useEffect(()=>{let n=true,o=core.CountdownEngine(a,{...w,onSnapshot:e=>{n&&g(e),u.current.onSnapshot?.(e);},onStateChange:(e,y)=>{u.current.onStateChange?.(e,y);},onError:e=>{u.current.onError?.(e);}});return l.current=o,g(o.getSnapshot()),C&&o.start(),()=>{n=false,o.destroy(),l.current=null;}},[C,w,a]);let t=react.useCallback((n,o)=>{let e=l.current;return e?n(e):o},[]),E=react.useCallback(()=>t(n=>n.start(),false),[t]),b=react.useCallback(()=>t(n=>n.pause(),false),[t]),O=react.useCallback(()=>t(n=>n.resume(),false),[t]),R=react.useCallback(()=>t(n=>n.stop(),false),[t]),U=react.useCallback(n=>{t(o=>o.setSeconds(n),void 0);},[t]),x=react.useCallback(n=>t(o=>o.reset(n),false),[t]);return {snapshot:r,state:r.state,totalSeconds:r.totalSeconds,parts:r.parts,isRunning:r.isRunning,isCompleted:r.isCompleted,start:E,pause:b,resume:O,reset:x,stop:R,setSeconds:U}}exports.useCountdown=D;

package/dist/index.d.cts

@@ -0,0 +1,27 @@
+import { CountdownEngineOptions, CountdownSnapshot, TimerState } from '@timekeeper-countdown/core';
+
+interface UseCountdownOptions extends Omit<CountdownEngineOptions, 'onSnapshot' | 'onStateChange' | 'onError'> {
+    autoStart?: boolean;
+    onSnapshot?: CountdownEngineOptions['onSnapshot'];
+    onStateChange?: CountdownEngineOptions['onStateChange'];
+    onError?: CountdownEngineOptions['onError'];
+}
+interface UseCountdownControls {
+    start: () => boolean;
+    pause: () => boolean;
+    resume: () => boolean;
+    reset: (nextInitialSeconds?: number) => boolean;
+    stop: () => boolean;
+    setSeconds: (value: number) => void;
+}
+interface UseCountdownResult extends UseCountdownControls {
+    snapshot: CountdownSnapshot;
+    state: TimerState;
+    totalSeconds: number;
+    parts: CountdownSnapshot['parts'];
+    isRunning: boolean;
+    isCompleted: boolean;
+}
+declare function useCountdown(initialSeconds: number, options?: UseCountdownOptions): UseCountdownResult;
+
+export { type UseCountdownControls, type UseCountdownOptions, type UseCountdownResult, useCountdown };

package/dist/index.js

@@ -1 +1 @@
-import {useRef,useState,useEffect,useMemo,useCallback}from'react';import {CountdownEngine}from'@timekeeper-countdown/core';var M=(a,p)=>{let u=CountdownEngine(a,{tickIntervalMs:p.tickIntervalMs,timeProvider:p.timeProvider}),i=u.getSnapshot();return u.destroy(),i};function P(a,p={}){let{autoStart:u=false,tickIntervalMs:i,timeProvider:c,onSnapshot:l,onStateChange:C,onError:S}=p,d=useRef({onSnapshot:l,onStateChange:C,onError:S}),g=useRef(null),[r,m]=useState(()=>M(a,{tickIntervalMs:i,timeProvider:c}));useEffect(()=>{d.current={onSnapshot:l,onStateChange:C,onError:S};},[S,l,C]);let w=useMemo(()=>({tickIntervalMs:i,timeProvider:c}),[i,c]);useEffect(()=>{let n=true,e=CountdownEngine(a,{...w,onSnapshot:o=>{n&&m(o),d.current.onSnapshot?.(o);},onStateChange:(o,y)=>{d.current.onStateChange?.(o,y);},onError:o=>{d.current.onError?.(o);}});return g.current=e,m(e.getSnapshot()),u&&e.start(),()=>{n=false,e.destroy(),g.current=null;}},[u,w,a]);let t=useCallback((n,e)=>{let o=g.current;return o?n(o):e},[]),E=useCallback(()=>t(n=>n.start(),false),[t]),v=useCallback(()=>t(n=>n.pause(),false),[t]),O=useCallback(()=>t(n=>n.resume(),false),[t]),U=useCallback(()=>t(n=>n.stop(),false),[t]),I=useCallback(n=>t(e=>e.setSeconds(n),void 0),[t]),R=useCallback(n=>t(e=>e.reset(n),false),[t]);return {snapshot:r,state:r.state,totalSeconds:r.totalSeconds,parts:r.parts,isRunning:r.isRunning,isCompleted:r.isCompleted,start:E,pause:v,resume:O,reset:R,stop:U,setSeconds:I}}export{P as useCountdown};
+import {useRef,useState,useEffect,useMemo,useCallback}from'react';import {buildSnapshot,TimerState,CountdownEngine}from'@timekeeper-countdown/core';function D(a,h={}){let{autoStart:C=false,tickIntervalMs:c,timeProvider:S,onSnapshot:p,onStateChange:i,onError:d}=h,u=useRef({onSnapshot:p,onStateChange:i,onError:d}),l=useRef(null),[r,g]=useState(()=>buildSnapshot(a,a,TimerState.IDLE));useEffect(()=>{u.current={onSnapshot:p,onStateChange:i,onError:d};},[d,p,i]);let w=useMemo(()=>({tickIntervalMs:c,timeProvider:S}),[c,S]);useEffect(()=>{let n=true,o=CountdownEngine(a,{...w,onSnapshot:e=>{n&&g(e),u.current.onSnapshot?.(e);},onStateChange:(e,y)=>{u.current.onStateChange?.(e,y);},onError:e=>{u.current.onError?.(e);}});return l.current=o,g(o.getSnapshot()),C&&o.start(),()=>{n=false,o.destroy(),l.current=null;}},[C,w,a]);let t=useCallback((n,o)=>{let e=l.current;return e?n(e):o},[]),E=useCallback(()=>t(n=>n.start(),false),[t]),b=useCallback(()=>t(n=>n.pause(),false),[t]),O=useCallback(()=>t(n=>n.resume(),false),[t]),R=useCallback(()=>t(n=>n.stop(),false),[t]),U=useCallback(n=>{t(o=>o.setSeconds(n),void 0);},[t]),x=useCallback(n=>t(o=>o.reset(n),false),[t]);return {snapshot:r,state:r.state,totalSeconds:r.totalSeconds,parts:r.parts,isRunning:r.isRunning,isCompleted:r.isCompleted,start:E,pause:b,resume:O,reset:x,stop:R,setSeconds:U}}export{D as useCountdown};

package/package.json

@@ -1,7 +1,17 @@
 {
   "name": "@timekeeper-countdown/react",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "description": "React adapter for the Timekeeper Countdown engine",
+  "author": "Eduardo Kohn",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/eagle-head/timekeeper-countdown.git"
+  },
+  "homepage": "https://eagle-head.github.io/timekeeper-countdown/",
+  "bugs": {
+    "url": "https://github.com/eagle-head/timekeeper-countdown/issues"
+  },
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -9,7 +19,8 @@
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
     }
   },
   "files": [
@@ -33,7 +44,7 @@
     "react": ">=17.0.0"
   },
   "dependencies": {
-    "@timekeeper-countdown/core": "^0.1.3"
+    "@timekeeper-countdown/core": "^0.2.0"
   },
   "devDependencies": {
     "@testing-library/jest-dom": "^6.4.2",