useDocyrusFormView

Installation

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

pnpm add @docyrus/api-client @docyrus/app-utils @tanstack/react-query jsonata

The native port of the web hook with the same signature. It is a thin Docyrus adapter over the shared form-view engine (see useDynamicFormView for the backend-agnostic sibling):

• Schema through the shared inventory cache (useDocyrusInventory), with a scoped expand fetch on a cache miss. Enum options come from the fields' inline enums, with a one-off /v1/apps/enums fallback when a field has none.
• Record from /v1/apps/{app}/data-sources/{ds}/items/{itemId} (companion columns included; a missing column is stripped and retried).
• Options: /v1/users for user fields, the related data source's items for relation fields.
• Uploads: image and file fields upload to /v1/apps/{app}/data-sources/{ds}/files/upload as an RN FormData part ({ uri, name, type }) and store the returned StoredFileValue.
• Persistence: create → POST …/items, edit (and inline click-to-edit saves) → PATCH …/items/{itemId}, or your collection / onSubmit.
• Saved forms: pass formLayout (a saved form's layout) to derive the layout, per-field overrides, validation tokens, form actions and label styling.

It needs an authenticated RestApiClient and a QueryClientProvider above it.

Usage

import { ScrollView } from 'react-native';

import { useDocyrusClient } from '@docyrus/signin/react-native';

import { Button } from '@/components/docyrus-native/button';
import { useDocyrusFormView } from '@/hooks/docyrus-native/use-docyrus-form-view';

export function ContactForm({ contactId }: { contactId?: string }) {
  const client = useDocyrusClient();
  const view = useDocyrusFormView({
    client: client!,
    appSlug: 'base',
    dataSourceSlug: 'contact',
    itemId: contactId,
    validationTokens: 'form',
    onSubmitSuccess: () => navigation.goBack()
  });

  if (view.isLoading) return null;

  return (
    <ScrollView contentContainerClassName="gap-4 p-4">
      {view.renderLayout()}
      <Button onPress={() => view.submit()} loading={view.isSubmitting}>Save</Button>
    </ScrollView>
  );
}

Read-only detail screen with inline editing:

const view = useDocyrusFormView({ client, appSlug: 'base', dataSourceSlug: 'contact', itemId, mode: 'view', clickToEdit: true });

return view.renderLayout(); // EditableRecordDetail — each save PATCHes the record

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.

Native differences

• Upload handlers receive a NativeFile instead of a DOM File.
• The in-form enum option editor (enumEditor, canManageEnumOptions, enumEditorAdminRoleIds) injects the native DocyrusEnumOptionEditor (bottom sheet) as a "Manage options" footer (ui.enumEditor.manageOptions) inside the picker sheet of every field-enum / field-systemEnum field, via fieldProps.renderOptionsEditor. Permission is read from /v1/users/me (ADMIN / ARCHITECT) unless canManageEnumOptions is passed; saving refreshes the schema so the picker shows the new options.

API Reference

Return Value

Type Exports