@b9g/jsx-web-types — typed JSX intrinsic elements (#60)

[brainkim]

Introduces @b9g/jsx-web-types and wires it into Crank's JSX.IntrinsicElements (#60). Spec-driven, framework-agnostic types for HTML, SVG, and MathML intrinsic elements.

What it is

• A generated .d.ts package: element → attributes/properties, ARIA, microdata/RDFa, global attributes, and a DOM event map. Each attribute carries its MDN description.
• The standard types use native platform names (class, onclick). A separate camelCase variant (@b9g/jsx-web-types/camel-case) re-keys them for React/Inferno (className, htmlFor, …), with names sourced from React's own possibleStandardNames.js.
• Crank's JSX.IntrinsicElements extends WebIntrinsicElements<…>, supplying its own intrinsic attributes (key/ref/prop:/attr:), children attribute, and object-style/class value overrides via the TPropOverrides parameter — so Crank's conventions live in the parameters, not the base types.

Everything is sourced — no hand-coded platform data

Generation is a reproducible function of authoritative sources:

Source	What it provides	How accessed
BCD (@mdn/browser-compat-data)	element names, per-element attributes, global_attributes, deprecated/experimental status, mdn_url	imported JSON
MDN pages	human descriptions + code examples (the hover text)	scraped with cheerio, cached in data/mdn-cache.json (offline-capable; network only on a cache miss)
aria-data	ARIA attributes and their value enums	imported JSON
TypeScript lib.dom.d.ts	tag → DOM interface maps, DOM property types, the *EventMap interfaces	parsed with ts-morph
W3C RDFa Core spec	RDFa attributes	scripts/parse-rdfa-w3c.ts → data/rdfa-attributes.json
MDN Microdata guide	microdata attributes	scripts/parse-microdata-mdn.ts → data/microdata-attributes.json
React possibleStandardNames.js	the camelCase prop-name map (pinned to a release)	scripts/parse-camel-case-names.ts → src/camel-case.generated.d.ts
(hand-written)	only structural constants — the namespace names and the fixed XMLAttributes W3C set	inline in the generator

Every .d.ts and data/*.json is regenerable from these and stamped do-not-edit; there is no hand-frozen platform data.

One known wrinkle: BCD omits fill and systemLanguage from svg.global_attributes despite their families being present. The generator promotes exactly those two (cross-referenced against BCD's per-element data); reported upstream as mdn/browser-compat-data#29912, and the workaround deletes itself once that lands.

Descriptions surface in editors (LSP)

Each attribute's MDN JSDoc reaches hover/completion. The prop types are composed so TypeScript preserves per-attribute doc comments (homomorphic mapped types; multi-namespace tags resolved by precedence rather than unioned), verified end-to-end through Crank JSX with the TypeScript language service — <div class>, <a href>, <label for>, etc. all show their descriptions.

Children

Void elements aren't specially typed: every element accepts children (the runtime ignores stray ones), so there's no void set or TIsVoid plumbing to maintain.

Tests

bun run test typechecks both src/ and the type-level test suite in tests/. Root tsc --noEmit is clean.

🤖 Generated with Claude Code

[brainkim]

This is pretty cool. The design makes me feel like a cat bathing in the sun.

[brainkim]

why though?

[brainkim]

The handler prop derives its event type from lib.dom’s GlobalEventHandlersEventMap, and lib.dom types oninput as the base Event, not InputEvent (long-standing quirk — the runtime fires an InputEvent, but the static type is widened). So a callback annotated (ev: InputEvent) is not assignable to the (ev: Event) => … the prop expects, hence the @ts-expect-error. The test pins that gap so we notice if the generated types ever start narrowing it.