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

package/dist/attributes.js

@@ -0,0 +1,166 @@
+import { kebabCase } from "./utils/strings.js";
+//#region src/attributes.ts
+/**
+* How the framework spells its own attributes, and how it reads a batch of
+* writes to them.
+*
+* One shape covers every attribute the framework reads:
+*
+* ```
+* data-<namespace>[:<qualifier>[.<part>…]]
+* ```
+*
+* A namespace is a whole name, and it is one of two kinds. A **fixed** one is
+* written here or by whoever owns it — `data-component`, `data-mount`,
+* `data-ref`, and in ui `data-on`, `data-track`, `data-bind`. A **generated**
+* one comes from a declaration: every declared option owns the namespace
+* {@link optionAttributeFor} builds for it, so `columns` owns
+* `data-option-columns`. The kind decides the mechanism — a generated
+* namespace's whole set of names is enumerable, so it is registered with the
+* one observer, while a fixed namespace with open qualifiers can only be
+* watched per element. See DESIGN.md §3.
+*
+* Both kinds take exactly one {@link QUALIFIER_SEPARATOR}, and neither reads
+* past it: a qualifier's parts belong to whoever declared the namespace.
+*
+* This module is deliberately a **leaf**: it imports nothing from core. The
+* mutation engine, the registry and `Base` all need the same names, and the
+* modules which used to own them sit downstream of the engine — the engine
+* carried string literals rather than close the cycle
+* `dom-mutations → component-declarations → responsive-options → dom-mutations`.
+* Moving the names down instead of importing them sideways breaks that cycle
+* without the copies. Anything which needs the DOM, a breakpoint or the
+* observer belongs upstream of here, not in this file.
+*/
+/** Declares one or more component names, as whitespace-separated tokens. */
+const COMPONENT_ATTRIBUTE = "data-component";
+/**
+* Overrides the mount strategy of the element's declared components.
+* @link https://js-toolkit-v4.studiometa.dev/api/html/data-mount.html
+*/
+const MOUNT_ATTRIBUTE = "data-mount";
+/** Names an element as a ref of the component which owns it. */
+const REF_ATTRIBUTE = "data-ref";
+/**
+* Every declared option is `data-option-` plus its kebab-cased name.
+*
+* This is a **namespace family**, not a namespace: the name after it is the
+* option's own, so `columns` owns `data-option-columns` — see the grammar
+* below.
+*/
+const OPTION_ATTRIBUTE_PREFIX = "data-option-";
+/**
+* Introduces one qualifier of the namespace on its left, and there is **at most
+* one of these in an attribute the framework reads**.
+*
+* A colon can never appear in a kebab-cased name, so `data-option-columns:s`
+* stays unambiguous where `data-option-columns-s` would not.
+*/
+const QUALIFIER_SEPARATOR = ":";
+/**
+* Splits a qualifier into its parts. Core never reads them: what a part means
+* belongs to whoever owns the namespace — a modifier for `data-on:click.prevent`,
+* a property name for `data-bind:prop.value`.
+*/
+const PART_SEPARATOR = ".";
+/** One qualified spelling: `data-on` + `click.prevent` → `data-on:click.prevent`. */
+function namespacedAttribute(namespace, qualifier) {
+	return `${namespace}:${qualifier}`;
+}
+/**
+* Whether a name belongs to a namespace, plainly or qualified. `data-component`
+* and `data-component:s` both answer yes; `data-components` does not.
+*/
+function isInNamespace(namespace, name) {
+	return name === namespace || name?.startsWith(`${namespace}:`) === true;
+}
+/**
+* The qualifier a name carries within a namespace, or `null` when the name is
+* outside it — the bare namespace included, since a namespace with nothing
+* after the colon declares nothing.
+* @link https://js-toolkit-v4.studiometa.dev/guide/concepts/attribute-grammar.html
+*/
+function namespaceQualifier(namespace, name) {
+	const prefix = `${namespace}:`;
+	return name.startsWith(prefix) ? name.slice(prefix.length) : null;
+}
+/**
+* The part of a qualifier which names the member: `click` of `click.prevent`,
+* `prop` of `prop.value`. The one piece of a qualifier core reads, and only to
+* check it against a vocabulary its owner declared.
+*/
+function qualifierHead(qualifier) {
+	const index = qualifier.indexOf(".");
+	return index === -1 ? qualifier : qualifier.slice(0, index);
+}
+/**
+* The names every page observes, before a single component declares an option.
+* The rest of the observer's filter is accumulated at registration time.
+*/
+const FRAMEWORK_ATTRIBUTES = [
+	COMPONENT_ATTRIBUTE,
+	MOUNT_ATTRIBUTE,
+	REF_ATTRIBUTE
+];
+/** The attribute holding one option's value at the base of the cascade. */
+function optionAttributeFor(name) {
+	return `${OPTION_ATTRIBUTE_PREFIX}${kebabCase(name)}`;
+}
+/**
+* What a present negation resolves to.
+*
+* A boolean reads presence, not value, so the raw string has to carry **which
+* spelling was there** rather than what it said. A NUL character is that
+* signal: the HTML parser replaces it with U+FFFD in an attribute value, so no
+* markup can produce it, and change detection still sees a plain string.
+*/
+const NEGATED_RAW = "\0";
+/**
+* The attribute which turns a boolean option off by being there.
+*
+* `data-option-no-view-transition` is another spelling of
+* `data-option-view-transition="false"`, which is what v3 wrote and what reads
+* better in markup: a flag is present or it is not.
+*/
+function negatedOptionAttributeFor(name) {
+	return `${OPTION_ATTRIBUTE_PREFIX}no-${kebabCase(name)}`;
+}
+/**
+* Whether a name is a declared option's, at any breakpoint. The scoped
+* spellings share the prefix, so one test covers the whole family.
+*/
+function isOptionAttribute(attribute) {
+	return attribute?.startsWith(OPTION_ATTRIBUTE_PREFIX) === true;
+}
+/** Whether a name declares components, plainly or scoped to a breakpoint. */
+function isComponentAttribute(attribute) {
+	return isInNamespace(COMPONENT_ATTRIBUTE, attribute);
+}
+/**
+* Several writes to one attribute in a batch are **one** change, from the value
+* it held before the first write to the value the DOM ends the batch with. So
+* the first previous value wins and every later record is dropped: a morph
+* rewriting an attribute twice must not look like two changes.
+*
+* This is the first half of the coalescing rule; {@link isNetChange} is the
+* second. Declared options, watched attributes and the responsive cascade all
+* answer to it, which is why it is stated here once rather than in each of them.
+*/
+function rememberPreviousValue(previousValues, attribute, previousValue) {
+	if (!previousValues.has(attribute)) previousValues.set(attribute, previousValue);
+}
+/**
+* The second half of the rule: a batch ending where it started changed nothing
+* and is not reported. The comparison is on raw strings — what is in force now
+* against what was in force before — so it holds for an attribute read straight
+* off the element and for a value resolved through the responsive cascade
+* alike, which is what lets a breakpoint crossing and an attribute rewrite be
+* the same kind of event.
+*/
+function isNetChange(value, previousValue) {
+	return value !== previousValue;
+}
+//#endregion
+export { COMPONENT_ATTRIBUTE, FRAMEWORK_ATTRIBUTES, MOUNT_ATTRIBUTE, NEGATED_RAW, OPTION_ATTRIBUTE_PREFIX, PART_SEPARATOR, QUALIFIER_SEPARATOR, REF_ATTRIBUTE, isComponentAttribute, isInNamespace, isNetChange, isOptionAttribute, namespaceQualifier, namespacedAttribute, negatedOptionAttributeFor, optionAttributeFor, qualifierHead, rememberPreviousValue };
+
+//# sourceMappingURL=attributes.js.map

