@companix/formkit 0.0.28 → 0.0.30

package/README.md

@@ -1,58 +1,320 @@
-## Create form primitives
+# @companix/formkit
+
+Формы на React одной декларативной схемой. Поля, раскладка, условия и проверка описываются деревом из обычных вызовов
+функций, а значения формы TypeScript выводит из самой схемы — без ручных интерфейсов, `useState` на каждое поле и
+`register` в разметке.
 
 ```tsx
-const SelectForm = (name: string) => {
-  // select form code
-}
-const InputForm = (name: string) => {
-  // input form code
-}
+const scheme = [
+  Label('Имя')(TextForm('name', { placeholder: 'Иван', $rules: { required: true } })),
+  CheckboxForm('hasCompany', { title: 'Представляю компанию' }),
+  Condition('hasCompany', { canActivate: (checked: boolean) => checked })(
+    Context('company')(Label('Компания')(TextForm('name', { placeholder: 'ООО «Ромашка»' })))
+  )
+]
+
+// onSubmit получит { name: string; hasCompany: boolean; company?: { name: string } }
+```
+
+`TextForm`, `CheckboxForm` и `Label` здесь — свои поле и раскладка проекта: как их завести, показано ниже.
+
+## Почему formkit
+
+- **Форма — данные, а не разметка.** Схема — массив, который собирают функциями: общий блок полей пишется один раз и
+  вставляется в любую форму, вариант формы — другой набор элементов, а не ветвление в JSX.
+- **Типы из схемы.** `onSubmit`, `onChange`, `defaultValues`, `setValue` и `useValue` знают имена и типы полей,
+  вложенные контексты и необязательность полей под условием.
+- **Поле пишется один раз.** `createForm` превращает любой компонент ввода в поле: умолчание, «что считать пустым» и
+  отрисовка ошибки живут в нём, а не в каждой форме.
+- **Условия и вложенность из коробки.** `Condition` показывает поля по значению другого поля, `Context` складывает их
+  в объект; скрытое поле не попадает ни в значения, ни в проверку.
+- **Состояние вне React.** Значения держит менеджер формы: правка поля перерисовывает это поле и тех, кто на него
+  подписан, а не всю форму и не экран вокруг неё.
+- **Изменённость.** Форма знает, что её правили, сообщает об этом и при отправке без изменений вызывает `onEqual`
+  вместо запроса.
+
+## Установка
+
+```sh
+npm i @companix/formkit
 ```
 
-## Create layouts
+Нужен React 18.
+
+## Форма за минуту
 
 ```tsx
-export const Label = createLayout((label: React.ReactNode) => {
-  return ({ children }) => {
-    return <FormGroup label={label}>{children}</FormGroup>
+import { useMemo } from 'react'
+import { createForm, createLayout, useForm, FormLayout } from '@companix/formkit'
+
+// поле: умолчание, проверка обязательности и компонент
+const TextForm = createForm<string, { placeholder: string }>({
+  defaultValue: '',
+  getRequireCheck: () => (value) => {
+    if (value.trim() === '') {
+      throw ''
+    }
+  },
+  getForm: ({ placeholder }) => {
+    return ({ field, error, disabled }) => {
+      return (
+        <div className="field">
+          <input
+            ref={field.ref}
+            value={field.value}
+            placeholder={placeholder}
+            disabled={disabled}
+            onChange={(e) => field.onChange(e.target.value)}
+          />
+          {error?.messages?.map((message) => (
+            <p key={message}>{message}</p>
+          ))}
+        </div>
+      )
+    }
   }
 })
 
-export const Double = createLayout(() => {
+// раскладка: подпись над полем
+const Label = createLayout((text: string) => {
   return ({ children }) => {
-    return <div className="form-double-primitive">{children}</div>
+    return (
+      <label className="label">
+        <span>{text}</span>
+        {children}
+      </label>
+    )
   }
 })
 
-export const Splitter = createLayout(() => {
-  return () => {
-    return <div className="form-splitter" />
+export const ProfileForm = () => {
+  const scheme = useMemo(() => {
+    return [
+      Label('Имя')(TextForm('name', { placeholder: 'Иван', $rules: { required: true } })),
+      Label('Город')(TextForm('city', { placeholder: 'Москва' }))
+    ]
+  }, [])
+
+  const form = useForm(scheme, {
+    defaultValues: { city: 'Москва' },
+    onSubmit: async (values) => {
+      await api.saveProfile(values) // values: { name: string; city: string }
+    }
+  })
+
+  return (
+    <>
+      <FormLayout manager={form.manager} />
+      <button onClick={form.handleSubmit}>Сохранить</button>
+    </>
+  )
+}
+```
+
+Менеджер формы создаётся один раз: схему и `defaultValues` `useForm` читает при первом рендере, поэтому схему держат в
+`useMemo`. `FormLayout` рисует схему и может стоять где угодно — в окне, на странице, в шаге мастера.
+
+## Поле — `createForm`
+
+Поле — это компонент ввода плюс три ответа: какое у него значение по умолчанию, что для него значит «пусто» и как его
+нарисовать по параметрам из схемы.
+
+```tsx
+const SelectForm = <T,>(defaultValue: T | null) => {
+  return createForm<T | null, { options: { value: T; title: string }[] }>({
+    defaultValue,
+    getRequireCheck: () => (value) => {
+      if (value === null) {
+        throw ''
+      }
+    },
+    getForm: ({ options }) => {
+      return ({ field, error }) => (
+        <Select options={options} value={field.value} onChange={field.onChange} error={error} />
+      )
+    }
+  })
+}
+
+SelectForm<'day' | 'night'>('day')('mode', { options: MODES })
+```
+
+Компонент получает `field` (`value`, `onChange`, `ref` для фокуса на ошибке), `error` и `disabled` формы. Умолчание,
+которое зависит от места, задают фабрикой, как у `SelectForm` выше: `NumberInputForm(1)('count', …)`.
+
+## Раскладка — `createLayout`
+
+Раскладка оборачивает поля разметкой. Параметр раскладки — один аргумент; раскладку без параметров вызывают сразу.
+
+```tsx
+const Card = createLayout(({ title, hint }: { title: string; hint?: string }) => {
+  return ({ children }) => (
+    <section className="card">
+      <h3>{title}</h3>
+      {hint && <p>{hint}</p>}
+      {children}
+    </section>
+  )
+})
+
+const Double = createLayout(() => {
+  return ({ children }) => <div className="double">{children}</div>
+})()
+
+Card({ title: 'Контакты', hint: 'Видят только менеджеры' })(
+  Double(TextForm('phone', { placeholder: '+7' }), TextForm('email', { placeholder: 'mail@site.ru' }))
+)
+```
+
+## Схема
+
+| Элемент                                  | Что делает                                                                | В значениях        |
+| ---------------------------------------- | ------------------------------------------------------------------------- | ------------------ |
+| `XForm('name', params)`                  | поле                                                                      | `name: V`          |
+| `Layout(params)(…)`                      | разметка вокруг полей                                                     | поля как есть      |
+| `Context('name')(…)`                     | вложенный объект: имена полей внутри — `name.field`                       | `name: { … }`      |
+| `Condition('field', { canActivate })(…)` | поля показаны, пока `canActivate(значение поля)` верно; имя — полный путь | поля необязательны |
+| `Visablility({ hidden })(…)`             | поля не рисуются, но несут значение из `defaultValues`                    | поля необязательны |
+| `createExtraForm(…)`                     | поля, которые пользователь добавляет и убирает сам                        | поля необязательны |
+
+Значения `onSubmit` и `onChange` выводятся из схемы сами, тип `defaultValues` схемы — `GetDefaultValues<typeof scheme>`.
+
+## Проверка
+
+```tsx
+TextForm('inn', {
+  placeholder: '12 цифр',
+  $rules: {
+    required: true,
+    validate: (value) => {
+      if (!/^\d{12}$/.test(value)) {
+        throw 'ИНН — 12 цифр'
+      }
+    }
   }
 })
 ```
 
