# EC React Components



`@socotra/ec-react-components` is a powerful, schema-driven framework
for building enterprise-grade insurance applications. This library
provides a comprehensive suite of dynamic forms and UI components
designed to accelerate development and handle the full spectrum of
policy lifecycle operations with unparalleled flexibility.

Core Philosophy [#core-philosophy]

At its core, this library is engineered to translate Socotra’s flexible
data model directly into a rich, interactive user interface. By
leveraging your unique data model, we dynamically generate complex
forms, eliminating the need to manually build and maintain forms for
every product or data variation. This schema-driven approach ensures
that as your insurance products evolve, your UI adapts automatically,
dramatically reducing development overhead and increasing speed to
market.

Our components are built with modern, robust technologies including
**React**, **TypeScript**, **Shadcn UI**, and **Tailwind CSS**, ensuring
a developer-friendly, performant, and highly customizable experience.

Key Features [#key-features]

* **Schema-Driven UI**: Forms for quotes, policies, accounts, and
  transactions are generated dynamically from your data model, not
  hardcoded.
* **Complex Logic Handling**: Built-in support for sophisticated
  insurance workflows, including constraint evaluation for real-time
  field dependency updates.
* **Highly Customizable**: A powerful `tag` system allows for deep
  customization of field behavior directly from the data model—from
  conditional visibility to special UI controls like multi-select and
  currency inputs.
* **Enterprise-Ready**: Designed to handle the intricate details of
  policy administration, including endorsements, payments,
  disbursements, and renewals.
* **Modern Tech Stack**: A clean, modern, and performant codebase that
  is a pleasure to work with and extend.

***

Installation [#installation]

```sh
npm i @socotra/ec-react-components
```

***

Component Documentation [#component-documentation]

Dive into the detailed documentation for our core components to
understand their purpose, props, and advanced capabilities.

Core Forms [#core-forms]

| Component            | Description                                                                                                                                               |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **AccountForm**      | A dynamic form for creating and updating customer accounts based on configurable account types.                                                           |
| **QuoteForm**        | The cornerstone of the quoting process. A comprehensive, multi-section form for creating and updating quotes with full support for constraint evaluation. |
| **PolicyForm**       | A specialized, read-only view for displaying the complete data of an issued policy in a structured format.                                                |
| **ElementForm**      | A versatile and powerful form for rendering any sub-element of a policy or quote, such as a vehicle, driver, or location.                                 |
| **PaymentForm**      | A suite of components for handling all payment-related actions: creating new payments, applying existing credit, and reversing transactions.              |
| **DisbursementForm** | A specialized form for processing disbursements from an account, with dynamic fields based on disbursement type.                                          |
| **DataPropertyForm** | A dynamic form used for rendering and editing data properties using a provided data model and property schema.                                            |

Transaction Forms [#transaction-forms]

These forms are used for handling changes to policies post-issuance
(endorsements, renewals, etc.).

| Component                      | Description                                                                                                                                                                    |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **InitializedTransactionForm** | Handles transactions in an `initialized` state (e.g., a new business quote), with full support for constraint evaluation to manage complex field dependencies before issuance. |
| **DraftTransactionForm**       | A specialized form for midterm policy changes. It generates the necessary `param` and `modify` change instructions to accurately update a `draft` transaction.                 |

***

Custom Rendering (Tags for Fields) [#custom-rendering-tags-for-fields]

To unlock the full potential of this library, it’s essential to
understand the `tag` system. Our custom rendering guide provides a
detailed walkthrough of how to control form behavior directly from your
data model.

This guide covers:

* Conditional Field Hiding (`hidden|...`, `rootHidden|...`,
  `hidden`)
* Advanced UI Controls (`multiselect`, `horizontal-layout`)
* Data Formatting (`currency`)
* Field Disable (`readOnly`)

Theming [#theming]

To style the components, follow the instructions in the theming guide.

This guide covers:

* Theming with Tailwind CSS and `shadcn/ui`
* CSS Imports from the package
* Per-Component Style Overrides

Documentation [#documentation]

The documentation for this package is generated from a script that must
be run after the package is built.

To contribute to the documentation, clone the repo and run the following
command:

```sh
git clone https://github.com/socotra/ec-react.git
cd ec-react/packages/docs/src/components
```

Edit files under the `components` directory.

Run `pnpm run sync` to update the documentation in the `README.md`
files of the other packages.

Follow instructions in the `ec-react/packages/docs/README.md` file to
build the documentation and update the `Socotra Documentation` repo.