@ant-design/pro-components 3.1.0-0 → 3.1.1-1

package/guidelines/components/steps-form.md

@@ -0,0 +1,105 @@
+### StepsForm
+
+**Purpose**: A multi-step form wizard.
+
+**When to use**:
+
+- For very long or complex processes that need to be broken down into chunks.
+- When there is a logical sequence of data entry (e.g. Account Info -> Profile Info -> Confirmation).
+
+**Semantic**:
+
+- Manages the state between steps.
+- Validates each step before proceeding to the next.
+
+**API Overview**:
+
+- `StepsForm`: The container component.
+  - `onFinish`: Triggered after the LAST step is submitted.
+  - `stepsProps`: Props for the Steps component (e.g. `current`).
+- `StepsForm.StepForm`: Individual step component.
+  - `title`: Step title.
+  - `onFinish`: Triggered when THIS step is completed. Return `true` to proceed.
+
+**Usage Pattern**:
+
+```tsx
+import { StepsForm, ProFormText, ProFormDatePicker } from '@ant-design/pro-components';
+import { Button, message, Modal } from 'antd';
+
+export default () => {
+  return (
+    <StepsForm
+      onFinish={async (values) => {
+        console.log(values);
+        await waitTime(1000);
+        message.success('Submission successful');
+      }}
+      formProps={{
+        validateMessages: {
+          required: 'This is required',
+        },
+      }}
+      submitter={{
+        render: (props) => {
+          if (props.step === 0) {
+            return (
+              <Button type="primary" onClick={() => props.onSubmit?.()}>
+                Next >
+              </Button>
+            );
+          }
+          if (props.step === 1) {
+            return [
+              <Button key="pre" onClick={() => props.onPre?.()}>
+                < Previous
+              </Button>,
+              <Button key="goToTree" type="primary" onClick={() => props.onSubmit?.()}>
+                Submit
+              </Button>,
+            ];
+          }
+          return null;
+        },
+      }}
+    >
+      <StepsForm.StepForm
+        name="base"
+        title="Basic Info"
+        stepProps={{
+          description: 'Enter basic details',
+        }}
+        onFinish={async () => {
+          console.log('Step 1 finished');
+          await waitTime(1000);
+          return true;
+        }}
+      >
+        <ProFormText
+          name="name"
+          label="Name"
+          width="md"
+          placeholder="Please enter name"
+          rules={[{ required: true }]}
+        />
+        <ProFormDatePicker name="date" label="Date" />
+      </StepsForm.StepForm>
+      <StepsForm.StepForm
+        name="checkbox"
+        title="Configuration"
+        stepProps={{
+          description: 'Enter configuration',
+        }}
+      >
+        <ProFormText name="config" label="Config" width="md" />
+      </StepsForm.StepForm>
+    </StepsForm>
+  );
+};
+```
+
+**Best Practices**:
+
+- Break down complex forms into 3-5 logical steps.
+- Use `onFinish` in `StepForm` to validate or save intermediate data.
+- Ensure the final `onFinish` handles the aggregation of all data.

package/guidelines/design-tokens/colors.md

@@ -0,0 +1,58 @@
+# Color Design Tokens
+
+ProComponents inherits the Design Token system from Ant Design v5.
+
+## Token Categories
+
+### Brand Color (`colorPrimary`)
+
+The primary color of the application.
+
+- `colorPrimary`: Main brand color.
+- `colorPrimaryBg`: Background color for light brand elements.
+- `colorPrimaryText`: Text color for brand elements.
+
+### Functional Colors
+
+- `colorSuccess`: Success state (Green).
+- `colorWarning`: Warning state (Gold).
+- `colorError`: Error state (Red).
+- `colorInfo`: Info state (Blue).
+
+### Neutral Colors
+
+- `colorText`: Default text color.
+- `colorTextSecondary`: Secondary text color.
+- `colorTextTertiary`: Tertiary text color.
+- `colorBgContainer`: Container background color (usually white).
+- `colorBgLayout`: Layout background color (usually light gray).
+- `colorBorder`: Default border color.
+
+## Usage
+
+You can access these tokens using `useToken` hook from `antd`.
+
+```tsx
+import { theme } from 'antd';
+
+const { useToken } = theme;
+
+const MyComponent = () => {
+  const { token } = useToken();
+
+  return (
+    <div
+      style={{
+        backgroundColor: token.colorPrimary,
+        color: token.colorTextLightSolid,
+      }}
+    >
+      Brand Content
+    </div>
+  );
+};
+```
+
+## ProComponents Specifics
+
+ProComponents may use additional tokens for specific layouts, which are documented in [layout.md](layout.md).

