Schema-driven rendering
Conditional visibility
Conditional requiredness
Cross-field validation
Dynamic field arrays
Server validation
Draft persistence
Versioned schema migration
Permission-aware fields
Accessible error reporting
Observable submit workflow
Testable rules and transitions

JSON raksasa yang berubah menjadi bahasa pemrograman buruk
Component yang membaca schema langsung lalu punya ratusan if
Setiap field subscribe ke seluruh form state
Validation logic tersebar di 40 component
Submit handler yang menjadi procedural monster

Schema describes structure.
Registry maps type to implementation.
State store owns current values and meta.
Dependency graph knows what depends on what.
Validation engine produces errors.
Renderer maps resolved form model to UI.
Submit command is the only boundary to server mutation.

Store user-provided facts.
Derive everything that can be deterministically derived.
Persist only what can survive schema/version changes.

export type FormSchema = {
  schemaVersion: string;
  formId: string;
  title: string;
  sections: SectionSchema[];
};

export type SectionSchema = {
  id: string;
  title: string;
  description?: string;
  visibleWhen?: RuleExpr;
  fields: FieldSchema[];
};

export type FieldSchema =
  | TextFieldSchema
  | NumberFieldSchema
  | DateFieldSchema
  | SelectFieldSchema
  | RepeaterFieldSchema;

type BaseFieldSchema = {
  id: string;
  path: string;
  label: string;
  helpText?: string;
  requiredWhen?: RuleExpr;
  visibleWhen?: RuleExpr;
  disabledWhen?: RuleExpr;
  validate?: ValidationRule[];
  permissions?: FieldPermissionRule;
};

export type TextFieldSchema = BaseFieldSchema & {
  type: 'text';
  placeholder?: string;
  maxLength?: number;
};

export type SelectFieldSchema = BaseFieldSchema & {
  type: 'select';
  options: Array<{ value: string; label: string }>;
};

export type RepeaterFieldSchema = BaseFieldSchema & {
  type: 'repeater';
  minItems?: number;
  maxItems?: number;
  itemFields: FieldSchema[];
};

id      = identity untuk schema node
path    = address value dalam payload
label   = accessible label
rules   = expression yang dievaluasi engine
type    = lookup ke field registry

{
  visibleWhen: (values) => values.country === 'ID'
}

export type RuleExpr =
  | { op: 'equals'; path: string; value: unknown }
  | { op: 'notEquals'; path: string; value: unknown }
  | { op: 'exists'; path: string }
  | { op: 'and'; rules: RuleExpr[] }
  | { op: 'or'; rules: RuleExpr[] }
  | { op: 'not'; rule: RuleExpr };

export function evaluateRule(rule: RuleExpr | undefined, values: unknown): boolean {
  if (!rule) return true;

  switch (rule.op) {
    case 'equals':
      return getPath(values, rule.path) === rule.value;

    case 'notEquals':
      return getPath(values, rule.path) !== rule.value;

    case 'exists':
      return getPath(values, rule.path) != null;

    case 'and':
      return rule.rules.every((child) => evaluateRule(child, values));

    case 'or':
      return rule.rules.some((child) => evaluateRule(child, values));

    case 'not':
      return !evaluateRule(rule.rule, values);

    default: {
      const _exhaustive: never = rule;
      return _exhaustive;
    }
  }
}

export type FieldRendererProps<TField extends FieldSchema = FieldSchema> = {
  field: TField;
  value: unknown;
  error?: FieldError;
  meta: FieldMeta;
  disabled: boolean;
  required: boolean;
  onChange: (value: unknown) => void;
  onBlur: () => void;
};

export type FieldRenderer<TField extends FieldSchema = FieldSchema> =
  (props: FieldRendererProps<TField>) => React.ReactNode;

export type FieldRegistry = {
  text: FieldRenderer<TextFieldSchema>;
  number: FieldRenderer<NumberFieldSchema>;
  date: FieldRenderer<DateFieldSchema>;
  select: FieldRenderer<SelectFieldSchema>;
  repeater: FieldRenderer<RepeaterFieldSchema>;
};

function FieldNode({ field }: { field: FieldSchema }) {
  const registry = useFieldRegistry();
  const form = useFormEngine();

  const visible = form.useVisible(field.id);
  const value = form.useFieldValue(field.path);
  const error = form.useFieldError(field.path);
  const meta = form.useFieldMeta(field.path);
  const disabled = form.useDisabled(field.id);
  const required = form.useRequired(field.id);

  if (!visible) return null;

  const Renderer = registry[field.type] as FieldRenderer;

  return (
    <Renderer
      field={field}
      value={value}
      error={error}
      meta={meta}
      disabled={disabled}
      required={required}
      onChange={(next) => form.setFieldValue(field.path, next)}
      onBlur={() => form.markBlurred(field.path)}
    />
  );
}

