Add first auto doc test

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,30 @@ 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);
+      return ts.createSourceFile(
+        filePath,
+        await fs.promises.readFile(filePath, "utf-8"),
+        ts.ScriptTarget.ES2015,
+        true
+      );
+    })
+  );
+
+  const manifest = create({
+    modules,
+    plugins: [...litPlugin()],
+    context: { dev: false },
+  });
+
+  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, "**/*"));

package.json

@@ -20,7 +20,8 @@
     "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",
+    "doc": "gulp generate-component-docs"
   },
   "author": "Paulus Schoutsen <Paulus@PaulusSchoutsen.nl> (http://paulusschoutsen.nl)",
   "license": "Apache-2.0",
@@ -155,6 +156,8 @@
     "@babel/plugin-transform-runtime": "7.27.1",
     "@babel/preset-env": "7.27.1",
     "@bundle-stats/plugin-webpack-filter": "4.20.0",
+    "@custom-elements-manifest/analyzer": "0.10.4",
+    "@custom-elements-manifest/to-markdown": "0.1.0",
     "@lokalise/node-api": "14.5.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;