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

package/src/hooks/tests/useCarouselStyles.test.ts

@@ -0,0 +1,140 @@
+import { renderHook, act } from "@testing-library/react-hooks";
+import useCarouselStyles from "../useCarouselStyles";
+
+describe("useCarouselStyles hook", () => {
+  it("returns two functions and a CSS style object", () => {
+    const { result } = renderHook(() => useCarouselStyles());
+
+    expect(typeof result.current.nextSlide).toEqual("function");
+    expect(typeof result.current.prevSlide).toEqual("function");
+    expect(result.current.carouselStyle).toEqual({
+      marginLeft: "-0%",
+      transition: "all .5s",
+    });
+  });
+
+  it("updates the style object when the nextSlide function is clicked", () => {
+    // Mocking we have an array of five slides.
+    const slides = [1, 2, 3, 4, 5];
+    const { result } = renderHook(() => useCarouselStyles(slides.length));
+    const nextSlide = result.current.nextSlide;
+
+    // Start at the first slide.
+    expect(result.current.carouselStyle).toEqual({
+      marginLeft: "-0%",
+      transition: "all .5s",
+    });
+
+    act(() => nextSlide());
+    // Each slide takes up a width of 100% by default.
+    // So now we move by 100% to the left for the next slide.
+    expect(result.current.carouselStyle).toEqual({
+      marginLeft: "-100%",
+      transition: "all .5s",
+    });
+
+    act(() => nextSlide());
+    // Move on to the next slide.
+    expect(result.current.carouselStyle).toEqual({
+      marginLeft: "-200%",
+      transition: "all .5s",
+    });
+
+    // We now click through all five slides and we expect to wrap around
+    // back to the first slide which starts at "-0%" (the negative value
+    // is set for direction but -0 is still 0).
+    act(() => nextSlide());
+    act(() => nextSlide());
+    act(() => nextSlide());
+    expect(result.current.carouselStyle).toEqual({
+      marginLeft: "-0%",
+      transition: "all .5s",
+    });
+  });
+
+  it("updates the style object when the prevSlide function is clicked", () => {
+    // Mocking we have an array of five slides.
+    const slides = [1, 2, 3, 4, 5];
+    const { result } = renderHook(() => useCarouselStyles(slides.length));
+    const prevSlide = result.current.prevSlide;
+
+    // Start at the first slide.
+    expect(result.current.carouselStyle).toEqual({
+      marginLeft: "-0%",
+      transition: "all .5s",
+    });
+
+    act(() => prevSlide());
+    // We started on the first slide and nwo we expect to wrap around
+    // to the last element.
+    expect(result.current.carouselStyle).toEqual({
+      marginLeft: "-400%",
+      transition: "all .5s",
+    });
+
+    act(() => prevSlide());
+    // Move on to the previous slide.
+    expect(result.current.carouselStyle).toEqual({
+      marginLeft: "-300%",
+      transition: "all .5s",
+    });
+
+    // We now clicked through all five slides and we expect to
+    // be at the first slide.
+    act(() => prevSlide());
+    act(() => prevSlide());
+    act(() => prevSlide());
+    expect(result.current.carouselStyle).toEqual({
+      marginLeft: "-0%",
+      transition: "all .5s",
+    });
+  });
+
+  it("resets the slide back to the first slide", () => {
+    // Mocking we have an array of five slides.
+    const slides = [1, 2, 3, 4, 5];
+    const { result } = renderHook(() => useCarouselStyles(slides.length));
+    const { nextSlide, goToStart } = result.current;
+
+    // Start at the first slide.
+    expect(result.current.carouselStyle).toEqual({
+      marginLeft: "-0%",
+      transition: "all .5s",
+    });
+
+    // Move on to the third slide.
+    act(() => nextSlide());
+    act(() => nextSlide());
+    act(() => nextSlide());
+    expect(result.current.carouselStyle).toEqual({
+      marginLeft: "-300%",
+      transition: "all .5s",
+    });
+
+    act(() => goToStart());
+    expect(result.current.carouselStyle).toEqual({
+      marginLeft: "-0%",
+      transition: "all .5s",
+    });
+  });
+
+  it("can set a custom slide count and slide width", () => {
+    const slides = [1, 2, 3];
+    const slideWidth = 50;
+    const { result } = renderHook(() =>
+      useCarouselStyles(slides.length, slideWidth)
+    );
+
+    expect(result.current.carouselStyle).toEqual({
+      marginLeft: "-0%",
+      transition: "all .5s",
+    });
+
+    act(() => result.current.nextSlide());
+    // Since each slide is of length 50, we expect to move by a 50%.
+    expect(result.current.carouselStyle).toEqual({
+      marginLeft: "-50%",
+      transition: "all .5s",
+    });
+  });
+});