<input value={String(value ?? '')} onChange={(e) => onChange(e.target.value)} />

function BufferedTextField({ value, onChange, onBlur }: FieldRendererProps<TextFieldSchema>) {
  const [draft, setDraft] = React.useState(() => String(value ?? ''));

  React.useEffect(() => {
    setDraft(String(value ?? ''));
  }, [value]);

  return (
    <input
      value={draft}
      onChange={(event) => setDraft(event.target.value)}
      onBlur={() => {
        onChange(draft);
        onBlur();
      }}
    />
  );
}

Use controlled field when value affects other fields immediately.
Use buffered field only when value is isolated and expensive to update per keystroke.

export type FormState = {
  values: Record<string, unknown>;
  meta: Record<string, FieldMeta>;
  errors: Record<string, FieldError[]>;
  submission: SubmissionState;
  schemaVersion: string;
};

export type FieldMeta = {
  touched: boolean;
  dirty: boolean;
  visited: boolean;
};

export type SubmissionState =
  | { tag: 'idle' }
  | { tag: 'submitting'; requestId: string }
  | { tag: 'succeeded'; submissionId: string }
  | { tag: 'failed'; requestId: string; reason: SubmitFailure };

export type FormEvent =
  | { type: 'FIELD_CHANGED'; path: string; value: unknown }
  | { type: 'FIELD_BLURRED'; path: string }
  | { type: 'FIELD_VISITED'; path: string }
  | { type: 'CLIENT_VALIDATION_COMPLETED'; errors: Record<string, FieldError[]> }
  | { type: 'SERVER_VALIDATION_FAILED'; errors: Record<string, FieldError[]> }
  | { type: 'SUBMIT_STARTED'; requestId: string }
  | { type: 'SUBMIT_SUCCEEDED'; requestId: string; submissionId: string }
  | { type: 'SUBMIT_FAILED'; requestId: string; reason: SubmitFailure }
  | { type: 'DRAFT_RESTORED'; snapshot: FormDraftSnapshot }
  | { type: 'FORM_RESET'; values?: Record<string, unknown> };

function formReducer(state: FormState, event: FormEvent): FormState {
  switch (event.type) {
    case 'FIELD_CHANGED': {
      return {
        ...state,
        values: setPathImmutable(state.values, event.path, event.value),
        meta: {
          ...state.meta,
          [event.path]: {
            ...state.meta[event.path],
            dirty: true,
          },
        },
      };
    }

    case 'SUBMIT_STARTED': {
      if (state.submission.tag === 'submitting') return state;
      return {
        ...state,
        submission: { tag: 'submitting', requestId: event.requestId },
      };
    }

    case 'SUBMIT_SUCCEEDED': {
      if (
        state.submission.tag !== 'submitting' ||
        state.submission.requestId !== event.requestId
      ) {
        return state;
      }

      return {
        ...state,
        submission: { tag: 'succeeded', submissionId: event.submissionId },
      };
    }

    default:
      return state;
  }
}

const schema: FormSchema = {
  schemaVersion: '2026-07',
  formId: 'risk-assessment',
  title: 'Risk Assessment',
  sections: [
    {
      id: 'business',
      title: 'Business',
      fields: [
        {
          id: 'country',
          path: 'business.country',
          type: 'select',
          label: 'Country',
          options: [
            { value: 'ID', label: 'Indonesia' },
            { value: 'SG', label: 'Singapore' },
          ],
        },
        {
          id: 'taxId',
          path: 'business.taxId',
          type: 'text',
          label: 'Tax ID',
          visibleWhen: { op: 'equals', path: 'business.country', value: 'ID' },
          requiredWhen: { op: 'equals', path: 'business.country', value: 'ID' },
        },
      ],
    },
  ],
};

export type DependencyGraph = {
  dependentsByPath: Map<string, Set<string>>;
};

export function buildDependencyGraph(schema: FormSchema): DependencyGraph {
  const dependentsByPath = new Map<string, Set<string>>();

  for (const field of walkFields(schema)) {
    const dependencies = collectRulePaths([
      field.visibleWhen,
      field.requiredWhen,
      field.disabledWhen,
      ...(field.validate ?? []).map((rule) => rule.when),
    ]);

    for (const path of dependencies) {
      const set = dependentsByPath.get(path) ?? new Set<string>();
      set.add(field.id);
      dependentsByPath.set(path, set);
    }
  }

  return { dependentsByPath };
}

