@nypl/design-system-react-components 0.25.7 → 0.25.8

package/src/components/Select/Select.stories.mdx

@@ -9,6 +9,8 @@ import { withDesign } from "storybook-addon-designs";
 
 import { VStack } from "@chakra-ui/react";
 import Select from "./Select";
+import Form from "../Form/Form";
+import Button from "../Button/Button";
 import { getCategory } from "../../utils/componentCategories";
 import DSProvider from "../../theme/provider";
 
@@ -19,8 +21,7 @@ import DSProvider from "../../theme/provider";
   parameters={{
     design: {
       type: "figma",
-      url:
-        "https://www.figma.com/file/qShodlfNCJHb8n03IFyApM/Master?node-id=11895%3A549",
+      url: "https://www.figma.com/file/qShodlfNCJHb8n03IFyApM/Master?node-id=11895%3A549",
     },
     jest: ["Select.test.tsx"],
   }}
@@ -38,7 +39,7 @@ import DSProvider from "../../theme/provider";
 | Component Version | DS Version |
 | ----------------- | ---------- |
 | Added             | `0.7.0`    |
-| Latest            | `0.25.1`   |
+| Latest            | `0.25.8`   |
 
 <Description of={Select} />
 
@@ -102,8 +103,8 @@ text within the `label` element.
   <Story name="Labelling Variations">
     <VStack align="stretch" spacing={8}>
       <Select
-        labelText="What is your favorite color?"
         helperText="Display the label"
+        labelText="What is your favorite color?"
         name="color"
       >
         <option value="red">Red</option>
@@ -113,8 +114,8 @@ text within the `label` element.
         <option value="white">White</option>
       </Select>
       <Select
-        labelText="What is your favorite color?"
         helperText="Do not display the label"
+        labelText="What is your favorite color?"
         name="color"
         showLabel={false}
       >
@@ -125,10 +126,10 @@ text within the `label` element.
         <option value="white">White</option>
       </Select>
       <Select
-        labelText="What is your favorite color?"
         helperText="Display the Required/Optional text"
-        name="color"
         isRequired
+        labelText="What is your favorite color?"
+        name="color"
       >
         <option value="red">Red</option>
         <option value="green">Green</option>
@@ -137,11 +138,11 @@ text within the `label` element.
         <option value="white">White</option>
       </Select>
       <Select
-        labelText="What is your favorite color?"
         helperText="Do not display the Required/Optional text"
+        isRequired
+        labelText="What is your favorite color?"
         name="color"
         showOptReqLabel={false}
-        isRequired
       >
         <option value="red">Red</option>
         <option value="green">Green</option>
@@ -158,11 +159,11 @@ text within the `label` element.
 <Canvas>
   <DSProvider>
     <Select
-      labelText="What is your favorite color?"
       helperText="This is the helper text."
       invalidText="This is the error text :("
-      name="color"
       isInvalid
+      labelText="What is your favorite color?"
+      name="color"
     >
       <option value="red">Red</option>
       <option value="green">Green</option>
@@ -178,11 +179,11 @@ text within the `label` element.
 <Canvas>
   <DSProvider>
     <Select
-      labelText="What is your favorite color?"
       helperText="This is the helper text."
       invalidText="This is the error text :("
-      name="color"
       isDisabled
+      labelText="What is your favorite color?"
+      name="color"
     >
       <option value="red">Red</option>
       <option value="green">Green</option>
@@ -198,57 +199,133 @@ text within the `label` element.
 ### Controlled Component using `value` and `onChange` props
 
 If your application uses controlled React components and the DS `Select`
-component must be controlled, you can control and extract the data through the
+component must be controlled, you can pass and extract the value through the
 `value` and `onChange` props. This will be called every time a new `option`
 value is selected.
 
