useDynamicFormView

Installation

pnpm dlx @docyrus/cli add @docyrus/rn-hooks-use-dynamic-form-view

pnpm add jsonata @react-querybuilder/core

The native port of the web hook with the same signature. It drives the shared form-view engine (the same one behind useDocyrusFormView) but fetches nothing: you pass the IField[] schema, the values, static option lists, upload handlers and an onSubmit sink. Fields render through the native DocyFieldDynamic controls; view mode renders the value renderers, or EditableRecordDetail with clickToEdit.

Usage

import { ScrollView } from 'react-native';

import { Alert } from '@/components/docyrus-native/alert';
import { Button } from '@/components/docyrus-native/button';
import { type IField } from '@/components/docyrus-native/form-fields';
import { useDynamicFormView } from '@/hooks/docyrus-native/use-dynamic-form-view';

const fields: IField[] = [
  { id: '1', name: 'Title', slug: 'title', type: 'field-text', validations: ['required', 'minLength:3'] },
  { id: '2', name: 'Quantity', slug: 'quantity', type: 'field-number' },
  { id: '3', name: 'Unit price', slug: 'unit_price', type: 'field-money' },
  { id: '4', name: 'Total', slug: 'total', type: 'field-number', readOnly: true }
];

export function OrderForm() {
  const view = useDynamicFormView({
    fields,
    validationTokens: 'all',
    layout: [
      { id: 'main', variant: 'fieldset', title: 'Order', items: [{ type: 'field', slug: 'title', colSpan: 'full' }, 'quantity', 'unit_price', 'total'] }
    ],
    fieldLayout: {
      total: { computedFormula: '$number(quantity) * $number(unit_price)' }
    },
    onSubmit: payload => saveOrder(payload)
  });

  return (
    <ScrollView contentContainerClassName="gap-4 p-4">
      {view.formValidationErrors.length > 0 && (
        <Alert variant="destructive" title="Please fix the form" description={view.formValidationErrors.join('\n')} />
      )}
      {view.renderLayout()}
      <Button onPress={() => view.submit()} loading={view.isSubmitting}>Save</Button>
    </ScrollView>
  );
}

Uploads

onImageUpload / onFileUpload receive the picked asset as a NativeFile ({ uri, name, type, size? } from expo-image-picker / expo-document-picker) instead of a DOM File. Upload it and resolve to a StoredFileValue:

onImageUpload: async (file) => {
  const formData = new FormData();

  formData.append('file', { uri: file.uri, name: file.name, type: file.type } as never);

  return uploadToStorage(formData); // → { file_name, source, signed_url, file_type, file_size }
}

Per-field async option loaders are wired through fieldLayout[slug].fieldProps (onSearch / searching / onLoadMore / hasMore / onExpand).

Layout

layout is a tree of field slugs, { type: 'field', slug, colSpan } items and sections:

Fields not placed in the layout are appended after it. The grid is a flex-wrap grid: phones render one column, tablets honor gridColumns / columns (capped at 2 below 900pt) and colSpan (1–4 or 'full'). Sections span the full row unless they carry a colSpan.

Form-level styling

labelAlign / labelWidth / fieldSize / fieldVariant are resolved into field props (getFormLayoutFieldProps in form-fields/lib/form-layout) instead of the web descendant CSS selectors (Uniwind has none): labelAlign: 'left' → labelAlignment: 'left' + a fixed label column (sm w-24 / md w-40 / lg w-56), fieldSize → field size, fieldVariant: 'outline' | 'filled' → 'outlined' | 'filled'. Explicit fieldLayout[slug].fieldProps win.

Computed fields, actions and validation

• Computed (fieldLayout[slug] or IField): computedHidden / computedRequired (JSONata string or query-builder JSON), computedLabel / computedDescription (JSONata → string), computedFormula (JSONata → value written back into the field). Expressions evaluate against the live values (quantity * unit_price).
• Field actions (fieldActions, trigger onFieldChange): blocks of IF / ELSE IF (conditionalItems) / ELSE (elseActions) / ALWAYS (unconditionalActions) with the 8 step methods setFieldValue, setFieldValues, clearFieldValue, showField, hideField, setFieldRequired, setFieldDisabled, setFieldReadOnly.
• Form actions (formActions): the same blocks on onFormLoad, onFormBeforeSubmit and onFormAfterSubmit ($result bound).
• Priority: computed formulas > field-action overrides > form-action overrides > fieldLayout callbacks > IField defaults.
• Validation order per field: required (always) → tokens (validationTokens: 'off' advisory, 'form' only fieldLayout.validations, 'all' also the field's own tokens; resolved list on field.enforcedValidations, also used for the fields' live hints) → JSONata customValidations (value + values bound). Form-level formCustomValidations run once every field passes.
• Payload: read-only and disabled fields are excluded; companion columns (__<slug>_currency, __<slug>_country, status sub-fields, avatar mapping) are submitted with their field.

API Reference

Return Value

Type Exports