@nypl/design-system-react-components 0.25.13 → 0.26.0

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

@@ -1,4 +1,4 @@
-import { Flex, Spacer } from "@chakra-ui/react";
+import { ButtonGroup, Flex, Spacer } from "@chakra-ui/react";
 import {
   ArgsTable,
   Canvas,
@@ -8,9 +8,12 @@ import {
 } from "@storybook/addon-docs";
 import { withDesign } from "storybook-addon-designs";
 
+import Button from "../Button/Button";
+import Form from "../Form/Form";
 import Radio from "../Radio/Radio";
-import RadioGroup, { onChangeDefault } from "./RadioGroup";
+import RadioGroup from "./RadioGroup";
 import { LayoutTypes } from "../../helpers/enums";
+import SimpleGrid from "../Grid/SimpleGrid";
 import { getCategory } from "../../utils/componentCategories";
 import DSProvider from "../../theme/provider";
 import { getStorybookEnumValues } from "../../utils/utils";
@@ -52,15 +55,15 @@ export const enumValues = getStorybookEnumValues(LayoutTypes, "LayoutTypes");
     key: { table: { disable: true } },
     onChange: { control: false },
     ref: { table: { disable: true } },
-    optReqFlag: {
-      table: { defaultValue: { summary: true } },
-    },
     showHelperInvalidText: {
       table: { defaultValue: { summary: true } },
     },
     showLabel: {
       table: { defaultValue: { summary: true } },
     },
+    showRequiredLabel: {
+      table: { defaultValue: { summary: true } },
+    },
   }}
 />
 
@@ -69,10 +72,26 @@ export const enumValues = getStorybookEnumValues(LayoutTypes, "LayoutTypes");
 | Component Version | DS Version |
 | ----------------- | ---------- |
 | Added             | `0.25.0`   |
