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

package/dist/context.js

@@ -0,0 +1,173 @@
+import { getSharedRuntimeSlot } from "./shared-runtime.js";
+import { isolateCallbackFailure } from "./diagnostics.js";
+//#region src/context.ts
+const CONTEXT_REQUEST = "js-toolkit:context:request";
+/**
+* Create a typed context key.
+* @link https://js-toolkit-v4.studiometa.dev/api/context/createContext.html
+*/
+function createContext(description = "context") {
+	return Symbol(description);
+}
+/**
+* Create a reactive value.
+*
+* Writes settle synchronously. A reentrant write supersedes the current delivery, so no subscriber observes an older value after a newer one.
+* @link https://js-toolkit-v4.studiometa.dev/api/context/signal.html
+*/
+function signal(initialValue) {
+	let current = initialValue;
+	let delivered = initialValue;
+	let isSettling = false;
+	const subscribers = /* @__PURE__ */ new Set();
+	function settle() {
+		if (isSettling) return;
+		isSettling = true;
+		try {
+			while (delivered !== current) {
+				delivered = current;
+				for (const subscriber of [...subscribers]) {
+					if (!subscriber.isActive) continue;
+					isolateCallbackFailure("callback.signal-failed", "A signal subscriber failed.", () => subscriber.callback(delivered));
+					if (current !== delivered) break;
+				}
+			}
+		} finally {
+			isSettling = false;
+		}
+	}
+	return {
+		get value() {
+			return current;
+		},
+		set value(next) {
+			if (next === current) return;
+			current = next;
+			settle();
+		},
+		subscribe(callback, { immediate = false } = {}) {
+			const subscriber = {
+				callback,
+				isActive: true
+			};
+			subscribers.add(subscriber);
+			if (immediate) isolateCallbackFailure("callback.signal-failed", "An immediate signal subscriber failed.", () => callback(current));
+			return () => {
+				subscriber.isActive = false;
+				subscribers.delete(subscriber);
+			};
+		}
+	};
+}
+const { pendingRequests, rootProviders } = /* @__PURE__ */ getSharedRuntimeSlot("context", 2, () => ({
+	pendingRequests: /* @__PURE__ */ new Set(),
+	rootProviders: /* @__PURE__ */ new Map()
+}));
+/**
+* Dispatch one request and report whether a provider answered synchronously.
+*
+* @internal
+*/
+function dispatchContextRequest(request) {
+	let isAnswered = false;
+	let event;
+	const detail = {
+		key: request.key,
+		subscribe: request.subscribe,
+		provide(value) {
+			isAnswered = true;
+			pendingRequests.delete(request);
+			const provider = event.currentTarget;
+			request.resolve(value, provider !== null && "contains" in provider ? provider : null);
+		}
+	};
+	event = new CustomEvent(CONTEXT_REQUEST, {
+		bubbles: true,
+		detail
+	});
+	request.el.dispatchEvent(event);
+	return isAnswered;
+}
+/** Keep an unanswered request available for a provider that appears later. @internal */
+function retainContextRequest(request) {
+	pendingRequests.add(request);
+}
+/** Stop replaying an unanswered request. @internal */
+function cancelContextRequest(request) {
+	pendingRequests.delete(request);
+}
+/**
+* Provide a value verbatim for a subtree. The nearest provider wins.
+* @link https://js-toolkit-v4.studiometa.dev/api/context/provideContext.html
+*/
+function provideContext(el, key, value) {
+	const onRequest = (event) => {
+		const { detail } = event;
+		if (detail?.key !== key) return;
+		event.stopPropagation();
+		detail.provide(value);
+	};
+	el.addEventListener(CONTEXT_REQUEST, onRequest);
+	for (const request of [...pendingRequests]) if (request.key === key && el.contains(request.el)) dispatchContextRequest(request);
+	return {
+		value,
+		dispose: () => el.removeEventListener(CONTEXT_REQUEST, onRequest)
+	};
+}
+/**
+* Provide a document-wide value created once per key. Nearer providers override it.
+*
+* Root providers are page-lifetime and cannot be disposed.
+* @link https://js-toolkit-v4.studiometa.dev/api/context/provideRootContext.html
+*/
+function provideRootContext(key, create) {
+	if (rootProviders.has(key)) return rootProviders.get(key);
+	const value = create();
+	rootProviders.set(key, value);
+	provideContext(document.documentElement, key, value);
+	return value;
+}
+/**
+* Resolve the nearest provided value for `key`, now or when a provider
+* appears. This request is one-shot: the first answer settles the promise and
+* removes the request.
+*
+* The promise stays pending while no provider exists. `cancel()` removes that
+* pending request and does nothing after an answer.
+* @link https://js-toolkit-v4.studiometa.dev/api/context/injectContext.html
+*/
+function injectContext(el, key) {
+	let request;
+	return {
+		promise: new Promise((resolve) => {
+			request = {
+				el,
+				key,
+				subscribe: false,
+				resolve: (value) => resolve(value)
+			};
+			if (!dispatchContextRequest(request)) retainContextRequest(request);
+		}),
+		cancel: () => cancelContextRequest(request)
+	};
+}
+/**
+* Resolve the nearest provided value synchronously, or return `undefined`.
+* @link https://js-toolkit-v4.studiometa.dev/api/context/injectContextSync.html
+*/
+function injectContextSync(el, key) {
+	let resolved;
+	dispatchContextRequest({
+		el,
+		key,
+		subscribe: false,
+		resolve: (value) => {
+			resolved = value;
+		}
+	});
+	return resolved;
+}
+//#endregion
+export { cancelContextRequest, createContext, dispatchContextRequest, injectContext, injectContextSync, provideContext, provideRootContext, retainContextRequest, signal };
+
+//# sourceMappingURL=context.js.map

