chore(cem): enable css custom states and display them in playground

packages/main/src/ToolbarItem.ts

@@ -20,48 +20,34 @@ interface IOverflowToolbarItem extends HTMLElement {
 	overflowCloseEvents?: string[] | undefined;
 	hasOverflow?: boolean | undefined;
 }
+
 /**
- * Fired when the overflow popover is closed.
+ * @class
+ *
+ * Represents an abstract class for items, used in the `ui5-toolbar`.
+ *
+ * @cssState overflowed - When the item is displayed in the overflow popover. Use this state to apply different styles when the item is overflowed. Available since 2.20.0.
+ * @constructor
+ * @extends UI5Element
  * @public
  * @since 1.17.0
  */
-@event("close-overflow", {
-	bubbles: true,
-	cancelable: true,
-})
-
 @customElement({
 	tag: "ui5-toolbar-item",
 	languageAware: true,
 	renderer: jsxRenderer,
 	template: ToolbarItemTemplate,
 	styles: ToolbarItemCss,
 })
-
 /**
- * @class
- *
- * Represents an abstract class for items, used in the `ui5-toolbar`.
- *
- * ### CSS Custom States
- *
- * The `ui5-toolbar-item` exposes the following CSS custom states for styling:
- *
- * @cssState overflowed - When the item is displayed in the overflow popover. Use this state to apply different styles when the item is overflowed.
- * Since 2.20.0
- *
- * **Example:**
- * ```css
- * ui5-toolbar-item:state(overflowed) {
- *     flex-direction: column;
- * }
- * ```
- *
- * @constructor
- * @extends UI5Element
+ * Fired when the overflow popover is closed.
  * @public
  * @since 1.17.0
  */
