@socotra/ec-react-components 2.19.3-next.6 → 2.19.3-next.8

package/README.md

@@ -1,78 +1,95 @@
-# @socotra/ec-react-components
+---
+title: ec-react-components
+description: React components for the Socotra Insurance Suite.
+---
 
-A React component library for generating forms and other components for EC.
+# EC React Components
 
-This library is styled via [tailwindcss](https://tailwindcss.com/) and [shadcn/ui](https://ui.shadcn.com/).
+`@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.
 
-- **Package name**: `@socotra/ec-react-components`
-- **Repo Path**: `packages/components`
-- **Install**:
-  ```sh
-  npm i @socotra/ec-react-components @tailwindcss/container-queries
-  ```
-- **Usage**:
+## Core Philosophy
 
-  ```js
-  // Import style.css anywhere in your application, preferably at the root
-  import '@socotra/ec-react-components/dist/style.css';
+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.
 
-  import { MyComponent } from '@socotra/ec-react-components';
-  ```
+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.
 
-- Add the plugin to your `tailwind.config.js` file along with the content path:
+## Key Features
 
-  ```js
-  // tailwind.config.js
-  module.exports = {
-    content: [
-      // ...
-      './node_modules/@socotra/ec-react-components/dist/**/*.js',
-    ]
-    theme: {
-      // ...
-    },
-    plugins: [
-      require('@tailwindcss/container-queries'),
-      // ...
-    ],
-  };
-  ```
+-   **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.
 
-## Customization
+---
 
-As this library is styled via shadcn components and tailwind, customization can be achieved by installing shadcn in your project. Follow the installation guide from [shadcn](https://ui.shadcn.com/docs/installation) and adjust your theme using the [theme creator](https://ui.shadcn.com/themes).
+## Installation
 
-Once you install shadcn, or if you are using it already, **delete the style.css import** to avoid style collisions
+```sh
+npm i @socotra/ec-react-components
+```
 
-### Running the Project Locally
+---
 
-To build the package:
+## Component Documentation
 
-```sh
-pnpm run build
-```
+Dive into the detailed documentation for our core components to understand their purpose, props, and advanced capabilities.
 
-To run tests:
+### Core Forms
 
-```sh
-pnpm run test
-```
+| 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. |
 
-To run the linter:
+### Transaction Forms
 
-```sh
-pnpm run lint
-```
+These forms are used for handling changes to policies post-issuance (endorsements, renewals, etc.).
 
-To run the sandbox
+| 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. |
 
-```sh
-cd ../sandbox
-pnpm run dev
-```
+---
+
+## 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.
 
-Installing directly for local development
+This guide covers:
+-   Conditional Field Hiding (`hidden|...`, `rootHidden|...`, `hidden`)
+-   Advanced UI Controls (`multiselect`, `horizontal-layout`)
+-   Data Formatting (`currency`)
+
+
+## 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
+
+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
-pnpm i ../path/to/this/packages/components
+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.

package/dist/index.d.ts

@@ -15,6 +15,7 @@ import { ElementConfig } from '@socotra/ec-react-schemas';
 import { ElementRequest } from '@socotra/ec-react-schemas';
 import { ElementResponse } from '@socotra/ec-react-schemas';
 import { EvaluateConstraintsRequest } from '@socotra/ec-react-schemas';
+import { FieldConfigRecord } from '@socotra/ec-react-schemas';
 import { ForwardRefExoticComponent } from 'react';
 import { JSX as JSX_2 } from 'react/jsx-runtime';
 import { ModifyChangeInstructionCreateRequest } from '@socotra/ec-react-schemas';
@@ -25,6 +26,7 @@ import { PaymentConfigRecord } from '@socotra/ec-react-schemas';
 import { PaymentRequest as PaymentRequest_2 } from '@socotra/ec-react-schemas';
 import { PolicyResponse } from '@socotra/ec-react-schemas';
 import { ProductConfig } from '@socotra/ec-react-schemas';
+import { PropertyRef } from '@socotra/ec-react-schemas';
 import { QuoteDependencyMapResponse } from '@socotra/ec-react-schemas';
 import { QuoteRequest } from '@socotra/ec-react-schemas';
 import { QuoteResponse } from '@socotra/ec-react-schemas';
@@ -104,6 +106,14 @@ declare type BaseProps = {
     };
 };
 
+/**
+ * DataPropertyForm is a form to render data based on data property schema and data model with edit and submission capabilities.
+ */
+export declare const DataPropertyForm: {
+    ({ data, dataModel, id, titles, dataPropertySchema, handleSubmit, isSubmitting, disabled, hideSubmitButton, validateOnSubmit, submitButtonText, readonly, }: Props_11): JSX_2.Element;
+    displayName: string;
+};
+
 /**
  * `DraftTransactionForm` is a form for updating a transaction on an issued policy. It requires a transaction in a `draft` state, a `transactionSnapshot`, `paramsChangeInstruction` (created when the transaction is created), and data types / product model / coverage terms from the tenant data model.
  */
@@ -260,6 +270,61 @@ declare type Props_10 = {
     } & Partial<GetDisbursementFormDefaultFieldsProps['titles']>;
 };
 
+declare type Props_11 = {
+    /**
+     * The resolved data model retrieved from data model response
+     */
+    dataModel: DataModel;
+    /**
+     * The data schema configuration
+     */
+    dataPropertySchema: FieldConfigRecord;
+    /**
+     * The initial data to display in the form
+     */
+    data: Record<string, PropertyRef>;
+    /**
+     * The function to call when the form is submitted. It will create an PaymentRequest from the form data.
+     */
+    handleSubmit?: (data: Record<string, PropertyRef>) => void;
+    /**
+     * Set to true when the form is submitting to set fields to readonly and disable the submit button
+     */
+    isSubmitting?: boolean;
+    /**
+     * Disables the form
+     */
+    disabled?: boolean;
+    /**
+     * Hides the submit button
+     */
+    hideSubmitButton?: boolean;
+    /**
+     * Whether to validate the form on submit
+     */
+    validateOnSubmit?: boolean;
+    /**
+     * The text to display on the submit button
+     */
+    submitButtonText?: string;
+    /**
+     * Readonly mode for the form
+     */
+    readonly?: boolean;
+    /**
+     * ID for the form wrapper
+     */
+    id?: string;
+    /**
+     * Titles for the form and boolean labels
+     */
+    titles?: {
+        formTitle?: string;
+        truthyLabel?: string;
+        falsyLabel?: string;
+    };
+};
+
 declare type Props_2 = {
     /**
      * The quote object