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

package/src/components/VideoPlayer/__snapshots__/VideoPlayer.test.tsx.snap

@@ -2,12 +2,12 @@
 
 exports[`VideoPlayer renders the UI snapshot correctly 1`] = `
 <div
-  className="css-0"
+  className="css-1xdhyk6"
   data-testid="video-player-component"
   id="video-player-without-text"
 >
   <div
-    className="css-0"
+    className="css-1xdhyk6"
   >
     <div
       className="css-0"
@@ -27,21 +27,21 @@ exports[`VideoPlayer renders the UI snapshot correctly 1`] = `
 
 exports[`VideoPlayer renders the UI snapshot correctly 2`] = `
 <div
-  className="css-0"
+  className="css-1xdhyk6"
   data-testid="video-player-component"
   id="video-player-with-text"
 >
   <div
-    className="css-0"
+    className="css-1xdhyk6"
   >
     <h2
-      className="chakra-heading css-0"
+      className="chakra-heading css-1xdhyk6"
       id="video-player-with-text-componentWrapper-heading"
     >
       VideoPlayer Heading
     </h2>
     <p
-      className="chakra-text css-0"
+      className="chakra-text css-1xdhyk6"
     >
       VideoPlayer description
     </p>
@@ -58,42 +58,38 @@ exports[`VideoPlayer renders the UI snapshot correctly 2`] = `
       />
     </div>
     <div
