Add component gallery descriptions (#2104)

## Summary: A component gallery was added in #2102 without descriptions. In this PR, I added descriptions for all the listed components. I also: - added IDs to the the component headings so that the table of components scrolls to the sections correctly. - added the external link icon to indicate that all the tiles link to their respective pages in new tabs. - made the gallery more mobile-friendly Issue: https://khanacademy.atlassian.net/browse/WB-1595 ## Test plan: - Go to http://localhost:6061/?path=/docs/overview--docs - Confirm that the descriptions all make sense and are all in the same tense. Author: nishasy Reviewers: jandrade Required Reviewers: Approved By: jandrade Checks: ❌ codecov/project, ✅ Check build sizes (ubuntu-latest, 16.x), ✅ Test (ubuntu-latest, 16.x, 2/2), ✅ Lint (ubuntu-latest, 16.x), ✅ Test (ubuntu-latest, 16.x, 1/2), ✅ Publish npm snapshot (ubuntu-latest, 16.x), ✅ Prime node_modules cache for primary configuration (ubuntu-latest, 16.x), ✅ Check for .changeset entries for all changed files (ubuntu-latest, 16.x), ✅ gerald, ✅ Chromatic - Get results on regular PRs (ubuntu-latest, 16.x), ✅ Test (ubuntu-latest, 16.x, 2/2), ✅ Test (ubuntu-latest, 16.x, 1/2), ✅ Check build sizes (ubuntu-latest, 16.x), ✅ Lint (ubuntu-latest, 16.x), ✅ Chromatic - Build on regular PRs / chromatic (ubuntu-latest, 16.x), ⏭ Publish npm snapshot, ⏭ Chromatic - Skip on Release PR (changesets), ✅ Prime node_modules cache for primary configuration (ubuntu-latest, 16.x), ✅ Check for .changeset entries for all changed files (ubuntu-latest, 16.x), ✅ gerald, ✅ Chromatic - Get results on regular PRs (ubuntu-latest, 16.x), ✅ Check build sizes (ubuntu-latest, 16.x), ✅ Test (ubuntu-latest, 16.x, 2/2), ✅ Lint (ubuntu-latest, 16.x), ✅ Test (ubuntu-latest, 16.x, 1/2), ✅ Chromatic - Build on regular PRs / chromatic (ubuntu-latest, 16.x), ⏭ Chromatic - Skip on Release PR (changesets), ⏭ Publish npm snapshot, ✅ Check for .changeset entries for all changed files (ubuntu-latest, 16.x), ✅ Prime node_modules cache for primary configuration (ubuntu-latest, 16.x) Pull Request URL: #2104
Khan · Nov 6, 2023 · 0d918a5 · 0d918a5
1 parent a6ac8f4
commit 0d918a5
Show file tree

Hide file tree

Showing 21 changed files with 272 additions and 116 deletions.
diff --git a/.changeset/brown-planets-relate.md b/.changeset/brown-planets-relate.md
@@ -0,0 +1,2 @@
+---
+---
diff --git a/__docs__/components/gallery/component-tile.tsx b/__docs__/components/gallery/component-tile.tsx
@@ -1,8 +1,10 @@
 import * as React from "react";
 import {StyleSheet} from "aphrodite";
+import externalLinkIcon from "@phosphor-icons/core/bold/arrow-square-out-bold.svg";
 
 import Clickable from "@khanacademy/wonder-blocks-clickable";
 import {View} from "@khanacademy/wonder-blocks-core";
+import {PhosphorIcon} from "@khanacademy/wonder-blocks-icon";
 import {tokens} from "@khanacademy/wonder-blocks-theming";
 import {Body, HeadingMedium} from "@khanacademy/wonder-blocks-typography";
 
@@ -17,12 +19,24 @@ export default function ComponentTile(props: Props) {
     const {children, description, name, href} = props;
     return (
         <View style={styles.tile}>
-            <Clickable href={href} target="_blank" style={styles.clickable}>
+            <Clickable
+                href={href}
+                target="_blank"
+                style={styles.clickable}
+                aria-label={`View ${name} component in a new tab.`}
+            >
                 {() => (
                     <>
                         <View style={styles.description}>
-                            <View style={styles.name}>
+                            <View style={styles.headingContainer}>
                                 <HeadingMedium tag="h4">{name}</HeadingMedium>
+                                <View style={styles.externalLinkIcon}>
+                                    <PhosphorIcon
+                                        icon={externalLinkIcon}
+                                        size="small"
+                                        aria-hidden="true"
+                                    />
+                                </View>
                             </View>
                             {description && (
                                 <Body style={styles.descriptionText}>
@@ -38,6 +52,8 @@ export default function ComponentTile(props: Props) {
     );
 }
 
+const mobile = "@media (max-width: 1023px)";
+
 const styles = StyleSheet.create({
     tile: {
         display: "flex",
@@ -46,6 +62,10 @@ const styles = StyleSheet.create({
         // Set the width to half the max width of the stories page content.
         width: 484,
         minHeight: 300,
+
+        [mobile]: {
+            width: "95%",
+        },
     },
     clickable: {
         backgroundColor: tokens.color.offWhite,
@@ -66,8 +86,10 @@ const styles = StyleSheet.create({
     description: {
         padding: tokens.spacing.large_24,
     },
-    name: {
+    headingContainer: {
         width: "fit-content",
+        flexDirection: "row",
+        alignItems: "center",
     },
     descriptionText: {
         marginTop: tokens.spacing.small_12,
@@ -81,5 +103,12 @@ const styles = StyleSheet.create({
         borderEndStartRadius: tokens.spacing.small_12,
         borderEndEndRadius: tokens.spacing.small_12,
         flexGrow: 1,
+
+        [mobile]: {
+            overflowX: "scroll",
+        },
+    },
+    externalLinkIcon: {
+        marginLeft: tokens.spacing.xSmall_8,
     },
 });
diff --git a/__docs__/components/gallery/sections/accordion-section.tsx b/__docs__/components/gallery/sections/accordion-section.tsx
@@ -13,14 +13,17 @@ import {styles} from "../styles";
 export default function AccordionGallerySection() {
     return (
         <RenderStateRoot>
-            <HeadingLarge tag="h3" style={styles.sectionLabel}>
+            <HeadingLarge id="accordion" tag="h3" style={styles.sectionLabel}>
                 Accordion
             </HeadingLarge>
 
             <View style={styles.section}>
                 <ComponentTile
                     name="Accordion"
                     href="/?path=/docs/accordion-accordion--docs"
+                    description={`A vertically stacked list of sections,
+                        each of which contains content that can be expanded
+                        or collapsed by clicking its header.`}
                 >
                     <Accordion>
                         <AccordionSection header="First section">
@@ -39,6 +42,9 @@ export default function AccordionGallerySection() {
                 <ComponentTile
                     name="AccordionSection"
                     href="/?path=/docs/accordion-accordionsection--docs"
+                    description={`A single collapsible section within
+                        an accordion. It can be used by itself or within
+                        an accordion.`}
                 >
                     <AccordionSection header="Accordion Section">
                         This is an accordion section.

diff --git a/__docs__/components/gallery/sections/banner-section.tsx b/__docs__/components/gallery/sections/banner-section.tsx
@@ -9,10 +9,16 @@ import {styles} from "../styles";
 export default function BannerSection() {
     return (
         <>
-            <HeadingLarge tag="h3" style={styles.sectionLabel}>
+            <HeadingLarge id="banner" tag="h3" style={styles.sectionLabel}>
                 Banner
             </HeadingLarge>
-            <ComponentTile name="Banner" href="/?path=/docs/banner--docs">
+            <ComponentTile
+                name="Banner"
+                href="/?path=/docs/banner--docs"
+                description={`Displays a prominent message and
+                    related optional actions. It can be used as a way
+                    of informing the user of important changes.`}
+            >
                 <Banner text="This is a banner!" layout="floating" />
             </ComponentTile>
         </>

diff --git a/__docs__/components/gallery/sections/birthday-picker-section.tsx b/__docs__/components/gallery/sections/birthday-picker-section.tsx
@@ -1,6 +1,7 @@
 import * as React from "react";
 
 import BirthdayPicker from "@khanacademy/wonder-blocks-birthday-picker";
+import {View} from "@khanacademy/wonder-blocks-core";
 import {HeadingLarge} from "@khanacademy/wonder-blocks-typography";
 
 import ComponentTile from "../component-tile";
@@ -9,14 +10,23 @@ import {styles} from "../styles";
 export default function BirthdayPickerSection() {
     return (
         <>
-            <HeadingLarge tag="h3" style={styles.sectionLabel}>
+            <HeadingLarge
+                id="birthday-picker"
+                tag="h3"
+                style={styles.sectionLabel}
+            >
                 Birthday Picker
             </HeadingLarge>
             <ComponentTile
                 name="BirthdayPicker"
                 href="/?path=/docs/birthdaypicker--docs"
+                description={`Similar to a datepicker, but specifically
+                    for birthdates. It consists of a set of dropdowns
+                    to choose the date.`}
             >
-                <BirthdayPicker onChange={() => {}} />
+                <View style={styles.centerContent}>
+                    <BirthdayPicker onChange={() => {}} />
+                </View>
             </ComponentTile>
         </>
     );

diff --git a/__docs__/components/gallery/sections/breadcrumbs-section.tsx b/__docs__/components/gallery/sections/breadcrumbs-section.tsx
@@ -4,6 +4,7 @@ import {
     Breadcrumbs,
     BreadcrumbsItem,
 } from "@khanacademy/wonder-blocks-breadcrumbs";
+import {View} from "@khanacademy/wonder-blocks-core";
 import Link from "@khanacademy/wonder-blocks-link";
 import {HeadingLarge} from "@khanacademy/wonder-blocks-typography";
 
@@ -13,22 +14,28 @@ import {styles} from "../styles";
 export default function BannerSection() {
     return (
         <>
-            <HeadingLarge tag="h3" style={styles.sectionLabel}>
+            <HeadingLarge id="breadcrumbs" tag="h3" style={styles.sectionLabel}>
                 Breadcrumbs
             </HeadingLarge>
             <ComponentTile
                 name="Breadcrumbs"
                 href="/?path=/docs/breadcrumbs--docs"
+                description={`A breadcrumb trail consists of a list of
+                    links to the parent pages of the current page in
+                    hierarchical order. It helps users find their place
+                    within a website or web application.`}
             >
-                <Breadcrumbs>
-                    <BreadcrumbsItem>
-                        <Link href="">Course</Link>
-                    </BreadcrumbsItem>
-                    <BreadcrumbsItem>
-                        <Link href="">Unit</Link>
-                    </BreadcrumbsItem>
-                    <BreadcrumbsItem>Lesson</BreadcrumbsItem>
-                </Breadcrumbs>
+                <View style={styles.centerContent}>
+                    <Breadcrumbs>
+                        <BreadcrumbsItem>
+                            <Link href="">Course</Link>
+                        </BreadcrumbsItem>
+                        <BreadcrumbsItem>
+                            <Link href="">Unit</Link>
+                        </BreadcrumbsItem>
+                        <BreadcrumbsItem>Lesson</BreadcrumbsItem>
+                    </Breadcrumbs>
+                </View>
             </ComponentTile>
         </>
     );

diff --git a/__docs__/components/gallery/sections/button-section.tsx b/__docs__/components/gallery/sections/button-section.tsx
@@ -11,10 +11,14 @@ import {styles} from "../styles";
 export default function BannerSection() {
     return (
         <>
-            <HeadingLarge tag="h3" style={styles.sectionLabel}>
+            <HeadingLarge id="button" tag="h3" style={styles.sectionLabel}>
                 Button
             </HeadingLarge>
-            <ComponentTile name="Button" href="/?path=/docs/button--docs">
+            <ComponentTile
+                name="Button"
+                href="/?path=/docs/button--docs"
+                description="Standard button. Triggers an action."
+            >
                 <Button
                     kind="primary"
                     onClick={() => {}}

diff --git a/__docs__/components/gallery/sections/cell-section.tsx b/__docs__/components/gallery/sections/cell-section.tsx
@@ -13,13 +13,16 @@ import {styles} from "../styles";
 export default function BannerSection() {
     return (
         <>
-            <HeadingLarge tag="h3" style={styles.sectionLabel}>
+            <HeadingLarge id="cell" tag="h3" style={styles.sectionLabel}>
                 Cell
             </HeadingLarge>
             <View style={styles.section}>
                 <ComponentTile
                     name="CompactCell"
                     href="/?path=/docs/cell-compactcell--docs"
+                    description={`A compacted-height cell with limited
+                        subviews and accessories. Typically they represent
+                        additional info or selection lists.`}
                 >
                     <View style={localStyles.cellExample}>
                         <CompactCell
@@ -34,6 +37,10 @@ export default function BannerSection() {
                 <ComponentTile
                     name="DetailCell"
                     href="/?path=/docs/cell-detailcell--docs"
+                    description={`A compact cell that allows adding
+                        subtitles before and after the cell title. They
+                        typically represent an item that can be
+                        clicked/tapped to view more complex details.`}
                 >
                     <View style={localStyles.cellExample}>
                         <DetailCell