@nlabs/arkhamjs-utils-react

React Hooks and Utilities for ArkhamJS - Seamless React integration with powerful hooks for state management, component sizing, and window dimensions.

🚀 Features

• 🎯 Flux Integration Hooks - useFlux, useFluxState, useFluxDispatch, useFluxListener
• 📏 Component Size Hooks - useComponentSize, useRefSize for responsive components
• 🖥️ Window Size Hooks - useWindowSize for viewport-aware components
• 🔧 FluxProvider - React Context provider for ArkhamJS
• ⚡ TypeScript Support - First-class TypeScript with full type safety
• 🌲 Tree-shakable - Only import what you need

📦 Installation

npm install @nlabs/arkhamjs-utils-react

Peer Dependencies:

• @nlabs/arkhamjs ^3.26.0
• react (any version)

🎯 Quick Start

Setup FluxProvider

import React from 'react';
import { Flux } from '@nlabs/arkhamjs';
import { FluxProvider } from '@nlabs/arkhamjs-utils-react';

// Initialize Flux
Flux.init({
  name: 'my-app',
  stores: [UserStore, CartStore]
});

const App = (): JSX.Element => {
  return (
    <FluxProvider>
      <UserList />
      <CartSummary />
    </FluxProvider>
  );
};

Use Flux Hooks

import React from 'react';
import { useFluxState, useFluxDispatch } from '@nlabs/arkhamjs-utils-react';

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

const UserList = (): JSX.Element => {
  // Get state with automatic re-renders
  const users = useFluxState<User[]>('user.users', []);

  // Get dispatch function
  const dispatch = useFluxDispatch();

  const addUser = (user: User): void => {
    dispatch({ type: 'ADD_USER', user });
  };

  return (
    <div>
      {users.map(user => (
        <div key={user.id}>{user.name}</div>
      ))}
      <button onClick={() => addUser({ id: 1, name: 'John' })}>
        Add User
      </button>
    </div>
  );
};

🔧 API Reference

Flux Integration Hooks

useFlux()

Get the Flux instance and dispatch function.

import { useFlux } from '@nlabs/arkhamjs-utils-react';

const MyComponent = (): JSX.Element => {
  const { flux, dispatch } = useFlux();

  // Access Flux methods
  const state = flux.getState('user');

  // Dispatch actions
  dispatch({ type: 'UPDATE_USER', user });
};

useFluxState(path, defaultValue?)

Subscribe to state changes with automatic re-renders.

import { useFluxState } from '@nlabs/arkhamjs-utils-react';

interface User {
  name: string;
  email: string;
}

const UserProfile = (): JSX.Element => {
  // Subscribe to specific state path
  const user = useFluxState<User | null>('user.current', null);
  const isLoading = useFluxState<boolean>('user.loading', false);

  if (isLoading) return <div>Loading...</div>;
  if (!user) return <div>No user found</div>;

  return <div>Welcome, {user.name}!</div>;
};

useFluxDispatch()

Get the dispatch function for dispatching actions.

import { useFluxDispatch } from '@nlabs/arkhamjs-utils-react';

interface UserData {
  name: string;
  email: string;
}

const AddUserForm = (): JSX.Element => {
  const dispatch = useFluxDispatch();

  const handleSubmit = (userData: UserData): void => {
    dispatch({ type: 'ADD_USER', user: userData });
  };

  return <form onSubmit={handleSubmit}>...</form>;
};

useFluxListener(event, callback)

Listen to specific Flux events.

import { useFluxListener } from '@nlabs/arkhamjs-utils-react';

const NotificationComponent = (): JSX.Element => {
  const [notifications, setNotifications] = useState<string[]>([]);

  // Listen to user events
  useFluxListener('USER_ADDED', (action: { type: string; user: { name: string } }) => {
    setNotifications(prev => [...prev, `User ${action.user.name} added`]);
  });

  return (
    <div>
      {notifications.map((msg, i) => (
        <div key={i}>{msg}</div>
      ))}
    </div>
  );
};

useFluxValue(path, defaultValue?)

Get a single value from state without re-renders on other changes.

import { useFluxValue } from '@nlabs/arkhamjs-utils-react';

const UserCount = (): JSX.Element => {
  const userCount = useFluxValue<number>('user.count', 0);

  return <div>Total users: {userCount}</div>;
};

Component Size Hooks

useComponentSize(ref)

Track component dimensions with ResizeObserver.

import React, { useRef } from 'react';
import { useComponentSize } from '@nlabs/arkhamjs-utils-react';

const ResponsiveComponent = (): JSX.Element => {
  const ref = useRef<HTMLDivElement>(null);
  const { width, height } = useComponentSize(ref);

  return (
    <div ref={ref}>
      <p>Width: {width}px, Height: {height}px</p>
    </div>
  );
};

useRefSize(ref)

Alternative size hook with different API.

import React, { useRef } from 'react';
import { useRefSize } from '@nlabs/arkhamjs-utils-react';

const SizeTracker = (): JSX.Element => {
  const ref = useRef<HTMLDivElement>(null);
  const size = useRefSize(ref);

  return (
    <div ref={ref}>
      <p>Size: {size.width} x {size.height}</p>
    </div>
  );
};

Window Size Hooks

useWindowSize()

