@classytic/formkit 1.3.1 → 1.5.0

package/CHANGELOG.md

@@ -5,6 +5,79 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.5.0] - 2026-07-02
+
+Stability / hardening release. Two intentional **behavioral changes** are called
+out below — read them before upgrading.
+
+### Behavioral changes
+
+- **`field.number()` no longer injects `min: 0`.** The builder previously added
+  an implicit non-negative constraint; forms relying on it must now pass
+  `{ min: 0 }` explicitly. Signed quantities (deltas, temperatures) are valid by
+  default.
+- **Missing components render a visible placeholder in production** (previously
+  a silent null). The wrong-widget `text` fallback for unregistered types was
+  removed entirely. Use the new `onMissingComponent` provider callback for
+  telemetry. Exception: `hidden` fields with no registered component render
+  nothing by design.
+
+### Added
+
+- `validateSchema(schema)` — structural schema linting (missing name/type,
+  duplicate names, `itemFields` on non-containers, unknown DSL operators),
+  exported from both entries and auto-run in dev by `FormGenerator`.
+- `focusFirstError(root?)` — focuses the first visibly-invalid field in layout
+  order; retries across two animation frames so it works from
+  `handleSubmit(onValid, () => focusFirstError())` on the very first submit.
+- `loadOptions` now receives `{ signal: AbortSignal }` as a second argument;
+  superseded/unmounted loads are aborted. New opt-in `cacheOptions` memoizes
+  results per watched-value signature (bounded).
+- `onMissingComponent` callback on `FormSystemProvider`.
+- `colSpan` field prop (surfaced as `data-col-span`; `fullWidth` now also emits
+  an inline `grid-column: 1 / -1` so full-width layout works without scanning
+  the package with Tailwind).
+- `resetOnSchemaChange` option on `useFormKit` for DB-loaded schema swaps.
+- Dev warning when `loadOptions` is used without `watchNames` (whole-form
+  refetch storms).
+- `buildFieldDefaults` exported; array-item seeds are now type-aware (`false`
+  for checkbox/switch, `[]` for multiselect/tags, `undefined` for number).
+- `mergeDefaultValues(base, override)` exported (both entries) — the exact
+  Date-safe deep merge `useFormKit` applies between schema defaults and caller
+  `defaultValues`, for wrappers that re-seed via `form.reset(...)`.
+
+### Fixed
+
+- **Rules-of-hooks crash**: `useFieldComponent` and the field-props memo are
+  hoisted above the group/array fallback returns, so a registry that changes
+  after mount (code-split adapters) can no longer change the hook count.
+  `eslint-plugin-react-hooks` is now enforced in CI-lint.
+- **Date / class-instance defaults survive merging**: `useFormKit`'s deep-merge
+  now replaces non-plain objects (Date, File, class instances) wholesale
+  instead of spread-merging them into `{}`.
+- Function conditions with `watchNames` receive properly **nested** watched
+  values (`(v) => v.address.city` works; previously flat `"address.city"` keys
+  made them throw and hide the field).
+- `extractDefaultValues` recurses into nested groups (deep defaults were
+  dropped beyond one level); shares one walker with the async variant.
+- Fallback UI (array items, error boundary, missing-component placeholder) uses
+  structural inline styles + `currentColor` instead of Tailwind classes that
+  don't exist in consumer builds; `formkit-*` classes remain as theming hooks.
+- `process.env` reads are guarded (`isDev()` helper), so bundler-less ESM
+  environments no longer throw `ReferenceError`.
+
+## [1.4.0] - 2026-05-26
+
+### Added
+
+- New schema helpers exported from `./schema`: `extractDefaultValuesAsync`, field-type predicates (`isChoiceField`, `isTextField`, `isNumericField`, `isDateField`, `isContainerField`, `isArrayField`, `isDynamicField`, `isConditionalField`), schema composition (`mergeSchemas`, `extendSection`, `pickFields`, `omitFields`, `flattenSchema`), and `applyServerErrors`.
+- New exported types: `SectionRendererProps`, `GridRendererProps`, `FieldWrapperProps`, `ValidationRuleObject`, `PatternRuleObject`.
+- Conditional package exports add `module-sync` condition for better React Server Components / sync-import interop.
+
+### Changed
+
+- `main` / `module` fields removed from `package.json` in favor of pure conditional `exports`.
+
 ## [1.3.0] - 2026-02-27
 
 ### Added

package/README.md