package/guidelines/design-tokens/layout.md

@@ -0,0 +1,53 @@
+# Layout Design Tokens
+
+ProLayout uses a specific set of design tokens to control its appearance. These tokens can be configured via `ProConfigProvider` or `ProLayout`'s `token` prop.
+
+## Token Structure
+
+The `LayoutDesignToken` consists of:
+
+### Sider Tokens (`sider`)
+
+Controls the appearance of the side menu.
+
+- `colorMenuBackground`: Background color of the menu
+- `colorBgMenuItemSelected`: Background of selected item
+- `colorTextMenuSelected`: Text color of selected item
+- `colorBgMenuItemHover`: Background of hovered item
+- `colorTextMenu`: Default text color
+- `menuHeight`: Height of menu items
+
+### Header Tokens (`header`)
+
+Controls the appearance of the top header.
+
+- `colorBgHeader`: Background color
+- `heightLayoutHeader`: Height of the header (default 56)
+- `colorHeaderTitle`: Color of the title
+- `colorTextMenu`: Color of menu items in header
+
+### PageContainer Tokens (`pageContainer`)
+
+Controls the content area wrapper.
+
+- `colorBgPageContainer`: Background color of the page container
+- `paddingInlinePageContainerContent`: Horizontal padding
+- `paddingBlockPageContainerContent`: Vertical padding
+
+## Usage
+
+```tsx
+<ProLayout
+  token={{
+    header: {
+      colorBgHeader: '#292f33',
+      colorHeaderTitle: '#fff',
+    },
+    sider: {
+      colorMenuBackground: '#fff',
+    },
+  }}
+>
+  {/* content */}
+</ProLayout>
+```

package/guidelines/design-tokens/typography.md

@@ -0,0 +1,49 @@
+# Typography Design Tokens
+
+ProComponents uses Ant Design's typography tokens.
+
+## Token Categories
+
+### Font Size
+
+- `fontSize`: Default font size (14px).
+- `fontSizeSM`: Small font size (12px).
+- `fontSizeLG`: Large font size (16px).
+- `fontSizeXL`: Extra large font size (20px).
+- `fontSizeHeading1`: H1 size.
+- `fontSizeHeading2`: H2 size.
+- `fontSizeHeading3`: H3 size.
+- `fontSizeHeading4`: H4 size.
+- `fontSizeHeading5`: H5 size.
+
+### Line Height
+
+- `lineHeight`: Default line height.
+- `lineHeightHeading1` to `lineHeightHeading5`: Line heights for headings.
+
+### Font Weight
+
+- `fontWeightStrong`: Bold weight (600).
+
+## Usage
+
+```tsx
+import { theme } from 'antd';
+
+const { useToken } = theme;
+
+const MyComponent = () => {
+  const { token } = useToken();
+
+  return (
+    <h1
+      style={{
+        fontSize: token.fontSizeHeading1,
+        fontWeight: token.fontWeightStrong,
+      }}
+    >
+      Title
+    </h1>
+  );
+};
+```

package/guidelines/overview-components.md

