💠 Vector Sigma

Dynamic Form Orchestrator 📦

Overview

Fields, Input Validation and Submission callback() can be defined and parametized in real-time predicated on a native JavaScript object/JSON (JavaScript Object Notation) xForm definition or by builder methods object pattern.

Key Features

Documentation

Installation

npm install @emeraldemperaur/vector-sigma

Peer Dependencies

npm install react@latest react-dom@latest sass@latest

Usage

Stateless Implementation

import React from 'react';
import { VectorSigma } from './VectorSigma';

const xForm = new VectorSigma(apiJSONSchema);
// e.g. https://github.com/emeraldemperaur/vector-sigma/blob/prometheus/src/utils/artificer.json

return xForm.transform({
    displayMode: 'dual',
    readOnlyMode: false,
    onSubmit: async (values, actions, instance) => {
        // Send validated xForm 'values' payload to destination API endpoint
        await axios.post('/api/submit', values);
        // Reset form after HTTP POST request success and more (i.e. https://formik.org/docs/api/formik)
        actions.resetForm(); 
    }
});

Stateful Implementation

import React from 'react';
import { useVectorSigma } from './hooks/useVectorSigma';
import { apiXFormData } from './mockData';
// e.g. https://github.com/emeraldemperaur/vector-sigma/blob/prometheus/src/utils/artificer.json

// Optionally define interface for inputAlias's expected in xForm 'values'
interface VΣRegistrationForm {
    firstName: string;
    lastName: string;
    emailAddress: string;
    isMITUndergraduate: boolean;
}

export const VΣRegistrationForm = () => {
    
    // Optionally pass the interface into the hook to apply <T> typing to 'values'
    const xFormBuilder = useVectorSigma<VΣRegistrationForm>(apiXFormData);

    // Or w/out a specified interface
    const xFormBuilder = useVectorSigma(apiXFormData);
        .setName('VΣ Registration Form')
        .setBrand("brandHexColor", "www.exampleurl.com/logoimage.png", 'right')
    return xFormBuilder.render({
        displayMode: 'accordion',
        readOnlyMode: false,
        // Access 'values', 'actions' and 'instance' objects in global onSubmit callback function
        onSubmit: async (values, actions, instance) => {
            
            console.log("Email:", values.emailAddress);
            console.log("MIT Undergraduate:", values.isMITUndergraduate);
            const timeTakenMs = (instance.timeSubmitted || Date.now()) - instance.timeCreated;
            console.log(`VΣ User finished the xForm in ${timeTakenMs / 1000} seconds.`);
            console.log(`xForm Status:`, instance.statusCode);
            
           try {
                // Initiate HTTP POST request with stateful 'values' and 'instance' payload
                await fetch(`/api/questionnaires/${instance.formObject.uuid}/responses`, {
                            method: 'POST',
                            headers: { 'Content-Type': 'application/json' },
                            body: JSON.stringify({
                                formVersion: instance.formObject.uuid,
                                responseTime: instance.timeSubmitted - instance.timeCreated,
                                xFormObject: instance.formObject,
                                answers: values
                            })
                        });
                // Reset form after HTTP POST request success and more (i.e. https://formik.org/docs/api/formik)
                actions.resetForm(); 
                alert("Thank you for completing the VΣ questionnaire!");
               } catch (error) {
                      console.error("Failed to save responses to VΣ DB", error);
                }
        }
    });
  
};

Screenshots

Automation Workflow (N8N Webhook Trigger Node) Use Case

Web Application (User Onboarding Data Pipeline) Use Case

Design Tenets

import React from 'react';
import { VectorSigma } from './VectorSigma';
import { xFormPrototypeData } from './mockData'; 

