Forms Package

@prox-os/forms is the shared input and editing package for Prox OS apps. It defines a form contract, field schema, validation issue model, submit result shape, React primitives, Zod adapters, React Hook Form integration, and Storybook examples for common OS app forms.

It is not a low-code form builder and it does not submit to a real backend. Apps own domain schemas and submit behavior.

Package Scope

The package provides:

form schema and field schema types;
validation issue and submit result types;
Zod-first validation helpers;
React Hook Form based primitives;
schema-driven rendering for simple forms;
form action buttons that can consume @prox-os/actions;
demo schemas for Dreams, media metadata, saved places, app settings, and destructive confirmation.

Core Types

OsFormSchema
OsFormFieldSchema
OsFieldKind
OsFieldOption
OsValidationIssue
OsFormSubmitResult
OsFormSubmitHandler
OsFormMode
OsFormLayout

Core Components

OsForm
OsFormSection
OsFormField
OsTextField
OsTextareaField
OsSelectField
OsCheckboxField
OsSwitchField
OsRadioGroupField
OsNumberField
OsDateField
OsFormActions
OsFormMessage
OsFormErrorSummary
OsSchemaForm

Validation

@prox-os/forms uses React Hook Form for local form state and Zod for TypeScript-first validation examples. The public contract is still Prox-owned: apps can use OsFormSchema without Zod, or use Zod through createZodFormResolver.

Helpers include:

createZodFormResolver
normalizeZodIssues
createDefaultValues
createFieldSchema
createFormSchema
createFieldRendererRegistry

Future backend validation errors should map into OsValidationIssue.

Storybook

Open UI Workshop and browse:

Forms / OsForm
Forms / OsSchemaForm
Forms / Fields
Forms / States
Forms / Integration

These stories cover basic forms, two-column layout, schema-driven forms, field types, validation summaries, loading/disabled states, form actions, filter forms, AI config forms, and destructive confirmation.

Package Relationships

Package	Relationship
`@prox-os/actions`	`OsFormActions` can render submit-adjacent actions such as reset, save draft, delete, or AI suggestions.
`@prox-os/data-table`	Future record editor, filter form, and column settings forms can use these primitives.
`@prox-os/media`	Future media metadata and alt text editors can use `OsFormSchema`.
`@prox-os/maps`	Saved place, layer config, and geocoding filter forms can use forms primitives.
`@prox-os/command`	Future commands with arguments can open quick-create or configuration forms.
Future AI UI	Agent settings, prompt config, and human approval forms should reuse this contract.
Future backend packages	`api-contract`, `permissions`, `audit`, and `db` can feed contract-driven, permission-aware forms later.

Current Boundaries

Primitive package only.
No real backend submission.
No full conditional logic engine.
No low-code form designer.
No OS Shell private imports.
No real permissions or audit integration yet.

See docs/platform/architecture/capabilities/forms.md for the architecture roadmap.