@socotra/ec-react-utils 2.19.3-next.6 → 2.19.3-next.7

package/README.md

@@ -1,48 +1,133 @@
-# @socotra/ec-react-utils
+---
+title: Utils
+description: Utils for the @socotra/ec-react-utils package.
+---
 
-A set of utility functions for integrating ec-react-components with API responses.
+# EC React Utils
+### Utils for the Socotra Insurance Suite
 
-- **Package name**: `@socotra/ec-react-utils`
-- **Repo Path**: `packages/utils`
-- **Install**:
-  ```sh
-  npm i @socotra/ec-react-utils
-  ```
-- **Usage**:
+This package provides a collection of shared helper functions used throughout the Socotra EC ecosystem. These utilities handle common tasks such as data extraction, transformation, default value generation, and building API requests, serving as a foundational layer for the component and application logic.
 
-  ```js
-  import { myUtilityFunction } from '@socotra/ec-react-utils';
-  ```
+The library is organized by function, including:
 
-### Running the Project
+-   **Data Extraction:** Functions for safely extracting nested data from large, complex objects.
+-   **Default Value Getters:** Functions for generating default values for forms.
+-   **API Request Builders:** Functions for mapping form data to API request payloads.
+-   **Miscellaneous Helpers:** A variety of other useful functions for data manipulation and comparison.
 
-To build the package:
+---
+
+## Installation
 
 ```sh
-pnpm run build
+npm i @socotra/ec-react-utils
 ```
 
-To run tests:
+This package has peer dependencies on `@socotra/ec-react-schemas` and `zod`, which you likely have installed already.
 
-```sh
-pnpm run test
-```
+---
 
-To run the linter:
+## Usage
 
-```sh
-pnpm run lint
+Import any utility directly from the package:
+
+```ts
+import { extractElementByType } from '@socotra/ec-react-utils';
+
+const element = extractElementByType(quote, 'my_element_type');
 ```
 
-To run the sandbox
+### 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
-cd ../sandbox
-pnpm run dev
+git clone https://github.com/socotra/ec-react.git
+cd ec-react/packages/docs/src/utils
 ```
 
-Installing directly for local development
+Edit files under the `utils` 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.
+
+## Available Utilities
+
+<!-- UTILS-START -->
+
+### Data Extraction
+
+| Function | Description | Returns |
+|----------|-------------|---------|
+| `extractElementByLocator` | Extracts the first element from a policy, quote, or transaction segment that matches the specified locator. | `Element` or `undefined` |
+| `extractElementByType` | Extracts the first element from a policy, quote, or transaction segment that matches the specified type. | `Element` or `undefined` |
+| `extractElementsByType` | Extracts all elements from a policy, quote, or transaction segment that match the specified type. | `Element[]` |
+| `extractElementDataModelFromQuote` | Extracts the data model for a specific element type from a quote response. | `object` or `undefined` |
+| `extractElementDataModelFromSegment` | Extracts the data model for a specific element type from a transaction segment. | `object` or `undefined` |
+| `extractElementDataModelFromType` | Extracts the data model for a specific element type from a policy response. | `object` or `undefined` |
+| `extractElementsFromQuote` | Extracts all elements from a quote's exposures. | `Element[]` |
+| `extractElementsFromTransactionSegment` | Extracts all elements from a transaction segment's exposures. | `Element[]` |
+| `extractProductDataModel` | Extracts the data model for a specific product from a policy or quote. | `object` or `undefined` |
+| `extractProductElements` | Extracts all elements associated with a product from a policy or quote. | `Element[]` |
+
+### Default Value Getters
+
+| Function | Description | Returns |
+|----------|-------------|---------|
+| `getCoverageTermsDefaultValues` | Generates default values for coverage terms based on the product configuration. | `object` |
+| `getDefaultAccountFormValues` | Generates default values for the account form. | `object` |
+| `getDefaultDraftTransactionValues` | Generates default values for a new draft transaction form. | `object` |
+| `getDefaultElementValues` | Generates default values for an element based on its data model. | `object` |
+| `getDefaultInitializedTransactionValues` | Generates default values for an initialized transaction form. | `object` |
+| `getDefaultPolicyValues` | Generates default values for a new policy. | `object` |
+| `getDefaultQuoteValues` | Generates default values for a new quote. | `object` |
+
+### API Request Builders
+
+| Function | Description | Returns |
+|----------|-------------|---------|
+| `getAccountRequest` | Transforms form data into a request payload for creating or updating an account. | `AccountCreateRequest` or `AccountUpdateRequest` |
+| `getElementRequest` | Transforms form data into a request payload for creating or updating an element. | `ElementCreateRequest` or `ElementUpdateRequest` |
+| `getEvaluatedConstraintsRequest` | Creates a request payload to evaluate constraints for a specific element. | `EvaluateConstraintsRequest` |
+| `getModifyChangeInstructionCreateRequestFromFormData` | Transforms form data into a request to modify a transaction's change instructions. | `ModifyChangeInstructionCreateRequest` |
+| `getParamsChangeInstructionCreateRequestFromFormData` | Transforms form data into a request to update the parameters of a transaction. | `ParamsChangeInstructionCreateRequest` |
+| `getElementTransactionUpdateRequestFromFormData` | Transforms form data into a request to update an element within a transaction. | `ElementTransactionUpdateRequest` |
+| `getPolicyRequest` | Transforms form data into a request payload for creating a new policy. | `PolicyCreateRequest` |
+| `getQuoteRequest` | Transforms form data into a request payload for creating or updating a quote. | `QuoteRequest` |
+
+### Miscellaneous
+
+| Function | Description | Returns |
+|----------|-------------|---------|
+| `compareData` | Compares two data objects and returns a list of differences. | `Diff[]` |
+| `dataModelToJSONSchema` | Converts a Socotra data model into a JSON schema for form generation. | `JSONSchema7` |
+| `getElementNameByType` | Retrieves the display name of an element based on its type from the product configuration. | `string` |
+| `getRemoveDataFieldValues` | Identifies fields that should be removed from a data object based on a comparison. | `object` |
+| `getUpdatedDataFromConstraints` | Applies the results of a constraint evaluation to a data object. | `object` |
+| `parseToPrimitive` | Safely parses a string into a boolean, number, or returns the original string. | `string | number | boolean` |
+| `splitInputAndQuantifier` | Splits a string into its core name and a quantifier suffix (e.g., `?`, `*`). | `{ name: string; quantifier: string }` |
+| `translateError` | Translates a validation error object into a human-readable string. | `string` |
+
+<!-- UTILS-END -->
+
+### 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/utils
 ```
+
+Edit files under the `utils` directory.
+
+Run `pnpm run sync` to update the documentation in the `README.md` files of this package.
+
+Run `pnpm run build` to build the documentation for the `Socotra Documentation` repo.
+
+Follow instructions in the `ec-react/packages/docs/README.md` file to build the documentation and update the `Socotra Documentation` repo.