@vue-ui-kit/ant 1.7.3 → 1.8.0

package/README.md

@@ -108,17 +108,70 @@ export const setupKit = () => {
 
 ## Components
 
+### PGrid
+
+Enhanced data table component with integrated search form, pagination, and toolbar.
+
+#### Basic Example
+
+```vue
+<script setup lang="ts">
+import { computed } from 'vue';
+import { PGridProps, labelColDict } from '@vue-ui-kit/ant';
+
+const gridSetting = computed<PGridProps<Student, { keyword?: string }>>(() => ({
+  columns: [
+    { field: 'name', title: 'Name', width: 200 },
+    { field: 'email', title: 'Email', width: 200 },
+    { field: 'age', title: 'Age', width: 100 },
+  ],
+  formConfig: {
+    items: [
+      {
+        field: 'keyword',
+        title: 'Keyword',
+        labelCol: labelColDict[3],
+        itemRender: {
+          name: '$input',
+          props: { placeholder: 'Search...' },
+        },
+      },
+    ],
+  },
+  proxyConfig: {
+    ajax: {
+      query: ({ form, page }) => api.getStudents({ ...form, ...page }),
+    },
+  },
+}));
+</script>
+
+<template>
+  <p-grid v-bind="gridSetting" />
+</template>
+```
+
 ### PForm
 
 Enhanced Form component with simplified configuration and dynamic fields.
 
 #### Props
 
-| Prop        | Type               | Description                    |
-| ----------- | ------------------ | ------------------------------ |
-| items       | `PFormItemProps[]` | Form items configuration array |
-| customReset | `() => void`       | Custom reset function          |
-| others      | `FormProps`        | All ant-design-vue Form props  |
+| Prop | Type | Description | Default |
+| --- | --- | --- | --- |
+| items | `PFormItemProps[]` | Form items configuration array | - |
+| data | `T` | Form data object | - |
+| customReset | `() => void` | Custom reset function | - |
+| labelCol | `ColProps` | Label column layout | `{ span: 6 }` |
+| wrapperCol | `ColProps` | Wrapper column layout | `{ span: 16 }` |
+| ...others | `FormProps` | All ant-design-vue Form props | - |
+
+#### Events
+
+| Event | Description | Parameters |
+| --- | --- | --- |
+| apply | Triggered when form is submitted | `(formData: T) => void` |
+| reset | Triggered when form is reset | `() => void` |
 
 #### PFormItemProps
 
@@ -126,279 +179,405 @@ Enhanced Form component with simplified configuration and dynamic fields.
 | --- | --- | --- | --- |
 | field | `string` | Form field name | - |
 | title | `string` | Field label | - |
-| span | `number` | Grid span | - |
-| colon | `boolean` | Show colon | true |
-| forceRequired | `boolean` | Show required mark (without validation) | false |
-| align | `'left' \| 'right' \| 'center'` | Text alignment | 'left' |
+| span | `number` | Grid span (1-24) | - |
+| colon | `boolean` | Show colon after label | `true` |
+| labelCol | `ColProps` | Label column layout | - |
+| wrapperCol | `ColProps` | Wrapper column layout | - |
+| forceRequired | `boolean` | Show required mark (visual only) | `false` |
+| align | `'left' \| 'right' \| 'center'` | Text alignment | `'left'` |
 | col | `ColProps` | Grid column properties | - |
 | rule | `Rule[]` | Validation rules | - |
+| itemRender | `ItemRender` | Field renderer configuration | - |
 | tooltipConfig | `TooltipConfig` | Tooltip configuration | - |
+| slots | `object` | Custom slot renderers | - |
+
+#### Built-in Renderers
+
+- `$input`: Input field
+- `$textarea`: Textarea field  
+- `$number`: Number input
+- `$select`: Select dropdown
+- `$date`: Date picker
+- `$range`: Date range picker
+- `$time`: Time picker
+- `ASwitch`: Switch component
+- `ACheckbox`: Checkbox
+- `ARate`: Rate component
+- `ASlider`: Slider component
 
-#### Example
+#### Basic Example
 
 ```vue
-<script setup lang="tsx">
-  import { computed, ref } from 'vue';
-  import { TextAdAccount } from '...somewhere';
-  import { PFormProps } from '@vue-ui-kit/ant';
-
-  const createFormData = ref<TextAdAccount>({
-    account_code: '',
-    key_id: '',
-    org_id: '',
-    secret_key: '',
-  });
-  const createFormSetting = computed<PFormProps<TestAdAccount>>(() => ({
-    rules: {
-      account_code: [{ required: true, message: 'Please select Test account', trigger: 'change' }],
-      org_id: [
-        { required: true, message: 'Please select authorization organization', trigger: 'change' },
-      ],
-      secret_key: [{ required: true, message: 'Please enter Secret Key', trigger: 'change' }],
-      key_id: [{ required: true, message: 'Please enter Key ID', trigger: 'change' }],
-    },
-    items: [
-      {
-        title: 'Channel',
-        span: 24,
-        itemRender: {
-          name: 'readonly',
-          props: {
-            getText: () => 'Test',
-          },
-        },
-      },
-      {
-        field: 'account_code',
-        title: 'Account',
-        span: 24,
-        itemRender: {
-          name: '$select',
-          props: {
-            options: [
-              { label: 'Test Account 1', value: '1' },
-              { label: 'Test Account 2', value: '2' },
-            ],
-          },
-          events: {
-            change: ({ data }) => {
-              data.org_id = '';
-            },
-          },
-        },
-        tooltipConfig: {
-          title: 'Account refers to the email used to log in to the Test backend',
-        },
+<script setup lang="ts">
+import { ref, computed } from 'vue';
+import { PFormProps } from '@vue-ui-kit/ant';
+
+interface UserForm {
+  name: string;
+  email: string;
+  age?: number;
+  gender: string;
+  skills: string[];
+}
+
+const formData = ref<UserForm>({
+  name: '',
+  email: '',
+  age: undefined,
+  gender: '',
+  skills: [],
+});
+
+const formSetting = computed<PFormProps<UserForm>>(() => ({
+  items: [
+    {
+      field: 'name',
+      title: 'Name',
+      span: 12,
+      rule: [{ required: true, message: 'Please enter name' }],
+      itemRender: {
+        name: '$input',
+        props: { placeholder: 'Enter name' },
       },
-      {
-        field: 'org_id',
-        title: 'Authorization Org',
-        span: 24,
-        slots: {
-          default: ({ data }) => <my-custom-input v-model={data.org_id}></my-custom-input>,
-        },
-        tooltipConfig: {
-          title: 'Organization name, ID, and Core ID under the corresponding account',
-        },
+    },
+    {
+      field: 'email',
+      title: 'Email',
+      span: 12,
+      rule: [
+        { required: true, message: 'Please enter email' },
+        { type: 'email', message: 'Invalid email format' },
+      ],
+      itemRender: {
+        name: '$input',
+        props: { placeholder: 'Enter email' },
       },
-      {
-        field: 'secret_key',
-        title: 'Secret Key',
-        span: 24,
-        itemRender: {
-          name: '$input',
-        },
-        tooltipConfig: {
-          title: 'I am a tooltip',
+    },
+    {
+      field: 'gender',
+      title: 'Gender',
+      span: 12,
+      rule: [{ required: true, message: 'Please select gender' }],
+      itemRender: {
+        name: '$select',
+        props: {
+          placeholder: 'Select gender',
+          options: [
+            { label: 'Male', value: 'male' },
+            { label: 'Female', value: 'female' },
+          ],
         },
       },
-      {
-        field: 'key_id',
-        title: 'Key ID',
-        span: 24,
-        itemRender: {
-          name: '$input',
-        },
-        tooltipConfig: {
-          title: 'I am a tooltip',
+    },
+    {
+      field: 'skills',
+      title: 'Skills',
+      span: 24,
+      itemRender: {
+        name: '$select',
+        props: {
+          mode: 'multiple',
+          placeholder: 'Select skills',
+          options: [
+            { label: 'Vue.js', value: 'vue' },
+            { label: 'React', value: 'react' },
+            { label: 'Angular', value: 'angular' },
+          ],
         },
       },
-    ],
-  }));
+    },
+  ],
+}));
+
+const handleSubmit = (data: UserForm) => {
+  console.log('Form submitted:', data);
+};
 </script>
+
 <template>
-  <p-form ref="cf" :data="createFormData" v-bind="createFormSetting" />
+  <p-form 
+    v-bind="formSetting" 
+    :data="formData"
+    @apply="handleSubmit"
+  />
 </template>
 ```
 
-### PGrid
+#### Advanced Example with Custom Slots
+
+```vue
+<script setup lang="tsx">
+import { ref, computed } from 'vue';
+
+const formData = ref({
+  name: '',
+  isActive: false,
+});
+
+const formSetting = computed(() => ({
+  items: [
+    {
+      field: 'isActive',
+      title: 'Status',
+      span: 24,
+      slots: {
+        default: ({ data }) => (
+          <a-switch
+            v-model:checked={data.isActive}
+            checkedChildren="Active"
+            unCheckedChildren="Inactive"
+          />
+        ),
+      },
+    },
+  ],
+}));
+</script>
+```
+
+### PFormGroup
 
-Advanced grid component with built-in data management and toolbar functionality.
+Dynamic form group component for managing multiple form instances with add/remove capabilities.
 
 #### Props
 
-| Prop          | Type                 | Description                   | Default |
-| ------------- | -------------------- | ----------------------------- | ------- |
-| rowKey        | `string`             | Unique identifier field       | 'id'    |
-| columns       | `ColumnProps[]`      | Table columns configuration   | -       |
-| formConfig    | `PFormProps`         | Search form configuration     | -       |
-| toolbarConfig | `ToolbarConfig`      | Toolbar buttons configuration | -       |
-| pageConfig    | `PageConfig`         | Pagination configuration      | -       |
-| proxyConfig   | `ProxyConfig`        | Data fetching configuration   | -       |
-| selectConfig  | `SelectConfig`       | Row selection configuration   | -       |
-| scrollMode    | `'outer' \| 'inner'` | Scroll mode                   | 'outer' |
-| fitHeight     | `number`             | Auto-fit height adjustment    | -       |
+| Prop | Type | Description | Default |
+| --- | --- | --- | --- |
+| v-model | `Array<T & { __index: number }>` | Form group data array | `[]` |
+| getFormSetting | `(data: T) => PFormProps<T>` | Function to get form configuration | - |
+| title | `string` | Group title | - |
+| tabLabel | `string` | Custom tab label template | - |
+| editAble | `boolean` | Whether tabs are editable | `true` |
+| showAdd | `boolean` | Show add button | `true` |
+| lazyErrorMark | `boolean` | Lazy error marking | `false` |
+| forceRender | `boolean` | Force render all tabs | `false` |
+| keepSerial | `boolean` | Keep serial indexing | `false` |
+| loading | `boolean` | Loading state | `false` |
+| max | `number` | Maximum number of items | `Infinity` |
+| itemMenus | `GroupMenuItem[]` | Custom menu items | Default copy/delete |
+| createItem | `(opts: { list: T[] }) => Promise<T>` | Custom item creator | - |
+| menuHandler | `GroupMenuItemHandler<T>` | Custom menu handler | - |
+
+#### Exposed Methods
+
+| Method | Description | Parameters | Returns |
+| --- | --- | --- | --- |
+| validateAll | Validate all form instances | - | `Promise<void>` |
+| validate | Validate specific form instance | `__index: number` | `Promise<void>` |
+| setActiveKey | Set active tab | `key: number` | `void` |
 
-#### Example
+#### Basic Example
 
 ```vue
 <script setup lang="ts">
-  import { ColumnProps, getButtonResponsive, labelColDict, PGridProps } from '@vue-ui-kit/ant';
-  import { computed } from 'vue';
-  import { hasAuth } from '...somewhere';
-  import { getChannelPage, deleteChannel, deleteChannels } from '...somewhere';
-  import type { Channel, ChannelParam } from '...somewhere';
-
-  const gridSetting = computed<PGridProps<Channel, ChannelParam>>(() => ({
-    selectConfig: {
-      multiple: true,
-    },
-    toolbarConfig: {
-      buttons: [
-        {
-          code: 'multiDelete',
-          content: t('批量删除'),
-          type: 'danger',
-        },
-      ],
-    },
-    columns: [
-      {
-        field: 'id',
-        title: 'ID',
-        width: 110,
-      },
+import { ref, computed } from 'vue';
+import { PFormGroupProps } from '@vue-ui-kit/ant';
+
+interface Project {
+  __index: number;
+  name: string;
+  startDate: string;
+  endDate: string;
+  budget?: number;
+}
+
+const projects = ref<Project[]>([
+  {
+    __index: 0,
+    name: 'Project A',
+    startDate: '',
+    endDate: '',
+    budget: undefined,
+  }
+]);
+
+const groupSetting = computed<PFormGroupProps<Project>>(() => ({
+  title: 'Project Management',
+  showAdd: true,
+  max: 10,
+  getFormSetting: (data) => ({
+    items: [
       {
         field: 'name',
-        title: 'Channel Name',
-        width: 140,
+        title: 'Project Name',
+        span: 24,
+        rule: [{ required: true, message: 'Please enter project name' }],
+        itemRender: {
+          name: '$input',
+          props: { placeholder: 'Enter project name' },
+        },
       },
       {
-        field: 'short_name',
-        title: 'Short Name',
-        width: 140,
+        field: 'startDate',
+        title: 'Start Date',
+        span: 12,
+        rule: [{ required: true, message: 'Please select start date' }],
+        itemRender: {
+          name: '$date',
+          props: { placeholder: 'Select start date' },
+        },
       },
       {
-        field: 'operator',
-        title: 'Operator',
-        width: 120,
+        field: 'endDate',
+        title: 'End Date',
+        span: 12,
+        rule: [{ required: true, message: 'Please select end date' }],
+        itemRender: {
+          name: '$date',
+          props: { placeholder: 'Select end date' },
+        },
       },
       {
-        field: 'update_time',
-        title: 'Last Modified',
-        width: 180,
-      },
-      ...(hasAuth('common_channel_admin')
-        ? ([
-            {
-              title: 'Actions',
-              fixed: 'right',
-              width: 160,
-              cellRender: {
-                name: 'ButtonTree',
-                children: [
-                  {
-                    content: 'Edit',
-                    type: 'link',
-                    clickEvt: ({ row }: { row: Channel }) => doEdit(row),
-                  },
-                  {
-                    content: 'Delete',
-                    type: 'link',
-                    danger: true,
-                    clickEvt: ({ row }: { row: Channel }) => confirmDelete(row),
-                  },
-                ],
-              },
-            },
-          ] as ColumnProps<Channel>[])
-        : []),
-    ],
-    formConfig: {
-      items: [
-        {
-          field: 'name',
-          title: 'Channel Name',
-          labelCol: labelColDict[4],
-          itemRender: {
-            name: '$input',
-            props: {
-              placeholder: 'Please enter channel name',
-            },
-          },
-        },
-        {
-          col: getButtonResponsive(1),
-          align: 'right',
-          itemRender: {
-            name: '$buttons',
-            children: [
-              {
-                props: {
-                  content: 'Search',
-                  htmlType: 'submit',
-                  type: 'primary',
-                },
-              },
-              {
-                props: {
-                  content: 'Reset',
-                  htmlType: 'reset',
-                },
-              },
-            ],
+        field: 'budget',
+        title: 'Budget',
+        span: 24,
+        itemRender: {
+          name: '$number',
+          props: {
+            min: 0,
+            placeholder: 'Enter budget',
+            formatter: (value) => `$ ${value}`.replace(/\B(?=(\d{3})+(?!\d))/g, ','),
+            parser: (value) => value.replace(/\$\s?|(,*)/g, ''),
           },
         },
-      ],
-    },
-    pageConfig: {
-      pageSize: 10,
-    },
-    proxyConfig: {
-      response: {
-        total: 'total',
-        result: 'list',
-      },
-      ajax: {
-        query: ({ form, page }) =>
-          getChannelPage({
-            ...form,
-            ...page,
-          } as ChannelParam),
-        multiDelete: deleteChannels,
       },
-    },
-  }));
+    ],
+  }),
+}));
+
+const handleSave = async () => {
+  try {
+    await groupRef.value?.validateAll();
+    console.log('All projects saved:', projects.value);
+  } catch (error) {
+    console.error('Validation failed:', error);
+  }
+};
+
+const groupRef = ref();
 </script>
+
 <template>
-  <p-grid ref="gridEl" v-bind="gridSetting" />
+  <div>
+    <p-form-group 
+      ref="groupRef"
+      v-model="projects"
+      v-bind="groupSetting"
+    />
+    <a-button type="primary" @click="handleSave">
+      Save All Projects
+    </a-button>
+  </div>
 </template>
 ```
 
-### PFormGroup
+#### Advanced Example with Custom Menu
+
+```vue
+<script setup lang="ts">
+import { ref, computed } from 'vue';
+
+const projects = ref([]);
+
+const groupSetting = computed(() => ({
+  title: 'Advanced Project Management',
+  itemMenus: [
+    { content: 'Copy', code: 'copy' },
+    { content: 'Delete', code: 'delete' },
+    { content: 'Export', code: 'export' },
+    { 
+      content: 'Archive', 
+      code: 'archive',
+      visibleMethod: ({ data }) => data.status !== 'archived'
+    },
+  ],
+  createItem: async ({ list }) => {
+    return {
+      name: `Project ${list.length + 1}`,
+      status: 'active',
+      startDate: new Date().toISOString().split('T')[0],
+    };
+  },
+  menuHandler: ({ code, data, index }) => {
+    switch (code) {
+      case 'export':
+        exportProject(data);
+        break;
+      case 'archive':
+        archiveProject(data, index);
+        break;
+    }
+  },
+  getFormSetting: (data) => ({
+    // ... form configuration
+  }),
+}));
+</script>
+```
 
-Form group component for organizing form fields into collapsible sections.
+## Utility Functions
 
-#### Props
+### labelColDict
+
+Pre-defined label column configurations for different text lengths:
+
+```ts
+import { labelColDict } from '@vue-ui-kit/ant';
+
+// Usage in form items
+{
+  field: 'shortField',
+  title: 'Name', // 2 characters
+  labelCol: labelColDict[2],
+}
+
+{
+  field: 'longerField', 
+  title: 'Description', // 4+ characters
+  labelCol: labelColDict[4],
+}
+```
 
-| Prop           | Type                   | Description                   |
-| -------------- | ---------------------- | ----------------------------- |
-| getFormSetting | `(data) => PFormProps` | Function to get form settings |
-| source         | `object`               | Form data source              |
+### Custom Renderers
 
-## Q&A
+Register custom form field renderers:
 
-### 1. When using computed + v-bind to generate dynamic tables + forms, form option updates cause table re-rendering. How to solve this?
+```tsx
+import UIKit from '@vue-ui-kit/ant';
+import { Switch } from 'ant-design-vue';
+
+UIKit.addRender('$switch', {
+  renderItemContent(
+    { props = {}, events = {} },
+    { data, field }
+  ) {
+    return (
+      <Switch
+        v-model:checked={data[field]}
+        {...props}
+        onChange={(...args) => {
+          events.change?.({ data, field }, ...args);
+        }}
+      />
+    );
+  },
+});
+```
+
+### Custom Formatters
+
+Register custom cell formatters for PGrid:
+
+```ts
+UIKit.addFormatter({
+  currency: ({ cellValue }) => `$${cellValue?.toLocaleString() || '0'}`,
+  percentage: ({ cellValue }) => `${(cellValue * 100).toFixed(2)}%`,
+});
+```
+
+## FAQ
+
+### 1. When using computed + v-bind to generate dynamic tables + forms, form option updates cause table re-rendering. How to solve?
 
 Answer: Separate the formConfig into another computed property
 
@@ -423,4 +602,22 @@ toolbarConfig: {
 
 ### 3. Why is the computed approach recommended?
 
-Answer: It simplifies all dynamic logic, that's all. For complex scenarios, you can try using reactive and maintain it yourself, but in most cases, computed is more convenient.
+Answer: It simplifies all dynamic logic. For complex scenarios, you can try using reactive and maintain it yourself, but in most cases, computed is more convenient.
+
+## TypeScript Support
+
+This library is fully written in TypeScript and provides comprehensive type definitions:
+
+```ts
+import type { 
+  PFormProps, 
+  PFormItemProps,
+  PFormGroupProps,
+  PGridProps,
+  ColumnProps 
+} from '@vue-ui-kit/ant';
+```
+
+## License
+
+MIT