package/dist/attributes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attributes.js","names":[],"sources":["../src/attributes.ts"],"sourcesContent":["/**\n * How the framework spells its own attributes, and how it reads a batch of\n * writes to them.\n *\n * One shape covers every attribute the framework reads:\n *\n * ```\n * data-<namespace>[:<qualifier>[.<part>…]]\n * ```\n *\n * A namespace is a whole name, and it is one of two kinds. A **fixed** one is\n * written here or by whoever owns it — `data-component`, `data-mount`,\n * `data-ref`, and in ui `data-on`, `data-track`, `data-bind`. A **generated**\n * one comes from a declaration: every declared option owns the namespace\n * {@link optionAttributeFor} builds for it, so `columns` owns\n * `data-option-columns`. The kind decides the mechanism — a generated\n * namespace's whole set of names is enumerable, so it is registered with the\n * one observer, while a fixed namespace with open qualifiers can only be\n * watched per element. See DESIGN.md §3.\n *\n * Both kinds take exactly one {@link QUALIFIER_SEPARATOR}, and neither reads\n * past it: a qualifier's parts belong to whoever declared the namespace.\n *\n * This module is deliberately a **leaf**: it imports nothing from core. The\n * mutation engine, the registry and `Base` all need the same names, and the\n * modules which used to own them sit downstream of the engine — the engine\n * carried string literals rather than close the cycle\n * `dom-mutations → component-declarations → responsive-options → dom-mutations`.\n * Moving the names down instead of importing them sideways breaks that cycle\n * without the copies. Anything which needs the DOM, a breakpoint or the\n * observer belongs upstream of here, not in this file.\n */\n\nimport { kebabCase } from './utils/strings.js';\n\n/** Declares one or more component names, as whitespace-separated tokens. */\nexport const COMPONENT_ATTRIBUTE = 'data-component';\n\n/**\n * Overrides the mount strategy of the element's declared components.\n * @link https://js-toolkit-v4.studiometa.dev/api/html/data-mount.html\n */\nexport const MOUNT_ATTRIBUTE = 'data-mount';\n\n/** Names an element as a ref of the component which owns it. */\nexport const REF_ATTRIBUTE = 'data-ref';\n\n/**\n * Every declared option is `data-option-` plus its kebab-cased name.\n *\n * This is a **namespace family**, not a namespace: the name after it is the\n * option's own, so `columns` owns `data-option-columns` — see the grammar\n * below.\n */\nexport const OPTION_ATTRIBUTE_PREFIX = 'data-option-';\n\n/**\n * Introduces one qualifier of the namespace on its left, and there is **at most\n * one of these in an attribute the framework reads**.\n *\n * A colon can never appear in a kebab-cased name, so `data-option-columns:s`\n * stays unambiguous where `data-option-columns-s` would not.\n */\nexport const QUALIFIER_SEPARATOR = ':';\n\n/**\n * Splits a qualifier into its parts. Core never reads them: what a part means\n * belongs to whoever owns the namespace — a modifier for `data-on:click.prevent`,\n * a property name for `data-bind:prop.value`.\n */\nexport const PART_SEPARATOR = '.';\n\n/** One qualified spelling: `data-on` + `click.prevent` → `data-on:click.prevent`. */\nexport function namespacedAttribute(namespace: string, qualifier: string): string {\n  return `${namespace}${QUALIFIER_SEPARATOR}${qualifier}`;\n}\n\n/**\n * Whether a name belongs to a namespace, plainly or qualified. `data-component`\n * and `data-component:s` both answer yes; `data-components` does not.\n */\nexport function isInNamespace(namespace: string, name: string | null): name is string {\n  return name === namespace || name?.startsWith(`${namespace}${QUALIFIER_SEPARATOR}`) === true;\n}\n\n/**\n * The qualifier a name carries within a namespace, or `null` when the name is\n * outside it — the bare namespace included, since a namespace with nothing\n * after the colon declares nothing.\n * @link https://js-toolkit-v4.studiometa.dev/guide/concepts/attribute-grammar.html\n */\nexport function namespaceQualifier(namespace: string, name: string): string | null {\n  const prefix = `${namespace}${QUALIFIER_SEPARATOR}`;\n  return name.startsWith(prefix) ? name.slice(prefix.length) : null;\n}\n\n/**\n * The part of a qualifier which names the member: `click` of `click.prevent`,\n * `prop` of `prop.value`. The one piece of a qualifier core reads, and only to\n * check it against a vocabulary its owner declared.\n */\nexport function qualifierHead(qualifier: string): string {\n  const index = qualifier.indexOf(PART_SEPARATOR);\n  return index === -1 ? qualifier : qualifier.slice(0, index);\n}\n\n/**\n * The names every page observes, before a single component declares an option.\n * The rest of the observer's filter is accumulated at registration time.\n */\nexport const FRAMEWORK_ATTRIBUTES = [COMPONENT_ATTRIBUTE, MOUNT_ATTRIBUTE, REF_ATTRIBUTE] as const;\n\n/** The attribute holding one option's value at the base of the cascade. */\nexport function optionAttributeFor(name: string): string {\n  return `${OPTION_ATTRIBUTE_PREFIX}${kebabCase(name)}`;\n}\n\n/**\n * What a present negation resolves to.\n *\n * A boolean reads presence, not value, so the raw string has to carry **which\n * spelling was there** rather than what it said. A NUL character is that\n * signal: the HTML parser replaces it with U+FFFD in an attribute value, so no\n * markup can produce it, and change detection still sees a plain string.\n */\nexport const NEGATED_RAW = '\\u0000';\n\n/**\n * The attribute which turns a boolean option off by being there.\n *\n * `data-option-no-view-transition` is another spelling of\n * `data-option-view-transition=\"false\"`, which is what v3 wrote and what reads\n * better in markup: a flag is present or it is not.\n */\nexport function negatedOptionAttributeFor(name: string): string {\n  return `${OPTION_ATTRIBUTE_PREFIX}no-${kebabCase(name)}`;\n}\n\n/**\n * Whether a name is a declared option's, at any breakpoint. The scoped\n * spellings share the prefix, so one test covers the whole family.\n */\nexport function isOptionAttribute(attribute: string | null): attribute is string {\n  return attribute?.startsWith(OPTION_ATTRIBUTE_PREFIX) === true;\n}\n\n/** Whether a name declares components, plainly or scoped to a breakpoint. */\nexport function isComponentAttribute(attribute: string | null): attribute is string {\n  return isInNamespace(COMPONENT_ATTRIBUTE, attribute);\n}\n\n/**\n * Several writes to one attribute in a batch are **one** change, from the value\n * it held before the first write to the value the DOM ends the batch with. So\n * the first previous value wins and every later record is dropped: a morph\n * rewriting an attribute twice must not look like two changes.\n *\n * This is the first half of the coalescing rule; {@link isNetChange} is the\n * second. Declared options, watched attributes and the responsive cascade all\n * answer to it, which is why it is stated here once rather than in each of them.\n */\nexport function rememberPreviousValue(\n  previousValues: Map<string, string | null>,\n  attribute: string,\n  previousValue: string | null,\n): void {\n  if (!previousValues.has(attribute)) {\n    previousValues.set(attribute, previousValue);\n  }\n}\n\n/**\n * The second half of the rule: a batch ending where it started changed nothing\n * and is not reported. The comparison is on raw strings — what is in force now\n * against what was in force before — so it holds for an attribute read straight\n * off the element and for a value resolved through the responsive cascade\n * alike, which is what lets a breakpoint crossing and an attribute rewrite be\n * the same kind of event.\n */\nexport function isNetChange(value: string | null, previousValue: string | null): boolean {\n  return value !== previousValue;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoCA,MAAa,sBAAsB;;;;;AAMnC,MAAa,kBAAkB;;AAG/B,MAAa,gBAAgB;;;;;;;;AAS7B,MAAa,0BAA0B;;;;;;;;AASvC,MAAa,sBAAsB;;;;;;AAOnC,MAAa,iBAAiB;;AAG9B,SAAgB,oBAAoB,WAAmB,WAA2B;CAChF,OAAO,GAAG,aAAkC;AAC9C;;;;;AAMA,SAAgB,cAAc,WAAmB,MAAqC;CACpF,OAAO,SAAS,aAAa,MAAM,WAAW,GAAG,YAAiC,MAAM;AAC1F;;;;;;;AAQA,SAAgB,mBAAmB,WAAmB,MAA6B;CACjF,MAAM,SAAS,GAAG;CAClB,OAAO,KAAK,WAAW,MAAM,IAAI,KAAK,MAAM,OAAO,MAAM,IAAI;AAC/D;;;;;;AAOA,SAAgB,cAAc,WAA2B;CACvD,MAAM,QAAQ,UAAU,QAAA,GAAsB;CAC9C,OAAO,UAAU,KAAK,YAAY,UAAU,MAAM,GAAG,KAAK;AAC5D;;;;;AAMA,MAAa,uBAAuB;CAAC;CAAqB;CAAiB;AAAa;;AAGxF,SAAgB,mBAAmB,MAAsB;CACvD,OAAO,GAAG,0BAA0B,UAAU,IAAI;AACpD;;;;;;;;;AAUA,MAAa,cAAc;;;;;;;;AAS3B,SAAgB,0BAA0B,MAAsB;CAC9D,OAAO,GAAG,wBAAwB,KAAK,UAAU,IAAI;AACvD;;;;;AAMA,SAAgB,kBAAkB,WAA+C;CAC/E,OAAO,WAAW,WAAW,uBAAuB,MAAM;AAC5D;;AAGA,SAAgB,qBAAqB,WAA+C;CAClF,OAAO,cAAc,qBAAqB,SAAS;AACrD;;;;;;;;;;;AAYA,SAAgB,sBACd,gBACA,WACA,eACM;CACN,IAAI,CAAC,eAAe,IAAI,SAAS,GAC/B,eAAe,IAAI,WAAW,aAAa;AAE/C;;;;;;;;;AAUA,SAAgB,YAAY,OAAsB,eAAuC;CACvF,OAAO,UAAU;AACnB"}

package/dist/children-watchers.d.ts

@@ -0,0 +1,23 @@
+import { Base } from "./Base.js";
+//#region src/children-watchers.d.ts
+/**
+ * What one `$watchChildren()` collection asks of the shared listener: drop the
+ * instance from the collection when it is one of the children being watched.
+ */
+type ChildrenWatcher = (instance: Base) => void;
+/**
+ * Route unmounted instances to one watcher.
+ *
+ * Unmounted events are dispatched from `document`, because the element of an
+ * unmounted instance can already be detached. One lazy, shared listener serves
+ * every watcher in this realm and every evaluated copy of the package, so the
+ * number of listeners on the document does not grow with the number of
+ * watchers.
+ *
+ * Registering takes no release. A watcher lasts as long as the instance that
+ * asked for it, which is the whole of what `$watchChildren()` promises, and
+ * the index forgets it on the first pass after its owner is collected.
+ */
+declare function registerChildrenWatcher(watcher: ChildrenWatcher): void;
+//#endregion
+export { ChildrenWatcher, registerChildrenWatcher };

package/dist/children-watchers.js

@@ -0,0 +1,48 @@
+import { getSharedRuntimeSlot } from "./shared-runtime.js";
+import { EVENTS } from "./events.js";
+//#region src/children-watchers.ts
+const watcherState = /* @__PURE__ */ getSharedRuntimeSlot("children-watchers", 1, () => ({
+	watcherIndex: /* @__PURE__ */ new Set(),
+	isUnmountListenerAttached: false
+}));
+const { watcherIndex } = watcherState;
+/**
+* Tell every live watcher about an unmounted instance, and forget the watchers
+* whose owner has been collected. Pruning happens here because a discarded
+* watcher has no teardown to run: its owner simply stopped existing.
+*/
+function onComponentUnmounted(event) {
+	const { instance } = event.detail;
+	for (const ref of [...watcherIndex]) {
+		const watcher = ref.deref();
+		if (!watcher) {
+			watcherIndex.delete(ref);
+			continue;
+		}
+		watcher(instance);
+	}
+}
+/**
+* Route unmounted instances to one watcher.
+*
+* Unmounted events are dispatched from `document`, because the element of an
+* unmounted instance can already be detached. One lazy, shared listener serves
+* every watcher in this realm and every evaluated copy of the package, so the
+* number of listeners on the document does not grow with the number of
+* watchers.
+*
+* Registering takes no release. A watcher lasts as long as the instance that
+* asked for it, which is the whole of what `$watchChildren()` promises, and
+* the index forgets it on the first pass after its owner is collected.
+*/
+function registerChildrenWatcher(watcher) {
+	watcherIndex.add(new WeakRef(watcher));
+	if (!watcherState.isUnmountListenerAttached) {
+		watcherState.isUnmountListenerAttached = true;
+		document.addEventListener(EVENTS.component.unmounted, onComponentUnmounted);
+	}
+}
+//#endregion
+export { registerChildrenWatcher };
+
+//# sourceMappingURL=children-watchers.js.map

package/dist/children-watchers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"children-watchers.js","names":[],"sources":["../src/children-watchers.ts"],"sourcesContent":["import { EVENTS } from './events.js';\nimport { getSharedRuntimeSlot } from './shared-runtime.js';\nimport type { Base, LifecycleEventDetail } from './Base.js';\n\n/**\n * What one `$watchChildren()` collection asks of the shared listener: drop the\n * instance from the collection when it is one of the children being watched.\n */\nexport type ChildrenWatcher = (instance: Base) => void;\n\ninterface ChildrenWatcherRuntimeState {\n  watcherIndex: Set<WeakRef<ChildrenWatcher>>;\n  isUnmountListenerAttached: boolean;\n}\n\nconst watcherState = /* @__PURE__ */ getSharedRuntimeSlot<ChildrenWatcherRuntimeState>(\n  'children-watchers',\n  1,\n  () => ({\n    watcherIndex: new Set(),\n    isUnmountListenerAttached: false,\n  }),\n);\nconst { watcherIndex } = watcherState;\n\n// A watcher closes over its owner's callbacks, so it reaches the owning\n// instance. The index therefore holds weak references only: a listener on\n// `document` outlives every component, and a strong entry here would make the\n// document keep every instance that ever watched its children alive for the\n// life of the page. The owner holds its own watchers strongly, which is what\n// decides when one dies.\n\n/**\n * Tell every live watcher about an unmounted instance, and forget the watchers\n * whose owner has been collected. Pruning happens here because a discarded\n * watcher has no teardown to run: its owner simply stopped existing.\n */\nfunction onComponentUnmounted(event: Event): void {\n  const { instance } = (event as CustomEvent<LifecycleEventDetail>).detail;\n  // Snapshot because a callback can add or release a watcher, and because dead\n  // references are deleted during this pass.\n  // oxlint-disable-next-line no-useless-spread\n  for (const ref of [...watcherIndex]) {\n    const watcher = ref.deref();\n    if (!watcher) {\n      watcherIndex.delete(ref);\n      continue;\n    }\n    watcher(instance);\n  }\n}\n\n/**\n * Route unmounted instances to one watcher.\n *\n * Unmounted events are dispatched from `document`, because the element of an\n * unmounted instance can already be detached. One lazy, shared listener serves\n * every watcher in this realm and every evaluated copy of the package, so the\n * number of listeners on the document does not grow with the number of\n * watchers.\n *\n * Registering takes no release. A watcher lasts as long as the instance that\n * asked for it, which is the whole of what `$watchChildren()` promises, and\n * the index forgets it on the first pass after its owner is collected.\n */\nexport function registerChildrenWatcher(watcher: ChildrenWatcher): void {\n  watcherIndex.add(new WeakRef(watcher));\n\n  if (!watcherState.isUnmountListenerAttached) {\n    watcherState.isUnmountListenerAttached = true;\n    document.addEventListener(EVENTS.component.unmounted, onComponentUnmounted);\n  }\n}\n"],"mappings":";;;AAeA,MAAM,eAA+B,qCACnC,qBACA,UACO;CACL,8BAAc,IAAI,IAAI;CACtB,2BAA2B;AAC7B,EACF;AACA,MAAM,EAAE,iBAAiB;;;;;;AAczB,SAAS,qBAAqB,OAAoB;CAChD,MAAM,EAAE,aAAc,MAA4C;CAIlE,KAAK,MAAM,OAAO,CAAC,GAAG,YAAY,GAAG;EACnC,MAAM,UAAU,IAAI,MAAM;EAC1B,IAAI,CAAC,SAAS;GACZ,aAAa,OAAO,GAAG;GACvB;EACF;EACA,QAAQ,QAAQ;CAClB;AACF;;;;;;;;;;;;;;AAeA,SAAgB,wBAAwB,SAAgC;CACtE,aAAa,IAAI,IAAI,QAAQ,OAAO,CAAC;CAErC,IAAI,CAAC,aAAa,2BAA2B;EAC3C,aAAa,4BAA4B;EACzC,SAAS,iBAAiB,OAAO,UAAU,WAAW,oBAAoB;CAC5E;AACF"}

