Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
28 commits
Select commit Hold shift + click to select a range
5ee8538
Support standard decorators in controller, target, targets and attr
mattcosta7 Nov 12, 2026
75d399e
Guard Symbol.metadata against frozen Symbol, register standard attrs …
mattcosta7 Nov 12, 2026
82f5eff
Point lockfile entries at registry.npmjs.org
mattcosta7 Nov 12, 2026
02c874b
Run shared decorator tests under both legacy and standard decorators
mattcosta7 Nov 13, 2026
ff03509
Support standard decorators in @register, document keeping class names
mattcosta7 Nov 13, 2026
2d292f5
Docs: an explicit @controller tag name avoids class renaming
mattcosta7 Nov 13, 2026
f87d2e9
Merge branch 'main' into mattcosta7-catalyst-dual-decorator-support
mattcosta7 Nov 16, 2026
af8b130
Register standard base attrs before legacy subclass attrs
mattcosta7 Nov 17, 2026
846043e
Fix standard decorator edge cases found in ship-check
mattcosta7 Nov 17, 2026
f87a6e9
Merge legacy and standard attrs per class, base first
mattcosta7 Nov 17, 2026
483d2fd
Keep legacy types for ReturnType and Parameters of register and target
mattcosta7 Nov 17, 2026
74a6ae7
Merge branch 'main' into mattcosta7-catalyst-dual-decorator-support
francinelucca Nov 18, 2026
7f9f09f
Initialize overriding getter attrs after stored attrs, in both modes
mattcosta7 Nov 19, 2026
23d4eeb
Document declare for legacy targets with useDefineForClassFields
mattcosta7 Nov 19, 2026
b86c922
Order mixed legacy getters after stored attrs and keep legacy types
mattcosta7 Nov 19, 2026
48bfee9
Initialize attrs with HTML attributes first instead of ordering by kind
mattcosta7 Nov 19, 2026
8bf25cb
Cache attribute names and partition attrs instead of sorting
mattcosta7 Nov 19, 2026
ad20798
Initialize field attrs first, in registration order
mattcosta7 Nov 19, 2026
af9c1b8
Return nothing from @defineObservedAttributes and test native class f…
mattcosta7 Nov 19, 2026
abdca2e
Initialize fields before checking getter attr presence; ignore built-…
mattcosta7 Nov 19, 2026
92ed9d5
Register a class's standard attrs before its legacy attrs
mattcosta7 Nov 20, 2026
5a52b0b
Initialize @attr accessors with fields, in registration order
mattcosta7 Nov 20, 2026
bf5c10c
Document that standard decorators register accessor attrs first
mattcosta7 Nov 20, 2026
196af15
Classify attrs by recorded kind, and stop at built-in element prototypes
mattcosta7 Nov 21, 2026
0c45f04
Fix attr classification edge cases and check class decorator targets
mattcosta7 Nov 21, 2026
bbb9318
Document that esbuild renames classes in standard decorator output
mattcosta7 Nov 21, 2026
739e30d
Keep registration order for legacy attrs with a setter
mattcosta7 Nov 21, 2026
746788a
Handle frozen parent metadata and an attr named constructor
mattcosta7 Nov 21, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .eslintrc.json
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@
},
"overrides": [
{
"files": "test/*",
"files": "test/**",
"rules": {
"@typescript-eslint/no-empty-function": "off"
},
Expand Down
5 changes: 4 additions & 1 deletion docs/_guide/attrs.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ Catalyst includes the `@attr` decorator, which provides nice syntax sugar to sim
- The attribute name is automatically [observed, meaning `attributeChangedCallback` will fire when it changes](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements#using_the_lifecycle_callbacks).
- Assigning a value in the class description will make that value the _default_ value, so when the element is connected that value is set (unless the element has the attribute defined already).

To use the `@attr` decorator, attach it to a class field, and it will get/set the value of the matching `data-*` attribute.
To use the `@attr` decorator, attach it to a class field, and it will get/set the value of the matching `data-*` attribute. With [standard decorators]({{ site.baseurl }}/guide/decorators#standard-decorators), `@attr` needs decorator metadata support, which TypeScript has from version 5.2.

### Example

Expand Down Expand Up @@ -150,6 +150,9 @@ When an element gets connected to the DOM, the attr is initialized. During this
- If the class property has a value, that is the _default_
- When connected, if the element _does not_ have a matching attribute, the default _is_ applied.
- When connected, if the element _does_ have a matching attribute, the default _is not_ applied, the property will be assigned to the value of the attribute instead.
- Field and `accessor` attrs are initialized first, in the order they're registered. Getter and setter attrs come next, starting with those that have a matching attribute, so a getter's default can read the other attrs' values.
- With legacy decorators, Catalyst can't tell an `accessor` from a getter and setter you wrote, so only a getter without a setter counts as a getter attr. Any attr with a setter initializes in registration order, as in earlier versions.
- Standard decorators register `accessor` attrs before field attrs, whatever order they're declared in. To initialize attrs in declaration order, as legacy decorators do, decorate fields, not accessors: `@attr name!: string`.

{% capture callout %}
Remember! The values defined in the class field are the _default_. They won't be set if the element is created and its attribute set to a custom value!
Expand Down
43 changes: 41 additions & 2 deletions docs/_guide/decorators.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ title: Decorators
subtitle: Using TypeScript for ergonomics
---

Decorators are used heavily in Catalyst, because they provide really clean ergonomics and makes using the library a lot easier. Decorators are a special, (currently) non standard, feature of TypeScript. You'll need to turn the `experimentalDecorators` option on inside of your TypeScript project to use them (if you're using `@babel/plugin-proposal-decorators` plugin, you need to use [`legacy` option](https://babeljs.io/docs/en/babel-plugin-proposal-decorators#legacy)).
Decorators are used heavily in Catalyst, because they provide really clean ergonomics and makes using the library a lot easier. Catalyst's decorators work with both TypeScript's legacy `experimentalDecorators` option (or the `@babel/plugin-proposal-decorators` [`legacy` option](https://babeljs.io/docs/en/babel-plugin-proposal-decorators#legacy)) and [standard decorators](#standard-decorators). The same imports work in both modes.

You can read more about [decorators in the TypeScript handbook](https://www.typescriptlang.org/docs/handbook/decorators.html), but here's quick guide:

Expand Down Expand Up @@ -83,6 +83,45 @@ class HelloWorldElement extends HTMLElement {
}
```

### Standard decorators

TypeScript 5.0+ and SWC (`decoratorVersion: "2023-11"`) compile standard (TC39) decorators when `experimentalDecorators` is off. `@controller`, `@attr`, `@target` and `@targets` support them, with two differences from legacy decorators:

- `@target` and `@targets` must decorate an `accessor`. Standard decorators can't decorate `declare` fields, and a plain field would hide the getter the decorator defines:

```typescript
@controller
class HelloWorldElement extends HTMLElement {
@target accessor output!: HTMLElement
@targets accessor items!: HTMLElement[]
}
```

Assigning to the accessor throws a `TypeError`, just as assigning to the getter-only legacy property does.
- `@attr` records its fields in [decorator metadata](https://github.com/tc39/proposal-decorator-metadata), so with TypeScript you need version 5.2 or later. `@attr` can decorate a field, an `accessor`, a getter or a setter. Prefer a field, such as `@attr name!: string` in place of a legacy `@attr declare name: string`: standard decorators register accessors before fields, so mixing them changes the order attrs initialize in (see [attrs]({{ site.baseurl }}/guide/attrs#default-values)).

Catalyst's member decorators only support public, non-static members. `@controller` (and `@register`) define the element once static fields such as `observedAttributes` and `attrPrefix` are assigned, the same as with legacy decorators.

Without an explicit name, `@controller` derives the element name from the class name, so the class name must survive your build. With standard decorators, TypeScript's output declares the class twice under the same name, and esbuild renames one of them in any transform or bundle, even at the same target. `HelloWorldElement` then becomes `HelloWorldElement2`, and the element is defined as `hello-world-element2` without an error. esbuild's [`keepNames`](https://esbuild.github.io/api/#keep-names) keeps the name from version 0.18.2. Before that, `@controller` sees an empty or internal name, such as `_this`, and defining the element throws. Minifiers rename classes too.

Passing the tag name, as in `@controller('hello-world')`, avoids all of this, and we recommend it with standard decorators. See [build considerations]({{ site.baseurl }}/guide/you-will-need#build-considerations).

### Legacy decorators and `useDefineForClassFields`

With legacy decorators, `@target` and `@targets` define a getter on the class prototype. When `useDefineForClassFields` is on, TypeScript defines each declared field on the instance, which hides that getter, so the target is always `undefined`. TypeScript turns `useDefineForClassFields` on by default when `target` is `ES2022` or later.

Marking the field with `!` or `?`, or typing it as `| undefined`, still emits the field. Use `declare`, which emits nothing:

```typescript
@controller
class HelloWorldElement extends HTMLElement {
@target declare output: HTMLElement | undefined
@targets declare items: HTMLElement[]
}
```

`@target` returns `undefined` when no element matches, so `| undefined` is the accurate type. `@attr` works either way, because Catalyst redefines `@attr` fields on each instance when it connects. Standard decorators avoid the problem by requiring an [accessor](#standard-decorators).

### Supporting `strictPropertyInitialization`

TypeScript comes with various "strict" mode settings, one of which is `strictPropertyInitialization` which lets TypeScript catch potential class properties which might not be assigned during construction of a class. This option conflicts with Catalyst's `@target`/`@targets` decorators, which safely do the assignment but TypeScript's simple heuristics cannot detect this. There are two ways to work around this:
Expand All @@ -96,7 +135,7 @@ TypeScript comes with various "strict" mode settings, one of which is `strictPro
}
```

Note that this only works on TypeScript 3.7+, so if you're on an older version, you can also use the [definite initialization operator](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-2-7.html#definite-assignment-assertions) to do the same thing.
Note that this only works on TypeScript 3.7+, so if you're on an older version, you can also use the [definite initialization operator](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-2-7.html#definite-assignment-assertions) to do the same thing, as long as `useDefineForClassFields` is off ([see above](#legacy-decorators-and-usedefineforclassfields)). With [standard decorators](#standard-decorators), use the definite initialization operator on an accessor instead: `@target accessor something!: HTMLElement`.

2. You can also disable the compiler option (other strict mode rules can still apply) in your `tsconfig.json` like so:

Expand Down
2 changes: 1 addition & 1 deletion docs/_guide/targets.md
Original file line number Diff line number Diff line change
Expand Up @@ -139,7 +139,7 @@ Important to note here is that nodes from the `shadowRoot` get returned _first_.

### What about without Decorators?

If you're using decorators, then the `@target` and `@targets` decorators will turn the decorated properties into getters.
If you're using decorators, then the `@target` and `@targets` decorators will turn the decorated properties into getters. With [standard decorators]({{ site.baseurl }}/guide/decorators#standard-decorators), decorate an accessor instead of a field: `@target accessor output!: HTMLElement`.

If you're not using decorators, then you'll need to make a `getter`, and call `findTarget(this, key)` or `findTargets(this, key)` in the getter, for example:

Expand Down
6 changes: 5 additions & 1 deletion docs/_guide/you-will-need.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ Catalyst is available as an npm module `@github/catalyst`. To install into your

### TypeScript

Catalyst has no strict dependencies, but it relies on TypeScript for decorator support, so you should also configure your project to use TypeScript. [Read the TypeScript docs on how to set up TypeScript on a new project](https://www.typescriptlang.org/docs/home.html).
Catalyst has no strict dependencies, but it relies on TypeScript for decorator support, so you should also configure your project to use TypeScript. [Read the TypeScript docs on how to set up TypeScript on a new project](https://www.typescriptlang.org/docs/home.html). Catalyst's decorators work with both the `experimentalDecorators` option and standard decorators; see [Decorators]({{ site.baseurl }}/guide/decorators).

### Polyfills

Expand All @@ -20,6 +20,8 @@ Catalyst uses modern browser standards, and so requires evergreen browsers or ma

Please note this list may increase over time. Catalyst will never ship with polyfills that add missing browser functionality, but will continue to use the latest Web Standards, and so may require more polyfills as new releases come out.

The one exception is `Symbol.metadata`, which [standard decorators]({{ site.baseurl }}/guide/decorators#standard-decorators) use to store metadata. TypeScript only attaches decorator metadata when `Symbol.metadata` exists, so if it is missing, Catalyst defines it as `Symbol.for('Symbol.metadata')` when it loads. That is the key SWC's and Babel's decorator helpers fall back to. Lit also defines `Symbol.metadata` when it is missing.

### Build considerations

When using build tools, some JavaScript minifiers modify the class name that Catalyst relies on. You know you have an issue if you encounter the error `"c" is not a valid custom element name`.
Expand All @@ -30,6 +32,8 @@ The preferred way to handle this is to disable renaming class names in your buil

When using ESBuild you can turn off all class and function name minification with the [`keep_names`](https://esbuild.github.io/api/#keep-names) option. Setting this to `true` in your build will opt-out all classes and all functions from minification.

With [standard decorators]({{ site.baseurl }}/guide/decorators#standard-decorators), esbuild renames classes in TypeScript's output even without minification, and `keep_names` only prevents it from esbuild 0.18.2. Passing a tag name to `@controller` works with every build tool.


```ts
{ keep_names: true }
Expand Down
Loading