feat(downstate): docs + implementation for example components (#2520)

* feat(downstate): docs + implementation for example components
* docs: update mdx
* docs: reorg, stories live within foundations
* docs: decorator for down state dimension tokens
* docs: fix mdx hierarchy console error
* fix: small iconOnly button gets min perspective
* docs: use markdown, update language
* fix: disabled, readonly checkbox doesnt have down state
* chore(button,checkbox): update package versions

Author: Melissa Thompson

.storybook/decorators/down-state.js

@@ -0,0 +1,19 @@
+export const withDownStateDimensionCapture = (selector) => (Story, context) => {
+  const captureDownStateDimensions = () => {
+    const components = document.querySelectorAll(selector);
+    components.forEach((component) => {
+      const { width, height } = component.getBoundingClientRect();
+      component.style.setProperty('--spectrum-downstate-width', `${width}px`);
+      component.style.setProperty('--spectrum-downstate-height', `${height}px`);
+    });
+  };
+
+  document.addEventListener("DOMContentLoaded", () => {
+    // Wait to make sure the story is fully rendered (otherwise width/height can be wrong)
+    setTimeout(() => {
+        captureDownStateDimensions();
+    }, 100);
+  });
+
+  return Story(context);
+};

.storybook/decorators/index.js

@@ -13,6 +13,7 @@
 
 export { withArgEvents } from "./arg-events.js";
 export { withContextWrapper } from "./context.js";
+export { withDownStateDimensionCapture } from "./down-state.js";
 export { withIconSpriteSheet } from "./icon-sprites.js";
 export { withLanguageWrapper } from "./language.js";
 export { withReducedMotionWrapper } from "./reduce-motion.js";

.storybook/foundations/down-state/button-down-state.stories.js

@@ -0,0 +1,32 @@
+import { Template } from "../../../components/button/stories/template.js";
+
+export default {
+	title: "Foundations/Down state",
+	description:
+		"Buttons allow users to perform an action or to navigate to another page. They have multiple styles for various needs, and are ideal for calling attention to where a user needs to do something in order to move forward in a flow.",
+	component: "Button",
+	args: {
+		rootClass: "spectrum-Button",
+	},
+	parameters: {
+		actions: {
+			handles: ['click .spectrum-Button'],
+		},
+		status: {
+			type: process.env.MIGRATED_PACKAGES.includes("button")
+				? "migrated"
+				: undefined,
+		},
+	},
+	tags: ['foundation'],
+};
+
+export const ButtonDownState = Template.bind({});
+ButtonDownState.args = {
+	label: "Edit",
+	variant: "accent",
+	customStyles: {
+		"--spectrum-downstate-width": "72px",
+		"--spectrum-downstate-height": "32px"
+	}
+};

.storybook/foundations/down-state/checkbox-down-state.stories.js

@@ -0,0 +1,27 @@
+import { Template } from "../../../components/checkbox/stories/template";
+
+export default {
+	title: "Foundations/Down state",
+	description:
+		"Checkboxes allow users to select multiple items from a list of individual items, or mark one individual item as selected.",
+	component: "Checkbox",
+	args: {
+		rootClass: "spectrum-Checkbox",
+	},
+	parameters: {
+		actions: {
+			handles: ['click input[type="checkbox"]'],
+		},
+		status: {
+			type: process.env.MIGRATED_PACKAGES.includes("checkbox")
+				? "migrated"
+				: undefined,
+		},
+	},
+	tags: ['foundation'],
+};
+
+export const CheckboxDownState = Template.bind({});
+CheckboxDownState.args = {
+	label: "Checkbox",
+};

.storybook/foundations/down-state/down-state.mdx

@@ -0,0 +1,44 @@
+import { Meta, Story } from '@storybook/blocks';
+import * as Checkbox from './checkbox-down-state.stories.js';
+import * as Button from './button-down-state.stories.js';
+
+<Meta title="Down state" />
+
+# Down state
+
+Down state is a Spectrum 2 feature that creates the illusion of components being pressed-in when active. This functionality is already included in Spectrum 2 components that require down state in this project. It is implemented with a CSS transform. The implementation depends on the size of the interactable element, as shown in the examples below.
+
+## Examples
+
+### Minimum perspective
+
+For elements that have a width of 24px or less, the minimum perspective token is used to apply the down state. One example of a component that uses this token is the checkbox:
+
+<Story of={Checkbox.CheckboxDownState} />
+
+In this case, we use the minimum perspective token:
+
+```
+transform:
+  perspective(var(--spectrum-component-size-minimum-perspective-down))
+  translateZ(var(--spectrum-component-size-difference-down));
+```
+
+### Calculated perspective
+
+For elements that have a width of greater than 24px, we need to use the component's width and height to apply the down state. One example of a component that uses this logic is the button:
+
+<Story of={Button.ButtonDownState} />
+
+In this case, we use a max formula to calculate the perspective based on component width and height (this helps us account for components that may be very wide):
+
+```
+transform:
+  perspective(max(
+    var(--spectrum-downstate-height),
+    var(--spectrum-downstate-width) * var(--spectrum-component-size-width-ratio-down)
+  ))
+  translateZ(var(--spectrum-component-size-difference-down));
+```
+
+*Note that in this case, users are required to develop an implementation to determine the width and height of the component. Assign these values to the `--spectrum-downstate-width` and `--spectrum-downstate-height` custom properties in a `style` attribute on the HTML element to expose them for use in the CSS.*

.storybook/main.js

@@ -20,6 +20,11 @@ export default {
 			files: "*.@(stories.js|mdx)",
 			titlePrefix: "Guides",
 		},
+		{
+			directory: "./foundations",
+			files: "*/*.mdx",
+			titlePrefix: "Foundations",
+		},
 		{
 			directory: "./deprecated",
 			files: "**/*.@(stories.js|mdx)",

.storybook/manager.js

@@ -68,5 +68,8 @@ addons.setConfig({
 	}),
 	sidebar: {
 		showRoots: false,
+		filters: {
+			patterns: (item) => !(item.id.includes('forced-colors') || item.tags.includes('foundation')),
+		}
 	},
 });