package/dist/component-brand.d.ts

@@ -0,0 +1,11 @@
+import { BaseConstructor } from "./Base.js";
+//#region src/component-brand.d.ts
+/** @internal The realm-stable key owned by `Base` and inherited by subclasses. */
+declare const BASE_BRAND: unique symbol;
+/**
+ * Recognise v4 component classes from this or another evaluated package copy.
+ * A normal function, importer, or unrelated class has no inherited brand.
+ */
+declare function isBaseConstructor(value: unknown): value is BaseConstructor;
+//#endregion
+export { BASE_BRAND, isBaseConstructor };

package/dist/component-brand.js

@@ -0,0 +1,17 @@
+//#region src/component-brand.ts
+/** @internal The realm-stable key owned by `Base` and inherited by subclasses. */
+const BASE_BRAND = Symbol.for("@studiometa/js-toolkit/base");
+/**
+* Recognise v4 component classes from this or another evaluated package copy.
+* A normal function, importer, or unrelated class has no inherited brand.
+*/
+function isBaseConstructor(value) {
+	if (typeof value !== "function") return false;
+	const candidate = value;
+	const config = candidate.config;
+	return candidate[BASE_BRAND] === true && typeof candidate.prototype === "object" && candidate.prototype !== null && typeof config === "object" && config !== null && typeof config.name === "string";
+}
+//#endregion
+export { BASE_BRAND, isBaseConstructor };
+
+//# sourceMappingURL=component-brand.js.map