@@ -0,0 +1,55 @@
+## Components
+
+Always prefer components from `@ant-design/pro-components` for complex scenarios (layouts, tables, forms). For basic elements, use `antd`.
+
+Here are the guidelines files and additional guidelines for the ProComponents:
+
+| Component        | Overview                                          | Guidelines file                                           |
+| ---------------- | ------------------------------------------------- | --------------------------------------------------------- |
+| ProCard          | Card component with better layout and actions     | [pro-card.md](components/pro-card.md)                     |
+| ProDescriptions  | Descriptions component with valueType support     | [pro-descriptions.md](components/pro-descriptions.md)     |
+| ProField         | Atomic field component for display and edit       | [pro-field.md](components/pro-field.md)                   |
+| ProForm          | Standard page form                                | [pro-form.md](components/pro-form.md)                     |
+| ModalForm        | Form inside a modal                               | [modal-form.md](components/modal-form.md)                 |
+| DrawerForm       | Form inside a drawer                              | [drawer-form.md](components/drawer-form.md)               |
+| StepsForm        | Multi-step form wizard                            | [steps-form.md](components/steps-form.md)                 |
+| ProLayout        | Heavy-duty layout component                       | [pro-layout.md](components/pro-layout.md)                 |
+| ProList          | List component with table-like features           | [pro-list.md](components/pro-list.md)                     |
+| ProSkeleton      | Skeleton loading component                        | [pro-skeleton.md](components/pro-skeleton.md)             |
+| ProTable         | Advanced table with search, filter, and valueType | [pro-table.md](components/pro-table.md)                   |
+| EditableProTable | Editable table for inline editing                 | [editable-pro-table.md](components/editable-pro-table.md) |
+
+## General Component Usage and Best Practices
+
+### Common Props
+
+Most ProComponents accept these common props:
+
+- `loading`: boolean | ReactNode - Loading state
+- `headerTitle`: ReactNode - Title for the component
+- `tooltip`: string | TooltipProps - Tooltip for the title
+- `extra`: ReactNode - Extra actions
+- `request`: (params) => Promise<Data> - Request data from server
+
+### ValueType
+
+ProComponents use `valueType` to abstract the render logic. Common valueTypes:
+
+- `text`: Default text
+- `date`, `dateRange`, `dateTime`, `time`: Date related
+- `select`: Select box (requires `valueEnum` or `request`)
+- `money`: Currency
+- `digit`: Number
+- `percent`: Percentage
+- `avatar`: Avatar
+- `image`: Image
+- `jsonCode`: JSON code block
+- `textarea`: Text area
+- `password`: Password input
+
+### Controlled vs Uncontrolled
+
+ProForm and ProTable support both controlled and uncontrolled modes.
+
+- Prefer `request` for data fetching (Uncontrolled data)
+- Use `formRef` or `actionRef` to interact with the component instance

package/guidelines/overview-icons.md

@@ -0,0 +1,23 @@
+### Icon Library
+
+ProComponents and Ant Design use `@ant-design/icons`.
+
+**Usage Pattern**:
+
+```typescript
+import {
+  PlusOutlined,
+  SettingOutlined,
+  CloseOutlined,
+  UserOutlined
+} from '@ant-design/icons'
+
+// In components
+<Button icon={<PlusOutlined />}>Add item</Button>
+```
+
+**Finding Icons**:
+
+- Icons are divided into three styles: `Outlined`, `Filled`, `TwoTone`.
+- Suffix indicates style (e.g. `HomeOutlined`, `HomeFilled`).
+- Always check `@ant-design/icons` package for availability.

package/lib/card/ProCard.js

@@ -5,22 +5,20 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.default = void 0;
-var _objectSpread2 = _interopRequireDefault(require("@babel/runtime/helpers/objectSpread2"));
 var _Card = _interopRequireDefault(require("./components/Card"));
 var _Divider = _interopRequireDefault(require("./components/Divider"));
 var _jsxRuntime = require("react/jsx-runtime");
