Merge pull request #1655 from NYPL/development

Release v3.3.0

.gitignore

@@ -7,7 +7,6 @@ dependencyGraph.json
 .DS_Store
 lib
 dist
-.vscode
 .eslintcache
 coverage
 .idea

.prettierignore

@@ -1 +1,2 @@
 /.jest-test-results.json
+/src/components/DevelopmentGuide/ConditionalViewport.mdx 

.vscode/settings.json

@@ -4,4 +4,4 @@
   "editor.defaultFormatter": "esbenp.prettier-vscode",
   "typescript.enablePromptUseWorkspaceTsdk": true,
   "typescript.tsdk": "node_modules/typescript/lib"
-}
+}

CHANGELOG.md

@@ -8,17 +8,40 @@ Currently, this repo is in Prerelease. When it is released, this project will ad
 
 ## Prerelease
 
+## 3.3.0 (August 29, 2024)
+
+### Adds
+
+- Adds development guide for Conditional Viewport
+- Adds the `FilterBarPopup` compoonent and `useFilterBarPopup` hook.
+
+### Updates
+
+- Updates the `FilterBarInline` component to apply `closeOnBlur` to `MultiSelect` components when `layout="row"`.
+- Updates the `Breadcrumbs` component props to include `customLinkComponent` and `linkProps`.
+- Updates the `Banner` component to allow for HTML content in the `content` prop when passed as a string.
+- Updates the `SearchBar` component styles for mobile viewports.
+- Updates the `Select` component to accept a `defaultValue` prop to set initial value of uncontrolled components.
+- Updates the legend in the `MultiSelect`'s `CheckboxGroup` to use the `buttonText` prop value for better accessibility context.
+- Updates the `Menu` component to add the `showSelectionAsLabel` prop and improve the `aria-label` values.
+- Updates the `Image` component to default the `alt` attribute to an empty string if no value is passed.
+
+### Removes
+
+- Removes `imageProps.alt` missing warning message from `FeaturedContent` as the prop is not always required.
+
 ## 3.2.0 (July 25, 2024)
 
 ### Adds
 
 - Adds the `FilterBarInline` component.
 - Adds refined `NewsletterSignup` component with updated props.
-- Adds refined `SocialMediaLinks` component with updated props.
+- Adds refined `SocialMediaLinks` component with updated props
 
 ### Updates
 
 - Updates Storybook and related npm packages to version `8.1.11`. Does not affect any DS component.
+- Updates `Menu` component with new `showSelectionAsLabel` prop and `aria-label` behavior.
 - Updates the `Banner`, `Button`, `ButtonGroup`, `DatePicker`, `FeaturedContent`, `FeedbackBox`, `Fieldset`, `HelperErrorText`, `Label`, `SkipNavigation`, and `StyledList` components to export all types and prop interfaces.
 
 ## 3.1.7 (July 3, 2024)

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nypl/design-system-react-components",
-  "version": "3.2.0",
+  "version": "3.3.0",
   "description": "NYPL Reservoir Design System React Components",
   "repository": {
     "type": "git",

src/components/Banner/Banner.mdx

@@ -12,7 +12,7 @@ import { changelogData } from "./bannerChangelogData";
 | Component Version | DS Version |
 | ----------------- | ---------- |
 | Added             | `3.1.0`    |
-| Latest            | `3.2.0`    |
+| Latest            | `3.3.0`    |
 
 ## Table of Contents
 
@@ -25,6 +25,7 @@ import { changelogData } from "./bannerChangelogData";
 - {<Link href="#with-html-content" target="_self">With HTML Content</Link>}
 - {<Link href="#custom-color" target="_self">Custom Color</Link>}
 - {<Link href="#dismissible" target="_self">Dismissible</Link>}
+- {<Link href="#with-html-content-passed-as-string" target="_self">With HTML content passed as string</Link>}
 - {<Link href="#changelog" target="_self">Changelog</Link>}
 
 ## Overview
@@ -234,6 +235,22 @@ renders once.
 
 <Canvas of={BannerStories.Dismissible} />
 
+## With HTML content passed as string
+
+HTML content passed as a string is rendered as HTML, useful in cases where HTML content is stored in an environment variable or from other sources where the content is stored as strings.
+
+<Source
+  code={`
+<Banner
+  heading="Standard Banner with HTML content passed as string"
+  content="<p>Cras mattis consectetur purus sit amet fermentum. Maecenas faucibus mollis interdum.</p><p>Morbi leo risus, porta ac consectetur ac, vestibulum at eros. <b>Cum sociis natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus</b>. <a href='#'>This is a link</a>.</p>"
+/>
+`}
+  language="tsx"
+/>
+
+<Canvas of={BannerStories.StringContentWithHTML} />
+
 ## Changelog
 
 <ComponentChangelogTable changelogData={changelogData} />

src/components/Banner/Banner.stories.tsx

@@ -396,3 +396,14 @@ export const Dismissible: Story = {
     />
   ),
 };
