Description

The ChangesListener component is a utility for observing changes in a reactive value within your React application. It leverages a custom hook (useValue) to access a dynamic value and triggers a provided listener function whenever this value changes. Importantly, ChangesListener itself does not render any DOM elements, making it a purely functional component for side-effect management based on value changes.

Key Features:

• Change Detection: It efficiently detects changes in the value returned by the useValue hook.
• Targeted Listening (Optional): For object types, you can specify a field prop to listen for changes in a specific property instead of the entire object.
• Non-Rendering: It doesn't add any extra nodes to your component tree.
• Clear Separation of Concerns: It isolates the logic for reacting to value changes, promoting cleaner and more maintainable components.

Use Cases:

• Performing actions when a specific piece of state updates.
• Triggering animations or transitions based on data changes.
• Synchronizing data with external systems or APIs when a relevant value is modified.
• Implementing custom logging or analytics based on state transitions.

How it Works:

1. It accepts a useValue prop, which should be a function (typically a custom hook) that returns the reactive value you want to observe.
2. It uses the provided useValue hook to get the current value.
3. It optionally accepts a field prop. If provided and the value is an object, it will only track changes to the property specified by this field.
4. It utilizes the usePrevious hook to store the previous value.
5. In each render, it compares the current value (or the specific property if a field is provided) with the previous value.
6. If a change is detected, it calls the listener function in an effect after the render commit, passing the new value (or the new value of the specific property).

Design Rationale:

• The listener runs in an effect to keep side effects out of the render phase.
• This avoids StrictMode double-calls that can happen when doing work in render.
• Running after commit is safer for side-effectful callbacks (logging, analytics, network calls) and still keeps the component renderless.
• The field prop only applies to object values; omit it when watching primitives.

Example Usage:

Watching for changes in a primitive value:

import { useState } from 'react';
import { ChangesListener } from 'react-changes-listener'

function Counter() {
  const [count, setCount] = useState(0);

  return (
    <>
      <button onClick={() => setCount(c => c + 1)}>Increment</button>
      <ChangesListener
        useValue={() => count}
        listener={(newCount) => console.log('Count changed to', newCount)}
      />
    </>
  );
}

Watching for changes in a state value:

import { useState } from 'react';
import { ChangesListener } from 'react-changes-listener'

function MyComponent() {
  const [count, setCount] = useState(0);

  const handleCountChange = (newCount: number) => {
    console.log(`Count changed to: ${newCount}`);
    // Perform other actions based on the new count
  };

  const useCurrentCount = () => count;

  return (
    <div>
      <p>Count: {count}</p>
      <button onClick={() => setCount(c => c + 1)}>Increment</button>
      <ChangesListener listener={handleCountChange} useValue={useCurrentCount} />
    </div>
  );
}

Watching for changes in a specific property of an object:

import { useState } from 'react';
import { ChangesListener } from 'react-changes-listener'

interface User {
  name: string;
  age: number;
}

function UserProfile() {
  const [user, setUser] = useState<User>({ name: 'Alice', age: 30 });

  const handleNameChange = (newName: string) => {
    console.log(`Name changed to: ${newName}`);
    // Update user profile in the backend, etc.
  };

  const useCurrentUser = () => user;

  return (
    <div>
      <p>Name: {user.name}</p>
      <p>Age: {user.age}</p>
      <button onClick={() => setUser(prev => ({ ...prev, name: 'Bob' }))}>Change Name</button>
      <ChangesListener<User> listener={handleNameChange} useValue={useCurrentUser} field="name" />
    </div>
  );
}

This component provides a flexible and efficient way to respond to value changes within your React applications without cluttering your rendering logic with side-effect management.