@pushwoosh/kit-helpers 4.12.3 → 4.12.4

package/ai-documentation.md

@@ -1,838 +0,0 @@
-
-
----
-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 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' | 'baseline';
-  $alignItems?: 'center' | 'start' | 'end' | 'baseline' | 'stretch';
-  $basis?: StrNum;
-  $bgColor?: string;
-  $border?: string | CssBoxSides<string>;
-  $borderRadius?: StrNum;
-  $bottom?: StrNum;
-  $boxShadow?: string;
-  $flex?: StrNum;
-  $gap?: StrNum;
-  $gridAutoFlow?: 'row' | 'column' | 'dense' | 'row dense' | 'column dense';
-  $grow?: number;
-  $height?: StrNum;
-  $inset?: StrNum;
-  $justifyContent?: 'center' | 'start' | 'end' | 'space-between' | 'space-around' | 'space-evenly' | 'stretch';
-  $justifyItems?: 'center' | 'start' | 'end' | 'baseline' | 'stretch';
-  $left?: StrNum;
-  $margin?: StrNum | CssBoxSides<StrNum>;
-  $maxHeight?: StrNum;
-  $maxWidth?: StrNum;
-  $minHeight?: StrNum;
-  $minWidth?: StrNum;
-  $overflow?: 'hidden' | 'auto' | 'scroll' | 'visible';
-  $overflowX?: 'hidden' | 'auto' | 'scroll' | 'visible';
-  $overflowY?: 'hidden' | 'auto' | 'scroll' | 'visible';
-  $padding?: StrNum | CssBoxSides<StrNum>;
-  $placeItems?: 'center' | 'start' | 'end' | 'baseline' | 'stretch';
-  $position?: 'static' | 'relative' | 'absolute' | 'fixed' | 'sticky';
-  $right?: StrNum;
-  $shrink?: number;
-  $top?: StrNum;
-  $width?: StrNum;
-  $zIndex?: number;
-}>
-```
-
-**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`, `baseline` |
-| `$alignItems` | enum |  |  | Aligns grid items along the cross axis | `center`, `start`, `end`, `baseline`, `stretch` |
-| `$basis` | string\|number |  |  | `flex-basis` (only effective when parent is a flex container; number → px) | |
-| `$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 | |
-| `$bottom` | string\|number |  |  | `bottom` offset (number → px) | |
-| `$boxShadow` | string |  |  | CSS box shadow property | |
-| `$flex` | string\|number |  |  | `flex` shorthand (only effective when parent is a flex container) | |
-| `$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` |
-| `$grow` | number |  |  | `flex-grow` (only effective when parent is a flex container) | |
-| `$height` | string\|number |  |  | `height` (number → px; strings like `'100%'` / `'auto'` / `'fit-content'` pass through) | |
-| `$inset` | string\|number |  |  | `inset` CSS shorthand (number → px, string passes through, e.g. `'10px 20px'`) | |
-| `$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` |
-| `$left` | string\|number |  |  | `left` offset (number → px) | |
-| `$margin` | object |  |  | Margin spacing, can be number/string or object with directional properties | |
-| `$maxHeight` | string\|number |  |  | `max-height` (number → px) | |
-| `$maxWidth` | string\|number |  |  | `max-width` (number → px) | |
-| `$minHeight` | string\|number |  |  | `min-height` (number → px) | |
-| `$minWidth` | string\|number |  |  | `min-width` (number → px) | |
-| `$overflow` | enum |  |  | `overflow` | `hidden`, `auto`, `scroll`, `visible` |
-| `$overflowX` | enum |  |  | `overflow-x` | `hidden`, `auto`, `scroll`, `visible` |
-| `$overflowY` | enum |  |  | `overflow-y` | `hidden`, `auto`, `scroll`, `visible` |
-| `$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`, `baseline`, `stretch` |
-| `$position` | enum |  |  | `position` | `static`, `relative`, `absolute`, `fixed`, `sticky` |
-| `$right` | string\|number |  |  | `right` offset (number → px) | |
-| `$shrink` | number |  |  | `flex-shrink` (only effective when parent is a flex container) | |
-| `$top` | string\|number |  |  | `top` offset (number → px) | |
-| `$width` | string\|number |  |  | `width` (number → px; strings pass through) | |
-| `$zIndex` | number |  |  | `z-index` | |
-
-**Examples**
-```tsx
-<GridContainer $gap={16} $padding={20} $bgColor="#f0f0f0">
-  <div>Item 1</div>
-  <div>Item 2</div>
-</GridContainer>
-```
-```tsx
-// Absolute tooltip
-<GridContainer $position="absolute" $top={40} $left={20} $width={350} $zIndex={10}>
-  <Tooltip />
-</GridContainer>
-```
-```tsx
-// Stretch horizontally
-<GridContainer $position="absolute" $left={0} $right={0} $bottom={0}>
-  <Footer />
-</GridContainer>
-```
-```tsx
-// Scrollable region
-<GridContainer $padding={16} $maxHeight={400} $overflow="auto">
-  ...
-</GridContainer>
-```
-
-**Notes**
-- All props are prefixed with `$` to indicate they are styled-component props
-- Numbers are automatically converted to `px` units; strings (e.g. `'100%'`, `'fit-content'`, `'2rem'`) pass through unchanged
-- Use `CssBoxSides` for asymmetric margin/padding/border
-- `$inset` maps directly to the CSS `inset` shorthand; for per-side control use individual `$top` / `$right` / `$bottom` / `$left`
-- 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
-
----
-
-### FlexContainer
-- **Path:** `~/src/flex`
-- **Description:** Base flex container component using CSS Flexbox for one-dimensional layouts
-- **Interface:**
-```ts
-FlexContainer<{
-  // Layout (flex-specific)
-  $flexDirection?: 'row' | 'row-reverse' | 'column' | 'column-reverse';
-  $flexWrap?: 'nowrap' | 'wrap' | 'wrap-reverse';
-  // Container alignment (shared with GridContainer)
-  $alignContent?: 'center' | 'start' | 'end' | 'space-between' | 'space-around' | 'space-evenly' | 'stretch' | 'baseline';
-  $alignItems?: 'center' | 'start' | 'end' | 'baseline' | 'stretch';
-  $gap?: StrNum;
-  $justifyContent?: 'center' | 'start' | 'end' | 'space-between' | 'space-around' | 'space-evenly' | 'stretch';
-  // Plus all CommonBoxProps: sizing ($width/$height/$min*/$max*), spacing ($padding/$margin),
-  // appearance ($bgColor/$border/$borderRadius/$boxShadow), position ($position/$top/$right/$bottom/$left/$inset/$zIndex),
-  // overflow ($overflow/$overflowX/$overflowY), flex-item ($flex/$grow/$shrink/$basis)
-}>
-```
-
-**Props**
-
-| Name | Type | Required | Default | Description | Values |
-|---|---|:---:|:---:|---|---|
-| `$flexDirection` | enum |  | `row` (browser default) | `flex-direction` — main axis direction | `row`, `row-reverse`, `column`, `column-reverse` |
-| `$flexWrap` | enum |  | `nowrap` (browser default) | `flex-wrap` — whether items wrap onto multiple lines | `nowrap`, `wrap`, `wrap-reverse` |
-
-Plus everything from `CommonContainerProps` (`$alignContent`, `$alignItems`, `$justifyContent`, `$gap`) and `CommonBoxProps` — see `GridContainer` props table for the full shared list. Grid-specific props (`$gridAutoFlow`, `$justifyItems`, `$placeItems`) are NOT available on `FlexContainer`.
-
-**Examples**
-```tsx
-<FlexContainer $gap={8} $alignItems="center">
-  <Icon />
-  <span>Label</span>
-</FlexContainer>
-```
-```tsx
-// Column with growing child filling remaining space
-<FlexContainer $flexDirection="column" $height="100vh">
-  <Header />
-  <Main $flex={1} $overflow="auto" />
-  <Footer />
-</FlexContainer>
-```
-
-**Notes**
-- Use when items have content-driven sizes or need to wrap; prefer `GridContainer` for explicit 2D tracks
-- Children can use `$flex` / `$grow` / `$shrink` / `$basis` from `CommonBoxProps` to control sizing — this works on any `GridContainer`/`FlexContainer` child too
-- Prefer the `Cluster` preset for wrap-based layouts (tags/chips)
-
----
-
-### Cluster
-- **Path:** `~/src/flex`
-- **Description:** Flex container with wrapping enabled — for tag/chip/badge groups
-- **Interface:** `Cluster<FlexContainerProps>`
-
-**Example**
-```tsx
-<Cluster $gap={8}>
-  {tags.map((tag) => <Tag key={tag.id}>{tag.label}</Tag>)}
-</Cluster>
-```
-
-**Notes**
-- Pre-configured with `$flexWrap: 'wrap'`
-- Inherits all `FlexContainer` props (override `$flexWrap` if needed)
-- Perfect for chip/tag rows that need to wrap on narrow widths
-
----
-
-### 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/styled-helpers` (also re-exported from `~/src/grid` for back-compat)
-- **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 and flex 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:**
-```typescript
-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
-
-### CommonBoxProps
-- **Path:** `~/src/styled-helpers`
-- **Description:** Shared box-model/positioning/flex-item props consumed by both `GridContainer` and `FlexContainer`. Covers sizing (`$width`, `$height`, `$minWidth`/`$minHeight`, `$maxWidth`/`$maxHeight`), spacing (`$padding`, `$margin`), appearance (`$bgColor`, `$border`, `$borderRadius`, `$boxShadow`), position (`$position`, `$top`/`$right`/`$bottom`/`$left`, `$inset`, `$zIndex`), overflow (`$overflow`/`$overflowX`/`$overflowY`), and flex-item sizing (`$flex`, `$grow`, `$shrink`, `$basis`)
-
-### CommonContainerProps
-- **Path:** `~/src/styled-helpers`
-- **Definition:** `CommonBoxProps & { $alignContent?: AlignContentValue; $alignItems?: ItemAlignmentValue; $gap?: StrNum; $justifyContent?: JustifyContentValue }`
-- **Description:** Extends `CommonBoxProps` with alignment props that work in both grid and flex contexts. Used as the base for `GridContainer` and `FlexContainer` props
-
-### ItemAlignmentValue
-- **Path:** `~/src/styled-helpers`
-- **Definition:** `'center' | 'start' | 'end' | 'baseline' | 'stretch'`
-- **Description:** Valid values for item-level alignment props: `$alignItems`, `$justifyItems`, `$placeItems`
-
-### JustifyContentValue
-- **Path:** `~/src/styled-helpers`
-- **Definition:** `'center' | 'start' | 'end' | 'space-between' | 'space-around' | 'space-evenly' | 'stretch'`
-- **Description:** Valid values for `$justifyContent`. Per CSS Box Alignment L3, `justify-content` does NOT accept `baseline` — use `AlignContentValue` for `$alignContent`
-
-### AlignContentValue
-- **Path:** `~/src/styled-helpers`
-- **Definition:** `JustifyContentValue | 'baseline'`
-- **Description:** Valid values for `$alignContent`. Same as `JustifyContentValue` plus `baseline` (which is spec-valid only for the cross-axis content distribution)
-
-### 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
-- Use the `Cluster` preset for wrap-based layouts; reach for `FlexContainer` for everything else
-- Prefer `FlexContainer` over `GridContainer` when item sizes are content-driven or you need wrapping; prefer Grid when you have explicit row/column tracks
-- Set `$flex` / `$grow` / `$shrink` / `$basis` on any `GridContainer`/`FlexContainer` child to control its size inside a flex parent — no extra wrapper needed
-- 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