`typescript
import { NdcForm, useFormField } from "@khamphamoi/form-builder";

type LoginForm = {
email: string;
password: string;
};

function EmailField() {
const field = useFormField({
name: "email",
initialValue: "",
validators: [
(value) => (!value ? "Email required" : null),
(value) => (!value?.includes("@") ? "Invalid email" : null),
],
});

return (


function App() {
return (
id="login" onSubmit={(values) => console.log(values)}>

{/ more fields... /}
Login

);
}
`

$3

`typescript
import { NdcForm, when, v } from "@khamphamoi/form-builder";

type ShippingForm = {
country: string;
state?: string;
province?: string;
};

const conditions = [
// Show 'state' only for US
when((values) => v(values, (x) => x.country) === "US")
.show((x) => x.state)
.hide((x) => x.province)
.toRules(),

// Show 'province' only for Canada
when((values) => v(values, (x) => x.country) === "CA")
.show((x) => x.province)
.hide((x) => x.state)
.toRules(),
].flat();

function App() {
return (
id="shipping" version="v1" conditions={conditions}>

{/ auto-hidden unless country=US /}
{/ auto-hidden unless country=CA /}

);
}
`

---

Core Concepts

$3

Access nested fields using dot notation:

`typescript
type Form = {
user: {
profile: {
name: string;
};
};
};

// Field path: "user.profile.name"
const field = useFormField({
name: "user.profile.name",
initialValue: "",
});
`

$3

Two styles supported:

`typescript
// Legacy validator (value only)
const required = (value: string) => (!value ? "Required" : null);

// Typed validator (value + all form values)
const matchPassword: TypedValidator = (value, values) =>
value !== values.password ? "Passwords must match" : null;
`

Validation Rules:

1. Hidden fields are never validated
2. Disabled fields are validated (unless also hidden)
3. Validation runs on:
- Field blur
- Form submit
- Manual field.validate() call

$3

Access form programmatically via ref:

`typescript
const formRef = useRef>(null);


{/ fields /}
;

// Later:
formRef.current?.email.set("user@example.com");
formRef.current?.validateAll();
const values = formRef.current?.getValues();
`

---

Conditional Logic (v1)

$3

`typescript
when(predicate)
.show(field) // Make field visible
.hide(field) // Make field invisible
.enable(field) // Enable field
.disable(field) // Disable field
.setValue(field, value) // Set field value
.clear(field) // Clear field value
.else() // Branch to opposite condition
.toRules(); // Convert to runtime rules
`

$3

Use the v() helper for type-safe value access:

`typescript
when((values) => v(values, (x) => x.shippingMethod) === "express").show(
(x) => x.deliveryDate
);
`

Why v()? It enables:

1. Type safety (autocomplete on x.shippingMethod)
2. Refactor safety (rename detection)
3. Runtime efficiency (accesses flat storage correctly)

$3

`typescript
// Multiple effects
when((values) => v(values, (x) => x.hasDiscount))
.show((x) => x.discountCode)
.enable((x) => x.applyDiscount)
.setValue((x) => x.discountPercent, 10)
.toRules();

// Computed values
when((values) => v(values, (x) => x.quantity) > 10)
.setValue(
(x) => x.total,
(values) => v(values, (x) => x.quantity) v(values, (x) => x.price) 0.9
)
.toRules();

// If/else branching
when((values) => v(values, (x) => x.paymentType) === "credit")
.show((x) => x.cardNumber)
.else()
.show((x) => x.bankAccount)
.toRules();
`

$3

When conditions conflict, higher priority wins:

`typescript
when(/ condition /)
.show((x) => x.field)
.withPriority(10) // This takes precedence over priority 5
.toRules();
`

---

Advanced Patterns

$3

Group fields into sections:

`typescript
import { NdcSection } from "@khamphamoi/form-builder";

name="billing" label="Billing Address">


;

// Hide entire section
when((values) => v(values, (x) => x.sameAsShipping))
.hide("billing")
.toRules();
`

Cascade Rule: Hiding a parent automatically hides all children and prevents their validation.

$3

`typescript
function TextField>({
name,
label,
validators,
}: NdcFieldProps) {
const field = useFormField({
name,
initialValue: "" as any,
validators,
});

return (


// Usage:

name="email"
label="Email Address"
validators={[required, validEmail]}
/>;
`

$3

