@astroapps/forms-app

@astroapps/forms-app

A framework-agnostic React library for building schema-driven forms applications. Provides a complete set of pages — dashboard with search/filter/export, item view/edit with workflow actions, export definition management, and a visual forms editor — all decoupled from specific UI libraries, API clients, and routing frameworks.

Installation

npm install @astroapps/forms-app

Peer Dependencies

@react-typed-forms/core        ^4.4.2
@react-typed-forms/schemas     ^17.1.0
@react-typed-forms/schemas-html ^17.1.0
@astroapps/basic-editor        ^1.0.0
@astroapps/client              ^2.6.0
@astroapps/searchstate         ^2.0.0
clsx                           ^2.1.1
react                          ^18.2.0 || ^19

Quick Start

1. Set Up the Provider

Wrap your app with FormsAppProvider, supplying API adapters, UI components, navigation, and form definitions.

import { FormsAppProvider, FormsAppConfig } from "@astroapps/forms-app";

const config: FormsAppConfig = {
  api: myApiAdapter,               // Implements FormsAppApi
  ui: myUIComponents,              // Implements FormsAppUIComponents
  navigationHandler: (intent) => { /* route based on intent.type */ },
  formDefinitions: myFormDefs,     // Pre-loaded form schemas
  schemaMap: mySchemas,            // Schema definitions
  rendererConfig: myRendererConfig,
};

function App() {
  return (
    <FormsAppProvider config={config}>
      {/* your routes */}
    </FormsAppProvider>
  );
}

2. Use Library Pages

Each page accepts its own API interface — wire your API client to the interface shape.

import { DashboardPage, ItemViewPage, ItemEditPage } from "@astroapps/forms-app";

// Dashboard with search, filters, and export
<DashboardPage />

// Item view with workflow actions and notes
<ItemViewPage
  itemId={id}
  api={{
    getItemView: (id) => client.getItemView(id),
    performAction: (id, action) => client.performAction(id, action),
    addItemNote: (id, note) => client.addItemNote(id, note),
    getFormForRender: (formId) => client.getFormForRender(formId),
  }}
/>

// Item edit with dynamic form rendering
<ItemEditPage
  itemId={id}
  api={{
    getItemView: (id) => client.getItemView(id),
    editItem: (id, edit) => client.editItem(id, edit),
    getFormForRender: (formId) => client.getFormForRender(formId),
  }}
/>

Architecture

The library uses three main abstraction layers to stay framework-agnostic:

• API interfaces — each page accepts its own typed API prop; consumers wire NSwag/fetch clients to these interfaces
• UI components — primitives (Button, Dialog, Textfield, etc.) injected via FormsAppUIComponents
• Navigation intents — routing is decoupled via NavigationIntent union type and a handler callback

All form state is managed with @react-typed-forms/core controls, and forms are rendered dynamically from schema definitions via @react-typed-forms/schemas.

Pages

DashboardPage

Search and browse items with filtering, sorting, and pagination. Supports row actions (view, edit, delete) and bulk CSV export of selected items.

<DashboardPage />

Uses the FormsAppApi from the provider context for search, filter options, delete, and export operations.

Related hooks:

• useDashboardSearch() — manages search state, debounced queries, and pagination
• useExportDialog() — manages export definition selection and CSV download
• SelectionCheckbox — row selection component for bulk export

ItemViewPage

Read-only item view with workflow actions, audit event history, and notes.

interface ItemViewPageProps {
  itemId: string | undefined;
  api: ItemViewApi;
  fileOperations?: FileOperations;
  viewFormType?: string;             // Default: "AdminItemViewForm"
  filterActions?: (action: string, navProps: CustomNavigationProps) => boolean;
  onAction?: DashboardActionHandlers;
}

ItemEditPage

Item editing with dynamic form rendering and workflow action buttons.

interface ItemEditPageProps {
  itemId: string | undefined;
  api: ItemEditApi;
  fileOperations?: FileOperations;
  filterActions?: (action: string, navProps: CustomNavigationProps) => boolean;
  hideSave?: boolean;
}

ExportDashboardPage

List and manage CSV export definitions, grouped by table.

interface ExportDashboardPageProps {
  api: ExportDashboardApi;
  formType?: string;    // Default: "ExportDefinitionDashboard"
  onAction?: DashboardActionHandlers;
}

ExportEditPage

Create or edit export definitions with table selection and column mapping.

interface ExportEditPageProps {
  definitionId: string | undefined;   // undefined = create, string = edit
  api: ExportEditApi;
  tableSelectionFormType?: string;
  editFormType?: string;
  createFieldSelectionRenderer?: (options: { schema: any }) => RendererRegistration;
}

FormsEditorPage

Visual form builder with drag-and-drop field placement, live preview, schema tree, properties panel, and a debug window.

interface FormsEditorPageProps {
  api: FormsEditorApi;
  editorComponents: FormsEditorComponents;
  createPreviewRenderer: (customRenderers?: RendererRegistration[]) => FormRenderer;
}

Editor components (@astroapps/basic-editor tree views, palettes, etc.) are injected via the FormsEditorComponents interface — no hard dependency on any editor package.