-      className="css-0"
-    >
-      <div
-        aria-atomic={true}
-        aria-live="off"
-        className=" css-0"
-        dangerouslySetInnerHTML={
-          Object {
-            "__html": "VideoPlayer helper test.",
-          }
+      aria-atomic={true}
+      aria-live="off"
+      className="css-1xdhyk6"
+      dangerouslySetInnerHTML={
+        Object {
+          "__html": "VideoPlayer helper test.",
         }
-        data-isinvalid={false}
-        id="video-player-with-text-componentWrapper-helperText"
-      />
-    </div>
+      }
+      data-isinvalid={false}
+      id="video-player-with-text-componentWrapper-helperText"
+    />
   </div>
 </div>
 `;
 
 exports[`VideoPlayer renders the UI snapshot correctly 3`] = `
 <div
-  className="css-0"
+  className="css-1xdhyk6"
   data-testid="video-player-component"
   id="video-player-with-text"
 >
   <div
-    className="css-0"
+    className="css-1xdhyk6"
   >
     <h2
-      className="chakra-heading css-0"
+      className="chakra-heading css-1xdhyk6"
       id="video-player-with-text-componentWrapper-heading"
     >
       VideoPlayer Heading
     </h2>
     <p
-      className="chakra-text css-0"
+      className="chakra-text css-1xdhyk6"
     >
       VideoPlayer description
     </p>
@@ -109,28 +105,24 @@ exports[`VideoPlayer renders the UI snapshot correctly 3`] = `
       />
     </div>
     <div
-      className="css-0"
-    >
-      <div
-        aria-atomic={true}
-        aria-live="off"
-        className=" css-0"
-        dangerouslySetInnerHTML={
-          Object {
-            "__html": "VideoPlayer helper test.",
-          }
+      aria-atomic={true}
+      aria-live="off"
+      className="css-1xdhyk6"
+      dangerouslySetInnerHTML={
+        Object {
+          "__html": "VideoPlayer helper test.",
         }
-        data-isinvalid={false}
-        id="video-player-with-text-componentWrapper-helperText"
-      />
-    </div>
+      }
+      data-isinvalid={false}
+      id="video-player-with-text-componentWrapper-helperText"
+    />
   </div>
 </div>
 `;
 
 exports[`VideoPlayer renders the UI snapshot correctly 4`] = `
 <div
-  className="css-0"
+  className="css-1xdhyk6"
   data-testid="video-player-component"
   id="video-player-error"
 >
@@ -143,3 +135,53 @@ exports[`VideoPlayer renders the UI snapshot correctly 4`] = `
   />
 </div>
 `;
+
+exports[`VideoPlayer renders the UI snapshot correctly 5`] = `
+<div
+  className="css-kle7zy"
+  data-testid="video-player-component"
+  id="chakra"
+>
+  <div
+    className="css-1xdhyk6"
+  >
+    <div
+      className="css-0"
+    >
+      <iframe
+        allow="accelerometer; autoplay; clipboard-write; encrypted-media; fullscreen; gyroscope; picture-in-picture"
+        allowFullScreen={true}
+        className="css-0"
+        frameBorder="0"
+        src="https://player.vimeo.com/video/474719268?autoplay=0&loop=0"
+        title="Vimeo video player"
+      />
+    </div>
+  </div>
+</div>
+`;
+
+exports[`VideoPlayer renders the UI snapshot correctly 6`] = `
+<div
+  className="css-1xdhyk6"
+  data-testid="props"
+  id="props"
+>
+  <div
+    className="css-1xdhyk6"
+  >
+    <div
+      className="css-0"
+    >
+      <iframe
+        allow="accelerometer; autoplay; clipboard-write; encrypted-media; fullscreen; gyroscope; picture-in-picture"
+        allowFullScreen={true}
+        className="css-0"
+        frameBorder="0"
+        src="https://player.vimeo.com/video/474719268?autoplay=0&loop=0"
+        title="Vimeo video player"
+      />
+    </div>
+  </div>
+</div>
+`;

package/src/docs/Chakra.stories.mdx

@@ -1,5 +1,9 @@
 import { Meta } from "@storybook/addon-docs";
 
+import Button from "../components/Button/Button";
+import Text from "../components/Text/Text";
+import DSProvider from "../theme/provider";
+
 <Meta title="Chakra UI" />
 
 # Chakra UI
@@ -10,19 +14,20 @@ import { Meta } from "@storybook/addon-docs";
 | 2. [DSProvider](#dsprovider)        |
 | 3. [Components](#components)        |
 | 4. [Styling](#styling)              |
-| 5. [Hooks](#hooks)                  |
-| 5. [Testing](#testing)              |
+| 5. [Style Props](#style-props)      |
+| 6. [Hooks](#hooks)                  |
+| 7. [Testing](#testing)              |
 
 ## Why Chakra UI?
 
-The NYPL Design System (DS) project was influenced by other design systems but
+The Reservoir Design System (DS) project was influenced by other design systems but
 ultimately we decided to initially build DS components from scratch rather than
 use another design system as its foundation. To better help all the projects at
 NYPL and to better scale with all the components we have built and still need to
-build, we decided to integrate Chakra UI into the NYPL Design System.
+build, we decided to integrate Chakra UI into the DS.
 
 Chakra UI is an open source component library that is opinionated and uses design
-and development patterns that various projects at NYPL use. Since the NYPL DS
+and development patterns that various projects at NYPL use. Since the DS
 will be the foundation for all NYPL projects moving forward, using Chakra will
 help us align all projects so similar patterns are used throughout various teams
 and projects.
@@ -38,7 +43,7 @@ We recommend to read Chakra's own [documentation](https://chakra-ui.com/docs/get
 to get up to speed on it. This file will provide information on how it is used
 in the DS but we rely on Chakra's documentation.
 
-If you need help updating to a newer version of the NYPL Design System, check out
+If you need help updating to a newer version of the DS, check out
 our [Chakra Migration Guide](https://github.com/NYPL/nypl-design-system/blob/development/CHAKRA_MIGRATION_GUIDE.md).
 
 ## DSProvider
@@ -411,6 +416,42 @@ All typography values can be found in the `src/theme/foundations/typography.ts`
 file. These values declare the font family, font sizes, and font weights to use
 for all text.
 
+## Style Props
+
+NYPL Reservoir components are built around the Chakra UI library. While Reservoir
+components may use the corresponding Chakra UI component, that is not always the
+case. Every Reservoir component, however, does make use of the Chakra UI
+"style props" pattern. This means that it is possible to pass in CSS rules to a
+component, including the shorthand versions. These style props will target the
+wrapper element of the component; this means if you want to target a specific
+element or component in a Reservoir component, you won't be able to with style
+props.
+
+<DSProvider>
+  <Text isBold>
+    While this is available to use, it is not recommended. If you see a need to
+    override styles, please reach out to the NYPL Reservoir team for assistance.
+  </Text>
+</DSProvider>
+
+In the following example, the `Button` component has been passed `p` and `maxW`
+props which are shorthand for "padding" and "max-width", respectively.
+
+```jsx
+<Button p="s" maxW="200px">
+  Button
+</Button>
+```
+
+<DSProvider>
+  <Button p="s" maxW="200px">
+    Button
+  </Button>
+</DSProvider>
+
+Find more information and a full list of all the available props, check the Chakra
+UI [Style Props page](https://chakra-ui.com/docs/styled-system/features/style-props).
+
 ## Hooks
 
 The following hooks are available to use and can be imported from
@@ -514,6 +555,6 @@ Use the `style` attribute in HTML components to add inline styles.
 ## Testing
 
 Do not re-test Chakra components that are re-exported since they are already
-tested in the `@chakra-ui/react` package. We do expect all new components
-composed from Chakra to have tests for functionality and styling
-(such as snapshots).
+tested in the `@chakra-ui/react` package. We expect all new components composed
+with Chakra components to have tests for functionality and styling, including
+snapshot tests.

package/src/docs/Welcome.stories.mdx

@@ -1,49 +1,168 @@
 import { Meta } from "@storybook/addon-docs";
 
-import Hero from "../components/Hero/Hero.tsx";
-import { HeroTypes } from "../components/Hero/HeroTypes.tsx";
-import Heading from "../components/Heading/Heading.tsx";
-import Image from "../components/Image/Image.tsx";
+import { Box, Center, Circle, VStack, Square } from "@chakra-ui/react";
+import Card, { CardHeading, CardContent } from "../components/Card/Card";
+import Hero from "../components/Hero/Hero";
+import { HeroTypes } from "../components/Hero/HeroTypes";
+import Heading from "../components/Heading/Heading";
+import {
+  HeadingLevels,
+  HeadingSizes,
+} from "../components/Heading/HeadingTypes";
+import Icon from "../components/Icons/Icon";
+import {
+  IconColors,
+  IconNames,
+  IconSizes,
+} from "../components/Icons/IconTypes";
+import Image from "../components/Image/Image";
+import Link from "../components/Link/Link";
+import { LinkTypes } from "../components/Link/LinkTypes";
+import Logo from "../components/Logo/Logo";
+import { LogoNames, LogoSizes } from "../components/Logo/LogoTypes";
+import SimpleGrid from "../components/Grid/SimpleGrid";
+import Text from "../components/Text/Text";
+import { TextSizes } from "../components/Text/TextTypes";
 import DSProvider from "../theme/provider";
 
 <Meta title="Welcome" />
 
-# NYPL Design System
-
-export const heroBackgroundColor = `var(--nypl-colors-section-books-and-more-primary)`;
-export const heroForegroundColor = `var(--nypl-colors-ui-white)`;
-
 <DSProvider>
-  <Hero
-    backgroundColor={heroBackgroundColor}
-    foregroundColor={heroForegroundColor}
-    heroType={HeroTypes.FiftyFifty}
-    imageAlt="NYPL Lion with mask on"
-    imageSrc="https://cdn-d8.nypl.org/s3fs-public/styles/2_1_960/public/2020-07/SASB_06_29_2020_Lions_mask-00207%20copy_0.jpeg?h=c8e955ed&itok=n_GLQgoe"
-    subHeaderText="With 92 locations across the Bronx, Manhattan, and Staten Island, The New York Public Library is an essential part of neighborhoods across the city. Visit us today."
-  />
+  <VStack spacing="s">
+    <Center>
+      <Logo name={LogoNames.ReservoirVerticalColor} size={LogoSizes.Small} />
+    </Center>
+    <Box>
+      <Center>
+        <Heading level={HeadingLevels.One} size={HeadingSizes.Tertiary}>
+          The React Component Library of the New York Public Library
+        </Heading>
+      </Center>
+      <Text>
+        Reservoir is NYPL's open-source extensible React component library for
+        products and experiences, with accessibility as its core. Aiming to
+        provide design and user experience consistency, Reservoir is the
+        foundation for all digital properties in the NYPL landscape, offering
+        functional components that implement the NYPL style standards.
+      </Text>
+    </Box>
+    <SimpleGrid>
+      <Box
+        style={{
+          alignItems: "center",
+          border: "1px solid #ccc",
+          display: "flex",
+          flexDirection: "column",
+          padding: "24px",
+        }}
+      >
+        <Icon
+          name={IconNames.ActionCheckCircle}
+          size={IconSizes.ExtraExtraLarge}
+          color={IconColors.SectionEducationSecondary}
+          additionalStyles={{
+            marginBottom: "s",
+          }}
+        />
+        <Card isCentered>
+          <CardHeading id="main-heading1" level={HeadingLevels.Three}>
+            Get Started
+          </CardHeading>
+          <CardContent>
+            <Text size={TextSizes.Caption}>
+              To start using Reservoir Design System, refer to Reservoir's
+              Github{" "}
+              <Link
+                href="https://github.com/NYPL/nypl-design-system/wiki"
+                type={LinkTypes.External}
+              >
+                Wiki
+              </Link>{" "}
+              and{" "}
+              <Link
+                href="https://github.com/NYPL/nypl-design-system/blob/development/README.md"
+                type={LinkTypes.External}
+              >
+                ReadMe
+              </Link>{" "}
+              to setup your project. You can also learn about our component
+              architecture and additional documentation.
+            </Text>
+          </CardContent>
+        </Card>
+      </Box>
+      <Box
+        style={{
+          alignItems: "center",
+          border: "1px solid #ccc",
+          display: "flex",
+          flexDirection: "column",
+          padding: "24px",
+        }}
+      >
+        <Icon
+          name={IconNames.Search}
+          size={IconSizes.ExtraExtraLarge}
+          color={IconColors.SectionEducationSecondary}
+          additionalStyles={{
+            marginBottom: "s",
+          }}
+        />
+        <Card isCentered>
+          <CardHeading id="main-heading1" level={HeadingLevels.Three}>
+            Find Components
+          </CardHeading>
+          <CardContent>
+            <Text size={TextSizes.Caption}>
+              For your convenience, the Reservoir Design System components have
+              been organized into logical categories based on both form and
+              function. Please refer to the <b>COMPONENTS</b> section in the
+              Storybook sidebar.
+            </Text>
+          </CardContent>
+        </Card>
+      </Box>
+      <Box
+        style={{
+          alignItems: "center",
+          border: "1px solid #ccc",
+          display: "flex",
+          flexDirection: "column",
+          padding: "24px",
+        }}
+      >
+        <Icon
+          name={IconNames.FileTypeSpreadsheet}
+          size={IconSizes.ExtraExtraLarge}
+          color={IconColors.SectionEducationSecondary}
+          additionalStyles={{
+            marginBottom: "s",
+          }}
+        />
+        <Card isCentered>
+          <CardHeading id="main-heading1" level={HeadingLevels.Three}>
+            View the Code
+          </CardHeading>
+          <CardContent>
+            <Text size="caption">
+              The Reservoir Design System React component library is currently
+              published on{" "}
+              <Link
+                href="https://www.npmjs.com/package/@nypl/design-system-react-components"
+                type={LinkTypes.External}
+              >
+                npm
+              </Link>
+              . If you're looking to contribute to this project, checkout the <Link
+                href="https://github.com/NYPL/nypl-design-system"
+                type={LinkTypes.External}
+              >
+                nypl-design-system
+              </Link> repo on Github for more information.
+            </Text>
+          </CardContent>
+        </Card>
+      </Box>
+    </SimpleGrid>
+  </VStack>
 </DSProvider>
-
-<br />
-
-Welcome to the New York Public Library's Design System React component library.
-This design system is NYPL's open-source extensible React library for products
-and experiences, with accessibility as its foundation. It ships functional components
-with consistent NYPL styling. You can learn more about the project and its goals
-[on our Confluence page](https://confluence.nypl.org/display/DIGTL/NYPL+Design+System)
-(needs a log in).
-
-The best way to get started is through the [Design System's Wiki](https://github.com/NYPL/nypl-design-system/wiki)
-to learn about design and implementation at NYPL. The Hero above is just
-one example of how we use the NYPL Design System on NYPL.org.
-
-For your convenience, the DS components have been organized into logical categories
-based on both form and function. Please refer to the **COMPONENTS** section in the
-Storybook sidebar.
-
-## @nypl/design-system-react-components
-
-This React design system library is currently published on [npm](https://www.npmjs.com/package/@nypl/design-system-react-components).
-If you're looking to contribute to this project, checkout the
-[nypl-design-system](https://github.com/NYPL/nypl-design-system) repo on Github
-for more information.

package/src/hooks/useCarouselStyles.stories.mdx

@@ -1,3 +1,5 @@
+import { Meta, Description } from "@storybook/addon-docs";
+
 import { getCategory } from "../utils/componentCategories";
 
 <Meta title={getCategory("useCarouselStyles")} />
@@ -6,5 +8,23 @@ import { getCategory } from "../utils/componentCategories";
 
 | Hook Version | DS Version |
 | ------------ | ---------- |
-| Added        | `?`        |
-| Latest       | `?`        |
+| Added        | `0.25.2`   |
+| Latest       | `0.25.2`   |
+
+This custom hook, inspired by this [codesandbox example](https://codesandbox.io/s/fxjeo),
+exposes functions used for carousel-like components that have sliding features.
+The two main functions are `prevSlide` and `nextSlide` used for buttons to
+navigate between slides, and a `carouselStyle` style object for the main wrapper
+element. If the carousel should programmatically slide to the first slide, use
+the `goToStart` function.
+
+## Usage
+
+For a full implementation examle, view the [`Tabs` component](https://github.com/NYPL/nypl-design-system/blob/development/src/components/Tabs/Tabs.tsx).
+
+```tsx
+const { prevSlide, nextSlide, carouselStyle, goToStart } = useCarouselStyles(
+  slidesCount,
+  slideWidth
+);
+```

package/src/hooks/useCarouselStyles.ts

@@ -3,10 +3,11 @@ import React from "react";
 /**
  * Custom hook that controls the sliding function for the carousel wrapper.
  * This returns functions to use for the "previous" and "next" buttons as well
- * as a CSS style object that should be use to transition between slides.
+ * as a CSS style object that should be use to transition between slides. There
+ * is also a function to programmatically slide to the first slide.
  * Inspired by: https://codesandbox.io/s/fxjeo
  */
-const useCarouselStyles = (slidesCount = 0, slideWidth = 100) => {
+export const useCarouselStyles = (slidesCount = 0, slideWidth = 100) => {
   const [currentSlide, setCurrentSlide] = React.useState(0);
   // This wraps around to the last slide if this is invoked while the
   // first slide is active.

package/src/hooks/useNYPLTheme.stories.mdx

@@ -0,0 +1,101 @@
+import { Meta } from "@storybook/addon-docs";
+import { getCategory } from "../utils/componentCategories";
+
+<Meta title={getCategory("useNYPLTheme")} />
+
+# useNYPLTheme
+
+| Hook Version | DS Version |
+| ------------ | ---------- |
+| Added        | `0.25.2`   |
+| Latest       | `0.25.2`   |
+
+This custom hook is based on Chakra UI's `useTheme` hook. If your application
+does not use CSS or SCSS files and you want to write CSS-in-JS styles in your
+React components, the `useNYPLTheme` hook will provide you with NYPL-specific
+style values.
+
+## Usage
+
+This hook depends on the `DSProvider` component and if the function is used
+outside of this wrapper component, then the theme object will be empty. After
+importing and rendering the `DSProvider` wrapper component, your children
+components can use this hook function.
+
+```tsx
+import { useNYPLTheme } from "@nypl/design-system-react-components";
+// ...
+
+const theme = useNYPLTheme();
+```
+
+The `theme` variable will be a JS object with design token style values.
+This will allow you to use NYPL-specific styles in your components through CSS-in-JS.
+
+```ts
+// theme:
+{
+  breakpoints: { ... },
+  colors: {
+    brand: { ... },
+    section: { ... },
+    transparent: { ... },
+    ui: { ... },
+  },
+  fontSizes: { ... },
+  fontWeights: { ... },
+  fonts: { ... },
+  radii: { ... },
+  space: { ... },
+}
+```
+
+1. NYPL DS Components
+
+All DS components _should_ be used with their current styles. If a DS component
+needs an updated style, first contact the Design System and UX teams about this
+update. If you really _need_ to update a style and there is no available
+variant, then you can add styles directly to the `additionalStyles` prop. At the
+moment, not all DS components have this prop or feature.
+
+For example, if the `Heading` component should render the text in NYPL's green
+color used for "success primary" and add a bold font weight, then you can do
+the following:
+
+```tsx
+const theme = useNYPLTheme();
+
+// ...
+return (
+  <div>
+    <Heading
+      level={2}
+      additionalStyles={{
+        color: theme.colors.ui.sucess.primary,
+        fontWeight: theme.fontWeights.bold,
+      }}
+    >
+      Get a Digital Library Card Today in a Few Easy Steps
+    </Heading>
+
+    {/* Other components */}
+  </div>
+);
+```
+
+Of course, you can destructure the `theme` object to only get the object keys
+you need for your component (this is a general example). Log the object to the
+console to see all the available styles.
+
+2. HTML Components
+
+Use the `style` attribute in HTML components to add inline styles.
+
+```tsx
+<p style={{ color: theme.colors.ui.success.primary }}>
+  If you are 13 or older and live, work, attend school, or pay property taxes in
+  New York State, you can get a free digital library card right now using this
+  online form. Visitors to New York State can also use this form to apply for a
+  temporary card.
+</p>
+```