Add cli to package.json

build-scripts/gulp/gallery.js

@@ -3,6 +3,9 @@ import { glob } from "glob";
 import gulp from "gulp";
 import yaml from "js-yaml";
 import { marked } from "marked";
+import ts from "typescript";
+import { create } from "@custom-elements-manifest/analyzer";
+import { litPlugin } from "@custom-elements-manifest/analyzer/src/features/framework-plugins/lit/lit.js";
 import path from "path";
 import paths from "../paths.cjs";
 import "./clean.js";
@@ -13,6 +16,28 @@ import "./service-worker.js";
 import "./translations.js";
 import "./rspack.js";
 
+gulp.task("generate-component-docs", async function generateComponentDocs() {
+  const filePaths = ["src/components/ha-alert.ts"];
+
+  const modules = await Promise.all(
+    filePaths.map(async (file) => {
+      const filePath = path.resolve(file);
+      console.log(`Reading ${file} -> ${filePath}`);
+      const source = fs.readFileSync(filePath).toString();
+
+      return ts.createSourceFile(file, source, ts.ScriptTarget.ES2015, true);
+    })
+  );
+
+  const manifest = create({
+    modules,
+    plugins: litPlugin(),
+    context: { dev: true },
+  });
+
+  console.log(manifest);
+});
+
 gulp.task("gather-gallery-pages", async function gatherPages() {
   const pageDir = path.resolve(paths.gallery_dir, "src/pages");
   const files = await glob(path.resolve(pageDir, "**/*"));

custom-elements.json

@@ -0,0 +1,186 @@
+{
+  "schemaVersion": "1.0.0",
+  "readme": "",
+  "modules": [
+    {
+      "kind": "javascript-module",
+      "path": "src/components/ha-alert.ts",
+      "declarations": [
+        {
+          "kind": "class",
+          "description": "A custom alert component for displaying messages with various alert types.",
+          "name": "HaAlert",
+          "cssProperties": [
+            {
+              "description": "The color used for \"info\" alerts.",
+              "name": "--info-color"
+            },
+            {
+              "description": "The color used for \"warning\" alerts.",
+              "name": "--warning-color"
+            },
+            {
+              "description": "The color used for \"error\" alerts.",
+              "name": "--error-color"
+            },
+            {
+              "description": "The color used for \"success\" alerts.",
+              "name": "--success-color"
+            },
+            {
+              "description": "The primary text color used in the alert.",
+              "name": "--primary-text-color"
+            }
+          ],
+          "cssParts": [
+            {
+              "description": "The container for the alert.",
+              "name": "issue-type"
+            },
+            {
+              "description": "The container for the alert icon.",
+              "name": "icon"
+            },
+            {
+              "description": "The container for the alert content.",
+              "name": "content"
+            },
+            {
+              "description": "The container for the alert actions.",
+              "name": "action"
+            },
+            {
+              "description": "The container for the alert title.",
+              "name": "title"
+            }
+          ],
+          "slots": [
+            {
+              "description": "The main content of the alert.",
+              "name": ""
+            },
+            {
+              "description": "Slot for providing a custom icon for the alert.",
+              "name": "icon"
+            },
+            {
+              "description": "Slot for providing custom actions or buttons for the alert.",
+              "name": "action"
+            }
+          ],
+          "members": [
+            {
+              "kind": "field",
+              "name": "title",
+              "type": {
+                "text": "string"
+              },
+              "privacy": "public",
+              "default": "\"\"",
+              "description": "The title of the alert. Defaults to an empty string.",
+              "attribute": "title"
+            },
+            {
+              "kind": "field",
+              "name": "alertType",
+              "type": {
+                "text": "\"info\" | \"warning\" | \"error\" | \"success\""
+              },
+              "privacy": "public",
+              "default": "\"info\"",
+              "description": "The type of alert to display. Defaults to \"info\". Determines the styling and icon used.",
+              "attribute": "alert-type"
+            },
+            {
+              "kind": "field",
+              "name": "dismissable",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "public",
+              "default": "false",
+              "description": "Whether the alert can be dismissed. Defaults to `false`. If `true`, a dismiss button is displayed.",
+              "attribute": "dismissable"
+            },
+            {
+              "kind": "field",
+              "name": "narrow",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "public",
+              "default": "false",
+              "description": "Whether the alert should use a narrow layout. Defaults to `false`.",
+              "attribute": "narrow"
+            },
+            {
+              "kind": "method",
+              "name": "_dismissClicked",
+              "privacy": "private"
+            }
+          ],
+          "events": [
+            {
+              "description": "Fired when the dismiss button is clicked.",
+              "name": "alert-dismissed-clicked"
+            }
+          ],
+          "attributes": [
+            {
+              "name": "title",
+              "type": {
+                "text": "string"
+              },
+              "default": "\"\"",
+              "description": "The title of the alert. Defaults to an empty string.",
+              "fieldName": "title"
+            },
+            {
+              "name": "alert-type",
+              "type": {
+                "text": "\"info\" | \"warning\" | \"error\" | \"success\""
+              },
+              "default": "\"info\"",
+              "description": "The type of alert to display. Defaults to \"info\". Determines the styling and icon used.",
+              "fieldName": "alertType"
+            },
+            {
+              "name": "dismissable",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Whether the alert can be dismissed. Defaults to `false`. If `true`, a dismiss button is displayed.",
+              "fieldName": "dismissable"
+            },
+            {
+              "name": "narrow",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Whether the alert should use a narrow layout. Defaults to `false`.",
+              "fieldName": "narrow"
+            }
+          ],
+          "superclass": {
+            "name": "LitElement",
+            "package": "lit"
+          },
+          "tagName": "ha-alert",
+          "customElement": true
+        }
+      ],
+      "exports": [
+        {
+          "kind": "custom-element-definition",
+          "name": "ha-alert",
+          "declaration": {
+            "name": "HaAlert",
+            "module": "src/components/ha-alert.ts"
+          }
+        }
+      ]
+    }
+  ]
+}

package.json

@@ -20,7 +20,9 @@
     "prepack": "pinst --disable",
     "postpack": "pinst --enable",
     "test": "vitest run --config test/vitest.config.ts",
-    "test:coverage": "vitest run --config test/vitest.config.ts --coverage"
+    "test:coverage": "vitest run --config test/vitest.config.ts --coverage",
+    "analyze": "cem analyze --litelement --globs \"src/components/ha-alert.ts\" --dev",
+    "doc": "gulp generate-component-docs"
   },
   "author": "Paulus Schoutsen <Paulus@PaulusSchoutsen.nl> (http://paulusschoutsen.nl)",
   "license": "Apache-2.0",
@@ -155,6 +157,8 @@
     "@babel/plugin-transform-runtime": "7.27.1",
     "@babel/preset-env": "7.27.2",
     "@bundle-stats/plugin-webpack-filter": "4.20.1",
+    "@custom-elements-manifest/analyzer": "0.10.4",
+    "@custom-elements-manifest/to-markdown": "0.1.0",
     "@lokalise/node-api": "14.7.0",
     "@octokit/auth-oauth-device": "7.1.5",
     "@octokit/plugin-retry": "7.2.1",

src/components/ha-alert.ts

@@ -25,6 +25,36 @@ declare global {
   }
 }
 
