@inl0re/blnk 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 blnk contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,148 @@
+# blnk
+
+`blnk` is an MVP React 19 form library with React Hook Form-like DX and a subscription-based mutable store under the hood. Inputs stay uncontrolled, while fields and selected form state can subscribe to precise updates.
+
+## Docs
+
+- [Subscriptions](./docs/concepts/subscriptions.md)
+- [Uncontrolled inputs](./docs/concepts/uncontrolled-inputs.md)
+- [Conditional fields](./docs/guides/conditional-fields.md)
+- [Field arrays](./docs/guides/field-arrays.md)
+- [Validation](./docs/guides/validation.md)
+- [Transactions](./docs/guides/transactions.md)
+
+## Examples
+
+- [LoginFormExample](./src/examples/LoginFormExample.tsx)
+- [WizardFormExample](./src/examples/WizardFormExample.tsx)
+- [ServerPatchTransactionExample](./src/examples/ServerPatchTransactionExample.tsx)
+- [ControlledInputExample](./src/examples/ControlledInputExample.tsx)
+- [CheckboxConditionalFieldExample](./src/examples/CheckboxConditionalFieldExample.tsx)
+- [ComplexFormExample](./src/examples/ComplexFormExample.tsx)
+
+## Basic Usage
+
+```tsx
+import { useForm } from "blnk";
+
+type FormValues = {
+  user: {
+    email: string;
+    age: number;
+  };
+};
+
+const form = useForm<FormValues>({
+  defaultValues: {
+    user: { email: "", age: 18 },
+  },
+});
+
+<form onSubmit={form.handleSubmit((data) => console.log(data.user.email))}>
+  <input {...form.register("user.email")} />
+  <input type="number" {...form.register("user.age", { valueAsNumber: true })} />
+</form>;
+```
+
+## Nested Fields
+
+Dot paths support nested objects and arrays:
+
+```ts
+form.setValue("user.age", 25);
+form.setValue("addresses.0.city", "Minsk");
+form.watch("user.email");
+form.reset();
+```
+
+`register`, `setValue`, `watch`, and `handleSubmit` are generic-aware through `Path<T>` and `PathValue<T, P>`.
+
+## Validation Resolver
+
+Use a custom resolver:
+
+```ts
+const form = useForm<FormValues>({
+  resolver: async (values) => ({
+    values,
+    errors: values.user.email ? {} : { user: { email: { type: "required", message: "Required" } } },
+  }),
+});
+```
+
+Zod-like and Yup-like schemas are supported through lightweight adapters:
+
+```ts
+import { zodResolver } from "blnk";
+
+const form = useForm<FormValues>({
+  schema: userSchema,
+  resolver: zodResolver(userSchema),
+  mode: "onBlur",
+});
+```
+
+## Async Validation
+
+Field-level validators can be sync or async. Async validators support debouncing and stale result protection.
+
+```ts
+const form = useForm<FormValues>({
+  asyncValidatorDebounceMs: 250,
+  asyncValidators: {
+    "user.email": async (email) => {
+      const exists = await api.checkEmail(email);
+      return exists ? "Email already exists" : true;
+    },
+  },
+});
+```
+
+## Field Arrays
+
+`useFieldArray` keeps stable `id` values for React keys.
+
+```tsx
+const skills = useFieldArray({ control: form.control, name: "skills" });
+
+skills.append({ title: "", level: "junior" });
+skills.remove(0);
+skills.move(0, 1);
+```
+
+## Subscriptions
+
+Use `useWatch` when React UI needs to rerender from form values, `useField` for field-level snapshots, and `useFormState` for selector-based form state subscriptions.
+
+```ts
+const emailValue = useWatch({ control: form.control, name: "user.email" });
+const email = useField(form.control, "user.email");
+
+const state = useFormState({
+  control: form.control,
+  selector: (formState) => ({
+    error: formState.errors.user?.email,
+    isDirty: formState.isDirty,
+  }),
+});
+```
+
+`form.watch("user.email")` is an imperative read. `form.watch("user.email", callback)` is an imperative subscription. `useWatch` is the React hook for conditional UI.
+
+## Transactions
+
+Transactions batch several mutations into one notification wave.
+
+```ts
+form.transaction(() => {
+  form.setValue("user.name", "Gleb");
+  form.setValue("user.email", "gleb@example.com");
+  form.setValue("user.age", 25);
+});
+```
+
+## MVP Limits
+
+- Field array metadata cleanup is still newer than the core field path flow, so keep array-heavy forms covered by tests.
+- Resolver adapters are duck-typed to keep Zod/Yup optional peer dependencies.
+- Package publishing metadata is intentionally minimal.

