@geee-be/react-utils 1.3.0 → 1.3.1

package/.copilot-instructions.md

@@ -0,0 +1,371 @@
+# @geee-be/react-utils - Copilot Instructions
+
+## Package Overview
+A collection of reusable React hooks and utility functions designed to enhance React applications with common functionality patterns. This package provides lightweight, well-tested utilities that work seamlessly with modern React patterns, SSR frameworks, and TypeScript. Focuses on performance, type safety, and developer experience.
+
+## Package Structure
+```
+src/
+├── helpers/                    # Utility functions and components
+│   ├── index.ts               # Helper exports
+│   ├── client-only.tsx        # Client-side only rendering wrapper
+│   ├── monitor.tsx            # Performance monitoring utilities
+│   ├── ripple.ts             # Material Design ripple effect
+│   └── sub-component.tsx      # Component composition helpers
+├── hooks/                     # Custom React hooks
+│   ├── index.ts               # Hook exports
+│   ├── state.util.ts          # State management utilities
+│   ├── use-broadcast-channel.ts # Cross-tab communication
+│   ├── use-history-state.ts   # Browser history state management
+│   ├── use-is-client.ts       # Client-side detection
+│   ├── use-is-mobile.ts       # Mobile device detection
+│   ├── use-local-state.ts     # Enhanced local state management
+│   └── use-local-state.stories.tsx # Storybook examples
+└── index.ts                   # Package main export
+```
+
+## Package Structure
+```
+src/
+├── helpers/          # Utility functions and components
+│   ├── client-only.tsx    # Client-side only rendering wrapper
+│   ├── monitor.tsx        # Performance monitoring utilities
+│   ├── ripple.ts         # Material Design ripple effect
+│   └── sub-component.tsx  # Component composition helpers
+└── hooks/            # Custom React hooks
+    ├── state.util.ts           # State management utilities
+    ├── use-broadcast-channel.ts # Cross-tab communication
+    ├── use-history-state.ts    # Browser history state management
+    ├── use-is-client.ts        # Client-side detection
+    ├── use-is-mobile.ts        # Mobile device detection
+    └── use-local-state.ts      # Enhanced local state management
+```
+
+## Key Dependencies
+- **@uidotdev/usehooks**: Additional utility hooks
+- **React 18+**: Modern React features and patterns
+
+## Hook Implementation Patterns
+
+### State Management Hooks
+- `useLocalState`: Enhanced useState with localStorage persistence and cross-tab sync
+- `useHistoryState`: State management with browser history integration
+- State utilities for common patterns and transformations
+
+### Environment Detection Hooks
+- `useIsClient`: Detect client-side rendering vs SSR (prevents hydration mismatches)
+- `useIsMobile`: Responsive mobile device detection with customizable breakpoints
+
+### Communication Hooks
+- `useBroadcastChannel`: Cross-tab/window communication using Broadcast Channel API
+
+### Performance Considerations
+- All hooks use proper dependency arrays and cleanup
+- Memoization implemented where beneficial for performance
+- Automatic event listener cleanup on component unmount
+- SSR-safe initialization patterns to prevent hydration issues
+
+## Helper Functions
+
+### Component Utilities
+- `ClientOnly`: Wrapper for client-side only rendering
+- `SubComponent`: Utilities for component composition patterns
+- `Monitor`: Performance monitoring and debugging tools
+
+### Effects and Interactions
+- `ripple`: Material Design ripple effect implementation
+
+## Development Patterns
+
+### Hook Implementation
+- Follow React hooks rules and conventions
+- Use TypeScript for type safety
+- Implement proper cleanup in useEffect
+- Support SSR/client-side rendering differences
+- Provide sensible default values
+
+### Utility Functions
+- Pure functions where possible
+- Proper error handling
+- TypeScript strict mode compliance
+- Minimal external dependencies
+
+## TypeScript Support
+- Full TypeScript definitions for all exports
+- Generic types for flexible hook APIs
+- Proper inference for hook return types
+- Strict type checking enabled
+
+## Usage Examples
+
+### Enhanced State Management
+```typescript
+import { useLocalState, useHistoryState } from '@geee-be/react-utils';
+
+// Persistent state with localStorage
+function UserPreferences() {
+  const [settings, setSettings] = useLocalState('user-settings', {
+    theme: 'light',
+    language: 'en',
+    notifications: true
+  });
+
+  const toggleTheme = () => {
+    setSettings(prev => ({
+      ...prev,
+      theme: prev.theme === 'light' ? 'dark' : 'light'
+    }));
+  };
+
+  return <button onClick={toggleTheme}>Theme: {settings.theme}</button>;
+}
+
+// Browser history integration
+function SearchPage() {
+  const [query, setQuery] = useHistoryState('search', '');
+  const [filters, setFilters] = useHistoryState('filters', {});
+
+  return (
+    <div>
+      <input
+        value={query}
+        onChange={(e) => setQuery(e.target.value)}
+        placeholder="Search..."
+      />
+      {/* Filters persist in browser history */}
+    </div>
+  );
+}
+```
+
+### SSR-Safe Environment Detection
+```typescript
+import { useIsClient, useIsMobile } from '@geee-be/react-utils';
+
+function ResponsiveComponent() {
+  const isClient = useIsClient();
+  const isMobile = useIsMobile(768); // Custom breakpoint
+
+  // Prevent hydration mismatch
+  if (!isClient) {
+    return <div>Loading...</div>;
+  }
+
+  return (
+    <div className={isMobile ? 'mobile-layout' : 'desktop-layout'}>
+      <h1>Welcome</h1>
+      {isMobile ? <MobileNavigation /> : <DesktopNavigation />}
+    </div>
+  );
+}
+```
+
+### Cross-Tab Communication
+```typescript
+import { useBroadcastChannel } from '@geee-be/react-utils';
+
+function MultiTabSync() {
+  const [message, postMessage] = useBroadcastChannel('app-sync');
+
+  useEffect(() => {
+    if (message) {
+      console.log('Received from another tab:', message);
+      // Handle cross-tab state synchronization
+    }
+  }, [message]);
+
+  const notifyOtherTabs = () => {
+    postMessage({
+      type: 'USER_LOGIN',
+      user: { id: 1, name: 'John' },
+      timestamp: Date.now()
+    });
+  };
+
+  return <button onClick={notifyOtherTabs}>Login & Sync</button>;
+}
+```
+
+### Utility Components
+```typescript
+import { ClientOnly, ripple } from '@geee-be/react-utils';
+
+// Client-only rendering
+function App() {
+  return (
+    <div>
+      <h1>Server + Client Rendered</h1>
+      <ClientOnly>
+        <ExpensiveClientComponent />
+        <BrowserAPIComponent />
+      </ClientOnly>
+    </div>
+  );
+}
+
+// Material Design ripple effect
+function RippleButton() {
+  const handleClick = (event) => {
+    ripple(event.currentTarget, {
+      duration: 600,
+      color: 'rgba(59, 130, 246, 0.3)'
+    });
+  };
+
+  return (
+    <button
+      onClick={handleClick}
+      className="relative overflow-hidden bg-blue-500 text-white px-4 py-2 rounded"
+    >
+      Click for Ripple
+    </button>
+  );
+}
+```
+
+## Build Configuration
+- **TypeScript Compilation**: Direct tsc build to `dist/`
+- **Type Exports**: Source types exported directly (`src/index.ts`)
+- **Development Mode**: Watch mode with `tsc --watch`
+- **ES Modules**: Modern ESM output format
+
+## Testing & Development
+- **Storybook Integration**: Stories for demonstrating hook usage
+- **Type Safety**: Strict TypeScript configuration
+- **Linting**: Biome for code quality
+- **Development Server**: Watch mode for rapid iteration
+
+## Best Practices
+
+### Hook Development Guidelines
+- Keep hooks focused on single responsibilities
+- Follow React hooks rules and conventions
+- Use TypeScript for comprehensive type safety
+- Implement proper cleanup in useEffect hooks
+- Handle edge cases (SSR, cleanup, errors gracefully)
+- Provide sensible default values for all parameters
+- Consider performance implications and optimize re-renders
+- Support both development and production environments
+
+### API Design Principles
+- Provide TypeScript definitions for all public APIs
+- Use proper dependency arrays in useEffect
+- Implement consistent return patterns across similar hooks
+- Support generic types for flexible, reusable APIs
+- Follow React's built-in hook naming conventions
+- Document complex hook behaviors with JSDoc comments
+
+### Performance Optimization
+- Use useCallback and useMemo appropriately
+- Implement proper event listener cleanup
+- Avoid unnecessary re-renders through careful state management
+- Use refs for values that don't trigger re-renders
+- Implement debouncing for expensive operations
+- Consider memory usage in long-running applications
+
+### Error Handling
+- Provide graceful fallbacks for failed operations
+- Handle browser API unavailability
+- Use try-catch blocks for potentially failing operations
+- Log errors appropriately for debugging
+- Provide meaningful error messages for developers
+- Support error boundaries where applicable
+
+### Testing Strategies
+- Test hooks in isolation using React Testing Library
+- Verify SSR compatibility with server-side rendering tests
+- Test browser API integration with appropriate mocks
+- Validate TypeScript types compile correctly
+- Test edge cases and error conditions
+- Ensure cleanup functions work properly
+
+## Framework-Specific Usage
+
+### Next.js Integration
+```typescript
+// App Router (app directory)
+import { useLocalState, useIsClient } from '@geee-be/react-utils';
+
+export default function ClientComponent() {
+  const isClient = useIsClient();
+  const [data, setData] = useLocalState('app-data', null);
+
+  if (!isClient) return <div>Loading...</div>;
+  return <div>{data}</div>;
+}
+
+// Pages Router
+import { useIsMobile } from '@geee-be/react-utils';
+
+export default function Page() {
+  const isMobile = useIsMobile();
+  return <div>{isMobile ? 'Mobile' : 'Desktop'}</div>;
+}
+```
+
+### Performance Monitoring
+```typescript
+import { Monitor } from '@geee-be/react-utils';
+
+// Use Monitor utilities for performance tracking
+function App() {
+  useEffect(() => {
+    Monitor.trackRender('App');
+    return () => Monitor.trackUnmount('App');
+  }, []);
+
+  return <div>App Content</div>;
+}
+```
+
+## SSR Considerations
+
+### Hydration Safety Patterns
+All hooks are designed to work with server-side rendering frameworks without hydration mismatches:
+
+```typescript
+// Safe pattern for SSR
+function ThemeProvider({ children }) {
+  const [theme, setTheme] = useLocalState('theme', 'light');
+  const isClient = useIsClient();
+
+  // Use fallback during SSR to prevent hydration mismatch
+  const currentTheme = isClient ? theme : 'light';
+
+  return (
+    <div data-theme={currentTheme} className={currentTheme}>
+      {children}
+    </div>
+  );
+}
+
+// Safe mobile detection
+function ResponsiveLayout() {
+  const isClient = useIsClient();
+  const isMobile = useIsMobile();
+
+  // Always render the same structure on server
+  if (!isClient) {
+    return <div className="responsive-container">Loading...</div>;
+  }
+
+  return (
+    <div className="responsive-container">
+      {isMobile ? <MobileLayout /> : <DesktopLayout />}
+    </div>
+  );
+}
+```
+
+### Framework Integration
+- **Next.js**: Full compatibility with App Router and Pages Router
+- **Remix**: Works with Remix's SSR patterns and hydration
+- **Gatsby**: Compatible with static site generation
+- **Vite SSR**: Supports Vite's SSR implementation
+- **Client-only apps**: Works perfectly in SPA environments
+
+### Browser API Safety
+- Hooks gracefully handle browser API availability
+- Proper feature detection prevents runtime errors
+- Fallback behavior for server environments
+- Progressive enhancement patterns supported

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @geee-be/react-utils
 
