@emeraldemperaur/vector-sigma 1.4.48 → 1.4.49

package/README.md

@@ -15,18 +15,22 @@ Vector Sigma (VΣ) is a dynamic form orchestrator package for rapidly creating a
 #### Key Features
 <ol>
 <li>
-<strong>Real-Time Form Adaptation:</strong> Adapt the form layout by adding/removing fields, sections or entire steps based on conditional logic.</li>
+<strong>Real-Time Form Adaptation:</strong> Adapt the xForm layout by adding/removing fields, sections or entire steps based on conditional logic.</li>
 <li>
 <strong>Validation Logic Management:</strong> Centralize business rules such as complex field validation, visibility constraints, and facilitate input value pre-population from external APIs.
 </li>
 <li>
-<strong>Form State Coordination:</strong> Monitor the "state" of the form across multi-step processes, allowing users to save progress and resume later.
+<strong>Form State Coordination:</strong> Monitor the "state" of the xForm across multi-step processes, allowing users to save progress and resume later.
 </li>
 <li>
-<strong>Application UI Integration:</strong> Connects the form data to backend workflows, CRM systems, or databases immediately upon submission.</li>
+<strong>Application UI Integration:</strong> Connects the xForm data to backend workflows, CRM systems, or databases immediately upon submission.</li>
 </ol>
 
 ### Documentation