Track window dimensions.

import { useWindowSize } from '@nlabs/arkhamjs-utils-react';

const WindowInfo = (): JSX.Element => {
  const { width, height } = useWindowSize();

  return (
    <div>
      <p>Window: {width} x {height}</p>
      <p>Is Mobile: {width < 768}</p>
    </div>
  );
};

🎯 Advanced Usage

Custom Hook Composition

import { useFluxState, useFluxDispatch } from '@nlabs/arkhamjs-utils-react';

interface User {
  id: number;
  name: string;
  email: string;
}

const useUserManagement = () => {
  const users = useFluxState<User[]>('user.users', []);
  const currentUser = useFluxState<User | null>('user.current', null);
  const dispatch = useFluxDispatch();

  const addUser = (user: Omit<User, 'id'>): void => {
    const newUser = { ...user, id: Date.now() };
    dispatch({ type: 'ADD_USER', user: newUser });
  };

  const updateUser = (id: number, updates: Partial<User>): void => {
    dispatch({ type: 'UPDATE_USER', id, updates });
  };

  const deleteUser = (id: number): void => {
    dispatch({ type: 'DELETE_USER', id });
  };

  return {
    users,
    currentUser,
    addUser,
    updateUser,
    deleteUser
  };
};

const UserManagement = (): JSX.Element => {
  const { users, addUser, updateUser, deleteUser } = useUserManagement();

  return (
    <div>
      {users.map(user => (
        <div key={user.id}>
          {user.name}
          <button onClick={() => updateUser(user.id, { name: 'Updated' })}>
            Update
          </button>
          <button onClick={() => deleteUser(user.id)}>Delete</button>
        </div>
      ))}
      <button onClick={() => addUser({ name: 'New User', email: '[email protected]' })}>
        Add User
      </button>
    </div>
  );
};

Performance Optimization

import React, { useCallback, useMemo } from 'react';
import { useFluxState, useFluxDispatch } from '@nlabs/arkhamjs-utils-react';

const OptimizedUserList = (): JSX.Element => {
  const users = useFluxState<User[]>('user.users', []);
  const dispatch = useFluxDispatch();

  // Memoize expensive computations
  const activeUsers = useMemo(() =>
    users.filter(user => user.status === 'active'),
    [users]
  );

  // Memoize callbacks
  const handleUserClick = useCallback((userId: number) => {
    dispatch({ type: 'SELECT_USER', id: userId });
  }, [dispatch]);

  return (
    <div>
      {activeUsers.map(user => (
        <div key={user.id} onClick={() => handleUserClick(user.id)}>
          {user.name}
        </div>
      ))}
    </div>
  );
};

🔧 Configuration

FluxProvider Options

import { FluxProvider } from '@nlabs/arkhamjs-utils-react';

const App = (): JSX.Element => {
  return (
    <FluxProvider
      debug={process.env.NODE_ENV === 'development'}
      enableStrictMode={true}
    >
      <YourApp />
    </FluxProvider>
  );
};

🎯 Use Cases

E-commerce Application

const ShoppingCart = (): JSX.Element => {
  const cartItems = useFluxState<CartItem[]>('cart.items', []);
  const total = useFluxState<number>('cart.total', 0);
  const dispatch = useFluxDispatch();

  const addToCart = (product: Product): void => {
    dispatch({ type: 'ADD_TO_CART', product });
  };

  const removeFromCart = (productId: number): void => {
    dispatch({ type: 'REMOVE_FROM_CART', productId });
  };

  return (
    <div>
      <h2>Shopping Cart ({cartItems.length} items)</h2>
      {cartItems.map(item => (
        <div key={item.id}>
          {item.name} - ${item.price}
          <button onClick={() => removeFromCart(item.id)}>Remove</button>
        </div>
      ))}
      <div>Total: ${total}</div>
    </div>
  );
};

Real-time Dashboard

const Dashboard = (): JSX.Element => {
  const metrics = useFluxState<Metrics>('dashboard.metrics', {});
  const { width, height } = useWindowSize();
  const isMobile = width < 768;

  // Listen for real-time updates
  useFluxListener('METRICS_UPDATED', (action) => {
    console.log('Metrics updated:', action.metrics);
  });

  return (
    <div className={isMobile ? 'mobile-dashboard' : 'desktop-dashboard'}>
      <MetricCard title="Users" value={metrics.userCount} />
      <MetricCard title="Revenue" value={metrics.revenue} />
      <MetricCard title="Orders" value={metrics.orderCount} />
    </div>
  );
};

🔗 Related Packages

• @nlabs/arkhamjs - Core Flux framework
• @nlabs/arkhamjs-middleware-logger - Logging middleware
• @nlabs/arkhamjs-middleware-devtools - DevTools integration
• @nlabs/arkhamjs-storage-browser - Browser storage

📚 Documentation

• ArkhamJS Documentation - Complete API reference
• React Integration Guide - Detailed React setup
• TypeScript Guide - TypeScript best practices

🤝 Community & Support

• 💬 Discord Community - Chat with other developers
• 🐛 GitHub Issues - Report bugs and request features
• 📝 Examples - Complete working examples

📄 License

MIT License - see LICENSE file for details.

Start building reactive React applications with ArkhamJS today! 🚀