From 84d194016360729ace10bb5c72a85d8ae49046ec Mon Sep 17 00:00:00 2001
From: Josh Winn <965114+jawinn@users.noreply.github.com>
Date: Tue, 2 Apr 2024 11:08:04 -0400
Subject: [PATCH] docs(button): custom mdx docs page

Create an MDX "Docs" page that works as a replacement for the YML docs
pages, and covers the important Button options from there and the
guidelines.

Adds the tag "is-hidden-story" for excluding Storybook sidebar items.
---
 .storybook/main.js                          |   1 +
 .storybook/manager.js                       |   2 +-
 components/button/stories/button.mdx        | 103 +++++
 components/button/stories/button.stories.js | 469 +++++++++++++-------
 4 files changed, 419 insertions(+), 156 deletions(-)
 create mode 100644 components/button/stories/button.mdx

diff --git a/.storybook/main.js b/.storybook/main.js
index 8a024ddafa8..d6e748a3330 100644
--- a/.storybook/main.js
+++ b/.storybook/main.js
@@ -10,6 +10,7 @@ const componentPkgs = readdirSync(componentsPath, {
 
 module.exports = {
 	stories: [
+		"../components/*/stories/*.mdx",
 		"../components/*/stories/*.stories.js",
 		"./guides/*.mdx",
 		"./foundations/*/*.mdx",
diff --git a/.storybook/manager.js b/.storybook/manager.js
index fb843f695a3..791ceaca79f 100644
--- a/.storybook/manager.js
+++ b/.storybook/manager.js
@@ -50,7 +50,7 @@ addons.setConfig({
 	sidebar: {
 		showRoots: false,
 		filters: {
-			patterns: (item) => !(item.id.includes('forced-colors') || item.tags.includes('foundation')),
+			patterns: (item) => !item.id.includes('forced-colors') && ['foundation','is-hidden-story'].every((tag) => !item.tags.includes(tag)),
 		}
 	},
 });
diff --git a/components/button/stories/button.mdx b/components/button/stories/button.mdx
new file mode 100644
index 00000000000..16ba1132323
--- /dev/null
+++ b/components/button/stories/button.mdx
@@ -0,0 +1,103 @@
+import { Canvas, Meta, Subtitle } from '@storybook/blocks';
+
+import * as ButtonStories from './button.stories';
+
+<Meta of={ButtonStories} title="Docs" />
+
+# Button
+
+<Subtitle>Buttons allow users to perform an action or to navigate to another page. They have
+multiple styles forvarious needs, and are ideal forcalling attention to where a user needs to
+do something in order to move forward in a flow.</Subtitle>
+
+## Variants
+
+There are four available variants that are used for different levels of emphasis and different
+types of actions. By default, a button uses the fill style with a solid background. The primary
+and secondary variants also have an outline option.
+
+### Accent
+
+The call to action button communicates strong emphasis and is reserved for encouraging critical
+actions. In general, only use the emphasized option for the most important action on the page.
+
+<Canvas of={ButtonStories.Accent} />
+
+### Primary
+
+The primary button is for medium emphasis. Use it in place of a call to action button when the
+action requires less prominence, or if there are multiple primary actions of the same importance
+in the same view. Both the fill (default) and outline styles are demonstrated below:
+
+<Canvas of={ButtonStories.Primary} />
+
+### Secondary
+
+The secondary button is for low emphasis. It’s paired with other button types to surface less
+prominent actions, and should never be the only button in a group. Both the fill (default) and
+outline styles are demonstrated below:
+
+<Canvas of={ButtonStories.Secondary} />
+
+### Negative
+
+The negative button is for emphasizing actions that can be destructive or have negative
+consequences if taken. Use it sparingly.
+
+<Canvas of={ButtonStories.Negative} />
+
+## Static color
+
+When a button needs to be placed on top of a color background or a visual, use the static color
+option. Static color buttons do not change shades or values depending upon the color theme.
+
+### Static white - primary
+
+<Canvas of={ButtonStories.StaticWhitePrimary} />
+
+### Static white - secondary
+
+<Canvas of={ButtonStories.StaticWhiteSecondary} />
+
+### Static black - primary
+
+<Canvas of={ButtonStories.StaticBlackPrimary} />
+
+### Static black - secondary
+
+<Canvas of={ButtonStories.StaticBlackSecondary} />
+
+## Sizing
+
+Buttons come in four different sizes: small, medium, large, and extra large. The medium size is
+the default and most frequently used option. Use the other sizes sparingly; they should be used
+to create a hierarchy of importance within the page.
+
+<Canvas of={ButtonStories.Sizing} />
+
+## Pending state
+
+The pending button is for indicating that a quick progress action is taking place. In this case, the
+label and optional icon disappear and a progress circle appears. The progress circle always shows an
+indeterminate progress. We recommend the use of the `.is-pending` class on the component’s parent
+container, but there is also an option to use an attribute of `pending` instead. Buttons should have
+the disabled attribute when the pending state is applied.
+
+<Canvas of={ButtonStories.Pending} />
+
+## Disabled state
+
+A button in a disabled state shows that an action exists, but is not available in that circumstance. 
+This state can be used to maintain layout continuity and to communicate that an action may become
+available later.
+
+<Canvas of={ButtonStories.Disabled} />
+
+## Text overflow behavior
+
+When the button text is too long for the horizontal space available, it wraps to form another line. 
+When there is no icon present, the text is aligned center. When there is an icon present, the text is
+aligned `start` (left with a writing direction of left-to-right) and the icon remains vertically aligned
+at the top.
+
+<Canvas of={ButtonStories.WithWrapping} />
\ No newline at end of file
diff --git a/components/button/stories/button.stories.js b/components/button/stories/button.stories.js
index 3047ae884be..1bf61b2396b 100644
--- a/components/button/stories/button.stories.js
+++ b/components/button/stories/button.stories.js
@@ -1,5 +1,6 @@
 import { html } from "lit";
 import { styleMap } from "lit/directives/style-map.js";
+import { when } from "lit/directives/when.js";
 import { withDownStateDimensionCapture } from "../../../.storybook/decorators";
 
 import { default as IconStories } from "@spectrum-css/icon/stories/icon.stories.js";
@@ -13,7 +14,6 @@ import { Template } from "./template";
 export default {
 	title: "Components/Button",
 	component: "Button",
-	decorators: [withDownStateDimensionCapture(".spectrum-Button:not(:disabled)")],
 	argTypes: {
 		size: {
 			name: "Size",
@@ -114,7 +114,7 @@ export default {
 			type: { name: "string" },
 			table: {
 				type: { summary: "string" },
-				category: "Advanced",
+				category: "Component",
 
 			},
 			options: ["white", "black"],
@@ -145,6 +145,7 @@ export default {
 		}
 	},
 	decorators: [
+		withDownStateDimensionCapture(".spectrum-Button:not(:disabled)"),
 		(Story, context) => html`
 			<style>
 				.spectrum-Detail { display: inline-block; }
@@ -194,6 +195,9 @@ const CustomButton = ({
 	})}
 `;
 
+/**
+ * Chromatic only template for displaying all button states.
+ */
 const States = (args) =>
 	html` <div>
 			${Typography({
@@ -282,6 +286,9 @@ const States = (args) =>
 			})}
 		</div>`;
 
+/**
+ * Display with all size options, and all treatments.
+ */
 const Sizes = (args) =>
 	html` ${["s", "m", "l", "xl"].map((size) => {
 		return html` <div>
@@ -304,165 +311,197 @@ const Sizes = (args) =>
 		</div>`;
 	})}`;
 
-const Treatment = (args) =>
-	html`
-<div
-	style=${styleMap({
-		display: "flex",
-		alignItems: "flex-start",
-		gap: "10px",
-	})}
-	id="render-root"
->
-	${["fill", "outline"].map((treatment) => CustomButton({ ...args, treatment }))}
-</div>`;
+/**
+ * Display all treatments (fill + outline)
+ */
+const Treatment = ({treatmentLayout = "inline", ...args}) => {
+	const TreatmentWrapper = (content) => html`
+		<div
+			style=${styleMap({
+				display: "flex",
+				alignItems: "flex-start",
+				gap: "10px",
+			})}
+			id="render-root"
+		>${content}</div>`;
 
+	// Stacked: display within separate wrappers so each treatment is in its own row.
+	if (treatmentLayout == "stacked") {
+		return html`${["fill", "outline"].map((treatment) => TreatmentWrapper(CustomButton({ ...args, treatment })))}`;
+	}
+	// Inline / default: display within the same wrapper, in a single row.
+	return TreatmentWrapper(html`${["fill", "outline"].map((treatment) => CustomButton({ ...args, treatment }))}`);
+};
+
+/* Text overflow scenarios. */
 const Wrapping = (args) => html`
 	${Template({
-	...args,
-	customStyles: {
-		"max-inline-size": "480px",
-	},
-	iconName: "Edit",
-	label: "An example of text overflow behavior within the button component. When the button text is too long for the horizontal space available, it wraps to form another line.",
-})}
-	${Template({
-	...args,
-	customStyles: {
-		"max-inline-size": "480px",
-	},
-	// Uses a UI icon that is smaller than workflow sizing, to test alignment:
-	iconName: "Cross100",
-	label: "An example of text overflow behavior within the button component. When the button text is too long for the horizontal space available, it wraps to form another line.",
-})}
+		...args,
+		customStyles: {
+			"max-inline-size": "480px",
+		},
+		label: "An example of text overflow behavior when there is no icon. When the button text is too long for the horizontal space available, it wraps to form another line.",
+	})}
 	${Template({
-	...args,
-	customStyles: {
-		"max-inline-size": "480px",
-	},
-	// UI icon that is larger than workflow sizing:
-	iconName: "ArrowDown600",
-	label: "An example of text overflow behavior within the button component. When the button text is too long for the horizontal space available, it wraps to form another line.",
-})}`;
-
-const Variants = (args) =>
-	html` ${window.isChromatic()
-		? html` <div class="spectrum-Typography">
-					${Typography({
-						semantics: "detail",
-						size: "l",
-						content: ["Accent"],
-					})}
-					<div
-						style=${styleMap({
-							display: "flex",
-							flexDirection: "column",
-							gap: "10px",
-						})}
-					>
-						${States(args)}
-					</div>
-				</div>
-				<div class="spectrum-Typography">
-					${Typography({
-						semantics: "detail",
-						size: "l",
-						content: ["Negative"],
-					})}
-					<div
-						style=${styleMap({
-							display: "flex",
-							flexDirection: "column",
-							gap: "10px",
-						})}
-					>
-						${States({
-							...args,
-							variant: "negative"
-						})}
-					</div>
-				</div>
-				<div class="spectrum-Typography">
-					${Typography({
-						semantics: "detail",
-						size: "l",
-						content: ["Primary"],
-					})}
-					<div
-						style=${styleMap({
-							display: "flex",
-							flexDirection: "column",
-							gap: "10px",
-						})}
-					>
-						${States({
-							...args,
-							variant: "primary"
-						})}
-					</div>
-				</div>
-				<div class="spectrum-Typography">
-					${Typography({
-						semantics: "detail",
-						size: "l",
-						content: ["Secondary"],
-					})}
-					<div
-						style=${styleMap({
-							display: "flex",
-							flexDirection: "column",
-							gap: "10px",
-						})}
-					>
-						${States({
-							...args,
-							variant: "secondary"
-						})}
-					</div>
-				</div>
-				<div class="spectrum-Typography">
-					${Typography({
-						semantics: "detail",
-						size: "l",
-						content: ["Sizing"],
-					})}
-					<div
-						style=${styleMap({
-							display: "flex",
-							flexDirection: "column",
-							gap: "10px",
-						})}
-					>
-						${Sizes(args)}
-					</div>
-				</div>
-				<div class="spectrum-Typography">
-					${Typography({
-						semantics: "detail",
-						size: "l",
-						content: ["Wrapping"],
-					})}
-					<div
-						style=${styleMap({
-							display: "flex",
-							flexDirection: "column",
-							gap: "10px",
-							padding: "6px"
-						})}
-					>
-						${Wrapping(args)}
-					</div>
-				</div>
-		` : html`
-<div
-	style=${styleMap({
-		display: "flex",
-		gap: "10px",
-		alignItems: "flex-start",
+		...args,
+		customStyles: {
+			"max-inline-size": "480px",
+		},
+		iconName: "Edit",
+		label: "An example of text overflow behavior when the button has an icon. When the button text is too long for the horizontal space available, it wraps to form another line.",
 	})}
-	id="render-root"
->${CustomButton(args)}</div>`}`;
+	${when(window.isChromatic(), () => html`
+		${Template({
+			...args,
+			customStyles: {
+				"max-inline-size": "480px",
+			},
+			// Uses a UI icon that is smaller than workflow sizing, to test alignment:
+			iconName: "Cross100",
+			label: "An example of text overflow behavior when the button has an icon. When the button text is too long for the horizontal space available, it wraps to form another line.",
+		})}
+		${Template({
+			...args,
+			customStyles: {
+				"max-inline-size": "480px",
+			},
+			// UI icon that is larger than workflow sizing:
+			iconName: "ArrowDown600",
+			label: "An example of text overflow behavior when the button has an icon. When the button text is too long for the horizontal space available, it wraps to form another line.",
+		})}
+	`)}
+`;
 
+/**
+ * Default story.
+ * - Chromatic only template displays a large grid of all variants and their states
+ * - User view is a single set of buttons that can be adjusted with controls
+ */
+const Variants = (args) => {
+	return window.isChromatic()
+		? html`<div class="spectrum-Typography">
+			${Typography({
+				semantics: "detail",
+				size: "l",
+				content: ["Accent"],
+			})}
+			<div
+				style=${styleMap({
+					display: "flex",
+					flexDirection: "column",
+					gap: "10px",
+				})}
+			>
+				${States(args)}
+			</div>
+		</div>
+		<div class="spectrum-Typography">
+			${Typography({
+				semantics: "detail",
+				size: "l",
+				content: ["Negative"],
+			})}
+			<div
+				style=${styleMap({
+					display: "flex",
+					flexDirection: "column",
+					gap: "10px",
+				})}
+			>
+				${States({
+					...args,
+					variant: "negative"
+				})}
+			</div>
+		</div>
+		<div class="spectrum-Typography">
+			${Typography({
+				semantics: "detail",
+				size: "l",
+				content: ["Primary"],
+			})}
+			<div
+				style=${styleMap({
+					display: "flex",
+					flexDirection: "column",
+					gap: "10px",
+				})}
+			>
+				${States({
+					...args,
+					variant: "primary"
+				})}
+			</div>
+		</div>
+		<div class="spectrum-Typography">
+			${Typography({
+				semantics: "detail",
+				size: "l",
+				content: ["Secondary"],
+			})}
+			<div
+				style=${styleMap({
+					display: "flex",
+					flexDirection: "column",
+					gap: "10px",
+				})}
+			>
+				${States({
+					...args,
+					variant: "secondary"
+				})}
+			</div>
+		</div>
+		<div class="spectrum-Typography">
+			${Typography({
+				semantics: "detail",
+				size: "l",
+				content: ["Sizing"],
+			})}
+			<div
+				style=${styleMap({
+					display: "flex",
+					flexDirection: "column",
+					gap: "10px",
+				})}
+			>
+				${Sizes(args)}
+			</div>
+		</div>
+		<div class="spectrum-Typography">
+			${Typography({
+				semantics: "detail",
+				size: "l",
+				content: ["Wrapping"],
+			})}
+			<div
+				style=${styleMap({
+					display: "flex",
+					flexDirection: "column",
+					gap: "10px",
+					padding: "6px"
+				})}
+			>
+				${Wrapping(args)}
+			</div>
+		</div>`
+		: CustomButtonWrap(args);
+};
+
+/**
+ * Flex layout used for displaying CustomButton elements in a row.
+ */
+const CustomButtonWrap = (args) =>
+	html`<div
+		style=${styleMap({
+			display: "flex",
+			gap: "10px",
+			alignItems: "flex-start",
+		})}
+		id="render-root"
+	>${CustomButton(args)}</div>`;
+
+/* Stories */
 export const Default = Variants.bind({});
 Default.args = {};
 
@@ -483,3 +522,123 @@ WithForcedColors.parameters = {
 WithForcedColors.args = {
 	iconName: "Actions",
 };
+
+// Stories for MDX "Docs"
+export const Accent = CustomButtonWrap.bind({});
+Accent.tags = ["is-hidden-story"];
+Accent.args = {
+	variant: "accent",
+};
+Accent.parameters = {
+	chromatic: { disableSnapshot: true },
+};
+
+export const Primary = Treatment.bind({});
+Primary.tags = ["is-hidden-story"];
+Primary.args = {
+	variant: "primary",
+	treatmentLayout: "stacked",
+};
+Primary.parameters = {
+	chromatic: { disableSnapshot: true },
+};
+
+export const Secondary = Treatment.bind({});
+Secondary.tags = ["is-hidden-story"];
+Secondary.args = {
+	variant: "secondary",
+	treatmentLayout: "stacked",
+};
+Secondary.parameters = {
+	chromatic: { disableSnapshot: true },
+};
+
+export const Negative = CustomButtonWrap.bind({});
+Negative.tags = ["is-hidden-story"];
+Negative.args = {
+	variant: "negative",
+};
+Negative.parameters = {
+	chromatic: { disableSnapshot: true },
+};
+
+export const StaticWhitePrimary = Treatment.bind({});
+StaticWhitePrimary.tags = ["is-hidden-story"];
+StaticWhitePrimary.args = {
+	variant: "primary",
+	treatmentLayout: "stacked",
+	staticColor: "white",
+};
+StaticWhitePrimary.parameters = {
+	chromatic: { disableSnapshot: true },
+};
+
+export const StaticWhiteSecondary = Treatment.bind({});
+StaticWhiteSecondary.tags = ["is-hidden-story"];
+StaticWhiteSecondary.args = {
+	variant: "secondary",
+	treatmentLayout: "stacked",
+	staticColor: "white",
+};
+StaticWhiteSecondary.parameters = {
+	chromatic: { disableSnapshot: true },
+};
+
+export const StaticBlackPrimary = Treatment.bind({});
+StaticBlackPrimary.tags = ["is-hidden-story"];
+StaticBlackPrimary.args = {
+	variant: "primary",
+	treatmentLayout: "stacked",
+	staticColor: "black",
+};
+StaticBlackPrimary.parameters = {
+	chromatic: { disableSnapshot: true },
+};
+
+export const StaticBlackSecondary = Treatment.bind({});
+StaticBlackSecondary.tags = ["is-hidden-story"];
+StaticBlackSecondary.args = {
+	variant: "secondary",
+	treatmentLayout: "stacked",
+	staticColor: "black",
+};
+StaticBlackSecondary.parameters = {
+	chromatic: { disableSnapshot: true },
+};
+
+export const Sizing = Sizes.bind({});
+Sizing.tags = ["is-hidden-story"];
+Sizing.args = {
+	variant: "primary",
+};
+Sizing.parameters = {
+	chromatic: { disableSnapshot: true },
+};
+
+export const Pending = CustomButtonWrap.bind({});
+Pending.tags = ["is-hidden-story"];
+Pending.args = {
+	variant: "accent",
+	isPending: true,
+	onclick: () => {},
+};
+Pending.parameters = {
+	chromatic: { disableSnapshot: true },
+};
+
+export const Disabled = CustomButtonWrap.bind({});
+Disabled.tags = ["is-hidden-story"];
+Disabled.args = {
+	variant: "accent",
+	isDisabled: true,
+};
+Disabled.parameters = {
+	chromatic: { disableSnapshot: true },
+};
+
+export const WithWrapping = Wrapping.bind({});
+WithWrapping.tags = ["is-hidden-story"];
+WithWrapping.storyName = "Wrapping";
+WithWrapping.args = {
+	variant: "primary",
+};
\ No newline at end of file