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

package/guidelines/components/modal-form.md

@@ -0,0 +1,88 @@
+### ModalForm
+
+**Purpose**: A form wrapped in a Modal, used for creating or editing data in a dialog.
+
+**When to use**:
+
+- For "Create" or "Edit" actions that don't require a full page.
+- When you need a quick interaction without leaving the current context.
+- When the form content is relatively short.
+
+**Semantic**:
+
+- Combines `antd` Modal and `ProForm`.
+- Automatically handles the `visible` (via `trigger`) and `loading` states.
+
+**API Overview**:
+
+- `trigger`: ReactNode. The element that opens the modal when clicked.
+- `title`: Modal title.
+- `width`: Modal width.
+- `open`: Controlled visibility state (optional).
+- `onOpenChange`: Callback when visibility changes.
+- `onFinish`: Async function. The modal closes automatically if this returns `true`.
+- `modalProps`: Props passed to the underlying `antd` Modal.
+
+**Usage Pattern**:
+
+```tsx
+import {
+  ModalForm,
+  ProFormText,
+  ProFormSelect,
+} from '@ant-design/pro-components';
+import { Button, message } from 'antd';
+import { PlusOutlined } from '@ant-design/icons';
+
+export default () => {
+  return (
+    <ModalForm<{
+      name: string;
+      company: string;
+    }>
+      title="Create New Entry"
+      trigger={
+        <Button type="primary">
+          <PlusOutlined />
+          New Entry
+        </Button>
+      }
+      autoFocusFirstInput
+      modalProps={{
+        destroyOnClose: true,
+        onCancel: () => console.log('run'),
+      }}
+      onFinish={async (values) => {
+        await waitTime(2000);
+        console.log(values.name);
+        message.success('Submitted successfully');
+        return true;
+      }}
+    >
+      <ProFormText
+        width="md"
+        name="name"
+        label="Name"
+        placeholder="Please enter name"
+        rules={[{ required: true, message: 'This is required' }]}
+      />
+      <ProFormSelect
+        width="md"
+        name="type"
+        label="Type"
+        options={[
+          { value: '1', label: 'Type 1' },
+          { value: '2', label: 'Type 2' },
+        ]}
+      />
+    </ModalForm>
+  );
+};
+```
+
+**Best Practices**:
+
+- Always use `trigger` when possible to avoid managing `open` state manually.
+- Return `true` in `onFinish` to close the modal. Return `false` or nothing to keep it open (e.g. if validation fails).
+- Use `modalProps={{ destroyOnClose: true }}` to reset the form when closed.
+- Keep the form simple. If the form is very long, consider using `DrawerForm` or `StepsForm`.

package/guidelines/components/pro-card.md

@@ -0,0 +1,90 @@
+### ProCard
+
+**Purpose**: An extended Card component that supports grid layout, splitting, and tabs.
+
+**When to use**:
+
+- To organize content into sections.
+- To create dashboard layouts with multiple cards.
+- When you need a card that can be split vertically or horizontally.
+- When you need tabs inside a card.
+
+**API Overview**:
+
+- `title`: Card title.
+- `extra`: Action area in top right.
+- `split`: 'vertical' | 'horizontal'. Split the card into multiple sections.
+- `colSpan`: Grid width (like `antd` Col).
+- `gutter`: Spacing between grid items.
+- `tabs`: Configure tabs inside the card.
+- `collapsible`: Whether the card can be collapsed.
+- `ghost`: Transparent background.
+
+**Usage Pattern**:
+
+```tsx
+import { ProCard } from '@ant-design/pro-components';
+
+export default () => {
+  return (
+    <ProCard
+      title="Card Title"
+      extra="More"
+      split="vertical"
+      bordered
+      headerBordered
+    >
+      <ProCard title="Left Details" colSpan="50%">
+        Left Content
+      </ProCard>
+      <ProCard title="Right Details">
+        <div style={{ height: 360 }}>Right Content</div>
+      </ProCard>
+    </ProCard>
+  );
+};
+```
+
+**Grid Layout**:
+
+```tsx
+<ProCard gutter={16} ghost>
+  <ProCard colSpan={12} layout="center" bordered>
+    Col 12
+  </ProCard>
+  <ProCard colSpan={6} layout="center" bordered>
+    Col 6
+  </ProCard>
+  <ProCard colSpan={6} layout="center" bordered>
+    Col 6
+  </ProCard>
+</ProCard>
+```
+
+**Tabs**:
+
+```tsx
+<ProCard
+  tabs={{
+    type: 'card',
+    items: [
+      {
+        label: 'Tab 1',
+        key: 'tab1',
+        children: 'Content 1',
+      },
+      {
+        label: 'Tab 2',
+        key: 'tab2',
+        children: 'Content 2',
+      },
+    ],
+  }}
+/>
+```
+
+**Best Practices**:
+
+- Use `ghost` mode when placing cards on a gray background (like in `ProLayout`).
+- Use `split` to create master-detail views.
+- Use `colSpan` for responsive layouts.