changed path: business.country
affected nodes: taxId, regionalComplianceSection, taxDocumentRepeater

Keep in draft.
Exclude from submit payload when invisible unless schema explicitly says otherwise.
Audit when field with value becomes excluded.

export function buildSubmitPayload(
  schema: FormSchema,
  values: Record<string, unknown>,
  visibility: Record<string, boolean>,
): Record<string, unknown> {
  let payload: Record<string, unknown> = {};

  for (const field of walkFields(schema)) {
    if (!visibility[field.id]) continue;

    const value = getPath(values, field.path);
    payload = setPathImmutable(payload, field.path, value);
  }

  return payload;
}

export type FieldError = {
  code: string;
  message: string;
  severity: 'error' | 'warning';
  source: 'client' | 'server' | 'business';
};

export type FormError = {
  code: string;
  message: string;
  fieldPaths?: string[];
};

export type ValidationRule =
  | { kind: 'required'; message?: string; when?: RuleExpr }
  | { kind: 'minLength'; value: number; message?: string; when?: RuleExpr }
  | { kind: 'maxLength'; value: number; message?: string; when?: RuleExpr }
  | { kind: 'regex'; pattern: string; message?: string; when?: RuleExpr }
  | { kind: 'customCode'; code: string; message?: string; when?: RuleExpr };

export type ValidatorRegistry = {
  [code: string]: (input: {
    value: unknown;
    values: Record<string, unknown>;
    field: FieldSchema;
  }) => FieldError | null;
};

if (values.a && values.b && values.c !== ...) {
  // ...
}

export type ValidationNode = {
  id: string;
  outputPath?: string;
  dependencies: string[];
  validate: (values: Record<string, unknown>) => FieldError[];
};

const dateRangeValidator: ValidationNode = {
  id: 'date-range',
  outputPath: 'period.endDate',
  dependencies: ['period.startDate', 'period.endDate'],
  validate(values) {
    const start = getPath(values, 'period.startDate');
    const end = getPath(values, 'period.endDate');

    if (!start || !end) return [];
    if (new Date(String(end)) < new Date(String(start))) {
      return [
        {
          code: 'END_BEFORE_START',
          message: 'End date must be after start date.',
          severity: 'error',
          source: 'client',
        },
      ];
    }

    return [];
  },
};

export type RepeaterItem = {
  itemId: string;
  value: Record<string, unknown>;
};

{
  "owners": [
    { "itemId": "tmp_1", "name": "A", "share": 60 },
    { "itemId": "tmp_2", "name": "B", "share": 40 }
  ]
}

function RepeaterField({ field, value, onChange }: FieldRendererProps<RepeaterFieldSchema>) {
  const items = Array.isArray(value) ? value : [];

  return (
    <div>
      {items.map((item, index) => (
        <div key={item.itemId}>
          {field.itemFields.map((childField) => (
            <FieldNode
              key={childField.id}
              field={rewriteFieldPath(childField, `${field.path}.${index}`)}
            />
          ))}

          <button
            type="button"
            onClick={() => onChange(items.filter((_, i) => i !== index))}
          >
            Remove
          </button>
        </div>
      ))}

      <button
        type="button"
        onClick={() => onChange([...items, createEmptyRepeaterItem(field)])}
      >
        Add
      </button>
    </div>
  );
}

const values = useFormValues();
const value = values[field.path];

const value = useFieldValue(field.path);

function useFieldValue(path: string) {
  const store = useFormStore();

  return useSyncExternalStoreWithSelector(
    store.subscribe,
    store.getSnapshot,
    store.getServerSnapshot,
    (snapshot) => getPath(snapshot.values, path),
    Object.is,
  );
}

function FormRenderer({ schema }: { schema: FormSchema }) {
  return schema.sections.map((section) => (
    <SectionNode key={section.id} section={section} />
  ));
}

const FieldNode = React.memo(function FieldNode({ field }: { field: FieldSchema }) {
  // subscribe narrowly here
});

export type FormDraftSnapshot = {
  formId: string;
  schemaVersion: string;
  savedAt: string;
  values: Record<string, unknown>;
  meta?: Record<string, FieldMeta>;
};

export type DraftAdapter = {
  load(input: { formId: string; userId: string }): Promise<FormDraftSnapshot | null>;
  save(input: { formId: string; userId: string; snapshot: FormDraftSnapshot }): Promise<void>;
  clear(input: { formId: string; userId: string }): Promise<void>;
};

