@codeleap/web 6.3.0 → 7.0.0

package/src/lib/hooks/useAsyncSelect.ts

@@ -0,0 +1,126 @@
+import React, { useState, useId, useCallback } from 'react'
+import { useQuery, type UseQueryOptions, type UseQueryResult } from '@tanstack/react-query'
+import { type ICSS } from '@codeleap/styles'
+
+/** Shape that `load` must resolve to in `useAsyncSelect`. */
+export type AsyncSelectLoadResult<TOption> = {
+  data: any
+  results: TOption[]
+}
+
+/** Options for `useAsyncSelect`. */
+export type UseAsyncSelectOptions<
+  TOption extends { label: string; value: any },
+  TQuery = string
+> = {
+  queryKey?: readonly unknown[]
+  load: (query: TQuery) => Promise<AsyncSelectLoadResult<TOption>>
+  /**
+   * Controls when load() is triggered. Defaults to non-empty/non-null check.
+   * Pass `() => true` to load on mount with an empty query.
+   */
+  isSearchValid?: (query: TQuery) => boolean
+  renderError?: (error: unknown, style: ICSS) => React.ReactNode
+  renderNoResults?: (query: TQuery, style: ICSS) => React.ReactNode
+  renderLoading?: (style: ICSS) => React.ReactNode
+  queryOptions?: Omit<
+    UseQueryOptions<AsyncSelectLoadResult<TOption>, Error>,
+    'queryKey' | 'queryFn' | 'enabled'
+  >
+}
+
+type SelectCompatibleProps<TOption extends { label: string; value: any }> = {
+  options: TOption[]
+  renderEmpty: (props: { style: ICSS }) => React.ReactNode
+}
+
+type AsyncSelectState<TOption extends { label: string; value: any }, TQuery> = {
+  query: (q: TQuery) => void
+  searchQuery: TQuery
+  data: any
+  isLoading: boolean
+  error: unknown
+  queryResult: UseQueryResult<AsyncSelectLoadResult<TOption>, Error>
+}
+
+/**
+ * Tuple returned by `useAsyncSelect`.
+ * Index 0 contains the props to spread onto a `Select` component;
+ * index 1 exposes the raw query state and the underlying `useQuery` result.
+ */
+export type UseAsyncSelectReturn<
+  TOption extends { label: string; value: any },
+  TQuery
+> = [SelectCompatibleProps<TOption>, AsyncSelectState<TOption, TQuery>]
+
+/**
+ * Wraps TanStack Query to power a search-driven async Select component.
+ *
+ * Returns a `[selectProps, state]` tuple. Spread the first element onto a
+ * `Select` component; use the second to drive the search query and inspect
+ * loading / error state.
+ *
+ * The query is gated by `isSearchValid` (defaults to non-empty/non-null).
+ * Pass `isSearchValid: () => true` to fetch on mount with an empty query.
+ * Requires a TanStack Query `QueryClientProvider` in the tree.
+ */
+export function useAsyncSelect<
+  TOption extends { label: string; value: any },
+  TQuery = string
+>(
+  opts: UseAsyncSelectOptions<TOption, TQuery>
+): UseAsyncSelectReturn<TOption, TQuery> {
+  const {
+    load, isSearchValid, renderError, renderNoResults, renderLoading, queryOptions,
+  } = opts
+
+  const hookId = useId()
+  const baseKey = opts.queryKey ?? [hookId]
+
+  const [searchQuery, setSearchQuery] = useState<TQuery>('' as TQuery)
+
+  const defaultIsValid = (q: TQuery) => q != null && q !== ('' as TQuery)
+  const enabled = isSearchValid ? isSearchValid(searchQuery) : defaultIsValid(searchQuery)
+
+  const queryResult = useQuery({
+    queryKey: ['asyncSelect', ...baseKey, searchQuery],
+    queryFn: () => load(searchQuery),
+    enabled,
+    placeholderData: (prev) => prev,
+    ...queryOptions,
+  })
+
+  const query = useCallback((q: TQuery) => setSearchQuery(q), [])
+
+  const renderEmpty = useCallback(
+    ({ style }: { style: ICSS }): React.ReactNode => {
+      if (queryResult.isLoading || queryResult.isFetching) {
+        return renderLoading?.(style) ?? null
+      }
+      if (queryResult.isError) {
+        return renderError?.(queryResult.error, style) ?? null
+      }
+      return renderNoResults?.(searchQuery, style) ?? null
+    },
+    [
+      queryResult.isLoading, queryResult.isFetching,
+      queryResult.isError, queryResult.error,
+      renderLoading, renderError, renderNoResults, searchQuery,
+    ]
+  )
+
+  return [
+    {
+      options: (queryResult.data?.results ?? []) as TOption[],
+      renderEmpty,
+    },
+    {
+      query,
+      searchQuery,
+      data: queryResult.data?.data ?? null,
+      isLoading: queryResult.isLoading,
+      error: queryResult.error,
+      queryResult,
+    },
+  ]
+}

