@skyroc/form

类型安全的 React 表单 primitive,路径级精确订阅 + StandardSchema 校验

概览

包名@skyroc/form
目录packages/primitives/filed-form
版本0.0.2
运行时依赖@radix-ui/react-slot@skyroc/utils(类型走 ./type 子入口)
peerreact、react-dom(^16.8 – ^19)
子入口../react
测试✅ 5 个
READMEREADME.md + README.zh.md

@skyroc/form 是一个类型安全的 React 表单库。设计核心是把表单数据形状(Values)作为泛型贯穿所有 API,让字段路径不是 string 而是由 Values 结构推导出的合法字面量联合,再配合 ChangeTag bitmask 实现精确订阅、避免无关字段触发重渲染。

适用场景

  • 字段路径 / 值类型必须类型安全
  • 大型表单需要精确订阅,避免重渲染整张表
  • 想用 Zod / Yup / Valibot 等 StandardSchema 兼容库做校验
  • 需要动态数组、ComputedField、Undo/Redo

四条主线

主线说明详见
泛型 Values 贯穿全链路路径与值类型从数据形状推导,写错编译期就报类型安全
ChangeTag bitmask 订阅值 / 校验状态 / 数组结构变化标记为不同位,按位匹配精确订阅
StandardSchema 集成通过 ~standard.validate 接入,兼容主流校验库校验
form-core 与 React 分层状态引擎框架无关,React 层只做桥接form-core

先跑起来看 快速上手

子入口

子路径内容
.form-core 类型 + 全部 React API
./react仅 React 层(组件 + hooks)

主入口 src/index.ts 除了 export * from './react',还额外导出 form-core 的类型:SubscribeMaskOptionsActionMetaValidateMessagesRule,以及从 type-utils 透传的 AllPathsKeysFieldElement

目录结构

src/
├── index.ts
├── form-core/                  # 框架无关核心
│   ├── createStore.ts          # FormStore 状态引擎
│   ├── event.ts                # ChangeTag bitmask 订阅
│   ├── event-value.ts
│   ├── flag-set.ts
│   ├── middleware.ts           # Action / Middleware 管道
│   ├── types.ts
│   ├── validate.ts
│   ├── validation.ts
│   └── resolver/
│       ├── resolver.ts         # StandardSchemaV1 / 自定义 schema
│       ├── standard.ts
│       └── utils.ts
└── react/
    ├── index.ts
    ├── components/
    │   ├── Form.tsx
    │   ├── Field.tsx
    │   ├── List.tsx
    │   └── ComputedField.tsx
    └── hooks/
        ├── FieldContext.ts     # FormInstance 实现 / 类型核心
        ├── useForm.ts
        ├── useWatch.ts
        ├── useSelector.ts
        ├── useFieldState.ts
        ├── useFieldError.ts
        ├── useFieldArray.ts
        ├── useFieldEffect.ts
        └── useUndoRedo.ts

目录名是 filed-form(拼写遗留),发布名是 @skyroc/form。以 package.json#name 为准,见 命名规范

测试

5 个测试文件:

文件主题覆盖
createStore状态引擎
validation校验逻辑
hooksReact hooks 行为
react-components组件交互
event-middleware-resolver事件 + 中间件 + schema 解析

详细文档

  • 中文:packages/primitives/filed-form/README.zh.md
  • 英文:packages/primitives/filed-form/README.md

两份 README 都包含完整 API 参考、进阶示例与设计动机。

Last updated on