@pushwoosh/kit-helpers 4.8.2 → 4.8.4

package/ai-documentation.mdx

@@ -0,0 +1,681 @@
+
+
+---
+title: "@pushwoosh/kit-helpers — API Reference"
+version: "2.0.0"
+description: "React component library for building Pushwoosh products with TypeScript, styled-components, and comprehensive hook utilities"
+---
+
+# @pushwoosh/kit-helpers
+
+**Version:** 2.0.0
+
+React component library for building Pushwoosh products with TypeScript, styled-components, and comprehensive hook utilities.
+
+> This page is generated from `ai-documentation.json` and groups the API by Components, Hooks, Utilities, and Types. All styled-component props are prefixed with `$` to avoid DOM prop warnings.
+
+---
+
+## Components
+
+### GridContainer
+- **Path:** `~/src/grid`
+- **Description:** Base grid container component using CSS Grid for flexible layouts
+- **Interface:**
+```ts
+GridContainer<{
+  $alignContent?: 'center' | 'start' | 'end' | 'space-between' | 'space-around' | 'space-evenly' | 'stretch';
+  $alignItems?: 'center' | 'start' | 'end' | 'baseline' | 'stretch';
+  $bgColor?: string;
+  $border?: string | CssBoxSides<string>;
+  $borderRadius?: StrNum;
+  $boxShadow?: string;
+  $gap?: StrNum;
+  $gridAutoFlow?: 'row' | 'column' | 'dense' | 'row dense' | 'column dense';
+  $justifyContent?: 'center' | 'start' | 'end' | 'space-between' | 'space-around' | 'space-evenly' | 'stretch';
+  $justifyItems?: 'center' | 'start' | 'end' | 'baseline' | 'stretch';
+  $margin?: StrNum | CssBoxSides<StrNum>;
+  $padding?: StrNum | CssBoxSides<StrNum>;
+  $placeItems?: 'center' | 'start' | 'end' | 'stretch';
+}>
+```
+
+**Props**
+
+| Name | Type | Required | Default | Description | Values |
+|---|---|:---:|:---:|---|---|
+| `$alignContent` | enum |  |  | Aligns the grid content along the cross axis | `center`, `start`, `end`, `space-between`, `space-around`, `space-evenly`, `stretch` |
+| `$alignItems` | enum |  |  | Aligns grid items along the cross axis | `center`, `start`, `end`, `baseline`, `stretch` |
+| `$bgColor` | string |  |  | Background color of the grid container | |
+| `$border` | object |  |  | Border styling, can be string or object with top/right/bottom/left properties | |
+| `$borderRadius` | string\|number |  |  | Border radius, accepts number (converted to px) or string | |
+| `$boxShadow` | string |  |  | CSS box shadow property | |
+| `$gap` | string\|number |  |  | Gap between grid items, accepts number (converted to px) or string | |
+| `$gridAutoFlow` | enum |  |  | Controls how auto-placed items are inserted in the grid | `row`, `column`, `dense`, `row dense`, `column dense` |
+| `$justifyContent` | enum |  |  | Aligns the grid content along the main axis | `center`, `start`, `end`, `space-between`, `space-around`, `space-evenly`, `stretch` |
+| `$justifyItems` | enum |  |  | Aligns grid items along the main axis | `center`, `start`, `end`, `baseline`, `stretch` |
+| `$margin` | object |  |  | Margin spacing, can be number/string or object with directional properties | |
+| `$padding` | object |  |  | Padding spacing, can be number/string or object with directional properties | |
+| `$placeItems` | enum |  |  | Shorthand for align-items and justify-items | `center`, `start`, `end`, `stretch` |
+
+**Example**
+```tsx
+<GridContainer $gap={16} $padding={20} $bgColor="#f0f0f0">
+  <div>Item 1</div>
+  <div>Item 2</div>
+</GridContainer>
+```
+
+**Notes**
+- All props are prefixed with `$` to indicate they are styled-component props
+- Numbers are automatically converted to `px` units
+- Use `CssBoxSides` for asymmetric margin/padding/border
+- Prefer specific layout components (Columns, Rows, Horizontal, Vertical) for common patterns
+
+---
+
+### Columns
+- **Path:** `~/src/grid`
+- **Description:** Grid container that creates equal or custom-sized columns
+- **Interface:** `Columns<{ $sizes: StrNum; ...GridContainerProps }>`
+
+**Props**
+
+| Name | Type | Required | Default | Description |
+|---|---|:---:|:---:|---|
+| `$sizes` | string\|number | ✓ |  | Number for equal columns (e.g., `3`) or string for custom sizing (e.g., `"1fr 2fr"`) |
+
+**Examples**
+```tsx
+<Columns $sizes={3} $gap={8}>
+  <div>Col 1</div>
+  <div>Col 2</div>
+  <div>Col 3</div>
+</Columns>
+```
+```tsx
+<Columns $sizes="1fr 2fr" $gap={8}>
+  <div>Narrow</div>
+  <div>Wide</div>
+</Columns>
+```
+
+**Notes**
+- Extends GridContainer with all its props
+- Number value creates equal columns using `repeat(n, 1fr)`
+- String value is passed directly to `grid-template-columns`
+- Ideal for responsive layouts with fixed column counts
+
+---
+
+### Rows
+- **Path:** `~/src/grid`
+- **Description:** Grid container that creates equal or custom-sized rows
+- **Interface:** `Rows<{ $sizes: StrNum; ...GridContainerProps }>`
+
+**Props**
+
+| Name | Type | Required | Default | Description |
+|---|---|:---:|:---:|---|
+| `$sizes` | string\|number | ✓ |  | Number for equal rows or string for custom sizing |
+
+**Example**
+```tsx
+<Rows $sizes={3} $gap={10}>
+  <div>Row 1</div>
+  <div>Row 2</div>
+  <div>Row 3</div>
+</Rows>
+```
+
+**Notes**
+- Similar to Columns but for vertical layouts
+- Extends GridContainer with all its props
+- Use for vertical stacking with specific row heights
+
+---
+
+### Horizontal
+- **Path:** `~/src/grid`
+- **Description:** Grid container with automatic column flow for horizontal layouts
+- **Interface:** `Horizontal<GridContainerProps>`
+
+**Example**
+```tsx
+<Horizontal $justifyContent="start" $gap={8}>
+  <Button>One</Button>
+  <Button>Two</Button>
+  <Button>Three</Button>
+</Horizontal>
+```
+
+**Notes**
+- Pre-configured with `gridAutoFlow: 'column'`
+- Perfect for button groups, inline elements, or navigation items
+- Inherits all GridContainer props
+- Items flow horizontally automatically
+
+---
+
+### Vertical
+- **Path:** `~/src/grid`
+- **Description:** Grid container with automatic row flow for vertical layouts
+- **Interface:** `Vertical<GridContainerProps>`
+
+**Example**
+```tsx
+<Vertical $gap={10}>
+  <Header />
+  <Content />
+  <Footer />
+</Vertical>
+```
+
+**Notes**
+- Pre-configured with `gridAutoFlow: 'row'`
+- Default behavior for vertical stacking
+- Inherits all GridContainer props
+- Use when you need explicit vertical flow control
+
+---
+
+### Collapse
+- **Path:** `~/src/expand`
+- **Description:** Animated collapsible component with height transition
+- **Interface:** `Collapse<{ expanded: boolean; timeout?: number; className?: string; internalClassName?: string; children: (() => ReactNode) | ReactNode; }>`
+
+**Props**
+
+| Name | Type | Required | Default | Description |
+|---|---|:---:|:---:|---|
+| `expanded` | boolean | ✓ |  | Controls whether content is visible or collapsed |
+| `timeout` | number |  | `100` | Animation duration in milliseconds |
+| `className` | string |  |  | CSS class for the outer wrapper |
+| `internalClassName` | string |  |  | CSS class for the inner content wrapper |
+| `children` | function\|ReactNode | ✓ |  | Content to show/hide, can be render function for lazy rendering |
+
+**Examples**
+```tsx
+<Collapse expanded={isOpen}>
+  <div>Collapsible content here</div>
+</Collapse>
+```
+```tsx
+<Collapse expanded={isOpen}>
+  {() => <ExpensiveComponent />}
+</Collapse>
+```
+
+**Notes**
+- Uses `react-transition-group` for animations
+- Height is calculated dynamically from content
+- Function children enable lazy rendering for performance
+- Smooth height and opacity transitions
+- Content is removed from DOM when collapsed
+
+---
+
+### ExpandTransition
+- **Path:** `~/src/expand`
+- **Description:** Advanced expand/collapse transition with zoom effect
+- **Interface:** `ExpandTransition<{ timeout?: number; className?: string; externalClassName?: string; internalClassName?: string; }>`
+
+**Props**
+
+| Name | Type | Required | Default | Description |
+|---|---|:---:|:---:|---|
+| `timeout` | number |  | `100` | Animation duration in milliseconds |
+| `className` | string |  |  | Base CSS class for transition states |
+| `externalClassName` | string |  |  | Additional class for outer wrapper |
+| `internalClassName` | string |  |  | Class for inner content wrapper |
+
+**Example**
+```tsx
+<TransitionGroup component={null}>
+  {visible && (
+    <ExpandTransition key={0}>
+      <Card>Content</Card>
+    </ExpandTransition>
+  )}
+</TransitionGroup>
+```
+
+**Notes**
+- Must be used with `TransitionGroup` from `react-transition-group`
+- Creates zoom-in/zoom-out effect with position animation
+- More complex than Collapse, use for special UI effects
+- Requires `key` prop when used in TransitionGroup
+
+---
+
+## Hooks
+
+### useClickAway
+- **Path:** `~/src/hooks/useClickAway`
+- **Description:** Detects clicks outside a referenced element and triggers a callback
+- **Signature:**
+```ts
+useClickAway<T extends HTMLElement>(
+  use: boolean,
+  ref: RefObject<T | null>,
+  cb: (event: MouseEvent | TouchEvent) => void
+): void
+```
+
+**Params:** `use` – enable/disable; `ref` – target element ref; `cb` – callback on outside click
+
+**Returns:** `void`
+
+**Example**
+```tsx
+const ref = useRef<HTMLDivElement>(null);
+useClickAway(isOpen, ref, () => setIsOpen(false));
+```
+
+**Notes**
+- Handles both mouse and touch events
+- Callback is persisted to avoid re-subscriptions
+- Can be toggled on/off with `use` parameter
+- Perfect for dropdowns, modals, and popovers
+- Automatically cleans up event listeners
+
+---
+
+### usePersistentFunction
+- **Path:** `~/src/hooks/usePersistentFunction`
+- **Description:** Creates a stable function reference that always calls the latest version of a callback
+- **Signature:**
+```ts
+usePersistentFunction<Args extends any[], Return>(
+  callback: (...args: Args) => Return
+): (...args: Args) => Return
+```
+
+**Example**
+```tsx
+const stableHandler = usePersistentFunction(() => {
+  console.log(currentState); // Always uses latest state
+});
+```
+
+**Notes**
+- Prevents unnecessary re-renders in child components
+- Always executes the latest callback version
+- Alternative to `useCallback` with empty deps
+- Ideal for event handlers and effect cleanup functions
+- Maintains referential equality across renders
+
+---
+
+### useAsync
+- **Path:** `~/src/hooks/useAsync`
+- **Description:** Automatically executes an async function and manages its state
+- **Signature:**
+```ts
+useAsync<T extends FunctionReturningPromise>(fn: T, deps?: DependencyList): AsyncState<T>
+```
+
+**Example**
+```tsx
+const { loading, error, value } = useAsync(
+  () => fetchUserData(userId),
+  [userId]
+);
+```
+
+**Notes**
+- Executes immediately on mount and when deps change
+- Handles loading states automatically
+- Catches and exposes errors
+- Starts with `loading: true`
+- Re-runs when dependencies change
+
+---
+
+### useAsyncFn
+- **Path:** `~/src/hooks/useAsyncFn`
+- **Description:** Returns an async function wrapper with state management
+- **Signature:**
+```ts
+useAsyncFn<T extends FunctionReturningPromise>(
+  fn: T,
+  deps?: DependencyList,
+  initialState?: AsyncState<T>
+): [AsyncState<T>, (p?: CallbackParams) => ReturnType<T>]
+```
+
+**Example**
+```tsx
+const [state, doFetch] = useAsyncFn(
+  () => api.saveData(data),
+  [data]
+);
+// Later: doFetch({ reset: true });
+```
+
+**Notes**
+- Manual trigger unlike `useAsync`
+- Returns both state and executable function
+- Supports `reset` option to clear previous state
+- Prevents race conditions with call tracking
+- Safe to use with unmounted components
+
+---
+
+### useAsyncFunction
+- **Path:** `~/src/hooks/useAsyncFunction`
+- **Description:** Creates a persistent async function with state tracking and call counting
+- **Signature:**
+```ts
+useAsyncFunction<T extends FunctionReturningPromise>(fn: T): [AsyncFunctionState<T>, T]
+```
+
+**Example**
+```tsx
+const [state, saveUser] = useAsyncFunction(async (user) => {
+  return api.saveUser(user);
+});
+// state.count tracks number of calls
+```
+
+**Notes**
+- Includes call counter in state
+- Function reference is always stable
+- Tracks loading state per call
+- Useful for forms and repeated actions
+- Prevents state updates on unmounted components
+
+---
+
+### useEffectOnce
+- **Path:** `~/src/hooks/useEffectOnce`
+- **Description:** Runs an effect only once on mount
+- **Signature:** `useEffectOnce(effect: EffectCallback): void`
+
+**Example**
+```tsx
+useEffectOnce(() => {
+  initializeApp();
+  return () => cleanup();
+});
+```
+
+**Notes**
+- Equivalent to `useEffect` with empty deps
+- Cleaner API for one-time setup
+- Supports cleanup function return
+- Use for initialization logic
+
+---
+
+### useMount
+- **Path:** `~/src/hooks/useMount`
+- **Description:** Runs a function on component mount
+- **Signature:** `useMount(fn: () => void): void`
+
+**Example**
+```tsx
+useMount(() => {
+  console.log('Component mounted');
+});
+```
+
+**Notes**
+- Simpler than `useEffectOnce` when no cleanup needed
+- Only for side effects on mount
+- No return value expected
+
+---
+
+### useUnmount
+- **Path:** `~/src/hooks/useUnmount`
+- **Description:** Runs a function on component unmount
+- **Signature:** `useUnmount(fn: () => any): void`
+
+**Example**
+```tsx
+useUnmount(() => {
+  saveProgress();
+  disconnectSocket();
+});
+```
+
+**Notes**
+- Always uses latest version of cleanup function
+- Perfect for cleanup operations
+- Saves form data, closes connections, etc.
+- Function ref is updated each render
+
+---
+
+### useMountedState
+- **Path:** `~/src/hooks/useMountedState`
+- **Description:** Returns a function that checks if component is still mounted
+- **Signature:** `useMountedState(): () => boolean`
+
+**Example**
+```tsx
+const isMounted = useMountedState();
+
+setTimeout(() => {
+  if (isMounted()) {
+    setState(newValue);
+  }
+}, 1000);
+```
+
+**Notes**
+- Prevents state updates on unmounted components
+- Essential for async operations
+- Check before `setState` in callbacks
+- Stable function reference
+
+---
+
+### useDelayedValue
+- **Path:** `~/src/hooks/useDelayedValue`
+- **Description:** Delays value updates by specified milliseconds
+- **Signature:** `useDelayedValue<T>(value: T, delay: number): T`
+
+**Example**
+```tsx
+const debouncedSearch = useDelayedValue(searchTerm, 300);
+useEffect(() => {
+  performSearch(debouncedSearch);
+}, [debouncedSearch]);
+```
+
+**Notes**
+- Acts as a debounce for value changes
+- Useful for search inputs and API calls
+- Cancels pending updates on new values
+- Returns initial value immediately
+
+---
+
+### useDelayedEffect
+- **Path:** `~/src/hooks/useDelayedEffect`
+- **Description:** Runs an effect after a delay with cancellation support
+- **Signature:**
+```ts
+useDelayedEffect(
+  effect: (getIsRunning: () => boolean) => void,
+  deps: DependencyList,
+  delay: number
+): void
+```
+
+**Example**
+```tsx
+useDelayedEffect(
+  (getIsRunning) => {
+    if (getIsRunning()) {
+      performExpensiveOperation();
+    }
+  },
+  [data],
+  500
+);
+```
+
+**Notes**
+- Provides cancellation check via `getIsRunning`
+- Clears timeout on deps change or unmount
+- Useful for debounced side effects
+- Check `getIsRunning()` before state updates
+
+---
+
+## Utilities
+
+### formatNumber
+- **Path:** `~/src/formatNumber`
+- **Description:** Formats numbers with spacing or short notation
+- **Signature:** `formatNumber(number: number, format: 'spaced' | 'short'): string`
+
+**Examples**
+```ts
+formatNumber(1234567, 'spaced') // '1 234 567'
+formatNumber(1234567, 'short')  // '1.2M'
+formatNumber(999, 'short')      // '999'
+```
+
+**Notes**
+- `spaced`: Adds spaces every 3 digits
+- `short`: Uses K, M, B notation above 10,000
+- Short format keeps one decimal place
+- Numbers below 10K in short format use spaced display
+- Ideal for statistics and dashboards
+
+---
+
+### toCssValue
+- **Path:** `~/src/grid`
+- **Description:** Converts number to px string or returns string as-is
+- **Signature:** `toCssValue(value: string | number): string`
+
+**Examples**
+```ts
+toCssValue(16)      // '16px'
+toCssValue('2rem')  // '2rem'
+```
+
+**Notes**
+- Used internally by grid components
+- Numbers become pixels
+- Strings pass through unchanged
+- Enables flexible prop values
+
+---
+
+### elementAddListeners
+- **Path:** `~/src/hooks/useClickAway`
+- **Description:** Adds event listeners to elements with cleanup function
+- **Signature:**
+```ts
+elementAddListeners<
+  K extends keyof HTMLElementEventMap,
+  E extends HTMLElement
+>(element: E | Document, eventNames: K | K[], listener: EventListener): () => void
+```
+
+**Example**
+```ts
+const cleanup = elementAddListeners(
+  document,
+  ['mousedown', 'touchstart'],
+  handleClick
+);
+```
+
+**Notes**
+- Returns cleanup function
+- Supports multiple event types
+- Works with `Document` or `HTMLElement`
+- Used internally by `useClickAway`
+
+---
+
+### subscribeClickAway
+- **Path:** `~/src/hooks/useClickAway`
+- **Description:** Subscribes to clicks outside an element
+- **Signature:**
+```ts
+subscribeClickAway<T extends HTMLElement>(
+  element: T,
+  callback: (event: MouseEvent | TouchEvent) => void
+): () => void
+```
+
+**Example**
+```ts
+const unsubscribe = subscribeClickAway(dropdownEl, () => closeDropdown());
+```
+
+**Notes**
+- Standalone version of `useClickAway` logic
+- Returns unsubscribe function
+- Handles mouse and touch events
+- Can be used outside React components
+
+---
+
+## Types
+
+### StrNum
+- **Definition:** `type StrNum = string | number`
+- **Description:** Union type for CSS values that can be string or number
+
+### CssBoxSides
+- **Definition:**
+```ts
+type CssBoxSides<T> =
+  | { top?: T; right?: T; bottom?: T; left?: T }
+  | { horizontal: T; top?: T; bottom?: T }
+  | { vertical: T; right?: T; left?: T }
+```
+- **Description:** Flexible type for directional CSS properties like margin/padding
+
+### AsyncState
+- **Definition:** `type AsyncState<T> = { loading: boolean; error?: Error; value?: T }`
+- **Description:** State shape for async operations with loading, error, and value
+
+### FunctionReturningPromise
+- **Definition:** `type FunctionReturningPromise = (...args: any[]) => Promise<any>`
+- **Description:** Generic type for any async function
+
+### PromiseType
+- **Definition:** `type PromiseType<P extends Promise<any>> = P extends Promise<infer T> ? T : never`
+- **Description:** Extracts the resolved type from a Promise
+
+---
+
+## Patterns
+
+### styledComponentProps
+- **Description:** All styled-component props are prefixed with `$` to avoid React prop warnings
+- **Example:** `$gap, $padding, $margin` instead of `gap, padding, margin`
+
+### lazyRendering
+- **Description:** Components accept function children for deferred rendering
+- **Example:** `<Collapse expanded={show}>{() => <ExpensiveComponent />}</Collapse>`
+
+### persistentCallbacks
+- **Description:** Use `usePersistentFunction` to maintain stable references while using latest closure values
+- **Example:** `const stable = usePersistentFunction(callback)`
+
+### asyncStateManagement
+- **Description:** Consistent async state shape with loading, error, and value properties
+- **Example:** All async hooks return `{ loading, error, value }` state
+
+---
+
+## Best Practices
+- Use specific layout components (Columns, Horizontal, Vertical) over generic GridContainer
+- Prefix all styled-component props with `$` to avoid DOM prop warnings
+- Use `usePersistentFunction` for callbacks passed to memoized components
+- Check `isMounted()` before state updates in async operations
+- Use function children in `Collapse` for expensive components
+- Leverage TypeScript's discriminated unions in `AsyncState` for type safety
+- Use `useDelayedValue` for debouncing user input
+- Combine `useClickAway` with portals for robust dropdown behavior

