@nypl/design-system-react-components 0.25.0 → 0.25.1

package/src/components/Template/Template.tsx

@@ -0,0 +1,226 @@
+import * as React from "react";
+import { Box, useStyleConfig } from "@chakra-ui/react";
+
+export interface TemplateProps {}
+export interface TemplateSidebarProps {
+  /** Renders the `TemplateContentSidebar` component either on the left or
+   * right side of the `TemplateContentPrimary` component. */
+  sidebar?: "none" | "left" | "right";
+}
+export interface TemplateContentProps extends TemplateSidebarProps {}
+export interface TemplateAppContainerProps extends TemplateSidebarProps {
+  /** DOM that will be rendered in the `TemplateBreakout` component section. */
+  breakout?: React.ReactElement;
+  /** DOM that will be rendered in the `TemplateContentPrimary` component section. */
+  contentPrimary?: React.ReactElement;
+  /** DOM that will be rendered in the `TemplateContentSidebar` component section. */
+  contentSidebar?: React.ReactElement;
+  /** DOM that will be rendered in the `TemplateContentTop` component section. */
+  contentTop?: React.ReactElement;
+  /** DOM that will be rendered in the `TemplateFooter` component section. */
+  footer?: React.ReactElement;
+  /** DOM that will be rendered in the `TemplateHeader` component section. */
+  header?: React.ReactElement;
+}
+
+/**
+ * The main top-level parent component that wraps all template-related
+ * components. For backwards compatibility, this renders a `nypl-ds` CSS class.
+ */
+const Template = (props: React.PropsWithChildren<TemplateProps>) => {
+  const styles = useStyleConfig("Template", {});
+  return (
+    <Box __css={styles} className="nypl-ds">
+      {props.children}
+    </Box>
+  );
+};
+
+/**
+ * This optional component should be the first child of the `Template`
+ * component. This is rendered as an HTML `<header>` element.
+ */
+const TemplateHeader = (props: React.PropsWithChildren<TemplateProps>) => {
+  const styles = useStyleConfig("TemplateHeader", {});
+  return (
+    <Box as="header" __css={styles}>
+      {props.children}
+    </Box>
+  );
+};
+
+/**
+ * This optional component should be used inside the `TemplateHeader` component.
+ * This is meant to render its children from edge to edge and is most useful
+ * for the `Breadcrumbs` and `Hero` components, and other banner-like components.
+ */
+const TemplateBreakout = (props: React.PropsWithChildren<TemplateProps>) => {
+  const styles = useStyleConfig("TemplateBreakout", {});
+  return <Box __css={styles}>{props.children}</Box>;
+};
+
+/**
+ * This component is most useful to render content on the page. This renders an
+ * HTML `<main>` element and takes a `sidebar` prop with optional "left" or
+ * "right" values. This will set the correct styling needed for the
+ * `TemplateContentPrimary` and `TemplateContentSidebar` components. Note that
+ * `TemplateContentPrimary` and `TemplateContentSidebar` must be ordered
+ * correctly as children elements for the appropriate styles to take effect.
+ */
+const TemplateContent = (
+  props: React.PropsWithChildren<TemplateContentProps>
+) => {
+  const { sidebar = "none", children } = props;
+  const styles = useStyleConfig("TemplateContent", {
+    variant: sidebar !== "none" ? "sidebar" : null,
+  });
+  // Manually pass in the `sidebar` prop to the `TemplateContentPrimary` and
+  // `TemplateContentSidebar` components.
+  const newChildren = React.Children.map(
+    children,
+    (child: React.ReactElement) => {
+      let newChild = child;
+      if (
+        (child && child?.type === TemplateContentPrimary) ||
+        (child?.props && child.props?.mdxType === "TemplateContentPrimary") ||
+        child?.type === TemplateContentSidebar ||
+        (child?.props && child.props?.mdxType === "TemplateContentSidebar")
+      ) {
+        newChild = React.cloneElement(child, { sidebar });
+      }
+
+      return newChild;
+    }
+  );
+
+  return (
+    <Box as="main" __css={styles}>
+      {newChildren}
+    </Box>
+  );
+};
+
+/**
+ * This optional component must be used inside the `TemplateContent` component.
+ * This renders content in the main width of the container and will always render
+ * above the primary component and the sidebar component (if any).
+ */
+const TemplateContentTop = (props: React.PropsWithChildren<TemplateProps>) => {
+  const styles = useStyleConfig("TemplateContentTop", {});
+  return <Box __css={styles}>{props.children}</Box>;
+};
+
+/**
+ * This component is used to render content in a column when there must be a
+ * sidebar component on either its left or right side. It must go inside the
+ * `TemplateContent` component. An optional `sidebar` prop value of "left" or
+ * "right" can be passed to render the correct CSS styles. If the `sidebar`
+ * prop is used in the `TemplateContent` component, there is no need to pass
+ * the `sidebar` prop to this component -- `TemplateContent` will handle it.
+ */
+const TemplateContentPrimary = (
+  props: React.PropsWithChildren<TemplateContentProps>
+) => {
+  const { sidebar } = props;
+  const styles = useStyleConfig("TemplateContentPrimary", {
+    variant: sidebar,
+  });
+  return <Box __css={styles}>{props.children}</Box>;
+};
+
+/**
+ * This component is used to render content in a sidebar column. It must go
+ * inside the `TemplateContent` component and must be paired with the
+ * `TemplateContentPrimary` component. If this is a left sidebar, it needs to be
+ * rendered before the `TemplateContentPrimary` component. If this is a right
+ * sidebar, it needs to be rendered after the `TemplateContentPrimary` component.
+ * An optional `sidebar` prop value of "left" or "right" can be passed to render
+ * the correct CSS styles. If the `sidebar` prop is used in the `TemplateContent`
+ * component, there is no need to pass the `sidebar` prop to this component --
+ * `TemplateContent` will handle it.
+ */
+const TemplateContentSidebar = (
+  props: React.PropsWithChildren<TemplateContentProps>
+) => {
+  const { sidebar } = props;
+  const styles = useStyleConfig("TemplateContentSidebar", {
+    variant: sidebar,
+  });
+  return <Box __css={styles}>{props.children}</Box>;
+};
+
+/**
+ * This optional component should be the last child of the `Template`
+ * component. This is rendered as an HTML `<footer>` element and spans the full
+ * width of the page.
+ */
+const TemplateFooter = (props: React.PropsWithChildren<TemplateProps>) => {
+  return <Box as="footer">{props.children}</Box>;
+};
+
+/**
+ * This single component can be used instead of all the individual template
+ * components. Instead of importing and rendering the needed "template"
+ * components, each section is passed as a prop to the section where it should
+ * be rendered. For example, if you want to render content in the
+ * `TemplateContentPrimary` section, then pass it as a prop to `contentPrimary`.
+ */
+const TemplateAppContainer = (
+  props: React.PropsWithChildren<TemplateAppContainerProps>
+) => {
+  const {
+    breakout,
+    contentPrimary,
+    contentSidebar,
+    contentTop,
+    footer,
+    header,
+    sidebar = "none",
+  } = props;
+  const breakoutElem = breakout && (
+    <TemplateBreakout>{breakout}</TemplateBreakout>
+  );
+  const contentTopElem = contentTop && (
+    <TemplateContentTop>{contentTop}</TemplateContentTop>
+  );
+  const contentPrimaryElem = contentPrimary && (
+    <TemplateContentPrimary>{contentPrimary}</TemplateContentPrimary>
+  );
+  const contentSidebarElem = contentSidebar && (
+    <TemplateContentSidebar>{contentSidebar}</TemplateContentSidebar>
+  );
+  return (
+    <Template>
+      {(header || breakoutElem) && (
+        <TemplateHeader>
+          {header}
+          {breakoutElem}
+        </TemplateHeader>
+      )}
+      {/* Note that setting `sidebar` as a prop here affects the
+       TemplateContentSidebar and TemplateContentPrimary components. */}
+      <TemplateContent sidebar={sidebar}>
+        {contentTopElem}
+
+        {sidebar === "left" && contentSidebarElem}
+
+        {contentPrimaryElem}
+
+        {sidebar === "right" && contentSidebarElem}
+      </TemplateContent>
+      {footer && <TemplateFooter>{footer}</TemplateFooter>}
+    </Template>
+  );
+};
+
+export {
+  TemplateAppContainer,
+  Template,
+  TemplateHeader,
+  TemplateBreakout,
+  TemplateContent,
+  TemplateContentTop,
+  TemplateContentPrimary,
+  TemplateContentSidebar,
+  TemplateFooter,
+};