+Try it out: open up the browser's console to see new values being logged on
+each change.
+
 ```jsx
-const value = "red";
-const onChange = (e) => {
-  // This will return the value selected through the event object.
-  console.log(e.target.value);
-};
-// ...
-
-<Select
-  labelText="What is your favorite color?"
-  helperText="This is the helper text."
-  name="color"
-  value={value}
-  onChange={onChange}
->
-  <option value="red">Red</option>
-  <option value="green">Green</option>
-  <option value="blue">Blue</option>
-  <option value="black">Black</option>
-  <option value="white">White</option>
-</Select>;
+export function SelectControlledExample() {
+  const [value, setValue] = React.useState();
+  const onChange = (e) => {
+    // This will return the value selected through the event object.
+    console.log(e.target.value);
+    setValue(e.target.value);
+  };
+  return (
+    <Select
+      helperText="This is the helper text."
+      labelText="What is your favorite color?"
+      name="color"
+      onChange={onChange}
+      value={value}
+    >
+      <option value="red">Red</option>
+      <option value="green">Green</option>
+      <option value="blue">Blue</option>
+      <option value="black">Black</option>
+      <option value="white">White</option>
+    </Select>
+  );
+}
 ```
 
+export function SelectControlledExample() {
+  const [value, setValue] = React.useState();
+  const onChange = (e) => {
+    // This will return the value selected through the event object.
+    console.log("Controlled value:", e.target.value);
+    setValue(e.target.value);
+  };
+  return (
+    <Select
+      helperText="This is the helper text."
+      labelText="What is your favorite color?"
+      name="color"
+      onChange={onChange}
+      value={value}
+    >
+      <option value="red">Red</option>
+      <option value="green">Green</option>
+      <option value="blue">Blue</option>
+      <option value="black">Black</option>
+      <option value="white">White</option>
+    </Select>
+  );
+}
+
+<Canvas>
+  <DSProvider>
+    <SelectControlledExample />
+  </DSProvider>
+</Canvas>
+
 ### Uncontrolled Component using `ref`s
 
 If your application uses uncontrolled components, you can pass a React `ref`
-prop to the DS Select component to get the selected value from the DOM.
+prop to the DS Select component to get the selected value from the DOM. Note
+that this example uses a `Form` and a `Button` to submit the form, only then
+will the value be available.
 