+## 1.3.1
+
+### Patch Changes
+
+- 1cdc182: Tidy ups
+
 ## 1.3.0
 
 ### Minor Changes

package/README.md

@@ -0,0 +1,413 @@
+# @geee-be/react-utils
+
+A collection of powerful, type-safe React hooks and utility functions designed to enhance modern React applications. Built with TypeScript, SSR compatibility, and performance in mind.
+
+[![npm version](https://badge.fury.io/js/%40geee-be%2Freact-utils.svg)](https://www.npmjs.com/package/@geee-be/react-utils)
+[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## ✨ Features
+
+- 🪝 **Custom React Hooks** - Enhanced state management and utility hooks
+- 🔒 **Type Safe** - Full TypeScript support with comprehensive type definitions
+- 🌐 **SSR Compatible** - Works seamlessly with Next.js and other SSR frameworks
+- ⚡ **Performance Focused** - Optimized for minimal re-renders and memory usage
+- 🧩 **Modular** - Tree-shakeable exports for optimal bundle size
+- 🔧 **Browser API Wrappers** - Safe abstractions for modern browser features
+- 📱 **Device Detection** - Responsive utilities for different environments
+- 🔄 **State Persistence** - Local storage integration with sync capabilities
+
+## 📋 Installation
+
+```bash
+npm install @geee-be/react-utils
+# or
+pnpm add @geee-be/react-utils
+# or
+yarn add @geee-be/react-utils
+```
+
+### Peer Dependencies
+
+```bash
+npm install react react-dom
+```
+
+**Required versions:**
+- React >= 18.0.0
+
+## 🚀 Quick Start
+
+```tsx
+import { useLocalState, useIsClient, useIsMobile } from '@geee-be/react-utils';
+
+function MyComponent() {
+  const [theme, setTheme] = useLocalState('theme', 'light');
+  const isClient = useIsClient();
+  const isMobile = useIsMobile();
+
+  if (!isClient) {
+    return <div>Loading...</div>;
+  }
+
+  return (
+    <div className={`theme-${theme} ${isMobile ? 'mobile' : 'desktop'}`}>
+      <button onClick={() => setTheme(theme === 'light' ? 'dark' : 'light')}>
+        Toggle Theme
+      </button>
+    </div>
+  );
+}
+```
+
+## 🪝 Hooks Overview
+
+### State Management
+
+#### `useLocalState`
+Enhanced `useState` with localStorage persistence and cross-tab synchronization.
+
+```tsx
+import { useLocalState } from '@geee-be/react-utils';
+
+function Settings() {
+  const [settings, setSettings] = useLocalState('user-settings', {
+    theme: 'light',
+    language: 'en'
+  });
+
+  return (
+    <div>
+      <button onClick={() => setSettings(prev => ({ ...prev, theme: 'dark' }))}>
+        Enable Dark Mode
+      </button>
+    </div>
+  );
+}
+```
+
+**Features:**
+- Automatic localStorage synchronization
+- Cross-tab state updates
+- SSR-safe initialization
+- Type-safe with TypeScript inference
+
+#### `useHistoryState`
+State management with browser history integration for navigation state persistence.
+
+```tsx
+import { useHistoryState } from '@geee-be/react-utils';
+
+function SearchPage() {
+  const [query, setQuery] = useHistoryState('search', '');
+
+  return (
+    <input
+      value={query}
+      onChange={(e) => setQuery(e.target.value)}
+      placeholder="Search..."
+    />
+  );
+}
+```
+
+### Environment Detection
+
+#### `useIsClient`
+Detect client-side rendering vs server-side rendering to prevent hydration mismatches.
+
+```tsx
+import { useIsClient } from '@geee-be/react-utils';
+
+function ClientOnlyFeature() {
+  const isClient = useIsClient();
+
+  if (!isClient) {
+    return <div>Loading...</div>; // Server-side fallback
+  }
+
+  return <ExpensiveClientComponent />;
+}
+```
+
+#### `useIsMobile`
+Responsive device detection with customizable breakpoints.
+
+```tsx
+import { useIsMobile } from '@geee-be/react-utils';
+
+function ResponsiveNav() {
+  const isMobile = useIsMobile(768); // Custom breakpoint
+
+  return isMobile ? <MobileNav /> : <DesktopNav />;
+}
+```
+
+### Communication
+
+#### `useBroadcastChannel`
+Cross-tab/window communication using the Broadcast Channel API with fallback.
+
+```tsx
+import { useBroadcastChannel } from '@geee-be/react-utils';
+
+function ChatApp() {
+  const [message, postMessage] = useBroadcastChannel('chat-channel');
+
+  useEffect(() => {
+    if (message) {
+      console.log('Received message:', message);
+      // Handle incoming message from other tabs
+    }
+  }, [message]);
+
+  const sendMessage = () => {
+    postMessage({ text: 'Hello from another tab!', timestamp: Date.now() });
+  };
+
+  return <button onClick={sendMessage}>Send Message</button>;
+}
+```
+
+## 🛠️ Utility Functions
+
+### Component Helpers
+
+#### `ClientOnly`
+Wrapper component for client-side only rendering.
+
+```tsx
+import { ClientOnly } from '@geee-be/react-utils';
+
+function App() {
+  return (
+    <div>
+      <h1>Server and Client Rendered</h1>
+      <ClientOnly>
+        <ExpensiveClientComponent />
+      </ClientOnly>
+    </div>
+  );
+}
+```
+
+#### `withSubComponents`
+Utility for creating compound components with sub-components.
+
+```tsx
+import { withSubComponents } from '@geee-be/react-utils';
+
+// Create compound components easily
+const Card = withSubComponents(CardRoot, {
+  Header: CardHeader,
+  Content: CardContent,
+  Footer: CardFooter
+});
+
+// Usage
+<Card>
+  <Card.Header>Title</Card.Header>
+  <Card.Content>Content here</Card.Content>
+</Card>
+```
+
+#### `Monitor`
+Development component for monitoring component renders and lifecycle.
+
+```tsx
+import { Monitor } from '@geee-be/react-utils';
+
+function DebugComponent() {
+  return (
+    <Monitor label="MyComponent">
+      <MyComponent />
+    </Monitor>
+  );
+}
+// Logs: "MyComponent mounted", "MyComponent rendered 1", etc.
+```
+
+### Effects and Interactions
+
+#### `createRipple`
+Material Design ripple effect implementation for click interactions.
+
+```tsx
+import { createRipple } from '@geee-be/react-utils';
+
+function RippleButton() {
+  return (
+    <button
+      onClick={createRipple}
+      className="relative overflow-hidden"
+    >
+      Click for Ripple Effect
+    </button>
+  );
+}
+
+// Or use with custom event handler
+function CustomButton() {
+  const handleClick = (event) => {
+    createRipple(event);
+    // Your custom logic here
+  };
+
+  return (
+    <button
+      onClick={handleClick}
+      className="relative overflow-hidden"
+    >
+      Custom Click Handler
+    </button>
+  );
+}
+```
+
+NOTE: it is important that the button has `className="relative"`
+
+## 🌐 SSR Compatibility
+
+All hooks and utilities are designed to work seamlessly with server-side rendering:
+
+### Next.js Integration
+
+```tsx
+// pages/_app.tsx or app/layout.tsx
+import { useIsClient } from '@geee-be/react-utils';
+
+function MyApp({ Component, pageProps }) {
+  const isClient = useIsClient();
+
+  return (
+    <div>
+      <Component {...pageProps} />
+      {isClient && <ClientOnlyAnalytics />}
+    </div>
+  );
+}
+```
+
+### Hydration Safety
+
+```tsx
+import { useLocalState, useIsClient } from '@geee-be/react-utils';
+
+function ThemeProvider({ children }) {
+  const [theme, setTheme] = useLocalState('theme', 'light');
+  const isClient = useIsClient();
+
+  // Prevents hydration mismatch
+  const currentTheme = isClient ? theme : 'light';
+
+  return (
+    <div data-theme={currentTheme}>
+      {children}
+    </div>
+  );
+}
+```
+
+## 🎯 Performance Considerations
+
+### Optimized Re-renders
+Hooks use React's built-in optimization patterns:
+
+```tsx
+// useLocalState only re-renders when the actual value changes
+const [count, setCount] = useLocalState('count', 0);
+
+// Callbacks are memoized automatically
+const increment = useCallback(() => setCount(c => c + 1), [setCount]);
+```
+
+### Memory Management
+Automatic cleanup prevents memory leaks:
+
+```tsx
+// Broadcast channels are automatically cleaned up on unmount
+const [message, postMessage] = useBroadcastChannel('channel');
+
+// Event listeners are properly removed
+const isMobile = useIsMobile();
+```
+
+## 📱 Framework Integration
+
+### Next.js
+```tsx
+// Full SSR support with App Router
+import { useLocalState } from '@geee-be/react-utils';
+
+export default function Page() {
+  const [data, setData] = useLocalState('page-data', null);
+  return <div>{data?.title}</div>;
+}
+```
+
+### Remix
+```tsx
+import { useIsClient } from '@geee-be/react-utils';
+
+export default function RemixRoute() {
+  const isClient = useIsClient();
+  return isClient ? <ClientFeature /> : <ServerFallback />;
+}
+```
+
+### Vite/SPA
+```tsx
+// Works great in client-side apps too
+import { useHistoryState } from '@geee-be/react-utils';
+
+function SinglePageApp() {
+  const [route, setRoute] = useHistoryState('route', '/');
+  return <Router currentRoute={route} />;
+}
+```
+
+## 🔧 TypeScript Support
+
+Full TypeScript support with comprehensive type definitions:
+
+```tsx
+import { useLocalState } from '@geee-be/react-utils';
+
+interface UserPreferences {
+  theme: 'light' | 'dark';
+  language: string;
+  notifications: boolean;
+}
+
+function UserSettings() {
+  // Type is automatically inferred as [UserPreferences, (value: UserPreferences) => void]
+  const [prefs, setPrefs] = useLocalState<UserPreferences>('user-prefs', {
+    theme: 'light',
+    language: 'en',
+    notifications: true
+  });
+
+  // TypeScript will ensure type safety
+  const toggleTheme = () => {
+    setPrefs(prev => ({
+      ...prev,
+      theme: prev.theme === 'light' ? 'dark' : 'light'
+    }));
+  };
+
+  return <button onClick={toggleTheme}>Toggle Theme</button>;
+}
+```
+
+## 🔗 Related Packages
+
+- **[@geee-be/react-twui](https://www.npmjs.com/package/@geee-be/react-twui)** - UI component library that uses these utilities
+- **[@uidotdev/usehooks](https://usehooks.com/)** - Additional React hooks (included as dependency)
+
+## 📄 License
+
+MIT License - see [LICENSE](../../LICENSE) file for details.
+
+## 🐛 Issues & Support
+
+Found a bug or need help? Please [open an issue](https://github.com/geee-be/react-libraries/issues) on GitHub.

package/dist/hooks/use-history-state.js

@@ -3,9 +3,6 @@ import { useEffect, useState } from 'react';
 import { deserialize, getInitialValue, serialize } from './state.util.js';
 const LOADING = Symbol('loading');
 export const useHistoryState = (key, initialValue, replace = true, options) => {
-    if (typeof history === 'undefined') {
-        return [undefined, () => { }, false];
-    }
     const [value, setValue] = useState(LOADING);
     useEffect(() => {
         setValue(deserialize(history.state?.[key], options?.fromSerializable) ??

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geee-be/react-utils",
-  "version": "1.3.0",
+  "version": "1.3.1",
   "description": "",
   "keywords": [],
   "license": "MIT",

package/src/helpers/monitor.tsx

@@ -1,7 +1,7 @@
 'use client';
 
 import { useRenderCount } from '@uidotdev/usehooks';
-import { useEffect, type FC, type PropsWithChildren } from 'react';
+import { type FC, type PropsWithChildren, useEffect } from 'react';
 
 type Props = PropsWithChildren<{ label: string }>;
 

package/src/helpers/sub-component.tsx

@@ -5,8 +5,8 @@ export const withSubComponents = <P extends {}, S>(
   subComponents: S,
 ) =>
   Object.assign(
-    forwardRef<unknown, P>((props: any, ref: any) => (
-      <RootComponent {...props} ref={ref} />
+    forwardRef<unknown, P>((props: unknown, ref: unknown) => (
+      <RootComponent {...(props as P)} ref={ref} />
     )),
     subComponents,
   );

package/src/hooks/use-history-state.ts

@@ -17,10 +17,6 @@ export const useHistoryState = <T, S = T>(
   replace = true,
   options?: SerializationOptions<T, S>,
 ): Response<T> => {
-  if (typeof history === 'undefined') {
-    return [undefined, () => {}, false];
-  }
-
   const [value, setValue] = useState<T | typeof LOADING>(LOADING);
 
   useEffect(() => {