TBC Common React App Helpers Modules

Common Helpers for all Trinidad Benham React apps, including:

• CommonDropDown
• Icons
• LabeledInput
• MultiSelect

Install

npm install --save tbc-common-helpers

Components

CommonDropDown Component:

Common Drop Down takes a dictionary or array of data objects and returns a group of option tags (for use within a select).

import CommonDropDown from "tbc-common-helpers/dist/CommonDropDown";

Within a select tag or React Component equivalent, place:

<CommonDropDown {...props} />

CommonDropDown props

| Prop | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | options | Array | Required* | null | Array of data objects to be converted to a list. Either this or dictionary must be provided | | dictionary | Object | Required* | null | Object of data objects to be converted to a list. Either this or options must be provided | | sortBy | String | Optional | "nm" | Sets how the return options are sorted; by default this is by the "nm" key | | optionValueCode | String | Optional | "cd" | By default the values of each option will be the data object's "cd"; use this prop if another key should be used instead | | optionDisplayCode | String | Optional | "nm | By default the display name for each option will be the data object's "nm"; use this prop if another key should be used instead | | noBlankFirstLine | Boolean | Optional | false | By default a blank line will be provided at the top of the option list; set this flag if no blank line should be provided | | ignoreActiveFlag | Boolean | Optional | false | By default, only data items with an "act" flag set to true will be displayed in the option list; use this flag to display all items, regardless of "act" flag | | defaultValue | Object | Optional | null | If a defaultValue object is provided, this object will be displayed at the top of the option list, beneath the blank blank line (if applicable). The defaultValue object looks like {optionValueCode: "value", optionalDisplayCode: "Default Value"} |

Expected data format

options

CommonDropDown expects the options array to look like this:

[
    {
        cd: "CODE",
        nm: "Name",
        act: true,
        ...
    },    
    {
        cd: "INACT",
        nm: "Inactive Value",
        act: false,
        ...
    }
]

Other key/values can be provided, but these will not be used by the CommonDropDown unless set so by the props.

dictionary

CommonDropDown expect the dictionary object to look like this:

{
    CODE: {
        nm: "Name",
        act: true,
        ...
    },
    INACT: {
        nm: "Inactive Value",
        act: false,
        ...
    }
}

By default, the key of each item will be used as the value, although this can be modified via props, as can the display name.

Icons Component:

Icons component contains three pre-build dynamic icons.

import { RequiredIcon, WarningIcon, SavedIcon, YesNoIcon } from "tbc-common-helpers/dist/Icons";

RequiredIcon:

This is a small icon that can be placed at the end of a field label for a required field; it has a tool tip stating "Required Field"

<RequiredIcon notRequired={!required} />

| Prop | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | notRequired | Boolean | Optional | false | Flag that determines if the required icon is not needed (if set to true, the RequiredIcon does not display). The purpose of this is to add a conditional flag to the icon to simplify conditional required |

WarningIcon:

This is a small icon that can be placed where ever a warning can be placed.

<WarningIcon {...props} />

| Prop | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | show | Boolean | Optional | false | Flag that determines if the warning icon should be displayed | | toolTip | String | Optional | "" | Text of the tooltip (mouse over) of the icon | | cssClasses | String | Optional | "" | Additional css classes that can be applied to the warning icon |

SavedIcon:

This icon shows a red file or green upload icon depending on if the "saved" flag prop is provided.

<SavedIcon saved={saved} />

| Prop | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | saved | Boolean | Optional | false | Flag that determines if the icon is in "unsaved" or "saved" mode |

YesNoIcon:

This icon shows a red x in a circle for prop of false and a green check in a circle for prop of true.

<YesNoIcon boolean={boolean} />

| Prop | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | boolean | Boolean | Optional | false | Flag that determines if the icon is in "yes" or "no" mode |

LabeledInput Component:

This takes the potentially large and oft-repeated Formik field input and simplifies it into a single React component.

import LabeledInput from "tbc-common-helpers/dist/LabeledInput";

 <LabeledInput
    name="title"
    title="Input Title"
    columnWidths={[6, 6]}
    formProps={formProps}
    {...props}
/>

| Prop | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | name | String | Required | "" | The field name, used by Formik | | title | String | Required* | "" | Text of the input label | | formProps | Object | Required | {} | Formik props passed into its form | | type | String | Optional | "input" | Type of input: "input" for text input field, and "select" for a drop down | | children | React.Component | Optional | null | If "select" type is chosen, this is the list of drop down option tags, typically using the <CommonDropDown /> component. Alternatively, this can be used with "input" type to render a custom input component. | | onChange | Function | Optional | formProps.handleChange() | Optional additional handleChange handler, beyond the one provided by Formik | | columnWidths | Array | Optional | [6 , 6] | The Bootstrap column widths of Label and Input (respectively) | | disabled | Boolean | Optional | false | Flag; if true, input is disabled | | required | Boolean | Optional | false | Flag; if true, the <RequiredIcon /> is displayed within the label, and the field become required| | warningMessage | String | Optional | "" | If provided, a <WarningIcon /> will be displayed in the label, with the message as its tooltip | | validate | Function | Optional | null | If required flag is set and the required validation is more than just whether or not a value is returned, this Function determines if requirements are met. Example: validate={() => isNumber(formProps.values.thisField())} If no validate function is provided, validation will be done on whether or not the field is populated. | | className | String | Optional | "" | Optional class names applied to entire input component | | fieldClassName | String | Optional | " | Optional class names applied only to input label |

