tbc-panda-helpers

v0.5.17

Published

3 years ago

Helpers for all Trinidad Benham Panda React apps, including:

Downloads

0High
0Medium
0Low

rwood

rbrianredd

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
  />

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}
/>

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|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 | | 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);
  }}
/>

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