tbc-panda-helpers

TBC Common React App Helpers Modules

Helpers for all Trinidad Benham Panda React apps, including:

• CommonDropDown
• Icons
• LabeledInput
• MultiSelect
• CheckboxInput
• DateTimeInput
• EditSaveButton
• ConfirmationButton
• InputWithButton
• NumericInput

Install

npm install --save tbc-panda-helpers

Styles

As of version 0.4.0, to use any of the components included in this module, the following style file will need to be imported/included into the main App.scss:

@import "tbc-panda-helpers/dist/styles/header.scss";

If the DateTimeInput is to be included in your app, add the following to index.js along with other third party style inclusions:

import "react-datepicker/dist/react-datepicker.css";

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-panda-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"}
placeHolderTest	String	Optional	null	Text of a default placeholder value for drop downs; appears at top of list if enabled. Uses class placeHolder-text which can be defined in CSS for optional styling

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-panda-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-panda-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
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)
isDisabled	Boolean	Optional	false	Flag; if true, input is disabled
disabled	Boolean	Optional	null	DEPRECIATED; alias for isDisabled Flag
isRequired	Boolean	Optional	false	Flag; if true, the <RequiredIcon /> is displayed within the label, and the field become required
required	Boolean	Optional	null	DEPRECIATED; alias for isRequird Flag;
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.
hasValidationSchema	Boolean	Optional	false	Flag; if true, assumes parent Formik form is using validationSchema for validation; this validationSchema will take precedence over validate or required parameters; required parameter is still necessary for display of fields that are required (or have other validations)
fieldClass	String	Optional	""	Optional class names applied to entire input component
className	String	Optional	null	DEPRECIATED; alias for fieldClass parameter
inputFieldClass	String	Optional	""	Optional class names applied only to input element
fieldClassName	String	Optional	null	DEPRECIATED; alias for inputFieldClass paramater
customErrorObject	Object	Optional	{}	Object used to define if tooltip error indicator is used instead of below-field Alert. Parameters are: useTooltip Boolean flag, customErrorClass String used to define which class(es) are applied to errored fields (defaults to internal class "default-error-border") , and placement String for Tooltip position (defaults to "left")

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-panda-helpers/dist/MultiSelect";

  <MultiSelect
    formProps={formProps}
    title="MultiSelect Values:"
    name="multiSelectValues"
    columnWidths={[12, 12]}
    optionList={options.map(item => {
      return { value: item.cd, label: item.nm };
    })}
    onChange={sel => {
      console.log("selection:", sel);
      formProps.setFieldValue("multiSelectValues", sel);
    }}
    closeMenuOnSelect
    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
optionList	Array	Required**	null	The array of input option objects; option objects should look like { value: item.cd, label: item.nm }
onChange	Function	Optional	null	onChange event (Formik default onChange event is not passed into MultiSelect)
closeMenuOnSelect	Boolean	Optional	false	If set to true, this flag causes the selection drop down to close upon a choice being made
fieldClass	String	Optional	""	Any custom classes to be used by the MultiSelect component (overall)
inputFieldClass	String	Optional	""	Any custom classes to be used in just the input element
isDisabled	Boolean	Optional	false	Disabled flag
isRequired	Boolean	Optional	false	Flag; if true, the <RequiredIcon /> is displayed within the label, and the field become required
customErrorObject	Object	Optional	{}	Object used to define if tooltip error indicator is used instead of below-field Alert. Parameters are: useTooltip Boolean flag, customErrorClass String used to define which class(es) are applied to errored fields (defaults to internal class "default-error-border") , and placement String for Tooltip position (defaults to "left")

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-panda-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
fieldClass	String	Optional	""	Optional class names applied to input field
onChange	Function	Optional	formProps.handleChange()	Optional additional handleChange handler, beyond the one provided by Formik
value	Boolean	Optional	undefined	Value of checkbox; if none provided, will use formProps.values instead

Checkbox

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

import { Checkbox } from "tbc-panda-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
onChange	Function	Optional	null	onChange event (Formik default onChange event is not passed into MultiSelect)

DateTimeInput Component:

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

import DateTimeInput from "tbc-panda-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
customErrorObject	Object	Optional	{}	Object used to define if tooltip error indicator is used instead of below-field Alert. Parameters are: useTooltip Boolean flag, customErrorClass String used to define which class(es) are applied to errored fields (defaults to internal class "default-error-border") , and placement String for Tooltip position (defaults to "left")