package/guidelines/components/pro-form.md

@@ -0,0 +1,96 @@
+### ProForm
+
+**Purpose**: High-performance form component with layout capabilities and preset fields.
+
+**When to use**:
+
+- For standard data entry forms on a page.
+- When you need a simple, direct form without modal or drawer wrappers.
+
+**Note**:
+
+- For forms in a Modal, see [ModalForm](modal-form.md).
+- For forms in a Drawer, see [DrawerForm](drawer-form.md).
+- For multi-step forms, see [StepsForm](steps-form.md).
+
+**API Overview**:
+
+- `onFinish`: Triggered on form submission. `(values) => Promise<boolean | void>`
+- `initialValues`: Initial values.
+- `submitter`: Configure the submit/reset buttons.
+- `layout`: Form layout ('horizontal', 'vertical', 'inline').
+- `grid`: Enable grid layout for children.
+
+**Field Components**:
+
+- `ProFormText`
+- `ProFormTextArea`
+- `ProFormSelect`
+- `ProFormDatePicker`
+- `ProFormDateRangePicker`
+- `ProFormDigit`
+- `ProFormSwitch`
+- `ProFormUploadButton`
+- ...and many more.
+
+**Usage Pattern**:
+
+```tsx
+import {
+  ProForm,
+  ProFormText,
+  ProFormSelect,
+  ProFormDateRangePicker,
+} from '@ant-design/pro-components';
+import { message } from 'antd';
+
+export default () => {
+  return (
+    <ProForm
+      onFinish={async (values) => {
+        console.log(values);
+        message.success('Submitted successfully');
+      }}
+      initialValues={{
+        name: 'Ant Design',
+        useMode: 'chapter',
+      }}
+    >
+      <ProForm.Group>
+        <ProFormText
+          width="md"
+          name="name"
+          label="Contract Name"
+          tooltip="The name of the contract"
+          placeholder="Please enter a name"
+          rules={[{ required: true, message: 'Please enter a name' }]}
+        />
+        <ProFormText
+          width="md"
+          name="company"
+          label="Company"
+          placeholder="Please enter a company"
+        />
+      </ProForm.Group>
+      <ProForm.Group>
+        <ProFormSelect
+          request={async () => [
+            { label: 'Chapter', value: 'chapter' },
+            { label: 'Section', value: 'section' },
+          ]}
+          width="xs"
+          name="useMode"
+          label="Contract Mode"
+        />
+        <ProFormDateRangePicker name="contractTime" label="Contract Time" />
+      </ProForm.Group>
+    </ProForm>
+  );
+};
+```
+
+**Best Practices**:
+
+- Use `ProForm.Group` to group related fields.
+- Use `width` prop to control field width (`xs`, `sm`, `md`, `lg`, `xl`) instead of raw pixels for consistency.
+- Use `request` in `ProFormSelect` to load options asynchronously.

package/guidelines/components/pro-layout.md

@@ -0,0 +1,84 @@
+### ProLayout
+
+**Purpose**: A heavy-duty layout component that provides a complete application frame including Sidebar, Header, Content, and Footer.
+
+**When to use**:
+
+- As the root component of your admin application.
+- When you need a responsive layout with collapsible sidebar.
+- When you need automatic menu generation from routes.
+
+**API Overview**:
+
+- `layout`: 'side' | 'top' | 'mix'.
+- `route`: Route configuration object.
+- `location`: Current location (usually from router).
+- `menuItemRender`: Custom render for menu items.
+- `headerContentRender`: Custom content in the header.
+- `rightContentRender`: Custom content in the top right (user profile, settings).
+- `footerRender`: Custom footer.
+- `token`: Design tokens for customization.
+
+**Usage Pattern**:
+
+```tsx
+import { ProLayout } from '@ant-design/pro-components';
+import { Button } from 'antd';
+
+export default (props) => {
+  return (
+    <ProLayout
+      title="My Application"
+      logo="https://gw.alipayobjects.com/zos/antfincdn/upvrAjAPQX/Logo_Tech%252520UI.svg"
+      layout="mix"
+      splitMenus={false}
+      route={{
+        routes: [
+          {
+            path: '/welcome',
+            name: 'Welcome',
+            icon: 'smile',
+          },
+          {
+            path: '/admin',
+            name: 'Admin',
+            icon: 'crown',
+            routes: [
+              {
+                path: '/admin/sub-page',
+                name: 'Sub Page',
+                icon: 'smile',
+                component: './Welcome',
+              },
+            ],
+          },
+        ],
+      }}
+      location={{
+        pathname: '/welcome',
+      }}
+      avatarProps={{
+        src: 'https://gw.alipayobjects.com/zos/antfincdn/efFD%24IOql2/weixintupian_20170331104822.jpg',
+        title: 'User Name',
+        size: 'small',
+      }}
+      actionsRender={(props) => {
+        if (props.isMobile) return [];
+        return [
+          <Button key="key" type="text">
+            Action
+          </Button>,
+        ];
+      }}
+    >
+      {props.children}
+    </ProLayout>
+  );
+};
+```
+
+**Common Mistakes**:
+
+- Not passing `location` causing the menu highlight to fail.
+- Forgetting to handle `menuItemRender` when using a router (like `react-router-dom`) to use `Link` instead of `a` tags.
+- Using `mix` layout without setting `splitMenus` correctly for the desired behavior.

