FrontEnd

a JavaScript Libray of Quick Tools and ReactJS Components that aid development.

SimpleField

import {SimpleField} from "geekpops/form/fields/SubmitterField";

[attrib] object

this object is required

provides basic input field data

purpose

Creates an input field

accepted props:

| key | type | required | object | description | |:------------:|:----------------|----------|:--------:|:--------------------------| | name | string | true | attrib | field name | | label | string | false | attrib | filed label | | length | int | true | attrib | field length | | type | input type | true | attrib | field type | | index | int | false | attrib | index of array of fields | | onChange | function | false | attrib | onChange event | | void | bool | false | attrib | adds "data-void" to field | | ____________ | _____________ | ________ | _______ | _________________________ | | theme | colour | N/A | password | show/hide colour | | show | component | N/A | password | show PW IAI | | hide | compnent | N/A | password | hide PW IAI | | ____________ | _____________ | ________ | ________ | _________________________ | | length | int | N/A | append | appender property | | setLength | function | N/A | append | appender property | | change | boolean | N/A | append | appender property | | setChange | function | N/A | append | appender property | | _key | int | N/A | append | appender property | | style | object | N/A | append | appender styling | | ____________ | _____________ | ________ | ________ | _________________________ | | string | string | N/A e | ia | ia array object property | | icon | component | N/A | ia | ia array object property | | tooltip | string | N/A | ia | ia array object property | | theme | string/colour | N/A | ia | ia array object property |

usage

<SimpleField
    attrib={{
        name: `name`,
        label: `name`,
        length: 60,
        type: `text`,
        void: false,
        index: index /** used to target a specific field in an arry of fields */,
        onChange: () => {
        }
    }}
/>

[ia] array object

the array is required, but not the indices (JSON objects)

is an array of objects

[{}, {}]

This array can have a maximum of three object

purpose

it adds upto 3 icons (input Aid | IAs) inside the field,these IAs can/are used for added field functionality such as, [password showing], [form appending], [submit buttons] etc.. or field input clarity by placing a non-event driven IA (see usage) for explaining the field with tooltips if you like...

events may be attached to these IAI [input aid icon] in the future...

accepted props | object as array index [{}]:

| key | type | required | object | description | |:-------:|:------------|----------|:------:|:------------------------| | string | string | false | ia | description of the IAI | | icon | component | true | ia | icon of the IAI | | theme | colour | false | ia | colour of the IAI | | toolTip | string | false | ia | tool tip string for IAI |

usage

import {FileCountIco} from "@conf/icons";

<SimpleField
    ia={[
        {
            string: `hello world`,
            icon: FileCountIco,
            theme: `#FFF`,
            toolTip: {
                string: `hello world`
            }
        },
    ]}
/>

[password] object

purpose

uses the ia object (internally) to add password showing functionality to the field, for attrib = {type:'password'}

| key | type | required | object | description | |:-----:|:------------|----------|:--------:|:----------------| | theme | colour | false | password | icon colour | | show | component | true | password | pw showing icon | | hide | component | true | password | pws hiding icon |

usage

<SimpleField
    attrib={{type: `password`}}
    password={{
        theme: colour,
        show: ShowPasswordFillIco,
        hide: HidePasswordFillIco
    }}
/>

[append] object

purpose

uses the ia object (internally) to add functionality to the form that allows us to append the field's entire associated form to DOM.

| key | type | required | object | description | |:---------:|:-----------|----------|:------:|:--------------------| | length | int | true | append | number of instances | | setLength | function | true | append | adjust instances | | change | boolean | true | append | state value | | setChange | function | true | append | update state value | | _key | int | true | append | index of instance | | style | object | true | append | style object |

Style Object properties apply for {append:{}} and {unappend:{}} see usage

| key | type | required | object | description | |:-----:|:------------|----------|:-------------:|:-----------------------| | icon | component | true | append::style | append/unappend icon | | theme | colour | false | append::style | append/unappend colour |

usage

