@nypl/design-system-react-components 0.25.5 → 0.25.9

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

@@ -1,16 +1,22 @@
+import { VStack } from "@chakra-ui/react";
 import {
-  Meta,
-  Story,
-  Canvas,
   ArgsTable,
+  Canvas,
   Description,
-} from "@storybook/addon-docs/blocks";
+  Meta,
+  Story,
+} from "@storybook/addon-docs";
 import { withDesign } from "storybook-addon-designs";
 
-import { VStack } from "@chakra-ui/react";
+import Button from "../Button/Button";
+import Form from "../Form/Form";
 import Select from "./Select";
+import { SelectTypes } from "./SelectTypes";
 import { getCategory } from "../../utils/componentCategories";
 import DSProvider from "../../theme/provider";
+import { getStorybookEnumValues } from "../../utils/utils";
+
+export const enumValues = getStorybookEnumValues(SelectTypes, "SelectTypes");
 
 <Meta
   title={getCategory("Select")}
@@ -19,17 +25,40 @@ 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"],
   }}
   argTypes={{
     children: { table: { disable: true } },
-    id: { table: { disable: true } },
-    name: { table: { disable: true } },
-    onChange: { table: { disable: true } },
-    value: { table: { disable: true } },
+    id: { control: false },
+    isDisabled: {
+      table: { defaultValue: { summary: false } },
+    },
+    isInvalid: {
+      table: { defaultValue: { summary: false } },
+    },
+    isRequired: {
+      table: { defaultValue: { summary: false } },
+    },
+    name: { control: false },
+    key: { table: { disable: true } },
+    onChange: { control: false },
+    ref: { table: { disable: true } },
+    showHelperInvalidText: {
+      table: { defaultValue: { summary: true } },
+    },
+    showLabel: {
+      table: { defaultValue: { summary: true } },
+    },
+    showOptReqLabel: {
+      table: { defaultValue: { summary: true } },
+    },
+    type: {
+      control: false,
+      table: { defaultValue: { summary: "SelectTypes.Default" } },
+    },
+    value: { control: false },
   }}
 />
 
@@ -38,7 +67,7 @@ import DSProvider from "../../theme/provider";
 | Component Version | DS Version |
 | ----------------- | ---------- |
 | Added             | `0.7.0`    |
-| Latest            | `0.25.1`   |
+| Latest            | `0.25.9`   |
 
 <Description of={Select} />
 
@@ -63,17 +92,23 @@ elements, but the select options _need_ to be child `<option>` HTML elements.
 
 <Canvas withToolbar>
   <Story
