@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.
@@ -1,6 +1,6 @@
1
1
  import * as react from 'react';
2
- import { ComponentType, ReactNode, ComponentProps, DragEvent, FormHTMLAttributes, FunctionComponent, ComponentClass, ForwardRefExoticComponent, Ref } from 'react';
3
- import { Display, Pattern, EnumOption, UiName, FieldEnum, RulesInput, FieldPath, PathValue, Pos, MoveResult, ArrayPath, FieldError, FormInstance, Draft, FormOptions, DefaultSubmit, FieldsInput, ResolveSubmit, ArrayItemOf, FormEngine, UiDisplay, FormMessageKey, MessageArgs } from '@shikiform/core/internal';
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
- display: Display;
75
- pattern: Pattern;
76
- required: boolean;
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; display, pattern, title, props and `id` (`<prefix>-<path>--<ui>`) are the instance'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`). `display` and `pattern` are persistent flags.
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 display / pattern / title / props, addressed in effects as
169
- * `d.amount.$ui('slider')` (unset falls back to the field: pattern inherits). Own DOM id `<prefix>-<path>--<ui>`.
170
- * `rules` / `required` / `enum` belong on the field itself (the `<Field>` without `ui`). `display` is this instance's.
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
- /** `virtual` renders and validates but is not submitted. `hidden` / `none` do not render. */
182
- display?: Display;
183
- pattern?: Pattern;
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 (`reason: 'invalid'`). Scroll to the first error, show a toast … */
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 (`reason: 'error'`).
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 for display `hidden` and `none` after subscribing, so a mounted model stays registered.
279
- * `virtual` stays mounted: it renders and validates, and is omitted from submit.
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 display,
289
- * pattern, title and props (unset falls back to the field's). Own DOM id `<prefix>-<path>--<ui>`. Leave rules / required /
290
- * enum to the `<Field>` without `ui`. `display` here is this instance's, not the field's.
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
- * readPretty views read it as `options`.
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
- * Initial display when no reaction has written `$display`. `virtual` renders and validates but is not submitted.
307
- * On `<Field ui>` this is the instance's display (`visible` | `hidden` | `none`); `virtual` belongs on the field.
308
- */
309
- display?: Display;
310
- /** Initial pattern when no reaction has written `$pattern`. `$pattern = undefined` inherits again. */
311
- pattern?: Pattern;
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
- * `display="virtual"` renders and validates but omits the value from submit. `display="hidden"` still validates.
349
- * `display="none"` skips validation. `<Field<Row> name="price">` checks the name.
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)` + not rendered (`hidden` / `none`) → `null`
352
- * + the two slots. `virtual` still renders.
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
- * `display="virtual"` omits this object (and its subtree) from submit (`getSubmitValues`).
358
- * Also list it in `useForm({ fields })` so the omission holds before this component mounts.
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, display, children, }: {
355
+ declare function ObjectField<TScope = any>({ name, visible, disabled, readOnly, omit, children, }: {
362
356
  name: FieldPath<TScope>;
363
- /** `virtual` omits this object from submit. `hidden` / `none` are inherited by the fields inside. */
364
- display?: Display;
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 useArray}.
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 useArray} (`path` is absolute). `<ArrayField>` renders it; use it in a custom
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 useTreeNode} with `pos`) read it. Stable value, so a row that did not move does not wake its consumers.
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
- /** Register a tree root. Rendering nodes is the caller's job (`pos` is `number[]`). `<TreeField<Values>>` checks the name. */
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: (tree: ReturnType<typeof useTreeField>) => ReactNode;
430
- }): ReactNode;
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' | 'pattern' | 'display' | 'path' | 'errors' | 'warnings' | `componentProps.${string}` | `decoratorProps.${string}`;
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`, …). `readPretty` is not converted: the view gets
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 ReadPrettyEnhancer = {
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? } }), mapBlur(...), or mapProps({ onBlur: false }) to opt out.';
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 })` / {@link mapBlur} / `mapProps({ onBlur: false })`). Otherwise `validateTrigger: 'onBlur'`
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 whose display is `virtual` / `none`.
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: { display: 'virtual' } } })
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' })` (same shape as `useTreeField`).
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
- * The nearest enclosing array, no name needed (Formily `ArrayBase.useArray`): inside an `<ArrayField>` row or its container
848
- * (`ArrayItems` / `ArrayCards` / `ArrayTable`, toolbar included), the same handle {@link useArrayField} returns for that array.
849
- * Throws outside an array.
850
- *
851
- * ```tsx
852
- * function RemoveButton() {
853
- * const array = useArray()
854
- * const index = useIndex()
855
- * return <button onClick={() => array.remove(index)}>删除</button>
856
- * }
857
- * ```
858
- */
859
- declare function useArray<TRow = unknown>(): ArrayHandle<TRow>;
860
- /** {@link useArrayField} for an absolute path, without field-group registration (internal: containers, `useArrayTable`). */
861
- declare function useArrayAt(path: string, rowKey?: string): ArrayHandle<unknown>;
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 display / pattern). */
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
- display: UiDisplay;
925
- pattern: Pattern;
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
- /** Initial display when no reaction wrote `$visible` / `$display` (default: the scope's). */
944
- display?: UiDisplay;
945
- /** Initial pattern when no reaction wrote `$pattern` (default: inherited from the scope / form). */
946
- pattern?: Pattern;
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` / `$display` / `$pattern` / `$title` / `$description` / `$componentProps` / `$decoratorProps`, same
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 `$visible` / display.
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, 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;
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
- * The tree node this component renders in: `path`, `pos`, `index` (last segment of `pos`), the reactive `record`,
977
- * plus `move(from, to)` and `dragProps(pos)` — the same node operations the tree handle gives, bound to the tree the
978
- * node belongs to (found by registering with the nearest tree, like `useArray()` does for arrays).
979
- * A tree's nodes are rendered by the caller; wrap each node in `<RowScope path pos>` to provide it.
980
- * Throws outside a node.
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
- declare function useTreeNode<TNode = any>(): {
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
- pos: Pos;
985
- index: number;
986
- record: TNode;
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` (default: this node). */
990
- dragProps: (pos?: Pos) => DragProps;
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
- * A set of field paths collected from the JSX below a {@link FieldGroup}: every `<Field>` / `useField(name)` /
995
- * `<ArrayField>` mounted inside registers its absolute path while mounted (nested groups register into every
996
- * enclosing group). It owns no state of the form; it only answers "which fields are inside this region".
997
- *
998
- * Layout containers use it to badge a tab with the errors of its fields (`FormTab`, `FormCollapse`) and to validate
999
- * one step (`FormStep`: `form.validate(group.paths())`). A pure-layout `FormItem` could aggregate its children's
1000
- * errors the same way.
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 FieldGroupHandle {
1003
- /** Absolute paths mounted inside the group, in mount order. A path mounted twice is listed once. */
1004
- paths(): string[];
1005
- /** Called after a path is added or removed. */
1006
- subscribe(listener: () => void): () => void;
1007
- /** Bumped on every add / remove (a `useSyncExternalStore` snapshot). */
1008
- version(): number;
1009
- }
1010
- /** Internal: the registry behind a {@link FieldGroupHandle}. */
1011
- declare class FieldGroupStore implements FieldGroupHandle {
1012
- private counts;
1013
- private listeners;
1014
- private ver;
1015
- paths: () => string[];
1016
- version: () => number;
1017
- subscribe: (listener: () => void) => (() => void);
1018
- /** Register `path` until the returned function runs. */
1019
- add(path: string): () => void;
1020
- private changed;
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
- * Collect the fields rendered inside `children` into `value` (from {@link useFieldGroup}). Renders no DOM.
1028
+ * One tree hook.
1026
1029
  *
1027
- * ```tsx
1028
- * const group = useFieldGroup()
1029
- * const errors = useFieldGroupErrors(group) // FieldError[] of the fields inside
1030
- * <FieldGroup value={group}><Field name="a" … /><Field name="b" … /></FieldGroup>
1031
- * await form.validate(group.paths()) // validate only those fields
1032
- * ```
1033
- */
1034
- declare function FieldGroup({ value, children }: {
1035
- value: FieldGroupHandle;
1036
- children?: ReactNode;
1037
- }): react.JSX.Element;
1038
- /** Internal: register `path` with the enclosing groups while mounted (`useField(name)`, `useArrayField`). */
1039
- declare function useFieldGroupRegistration(path: string): void;
1040
- /** Internal: the shown errors of each group (one entry per field with messages), re-rendering when they change. */
1041
- declare function useGroupsErrors(form: FormEngine<any, any>, groups: readonly FieldGroupHandle[]): FieldError[][];
1042
- /**
1043
- * The errors of the fields inside a {@link FieldGroup}: one `{ path, messages }` per field with shown errors
1044
- * (display `none` excluded), re-rendering only when that list changes. `errors.length` is a tab's badge count.
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 useFieldGroupErrors(group: FieldGroupHandle): FieldError[];
1047
-
1037
+ declare function useTreeField<TNode = unknown>(): TreeNodeHandle<TNode>;
1038
+ declare function useTreeField(name: string, opts?: TreeOptions): TreeHandle<unknown>;
1048
1039
  /**
1049
- * Resolve built-in texts for the nearest form: its `messages` → `setDefaultMessages` → `zhCN`.
1050
- * Outside a form only the app defaults apply. Component labels in `@shikiform/antd` read through this,
1051
- * so a custom component can follow the same locale: `const t = useFormMessage(); t('submit')`.
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 useFormMessage(): <K extends FormMessageKey>(key: K, ...params: MessageArgs<K>) => string;
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 { mapFieldProps as $, type ArrayContainerSlot as A, type BlurFlag as B, type CheckedFieldProps as C, Form as D, type FormDomProps as E, type FormSubmitHandlers as F, type FormProps as G, type PropsTransform as H, type RegisteredComponentSlot as I, type RegisteredDecoratorSlot as J, type RegisteredSlot as K, RowScope as L, type ScopeValue as M, UI as N, ObjectField as O, type PropsMapping as P, type UIProps as Q, type ResetState as R, type SubmitState as S, TreeField as T, type UseFieldOptions as U, type UiBinding as V, type UseResetOptions as W, type UseSubmitOptions as X, Watch as Y, connect as Z, mapBlur as _, type FieldProps as a, mapProps as a0, mapReadPretty as a1, useArray as a2, useArrayErrors as a3, useArrayField as a4, useField as a5, useFieldGroup as a6, useFieldGroupErrors as a7, useForm as a8, useFormContext as a9, useFormMessage as aa, useIndex as ab, useRecord as ac, useReset as ad, useSubmit as ae, useTreeField as af, useTreeNode as ag, useWatch as ah, ArrayContext as ai, type DragProps as aj, FieldGroupStore as ak, FormContext as al, type PropsEnhancer as am, type ReadPrettyEnhancer as an, RowWrapContext as ao, ScopeContext as ap, useArrayAt as aq, useFieldGroupRegistration as ar, useGroupsErrors as as, useRequiredForm as at, useScope as au, useUiNodeOrNull as av, valueFromEvent as aw, type ArrayKey as b, type FieldBinding as c, type ArrayHandle as d, type UseFormOptions as e, type ArrayErrors as f, ArrayField as g, ArrayScope as h, type ArrayScopeValue as i, type BlurOn as j, type ClickEvent as k, type ComponentStatics as l, type ConnectEnhancer as m, type ConnectFieldProps as n, type ConnectedComponent as o, Field as p, type FieldComponents as q, type FieldDecorators as r, FieldGroup as s, type FieldGroupHandle as t, FieldKit as u, type FieldKitDecorator as v, type FieldKitSpec as w, type FieldPropKey as x, type FieldSlot as y, type FieldStateKey as z };
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 };