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

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

@@ -0,0 +1,479 @@
+import { Flex, Spacer } from "@chakra-ui/react";
+import {
+  ArgsTable,
+  Canvas,
+  Description,
+  Meta,
+  Story,
+} from "@storybook/addon-docs";
+import { withDesign } from "storybook-addon-designs";
+
+import Button from "../Button/Button";
+import ButtonGroup from "../ButtonGroup/ButtonGroup";
+import Form from "../Form/Form";
+import Radio from "../Radio/Radio";
+import RadioGroup from "./RadioGroup";
+import SimpleGrid from "../Grid/SimpleGrid";
+import { getCategory } from "../../utils/componentCategories";
+import DSProvider from "../../theme/provider";
+
+<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: { control: false },
+    id: { control: false },
+    isDisabled: {
+      table: { defaultValue: { summary: false } },
+    },
+    isFullWidth: {
+      table: { defaultValue: { summary: false } },
+    },
+    isInvalid: {
+      table: { defaultValue: { summary: false } },
+    },
+    isRequired: {
+      table: { defaultValue: { summary: false } },
+    },
+    layout: {
+      table: { defaultValue: { summary: "column" } },
+    },
+    key: { table: { disable: true } },
+    onChange: { control: false },
+    ref: { table: { disable: true } },
+    showHelperInvalidText: {
+      table: { defaultValue: { summary: true } },
+    },
+    showLabel: {
+      table: { defaultValue: { summary: true } },
+    },
+    showRequiredLabel: {
+      table: { defaultValue: { summary: true } },
+    },
+  }}
+/>
+
+# RadioGroup
+
+| Component Version | DS Version |
+| ----------------- | ---------- |
+| Added             | `0.25.0`   |
+| Latest            | `1.0.2`    |
+
+## 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"
+    args={{
+      className: undefined,
+      defaultValue: "4",
+      helperText: "This is the helper text for the full group.",
+      id: "radioGroup-id",
+      invalidText: "An error occurred :(",
+      isDisabled: false,
+      isFullWidth: false,
+      isInvalid: false,
+      isRequired: false,
+      labelText: "Standard Radio Group",
+      layout: "column",
+      name: "radio-story",
+      onChange: undefined,
+      showHelperInvalidText: true,
+      showLabel: true,
+      showRequiredLabel: true,
+    }}
+  >
+    {(args) => (
+      <RadioGroup {...args}>
+        <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>
+</Canvas>
+
+<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
+a row.
+
+<Canvas>
+  <DSProvider>
+    <RadioGroup
+      defaultValue="4"
+      id="column"
+      labelText="Column (default)"
+      name="column-example"
+    >
+      <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="row"
+    >
+      <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>
+
+## Errored
+
+<Canvas>
+  <DSProvider>
+    <RadioGroup
+      defaultValue="4"
+      id="errored"
+      invalidText="Error message for the full group."
+      isInvalid
+      labelText="Errored Radio Group"
+      name="errored-example"
+    >
+      <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>
+
+## Disabled
+
+<Canvas>
+  <DSProvider>
+    <RadioGroup
+      helperText="The reason for being disabled."
+      id="disabled"
+      isDisabled
+      labelText="Disabled Radio Group"
+      name="disabled-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>
+
+## With JSX Element labels
+
+React elements can be passed to the `labelText` prop of the `Radio` component.
+This is useful if you need to pass information as part of the label. For example,
+if a `Radio` label needs to display how many items that option has, it can be
+displayed with the help of the `Flex` and `Spacer` components.
+
+Note: the width of `RadioGroup` is _not_ set to full width by default. In
+order to make this work, pass in the `isFullWidth` prop.
+
+<Canvas>
+  <DSProvider>
+    <RadioGroup
+      id="jsx-radiogroup"
+      isFullWidth
+      labelText="Radio Group"
+      name="radio-example"
+    >
+      <Radio
+        id="arts"
+        labelText={
+          <Flex>
+            <span>Arts</span>
+            <Spacer />
+            <span>4</span>
+          </Flex>
+        }
+        value="arts"
+      />
+      <Radio
+        id="english"
+        labelText={
+          <Flex>
+            <span>English</span>
+            <Spacer />
+            <span>23</span>
+          </Flex>
+        }
+        value="English"
+      />
+      <Radio
+        id="science"
+        labelText={
+          <Flex>
+            <span>Science</span>
+            <Spacer />
+            <span>10</span>
+          </Flex>
+        }
+        value="Science"
+      />
+      <Radio
+        id="math"
+        labelText={
+          <Flex>
+            <span>Math</span>
+            <Spacer />
+            <span>3</span>
+          </Flex>
+        }
+        value="Math"
+      />
+    </RadioGroup>
+  </DSProvider>
+</Canvas>
+
+## Getting Radio Input Values
+
+### Controlled Component using `name` and `onChange` props
+
+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
+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.
+
+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
+  id="example-form"
+  onSubmit={handleSubmit(submitForm)}
+  method="post"
+  action="/some/api/endpoint"
+>
+  <Controller
+    as={
+      <RadioGroup
+        defaultValue="3"
+        id="uncontrolled-example"
+        labelText="RadioGroup Uncontrolled"
+        name="radioGroupExample"
+        ref={register()}
+      >
+        <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>
+    }
+    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. 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
+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 id="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 id="submit" 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 id="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 id="submit" type="submit">
+            Submit
+          </Button>
+        </ButtonGroup>
+      </SimpleGrid>
+    </Form>
+  );
+}
+
+<Canvas>
+  <DSProvider>
+    <RadioGroupUncontrolledExample />
+  </DSProvider>
+</Canvas>