package/dist/component-brand.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"component-brand.js","names":[],"sources":["../src/component-brand.ts"],"sourcesContent":["import type { BaseConstructor } from './Base.js';\n\n/** @internal The realm-stable key owned by `Base` and inherited by subclasses. */\nexport const BASE_BRAND = Symbol.for('@studiometa/js-toolkit/base');\n\n/**\n * Recognise v4 component classes from this or another evaluated package copy.\n * A normal function, importer, or unrelated class has no inherited brand.\n */\nexport function isBaseConstructor(value: unknown): value is BaseConstructor {\n  if (typeof value !== 'function') {\n    return false;\n  }\n  const candidate = value as unknown as {\n    [BASE_BRAND]?: unknown;\n    config?: unknown;\n    prototype?: unknown;\n  };\n  const config = candidate.config as { name?: unknown } | undefined;\n  return (\n    candidate[BASE_BRAND] === true &&\n    typeof candidate.prototype === 'object' &&\n    candidate.prototype !== null &&\n    typeof config === 'object' &&\n    config !== null &&\n    typeof config.name === 'string'\n  );\n}\n"],"mappings":";;AAGA,MAAa,aAAa,OAAO,IAAI,6BAA6B;;;;;AAMlE,SAAgB,kBAAkB,OAA0C;CAC1E,IAAI,OAAO,UAAU,YACnB,OAAO;CAET,MAAM,YAAY;CAKlB,MAAM,SAAS,UAAU;CACzB,OACE,UAAU,gBAAgB,QAC1B,OAAO,UAAU,cAAc,YAC/B,UAAU,cAAc,QACxB,OAAO,WAAW,YAClB,WAAW,QACX,OAAO,OAAO,SAAS;AAE3B"}

