palistor 0.0.24

package/dist/index.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Palistor - State Manager для форм
+ *
+ * Архитектура: createForm + useForm(id)
+ *
+ * createForm() вызывается на уровне модуля — задаёт статическую конфигурацию.
+ * useForm(id) вызывается в React-компоненте — привязывает к экземпляру.
+ *
+ * @example
+ * ```ts
+ * // config/orderForm.ts — модульный уровень
+ * import { createForm } from 'palistor';
+ * import { useTranslations } from 'next-intl';
+ *
+ * export const { useForm } = createForm<OrderValues>({
+ *   config: orderConfig,
+ *   defaults: orderDefaults,
+ *   translateFunction: useTranslations,
+ *   type: "Order",
+ * });
+ * ```
+ *
+ * ```tsx
+ * // Корневой компонент — передаёт initial и колбэки
+ * const { getFieldProps, submit } = useForm(order?.id ?? "NewOrder", {
+ *   initial: order,
+ *   onSubmit: async (values) => { await api.saveOrder(values); },
+ * });
+ *
+ * return <Input {...getFieldProps("name")} />;
+ * ```
+ *
+ * ```tsx
+ * // Вложенный компонент — подключается к существующему store
+ * const { getFieldProps } = useForm(orderId);
+ *
+ * return <Input {...getFieldProps("name")} />;
+ * ```
+ */
+export type { PersistDriver, PersistOptions } from "./store/persist/types";
+export type { PersistManager } from "./store/persist/persistManager";
+export { localStorageDriver, sessionStorageDriver } from "./store/persist/drivers";
+export type { TranslateFn, FormConfig, MaybeComputed, MaybeTranslatable, DeepPartialValues, FieldTypeMeta, ConfigNode, FieldProxyNode, GroupProxyNode, ConfigProxy, FieldMapping, ApplyFieldMapping, ValidateExternalConfig, ConfigKeyError, ExternalConfig, ExternalConfigNode, RawStoreProxy, RawStoreProxyMarker, ExtractValues, ProxyStoreOptions, ProxyStore, Unsubscribe, PalistorRef, PalistorList, PalistorEntityProxy, TypedListNode, ListResolver, TemplateConfig, InferEntity, } from "./store/store/types";
+export type { Palistor as PalistorProxy } from "./store/store/types";
+export { Palistor } from "./store/store";
+export type { Resolve, NotifyFn, ResolveErrorContext } from "./store/resolvePipeline/";
+export { useNotifier } from "./react/useNotifier";
+export { useForm } from "./react/useForm";
+export { usePersist } from "./react/usePersist";
+export { useTranslator } from "./react/useTranslator";
+export { useStoreContext } from "./react/useStoreContext";
+export { defineList } from "./store/defineList";
+export { defineFieldMapping } from "./store/defineFieldMapping";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAMH,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAC3E,YAAY,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AACrE,OAAO,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAMnF,YAAY,EACV,WAAW,EACX,UAAU,EACV,aAAa,EACb,iBAAiB,EACjB,iBAAiB,EACjB,aAAa,EACb,UAAU,EACV,cAAc,EACd,cAAc,EACd,WAAW,EACX,YAAY,EACZ,iBAAiB,EACjB,sBAAsB,EACtB,cAAc,EACd,cAAc,EACd,kBAAkB,EAClB,aAAa,EACb,mBAAmB,EACnB,aAAa,EACb,iBAAiB,EACjB,UAAU,EACV,WAAW,EACX,WAAW,EACX,YAAY,EACZ,mBAAmB,EACnB,aAAa,EACb,YAAY,EACZ,cAAc,EACd,WAAW,GACZ,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EAAE,QAAQ,IAAI,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACrE,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAMzC,YAAY,EAAE,OAAO,EAAE,QAAQ,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AACvF,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAMlD,OAAO,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAC1C,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAChD,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAM1D,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAMhD,OAAO,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC"}

package/dist/index.js

