Merge pull request #1434 from NYPL/DR-2525/featuredcontent

DR-2525 FeaturedContent Component

CHANGELOG.md

@@ -19,6 +19,7 @@ Currently, this repo is in Prerelease. When it is released, this project will ad
 - Updates `DatePicker` so that focus remains on input after value is changed.
 - Updates the `FeedbackBox` component to remove the underline on the component's `Privacy Policy` link.
 - Updates `DatePicker` to pass a `additionalHelperTextIds` to its `TextInput` if needed so that the `aria-describedby` value can be associated with all relevant `helperText`s.
+- Adds the `FeaturedContent` component.
 
 ### Fixes
 

src/components/FeaturedContent/FeaturedContent.mdx

@@ -0,0 +1,84 @@
+import { ArgTypes, Canvas, Description, Meta, Source } from "@storybook/blocks";
+import { changelogData } from "./featuredContentChangelogData";
+import ComponentChangelogTable from "../../utils/ComponentChangelogTable";
+import * as FeaturedContentStories from "./FeaturedContent.stories";
+import Link from "../Link/Link";
+
+<Meta of={FeaturedContentStories} />
+
+# Featured Content
+
+| Component Version | DS Version |
+| ----------------- | ---------- |
+| Added             | Prerelease |
+| Latest            | Prerelease |
+
+## 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="#component-width-variations" target="_self">Component Width Variations</Link>}
+- {<Link href="#image-position-variations" target="_self">Image Position Variations</Link>}
+- {<Link href="#image-width-variations" target="_self">Image Width Variations</Link>}
+- {<Link href="#changelog" target="_self">Changelog</Link>}
+
+## Overview
+
+The `FeaturedContent` component provides a method to visually emphasize a text block with an image, within a full page layout.
+
+## Component Props
+
+<Canvas of={FeaturedContentStories.WithControls} />
+
+<ArgTypes of={FeaturedContentStories.WithControls} />
+
+## Accessibility
+
+The `FeaturedContent` component combines a text block and an image. The text block (`textContent`) can be any JSX element, so accessibility for child input elements should follow the accessibility requirements specified for each input component (for example, [Button](https://nypl.github.io/nypl-design-system/reservoir/v1/?path=/docs/components-form-elements-button--docs)).
+All images must have an `alt` attribute, even if it's empty. The `alt` prop should be used to concisely describe the image.
+If the image is decorative, then the `alt` prop should be an empty string `""`.
+
+Resources for text accessibility:
+
+- [Chakra UI Text](https://chakra-ui.com/docs/components/typography/text)
+
+Resources for image accessibility:
+
+- [W3C WAI Images Tutorial](https://www.w3.org/WAI/tutorials/images/)
+- [WebAIM Accessible Images](https://webaim.org/techniques/images/)
+- [Yale Usability & Web Accessibility](https://usability.yale.edu/web-accessibility/articles/images)
+
+## Component Width Variations
+
+The width variations of the `FeaturedContent` component can be rendered through the `isFullWidth` prop.
+The default is `isFullWidth = false`, and the component will fill only its parent. If `isFullWidth = true`, component will fill the screen's width (max 1280px), breaking out of its parent container.
+This full layout is best viewed on a full screen, not as shown below.
+
+<Canvas of={FeaturedContentStories.LayoutVariations} />
+
+## Image Position Variations
+
+The image position variations of the `FeaturedContent` component can be rendered through the `imageProps.position` prop. The default is `end`, and the image will appear after the text block in a row (on mobile, it will appear below).
+The other option is `start`, where the image will appear before the text block in the row on desktop (and above it on mobile).
+
+<Canvas of={FeaturedContentStories.ImagePositionVariations} />
+
+## Image Width Variations
+
+The image width variations of the `FeaturedContent` component can be rendered through the `imageProps.width` prop.
+The options for width are `oneQuarter`, `oneThird`, `oneHalf`, `twoThirds`, and `threeQuarters`. The default width is `oneHalf`.
+
+<Canvas of={FeaturedContentStories.imageWidthVariations} />
+
+## Text Content
+
+`textContent` is a string or JSX element passed into `FeaturedContent`, so accessibility standards and spacing should be considered independently of the `FeaturedContent` styling.
+
+The above example with an overline, a heading, a short paragraph of body text, and a CTA button is the recommended usage. While other configurations are possible, keep in mind that the minimum height of the component is 320px and it is best to avoid excessive white space.
+
+<Canvas of={FeaturedContentStories.textContentVariations} />
+
+## Changelog
+
+<ComponentChangelogTable changelogData={changelogData} />