`typescript
function DynamicForm() {
const [showAdvanced, setShowAdvanced] = useState(false);

return (
id="dynamic">


{showAdvanced && }
{/ Fields register/unregister automatically /}

setShowAdvanced(!showAdvanced)}>
Toggle Advanced


);
}
`

---

Architecture Principles

$3

`typescript
// Single source of truth
{
values: Record, // Field values
errors: Record, // Validation errors
meta: Record, // Visibility/enabled state
validators: Record
}
`

$3

Fields subscribe to changes:

`typescript
api.subscribeValue("email", () => rerender()); // Value changes
api.subscribeError("email", () => rerender()); // Error changes
api.subscribe(() => rerender()); // Any change (global)
`

$3

`
User types → Values change → Conditions re-evaluate →
Meta updates → Fields show/hide → Validation re-runs
`

Optimization: Conditions only run when subscribed values change.

$3

`typescript
// Instead of:
formRef.current.getValue("email");

// You write:
formRef.current.email.value; // Fully typed!
`

The Proxy intercepts property access and maps it to the correct API calls.

---

Migration Guide

$3

`typescript
// Before (v0)
id="form">{country === "US" && };

// After (v1)
const conditions = [
when((values) => v(values, (x) => x.country) === "US")
.show((x) => x.state)
.toRules(),
].flat();

id="form" version="v1" conditions={conditions}>
{/ Always rendered, visibility controlled by conditions /}
;
`

Benefits:

- Declarative (easier to test/reason about)
- Automatic validation gating
- No manual state management
- Serializable (can save/load condition rules)

---

Best Practices

$3

`typescript
// Good: Self-contained field
function EmailField() {
const field = useFormField({
name: 'email',
initialValue: '',
validators: [required, validEmail]
});

return field bindings /} />;
}
`

$3

`typescript
const required = (value: any) => (!value ? "Required" : null);
const minLength = (min: number) => (value: string) =>
value.length < min ? Min ${min} characters : null;
`

$3

`typescript




`

$3

`typescript
// Multiple conditions for same field
const conditions = [
when(/ condition A /).show("field").toRules(),
when(/ condition B /).hide("field").toRules(),
].flat(); // Flatten into single array
`

$3

`typescript
onSubmit={values => {
// This only runs if validateAll() passes
submitToServer(values);
}}
>
`

---

Philosophy

Ndc follows these design principles:

1. Type Safety Without Runtime Cost - Full TypeScript support with zero runtime type checks
2. Explicit Over Implicit - Clear APIs, no magic
3. Composition Over Configuration - Build complex forms from simple pieces
4. Declarative Conditions - What, not how
5. Performance by Default - Fine-grained subscriptions prevent unnecessary renders

The name "Ndc" suggests a form that acts as a communication portal - gathering structured data from users through a conversational, reactive interface.

---

API Reference

$3

| Prop | Type | Description |
| ------------ | ------------------------ | --------------------------- |
| id | string | Unique form identifier |
| version | 'v0' \| 'v1' | Form version (default: v0) |
| conditions | UntypedConditionRule[] | Conditional logic (v1 only) |
| onSubmit | (values) => void | Submit handler |
| children | ReactNode | Form fields |

$3

`typescript
function useFormField>(opts: {
name: P;
initialValue: FieldPathValue;
validators?: Validator[];
}): {
name: string;
value: T | undefined;
error: string | null;
setValue(value: T): void;
validate(): string | null;
};
`

$3

`typescript
when(predicate: (values: FormValues) => boolean)
.show(field: FieldPath | ((x: TShape) => any))
.hide(field)
.enable(field)
.disable(field)
.setValue

(field: P, value: FieldPathValue)
.clear(field)
.withPriority(n: number)
.else()
.toRules(): UntypedConditionRule[]
`

---

Examples Repository

See /examples for:

- Multi-step wizard
- Dynamic array fields
- Conditional sections
- Custom field libraries
- Form persistence
- Server-side validation

---

$3

`bash
npm install -g pnpm
`

$3

`bash
npm install -g vsts-npm-auth
`

---

Build the Package (Maintainers)

$3

`bash
pnpm install
`

$3

`bash
pnpm build
npm version prerelease --preid=beta
`

`bash
const checkEmailExists = async (email?: string) => {
if (!email) return null;
const exists = await backend.emailExists(email);
return exists ? "Email already exists" : null;
};

// Attach from outside UI:
formApi.setValidators("user.email", [checkEmailExists]);
``

License

MIT