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

package/README.md

@@ -1,138 +1,63 @@
 # @studiometa/js-toolkit
 
-[![NPM Version](https://img.shields.io/npm/v/@studiometa/js-toolkit.svg?style=flat&colorB=3e63dd&colorA=414853)](https://www.npmjs.com/package/@studiometa/js-toolkit/)
+[![NPM Version](https://img.shields.io/npm/v/@studiometa/js-toolkit/next.svg?style=flat&colorB=3e63dd&colorA=414853)](https://www.npmjs.com/package/@studiometa/js-toolkit/v/next)
 [![Downloads](https://img.shields.io/npm/dm/@studiometa/js-toolkit?style=flat&colorB=3e63dd&colorA=414853)](https://www.npmjs.com/package/@studiometa/js-toolkit/)
-[![Size](https://img.shields.io/bundlephobia/minzip/@studiometa/js-toolkit?style=flat&colorB=3e63dd&colorA=414853&label=size)](https://bundlephobia.com/package/@studiometa/js-toolkit)
-[![Dependency Status](https://img.shields.io/librariesio/release/npm/@studiometa/js-toolkit?style=flat&colorB=3e63dd&colorA=414853)](https://david-dm.org/studiometa/js-toolkit)
-![Codecov](https://img.shields.io/codecov/c/github/studiometa/js-toolkit?style=flat&colorB=3e63dd&colorA=414853)
+[![License](https://img.shields.io/npm/l/@studiometa/js-toolkit?style=flat&colorB=3e63dd&colorA=414853)](./LICENSE)
 
 > A JavaScript data-attributes driven micro-framework shipped with plenty of useful utility functions to boost your project.
 
-## Installation
+> [!WARNING]
+> **This is the 4.0 alpha.** It is published under the `next` dist-tag, and it is a breaking major: `latest` still installs 3.x. The API is stable and documented, but the version is an alpha because it has not yet been run on a production project. Expect the occasional break until 4.0.0 ships.
+>
+> For 3.x, install `@studiometa/js-toolkit@latest` and read [js-toolkit.studiometa.dev](https://js-toolkit.studiometa.dev).
 
-Install the latest version via NPM:
+## Installation
 
 ```bash
-npm install @studiometa/js-toolkit
+npm install @studiometa/js-toolkit@next
 ```
 
 ## What is it?
 
-This project is a JavaScript micro-framework (along with its utility functions) whose main objectives are:
-
-- Enforcing best-practice and consistency between projects
-- Using elements from the DOM easily
-- Enabling custom behaviours on component initialization or other user events
-- Disabling custom behaviours on component destruction or other user events
-- Initializing components in the right place at the right time
-- Defining dependencies between components
-
-Visit [js-toolkit.studiometa.dev](https://js-toolkit.studiometa.dev) to learn more, jump directly to [ui.studiometa.dev](https://ui.studiometa.dev) to discover existing components, or open [the playground](https://ui.studiometa.dev/-/play/) to test it live.
-
-## Linting
+Write components as classes and bind them to the DOM with `data-…` attributes. A component declares the elements it needs, and the framework mounts it wherever it appears in the page — including elements added later.
 
-The [`@studiometa/eslint-plugin-js-toolkit`](./packages/eslint-plugin-js-toolkit/) package provides an Oxlint/ESLint plugin that enforces best practices when writing components with this framework.
-
-```bash
-npm install --save-dev @studiometa/eslint-plugin-js-toolkit
+```html
+<div data-component="Counter" data-option-step="2">
+  <button data-ref="add">Add</button>
+  <span data-ref="count">0</span>
+</div>
 ```
 
-See the [plugin README](./packages/eslint-plugin-js-toolkit/README.md) or the [linting guide](https://js-toolkit.studiometa.dev/guide/going-further/linting.html) for configuration details.
-
-## Quick overview
-
-This framework lets you define components as classes, and bind them to the DOM with `data-…` attributes. For example, here is how a `Counter` component would be defined in JavaScript:
-
 ```js
-import { Base } from '@studiometa/js-toolkit';
+import { Base, registerComponent } from '@studiometa/js-toolkit';
 
-export default class Counter extends Base {
+class Counter extends Base {
   static config = {
     name: 'Counter',
-    refs: ['add', 'remove', 'count'],
+    refs: ['add', 'count'],
+    options: { step: { type: Number, default: 1 } },
   };
 
-  get counter() {
-    return this.$refs.count.valueAsNumber;
-  }
-
-  set counter(value) {
-    this.$refs.count.value = value;
-  }
-
   onAddClick() {
-    this.counter += 1;
-  }
-
-  onRemoveClick() {
-    this.counter -= 1;
+    this.$refs.count.textContent = Number(this.$refs.count.textContent) + this.$options.step;
   }
 }
-```
-
-And its accompanying HTML would be sprinkled with `data-…` attributes to bind elements from the DOM to the JavaScript class.
-
-```html
-<div data-component="Counter">
-  <button data-ref="add">Add</button>
-  <button data-ref="remove">Remove</button>
-  <input data-ref="count" type="number" value="0" />
-</div>
-```
 
-You can define options that can be specified with `data-option-...` attributes as well. First in JavaScript:
-
-```diff
-  class Counter extends Base {
-    static config = {
-      name: 'Counter',
-      refs: ['add', 'remove', 'count'],
-+     options: {
-+       step: {
-+         type: Number,
-+         default: 1,
-+       },
-+     },
-    };
-
-    onAddClick() {
--     this.counter += 1;
-+     this.counter += this.$options.step;
-    }
-
-    onRemoveClick() {
--     this.counter -= 1;
-+     this.counter -= this.$options.step;
-    }
-  }
-```
-
-And then adjust it as you wish in your HTML:
-
-```diff
-- <div data-component="Counter">
-+ <div data-component="Counter" data-option-step="2">
-    <button data-ref="add">Add</button>
-    <button data-ref="remove">Remove</button>
-    <input data-ref="count" type="number" value="0">
-  </div>
+registerComponent(Counter);
 ```
 
-Like Web Components, components based on the `Base` class can be registered. Any matching component found in the DOM from the moment it is registered to any future change will be mounted.
+There is no build step to adopt: the same class runs from a `<script type="module">` and an import map.
 
-```js
-import { registerComponent } from '@studiometa/js-toolkit';
-import Counter from './components/Counter.js';
+## Documentation
 
-registerComponent(Counter);
-```
+[js-toolkit-v4.studiometa.dev](https://js-toolkit-v4.studiometa.dev) — the guide, the full API reference, and the [v3 to v4 migration guide](https://js-toolkit-v4.studiometa.dev/guide/migration/v3-to-v4.html).
 
-Visit our ["Getting Started" guide](https://js-toolkit.studiometa.dev/guide/) to learn more and try the above component by visiting [the playground](https://ui.studiometa.dev/-/play/#script=eNqVkjFPwzAQhff%2BijcguRVtEGurSpTuDKyIwdiXYprYkX2pQFX%2BO7bjlg6A1EiJndO97873bNrOecYRjzLQHMqTZNp0HQbU3rUQD4F7bVxLLO8%2BwoKda%2FaGxWoyUY0MAVvXWyYP%2BmSyOmQOjhMgsGSjoJytzQ7rHAOsbGkJUVRinoOe6rDEi5BaizmEp9YdKO1UShOvY5br2DgbE0dSqkDdzx%2FAX11kP%2FXtG%2FlRkh5NtewbXuL%2BFBvGzRC%2FQzwHsCOOfeaOprMC9MS9t%2BB3E6qb1GCVM6qDbHrahLHKKiESIVwQcsYJ87s%2BjiOvZ72zG623jVH7cwNZWZi4XRdSGUKVzn6hfs4j%2Bwew%2BBsQEaOVyfbrbIyKYqFy8SJZsnzhTzG5TDstcdyp2umSTeM7W30DtazCdQ%3D%3D&html=eNqFkEsKwzAMRPc9hdDe5EOXcaD0Br2BEyvBkMjGkUN7%2Byb1ogkUupJAmjfMNNatYI0Y1fs5eCYWjXefWChiPvggzrNahILGGqGfzLJoDOoKw0RPGM22YnsBaLok4jnLIg0ajbUHQQ3dqLopkarKEuLmYslie7O2KbL0NyXS7Ff6D3p8%2Fk4sxyHJAdXv0RDkFUgjp7nbY65mQ2ksTw7R8aiqPBwvJF%2BfS1NstbVv4jxoZA%3D%3D&style=eNpLyk%2BpVKjmUlAoSExJycxLt1IwLErNteaqBQBpsgf8). Discover our existing library of components by checking out the [@studiometa/ui](https://github.com/studiometa/ui) package.
+The design record lives in the repository: [DESIGN.md](./DESIGN.md) states what v4 does, and [RATIONALE.md](./RATIONALE.md) states why, which options were refused, and what the measurements are.
 
 ## Contributing
 
-This projects follows the [Git Flow](https://github.com/petervanderdoes/gitflow-avh) methodology to manage its branches and features. The packages and their dependencies are managed with NPM workspaces. The files are linted with ESLint, type checked with TypeScript and formatted with Prettier.
+See the [repository README](https://github.com/studiometa/js-toolkit#contributing). Fixes for the 3.x line go to the [`3.x` branch](https://github.com/studiometa/js-toolkit/tree/3.x).
 
 ## License
 
-See [LICENSE](./LICENSE).
+[MIT](./LICENSE)

package/dist/Base.d.ts

@@ -0,0 +1,371 @@
+import { Memo } from "./utils/memo.js";
+import { BASE_BRAND } from "./component-brand.js";
+import { ContextKey } from "./context.js";
+import { ToolkitDiagnosticCode } from "./diagnostic-contract.js";
+import { HANDLER_REGISTRATIONS, INSTANCES } from "./protocol-symbols.js";
+import { ScheduledTask } from "./scheduler.js";
+import { MountStrategy } from "./mount-strategies.js";
+//#region src/Base.d.ts
+type OptionType = typeof String | typeof Number | typeof Boolean | typeof Array | typeof Object;
+/** An ordered list of types accepted by one option. */
+type OptionTypes = readonly OptionType[];
+type OptionDefinitionType = OptionType | OptionTypes;
+/**
+ * The value an option of a given type holds.
+ */
+type OptionValue<T extends OptionDefinitionType> = T extends OptionTypes ? OptionValue<T[number]> : T extends typeof String ? string : T extends typeof Number ? number : T extends typeof Boolean ? boolean : T extends typeof Array ? unknown[] : Record<string, unknown>;
+type PrimitiveOptionType = typeof String | typeof Number | typeof Boolean;
+/** `Array` and `Object` defaults must be per-instance factories. */
+type TypedOptionDefinition<T extends OptionDefinitionType = OptionDefinitionType> = T extends OptionTypes ? {
+  type: T;
+  default?: (() => OptionValue<T>) | (Extract<T[number], PrimitiveOptionType> extends never ? never : OptionValue<Extract<T[number], PrimitiveOptionType>>);
+} : T extends OptionType ? T extends typeof Array | typeof Object ? {
+  type: T;
+  default?: () => OptionValue<T>;
+} : {
+  type: T;
+  default?: OptionValue<T> | (() => OptionValue<T>);
+} : never;
+type OptionDefinition = OptionDefinitionType | TypedOptionDefinition;
+interface OptionChange<T = unknown> {
+  name: string;
+  value: T;
+  previousValue: T | undefined;
+  rawValue: string | null;
+  previousRawValue: string | null;
+  initial: boolean;
+}
+type OptionChangedReturn = void | (() => void);
+/** Lazy importer resolving to a component class, default export or module namespace. */
+type ComponentImporter = () => Promise<unknown>;
+interface BaseConfig {
+  name: string;
+  /** Child classes or lazy importers keyed by component name. Importers are registered without being called. */
+  components?: Record<string, BaseConstructor | ComponentImporter>;
+  refs?: string[];
+  options?: Record<string, OptionDefinition>;
+  /**
+   * When instances of this component mount. Defaults to `eager`; an
+   * element's `data-mount` attribute overrides it.
+   */
+  mountStrategy?: MountStrategy;
+}
+/** Structural component constructor compatible with typed `Base` subclasses. */
+interface BaseConstructor {
+  new (el: HTMLElement): Base<any>;
+  config: BaseConfig;
+  readonly prototype: Base<any>;
+}
+/** Child event payload. `payload` is the unchanged event detail, typed from the child's `$emits`. */
+interface DelegatedEvent<T extends Base = Base, K extends string = string> {
+  event: Event;
+  target: T;
+  payload: EmitDetail<PropsOf<T>, K>;
+}
+/**
+ * Payload given to `on<Ref><Event>` handlers. `index` is the ref's position
+ * among the same-named refs, so a list of buttons can be told apart.
+ */
+interface RefEvent<T extends HTMLElement = HTMLElement> {
+  event: Event;
+  target: T;
+  index: number;
+}
+/** Global handler payload containing the named target and platform event. */
+interface GlobalEvent<T extends Event = Event> {
+  event: T;
+  target: Window | Document;
+}
+/**
+ * Type-level description of a component's public surface.
+ *
+ * `$el` narrows the root element. `$emits` maps event names to payload objects, or `void` for events without payloads. Declarations do not validate markup at runtime.
+ */
+interface BaseProps {
+  $el?: HTMLElement;
+  $refs?: Record<string, HTMLElement | HTMLElement[]>;
+  /** `object` accepts named option interfaces without requiring an index signature. */
+  $options?: object;
+  $emits?: EmitMap;
+}
+/**
+ * What `$emits` maps an event name to: the payload object the event carries,
+ * or `void` for one that carries nothing.
+ */
+type EmitMap = Record<string, object | void>;
+type El<T extends BaseProps> = T['$el'] & HTMLElement;
+type Refs<T extends BaseProps> = T['$refs'] & Record<string, HTMLElement | HTMLElement[]>;
+type Options<T extends BaseProps> = T['$options'] & Record<string, unknown>;
+/** Resolve declared event names without widening them to `string`. */
+type Emits<T extends BaseProps> = NonNullable<T['$emits']> & (unknown extends T['$emits'] ? EmitMap : unknown);
+/**
+ * A component that declares `$emits` may only emit those names; one that
+ * does not keeps the unrestricted signature — `keyof EmitMap` is `string`.
+ */
+type EmitName<T extends BaseProps> = keyof Emits<T> & string;
+/**
+ * The `detail` an event carries: the declared payload object, or `null` for an
+ * event declared `void`. `null` rather than `{}` because that is what the
+ * platform stores for a `CustomEvent` built without a detail — nothing is
+ * synthesized to stand in for a payload nobody announced.
+ */
+type EmitDetail<T extends BaseProps, K extends string> = string extends K ? unknown : PayloadOf<Emits<T>, K>;
+/**
+ * One payload, looked up in a resolved `$emits` map. The lookup is an indexed
+ * access rather than `K extends keyof M ? … : never`: `keyof M` mentions the
+ * props parameter, and a conditional that tests against it is deferred for
+ * every component that has one.
+ */
+type PayloadOf<M extends EmitMap, K extends string> = M[K] extends void ? null : M[K];
+/**
+ * `$emit()`'s payload parameter, as a tuple so a declared payload is
+ * **required** and a `void` event takes none — an event declared `void` accepts
+ * no payload object, only the absent argument.
+ */
+type EmitArgs<T extends BaseProps, K extends string> = string extends K ? [payload?: object] : ArgsOf<Emits<T>, K>;
+/** Check concrete `void` first so generic component argument tuples remain resolvable. */
+type ArgsOf<M extends EmitMap, K extends string> = void extends M[K] ? [payload?: M[K]] : [payload: M[K]];
+/**
+ * The props a component was declared with, read from the phantom carrier
+ * `Base` holds — inferring through `Base<infer P>` does not work, since the
+ * parameter only appears inside conditional types.
+ */
+type PropsOf<T> = T extends {
+  __props?: infer P;
+} ? NonNullable<P> extends BaseProps ? NonNullable<P> : BaseProps : BaseProps;
+interface WatchChildrenCallbacks<T extends Base = Base> {
+  added?(instance: T): void;
+  removed?(instance: T): void;
+}
+/**
+ * Live, DOM-ordered view over mounted descendants matched by exact component
+ * name or by a component constructor and its subclasses.
+ */
+interface ChildrenCollection<T extends Base = Base> extends Iterable<T> {
+  readonly size: number;
+  readonly items: T[];
+}
+interface LifecycleEventDetail {
+  instance: Base;
+}
+/**
+ * One handler declared with the `@on` decorator. Initializers store these on
+ * the realm-stable `HANDLER_REGISTRATIONS` key for each instance.
+ */
+interface HandlerRegistration {
+  /**
+   * The decorated method's name, and the only key the magic name scan dedupes
+   * on. Not the function it decorates: `@read` and `@write` **replace** the
+   * method with a wrapper, so a `@write` applied above an `@on` leaves the
+   * class carrying a function this registration never saw. Comparing
+   * identities missed it and bound the same handler a second time, which made
+   * the order the two decorators are stacked in part of the interface. The
+   * name is the same on both sides whatever wraps the body.
+   */
+  method: string | symbol;
+  /**
+   * Global event target for `@on(window, …)` / `@on(document, …)`, `null` for
+   * everything the component can reach from its own subtree. Recorded as the
+   * target itself rather than as a reserved `child` name, so the string space
+   * stays free for a child or a ref actually called `window`.
+   */
+  target: Window | Document | null;
+  /**
+   * Child component name — or ref name, spelled the way `config.refs` declares
+   * it, `[]` included for a list — for delegated handlers. `null` for own
+   * events.
+   */
+  child: string | null;
+  type: string;
+  handler: (this: any, payload: any) => void;
+}
+declare global {
+  interface Element {
+    [INSTANCES]?: Map<string, Base>;
+  }
+}
+/**
+ * Whether an option can hold `false`, and therefore whether the negated
+ * attribute means anything for it. A union is enough: `[Boolean, String]` can
+ * be turned off, `[String, Number]` has nothing to turn off.
+ */
+declare function declaresBoolean(definition: OptionDefinition): boolean;
+/**
+ * Merge inherited config. Collections merge; declared scalar values override parent values.
+ *
+ * The registry uses this before an instance exists. Memoised per class: a
+ * config is a pure function of the prototype chain, and `$config` reads it on
+ * every access.
+ */
+declare const resolveConfig: Memo<[ctor: BaseConstructor], BaseConfig>;
+/**
+ * `mounted()` may return one cleanup, several, nothing — or a promise of
+ * those. The shape nests, so a subclass composes with what it extends
+ * without unpacking it: `return [super.mounted(), () => { … }]`.
+ */
+type MountedReturn = void | (() => void) | MountedReturn[] | Promise<MountedReturn>;
+/**
+ * The class every component extends.
+ * @link https://js-toolkit-v4.studiometa.dev/api/
+ */
+declare class Base<T extends BaseProps = BaseProps> {
+  #private;
+  /** A class-owned brand inherited by subclasses and shared by bundled copies. */
+  static readonly [BASE_BRAND] = true;
+  static config: BaseConfig;
+  /**
+   * Phantom carrier for the props type: type-only, never assigned, so
+   * another component can read this one's declared surface.
+   */
+  readonly __props?: T;
+  /**
+   * Unique, stable instance id (`<ComponentName>-<sequence>`).
+   *
+   * Generated once during construction from the resolved component name. It
+   * stays unchanged across unmount and remount cycles, so a component can use
+   * it for persistent ARIA relationships without changing the DOM id itself.
+   */
+  readonly $id: string;
+  readonly $el: El<T>;
+  /**
+   * Live view over the component's `data-ref` elements: every access
+   * re-reads the DOM, so replaced markup is picked up with nothing to
+   * refresh.
+   */
+  readonly $refs: Refs<T>;
+  /**
+   * Read-only view over the component's `data-option-*` attributes: an option
+   * is an input, never a store.
+   *
+   * `buildOptions()` defines every property with a getter and no setter, so
+   * the value is derived from the DOM and the viewport on each access and
+   * nothing is ever written in. Assigning to one throws a `TypeError`, since
+   * a module is strict code; the type says the same thing ahead of the throw.
+   *
+   * A component which must change a value it read keeps a private field
+   * seeded from the option. One which means the DOM to change writes the
+   * attribute, which is the same statement the markup makes.
+   *
+   * The constructor is the one place it is set.
+   */
+  readonly $options: Readonly<Options<T>>;
+  /** Filled by the `@on` decorator's initializers, if any are used. */
+  [HANDLER_REGISTRATIONS]?: HandlerRegistration[];
+  get $config(): BaseConfig;
+  get $isMounted(): boolean;
+  constructor(el: HTMLElement);
+  /**
+   * Lifecycle hook, meant to be overridden. May return a cleanup function
+   * (or an array of them) that runs on the next `$unmount()` — sync or
+   * async:
+   *
+   *     async mounted() {
+   *       const signal = await this.$inject(SomeContext);
+   *       return signal.subscribe((value) => { … });
+   *     }
+   *
+   * A component extending a mixin returns what it extends along with its
+   * own, in any nesting:
+   *
+   *     mounted() {
+   *       return [super.mounted(), () => { … }];
+   *     }
+   */
+  mounted(): MountedReturn;
+  /**
+   * Lifecycle hook, meant to be overridden. Runs at the end of `$unmount()`,
+   * after the `mounted()` cleanups, and returns nothing: a teardown that
+   * belongs to a specific piece of setup is better written as the cleanup
+   * `mounted()` returns, next to the setup it undoes.
+   */
+  unmounted(): void;
+  /**
+   * Mount the instance. `$unmount()` is its inverse and the same instance can
+   * mount again — this is what happens when an element is moved or
+   * re-inserted in the DOM.
+   */
+  $mount(): this;
+  /**
+   * End the mount cycle. Removes the per-cycle listeners, leaves the
+   * services, cancels the scheduler tasks the cycle left pending, runs the
+   * `mounted()` cleanups and calls the `unmounted()` hook. The instance stays
+   * on its element and `$mount()` starts a new cycle.
+   */
+  $unmount(): this;
+  /**
+   * Dispatch a bubbling, cancelable event with the payload as `detail`.
+   *
+   * @returns The dispatched event. Check `defaultPrevented` for cancellation.
+   */
+  $emit<K extends EmitName<T>>(event: K, ...payload: EmitArgs<T, K>): CustomEvent<EmitDetail<T, K>>;
+  $on(type: string, listener: EventListener, options?: AddEventListenerOptions): () => void;
+  $off(type: string, listener: EventListener, options?: AddEventListenerOptions): void;
+  /**
+   * Mounted descendant instances by component name, in DOM order.
+   */
+  $query<T extends Base = Base>(name: string): T[];
+  /**
+   * Nearest mounted ancestor instance by component name.
+   */
+  $closest<T extends Base = Base>(name: string): T | null;
+  /**
+   * Return a live, DOM-ordered collection of mounted descendants.
+   *
+   * A string matches `config.name`. A class also matches subclasses.
+   */
+  $watchChildren<T extends Base = Base>(name: string, callbacks?: WatchChildrenCallbacks<T>): ChildrenCollection<T>;
+  $watchChildren<T extends BaseConstructor>(ComponentClass: T, callbacks?: WatchChildrenCallbacks<InstanceType<T>>): ChildrenCollection<InstanceType<T>>;
+  /**
+   * Provide a value verbatim to the subtree for as long as the element lives.
+   * The nearest provider wins.
+   *
+   * The provider sits on the element, not on the mount cycle, so it answers
+   * through every unmount and mount. Nothing releases it early: a component
+   * whose declaration is withdrawn keeps providing until its element goes.
+   */
+  $provide<V>(key: ContextKey<V>, value: V): V;
+  /**
+   * Resolve the nearest value now or when a provider appears. The request remains pending without a provider and is canceled on unmount.
+   */
+  $inject<V>(key: ContextKey<V>): Promise<V>;
+  /** Resolve the nearest value now, or return `undefined` without queuing a request. */
+  $injectSync<V>(key: ContextKey<V>): V | undefined;
+  /**
+   * Apply one mutation batch after declaration reconciliation. Option cleanup runs before the next value and on unmount. Only resolved value changes trigger effects.
+   *
+   * @internal
+   */
+  $optionsChanged(changes: ReadonlyMap<string, string | null>): void;
+  /**
+   * Report a warning on the diagnostic channel, as this component.
+   *
+   * The component name and the element are filled in from the instance, which
+   * is the whole reason this exists on `Base` rather than being a bare
+   * function a component imports: those two are what a listener filters and
+   * inspects on, and a component is the one thing that always knows both.
+   *
+   * The code is namespaced — `'figure.load-failed'` — so a listener can select
+   * one component's diagnostics without matching on message text. Core's own
+   * codes are enumerated in `DIAGNOSTICS`; a code outside that set is a
+   * consumer's, and the shape is all that is required of it.
+   *
+   * Canceling the event suppresses the default `console.warn` and nothing
+   * else, so a host application can route these into its own reporter.
+   */
+  $warn(code: ToolkitDiagnosticCode, message: string): void;
+  /**
+   * Report a recovered failure on the diagnostic channel, as this component.
+   *
+   * The counterpart to {@link $warn} for the case where something threw and
+   * the component carried on: the original value is required, because a
+   * reporter that cannot see the cause cannot do anything useful with it.
+   * Canceling suppresses the default error sink.
+   */
+  $error(code: ToolkitDiagnosticCode, message: string, error: unknown): void;
+  /** Schedule a DOM read; canceled automatically when the instance unmounts. */
+  $read<T>(fn: () => T): ScheduledTask<T>;
+  /** Schedule a DOM write; canceled automatically when the instance unmounts. */
+  $write<T>(fn: () => T): ScheduledTask<T>;
+}
+//#endregion
+export { Base, BaseConfig, BaseConstructor, BaseProps, ChildrenCollection, ComponentImporter, DelegatedEvent, EmitMap, GlobalEvent, HandlerRegistration, LifecycleEventDetail, MountedReturn, OptionChange, OptionChangedReturn, OptionDefinition, OptionType, OptionTypes, RefEvent, WatchChildrenCallbacks, declaresBoolean, resolveConfig };