@rc-component/util
+
Part of the Ant Design ecosystem.
🛠️ Shared React utilities for rc-component packages.
-Common Utils For React Component. +
+ 
+ 
+ 
+ 
+ 
Part of the Ant Design ecosystem.
🛠️ Shared React utilities for rc-component packages.
-Common Utils For React Component. +
+
+
+
+
+
English | 简体中文
-[npm-image]: http://img.shields.io/npm/v/rc-util.svg?style=flat-square -[npm-url]: http://npmjs.org/package/rc-util -[travis-image]: https://img.shields.io/travis/react-component/util/master?style=flat-square -[travis-url]: https://travis-ci.com/react-component/util -[github-actions-image]: https://github.com/react-component/util/actions/workflows/react-component-ci.yml/badge.svg -[github-actions-url]: https://github.com/react-component/util/actions/workflows/react-component-ci.yml -[codecov-image]: https://img.shields.io/codecov/c/github/react-component/util/master.svg?style=flat-square -[codecov-url]: https://app.codecov.io/gh/react-component/util -[david-url]: https://david-dm.org/react-component/util -[david-image]: https://david-dm.org/react-component/util/status.svg?style=flat-square -[david-dev-url]: https://david-dm.org/react-component/util?type=dev -[david-dev-image]: https://david-dm.org/react-component/util/dev-status.svg?style=flat-square -[download-image]: https://img.shields.io/npm/dm/rc-util.svg?style=flat-square -[download-url]: https://npmjs.org/package/rc-util -[bundlephobia-url]: https://bundlephobia.com/package/rc-util -[bundlephobia-image]: https://badgen.net/bundlephobia/minzip/rc-util -[dumi-url]: https://github.com/umijs/dumi -[dumi-image]: https://img.shields.io/badge/docs%20by-dumi-blue?style=flat-square -## Install - -[](https://npmjs.org/package/rc-util) - -## API - -### createChainedFunction - -> (...functions): Function - -Create a function which will call all the functions with it's arguments from left to right. - -```jsx|pure -import createChainedFunction from 'rc-util/lib/createChainedFunction'; -``` - -### deprecated - -> (prop: string, instead: string, component: string): void - -Log an error message to warn developers that `prop` is deprecated. - -```jsx|pure -import deprecated from 'rc-util/lib/deprecated'; -``` - -### getContainerRenderMixin - -> (config: Object): Object - -To generate a mixin which will render specific component into specific container automatically. - -```jsx|pure -import getContainerRenderMixin from 'rc-util/lib/getContainerRenderMixin'; -``` - -Fields in `config` and their meanings. - -| Field | Type | Description | Default | -| ------------- | ---------------------------- | -------------------------------------------------------------------------- | ------- | -| autoMount | boolean | Whether to render component into container automatically | true | -| autoDestroy | boolean | Whether to remove container automatically while the component is unmounted | true | -| isVisible | (instance): boolean | A function to get current visibility of the component | - | -| isForceRender | (instance): boolean | A function to determine whether to render popup even it's not visible | - | -| getComponent | (instance, extra): ReactNode | A function to get the component which will be rendered into container | - | -| getContainer | (instance): HTMLElement | A function to get the container | | - -### Portal - -Render children to the specific container; - -```jsx|pure -import Portal from 'rc-util/lib/Portal'; -``` - -Props: - -| Prop | Type | Description | Default | -| ------------ | --------------- | ------------------------------- | ------- | -| children | ReactChildren | Content render to the container | - | -| getContainer | (): HTMLElement | A function to get the container | - | - -### getScrollBarSize - -> (fresh?: boolean): number - -Get the width of scrollbar. - -```jsx|pure -import getScrollBarSize from 'rc-util/lib/getScrollBarSize'; -``` - -### guid - -> (): string - -To generate a global unique id across current application. - -```jsx|pure -import guid from 'rc-util/lib/guid'; -``` - -### pickAttrs - -> (props: Object): Object - -Pick valid HTML attributes and events from props. - -```jsx|pure -import pickAttrs from 'rc-util/lib/pickAttrs'; -``` - -### warn - -> (msg: string): void - -A shallow wrapper of `console.warn`. - -```jsx|pure -import warn from 'rc-util/lib/warn'; -``` - -### warning - -> (valid: boolean, msg: string): void - -A shallow wrapper of [warning](https://github.com/BerkeleyTrue/warning), but only warning once for the same message. +## Highlights -```jsx|pure -import warning, { noteOnce } from 'rc-util/lib/warning'; +- Built for React and maintained by the rc-component team. +- Used by Ant Design and other React component libraries. +- Ships TypeScript declarations with both ES module and CommonJS outputs. +- Keeps examples, tests, and preview builds aligned with the package source. -warning(false, '[antd Component] test hello world'); +> This package was historically published as `rc-util`. Prefer the scoped package for new code. -// Low level note -noteOnce(false, '[antd Component] test hello world'); -``` - -### Children - -A collection of functions to operate React elements' children. - -#### Children/mapSelf - -> (children): children - -Return a shallow copy of children. - -```jsx|pure -import mapSelf from 'rc-util/lib/Children/mapSelf'; -``` - -#### Children/toArray - -> (children: ReactNode[]): ReactNode[] - -Convert children into an array. - -```jsx|pure -import toArray from 'rc-util/lib/Children/toArray'; -``` - -### Dom - -A collection of functions to operate DOM elements. - -#### Dom/addEventlistener - -> (target: ReactNode, eventType: string, listener: Function): { remove: Function } - -A shallow wrapper of [add-dom-event-listener](https://github.com/yiminghe/add-dom-event-listener). - -```jsx|pure -import addEventlistener from 'rc-util/lib/Dom/addEventlistener'; -``` - -#### Dom/canUseDom - -> (): boolean - -Check if DOM is available. - -```jsx|pure -import canUseDom from 'rc-util/lib/Dom/canUseDom'; -``` - -#### Dom/class - -A collection of functions to operate DOM nodes' class name. - -- `hasClass(node: HTMLElement, className: string): boolean` -- `addClass(node: HTMLElement, className: string): void` -- `removeClass(node: HTMLElement, className: string): void` +## Install -```jsx|pure -import cssClass from 'rc-util/lib/Dom/class; +```bash +npm install @rc-component/util ``` -#### Dom/contains +## Usage -> (root: HTMLElement, node: HTMLElement): boolean - -Check if node is equal to root or in the subtree of root. - -```jsx|pure -import contains from 'rc-util/lib/Dom/contains'; +```tsx | pure +import { + Portal, + raf, + useEvent, + useLayoutEffect, + warning, +} from '@rc-component/util'; ``` -#### Dom/css - -A collection of functions to get or set css styles. +## Examples -- `get(node: HTMLElement, name?: string): any` -- `set(node: HTMLElement, name?: string, value: any) | set(node, object)` -- `getOuterWidth(el: HTMLElement): number` -- `getOuterHeight(el: HTMLElement): number` -- `getDocSize(): { width: number, height: number }` -- `getClientSize(): { width: number, height: number }` -- `getScroll(): { scrollLeft: number, scrollTop: number }` -- `getOffset(node: HTMLElement): { left: number, top: number }` +Run the local dumi site: -```jsx|pure -import css from 'rc-util/lib/Dom/css'; +```bash +npm install +npm start ``` -#### Dom/focus +Then open `http://localhost:8000`. -A collection of functions to operate focus status of DOM node. - -- `saveLastFocusNode(): void` -- `clearLastFocusNode(): void` -- `backLastFocusNode(): void` -- `getFocusNodeList(node: HTMLElement): HTMLElement[]` get a list of focusable nodes from the subtree of node. -- `limitTabRange(node: HTMLElement, e: Event): void` +## API -```jsx|pure -import focus from 'rc-util/lib/Dom/focus'; -``` +The package exposes small, focused helpers used across rc-component and Ant Design packages. Import the public entry when possible, and use subpath imports for specialized DOM, React, or test helpers. -#### Dom/support +| Area | Examples | +| --------------- | ---------------------------------------------------------------------------------- | +| React hooks | `useEvent`, `useLayoutEffect`, `useMergedState`, `useState` helpers | +| React utilities | `Children/toArray`, `composeRef`, `pickAttrs`, `Portal` | +| DOM utilities | `Dom/canUseDom`, `Dom/contains`, `Dom/dynamicCSS`, `Dom/focus`, `getScrollBarSize` | +| Async helpers | `raf`, `raf.cancel` | +| Warnings | `warning`, `noteOnce`, `resetWarned` | +| Tests | `test/domHook` for DOM prototype spies | -> { animation: boolean | Object, transition: boolean | Object } +Examples in `docs/examples` cover the commonly used subpath helpers. -A flag to tell whether current environment supports `animationend` or `transitionend`. +## Development -```jsx|pure -import support from 'rc-util/lib/Dom/support'; +```bash +npm install +npm start +npm test +npm run build ``` -### KeyCode +The dumi site runs at `http://localhost:8000` by default. -> Enum +## Release -Enum of KeyCode, please check the [definition](https://github.com/react-component/util/blob/master/src/KeyCode.ts) of it. - -```jsx|pure -import KeyCode from 'rc-util/lib/KeyCode'; +```bash +npm run prepublishOnly ``` -#### KeyCode.isTextModifyingKeyEvent - -> (e: Event): boolean - -Whether text and modified key is entered at the same time. - -#### KeyCode.isCharacterKey - -> (keyCode: KeyCode): boolean - -Whether character is entered. - -### ScrollLocker - -> ScrollLocker<{lock: (options: {container: HTMLElement}) => void, unLock: () => void}> - -improve shake when page scroll bar hidden. - -`ScrollLocker` change body style, and add a class `ant-scrolling-effect` when called, so if you page look abnormal, please check this; - -```js -import ScrollLocker from 'rc-util/lib/Dom/scrollLocker'; - -const scrollLocker = new ScrollLocker(); - -// lock -scrollLocker.lock() - -// unLock -scrollLocker.unLock() -``` +The release flow is handled by `@rc-component/np` through the `rc-np` command after the package build. ## License -[MIT](/LICENSE) +@rc-component/util is released under the [MIT](./LICENSE) license. diff --git a/README.zh-CN.md b/README.zh-CN.md new file mode 100644 index 00000000..0b3e6dbc --- /dev/null +++ b/README.zh-CN.md @@ -0,0 +1,93 @@ + Ant Design 生态的一部分。
🛠️ rc-component 共享工具集合，包含 DOM、React 和测试辅助能力。
+ +
+
+
+
+
+
English | 简体中文
+ + +## 特性 + +- 面向 React 构建，并由 rc-component 团队维护。 +- 被 Ant Design 使用和其他 React 组件库使用。 +- 提供 TypeScript 类型声明，同时输出 ES module 和 CommonJS 产物。 +- 示例、测试和预览构建与包源码保持一致。 + +> 该包历史上曾以 `rc-util` 发布。新代码推荐使用带 scope 的包名。 + +## 安装 + +```bash +npm install @rc-component/util +``` + +## 使用 + +```tsx | pure +import { + Portal, + raf, + useEvent, + useLayoutEffect, + warning, +} from '@rc-component/util'; +``` + +## 示例 + +运行本地 dumi 站点： + +```bash +npm install +npm start +``` + +然后打开 `http://localhost:8000`。 + +## API + +该包提供在 rc-component 和 Ant Design 包中复用的小型聚焦工具。优先导入公开入口；针对 DOM、React 或测试辅助能力，可使用子路径导入。 + +| 范围 | 示例 | +| --------------- | ---------------------------------------------------------------------------------- | +| React hooks | `useEvent`, `useLayoutEffect`, `useMergedState`, `useState` 辅助方法 | +| React 工具 | `Children/toArray`, `composeRef`, `pickAttrs`, `Portal` | +| DOM 工具 | `Dom/canUseDom`, `Dom/contains`, `Dom/dynamicCSS`, `Dom/focus`, `getScrollBarSize` | +| 异步辅助方法 | `raf`, `raf.cancel` | +| 警告工具 | `warning`, `noteOnce`, `resetWarned` | +| 测试工具 | `test/domHook` 用于 DOM 原型 spy | + +`docs/examples` 中的示例覆盖了常用的子路径辅助工具。 + +## 本地开发 + +```bash +npm install +npm start +npm test +npm run build +``` + +dumi 站点默认运行在 `http://localhost:8000`。 + +## 发布 + +```bash +npm run prepublishOnly +``` + +包构建完成后，发布流程由 `@rc-component/np` 通过 `rc-np` 命令处理。 + +## 许可证 + +@rc-component/util 基于 [MIT](./LICENSE) 许可证发布。 diff --git a/docs/examples/dynaymicCSS.tsx b/docs/examples/dynaymicCSS.tsx index d77f14ee..3b6d3d43 100644 --- a/docs/examples/dynaymicCSS.tsx +++ b/docs/examples/dynaymicCSS.tsx @@ -1,5 +1,5 @@ -import type { Prepend } from 'rc-util/es/Dom/dynamicCSS'; -import { removeCSS, updateCSS } from 'rc-util/es/Dom/dynamicCSS'; +import type { Prepend } from '@rc-component/util/es/Dom/dynamicCSS'; +import { removeCSS, updateCSS } from '@rc-component/util/es/Dom/dynamicCSS'; import React from 'react'; function injectStyle(id: number, prepend?: Prepend, priority?: number) { diff --git a/docs/examples/getScrollBarSize.tsx b/docs/examples/getScrollBarSize.tsx index b6988f6f..5abedc5e 100644 --- a/docs/examples/getScrollBarSize.tsx +++ b/docs/examples/getScrollBarSize.tsx @@ -1,6 +1,6 @@ import getScrollBarSize, { getTargetScrollBarSize, -} from 'rc-util/es/getScrollBarSize'; +} from '@rc-component/util/es/getScrollBarSize'; import React from 'react'; const cssText = ` diff --git a/docs/examples/portal.tsx b/docs/examples/portal.tsx index 50b30c3a..9f5b2b34 100644 --- a/docs/examples/portal.tsx +++ b/docs/examples/portal.tsx @@ -1,24 +1,29 @@ import React from 'react'; -import PortalWrapper from 'rc-util/es/PortalWrapper'; +import { Portal } from '@rc-component/util'; const Demo: React.FC = () => { const divRef = React.useRefPress F12 to open the console (Click Clear Console)
+1
2