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

package/src/components/Autosuggest/Autosuggest.stories.mdx

@@ -0,0 +1,75 @@
+import { Canvas, Meta, Story } from "@storybook/addon-docs";
+import Autosuggest from "react-autosuggest";
+
+import * as stories from "./Autosuggest.stories.tsx";
+import { getCategory } from "../../utils/componentCategories";
+
+<Meta title={getCategory("Autosuggest")} component={Autosuggest} />
+
+# Autosuggest
+
+The Reservoir Design System (DS) does not have its own `Autosuggest` component. Instead,
+we are currently using the
+[react-autosuggest](https://www.npmjs.com/package/react-autosuggest) package.
+We recommend using this package in your application and wrapping it in a [custom
+component](#code-implementation). The Reservoir Design System (DS) does have custom
+styling that targets the classes from the `react-autosuggest` package, so the look
+and feel will be consistent.
+
+In the following previews, you'll notice that there is a lot of white space underneath
+every input element. Since the suggestion dropdown will appear on top of page content,
+we've added a min-height to make it easier to see the dropdown. This is for demonstration
+purposes only and you will not need to do this in your application.
+
+<Canvas withToolbar>
+  <Story name="Basic" story={stories.AutosuggestLibrary} />
+</Canvas>
+
+## With custom icons
+
+You can customize how suggestions appear by updating what the
+`renderSuggestion` function returns. In the following example, an `Icon`
+component is added to render a checkmark after each suggestion. View it by
+typing "c" or "tr" in the following input.
+
+```jsx
+const renderSuggestion = (suggestion) => (
+  <span>
+    {suggestion}
+    <Icon name="check" />
+  </span>
+);
+```
+
+<Story name="With custom icons" story={stories.AutosuggestFish} />
+
+## Code Implementation
+
+In order to use the `Autosuggest` component, we suggest wrapping it a custom
+component that stores state. State is needed to keep track of all the
+suggestions and of the current input value. The custom component returns the
+`Autosuggest` component with the following suggested props:
+
+```
+<Autosuggest
+  suggestions={suggestions}
+  onSuggestionsFetchRequested={onSuggestionsFetchRequested}
+  onSuggestionsClearRequested={onSuggestionsClearRequested}
+  getSuggestionValue={getSuggestionValue}
+  renderSuggestion={renderSuggestion}
+  inputProps={inputProps}
+  renderInputComponent={renderInputComponent}
+/>
+```
+
+| prop                          | notes                                                                                                                                         |
+| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| `suggestions`                 | The array of suggestions to use based on the component's state. An example can be using `const [suggestions, setSuggestions] = useState([]);` |
+| `onSuggestionsFetchRequested` | Function that Autosuggest will call every time suggestions need to be updated.                                                                |
+| `onSuggestionsClearRequested` | Function to clear out all current suggestions.                                                                                                |
+| `getSuggestionValue`          | A suggestion can be a string or an object. If it is an object, this function tells it what property to use in the object.                     |
+| `renderSuggestion`            | This function controls the output of each suggestion.                                                                                         |
+| `inputProps`                  | An object with props for the `input` component.                                                                                               |
+| `renderInputComponent`        | This function allows overriding the `input` component as well as the structure with other components, such as `label`.                        |
+
+Check `/src/components/Autosuggest/Autosuggest.stories.tsx` for two detailed examples.

package/src/components/Autosuggest/Autosuggest.stories.tsx

@@ -0,0 +1,211 @@
+import React, { useState } from "react";
+
+import Autosuggest from "react-autosuggest";
+import Icon from "../Icons/Icon";
+import TextInput from "../TextInput/TextInput";
+
+/**
+ * StoryWrapper
+ * Wrapper component just to give the Autosuggest examples more space for the
+ * suggestions dropdown to display.
+ */
+const StoryWrapper = ({ children }: { children: JSX.Element }) => (
+  <div style={{ padding: "5px", minHeight: "400px" }}>{children}</div>
+);
+
+const libraryRenderInputComponent = (inputProps: any) => {
+  return (
+    <TextInput
+      id="library-autosuggest"
+      isRequired
+      labelText="Home Library"
+      name="homeLibraryName"
+      helperText="Select your home library. Start by typing the name of the library. Try 'ba'."
+      {...inputProps}
+    />
+  );
+};
+
+interface Library {
+  label: string;
+}
+
+/**
+ * LibraryExample
+ * An example component that internally uses the `react-autosuggest` library.
+ * The list is made up of objects with `label` key. It adds a Label, Input, and
+ * HelperErrorText as elements for the autosuggest component to render.
+ */
+const LibraryExample = ({
+  renderInputComponent,
+}: {
+  renderInputComponent: JSX.Element;
+}) => {
+  const [value, setValue] = useState("");
+  const [suggestions, setSuggestions] = useState([]);
+  const libraryList: Library[] = [
+    { label: "SimplyE" },
+    { label: "53rd Street Branch" },
+    { label: "Aguilar Branch" },
+    { label: "Allerton Branch" },
+    { label: "Battery Park City" },
+    { label: "Baychester Branch" },
+    { label: "Belmont Branch" },
+    { label: "South Beach Branch" },
+    { label: "St. Agnes" },
+    { label: "Sedgwick Branch" },
+    { label: "Seward Park Branch" },
+    { label: "Soundview Branch" },
+    { label: "St. George Library Center" },
+  ];
+  const onChange = (_: any, { newValue }: { newValue: string }) =>
+    setValue(newValue);
+  // Tell autosuggest to suggest by the first letter of the library. This can
+  // be manipulated.
+  const getSuggestions = (value: string, list: Library[]) => {
+    const inputValue = value.trim().toLowerCase();
+    const inputLength = inputValue.length;
+
+    return inputLength === 0
+      ? []
+      : list.filter(
+          (l) => l.label.toLowerCase().slice(0, inputLength) === inputValue
+        );
+  };
+
+  // Autosuggest will call this function every time suggestions need to be
+  // updated. `getSuggestions` must be passed.
+  const onSuggestionsFetchRequested = ({ value }: { value: string }) =>
+    setSuggestions(getSuggestions(value, libraryList));
+  // Clear out any suggestions.
+  const onSuggestionsClearRequested = () => setSuggestions([]);
+
+  // When suggestion is clicked, Autosuggest needs to populate the input
+  // based on the clicked suggestion. We want the label from that object.
+  const getSuggestionValue = (suggestion) => suggestion.label;
+  // Render every suggestion in a span.
+  const renderSuggestion = (suggestion) => <span>{suggestion.label}</span>;
+  // Autosuggest will pass through all these props to the Input component.
+  const inputProps = {
+    "aria-label": "Home Library",
+    placeholder: "Type a library name",
+    value,
+    onChange,
+  };
+
+  return (
+    <Autosuggest
+      suggestions={suggestions}
+      onSuggestionsFetchRequested={onSuggestionsFetchRequested}
+      onSuggestionsClearRequested={onSuggestionsClearRequested}
+      getSuggestionValue={getSuggestionValue}
+      renderSuggestion={renderSuggestion}
+      inputProps={inputProps}
+      renderInputComponent={renderInputComponent}
+    />
+  );
+};
+
+export const AutosuggestLibrary = () => (
+  <StoryWrapper>
+    <LibraryExample renderInputComponent={libraryRenderInputComponent as any} />
+  </StoryWrapper>
+);
+
+/**
+ * FishExample
+ * An example component that internally uses the `react-autosuggest` library.
+ * The list is made up of strings. It adds an Input element for the autosuggest
+ * component to render and renders the Label separately.
+ */
+const FishExample = () => {
+  const [value, setValue] = useState("");
+  const [suggestions, setSuggestions] = useState([]);
+  const fishList = [
+    "sea bass",
+    "mahi mahi",
+    "pale chub",
+    "carp",
+    "ranchu goldfish",
+    "char",
+    "golden trout",
+    "crawfish",
+    "catfish",
+    "neon tetra",
+    "blowfish",
+  ];
+  const renderInputComponent = (inputProps) => {
+    return (
+      <TextInput
+        id="library-fish-autosuggest"
+        labelText="Fish in Animal Crossing"
+        name="favoriteFish"
+        {...inputProps}
+      />
+    );
+  };
+  const onChange = (_: any, { newValue }) => setValue(newValue);
+  // Just adding a simple icon to show how suggestions can be rendered.
+  const renderSuggestion = (suggestion) => (
+    <span>
+      {suggestion}
+      <Icon name="check" size="medium" />
+    </span>
+  );
+  const getSuggestionValue = (suggestion) => suggestion;
+  // Here, we want to filter suggestions if we can the user-typed string in
+  // any of the suggestion string list.
+  const getSuggestions = (value, list) => {
+    const inputValue = value.trim().toLowerCase();
+    const inputLength = inputValue.length;
+
+    return inputLength === 0
+      ? []
+      : list.filter((l) => l.indexOf(inputValue) !== -1);
+  };
+  const onSuggestionsFetchRequested = ({ value }) =>
+    setSuggestions(getSuggestions(value, fishList));
+  const onSuggestionsClearRequested = () => setSuggestions([]);
+  const inputProps = {
+    placeholder: "Try the letter 'c' or 'tr'",
+    value,
+    onChange,
+  };
+
+  return (
+    <>
+      <Autosuggest
+        suggestions={suggestions}
+        onSuggestionsFetchRequested={onSuggestionsFetchRequested}
+        onSuggestionsClearRequested={onSuggestionsClearRequested}
+        getSuggestionValue={getSuggestionValue}
+        renderSuggestion={renderSuggestion}
+        inputProps={inputProps}
+        renderInputComponent={renderInputComponent}
+        highlightFirstSuggestion={true}
+      />
+    </>
+  );
+};
+
+export const AutosuggestFish = () => (
+  <StoryWrapper>
+    <FishExample />
+  </StoryWrapper>
+);
+
+const searchBarRenderInputComponent = (inputProps: any) => {
+  return (
+    <TextInput
+      id="autosuggest-searchBar"
+      isRequired
+      labelText="home library"
+      name="homeLibraryName"
+      {...inputProps}
+    />
+  );
+};
+
+export const SearchBarExample = () => (
+  <LibraryExample renderInputComponent={searchBarRenderInputComponent as any} />
+);

package/src/components/Autosuggest/_Autosuggest.scss

@@ -0,0 +1,51 @@
+// React Autosuggest
+.react-autosuggest__container {
+  display: inline;
+  position: relative;
+  width: 100%;
+}
+
+.react-autosuggest__input--focused {
+  outline: none;
+}
+
+.react-autosuggest__input--open {
+  border-bottom-left-radius: 0;
+  border-bottom-right-radius: 0;
+  width: 100%;
+}
+
+.react-autosuggest__suggestions-container {
+  display: none;
+  width: 100%;
+}
+
+.react-autosuggest__suggestions-container--open {
+  background-color: var(--nypl-colors-ui-white);
+  display: block;
+  font-weight: 300;
+  margin-top: 1px; // accounts for the focus ring on the input
+  outline: 1px solid var(--nypl-colors-ui-gray-light-cool);
+  position: relative;
+  width: 100%;
+  z-index: 2;
+}
+
+.react-autosuggest__suggestions-list {
+  list-style-type: none;
+  margin: 0;
+  padding: 0;
+}
+
+.react-autosuggest__suggestion {
+  cursor: pointer;
+  padding: var(--nypl-space-xs);
+}
+
+.react-autosuggest__suggestion--highlighted {
+  background-color: var(--nypl-colors-ui-gray-light-cool);
+}
+
+.auto-suggest-bottom {
+  padding: var(--nypl-space-xs);
+}

package/src/components/Breadcrumbs/Breadcrumbs.stories.mdx

@@ -0,0 +1,231 @@
+import {
+  ArgsTable,
+  Canvas,
+  Description,
+  Meta,
+  Story,
+} from "@storybook/addon-docs";
+import { withDesign } from "storybook-addon-designs";
+
+import Breadcrumbs, { BreadcrumbsTypes } from "./Breadcrumbs";
+import Heading from "../Heading/Heading";
+import Link from "../Link/Link";
+import { getCategory } from "../../utils/componentCategories";
+import DSProvider from "../../theme/provider";
+
+<Meta
+  title={getCategory("Breadcrumbs")}
+  component={Breadcrumbs}
+  decorators={[withDesign]}
+  parameters={{
+    design: {
+      type: "figma",
+      url: "https://www.figma.com/file/qShodlfNCJHb8n03IFyApM/Main?node-id=10766%3A1031",
+    },
+    jest: ["Breadcrumbs.test.tsx"],
+  }}
+  argTypes={{
+    breadcrumbsData: { control: false },
+    breadcrumbsType: {
+      table: { defaultValue: { summary: "whatsOn" } },
+    },
+    className: { control: false },
+    id: { control: false },
+  }}
+/>
+
+# Breadcrumbs
+
+| Component Version | DS Version |
+| ----------------- | ---------- |
+| Added             | `0.0.3`    |
+| Latest            | `0.28.0`   |
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Component Props](#component-props)
+- [Accessibility](#accessibility)
+- [Long Titles](#long-titles)
+- [Color Variations](#color-variations)
+
+## Overview
+
+<Description of={Breadcrumbs} />
+
+The `Breadcrumbs` component is a navigation element that provides a breadcrumb
+path that reflects the site structure and allows a user to navigate to any page
+available in the breadcrumb hierarchy.
+
+## Component Props
+
+<Canvas withToolbar>
+  <Story
+    name="Breadcrumbs with Controls"
+    args={{
+      breadcrumbsData: [
+        { url: "#", text: "Parent" },
+        { url: "#", text: "Child" },
+        { url: "#", text: "Grandchild" },
+      ],
+      className: undefined,
+      breadcrumbsType: "whatsOn",
+      id: "breadcrumbs-id",
+    }}
+  >
+    {(args) => <Breadcrumbs {...args} />}
+  </Story>
+</Canvas>
+
+<ArgsTable story="Breadcrumbs with Controls" />
+
+### Accessibility
+
+Only one `Breadcrumbs` component should be rendered on a page. This is because
+only one HTML `<nav>` element with an `aria-label` attribute value of
+"Breadcrumbs" should be rendered on a page. The DS `Breadcrumbs` component
+renders this HTML landmark so only one component must be rendered on a page.
+
+Internally, links are organized in a `ul` list element. The current page link is
+denoted by an `aria-current` attribute value of "page".
+
+- [W3 Breadcrumbs Practice](https://www.w3.org/TR/wai-aria-practices/examples/breadcrumb/index.html)
+- [Chakra UI Breadcrumb](https://chakra-ui.com/docs/components/navigation/breadcrumb)
+
+## Long Titles
+
+<Canvas>
+  <DSProvider>
+    <Breadcrumbs
+      breadcrumbsData={[
+        { url: "#", text: "Parent with a Long Name" },
+        { url: "#", text: "Child with an Even Longer Name" },
+        {
+          url: "#",
+          text: "Grandchild with an Exceptionally Long Name",
+        },
+        {
+          url: "#",
+          text: "Great-Grandchild with the Longest Name That Will Wrap onto the Second Line of the Breadcrumb Component Under the Right Circumstances",
+        },
+      ]}
+    />
+  </DSProvider>
+</Canvas>
+
+## Color Variations
+
+The `Breadcrumbs` component background color can be set to a value of the
+`breadcrumbsType` type. If the `breadcrumbsType` prop is omitted, the default
+background color is `"whatsOn"` (`ui.black`).
+
+<Canvas>
+  <Story
+    name="Color Variations"
+    args={{
+      breadcrumbsType: "blogs",
+    }}
+  >
+    {(args) => (
+      <>
+        <Heading level="three">Blogs</Heading>
+        <Breadcrumbs
+          breadcrumbsData={[
+            { url: "#", text: "Parent" },
+            { url: "#", text: "Child" },
+            {
+              url: "#",
+              text: "Grandchild",
+            },
+          ]}
+          breadcrumbsType={args.breadcrumbsType}
+        />
+      </>
+    )}
+  </Story>
+</Canvas>
+
+<Canvas>
+  <DSProvider>
+    <Heading level="three">Books and More</Heading>
+    <Breadcrumbs
+      breadcrumbsData={[
+        { url: "#", text: "Parent" },
+        { url: "#", text: "Child" },
+        {
+          url: "#",
+          text: "Grandchild",
+        },
+      ]}
+      breadcrumbsType="booksAndMore"
+    />
+  </DSProvider>
+</Canvas>
+
+<Canvas>
+  <DSProvider>
+    <Heading level="three">Education</Heading>
+    <Breadcrumbs
+      breadcrumbsData={[
+        { url: "#", text: "Parent" },
+        { url: "#", text: "Child" },
+        {
+          url: "#",
+          text: "Grandchild",
+        },
+      ]}
+      breadcrumbsType="education"
+    />
+  </DSProvider>
+</Canvas>
+
+<Canvas>
+  <DSProvider>
+    <Heading level="three">Locations</Heading>
+    <Breadcrumbs
+      breadcrumbsData={[
+        { url: "#", text: "Parent" },
+        { url: "#", text: "Child" },
+        {
+          url: "#",
+          text: "Grandchild",
+        },
+      ]}
+      breadcrumbsType="locations"
+    />
+  </DSProvider>
+</Canvas>
+
+<Canvas>
+  <DSProvider>
+    <Heading level="three">Research</Heading>
+    <Breadcrumbs
+      breadcrumbsData={[
+        { url: "#", text: "Parent" },
+        { url: "#", text: "Child" },
+        {
+          url: "#",
+          text: "Grandchild",
+        },
+      ]}
+      breadcrumbsType="research"
+    />
+  </DSProvider>
+</Canvas>
+
+<Canvas>
+  <DSProvider>
+    <Heading level="three">What's On</Heading>
+    <Breadcrumbs
+      breadcrumbsData={[
+        { url: "#", text: "Parent" },
+        { url: "#", text: "Child" },
+        {
+          url: "#",
+          text: "Grandchild",
+        },
+      ]}
+      breadcrumbsType="whatsOn"
+    />
+  </DSProvider>
+</Canvas>