@ngrok/mantle 0.70.2 → 0.71.1

package/dist/hooks.d.ts

@@ -106,42 +106,119 @@ declare function useIsBelowBreakpoint(breakpoint: TailwindBreakpoint): boolean;
 //#endregion
 //#region src/hooks/use-callback-ref.d.ts
 /**
- * Returns a memoized callback that will always refer to the latest callback
- * passed to the hook.
+ * Returns a memoized callback that always invokes the latest version of the
+ * provided callback, while preserving a stable function identity across
+ * renders.
+ *
+ * Use this when you need to pass a callback to a child component, an event
+ * handler, or a hook dependency array, but the consumer should not re-run /
+ * re-render simply because the callback's identity changed. The returned
+ * function never changes reference, but internally always calls through to
+ * the latest `callback` passed in.
+ *
+ * Most commonly used as an internal building block for other hooks (for
+ * example, {@link useDebouncedCallback}). It is also re-exported publicly
+ * for consumers that need the same pattern.
+ *
+ * @param callback - The callback to wrap. May be `undefined`, in which case
+ *   invoking the returned function is a no-op until a callback is provided
+ *   on a subsequent render.
+ * @returns A stable function with the same signature as `callback` that
+ *   forwards its arguments to the most recent `callback` value.
  *
- * This is useful when you want to pass a callback which may or may not be
- * memoized (have a stable identity) to a child component that will be updated
- * without causing the child component to re-render.
+ * @example
+ * // Pass a stable handler to a memoized child without re-rendering it
+ * const onSelect = useCallbackRef((id: string) => {
+ *   // reads the latest `props.items` without being in deps
+ *   props.onSelectItem(id, props.items);
+ * });
+ *
+ * return <MemoizedList onSelect={onSelect} />;
  */
 declare function useCallbackRef<T extends (...args: unknown[]) => unknown>(callback: T | undefined): T;
 //#endregion
 //#region src/hooks/use-copy-to-clipboard.d.ts
 /**
- * A hook that returns an async function to copy a string to the clipboard.
+ * React hook that returns a stable async function for copying a string to
+ * the system clipboard.
  *
- * `await` the returned function to know whether the write succeeded. It
- * throws when both the Clipboard API and the `execCommand` polyfill fail.
+ * The returned function uses the Clipboard API when available and falls back
+ * to a `document.execCommand("copy")` polyfill for older browsers. `await`
+ * the call (or attach a `.then()` / `.catch()`) to observe whether the copy
+ * succeeded — the function throws when both the Clipboard API and the
+ * polyfill fail, or when called outside of a DOM environment.
  *
  * Inspired by: https://usehooks.com/usecopytoclipboard
+ *
+ * @returns An async function `(value: string) => Promise<void>` that writes
+ *   `value` to the clipboard and rejects on failure.
+ *
+ * @example
+ * // Copy a token on click and surface a toast on success/failure
+ * const copy = useCopyToClipboard();
+ *
+ * async function handleCopy() {
+ *   try {
+ *     await copy(token);
+ *     toast.success("Copied!");
+ *   } catch {
+ *     toast.error("Could not copy to clipboard");
+ *   }
+ * }
+ *
+ * return <button onClick={handleCopy}>Copy token</button>;
  */
 declare function useCopyToClipboard(): typeof copyToClipboard;
 //#endregion
 //#region src/hooks/use-debounced-callback.d.ts