+<ul>
+<li><a href="#">VΣ Documentation</a></li>
+<li><a href="#">χForm Components Storybook</a></li>
+<ul>
 
 ### Installation
 ```bash
@@ -455,6 +459,10 @@ const App = () => {
 ![Testing Library](https://img.shields.io/badge/-Testing%20Library-%23E33332?style=for-the-badge&logo=testing-library&logoColor=white)
 ![Jest](https://img.shields.io/badge/-jest-%23C21325?style=for-the-badge&logo=jest&logoColor=white)
 ![GitHub Actions](https://img.shields.io/badge/github%20actions-%232671E5.svg?style=for-the-badge&logo=githubactions&logoColor=white)
+[![Storybook](https://raw.githubusercontent.com/storybookjs/brand/master/badge/badge-storybook.svg)](https://storybook.js.org)
+![Lerna](https://img.shields.io/badge/-Lerna-9437FF?style=flat-square&logo=lerna&logoColor=white)
+![Chromatic](https://img.shields.io/badge/-Chromatic-FC521F?style=flat-square&logo=chromatic&logoColor=white)
+![Netlify](https://img.shields.io/badge/-Netlify-00C7B7?style=flat-square&logo=netlify&logoColor=white)
 
 
 ### Changeset Versioning Synopsis

package/lib/index.cjs

@@ -57285,17 +57285,29 @@ const Teletraan1 = ({ xFormModel, readOnlyMode = false, displayMode = 'codice',
 };
 
 const FormikStateObserver = ({ instance }) => {
-    const { values, errors, dirty } = formik.useFormikContext();
+    const formikContext = formik.useFormikContext();
     React.useEffect(() => {
-        instance.values = values;
-        instance.errors = errors;
+        instance.values = formikContext.values;
+        instance.errors = formikContext.errors;
+        if (!instance.actions) {
+            instance.actions = {
+                submitForm: formikContext.submitForm,
+                resetForm: formikContext.resetForm,
+                setValues: formikContext.setValues,
+                setFieldValue: formikContext.setFieldValue,
+                setFieldError: formikContext.setFieldError,
+                setFieldTouched: formikContext.setFieldTouched,
+                validateForm: formikContext.validateForm,
+                setSubmitting: formikContext.setSubmitting,
+            };
+        }
         // Status code 0 (Empty) to 
         // Status code 1 (In Progress) :: user typing detected
-        if (dirty && instance.statusCode === 0) {
+        if (formikContext.dirty && instance.statusCode === 0) {
             instance.statusCode = 1;
             instance.timeInProgress = Date.now();
         }
-    }, [values, errors, dirty, instance]);
+    }, [formikContext, instance]);
     return null;
 };
 class VectorSigma {
@@ -57308,6 +57320,7 @@ class VectorSigma {
         this.isValid = false;
         this.values = {};
         this.errors = {};
+        this.actions = null;
         this.statusCode = 0; // 0 = Created/Empty | 1 = In Progress | 2 = Submitted
         this.timeInProgress = null;
         this.timeSubmitted = null;
@@ -57432,7 +57445,7 @@ class VectorSigma {
         };
     }
     /**
-     * Traverses xForm schema object and injects Formik values into their respective input queryResponse attributes by `inputAlias`.
+     * Traverses xForm schema object and injects Formik values into respective input queryResponse attributes by `inputAlias`.
      */
     hydrateQueryResponses(submittedValues) {
         const traverseAndHydrate = (queries) => {
@@ -57569,17 +57582,17 @@ class VectorSigma {
      * * Transforms the initialized xForm JSON/JS object, normalizing attribute fields and returning a `<Teletraan1/>` component.
      * @param options VectorSigmaRenderProps -- `VectorSigma` and `Teletraan1` props for VΣ render matrix.
      * @example .transform({
-          displayMode: 'codex',
-          readOnlyMode: false,
-          brandColor: '#800020',
-          onSubmit: async (values, actions, instance) => { // <-- onSubmit callback function passed into VectorSigma props
+         displayMode: 'codex',
+         readOnlyMode: false,
+         brandColor: '#800020',
+         onSubmit: async (values, actions, instance) => { // <-- onSubmit callback function passed into VectorSigma props
             // Use Case: Send extant xForm object to API
             await axios.post('/api/submit', instance.getxForm());
             // Use Case: Submit and clear form after success
             actions.submitForm();
             actions.resetForm();
             },
-          onFinish: () => handleFormFinish() // <-- onFinish callback function passed into Teletraan1 (Codex only) props
+         onFinish: () => handleFormFinish() // <-- onFinish callback function passed into Teletraan1 (Codex only) props
       })})
      */
     transform(options) {
@@ -57618,7 +57631,7 @@ class VectorSigma {
                     } },
                     React.createElement("img", { src: sanitizedData.logo, alt: `${sanitizedData.name || 'Form'} Logo`, style: { maxHeight: '64px', maxWidth: '100%', objectFit: 'contain' } }))),
                 React.createElement(Teletraan1, Object.assign({ brandColor: sanitizedData.brandColor, xFormModel: sanitizedData }, options)),
-                !isCodexMode && !(options === null || options === void 0 ? void 0 : options.readOnlyMode) && (React.createElement(p$5, { mt: "6", justify: "end", style: { width: '100%', paddingTop: '20px', borderTop: '1px solid var(--gray-5)' } },
+                !isCodexMode && !(options === null || options === void 0 ? void 0 : options.readOnlyMode) && !(options === null || options === void 0 ? void 0 : options.buttonOverride) && (React.createElement(p$5, { mt: "6", justify: "end", style: { width: '100%', paddingTop: '20px', borderTop: '1px solid var(--gray-5)' } },
                     React.createElement(o$a, { type: "submit", disabled: isSubmitting, style: Object.assign({ cursor: isSubmitting ? 'wait' : 'pointer', padding: '0 24px' }, (sanitizedData.brandColor ?
                             { backgroundColor: sanitizedData.brandColor, color: '#fff' }
                             :
@@ -57630,17 +57643,17 @@ class VectorSigma {
      * * `render()` is the final method in the Vector Sigma builder pattern chain.
      * @param options VectorSigmaRenderProps -- `VectorSigma` and `Teletraan1` props for VΣ render matrix.
      * @example .render({
-          displayMode: 'dual',
-          brandColor: '#800020',
-          readOnlyMode: false,
-          onSubmit: async (values, actions, instance) => { // <-- onSubmit callback function passed into VectorSigma props
+         displayMode: 'dual',
+         brandColor: '#800020',
+         readOnlyMode: false,
+         onSubmit: async (values, actions, instance) => { // <-- onSubmit callback function passed into VectorSigma props
             // Use Case: Send hydrated xForm object to API
             await axios.post('/api/submit', instance.getxForm());
             // Use Case: Submit and clear form after success
             actions.submitForm();
             actions.resetForm();
             },
-          onFinish: () => handleFormFinish() // <-- onFinish callback function passed into Teletraan1 (Codex) props
+         onFinish: () => handleFormFinish() // <-- onFinish callback function passed into Teletraan1 (Codex) props
       })})
      */
     render(options) {

package/lib/index.esm.js

@@ -57264,17 +57264,29 @@ const Teletraan1 = ({ xFormModel, readOnlyMode = false, displayMode = 'codice',
 };
 
 const FormikStateObserver = ({ instance }) => {
-    const { values, errors, dirty } = useFormikContext();
+    const formikContext = useFormikContext();
     useEffect(() => {
-        instance.values = values;
-        instance.errors = errors;
+        instance.values = formikContext.values;
+        instance.errors = formikContext.errors;
+        if (!instance.actions) {
+            instance.actions = {
+                submitForm: formikContext.submitForm,
+                resetForm: formikContext.resetForm,
+                setValues: formikContext.setValues,
+                setFieldValue: formikContext.setFieldValue,
+                setFieldError: formikContext.setFieldError,
+                setFieldTouched: formikContext.setFieldTouched,
+                validateForm: formikContext.validateForm,
+                setSubmitting: formikContext.setSubmitting,
+            };
+        }
         // Status code 0 (Empty) to 
         // Status code 1 (In Progress) :: user typing detected
-        if (dirty && instance.statusCode === 0) {
+        if (formikContext.dirty && instance.statusCode === 0) {
             instance.statusCode = 1;
             instance.timeInProgress = Date.now();
         }
-    }, [values, errors, dirty, instance]);
+    }, [formikContext, instance]);
     return null;
 };
 class VectorSigma {
@@ -57287,6 +57299,7 @@ class VectorSigma {
         this.isValid = false;
         this.values = {};
         this.errors = {};
+        this.actions = null;
         this.statusCode = 0; // 0 = Created/Empty | 1 = In Progress | 2 = Submitted
         this.timeInProgress = null;
         this.timeSubmitted = null;
@@ -57411,7 +57424,7 @@ class VectorSigma {
         };
     }
     /**
-     * Traverses xForm schema object and injects Formik values into their respective input queryResponse attributes by `inputAlias`.
+     * Traverses xForm schema object and injects Formik values into respective input queryResponse attributes by `inputAlias`.
      */
     hydrateQueryResponses(submittedValues) {
         const traverseAndHydrate = (queries) => {
@@ -57548,17 +57561,17 @@ class VectorSigma {
      * * Transforms the initialized xForm JSON/JS object, normalizing attribute fields and returning a `<Teletraan1/>` component.
      * @param options VectorSigmaRenderProps -- `VectorSigma` and `Teletraan1` props for VΣ render matrix.
      * @example .transform({
-          displayMode: 'codex',
-          readOnlyMode: false,
-          brandColor: '#800020',
-          onSubmit: async (values, actions, instance) => { // <-- onSubmit callback function passed into VectorSigma props
+         displayMode: 'codex',
+         readOnlyMode: false,
+         brandColor: '#800020',
+         onSubmit: async (values, actions, instance) => { // <-- onSubmit callback function passed into VectorSigma props
             // Use Case: Send extant xForm object to API
             await axios.post('/api/submit', instance.getxForm());
             // Use Case: Submit and clear form after success
             actions.submitForm();
             actions.resetForm();
             },
-          onFinish: () => handleFormFinish() // <-- onFinish callback function passed into Teletraan1 (Codex only) props
+         onFinish: () => handleFormFinish() // <-- onFinish callback function passed into Teletraan1 (Codex only) props
       })})
      */
     transform(options) {
@@ -57597,7 +57610,7 @@ class VectorSigma {
                     } },
                     React__default.createElement("img", { src: sanitizedData.logo, alt: `${sanitizedData.name || 'Form'} Logo`, style: { maxHeight: '64px', maxWidth: '100%', objectFit: 'contain' } }))),
                 React__default.createElement(Teletraan1, Object.assign({ brandColor: sanitizedData.brandColor, xFormModel: sanitizedData }, options)),
-                !isCodexMode && !(options === null || options === void 0 ? void 0 : options.readOnlyMode) && (React__default.createElement(p$5, { mt: "6", justify: "end", style: { width: '100%', paddingTop: '20px', borderTop: '1px solid var(--gray-5)' } },
+                !isCodexMode && !(options === null || options === void 0 ? void 0 : options.readOnlyMode) && !(options === null || options === void 0 ? void 0 : options.buttonOverride) && (React__default.createElement(p$5, { mt: "6", justify: "end", style: { width: '100%', paddingTop: '20px', borderTop: '1px solid var(--gray-5)' } },
                     React__default.createElement(o$a, { type: "submit", disabled: isSubmitting, style: Object.assign({ cursor: isSubmitting ? 'wait' : 'pointer', padding: '0 24px' }, (sanitizedData.brandColor ?
                             { backgroundColor: sanitizedData.brandColor, color: '#fff' }
                             :
@@ -57609,17 +57622,17 @@ class VectorSigma {
      * * `render()` is the final method in the Vector Sigma builder pattern chain.
      * @param options VectorSigmaRenderProps -- `VectorSigma` and `Teletraan1` props for VΣ render matrix.
      * @example .render({
-          displayMode: 'dual',
-          brandColor: '#800020',
-          readOnlyMode: false,
-          onSubmit: async (values, actions, instance) => { // <-- onSubmit callback function passed into VectorSigma props
+         displayMode: 'dual',
+         brandColor: '#800020',
+         readOnlyMode: false,
+         onSubmit: async (values, actions, instance) => { // <-- onSubmit callback function passed into VectorSigma props
             // Use Case: Send hydrated xForm object to API
             await axios.post('/api/submit', instance.getxForm());
             // Use Case: Submit and clear form after success
             actions.submitForm();
             actions.resetForm();
             },
-          onFinish: () => handleFormFinish() // <-- onFinish callback function passed into Teletraan1 (Codex) props
+         onFinish: () => handleFormFinish() // <-- onFinish callback function passed into Teletraan1 (Codex) props
       })})
      */
     render(options) {

package/lib/types/vectorSigma.d.ts

@@ -24,18 +24,35 @@ export interface VectorSigmaRenderProps<T extends Record<string, any> = Record<s
     /**
      * * Optional Radix UI Theme configuration.
      * Enables developer theming extensibility to align xForm appearance with an extant application design system.
-     *
-     * https://www.radix-ui.com/themes/docs/components/theme
+     * * https://www.radix-ui.com/themes/docs/components/theme
      * @example
      * theme={{ appearance: 'dark', accentColor: 'ruby', radius: 'large' }}
      */
     theme?: Omit<ThemeProps, 'children'>;
+    /**
+     * * Optional toggle to disable the default xForm bottom submit button.
+     * Allows developers to implement custom Submit, Save or Validate buttons outside xForm component.
+     * @example
+     * buttonOverride={true}
+     */
+    buttonOverride?: boolean;
+}
+export interface VectorSigmaActions<T> {
+    submitForm: () => Promise<void | undefined>;
+    resetForm: (nextState?: Partial<import('formik').FormikState<T>>) => void;
+    setValues: (values: React.SetStateAction<T>, shouldValidate?: boolean) => Promise<void | import('formik').FormikErrors<T>>;
+    setFieldValue: (field: string, value: any, shouldValidate?: boolean) => Promise<void | import('formik').FormikErrors<T>>;
+    setFieldError: (field: string, message: string | undefined) => void;
+    setFieldTouched: (field: string, isTouched?: boolean, shouldValidate?: boolean) => Promise<void | import('formik').FormikErrors<T>>;
+    validateForm: (values?: any) => Promise<import('formik').FormikErrors<T>>;
+    setSubmitting: (isSubmitting: boolean) => void;
 }
 export declare class VectorSigma<T extends Record<string, any> = Record<string, any>> {
     isValid: boolean;
     formObject: XFormType;
     values: Partial<T>;
     errors: Record<string, any>;
+    actions: VectorSigmaActions<T> | null;
     statusCode: 0 | 1 | 2;
     timeCreated: number;
     timeInProgress: number | null;
@@ -57,7 +74,7 @@ export declare class VectorSigma<T extends Record<string, any> = Record<string,
      */
     private buildFormikConfig;
     /**
-     * Traverses xForm schema object and injects Formik values into their respective input queryResponse attributes by `inputAlias`.
+     * Traverses xForm schema object and injects Formik values into respective input queryResponse attributes by `inputAlias`.
      */
     private hydrateQueryResponses;
     /**
@@ -149,17 +166,17 @@ export declare class VectorSigma<T extends Record<string, any> = Record<string,
      * * Transforms the initialized xForm JSON/JS object, normalizing attribute fields and returning a `<Teletraan1/>` component.
      * @param options VectorSigmaRenderProps -- `VectorSigma` and `Teletraan1` props for VΣ render matrix.
      * @example .transform({
-          displayMode: 'codex',
-          readOnlyMode: false,
-          brandColor: '#800020',
-          onSubmit: async (values, actions, instance) => { // <-- onSubmit callback function passed into VectorSigma props
+         displayMode: 'codex',
+         readOnlyMode: false,
+         brandColor: '#800020',
+         onSubmit: async (values, actions, instance) => { // <-- onSubmit callback function passed into VectorSigma props
             // Use Case: Send extant xForm object to API
             await axios.post('/api/submit', instance.getxForm());
             // Use Case: Submit and clear form after success
             actions.submitForm();
             actions.resetForm();
             },
-          onFinish: () => handleFormFinish() // <-- onFinish callback function passed into Teletraan1 (Codex only) props
+         onFinish: () => handleFormFinish() // <-- onFinish callback function passed into Teletraan1 (Codex only) props
       })})
      */
     transform(options?: VectorSigmaRenderProps<T>): React.ReactElement;
@@ -169,17 +186,17 @@ export declare class VectorSigma<T extends Record<string, any> = Record<string,
      * * `render()` is the final method in the Vector Sigma builder pattern chain.
      * @param options VectorSigmaRenderProps -- `VectorSigma` and `Teletraan1` props for VΣ render matrix.
      * @example .render({
-          displayMode: 'dual',
-          brandColor: '#800020',
-          readOnlyMode: false,
-          onSubmit: async (values, actions, instance) => { // <-- onSubmit callback function passed into VectorSigma props
+         displayMode: 'dual',
+         brandColor: '#800020',
+         readOnlyMode: false,
+         onSubmit: async (values, actions, instance) => { // <-- onSubmit callback function passed into VectorSigma props
             // Use Case: Send hydrated xForm object to API
             await axios.post('/api/submit', instance.getxForm());
             // Use Case: Submit and clear form after success
             actions.submitForm();
             actions.resetForm();
             },
-          onFinish: () => handleFormFinish() // <-- onFinish callback function passed into Teletraan1 (Codex) props
+         onFinish: () => handleFormFinish() // <-- onFinish callback function passed into Teletraan1 (Codex) props
       })})
      */
     render(options?: VectorSigmaRenderProps<T>): React.ReactElement;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@emeraldemperaur/vector-sigma",
-  "version": "1.4.48",
+  "version": "1.4.49",
   "description": "Dynamic Form Orchestrator: NPM Package",
   "repository": {
     "type": "git",
@@ -47,32 +47,24 @@
     "@types/react": "^19.2.10",
     "@types/react-dom": "^19.2.3",
     "@types/react-datepicker": "^6.2.0",
-    "formik": "^2.4.9",
     "identity-obj-proxy": "^3.0.0",
     "jest": "^30.2.0",
     "jest-environment-jsdom": "^30.2.0",
     "jest-junit": "^16.0.0",
-    "react": "^19.2.4",
-    "react-dom": "^19.2.4",
     "rollup": "^4.58.1",
     "rollup-plugin-delete": "^3.0.2",
     "rollup-plugin-postcss": "^4.0.2",
     "rollup-plugin-preserve-directives": "^0.4.0",
     "rollup-plugin-typescript2": "^0.36.0",
     "rollup-plugin-visualizer": "^6.0.5",
-    "sass-embedded": "^1.97.3",
     "ts-jest": "^29.4.6",
     "tslib": "^2.8.1",
-    "typescript": "^5.9.3",
-    "yup": "^1.7.1",
-    "zod": "^4.3.6"
+    "typescript": "^5.9.3"
   },
   "peerDependencies": {
-    "formik": "^2.4.9",
     "react": ">=18.0.0",
     "react-dom": ">=18.0.0",
-    "sass-embedded": "^1.97.3",
-    "yup": "^1.7.1"
+    "sass-embedded": "^1.97.3"
   },
   "dependencies": {
     "@radix-ui/react-accordion": "^1.2.12",
@@ -81,10 +73,13 @@
     "card-validator": "^10.0.4",
     "country-flag-icons": "^1.6.12",
     "date-fns": "^4.1.0",
+    "formik": "^2.4.9",
     "react-datepicker": "^9.1.0",
     "react-day-picker": "^9.13.1",
     "react-imask": "^7.6.1",
-    "react-phone-number-input": "^3.4.14"
+    "react-phone-number-input": "^3.4.14",
+    "yup": "^1.7.1",
+    "zod": "^4.3.6"
   },
   "overrides": {
     "minimatch": "^10.2.3"