-| Latest            | `0.25.13`  |
+| Latest            | `0.26.0`   |
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Component Props](#component-props)
+- [Accessibility](#accessibility)
+- [Layout Patterns](#layout-patterns)
+- [Errored](#errored)
+- [Required](#required)
+- [Disabled](#disabled)
+- [With JSX Element labels](#with-jsx-element-labels)
+- [Getting Radio Input Values](#getting-radio-input-values)
+
+## Overview
 
 <Description of={RadioGroup} />
 
+## Component Props
+
 <Canvas withToolbar>
   <Story
     name="RadioGroup"
@@ -81,7 +100,7 @@ export const enumValues = getStorybookEnumValues(LayoutTypes, "LayoutTypes");
       defaultValue: "4",
       helperText: "This is the helper text for the full group.",
       id: "radioGroup-id",
-      invalidText: "error!",
+      invalidText: "An error occurred :(",
       isDisabled: false,
       isFullWidth: false,
       isInvalid: false,
@@ -90,17 +109,17 @@ export const enumValues = getStorybookEnumValues(LayoutTypes, "LayoutTypes");
       layout: "LayoutTypes.Column",
       name: "radio-story",
       onChange: undefined,
-      optReqFlag: true,
       showHelperInvalidText: true,
       showLabel: true,
+      showRequiredLabel: true,
     }}
   >
     {(args) => (
       <RadioGroup {...args} layout={enumValues.getValue(args.layout)}>
-        <Radio value="2" labelText="Radio 2" />
-        <Radio value="3" labelText="Radio 3" />
-        <Radio value="4" labelText="Radio 4" />
-        <Radio value="5" labelText="Radio 5" />
+        <Radio id="main-2" labelText="Radio 2" value="2" />
+        <Radio id="main-3" labelText="Radio 3" value="3" />
+        <Radio id="main-4" labelText="Radio 4" value="4" />
+        <Radio id="main-5" labelText="Radio 5" value="5" />
       </RadioGroup>
     )}
   </Story>
@@ -108,6 +127,18 @@ export const enumValues = getStorybookEnumValues(LayoutTypes, "LayoutTypes");
 
 <ArgsTable story="RadioGroup" />
 
+## Accessibility
+
+The `RadioGroup` renders a group of `Radio` components that are wrapped in a
+`<fieldset>` element. The `<fieldset>` element renders a `<legend>` element that
+can be visually hidden through the `showLabel` prop.
+
+Resources:
+
+- [W3C ARIA radiogroup and radio example](https://www.w3.org/TR/2016/WD-wai-aria-practices-1.1-20160317/examples/radio/radio.html)
+- [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)
+
 ## Layout Patterns
 
 Use the `layout` prop to set the `Radio` buttons to display in a column or in
@@ -116,26 +147,28 @@ a row.
 <Canvas>
   <DSProvider>
     <RadioGroup
+      defaultValue="4"
+      id="column"
       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" />
+      <Radio id="column-2" labelText="Radio 2" value="2" />
+      <Radio id="column-3" labelText="Radio 3" value="3" />
+      <Radio id="column-4" labelText="Radio 4" value="4" />
+      <Radio id="column-5" labelText="Radio 5" value="5" />
     </RadioGroup>
     <br />
     <RadioGroup
+      defaultValue="3"
+      id="row"
       labelText="Row"
       name="row-example"
       layout={LayoutTypes.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" />
+      <Radio id="row-2" labelText="Radio 2" value="2" />
+      <Radio id="row-3" labelText="Radio 3" value="3" />
+      <Radio id="row-4" labelText="Radio 4" value="4" />
+      <Radio id="row-5" labelText="Radio 5" value="5" />
     </RadioGroup>
   </DSProvider>
 </Canvas>
@@ -145,16 +178,36 @@ a row.
 <Canvas>
   <DSProvider>
     <RadioGroup
-      labelText="Errored Radio Group"
-      name="errored-example"
-      optReqFlag={false}
+      defaultValue="4"
+      id="errored"
       invalidText="Error message for the full group."
       isInvalid
+      labelText="Errored Radio Group"
+      name="errored-example"
     >
-      <Radio value="2" labelText="Radio 2" />
-      <Radio value="3" labelText="Radio 3" />
-      <Radio value="4" labelText="Radio 4" />
-      <Radio value="5" labelText="Radio 5" />
+      <Radio id="radio-2" labelText="Radio 2" value="2" />
+      <Radio id="radio-3" labelText="Radio 3" value="3" />
+      <Radio id="radio-4" labelText="Radio 4" value="4" />
+      <Radio id="radio-5" labelText="Radio 5" value="5" />
+    </RadioGroup>
+  </DSProvider>
+</Canvas>
+
+## Required
+
+<Canvas>
+  <DSProvider>
+    <RadioGroup
+      helperText="The reason for being required."
+      id="required"
+      isRequired
+      labelText="Required Radio Group"
+      name="required-example"
+    >
+      <Radio id="required-2" labelText="Radio 2" value="2" />
+      <Radio id="required-3" labelText="Radio 3" value="3" />
+      <Radio id="required-4" labelText="Radio 4" value="4" />
+      <Radio id="required-5" labelText="Radio 5" value="5" />
     </RadioGroup>
   </DSProvider>
 </Canvas>
@@ -164,16 +217,16 @@ a row.
 <Canvas>
   <DSProvider>
     <RadioGroup
-      labelText="Disabled Radio Group"
-      name="disabled-example"
-      optReqFlag={false}
       helperText="The reason for being disabled."
+      id="disabled"
       isDisabled
+      labelText="Disabled Radio Group"
+      name="disabled-example"
     >
-      <Radio value="2" labelText="Radio 2" />
-      <Radio value="3" labelText="Radio 3" />
-      <Radio value="4" labelText="Radio 4" />
-      <Radio value="5" labelText="Radio 5" />
+      <Radio id="required-2" labelText="Radio 2" value="2" />
+      <Radio id="required-3" labelText="Radio 3" value="3" />
+      <Radio id="required-4" labelText="Radio 4" value="4" />
+      <Radio id="required-5" labelText="Radio 5" value="5" />
     </RadioGroup>
   </DSProvider>
 </Canvas>
@@ -191,12 +244,13 @@ order to make this work, pass in the `isFullWidth` prop.
 <Canvas>
   <DSProvider>
     <RadioGroup
+      id="jsx-radiogroup"
+      isFullWidth
       labelText="Radio Group"
       name="radio-example"
-      optReqFlag={false}
-      isFullWidth
     >
       <Radio
+        id="arts"
         labelText={
           <Flex>
             <span>Arts</span>
@@ -207,6 +261,7 @@ order to make this work, pass in the `isFullWidth` prop.
         value="arts"
       />
       <Radio
+        id="english"
         labelText={
           <Flex>
             <span>English</span>
@@ -217,6 +272,7 @@ order to make this work, pass in the `isFullWidth` prop.
         value="English"
       />
       <Radio
+        id="science"
         labelText={
           <Flex>
             <span>Science</span>
@@ -227,6 +283,7 @@ order to make this work, pass in the `isFullWidth` prop.
         value="Science"
       />
       <Radio
+        id="math"
         labelText={
           <Flex>
             <span>Math</span>
@@ -240,39 +297,70 @@ order to make this work, pass in the `isFullWidth` prop.
   </DSProvider>
 </Canvas>
 
-## Getting Radio Data Values
+## Getting Radio Input 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.
+If your application uses controlled React components and the Reservoir Design
+System (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. Open the browser's console to see the output.
 
 ```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>;
+function RadioGroupControlledExample() {
+  const onChange = (selected) => {
+    // This will return the value selected as a string.
+    console.log(`Controlled example. Selected: ${selected}`);
+  };
+  return (
+    <RadioGroup
+      defaultValue="3"
+      id="controlled-example"
+      labelText="Controlled RadioGroup"
+      name="radioGroupExample"
+      onChange={onChange}
+    >
+      <Radio id="2" labelText="Radio 2" value="2" />
+      <Radio id="3" labelText="Radio 3" value="3" />
+      <Radio id="4" labelText="Radio 4" value="4" />
+    </RadioGroup>
+  );
+}
 ```
 
+export function RadioGroupControlledExample() {
+  const onChange = (selected) => {
+    // This will return the value selected as a string.
+    console.log(`Controlled example. Selected: ${selected}`);
+  };
+  return (
+    <RadioGroup
+      defaultValue="3"
+      id="controlled-example"
+      labelText="Controlled RadioGroup"
+      name="radioGroupExample"
+      onChange={onChange}
+    >
+      <Radio id="2" labelText="Radio 2" value="2" />
+      <Radio id="3" labelText="Radio 3" value="3" />
+      <Radio id="4" labelText="Radio 4" value="4" />
+    </RadioGroup>
+  );
+}
+
+<Canvas>
+  <DSProvider>
+    <RadioGroupControlledExample />
+  </DSProvider>
+</Canvas>
+
 ### Uncontrolled Component using `ref`s
 
+**NOTE: this, along with Chakra's own `RadioGroup` component, are not working
+at this time and we recommend to use the controlled pattern above.**
+
 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.
+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.
@@ -300,45 +388,92 @@ const submitForm = (formData) => {
   <Controller
     as={
       <RadioGroup
-        id="uncontrolled-example"
-        labelText="Radio Group"
-        name="radioExample"
         defaultValue="3"
+        id="uncontrolled-example"
+        labelText="RadioGroup Uncontrolled"
+        name="radioGroupExample"
         ref={register()}
       >
-        <Radio value="2" labelText="Radio 2" />
-        <Radio value="3" labelText="Radio 3" />
-        <Radio value="4" labelText="Radio 4" />
+        <Radio id="2" labelText="Radio 2" value="2" />
+        <Radio id="3" labelText="Radio 3" value="3" />
+        <Radio id="4" labelText="Radio 4" value="4" />
       </RadioGroup>
     }
-    name="radioExample"
     control={control}
+    name="radioGroupExample"
   />
 </form>;
 ```
 
 The above is specific to `react-hook-form` but a similar pattern can be used
-with normal React `ref` values.
+with normal React `ref` values. Open the browser's console to see the output
+**although, at the moment, forwarding the ref to Chakra's own `RadioGroup`
+component is not working.**
 
 ```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;
-};
+export function RadioGroupUncontrolledExample() {
+  const radioGroupRef = React.createRef();
+  // Get the value through:
+  const onSubmit = (e) => {
+    e.preventDefault();
+    const radioGroupValue = radioGroupRef.current.value;
+    console.log(`Uncontrolled example. Selected: ${radioGroupValue}`);
+  };
+  return (
+    <Form onSubmit={onSubmit}>
+      <SimpleGrid columns="1">
+        <RadioGroup
+          defaultValue="3"
+          id="uncontrolled-example"
+          labelText="Uncontrolled RadioGroup"
+          name="radioGroupExample"
+          ref={radioGroupRef}
+        >
+          <Radio id="2" labelText="Radio 2" value="2" />
+          <Radio id="3" labelText="Radio 3" value="3" />
+          <Radio id="4" labelText="Radio 4" value="4" />
+        </RadioGroup>
+        <ButtonGroup>
+          <Button type="submit">Submit</Button>
+        </ButtonGroup>
+      </SimpleGrid>
+    </Form>
+  );
+}
 ```
+
+export function RadioGroupUncontrolledExample() {
+  const radioGroupRef = React.createRef();
+  // Get the value through:
+  const onSubmit = (e) => {
+    e.preventDefault();
+    const radioGroupValue = radioGroupRef.current.value;
+    console.log(`Uncontrolled example. Selected: ${radioGroupValue}`);
+  };
+  return (
+    <Form onSubmit={onSubmit}>
+      <SimpleGrid columns="1">
+        <RadioGroup
+          defaultValue="3"
+          id="uncontrolled-example"
+          labelText="Uncontrolled RadioGroup"
+          name="radioGroupExample"
+          ref={radioGroupRef}
+        >
+          <Radio id="2" labelText="Radio 2" value="2" />
+          <Radio id="3" labelText="Radio 3" value="3" />
+          <Radio id="4" labelText="Radio 4" value="4" />
+        </RadioGroup>
+        <ButtonGroup>
+          <Button type="submit">Submit</Button>
+        </ButtonGroup>
+      </SimpleGrid>
+    </Form>
+  );
+}
+
+<Canvas>
+  <DSProvider>
+    <RadioGroupUncontrolledExample />
+  </DSProvider>
+</Canvas>