feat(downstate,checkbox,button): downstate docs and implementation wi…

…thin example components
adobe · Feb 29, 2024 · 99bc0b9 · 99bc0b9
1 parent 876bc2d
commit 99bc0b9
Show file tree

Hide file tree

Showing 12 changed files with 103 additions and 121 deletions.
diff --git a/components/button/index.css b/components/button/index.css
@@ -147,6 +147,11 @@ governing permissions and limitations under the License.
     box-shadow: none;
   }
 
+  &:active {
+    /* stylelint-disable-next-line spectrum-tools/no-unknown-custom-properties */
+    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));
+  }
+
   .spectrum-Icon {
     /* Any block-size difference between the intended workflow icon size and actual icon used.
        Helps support any existing use of smaller UI icons instead of intended Workflow icons. */

diff --git a/components/checkbox/index.css b/components/checkbox/index.css
@@ -16,8 +16,6 @@ governing permissions and limitations under the License.
  * .spectrum-Checkbox-box::after is the focus indicator
  */
 
-@import "@spectrum-css/downstate/index.css";
-
 /* Component tokens by t-shirt size */
 .spectrum-Checkbox {
   /* Color */
@@ -139,6 +137,10 @@ governing permissions and limitations under the License.
   }
 
   &:active {
+    .spectrum-Checkbox-box {
+      transform: perspective(var(--spectrum-component-size-minimum-perspective-down)) translateZ(var(--spectrum-component-size-difference-down));
+    }
+
     .spectrum-Checkbox-box::before {
       border-color: var(--highcontrast-checkbox-highlight-color-down, var(--mod-checkbox-control-color-down, var(--spectrum-checkbox-control-color-down)));
     }
@@ -375,10 +377,6 @@ governing permissions and limitations under the License.
   }
 }
 
