Merge branch 'release' into gh-pages

CHANGELOG.md

@@ -8,6 +8,18 @@ Currently, this repo is in Prerelease. When it is released, this project will ad
 
 ## Prerelease
 
+## 3.1.0 (April 11, 2024)
+
+### Adds
+
+- Adds the `"actionLightbulb"` option to the `Icon` component.
+- Adds the `Banner` component.
+- Adds the `MultiSelectGroup` v2 component.
+
+### Updates
+
+- Updates the `DatePicker`, `Select`, `Slider`, and `TextInput` components to reduce the spacing between the field label and the field itself from `"8px"` to `"2px"`.
+
 ## 3.0.1 (March 28, 2024)
 
 ### Adds

package.json

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

src/__tests__/utils/getSectionColors.test.ts

@@ -84,7 +84,7 @@ describe("getSectionColors", () => {
     expect(locations).toEqual("dark.section.locations.secondary");
     expect(researchLibraryLpa).toEqual("dark.section.research-library.lpa");
     expect(researchLibrarySchwarzman).toEqual(
-      "dark.section.research-library.schwartzman"
+      "dark.section.research-library.schwarzman"
     );
     expect(whatsOn).toEqual("dark.section.whats-on.secondary");
   });

src/components/Banner/Banner.mdx

@@ -0,0 +1,239 @@
+import { ArgTypes, Canvas, Description, Meta, Source } from "@storybook/blocks";
+
+import * as BannerStories from "./Banner.stories";
+import Link from "../Link/Link";
+import ComponentChangelogTable from "../../utils/ComponentChangelogTable";
+import { changelogData } from "./bannerChangelogData";
+
+<Meta of={BannerStories} />
+
+# Banner
+
+| Component Version | DS Version |
+| ----------------- | ---------- |
+| Added             | `3.1.0`    |
+| Latest            | `3.1.0`    |
+
+## Table of Contents
+
+- {<Link href="#overiew" target="_self">Overview</Link>}
+- {<Link href="#component-props" target="_self">Component Props</Link>}
+- {<Link href="#accessibility" target="_self">Accessibility</Link>}
+- {<Link href="#variants" target="_self">Variants</Link>}
+- {<Link href="#banner-heading" target="_self">Banner Heading</Link>}
+- {<Link href="#banner-icon" target="_self">Banner Icon</Link>}
+- {<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="#changelog" target="_self">Changelog</Link>}
+
+## Overview
+
+<Description of={BannerStories} />
+
+**IMPORTANT:** The `Banner` component is similar in form and function to the
+`Notification` component. However, the `Notification` component should be used
+for global messaging located at the top of the site, above the NYPL header,
+while the `Banner` component should be used for all messaging that sits within
+the flow of the page.
+
+## Component Props
+
+<Canvas of={BannerStories.WithControls} />
+
+<ArgTypes of={BannerStories.WithControls} />
+
+## Accessibility
+
+The `Banner` component renders with an HTML `aside` element as its
+wrapper. This is an HTML landmark element that is similar to adding an attribute
+of `role="complementary"`. For accessibility purposes, landmark elements should
+not be rendered inside other landmark elements such as the `header` and `footer`
+landmark elements. Adding a `Banner` component inside an HTML `main`
+landmark element is acceptable.
+
+### ARIA Label
+
+If an `aria-label` is needed, it can be set through the `ariaLabel` prop. If
+there are multiple `Banner` components on a page, they must each have unique
+`aria-label` attributes. A unique `aria-label` value, along with the
+`<aside>` HTML landmark element, helps screen readers better navigate a page
+with multiple `Banner`s.
+
+### Icons
+
+Icons rendered in the `Banner` component are decorative by default which
+means that they are hidden to screen readers. If `isDismissable` is true, the
+"X" close icon is wrapped inside a button with an appropriate `aria-label`
+attribute.
+
+### Language Patterns
+
+When the `Banner` component is rendered, the text within the component
+should always include wording that aligns with the type of notitication that is
+being delivered. For example, if the Banner is a warning or error, the
+heading or body copy within the Banner should use the words `"warning"` or
+`"error"` and provide a clear description of the existing or potential isssue.
+
+### Dynamic Banners
+
+If dynamically generated `Banners` are required, a container into which the
+`Banner` will be injected should be included in the DOM. The container
+element should have `aria-live="polite"` applied. The container element should
+always be rendered in the DOM regardless of the presence of the `Banner`
+component. This DOM structure will allow the newly generated content to be
+recognized and announced by assistive technology.
+
+<Source
+  code={`
+<div aria-live="polite">
+  <Banner {...props} />
+</div>
+`}
+  language="tsx"
+/>
+
+### Resources
+
+- [MDN Aria: complementary role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/complementary_role)
+- [Deque Creating Accessible SVGs](https://www.deque.com/blog/creating-accessible-svgs/)
+- [CSS Tricks Accessible SVG Icons](https://css-tricks.com/accessible-svg-icons/)
+- [Reservoir Accessibility Guide: Dynamic Content](..?path=/docs/accessibility-guide-dynamic-content--docs)
+
+## Variants
+
+The `type` prop can be used to render different variants of `Banner`. Each
+variant has a different color and iconography.
+
+It is recommended to align the usage of the Banner component to the semantic
+meaning of one of the component’s variants. When using the Banner component,
+the implementation should not rely on the color alone to convey meaning, as
+color is not a universal experience for everyone. The meaning of the heading
+and body copy should align with the general meaning associated with the semantic
+colors used in a specific variant.
+
+**IMPORTANT:** The text color for links within the content will NOT use the
+DS standard link color. Instead, the color will match the color of the content.
+Additionally, links will always be underlined.
+
+**IMPORTANT:** For the "negative" variant only, the heading and text color will
+both be set to the same color, `ui.error.primary` and `dark.ui.error.primary`
+for dark mode.
+
+<Canvas of={BannerStories.TypeVariants} />
+
+## Banner Heading
+
+The `Banner` component can be rendered with and without a heading. By
+default, when a string is passed to the `heading` prop, the
+`Banner` component will render an `h2` element sized as a `heading6`
+heading. If this causes accessibility issues in your app, you can set a custom
+heading by passing in a DS `Heading` component.
+
+In the following examples, the `Banner` component will render custom `h3`
+and `h5` elements. Note that no matter what heading level is set, the size will
+always be set to `heading6` internally by the `Banner` component.
+
+<Source
+  code={`
+
+const customH3 = <Heading level="h3">Custom H3 Heading</Heading>;
+const customH5 = <Heading level="h5">Custom H5 Heading</Heading>;
+
+<Banner heading={customH3} {...props} />
+<Banner heading={customH5} {...props} />
+`} language="tsx" />
+
+<Canvas of={BannerStories.BannerHeading} />
+
+## Banner Icon
+
+The default icon can be overridden by using the `icon` prop to pass a
+custom `Icon` component. Make sure to set `size="large"` and `marginTop="xxxs"`
+as props to match desired styling.
+
+<Source
+  code={`
+<Banner
+  content={
+    <>
+      Cras mattis consectetur purus sit amet fermentum. Maecenas faucibus
+      mollis interdum. Morbi leo risus, porta ac consectetur ac,
+      vestibulum at eros. Cum sociis natoque penatibus et magnis dis
+      parturient montes, nascetur ridiculus mus.
+    </>
+  }
+  heading="Banner with Custom Icon"
+  icon={
+    <Icon
+      name="actionLightbulb"
+      title="Banner with custom icon"
+      size="large"
+      marginTop="xxxs"
+    />
+  }
+  type="informative"
+/>
+`}
+  language="tsx"
+/>
+
+<Canvas of={BannerStories.CustomBannerIcon} />
+
+## With HTML Content
+
+The `content` prop can accept HTML.
+
+<Source
+  code={`
+<Banner
+  heading="Standard Banner with HTML content"
+  content={
+    <>
+      <Text>
+        Cras mattis consectetur purus sit amet fermentum. Maecenas
+        faucibus mollis interdum.
+      </Text>
+      <Text noSpace>
+        Morbi leo risus, porta ac consectetur ac, vestibulum at eros.{" "}
+        <b>
+          Cum sociis natoque penatibus et magnis dis parturient montes,
+          nascetur ridiculus mus
+        </b>
+        . <Link href="#">This is a link</Link>.
+      </Text>
+    </>
+  }
+/>
+`}
+  language="tsx"
+/>
+
+<Canvas of={BannerStories.HTMLContent} />
+
+## Custom Color
+
+It is recommended to rely on the color styles set with the `type` prop.
+However, in cases where a different color is necessary, a value from a defined
+set of colors can be used. Both `backgroundColor` and `highlightColor` must be
+set in order to override the predefined variant types.
+
+- The `backgroundColor` prop can be used to set the color of the entire
+  background.
+- The `highlightColor` prop can be used to set the color of the left border
+  and the icon.
+
+<Canvas of={BannerStories.CustomColors} />
+
+## Dismissible
+
+A dismissible `Banner` component can be created by setting the
+`isDismissible` prop to `true`. Once the "X" close icon on the upper right is
+clicked, the `Banner` will be removed from the DOM, therefore it only
+renders once.
+
+<Canvas of={BannerStories.Dismissible} />
+
+## Changelog
+
+<ComponentChangelogTable changelogData={changelogData} />