NOTE: Additional props can be passed into DateTimeInput, and they will pass as is into DatePicker within.

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-panda-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
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
isIconOnly	Boolean	Optional	false	flag; if "true" then text is removed and only icons display; changes width from 160px to 70px
iconSize	String	Optional	"lg"	Used only if isIconOnly flag is true; sets icon size based on FontAwesome icon sizing convention ("lg", "2x", etc)
primaryButton	Object	Optional	{class: "info", text: "Edit", icon: "far fa-edit"}	Optional object containing "edit" button's class, text, and iconvalues

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-panda-helpers/dist/ConfirmationButton";

<ConfirmationButton
  primaryButton={{      
    class: "btn-main",
    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-panda-helpers/dist/InputWithButton";

<InputWithButton
  title="Input:"
  name="input"
  formProps={formProps}
  columnWidths={[6, 6]}
  isRequired={isRequired}
  buttonIcon={"fas fa-search"}
  buttonClass={"btn-prime"}
  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)
fieldClass	String	Optional	""	Optional class names applied to input field
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-prime"	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

NumericInput Component:

Input component for numeric input only.

NOTE: This is more robust than using type="number" within LabeledInput.

import NumericInput from "tbc-panda-helpers/dist/NumericInput";

<NumericInput
  name="number"
  title="Number:"
  formProps={formProps}
  columnWidths={[6, 6]}
  isDisabled={demoFlag}
/>

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)
fieldClass	String	Optional	""	Optional class names applied to input field
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
validationMessage	String	Optional	""	If prop contains a value, message will be displayed beneath field (same styles as Required alert)
allowNegative	Boolean	Optional	true	Flag; if false, negative values are disallowed
showThousandSeparator	Boolean	Optional	true	Flag; if false then comma thousand separator is not displayed
isFixedDecimalScale	Boolean	Optional	false	Flag; if true then all values will contain number of significant digits as defined in decimalScale prop
decimalScale	Number	Optional	0	Number of significant digits any value in field will be rounded to
onChange	Function	Optional	null	Function called onChange; if nothing provided, then default formProps onChange will be called
units	String	Optional	null	If provided, then will be displayed as an addendum or prepended to input field
isPrependedUnits	Boolean	Optional	false	Flag; if true then units will be displayed before input field; otherwise, will be displayed after
customErrorObject	Object	Optional	{}	Object used to define if tooltip error indicator is used instead of below-field Alert. Parameters are: useTooltip Boolean flag, customErrorClass String used to define which class(es) are applied to errored fields (defaults to internal class "default-error-border") , and placement String for Tooltip position (defaults to "left")
value	Boolean	Number	undefined	Value of field; if none provided, will use formProps.values instead

Required NPM Packages

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

Testing

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

jest.mock("tbc-panda-helpers/dist/CommonDropDown", () => "div"); jest.mock("tbc-panda-helpers/dist/Icons", () => "div"); jest.mock("tbc-panda-helpers/dist/LabeledInput", () => "div"); jest.mock("tbc-panda-helpers/dist/MultiSelect", () => "div"); jest.mock("tbc-panda-helpers/dist/CheckboxInput", () => "div"); jest.mock("tbc-panda-helpers/dist/DateTimeInput", () => "div"); jest.mock("tbc-panda-helpers/dist/EditSaveButton", () => "div"); jest.mock("tbc-panda-helpers/dist/ConfirmationButton", () => "div"); jest.mock("tbc-panda-helpers/dist/InputWithButton", () => "div"); jest.mock("tbc-panda-helpers/dist/NumericInput", () => "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")
• 0.4.2: Added NumericInput
• 0.5.0: Updated MultiSelect to match other inputs; improvements to NumericInput
• 0.5.1: Added onChange prop option to CheckboxInput
• 0.5.3: LabeledInput now functions with Formik/Yup validationSchema; uses both isRequired/isDisabled and required/disabled (depreciated) params
• 0.5.6: Alternate error display option added (customErrorObject; generates Tooltip instead of Alert)
• 0.5.9: Added isIconOnly flag to Save/Edit Button
• 0.5.12: Added iconSize field to icon only Save/Edit button
• 0.5.15: Added optional primaryButton param to Save/Edit button
• 0.5.16: Allow 0 in NumericInput required fields; also disabled autocomplete in DateTimeInput
• 0.5.17: Added placeHolderText to CommonDropDown