package/src/components/Text/Text.stories.mdx

@@ -0,0 +1,70 @@
+import {
+  Meta,
+  Story,
+  Canvas,
+  ArgsTable,
+  Description,
+} from "@storybook/addon-docs/blocks";
+import { withDesign } from "storybook-addon-designs";
+
+import Text from "./Text";
+import { getCategory } from "../../utils/componentCategories";
+
+<Meta
+  title={getCategory("Text")}
+  component={Text}
+  decorators={[withDesign]}
+  parameters={{
+    design: {
+      type: "figma",
+      url:
+        "https://www.figma.com/file/qShodlfNCJHb8n03IFyApM/?node-id=10733%3A56919",
+    },
+  }}
+  argTypes={{
+    displaySize: { table: { disable: false } },
+    className: { table: { disable: true } },
+  }}
+/>
+
+# Text
+
+| Component Version | DS Version |
+| ----------------- | ---------- |
+| Added             | `0.25.1`   |
+| Latest            | `0.25.1`   |
+
+<Description of={Text} />
+
+The `Text` component renders a basic `<p>` element. As its name indicates, the `displaySize` prop controls the size of the text rendered in the component.
+
+<Canvas withToolbar>
+  <Story name="Text" args={{}}>
+    {(args) => (
+      <>
+        <Text {...args}>
+          Animal Crossing[a] is a social simulation video game series developed
+          and published by Nintendo. The series was conceptualized and created
+          by Katsuya Eguchi and Hisashi Nogami. In Animal Crossing, the player
+          character is a human who lives in a village inhabited by various
+          anthropomorphic animals and can do various activities like fishing,
+          bug catching, and fossil hunting. The series is notable for its
+          open-ended gameplay and use of the video game console's internal clock
+          and calendar to simulate real passage of time.
+        </Text>
+        <Text {...args}>
+          Since its initial release in 2001, five Animal Crossing games have
+          been released worldwide, one each for the Nintendo 64/iQue Player
+          (enhanced and reissued for the GameCube), Nintendo DS, Wii, Nintendo
+          3DS and Nintendo Switch. The series has been both critically and
+          commercially successful and has sold over 60 million units worldwide.
+          Three spin-off games have also been released: Animal Crossing: Happy
+          Home Designer for Nintendo 3DS, Animal Crossing: Amiibo Festival for
+          Wii U, and Animal Crossing: Pocket Camp for mobile devices.
+        </Text>
+      </>
+    )}
+  </Story>
+</Canvas>
+
+<ArgsTable story="Text" />