Debounce writes.
Do not save invalid transient every keystroke if payload is huge.
Include schemaVersion.
Use migration before restore.
Handle multi-tab conflict.
Never persist secrets unless explicitly allowed.

export type DraftMigration = {
  from: string;
  to: string;
  migrate(values: Record<string, unknown>): Record<string, unknown>;
};

export function restoreDraft(
  draft: FormDraftSnapshot,
  currentSchema: FormSchema,
  migrations: DraftMigration[],
): Record<string, unknown> {
  let values = draft.values;
  let version = draft.schemaVersion;

  while (version !== currentSchema.schemaVersion) {
    const migration = migrations.find((m) => m.from === version);
    if (!migration) {
      throw new Error(`No draft migration from ${version} to ${currentSchema.schemaVersion}`);
    }
    values = migration.migrate(values);
    version = migration.to;
  }

  return values;
}

export type SubmitFormResponse =
  | {
      ok: true;
      submissionId: string;
      nextRoute?: string;
    }
  | {
      ok: false;
      kind: 'validation_failed';
      fieldErrors: Record<string, FieldError[]>;
      formErrors: FormError[];
    }
  | {
      ok: false;
      kind: 'conflict';
      message: string;
      latestVersion: string;
    }
  | {
      ok: false;
      kind: 'forbidden';
      message: string;
    };

async function submitForm(input: SubmitInput) {
  const clientErrors = validateForm(input.schema, input.values);

  if (hasBlockingErrors(clientErrors)) {
    input.dispatch({ type: 'CLIENT_VALIDATION_COMPLETED', errors: clientErrors });
    focusFirstError(clientErrors);
    return;
  }

  const requestId = crypto.randomUUID();
  input.dispatch({ type: 'SUBMIT_STARTED', requestId });

  const response = await input.api.submit({
    formId: input.schema.formId,
    schemaVersion: input.schema.schemaVersion,
    payload: buildSubmitPayload(input.schema, input.values, input.visibility),
    idempotencyKey: requestId,
  });

  if (response.ok) {
    input.dispatch({ type: 'SUBMIT_SUCCEEDED', requestId, submissionId: response.submissionId });
    return;
  }

  if (response.kind === 'validation_failed') {
    input.dispatch({ type: 'SERVER_VALIDATION_FAILED', errors: response.fieldErrors });
    focusFirstError(response.fieldErrors);
    return;
  }

  input.dispatch({ type: 'SUBMIT_FAILED', requestId, reason: response });
}

function SubmitButton() {
  const status = useFormStatus();

  return (
    <button type="submit" disabled={status.pending}>
      {status.pending ? 'Submitting…' : 'Submit'}
    </button>
  );
}

schema validation
field registry
draft lifecycle
permission handling
client/server validation mapping
audit/telemetry

export type AccessibleFieldIds = {
  inputId: string;
  labelId: string;
  descriptionId?: string;
  errorId?: string;
};

function TextField({ field, value, error, required, disabled, onChange, onBlur }: FieldRendererProps<TextFieldSchema>) {
  const inputId = React.useId();
  const errorId = `${inputId}-error`;
  const helpId = `${inputId}-help`;

  return (
    <div>
      <label htmlFor={inputId}>
        {field.label} {required ? <span aria-hidden="true">*</span> : null}
      </label>

      {field.helpText ? <p id={helpId}>{field.helpText}</p> : null}

      <input
        id={inputId}
        value={String(value ?? '')}
        required={required}
        disabled={disabled}
        aria-invalid={Boolean(error) || undefined}
        aria-describedby={[field.helpText ? helpId : null, error ? errorId : null]
          .filter(Boolean)
          .join(' ') || undefined}
        onChange={(event) => onChange(event.target.value)}
        onBlur={onBlur}
      />

      {error ? <p id={errorId} role="alert">{error.message}</p> : null}
    </div>
  );
}

function ErrorSummary({ errors }: { errors: Record<string, FieldError[]> }) {
  const items = Object.entries(errors).filter(([, fieldErrors]) => fieldErrors.length > 0);

  if (items.length === 0) return null;

  return (
    <section role="alert" aria-labelledby="form-errors-title" tabIndex={-1}>
      <h2 id="form-errors-title">Please fix the following errors</h2>
      <ul>
        {items.map(([path, fieldErrors]) => (
          <li key={path}>
            <a href={`#${fieldIdFromPath(path)}`}>{fieldErrors[0].message}</a>
          </li>
        ))}
      </ul>
    </section>
  );
}

