chore: add api tables to all components (#2297)

* chore: add api tables to all components

* chore: only use eleventyignore as ignore files for rocket

.gitignore

@@ -47,6 +47,7 @@ browserstack.err
 docs/_merged_data/
 docs/_merged_assets/
 docs/_merged_includes/
+docs/**/api-table.md
 
 debug.log
 

package.json

@@ -6,7 +6,7 @@
     "build": "rocket build",
     "bundlesize": "rollup -c bundlesize/rollup.config.js && bundlesize",
     "changeset": "changeset",
-    "custom-elements-manifest": "npm run custom-elements-manifest --workspaces --if-present",
+    "custom-elements-manifest": "npm run custom-elements-manifest --workspaces --if-present && node ./scripts/create-api-tables.mjs",
     "debug": "web-test-runner --watch --config web-test-runner-chrome.config.mjs",
     "debug:firefox": "web-test-runner --watch --config web-test-runner-firefox.config.mjs",
     "debug:webkit": "web-test-runner --watch --config web-test-runner-webkit.config.mjs",
@@ -42,7 +42,8 @@
     "@babel/core": "^7.24.5",
     "@bundled-es-modules/fetch-mock": "^6.5.2",
     "@changesets/cli": "^2.27.1",
-    "@custom-elements-manifest/analyzer": "^0.10.2",
+    "@custom-elements-manifest/analyzer": "^0.9.4",
+    "@custom-elements-manifest/to-markdown": "^0.1.0",
     "@open-wc/building-rollup": "^2.2.3",
     "@open-wc/eslint-config": "^12.0.3",
     "@open-wc/scoped-elements": "^3.0.5",
@@ -52,6 +53,7 @@
     "@rocket/cli": "^0.10.2",
     "@rocket/launch": "^0.6.0",
     "@rocket/search": "^0.5.1",
+    "@thepassle/module-graph": "^0.10.1",
     "@types/autosize": "^4.0.3",
     "@types/chai-as-promised": "^7.1.8",
     "@types/chai-dom": "^1.11.3",
@@ -81,6 +83,7 @@
     "markdownlint-cli": "^0.40.0",
     "mocha": "^10.4.0",
     "npm-run-all": "^4.1.5",
+    "patch-package": "^6.4.7",
     "postinstall-postinstall": "^2.1.0",
     "prettier": "^3.2.5",
     "prettier-package-json": "^2.8.0",

packages/ui/components/switch/src/LionSwitch.js

@@ -105,6 +105,16 @@ export class LionSwitch extends ScopedElementsMixin(ChoiceInputMixin(LionField))
     }
   }
 
+  /**
+   * Override this function from ChoiceInputMixin.
+   * @param {Event} ev
+   * @protected
+   */
+  _toggleChecked(ev) {
+    ev.preventDefault();
+    super._toggleChecked(ev);
+  }
+
   /**
    * Override this function from ChoiceInputMixin.
    * @protected

packages/ui/custom-elements-manifest.config.js

@@ -1,3 +0,0 @@
-import { generateCustomData } from 'cem-plugin-vs-code-custom-data-generator';
-
-export default { plugins: [generateCustomData()] };

packages/ui/package.json

@@ -41,7 +41,7 @@
   ],
   "scripts": {
     "create-npm-publish-docs": "node ./scripts/create-docs-for-npm-publish.js",
-    "custom-elements-manifest": "custom-elements-manifest analyze --litelement --exclude \"docs/**/*\" \"test-helpers/**/*\"",
+    "custom-elements-manifest": "node ./scripts/cem.js",
     "debug": "cd ../../ && npm run debug",
     "debug:firefox": "cd ../../ && npm run debug:firefox",
     "debug:webkit": "cd ../../ && npm run debug:webkit",

packages/ui/scripts/cem.js