+export const StringContentWithHTML: Story = {
+  render: () => (
+    <Banner
+      content={
+        "<p>Cras mattis consectetur purus sit amet fermentum. Maecenas faucibus mollis interdum.</p><p>Morbi leo risus, porta ac consectetur ac, vestibulum at eros. <b>Cum sociis natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus</b>. <a href='#'>This is a link</a>.</p>"
+      }
+      heading="String content with HTML"
+      type="neutral"
+    />
+  ),
+};

src/components/Banner/Banner.test.tsx

@@ -353,4 +353,15 @@ describe("Banner", () => {
 
     expect(container.querySelector("aside")).toBe(ref.current);
   });
+
+  it("renders string content as div with dangerouslySetInnerHTML", () => {
+    utils.rerender(
+      <Banner
+        id="bannerID"
+        content="<p data-testid='dangerous'>Dangerous HTML</p>"
+      />
+    );
+
+    expect(screen.getByTestId("dangerous")).toHaveTextContent("Dangerous HTML");
+  });
 });

src/components/Banner/Banner.tsx

@@ -243,7 +243,13 @@ export const Banner: ChakraComponent<
         {finalIcon}
         <Box maxWidth="800px">
           {heading && finalHeading}
-          {content}
+          {/* Render string content as div with dangerouslySetInnerHTML prop in case HTML is passed in as string
+            (e.g. notification HTML stored in an environment variable. */}
+          {typeof content === "string" ? (
+            <Box dangerouslySetInnerHTML={{ __html: content }} />
+          ) : (
+            <>{content}</>
+          )}
         </Box>
         {isDismissible && dismissibleButton}
       </Box>

src/components/Banner/bannerChangelogData.ts

