rc-util: Common React Utilities

Common errors

• ERROR in ./src/App.tsx Module not found: Error: Can't resolve 'rc-util'

  cause The 'rc-util' package is not installed in the project's dependencies.
  fix Install the package using your package manager: `npm install rc-util` or `yarn add rc-util`.

• TypeError: (0 , _rc_util_lib_createChainedFunction__WEBPACK_IMPORTED_MODULE_0__.default) is not a function

  cause Attempting to use a named import or incorrect CommonJS `require` for a utility that is a default export from a specific deep path.
  fix Adjust your import statement to `import createChainedFunction from 'rc-util/lib/createChainedFunction';` for ESM, or `const createChainedFunction = require('rc-util/lib/createChainedFunction');` for CJS.

• ReferenceError: document is not defined

  cause Trying to use browser-specific APIs (e.g., `document` or `HTMLElement` with `Portal`) in a Node.js server-side rendering (SSR) environment without proper safeguards.
  fix Ensure components or hooks that rely on browser APIs are executed only in client-side environments, or use appropriate SSR guards like `typeof window !== 'undefined'` to conditionally render or execute code.

Warnings

• gotcha The `rc-util` library primarily exposes its utilities as default exports from deep paths (e.g., `rc-util/lib/createChainedFunction`). This deviates from common modern practices of named exports directly from the root package, which can lead to 'Module not found' or 'is not a function' errors if users attempt `import { FunctionName } from 'rc-util';`.
  Fix: Always refer to the specific import paths detailed in the `rc-util` documentation or examples, typically `import MyUtil from 'rc-util/lib/myUtil';`.
• breaking rc-util declares `react` and `react-dom` as peer dependencies (`>=16.9.0`). As React major versions increment (e.g., React 18, React 19), there may be breaking changes in React's APIs that `rc-util`'s internal components or hooks rely on. While `rc-util` aims for compatibility, ensure your installed `rc-util` version is officially tested and compatible with your project's React version.
  Fix: Always check the `rc-util` changelog and release notes for compatibility with new React versions. Upgrade `rc-util` to the latest version compatible with your React installation.
• gotcha The commit history provided pertains to `@rc-component/util` (version 1.x.x) rather than `rc-util` (version 5.x.x). While these packages likely share a lineage or common purpose, users should be aware that their specific `rc-util` version `5.44.4` might not directly reflect the features, fixes, or breaking changes detailed in the `@rc-component/util` commit logs. Always refer to `rc-util`'s specific documentation and changelog for the installed version.
  Fix: When troubleshooting or seeking new features, ensure you are referencing the documentation and changelog specific to the `rc-util` package and your installed version, not potentially related scoped packages.

Install

• npm install rc-util npm
• yarn add rc-util yarn
• pnpm add rc-util pnpm

Imports

• createChainedFunction
  wrong:

  import { createChainedFunction } from 'rc-util';

  correct:

  import createChainedFunction from 'rc-util/lib/createChainedFunction';

  This utility is a default export from a deep path within the package. Direct named imports from the root are incorrect.
• deprecated
  wrong:

  const deprecated = require('rc-util').deprecated;

  correct:

  import deprecated from 'rc-util/lib/deprecated';

  Similar to other utilities, `deprecated` is a default export from a specific internal path. CommonJS `require` should also target this path.
• Portal
  wrong:

  import { Portal } from 'rc-util';

  correct:

  import Portal from 'rc-util/lib/Portal';

  The `Portal` React component is exported as a default from its specific `/lib/` path. Ensure you use the correct import statement.

Quickstart

This quickstart demonstrates how to use `createChainedFunction` to combine multiple event handlers and `Portal` to render content into a specific DOM node, which is useful for overlays or modals.

import React, { useRef, useState } from 'react';
import { createRoot } from 'react-dom/client';
import createChainedFunction from 'rc-util/lib/createChainedFunction';
import Portal from 'rc-util/lib/Portal';

const App = () => {
  const [log, setLog] = useState<string[]>([]);
  const containerRef = useRef<HTMLDivElement>(null);

  const handleClick1 = () => {
    setLog(prev => [...prev, 'Function 1 called!']);
  };

  const handleClick2 = () => {
    setLog(prev => [...prev, 'Function 2 called!']);
  };

  const chainedClickHandler = createChainedFunction(handleClick1, handleClick2);

  const getPortalContainer = () => {
    if (!containerRef.current) {
      // Create container if it doesn't exist
      const div = document.createElement('div');
      div.id = 'portal-root';
      document.body.appendChild(div);
      containerRef.current = div;
    }
    return containerRef.current;
  };

  return (
    <div>
      <h1>rc-util Demo</h1>
      <button onClick={chainedClickHandler}>
        Click Me (Chained Functions)
      </button>
      <div style={{ marginTop: '20px', border: '1px solid #ccc', padding: '10px' }}>
        <h2>Event Log:</h2>
        {log.length === 0 ? <p>No events yet.</p> : log.map((msg, i) => <p key={i}>{msg}</p>)}
      </div>

      <div ref={containerRef} style={{ border: '1px dashed blue', padding: '10px', marginTop: '20px' }}>
        Portal Mount Point (conceptually inside App, visually rendered here)
      </div>

      {/* Content rendered into the container obtained from getPortalContainer */}
      <Portal getContainer={getPortalContainer}>
        <div style={{ background: 'lightgreen', padding: '10px', border: '1px solid green' }}>
          This content is rendered via Portal!
        </div>
      </Portal>
    </div>
  );
};

const rootElement = document.getElementById('root');
if (rootElement) {
  createRoot(rootElement).render(<App />);
} else {
  console.error("Root element with ID 'root' not found in the document.");
}