package/src/hooks/tests/useNYPLTheme.test.tsx

@@ -0,0 +1,36 @@
+import React from "react";
+import { renderHook } from "@testing-library/react-hooks";
+
+import useNYPLTheme from "../useNYPLTheme";
+import DSProvider from "../../theme/provider";
+
+describe("useNYPLTheme", () => {
+  it("returns an empty object when not used inside a DSProvider component", () => {
+    const warn = jest.spyOn(console, "warn");
+    const { result } = renderHook(() => useNYPLTheme());
+
+    expect(warn).toHaveBeenCalledWith(
+      "NYPL Reservoir useNYPLTheme: hook must be used inside of `<DSProvider />`."
+    );
+    expect(result.current).toEqual({});
+  });
+
+  it("returns an object with NYPL styles", () => {
+    const { result } = renderHook(() => useNYPLTheme(), {
+      wrapper: ({ children }) => <DSProvider>{children}</DSProvider>,
+    });
+    const allKeys = Object.keys(result.current);
+    const colorsKeys = Object.keys((result.current as any).colors);
+
+    expect(allKeys).toEqual([
+      "breakpoints",
+      "colors",
+      "fontSizes",
+      "fontWeights",
+      "fonts",
+      "radii",
+      "space",
+    ]);
+    expect(colorsKeys).toEqual(["brand", "section", "transparent", "ui"]);
+  });
+});

package/src/hooks/useCarouselStyles.stories.mdx

@@ -0,0 +1,30 @@
+import { Meta, Description } from "@storybook/addon-docs";
+
+import { getCategory } from "../utils/componentCategories";
+
+<Meta title={getCategory("useCarouselStyles")} />
+
+# useCarouselStyles
+
+| Hook Version | DS Version |
+| ------------ | ---------- |
+| 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

@@ -0,0 +1,35 @@
+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. There
+ * is also a function to programmatically slide to the first slide.
+ * Inspired by: https://codesandbox.io/s/fxjeo
+ */
+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.
+  const prevSlide = () => {
+    setCurrentSlide((slide) => (slide === 0 ? slidesCount - 1 : slide - 1));
+  };
+  // This wraps around to the first slide if this is invoked while the
+  // last slide is active.
+  const nextSlide = () => {
+    setCurrentSlide((slide) => (slide === slidesCount - 1 ? 0 : slide + 1));
+  };
+  const goToStart = () => {
+    setCurrentSlide(0);
+  };
+  // Updates the left margin for the carousel so the elements can
+  // slide inside the container.
+  const carouselStyle = {
+    transition: "all .5s",
+    marginLeft: `-${currentSlide * slideWidth}%`,
+  };
+
+  return { prevSlide, nextSlide, carouselStyle, goToStart };
+};
+
+export default useCarouselStyles;

package/src/hooks/useNYPLTheme.stories.mdx

