# @lssm-tech/example.form-showcase

Focused ContractSpec form example and template covering field kinds, conditional rules, and layout flows.

## What This Demonstrates

- Schema-backed `defineFormSpec` authoring with `fromZod`.
- Every current form field kind: text, email, textarea, select, checkbox, radio, switch, autocomplete, address, phone, date, time, datetime, group, and array.
- Layout variants including responsive columns, full-width spans, section flows, step flows, nested groups, horizontal/responsive orientation, and repeated group arrays.
- Form metadata for input groups, password fields, read-only/computed hints, conditional visibility/enabled/required rules, custom constraints, PII hints, and submit actions.
- A `FormRegistry` that downstream apps can import and filter, including entity projection form metadata.
- A `FormShowcasePreview` UI that demonstrates the specs with real form controls across field kinds, sections, arrays, groups, and step layouts.

## Running Locally

From `packages/examples/form-showcase`:

- `bun run build`
- `bun run typecheck`
- `bun run test`
- `bun run smoke`
- `bun run preflight`

## Usage

Import the registry or individual form specs:

```ts
import {
	FormShowcaseRegistry,
	FormShowcaseAllFieldsForm,
	FormShowcaseProgressiveStepsForm,
} from "@lssm-tech/example.form-showcase/forms";
```

Use this package as a form-only template when you want a compact reference for ContractSpec form authoring without a larger business app around it. Import `@lssm-tech/example.form-showcase/proof-config` when tooling needs the stable docs, sandbox, templates, forms, and UI entrypoint map without reaching into private preview helpers.

## Proof map and boundaries

The public proof map is intentionally stable and package-local:

- Docs routes: `/docs/examples/form-showcase`, `/docs/examples/form-showcase/usage`, and `/docs/examples/form-showcase/proof-config`.
- Sandbox route: `/sandbox?template=form-showcase`.
- Template route: `/templates?tag=forms`.
- Public entrypoints: the package barrel, `./example`, `./forms`, `./docs`, `./proof-config`, and `./ui`.

Private proof helpers under `src/ui/proof/*` and preview data/model files stay implementation details. Tooling should read `@lssm-tech/example.form-showcase/proof-config` instead of deep-importing those helpers.

When a form-configuration panel is needed, reuse the design-system `FormConfigShell`, `FormConfigMenuBar`, and `FormConfigPanel` exports from `@lssm-tech/lib.design-system/forms`. The showcase proof should not fork a local configuration shell.

No persistence, backend, auth, provider, credential custody, or production form-storage guarantee is implied by this example. Capture/readiness proof state is deterministic fixture state only.

## Public Entry Points

- `@lssm-tech/example.form-showcase`
- `@lssm-tech/example.form-showcase/example`
- `@lssm-tech/example.form-showcase/forms`
- `@lssm-tech/example.form-showcase/forms/all-fields.form`
- `@lssm-tech/example.form-showcase/forms/entity-projections.form`
- `@lssm-tech/example.form-showcase/forms/form-showcase.docs`
- `@lssm-tech/example.form-showcase/forms/progressive-steps.form`
- `@lssm-tech/example.form-showcase/proof-config`
- `@lssm-tech/example.form-showcase/docs`
- `@lssm-tech/example.form-showcase/ui`
- `@lssm-tech/example.form-showcase/ui/FormShowcasePreview`

Private proof/state helpers under `src/ui/proof/*`, any screen-model internals under `src/ui/screens/*`, and non-existent deep proof shortcuts such as `@lssm-tech/example.form-showcase/proof` are intentionally not package exports. Use `@lssm-tech/example.form-showcase/proof-config` for the stable proof map instead of deep imports.

## Notes

- This package intentionally does not ship a production custom renderer. Its preview uses real controls and the same sample data to demonstrate the contract capabilities, while host apps can map `FieldSpec` objects to their own design-system components for fully interactive forms.
- The example is available in the templates catalog through `surfaces.templates: true`.
- The proof/config preview is deterministic and in-memory only: it does not require persistence, backend routes, authentication, credentials, or network access.