MultiSelect Component:

MultiSelect is a specialized input select component that allows for multiple items within a drop down to be selected and displayed. It uses react-select as a foundation.

import MultiSelect from "tbc-common-helpers/dist/MultiSelect";

MultiSelect is placed within a Formik Field tag. NOTE: MultiSelect is not compatible with <LabeledInput />.

<Field
    name="title"
    value={formProps.values.title}
>
{field => (
    <MultiSelect
        {...field}
        optionList={optionList}
        onChange={sel => {
            formProps.setFieldValue("title", sel);
        }}
        {...props}
    />
)}
</Field>

| Prop | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | optionList | Array | Required | null | The array of input option objects; option objects should look like { value: item.cd, label: item.nm } | | onChange | Function | Required | null | onChange event (Formik default onChange event is not passed into MultiSelect) | | field | Object | Required | {} | Props passed from Formik Field component | | code | String | Optional | "cd" | By default, MultiSelect will use the "cd" key from the optionsList array as its value; use this prop if another key should be used | | name | String | Optional | "nm" | By default, MultiSelect will use the "nm" key from the optionsList array as its display name; use this prop if another key should be used | | closeMenuOnSelect | Boolean | Optional | false | If set to true, this flag causes the selection drop down to close upon a choice being made | | customClass | String | Optional | "" | Any custom classes to be used by the MultiSelect | | disabled | Boolean | Optional | false | Disabled flag |

NOTE:

The values returned by MultiSelect is an array of { value: item.cd, label: item.nm } objects (same format as the optionsList input).

CheckboxInput Component:

CheckboxInput

This is similar to LabeledInput except it provides a label and checkbox

import CheckboxInput from "tbc-common-helpers/dist/CheckboxInput";

 <CheckboxInput
    name="Checkbox"
    title="check"
    formProps={formProps}
    columnWidths={[6, 6]}
    isDisabled={isDisabled}
    isRequired={isRequired}
/>

| Prop | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | name | String | Required | "" | The field name, used by Formik | | title | String | Required | "" | Text of the input label | | formProps | Object | Required | {} | Formik props passed into its form | | columnWidths | Array | Optional | [6 , 6] | The Bootstrap column widths of Label and Input (respectively) | | isDisabled | Boolean | Optional | false | Flag; if true, input is disabled | | isRequired | Boolean | Optional | false | Flag; if true, the <RequiredIcon /> is displayed within the label, and the field become required|

Checkbox

This component also contains the stand-alone checkbox, which can be used separately from the label.

import { Checkbox } from "tbc-common-helpers/dist/CheckboxInput";

 <Checkbox
    title="check"
    formProps={formProps}
    isDisabled={isDisabled}
/>

| Prop | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | title | String | Required | "" | Text of the input label | | formProps | Object | Required | {} | Formik props passed into its form | | isDisabled | Boolean | Optional | false | Flag; if true, input is disabled |

DateTimeInput Component:

Date/Time input and label, using react-datepicker within Formik Field.

import DateTimeInput from "tbc-common-helpers/dist/DateTimeInput";

 <DateTimeInput
    name="datetime"
    title="Date/Time"
    formProps={formProps}
    columnWidths={[6, 6]}
    placeHolderText="Select Date and Time"
    isDisabled={isDisabled}
    isRequired={isRequired}
    fieldClass=""
    calendarClass=""
    visualDateFormat="MMMM d, yyyy h:mm aa"
    dataDateFormat="MM/DD/YYYY hh:mm A"
    showTimeSelect={showTimeSelect}
    timeIntervals={15}
    timeFormat="HH:mm"
    timeCaption="Time"
  />

| Prop | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | name | String | Required | "" | The field name, used by Formik | | title | String | Required | "" | Text of the input label | | formProps | Object | Required | {} | Formik props passed into its form | | columnWidths | Array | Optional | [6 , 6] | The Bootstrap column widths of Label and Input (respectively) | | placeHolderText | String | Optional | "" | Text that will appear in field until values are entered | | isDisabled | Boolean | Optional | false | Flag; if true, input is disabled | | isRequired | Boolean | Optional | false | Flag; if true, the <RequiredIcon /> is displayed within the label, and the field become required| | fieldClass | String | Optional | "" | Optional class names applied to input field | | calendarClass | String | Optional | "" | Optional class names applied to calendar popper | | visualDateFormat | String | Optional | "MMMM d, yyyy h:mm aa" | Optional format for date as displayed | | dataDateFormat | String | Optional | "MM/DD/YYYY hh:mm A" | Optional format for date used by data/form | | showTimeSelect | Boolean | Optional | true | Flag; if true, time selection is available | | timeIntervals | Number | Optional | 15 | Optional increments used by time selection | | timeFormat | String | Optional | "HH:mm" | Optional format for time in selection | | timeCaption | String | Optional | "Time" | Optional caption for time selection |