Components

DynamicFormRenderer

Loads a form definition from the API and renders it dynamically. Supports read-only mode, file operations, and custom renderers.

interface DynamicFormRendererProps {
  formId: string;
  itemId?: string;
  formData: Control<any>;
  readonly?: boolean;
  customRenderers?: RendererRegistration[];
  noNavigation?: boolean;
  getFormForRender: (formId: string) => Promise<FormRenderData>;
  fileOperations?: FileOperations;
}

AppFormRenderer

Renders a pre-loaded form by type from the form definitions registry (via useFormsApp() context).

<AppFormRenderer formType="MyFormType" data={control} />

Workflow Utilities

import { createWorkflowActions, createActionWizardNavigation, wrapFormControls } from "@astroapps/forms-app";

• wrapFormControls(controls, config) — wraps form controls in wizard/tabs navigation based on form config
• createActionWizardNavigation(actions, onAction, ...) — creates wizard renderer with workflow action buttons
• createWorkflowActions(actions, onAction, ui) — generates action buttons from available workflow actions

API Interfaces

Each page defines its own API interface. Consumers implement these by wiring their API clients.

FormsAppApi (provider-level)

Used by DashboardPage and shared functionality:

interface FormsAppApi {
  searchItems(options: SearchOptions): Promise<ItemSearchResults>;
  getFilterOptions(): Promise<Record<string, FieldOptionData[]>>;
  deleteItem(id: string): Promise<void>;
  exportRecords(request: ExportRecordsEdit): Promise<string>;
  getExportDefinitionOfForms(ids: string[]): Promise<ExportDefinitionGroupData[]>;
}

Per-Page APIs

Interface	Used By	Methods
ItemViewApi	ItemViewPage	getItemView, performAction, addItemNote, getFormForRender
ItemEditApi	ItemEditPage	getItemView, editItem, getFormForRender
ExportDashboardApi	ExportDashboardPage	listExportDefinitions, deleteExportDefinition
ExportEditApi	ExportEditPage	getExportDefinition, saveExportDefinition, listTables, getTable
FormsEditorApi	FormsEditorPage	listForms, createForm, getForm, editForm, deleteForm, createTable, getTable, editTable, deleteTable

Types

Data Types

All data interfaces use a Data suffix. TypeScript's structural typing means NSwag-generated types automatically satisfy these interfaces when shapes match.

Type	Description
ItemViewData	Full item detail (actions, metadata, status, events, notes)
ItemInfoData	Item search result row
ItemEventData	Audit event record
ItemNoteResultData	Note display data
ItemNoteEditData	Note submission payload
ItemEditData	Item edit payload (action + metadata)
FormRenderData	Form controls + schemas for rendering
FormConfigData	Layout config (layoutMode, navigationStyle, public, published)
FormInfoData	Form listing info
FormDefinitionEditData	Form creation/editing payload
FormUploadData	File upload result
TableDefinitionEditData	Table definition payload
ExportDefinitionEditData	Export definition payload
ExportColumnData	Column mapping for exports
ExportDefinitionGroupData	Export definitions grouped by table

Constants

import { WorkflowActions, WorkflowStatuses, AuditEventTypes, FormLayoutMode, PageNavigationStyle } from "@astroapps/forms-app";

WorkflowActions.Submit    // "Submit"
WorkflowStatuses.Draft    // "Draft"
AuditEventTypes.Note      // "Note"
FormLayoutMode.MultiPage  // 1
PageNavigationStyle.Tabs  // 2

UI Components Interface

Consumers provide UI primitives via FormsAppUIComponents:

interface FormsAppUIComponents {
  useDialog: () => DialogHook;
  useConfirmDialog: () => ConfirmDialogHook;
  Button: ComponentType<{ onClick: () => void; children: ReactNode; ... }>;
  Textfield: ComponentType<{ control: Control<string>; label?: string; ... }>;
  CircularProgress: ComponentType<{}>;
}

Navigation

type NavigationIntent =
  | { type: "viewItem"; itemId: string }
  | { type: "editItem"; itemId: string }
  | { type: "dashboard" }
  | { type: "exportDashboard" }
  | { type: "exportCreate" }
  | { type: "exportEdit"; definitionId: string }
  | { type: "custom"; data: any };

File Operations

interface FileOperations {
  downloadFile: (file: { id: string }) => Promise<void>;
  uploadFile: (file: File) => Promise<FormUploadData>;
  deleteFile: (file: { id: string }) => Promise<void>;
}

Consumer Migration Pattern

After migration, each Next.js page becomes a thin wrapper:

"use client";
import { ItemViewPage } from "@astroapps/forms-app";

export default function AdminItemView() {
  const itemClient = useApiClient(ItemClient);
  const formClient = useApiClient(FormClient);
  const itemId = useParam("id");

  return (
    <ItemViewPage
      itemId={itemId}
      api={{
        getItemView: (id) => itemClient.getItemView(id),
        performAction: (id, action) => itemClient.performAction(id, action),
        addItemNote: (id, note) => itemClient.addItemNote(id, note),
        getFormForRender: (formId) => formClient.getFormForRender(formId),
      }}
    />
  );
}