@websolutespa/bom-mixer-hooks 1.8.11 → 1.9.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # @websolutespa/bom-mixer-hooks
 
+## 1.9.0
+
+### Minor Changes
+
+- Modified: usePagination
+- Added: useMetaData
+
 ## 1.8.11
 
 ### 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.

package/dist/index.d.ts

@@ -5,7 +5,7 @@ import * as _websolutespa_bom_core from '@websolutespa/bom-core';
 import { QueryParams, IEquatable, IFeatureType, ILabel, ILocalizable, ILayout, ILocalized, IPage } from '@websolutespa/bom-core';
 import * as zustand from 'zustand';
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { ILazyModules } from '@websolutespa/bom-mixer-models';
+import { ILazyModules, IMetaData, StructuredDataType, OpenGraphType, TwitterCardType } from '@websolutespa/bom-mixer-models';
 import { NextRouter } from 'next/router';
 
 declare function useApiFetch<T = unknown>(pathname: string, options?: ApiRequestOptions): [T | undefined, boolean, any, react.Dispatch<any>];
@@ -405,6 +405,34 @@ declare function LazyModulesProvider({ children, modules }: {
     modules: ILazyModules;
 }): react_jsx_runtime.JSX.Element;
 
+type IMetaDataContext = IMetaData;
+declare const useMetaData: () => IMetaData;
+declare function MetaDataProvider({ children, metaData }: {
+    children?: react__default.ReactNode;
+    metaData: {
+        brand: {
+            name: string;
+            logo: string;
+            businessName?: string;
+            appName?: string;
+            url?: string;
+            email?: string;
+            telephone?: string;
+            zipCode?: string;
+            address?: string;
+            city?: string;
+            provinceCode?: string;
+            countryName?: string;
+            countryCode?: string;
+            twitterName?: string;
+            social?: Record<string, string>;
+        };
+        structuredData?: StructuredDataType;
+        openGraph?: OpenGraphType;
+        twitterCard?: TwitterCardType;
+    };
+}): react_jsx_runtime.JSX.Element;
+
 declare function useModal(): [modal: UIValue, open: (value?: string) => void, close: () => void];
 
 declare function useMounted(): boolean;
