@formality-ui/react 0.0.0 → 0.1.0

package/README.md

@@ -13,6 +13,7 @@ yarn add @formality-ui/react react-hook-form
 ```
 
 **Peer Dependencies:**
+
 - `react` >= 18.0.0
 - `react-dom` >= 18.0.0
 - `react-hook-form` >= 7.0.0
@@ -20,8 +21,8 @@ yarn add @formality-ui/react react-hook-form
 ## Quick Start
 
 ```tsx
-import { FormalityProvider, Form, Field } from '@formality-ui/react';
-import type { InputConfig, FormFieldsConfig } from '@formality-ui/react';
+import { FormalityProvider, Form, Field } from "@formality-ui/react";
+import type { InputConfig, FormFieldsConfig } from "@formality-ui/react";
 
 // Define your input types
 const inputs: Record<string, InputConfig> = {
@@ -29,16 +30,24 @@ const inputs: Record<string, InputConfig> = {
     component: ({ value, onChange, label, error, ...props }) => (
       <div>
         <label>{label}</label>
-        <input value={value ?? ''} onChange={(e) => onChange(e.target.value)} {...props} />
+        <input
+          value={value ?? ""}
+          onChange={(e) => onChange(e.target.value)}
+          {...props}
+        />
         {error && <span>{error}</span>}
       </div>
     ),
-    defaultValue: '',
+    defaultValue: "",
   },
   switch: {
     component: ({ value, onChange, label }) => (
       <label>
-        <input type="checkbox" checked={value ?? false} onChange={(e) => onChange(e.target.checked)} />
+        <input
+          type="checkbox"
+          checked={value ?? false}
+          onChange={(e) => onChange(e.target.checked)}
+        />
         {label}
       </label>
     ),
@@ -48,9 +57,9 @@ const inputs: Record<string, InputConfig> = {
 
 // Define your form fields
 const config: FormFieldsConfig = {
-  name: { type: 'textField', label: 'Full Name' },
-  email: { type: 'textField', label: 'Email Address' },
-  subscribed: { type: 'switch', label: 'Subscribe to newsletter' },
+  name: { type: "textField", label: "Full Name" },
+  email: { type: "textField", label: "Email Address" },
+  subscribed: { type: "switch", label: "Subscribe to newsletter" },
 };
 
 // Use in your app
@@ -181,7 +190,7 @@ Apply conditions to multiple fields.
 const formConfig = {
   groups: {
     signedFields: {
-      conditions: [{ when: 'signed', is: true, disabled: false }],
+      conditions: [{ when: "signed", is: true, disabled: false }],
     },
   },
 };
@@ -189,7 +198,7 @@ const formConfig = {
 <FieldGroup name="signedFields">
   <Field name="creditApp" />
   <Field name="inCarvin" />
-</FieldGroup>
+</FieldGroup>;
 ```
 
 **Props:**
@@ -221,12 +230,12 @@ Add conditional logic to fields:
 
 ```typescript
 const config: FormFieldsConfig = {
-  signed: { type: 'switch' },
+  signed: { type: "switch" },
   creditApp: {
-    type: 'switch',
+    type: "switch",
     conditions: [
-      { when: 'signed', is: false, disabled: true },
-      { when: 'signed', is: true, visible: true },
+      { when: "signed", is: false, disabled: true },
+      { when: "signed", is: true, visible: true },
     ],
   },
 };
@@ -255,13 +264,13 @@ Evaluate props dynamically based on form state:
 
 ```typescript
 const config: FormFieldsConfig = {
-  client: { type: 'autocomplete' },
+  client: { type: "autocomplete" },
   clientContact: {
-    type: 'autocomplete',
+    type: "autocomplete",
     selectProps: {
-      queryParams: 'client.id',
-      disabled: '!client',
-      placeholder: 'client.name',
+      queryParams: "client.id",
+      disabled: "!client",
+      placeholder: "client.name",
     },
   },
 };
@@ -291,10 +300,11 @@ Enable automatic form submission on changes:
 Access form state and methods from any child component:
 
 ```typescript
-import { useFormContext } from '@formality-ui/react';
+import { useFormContext } from "@formality-ui/react";
 
 function CustomComponent() {
-  const { config, methods, record, unusedFields, submitImmediate } = useFormContext();
+  const { config, methods, record, unusedFields, submitImmediate } =
+    useFormContext();
   // ...
 }
 ```
@@ -304,7 +314,7 @@ function CustomComponent() {
 Evaluate conditions manually:
 
 ```typescript
-import { useConditions } from '@formality-ui/react';
+import { useConditions } from "@formality-ui/react";
 
 const { disabled, visible, setValue } = useConditions({
   conditions: fieldConfig.conditions,
@@ -316,7 +326,7 @@ const { disabled, visible, setValue } = useConditions({
 Evaluate dynamic props:
 
 ```typescript
-import { usePropsEvaluation } from '@formality-ui/react';
+import { usePropsEvaluation } from "@formality-ui/react";
 
 const evaluatedProps = usePropsEvaluation(selectProps, watchedValues);
 ```
@@ -326,7 +336,7 @@ const evaluatedProps = usePropsEvaluation(selectProps, watchedValues);
 Subscribe to form state changes:
 
 ```typescript
-import { useFormState } from '@formality-ui/react';
+import { useFormState } from "@formality-ui/react";
 
 const { methods, formState } = useFormState(options);
 ```
@@ -336,7 +346,7 @@ const { methods, formState } = useFormState(options);
 Subscribe to field value changes:
 
 ```typescript
-import { useSubscriptions } from '@formality-ui/react';
+import { useSubscriptions } from "@formality-ui/react";
 
 const watchedValues = useSubscriptions(fieldNames);
 ```
@@ -346,7 +356,7 @@ const watchedValues = useSubscriptions(fieldNames);
 Infer input configurations:
 
 ```typescript
-import { useInferredInputs } from '@formality-ui/react';
+import { useInferredInputs } from "@formality-ui/react";
 
 const inputs = useInferredInputs(config);
 ```
@@ -358,9 +368,10 @@ const inputs = useInferredInputs(config);
 Global configuration context:
 
 ```typescript
-import { useConfigContext } from '@formality-ui/react';
+import { useConfigContext } from "@formality-ui/react";
 
-const { inputs, validators, formatters, parsers, errorMessages } = useConfigContext();
+const { inputs, validators, formatters, parsers, errorMessages } =
+  useConfigContext();
 ```
 
 ### FormContext
@@ -368,7 +379,7 @@ const { inputs, validators, formatters, parsers, errorMessages } = useConfigCont
 Form-level context:
 
 ```typescript
-import { useFormContext } from '@formality-ui/react';
+import { useFormContext } from "@formality-ui/react";
 
 const { config, methods, record, formConfig, unusedFields } = useFormContext();
 ```
@@ -378,7 +389,7 @@ const { config, methods, record, formConfig, unusedFields } = useFormContext();
 Group-level context for nested conditions:
 
 ```typescript
-import { useGroupContext } from '@formality-ui/react';
+import { useGroupContext } from "@formality-ui/react";
 
 const groupState = useGroupContext();
 ```
@@ -420,9 +431,189 @@ import type {
   UseFormStateOptions,
   WatcherSetterFn,
   DebouncedFunction,
-} from '@formality-ui/react';
+
+  // React type overlays — precise React/RHF types layered over core's loose
+  // `unknown` types. Prefer these in React code (see Type Safety below).
+  ReactInputConfig,
+  ReactFieldConfig,
+  ReactFormFieldsConfig,
+  FormalityFieldComponentProps,
+
+  // Re-exported react-hook-form types — so consumers need no direct RHF import.
+  RefCallBack,
+  UseFormStateReturn,
+  FieldValues,
+} from "@formality-ui/react";
+
+// `defineInputs` is a VALUE export (an identity helper), not a type — import
+// it separately, not inside an `import type { ... }` block.
+import { defineInputs } from "@formality-ui/react";
+```
+
+## Type Safety
+
+Formality ships opt-in, compile-time checking for the three places typos hurt
+most: **Form config keys**, **Field names**, and **input `type` strings**. It
+also ships a precise type for the props Formality injects onto your field
+components, so you can stop hand-rolling a lossy `WithFormality<P>` helper.
+
+All of the checks below are **opt-in and non-breaking** — the non-generic
+`<Form>`, `<Field>`, and `InputConfig`/`FormFieldsConfig` patterns shown in
+[Quick Start](#quick-start) keep working byte-for-byte. The overlays below are
+the recommended pattern for new React code.
+
+### Checked Form config keys (`<Form<TFieldValues>>`)
+
+`<Form>` is generic over your form's field-values type. With the default
+generic, any string key is accepted (unchanged behavior). Narrow the generic to
+your values type and unknown `config` keys become a **compile error** —
+catching typos like `ofice` at compile time instead of silently rendering
+nothing.
+
+```tsx
+import { Form } from "@formality-ui/react";
+import type { ReactFormFieldsConfig } from "@formality-ui/react";
+
+type ClientValues = { name: string; email: string; subscribed: boolean };
+
+// ✅ Narrowed — only known field names are accepted.
+const config: ReactFormFieldsConfig<ClientValues> = {
+  name: { type: "textField", label: "Full Name" },
+  email: { type: "textField", label: "Email" },
+  subscribed: { type: "switch", label: "Subscribe" },
+};
+
+// @ts-expect-error — typo `ofice` is rejected when the generic is narrowed.
+const bad: ReactFormFieldsConfig<ClientValues> = {
+  ofice: { type: "textField" },
+};
+
+<Form<ClientValues> config={config}>{/* ... */}</Form>;
+```
+
+The default `<Form>` (no generic) still accepts any string key, so existing
+consumers migrate at their own pace.
+
+### Checked Field names (`FieldProps<TName>`)
+
+By default `<Field name="..." />` accepts **any string** — this is backwards
+compatible and matches the Quick Start. Name-checking engages **only when
+`FieldProps` is explicitly narrowed**.
+
+> React generics do **not** thread from `<Form<T>>` into its children, so a
+> `<Form<ClientValues>>` does **not** automatically narrow the `name` on a
+> child `<Field>`. To check field names you narrow `FieldProps` explicitly
+> (the honest pattern below), typically via a thin typed wrapper.
+
+```tsx
+import { Field } from "@formality-ui/react";
+import type { FieldProps } from "@formality-ui/react";
+
+type ClientValues = { name: string; email: string; subscribed: boolean };
+type Names = keyof ClientValues; // "name" | "email" | "subscribed"
+
+// Default usage — any string name compiles (unchanged):
+<Field name="anything" />;
+
+// Opt-in strict usage — a typed wrapper that narrows FieldProps:
+function TypedField(props: FieldProps<Names>) {
+  return <Field {...props} />;
+}
+
+<TypedField name="email" />; // ✅
+// @ts-expect-error — typo `ofice` is rejected once FieldProps is narrowed.
+const _bad: FieldProps<Names> = { name: "ofice" };
+```
+
+Automatic per-form narrowing — where a `<Field>` auto-narrows against the
+enclosing `<Form<TFieldValues>>`'s key set — is a planned follow-up.
+
+### Checking input types with `defineInputs` (opt-in)
+
+`type: "textField"` typos (e.g. `type: "texField"`) are invisible by default
+because `FieldConfig.type` / `FieldProps.type` default to `string`.
+`defineInputs` is an **identity helper** that lets you derive a checked union
+of your input-type keys, which you can then thread into `type`.
+
+`defineInputs` is a **value** export (it returns `inputs` unchanged with zero
+runtime effect — bundlers tree-shake it to nothing). Import it as a value, not
+`import type`:
+
+```tsx
+import { defineInputs } from "@formality-ui/react";
+
+const inputs = defineInputs({
+  textField: { component: TextField, defaultValue: "" },
+  switch: { component: Switch, defaultValue: false },
+});
+
+// "textField" | "switch" — a checked union of your input-type keys.
+export type InputType = keyof typeof inputs;
+```
+
+This is purely additive — the existing non-generic `Field` and
+`FieldConfig.type` still work unchanged. End-to-end wiring of `InputType` into
+those types is a follow-up; `defineInputs` is the opt-in entry point.
+
+### Field component props: `FormalityFieldComponentProps`
+
+`<Field>` renders your input component via React Hook Form's `<Controller>` and
+injects a bundle of props onto it. `FormalityFieldComponentProps<P>` is the
+**precise** type for that contract — replacing the lossy `WithFormality<P>`
+helper consumers (e.g. `sellario-ui`) hand-roll today.
+
+**Before — the lossy hand-rolled helper:**
+
+```tsx
+// ❌ Lossy: state/formState are `unknown`, and forwardRef is the wrong type.
+type WithFormality<P> = P & {
+  state?: unknown;
+  formState?: unknown;
+  forwardRef?: React.Ref<HTMLInputElement>; // wrong: RHF hands a RefCallBack
+};
+```
+
+**After — the shipped precise type:**
+
+```tsx
+import type { FormalityFieldComponentProps } from "@formality-ui/react";
+
+// FormalityFieldComponentProps<P = unknown> = P & {
+//   state?: CustomFieldState | Record<string, CustomFieldState>;
+//   formState?: UseFormStateReturn<FieldValues>;
+//   forwardRef?: RefCallBack;
+// }
+
+type TextFieldProps = { label?: string };
+
+const TextField: React.ComponentType<
+  FormalityFieldComponentProps<TextFieldProps>
+> = ({ state, formState, forwardRef, ...domProps }) => (
+  <input ref={forwardRef} {...domProps} />
+);
 ```
 
+**Destructure before forwarding.** Always pull `state`, `formState`, and
+`forwardRef` **out** of props before spreading the rest onto the underlying DOM
+node — otherwise these non-DOM props leak to the DOM and React warns.
+
+**Wiring `forwardRef` to the inner input.** `forwardRef` is RHF's `RefCallBack`
+(`(instance: any) => void`), **not** `React.Ref<HTMLInputElement>`. For a
+plain `<input>` use `ref={forwardRef}`. For **MUI v9** components (e.g.
+`Checkbox`) that no longer accept a top-level `inputRef`, wire it via slots:
+
+```tsx
+slotProps={{ input: { ref: forwardRef } }}
+```
+
+**Runtime caveat (important).** Today `Field` delivers the RHF ref via the
+React-special `ref` key, **not** a top-level `forwardRef` prop. To receive it
+as `forwardRef` on a bare function component, either wrap your component with
+`React.forwardRef`, or target React 19's ref-as-prop. Making `Field` deliver a
+top-level `forwardRef` key for bare components is a future runtime task; the
+type ships the **intended contract now** so consumers can stop hand-rolling
+`WithFormality`.
+
 ## Utilities
 
 ### makeProxyState
@@ -430,12 +621,39 @@ import type {
 Create proxy state for efficient subscriptions:
 
 ```typescript
-import { makeProxyState, makeDeepProxyState } from '@formality-ui/react';
+import { makeProxyState, makeDeepProxyState } from "@formality-ui/react";
 
 const proxy = makeProxyState(initialState);
 const deepProxy = makeDeepProxyState(initialState);
 ```
 
+## Testing & Coverage
+
+Run the test suite with coverage from the repo root:
+
+```bash
+pnpm test:coverage
+# equivalent to: vitest run --coverage
+```
+
+Coverage is enforced as a **hard gate**: the run exits non-zero if **any** of
+statements, branches, functions, or lines drop below **90%**
+([vitest coverage thresholds](https://vitest.dev/guide/coverage.html#coverage-thresholds)).
+
+Coverage is computed **repo-wide** (merged across `packages/core` and
+`packages/react`), excluding only the directories below:
+
+| Glob                 | Reason                 |
+| -------------------- | ---------------------- |
+| `examples/**`        | Demo apps; not shipped |
+| `packages/svelte/**` | Stubbed adapter        |
+| `packages/vue/**`    | Stubbed adapter        |
+| `**/dist/**`         | Build output           |
+
+All other code — `packages/core/**`, `packages/react/**`, and any future
+adapter with a real implementation — is in scope and must clear 90%. See
+`vitest.config.ts` for the exact configuration.
+
 ## License
 
 MIT