@studiometa/js-toolkit 3.9.0 → 4.0.0-alpha.0

package/dist/Base.js

@@ -0,0 +1,907 @@
+import { memo } from "./utils/memo.js";
+import { capitalize, kebabCase } from "./utils/strings.js";
+import { REF_ATTRIBUTE, isInNamespace, isNetChange, negatedOptionAttributeFor, optionAttributeFor } from "./attributes.js";
+import { BASE_BRAND } from "./component-brand.js";
+import { reportDiagnostic, warn, warnOnce } from "./diagnostics.js";
+import { defaultScheduler } from "./scheduler.js";
+import { domVersion } from "./dom-mutations.js";
+import { activeBreakpoint, checkResponsiveAttributes, responsiveRawValue, watchBreakpoint } from "./responsive-options.js";
+import { componentTokens } from "./component-declarations.js";
+import { EVENTS } from "./events.js";
+import { registerChildrenWatcher } from "./children-watchers.js";
+import { injectContext, injectContextSync, provideContext } from "./context.js";
+import { compareDocumentOrder } from "./document-order.js";
+import { HANDLER_REGISTRATIONS, INSTANCES } from "./protocol-symbols.js";
+import { selectorFor } from "./utils/selectors.js";
+//#region src/Base.ts
+const REGEX_HANDLER = /^on[A-Z]/;
+let componentId = 0;
+/**
+* Events that do not bubble, so their delegated listener must be registered
+* in the capture phase to be reached at all.
+*/
+const CAPTURED_EVENTS = /* @__PURE__ */ new Set([
+	"blur",
+	"focus",
+	"load",
+	"error",
+	"scroll",
+	"mouseenter",
+	"mouseleave",
+	"pointerenter",
+	"pointerleave"
+]);
+/** Warn for non-object payloads used from untyped code. The event still dispatches. */
+function checkPayload(instance, event, payload) {
+	if (payload !== void 0 && (typeof payload !== "object" || payload === null)) warnOnce(instance, event, "event.invalid-emit-payload", `\`$emit('${event}', …)\` takes one payload object; received ${typeof payload}. Name the value: \`{ value }\`.`, {
+		component: instance.$config.name,
+		target: instance.$el
+	});
+}
+/**
+* Test ref ownership. Plain refs stop at any component boundary; namespaced refs stop at a boundary with the named component.
+*
+* The root is not tested because the namespace uses the class config name, which can differ from its declaration token.
+*/
+function belongsTo(el, root, owner) {
+	let parent = el.parentElement;
+	while (parent && parent !== root) {
+		const declarations = componentTokens(parent);
+		if (owner === void 0 ? declarations.size > 0 : declarations.has(owner)) return false;
+		parent = parent.parentElement;
+	}
+	return parent === root;
+}
+/** The list suffix is part of both the declaration and `data-ref` value. */
+const REF_LIST_SUFFIX = "[]";
+function isRefList(definition) {
+	return definition.endsWith(REF_LIST_SUFFIX);
+}
+/** The name a `config.refs` entry takes in `$refs`, and in `on<Ref><Event>`. */
+function refPropertyName(definition) {
+	return isRefList(definition) ? definition.slice(0, -2) : definition;
+}
+/** Namespaced refs name their owner and can cross other component boundaries. */
+const REF_NAMESPACE_SEPARATOR = ".";
+/** Return `Component.ref[]`; the namespace wraps the complete ref definition. */
+function namespacedRef(componentName, definition) {
+	return `${componentName}${REF_NAMESPACE_SEPARATOR}${definition}`;
+}
+/**
+* Does this element declare `definition` as a ref of `root`, in either
+* spelling? The two forms scope differently, so which one was written decides
+* how ownership is resolved.
+*/
+function isRefOf(el, root, componentName, definition) {
+	const declared = el.getAttribute(REF_ATTRIBUTE);
+	if (declared === definition) return belongsTo(el, root);
+	return declared === namespacedRef(componentName, definition) && belongsTo(el, root, componentName);
+}
+/** Return owned plain and namespaced refs for the declared name, in document order. */
+function queryRefs(root, componentName, definition) {
+	const plain = [...root.querySelectorAll(`[${REF_ATTRIBUTE}="${definition}"]`)].filter((el) => belongsTo(el, root));
+	const namespaced = root.querySelectorAll(`[${REF_ATTRIBUTE}="${namespacedRef(componentName, definition)}"]`);
+	if (namespaced.length === 0) return plain;
+	const owned = [...namespaced].filter((el) => belongsTo(el, root, componentName));
+	if (plain.length === 0) return owned;
+	return [...plain, ...owned].sort(compareDocumentOrder);
+}
+/** Warn once when a missing list ref has an unsuffixed markup candidate. */
+function warnMissingRefSuffix(instance, definition, checked) {
+	if (checked.has(definition)) return;
+	checked.add(definition);
+	const name = refPropertyName(definition);
+	const namespaced = namespacedRef(instance.$config.name, name);
+	if (!instance.$el.querySelector(`[data-ref="${name}"],[data-ref="${namespaced}"]`)) return;
+	warnOnce(instance, `attribute:${definition}`, "ref.mismatch", `\`${instance.$config.name}\` declares \`${definition}\` and found no \`data-ref="${definition}"\`, but the markup declares \`data-ref="${name}"\`. A list ref carries the \`[]\` in the attribute too: add it, or drop it from \`config.refs\`.`, {
+		component: instance.$config.name,
+		target: instance.$el
+	});
+}
+/** Warn when `@on()` uses a list ref's derived property name instead of its suffixed declaration. */
+function warnRefSuffixMismatch(instance, child, refs) {
+	const other = isRefList(child) ? refPropertyName(child) : `${child}${REF_LIST_SUFFIX}`;
+	if (!refs.some(({ definition }) => definition === other)) return;
+	warnOnce(instance, `handler:${child}`, "ref.mismatch", `\`${instance.$config.name}\` binds \`@on('${child}', …)\`, which matches no component and no ref. The ref is declared \`${other}\`, and \`@on()\` names a ref the way it is declared: write \`@on('${other}', …)\`.`, {
+		component: instance.$config.name,
+		target: instance.$el
+	});
+}
+/**
+* Build live refs resolved from current DOM. List declarations return arrays; namespaced attributes use the unqualified property name.
+*/
+function buildRefs(instance) {
+	const refs = {};
+	const checked = /* @__PURE__ */ new Set();
+	const componentName = instance.$config.name;
+	for (const definition of instance.$config.refs ?? []) {
+		const isList = isRefList(definition);
+		const name = refPropertyName(definition);
+		let cachedVersion = -1;
+		let cached = [];
+		Object.defineProperty(refs, name, {
+			enumerable: true,
+			get() {
+				let elements;
+				if (instance.$el.isConnected) {
+					const version = domVersion();
+					if (version !== cachedVersion) {
+						cachedVersion = version;
+						cached = queryRefs(instance.$el, componentName, definition);
+					}
+					elements = cached;
+				} else elements = queryRefs(instance.$el, componentName, definition);
+				if (isList && elements.length === 0) warnMissingRefSuffix(instance, definition, checked);
+				return isList ? elements : elements[0];
+			}
+		});
+	}
+	return refs;
+}
+/** The method name an option's effect is declared under. */
+function optionChangedMethod(name) {
+	return `option${capitalize(name)}Changed`;
+}
+/** The effect an option declares, or `undefined` when the component declares none. */
+function optionChangedHandler(instance, name) {
+	const handler = instance[optionChangedMethod(name)];
+	return typeof handler === "function" ? handler : void 0;
+}
+/** Warn once per declaration for literal object or array defaults. Values are not copied. */
+function warnLiteralDefault(componentName, option, definition, declared, target) {
+	warnOnce(definition, "", "option.literal-default", `\`${componentName}\` declares option \`${option}\` with a literal ${Array.isArray(declared) ? "array" : "object"} default, which every instance of it then shares. Only a primitive may be a default; declare this one as a factory: \`default: () => (…)\`.`, {
+		component: componentName,
+		target
+	});
+}
+/** An absent attribute reads the declared default, or the type's empty value. */
+function absentValue(defaultValue, empty) {
+	const value = defaultValue();
+	return value === void 0 ? empty : value;
+}
+/**
+* `buildDefault()` already answers `[]` or `{}` when nothing was declared, so
+* a structured type needs no empty value of its own. Unparsable JSON is not a
+* failure either: the option falls back to that same default.
+*/
+function readJSON(raw, defaultValue) {
+	if (raw === null) return absentValue(defaultValue, void 0);
+	try {
+		return JSON.parse(raw);
+	} catch {
+		return defaultValue();
+	}
+}
+function emptyValue(type) {
+	if (type === Boolean) return false;
+	if (type === Number) return 0;
+	if (type === String) return "";
+	if (type === Array) return [];
+	return {};
+}
+function isOptionValue(value, type) {
+	if (type === Boolean) return typeof value === "boolean";
+	if (type === Number) return typeof value === "number" && !Number.isNaN(value);
+	if (type === String) return typeof value === "string";
+	if (type === Array) return Array.isArray(value);
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+/** What each supported option type makes of its attribute. */
+const OPTION_TYPE_RULES = /* @__PURE__ */ new Map([
+	[Boolean, (raw, defaultValue) => raw === null ? defaultValue() ?? false : raw !== "\0"],
+	[Number, (raw, defaultValue) => raw === null ? absentValue(defaultValue, 0) : Number(raw)],
+	[String, (raw, defaultValue) => raw === null ? absentValue(defaultValue, "") : raw],
+	[Array, readJSON],
+	[Object, readJSON]
+]);
+function readUnion(types, raw, defaultValue) {
+	if (raw === null) return absentValue(defaultValue, types[0] === void 0 ? void 0 : emptyValue(types[0]));
+	if (raw === "\0") return false;
+	for (const type of types) {
+		const value = OPTION_TYPE_RULES.get(type)(raw, () => void 0);
+		if (isOptionValue(value, type)) return value;
+	}
+	return defaultValue();
+}
+function isOptionTypes(value) {
+	return Array.isArray(value);
+}
+function isOptionShorthand(definition) {
+	return typeof definition === "function" || isOptionTypes(definition);
+}
+/**
+* Whether an option can hold `false`, and therefore whether the negated
+* attribute means anything for it. A union is enough: `[Boolean, String]` can
+* be turned off, `[String, Number]` has nothing to turn off.
+*/
+function declaresBoolean(definition) {
+	const type = isOptionShorthand(definition) ? definition : definition.type;
+	return isOptionTypes(type) ? type.includes(Boolean) : type === Boolean;
+}
+/**
+* The `$options` view and the readers behind it, built in one pass: the getters
+* and the readers are the same closures seen from two sides.
+*/
+function buildOptions(instance) {
+	const options = {};
+	const readers = /* @__PURE__ */ new Map();
+	const el = instance.$el;
+	for (const [name, definition] of Object.entries(instance.$config.options ?? {})) {
+		const shorthand = isOptionShorthand(definition);
+		const type = shorthand ? definition : definition.type;
+		const declared = shorthand ? void 0 : definition.default;
+		const attribute = optionAttributeFor(name);
+		const negated = declaresBoolean(definition) ? negatedOptionAttributeFor(name) : void 0;
+		if (!shorthand && declared !== null && typeof declared === "object") warnLiteralDefault(instance.$config.name, name, definition, declared, el);
+		let memoized;
+		let isMemoized = false;
+		const defaultValue = () => {
+			if (!isMemoized) {
+				isMemoized = true;
+				memoized = buildDefault();
+			}
+			return memoized;
+		};
+		const buildDefault = () => {
+			if (typeof declared === "function") return declared();
+			if (declared !== void 0) return declared;
+			const defaultType = isOptionTypes(type) ? type[0] : type;
+			if (defaultType === Array) return [];
+			if (defaultType === Object) return {};
+		};
+		const read = (raw) => isOptionTypes(type) ? readUnion(type, raw, defaultValue) : (OPTION_TYPE_RULES.get(type) ?? ((value, fallback) => value === null ? absentValue(fallback, void 0) : value))(raw, defaultValue);
+		const fromElement = (attributeName) => el.getAttribute(attributeName);
+		const rawValue = () => responsiveRawValue(attribute, activeBreakpoint(), fromElement, negated);
+		const rawValueAt = (breakpoint, get) => responsiveRawValue(attribute, breakpoint, get, negated);
+		const owns = (attributeName) => isInNamespace(attribute, attributeName) || negated !== void 0 && isInNamespace(negated, attributeName);
+		readers.set(name, {
+			attribute,
+			rawValue,
+			rawValueAt,
+			owns,
+			read
+		});
+		Object.defineProperty(options, name, {
+			enumerable: true,
+			get: () => read(rawValue())
+		});
+	}
+	return {
+		options,
+		readers
+	};
+}
+/**
+* Merge inherited config. Collections merge; declared scalar values override parent values.
+*
+* The registry uses this before an instance exists. Memoised per class: a
+* config is a pure function of the prototype chain, and `$config` reads it on
+* every access.
+*/
+const resolveConfig = /* @__PURE__ */ memo((ctor) => {
+	const chain = [];
+	let current = ctor;
+	while (current?.config) {
+		if (Object.hasOwn(current, "config")) chain.unshift(current.config);
+		current = Object.getPrototypeOf(current);
+	}
+	return chain.reduce((merged, own) => ({
+		...merged,
+		...own,
+		refs: [.../* @__PURE__ */ new Set([...merged.refs ?? [], ...own.refs ?? []])],
+		options: {
+			...merged.options,
+			...own.options
+		},
+		components: {
+			...merged.components,
+			...own.components
+		}
+	}), { name: ctor.name });
+});
+/**
+* Define one of the four fixed instance properties.
+*
+* `readonly` is a compile-time promise and these four are the instance's
+* identity — the element it is bound to, the id derived from its name, and the
+* two views over its markup. A non-writable property makes the promise the
+* runtime's too: an assignment throws in a module rather than replacing what
+* every other part of the framework reads. The fields are `declare`d, so the
+* class emits no initializer to overwrite what this defines.
+*/
+function defineFixed(instance, property, value) {
+	Object.defineProperty(instance, property, {
+		value,
+		enumerable: true
+	});
+}
+/** Reserved handler prefixes for global targets. They take precedence over child and ref names. */
+const GLOBAL_PREFIXES = ["Window", "Document"];
+/** Resolve a global handler prefix only when an event name follows it. */
+function resolveGlobal(rest) {
+	for (const prefix of GLOBAL_PREFIXES) if (rest.length > prefix.length && rest.startsWith(prefix)) return {
+		target: prefix === "Window" ? window : document,
+		type: kebabCase(rest.slice(prefix.length))
+	};
+	return null;
+}
+/** Return inherited prototype handler names. Class fields are not included. */
+function handlerMethodNames(ctor) {
+	const names = /* @__PURE__ */ new Set();
+	let proto = ctor.prototype;
+	while (proto && proto !== Base.prototype) {
+		for (const name of Object.getOwnPropertyNames(proto)) if (REGEX_HANDLER.test(name)) names.add(name);
+		proto = Object.getPrototypeOf(proto);
+	}
+	return [...names];
+}
+/**
+* Resolve and cache each class's handler plan.
+*
+* Keep the `@__PURE__` annotation so bundlers can remove unused handler planning.
+*/
+const handlerPlan = /* @__PURE__ */ memo((ctor) => {
+	const config = resolveConfig(ctor);
+	const byLength = (a, b) => b.length - a.length;
+	const childNames = Object.keys(config.components ?? {}).sort(byLength);
+	const refs = (config.refs ?? []).map((definition) => ({
+		name: refPropertyName(definition),
+		definition
+	})).sort((a, b) => byLength(a.name, b.name));
+	const entries = handlerMethodNames(ctor).map((method) => {
+		const rest = method.slice(2);
+		const global = resolveGlobal(rest);
+		if (global) return {
+			kind: "global",
+			method,
+			type: global.type,
+			target: global.target
+		};
+		const startsWith = (name) => rest.startsWith(capitalize(name)) && rest.length > name.length;
+		const childName = childNames.find(startsWith);
+		if (childName) return {
+			kind: "child",
+			method,
+			type: kebabCase(rest.slice(childName.length)),
+			name: childName
+		};
+		const ref = refs.find(({ name }) => startsWith(name));
+		if (ref) return {
+			kind: "ref",
+			method,
+			type: kebabCase(rest.slice(ref.name.length)),
+			name: ref.definition
+		};
+		return {
+			kind: "own",
+			method,
+			type: kebabCase(rest)
+		};
+	});
+	return {
+		childNames,
+		refs,
+		componentName: config.name,
+		entries
+	};
+});
+function addDelegated(delegated, type, entry) {
+	if (!delegated.has(type)) delegated.set(type, []);
+	delegated.get(type)?.push(entry);
+}
+function reportLifecycleFailure(instance, message, error) {
+	reportDiagnostic("component.lifecycle-failed", message, error, {
+		component: instance.$config.name,
+		target: instance.$el
+	});
+}
+/** What `#guard()` returns instead of a value when the guarded call threw. */
+const GUARD_FAILED = Symbol("guard-failed");
+/**
+* The class every component extends.
+* @link https://js-toolkit-v4.studiometa.dev/api/
+*/
+var Base = class {
+	/** A class-owned brand inherited by subclasses and shared by bundled copies. */
+	static [BASE_BRAND] = true;
+	static config = { name: "Base" };
+	#isMounted = false;
+	/** Per-mount-cycle listeners, removed on every `$unmount()`. */
+	#listeners = [];
+	/** Per-mount-cycle cleanups (service unsubscriptions, `mounted()` return values). */
+	#unmountCallbacks = [];
+	/**
+	* The reader behind each declared option, built with the `$options` view.
+	*
+	* A side table rather than a cache: it holds no computed value, it holds the
+	* other half of what `buildOptions()` produced, so it lives with the
+	* instance like every other piece of its state.
+	*/
+	#optionReaders;
+	/** Cleanup returned by each active `option<Name>Changed()` effect. */
+	#optionCleanups = /* @__PURE__ */ new Map();
+	/** Increments on mount so a reentrant effect cannot attach to a later cycle. */
+	#mountCycle = 0;
+	/**
+	* The `$watchChildren()` watchers this instance owns. The shared unmount
+	* listener only holds weak references to them, so this field is what keeps
+	* them alive — and what lets them die with their owner.
+	*/
+	#childrenWatchers = [];
+	#tasks = /* @__PURE__ */ new Set();
+	get $config() {
+		return resolveConfig(this.constructor);
+	}
+	get $isMounted() {
+		return this.#isMounted;
+	}
+	constructor(el) {
+		const { name } = this.$config;
+		componentId += 1;
+		defineFixed(this, "$el", el);
+		defineFixed(this, "$id", `${name}-${componentId - 1}`);
+		el[INSTANCES] ??= /* @__PURE__ */ new Map();
+		el[INSTANCES].set(name, this);
+		const built = buildOptions(this);
+		defineFixed(this, "$options", built.options);
+		this.#optionReaders = built.readers;
+		defineFixed(this, "$refs", buildRefs(this));
+	}
+	/**
+	* Lifecycle hook, meant to be overridden. May return a cleanup function
+	* (or an array of them) that runs on the next `$unmount()` — sync or
+	* async:
+	*
+	*     async mounted() {
+	*       const signal = await this.$inject(SomeContext);
+	*       return signal.subscribe((value) => { … });
+	*     }
+	*
+	* A component extending a mixin returns what it extends along with its
+	* own, in any nesting:
+	*
+	*     mounted() {
+	*       return [super.mounted(), () => { … }];
+	*     }
+	*/
+	mounted() {}
+	/**
+	* Lifecycle hook, meant to be overridden. Runs at the end of `$unmount()`,
+	* after the `mounted()` cleanups, and returns nothing: a teardown that
+	* belongs to a specific piece of setup is better written as the cleanup
+	* `mounted()` returns, next to the setup it undoes.
+	*/
+	unmounted() {}
+	/**
+	* Mount the instance. `$unmount()` is its inverse and the same instance can
+	* mount again — this is what happens when an element is moved or
+	* re-inserted in the DOM.
+	*/
+	$mount() {
+		if (this.#isMounted) return this;
+		this.#bindHandlers();
+		this.#isMounted = true;
+		this.#mountCycle += 1;
+		const cycle = this.#mountCycle;
+		this.#initializeOptionEffects(cycle);
+		if (!this.#isActiveMountCycle(cycle)) return this;
+		this.#initializeResponsiveOptions(cycle);
+		if (!this.#isActiveMountCycle(cycle)) return this;
+		this.#guard("`mounted()` failed.", () => this.#collectCleanup(this.mounted(), cycle));
+		if (!this.#isActiveMountCycle(cycle)) return this;
+		const detail = { instance: this };
+		this.$el.dispatchEvent(new CustomEvent(EVENTS.component.mounted, {
+			bubbles: true,
+			cancelable: false,
+			detail
+		}));
+		return this;
+	}
+	/**
+	* End the mount cycle. Removes the per-cycle listeners, leaves the
+	* services, cancels the scheduler tasks the cycle left pending, runs the
+	* `mounted()` cleanups and calls the `unmounted()` hook. The instance stays
+	* on its element and `$mount()` starts a new cycle.
+	*/
+	$unmount() {
+		if (!this.#isMounted) return this;
+		this.#isMounted = false;
+		for (const [type, listener, target, capture] of this.#listeners) target.removeEventListener(type, listener, capture);
+		this.#listeners = [];
+		const pending = this.#tasks;
+		this.#tasks = /* @__PURE__ */ new Set();
+		for (const task of pending) task.cancel();
+		const callbacks = this.#unmountCallbacks;
+		this.#unmountCallbacks = [];
+		for (const callback of callbacks) this.#guard("A mount cleanup failed.", callback);
+		this.#clearOptionEffects();
+		this.#guard("`unmounted()` failed.", () => this.unmounted());
+		const detail = { instance: this };
+		document.dispatchEvent(new CustomEvent(EVENTS.component.unmounted, {
+			cancelable: false,
+			detail
+		}));
+		return this;
+	}
+	$emit(event, payload) {
+		checkPayload(this, event, payload);
+		return this.#dispatch(event, payload);
+	}
+	/** Build and dispatch a component event. */
+	#dispatch(event, detail) {
+		const dispatched = new CustomEvent(event, {
+			bubbles: true,
+			cancelable: true,
+			detail
+		});
+		this.$el.dispatchEvent(dispatched);
+		return dispatched;
+	}
+	$on(type, listener, options) {
+		this.$el.addEventListener(type, listener, options);
+		return () => this.$el.removeEventListener(type, listener, options);
+	}
+	$off(type, listener, options) {
+		this.$el.removeEventListener(type, listener, options);
+	}
+	/**
+	* Mounted descendant instances by component name, in DOM order.
+	*/
+	$query(name) {
+		return [...this.$el.querySelectorAll(selectorFor(name))].map((el) => el[INSTANCES]?.get(name)).filter((instance) => Boolean(instance?.$isMounted));
+	}
+	/**
+	* Nearest mounted ancestor instance by component name.
+	*/
+	$closest(name) {
+		let el = this.$el.parentElement;
+		while (el) {
+			const instance = el[INSTANCES]?.get(name);
+			if (instance?.$isMounted) return instance;
+			el = el.parentElement;
+		}
+		return null;
+	}
+	$watchChildren(target, callbacks = {}) {
+		const instances = /* @__PURE__ */ new Set();
+		const matches = (instance) => typeof target === "string" ? instance.$config.name === target : instance instanceof target;
+		const add = (instance) => {
+			if (instance !== this && !instances.has(instance)) {
+				instances.add(instance);
+				callbacks.added?.(instance);
+			}
+		};
+		const remove = (instance) => {
+			if (instances.delete(instance)) callbacks.removed?.(instance);
+		};
+		queueMicrotask(() => {
+			if (typeof target === "string") {
+				for (const instance of this.$query(target)) add(instance);
+				return;
+			}
+			for (const el of this.$el.querySelectorAll("*")) for (const instance of el[INSTANCES]?.values() ?? []) if (instance.$isMounted && matches(instance)) add(instance);
+		});
+		const onMounted = (event) => {
+			const { instance } = event.detail;
+			if (instance.$isMounted && matches(instance)) add(instance);
+		};
+		const watcher = (instance) => {
+			if (matches(instance)) remove(instance);
+		};
+		this.#childrenWatchers.push(watcher);
+		registerChildrenWatcher(watcher);
+		this.$el.addEventListener(EVENTS.component.mounted, onMounted);
+		return {
+			get size() {
+				return instances.size;
+			},
+			get items() {
+				return [...instances].sort((a, b) => compareDocumentOrder(a.$el, b.$el));
+			},
+			[Symbol.iterator]() {
+				return this.items[Symbol.iterator]();
+			}
+		};
+	}
+	/**
+	* Provide a value verbatim to the subtree for as long as the element lives.
+	* The nearest provider wins.
+	*
+	* The provider sits on the element, not on the mount cycle, so it answers
+	* through every unmount and mount. Nothing releases it early: a component
+	* whose declaration is withdrawn keeps providing until its element goes.
+	*/
+	$provide(key, value) {
+		provideContext(this.$el, key, value);
+		return value;
+	}
+	/**
+	* Resolve the nearest value now or when a provider appears. The request remains pending without a provider and is canceled on unmount.
+	*/
+	$inject(key) {
+		const { promise, cancel } = injectContext(this.$el, key);
+		this.#unmountCallbacks.push(cancel);
+		return promise;
+	}
+	/** Resolve the nearest value now, or return `undefined` without queuing a request. */
+	$injectSync(key) {
+		return injectContextSync(this.$el, key);
+	}
+	/**
+	* Apply one mutation batch after declaration reconciliation. Option cleanup runs before the next value and on unmount. Only resolved value changes trigger effects.
+	*
+	* @internal
+	*/
+	$optionsChanged(changes) {
+		if (!this.#isMounted) return;
+		const before = (attributeName) => changes.has(attributeName) ? changes.get(attributeName) ?? null : this.$el.getAttribute(attributeName);
+		for (const [name, reader] of this.#optionReaders) {
+			let touched = changes.has(reader.attribute);
+			if (!touched) {
+				for (const attributeName of changes.keys()) if (reader.owns(attributeName)) {
+					touched = true;
+					break;
+				}
+			}
+			if (!touched) continue;
+			const previousRawValue = reader.rawValueAt(activeBreakpoint(), before);
+			if (isNetChange(reader.rawValue(), previousRawValue)) this.#runOptionEffect(name, reader, previousRawValue, false);
+		}
+	}
+	/**
+	* Report a warning on the diagnostic channel, as this component.
+	*
+	* The component name and the element are filled in from the instance, which
+	* is the whole reason this exists on `Base` rather than being a bare
+	* function a component imports: those two are what a listener filters and
+	* inspects on, and a component is the one thing that always knows both.
+	*
+	* The code is namespaced — `'figure.load-failed'` — so a listener can select
+	* one component's diagnostics without matching on message text. Core's own
+	* codes are enumerated in `DIAGNOSTICS`; a code outside that set is a
+	* consumer's, and the shape is all that is required of it.
+	*
+	* Canceling the event suppresses the default `console.warn` and nothing
+	* else, so a host application can route these into its own reporter.
+	*/
+	$warn(code, message) {
+		warn(code, message, {
+			component: this.$config.name,
+			target: this.$el
+		});
+	}
+	/**
+	* Report a recovered failure on the diagnostic channel, as this component.
+	*
+	* The counterpart to {@link $warn} for the case where something threw and
+	* the component carried on: the original value is required, because a
+	* reporter that cannot see the cause cannot do anything useful with it.
+	* Canceling suppresses the default error sink.
+	*/
+	$error(code, message, error) {
+		reportDiagnostic(code, message, error, {
+			component: this.$config.name,
+			target: this.$el
+		});
+	}
+	/** Schedule a DOM read; canceled automatically when the instance unmounts. */
+	$read(fn) {
+		return this.#track(defaultScheduler.read(fn));
+	}
+	/** Schedule a DOM write; canceled automatically when the instance unmounts. */
+	$write(fn) {
+		return this.#track(defaultScheduler.write(fn));
+	}
+	#track(task) {
+		this.#tasks.add(task);
+		const finished = () => this.#tasks.delete(task);
+		task.promise.then(finished, finished);
+		return task;
+	}
+	#isActiveMountCycle(cycle) {
+		return this.#isMounted && this.#mountCycle === cycle;
+	}
+	/**
+	* Run a hook or a cleanup owned by the component. A throw there must not
+	* abandon the framework bookkeeping which follows it, so it is reported and
+	* swallowed; the sentinel lets the few callers which care tell a failure
+	* from a value the call returned.
+	*/
+	#guard(message, run) {
+		try {
+			return run();
+		} catch (error) {
+			reportLifecycleFailure(this, message, error);
+			return GUARD_FAILED;
+		}
+	}
+	#initializeOptionEffects(cycle) {
+		for (const [name, reader] of this.#optionReaders) {
+			if (!this.#isActiveMountCycle(cycle)) return;
+			this.#runOptionEffect(name, reader, null, true);
+		}
+	}
+	/** Subscribe to breakpoint changes for this mount cycle only when an option effect exists. */
+	#initializeResponsiveOptions(cycle) {
+		const readers = this.#optionReaders;
+		if (!readers || readers.size === 0) return;
+		checkResponsiveAttributes(this.$el, [...readers.values()].map((reader) => reader.attribute));
+		if (![...readers.keys()].some((name) => optionChangedHandler(this, name) !== void 0)) return;
+		this.#collectCleanup(watchBreakpoint((previous) => {
+			const fromElement = (attributeName) => this.$el.getAttribute(attributeName);
+			for (const [name, reader] of readers) {
+				const previousRawValue = reader.rawValueAt(previous, fromElement);
+				if (isNetChange(reader.rawValue(), previousRawValue)) this.#runOptionEffect(name, reader, previousRawValue, false);
+			}
+		}), cycle);
+	}
+	#runOptionEffect(name, reader, previousRawValue, initial) {
+		const previousCleanup = this.#optionCleanups.get(name);
+		this.#optionCleanups.delete(name);
+		if (previousCleanup) this.#guard(`Option "${name}" cleanup failed.`, previousCleanup);
+		if (!this.#isMounted) return;
+		const handler = optionChangedHandler(this, name);
+		if (!handler) return;
+		const cycle = this.#mountCycle;
+		const cleanup = this.#guard(`\`${optionChangedMethod(name)}()\` failed.`, () => {
+			const rawValue = reader.rawValue();
+			const change = {
+				name,
+				value: reader.read(rawValue),
+				previousValue: initial ? void 0 : reader.read(previousRawValue),
+				rawValue,
+				previousRawValue,
+				initial
+			};
+			return handler.call(this, change);
+		});
+		if (cleanup === GUARD_FAILED) return;
+		if (typeof cleanup === "function") {
+			if (this.#isMounted && this.#mountCycle === cycle) this.#optionCleanups.set(name, cleanup);
+			else this.#guard(`Option "${name}" cleanup failed.`, cleanup);
+		}
+	}
+	#clearOptionEffects() {
+		const cleanups = this.#optionCleanups;
+		this.#optionCleanups = /* @__PURE__ */ new Map();
+		for (const [name, cleanup] of cleanups) this.#guard(`Option "${name}" cleanup failed.`, cleanup);
+	}
+	/**
+	* Register the cleanup value returned by `mounted()`. Async hooks are
+	* awaited; if their mount cycle ended in the meantime, the cleanup runs
+	* right away instead of leaking into a later cycle.
+	*/
+	#collectCleanup(result, cycle) {
+		if (typeof result === "function") {
+			if (this.#isActiveMountCycle(cycle)) this.#unmountCallbacks.push(result);
+			else this.#guard("A late mount cleanup failed.", result);
+			return;
+		}
+		if (Array.isArray(result)) {
+			for (const item of result) this.#collectCleanup(item, cycle);
+			return;
+		}
+		if (result instanceof Promise) result.then((resolved) => this.#collectCleanup(resolved, cycle)).catch((error) => {
+			reportLifecycleFailure(this, "`mounted()` failed.", error);
+		});
+	}
+	/** Bind root, delegated child/ref and global handlers for the current mount cycle. Delegated handlers resolve dynamic descendants at event time. */
+	#bindHandlers() {
+		const plan = handlerPlan(this.constructor);
+		const delegated = /* @__PURE__ */ new Map();
+		const decorated = this.#bindDecoratedHandlers(plan, delegated);
+		this.#bindPlannedHandlers(plan, delegated, decorated);
+		this.#installDelegatedListeners(plan.componentName, delegated);
+	}
+	#bindOwn(type, invoke) {
+		const listener = (event) => invoke(event);
+		this.$el.addEventListener(type, listener);
+		this.#listeners.push([
+			type,
+			listener,
+			this.$el,
+			false
+		]);
+	}
+	/** Bind a global handler in bubble phase for the current mount cycle. Capture is only for delegated non-bubbling events. */
+	#bindGlobal(target, type, invoke) {
+		const listener = (event) => invoke({
+			event,
+			target
+		});
+		target.addEventListener(type, listener);
+		this.#listeners.push([
+			type,
+			listener,
+			target,
+			false
+		]);
+	}
+	/**
+	* Bind the decorated handlers, which already carry resolved targets and
+	* event types, and return the method names they bound.
+	*/
+	#bindDecoratedHandlers(plan, delegated) {
+		const { childNames, refs } = plan;
+		const registrations = this[HANDLER_REGISTRATIONS] ?? [];
+		const decorated = new Set(registrations.map(({ method }) => method));
+		for (const { target, child, type, handler } of registrations) if (target) this.#bindGlobal(target, type, (payload) => handler.call(this, payload));
+		else if (child) {
+			const declaredChild = childNames.includes(child);
+			const ref = declaredChild ? void 0 : refs.find(({ definition }) => definition === child);
+			if (!declaredChild && !ref) warnRefSuffixMismatch(this, child, refs);
+			addDelegated(delegated, type, {
+				kind: ref ? "ref" : "child",
+				name: child,
+				invoke: (payload) => handler.call(this, payload)
+			});
+		} else this.#bindOwn(type, (event) => handler.call(this, event));
+		return decorated;
+	}
+	/** Bind the undecorated magic handlers from the cached class plan. */
+	#bindPlannedHandlers(plan, delegated, decorated) {
+		const self = this;
+		for (const entry of plan.entries) {
+			const { method, type } = entry;
+			if (decorated.has(method)) continue;
+			if (typeof self[method] !== "function") continue;
+			if (entry.kind === "global") this.#bindGlobal(entry.target, type, (payload) => self[method](payload));
+			else if (entry.kind === "own") this.#bindOwn(type, (event) => self[method](event));
+			else addDelegated(delegated, type, {
+				kind: entry.kind,
+				name: entry.name,
+				invoke: (payload) => self[method](payload)
+			});
+		}
+	}
+	/** Install one root listener per delegated event type. */
+	#installDelegatedListeners(componentName, delegated) {
+		for (const [type, entries] of delegated) {
+			const listener = (event) => {
+				let el = event.target instanceof Element ? event.target : null;
+				while (el && el !== this.$el) {
+					let invoked = false;
+					for (const entry of entries) if (this.#invokeDelegated(entry, el, event, componentName)) invoked = true;
+					if (invoked) return;
+					el = el.parentElement;
+				}
+			};
+			const capture = CAPTURED_EVENTS.has(type);
+			this.$el.addEventListener(type, listener, capture);
+			this.#listeners.push([
+				type,
+				listener,
+				this.$el,
+				capture
+			]);
+		}
+	}
+	/**
+	* Fire one delegated entry when `el` is what it waits on: a mounted child
+	* instance, or an owned ref. Returns whether it fired, which is how the
+	* walk knows it reached the nearest matching element.
+	*/
+	#invokeDelegated(entry, el, event, componentName) {
+		if (entry.kind === "child") {
+			const child = el[INSTANCES]?.get(entry.name);
+			if (!child?.$isMounted) return false;
+			entry.invoke({
+				event,
+				target: child,
+				payload: event.detail
+			});
+			return true;
+		}
+		if (!isRefOf(el, this.$el, componentName, entry.name)) return false;
+		entry.invoke({
+			event,
+			target: el,
+			index: queryRefs(this.$el, componentName, entry.name).indexOf(el)
+		});
+		return true;
+	}
+};
+//#endregion
+export { Base, declaresBoolean, resolveConfig };
+
+//# sourceMappingURL=Base.js.map