ui/_docs/02_document/modules/src__hooks__useDebounce.md

Module: src/hooks/useDebounce.ts

Source: src/hooks/useDebounce.ts (12 lines) Topo batch: B1 (leaf)

Purpose

Generic React hook that delays propagation of a rapidly-changing value to its consumers, used to throttle search inputs against the backend.

Public interface

export function useDebounce<T>(value: T, delay: number): T

Returns the latest value only after delay milliseconds have elapsed without any further change. Generic in T, so callers can debounce strings, numbers, or any reference value (referential identity matters; see notes).

Internal logic

useState<T>(value) for the debounced output; useEffect registers a setTimeout(setDebounced, delay) and returns a clearTimeout cleanup. The effect re-runs whenever value or delay changes — each new input value cancels the pending timeout from the previous render and starts a fresh one.

Dependencies

• Internal: none.
• External: react (useState, useEffect).

Consumers (intra-repo)

• src/features/annotations/MediaList.tsx — debounces the media-name search input.
• src/features/dataset/DatasetPage.tsx — debounces the dataset name-search filter (specified as 400ms in _docs/ui_design/README.md §"Dataset Explorer", but the actual delay is set by the caller).

Data models

None.

Configuration

None.

External integrations

None.

Security

None.

Tests

None.

Notes / open questions

• The hook compares values by referential equality (useEffect deps array). Passing a fresh object literal each render — e.g. useDebounce({ q }, 300) — would re-trigger the timer endlessly. Current callers pass primitives only; safe.
• No "leading edge" / "trailing edge" / "max wait" knobs. Adequate for the two current consumers; if/when richer behaviour is needed, prefer useDebouncedCallback from a library over extending this module.