@shikiform/react 0.0.0-stage → 0.1.0
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 +8 -2
- package/dist/chunk-EYDJ6I7P.js +1024 -0
- package/dist/chunk-EYDJ6I7P.js.map +1 -0
- package/dist/index.d.ts +243 -0
- package/dist/index.js +150 -0
- package/dist/index.js.map +1 -0
- package/dist/internal.d.ts +27 -0
- package/dist/internal.js +3 -0
- package/dist/internal.js.map +1 -0
- package/dist/use-watch-BZlpyvHw.d.ts +1074 -0
- package/package.json +36 -4
|
@@ -0,0 +1,1074 @@
|
|
|
1
|
+
import * as react from 'react';
|
|
2
|
+
import { ComponentType, ReactNode, ComponentProps, DragEvent, FormHTMLAttributes, FunctionComponent, ComponentClass, ForwardRefExoticComponent, Ref } from 'react';
|
|
3
|
+
import { Display, Pattern, EnumOption, UiName, FieldEnum, RulesInput, FieldPath, PathValue, Pos, MoveResult, ArrayPath, FieldError, FormInstance, Draft, FormOptions, DefaultSubmit, FieldsInput, ResolveSubmit, ArrayItemOf, FormEngine, UiDisplay, FormMessageKey, MessageArgs } from '@shikiform/core/internal';
|
|
4
|
+
|
|
5
|
+
/**
|
|
6
|
+
* Register the controls your app passes to `<Field component="Input">` (module augmentation):
|
|
7
|
+
*
|
|
8
|
+
* ```ts
|
|
9
|
+
* declare module '@shikiform/react' { interface FieldComponents { Input: typeof Input; Select: typeof Select } }
|
|
10
|
+
* ```
|
|
11
|
+
*
|
|
12
|
+
* Without it any string is accepted. The runtime map is {@link FieldKit} / `<Form kit>`.
|
|
13
|
+
*/
|
|
14
|
+
interface FieldComponents {
|
|
15
|
+
}
|
|
16
|
+
/**
|
|
17
|
+
* Register the decorators your app passes to `<Field decorator="FormItem">`.
|
|
18
|
+
* Same rule as {@link FieldComponents}: an empty interface means any string.
|
|
19
|
+
*/
|
|
20
|
+
interface FieldDecorators {
|
|
21
|
+
}
|
|
22
|
+
/** A component, `[Component, props]`, or a name registered in `decorators`. */
|
|
23
|
+
type FieldKitDecorator = ComponentType<any> | readonly [ComponentType<any> | string, Record<string, any>?] | string;
|
|
24
|
+
/**
|
|
25
|
+
* One registration of controls and decorators. Pass it to `<FieldKit>` (several forms) or `<Form kit>` (this form).
|
|
26
|
+
* A field that omits `decorator` uses `decorator` here. `decorator={false}` on the field opts out.
|
|
27
|
+
* String `component` / `decorator` names look up `components` / `decorators`; a component reference does not need
|
|
28
|
+
* to be in the map — it still gets the default decorator.
|
|
29
|
+
*/
|
|
30
|
+
interface FieldKitSpec {
|
|
31
|
+
/** Name → control. `<Field component="Input" />` and `<Field component={["Input", props]} />`. */
|
|
32
|
+
components?: Record<string, ComponentType<any>>;
|
|
33
|
+
/** Name → decorator. `<Field decorator="FormItem" />`. */
|
|
34
|
+
decorators?: Record<string, ComponentType<any>>;
|
|
35
|
+
/** Used when a `<Field>` omits `decorator`. A string looks up `decorators`. */
|
|
36
|
+
decorator?: FieldKitDecorator;
|
|
37
|
+
}
|
|
38
|
+
/**
|
|
39
|
+
* Register controls and a default decorator for every `<Field>` inside.
|
|
40
|
+
* `<Form kit>` does the same for one form. Names are the `component` / `decorator` strings; the components you
|
|
41
|
+
* already `connect()`ed are passed by reference (`component={Input}` or `component={[Input, props]}`) and still
|
|
42
|
+
* pick up the default decorator. There is no second Field component.
|
|
43
|
+
*
|
|
44
|
+
* ```tsx
|
|
45
|
+
* <FieldKit components={{ Input, Select }} decorator={FormItem}>
|
|
46
|
+
* <Form form={form}>
|
|
47
|
+
* <Field name="email" title="邮箱" component="Input" />
|
|
48
|
+
* <Field name="city" component={[Select, { allowClear: true }]} />
|
|
49
|
+
* <Field name="qty" component={[InputNumber]} decorator={false} />
|
|
50
|
+
* </Form>
|
|
51
|
+
* </FieldKit>
|
|
52
|
+
* ```
|
|
53
|
+
*/
|
|
54
|
+
declare function FieldKit({ children, ...spec }: FieldKitSpec & {
|
|
55
|
+
children?: ReactNode;
|
|
56
|
+
}): react.JSX.Element;
|
|
57
|
+
|
|
58
|
+
/**
|
|
59
|
+
* What `useField` and `<Field>` hand to an input.
|
|
60
|
+
* The component re-renders only when this path's version changes, not when a sibling changes.
|
|
61
|
+
*/
|
|
62
|
+
interface FieldBinding<TValue> {
|
|
63
|
+
path: string;
|
|
64
|
+
value: TValue;
|
|
65
|
+
/**
|
|
66
|
+
* Method syntax is bivariant, so `FieldBinding<string>` can be passed to a helper typed as
|
|
67
|
+
* `FieldBinding<string | number>` or `FieldBinding<unknown>`. `value` stays covariant: a `string` binding is not a
|
|
68
|
+
* `number` binding. Calling `onChange` with a wider value is the same tradeoff React uses for event handlers.
|
|
69
|
+
*/
|
|
70
|
+
onChange(value: TValue): void;
|
|
71
|
+
onBlur(): void;
|
|
72
|
+
errors: string[];
|
|
73
|
+
warnings: string[];
|
|
74
|
+
display: Display;
|
|
75
|
+
pattern: Pattern;
|
|
76
|
+
required: boolean;
|
|
77
|
+
disabled: boolean;
|
|
78
|
+
readOnly: boolean;
|
|
79
|
+
/** True after blur. `reset` clears it. */
|
|
80
|
+
touched: boolean;
|
|
81
|
+
/** The value differs from its initial value (deep compare). Changing it back clears it. */
|
|
82
|
+
dirty: boolean;
|
|
83
|
+
/** Sticky: a user edit happened since the last reset. A reaction writing `$value` does not set it. */
|
|
84
|
+
edited: boolean;
|
|
85
|
+
/** True while an async rule or schema for this field is in flight. */
|
|
86
|
+
validating: boolean;
|
|
87
|
+
options: EnumOption[];
|
|
88
|
+
loading: boolean;
|
|
89
|
+
id: string;
|
|
90
|
+
/** Decorator label. Reaction `$title` > JSX `title` > `fields.x.title`. */
|
|
91
|
+
title: ReactNode;
|
|
92
|
+
/** Decorator help text. Reaction `$description` > JSX > `fields`. */
|
|
93
|
+
description: ReactNode;
|
|
94
|
+
/** The control `<Field>` renders (from the `component` slot). */
|
|
95
|
+
component: ComponentType<any> | undefined;
|
|
96
|
+
/** The wrapper `<Field>` renders (from the `decorator` slot). */
|
|
97
|
+
decorator: ComponentType<any> | undefined;
|
|
98
|
+
/** Props for the control: `fields` ← JSX ← reaction (`$componentProps`), deep-merged. */
|
|
99
|
+
componentProps: Record<string, any>;
|
|
100
|
+
/** Props for the decorator: `fields` ← JSX ← reaction (`$decoratorProps`), deep-merged. */
|
|
101
|
+
decoratorProps: Record<string, any>;
|
|
102
|
+
/**
|
|
103
|
+
* The UI instance name when this binding comes from `<Field name ui="echo">` / `useField(name, { ui })`: value,
|
|
104
|
+
* errors and `onChange` are the field's; display, pattern, title, props and `id` (`<prefix>-<path>--<ui>`) are the instance's.
|
|
105
|
+
*/
|
|
106
|
+
ui?: string;
|
|
107
|
+
}
|
|
108
|
+
/**
|
|
109
|
+
* A `component` / `decorator` slot: the component, or `[Component, props]` (Formily style). On `<Field>` / `typed().Field`
|
|
110
|
+
* / `row.Field` / `<UI>`, `C` is inferred from the component and the props are checked against it (all optional: the field
|
|
111
|
+
* supplies value / onChange); `[InputNumber, { min: 'zero' }]` does not compile.
|
|
112
|
+
*/
|
|
113
|
+
type FieldSlot<C extends ComponentType<any> = ComponentType<any>> = C | readonly [C] | readonly [C, SlotProps<C> | undefined];
|
|
114
|
+
/** The props half of a slot tuple: the component's own props, all optional, plus `data-*` attributes (as in JSX). */
|
|
115
|
+
type SlotProps<C extends ComponentType<any>> = Partial<ComponentProps<C>> & {
|
|
116
|
+
[key: `data-${string}`]: unknown;
|
|
117
|
+
};
|
|
118
|
+
type IsAny$1<T> = 0 extends 1 & T ? true : false;
|
|
119
|
+
/**
|
|
120
|
+
* The value a control stores on the field. `connect` sets `__shikiAccepts` from `format` / `parse` when those convert
|
|
121
|
+
* the value (a date string, not a Dayjs). Otherwise it is the control's `value` prop. An explicit
|
|
122
|
+
* `__shikiAccepts` on the component wins over the wide prop (antd `InputNumber` accepts `string | number` but stores
|
|
123
|
+
* `number | null`).
|
|
124
|
+
*/
|
|
125
|
+
type ControlValue<C> = C extends {
|
|
126
|
+
readonly __shikiAccepts: infer V;
|
|
127
|
+
} ? V : C extends ComponentType<infer P> ? P extends {
|
|
128
|
+
value?: infer V;
|
|
129
|
+
} ? IsAny$1<V> extends true ? any : V : any : any;
|
|
130
|
+
/**
|
|
131
|
+
* True when `V` can be passed as the control's value (`any` on either side skips the check).
|
|
132
|
+
* `undefined` and `null` are ignored on the field side: `string | null` still matches Input, `boolean | null` still
|
|
133
|
+
* matches Switch / Checkbox. A cleared option (`value: null`) is a separate enum check.
|
|
134
|
+
*/
|
|
135
|
+
type ControlAccepts<C, V> = IsAny$1<V> extends true ? true : IsAny$1<ControlValue<C>> extends true ? true : [Exclude<V, undefined | null>] extends [ControlValue<C>] ? true : false;
|
|
136
|
+
/**
|
|
137
|
+
* When the field value is not assignable to the control, the props gain a required explanation and `component`
|
|
138
|
+
* becomes `never`, so the error names both types.
|
|
139
|
+
*/
|
|
140
|
+
type ControlValueGuard<C, V> = ControlAccepts<C, V> extends true ? unknown : {
|
|
141
|
+
component?: never;
|
|
142
|
+
__shikiValueMismatch: {
|
|
143
|
+
field: V;
|
|
144
|
+
control: ControlValue<C>;
|
|
145
|
+
};
|
|
146
|
+
};
|
|
147
|
+
/**
|
|
148
|
+
* A `component` / `decorator` slot addressed by a name from {@link FieldComponents} / {@link FieldDecorators}.
|
|
149
|
+
* With nothing registered, any string (and a loose props object) is accepted — the same escape hatch as an untyped
|
|
150
|
+
* field name. Register the map (`declare module '@shikiform/react' { interface FieldComponents { Input: typeof Input } }`)
|
|
151
|
+
* and `"Input"` / `["Input", props]` are checked, including the props.
|
|
152
|
+
*/
|
|
153
|
+
type RegisteredSlot<Registry> = [keyof Registry] extends [never] ? string | readonly [string] | readonly [string, Record<string, any> | undefined] : {
|
|
154
|
+
[K in keyof Registry & string]: Registry[K] extends ComponentType<any> ? K | readonly [K] | readonly [K, SlotProps<Registry[K]> | undefined] : never;
|
|
155
|
+
}[keyof Registry & string];
|
|
156
|
+
/** `<Field component="Input">` when {@link FieldComponents} is augmented; any string otherwise. */
|
|
157
|
+
type RegisteredComponentSlot = RegisteredSlot<FieldComponents>;
|
|
158
|
+
/** `<Field decorator="FormItem">` when {@link FieldDecorators} is augmented; any string otherwise. */
|
|
159
|
+
type RegisteredDecoratorSlot = RegisteredSlot<FieldDecorators>;
|
|
160
|
+
/**
|
|
161
|
+
* Field options a hook caller can pass. Same semantics as the `<Field>` props of the same name:
|
|
162
|
+
* `rules` / `required` are a mount-scoped lease (applied while the calling component is mounted, released on unmount,
|
|
163
|
+
* restoring a declaration, item template, or `$rules`). `display` and `pattern` are persistent flags.
|
|
164
|
+
*/
|
|
165
|
+
interface UseFieldOptions<TValue = any> {
|
|
166
|
+
/**
|
|
167
|
+
* A second (third …) UI of the same field: `<Field name="amount" ui="slider" component={[Slider]} />`.
|
|
168
|
+
* Shares the value, errors and rules; has its own display / pattern / title / props, addressed in effects as
|
|
169
|
+
* `d.amount.$ui('slider')` (unset falls back to the field: pattern inherits). Own DOM id `<prefix>-<path>--<ui>`.
|
|
170
|
+
* `rules` / `required` / `enum` belong on the field itself (the `<Field>` without `ui`). `display` is this instance's.
|
|
171
|
+
*/
|
|
172
|
+
ui?: UiName;
|
|
173
|
+
/**
|
|
174
|
+
* Options for this field, inline (Formily `enum`): `[{ label, value }]`, bare primitives, or `SomeEnum.with(params)`.
|
|
175
|
+
* Wins over `fields.x.enum` / item templates while the component is mounted; a reaction's `$enum` wins over it.
|
|
176
|
+
* A new value (deep-compared, so an inline array is fine) is applied again; unmount or `undefined` restores the declaration.
|
|
177
|
+
*/
|
|
178
|
+
enum?: FieldEnum<TValue>;
|
|
179
|
+
rules?: RulesInput<TValue>;
|
|
180
|
+
required?: boolean;
|
|
181
|
+
/** `virtual` renders and validates but is not submitted. `hidden` / `none` do not render. */
|
|
182
|
+
display?: Display;
|
|
183
|
+
pattern?: Pattern;
|
|
184
|
+
/**
|
|
185
|
+
* UI state, the render-time JSX layer: not stored on the model, so inline objects and handlers are free.
|
|
186
|
+
* A reaction (`$title`, `$componentProps.x = …`) wins over it; it wins over `fields` declarations.
|
|
187
|
+
*/
|
|
188
|
+
title?: ReactNode;
|
|
189
|
+
description?: ReactNode;
|
|
190
|
+
/** The control, `[Control, props]`, or a name from {@link FieldComponents} (`"Input"`, `["Input", props]`). */
|
|
191
|
+
component?: FieldSlot | RegisteredComponentSlot;
|
|
192
|
+
/**
|
|
193
|
+
* The wrapper, `[Decorator, props]`, a name from {@link FieldDecorators}, or `false` to opt out of the
|
|
194
|
+
* default decorator from `<FieldKit>` / `<Form kit>`.
|
|
195
|
+
*/
|
|
196
|
+
decorator?: FieldSlot | RegisteredDecoratorSlot | false;
|
|
197
|
+
}
|
|
198
|
+
/**
|
|
199
|
+
* Subscribe to one field. This is the primitive every field component (`<Field>`, the Ant Design
|
|
200
|
+
* `connect` adapter, `FormItem`) is built on.
|
|
201
|
+
* Inside a row whose scope is `items.0`, `useField('price')` is `items.0.price`.
|
|
202
|
+
*
|
|
203
|
+
* Pass `options` to own the field's JSX-level config from a hook: `useField('email', { rules: z.string().email() })`
|
|
204
|
+
* behaves exactly like `<Field name="email" rules={z.string().email()}>`. UI options (`title`, `component`,
|
|
205
|
+
* `decorator`, …) are merged into the returned binding the same way `<Field>` merges them.
|
|
206
|
+
*
|
|
207
|
+
* A dynamic `string` name returns `FieldBinding<any>` so a column renderer can share one component.
|
|
208
|
+
* `useField<Row>('price')` rejects a key `Row` does not have. That value is the union of `Row`'s fields.
|
|
209
|
+
* `useField<Row, 'price'>('price')` types `field.value` as that property.
|
|
210
|
+
*
|
|
211
|
+
* With no name, `useField()` returns the field the nearest `<Field>` is rendering (Formily's
|
|
212
|
+
* `useField()`): this is how a custom input, decorator, or table cell reads its field without repeating the name.
|
|
213
|
+
* `useField<string>()` types `field.value`. Outside a field it throws a `ShikiUsageError` naming the fix.
|
|
214
|
+
* A call site either always passes a name or never does (the two forms use different hooks).
|
|
215
|
+
*/
|
|
216
|
+
declare function useField<TValue = any>(): FieldBinding<TValue>;
|
|
217
|
+
declare function useField(name: string, options?: UseFieldOptions): FieldBinding<any>;
|
|
218
|
+
declare function useField<TScope>(name: FieldPath<TScope>, options?: UseFieldOptions<PathValue<TScope, FieldPath<TScope> & string>>): FieldBinding<PathValue<TScope, FieldPath<TScope> & string>>;
|
|
219
|
+
declare function useField<TScope, N extends FieldPath<TScope>>(name: N, options?: UseFieldOptions<PathValue<TScope, N & string>>): FieldBinding<PathValue<TScope, N & string>>;
|
|
220
|
+
|
|
221
|
+
/** HTML5 drag-and-drop props for one row / node: the same object serves as drag source and drop target. */
|
|
222
|
+
interface DragProps {
|
|
223
|
+
draggable: true;
|
|
224
|
+
onDragStart: (event: DragEvent) => void;
|
|
225
|
+
onDragOver: (event: DragEvent) => void;
|
|
226
|
+
onDrop: (event: DragEvent) => void;
|
|
227
|
+
}
|
|
228
|
+
|
|
229
|
+
/**
|
|
230
|
+
* Tree handle. `move(from, to)` uses final `pos` coordinates and refuses a move into a descendant (the result says why).
|
|
231
|
+
* `dragProps(pos)` is the HTML5 drag-and-drop props for the node at that coordinate (source and drop target);
|
|
232
|
+
* dropping node A on node B is `move(A, B)`, so cross-parent moves keep the node id and its field state.
|
|
233
|
+
* Subscribes to structure only.
|
|
234
|
+
*/
|
|
235
|
+
declare function useTreeField(name: string, opts?: {
|
|
236
|
+
childrenKey?: string;
|
|
237
|
+
rowKey?: string;
|
|
238
|
+
}): {
|
|
239
|
+
path: string;
|
|
240
|
+
value: any[];
|
|
241
|
+
move: (from: Pos, to: Pos) => MoveResult;
|
|
242
|
+
dragProps: (at: Pos) => DragProps;
|
|
243
|
+
};
|
|
244
|
+
|
|
245
|
+
/** Submit callbacks of `<Form>` (and the antd `Submit` button's own `onSubmit`). */
|
|
246
|
+
interface FormSubmitHandlers<T> {
|
|
247
|
+
/** Called with the submit values after validation passes. May be async; the submit waits for it. */
|
|
248
|
+
onSubmit?: (values: T) => void | Promise<void>;
|
|
249
|
+
/** Called with the errors when validation fails (`reason: 'invalid'`). Scroll to the first error, show a toast … */
|
|
250
|
+
onInvalid?: (errors: FieldError[]) => void;
|
|
251
|
+
/**
|
|
252
|
+
* Called when `onSubmit` (or a form-level `validate`) throws or rejects (`reason: 'error'`).
|
|
253
|
+
* Without it the error is reported with `console.error`; it never becomes an unhandled rejection.
|
|
254
|
+
*/
|
|
255
|
+
onSubmitError?: (error: unknown) => void;
|
|
256
|
+
}
|
|
257
|
+
/** Native `<form>` attributes `<Form>` passes through (`id`, `className`, `noValidate`, `aria-*` …). */
|
|
258
|
+
type FormDomProps = Omit<FormHTMLAttributes<HTMLFormElement>, 'onSubmit' | 'onInvalid' | 'children'>;
|
|
259
|
+
/** `<Form>` props. `onSubmit` receives the form's `TSubmit` (default `T`, see `SubmitValues`). */
|
|
260
|
+
type FormProps<T, TSubmit = T> = FormSubmitHandlers<TSubmit> & FormDomProps & {
|
|
261
|
+
form: FormInstance<T, TSubmit>;
|
|
262
|
+
children?: ReactNode;
|
|
263
|
+
/**
|
|
264
|
+
* Controls and the default decorator for fields in this form ({@link FieldKit}).
|
|
265
|
+
* A field omits `decorator` to use `kit.decorator`; `decorator={false}` opts out.
|
|
266
|
+
* `component="Input"` / `component={["Input", props]}` look up `kit.components`.
|
|
267
|
+
*/
|
|
268
|
+
kit?: FieldKitSpec;
|
|
269
|
+
};
|
|
270
|
+
/**
|
|
271
|
+
* Provide `form` and submit on Enter / the submit button.
|
|
272
|
+
* `onInvalid` gets the errors when validation fails; `onSubmitError` gets what `onSubmit` threw.
|
|
273
|
+
* When a submit or `form.validate()` fails, the first errored field inside (document order) is focused.
|
|
274
|
+
* Other props go to the native `<form>`.
|
|
275
|
+
* Field DOM ids are prefixed with this form's `id`, or with React `useId()` when `id` is omitted, so two forms
|
|
276
|
+
* do not share `id="email"`. The engine's `binding().id` stays the sanitized path (`user.name` → `user-name`);
|
|
277
|
+
* the control's id is `<prefix>-user-name`.
|
|
278
|
+
* `<Field>` returns null for display `hidden` and `none` after subscribing, so a mounted model stays registered.
|
|
279
|
+
* `virtual` stays mounted: it renders and validates, and is omitted from submit.
|
|
280
|
+
* A field declared on the form, or given `$rules` / `registerField`, still validates when this component is not rendered.
|
|
281
|
+
*/
|
|
282
|
+
declare function Form<T, TSubmit = T>({ form, children, onSubmit, onInvalid, onSubmitError, id, kit, ...rest }: FormProps<T, TSubmit>): react.JSX.Element;
|
|
283
|
+
/** `<Field>` props. Every prop except `name` / `children` is a {@link useField} option of the same name. */
|
|
284
|
+
interface FieldProps<TScope = any, N extends FieldPath<TScope> = FieldPath<TScope>, C extends ComponentType<any> = ComponentType<any>, D extends ComponentType<any> = ComponentType<any>> {
|
|
285
|
+
/** Name relative to the current `<ObjectField>` / `<ArrayField>` / `<TreeField>` scope. */
|
|
286
|
+
name: N;
|
|
287
|
+
/**
|
|
288
|
+
* Another UI of the same field (`d.name.$ui('echo')` in effects): shared value / errors / rules, its own display,
|
|
289
|
+
* pattern, title and props (unset falls back to the field's). Own DOM id `<prefix>-<path>--<ui>`. Leave rules / required /
|
|
290
|
+
* enum to the `<Field>` without `ui`. `display` here is this instance's, not the field's.
|
|
291
|
+
*/
|
|
292
|
+
ui?: UiName;
|
|
293
|
+
/**
|
|
294
|
+
* Inline options (Formily `enum`): `[{ label, value }]`, bare primitives (`['a', 'b']`), or `SomeEnum.with(params)`.
|
|
295
|
+
* Option values are typed against the field value (its element type for an array field) when the name is typed
|
|
296
|
+
* (`typed(form).Field`, `row.Field`). Wins over `fields.x.enum` while mounted; a reaction's `$enum` wins over it.
|
|
297
|
+
* Changing the prop re-applies it; unmount restores the declared enum. Select / Radio / Checkbox.Group and their
|
|
298
|
+
* readPretty views read it as `options`.
|
|
299
|
+
*/
|
|
300
|
+
enum?: FieldEnum<PathValue<TScope, N & string>>;
|
|
301
|
+
/** Mount-scoped rules. Cleared on unmount. Does not erase a declaration, a template, or `$rules`. `validator` receives this field's value. */
|
|
302
|
+
rules?: RulesInput<PathValue<TScope, N & string>>;
|
|
303
|
+
/** Mount-scoped required flag. Cleared on unmount. A declared or `$required` flag stays. */
|
|
304
|
+
required?: boolean;
|
|
305
|
+
/**
|
|
306
|
+
* Initial display when no reaction has written `$display`. `virtual` renders and validates but is not submitted.
|
|
307
|
+
* On `<Field ui>` this is the instance's display (`visible` | `hidden` | `none`); `virtual` belongs on the field.
|
|
308
|
+
*/
|
|
309
|
+
display?: Display;
|
|
310
|
+
/** Initial pattern when no reaction has written `$pattern`. `$pattern = undefined` inherits again. */
|
|
311
|
+
pattern?: Pattern;
|
|
312
|
+
/** Decorator label (`FormItem` shows it as `label`). A reaction's `$title` wins. */
|
|
313
|
+
title?: ReactNode;
|
|
314
|
+
/** Decorator help text (`FormItem` shows it as `extra`). A reaction's `$description` wins. */
|
|
315
|
+
description?: ReactNode;
|
|
316
|
+
/**
|
|
317
|
+
* Wrapper around the control: `decorator={[FormItem, { tooltip: '…' }]}`, or a registered name (`"FormItem"`,
|
|
318
|
+
* `["FormItem", props]`). Reads the field from context. The tuple's props are the JSX layer of `decoratorProps`
|
|
319
|
+
* (under a reaction's `$decoratorProps`). `false` opts out of the `<Form kit>` / `<FieldKit>` default decorator.
|
|
320
|
+
*/
|
|
321
|
+
decorator?: FieldSlot<D> | RegisteredDecoratorSlot | false;
|
|
322
|
+
/**
|
|
323
|
+
* The control: `component={[Input, { placeholder: '…' }]}`, or a registered name (`"Input"`, `["Input", props]`).
|
|
324
|
+
* A `connect()`ed control reads the field from context. The tuple's props are the JSX layer of `componentProps`
|
|
325
|
+
* (under a reaction's `$componentProps`). A component reference and a string name are the same slot.
|
|
326
|
+
*/
|
|
327
|
+
component?: FieldSlot<C> | RegisteredComponentSlot;
|
|
328
|
+
/** A render prop (`(field) => …`), or field-aware children (`<Input />`) rendered instead of `component`. */
|
|
329
|
+
children?: ReactNode | ((field: FieldBinding<PathValue<TScope, N & string>>) => ReactNode);
|
|
330
|
+
}
|
|
331
|
+
/** {@link FieldProps} plus the control/value check (`InputNumber` on a `string` field does not compile). */
|
|
332
|
+
type CheckedFieldProps<TScope = any, N extends FieldPath<TScope> = FieldPath<TScope>, C extends ComponentType<any> = ComponentType<any>, D extends ComponentType<any> = ComponentType<any>> = FieldProps<TScope, N, C, D> & ControlValueGuard<C, PathValue<TScope, N & string>>;
|
|
333
|
+
/**
|
|
334
|
+
* One field: the single owner of a path's JSX config (Formily `<Field>`).
|
|
335
|
+
*
|
|
336
|
+
* ```tsx
|
|
337
|
+
* <Field name="email" title="邮箱" required rules={{ format: 'email' }}
|
|
338
|
+
* decorator={[FormItem]} component={[Input, { placeholder: 'name@example.com' }]} />
|
|
339
|
+
* ```
|
|
340
|
+
*
|
|
341
|
+
* It renders `decorator` around `component` (or around `children`), and provides the binding through
|
|
342
|
+
* {@link FieldContext}, so a decorator (`FormItem`) and a `connect()`ed control need no `name` of their own.
|
|
343
|
+
* Both receive the effective `decoratorProps` / `componentProps` (`fields` ← JSX ← reaction). A render prop
|
|
344
|
+
* `children={(field) => …}` still works and replaces `component`.
|
|
345
|
+
*
|
|
346
|
+
* `rules` may be a built-in rule, a Standard Schema, or a mix. JSX `rules` and `required` apply only while this
|
|
347
|
+
* component is mounted; unmount restores rules from `useForm({ fields })`, `registerField`, an item template, or `$rules`.
|
|
348
|
+
* `display="virtual"` renders and validates but omits the value from submit. `display="hidden"` still validates.
|
|
349
|
+
* `display="none"` skips validation. `<Field<Row> name="price">` checks the name.
|
|
350
|
+
* `<Field<Row, 'price'> name="price">` types the value.
|
|
351
|
+
* `<Field>` is a thin wrapper around {@link useField}: `useField(name, options)` + not rendered (`hidden` / `none`) → `null`
|
|
352
|
+
* + the two slots. `virtual` still renders.
|
|
353
|
+
*/
|
|
354
|
+
declare function Field<TScope = any, N extends FieldPath<TScope> = FieldPath<TScope>, C extends ComponentType<any> = ComponentType<any>, D extends ComponentType<any> = ComponentType<any>>({ name, children, ...options }: CheckedFieldProps<TScope, N, C, D>): react.JSX.Element | null;
|
|
355
|
+
/**
|
|
356
|
+
* Scope child names under an object path. Does not subscribe to child values.
|
|
357
|
+
* `display="virtual"` omits this object (and its subtree) from submit (`getSubmitValues`).
|
|
358
|
+
* Also list it in `useForm({ fields })` so the omission holds before this component mounts.
|
|
359
|
+
* `<ObjectField<Values> name="address">` checks the name; `typed(form).ObjectField` also types the children.
|
|
360
|
+
*/
|
|
361
|
+
declare function ObjectField<TScope = any>({ name, display, children, }: {
|
|
362
|
+
name: FieldPath<TScope>;
|
|
363
|
+
/** `virtual` omits this object from submit. `hidden` / `none` are inherited by the fields inside. */
|
|
364
|
+
display?: Display;
|
|
365
|
+
children?: ReactNode;
|
|
366
|
+
}): react.JSX.Element;
|
|
367
|
+
/**
|
|
368
|
+
* The owner of an array path. Repeats `children` once per row; the key is the row id when present (`rowKey`, else
|
|
369
|
+
* `id`), otherwise a stable object identity, so rows without an id keep their state when they move.
|
|
370
|
+
* The parent subscribes to structure only. Put cell inputs in a child that calls `useField`.
|
|
371
|
+
* Names inside a row are relative to the row (`name="price"`, not `items.0.price`).
|
|
372
|
+
* `component` is the container around the rows (Formily `ArrayItems` / `ArrayCards` / `ArrayTable` in
|
|
373
|
+
* `@shikiform/antd`): `component={[ArrayItems, { addition: <ArrayItems.Addition /> }]}` renders
|
|
374
|
+
* `<ArrayItems …>{rows}</ArrayItems>` inside the array's scope, so its buttons reach the array through {@link useArray}.
|
|
375
|
+
* A container that renders its own cells (`ArrayTable` with `columns`) needs no `children`.
|
|
376
|
+
* `virtualScroll` windows the plain rows (TanStack Virtual); it does not combine with a container `component`.
|
|
377
|
+
* `<ArrayField<Values> name="items">` checks the name; `typed(form).ArrayField` also types the row's fields.
|
|
378
|
+
*/
|
|
379
|
+
/**
|
|
380
|
+
* The `component` of an `<ArrayField>`: a container, or `[Container, props]`. The props are checked against the
|
|
381
|
+
* container (`[ArrayTable, { columns }]` requires `columns` and types each column's `render`); `children` is the rows.
|
|
382
|
+
*/
|
|
383
|
+
type ArrayContainerSlot<C extends ComponentType<any> = ComponentType<any>> = C | readonly [C] | readonly [C, Omit<ComponentProps<C>, 'children'> | undefined];
|
|
384
|
+
declare function ArrayField<TScope = any, C extends ComponentType<any> = ComponentType<any>>({ name, rowKey, component, virtualScroll, children, }: {
|
|
385
|
+
name: ArrayPath<TScope>;
|
|
386
|
+
rowKey?: string;
|
|
387
|
+
/** Container around the rows: the component, or `[Component, props]`. It receives the rows as `children`. */
|
|
388
|
+
component?: ArrayContainerSlot<C>;
|
|
389
|
+
/** Window the rows: only those in view (plus `overscan`) mount. Plain rows only (no `component`). */
|
|
390
|
+
virtualScroll?: {
|
|
391
|
+
height: number;
|
|
392
|
+
rowHeight?: number;
|
|
393
|
+
overscan?: number;
|
|
394
|
+
};
|
|
395
|
+
/** One row. Optional when `component` renders the rows itself (`ArrayTable` columns). */
|
|
396
|
+
children?: (row: {
|
|
397
|
+
index: number;
|
|
398
|
+
key: string;
|
|
399
|
+
}) => ReactNode;
|
|
400
|
+
}): react.JSX.Element;
|
|
401
|
+
/**
|
|
402
|
+
* Mark the nearest array for {@link useArray} (`path` is absolute). `<ArrayField>` renders it; use it in a custom
|
|
403
|
+
* array component built on `useArrayField`.
|
|
404
|
+
*/
|
|
405
|
+
declare function ArrayScope({ path, rowKey, children }: {
|
|
406
|
+
path: string;
|
|
407
|
+
rowKey?: string;
|
|
408
|
+
children?: ReactNode;
|
|
409
|
+
}): react.JSX.Element;
|
|
410
|
+
/**
|
|
411
|
+
* Scope for one row (or tree node): relative names resolve under `path`, and {@link useIndex} / {@link useRecord}
|
|
412
|
+
* (/ {@link useTreeNode} with `pos`) read it. Stable value, so a row that did not move does not wake its consumers.
|
|
413
|
+
* For a tree node pass `pos` (and `index` = its last segment, or omit `index`).
|
|
414
|
+
*/
|
|
415
|
+
declare function RowScope({ path, index, itemKey, pos, children, }: {
|
|
416
|
+
path: string;
|
|
417
|
+
index?: number;
|
|
418
|
+
/** Row id (structure key). */
|
|
419
|
+
itemKey?: string;
|
|
420
|
+
/** Tree coordinate of this node. */
|
|
421
|
+
pos?: Pos;
|
|
422
|
+
children?: ReactNode;
|
|
423
|
+
}): react.JSX.Element;
|
|
424
|
+
/** Register a tree root. Rendering nodes is the caller's job (`pos` is `number[]`). `<TreeField<Values>>` checks the name. */
|
|
425
|
+
declare function TreeField<TScope = any>({ name, childrenKey, rowKey, children, }: {
|
|
426
|
+
name: ArrayPath<TScope>;
|
|
427
|
+
childrenKey?: string;
|
|
428
|
+
rowKey?: string;
|
|
429
|
+
children: (tree: ReturnType<typeof useTreeField>) => ReactNode;
|
|
430
|
+
}): ReactNode;
|
|
431
|
+
/**
|
|
432
|
+
* Render `children` with the current selector value. Same selectors and typing as {@link useWatch}:
|
|
433
|
+
* an unannotated `select={(d) => d.$canSubmit}` compiles (`d` is untyped); `typed(form).Watch` or
|
|
434
|
+
* `select={(d: Draft<Values>) => …}` types the draft and the value.
|
|
435
|
+
* `select={(d) => d.$canSubmit}` subscribes a submit button without subscribing to every keystroke.
|
|
436
|
+
*/
|
|
437
|
+
declare function Watch<T = any, S = unknown>({ select, children }: {
|
|
438
|
+
select: (d: Draft<T>) => S;
|
|
439
|
+
children: (value: S) => ReactNode;
|
|
440
|
+
}): react.JSX.Element;
|
|
441
|
+
|
|
442
|
+
/** The minimum a click handler needs. DOM and component events satisfy it. */
|
|
443
|
+
interface ClickEvent {
|
|
444
|
+
preventDefault(): void;
|
|
445
|
+
readonly defaultPrevented: boolean;
|
|
446
|
+
}
|
|
447
|
+
/**
|
|
448
|
+
* What {@link useSubmit} returns. Spread the DOM fields onto a button, or read `loading` for a spinner.
|
|
449
|
+
* `disabled` follows `!$canSubmit` unless `options.disabled` is passed (`false` forces the button enabled).
|
|
450
|
+
*/
|
|
451
|
+
interface SubmitState<E = ClickEvent> {
|
|
452
|
+
/** True when the form has no shown errors and is not submitting or validating. */
|
|
453
|
+
canSubmit: boolean;
|
|
454
|
+
submitting: boolean;
|
|
455
|
+
/** Alias of `submitting`, for a spinner. */
|
|
456
|
+
loading: boolean;
|
|
457
|
+
disabled: boolean;
|
|
458
|
+
/** `'button'` when `onSubmit` is passed (the click submits). Otherwise `'submit'` for `<Form onSubmit>`. */
|
|
459
|
+
type: 'submit' | 'button';
|
|
460
|
+
'aria-busy': true | undefined;
|
|
461
|
+
'data-loading': '' | undefined;
|
|
462
|
+
onClick: (event: E) => void;
|
|
463
|
+
}
|
|
464
|
+
interface UseSubmitOptions<T, E> extends FormSubmitHandlers<T> {
|
|
465
|
+
/** Overrides `!$canSubmit`. `false` keeps the button enabled while the form is invalid. */
|
|
466
|
+
disabled?: boolean;
|
|
467
|
+
/** Runs first. `preventDefault` skips the submit this button would start (`onSubmit` passed). */
|
|
468
|
+
onClick?: (event: E) => void;
|
|
469
|
+
}
|
|
470
|
+
/**
|
|
471
|
+
* Submit state for the surrounding form. Disabled while `$canSubmit` is false, busy while `$submitting`.
|
|
472
|
+
* Subscribes to form meta only, not to field values.
|
|
473
|
+
*
|
|
474
|
+
* - Without `onSubmit`, `type` is `'submit'`: the click is a native submit and `<Form onSubmit>` handles it.
|
|
475
|
+
* - With `onSubmit`, `type` is `'button'` and the click runs `form.submit(onSubmit)` (no `<form>` element required).
|
|
476
|
+
*
|
|
477
|
+
* ```tsx
|
|
478
|
+
* const submit = useSubmit({ onSubmit: save })
|
|
479
|
+
* return <button type={submit.type} disabled={submit.disabled} aria-busy={submit['aria-busy']} onClick={submit.onClick}>保存</button>
|
|
480
|
+
* ```
|
|
481
|
+
*/
|
|
482
|
+
declare function useSubmit<T = any, E extends ClickEvent = ClickEvent>(options?: UseSubmitOptions<T, E>): SubmitState<E>;
|
|
483
|
+
interface UseResetOptions<T, E> {
|
|
484
|
+
/** Passed to `form.reset(values)`: the new initial values. Omit to restore the current initial values. */
|
|
485
|
+
values?: T;
|
|
486
|
+
/**
|
|
487
|
+
* Called after `form.reset`, with the values already restored. `onClick` still runs first;
|
|
488
|
+
* `preventDefault` there skips the reset and this callback.
|
|
489
|
+
*/
|
|
490
|
+
afterReset?: (values: T) => void;
|
|
491
|
+
/** Runs before the reset. `preventDefault` skips the reset. */
|
|
492
|
+
onClick?: (event: E) => void;
|
|
493
|
+
/**
|
|
494
|
+
* Forces the button disabled. Default `false`: reset stays available while the form is invalid
|
|
495
|
+
* (unlike {@link useSubmit}, whose `disabled` follows `!$canSubmit`).
|
|
496
|
+
*/
|
|
497
|
+
disabled?: boolean;
|
|
498
|
+
}
|
|
499
|
+
/** What {@link useReset} returns. `type` is always `'button'` so a native form reset does not bypass the store. */
|
|
500
|
+
interface ResetState<E = ClickEvent> {
|
|
501
|
+
type: 'button';
|
|
502
|
+
/** `options.disabled`, or `false`. Reset is not tied to `$canSubmit`. */
|
|
503
|
+
disabled: boolean;
|
|
504
|
+
onClick: (event: E) => void;
|
|
505
|
+
}
|
|
506
|
+
/**
|
|
507
|
+
* Reset handler for the surrounding form. `onClick` runs first (and can cancel); `form.reset` runs next;
|
|
508
|
+
* `afterReset` receives the restored values, so a query page can search with the cleared filters
|
|
509
|
+
* without reading the values from before the click.
|
|
510
|
+
*
|
|
511
|
+
* ```tsx
|
|
512
|
+
* const reset = useReset({ afterReset: (values) => search(values) })
|
|
513
|
+
* return <button type={reset.type} disabled={reset.disabled} onClick={reset.onClick}>重置</button>
|
|
514
|
+
* ```
|
|
515
|
+
*/
|
|
516
|
+
declare function useReset<T = any, E extends ClickEvent = ClickEvent>(options?: UseResetOptions<T, E>): ResetState<E>;
|
|
517
|
+
|
|
518
|
+
/**
|
|
519
|
+
* Binding keys a control receives by default (each under its own name unless mapped).
|
|
520
|
+
* `status` is Ant Design's (`'error'` / `'warning'`). Headless `connect` does not pass it;
|
|
521
|
+
* `@shikiform/antd` opts in with `mapProps({ status: 'status' })` on the controls that paint it.
|
|
522
|
+
*/
|
|
523
|
+
type FieldPropKey = 'value' | 'onChange' | 'onBlur' | 'disabled' | 'readOnly' | 'status' | 'id' | 'options' | 'loading';
|
|
524
|
+
/**
|
|
525
|
+
* Any other field state a `mapProps` object can hand to a prop (Formily: the key is a field path):
|
|
526
|
+
* `{ title: 'placeholder' }`, `{ required: 'aria-required' }`, `{ 'componentProps.max': 'count' }`.
|
|
527
|
+
*/
|
|
528
|
+
type FieldStateKey = 'title' | 'description' | 'required' | 'validating' | 'touched' | 'dirty' | 'edited' | 'pattern' | 'display' | 'path' | 'errors' | 'warnings' | `componentProps.${string}` | `decoratorProps.${string}`;
|
|
529
|
+
/**
|
|
530
|
+
* Where blur validation goes when the control has no `onBlur` (a Lobe Select, a popover picker).
|
|
531
|
+
* Without this, `validateTrigger: 'onBlur'` never runs because the `onBlur` prop is ignored.
|
|
532
|
+
*
|
|
533
|
+
* - `'onChange'` — `field.onBlur()` after each change (the value is already written).
|
|
534
|
+
* - `'onOpenChange'` — `field.onBlur()` when the first argument is `false` (the popup closed).
|
|
535
|
+
* - `{ prop, when? }` — `field.onBlur()` when `prop` fires and `when(...args)` is not false (`when` defaults to always).
|
|
536
|
+
*/
|
|
537
|
+
type BlurOn = 'onChange' | 'onOpenChange' | {
|
|
538
|
+
prop: string;
|
|
539
|
+
when?: (...args: any[]) => boolean;
|
|
540
|
+
};
|
|
541
|
+
/**
|
|
542
|
+
* Rename (`{ value: 'checked' }`), merge (`{ readOnly: 'disabled' }`), drop (`{ onBlur: false }`) binding props, or pass
|
|
543
|
+
* more field state to a prop (`{ title: 'placeholder' }`; an explicit caller prop wins).
|
|
544
|
+
* `format` / `parse` convert between the field value and the control value (a `'YYYY-MM-DD'` string in the field,
|
|
545
|
+
* a `Date` / Dayjs in the control). `parse` replaces the default {@link valueFromEvent}. `format` runs after prop
|
|
546
|
+
* transforms, so it sees the control's own props (`props.format`, …). `readPretty` is not converted: the view gets
|
|
547
|
+
* the field value.
|
|
548
|
+
* `blurOn` is the blur fallback for a control that does not call `onBlur` ({@link BlurOn}). It replaces the default
|
|
549
|
+
* `onBlur` prop so the unused handler is not passed through.
|
|
550
|
+
*
|
|
551
|
+
* Inside `connect(Control, mapProps({ … }))`, `parse`'s parameters are the control's `onChange` arguments and
|
|
552
|
+
* `format`'s `props` are the control's props, so a date converter does not annotate Dayjs / Date. Annotate
|
|
553
|
+
* `format`'s value parameter when you want that callback to name the field type.
|
|
554
|
+
*/
|
|
555
|
+
type PropsMapping<P = any, F = any> = Partial<Record<FieldPropKey | FieldStateKey, string | false>> & {
|
|
556
|
+
/** Field value → the value the control receives (the prop named by `value`, default `'value'`). */
|
|
557
|
+
format?: (value: F, props: FormatProps<P>) => ValueOf<P>;
|
|
558
|
+
/** Control `onChange` arguments → the value stored on the field. Default: {@link valueFromEvent}. */
|
|
559
|
+
parse?: ParseFn<P, F>;
|
|
560
|
+
blurOn?: BlurOn;
|
|
561
|
+
};
|
|
562
|
+
/** `true` when `P` is `any` (not a concrete props type). `unknown` is not `any`. */
|
|
563
|
+
type IsAny<T> = 0 extends 1 & T ? true : false;
|
|
564
|
+
/** `P['value']` when the control has one, otherwise unchecked. */
|
|
565
|
+
type ValueOf<P> = IsAny<P> extends true ? unknown : P extends {
|
|
566
|
+
value?: infer V;
|
|
567
|
+
} ? V : unknown;
|
|
568
|
+
/**
|
|
569
|
+
* Parameter list of `P['onChange']`. `any` / `unknown` (mapProps outside `connect`, or a control with no
|
|
570
|
+
* `onChange`) stay loose: a fixed-arity `parse` must still be assignable. A concrete list is what `connect`
|
|
571
|
+
* uses to type `parse`'s parameters.
|
|
572
|
+
*/
|
|
573
|
+
type ChangeArgs<P> = IsAny<P> extends true ? any[] : [unknown] extends [P] ? any[] : P extends {
|
|
574
|
+
onChange?: (...args: infer A) => any;
|
|
575
|
+
} ? A : any[];
|
|
576
|
+
/**
|
|
577
|
+
* `parse`. Concrete `onChange` parameters stay strict (a `string` callback is not a `Date` callback).
|
|
578
|
+
* When the props type is not known, the callback is bivariant so `(a, b) => field` still assigns to a rest `any[]`.
|
|
579
|
+
*/
|
|
580
|
+
type ParseFn<P, F> = IsAny<P> extends true ? {
|
|
581
|
+
bivarianceHack(...args: any[]): F;
|
|
582
|
+
}['bivarianceHack'] : [unknown] extends [P] ? {
|
|
583
|
+
bivarianceHack(...args: any[]): F;
|
|
584
|
+
}['bivarianceHack'] : (...args: ChangeArgs<P>) => F;
|
|
585
|
+
/** `format`'s props parameter. `any` when the control props are not known yet, so an annotation is allowed. */
|
|
586
|
+
type FormatProps<P> = IsAny<P> extends true ? any : [unknown] extends [P] ? any : P;
|
|
587
|
+
/** A props enhancer whose `format` / `parse` are checked against the control `connect` wraps. */
|
|
588
|
+
type CodecEnhancer<P, F> = PropsEnhancer & {
|
|
589
|
+
__codec: {
|
|
590
|
+
props: P;
|
|
591
|
+
field: F;
|
|
592
|
+
};
|
|
593
|
+
};
|
|
594
|
+
/** Last-step transform: receives the mapped props and the field, returns the props the control gets. */
|
|
595
|
+
type PropsTransform = (props: Record<string, any>, field: FieldBinding<any>) => Record<string, any>;
|
|
596
|
+
/** Set when a props enhancer decides blur: a {@link BlurOn} fallback, an `onBlur` rename, or an explicit drop. */
|
|
597
|
+
type BlurFlag = BlurOn | 'drop' | 'rename';
|
|
598
|
+
type PropsEnhancer = {
|
|
599
|
+
kind: 'props';
|
|
600
|
+
mapping: PropsMapping;
|
|
601
|
+
transforms: PropsTransform[];
|
|
602
|
+
/** Present when this mapping names a blur fallback, renames `onBlur`, or drops it on purpose. */
|
|
603
|
+
blur?: BlurFlag;
|
|
604
|
+
};
|
|
605
|
+
type ReadPrettyEnhancer = {
|
|
606
|
+
kind: 'readPretty';
|
|
607
|
+
component: ComponentType<any>;
|
|
608
|
+
props?: Record<string, unknown>;
|
|
609
|
+
};
|
|
610
|
+
type ConnectEnhancer = PropsEnhancer | ReadPrettyEnhancer;
|
|
611
|
+
/** Props every connected control accepts besides its own. */
|
|
612
|
+
interface ConnectFieldProps {
|
|
613
|
+
/** Field name relative to the current scope. Omit it inside a `<Field>`, which supplies the field. */
|
|
614
|
+
name?: string;
|
|
615
|
+
/** An explicit binding, e.g. from `useField(name, options)`. Wins over `name` and context. */
|
|
616
|
+
field?: FieldBinding<any>;
|
|
617
|
+
}
|
|
618
|
+
/** A connected control: the target's props (all optional) plus {@link ConnectFieldProps}; the ref reaches the target. */
|
|
619
|
+
type ConnectedComponent<P> = ComponentType<Partial<P> & ConnectFieldProps & {
|
|
620
|
+
ref?: Ref<any>;
|
|
621
|
+
}>;
|
|
622
|
+
/** Static members of a component (`Select.Option`, `Input.Group` …), hoisted onto its connected version. */
|
|
623
|
+
type ComponentStatics<C> = Omit<C, keyof FunctionComponent<any> | keyof ComponentClass<any> | keyof ForwardRefExoticComponent<any> | 'prototype'>;
|
|
624
|
+
/**
|
|
625
|
+
* Default `onChange` → value: a DOM change event yields `target.checked` for checkboxes and
|
|
626
|
+
* `target.value` otherwise; anything else (a number, an array, `null`) is the value itself.
|
|
627
|
+
*/
|
|
628
|
+
declare function valueFromEvent(...args: any[]): unknown;
|
|
629
|
+
/**
|
|
630
|
+
* Map a field binding plus caller props onto a control's props. Pure; this is all `connect` does per render,
|
|
631
|
+
* exported so a hook user (`useField`) gets the identical mapping without a wrapper component:
|
|
632
|
+
*
|
|
633
|
+
* ```tsx
|
|
634
|
+
* const field = useField('email', { required: true })
|
|
635
|
+
* return <input {...mapFieldProps(field, { placeholder: 'Email' })} />
|
|
636
|
+
* ```
|
|
637
|
+
*
|
|
638
|
+
* - `value` → the field value (`format`, when set, turns it into the control's value after the other mapping);
|
|
639
|
+
* `onChange` → `field.onChange(parse(...args))` (default {@link valueFromEvent}), then the caller's handler
|
|
640
|
+
* with the original arguments; `onBlur` → `field.onBlur()`, then the caller's handler.
|
|
641
|
+
* - `disabled` / `readOnly` are OR-ed with the caller's prop. Several keys may target one prop (`readOnly: 'disabled'`).
|
|
642
|
+
* - `status` is not passed unless mapped (`{ status: 'status' }`): then `'error'` with errors, `'warning'` with only
|
|
643
|
+
* warnings; an explicit caller `status` wins. Ant Design controls that paint `status` opt in; others should not.
|
|
644
|
+
* - `options` (enum, tree nodes keep `children`) and `loading` are passed only when mapped; an explicit caller prop wins.
|
|
645
|
+
* - `blurOn` calls `field.onBlur()` from another prop and does not pass `onBlur` (see {@link BlurOn}).
|
|
646
|
+
* - `readPretty` without a `mapReadPretty` view is treated as `readOnly`.
|
|
647
|
+
* - `field.componentProps` (`fields` ← JSX ← `$componentProps`) are merged under `props`.
|
|
648
|
+
*/
|
|
649
|
+
declare function mapFieldProps(field: FieldBinding<any>, props: Record<string, any>, ...mappers: Array<PropsMapping | PropsTransform>): Record<string, any>;
|
|
650
|
+
/** A mapping that does not convert values. `format` / `parse` take the codec overload so `connect` can check them. */
|
|
651
|
+
type MapArg = Omit<PropsMapping, 'format' | 'parse'> | PropsTransform;
|
|
652
|
+
type BlurFrom<A extends readonly unknown[]> = A extends readonly [infer H, ...infer R] ? H extends {
|
|
653
|
+
blurOn: infer B;
|
|
654
|
+
} ? [B] extends [BlurOn] ? B : BlurFrom<R> : H extends {
|
|
655
|
+
onBlur: false;
|
|
656
|
+
} ? 'drop' : H extends {
|
|
657
|
+
onBlur: string;
|
|
658
|
+
} ? 'rename' : BlurFrom<R> : undefined;
|
|
659
|
+
type MapPropsResult<A extends readonly unknown[]> = [
|
|
660
|
+
BlurFrom<A>
|
|
661
|
+
] extends [undefined] ? PropsEnhancer : PropsEnhancer & {
|
|
662
|
+
blur: NonNullable<BlurFrom<A>>;
|
|
663
|
+
};
|
|
664
|
+
/**
|
|
665
|
+
* Describe how a control's props come from the field (Formily `mapProps`).
|
|
666
|
+
* Objects rename / merge / drop binding props; functions transform the final props.
|
|
667
|
+
* `format` / `parse` on the first object convert the field value both ways ({@link PropsMapping}).
|
|
668
|
+
*
|
|
669
|
+
* ```ts
|
|
670
|
+
* connect(Switch, mapProps({ value: 'checked', readOnly: 'disabled' }))
|
|
671
|
+
* connect(LobeSelect, mapProps({ options: 'options', blurOn: 'onOpenChange' }))
|
|
672
|
+
* connect(DatePicker, mapProps({
|
|
673
|
+
* format: (value: string | undefined) => (value ? parseISO(value) : null),
|
|
674
|
+
* parse: (next: Date | null) => (next ? format(next, 'yyyy-MM-dd') : undefined),
|
|
675
|
+
* }))
|
|
676
|
+
* ```
|
|
677
|
+
*
|
|
678
|
+
* `blurOn` keeps `validateTrigger: 'onBlur'` alive when the control never calls `onBlur`.
|
|
679
|
+
* `mapBlur('onOpenChange')` is the same decision as its own enhancer.
|
|
680
|
+
* Put `format` / `parse` on the first object so `connect` can check them against the control.
|
|
681
|
+
*/
|
|
682
|
+
type CodecMapping<P, F> = PropsMapping<P, F> & ({
|
|
683
|
+
format: (value: F, props: FormatProps<P>) => ValueOf<P>;
|
|
684
|
+
} | {
|
|
685
|
+
parse: ParseFn<P, F>;
|
|
686
|
+
});
|
|
687
|
+
declare function mapProps<P, F>(mapping: CodecMapping<P, F>, ...rest: Array<PropsMapping<P, F> | PropsTransform>): CodecEnhancer<P, F>;
|
|
688
|
+
declare function mapProps<const A extends readonly MapArg[]>(...args: A): MapPropsResult<A>;
|
|
689
|
+
/**
|
|
690
|
+
* Blur fallback as its own enhancer (same as `mapProps({ blurOn })`).
|
|
691
|
+
* Use it when the control's props type has no `onBlur` — `connect` requires one of these, or `onBlur: false`.
|
|
692
|
+
*
|
|
693
|
+
* ```ts
|
|
694
|
+
* connect(LobeSelect, mapBlur('onOpenChange'), mapProps({ options: 'options' }))
|
|
695
|
+
* ```
|
|
696
|
+
*/
|
|
697
|
+
declare function mapBlur(on: BlurOn): PropsEnhancer & {
|
|
698
|
+
blur: BlurOn;
|
|
699
|
+
};
|
|
700
|
+
/**
|
|
701
|
+
* Render `component` instead of the control when the field pattern is `readPretty` (Formily `mapReadPretty`).
|
|
702
|
+
* It receives the caller props plus `value` and `options` (the enum).
|
|
703
|
+
*/
|
|
704
|
+
declare function mapReadPretty(component: ComponentType<any>, props?: Record<string, unknown>): ReadPrettyEnhancer;
|
|
705
|
+
/**
|
|
706
|
+
* Props of a component, from its call signature. `unknown` when the signature can't be read
|
|
707
|
+
* (then blur is not required — a typed `onBlur` is what the check can see).
|
|
708
|
+
*/
|
|
709
|
+
type CallProps<C> = C extends (props: infer P, ...args: any[]) => any ? P : unknown;
|
|
710
|
+
/**
|
|
711
|
+
* True when the control's props include `onBlur` (so the handler we pass can be called),
|
|
712
|
+
* or when the props type can't be read. A closed props type with no `onBlur` is false:
|
|
713
|
+
* passing `onBlur` would be ignored and blur validation would disappear.
|
|
714
|
+
*/
|
|
715
|
+
type HasOnBlurProp<C> = [CallProps<C>] extends [unknown] ? [unknown] extends [CallProps<C>] ? true : 'onBlur' extends keyof CallProps<C> ? true : false : true;
|
|
716
|
+
type AnyBlur<E extends readonly unknown[]> = E extends readonly [infer H, ...infer R] ? H extends {
|
|
717
|
+
blur: BlurFlag;
|
|
718
|
+
} ? true : AnyBlur<R> : false;
|
|
719
|
+
type DemandBlur<C> = C & {
|
|
720
|
+
readonly __shikiConnectBlurFallback: 'This control has no onBlur, so onBlur validation would never run. Pass mapProps({ blurOn: "onChange" | "onOpenChange" | { prop, when? } }), mapBlur(...), or mapProps({ onBlur: false }) to opt out.';
|
|
721
|
+
};
|
|
722
|
+
type BlurTarget<C, E extends readonly unknown[]> = HasOnBlurProp<C> extends true ? C : AnyBlur<E> extends true ? C : DemandBlur<C>;
|
|
723
|
+
type ValueOfProps<C> = C extends ComponentType<infer P> ? (P extends {
|
|
724
|
+
value?: infer V;
|
|
725
|
+
} ? V : unknown) : unknown;
|
|
726
|
+
/**
|
|
727
|
+
* Field value this control stores. Codec `format` / `parse` set it (a date field is a string, not a Dayjs).
|
|
728
|
+
* Otherwise it is the `value` prop. A later `__shikiAccepts` intersection narrows it (`InputNumber` → `number | null`).
|
|
729
|
+
*/
|
|
730
|
+
type ConnectedOf<C extends ComponentType<any>, V = ValueOfProps<C>> = ConnectedComponent<ComponentProps<C>> & ComponentStatics<C> & {
|
|
731
|
+
readonly __shikiAccepts: V;
|
|
732
|
+
};
|
|
733
|
+
/** A plain enhancer: `format` / `parse` go through {@link CodecEnhancer}, so a mismatch is not swallowed by this overload. */
|
|
734
|
+
type NoCodec<E> = E extends {
|
|
735
|
+
__codec: any;
|
|
736
|
+
} ? never : E;
|
|
737
|
+
/**
|
|
738
|
+
* Turn any value/onChange control into a ShikiForm field control (Formily `connect`).
|
|
739
|
+
* Lives in `@shikiform/react` (no Ant Design). `@shikiform/antd` re-exports it and opts its controls into `status`.
|
|
740
|
+
*
|
|
741
|
+
* The result reads its field from, in order: a `field` prop, a `name` prop (via {@link useField}),
|
|
742
|
+
* or the surrounding `<Field>` (what `useField()` with no name returns). It has no state of its own: every prop comes
|
|
743
|
+
* from {@link mapFieldProps} over the binding, with the field's `componentProps` merged under the caller's props
|
|
744
|
+
* (so `$componentProps.placeholder = …` in a reaction reaches the control).
|
|
745
|
+
*
|
|
746
|
+
* A control whose props type has no `onBlur` must say where blur validation goes
|
|
747
|
+
* (`mapProps({ blurOn })` / {@link mapBlur} / `mapProps({ onBlur: false })`). Otherwise `validateTrigger: 'onBlur'`
|
|
748
|
+
* would never run and TypeScript would not complain. `blurOn: 'onOpenChange'` treats a popup close (`false`) as blur;
|
|
749
|
+
* `blurOn: 'onChange'` blurs after every change.
|
|
750
|
+
*
|
|
751
|
+
* It forwards `ref` to the target and copies the target's static members (`Select.Option`,
|
|
752
|
+
* `Input.Search` — the originals, not connected). With no field at all it renders the plain control with the
|
|
753
|
+
* caller's props and warns once in development.
|
|
754
|
+
*
|
|
755
|
+
* ```tsx
|
|
756
|
+
* const Rate = connect(Stars, mapProps({ value: 'score', onChange: 'onPick', onBlur: false }))
|
|
757
|
+
* const City = connect(LobeSelect, mapProps({ options: 'options', blurOn: 'onOpenChange' }))
|
|
758
|
+
* const Birthday = connect(DateInput, mapProps({
|
|
759
|
+
* format: (value: string | undefined) => (value ? new Date(value) : null),
|
|
760
|
+
* parse: (next: Date | null) => (next ? next.toISOString().slice(0, 10) : undefined),
|
|
761
|
+
* }))
|
|
762
|
+
* ```
|
|
763
|
+
*/
|
|
764
|
+
declare function connect<C extends ComponentType<any>, F, E extends readonly ConnectEnhancer[]>(target: C, e1: CodecEnhancer<ComponentProps<C>, F>, ...rest: E): BlurTarget<C, [CodecEnhancer<ComponentProps<C>, F>, ...E]> extends C ? ConnectedOf<C, F> : DemandBlur<C>;
|
|
765
|
+
declare function connect<C extends ComponentType<any>, F, E1 extends ConnectEnhancer, E extends readonly ConnectEnhancer[]>(target: C, e1: E1, e2: CodecEnhancer<ComponentProps<C>, F>, ...rest: E): BlurTarget<C, [E1, CodecEnhancer<ComponentProps<C>, F>, ...E]> extends C ? ConnectedOf<C, F> : DemandBlur<C>;
|
|
766
|
+
declare function connect<C extends ComponentType<any>>(target: BlurTarget<C, []>): ConnectedOf<C>;
|
|
767
|
+
declare function connect<C extends ComponentType<any>, E1 extends ConnectEnhancer>(target: BlurTarget<C, [NoCodec<E1>]>, e1: NoCodec<E1>): ConnectedOf<C>;
|
|
768
|
+
declare function connect<C extends ComponentType<any>, E1 extends ConnectEnhancer, E2 extends ConnectEnhancer>(target: BlurTarget<C, [NoCodec<E1>, NoCodec<E2>]>, e1: NoCodec<E1>, e2: NoCodec<E2>): ConnectedOf<C>;
|
|
769
|
+
declare function connect<C extends ComponentType<any>, E1 extends ConnectEnhancer, E2 extends ConnectEnhancer, E3 extends ConnectEnhancer>(target: BlurTarget<C, [NoCodec<E1>, NoCodec<E2>, NoCodec<E3>]>, e1: NoCodec<E1>, e2: NoCodec<E2>, e3: NoCodec<E3>): ConnectedOf<C>;
|
|
770
|
+
declare function connect<C extends ComponentType<any>, E1 extends ConnectEnhancer, E2 extends ConnectEnhancer, E3 extends ConnectEnhancer, E4 extends ConnectEnhancer>(target: BlurTarget<C, [NoCodec<E1>, NoCodec<E2>, NoCodec<E3>, NoCodec<E4>]>, e1: NoCodec<E1>, e2: NoCodec<E2>, e3: NoCodec<E3>, e4: NoCodec<E4>): ConnectedOf<C>;
|
|
771
|
+
|
|
772
|
+
/** `useForm` options: {@link FormOptions} plus `values`. */
|
|
773
|
+
interface UseFormOptions<T> extends FormOptions<T> {
|
|
774
|
+
/**
|
|
775
|
+
* Values owned outside the form (a loaded record, a query cache). The first render uses them as `initialValues`.
|
|
776
|
+
* When a later render passes a different object whose content also changed, the form calls `reset(values)`:
|
|
777
|
+
* they become the new baseline, edits are discarded, the form is not dirty. Same content under a new identity
|
|
778
|
+
* (an inline literal) does nothing. `initialValues` is read once; use `values` when the data can change.
|
|
779
|
+
*/
|
|
780
|
+
values?: T;
|
|
781
|
+
}
|
|
782
|
+
/**
|
|
783
|
+
* Create a form and keep the same instance for the lifetime of the component.
|
|
784
|
+
* Options are read on the first render. Later renders ignore a new options object, except `values`,
|
|
785
|
+
* which resets the form when its content changes.
|
|
786
|
+
* The returned form is headless: nothing here imports a UI kit.
|
|
787
|
+
*
|
|
788
|
+
* `T` is inferred from `initialValues` / `values`. `getValue` / `setValue` / `batch` use that type.
|
|
789
|
+
* Submit values: no type argument drops `fields` paths whose display is `virtual` / `none`.
|
|
790
|
+
* `useForm<V>(options)` keeps the submit type as `V`. To keep `V` and still infer `fields`, call
|
|
791
|
+
* `typed<V>().useForm(options)`. An explicit second argument (`SubmitValues<V, …>`) is used as written.
|
|
792
|
+
* `useForm()`, `useForm(undefined)` and `useForm({})` are the same call: each returns a form and runs the same hooks.
|
|
793
|
+
* `typed(form)` gives the name-checked `Field` / `ArrayField` / `useField` / `useWatch` for this form.
|
|
794
|
+
* `fields` and `rows.*.name` templates validate even when the matching `<Field>` is not mounted.
|
|
795
|
+
*
|
|
796
|
+
* @example
|
|
797
|
+
* const form = useForm({
|
|
798
|
+
* initialValues: { email: '', rows: [{ name: '' }] },
|
|
799
|
+
* fields: { email: { required: true }, 'rows.*.name': { required: true } },
|
|
800
|
+
* })
|
|
801
|
+
* const edit = typed<Detail>().useForm({ values: record, fields: { token: { display: 'virtual' } } })
|
|
802
|
+
*/
|
|
803
|
+
type UseFormArg<T, F> = Omit<UseFormOptions<T>, 'fields'> & {
|
|
804
|
+
fields?: F & FieldsInput<T>;
|
|
805
|
+
};
|
|
806
|
+
declare function useForm<T = any, TSubmit = DefaultSubmit, const F extends FieldsInput<T> = {}>(options?: UseFormArg<T, F>): FormInstance<T, ResolveSubmit<T, TSubmit, F>>;
|
|
807
|
+
|
|
808
|
+
/** One rendered row. `key` is the row id, or a stable identity when the row has none. */
|
|
809
|
+
interface ArrayKey {
|
|
810
|
+
key: string;
|
|
811
|
+
index: number;
|
|
812
|
+
}
|
|
813
|
+
type ArrayHandle<TRow> = {
|
|
814
|
+
path: string;
|
|
815
|
+
keys: ArrayKey[];
|
|
816
|
+
push: (row: TRow) => void;
|
|
817
|
+
insert: (index: number, row: TRow) => void;
|
|
818
|
+
remove: (index: number) => void;
|
|
819
|
+
/** `to` is the final index. */
|
|
820
|
+
move: (from: number, to: number) => void;
|
|
821
|
+
swap: (indexA: number, indexB: number) => void;
|
|
822
|
+
replace: (index: number, row: TRow) => void;
|
|
823
|
+
/**
|
|
824
|
+
* HTML5 drag-and-drop props for row `index`: spread them on the row (drop target) and on its handle (drag source).
|
|
825
|
+
* Dropping row A on row B moves A to B's index. Stable per path; dragging does not re-render.
|
|
826
|
+
*/
|
|
827
|
+
dragProps: (index: number) => DragProps;
|
|
828
|
+
};
|
|
829
|
+
/**
|
|
830
|
+
* Array handle. Subscribes to row structure (length and ids), not to cell values.
|
|
831
|
+
* `keys` use the row id when the row has one, otherwise a stable object identity.
|
|
832
|
+
* `to` on `move` is the final index.
|
|
833
|
+
* `useArrayField<Values, 'rows'>('rows')` checks the name and types `push` / `replace` as one row.
|
|
834
|
+
* `useArrayField<Values>('rows')` only checks the name. A bare `useArrayField('rows')` accepts any row.
|
|
835
|
+
* Options are the second argument's object: `useArrayField('rows', { rowKey: 'id' })` (same shape as `useTreeField`).
|
|
836
|
+
*/
|
|
837
|
+
declare function useArrayField(name: string, opts?: {
|
|
838
|
+
rowKey?: string;
|
|
839
|
+
}): ArrayHandle<unknown>;
|
|
840
|
+
declare function useArrayField<TScope>(name: ArrayPath<TScope>, opts?: {
|
|
841
|
+
rowKey?: string;
|
|
842
|
+
}): ArrayHandle<unknown>;
|
|
843
|
+
declare function useArrayField<TScope, N extends ArrayPath<TScope>>(name: N, opts?: {
|
|
844
|
+
rowKey?: string;
|
|
845
|
+
}): ArrayHandle<ArrayItemOf<TScope, N & string>>;
|
|
846
|
+
/**
|
|
847
|
+
* The nearest enclosing array, no name needed (Formily `ArrayBase.useArray`): inside an `<ArrayField>` row or its container
|
|
848
|
+
* (`ArrayItems` / `ArrayCards` / `ArrayTable`, toolbar included), the same handle {@link useArrayField} returns for that array.
|
|
849
|
+
* Throws outside an array.
|
|
850
|
+
*
|
|
851
|
+
* ```tsx
|
|
852
|
+
* function RemoveButton() {
|
|
853
|
+
* const array = useArray()
|
|
854
|
+
* const index = useIndex()
|
|
855
|
+
* return <button onClick={() => array.remove(index)}>删除</button>
|
|
856
|
+
* }
|
|
857
|
+
* ```
|
|
858
|
+
*/
|
|
859
|
+
declare function useArray<TRow = unknown>(): ArrayHandle<TRow>;
|
|
860
|
+
/** {@link useArrayField} for an absolute path, without field-group registration (internal: containers, `useArrayTable`). */
|
|
861
|
+
declare function useArrayAt(path: string, rowKey?: string): ArrayHandle<unknown>;
|
|
862
|
+
/** This array path's own messages. Descendant fields are not included — those render on the row fields. */
|
|
863
|
+
interface ArrayErrors {
|
|
864
|
+
errors: readonly string[];
|
|
865
|
+
warnings: readonly string[];
|
|
866
|
+
}
|
|
867
|
+
/**
|
|
868
|
+
* The nearest array field's own validation messages (rules, schema, `form.setErrors` on that path).
|
|
869
|
+
* A child field's "必填" is not in here: `d.items.$errors` aggregates descendants, this does not.
|
|
870
|
+
* Subscribes to the array path only, so editing a cell does not re-render.
|
|
871
|
+
* Throws outside an `<ArrayField>`, like {@link useArray}.
|
|
872
|
+
*
|
|
873
|
+
* `ArrayItems` / `ArrayCards` render this under the rows. A custom list does the same:
|
|
874
|
+
*
|
|
875
|
+
* ```tsx
|
|
876
|
+
* function ListError() {
|
|
877
|
+
* const { errors } = useArrayErrors()
|
|
878
|
+
* if (!errors.length) return null
|
|
879
|
+
* return <p role="alert">{errors.join('、')}</p>
|
|
880
|
+
* }
|
|
881
|
+
* ```
|
|
882
|
+
*/
|
|
883
|
+
declare function useArrayErrors(): ArrayErrors;
|
|
884
|
+
|
|
885
|
+
/** React scope for relative field names. `path` is the index path of the parent object or row. */
|
|
886
|
+
interface ScopeValue {
|
|
887
|
+
path: string;
|
|
888
|
+
/** Row index inside its array, `-1` outside a row. */
|
|
889
|
+
index: number;
|
|
890
|
+
/** Row id (structure key) when a row component provided it. */
|
|
891
|
+
itemKey?: string;
|
|
892
|
+
/** Tree coordinate when a tree node provided it. */
|
|
893
|
+
pos?: readonly number[];
|
|
894
|
+
}
|
|
895
|
+
/** The nearest enclosing array (`<ArrayField>` and its container): its absolute path and row key. */
|
|
896
|
+
interface ArrayScopeValue {
|
|
897
|
+
path: string;
|
|
898
|
+
rowKey?: string;
|
|
899
|
+
}
|
|
900
|
+
declare const FormContext: react.Context<FormEngine<any, any> | null>;
|
|
901
|
+
declare const ScopeContext: react.Context<ScopeValue>;
|
|
902
|
+
declare const ArrayContext: react.Context<ArrayScopeValue | null>;
|
|
903
|
+
/**
|
|
904
|
+
* Internal: a container's per-row wrapper (`ArrayCards` puts each row in a card). `<ArrayField>` rows are memoized,
|
|
905
|
+
* so a container cannot rewrite them; it provides this and every row renders `wrap(rowContent)` inside its scope.
|
|
906
|
+
*/
|
|
907
|
+
declare const RowWrapContext: react.Context<((content: ReactNode) => ReactNode) | null>;
|
|
908
|
+
/** The form provided by `<Form>` (the same object `useForm()` returned). */
|
|
909
|
+
declare function useFormContext<T = any>(): FormInstance<T>;
|
|
910
|
+
/**
|
|
911
|
+
* Internal: the provided form's engine, or an error naming the caller (`useField('email')`, `<ArrayField name="items">`) and the fix.
|
|
912
|
+
* `useForm()` / `createForm()` only create the engine; it reaches fields through `<Form form={form}>`.
|
|
913
|
+
*/
|
|
914
|
+
declare function useRequiredForm<T = any>(caller: string): FormEngine<T>;
|
|
915
|
+
/** Parent path for `useField('price')` inside a row or object. */
|
|
916
|
+
declare function useScope(): ScopeValue;
|
|
917
|
+
|
|
918
|
+
/** What `<UI>` renders with: the node's effective state (reaction > JSX props > the scope's display / pattern). */
|
|
919
|
+
interface UiBinding {
|
|
920
|
+
/** The node name (`d.$ui(name)`). */
|
|
921
|
+
ui: string;
|
|
922
|
+
/** DOM id: `<prefix>-<scope>--<name>` (`<prefix>-ui--approvalTip` at the root). */
|
|
923
|
+
id: string;
|
|
924
|
+
display: UiDisplay;
|
|
925
|
+
pattern: Pattern;
|
|
926
|
+
title: ReactNode;
|
|
927
|
+
description: ReactNode;
|
|
928
|
+
component: ComponentType<any> | undefined;
|
|
929
|
+
decorator: ComponentType<any> | undefined;
|
|
930
|
+
componentProps: Record<string, any>;
|
|
931
|
+
decoratorProps: Record<string, any>;
|
|
932
|
+
}
|
|
933
|
+
/** `<UI>` props. A UI node has no value: nothing here is submitted or validated. */
|
|
934
|
+
interface UIProps<C extends ComponentType<any> = ComponentType<any>, D extends ComponentType<any> = ComponentType<any>> {
|
|
935
|
+
/** Addressed in effects as `d.$ui(name)` (inside a row / `<ObjectField>`: that scope's `row.$ui(name)`). */
|
|
936
|
+
name: UiName;
|
|
937
|
+
/** The component: `component={[Alert, { type: 'warning' }]}`, or a name registered on `<FieldKit>` / `<Form kit>`. Children render inside it. */
|
|
938
|
+
component?: FieldSlot<C> | RegisteredComponentSlot;
|
|
939
|
+
/** Wrapper (`decorator={[FormItem]}`: `title` → label, `description` → extra), or a registered decorator name. */
|
|
940
|
+
decorator?: FieldSlot<D> | RegisteredDecoratorSlot | false;
|
|
941
|
+
title?: ReactNode;
|
|
942
|
+
description?: ReactNode;
|
|
943
|
+
/** Initial display when no reaction wrote `$visible` / `$display` (default: the scope's). */
|
|
944
|
+
display?: UiDisplay;
|
|
945
|
+
/** Initial pattern when no reaction wrote `$pattern` (default: inherited from the scope / form). */
|
|
946
|
+
pattern?: Pattern;
|
|
947
|
+
/** Rendered inside `component` (or alone), or a render prop `(ui) => …`. */
|
|
948
|
+
children?: ReactNode | ((ui: UiBinding) => ReactNode);
|
|
949
|
+
}
|
|
950
|
+
/** Internal: the surrounding `<UI>`, or `null`. */
|
|
951
|
+
declare function useUiNodeOrNull(): UiBinding | null;
|
|
952
|
+
/**
|
|
953
|
+
* A UI with no data, addressed by name in effects: `d.$ui('approvalTip').$visible = d.amount.$value >= 50000`.
|
|
954
|
+
*
|
|
955
|
+
* ```tsx
|
|
956
|
+
* <UI name="approvalTip" component={[Alert, { type: 'warning', message: '金额 ≥ 5 万需要审批' }]} />
|
|
957
|
+
* ```
|
|
958
|
+
*
|
|
959
|
+
* `$visible` / `$display` / `$pattern` / `$title` / `$description` / `$componentProps` / `$decoratorProps`, same
|
|
960
|
+
* priority as a field's UI layer (reaction > these props). Hiding it unmounts its children but does **not** hide,
|
|
961
|
+
* skip or drop the fields inside: a field's validation and submit depend only on its own `$visible` / display.
|
|
962
|
+
*/
|
|
963
|
+
declare function UI<C extends ComponentType<any> = ComponentType<any>, D extends ComponentType<any> = ComponentType<any>>({ name, children, display, pattern, ...slots }: UIProps<C, D>): string | number | bigint | boolean | Iterable<ReactNode> | Promise<string | number | bigint | boolean | react.ReactPortal | react.ReactElement<unknown, string | react.JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | react.JSX.Element | null | undefined;
|
|
964
|
+
|
|
965
|
+
/**
|
|
966
|
+
* Index of the row this component renders in (Formily `ArrayBase.useIndex`), from the surrounding `RowScope`
|
|
967
|
+
* (`<ArrayField>` rows, `ArrayTable` cells included). Throws outside a row.
|
|
968
|
+
*/
|
|
969
|
+
declare function useIndex(): number;
|
|
970
|
+
/**
|
|
971
|
+
* Value of the row this component renders in (Formily `ArrayBase.useRecord`). Reactive: re-renders when any cell of
|
|
972
|
+
* this row changes, and follows the row when it moves. Throws outside a row (or tree node).
|
|
973
|
+
*/
|
|
974
|
+
declare function useRecord<TRow = any>(): TRow;
|
|
975
|
+
/**
|
|
976
|
+
* The tree node this component renders in: `path`, `pos`, `index` (last segment of `pos`), the reactive `record`,
|
|
977
|
+
* plus `move(from, to)` and `dragProps(pos)` — the same node operations the tree handle gives, bound to the tree the
|
|
978
|
+
* node belongs to (found by registering with the nearest tree, like `useArray()` does for arrays).
|
|
979
|
+
* A tree's nodes are rendered by the caller; wrap each node in `<RowScope path pos>` to provide it.
|
|
980
|
+
* Throws outside a node.
|
|
981
|
+
*/
|
|
982
|
+
declare function useTreeNode<TNode = any>(): {
|
|
983
|
+
path: string;
|
|
984
|
+
pos: Pos;
|
|
985
|
+
index: number;
|
|
986
|
+
record: TNode;
|
|
987
|
+
/** `to` is the final `pos`. Refuses a move into the node's own descendant. */
|
|
988
|
+
move: (from: Pos, to: Pos) => MoveResult;
|
|
989
|
+
/** HTML5 drag-and-drop props for the node at `pos` (default: this node). */
|
|
990
|
+
dragProps: (pos?: Pos) => DragProps;
|
|
991
|
+
};
|
|
992
|
+
|
|
993
|
+
/**
|
|
994
|
+
* A set of field paths collected from the JSX below a {@link FieldGroup}: every `<Field>` / `useField(name)` /
|
|
995
|
+
* `<ArrayField>` mounted inside registers its absolute path while mounted (nested groups register into every
|
|
996
|
+
* enclosing group). It owns no state of the form; it only answers "which fields are inside this region".
|
|
997
|
+
*
|
|
998
|
+
* Layout containers use it to badge a tab with the errors of its fields (`FormTab`, `FormCollapse`) and to validate
|
|
999
|
+
* one step (`FormStep`: `form.validate(group.paths())`). A pure-layout `FormItem` could aggregate its children's
|
|
1000
|
+
* errors the same way.
|
|
1001
|
+
*/
|
|
1002
|
+
interface FieldGroupHandle {
|
|
1003
|
+
/** Absolute paths mounted inside the group, in mount order. A path mounted twice is listed once. */
|
|
1004
|
+
paths(): string[];
|
|
1005
|
+
/** Called after a path is added or removed. */
|
|
1006
|
+
subscribe(listener: () => void): () => void;
|
|
1007
|
+
/** Bumped on every add / remove (a `useSyncExternalStore` snapshot). */
|
|
1008
|
+
version(): number;
|
|
1009
|
+
}
|
|
1010
|
+
/** Internal: the registry behind a {@link FieldGroupHandle}. */
|
|
1011
|
+
declare class FieldGroupStore implements FieldGroupHandle {
|
|
1012
|
+
private counts;
|
|
1013
|
+
private listeners;
|
|
1014
|
+
private ver;
|
|
1015
|
+
paths: () => string[];
|
|
1016
|
+
version: () => number;
|
|
1017
|
+
subscribe: (listener: () => void) => (() => void);
|
|
1018
|
+
/** Register `path` until the returned function runs. */
|
|
1019
|
+
add(path: string): () => void;
|
|
1020
|
+
private changed;
|
|
1021
|
+
}
|
|
1022
|
+
/** Create a group handle that lives as long as the component (pass it to {@link FieldGroup}). */
|
|
1023
|
+
declare function useFieldGroup(): FieldGroupHandle;
|
|
1024
|
+
/**
|
|
1025
|
+
* Collect the fields rendered inside `children` into `value` (from {@link useFieldGroup}). Renders no DOM.
|
|
1026
|
+
*
|
|
1027
|
+
* ```tsx
|
|
1028
|
+
* const group = useFieldGroup()
|
|
1029
|
+
* const errors = useFieldGroupErrors(group) // FieldError[] of the fields inside
|
|
1030
|
+
* <FieldGroup value={group}><Field name="a" … /><Field name="b" … /></FieldGroup>
|
|
1031
|
+
* await form.validate(group.paths()) // validate only those fields
|
|
1032
|
+
* ```
|
|
1033
|
+
*/
|
|
1034
|
+
declare function FieldGroup({ value, children }: {
|
|
1035
|
+
value: FieldGroupHandle;
|
|
1036
|
+
children?: ReactNode;
|
|
1037
|
+
}): react.JSX.Element;
|
|
1038
|
+
/** Internal: register `path` with the enclosing groups while mounted (`useField(name)`, `useArrayField`). */
|
|
1039
|
+
declare function useFieldGroupRegistration(path: string): void;
|
|
1040
|
+
/** Internal: the shown errors of each group (one entry per field with messages), re-rendering when they change. */
|
|
1041
|
+
declare function useGroupsErrors(form: FormEngine<any, any>, groups: readonly FieldGroupHandle[]): FieldError[][];
|
|
1042
|
+
/**
|
|
1043
|
+
* The errors of the fields inside a {@link FieldGroup}: one `{ path, messages }` per field with shown errors
|
|
1044
|
+
* (display `none` excluded), re-rendering only when that list changes. `errors.length` is a tab's badge count.
|
|
1045
|
+
*/
|
|
1046
|
+
declare function useFieldGroupErrors(group: FieldGroupHandle): FieldError[];
|
|
1047
|
+
|
|
1048
|
+
/**
|
|
1049
|
+
* Resolve built-in texts for the nearest form: its `messages` → `setDefaultMessages` → `zhCN`.
|
|
1050
|
+
* Outside a form only the app defaults apply. Component labels in `@shikiform/antd` read through this,
|
|
1051
|
+
* so a custom component can follow the same locale: `const t = useFormMessage(); t('submit')`.
|
|
1052
|
+
*/
|
|
1053
|
+
declare function useFormMessage(): <K extends FormMessageKey>(key: K, ...params: MessageArgs<K>) => string;
|
|
1054
|
+
|
|
1055
|
+
/**
|
|
1056
|
+
* Subscribe to the `$` reads inside `select`.
|
|
1057
|
+
* An unannotated draft compiles and is untyped (`useWatch((d) => d.$submitting)`, `d` is `any`).
|
|
1058
|
+
* Prefer the form's typed handle. `useWatch<Values>()(select)` types the draft and still infers the result
|
|
1059
|
+
* (`useWatch<Values>(select)` does not: one explicit type argument stops inference of the result).
|
|
1060
|
+
*
|
|
1061
|
+
* ```tsx
|
|
1062
|
+
* const F = typed(form)
|
|
1063
|
+
* const name = F.useWatch((d) => d.name.$value) // string
|
|
1064
|
+
* const email = useWatch<Values>()((d) => d.email.$value) // string
|
|
1065
|
+
* const can = useWatch((d: Draft<Values>) => d.$canSubmit) // boolean
|
|
1066
|
+
* ```
|
|
1067
|
+
* `select={(d) => d.email.$errors}` re-renders when that field's errors change.
|
|
1068
|
+
* `select={(d) => d.$canSubmit}` re-renders when submit, validation, or errors change, not on unrelated keystrokes.
|
|
1069
|
+
* Return data, not a new function. The snapshot is cached with {@link deepEqual}.
|
|
1070
|
+
*/
|
|
1071
|
+
declare function useWatch<T>(): <S>(select: (d: Draft<T>) => S) => S;
|
|
1072
|
+
declare function useWatch<T = any, S = unknown>(select: (d: Draft<T>) => S): S;
|
|
1073
|
+
|
|
1074
|
+
export { mapFieldProps as $, type ArrayContainerSlot as A, type BlurFlag as B, type CheckedFieldProps as C, Form as D, type FormDomProps as E, type FormSubmitHandlers as F, type FormProps as G, type PropsTransform as H, type RegisteredComponentSlot as I, type RegisteredDecoratorSlot as J, type RegisteredSlot as K, RowScope as L, type ScopeValue as M, UI as N, ObjectField as O, type PropsMapping as P, type UIProps as Q, type ResetState as R, type SubmitState as S, TreeField as T, type UseFieldOptions as U, type UiBinding as V, type UseResetOptions as W, type UseSubmitOptions as X, Watch as Y, connect as Z, mapBlur as _, type FieldProps as a, mapProps as a0, mapReadPretty as a1, useArray as a2, useArrayErrors as a3, useArrayField as a4, useField as a5, useFieldGroup as a6, useFieldGroupErrors as a7, useForm as a8, useFormContext as a9, useFormMessage as aa, useIndex as ab, useRecord as ac, useReset as ad, useSubmit as ae, useTreeField as af, useTreeNode as ag, useWatch as ah, ArrayContext as ai, type DragProps as aj, FieldGroupStore as ak, FormContext as al, type PropsEnhancer as am, type ReadPrettyEnhancer as an, RowWrapContext as ao, ScopeContext as ap, useArrayAt as aq, useFieldGroupRegistration as ar, useGroupsErrors as as, useRequiredForm as at, useScope as au, useUiNodeOrNull as av, valueFromEvent as aw, type ArrayKey as b, type FieldBinding as c, type ArrayHandle as d, type UseFormOptions as e, type ArrayErrors as f, ArrayField as g, ArrayScope as h, type ArrayScopeValue as i, type BlurOn as j, type ClickEvent as k, type ComponentStatics as l, type ConnectEnhancer as m, type ConnectFieldProps as n, type ConnectedComponent as o, Field as p, type FieldComponents as q, type FieldDecorators as r, FieldGroup as s, type FieldGroupHandle as t, FieldKit as u, type FieldKitDecorator as v, type FieldKitSpec as w, type FieldPropKey as x, type FieldSlot as y, type FieldStateKey as z };
|