+/**
+ * A custom alert component for displaying messages with various alert types.
+ * 
+ * @element ha-alert
+ * 
+ * @property {string} title - The title of the alert. Defaults to an empty string.
+ * @property {"info" | "warning" | "error" | "success"} alertType - The type of alert to display.
+ * Defaults to "info". Determines the styling and icon used.
+ * @property {boolean} dismissable - Whether the alert can be dismissed. Defaults to `false`.
+ * If `true`, a dismiss button is displayed.
+ * @property {boolean} narrow - Whether the alert should use a narrow layout. Defaults to `false`.
+ * 
+ * @slot - The main content of the alert.
+ * @slot icon - Slot for providing a custom icon for the alert.
+ * @slot action - Slot for providing custom actions or buttons for the alert.
+ * 
+ * @fires alert-dismissed-clicked - Fired when the dismiss button is clicked.
+ * 
+ * @csspart issue-type - The container for the alert.
+ * @csspart icon - The container for the alert icon.
+ * @csspart content - The container for the alert content.
+ * @csspart action - The container for the alert actions.
+ * @csspart title - The container for the alert title.
+ * 
+ * @cssprop --info-color - The color used for "info" alerts.
+ * @cssprop --warning-color - The color used for "warning" alerts.
+ * @cssprop --error-color - The color used for "error" alerts.
+ * @cssprop --success-color - The color used for "success" alerts.
+ * @cssprop --primary-text-color - The primary text color used in the alert.
+ */
 @customElement("ha-alert")
 class HaAlert extends LitElement {
   // eslint-disable-next-line lit/no-native-attributes
@@ -35,7 +65,7 @@ class HaAlert extends LitElement {
     | "warning"
     | "error"
     | "success" = "info";
-
+    
   @property({ type: Boolean }) public dismissable = false;
 
   @property({ type: Boolean }) public narrow = false;