visibility
editable/read-only state
submit payload
audit explanation
server command authorization

export type FieldPermissionDecision = {
  visible: boolean;
  editable: boolean;
  reason?: string;
};

function PermissionAwareField({ field }: { field: FieldSchema }) {
  const decision = useFieldPermission(field.id);

  if (!decision.visible) return null;

  return (
    <FieldNode
      field={field}
      forcedDisabled={!decision.editable}
      disabledReason={decision.reason}
    />
  );
}

Frontend permission is UX and intent guard.
Server authorization is final authority.

formId
schemaVersion
rendered field set
visible field set
submitted payload
client validation version
server validation version
user id / actor id
timestamp
correlation id

export type FormAuditEvent =
  | { type: 'FORM_RENDERED'; formId: string; schemaVersion: string; correlationId: string }
  | { type: 'FIELD_CHANGED'; path: string; correlationId: string }
  | { type: 'FIELD_EXCLUDED_FROM_SUBMIT'; path: string; reason: string; correlationId: string }
  | { type: 'CLIENT_VALIDATION_FAILED'; errorCount: number; correlationId: string }
  | { type: 'SERVER_VALIDATION_FAILED'; errorCount: number; correlationId: string }
  | { type: 'FORM_SUBMITTED'; submissionId: string; correlationId: string };

Schema mana yang user lihat?
Field mana yang hidden saat submit?
Validation mana yang gagal?
Apakah server menolak karena stale schema, permission, atau business rule?
Berapa lama user stuck di section tertentu?

features/form-builder/
  model/
    schema.ts
    rules.ts
    validation.ts
    dependency-graph.ts
    form-reducer.ts
    form-store.ts
    draft.ts
    submit.ts
  ui/
    FormRenderer.tsx
    SectionNode.tsx
    FieldNode.tsx
    ErrorSummary.tsx
  fields/
    TextField.tsx
    SelectField.tsx
    DateField.tsx
    RepeaterField.tsx
    registry.ts
  adapters/
    react-hook-form-adapter.ts
    tanstack-query-submit-adapter.ts
    local-draft-adapter.ts
  tests/
    schema-fixtures.ts
    validation.test.ts
    renderer.test.tsx
    submit-flow.test.tsx

ui -> model allowed
fields -> model allowed
model -> ui forbidden
model -> adapters forbidden
adapters -> model allowed

it('ignores stale submit success', () => {
  const state: FormState = {
    values: {},
    meta: {},
    errors: {},
    schemaVersion: '1',
    submission: { tag: 'submitting', requestId: 'newer' },
  };

  const next = formReducer(state, {
    type: 'SUBMIT_SUCCEEDED',
    requestId: 'older',
    submissionId: 'sub_1',
  });

  expect(next.submission).toEqual({ tag: 'submitting', requestId: 'newer' });
});

Given country is SG
Then Tax ID is not visible
When country changes to ID
Then Tax ID appears and is required
When user submits without Tax ID
Then focus moves to Tax ID error
And submit command is not sent

schema has scripts
conditions are impossible to audit
business users can create untestable logic
server cannot validate same rules

Use constrained expression AST.
Version expressions.
Validate schema before publish.
Create rule test fixtures.

field.id for schema identity
field.path for value address
itemId for dynamic array identity

Build submit payload from visible/resolved schema.
Do not submit raw values object.
Audit excluded fields if necessary.

Move validation into validation graph.
Test validation without React.

Version every draft.
Require migration or explicit discard path.

Never key by array index.
Preserve item identity.

Use field-level subscription.
Split component boundaries.
Profile before memoizing blindly.

Frontend guards improve UX only.
Server authorization remains final.

[ ] Schema has version.
[ ] Schema is validated before use.
[ ] Field id and field path are distinct.
[ ] Field registry has typed renderer contract.
[ ] Dynamic arrays use stable item identity.
[ ] Value state and meta state are separate.
[ ] Derived visibility/requiredness is not stored as source of truth.
[ ] Hidden-field submit policy is explicit.
[ ] Validation is centralized and testable.
[ ] Server validation maps back to field paths.
[ ] Submit command uses request identity/idempotency.
[ ] Draft persistence is versioned and migratable.
[ ] Permission affects UI but server remains authority.
[ ] Accessibility labels/errors/focus are tested.
[ ] Observability records schema version and error taxonomy.
[ ] Form model layer is testable without React.

A field component renders and reports intent.
The form engine owns value/meta/errors.
The rules engine derives visibility/requiredness/validation.
The submit command owns server interaction.
The schema is versioned evidence of what the user was asked to provide.