@nypl/design-system-react-components 0.23.4 → 0.25.1

package/src/components/TextInput/TextInput.tsx

@@ -1,99 +1,111 @@
 import * as React from "react";
-import bem from "../../utils/bem";
-import { TextInputTypes, TextInputFormats } from "./TextInputTypes";
+import {
+  Box,
+  Input as ChakraInput,
+  Textarea as ChakraTextarea,
+  useMultiStyleConfig,
+} from "@chakra-ui/react";
+
+import {
+  TextInputTypes,
+  TextInputFormats,
+  TextInputVariants,
+} from "./TextInputTypes";
 import Label from "../Label/Label";
 import HelperErrorText from "../HelperErrorText/HelperErrorText";
 import generateUUID from "../../helpers/generateUUID";
 
 export interface InputProps {
-  /** Additional attributes to pass to the `<input>` tag */
+  /** Additional attributes to pass to the `<input>` or `<textarea>` element */
   attributes?: { [key: string]: any };
-  /** HTML Input types as defined by MDN: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input */
-  type?: TextInputTypes;
-  /** Will add 'aria-required: true' to input */
-  required?: boolean;
-  /** Provides text for a `Label` component if `showLabel` is set to true; populates a `aria-label` sttribute if `showLabel` is set to false. */
-  labelText: string;
-  /** Offers the ability to show the label onscreen or hide it. Refer to the `labelText` property for more information. */
-  showLabel?: boolean;
-  /** Populates the HelperErrorText for standard state */
-  helperText?: string;
-  /** Populates the HelperErrorText for error state */
-  errorText?: string;
-  /** Populates the placeholder of the input */
-  placeholder?: string;
-  /** Populates the value of the input */
-  value?: string;
-  /** className you can add in addition to 'textinput' */
+  /** A class name for the TextInput parent div. */
   className?: string;
+  /** Populates the HelperErrorText for the standard state */
+  helperText?: string;
   /** ID that other components can cross reference for accessibility purposes */
   id?: string;
-  /** Helper for modifiers array; adds 'errored' styling */
-  errored?: boolean;
-  /** Adds the 'disabled' prop to the input when true */
-  disabled?: boolean;
-  /** Modifiers array for use with BEM. See how to work with modifiers and BEM here: http://getbem.com/introduction/ */
-  modifiers?: string[];
-  /** The action to perform on the `<input>`'s onChange function  */
+  /** Populates the HelperErrorText for the error state */
+  invalidText?: string;
+  /** Adds the `disabled` and `aria-disabled` prop to the input when true */
+  isDisabled?: boolean;
+  /** Adds errored styling to the input/textarea and helper text elements */
+  isInvalid?: boolean;
+  /** Will add `required` and `aria-required` props to the input/textarea elements */
+  isRequired?: boolean;
+  /** Provides text for a `Label` component if `showLabel` is set to true;
+   * populates an `aria-label` attribute if `showLabel` is set to false. */
+  labelText: string;
+  /** The action to perform on the `input`/`textarea`'s onChange function  */
   onChange?: (
     event:
       | React.ChangeEvent<HTMLInputElement>
       | React.ChangeEvent<HTMLTextAreaElement>
   ) => void;
+  /** Populates the placeholder for the input/textarea elements */
+  placeholder?: string;
+  /** Offers the ability to show the label onscreen or hide it. Refer to the
+   * `labelText` property for more information. */
+  showLabel?: boolean;
+  /** Offers the ability to show the "Required"/"Optional" label onscreen or
+   * hide it. True by default. */
+  showOptReqLabel?: boolean;
+  /** HTML Input types as defined by MDN: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input */
+  type?: TextInputTypes;
+  /** Populates the value of the input/textarea elements */
+  value?: string;
+  /** The variant to display. */
+  variantType?: TextInputVariants;
 }
 
-/** The type used for `ref`s. We want to extend both `input` and `textarea`
+/**
+ * The type used for `ref`s. We want to extend both `input` and `textarea`
  * since both are available to create through `TextInput`.
  */
 export type TextInputRefType = HTMLInputElement & HTMLTextAreaElement;
 