package/README.ru.md

@@ -0,0 +1,476 @@
+# blnk
+
+## Docs
+
+- [Subscriptions](./docs/concepts/subscriptions.md)
+- [Uncontrolled inputs](./docs/concepts/uncontrolled-inputs.md)
+- [Conditional fields](./docs/guides/conditional-fields.md)
+- [Field arrays](./docs/guides/field-arrays.md)
+- [Validation](./docs/guides/validation.md)
+- [Transactions](./docs/guides/transactions.md)
+
+## Examples
+
+- [LoginFormExample](./src/examples/LoginFormExample.tsx)
+- [WizardFormExample](./src/examples/WizardFormExample.tsx)
+- [ServerPatchTransactionExample](./src/examples/ServerPatchTransactionExample.tsx)
+- [ControlledInputExample](./src/examples/ControlledInputExample.tsx)
+- [CheckboxConditionalFieldExample](./src/examples/CheckboxConditionalFieldExample.tsx)
+- [ComplexFormExample](./src/examples/ComplexFormExample.tsx)
+
+`blnk` — библиотека форм для React 19. Снаружи она похожа на React Hook Form: ты вызываешь `useForm`, регистрируешь поля через `register` и отправляешь форму через `handleSubmit`. Внутри она работает иначе: значения лежат в mutable store, а компоненты подписываются только на нужные поля.
+
+Это значит, что ввод в одно поле не должен перерисовывать всю форму.
+
+## Самый короткий пример
+
+Этот пример показывает главный сценарий: создать форму, подключить input и получить типизированные данные при submit.
+
+```tsx
+import { useForm } from "blnk";
+
+type FormValues = {
+  user: {
+    email: string;
+    age: number;
+  };
+};
+
+const form = useForm<FormValues>({
+  defaultValues: {
+    user: { email: "", age: 18 },
+  },
+});
+
+return (
+  <form onSubmit={form.handleSubmit((data) => console.log(data.user.email))}>
+    <input {...form.register("user.email")} />
+    <input type="number" {...form.register("user.age", { valueAsNumber: true })} />
+    <button type="submit">Save</button>
+  </form>
+);
+```
+
+Что здесь важно:
+
+- `FormValues` описывает форму целиком
+- `register("user.email")` знает, что такое поле существует
+- `data.user.email` типизирован внутри `handleSubmit`
+- `valueAsNumber` превращает строку из `<input type="number">` в число
+
+## Как устроен state
+
+`blnk` не хранит каждое значение input в React state. Вместо этого форма хранит значения во внутреннем объекте.
+
+Когда пользователь печатает:
+
+1. `register` получает событие из input
+2. библиотека достает значение из события
+3. значение записывается во внутренний store
+4. обновляются `dirtyFields`, `touchedFields` или `errors`
+5. уведомляются только подписчики этого поля
+
+Такой подход полезен для больших форм. Если изменилось `user.email`, компонент с `user.age` не обязан ререндериться.
+
+## Вложенные поля
+
+Поля записываются строками через точку.
+
+```ts
+form.setValue("user.age", 25);
+form.setValue("addresses.0.city", "Minsk");
+
+const email = form.watch("user.email");
+```
+
+Путь `addresses.0.city` означает: массив `addresses`, первый элемент, поле `city`.
+
+Типы тоже работают через эти пути:
+
+```ts
+form.setValue("user.age", 25);
+form.setValue("user.email", "gleb@example.com");
+```
+
+Если передать неправильный тип значения, TypeScript должен подсветить ошибку.
+
+## register
+
+`register` возвращает props для input.
+
+```tsx
+<input {...form.register("user.email")} />
+```
+
+На практике это объект:
+
+```ts
+{
+  name,
+  ref,
+  onChange,
+  onBlur,
+}
+```
+
+`onChange` пишет значение в store. `onBlur` отмечает поле как touched и может запустить валидацию, если форма настроена на `mode: "onBlur"`.
+
+Поддерживаются обычные HTML-поля:
+
+- text input
+- number input
+- checkbox
+- radio
+- select
+- textarea
+- file input
+
+## handleSubmit
+
+`handleSubmit` оборачивает твой submit handler.
+
+```tsx
+<form
+  onSubmit={form.handleSubmit(
+    (values) => {
+      console.log(values.user.email);
+    },
+    (errors) => {
+      console.log(errors);
+    },
+  )}
+>
+```
+
+При submit библиотека:
+
+1. вызывает `event.preventDefault()`
+2. ставит `formState.isSubmitting`
+3. запускает валидацию всей формы
+4. вызывает `onValid`, если ошибок нет
+5. вызывает `onInvalid`, если ошибки есть
+6. обновляет `isSubmitted` и `submitCount`
+7. снимает `isSubmitting`
+
+Submit handler может быть async.
+
+## watch
+
+`watch` можно использовать двумя способами.
+
+Получить текущее значение:
+
+```ts
+const email = form.watch("user.email");
+```
+
+Подписаться на изменения:
+
+```ts
+const unsubscribe = form.watch("user.email", (email) => {
+  console.log(email);
+});
+```
+
+Во втором варианте ты сам вызываешь `unsubscribe`, когда подписка больше не нужна.
+
+## useWatch
+
+`useWatch` нужен, когда значение поля должно управлять React UI.
+
+```ts
+const wantsDetails = useWatch({
+  control: form.control,
+  name: "wantsDetails",
+});
+```
+
+Пример: чекбокс показывает дополнительное поле.
+
+```tsx
+{
+  wantsDetails ? <input {...form.register("details")} /> : null;
+}
+```
+
+Разница простая:
+
+- `form.watch("field")` читает текущее значение
+- `form.watch("field", callback)` подписывается вручную
+- `useWatch(...)` подписывает React-компонент и вызывает ререндер
+
+## formState
+
+`formState` хранит служебное состояние формы.
+
+```ts
+form.formState.isDirty;
+form.formState.isSubmitting;
+form.formState.errors.user?.email;
+```
+
+Главные поля:
+
+- `errors`: ошибки валидации
+- `touchedFields`: поля, которые потеряли фокус
+- `dirtyFields`: поля, которые отличаются от `defaultValues`
+- `isDirty`: в форме есть измененные поля
+- `isValid`: в форме нет ошибок
+- `isValidating`: идет async validation
+- `isSubmitting`: идет submit
+- `isSubmitted`: форма уже отправлялась
+- `submitCount`: количество submit попыток
+
+## useField
+
+`useField` нужен, когда компонент должен следить только за одним полем.
+
+```ts
+const email = useField(form.control, "user.email");
+```
+
+Он возвращает:
+
+```ts
+{
+  value,
+  error,
+  isDirty,
+  isTouched,
+  isValidating,
+}
+```
+
+Если изменится другое поле, этот компонент не должен обновляться из-за него.
+
+## useFormState
+
+`useFormState` нужен, когда компоненту нужна не вся форма, а выбранная часть `formState`.
+
+```ts
+const state = useFormState({
+  control: form.control,
+  selector: (formState) => ({
+    error: formState.errors.user?.email,
+    isDirty: formState.isDirty,
+  }),
+});
+```
+
+Selector помогает не подписывать компонент на лишние изменения.
+
+## Валидация через resolver
+
+Resolver — это функция, которая получает все значения формы и возвращает либо данные, либо ошибки.
+
+```ts
+const form = useForm<FormValues>({
+  resolver: async (values) => ({
+    values,
+    errors: values.user.email
+      ? {}
+      : { user: { email: { type: "required", message: "Email is required" } } },
+  }),
+});
+```
+
+Формат ошибки:
+
+```ts
+{
+  type: "required",
+  message: "Email is required",
+}
+```
+
+Такой слой позволяет подключать любую схему валидации.
+
+## Zod и Yup
+
+В библиотеке есть адаптеры:
+
+```ts
+import { zodResolver, yupResolver } from "blnk";
+```
+
+Пример с Zod-like схемой:
+
+```ts
+const form = useForm<FormValues>({
+  resolver: zodResolver(userSchema),
+  mode: "onBlur",
+});
+```
+
+Zod и Yup не установлены как обязательные зависимости. Они указаны как optional peer dependencies, поэтому проект сам решает, нужны они ему или нет.
+
+## Field-level validation
+
+Валидацию можно повесить на конкретное поле.
+
+```tsx
+<input
+  {...form.register("user.email", {
+    required: "Email is required",
+    validate: (email) => email.includes("@") || "Email is invalid",
+  })}
+/>
+```
+
+`validate` возвращает:
+
+- `true`, если значение валидно
+- строку, если нужно показать ошибку
+- объект ошибки, если нужен свой `type`
+
+## Async validation
+
+Асинхронная валидация полезна для проверок на сервере. Например, проверить, занят ли email.
+
+```ts
+const form = useForm<FormValues>({
+  mode: "onBlur",
+  asyncValidatorDebounceMs: 250,
+  asyncValidators: {
+    "user.email": async (email) => {
+      const exists = await api.checkEmail(email);
+      return exists ? "Email already exists" : true;
+    },
+  },
+});
+```
+
+Важные детали:
+
+- debounce задерживает запрос, если пользователь продолжает ввод
+- stale result protection игнорирует старый ответ, если уже началась новая проверка
+- `formState.isValidating` показывает, что идет проверка
+- `formState.validatingFields` показывает, какие поля проверяются
+
+## Field arrays
+
+`useFieldArray` управляет массивами полей.
+
+```tsx
+const skills = useFieldArray({
+  control: form.control,
+  name: "skills",
+});
+
+skills.append({ title: "", level: "junior" });
+skills.remove(0);
+```
+
+`fields` содержит элементы массива плюс стабильный `id`.
+
+```tsx
+{
+  skills.fields.map((skill, index) => (
+    <div key={skill.id}>
+      <input {...form.register(`skills.${index}.title`)} />
+    </div>
+  ));
+}
+```
+
+Используй `skill.id` как React key. Не используй `index` как key, потому что при удалении или перемещении элементов React может перепутать DOM.
+
+Доступные операции:
+
+- `append`: добавить в конец
+- `remove`: удалить по индексу
+- `insert`: вставить по индексу
+- `move`: переместить
+- `swap`: поменять местами
+- `replace`: заменить весь массив
+
+## Transactions API
+
+Transaction нужна, когда ты меняешь сразу несколько полей.
+
+```ts
+form.transaction(() => {
+  form.setValue("user.name", "Gleb");
+  form.setValue("user.email", "gleb@example.com");
+  form.setValue("user.age", 25);
+});
+```
+
+Без transaction каждое изменение уведомляет подписчиков отдельно. Внутри transaction изменения применяются сразу, но уведомления отправляются одной пачкой после `commitTransaction`.
+
+Это удобно для:
+
+- server patches
+- wizard forms
+- autosave
+- заполнения формы из шаблона
+- массового reset части формы
+
+Низкоуровневый API тоже доступен:
+
+```ts
+form.beginTransaction();
+form.setValue("user.name", "Gleb");
+form.setValue("user.age", 25);
+form.commitTransaction();
+```
+
+В большинстве случаев удобнее использовать `form.transaction`.
+
+## reset
+
+`reset` возвращает форму к `defaultValues`.
+
+```ts
+form.reset();
+```
+
+Можно передать новые значения:
+
+```ts
+form.reset({
+  user: {
+    email: "new@example.com",
+    age: 30,
+  },
+});
+```
+
+После reset очищаются ошибки, touched, dirty и submit state.
+
+## Что уже есть
+
+- RHF-like API
+- uncontrolled inputs
+- mutable store
+- подписки на поля
+- selector-based подписки на `formState`
+- `useWatch` для условного React UI
+- nested paths
+- arrays и `useFieldArray`
+- custom resolver
+- Zod/Yup adapters
+- field-level validation
+- async validation с debounce
+- защита от race condition
+- transactions
+- TypeScript-типы для основных сценариев
+
+## Ограничения MVP
+
+- Нет adapter для controlled components
+- React rendering tests пока покрывают `useWatch` и checkbox conditional-field example
+- Очистка `errors`, `touched` и `dirty` при сложных перестановках field arrays пока базовая
+- Zod/Yup adapters используют duck typing
+- Package publishing metadata минимальная
+- `Path<T>` ограничен разумной глубиной, чтобы TypeScript не уходил в бесконечную рекурсию
+
+## Как проверить проект
+
+```bash
+npm test
+npm run typecheck
+npm run build
+```
+
+`lint`-скрипта сейчас нет.