package/dist/component-declarations.d.ts

@@ -0,0 +1,15 @@
+//#region src/component-declarations.d.ts
+/**
+ * The component names currently declared on an element.
+ *
+ * The plain attribute is unconditional. One scoped value is selected by the
+ * responsive cascade and replaces every lower scoped value. The two sets are
+ * then combined and deduplicated here, before the registry sees them.
+ */
+declare function componentTokens(el: Element): Set<string>;
+/** Whether an element carries any component spelling, including an invalid suffix. */
+declare function hasComponentAttribute(el: Element): boolean;
+/** Whether an element carries a scoped spelling from the configured breakpoint set. */
+declare function hasResponsiveComponentAttribute(el: Element): boolean;
+//#endregion
+export { componentTokens, hasComponentAttribute, hasResponsiveComponentAttribute };

package/dist/component-declarations.js

@@ -0,0 +1,31 @@
+import { COMPONENT_ATTRIBUTE, isInNamespace } from "./attributes.js";
+import { activeBreakpoint, responsiveAttributeNames, responsiveScopedRawValue } from "./responsive-options.js";
+//#region src/component-declarations.ts
+/** Parse the whitespace-token syntax used by every component declaration. */
+function tokens(value) {
+	return (value ?? "").split(/\s+/).filter(Boolean);
+}
+/**
+* The component names currently declared on an element.
+*
+* The plain attribute is unconditional. One scoped value is selected by the
+* responsive cascade and replaces every lower scoped value. The two sets are
+* then combined and deduplicated here, before the registry sees them.
+*/
+function componentTokens(el) {
+	const get = (attribute) => el.getAttribute(attribute);
+	const scoped = responsiveScopedRawValue(COMPONENT_ATTRIBUTE, activeBreakpoint(), get);
+	return /* @__PURE__ */ new Set([...tokens(get(COMPONENT_ATTRIBUTE)), ...tokens(scoped)]);
+}
+/** Whether an element carries any component spelling, including an invalid suffix. */
+function hasComponentAttribute(el) {
+	return el.getAttributeNames().some((attribute) => isInNamespace(COMPONENT_ATTRIBUTE, attribute));
+}
+/** Whether an element carries a scoped spelling from the configured breakpoint set. */
+function hasResponsiveComponentAttribute(el) {
+	return responsiveAttributeNames(COMPONENT_ATTRIBUTE).some((attribute) => el.hasAttribute(attribute));
+}
+//#endregion
+export { componentTokens, hasComponentAttribute, hasResponsiveComponentAttribute };
+
+//# sourceMappingURL=component-declarations.js.map

package/dist/component-declarations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"component-declarations.js","names":[],"sources":["../src/component-declarations.ts"],"sourcesContent":["import { COMPONENT_ATTRIBUTE, isInNamespace } from './attributes.js';\nimport {\n  activeBreakpoint,\n  responsiveAttributeNames,\n  responsiveScopedRawValue,\n} from './responsive-options.js';\n\n/** Parse the whitespace-token syntax used by every component declaration. */\nfunction tokens(value: string | null): string[] {\n  return (value ?? '').split(/\\s+/).filter(Boolean);\n}\n\n/**\n * The component names currently declared on an element.\n *\n * The plain attribute is unconditional. One scoped value is selected by the\n * responsive cascade and replaces every lower scoped value. The two sets are\n * then combined and deduplicated here, before the registry sees them.\n */\nexport function componentTokens(el: Element): Set<string> {\n  const get = (attribute: string) => el.getAttribute(attribute);\n  const scoped = responsiveScopedRawValue(COMPONENT_ATTRIBUTE, activeBreakpoint(), get);\n  return new Set([...tokens(get(COMPONENT_ATTRIBUTE)), ...tokens(scoped)]);\n}\n\n/** Whether an element carries any component spelling, including an invalid suffix. */\nexport function hasComponentAttribute(el: Element): boolean {\n  return el.getAttributeNames().some((attribute) => isInNamespace(COMPONENT_ATTRIBUTE, attribute));\n}\n\n/** Whether an element carries a scoped spelling from the configured breakpoint set. */\nexport function hasResponsiveComponentAttribute(el: Element): boolean {\n  return responsiveAttributeNames(COMPONENT_ATTRIBUTE).some((attribute) =>\n    el.hasAttribute(attribute),\n  );\n}\n"],"mappings":";;;;AAQA,SAAS,OAAO,OAAgC;CAC9C,QAAQ,SAAS,GAAA,CAAI,MAAM,KAAK,CAAC,CAAC,OAAO,OAAO;AAClD;;;;;;;;AASA,SAAgB,gBAAgB,IAA0B;CACxD,MAAM,OAAO,cAAsB,GAAG,aAAa,SAAS;CAC5D,MAAM,SAAS,yBAAyB,qBAAqB,iBAAiB,GAAG,GAAG;CACpF,uBAAO,IAAI,IAAI,CAAC,GAAG,OAAO,IAAI,mBAAmB,CAAC,GAAG,GAAG,OAAO,MAAM,CAAC,CAAC;AACzE;;AAGA,SAAgB,sBAAsB,IAAsB;CAC1D,OAAO,GAAG,kBAAkB,CAAC,CAAC,MAAM,cAAc,cAAc,qBAAqB,SAAS,CAAC;AACjG;;AAGA,SAAgB,gCAAgC,IAAsB;CACpE,OAAO,yBAAyB,mBAAmB,CAAC,CAAC,MAAM,cACzD,GAAG,aAAa,SAAS,CAC3B;AACF"}

package/dist/context-subscription.d.ts