-var Group = function Group(props) {
-  return /*#__PURE__*/(0, _jsxRuntime.jsx)(_Card.default, (0, _objectSpread2.default)({
-    styles: {
-      body: {
-        padding: 0
-      }
+const Group = props => /*#__PURE__*/(0, _jsxRuntime.jsx)(_Card.default, {
+  styles: {
+    body: {
+      padding: 0
     }
-  }, props));
-};
+  },
+  ...props
+});
 
 // 当前不对底层 Card 做封装，仅挂载子组件，直接导出
-var ProCard = _Card.default;
+const ProCard = _Card.default;
 ProCard.isProCard = true;
 ProCard.Divider = _Divider.default;
 ProCard.Group = Group;

package/lib/card/components/Actions/index.js

@@ -5,38 +5,38 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.default = void 0;
-var _classnames = _interopRequireDefault(require("classnames"));
+var _clsx = require("clsx");
 var _react = _interopRequireDefault(require("react"));
 var _style = _interopRequireDefault(require("./style"));
 var _jsxRuntime = require("react/jsx-runtime");
-var ProCardActions = function ProCardActions(props) {
-  var actions = props.actions,
-    prefixCls = props.prefixCls;
-  var _useStyle = (0, _style.default)(prefixCls),
-    wrapSSR = _useStyle.wrapSSR,
-    hashId = _useStyle.hashId;
-  if (Array.isArray(actions) && actions !== null && actions !== void 0 && actions.length) {
+const ProCardActions = props => {
+  const {
+    actions,
+    prefixCls
+  } = props;
+  const {
+    wrapSSR,
+    hashId
+  } = (0, _style.default)(prefixCls);
+  if (Array.isArray(actions) && actions?.length) {
     return wrapSSR( /*#__PURE__*/(0, _jsxRuntime.jsx)("ul", {
-      className: (0, _classnames.default)("".concat(prefixCls, "-actions"), hashId),
-      children: actions.map(function (action, index) {
-        return (
-          /*#__PURE__*/
-          // eslint-disable-next-line react/no-array-index-key
-          (0, _jsxRuntime.jsx)("li", {
-            style: {
-              width: "".concat(100 / actions.length, "%"),
-              padding: 0,
-              margin: 0
-            },
-            className: (0, _classnames.default)("".concat(prefixCls, "-actions-item"), hashId),
-            children: action
-          }, "action-".concat(index))
-        );
-      })
+      className: (0, _clsx.clsx)(`${prefixCls}-actions`, hashId),
+      children: actions.map((action, index) =>
+      /*#__PURE__*/
+      // eslint-disable-next-line react/no-array-index-key
+      (0, _jsxRuntime.jsx)("li", {
+        style: {
+          width: `${100 / actions.length}%`,
+          padding: 0,
+          margin: 0
+        },
+        className: (0, _clsx.clsx)(`${prefixCls}-actions-item`, hashId),
+        children: action
+      }, `action-${index}`))
     }));
   }
   return wrapSSR( /*#__PURE__*/(0, _jsxRuntime.jsx)("ul", {
-    className: (0, _classnames.default)("".concat(prefixCls, "-actions"), hashId),
+    className: (0, _clsx.clsx)(`${prefixCls}-actions`, hashId),
     children: actions
   }));
 };

package/lib/card/components/Actions/style.js

@@ -1,87 +1,94 @@
 "use strict";
 
-var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault").default;
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.default = useStyle;
-var _objectSpread2 = _interopRequireDefault(require("@babel/runtime/helpers/objectSpread2"));
-var _defineProperty2 = _interopRequireDefault(require("@babel/runtime/helpers/defineProperty"));
 var _provider = require("../../../provider");
-var genActionsStyle = function genActionsStyle(token) {
-  var componentCls = token.componentCls,
-    antCls = token.antCls;
-  return (0, _defineProperty2.default)({}, "".concat(componentCls, "-actions"), (0, _defineProperty2.default)((0, _defineProperty2.default)({
-    marginBlock: 0,
-    marginInline: 0,
-    paddingBlock: 0,
-    paddingInline: 0,
-    listStyle: 'none',
-    display: 'flex',
-    gap: token.marginXS,
-    background: token.colorBgContainer,
-    borderBlockStart: "".concat(token.lineWidth, "px ").concat(token.lineType, " ").concat(token.colorSplit),
-    minHeight: 42
-  }, "& > *", {
-    alignItems: 'center',
-    justifyContent: 'center',
-    flex: 1,
-    display: 'flex',
-    cursor: 'pointer',
-    color: token.colorTextSecondary,
-    transition: 'color 0.3s',
-    '&:hover': {
-      color: token.colorPrimaryHover
-    }
-  }), "& > li > div", {
-    flex: 1,
-    width: '100%',
-    marginBlock: token.marginSM,
-    marginInline: 0,
-    color: token.colorTextSecondary,
-    textAlign: 'center',
-    a: {
-      color: token.colorTextSecondary,
-      transition: 'color 0.3s',
-      '&:hover': {
-        color: token.colorPrimaryHover
-      }
-    },
-    div: (0, _defineProperty2.default)((0, _defineProperty2.default)({
-      position: 'relative',
-      display: 'block',
-      minWidth: 32,
-      fontSize: token.fontSize,
-      lineHeight: token.lineHeight,
-      cursor: 'pointer',
-      '&:hover': {
-        color: token.colorPrimaryHover,
-        transition: 'color 0.3s'
-      }
-    }, "a:not(".concat(antCls, "-btn),\n            > .anticon"), {
-      display: 'inline-block',
-      width: '100%',
-      color: token.colorTextSecondary,
-      lineHeight: '22px',
-      transition: 'color 0.3s',
-      '&:hover': {
-        color: token.colorPrimaryHover
+const genActionsStyle = token => {
+  const {
+    componentCls,
+    antCls
+  } = token;
+  return {
+    [`${componentCls}-actions`]: {
+      marginBlock: 0,
+      marginInline: 0,
+      paddingBlock: 0,
+      paddingInline: 0,
+      listStyle: 'none',
+      display: 'flex',
+      gap: token.marginXS,
+      background: token.colorBgContainer,
+      borderBlockStart: `${token.lineWidth}px ${token.lineType} ${token.colorSplit}`,
+      minHeight: 42,
+      [`& > *`]: {
+        alignItems: 'center',
+        justifyContent: 'center',
+        flex: 1,
+        display: 'flex',
+        cursor: 'pointer',
+        color: token.colorTextSecondary,
+        transition: 'color 0.3s',
+        '&:hover': {
+          color: token.colorPrimaryHover
+        }
+      },
+      [`& > li > div`]: {
+        flex: 1,
+        width: '100%',
+        marginBlock: token.marginSM,
+        marginInline: 0,
+        color: token.colorTextSecondary,
+        textAlign: 'center',
+        a: {
+          color: token.colorTextSecondary,
+          transition: 'color 0.3s',
+          '&:hover': {
+            color: token.colorPrimaryHover
+          }
+        },
+        div: {
+          position: 'relative',
+          display: 'block',
+          minWidth: 32,
+          fontSize: token.fontSize,
+          lineHeight: token.lineHeight,
+          cursor: 'pointer',
+          '&:hover': {
+            color: token.colorPrimaryHover,
+            transition: 'color 0.3s'
+          },
+          [`a:not(${antCls}-btn),
+            > .anticon`]: {
+            display: 'inline-block',
+            width: '100%',
+            color: token.colorTextSecondary,
+            lineHeight: '22px',
+            transition: 'color 0.3s',
+            '&:hover': {
+              color: token.colorPrimaryHover
+            }
+          },
+          '.anticon': {
+            fontSize: token.cardActionIconSize,
+            lineHeight: '22px'
+          }
+        },
+        '&:not(:last-child)': {
+          borderInlineEnd: `${token.lineWidth}px ${token.lineType} ${token.colorSplit}`
+        }
       }
-    }), '.anticon', {
-      fontSize: token.cardActionIconSize,
-      lineHeight: '22px'
-    }),
-    '&:not(:last-child)': {
-      borderInlineEnd: "".concat(token.lineWidth, "px ").concat(token.lineType, " ").concat(token.colorSplit)
     }
-  }));
+  };
 };
 function useStyle(prefixCls) {
-  return (0, _provider.useStyle)('ProCardActions', function (token) {
-    var proCardActionsToken = (0, _objectSpread2.default)((0, _objectSpread2.default)({}, token), {}, {
-      componentCls: ".".concat(prefixCls),
+  return (0, _provider.useStyle)('ProCardActions', token => {
+    const proCardActionsToken = {
+      ...token,
+      componentCls: `.${prefixCls}`,
       cardActionIconSize: 16
-    });
+    };
     return [genActionsStyle(proCardActionsToken)];
   });
 }