@@ -0,0 +1,58 @@
+/**
+ * Palistor - State Manager для форм
+ *
+ * Архитектура: createForm + useForm(id)
+ *
+ * createForm() вызывается на уровне модуля — задаёт статическую конфигурацию.
+ * useForm(id) вызывается в React-компоненте — привязывает к экземпляру.
+ *
+ * @example
+ * ```ts
+ * // config/orderForm.ts — модульный уровень
+ * import { createForm } from 'palistor';
+ * import { useTranslations } from 'next-intl';
+ *
+ * export const { useForm } = createForm<OrderValues>({
+ *   config: orderConfig,
+ *   defaults: orderDefaults,
+ *   translateFunction: useTranslations,
+ *   type: "Order",
+ * });
+ * ```
+ *
+ * ```tsx
+ * // Корневой компонент — передаёт initial и колбэки
+ * const { getFieldProps, submit } = useForm(order?.id ?? "NewOrder", {
+ *   initial: order,
+ *   onSubmit: async (values) => { await api.saveOrder(values); },
+ * });
+ *
+ * return <Input {...getFieldProps("name")} />;
+ * ```
+ *
+ * ```tsx
+ * // Вложенный компонент — подключается к существующему store
+ * const { getFieldProps } = useForm(orderId);
+ *
+ * return <Input {...getFieldProps("name")} />;
+ * ```
+ */
+export { localStorageDriver, sessionStorageDriver } from "./store/persist/drivers";
+export { Palistor } from "./store/store";
+export { useNotifier } from "./react/useNotifier";
+// ============================================================================
+// React hooks
+// ============================================================================
+export { useForm } from "./react/useForm";
+export { usePersist } from "./react/usePersist";
+export { useTranslator } from "./react/useTranslator";
+export { useStoreContext } from "./react/useStoreContext";
+// ============================================================================
+// defineList — typed list helper
+// ============================================================================
+export { defineList } from "./store/defineList";
+// ============================================================================
+// defineFieldMapping — typed fieldMapping helper (сохраняет литералы)
+// ============================================================================
+export { defineFieldMapping } from "./store/defineFieldMapping";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAQH,OAAO,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAsCnF,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAOzC,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAElD,+EAA+E;AAC/E,cAAc;AACd,+EAA+E;AAE/E,OAAO,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAC1C,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAChD,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAE1D,+EAA+E;AAC/E,iCAAiC;AACjC,+EAA+E;AAE/E,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAEhD,+EAA+E;AAC/E,sEAAsE;AACtE,+EAA+E;AAE/E,OAAO,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC"}

package/dist/react/createTrackingProxy.d.ts

@@ -0,0 +1,55 @@
+/**
+ * createTrackingProxy — оборачивает store.proxy во второй слой Proxy,
+ * который записывает, какие config-ноды были прочитаны компонентом.
+ *
+ * Каждый `useForm` вызов создаёт свой tracking proxy → свой tracked set.
+ * Это позволяет `getSnapshot` проверять версии только прочитанных нод
+ * и не вызывать re-render, если изменились поля, которые компонент не читает.
+ *
+ * Tracking работает на уровне ноды: чтение ЛЮБОГО свойства
+ * (value, label, isVisible…) добавляет всю ноду в tracked set.
+ *
+ * Списки: `items`, `map`, `length`, `loading`, `dirty` на list-proxy добавляют
+ * объект `ListState` (бренд LIST_STATE, единый для root и per-entity) в tracked
+ * set. Мутация/resolve бампает версию этого ListState → getSnapshot детектирует
+ * изменение → re-render только списка. `map` → entity-прокси оборачиваются в
+ * tracking proxy для per-leaf отслеживания строк.
+ */
+import type { ProxyStore } from "../store/store";
+export interface TrackingRefs {
+    /** Набор config-нод, прочитанных компонентом. Только растёт (accumulate). */
+    accessed: Set<object>;
+    /** Версия каждой ноды на момент первого трекинга — для предотвращения
+     *  ложных re-render сразу после добавления ноды в tracked set. */
+    lastVersions: Map<object, number>;
+    /**
+     * Компонент обращался к дочерним ключам (form.email, form.passport),
+     * но не читал FIELD_STATE_PROPS. Позволяет различить:
+     * - «навигация без чтения» (Parent передаёт поддерево пропсом) → стабильный snapshot
+     * - «ничего не трогал» (renderHook без JSX) → fallback на глобальную версию
+     */
+    hasNavigated: boolean;
+}
+/**
+ * Проверить, является ли объект tracking proxy (имеет SOURCE_PROXY символ).
+ */
+export declare function isTrackingProxy(obj: unknown): boolean;
+/**
+ * Извлечь source proxy и store из tracking proxy.
+ * Возвращает null если объект не является tracking proxy.
+ */
+export declare function unwrapTrackingProxy<TConfig extends Record<string, any>>(obj: unknown): {
+    sourceProxy: any;
+    store: ProxyStore<TConfig>;
+} | null;
+/**
+ * Создать tracking proxy поверх source proxy.
+ * Кэшируется по source proxy объектам (один tracking proxy на вложенный узел).
+ *
+ * @param sourceProxy — базовый Proxy из store.proxy (или его дочерний узел)
+ * @param refs        — per-component tracking state (accessed, lastVersions)
+ * @param store       — ProxyStore, для чтения текущих версий нод
+ * @param cache       — WeakMap для кэширования tracking прокси объектов
+ */
+export declare function createTrackingProxy<TConfig extends Record<string, any>>(sourceProxy: any, refs: TrackingRefs, store: ProxyStore<TConfig>, cache: WeakMap<object, object>): any;
+//# sourceMappingURL=createTrackingProxy.d.ts.map