-## Create a scheme
+- `required` проверяет поле его же `getRequireCheck`; `validate` — после него. Без `required` `validate` работает,
+  только если поле не пустое.
+- Проверка бросает строку: `throw ''` подсвечивает поле, `throw 'текст'` — с сообщением, массив строк — несколько
+  сообщений. Ошибку рисует компонент поля из `error.messages`.
+- `handleSubmit` проверяет поля, которые форма показывает, и ставит фокус на первое ошибочное. Поле скрытого условия
+  отправку не держит. После первой попытки поля проверяются на каждой правке.
+- Ошибку от сервера ставит `setError` из второго аргумента `onSubmit`: `setError('inn', { message: 'ИНН занят' })`.
 
-```ts
-const scheme = [
-  Label('Имя')(
-    SelectForm('name', {
-      placeholder: 'Введите имя',
-      options: []
-    })
-  ),
-  Splitter(),
-  Double()(
-    Label('Фамилия')(
-      InputForm('surname', {
-        placeholder: 'Введите фамилию'
-      })
-    ),
-    Label('Отчество')(
-      InputForm('patronymic', {
-        placeholder: 'Введите отчество'
-      })
+## Значения, умолчания и условия
+
+У поля два источника начального значения: умолчание компонента (`defaultValue` из `createForm`) и `defaultValues`
+формы. Стартовое значение — `defaultValues`, а без них — умолчание компонента. От стартового значения считается
+изменённость, и с него поле начинает:
+
+- при первом показе;
+- когда условие снова показывает поле: скрытое поле теряет значение и ошибку, вернувшееся — начинает заново со
+  стартового, а не с того, что ввели до скрытия.
+
+Значения формы — `onChange`, `getValues()` и отправка — это то, что форма показывает. Поля скрытых условий в них не
+входят, а поле, которое изменение только что открыло, входит сразу, ещё до монтирования, со стартовым значением.
+
+Отсюда простое правило: `defaultValues` — только данные. Где данных нет, передавайте `undefined`, и поле возьмёт своё
+умолчание; повторять умолчание поля в `defaultValues` не нужно.
+
+```tsx
+defaultValues: {
+  hasEscorts: escorts !== null,
+  escorts: escorts ?? undefined // нет данных — поля начнут со своих умолчаний
+}
+```
+
+## Живая форма и изменённость
+
+```tsx
+const form = useForm(scheme, {
+  defaultValues,
+  // значения после каждой правки — расчёт и подсказки поверх полей, без кнопки отправки
+  onChange: (values) => setDraft(toDraft(values)),
+  // форма изменена или снова стартовая
+  onFormDirty: (isDirty) => setDirty(isDirty),
+  // отправили без изменений
+  onEqual: () => close()
+})
+```
+
+- `onDirty` сообщает о каждом поле, `onFormDirty` — о форме целиком: первое изменение и снятие последнего.
+- `setAsDefault()` делает текущие значения стартовыми — после успешного сохранения.
+- `reset(values)` ставит новые значения и делает их стартовыми; поле, которого нет в `values`, получает умолчание
+  компонента. `reset(values, { asDirty: true })` оставляет новые значения изменением.
+- `setAsDefault()` и `reset(values)` сообщают «чисто» через `onDirty` и `onFormDirty`.
+
+## Управление формой
+
+`useForm` возвращает:
+
+| Метод                         | Что делает                                                             |
+| ----------------------------- | ---------------------------------------------------------------------- |
+| `manager`                     | менеджер для `FormLayout`                                              |
+| `handleSubmit()`              | проверка показанных полей и `onSubmit` (или `onEqual`)                 |
+| `getValues()`                 | значения формы — то, что она показывает                                |
+| `getValue(name)`              | значение поля по полному пути (`company.name`)                         |
+| `setValue(name, value)`       | запись поля, как ввод пользователя                                     |
+| `reset(values, options?)`     | новые значения, по умолчанию — стартовые                               |
+| `setAsDefault()`              | текущие значения — стартовые                                           |
+| `setError(name, { message })` | ошибка поля                                                            |
+| `setFocus(name)`              | фокус на поле                                                          |
+| `subscribe(name, callback)`   | подписка на поле; возвращает отписку                                   |
+| `subscribeAny(callback)`      | подписка на любую правку; возвращает отписку                           |
+| `getNames()`                  | полные пути всех полей схемы                                           |
+| `useValue(name)`              | хук внутри `FormLayout`: значение поля с перерисовкой и типом из схемы |
+
+## Внутри схемы: `useValue` и `useSetValue`
+
+Компоненты раскладок и поля читают и пишут соседние поля по полному пути. Хуки берут форму из контекста, поэтому
+работают внутри `FormLayout`:
+
+```tsx
+// подсказка, которая зависит от выбранной причины
+const ReasonHint = createLayout(() => {
+  return () => {
+    const reason = useValue<Reason | null>('reason')
+
+    return (
+      <p className="hint">
+        {reason === 'scan' ? 'Переснимут только отмеченные' : 'Анкета вернётся на шаг'}
+      </p>
     )
-  )
-]
+  }
+})()
+
+// подстановка из списка в поле контакта
+const ManagerPick = ({ managers }: { managers: Manager[] }) => {
+  const setName = useSetValue<string>('contact.name')
+
+  return <Menu items={managers} onSelect={(manager) => setName(manager.name)} />
+}
+```
+
+Типизированный `useValue` для схемы — `createUseValue<typeof scheme>()`.
+
+## Поля, которые добавляет пользователь
+
+```tsx
+// Removable — своя раскладка с кнопкой удаления, AddMenu — меню ещё не добавленных полей
+const Optional = createExtraForm({
+  getItems: (registry) => [
+    registry('phone')((name, remove) => Removable(remove)(TextForm(name, { placeholder: 'Телефон' }))),
+    registry('email')((name, remove) => Removable(remove)(TextForm(name, { placeholder: 'Почта' })))
+  ],
+  getController: (append, visible) => <AddMenu hidden={visible} onSelect={append} />
+})
 ```
+
+Поле добавлено, пока у него есть значение: в `defaultValues` — показано сразу, убранное — изменение формы.
+
+## 0.0.30
+
+- Поле, снова показанное условием, начинает со стартового значения (`defaultValues`), а не с умолчания компонента.
+- `onChange`, `getValues()` и отправка включают поля, которые изменение только что показало, — со стартовым значением,
+  до монтирования.
+- `handleSubmit` проверяет только показанные поля: скрытое поле отправку не держит. Ошибка скрытого поля сбрасывается.
+- Скрытое условием поле не считается изменённым — изменение несёт поле условия.
+- `setAsDefault()` и `reset()` сообщают «чисто» через `onDirty` и `onFormDirty`.

package/dist/bundle.es.js

@@ -1,342 +1,378 @@
-import { jsx as h, Fragment as w, jsxs as B } from "react/jsx-runtime";
-import { createContext as M, useState as R, useContext as T, useMemo as S, useEffect as $, useCallback as D, useRef as P } from "react";
-import L from "fast-deep-equal";
-const j = M({}), q = (o) => {
-  const [, r] = R([]), e = T(j);
+import { jsx as g, Fragment as N, jsxs as U } from "react/jsx-runtime";
+import { createContext as _, useState as B, useContext as T, useMemo as A, useEffect as m, useCallback as R, useRef as z } from "react";
+import O from "fast-deep-equal";
+const D = _({}), M = (n) => {
+  const [, r] = B([]), e = T(D);
   if (!e)
     throw new Error("useValue cannot be used outside Form context");
-  const s = S(() => {
-    const t = e.getForm(o);
+  const s = A(() => {
+    const t = e.getForm(n);
     if (!t)
-      throw new Error(`form with name "${o}" doesnt exist in form`);
+      throw new Error(`form with name "${n}" doesnt exist in form`);
     return t;
-  }, [e, o]);
-  return $(() => {
-    const t = e.subscribeToForm(o, () => {
+  }, [e, n]);
+  return m(() => {
+    const t = e.subscribeToForm(n, () => {
       r([]);
     });
     return () => {
       t();
     };
   }, []), s.value;
-}, K = () => (o) => q(o), O = ({ canActivate: o, name: r, children: e }) => {
-  const s = q(r);
-  return o(s) ? /* @__PURE__ */ h(w, { children: e }) : null;
-}, U = ({ item: { Form: o }, name: r }) => {
-  const [, e] = R([]), s = T(j), { unregistry: t } = S(() => s.registry(r, () => {
+}, Y = (n) => {
+  const r = T(D);
+  if (!r)
+    throw new Error("useSetValue cannot be used outside Form context");
+  return (e) => {
+    r.setValue(n, e);
+  };
+}, Z = () => (n) => M(n), G = ({ canActivate: n, name: r, children: e }) => {
+  const s = M(r);
+  return n(s) ? /* @__PURE__ */ g(N, { children: e }) : null;
+}, H = ({ item: { Form: n }, name: r }) => {
+  const [, e] = B([]), s = T(D), { unregistry: t } = A(() => s.registry(r, () => {
     e([]);
-  }), []), l = D(
-    (b) => {
-      if (b && b.focus) {
+  }), []), u = R(
+    (y) => {
+      if (y && y.focus) {
         const v = s.getForm(r);
         v.focus = () => {
-          b.focus();
+          y.focus();
         };
       }
     },
     [r]
   );
-  $(() => () => {
+  m(() => () => {
     t();
   }, []);
-  const { value: g, error: x } = s.getForm(r);
-  return /* @__PURE__ */ h(
-    o,
+  const { value: d, error: b } = s.getForm(r);
+  return /* @__PURE__ */ g(
+    n,
     {
       field: {
-        value: g,
-        onChange: (b) => {
-          s.onChange(r, b);
+        value: d,
+        onChange: (y) => {
+          s.onChange(r, y);
         },
         onBlur: () => {
         },
-        ref: l
+        ref: u
       },
       isDirty: !1,
-      error: x,
+      error: b,
       disabled: s.disabled
     }
   );
-}, _ = ({ item: o, path: r }) => {
-  const { getController: e, items: s } = o, t = T(j), l = S(() => {
-    const y = {};
-    return s.forEach(({ name: d, getForm: V }) => {
-      y[d] = V(d, () => a(d));
-    }), y;
-  }, []), g = D(() => {
-    const y = [];
-    return s.forEach(({ name: d }) => {
-      t.getForm([...r, d].join(".")).value !== void 0 && y.push(d);
-    }), y;
-  }, []), x = S(() => g(), []), [b, v] = R(x);
-  $(() => {
-    const { unregistry: y } = t.registryExtraForm(
-      s.map(({ name: d }) => [...r, d].join(".")),
+}, J = ({ item: n, path: r }) => {
+  const { getController: e, items: s } = n, t = T(D), u = A(() => {
+    const l = {};
+    return s.forEach(({ name: i, getForm: F }) => {
+      l[i] = F(i, () => j(i));
+    }), l;
+  }, []), d = R(() => {
+    const l = [];
+    return s.forEach(({ name: i }) => {
+      t.getForm([...r, i].join(".")).value !== void 0 && l.push(i);
+    }), l;
+  }, []), b = A(() => d(), []), [y, v] = B(b);
+  m(() => {
+    const { unregistry: l } = t.registryExtraForm(
+      s.map(({ name: i }) => [...r, i].join(".")),
       () => {
-        v(g());
+        v(d());
       }
     );
     return () => {
-      y();
+      l();
     };
   }, []);
-  const f = D(
-    (y) => {
-      l[y] && !b.includes(y) && v((d) => [...d, y]);
+  const x = R(
+    (l) => {
+      u[l] && !y.includes(l) && v((i) => [...i, l]);
     },
-    [b]
-  ), a = D((y) => {
-    v((d) => d.filter((V) => V !== y));
+    [y]
+  ), j = R((l) => {
+    v((i) => i.filter((F) => F !== l));
   }, []);
-  return /* @__PURE__ */ B(w, { children: [
-    b.map((y) => {
-      const d = l[y];
-      return /* @__PURE__ */ h(p, { path: r, scheme: [d] }, `param-form--${y}`);
+  return /* @__PURE__ */ U(N, { children: [
+    y.map((l) => {
+      const i = u[l];
+      return /* @__PURE__ */ g(p, { path: r, scheme: [i] }, `param-form--${l}`);
     }),
-    e(f, b)
+    e(x, y)
   ] });
-}, p = ({ scheme: o, path: r }) => /* @__PURE__ */ h(w, { children: o.map((e, s) => e.type === "layout" ? /* @__PURE__ */ h(e.Layout, { children: /* @__PURE__ */ h(p, { path: r, scheme: e.childs }) }, `layout-form--${s}-${r.length}`) : e.type === "context" ? /* @__PURE__ */ h(
+}, p = ({ scheme: n, path: r }) => /* @__PURE__ */ g(N, { children: n.map((e, s) => e.type === "layout" ? /* @__PURE__ */ g(e.Layout, { children: /* @__PURE__ */ g(p, { path: r, scheme: e.childs }) }, `layout-form--${s}-${r.length}`) : e.type === "context" ? /* @__PURE__ */ g(
   p,
   {
     path: [...r, e.context],
     scheme: e.childs
   },
   `context-form--${s}-${e.context}-${r.length}`
-) : e.type === "condition" ? /* @__PURE__ */ h(
-  O,
+) : e.type === "condition" ? /* @__PURE__ */ g(
+  G,
   {
     name: e.depended,
     canActivate: e.canActivate,
-    children: /* @__PURE__ */ h(p, { path: r, scheme: e.childs })
+    children: /* @__PURE__ */ g(p, { path: r, scheme: e.childs })
   },
   `condition--${s}-${e.depended}-${r.length}`
-) : e.type === "extra" ? /* @__PURE__ */ h(_, { path: r, item: e }, `partial-item--${s}-${r.length}`) : e.type === "visability" ? e.hidden ? null : /* @__PURE__ */ h(p, { path: r, scheme: e.childs }, `visability--${s}-${r.length}`) : /* @__PURE__ */ h(
-  U,
+) : e.type === "extra" ? /* @__PURE__ */ g(J, { path: r, item: e }, `partial-item--${s}-${r.length}`) : e.type === "visability" ? e.hidden ? null : /* @__PURE__ */ g(p, { path: r, scheme: e.childs }, `visability--${s}-${r.length}`) : /* @__PURE__ */ g(
+  H,
   {
     name: [...r, e.name].join("."),
     item: e
   },
   `form-item--${s}-${e.name}-${r.length}`
-)) }), C = (o, r, e, s) => {
-  o.forEach((t) => {
+)) }), $ = (n, r, e, s) => {
+  n.forEach((t) => {
     if (t.type === "form" && s(t, [...r, t.name].join("."), e[t.name]), t.type === "context") {
-      C(t.childs, [...r, t.context], e[t.context] ?? {}, s);
+      $(t.childs, [...r, t.context], e[t.context] ?? {}, s);
       return;
     }
     if (t.type === "layout" || t.type === "condition" || t.type === "visability") {
+      $(t.childs, r, e, s);
+      return;
+    }
+    t.type === "extra" && t.items.forEach(({ getForm: u, name: d }) => {
+      $([u(d, () => {
+      })], r, e, s);
+    });
+  });
+}, C = (n, r, e, s) => {
+  n.forEach((t) => {
+    if (t.type === "form" && s([...r, t.name].join(".")), t.type === "context") {
+      C(t.childs, [...r, t.context], e, s);
+      return;
+    }
+    if (t.type === "layout") {
       C(t.childs, r, e, s);
       return;
     }
-    t.type === "extra" && t.items.forEach(({ getForm: l, name: g }) => {
-      C([l(g, () => {
+    if (t.type === "visability" && !t.hidden) {
+      C(t.childs, r, e, s);
+      return;
+    }
+    if (t.type === "condition" && t.canActivate(e[t.depended]?.value)) {
+      C(t.childs, r, e, s);
+      return;
+    }
+    t.type === "extra" && t.items.forEach(({ getForm: u, name: d }) => {
+      e[[...r, d].join(".")]?.value !== void 0 && C([u(d, () => {
       })], r, e, s);
     });
   });
-}, E = ({ scheme: o, values: r, path: e, forms: s }) => {
-  o.forEach((t) => {
-    if (t.type === "form") {
-      const l = [...e, t.name].join(".");
-      s[l].value !== void 0 && (r[t.name] = s[l].value);
+}, S = ({ scheme: n, values: r, path: e, forms: s, shown: t }) => {
+  n.forEach((u) => {
+    if (u.type === "form") {
+      const { value: d, startValue: b } = s[[...e, u.name].join(".")];
+      d !== void 0 && (r[u.name] = d), d === void 0 && t && (r[u.name] = b);
     }
-    if (t.type === "context") {
-      r[t.context] = {}, E({
-        scheme: t.childs,
-        path: [...e, t.context],
-        values: r[t.context],
-        forms: s
+    if (u.type === "context") {
+      r[u.context] = {}, S({
+        scheme: u.childs,
+        path: [...e, u.context],
+        values: r[u.context],
+        forms: s,
+        shown: t
       });
       return;
     }
-    if (t.type === "layout") {
-      E({ scheme: t.childs, path: e, values: r, forms: s });
+    if (u.type === "layout") {
+      S({ scheme: u.childs, path: e, values: r, forms: s, shown: t });
       return;
     }
-    if (t.type === "visability") {
-      E({ scheme: t.childs, path: e, values: r, forms: s });
+    if (u.type === "visability") {
+      S({ scheme: u.childs, path: e, values: r, forms: s, shown: t && !u.hidden });
       return;
     }
-    if (t.type === "condition") {
-      const l = s[t.depended]?.value;
-      if (t.canActivate(l)) {
-        E({ scheme: t.childs, path: e, values: r, forms: s });
+    if (u.type === "condition") {
+      const d = s[u.depended]?.value;
+      if (u.canActivate(d)) {
+        S({ scheme: u.childs, path: e, values: r, forms: s, shown: t });
         return;
       }
     }
-    t.type === "extra" && t.items.forEach(({ getForm: l, name: g }) => {
-      E({ scheme: [l(g, () => {
-      })], path: e, values: r, forms: s });
+    u.type === "extra" && u.items.forEach(({ getForm: d, name: b }) => {
+      S({ scheme: [d(b, () => {
+      })], path: e, values: r, forms: s, shown: !1 });
     });
   });
-}, N = (o, r) => {
+}, L = (n, r) => {
   const e = {};
-  return E({ scheme: o, path: [], values: e, forms: r }), e;
-}, z = (o, r) => {
-  const { onSubmit: e, onEqual: s, disabled: t, onDirty: l, onFormDirty: g, onChangeEvent: x, defaultValues: b } = r, v = { onSubmit: e }, f = {
+  return S({ scheme: n, path: [], values: e, forms: r, shown: !0 }), e;
+}, K = (n, r) => {
+  const { onSubmit: e, onChange: s, onEqual: t, disabled: u, onDirty: d, onFormDirty: b, onChangeEvent: y, defaultValues: v } = r, x = { onSubmit: e }, j = { onChange: s }, l = {
     isActive: !1,
     isSubmitted: !1,
     dirtyCount: 0
-  }, a = {}, y = /* @__PURE__ */ new Set(), d = {
+  }, i = {}, F = /* @__PURE__ */ new Set(), E = {
     subscribers: [],
     names: {}
   };
-  C(o, [], b ?? {}, (n, u, i) => {
-    a[u] = {
+  $(n, [], v ?? {}, (o, a, c) => {
+    i[a] = {
       error: null,
       isDirty: !1,
-      value: i,
-      // текущее (динамическое) состояние поля. Значение равно переданному дефолтному, либо: определяется как дефолтное значение компонента формы в момент его монтирования, а до этого - undefined.
-      startValue: i ?? n.defaultValue,
-      // начальное (стартовое) значение (равно переданному дефолтному, либо значению формы по умолчанию). Исходя из сравнения текущего значения со стартовым, можно понять, модифицированно ли поле
-      defaultValue: n.defaultValue,
+      value: c,
+      // текущее (динамическое) состояние поля. Значение равно переданному дефолтному, либо: определяется как стартовое значение в момент монтирования поля, а до этого - undefined. Поле, которое скрыло условие, значения не имеет.
+      startValue: c ?? o.defaultValue,
+      // начальное (стартовое) значение (равно переданному дефолтному, либо значению формы по умолчанию). С него начинает поле при монтировании, в том числе снова показанное условием; исходя из сравнения текущего значения со стартовым, можно понять, модифицированно ли поле
+      defaultValue: o.defaultValue,
       // дефолтное значение компонента формы
       rerender: () => {
       },
       subscribers: [],
-      validate: n.validate
+      validate: o.validate
     };
   });
-  const V = (n, u) => {
-    l?.({ name: n, isDirty: u }), u && f.dirtyCount === 0 && g?.(!0), !u && f.dirtyCount === 1 && g?.(!1), f.dirtyCount += u ? 1 : -1;
+  const q = (o, a) => {
+    d?.({ name: o, isDirty: a }), a && l.dirtyCount === 0 && b?.(!0), !a && l.dirtyCount === 1 && b?.(!1), l.dirtyCount += a ? 1 : -1;
+  }, P = () => {
+    for (const o in i)
+      i[o].isDirty && (q(o, !1), i[o].isDirty = !1);
   };
   return {
-    submitRef: v,
-    scheme: o,
-    disabled: t,
+    submitRef: x,
+    changeRef: j,
+    scheme: n,
+    disabled: u,
     activate() {
-      f.isActive = !0;
+      l.isActive = !0;
     },
     disactivate() {
-      f.isActive = !1;
+      l.isActive = !1;
     },
-    setError(n, u) {
-      const i = this.getForm(n);
-      i && (i.error = {
+    setError(o, a) {
+      const c = this.getForm(o);
+      c && (c.error = {
         error: !0,
-        messages: [u.message]
-      }, i.rerender());
+        messages: [a.message]
+      }, c.rerender());
     },
-    setFocus(n) {
-      const u = this.getForm(n);
-      u && u.focus && u.focus();
+    setFocus(o) {
+      const a = this.getForm(o);
+      a && a.focus && a.focus();
     },
-    setValue(n, u) {
-      const i = this.getForm(n);
-      i && i.value !== u && this.onChange(n, u);
+    setValue(o, a) {
+      const c = this.getForm(o);
+      c && c.value !== a && this.onChange(o, a);
     },
     getValues() {
-      return N(o, a);
+      return L(n, i);
     },
     async handleSubmit() {
-      if (t)
+      if (u)
         return;
-      f.isSubmitted = !0;
-      let n = !1, u = !1;
-      for (const i in a) {
-        const c = a[i];
-        if (c.value !== void 0) {
-          const F = c.validate(c.value);
-          F && (u = !0, c.error = F, c.rerender(), !n && c.focus && (c.focus(), n = !0));
+      l.isSubmitted = !0;
+      let o = !1, a = !1;
+      if (C(n, [], i, (c) => {
+        const f = i[c];
+        if (f.value !== void 0) {
+          const h = f.validate(f.value);
+          h && (a = !0, f.error = h, f.rerender(), !o && f.focus && (f.focus(), o = !0));
         }
-      }
-      if (!u) {
-        if (f.dirtyCount === 0 && s) {
-          s();
+      }), !a) {
+        if (l.dirtyCount === 0 && t) {
+          t();
           return;
         }
-        const i = N(o, a);
-        await v.onSubmit(i, {
-          setError: (c, F) => {
-            const m = this.getForm(c);
-            m.error = {
+        if (!x.onSubmit)
+          return;
+        const c = L(n, i);
+        await x.onSubmit(c, {
+          setError: (f, h) => {
+            const V = this.getForm(f);
+            V.error = {
               error: !0,
-              messages: [F.message]
-            }, m.rerender();
+              messages: [h.message]
+            }, V.rerender();
           }
-        }).catch((c) => {
-          console.log("[formkit] submit exception:", c);
+        }).catch((f) => {
+          console.log("[formkit] submit exception:", f);
         });
       }
     },
-    reset(n, { asDirty: u }) {
-      C(o, [], n, (i, c, F) => {
-        if (F === void 0 && a[c].value === void 0)
+    reset(o, { asDirty: a }) {
+      $(n, [], o, (c, f, h) => {
+        if (h === void 0 && i[f].value === void 0)
           return;
-        if (d.names[c] && F === void 0) {
-          a[c].value = void 0;
+        if (E.names[f] && h === void 0) {
+          i[f].value = void 0;
           return;
         }
-        const m = F ?? i.defaultValue;
-        u || (a[c].startValue = m, a[c].isDirty = !1), a[c].value !== m && this.onChange(c, m);
-      }), u || (f.dirtyCount = 0, f.isSubmitted = !1), d.subscribers.forEach(({ visualizeEvalueatedForms: i }) => {
-        i();
+        const V = h ?? c.defaultValue;
+        a || (i[f].startValue = V), i[f].value !== V && this.onChange(f, V);
+      }), a || (P(), l.isSubmitted = !1), E.subscribers.forEach(({ visualizeEvalueatedForms: c }) => {
+        c();
       });
     },
     setAsDefault() {
-      C(o, [], {}, (n, u) => {
-        a[u].startValue = a[u].value, a[u].isDirty = !1;
-      }), f.dirtyCount = 0, f.isSubmitted = !1;
+      $(n, [], {}, (o, a) => {
+        i[a].startValue = i[a].value ?? i[a].defaultValue;
+      }), P(), l.isSubmitted = !1;
     },
-    registry(n, u) {
-      return a[n].rerender = u, a[n].value === void 0 && (a[n].value = a[n].defaultValue), {
+    registry(o, a) {
+      return i[o].rerender = a, i[o].value === void 0 && (i[o].value = E.names[o] ? i[o].defaultValue : i[o].startValue), {
         unregistry() {
-          if (a[n].rerender = () => {
-          }, a[n].focus = void 0, f.isActive) {
-            a[n].value = void 0;
-            const i = !L(a[n].startValue, a[n].defaultValue);
-            a[n].isDirty !== i && V(n, i), a[n].isDirty = i;
+          if (i[o].rerender = () => {
+          }, i[o].focus = void 0, l.isActive) {
+            i[o].value = void 0, i[o].error = null;
+            const c = E.names[o] ? !O(i[o].startValue, i[o].defaultValue) : !1;
+            i[o].isDirty !== c && q(o, c), i[o].isDirty = c;
           }
         }
       };
     },
-    getForm(n) {
-      return a[n];
+    getForm(o) {
+      return i[o];
     },
-    subscribeToForm(n, u) {
-      const i = { callback: u }, c = this.getForm(n);
-      return c.subscribers.push(i), () => {
-        c.subscribers = c.subscribers.filter((F) => F !== i);
+    subscribeToForm(o, a) {
+      const c = { callback: a }, f = this.getForm(o);
+      return f.subscribers.push(c), () => {
+        f.subscribers = f.subscribers.filter((h) => h !== c);
       };
     },
-    subscribeToAny(n) {
-      return y.add(n), () => {
-        y.delete(n);
+    subscribeToAny(o) {
+      return F.add(o), () => {
+        F.delete(o);
       };
     },
     getNames() {
-      return Object.keys(a);
+      return Object.keys(i);
     },
-    registryExtraForm(n, u) {
-      const i = { visualizeEvalueatedForms: u };
-      return n.forEach((c) => {
-        d.names[c] = !0;
-      }), d.subscribers.push(i), {
+    registryExtraForm(o, a) {
+      const c = { visualizeEvalueatedForms: a };
+      return o.forEach((f) => {
+        E.names[f] = !0;
+      }), E.subscribers.push(c), {
         unregistry() {
-          d.subscribers = d.subscribers.filter((c) => c !== i);
+          E.subscribers = E.subscribers.filter((f) => f !== c);
         }
       };
     },
-    onChange(n, u) {
-      const i = this.getForm(n), c = !L(u, i.startValue);
-      i.isDirty !== c && V(n, c), i.isDirty = c, x?.({ name: n, value: u }), (i.error || f.isSubmitted) && (i.error = i.validate(u) || null);
-      const F = i.value;
-      i.value = u, i.rerender(), i.subscribers.forEach(({ callback: m }) => {
-        m(u, F);
-      }), y.forEach((m) => {
-        m();
-      });
+    onChange(o, a) {
+      const c = this.getForm(o), f = !O(a, c.startValue);
+      c.isDirty !== f && q(o, f), c.isDirty = f, y?.({ name: o, value: a }), (c.error || l.isSubmitted) && (c.error = c.validate(a) || null);
+      const h = c.value;
+      c.value = a, c.rerender(), c.subscribers.forEach(({ callback: V }) => {
+        V(a, h);
+      }), F.forEach((V) => {
+        V();
+      }), j.onChange?.(L(n, i));
     }
   };
-}, Q = (o, r) => {
-  const e = P(null);
-  e.current === null && (e.current = z(o, r));
+}, k = (n, r) => {
+  const e = z(null);
+  e.current === null && (e.current = K(n, r));
   const s = e.current;
-  return $(() => {
-    e.current && (e.current.submitRef.onSubmit = r.onSubmit);
-  }, [r.onSubmit]), {
+  return m(() => {
+    e.current && (e.current.submitRef.onSubmit = r.onSubmit, e.current.changeRef.onChange = r.onChange);
+  }, [r.onSubmit, r.onChange]), {
     manager: s,
-    useValue: (t) => q(t),
-    reset: (t, l = {}) => {
-      s.reset(t, l);
+    useValue: (t) => M(t),
+    reset: (t, u = {}) => {
+      s.reset(t, u);
     },
     setAsDefault: () => {
       s.setAsDefault();
@@ -344,11 +380,11 @@ const j = M({}), q = (o) => {
     setFocus: (t) => {
       s.setFocus(t);
     },
-    setError: (t, l) => {
-      s.setError(t, l);
+    setError: (t, u) => {
+      s.setError(t, u);
     },
-    setValue: (t, l) => {
-      s.setValue(t, l);
+    setValue: (t, u) => {
+      s.setValue(t, u);
     },
     getValue: (t) => s.getForm(t).value,
     getValues: () => s.getValues(),
@@ -356,19 +392,19 @@ const j = M({}), q = (o) => {
       await s.handleSubmit();
     },
     // prettier-ignore
-    subscribe: (t, l) => s.subscribeToForm(t, l),
+    subscribe: (t, u) => s.subscribeToForm(t, u),
     // подписка на любое изменение значений формы (для гейтов поверх всех полей)
     subscribeAny: (t) => s.subscribeToAny(t),
     // плоский список имён всех полей (dotted-пути; вложенные context раскрыты)
     getNames: () => s.getNames()
   };
-}, W = ({ manager: o }) => (S(() => {
-  o.activate();
-}, []), $(() => () => {
-  o.disactivate();
-}, []), /* @__PURE__ */ h(j.Provider, { value: o, children: /* @__PURE__ */ h(p, { scheme: o.scheme, path: [] }) })), A = (o) => {
+}, I = ({ manager: n }) => (A(() => {
+  n.activate();
+}, []), m(() => () => {
+  n.disactivate();
+}, []), /* @__PURE__ */ g(D.Provider, { value: n, children: /* @__PURE__ */ g(p, { scheme: n.scheme, path: [] }) })), w = (n) => {
   try {
-    o();
+    n();
   } catch (r) {
     return r && typeof r == "string" ? {
       error: !0,
@@ -380,66 +416,67 @@ const j = M({}), q = (o) => {
       error: !0
     };
   }
-}, X = (o) => (r, e) => {
-  const s = o.getRequireCheck(e), { $rules: t = {}, ...l } = e, { validate: g, required: x } = t;
+}, rr = (n) => (r, e) => {
+  const s = n.getRequireCheck(e), { $rules: t = {}, ...u } = e, { validate: d, required: b } = t;
   return {
     type: "form",
     name: r,
-    defaultValue: o.defaultValue,
-    Form: o.getForm(l),
-    validate: (b) => {
-      if (x) {
-        const v = A(() => s(b));
+    defaultValue: n.defaultValue,
+    Form: n.getForm(u),
+    validate: (y) => {
+      if (b) {
+        const v = w(() => s(y));
         if (v)
           return v;
-        if (g) {
-          const f = A(() => g(b));
-          if (f)
-            return f;
+        if (d) {
+          const x = w(() => d(y));
+          if (x)
+            return x;
         }
         return;
       }
-      if (g && !A(() => s(b))) {
-        const f = A(() => g(b));
-        if (f)
-          return f;
+      if (d && !w(() => s(y))) {
+        const x = w(() => d(y));
+        if (x)
+          return x;
       }
     }
   };
-}, Y = (o) => (r) => (...e) => ({
+}, er = (n) => (r) => (...e) => ({
   type: "layout",
-  Layout: o(r),
+  Layout: n(r),
   childs: e
-}), Z = ({
-  getItems: o,
+}), tr = ({
+  getItems: n,
   getController: r
 }) => ({
   type: "extra",
-  items: o((e) => (s) => ({ type: "registry", name: e, getForm: s })),
+  items: n((e) => (s) => ({ type: "registry", name: e, getForm: s })),
   getController: r
-}), k = (o) => (...r) => ({
+}), sr = (n) => (...r) => ({
   type: "context",
-  context: o,
+  context: n,
   childs: r
-}), I = (o, r) => (...e) => ({
+}), nr = (n, r) => (...e) => ({
   type: "condition",
-  depended: o,
+  depended: n,
   canActivate: r.canActivate,
   childs: e
-}), rr = ({ hidden: o }) => (...r) => ({
+}), or = ({ hidden: n }) => (...r) => ({
   type: "visability",
-  hidden: o ?? !1,
+  hidden: n ?? !1,
   childs: r
 });
 export {
-  I as Condition,
-  k as Context,
-  W as FormLayout,
-  rr as Visablility,
-  Z as createExtraForm,
-  X as createForm,
-  Y as createLayout,
-  K as createUseValue,
-  Q as useForm,
-  q as useValue
+  nr as Condition,
+  sr as Context,
+  I as FormLayout,
+  or as Visablility,
+  tr as createExtraForm,
+  rr as createForm,
+  er as createLayout,
+  Z as createUseValue,
+  k as useForm,
+  Y as useSetValue,
+  M as useValue
 };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export { useForm, FormLayout } from './useForm';
-export { useValue, createUseValue } from './useValue';
+export { useValue, useSetValue, createUseValue } from './useValue';
 export { createForm } from './core/builders/create-form';
 export { createLayout } from './core/builders/create-layout';
 export { createExtraForm } from './core/builders/create-extra-form';

package/dist/manager/manager.d.ts

@@ -22,7 +22,10 @@ export interface ResetOptions {
 }
 export interface FormManager<Values, FlattenValues, ClonedValues> {
     submitRef: {
-        onSubmit: (values: Values, callbacks: SubmitCallbacls<FlattenValues>) => void;
+        onSubmit?: (values: Values, callbacks: SubmitCallbacls<FlattenValues>) => Promise<void>;
+    };
+    changeRef: {
+        onChange?: (values: Values) => void;
     };
     scheme: SchemeItems.All[];
     disabled?: boolean;

package/dist/manager/read-scheme.d.ts

@@ -1,5 +1,8 @@
+import { Forms } from './manager';
 import { FieldValues } from '../types';
 import { SchemeItems } from '../core/types';
 type cb = (item: SchemeItems.Form, name: string, value?: any) => void;
+type shownCb = (name: string) => void;
 declare const readScheme: (scheme: SchemeItems.All[], path: string[], values: FieldValues, callback: cb) => void;
-export { readScheme };
+declare const readShown: (scheme: SchemeItems.All[], path: string[], forms: Forms, callback: shownCb) => void;
+export { readScheme, readShown };

package/dist/useForm.d.ts

@@ -30,7 +30,8 @@ export interface MainOptions<Values extends FieldValues, FlattenValues, ClonedVa
     onDirty?: (event: DirtyEvent<FlattenValues>) => void;
     onChangeEvent?: (event: ChangeEvent<FlattenValues>) => void;
     onFormDirty?: (isDirty: boolean) => void;
-    onSubmit: (values: Values, callbacks: SubmitCallbacls<FlattenValues>) => Promise<void>;
+    onChange?: (values: Values) => void;
+    onSubmit?: (values: Values, callbacks: SubmitCallbacls<FlattenValues>) => Promise<void>;
 }
 export type GetDefaultValues<Items extends SchemeItems.All[]> = DeepPartial<ExtractValues<Items[number]>>;
 declare const useDynamicForm: (scheme: SchemeItems.All[], opts: MainOptions<FieldValues, FieldValues, FieldValues>) => {

package/dist/useValue.d.ts

@@ -1,4 +1,5 @@
 import { SchemeItems } from './core/types';
 import { ExtractFlatValues } from './core/extract';
 export declare const useValue: <T = any>(name: string) => T;
+export declare const useSetValue: <T = any>(name: string) => (value: T) => void;
 export declare const createUseValue: <Items extends SchemeItems.All[]>() => <FlattenValues extends ExtractFlatValues<Items[number]>, K extends keyof FlattenValues>(name: K & string) => FlattenValues[K];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@companix/formkit",
-  "version": "0.0.28",
+  "version": "0.0.30",
   "module": "./dist/bundle.es.js",
   "types": "./dist/index.d.ts",
   "type": "module",