-.spectrum-Checkbox:active:not(.is-readOnly, :disabled, .is-disabled) .spectrum-Checkbox-box {
-  @extend %spectrum-DownState--min-perspective;
-}
-
 /* stylelint-enable max-nesting-depth */
 
 .spectrum-Checkbox-label {

diff --git a/components/checkbox/package.json b/components/checkbox/package.json
@@ -19,7 +19,6 @@
     "@spectrum-css/tokens": ">=13"
   },
   "devDependencies": {
-    "@spectrum-css/component-builder-simple": "^5.0.4",
     "@spectrum-css/downstate": "^1.0.0"
   },
   "publishConfig": {

diff --git a/components/checkbox/stories/template.js b/components/checkbox/stories/template.js
@@ -1,7 +1,7 @@
 import { html } from "lit";
 import { classMap } from "lit/directives/class-map.js";
-import { ifDefined } from "lit/directives/if-defined.js";
 import { styleMap } from "lit/directives/style-map.js";
+import { ifDefined } from "lit/directives/if-defined.js";
 import { when } from "lit/directives/when.js";
 
 import { useArgs } from "@storybook/client-api";
@@ -26,7 +26,6 @@ export const Template = ({
 	ariaLabelledby,
 	customStyles = {},
 	customClasses = [],
-	customDownstateClasses = [],
 	...globals
 }) => {
 	const [_, updateArgs] = useArgs();
@@ -73,10 +72,7 @@ export const Template = ({
 		>
 			<input
 				type="checkbox"
-				class=${classMap({
-					[`${rootClass}-input`]: true,
-					...customDownstateClasses.reduce((a, c) => ({ ...a, [c]: true }), {}),
-				})}
+				class="${rootClass}-input"
 				aria-labelledby=${ifDefined(ariaLabelledby)}
 				?checked=${isChecked}
 				?disabled=${isDisabled || isReadOnly}
@@ -88,12 +84,7 @@ export const Template = ({
 				}}
 				id=${ifDefined(id ? `${id}-input` : undefined)}
 			/>
-			<span
-				class=${classMap({
-					[`${rootClass}-box`]: true,
-					// ...customDownstateClasses.reduce((a, c) => ({ ...a, [c]: true }), {}),
-				})}
-			>
+			<span class="${rootClass}-box">
 				${Icon({
 					...globals,
 					size,

diff --git a/components/downstate/README.md b/components/downstate/README.md
@@ -1,12 +1,10 @@
 # @spectrum-css/downstate
 
-> > The Spectrum CSS, down state is a utility class used to apply active states to Spectrum 2 components. Consult design documentation for further usage and infomation.
+Down state is a Spectrum 2 (S2) feature that creates the illusion of components being pressed-in when active. This functionality is already included in S2 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:
 
-`.spectrum-DownState`
-
-To use this classes:
-- add @spectrum-css/downstate as a dependency
-- Use the class on the component's parent element (for example, it would be on the same element as the `.spectrum-Checkbox` class, or the `.spectrum-Button` class)
+  - If the interactable element has a width of 24px or less, we use the minimum perspective token: `transform: perspective(var(--spectrum-component-size-minimum-perspective-down)) translateZ(var(--spectrum-component-size-difference-down));`
+  - If the interactable element has a width that is greater than 24px, we use the max formula: `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.
 
 This package is part of the [Spectrum CSS project](https://github.com/adobe/spectrum-css).
 

diff --git a/components/downstate/index.css b/components/downstate/index.css
@@ -1,5 +1,5 @@
 /*!
-Copyright 2023 Adobe. All rights reserved.
+Copyright 2024 Adobe. All rights reserved.
 This file is licensed to you under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License. You may obtain a copy
 of the License at http://www.apache.org/licenses/LICENSE-2.0
@@ -9,29 +9,3 @@ the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTA
 OF ANY KIND, either express or implied. See the License for the specific language
 governing permissions and limitations under the License.
 */
-
-/* stylelint-disable custom-property-pattern */
-
-.spectrum-DownState {
-	/* 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));
-
-	&--min-perspective {
-		--spectrum-downstate-perspective: var(--spectrum-component-size-minimum-perspective-down);
-	}
-
-	&:active {
-		transform: perspective(var(--spectrum-downstate-perspective)) translateZ(var(--spectrum-component-size-difference-down));
-	}
-}
-
-%spectrum-DownState {
-	/* 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));
-	transform: perspective(var(--spectrum-downstate-perspective)) translateZ(var(--spectrum-component-size-difference-down));
-}
-
-%spectrum-DownState--min-perspective {
-	--spectrum-downstate-perspective: var(--spectrum-component-size-minimum-perspective-down);
-	transform: perspective(var(--spectrum-downstate-perspective)) translateZ(var(--spectrum-component-size-difference-down));
-}
diff --git a/components/downstate/metadata/downstate.yml b/components/downstate/metadata/downstate.yml
@@ -1,23 +1,82 @@
 name: Down state
 SpectrumSiteSlug: https://spectrum.adobe.com/page/down-state/
 description: |
-  Down state is a Spectrum 2 (S2) feature that creates the illusion of components being pressed-in when active. There are two different ways to implement down state depending on the component.
+  Down state is a Spectrum 2 (S2) feature that creates the illusion of components being pressed-in when active. This functionality is already included in S2 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:
 
-  If the component is interactable at it's root level:
-    - Add the `.spectrum-DownState` class to the root of the element that receives interactions.
-      - Components with a width of 24px or less require the addition of the `.spectrum-DownState--min-perpsective` class next to the `.spectrum-DownState` class.
-    - Develop an implementation to determine the width and height of the component. Assign this to the `--spectrum-downstate-width` and `--spectrum-downstate-height` custom properties in a `style` attribute on the HTML element.
+  - If the interactable element has a width of 24px or less, we use the minimum perspective token: `transform: perspective(var(--spectrum-component-size-minimum-perspective-down)) translateZ(var(--spectrum-component-size-difference-down));`
+  - If the interactable element has a width that is greater than 24px, we use the max formula: `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.
 
-  If the component has an interactable element nested within it, this will require CSS changes:
-    - Use the `%spectrum-DownState` or `%spectrum-DownState--min-perspective` placeholder on the interactable element when the root of the component is in an `:active` state.
-      - Components with a width of 24px or less require the `%spectrum-DownState--min-perspective` placeholder instead.
-    - Note that this functionality is included in S2 components that require down state in this project. This can be seen in the [checkbox component](/checkbox.html).
 examples:
-  - id: downstate
-    name: Down state - utility class
+  - id: downstate-min
+    name: Checkbox - less than 24px wide
     markup: |
       <div class="spectrum-Examples">
-        <button class="spectrum-DownState spectrum-Button spectrum-Button--fill spectrum-Button--accent spectrum-Button--sizeM" style="--spectrum-downstate-width: 72px; --spectrum-downstate-height: 32px;">
+        <div class="spectrum-Examples-item">
+          <h4 class="spectrum-Heading spectrum-Heading--sizeXS spectrum-Examples-itemHeading">Default</h4>
+
+          <label class="spectrum-Checkbox spectrum-Checkbox--sizeM">
+            <input type="checkbox" class="spectrum-Checkbox-input" id="checkbox-0">
+            <span class="spectrum-Checkbox-box">
+              <svg class="spectrum-Icon spectrum-UIIcon-Checkmark100 spectrum-Checkbox-checkmark" focusable="false" aria-hidden="true">
+                <use xlink:href="#spectrum-css-icon-Checkmark100" />
+              </svg>
+              <svg class="spectrum-Icon spectrum-UIIcon-Dash100 spectrum-Checkbox-partialCheckmark" focusable="false" aria-hidden="true">
+                <use xlink:href="#spectrum-css-icon-Dash100" />
+              </svg>
+            </span>
+            <span class="spectrum-Checkbox-label">Checkbox</span>
+          </label>
+
+          <br>
+
+          <label class="spectrum-Checkbox spectrum-Checkbox--sizeM">
+            <input type="checkbox" class="spectrum-Checkbox-input" id="checkbox-1" checked>
+            <span class="spectrum-Checkbox-box">
+              <svg class="spectrum-Icon spectrum-UIIcon-Checkmark100 spectrum-Checkbox-checkmark" focusable="false" aria-hidden="true">
+                <use xlink:href="#spectrum-css-icon-Checkmark100" />
+              </svg>
+              <svg class="spectrum-Icon spectrum-UIIcon-Dash100 spectrum-Checkbox-partialCheckmark" focusable="false" aria-hidden="true">
+                <use xlink:href="#spectrum-css-icon-Dash100" />
+              </svg>
+            </span>
+            <span class="spectrum-Checkbox-label">Checkbox</span>
+          </label>
+
+          <br>
+
+          <label class="spectrum-Checkbox spectrum-Checkbox--sizeM is-indeterminate">
+            <input type="checkbox" class="spectrum-Checkbox-input" id="checkbox-2">
+            <span class="spectrum-Checkbox-box">
+              <svg class="spectrum-Icon spectrum-UIIcon-Checkmark100 spectrum-Checkbox-checkmark" focusable="false" aria-hidden="true">
+                <use xlink:href="#spectrum-css-icon-Checkmark100" />
+              </svg>
+              <svg class="spectrum-Icon spectrum-UIIcon-Dash100 spectrum-Checkbox-partialCheckmark" focusable="false" aria-hidden="true">
+                <use xlink:href="#spectrum-css-icon-Dash100" />
+              </svg>
+            </span>
+            <span class="spectrum-Checkbox-label">Checkbox</span>
+          </label>
+        </div>
+      </div>
+  - id: downstate
+    name: Button - greater than 24px wide
+    markup: |
+      <div class="spectrum-Examples-item">
+        <button class="spectrum-Button spectrum-Button--fill spectrum-Button--accent spectrum-Button--sizeM" style="--spectrum-downstate-width: 72px; --spectrum-downstate-height: 32px;">
           <span class="spectrum-Button-label">Edit</span>
         </button>
+
+        <button class="spectrum-Button spectrum-Button--fill spectrum-Button--accent spectrum-Button--sizeM" style="--spectrum-downstate-width: 78px; --spectrum-downstate-height: 32px;">
+          <svg class="spectrum-Icon spectrum-Icon--sizeM" focusable="false" aria-hidden="true">
+            <use xlink:href="#spectrum-icon-18-Edit" />
+          </svg>
+          <span class="spectrum-Button-label">Edit</span>
+        </button>
+
+        <button class="spectrum-Button spectrum-Button--fill spectrum-Button--accent spectrum-Button--sizeM spectrum-Button--iconOnly" aria-label="Edit" style="--spectrum-downstate-width: 34px; --spectrum-downstate-height: 34px;">
+          <svg class="spectrum-Icon spectrum-Icon--sizeM" focusable="false" aria-hidden="true">
+            <use xlink:href="#spectrum-icon-18-Edit" />
+          </svg>
+        </button>
       </div>
diff --git a/components/downstate/package.json b/components/downstate/package.json
@@ -15,8 +15,18 @@
   },
   "main": "dist/index-vars.css",
   "peerDependencies": {
+    "@spectrum-css/button": "^11.2.0",
+    "@spectrum-css/checkbox": "^8.1.0",
     "@spectrum-css/tokens": ">=13"
   },
+  "peerDependenciesMeta": {
+    "@spectrum-css/button": {
+      "optional": true
+    },
+    "@spectrum-css/checkbox": {
+      "optional": true
+    }
+  },
   "publishConfig": {
     "access": "public"
   }

diff --git a/components/downstate/stories/downstate.stories.js b/components/downstate/stories/downstate.stories.js
@@ -1,13 +1,10 @@
 import { Template } from './template';
 
 export default {
-  title: "UtilityClasses/Down state",
+  title: "Concepts/Down state",
   description: "Down state is utility class used to add an active state to S2 components.",
   component: "DownState",
   argTypes: {},
-  args: {
-    rootClass: "spectrum-DownState",
-  },
   parameters: {
     actions: {
       handles: []

diff --git a/components/downstate/stories/template.js b/components/downstate/stories/template.js
@@ -3,49 +3,26 @@ import { html } from "lit";
 import { Template as Button } from "@spectrum-css/button/stories/template.js";
 import { Template as Checkbox } from "@spectrum-css/checkbox/stories/template.js";
 
-import "../index.css";
-
 export const Template = ({
   rootClass = "spectrum-DownState",
   ...globals
 }) => {
-
-  document.addEventListener("DOMContentLoaded", () => {
-    for (let checkbox of document.querySelectorAll(".spectrum-Checkbox-box")) {
-      // Ideally these values would be found dynamically but this can get wonky with logical properties
-      const width = "14px";
-      const height = "14px";
-
-      checkbox.style.setProperty("--spectrum-downstate-width", width);
-      checkbox.style.setProperty("--spectrum-downstate-height", height);
-    };
-
-    for (let button of document.querySelectorAll(".spectrum-Button")) {
-      // Ideally these values would be found dynamically but this can get wonky with logical properties
-      const width = "72px";
-      const height = "32px";
-
-      button.style.setProperty("--spectrum-downstate-width", width);
-      button.style.setProperty("--spectrum-downstate-height", height);
-    };
-  });
-
-  console.log(globals);
-
   return html`
     ${Checkbox({
       ...globals,
       isEmphasized: true,
       isChecked: true,
       label: "Checkbox",
-      customDownstateClasses: [`${rootClass}`, `${rootClass}--min-perspective`],
     })}
     <div style="padding: 1rem 0;">
       ${Button({
         ...globals,
         treatment: "accent",
         label: "Edit",
-        customClasses: [`${rootClass}`]
+        customStyles: {
+          "--spectrum-downstate-width": "72px",
+          "--spectrum-downstate-height": "32px"
+        }
       })}
     </div>
 

diff --git a/components/downstate/themes/express.css b/components/downstate/themes/express.css
diff --git a/components/downstate/themes/spectrum.css b/components/downstate/themes/spectrum.css