pdyform 2.2.0 → 2.3.0

package/README.md

@@ -1,7 +1,8 @@
 # pdyform
 
 [![npm version](https://badge.fury.io/js/pdyform.svg)](https://badge.fury.io/js/pdyform)
-[![Tests](https://img.shields.io/badge/tests-27%20passed%20(100%25)-brightgreen.svg)]()
+[![Tests](https://img.shields.io/badge/tests-pass-brightgreen.svg)]()
+[![Coverage](https://img.shields.io/badge/coverage-87%25-brightgreen.svg)]()
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
 [English](#english) | [中文说明](#中文说明)
@@ -16,10 +17,19 @@ A high-performance, schema-driven dynamic form system with **React** and **Vue**
 
 - **Schema-Driven**: Define your forms using a simple and intuitive JSON/JS schema.
 - **Framework Agnostic Core**: Core logic is entirely framework-free, making it extremely lightweight and portable.
+- **Vanilla Pub-Sub Store**: Built-in 40-line `VanillaStore` ensures high-performance updates without relying on heavy state-management libraries like Zustand or Redux.
 - **Conditional Logic**: Supports dynamic `hidden` and `disabled` states based on form values (supports both boolean and functions).
-- **React & Vue Support**: Out-of-the-box UI components built on top of modern UI libraries (Radix UI / Shadcn).
-- **Type Safety**: Built with TypeScript for excellent developer experience and catch errors early.
-- **High Performance**: Optimized rendering using store-based state management (Zustand) to minimize re-renders.
+- **React & Vue Support**: Out-of-the-box UI components. (Moving towards a pure Headless approach to decouple from Tailwind/Shadcn).
+- **Type Safety**: Built with strict TypeScript for excellent developer experience and early error catching.
+- **High Test Coverage**: Core logic is heavily tested (>85% coverage) ensuring robustness against edge cases like network-level async validation and race conditions.
+- **Zero Side Effects**: Configured for aggressive tree-shaking with `"sideEffects": false`.
+
+### 🏗 Architecture & Roadmap
+
+pdyform is built with a strict separation of concerns:
+1. **Core Data Engine (`pdyform-core`)**: Maintains the schema structure, parses definitions, runs asynchronous/synchronous validations, and manages state using an internal Vanilla Pub-Sub model.
+2. **Framework Adapters (`pdyform-react` / `pdyform-vue`)**: Wraps the core engine with localized hooks (e.g. `useSyncExternalStore` for React) and provides base components.
+3. **Headless Roadmap**: Currently, the React/Vue components bundle specific UI elements (Radix, Tailwind). We are moving towards a true Headless architecture where the packages expose only accessible logic components (`<Field>`) and hooks (`useForm`), leaving the styling implementation entirely up to the user (similar to unstyled Shadcn UI).
 
 ### 📦 Packages
 
@@ -116,10 +126,19 @@ const handleSubmit = (values: any) => console.log(values);
 
 - **Schema 驱动**: 使用简单直观的 JSON/JS 对象定义你的表单。
 - **框架无关核心**: 核心逻辑完全独立于 UI 框架，极其轻量且易于移植。
+- **原生的防抖状态引擎**: 内置不到 40 行的 `VanillaStore` 来完成高性能的局部渲染与订阅，告别由于集成 Zustand 等库带来的体积膨胀。
 - **联动逻辑**: 支持基于表单实时数值动态控制字段的 `hidden`（隐藏）和 `disabled`（禁用）状态（支持布尔值或函数）。
-- **支持 React & Vue**: 提供基于现代 UI 库（Radix UI / Shadcn）的开箱即用组件。
+- **支持 React & Vue**: 提供开箱即用的基础组件 (未来的路线图将向纯 Headless UI 组件过渡，解耦 Tailwind 样式依赖)。
 - **类型安全**: 全量 TypeScript 编写，提供极佳的开发体验。
-- **高性能**: 基于 Zustand 状态管理库优化渲染逻辑，最小化不必要的组件重绘。
+- **高测试覆盖**: 核心逻辑配备了超过 85% 的单元测试与异步并发校验的健壮性控制。
+- **零副作用**: 各包均通过 `"sideEffects": false` 配置，对构建工具进行深度 Tree-Shaking 优化。
+
+### 🏗 架构与路线图设计
+
+整个引擎保持了极其严格的职责划分：
+1. **核心数据引擎 (`pdyform-core`)**: 管理表单 Schema 结构的解析，处理异步和同步的各项校验机制。利用手写原生 Pub-Sub 处理多级数据变化拦截。
+2. **框架适配 Hook (`pdyform-react` / `pdyform-vue`)**: 将状态和渲染树绑定（如在 React 中使用 `useSyncExternalStore`）。
+3. **Headless 演进**: 尽全力提供类似无头表单 (Headless Form) 的钩子调用，不再强绑定各类 UI 组件库和样式设定。
 
 ### 📦 包结构
 

package/package.json

@@ -1,5 +1,8 @@
 {
   "name": "pdyform",
+  "publishConfig": {
+    "access": "public"
+  },
   "description": "A high-performance, schema-driven dynamic form system with React and Vue support.",
   "keywords": [
     "dynamic-form",
@@ -15,7 +18,28 @@
     "packages/react/dist/**",
     "packages/vue/dist/**"
   ],
+  "main": "./packages/core/dist/index.cjs",
+  "module": "./packages/core/dist/index.js",
+  "types": "./packages/core/dist/index.d.ts",
+  "typesVersions": {
+    "*": {
+      "core": [
+        "./packages/core/dist/index.d.ts"
+      ],
+      "react": [
+        "./packages/react/dist/index.d.ts"
+      ],
+      "vue": [
+        "./packages/vue/dist/index.d.ts"
+      ]
+    }
+  },
   "exports": {
+    ".": {
+      "types": "./packages/core/dist/index.d.ts",
+      "import": "./packages/core/dist/index.js",
+      "require": "./packages/core/dist/index.cjs"
+    },
     "./core": {
       "types": "./packages/core/dist/index.d.ts",
       "import": "./packages/core/dist/index.js",
@@ -39,17 +63,24 @@
     "url": "https://github.com/LaoChen1994/pdyform"
   },
   "devDependencies": {
+    "@changesets/cli": "^2.30.0",
+    "@commitlint/cli": "^20.5.0",
+    "@commitlint/config-conventional": "^20.5.0",
     "@eslint/js": "^9.39.3",
+    "@size-limit/preset-small-lib": "^12.0.1",
     "@typescript-eslint/eslint-plugin": "^8.56.1",
     "@typescript-eslint/parser": "^8.56.1",
+    "@vitest/coverage-v8": "^1.6.1",
     "autoprefixer": "^10.4.27",
     "eslint": "^9.39.3",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-react": "^7.37.5",
     "eslint-plugin-vue": "^10.8.0",
     "globals": "^15.15.0",
+    "husky": "^9.1.7",
     "postcss": "^8.5.8",
     "prettier": "^3.8.1",
+    "size-limit": "^12.0.1",
     "tailwindcss": "^3.4.0",
     "turbo": "latest",
     "typescript": "^5.0.0",
@@ -57,16 +88,21 @@
     "vitest": "^1.0.0",
     "vue": "^3.5.0"
   },
-  "version": "2.2.0",
+  "version": "2.3.0",
   "scripts": {
     "build:all": "turbo run build",
     "dev:all": "turbo run dev",
     "dev:example": "turbo run dev --filter=@example/*",
     "test:all": "turbo run test",
+    "test:coverage:all": "turbo run test:coverage",
     "lint:all": "turbo run lint",
     "dev:example:react": "pnpm --filter @example/react-demo dev",
     "dev:example:vue": "pnpm --filter @example/vue-demo dev",
     "build:example:react": "pnpm --filter @example/react-demo build",
-    "build:example:vue": "pnpm --filter @example/vue-demo build"
+    "build:example:vue": "pnpm --filter @example/vue-demo build",
+    "changeset": "changeset",
+    "version-packages": "changeset version",
+    "release": "pnpm build:all && changeset publish",
+    "size": "size-limit"
   }
 }

package/packages/core/dist/{chunk-KA6QUMVR.js → chunk-T3LQTNYY.js}

@@ -14,6 +14,7 @@ var defaultErrorMessages = {
   custom: "Invalid value"
 };
 function formatMessage(template, field, rule) {
+  if (!template) return "";
   return template.replace("{label}", field.label).replace("{value}", String(rule.value || ""));
 }
 function get(obj, path, defaultValue) {
@@ -133,6 +134,8 @@ async function validateForm(fields, values, resolver, customMessages) {
   }
   const validationPromises = fields.map(async (field) => {
     if (errors[field.name]) return;
+    const isHidden = typeof field.hidden === "function" ? field.hidden(values) : field.hidden;
+    if (isHidden) return;
     const error = await validateField(get(values, field.name), field, customMessages);
     if (error) errors[field.name] = error;
   });

package/packages/core/dist/chunk-V4VK2GZU.js

@@ -0,0 +1,108 @@
+import {
+  get,
+  getDefaultValues,
+  normalizeFieldValue,
+  set,
+  validateFieldByName,
+  validateForm
+} from "./chunk-T3LQTNYY.js";
+
+// src/formState.ts
+function createStore(initialState) {
+  let state = initialState;
+  const listeners = /* @__PURE__ */ new Set();
+  const getState = () => state;
+  const setState = (partial) => {
+    const nextState = typeof partial === "function" ? partial(state) : partial;
+    if (!Object.is(nextState, state)) {
+      const prevState = state;
+      state = { ...state, ...nextState };
+      listeners.forEach((listener) => listener(state, prevState));
+    }
+  };
+  const subscribe = (listener) => {
+    listeners.add(listener);
+    return () => listeners.delete(listener);
+  };
+  return { getState, setState, subscribe };
+}
+function createFormEngine(fields, resolver, errorMessages) {
+  const store = createStore({
+    values: getDefaultValues(fields),
+    errors: {},
+    validatingFields: [],
+    isSubmitting: false
+  });
+  const { getState, setState } = store;
+  const setFieldValue = async (name, rawValue) => {
+    const field = fields.find((f) => f.name === name);
+    const normalizedValue = field ? normalizeFieldValue(field, rawValue) : rawValue;
+    setState((s) => ({
+      values: set(s.values, name, normalizedValue)
+    }));
+    const hasExistingError = !!getState().errors[name];
+    const shouldValidateImmediately = field && ["select", "checkbox", "radio", "switch", "date"].includes(field.type);
+    if (shouldValidateImmediately || hasExistingError) {
+      setState((s) => ({
+        validatingFields: [...s.validatingFields, name]
+      }));
+      try {
+        const currentValues = getState().values;
+        const error = await validateFieldByName(fields, name, normalizedValue, resolver, currentValues, errorMessages);
+        setState((s) => ({
+          errors: { ...s.errors, [name]: error || "" },
+          validatingFields: s.validatingFields.filter((f) => f !== name)
+        }));
+      } catch {
+        setState((s) => ({
+          validatingFields: s.validatingFields.filter((f) => f !== name)
+        }));
+      }
+    }
+  };
+  const setFieldBlur = async (name) => {
+    setState((s) => ({
+      validatingFields: [...s.validatingFields, name]
+    }));
+    try {
+      const currentValues = getState().values;
+      const value = get(currentValues, name);
+      const error = await validateFieldByName(fields, name, value, resolver, currentValues, errorMessages);
+      setState((s) => ({
+        errors: { ...s.errors, [name]: error || "" },
+        validatingFields: s.validatingFields.filter((f) => f !== name)
+      }));
+    } catch {
+      setState((s) => ({
+        validatingFields: s.validatingFields.filter((f) => f !== name)
+      }));
+    }
+  };
+  const setSubmitting = (isSubmitting) => setState({ isSubmitting });
+  const runSubmitValidation = async () => {
+    setState({ isSubmitting: true });
+    const currentValues = getState().values;
+    const errors = await validateForm(fields, currentValues, resolver, errorMessages);
+    const hasError = Object.keys(errors).length > 0;
+    setState({
+      errors,
+      isSubmitting: false
+    });
+    return {
+      state: getState(),
+      hasError
+    };
+  };
+  return {
+    store,
+    setFieldValue,
+    setFieldBlur,
+    setSubmitting,
+    runSubmitValidation
+  };
+}
+
+export {
+  createStore,
+  createFormEngine
+};

package/packages/core/dist/formState.cjs

@@ -20,10 +20,10 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/formState.ts
 var formState_exports = {};
 __export(formState_exports, {
-  createFormStore: () => createFormStore
+  createFormEngine: () => createFormEngine,
+  createStore: () => createStore
 });
 module.exports = __toCommonJS(formState_exports);
-var import_vanilla = require("zustand/vanilla");
 
 // src/utils.ts
 function parseNumberish(value) {
@@ -41,6 +41,7 @@ var defaultErrorMessages = {
   custom: "Invalid value"
 };
 function formatMessage(template, field, rule) {
+  if (!template) return "";
   return template.replace("{label}", field.label).replace("{value}", String(rule.value || ""));
 }
 function get(obj, path, defaultValue) {
@@ -160,6 +161,8 @@ async function validateForm(fields, values, resolver, customMessages) {
   }
   const validationPromises = fields.map(async (field) => {
     if (errors[field.name]) return;
+    const isHidden = typeof field.hidden === "function" ? field.hidden(values) : field.hidden;
+    if (isHidden) return;
     const error = await validateField(get(values, field.name), field, customMessages);
     if (error) errors[field.name] = error;
   });
@@ -174,68 +177,101 @@ function getDefaultValues(fields) {
 }
 
 // src/formState.ts
-function createFormStore(fields, resolver, errorMessages) {
-  return (0, import_vanilla.createStore)()((set2, getStore) => ({
+function createStore(initialState) {
+  let state = initialState;
+  const listeners = /* @__PURE__ */ new Set();
+  const getState = () => state;
+  const setState = (partial) => {
+    const nextState = typeof partial === "function" ? partial(state) : partial;
+    if (!Object.is(nextState, state)) {
+      const prevState = state;
+      state = { ...state, ...nextState };
+      listeners.forEach((listener) => listener(state, prevState));
+    }
+  };
+  const subscribe = (listener) => {
+    listeners.add(listener);
+    return () => listeners.delete(listener);
+  };
+  return { getState, setState, subscribe };
+}
+function createFormEngine(fields, resolver, errorMessages) {
+  const store = createStore({
     values: getDefaultValues(fields),
     errors: {},
     validatingFields: [],
-    isSubmitting: false,
-    setFieldValue: async (name, rawValue) => {
-      const field = fields.find((f) => f.name === name);
-      const normalizedValue = field ? normalizeFieldValue(field, rawValue) : rawValue;
-      set2((state) => ({
-        values: set(state.values, name, normalizedValue),
-        validatingFields: [...state.validatingFields, name]
+    isSubmitting: false
+  });
+  const { getState, setState } = store;
+  const setFieldValue = async (name, rawValue) => {
+    const field = fields.find((f) => f.name === name);
+    const normalizedValue = field ? normalizeFieldValue(field, rawValue) : rawValue;
+    setState((s) => ({
+      values: set(s.values, name, normalizedValue)
+    }));
+    const hasExistingError = !!getState().errors[name];
+    const shouldValidateImmediately = field && ["select", "checkbox", "radio", "switch", "date"].includes(field.type);
+    if (shouldValidateImmediately || hasExistingError) {
+      setState((s) => ({
+        validatingFields: [...s.validatingFields, name]
       }));
       try {
-        const currentValues = getStore().values;
+        const currentValues = getState().values;
         const error = await validateFieldByName(fields, name, normalizedValue, resolver, currentValues, errorMessages);
-        set2((state) => ({
-          errors: { ...state.errors, [name]: error || "" },
-          validatingFields: state.validatingFields.filter((f) => f !== name)
+        setState((s) => ({
+          errors: { ...s.errors, [name]: error || "" },
+          validatingFields: s.validatingFields.filter((f) => f !== name)
         }));
-      } catch (err) {
-        set2((state) => ({
-          validatingFields: state.validatingFields.filter((f) => f !== name)
+      } catch {
+        setState((s) => ({
+          validatingFields: s.validatingFields.filter((f) => f !== name)
         }));
       }
-    },
-    setFieldBlur: async (name) => {
-      set2((state) => ({
-        validatingFields: [...state.validatingFields, name]
+    }
+  };
+  const setFieldBlur = async (name) => {
+    setState((s) => ({
+      validatingFields: [...s.validatingFields, name]
+    }));
+    try {
+      const currentValues = getState().values;
+      const value = get(currentValues, name);
+      const error = await validateFieldByName(fields, name, value, resolver, currentValues, errorMessages);
+      setState((s) => ({
+        errors: { ...s.errors, [name]: error || "" },
+        validatingFields: s.validatingFields.filter((f) => f !== name)
+      }));
+    } catch {
+      setState((s) => ({
+        validatingFields: s.validatingFields.filter((f) => f !== name)
       }));
-      try {
-        const currentValues = getStore().values;
-        const value = get(currentValues, name);
-        const error = await validateFieldByName(fields, name, value, resolver, currentValues, errorMessages);
-        set2((state) => ({
-          errors: { ...state.errors, [name]: error || "" },
-          validatingFields: state.validatingFields.filter((f) => f !== name)
-        }));
-      } catch (err) {
-        set2((state) => ({
-          validatingFields: state.validatingFields.filter((f) => f !== name)
-        }));
-      }
-    },
-    setSubmitting: (isSubmitting) => set2({ isSubmitting }),
-    runSubmitValidation: async () => {
-      set2({ isSubmitting: true });
-      const state = getStore();
-      const errors = await validateForm(fields, state.values, resolver, errorMessages);
-      const hasError = Object.keys(errors).length > 0;
-      set2({
-        errors,
-        isSubmitting: false
-      });
-      return {
-        state: getStore(),
-        hasError
-      };
     }
-  }));
+  };
+  const setSubmitting = (isSubmitting) => setState({ isSubmitting });
+  const runSubmitValidation = async () => {
+    setState({ isSubmitting: true });
+    const currentValues = getState().values;
+    const errors = await validateForm(fields, currentValues, resolver, errorMessages);
+    const hasError = Object.keys(errors).length > 0;
+    setState({
+      errors,
+      isSubmitting: false
+    });
+    return {
+      state: getState(),
+      hasError
+    };
+  };
+  return {
+    store,
+    setFieldValue,
+    setFieldBlur,
+    setSubmitting,
+    runSubmitValidation
+  };
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  createFormStore
+  createFormEngine,
+  createStore
 });

package/packages/core/dist/formState.d.cts

@@ -1,13 +1,20 @@
-import * as zustand_vanilla from 'zustand/vanilla';
 import { FormField, FormResolver, ErrorMessageTemplates } from './types.cjs';
 
+type StoreListener<T> = (state: T, prevState: T) => void;
+interface VanillaStore<T> {
+    getState: () => T;
+    setState: (partial: Partial<T> | ((state: T) => Partial<T>)) => void;
+    subscribe: (listener: StoreListener<T>) => () => void;
+}
+declare function createStore<T>(initialState: T): VanillaStore<T>;
 interface FormRuntimeState {
-    values: Record<string, any>;
+    values: Record<string, unknown>;
     errors: Record<string, string>;
     validatingFields: string[];
     isSubmitting: boolean;
 }
-interface FormStore extends FormRuntimeState {
+interface FormEngine {
+    store: VanillaStore<FormRuntimeState>;
     setFieldValue: (name: string, rawValue: unknown) => Promise<void>;
     setFieldBlur: (name: string) => Promise<void>;
     setSubmitting: (isSubmitting: boolean) => void;
@@ -16,6 +23,6 @@ interface FormStore extends FormRuntimeState {
         hasError: boolean;
     }>;
 }
-declare function createFormStore(fields: FormField[], resolver?: FormResolver, errorMessages?: ErrorMessageTemplates): zustand_vanilla.StoreApi<FormStore>;
+declare function createFormEngine(fields: FormField[], resolver?: FormResolver, errorMessages?: ErrorMessageTemplates): FormEngine;
 
-export { type FormRuntimeState, type FormStore, createFormStore };
+export { type FormEngine, type FormRuntimeState, type StoreListener, type VanillaStore, createFormEngine, createStore };

package/packages/core/dist/formState.d.ts

@@ -1,13 +1,20 @@
-import * as zustand_vanilla from 'zustand/vanilla';
 import { FormField, FormResolver, ErrorMessageTemplates } from './types.js';
 
+type StoreListener<T> = (state: T, prevState: T) => void;
+interface VanillaStore<T> {
+    getState: () => T;
+    setState: (partial: Partial<T> | ((state: T) => Partial<T>)) => void;
+    subscribe: (listener: StoreListener<T>) => () => void;
+}
+declare function createStore<T>(initialState: T): VanillaStore<T>;
 interface FormRuntimeState {
-    values: Record<string, any>;
+    values: Record<string, unknown>;
     errors: Record<string, string>;
     validatingFields: string[];
     isSubmitting: boolean;
 }
-interface FormStore extends FormRuntimeState {
+interface FormEngine {
+    store: VanillaStore<FormRuntimeState>;
     setFieldValue: (name: string, rawValue: unknown) => Promise<void>;
     setFieldBlur: (name: string) => Promise<void>;
     setSubmitting: (isSubmitting: boolean) => void;
@@ -16,6 +23,6 @@ interface FormStore extends FormRuntimeState {
         hasError: boolean;
     }>;
 }
-declare function createFormStore(fields: FormField[], resolver?: FormResolver, errorMessages?: ErrorMessageTemplates): zustand_vanilla.StoreApi<FormStore>;
+declare function createFormEngine(fields: FormField[], resolver?: FormResolver, errorMessages?: ErrorMessageTemplates): FormEngine;
 
-export { type FormRuntimeState, type FormStore, createFormStore };
+export { type FormEngine, type FormRuntimeState, type StoreListener, type VanillaStore, createFormEngine, createStore };

package/packages/core/dist/formState.js

@@ -1,7 +1,9 @@
 import {
-  createFormStore
-} from "./chunk-REHKL5VH.js";
-import "./chunk-KA6QUMVR.js";
+  createFormEngine,
+  createStore
+} from "./chunk-V4VK2GZU.js";
+import "./chunk-T3LQTNYY.js";
 export {
-  createFormStore
+  createFormEngine,
+  createStore
 };