@websolutespa/bom-mixer-hooks 1.8.10 → 1.9.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # @websolutespa/bom-mixer-hooks
 
+## 1.9.0
+
+### Minor Changes
+
+- Modified: usePagination
+- Added: useMetaData
+
+## 1.8.11
+
+### Patch Changes
+
+- Modified: usePage typings
+- Updated dependencies
+- Updated dependencies
+  - @websolutespa/bom-mixer-store@1.8.11
+  - @websolutespa/bom-mixer-models@1.8.18
+
 ## 1.8.10
 
 ### Patch Changes

package/README.md

@@ -9,3 +9,433 @@ Mixer Hooks module of the [BOM Repository](https://github.com/websolutespa/bom)
 ---
 
 ##### *this library is for internal usage and not production ready*
+
+# @websolutespa/bom-mixer-hooks Documentation
+
+A collection of React hooks for building modern web applications.
+
+## Table of Contents
+
+- [Installation](#installation)
+- [API and Networking](#api-and-networking)
+- [UI and Layout](#ui-and-layout)
+- [Form and Input](#form-and-input)
+- [Internationalization](#internationalization)
+- [Scroll and Viewport](#scroll-and-viewport)
+- [State Management](#state-management)
+- [Performance](#performance)
+- [Event Handling](#event-handling)
+
+## Installation
+
+```bash
+npm install @websolutespa/bom-mixer-hooks
+```
+
+## API and Networking
+
+### useApi
+
+Hook for making RESTful API calls.
+
+```typescript
+import { useApi } from '@websolutespa/bom-mixer-hooks';
+
+function MyComponent() {
+  const api = useApi();
+
+  const fetchData = async () => {
+    try {
+      // GET request
+      const data = await api.get('/endpoint');
+
+      // POST request with payload
+      const response = await api.post('/endpoint', {
+        name: 'John',
+      });
+
+      // PUT request
+      await api.put('/endpoint/1', {
+        updated: true,
+      });
+
+      // DELETE request
+      await api.delete('/endpoint/1');
+    } catch (error) {
+      console.error('API error:', error);
+    }
+  };
+}
+```
+
+### useCollectionApi
+
+Specialized version of useApi for data collections.
+
+```typescript
+import { useCollectionApi, useCollectionApiGet } from '@websolutespa/bom-mixer-hooks';
+
+function MyCollection() {
+  const [data, loading, error] = useCollectionApiGet('/collection', {
+    where: { status: 'active' }
+  });
+
+  if (loading) return <Loading />;
+  if (error) return <Error message={error.message} />;
+
+  return (
+    <div>
+      {data.map(item => (
+        <Item key={item.id} {...item} />
+      ))}
+    </div>
+  );
+}
+```
+
+## UI and Layout
+
+### useLayout
+
+Manages the global application layout.
+
+```typescript
+import { useLayout } from '@websolutespa/bom-mixer-hooks';
+
+function Header() {
+  const layout = useLayout();
+
+  return (
+    <header>
+      <nav>
+        {layout.menu.main.items.map(item => (
+          <MenuItem key={item.id} {...item} />
+        ))}
+      </nav>
+    </header>
+  );
+}
+```
+
+### useDrawer
+
+Manages drawer/sidebar state.
+
+```typescript
+import { useDrawer } from '@websolutespa/bom-mixer-hooks';
+
+function Sidebar() {
+  const [drawer, openDrawer, closeDrawer] = useDrawer();
+
+  return (
+    <>
+      <button onClick={() => openDrawer('main')}>Open Menu</button>
+
+      <div className={`drawer ${drawer === 'main' ? 'open' : ''}`}>
+        <button onClick={closeDrawer}>Close</button>
+        {/* Drawer content */}
+      </div>
+    </>
+  );
+}
+```
+
+### useBreakpoint
+
+Handles responsive breakpoints.
+
+```typescript
+import { useBreakpoint } from '@websolutespa/bom-mixer-hooks';
+
+function ResponsiveComponent() {
+  const breakpoint = useBreakpoint();
+
+  return (
+    <div>
+      {breakpoint.key === 'xs' && <MobileView />}
+      {breakpoint.key === 'md' && <TabletView />}
+      {breakpoint.key === 'lg' && <DesktopView />}
+    </div>
+  );
+}
+```
+
+## Form and Input
+
+### useAutosizeTextArea
+
+Automatically adjusts textarea height.
+
+```typescript
+import { useAutosizeTextArea } from '@websolutespa/bom-mixer-hooks';
+
+function AutoResizingTextarea() {
+  const [value, setValue] = useState('');
+  const textAreaRef = useRef<HTMLTextAreaElement>(null);
+
+  useAutosizeTextArea(textAreaRef.current, value);
+
+  return (
+    <textarea
+      ref={textAreaRef}
+      value={value}
+      onChange={(e) => setValue(e.target.value)}
+    />
+  );
+}
+```
+
+### useFocusTrap
+
+Keeps focus within an element (useful for modals).
+
+```typescript
+import { useFocusTrap } from '@websolutespa/bom-mixer-hooks';
+
+function Modal() {
+  const modalRef = useRef(null);
+  const [isTrapped, setIsTrapped] = useFocusTrap(modalRef);
+
+  useEffect(() => {
+    setIsTrapped(true);
+    return () => setIsTrapped(false);
+  }, []);
+
+  return (
+    <div ref={modalRef}>
+      <input type="text" />
+      <button>Action</button>
+      <button>Close</button>
+    </div>
+  );
+}
+```
+
+## Internationalization
+
+### useLabel
+
+Manages translations.
+
+```typescript
+import { useLabel } from '@websolutespa/bom-mixer-hooks';
+
+function Translated() {
+  const label = useLabel();
+
+  return (
+    <div>
+      <h1>{label('welcome.title')}</h1>
+      <p>{label('welcome.description', { name: 'John' })}</p>
+    </div>
+  );
+}
+```
+
+### useCurrency
+
+Formats monetary values.
+
+```typescript
+import { useCurrency } from '@websolutespa/bom-mixer-hooks';
+
+function PriceDisplay() {
+  const formatCurrency = useCurrency('EUR', 'en-US');
+
+  return (
+    <div>
+      <p>Price: {formatCurrency(29.99)}</p> {/* Outputs: €29.99 */}
+    </div>
+  );
+}
+```
+
+## Scroll and Viewport
+
+### useIntersectionObserver
+
+Observes when elements enter the viewport.
+
+```typescript
+import { useIntersectionObserver } from '@websolutespa/bom-mixer-hooks';
+
+function LazyImage() {
+  const ref = useRef(null);
+  const isVisible = useIntersectionObserver(ref, {
+    threshold: 0.1
+  });
+
+  return (
+    <div ref={ref}>
+      {isVisible && <img src="heavy-image.jpg" alt="Lazy loaded" />}
+    </div>
+  );
+}
+```
+
+### useScrollTo
+
+Manages smooth scrolling to elements.
+
+```typescript
+import { useScrollTo } from '@websolutespa/bom-mixer-hooks';
+
+function ScrollableContent() {
+  const scrollTo = useScrollTo(80); // 80px offset
+
+  return (
+    <nav>
+      <a href="#section1" onClick={scrollTo}>Go to Section 1</a>
+      <div id="section1">
+        {/* Content */}
+      </div>
+    </nav>
+  );
+}
+```
+
+## State Management
+
+### useCurrentState
+
+Manages state with current reference.
+
+```typescript
+import { useCurrentState } from '@websolutespa/bom-mixer-hooks';
+
+function StateManager() {
+  const [value, setValue, valueRef] = useCurrentState(0);
+
+  useEffect(() => {
+    // valueRef.current is always up to date
+    const interval = setInterval(() => {
+      console.log('Current value:', valueRef.current);
+    }, 1000);
+
+    return () => clearInterval(interval);
+  }, []);
+
+  return (
+    <button onClick={() => setValue(v => v + 1)}>
+      Count: {value}
+    </button>
+  );
+}
+```
+
+## Performance
+
+### useDebounce
+
+Delays function execution.
+
+```typescript
+import { useDebounce } from '@websolutespa/bom-mixer-hooks';
+
+function SearchInput() {
+  const [value, setValue] = useState('');
+  const debouncedValue = useDebounce(value, 500);
+
+  useEffect(() => {
+    // API call only after 500ms from last input
+    searchAPI(debouncedValue);
+  }, [debouncedValue]);
+
+  return (
+    <input
+      type="text"
+      value={value}
+      onChange={(e) => setValue(e.target.value)}
+    />
+  );
+}
+```
+
+## Event Handling
+
+### useEventListener
+
+Safely manages event listeners.
+
+```typescript
+import { useEventListener } from '@websolutespa/bom-mixer-hooks';
+
+function EventHandler() {
+  const handleKeyPress = (e: KeyboardEvent) => {
+    if (e.key === 'Escape') {
+      // Handle escape key
+    }
+  };
+
+  useEventListener('keydown', handleKeyPress);
+
+  return <div>Press ESC to trigger action</div>;
+}
+```
+
+## Best Practices
+
+1. **Hook Composition**
+
+```typescript
+function ComplexComponent() {
+  const layout = useLayout();
+  const breakpoint = useBreakpoint();
+  const [drawer] = useDrawer();
+
+  // Combine hooks for advanced functionality
+  const isMobileMenuOpen = breakpoint.key === 'xs' && drawer === 'menu';
+
+  return (
+    <div className={isMobileMenuOpen ? 'mobile-menu' : ''}>
+      {/* Component content */}
+    </div>
+  );
+}
+```
+
+2. **Error Handling**
+
+```typescript
+function DataFetcher() {
+  const [data, loading, error] = useCollectionApiGet('/api/data');
+
+  if (error) {
+    return <ErrorBoundary error={error} />;
+  }
+
+  if (loading) {
+    return <LoadingSpinner />;
+  }
+
+  return <DataDisplay data={data} />;
+}
+```
+
+3. **Performance Optimization**
+
+```typescript
+function OptimizedComponent() {
+  const debouncedSearch = useDebounceCallback((term: string) => {
+    searchAPI(term);
+  }, 300);
+
+  const intersectionRef = useRef(null);
+  const isVisible = useIntersectionObserver(intersectionRef);
+
+  // Load heavy content only when visible
+  return (
+    <div ref={intersectionRef}>
+      {isVisible && <HeavyContent />}
+    </div>
+  );
+}
+```
+
+## Contributing
+
+Please read our [Contributing Guide](CONTRIBUTING.md) before submitting a Pull Request to the project.
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.