Create non-auto-registering routes (shoelace-style#1450)

* initial attempt at not auto defining

* add files with -

* continued work on removing auto-define

* fix component definitions

* update with new tag stuff

* fix lots of things

* fix improper scoped elements

* working through side effects

* continued react wrapper work

* update changelog

* formatting

* fixes

* update changelog

* lint / formatting

* fix version injection

* fix version injection, work on test

* fix version injection, work on test

* fix merge conflicts

* fix jsdoc null issue

* fix templates

* use exports

* working on tests

* working on registration mocking

* fix customElements test

* linting

* fix some test stuff

* clean up test

* clean up comment

* rename scopedElements to dependencies

* linting / formatting

* linting / formatting

* mark all packages external and still bundle

* set bundle false

* set bundle true

* dont minify

* fix merge conflicts

* use built shoelace-element

* fix lint errors

* prettier

* appease eslint

* appease eslint gods

* appease eslint gods

* appease eslint gods

* appease eslint gods

* add shoelace-autoloader

* move it all into 1 function

* add exportmaps note

* prettier

* add jsdelivr entrypoint

* read as utf8

* update docs with .component.js importS

* prettier

custom-elements-manifest.config.js

@@ -3,6 +3,7 @@ import { parse } from 'comment-parser';
 import { pascalCase } from 'pascal-case';
 import commandLineArgs from 'command-line-args';
 import fs from 'fs';
+import * as path from 'path';
 
 const packageData = JSON.parse(fs.readFileSync('./package.json', 'utf8'));
 const { name, description, version, author, homepage, license } = packageData;
@@ -26,7 +27,7 @@ function replace(string, terms) {
 }
 
 export default {
-  globs: ['src/components/**/*.ts'],
+  globs: ['src/components/**/*.component.ts'],
   exclude: ['**/*.styles.ts', '**/*.test.ts'],
   plugins: [
     // Append package data
@@ -36,7 +37,32 @@ export default {
         customElementsManifest.package = { name, description, version, author, homepage, license };
       }
     },
+    // Infer tag names because we no longer use @customElement decorators.
+    {
+      name: 'shoelace-infer-tag-names',
+      analyzePhase({ ts, node, moduleDoc }) {
+        switch (node.kind) {
+          case ts.SyntaxKind.ClassDeclaration: {
+            const className = node.name.getText();
+            const classDoc = moduleDoc?.declarations?.find(declaration => declaration.name === className);
+
+            const importPath = moduleDoc.path;
+
+            // This is kind of a best guess at components. "thing.component.ts"
+            if (!importPath.endsWith('.component.ts')) {
+              return;
+            }
+
+            const tagName = 'sl-' + path.basename(importPath, '.component.ts');
 
+            classDoc.tagName = tagName;
+
+            // This used to be set to true by @customElement
+            classDoc.customElement = true;
+          }
+        }
+      }
+    },
     // Parse custom jsDoc tags
     {
       name: 'shoelace-custom-tags',
@@ -58,6 +84,9 @@ export default {
               });
             });
 
