feat: ResourceListDetails doc block (#3129)

* chore: add componentGuidelinesName to package.json

- components that have a valid page on the spectrum guidelines site have
a componentGuidelinesName key now.
- components that do not have a valid page on the spectrum guidelines
site have a componentBetaName key that will point to the
spectrum-contributions site.
- for components that do not any guidelines, setting the
componentGuidelinesName key to an empty string in the package.json will
make sure the guidelines resource card doesn't render.

* feat: resource list component doc block

The ResourceListDetails fetches data from each storybook component's
package.json, specifically utilizing the package name and optional
componentGuidelinesName. It then creates links to the spectrum
guidelines, github, and npm sites. If a component doesn't have a
spectrum guidelines page, it uses the optional componentBetaName and the
spectrum-contributions site instead.

- creates new `styled` components related to the resource section, any
element wrappers and links
- creates ResourceListDetails doc block
- creates ResourceListContent component (which are the individual
resource cards)
- adds some helper functions to generate SVGs corresponding to the links,
switch statements, mapping text, etc.

* refactor: add support for nested components

this applies to form and meter. Form should no longer render a guidelines
link card, and meter should navigate to its own guidelines page instead
of progress bar's.

* chore: pr fixes

- update spacing for if() statement
- render ResourceListDetails in ComponentDetails
- console.warn instead of throw an error
- hard codes styles for cards

* refactor: svg usage

- extracts SVG code to individual jsx files
- imports those SVG jsx files to use a components
- replaces/refactors svg functions to render new svg components

* chore: update package.json

- creates a `spectrum` key in each component's package.json to use in
ComponentDetails
- `spectrum` array holds metadata for components and/or nested
components, like the componentName, the guidelineLink, and rootClass
- eventually we may be able to add designLink to add Figma links to this
block

* refactor: resource list component fixes

- reorganizes file so ResourceLinkContent and ResourceListDetails are
closer to CopmonentDetails, and all fetching/processing helper functions
are together
- addresses missing field label guidelines link
- removes some hardcoded nestedComponent code in favor for a for loop
- indentation fixes

* chore: break out resource link config

* chore: add componentName back to package.json

* docs: revert componentName in favor of docsPage: false

- removed componentName from field label and progress bar package.jsons
- created docsPage parameter for form in the storyMeta
- refactored the nested component for loop to check if the guidelines
are defined, and if docsPage is undefined. If both of those check out,
render the guidelines link. Form is the only component that needed this,
since it's the only nested component that doesn't have a guidelines page
while its parent (field label) does.

* chore: refactor to check for unique rootClass

To better capture nested components, as well as components that may not
have a guidelines page, this refactor double checks that the hasDocsPage
prop is undefined, as well as that the spectrum.rootClass value includes
a transformed component title. Adding the additional check of the
rootClass helped ensure the proper guidelines link was rendering for
nested components, as well as breaking when the condition was met.

* chore: refactor to use meta.args.rootClass

- instead of comparing a story's title (because meter didn't have a
unique rootClass), compare the spectrum.rootClass to the
meta.args.rootClass. This is possible now because we have updated the
default args for meter to be spectrum-Meter.
- removes usage or reformatTitle and hasDocsPage functions and props
- adds more thorough JSDoc comments

* chore: fix color loupe's root class in package.json

* chore: fixes after rebase

* docs: add quickaction guidelines link

- white space removal

* chore: add condition for deprecated component github links

* chore: pr fixes

- change status prop name to isDeprecated
- remove unnecessary skipBorder prop

* chore: do not render github cards for deprecated components

---------

Co-authored-by: castastrophe <castastrophe@users.noreply.github.com>

Author: marissahuysentruyt

.storybook/assets/images/adobe_logo.svg

@@ -2,7 +2,10 @@ import { useOf } from '@storybook/blocks';
 import { ResetWrapper } from "@storybook/components";
 import { styled } from "@storybook/theming";
 import React, { useEffect, useState } from "react";
