From 1adb2f414a0dabb2cc930142bbcb7116cd9c2e5c Mon Sep 17 00:00:00 2001
From: Josh Winn <965114+jawinn@users.noreply.github.com>
Date: Mon, 23 Sep 2024 15:20:53 -0400
Subject: [PATCH] docs(helptext): migrate docs to storybook (#3151)

Migrates the help text component's docs page information to Storybook.
Creates additional docs-only stories and some supporting templates.
Brings over some helpful info from help text's guidelines for the
descriptions.
---
 .../helptext/stories/helptext.stories.js      | 73 ++++++++++++++++++-
 components/helptext/stories/template.js       | 46 +++++++++++-
 2 files changed, 117 insertions(+), 2 deletions(-)

diff --git a/components/helptext/stories/helptext.stories.js b/components/helptext/stories/helptext.stories.js
index a3b6b8f2d8..3ddcaaa8a4 100644
--- a/components/helptext/stories/helptext.stories.js
+++ b/components/helptext/stories/helptext.stories.js
@@ -1,7 +1,9 @@
+import { Sizes } from "@spectrum-css/preview/decorators";
 import { disableDefaultModes } from "@spectrum-css/preview/modes";
 import { isDisabled, size } from "@spectrum-css/preview/types";
 import pkgJson from "../package.json";
 import { HelpTextGroup } from "./helptext.test.js";
+import { NegativeTemplate, Template, VariantsTemplate } from "./template.js";
 
 /**
  * Help text provides either an informative description or an error message that gives more context about what a user needs to input. It's commonly used in forms.
@@ -34,7 +36,7 @@ export default {
 		hideIcon: {
 			name: "Hide icon",
 			type: { name: "boolean" },
-			description: "Help text using the negative variant can have an optional icon.",
+			description: "Hides the optional icon used with the negative variant.",
 			table: {
 				type: { summary: "boolean" },
 				disable: false,
@@ -58,6 +60,9 @@ export default {
 	},
 };
 
+/**
+ * The default neutral variant is used to convey informative messages.
+ */
 export const Default = HelpTextGroup.bind({});
 Default.args = {};
 
@@ -71,3 +76,69 @@ WithForcedColors.parameters = {
 		modes: disableDefaultModes
 	},
 };
+
+// ********* DOCS ONLY ********* //
+
+/**
+ * Help text comes in four different sizes: small, medium, large, and extra-large. The medium size is the default.
+ */
+export const Sizing = (args, context) => Sizes({
+	Template,
+	withHeading: false,
+	withBorder: false,
+	...args,
+}, context);
+Sizing.storyName = "Sizing";
+Sizing.args = {
+	variant: "negative",
+};
+Sizing.tags = ["!dev"];
+Sizing.parameters = {
+	chromatic: { disableSnapshot: true },
+};
+
+/**
+ * Help text using the neutral variant can be displayed in a disabled state. The text appears with a lighter gray that matches
+ * the style of other components in a disabled state. Help text using the negative variant cannot be displayed in a disabled
+ * state because it communicates an error, and error messages should not be visible when the component is disabled.
+ */
+export const Disabled = Template.bind({});
+Disabled.args = {
+	isDisabled: true,
+};
+Disabled.tags = ["!dev"];
+Disabled.parameters = {
+	chromatic: { disableSnapshot: true },
+};
+
+/**
+ * The negative variant is used to convey error messages and can have an optional icon.
+ * 
+ * In most cases, help text is used with a component that already displays an icon communicating an error (e.g., 
+ * [text field](?path=/docs/components-text-field--docs),
+ * [picker](?path=/docs/components-picker--docs), 
+ * [combo box](?path=/docs/components-combobox--docs#standard---invalid)),
+ * so it’s not necessary to include another icon. In other cases, help text that is used with a component that does not display an icon
+ * communicating an error (e.g., [field group](?path=/docs/components-field-group--docs#invalid)) needs to display an icon.
+ */
+export const Negative = NegativeTemplate.bind({});
+Negative.args = {
+	variant: "negative",
+};
+Negative.tags = ["!dev"];
+Negative.parameters = {
+	chromatic: { disableSnapshot: true },
+};
+
+/**
+ * When the text is too long for the available horizontal space, it wraps to form another line.
+ */
+export const TextOverflow = VariantsTemplate.bind({});
+TextOverflow.args = {
+	variant: "negative",
+	text: "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.",
+};
+TextOverflow.tags = ["!dev"];
+TextOverflow.parameters = {
+	chromatic: { disableSnapshot: true },
+};
diff --git a/components/helptext/stories/template.js b/components/helptext/stories/template.js
index 164ce4e1fa..7c0f5c3fd4 100644
--- a/components/helptext/stories/template.js
+++ b/components/helptext/stories/template.js
@@ -1,5 +1,5 @@
 import { Template as Icon } from "@spectrum-css/icon/stories/template.js";
-import { getRandomId } from "@spectrum-css/preview/decorators";
+import { Container, getRandomId } from "@spectrum-css/preview/decorators";
 import { html } from "lit";
 import { classMap } from "lit/directives/class-map.js";
 import { ifDefined } from "lit/directives/if-defined.js";
@@ -45,3 +45,47 @@ export const Template = ({
 		</div>
 	`;
 };
+
+/**
+ * Displays both variants.
+ */
+export const VariantsTemplate = (args, context) => Container({
+	withBorder: false,
+	direction: "column",
+	content: html`${["neutral", "negative"].map((variant) => 
+		Container({
+			withBorder: false,
+			direction: "column",
+			heading: `Variant: ${variant}`,
+			containerStyles: {
+				rowGap: "8px",
+			},
+			content: Template({
+				...args,
+				variant
+			}, context),
+		})
+	)}`,
+});
+
+/**
+ * Displays options for the negative variant; with and without an icon.
+ */
+export const NegativeTemplate = (args, context) => Container({
+	withBorder: false,
+	direction: "column",
+	content: html`${[true, false].map((hideIcon) => 
+		Container({
+			withBorder: false,
+			direction: "column",
+			heading: hideIcon ? "Without icon" : "With icon",
+			containerStyles: {
+				rowGap: "8px",
+			},
+			content: Template({
+				...args,
+				hideIcon
+			}, context),
+		})
+	)}`,
+});