Merge branch 'main' into campaign-fix-5-4-3

Author: dgreif

.devcontainer/Dockerfile

@@ -1,7 +1,7 @@
 # See here for image contents: https://github.com/microsoft/vscode-dev-containers/tree/v0.222.0/containers/javascript-node/.devcontainer/base.Dockerfile
 
 # [Choice] Node.js version (use -bullseye variants on local arm64/Apple Silicon): 16, 14, 12, 16-bullseye, 14-bullseye, 12-bullseye, 16-buster, 14-buster, 12-buster
-ARG VARIANT="16"
+ARG VARIANT="24"
 FROM mcr.microsoft.com/vscode/devcontainers/javascript-node:0-${VARIANT}
 
 RUN apt-get update && export DEBIAN_FRONTEND=noninteractive \

.devcontainer/devcontainer.json

@@ -7,7 +7,7 @@
 		// Update 'VARIANT' to pick a Node version: 16, 14, 12.
 		// Append -bullseye or -buster to pin to an OS version.
 		// Use -bullseye variants on local arm64/Apple Silicon.
-		"args": { "VARIANT": "16" }
+		"args": { "VARIANT": "24" }
 	},
 
 	// Set *default* container specific settings.json values on container create.

.github/workflows/lighthouse.yml

@@ -12,10 +12,10 @@ jobs:
       - name: Checkout the project
         uses: actions/checkout@v3
 
-      - name: Use Node.js 16.x (LTS)
+      - name: Use Node.js 24.x (LTS)
         uses: actions/setup-node@v3
         with:
-          node-version: 16.x
+          node-version: 24.x
           cache: 'npm'
       - run: npm ci
 

.github/workflows/nodejs.yml

@@ -13,10 +13,10 @@ jobs:
     steps:
     - name: Checkout the project
       uses: actions/checkout@v3
-    - name: Use Node.js 16.x (LTS)
+    - name: Use Node.js 24.x (LTS)
       uses: actions/setup-node@v3
       with:
-        node-version: 16.x
+        node-version: 24.x
         cache: 'npm'
     - run: npm ci
     - name: Lint Codebase

.github/workflows/publish.yml

@@ -6,23 +6,25 @@ on:
   release:
     types: [created]
 
+permissions:
+  contents: read
+  id-token: write # for provenance and publish access
+
 jobs:
   publish-npm:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout the project
         uses: actions/checkout@v3
-      - name: Use Node.js 16.x (LTS)
+      - name: Use Node.js 24.x (LTS)
         uses: actions/setup-node@v3
         with:
-          node-version: 16.x
+          node-version: 24.x
           registry-url: https://registry.npmjs.org/
           cache: npm
       - run: npm ci
       - run: npm test
       - run: npm version ${TAG_NAME} --git-tag-version=false
         env:
           TAG_NAME: ${{ github.event.release.tag_name }}
-      - run: npm whoami; npm publish
-        env:
-          NODE_AUTH_TOKEN: ${{secrets.npm_token}}
+      - run: npm publish --provenance

docs/_guide/your-first-component.md

@@ -31,6 +31,27 @@ Catalyst will automatically convert the classes name; removing the trailing `Ele
 
 By convention Catalyst controllers end in `Element`; Catalyst will omit this when generating a tag name. The `Element` suffix is _not_ required - just convention. All examples in this guide use `Element` suffixed names.
 
+### Custom Element Names
+
+If you need to use a specific element name that doesn't match your class name (for example, to support minification), you can pass the element name directly to the `@controller` decorator:
+
+```js
+import {controller} from '@github/catalyst'
+
+@controller('hello-widget')
+class SomeClass extends HTMLElement {
+  connectedCallback() {
+    this.innerHTML = 'Hello from hello-widget!'
+  }
+}
+```
+<br>
+
+This will register the element as `<hello-widget>` regardless of the class name. This is particularly useful when:
+- Your production build minifies class names
+- You want explicit control over the element name
+- The class name doesn't follow the naming pattern required for automatic naming
+
 {% capture callout %}
 Remember! A class name _must_ include at least two CamelCased words (not including the `Element` suffix). One-word elements will raise exceptions. Example of good names: `UserListElement`, `SubTaskElement`, `PagerContainerElement`
 {% endcapture %}{% include callout.md %}
@@ -40,8 +61,8 @@ Remember! A class name _must_ include at least two CamelCased words (not includi
 
 The `@controller` decorator ties together the various other decorators within Catalyst, plus a few extra conveniences such as automatically registering the element, which saves you writing some boilerplate that you'd otherwise have to write by hand. Specifically the `@controller` decorator:
 
- - Derives a tag name based on your class name, removing the trailing `Element` suffix and lowercasing all capital letters, separating them with a dash.
- - Calls `window.customElements.define` with the newly derived tag name and your class.
+ - Derives a tag name based on your class name, removing the trailing `Element` suffix and lowercasing all capital letters, separating them with a dash. You can optionally provide a custom element name as a parameter (e.g., `@controller('my-element')`).
+ - Calls `window.customElements.define` with the newly derived (or provided) tag name and your class.
  - Calls `defineObservedAttributes` with the class to add map any `@attr` decorators. See [attrs]({{ site.baseurl }}/guide/attrs) for more on this.
  - Injects the following code inside of the `connectedCallback()` function of your class:
    - `bind(this)`; ensures that as your element connects it picks up any `data-action` handlers. See [actions]({{ site.baseurl }}/guide/actions) for more on this.
@@ -79,4 +100,16 @@ controller(
   }
 )
 ```
+
+Or with a custom element name:
+
+```js
+import {controller} from '@github/catalyst'
+
+controller('my-custom-name')(
+  class HelloWorldElement extends HTMLElement {
+    //...
+  }
+)
+```
 <br>