@jswork/antd-form-schema 0.0.0-stage → 1.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +196 -2
- package/dist/index.cjs +979 -0
- package/dist/index.cjs.map +1 -0
- package/dist/index.d.mts +284 -0
- package/dist/index.d.ts +286 -0
- package/dist/index.mjs +938 -0
- package/dist/index.mjs.map +1 -0
- package/dist/style.css +0 -0
- package/package.json +63 -4
package/README.md
CHANGED
|
@@ -1,3 +1,197 @@
|
|
|
1
|
-
#
|
|
1
|
+
# antd-form-schema
|
|
2
|
+
> A tiny headless schema renderer for Ant Design form fields and rules.
|
|
2
3
|
|
|
3
|
-
|
|
4
|
+
## installation
|
|
5
|
+
```shell
|
|
6
|
+
pnpm add @jswork/antd-form-schema antd
|
|
7
|
+
```
|
|
8
|
+
`antd`, `react`, `react-dom` and `classnames` are peer dependencies.
|
|
9
|
+
|
|
10
|
+
The schema describes only **what a field is** (widget id, data, text, validation, conditions) — never **how it looks**. No layout, grid or style keys exist in the schema.
|
|
11
|
+
|
|
12
|
+
## headless usage (`useFormSchema`)
|
|
13
|
+
```tsx
|
|
14
|
+
import { Button, Form } from 'antd';
|
|
15
|
+
import { useFormSchema } from '@jswork/antd-form-schema';
|
|
16
|
+
import type { FormSchema } from '@jswork/antd-form-schema';
|
|
17
|
+
|
|
18
|
+
const meta: FormSchema = {
|
|
19
|
+
fields: [
|
|
20
|
+
{ key: 'name', label: 'Name', widget: 'input', required: true },
|
|
21
|
+
{ key: 'role', label: 'Role', widget: 'select', options: ['admin', 'user'] },
|
|
22
|
+
{
|
|
23
|
+
key: 'company', label: 'Company', widget: 'input',
|
|
24
|
+
condition: { field: 'role', op: 'eq', value: 'admin' },
|
|
25
|
+
},
|
|
26
|
+
],
|
|
27
|
+
};
|
|
28
|
+
|
|
29
|
+
function UserForm() {
|
|
30
|
+
const [form] = Form.useForm();
|
|
31
|
+
const { visibleFields } = useFormSchema(meta, form);
|
|
32
|
+
return (
|
|
33
|
+
<Form form={form} initialValues={{ role: 'user' }} onFinish={console.log} layout="vertical">
|
|
34
|
+
<div className="grid grid-cols-1 md:grid-cols-2 gap-4">
|
|
35
|
+
{visibleFields.map((f) => (
|
|
36
|
+
<div key={f.key} className={f.widget === 'textarea' ? 'md:col-span-2' : ''}>
|
|
37
|
+
<Form.Item {...f.itemProps} label={f.label} required={f.required}>
|
|
38
|
+
{f.control}
|
|
39
|
+
</Form.Item>
|
|
40
|
+
</div>
|
|
41
|
+
))}
|
|
42
|
+
</div>
|
|
43
|
+
<Button htmlType="submit" type="primary">Submit</Button>
|
|
44
|
+
</Form>
|
|
45
|
+
);
|
|
46
|
+
}
|
|
47
|
+
```
|
|
48
|
+
`itemProps` contains only data-binding keys (`name`, `rules`, `valuePropName`, `dependencies`, `shouldUpdate`); it deliberately has no `label`/`className`/`style`. Pass `label` to `Form.Item` yourself for accessible labels — layout remains in your JSX.
|
|
49
|
+
|
|
50
|
+
## convenience renderer (`FormFields`)
|
|
51
|
+
For simple cases, `FormFields` is a thin vertical wrapper around `Form.Item` and `f.control`:
|
|
52
|
+
|
|
53
|
+
```tsx
|
|
54
|
+
import { Form } from 'antd';
|
|
55
|
+
import { FormFields, useFormSchema } from '@jswork/antd-form-schema';
|
|
56
|
+
|
|
57
|
+
function SimpleForm() {
|
|
58
|
+
const [form] = Form.useForm();
|
|
59
|
+
const { visibleFields } = useFormSchema(meta, form);
|
|
60
|
+
return (
|
|
61
|
+
<Form form={form}>
|
|
62
|
+
<FormFields fields={visibleFields} className="space-y-4" />
|
|
63
|
+
</Form>
|
|
64
|
+
);
|
|
65
|
+
}
|
|
66
|
+
```
|
|
67
|
+
`FormFields` has **no** `columns`/`gutter` or any other layout props — use custom JSX when you need layout.
|
|
68
|
+
|
|
69
|
+
## quick start (`SchemaForm` / `SchemaFields`)
|
|
70
|
+
|
|
71
|
+
For common forms, skip the JSX boilerplate. `SchemaForm` creates the Form for you — pass a meta and you are done:
|
|
72
|
+
|
|
73
|
+
```tsx
|
|
74
|
+
import { SchemaForm } from '@jswork/antd-form-schema';
|
|
75
|
+
import type { FormClassNames } from '@jswork/antd-form-schema';
|
|
76
|
+
|
|
77
|
+
const classNames: FormClassNames = {
|
|
78
|
+
form: 'grid grid-cols-2 gap-4',
|
|
79
|
+
field: 'rounded border p-3',
|
|
80
|
+
label: 'mb-1 block text-sm font-medium',
|
|
81
|
+
control: 'w-full',
|
|
82
|
+
};
|
|
83
|
+
|
|
84
|
+
<SchemaForm meta={meta} onFinish={save} classNames={classNames}>
|
|
85
|
+
<Button htmlType="submit" type="primary">Submit</Button>
|
|
86
|
+
</SchemaForm>
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
Need to own the form (read/validate values, reset, etc.)? Use `SchemaFields` inside your own `<Form>`:
|
|
90
|
+
|
|
91
|
+
```tsx
|
|
92
|
+
import { Button, Form } from 'antd';
|
|
93
|
+
import { SchemaFields } from '@jswork/antd-form-schema';
|
|
94
|
+
|
|
95
|
+
const [form] = Form.useForm();
|
|
96
|
+
<Form form={form} onFinish={save}>
|
|
97
|
+
<div className="grid grid-cols-2 gap-4">
|
|
98
|
+
<SchemaFields meta={meta} classNames={{ field: 'rounded border p-3' }} />
|
|
99
|
+
</div>
|
|
100
|
+
<Button htmlType="submit">Submit</Button>
|
|
101
|
+
</Form>
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
- Layout is controlled by one `classNames` object (keys mirror the parts: `form` / `field` / `label` / `control`) — Tailwind classes, never schema keys. `classNames.form` applies only to `SchemaForm`; on `SchemaFields` it is ignored with a dev warning.
|
|
105
|
+
- Initial values come **only** from `meta.initialValues`.
|
|
106
|
+
- Date fields store dayjs objects by default; declare `valueType: 'string' | 'number' | 'timestamp'` on a date field (optional `valueFormat`, default `YYYY-MM-DD`, string type only) to store plain values instead. Conversion wraps the form store — antd React's DatePicker has no native `valueFormat`.
|
|
107
|
+
- `meta` may be a `Promise<FormSchema>` — components render a loading placeholder until it resolves (`loading`/`error` props customize the placeholders). Fields mount only after resolve, so late `initialValues` apply correctly.
|
|
108
|
+
- `normalizeValues` (on `meta` or as a `SchemaForm` prop) transforms the whole values object right before `onFinish` — for cross-field cleanup the schema cannot express.
|
|
109
|
+
- `label`, required mark and validation errors are rendered by antd `Form.Item` itself (so clicking a label focuses its control; error messages use antd styles).
|
|
110
|
+
- For extreme customization, drop down to `useFormSchema` and write your own JSX.
|
|
111
|
+
|
|
112
|
+
> **Breaking change:** the default export is now an alias of `FormFields` (previously an empty scaffold `div` component). Named exports are the primary API.
|
|
113
|
+
|
|
114
|
+
## key presets (label + widget)
|
|
115
|
+
|
|
116
|
+
Define each key's standard shape once — its label (locale-aware) and its widget — then keep schemas to bare keys. Anything you still write on a field always wins.
|
|
117
|
+
|
|
118
|
+
```yaml
|
|
119
|
+
# presets.yaml
|
|
120
|
+
fields:
|
|
121
|
+
title: input
|
|
122
|
+
status: select
|
|
123
|
+
labels:
|
|
124
|
+
zh-CN:
|
|
125
|
+
title: 标题
|
|
126
|
+
status: 状态
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
```tsx
|
|
130
|
+
import presets from './presets.yaml'; // e.g. Vite + @rollup/plugin-yaml
|
|
131
|
+
<SchemaForm meta={{ fields: [{ key: 'title' }, { key: 'status' }] }} presets={presets} />;
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
- Priority — widget: `schema.widget` > `presets.fields[key]` > `input`. Label: `schema.label` > `presets.labels[locale][key]` > `presets.labels['zh-CN'][key]` > builtin dictionary > **the key itself**.
|
|
135
|
+
- `locale` defaults to `zh-CN`; a missing language or a missing key silently falls back — no warnings, no errors.
|
|
136
|
+
- A flat single-language table is also accepted: `presets={{ title: '标题', name: '姓名' }}`.
|
|
137
|
+
- Presets never create fields: entries whose key is absent from `meta.fields` are ignored.
|
|
138
|
+
- Only `widget` and `label` are taken from presets; options, placeholder and rules stay in the schema.
|
|
139
|
+
|
|
140
|
+
## slots
|
|
141
|
+
|
|
142
|
+
`SchemaForm` and `SchemaFields` render each field with three replaceable parts (`slots` is a component prop, never a schema key). The `<label htmlFor>`, required mark and error text are always owned by antd `Form.Item`:
|
|
143
|
+
|
|
144
|
+
- `label` — overrides the **label content** (antd still wraps it in `<label>` and adds the required mark)
|
|
145
|
+
- `control` — overrides the `Form.Item` children (the value-bound control)
|
|
146
|
+
- `field` — overrides the wrapper around the whole `Form.Item`
|
|
147
|
+
|
|
148
|
+
Every slot accepts three shapes: a component, a ReactNode, or `{ component, props }`. Runtime context (`field`, and the part's own props) is passed to the component; a ReactNode is rendered as-is. For `control` and `field` use the component shape — a static ReactNode cannot host a live input.
|
|
149
|
+
|
|
150
|
+
```tsx
|
|
151
|
+
import { SchemaForm } from '@jswork/antd-form-schema';
|
|
152
|
+
import type { FormSlots } from '@jswork/antd-form-schema';
|
|
153
|
+
|
|
154
|
+
const slots: FormSlots = {
|
|
155
|
+
label: ({ field }) => <abbr title={String(field.label)}>{String(field.label)}</abbr>,
|
|
156
|
+
control: ({ control, field }) => (
|
|
157
|
+
<div className="flex items-center gap-2">
|
|
158
|
+
<div className="flex-1">{control}</div>
|
|
159
|
+
{field.key === 'age' && <span>岁</span>}
|
|
160
|
+
</div>
|
|
161
|
+
),
|
|
162
|
+
};
|
|
163
|
+
|
|
164
|
+
<SchemaForm meta={meta} slots={slots} />;
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
Only replace the parts you need — any slot you omit falls back to the default (`Form.Item`-based) rendering. Custom slots own their markup and classes; the four `className` props still style only the default renderers.
|
|
168
|
+
|
|
169
|
+
## widget override & conditions
|
|
170
|
+
Pass a `widgets` map to `useFormSchema` to register or override widget ids. A widget is a string id or a component escape hatch:
|
|
171
|
+
|
|
172
|
+
```tsx
|
|
173
|
+
import Rate from 'antd/es/rate';
|
|
174
|
+
import type { WidgetDef } from '@jswork/antd-form-schema';
|
|
175
|
+
|
|
176
|
+
const widgets: Record<string, WidgetDef> = {
|
|
177
|
+
rate: { component: Rate },
|
|
178
|
+
};
|
|
179
|
+
const { visibleFields } = useFormSchema(
|
|
180
|
+
{ fields: [{ key: 'rating', label: 'Rating', widget: 'rate' }] },
|
|
181
|
+
form,
|
|
182
|
+
{ widgets },
|
|
183
|
+
);
|
|
184
|
+
```
|
|
185
|
+
Conditions can be declarative or a function with auto watch paths:
|
|
186
|
+
|
|
187
|
+
```tsx
|
|
188
|
+
{ key: 'company', condition: { field: 'role', op: 'eq', value: 'admin' } }
|
|
189
|
+
{ key: 'info', watch: ['role'], condition: ({ values }) => values.role === 'admin' }
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
## exports
|
|
193
|
+
Named: `useFormSchema`, `FormFields`, `SchemaFields`, `SchemaForm`, `validateMeta`, `normalizeMeta`, `evaluateCondition`, `collectWatchPaths`, type `FormSlots` and all types from `types.ts` (including `Presets`, `PresetsInput`, `PresetField`).
|
|
194
|
+
Default: `AntdFormSchema` = `FormFields` (with `version`), kept for scaffold compatibility.
|
|
195
|
+
|
|
196
|
+
## license
|
|
197
|
+
Code released under the MIT license.
|