-import { Code } from "./Typography.jsx";
+import AdobeSVG from "../assets/images/adobe_logo.svg?raw";
+import GitHubSVG from "../assets/images/github_logo.svg?raw";
+import NpmSVG from "../assets/images/npm_logo.svg?raw";
+import { Body, Code, Heading } from "./Typography.jsx";
 import { fetchToken } from "./utilities.js";
 
 export const DList = styled.dl`
@@ -97,6 +100,45 @@ export const StatusLight = styled.span(({ variant = "positive", ...props }) => `
 	margin-block-end: 1px;
 `);
 
+export const ResourceSection = styled.section`
+	display: flex;
+	flex-flow: row wrap;
+	align-items: center;
+`;
+
+export const ResourceLink = styled.a`
+	position: relative;
+	display: inline-flex;
+	flex-direction: row;
+	align-items: center;
+	margin-block-end: 16px;
+	margin-inline-end: 16px;
+	box-sizing: border-box;
+	text-decoration: none;
+	min-inline-size: 100px;
+	border: 1px solid transparent;
+	border-radius: 5px;
+	border-color: rgb(230, 230, 230);
+	overflow: hidden;
+	color: rgb(0, 0, 0);
+
+	&:hover {
+		border-color: rgb(213, 213, 213);
+	}
+`;
+
+export const ResourceIconWrapper = styled.div`
+	background-color: rgba(248, 248, 248);
+	padding: 12px;
+	display: flex;
+	inline-size: 40px;
+	block-size: 40px;
+`;
+
+export const ResourceTextWrapper = styled.div`
+	margin-inline: 16px;
+`;
+
 const VersionDetails = ({ tag, data = {}, isDeprecated = false, skipDate = false, skipLink = false }) => {
 	let statusType = "notice";
 	let statusMessage = "Not yet available on the npm registry.";
@@ -264,13 +306,104 @@ function fetchNpmData(packageName, setnpmData, setIsLoading) {
 	}, [cache, setCache, packageName, setnpmData, setIsLoading]);
 }
 
+const fetchLogo = (brand) => {
+	switch(brand) {
+		case "npm":
+			return NpmSVG;
+		case "GitHub":
+			return GitHubSVG;
+		case "Adobe":
+			return AdobeSVG;
+	}
+
+	return;
+}
+
+/**
+ * Displays a resource card containing text and an image that links to a particular resource.
+ *
+ * @param {string} heading - heading of the resource card
+ * @param {string} alt - additional description of the resource card
+ * @param {string} image - the SVG image
+ * @param {string} href - optional link to the resource, found in packageJson?.spectrum?.guidelines
+ * @returns {string}
+ */
+export const ResourceLinkContent = ({ heading, alt, logo, href }) => {
+	if (!href) return;
+
+	return (
+		<ResourceLink href={href} className="sb-unstyled" title={alt}>
+			<ResourceIconWrapper dangerouslySetInnerHTML={{ __html: fetchLogo(logo) }} />
+			<ResourceTextWrapper>
+				{heading ? <Heading size="xs">{heading}</Heading> : ""}
+				{alt ? <Body size="s">{alt}</Body> : ""}
+			</ResourceTextWrapper>
+		</ResourceLink>
+	);
+};
+
+/**
+ * Displays the list of relevant component links (to NPM, repo, guidelines, etc).
+ *
+ * The rootClassName is read from the story's default args, found in the story's metadata.
+ *
+ * The for loop is particularly helpful to match guidelines links for any nested components
+ * (i.e. meter, form). We need to check that the rootClassName matches the rootClass found
+ * in the packageJson.spectrum, to link to the correct guidelines page.
+ *
+ * Deprecated components should not show a GitHub resource card.
+ *
+ * @param {string} packageName - packageName sourced from packageJson?.name
+ * @param {string[]} spectrumData - an array of objects sourced from packageJson?.spectrum
+ * @param {string} rootClassName - a component's default rootClass arg
+ * @returns {string}
+ */
+export const ResourceListDetails = ({ packageName, spectrumData = [], rootClassName, isDeprecated }) => {
+	if (!packageName) return;
+
+	let href;
+
+	for(let i = 0; i < spectrumData?.length; i++) {
+		if (spectrumData[i]?.guidelines && spectrumData[i]?.rootClass === rootClassName) {
+			href = spectrumData[i]?.guidelines;
+		}
+	}
+
+	return (
+		<ResourceSection className="sb-unstyled">
+			{href ?
+				<ResourceLinkContent
+					className="doc-block-resource-cards"
+					heading="View guidelines"
+					alt="Spectrum website"
+					logo="Adobe"
+					href={href}/> : ""}
+				<ResourceLinkContent
+					className="doc-block-resource-cards"
+					heading="View package"
+					alt="npm"
+					logo="npm"
+					href={`https://npmjs.com/${packageName}`}/>
+			{!isDeprecated ?
+				<ResourceLinkContent
+					className="doc-block-resource-cards"
+					heading="View repository"
+					alt="GitHub"
+					logo="GitHub"
+					href={`https://github.com/adobe/spectrum-css/tree/main/components/${packageName.split('/').pop()}`}/> : ""}
+		</ResourceSection>
+	)
+};
+
 /**
  * Displays the current version number of the component. The version is read from
  * the component's parameters, where it was sourced from the package.json file.
  *
- * Also displays a component status of "deprecated" if it is set in the story's
+ * Displays a component status of "deprecated" if it is set in the story's
  * parameters.
  *
+ * Displays the list of relevant component links (to NPM, repo, guidelines, etc).
+ *
  * Usage of this doc block within MDX template(s):
  *  <ComponentDetails />
  */