package/hooks/useClickAway.d.ts

@@ -1,3 +1,27 @@
-export declare function elementAddListener<K extends keyof HTMLElementEventMap, E extends HTMLElement>(element: E, eventNames: K | K[], listener: (this: HTMLElement, ev: HTMLElementEventMap[K]) => void): () => void;
-export declare function subscribeClickAway<T extends HTMLElement>(element: T, callback: EventListener): () => void;
-export declare function useClickAway(use: boolean, ref: any, cb: EventListener): void;
+import { type RefObject } from 'react';
+type ClickAwayCallback = (event: MouseEvent | TouchEvent) => void;
+/**
+ * Adds event listeners to an element and returns a cleanup function.
+ * @param element The target HTML element.
+ * @param eventNames The event name(s) to listen for.
+ * @param listener The callback function to execute when the event occurs.
+ * @returns A function to remove the added event listeners.
+ */
+export declare function elementAddListeners<K extends keyof HTMLElementEventMap, E extends HTMLElement>(element: E | Document, // Allow Document as well
+eventNames: K | K[], listener: (this: E | Document, ev: HTMLElementEventMap[K]) => void): () => void;
+/**
+ * Subscribes to mousedown/touchstart events outside a given element.
+ * @param element The element to detect clicks away from.
+ * @param callback The function to call when a click away is detected.
+ * @returns A function to unsubscribe the listeners.
+ */
+export declare function subscribeClickAway<T extends HTMLElement>(element: T, callback: ClickAwayCallback): () => void;
+/**
+ * Custom hook to trigger a callback when a click occurs outside the referenced element.
+ * @param use Whether the hook is active.
+ * @param ref A React ref object pointing to the target HTMLElement.
+ * @param cb The callback function to execute on a click away.
+ */
+export declare function useClickAway<T extends HTMLElement>(use: boolean, ref: RefObject<T | null>, // Use RefObject<T | null> for better type safety
+cb: ClickAwayCallback): void;
+export {};

