Form on Palmyra

PalmyraForm

Mon, 01 Jan 0001 00:00:00 +0000

PalmyraForm#

@palmyralabs/rt-forms · src/palmyra/form/PalmyraForm.tsx

Overview#

The root controlled form. Creates a FormManager via useFormManager(props), publishes it through FormManagerContext, forwards a StoreFactory through StoreFactoryContext, and wraps its children in a default FieldGroup name="_default". Field widgets inside the subtree self-register by consuming FieldGroupManagerContext — you never enumerate fields at the prop level.

Use PalmyraForm directly when you need full control of the submit / hydrate flow; for the common patterns, reach for PalmyraNewForm, PalmyraEditForm, or PalmyraViewForm.

PalmyraNewForm

Mon, 01 Jan 0001 00:00:00 +0000

PalmyraNewForm#

@palmyralabs/rt-forms · src/palmyra/form/PalmyraNewForm.tsx

Overview#

Create-flow wrapper around PalmyraForm. Binds a Wire store against endPoint, exposes saveData on the ref so the caller (or a dialog template) can trigger the POST, and forwards success/failure through onSaveSuccess / onSaveFailure.

Props — `IPalmyraNewFormInput`#

interface IPalmyraNewFormInput extends IuseFormOptions<StoreOptions>,
                                       IFormQueryEventHandler,
                                       IFormSaveEventHandler {
  initialData?:          any;
  refreshOnSaveResponse?: boolean;
  children?:             any;
  onValidChange?:        (isValid: boolean) => void;
}

interface IuseFormOptions<T> {
  endPoint:         IEndPoint;
  endPointOptions?: Record<string, string | number>;
  axiosCustomizer?: (axios: AxiosInstance) => void;
  storeFactory?:    StoreFactory<any, T>;
  storeOptions?:    T;
  formRef?:         React.Ref<ISaveForm>;
}

interface IFormSaveEventHandler {
  preSave?:       (data: any) => any | Promise<any>;
  onSaveSuccess?: (response: any) => void;
  onSaveFailure?: (error: any) => void;
}

Ref — `ISaveForm`#

interface ISaveForm extends IForm {
  saveData(data?: any): Promise<any>;
  refresh(): void;
}

Example#

import { useRef } from 'react';
import { PalmyraNewForm, FieldGroupContainer, type ISaveForm } from '@palmyralabs/rt-forms';
import { TextField, TextArea } from '@palmyralabs/rt-forms-mantine';
import { Button } from '@mantine/core';

export function NewManufacturerForm({ onRefresh }: { onRefresh: () => void }) {
  const formRef = useRef<ISaveForm>(null);

  return (
    <>
      <PalmyraNewForm
        formRef={formRef}
        endPoint="/mstManufacturer"
        onSaveSuccess={() => { onRefresh(); formRef.current?.refresh(); }}
        onSaveFailure={(err) => console.error(err)}
      >
        <FieldGroupContainer columns={2}>
          <TextField attribute="name"          label="Name" required />
          <TextField attribute="contactMobile" label="Mobile" />
          <TextField attribute="contactEmail"  label="Email"  validRule="email" />
          <TextArea  attribute="address"       label="Address" colspan={2} />
        </FieldGroupContainer>
      </PalmyraNewForm>
      <Button onClick={() => formRef.current?.saveData()}>Save</Button>
    </>
  );
}

PalmyraEditForm

Mon, 01 Jan 0001 00:00:00 +0000

PalmyraEditForm#

@palmyralabs/rt-forms · src/palmyra/form/PalmyraEditForm.tsx

Overview#

Load-then-edit flow. On mount (and whenever id changes), fetches the record via the bound Wire store, hydrates the form, and exposes saveData that dispatches either a PUT or an action: save upsert based on mode.

Props — `IPalmyraEditFormInput`#

interface IPalmyraEditFormInput extends IPalmyraViewFormInput,
                                        IFormSaveEventHandler {
  mode?:                 'edit' | 'save';     // default 'edit' → PUT; 'save' → upsert
  refreshOnSaveResponse?: boolean;
  onValidChange?:         (isValid: boolean) => void;
  children?:              any;
}

interface IPalmyraViewFormInput extends IuseFormOptions<StoreOptions>,
                                        IFormQueryEventHandler {
  id:              string;
  idKey?:          string;             // defaults to the store's id property
  fields?:         string[];           // projection — fetch only these
  onQueryData?:    (data: any) => void;
  onQueryFailure?: (error: any) => void;
}

