@nypl/design-system-react-components 0.25.7 → 0.25.10

package/src/components/Template/Template.tsx

@@ -2,13 +2,27 @@ import * as React from "react";
 import { Box, useStyleConfig } from "@chakra-ui/react";
 
 export interface TemplateProps {}
+export interface TemplateHeaderProps {
+  /** Flag to render an HTML header element. True by default. */
+  renderHeaderElement?: boolean;
+}
+export interface TemplateFooterProps {
+  /** Flag to render an HTML footer element. True by default. */
+  renderFooterElement?: boolean;
+}
 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 {
+export interface TemplateAppContainerProps
+  extends TemplateFooterProps,
+    TemplateHeaderProps,
+    TemplateSidebarProps {
+  /** DOM that will be rendered before the rest of the components in
+   * `TemplateAppContainer` and immediately before the `TemplateHeader` component. */
+  aboveHeader?: React.ReactElement;
   /** DOM that will be rendered in the `TemplateBreakout` component section. */
   breakout?: React.ReactElement;
   /** DOM that will be rendered in the `TemplateContentPrimary` component section. */
@@ -36,17 +50,52 @@ const Template = (props: React.PropsWithChildren<TemplateProps>) => {
   );
 };
 
+/**
+ * This optional component renders its children from edge-to-edge and should
+ * be used for alerts or notifications that are typically site-wide. This must
+ * be rendered immediately before the `TemplateHeader` component. This is meant
+ * for components that render an `aside` HTML element or HTML element with the
+ * `role="complementary"` attribute. These elements should *not* be rendered
+ * in the `header` HTML section since that's an accessibility violation.
+ */
+const TemplateAboveHeader = (props: React.PropsWithChildren<TemplateProps>) => {
+  const styles = useStyleConfig("TemplateBreakout", {});
+  return <Box __css={styles}>{props.children}</Box>;
+};
+
 /**
  * This optional component should be the first child of the `Template`
- * component. This is rendered as an HTML `<header>` element.
+ * component. This is rendered as an HTML `<header>` element. If an HTML
+ * `<header>` element is already passed in a custom component as the children,
+ * set `renderFooterElement` to `false`. Otherwise, the parent wrapper will
+ * render an HTML `<header>` element.
  */
-const TemplateHeader = (props: React.PropsWithChildren<TemplateProps>) => {
+const TemplateHeader = ({
+  children,
+  renderHeaderElement = true,
+}: React.PropsWithChildren<TemplateHeaderProps>) => {
   const styles = useStyleConfig("TemplateHeader", {});
-  return (
-    <Box as="header" __css={styles}>
-      {props.children}
-    </Box>
-  );
+  let headerElement = <Box __css={styles}>{children}</Box>;
+
+  // The user wants to render the `header` HTML element.
+  if (renderHeaderElement) {
+    // But if they passed in a component that renders an HTML `<header>`,
+    // then log a warning.
+    React.Children.map(children, (child: React.ReactElement) => {
+      if (child?.type === "header" || child?.props?.mdxType === "header") {
+        console.warn(
+          "`TemplateHeader`: An HTML `header` element was passed in. Set " +
+            "`renderHeaderElement` to `false` to avoid nested HTML `header` elements."
+        );
+      }
+    });
+    headerElement = (
+      <Box as="header" __css={styles}>
+        {children}
+      </Box>
+    );
+  }
+  return headerElement;
 };
 
 /**
@@ -152,10 +201,29 @@ const TemplateContentSidebar = (
 /**
  * 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.
+ * width of the page. If an HTML `<footer>` element is already passed in a
+ * custom component, set `renderFooterElement` to `false`.
  */
-const TemplateFooter = (props: React.PropsWithChildren<TemplateProps>) => {
-  return <Box as="footer">{props.children}</Box>;
+const TemplateFooter = ({
+  children,
+  renderFooterElement = true,
+}: React.PropsWithChildren<TemplateFooterProps>) => {
+  let footerElement = <>{children}</>;
+
+  // The user wants to render the `footer` HTML element.
+  if (renderFooterElement) {
+    // But give a warning if one was passed.
+    React.Children.map(children, (child: React.ReactElement) => {
+      if (child?.type === "footer" || child?.props?.mdxType === "footer") {
+        console.warn(
+          "`TemplateFooter`: An HTML `footer` element was passed in. Set " +
+            "`renderFooterElement` to `false` to avoid nested HTML `footer` elements."
+        );
+      }
+    });
+    footerElement = <Box as="footer">{children}</Box>;
+  }
+  return footerElement;
 };
 
 /**
@@ -169,6 +237,7 @@ const TemplateAppContainer = (
   props: React.PropsWithChildren<TemplateAppContainerProps>
 ) => {
   const {
+    aboveHeader,
     breakout,
     contentPrimary,
     contentSidebar,
@@ -176,7 +245,12 @@ const TemplateAppContainer = (
     footer,
     header,
     sidebar = "none",
+    renderFooterElement = true,
+    renderHeaderElement = true,
   } = props;
+  const aboveHeaderElem = aboveHeader && (
+    <TemplateAboveHeader>{aboveHeader}</TemplateAboveHeader>
+  );
   const breakoutElem = breakout && (
     <TemplateBreakout>{breakout}</TemplateBreakout>
   );
@@ -191,8 +265,9 @@ const TemplateAppContainer = (
   );
   return (
     <Template>
+      {aboveHeaderElem}
       {(header || breakoutElem) && (
-        <TemplateHeader>
+        <TemplateHeader renderHeaderElement={renderHeaderElement}>
           {header}
           {breakoutElem}
         </TemplateHeader>
@@ -208,7 +283,11 @@ const TemplateAppContainer = (
 
         {sidebar === "right" && contentSidebarElem}
       </TemplateContent>
-      {footer && <TemplateFooter>{footer}</TemplateFooter>}
+      {footer && (
+        <TemplateFooter renderFooterElement={renderFooterElement}>
+          {footer}
+        </TemplateFooter>
+      )}
     </Template>
   );
 };
@@ -216,6 +295,7 @@ const TemplateAppContainer = (
 export {
   TemplateAppContainer,
   Template,
+  TemplateAboveHeader,
   TemplateHeader,
   TemplateBreakout,
   TemplateContent,

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

@@ -0,0 +1,169 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`Template components Renders the UI snapshot correctly 1`] = `
+<div
+  className="nypl-ds css-0"
+>
+  <div
+    className="css-0"
+  >
+    <div
+      className="placeholder placeholder-short"
+    >
+      Above Header
+    </div>
+  </div>
+  <header
+    className="css-0"
+  >
+    <div
+      className="placeholder placeholder-short"
+    >
+      NYPL Header
+    </div>
+    <div
+      className="css-0"
+    >
+      <div
+        className="placeholder placeholder-short"
+      >
+        Breadcrumbs
+      </div>
+      <div
+        className="placeholder placeholder-short"
+      >
+        Hero
+      </div>
+    </div>
+  </header>
+  <main
+    className="css-0"
+  >
+    <div
+      className="css-0"
+    >
+      <div
+        className="placeholder placeholder-undefined"
+      >
+        Content Top
+      </div>
+    </div>
+    <div
+      className="css-0"
+    >
+      <div
+        className="placeholder placeholder-undefined"
+      >
+        Left Sidebar
+      </div>
+    </div>
+    <div
+      className="css-0"
+    >
+      <div
+        className="placeholder placeholder-undefined"
+      >
+        Main Content
+      </div>
+      <div
+        className="placeholder placeholder-short"
+      >
+        More Content
+      </div>
+    </div>
+  </main>
+  <footer
+    className="css-0"
+  >
+    <div
+      className="placeholder placeholder-short"
+    >
+      Footer
+    </div>
+  </footer>
+</div>
+`;
+
+exports[`Template components Renders the UI snapshot correctly 2`] = `
+<div
+  className="nypl-ds css-0"
+>
+  <div
+    className="css-0"
+  >
+    <div
+      className="placeholder placeholder-short"
+    >
+      Above Header
+    </div>
+  </div>
+  <header
+    className="css-0"
+  >
+    <div
+      className="placeholder placeholder-short"
+    >
+      NYPL Header
+    </div>
+    <div
+      className="css-0"
+    >
+      <div
+        className="placeholder placeholder-short"
+      >
+        Breadcrumbs
+      </div>
+      <div
+        className="placeholder placeholder-short"
+      >
+        Hero
+      </div>
+    </div>
+  </header>
+  <main
+    className="css-0"
+  >
+    <div
+      className="css-0"
+    >
+      <div
+        className="placeholder placeholder-undefined"
+      >
+        Content Top
+      </div>
+    </div>
+    <div
+      className="css-0"
+    >
+      <div
+        className="placeholder placeholder-undefined"
+      >
+        Left Sidebar
+      </div>
+    </div>
+    <div
+      className="css-0"
+    >
+      <div
+        className="placeholder placeholder-undefined"
+      >
+        Main Content
+      </div>
+      <div
+        className="placeholder placeholder-short"
+      >
+        More Content
+      </div>
+    </div>
+  </main>
+  <footer
+    className="css-0"
+  >
+    <div
+      className="placeholder placeholder-short"
+    >
+      Footer
+    </div>
+  </footer>
+</div>
+`;

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

@@ -1,14 +1,21 @@
 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 Text from "./Text";
+import { TextDisplaySizes } from "./TextTypes";
 import { getCategory } from "../../utils/componentCategories";
+import { getStorybookEnumValues } from "../../utils/utils";
+
+export const enumValues = getStorybookEnumValues(
+  TextDisplaySizes,
+  "TextDisplaySizes"
+);
 
 <Meta
   title={getCategory("Text")}
@@ -17,13 +24,19 @@ import { getCategory } from "../../utils/componentCategories";
   parameters={{
     design: {
       type: "figma",
-      url:
-        "https://www.figma.com/file/qShodlfNCJHb8n03IFyApM/?node-id=10733%3A56919",
+      url: "https://www.figma.com/file/qShodlfNCJHb8n03IFyApM/?node-id=10733%3A56919",
     },
   }}
   argTypes={{
-    displaySize: { table: { disable: false } },
-    className: { table: { disable: true } },
+    className: { control: false },
+    displaySize: {
+      control: { type: "select" },
+      options: enumValues.options,
+      table: { defaultValue: { summary: "TextDisplaySizes.Default" } },
+    },
+    isBold: { table: { defaultValue: { summary: false } } },
+    isItalic: { table: { defaultValue: { summary: false } } },
+    noSpace: { table: { defaultValue: { summary: false } } },
   }}
 />
 
@@ -39,10 +52,19 @@ import { getCategory } from "../../utils/componentCategories";
 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={{}}>
+  <Story
+    name="Text"
+    args={{
+      className: undefined,
+      displaySize: "TextDisplaySizes.Default",
+      isBold: false,
+      isItalic: false,
+      noSpace: false,
+    }}
+  >
     {(args) => (
       <>
-        <Text {...args}>
+        <Text {...args} displaySize={enumValues.getValue(args.displaySize)}>
           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
@@ -52,7 +74,7 @@ The `Text` component renders a basic `<p>` element. As its name indicates, the `
           open-ended gameplay and use of the video game console's internal clock
           and calendar to simulate real passage of time.
         </Text>
-        <Text {...args}>
+        <Text {...args} displaySize={enumValues.getValue(args.displaySize)}>
           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

package/src/components/Text/Text.tsx

@@ -6,14 +6,14 @@ import { getVariant } from "../../utils/utils";
 export interface TextProps {
   /** Additional class name to render in the `Text` component. */
   className?: string;
+  /** Optional prop to control the text styling */
+  displaySize?: TextDisplaySizes;
   /** 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>) {

package/src/components/TextInput/TextInput.stories.mdx

@@ -1,17 +1,23 @@
+import { VStack } from "@chakra-ui/react";
 import {
-  Meta,
-  Story,
   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 TextInput from "./TextInput";
-import { TextInputTypes } from "./TextInputTypes";
+import { TextInputTypes, TextInputVariants } from "./TextInputTypes";
 import { getCategory } from "../../utils/componentCategories";
 import DSProvider from "../../theme/provider";
+import { getStorybookEnumValues } from "../../utils/utils";
+
+export const enumValues = getStorybookEnumValues(
+  TextInputTypes,
+  "TextInputTypes"
+);
 
 <Meta
   title={getCategory("TextInput")}
@@ -20,16 +26,33 @@ import DSProvider from "../../theme/provider";
   parameters={{
     design: {
       type: "figma",
-      url:
-        "https://www.figma.com/file/qShodlfNCJHb8n03IFyApM/Master?node-id=11895%3A547",
+      url: "https://www.figma.com/file/qShodlfNCJHb8n03IFyApM/Master?node-id=11895%3A547",
     },
     jest: ["TextInput.test.tsx"],
   }}
   argTypes={{
-    attributes: { table: { disable: true } },
-    id: { table: { disable: true } },
-    onChange: { table: { disable: true } },
-    value: { table: { disable: true } },
+    attributes: { control: false },
+    id: { control: false },
+    isDisabled: { table: { defaultValue: { summary: false } } },
+    isInvalid: { table: { defaultValue: { summary: false } } },
+    isRequired: { table: { defaultValue: { summary: 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 } } },
+    step: { table: { defaultValue: { summary: 1 } } },
+    type: {
+      control: { type: "select" },
+      table: { defaultValue: { summary: "TextInputTypes.text" } },
+      options: enumValues.options,
+    },
+    value: { control: false },
+    variantType: {
+      control: false,
+      table: { defaultValue: { summary: "TextInputVariants.Default" } },
+    },
   }}
 />
 
@@ -38,7 +61,7 @@ import DSProvider from "../../theme/provider";
 | Component Version | DS Version |
 | ----------------- | ---------- |
 | Added             | `0.22.0`   |
-| Latest            | `0.25.4`   |
+| Latest            | `0.25.9`   |
 
 <Description of={TextInput} />
 
@@ -50,26 +73,36 @@ is left blank, a value will be generated for you.
 
 <Canvas withToolbar>
   <Story
-    name="TextInput"
+    name="TextInput with Controls"
     args={{
+      additionalStyles: undefined,
+      attributes: undefined,
+      className: undefined,
+      defaultValue: undefined,
       helperText: "Choose wisely.",
-      id: "myTextInput",
+      id: "textInput-id",
       invalidText: "This is error text :(",
       isDisabled: false,
       isInvalid: false,
       isRequired: true,
       labelText: "What is your favorite color?",
+      name: undefined,
+      onChange: undefined,
       placeholder: "e.g. blue, green, etc.",
+      showHelperInvalidText: true,
       showLabel: true,
       showOptReqLabel: true,
-      type: TextInputTypes.text,
+      step: 1,
+      type: "TextInputTypes.text",
+      value: undefined,
+      variantType: TextInputVariants.Default,
     }}
   >
-    {(args) => <TextInput {...args} />}
+    {(args) => <TextInput {...args} type={enumValues.getValue(args.type)} />}
   </Story>
 </Canvas>
 
-<ArgsTable story="TextInput" />
+<ArgsTable story="TextInput with Controls" />
 
 ## Labelling Variations
 
@@ -140,6 +173,36 @@ text within the `label` element.
   </DSProvider>
 </Canvas>
 
+## HTML in Helper Text
+
+HTML can be passed into the `helperText` prop as a string or HTML.
+
+```jsx
+helperText="Choose <b>wisely!</b>"
+// or
+helperText={<>Choose <b>wisely!</b></>}
+```
+
+<Canvas>
+  <DSProvider>
+    <TextInput
+      labelText="What is your favorite color?"
+      placeholder="i.e. blue, green, etc."
+      helperText="Choose <b>wisely!</b>"
+    />
+    <br />
+    <TextInput
+      labelText="What is your favorite color?"
+      placeholder="i.e. blue, green, etc."
+      helperText={
+        <>
+          Choose <b>wisely!</b>
+        </>
+      }
+    />
+  </DSProvider>
+</Canvas>
+
 ## Textarea
 
 The TextInput component includes a multiline `textarea` form field. To render a
@@ -161,6 +224,10 @@ variations described above are available for the `textarea` option.
       showOptReqLabel: true,
       type: TextInputTypes.textarea,
     }}
+    argTypes={{
+      type: { control: false },
+      variantType: { control: false },
+    }}
   >
     {(args) => <TextInput {...args} />}
   </Story>