@thecb/components 12.0.0-beta.0 → 12.0.0-beta.2

package/src/components/atoms/form-layouts/FormTextarea.js

@@ -0,0 +1,207 @@
+import React from "react";
+import styled, { css } from "styled-components";
+import { fallbackValues } from "./FormLayouts.theme.js";
+import { themeComponent } from "../../../util/themeUtils";
+import { createIdFromString } from "../../../util/general.js";
+import Text from "../text";
+import { Box, Cluster, Stack } from "../layouts";
+import { FONT_WEIGHT_REGULAR } from "../../../constants/style_constants";
+import { ERROR_COLOR, ROYAL_BLUE } from "../../../constants/colors";
+
+const TextareaField = styled.textarea`
+  border: 1px solid
+    ${({ field, showErrors, themeValues }) =>
+      (field.dirty && field.hasErrors) || (field.hasErrors && showErrors)
+        ? ERROR_COLOR
+        : themeValues.borderColor};
+  border-radius: 2px;
+  height: ${({ $customHeight }) => ($customHeight ? $customHeight : "auto")};
+  width: 100%;
+  padding: 1rem;
+  min-width: 100px;
+  margin: 0;
+  box-sizing: border-box;
+  position: relative;
+  font-size: 1.1rem;
+  font-family: Public Sans;
+  line-height: 1.5rem;
+  font-weight: ${FONT_WEIGHT_REGULAR};
+  background-color: ${({ themeValues }) =>
+    themeValues.inputBackgroundColor && themeValues.inputBackgroundColor};
+  color: ${({ themeValues }) => themeValues.color && themeValues.color};
+  box-shadow: none;
+  resize: ${({ resize }) => resize || "vertical"};
+  transition: background 0.3s ease;
+
+  &:focus {
+    outline: 3px solid ${ROYAL_BLUE};
+    outline-offset: 2px;
+  }
+
+  ${({ disabled }) =>
+    disabled &&
+    css`
+      color: #6e727e;
+      background-color: #f7f7f7;
+    `}
+
+  ${({ $extraStyles }) =>
+    css`
+      ${$extraStyles}
+    `}
+`;
+
+const FormTextarea = ({
+  ariaLabelledBy = undefined,
+  labelDisplayOverride = null,
+  labelTextWhenNoError = "",
+  errorMessages,
+  helperModal = false,
+  field,
+  fieldActions,
+  showErrors,
+  themeValues,
+  customHeight,
+  extraStyles,
+  removeFromValue, // regex of characters to remove before setting value
+  dataQa = null,
+  isRequired = false,
+  errorFieldExtraStyles,
+  showFieldErrorRow = true,
+  labelTextVariant = "pS",
+  errorTextVariant = "pXS",
+  resize = "vertical", // none, horizontal, vertical, both
+  rows = 5,
+  cols,
+  placeholder,
+  maxLength,
+  ...props
+}) => {
+  const setValue = value => {
+    if (removeFromValue !== undefined) {
+      return fieldActions.set(value.replace(removeFromValue, ""));
+    }
+    return fieldActions.set(value);
+  };
+
+  return (
+    <Stack childGap="0.25rem">
+      <Box padding="0">
+        {helperModal ? (
+          <Cluster justify="space-between" align="center">
+            {labelDisplayOverride ? (
+              labelDisplayOverride
+            ) : (
+              <Text
+                as="label"
+                color={themeValues.labelColor}
+                variant={labelTextVariant}
+                weight={themeValues.fontWeight}
+                extraStyles={`word-break: break-word;
+                  font-family: Public Sans;
+                  &::first-letter {
+                    text-transform: uppercase;
+                  }`}
+                id={createIdFromString(labelTextWhenNoError)}
+              >
+                {labelTextWhenNoError}
+              </Text>
+            )}
+            {helperModal()}
+          </Cluster>
+        ) : (
+          <Box padding="0" minWidth="100%">
+            <Cluster justify="space-between" align="center">
+              {labelDisplayOverride ? (
+                labelDisplayOverride
+              ) : (
+                <Text
+                  as="label"
+                  color={themeValues.labelColor}
+                  variant={labelTextVariant}
+                  fontWeight={themeValues.fontWeight}
+                  extraStyles={`word-break: break-word;
+                    font-family: Public Sans;
+                    &::first-letter {
+                      text-transform: uppercase;
+                    }`}
+                  id={createIdFromString(labelTextWhenNoError)}
+                >
+                  {labelTextWhenNoError}
+                </Text>
+              )}
+            </Cluster>
+          </Box>
+        )}
+      </Box>
+      <Box padding="0">
+        <TextareaField
+          aria-labelledby={
+            ariaLabelledBy === undefined
+              ? createIdFromString(labelTextWhenNoError)
+              : ariaLabelledBy
+          }
+          aria-describedby={createIdFromString(
+            labelTextWhenNoError,
+            "error message"
+          )}
+          aria-invalid={
+            (field.dirty && field.hasErrors) || (field.hasErrors && showErrors)
+          }
+          onChange={e => setValue(e.target.value)}
+          value={field.rawValue}
+          field={field}
+          showErrors={showErrors}
+          themeValues={themeValues}
+          $customHeight={customHeight}
+          $extraStyles={extraStyles}
+          data-qa={dataQa || labelTextWhenNoError}
+          required={isRequired}
+          resize={resize}
+          rows={rows}
+          cols={cols}
+          placeholder={placeholder}
+          maxLength={maxLength}
+          {...props}
+        />
+      </Box>
+      {showFieldErrorRow && (
+        <Stack
+          direction="row"
+          justify="space-between"
+          aria-live="polite"
+          aria-atomic={true}
+        >
+          {(field.hasErrors && field.dirty) ||
+          (field.hasErrors && showErrors) ? (
+            <Text
+              color={ERROR_COLOR}
+              variant={errorTextVariant}
+              weight={themeValues.fontWeight}
+              extraStyles={`word-break: break-word;
+              font-family: Public Sans;
+              &::first-letter {
+                text-transform: uppercase;
+              }
+              ${errorFieldExtraStyles};`}
+              id={createIdFromString(labelTextWhenNoError, "error message")}
+            >
+              {errorMessages[field.errors[0]]}
+            </Text>
+          ) : (
+            <Text
+              extraStyles={`height: ${themeValues.lineHeight}; ${errorFieldExtraStyles};`}
+            />
+          )}
+        </Stack>
+      )}
+    </Stack>
+  );
+};
+
+export default themeComponent(
+  FormTextarea,
+  "FormTextarea",
+  fallbackValues,
+  "default"
+);