package/src/components/Text/Text.test.tsx

@@ -0,0 +1,63 @@
+import * as React from "react";
+import { render, screen } from "@testing-library/react";
+import { axe } from "jest-axe";
+import renderer from "react-test-renderer";
+
+import Text from "./Text";
+import { TextDisplaySizes } from "./TextTypes";
+
+describe("Text Accessibility", () => {
+  it("passes axe accessibility test", async () => {
+    const { container } = render(<Text>Animal Crossing is all that!</Text>);
+    expect(await axe(container)).toHaveNoViolations();
+  });
+});
+
+describe("Text", () => {
+  it("renders a <p> tag and text", () => {
+    render(<Text>Animal Crossing is all that!</Text>);
+    expect(
+      screen.getByText("Animal Crossing is all that!")
+    ).toBeInTheDocument();
+  });
+
+  it("throws a warning when no children are passed", () => {
+    const warn = jest.spyOn(console, "warn");
+    render(<Text></Text>);
+    expect(warn).toHaveBeenCalledWith(
+      "The Text component has no children and will not render correctly."
+    );
+  });
+
+  it("renders the UI snapshot correctly", () => {
+    const defaultText = renderer
+      .create(<Text>Animal Crossing is all that!</Text>)
+      .toJSON();
+    const caption = renderer
+      .create(
+        <Text displaySize={TextDisplaySizes.Caption}>
+          Animal Crossing is all that!
+        </Text>
+      )
+      .toJSON();
+    const tag = renderer
+      .create(
+        <Text displaySize={TextDisplaySizes.Tag}>
+          Animal Crossing is all that!
+        </Text>
+      )
+      .toJSON();
+    const mini = renderer
+      .create(
+        <Text displaySize={TextDisplaySizes.Mini}>
+          Animal Crossing is all that!
+        </Text>
+      )
+      .toJSON();
+
+    expect(defaultText).toMatchSnapshot();
+    expect(caption).toMatchSnapshot();
+    expect(tag).toMatchSnapshot();
+    expect(mini).toMatchSnapshot();
+  });
+});

