palistor 0.0.29 → 0.0.30

package/README.md

@@ -60,9 +60,33 @@ Palistor's state also caches data so it isn't re-fetched from the data layer unn
 
 ---
 
-## The MVVM idea (Model-View-ViewModel)
+## Table of contents
+
+- [Idea](#idea)
+- [Demo](#demo)
+- [Features](#features)
+- [Installation](#installation)
+- [Quick start](#quick-start)
+- [Concepts](#concepts)
+- [API reference](#api-reference)
+- [Async resolvers](#async-resolvers)
+- [Lists & entities](#lists--entities)
+- [Flows (step wizards)](#flows-step-wizards)
+- [Field mapping](#field-mapping)
+- [Persist](#persist)
+- [i18n](#i18n)
+- [Notifications](#notifications)
+- [Store context](#store-context)
+- [TypeScript](#typescript)
+- [License](#license)
+
+---
+
+## Idea
+
+### The MVVM idea (Model-View-ViewModel)
 
-### Classic MVVM, but by data flow it's more accurate to read it as a pipeline: Model → ViewModel → View
+#### Classic MVVM, but by data flow it's more accurate to read it as a pipeline: Model → ViewModel → View
 
 Most React screens tangle three unrelated concerns inside components:
  - how the screen **behaves** (validation, conditional fields, cross-field rules),
@@ -91,7 +115,7 @@ As a bonus, we get:
 
 All of this lets us grow the complexity of every layer and add new functionality without sacrificing stability or predictability. And, most importantly, move toward generating frontends for enterprise systems.
 
-## Use cases for Palistor
+### Use cases for Palistor
 
 Admin panels, SaaS platforms, consoles, personal dashboards — anything built mostly from forms, step wizards, dynamic widgets and tables:
  - Onboarding / KYC / verification / questionnaires — branching multi-step wizards, conditional fields, step-by-step validation (`defineFlow`).
@@ -102,7 +126,7 @@ Admin panels, SaaS platforms, consoles, personal dashboards — anything built m
  - Schema-driven / backend-driven forms — since the config is data, it can be generated or served from the backend. Plus the multi-region angle: context for regions/laws.
  - Dashboards with form-like filters — a filter panel as a reactive data source.
 
-## What Palistor is not for
+### What Palistor is not for
 
 Landing pages with no complex logic, where the main goal is to ship a simple page fast.
  - Content sites: blogs, docs, marketing, SSG — SEO-first, static, almost no behavior.
@@ -112,23 +136,19 @@ Landing pages with no complex logic, where the main goal is to ship a simple pag
 
 ---
 
-## Table of contents
+## Demo
 
-- [Features](#features)
-- [Installation](#installation)
-- [Quick start](#quick-start)
-- [Concepts](#concepts)
-- [API reference](#api-reference)
-- [Async resolvers](#async-resolvers)
-- [Lists & entities](#lists--entities)
-- [Flows (step wizards)](#flows-step-wizards)
-- [Field mapping](#field-mapping)
-- [Persist](#persist)
-- [i18n](#i18n)
-- [Notifications](#notifications)
-- [Store context](#store-context)
-- [TypeScript](#typescript)
-- [License](#license)
+A live playground with every example from this README: **[projectint.github.io/palistor](https://projectint.github.io/palistor/)**
+
+Each tab is a separate framework feature, and every one has a direct deep link:
+
+- [Quick start](https://projectint.github.io/palistor/#form) — conditional fields, submit pipeline, persist
+- [Flows](https://projectint.github.io/palistor/#flow) — a step wizard with branching
+- [Lists & entities](https://projectint.github.io/palistor/#lists) — normalized registry, list proxy, store context
+- [Async resolvers](https://projectint.github.io/palistor/#async) — data loading, retry, notifications
+- [Field mapping](https://projectint.github.io/palistor/#mapping) — rename props to your UI kit
+
+The playground sources live in [`app-demo/`](https://github.com/ProjectINT/palistor/tree/main/app-demo). Each section below links to the specific example code and its live tab.
 
 ---
 
@@ -199,6 +219,8 @@ import {
 
 ## Quick start
 
+> 🔗 **Source:** [config/payment.ts](https://github.com/ProjectINT/palistor/blob/main/app-demo/src/config/payment.ts), [modules/payment-form/](https://github.com/ProjectINT/palistor/tree/main/app-demo/src/modules/payment-form) · **Live result:** [Demo → Payment Form](https://projectint.github.io/palistor/#form)
+
 ### 1. Describe the form
 
 The config is declarative: field values, validation, visibility and lifecycle callbacks live in one tree. Create the store at module level.
@@ -544,6 +566,8 @@ company: {
 
 ## Async resolvers
 
+> 🔗 **Source:** [config/catalog/](https://github.com/ProjectINT/palistor/tree/main/app-demo/src/config/catalog), [modules/async-demo/](https://github.com/ProjectINT/palistor/tree/main/app-demo/src/modules/async-demo) · **Live result:** [Demo → Async resolvers](https://projectint.github.io/palistor/#async)
+
 A resolver is configured on a group node. It loads data asynchronously with auto-tracked dependencies, retry and React Suspense support.
 
 ```typescript
@@ -603,6 +627,8 @@ When a dependency changes, the resolve state resets, `optimisticResolver` applie
 
 ## Lists & entities
 
+> 🔗 **Source:** [modules/lists-demo/](https://github.com/ProjectINT/palistor/tree/main/app-demo/src/modules/lists-demo) · **Live result:** [Demo → Lists & entities](https://projectint.github.io/palistor/#lists)
+
 Lists are declared with `defineList` (preferred — fully typed) or as a raw array of length 1–2 where `[0]` is the item template.
 
 ```typescript
@@ -704,6 +730,8 @@ store.delete("u1");
 
 ## Flows (step wizards)
 
+> 🔗 **Source:** [config/flow.ts](https://github.com/ProjectINT/palistor/blob/main/app-demo/src/config/flow.ts), [modules/flow-demo/](https://github.com/ProjectINT/palistor/tree/main/app-demo/src/modules/flow-demo) · **Live result:** [Demo → Flows](https://projectint.github.io/palistor/#flow)
+
 `defineFlow` / `defineStep` build a step wizard on top of regular group nodes: navigation state, step statuses, branching and per-step validation.
 
 ```typescript
@@ -798,6 +826,8 @@ Flow navigation (current step, history) is included in [persist](#persist) snaps
 
 ## Field mapping
 
+> 🔗 **Source:** [config/fieldMapping.ts](https://github.com/ProjectINT/palistor/blob/main/app-demo/src/config/fieldMapping.ts), [modules/field-mapping/](https://github.com/ProjectINT/palistor/tree/main/app-demo/src/modules/field-mapping) · **Live result:** [Demo → Field mapping](https://projectint.github.io/palistor/#mapping)
+
 `fieldMapping` renames field-state props **at the proxy boundary** — GET, SET, tracking and spread — so `{...form.email}` can be spread directly into a component from MUI, Ant Design or plain HTML without adapters. The internal engine is unchanged.
 
 ```typescript
@@ -843,6 +873,8 @@ Mappable keys: `value`, `label`, `placeholder`, `description`, `isRequired`, `is
 
 ## Persist
 
+> 🔗 **Source:** [modules/payment-form/PersistControls.tsx](https://github.com/ProjectINT/palistor/blob/main/app-demo/src/modules/payment-form/PersistControls.tsx) · **Live result:** [Demo → Payment Form](https://projectint.github.io/palistor/#form)
+
 Autosave form state to any storage.
 
 ### React hook (recommended)
@@ -937,6 +969,8 @@ The `validate` callback also receives `t` as its third argument. Without a regis
 
 ## Notifications
 
+> 🔗 **Source:** [config/catalog/catalog.ts](https://github.com/ProjectINT/palistor/blob/main/app-demo/src/config/catalog/catalog.ts) · **Live result:** [Demo → Async resolvers](https://projectint.github.io/palistor/#async)
+
 Register a toast/alert function once; resolvers receive it in `onError` via `ctx.notify`:
 
 ```tsx
@@ -957,6 +991,8 @@ function RootLayout({ children }: { children: React.ReactNode }) {
 
 ## Store context
 
+> 🔗 **Source:** [modules/lists-demo/StoreContextSection.tsx](https://github.com/ProjectINT/palistor/blob/main/app-demo/src/modules/lists-demo/StoreContextSection.tsx) · **Live result:** [Demo → Lists & entities](https://projectint.github.io/palistor/#lists)
+
 Non-reactive data (account id, tenant, tokens…) available to every callback via `store.context`. It is not part of the form — it does not appear in `getValues()`, submit payloads or persisted state.
 
 ```tsx

package/README.ru.md

@@ -60,9 +60,33 @@ const store = new Palistor({
 
 ---
 
-## Идея MVVM (Model-View-ViewModel)
+## Содержание
+
+- [Идея](#идея)
+- [Демо](#демо)
+- [Возможности](#возможности)
+- [Установка](#установка)
+- [Быстрый старт](#быстрый-старт)
+- [Концепции](#концепции)
+- [API Reference](#api-reference)
+- [Async-резолверы](#async-резолверы)
+- [Списки и сущности](#списки-и-сущности)
+- [Flows (пошаговые мастера)](#flows-пошаговые-мастера)
+- [Field mapping](#field-mapping)
+- [Persist](#persist)
+- [i18n](#i18n)
+- [Уведомления](#уведомления)
+- [Контекст store](#контекст-store)
+- [TypeScript](#typescript)
+- [Лицензия](#лицензия)
+
+---
+
+## Идея
+
+### Идея MVVM (Model-View-ViewModel)
 
-### Классический MVVM, но по потоку данных правильнее читать его как конвейер: Model → ViewModel → View
+#### Классический MVVM, но по потоку данных правильнее читать его как конвейер: Model → ViewModel → View
 
 Большинство React-экранов сплетают внутри компонентов три несвязанные заботы: 
  - как экран **себя ведёт** (валидация, условные поля, кросс-полевые правила),
@@ -91,7 +115,7 @@ const store = new Palistor({
 
 Все это позволит нам нарастить сложность всех слоев и добавить новый функционал без ущерба для стабильности и предсказуемости. А главное перейти к генерации фронтенда для корпоративных систем.
 
-## Задачи для Palistor
+### Задачи для Palistor
 Админки, саас платформы, консоли, личные кабинеты, состоящие в основном из форм и шаговых мастеров, динамических виджетов и таблиц:
  - Онбординг / KYC / верификация / анкеты — ветвящиеся многошаговые мастера, условные поля, пошаговая валидация (defineFlow).
  - Чек-ауты и платёжные формы — условные способы оплаты, кросс-полевые правила, async-подгрузка.
@@ -101,7 +125,7 @@ const store = new Palistor({
  - Schema-driven / бэкенд-управляемые формы — раз конфиг это данные, его можно генерить/отдавать с сервера. Плюс твой козырь про мультирегиональность (context под регионы/законы).
  - Дашборды с формо-подобными фильтрами — панель фильтров как реактивный источник для данных.
 
-## Для чего не подходит Palistor
+### Для чего не подходит Palistor
 Сайты лендинги где нет сложной логики и главная задача быстрее отдать простую страницу.
  - Контент-сайты: блоги, документация, маркетинг, SSG — SEO-first, статика, поведения почти нет.
  - Графика / canvas / realtime-рендер — игры, редакторы (rich-text, диаграммы, карты), видеоплееры, тяжёлые визуализации. Тут сложность в рендере, а модель не расщепляется на слои.
@@ -109,23 +133,19 @@ const store = new Palistor({
  - Встраиваемые виджеты, где критичен вес бандла — ты сам признал «библиотека не маленькая»; для embeddable-скрипта на чужой странице это минус.
 ---
 
-## Содержание
+## Демо
 
-- [Возможности](#возможности)
-- [Установка](#установка)
-- [Быстрый старт](#быстрый-старт)
-- [Концепции](#концепции)
-- [API Reference](#api-reference)
-- [Async-резолверы](#async-резолверы)
-- [Списки и сущности](#списки-и-сущности)
-- [Flows (пошаговые мастера)](#flows-пошаговые-мастера)
-- [Field mapping](#field-mapping)
-- [Persist](#persist)
-- [i18n](#i18n)
-- [Уведомления](#уведомления)
-- [Контекст store](#контекст-store)
-- [TypeScript](#typescript)
-- [Лицензия](#лицензия)
+Живой стенд со всеми примерами из этого README: **[projectint.github.io/palistor](https://projectint.github.io/palistor/)**
+
+Каждый таб — отдельная возможность фреймворка, на каждый ведёт прямая deep-ссылка:
+
+- [Быстрый старт](https://projectint.github.io/palistor/#form) — условные поля, submit-pipeline, persist
+- [Flows](https://projectint.github.io/palistor/#flow) — пошаговый мастер с ветвлением
+- [Списки и сущности](https://projectint.github.io/palistor/#lists) — нормализованный реестр, list-proxy, контекст store
+- [Async-резолверы](https://projectint.github.io/palistor/#async) — загрузка данных, retry, уведомления
+- [Field mapping](https://projectint.github.io/palistor/#mapping) — переименование пропсов под UI-кит
+
+Исходники стенда — в [`app-demo/`](https://github.com/ProjectINT/palistor/tree/main/app-demo). Под каждым разделом ниже — ссылки на конкретный код примера и соответствующий таб.
 
 ---
 
@@ -196,6 +216,8 @@ import {
 
 ## Быстрый старт
 
+> 🔗 **Код:** [config/payment.ts](https://github.com/ProjectINT/palistor/blob/main/app-demo/src/config/payment.ts), [modules/payment-form/](https://github.com/ProjectINT/palistor/tree/main/app-demo/src/modules/payment-form) · **Живой результат:** [Демо → Форма оплаты](https://projectint.github.io/palistor/#form)
+
 ### 1. Опишите форму
 
 Конфиг декларативен: значения полей, валидация, видимость и lifecycle-колбэки живут в одном дереве. Store создаётся на уровне модуля.
@@ -541,6 +563,8 @@ company: {
 
 ## Async-резолверы
 
+> 🔗 **Код:** [config/catalog/](https://github.com/ProjectINT/palistor/tree/main/app-demo/src/config/catalog), [modules/async-demo/](https://github.com/ProjectINT/palistor/tree/main/app-demo/src/modules/async-demo) · **Живой результат:** [Демо → Async-резолверы](https://projectint.github.io/palistor/#async)
+
 Резолвер конфигурируется на групповом узле. Загружает данные асинхронно — с авто-трекингом зависимостей, retry и поддержкой React Suspense.
 
 ```typescript
@@ -600,6 +624,8 @@ if (form.userInfo.loading) return <Spinner />;
 
 ## Списки и сущности
 
+> 🔗 **Код:** [modules/lists-demo/](https://github.com/ProjectINT/palistor/tree/main/app-demo/src/modules/lists-demo) · **Живой результат:** [Демо → Списки и сущности](https://projectint.github.io/palistor/#lists)
+
 Списки объявляются через `defineList` (предпочтительно — полная типизация) или сырым массивом длиной 1–2, где `[0]` — шаблон элемента.
 
 ```typescript
@@ -701,6 +727,8 @@ store.delete("u1");
 
 ## Flows (пошаговые мастера)
 
+> 🔗 **Код:** [config/flow.ts](https://github.com/ProjectINT/palistor/blob/main/app-demo/src/config/flow.ts), [modules/flow-demo/](https://github.com/ProjectINT/palistor/tree/main/app-demo/src/modules/flow-demo) · **Живой результат:** [Демо → Flows](https://projectint.github.io/palistor/#flow)
+
 `defineFlow` / `defineStep` строят пошаговый мастер поверх обычных групповых узлов: навигационное состояние, статусы шагов, ветвление и валидация по шагам.
 
 ```typescript
@@ -795,6 +823,8 @@ defineStep("details", {
 
 ## Field mapping
 
+> 🔗 **Код:** [config/fieldMapping.ts](https://github.com/ProjectINT/palistor/blob/main/app-demo/src/config/fieldMapping.ts), [modules/field-mapping/](https://github.com/ProjectINT/palistor/tree/main/app-demo/src/modules/field-mapping) · **Живой результат:** [Демо → Field mapping](https://projectint.github.io/palistor/#mapping)
+
 `fieldMapping` переименовывает пропсы состояния поля **на границе proxy** — GET, SET, tracking и spread, — так что `{...form.email}` можно спредить напрямую в компонент MUI, Ant Design или нативный HTML без адаптеров. Внутреннее ядро не меняется.
 
 ```typescript
@@ -840,6 +870,8 @@ function EmailField() {
 
 ## Persist
 
+> 🔗 **Код:** [modules/payment-form/PersistControls.tsx](https://github.com/ProjectINT/palistor/blob/main/app-demo/src/modules/payment-form/PersistControls.tsx) · **Живой результат:** [Демо → Форма оплаты](https://projectint.github.io/palistor/#form)
+
 Автосохранение состояния формы в любое хранилище.
 
 ### React-хук (рекомендуется)
@@ -934,6 +966,8 @@ cardNumber: {
 
 ## Уведомления
 
+> 🔗 **Код:** [config/catalog/catalog.ts](https://github.com/ProjectINT/palistor/blob/main/app-demo/src/config/catalog/catalog.ts) · **Живой результат:** [Демо → Async-резолверы](https://projectint.github.io/palistor/#async)
+
 Зарегистрируйте функцию toast/alert один раз; резолверы получат её в `onError` через `ctx.notify`:
 
 ```tsx
@@ -954,6 +988,8 @@ function RootLayout({ children }: { children: React.ReactNode }) {
 
 ## Контекст store
 
+> 🔗 **Код:** [modules/lists-demo/StoreContextSection.tsx](https://github.com/ProjectINT/palistor/blob/main/app-demo/src/modules/lists-demo/StoreContextSection.tsx) · **Живой результат:** [Демо → Списки и сущности](https://projectint.github.io/palistor/#lists)
+
 Нереактивные данные (id аккаунта, tenant, токены…), доступные во всех колбэках через `store.context`. Не является частью формы — не попадает в `getValues()`, submit-payload и persist.
 
 ```tsx

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "palistor",
-  "version": "0.0.29",
+  "version": "0.0.30",
   "description": "Declarative MVVM-style state framework for React — forms, lists & wizards, batteries included",
   "main": "dist/index.js",
   "module": "dist/index.js",