@timekeeper-countdown/react 0.1.4 → 0.3.0

package/README.md

@@ -100,6 +100,7 @@ interface UseCountdownResult {
 ```
 
 - All control methods mirror the engine and return `false` for invalid transitions.
+- `setSeconds(value)` and `reset(value)` validate their argument and **throw** on an invalid value (negative, non-integer, `NaN`, or `Infinity`), matching the engine.
 - `snapshot` is stable per render; derive memoised values with `useMemo` if needed.
 - `totalSeconds`, `parts`, `isRunning`, and `isCompleted` are re-exposed for convenience.
 
@@ -182,6 +183,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
@@ -221,13 +237,9 @@ function MultiStageTimer() {
 
 ## Contributing
 
-Bug reports and pull requests are welcome. Please read the [repository guidelines](https://github.com/eagle-head/timekeeper-countdown/blob/main/AGENTS.md) and check your work with:
+We welcome contributions! Please read our [Contributing Guide](https://github.com/eagle-head/timekeeper-countdown/blob/main/CONTRIBUTING.md) to get started.
 
-```bash
-npm run lint --workspaces
-npm run test --workspaces
-npm run typecheck --workspaces
-```
+By participating in this project, you agree to abide by our [Code of Conduct](https://github.com/eagle-head/timekeeper-countdown/blob/main/CODE_OF_CONDUCT.md).
 
 ---
 

package/dist/index.cjs

@@ -1 +1 @@
-'use strict';var react=require('react'),core=require('@timekeeper-countdown/core');var M=(a,p)=>{let u=core.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=react.useRef({onSnapshot:l,onStateChange:C,onError:S}),g=react.useRef(null),[r,m]=react.useState(()=>M(a,{tickIntervalMs:i,timeProvider:c}));react.useEffect(()=>{d.current={onSnapshot:l,onStateChange:C,onError:S};},[S,l,C]);let w=react.useMemo(()=>({tickIntervalMs:i,timeProvider:c}),[i,c]);react.useEffect(()=>{let n=true,e=core.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=react.useCallback((n,e)=>{let o=g.current;return o?n(o):e},[]),E=react.useCallback(()=>t(n=>n.start(),false),[t]),v=react.useCallback(()=>t(n=>n.pause(),false),[t]),O=react.useCallback(()=>t(n=>n.resume(),false),[t]),U=react.useCallback(()=>t(n=>n.stop(),false),[t]),I=react.useCallback(n=>t(e=>e.setSeconds(n),void 0),[t]),R=react.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}}exports.useCountdown=P;
+'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.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.4",
+  "version": "0.3.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",
@@ -23,6 +33,7 @@
     "test": "vitest run",
     "test:ui": "vitest --ui",
     "test:coverage": "vitest run --coverage",
+    "test:mutation": "stryker run",
     "typecheck": "tsc --noEmit",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
@@ -34,11 +45,12 @@
     "react": ">=17.0.0"
   },
   "dependencies": {
-    "@timekeeper-countdown/core": "^0.1.4"
+    "@timekeeper-countdown/core": "^0.3.0"
   },
   "devDependencies": {
-    "@testing-library/jest-dom": "^6.4.2",
-    "@testing-library/react": "^15.0.0",
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.2",
     "@types/react": "^18.2.55",
     "@types/react-dom": "^18.2.19",
     "react": "^18.3.1",
@@ -52,6 +64,9 @@
     "typescript"
   ],
   "sideEffects": false,
+  "engines": {
+    "node": ">=22"
+  },
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
     "access": "public"