@@ -444,6 +472,26 @@ declare const usePage: () => {
         description?: string | undefined;
         keywords?: string | undefined;
         robots?: string | undefined;
+        image?: {
+            [x: string]: unknown;
+            id?: string | undefined;
+            alt?: string | undefined;
+            filename?: string | undefined;
+            mimeType?: string | undefined;
+            filesize?: number | undefined;
+            focalX?: number | undefined;
+            focalY?: number | undefined;
+            createdAt?: string | Date | undefined;
+            updatedAt?: string | Date | undefined;
+            url?: string | undefined;
+            title?: string | undefined;
+            abstract?: string | undefined;
+            type: string;
+            src?: string | undefined;
+            media?: any | undefined;
+            width?: string | number | undefined;
+            height?: string | number | undefined;
+        } | undefined;
     } | undefined;
     components?: _websolutespa_bom_core.IComponent[] | undefined;
     category: {
@@ -792,18 +840,53 @@ declare function usePageLoading(options?: {
     previousPageRoute: IPageRoute | undefined;
 };
 
-type IPaginationInfo<T = any> = {
+type IPaginationItem = any;
+type IPaginationOptions = {
+    mode?: 'pagination' | 'infinite';
+    page?: number;
+    perPage?: number;
+    delayInMs?: number;
+};
+type IPaginationInfo<T extends IPaginationItem = IPaginationItem> = {
+    items: T[];
+    hasMore: boolean;
+    nextPage: number | undefined;
+    page: number;
+    pages: number;
+    perPage: number;
+    prevPage: number | undefined;
+    total: number;
+};
+declare function isPaginationInfo(item: unknown): item is IPaginationInfo;
+declare function getPagedItems<T extends IPaginationItem = IPaginationItem>(items: T[], page: number, perPage: number): T[];
+declare function getMoreItems<T extends IPaginationItem = IPaginationItem>(items: T[], page: number, perPage: number): T[];
+declare function getPaginationInfo<T extends IPaginationItem = IPaginationItem>(items: T[], options?: IPaginationOptions): IPaginationInfo<T>;
+
+declare function usePagination<T extends IPaginationItem = IPaginationItem>(items: T[], options?: {
+    mode?: 'pagination' | 'infinite';
+    page?: number;
+    perPage?: number;
+    delayInMs?: number;
+}): IPaginationInfo<T> & {
+    loadMore: () => number;
+    goToPage: (page: number) => void;
+    goToNextPage: () => void;
+    goToPreviousPage: () => void;
+    setPerPage: (perPage: number) => void;
+};
+
+type IPaginationLegacyInfo<T = any> = {
     items: T[];
     page: number;
     pages: number;
     perPage: number;
     total: number;
 };
-declare function isPaginationInfo(item: unknown): item is IPaginationInfo<any>;
-declare function getPagedItems<T>(items: T[], page: number, perPage: number): T[];
-declare function getPaginationInfo<T>(items: T[], page?: number, perPage?: number): IPaginationInfo<T>;
+declare function isPaginationLegacyInfo(item: unknown): item is IPaginationLegacyInfo<any>;
+declare function getPagedItemsLegacy<T>(items: T[], page: number, perPage: number): T[];
+declare function getPaginationLegacyInfo<T>(items: T[], page?: number, perPage?: number): IPaginationLegacyInfo<T>;
 
-declare function usePagination<T>($items: T[], $page?: number, $perPage?: number): {
+declare function usePaginationLegacy<T>($items: T[], $page?: number, $perPage?: number): {
     items: T[];
     page: number;
     pages: number;
@@ -972,4 +1055,4 @@ type WindowSize = {
 };
 declare function useWindowSize(): WindowSize;
 
-export { BodyScrollOptions, ClickOutGetContainer, ColorScheme, CurrentStateType, ElementStackItem, ExtraProvider, Filter, FilterMode, FilterParams, FilterValues, GeoLocationSensorState, IExtra, IFilter, IFilterOption, IGeolocationPositionError, ILabelContext, ILayoutContext, ILazyModulesContext, IPageContext, IPageRoute, IPageRouteOptions, IPaginationInfo, IParams, IParamsEncoded, IParamsQs, IUseSearchParamsEncodedResult, IUseSearchParamsQsResult, IUseSearchParamsResult, IUseSearchParamsValueResult, KeyCode, KeyMod, KeyboardOptions, KeyboardResult, LabelProvider, LabelService, LayoutProvider, LazyModulesProvider, PageProvider, SSRState, SizeResult, SizeType, Sorting, UIReducer, UIValue, UseFiltersResultType, UseKeyboard, UseKeyboardHandler, createElementWithId, createGenericContext, detectIsBrowser, filtersToParams, getCurrentPosition, getFilteredItems, getFilters, getOwnerPaddingRight, getOwnerScrollbarWidth, getPagedItems, getPaginationInfo, getPreferredColorScheme, getPreferredReducedMotion, getRealSize, getSearchParams, getSearchParamsEncoded, getSearchParamsQs, getUID, hasGeolocation, isElement, isPaginationInfo, localCollectionDelete, localCollectionFetch, localCollectionGet, localCollectionPatch, localCollectionPost, localCollectionPut, parseLabel, parseParams, pushSearchParams, pushSearchParamsEncoded, pushSearchParamsEncodedSilently, pushSearchParamsQs, pushSearchParamsQsSilently, pushSearchParamsSilently, replaceSearchParams, replaceSearchParamsEncoded, replaceSearchParamsEncodedSilently, replaceSearchParamsQs, replaceSearchParamsQsSilently, replaceSearchParamsSilently, scrollToRelativeY, scrollToSelector, scrollToY, setFilters, updateSearchParams, updateSearchParamsEncoded, updateSearchParamsQs, useApi, useApiDelete, useApiFetch, useApiGet, useApiPatch, useApiPost, useApiPut, useAutosizeTextArea, useBodyScroll, useBreakpoint, useClickAnyWhere, useClickOut, useCollectionApi, useCollectionApiDelete, useCollectionApiGet, useCollectionApiPatch, useCollectionApiPost, useCollectionApiPut, useColorScheme, useCurrency, useCurrentState, useDateTimeFormat, useDebounce, useDebounceCallback, useDebugChangedProps, useDomObserver, useDrawer, useElementSize, useEventListener, useExtra, useFilters, useFocusTrap, useGeolocation, useIdle, useInfiniteLoader, useIntersectionObserver, useIsomorphicLayoutEffect, useKeyboard, useLabel, useLayout, useLazyModules, useModal, useMounted, useNumber, usePage, usePageLoading, usePagination, usePortal, usePrevious, useRealSize, useReducedMotion, useReducedMotionLocal, useResize, useSSR, useScroll, useScrollTo, useScrolled, useSearchParams, useSearchParamsEncoded, useSearchParamsQs, useSearchParamsValue, useSorting, useSyncedRef, useUI, useUnit, useUnmountEffect, useWindowSize };
+export { BodyScrollOptions, ClickOutGetContainer, ColorScheme, CurrentStateType, ElementStackItem, ExtraProvider, Filter, FilterMode, FilterParams, FilterValues, GeoLocationSensorState, IExtra, IFilter, IFilterOption, IGeolocationPositionError, ILabelContext, ILayoutContext, ILazyModulesContext, IMetaDataContext, IPageContext, IPageRoute, IPageRouteOptions, IPaginationInfo, IPaginationItem, IPaginationLegacyInfo, IPaginationOptions, IParams, IParamsEncoded, IParamsQs, IUseSearchParamsEncodedResult, IUseSearchParamsQsResult, IUseSearchParamsResult, IUseSearchParamsValueResult, KeyCode, KeyMod, KeyboardOptions, KeyboardResult, LabelProvider, LabelService, LayoutProvider, LazyModulesProvider, MetaDataProvider, PageProvider, SSRState, SizeResult, SizeType, Sorting, UIReducer, UIValue, UseFiltersResultType, UseKeyboard, UseKeyboardHandler, createElementWithId, createGenericContext, detectIsBrowser, filtersToParams, getCurrentPosition, getFilteredItems, getFilters, getMoreItems, getOwnerPaddingRight, getOwnerScrollbarWidth, getPagedItems, getPagedItemsLegacy, getPaginationInfo, getPaginationLegacyInfo, getPreferredColorScheme, getPreferredReducedMotion, getRealSize, getSearchParams, getSearchParamsEncoded, getSearchParamsQs, getUID, hasGeolocation, isElement, isPaginationInfo, isPaginationLegacyInfo, localCollectionDelete, localCollectionFetch, localCollectionGet, localCollectionPatch, localCollectionPost, localCollectionPut, parseLabel, parseParams, pushSearchParams, pushSearchParamsEncoded, pushSearchParamsEncodedSilently, pushSearchParamsQs, pushSearchParamsQsSilently, pushSearchParamsSilently, replaceSearchParams, replaceSearchParamsEncoded, replaceSearchParamsEncodedSilently, replaceSearchParamsQs, replaceSearchParamsQsSilently, replaceSearchParamsSilently, scrollToRelativeY, scrollToSelector, scrollToY, setFilters, updateSearchParams, updateSearchParamsEncoded, updateSearchParamsQs, useApi, useApiDelete, useApiFetch, useApiGet, useApiPatch, useApiPost, useApiPut, useAutosizeTextArea, useBodyScroll, useBreakpoint, useClickAnyWhere, useClickOut, useCollectionApi, useCollectionApiDelete, useCollectionApiGet, useCollectionApiPatch, useCollectionApiPost, useCollectionApiPut, useColorScheme, useCurrency, useCurrentState, useDateTimeFormat, useDebounce, useDebounceCallback, useDebugChangedProps, useDomObserver, useDrawer, useElementSize, useEventListener, useExtra, useFilters, useFocusTrap, useGeolocation, useIdle, useInfiniteLoader, useIntersectionObserver, useIsomorphicLayoutEffect, useKeyboard, useLabel, useLayout, useLazyModules, useMetaData, useModal, useMounted, useNumber, usePage, usePageLoading, usePagination, usePaginationLegacy, usePortal, usePrevious, useRealSize, useReducedMotion, useReducedMotionLocal, useResize, useSSR, useScroll, useScrollTo, useScrolled, useSearchParams, useSearchParamsEncoded, useSearchParamsQs, useSearchParamsValue, useSorting, useSyncedRef, useUI, useUnit, useUnmountEffect, useWindowSize };