/**
* @license
* Copyright 2019 Google LLC
* SPDX-License-Identifier: BSD-3-Clause
*/
import {ElementInternalsShim} from './lib/element-internals.js';
import {EventShim, CustomEventShim} from './lib/events.js';
export {
ariaMixinAttributes,
ElementInternals,
HYDRATE_INTERNALS_ATTR_PREFIX,
} from './lib/element-internals.js';
export {
CSSRule,
CSSRuleList,
CSSStyleSheet,
MediaList,
StyleSheet,
} from './lib/css.js';
export {CustomEvent, Event} from './lib/events.js';
export {
IntersectionObserver,
MutationObserver,
ResizeObserver,
} from './lib/observers.js';
// In an empty Node.js vm, we need to patch the global context.
// TODO: Remove these globalThis assignments when we remove support
// for vm modules (--experimental-vm-modules).
globalThis.Event ??= EventShim;
globalThis.CustomEvent ??= CustomEventShim;
const constructionToken = Symbol();
/**
* Internal type to be used for the event polyfill functionality.
* @deprecated Use EventTargetShimMeta directly, if needed.
*/
export type HTMLElementWithEventMeta = HTMLElement & EventTargetShimMeta;
/**
* Properties necessary for the EventTarget shim to work.
*/
export interface EventTargetShimMeta {
/**
* The event target parent represents the previous event target for an event
* in capture phase and the next event target for a bubbling event.
* Note that this is not the element parent
*/
__eventTargetParent?: globalThis.EventTarget;
/**
* The host event target/element of this event target, if this event target
* is inside a Shadow DOM.
*/
__host?: globalThis.EventTarget;
/**
* A map of slot name to the corresponding slot element.
* For named slots, the key is the name of the slot and for
* the unnamed slot, the key is `undefined`.
*
* These need to be tracked explicitly since the slot elements are not
* necessarily in the same tree as the event target, so they can't be found
* by traversing the event path. This is needed to properly retarget events
* dispatched on slotted nodes.
*
*
* #shadow-dom (open)
*
*
* #shadow-dom (closed)
*
*
*
*
*
*
* With the above example the shadow DOM of `` is rendered before the
* child elements of ``, so when the slot elements are rendered, they
* are added and subsequently removed from the eventTargetStack and when
* `` is rendered it cannot solely rely on the eventTargetStack
* and need to check for each custom element in the stack if it has a slot
* with the name of the slot it is trying to fill.
*/
__slots?: Map;
}
const isCaptureEventListener = (
options: undefined | AddEventListenerOptions | boolean
) => (typeof options === 'boolean' ? options : (options?.capture ?? false));
const enumerableProperty: Record = {__proto__: null};
enumerableProperty.enumerable = true;
Object.freeze(enumerableProperty);
/**
* This is a basic implementation of an EventTarget.
*
* This is not fully spec compliant (e.g. validation),
* but should work well enough for our use cases.
*
* @see https://dom.spec.whatwg.org/#eventtarget
*
* Example Event Path
* ------------------
*
* Note that this depends on the logic in `packages/labs/ssr/src/lib/render-value.ts`.
* Any element that is not a custom element or a slot element is skipped in the chain.
*
*
*
* #shadow-dom (open)
*
*
*
* #shadow-dom (closed)
*
*
*
*
*
*
*
*
*
*
* Given the previous structure, the event path of this shim would be as follows,
* for the given dispatcher with an event that bubbles (document-fragment
* represents a ShadowRoot/#shadow-dom instance):
*
* :
* [event-dispatcher1, slot{my-el1}, document-fragment{my-el1}, my-el1, document]
*
* :
* [
* event-dispatcher2,
* slot[name="nested"]{my-el1},
* slot{my-el2},
* document-fragment{my-el2},
* my-el2,
* document-fragment{my-el1},
* my-el1,
* document
* ]
*
* (without composed):
* [event-dispatcher3, document-fragment{my-el2}]
*
* (composed):
* [
* event-dispatcher3,
* document-fragment{my-el2},
* my-el2,
* document-fragment{my-el1},
* my-el1,
* document
* ]
*/
class EventTarget implements globalThis.EventTarget, EventTargetShimMeta {
private __eventListeners = new Map<
string,
Map
>();
private __captureEventListeners = new Map<
string,
Map
>();
private __eventPathCache?: EventTarget[];
__eventTargetParent?: EventTarget;
__host?: EventTarget;
__slots?: Map;
addEventListener(
type: string,
callback: EventListenerOrEventListenerObject | null,
options?: AddEventListenerOptions | boolean
): void {
if (callback === undefined || callback === null) {
return;
}
const eventListenersMap = isCaptureEventListener(options)
? this.__captureEventListeners
: this.__eventListeners;
let eventListeners = eventListenersMap.get(type);
if (eventListeners === undefined) {
eventListeners = new Map();
eventListenersMap.set(type, eventListeners);
} else if (eventListeners.has(callback)) {
return;
}
const normalizedOptions =
typeof options === 'object' && options ? options : {};
normalizedOptions.signal?.addEventListener('abort', () =>
this.removeEventListener(type, callback, options)
);
eventListeners.set(callback, normalizedOptions ?? {});
}
removeEventListener(
type: string,
callback: EventListenerOrEventListenerObject | null,
options?: EventListenerOptions | boolean
): void {
if (callback === undefined || callback === null) {
return;
}
const eventListenersMap = isCaptureEventListener(options)
? this.__captureEventListeners
: this.__eventListeners;
const eventListeners = eventListenersMap.get(type);
if (eventListeners !== undefined) {
eventListeners.delete(callback);
if (!eventListeners.size) {
eventListenersMap.delete(type);
}
}
}
dispatchEvent(event: Event): boolean {
let composedPath = this.__resolveFullEventPath();
if (!event.composed && this.__host) {
// If the event is not composed and the event was dispatched inside
// shadow DOM, we need to stop the event chain before the host of the
// shadow DOM.
composedPath = composedPath.slice(0, composedPath.indexOf(this.__host));
}
// We need to patch various properties that would either be empty or wrong
// in this scenario.
let stopPropagation = false;
let stopImmediatePropagation = false;
let eventPhase: number = EventShim.NONE;
let target: EventTarget | null = null;
let tmpTarget: EventTarget | null = null;
let currentTarget: EventTarget | null = null;
const originalStopPropagation = event.stopPropagation;
const originalStopImmediatePropagation = event.stopImmediatePropagation;
Object.defineProperties(event, {
target: {
get() {
return target ?? tmpTarget;
},
...enumerableProperty,
},
srcElement: {
get() {
return event.target;
},
...enumerableProperty,
},
currentTarget: {
get() {
return currentTarget;
},
...enumerableProperty,
},
eventPhase: {
get() {
return eventPhase;
},
...enumerableProperty,
},
composedPath: {
value: () => composedPath,
...enumerableProperty,
},
stopPropagation: {
value: () => {
stopPropagation = true;
originalStopPropagation.call(event);
},
...enumerableProperty,
},
stopImmediatePropagation: {
value: () => {
stopImmediatePropagation = true;
originalStopImmediatePropagation.call(event);
},
...enumerableProperty,
},
});
// An event handler can either be a function, an object with a handleEvent
// method or null. This function takes care to call the event handler
// correctly.
const invokeEventListener = (
listener: EventListenerOrEventListenerObject,
options: AddEventListenerOptions,
eventListenerMap: Map<
EventListenerOrEventListenerObject,
AddEventListenerOptions
>
) => {
if (typeof listener === 'function') {
listener(event);
} else if (typeof listener?.handleEvent === 'function') {
listener.handleEvent(event);
}
if (options.once) {
eventListenerMap.delete(listener);
}
};
// When an event is finished being dispatched, which can be after the event
// tree has been traversed or stopPropagation/stopImmediatePropagation has
// been called. Once that is the case, the currentTarget and eventPhase
// need to be reset and a value, representing whether the event has not
// been prevented, needs to be returned.
const finishDispatch = () => {
currentTarget = null;
eventPhase = EventShim.NONE;
return !event.defaultPrevented;
};
// An event starts with the capture order, where it starts from the top.
// This is done even if bubbles is set to false, which is the default.
const captureEventPath = composedPath.slice().reverse();
// If the event target, which dispatches the event, is either in the light DOM
// or the event is not composed, the target is always itself. If that is not
// the case, the target needs to be retargeted: https://dom.spec.whatwg.org/#retarget
target = !this.__host || !event.composed ? this : null;
const retarget = (eventTargets: EventTarget[]) => {
// eslint-disable-next-line @typescript-eslint/no-this-alias
tmpTarget = this;
while (tmpTarget.__host && eventTargets.includes(tmpTarget.__host)) {
tmpTarget = tmpTarget.__host;
}
};
for (const eventTarget of captureEventPath) {
if (!target && (!tmpTarget || tmpTarget === eventTarget.__host)) {
retarget(captureEventPath.slice(captureEventPath.indexOf(eventTarget)));
}
currentTarget = eventTarget;
eventPhase =
eventTarget === event.target
? EventShim.AT_TARGET
: EventShim.CAPTURING_PHASE;
const captureEventListeners = eventTarget.__captureEventListeners.get(
event.type
);
if (captureEventListeners) {
for (const [listener, options] of captureEventListeners) {
invokeEventListener(listener, options, captureEventListeners);
if (stopImmediatePropagation) {
// Event.stopImmediatePropagation() stops any following invocation
// of an event handler even on the same event target.
return finishDispatch();
}
}
}
if (stopPropagation) {
// Event.stopPropagation() stops any following invocation
// of an event handler for any following event targets.
return finishDispatch();
}
}
const bubbleEventPath = event.bubbles ? composedPath : [this];
tmpTarget = null;
for (const eventTarget of bubbleEventPath) {
if (
!target &&
(!tmpTarget || eventTarget === (tmpTarget as EventTarget).__host)
) {
retarget(
bubbleEventPath.slice(0, bubbleEventPath.indexOf(eventTarget) + 1)
);
}
currentTarget = eventTarget;
eventPhase =
eventTarget === event.target
? EventShim.AT_TARGET
: EventShim.BUBBLING_PHASE;
const eventListeners = eventTarget.__eventListeners.get(event.type);
if (eventListeners) {
for (const [listener, options] of eventListeners) {
invokeEventListener(listener, options, eventListeners);
if (stopImmediatePropagation) {
// Event.stopImmediatePropagation() stops any following invocation
// of an event handler even on the same event target.
return finishDispatch();
}
}
}
if (stopPropagation) {
// Event.stopPropagation() stops any following invocation
// of an event handler for any following event targets.
return finishDispatch();
}
}
return finishDispatch();
}
private __resolveFullEventPath(): EventTarget[] {
if (this.__eventPathCache) {
return this.__eventPathCache;
} else if (!this.__eventTargetParent) {
return (this.__eventPathCache = [this, documentShim, windowShim]);
} else {
return (this.__eventPathCache = [
this,
...this.__eventTargetParent.__resolveFullEventPath(),
]);
}
}
}
const EventTargetShimWithRealType =
EventTarget as object as typeof globalThis.EventTarget;
export {EventTargetShimWithRealType as EventTarget};
const attributes = new WeakMap<
InstanceType,
Map
>();
const attributesForElement = (
element: InstanceType
) => {
let attrs = attributes.get(element);
if (attrs === undefined) {
attributes.set(element, (attrs = new Map()));
}
return attrs;
};
// The typings around the exports below are a little funky:
//
// 1. We want the `name` of the shim classes to match the real ones at runtime,
// hence e.g. `class Element`.
// 2. We can't shadow the global types with a simple class declaration, because
// then we can't reference the global types for casting, hence e.g.
// `const ElementShim = class Element`.
// 3. We want to export the classes typed as the real ones, hence e.g.
// `const ElementShimWithRealType = ElementShim as object as typeof Element;`.
// 4. We want the exported names to match the real ones, hence e.g.
// `export {ElementShimWithRealType as Element}`.
const NodeShim = class Node extends EventTarget {
getRootNode(options?: GetRootNodeOptions): globalThis.Node {
if (options?.composed) {
return document;
}
// getRootNode returns the containing ShadowRoot instance, even if that was
// created in closed mode.
const host = (this as Partial).__host as
| typeof ElementShim
| undefined;
return (
(host as {__shadowRoot?: null | ShadowRoot})?.__shadowRoot ?? document
);
}
};
const NodeShimWithRealType = NodeShim as object as typeof Node;
export {NodeShimWithRealType as Node};
type DocumentInterface = Document;
const DocumentShim = class Document
extends NodeShim
implements Partial
{
get adoptedStyleSheets() {
return [];
}
createTreeWalker() {
return {} as TreeWalker;
}
createTextNode() {
return {} as Text;
}
createElement() {
return {} as HTMLElement;
}
};
const DocumentShimWithRealType = DocumentShim as object as typeof Document;
export {DocumentShimWithRealType as Document};
const documentShim = new DocumentShim();
const document: Document = documentShim as object as typeof document;
export {document};
type WindowInterface = Window;
const WindowShim = class Window
extends NodeShim
implements Partial
{
[index: number]: WindowInterface;
constructor();
/**
* @internal
*/
constructor(constructionToken: Symbol);
constructor(token?: Symbol) {
super();
if (token !== constructionToken) {
throw new TypeError('Illegal constructor');
}
Object.assign(this, globalThis, {
CustomElementRegistry,
customElements,
document,
Document: DocumentShim,
Element: ElementShim,
EventTarget,
HTMLElement: HTMLElementShim,
Node: NodeShim,
ShadowRoot: ShadowRootShim,
window: this,
Window: WindowShim,
});
}
};
const WindowShimWithRealType = WindowShim as object as typeof Window;
export {WindowShimWithRealType as Window};
const ElementShim = class Element extends NodeShim {
get attributes() {
return Array.from(attributesForElement(this)).map(([name, value]) => ({
name,
value,
}));
}
private __shadowRootMode: null | ShadowRootMode = null;
protected __shadowRoot: null | ShadowRoot = null;
protected __internals: null | ElementInternals = null;
get shadowRoot() {
if (this.__shadowRootMode === 'closed') {
return null;
}
return this.__shadowRoot;
}
get localName() {
return (this.constructor as NamedCustomHTMLElementConstructor).__localName;
}
get tagName() {
return this.localName?.toUpperCase();
}
setAttribute(name: string, value: unknown): void {
// Emulate browser behavior that silently casts all values to string. E.g.
// `42` becomes `"42"` and `{}` becomes `"[object Object]""`.
attributesForElement(this).set(name, String(value));
}
removeAttribute(name: string) {
attributesForElement(this).delete(name);
}
toggleAttribute(name: string, force?: boolean): boolean {
// Steps reference https://dom.spec.whatwg.org/#dom-element-toggleattribute
if (this.hasAttribute(name)) {
// Step 5
if (force === undefined || !force) {
this.removeAttribute(name);
return false;
}
} else {
// Step 4
if (force === undefined || force) {
// Step 4.1
this.setAttribute(name, '');
return true;
} else {
// Step 4.2
return false;
}
}
// Step 6
return true;
}
hasAttribute(name: string) {
return attributesForElement(this).has(name);
}
attachShadow(init: ShadowRootInit): ShadowRoot {
this.__shadowRootMode = init.mode;
const shadowRoot: Partial & EventTargetShimMeta =
new ShadowRootShim(constructionToken, init);
shadowRoot.__eventTargetParent = this;
shadowRoot.__host = this;
return (this.__shadowRoot = shadowRoot as ShadowRootInterface);
}
attachInternals(): ElementInternals {
if (this.__internals !== null) {
throw new Error(
`Failed to execute 'attachInternals' on 'HTMLElement': ` +
`ElementInternals for the specified element was already attached.`
);
}
const internals = new ElementInternalsShim(this as unknown as HTMLElement);
this.__internals = internals;
return internals as ElementInternals;
}
getAttribute(name: string) {
const value = attributesForElement(this).get(name);
return value ?? null;
}
};
const ElementShimWithRealType = ElementShim as object as typeof Element;
export {ElementShimWithRealType as Element};
const HTMLElementShim = class HTMLElement extends ElementShim {};
const HTMLElementShimWithRealType =
HTMLElementShim as object as typeof HTMLElement;
export {HTMLElementShimWithRealType as HTMLElement};
const HTMLSlotElementShim = class HTMLSlotElement extends HTMLElementShim {
name!: string;
override get localName(): string {
return 'slot';
}
};
const HTMLSlotElementShimWithRealType =
HTMLSlotElementShim as object as typeof HTMLSlotElement;
export {HTMLSlotElementShimWithRealType as HTMLSlotElement};
type ShadowRootInterface = ShadowRoot;
const ShadowRootShim = class ShadowRoot
extends NodeShim
implements Partial
{
get host(): Element {
return (this as Partial).__host! as Element;
}
mode: 'open' | 'closed';
constructor();
/**
* @internal
*/
constructor(constructionToken: Symbol, init: ShadowRootInit);
constructor(constructionToken?: Symbol, init?: ShadowRootInit) {
super();
if (constructionToken !== constructionToken) {
throw new TypeError('Illegal constructor');
}
this.mode = init!.mode;
}
};
const ShadowRootShimWithRealType =
ShadowRootShim as object as typeof ShadowRoot;
export {ShadowRootShimWithRealType as ShadowRoot};
// For convenience, we provide a global instance of a HTMLElement as an event
// target. This facilitates registering global event handlers
// (e.g. for @lit/context ContextProvider).
// We use this in in the SSR render function.
// Note, this is a bespoke element and not simply `document` or `window` since
// user code relies on these being undefined in the server environment.
globalThis.litServerRoot ??= Object.defineProperty(
new HTMLElementShimWithRealType(),
'localName',
{
// Patch localName (and tagName) to return a unique name.
get() {
return 'lit-server-root';
},
}
);
interface CustomHTMLElementConstructor {
new (): HTMLElement;
observedAttributes?: string[];
}
interface NamedCustomHTMLElementConstructor
extends CustomHTMLElementConstructor {
__localName: string;
}
type CustomElementRegistration = {
ctor: {new (): HTMLElement};
observedAttributes: string[];
};
type RealCustomElementRegistry = (typeof globalThis)['customElements'];
type RealCustomElementRegistryClass =
(typeof globalThis)['CustomElementRegistry'];
// Ponyfill for PromiseWithResolvers, remove once we can assume its presence.
type PromiseWithResolvers = {
promise: Promise;
resolve: (value: T) => void;
reject: (reason?: unknown) => void;
};
function promiseWithResolvers(): PromiseWithResolvers {
let resolve: (value: T) => void;
let reject: (reason?: unknown) => void;
const promise = new Promise((res, rej) => {
resolve = res;
reject = rej;
});
return {promise, resolve: resolve!, reject: reject!};
}
class CustomElementRegistry implements RealCustomElementRegistry {
private __definitions = new Map();
private __reverseDefinitions = new Map<
CustomHTMLElementConstructor,
string
>();
private __pendingWhenDefineds = new Map<
string,
PromiseWithResolvers
>();
define(name: string, ctor: CustomHTMLElementConstructor) {
if (this.__definitions.has(name)) {
if (process.env.NODE_ENV === 'development') {
console.warn(
`'CustomElementRegistry' already has "${name}" defined. ` +
`This may have been caused by live reload or hot module ` +
`replacement in which case it can be safely ignored.\n` +
`Make sure to test your application with a production build as ` +
`repeat registrations will throw in production.`
);
} else {
throw new Error(
`Failed to execute 'define' on 'CustomElementRegistry': ` +
`the name "${name}" has already been used with this registry`
);
}
}
if (this.__reverseDefinitions.has(ctor)) {
throw new Error(
`Failed to execute 'define' on 'CustomElementRegistry': ` +
`the constructor has already been used with this registry for the ` +
`tag name ${this.__reverseDefinitions.get(ctor)}`
);
}
// Provide tagName and localName for the component.
(ctor as NamedCustomHTMLElementConstructor).__localName = name;
this.__definitions.set(name, {
ctor,
// Note it's important we read `observedAttributes` in case it is a getter
// with side-effects, as is the case in Lit, where it triggers class
// finalization.
//
// TODO(aomarks) To be spec compliant, we should also capture the
// registration-time lifecycle methods like `connectedCallback`. For them
// to be actually accessible to e.g. the Lit SSR element renderer, though,
// we'd need to introduce a new API for accessing them (since `get` only
// returns the constructor).
observedAttributes: ctor.observedAttributes ?? [],
});
this.__reverseDefinitions.set(ctor, name);
this.__pendingWhenDefineds.get(name)?.resolve(ctor);
this.__pendingWhenDefineds.delete(name);
}
get(name: string) {
const definition = this.__definitions.get(name);
return definition?.ctor;
}
getName(ctor: CustomHTMLElementConstructor) {
return this.__reverseDefinitions.get(ctor) ?? null;
}
initialize(_root: Node): void {
throw new Error(
`customElements.initialize is not currently supported in SSR. ` +
`Please file a bug if you need it.`
);
}
upgrade(_element: HTMLElement) {
// In SSR this doesn't make a lot of sense, so we do nothing.
throw new Error(
`customElements.upgrade is not currently supported in SSR. ` +
`Please file a bug if you need it.`
);
}
async whenDefined(name: string): Promise {
const definition = this.__definitions.get(name);
if (definition) {
return definition.ctor;
}
let withResolvers = this.__pendingWhenDefineds.get(name);
if (!withResolvers) {
withResolvers = promiseWithResolvers();
this.__pendingWhenDefineds.set(name, withResolvers);
}
return withResolvers.promise;
}
}
const CustomElementRegistryShimWithRealType =
CustomElementRegistry as object as RealCustomElementRegistryClass;
export {CustomElementRegistryShimWithRealType as CustomElementRegistry};
export const customElements = new CustomElementRegistryShimWithRealType();
// The window variable instantiation must happen after all shims
// have been declared, as they will be included in the window instance.
const windowShim = new WindowShim(constructionToken);
const window: Window = windowShim as object as typeof window;
export {window};