package/dist/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","names":[],"sources":["../src/context.ts"],"sourcesContent":["import { isolateCallbackFailure } from './diagnostics.js';\nimport { getSharedRuntimeSlot } from './shared-runtime.js';\n\nconst CONTEXT_REQUEST = 'js-toolkit:context:request';\n\n/** A typed context key. `__context` is type-only. */\nexport type ContextKey<T = unknown> = symbol & { readonly __context?: T };\n\n/**\n * Create a typed context key.\n * @link https://js-toolkit-v4.studiometa.dev/api/context/createContext.html\n */\nexport function createContext<T = unknown>(description = 'context'): ContextKey<T> {\n  return Symbol(description);\n}\n\n/** A reactive value with synchronous subscriptions. */\nexport interface Signal<T = unknown> {\n  /** The latest value, including during delivery. */\n  value: T;\n  /** @returns Unsubscribe. */\n  subscribe(callback: (value: T) => void, options?: { immediate?: boolean }): () => void;\n}\n\n/** Each subscription has independent ownership and active state. */\ninterface Subscriber<T> {\n  callback: (value: T) => void;\n  isActive: boolean;\n}\n\n/**\n * Create a reactive value.\n *\n * Writes settle synchronously. A reentrant write supersedes the current delivery, so no subscriber observes an older value after a newer one.\n * @link https://js-toolkit-v4.studiometa.dev/api/context/signal.html\n */\nexport function signal<T>(initialValue: T): Signal<T> {\n  let current = initialValue;\n  let delivered = initialValue;\n  let isSettling = false;\n  const subscribers = new Set<Subscriber<T>>();\n\n  function settle() {\n    // The active loop drains reentrant writes without nesting delivery.\n    if (isSettling) {\n      return;\n    }\n    isSettling = true;\n    try {\n      while (delivered !== current) {\n        delivered = current;\n        // Snapshot delivery excludes later additions; `isActive` handles removals.\n        for (const subscriber of [...subscribers]) {\n          if (!subscriber.isActive) {\n            continue;\n          }\n          isolateCallbackFailure('callback.signal-failed', 'A signal subscriber failed.', () =>\n            subscriber.callback(delivered),\n          );\n          if (current !== delivered) {\n            break;\n          }\n        }\n      }\n    } finally {\n      isSettling = false;\n    }\n  }\n\n  return {\n    get value(): T {\n      return current;\n    },\n    set value(next: T) {\n      if (next === current) {\n        return;\n      }\n      current = next;\n      settle();\n    },\n    subscribe(callback: (value: T) => void, { immediate = false } = {}): () => void {\n      const subscriber: Subscriber<T> = { callback, isActive: true };\n      subscribers.add(subscriber);\n      if (immediate) {\n        isolateCallbackFailure(\n          'callback.signal-failed',\n          'An immediate signal subscriber failed.',\n          () => callback(current),\n        );\n      }\n      return () => {\n        subscriber.isActive = false;\n        subscribers.delete(subscriber);\n      };\n    },\n  };\n}\n\ninterface ContextRequestDetail {\n  key: symbol;\n  /** Required by the WICG protocol for subscribed third-party requests. */\n  subscribe: boolean;\n  provide(value: unknown): void;\n}\n\n/**\n * One context request on the private event transport.\n *\n * @internal\n */\nexport interface ContextRequest {\n  el: Element;\n  key: symbol;\n  subscribe: boolean;\n  resolve(value: unknown, providerNode: Node | null): void;\n}\n\ninterface ContextRuntimeState {\n  pendingRequests: Set<ContextRequest>;\n  rootProviders: Map<symbol, unknown>;\n}\n\nconst contextState = /* @__PURE__ */ getSharedRuntimeSlot<ContextRuntimeState>(\n  'context',\n  2,\n  () => ({\n    pendingRequests: new Set(),\n    rootProviders: new Map(),\n  }),\n);\nconst { pendingRequests, rootProviders } = contextState;\n\n/**\n * Dispatch one request and report whether a provider answered synchronously.\n *\n * @internal\n */\nexport function dispatchContextRequest(request: ContextRequest): boolean {\n  let isAnswered = false;\n  let event!: CustomEvent<ContextRequestDetail>;\n  const detail: ContextRequestDetail = {\n    key: request.key,\n    subscribe: request.subscribe,\n    provide(value) {\n      isAnswered = true;\n      pendingRequests.delete(request);\n      const provider = event.currentTarget;\n      request.resolve(\n        value,\n        provider !== null && 'contains' in provider ? (provider as Node) : null,\n      );\n    },\n  };\n  event = new CustomEvent(CONTEXT_REQUEST, { bubbles: true, detail });\n  request.el.dispatchEvent(event);\n  return isAnswered;\n}\n\n/** Keep an unanswered request available for a provider that appears later. @internal */\nexport function retainContextRequest(request: ContextRequest): void {\n  pendingRequests.add(request);\n}\n\n/** Stop replaying an unanswered request. @internal */\nexport function cancelContextRequest(request: ContextRequest): void {\n  pendingRequests.delete(request);\n}\n\n/**\n * Provide a value verbatim for a subtree. The nearest provider wins.\n * @link https://js-toolkit-v4.studiometa.dev/api/context/provideContext.html\n */\nexport function provideContext<T>(\n  el: Element,\n  key: ContextKey<T>,\n  value: T,\n): { value: T; dispose: () => void } {\n  const onRequest = (event: Event) => {\n    const { detail } = event as CustomEvent<ContextRequestDetail>;\n    if (detail?.key !== key) {\n      return;\n    }\n    event.stopPropagation();\n    detail.provide(value);\n  };\n  el.addEventListener(CONTEXT_REQUEST, onRequest);\n\n  // Re-dispatch pending subtree requests so the nearest provider still wins.\n  // oxlint-disable-next-line no-useless-spread\n  for (const request of [...pendingRequests]) {\n    if (request.key === key && el.contains(request.el)) {\n      dispatchContextRequest(request);\n    }\n  }\n\n  return {\n    value,\n    dispose: () => el.removeEventListener(CONTEXT_REQUEST, onRequest),\n  };\n}\n\n/**\n * Provide a document-wide value created once per key. Nearer providers override it.\n *\n * Root providers are page-lifetime and cannot be disposed.\n * @link https://js-toolkit-v4.studiometa.dev/api/context/provideRootContext.html\n */\nexport function provideRootContext<T>(key: ContextKey<T>, create: () => T): T {\n  if (rootProviders.has(key)) {\n    return rootProviders.get(key) as T;\n  }\n  const value = create();\n  rootProviders.set(key, value);\n  provideContext(document.documentElement, key, value);\n  return value;\n}\n\n/**\n * Resolve the nearest provided value for `key`, now or when a provider\n * appears. This request is one-shot: the first answer settles the promise and\n * removes the request.\n *\n * The promise stays pending while no provider exists. `cancel()` removes that\n * pending request and does nothing after an answer.\n * @link https://js-toolkit-v4.studiometa.dev/api/context/injectContext.html\n */\nexport function injectContext<T>(\n  el: Element,\n  key: ContextKey<T>,\n): { promise: Promise<T>; cancel: () => void } {\n  let request!: ContextRequest;\n  const promise = new Promise<T>((resolve) => {\n    request = {\n      el,\n      key,\n      subscribe: false,\n      resolve: (value) => resolve(value as T),\n    };\n    if (!dispatchContextRequest(request)) {\n      retainContextRequest(request);\n    }\n  });\n  return { promise, cancel: () => cancelContextRequest(request) };\n}\n\n/**\n * Resolve the nearest provided value synchronously, or return `undefined`.\n * @link https://js-toolkit-v4.studiometa.dev/api/context/injectContextSync.html\n */\nexport function injectContextSync<T>(el: Element, key: ContextKey<T>): T | undefined {\n  let resolved: T | undefined;\n  dispatchContextRequest({\n    el,\n    key,\n    subscribe: false,\n    resolve: (value) => {\n      resolved = value as T;\n    },\n  });\n  return resolved;\n}\n"],"mappings":"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"}

package/dist/decorators.d.ts

@@ -0,0 +1,70 @@
+import { ContextKey } from "./context.js";
+import { Base, BaseConfig, BaseConstructor, ChildrenCollection, DelegatedEvent, GlobalEvent, RefEvent, WatchChildrenCallbacks } from "./Base.js";
+//#region src/decorators.d.ts
+/** Decorator syntax requires transpilation; use the function APIs without a build step. */
+type ChildHandler<T extends Base = Base, K extends string = string> = (this: any, payload: DelegatedEvent<T, K>) => void;
+type RefHandler<T extends HTMLElement = HTMLElement> = (this: any, payload: RefEvent<T>) => void;
+type GlobalHandler<T extends Event = Event> = (this: any, payload: GlobalEvent<T>) => void;
+/** Maps known global event names to their platform type and custom names to `Event`. */
+type PlatformEvent<M, K extends string> = K extends keyof M ? M[K] extends Event ? M[K] : Event : Event;
+interface ValueDecorator<Value> {
+  <This extends Base>(target: undefined, context: ClassFieldDecoratorContext<This, Value>): (this: This, initial: Value) => Value;
+  <This extends Base>(target: ClassAccessorDecoratorTarget<This, Value>, context: ClassAccessorDecoratorContext<This, Value>): ClassAccessorDecoratorResult<This, Value>;
+}
+interface ValueObserver<Value> {
+  <This extends Base>(target: undefined, context: ClassFieldDecoratorContext<This, Value>): void;
+  <This extends Base>(target: ClassAccessorDecoratorTarget<This, Value>, context: ClassAccessorDecoratorContext<This, Value>): void;
+}
+/**
+ * Decorate a method as an event handler.
+ * One string binds an event on the component root. A string and event type bind a child or ref.
+ * A component class binds that child type. `window` and `document` bind global events.
+ * @link https://js-toolkit-v4.studiometa.dev/api/decorators/on.html
+ */
+declare function on<K extends keyof HTMLElementEventMap>(type: K): <This extends Base>(value: (this: This, event: HTMLElementEventMap[K]) => void, context: ClassMethodDecoratorContext<This, (this: This, event: HTMLElementEventMap[K]) => void>) => void;
+/**
+ * A name outside the platform's map is a component event, whose detail only its
+ * emitter knows, so the handler declares the event type it expects.
+ */
+declare function on<E extends Event = Event>(type: string): <This extends Base>(value: (this: This, event: E) => void, context: ClassMethodDecoratorContext<This, (this: This, event: E) => void>) => void;
+declare function on<K extends string>(target: typeof window, type: K): <This extends Base>(value: GlobalHandler<PlatformEvent<WindowEventMap, K>>, context: ClassMethodDecoratorContext<This, GlobalHandler<PlatformEvent<WindowEventMap, K>>>) => void;
+declare function on<K extends string>(target: typeof document, type: K): <This extends Base>(value: GlobalHandler<PlatformEvent<DocumentEventMap, K>>, context: ClassMethodDecoratorContext<This, GlobalHandler<PlatformEvent<DocumentEventMap, K>>>) => void;
+declare function on<T extends BaseConstructor, K extends string>(child: T, type: K): <This extends Base>(value: ChildHandler<InstanceType<T>, K>, context: ClassMethodDecoratorContext<This, ChildHandler<InstanceType<T>, K>>) => void;
+/** A string target can be a child or ref. Ref names must include the `[]` suffix declared in `config.refs`. */
+declare function on(child: string, type: string): <T extends Base, E extends HTMLElement, This extends Base>(value: ChildHandler<T> | RefHandler<E>, context: ClassMethodDecoratorContext<This, ChildHandler<T> | RefHandler<E>>) => void;
+type VoidMethod<This, Args extends unknown[]> = (this: This, ...args: Args) => void;
+/**
+ * Schedule the method body in the next read phase. Destruction cancels pending work.
+ * @link https://js-toolkit-v4.studiometa.dev/api/decorators/read-write.html
+ */
+declare const read: <This extends Base, Args extends unknown[]>(value: VoidMethod<This, Args>, _context: ClassMethodDecoratorContext<This, VoidMethod<This, Args>>) => VoidMethod<This, Args>;
+/**
+ * Schedule the method body in the next write phase. Destruction cancels pending work.
+ * @link https://js-toolkit-v4.studiometa.dev/api/decorators/read-write.html
+ */
+declare const write: <This extends Base, Args extends unknown[]>(value: VoidMethod<This, Args>, _context: ClassMethodDecoratorContext<This, VoidMethod<This, Args>>) => VoidMethod<This, Args>;
+/**
+ * Set the component config and register the class when it is defined.
+ * @link https://js-toolkit-v4.studiometa.dev/api/decorators/component.html
+ */
+declare function component(config: BaseConfig): <T extends BaseConstructor>(value: T, context: ClassDecoratorContext<T>) => void;
+/**
+ * Provide the decorated field to descendants. The nearest provider wins.
+ * @link https://js-toolkit-v4.studiometa.dev/api/decorators/provide.html
+ */
+declare function provide<T>(key: ContextKey<T>): ValueDecorator<T>;
+/**
+ * Resolve the nearest provided value into the decorated field. The field stays `undefined` until resolution.
+ * Resolution starts once at construction and does not restart after destruction.
+ * @link https://js-toolkit-v4.studiometa.dev/api/decorators/inject.html
+ */
+declare function inject<T>(key: ContextKey<T>): ValueObserver<T | undefined>;
+/**
+ * Track mounted descendants as a live collection. Strings match `config.name` exactly.
+ * Component classes include named subclasses. Callbacks bind to the host component.
+ * @link https://js-toolkit-v4.studiometa.dev/api/decorators/children.html
+ */
+declare function children<T extends Base = Base, Host = any>(name: string, callbacks?: WatchChildrenCallbacks<T> & ThisType<Host>): ValueDecorator<ChildrenCollection<T>>;
+declare function children<T extends BaseConstructor, Host = any>(ComponentClass: T, callbacks?: WatchChildrenCallbacks<InstanceType<T>> & ThisType<Host>): ValueDecorator<ChildrenCollection<InstanceType<T>>>;
+//#endregion
+export { children, component, inject, on, provide, read, write };

package/dist/decorators.js

@@ -0,0 +1,189 @@
+import { isBaseConstructor } from "./component-brand.js";
+import { warnOnce } from "./diagnostics.js";
+import { HANDLER_REGISTRATIONS } from "./protocol-symbols.js";
+import { resolveConfig } from "./Base.js";
+import { registerComponent } from "./registry.js";
+//#region src/decorators.ts
+/**
+* Global targets use identity checks. Component classes use their merged config name because it is their mount identity.
+* Other `EventTarget` values are invalid because decorators have no component instance or mount cycle.
+*/
+function resolveHandlerTarget(target, maybeType) {
+	if (typeof target === "string") return maybeType === void 0 ? {
+		target: null,
+		child: null,
+		type: target
+	} : {
+		target: null,
+		child: target,
+		type: maybeType
+	};
+	if (maybeType === void 0) throw new TypeError("[@on] a target value must be followed by an event type.");
+	if (isBaseConstructor(target)) return {
+		target: null,
+		child: resolveConfig(target).name,
+		type: maybeType
+	};
+	else if (target === window || target === document) return {
+		target,
+		child: null,
+		type: maybeType
+	};
+	throw new TypeError("[@on] the target must be a child name, a component class, `window` or `document`. Bind any other EventTarget from `mounted()`, where the instance and its cleanup exist.");
+}
+function withInitializer(context, initialize) {
+	return context.kind === "accessor" ? { init: initialize } : initialize;
+}
+function on(target, maybeType) {
+	const registration = resolveHandlerTarget(target, maybeType);
+	return function decorate(value, context) {
+		context.addInitializer(function initialize() {
+			(this[HANDLER_REGISTRATIONS] ??= []).push({
+				...registration,
+				method: context.name,
+				handler: value
+			});
+		});
+	};
+}
+function inPhase(phase) {
+	return function decorate(value, _context) {
+		return function scheduled(...args) {
+			this[phase](() => value.apply(this, args));
+		};
+	};
+}
+/**
+* Schedule the method body in the next read phase. Destruction cancels pending work.
+* @link https://js-toolkit-v4.studiometa.dev/api/decorators/read-write.html
+*/
+const read = inPhase("$read");
+/**
+* Schedule the method body in the next write phase. Destruction cancels pending work.
+* @link https://js-toolkit-v4.studiometa.dev/api/decorators/read-write.html
+*/
+const write = inPhase("$write");
+/** Config keys that merge rather than override; the rest are compared as scalars. */
+const COLLECTION_KEYS = /* @__PURE__ */ new Set([
+	"refs",
+	"options",
+	"components"
+]);
+/**
+* Merge the two config declarations one class can carry, by the rules
+* `resolveConfig()` applies to a chain: collections merge, declared values
+* override. A key neither side declares stays absent, so the written config
+* keeps the shorthand shape the author wrote.
+*/
+function mergeOwnConfigs(base, extra) {
+	const merged = {
+		...base,
+		...extra
+	};
+	if (base.refs && extra.refs) merged.refs = [.../* @__PURE__ */ new Set([...base.refs, ...extra.refs])];
+	if (base.options && extra.options) merged.options = {
+		...base.options,
+		...extra.options
+	};
+	if (base.components && extra.components) merged.components = {
+		...base.components,
+		...extra.components
+	};
+	return merged;
+}
+/**
+* Keys the two declarations give different values, `options` and `components`
+* entry by entry. `refs` are a union, so declaring one twice keeps it and is
+* not reported. Only these keys make the precedence rule observable, so they
+* are the only ones worth a warning.
+*/
+function conflictingKeys(base, extra) {
+	return [
+		...conflictingScalars(base, extra),
+		...conflictingEntries("options", base, extra),
+		...conflictingEntries("components", base, extra)
+	];
+}
+/** Top-level keys both declare with different values; the collections are compared per entry. */
+function conflictingScalars(base, extra) {
+	const conflicts = [];
+	const scalars = base;
+	for (const [key, value] of Object.entries(extra)) if (!COLLECTION_KEYS.has(key) && scalars[key] !== void 0 && scalars[key] !== value) conflicts.push(key);
+	return conflicts;
+}
+/** Entries of one collection both declare with different values. */
+function conflictingEntries(key, base, extra) {
+	const own = base[key];
+	const incoming = extra[key];
+	if (!own || !incoming) return [];
+	const conflicts = [];
+	for (const [entry, value] of Object.entries(incoming)) if (own[entry] !== void 0 && own[entry] !== value) conflicts.push(`${key}.${entry}`);
+	return conflicts;
+}
+/**
+* Set the component config and register the class when it is defined.
+* @link https://js-toolkit-v4.studiometa.dev/api/decorators/component.html
+*/
+function component(config) {
+	return function decorate(value, context) {
+		const inherited = value.config;
+		const written = {
+			...inherited,
+			...config
+		};
+		value.config = written;
+		context.addInitializer(function initialize() {
+			if (this.config !== written) {
+				const field = this.config;
+				const merged = mergeOwnConfigs({
+					...inherited,
+					...field
+				}, config);
+				this.config = merged;
+				const conflicts = conflictingKeys(field, config);
+				if (conflicts.length > 0) warnOnce(this, "config", "component.config-conflict", `"${merged.name}" declares ${conflicts.join(", ")} in both @component() and its static config; the @component() value was kept. Declare each key once.`, { component: merged.name });
+			}
+			registerComponent(this);
+		});
+	};
+}
+/**
+* Provide the decorated field to descendants. The nearest provider wins.
+* @link https://js-toolkit-v4.studiometa.dev/api/decorators/provide.html
+*/
+function provide(key) {
+	return function decorate(_target, context) {
+		return withInitializer(context, function initialize(initial) {
+			return this.$provide(key, initial);
+		});
+	};
+}
+/**
+* Resolve the nearest provided value into the decorated field. The field stays `undefined` until resolution.
+* Resolution starts once at construction and does not restart after destruction.
+* @link https://js-toolkit-v4.studiometa.dev/api/decorators/inject.html
+*/
+function inject(key) {
+	return function decorate(_target, context) {
+		context.addInitializer(function initialize() {
+			this.$inject(key).then((value) => {
+				context.access.set(this, value);
+			});
+		});
+	};
+}
+function children(target, callbacks) {
+	return function decorate(_target, context) {
+		return withInitializer(context, function initialize() {
+			const bound = callbacks && {
+				added: callbacks.added?.bind(this),
+				removed: callbacks.removed?.bind(this)
+			};
+			return typeof target === "string" ? this.$watchChildren(target, bound) : this.$watchChildren(target, bound);
+		});
+	};
+}
+//#endregion
+export { children, component, inject, on, provide, read, write };
+
+//# sourceMappingURL=decorators.js.map

package/dist/decorators.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"decorators.js","names":[],"sources":["../src/decorators.ts"],"sourcesContent":["import {\n  type Base,\n  type BaseConfig,\n  type BaseConstructor,\n  type ChildrenCollection,\n  type DelegatedEvent,\n  type GlobalEvent,\n  type HandlerRegistration,\n  type RefEvent,\n  resolveConfig,\n  type WatchChildrenCallbacks,\n} from './Base.js';\nimport { isBaseConstructor } from './component-brand.js';\nimport type { ContextKey } from './context.js';\nimport { warnOnce } from './diagnostics.js';\nimport { HANDLER_REGISTRATIONS } from './protocol-symbols.js';\nimport { registerComponent } from './registry.js';\n\n/** Decorator syntax requires transpilation; use the function APIs without a build step. */\n\n// The decorator cannot know the host class of a decorated method.\ntype ChildHandler<T extends Base = Base, K extends string = string> = (\n  this: any,\n  payload: DelegatedEvent<T, K>,\n) => void;\ntype RefHandler<T extends HTMLElement = HTMLElement> = (this: any, payload: RefEvent<T>) => void;\ntype GlobalHandler<T extends Event = Event> = (this: any, payload: GlobalEvent<T>) => void;\n\n/** Maps known global event names to their platform type and custom names to `Event`. */\ntype PlatformEvent<M, K extends string> = K extends keyof M\n  ? M[K] extends Event\n    ? M[K]\n    : Event\n  : Event;\n\ntype OnTarget = string | BaseConstructor | typeof window | typeof document;\n\n/**\n * Global targets use identity checks. Component classes use their merged config name because it is their mount identity.\n * Other `EventTarget` values are invalid because decorators have no component instance or mount cycle.\n */\nfunction resolveHandlerTarget(\n  target: OnTarget,\n  maybeType?: string,\n): Omit<HandlerRegistration, 'handler' | 'method'> {\n  if (typeof target === 'string') {\n    return maybeType === undefined\n      ? { target: null, child: null, type: target }\n      : { target: null, child: target, type: maybeType };\n  }\n\n  if (maybeType === undefined) {\n    throw new TypeError('[@on] a target value must be followed by an event type.');\n  }\n\n  if (isBaseConstructor(target)) {\n    return { target: null, child: resolveConfig(target).name, type: maybeType };\n  } else if (target === window || target === document) {\n    return { target, child: null, type: maybeType };\n  }\n\n  throw new TypeError(\n    '[@on] the target must be a child name, a component class, `window` or `document`. ' +\n      'Bind any other EventTarget from `mounted()`, where the instance and its cleanup exist.',\n  );\n}\n\n/** A value decorator for a field or an `accessor` field. */\ntype ValueDecoratorContext<This, Value> =\n  | ClassFieldDecoratorContext<This, Value>\n  | ClassAccessorDecoratorContext<This, Value>;\n\ninterface ValueDecorator<Value> {\n  <This extends Base>(\n    target: undefined,\n    context: ClassFieldDecoratorContext<This, Value>,\n  ): (this: This, initial: Value) => Value;\n  <This extends Base>(\n    target: ClassAccessorDecoratorTarget<This, Value>,\n    context: ClassAccessorDecoratorContext<This, Value>,\n  ): ClassAccessorDecoratorResult<This, Value>;\n}\n\ninterface ValueObserver<Value> {\n  <This extends Base>(target: undefined, context: ClassFieldDecoratorContext<This, Value>): void;\n  <This extends Base>(\n    target: ClassAccessorDecoratorTarget<This, Value>,\n    context: ClassAccessorDecoratorContext<This, Value>,\n  ): void;\n}\n\nfunction withInitializer<This extends Base, Value>(\n  context: ValueDecoratorContext<This, Value>,\n  initialize: (this: This, initial: Value) => Value,\n) {\n  return context.kind === 'accessor' ? { init: initialize } : initialize;\n}\n\n/**\n * Decorate a method as an event handler.\n * One string binds an event on the component root. A string and event type bind a child or ref.\n * A component class binds that child type. `window` and `document` bind global events.\n * @link https://js-toolkit-v4.studiometa.dev/api/decorators/on.html\n */\nexport function on<K extends keyof HTMLElementEventMap>(\n  type: K,\n): <This extends Base>(\n  value: (this: This, event: HTMLElementEventMap[K]) => void,\n  context: ClassMethodDecoratorContext<This, (this: This, event: HTMLElementEventMap[K]) => void>,\n) => void;\n/**\n * A name outside the platform's map is a component event, whose detail only its\n * emitter knows, so the handler declares the event type it expects.\n */\nexport function on<E extends Event = Event>(\n  type: string,\n): <This extends Base>(\n  value: (this: This, event: E) => void,\n  context: ClassMethodDecoratorContext<This, (this: This, event: E) => void>,\n) => void;\nexport function on<K extends string>(\n  target: typeof window,\n  type: K,\n): <This extends Base>(\n  value: GlobalHandler<PlatformEvent<WindowEventMap, K>>,\n  context: ClassMethodDecoratorContext<This, GlobalHandler<PlatformEvent<WindowEventMap, K>>>,\n) => void;\nexport function on<K extends string>(\n  target: typeof document,\n  type: K,\n): <This extends Base>(\n  value: GlobalHandler<PlatformEvent<DocumentEventMap, K>>,\n  context: ClassMethodDecoratorContext<This, GlobalHandler<PlatformEvent<DocumentEventMap, K>>>,\n) => void;\nexport function on<T extends BaseConstructor, K extends string>(\n  child: T,\n  type: K,\n): <This extends Base>(\n  value: ChildHandler<InstanceType<T>, K>,\n  context: ClassMethodDecoratorContext<This, ChildHandler<InstanceType<T>, K>>,\n) => void;\n/** A string target can be a child or ref. Ref names must include the `[]` suffix declared in `config.refs`. */\nexport function on(\n  child: string,\n  type: string,\n): <T extends Base, E extends HTMLElement, This extends Base>(\n  value: ChildHandler<T> | RefHandler<E>,\n  context: ClassMethodDecoratorContext<This, ChildHandler<T> | RefHandler<E>>,\n) => void;\nexport function on(target: OnTarget, maybeType?: string) {\n  const registration = resolveHandlerTarget(target, maybeType);\n  return function decorate(\n    value: HandlerRegistration['handler'],\n    context: ClassMethodDecoratorContext<any, any>,\n  ): void {\n    context.addInitializer(function initialize(this: Base) {\n      // `context.name` rather than `value.name`: `@read`/`@write` hand their\n      // wrapper down, and it is named after the wrapper. The context names the\n      // method being decorated whatever else is stacked on it, which is what\n      // makes the magic name scan skip this handler in either order.\n      (this[HANDLER_REGISTRATIONS] ??= []).push({\n        ...registration,\n        method: context.name,\n        handler: value,\n      });\n    });\n  };\n}\n\ntype VoidMethod<This, Args extends unknown[]> = (this: This, ...args: Args) => void;\n\nfunction inPhase(phase: '$read' | '$write') {\n  return function decorate<This extends Base, Args extends unknown[]>(\n    value: VoidMethod<This, Args>,\n    _context: ClassMethodDecoratorContext<This, VoidMethod<This, Args>>,\n  ): VoidMethod<This, Args> {\n    return function scheduled(this: This, ...args: Args) {\n      this[phase](() => value.apply(this, args));\n    };\n  };\n}\n\n/**\n * Schedule the method body in the next read phase. Destruction cancels pending work.\n * @link https://js-toolkit-v4.studiometa.dev/api/decorators/read-write.html\n */\nexport const read = inPhase('$read');\n\n/**\n * Schedule the method body in the next write phase. Destruction cancels pending work.\n * @link https://js-toolkit-v4.studiometa.dev/api/decorators/read-write.html\n */\nexport const write = inPhase('$write');\n\n/** Config keys that merge rather than override; the rest are compared as scalars. */\nconst COLLECTION_KEYS = new Set(['refs', 'options', 'components']);\n\n/**\n * Merge the two config declarations one class can carry, by the rules\n * `resolveConfig()` applies to a chain: collections merge, declared values\n * override. A key neither side declares stays absent, so the written config\n * keeps the shorthand shape the author wrote.\n */\nfunction mergeOwnConfigs(base: BaseConfig, extra: BaseConfig): BaseConfig {\n  const merged: BaseConfig = { ...base, ...extra };\n  if (base.refs && extra.refs) {\n    merged.refs = [...new Set([...base.refs, ...extra.refs])];\n  }\n  if (base.options && extra.options) {\n    merged.options = { ...base.options, ...extra.options };\n  }\n  if (base.components && extra.components) {\n    merged.components = { ...base.components, ...extra.components };\n  }\n  return merged;\n}\n\n/**\n * Keys the two declarations give different values, `options` and `components`\n * entry by entry. `refs` are a union, so declaring one twice keeps it and is\n * not reported. Only these keys make the precedence rule observable, so they\n * are the only ones worth a warning.\n */\nfunction conflictingKeys(base: BaseConfig, extra: BaseConfig): string[] {\n  return [\n    ...conflictingScalars(base, extra),\n    ...conflictingEntries('options', base, extra),\n    ...conflictingEntries('components', base, extra),\n  ];\n}\n\n/** Top-level keys both declare with different values; the collections are compared per entry. */\nfunction conflictingScalars(base: BaseConfig, extra: BaseConfig): string[] {\n  const conflicts: string[] = [];\n  const scalars = base as unknown as Record<string, unknown>;\n  for (const [key, value] of Object.entries(extra)) {\n    if (!COLLECTION_KEYS.has(key) && scalars[key] !== undefined && scalars[key] !== value) {\n      conflicts.push(key);\n    }\n  }\n  return conflicts;\n}\n\n/** Entries of one collection both declare with different values. */\nfunction conflictingEntries(\n  key: 'options' | 'components',\n  base: BaseConfig,\n  extra: BaseConfig,\n): string[] {\n  const own = base[key];\n  const incoming = extra[key];\n  if (!own || !incoming) {\n    return [];\n  }\n  const conflicts: string[] = [];\n  for (const [entry, value] of Object.entries(incoming)) {\n    if (own[entry] !== undefined && own[entry] !== value) {\n      conflicts.push(`${key}.${entry}`);\n    }\n  }\n  return conflicts;\n}\n\n/**\n * Set the component config and register the class when it is defined.\n * @link https://js-toolkit-v4.studiometa.dev/api/decorators/component.html\n */\nexport function component(config: BaseConfig) {\n  return function decorate<T extends BaseConstructor>(\n    value: T,\n    context: ClassDecoratorContext<T>,\n  ): void {\n    const inherited = value.config;\n    // Copying the inherited config adds nothing to the merged one —\n    // `resolveConfig()` walks the prototype chain — but `isBaseConstructor()`\n    // reads `config.name` straight off the class, and cannot call\n    // `resolveConfig()` because `Base` imports the brand. A config written\n    // without a name, as an untyped subclass adding config to its parent's\n    // does, would leave the class registered under the name it inherited yet\n    // rejected by every brand check: `config.components` entries,\n    // `@on(Class, type)` and lazy import resolution.\n    const written = { ...inherited, ...config };\n    value.config = written;\n\n    context.addInitializer(function initialize(this: T) {\n      // Static field initializers run after class decorators, so a `static\n      // config` on the same class has replaced the object written above and\n      // the decorator's declaration would be gone. Class initializers run\n      // after those fields, which is the first moment both declarations exist:\n      // merge them, decorator last — the direction it already has over the\n      // inherited config. Initializers still run while the class definition\n      // evaluates, so `this.config` is final before any statement following\n      // the class, `registerComponent()` at module scope included.\n      if (this.config !== written) {\n        const field = this.config;\n        const merged = mergeOwnConfigs({ ...inherited, ...field }, config);\n        this.config = merged;\n        const conflicts = conflictingKeys(field, config);\n        if (conflicts.length > 0) {\n          warnOnce(\n            this,\n            'config',\n            'component.config-conflict',\n            `\"${merged.name}\" declares ${conflicts.join(', ')} in both @component() and its static config; the @component() value was kept. Declare each key once.`,\n            { component: merged.name },\n          );\n        }\n      }\n      registerComponent(this);\n    });\n  };\n}\n\n/**\n * Provide the decorated field to descendants. The nearest provider wins.\n * @link https://js-toolkit-v4.studiometa.dev/api/decorators/provide.html\n */\nexport function provide<T>(key: ContextKey<T>): ValueDecorator<T> {\n  return function decorate<This extends Base>(\n    _target: unknown,\n    context: ValueDecoratorContext<This, T>,\n  ) {\n    return withInitializer(context, function initialize(this: This, initial: T) {\n      return this.$provide(key, initial);\n    });\n  } as ValueDecorator<T>;\n}\n\n/**\n * Resolve the nearest provided value into the decorated field. The field stays `undefined` until resolution.\n * Resolution starts once at construction and does not restart after destruction.\n * @link https://js-toolkit-v4.studiometa.dev/api/decorators/inject.html\n */\nexport function inject<T>(key: ContextKey<T>): ValueObserver<T | undefined> {\n  return function decorate<This extends Base>(\n    _target: unknown,\n    context: ValueDecoratorContext<This, T | undefined>,\n  ): void {\n    context.addInitializer(function initialize(this: This) {\n      void this.$inject(key).then((value) => {\n        context.access.set(this, value);\n      });\n    });\n  };\n}\n\n/**\n * Track mounted descendants as a live collection. Strings match `config.name` exactly.\n * Component classes include named subclasses. Callbacks bind to the host component.\n * @link https://js-toolkit-v4.studiometa.dev/api/decorators/children.html\n */\nexport function children<T extends Base = Base, Host = any>(\n  name: string,\n  callbacks?: WatchChildrenCallbacks<T> & ThisType<Host>,\n): ValueDecorator<ChildrenCollection<T>>;\nexport function children<T extends BaseConstructor, Host = any>(\n  ComponentClass: T,\n  callbacks?: WatchChildrenCallbacks<InstanceType<T>> & ThisType<Host>,\n): ValueDecorator<ChildrenCollection<InstanceType<T>>>;\nexport function children(\n  target: string | BaseConstructor,\n  callbacks?: WatchChildrenCallbacks & ThisType<any>,\n): ValueDecorator<ChildrenCollection> {\n  return function decorate<This extends Base>(\n    _target: unknown,\n    context: ValueDecoratorContext<This, ChildrenCollection>,\n  ) {\n    return withInitializer(context, function initialize(this: This) {\n      const bound = callbacks && {\n        added: callbacks.added?.bind(this),\n        removed: callbacks.removed?.bind(this),\n      };\n      return typeof target === 'string'\n        ? this.$watchChildren(target, bound)\n        : this.$watchChildren(target, bound);\n    });\n  } as ValueDecorator<ChildrenCollection>;\n}\n"],"mappings":"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"}

package/dist/diagnostic-contract.d.ts

@@ -0,0 +1,104 @@
+//#region src/diagnostic-contract.d.ts
+/**
+ * Stable codes carried by toolkit diagnostics.
+ * @link https://js-toolkit-v4.studiometa.dev/api/diagnostics/DIAGNOSTICS.html
+ */
+declare const DIAGNOSTICS: Readonly<{
+  readonly attribute: Readonly<{
+    readonly unknownQualifier: 'attribute.unknown-qualifier';
+  }>;
+  readonly callback: Readonly<{
+    readonly signalFailed: 'callback.signal-failed';
+    readonly contextSubscriptionFailed: 'callback.context-subscription-failed';
+    readonly contextTeardownFailed: 'callback.context-teardown-failed';
+    readonly attributeWatcherFailed: 'callback.attribute-watcher-failed';
+    readonly serviceFailed: 'callback.service-failed';
+    readonly schedulerTickFailed: 'callback.scheduler-tick-failed';
+    readonly scheduledTaskFailed: 'callback.scheduled-task-failed';
+    readonly domUpdateRunnerFailed: 'callback.dom-update-runner-failed';
+    readonly extendableEventExtensionFailed: 'callback.extendable-event-extension-failed';
+  }>;
+  readonly component: Readonly<{
+    readonly loadFailed: 'component.load-failed';
+    readonly mountFailed: 'component.mount-failed';
+    readonly lifecycleFailed: 'component.lifecycle-failed';
+    readonly invalidMountStrategy: 'component.invalid-mount-strategy';
+    readonly invalidFamilyDeclaration: 'component.invalid-family-declaration';
+    readonly configConflict: 'component.config-conflict';
+  }>;
+  readonly event: Readonly<{
+    readonly invalidEmitPayload: 'event.invalid-emit-payload';
+  }>;
+  readonly manifest: Readonly<{
+    readonly duplicateToken: 'manifest.duplicate-token';
+  }>;
+  readonly option: Readonly<{
+    readonly literalDefault: 'option.literal-default';
+  }>;
+  readonly protocol: Readonly<{
+    readonly lateRegistration: 'protocol.late-registration';
+    readonly unappliedDomUpdate: 'protocol.unapplied-dom-update';
+  }>;
+  readonly ref: Readonly<{
+    readonly mismatch: 'ref.mismatch';
+  }>;
+  readonly registry: Readonly<{
+    readonly conflict: 'registry.conflict';
+    readonly lazyNameMismatch: 'registry.lazy-name-mismatch';
+  }>;
+  readonly responsive: Readonly<{
+    readonly unknownBreakpoint: 'responsive.unknown-breakpoint';
+  }>;
+  readonly scheduler: Readonly<{
+    readonly backgroundPostFailed: 'scheduler.background-post-failed';
+  }>;
+  readonly service: Readonly<{
+    readonly missingTarget: 'service.missing-target';
+  }>;
+  readonly storage: Readonly<{
+    readonly accessFailed: 'storage.access-failed';
+    readonly deserializeFailed: 'storage.deserialize-failed';
+    readonly serializeFailed: 'storage.serialize-failed';
+  }>;
+  readonly swap: Readonly<{
+    readonly selfIgnored: 'swap.self-ignored';
+  }>;
+}>;
+type ToolkitDiagnosticSeverity = 'warning' | 'error';
+type NestedValue<T> = T extends string ? T : { [K in keyof T]: NestedValue<T[K]>; }[keyof T];
+/** One stable value from {@link DIAGNOSTICS}. */
+type ToolkitCoreDiagnosticCode = NestedValue<typeof DIAGNOSTICS>;
+/**
+ * A code minted outside core, in the same `namespace.detail` shape.
+ *
+ * The channel is only worth having if a consumer can be told apart on it: a
+ * listener filters by code, so a component reporting through a shared generic
+ * code would be unfilterable, and one reporting through a core code would be
+ * indistinguishable from core itself. The template literal is the loosest
+ * thing that still keeps the shape a filter can rely on — `startsWith('figure.')`
+ * works because the namespace is mandatory.
+ */
+type ToolkitConsumerDiagnosticCode = `${string}.${string}`;
+/**
+ * A diagnostic code: one of core's own, or a consumer's namespaced one.
+ *
+ * Core's set stays enumerated and documented as {@link DIAGNOSTICS}; the union
+ * with the wider shape is what lets a component outside core report on the same
+ * channel rather than reaching for `console.warn`.
+ */
+type ToolkitDiagnosticCode = ToolkitCoreDiagnosticCode | ToolkitConsumerDiagnosticCode;
+interface ToolkitDiagnosticBaseDetail {
+  readonly code: ToolkitDiagnosticCode;
+  readonly message: string;
+  readonly component?: string;
+}
+/** The payload of the public diagnostic event. */
+type ToolkitDiagnosticDetail = (ToolkitDiagnosticBaseDetail & {
+  readonly severity: 'warning';
+  readonly error?: never;
+}) | (ToolkitDiagnosticBaseDetail & {
+  readonly severity: 'error';
+  readonly error: unknown;
+});
+//#endregion
+export { DIAGNOSTICS, ToolkitConsumerDiagnosticCode, ToolkitCoreDiagnosticCode, ToolkitDiagnosticCode, ToolkitDiagnosticDetail, ToolkitDiagnosticSeverity };