<SimpleField
    append={
        {
            length: _length,
            setLength: set_length,
            change: change,
            setChange: setChange,
            _key: key,
            style: {
                append: {
                    icon: PlusLineIco,
                    theme: `#b30000`
                },
                unappend: {
                    icon: MinusLineIco,
                    theme: `white`
                }
            }
        }}
/>

full usage

<ul>
    <SimpleField
        attrib={{
            name: `name`,
            label: `name`,
            length: 60,
            type: `text`,
            onChange: () => {
            },
            index: index /** used to target a specific field in an arry of fields */,
            void: true /** adds [data-void], so JS can be used to invalidate the input field... */
        }}
        ia={[
            {
                string: `hello world`,
                icon: FileCountIco,
                theme: `#FFF`,
                toolTip: {
                    string: `hello world`
                }
            }
        ]}
        password={{
            theme: colour,
            show: ShowPasswordFillIco,
            hide: HidePasswordFillIco
        }}
        append={
            {
                length: _length,
                setLength: set_length,
                change: change,
                setChange: setChange,
                _key: key,
                style: {
                    append: {
                        icon: PlusLineIco,
                        theme: `red`
                    },
                    unappend: {
                        icon: MinusLineIco,
                        theme: `white`
                    }
                }
            }}
    />
</ul>

=======================================================

SubmitterField

import {SubmitterField} from "geekpops/form/fields/SubmitterField";

the [SubmitterField] is just a [SimpleField] with a permanent IAI and actions object to action the form.

N.B. there can only be one of these per form.

[attrib] object

this object is required

provides basic input field data

purpose

Creates an input field

accepted props:

| key | type | required | object | description | |:------------:|:---------------|----------|:--------:|:---------------------------| | name | string | true | attrib | field name | | label | string | false | attrib | filed label | | length | int | true | attrib | field length | | type | input type | true | attrib | field type | | ____________ | _____________ | ________ | _______ | _________________________ | | theme | colour | N/A | style | IA colour | | submit | component | N/A | style | submit icon | | loader | compnent | N/A | style | "loading" icon | | ____________ | _____________ | ________ | ________ | _________________________ | | method | fnction | N/A | action | form submitting function | | submit | boolean | N/A | action | submission state evaluator | | states | state object | N/A | action | component state values | | setStates | function | N/A | action | state function | | dispatch | function | N/A | action | redux state function | | interface | object | N/A | action | redux interface object | | collapseForm | | N/A | action | | | params | object | N/A | action | object of values to submit |

usage

<SimpleField
    attrib={{
        name: `name`,
        label: `name`,
        length: 60,
        type: `text`
    }}

/>

[style] object

this object is required

uses the ia object (internally) to add submit & "loading" IAs as well as the colour for those icons

purpose

adds form submission elements to field.

accepted props:

| key | type | required | object | description | |:------:|:------------|----------|:------:|:---------------| | theme | colour | true | style | icons colour | | submit | component | true | style | submit icon | | loader | component | true | style | "loading" icon |

usage

<SubmitterField
    style={{
        theme: `white`,
        submit: SendLineIco,
        loader: CircleLoader
    }}
/>

[action] object

this object is required

purpose

adds form submission functionality to field.

accepted props:

| key | type | required | object | description | |:------------:|:-------------------------|----------|:------:|:----------------------------------------| | method | function | true | action | submits the form | | submit | boolean | true | action | evaluates state of submission | | sates | component state values | true | action | component state object | | setStates | function | true | action | modify component state object | | dispatch | function | true | action | dispatch data to redux state | | interface | function | true | action | allows access to redux global state | | collapseForm | | false | action | | | params | object | false | action | passes component variables to submitter |

usage

<SubmitterField
    action={{
        method: Actions.Staff.Request,
        submit: states.submit,
        states: {...states},
        setStates: setStates,
        dispatch: props.BackEndAuth.mapDispatch,
        interface: props.BackEndAuth.Interface,
        collapseForm: {states: states, setStates: setStates},
        params: {}
    }}