package/src/components/Text/Text.tsx

@@ -0,0 +1,55 @@
+import * as React from "react";
+import { Text as ChakraText, useStyleConfig } from "@chakra-ui/react";
+import { TextDisplaySizes } from "./TextTypes";
+import { getVariant } from "../../utils/utils";
+
+export interface TextProps {
+  /** Additional class name to render in the `Text` component. */
+  className?: string;
+  /** Optional prop used to show bolded text */
+  isBold?: boolean;
+  /** Optional prop used to show itlicized text */
+  isItalic?: boolean;
+  /** Optional prop used to remove default spacing */
+  noSpace?: boolean;
+  /** Optional prop to control the text styling */
+  displaySize?: TextDisplaySizes;
+}
+
+function Text(props: React.PropsWithChildren<TextProps>) {
+  const {
+    children,
+    className = "",
+    displaySize = TextDisplaySizes.Default,
+    isBold,
+    isItalic,
+    noSpace,
+  } = props;
+
+  let variant = getVariant(
+    displaySize,
+    TextDisplaySizes,
+    TextDisplaySizes.Default
+  );
+
+  const styles = useStyleConfig("Text", {
+    variant,
+    isBold,
+    isItalic,
+    noSpace,
+  });
+
+  if (!children) {
+    console.warn(
+      "The Text component has no children and will not render correctly."
+    );
+  }
+
+  return (
+    <ChakraText className={className} sx={styles}>
+      {children}
+    </ChakraText>
+  );
+}
+
+export default Text;

package/src/components/Text/TextTypes.tsx

@@ -0,0 +1,6 @@
+export enum TextDisplaySizes {
+  Default = "default",
+  Caption = "caption",
+  Tag = "tag",
+  Mini = "mini",
+}

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

@@ -0,0 +1,33 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`Text renders the UI snapshot correctly 1`] = `
+<p
+  className="chakra-text css-0"
+>
+  Animal Crossing is all that!
+</p>
+`;
+
+exports[`Text renders the UI snapshot correctly 2`] = `
+<p
+  className="chakra-text css-0"
+>
+  Animal Crossing is all that!
+</p>
+`;
+
+exports[`Text renders the UI snapshot correctly 3`] = `
+<p
+  className="chakra-text css-0"
+>
+  Animal Crossing is all that!
+</p>
+`;
+
+exports[`Text renders the UI snapshot correctly 4`] = `
+<p
+  className="chakra-text css-0"
+>
+  Animal Crossing is all that!
+</p>
+`;