@@ -0,0 +1,24 @@
+import { ContextKey } from "./context.js";
+//#region src/context-subscription.d.ts
+/**
+ * What a subscribed consumer receives for every answer.
+ *
+ * The second argument is the same unsubscribe function returned by
+ * `subscribeContext()`. Returning a function registers the teardown for the
+ * answer.
+ */
+type ContextCallback<T> = (value: T, unsubscribe: () => void) => void | (() => void);
+/**
+ * Subscribe to the nearest context value.
+ *
+ * The required callback runs synchronously for the first answer and every
+ * changed answer from a nearer provider. Its teardown runs before the next
+ * changed value and on unsubscribe. A provider change that supplies the same
+ * value only updates provider ownership and does not restart the callback.
+ *
+ * @returns One unsubscribe function.
+ * @link https://js-toolkit-v4.studiometa.dev/api/context/subscribeContext.html
+ */
+declare function subscribeContext<T>(el: Element, key: ContextKey<T>, onProvide: ContextCallback<T>): () => void;
+//#endregion
+export { ContextCallback, subscribeContext };

package/dist/context-subscription.js

@@ -0,0 +1,123 @@
+import { getSharedRuntimeSlot } from "./shared-runtime.js";
+import { reportDiagnostic } from "./diagnostics.js";
+import { EVENTS } from "./events.js";
+import { cancelContextRequest, dispatchContextRequest, retainContextRequest } from "./context.js";
+//#region src/context-subscription.ts
+const subscriptionState = /* @__PURE__ */ getSharedRuntimeSlot("context-subscription", 1, () => ({
+	subscriptionsByElement: /* @__PURE__ */ new WeakMap(),
+	subscriptionIndex: /* @__PURE__ */ new Set(),
+	isMountListenerAttached: false
+}));
+const { subscriptionsByElement, subscriptionIndex } = subscriptionState;
+function reportFailure(subscription, operation, error) {
+	reportDiagnostic(operation === "callback" ? "callback.context-subscription-failed" : "callback.context-teardown-failed", `A context subscription ${operation} failed.`, error, { target: subscription.el });
+}
+function runTeardown(subscription) {
+	const { teardown } = subscription;
+	subscription.teardown = void 0;
+	if (!teardown) return;
+	try {
+		teardown();
+	} catch (error) {
+		reportFailure(subscription, "teardown", error);
+	}
+}
+/** Deliver one changed answer after the previous answer is fully released. */
+function deliver(subscription, value, providerNode) {
+	if (!subscription.isActive) return;
+	if (subscription.hasValue && Object.is(value, subscription.value)) {
+		subscription.providerNode = providerNode;
+		return;
+	}
+	runTeardown(subscription);
+	if (!subscription.isActive) return;
+	subscription.value = value;
+	subscription.hasValue = true;
+	subscription.providerNode = providerNode;
+	let teardown;
+	try {
+		teardown = subscription.callback(value, subscription.unsubscribe);
+	} catch (error) {
+		reportFailure(subscription, "callback", error);
+		return;
+	}
+	if (typeof teardown !== "function") return;
+	if (subscription.isActive) {
+		subscription.teardown = teardown;
+		return;
+	}
+	subscription.teardown = teardown;
+	runTeardown(subscription);
+}
+/** Re-ask subscriptions whose nearest provider can change after this mount. */
+function onComponentMounted(event) {
+	const mountedEl = event.target;
+	if (!(mountedEl instanceof Element) || subscriptionIndex.size === 0) return;
+	for (const ref of [...subscriptionIndex]) {
+		const subscription = ref.deref();
+		if (!subscription) {
+			subscriptionIndex.delete(ref);
+			continue;
+		}
+		const { providerNode } = subscription;
+		if (!subscription.isActive || providerNode === mountedEl || !mountedEl.contains(subscription.el) || providerNode !== null && !providerNode.contains(mountedEl)) continue;
+		dispatchContextRequest(subscription.request);
+	}
+}
+function registerSubscription(subscription) {
+	let owned = subscriptionsByElement.get(subscription.el);
+	if (!owned) {
+		owned = /* @__PURE__ */ new Set();
+		subscriptionsByElement.set(subscription.el, owned);
+	}
+	owned.add(subscription);
+	subscriptionIndex.add(subscription.ref);
+	if (!subscriptionState.isMountListenerAttached) {
+		subscriptionState.isMountListenerAttached = true;
+		document.addEventListener(EVENTS.component.mounted, onComponentMounted);
+	}
+}
+function unsubscribeSubscription(subscription) {
+	if (!subscription.isActive) return;
+	subscription.isActive = false;
+	cancelContextRequest(subscription.request);
+	subscriptionsByElement.get(subscription.el)?.delete(subscription);
+	subscriptionIndex.delete(subscription.ref);
+	runTeardown(subscription);
+}
+/**
+* Subscribe to the nearest context value.
+*
+* The required callback runs synchronously for the first answer and every
+* changed answer from a nearer provider. Its teardown runs before the next
+* changed value and on unsubscribe. A provider change that supplies the same
+* value only updates provider ownership and does not restart the callback.
+*
+* @returns One unsubscribe function.
+* @link https://js-toolkit-v4.studiometa.dev/api/context/subscribeContext.html
+*/
+function subscribeContext(el, key, onProvide) {
+	const subscription = {
+		el,
+		callback: onProvide,
+		providerNode: null,
+		value: void 0,
+		hasValue: false,
+		isActive: true
+	};
+	subscription.ref = new WeakRef(subscription);
+	subscription.unsubscribe = () => unsubscribeSubscription(subscription);
+	subscription.request = {
+		el,
+		key,
+		subscribe: true,
+		resolve: (value, providerNode) => deliver(subscription, value, providerNode)
+	};
+	registerSubscription(subscription);
+	if (!dispatchContextRequest(subscription.request)) retainContextRequest(subscription.request);
+	return subscription.unsubscribe;
+}
+//#endregion
+export { subscribeContext };
+
+//# sourceMappingURL=context-subscription.js.map