package/src/lib/hooks/useBreakpointMatch.ts

@@ -82,6 +82,17 @@ function useBreakpointListeners() {
   return breakpointMatches
 }
 
+/**
+ * Returns the value mapped to the currently active breakpoint.
+ *
+ * Reads breakpoint definitions from the active `themeStore` theme and attaches
+ * `matchMedia` listeners to track viewport changes reactively. The lookup walks
+ * up from the current breakpoint until it finds a key present in `values`, so
+ * you can omit smaller breakpoints and let them fall back to the next larger one.
+ *
+ * Must be rendered in a browser context; SSR always resolves to the fallback
+ * value (the largest defined key in `values`).
+ */
 export function useBreakpointMatch<T = string>(values: Partial<Record<Breakpoint, T>>): T {
   const breakpointMatches = useBreakpointListeners()
 

package/src/lib/hooks/useClick.ts

@@ -5,8 +5,14 @@ type HandlerClickOutside = (clickedOutside: boolean) => void
 
 type UseClickOutsideElementReturn = React.MutableRefObject<any>
 
+/**
+ * Attaches a global `click` listener and calls `handler` with `true` when the
+ * user clicks outside the returned ref's element, or `false` when they click
+ * inside it. Pass additional `elements` refs to treat those nodes as "inside"
+ * as well — the handler fires `false` if any of them contains the click target.
+ */
 export function useClickOutsideElement(
-  handler: HandlerClickOutside, 
+  handler: HandlerClickOutside,
   elements: Array<React.MutableRefObject<any>> = null,
 ): UseClickOutsideElementReturn {
   const elementRef = useRef(null)

package/src/lib/hooks/useClickOutside.ts

@@ -2,6 +2,14 @@ import { useEffect, useRef } from 'react'
 
 const DEFAULT_EVENTS = ['mousedown', 'touchstart']
 
+/**
+ * Calls `handler` when a pointer event fires outside the returned ref's element.
+ *
+ * Listens for `mousedown` and `touchstart` by default; pass `events` to
+ * override. Supply `nodes` to bypass the ref entirely and check a fixed set of
+ * elements instead — useful when the trigger lives outside the component tree.
+ * Elements with `data-ignore-outside-clicks` are always ignored.
+ */
 export function useClickOutside<T extends HTMLElement = any>(
   handler: () => void,
   events?: string[] | null,

package/src/lib/hooks/useFileInput.ts

@@ -1,6 +1,11 @@
 import { useRef } from 'react'
 import { FileInputRef } from '../../components/FileInput/types'
 
+/**
+ * Provides an imperative ref and `openFilePicker` helper for a `FileInput`
+ * component. Attach the returned `ref` to `<FileInput ref={ref} />` and call
+ * `openFilePicker()` from a button or any other trigger.
+ */
 export const useFileInput = () => {
   const inputRef = useRef<FileInputRef | null>(null)
 

package/src/lib/hooks/useIsomorphicEffect.ts

@@ -1,3 +1,7 @@
 import { useEffect, useLayoutEffect } from 'react'
 
+/**
+ * `useLayoutEffect` in the browser; `useEffect` on the server.
+ * Avoids the React SSR warning about `useLayoutEffect` in non-browser environments.
+ */
 export const useIsomorphicEffect = typeof document !== 'undefined' ? useLayoutEffect : useEffect

package/src/lib/hooks/useKeydown.ts

@@ -1,6 +1,7 @@
 import { TypeGuards } from '@codeleap/types'
 import { useEffect } from 'react'
 
+/** Convenience key descriptors available as `useKeydown.keys`. */
 export const keydownDefaultKeyOptions = {
   ArrowLeft: 'ArrowLeft',
   ArrowRight: 'ArrowRight',
@@ -13,6 +14,13 @@ export const keydownDefaultKeyOptions = {
   },
 }
 
+/**
+ * Adds a `keydown` listener on `document` for a single key.
+ *
+ * `expectedKey` can be a shorthand from `useKeydown.keys` (e.g. `'Enter'`) or
+ * an explicit `{ key, code }` object. The listener is re-registered whenever
+ * `deps` change.
+ */
 export function useKeydown(
   expectedKey: keyof typeof useKeydown.keys | { key: string; code: string },
   handler: (event: KeyboardEvent) => void,

package/src/lib/hooks/useListFocus.ts

@@ -0,0 +1,59 @@
+import { useEffect, useMemo, type RefObject } from 'react'
+
+/** Determines which option receives focus when `ListFocusHandle.focus` is called. */
+export type ListFocusStrategy = 'first' | 'last' | 'selected'
+
+export interface ListFocusHandle {
+  focus(strategy?: ListFocusStrategy): void
+}
+
+/**
+ * Creates a stable imperative focus handle for a ListBox DOM ref and returns it.
+ *
+ * The handle queries [role="option"] elements directly. When the chosen item
+ * receives DOM focus, react-aria's own useSelectableItem onFocus handler calls
+ * manager.setFocusedKey(key), so internal keyboard-navigation state stays in
+ * sync without needing access to ListStateContext.
+ *
+ * Pass the same listBoxRef to <ListBox ref={...}>.
+ * Pass externalRef to also expose the handle to a consumer-provided ref.
+ */
+export function useListFocus(
+  listBoxRef: RefObject<HTMLElement | null>,
+  externalRef?: RefObject<ListFocusHandle | null>,
+): ListFocusHandle {
+  const handle = useMemo<ListFocusHandle>(() => ({
+    focus(strategy: ListFocusStrategy = 'selected') {
+      const list = listBoxRef.current
+      if (!list) return
+
+      const options = Array.from(
+        list.querySelectorAll<HTMLElement>('[role="option"]:not([data-disabled])')
+      )
+      if (!options.length) return
+
+      let target: HTMLElement | null = null
+
+      if (strategy === 'last') {
+        target = options.at(-1) ?? null
+      } else if (strategy === 'selected') {
+        target =
+          list.querySelector<HTMLElement>('[role="option"][aria-selected="true"]') ??
+          options[0] ??
+          null
+      } else {
+        target = options[0] ?? null
+      }
+
+      target?.focus()
+    },
+  }), [listBoxRef])
+
+  useEffect(() => {
+    if (!externalRef) return
+    externalRef.current = handle
+    return () => { externalRef.current = null }
+  }, [handle, externalRef])
+
+  return handle
+}

package/src/lib/hooks/useMediaQuery.ts

@@ -1,6 +1,13 @@
 import { useEffect, useRef, useState } from 'react'
 import { attachMediaListener, getMediaQuery, isMediaQuery } from '../tools'
 
+/**
+ * Subscribes to a CSS media query string and returns whether it currently matches.
+ *
+ * Falls back to a static check via `isMediaQuery` on SSR or when `matchMedia` is
+ * unavailable. The query string may include the `@media screen and ` prefix —
+ * it is stripped internally before passing to `window.matchMedia`.
+ */
 export function useMediaQuery(query: string) {
   const [matches, setMatches] = useState(isMediaQuery(query))
 

package/src/lib/hooks/usePageExitBlocker.ts

@@ -1,6 +1,16 @@
 import { globalHistory } from '@reach/router'
 import { useEffect } from 'react'
 
+/**
+ * Blocks the user from leaving the current page without confirmation.
+ *
+ * Intercepts both browser tab-close / reload (`beforeunload`) and in-app
+ * navigation via `@reach/router`'s `globalHistory`. When a PUSH or POP
+ * navigation is detected, a `window.confirm` dialog is shown; `handler` is
+ * called with `true` if the user confirmed, `false` if they cancelled.
+ *
+ * Requires `@reach/router` to be present in the application.
+ */
 export const usePageExitBlocker = (
   handler: (willLeavePage: boolean) => void,
   deps: Array<any> = [],

package/src/lib/hooks/usePagination.ts

@@ -1,6 +1,7 @@
 import { useMemo, useUncontrolled } from '@codeleap/hooks'
 import { range } from '@codeleap/utils'
 
+/** Parameters accepted by `usePagination`. */
 export type PaginationParams = {
   initialPage?: number
   page?: number
@@ -15,6 +16,19 @@ export type PaginationParams = {
   abbreviationSymbol?: any
 }
 
+/**
+ * Manages pagination state and computes the visible page range for a
+ * `PaginationButtons` component.
+ *
+ * Supports controlled (`page` + `onChangePage`) and uncontrolled modes. When
+ * `shouldAbbreviate` is true (default) and `total` exceeds
+ * `abbreviationMinimumAmount`, the range collapses middle pages into
+ * `abbreviationSymbol` entries. Mobile mode reduces the boundary count and
+ * forces abbreviation.
+ *
+ * Arrow buttons at positions `0` and `total + 1` are reserved for the
+ * previous/next controls and are not selectable as page numbers.
+ */
 export function usePagination(props: PaginationParams) {
 
   const { isMobile } = props

package/src/lib/hooks/usePopState.ts

@@ -2,6 +2,17 @@ import { AnyFunction } from '@codeleap/types'
 import { useUnmount } from '@codeleap/hooks'
 import { useIsomorphicEffect } from './useIsomorphicEffect'
 
+/**
+ * Conditionally attaches a `popstate` listener while `dependence` is `true`.
+ *
+ * When `dependence` becomes `true`, pushes the current URL onto the history
+ * stack so the browser back button triggers `popstate` rather than navigating
+ * away. When `dependence` becomes `false` (or the component unmounts), the
+ * listener is removed.
+ *
+ * Useful for keeping overlays (modals, drawers) dismissable via the browser
+ * back button.
+ */
 export const usePopState = (dependence: boolean, handler: AnyFunction) => {
   useIsomorphicEffect(() => {
     if (dependence) {

package/src/lib/hooks/usePopoverDismiss.ts

@@ -0,0 +1,42 @@
+import { useEffect, useRef, type RefObject } from 'react'
+
+/**
+ * Restores outside-click dismissal for a Popover rendered with isNonModal=true.
+ *
+ * react-aria's usePopover sets isDismissable=!isNonModal, which disables its own
+ * useInteractOutside listener. This hook adds an equivalent pointerdown capture
+ * listener directly on the document.
+ *
+ * The trigger element is excluded so its own press handler can handle the toggle.
+ * The blur-based close (shouldCloseOnBlur=true in useOverlay) still handles the
+ * case where focus is inside the popover and moves elsewhere, so this hook only
+ * needs to cover the unfocused-popover scenario.
+ */
+export function usePopoverDismiss({
+  popoverRef,
+  triggerRef,
+  isOpen,
+  onClose,
+}: {
+  popoverRef: RefObject<Element | null>
+  triggerRef: RefObject<Element | null>
+  isOpen: boolean
+  onClose: () => void
+}) {
+  const onCloseRef = useRef(onClose)
+  useEffect(() => { onCloseRef.current = onClose })
+
+  useEffect(() => {
+    if (!isOpen) return
+
+    const handle = (e: PointerEvent) => {
+      const target = e.target as Node
+      if (popoverRef.current?.contains(target)) return
+      if (triggerRef.current?.contains(target)) return
+      onCloseRef.current()
+    }
+
+    document.addEventListener('pointerdown', handle, { capture: true })
+    return () => document.removeEventListener('pointerdown', handle, { capture: true })
+  }, [isOpen, popoverRef, triggerRef])
+}

package/src/lib/hooks/useRefresh.ts

@@ -21,6 +21,15 @@ const scrollDebounce = (func, delay) => {
   return scrollDebounce
 }
 
+/**
+ * Implements a pull-to-refresh pattern for web scroll containers.
+ *
+ * Monitors the window `scroll` event and fires `onRefresh` when the container
+ * has been scrolled above `threshold` (percentage) twice in quick succession.
+ * After `onRefresh` resolves, the refresh state is reset after 2.5 s. Set
+ * `enabled: false` to disable the listener entirely (e.g. while a request is
+ * already in flight). Attach `scrollableRef` to the scrollable container element.
+ */
 export const useRefresh = (onRefresh = () => null, options: UseRefreshOptions) => {
 
   const {

package/src/lib/hooks/useScrollEffect.ts

@@ -1,5 +1,10 @@
 import { useEffect } from 'react'
 
+/**
+ * Calls `effect` on every window scroll event, passing whether `window.scrollY`
+ * has passed `breakpoint` and the current scroll position. The listener is
+ * re-registered when `breakpoint` or any `extraDependencies` change.
+ */
 export function useScrollEffect(
   effect: (passed: boolean, current: number) => any,
   breakpoint: number,

package/src/lib/hooks/useSearchParams.ts

@@ -1,6 +1,10 @@
 import { useEffect, useRef, useState } from 'react'
 import { usePrevious } from '@codeleap/hooks'
 
+/**
+ * Tuple returned by `useSearchParams`:
+ * `[params, setParams, reset, rawURLSearchParams]`.
+ */
 export type UseSearchParamsReturn<T> = [
   T,
   React.Dispatch<React.SetStateAction<T>>,
@@ -8,6 +12,15 @@ export type UseSearchParamsReturn<T> = [
   URLSearchParams
 ]
 
+/**
+ * Syncs a typed record of string params with the URL query string via
+ * `window.history.replaceState`. On mount, reads the current URL params and
+ * merges them with `initial` defaults (initial values are only applied when the
+ * URL param is absent or empty). Call `reset()` to restore `initial`.
+ *
+ * Not a router integration — changes do not trigger a navigation event, and the
+ * hook does not react to external URL changes after mount.
+ */
 export function useSearchParams<
   T extends Record<string, string> = Record<string, string>
 >(initial?: T): UseSearchParamsReturn<T> {

package/src/lib/hooks/useStaticAnimationStyles.ts

@@ -1,6 +1,12 @@
 import { useRef } from 'react'
 import { SelectProperties } from '../../types'
 
+/**
+ * Captures a frozen snapshot of the selected `keys` from `obj` on the first
+ * render and never updates it. Used by `useAnimatedVariantStyles` to keep the
+ * non-animated style values stable across re-renders so Framer Motion does not
+ * re-create animation targets unnecessarily.
+ */
 export function useStaticAnimationStyles<T extends Record<string | number | symbol, any>, K extends keyof T>(obj: T, keys: K[]) {
   const styles = useRef({})
 

package/src/lib/hooks/useStylesFor.ts

@@ -1,34 +1,45 @@
-import { StyleProp, useStyleObserver } from '@codeleap/styles'
+import { ComponentContext, ICSS, StyleProp, useStyleObserver } from '@codeleap/styles'
 import { useMemo } from 'react'
 import { WebStyleRegistry } from '../WebStyleRegistry'
-import { useIsMounted } from '@codeleap/hooks'
-
-export const useStylesFor = <T = unknown>(componentName: string, style: StyleProp<T, string>): T => {
+import { useIsMounted, useStableReference } from '@codeleap/hooks'
+
+/**
+ * Resolves a component's style parts from `WebStyleRegistry` and re-evaluates
+ * whenever the `style` prop or `context` changes.
+ *
+ * Must be called inside a component that has a `WebStyleRegistry` instance
+ * available (created once per app via `new WebStyleRegistry()`). Pass the
+ * component's registered name as `componentName` — it must match the name used
+ * in `WebStyleRegistry.registerComponent`.
+ */
+export const useStylesFor = <C extends string>(componentName: string, style: StyleProp<C, string>, context?: ComponentContext): Record<C, ICSS> => {
   const styleObserver = useStyleObserver(style)
 
-  const isMounted = useIsMounted()
+  // const isMounted = useIsMounted()
+
+  const stableContext = useStableReference(context ?? {})
 
   const styles = useMemo(() => {
-    return WebStyleRegistry.current.styleFor(componentName, style)
-  }, [styleObserver])
+    return WebStyleRegistry.current.styleFor(componentName, style, true, stableContext)
+  }, [styleObserver, stableContext])
 
-  const processedStyles = useMemo(() => {
-    // this is strange, but necessary to recalculate the pre-set styles from SSR
-    return Object.entries(styles).reduce((acc, [key, styleValue]) => {
-      const isServer = typeof window === 'undefined'
-      const inEnvTransition = isServer ? false : !isMounted
+  // const processedStyles = useMemo(() => {
+  //   // this is strange, but necessary to recalculate the pre-set styles from SSR
+  //   return Object.entries(styles).reduce((acc, [key, styleValue]) => {
+  //     const isServer = typeof window === 'undefined'
+  //     const inEnvTransition = isServer ? false : !isMounted
 
-      acc[key] = inEnvTransition ? {
-        // Despite what it may look like, this is not (just) a joke. The "orphans" property is almost completely useless,
-        // so we set it just to force the styles to recompute after hydration. Also picked for comedic impact.
-        orphans: 1,
+  //     acc[key] = inEnvTransition ? {
+  //       // Despite what it may look like, this is not (just) a joke. The "orphans" property is almost completely useless,
+  //       // so we set it just to force the styles to recompute after hydration. Also picked for comedic impact.
+  //       orphans: 1,
 
-        ...styleValue } : styleValue
+  //       ...styleValue } : styleValue
 
-      return acc
-    }, {} as T)
-  }, [styles, isMounted])
+  //     return acc
+  //   }, {} as Record<C, ICSS>)
+  // }, [styles, isMounted])
 
-  return processedStyles
+  return styles as Record<C, ICSS>
 
 }

package/src/lib/hooks/useTouchableEvents.ts

@@ -0,0 +1,41 @@
+import { useState } from 'react'
+
+/**
+ * Tracks hover and pressed interaction states for a `Touchable`-like element
+ * using pointer events. Uses `setPointerCapture` / `releasePointerCapture` so
+ * that `isPressed` stays accurate even when the pointer leaves the element
+ * while held down. Both states are forced to `false` when `disabled` is `true`.
+ */
+export function useTouchableInteraction(disabled = false) {
+  const [isHovering, setIsHovering] = useState(false)
+  const [isPressed, setIsPressed] = useState(false)
+
+  return {
+    eventHandlers: {
+      onPointerEnter: () => setIsHovering(true),
+
+      onPointerLeave: () => {
+        setIsHovering(false)
+        setIsPressed(false)
+      },
+
+      onPointerDown: (e) => {
+        setIsPressed(true)
+        e.currentTarget.setPointerCapture(e.pointerId)
+      },
+
+      onPointerUp: (e) => {
+        setIsPressed(false)
+        e.currentTarget.releasePointerCapture(e.pointerId)
+      },
+
+      onPointerCancel: () => {
+        setIsPressed(false)
+      },
+    },
+    isHovering: isHovering && !disabled,
+    isPressed: isPressed && !disabled,
+  }
+}
+
+export type TouchableInteractionHandler = ReturnType<typeof useTouchableInteraction>

package/src/lib/hooks/useWindowFocus.ts

@@ -6,6 +6,11 @@ type UseWindowFocusOptions = {
   onBlur?: AnyFunction
 }
 
+/**
+ * Returns `true` when the browser window has focus, `false` when it is blurred.
+ * Calls `options.onFocus` and `options.onBlur` side-effect callbacks as needed.
+ * The listeners are re-registered when `deps` change.
+ */
 export const useWindowFocus = (options: UseWindowFocusOptions = {}, deps: Array<any> = []): boolean => {
   const [focused, setFocused] = useState(true)
 

package/src/lib/hooks/useWindowSize.ts

@@ -1,11 +1,26 @@
-import { useState, useEffect } from 'react'
+import { useDebounceCallback } from '@codeleap/hooks'
+import { useState, useEffect, useCallback } from 'react'
 
-export function useWindowSize() {
-  const [size, setSize] = useState([])
 
-  function handleResize() {
+/**
+ * Returns `[innerWidth, innerHeight]` and keeps the value in sync with window
+ * resize events. When `live` is `false` (default), resize updates are debounced
+ * by 300 ms to avoid flooding renders. Pass `live: true` for immediate updates.
+ * SSR returns `[1920, 1080]` as a placeholder.
+ */
+export function useWindowSize(live=false) {
+  const [size, setSize] = useState(() => {
+    if(typeof window === 'undefined') return [1920,1080]
+    return [window.innerWidth, window.innerHeight]
+  })
+
+  const handler = useCallback(() => {
     setSize([window.innerWidth, window.innerHeight])
-  }
+  },[setSize])
+
+  const debouncedHandleResize = useDebounceCallback(handler, 300)
+
+  const handleResize = live ? handler : debouncedHandleResize.debounce
 
   useEffect(() => {
     handleResize()
@@ -15,7 +30,7 @@ export function useWindowSize() {
     return () => {
       window.removeEventListener('resize', handleResize)
     }
-  }, [])
+  }, [handleResize])
 
   return size
 }

package/src/lib/index.ts

@@ -3,3 +3,4 @@ export * from './tools'
 export * from './utils'
 export * from './ListMasonry'
 export * from './WebStyleRegistry'
+export * from './ThemeVariables'

package/src/lib/tools/localStorage.ts

@@ -1,6 +1,7 @@
 import { useEffect, useState } from 'react'
 import { TypeGuards } from '@codeleap/types'
 
+/** Callback signature for `LocalStorage.listen`. Receives the key, the raw `StorageEvent`, and the parsed new value. */
 export type LocalStorageHandler<T> = (key: T, event: StorageEvent, value: any) => void
 export type Key<T> = keyof T
 
@@ -11,6 +12,17 @@ type UseLocalStorageOptions = {
   parseValueOnGet?: boolean
 }
 
+/**
+ * Type-safe wrapper around `window.localStorage`.
+ *
+ * Instantiate with a key map (`{ tokenKey: 'auth_token', ... }`) so all reads
+ * and writes are validated against the map's keys at compile time. Values are
+ * automatically JSON-serialised on write and JSON-parsed on read; strings are
+ * stored as-is. Returns safe no-ops when called server-side.
+ *
+ * Use `use()` to get a React state pair that stays in sync with storage across
+ * tabs via the `storage` event.
+ */
 export class LocalStorage<T extends Record<string, string>> {
   public storageKeys: T