Ref — `ISaveForm`#

interface ISaveForm extends IForm {
  saveData(data?: any): Promise<any>;   // PUT or POST?action=save depending on mode
  refresh(): void;                      // re-fetch the record
}

Example#

import { useRef } from 'react';
import { PalmyraEditForm, FieldGroupContainer, type ISaveForm } from '@palmyralabs/rt-forms';
import { TextField, TextArea } from '@palmyralabs/rt-forms-mantine';
import { Button, Group } from '@mantine/core';

export function EditManufacturerForm({ id, onRefresh }: { id: string; onRefresh: () => void }) {
  const formRef = useRef<ISaveForm>(null);

  return (
    <>
      <PalmyraEditForm
        formRef={formRef}
        endPoint="/mstManufacturer/{id}"
        id={id}
        mode="edit"
        onSaveSuccess={onRefresh}
      >
        <FieldGroupContainer columns={2}>
          <TextField attribute="name"          label="Name" required />
          <TextField attribute="contactMobile" label="Mobile" />
          <TextField attribute="contactEmail"  label="Email" validRule="email" />
          <TextArea  attribute="address"       label="Address" colspan={2} />
        </FieldGroupContainer>
      </PalmyraEditForm>
      <Group>
        <Button variant="default" onClick={() => formRef.current?.refresh()}>Reload</Button>
        <Button onClick={() => formRef.current?.saveData()}>Save</Button>
      </Group>
    </>
  );
}

Use mode="save" when the server decides insert-vs-update by payload (e.g. a merge-semantics endpoint). For strict update-only semantics that 404s on a missing row, keep the default mode="edit".

PalmyraViewForm

Mon, 01 Jan 0001 00:00:00 +0000

PalmyraViewForm#

@palmyralabs/rt-forms · src/palmyra/form/PalmyraViewForm.tsx

Overview#

Read-only variant of PalmyraEditForm. Fetches a record by id on mount, exposes getData and refresh, but has no saveData and no onValidChange — the form is never considered dirty because it never submits.

Use for detail views, confirmation panes, and drill-downs. Pair it with rt-forms-mantine field widgets in their disabled / display-only mode.

Props — `IPalmyraViewFormInput`#

interface IPalmyraViewFormInput extends IuseFormOptions<StoreOptions>,
                                        IFormQueryEventHandler {
  id:              string;
  idKey?:          string;             // defaults to the store's id property
  fields?:         string[];           // projection — fetch only these
  onQueryData?:    (data: any) => void;
  onQueryFailure?: (error: any) => void;
  children?:       any;
}

Ref — `IViewForm`#

interface IViewForm extends IForm {
  refresh(): void;       // re-fetch the record
}

getData() and setData() are inherited from IForm; isValid() always returns true.

FieldGroup

Mon, 01 Jan 0001 00:00:00 +0000

FieldGroup#

@palmyralabs/rt-forms · src/palmyra/form/FieldGroup.tsx

Overview#

Registers a named group of fields with the enclosing PalmyraForm. Consumes FormManagerContext, asks the form manager for an IFieldGroupManager, and re-publishes it through FieldGroupManagerContext so that every descendant field widget can self-register.

PalmyraForm automatically wraps its children in a default FieldGroup name="_default", so you only need an explicit FieldGroup when you want multiple named groups in the same form (e.g. basic info / billing / shipping submitted together, or validation scoped per group).

Form on Palmyra

PalmyraForm

PalmyraForm#

Overview#

PalmyraNewForm

PalmyraNewForm#

Overview#

Props — IPalmyraNewFormInput#

Ref — ISaveForm#

Example#

PalmyraEditForm

PalmyraEditForm#

Overview#

Props — IPalmyraEditFormInput#

Ref — ISaveForm#

Example#

PalmyraViewForm

PalmyraViewForm#

Overview#

Props — IPalmyraViewFormInput#

Ref — IViewForm#

FieldGroup

FieldGroup#

Overview#

Props — `IPalmyraNewFormInput`#

Ref — `ISaveForm`#

Props — `IPalmyraEditFormInput`#

Ref — `ISaveForm`#

Props — `IPalmyraViewFormInput`#

Ref — `IViewForm`#