package/dist/context-subscription.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-subscription.js","names":[],"sources":["../src/context-subscription.ts"],"sourcesContent":["import {\n  cancelContextRequest,\n  dispatchContextRequest,\n  retainContextRequest,\n  type ContextKey,\n  type ContextRequest,\n} from './context.js';\nimport { reportDiagnostic } from './diagnostics.js';\nimport { EVENTS } from './events.js';\nimport { getSharedRuntimeSlot } from './shared-runtime.js';\n\n/**\n * What a subscribed consumer receives for every answer.\n *\n * The second argument is the same unsubscribe function returned by\n * `subscribeContext()`. Returning a function registers the teardown for the\n * answer.\n */\nexport type ContextCallback<T> = (value: T, unsubscribe: () => void) => void | (() => void);\n\n/** An answered request that can be answered again. */\ninterface ContextSubscription {\n  request: ContextRequest;\n  el: Element;\n  callback: ContextCallback<unknown>;\n  /** The provider that answered last. `null` until the first answer. */\n  providerNode: Node | null;\n  value: unknown;\n  hasValue: boolean;\n  teardown?: () => void;\n  isActive: boolean;\n  ref: WeakRef<ContextSubscription>;\n  unsubscribe: () => void;\n}\n\ninterface ContextSubscriptionRuntimeState {\n  subscriptionsByElement: WeakMap<Element, Set<ContextSubscription>>;\n  subscriptionIndex: Set<WeakRef<ContextSubscription>>;\n  isMountListenerAttached: boolean;\n}\n\nconst subscriptionState = /* @__PURE__ */ getSharedRuntimeSlot<ContextSubscriptionRuntimeState>(\n  'context-subscription',\n  1,\n  () => ({\n    subscriptionsByElement: new WeakMap(),\n    subscriptionIndex: new Set(),\n    isMountListenerAttached: false,\n  }),\n);\nconst { subscriptionsByElement, subscriptionIndex } = subscriptionState;\n\n// The weak owner map anchors a subscription to its consumer element. The\n// iterable index contains only weak references, so the document listener can\n// sweep subscriptions without keeping discarded consumers alive.\n\nfunction reportFailure(\n  subscription: ContextSubscription,\n  operation: 'callback' | 'teardown',\n  error: unknown,\n): void {\n  reportDiagnostic(\n    operation === 'callback'\n      ? 'callback.context-subscription-failed'\n      : 'callback.context-teardown-failed',\n    `A context subscription ${operation} failed.`,\n    error,\n    { target: subscription.el },\n  );\n}\n\nfunction runTeardown(subscription: ContextSubscription): void {\n  const { teardown } = subscription;\n  subscription.teardown = undefined;\n  if (!teardown) {\n    return;\n  }\n  try {\n    teardown();\n  } catch (error) {\n    reportFailure(subscription, 'teardown', error);\n  }\n}\n\n/** Deliver one changed answer after the previous answer is fully released. */\nfunction deliver(subscription: ContextSubscription, value: unknown, providerNode: Node | null) {\n  if (!subscription.isActive) {\n    return;\n  }\n  if (subscription.hasValue && Object.is(value, subscription.value)) {\n    subscription.providerNode = providerNode;\n    return;\n  }\n\n  runTeardown(subscription);\n  if (!subscription.isActive) {\n    return;\n  }\n\n  subscription.value = value;\n  subscription.hasValue = true;\n  subscription.providerNode = providerNode;\n\n  let teardown: void | (() => void);\n  try {\n    teardown = subscription.callback(value, subscription.unsubscribe);\n  } catch (error) {\n    reportFailure(subscription, 'callback', error);\n    return;\n  }\n\n  if (typeof teardown !== 'function') {\n    return;\n  }\n  if (subscription.isActive) {\n    subscription.teardown = teardown;\n    return;\n  }\n\n  // The callback unsubscribed itself before it returned its teardown. The\n  // teardown still belongs to that answer and must run before delivery ends.\n  subscription.teardown = teardown;\n  runTeardown(subscription);\n}\n\n/** Re-ask subscriptions whose nearest provider can change after this mount. */\nfunction onComponentMounted(event: Event): void {\n  const mountedEl = event.target;\n  if (!(mountedEl instanceof Element) || subscriptionIndex.size === 0) {\n    return;\n  }\n\n  // Snapshot because delivery can unsubscribe and dead weak references are\n  // pruned during this pass.\n  // oxlint-disable-next-line no-useless-spread\n  for (const ref of [...subscriptionIndex]) {\n    const subscription = ref.deref();\n    if (!subscription) {\n      subscriptionIndex.delete(ref);\n      continue;\n    }\n    const { providerNode } = subscription;\n    if (\n      !subscription.isActive ||\n      providerNode === mountedEl ||\n      !mountedEl.contains(subscription.el) ||\n      (providerNode !== null && !providerNode.contains(mountedEl))\n    ) {\n      continue;\n    }\n    dispatchContextRequest(subscription.request);\n  }\n}\n\nfunction registerSubscription(subscription: ContextSubscription): void {\n  let owned = subscriptionsByElement.get(subscription.el);\n  if (!owned) {\n    owned = new Set();\n    subscriptionsByElement.set(subscription.el, owned);\n  }\n  owned.add(subscription);\n  subscriptionIndex.add(subscription.ref);\n\n  if (!subscriptionState.isMountListenerAttached) {\n    subscriptionState.isMountListenerAttached = true;\n    // One lazy, shared listener serves all subscribed consumers and all\n    // evaluated copies in this realm.\n    document.addEventListener(EVENTS.component.mounted, onComponentMounted);\n  }\n}\n\nfunction unsubscribeSubscription(subscription: ContextSubscription): void {\n  if (!subscription.isActive) {\n    return;\n  }\n  subscription.isActive = false;\n  cancelContextRequest(subscription.request);\n  subscriptionsByElement.get(subscription.el)?.delete(subscription);\n  subscriptionIndex.delete(subscription.ref);\n  runTeardown(subscription);\n}\n\n/**\n * Subscribe to the nearest context value.\n *\n * The required callback runs synchronously for the first answer and every\n * changed answer from a nearer provider. Its teardown runs before the next\n * changed value and on unsubscribe. A provider change that supplies the same\n * value only updates provider ownership and does not restart the callback.\n *\n * @returns One unsubscribe function.\n * @link https://js-toolkit-v4.studiometa.dev/api/context/subscribeContext.html\n */\nexport function subscribeContext<T>(\n  el: Element,\n  key: ContextKey<T>,\n  onProvide: ContextCallback<T>,\n): () => void {\n  const subscription = {\n    el,\n    callback: onProvide as ContextCallback<unknown>,\n    providerNode: null,\n    value: undefined,\n    hasValue: false,\n    isActive: true,\n  } as ContextSubscription;\n  subscription.ref = new WeakRef(subscription);\n  subscription.unsubscribe = () => unsubscribeSubscription(subscription);\n  subscription.request = {\n    el,\n    key,\n    subscribe: true,\n    resolve: (value, providerNode) => deliver(subscription, value, providerNode),\n  };\n\n  registerSubscription(subscription);\n  if (!dispatchContextRequest(subscription.request)) {\n    retainContextRequest(subscription.request);\n  }\n\n  return subscription.unsubscribe;\n}\n"],"mappings":";;;;;AAyCA,MAAM,oBAAoC,qCACxC,wBACA,UACO;CACL,wCAAwB,IAAI,QAAQ;CACpC,mCAAmB,IAAI,IAAI;CAC3B,yBAAyB;AAC3B,EACF;AACA,MAAM,EAAE,wBAAwB,sBAAsB;AAMtD,SAAS,cACP,cACA,WACA,OACM;CACN,iBACE,cAAc,aACV,yCACA,oCACJ,0BAA0B,UAAU,WACpC,OACA,EAAE,QAAQ,aAAa,GAAG,CAC5B;AACF;AAEA,SAAS,YAAY,cAAyC;CAC5D,MAAM,EAAE,aAAa;CACrB,aAAa,WAAW,KAAA;CACxB,IAAI,CAAC,UACH;CAEF,IAAI;EACF,SAAS;CACX,SAAS,OAAO;EACd,cAAc,cAAc,YAAY,KAAK;CAC/C;AACF;;AAGA,SAAS,QAAQ,cAAmC,OAAgB,cAA2B;CAC7F,IAAI,CAAC,aAAa,UAChB;CAEF,IAAI,aAAa,YAAY,OAAO,GAAG,OAAO,aAAa,KAAK,GAAG;EACjE,aAAa,eAAe;EAC5B;CACF;CAEA,YAAY,YAAY;CACxB,IAAI,CAAC,aAAa,UAChB;CAGF,aAAa,QAAQ;CACrB,aAAa,WAAW;CACxB,aAAa,eAAe;CAE5B,IAAI;CACJ,IAAI;EACF,WAAW,aAAa,SAAS,OAAO,aAAa,WAAW;CAClE,SAAS,OAAO;EACd,cAAc,cAAc,YAAY,KAAK;EAC7C;CACF;CAEA,IAAI,OAAO,aAAa,YACtB;CAEF,IAAI,aAAa,UAAU;EACzB,aAAa,WAAW;EACxB;CACF;CAIA,aAAa,WAAW;CACxB,YAAY,YAAY;AAC1B;;AAGA,SAAS,mBAAmB,OAAoB;CAC9C,MAAM,YAAY,MAAM;CACxB,IAAI,EAAE,qBAAqB,YAAY,kBAAkB,SAAS,GAChE;CAMF,KAAK,MAAM,OAAO,CAAC,GAAG,iBAAiB,GAAG;EACxC,MAAM,eAAe,IAAI,MAAM;EAC/B,IAAI,CAAC,cAAc;GACjB,kBAAkB,OAAO,GAAG;GAC5B;EACF;EACA,MAAM,EAAE,iBAAiB;EACzB,IACE,CAAC,aAAa,YACd,iBAAiB,aACjB,CAAC,UAAU,SAAS,aAAa,EAAE,KAClC,iBAAiB,QAAQ,CAAC,aAAa,SAAS,SAAS,GAE1D;EAEF,uBAAuB,aAAa,OAAO;CAC7C;AACF;AAEA,SAAS,qBAAqB,cAAyC;CACrE,IAAI,QAAQ,uBAAuB,IAAI,aAAa,EAAE;CACtD,IAAI,CAAC,OAAO;EACV,wBAAQ,IAAI,IAAI;EAChB,uBAAuB,IAAI,aAAa,IAAI,KAAK;CACnD;CACA,MAAM,IAAI,YAAY;CACtB,kBAAkB,IAAI,aAAa,GAAG;CAEtC,IAAI,CAAC,kBAAkB,yBAAyB;EAC9C,kBAAkB,0BAA0B;EAG5C,SAAS,iBAAiB,OAAO,UAAU,SAAS,kBAAkB;CACxE;AACF;AAEA,SAAS,wBAAwB,cAAyC;CACxE,IAAI,CAAC,aAAa,UAChB;CAEF,aAAa,WAAW;CACxB,qBAAqB,aAAa,OAAO;CACzC,uBAAuB,IAAI,aAAa,EAAE,CAAC,EAAE,OAAO,YAAY;CAChE,kBAAkB,OAAO,aAAa,GAAG;CACzC,YAAY,YAAY;AAC1B;;;;;;;;;;;;AAaA,SAAgB,iBACd,IACA,KACA,WACY;CACZ,MAAM,eAAe;EACnB;EACA,UAAU;EACV,cAAc;EACd,OAAO,KAAA;EACP,UAAU;EACV,UAAU;CACZ;CACA,aAAa,MAAM,IAAI,QAAQ,YAAY;CAC3C,aAAa,oBAAoB,wBAAwB,YAAY;CACrE,aAAa,UAAU;EACrB;EACA;EACA,WAAW;EACX,UAAU,OAAO,iBAAiB,QAAQ,cAAc,OAAO,YAAY;CAC7E;CAEA,qBAAqB,YAAY;CACjC,IAAI,CAAC,uBAAuB,aAAa,OAAO,GAC9C,qBAAqB,aAAa,OAAO;CAG3C,OAAO,aAAa;AACtB"}

