@shikiform/react 0.1.0 → 0.3.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/dist/{chunk-EYDJ6I7P.js → chunk-A54EUYGM.js} +318 -133
- package/dist/chunk-A54EUYGM.js.map +1 -0
- package/dist/index.d.ts +23 -25
- package/dist/index.js +10 -7
- package/dist/index.js.map +1 -1
- package/dist/internal.d.ts +92 -4
- package/dist/internal.js +1 -1
- package/dist/{use-watch-BZlpyvHw.d.ts → use-watch-BJDsp7Zo.d.ts} +220 -229
- package/package.json +2 -2
- package/dist/chunk-EYDJ6I7P.js.map +0 -1
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import * as react from 'react';
|
|
2
|
-
import { ComponentType, ReactNode, ComponentProps,
|
|
3
|
-
import {
|
|
2
|
+
import { ComponentType, ReactNode, ComponentProps, FormHTMLAttributes, FunctionComponent, ComponentClass, ForwardRefExoticComponent, Ref, DragEvent } from 'react';
|
|
3
|
+
import { EnumOption, UiName, FieldEnum, RulesInput, FieldPath, PathValue, ArrayPath, FieldError, FormInstance, Pos, Draft, FormOptions, DefaultSubmit, FieldsInput, ResolveSubmit, ArrayItemOf, FormEngine, MoveResult } from '@shikiform/core/internal';
|
|
4
4
|
|
|
5
5
|
/**
|
|
6
6
|
* Register the controls your app passes to `<Field component="Input">` (module augmentation):
|
|
@@ -71,11 +71,15 @@ interface FieldBinding<TValue> {
|
|
|
71
71
|
onBlur(): void;
|
|
72
72
|
errors: string[];
|
|
73
73
|
warnings: string[];
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
74
|
+
/** Effective render flag (OR-inherited). `false` does not render; the value is still submitted unless `omit`. */
|
|
75
|
+
visible: boolean;
|
|
76
|
+
/** Effective disabled (OR-inherited). The preview wins when `readOnly` is also set. */
|
|
77
77
|
disabled: boolean;
|
|
78
|
+
/** Effective read-only (OR-inherited). Renders the preview. Wins over `disabled`. */
|
|
78
79
|
readOnly: boolean;
|
|
80
|
+
/** This field is left out of submit. Not inherited. */
|
|
81
|
+
omit: boolean;
|
|
82
|
+
required: boolean;
|
|
79
83
|
/** True after blur. `reset` clears it. */
|
|
80
84
|
touched: boolean;
|
|
81
85
|
/** The value differs from its initial value (deep compare). Changing it back clears it. */
|
|
@@ -101,10 +105,14 @@ interface FieldBinding<TValue> {
|
|
|
101
105
|
decoratorProps: Record<string, any>;
|
|
102
106
|
/**
|
|
103
107
|
* 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;
|
|
108
|
+
* errors and `onChange` are the field's; visible, disabled, readOnly, title, props and `id` (`<prefix>-<path>--<ui>`) are the instance's.
|
|
105
109
|
*/
|
|
106
110
|
ui?: string;
|
|
107
111
|
}
|
|
112
|
+
/**
|
|
113
|
+
* 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).
|
|
114
|
+
*/
|
|
115
|
+
declare const FieldContext: react.Context<FieldBinding<any> | null>;
|
|
108
116
|
/**
|
|
109
117
|
* A `component` / `decorator` slot: the component, or `[Component, props]` (Formily style). On `<Field>` / `typed().Field`
|
|
110
118
|
* / `row.Field` / `<UI>`, `C` is inferred from the component and the props are checked against it (all optional: the field
|
|
@@ -160,14 +168,14 @@ type RegisteredDecoratorSlot = RegisteredSlot<FieldDecorators>;
|
|
|
160
168
|
/**
|
|
161
169
|
* Field options a hook caller can pass. Same semantics as the `<Field>` props of the same name:
|
|
162
170
|
* `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`). `
|
|
171
|
+
* restoring a declaration, item template, or `$rules`). `visible` / `disabled` / `readOnly` / `omit` are the same lease.
|
|
164
172
|
*/
|
|
165
173
|
interface UseFieldOptions<TValue = any> {
|
|
166
174
|
/**
|
|
167
175
|
* 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
|
|
169
|
-
* `d.amount.$ui('slider')` (unset falls back to the field
|
|
170
|
-
* `rules` / `required` / `enum` belong on the field itself (the `<Field>` without `ui`).
|
|
176
|
+
* Shares the value, errors and rules; has its own visible / disabled / readOnly / title / props, addressed in effects as
|
|
177
|
+
* `d.amount.$ui('slider')` (unset falls back to the field). Own DOM id `<prefix>-<path>--<ui>`.
|
|
178
|
+
* `rules` / `required` / `enum` / `omit` belong on the field itself (the `<Field>` without `ui`).
|
|
171
179
|
*/
|
|
172
180
|
ui?: UiName;
|
|
173
181
|
/**
|
|
@@ -178,9 +186,14 @@ interface UseFieldOptions<TValue = any> {
|
|
|
178
186
|
enum?: FieldEnum<TValue>;
|
|
179
187
|
rules?: RulesInput<TValue>;
|
|
180
188
|
required?: boolean;
|
|
181
|
-
/** `
|
|
182
|
-
|
|
183
|
-
|
|
189
|
+
/** `false` does not render. Inherited (OR); explicit `false` exits a shown parent. Still submitted unless `omit`. */
|
|
190
|
+
visible?: boolean;
|
|
191
|
+
/** Gray the control out. Inherited (OR); explicit `false` exits. Skips validation. */
|
|
192
|
+
disabled?: boolean;
|
|
193
|
+
/** Render the preview. Inherited (OR); explicit `false` exits. Wins over `disabled`. Skips validation. */
|
|
194
|
+
readOnly?: boolean;
|
|
195
|
+
/** Leave this field out of submit. Not inherited. */
|
|
196
|
+
omit?: boolean;
|
|
184
197
|
/**
|
|
185
198
|
* UI state, the render-time JSX layer: not stored on the model, so inline objects and handlers are free.
|
|
186
199
|
* A reaction (`$title`, `$componentProps.x = …`) wins over it; it wins over `fields` declarations.
|
|
@@ -218,39 +231,17 @@ declare function useField(name: string, options?: UseFieldOptions): FieldBinding
|
|
|
218
231
|
declare function useField<TScope>(name: FieldPath<TScope>, options?: UseFieldOptions<PathValue<TScope, FieldPath<TScope> & string>>): FieldBinding<PathValue<TScope, FieldPath<TScope> & string>>;
|
|
219
232
|
declare function useField<TScope, N extends FieldPath<TScope>>(name: N, options?: UseFieldOptions<PathValue<TScope, N & string>>): FieldBinding<PathValue<TScope, N & string>>;
|
|
220
233
|
|
|
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
234
|
/** Submit callbacks of `<Form>` (and the antd `Submit` button's own `onSubmit`). */
|
|
246
235
|
interface FormSubmitHandlers<T> {
|
|
247
236
|
/** Called with the submit values after validation passes. May be async; the submit waits for it. */
|
|
248
237
|
onSubmit?: (values: T) => void | Promise<void>;
|
|
249
|
-
/** Called with the errors when validation fails (`
|
|
238
|
+
/** Called with the errors when validation fails (`submit` / `validate` reject `FieldError[]`). */
|
|
250
239
|
onInvalid?: (errors: FieldError[]) => void;
|
|
251
240
|
/**
|
|
252
|
-
* Called when `onSubmit` (or a form-level `validate`) throws or rejects
|
|
241
|
+
* Called when `onSubmit` (or a form-level `validate`) throws or rejects.
|
|
253
242
|
* Without it the error is reported with `console.error`; it never becomes an unhandled rejection.
|
|
243
|
+
* Includes `SubmitUnstableError` (values never settled). A `SubmitSupersededError` is swallowed:
|
|
244
|
+
* the newer submit owns that outcome.
|
|
254
245
|
*/
|
|
255
246
|
onSubmitError?: (error: unknown) => void;
|
|
256
247
|
}
|
|
@@ -275,8 +266,8 @@ type FormProps<T, TSubmit = T> = FormSubmitHandlers<TSubmit> & FormDomProps & {
|
|
|
275
266
|
* Field DOM ids are prefixed with this form's `id`, or with React `useId()` when `id` is omitted, so two forms
|
|
276
267
|
* do not share `id="email"`. The engine's `binding().id` stays the sanitized path (`user.name` → `user-name`);
|
|
277
268
|
* the control's id is `<prefix>-user-name`.
|
|
278
|
-
* `<Field>` returns null
|
|
279
|
-
* `
|
|
269
|
+
* `<Field>` returns null when `visible` is false after subscribing, so a mounted model stays registered.
|
|
270
|
+
* `omit` still renders: the value is left out of submit only.
|
|
280
271
|
* A field declared on the form, or given `$rules` / `registerField`, still validates when this component is not rendered.
|
|
281
272
|
*/
|
|
282
273
|
declare function Form<T, TSubmit = T>({ form, children, onSubmit, onInvalid, onSubmitError, id, kit, ...rest }: FormProps<T, TSubmit>): react.JSX.Element;
|
|
@@ -285,9 +276,9 @@ interface FieldProps<TScope = any, N extends FieldPath<TScope> = FieldPath<TScop
|
|
|
285
276
|
/** Name relative to the current `<ObjectField>` / `<ArrayField>` / `<TreeField>` scope. */
|
|
286
277
|
name: N;
|
|
287
278
|
/**
|
|
288
|
-
* Another UI of the same field (`d.name.$ui('echo')` in effects): shared value / errors / rules, its own
|
|
289
|
-
*
|
|
290
|
-
* enum to the `<Field>` without `ui`.
|
|
279
|
+
* Another UI of the same field (`d.name.$ui('echo')` in effects): shared value / errors / rules, its own visible /
|
|
280
|
+
* disabled / readOnly, title and props (unset falls back to the field's). Own DOM id `<prefix>-<path>--<ui>`.
|
|
281
|
+
* Leave rules / required / enum / omit to the `<Field>` without `ui`.
|
|
291
282
|
*/
|
|
292
283
|
ui?: UiName;
|
|
293
284
|
/**
|
|
@@ -295,20 +286,21 @@ interface FieldProps<TScope = any, N extends FieldPath<TScope> = FieldPath<TScop
|
|
|
295
286
|
* Option values are typed against the field value (its element type for an array field) when the name is typed
|
|
296
287
|
* (`typed(form).Field`, `row.Field`). Wins over `fields.x.enum` while mounted; a reaction's `$enum` wins over it.
|
|
297
288
|
* Changing the prop re-applies it; unmount restores the declared enum. Select / Radio / Checkbox.Group and their
|
|
298
|
-
*
|
|
289
|
+
* read-only previews read it as `options`.
|
|
299
290
|
*/
|
|
300
291
|
enum?: FieldEnum<PathValue<TScope, N & string>>;
|
|
301
292
|
/** Mount-scoped rules. Cleared on unmount. Does not erase a declaration, a template, or `$rules`. `validator` receives this field's value. */
|
|
302
293
|
rules?: RulesInput<PathValue<TScope, N & string>>;
|
|
303
294
|
/** Mount-scoped required flag. Cleared on unmount. A declared or `$required` flag stays. */
|
|
304
295
|
required?: boolean;
|
|
305
|
-
/**
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
296
|
+
/** `false` does not render. Inherited (OR). Still submitted unless `omit`. On `<Field ui>` this is the instance's. */
|
|
297
|
+
visible?: boolean;
|
|
298
|
+
/** Gray the control out. Inherited (OR). Skips validation. Still submitted. */
|
|
299
|
+
disabled?: boolean;
|
|
300
|
+
/** Render the preview. Inherited (OR). Wins over `disabled`. Skips validation. Still submitted. */
|
|
301
|
+
readOnly?: boolean;
|
|
302
|
+
/** Leave this field out of submit. Not inherited. On `<Field ui>` this is ignored (it belongs to the field). */
|
|
303
|
+
omit?: boolean;
|
|
312
304
|
/** Decorator label (`FormItem` shows it as `label`). A reaction's `$title` wins. */
|
|
313
305
|
title?: ReactNode;
|
|
314
306
|
/** Decorator help text (`FormItem` shows it as `extra`). A reaction's `$description` wins. */
|
|
@@ -345,23 +337,31 @@ type CheckedFieldProps<TScope = any, N extends FieldPath<TScope> = FieldPath<TSc
|
|
|
345
337
|
*
|
|
346
338
|
* `rules` may be a built-in rule, a Standard Schema, or a mix. JSX `rules` and `required` apply only while this
|
|
347
339
|
* component is mounted; unmount restores rules from `useForm({ fields })`, `registerField`, an item template, or `$rules`.
|
|
348
|
-
* `
|
|
349
|
-
* `
|
|
340
|
+
* `visible={false}` does not render and skips validation; the value is still submitted unless `omit`.
|
|
341
|
+
* `readOnly` renders the preview and skips validation. `omit` leaves the value out of submit.
|
|
342
|
+
* `<Field<Row> name="price">` checks the name.
|
|
350
343
|
* `<Field<Row, 'price'> name="price">` types the value.
|
|
351
|
-
* `<Field>` is a thin wrapper around {@link useField}: `useField(name, options)` +
|
|
352
|
-
* + the two slots. `
|
|
344
|
+
* `<Field>` is a thin wrapper around {@link useField}: `useField(name, options)` + `visible === false` → `null`
|
|
345
|
+
* + the two slots. `omit` still renders.
|
|
353
346
|
*/
|
|
354
347
|
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
348
|
/**
|
|
356
349
|
* Scope child names under an object path. Does not subscribe to child values.
|
|
357
|
-
* `
|
|
358
|
-
*
|
|
350
|
+
* `omit` leaves this object out of submit (`getSubmitValues`; nested keys go with it). `omit` does not inherit,
|
|
351
|
+
* so list the object in `useForm({ fields })` when the omission must hold before this component mounts.
|
|
352
|
+
* `visible` / `disabled` / `readOnly` are inherited by the fields inside (OR; a child `false` exits).
|
|
359
353
|
* `<ObjectField<Values> name="address">` checks the name; `typed(form).ObjectField` also types the children.
|
|
360
354
|
*/
|
|
361
|
-
declare function ObjectField<TScope = any>({ name,
|
|
355
|
+
declare function ObjectField<TScope = any>({ name, visible, disabled, readOnly, omit, children, }: {
|
|
362
356
|
name: FieldPath<TScope>;
|
|
363
|
-
/** `
|
|
364
|
-
|
|
357
|
+
/** `false` hides this object and, by inheritance, the fields inside. Explicit `false` on a child exits. */
|
|
358
|
+
visible?: boolean;
|
|
359
|
+
/** Disables this object and, by inheritance, the fields inside. */
|
|
360
|
+
disabled?: boolean;
|
|
361
|
+
/** Read-only preview for this object and, by inheritance, the fields inside. */
|
|
362
|
+
readOnly?: boolean;
|
|
363
|
+
/** Leave this object out of submit. Not inherited; nested keys disappear with the object. */
|
|
364
|
+
omit?: boolean;
|
|
365
365
|
children?: ReactNode;
|
|
366
366
|
}): react.JSX.Element;
|
|
367
367
|
/**
|
|
@@ -371,7 +371,7 @@ declare function ObjectField<TScope = any>({ name, display, children, }: {
|
|
|
371
371
|
* Names inside a row are relative to the row (`name="price"`, not `items.0.price`).
|
|
372
372
|
* `component` is the container around the rows (Formily `ArrayItems` / `ArrayCards` / `ArrayTable` in
|
|
373
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
|
|
374
|
+
* `<ArrayItems …>{rows}</ArrayItems>` inside the array's scope, so its buttons reach the array through {@link useArrayField}.
|
|
375
375
|
* A container that renders its own cells (`ArrayTable` with `columns`) needs no `children`.
|
|
376
376
|
* `virtualScroll` windows the plain rows (TanStack Virtual); it does not combine with a container `component`.
|
|
377
377
|
* `<ArrayField<Values> name="items">` checks the name; `typed(form).ArrayField` also types the row's fields.
|
|
@@ -399,17 +399,27 @@ declare function ArrayField<TScope = any, C extends ComponentType<any> = Compone
|
|
|
399
399
|
}) => ReactNode;
|
|
400
400
|
}): react.JSX.Element;
|
|
401
401
|
/**
|
|
402
|
-
* Mark the nearest array for {@link
|
|
403
|
-
* array component built on `useArrayField`.
|
|
402
|
+
* Mark the nearest array for {@link useArrayField} (`path` is absolute). `<ArrayField>` renders it; use it in a custom
|
|
403
|
+
* array component built on `useArrayField(name)`.
|
|
404
404
|
*/
|
|
405
405
|
declare function ArrayScope({ path, rowKey, children }: {
|
|
406
406
|
path: string;
|
|
407
407
|
rowKey?: string;
|
|
408
408
|
children?: ReactNode;
|
|
409
409
|
}): react.JSX.Element;
|
|
410
|
+
/**
|
|
411
|
+
* Mark the nearest tree for {@link useTreeField} (`path` is absolute). `<TreeField>` renders it.
|
|
412
|
+
* `childrenKey` / `rowKey` stay unset when the caller omitted them, so a prior `trees` registration is kept.
|
|
413
|
+
*/
|
|
414
|
+
declare function TreeScope({ path, childrenKey, rowKey, children, }: {
|
|
415
|
+
path: string;
|
|
416
|
+
childrenKey?: string;
|
|
417
|
+
rowKey?: string;
|
|
418
|
+
children?: ReactNode;
|
|
419
|
+
}): react.JSX.Element;
|
|
410
420
|
/**
|
|
411
421
|
* Scope for one row (or tree node): relative names resolve under `path`, and {@link useIndex} / {@link useRecord}
|
|
412
|
-
* (/ {@link
|
|
422
|
+
* (/ {@link useTreeField} with `pos`) read it. Stable value, so a row that did not move does not wake its consumers.
|
|
413
423
|
* For a tree node pass `pos` (and `index` = its last segment, or omit `index`).
|
|
414
424
|
*/
|
|
415
425
|
declare function RowScope({ path, index, itemKey, pos, children, }: {
|
|
@@ -421,13 +431,32 @@ declare function RowScope({ path, index, itemKey, pos, children, }: {
|
|
|
421
431
|
pos?: Pos;
|
|
422
432
|
children?: ReactNode;
|
|
423
433
|
}): react.JSX.Element;
|
|
424
|
-
/**
|
|
434
|
+
/** Rendered tree node passed to `<TreeField>{(node) => …}</TreeField>`. */
|
|
435
|
+
interface TreeNodeRender {
|
|
436
|
+
path: string;
|
|
437
|
+
pos: Pos;
|
|
438
|
+
index: number;
|
|
439
|
+
key: string;
|
|
440
|
+
depth: number;
|
|
441
|
+
children: ReactNode;
|
|
442
|
+
}
|
|
443
|
+
/**
|
|
444
|
+
* The owner of a tree path. Walks the tree recursively, wraps each node in a row scope keyed by the node id
|
|
445
|
+
* (`rowKey`, else `id`, else a stable object identity), and hands `children` the pre-rendered subtree as `node.children`
|
|
446
|
+
* (`null` on leaves) so the caller decides where to place it (`<li><NodeRow />{node.children && <ul>{node.children}</ul>}</li>`).
|
|
447
|
+
* A move re-renders the moved node, nodes whose `pos` changed, and ancestors whose subtree changed.
|
|
448
|
+
* A sibling whose position and subtree did not change, and every other subtree, keep the previous element and do not re-render.
|
|
449
|
+
* The `children` render function is part of that identity: a new function (an inline callback while the parent re-renders) redraws every node.
|
|
450
|
+
* Inside a node, relative `<Field name="name">` / `useField('name')`, {@link useRecord}, and {@link useTreeField}
|
|
451
|
+
* (no name: this node, plus the tree's edits) read that node, and field state / errors follow the node across moves.
|
|
452
|
+
* `<TreeField<Values> name="menu">` checks the name; `typed(form).TreeField` also types the node's fields.
|
|
453
|
+
*/
|
|
425
454
|
declare function TreeField<TScope = any>({ name, childrenKey, rowKey, children, }: {
|
|
426
455
|
name: ArrayPath<TScope>;
|
|
427
456
|
childrenKey?: string;
|
|
428
457
|
rowKey?: string;
|
|
429
|
-
children: (
|
|
430
|
-
}):
|
|
458
|
+
children: (node: TreeNodeRender) => ReactNode;
|
|
459
|
+
}): react.JSX.Element;
|
|
431
460
|
/**
|
|
432
461
|
* Render `children` with the current selector value. Same selectors and typing as {@link useWatch}:
|
|
433
462
|
* an unannotated `select={(d) => d.$canSubmit}` compiles (`d` is untyped); `typed(form).Watch` or
|
|
@@ -525,7 +554,7 @@ type FieldPropKey = 'value' | 'onChange' | 'onBlur' | 'disabled' | 'readOnly' |
|
|
|
525
554
|
* Any other field state a `mapProps` object can hand to a prop (Formily: the key is a field path):
|
|
526
555
|
* `{ title: 'placeholder' }`, `{ required: 'aria-required' }`, `{ 'componentProps.max': 'count' }`.
|
|
527
556
|
*/
|
|
528
|
-
type FieldStateKey = 'title' | 'description' | 'required' | 'validating' | 'touched' | 'dirty' | 'edited' | '
|
|
557
|
+
type FieldStateKey = 'title' | 'description' | 'required' | 'validating' | 'touched' | 'dirty' | 'edited' | 'visible' | 'disabled' | 'readOnly' | 'omit' | 'path' | 'errors' | 'warnings' | `componentProps.${string}` | `decoratorProps.${string}`;
|
|
529
558
|
/**
|
|
530
559
|
* Where blur validation goes when the control has no `onBlur` (a Lobe Select, a popover picker).
|
|
531
560
|
* Without this, `validateTrigger: 'onBlur'` never runs because the `onBlur` prop is ignored.
|
|
@@ -543,7 +572,7 @@ type BlurOn = 'onChange' | 'onOpenChange' | {
|
|
|
543
572
|
* more field state to a prop (`{ title: 'placeholder' }`; an explicit caller prop wins).
|
|
544
573
|
* `format` / `parse` convert between the field value and the control value (a `'YYYY-MM-DD'` string in the field,
|
|
545
574
|
* 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`, …). `
|
|
575
|
+
* transforms, so it sees the control's own props (`props.format`, …). The `readOnly` preview is not converted: the view gets
|
|
547
576
|
* the field value.
|
|
548
577
|
* `blurOn` is the blur fallback for a control that does not call `onBlur` ({@link BlurOn}). It replaces the default
|
|
549
578
|
* `onBlur` prop so the unused handler is not passed through.
|
|
@@ -558,6 +587,8 @@ type PropsMapping<P = any, F = any> = Partial<Record<FieldPropKey | FieldStateKe
|
|
|
558
587
|
/** Control `onChange` arguments → the value stored on the field. Default: {@link valueFromEvent}. */
|
|
559
588
|
parse?: ParseFn<P, F>;
|
|
560
589
|
blurOn?: BlurOn;
|
|
590
|
+
/** Component rendered when the field is `readOnly` (the preview). A tuple's props are its defaults. */
|
|
591
|
+
preview?: ComponentType<any> | readonly [ComponentType<any>, Record<string, unknown>?];
|
|
561
592
|
};
|
|
562
593
|
/** `true` when `P` is `any` (not a concrete props type). `unknown` is not `any`. */
|
|
563
594
|
type IsAny<T> = 0 extends 1 & T ? true : false;
|
|
@@ -601,13 +632,12 @@ type PropsEnhancer = {
|
|
|
601
632
|
transforms: PropsTransform[];
|
|
602
633
|
/** Present when this mapping names a blur fallback, renames `onBlur`, or drops it on purpose. */
|
|
603
634
|
blur?: BlurFlag;
|
|
635
|
+
preview?: {
|
|
636
|
+
component: ComponentType<any>;
|
|
637
|
+
props?: Record<string, unknown>;
|
|
638
|
+
};
|
|
604
639
|
};
|
|
605
|
-
type
|
|
606
|
-
kind: 'readPretty';
|
|
607
|
-
component: ComponentType<any>;
|
|
608
|
-
props?: Record<string, unknown>;
|
|
609
|
-
};
|
|
610
|
-
type ConnectEnhancer = PropsEnhancer | ReadPrettyEnhancer;
|
|
640
|
+
type ConnectEnhancer = PropsEnhancer;
|
|
611
641
|
/** Props every connected control accepts besides its own. */
|
|
612
642
|
interface ConnectFieldProps {
|
|
613
643
|
/** Field name relative to the current scope. Omit it inside a `<Field>`, which supplies the field. */
|
|
@@ -626,27 +656,6 @@ type ComponentStatics<C> = Omit<C, keyof FunctionComponent<any> | keyof Componen
|
|
|
626
656
|
* `target.value` otherwise; anything else (a number, an array, `null`) is the value itself.
|
|
627
657
|
*/
|
|
628
658
|
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
659
|
/** A mapping that does not convert values. `format` / `parse` take the codec overload so `connect` can check them. */
|
|
651
660
|
type MapArg = Omit<PropsMapping, 'format' | 'parse'> | PropsTransform;
|
|
652
661
|
type BlurFrom<A extends readonly unknown[]> = A extends readonly [infer H, ...infer R] ? H extends {
|
|
@@ -676,7 +685,6 @@ type MapPropsResult<A extends readonly unknown[]> = [
|
|
|
676
685
|
* ```
|
|
677
686
|
*
|
|
678
687
|
* `blurOn` keeps `validateTrigger: 'onBlur'` alive when the control never calls `onBlur`.
|
|
679
|
-
* `mapBlur('onOpenChange')` is the same decision as its own enhancer.
|
|
680
688
|
* Put `format` / `parse` on the first object so `connect` can check them against the control.
|
|
681
689
|
*/
|
|
682
690
|
type CodecMapping<P, F> = PropsMapping<P, F> & ({
|
|
@@ -686,22 +694,6 @@ type CodecMapping<P, F> = PropsMapping<P, F> & ({
|
|
|
686
694
|
});
|
|
687
695
|
declare function mapProps<P, F>(mapping: CodecMapping<P, F>, ...rest: Array<PropsMapping<P, F> | PropsTransform>): CodecEnhancer<P, F>;
|
|
688
696
|
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
697
|
/**
|
|
706
698
|
* Props of a component, from its call signature. `unknown` when the signature can't be read
|
|
707
699
|
* (then blur is not required — a typed `onBlur` is what the check can see).
|
|
@@ -717,7 +709,7 @@ type AnyBlur<E extends readonly unknown[]> = E extends readonly [infer H, ...inf
|
|
|
717
709
|
blur: BlurFlag;
|
|
718
710
|
} ? true : AnyBlur<R> : false;
|
|
719
711
|
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? } })
|
|
712
|
+
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.';
|
|
721
713
|
};
|
|
722
714
|
type BlurTarget<C, E extends readonly unknown[]> = HasOnBlurProp<C> extends true ? C : AnyBlur<E> extends true ? C : DemandBlur<C>;
|
|
723
715
|
type ValueOfProps<C> = C extends ComponentType<infer P> ? (P extends {
|
|
@@ -744,7 +736,7 @@ type NoCodec<E> = E extends {
|
|
|
744
736
|
* (so `$componentProps.placeholder = …` in a reaction reaches the control).
|
|
745
737
|
*
|
|
746
738
|
* A control whose props type has no `onBlur` must say where blur validation goes
|
|
747
|
-
* (`mapProps({ blurOn })` /
|
|
739
|
+
* (`mapProps({ blurOn })` / `mapProps({ onBlur: false })`). Otherwise `validateTrigger: 'onBlur'`
|
|
748
740
|
* would never run and TypeScript would not complain. `blurOn: 'onOpenChange'` treats a popup close (`false`) as blur;
|
|
749
741
|
* `blurOn: 'onChange'` blurs after every change.
|
|
750
742
|
*
|
|
@@ -786,7 +778,7 @@ interface UseFormOptions<T> extends FormOptions<T> {
|
|
|
786
778
|
* The returned form is headless: nothing here imports a UI kit.
|
|
787
779
|
*
|
|
788
780
|
* `T` is inferred from `initialValues` / `values`. `getValue` / `setValue` / `batch` use that type.
|
|
789
|
-
* Submit values: no type argument drops `fields` paths
|
|
781
|
+
* Submit values: no type argument drops `fields` paths with `omit: true`.
|
|
790
782
|
* `useForm<V>(options)` keeps the submit type as `V`. To keep `V` and still infer `fields`, call
|
|
791
783
|
* `typed<V>().useForm(options)`. An explicit second argument (`SubmitValues<V, …>`) is used as written.
|
|
792
784
|
* `useForm()`, `useForm(undefined)` and `useForm({})` are the same call: each returns a form and runs the same hooks.
|
|
@@ -798,13 +790,21 @@ interface UseFormOptions<T> extends FormOptions<T> {
|
|
|
798
790
|
* initialValues: { email: '', rows: [{ name: '' }] },
|
|
799
791
|
* fields: { email: { required: true }, 'rows.*.name': { required: true } },
|
|
800
792
|
* })
|
|
801
|
-
* const edit = typed<Detail>().useForm({ values: record, fields: { token: {
|
|
793
|
+
* const edit = typed<Detail>().useForm({ values: record, fields: { token: { omit: true } } })
|
|
802
794
|
*/
|
|
803
795
|
type UseFormArg<T, F> = Omit<UseFormOptions<T>, 'fields'> & {
|
|
804
796
|
fields?: F & FieldsInput<T>;
|
|
805
797
|
};
|
|
806
798
|
declare function useForm<T = any, TSubmit = DefaultSubmit, const F extends FieldsInput<T> = {}>(options?: UseFormArg<T, F>): FormInstance<T, ResolveSubmit<T, TSubmit, F>>;
|
|
807
799
|
|
|
800
|
+
/** HTML5 drag-and-drop props for one row / node: the same object serves as drag source and drop target. */
|
|
801
|
+
interface DragProps {
|
|
802
|
+
draggable: true;
|
|
803
|
+
onDragStart: (event: DragEvent) => void;
|
|
804
|
+
onDragOver: (event: DragEvent) => void;
|
|
805
|
+
onDrop: (event: DragEvent) => void;
|
|
806
|
+
}
|
|
807
|
+
|
|
808
808
|
/** One rendered row. `key` is the row id, or a stable identity when the row has none. */
|
|
809
809
|
interface ArrayKey {
|
|
810
810
|
key: string;
|
|
@@ -825,15 +825,34 @@ type ArrayHandle<TRow> = {
|
|
|
825
825
|
* Dropping row A on row B moves A to B's index. Stable per path; dragging does not re-render.
|
|
826
826
|
*/
|
|
827
827
|
dragProps: (index: number) => DragProps;
|
|
828
|
+
/** This array path's own messages. Descendant fields are not included. */
|
|
829
|
+
errors: readonly string[];
|
|
830
|
+
warnings: readonly string[];
|
|
828
831
|
};
|
|
829
832
|
/**
|
|
830
833
|
* Array handle. Subscribes to row structure (length and ids), not to cell values.
|
|
831
834
|
* `keys` use the row id when the row has one, otherwise a stable object identity.
|
|
832
835
|
* `to` on `move` is the final index.
|
|
836
|
+
*
|
|
837
|
+
* `useArrayField()` is the nearest `<ArrayField>` (Formily `ArrayBase.useArray`): a row, or the container
|
|
838
|
+
* (`ArrayItems` / `ArrayCards` / `ArrayTable`, toolbar included). Nested arrays resolve to the inner one.
|
|
839
|
+
* Outside an array it throws.
|
|
840
|
+
*
|
|
841
|
+
* `useArrayField(name)` resolves `name` against the current scope (a repeated scope prefix throws in development),
|
|
842
|
+
* registers that path into the nearest `FieldGroup`, and returns the same handle.
|
|
833
843
|
* `useArrayField<Values, 'rows'>('rows')` checks the name and types `push` / `replace` as one row.
|
|
834
844
|
* `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' })
|
|
845
|
+
* Options are the second argument's object: `useArrayField('rows', { rowKey: 'id' })`.
|
|
846
|
+
*
|
|
847
|
+
* ```tsx
|
|
848
|
+
* function RemoveButton() {
|
|
849
|
+
* const array = useArrayField()
|
|
850
|
+
* const index = useIndex()
|
|
851
|
+
* return <button onClick={() => array.remove(index)}>删除</button>
|
|
852
|
+
* }
|
|
853
|
+
* ```
|
|
836
854
|
*/
|
|
855
|
+
declare function useArrayField<TRow = unknown>(): ArrayHandle<TRow>;
|
|
837
856
|
declare function useArrayField(name: string, opts?: {
|
|
838
857
|
rowKey?: string;
|
|
839
858
|
}): ArrayHandle<unknown>;
|
|
@@ -843,44 +862,13 @@ declare function useArrayField<TScope>(name: ArrayPath<TScope>, opts?: {
|
|
|
843
862
|
declare function useArrayField<TScope, N extends ArrayPath<TScope>>(name: N, opts?: {
|
|
844
863
|
rowKey?: string;
|
|
845
864
|
}): ArrayHandle<ArrayItemOf<TScope, N & string>>;
|
|
846
|
-
/**
|
|
847
|
-
|
|
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>;
|
|
865
|
+
/** {@link useArrayField} for an absolute path, without field-group registration (internal: containers, `useArrayTable`). `null` subscribes to nothing. */
|
|
866
|
+
declare function useArrayAt(path: string | null, rowKey?: string): ArrayHandle<unknown>;
|
|
862
867
|
/** This array path's own messages. Descendant fields are not included — those render on the row fields. */
|
|
863
868
|
interface ArrayErrors {
|
|
864
869
|
errors: readonly string[];
|
|
865
870
|
warnings: readonly string[];
|
|
866
871
|
}
|
|
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
872
|
|
|
885
873
|
/** React scope for relative field names. `path` is the index path of the parent object or row. */
|
|
886
874
|
interface ScopeValue {
|
|
@@ -897,9 +885,16 @@ interface ArrayScopeValue {
|
|
|
897
885
|
path: string;
|
|
898
886
|
rowKey?: string;
|
|
899
887
|
}
|
|
888
|
+
/** The nearest enclosing tree (`<TreeField>`): its absolute path and the keys it was given (unset inherits). */
|
|
889
|
+
interface TreeScopeValue {
|
|
890
|
+
path: string;
|
|
891
|
+
childrenKey?: string;
|
|
892
|
+
rowKey?: string;
|
|
893
|
+
}
|
|
900
894
|
declare const FormContext: react.Context<FormEngine<any, any> | null>;
|
|
901
895
|
declare const ScopeContext: react.Context<ScopeValue>;
|
|
902
896
|
declare const ArrayContext: react.Context<ArrayScopeValue | null>;
|
|
897
|
+
declare const TreeContext: react.Context<TreeScopeValue | null>;
|
|
903
898
|
/**
|
|
904
899
|
* Internal: a container's per-row wrapper (`ArrayCards` puts each row in a card). `<ArrayField>` rows are memoized,
|
|
905
900
|
* so a container cannot rewrite them; it provides this and every row renders `wrap(rowContent)` inside its scope.
|
|
@@ -915,14 +910,15 @@ declare function useRequiredForm<T = any>(caller: string): FormEngine<T>;
|
|
|
915
910
|
/** Parent path for `useField('price')` inside a row or object. */
|
|
916
911
|
declare function useScope(): ScopeValue;
|
|
917
912
|
|
|
918
|
-
/** What `<UI>` renders with: the node's effective state (reaction > JSX props > the scope's
|
|
913
|
+
/** What `<UI>` renders with: the node's effective state (reaction > JSX props > the scope's flags). */
|
|
919
914
|
interface UiBinding {
|
|
920
915
|
/** The node name (`d.$ui(name)`). */
|
|
921
916
|
ui: string;
|
|
922
917
|
/** DOM id: `<prefix>-<scope>--<name>` (`<prefix>-ui--approvalTip` at the root). */
|
|
923
918
|
id: string;
|
|
924
|
-
|
|
925
|
-
|
|
919
|
+
visible: boolean;
|
|
920
|
+
disabled: boolean;
|
|
921
|
+
readOnly: boolean;
|
|
926
922
|
title: ReactNode;
|
|
927
923
|
description: ReactNode;
|
|
928
924
|
component: ComponentType<any> | undefined;
|
|
@@ -940,13 +936,17 @@ interface UIProps<C extends ComponentType<any> = ComponentType<any>, D extends C
|
|
|
940
936
|
decorator?: FieldSlot<D> | RegisteredDecoratorSlot | false;
|
|
941
937
|
title?: ReactNode;
|
|
942
938
|
description?: ReactNode;
|
|
943
|
-
/**
|
|
944
|
-
|
|
945
|
-
/**
|
|
946
|
-
|
|
939
|
+
/** `false` hides this UI (default: the scope's `visible`). An explicit `false` exits that fallback. */
|
|
940
|
+
visible?: boolean;
|
|
941
|
+
/** Gray this UI out (default: the scope's `disabled`). */
|
|
942
|
+
disabled?: boolean;
|
|
943
|
+
/** Render this UI's preview (default: the scope's `readOnly`). Wins over `disabled`. */
|
|
944
|
+
readOnly?: boolean;
|
|
947
945
|
/** Rendered inside `component` (or alone), or a render prop `(ui) => …`. */
|
|
948
946
|
children?: ReactNode | ((ui: UiBinding) => ReactNode);
|
|
949
947
|
}
|
|
948
|
+
/** Internal: the `<UI>` whose decorator is rendering (`FormItem` reads `title` / `description` from it). */
|
|
949
|
+
declare const UiNodeContext: react.Context<UiBinding | null>;
|
|
950
950
|
/** Internal: the surrounding `<UI>`, or `null`. */
|
|
951
951
|
declare function useUiNodeOrNull(): UiBinding | null;
|
|
952
952
|
/**
|
|
@@ -956,11 +956,11 @@ declare function useUiNodeOrNull(): UiBinding | null;
|
|
|
956
956
|
* <UI name="approvalTip" component={[Alert, { type: 'warning', message: '金额 ≥ 5 万需要审批' }]} />
|
|
957
957
|
* ```
|
|
958
958
|
*
|
|
959
|
-
* `$visible` / `$
|
|
959
|
+
* `$visible` / `$disabled` / `$readOnly` / `$title` / `$description` / `$componentProps` / `$decoratorProps`, same
|
|
960
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
|
|
961
|
+
* skip or drop the fields inside: a field's validation and submit depend only on its own flags.
|
|
962
962
|
*/
|
|
963
|
-
declare function UI<C extends ComponentType<any> = ComponentType<any>, D extends ComponentType<any> = ComponentType<any>>({ name, children,
|
|
963
|
+
declare function UI<C extends ComponentType<any> = ComponentType<any>, D extends ComponentType<any> = ComponentType<any>>({ name, children, visible, disabled, readOnly, ...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
964
|
|
|
965
965
|
/**
|
|
966
966
|
* Index of the row this component renders in (Formily `ArrayBase.useIndex`), from the surrounding `RowScope`
|
|
@@ -972,85 +972,76 @@ declare function useIndex(): number;
|
|
|
972
972
|
* this row changes, and follows the row when it moves. Throws outside a row (or tree node).
|
|
973
973
|
*/
|
|
974
974
|
declare function useRecord<TRow = any>(): TRow;
|
|
975
|
+
|
|
976
|
+
/** Options for a named {@link useTreeField}. Omitted keys keep a registration that is already there. */
|
|
977
|
+
interface TreeOptions {
|
|
978
|
+
childrenKey?: string;
|
|
979
|
+
rowKey?: string;
|
|
980
|
+
}
|
|
975
981
|
/**
|
|
976
|
-
*
|
|
977
|
-
*
|
|
978
|
-
*
|
|
979
|
-
*
|
|
980
|
-
*
|
|
982
|
+
* Edits on one tree. Field models follow the node id.
|
|
983
|
+
* `path` is always the thing this handle points at: the tree root for `useTreeField(name)`, the current node for `useTreeField()`.
|
|
984
|
+
* `treePath` is always the tree root (same as `path` on a root handle).
|
|
985
|
+
* `errors` / `warnings` are that path's own messages, not descendant fields.
|
|
986
|
+
* `value` is the current root array (`[]` when the stored value is not an array).
|
|
987
|
+
* `move(from, to)` uses final `pos` coordinates and refuses a move into a descendant (the result says why).
|
|
988
|
+
* `dragProps(pos)` is the HTML5 drag-and-drop props for the node at that coordinate; dropping A on B is `move(A, B)`.
|
|
981
989
|
*/
|
|
982
|
-
|
|
990
|
+
interface TreeHandle<TNode = unknown> {
|
|
991
|
+
/** What this handle points at. Root handle: the tree root. Node handle: the current node. */
|
|
983
992
|
path: string;
|
|
984
|
-
|
|
985
|
-
|
|
986
|
-
|
|
993
|
+
/** The tree root. Equal to `path` on a root handle. */
|
|
994
|
+
treePath: string;
|
|
995
|
+
/** This path's own messages. Descendant fields are not included. */
|
|
996
|
+
errors: readonly string[];
|
|
997
|
+
warnings: readonly string[];
|
|
998
|
+
value: TNode[];
|
|
999
|
+
/** Append `node` at the root, or as the last child of `parentPos`. A missing children array is created. */
|
|
1000
|
+
push: (node: TNode, parentPos?: Pos) => void;
|
|
1001
|
+
/** Insert `node` so it sits at `pos`. Later siblings shift. */
|
|
1002
|
+
insert: (pos: Pos, node: TNode) => void;
|
|
1003
|
+
/** Remove the node at `pos`. Its field model is dropped. */
|
|
1004
|
+
remove: (pos: Pos) => void;
|
|
1005
|
+
/** Replace the node at `pos`. The previous node's field model is dropped. */
|
|
1006
|
+
replace: (pos: Pos, node: TNode) => void;
|
|
987
1007
|
/** `to` is the final `pos`. Refuses a move into the node's own descendant. */
|
|
988
1008
|
move: (from: Pos, to: Pos) => MoveResult;
|
|
989
|
-
/** HTML5 drag-and-drop props for the node at `pos`
|
|
990
|
-
dragProps: (pos
|
|
991
|
-
}
|
|
992
|
-
|
|
1009
|
+
/** HTML5 drag-and-drop props for the node at `pos`. Dropping A on B is `move(A, B)`. */
|
|
1010
|
+
dragProps: (pos: Pos) => DragProps;
|
|
1011
|
+
}
|
|
993
1012
|
/**
|
|
994
|
-
*
|
|
995
|
-
*
|
|
996
|
-
*
|
|
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.
|
|
1013
|
+
* `useTreeField()` inside a node: the current node plus the same tree edits.
|
|
1014
|
+
* `path` is this node's path (`items.0.children.1`). `treePath` is the tree root.
|
|
1015
|
+
* `errors` / `warnings` are this node's own messages. `value` is the enclosing tree.
|
|
1016
|
+
* `dragProps()` with no argument targets this node.
|
|
1001
1017
|
*/
|
|
1002
|
-
interface
|
|
1003
|
-
/**
|
|
1004
|
-
|
|
1005
|
-
|
|
1006
|
-
|
|
1007
|
-
|
|
1008
|
-
|
|
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;
|
|
1018
|
+
interface TreeNodeHandle<TNode = unknown> extends TreeHandle<TNode> {
|
|
1019
|
+
/** This node's path, not the tree root. */
|
|
1020
|
+
path: string;
|
|
1021
|
+
pos: Pos;
|
|
1022
|
+
index: number;
|
|
1023
|
+
record: TNode;
|
|
1024
|
+
treePath: string;
|
|
1025
|
+
dragProps: (pos?: Pos) => DragProps;
|
|
1021
1026
|
}
|
|
1022
|
-
/** Create a group handle that lives as long as the component (pass it to {@link FieldGroup}). */
|
|
1023
|
-
declare function useFieldGroup(): FieldGroupHandle;
|
|
1024
1027
|
/**
|
|
1025
|
-
*
|
|
1028
|
+
* One tree hook.
|
|
1026
1029
|
*
|
|
1027
|
-
*
|
|
1028
|
-
*
|
|
1029
|
-
*
|
|
1030
|
-
*
|
|
1031
|
-
*
|
|
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.
|
|
1030
|
+
* `useTreeField(name)` resolves `name` against the current scope and returns the tree.
|
|
1031
|
+
* `path` and `treePath` are both the root. It registers that path into the nearest `FieldGroup`.
|
|
1032
|
+
*
|
|
1033
|
+
* `useTreeField()` takes the nearest `<TreeField>` node: `path` is the node, `treePath` is the root,
|
|
1034
|
+
* plus `pos`, `index`, `record`, and the tree's `push` / `insert` / `remove` / `replace` / `move` / `dragProps`.
|
|
1035
|
+
* Outside a node it throws.
|
|
1045
1036
|
*/
|
|
1046
|
-
declare function
|
|
1047
|
-
|
|
1037
|
+
declare function useTreeField<TNode = unknown>(): TreeNodeHandle<TNode>;
|
|
1038
|
+
declare function useTreeField(name: string, opts?: TreeOptions): TreeHandle<unknown>;
|
|
1048
1039
|
/**
|
|
1049
|
-
*
|
|
1050
|
-
*
|
|
1051
|
-
*
|
|
1040
|
+
* {@link useTreeField} for an absolute path, without field-group registration. `null` subscribes to nothing.
|
|
1041
|
+
* `subscribe` is false for the current node: structure paints from the named tree hook, and this call
|
|
1042
|
+
* only reads the value at render time.
|
|
1052
1043
|
*/
|
|
1053
|
-
declare function
|
|
1044
|
+
declare function useTreeAt(path: string | null, opts?: TreeOptions, subscribe?: boolean): TreeHandle<unknown>;
|
|
1054
1045
|
|
|
1055
1046
|
/**
|
|
1056
1047
|
* Subscribe to the `$` reads inside `select`.
|
|
@@ -1071,4 +1062,4 @@ declare function useFormMessage(): <K extends FormMessageKey>(key: K, ...params:
|
|
|
1071
1062
|
declare function useWatch<T>(): <S>(select: (d: Draft<T>) => S) => S;
|
|
1072
1063
|
declare function useWatch<T = any, S = unknown>(select: (d: Draft<T>) => S): S;
|
|
1073
1064
|
|
|
1074
|
-
export {
|
|
1065
|
+
export { useForm as $, type ArrayContainerSlot as A, type BlurFlag as B, type CheckedFieldProps as C, type RegisteredComponentSlot as D, type RegisteredDecoratorSlot as E, type FormSubmitHandlers as F, type RegisteredSlot as G, type ScopeValue as H, TreeField as I, type TreeHandle as J, type TreeNodeHandle as K, type TreeOptions as L, type TreeScopeValue 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, Watch as W, connect as X, mapProps as Y, useArrayField as Z, useField as _, type FieldProps as a, useFormContext as a0, useIndex as a1, useRecord as a2, useTreeField as a3, useWatch as a4, ArrayContext as a5, ArrayScope as a6, type DragProps as a7, FieldContext as a8, FormContext as a9, type PropsEnhancer as aa, RowScope as ab, RowWrapContext as ac, ScopeContext as ad, TreeContext as ae, TreeScope as af, UiNodeContext as ag, useArrayAt as ah, useRequiredForm as ai, useReset as aj, useScope as ak, useSubmit as al, useTreeAt as am, useUiNodeOrNull as an, valueFromEvent as ao, 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 ComponentStatics as j, type ConnectEnhancer as k, type ConnectFieldProps as l, type ConnectedComponent as m, Field as n, type FieldComponents as o, type FieldDecorators as p, FieldKit as q, type FieldKitDecorator as r, type FieldKitSpec as s, type FieldPropKey as t, type FieldSlot as u, type FieldStateKey as v, Form as w, type FormDomProps as x, type FormProps as y, type PropsTransform as z };
|