package/dist/react/createTrackingProxy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createTrackingProxy.d.ts","sourceRoot":"","sources":["../../react/createTrackingProxy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAEjD,MAAM,WAAW,YAAY;IAC3B,6EAA6E;IAC7E,QAAQ,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACtB;sEACkE;IAClE,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC;;;;;OAKG;IACH,YAAY,EAAE,OAAO,CAAC;CACvB;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAErD;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EACrE,GAAG,EAAE,OAAO,GACX;IAAE,WAAW,EAAE,GAAG,CAAC;IAAC,KAAK,EAAE,UAAU,CAAC,OAAO,CAAC,CAAA;CAAE,GAAG,IAAI,CAMzD;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EACrE,WAAW,EAAE,GAAG,EAChB,IAAI,EAAE,YAAY,EAClB,KAAK,EAAE,UAAU,CAAC,OAAO,CAAC,EAC1B,KAAK,EAAE,OAAO,CAAC,MAAM,EAAE,MAAM,CAAC,GAC7B,GAAG,CAuHL"}

package/dist/react/createTrackingProxy.js

@@ -0,0 +1,149 @@
+/**
+ * createTrackingProxy — оборачивает store.proxy во второй слой Proxy,
+ * который записывает, какие config-ноды были прочитаны компонентом.
+ *
+ * Каждый `useForm` вызов создаёт свой tracking proxy → свой tracked set.
+ * Это позволяет `getSnapshot` проверять версии только прочитанных нод
+ * и не вызывать re-render, если изменились поля, которые компонент не читает.
+ *
+ * Tracking работает на уровне ноды: чтение ЛЮБОГО свойства
+ * (value, label, isVisible…) добавляет всю ноду в tracked set.
+ *
+ * Списки: `items`, `map`, `length`, `loading`, `dirty` на list-proxy добавляют
+ * объект `ListState` (бренд LIST_STATE, единый для root и per-entity) в tracked
+ * set. Мутация/resolve бампает версию этого ListState → getSnapshot детектирует
+ * изменение → re-render только списка. `map` → entity-прокси оборачиваются в
+ * tracking proxy для per-leaf отслеживания строк.
+ */
+import { FIELD_STATE_PROPS, CONFIG_NODE, SOURCE_PROXY, STORE_REF, ENTITY_ID_LEAF, LIST_STATE } from "../store/constants";
+/**
+ * Проверить, является ли объект tracking proxy (имеет SOURCE_PROXY символ).
+ */
+export function isTrackingProxy(obj) {
+    return !!obj && typeof obj === "object" && !!obj[SOURCE_PROXY];
+}
+/**
+ * Извлечь source proxy и store из tracking proxy.
+ * Возвращает null если объект не является tracking proxy.
+ */
+export function unwrapTrackingProxy(obj) {
+    if (!isTrackingProxy(obj))
+        return null;
+    return {
+        sourceProxy: obj[SOURCE_PROXY],
+        store: obj[STORE_REF],
+    };
+}
+/**
+ * Создать tracking proxy поверх source proxy.
+ * Кэшируется по source proxy объектам (один tracking proxy на вложенный узел).
+ *
+ * @param sourceProxy — базовый Proxy из store.proxy (или его дочерний узел)
+ * @param refs        — per-component tracking state (accessed, lastVersions)
+ * @param store       — ProxyStore, для чтения текущих версий нод
+ * @param cache       — WeakMap для кэширования tracking прокси объектов
+ */
+export function createTrackingProxy(sourceProxy, refs, store, cache) {
+    if (cache.has(sourceProxy))
+        return cache.get(sourceProxy);
+    const tracked = new Proxy(sourceProxy, {
+        get(target, key) {
+            // CONFIG_NODE — пробрасываем, tracking proxy прозрачен для этого символа
+            if (key === CONFIG_NODE)
+                return target[CONFIG_NODE];
+            // SOURCE_PROXY — возвращаем исходный store proxy (target tracking proxy)
+            if (key === SOURCE_PROXY)
+                return target;
+            // STORE_REF — возвращаем ссылку на ProxyStore
+            if (key === STORE_REF)
+                return store;
+            // Прочие символы — пробрасываем как есть
+            if (typeof key === "symbol")
+                return target[key];
+            // Обратный маппинг на входе: external → internal. Проверки состояния
+            // (list-ключи, FIELD_STATE_PROPS) — по `ikey`; читаем и навигируем по
+            // оригинальному external-`key` (source-proxy переведёт его обратно).
+            const ikey = (store.externalToInternal[key] ?? key);
+            // ── List proxy (единый кубик: root + per-entity) ───────────────────────
+            // Ключ трекинга = объект ListState, а НЕ общий listConfigNode: иначе версии
+            // разных владельцев одного per-entity-списка схлопнутся (RFC §2.6), а root
+            // и entity потребовали бы две ветки. Должно идти ДО FIELD_STATE_PROPS:
+            // `loading`/`dirty` входят в FIELD_STATE_PROPS, но на списке их надо трекать
+            // по ListState, а не по CONFIG_NODE.
+            const listState = target[LIST_STATE];
+            if (listState) {
+                if (ikey === "length" || ikey === "loading" || ikey === "dirty") {
+                    if (!refs.accessed.has(listState)) {
+                        refs.accessed.add(listState);
+                        refs.lastVersions.set(listState, store.getNodeVersion(listState));
+                    }
+                    return target[key];
+                }
+                if (ikey === "items") {
+                    if (!refs.accessed.has(listState)) {
+                        refs.accessed.add(listState);
+                        refs.lastVersions.set(listState, store.getNodeVersion(listState));
+                    }
+                    const rawItems = target[key];
+                    return rawItems.map((item) => createTrackingProxy(item, refs, store, cache));
+                }
+                if (ikey === "map") {
+                    if (!refs.accessed.has(listState)) {
+                        refs.accessed.add(listState);
+                        refs.lastVersions.set(listState, store.getNodeVersion(listState));
+                    }
+                    const origMap = target[key];
+                    return (fn) => origMap((item, index, id) => fn(createTrackingProxy(item, refs, store, cache), index, id));
+                }
+                // add/remove/setItems/getById — пробрасываем без трекинга.
+                return target[key];
+            }
+            // Чтение состояния поля → трекинг ноды
+            // submitting — реактивный флаг группы, тоже требует трекинга
+            if (FIELD_STATE_PROPS.has(ikey) || ikey === "submitting") {
+                const configNode = target[CONFIG_NODE];
+                if (configNode && !refs.accessed.has(configNode)) {
+                    refs.accessed.add(configNode);
+                    // Сохраняем текущую версию, чтобы getSnapshot не считал это изменением
+                    refs.lastVersions.set(configNode, store.getNodeVersion(configNode));
+                }
+                return target[key];
+            }
+            // Дочерний объект → рекурсивный tracking proxy
+            const result = target[key];
+            // Entity id access: the entity proxy returns the id string directly (not via a
+            // leaf proxy), so we would normally miss tracking it. Detect by checking if the
+            // entity proxy exposes ENTITY_ID_LEAF and register that leaf for subscriptions.
+            // This ensures rekey() → idLeaf version bump → getSnapshot detects change → re-render.
+            if (key === "id") {
+                const idLeaf = target[ENTITY_ID_LEAF];
+                if (idLeaf && !refs.accessed.has(idLeaf)) {
+                    refs.accessed.add(idLeaf);
+                    refs.lastVersions.set(idLeaf, store.getNodeVersion(idLeaf));
+                }
+            }
+            if (result && typeof result === "object") {
+                refs.hasNavigated = true;
+                return createTrackingProxy(result, refs, store, cache);
+            }
+            return result;
+        },
+        set(target, key, value) {
+            // Запись пробрасывается в исходный proxy (SET trap в buildProxy)
+            return Reflect.set(target, key, value);
+        },
+        /**
+         * Пробрасываем ownKeys из source proxy, чтобы spread ({...trackingProxy})
+         * возвращал те же ключи, что и store proxy (без validate, formatter, …).
+         */
+        ownKeys(target) {
+            return Reflect.ownKeys(target);
+        },
+        getOwnPropertyDescriptor(target, key) {
+            return Reflect.getOwnPropertyDescriptor(target, key);
+        },
+    });
+    cache.set(sourceProxy, tracked);
+    return tracked;
+}
+//# sourceMappingURL=createTrackingProxy.js.map