/>

[ia] object (array)

the array is required, but not the indices (JSON objects)

is an array of objects

[{}, {}]

This array can have a maximum of three object

N.B. In this case there can only be a maximum of 2 IAIs, this is because there's already 1 permanent IAI for submitting the form.

purpose

it adds upto 3 icons inside the field,these icons can be used for adding the visitor on the action to take.

events may be attached to these IAI [input aid icon] in the future...

accepted props | object as array index [{}]:

| key | type | required | object | description | |:-------:|:------------|----------|:------:|:-----------------------| | string | string | false | ia | description of the IAI | | icon | component | true | ia | icon of the IAI | | theme | colour | false | ia | colour of the IAI | | toolTip | string | false | ia | tooltip string for IAI |

usage

import {FileCountIco} from "@conf/icons";

<SimpleField
    ia={[
        {
            string: `hello world`,
            icon: FileCountIco,
            theme: `#FFF`,
            toolTip: {
                string: `hello world`
            }
        }
    ]}
/>

full usage

<SubmitterField
    attrib={{
        name: `qemail`,
        label: `email`,
        length: 60,
        type: `email`
    }}
    style={{
        theme: `white`,
        submit: SendLineIco,
        loader: CircleLoader
    }}
    ia={[]}
    action={{
        method: Actions.Quotes.Submit,
        submit: states.submit,
        states: {...states},
        setStates: setStates,
        dispatch: props.mapDispatch,
        interface: props.Interface,
        collapseForm: {states: props.states, setStates: props.setStates},
        params: {
            uploads: props.Interface.uploads
        }
    }}
/>

the click event

{
    !props.action.states.submit &&
    <span
        onClick={target => {
            props.action.method({
                params: {...props.action.params},
                element: {...target},
                states: {states: {...props.action.states}, setStates: props.action.setStates},
                dispatch: props.action.dispatch,
                interface: props.action.interface,
                caller: `${props.attrib.name}_ia` //needed by ErrorHandler::print()
            });
            /** negate submit value to call loader */
            props.action.setStates({...props.action.states, submit: true});
        }}
        title={`send`}>
        <Submit {...{theme: props.style.theme}}/>
    </span>
}

{
    props.action.states.submit &&
    <span>
        <Loading {...{theme: props.style.theme}}/>
    </span>
}

data at the method will always be received as:

{
    params: {},
    element: {},
    states: {
        states: {}, setStates: function () {
        }
    },
    dispatch: function () {
    },
    interface: {},
    caller: `caller`
}

========================================================

ErrorHandler

import {ErrorHandler} from "geekpops/Libs/MessageDispatcher";

An error handling scope used primarily in input validation of frontend & backend error responses.

ErrorHandler::print()

*purpose

prints errors to visitor on screen.

most errors are printed just below the affected input field.

the error message is bound-elastic, meaning it only lasts for a few seconds before it disappears, and it appears relative to the affected field.

milisecs = object.message.length <= 60 ? 3000 : (object.message.length / 35) * 1000;

await sleep(milisecs);

the timeout depends on the message string length, the shorter the string, the quicker the timeout.

string lengths <= 60 will have a 3 sec timeout.

this methods affect these HTML elements:

keys = {
    group: Utils.DOMCLS(`${object.key}_group`),
    error: Utils.DOMCLS(`${object.key}_error`),
    ia: Utils.DOMCLS(`${object.key}_ia`),
    /** the IAI that let to the invocation of this method */
    caller: Utils.DOMCLS(`${object.caller}`)
};

...where ${object.key} is the same input field name used on various elements suffixed with:

_group or _error or _ia

the caller is the IAI is the icon that led to the invocation of this method, it along with IAIs from the affected field are removed from view while the error message is displayed.

/** hide input aid icons/buttons while the error message is displayed */
keys.ia && keys.ia.classList.add(`hidden`);
keys.caller && keys.caller.classList.add(`hidden`);

_group,_error&_ia

