@nypl/design-system-react-components 1.0.1 → 1.0.2

package/src/components/Radio/Radio.stories.mdx

@@ -0,0 +1,216 @@
+import { HStack } from "@chakra-ui/react";
+import {
+  ArgsTable,
+  Canvas,
+  Description,
+  Meta,
+  Story,
+} from "@storybook/addon-docs";
+import { withDesign } from "storybook-addon-designs";
+
+import Radio from "./Radio";
+import { getCategory } from "../../utils/componentCategories";
+import DSProvider from "../../theme/provider";
+
+<Meta
+  title={getCategory("Radio")}
+  component={Radio}
+  decorators={[withDesign]}
+  parameters={{
+    design: {
+      type: "figma",
+      url: "https://www.figma.com/file/qShodlfNCJHb8n03IFyApM/Master?node-id=11895%3A742",
+    },
+    jest: ["Radio.test.tsx"],
+  }}
+  argTypes={{
+    className: { control: false },
+    id: { control: false },
+    isChecked: { control: false },
+    isDisabled: {
+      table: { defaultValue: { summary: false } },
+    },
+    isInvalid: {
+      table: { defaultValue: { summary: false } },
+    },
+    isRequired: {
+      table: { defaultValue: { summary: false } },
+    },
+    key: { table: { disable: true } },
+    onChange: { control: false },
+    ref: { table: { disable: true } },
+    showHelperInvalidText: {
+      table: { defaultValue: { summary: true } },
+    },
+    showLabel: {
+      table: { defaultValue: { summary: true } },
+    },
+  }}
+/>
+
+# Radio
+
+| Component Version | DS Version |
+| ----------------- | ---------- |
+| Added             | `0.22.0`   |
+| Latest            | `1.0.2`    |
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Component Props](#component-props)
+- [Accessibility](#accessibility)
+- [Checked](#checked)
+- [Focused](#focused)
+- [Errored](#errored)
+- [Disabled](#disabled)
+- [Helper Text](#helper-text)
+- [Error Text](#error-text)
+- [With JSX Element Label](#with-jsx-element-label)
+
+## Overview
+
+<Description of={Radio} />
+
+This component renders a radio button form element. Note that all these examples
+show the `Radio` button in isolation. We recommend to always use the `Radio`
+component inside the Design System `RadioGroup` component. The `RadioGroup`
+component will handle all the states and data management.
+
+## Component Props
+
+<Canvas withToolbar>
+  <Story
+    name="Radio"
+    args={{
+      className: undefined,
+      helperText: "This is the helper text!",
+      id: "radio-id",
+      invalidText: "This is the error text :(",
+      isChecked: undefined,
+      isDisabled: false,
+      isInvalid: false,
+      isRequired: false,
+      labelText: "Test Label",
+      name: "test_name",
+      onChange: undefined,
+      showHelperInvalidText: true,
+      showLabel: true,
+      value: "1",
+    }}
+  >
+    {(args) => <Radio {...args} />}
+  </Story>
+</Canvas>
+
+<ArgsTable story="Radio" />
+
+## Accessibility
+
+The `Radio` component renders an `input` element with the `type="radio"` attribute.
+This HTML element is accessible by default.
+
+When `showLabel` is set to false, the `labelText` value will be set to the
+`<input>`'s `aria-label` attribute.
+
+Resources:
+
+- [W3C ARIA radiogroup and radio example](https://www.w3.org/TR/2016/WD-wai-aria-practices-1.1-20160317/examples/radio/radio.html)
+- [W3C Radio Button Example](https://www.w3.org/TR/2017/WD-wai-aria-practices-1.1-20170628/examples/radio/radio-1/radio-1.html)
+- [MDN input type="radio"](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/radio)
+- [Deque University Radio and Radio Group](https://dequeuniversity.com/library/aria/radio-and-radio-group)
+- [Chakra UI Radio](https://chakra-ui.com/docs/components/form/radio)
+
+## Checked
+
+<Canvas>
+  <DSProvider>
+    <Radio labelText="I am checked" id="checked" isChecked value="1" />
+  </DSProvider>
+</Canvas>
+
+## Focused
+
+<Canvas>
+  <DSProvider>
+    <Radio
+      id="focused"
+      labelText="Click or tab to the Radio to see its focus state"
+    />
+  </DSProvider>
+</Canvas>
+
+## Errored
+
+<Canvas>
+  <DSProvider>
+    <HStack>
+      <Radio id="invalid" isInvalid labelText="I am in an error state" />
+      <Radio
+        id="invalid-checked"
+        isInvalid
+        isChecked
+        labelText="I am checked in an error state"
+      />
+    </HStack>
+  </DSProvider>
+</Canvas>
+
+## Disabled
+
+<Canvas>
+  <DSProvider>
+    <HStack>
+      <Radio id="disabled" isDisabled labelText="I am disabled" />
+      <Radio
+        id="disabled-checked"
+        isDisabled
+        isChecked
+        labelText="I am checked and disabled"
+      />
+    </HStack>
+  </DSProvider>
+</Canvas>
+
+## Helper Text
+
+<Canvas>
+  <DSProvider>
+    <Radio
+      helperText="I am the helper text for this Radio"
+      id="help-text"
+      labelText="I have helper text"
+      name="testHelperText"
+    />
+  </DSProvider>
+</Canvas>
+
+## Error Text
+
+<Canvas>
+  <DSProvider>
+    <Radio
+      id="invalid-text"
+      invalidText="I am the error text for this Radio"
+      isInvalid
+      labelText="I have error text"
+      name="testErrorText"
+    />
+  </DSProvider>
+</Canvas>
+
+## With JSX Element Label
+
+This is useful when you want to add dynamic content to the label or add
+a layout to the label. View the `RadioGroup` documentation for this
+usage.
+
+<Canvas>
+  <DSProvider>
+    <Radio
+      id="jsx-label"
+      labelText={<span>Arts</span>}
+      name="jsxElementLabel"
+    />
+  </DSProvider>
+</Canvas>

package/src/components/Radio/Radio.test.tsx

@@ -0,0 +1,247 @@
+import { Flex, Spacer } from "@chakra-ui/react";
+import * as React from "react";
+import { render, screen } from "@testing-library/react";
+import { axe } from "jest-axe";
+import renderer from "react-test-renderer";
+
+import Radio from "./Radio";
+
+describe("Radio Accessibility", () => {
+  it("passes axe accessibility test with string label", async () => {
+    const { container } = render(<Radio id="inputID" labelText="Test Label" />);
+    expect(await axe(container)).toHaveNoViolations();
+  });
+
+  it("passes axe accessibility test with jsx label", async () => {
+    const { container } = render(
+      <Radio
+        id="jsxLabel"
+        labelText={
+          <Flex>
+            <span>Arts</span>
+            <Spacer />
+            <span>4</span>
+          </Flex>
+        }
+      />
+    );
+    expect(await axe(container)).toHaveNoViolations();
+  });
+});
+
+describe("Radio Button", () => {
+  it("renders with a radio input and label", () => {
+    render(<Radio id="inputID" labelText="Test Label" />);
+    expect(screen.getByLabelText("Test Label")).toBeInTheDocument();
+    expect(screen.getByRole("radio")).toBeInTheDocument();
+  });
+
+  it("renders with appropriate 'aria-label' attribute and value when 'showLabel' prop is set to false", () => {
+    render(<Radio id="inputID" labelText="Test Label" showLabel={false} />);
+    expect(screen.getByLabelText("Test Label")).toHaveAttribute(
+      "aria-label",
+      "Test Label"
+    );
+  });
+
+  it("renders with appropriate 'aria-label' attribute and value when 'showLabel' prop is set to false and 'helperText' has been passed", () => {
+    render(
+      <Radio
+        id="inputID"
+        labelText="Test Label"
+        showLabel={false}
+        helperText="This is the helper text."
+      />
+    );
+    expect(
+      screen.getByLabelText("Test Label - This is the helper text.")
+    ).toBeInTheDocument();
+  });
+
+  it("renders visible helper or error text", () => {
+    const { rerender } = render(
+      <Radio
+        id="inputID"
+        labelText="Test Label"
+        helperText="This is the helper text."
+        invalidText="This is the error text :("
+      />
+    );
+    expect(screen.getByText("This is the helper text.")).toBeVisible();
+    expect(
+      screen.queryByText("This is the error text :(")
+    ).not.toBeInTheDocument();
+
+    rerender(
+      <Radio
+        id="inputID"
+        labelText="Test Label"
+        isInvalid
+        helperText="This is the helper text."
+        invalidText="This is the error text :("
+      />
+    );
+    expect(screen.getByText("This is the error text :(")).toBeVisible();
+    expect(
+      screen.queryByText("This is the helper text.")
+    ).not.toBeInTheDocument();
+  });
+
+  it("sets the radio's ID", () => {
+    render(<Radio id="inputID" labelText="Test Label" />);
+    expect(screen.getByRole("radio")).toHaveAttribute("id", "inputID");
+  });
+
+  it("sets the 'checked' attribute", () => {
+    render(
+      <Radio
+        id="inputID-attributes"
+        labelText="onChange test"
+        showLabel
+        isChecked
+      />
+    );
+    expect(screen.getByRole("radio")).toHaveAttribute("checked");
+  });
+
+  it("sets the 'disabled' attribute", () => {
+    render(
+      <Radio
+        id="inputID-attributes"
+        labelText="onChange test"
+        showLabel
+        isDisabled
+      />
+    );
+    expect(screen.getByRole("radio")).toHaveAttribute("disabled");
+  });
+
+  it("sets the 'required' attribute", () => {
+    render(
+      <Radio
+        id="inputID-attributes"
+        labelText="onChange test"
+        showLabel
+        isRequired
+      />
+    );
+    expect(screen.getByRole("radio")).toHaveAttribute("required");
+  });
+
+  it("sets the error state", () => {
+    render(
+      <Radio
+        id="inputID-attributes"
+        labelText="onChange test"
+        showLabel
+        invalidText="There is an error!"
+        isInvalid
+      />
+    );
+    expect(screen.getByRole("radio")).toHaveAttribute("aria-invalid");
+    expect(screen.getByText("There is an error!")).toBeInTheDocument();
+  });
+
+  it("does not render the error text when 'showHelperInvalidText' is false", () => {
+    render(
+      <Radio
+        id="inputID-attributes"
+        labelText="onChange test"
+        showLabel
+        showHelperInvalidText={false}
+        isInvalid
+      />
+    );
+    expect(screen.getByRole("radio")).toHaveAttribute("aria-invalid");
+    expect(screen.queryByText("There is an error!")).not.toBeInTheDocument();
+  });
+
+  it("logs a warning if `labelText` is not a string and `showLabel` is false", () => {
+    const warn = jest.spyOn(console, "warn");
+    render(
+      <Radio
+        id="radio"
+        value="arts"
+        labelText={
+          <Flex>
+            <span>Arts</span>
+            <Spacer />
+            <span>4</span>
+          </Flex>
+        }
+        showLabel={false}
+      />
+    );
+
+    expect(warn).toHaveBeenCalledWith(
+      "NYPL Reservoir Radio: `labelText` must be a string when `showLabel` is false."
+    );
+  });
+
+  it("logs a warning when there is no `id` passed", () => {
+    const warn = jest.spyOn(console, "warn");
+    render(
+      // @ts-ignore: Typescript complains when a required prop is not passed, but
+      // here we don't want to pass the required prop to make sure the warning appears.
+      <Radio labelText="Arts" />
+    );
+    expect(warn).toHaveBeenCalledWith(
+      "NYPL Reservoir Radio: This component's required `id` prop was not passed."
+    );
+  });
+
+  it("renders the UI snapshot correctly", () => {
+    const primary = renderer
+      .create(<Radio id="inputID" labelText="Test Label" />)
+      .toJSON();
+    const isChecked = renderer
+      .create(<Radio id="radio-checked" labelText="Test Label" isChecked />)
+      .toJSON();
+    const isRequired = renderer
+      .create(<Radio id="radio-required" labelText="Test Label" isRequired />)
+      .toJSON();
+    const isInvalid = renderer
+      .create(<Radio id="radio-invalid" labelText="Test Label" isInvalid />)
+      .toJSON();
+    const isDisabled = renderer
+      .create(<Radio id="radio-disabled" labelText="Test Label" isDisabled />)
+      .toJSON();
+    const withJSXLabel = renderer
+      .create(
+        <Radio
+          id="jsxLabel"
+          labelText={
+            <Flex>
+              <span>Arts</span>
+              <Spacer />
+              <span>4</span>
+            </Flex>
+          }
+          value="arts"
+        />
+      )
+      .toJSON();
+    const withChakraProps = renderer
+      .create(
+        <Radio
+          id="chakra"
+          labelText="Test Label"
+          p="20px"
+          color="ui.error.primary"
+        />
+      )
+      .toJSON();
+    const withOtherProps = renderer
+      .create(<Radio id="props" labelText="Test Label" data-testid="props" />)
+      .toJSON();
+
+    expect(primary).toMatchSnapshot();
+    expect(isChecked).toMatchSnapshot();
+    expect(isRequired).toMatchSnapshot();
+    expect(isInvalid).toMatchSnapshot();
+    expect(isDisabled).toMatchSnapshot();
+    expect(withJSXLabel).toMatchSnapshot();
+    expect(withChakraProps).toMatchSnapshot();
+    expect(withOtherProps).toMatchSnapshot();
+  });
+});

package/src/components/Radio/Radio.tsx

@@ -0,0 +1,119 @@
+import {
+  chakra,
+  Radio as ChakraRadio,
+  useMultiStyleConfig,
+} from "@chakra-ui/react";
+import * as React from "react";
+
+import ComponentWrapper from "../ComponentWrapper/ComponentWrapper";
+import { HelperErrorTextType } from "../HelperErrorText/HelperErrorText";
+import { getAriaAttrs } from "../../utils/utils";
+
+export interface RadioProps {
+  /** Additional class name. */
+  className?: string;
+  /** Optional string to populate the HelperErrorText for the standard state. */
+  helperText?: HelperErrorTextType;
+  /** ID that other components can cross reference for accessibility purposes */
+  id: string;
+  /** Optional string to populate the HelperErrorText for the error state
+   * when `isInvalid` is true.
+   */
+  invalidText?: HelperErrorTextType;
+  /** When using the Radio as a "controlled" form element, you can specify the
+   * `Radio`'s checked state using this prop. You must also pass an onChange prop.
+   * Learn more about controlled and uncontrolled form fields: https://goshakkk.name/controlled-vs-uncontrolled-inputs-react/ */
+  isChecked?: boolean;
+  /** Adds the 'disabled' and `aria-disabled` attributes to the input when true.
+   * This also makes the text italic and color scheme gray. */
+  isDisabled?: boolean;
+  /** Adds the 'aria-invalid' attribute to the input when true. This also makes
+   * the color theme "NYPL error" red for the button and text. */
+  isInvalid?: boolean;
+  /** Adds the 'required' attribute to the input when true. */
+  isRequired?: boolean;
+  /** The radio button's label. This will serve as the text content for the
+   * `<label>` element if `showlabel` is true, or an "aria-label" if `showLabel`
+   * is false. */
+  labelText: string | JSX.Element;
+  /** Used to reference the input element in forms. */
+  name?: string;
+  /** Should be passed along with `isChecked` for controlled components. */
+  onChange?: (event: React.ChangeEvent<HTMLInputElement>) => void;
+  /** Offers the ability to hide the helper/invalid text. */
+  showHelperInvalidText?: boolean;
+  /** Offers the ability to show the radio's label onscreen or hide it. Refer
+   * to the `labelText` property for more information. */
+  showLabel?: boolean;
+  /** Populates the value of the input. */
+  value?: string;
+}
+
+export const Radio = chakra(
+  React.forwardRef<HTMLInputElement, RadioProps>((props, ref?) => {
+    const {
+      className,
+      helperText,
+      id,
+      invalidText,
+      isChecked,
+      isDisabled = false,
+      isInvalid = false,
+      isRequired = false,
+      labelText,
+      name,
+      onChange,
+      showHelperInvalidText = true,
+      showLabel = true,
+      value,
+      ...rest
+    } = props;
+    const styles = useMultiStyleConfig("Radio", {});
+    const footnote = isInvalid ? invalidText : helperText;
+    const ariaAttributes = getAriaAttrs({
+      footnote,
+      id,
+      labelText,
+      name: "Radio",
+      showLabel,
+    });
+
+    if (!id) {
+      console.warn(
+        "NYPL Reservoir Radio: This component's required `id` prop was not passed."
+      );
+    }
+
+    return (
+      <ComponentWrapper
+        helperText={helperText}
+        helperTextStyles={styles.helperErrorText}
+        id={id}
+        invalidText={invalidText}
+        isInvalid={isInvalid}
+        showHelperInvalidText={showHelperInvalidText}
+        {...rest}
+      >
+        <ChakraRadio
+          className={className}
+          id={id}
+          isChecked={isChecked}
+          isDisabled={isDisabled}
+          isInvalid={isInvalid}
+          isRequired={isRequired}
+          name={name}
+          onChange={onChange}
+          ref={ref}
+          value={value}
+          alignItems="flex-start"
+          __css={styles}
+          {...ariaAttributes}
+        >
+          {showLabel && labelText}
+        </ChakraRadio>
+      </ComponentWrapper>
+    );
+  })
+);
+
+export default Radio;