docs(breadcrumb, checkbox, clearbutton, coachindicator): Site Docs to…

… Storybook (#2793) * docs: fix typo in storybook/guides/develop.mdx * docs(breadcrumb): add missing stories and test coverage * docs(checkbox): add missing stories and test coverage * docs(clearbutton): add missing stories and test coverage * docs(coachindicator): add missing stories * docs(checkbox,clearbutton): refactor to use Sizes decorator this removes a custom "Sizing" template for the 2 components and uses the updated Sizes decorator. * chore(checkbox): additional test cases for states and checked - adds disabled-checked and readonly-checked checkbox tests * chore(breadcrumb): additional test cases - adds nested & nested-root-visible test cases for default/compact/ multiline variants - clarifies the state data heading to call out the dragged and disabled breadcrumb states * docs(breadcrumb): add more documentation - adds documentation for nesting/overflow, and root-visible stories - refactors some storyNames to follow a convention/pattern better - removes MultilineDragged story since that state is covered in the separate Dragged story * docs(checkbox): use Container() decorator on docs page - exports the Container() function from utilities.js - refactors DocsCheckboxGroup to use Container(), instead of custom template and styles - refactors AllVariantsCheckboxGroup to also use Container(), instead of more custom styles and headings * docs(breadcrumb): refactor test cases - adds dragged/disabled stateData back to all variants - cleans up items object for each subvariant (default, nested, nested- root-visible) * docs(breadcrumb): cleans up stories - use sentence case in breadcrumb text - refactor items to use ...Default.args etc. where possible - reorganize stories so major variants are grouped together * docs(coachindicator): use Container() decorator on docs page - refactors AllVariantsCoachIndicatorGroup to use Container(), instead of custom template and styles * chore(breadcrumb): use select dropdown for variants - use a select instead of inline-radio - display defaultValue in arg table * chore(checkbox): simplify content arg Co-authored-by: [ Cassondra ] <[email protected]> * chore(coachindicator): simplify content arg Co-authored-by: [ Cassondra ] <[email protected]> * chore(checkbox,coachindicator): pr edits - fix sentence case in clear button args table - add variant: default to coachindicator default args --------- Co-authored-by: [ Cassondra ] <[email protected]>
adobe · Aug 23, 2024 · 2621341 · 2621341
1 parent 2c14098
commit 2621341
Show file tree

Hide file tree

Showing 13 changed files with 545 additions and 44 deletions.
diff --git a/.storybook/decorators/utilities.js b/.storybook/decorators/utilities.js
@@ -49,7 +49,7 @@ const Heading = ({
  * @param {Object} props.containerStyles - Additional styles to apply to the container.
  * @param {Object} props.wrapperStyles - Additional styles to apply to the content wrapper.
  */
-const Container = ({
+export const Container = ({
 	heading,
 	content,
 	type = "heading",

diff --git a/.storybook/guides/develop.mdx b/.storybook/guides/develop.mdx
@@ -470,7 +470,7 @@ Default.args = {};
 
 Ideally you should have a single story file for each component with multiple variations and states represented in the testing grid that only renders in Chromatic. To preview the groups locally, there is a global toolbar setting with a beaker icon called "Show testing preview" that will activate the Chromatic view.
 
-In the event that you don't want a story to be tested in Chromatic, you can use the `disableSnapshot` paramter:
+In the event that you don't want a story to be tested in Chromatic, you can use the `disableSnapshot` parameter:
 
 ```js
 Default.parameters = {

diff --git a/components/breadcrumb/stories/breadcrumb.stories.js b/components/breadcrumb/stories/breadcrumb.stories.js
@@ -1,9 +1,18 @@
 import { disableDefaultModes } from "@spectrum-css/preview/modes";
 import { version } from "../package.json";
 import { BreadcrumbGroup } from "./breadcrumb.test.js";
+import { Template } from "./template";
 
 /**
  * Breadcrumbs show hierarchy and navigational context for a user's location within an app.
+ * 
+ * ## Nesting
+ * Breadcrumbs truncate when there is not enough room to display all levels of the breadcrumb list, or as a way of managing relevance of the visible breadcrumb items in a deeply nested hierarchy. The truncation of breadcrumb items begins when either there is not enough room to display all items, or if there are 5 or more breadcrumbs to display. They are typically indicated by the truncated menu folder icon.
+ * 
+ * The nested variants below are non-functional. Implementations can add their own overflow menus to display all options within a breadcrumb.
+ * 
+ * ## Root Context
+ * Some applications find that displaying the root directory is useful for user orientation. This variation keeps the root visible when other folders are truncated into a menu. For example, when users can navigate file directories on their device as well as in the cloud, exposing a root directory called “On this device” is very helpful.
  */
 export default {
 	title: "Breadcrumbs",
@@ -13,12 +22,14 @@ export default {
 		variant: {
 			name: "Variants",
 			type: { name: "string" },
+			defaultValue: "Default",
 			table: {
 				type: { summary: "string" },
 				category: "Component",
+				defaultValue: { summary: "Default" },
 			},
-			options: ["compact", "multiline"],
-			control: "inline-radio",
+			options: ["default", "compact", "multiline"],
+			control: "select",
 		},
 		isDragged: {
 			name: "Dragged",
@@ -33,28 +44,187 @@ export default {
 	args: {
 		rootClass: "spectrum-Breadcrumbs",
 		isDragged: false,
+		variant: "default",
 	},
 	parameters: {
 		componentVersion: version,
 	},
 };
 
+/**
+ * By default, breadcrumbs are displayed inline with the hierarchy shown in reading order.
+ */
 export const Default = BreadcrumbGroup.bind({});
 Default.args = {
 	items: [
 		{
 			label: "Nav root",
+		},
+		{
+			label: "Trend",
 			isDragged: true,
 		},
+		{
+			label: "January 2019 assets",
+		},
+	],
+};
+
+export const DefaultNested = Template.bind({});
+DefaultNested.args = {
+	items: [
+		{
+			iconName: "FolderOpen",
+		},
+		{
+			label: "Sub item",
+		},
+		{
+			label: "Trend",
+		},
+		{
+			label: "January 2019 assets",
+		},
+	],
+};
+DefaultNested.tags = ["!dev"];
+DefaultNested.parameters = {
+	chromatic: { disableSnapshot: true },
+};
+DefaultNested.storyName = "Default, nested";
+
+export const DefaultNestedRootVisible = Template.bind({});
+DefaultNestedRootVisible.args = {
+	items: [
+		{
+			label: "Nav root",
+		},
+		{
+			iconName: "FolderOpen",
+		},
 		{
 			label: "Trend",
+		},
+		{
+			label: "January 2019 assets",
+		},
+	],
+};
+DefaultNestedRootVisible.tags = ["!dev"];
+DefaultNestedRootVisible.parameters = {
+	chromatic: { disableSnapshot: true },
+};
+DefaultNestedRootVisible.storyName = "Default, nested (root visible)";
+
+/**
+ * The multiline variation places emphasis on the selected breadcrumb item as a page title, helping a user to more clearly identify their current location.
+ */
+export const Multiline = Template.bind({});
+Multiline.args = {
+	...Default.args,
+	variant: "multiline",
+};
+Multiline.tags = ["!dev"];
+Multiline.parameters = {
+	chromatic: { disableSnapshot: true },
+};
+
+export const MultilineNested = Template.bind({});
+MultilineNested.args = {
+	...DefaultNested.args,
+	variant: "multiline",
+};
+MultilineNested.storyName = "Multiline, nested";
+MultilineNested.tags= ["!dev"];
+MultilineNested.parameters = {
+	chromatic: { disableSnapshot: true },
+};
+
+export const MultilineNestedRootVisible = Template.bind({});
+MultilineNestedRootVisible.args = {
+	...DefaultNestedRootVisible.args,
+	variant: "multiline",
+};
+MultilineNestedRootVisible.tags = ["!dev"];
+MultilineNestedRootVisible.parameters = {
+	chromatic: { disableSnapshot: true },
+};
+MultilineNestedRootVisible.storyName = "Multiline, nested (root visible)";
+
+/**
+ * When needing to optimize for functional space, the compact option is useful for reducing the height of the breadcrumbs while still maintaining the proper user context.
+ */
+export const Compact = Template.bind({});
+Compact.args = {
+	...Default.args,
+	variant: "compact",
+};
+Compact.tags = ["!dev"];
+Compact.parameters = {
+	chromatic: { disableSnapshot: true },
+};
+
+export const CompactNested = Template.bind({});
+CompactNested.args = {
+	...DefaultNested.args,
+	variant: "compact",
+};
+CompactNested.tags = ["!dev"];
+CompactNested.parameters = {
+	chromatic: { disableSnapshot: true },
+};
+CompactNested.storyName = "Compact, nested";
+
+export const CompactNestedRootVisible = Template.bind({});
+CompactNestedRootVisible.args = {
+	...DefaultNestedRootVisible.args,
+	variant: "compact",
+};
+CompactNestedRootVisible.tags = ["!dev"];
+CompactNestedRootVisible.parameters = {
+	chromatic: { disableSnapshot: true },
+};
+CompactNestedRootVisible.storyName = "Compact, nested (root visible)";
+
+/**
+ * Breadcrumbs can have optional behavior to allow for drag and drop functionality.
+ */
+export const Dragged = Template.bind({});
+Dragged.args = {
+	...Default.args,
+	isDragged: true,
+};
+Dragged.tags = ["!dev"];
+Dragged.parameters = {
+	chromatic: { disableSnapshot: true },
+};
+
+/**
+ * The example below has two disabled breadcrumb items. When disabling the text link, the `is-disabled` class gets added to `.spectrum-Breadcrumbs-itemLink`. When disabling the Action button, the `[disabled]` attribute is applied.
+ */
+export const Disabled = Template.bind({});
+Disabled.args = {
+	items: [
+		{
+			label: "Nav root",
+		},
+		{
+			iconName: "FolderOpen",
 			isDisabled: true,
 		},
 		{
-			label: "January 2019 Assets",
+			label: "Trendy",
+			isDisabled: true,
+		},
+		{
+			label: "January 2019 assets",
 		},
 	],
 };
+Disabled.tags = ["!dev"];
+Disabled.parameters = {
+	chromatic: { disableSnapshot: true },
+};
 
 // ********* VRT ONLY ********* //
 export const WithForcedColors = BreadcrumbGroup.bind({});

diff --git a/components/breadcrumb/stories/breadcrumb.test.js b/components/breadcrumb/stories/breadcrumb.test.js
@@ -1,37 +1,106 @@
 import { Variants } from "@spectrum-css/preview/decorators";
 import { Template } from "./template.js";
 
+const DefaultItems = [
+	{
+		label: "Nav root",
+	},
+	{
+		label: "Dragged",
+		isDragged: true,
+	},
+	{
+		label: "Disabled sub item",
+		isDisabled: true,
+	},
+	{
+		label: "January 2019 assets",
+	},
+];
+
+const NestedItems = [
+	{
+		iconName: "FolderOpen",
+	},
+	{
+		label: "Dragged",
+		isDragged: true,
+	},
+	{
+		label: "Disabled",
+		isDisabled: true,
+	},
+	{
+		label: "January 2019 assets",
+	},
+];
+
+const NestedRootVisibleItems = [
+	{
+		label: "Nav root",
+	},
+	{
+		iconName: "FolderOpen",
+		isDisabled: true,
+	},
+	{
+		label: "Dragged sub item",
+		isDragged: true,
+	},
+	{
+		label: "January 2019 assets",
+	},
+];
+
 export const BreadcrumbGroup = Variants({
 	Template,
-	testData: [{
-		testHeading: "Default"
-	}, {
-		testHeading: "Compact",
-		variant: "compact",
-	},
-	{
-		testHeading: "Multiline",
-		variant: "multiline",
-		items: [
-			{
-				label: "Nav root",
-			},
-			{
-				iconName: "FolderOpen",
-				isDisabled: true,
-			},
-			{
-				label: "Trend",
-				isDragged: true,
-			},
-			{
-				label: "January 2019 Assets",
-			},
-		],
-	}],
+	testData: [
+		{
+			testHeading: "Default",
+			items: DefaultItems,
+		},
+		{
+			testHeading: "Default (nested)",
+			items: NestedItems,
+		},
+		{
+			testHeading: "Default (nested, root visible)",
+			items: NestedRootVisibleItems,
+		},
+		{
+			testHeading: "Compact",
+			variant: "compact",
+			items: DefaultItems,
+		},
+		{
+			testHeading: "Compact (nested)",
+			variant: "compact",
+			items: NestedItems,
+		},
+		{
+			testHeading: "Compact (nested, root visible)",
+			variant: "compact",
+			items: NestedRootVisibleItems,
+		},
+		{
+			testHeading: "Multiline",
+			variant: "multiline",
+			items: DefaultItems,
+		},
+		{
+			testHeading: "Multiline (nested)",
+			variant: "multiline",
+			items: NestedItems,
+		},
+		{
+			testHeading: "Multiline (nested, root visible)",
+			variant: "multiline",
+			items: NestedRootVisibleItems,
+		},
+	],
 	stateData: [
 		{
-			testHeading: "Dragged",
+			testHeading: "Dragged, disabled",
 			isDragged: true,
 		}
 	]

diff --git a/components/breadcrumb/stories/template.js b/components/breadcrumb/stories/template.js
@@ -21,7 +21,7 @@ export const Template = (
 		<ul
 			class=${classMap({
 				[rootClass]: true,
-				[`${rootClass}--${variant}`]: typeof variant !== "undefined",
+				[`${rootClass}--${variant}`]: typeof variant !== "undefined" || variant !== "default",
 				...customClasses.reduce((a, c) => ({ ...a, [c]: true }), {}),
 			})}
 		>