@@ -8,8 +8,12 @@ Headless, type-safe form generation engine for React 19. Schema-driven with full
 
 ## Features
 
-- **Minimal boilerplate** - `useFormKit` hook: 5 lines to set up a complete form
-- **Headless** - Bring your own UI components (Shadcn, MUI, Chakra, etc.)
+- **Headless** - Bring your own UI components (Shadcn, MUI, Chakra, etc.) via a
+  one-time component/layout adapter. Already using shadcn? Skip the adapter
+  entirely with the prebuilt one in **[`@classytic/fluid/formkit`](https://www.npmjs.com/package/@classytic/fluid)** —
+  its `SchemaForm` is genuinely a schema + `onSubmit` away.
+- **Minimal boilerplate** - once an adapter is registered, `useFormKit` wires a
+  full form (defaults + RHF + generator props) in a few lines
 - **Schema-driven** - Define forms with JSON/TypeScript schemas, defaults extracted automatically
 - **Type-safe** - Full TypeScript support with generics
 - **React Hook Form** - Built on top of the best form library, referentially stable return values
@@ -20,7 +24,7 @@ Headless, type-safe form generation engine for React 19. Schema-driven with full
 - **Responsive layouts** - Multi-column grid layouts
 - **Accessibility** - Auto-generated `fieldId`, `error`, and `fieldState` props
 - **Validation helpers** - `buildValidationRules` generates RHF rules from schema props
-- **Lightweight** - ~7KB gzipped, tree-shakeable
+- **Lightweight** - ~17KB gzipped (peer deps excluded, everything included), tree-shakeable
 
 ## Requirements
 
@@ -54,28 +58,41 @@ import { Label } from "@/components/ui/label";
 
 export function FormInput({
   control,
-  field,
+  name,
+  rules,       // pre-computed RHF rules from schema (required, minLength, pattern, validate…)
   label,
   placeholder,
   required,
+  fieldId,     // use as id on <input> and htmlFor on <Label>
+  errorId,     // use as id on error <p> and aria-errormessage on <input>
+  shouldShowError, // true only after touch/submit — mirrors :user-invalid timing
   error,
-  fieldId,
 }: FieldComponentProps) {
   return (
     <Controller
-      name={field.name}
+      name={name}
       control={control}
-      render={({ field: rhfField }) => (
+      rules={rules}
+      render={({ field }) => (
         <div className="space-y-2">
           {label && (
             <Label htmlFor={fieldId}>
               {label}
-              {required && <span className="text-red-500 ml-1">*</span>}
+              {required && <span aria-hidden="true" className="text-red-500 ml-1">*</span>}
             </Label>
           )}
-          <Input {...rhfField} id={fieldId} placeholder={placeholder} />
-          {error && (
-            <p className="text-sm text-red-500">{error.message}</p>
+          <Input
+            {...field}
+            id={fieldId}
+            placeholder={placeholder}
+            aria-required={required || undefined}
+            aria-invalid={shouldShowError || undefined}
+            aria-errormessage={shouldShowError ? errorId : undefined}
+          />
+          {shouldShowError && (
+            <p id={errorId} role="alert" className="text-sm text-red-500">
+              {error?.message}
+            </p>
           )}
         </div>
       )}
@@ -114,9 +131,16 @@ const layouts: LayoutRegistry = {
       {children}
     </div>
   ),
-  grid: ({ children, cols = 1 }) => (
-    <div className={`grid grid-cols-${cols} gap-4`}>{children}</div>
-  ),
+  grid: ({ children, cols = 1 }) => {
+    // Map to STATIC class names. A template like `grid-cols-${cols}` is never
+    // generated by Tailwind's JIT (it only sees whole class strings in source).
+    const COLS: Record<number, string> = {
+      1: "grid-cols-1",
+      2: "grid-cols-1 md:grid-cols-2",
+      3: "grid-cols-1 md:grid-cols-2 lg:grid-cols-3",
+    };
+    return <div className={`grid gap-4 ${COLS[cols] ?? "grid-cols-1"}`}>{children}</div>;
+  },
 };
 
 export function FormProvider({ children }: { children: React.ReactNode }) {
@@ -185,6 +209,26 @@ export default function SignupPage() {
 }
 ```
 
+## Type safety
+
+Field **names** are enforced against your form type at *authoring* time by the
+builders. Use `field.for<T>()`, `defineField<T>()`, or `section<T>()` and a typo
+is a compile error:
+
+```ts
+const f = field.for<SignupData>();
+f.text("emial", "Email"); // ✗ compile error — "emial" is not a key of SignupData
+f.text("email", "Email"); // ✓
+```
+
+The `<FormGenerator schema>` / `useFormKit({ schema })` props themselves accept
+`FormSchema<any>` **by design**: a schema's condition functions (`(values) => …`)
+make `FormSchema<T>` contravariant in `T`, so pinning the prop to the form's `T`
+would force a cast at every call site. Author with the typed builders for name
+safety; the generator stays permissive so any built schema drops in without
+ceremony. `itemFields` (group/array children) use relative names and are
+resolved at render time, so they are typed loosely on purpose.
+
 ## API Reference
 
 ### useFormKit
@@ -203,6 +247,7 @@ const form = useFormKit({
   disabled: false,                          // optional
   variant: "compact",                       // optional
   className: "my-form",                     // optional
+  resetOnSchemaChange: true,                // optional — re-seed on schema swap
   mode: "onBlur",                           // any useForm option
 });
 
@@ -221,7 +266,9 @@ return (
 );
 ```
 
-Schema `defaultValue` fields are automatically extracted and merged with any explicit `defaultValues` you provide (explicit values take priority).
+Schema `defaultValue` fields are automatically extracted and merged with any explicit `defaultValues` you provide (explicit values take priority). Nested/namespaced defaults are extracted as a nested object (`{ address: { city } }`), so react-hook-form's dot-path resolution applies them correctly.
+
+Pass `resetOnSchemaChange: true` to re-seed the form when the `schema` identity changes at runtime (e.g. a schema loaded from a DB is swapped in). It's off by default because a reset discards in-progress edits.
 
 `generatorProps` is memoized — it only recomputes when `schema`, `control`, `disabled`, `variant`, or `className` change.
 
@@ -277,7 +324,11 @@ interface Section<T> {
 
 ```ts
 interface BaseField<T> {
-  name: string;                 // Field name (required)
+  // name accepts Path<T> or any string.
+  // Use field.for<T>() builders for call-site enforcement of valid paths.
+  // Relative names are correct for nameSpace sections and itemFields children —
+  // FormGenerator prefixes them at render time (e.g. "street" → "address.street").
+  name: Path<T> | string;       // Field name (required)
   type: FieldType;              // Field type (required)
   label?: string;               // Field label
   placeholder?: string;         // Placeholder text
@@ -298,8 +349,10 @@ interface BaseField<T> {
   loadOptions?: (formValues: Partial<T>) => Promise<FieldOption[]> | FieldOption[];
   debounceMs?: number;
 
-  // For array/grouped types
-  itemFields?: BaseField<T>[];
+  // Sub-fields for group and array types.
+  // Children use relative names ("street") — FormGenerator prefixes with parent name.
+  // Intentionally untyped to T because they resolve at render time, not authoring time.
+  itemFields?: BaseField[];
 
   // For select/radio/checkbox
   options?: FieldOption[];
@@ -342,9 +395,14 @@ interface FieldComponentProps<T extends FieldValues = FieldValues>
     isDirty: boolean;
     isTouched: boolean;
     isValidating: boolean;
+    isSubmitted: boolean;
     error?: FieldError;
   };
   fieldId: string;              // Generated ID for label-input association (e.g. "formkit-field-email")
+  errorId: string;              // ID for the error node — set as aria-errormessage on the input
+  shouldShowError: boolean;     // true only after touch/submit (mirrors :user-invalid timing)
+  rules: RegisterOptions;       // Pre-computed RHF rules from schema (required/min/max/pattern…)
+  isLoading?: boolean;          // true while async loadOptions is in flight
 }
 ```
 
@@ -447,6 +505,64 @@ function FormInput({ field, control, error, fieldId }: FieldComponentProps) {
 
 Maps `required`, `min`, `max`, `minLength`, `maxLength`, and `pattern` from the field schema to RHF-compatible rules with auto-generated error messages.
 
+## Validation & helpers
+
+### validateSchema
+
+Structurally validate a schema (great for DB-loaded / `resetOnSchemaChange`
+schemas). Server-safe; returns `SchemaIssue[]` (empty ⇒ OK). `FormGenerator`
+also runs it automatically in dev and `console.warn`s any issues.
+
+```ts
+import { validateSchema } from "@classytic/formkit"; // or /server
+
+for (const issue of validateSchema(schema)) {
+  console.warn(`${issue.severity} ${issue.path}: ${issue.message}`);
+}
+// Detects: missing name/type, duplicate names (namespace-aware),
+// itemFields on a non-container, empty containers, unknown DSL operators.
+```
+
+It validates **shape**, not your component registry — an unregistered field
+`type` is a rendering concern, surfaced separately (see `onMissingComponent`).
+
+### focusFirstError
+
+Focus + scroll to the first visibly-invalid field, in layout order. Wire it into
+the submit's invalid handler:
+
+```tsx
+import { focusFirstError } from "@classytic/formkit";
+
+<form onSubmit={handleSubmit(onValid, () => focusFirstError())}>
+```
+
+React Hook Form calls the invalid handler *before* React commits the re-render
+that marks fields invalid, so if the immediate query finds nothing,
+`focusFirstError` automatically retries on the next two animation frames — the
+plain wiring above works on the very first submit. It returns `true` when a
+field was focused immediately, `false` when the attempt was deferred.
+
+### onMissingComponent
+
+If a field's `type` has no registered component, the form renders a **visible
+placeholder** (dev and prod — never a silent drop or a wrong-widget text input)
+and notifies this callback so you can log the gap. `hidden` fields are the one
+exception: with no registered component they render nothing by design (the
+value still lives in form state); register a `hidden` component to override.
+
+```tsx
+<FormSystemProvider
+  components={components}
+  layouts={layouts}
+  onMissingComponent={(type) => reportToTelemetry("formkit_missing_component", { type })}
+>
+```
+
+> **Security note:** `buildValidationRules` compiles a field's `pattern` into a
+> `new RegExp(...)`. If your schemas are ever authored by untrusted users, treat
+> `pattern` as a ReDoS surface — validate/limit it before persisting.
+
 ## Server Components
 
 The `@classytic/formkit/server` entry point exports server-safe utilities with no React hooks or client-side code:
@@ -475,6 +591,24 @@ import type {
 
 Use this entry point in React Server Components to define schemas, evaluate conditions, or use `cn` without pulling in client-side code.
 
+### Passing a schema across the RSC → Client boundary
+
+`FormGenerator` is a Client Component (it drives react-hook-form). If you build
+a schema in a Server Component and pass it as a prop into the client, React
+requires that prop to be **serializable** — so **function** members won't cross
+the boundary:
+
+- ❌ function `condition: (values) => …`, custom `render`, and `loadOptions`
+  (functions aren't serializable)
+- ✅ **DSL** conditions (`{ watch, operator, value }`), and all the plain data
+  fields (`name`, `type`, `label`, `options`, `required`, `min`/`max`, …)
+
+For fully static, server-defined schemas use DSL conditions. If a schema needs
+function conditions / custom renders / async options, define it **inside the
+Client Component** (e.g. the file that renders `FormGenerator`) rather than
+passing it down from an RSC. This is a general Next.js constraint, not specific
+to formkit.
+
 ## Advanced Features
 
 ### Conditional Fields (Function)
@@ -488,6 +622,12 @@ Use this entry point in React Server Components to define schemas, evaluate cond
 }
 ```
 
+> **Performance:** a function condition can't be statically analyzed, so the
+> field subscribes to the **whole form** and re-evaluates on every change. For
+> large forms prefer a DSL rule (below, whose watched paths are auto-scoped), or
+> add `watchNames` to scope the subscription yourself:
+> `{ condition: (v) => v.accountType === "business", watchNames: ["accountType"] }`.
+
 ### Conditional Fields (DSL Rules)
 
 ```ts
@@ -585,14 +725,20 @@ const components = {
   name: "city",
   type: "select",
   watchNames: ["country"],
-  loadOptions: async (values) => {
-    const cities = await fetchCities(values.country);
+  loadOptions: async (values, { signal }) => {
+    // Forward `signal` so a superseded/unmounted load is cancelled.
+    const cities = await fetchCities(values.country, { signal });
     return cities.map(c => ({ label: c.name, value: c.id }));
   },
   debounceMs: 300,
+  cacheOptions: true, // reuse the last fetch when a dependency is re-selected
 }
 ```
 
+> `cacheOptions` (default `false`) memoizes results per watched-value signature
+> for the field's lifetime, so toggling `country` back and forth doesn't re-hit
+> the API. Leave it off when the options can change server-side between loads.
+
 ### Custom Section Render
 
 ```ts