+/**
+ * Options for {@link useDebouncedCallback}.
+ */
 type Options = {
   /**
-   * The delay in milliseconds to wait before calling the callback.
+   * The delay in milliseconds to wait between the last invocation and
+   * actually running the callback.
    */
   waitMs: number;
 };
 /**
- * Create a debounced version of a callback function.
+ * Returns a debounced version of the provided callback. Each call resets a
+ * timer; the underlying callback only runs after `options.waitMs` of
+ * inactivity has elapsed.
+ *
+ * Useful for limiting rapid invocations such as search-as-you-type inputs,
+ * window resize handlers, or expensive button-press handlers. The pending
+ * timer is automatically cleared on unmount.
+ *
+ * The debounced function always invokes the latest version of `callbackFn`,
+ * so callers do not need to memoize it. The returned function's identity
+ * only changes when `options.waitMs` changes, so it is safe to include in
+ * dependency arrays.
+ *
+ * @param callbackFn - The function to debounce. The latest reference passed
+ *   on each render is always used when the timer fires.
+ * @param options - Debounce options.
+ * @param options.waitMs - Milliseconds of inactivity to wait before calling
+ *   `callbackFn`.
+ * @returns A function with the same parameter list as `callbackFn` that
+ *   schedules (or reschedules) the underlying call.
  *
- * It allows you to delay the execution of a function until a certain period of
- * inactivity has passed (the `options.waitMs`), which can be useful for limiting rapid
- * invocations of a function (like in search inputs or button clicks)
+ * @example
+ * // Debounce a search input by 300ms
+ * const [query, setQuery] = useState("");
+ * const search = useDebouncedCallback((value: string) => {
+ *   fetchResults(value);
+ * }, { waitMs: 300 });
  *
- * Note: The debounced callback will always refer to the latest callback passed
- * even without memoization, so it's stable and safe to use in dependency arrays.
+ * return (
+ *   <input
+ *     value={query}
+ *     onChange={(event) => {
+ *       setQuery(event.target.value);
+ *       search(event.target.value);
+ *     }}
+ *   />
+ * );
  */
 declare function useDebouncedCallback<T extends (...args: unknown[]) => unknown>(callbackFn: T, options: Options): (...args: Parameters<T>) => void;
 //#endregion