@@ -0,0 +1,98 @@
+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 as style prop.
+
+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}
+      color={theme.colors.ui.success.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>
+```

package/src/hooks/useNYPLTheme.ts

@@ -0,0 +1,91 @@
+import { useTheme } from "@chakra-ui/react";
+
+/**
+ * A custom hook that returns the Chakra-based NYPL theme object. This must be
+ * used inside a component that is wrapped in the `DSProvider` component, so
+ * that the theme object can be available to use.
+ */
+function useNYPLTheme() {
+  const theme = useTheme();
+  if (!theme || Object.keys(theme).length === 0) {
+    console.warn(
+      "NYPL Reservoir useNYPLTheme: hook must be used inside of `<DSProvider />`."
+    );
+    return {};
+  }
+
+  // Chakra provides a lot of their own styles but
+  // only NYPL styles should be exported.
+  return {
+    // base, sm, md, lg, xl, 2xl
+    breakpoints: theme.breakpoints,
+    colors: {
+      // primary, secondary
+      brand: theme.colors.brand,
+      // blogs, books-and-more, education, locations,
+      // research, research-library, whats-on
+      section: theme.colors.section,
+      transparent: theme.colors.transparent,
+      // black, disabled, error, focus, gray, link,
+      // status, success, test, warning, white
+      ui: theme.colors.ui,
+    },
+    fontSizes: {
+      "-3": theme.fontSizes["-3"],
+      "-2": theme.fontSizes["-2"],
+      "-1": theme.fontSizes["-1"],
+      "0": theme.fontSizes["0"],
+      "1": theme.fontSizes["1"],
+      "2": theme.fontSizes["2"],
+      "3": theme.fontSizes["3"],
+      "4": theme.fontSizes["4"],
+      // default
+      breadcrumbs: theme.fontSizes.breadcrumbs,
+      // default
+      button: theme.fontSizes.button,
+      // primary, secondary, tertiary, callout
+      heading: theme.fontSizes.heading,
+      // default
+      helper: theme.fontSizes.helper,
+      // default, secondary
+      label: theme.fontSizes.label,
+      // default, caption, tag, mini
+      text: theme.fontSizes.text,
+    },
+    fontWeights: {
+      light: theme.fontWeights.light,
+      regular: theme.fontWeights.regular,
+      medium: theme.fontWeights.medium,
+      bold: theme.fontWeights.bold,
+      // default, lastChild
+      breadcrumbs: theme.fontWeights.breadcrumbs,
+      // default
+      button: theme.fontWeights.button,
+      // primary, secondary, tertiary, callout
+      heading: theme.fontWeights.heading,
+      // default
+      helper: theme.fontWeights.helper,
+      // default
+      label: theme.fontWeights.label,
+      // default, caption, tag, mini
+      text: theme.fontWeights.text,
+    },
+    fonts: {
+      body: theme.fonts.body,
+      heading: theme.fonts.heading,
+    },
+    radii: theme.radii,
+    space: {
+      xxs: theme.space.xxs,
+      xs: theme.space.xs,
+      s: theme.space.s,
+      m: theme.space.m,
+      l: theme.space.l,
+      xl: theme.space.xl,
+      xxl: theme.space.xxl,
+      xxxl: theme.space.xxxl,
+    },
+  };
+}
+
+export default useNYPLTheme;

package/src/hooks/useWindowSize.stories.mdx

@@ -0,0 +1,23 @@
+import { Meta } from "@storybook/addon-docs";
+import { getCategory } from "../utils/componentCategories";
+
+<Meta title={getCategory("useWindowSize")} />
+
+# useWindowSize
+
+| Hook Version | DS Version |
+| ------------ | ---------- |
+| Added        | `0.25.2`   |
+| Latest       | `0.25.2`   |
+
+This hook is based on [Typescript hooks](https://usehooks-typescript.com/react-hook/use-window-size).
+It returns an object with `width` and `height` properties that can be used to
+update a component's UI based on the size of the browser window.
+
+## Usage
+
+For an example implementation, view the [`Tabs` component](https://github.com/NYPL/nypl-design-system/blob/development/src/components/Tabs/Tabs.tsx).
+
+```tsx
+const { height, width } = useWindowSize();
+```

package/src/hooks/useWindowSize.ts

@@ -0,0 +1,40 @@
+import React from "react";
+
+interface WindowSize {
+  width: number;
+  height: number;
+}
+
+/**
+ * React hook used to get the window size on device resizing.
+ * Based on https://usehooks-typescript.com/react-hook/use-window-size
+ */
+function useWindowSize(): WindowSize {
+  const [windowSize, setWindowSize] = React.useState<WindowSize>({
+    width: 0,
+    height: 0,
+  });
+
+  React.useEffect(() => {
+    const handler = () => {
+      setWindowSize({
+        width: window.innerWidth,
+        height: window.innerHeight,
+      });
+    };
+
+    // Set size at the first client-side load
+    handler();
+
+    window.addEventListener("resize", handler);
+
+    // Remove event listener on cleanup
+    return () => {
+      window.removeEventListener("resize", handler);
+    };
+  }, []);
+
+  return windowSize;
+}
+
+export default useWindowSize;

package/src/index.ts

@@ -0,0 +1,136 @@
+import "./styles.scss";
+
+// Note that the NYPL Design System directly re-exports the following
+// components for usage in consuming applications.
+export {
+  Box,
+  Center,
+  Circle,
+  Flex,
+  Grid,
+  GridItem,
+  HStack,
+  Spacer,
+  Square,
+  Stack,
+  VStack,
+} from "@chakra-ui/react";
+export {
+  default as Accordion,
+  AccordionTypes,
+} from "./components/Accordion/Accordion";
+export {
+  default as Breadcrumbs,
+  BreadcrumbsTypes,
+} from "./components/Breadcrumbs/Breadcrumbs";
+export { default as Button, ButtonTypes } from "./components/Button/Button";
+export { default as ButtonGroup } from "./components/ButtonGroup/ButtonGroup";
+export {
+  default as Card,
+  CardActions,
+  CardContent,
+  CardHeading,
+} from "./components/Card/Card";
+export { default as Checkbox } from "./components/Checkbox/Checkbox";
+export { default as CheckboxGroup } from "./components/CheckboxGroup/CheckboxGroup";
+export {
+  default as DatePicker,
+  DatePickerTypes,
+  FullDateType,
+} from "./components/DatePicker/DatePicker";
+export { default as DSProvider } from "./theme/provider";
+export { default as Fieldset } from "./components/Fieldset/Fieldset";
+export { default as Form, FormField, FormRow } from "./components/Form/Form";
+export {
+  default as Heading,
+  HeadingSizes,
+  HeadingLevels,
+} from "./components/Heading/Heading";
+export { default as HelperErrorText } from "./components/HelperErrorText/HelperErrorText";
+export { default as Hero, HeroTypes } from "./components/Hero/Hero";
+export { default as HorizontalRule } from "./components/HorizontalRule/HorizontalRule";
+export {
+  default as Icon,
+  IconAlign,
+  IconColors,
+  IconNames,
+  IconRotationTypes,
+  IconSizes,
+  IconTypes,
+} from "./components/Icons/Icon";
+export {
+  default as Image,
+  ImageRatios,
+  ImageSizes,
+  ImageTypes,
+} from "./components/Image/Image";
+export { default as Label } from "./components/Label/Label";
+export { LayoutTypes } from "./helpers/types";
+export { default as Link, LinkTypes } from "./components/Link/Link";
+export { default as List, ListTypes } from "./components/List/List";
+export { default as Logo, LogoNames, LogoSizes } from "./components/Logo/Logo";
+export { ModalTrigger, useModal } from "./components/Modal/Modal";
+export {
+  default as Notification,
+  NotificationTypes,
+} from "./components/Notification/Notification";
+export { default as Pagination } from "./components/Pagination/Pagination";
+export {
+  default as ProgressIndicator,
+  ProgressIndicatorSizes,
+  ProgressIndicatorTypes,
+} from "./components/ProgressIndicator/ProgressIndicator";
+export { default as Radio } from "./components/Radio/Radio";
+export { default as RadioGroup } from "./components/RadioGroup/RadioGroup";
+export { default as SearchBar } from "./components/SearchBar/SearchBar";
+export { default as Select, LabelPositions } from "./components/Select/Select";
+export { default as SimpleGrid, GridGaps } from "./components/Grid/SimpleGrid";
+export {
+  default as SkeletonLoader,
+  SkeletonLoaderImageRatios,
+} from "./components/SkeletonLoader/SkeletonLoader";
+export { default as SkipNavigation } from "./components/SkipNavigation/SkipNavigation";
+export { default as Slider } from "./components/Slider/Slider";
+export {
+  default as StatusBadge,
+  StatusBadgeTypes,
+} from "./components/StatusBadge/StatusBadge";
+export {
+  default as StructuredContent,
+  StructuredContentImagePosition,
+} from "./components/StructuredContent/StructuredContent";
+export {
+  default as Tabs,
+  TabList,
+  Tab,
+  TabPanels,
+  TabPanel,
+} from "./components/Tabs/Tabs";
+export {
+  TemplateAppContainer,
+  Template,
+  TemplateAboveHeader,
+  TemplateHeader,
+  TemplateBreakout,
+  TemplateContent,
+  TemplateContentTop,
+  TemplateContentPrimary,
+  TemplateContentSidebar,
+  TemplateFooter,
+} from "./components/Template/Template";
+export { default as Text, TextSizes } from "./components/Text/Text";
+export {
+  default as TextInput,
+  TextInputRefType,
+  TextInputTypes,
+} from "./components/TextInput/TextInput";
+export { default as Toggle, ToggleSizes } from "./components/Toggle/Toggle";
+export { default as useCarouselStyles } from "./hooks/useCarouselStyles";
+export { default as useNYPLTheme } from "./hooks/useNYPLTheme";
+export { default as useWindowSize } from "./hooks/useWindowSize";
+export {
+  default as VideoPlayer,
+  VideoPlayerAspectRatios,
+  VideoPlayerTypes,
+} from "./components/VideoPlayer/VideoPlayer";
+export { default as Table } from "./components/Table/Table";

package/src/resources.scss

@@ -0,0 +1,6 @@
+// Resources to export as sass mixins
+@import "./styles/base/01-breakpoints";
+@import "./styles/base/02-mixins";
+@import "./styles/space/space-inline";
+@import "./styles/space/space-inset";
+@import "./styles/space/space-stack";

package/src/styles/base/_01-breakpoints.scss

@@ -0,0 +1,27 @@
+/**
+ * Breakpoint Configuration
+ * @see https://github.com/Team-Sass/breakpoint/wiki
+ */
+
+// Global Breakpoints
+
+// Avoid using in favor of atomic, content-specific, breakpoints.
+// These should be used for generic code, like layouts and typography, only.
+// The CSS variables and the Sass variables below need to stay in sync.
+// Sass' breakpoint() mixin doesn't work without Sass variables.
+// CSS variables expose the breakpoint variables to consumers.
+:root {
+  --nypl-breakpoint-small: 320px;
+  --nypl-breakpoint-medium: 600px;
+  --nypl-breakpoint-large: 960px;
+  --nypl-breakpoint-xl: 1280px;
+}
+
+$nypl-breakpoint-small: 320px;
+$nypl-breakpoint-medium: 600px;
+$nypl-breakpoint-large: 960px;
+$nypl-breakpoint-xl: 1280px;
+// The max-width breakpoint is used when the design should be applied at
+// whatever the largest breakpoint is regardless of actual pixel value,
+// e.g. removing outer margin on body wrapper.
+$nypl-max-width: $nypl-breakpoint-xl;