@@ -9,6 +9,15 @@
 import { ChangelogData } from "../../utils/ComponentChangelogTable";
 
 export const changelogData: ChangelogData[] = [
+  {
+    date: "2024-08-29",
+    version: "3.3.0",
+    type: "Update",
+    affects: ["Functionality"],
+    notes: [
+      "Render HTML content when passed as a string in the `content` prop.",
+    ],
+  },
   {
     date: "2024-07-25",
     version: "3.2.0",

src/components/Breadcrumbs/Breadcrumbs.mdx

@@ -12,14 +12,15 @@ import Link from "../Link/Link";
 | Component Version | DS Version |
 | ----------------- | ---------- |
 | Added             | `0.0.3`    |
-| Latest            | `3.1.7`    |
+| Latest            | `3.3.0`    |
 
 ## Table of Contents
 
 - {<Link href="#overview" target="_self">Overview</Link>}
 - {<Link href="#component-props" target="_self">Component Props</Link>}
 - {<Link href="#accessibility" target="_self">Accessibility</Link>}
 - {<Link href="#long-titles" target="_self">Long Titles</Link>}
+- {<Link href="#custom-link-and-link-props" target="_self">Custom Link and Link Props</Link>}
 - {<Link href="#color-variations" target="_self">Color Variations</Link>}
 - {<Link href="#changelog" target="_self">Changelog</Link>}
 
@@ -69,6 +70,36 @@ the truncated page title.
 
 <Canvas of={BreadcrumbsStories.LongText} />
 
+## Custom Link Component and Link Props
+
+The `customLinkComponent` prop allows apps with internal routers (Next.js, for example) to pass their custom link component
+into the `Breadcrumbs` component. This allows the `Breadcrumbs` links to use client-side routing, so users can navigate between pages without reloading the full page.
+
+Additionally, the `linkProps` prop on `breadcrumbsData` allows any of the framework's [custom props](https://nextjs.org/docs/app/api-reference/components/link) to be applied on a link-by-link basis.
+
+Note: assigning a value for `href` in `linkProps` will override the `url` prop, so we recommend against this.
+
+<Source
+  code={`
+  // Example with Next.js Link and its associated custom props (scroll, replace, prefetch)
+import Link from "next/link";
+
+const breadcrumbsDataWithLinkProps = [
+{ url: "#", text: "Parent", linkProps: { replace: true, scroll: false }}
+{ url: "#", text: "Child", linkProps: { replace: true }}
+{ url: "#", text: "Grandchild" },
+];
+
+<Breadcrumbs
+  customLinkComponent={Link}
+  breadcrumbsData={breadcrumbsDataWithLinkProps}
+/>
+`} language="tsx" />
+
+Below story uses the DS `Link` component.
+
+<Canvas of={BreadcrumbsStories.CustomLinkComponent} />
+
 ## Color Variations
 
 The `Breadcrumbs` component background color can be set to a value of the

src/components/Breadcrumbs/Breadcrumbs.stories.tsx

@@ -1,14 +1,21 @@
 import { Box, VStack } from "@chakra-ui/react";
 import type { Meta, StoryObj } from "@storybook/react";
-
 import Breadcrumbs, { breadcrumbTypeArray } from "./Breadcrumbs";
 import Heading from "../Heading/Heading";
+import Link from "../Link/Link";
 
 const breadcrumbsData = [
   { url: "#", text: "Parent" },
   { url: "#", text: "Child" },
   { url: "#", text: "Grandchild" },
 ];
+
+const linkPropsBreadcrumbsData = [
+  { url: "#", text: "Parent", linkProps: { target: "_top" } },
+  { url: "#", text: "Child", linkProps: { target: "_top" } },
+  { url: "#", text: "Grandchild", linkProps: { target: "_top" } },
+];
+
 const breadcrumbsLongTextData = [
   { url: "#", text: "Parent with a Long Name" },
   { url: "#", text: "Child with an Even Longer Name" },
@@ -27,6 +34,7 @@ const meta: Meta<typeof Breadcrumbs> = {
   component: Breadcrumbs,
   argTypes: {
     breadcrumbsData: { control: false },
+    customLinkComponent: { control: false },
     breadcrumbsType: {
       table: { defaultValue: { summary: "whatsOn" } },
       control: {
@@ -51,6 +59,7 @@ export const WithControls: Story = {
     breadcrumbsData,
     breadcrumbsType: "whatsOn",
     className: undefined,
+    customLinkComponent: undefined,
     id: "breadcrumbs-id",
   },
   parameters: {
@@ -66,6 +75,14 @@ export const WithControls: Story = {
 export const LongText: Story = {
   render: () => <Breadcrumbs breadcrumbsData={breadcrumbsLongTextData} />,
 };
+export const CustomLinkComponent: Story = {
+  render: () => (
+    <Breadcrumbs
+      customLinkComponent={Link}
+      breadcrumbsData={linkPropsBreadcrumbsData}
+    />
+  ),
+};
 export const ColorVariations: Story = {
   render: () => (
     <VStack align="stretch" spacing="l">
@@ -76,6 +93,7 @@ export const ColorVariations: Story = {
         <Breadcrumbs
           breadcrumbsData={breadcrumbsData}
           breadcrumbsType="blogs"
+          customLinkComponent={Link}
         />
       </Box>
       <Box>

src/components/Breadcrumbs/Breadcrumbs.test.tsx

@@ -2,6 +2,7 @@ import { render, screen } from "@testing-library/react";
 import { axe } from "jest-axe";
 import { createRef } from "react";
 import renderer from "react-test-renderer";
+import Link from "../Link/Link";
 
 import Breadcrumbs from "./Breadcrumbs";
 
@@ -10,6 +11,13 @@ const breadcrumbsData = [
   { url: "#string2", text: "string2" },
   { url: "#string3", text: "string3" },
 ];
+
+const breadcrumbsDataLinkProps = [
+  { url: "#string1", text: "string1", linkProps: { target: "_top" } },
+  { url: "#string2", text: "string2" },
+  { url: "#string3", text: "string3" },
+];
+
 const breadcrumbsDataLongText = [
   { url: "#string1", text: "Parent with a Long Name" },
   {
@@ -89,6 +97,34 @@ describe("Breadcrumbs", () => {
     );
   });
 
+  it("replaces BreadcrumbsLink when customLinkComponent is passed", () => {
+    render(
+      <Breadcrumbs
+        customLinkComponent={Link}
+        breadcrumbsData={breadcrumbsDataLinkProps}
+      />
+    );
+    expect(screen.getByText("string1").closest("a")).toHaveClass("chakra-link");
+  });
+
+  it("does not replace BreadcrumbsLink when no custom link is passed", () => {
+    render(<Breadcrumbs breadcrumbsData={breadcrumbsDataLinkProps} />);
+    expect(screen.getByText("string1").closest("a")).toHaveClass(
+      "chakra-breadcrumb__link"
+    );
+    expect(screen.getByText("string1").closest("a")).not.toHaveClass(
+      "chakra-link"
+    );
+  });
+
+  it("passes linkProps to specified breadcrumbs", () => {
+    render(<Breadcrumbs breadcrumbsData={breadcrumbsDataLinkProps} />);
+    expect(screen.getByText("string1").closest("a")).toHaveAttribute(
+      "target",
+      "_top"
+    );
+  });
+
   it("passes a ref to the nav wrapper element", () => {
     // It's okay to use this type even though the rendered element is
     // a `nav` since Chakra internally generates the necessary DOM.