@@ -174,71 +251,171 @@ declare function useIsHydrated(): boolean;
 //#endregion
 //#region src/hooks/use-isomorphic-layout-effect.d.ts
 /**
- * useIsomorphicLayoutEffect is a hook that uses useLayoutEffect on the client and useEffect on the server.
+ * A drop-in replacement for `useLayoutEffect` that does not warn during
+ * server-side rendering.
+ *
+ * Resolves to `useLayoutEffect` in the browser (where it can read layout and
+ * synchronously re-render before paint) and to `useEffect` on the server
+ * (where layout effects are a no-op and React would otherwise log a
+ * "useLayoutEffect does nothing on the server" warning).
+ *
+ * Use this whenever you need the timing semantics of `useLayoutEffect` in
+ * code that may also execute during SSR. It is most often used internally
+ * by other Mantle hooks and components.
+ *
+ * @param effect - The imperative function that may return a cleanup
+ *   function — same signature as React's `useLayoutEffect` / `useEffect`.
+ * @param deps - Optional dependency list, same semantics as
+ *   `useLayoutEffect`.
+ * @returns Nothing.
+ *
+ * @example
+ * // Measure an element synchronously after layout
+ * const ref = useRef<HTMLDivElement>(null);
+ * const [width, setWidth] = useState(0);
+ *
+ * useIsomorphicLayoutEffect(() => {
+ *   if (ref.current) {
+ *     setWidth(ref.current.getBoundingClientRect().width);
+ *   }
+ * }, []);
+ *
+ * return <div ref={ref}>Width: {width}</div>;
  */
 declare const useIsomorphicLayoutEffect: typeof useEffect;
 //#endregion
 //#region src/hooks/use-matches-media-query.d.ts
 /**
- * React hook that subscribes to and returns the result of a CSS media query.
+ * React hook that subscribes to a CSS media query and returns whether it
+ * currently matches, re-rendering whenever the result changes.
  *
- * This hook uses `window.matchMedia` under the hood and leverages
- * `useSyncExternalStore` to stay compliant with React's concurrent rendering model.
+ * Uses `window.matchMedia` under the hood and `useSyncExternalStore` for
+ * compatibility with React's concurrent rendering model. Returns `false`
+ * on the server; during hydration React uses that server snapshot before
+ * updating to the client media-query value.
  *
- * @param {string} query - A valid CSS media query string (e.g., `(max-width: 768px)`).
+ * For common viewport breakpoint checks, prefer the more specific
+ * {@link useBreakpoint} or {@link useIsBelowBreakpoint} hooks.
  *
- * @returns {boolean} `true` if the media query currently matches, otherwise `false`.
+ * @param query - A valid CSS media query string
+ *   (e.g. `"(max-width: 768px)"`, `"(prefers-color-scheme: dark)"`).
+ * @returns `true` if the media query currently matches, otherwise `false`.
  *
  * @example
- * // Detect if the user prefers a dark color scheme:
- * const isDarkMode = useMatchesMediaQuery("(prefers-color-scheme: dark)");
+ * // Detect if the user prefers a dark color scheme
+ * const prefersDark = useMatchesMediaQuery("(prefers-color-scheme: dark)");
  *
- * if (isDarkMode) {
- *   document.body.classList.add("dark");
- * } else {
- *   document.body.classList.remove("dark");
- * }
+ * return <div className={prefersDark ? "dark" : "light"}>Hello</div>;
+ *
+ * @example
+ * // Show a different layout on portrait orientation
+ * const isPortrait = useMatchesMediaQuery("(orientation: portrait)");
+ *
+ * return isPortrait ? <PortraitLayout /> : <LandscapeLayout />;
  */
 declare function useMatchesMediaQuery(query: string): boolean;
 //#endregion
 //#region src/hooks/use-prefers-reduced-motion.d.ts
 /**
- * Imperatively reads the current `prefers-reduced-motion` preference.
- * Useful in event handlers and plain functions where a hook cannot be called.
+ * Imperatively reads the current `prefers-reduced-motion` preference once at
+ * the time of the call.
+ *
+ * Useful in event handlers, animation entrypoints, or plain functions where
+ * a React hook cannot be called. Prefer {@link usePrefersReducedMotion}
+ * inside components — it subscribes to live changes.
  *
- * Returns `true` when the user has opted out of animations.
+ * @returns `true` when the user has opted out of animations or when called
+ *   outside a browser environment (SSR), `false` when motion is allowed.
  *
  * @remarks
- * Returns `true` (reduce motion) when called outside a browser environment (SSR),
- * matching the conservative default of {@link usePrefersReducedMotion}.
+ * The conservative SSR default of `true` matches
+ * {@link usePrefersReducedMotion}: animations stay off until we can verify
+ * the user's preference on the client.
+ *
+ * @example
+ * // Skip a one-off entrance animation in a click handler
+ * function onOpen() {
+ *   if (getPrefersReducedMotion()) {
+ *     element.style.opacity = "1";
+ *     return;
+ *   }
+ *   element.animate([{ opacity: 0 }, { opacity: 1 }], { duration: 200 });
+ * }
  */
 declare function getPrefersReducedMotion(): boolean;
 /**
- * Returns `true` when the user has opted out of animations (i.e., prefers reduced motion).
+ * React hook that subscribes to the user's `prefers-reduced-motion` media
+ * query and re-renders when it changes.
+ *
+ * Defaults to `true` (reduce motion) on the server and during the first
+ * client render to avoid animating before hydration. The initial client
+ * effect reads the *real* preference and updates state. The underlying
+ * media query used is `(prefers-reduced-motion: no-preference)` inverted —
+ * "if the system hasn't opted out, animations are allowed."
  *
- * Implementation notes:
- * - Uses the `(prefers-reduced-motion: no-preference)` media query and inverts it.
- *   This keeps the “default” mental model explicit: if the system hasn’t opted out,
- *   animations are allowed.
- * - Defaults to `true` (reduce motion) on the server/during SSR to avoid animating
- *   before hydration. The initial client effect reads the *real* preference and updates state.
+ * @returns `true` when the user prefers reduced motion (animations should be
+ *   shortened or skipped), `false` when full motion is acceptable.
+ *
+ * @remarks
+ * If you need to support very old browsers that lack
+ * `MediaQueryList.addEventListener`, consider falling back to
+ * `addListener` / `removeListener`.
  *
  * @example
  * // Conditionally shorten or skip transitions
- * const reduce = usePrefersReducedMotion();
- * const duration = reduce ? 0 : 200;
+ * const prefersReducedMotion = usePrefersReducedMotion();
+ * const duration = prefersReducedMotion ? 0 : 200;
  *
- * @remarks
- * If you need to support very old browsers that lack `MediaQueryList.addEventListener`,
- * consider falling back to `addListener/removeListener`.
+ * return <Modal transitionDuration={duration} />;
+ *
+ * @example
+ * // Disable an autoplaying carousel when motion is reduced
+ * const prefersReducedMotion = usePrefersReducedMotion();
+ *
+ * return <Carousel autoplay={!prefersReducedMotion} />;
  */
 declare function usePrefersReducedMotion(): boolean;
 //#endregion
 //#region src/hooks/use-random-stable-id.d.ts
 /**
- * Hook to generate a random, stable id.
- * This is similar to `useId`, but generates a stable id client side which can also
- * be used for css selectors and element ids.
+ * React hook that returns a random, stable id (e.g. `"mantle-a3f9k7q"`)
+ * suitable for DOM `id` attributes and `aria-*` references.
+ *
+ * Unlike React's built-in `useId`, the generated suffix does not contain
+ * special characters (`:`). The default id is safe to use directly in CSS
+ * selectors and `querySelector` calls; if you provide a custom `prefix`,
+ * keep it selector-safe or escape the final id with `CSS.escape()` before
+ * querying. The id is generated once for the lifetime of the component and
+ * is stable across re-renders, but a new value is produced when `prefix`
+ * changes.
+ *
+ * @param prefix - Optional string prepended to the generated suffix.
+ *   Whitespace-only or empty values fall back to `"mantle"`. Use a
+ *   selector-safe prefix if you plan to reference the id in CSS selectors
+ *   without escaping. Defaults to `"mantle"`.
+ * @returns A string of the form `"<prefix>-<7-char-random>"`.
+ *
+ * @example
+ * // Associate a label with a custom input
+ * const id = useRandomStableId("email-input");
+ *
+ * return (
+ *   <>
+ *     <label htmlFor={id}>Email</label>
+ *     <input id={id} type="email" />
+ *   </>
+ * );
+ *
+ * @example
+ * // Use as an aria-controls reference
+ * const panelId = useRandomStableId("panel");
+ *
+ * return (
+ *   <>
+ *     <button aria-controls={panelId}>Toggle</button>
+ *     <div id={panelId}>Panel contents</div>
+ *   </>
+ * );
  */
 declare const useRandomStableId: (prefix?: string) => string;
 //#endregion