package/src/components/atoms/form-layouts/FormTextarea.mdx

@@ -0,0 +1,48 @@
+import { Canvas, Meta, Title, Story, Controls } from '@storybook/blocks';
+
+import * as FormTextareaStories from './FormTextarea.stories.js';
+
+<Meta of={FormTextareaStories} />
+
+<Title />
+
+FormTextarea is a wrapper for `<textarea/>` elements that adds extra functionality. It is meant to be used in forms for multi-line text input. The underlying component is a `textarea` element with additional form integration and styling. Additional props are passed down to the underlying element.
+
+## Form Integration
+
+FormTextarea requires a `field` and `fieldActions` prop. Both are objects that _can_ be generated with [redux-freeform](https://github.com/CityBaseInc/redux-freeform). Below are example values for each prop with the minimum properties needed for a FormTextarea component.
+
+### field
+
+```
+{
+  "dirty": false,
+  "rawValue": "",
+  "errors": [
+    "error/REQUIRED"
+  ],
+  "hasErrors": true
+}
+```
+
+### fieldActions
+
+```
+{
+  set: (value) => {...}
+}
+```
+
+`fieldActions.set()` is called when the textarea value changes.
+
+## Textarea-Specific Features
+
+FormTextarea includes several features specific to textarea elements:
+
+- **Resize Control**: Use the `resize` prop to control how users can resize the textarea (`"none"`, `"horizontal"`, `"vertical"`, or `"both"`)
+- **Rows and Columns**: Set initial size with `rows` and `cols` props
+- **Character Limit**: Use `maxLength` to limit the number of characters
+- **Placeholder Text**: Provide helpful placeholder text with the `placeholder` prop
+- **Custom Height**: Override the default height with the `customHeight` prop
+
+<Controls />

package/src/components/atoms/form-layouts/FormTextarea.stories.js

@@ -0,0 +1,265 @@
+import React, { useState } from "react";
+import FormTextarea from "./FormTextarea";
+import { connect, Provider } from "react-redux";
+import { createStore } from "redux";
+import { createFormState, required } from "redux-freeform";
+import Modal from "../../molecules/modal";
+
+const { mapStateToProps, mapDispatchToProps, reducer } = createFormState({
+  example: {
+    validators: [required()]
+  }
+});
+
+const store = createStore(
+  reducer,
+  window.__REDUX_DEVTOOLS_EXTENSION__ && window.__REDUX_DEVTOOLS_EXTENSION__()
+);
+
+const errorMessages = {
+  [required.error]: "This is required!"
+};
+
+const FormWrapper = props => (
+  <FormTextarea
+    {...props}
+    field={props.fields.example}
+    fieldActions={props.actions.fields.example}
+  />
+);
+
+const ConnectedFormTextarea = connect(
+  mapStateToProps,
+  mapDispatchToProps
+)(FormWrapper);
+
+export default {
+  title: "Atoms/form-layouts/FormTextarea",
+  component: ConnectedFormTextarea,
+  tags: ["!autodocs"],
+  parameters: {
+    layout: "centered",
+    controls: { expanded: true }
+  },
+  args: {
+    labelTextWhenNoError: "",
+    errorMessages: errorMessages,
+    helperModal: undefined,
+    showErrors: undefined,
+    themeValues: {},
+    customHeight: undefined,
+    extraStyles: undefined,
+    removeFromValue: undefined,
+    dataQa: "form-textarea-qa",
+    isRequired: false,
+    resize: "vertical",
+    rows: 5,
+    cols: undefined,
+    placeholder: "",
+    maxLength: undefined
+  },
+  argTypes: {
+    extraStyles: { type: "string" },
+    fieldActions: { type: "object" },
+    field: { type: "object" },
+    isRequired: {
+      description: "adds the `required` attribute to the textarea element",
+      table: {
+        type: { summary: "boolean" },
+        defaultValue: { summary: false }
+      }
+    },
+    customHeight: {
+      description: "sets a height to the textarea",
+      table: {
+        type: { summary: "string" },
+        defaultValue: { summary: "120px" }
+      }
+    },
+    helperModal: {
+      description: "a function that returns a modal",
+      table: {
+        type: { summary: "object" },
+        defaultValue: { summary: undefined }
+      }
+    },
+    removeFromValue: {
+      description:
+        "regex pattern for characters to remove from the user inputted value before passing it to `fieldActions.set()`",
+      table: {
+        type: { summary: "string" },
+        defaultValue: { summary: undefined }
+      }
+    },
+    extraStyles: {
+      description: "styles applied to the underlying textarea element",
+      table: {
+        type: { summary: "string" },
+        defaultValue: { summary: undefined }
+      }
+    },
+    resize: {
+      description: "controls how the textarea can be resized",
+      control: {
+        type: "select",
+        options: ["none", "horizontal", "vertical", "both"]
+      },
+      table: {
+        type: { summary: "string" },
+        defaultValue: { summary: "vertical" }
+      }
+    },
+    rows: {
+      description: "number of visible text lines for the textarea",
+      table: {
+        type: { summary: "number" },
+        defaultValue: { summary: 5 }
+      }
+    },
+    cols: {
+      description: "visible width of the textarea",
+      table: {
+        type: { summary: "number" },
+        defaultValue: { summary: undefined }
+      }
+    },
+    placeholder: {
+      description: "placeholder text for the textarea",
+      table: {
+        type: { summary: "string" },
+        defaultValue: { summary: "" }
+      }
+    },
+    maxLength: {
+      description: "maximum number of characters allowed",
+      table: {
+        type: { summary: "number" },
+        defaultValue: { summary: undefined }
+      }
+    }
+  },
+  decorators: [
+    Story => (
+      <Provider store={store}>
+        <Story />
+      </Provider>
+    )
+  ]
+};
+
+export const Basic = args => <ConnectedFormTextarea {...args} />;
+
+export const WithLabel = {
+  args: {
+    labelTextWhenNoError: "Description"
+  },
+  render: args => <ConnectedFormTextarea {...args} />
+};
+
+export const WithPlaceholder = {
+  args: {
+    labelTextWhenNoError: "Comments",
+    placeholder: "Enter your comments here..."
+  },
+  render: args => <ConnectedFormTextarea {...args} />
+};
+
+export const WithCustomHeight = {
+  args: {
+    labelTextWhenNoError: "Message",
+    customHeight: "200px"
+  },
+  render: args => <ConnectedFormTextarea {...args} />
+};
+
+export const Required = {
+  args: {
+    labelTextWhenNoError: "Required Field",
+    isRequired: true
+  },
+  render: args => <ConnectedFormTextarea {...args} />
+};
+
+export const NoResize = {
+  args: {
+    labelTextWhenNoError: "Fixed Size",
+    resize: "none"
+  },
+  render: args => <ConnectedFormTextarea {...args} />
+};
+
+export const HorizontalResize = {
+  args: {
+    labelTextWhenNoError: "Horizontal Resize",
+    resize: "horizontal"
+  },
+  render: args => <ConnectedFormTextarea {...args} />
+};
+
+export const BothResize = {
+  args: {
+    labelTextWhenNoError: "Both Directions",
+    resize: "both"
+  },
+  render: args => <ConnectedFormTextarea {...args} />
+};
+
+export const WithMaxLength = {
+  args: {
+    labelTextWhenNoError: "Limited Text",
+    maxLength: 100,
+    placeholder: "Maximum 100 characters"
+  },
+  render: args => <ConnectedFormTextarea {...args} />
+};
+
+export const CustomRows = {
+  args: {
+    labelTextWhenNoError: "Many Rows",
+    rows: 10
+  },
+  render: args => <ConnectedFormTextarea {...args} />
+};
+
+export const Disabled = {
+  args: {
+    disabled: true
+  },
+  render: args => <ConnectedFormTextarea {...args} />
+};
+
+const TextareaWithModal = props => {
+  const [isOpen, toggleOpen] = useState(false);
+
+  return (
+    <ConnectedFormTextarea
+      {...props}
+      helperModal={() => (
+        <Modal
+          modalOpen={isOpen}
+          hideModal={() => toggleOpen(false)}
+          showModal={() => toggleOpen(true)}
+          modalHeaderText="Help with this field"
+          modalBodyText="This textarea is for entering detailed information. You can use multiple lines and resize as needed."
+          defaultWrapper={false}
+          onlyCloseButton={true}
+          initialFocusSelector=""
+        >
+          <div onClick={() => toggleOpen(true)} role="button">
+            Help!
+          </div>
+        </Modal>
+      )}
+    />
+  );
+};
+
+export const WithHelperModal = {
+  args: {
+    labelTextWhenNoError: "Description"
+  },
+  argTypes: {
+    helperModal: { type: "function" }
+  },
+  render: args => <TextareaWithModal {...args} />
+};

package/src/components/atoms/form-layouts/index.d.ts

@@ -19,14 +19,47 @@ export interface FormInputProps {
   showErrors?: boolean;
   type?: string;
   formatter?: string | null;
-  decorator?: boolean;
+  decorator?: string;
   themeValues?: object;
   background?: string;
   customHeight?: string;
   autocompleteValue?: string;
   removeFromValue?: RegExp;
   dataQa?: string | null;
+  isRequired?: boolean;
+  errorFieldExtraStyles?: string;
+  showFieldErrorRow?: boolean;
+  labelTextVariant?: string;
+  errorTextVariant?: string;
 }
 
 export const FormInput: React.FC<Expand<FormInputProps> &
   React.HTMLAttributes<HTMLElement>>;
+
+export interface FormTextareaProps {
+  extraStyles?: string;
+  field?: Field;
+  fieldActions?: FieldActions;
+  disabled?: boolean;
+  errorMessages?: ErrorMessageDictionary;
+  helperModal?: boolean;
+  labelTextWhenNoError?: string;
+  showErrors?: boolean;
+  themeValues?: object;
+  customHeight?: string;
+  removeFromValue?: RegExp;
+  dataQa?: string | null;
+  isRequired?: boolean;
+  errorFieldExtraStyles?: string;
+  showFieldErrorRow?: boolean;
+  labelTextVariant?: string;
+  errorTextVariant?: string;
+  resize?: "none" | "horizontal" | "vertical" | "both";
+  rows?: number;
+  cols?: number;
+  placeholder?: string;
+  maxLength?: number;
+}
+
+export const FormTextarea: React.FC<Expand<FormTextareaProps> &
+  React.HTMLAttributes<HTMLTextAreaElement>>;

package/src/components/atoms/form-layouts/index.js

@@ -3,11 +3,13 @@ import FormInputRow from "./FormInputRow";
 import FormInputColumn from "./FormInputColumn";
 import FormContainer from "./FormContainer";
 import FormFooterPanel from "./FormFooterPanel";
+import FormTextarea from "./FormTextarea";
 
 export {
   FormInput,
   FormInputRow,
   FormInputColumn,
   FormContainer,
-  FormFooterPanel
+  FormFooterPanel,
+  FormTextarea
 };

package/src/components/atoms/form-select/FormSelect.js

@@ -25,7 +25,9 @@ const FormSelect = ({
   smoothScroll = true, // whether the browser should animate scroll to selected item on first open
   dataQa = null,
   widthFitOptions = false,
-  isRequired = false
+  isRequired = false,
+  labelTextVariant = "pS",
+  errorLabelTextVariant = "pXS"
 }) => {
   const [open, setOpen] = useState(false);
   const dropdownRef = useRef(null);
@@ -54,7 +56,7 @@ const FormSelect = ({
         <Cluster justify="space-between" align="center">
           <Text
             as="label"
-            variant="pS"
+            variant={labelTextVariant}
             color={themeValues.labelColor}
             weight={themeValues.fontWeight}
             extraStyles={`word-break: break-word;
@@ -101,7 +103,7 @@ const FormSelect = ({
         {(field.hasErrors && field.dirty) || (field.hasErrors && showErrors) ? (
           <Text
             color={ERROR_COLOR}
-            variant="pXS"
+            variant={errorLabelTextVariant}
             weight={themeValues.fontWeight}
             extraStyles={`
             word-break: break-word;

package/src/components/atoms/form-select/FormSelect.mdx

@@ -0,0 +1,42 @@
+import { Canvas, Meta, Title, Story, Controls } from '@storybook/blocks';
+
+import * as FormSelectStories from './FormSelect.stories.js';
+
+<Meta of={FormSelectStories} />
+
+<Title />
+
+FormSelect is a wrapper for the [Dropdown component](?path=/docs/atoms-dropdown--docs) meant to be used in forms.
+
+It controls the open state of the menu (including closing on mouse clicks outside of the component). It also renders an accesible label and error messages.
+
+FormSelect can be used with [redux-freeform](https://github.com/CityBaseInc/redux-freeform) to connect the form to Redux state.
+
+<Story />
+
+## Form Integration
+
+FormSelect requires a `field` and `fieldActions` prop. Both are objects that _can_ be generated with [redux-freeform](https://github.com/CityBaseInc/redux-freeform). Below are example values for each prop with the minimum properties needed for a FormSelect component.
+
+### field
+
+```
+{
+  "dirty": false,
+  "rawValue": "",
+  "errors": [
+    "error/REQUIRED"
+  ],
+  "hasErrors": true
+}
+```
+
+### fieldActions
+
+```
+{
+  set: (value) => {...}
+}
+```
+
+`fieldActions.set()` is called when an option is selected in the underlying Dropdown component, unless a function is defined for the `onChange` prop.