@@ -0,0 +1,85 @@
+import fs from 'fs';
+// eslint-disable-next-line import/no-extraneous-dependencies
+import { globby } from 'globby';
+// eslint-disable-next-line import/no-extraneous-dependencies
+import { createModuleGraph } from '@thepassle/module-graph';
+// eslint-disable-next-line import/no-extraneous-dependencies
+import { create, ts } from '@custom-elements-manifest/analyzer';
+// eslint-disable-next-line import/no-extraneous-dependencies
+import { litPlugin } from '@custom-elements-manifest/analyzer/src/features/framework-plugins/lit/lit.js';
+// eslint-disable-next-line import/no-extraneous-dependencies
+import { generateCustomData } from 'cem-plugin-vs-code-custom-data-generator';
+
+/**
+ * Find all entrypoints for lion to create the CEM from
+ */
+const globs = await globby('./exports/**/*.js');
+
+/**
+ * Based on the entrypoints, create a module graph including @lion/ui dependency
+ * We'll feed these modules to the CEM analyzer
+ */
+const moduleGraph = await createModuleGraph(globs, {
+  exclude: [
+    /** Don't include translations in the CEM */
+    i => i.includes('/translations/'),
+    /** Don't include SVGs in the CEM */
+    i => i.endsWith('.svg.js'),
+  ],
+});
+
+/**
+ * Create ts.sourceFiles from the modules in the module graph
+ * to pass to the CEM analyzer
+ */
+const modules = [];
+for (const [, module] of moduleGraph.modules) {
+  modules.push(ts.createSourceFile(module.path, module.source, ts.ScriptTarget.ES2015, true));
+}
+
+/** Exclude information inherited from these mixins, they're generally not useful for public api */
+const inheritanceDenyList = [
+  'LocalizeMixin',
+  'ScopedElementsMixin',
+  'SlotMixin',
+  'SyncUpdatableMixin',
+];
+
+const cem = create({
+  modules,
+  plugins: [
+    ...litPlugin(),
+    generateCustomData(),
+    {
+      packageLinkPhase({ customElementsManifest }) {
+        for (const definition of customElementsManifest.modules) {
+          for (const declaration of definition.declarations) {
+            if (declaration.kind === 'class' && declaration?.members?.length) {
+              /**
+               * Filter out unwanted information from the docs
+               */
+              declaration.members = declaration.members.filter(
+                member => !inheritanceDenyList.includes(member.inheritedFrom?.name),
+              );
+
+              /**
+               * Set privacy for members based on naming conventions
+               */
+              for (const m of declaration.members) {
+                if (!m.privacy && !m.name.startsWith('_') && !m.name.startsWith('#')) {
+                  m.privacy = 'public';
+                } else if (!m.privacy && m.name.startsWith('_')) {
+                  m.privacy = 'protected';
+                } else if (m.name.startsWith('#') || m.name.startsWith('__')) {
+                  m.privacy = 'private';
+                }
+              }
+            }
+          }
+        }
+      },
+    },
+  ],
+});
+
+fs.writeFileSync('./custom-elements.json', JSON.stringify(cem, null, 2));

rocket.config.mjs

@@ -8,6 +8,9 @@ import { copy } from '@web/rollup-plugin-copy';
 
 export default {
   presets: [rocketLaunch(), rocketSearch(), rocketBlog()],
+  eleventy(eleventyConfig) {
+    eleventyConfig.setUseGitIgnore(false);
+  },
   absoluteBaseUrl: absoluteBaseUrlNetlify('http://localhost:8080'),
   setupUnifiedPlugins: [
     adjustPluginOptions(mdjsSetupCode, {

scripts/create-api-tables.mjs

@@ -0,0 +1,89 @@
+import fs from 'fs';
+import { customElementsManifestToMarkdown } from '@custom-elements-manifest/to-markdown';
+
+/**
+ * @param {string} text
+ */
+function toSplitAndUpperCase(text) {
+  return text.replace(/(^\w|-\w)/g, clearAndUpper);
+}
+
+/**
+ * @param {string} text
+ */
+function clearAndUpper(text) {
+  return text.replace(/-/, ' ').toUpperCase();
+}
+
+const systemsTable = ['core', 'form-core', 'localize', 'overlays'];
+const mappingTable = [{ componentDir: 'validate-messages', portalDir: 'form' }];
+
+const componentDirs = fs
+  .readdirSync('./packages/ui/components')
+  .filter(d => !d.startsWith('_') && !d.startsWith('form-integrations'));
+
+const customElementsJson = JSON.parse(
+  fs.readFileSync('./packages/ui/custom-elements.json', 'utf8'),
+);
+
+for (let dir of componentDirs) {
+  const isSystem = systemsTable.includes(dir);
+  const classes = fs
+    .readdirSync(`./packages/ui/components/${dir}/src/`)
+    .filter(f => {
+      if (isSystem) {
+        return f.endsWith('.js')
+      }
+      return f.endsWith('.js') && !f.endsWith('Manager.js') && !f.endsWith('Mixin.js')
+    })
+    .map(f => f.replace('.js', ''));
+
+  for (const component of mappingTable) {
+    if (dir === component.componentDir) {
+      dir = component.portalDir;
+    }
+  }
+  if (dir === 'form-core') {
+    dir = 'form';
+  }
+
+  const folderHeading = isSystem ? 'Systems >> ' : '';
+  let dirApiTableMd = `# ${folderHeading}${toSplitAndUpperCase(dir)} >> API Table ||90`;
+
+  for (const c of classes) {
+    for (const mod of customElementsJson.modules) {
+      for (const declaration of mod.declarations) {
+        if (declaration.name === c && declaration.kind === 'class') {
+          const md = customElementsManifestToMarkdown(
+            {
+              modules: [
+                {
+                  declarations: [declaration],
+                },
+              ],
+            },
+            {
+              private: 'hidden',
+              headingOffset: 0,
+              omitSections: [
+                'main-heading',
+                'super-class',
+                'static-fields',
+                'static-methods',
+                'mixins',
+              ],
+            },
+          );
+          dirApiTableMd = `${dirApiTableMd} \n\n${md}`;
+        }
+      }
+    }
+  }
+
+  const folder = isSystem ? 'fundamentals/systems' : 'components';
+  try {
+    fs.writeFileSync(`./docs/${folder}/${dir}/api-table.md`, dirApiTableMd);
+  } catch (e) {
+    console.error(`No api docs have been created, ${e}`);
+  }
+}