package/dist/context.d.ts

@@ -0,0 +1,82 @@
+//#region src/context.d.ts
+/** A typed context key. `__context` is type-only. */
+type ContextKey<T = unknown> = symbol & {
+  readonly __context?: T;
+};
+/**
+ * Create a typed context key.
+ * @link https://js-toolkit-v4.studiometa.dev/api/context/createContext.html
+ */
+declare function createContext<T = unknown>(description?: string): ContextKey<T>;
+/** A reactive value with synchronous subscriptions. */
+interface Signal<T = unknown> {
+  /** The latest value, including during delivery. */
+  value: T;
+  /** @returns Unsubscribe. */
+  subscribe(callback: (value: T) => void, options?: {
+    immediate?: boolean;
+  }): () => void;
+}
+/**
+ * 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
+ */
+declare function signal<T>(initialValue: T): Signal<T>;
+/**
+ * One context request on the private event transport.
+ *
+ * @internal
+ */
+interface ContextRequest {
+  el: Element;
+  key: symbol;
+  subscribe: boolean;
+  resolve(value: unknown, providerNode: Node | null): void;
+}
+/**
+ * Dispatch one request and report whether a provider answered synchronously.
+ *
+ * @internal
+ */
+declare function dispatchContextRequest(request: ContextRequest): boolean;
+/** Keep an unanswered request available for a provider that appears later. @internal */
+declare function retainContextRequest(request: ContextRequest): void;
+/** Stop replaying an unanswered request. @internal */
+declare function cancelContextRequest(request: ContextRequest): void;
+/**
+ * Provide a value verbatim for a subtree. The nearest provider wins.
+ * @link https://js-toolkit-v4.studiometa.dev/api/context/provideContext.html
+ */
+declare function provideContext<T>(el: Element, key: ContextKey<T>, value: T): {
+  value: T;
+  dispose: () => void;
+};
+/**
+ * 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
+ */
+declare function provideRootContext<T>(key: ContextKey<T>, create: () => T): T;
+/**
+ * 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
+ */
+declare function injectContext<T>(el: Element, key: ContextKey<T>): {
+  promise: Promise<T>;
+  cancel: () => void;
+};
+/**
+ * Resolve the nearest provided value synchronously, or return `undefined`.
+ * @link https://js-toolkit-v4.studiometa.dev/api/context/injectContextSync.html
+ */
+declare function injectContextSync<T>(el: Element, key: ContextKey<T>): T | undefined;
+//#endregion
+export { ContextKey, ContextRequest, Signal, cancelContextRequest, createContext, dispatchContextRequest, injectContext, injectContextSync, provideContext, provideRootContext, retainContextRequest, signal };