package/hooks/useClickAway.js

@@ -1,28 +1,59 @@
 import { useEffect } from 'react';
 import usePersistentFunction from './usePersistentFunction';
-export function elementAddListener(element, eventNames, listener) {
+/**
+ * Adds event listeners to an element and returns a cleanup function.
+ * @param element The target HTML element.
+ * @param eventNames The event name(s) to listen for.
+ * @param listener The callback function to execute when the event occurs.
+ * @returns A function to remove the added event listeners.
+ */
+export function elementAddListeners(element,
+// Allow Document as well
+eventNames, listener) {
   const eventNamesArray = Array.isArray(eventNames) ? eventNames : [eventNames];
   eventNamesArray.forEach(eventName => {
-    element.addEventListener(eventName, listener);
+    element.addEventListener(eventName, listener); // Cast needed as addEventListener expects EventListener
   });
   return () => {
     eventNamesArray.forEach(eventName => {
-      element.removeEventListener(eventName, listener);
+      element.removeEventListener(eventName, listener); // Cast needed as removeEventListener expects EventListener
     });
   };
 }
+/**
+ * Subscribes to mousedown/touchstart events outside a given element.
+ * @param element The element to detect clicks away from.
+ * @param callback The function to call when a click away is detected.
+ * @returns A function to unsubscribe the listeners.
+ */
 export function subscribeClickAway(element, callback) {
-  return elementAddListener(document, ['mousedown', 'touchstart'], event => {
-    if (element && !element.contains(event.target)) {
-      callback(event);
+  // Use document directly, no need for 'any' cast
+  return elementAddListeners(document, ['mousedown', 'touchstart'], event => {
+    // Type assertion for event target
+    const target = event.target;
+    // Check if the element exists and the click target is outside the element
+    if (element && !element.contains(target)) {
+      callback(event); // Assert event type for the callback
     }
   });
 }
-export function useClickAway(use, ref, cb) {
-  const mcb = usePersistentFunction(cb);
+/**
+ * Custom hook to trigger a callback when a click occurs outside the referenced element.
+ * @param use Whether the hook is active.
+ * @param ref A React ref object pointing to the target HTMLElement.
+ * @param cb The callback function to execute on a click away.
+ */
+export function useClickAway(use, ref,
+// Use RefObject<T | null> for better type safety
+cb) {
+  // Persist the callback function to avoid re-subscribing on every render
+  const persistentCb = usePersistentFunction(cb);
+  // eslint-disable-next-line consistent-return
   useEffect(() => {
-    if (use) {
-      return subscribeClickAway(ref.current, mcb);
+    // Only subscribe if the hook is active and the ref points to an element
+    if (use && ref.current) {
+      // Return the cleanup function directly
+      return subscribeClickAway(ref.current, persistentCb);
     }
-  }, [use, ref, mcb]);
+  }, [use, ref, persistentCb]);
 }

package/hooks/usePersistentFunction.d.ts

@@ -1 +1,47 @@
-export default function usePersistentFunction<T extends (...args: any[]) => any>(callback: T): T;
+/**
+ * Creates a stable function reference that always calls the latest version of a callback.
+ *
+ * This hook is useful when you need to pass a callback to a child component or as a dependency
+ * to another hook, but want to avoid unnecessary re-renders when the callback changes.
+ *
+ * Unlike using plain `useCallback`, this approach ensures that the latest version of the
+ * callback is always used, even if the reference remains stable.
+ *
+ * @param callback - The function that should be persisted
+ * @returns A stable function reference that will always call the most recent version of the provided callback
+ *
+ * @example
+ * // Using with event handlers
+ * const MyComponent = () => {
+ *   const [count, setCount] = useState(0);
+ *
+ *   // This function reference remains stable across renders
+ *   // but will always use the current value of `count`
+ *   const handleClick = usePersistentFunction(() => {
+ *     console.log(`Current count: ${count}`);
+ *   });
+ *
+ *   return <ChildComponent onClick={handleClick} />;
+ * };
+ *
+ * @example
+ * // Using with cleanup functions
+ * const MyComponent = () => {
+ *   const [resource, setResource] = useState(null);
+ *
+ *   // The cleanup function remains stable but always uses the latest resource
+ *   const cleanup = usePersistentFunction(() => {
+ *     if (resource) {
+ *       resource.dispose();
+ *     }
+ *   });
+ *
+ *   useEffect(() => {
+ *     // Some setup code...
+ *     return cleanup;
+ *   }, []); // No need to include cleanup in dependencies
+ *
+ *   return <div>...</div>;
+ * };
+ */
+export default function usePersistentFunction<Args extends any[], Return>(callback: (...args: Args) => Return): (...args: Args) => Return;

package/hooks/usePersistentFunction.js

@@ -1,6 +1,55 @@
 import { useCallback, useRef } from 'react';
+/**
+ * Creates a stable function reference that always calls the latest version of a callback.
+ *
+ * This hook is useful when you need to pass a callback to a child component or as a dependency
+ * to another hook, but want to avoid unnecessary re-renders when the callback changes.
+ *
+ * Unlike using plain `useCallback`, this approach ensures that the latest version of the
+ * callback is always used, even if the reference remains stable.
+ *
+ * @param callback - The function that should be persisted
+ * @returns A stable function reference that will always call the most recent version of the provided callback
+ *
+ * @example
+ * // Using with event handlers
+ * const MyComponent = () => {
+ *   const [count, setCount] = useState(0);
+ *
+ *   // This function reference remains stable across renders
+ *   // but will always use the current value of `count`
+ *   const handleClick = usePersistentFunction(() => {
+ *     console.log(`Current count: ${count}`);
+ *   });
+ *
+ *   return <ChildComponent onClick={handleClick} />;
+ * };
+ *
+ * @example
+ * // Using with cleanup functions
+ * const MyComponent = () => {
+ *   const [resource, setResource] = useState(null);
+ *
+ *   // The cleanup function remains stable but always uses the latest resource
+ *   const cleanup = usePersistentFunction(() => {
+ *     if (resource) {
+ *       resource.dispose();
+ *     }
+ *   });
+ *
+ *   useEffect(() => {
+ *     // Some setup code...
+ *     return cleanup;
+ *   }, []); // No need to include cleanup in dependencies
+ *
+ *   return <div>...</div>;
+ * };
+ */
 export default function usePersistentFunction(callback) {
-  const ref = useRef(callback);
-  ref.current = callback;
-  return useCallback((...args) => ref.current(...args), []);
+  // Store the latest callback in a ref
+  const callbackRef = useRef(callback);
+  // Update the ref to the latest callback on each render
+  callbackRef.current = callback;
+  // Create a stable function reference that calls the latest callback
+  return useCallback((...args) => callbackRef.current(...args), []);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pushwoosh/kit-helpers",
-  "version": "4.8.2",
+  "version": "4.8.4",
   "description": "React component for build Pushwoosh products",
   "main": "index.js",
   "module": "index.js",
@@ -8,7 +8,7 @@
   "sideEffects": false,
   "scripts": {
     "start": "npm run playground",
-    "build": "pushwoosh-engine lib:build",
+    "build": "pushwoosh-engine lib:build && cp ai-documentation.mdx dist/ai-documentation.mdx",
     "playground": "pushwoosh-engine lib:playground",
     "check": "npm run check:lint && npm run check:types",
     "check:lint": "echo \"Run check:lint\" && eslint .",