From 3cd5d16bc2bb137894d7d5d13f4b56ee0f90b374 Mon Sep 17 00:00:00 2001 From: Keith Cirkel Date: Mon, 2 May 2022 14:18:24 +0000 Subject: [PATCH 1/6] remove controller or component suffix from registered elements --- docs/_guide/conventions.md | 11 ++++++++--- docs/_guide/your-first-component.md | 4 ++-- src/register.ts | 4 ++-- test/register.ts | 12 ++++++++++++ 4 files changed, 24 insertions(+), 7 deletions(-) diff --git a/docs/_guide/conventions.md b/docs/_guide/conventions.md index 4d9d01fd..a7548a07 100644 --- a/docs/_guide/conventions.md +++ b/docs/_guide/conventions.md @@ -5,13 +5,18 @@ subtitle: Conventions Catalyst strives for convention over code. Here are a few conventions we recommend when writing Catalyst code: -### Use `Element` to suffix your controller class +### Use `Element` or `Component` to suffix your controller class -Built in HTML elements all extend from the `HTMLElement` constructor, and are all suffixed with `Element` (for example `HTMLElement`, `SVGElement`, `HTMLInputElement` and so on). Catalyst components should be no different, they should behave as closely to the built-ins as possible. +Built in HTML elements all extend from the `HTMLElement` constructor, and are all suffixed with `Element` (for example `HTMLElement`, `SVGElement`, `HTMLInputElement` and so on). Catalyst components can be suffixed with `Element`, `Component` or `Controller`. We think elements should behave as closely to the built-ins as possible, so we like to use `Element`, but the other suffixes might be useful for symettry with other server side comoponent frameworks such as [ViewComponent](https://viewcomponent.org/). ```typescript @controller -class UserListElement extends HTMLElement {} +class UserListElement extends HTMLElement {} // `` +``` + +```typescript +@controller +class UserListComponent extends HTMLElement {} // `` ``` ### The best class-names are two word descriptions diff --git a/docs/_guide/your-first-component.md b/docs/_guide/your-first-component.md index 5b6348d7..4b876891 100644 --- a/docs/_guide/your-first-component.md +++ b/docs/_guide/your-first-component.md @@ -27,10 +27,10 @@ class HelloWorldElement extends HTMLElement { Catalyst will automatically convert the classes name; removing the trailing `Element` suffix and lowercasing all capital letters, separating them with a dash. -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. +Catalyst controllers can end in `Element`, `Controller`, or `Component` and Catalyst will remove this suffix when generating a tag name. Adding one of these suffixes is _not_ required - just convention. All examples in this guide use `Element` suffixed names. {% 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` +Remember! A class name _must_ include at least two CamelCased words (not including the `Element`, `Controller` or `Component` suffix). One-word elements will raise exceptions. Example of good names: `UserListElement`, `SubTaskController`, `PagerContainerComponent` {% endcapture %}{% include callout.md %} diff --git a/src/register.ts b/src/register.ts index 43780089..cf29ca68 100644 --- a/src/register.ts +++ b/src/register.ts @@ -1,5 +1,5 @@ -import type {CustomElement} from './custom-element.js' import {dasherize} from './dasherize.js' +import type {CustomElement} from './custom-element.js' /** * Register the controller as a custom element. @@ -9,7 +9,7 @@ import {dasherize} from './dasherize.js' * Example: HelloController => hello-controller */ export function register(classObject: CustomElement): CustomElement { - const name = dasherize(classObject.name).replace(/-element$/, '') + const name = dasherize(classObject.name).replace(/-(element|controller|component)$/, '') try { window.customElements.define(name, classObject) diff --git a/test/register.ts b/test/register.ts index f39531ee..5f4fef99 100644 --- a/test/register.ts +++ b/test/register.ts @@ -70,4 +70,16 @@ describe('register', () => { class FirstSuffixElement {} expect(window.customElements.get('first-suffix')).to.equal(FirstSuffixElement) }) + + it('automatically drops the `Controller` suffix', () => { + @register + class SecondSuffixController {} + expect(window.customElements.get('second-suffix')).to.equal(SecondSuffixController) + }) + + it('automatically drops the `Component` suffix', () => { + @register + class ThirdSuffixComponent {} + expect(window.customElements.get('third-suffix')).to.equal(ThirdSuffixComponent) + }) }) From 6515d9672f238ae15d2a59395943d70ca19c5db5 Mon Sep 17 00:00:00 2001 From: Keith Cirkel Date: Mon, 2 May 2022 17:35:37 +0100 Subject: [PATCH 2/6] v2 will be 2kb --- package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/package.json b/package.json index ce7201a5..89aa9da4 100644 --- a/package.json +++ b/package.json @@ -53,7 +53,7 @@ { "path": "lib/index.js", "import": "{controller, attr, target, targets}", - "limit": "1.64kb" + "limit": "2kb" } ] } From 976260faef8fe167a6f15c3f40f823b365a43785 Mon Sep 17 00:00:00 2001 From: Keith Cirkel Date: Tue, 3 May 2022 12:42:51 +0100 Subject: [PATCH 3/6] improve convention node on controller suffixes --- docs/_guide/conventions.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/_guide/conventions.md b/docs/_guide/conventions.md index a7548a07..8577a57c 100644 --- a/docs/_guide/conventions.md +++ b/docs/_guide/conventions.md @@ -5,9 +5,9 @@ subtitle: Conventions Catalyst strives for convention over code. Here are a few conventions we recommend when writing Catalyst code: -### Use `Element` or `Component` to suffix your controller class +### Suffix your controllers consistently, for symmetry -Built in HTML elements all extend from the `HTMLElement` constructor, and are all suffixed with `Element` (for example `HTMLElement`, `SVGElement`, `HTMLInputElement` and so on). Catalyst components can be suffixed with `Element`, `Component` or `Controller`. We think elements should behave as closely to the built-ins as possible, so we like to use `Element`, but the other suffixes might be useful for symettry with other server side comoponent frameworks such as [ViewComponent](https://viewcomponent.org/). +Catalyst components can be suffixed with `Element`, `Component` or `Controller`. We think elements should behave as closely to the built-ins as possible, so we like to use `Element` (existing elements do this, for example `HTMLDivElement`, `SVGElement`). If you're using a server side comoponent framework such as [ViewComponent](https://viewcomponent.org/), it's probably better to suffix `Component` for symmetry with that component framework. ```typescript @controller From 083a5703ae1b326ea1fb80417935eb826768460a Mon Sep 17 00:00:00 2001 From: Keith Cirkel Date: Tue, 3 May 2022 12:45:45 +0100 Subject: [PATCH 4/6] improve your-first-component docs around suffixes --- docs/_guide/your-first-component.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/_guide/your-first-component.md b/docs/_guide/your-first-component.md index 4b876891..4ca0e4df 100644 --- a/docs/_guide/your-first-component.md +++ b/docs/_guide/your-first-component.md @@ -27,7 +27,7 @@ class HelloWorldElement extends HTMLElement { Catalyst will automatically convert the classes name; removing the trailing `Element` suffix and lowercasing all capital letters, separating them with a dash. -Catalyst controllers can end in `Element`, `Controller`, or `Component` and Catalyst will remove this suffix when generating a tag name. Adding one of these suffixes is _not_ required - just convention. All examples in this guide use `Element` suffixed names. +Catalyst controllers can end in `Element`, `Controller`, or `Component` and Catalyst will remove this suffix when generating a tag name. Adding one of these suffixes is _not_ required - just convention. All examples in this guide use `Element` suffixed names (see our [convention note on this for more]({{ site.baseurl }}/guide/conventions#suffix-your-controllers-consistently-for-symmetry)). {% capture callout %} Remember! A class name _must_ include at least two CamelCased words (not including the `Element`, `Controller` or `Component` suffix). One-word elements will raise exceptions. Example of good names: `UserListElement`, `SubTaskController`, `PagerContainerComponent` From 51c91979d8c4d5404c3608d80284d8e550c354d1 Mon Sep 17 00:00:00 2001 From: Keith Cirkel Date: Tue, 3 May 2022 12:46:57 +0100 Subject: [PATCH 5/6] add exact example for tag name in your-first-component --- docs/_guide/your-first-component.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/_guide/your-first-component.md b/docs/_guide/your-first-component.md index 4ca0e4df..9e6b7c5f 100644 --- a/docs/_guide/your-first-component.md +++ b/docs/_guide/your-first-component.md @@ -25,7 +25,7 @@ class HelloWorldElement extends HTMLElement { ```
-Catalyst will automatically convert the classes name; removing the trailing `Element` suffix and lowercasing all capital letters, separating them with a dash. +Catalyst will automatically convert the classes name so the HTML tag will be ``. It removes the trailing `Element` suffix and lowercases all capital letters, separating them with a dash. Catalyst controllers can end in `Element`, `Controller`, or `Component` and Catalyst will remove this suffix when generating a tag name. Adding one of these suffixes is _not_ required - just convention. All examples in this guide use `Element` suffixed names (see our [convention note on this for more]({{ site.baseurl }}/guide/conventions#suffix-your-controllers-consistently-for-symmetry)). From cccfc679f3c15b7e99d3fa65e795a6029f61a6d9 Mon Sep 17 00:00:00 2001 From: Keith Cirkel Date: Tue, 3 May 2022 12:48:17 +0100 Subject: [PATCH 6/6] drop the the --- docs/_guide/conventions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/_guide/conventions.md b/docs/_guide/conventions.md index 8577a57c..e38472af 100644 --- a/docs/_guide/conventions.md +++ b/docs/_guide/conventions.md @@ -7,7 +7,7 @@ Catalyst strives for convention over code. Here are a few conventions we recomme ### Suffix your controllers consistently, for symmetry -Catalyst components can be suffixed with `Element`, `Component` or `Controller`. We think elements should behave as closely to the built-ins as possible, so we like to use `Element` (existing elements do this, for example `HTMLDivElement`, `SVGElement`). If you're using a server side comoponent framework such as [ViewComponent](https://viewcomponent.org/), it's probably better to suffix `Component` for symmetry with that component framework. +Catalyst components can be suffixed with `Element`, `Component` or `Controller`. We think elements should behave as closely to the built-ins as possible, so we like to use `Element` (existing elements do this, for example `HTMLDivElement`, `SVGElement`). If you're using a server side comoponent framework such as [ViewComponent](https://viewcomponent.org/), it's probably better to suffix `Component` for symmetry with that framework. ```typescript @controller