package/dist/react/createTrackingProxy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"createTrackingProxy.js","sourceRoot":"","sources":["../../react/createTrackingProxy.ts"],"names":[],"mappings":"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"}

package/dist/react/useForm.d.ts

@@ -0,0 +1,108 @@
+/**
+ * useForm — React хук для подключения к ProxyStore
+ *
+ * Возвращает реактивный прокси. Доступ к полям через точку — это и есть
+ * подписка: компонент перерендерится только при изменении прочитанных полей.
+ *
+ * @example
+ * ```tsx
+ * const store = new Palistor({ config });
+ *
+ * function App() {
+ *   const form = useForm(store);
+ *
+ *   return (
+ *     <div>
+ *       <PassportSection passport={form.passport} />
+ *       <input
+ *         value={form.email.value}
+ *         onChange={(e) => { form.email.value = e.target.value }}
+ *       />
+ *     </div>
+ *   );
+ * }
+ *
+ * // Дочерний компонент с useForm для независимой подписки:
+ * function PassportSection({ passport }) {
+ *   const p = useForm(passport); // ← принимает поддерево!
+ *   if (!p.isVisible) return null;
+ *   return <NumberField field={p.number} />;
+ * }
+ * ```
+ *
+ * Как работает:
+ *   1. useSyncExternalStore подписывается на глобальные изменения store.
+ *   2. getSnapshot сравнивает версии только прочитанных узлов →
+ *      re-render происходит только если изменилось то, что читалось.
+ *   3. store.proxy оборачивается в tracking proxy. Каждый GET записывает
+ *      config-ноду в tracked set. getSnapshot проверяет только эти ноды.
+ *   4. Запись `form.email.value = "X"` → store.proxy.email.value = "X" →
+ *      SET trap → formatter → validate → recompute → notify → re-render
+ *      (только компонентов, которые читали изменившиеся ноды).
+ *
+ * Перегрузки:
+ *   - useForm(store)        — основной вариант, передаём ProxyStore
+ *   - useForm(proxySubtree) — принимает tracking proxy поддерево (из пропса),
+ *     создаёт **независимый** tracking для этого компонента
+ *   - useForm(entityProxy, templateSelector) — привязка entity к template.
+ *     entityProxy из list.items/list.getById. templateSelector = (s) => s.editForm.
+ *     Вызывает entityRegistry.bind на mount, unbind на unmount.
+ */
+import type { ProxyStore, ConfigProxy, GroupProxyNode, RawStoreProxyMarker } from "../store/store";
+import type { PalistorRef, PalistorList, Palistor, PalistorEntityProxy, FieldMapping } from "../store/store/types";
+/**
+ * Подключает React-компонент к ProxyStore.
+ *
+ * Компонент перерендерится только при изменении полей, которые он читал
+ * во время предыдущего рендера. Tracking proxy автоматически записывает
+ * обращения к FIELD_STATE_PROPS (value, label, isVisible, error…) и
+ * getSnapshot проверяет версии только этих нод.
+ *
+ * На первом рендере tracked set пуст → используется глобальная версия
+ * (fallback). После первого рендера tracking работает точечно.
+ *
+ * @param input — ProxyStore, созданный через new Palistor(), ИЛИ
+ *                tracking proxy поддерево (из пропса другого useForm)
+ * @returns tracking proxy — типизированный по конфигу (или поддереву)
+ */
+/**
+ * Тип-«ошибка», который TypeScript показывает в диагностике, если в
+ * `useForm` передали сырой `store.proxy` или его поддерево. Имя интерфейса
+ * специально длинное и описательное — оно появится в тексте ошибки и
+ * подскажет, что делать.
+ *
+ * @see {@link RawStoreProxyMarker}
+ */
+export interface _PALISTOR_ERROR__do_not_pass_store_proxy_subtree_to_useForm__call_useForm_store_first {
+    readonly _palistorError: "useForm received a raw store.proxy subtree. Use: const form = useForm(store); then drill into form.subtree (a tracking proxy). See useForm-raw-proxy-pitfall.md.";
+}
+/**
+ * Превращает T в тип-ошибку, если T помечен {@link RawStoreProxyMarker}.
+ * Применяется к параметру subtree-перегрузки `useForm`, чтобы сделать
+ * `useForm(store.proxy.subtree)` ошибкой компиляции.
+ */
+type ForbidRawStoreProxy<T> = T extends RawStoreProxyMarker ? _PALISTOR_ERROR__do_not_pass_store_proxy_subtree_to_useForm__call_useForm_store_first : T;
+export declare function useForm<T extends Record<string, any>>(input: PalistorRef<T>): PalistorEntityProxy<T>;
+export declare function useForm<T extends Record<string, any>>(input: PalistorList<T>): PalistorList<T>;
+export declare function useForm<T extends Record<string, any> & {
+    id?: any;
+}>(input: Palistor<T>): PalistorEntityProxy<T>;
+export declare function useForm<T extends GroupProxyNode>(input: ForbidRawStoreProxy<T>): T;
+export declare function useForm<TConfig extends Record<string, any>, TMapping extends FieldMapping = {}>(input: ProxyStore<TConfig, TMapping>): ConfigProxy<TConfig, TMapping>;
+/**
+ * Перегрузка: привязка entity к template для отображения/редактирования.
+ *
+ * @param entity           — EntityProjectionProxy из list.items или list.getById
+ * @param templateSelector — функция выбора template: (store) => store.editUserForm
+ * @returns tracking proxy entity через template (поля template + значения entity)
+ *
+ * Lifecycle:
+ *   - mount: entityRegistry.bind(entityId, templateNode)
+ *   - unmount: entityRegistry.unbind(entityId, templateNode)
+ *
+ * Resolved cache (3A.4): при повторном открытии той же entity+template
+ * `isResolved` возвращает true → resolve будет пропущен (Phase 3B).
+ */
+export declare function useForm(entity: object, templateSelector: (store: any) => any): any;
+export {};
+//# sourceMappingURL=useForm.d.ts.map