-/** Renders either an `input` element with a specified type or a `textarea`
- * element. All types will render an accessible Label component and an optional
- * HelperErrorText component.
+/**
+ * Renders either an `input` element with a specified type or a `textarea`
+ * element. All types will render an accessible `Label` component and an
+ * optional `HelperErrorText` component.
  */
 const TextInput = React.forwardRef<TextInputRefType, InputProps>(
   (props, ref: React.Ref<TextInputRefType>) => {
     const {
       attributes = {},
-      type = TextInputTypes.text,
-      required,
-      labelText,
-      showLabel = true,
+      className,
       helperText,
-      errorText,
+      id = generateUUID(),
+      invalidText,
+      isDisabled = false,
+      isInvalid = false,
+      isRequired = false,
+      labelText,
+      onChange,
       placeholder,
+      showLabel = true,
+      showOptReqLabel = true,
+      type = TextInputTypes.text,
       value,
-      className,
-      disabled,
-      errored,
-      onChange,
-      modifiers = [],
-      id = generateUUID(),
+      variantType = TextInputVariants.Default,
     } = props;
-
+    const styles = useMultiStyleConfig("TextInput", { variant: variantType });
     const isTextArea = type === TextInputTypes.textarea;
     const isHidden = type === TextInputTypes.hidden;
-    const optReqFlag = required ? "Required" : "Optional";
-    const errorOutput = errorText
-      ? errorText
+    const optReqFlag = isRequired ? "Required" : "Optional";
+    const finalInvalidText = invalidText
+      ? invalidText
       : "There is an error related to this field.";
-    let footnote;
+    let footnote: string | React.ReactNode = isInvalid
+      ? finalInvalidText
+      : helperText;
+    let fieldOutput;
     let options;
 
-    if (!showLabel) attributes["aria-label"] = labelText;
-    if (helperText) attributes["aria-describedby"] = helperText;
-
-    if (errored) {
-      modifiers.push("error");
-    }
-    if (isTextArea) {
-      modifiers.push("textarea");
-    }
-
-    if (errored) {
-      footnote = errorOutput;
-    } else {
-      footnote = helperText;
+    if (!showLabel) {
+      attributes["aria-label"] =
+        labelText && footnote ? `${labelText} - ${footnote}` : labelText;
+    } else if (helperText) {
+      attributes["aria-describedby"] = `${id}-helperText`;
     }
 
     if (
@@ -111,50 +123,55 @@ const TextInput = React.forwardRef<TextInputRefType, InputProps>(
       );
     }
 
-    options = {
-      id,
-      className: bem("inputfield", modifiers, "", [className]),
-      "aria-required": required,
-      "aria-hidden": isHidden,
-      disabled,
-      required,
-      placeholder,
-      onChange,
-      ref,
-      ...attributes,
-    };
+    // When the type is "hidden", the input element needs fewer attributes.
+    options = isHidden
+      ? { id, "aria-hidden": isHidden, onChange, ref }
+      : {
+          id,
+          "aria-required": isRequired,
+          isDisabled,
+          isRequired,
+          isInvalid,
+          placeholder,
+          onChange,
+          ref,
+          ...attributes,
+        };
     // For `input` and `textarea`, all attributes are the same but `input`
     // also needs `type` and `value` to render correctly.
     if (!isTextArea) {
       options = { type, value, ...options } as any;
+      fieldOutput = <ChakraInput {...options} __css={styles.input} />;
+    } else {
+      fieldOutput = (
+        <ChakraTextarea {...options} __css={styles.textarea}>
+          {value}
+        </ChakraTextarea>
+      );
     }
 
-    const fieldOutput = React.createElement(
-      isTextArea ? "textarea" : "input",
-      options,
-      isTextArea ? value : null
-    );
-
-    const transformedInput = (
-      <div className="textinput">
+    return (
+      <Box __css={styles} className={className}>
         {labelText && showLabel && !isHidden && (
-          <Label htmlFor={id} optReqFlag={optReqFlag} id={id + `-label`}>
+          <Label
+            htmlFor={id}
+            optReqFlag={showOptReqLabel && optReqFlag}
+            id={`${id}-label`}
+          >
             {labelText}
           </Label>
         )}
         {fieldOutput}
-        {((helperText && !isHidden) || errored) && (
-          <HelperErrorText isError={errored} id={id + `-helperText`}>
-            {footnote}
-          </HelperErrorText>
+        {footnote && !isHidden && (
+          <Box __css={styles.helper} aria-disabled={isDisabled}>
+            <HelperErrorText isError={isInvalid} id={`${id}-helperText`}>
+              {footnote}
+            </HelperErrorText>
+          </Box>
         )}
-      </div>
+      </Box>
     );
-
-    return transformedInput;
   }
 );
 
-TextInput.displayName = "TextInput";
-
 export default TextInput;

package/src/components/TextInput/TextInputTypes.tsx

@@ -23,6 +23,12 @@ export enum TextInputFormats {
   url = "https://domain.com",
 }
 
+export enum TextInputVariants {
+  Default = "default",
+  SearchBar = "searchBar",
+  SearchBarSelect = "searchBarSelect",
+}
+
 /*
 export enum TextInputPatterns {
   // eslint-disable-next-line prettier/prettier

package/src/components/VideoPlayer/VideoPlayer.stories.mdx

@@ -11,9 +11,10 @@ import { withDesign } from "storybook-addon-designs";
 import VideoPlayer from "./VideoPlayer";
 import { VideoPlayerTypes } from "./VideoPlayerTypes";
 import { action } from "@storybook/addon-actions";
+import { getCategory } from "../../utils/componentCategories";
 
 <Meta
-  title="VideoPlayer"
+  title={getCategory("VideoPlayer")}
   component={VideoPlayer}
   decorators={[withDesign]}
   parameters={{

package/src/components/VideoPlayer/VideoPlayer.tsx

@@ -2,7 +2,7 @@ import * as React from "react";
 import bem from "../../utils/bem";
 import { VideoPlayerAspectRatios, VideoPlayerTypes } from "./VideoPlayerTypes";
 import Heading from "../Heading/Heading";
-// import { HeadingDisplaySizes } from "../Heading/HeadingDisplaySizes";
+import { HeadingLevels } from "../Heading/HeadingTypes";
 import HelperErrorText from "../HelperErrorText/HelperErrorText";
 
 export interface VideoPlayerProps {
@@ -105,7 +105,9 @@ export default function VideoPlayer(
         <span dangerouslySetInnerHTML={{ __html: errorMessage }} />
       ) : (
         <>
-          {headingText && <Heading level={2} text={headingText} />}
+          {headingText && (
+            <Heading level={HeadingLevels.Two} text={headingText} />
+          )}
           {descriptionText && <p>{descriptionText}</p>}
           <div className={bem("video-player__inside", modifiers, "", [])}>
             {embedCode}

package/src/components/VideoPlayer/_VideoPlayer.scss

@@ -14,7 +14,7 @@
     }
 
     &--errored {
-      background-color: var(--ui-gray-warm-light);
+      background-color: var(--ui-gray-light-warm);
       height: auto;
       padding: var(--space-s);
     }

package/src/docs/Chakra.stories.mdx

@@ -0,0 +1,341 @@
+import { Meta } from "@storybook/addon-docs/blocks";
+
+<Meta title="Chakra UI" />
+
+# Chakra UI
+
+| Table of Contents                   |
+| ----------------------------------- |
+| 1. [Why Chakra UI?](#why-chakra-ui) |
+| 2. [DSProvider](#dsprovider)        |
+| 3. [Components](#components)        |
+| 4. [Styling](#styling)              |
+| 5. [Testing](#testing)              |
+
+## Why Chakra UI?
+
+The NYPL Design System (DS) project was influenced by other design systems but
+ultimately we decided to initially build DS components from scratch rather than
+use another design system as its foundation. To better help all the projects at
+NYPL and to better scale with all the components we have built and still need to
+build, we decided to integrate Chakra UI into the NYPL Design System.
+
+Chakra UI is an open source component library that is opinionated and uses design
+and development patterns that various projects at NYPL use. Since the NYPL DS
+will be the foundation for all NYPL projects moving forward, using Chakra will
+help us align all projects so similar patterns are used throughout various teams
+and projects.
+
+Chakra follows WAI-ARIA and WCAG 2.1 standards and guidelines which aligns with
+the standards that NYPL follows for its own components and applications.
+
+With design and development consistency, the ability to customize components
+_if necessary_, and accessibility standards in place, developers at NYPL using
+the Design System will be able to build out applications faster.
+
+We recommend to read Chakra's own [documentation](https://chakra-ui.com/docs/getting-started)
+to get up to speed on it. This file will provide information on how it is used
+in the DS but we rely on Chakra's documentation.
+
+## DSProvider
+
+While the Chakra UI integration into the DS is a work-in-progress, there is one
+necessary step consuming applications need to take for component styles to
+properly render. Consuming applications need to wrap all the DS components with
+a simple provider component. Fortunately, this only needs to be done once at
+the top level of the consuming application.
+
+Once the following is completed, DS components that internally use Chakra UI
+will render styles properly. Internally, the `DSProvider` is built on top of
+Chakra's `ChakraProvider` with NYPL's custom theme.
+
+```jsx
+// your main application file
+import { DSProvider } from "@nypl/design-system-react-components";
+
+// ...
+const Application = (props) => {
+  // ...
+  return (
+    <DSProvider>
+      <header>...</header>
+      <div className="my-app nypl-ds">
+        // ...
+        {children}
+      </div>
+      <footer>...</footer>
+    </DSProvider>
+  );
+};
+```
+
+### Chakra Components in Storybook
+
+Storybook is configured to use the `DSProvider` so that components can render
+appropriately. Unfortunately, this only works within the `Story` component.
+When rendering components in documentation examples within a `Canvas` component,
+wrap the elements in the `DSProvider` component.
+
+```jsx
+// These buttons are not a part of a "story" but still appear only
+// in the documentation.
+<Canvas>
+  <DSProvider>
+    <ButtonGroup>
+      <Button disabled={false}>Enabled</Button>
+      <Button disabled={true}>Disabled</Button>
+    </ButtonGroup>
+  </DSProvider>
+</Canvas>
+```
+
+## Components
+
+The current work-in-progress is to use Chakra components to compose DS
+components that align directly or to compose DS-specific components with Chakra.
+For example, both the DS and Chakra have a `Button` component so we will use
+Chakra's `Button` component to compose the DS `Button` component. However, the
+DS has a `Hero` component that is not already built by Chakra. In this case,
+the DS `Hero` component will internally use `Chakra` components.
+
+### Components Composed with Chakra
+
+While we can directly use Chakra components that align with DS components, we
+want to compose DS components using the Chakra component as a base instead. This
+pattern allows the Design System to have control over props and standard styles.
+
+These components composed from Chakra, therefore, do not have all styled props
+available. For example, whereas `m` (`margin`), `mr` (`marginright`), and similar
+props can be used in Chakra components, those props are not available for DS
+components that internally are composed with Chakra components.
+
+Components built from Chakra rename the component with the `Chakra` name prefix.
+
+```jsx
+import { Tabs as ChakraTabs, useStyleConfig } from "@chakra-ui/react";
+```
+
+In this example, the `ChakraTabs` component is returned with NYPL specific
+functionality, styles, and other requirements.
+
+```jsx
+function Tabs(props) {
+  // ...
+  const styles = useStyleConfig("Tabs", { variant: props.tabsType });
+
+  return (
+    <ChakraTabs
+      id={id}
+      __css={styles}
+      // ... other props
+    >
+      {children}
+    </ChakraTabs>
+}
+```
+
+#### Patterns
+
+The NYPL DS uses the [CSS BEM](http://getbem.com/introduction/) pattern to structure
+and write CSS. We are moving away from this and re-writing SCSS classes into
+Javascript objects that work with Chakra's theme. Instead of creating a variant
+for a component with a class name, now the `type` prop is used. Internally, the
+`type` prop will be mapped to a Chakra theme variant that will provide all the
+necessary styles.
+
+For the `Button` component, for example, we would convert a SCSS class rule such
+as `.button-outline` to a Javascript object (more on this in the [Anatomy of a
+Component Styling Object](#anatomy-of-a-component-styling-object) section).
+
+### Components re-exported from Chakra
+
+Some components are directly exported from Chakra. These components can be found
+in the `/src/index.ts` file. Note that not _all_ Chakra components are re-exported
+because we want to limit what developers should use in consuming applications.
+
+Note: These components are harder to have snapshot tests for because, internally,
+these components autogenerate ids and class names on every new render. We can't
+override them so snapshot tests will fail.
+
+## Styling
+
+As mentioned in the [Components composed with Chakra](#components-composed-with-chakra)
+section, we are moving away from using the BEM structure to using Javascript objects
+to extend Chakra's theme.
+
+The NYPL DS' theme file can be found at `src/theme/index.ts`. This creates a new
+theme that extends Chakra's theme and is set in the `DSProvider` component. Note
+that the example below is the general structure of the `theme` object but the DS
+`theme` object has values already set so it may look different. You would generally
+only work and add new object values in the `components` attribute for new
+components and their theme or variants.
+
+```jsx
+const theme = extendTheme({
+  styles: { ... },
+  breakpoints: { ... },
+  colors: { ... },
+  typography: { ... },
+  space: { ... },
+  components: {
+    Button,
+    // ...
+  },
+});
+```
+
+### Anatomy of a Component Styling Object
+
+For in-depth information, read Chakra's [Component Style documentation](https://chakra-ui.com/docs/theming/component-style).
+
+Component theme files can be found in the `src/theme/components/` directory.
+Here is an example using the `Button` component.
+
+```jsx
+// The basic structure for all component style objects.
+const Button = {
+  baseStyle: {},
+  sizes: {},
+  variants: {},
+  defaultProps: {},
+};
+```
+
+A current variant class rule can be converted to a Javascript object and go in
+the `variants` object as in the following example.
+
+```jsx
+// Button.scss
+// This is the "Secondary" variant.
+.button--outline {
+  @include button-base;
+
+  background-color: var(--ui-white);
+  border: 1px solid var(--ui-gray-light-cool);
+  color: inherit;
+
+  &:hover {
+    background-color: var(--ui-gray-xx-light-cool);
+  }
+}
+
+// Button.ts
+const Button = {
+  baseStyles: { ... },
+  sizes: { ... },
+  variants: {
+    secondary: {
+      bg: "ui.white",
+      border: "1px solid",
+      borderColor: "ui.gray.light-cool",
+      color: "inherit",
+      _hover: {
+        bg: "ui.gray.xx-light-cool",
+      },
+    },
+    // ... other variants,
+  },
+  defaultProps: { ... },
+};
+```
+
+Now this variant can be rendered:
+
+```jsx
+<Button buttonType={ButtonTypes.Secondary}>Press me</Button>
+```
+
+### Breakpoints
+
+TODO:
+
+### Colors
+
+All available colors can be found in `src/theme/foundations/colors.ts`. Chakra
+autogenerates the `colors` object into CSS variables. We will rely on these
+variables rather than creating our own.
+
+```jsx
+const colors: Colors = {
+  // ui fills
+  ui: {
+    /// State and link utilities
+    focus: "#4181F1",
+    link: {
+      primary: "#0576D3",
+      secondary: "#004B98",
+    },
+    // ...
+  },
+  section: {
+    /** What's On is used for Exhibitions & Events. */
+    "whats-on": {
+      primary: "#242424",
+      secondary: "#000000",
+    },
+  },
+  // ...
+};
+```
+
+In the shorten object example above, the following will be generated by Chakra:
+
+| Theme object value                     | CSS variable                                 |
+| -------------------------------------- | -------------------------------------------- |
+| `colors.ui.focus`                      | `--chakra-colors-ui-focus`                   |
+| `colors.ui.link.primary`               | `--chakra-colors-ui-link-primary`            |
+| `colors.ui.link.secondary`             | `--chakra-colors-ui-link-secondary`          |
+| `colors.section["whats-on"].primary`   | `--chakra-colors-section-whats-on-primary`   |
+| `colors.section["whats-on"].secondary` | `--chakra-colors-section-whats-on-secondary` |
+
+The current prefix is `--chakra` but we expect to update that soon. DS specified
+CSS variables are still exported but we will remove those in favor of the CSS
+variables provided by Chakra for ease of use.
+
+Note: while each Chakra color has number range values from 50 to 900 (such as
+`red.400`, `blue.600`, etc) and each one is based on the color coming from
+DS' Figma documentation, we recommend NOT to use them.
+
+### Spacing
+
+All the spacing values can be found in the `src/theme/foundations/spacing.ts`
+file. While Chakra provides many values, only use the eight DS defined values.
+
+| Chakra Value | DS Variable |
+| ------------ | ----------- |
+| 1            | --space-xxs |
+| 2            | --space-xs  |
+| 4            | --space-s   |
+| 6            | --space-m   |
+| 8            | --space-l   |
+| 12           | --space-xl  |
+| 16           | --space-xxl |
+| 24           | --space-xxl |
+
+For example, to make all `button`s have a `padding: 8px 16px` value:
+
+```jsx
+// src/theme/components/button.ts
+const Button = {
+  baseStyle: {
+    py: 2, // var(--space-xs) which results in a value of 8px or 0.5rem
+    px: 4, // var(--space-s) which results in a value of 16px or 1rem
+    // ... other styles
+  },
+  sizes: { ... },
+  variants: { ... },
+  defaultProps: { ... },
+};
+```
+
+### Typography
+
+All typography values can be found in the `src/theme/foundations/typography.ts`
+file. These values declare the font family, font sizes, and font weights to use
+for all text.
+
+## Testing
+
+Do not re-test Chakra components that are re-exported since they are already
+tested in the `@chakra-ui/react` package. We do expect all new components composed
+from Chakra to have tests for functionality and styling (such as snapshots).