package/guidelines/components/pro-table.md

@@ -0,0 +1,142 @@
+### ProTable
+
+**Purpose**: Advanced table component that solves common table issues like search, filter, sort, and pagination.
+
+**When to use**:
+
+- For admin interfaces displaying lists of data.
+- When you need built-in search/filter forms.
+- When you need to handle server-side sorting and pagination easily.
+
+**Note**: If you need an editable table, please refer to [EditableProTable](editable-pro-table.md).
+
+**Semantic**:
+
+- Uses `antd` Table under the hood but adds a search form above and toolbars.
+- `dataSource` can be fetched automatically via `request` prop.
+
+**API Overview**:
+
+- `columns`: Array of `ProColumns`. Defines table columns and search form fields.
+- `request`: Function to fetch data. `(params, sort, filter) => Promise<{ data, success, total }>`
+- `rowKey`: Unique key for each row (required).
+- `headerTitle`: Title of the table.
+- `toolBarRender`: Render custom actions in the toolbar.
+- `actionRef`: Ref to trigger table actions like `reload()`.
+
+**ProColumns Configuration**:
+
+- `dataIndex`: Key in the data object.
+- `title`: Column header title.
+- `valueType`: Type of the data (e.g. `date`, `money`, `select`).
+- `hideInSearch`: Hide this field in the search form.
+- `hideInTable`: Hide this column in the table.
+- `search`: Configure search behavior (transform, etc.).
+- `render`: Custom render function.
+- `valueEnum`: Map of values for `select` type.
+
+**Usage Pattern**:
+
+```tsx
+import { ProTable } from '@ant-design/pro-components';
+import { useRef } from 'react';
+
+// Define the data type
+type GithubIssueItem = {
+  id: number;
+  number: number;
+  title: string;
+  state: string;
+  created_at: string;
+};
+
+export default () => {
+  const actionRef = useRef();
+
+  return (
+    <ProTable<GithubIssueItem>
+      columns={[
+        {
+          title: 'Title',
+          dataIndex: 'title',
+          copyable: true,
+          ellipsis: true,
+          tip: 'Title is too long',
+          formItemProps: {
+            rules: [
+              {
+                required: true,
+                message: 'This is required',
+              },
+            ],
+          },
+        },
+        {
+          title: 'State',
+          dataIndex: 'state',
+          valueType: 'select',
+          valueEnum: {
+            open: { text: 'Open', status: 'Error' },
+            closed: { text: 'Closed', status: 'Success' },
+          },
+        },
+        {
+          title: 'Created At',
+          dataIndex: 'created_at',
+          valueType: 'date',
+          sorter: true,
+          hideInSearch: true,
+        },
+        {
+          title: 'Option',
+          valueType: 'option',
+          render: (text, record, _, action) => [
+            <a
+              key="view"
+              onClick={() => {
+                // View action
+              }}
+            >
+              View
+            </a>,
+          ],
+        },
+      ]}
+      actionRef={actionRef}
+      cardBordered
+      request={async (params = {}, sort, filter) => {
+        // Mock request
+        return {
+          data: [],
+          success: true,
+          total: 0,
+        };
+      }}
+      columnsState={{
+        persistenceKey: 'pro-table-singe-demos',
+        persistenceType: 'localStorage',
+        defaultValue: {
+          option: { fixed: 'right', disable: true },
+        },
+      }}
+      rowKey="id"
+      search={{
+        labelWidth: 'auto',
+      }}
+      pagination={{
+        pageSize: 5,
+        onChange: (page) => console.log(page),
+      }}
+      dateFormatter="string"
+      headerTitle="Advanced Table"
+    />
+  );
+};
+```
+
+**Common Mistakes**:
+
+- Forgetting `rowKey`.
+- Manually managing `dataSource` and `loading` when `request` is better.
+- Not using `valueType` and writing custom `render` for everything.
+- Modifying `params` directly in `request` without returning the correct structure.

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).