docs(combobox): remove use of placeholder (#3219)

Removes use of placeholder in combobox and adds guidelines to explain
why it should not be used.
Updates docs page to use documentation template.
Also makes adjustments to combobox template so that value and menu args
can be passed.

CSS-41

Author: rise-erpelding

components/combobox/stories/combobox.mdx

@@ -3,10 +3,36 @@ import { disableDefaultModes } from "@spectrum-css/preview/modes";
 import { isDisabled, isFocused, isInvalid, isKeyboardFocused, isLoading, isOpen, isQuiet, size } from "@spectrum-css/preview/types";
 import pkgJson from "../package.json";
 import { ComboBoxGroup } from "./combobox.test.js";
-import { Template } from "./template.js";
+import { VariantGroup } from "./template.js";
 
 /**
  * Comboboxes combine a text entry with a picker menu, allowing users to filter longer lists to only the selections matching a query.
+ *
+ * ## Usage notes
+ *
+ * ### General notes
+ *
+ * - Combobox uses `.spectrum-PickerButton` instead of a `.spectrum-Picker`
+ * - The following classes must be added:
+ *   - `.spectrum-Combobox-textfield` is required on the Textfield outer element (`.spectrum-Textfield`)
+ *   - `.spectrum-Combobox-input` is required on the `<input>` element inside of Textfields (`.spectrum-Textfield-input`)
+ *   - `.spectrum-Combobox-button` is required on the FieldButton (`.spectrum-ActionButton spectrum-ActionButton--sizeM`)
+ * 
+ * ### Indicating validity and focus
+ *
+ * Validity and focus must be bubbled up to the parent so descendants siblings can be styled. Implementations should add the following classes to the `.spectrum-Combobox` parent class in the following situations:
+ *
+ * - `.is-focused` - when the input or button is focused with the mouse
+ * - `.is-keyboardFocused` - when the input or button is focused with the keyboard
+ * - `.is-valid` - when the input has an explicit valid state
+ * - `.is-invalid` - when the input has an explicit invalid state
+ * - `.is-disabled` - when the control is disabled; should also add to the `.spectrum-Combobox-textfield` and include a `[disabled]` attribute to the `.spectrum-Combobox-button`
+ * - `.is-loading` - when the progress circle is being shown
+ *
+ * ### Don't use placeholder text
+ * Putting instructions for how to complete an input, requirements, or any other essential information into placeholder text is not accessible. Once a value is entered, placeholder text is no longer viewable; if someone is using an automatic form filler, they will never get the information in the placeholder text.
+ *
+ * Instead of placeholder text, use the [help text](/docs/components-help-text--docs) description to convey requirements or to show any formatting examples that would help user comprehension. If there's placeholder text and help text at the same time, it becomes redundant and distracting, especially if they're communicating the same thing.
  */
 export default {
 	title: "Combobox",
@@ -50,6 +76,16 @@ export default {
 			control: "select",
 			if: { arg: "showFieldLabel", truthy: true },
 		},
+		value: {
+			name: "Value",
+			description: "The value shows the option that a user has selected.",
+			type: { name: "string" },
+			table: {
+				type: { summary: "string" },
+				category: "Content",
+			},
+			control: { type: "text" },
+		},
 		content: { table: { disable: true } },
 	},
 	args: {
@@ -64,151 +100,66 @@ export default {
 		isDisabled: false,
 		showFieldLabel: false,
 		testId: "combobox",
+		content: [
+			(passthroughs, context) => Menu({
+				role: "listbox",
+				subrole: "option",
+				selectionMode: "single",
+				hasDividers: true,
+				items: [
+					{
+						label: "Ballard",
+						isSelected: true,
+						isChecked: true,
+					},
+					{
+						label: "Fremont",
+					},
+					{
+						label: "Greenwood",
+					},
+					{
+						type: "divider",
+					},
+					{
+						label: "United States of America",
+						isDisabled: true,
+					},
+				],
+				...passthroughs,
+			}, context),
+		],
 	},
 	parameters: {
 		packageJson: pkgJson,
 	},
 };
 
 export const Default = ComboBoxGroup.bind({});
+Default.tags = ["!autodocs"];
 Default.args = {
 	isOpen: true,
 	fieldLabelText: "Select location",
-	content: [
-		Menu({
-			role: "listbox",
-			subrole: "option",
-			isSelectable: true,
-			items: [
-				{
-					label: "Ballard",
-					isSelected: true,
-					isChecked: true,
-				},
-				{
-					label: "Fremont",
-				},
-				{
-					label: "Greenwood",
-				},
-				{
-					type: "divider",
-				},
-				{
-					label: "United States of America",
-					isDisabled: true,
-				},
-			],
-		}),
-	],
+	value: "Ballard",
 };
 
 // ********* DOCS ONLY ********* //
-export const WithLabel = Template.bind({});
-WithLabel.tags = ["!dev"];
-WithLabel.args = {
-	showFieldLabel: true,
-	fieldLabelText: "Country",
-	isOpen: true,
-};
-WithLabel.parameters = {
-	chromatic: { disableSnapshot: true },
-};
-
-export const Closed = Template.bind({});
-Closed.tags = ["!dev"];
-Closed.args = {
-	isOpen: false,
-};
-Closed.parameters = {
-	chromatic: { disableSnapshot: true },
-};
-
-export const Invalid = Template.bind({});
-Invalid.tags = ["!dev"];
-Invalid.args = {
-	isInvalid: true,
-};
-Invalid.parameters = {
-	chromatic: { disableSnapshot: true },
-};
-
-export const Loading = Template.bind({});
-Loading.tags = ["!dev"];
-Loading.args = {
-	isLoading: true,
-};
-Loading.parameters = {
-	chromatic: { disableSnapshot: true },
-};
-
-export const Disabled = Template.bind({});
-Disabled.tags = ["!dev"];
-Disabled.args = {
-	isDisabled: true,
-};
-Disabled.parameters = {
-	chromatic: { disableSnapshot: true },
-};
-
-// Quiet
-export const Quiet = Template.bind({});
-Quiet.tags = ["!dev"];
-Quiet.args = {
-	isQuiet: true,
-};
-Quiet.parameters = {
-	chromatic: { disableSnapshot: true },
-};
-
-export const QuietWithLabel = Template.bind({});
-QuietWithLabel.tags = ["!dev"];
-QuietWithLabel.args = {
-	showFieldLabel: true,
-	fieldLabelText: "Country",
-	isQuiet: true,
-};
-QuietWithLabel.parameters = {
-	chromatic: { disableSnapshot: true },
-};
-
-export const QuietClosed = Template.bind({});
-QuietClosed.tags = ["!dev"];
-QuietClosed.args = {
-	isQuiet: true,
-	isOpen: false,
-};
-QuietClosed.parameters = {
-	chromatic: { disableSnapshot: true },
-};
-
-export const QuietInvalid = Template.bind({});
-QuietInvalid.tags = ["!dev"];
-QuietInvalid.args = {
-	isQuiet: true,
-	isInvalid: true,
-};
-QuietInvalid.parameters = {
-	chromatic: { disableSnapshot: true },
-};
-
-export const QuietLoading = Template.bind({});
-QuietLoading.tags = ["!dev"];
-QuietLoading.args = {
-	isQuiet: true,
-	isLoading: true,
-};
-QuietLoading.parameters = {
+export const DefaultGroup = VariantGroup.bind({});
+DefaultGroup.storyName = "Default";
+DefaultGroup.args = Default.args;
+DefaultGroup.tags = ["!dev"];
+DefaultGroup.parameters = {
 	chromatic: { disableSnapshot: true },
 };
 
-export const QuietDisabled = Template.bind({});
-QuietDisabled.tags = ["!dev"];
-QuietDisabled.args = {
+export const QuietGroup = VariantGroup.bind({});
+QuietGroup.storyName = "Quiet";
+QuietGroup.args = {
+	...Default.args,
 	isQuiet: true,
-	isDisabled: true,
 };
-QuietDisabled.parameters = {
+QuietGroup.tags = ["!dev"];
+QuietGroup.parameters = {
 	chromatic: { disableSnapshot: true },
 };
 

components/combobox/stories/combobox.stories.js

@@ -38,6 +38,17 @@ export const ComboBoxGroup = Variants({
 			isOpen: false,
 			fieldLabelPosition: "left",
 		},
+		{
+			testHeading: "Truncation",
+			isOpen: false,
+			value: "United States of America and to the republic",
+		},
+		{
+			testHeading: "Quiet + truncation",
+			isOpen: false,
+			isQuiet: true,
+			value: "United States of America and to the republic",
+		}
 	],
 	stateData: [
 		{