@@ -279,8 +412,16 @@ export const ComponentDetails = () => {
 
 	const isDeprecated = storyMeta?.csfFile?.meta?.parameters?.status?.type == "deprecated";
 	const packageJson = storyMeta?.csfFile?.meta?.parameters?.packageJson ?? {};
+	const rootClassName = storyMeta?.csfFile?.meta?.args?.rootClass ?? "";
+
+	const packageName = packageJson?.name;
+
+	if (!packageName) return;
 
-	if (!packageJson?.name) return;
+	let spectrumData = packageJson?.spectrum;
+	if (typeof spectrumData === "string") {
+		spectrumData = [spectrumData];
+	}
 
 	const [isLoading, setIsLoading] = useState(true);
 	const [npmData, setnpmData] = useState({});
@@ -291,26 +432,28 @@ export const ComponentDetails = () => {
 
 	return (
 		<ResetWrapper>
-			{ !isLoading ?
-				<DList className="docblock-metadata sb-unstyled">
-					{ isDeprecated
-						?	<>
-								<DTerm key={'status'}>Status:</DTerm>
-								<DDefinition key={'status-data'}>Deprecated</DDefinition>
-							</>
-						: ""
-					}
-					{ showLocalVersion
-						?	<>
-								<DTerm key={'version-label'}>Local version:</DTerm>
-								<DDefinition key={'version'}><VersionDetails tag={"local"} data={allVersions && allVersions.find(([tag]) => tag === "local")?.[1]} isDeprecated={isDeprecated} /></DDefinition>
+			{ !isLoading ? <>
+					<DList className="docblock-metadata sb-unstyled">
+						{ isDeprecated
+							?	<>
+									<DTerm key={'status'}>Status:</DTerm>
+									<DDefinition key={'status-data'}>Deprecated</DDefinition>
+								</>
+							: ""
+						}
+						{ showLocalVersion
+							?	<>
+									<DTerm key={'version-label'}>Local version:</DTerm>
+									<DDefinition key={'version'}><VersionDetails tag={"local"} data={allVersions && allVersions.find(([tag]) => tag === "local")?.[1]} isDeprecated={isDeprecated} /></DDefinition>
+								</>
+							: <>
+								<DTerm key={'version-label'}>Latest version:</DTerm>
+								<DDefinition key={'version'}><VersionDetails tag={"latest"} data={allVersions && allVersions.find(([tag]) => tag === "latest")?.[1]} isDeprecated={isDeprecated} skipLink={true} /></DDefinition>
 							</>
-						: <>
-							<DTerm key={'version-label'}>Latest version:</DTerm>
-							<DDefinition key={'version'}><VersionDetails tag={"latest"} data={allVersions && allVersions.find(([tag]) => tag === "latest")?.[1]} isDeprecated={isDeprecated} skipLink={true} /></DDefinition>
-						</>
-					}
-				</DList>
+						}
+					</DList>
+					<ResourceListDetails packageName={packageName} spectrumData={spectrumData} rootClassName={rootClassName} isDeprecated={isDeprecated}/>
+				</>
 			: ""}
 		</ResetWrapper>
 	);

.storybook/assets/images/github_logo.svg

@@ -5,8 +5,9 @@ export const Heading = styled.h3`
     font-family: ${({ theme }) => theme.typography.fontFamily};
     font-weight: ${({ theme }) => theme.typography.weight.bold};
     color: inherit;
-    font-size: ${({ size }) => fetchToken(`font-size-${size === "s" ? 300 : size === "l" ? 700 : size === "xl" ? 900 : 500}`, 22)};
+    font-size: ${({ size }) => fetchToken(`font-size-${size === "xs" ? 200 : size === "s" ? 300 : size === "l" ? 700 : size === "xl" ? 900 : 500}`, 22)};
     -webkit-font-smoothing: antialiased;
+    margin: 0;
 
     > strong {
         font-weight: 900;

.storybook/assets/images/npm_logo.svg

@@ -72,7 +72,15 @@ export default {
 		status: {
 			type: "deprecated"
 		},
-		packageJson,
+		packageJson: {
+			...packageJson,
+			"spectrum": [
+				{
+					"guidelines": "https://spectrum.adobe.com/page/quick-actions/",
+					"rootClass": "spectrum-QuickActions",
+				}
+			]
+		}
 	},
 };
 

.storybook/blocks/ComponentDetails.jsx

@@ -17,7 +17,7 @@ export default {
 		},
 	],
 	rootDir: "../",
-	staticDirs: ["../assets"],
+	staticDirs: ["../assets", "./assets/images"],
 	addons: [
 		{
 			name: "@storybook/addon-essentials",

.storybook/blocks/Typography.jsx

@@ -48,5 +48,11 @@
 	],
 	"publishConfig": {
 		"access": "public"
-	}
+	},
+	"spectrum": [
+		{
+			"guidelines": "https://spectrum-contributions.corp.adobe.com/page/accordion-beta",
+			"rootClass": "spectrum-Accordion"
+		}
+	]
 }

.storybook/deprecated/quickaction/quickaction.stories.js

@@ -54,5 +54,11 @@
 	],
 	"publishConfig": {
 		"access": "public"
-	}
+	},
+	"spectrum": [
+		{
+			"guidelines": "https://spectrum.adobe.com/page/action-bar",
+			"rootClass": "spectrum-ActionBar"
+		}
+	]
 }

.storybook/main.js

@@ -54,5 +54,11 @@
 	],
 	"publishConfig": {
 		"access": "public"
-	}
+	},
+	"spectrum": [
+		{
+			"guidelines": "https://spectrum.adobe.com/page/action-button",
+			"rootClass": "spectrum-ActionButton"
+		}
+	]
 }

components/accordion/package.json

@@ -49,5 +49,11 @@
 	],
 	"publishConfig": {
 		"access": "public"
-	}
+	},
+	"spectrum": [
+		{
+			"guidelines": "https://spectrum.adobe.com/page/action-group",
+			"rootClass": "spectrum-ActionGroup"
+		}
+	]
 }

components/actionbar/package.json

@@ -32,12 +32,6 @@
 		"stories/*",
 		"metadata/*"
 	],
-	"keywords": [
-		"spectrum",
-		"css",
-		"design system",
-		"adobe"
-	],
 	"peerDependencies": {
 		"@spectrum-css/actionbutton": ">=6",
 		"@spectrum-css/icon": ">=7",
@@ -52,6 +46,12 @@
 		"@spectrum-css/popover": "workspace:^",
 		"@spectrum-css/tokens": "workspace:^"
 	},
+	"keywords": [
+		"spectrum",
+		"css",
+		"design system",
+		"adobe"
+	],
 	"publishConfig": {
 		"access": "public"
 	}

components/actionbutton/package.json

@@ -59,5 +59,11 @@
 	],
 	"publishConfig": {
 		"access": "public"
-	}
+	},
+	"spectrum": [
+		{
+			"guidelines": "https://spectrum.adobe.com/page/alert-banner",
+			"rootClass": "spectrum-AlertBanner"
+		}
+	]
 }

components/actiongroup/package.json

@@ -64,5 +64,11 @@
 	],
 	"publishConfig": {
 		"access": "public"
-	}
+	},
+	"spectrum": [
+		{
+			"guidelines": "https://spectrum.adobe.com/page/alert-dialog",
+			"rootClass": "spectrum-AlertDialog"
+		}
+	]
 }