@riverty/web-components 6.3.0 → 6.3.1

package/dist/cjs/style-observer-D9zSP9wP.js

@@ -0,0 +1,1118 @@
+'use strict';
+
+// In Safari < 18.2, transitioning custom properties of syntax `*` or `<string>`
+// causes an infinite loop of `transitionrun` or `transitionstart` events.
+// We use this test to detect the bug.
+
+/**
+ * Detect if the browser is affected by the Safari transition loop bug.
+ * @see https://bugs.webkit.org/show_bug.cgi?id=279012
+ * @returns {Promise<boolean>}
+ */
+var TRANSITIONRUN_EVENT_LOOP = {
+	value: undefined,
+	get valuePending () {
+		if (this.value !== undefined) {
+			return this.value;
+		}
+
+		let dummy = document.createElement("div");
+		document.body.appendChild(dummy);
+		let property = "--bar-" + Date.now();
+		dummy.style.cssText = `${property}: 1; transition: ${property} 1ms step-start allow-discrete`;
+
+		delete this.valuePending;
+		return (this.valuePending = new Promise(resolve => {
+			let eventsCount = 0;
+			requestAnimationFrame(() => {
+				setTimeout(_ => resolve(eventsCount > 1), 50);
+				dummy.addEventListener("transitionrun", _ => eventsCount++);
+				dummy.style.setProperty(property, "2");
+			});
+		})
+			.then(v => (this.value = v))
+			.finally(() => dummy.remove()));
+	},
+};
+
+// Detect https://issues.chromium.org/issues/360159391
+
+/**
+ * Detect if the browser is affected by the unregistered transition bug.
+ * @see https://issues.chromium.org/issues/360159391
+ * @returns {Promise<boolean>}
+ */
+var UNREGISTERED_TRANSITION = {
+	value: undefined,
+	get valuePending () {
+		if (this.value !== undefined) {
+			return this.value;
+		}
+
+		let dummy = document.createElement("div");
+		document.body.appendChild(dummy);
+		let property = "--foo-" + Date.now();
+		dummy.style.cssText = `${property}: 1; transition: ${property} 1ms step-start allow-discrete`;
+
+		delete this.valuePending;
+		return (this.valuePending = new Promise(resolve => {
+			requestAnimationFrame(() => {
+				setTimeout(_ => resolve(true), 30);
+				dummy.addEventListener("transitionstart", _ => resolve(false));
+				dummy.style.setProperty(property, "2");
+			});
+		})
+			.then(v => (this.value = v))
+			.finally(() => dummy.remove()));
+	},
+};
+
+/**
+ * Check if a CSS custom property is registered.
+ * This function will return `false` for custom properties that behave identically to non-registered properties (e.g., registered inherited properties with syntax "*").
+ * @param {string} property - The property to check.
+ * @param {Window} [window] - The window to check in.
+ * @returns {boolean}
+ */
+function isRegisteredProperty (property, window = globalThis) {
+	let document = window.document;
+
+	let dummy = document.createElement("div");
+	document.body.append(dummy);
+
+	let invalidValue = "foo(bar)"; // a value that is invalid for any registered syntax
+	dummy.style.setProperty(property, invalidValue);
+	let value = getComputedStyle(dummy).getPropertyValue(property);
+
+	let ret = true;
+	if (value === invalidValue) {
+		// We might have either unregistered or registered custom property with syntax "*".
+		// If it's non-inherited, we can be sure it's registered.
+		// But if it's inherited, it's OK if we (re-)register it with syntax "*" in any case.
+		let child = dummy.appendChild(document.createElement("div"));
+		let inheritedValue = getComputedStyle(child).getPropertyValue(property);
+		ret = inheritedValue !== invalidValue;
+	}
+
+	dummy.remove();
+
+	return ret;
+}
+
+const INITIAL_VALUES = {
+	"<angle>": "0deg",
+	"<color>": "transparent",
+	"<custom-ident>": "none",
+	"<image>": "linear-gradient(transparent 0% 100%)",
+	"<integer>": "0",
+	"<length>": "0px",
+	"<length-percentage>": "0px",
+	"<number>": "0",
+	"<percentage>": "0%",
+	"<resolution>": "1dppx",
+	"<string>": "''",
+	"<time>": "0s",
+	"<transform-function>": "scale(1)",
+	"<transform-list>": "scale(1)",
+	"<url>": "url('')",
+};
+
+/**
+ * Register a CSS custom property if it’s not already registered.
+ * @param {string} property - Property name.
+ * @param {Object} [meta] - Property definition.
+ * @param {string} [meta.syntax] - Property syntax.
+ * @param {boolean} [meta.inherits] - Whether the property inherits.
+ * @param {*} [meta.initialValue] - Initial value.
+ * @param {Window} [window] - Window to register the property in.
+ */
+function gentleRegisterProperty (property, meta = {}, window = globalThis) {
+	if (
+		!property.startsWith("--") ||
+		!window.CSS?.registerProperty ||
+		isRegisteredProperty(property, window)
+	) {
+		return;
+	}
+
+	let definition = {
+		name: property,
+		syntax: meta.syntax || "*",
+		inherits: meta.inherits ?? true,
+	};
+
+	if (meta.initialValue !== undefined) {
+		definition.initialValue = meta.initialValue;
+	}
+	else if (definition.syntax !== "*" && definition.syntax in INITIAL_VALUES) {
+		definition.initialValue = INITIAL_VALUES[definition.syntax];
+	}
+
+	try {
+		window.CSS.registerProperty(definition);
+	}
+	catch (e) {
+		let error = e;
+		let rethrow = true;
+
+		if (e instanceof window.DOMException) {
+			if (e.name === "InvalidModificationError") {
+				// Property is already registered, which is fine
+				rethrow = false;
+			}
+			else if (e.name === "SyntaxError") {
+				// In Safari < 18.2 (where we face the infinite loop bug),
+				// there is no way to provide an initial value for a custom property with a syntax of "<string>".
+				// There will always be an error: “The given initial value does not parse for the given syntax.”
+				// So we try again with universal syntax.
+				// We do the same for any other syntax that is not supported.
+				definition.syntax = "*";
+
+				try {
+					window.CSS.registerProperty(definition);
+					rethrow = false;
+				}
+				catch (e) {
+					error = e;
+				}
+			}
+		}
+
+		if (rethrow) {
+			// Re-throw any other errors
+			throw new Error(`Failed to register custom property ${property}: ${error.message}`, {
+				cause: error,
+			});
+		}
+	}
+}
+
+/**
+ * Detect if the browser is affected by the Safari adopted style sheet bug:
+ * removing a CSS custom property from an adopted stylesheet in a ShadowRoot
+ * does not update the computed value as expected and doesn't trigger a transition.
+ * @returns {{value: boolean, valuePending: boolean}}
+ */
+var ADOPTED_STYLE_SHEET = {
+	get value () {
+		let dummy = document.createElement("div");
+		document.body.append(dummy);
+		dummy.attachShadow({ mode: "open" });
+
+		if (Object.isFrozen(dummy.shadowRoot.adoptedStyleSheets)) {
+			// The browser doesn't support the modern adoptedStyleSheets API, i.e., it is not affected by the bug
+			dummy.remove();
+			delete this.value;
+
+			return (this.value = false);
+		}
+
+		gentleRegisterProperty("--style-observer-adopted-style-sheet-bug", {
+			syntax: "<number>",
+			inherits: true,
+			initialValue: 0,
+		});
+
+		let sheet = new CSSStyleSheet();
+		sheet.insertRule(`
+			:host {
+				/* This declaration shouldn't be empty for the bug to trigger */
+				color: transparent;
+			}
+		`);
+
+		dummy.shadowRoot.adoptedStyleSheets.push(sheet);
+		let style = sheet.cssRules[0].style;
+
+		style.setProperty("--style-observer-adopted-style-sheet-bug", "1");
+		let cs = getComputedStyle(dummy);
+		let oldValue = cs.getPropertyValue("--style-observer-adopted-style-sheet-bug");
+
+		style.removeProperty("--style-observer-adopted-style-sheet-bug");
+		cs = getComputedStyle(dummy);
+		let newValue = cs.getPropertyValue("--style-observer-adopted-style-sheet-bug");
+
+		dummy.remove();
+		delete this.value;
+
+		return (this.value = oldValue === newValue);
+	},
+	get valuePending () {
+		delete this.valuePending;
+		return this.value;
+	},
+};
+
+const detectors = { TRANSITIONRUN_EVENT_LOOP, UNREGISTERED_TRANSITION, ADOPTED_STYLE_SHEET };
+
+/**
+ * Data structure for all detected bugs.
+ * All bugs start off as true, and once their promises resolve, that is replaced with the actual value
+ */
+const bugs = {
+	detectAll () {
+		return Promise.all(Object.values(detectors).map(detector => detector.valuePending));
+	},
+};
+
+for (let bug in detectors) {
+	let detector = detectors[bug];
+	Object.defineProperty(bugs, bug, {
+		get () {
+			if (detector.value !== undefined) {
+				delete detector.valuePending;
+				delete this[bug];
+
+				return (this[bug] = detector.value);
+			}
+
+			detector.valuePending.then(value => {
+				delete this[bug];
+				this[bug] = value;
+			});
+
+			// Until we know, assume the bug is present
+			return true;
+		},
+		configurable: true,
+		enumerable: true,
+	});
+}
+
+/**
+ * A WeakMap that maps keys to Sets of values, allowing multiple values per key.
+ */
+class MultiWeakMap extends WeakMap {
+	has (key, value) {
+		if (arguments.length === 1) {
+			return super.has(key);
+		}
+
+		let set = super.get(key);
+		return set?.has(value) || false;
+	}
+
+	add (key, value) {
+		let set = super.get(key) ?? new Set();
+		set.add(value);
+		super.set(key, set);
+	}
+
+	delete (key, ...values) {
+		let set = super.get(key);
+		if (set) {
+			for (let value of values) {
+				set.delete(value);
+			}
+
+			if (set.size === 0) {
+				super.delete(key);
+			}
+		}
+	}
+}
+
+/**
+ * Convert a value to an array. `undefined` and `null` values are converted to an empty array.
+ * @param {*} value - The value to convert.
+ * @returns {any[]} The converted array.
+ */
+function toArray (value) {
+	if (value === undefined || value === null) {
+		return [];
+	}
+
+	if (Array.isArray(value)) {
+		return value;
+	}
+
+	// Don't convert "foo" into ["f", "o", "o"]
+	if (typeof value !== "string" && typeof value[Symbol.iterator] === "function") {
+		return Array.from(value);
+	}
+
+	return [value];
+}
+
+/**
+ * Wait for a given number of milliseconds or a `requestAnimationFrame`.
+ * @param {number} ms - The number of milliseconds to wait.
+ * @returns {Promise<void>}
+ */
+function wait (ms) {
+	if (ms) {
+		return new Promise(resolve => setTimeout(resolve, ms));
+	}
+
+	return new Promise(resolve => requestAnimationFrame(resolve));
+}
+
+let dummy;
+
+/**
+ * Get the longhands for a given property.
+ * @param {string} property - The property to get the longhands for.
+ * @returns {string[]} The longhands.
+ * @see https://lea.verou.me/blog/2020/07/introspecting-css-via-the-css-om-getting-supported-properties-shorthands-longhands/
+ */
+function getLonghands (property) {
+	dummy ??= document.createElement("div");
+	let style = dummy.style;
+	style[property] = "inherit"; // a value that works in every property
+	let ret = [...style];
+
+	if (ret.length === 0) {
+		// Fallback, in case
+		ret = [property];
+	}
+
+	style.cssText = ""; // clean up
+
+	return ret;
+}
+
+/**
+ * Parse a CSS `<time>` value.
+ * @param {string } cssTime - A string that contains CSS `<time>` values.
+ * @return { number[] } Any times found, in milliseconds.
+ */
+function parseTimes (cssTime) {
+	let matches = cssTime.matchAll(/(?:^|\s)([+-]?(?:\d+|\d*\.\d+))\s*(ms|s)?(?=\s|$)/g);
+	let ret = [];
+
+	for (let match of matches) {
+		let [, value, unit] = match;
+		value = parseFloat(value);
+
+		if (unit === "s") {
+			value *= 1000;
+		}
+
+		ret.push(value);
+	}
+
+	return ret;
+}
+
+/**
+ * Get the duration and delay of a CSS transition for a given property.
+ * @param {string} property - The CSS property name.
+ * @param {string} transitions - The computed value of the `transition` property.
+ * @returns { { duration: number, delay: number } } The duration and delay, in milliseconds.
+ */
+function getTimesFor (property, transitions) {
+	transitions = splitCommas(transitions);
+	let propertyRegex;
+
+	if (property === "all") {
+		propertyRegex = /\b\w+\b/g;
+	}
+	else {
+		let properties = [...new Set([...getLonghands(property), property, "all"])];
+		propertyRegex = RegExp(`(?:^|\\s)(${properties.join("|")})\\b`);
+	}
+
+	let lastRelevantTransition = transitions.findLast(transition => propertyRegex.test(transition));
+	let times = lastRelevantTransition ? parseTimes(lastRelevantTransition) : [0, 0];
+
+	if (times.length === 0) {
+		times = [0, 0];
+	}
+	else if (times.length === 1) {
+		times.push(0);
+	}
+
+	let [duration, delay] = times;
+	return { duration, delay };
+}
+
+/**
+ * Split a value by commas, ignoring commas within parentheses and trimming whitespace.
+ * @param {string} value - The value to split.
+ * @returns {string[]} The split values.
+ */
+function splitCommas (value) {
+	let ret = [];
+	let lastIndex = 0;
+	let stack = [];
+
+	for (let match of value.matchAll(/[,()]/g)) {
+		let char = match[0];
+
+		if (char === ",") {
+			if (stack.length === 0) {
+				let item = value.slice(lastIndex, match.index);
+				ret.push(item.trim());
+				lastIndex = match.index + 1;
+			}
+		}
+		else if (char === "(") {
+			stack.push("(");
+		}
+		else if (char === ")") {
+			stack.pop();
+		}
+	}
+
+	if (lastIndex < value.length) {
+		// Push any remaining string
+		let item = value.slice(lastIndex);
+		ret.push(item.trim());
+	}
+
+	return ret;
+}
+
+/**
+ * Monitor the presence of an element in the document.
+ * This observer fires the callback in situations like:
+ * - The element is added to the DOM
+ * - The element gets slotted or its slot starts existing (but not when moved to another slot)
+ * - The element becomes visible from display: none
+ */
+
+class RenderedObserver {
+	/**
+	 * All currently observed targets
+	 * @type {WeakSet<Element>}
+	 */
+	#targets = new Set();
+
+	/**
+	 * Documents to IntersectionObserver instances
+	 * @type {WeakMap<Document, IntersectionObserver>}
+	 */
+	#intersectionObservers = new WeakMap();
+
+	constructor (callback) {
+		this.callback = callback;
+	}
+
+	/**
+	 * Begin observing the presence of an element.
+	 * @param {Element} element - The element to observe.
+	 */
+	observe (element) {
+		if (this.#targets.has(element)) {
+			// Already observing this element
+			return;
+		}
+
+		let doc = element.ownerDocument;
+		let io = this.#intersectionObservers.get(doc);
+
+		if (!io) {
+			io = new IntersectionObserver(
+				entries => {
+					this.callback(entries.map(({ target }) => ({ target })));
+				},
+				{ root: doc.documentElement },
+			);
+
+			this.#intersectionObservers.set(doc, io);
+		}
+
+		this.#targets.add(element);
+		io.observe(element);
+	}
+
+	/**
+	 * Stop observing the presence of an element.
+	 * @param {Element} [element] - The element to stop observing. If not provided, all targets will be unobserved.
+	 */
+	unobserve (element) {
+		if (!element) {
+			// Unobserve all targets
+			for (const target of this.#targets) {
+				this.unobserve(target);
+			}
+			return;
+		}
+
+		let doc = element.ownerDocument;
+		let io = this.#intersectionObservers.get(doc);
+
+		io?.unobserve(element);
+		this.#targets.delete(element);
+	}
+}
+
+const allowDiscrete = globalThis.CSS?.supports?.("transition-behavior", "allow-discrete")
+	? " allow-discrete"
+	: "";
+
+if (globalThis.document) {
+	gentleRegisterProperty("--style-observer-transition", { inherits: false });
+	bugs.detectAll();
+}
+
+/**
+ * @typedef { object } StyleObserverOptionsObject
+ * @property { string[] } properties - The properties to observe.
+ */
+/**
+ * @typedef { StyleObserverOptionsObject | string | string[] } StyleObserverOptions
+ */
+
+/**
+ * @callback StyleObserverCallback
+ * @param {Record[]} records
+ * @returns {void}
+ */
+
+/**
+ * @typedef { Object } Record
+ * @property {Element} target - The element that changed.
+ * @property {string} property - The property that changed.
+ * @property {string} value - The new value of the property.
+ * @property {string} oldValue - The old value of the property.
+ */
+
+class ElementStyleObserver {
+	/**
+	 * Observed properties to their old values.
+	 * @type {Map<string, string>}
+	 */
+	properties;
+
+	/**
+	 * Get the names of all properties currently being observed.
+	 * @type { string[] }
+	 */
+	get propertyNames () {
+		return [...this.properties.keys()];
+	}
+
+	/**
+	 * The element being observed.
+	 * @type {Element}
+	 */
+	target;
+
+	/**
+	 * The callback to call when the element's style changes.
+	 * @type {StyleObserverCallback}
+	 */
+	callback;
+
+	/**
+	 * The observer options.
+	 * @type {StyleObserverOptions}
+	 */
+	options;
+
+	/**
+	 * Whether the observer has been initialized.
+	 * @type {boolean}
+	 */
+	#initialized = false;
+
+	/**
+	 * @param {Element} target
+	 * @param {StyleObserverCallback} callback
+	 * @param {StyleObserverOptions} [options]
+	 */
+	constructor (target, callback, options = {}) {
+		this.constructor.all.add(target, this);
+		this.properties = new Map();
+		this.target = target;
+		this.callback = callback;
+		this.options = { properties: [], ...options };
+		let properties = toArray(options.properties);
+
+		this.renderedObserver = new RenderedObserver(records => {
+			if (this.propertyNames.length > 0) {
+				this.handleEvent();
+			}
+		});
+
+		if (properties.length > 0) {
+			this.observe(properties);
+		}
+	}
+
+	/**
+	 * Called the first time observe() is called to initialize the target.
+	 */
+	#init () {
+		if (this.#initialized) {
+			return;
+		}
+
+		let firstTime = this.constructor.all.get(this.target).size === 1;
+		this.updateTransition({ firstTime });
+
+		this.#initialized = true;
+	}
+
+	resolveOptions (options) {
+		return Object.assign(resolveOptions(options), this.options);
+	}
+
+	/**
+	 * Handle a potential property change
+	 * @private
+	 * @param {TransitionEvent} [event]
+	 */
+	async handleEvent (event) {
+		if (event && !this.properties.has(event.propertyName)) {
+			return;
+		}
+
+		if (
+			(bugs.TRANSITIONRUN_EVENT_LOOP && event?.type === "transitionrun") ||
+			this.options.throttle > 0
+		) {
+			let eventName = bugs.TRANSITIONRUN_EVENT_LOOP ? "transitionrun" : "transitionstart";
+			let delay = Math.max(this.options.throttle, 50);
+
+			if (bugs.TRANSITIONRUN_EVENT_LOOP) {
+				// Safari < 18.2 fires `transitionrun` events too often, so we need to debounce.
+				// Wait at least the amount of time needed for the transition to run + 1 frame (~16ms)
+				let times = getTimesFor(
+					event.propertyName,
+					getComputedStyle(this.target).transition,
+				);
+				delay = Math.max(delay, times.duration + times.delay + 16);
+			}
+
+			this.target.removeEventListener(eventName, this);
+			await wait(delay);
+			this.target.addEventListener(eventName, this);
+		}
+
+		let cs = getComputedStyle(this.target);
+		let records = [];
+
+		// Other properties may have changed in the meantime
+		for (let property of this.propertyNames) {
+			let value = cs.getPropertyValue(property);
+			let oldValue = this.properties.get(property);
+
+			if (value !== oldValue) {
+				records.push({ target: this.target, property, value, oldValue });
+				this.properties.set(property, value);
+			}
+		}
+
+		if (records.length > 0) {
+			this.callback(records);
+		}
+	}
+
+	/**
+	 * Observe the target for changes to one or more CSS properties.
+	 * @param {string | string[]} properties
+	 * @return {void}
+	 */
+	observe (properties) {
+		properties = toArray(properties);
+
+		// Drop properties already being observed
+		properties = properties.filter(property => !this.properties.has(property));
+
+		if (properties.length === 0) {
+			// Nothing new to observe
+			return;
+		}
+
+		this.#init();
+
+		let cs = getComputedStyle(this.target);
+
+		for (let property of properties) {
+			if (bugs.UNREGISTERED_TRANSITION && !this.constructor.properties.has(property)) {
+				// Init property
+				gentleRegisterProperty(property, undefined, this.target.ownerDocument.defaultView);
+				this.constructor.properties.add(property);
+			}
+
+			let value = cs.getPropertyValue(property);
+			this.properties.set(property, value);
+		}
+
+		if (bugs.TRANSITIONRUN_EVENT_LOOP) {
+			this.target.addEventListener("transitionrun", this);
+		}
+
+		this.target.addEventListener("transitionstart", this);
+		this.target.addEventListener("transitionend", this);
+		this.updateTransitionProperties();
+
+		this.renderedObserver.observe(this.target);
+	}
+
+	/**
+	 * Update the `--style-observer-transition` property to include all observed properties.
+	 */
+	updateTransitionProperties () {
+		// Clear our own transition
+		this.setProperty("--style-observer-transition", "");
+
+		let transitionProperties = new Set(
+			getComputedStyle(this.target).transitionProperty.split(", "),
+		);
+		let properties = [];
+
+		for (let observer of this.constructor.all.get(this.target)) {
+			properties.push(...observer.propertyNames);
+		}
+
+		properties = [...new Set(properties)]; // Dedupe
+
+		// Only add properties not already present
+		let transition = properties
+			.filter(property => !transitionProperties.has(property))
+			.map(property => `${property} 1ms step-start${allowDiscrete}`)
+			.join(", ");
+
+		this.setProperty("--style-observer-transition", transition);
+	}
+
+	/**
+	 * @type { string | undefined }
+	 */
+	#inlineTransition;
+
+	/**
+	 * Update the target's transition property or refresh it if it was overwritten.
+	 * @param {object} options
+	 * @param {boolean} [options.firstTime] - Whether this is the first time the transition is being set.
+	 */
+	updateTransition ({ firstTime } = {}) {
+		const sot = "var(--style-observer-transition, --style-observer-noop)";
+		const inlineTransition = this.getProperty("transition");
+		let transition;
+
+		// NOTE This code assumes that if there is an inline style, it takes precedence over other styles
+		// This is not always true (think of !important), but will do for now.
+		if (firstTime ? inlineTransition : !inlineTransition.includes(sot)) {
+			// Either we are starting with an inline style being there, or our inline style was overwritten
+			transition = this.#inlineTransition = inlineTransition;
+		}
+
+		if (transition === undefined && (firstTime || !this.#inlineTransition)) {
+			// Just update based on most current computed style
+			if (inlineTransition.includes(sot)) {
+				this.setProperty("transition", "");
+			}
+
+			transition = getComputedStyle(this.target).transition;
+		}
+
+		if (transition === "all") {
+			transition = "";
+		}
+		else {
+			// Don't disable transitions on properties we are observing. See https://github.com/LeaVerou/style-observer/issues/107
+			transition = transition.replace(/^none\b/, "");
+		}
+
+		// Note that in Safari < 18.2 this fires no `transitionrun` or `transitionstart` events:
+		// transition: all, var(--style-observer-transition, all);
+		// so we can't just concatenate with whatever the existing value is
+		const prefix = transition ? transition + ", " : "";
+		this.setProperty("transition", prefix + sot);
+
+		this.updateTransitionProperties();
+	}
+
+	/**
+	 * Whether the target has an open shadow root (and the modern adoptedStyleSheets API is supported).
+	 * @type { boolean }
+	 * @private
+	 */
+	get _isHost () {
+		return (
+			this.target.shadowRoot && !bugs.ADOPTED_STYLE_SHEET && !Object.isFrozen(this.target.shadowRoot.adoptedStyleSheets)
+		);
+	}
+
+	/**
+	 * Shadow style sheet. Only used if _isHost is true.
+	 * @type { CSSStyleSheet | undefined }
+	 * @private
+	 */
+	_shadowSheet;
+
+	/**
+	 * Any styles we've set on the target, for any reason.
+	 * @type { Record<string, string> }
+	 * @private
+	 */
+	_styles = {};
+
+	/**
+	 * Set a CSS property on the target.
+	 * @param {string} property
+	 * @param {string} value
+	 * @param {string} [priority]
+	 * @return {void}
+	 */
+	setProperty (property, value, priority) {
+		let inlineStyle = this.target.style;
+		let style = inlineStyle;
+		if (this._isHost) {
+			// This has an open shadow root.
+			// We can use an adopted shadow style to avoid manipulating its style attribute
+			if (!this._shadowSheet) {
+				this._shadowSheet = new CSSStyleSheet();
+				this._shadowSheet.insertRule(`:host { }`);
+				this.target.shadowRoot.adoptedStyleSheets.push(this._shadowSheet);
+
+				if (Object.keys(this._styles).length > 0) {
+					// It was previously not a host, so we need to port the properties over
+					for (let property in this._styles) {
+						let value = this._styles[property];
+						this.setProperty(property, value);
+
+						// Remove from inline style if it hasn't changed externally
+						if (inlineStyle.getPropertyValue(property) === value) {
+							inlineStyle.removeProperty(property);
+						}
+					}
+				}
+			}
+
+			style = this._shadowSheet.cssRules[0].style;
+		}
+
+		style.setProperty(property, value, priority);
+		// Store reserialized value for later comparison
+		this._styles[property] = this.getProperty(property);
+	}
+
+	/**
+	 * Get a CSS property from the target.
+	 * @param {string} property
+	 * @return {string}
+	 */
+	getProperty (property) {
+		let style = this._shadowSheet?.cssRules[0]?.style ?? this.target.style;
+		return style.getPropertyValue(property);
+	}
+
+	/**
+	 * Stop observing a target for changes to one or more CSS properties.
+	 * @param { string | string[] } [properties] Properties to stop observing. Defaults to all observed properties.
+	 * @return {void}
+	 */
+	unobserve (properties) {
+		properties = toArray(properties);
+
+		// Drop properties not being observed anyway
+		properties = properties.filter(property => this.properties.has(property));
+
+		for (let property of properties) {
+			this.properties.delete(property);
+		}
+
+		if (this.properties.size === 0) {
+			// No longer observing any properties
+			this.target.removeEventListener("transitionrun", this);
+			this.target.removeEventListener("transitionstart", this);
+			this.target.removeEventListener("transitionend", this);
+			this.renderedObserver.unobserve(this.target);
+		}
+
+		this.updateTransitionProperties();
+	}
+
+	/** All properties ever observed by this class. */
+	static properties = new Set();
+
+	/**
+	 * All instances ever observed by this class.
+	 */
+	static all = new MultiWeakMap();
+}
+
+/**
+ * Resolve the observer options.
+ * @param {StyleObserverOptions} options
+ * @returns {StyleObserverOptionsObject}
+ */
+function resolveOptions (options) {
+	if (!options) {
+		return {};
+	}
+
+	if (typeof options === "string" || Array.isArray(options)) {
+		options = { properties: toArray(options) };
+	}
+	else if (typeof options === "object") {
+		options = { properties: [], ...options };
+	}
+
+	return options;
+}
+
+/**
+ * @typedef {import("./element-style-observer.js").StyleObserverCallback} StyleObserverCallback
+ */
+
+/**
+ * @typedef { Object } StyleObserverOptions
+ * @property {string | string[]} [properties] - The properties to observe.
+ * @property {Element | Element[]} [targets] - The elements to observe.
+ */
+
+class StyleObserver {
+	/**
+	 * @type { WeakMap<Element, ElementStyleObserver> }
+	 */
+	elementObservers = new WeakMap();
+
+	/**
+	 * @param {StyleObserverCallback} callback
+	 * @param {StyleObserverOptions | string | string[]} [options]
+	 */
+	constructor (callback, options) {
+		this.callback = callback;
+
+		options = resolveOptions(options);
+		options.targets ??= [];
+
+		if (options.target) {
+			options.targets.push(options.target);
+		}
+
+		this.options = options;
+
+		if (this.options.targets.length > 0 && this.options.properties.length > 0) {
+			this.observe(this.options.targets, this.options.properties);
+		}
+	}
+
+	/**
+	 * @type {StyleObserverCallback}
+	 */
+	changed (records) {
+		// TODO throttle & combine records
+		this.callback(records);
+	}
+
+	/**
+	 * Observe one or more targets for changes to one or more CSS properties.
+	 *
+	 * @overload
+	 * @param {Element | Element[]} targets
+	 * @param {string | string[]} properties
+	 * @returns {void}
+	 *
+	 * @overload
+	 * @param {string | string[]} properties
+	 * @param {Element | Element[]} targets
+	 * @returns {void}
+	 *
+	 * @overload
+	 * @param {...(string | Element | (string | Element)[]) } propertiesOrTargets
+	 * @returns {void}
+	 */
+	observe (...args) {
+		let { targets, properties } = resolveArgs(...args);
+
+		if (targets.length === 0) {
+			// Default to constructor-specified targets
+			targets = this.options.targets;
+		}
+
+		if (targets.length === 0) {
+			return;
+		}
+
+		for (let target of targets) {
+			let observer = this.elementObservers.get(target);
+
+			if (!observer) {
+				observer = new ElementStyleObserver(
+					target,
+					records => this.changed(records),
+					this.options,
+				);
+				this.elementObservers.set(target, observer);
+			}
+
+			observer.observe(properties);
+		}
+	}
+
+	/**
+	 * Stop observing one or more targets for changes to one or more CSS properties.
+	 *
+	 * @overload
+	 * @param {Element | Element[]} targets
+	 * @param {string | string[]} properties
+	 * @returns {void}
+	 *
+	 * @overload
+	 * @param {string | string[]} properties
+	 * @param {Element | Element[]} targets
+	 * @returns {void}
+	 *
+	 * @overload
+	 * @param {...(string | Element | (string | Element)[]) } propertiesOrTargets
+	 * @returns {void}
+	 */
+	unobserve (...args) {
+		let { targets, properties } = resolveArgs(...args);
+
+		if (targets.length === 0) {
+			// Default to constructor-specified targets
+			targets = this.options.targets;
+		}
+
+		if (targets.length === 0) {
+			return;
+		}
+
+		if (properties.length === 0) {
+			// Default to constructor-specified properties
+			properties = this.options.properties;
+		}
+
+		for (let target of targets) {
+			let observer = this.elementObservers.get(target);
+
+			if (observer) {
+				observer.unobserve(properties);
+			}
+		}
+	}
+
+	/**
+	 * Update the transition for one or more targets.
+	 * @param {Element | Element[]} targets
+	 * @returns {void}
+	 */
+	updateTransition (targets) {
+		for (let target of toArray(targets)) {
+			let observer = this.elementObservers.get(target);
+
+			if (observer) {
+				observer.updateTransition();
+			}
+		}
+	}
+}
+
+/**
+ * Resolve the targets and properties from the arguments.
+ * @param {Element | Element[] | string | string[]} targets
+ * @param {Element | Element[] | string | string[]} properties
+ * @returns {{ targets: Element[], properties: string[] }}
+ */
+function resolveArgs (targets, properties) {
+	let args = [...toArray(targets), ...toArray(properties)];
+	targets = [];
+	properties = [];
+
+	for (let arg of args) {
+		let arr = typeof arg === "string" || arg instanceof String ? properties : targets;
+		arr.push(arg);
+	}
+
+	return { targets, properties };
+}
+
+exports.StyleObserver = StyleObserver;