/*!
* ========================================================================
*  @rzl-zone/next-kit
* ------------------------------------------------------------------------
*  Version: `0.10.4`
*  Author: `Rizalvin Dwiky <rizalvindwiky1998@gmail.com>`
*  Repository: `https://github.com/rzl-zone/rzl-zone/tree/main/packages/next-kit`
* ========================================================================
*/

import { ComponentType, FC, ForwardRefExoticComponent, PropsWithoutRef, RefAttributes, SuspenseProps } from "react";
type SuspensedExoticComponent<P> = FC<P>;
type SuspensedForwardRefExoticComponent<P, R> = ForwardRefExoticComponent<PropsWithoutRef<P> & RefAttributes<R>>;
/** -------------------------------------------------------------
 * * ***Higher-Order Component (HOC): `WithSuspense`.***
 * -------------------------------------------------------------
 * Wraps a React component with a `<Suspense>` boundary.
 *
 * This allows the wrapped component to be lazy-loaded or deferred,
 * while providing a configurable `fallback` UI via React Suspense.
 *
 * -------------------------------------------------------------
 * **Type Inference Notes.**
 *
 * `WithSuspense` preserves the original component’s props type (`P`)
 * through generic inference. This works automatically for components
 * with **required** props, for example:
 *
 * ```tsx
 * const UserCard = (props: { id: string }) => <>...</>;
 * const Wrapped = WithSuspense(UserCard);
 * //               ^? FC<{ id: string }>  ✅ inferred correctly
 * ```
 *
 * However, TypeScript may fail to infer `P` precisely if the
 * component’s props are **fully optional**, such as:
 *
 * - `props?: P`
 * - `props: P = defaultValue`
 *
 * In such cases, TypeScript widens the type to `object`, so it is
 * recommended to **pass `<P>` explicitly**:
 *
 * ```tsx
 * const Profile = (props?: ProfileProps) => <>...</>;
 * const Broken = WithSuspense(Profile);
 * //              ^? FC<object>        ❌ incorrect
 *
 * const Fixed = WithSuspense<ProfileProps>(Profile);
 * //              ^? FC<ProfileProps>  ✅ correct
 * ```
 *
 * -------------------------------------------------------------
 * **ForwardRef Support.**
 *
 * `WithSuspense` includes a dedicated overload for components using
 * `React.forwardRef`, the returned HOC preserves:
 *
 * - `P` — the component’s props
 * - `R` — the forwarded ref type
 *
 * Example:
 *
 * ```tsx
 * const Input = React.forwardRef<HTMLInputElement, { label: string }>(
 *   (props, ref) => <input ref={ref} />
 * );
 *
 * const SuspenseInput = WithSuspense(Input);
 * //     ^? ForwardRefExoticComponent<{ label: string } & RefAttributes<HTMLInputElement>>
 * ```
 *
 * -------------------------------------------------------------
 * **React 19 Compatibility.**
 *
 * React 19 introduces automatic ref forwarding for function components, however, for full compatibility with both React 18 *and* React 19,
 * this HOC:
 *
 * - Detects `forwardRef` components via the internal `$$typeof` symbol
 * - Passes refs only when supported
 *
 * This ensures consistent runtime behavior across both versions.
 *
 * -------------------------------------------------------------
 * **Suspense Configuration (`suspenseProps`).**
 *
 * The second argument, `suspenseProps`, allows customizing behavior
 * of the `<Suspense>` boundary used to wrap the component.
 *
 * Example:
 *
 * ```tsx
 * const Wrapped = WithSuspense(UserCard, {
 *   fallback: <Spinner />,
 *   unstable_expectedLoadTime: 300, // React 19+
 * });
 * ```
 *
 * Any prop supported by `React.SuspenseProps` may be passed here.
 *
 * -------------------------------------------------------------
 * @template P - Props type of the wrapped component.
 * @template R - Ref type (only used when `Component` is forwardRef).
 *
 * @param Component - The React component to wrap with `<Suspense>`.
 * @param suspenseProps - Optional props forwarded to the `<Suspense>`
 *   wrapper (e.g. `fallback`, `unstable_expectedLoadTime`).
 *
 * @returns
 * A new component wrapped with `<Suspense>`, preserving its props
 * and (when applicable) its forwarded ref type.
 *
 * -------------------------------------------------------------
 */
declare function WithSuspense<P>(Component: ComponentType<P>, suspenseProps?: Partial<SuspenseProps>): SuspensedExoticComponent<Exclude<P, undefined>>;
declare function WithSuspense<P, R>(Component: ForwardRefExoticComponent<PropsWithoutRef<P> & RefAttributes<R>>, suspenseProps?: Partial<SuspenseProps>): SuspensedForwardRefExoticComponent<P, R>;
/** ------------------------------------------
 * * **Higher-Order Component (HOC): `withMemo`.**
 * ------------------------------------------
 * Enhances any React component with **automatic memoization**
 * using `React.memo`, with additional custom controls:
 *
 * - `memo?: boolean` — Disable memoization per instance
 *   (when set to `false`).
 * - `shouldCompareComplexProps?: boolean` — Enable/disable
 *   detailed shallow comparison for props.
 *
 * This HOC is useful for fine-grained re-render control while
 * keeping the wrapped component's API clean and predictable.
 *
 * @template P - Props type of the wrapped component.
 *               Must include optional `memo` and
 *               `shouldCompareComplexProps`.
 *
 * @param Component - The React component to wrap.
 *
 * @param [ignoreKeys=["memo", "shouldCompareComplexProps"]]
 * Keys that should be excluded from shallow comparison.
 *
 * @returns The memoized version of the component, respecting the
 *          custom memoization rules.
 *
 * @example
 * interface Props {
 *   title: string;
 *   memo?: boolean;
 *   shouldCompareComplexProps?: boolean;
 * }
 *
 * function Title({ title }: Props) {
 *   return <h1>{title}</h1>;
 * }
 *
 * const MemoTitle = withMemo(Title);
 *
 * // Memoization ON (default)
 * <MemoTitle title="Hello" />;
 *
 * // Disable memoization (force re-render)
 * <MemoTitle title="Hello" memo={false} />;
 *
 * // Enable shallow comparison for complex props
 * <MemoTitle title="Hello" shouldCompareComplexProps={true} />;
 */
declare function withMemo<P extends {
  memo?: boolean;
  shouldCompareComplexProps?: boolean;
}>(Component: ComponentType<P>, ignoreKeys?: string[]): import("react").MemoExoticComponent<ComponentType<P>>;
export { WithSuspense, withMemo };