Implement optional element name parameter for @controller decorator

Co-authored-by: dgreif <3026298+dgreif@users.noreply.github.com>

Author: Copilot

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('happy-widget')
+class SomeClass extends HTMLElement {
+  connectedCallback() {
+    this.innerHTML = 'Hello from happy-widget!'
+  }
+}
+```
+<br>
+
+This will register the element as `<happy-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>

src/controller.ts

@@ -6,6 +6,15 @@ import type {CustomElementClass} from './custom-element.js'
  * registry, as well as ensuring `bind(this)` is called on `connectedCallback`,
  * wrapping the classes `connectedCallback` method if needed.
  */
-export function controller(classObject: CustomElementClass): void {
-  new CatalystDelegate(classObject)
+export function controller(classObject: CustomElementClass): void
+export function controller(name: string): (classObject: CustomElementClass) => void
+export function controller(
+  classObjectOrName: CustomElementClass | string
+): void | ((classObject: CustomElementClass) => void) {
+  if (typeof classObjectOrName === 'string') {
+    return (classObject: CustomElementClass) => {
+      new CatalystDelegate(classObject, classObjectOrName)
+    }
+  }
+  new CatalystDelegate(classObjectOrName)
 }

src/core.ts

@@ -8,7 +8,7 @@ import {observe} from './lazy-define.js'
 const symbol = Symbol.for('catalyst')
 
 export class CatalystDelegate {
-  constructor(classObject: CustomElementClass) {
+  constructor(classObject: CustomElementClass, elementName?: string) {
     // eslint-disable-next-line @typescript-eslint/no-this-alias
     const delegate = this
 
@@ -44,7 +44,7 @@ export class CatalystDelegate {
     })
 
     defineObservedAttributes(classObject)
-    register(classObject)
+    register(classObject, elementName)
   }
 
   observedAttributes(instance: HTMLElement, observedAttributes: string[]) {

src/register.ts

@@ -8,14 +8,14 @@ import {dasherize} from './dasherize.js'
  *
  * Example: HelloController => hello-controller
  */
-export function register(classObject: CustomElementClass): CustomElementClass {
-  const name = dasherize(classObject.name).replace(/-element$/, '')
+export function register(classObject: CustomElementClass, name?: string): CustomElementClass {
+  const tagName = name || dasherize(classObject.name).replace(/-element$/, '')
 
   try {
-    window.customElements.define(name, classObject)
+    window.customElements.define(tagName, classObject)
     // eslint-disable-next-line @typescript-eslint/ban-ts-comment
     // @ts-ignore
-    window[classObject.name] = customElements.get(name)
+    window[classObject.name] = customElements.get(tagName)
   } catch (e: unknown) {
     // The only reason for window.customElements.define to throw a `NotSupportedError`
     // is if the element has already been defined.

test/controller.ts

@@ -14,6 +14,19 @@ describe('controller', () => {
     expect(instance).to.be.instanceof(ControllerRegisterElement)
   })
 
+  it('registers element with custom name when provided', async () => {
+    @controller('happy-widget')
+    class SomeClass extends HTMLElement {}
+    instance = await fixture(html`<happy-widget />`)
+    expect(instance).to.be.instanceof(SomeClass)
+  })
+
+  it('registers element with custom name using function syntax', async () => {
+    controller('custom-element-name')(class AnotherClass extends HTMLElement {})
+    instance = await fixture(html`<custom-element-name />`)
+    expect(instance).to.exist
+  })
+
   it('adds data-catalyst to elements', async () => {
     @controller
     // eslint-disable-next-line @typescript-eslint/no-unused-vars