package/dist/react/useForm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useForm.d.ts","sourceRoot":"","sources":["../../react/useForm.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AACnG,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,QAAQ,EAAE,mBAAmB,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AA2CnH;;;;;;;;;;;;;;GAcG;AACH;;;;;;;GAOG;AACH,MAAM,WAAW,qFAAqF;IACpG,QAAQ,CAAC,cAAc,EACrB,kKAAkK,CAAC;CACtK;AAED;;;;GAIG;AACH,KAAK,mBAAmB,CAAC,CAAC,IAAI,CAAC,SAAS,mBAAmB,GACvD,qFAAqF,GACrF,CAAC,CAAC;AAEN,wBAAgB,OAAO,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,KAAK,EAAE,WAAW,CAAC,CAAC,CAAC,GAAG,mBAAmB,CAAC,CAAC,CAAC,CAAC;AACtG,wBAAgB,OAAO,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,KAAK,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,YAAY,CAAC,CAAC,CAAC,CAAC;AAChG,wBAAgB,OAAO,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG;IAAE,EAAE,CAAC,EAAE,GAAG,CAAA;CAAE,EAClE,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC,GACjB,mBAAmB,CAAC,CAAC,CAAC,CAAC;AAC1B,wBAAgB,OAAO,CAAC,CAAC,SAAS,cAAc,EAC9C,KAAK,EAAE,mBAAmB,CAAC,CAAC,CAAC,GAC5B,CAAC,CAAC;AAEL,wBAAgB,OAAO,CACrB,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EACnC,QAAQ,SAAS,YAAY,GAAG,EAAE,EAElC,KAAK,EAAE,UAAU,CAAC,OAAO,EAAE,QAAQ,CAAC,GACnC,WAAW,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;AAElC;;;;;;;;;;;;;GAaG;AACH,wBAAgB,OAAO,CACrB,MAAM,EAAE,MAAM,EACd,gBAAgB,EAAE,CAAC,KAAK,EAAE,GAAG,KAAK,GAAG,GACpC,GAAG,CAAC"}

