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