@twobirds/microcomponents 0.4.0 → 0.5.0

package/dist/mcp/api.json

@@ -0,0 +1,601 @@
+{
+  "libraryVersion": "0.5.0",
+  "exportedCount": 41,
+  "entries": {
+    "MC": {
+      "name": "MC",
+      "kind": "class",
+      "file": "src/core/MC.ts",
+      "signatures": [
+        "class MC<TTarget extends object = object> extends McBase<TTarget> {"
+      ],
+      "description": "A general-purpose base microcomponent that does not require a DOM target.\n\nInherits from `McBase`, but is primarily used as a lightweight container or\nfor logic not directly tied to DOM elements."
+    },
+    "DC": {
+      "name": "DC",
+      "kind": "class",
+      "file": "src/core/MC.ts",
+      "signatures": [
+        "class DC< T extends HTMLElement = HTMLElement, EM extends Record<string, unknown> = Record<never, never>, > extends McBase<T> implements McController<T> {"
+      ],
+      "description": "A DOM-centric microcomponent that operates on a specific HTML element.\n\nExtends McBase and associates itself with an actual DOM node via the\n`_target` reference. Provides methods for event handling, DOM traversal,\nand interaction with sibling or ancestor microcomponents.\n\n\n## Static Configuration Properties\n\nDC classes support three static properties that configure custom elements\nbefore any instance is constructed:\n\n### `static tag?: string`\n\nReplaces the default target element with a semantic HTML element, or removes it entirely.\n\n- **Non-empty string** (e.g., `'header'`) — the original custom element is replaced\nwith the specified built-in element. The original tag name is added as a CSS class.\n- **Empty string `''`** — the target element is removed from the DOM entirely.\nUseful for components that only inject global styles or act as style containers.\n\nProduces `<header class=\"shop-header\">` instead of `<shop-header>`.\n\nThe element self-destructs; only side effects (e.g., injected styles) remain.\n\n### `static assets: string[]`\n\nDeclares companion files for auto-loading by convention. Asset names are camelCase\nand translated into file extensions: `'targetHtml'` → `.target.html`, `'json'` → `.json`.\n\nThe path is derived from the custom element tag segments, and the basename is the\nlast segment. For `<cart-container-checkout>`, assets load from `/cart/container/checkout.*`.\n\nWhen assets finish loading, an `'assets'` event fires so that `oneAssets(ev)` can\nprocess them. Everything ending in `Json` arrives parsed; all other files arrive as text.\n\n*One-time global styles**: Assets named `'css'` and `'targetCss'` inject CSS into the\nglobal document scope via `injectCSS(document, ...)`. Because these are idempotent\nglobal side effects, they are processed only once — after the first instance loads them,\nthe entries are removed from both `static assets` and `static _assets`. Subsequent\ninstances skip loading and re-processing them entirely.\n\n*CSS file roles**:\n\n- `.css` — design tokens only (CSS custom-property presets). Injected into the document\nscope once, like `targetCss`.\n- `.target.css` — layout rules for the light DOM. Also document-scoped and one-time.\n- `.shadow.css` — layout rules for the shadow DOM. Injected per instance into the\ncomponent's own shadow root, so each instance gets its own copy.\n\nEvery declared asset — CSS, HTML, JSON — is inlined into `static _assets` at build time by\nthe load-assets plugin, so a bundled build performs no fetches at all.\n\nIn a bundled build the plain `.css` files are additionally concatenated into a single\n`bundle.css` by the bundling script. That file is a convenience listing of the available\nvariables: copy the ones you want to change into your own stylesheet and override them\nthere. It is not required at runtime, and it cannot drift from the inlined presets — both\nare read from the same source files.\n\nThe runtime decides whether an asset still needs fetching with `!ctor._assets[key]`, so an\ninlined entry must never be an empty string: that would trigger a re-fetch of a file that\ndoes not exist in a bundled build.\n\n`configJson` arrives already parsed into an object.\n\n### `static attributes?: object`\n\nSets HTML attributes on every instance automatically.\n\nEvery `<product-card>` carries `role=\"listitem\"`.\n\n### Combined usage\n\nAll three can be combined in one class:\n\nProduces `<section role=\"list\" aria-label=\"products\">`.\n\n\n## Event Handler Conventions\n\nMethods whose names start with `on` or `one` are automatically wired as event listeners\non the target element. The prefix determines persistence:\n\n- **`on<EventName>`** — persistent listener (fires every time)\n- **`one<EventName>`** — one-time listener (fires once, then detaches)\n\n### Web Component Lifecycle Events\n\nWhen a DC is registered via defineCE, the custom element dispatches these\ninternal events that can be caught with handler methods:\n\n| Method | When it fires |\n|--------|---------------|\n| `onConnected()` | Element was inserted into the DOM (`connectedCallback`) |\n| `onDisconnected()` | Element was removed from the DOM (`disconnectedCallback`) |\n| `onAdopted()` | Element was moved to a new document (`adoptedCallback`) |\n| `onAttributeChanged()` | An observed attribute changed (`attributeChangedCallback`) |\n| `oneInit()` | Constructor finished; all synchronous setup complete (microtask) |\n| `oneAssets()` | Constructor finished; all assets loaded and available; ev contains assets object |\n\n\n## Construction Patterns\n\n### Template usage (declarative)\n\n```ts\nclass MyElement extends DC {}\ndefineCE('my-element', MyElement);\n```\n\nThe registered element is then used in HTML as `<my-element></my-element>`.\n\n### Programmatic construction with data\n\nWhen constructing programmatically via getCE, pass only the `data` payload —\nthe target element is created automatically by the custom element constructor.\n\n### Data from HTML attributes\n\nUsed in HTML as `<my-element my-data='{\"name\":\"John\"}'></my-element>`.\n\n\n## Plugin Extension Points\n\nThe prototype of `DC` (inherited from McBase) is extended at runtime by optional\nplugins. See the McBase documentation for details on State.observePlugin and\nState.formValuePlugin.\n\n`trigger()` checks the payload against the registered `CartUpdate` shape, and the `on()`\nhandler receives a fully typed `ev`.",
+      "examples": [
+        {
+          "title": "static tag — replace with semantic element",
+          "code": "class ShopHeader extends DC {\nstatic tag = 'header';\n}\ndefineCE('shop-header', ShopHeader);"
+        },
+        {
+          "title": "static tag — remove element entirely",
+          "code": "class GlobalStyles extends DC {\nstatic tag = '';\n}\ndefineCE('global-styles', GlobalStyles);"
+        },
+        {
+          "title": "static assets with autoload",
+          "code": "class CartCheckout extends DC {\nstatic assets = ['targetHtml', 'targetCss', 'configJson'];\n\noneAssets(ev) {\nconst { configJson } = ev.detail.data;\nconsole.log(configJson);\n}\n}\ndefineCE('cart-checkout', CartCheckout);"
+        },
+        {
+          "title": "static attributes",
+          "code": "class ProductCard extends DC {\nstatic attributes = { role: 'listitem' };\n}\ndefineCE('product-card', ProductCard);"
+        },
+        {
+          "title": "All static properties together",
+          "code": "class ShopCatalog extends DC {\nstatic tag = 'section';\nstatic attributes = { role: 'list', 'aria-label': 'products' };\nstatic assets = ['targetHtml', 'targetCss'];\n}\ndefineCE('shop-catalog', ShopCatalog);"
+        },
+        {
+          "title": "Event handlers in action",
+          "code": "class MyElement extends DC {\nonConnected() {\nconsole.log('entered the DOM');\n}\n\nonDisconnected() {\nconsole.log('left the DOM');\n}\n\nonClick() {\nthis.trigger('something', 'payload');\n}\n\noneSomething(ev) {\nconsole.log('first time only:', ev.detail.data);\n}\n}\ndefineCE('my-element', MyElement);"
+        },
+        {
+          "title": "Programmatic construction",
+          "code": "class MyElement extends DC {\ndata = {};\n\nconstructor(target, data) {\nsuper(target);\nthis.data = data;\n}\n}\ndefineCE('my-element', MyElement);\n\nconst Ctor = getCE('my-element');\ndocument.body.append(new Ctor({ name: 'John' }));"
+        },
+        {
+          "title": "Reading data from an attribute",
+          "code": "class MyElement extends DC {\ndata = {};\n\nconstructor(target) {\nsuper(target);\nthis.data = JSON.parse(target.getAttribute('my-data'));\n}\n}\ndefineCE('my-element', MyElement);"
+        },
+        {
+          "title": "Typed event map",
+          "code": "class Cart extends DC<HTMLFormElement, { CartUpdate: { count: number } }> {\ncheckout() {\nthis.trigger('CartUpdate', { count: 2 }, 'u');\nthis.on('CartUpdate', (ev) => ev.detail.data.count);\n}\n}"
+        }
+      ]
+    },
+    "McBase": {
+      "name": "McBase",
+      "kind": "class",
+      "file": "src/core/MC.ts",
+      "signatures": [
+        "class McBase<TTarget extends object = object> {"
+      ],
+      "description": "The base class for all microcomponents — shared root of both MC and DC.\n\nHolds a `WeakRef` to the target (a DOM element for `DC`, or any plain object for `MC`)\nto avoid circular references. For `DC` subclasses it also bootstraps two automatic\nbehaviours:\n\n1. **Event listener auto-attachment** — methods whose names start with `on` or `one`\n(e.g. `onClick`, `oneInit`) are wired to the target element via on / one.\n2. **\"Init\" lifecycle event** — dispatched asynchronously in a microtask so that all\nsynchronous constructor work finishes first.\n\nBoth mechanisms run only when the instance is a `DC` (checked with `instanceof DC`).\nPlain `MC` instances skip them entirely, keeping server-side usage lightweight.\n\n### Plugin extension points\n\nThe prototype of `McBase` is the attachment point for optional plugins that curry\nadditional instance methods onto every microcomponent. Two built-in plugins modify\nthis class at runtime:\n\n- **State.observePlugin** — adds `notify()`, `subscribe()`, and `bind()` so that\nobservable properties can be controlled directly on the component instance with\nfluent chaining. Call `observePlugin(DC)` once at module level to activate.\n\n- **State.formValuePlugin** — adds `formValues()` for two-way binding between DOM\nform controls and an observable property. Also pulls in all methods from\nState.observePlugin, so you can chain `.subscribe()` and `.bind()` after\n`.formValues()`. Call `formValuePlugin(DC)` once at module level to activate.\n\nBoth plugins are idempotent — calling them multiple times has no side effects. They\nwork by assigning methods onto `McBase.prototype` (reached via\n`Object.getPrototypeOf(Class.prototype)`) and use TypeScript module augmentation\n(`declare module`) so the added signatures appear in type-checking automatically.\n\n`observePlugin(DC)` adds `notify()`, `subscribe()`, `bind()` to `McBase.prototype`;\n`formValuePlugin(DC)` adds `formValues()` and re-runs `observePlugin`. `oneInit()`\nruns once after the constructor.",
+      "examples": [
+        {
+          "title": "Extending with plugins at runtime",
+          "code": "import { DC, observePlugin, formValuePlugin } from '@twobirds/microcomponents';\n\nobservePlugin(DC);\nformValuePlugin(DC);\n\nclass MyForm extends DC {\ndata = { name: '' };\n\noneInit() {\nthis\n.formValues(this.target, 'data')\n.subscribe('data', (v) => console.log(v))\n.bind('data', this.target);\n}\n}"
+        }
+      ]
+    },
+    "defineCE": {
+      "name": "defineCE",
+      "kind": "function",
+      "group": "Elements",
+      "file": "src/core/elements.ts",
+      "signatures": [
+        "export function defineCE< Tag extends `${string}-${string}`, T extends object, D, E extends keyof HTMLElementTagNameMap | undefined = undefined, >( tagName: Tag, DefinitionClass: new (target: TargetOf<E>, data?: D) => T, observedAttributes?: string[], extend?: E",
+        "export function defineCE< Tag extends `${string}-${string}`, T extends object, E extends keyof HTMLElementTagNameMap | undefined = undefined, >( tagName: Tag, DefinitionClass: new (target: TargetOf<E>) => T, observedAttributes?: string[], extend?: E ): McElementConstructor<T, undefined, E, McPascalCase<Tag>> | undefined;",
+        "export function defineCE< Tag extends `${string}-${string}`, T extends object, D, E extends keyof HTMLElementTagNameMap | undefined = undefined, >( tagName: Tag, DefinitionClass: new (target: TargetOf<E>, data: D) => T, observedAttributes?: string[], extend?: E",
+        "export function defineCE< Tag extends `${string}-${string}`, T extends object, D = unknown, E extends keyof HTMLElementTagNameMap | undefined = undefined, >( tagName: Tag, DefinitionClass: new (target: TargetOf<E>, data?: D) => T, observedAttributes: string[] = [], extend?: E"
+      ],
+      "description": "### Examples\n\n#### Define custom element in registry\n\n```ts\nclass MyElement extends DC {}\ndefineCE('my-element', MyElement);\n```\n\nThe registered element is then used in HTML as `<my-element></my-element>`.\n\n#### Define custom element in registry with observed attributes\n\n```ts\nclass MyElement extends DC {\nonAttributeChanged(ev){\nconst newValue = ev.detail.data.newValue;\n}\n}\ndefineCE('my-element', MyElement, ['observed']);\n```\n\nUsed in HTML as `<my-element observed></my-element>`. When the `observed` attribute\nchanges, `attributeChanged` is triggered, which calls `onAttributeChanged` with the\nchange data in the payload.\n\nDefines a custom HTML element with optional observed attributes and micro component integration.\nThe class provided in DefinitionClass will be added to the ._mc hash object appended to the custom element instance.\nAutomatically assigns a \"PascalCase\" class name derived from the <kebab-case> tagName.\nIf the provided definition class extends McBase (indicating a DC or MC class extension), it wraps the constructor to register\nthe element instance with DC (DomComponent)."
+    },
+    "getCE": {
+      "name": "getCE",
+      "kind": "function",
+      "group": "Elements",
+      "file": "src/core/elements.ts",
+      "signatures": [
+        "export function getCE<K extends keyof McElementTagNameMap & string>( tagName: K ): McElementTagNameMap[K] | undefined;",
+        "export function getCE(tagName: string): CustomElementConstructor | undefined;",
+        "export function getCE(tagName: string) {"
+      ],
+      "description": "Retrieves a custom element constructor by tag name.\n\nTags registered on the global McElementTagNameMap (via declaration\nmerging) come back as their declared constructor type — payload and `_mc`\nentry included; any other string falls back to the plain\n`CustomElementConstructor`.",
+      "examples": [
+        {
+          "title": "",
+          "code": "const MyElementClass = getCE('my-element');\nif (MyElementClass) {\ndocument.body.append(new MyElementClass());\n}"
+        }
+      ]
+    },
+    "listCE": {
+      "name": "listCE",
+      "kind": "function",
+      "group": "Elements",
+      "file": "src/core/elements.ts",
+      "signatures": [
+        "export function listCE(): string[] {"
+      ],
+      "description": "Returns an array of all tag names registered via defineCE.",
+      "examples": [
+        {
+          "title": "",
+          "code": "defineCE('my-element', MyElement);\ndefineCE('another-widget', AnotherWidget);\nconsole.log(listCE());"
+        }
+      ]
+    },
+    "TargetOf": {
+      "name": "TargetOf",
+      "kind": "type alias",
+      "group": "Types",
+      "file": "src/core/elements.ts",
+      "signatures": [
+        "export type TargetOf<E> = E extends keyof HTMLElementTagNameMap ? HTMLElementTagNameMap[E] : HTMLElement;"
+      ],
+      "description": "Resolves the host element type for a given `extend` tag: the matching built-in\nelement type when extending one (e.g. `'button'` → `HTMLButtonElement`),\nplain `HTMLElement` otherwise.\n\n`Btn` resolves to `HTMLButtonElement`, `Plain` to plain `HTMLElement`.",
+      "examples": [
+        {
+          "title": "",
+          "code": "type Btn = TargetOf<'button'>;\ntype Plain = TargetOf<'div'>;"
+        }
+      ]
+    },
+    "McPascalCase": {
+      "name": "McPascalCase",
+      "kind": "type alias",
+      "group": "Types",
+      "file": "src/core/elements.ts",
+      "signatures": [
+        "export type McPascalCase<S extends string> = S extends `${infer Head}-${infer Rest}` ? `${Capitalize<Head>}${McPascalCase<Rest>}` : Capitalize<S>;"
+      ],
+      "description": "The type-level mirror of `kebabToPascal()` in helpers.ts: `'user-card'` →\n`'UserCard'`. Lets defineCE type the `_mc` registry entry under the\nexact key the runtime stores it at."
+    },
+    "McElementConstructor": {
+      "name": "McElementConstructor",
+      "kind": "type alias",
+      "group": "Types",
+      "file": "src/core/elements.ts",
+      "signatures": [
+        "export type McElementConstructor< T extends object = object, D = unknown, E extends keyof HTMLElementTagNameMap | undefined = undefined, N extends string = string, > = new (data?: D) => McHost<TargetOf<E>, string extends N ? Record<never, never> : Record<N, T>>;"
+      ],
+      "description": "The custom element constructor returned by defineCE. Constructing it\nprogrammatically accepts an optional `data` payload, forwarded as the second\nargument to the microcomponent class. The resulting element exposes its\nmicrocomponent instance via `._mc`, keyed by the PascalCase form of the tag\nname (`N`); with the default `N = string` no entry is claimed."
+    },
+    "isMcHost": {
+      "name": "isMcHost",
+      "kind": "function",
+      "group": "Helpers",
+      "file": "src/core/mcGuards.ts",
+      "signatures": [
+        "export function isMcHost<T extends HTMLElement, K extends keyof McRegistry & string>( element: T, key: K ): element is McHost<T, Pick<McRegistry, K>>;",
+        "export function isMcHost<K extends keyof McRegistry & string>( element: unknown, key: K ): element is McHost<HTMLElement, Pick<McRegistry, K>>;",
+        "export function isMcHost<T extends HTMLElement>(element: T): element is McHost<T>;",
+        "export function isMcHost(element: unknown): element is McHost;",
+        "export function isMcHost(element: unknown, key?: string): boolean {"
+      ],
+      "description": "Checks whether the given value is a microcomponent host element (McHost).\n\nBare form: narrows to the controller API only — no registry entries are claimed,\nbecause different elements carry different `_mc` records and the type system\ncannot know which keys a specific element holds.\n\nKeyed form: additionally checks `key in element._mc` at runtime and narrows the\nentry to the type bound on the global `McRegistry` interface — *non-optional*,\nbecause presence was just verified. The binding is an app-wide naming\nconvention (key name → component type); where type identity must be proven or\nkey names may collide, use `DC.get(el, key, Class)` instead.",
+      "examples": [
+        {
+          "title": "",
+          "code": "declare global {\ninterface McRegistry {\ncart: Cart;\n}\n}\n\nconst el = document.querySelector('form');\nif (el && isMcHost(el)) {\nel._mc.trigger('Ping');\n}\nif (el && isMcHost(el, 'cart')) {\nel._mc.cart.addItem(item);\n}"
+        }
+      ]
+    },
+    "observe": {
+      "name": "observe",
+      "kind": "function",
+      "file": "src/state/observables.ts",
+      "signatures": [
+        "export function observe<T extends object, K extends keyof T>( target: T, propertyName: K ): ObservedKey<T, K>;",
+        "export function observe<T extends object>(target: T): Observed<T>;",
+        "export function observe<S extends object>(target: Unobserved<S>): S;",
+        "export function observe(target: object, propertyName?: string): object {"
+      ],
+      "description": "Makes a target object's properties observable by replacing them with wrapped values.\n\nWraps each property of `target` that is not already observable (and meets criteria)\nin an observable wrapper. Also sets up deep change detection for objects and\ndebounced notifications when the data changes.\n\nThere are two sides to using it — pick per call site:\n\n*Declarative (typed class fields).** Declare the field as `Observable<T>` up\nfront, then let `observe(this, 'field')` install the live wrapper in the\nconstructor. The declaration needs the double cast once (`0 as unknown as\nObservable<number>`): the field starts life as a plain value and only becomes\nthe wrapper when `observe()` runs. In exchange, every later use is fully typed —\narithmetic, `subscribe`, `bind` — with no casts anywhere else.\n\n*Imperative (wrapping existing data).** Hand any object to `observe()` after\nthe fact — no declarations, the return type is inferred: every property comes\nback as `Observable<PropertyType>`.\n\nIncrementing `state.count` triggers the subscribed callback.\n\nPlain arithmetic compiles because the declaration carries the observable type.\n\nThe seed object is validated against the schema, the subscription callback is fully\ntyped, and plain assignment is legal because the declared setter type permits it.",
+      "examples": [
+        {
+          "title": "Imperative usage — wrap an existing plain object:",
+          "code": "const state = observe({ count: 0, label: 'hi' });\nstate.count.subscribe((v) => console.log('count is now', v));\nstate.count++;"
+        },
+        {
+          "title": "Declarative usage — typed class field with double cast:",
+          "code": "class Counter {\nclicks: Observable<number> = 0 as unknown as Observable<number>;\n\nconstructor() {\nobserve(this, 'clicks');\n}\n\nbump() {\nthis.clicks++;\n}\n}"
+        },
+        {
+          "title": "Schema-first usage — divergent read/write types via hand-declared interface:",
+          "code": "interface CounterState {\nget count(): Observable<number>;\nset count(v: number);\n}\n\nconst state = observe<CounterState>({ count: 0 });\nstate.count.subscribe((v) => console.log(v));\nstate.count = 5;"
+        }
+      ]
+    },
+    "observePlugin": {
+      "name": "observePlugin",
+      "kind": "function",
+      "file": "src/state/observables.ts",
+      "signatures": [
+        "export function observePlugin(Class: any) {"
+      ],
+      "description": "Attaches convenience methods `notify()`, `subscribe()`, and `bind()` to the prototype of a\nmicrocomponent class so that observable properties can be controlled directly on the instance.\n\nAll three methods return the component instance, so you can chain them fluently.\n\nCall it once at module level before defining any component classes. The plugin is idempotent —\nsubsequent calls are no-ops.",
+      "examples": [
+        {
+          "title": "",
+          "code": "class Counter extends DC {\ndata = { clicks: 1 };\n\noneAssets() {\nthis\n.subscribe('data', (v) => console.log('data →', v))\n.bind('data', this.target);\n}\n}"
+        }
+      ]
+    },
+    "isAlreadyObserved": {
+      "name": "isAlreadyObserved",
+      "kind": "function",
+      "file": "src/state/observables.ts",
+      "signatures": [
+        "export function isAlreadyObserved(value: unknown): boolean {"
+      ],
+      "description": "Whether a value is already an observable wrapper — `subscribe` is reachable on its prototype chain.\nUsed by observe to skip re-wrapping and to detect the \"not yet observed\" state on reassignment.\n\nThe wrapped property reports `true`, a plain primitive reports `false`.",
+      "examples": [
+        {
+          "title": "",
+          "code": "const state = observe({ count: 0 });\nconsole.log(isAlreadyObserved(state.count));\nconsole.log(isAlreadyObserved(42));"
+        }
+      ]
+    },
+    "Observable": {
+      "name": "Observable",
+      "kind": "type alias",
+      "file": "src/state/observables.ts",
+      "signatures": [
+        "export type Observable<T = unknown> = T & {"
+      ],
+      "description": "Interface representing an observable object that supports subscription, notification, and DOM binding.\n\nObservable objects track registered callbacks and invoke them when their internal state changes.\nThey can also be bound to a DOM target to automatically update placeholder values in the view layer.\n\nThe subscription fires on the increment, logging `count is now 1`.",
+      "examples": [
+        {
+          "title": "",
+          "code": "const state = observe({ count: 0 });\nstate.count.subscribe((v) => console.log('count is now', v));\nstate.count++;"
+        }
+      ]
+    },
+    "Callback": {
+      "name": "Callback",
+      "kind": "type alias",
+      "file": "src/state/observables.ts",
+      "signatures": [
+        "export type Callback<T = unknown> = (value: T) => void;"
+      ],
+      "description": "A callback invoked with the current observable value when notified.",
+      "examples": [
+        {
+          "title": "",
+          "code": "const cb: Callback<number> = (v) => console.log('new value:', v);\nobservable.subscribe(cb);"
+        }
+      ]
+    },
+    "Observed": {
+      "name": "Observed",
+      "kind": "type alias",
+      "file": "src/state/observables.ts",
+      "signatures": [
+        "export type Observed<T> = { [K in keyof T]: Observable<T[K]> };"
+      ],
+      "description": "Every property of `T` mapped to an observable of its value.\n\nKNOWN LIMIT: the runtime property *setter* accepts a plain value\n(`state.count = 5` re-wraps it), but this mapped type cannot say so — mapped\ntypes cannot declare divergent read/write (get/set) types, so the wrapper type\ngoverns writes too and plain assignment to a primitive observable is rejected.\nTracked upstream as https://github.com/microsoft/TypeScript/issues/43826\n(variant accessors for mapped types); when it lands, the write type here\nbecomes `T[K] | Observable<T[K]>` and the limit disappears.\n\nUntil then, use one of the supported write paths:\n- the `observed` variant, a single container whose `.value` gives \ntyped reads and writes today (`state.value.count = 5`, deep\nwrites included) — the limitation never applies;\n- `state.count++` (compiles today; TS does not re-check the `++` write-back);\n- the schema-first `observe<S>()` overload with a hand-declared get/set\ninterface, where the divergence IS expressible (and plain `=` becomes\nlegal) — see Unobserved.\n\nEvery property is mapped to an observable: `State` is\n`{ count: Observable<number>, name: Observable<string> }`.",
+      "examples": [
+        {
+          "title": "",
+          "code": "type State = Observed<{ count: number; name: string }>;"
+        }
+      ]
+    },
+    "ObservedKey": {
+      "name": "ObservedKey",
+      "kind": "type alias",
+      "file": "src/state/observables.ts",
+      "signatures": [
+        "export type ObservedKey<T, K extends keyof T> = {"
+      ],
+      "description": "Only `K` of `T` mapped to an observable; other properties keep their type.\nCarries the same write limitation as Observed for the mapped key.\n\nOnly `count` is mapped to an observable: `State` is\n`{ count: Observable<number>, label: string }`.",
+      "examples": [
+        {
+          "title": "",
+          "code": "type State = ObservedKey<{ count: number; label: string }, 'count'>;"
+        }
+      ]
+    },
+    "Unobserved": {
+      "name": "Unobserved",
+      "kind": "type alias",
+      "file": "src/state/observables.ts",
+      "signatures": [
+        "export type Unobserved<S> = {"
+      ],
+      "description": "The inverse of a hand-declared observable state interface: strips the\n`Observable` wrapper from every property, yielding the plain seed shape.\n`Unobserved<CounterState>` → `{ count: number }`.\n\nExtraction goes through the `subscribe` callback parameter, so it works for\nboth accessor-declared members (`get count(): Observable<number>`) and plain\n`Observable<T>` properties; non-observable members pass through unchanged.\n\nUsed by the schema-first `observe<S>()` overload to validate the seed object\nagainst the declared interface — see that overload's example.\n\n`Seed` strips the wrapper, yielding the plain seed shape `{ count: number }`. The\n`observe<CounterState>()` overload validates the seed object against the schema.",
+      "examples": [
+        {
+          "title": "",
+          "code": "interface CounterState {\nget count(): Observable<number>;\nset count(v: number);\n}\ntype Seed = Unobserved<CounterState>;\nconst state = observe<CounterState>({ count: 0 });"
+        }
+      ]
+    },
+    "formValues": {
+      "name": "formValues",
+      "kind": "function",
+      "file": "src/state/formValues.ts",
+      "signatures": [
+        "export function formValues<T extends object>( targetObject: T, propertyName: keyof T & string, dom: HTMLElement | ShadowRoot ) {"
+      ],
+      "description": "Attaches a form-values observable to a target object property, enabling two-way binding\nbetween DOM form controls and the object's state.\n\nScans the given DOM subtree for `input`, `select`, and `textarea` elements with a `name`\nattribute and creates live getters/setters on the resulting observable. Input events trigger\nautomatic notifications so subscribers react to user changes.\n\nReading `state.formData.username` reflects the live `<input name=\"username\">` value;\nassigning `state.formData.role` writes straight back to the `<select>` control.",
+      "examples": [
+        {
+          "title": "Bind a plain object to an HTML form element",
+          "code": "import { formValues } from '@twobirds/microcomponents/formValues';\n\nconst state = {};\nformValues(state, 'formData', document.getElementById('myForm'));\nconsole.log(state.formData.username);\nstate.formData.role = 'admin';"
+        },
+        {
+          "title": "Subscribe to form changes inside a component",
+          "code": "import { DC, defineCE, formValues } from '@twobirds/microcomponents';\n\nclass MyForm extends DC {\nstatic assets = ['targetHtml'];\n\noneAssets() {\nformValues(this, 'formData', this.target);\nthis.formData.subscribe((data) => console.log('form changed:', data));\n}\n}\n\ndefineCE('my-form', MyForm);"
+        }
+      ]
+    },
+    "formValuePlugin": {
+      "name": "formValuePlugin",
+      "kind": "function",
+      "file": "src/state/formValues.ts",
+      "signatures": [
+        "export function formValuePlugin(Class: any) {"
+      ],
+      "description": "Attaches a convenience method `formValues()` to the prototype of a microcomponent class so that\nform controls can be bound directly on the instance without importing the standalone function.\n\nThis plugin also pulls in all observable methods from observePlugin — `notify()`,\n`subscribe()`, and `bind()` — so you can chain them fluently after binding form data.\n\nCall it once at module level before defining any component classes. The plugin is idempotent —\nsubsequent calls are no-ops.",
+      "examples": [
+        {
+          "title": "",
+          "code": "import { DC, defineCE, formValuePlugin } from '@twobirds/microcomponents';\n\nformValuePlugin(DC);\n\nclass CheckoutForm extends DC {\nstatic assets = ['targetHtml'];\n\noneAssets() {\nthis\n.formValues(this.target, 'formData')\n.subscribe('formData', (data) => console.log(data))\n.bind('formData', this.target);\n}\n}\n\ndefineCE('checkout-form', CheckoutForm);"
+        }
+      ]
+    },
+    "getMcEventName": {
+      "name": "getMcEventName",
+      "kind": "function",
+      "file": "src/utils/events.ts",
+      "signatures": [
+        "export function getMcEventName(eventName: string): string {"
+      ],
+      "description": "Converts a standard event name to its microcomponent-prefixed variant.\n\nThis utility is used internally to namespace custom events (e.g., 'Click' → '_mcClick').",
+      "examples": [
+        {
+          "title": "",
+          "code": "console.log(getMcEventName('update'));"
+        }
+      ]
+    },
+    "trueEventName": {
+      "name": "trueEventName",
+      "kind": "function",
+      "file": "src/utils/events.ts",
+      "signatures": [
+        "export function trueEventName(target: HTMLElement, eventName: string): string {"
+      ],
+      "description": "Returns the correct event name to listen for on a DOM element.\n\nIf `eventName` (case-insensitive) matches a native HTML event handler property\n(`'on' + eventName.toLowerCase()`) on the target, returns the lowercase native\nname so that standard DOM events like `'click'` are listened to correctly.\nOtherwise, prefixes with `_mc` for microcomponent custom events.\n\n`'Click'` resolves to the native `'click'` because the button has an `onclick` handler\nproperty; `'Update'` has no native counterpart, so it becomes the `_mc`-prefixed custom\nevent name.",
+      "examples": [
+        {
+          "title": "",
+          "code": "const btn = document.createElement('button');\nconsole.log(trueEventName(btn, 'Click'));\nconsole.log(trueEventName(btn, 'Update'));"
+        }
+      ]
+    },
+    "off": {
+      "name": "off",
+      "kind": "function",
+      "file": "src/utils/events.ts",
+      "signatures": [
+        "export function off<D = unknown>( target: TargetSelect, eventName: string, handler: McEventHandler<D> ): void;",
+        "export function off( target: TargetSelect, eventName: string, handler: EventListenerOrEventListenerObject ): void;",
+        "export function off( target: TargetSelect, eventName: string, handler: EventListenerOrEventListenerObject | McEventHandler<never> ) {"
+      ],
+      "description": "Removes a previously attached event handler from the DOM node. See on and one.\n\nUses internal microcomponent-prefixed naming for event handlers.\nThis is primarily used to interface with external frameworks or vanilla JS environments.\nFor communication between frontend microcomponents, use the `DC.off()` method instead.",
+      "examples": [
+        {
+          "title": "",
+          "code": "const handler = on(myElement, 'click', () => console.log('clicked'));\noff(myElement, 'click', handler);"
+        }
+      ]
+    },
+    "on": {
+      "name": "on",
+      "kind": "function",
+      "file": "src/utils/events.ts",
+      "signatures": [
+        "export function on<D = unknown>( target: TargetSelect, eventName: string, handler: McEventHandler<D>, once?: boolean ): McEventHandler<D>;",
+        "export function on( target: TargetSelect, eventName: string, handler: EventListenerOrEventListenerObject, once?: boolean ): EventListenerOrEventListenerObject;",
+        "export function on( target: TargetSelect, eventName: string, handler: EventListenerOrEventListenerObject | McEventHandler<never>, once: boolean = false ) {"
+      ],
+      "description": "Attaches a persistent event listener that will fire every time the specified event occurs.\n\nThis is primarily used to interface with external frameworks or vanilla JS environments.\nFor communication between frontend microcomponents, use the `DC.on()` method instead.\n\nThe handler receives a `CustomEvent<McDetail<D>>`: the payload sits under\n`ev.detail.data`, the bubble-control handle under `ev.detail.control`.",
+      "examples": [
+        {
+          "title": "",
+          "code": "const handler = on<{ value: number }>(myElement, 'update', (ev) => {\nconsole.log(ev.detail.data.value);\n});\noff(myElement, 'update', handler);"
+        }
+      ]
+    },
+    "one": {
+      "name": "one",
+      "kind": "function",
+      "file": "src/utils/events.ts",
+      "signatures": [
+        "export function one<D = unknown>( target: TargetSelect, eventName: string, handler: McEventHandler<D> ): McEventHandler<D>;",
+        "export function one( target: TargetSelect, eventName: string, handler: EventListenerOrEventListenerObject ): EventListenerOrEventListenerObject;",
+        "export function one( target: TargetSelect, eventName: string, handler: EventListenerOrEventListenerObject | McEventHandler<never> ) {"
+      ],
+      "description": "Attaches an event listener that will fire only once.\n\nInternally calls on with the `once` flag set to true. The handler\nis automatically removed after its first invocation.\nThis is primarily used to interface with external frameworks or vanilla JS environments.\nFor communication between frontend microcomponents, use the `DC.one()` method instead.\n\nThe listener fires only once and detaches automatically.",
+      "examples": [
+        {
+          "title": "",
+          "code": "one<{ ready: boolean }>(myElement, 'dataReady', (ev) => console.log('received:', ev.detail.data));"
+        }
+      ]
+    },
+    "trigger": {
+      "name": "trigger",
+      "kind": "function",
+      "file": "src/utils/events.ts",
+      "signatures": [
+        "export function trigger<D = unknown>( target: HTMLElement | string | undefined | null, event: string, data: D = {} as D, bubble: BubbleDirections = 'l', // direction of bubbling controller?: BubbleController ) {"
+      ],
+      "description": "Creates and dispatches a custom event on the specified DOM node.\n\nThe event is namespaced with an `_mc` prefix by default, unless already prefixed.\nSupports bidirectional bubbling (up/down the DOM tree) based on the `bubble` parameter:\n- 'l': local dispatch only\n- 'u': bubble up towards ancestors\n- 'd': bubble down to descendants\n\nThe dispatched event is a `CustomEvent<McDetail<D>>`: handlers find the payload\nunder `ev.detail.data` and can call `ev.detail.control.stop()` to cancel bubbling.\n\nThe first dispatch fires locally only; the second bubbles upward to ancestor components.",
+      "examples": [
+        {
+          "title": "",
+          "code": "trigger(myElement, 'update', { value: 42 }, 'l');\ntrigger(myElement, 'dataReady', { ready: true }, 'u');"
+        }
+      ]
+    },
+    "BubbleController": {
+      "name": "BubbleController",
+      "kind": "class",
+      "file": "src/utils/events.ts",
+      "signatures": [
+        "export class BubbleController implements McBubbleController {"
+      ],
+      "description": "A controller object used to manage and potentially abort event bubbling.\n\nThe `trigger()` function internally creates instance of this class,\nallowing the an eventual handler to call `ev.detail.control.stop()` to\nprevent further propagation in either direction (up/down).\n\nThis is only used internally.",
+      "examples": [
+        {
+          "title": "",
+          "code": "trigger(myElement, 'update', { value: 42 }, 'u');\n\nonUpdate(ev) {\n    ev.detail.control.stop();\n}"
+        }
+      ]
+    },
+    "McBubbleController": {
+      "name": "McBubbleController",
+      "kind": "interface",
+      "file": "src/types/mcTypes.ts",
+      "signatures": [
+        "export interface McBubbleController {"
+      ],
+      "description": "The bubble control handle passed to event handlers; `BubbleController` in events.ts implements it. */"
+    },
+    "BubbleDirection": {
+      "name": "BubbleDirection",
+      "kind": "type alias",
+      "file": "src/types/mcTypes.ts",
+      "signatures": [
+        "export type BubbleDirection = 'l' | 'u' | 'd';"
+      ],
+      "description": "One bubbling direction: `l` local dispatch, `u` up to ancestors, `d` down to descendants. */"
+    },
+    "BubbleDirections": {
+      "name": "BubbleDirections",
+      "kind": "type alias",
+      "file": "src/types/mcTypes.ts",
+      "signatures": [
+        "export type BubbleDirections = | BubbleDirection | `${BubbleDirection}${BubbleDirection}` | `${BubbleDirection}${BubbleDirection}${BubbleDirection}`;"
+      ],
+      "description": "The `bubble` argument of `trigger()`: one to three BubbleDirection letters\ncombined — e.g. `'l'`, `'lu'`, `'lud'` — to dispatch locally and/or propagate up\nand down in one call."
+    },
+    "McDetail": {
+      "name": "McDetail",
+      "kind": "interface",
+      "file": "src/types/mcTypes.ts",
+      "signatures": [
+        "export interface McDetail<D = unknown> {"
+      ],
+      "description": "The `detail` of a microcomponent event: the payload under `data`, the bubble\ncontrol handle under `control`."
+    },
+    "McEventHandler": {
+      "name": "McEventHandler",
+      "kind": "type alias",
+      "file": "src/types/mcTypes.ts",
+      "signatures": [
+        "export type McEventHandler<D = unknown> = (ev: McEvent<D>) => void;"
+      ],
+      "description": "The function `on()` / `one()` accept as an event handler: it receives an\nMcEvent carrying payload `D`."
+    },
+    "McEvent": {
+      "name": "McEvent",
+      "kind": "type alias",
+      "file": "src/types/mcTypes.ts",
+      "signatures": [
+        "export type McEvent<D = unknown> = CustomEvent<McDetail<D>>;"
+      ],
+      "description": "The event object passed to `on()` / `one()` handlers — a `CustomEvent` carrying\npayload `D`. Short for `CustomEvent<McDetail<D>>`.\n\nAnnotate a handler with `McEvent<D>`, or skip the annotation when the event name\nis in the component's event map (`EM` on `DC`) and let it be inferred.\n\n`ev.detail.data.count` is typed `number`; `ev.detail.control.stop()` halts further bubbling.",
+      "examples": [
+        {
+          "title": "",
+          "code": "cart.on('CartUpdate', (ev: McEvent<{ count: number }>) => {\nconsole.log(ev.detail.data.count);\nev.detail.control.stop();\n});"
+        }
+      ]
+    },
+    "McPayloadOf": {
+      "name": "McPayloadOf",
+      "kind": "type alias",
+      "file": "src/types/mcTypes.ts",
+      "signatures": [
+        "export type McPayloadOf<EM, K extends string, D = unknown> = K extends keyof EM ? EM[K] : D;"
+      ],
+      "description": "The payload type of event `K`: its entry in the event map `EM`, or the fallback\n`D` when `K` is not in the map."
+    },
+    "McController": {
+      "name": "McController",
+      "kind": "interface",
+      "file": "src/types/mcTypes.ts",
+      "signatures": [
+        "export interface McController<T extends HTMLElement = HTMLElement> {"
+      ],
+      "description": "The public surface of a DOM microcomponent controller — what `DC` exposes per\ninstance. The registry types reference this instead of the `DC` class so the\nfile stays import-free (`DC implements McController`).\n\n`trigger`'s `bubble` is `string` here, not `BubbleDirections`, because this file\ncannot import from events.ts; `DC` narrows it."
+    },
+    "McNativeEventHandlers": {
+      "name": "McNativeEventHandlers",
+      "kind": "type alias",
+      "file": "src/types/mcTypes.ts",
+      "signatures": [
+        "export type McNativeEventHandlers = {"
+      ],
+      "description": "Opt-in type check for native-event handler methods (`onClick`, `onePointerdown`,\n…). Add it with `implements` and each `on<Event>` / `one<Event>` method is\nchecked against the correct DOM event type; other methods are left alone.\nType-only — nothing exists at runtime.\n\n`onClick` is checked against the native `'click'` event type. Declaring\n`onClick(ev: KeyboardEvent)` instead is a compile error.",
+      "examples": [
+        {
+          "title": "",
+          "code": "class Panel extends DC implements McNativeEventHandlers {\nonClick(ev: MouseEvent) {}\n}"
+        }
+      ]
+    },
+    "McHost": {
+      "name": "McHost",
+      "kind": "type alias",
+      "file": "src/types/mcTypes.ts",
+      "signatures": [
+        "export type McHost< T extends HTMLElement = HTMLElement, R extends Record<string, unknown> = Record<never, never>, > = T & {"
+      ],
+      "description": "A DOM element that hosts microcomponents: the element type `T` plus an `_mc`\nregistry. `R` holds the known entries (`key → element type`); there is no string\nindex, so an unregistered key is a compile error. Chained `add()` calls merge\ntheir entries into `R`.\n\n`withA._mc.a.a` is typed `number`. Accessing `withA._mc.b` is a compile error\nbecause that key was never registered.",
+      "examples": [
+        {
+          "title": "",
+          "code": "const withA = DC.add(form, 'a', { a: 0 });\nconsole.log(withA._mc.a.a);"
+        }
+      ]
+    },
+    "McHostOf": {
+      "name": "McHostOf",
+      "kind": "type alias",
+      "file": "src/types/mcTypes.ts",
+      "signatures": [
+        "export type McHostOf<T extends HTMLElement> = T extends { _mc: McController<infer U> } ? U : T;"
+      ],
+      "description": "The element type behind a target: unwraps `McHost<U, R>` back to `U`, identity\nfor a plain element. Keeps chained `add()` calls from nesting."
+    },
+    "McEntriesOf": {
+      "name": "McEntriesOf",
+      "kind": "type alias",
+      "file": "src/types/mcTypes.ts",
+      "signatures": [
+        "export type McEntriesOf<T> = T extends { _mc: infer M } ? {"
+      ],
+      "description": "The known `_mc` entries of a target as a flat `key → element type` record: the\n`add()` entries with the controller members stripped out, empty for a plain\nelement. This is what lets chained `add()` calls stay flat instead of nesting."
+    },
+    "McMerged": {
+      "name": "McMerged",
+      "kind": "type alias",
+      "file": "src/types/mcTypes.ts",
+      "signatures": [
+        "export type McMerged<A, B> = A & B extends infer U ? { [K in keyof U]: U[K] } : never;"
+      ],
+      "description": "Merges two records into one flat record, so registry entries show as a single object. */"
+    },
+    "McRemoved": {
+      "name": "McRemoved",
+      "kind": "type alias",
+      "file": "src/types/mcTypes.ts",
+      "signatures": [
+        "export type McRemoved<T extends HTMLElement, K extends string> = T extends { _mc: McController } ? { _mc: Record<K, never> } : unknown;"
+      ],
+      "description": "The type `remove()` asserts onto the caller's reference: on an enhanced target the\nremoved key is poisoned to `never` (member access becomes a compile error); a\nplain target is left untouched. A later `add()` re-registers the key cleanly."
+    }
+  },
+  "undocumented": []
+}