package/dist/react/useForm.js

@@ -0,0 +1,180 @@
+/**
+ * useForm — React хук для подключения к ProxyStore
+ *
+ * Возвращает реактивный прокси. Доступ к полям через точку — это и есть
+ * подписка: компонент перерендерится только при изменении прочитанных полей.
+ *
+ * @example
+ * ```tsx
+ * const store = new Palistor({ config });
+ *
+ * function App() {
+ *   const form = useForm(store);
+ *
+ *   return (
+ *     <div>
+ *       <PassportSection passport={form.passport} />
+ *       <input
+ *         value={form.email.value}
+ *         onChange={(e) => { form.email.value = e.target.value }}
+ *       />
+ *     </div>
+ *   );
+ * }
+ *
+ * // Дочерний компонент с useForm для независимой подписки:
+ * function PassportSection({ passport }) {
+ *   const p = useForm(passport); // ← принимает поддерево!
+ *   if (!p.isVisible) return null;
+ *   return <NumberField field={p.number} />;
+ * }
+ * ```
+ *
+ * Как работает:
+ *   1. useSyncExternalStore подписывается на глобальные изменения store.
+ *   2. getSnapshot сравнивает версии только прочитанных узлов →
+ *      re-render происходит только если изменилось то, что читалось.
+ *   3. store.proxy оборачивается в tracking proxy. Каждый GET записывает
+ *      config-ноду в tracked set. getSnapshot проверяет только эти ноды.
+ *   4. Запись `form.email.value = "X"` → store.proxy.email.value = "X" →
+ *      SET trap → formatter → validate → recompute → notify → re-render
+ *      (только компонентов, которые читали изменившиеся ноды).
+ *
+ * Перегрузки:
+ *   - useForm(store)        — основной вариант, передаём ProxyStore
+ *   - useForm(proxySubtree) — принимает tracking proxy поддерево (из пропса),
+ *     создаёт **независимый** tracking для этого компонента
+ *   - useForm(entityProxy, templateSelector) — привязка entity к template.
+ *     entityProxy из list.items/list.getById. templateSelector = (s) => s.editForm.
+ *     Вызывает entityRegistry.bind на mount, unbind на unmount.
+ */
+import { useSyncExternalStore, useCallback, useRef, useMemo, useEffect } from "react";
+import { createTrackingProxy, unwrapTrackingProxy, } from "./createTrackingProxy";
+import { ENTITY_ID, STORE_REF, CONFIG_NODE } from "../store/constants";
+import { buildEntityProjectionProxy } from "../store/buildProxy/buildEntityProjectionProxy";
+/**
+ * Извлечь store и sourceProxy из аргумента useForm.
+ * Поддерживает ProxyStore напрямую и tracking proxy поддеревья.
+ */
+function resolveInput(input) {
+    // Если это tracking proxy (поддерево переданное пропсом)
+    const unwrapped = unwrapTrackingProxy(input);
+    if (unwrapped)
+        return unwrapped;
+    // Сырой GroupProxyNode из store.proxy.someGroup — НЕ подходит.
+    // Пользователь должен передавать либо ProxyStore (new Palistor()),
+    // либо tracking proxy (из пропса родительского useForm).
+    if (input != null && typeof input === "object" && input[CONFIG_NODE]) {
+        throw new Error("useForm: получен сырой proxy-узел стора (store.proxy.someGroup). " +
+            "Это не допустимо.\n\n" +
+            "Правильный способ:\n" +
+            "  1. Получите tracking proxy через useForm(store):\n" +
+            "       const form = useForm(store);\n" +
+            "  2. Передайте поддерево как проп дочернему компоненту:\n" +
+            "       <Child section={form.someGroup} />\n" +
+            "  3. В дочернем компоненте вызовите useForm(props.section).\n\n" +
+            "Нельзя передавать store.proxy или его дочерние узлы напрямую в useForm.");
+    }
+    // Иначе это ProxyStore — берём store.proxy как sourceProxy
+    return { store: input, sourceProxy: input.proxy };
+}
+export function useForm(input, templateSelector) {
+    // ─── Detect entity mode ──────────────────────────────────────────────────
+    const isEntityMode = typeof templateSelector === "function";
+    const entityMetaRef = useRef(null);
+    if (isEntityMode && !entityMetaRef.current) {
+        const entityId = input[ENTITY_ID];
+        const entityStore = input[STORE_REF];
+        if (!entityId || !entityStore) {
+            throw new Error("useForm: first argument must be an entity proxy (from list.items or list.getById) " +
+                "when templateSelector is provided.");
+        }
+        const templateProxy = templateSelector(entityStore.proxy);
+        const templateNode = templateProxy[CONFIG_NODE];
+        if (!templateNode) {
+            throw new Error("useForm: templateSelector must return a group proxy node.");
+        }
+        const entityNode = entityStore.entityRegistry.get(entityId);
+        if (!entityNode) {
+            throw new Error(`useForm: entity "${entityId}" not found in registry.`);
+        }
+        const entityProxy = buildEntityProjectionProxy(entityNode, templateNode, entityStore, new WeakMap());
+        entityMetaRef.current = { entityId, entityStore, templateNode, entityProxy };
+    }
+    // ─── Standard mode: resolve store + sourceProxy ──────────────────────────
+    const { store: stdStore, sourceProxy: stdSourceProxy } = useMemo(() => isEntityMode
+        ? { store: null, sourceProxy: null }
+        : resolveInput(input), 
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [input, isEntityMode]);
+    // ─── Unified store + sourceProxy ────────────────────────────────────────
+    const store = isEntityMode
+        ? entityMetaRef.current.entityStore
+        : stdStore;
+    const sourceProxy = isEntityMode
+        ? entityMetaRef.current.entityProxy
+        : stdSourceProxy;
+    // ─── Tracking state (per-component, стабильные ref-ы) ────────────────────
+    const refsRef = useRef(null);
+    if (!refsRef.current) {
+        refsRef.current = {
+            accessed: new Set(),
+            lastVersions: new Map(),
+            hasNavigated: false,
+        };
+    }
+    const refs = refsRef.current;
+    const cacheRef = useRef(null);
+    if (!cacheRef.current)
+        cacheRef.current = new WeakMap();
+    const snapshotRef = useRef(0);
+    // ─── Tracking proxy ───────────────────────────────────────────────────────
+    const trackingProxy = useMemo(() => createTrackingProxy(sourceProxy, refs, store, cacheRef.current), [store, sourceProxy, refs]);
+    // ─── Bind/unbind lifecycle (entity mode only) ────────────────────────────
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    useEffect(() => {
+        if (!isEntityMode)
+            return;
+        const meta = entityMetaRef.current;
+        if (!meta)
+            return;
+        // Привязываем entity к template — регистрируем, что этот шаблон сейчас отображает данную entity
+        meta.entityStore.entityRegistry.bind(meta.entityId, meta.templateNode);
+        // Запускаем resolve на уровне template, если он ещё не выполнялся для этой entity+template пары
+        if (!meta.entityStore.entityRegistry.isResolved(meta.entityId, meta.templateNode)) {
+            meta.entityStore.resolveManager.triggerEntityTemplateResolve(meta.entityId, meta.templateNode, meta.entityProxy);
+        }
+        // Per-field resolves are now triggered lazily from the entity leaf proxy GET trap
+        // (on first access to .value or .loading) — no eager loop needed here.
+        return () => {
+            // При размонтировании отвязываем entity от template — шаблон больше не отображает эту entity
+            meta.entityStore.entityRegistry.unbind(meta.entityId, meta.templateNode);
+        };
+    }, []); // bind once on mount, unbind on unmount
+    // ─── useSyncExternalStore ────────────────────────────────────────────────
+    const subscribe = useCallback((onStoreChange) => store.subscribeGlobal(onStoreChange), [store]);
+    const getSnapshot = useCallback(() => {
+        const { accessed, lastVersions } = refs;
+        if (accessed.size === 0) {
+            return refs.hasNavigated ? snapshotRef.current : store.getVersion();
+        }
+        let changed = false;
+        for (const node of accessed) {
+            const currentVersion = store.getNodeVersion(node);
+            if (currentVersion !== lastVersions.get(node)) {
+                changed = true;
+                break;
+            }
+        }
+        if (changed) {
+            snapshotRef.current = store.getVersion();
+            for (const node of accessed) {
+                lastVersions.set(node, store.getNodeVersion(node));
+            }
+        }
+        return snapshotRef.current;
+    }, [store, refs]);
+    useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+    return trackingProxy;
+}
+//# sourceMappingURL=useForm.js.map