+            // This is what allows us to map JSDOC comments to ReactWrappers.
+            classDoc['jsDoc'] = node.jsDoc?.map(jsDoc => jsDoc.getFullText()).join('\n');
+
             const parsed = parse(`${customComments}\n */`);
             parsed[0].tags?.forEach(t => {
               switch (t.tag) {

docs/pages/getting-started/installation.md

@@ -196,6 +196,21 @@ setBasePath('/path/to/shoelace/%NPMDIR%
 Component modules include side effects for registration purposes. Because of this, importing directly from `@shoelace-style/shoelace` may result in a larger bundle size than necessary. For optimal tree shaking, always cherry pick, i.e. import components and utilities from their respective files, as shown above.
 :::
 
+### Avoiding side-effect imports
+
+By default, imports to components will auto-register themselves. This may not be ideal in all cases. To import just the component's class without auto-registering it's tag we can do the following:
+
+```diff
+- import SlButton from '@shoelace-style/shoelace/%NPMDIR%/components/button/button.js';
++ import SlButton from '@shoelace-style/shoelace/%NPMDIR%/components/button/button.component.js';
+```
+
+Notice how the import ends with `.component.js`. This is the current convention to convey the import does not register itself.
+
+:::danger
+While you can override the class or re-register the shoelace class under a different tag name, if you do so, many components won’t work as expected.
+:::
+
 ## The difference between CDN and npm
 
 You'll notice that the CDN links all start with `/%CDNDIR%/<path>` and npm imports use `/%NPMDIR%/<path>`. The `/%CDNDIR%` files are bundled separately from the `/%NPMDIR%` files. The `/%CDNDIR%` files come pre-bundled, which means all dependencies are inlined so you do not need to worry about loading additional libraries. The `/%NPMDIR%` files **DO NOT** come pre-bundled, allowing your bundler of choice to more efficiently deduplicate dependencies, resulting in smaller bundles and optimal code sharing.

docs/pages/resources/changelog.md

@@ -14,10 +14,17 @@ New versions of Shoelace are released as-needed and generally occur when a criti
 
 ## Next
 
+- Added JSDoc comments to React Wrappers for better documentation when hovering a component. [#1450]
+- Added `displayName` to React Wrappers for better debugging. [#1450]
+- Added non-auto-registering routes for Components to fix a number of issues around auto-registration. [#1450]
+- Added a console warning if you attempt to register the same Shoelace component twice. [#1450]
 - Added tests for `<sl-qr-code>` [#1416]
 - Added support for pressing [[Space]] to select/toggle selected `<sl-menu-item>` elements [#1429]
 - Added support for virtual elements in `<sl-popup>` [#1449]
 - Added the `spinner` part to `<sl-button>` [#1460]
+- Added a `shoelace.js` and `shoelace-autoloader.js` to exportmaps. [#1450]
+- Fixed React component treeshaking by introducing `sideEffects` key in `package.json`. [#1450]
+- Fixed a bug in `<sl-tree>` where it was auto-defining `<sl-tree-item>`. [#1450]
 - Fixed a bug in focus trapping of modal elements like `<sl-dialog>`. We now manually handle focus ordering as well as added `offsetParent()` check for tabbable boundaries in Safari. Test cases added for `<sl-dialog>` inside a shadowRoot [#1403]
 - Fixed a bug in `valueAsDate` on `<sl-input>` where it would always set `type="date"` for the underlying `<input>` element. It now falls back to the native browser implementation for the in-memory input. This may cause unexpected behavior if you're using `valueAsDate` on any input elements that aren't `type="date"`. [#1399]
 - Fixed a bug in `<sl-qr-code>` where the `background` attribute was never passed to the QR code [#1416]
@@ -27,6 +34,7 @@ New versions of Shoelace are released as-needed and generally occur when a criti
 - Fixed a bug in `<sl-tree>` that caused focus to be stolen when removing focused tree items [#1430]
 - Fixed a bug in `<sl-dialog>` and `<sl-drawer>` that caused nested modals to respond too eagerly to the [[Esc]] key [#1457]
 - Updated ESLint and related plugins to the latest versions
+- Changed the default entrypoint for jsDelivr to point to the autoloader. [#1450]
 
 ## 2.5.2
 

docs/pages/resources/contributing.md

@@ -367,7 +367,6 @@ Then use the following syntax for comments so they appear in the generated docs.
  * @cssproperty --color: The component's text color.
  * @cssproperty --background-color: The component's background color.
  */
-@customElement('sl-example')
 export default class SlExample {
   // ...
 }

package.json

@@ -9,12 +9,24 @@
   "web-types": "dist/web-types.json",
   "type": "module",
   "types": "dist/shoelace.d.ts",
+  "jsdelivr": "./cdn/shoelace-autoloader.js",
+  "sideEffects": [
+    "./dist/shoelace.js",
+    "./dist/shoelace-autoloader.js",
+    "./dist/components/**/*.js",
+    "./dist/translations/**/*.*",
+    "./src/translations/**/*.*",
+    "// COMMENT: This monstrosity below isn't perfect, but its like 99% to get bundlers to recognize 'thing.component.ts' as having no side effects. Example: https://regexr.com/7grof",
+    "./dist/components/**/*((?<!(\\.component|\\.styles)))\\.js"
+  ],
   "exports": {
     ".": {
       "types": "./dist/shoelace.d.ts",
       "import": "./dist/shoelace.js"
     },
     "./dist/custom-elements.json": "./dist/custom-elements.json",
+    "./dist/shoelace.js": "./dist/shoelace.js",
+    "./dist/shoelace-autoloader.js": "./dist/shoelace-autoloader.js",
     "./dist/themes/*": "./dist/themes/*",
     "./dist/components/*": "./dist/components/*",
     "./dist/utilities/*": "./dist/utilities/*",
@@ -96,6 +108,7 @@
     "del": "^7.0.0",
     "download": "^8.0.0",
     "esbuild": "^0.18.2",
+    "esbuild-plugin-replace": "^1.4.0",
     "eslint": "^8.44.0",
     "eslint-plugin-chai-expect": "^3.0.0",
     "eslint-plugin-chai-friendly": "^0.7.2",

scripts/build.js

@@ -11,6 +11,8 @@ import getPort, { portNumbers } from 'get-port';
 import ora from 'ora';
 import util from 'util';
 import * as path from 'path';
+import { readFileSync } from 'fs';
+import { replace } from 'esbuild-plugin-replace';
 
 const { serve } = commandLineArgs([{ name: 'serve', type: Boolean }]);
 const outdir = 'dist';
@@ -22,6 +24,8 @@ let childProcess;
 let buildResults;
 
 const bundleDirectories = [cdndir, outdir];
+let packageData = JSON.parse(readFileSync(path.join(process.cwd(), 'package.json'), 'utf-8'));
+const shoelaceVersion = JSON.stringify(packageData.version.toString());
 
 //
 // Runs 11ty and builds the docs. The returned promise resolves after the initial publish has completed. The child
@@ -108,13 +112,18 @@ async function buildTheSource() {
     //
     external: alwaysExternal,
     splitting: true,
-    plugins: []
+    plugins: [
+      replace({
+        __SHOELACE_VERSION__: shoelaceVersion
+      })
+    ]
   };
 
   const npmConfig = {
     ...cdnConfig,
-    bundle: false,
     external: undefined,
+    minify: false,
+    packages: 'external',
     outdir
   };
 

scripts/make-react.js

@@ -36,6 +36,8 @@ components.map(component => {
 
   fs.mkdirSync(componentDir, { recursive: true });
 
+  const jsDoc = component.jsDoc || '';
+
   const source = prettier.format(
     `
       import * as React from 'react';
@@ -45,14 +47,32 @@ components.map(component => {
       ${eventNameImport}
       ${eventImports}
 
-      export default createComponent({
-        tagName: '${component.tagName}',
+      const tagName = '${component.tagName}'
+
+      const component = createComponent({
+        tagName,
         elementClass: Component,
         react: React,
         events: {
           ${events}
+        },
+        displayName: "${component.name}"
+      })
+
+      ${jsDoc}
+      class SlComponent extends React.Component<Parameters<typeof component>[0]> {
+        constructor (...args: Parameters<typeof component>) {
+          super(...args)
+          Component.define(tagName)
         }
-      });
+
+        render () {
+          const { children, ...props } = this.props
+          return React.createElement(component, props, children)
+        }
+      }
+
+      export default SlComponent;
     `,
     Object.assign(prettierConfig, {
       parser: 'babel-ts'

scripts/plop/plopfile.js

@@ -33,6 +33,11 @@ export default function (plop) {
       {
         type: 'add',
         path: '../../src/components/{{ tagWithoutPrefix tag }}/{{ tagWithoutPrefix tag }}.ts',
+        templateFile: 'templates/component/define.hbs'
+      },
+      {
+        type: 'add',
+        path: '../../src/components/{{ tagWithoutPrefix tag }}/{{ tagWithoutPrefix tag }}.component.ts',
         templateFile: 'templates/component/component.hbs'
       },
       {

scripts/plop/templates/component/component.hbs

@@ -1,4 +1,4 @@
-import { customElement, property } from 'lit/decorators.js';
+import { property } from 'lit/decorators.js';
 import { html } from 'lit';
 import { LocalizeController } from '../../utilities/localize.js';
 import { watch } from '../../internal/watch.js';
@@ -23,7 +23,6 @@ import type { CSSResultGroup } from 'lit';
  *
  * @cssproperty --example - An example CSS custom property.
  */
-@customElement('{{ tag }}')
 export default class {{ properCase tag }} extends ShoelaceElement {
   static styles: CSSResultGroup = styles;
 

scripts/plop/templates/component/define.hbs

@@ -0,0 +1,4 @@
+import {{ properCase tag }} from './{{ tagWithoutPrefix tag }}.component.js';
+export * from './{{ tagWithoutPrefix tag }}.component.js';
+export default {{ properCase tag }};
+{{ properCase tag }}.define('{{ tag }}');