Edit/Save Component:

A single component that replaces need for separate "Edit" and "Save" buttons (displayed based on state). Button component with two states: a single button with text "Edit" and a pair of buttons for "Save" and "Cancel".

import EditSaveButton from "tbc-common-helpers/dist/EditSaveButton";

<EditSaveButton
  isDisabled={isDisabled}
  isSaveMode={toggleValue}
  toggleFunc={() => {
    toggleEditSave();
  }}
  saveFunc={() => {
    formProps.handleSubmit();
    toggleEditSave();
  }}
  cancelFunc={() => {
    formProps.handleReset();
    toggleEditSave();
  }}
  isSaveDisabled={isSaveDisabled}
  align={align}
/>

| Prop | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | isDisabled | Boolean | Optional | false | flag; if "true" then "Edit" mode is disabled | | isSaveMode | Boolean | Required | false | flag; if "true" then mode switches to "Save|Cancel" | | toggleFunc | Function | Required | () => {} | Function fired when "Edit" is pressed, typically switching the value provided to the "isSaveMode" prop | | saveFunc | Function | Required | () => {} | Function fired when "Save" is pressed; NOTE: this does not automatically fire toggleFunc, so that should be provided separately if desired | | cancelFunc | Function | Optional | same as toggleFunc | Function fired when "Save" is pressed; NOTE: if nothing is provided, then toggleFunc will be fired, but toggleFunc isn't fired automatically if a function is provided to the cancelFunc prop | | isSaveDisabled | Boolean | Optional | false | flag; if "true" then "Save" button is disabled | | align | String | Optional | "right" | "right" or "left"; the alignment of the buttons |

ConfirmationButton Component:

Button component with two states: a single button with customizable text and a pair of buttons for "Save" and "Cancel". Replaces the need for some confirmation modals.

import ConfirmationButton from "tbc-common-helpers/dist/ConfirmationButton";

<ConfirmationButton
  primaryButton={{      
    class: "btn-secondary",
    text: "Edit",
    icon: "far fa-edit",
    isDisabled: false
  }}
  confirmedFunc={confirmedFunc}
  message="Are you sure?"
  align="right"
/>

| Prop | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | primaryButton | Object | Required | {} | Object containing button class, text, icon, and isDisabled flag | | confirmedFunc | Function | Required | () => {} | Function fired upon confirmation | | message | String | Optional | "Confirm?" | Tooltip message explaining why there is a confirmation | | align | String | Optional | "right" | "right" or "left"; the alignment of the buttons |

InputWithButton Component:

Text input component with integration button.

import InputWithButton from "tbc-common-helpers/dist/InputWithButton";

<InputWithButton
  title="Input:"
  name="input"
  formProps={formProps}
  columnWidths={[6, 6]}
  isRequired={isRequired}
  buttonIcon={"fas fa-search"}
  buttonClass={"btn-primary"}
  buttonPosition={"end"}
  isButtonDisabled={!formProps.values.input}
  buttonFunction={() => {
    setModalOpen(true);
  }}
/>

| Prop | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | name | String | Required | "" | The field name, used by Formik | | title | String | Required | "" | Text of the input label | | formProps | Object | Required | {} | Formik props passed into its form | | columnWidths | Array | Optional | [6 , 6] | The Bootstrap column widths of Label and Input (respectively) | | isDisabled | Boolean | Optional | false | Flag; if true, input is disabled | | isRequired | Boolean | Optional | false | Flag; if true, the <RequiredIcon /> is displayed within the label, and the field become required | | buttonIcon | String | Optional | "fas fa-search" | Icon used by Button | | buttonClass | String | Optional | "btn-primary" | Class used by Button (beyond "btn") | | buttonPosition | String | Optional | "end" | Is button before ("start") or after ("end") text input field | | isButtonDisabled | Boolean | Optional | false | flag; If true button is disabled | | buttonFunction | Function | Required | () => {} | Function fired when button is pressed |

Required NPM Packages

npm install --save formik react-select react-datepicker lodash moment framer-motion

Testing

For any unit test file that deep renders ("mounts") this imported component, add the following:

jest.mock("tbc-common-helpers/dist/CommonDropDown", () => "div"); jest.mock("tbc-common-helpers/dist/Icons", () => "div"); jest.mock("tbc-common-helpers/dist/LabeledInput", () => "div"); jest.mock("tbc-common-helpers/dist/MultiSelect", () => "div"); jest.mock("tbc-common-helpers/dist/CheckboxInput", () => "div"); jest.mock("tbc-common-helpers/dist/DateTimeInput", () => "div"); jest.mock("tbc-common-helpers/dist/EditSaveButton", () => "div"); jest.mock("tbc-common-helpers/dist/ConfirmationButton", () => "div"); jest.mock("tbc-common-helpers/dist/InputWithButton", () => "div");

Changelog

• 0.3.0: Addition of CheckboxInput, DateTimeInput, EditSaveButton, ConfirmationButton, InputWithButton components
• 0.3.7: Updated Boolean naming convention in new components (to "isSomething" or "showSomething" instead of just "something")