-```jsx
-const selectRef = React.createRef<HTMLSelectElement>();
-// ...
-<Select
-  labelText="What is your favorite color?"
-  helperText="This is the helper text."
-  name="color"
->
-  <option value="red">Red</option>
-  <option value="green">Green</option>
-  <option value="blue">Blue</option>
-  <option value="black">Black</option>
-  <option value="white">White</option>
-</Select>
+Try it out: open up the browser's console to see new values being logged on
+each change.
 
-// ...
-// Get the value through:
-const onSubmit = () => {
-  // ...
-  const selectValue = selectRef.current.value;
-};
+```jsx
+export function SelectUncontrolledExample() {
+  const selectRef = React.createRef();
+  const onSubmit = () => {
+    const selectValue = selectRef.current.value;
+    console.log("Using uncontrolled ref:", selectValue);
+  };
+  return (
+    <Form>
+      <Select
+        helperText="This is the helper text."
+        labelText="What is your favorite color?"
+        name="color"
+        ref={selectRef}
+      >
+        <option value="red">Red</option>
+        <option value="green">Green</option>
+        <option value="blue">Blue</option>
+        <option value="black">Black</option>
+        <option value="white">White</option>
+      </Select>
+      <Button onClick={onSubmit}>Submit</Button>
+    </Form>
+  );
+}
 ```
+
+export function SelectUncontrolledExample() {
+  const selectRef = React.createRef();
+  const onSubmit = () => {
+    const selectValue = selectRef.current.value;
+    console.log("Using uncontrolled ref:", selectValue);
+  };
+  return (
+    <Form>
+      <Select
+        helperText="This is the helper text."
+        labelText="What is your favorite color?"
+        name="color"
+        ref={selectRef}
+      >
+        <option value="red">Red</option>
+        <option value="green">Green</option>
+        <option value="blue">Blue</option>
+        <option value="black">Black</option>
+        <option value="white">White</option>
+      </Select>
+      <Button onClick={onSubmit}>Submit</Button>
+    </Form>
+  );
+}
+
+<Canvas>
+  <DSProvider>
+    <SelectUncontrolledExample />
+  </DSProvider>
+</Canvas>

package/src/components/Select/Select.test.tsx

@@ -198,7 +198,7 @@ describe("Select", () => {
   });
 
   it("calls the onChange callback function", () => {
-    let value = "red";
+    let value = "";
     const changeCallback = (e) => {
       value = e.target.value;
     };
@@ -208,7 +208,7 @@ describe("Select", () => {
       </Select>
     );
 
-    expect(value).toEqual("red");
+    expect(value).toEqual("");
 
     fireEvent.change(screen.getByRole("combobox"), {
       target: { value: "blue" },

package/src/components/Select/Select.tsx

@@ -38,6 +38,8 @@ export interface SelectProps {
   /** The callback function to get the selected value.
    * Should be passed along with `value` for controlled components. */
   onChange?: (event: React.FormEvent) => void;
+  /** Placeholder text in the select element. */
+  placeholder?: string;
   /** Offers the ability to hide the helper/invalid text. */
   showHelperInvalidText?: boolean;
   /** Offers the ability to show the select's label onscreen or hide it. Refer
@@ -72,11 +74,12 @@ const Select = React.forwardRef<
     labelText,
     name,
     onChange,
+    placeholder,
     showHelperInvalidText = true,
     showLabel = true,
     showOptReqLabel = true,
     type = SelectTypes.Default,
-    value,
+    value = "",
   } = props;
   const ariaAttributes = {};
   const optReqFlag = isRequired ? "Required" : "Optional";
@@ -87,7 +90,7 @@ const Select = React.forwardRef<
   const footnote = isInvalid ? finalInvalidText : helperText;
   // To control the `Select` component, both `onChange` and `value`
   // must be passed.
-  const controlledProps = onChange && value ? { onChange, value } : {};
+  const controlledProps = onChange ? { onChange, value } : {};
 
   if (!showLabel) {
     ariaAttributes["aria-label"] =
@@ -126,6 +129,7 @@ const Select = React.forwardRef<
         isDisabled={isDisabled}
         isInvalid={isInvalid}
         name={name}
+        placeholder={placeholder}
         ref={ref}
         {...controlledProps}
         {...ariaAttributes}

package/src/components/Slider/Slider.stories.mdx

@@ -40,7 +40,7 @@ import DSProvider from "../../theme/provider";
 | Component Version | DS Version |
 | ----------------- | ---------- |
 | Added             | `0.25.4`   |
-| Latest            | `0.25.4`   |
+| Latest            | `0.25.8`   |
 
 <Description of={Slider} />
 
@@ -439,7 +439,8 @@ Pass a callback function to the `onChange` prop to get the current number value
 of the `Slider` component or an array of two numbers when it is a range slider.
 Internally, the `Slider` component handles the state of the current selected
 value or values. Once the value(s) is updated, the `onChange` callback will be
-called and the values will be passed.
+called and the values will be passed. If no `onChange` callback is provided,
+you won't be able to get the updated value(s) of the `Slider` component.
 
 #### Single Slider Value
 

package/src/components/Slider/Slider.test.tsx

@@ -294,6 +294,26 @@ describe("Slider", () => {
       expect(input).toHaveValue(100);
     });
 
+    it("doesn't crash if no onChange callback function is passed", () => {
+      let currentValue = 0;
+      render(
+        <Slider
+          defaultValue={50}
+          helperText="Component helper text."
+          invalidText="Component error text :("
+          labelText="Label"
+        />
+      );
+
+      const input = screen.getByRole("spinbutton");
+      fireEvent.change(input, {
+        target: { value: "42" },
+      });
+      // While we change the slider input value, since there is no onChange
+      // function, there is no way to update this local `currentValue` variable.
+      expect(currentValue).toEqual(0);
+    });
+
     it("gets the current value through the onChange callback function", () => {
       let currentValue = 0;
       function onChange(value) {
@@ -495,6 +515,21 @@ describe("Slider", () => {
       );
     });
 
+    it("renders with min and max values as the default values if no `defaultValue` array is passed", () => {
+      render(
+        <Slider
+          helperText="Component helper text."
+          invalidText="Component error text :("
+          isRangeSlider
+          labelText="Label"
+          max={80}
+          min={30}
+        />
+      );
+      expect(screen.getByText("30")).toBeInTheDocument();
+      expect(screen.getByText("80")).toBeInTheDocument();
+    });
+
     it("renders the invalid state if the start and end values are wrong", () => {
       // The start value is bigger than the end value.
       render(

package/src/components/Slider/Slider.tsx

@@ -97,8 +97,14 @@ export default function Slider(props: React.PropsWithChildren<SliderProps>) {
     showValues = true,
     step = 1,
   } = props;
+  // For the RangeSlider, if the defaultValue is not an array, then we set
+  // the defaultValue to an array with the min and max values.
+  const rangeSliderDefault =
+    typeof defaultValue === "number" ? [min, max] : defaultValue;
+  // We need to set the default value correctly for both types of sliders.
+  const finalDevaultValue = isRangeSlider ? rangeSliderDefault : defaultValue;
   const [currentValue, setCurrentValue] = React.useState<typeof defaultValue>(
-    defaultValue
+    finalDevaultValue
   );
   let finalIsInvalid = isInvalid;
   // In the Range Slider, if the first value is bigger than the second value,
@@ -127,7 +133,7 @@ export default function Slider(props: React.PropsWithChildren<SliderProps>) {
     onChange: (val) => setCurrentValue(val),
     // Call the passed in `onChange` function prop to get the
     // *final* value once a user stops dragging the slider.
-    onChangeEnd: (val) => onChange(val),
+    onChangeEnd: (val) => onChange && onChange(val),
     step,
   };
   // Props that the two `TextInput` components use.

package/src/components/Template/Template.stories.mdx

@@ -49,8 +49,7 @@ import { getCategory } from "../../utils/componentCategories";
   parameters={{
     design: {
       type: "figma",
-      url:
-        "https://www.figma.com/file/qShodlfNCJHb8n03IFyApM/Master?node-id=11982%3A47778",
+      url: "https://www.figma.com/file/qShodlfNCJHb8n03IFyApM/Master?node-id=11982%3A47778",
     },
   }}
 />

package/src/components/Toggle/Toggle.stories.mdx

@@ -0,0 +1,176 @@
+import {
+  Meta,
+  Story,
+  Canvas,
+  ArgsTable,
+  Description,
+} from "@storybook/addon-docs/blocks";
+import { withDesign } from "storybook-addon-designs";
+import { HStack, VStack, Grid, Box } from "@chakra-ui/react";
+import Heading from "../Heading/Heading";
+import SimpleGrid from "../Grid/SimpleGrid";
+import { getCategory } from "../../utils/componentCategories";
+import DSProvider from "../../theme/provider";
+import Toggle from "./Toggle";
+import { ToggleSizes } from "./ToggleSizes";
+
+<Meta
+  title={getCategory("Toggle")}
+  component={Toggle}
+  decorators={[withDesign]}
+  parameters={{
+    design: {
+      type: "figma",
+      url: "https://www.figma.com/file/qShodlfNCJHb8n03IFyApM/Main?node-id=31581%3A302",
+    },
+    jest: ["Toggle.test.tsx"],
+  }}
+  argTypes={{
+    id: { control: false },
+    className: { control: false },
+  }}
+/>
+
+# Toggle
+
+| Component Version | DS Version |
+| ----------------- | ---------- |
+| Added             | `0.25.8`   |
+| Latest            | `0.25.8`   |
+
+<Description of={Toggle} />
+
+The Toggle component is used as an alternative for the Checkbox component and returns a boolean response. Like the Checkbox component, the Toggle component can display a label to the right of the toggle and helper/error text below the toggle.
+
+### Best Practices
+
+Toggle components are commonly used for “on/off” switches to perform binary actions that occur immediately after a user “flips the switch.”
+
+The Toggle component label should clarify the action being performed. Labels should be short and to the point, often three words or less.
+
+<Canvas>
+  <Story
+    name="Toggle"
+    args={{
+      labelText: "Test Label",
+      size: "large",
+      defaultChecked: false,
+      helperText: "This is the helper text!",
+      invalidText: "",
+      isDisabled: false,
+      isInvalid: false,
+      isRequired: false,
+    }}
+  >
+    {(args) => <Toggle {...args} />}
+  </Story>
+</Canvas>
+
+<ArgsTable story="Toggle" />
+
+## Sizes
+
+<Canvas>
+  <DSProvider>
+    <SimpleGrid columns="2">
+      <VStack align="left" spacing="s">
+        <Heading level={3}>Large</Heading>
+        <Toggle size={ToggleSizes.Large} defaultChecked={true} labelText="On" />
+        <Toggle size={ToggleSizes.Large} labelText="Off" />
+      </VStack>
+      <VStack align="left" spacing="s">
+        <Heading level={3}>Small</Heading>
+        <Toggle size={ToggleSizes.Small} defaultChecked={true} labelText="On" />
+        <Toggle size={ToggleSizes.Small} labelText="Off" />
+      </VStack>
+    </SimpleGrid>
+  </DSProvider>
+</Canvas>
+
+## Controlled Toggle
+
+Note that the `isChecked` property in this example is set to `true`. Clicking
+on it won't change the toggle; The `isChecked` prop must now be controlled
+and removed manually by the parent component that controls this state. The
+`onChange` function will be called every time the `isChecked` prop changes.
+
+```jsx
+const isChecked = true;
+const onChange = (e) => {
+  // This will return the value through the event object.
+  console.log(e.target.value);
+};
+
+<Toggle isChecked={true} onChange={onChange} labelText="Controlled Toggle" />;
+```
+
+<Canvas>
+  <DSProvider>
+    <Toggle
+      isChecked={true}
+      onChange={(e) => {
+        console.log(e.target.value);
+      }}
+      labelText="Controlled Toggle"
+    />
+  </DSProvider>
+</Canvas>
+
+## Browser States
+
+<Canvas>
+  <DSProvider>
+    <SimpleGrid columns="3">
+      <VStack align="left" spacing="s">
+        <Heading level={3}>Default</Heading>
+        <Toggle size={ToggleSizes.Large} defaultChecked={true} labelText="On" />
+        <Toggle size={ToggleSizes.Large} labelText="Off" />
+      </VStack>
+      <VStack align="left" spacing="s">
+        <Heading level={3}>Disabled</Heading>
+        <Toggle
+          size={ToggleSizes.Large}
+          defaultChecked={true}
+          isDisabled={true}
+          labelText="On"
+        />
+        <Toggle size={ToggleSizes.Large} labelText="Off" isDisabled={true} />
+      </VStack>
+      <VStack align="left" spacing="s">
+        <Heading level={3}>Error</Heading>
+        <Toggle
+          size={ToggleSizes.Large}
+          defaultChecked={true}
+          labelText="On"
+          isInvalid={true}
+        />
+        <Toggle size={ToggleSizes.Large} labelText="Off" isInvalid={true} />
+      </VStack>
+    </SimpleGrid>
+  </DSProvider>
+</Canvas>
+
+## Layouts
+
+<Canvas>
+  <DSProvider>
+    <SimpleGrid columns="2">
+      <VStack align="left" spacing="s">
+        <Heading level={3}>Grouped</Heading>
+        <Toggle defaultChecked={true} labelText="On" />
+        <Toggle defaultChecked={true} labelText="On" />
+        <Toggle defaultChecked={true} labelText="On" />
+        <Toggle defaultChecked={true} labelText="On" />
+        <Toggle defaultChecked={true} labelText="On" />
+      </VStack>
+      <VStack align="left" spacing="s">
+        <Heading level={3}>With Helper Text</Heading>
+        <Toggle
+          defaultChecked={true}
+          labelText="On"
+          helperText="Component Helper Text"
+        />
+      </VStack>
+    </SimpleGrid>
+  </DSProvider>
+</Canvas>