@@ -253,24 +430,38 @@ declare const useRandomStableId: (prefix?: string) => string;
  */
 type ScrollBehavior = "auto" | "smooth";
 /**
- * Returns a `ScrollBehavior` that respects the user's motion preference via `usePrefersReducedMotion`.
+ * React hook that returns a {@link ScrollBehavior} value (`"auto"` or
+ * `"smooth"`) that respects the user's motion preference.
  *
- * - When `usePrefersReducedMotion()` is `true`, returns `"auto"` (no animated scroll).
- * - Otherwise returns `"smooth"`.
+ * Internally calls {@link usePrefersReducedMotion}: when reduced motion is
+ * preferred, this returns `"auto"` (no animated scroll); otherwise it
+ * returns `"smooth"`. Pair this with `window.scrollTo`,
+ * `Element.scrollIntoView`, or any other scroll API that accepts a
+ * `behavior` option to avoid forcing animations on users who have opted
+ * out of motion. The conservative SSR default also prevents "first paint"
+ * scroll animations.
  *
- * Use this with `window.scrollTo`, `Element.scrollIntoView`, etc. It prevents
- * smooth-scrolling for users who opt out of motion and avoids SSR “first paint”
- * animations thanks to the hook’s conservative server default.
+ * @returns `"auto"` when the user prefers reduced motion, otherwise
+ *   `"smooth"`.
  *
  * @example
- * // Scroll to top
+ * // Scroll to the top of the page on a button click
  * const behavior = useScrollBehavior();
- * window.scrollTo({ top: 0, behavior });
+ *
+ * return (
+ *   <button onClick={() => window.scrollTo({ top: 0, behavior })}>
+ *     Back to top
+ *   </button>
+ * );
  *
  * @example
- * // Bring a section into view
+ * // Bring a referenced section into view
  * const behavior = useScrollBehavior();
- * sectionRef.current?.scrollIntoView({ behavior, block: "start" });
+ * const sectionRef = useRef<HTMLElement>(null);
+ *
+ * function focusSection() {
+ *   sectionRef.current?.scrollIntoView({ behavior, block: "start" });
+ * }
  *
  * @see {@link usePrefersReducedMotion}
  * @see CSS `scroll-behavior` property (values: `"auto"`, `"smooth"`).
@@ -361,32 +552,66 @@ type UseUndoRedoReturn<T> = {
   redo: (current: T) => T | undefined;
 };
 /**
- * A generic undo/redo hook backed by a reducer.
- *
- * Maintains two stacks (undo and redo). Call `push` before mutating state
- * to snapshot the current value. Call `undo`/`redo` with the current value
- * to swap it with the previous/next snapshot.
+ * Generic undo/redo hook backed by a reducer that maintains two history
+ * stacks (undo and redo).
+ *
+ * The hook does not own your application state — instead it helps you
+ * snapshot it. Call `push(snapshot)` *before* mutating state to capture
+ * the current value, then call `undo(current)` or `redo(current)` to swap
+ * `current` with the previous/next snapshot. Both `undo` and `redo` return
+ * the snapshot to apply, or `undefined` if their stack is empty. Pushing a
+ * new snapshot clears the redo stack, matching standard editor semantics.
+ *
+ * @typeParam T - The type of the value being snapshotted (e.g. a list of
+ *   items, a serialized form value, etc.).
+ *
+ * @returns An object with the current undo/redo capability flags and
+ *   actions:
+ *   - `canUndo`: `true` when there is at least one snapshot on the undo
+ *     stack.
+ *   - `canRedo`: `true` when there is at least one snapshot on the redo
+ *     stack.
+ *   - `push(snapshot)`: Push a snapshot onto the undo stack and clear the
+ *     redo stack. Call this *before* mutating state.
+ *   - `undo(current)`: Pop the latest undo snapshot and return it; returns
+ *     `undefined` when the undo stack is empty. The supplied `current` is
+ *     pushed onto the redo stack so you can redo back to it.
+ *   - `redo(current)`: Pop the latest redo snapshot and return it; returns
+ *     `undefined` when the redo stack is empty. The supplied `current` is
+ *     pushed onto the undo stack.
  *
  * @example
- * ```tsx
+ * // Snapshot before mutating, then wire up keyboard shortcuts
+ * const [items, setItems] = useState<string[]>([]);
  * const { push, undo, redo, canUndo, canRedo } = useUndoRedo<string[]>();
  *
  * function removeItem(item: string) {
- *   push([...items]); // snapshot before mutation
- *   setItems(items.filter((i) => i !== item));
+ *   push(items); // snapshot before mutation
+ *   setItems((prev) => prev.filter((entry) => entry !== item));
  * }
  *
- * function handleKeyDown(event: KeyboardEvent) {
- *   if ((event.metaKey || event.ctrlKey) && event.key === "z" && !event.shiftKey) {
+ * function handleKeyDown(event: React.KeyboardEvent) {
+ *   const cmd = event.metaKey || event.ctrlKey;
+ *   if (cmd && event.key === "z" && !event.shiftKey) {
  *     const previous = undo(items);
- *     if (previous) setItems(previous);
+ *     if (previous) {
+ *       setItems(previous);
+ *     }
  *   }
- *   if ((event.metaKey || event.ctrlKey) && (event.shiftKey && event.key === "z" || event.key === "y")) {
+ *   if (cmd && ((event.shiftKey && event.key === "z") || event.key === "y")) {
  *     const next = redo(items);
- *     if (next) setItems(next);
+ *     if (next) {
+ *       setItems(next);
+ *     }
  *   }
  * }
- * ```
+ *
+ * return (
+ *   <div tabIndex={0} onKeyDown={handleKeyDown}>
+ *     <button disabled={!canUndo} onClick={() => { const previous = undo(items); if (previous) setItems(previous); }}>Undo</button>
+ *     <button disabled={!canRedo} onClick={() => { const next = redo(items); if (next) setItems(next); }}>Redo</button>
+ *   </div>
+ * );
  */
 declare function useUndoRedo<T>(): UseUndoRedoReturn<T>;
 //#endregion