export const BespokeAPIForm = ({ brandColor, brandLogoUrl }) => {
    
    // Initialize VectorSigma xForm with JSON schema
    const xFormBuilder = new VectorSigma(xFormPrototypeData);

    // Chain VectorSigma builder methods to specify or override the xForm model properties dynamically
    const xFormElement = xFormBuilder
        .setName('Cyberdyne Systems Billing Form')
        // Optionally override brand color and logo from JSON {} with brand props
        // setBrand(color, logoUrl?, logoPosition?)
        .setBrand(tenantBrandColor, tenantLogo, 'left')
        
        // Output xForm React component with .transform()
        .transform({
            displayMode: 'dual', // Dual Display UI (i.e. Codice | Accordion)
            readOnlyMode: false,
            // Optionally inject VectorSigma global callback function
            onSubmit: async (values, actions, instance) => {
                console.log("Processing Payment...", values);
                
                // Initiate a HTTP POST request to destination API with 'values' payload
                await new Promise(resolve => setTimeout(resolve, 1997));
                
                alert("Payment processed successfully!...");
                // Update Formik context to isSubmitting false after successful HTTP post request
                actions.setSubmitting(false); 
            },
            // Optionally inject Teletraan1 (codex display) callback function
            onFinish: () => {
                console.log("xForm submission complete.");
            }
        });

    return (
        <div className="cyberdyne-store-portal">
            {xFormElement}
        </div>
    );
};

import React from 'react';
import { VectorSigma } from './VectorSigma';

export const VΣCodexForm = () => {
    // Initialize an empty xForm
    const xFormBuilder = new VectorSigma();

    // Chain object methods to build xForm schema
    // ---------------------------------------------------------
    // METHOD A: addSection(xFormSectionSchema{})
    // METHOD B: createSection() * addQueryToSection()
    // ---------------------------------------------------------
    const xFormElement = xFormBuilder
        .setUUID('ai-agent-007')
        .setName('New User Onboarding')
        // setBrand(color, logoUrl?, logoPosition?)
        .setBrand(
            '#800020', // Brand (i.e. Primary) color
            'https://www.example.com/brandLogo.jpeg', // Brand Logo URL
            'center' // Brand Logo alignment
        )
        .createSection('personal-info', 'Personal Information', 'user')
        .addQueryToSection('personal-info', {
            queryId: 101,
            inputType: 'text-input',
            inputAlias: 'firstName',
            inputLabel: 'First Name',
            inputPlaceholder: 'Enter your first name',
            inputWidth: 6,
            newRow: true,
            isRequired: true,
            errorText: 'First name is required'
        })
        .createSection('address-info', 'Address Info', 'home')
        .addQueryToSection('address-info', {
            queryId: 102,
            inputType: 'password-input',
            inputAlias: 'securityCode',
            inputLabel: 'Secure Passcode',
            inputWidth: 6,
            newRow: true,
            isRequired: true,
            errorText: 'Security code is required'
        })
        .addSection({
            sectionId: "shipping-info",
            title: "Shipping Address",
            icon: "paperplane",
            queries: [
                {
                    queryId: 103,
                    inputType: "text-input",
                    inputAlias: "deliveryAddress",
                    inputLabel: "Home Address",
                    inputWidth: 9,
                    newRow: false,
                    isRequired: true,
                    errorText: 'Address is required for shipping'
                }
            ]
        })
        .render({
            displayMode: 'codex',
            readOnlyMode: false,
            // Optionally inject Teletraan1 (codex display) callback
            onFinish:  () => {
                console.log("xForm submission complete.");
            }
            // Optionally inject VectorSigma global callback
            onSubmit: async (values, actions, instance) => {
                console.log("Submitting to API...", values);
                try {
                    await fetch('/api/users/onboard', {
                        method: 'POST',
                        body: JSON.stringify(values)
                    });
                    alert("VΣ has come to...");
                    actions.submitForm();
                    actions.resetForm();
                } catch (error) {
                    console.error("xForm submission failed", error);
                }
            }
        });

    return (
        <div className="x-form-container">
            {xFormElement}
        </div>
    );
};

 const xFormElement = xFormBuilder
        .setUUID('kaiju-zaibatsu-101011')
        .setName('Monaco Smart Road User Registration')
        .setBrand(
            '#800020',
            'https://www.example.com/brandLogo.jpeg',
            'right'
        )
        .createSection('vehicle-info', 'Vehicle Information', 'avatar')
        .addQueryToSection('vehicle-info', {
            queryId: 1,
            inputType: 'text-input',
            inputAlias: 'vehicleRegistration',
            inputLabel: 'Vehicle Registration Number',
            inputPlaceholder: 'Enter your vehicle registration number',
            inputWidth: 7,
            newRow: true,
            isRequired: true, // Specifies if input validation required
            errorText: 'A vehicle registration number is required' // Specifies errorText rendered when isRequired and validation fails
        })

