Skip to content

Commit b61ba08

Browse files
mattcosta7Copilot
andcommitted
Merge PR head 739e30d into installable branch (testing only)
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
2 parents da06b38 + 739e30d commit b61ba08

5 files changed

Lines changed: 42 additions & 7 deletions

File tree

‎docs/_guide/attrs.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -151,6 +151,7 @@ When an element gets connected to the DOM, the attr is initialized. During this
151151
- When connected, if the element _does not_ have a matching attribute, the default _is_ applied.
152152
- 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.
153153
- 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.
154+
- 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.
154155
- 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`.
155156

156157
{% capture callout %}

‎docs/_guide/decorators.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -102,7 +102,9 @@ TypeScript 5.0+ and SWC (`decoratorVersion: "2023-11"`) compile standard (TC39)
102102

103103
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.
104104

105-
Without an explicit name, `@controller` derives the element name from the class name, so the class name must survive your build. For example, if TypeScript emits standard decorators as ES2022 and esbuild then lowers that output to an older target, esbuild renames the class unless you turn on [`keepNames`](https://esbuild.github.io/api/#keep-names). Passing the tag name, as in `@controller('hello-world')`, avoids this. See [build considerations]({{ site.baseurl }}/guide/you-will-need#build-considerations).
105+
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.
106+
107+
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).
106108

107109
### Legacy decorators and `useDefineForClassFields`
108110

‎docs/_guide/you-will-need.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,8 @@ The preferred way to handle this is to disable renaming class names in your buil
3232

3333
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.
3434

35+
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.
36+
3537

3638
```ts
3739
{ keep_names: true }

‎src/attr.ts‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -157,13 +157,15 @@ export function initializeAttrs(instance: HTMLElement, names?: Iterable<string>)
157157
if (!names) names = meta(proto, attrKey)
158158
const nameOf = (key: string) => attrName(`${prefix}${key}`)
159159
const kinds = standardAttrKinds.get(proto?.constructor)
160-
// Standard decorators record whether an attr is a getter or setter. For legacy ones, look for an accessor on the
161-
// classes above the built-in element they extend. An attr named like a built-in accessor, such as `title`, is a field.
160+
// Standard decorators record whether an attr is a getter or setter. For others, look for a getter without a setter
161+
// on the classes above the built-in element they extend. One with a setter, such as an auto-accessor or a getter and
162+
// setter pair, stores a value as far as Catalyst can tell, so it keeps registration order, as in v1.8.1. An attr
163+
// named like a built-in accessor, such as `title`, is a field.
162164
const isAccessor = (key: string) => {
163165
if (kinds?.has(key)) return kinds.get(key)
164166
for (let o = proto; o && !isNative(o); o = Object.getPrototypeOf(o)) {
165167
const descriptor = Object.getOwnPropertyDescriptor(o, key)
166-
if (descriptor) return !('value' in descriptor)
168+
if (descriptor) return !!descriptor.get && !descriptor.set
167169
}
168170
return false
169171
}

‎test/standard/attr.ts‎

Lines changed: 31 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -178,6 +178,36 @@ describe('Attr (standard decorators)', () => {
178178
expect(seen.override).to.eql(seen.field)
179179
})
180180

181+
// Undecorated auto-accessors have no metadata recording that they store a value, but they have a setter, which
182+
// computed getter attrs don't, so they initialize in registration order as in v1.8.1.
183+
for (const registration of ['attr calls', 'explicit names'] as const) {
184+
it(`initializes undecorated accessors registered by ${registration} in registration order`, () => {
185+
class UndecoratedAccessorElement extends HTMLElement {
186+
static observedAttributes = ['data-ready']
187+
accessor ready = true
188+
accessor status = 'default'
189+
connectedCallback() {
190+
if (registration === 'explicit names') initializeAttrs(this, ['ready', 'status'])
191+
else initializeAttrs(this)
192+
}
193+
attributeChangedCallback() {
194+
this.status = 'updated'
195+
}
196+
}
197+
if (registration === 'attr calls') {
198+
attr(UndecoratedAccessorElement.prototype, 'ready')
199+
attr(UndecoratedAccessorElement.prototype, 'status')
200+
}
201+
const tag = `undecorated-accessor-${registration.replace(' ', '-')}`
202+
customElements.define(tag, UndecoratedAccessorElement)
203+
const element = document.createElement(tag) as UndecoratedAccessorElement
204+
element.setAttribute('data-status', 'html')
205+
document.body.append(element)
206+
element.remove()
207+
expect(element.status).to.equal('html')
208+
})
209+
}
210+
181211
it('initializes explicitly named accessor attrs in the order given, like fields', () => {
182212
class ExplicitNamesElement extends HTMLElement {
183213
static observedAttributes = ['data-ready']
@@ -300,12 +330,10 @@ describe('Attr (standard decorators)', () => {
300330
}
301331
class Child extends Base {
302332
input = 'field'
333+
// A getter without a setter computes its value, so it initializes after the attrs it reads.
303334
override get label() {
304335
return `${this.input}-label`
305336
}
306-
override set label(value: string) {
307-
super.label = value
308-
}
309337
}
310338
attr(Child.prototype, 'input')
311339
attr(Child.prototype, 'label')

0 commit comments

Comments
 (0)