Skip to content

Commit 0000633

Browse files
Copilotyomybaby
Copilot
and
yomybaby
committed
docs(FR-1966): Add comprehensive documentation for BulkEditFormItem
Co-authored-by: yomybaby <621215+yomybaby@users.noreply.github.com>
1 parent 2ab2eed commit 0000633

1 file changed

Lines changed: 177 additions & 0 deletions

File tree

‎react/src/components/BulkEditFormItem.md‎

Lines changed: 177 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,177 @@
1+
# BulkEditFormItem Component
2+
3+
## Overview
4+
5+
`BulkEditFormItem` is a custom Form.Item component designed for bulk editing scenarios in the Backend.AI WebUI. It provides a user-friendly interface for handling bulk updates with three distinct modes:
6+
7+
1. **Keep as is** (default): Maintains current values without changes
8+
2. **Edit**: Allows modification of the field value
9+
3. **Clear**: Unsets the value for all items (only available for optional fields)
10+
11+
## Features
12+
13+
- ✅ Three distinct editing modes with clear user feedback
14+
- ✅ Optional field support with Clear button
15+
- ✅ Undo changes functionality to revert to "Keep as is" state
16+
- ✅ Proper TypeScript types and documentation
17+
- ✅ Internationalization support (21 languages)
18+
- ✅ React Compiler optimization with `'use memo'` directive
19+
- ✅ Comprehensive unit tests
20+
- ✅ Detailed Storybook stories
21+
22+
## Usage
23+
24+
### Basic Example
25+
26+
```tsx
27+
import BulkEditFormItem from './components/BulkEditFormItem';
28+
import { Form, Input } from 'antd';
29+
30+
<Form>
31+
<BulkEditFormItem name="username" label="Username">
32+
<Input placeholder="Enter username" />
33+
</BulkEditFormItem>
34+
</Form>
35+
```
36+
37+
### Optional Field Example
38+
39+
```tsx
40+
<BulkEditFormItem name="domain_name" label="Domain" optional>
41+
<BAISelect
42+
options={[
43+
{ value: 'default', label: 'Default' },
44+
{ value: 'custom', label: 'Custom' },
45+
]}
46+
/>
47+
</BulkEditFormItem>
48+
```
49+
50+
### Multiple Fields Example
51+
52+
```tsx
53+
<Form>
54+
<BulkEditFormItem name="domain" label="Domain" optional>
55+
<BAISelect options={domainOptions} />
56+
</BulkEditFormItem>
57+
58+
<BulkEditFormItem name="status" label="Status">
59+
<BAISelect options={statusOptions} />
60+
</BulkEditFormItem>
61+
62+
<BulkEditFormItem name="notes" label="Notes" optional>
63+
<Input.TextArea rows={3} />
64+
</BulkEditFormItem>
65+
</Form>
66+
```
67+
68+
## Props
69+
70+
| Name | Type | Default | Description |
71+
|------|------|---------|-------------|
72+
| `optional` | `boolean` | `false` | Whether this field can be cleared (shows Clear button in "Keep as is" mode) |
73+
| `children` | `ReactElement` | - | Input component to render (typically Select, Input, InputNumber, etc.) |
74+
| `...formItemProps` | `FormItemProps` | - | All Ant Design Form.Item props (name, label, rules, tooltip, etc.) |
75+
76+
## Modes
77+
78+
### Keep as is (Default)
79+
80+
- Input is disabled
81+
- Field value is set to `undefined` (not included in form submission)
82+
- Shows "Keep as is" text
83+
- Displays Edit and Clear (if optional) buttons
84+
85+
### Edit Mode
86+
87+
- Input is enabled
88+
- User can modify the field value
89+
- Shows "Undo changes" button to revert to "Keep as is"
90+
91+
### Clear Mode
92+
93+
- Only available for optional fields
94+
- Field value is set to `null` (explicitly clears the value)
95+
- Shows "Undo changes" button to revert to "Keep as is"
96+
97+
## Implementation Details
98+
99+
### State Management
100+
101+
The component uses React's `useState` to manage the current mode:
102+
103+
```typescript
104+
type BulkEditMode = 'keep' | 'edit' | 'clear';
105+
const [mode, setMode] = useState<BulkEditMode>('keep');
106+
```
107+
108+
### Form Integration
109+
110+
- Uses Ant Design's `Form.useFormInstance()` to access form methods
111+
- Automatically resets to "Keep as is" when form is reset
112+
- Properly handles field value updates
113+
114+
### Children Props
115+
116+
The component clones the children element and adds/overrides props:
117+
118+
- In "Keep as is" mode: `disabled: true`, `value: undefined`
119+
- In other modes: children render with their original props
120+
121+
## Testing
122+
123+
### Unit Tests
124+
125+
Run unit tests with:
126+
127+
```bash
128+
pnpm test BulkEditFormItem.test.tsx
129+
```
130+
131+
The test suite covers:
132+
- Default rendering in "keep" mode
133+
- Clear button visibility for optional fields
134+
- Mode switching (Edit, Clear, Undo)
135+
- Input disable/enable behavior
136+
137+
### Storybook
138+
139+
View the component in Storybook:
140+
141+
```bash
142+
cd packages/backend.ai-ui
143+
pnpm run storybook
144+
```
145+
146+
Navigate to: **Components > BulkEditFormItem**
147+
148+
## Internationalization
149+
150+
The component uses the following i18n keys:
151+
152+
| Key | English | Korean | Japanese | Chinese (Simplified) |
153+
|-----|---------|--------|----------|---------------------|
154+
| `bulkEdit.Clear` | Clear | 지우기 | クリア | 清除 |
155+
| `bulkEdit.Edit` | Edit | 편집 | 編集 | 编辑 |
156+
| `bulkEdit.KeepAsIs` | Keep as is | 그대로 유지 | そのまま維持 | 保持原样 |
157+
| `bulkEdit.UndoChanges` | Undo changes | 변경 취소 | 変更を元に戻す | 撤销更改 |
158+
159+
Translations are available for all 21 supported languages.
160+
161+
## Related Files
162+
163+
- **Component**: `/react/src/components/BulkEditFormItem.tsx`
164+
- **Tests**: `/react/src/components/BulkEditFormItem.test.tsx`
165+
- **Stories**: `/react/src/components/BulkEditFormItem.stories.tsx`
166+
- **Usage Example**: `/react/src/components/UpdateUsersModal.tsx`
167+
168+
## Related Issues
169+
170+
- **JIRA**: FR-1966
171+
- **GitHub Issue**: Custom Form.Item for bulk editing
172+
173+
## Notes
174+
175+
- The component is optimized with React Compiler's `'use memo'` directive
176+
- It follows the existing patterns from `FormItemControl.tsx` and `FormItemWithUnlimited.tsx`
177+
- The component was created to replace the TODO comment in `UpdateUsersModal.tsx`

0 commit comments

Comments
 (0)