import React from 'react';
import { useVectorSigma } from './hooks/useVectorSigma';

 const xFormBuilder = useVectorSigma(apiXFormData);
        .setName('VΣ Robot Activation')
        .setBrand("brandHexColor", "www.exampleurl.com/logoimage.png", 'center')
    return xFormBuilder.render({
        displayMode: 'codex',
        readOnlyMode: false,
        // Access 'values', 'actions' and 'instance' object(s) in global onSubmit callback function
        // 'instance' :: { errors, statusCode, isSubmitting, timeCreated, timeInProgress, timeSubmitted, formObject } 
        onSubmit: async (values, actions, instance) => {
            
            console.log("VΣ User Email:", values.emailAddress);
            console.log("VΣ Robot Serial Number:", values.serialNumber);
            const timeTakenMs = (instance.timeSubmitted || Date.now()) - instance.timeCreated;
            console.log(`VΣ User finished the xForm in ${timeTakenMs / 1000} seconds.`);
            console.log(`Extant xForm Status:`, instance.statusCode);
            console.log(`Extant xForm object:`, instance.formObject);
            // Initiate Promise or API HTTP POST
            await new Promise(resolve => setTimeout(resolve, 1000));
            alert("VΣ Robot Activated!");
            actions.resetForm();
        }
        })

import React from 'react';
import { VectorSigma } from './VectorSigma';

const xForm97 = new VectorSigma(apiJSONData);

return xForm97.render({
    displayMode: 'codex',
    // www.radix-ui.com/themes/docs/components/theme
    theme: {
        appearance: 'dark',  
        accentColor: 'yellow',     
        grayColor: 'slate',        
        radius: 'none',            
        scaling: '100%'            
    },
    onSubmit: async (values, actions, instance) => {
        console.log(values);
    }
});

import { Container, Column, Row, CheckboxGroup, Dropdown, File, RangeSlider } 
from '@emeraldemperaur/vector-sigma';
import { Theme } from '@emeraldemperaur/vector-sigma';
import { Form, Formik } from 'formik'
import * as Yup from 'yup'


const App = () => {
  return (
    <Container fluid>
      <Row>
        <Column span={9}>
        <Formik 
          initialValues={{
            dropdownInput: 'Zaibatsu',
          }}
          
          validationSchema={Yup.object({
            dropdownInput: Yup.string().required('Dropdown selection is required'),
          })}

          onSubmit={(values) => {
            console.log(values);
          }}
    >
      {({ values }) => (
        <Form>
            <Theme>
            <File alias='inputFile' width={3}/>
            <Dropdown alias="dropdownInput" width={8} inputLabel="Dropdown Element" inputtype="dropdown-outline" value="Zaibatsu" 
                inputoptions={
                    [
                    {optionid: 1, 
                    optionvalue: "Kaiju", 
                    optionurl:"https://github.com/emeraldemperaur", 
                    text: "Kaiju"},
                    {optionid: 2, 
                    optionvalue: "Meka", 
                    optionurl:"https://www.mekaegwim.ca", 
                    text: "Meka"},
                    {optionid: 3, 
                    optionvalue: "Godzilla", 
                    optionurl:"https://www.me.ca", 
                    text: "Godzilla"},
                    {optionid: 4, 
                    optionvalue: "Zaibatsu", 
                    optionurl:"https://www.npmjs.com/package/@emeraldemperaur/vector-sigma", 
                    text: "Zaibatsu"},
                    ]}/>
            </Theme>
            <button type="submit" style={{ marginTop: 20 }}>Submit</button>
        </Form>
      )}
        </Formik>
        </Column>
      </Row>
    </Container>
  );
}

Tool Stack

Changeset Versioning Synopsis

npm install --save-dev @changesets/cli
# Changeset project initializer
npx changeset init

git checkout -b new-changeset-branchname

# Changeset - patch, minor, major versioning
npx changeset

# PreRelease mode (alpha)
npx changeset pre enter alpha

# PreRelease mode (beta)
npx changeset pre enter beta

# Exit PreRelease mode 
npx changeset pre exit

git add .
git commit -m "Changeset :: commit message"
git status
# confirm clean working tree before push
git push origin new-changeset-branchname

git checkout prometheus

git pull origin prometheus