@emeraldemperaur/vector-sigma 1.4.38 → 1.4.40

package/lib/types/components/conditional/conditional.d.ts

@@ -5,7 +5,7 @@ import '../../styles/main.scss';
 export type ToggleTriggerDesign = 'conditionaltoggle' | 'conditionaltoggle-outline' | 'conditionaltoggle-material' | 'conditionaltoggle-neumorphic';
 export type CheckboxTriggerDesign = 'conditionalcheckbox' | 'conditionalcheckbox-outline' | 'conditionalcheckbox-material' | 'conditionalcheckbox-neumorphic';
 export type SelectTriggerDesign = 'conditionalselect' | 'conditionalselect-outline' | 'conditionalselect-material' | 'conditionalselect-neumorphic';
-export type TriggerType = 'conditionaltoggle' | 'conditionalcheckbox' | 'conditionalselect';
+export type TriggerType = 'conditionaltoggle' | 'conditionalcheckbox' | 'conditionalselect' | 'conditional-toggle' | 'conditional-checkbox' | 'conditional-select';
 export interface ConditionalProps {
     /**
      * * The design variation of the Conditional Trigger input.

package/lib/types/hooks/useVectorSigma.d.ts

@@ -0,0 +1,9 @@
+import { VectorSigma } from '../vectorSigma';
+import { XFormType } from '../utils/voltron';
+/**
+ * VΣ hook to securely initialize and persist a VectorSigma instance
+ * across React re-renders w/out losing internal VΣ tracking state.
+ * * @param initializer Optional JSON string, XFormType object, or undefined when constructing xForm schema object by builder methods.
+ * @returns Stateful VectorSigma class instance.
+ */
+export declare const useVectorSigma: (initializer?: string | XFormType | unknown) => VectorSigma<Record<string, any>>;

package/lib/types/vectorSigma.d.ts

@@ -2,11 +2,29 @@ import React from 'react';
 import { XFormType, XFormQuery, SectionSchema } from './utils/voltron';
 import { Teletraan1Props } from './teletraan1';
 import { z } from "zod";
+import { FormikHelpers } from 'formik';
 import './styles/main.scss';
-export declare class VectorSigma {
+export interface VectorSigmaRenderProps<T extends Record<string, any> = Record<string, any>> extends Omit<Teletraan1Props, 'xFormModel'> {
+    /**
+     * * Optional callback fired when the form is submitted and passes validation.
+     * Receives normalized xForm form values, developer access to Formik action helper methods, and the VectorSigma class instance.
+     * * @example
+     * onSubmit={async (values, actions, instance) => {
+        // Send data to API
+        await axios.post('/api/upload', instance.getxForm());
+        await axios.post('/api/submit', values);
+        // Track completion time using 'instance'
+        console.log(`Form completed in ${(instance.timeSubmitted! - instance.timeCreated) / 1000}s`);
+        // Clear form after success
+        actions.resetForm();
+    }}
+     */
+    onSubmit?: (values: T, actions: FormikHelpers<T>, instance: VectorSigma<T>) => void | Promise<any>;
+}
+export declare class VectorSigma<T extends Record<string, any> = Record<string, any>> {
     isValid: boolean;
     formObject: XFormType;
-    values: Record<string, any>;
+    values: Partial<T>;
     errors: Record<string, any>;
     statusCode: 0 | 1 | 2;
     timeCreated: number;
@@ -14,34 +32,154 @@ export declare class VectorSigma {
     timeSubmitted: number | null;
     isSubmitting: boolean;
     /**
-     * Initializes the VectorSigma instance.
-     * @param initializer A JSON string or a JavaScript object matching XFormType.
-     * If left empty, initializes a blank form object for use with Builder methods.
+     * Initializes VectorSigma instance.
+     * @param initializer JSON string literal or a JavaScript {} matching XFormType.
+     * When undefined, initializes base xForm object scaffold for use with VectorSigma builder methods.
      */
     constructor(initializer?: string | XFormType | unknown);
     /**
-     * Safely validates the input against the XFormSchema.
-     * Throws developer-friendly errors if the JSON is malformed or violates the schema.
+     * Validates JSON juxtaposed with the XFormSchema.
+     * Raises DX (developer-friendly) errors if the JSON malformed or violates XFormSchema.
      */
     private validateAndSet;
     /**
-     * Traverses the schema to extract Formik InitialValues and Yup Validation logic.
+     * Extrapolates Formik InitialValues and Yup Schema based on inputType value data type.
      */
     private buildFormikConfig;
+    /**
+     * Traverses xForm schema object and injects Formik values into their respective input queryResponse attributes by `inputAlias`.
+     */
+    private hydrateQueryResponses;
+    /**
+     * VΣ builder method to set the xForm model's unique universal identifier (uuid) attribute.
+     * @param uuid unique universal identifier for xForm object.
+     * @example
+     * const xForm97 = new VectorSigma()
+     * .setUUID("the-uuid-is-sahelanthropus")
+     */
     setUUID(uuid: string): this;
+    /**
+     * VΣ builder method to set the xForm model's name attribute.
+     * @param name name for xForm object.
+     * @example
+     * const xForm97 = new VectorSigma()
+     * .setName("Wakanda Citizenship Form")
+     */
     setName(name: string): this;
+    /**
+     * VΣ builder method to set the xForm model's branding attribute.
+     * @param color brand color hex string for xForm object.
+     * @param logo logo image url for xForm object.
+     * @param logoPosition logo position for xForm object.
+     * @example
+     * const xForm97 = new VectorSigma()
+     * .setBrand("#000000", brandLogoUrlRef, 'right')
+     */
     setBrand(color: string, logo?: string, logoPosition?: 'left' | 'center' | 'right'): this;
+    /**
+     * VΣ builder method to add a Section object to the xForm model.
+     * @param section valid schema section object for xForm model.
+     * @example
+     * const xForm97 = new VectorSigma()
+     * .setBrand("#000000", brandLogoUrlRef, 'right')
+     * .addSection({
+            sectionId: "bio-data",
+            title: "Personal Information",
+            icon: "user",
+            queries: [
+                {
+                    queryId: 303,
+                    inputType: "text-input",
+                    inputAlias: "wakandanName",
+                    inputLabel: "Wakandan Name",
+                    inputWidth: 7,
+                    newRow: false,
+                    isRequired: true,
+                    errorText: "Wakandan name is required for citizenship applications"
+                }
+            ]
+        })
+     */
     addSection(section: z.infer<typeof SectionSchema>): this;
+    /**
+     * VΣ builder method to create a Section object in the xForm model.
+     * @param sectionId sectionId string for the xForm model section.
+     * @param title title string for the xForm model section.
+     * @param icon xForm icon name for the xForm model section.
+     * @example
+     * const xForm97 = new VectorSigma()
+     * .setBrand("#000000", brandLogoUrlRef, 'right')
+     * .createSection('bio-data', 'Personal Information', 'user')
+     */
     createSection(sectionId: string, title: string, icon?: string): this;
+    /**
+     * VΣ builder method to add a Query object to the xForm model section by sectionId.
+     * @param sectionId sectionId string for the target xForm model section.
+     * @param query valid schema query object for the xForm model section.
+     * @example
+     * const xForm97 = new VectorSigma()
+     * .setBrand("#000000", brandLogoUrlRef, 'right')
+     * .createSection('bio-data', 'Personal Information', 'user')
+     * .addQueryToSection('bio-data', {
+            queryId: 100,
+            inputType: 'password-input',
+            inputAlias: 'wakanadaPassport',
+            inputLabel: 'Wakandan Passport Number',
+            inputWidth: 6,
+            newRow: false,
+            isRequired: true,
+            errorText: "A valid passport number is required for citizenship application"
+        })
+     */
     addQueryToSection(sectionId: string, query: XFormQuery): this;
     /**
-     * Transforms the initialized xForm JSON/JS object by normalizing it and returning a `<Teletraan1/>` component.
+     * VΣ `transform()` method for use with initialized JSON/Object
+     * * Apt for integration with JSON data fetched from a backend API or localhost .json file.
+     * * 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
+            // 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
+      })})
+     */
+    transform(options?: VectorSigmaRenderProps<T>): React.ReactElement;
+    /**
+     * VΣ `render()` method for use with VectorSigma object builder
+     * * Apt for dynamically creating forms via code.
+     * * `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
+            // 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
+      })})
      */
-    transform(teletraanProps?: Omit<Teletraan1Props, 'xFormModel'>): React.ReactElement;
+    render(options?: VectorSigmaRenderProps<T>): React.ReactElement;
     /**
-     * `render()` is the final method in the builder pattern chain.
+     * VΣ `toJSON()` utility method for retrieving the extant VectorSigma xForm JSON string
+     * @example toJSON()
      */
-    render(teletraanProps?: Omit<Teletraan1Props, 'xFormModel'>): React.ReactElement;
     toJSON(): string;
-    getObject(): XFormType;
+    /**
+     * VΣ `getxForm()` utility method for retrieving the extant VectorSigma xForm {}
+     * @example getxForm()
+     */
+    getxForm(): XFormType;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@emeraldemperaur/vector-sigma",
-  "version": "1.4.38",
+  "version": "1.4.40",
   "description": "Dynamic Form Orchestrator: NPM Package",
   "repository": {
     "type": "git",