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

package/guidelines/components/editable-pro-table.md

@@ -0,0 +1,150 @@
+### EditableProTable
+
+**Purpose**: A specific mode of ProTable for editing data rows directly within the table.
+
+**When to use**:
+
+- When you need to edit data line by line.
+- For inline editing scenarios where a full form is too heavy.
+- Supports adding new rows, deleting rows, and editing existing rows.
+
+**Semantic**:
+
+- Uses `ProTable` with the `editable` prop configuration.
+- Can manage data via `value` (controlled) or internal state.
+
+**API Overview**:
+
+- `editable`: Configuration object for edit mode.
+  - `type`: 'single' | 'multiple' (default: 'single').
+  - `editableKeys`: Keys of the rows currently being edited (controlled).
+  - `onChange`: Callback when data changes.
+  - `onSave`: Async callback when a row is saved. `(key, record, originRow) => Promise<any>`
+  - `onDelete`: Async callback when a row is deleted.
+  - `actionRender`: Custom render for the action column.
+- `recordCreatorProps`: Configuration for the "Add New" button.
+  - `record`: Default data for the new row.
+  - `position`: 'top' | 'bottom'.
+
+**Usage Pattern**:
+
+```tsx
+import { EditableProTable } from '@ant-design/pro-components';
+import { useState } from 'react';
+
+type DataSourceType = {
+  id: React.Key;
+  title?: string;
+  readonly?: string;
+  decs?: string;
+  state?: string;
+  created_at?: string;
+  update_at?: string;
+  children?: DataSourceType[];
+};
+
+const defaultData: DataSourceType[] = [
+  {
+    id: 624748504,
+    title: 'Activity name',
+    readonly: 'Read-only',
+    decs: 'Description',
+    state: 'open',
+    created_at: '2020-05-26T09:42:56Z',
+    update_at: '2020-05-26T09:42:56Z',
+  },
+  {
+    id: 624691229,
+    title: 'Activity name 2',
+    readonly: 'Read-only',
+    decs: 'Description',
+    state: 'closed',
+    created_at: '2020-05-26T08:19:22Z',
+    update_at: '2020-05-26T08:19:22Z',
+  },
+];
+
+export default () => {
+  const [editableKeys, setEditableRowKeys] = useState<React.Key[]>([]);
+  const [dataSource, setDataSource] = useState<DataSourceType[]>(defaultData);
+
+  return (
+    <EditableProTable<DataSourceType>
+      rowKey="id"
+      headerTitle="Editable Table"
+      maxLength={5}
+      recordCreatorProps={{
+        position: 'bottom',
+        record: () => ({ id: (Math.random() * 1000000).toFixed(0) }),
+      }}
+      columns={[
+        {
+          title: 'Title',
+          dataIndex: 'title',
+          formItemProps: (form, { rowIndex }) => {
+            return {
+              rules: [{ required: true, message: 'Title is required' }],
+            };
+          },
+          // Columns can be editable
+          editable: true,
+        },
+        {
+          title: 'State',
+          key: 'state',
+          dataIndex: 'state',
+          valueType: 'select',
+          valueEnum: {
+            all: { text: 'All', status: 'Default' },
+            open: { text: 'Open', status: 'Error' },
+            closed: { text: 'Closed', status: 'Success' },
+          },
+        },
+        {
+          title: 'Option',
+          valueType: 'option',
+          width: 200,
+          render: (text, record, _, action) => [
+            <a
+              key="editable"
+              onClick={() => {
+                action?.startEditable?.(record.id);
+              }}
+            >
+              Edit
+            </a>,
+            <a
+              key="delete"
+              onClick={() => {
+                setDataSource(
+                  dataSource.filter((item) => item.id !== record.id),
+                );
+              }}
+            >
+              Delete
+            </a>,
+          ],
+        },
+      ]}
+      value={dataSource}
+      onChange={setDataSource}
+      editable={{
+        type: 'multiple',
+        editableKeys,
+        onSave: async (rowKey, data, row) => {
+          console.log(rowKey, data, row);
+          await new Promise((resolve) => setTimeout(resolve, 2000));
+        },
+        onChange: setEditableRowKeys,
+      }}
+    />
+  );
+};
+```
+
+**Common Mistakes**:
+
+- Forgetting to provide a unique `rowKey`.
+- Not handling `editableKeys` properly in controlled mode.
+- Assuming `onSave` automatically updates the data source (you often need to update state manually or use `onChange` for local data).
+- Not configuring `recordCreatorProps` correctly for new rows.

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.