Forms Architecture

Scope

Forms are the controlled input surface for OS apps, settings, resources, and future backend contracts. This document defines the app-level form contract and package boundary for @prox-os/forms.

Position

Form package owns input contracts and UI primitives.
Apps own domain schema and submit behavior.
Backend packages own persisted validation, permissions, audit, and side effects.

@prox-os/forms lets Prox OS apps move from static UI to real user input without every app inventing private field wrappers, error summaries, or submit states.

Form Schema vs Domain Schema

OsFormSchema describes how a form should render:

• title and description;
• mode and layout;
• sections;
• fields;
• default values;
• UI metadata.

Domain schemas describe business objects. A Dream entry, media asset, saved place, or app setting can have a domain schema that is stricter than the form. The form schema should not become the source of truth for all business rules.

Contract Pieces

• OsFormMode: create, edit, view, filter, settings, or confirm.
• OsFormLayout: stack, grid, two-column, inline, compact, or wizard.
• OsFieldKind: text, textarea, number, email, URL, password, date, datetime, select, multi-select, checkbox, switch, radio, slider, color, file, JSON, hidden, or custom.
• OsValidationIssue: normalized field or form validation issue.
• OsFormSubmitResult: normalized local submit result.
• OsFormSubmitHandler: local submit handler boundary.

Zod and React Hook Form

Phase 1 uses:

• React Hook Form for local React form state;
• Zod for TypeScript-first validation examples;
• @hookform/resolvers to connect both.

These are implementation choices, not the full public contract. Apps should import OsForm* types and components. Zod helpers are supported, but apps are not required to use Zod for every form.

Schema-Driven Forms

OsSchemaForm is a simple renderer for OsFormSchema. It is useful for:

• mock app forms;
• settings forms;
• filter forms;
• metadata editors;
• quick-create forms;
• Storybook examples.

It is not a full low-code form builder. Phase 1 intentionally avoids advanced conditional logic, drag-and-drop builders, collaborative editing, or deeply custom field orchestration.

Action Boundary

Forms can consume @prox-os/actions for submit-adjacent actions:

save draft
reset
cancel
delete
ask AI to suggest values
inspect metadata

The forms package emits UI intent. It does not execute OS-level actions, permissions, audit events, or backend mutations.

Future Backend Contract Forms

Future backend packages can feed forms:

• @prox-os/api-contract can expose request schemas and validation errors;
• @prox-os/permissions can mark fields as hidden or readonly;
• @prox-os/audit can record sensitive submissions;
• @prox-os/db can define persisted domain models.

Backend validation errors should map to OsValidationIssue so forms can render field-level and summary-level feedback consistently.

Future AI-Assisted Forms

AI-assisted form work should use the same contract:

• AI can suggest field values.
• AI can draft an OsFormSchema.
• Human approval is required for sensitive changes.
• Agent settings and prompt configuration forms can share primitives.

AI should not bypass validation, permissions, or audit when those backend systems exist.

Phase Roadmap

Phase 1: Form Contract and UI Primitives

• Form and field types.
• Zod / React Hook Form adapter.
• Basic field primitives.
• Schema form renderer.
• Form actions.
• Storybook examples.
• Docs.

Phase 2: App Integration

• Dreams create/edit form.
• Media metadata form.
• Map saved place form.
• Data record editor.
• Settings forms.

Phase 3: Backend Contract Integration

• Generate or map forms from API contracts.
• Map backend validation errors to OsValidationIssue.
• Permission-aware hidden and readonly fields.
• Audit form submissions.

Phase 4: AI-Assisted Forms

• AI suggests field values.
• AI generates draft forms.
• Human approval for sensitive changes.
• Prompt and config forms for agents.

Phase 5: Advanced Form Builder

Future evaluation only:

• custom field registry;
• plugin fields;
• conditional fields;
• wizard flows;
• collaborative form editing.

Non-Goals

• No complete low-code form builder in Phase 1.
• No real backend submission.
• No full conditional logic engine.
• No heavyweight date picker or rich select dependency.
• No OS Shell private imports.
• No real permissions, audit, or API contract integration yet.