-    name="Select"
+    name="Select with Controls"
     args={{
+      className: undefined,
       helperText: "This is the helper text.",
+      id: "select-id",
       invalidText: "This is the error text :(",
       isDisabled: false,
       isInvalid: false,
       isRequired: false,
       labelText: "What is your favorite color?",
       name: "color",
+      onChange: undefined,
+      showHelperInvalidText: undefined,
       showLabel: true,
       showOptReqLabel: true,
+      type: SelectTypes.Default,
+      value: undefined,
     }}
   >
     {(args) => (
@@ -88,7 +123,7 @@ elements, but the select options _need_ to be child `<option>` HTML elements.
   </Story>
 </Canvas>
 
-<ArgsTable story="Select" />
+<ArgsTable story="Select with Controls" />
 
 ## Labelling Variations
 
@@ -102,8 +137,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 +148,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 +160,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 +172,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 +193,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 +213,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 +233,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

@@ -5,23 +5,25 @@ import {
   useMultiStyleConfig,
 } from "@chakra-ui/react";
 
-import Label from "../Label/Label";
-import HelperErrorText from "../HelperErrorText/HelperErrorText";
-import generateUUID from "../../helpers/generateUUID";
-import { IconNames, IconSizes } from "../Icons/IconTypes";
+import HelperErrorText, {
+  HelperErrorTextType,
+} from "../HelperErrorText/HelperErrorText";
 import Icon from "../Icons/Icon";
+import { IconNames, IconSizes } from "../Icons/IconTypes";
+import Label from "../Label/Label";
 import { SelectTypes } from "./SelectTypes";
+import generateUUID from "../../helpers/generateUUID";
 
 export interface SelectProps {
   /** A class name for the `div` parent element. */
   className?: string;
   /** Optional string to populate the `HelperErrorText` for the standard state. */
-  helperText?: string;
+  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?: string;
+  invalidText?: HelperErrorTextType;
   /** Adds the `disabled` and `aria-disabled` attributes to the select when true */
   isDisabled?: boolean;
   /** Adds the `aria-invalid` attribute to the select when true. This also makes
@@ -38,6 +40,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 +76,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";
@@ -84,10 +89,12 @@ const Select = React.forwardRef<
   const finalInvalidText = invalidText
     ? invalidText
     : "There is an error related to this field.";
-  const footnote = isInvalid ? finalInvalidText : helperText;
+  const footnote: HelperErrorTextType = 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 +133,7 @@ const Select = React.forwardRef<
         isDisabled={isDisabled}
         isInvalid={isInvalid}
         name={name}
+        placeholder={placeholder}
         ref={ref}
         {...controlledProps}
         {...ariaAttributes}
@@ -136,9 +144,11 @@ const Select = React.forwardRef<
       </ChakraSelect>
       {footnote && showHelperInvalidText && (
         <Box __css={styles.helper} aria-disabled={isDisabled}>
-          <HelperErrorText isInvalid={isInvalid} id={id + `-helperText`}>
-            {footnote}
-          </HelperErrorText>
+          <HelperErrorText
+            id={`${id}-helperText`}
+            isInvalid={isInvalid}
+            text={footnote}
+          />
         </Box>
       )}
     </Box>

package/src/components/SkeletonLoader/SkeletonLoader.stories.mdx

@@ -1,20 +1,30 @@
+import { action } from "@storybook/addon-actions";
 import {
-  Meta,
-  Story,
-  Canvas,
   ArgsTable,
+  Canvas,
   Description,
-} from "@storybook/addon-docs/blocks";
+  Meta,
+  Story,
+} from "@storybook/addon-docs";
 import { withDesign } from "storybook-addon-designs";
-import { action } from "@storybook/addon-actions";
 
-import { getCategory } from "../../utils/componentCategories";
+import SimpleGrid from "../Grid/SimpleGrid";
 import SkeletonLoader from "./SkeletonLoader";
 import {
-  SkeletonLoaderLayouts,
   SkeletonLoaderImageRatios,
+  SkeletonLoaderLayouts,
 } from "./SkeletonLoaderTypes";
-import SimpleGrid from "../Grid/SimpleGrid";
+import { getCategory } from "../../utils/componentCategories";
+import { getStorybookEnumValues } from "../../utils/utils";
+
+export const imageRatiosEnumValues = getStorybookEnumValues(
+  SkeletonLoaderImageRatios,
+  "SkeletonLoaderImageRatios"
+);
+export const layoutsEnumValues = getStorybookEnumValues(
+  SkeletonLoaderLayouts,
+  "SkeletonLoaderLayouts"
+);
 
 <Meta
   title={getCategory("SkeletonLoader")}
@@ -23,17 +33,25 @@ import SimpleGrid from "../Grid/SimpleGrid";
   parameters={{
     design: {
       type: "figma",
-      url:
-        "https://www.figma.com/file/qShodlfNCJHb8n03IFyApM/Master?node-id=17219%3A7",
+      url: "https://www.figma.com/file/qShodlfNCJHb8n03IFyApM/Master?node-id=17219%3A7",
     },
     jest: ["SkeletonLoader.test.tsx"],
   }}
   argTypes={{
-    className: { table: { disable: true } },
+    className: { control: false },
     contentSize: { table: { defaultValue: { summary: "3" } } },
     headingSize: { table: { defaultValue: { summary: "1" } } },
-    imageAspectRatio: { table: { defaultValue: { summary: "square" } } },
-    layout: { table: { defaultValue: { summary: "column" } } },
+    imageAspectRatio: {
+      control: { type: "select" },
+      table: {
+        defaultValue: { summary: "SkeletonLoaderImageRatios.Square" },
+      },
+      options: imageRatiosEnumValues.options,
+    },
+    layout: {
+      table: { defaultValue: { summary: "SkeletonLoaderLayouts.Column" } },
+      options: layoutsEnumValues.options,
+    },
     showButton: { table: { defaultValue: { summary: "false" } } },
     showContent: { table: { defaultValue: { summary: "true" } } },
     showHeading: { table: { defaultValue: { summary: "true" } } },
@@ -58,16 +76,32 @@ to better view the example. The default value is `100%`.
 
 <Canvas withToolbar>
   <Story
-    name="Basic with Props"
+    name="SkeletonLoader with Controls"
     args={{
+      border: false,
+      className: undefined,
+      contentSize: 3,
+      headingSize: 1,
+      imageAspectRatio: "SkeletonLoaderImageRatios.Square",
+      layout: "SkeletonLoaderLayouts.Column",
+      showButton: false,
+      showContent: true,
+      showHeading: true,
+      showImage: true,
       width: "300px",
     }}
   >
-    {(args) => <SkeletonLoader {...args} />}
+    {(args) => (
+      <SkeletonLoader
+        {...args}
+        imageAspectRatio={imageRatiosEnumValues.getValue(args.imageAspectRatio)}
+        layout={layoutsEnumValues.getValue(args.layout)}
+      />
+    )}
   </Story>
 </Canvas>
 
-<ArgsTable story="Basic with Props" />
+<ArgsTable story="SkeletonLoader with Controls" />
 
 # Card Placeholders in a Grid
 

package/src/components/SkeletonLoader/SkeletonLoader.tsx

@@ -15,13 +15,17 @@ export interface SkeletonLoaderProps {
   border?: boolean;
   /** Additional class name for the Skeleton component. */
   className?: string;
-  /** Optional numeric value to control the number of lines for content placeholder; default value is `3`. */
+  /** Optional numeric value to control the number of lines for content
+   * placeholder; default value is `3`. */
   contentSize?: number;
-  /** Optional numeric value to control the number of lines for heading placeholder; default value is `1`. */
+  /** Optional numeric value to control the number of lines for heading
+   * placeholder; default value is `1`. */
   headingSize?: number;
-  /** Optional value to control the aspect ratio of the image placeholder; default value is `square`. */
+  /** Optional value to control the aspect ratio of the image placeholder;
+   * default value is `SkeletonLoaderImageRatios.Square`. */
   imageAspectRatio?: SkeletonLoaderImageRatios;
-  /** Optional value to control the position of the image placeholder; default value is `column`. */
+  /** Optional value to control the position of the image placeholder;
+   * default value is `SkeletonLoaderLayouts.Column`. */
   layout?: SkeletonLoaderLayouts;
   /** Optional boolean value to control visibility of button placeholder. */
   showButton?: boolean;