/
reactive-element.ts
1535 lines (1437 loc) · 52.5 KB
/
reactive-element.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
/**
* @license
* Copyright 2017 Google LLC
* SPDX-License-Identifier: BSD-3-Clause
*/
/**
* Use this module if you want to create your own base class extending
* {@link ReactiveElement}.
* @packageDocumentation
*/
import {
getCompatibleStyle,
adoptStyles,
CSSResultGroup,
CSSResultOrNative,
} from './css-tag.js';
import type {
ReactiveController,
ReactiveControllerHost,
} from './reactive-controller.js';
export * from './css-tag.js';
export type {
ReactiveController,
ReactiveControllerHost,
} from './reactive-controller.js';
const DEV_MODE = true;
let requestUpdateThenable: (name: string) => {
then: (
onfulfilled?: (value: boolean) => void,
_onrejected?: () => void
) => void;
};
let issueWarning: (code: string, warning: string) => void;
const trustedTypes = (window as unknown as {trustedTypes?: {emptyScript: ''}})
.trustedTypes;
// Temporary workaround for https://crbug.com/993268
// Currently, any attribute starting with "on" is considered to be a
// TrustedScript source. Such boolean attributes must be set to the equivalent
// trusted emptyScript value.
const emptyStringForBooleanAttribute = trustedTypes
? (trustedTypes.emptyScript as unknown as '')
: '';
const polyfillSupport = DEV_MODE
? window.reactiveElementPolyfillSupportDevMode
: window.reactiveElementPolyfillSupport;
if (DEV_MODE) {
// Ensure warnings are issued only 1x, even if multiple versions of Lit
// are loaded.
const issuedWarnings: Set<string | undefined> =
(globalThis.litIssuedWarnings ??= new Set());
// Issue a warning, if we haven't already.
issueWarning = (code: string, warning: string) => {
warning += ` See https://lit.dev/msg/${code} for more information.`;
if (!issuedWarnings.has(warning)) {
console.warn(warning);
issuedWarnings.add(warning);
}
};
issueWarning(
'dev-mode',
`Lit is in dev mode. Not recommended for production!`
);
// Issue polyfill support warning.
if (window.ShadyDOM?.inUse && polyfillSupport === undefined) {
issueWarning(
'polyfill-support-missing',
`Shadow DOM is being polyfilled via \`ShadyDOM\` but ` +
`the \`polyfill-support\` module has not been loaded.`
);
}
requestUpdateThenable = (name) => ({
then: (
onfulfilled?: (value: boolean) => void,
_onrejected?: () => void
) => {
issueWarning(
'request-update-promise',
`The \`requestUpdate\` method should no longer return a Promise but ` +
`does so on \`${name}\`. Use \`updateComplete\` instead.`
);
if (onfulfilled !== undefined) {
onfulfilled(false);
}
},
});
}
/**
* Contains types that are part of the unstable debug API.
*
* Everything in this API is not stable and may change or be removed in the future,
* even on patch releases.
*/
// eslint-disable-next-line @typescript-eslint/no-namespace
export namespace ReactiveUnstable {
/**
* When Lit is running in dev mode and `window.emitLitDebugLogEvents` is true,
* we will emit 'lit-debug' events to window, with live details about the update and render
* lifecycle. These can be useful for writing debug tooling and visualizations.
*
* Please be aware that running with window.emitLitDebugLogEvents has performance overhead,
* making certain operations that are normally very cheap (like a no-op render) much slower,
* because we must copy data and dispatch events.
*/
// eslint-disable-next-line @typescript-eslint/no-namespace
export namespace DebugLog {
export type Entry = Update;
export interface Update {
kind: 'update';
}
}
}
interface DebugLoggingWindow {
// Even in dev mode, we generally don't want to emit these events, as that's
// another level of cost, so only emit them when DEV_MODE is true _and_ when
// window.emitLitDebugEvents is true.
emitLitDebugLogEvents?: boolean;
}
/**
* Useful for visualizing and logging insights into what the Lit template system is doing.
*
* Compiled out of prod mode builds.
*/
const debugLogEvent = DEV_MODE
? (event: ReactiveUnstable.DebugLog.Entry) => {
const shouldEmit = (window as unknown as DebugLoggingWindow)
.emitLitDebugLogEvents;
if (!shouldEmit) {
return;
}
window.dispatchEvent(
new CustomEvent<ReactiveUnstable.DebugLog.Entry>('lit-debug', {
detail: event,
})
);
}
: undefined;
/*
* When using Closure Compiler, JSCompiler_renameProperty(property, object) is
* replaced at compile time by the munged name for object[property]. We cannot
* alias this function, so we have to use a small shim that has the same
* behavior when not compiling.
*/
/*@__INLINE__*/
const JSCompiler_renameProperty = <P extends PropertyKey>(
prop: P,
_obj: unknown
): P => prop;
/**
* Converts property values to and from attribute values.
*/
export interface ComplexAttributeConverter<Type = unknown, TypeHint = unknown> {
/**
* Called to convert an attribute value to a property
* value.
*/
fromAttribute?(value: string | null, type?: TypeHint): Type;
/**
* Called to convert a property value to an attribute
* value.
*
* It returns unknown instead of string, to be compatible with
* https://github.com/WICG/trusted-types (and similar efforts).
*/
toAttribute?(value: Type, type?: TypeHint): unknown;
}
type AttributeConverter<Type = unknown, TypeHint = unknown> =
| ComplexAttributeConverter<Type>
| ((value: string | null, type?: TypeHint) => Type);
/**
* Defines options for a property accessor.
*/
export interface PropertyDeclaration<Type = unknown, TypeHint = unknown> {
/**
* When set to `true`, indicates the property is internal private state. The
* property should not be set by users. When using TypeScript, this property
* should be marked as `private` or `protected`, and it is also a common
* practice to use a leading `_` in the name. The property is not added to
* `observedAttributes`.
*/
readonly state?: boolean;
/**
* Indicates how and whether the property becomes an observed attribute.
* If the value is `false`, the property is not added to `observedAttributes`.
* If true or absent, the lowercased property name is observed (e.g. `fooBar`
* becomes `foobar`). If a string, the string value is observed (e.g
* `attribute: 'foo-bar'`).
*/
readonly attribute?: boolean | string;
/**
* Indicates the type of the property. This is used only as a hint for the
* `converter` to determine how to convert the attribute
* to/from a property.
*/
readonly type?: TypeHint;
/**
* Indicates how to convert the attribute to/from a property. If this value
* is a function, it is used to convert the attribute value a the property
* value. If it's an object, it can have keys for `fromAttribute` and
* `toAttribute`. If no `toAttribute` function is provided and
* `reflect` is set to `true`, the property value is set directly to the
* attribute. A default `converter` is used if none is provided; it supports
* `Boolean`, `String`, `Number`, `Object`, and `Array`. Note,
* when a property changes and the converter is used to update the attribute,
* the property is never updated again as a result of the attribute changing,
* and vice versa.
*/
readonly converter?: AttributeConverter<Type, TypeHint>;
/**
* Indicates if the property should reflect to an attribute.
* If `true`, when the property is set, the attribute is set using the
* attribute name determined according to the rules for the `attribute`
* property option and the value of the property converted using the rules
* from the `converter` property option.
*/
readonly reflect?: boolean;
/**
* A function that indicates if a property should be considered changed when
* it is set. The function should take the `newValue` and `oldValue` and
* return `true` if an update should be requested.
*/
hasChanged?(value: Type, oldValue: Type): boolean;
/**
* Indicates whether an accessor will be created for this property. By
* default, an accessor will be generated for this property that requests an
* update when set. If this flag is `true`, no accessor will be created, and
* it will be the user's responsibility to call
* `this.requestUpdate(propertyName, oldValue)` to request an update when
* the property changes.
*/
readonly noAccessor?: boolean;
}
/**
* Map of properties to PropertyDeclaration options. For each property an
* accessor is made, and the property is processed according to the
* PropertyDeclaration options.
*/
export interface PropertyDeclarations {
readonly [key: string]: PropertyDeclaration;
}
type PropertyDeclarationMap = Map<PropertyKey, PropertyDeclaration>;
type AttributeMap = Map<string, PropertyKey>;
/**
* A Map of property keys to values.
*
* Takes an optional type parameter T, which when specified as a non-any,
* non-unknown type, will make the Map more strongly-typed, associating the map
* keys with their corresponding value type on T.
*
* Use `PropertyValues<this>` when overriding ReactiveElement.update() and
* other lifecycle methods in order to get stronger type-checking on keys
* and values.
*/
// This type is conditional so that if the parameter T is not specified, or
// is `any`, the type will include `Map<PropertyKey, unknown>`. Since T is not
// given in the uses of PropertyValues in this file, all uses here fallback to
// meaning `Map<PropertyKey, unknown>`, but if a developer uses
// `PropertyValues<this>` (or any other value for T) they will get a
// strongly-typed Map type.
// eslint-disable-next-line @typescript-eslint/no-explicit-any
export type PropertyValues<T = any> = T extends object
? PropertyValueMap<T>
: Map<PropertyKey, unknown>;
/**
* Do not use, instead prefer {@linkcode PropertyValues}.
*/
// This type must be exported such that JavaScript generated by the Google
// Closure Compiler can import a type reference.
export interface PropertyValueMap<T> extends Map<PropertyKey, unknown> {
get<K extends keyof T>(k: K): T[K];
set<K extends keyof T>(key: K, value: T[K]): this;
has<K extends keyof T>(k: K): boolean;
delete<K extends keyof T>(k: K): boolean;
}
export const defaultConverter: ComplexAttributeConverter = {
toAttribute(value: unknown, type?: unknown): unknown {
switch (type) {
case Boolean:
value = value ? emptyStringForBooleanAttribute : null;
break;
case Object:
case Array:
// if the value is `null` or `undefined` pass this through
// to allow removing/no change behavior.
value = value == null ? value : JSON.stringify(value);
break;
}
return value;
},
fromAttribute(value: string | null, type?: unknown) {
let fromValue: unknown = value;
switch (type) {
case Boolean:
fromValue = value !== null;
break;
case Number:
fromValue = value === null ? null : Number(value);
break;
case Object:
case Array:
// Do *not* generate exception when invalid JSON is set as elements
// don't normally complain on being mis-configured.
// TODO(sorvell): Do generate exception in *dev mode*.
try {
// Assert to adhere to Bazel's "must type assert JSON parse" rule.
fromValue = JSON.parse(value!) as unknown;
} catch (e) {
fromValue = null;
}
break;
}
return fromValue;
},
};
export interface HasChanged {
(value: unknown, old: unknown): boolean;
}
/**
* Change function that returns true if `value` is different from `oldValue`.
* This method is used as the default for a property's `hasChanged` function.
*/
export const notEqual: HasChanged = (value: unknown, old: unknown): boolean => {
// This ensures (old==NaN, value==NaN) always returns false
return old !== value && (old === old || value === value);
};
const defaultPropertyDeclaration: PropertyDeclaration = {
attribute: true,
type: String,
converter: defaultConverter,
reflect: false,
hasChanged: notEqual,
};
/**
* The Closure JS Compiler doesn't currently have good support for static
* property semantics where "this" is dynamic (e.g.
* https://github.com/google/closure-compiler/issues/3177 and others) so we use
* this hack to bypass any rewriting by the compiler.
*/
const finalized = 'finalized';
/**
* A string representing one of the supported dev mode warning categories.
*/
export type WarningKind = 'change-in-update' | 'migration';
export type Initializer = (element: ReactiveElement) => void;
/**
* Base element class which manages element properties and attributes. When
* properties change, the `update` method is asynchronously called. This method
* should be supplied by subclassers to render updates as desired.
* @noInheritDoc
*/
export abstract class ReactiveElement
extends HTMLElement
implements ReactiveControllerHost
{
// Note: these are patched in only in DEV_MODE.
/**
* Read or set all the enabled warning categories for this class.
*
* This property is only used in development builds.
*
* @nocollapse
* @category dev-mode
*/
static enabledWarnings?: WarningKind[];
/**
* Enable the given warning category for this class.
*
* This method only exists in development builds, so it should be accessed
* with a guard like:
*
* ```ts
* // Enable for all ReactiveElement subclasses
* ReactiveElement.enableWarning?.('migration');
*
* // Enable for only MyElement and subclasses
* MyElement.enableWarning?.('migration');
* ```
*
* @nocollapse
* @category dev-mode
*/
static enableWarning?: (warningKind: WarningKind) => void;
/**
* Disable the given warning category for this class.
*
* This method only exists in development builds, so it should be accessed
* with a guard like:
*
* ```ts
* // Disable for all ReactiveElement subclasses
* ReactiveElement.disableWarning?.('migration');
*
* // Disable for only MyElement and subclasses
* MyElement.disableWarning?.('migration');
* ```
*
* @nocollapse
* @category dev-mode
*/
static disableWarning?: (warningKind: WarningKind) => void;
/**
* Adds an initializer function to the class that is called during instance
* construction.
*
* This is useful for code that runs against a `ReactiveElement`
* subclass, such as a decorator, that needs to do work for each
* instance, such as setting up a `ReactiveController`.
*
* ```ts
* const myDecorator = (target: typeof ReactiveElement, key: string) => {
* target.addInitializer((instance: ReactiveElement) => {
* // This is run during construction of the element
* new MyController(instance);
* });
* }
* ```
*
* Decorating a field will then cause each instance to run an initializer
* that adds a controller:
*
* ```ts
* class MyElement extends LitElement {
* @myDecorator foo;
* }
* ```
*
* Initializers are stored per-constructor. Adding an initializer to a
* subclass does not add it to a superclass. Since initializers are run in
* constructors, initializers will run in order of the class hierarchy,
* starting with superclasses and progressing to the instance's class.
*
* @nocollapse
*/
static addInitializer(initializer: Initializer) {
this._initializers ??= [];
this._initializers.push(initializer);
}
static _initializers?: Initializer[];
/*
* Due to closure compiler ES6 compilation bugs, @nocollapse is required on
* all static methods and properties with initializers. Reference:
* - https://github.com/google/closure-compiler/issues/1776
*/
/**
* Maps attribute names to properties; for example `foobar` attribute to
* `fooBar` property. Created lazily on user subclasses when finalizing the
* class.
* @nocollapse
*/
private static __attributeToPropertyMap: AttributeMap;
/**
* Marks class as having finished creating properties.
*/
protected static [finalized] = true;
/**
* Memoized list of all element properties, including any superclass properties.
* Created lazily on user subclasses when finalizing the class.
* @nocollapse
* @category properties
*/
static elementProperties: PropertyDeclarationMap = new Map();
/**
* User-supplied object that maps property names to `PropertyDeclaration`
* objects containing options for configuring reactive properties. When
* a reactive property is set the element will update and render.
*
* By default properties are public fields, and as such, they should be
* considered as primarily settable by element users, either via attribute or
* the property itself.
*
* Generally, properties that are changed by the element should be private or
* protected fields and should use the `state: true` option. Properties
* marked as `state` do not reflect from the corresponding attribute
*
* However, sometimes element code does need to set a public property. This
* should typically only be done in response to user interaction, and an event
* should be fired informing the user; for example, a checkbox sets its
* `checked` property when clicked and fires a `changed` event. Mutating
* public properties should typically not be done for non-primitive (object or
* array) properties. In other cases when an element needs to manage state, a
* private property set with the `state: true` option should be used. When
* needed, state properties can be initialized via public properties to
* facilitate complex interactions.
* @nocollapse
* @category properties
*/
static properties: PropertyDeclarations;
/**
* Memoized list of all element styles.
* Created lazily on user subclasses when finalizing the class.
* @nocollapse
* @category styles
*/
static elementStyles: Array<CSSResultOrNative> = [];
/**
* Array of styles to apply to the element. The styles should be defined
* using the {@linkcode css} tag function, via constructible stylesheets, or
* imported from native CSS module scripts.
*
* Note on Content Security Policy:
*
* Element styles are implemented with `<style>` tags when the browser doesn't
* support adopted StyleSheets. To use such `<style>` tags with the style-src
* CSP directive, the style-src value must either include 'unsafe-inline' or
* 'nonce-<base64-value>' with <base64-value> replaced be a server-generated
* nonce.
*
* To provide a nonce to use on generated <style> elements, set
* `window.litNonce` to a server-generated nonce in your page's HTML, before
* loading application code:
*
* ```html
* <script>
* // Generated and unique per request:
* window.litNonce = 'a1b2c3d4';
* </script>
* ```
* @nocollapse
* @category styles
*/
static styles?: CSSResultGroup;
/**
* The set of properties defined by this class that caused an accessor to be
* added during `createProperty`.
* @nocollapse
*/
private static __reactivePropertyKeys?: Set<PropertyKey>;
/**
* Returns a list of attributes corresponding to the registered properties.
* @nocollapse
* @category attributes
*/
static get observedAttributes() {
// note: piggy backing on this to ensure we're finalized.
this.finalize();
const attributes: string[] = [];
// Use forEach so this works even if for/of loops are compiled to for loops
// expecting arrays
this.elementProperties.forEach((v, p) => {
const attr = this.__attributeNameForProperty(p, v);
if (attr !== undefined) {
this.__attributeToPropertyMap.set(attr, p);
attributes.push(attr);
}
});
return attributes;
}
/**
* Creates a property accessor on the element prototype if one does not exist
* and stores a {@linkcode PropertyDeclaration} for the property with the
* given options. The property setter calls the property's `hasChanged`
* property option or uses a strict identity check to determine whether or not
* to request an update.
*
* This method may be overridden to customize properties; however,
* when doing so, it's important to call `super.createProperty` to ensure
* the property is setup correctly. This method calls
* `getPropertyDescriptor` internally to get a descriptor to install.
* To customize what properties do when they are get or set, override
* `getPropertyDescriptor`. To customize the options for a property,
* implement `createProperty` like this:
*
* ```ts
* static createProperty(name, options) {
* options = Object.assign(options, {myOption: true});
* super.createProperty(name, options);
* }
* ```
*
* @nocollapse
* @category properties
*/
static createProperty(
name: PropertyKey,
options: PropertyDeclaration = defaultPropertyDeclaration
) {
// if this is a state property, force the attribute to false.
if (options.state) {
// Cast as any since this is readonly.
// eslint-disable-next-line @typescript-eslint/no-explicit-any
(options as any).attribute = false;
}
// Note, since this can be called by the `@property` decorator which
// is called before `finalize`, we ensure finalization has been kicked off.
this.finalize();
this.elementProperties.set(name, options);
// Do not generate an accessor if the prototype already has one, since
// it would be lost otherwise and that would never be the user's intention;
// Instead, we expect users to call `requestUpdate` themselves from
// user-defined accessors. Note that if the super has an accessor we will
// still overwrite it
if (!options.noAccessor && !this.prototype.hasOwnProperty(name)) {
const key = typeof name === 'symbol' ? Symbol() : `__${name}`;
const descriptor = this.getPropertyDescriptor(name, key, options);
if (descriptor !== undefined) {
Object.defineProperty(this.prototype, name, descriptor);
if (DEV_MODE) {
// If this class doesn't have its own set, create one and initialize
// with the values in the set from the nearest ancestor class, if any.
if (!this.hasOwnProperty('__reactivePropertyKeys')) {
this.__reactivePropertyKeys = new Set(
this.__reactivePropertyKeys ?? []
);
}
this.__reactivePropertyKeys!.add(name);
}
}
}
}
/**
* Returns a property descriptor to be defined on the given named property.
* If no descriptor is returned, the property will not become an accessor.
* For example,
*
* ```ts
* class MyElement extends LitElement {
* static getPropertyDescriptor(name, key, options) {
* const defaultDescriptor =
* super.getPropertyDescriptor(name, key, options);
* const setter = defaultDescriptor.set;
* return {
* get: defaultDescriptor.get,
* set(value) {
* setter.call(this, value);
* // custom action.
* },
* configurable: true,
* enumerable: true
* }
* }
* }
* ```
*
* @nocollapse
* @category properties
*/
protected static getPropertyDescriptor(
name: PropertyKey,
key: string | symbol,
options: PropertyDeclaration
): PropertyDescriptor | undefined {
return {
// eslint-disable-next-line @typescript-eslint/no-explicit-any
get(): any {
return (this as {[key: string]: unknown})[key as string];
},
set(this: ReactiveElement, value: unknown) {
const oldValue = (this as {} as {[key: string]: unknown})[
name as string
];
(this as {} as {[key: string]: unknown})[key as string] = value;
(this as unknown as ReactiveElement).requestUpdate(
name,
oldValue,
options
);
},
configurable: true,
enumerable: true,
};
}
/**
* Returns the property options associated with the given property.
* These options are defined with a `PropertyDeclaration` via the `properties`
* object or the `@property` decorator and are registered in
* `createProperty(...)`.
*
* Note, this method should be considered "final" and not overridden. To
* customize the options for a given property, override
* {@linkcode createProperty}.
*
* @nocollapse
* @final
* @category properties
*/
static getPropertyOptions(name: PropertyKey) {
return this.elementProperties.get(name) || defaultPropertyDeclaration;
}
/**
* Creates property accessors for registered properties, sets up element
* styling, and ensures any superclasses are also finalized. Returns true if
* the element was finalized.
* @nocollapse
*/
protected static finalize() {
if (this.hasOwnProperty(finalized)) {
return false;
}
this[finalized] = true;
// finalize any superclasses
const superCtor = Object.getPrototypeOf(this) as typeof ReactiveElement;
superCtor.finalize();
this.elementProperties = new Map(superCtor.elementProperties);
// initialize Map populated in observedAttributes
this.__attributeToPropertyMap = new Map();
// make any properties
// Note, only process "own" properties since this element will inherit
// any properties defined on the superClass, and finalization ensures
// the entire prototype chain is finalized.
if (this.hasOwnProperty(JSCompiler_renameProperty('properties', this))) {
const props = this.properties;
// support symbols in properties (IE11 does not support this)
const propKeys = [
...Object.getOwnPropertyNames(props),
...Object.getOwnPropertySymbols(props),
];
// This for/of is ok because propKeys is an array
for (const p of propKeys) {
// note, use of `any` is due to TypeScript lack of support for symbol in
// index types
// eslint-disable-next-line @typescript-eslint/no-explicit-any
this.createProperty(p, (props as any)[p]);
}
}
this.elementStyles = this.finalizeStyles(this.styles);
// DEV mode warnings
if (DEV_MODE) {
const warnRemovedOrRenamed = (name: string, renamed = false) => {
if (this.prototype.hasOwnProperty(name)) {
issueWarning(
renamed ? 'renamed-api' : 'removed-api',
`\`${name}\` is implemented on class ${this.name}. It ` +
`has been ${renamed ? 'renamed' : 'removed'} ` +
`in this version of LitElement.`
);
}
};
warnRemovedOrRenamed('initialize');
warnRemovedOrRenamed('requestUpdateInternal');
warnRemovedOrRenamed('_getUpdateComplete', true);
}
return true;
}
/**
* Options used when calling `attachShadow`. Set this property to customize
* the options for the shadowRoot; for example, to create a closed
* shadowRoot: `{mode: 'closed'}`.
*
* Note, these options are used in `createRenderRoot`. If this method
* is customized, options should be respected if possible.
* @nocollapse
* @category rendering
*/
static shadowRootOptions: ShadowRootInit = {mode: 'open'};
/**
* Takes the styles the user supplied via the `static styles` property and
* returns the array of styles to apply to the element.
* Override this method to integrate into a style management system.
*
* Styles are deduplicated preserving the _last_ instance in the list. This
* is a performance optimization to avoid duplicated styles that can occur
* especially when composing via subclassing. The last item is kept to try
* to preserve the cascade order with the assumption that it's most important
* that last added styles override previous styles.
*
* @nocollapse
* @category styles
*/
protected static finalizeStyles(
styles?: CSSResultGroup
): Array<CSSResultOrNative> {
const elementStyles = [];
if (Array.isArray(styles)) {
// Dedupe the flattened array in reverse order to preserve the last items.
// Casting to Array<unknown> works around TS error that
// appears to come from trying to flatten a type CSSResultArray.
const set = new Set((styles as Array<unknown>).flat(Infinity).reverse());
// Then preserve original order by adding the set items in reverse order.
for (const s of set) {
elementStyles.unshift(getCompatibleStyle(s as CSSResultOrNative));
}
} else if (styles !== undefined) {
elementStyles.push(getCompatibleStyle(styles));
}
return elementStyles;
}
/**
* Node or ShadowRoot into which element DOM should be rendered. Defaults
* to an open shadowRoot.
* @category rendering
*/
readonly renderRoot!: HTMLElement | ShadowRoot;
/**
* Returns the property name for the given attribute `name`.
* @nocollapse
*/
private static __attributeNameForProperty(
name: PropertyKey,
options: PropertyDeclaration
) {
const attribute = options.attribute;
return attribute === false
? undefined
: typeof attribute === 'string'
? attribute
: typeof name === 'string'
? name.toLowerCase()
: undefined;
}
private __instanceProperties?: PropertyValues = new Map();
// Initialize to an unresolved Promise so we can make sure the element has
// connected before first update.
private __updatePromise!: Promise<boolean>;
/**
* True if there is a pending update as a result of calling `requestUpdate()`.
* Should only be read.
* @category updates
*/
isUpdatePending = false;
/**
* Is set to `true` after the first update. The element code cannot assume
* that `renderRoot` exists before the element `hasUpdated`.
* @category updates
*/
hasUpdated = false;
/**
* Map with keys for any properties that have changed since the last
* update cycle with previous values.
*
* @internal
*/
_$changedProperties!: PropertyValues;
/**
* Map with keys of properties that should be reflected when updated.
*/
private __reflectingProperties?: Map<PropertyKey, PropertyDeclaration>;
/**
* Name of currently reflecting property
*/
private __reflectingProperty: PropertyKey | null = null;
/**
* Set of controllers.
*/
private __controllers?: ReactiveController[];
constructor() {
super();
this._initialize();
}
/**
* Internal only override point for customizing work done when elements
* are constructed.
*
* @internal
*/
_initialize() {
this.__updatePromise = new Promise<boolean>(
(res) => (this.enableUpdating = res)
);
this._$changedProperties = new Map();
this.__saveInstanceProperties();
// ensures first update will be caught by an early access of
// `updateComplete`
this.requestUpdate();
(this.constructor as typeof ReactiveElement)._initializers?.forEach((i) =>
i(this)
);
}
/**
* Registers a `ReactiveController` to participate in the element's reactive
* update cycle. The element automatically calls into any registered
* controllers during its lifecycle callbacks.
*
* If the element is connected when `addController()` is called, the
* controller's `hostConnected()` callback will be immediately called.
* @category controllers
*/
addController(controller: ReactiveController) {
(this.__controllers ??= []).push(controller);
// If a controller is added after the element has been connected,
// call hostConnected. Note, re-using existence of `renderRoot` here
// (which is set in connectedCallback) to avoid the need to track a
// first connected state.
if (this.renderRoot !== undefined && this.isConnected) {
controller.hostConnected?.();
}
}
/**
* Removes a `ReactiveController` from the element.
* @category controllers
*/
removeController(controller: ReactiveController) {
// Note, if the indexOf is -1, the >>> will flip the sign which makes the
// splice do nothing.
this.__controllers?.splice(this.__controllers.indexOf(controller) >>> 0, 1);
}
/**
* Fixes any properties set on the instance before upgrade time.
* Otherwise these would shadow the accessor and break these properties.
* The properties are stored in a Map which is played back after the
* constructor runs. Note, on very old versions of Safari (<=9) or Chrome
* (<=41), properties created for native platform properties like (`id` or
* `name`) may not have default values set in the element constructor. On
* these browsers native properties appear on instances and therefore their
* default value will overwrite any element default (e.g. if the element sets
* this.id = 'id' in the constructor, the 'id' will become '' since this is
* the native platform default).
*/
private __saveInstanceProperties() {
// Use forEach so this works even if for/of loops are compiled to for loops
// expecting arrays
(this.constructor as typeof ReactiveElement).elementProperties.forEach(
(_v, p) => {
if (this.hasOwnProperty(p)) {
this.__instanceProperties!.set(p, this[p as keyof this]);
delete this[p as keyof this];
}
}
);
}
/**
* Returns the node into which the element should render and by default
* creates and returns an open shadowRoot. Implement to customize where the
* element's DOM is rendered. For example, to render into the element's
* childNodes, return `this`.
*
* @return Returns a node into which to render.
* @category rendering
*/
protected createRenderRoot(): Element | ShadowRoot {
const renderRoot =
this.shadowRoot ??
this.attachShadow(
(this.constructor as typeof ReactiveElement).shadowRootOptions
);
adoptStyles(