@tiny-codes/react-easy 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,20 @@
+<!-- markdownlint-disable MD009, MD024 -->
+
+# Changelog
+
+- ## 1.0.0
+
+2025-2-7
+
+The first release ships the following contents
+
+- **Components**
+
+  - `ConfirmAction` component that renders a button that triggers a confirmation modal before executing the action
+  - `DeleteConfirmAction` component that renders a button that triggers a deletion confirmation modal before deleting action
+  - `ModalAction` component that renders a button that triggers a modal with a form to collect user input
+  - `ConfigProvider` component that provides a global configuration for the components
+
+- **Hooks**
+
+  - `useRefFunction` hook that wraps a function to an immutable function

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 李凤宝(Leo)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,194 @@
+# @tiny-codes/react-easy
+
+[English](./README.md) | [中文](./README.zh-CN.md)
+
+> Helps you use React and AntDesign more easily
+
+[![npm version](https://img.shields.io/npm/v/@tiny-codes/react-easy.svg)](https://www.npmjs.com/package/@tiny-codes/react-easy)
+[![npm bundle size](https://img.shields.io/bundlephobia/minzip/@tiny-codes/react-easy)](https://bundlephobia.com/result?p=@tiny-codes/react-easy)
+[![npm downloads](https://img.shields.io/npm/dm/@tiny-codes/react-easy.svg)](https://www.npmjs.com/package/@tiny-codes/react-easy)
+![GitHub License](https://img.shields.io/github/license/shijistar/react-easy?label=License)
+
+⬇️    [Introduction](#introduction) | [Installation](#installation) | [Usage](#usage) | [Compatibility](#compatibility)    ⬇️
+
+## Introduction
+
+Includes a series of React components, some of which are secondary encapsulations of AntDesign, helping you use the AntDesign component library more easily. In addition, it also includes some common Hooks and utility functions.
+
+> The library is shipped in ECMAScript version `ES2016`
+
+## Installation
+
+Install using npm:
+
+```bash
+npm install @tiny-codes/react-easy
+```
+
+Install using pnpm:
+
+```bash
+pnpm add @tiny-codes/react-easy
+```
+
+Install using bun:
+
+```bash
+bun add @tiny-codes/react-easy
+```
+
+Or using yarn:
+
+```bash
+yarn add @tiny-codes/react-easy
+```
+
+## Usage
+
+### ConfigProvider
+
+You can use `ConfigProvider` to provide a global configuration for the components.
+
+```jsx
+import { ConfigProvider } from '@tiny-codes/react-easy';
+import { useTranslation } from 'react-i18next';
+
+const { t } = useTranslation();
+
+<ConfigProvider
+  localize={t}
+  defaultConfirmTitle="common.confirm"
+  defaultConfirmContent="common.confirm.content"
+  defaultDeletionConfirmTitle="common.confirm"
+  defaultDeletionConfirmContent="common.confirmDeleteValue"
+>
+  <App />
+</ConfigProvider>;
+```
+
+In the example above, the `localize` function uses `react-i18next`, you can also use other internationalization libraries, or directly pass in a custom function that satisfies your internationalization solution.
+
+`defaultConfirmTitle` and `defaultConfirmContent` are the default confirmation box title and content, `defaultDeletionConfirmTitle` and `defaultDeletionConfirmContent` are the default deletion confirmation box title and content. You can use the key of the internationalization resource, or use plain text if you don't consider internationalization.
+
+### ConfirmAction (Confirm box)
+
+```jsx
+import { ConfirmAction } from '@tiny-codes/react-easy';
+
+<ConfirmAction.Button title="Are you sure?" content="This action cannot be undone!" onOk={handleTurnOff}>
+  Turn off
+</ConfirmAction.Button>;
+```
+
+With the default values of `ConfigProvider`, you can simplify the code further:
+
+```jsx
+<ConfirmAction.Button onOk={handleTurnOff}>Turn off</ConfirmAction.Button>
+```
+
+### DeleteConfirmAction (Deletion confirm box)
+
+```jsx
+import { DeleteConfirmAction } from '@tiny-codes/react-easy';
+
+<DeleteConfirmAction.Button title="Are you sure?" content="This action cannot be undone!" onOk={handleDelete}>
+  Delete
+</DeleteConfirmAction.Button>;
+```
+
+With the default values of `ConfigProvider`, you can simplify the code further:
+
+```jsx
+<DeleteConfirmAction.Button onOk={handleDelete}>Delete</DeleteConfirmAction.Button>
+```
+
+### ModalAction (Modal box)
+
+```jsx
+import { ModalAction } from '@tiny-codes/react-easy';
+
+<ModalAction.Button title="Edit" onOk={handleEdit}>
+  Edit
+</ModalAction.Button>;
+```
+
+### withModalAction
+
+This is a higher-order component that wraps a form component into a modal, and when you click the button to display the modal, the content of the modal is the form component, which is used to edit data.
+
+_form.tsx_
+
+```jsx
+import { withModalAction, FormCompPropsConstraint } from '@tiny-codes/react-easy';
+
+type FormProps = { data?: FormData }; // Form component properties
+type FormData = { name: string; age: number; } // Form binding data
+
+const EditForm: React.FC<FormProps & FormCompPropsConstraint<FormData>> = (props) => {
+  // The form instance is automatically injected by withModalAction, do not create the form instance yourself
+  // onSave is to pass the submission function to withModalAction, which is called when the user clicks the OK button
+  const { data, form, onSave } = props;
+
+  // 3. Click the OK button to save the form data
+  const handleSubmit = useRefFunction(async (values: FormData) => {
+    await axios.put('/api/edit', values);
+  });
+
+  // 1. Register save event
+  useEffect(() => { onSave(handleSubmit); }, [onSave, handleSubmit]);
+
+  // 2. Bind form data
+  return (
+    <Form form={form} initialValues={data}>
+      <Form.Item name="name" label="Name"> <Input /> </Form.Item>
+      <Form.Item name="age" label="Age"> <InputNumber /> </Form.Item>
+    </Form>
+  );
+};
+
+export default withModalAction(EditForm);
+```
+
+_app.tsx_
+
+```jsx
+<EditModalAction>Edit</EditModalAction>
+```
+
+### useRefFunction
+
+`useRefFunction` is used to wrap a function into an immutable function, which is suitable for scenarios that need to be used in `useEffect`, avoiding repeated execution of useEffect due to changes in function references. Another common scenario is that multiple variables are used in useEffect, but only one variable needs to be monitored in practice. We may have to use multiple `useRef` to save those other variables so that they do not appear in the dependency array of useEffect. At this time, we can use `useRefFunction` to solve this problem.
+
+`useRefFunction` returns an immutable function, the reference of this function is immutable throughout the lifecycle of the component, but the variables used inside are real-time changes.
+
+```jsx
+import { useRefFunction } from '@tiny-codes/react-easy';
+
+const Foo: React.FC<{ value: string; }> = (props) => {
+  const printValue = useRefFunction(() => {
+    // The value here changes in real time, but the reference of printValue is stable and unchanged
+    console.log(props.value);
+  });
+
+  useEffect(() => {
+    const timer = setInterval(() => { printValue(); }, 1000);
+    return () => { clearInterval(timer); };
+  }, [printValue])
+
+  return null;
+};
+```
+
+## Compatibility
+
+- `react` >= 16.8.0
+- `react-is` >= 16.8.0 _(Should be consistent with react)_
+- `antd` >= 5.1.0
+
+> To support different versions of npm dependencies, we use `peerDependencies` in the package.json declaration instead of `dependencies`, which requires you to explicitly install these dependencies in your project and ensure that they meet the version requirements. If these dependencies are not installed in the project, it may cause the installation of `@tiny-codes/react-easy` to fail.
+>
+> The ECMAScript version of shipped codes is `ES2016`, please ensure that your bundler tool supports this version
+
+```
+
+```

package/README.zh-CN.md

@@ -0,0 +1,190 @@
+# @tiny-codes/react-easy
+
+[English](./README.md) | [中文](./README.zh-CN.md)
+
+> 让使用 React 和 AntDesign 变得更简单
+
+[![npm version](https://img.shields.io/npm/v/@tiny-codes/react-easy.svg)](https://www.npmjs.com/package/@tiny-codes/react-easy)
+[![npm bundle size](https://img.shields.io/bundlephobia/minzip/@tiny-codes/react-easy)](https://bundlephobia.com/result?p=@tiny-codes/react-easy)
+[![npm downloads](https://img.shields.io/npm/dm/@tiny-codes/react-easy.svg)](https://www.npmjs.com/package/@tiny-codes/react-easy)
+![GitHub License](https://img.shields.io/github/license/shijistar/react-easy?label=License)
+
+⬇️    [介绍](#介绍) | [安装](#安装) | [使用](#使用) | [兼容性](#兼容性)    ⬇️
+
+## 介绍
+
+包含一系列的React组件，其中一些是对AntDesign的二次封装，帮助你更方便地使用AntDesign组件库。除此之外还包含一些常用的Hooks和工具函数。
+
+> 该库发布的ECMAScript版本为 `ES2016`
+
+## 安装
+
+使用 npm 安装:
+
+```bash
+npm install @tiny-codes/react-easy
+```
+
+使用 pnpm 安装:
+
+```bash
+pnpm add @tiny-codes/react-easy
+```
+
+使用 bun 安装:
+
+```bash
+bun add @tiny-codes/react-easy
+```
+
+或者使用 yarn 安装:
+
+```bash
+yarn add @tiny-codes/react-easy
+```
+
+## 使用
+
+### ConfigProvider
+
+你可以使用 `ConfigProvider` 为组件提供全局配置
+
+```jsx
+import { ConfigProvider } from '@tiny-codes/react-easy';
+import { useTranslation } from 'react-i18next';
+
+const { t } = useTranslation();
+
+<ConfigProvider
+  localize={t}
+  defaultConfirmTitle="common.confirm"
+  defaultConfirmContent="common.confirm.content"
+  defaultDeletionConfirmTitle="common.confirm"
+  defaultDeletionConfirmContent="common.confirmDeleteValue"
+>
+  <App />
+</ConfigProvider>;
+```
+
+在上面的例子中，`localize` 函数使用了`react-i18next`，你也可以使用其它的国际化库，或者直接传入一个自定义函数，使用适合你的国际化方案。
+
+`defaultConfirmTitle` 和 `defaultConfirmContent` 是默认的确认框标题和内容，`defaultDeletionConfirmTitle` 和 `defaultDeletionConfirmContent` 是默认的删除确认框标题和内容。你可以使用国际化资源的键值，也可以使用普通文本，如果不考虑国际化的话。
+
+### ConfirmAction (确认框)
+
+```jsx
+import { ConfirmAction } from '@tiny-codes/react-easy';
+
+<ConfirmAction.Button title="是否确认？" content="这个操作无法撤销！" onOk={handleTurnOff}>
+  关闭
+</ConfirmAction.Button>;
+```
+
+借助 `ConfigProvider` 的默认值，你可以将代码进一步简化为：
+
+```jsx
+<ConfirmAction.Button onOk={handleTurnOff}>关闭</ConfirmAction.Button>
+```
+
+### DeleteConfirmAction（删除确认框）
+
+```jsx
+import { DeleteConfirmAction } from '@tiny-codes/react-easy';
+
+<DeleteConfirmAction.Button title="确定删除吗？" content="删除动作无法撤销!" onOk={handleDelete}>
+  删除
+</DeleteConfirmAction.Button>;
+```
+
+借助 `ConfigProvider` 的默认值，你可以将代码进一步简化为：
+
+```jsx
+<DeleteConfirmAction.Button onOk={handleDelete}>删除</DeleteConfirmAction.Button>
+```
+
+### ModalAction (模态框)
+
+```jsx
+import { ModalAction } from '@tiny-codes/react-easy';
+
+<ModalAction.Button title="Edit" onOk={handleEdit}>
+  Edit
+</ModalAction.Button>;
+```
+
+### withModalAction
+
+这是一个高阶组件，用于将一个表单组件包装成一个模态框，当点击按钮显示模态框时，模态框内容就是这个表单组件，用于编辑数据。
+
+_form.tsx_
+
+```jsx
+import { withModalAction, FormCompPropsConstraint } from '@tiny-codes/react-easy';
+
+type FormProps = { data?: FormData }; // 表单组件的属性
+type FormData = { name: string; age: number; } // 表单绑定数据
+
+const EditForm: React.FC<FormProps & FormCompPropsConstraint<FormData>> = (props) => {
+  // form实例是由 withModalAction 自动注入的，不要自己创建表单实例
+  // onSave的作用是将提交函数传递给 withModalAction，在用户点击确定按钮时调用
+  const { data, form, onSave } = props;
+
+  // 3. 点击确定按钮，保存表单数据
+  const handleSubmit = useRefFunction(async (values: FormData) => {
+    await axios.put('/api/edit', values);
+  });
+
+  // 1. 注册保存事件
+  useEffect(() => { onSave(handleSubmit); }, [onSave, handleSubmit]);
+
+  // 2. 绑定表单数据
+  return (
+    <Form form={form} initialValues={data}>
+      <Form.Item name="name" label="姓名"> <Input /> </Form.Item>
+      <Form.Item name="age" label="年龄"> <InputNumber /> </Form.Item>
+    </Form>
+  );
+};
+
+export default withModalAction(EditForm);
+```
+
+_app.tsx_
+
+```jsx
+<EditModalAction>编辑</EditModalAction>
+```
+
+### useRefFunction
+
+`useRefFunction` 用于将一个函数包装成不可变的函数, 适用于需要在 `useEffect` 中使用的场景，避免因为函数引用的变化导致 useEffect 重复执行。另外一个常见的场景是，在 useEffect 中使用了多个变量，但实际只需要监听某一个变量，我们可能不得不使用多个 `useRef` 来保存其它那些变量，以不让他们出现在 useEffect 的依赖数组中，这时候我们可以使用 `useRefFunction` 来解决这个问题。
+
+`useRefFunction` 会返回一个不可变的函数，这个函数的引用在组件的整个生命周期中都是不变的，但在其内部使用的变量是实时变化的。
+
+```jsx
+import { useRefFunction } from '@tiny-codes/react-easy';
+
+const Foo: React.FC<{ value: string; }> = (props) => {
+  const printValue = useRefFunction(() => {
+    // 这里的 value 是实时变化的，但 printValue 的引用是稳定不变的
+    console.log(props.value);
+  });
+
+  useEffect(() => {
+    const timer = setInterval(() => { printValue(); }, 1000);
+    return () => { clearInterval(timer); };
+  }, [printValue])
+
+  return null;
+};
+```
+
+## 兼容性
+
+- `react` >= 16.8.0
+- `react-is` >= 16.8.0 _(需要与 react 版本一致)_
+- `antd` >= 5.1.0
+
+> 为了支持不同版本的 npm 依赖库，我们在 package.json 声明中使用了`peerDependencies`，而不是`dependencies`，这需要在你的项目中显式安装这些依赖库，并且确保它们符合版本要求。如果项目中没有安装这些依赖库，可能会导致 `@tiny-codes/react-easy` 安装失败。
+>
+> npm 包输出的 ECMAScript 版本为 `ES2016`，请确保你的打包工具支持这个版本

package/es/components/ConfigProvider/context.d.ts

@@ -0,0 +1,49 @@
+import { type ReactNode } from 'react';
+export interface AntHelperContextProps {
+    /**
+     * **EN:** Default title of the confirm dialog, used for global configuration, can be normal text
+     * or the key of localized resources, the key of localized resources will be converted into
+     * localized text through the `localize` method
+     *
+     * **CN:** 确认弹框的默认标题，用于全局配置，可以是普通文本或本地化资源的键值，本地化资源的键值会通过`localize`方法转换成本地化文本
+     */
+    defaultConfirmTitle?: ReactNode;
+    /**
+     * **EN:** Default content of the confirm dialog, used for global configuration, can be normal
+     * text or the key of localized resources, the key of localized resources will be converted into
+     * localized text through the `localize` method
+     *
+     * **CN:** 确认弹框的默认内容，用于全局配置，可以是普通文本或本地化资源的键值，本地化资源的键值会通过`localize`方法转换成本地化文本
+     */
+    defaultConfirmContent?: ReactNode;
+    /**
+     * **EN:** Default title of the deletion confirmation dialog, used for global configuration, can
+     * be normal text or the key of localized resources, the key of localized resources will be
+     * converted into localized text through the `localize` method
+     *
+     * **CN:** 删除确认弹框的默认标题，用于全局配置，可以是普通文本或本地化资源的键值，本地化资源的键值会通过`localize`方法转换成本地化文本
+     */
+    defaultDeletionConfirmTitle?: ReactNode;
+    /**
+     * **EN:** Default content of the deletion confirmation dialog, used for global configuration, can
+     * be normal text or the key of localized resources, the key of localized resources will be
+     * converted into localized text through the `localize` method
+     *
+     * **CN:** 删除确认弹框的默认内容，用于全局配置，可以是普通文本或本地化资源的键值，本地化资源的键值会通过`localize`方法转换成本地化文本
+     */
+    defaultDeletionConfirmContent?: ReactNode;
+    /**
+     * **EN:** Get localized text
+     *
+     * **CN:** 获取本地化文本
+     *
+     * @param key Normal text or key of local resource | 普通文本或本地资源的键值
+     * @param args Parameters of the localized text | 本地化文本的参数
+     *
+     * @returns Localized text | 本地化文本
+     */
+    localize?: <T>(key: T, args?: Record<string, unknown>) => ReactNode;
+}
+export declare const defaultContextValue: AntHelperContextProps;
+declare const AntHelperContext: import("react").Context<AntHelperContextProps>;
+export default AntHelperContext;

package/es/components/ConfigProvider/context.js

@@ -0,0 +1,5 @@
+import { createContext } from 'react';
+export const defaultContextValue = {};
+const AntHelperContext = createContext(defaultContextValue);
+export default AntHelperContext;
+//# sourceMappingURL=context.js.map

package/es/components/ConfigProvider/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../../src/components/ConfigProvider/context.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAkB,MAAM,OAAO,CAAC;AAoDtD,MAAM,CAAC,MAAM,mBAAmB,GAA0B,EAAE,CAAC;AAE7D,MAAM,gBAAgB,GAAG,aAAa,CAAwB,mBAAmB,CAAC,CAAC;AAEnF,eAAe,gBAAgB,CAAC"}

package/es/components/ConfigProvider/index.d.ts

@@ -0,0 +1,12 @@
+import type { FC, ReactNode } from 'react';
+import { type AntHelperContextProps } from './context';
+export interface ConfigProviderProps extends AntHelperContextProps {
+    children: ReactNode;
+}
+/**
+ * **EN:** Provide global configuration for AntdHelper
+ *
+ * **CN:** 提供AntdHelper的全局配置
+ */
+declare const ConfigProvider: FC<ConfigProviderProps>;
+export default ConfigProvider;

package/es/components/ConfigProvider/index.js

@@ -0,0 +1,24 @@
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
+import { jsx as _jsx } from "react/jsx-runtime";
+import AntHelperContext from './context';
+/**
+ * **EN:** Provide global configuration for AntdHelper
+ *
+ * **CN:** 提供AntdHelper的全局配置
+ */
+const ConfigProvider = (props) => {
+    const { children } = props, restProps = __rest(props, ["children"]);
+    return _jsx(AntHelperContext.Provider, { value: restProps, children: children });
+};
+export default ConfigProvider;
+//# sourceMappingURL=index.js.map

package/es/components/ConfigProvider/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/components/ConfigProvider/index.tsx"],"names":[],"mappings":";;;;;;;;;;;;AACA,OAAO,gBAAgD,MAAM,WAAW,CAAC;AAMzE;;;;GAIG;AACH,MAAM,cAAc,GAA4B,CAAC,KAAK,EAAE,EAAE;IACxD,MAAM,EAAE,QAAQ,KAAmB,KAAK,EAAnB,SAAS,UAAK,KAAK,EAAlC,YAA0B,CAAQ,CAAC;IACzC,OAAO,KAAC,gBAAgB,CAAC,QAAQ,IAAC,KAAK,EAAE,SAAS,YAAG,QAAQ,GAA6B,CAAC;AAC7F,CAAC,CAAC;AAEF,eAAe,cAAc,CAAC"}