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

package/src/components/Radio/Radio.tsx

@@ -1,108 +1,109 @@
 import * as React from "react";
-import bem from "../../utils/bem";
-import HelperErrorText from "../HelperErrorText/HelperErrorText";
-import Label from "../Label/Label";
+import {
+  Box,
+  Radio as ChakraRadio,
+  useMultiStyleConfig,
+} from "@chakra-ui/react";
+
 import generateUUID from "../../helpers/generateUUID";
+import HelperErrorText from "../HelperErrorText/HelperErrorText";
 
 export interface RadioProps {
-  /** The radio button's label.  This will serve as the text content for a `<label>` element if `showlabel` is true, or an "aria-label" if `showLabel` is false. */
-  labelText: string;
-  /** Additional attributes to pass to the `<input>` tag */
-  attributes?: { [key: string]: any };
-  /** When using the Radio as a "controlled" form element, you can specify the Radio's checked state using this prop. Learn more about controlled and uncontrolled form fields: https://goshakkk.name/controlled-vs-uncontrolled-inputs-react/ */
-  checked?: boolean;
-  /** className you can add in addition to 'input' */
+  /** Additional class name. */
   className?: string;
-  /** Adds the 'disabled' prop to the input when true */
-  disabled?: boolean;
-  /** Helper for modifiers array; adds 'errored' styling */
-  errored?: boolean;
-  /** Optional string to populate the HelperErrorText for error state */
-  errorText?: string;
-  /** Optional string to populate the HelperErrorText for standard state */
+  /** Optional string to populate the HelperErrorText for the error state
+   * when `isInvalid` is true.
+   */
+  invalidText?: string;
+  /** Optional string to populate the HelperErrorText for the standard state. */
   helperText?: string;
   /** ID that other components can cross reference for accessibility purposes */
   id?: string;
-  /** Modifiers array for use with BEM. See how to work with modifiers and BEM here: http://getbem.com/introduction/ */
-  modifiers?: string[];
-  /** The name prop indicates into which group of radios this radio belongs.  If none is specified, 'default' will be used */
+  /** 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;
+  /** Used to reference the input element in forms. */
   name?: string;
-  /** The action to perform on the `<input>`'s onChange function  */
+  /** Should be passed along with `isChecked` for controlled components. */
   onChange?: (event: React.ChangeEvent<HTMLInputElement>) => void;
-  /** 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 */
+  /** 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 onChangeDefault = () => {
-  return;
-};
-
 const Radio = React.forwardRef<HTMLInputElement, RadioProps>((props, ref?) => {
   const {
-    checked,
     className,
-    disabled,
-    errored,
-    errorText,
+    invalidText,
     helperText,
-    id,
+    id = generateUUID(),
+    isChecked,
+    isDisabled = false,
+    isInvalid = false,
+    isRequired = false,
     labelText,
     name,
-    showLabel,
+    onChange,
+    showLabel = true,
     value,
   } = props;
-
-  const attributes = props.attributes || {};
-  const modifiers = props.modifiers ? props.modifiers : [];
-  const radioID = id || generateUUID();
-  const onChange = props.onChange || onChangeDefault;
-
-  const footnote = errored ? errorText : helperText;
+  const styles = useMultiStyleConfig("Radio", {});
+  const footnote = isInvalid ? invalidText : helperText;
+  const attributes = {};
 
   if (!showLabel) {
     attributes["aria-label"] =
       labelText && footnote ? `${labelText} - ${footnote}` : labelText;
   } else {
-    if (footnote) attributes["aria-describedby"] = `${radioID}-helperText`;
-  }
-
-  if (errored) {
-    modifiers.push("error");
+    if (footnote) {
+      attributes["aria-describedby"] = `${id}-helperText`;
+    }
   }
 
   return (
     <>
-      <input
-        {...(checked !== undefined
-          ? {
-              checked: checked,
-              onChange: onChange,
-            }
-          : {
-              defaultChecked: false,
-            })}
-        className={bem("radio", modifiers, "", [className])}
-        disabled={disabled}
-        id={radioID}
-        name={name || "default"}
-        ref={ref}
-        type="radio"
-        value={value}
+      <ChakraRadio
+        className={className}
+        id={id}
+        isChecked={isChecked}
+        isDisabled={isDisabled}
+        isInvalid={isInvalid}
+        isRequired={isRequired}
+        name={name}
         onChange={onChange}
+        value={value}
+        ref={ref}
+        __css={styles}
         {...attributes}
-      />
-      {labelText && showLabel && <Label htmlFor={radioID}>{labelText}</Label>}
+      >
+        {showLabel && labelText}
+      </ChakraRadio>
       {footnote && showLabel && (
-        <HelperErrorText isError={errored} id={id + `-helperText`}>
-          {footnote}
-        </HelperErrorText>
+        <Box __css={styles.helper} aria-disabled={isDisabled}>
+          <HelperErrorText isError={isInvalid} id={`${id}-helperText`}>
+            {footnote}
+          </HelperErrorText>
+        </Box>
       )}
     </>
   );
 });
 
-Radio.displayName = "Radio";
-
 export default Radio;

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

@@ -0,0 +1,250 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`Radio Button renders the UI snapshot correctly 1`] = `
+<label
+  className="chakra-radio css-78joka"
+>
+  <input
+    checked={false}
+    className="chakra-radio__input"
+    disabled={false}
+    id="inputID"
+    onBlur={[Function]}
+    onChange={[Function]}
+    onFocus={[Function]}
+    onKeyDown={[Function]}
+    onKeyUp={[Function]}
+    required={false}
+    style={
+      Object {
+        "border": "0px",
+        "clip": "rect(0px, 0px, 0px, 0px)",
+        "height": "1px",
+        "margin": "-1px",
+        "overflow": "hidden",
+        "padding": "0px",
+        "position": "absolute",
+        "whiteSpace": "nowrap",
+        "width": "1px",
+      }
+    }
+    type="radio"
+  />
+  <span
+    aria-hidden={true}
+    className="css-ssalds"
+    onMouseDown={[Function]}
+    onMouseEnter={[Function]}
+    onMouseLeave={[Function]}
+    onMouseUp={[Function]}
+  />
+  <span
+    className="chakra-radio__label css-1y8kf23"
+    onMouseDown={[Function]}
+    onTouchStart={[Function]}
+  >
+    Test Label
+  </span>
+</label>
+`;
+
+exports[`Radio Button renders the UI snapshot correctly 2`] = `
+<label
+  className="chakra-radio css-78joka"
+>
+  <input
+    checked={true}
+    className="chakra-radio__input"
+    disabled={false}
+    id="radio-checked"
+    onBlur={[Function]}
+    onChange={[Function]}
+    onFocus={[Function]}
+    onKeyDown={[Function]}
+    onKeyUp={[Function]}
+    required={false}
+    style={
+      Object {
+        "border": "0px",
+        "clip": "rect(0px, 0px, 0px, 0px)",
+        "height": "1px",
+        "margin": "-1px",
+        "overflow": "hidden",
+        "padding": "0px",
+        "position": "absolute",
+        "whiteSpace": "nowrap",
+        "width": "1px",
+      }
+    }
+    type="radio"
+  />
+  <span
+    aria-hidden={true}
+    className="css-ssalds"
+    data-checked=""
+    onMouseDown={[Function]}
+    onMouseEnter={[Function]}
+    onMouseLeave={[Function]}
+    onMouseUp={[Function]}
+  />
+  <span
+    className="chakra-radio__label css-1y8kf23"
+    data-checked=""
+    onMouseDown={[Function]}
+    onTouchStart={[Function]}
+  >
+    Test Label
+  </span>
+</label>
+`;
+
+exports[`Radio Button renders the UI snapshot correctly 3`] = `
+<label
+  className="chakra-radio css-78joka"
+>
+  <input
+    aria-required={true}
+    checked={false}
+    className="chakra-radio__input"
+    disabled={false}
+    id="radio-required"
+    onBlur={[Function]}
+    onChange={[Function]}
+    onFocus={[Function]}
+    onKeyDown={[Function]}
+    onKeyUp={[Function]}
+    required={true}
+    style={
+      Object {
+        "border": "0px",
+        "clip": "rect(0px, 0px, 0px, 0px)",
+        "height": "1px",
+        "margin": "-1px",
+        "overflow": "hidden",
+        "padding": "0px",
+        "position": "absolute",
+        "whiteSpace": "nowrap",
+        "width": "1px",
+      }
+    }
+    type="radio"
+  />
+  <span
+    aria-hidden={true}
+    className="css-ssalds"
+    onMouseDown={[Function]}
+    onMouseEnter={[Function]}
+    onMouseLeave={[Function]}
+    onMouseUp={[Function]}
+  />
+  <span
+    className="chakra-radio__label css-1y8kf23"
+    onMouseDown={[Function]}
+    onTouchStart={[Function]}
+  >
+    Test Label
+  </span>
+</label>
+`;
+
+exports[`Radio Button renders the UI snapshot correctly 4`] = `
+<label
+  className="chakra-radio css-78joka"
+>
+  <input
+    aria-invalid={true}
+    checked={false}
+    className="chakra-radio__input"
+    disabled={false}
+    id="radio-invalid"
+    onBlur={[Function]}
+    onChange={[Function]}
+    onFocus={[Function]}
+    onKeyDown={[Function]}
+    onKeyUp={[Function]}
+    required={false}
+    style={
+      Object {
+        "border": "0px",
+        "clip": "rect(0px, 0px, 0px, 0px)",
+        "height": "1px",
+        "margin": "-1px",
+        "overflow": "hidden",
+        "padding": "0px",
+        "position": "absolute",
+        "whiteSpace": "nowrap",
+        "width": "1px",
+      }
+    }
+    type="radio"
+  />
+  <span
+    aria-hidden={true}
+    className="css-ssalds"
+    data-invalid=""
+    onMouseDown={[Function]}
+    onMouseEnter={[Function]}
+    onMouseLeave={[Function]}
+    onMouseUp={[Function]}
+  />
+  <span
+    className="chakra-radio__label css-1y8kf23"
+    data-invalid=""
+    onMouseDown={[Function]}
+    onTouchStart={[Function]}
+  >
+    Test Label
+  </span>
+</label>
+`;
+
+exports[`Radio Button renders the UI snapshot correctly 5`] = `
+<label
+  className="chakra-radio css-78joka"
+>
+  <input
+    aria-disabled={true}
+    checked={false}
+    className="chakra-radio__input"
+    disabled={true}
+    id="radio-disabled"
+    onBlur={[Function]}
+    onChange={[Function]}
+    onFocus={[Function]}
+    onKeyDown={[Function]}
+    onKeyUp={[Function]}
+    required={false}
+    style={
+      Object {
+        "border": "0px",
+        "clip": "rect(0px, 0px, 0px, 0px)",
+        "height": "1px",
+        "margin": "-1px",
+        "overflow": "hidden",
+        "padding": "0px",
+        "position": "absolute",
+        "whiteSpace": "nowrap",
+        "width": "1px",
+      }
+    }
+    type="radio"
+  />
+  <span
+    aria-hidden={true}
+    className="css-ssalds"
+    data-disabled=""
+    onMouseDown={[Function]}
+    onMouseEnter={[Function]}
+    onMouseLeave={[Function]}
+    onMouseUp={[Function]}
+  />
+  <span
+    className="chakra-radio__label css-1y8kf23"
+    data-disabled=""
+    onMouseDown={[Function]}
+    onTouchStart={[Function]}
+  >
+    Test Label
+  </span>
+</label>
+`;

package/src/components/RadioGroup/RadioGroup.stories.mdx

@@ -0,0 +1,247 @@
+import {
+  Meta,
+  Story,
+  Canvas,
+  ArgsTable,
+  Preview,
+  Description,
+} from "@storybook/addon-docs/blocks";
+import { withDesign } from "storybook-addon-designs";
+
+import { getCategory } from "../../utils/componentCategories";
+import DSProvider from "../../theme/provider";
+import RadioGroup, { onChangeDefault } from "./RadioGroup";
+import { RadioGroupLayoutTypes } from "./RadioGroupLayoutTypes";
+import Radio from "../Radio/Radio";
+
+<Meta
+  title={getCategory("RadioGroup")}
+  component={RadioGroup}
+  decorators={[withDesign]}
+  parameters={{
+    design: {
+      type: "figma",
+      url:
+        "https://www.figma.com/file/qShodlfNCJHb8n03IFyApM/Main?node-id=11895%3A742",
+    },
+    jest: ["RadioGroup.test.tsx"],
+  }}
+  argTypes={{
+    children: { table: { disable: true } },
+    className: { table: { disable: true } },
+    onChange: { table: { disable: true } },
+    id: { table: { disable: true } },
+  }}
+/>
+
+# RadioGroup
+
+| Component Version | DS Version |
+| ----------------- | ---------- |
+| Added             | `0.25.0`   |
+| Latest            | `0.25.0`   |
+
+<Description of={RadioGroup} />
+
+<Preview withToolbar>
+  <Story
+    name="RadioGroup"
+    args={{
+      defaultValue: "4",
+      invalidText: "error!",
+      helperText: "This is the helper text for the full group.",
+      isDisabled: false,
+      isInvalid: false,
+      isRequired: false,
+      labelText: "Standard Radio Group",
+      layout: RadioGroupLayoutTypes.Column,
+      name: "radio-story",
+      optReqFlag: true,
+      showLabel: true,
+    }}
+  >
+    {(args) => (
+      <RadioGroup {...args}>
+        <Radio value="2" labelText="Radio 2" />
+        <Radio value="3" labelText="Radio 3" />
+        <Radio value="4" labelText="Radio 4" />
+        <Radio value="5" labelText="Radio 5" />
+      </RadioGroup>
+    )}
+  </Story>
+</Preview>
+
+<ArgsTable story="RadioGroup" />
+
+## Layout Patterns
+
+Use the `layout` prop to set the `Radio` buttons to display in a column or in
+a row.
+
+<Canvas>
+  <DSProvider>
+    <RadioGroup
+      labelText="Column (default)"
+      name="column-example"
+      optReqFlag={false}
+    >
+      <Radio value="2" labelText="Radio 2" />
+      <Radio value="3" labelText="Radio 3" />
+      <Radio value="4" labelText="Radio 4" />
+      <Radio value="5" labelText="Radio 5" />
+    </RadioGroup>
+    <br />
+    <RadioGroup
+      labelText="Row"
+      name="row-example"
+      layout={RadioGroupLayoutTypes.Row}
+      optReqFlag={false}
+    >
+      <Radio value="2" labelText="Radio 2" />
+      <Radio value="3" labelText="Radio 3" />
+      <Radio value="4" labelText="Radio 4" />
+      <Radio value="5" labelText="Radio 5" />
+    </RadioGroup>
+  </DSProvider>
+</Canvas>
+
+## Errored
+
+<Canvas>
+  <DSProvider>
+    <RadioGroup
+      labelText="Errored Radio Group"
+      name="errored-example"
+      optReqFlag={false}
+      invalidText="Error message for the full group."
+      isInvalid
+    >
+      <Radio value="2" labelText="Radio 2" />
+      <Radio value="3" labelText="Radio 3" />
+      <Radio value="4" labelText="Radio 4" />
+      <Radio value="5" labelText="Radio 5" />
+    </RadioGroup>
+  </DSProvider>
+</Canvas>
+
+## Disabled
+
+<Canvas>
+  <DSProvider>
+    <RadioGroup
+      labelText="Disabled Radio Group"
+      name="disabled-example"
+      optReqFlag={false}
+      helperText="The reason for being disabled."
+      isDisabled
+    >
+      <Radio value="2" labelText="Radio 2" />
+      <Radio value="3" labelText="Radio 3" />
+      <Radio value="4" labelText="Radio 4" />
+      <Radio value="5" labelText="Radio 5" />
+    </RadioGroup>
+  </DSProvider>
+</Canvas>
+
+## Getting Radio Data Values
+
+### Controlled Component using `name` and `onChange` props
+
+If your application uses controlled React components and the DS RadioGroup must
+be controlled, you can extract the data through the `name` and `onChange` props.
+This will be called every time a new `Radio` value is selected.
+
+```jsx
+const onChange = (data) => {
+  // This will return the value selected as a string.
+  console.log(data);
+};
+// ...
+
+// Example of the DS RadioGroup instance with the function above:
+<RadioGroup
+  id="controlled-example"
+  labelText="Radio Group"
+  name="radioExample"
+  defaultValue="3"
+  onChange={onChange}
+>
+  <Radio value="2" labelText="Radio 2" />
+  <Radio value="3" labelText="Radio 3" />
+  <Radio value="4" labelText="Radio 4" />
+</RadioGroup>;
+```
+
+### Uncontrolled Component using `ref`s
+
+If your application uses uncontrolled components, you can pass React `ref` props
+to the DS RadioGroup component to get the selected value from the DOM.
+
+The following example is using the `register` React `ref` from the
+`react-hook-form` package.
+
+```jsx
+import { useFormContext, Controller } from "react-hook-form";
+// ...
+const { register, handleSubmit, control } = useFormContext();
+// ...
+const submitForm = (formData) => {
+  // This will return an object with all the DOM element values that were
+  // registered with a `name` attribute.
+  // {
+  //   radioExample: "3"
+  // }
+  console.log(formData);
+  // ...
+};
+
+<form
+  onSubmit={handleSubmit(submitForm)}
+  method="post"
+  action="/some/api/endpoint"
+>
+  <Controller
+    as={
+      <RadioGroup
+        id="uncontrolled-example"
+        labelText="Radio Group"
+        name="radioExample"
+        defaultValue="3"
+        ref={register()}
+      >
+        <Radio value="2" labelText="Radio 2" />
+        <Radio value="3" labelText="Radio 3" />
+        <Radio value="4" labelText="Radio 4" />
+      </RadioGroup>
+    }
+    name="radioExample"
+    control={control}
+  />
+</form>;
+```
+
+The above is specific to `react-hook-form` but a similar pattern can be used
+with normal React `ref` values.
+
+```jsx
+const radioGroupRef = React.createRef<HTMLInputElement>();
+// ...
+<RadioGroup
+  id="uncontrolled-example"
+  labelText="Radio Group"
+  name="radioExample"
+  defaultValue="3"
+  ref={radioGroupRef}
+>
+  <Radio value="2" labelText="Radio 2" />
+  <Radio value="3" labelText="Radio 3" />
+  <Radio value="4" labelText="Radio 4" />
+</RadioGroup>
+
+// ...
+// Get the value through:
+const onSubmit = () => {
+  // ...
+  const radioGroupValue = radioGroupRef.current.value;
+};
+```