package/dist/core/createFormControl.d.ts

@@ -0,0 +1,3 @@
+import type { FieldValues, FormControl, UseFormOptions } from "../types/form";
+export declare function createFormControl<T extends FieldValues>(options?: UseFormOptions<T>): FormControl<T>;
+//# sourceMappingURL=createFormControl.d.ts.map

package/dist/core/createFormControl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createFormControl.d.ts","sourceRoot":"","sources":["../../src/core/createFormControl.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEV,WAAW,EACX,WAAW,EAIX,cAAc,EAGf,MAAM,eAAe,CAAC;AA8DvB,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,WAAW,EACrD,OAAO,GAAE,cAAc,CAAC,CAAC,CAAM,GAC9B,WAAW,CAAC,CAAC,CAAC,CAwYhB"}

package/dist/core/fieldArrayState.d.ts

@@ -0,0 +1,23 @@
+export declare function getFieldArrayIds(control: object, name: string, length: number): string[];
+export declare function setFieldArrayIds(control: object, name: string, ids: string[]): void;
+export declare function createFieldArrayId(): string;
+export type FieldArrayMetadataOperation = {
+    type: "append";
+} | {
+    type: "remove";
+    index: number;
+} | {
+    type: "insert";
+    index: number;
+} | {
+    type: "move";
+    from: number;
+    to: number;
+} | {
+    type: "swap";
+    left: number;
+    right: number;
+} | {
+    type: "replace";
+};
+//# sourceMappingURL=fieldArrayState.d.ts.map