<li>
    <div className={`${props.attrib.name}_group`}>

        <input
            type={props.attrib.type}
            maxLength={props.attrib.length}
            name={props.attrib.name}
            required/>

        <IL{...{...props.attrib}}/>
        {/** infield input aid icons*/}
        {inputAid && <div className={`${props.attrib.name}_ia`} data-ia-inline {...inputAid}>
            {props.ia.map((item, key) => {
                const IAI = item.icon;
                return <span title={item.string} key={key}><IAI {...{theme: item.theme}}/></span>
            })}
        </div>}
    </div>
    {/** print error here */}
    <div style={{"--error-timeout": 0}} className={`${props.attrib.name}_error hidden`} data-error></div>
</li>

since the messages' timeout automatically, we've added a regressive bar that runs down with the time to help reducer visitor impatience.

/** establish time remaining in seconds*/
const TimeRemaining = ((new Date().getTime() + ms) - (new Date().getTime())) / 10;
/** work out percentage from 100 to 0 */
percentage = 100 - ((TTL - TimeRemaining) / (TTL + TimeRemaining / 2)) * 100;

/**update [--error-timeout] inline variable until 0 **/
Utils.DOMCLS(`${object.key}_error`).style.setProperty(`--error-timeout`, `${percentage}%`);

lastly a shake effect is added to the _group, so the visitor can still know where the error occurred even after the bound-elastic error message.

/** add shake to input group */
keys.group.classList.add(`animate`, `error`);

this effect lasts until the visitor re-focus on the field.

accepted arguements (as object):

| key | type | required | description | |:--------:|:---------|----------|:-------------------------------------| | key | string | true | field name | | message | string | true | error message (local or remote) | | response | int | true | response type | | type | string | false | type of error (error or warning) | | caller | string | false | where click event occurred |

N.B. in all input error cases, the type of error will be error because errors are blocking.

usage

MessageDispatcher.print({
    key: `key`,
    message: `message`,
    response: 1,
    type: `error`,
    caller: `caller` //usually attached to the click event that led to the error being invoked.
});

===========================================================

MessageHandler

import {MessageHandler} from "geekpops/Libs/MessageDispatcher";

A message handling scope used to display messages, mostly promise fulfilled messages, such as form submission success and similar.

MessageHandler::elastic()

purpose

Print messages to visitor on screen.

the message is unbound-elastic, meaning it only lasts for a few seconds before it disappears, and it appears fixed relative to the viewport.

required mark-up

<header>
    {/** your mark-up  */}
</header>
<div style={{"--message-timeout": 0}} className={`elastic hidden`}></div>

which is preferably placed in the project's header component.

milisecs = object.message.length <= 60 ? 3000 : ((object.message.length * object.multiply) / 35) * 1000;

await sleep(milisecs);

the timeout depends on the message string length, the shorter the string, the quicker the timeout.

for added display time, string length can be multiplied

MessageHandler.elastic({...data, caller: `accept_ia`, multiply: 2});

string lengths <= 60 will have a 3 sec timeout.

since the messages' timeout automatically, we've added a regressive bar that runs down with the time to help reducer visitor impatience.

/** establish time remaining in seconds*/
const TimeRemaining = ((new Date().getTime() + ms) - (new Date().getTime())) / 10;
/** work out percentage from 100 to 0 */
percentage = 100 - ((TTL - TimeRemaining) / (TTL + TimeRemaining / 2)) * 100;

/**update [--error-timeout] inline variable until 0 **/
Utils.DOMCLS(`elastic`).style.setProperty(`--message-timeout`, `${percentage}%`);

accepted arguements (as object):

| key | type | required | description | |:--------:|:----------------|----------|:------------------------------------------------------------------| | message | string | true | error message (local or remote) | | multiply | int / float | false | extends the message display time by multiplying the string length | | caller | string | false | where click event occurred |

usage

MessageHandler.elastic({
    message:`string...`,
    caller: `accept_ia`,
    multiply: 2
});

===========================================================