.storybook/preview.js

@@ -35,6 +35,8 @@ export const parameters = {
 			order: [
 				"Guides",
 				["Contributing", "*", "Adobe Code of Conduct", "Changelog"],
+				"Foundations",
+				["*"],
 				"Components",
 				["*", ["Docs", "Default", "*"]],
 				"Deprecated",

components/button/dist/metadata.json

@@ -195,6 +195,9 @@
     "--spectrum-component-pill-edge-to-visual-only-200",
     "--spectrum-component-pill-edge-to-visual-only-300",
     "--spectrum-component-pill-edge-to-visual-only-75",
+    "--spectrum-component-size-difference-down",
+    "--spectrum-component-size-minimum-perspective-down",
+    "--spectrum-component-size-width-ratio-down",
     "--spectrum-component-top-to-workflow-icon-100",
     "--spectrum-component-top-to-workflow-icon-200",
     "--spectrum-component-top-to-workflow-icon-300",
@@ -208,6 +211,9 @@
     "--spectrum-disabled-static-white-background-color",
     "--spectrum-disabled-static-white-border-color",
     "--spectrum-disabled-static-white-content-color",
+    "--spectrum-downstate-height",
+    "--spectrum-downstate-perspective",
+    "--spectrum-downstate-width",
     "--spectrum-focus-indicator-color",
     "--spectrum-focus-indicator-gap",
     "--spectrum-focus-indicator-thickness",

components/button/index.css

@@ -56,6 +56,12 @@
 	--spectrum-button-content-color-focus: var(--highcontrast-button-content-color-focus, var(--mod-button-content-color-focus, var(--spectrum-neutral-content-color-key-focus)));
 	--spectrum-button-content-color-disabled: var(--highcontrast-button-content-color-disabled, var(--mod-button-content-color-disabled, var(--spectrum-disabled-content-color)));
 
+	/* stylelint-disable-next-line spectrum-tools/no-unknown-custom-properties */
+	--spectrum-downstate-perspective: max(var(--spectrum-downstate-height), var(--spectrum-downstate-width) * var(--spectrum-component-size-width-ratio-down));
+
+	&.spectrum-Button--iconOnly {
+		--spectrum-downstate-perspective: var(--spectrum-component-size-minimum-perspective-down);
+	}
 }
 
 .spectrum-Button--sizeS {
@@ -436,6 +442,8 @@
 		border-color: var(--highcontrast-button-border-color-down, var(--mod-button-border-color-down, var(--spectrum-button-border-color-down)));
 		color: var(--spectrum-button-content-color-down);
 		box-shadow: none;
+
+		transform: perspective(var(--spectrum-downstate-perspective)) translateZ(var(--spectrum-component-size-difference-down));
 	}
 
 	&:disabled,