@reformer/cdk 1.0.0-beta.1

package/dist/components/form-array/FormArray.d.ts

@@ -0,0 +1,223 @@
+import { FormFields, FormProxy } from '@reformer/core';
+import { FormArrayList } from './FormArrayList';
+import { FormArrayAddButton } from './FormArrayAddButton';
+import { FormArrayRemoveButton } from './FormArrayRemoveButton';
+import { FormArrayEmpty } from './FormArrayEmpty';
+import { FormArrayCount } from './FormArrayCount';
+import { FormArrayItemIndex } from './FormArrayItemIndex';
+import { FormArrayRootProps } from './types';
+/**
+ * Handle exposed via ref for external control of {@link FormArray}.
+ *
+ * Имперо-API для случаев, когда триггер находится вне дерева `FormArray.Root`
+ * (тулбар страницы, диалог подтверждения, async-эффект). Получают через
+ * `useRef<FormArrayHandle<T>>(null)` и передают в `<FormArray.Root ref={...}>`.
+ *
+ * Свойства `length` / `isEmpty` — снимок на момент рендера. Реактивную длину
+ * для условного UI снаружи берите через `useFormControl(arrayNode).length`.
+ *
+ * @typeParam T - Тип одного элемента массива (как в `FormArray.Root control={...}`).
+ *
+ * @example Тулбар «Добавить / Очистить» поверх массива
+ * ```tsx
+ * import { useRef } from 'react';
+ * import { FormArray, type FormArrayHandle } from '@reformer/cdk/form-array';
+ *
+ * function PropertiesEditor({ form }: Props) {
+ *   const arrayRef = useRef<FormArrayHandle<Property>>(null);
+ *
+ *   return (
+ *     <>
+ *       <div className="toolbar">
+ *         <button onClick={() => arrayRef.current?.add({ type: 'apartment' })}>
+ *           + Квартира
+ *         </button>
+ *         <button onClick={() => arrayRef.current?.add({ type: 'house' })}>
+ *           + Дом
+ *         </button>
+ *         <button onClick={() => confirm('Удалить всё?') && arrayRef.current?.clear()}>
+ *           Очистить
+ *         </button>
+ *       </div>
+ *       <FormArray.Root ref={arrayRef} control={form.properties}>
+ *         <FormArray.List>{({ control }) => <PropertyForm control={control} />}</FormArray.List>
+ *       </FormArray.Root>
+ *     </>
+ *   );
+ * }
+ * ```
+ *
+ * @example Импорт массива из API: insert + at для проверки дублей
+ * ```tsx
+ * const arrayRef = useRef<FormArrayHandle<Contact>>(null);
+ *
+ * async function importFromCSV(rows: Contact[]) {
+ *   for (const row of rows) {
+ *     // skip duplicates by email
+ *     const existing = Array.from({ length: arrayRef.current?.length ?? 0 })
+ *       .map((_, i) => arrayRef.current?.at(i)?.getValue());
+ *     if (existing.some((c) => c?.email === row.email)) continue;
+ *     arrayRef.current?.insert(0, row); // добавляем в начало
+ *   }
+ * }
+ * ```
+ */
+export interface FormArrayHandle<T extends FormFields> {
+    /** Add a new item to the end of the array */
+    add: (value?: Partial<T>) => void;
+    /** Remove all items from the array */
+    clear: () => void;
+    /** Insert a new item at a specific index */
+    insert: (index: number, value?: Partial<T>) => void;
+    /** Remove item at specific index */
+    removeAt: (index: number) => void;
+    /** Current number of items */
+    length: number;
+    /** Whether the array is empty */
+    isEmpty: boolean;
+    /** Get item control at specific index */
+    at: (index: number) => FormProxy<T> | undefined;
+}
+declare const FormArrayRoot: <T extends FormFields>(props: FormArrayRootProps<T> & {
+    ref?: React.ForwardedRef<FormArrayHandle<T>>;
+}) => React.ReactElement;
+type FormArrayComponent = typeof FormArrayRoot & {
+    Root: typeof FormArrayRoot;
+    List: typeof FormArrayList;
+    AddButton: typeof FormArrayAddButton;
+    RemoveButton: typeof FormArrayRemoveButton;
+    Empty: typeof FormArrayEmpty;
+    Count: typeof FormArrayCount;
+    ItemIndex: typeof FormArrayItemIndex;
+};
+/**
+ * FormArray - Headless compound component for managing form arrays
+ *
+ * Provides complete flexibility for building array UI while handling
+ * all the form array state and actions internally.
+ *
+ * ## Features
+ * - **Headless** - complete freedom in building UI
+ * - **Compound Components** - declarative API via nested components
+ * - **External Control** - control from outside via ref (useImperativeHandle)
+ * - **Type Safe** - full TypeScript support
+ *
+ * ## Sub-components
+ * - `FormArray.Root` - context provider, accepts ref for external control
+ * - `FormArray.List` - iterates over array items
+ * - `FormArray.AddButton` - button to add item
+ * - `FormArray.RemoveButton` - button to remove item (inside List)
+ * - `FormArray.Empty` - content for empty state
+ * - `FormArray.Count` - display item count
+ * - `FormArray.ItemIndex` - display item index (inside List)
+ *
+ * ## FormArrayHandle API (ref)
+ * - `add(value?)` - add item to the end
+ * - `insert(index, value?)` - insert item at position
+ * - `removeAt(index)` - remove item by index
+ * - `clear()` - clear array
+ * - `at(index)` - get item control by index
+ * - `length` - current item count
+ * - `isEmpty` - empty array flag
+ *
+ * @example Basic usage
+ * ```tsx
+ * <FormArray.Root control={form.properties}>
+ *   <h3>Properties (<FormArray.Count />)</h3>
+ *
+ *   <FormArray.Empty>
+ *     <p className="text-gray-500">No properties added</p>
+ *   </FormArray.Empty>
+ *
+ *   <FormArray.List className="space-y-4">
+ *     {({ control }) => (
+ *       <div className="p-4 border rounded">
+ *         <div className="flex justify-between mb-2">
+ *           <h4>Property #<FormArray.ItemIndex /></h4>
+ *           <FormArray.RemoveButton className="text-red-500">
+ *             Remove
+ *           </FormArray.RemoveButton>
+ *         </div>
+ *         <PropertyForm control={control} />
+ *       </div>
+ *     )}
+ *   </FormArray.List>
+ *
+ *   <FormArray.AddButton className="mt-4 btn-primary">
+ *     + Add Property
+ *   </FormArray.AddButton>
+ * </FormArray.Root>
+ * ```
+ *
+ * @example External control via ref
+ * ```tsx
+ * import { useRef } from 'react';
+ * import { FormArray, FormArrayHandle } from '@reformer/cdk/form-array';
+ *
+ * function PropertiesManager() {
+ *   const arrayRef = useRef<FormArrayHandle<Property>>(null);
+ *
+ *   // Programmatic control from outside
+ *   const handleAddApartment = () => {
+ *     arrayRef.current?.add({ type: 'apartment', estimatedValue: 0 });
+ *   };
+ *
+ *   const handleClearAll = () => {
+ *     if (confirm('Delete all items?')) {
+ *       arrayRef.current?.clear();
+ *     }
+ *   };
+ *
+ *   const handleRemoveFirst = () => {
+ *     if (arrayRef.current && arrayRef.current.length > 0) {
+ *       arrayRef.current.removeAt(0);
+ *     }
+ *   };
+ *
+ *   const handleInsertAtStart = () => {
+ *     arrayRef.current?.insert(0, { type: 'house' });
+ *   };
+ *
+ *   return (
+ *     <div>
+ *       <div className="toolbar">
+ *         <button onClick={handleAddApartment}>+ Apartment</button>
+ *         <button onClick={handleInsertAtStart}>Insert at start</button>
+ *         <button onClick={handleRemoveFirst}>Remove first</button>
+ *         <button onClick={handleClearAll}>Clear all</button>
+ *       </div>
+ *
+ *       <FormArray.Root ref={arrayRef} control={form.properties}>
+ *         <FormArray.List>
+ *           {({ control }) => <PropertyForm control={control} />}
+ *         </FormArray.List>
+ *       </FormArray.Root>
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example Using useFormArray hook for full customization
+ * ```tsx
+ * import { useFormArray } from '@reformer/cdk/form-array';
+ *
+ * function CustomArrayUI() {
+ *   const { items, add, isEmpty, length } = useFormArray(form.properties);
+ *
+ *   return (
+ *     <div>
+ *       <span>Total: {length}</span>
+ *       {items.map(({ control, id, remove }) => (
+ *         <CustomCard key={id} onDelete={remove}>
+ *           <PropertyForm control={control} />
+ *         </CustomCard>
+ *       ))}
+ *       {isEmpty && <EmptyState />}
+ *       <button onClick={() => add()}>Add</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare const FormArray: FormArrayComponent;
+export {};

package/dist/components/form-array/FormArrayAddButton.d.ts

@@ -0,0 +1,6 @@
+import { ReactElement } from 'react';
+import { FormFields } from '@reformer/core';
+import { FormArrayAddButtonProps } from './types';
+export declare const FormArrayAddButton: <T extends FormFields = FormFields>(props: FormArrayAddButtonProps<T> & {
+    ref?: React.Ref<HTMLButtonElement>;
+}) => ReactElement | null;

package/dist/components/form-array/FormArrayContext.d.ts

@@ -0,0 +1,137 @@
+import { ArrayNode, FormFields, FormProxy } from '@reformer/core';
+/**
+ * Представляет элемент массива с контролом, индексом и действиями
+ */
+export interface FormArrayItem<T extends FormFields> {
+    /** Контрол для данного элемента */
+    control: FormProxy<T>;
+    /** Индекс элемента (0-based) */
+    index: number;
+    /** Уникальный идентификатор для React key */
+    id: string | number;
+    /** Удалить этот элемент из массива */
+    remove: () => void;
+}
+/**
+ * Контекст уровня массива
+ */
+export interface FormArrayContextValue<T extends FormFields = FormFields> {
+    /** Массив элементов с контролами и действиями */
+    items: FormArrayItem<T>[];
+    /** Текущая длина массива */
+    length: number;
+    /** Пустой ли массив */
+    isEmpty: boolean;
+    /** Добавить новый элемент в конец */
+    add: (value?: Partial<T>) => void;
+    /** Удалить все элементы */
+    clear: () => void;
+    /** Вставить элемент на указанную позицию */
+    insert: (index: number, value?: Partial<T>) => void;
+    /** Оригинальный ArrayNode */
+    control: ArrayNode<T>;
+}
+/**
+ * Контекст уровня элемента массива
+ */
+export interface FormArrayItemContextValue<T extends FormFields = FormFields> {
+    /** Контрол для данного элемента */
+    control: FormProxy<T>;
+    /** Индекс элемента (0-based) */
+    index: number;
+    /** Уникальный идентификатор для React key */
+    id: string | number;
+    /** Удалить этот элемент из массива */
+    remove: () => void;
+}
+/**
+ * React context, который снабжает дочерние компоненты `FormArray` (List, AddButton, …)
+ * текущим `ArrayNode` и хелперами. Создаётся `FormArray.Root`. Читать через {@link useFormArrayContext}.
+ *
+ * @example
+ * ```tsx
+ * import { FormArrayContext } from '@reformer/cdk/form-array';
+ *
+ * function MyConsumer() {
+ *   const ctx = useContext(FormArrayContext);
+ *   return <span>items: {ctx?.items.length}</span>;
+ * }
+ * ```
+ */
+export declare const FormArrayContext: import('react').Context<FormArrayContextValue<any> | null>;
+/**
+ * React context, видимый внутри `FormArray.List` для одного элемента массива.
+ * Содержит `index`, `path` и `remove()`. Читать через {@link useFormArrayItemContext}.
+ *
+ * @example
+ * ```tsx
+ * import { FormArrayItemContext } from '@reformer/cdk/form-array';
+ *
+ * function CurrentIndex() {
+ *   const item = useContext(FormArrayItemContext);
+ *   return <small>#{item?.index}</small>;
+ * }
+ * ```
+ */
+export declare const FormArrayItemContext: import('react').Context<FormArrayItemContextValue<any> | null>;
+/**
+ * Хук для доступа к контексту `FormArray`. Бросает исключение, если вызван вне
+ * `FormArray.Root` или эквивалентного провайдера.
+ *
+ * @returns Текущий {@link FormArrayContextValue}.
+ * @throws Error если используется вне `FormArray.Root`.
+ *
+ * @example Кастомный AddButton с predefined значением
+ * ```tsx
+ * import { useFormArrayContext } from '@reformer/cdk/form-array';
+ *
+ * function AddDraftButton() {
+ *   const { add } = useFormArrayContext<Item>();
+ *   return (
+ *     <button onClick={() => add({ status: 'draft', createdAt: Date.now() })}>
+ *       + Add Draft
+ *     </button>
+ *   );
+ * }
+ * ```
+ *
+ * @example Счётчик и условный empty-state из произвольного места дерева
+ * ```tsx
+ * function ItemsBadge() {
+ *   const { length, isEmpty } = useFormArrayContext();
+ *   if (isEmpty) return <span className="text-gray-400">Нет элементов</span>;
+ *   return <span className="badge">{length}</span>;
+ * }
+ * ```
+ */
+export declare function useFormArrayContext<T extends FormFields = FormFields>(): FormArrayContextValue<T>;
+/**
+ * Хук для доступа к контексту текущего элемента внутри `FormArray.List`.
+ *
+ * @returns Текущий {@link FormArrayItemContextValue} (`index`, `path`, `remove`).
+ * @throws Error если используется вне `FormArray.List` или item-шаблона.
+ *
+ * @example Кнопка удаления текущего элемента
+ * ```tsx
+ * import { useFormArrayItemContext } from '@reformer/cdk/form-array';
+ *
+ * function ItemRemoveButton() {
+ *   const { remove } = useFormArrayItemContext();
+ *   return <button onClick={remove}>×</button>;
+ * }
+ * ```
+ *
+ * @example Доступ к control + index для условной валидации
+ * ```tsx
+ * function ItemHeader() {
+ *   const { control, index } = useFormArrayItemContext<Property>();
+ *   const { value: type } = useFormControl(control.type);
+ *   return (
+ *     <h4>
+ *       #{index + 1} — {type === 'house' ? 'Дом' : 'Квартира'}
+ *     </h4>
+ *   );
+ * }
+ * ```
+ */
+export declare function useFormArrayItemContext<T extends FormFields = FormFields>(): FormArrayItemContextValue<T>;