+@event("close-overflow", {
+	bubbles: true,
+	cancelable: true,
+})
 class ToolbarItem extends UI5Element {
 	// strictEvents: needed for parent class
 	eventDetails!: {

packages/tools/lib/cem/custom-elements-manifest.config.mjs

@@ -420,7 +420,7 @@ const processPublicAPI = object => {
 		if ((key === "privacy" && object[key] !== "public") || (key === "_ui5privacy" && object[key] !== "public")) {
 			return true;
 		} else if (typeof object[key] === "object") {
-			if (key === "cssParts" || key === "attributes" || key === "_ui5implements") {
+			if (key === "cssParts" || key === "cssStates" || key === "attributes" || key === "_ui5implements") {
 				continue;
 			}
 

packages/tools/lib/cem/schema-internal.json

@@ -1,6 +1,34 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
   "definitions": {
+    "CssCustomState": {
+      "description": "The description of a CSS Custom State\nhttps://developer.mozilla.org/en-US/docs/Web/API/CustomStateSet",
+      "properties": {
+        "deprecated": {
+          "description": "Whether the CSS custom state is deprecated.\nIf the value is a string, it's the reason for the deprecation.",
+          "type": [
+            "string",
+            "boolean"
+          ]
+        },
+        "description": {
+          "description": "A markdown description.",
+          "type": "string"
+        },
+        "name": {
+          "description": "The name of the state. Note: Unlike CSS custom properties, custom states\ndo not have a leading `--`.",
+          "type": "string"
+        },
+        "summary": {
+          "description": "A markdown summary suitable for display in a listing.",
+          "type": "string"
+        }
+      },
+      "required": [
+        "name"
+      ],
+      "type": "object"
+    },
     "Attribute": {
       "additionalProperties": false,
       "properties": {
@@ -521,6 +549,12 @@
           },
           "type": "array"
         },
+        "cssStates": {
+          "items": {
+            "$ref": "#/definitions/CssCustomState"
+          },
+          "type": "array"
+        },
         "customElement": {
           "description": "Distinguishes a regular JavaScript class from a\ncustom element class",
           "enum": [
@@ -676,6 +710,12 @@
           },
           "type": "array"
         },
+        "cssStates": {
+          "items": {
+            "$ref": "#/definitions/CssCustomState"
+          },
+          "type": "array"
+        },
         "customElement": {
           "description": "Distinguishes a regular JavaScript class from a\ncustom element class",
           "enum": [
@@ -1039,7 +1079,7 @@
           "type": "string"
         },
         "path": {
-          "description": "Path to the javascript file needed to be imported. \n(not the path for example to a typescript file.)",
+          "description": "Path to the javascript file needed to be imported.\n(not the path for example to a typescript file.)",
           "type": "string"
         },
         "summary": {

packages/tools/lib/cem/schema.json

@@ -258,6 +258,34 @@
       ],
       "type": "object"
     },
+    "CssCustomState": {
+      "description": "The description of a CSS Custom State\nhttps://developer.mozilla.org/en-US/docs/Web/API/CustomStateSet",
+      "properties": {
+        "deprecated": {
+          "description": "Whether the CSS custom state is deprecated.\nIf the value is a string, it's the reason for the deprecation.",
+          "type": [
+            "string",
+            "boolean"
+          ]
+        },
+        "description": {
+          "description": "A markdown description.",
+          "type": "string"
+        },
+        "name": {
+          "description": "The name of the state. Note: Unlike CSS custom properties, custom states\ndo not have a leading `--`.",
+          "type": "string"
+        },
+        "summary": {
+          "description": "A markdown summary suitable for display in a listing.",
+          "type": "string"
+        }
+      },
+      "required": [
+        "name"
+      ],
+      "type": "object"
+    },
     "CssPart": {
       "description": "The description of a CSS Part",
       "properties": {
@@ -307,6 +335,12 @@
           },
           "type": "array"
         },
+        "cssStates": {
+          "items": {
+            "$ref": "#/definitions/CssCustomState"
+          },
+          "type": "array"
+        },
         "customElement": {
           "description": "Distinguishes a regular JavaScript class from a\ncustom element class",
           "enum": [
@@ -451,6 +485,12 @@
           },
           "type": "array"
         },
+        "cssStates": {
+          "items": {
+            "$ref": "#/definitions/CssCustomState"
+          },
+          "type": "array"
+        },
         "customElement": {
           "description": "Distinguishes a regular JavaScript class from a\ncustom element class",
           "enum": [
@@ -765,7 +805,7 @@
           "type": "string"
         },
         "path": {
-          "description": "Path to the javascript file needed to be imported. \n(not the path for example to a typescript file.)",
+          "description": "Path to the javascript file needed to be imported.\n(not the path for example to a typescript file.)",
           "type": "string"
         },
         "summary": {

packages/tools/lib/cem/types-internal.d.ts

@@ -56,7 +56,7 @@ export interface JavaScriptModule {
   kind: 'javascript-module';
 
   /**
-   * Path to the javascript file needed to be imported. 
+   * Path to the javascript file needed to be imported.
    * (not the path for example to a typescript file.)
    */
   path: string;
@@ -258,6 +258,8 @@ export interface CustomElement extends ClassLike {
 
   cssProperties?: CssCustomProperty[];
 
+  cssStates?: CssCustomState[];
+
   demos?: Demo[];
 
   /**
@@ -416,6 +418,34 @@ export interface CssPart {
   deprecated?: boolean | string;
 }
 
+/**
+ * The description of a CSS Custom State
+ * https://developer.mozilla.org/en-US/docs/Web/API/CustomStateSet
+ */
+export interface CssCustomState {
+  /**
+   * The name of the state. Note: Unlike CSS custom properties, custom states
+   * do not have a leading `--`.
+   */
+  name: string;
+
+  /**
+   * A markdown summary suitable for display in a listing.
+   */
+  summary?: string;
+
+  /**
+   * A markdown description.
+   */
+  description?: string;
+
+  /**
+   * Whether the CSS custom state is deprecated.
+   * If the value is a string, it's the reason for the deprecation.
+   */
+  deprecated?: boolean | string;
+}
+
 export interface CssCustomProperty {
   /**
    * The name of the property, including leading `--`.
@@ -632,7 +662,7 @@ export interface ClassField extends PropertyLike {
 export interface CustomElementField extends ClassField {
   /**
    * The corresponding attribute name if there is one.
-   * 
+   *
    * If this property is defined, the attribute must be listed in the classes'
    * `attributes` array.
    */

packages/tools/lib/cem/types.d.ts

@@ -56,7 +56,7 @@ export interface JavaScriptModule {
   kind: 'javascript-module';
 
   /**
-   * Path to the javascript file needed to be imported. 
+   * Path to the javascript file needed to be imported.
    * (not the path for example to a typescript file.)
    */
   path: string;
@@ -250,6 +250,8 @@ export interface CustomElement extends ClassLike {
 
   cssProperties?: CssCustomProperty[];
 
+  cssStates?: CssCustomState[];
+
   demos?: Demo[];
 
   /**
@@ -372,6 +374,34 @@ export interface CssPart {
   deprecated?: boolean | string;
 }
 
+/**
+ * The description of a CSS Custom State
+ * https://developer.mozilla.org/en-US/docs/Web/API/CustomStateSet
+ */
+export interface CssCustomState {
+  /**
+   * The name of the state. Note: Unlike CSS custom properties, custom states
+   * do not have a leading `--`.
+   */
+  name: string;
+
+  /**
+   * A markdown summary suitable for display in a listing.
+   */
+  summary?: string;
+
+  /**
+   * A markdown description.
+   */
+  description?: string;
+
+  /**
+   * Whether the CSS custom state is deprecated.
+   * If the value is a string, it's the reason for the deprecation.
+   */
+  deprecated?: boolean | string;
+}
+
 export interface CssCustomProperty {
   /**
    * The name of the property, including leading `--`.
@@ -573,7 +603,7 @@ export interface ClassField extends PropertyLike {
 export interface CustomElementField extends ClassField {
   /**
    * The corresponding attribute name if there is one.
-   * 
+   *
    * If this property is defined, the attribute must be listed in the classes'
    * `attributes` array.
    */

packages/tools/lib/cem/utils.mjs

@@ -240,7 +240,7 @@ const allowedTags = {
     event: [...commonTags, "param", "native", "allowPreventDefault"],
     eventParam: [...commonTags],
     method: [...commonTags, "param", "returns", "override"],
-    class: [...commonTags, "constructor", "class", "abstract", "experimental", "implements", "extends", "slot", "csspart"],
+    class: [...commonTags, "constructor", "class", "abstract", "experimental", "implements", "extends", "slot", "csspart", "cssstate", "cssState"],
     enum: [...commonTags, "experimental",],
     enumMember: [...commonTags, "experimental",],
     interface: [...commonTags, "experimental",],
@@ -330,6 +330,9 @@ const validateJSDocTag = (tag) => {
             return tag.type && tag.name && tag.description;
         case "csspart":
             return !tag.type && tag.name && tag.description;
+        case "cssState":
+        case "cssstate":
+            return !tag.type && tag.name && tag.description;
         case "since":
             return !tag.type && tag.name;
         case "returns":

packages/website/build-scripts/api-reference-generation/component-file.mjs

@@ -258,6 +258,23 @@ ${cssParts.map(cssPart => `| ${cssPart.name} | ${processDescription(cssPart.desc
     return result;
 }
 
+const getCssStatesTable = (declaration) => {
+    let result = `## CSS Custom States`
+    const cssStates = declaration.cssStates || [];
+
+    if (!cssStates.length) {
+        return `${result}
+No CSS custom states available for this component.`
+    }
+
+    result = `${result}
+| Name | Description |
+|------|-------------|
+${cssStates.map(cssState => `| ${cssState.name} | ${processDescription(cssState.description)} |`).join("\n")}`
+
+    return result;
+}
+
 
 
 const getEnumFieldsTables = (declaration) => {
@@ -287,6 +304,8 @@ const getTable = (kind, declaration) => {
             return getEventsTables(declaration);
         case "cssPart":
             return getCssPartsTable(declaration);
+        case "cssState":
+            return getCssStatesTable(declaration);
         case "slot":
             return getSlotsTables(declaration);
         case "enum":
@@ -403,7 +422,8 @@ ${parseDeclarationDescription(declaration.description)}`)
         "slot",
         "event",
         "method",
-        "cssPart"
+        "cssPart",
+        "cssState"
     ].map(fieldType => getTable(fieldType, declaration))
 
     fileContent = fileContent.replace("<%COMPONENT_METADATA%>", metadataSections.join("\n\n"));