package/dist/core/fieldArrayState.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fieldArrayState.d.ts","sourceRoot":"","sources":["../../src/core/fieldArrayState.ts"],"names":[],"mappings":"AAiBA,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAWxF;AAED,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,IAAI,CAEnF;AAED,wBAAgB,kBAAkB,IAAI,MAAM,CAE3C;AAED,MAAM,MAAM,2BAA2B,GACnC;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,GAClB;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACjC;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACjC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GAC1C;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAC7C;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,CAAC"}

package/dist/core/fieldRegistry.d.ts

@@ -0,0 +1,9 @@
+import type { FieldValues, RegisterOptions } from "../types/form";
+import type { Path } from "../types/path";
+export type RegisteredField<T extends FieldValues> = {
+    ref: unknown;
+    options?: RegisterOptions<T, any>;
+};
+export declare function setRegisteredField<T extends FieldValues>(fields: Map<string, RegisteredField<T>>, refs: Map<string, unknown>, name: Path<T>, ref: unknown, options?: RegisterOptions<T, any>): void;
+export declare function unsetRegisteredField<T extends FieldValues>(fields: Map<string, RegisteredField<T>>, refs: Map<string, unknown>, name: Path<T>): void;
+//# sourceMappingURL=fieldRegistry.d.ts.map

package/dist/core/fieldRegistry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fieldRegistry.d.ts","sourceRoot":"","sources":["../../src/core/fieldRegistry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAClE,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,eAAe,CAAC;AAE1C,MAAM,MAAM,eAAe,CAAC,CAAC,SAAS,WAAW,IAAI;IACnD,GAAG,EAAE,OAAO,CAAC;IACb,OAAO,CAAC,EAAE,eAAe,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;CACnC,CAAC;AAEF,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,WAAW,EACtD,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC,CAAC,CAAC,EACvC,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,EAC1B,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,EACb,GAAG,EAAE,OAAO,EACZ,OAAO,CAAC,EAAE,eAAe,CAAC,CAAC,EAAE,GAAG,CAAC,GAChC,IAAI,CAIN;AAED,wBAAgB,oBAAoB,CAAC,CAAC,SAAS,WAAW,EACxD,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC,CAAC,CAAC,EACvC,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,EAC1B,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,GACZ,IAAI,CAIN"}