Align logic more closely with the original nprogress

Author: tanem

.github/copilot-instructions.md

@@ -7,7 +7,7 @@ changes agent behaviour and cannot be inferred from the codebase or tooling.
 
 TypeScript React library providing a slim progress bar primitive via three
 patterns: `useNProgress` hook, `NProgress` render-props component, and
-`withNProgress` HOC. Exports logic only — no rendering. All exports go through
+`withNProgress` HOC. Exports logic only, not rendering. All exports go through
 `src/index.tsx`. Types live in `src/types.ts`.
 
 ## Key Commands
@@ -22,14 +22,15 @@ npm run format    # fix lint and formatting
 
 ### Comments
 
-- Use `//` line comments only — never `/* */` or `/** */`
+- Use `//` line comments only, never `/* */` or `/** */`
 - Explain _why_, not _what_; wrap at 80 characters
+- End every comment with a full stop, even single-line comments
 
 ### Language
 
 Use **New Zealand English** in all user-facing text, variable names, and
 comments (e.g. "colour", "behaviour", "organisation"). Standardised API names
-(`color`, `textAlign`) are fixed — leave them unchanged.
+(`color`, `textAlign`) are fixed: leave them unchanged.
 
 ```javascript
 const progressColour = '#0066cc'
@@ -49,9 +50,9 @@ subject, no trailing period, blank line between subject and body.
 
 Managed by Renovate (`config:js-lib` preset):
 
-- `devDependencies` — pinned exact versions (no `^` or `~`)
-- `dependencies` — caret ranges (`^`)
-- `peerDependencies` — explicit OR ranges (e.g. `^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0`)
+- `devDependencies`: pinned exact versions (no `^` or `~`)
+- `dependencies`: caret ranges (`^`)
+- `peerDependencies`: explicit OR ranges (e.g. `^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0`)
 - Do **not** add `allowedVersions` to `renovate.json` without a documented reason
 
 ## Testing
@@ -85,7 +86,23 @@ needed but test on CodeSandbox before merging.
 Do not bump vite, @vitejs/plugin-react, next, or typescript in examples
 beyond the versions in the reference templates.
 
+## Writing Style
+
+- Avoid marketing or promotional language. State facts plainly.
+- Follow best practices for technical writing: be clear, direct, and
+  concise.
+- Avoid em dashes. Use colons, commas, or separate sentences instead.
+- Use present tense and active voice where practical.
+- Keep sentences short. One idea per sentence.
+
 ## Versioning
 
-Strict semver — no breaking changes without a major version bump, including
+Strict semver: no breaking changes without a major version bump, including
 technical refactors.
+
+## Documentation
+
+- After each code change, update all related docs and markdown files
+  (README.md, MIGRATION.md, example READMEs, etc.) in the same pass.
+- Do not manually modify CHANGELOG.md. It is auto-generated during
+  release.

MIGRATION.md

@@ -1,5 +1,35 @@
 # Migrating
 
+## v6.0.0
+
+Trickle pacing was adjusted to more closely match the original
+[nprogress](https://github.com/rstacruz/nprogress) behaviour.
+
+### `incrementDuration` default changed from `800` to `200`
+
+The previous default of `800` meant each trickle took roughly one second
+(animation wait plus increment delay). The new default of `200` matches
+the original library's `trickleSpeed` and results in faster trickle
+pacing.
+
+**Action required:** if you were relying on the old default pacing,
+explicitly pass `incrementDuration={800}` to restore the previous
+behaviour.
+
+### Intermediate progress updates no longer wait for `animationDuration`
+
+Non-completion `set()` calls previously waited `animationDuration`
+(200 ms) before advancing the internal queue. This wait has been
+removed for intermediate updates so that only `incrementDuration`
+controls trickle pacing. The completion path (`set(1)`) still waits
+`animationDuration` before marking the bar as finished, giving
+consumers time to animate the bar to 100% before it disappears.
+
+**Action required:** none in most cases. If your rendering code relied
+on intermediate progress updates being spaced at least
+`animationDuration` apart, you may need to adjust your
+transition/animation timing.
+
 ## v5.0.0
 
 The prop-types package is no longer required for using the UMD builds.

README.md

@@ -111,7 +111,7 @@ render(<Enhanced isAnimating />, document.getElementById('root'))
 **Props**
 
 - `animationDuration` - _Optional_ Number indicating the animation duration in `ms`. Defaults to `200`.
-- `incrementDuration` - _Optional_ Number indicating the length of time between progress bar increments in `ms`. Defaults to `800`.
+- `incrementDuration` - _Optional_ Number indicating the length of time between progress bar increments in `ms`. Defaults to `200`.
 - `isAnimating` - _Optional_ Boolean indicating if the progress bar is animating. Defaults to `false`.
 - `minimum` - _Optional_ Number between `0` and `1` indicating the minimum value of the progress bar. Defaults to `0.08`.
 

src/createTimeout.ts

@@ -1,13 +1,18 @@
+// Uses requestAnimationFrame rather than setTimeout for smoother animation
+// timing. Note that rAF is throttled or paused in background tabs, so progress
+// will stall when the tab is hidden and resume when it regains focus.
 export const createTimeout = () => {
   let handle: number | undefined
 
   const cancel = (): void => {
-    if (handle) {
+    if (handle !== undefined) {
       window.cancelAnimationFrame(handle)
     }
   }
 
   const schedule = (callback: () => void, delay: number): void => {
+    cancel()
+
     let deltaTime
     let start: number | undefined
     const frame: FrameRequestCallback = (time) => {

src/useNProgress.tsx

@@ -1,4 +1,4 @@
-import { useCallback, useEffect, useRef } from 'react'
+import { useCallback, useRef } from 'react'
 
 import { clamp } from './clamp'
 import { createQueue } from './createQueue'
@@ -12,6 +12,11 @@ import { useUpdateEffect } from './useUpdateEffect'
 /* istanbul ignore next */
 const noop = () => undefined
 
+// State includes a `sideEffect` callback that bridges imperative queue
+// operations into React's declarative model. Each `setState` stores a callback;
+// `useUpdateEffect` fires it after React commits the update. This lets the
+// queue drive animations and schedule follow-up work without breaking React's
+// rendering lifecycle.
 const initialState: {
   isFinished: boolean
   progress: number
@@ -24,7 +29,7 @@ const initialState: {
 
 export const useNProgress = ({
   animationDuration = 200,
-  incrementDuration = 800,
+  incrementDuration = 200,
   isAnimating = false,
   minimum = 0.08,
 }: Options = {}): {
@@ -51,6 +56,10 @@ export const useNProgress = ({
     (n: number) => {
       n = clamp(n, minimum, 1)
 
+      // Unlike the original nprogress `done()`, completion does not include a
+      // random progress jump before animating to 1. This keeps the primitive
+      // predictable; consumers can set a higher progress value before stopping
+      // the animation if they want that effect.
       if (n === 1) {
         cleanup()
 
@@ -73,7 +82,7 @@ export const useNProgress = ({
         setState({
           isFinished: false,
           progress: n,
-          sideEffect: () => timeout.current?.schedule(next, animationDuration),
+          sideEffect: next,
         })
       })
     },
@@ -85,6 +94,10 @@ export const useNProgress = ({
   }, [get, set])
 
   const start = useCallback(() => {
+    // The original nprogress calls set(0) - which clamps to `minimum` - before
+    // the first trickle. Here, the first trickle starts from increment(0) =
+    // 0.1, so the bar appears at max(0.1, minimum) rather than exactly
+    // `minimum`. The difference is negligible at the default minimum of 0.08.
     const work = () => {
       trickle()
       queue.current?.enqueue((next) => {
@@ -98,14 +111,8 @@ export const useNProgress = ({
     work()
   }, [incrementDuration, queue, timeout, trickle])
 
-  const savedTrickle = useRef<() => void>(noop)
-
   const sideEffect = get().sideEffect
 
-  useEffect(() => {
-    savedTrickle.current = trickle
-  })
-
   useEffectOnce(() => {
     if (isAnimating) {
       start()

test/NProgress.spec.tsx

@@ -22,3 +22,21 @@ test('receives render props', () => {
   expect(isFinished).toBe(true)
   expect(progress).toBe(0)
 })
+
+test('passes animating state to children', () => {
+  let isFinished
+  let progress
+
+  render(
+    <NProgress isAnimating>
+      {(props) => {
+        isFinished = props.isFinished
+        progress = props.progress
+        return <></>
+      }}
+    </NProgress>,
+  )
+
+  expect(isFinished).toBe(false)
+  expect(progress).toBe(0.1)
+})

test/increment.spec.ts

@@ -1,10 +1,27 @@
 import { increment } from '../src/increment'
 
-test('increments corrrectly', () => {
+test('increments correctly', () => {
+  // Below zero.
   expect(increment(-1)).toBeCloseTo(0)
+
+  // [0, 0.2): amount = 0.1.
   expect(increment(0)).toBeCloseTo(0.1)
+  expect(increment(0.19)).toBeCloseTo(0.29)
+
+  // [0.2, 0.5): amount = 0.04.
   expect(increment(0.2)).toBeCloseTo(0.24)
+  expect(increment(0.49)).toBeCloseTo(0.53)
+
+  // [0.5, 0.8): amount = 0.02.
   expect(increment(0.5)).toBeCloseTo(0.52)
+  expect(increment(0.79)).toBeCloseTo(0.81)
+
+  // [0.8, 0.99): amount = 0.005.
   expect(increment(0.8)).toBeCloseTo(0.805)
+  expect(increment(0.989)).toBeCloseTo(0.994)
+
+  // >= 0.99: amount = 0, clamped to 0.994.
+  expect(increment(0.99)).toBeCloseTo(0.99)
+  expect(increment(0.994)).toBeCloseTo(0.994)
   expect(increment(1)).toBeCloseTo(0.994)
 })

test/queue.spec.ts

@@ -1,9 +1,14 @@
 import { createQueue } from '../src/createQueue'
 
-const { clear, enqueue } = createQueue()
-
 jest.useFakeTimers()
 
+let clear: ReturnType<typeof createQueue>['clear']
+let enqueue: ReturnType<typeof createQueue>['enqueue']
+
+beforeEach(() => {
+  ;({ clear, enqueue } = createQueue())
+})
+
 test('starts running when the first callback is pushed onto the queue', () => {
   const mockFn = jest.fn()
 

test/timeout.spec.ts

@@ -14,7 +14,7 @@ test('executes a callback after a delay', () => {
   schedule(mockFn, 10)
   mockRaf.step()
   mockRaf.step()
-  expect(mockFn).toHaveBeenCalled()
+  expect(mockFn).toHaveBeenCalledTimes(1)
 })
 
 test('can cancel a pending callback', () => {
@@ -25,3 +25,15 @@ test('can cancel a pending callback', () => {
   mockRaf.step()
   expect(mockFn).not.toHaveBeenCalled()
 })
+
+test('cancels a pending callback when rescheduling', () => {
+  const mockFn1 = jest.fn()
+  const mockFn2 = jest.fn()
+  schedule(mockFn1, 10)
+  mockRaf.step()
+  schedule(mockFn2, 10)
+  mockRaf.step()
+  mockRaf.step()
+  expect(mockFn1).not.toHaveBeenCalled()
+  expect(mockFn2).toHaveBeenCalled()
+})

test/useNProgress.spec.ts

@@ -58,8 +58,6 @@ test('increments correctly', () => {
   act(() => {
     mockRaf.step()
     mockRaf.step({ time: 201 })
-    mockRaf.step()
-    mockRaf.step({ time: 801 })
   })
 
   expect(result.current).toEqual({
@@ -117,8 +115,6 @@ test('correctly restarts a finished animation', () => {
   act(() => {
     mockRaf.step()
     mockRaf.step({ time: 201 })
-    mockRaf.step()
-    mockRaf.step({ time: 801 })
   })
 
   expect(result.current).toEqual({
@@ -129,3 +125,68 @@ test('correctly restarts a finished animation', () => {
 
   unmount()
 })
+
+test('respects custom minimum', () => {
+  const { result, unmount } = renderHook(() =>
+    useNProgress({ isAnimating: true, minimum: 0.3 }),
+  )
+
+  // increment(0) = 0.1, clamped to minimum of 0.3.
+  expect(result.current.progress).toBe(0.3)
+
+  unmount()
+})
+
+test('respects custom animationDuration', () => {
+  const { result, rerender, unmount } = renderHook(
+    ({ isAnimating }) => useNProgress({ animationDuration: 500, isAnimating }),
+    { initialProps: { isAnimating: true } },
+  )
+
+  expect(result.current.animationDuration).toBe(500)
+
+  rerender({ isAnimating: false })
+
+  // Completion waits animationDuration (500ms) before isFinished.
+  act(() => {
+    mockRaf.step()
+    mockRaf.step({ time: 300 })
+  })
+
+  expect(result.current.isFinished).toBe(false)
+
+  act(() => {
+    mockRaf.step()
+    mockRaf.step({ time: 501 })
+  })
+
+  expect(result.current.isFinished).toBe(true)
+
+  unmount()
+})
+
+test('respects custom incrementDuration', () => {
+  const { result, unmount } = renderHook(() =>
+    useNProgress({ incrementDuration: 500, isAnimating: true }),
+  )
+
+  expect(result.current.progress).toBe(0.1)
+
+  // Not enough time for a second trickle.
+  act(() => {
+    mockRaf.step()
+    mockRaf.step({ time: 201 })
+  })
+
+  expect(result.current.progress).toBe(0.1)
+
+  // Enough time for the second trickle.
+  act(() => {
+    mockRaf.step()
+    mockRaf.step({ time: 501 })
+  })
+
+  expect(result.current.progress).toBe(0.2)
+
+  unmount()
+})