feat(breadcrumb): add support for multiline headings

The new specs specified that title item can be customized in the
multiline variant, with preferred sizing. This adds support for that
in our template and adds a new Storybook control.

Author: jawinn

.changeset/wet-laws-worry.md

@@ -11,11 +11,9 @@ There has been a major design change to the variant classes related to density a
 - The "compact" variant no longer exists. The `spectrum-Breadcrumbs--compact` class and associated custom properties are removed. The default (medium) breadcrumbs are now sized similar to what was previously called compact.
 - There is a new "large" variant, which uses the `spectrum-Breadcrumbs--large` class. This is sized similarly to what was previously the default.
 
-For each breadcrumbs variant, the design spec specifies that following sizes should be used for the truncated menu action button and the separator chevron:
-
-- default (medium): medium action button and Chevron100 UI icon
-- large: large action button and Chevron100 UI icon
-- multiline: small action button and Chevron75 UI icon
+The breadcrumb title can now be customized in the multiline variant using an additional element that uses the typography component's heading classes.
+See the documentation for details about this and the preferred sizing. The documentation also has been updated to include information about which
+icon sizes should be displayed for each t-shirt size.
 
 The component has been refactored to slim down and simplify its CSS and custom properties, by changing the values of existing custom properties for large and multiline variants.
 

components/breadcrumb/package.json

@@ -24,14 +24,18 @@
 	"peerDependencies": {
 		"@spectrum-css/actionbutton": ">=6",
 		"@spectrum-css/icon": ">=7",
-		"@spectrum-css/tokens": ">=14.0.0-next.3"
+		"@spectrum-css/tokens": ">=14.0.0-next.3",
+		"@spectrum-css/typography": ">=6"
 	},
 	"peerDependenciesMeta": {
 		"@spectrum-css/actionbutton": {
 			"optional": true
 		},
 		"@spectrum-css/icon": {
 			"optional": true
+		},
+		"@spectrum-css/typography": {
+			"optional": true
 		}
 	},
 	"keywords": [

components/breadcrumb/stories/breadcrumb.stories.js

@@ -1,4 +1,4 @@
-import { Template } from "./template";
+import { BreadcrumbTitleHeadings, Template } from "./template";
 
 /**
  * Breadcrumbs show hierarchy and navigational context for a user's location within an app.
@@ -44,6 +44,28 @@ export default {
 			},
 			control: "boolean"
 		},
+		titleHeadingSize: {
+			name: "Breadcrumb title heading size",
+			description: "The breadcrumb title can be customized in the multiline variant using an additional element that uses the typography component's heading classes. The preferred heading sizes are small,  medium large, and extra-large. When no heading classes are used, the text will be sized the same as a large heading by default.",
+			type: { name: "string" },
+			table: {
+				type: { summary: "string" },
+				category: "Content",
+			},
+			control: {
+				type: "select",
+				labels: {
+					undefined: "Default",
+					s: "Small",
+					m: "Medium",
+					l: "Large",
+					xl: "Extra-large",
+				},
+			},
+			defaultValue: undefined,
+			options: [undefined, "s", "m", "l", "xl"],
+			if: { arg: "variant", eq: "multiline" },
+		}
 	},
 	args: {
 		rootClass: "spectrum-Breadcrumbs",
@@ -241,6 +263,23 @@ Disabled.parameters = {
 	chromatic: { disableSnapshot: true },
 };
 
+/**
+ * For the multiline variant, the breadcrumb title can be customized using an additional element that uses the heading classes from
+ * the [typography component](?path=/docs/components-typography). The preferred heading sizes are `.spectrum-Heading--sizeS`,
+ * `.spectrum-Heading--sizeM`, `.spectrum-Heading--sizeL` (default), and `.spectrum-Heading--sizeXL`. If no heading element or classes are
+ * used, the text will be sized the same as a large heading by default.
+ */
+export const MultilineTitleSizes = BreadcrumbTitleHeadings.bind({});
+MultilineTitleSizes.args = {
+	...DefaultNested.args,
+	variant: "multiline",
+};
+MultilineTitleSizes.storyName = "Multiline breadcrumb title heading sizes";
+MultilineTitleSizes.tags= ["!dev"];
+MultilineTitleSizes.parameters = {
+	chromatic: { disableSnapshot: true },
+};
+
 // ********* VRT ONLY ********* //
 /*
 export const WithForcedColors = BreadcrumbGroup.bind({});

components/breadcrumb/stories/template.js

@@ -1,5 +1,6 @@
 import { Template as ActionButton } from "@spectrum-css/actionbutton/stories/template.js";
 import { Template as Icon } from "@spectrum-css/icon/stories/template.js";
+import { Template as Typography } from "@spectrum-css/typography/stories/template.js";
 import { html } from "lit";
 import { classMap } from "lit/directives/class-map.js";
 import { ifDefined } from "lit/directives/if-defined.js";
@@ -14,6 +15,7 @@ export const Template = (
 		items = [],
 		variant = "medium",
 		isDragged = false,
+		titleHeadingSize,
 	} = {},
 	context = {},
 ) => html`
@@ -68,7 +70,11 @@ export const Template = (
 									</div>`,
 								() =>
 									html`<a class="${rootClass}-itemLink" aria-current="page"
-										>${label}</a
+										>${ typeof titleHeadingSize == "undefined" ? label : Typography({
+											semantics: "heading",
+											size: titleHeadingSize,
+											content: [label],
+										})}</a
 									>`,
 							),
 					)}
@@ -86,4 +92,30 @@ export const Template = (
 			})}
 		</ul>
 	</nav>
+`;
+
+/**
+ * Displays all preferred sizes for breadcrumb title headings used with the multiline variant.
+ * 
+ * TODO: make sure of Container() with headings when S2 is in sync with the main branch again. 
+ */
+export const BreadcrumbTitleHeadings = (args) => html`
+	<div style="display: flex; flex-direction: column; gap: 16px;">
+		${[undefined, "s", "m", "l", "xl"].map((titleHeadingSize) => html`
+			${Typography({
+				semantics: "detail",
+				size: "s",
+				content: [
+					typeof titleHeadingSize != "undefined"
+						? `Heading size: ${titleHeadingSize}`
+						: "Default - no heading element or classes"
+				],
+				customClasses: ["chromatic-ignore"],
+			})}
+			${Template({
+				...args,
+				titleHeadingSize,
+			})}
+		`)}
+	</div>
 `;