package/dist/components/form-array/FormArrayCount.d.ts

@@ -0,0 +1,17 @@
+import { FormArrayCountProps } from './types';
+/**
+ * FormArray.Count - Displays the number of items in the array
+ *
+ * @example Basic usage
+ * ```tsx
+ * <h3>Items (<FormArray.Count />)</h3>
+ * ```
+ *
+ * @example With custom render
+ * ```tsx
+ * <FormArray.Count render={(count) => (
+ *   count === 0 ? 'No items' : `${count} item${count > 1 ? 's' : ''}`
+ * )} />
+ * ```
+ */
+export declare function FormArrayCount({ render }: FormArrayCountProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/form-array/FormArrayEmpty.d.ts

@@ -0,0 +1,22 @@
+import { FormArrayEmptyProps } from './types';
+/**
+ * FormArray.Empty - Renders children only when array is empty
+ *
+ * @example Basic usage
+ * ```tsx
+ * <FormArray.Empty>
+ *   <p className="text-gray-500">No items added yet</p>
+ * </FormArray.Empty>
+ * ```
+ *
+ * @example With call to action
+ * ```tsx
+ * <FormArray.Empty>
+ *   <div className="text-center p-8">
+ *     <p>No properties</p>
+ *     <FormArray.AddButton>Add your first property</FormArray.AddButton>
+ *   </div>
+ * </FormArray.Empty>
+ * ```
+ */
+export declare function FormArrayEmpty({ children }: FormArrayEmptyProps): import("react/jsx-runtime").JSX.Element | null;

package/dist/components/form-array/FormArrayItemIndex.d.ts

@@ -0,0 +1,24 @@
+import { FormArrayItemIndexProps } from './types';
+/**
+ * FormArray.ItemIndex - Displays the index of current item (must be inside FormArray.List)
+ *
+ * @example Basic usage (1-based display)
+ * ```tsx
+ * <FormArray.List>
+ *   {() => (
+ *     <h4>Item #<FormArray.ItemIndex render={(i) => i + 1} /></h4>
+ *   )}
+ * </FormArray.List>
+ * ```
+ *
+ * @example Zero-based index
+ * ```tsx
+ * <FormArray.ItemIndex /> // Renders 0, 1, 2, ...
+ * ```
+ *
+ * @example Custom render
+ * ```tsx
+ * <FormArray.ItemIndex render={(index) => `Position: ${index + 1}`} />
+ * ```
+ */
+export declare function FormArrayItemIndex({ render }: FormArrayItemIndexProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/form-array/FormArrayList.d.ts

@@ -0,0 +1,26 @@
+import { FormFields } from '@reformer/core';
+import { FormArrayListProps } from './types';
+/**
+ * FormArray.List - Iterates over array items and provides item context
+ *
+ * @example Basic usage
+ * ```tsx
+ * <FormArray.List>
+ *   {({ control, index, remove }) => (
+ *     <div>
+ *       <span>Item #{index + 1}</span>
+ *       <button onClick={remove}>Remove</button>
+ *       <ItemForm control={control} />
+ *     </div>
+ *   )}
+ * </FormArray.List>
+ * ```
+ *
+ * @example With custom container
+ * ```tsx
+ * <FormArray.List className="space-y-4" as="ul">
+ *   {(item) => <li><ItemForm control={item.control} /></li>}
+ * </FormArray.List>
+ * ```
+ */
+export declare function FormArrayList<T extends FormFields>({ children, className, as, }: FormArrayListProps<T>): import("react/jsx-runtime").JSX.Element;

package/dist/components/form-array/FormArrayRemoveButton.d.ts

@@ -0,0 +1,26 @@
+import { FormArrayRemoveButtonProps } from './types';
+/**
+ * FormArray.RemoveButton - Button to remove current item (must be inside FormArray.List)
+ *
+ * @example Basic usage
+ * ```tsx
+ * <FormArray.List>
+ *   {({ control }) => (
+ *     <div>
+ *       <ItemForm control={control} />
+ *       <FormArray.RemoveButton className="text-red-500">
+ *         Remove
+ *       </FormArray.RemoveButton>
+ *     </div>
+ *   )}
+ * </FormArray.List>
+ * ```
+ *
+ * @example With custom button (asChild)
+ * ```tsx
+ * <FormArray.RemoveButton asChild>
+ *   <IconButton icon="trash" aria-label="Remove" />
+ * </FormArray.RemoveButton>
+ * ```
+ */
+export declare const FormArrayRemoveButton: import('react').ForwardRefExoticComponent<FormArrayRemoveButtonProps & import('react').RefAttributes<HTMLButtonElement>>;

package/dist/components/form-array/index.d.ts

@@ -0,0 +1,13 @@
+export { FormArray } from './FormArray';
+export type { FormArrayHandle } from './FormArray';
+export { FormArrayList } from './FormArrayList';
+export { FormArrayAddButton } from './FormArrayAddButton';
+export { FormArrayRemoveButton } from './FormArrayRemoveButton';
+export { FormArrayEmpty } from './FormArrayEmpty';
+export { FormArrayCount } from './FormArrayCount';
+export { FormArrayItemIndex } from './FormArrayItemIndex';
+export { useFormArray } from './useFormArray';
+export type { FormArrayItem, UseFormArrayReturn } from './useFormArray';
+export { FormArrayContext, FormArrayItemContext, useFormArrayContext, useFormArrayItemContext, } from './FormArrayContext';
+export type { FormArrayRootProps, FormArrayListProps, FormArrayItemRenderProps, FormArrayAddButtonProps, FormArrayRemoveButtonProps, FormArrayEmptyProps, FormArrayCountProps, FormArrayItemIndexProps, } from './types';
+export type { FormArrayContextValue, FormArrayItemContextValue } from './FormArrayContext';

package/dist/components/form-array/types.d.ts

@@ -0,0 +1,77 @@
+import { ReactNode, ElementType } from 'react';
+import { ArrayNode, FormFields, FormProxy } from '@reformer/core';
+/**
+ * Props for FormArray.Root component
+ */
+export interface FormArrayRootProps<T extends FormFields> {
+    /** The ArrayNode control from the form */
+    control: ArrayNode<T>;
+    /** Child components */
+    children: ReactNode;
+}
+/**
+ * Props for FormArray.List component
+ */
+export interface FormArrayListProps<T extends FormFields> {
+    /** Render function for each item */
+    children: (item: FormArrayItemRenderProps<T>) => ReactNode;
+    /** Optional className for the list container */
+    className?: string;
+    /** Optional element type for the container (default: 'div') */
+    as?: ElementType;
+}
+/**
+ * Props passed to the render function in FormArray.List
+ */
+export interface FormArrayItemRenderProps<T extends FormFields> {
+    /** The form control for this item */
+    control: FormProxy<T>;
+    /** Zero-based index of the item */
+    index: number;
+    /** Unique identifier for React key */
+    id: string | number;
+    /** Remove this item from the array */
+    remove: () => void;
+}
+/**
+ * Props for FormArray.AddButton component
+ *
+ * Generic `T` — тип элемента массива. По умолчанию `FormFields` (широкий) —
+ * для совместимости. Для type-safe initialValue передавайте generic явно
+ * (`<FormArray.AddButton<PropertyItem> ...>`) либо проксируйте через
+ * `FormArraySection<T>` из `@reformer/ui-kit`.
+ */
+export interface FormArrayAddButtonProps<T extends FormFields = FormFields> extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, 'onClick'> {
+    /** Initial value for the new item */
+    initialValue?: Partial<T>;
+    /** Custom render function for the button */
+    asChild?: boolean;
+}
+/**
+ * Props for FormArray.RemoveButton component
+ */
+export interface FormArrayRemoveButtonProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, 'onClick'> {
+    /** Custom render function for the button */
+    asChild?: boolean;
+}
+/**
+ * Props for FormArray.Empty component
+ */
+export interface FormArrayEmptyProps {
+    /** Content to show when array is empty */
+    children: ReactNode;
+}
+/**
+ * Props for FormArray.Count component
+ */
+export interface FormArrayCountProps {
+    /** Custom render function for the count */
+    render?: (count: number) => ReactNode;
+}
+/**
+ * Props for FormArray.ItemIndex component
+ */
+export interface FormArrayItemIndexProps {
+    /** Custom render function for the index (receives 0-based index) */
+    render?: (index: number) => ReactNode;
+}

package/dist/components/form-array/useFormArray.d.ts

@@ -0,0 +1,95 @@
+import { ArrayNode, FormFields, FormProxy } from '@reformer/core';
+/**
+ * Represents a single item in a form array with its control, index, and actions
+ */
+export interface FormArrayItem<T extends FormFields> {
+    /** The form control for this item */
+    control: FormProxy<T>;
+    /** Zero-based index of the item in the array */
+    index: number;
+    /** Unique identifier for React key (uses internal id or falls back to index) */
+    id: string | number;
+    /** Remove this item from the array */
+    remove: () => void;
+}
+/**
+ * Return type for useFormArray hook
+ */
+export interface UseFormArrayReturn<T extends FormFields> {
+    /** Array of items with their controls and actions */
+    items: FormArrayItem<T>[];
+    /** Current number of items in the array */
+    length: number;
+    /** Whether the array is empty */
+    isEmpty: boolean;
+    /** Add a new item to the end of the array */
+    add: (value?: Partial<T>) => void;
+    /** Remove all items from the array */
+    clear: () => void;
+    /** Insert a new item at a specific index */
+    insert: (index: number, value?: Partial<T>) => void;
+}
+/**
+ * Headless hook for managing form arrays
+ *
+ * Provides reactive state and actions for form array manipulation
+ * without any UI - perfect for building custom array interfaces.
+ *
+ * @example Basic usage
+ * ```tsx
+ * function PropertyList() {
+ *   const { items, add, isEmpty } = useFormArray(form.properties);
+ *
+ *   return (
+ *     <div>
+ *       {items.map(({ control, index, remove, id }) => (
+ *         <div key={id}>
+ *           <span>Property #{index + 1}</span>
+ *           <button onClick={remove}>Remove</button>
+ *           <PropertyForm control={control} />
+ *         </div>
+ *       ))}
+ *       {isEmpty && <p>No properties added</p>}
+ *       <button onClick={() => add()}>Add Property</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example With initial values + clear / insert
+ * ```tsx
+ * function PropertyToolbar() {
+ *   const { add, clear, insert, length } = useFormArray(form.properties);
+ *
+ *   return (
+ *     <div className="flex gap-2">
+ *       <button onClick={() => add({ type: 'apartment', estimatedValue: 0 })}>
+ *         + Квартира
+ *       </button>
+ *       <button onClick={() => insert(0, { type: 'house' })}>
+ *         + Дом (в начало)
+ *       </button>
+ *       <button onClick={clear} disabled={length === 0}>Очистить</button>
+ *       <span>{length} шт.</span>
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example Кастомный AddButton снаружи compound API (drop-down)
+ * ```tsx
+ * import { useFormArrayContext } from '@reformer/cdk/form-array';
+ *
+ * function AddPropertyMenu() {
+ *   const { add } = useFormArrayContext<Property>();
+ *   return (
+ *     <Menu>
+ *       <Menu.Trigger>+ Добавить ▾</Menu.Trigger>
+ *       <Menu.Item onSelect={() => add({ type: 'apartment' })}>Квартира</Menu.Item>
+ *       <Menu.Item onSelect={() => add({ type: 'house' })}>Дом</Menu.Item>
+ *     </Menu>
+ *   );
+ * }
+ * ```
+ */
+export declare function useFormArray<T extends FormFields>(control: ArrayNode<T>): UseFormArrayReturn<T>;