@knighted/jsx 1.3.2 → 1.4.1

package/README.md

@@ -20,6 +20,7 @@ A runtime JSX template tag backed by the [`oxc-parser`](https://github.com/oxc-p
 - [Node / SSR usage](#node--ssr-usage)
 - [Browser usage](#browser-usage)
 - [TypeScript plugin](docs/ts-plugin.md)
+- [TypeScript guide](docs/typescript.md)
 - [Component testing](docs/testing.md)
 - [CLI setup](docs/cli.md)
 
@@ -206,6 +207,45 @@ This repository ships a ready-to-run fixture under `test/fixtures/node-ssr` that
 
 See how to [integrate with Next.js](./docs/nextjs-integration.md).
 
+## TypeScript integration
+
+The [`@knighted/jsx-ts-plugin`](docs/ts-plugin.md) keeps DOM (`jsx`) and React (`reactJsx`) templates type-safe with a single config block. The plugin maps each helper to the right mode by default, so you can mix DOM nodes and React components in the same file without juggling multiple plugin entries.
+
+```jsonc
+// tsconfig.json
+{
+  "compilerOptions": {
+    "plugins": [
+      {
+        "name": "@knighted/jsx-ts-plugin",
+        "tagModes": {
+          "jsx": "dom",
+          "reactJsx": "react",
+        },
+      },
+    ],
+  },
+}
+```
+
+- Choose **TypeScript: Select TypeScript Version → Use Workspace Version** in VS Code so the plugin loads from `node_modules`.
+- Run `tsc --noEmit` (or your build step) to surface the same diagnostics your editor shows.
+- Set `jsxImportSource` to `@knighted/jsx` when compiling `.tsx` helpers. The package publishes the `@knighted/jsx/jsx-runtime` module TypeScript expects. The runtime export exists solely for diagnostics and will throw if you call it at execution time—switch back to tagged templates before shipping code.
+- Drop `/* @jsx-dom */` or `/* @jsx-react */` immediately before a tagged template when you need a one-off override.
+- Import the `JsxRenderable` helper type from `@knighted/jsx` whenever you annotate DOM-facing utilities without the plugin:
+
+  ```ts
+  import type { JsxRenderable } from '@knighted/jsx'
+
+  const coerceToDom = (value: unknown): JsxRenderable => value ?? ''
+  const view = jsx`<section>${coerceToDom(data)}</section>`
+  ```
+
+> [!TIP]
+> Full `tsconfig` examples (single config or split React + DOM helper projects) live in [docs/typescript.md](docs/typescript.md).
+
+Head over to [docs/ts-plugin.md](docs/ts-plugin.md) for deeper guidance, advanced options, and troubleshooting tips.
+
 ## Browser usage
 
 When you are not using a bundler, load the module directly from a CDN that understands npm packages:

package/dist/cjs/jsx-runtime.cjs

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Fragment = void 0;
+exports.jsx = jsx;
+exports.jsxs = jsxs;
+exports.jsxDEV = jsxDEV;
+const runtimeModuleId = '@knighted/jsx/jsx-runtime';
+const fragmentSymbolDescription = `${runtimeModuleId}::Fragment`;
+const runtimeNotAvailable = () => {
+    throw new Error(`The automatic JSX runtime is only published for TypeScript diagnostics. ` +
+        `Render DOM nodes through the jsx tagged template exported by @knighted/jsx instead.`);
+};
+exports.Fragment = Symbol.for(fragmentSymbolDescription);
+function jsx(_, __, ___) {
+    return runtimeNotAvailable();
+}
+function jsxs(_, __, ___) {
+    return runtimeNotAvailable();
+}
+function jsxDEV(_, __, ___, ____, _____, ______) {
+    return runtimeNotAvailable();
+}

package/dist/cjs/jsx-runtime.d.cts

@@ -0,0 +1,32 @@
+import type { JsxRenderable } from './jsx.cjs';
+export declare const Fragment: unique symbol;
+export declare function jsx(_: unknown, __?: unknown, ___?: unknown): JsxRenderable;
+export declare function jsxs(_: unknown, __?: unknown, ___?: unknown): JsxRenderable;
+export declare function jsxDEV(_: unknown, __?: unknown, ___?: unknown, ____?: boolean, _____?: unknown, ______?: unknown): JsxRenderable;
+type DataAttributes = {
+    [K in `data-${string}`]?: string | number | boolean | null | undefined;
+};
+type AriaAttributes = {
+    [K in `aria-${string}`]?: string | number | boolean | null | undefined;
+};
+type EventHandlers<T extends EventTarget> = {
+    [K in keyof GlobalEventHandlersEventMap as `on${Capitalize<string & K>}`]?: (event: GlobalEventHandlersEventMap[K]) => void;
+};
+type ElementProps<Tag extends keyof HTMLElementTagNameMap> = Omit<Partial<HTMLElementTagNameMap[Tag]>, 'children'> & EventHandlers<HTMLElementTagNameMap[Tag]> & DataAttributes & AriaAttributes & {
+    class?: string;
+    className?: string;
+    style?: string | Record<string, string | number>;
+    ref?: ((value: HTMLElementTagNameMap[Tag]) => void) | {
+        current: HTMLElementTagNameMap[Tag] | null;
+    };
+    children?: JsxRenderable | JsxRenderable[];
+};
+declare global {
+    namespace JSX {
+        type Element = JsxRenderable;
+        type IntrinsicElements = {
+            [Tag in keyof HTMLElementTagNameMap]: ElementProps<Tag>;
+        };
+    }
+}
+export {};

package/dist/jsx-runtime.d.ts

@@ -0,0 +1,32 @@
+import type { JsxRenderable } from './jsx.js';
+export declare const Fragment: unique symbol;
+export declare function jsx(_: unknown, __?: unknown, ___?: unknown): JsxRenderable;
+export declare function jsxs(_: unknown, __?: unknown, ___?: unknown): JsxRenderable;
+export declare function jsxDEV(_: unknown, __?: unknown, ___?: unknown, ____?: boolean, _____?: unknown, ______?: unknown): JsxRenderable;
+type DataAttributes = {
+    [K in `data-${string}`]?: string | number | boolean | null | undefined;
+};
+type AriaAttributes = {
+    [K in `aria-${string}`]?: string | number | boolean | null | undefined;
+};
+type EventHandlers<T extends EventTarget> = {
+    [K in keyof GlobalEventHandlersEventMap as `on${Capitalize<string & K>}`]?: (event: GlobalEventHandlersEventMap[K]) => void;
+};
+type ElementProps<Tag extends keyof HTMLElementTagNameMap> = Omit<Partial<HTMLElementTagNameMap[Tag]>, 'children'> & EventHandlers<HTMLElementTagNameMap[Tag]> & DataAttributes & AriaAttributes & {
+    class?: string;
+    className?: string;
+    style?: string | Record<string, string | number>;
+    ref?: ((value: HTMLElementTagNameMap[Tag]) => void) | {
+        current: HTMLElementTagNameMap[Tag] | null;
+    };
+    children?: JsxRenderable | JsxRenderable[];
+};
+declare global {
+    namespace JSX {
+        type Element = JsxRenderable;
+        type IntrinsicElements = {
+            [Tag in keyof HTMLElementTagNameMap]: ElementProps<Tag>;
+        };
+    }
+}
+export {};

package/dist/jsx-runtime.js

@@ -0,0 +1,16 @@
+const runtimeModuleId = '@knighted/jsx/jsx-runtime';
+const fragmentSymbolDescription = `${runtimeModuleId}::Fragment`;
+const runtimeNotAvailable = () => {
+    throw new Error(`The automatic JSX runtime is only published for TypeScript diagnostics. ` +
+        `Render DOM nodes through the jsx tagged template exported by @knighted/jsx instead.`);
+};
+export const Fragment = Symbol.for(fragmentSymbolDescription);
+export function jsx(_, __, ___) {
+    return runtimeNotAvailable();
+}
+export function jsxs(_, __, ___) {
+    return runtimeNotAvailable();
+}
+export function jsxDEV(_, __, ___, ____, _____, ______) {
+    return runtimeNotAvailable();
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knighted/jsx",
-  "version": "1.3.2",
+  "version": "1.4.1",
   "description": "Runtime JSX tagged template that renders DOM or React trees anywhere without a build step.",
   "keywords": [
     "jsx runtime",
@@ -26,6 +26,16 @@
       "import": "./dist/index.js",
       "default": "./dist/index.js"
     },
+    "./jsx-runtime": {
+      "types": "./dist/jsx-runtime.d.ts",
+      "import": "./dist/jsx-runtime.js",
+      "default": "./dist/jsx-runtime.js"
+    },
+    "./jsx-dev-runtime": {
+      "types": "./dist/jsx-runtime.d.ts",
+      "import": "./dist/jsx-runtime.js",
+      "default": "./dist/jsx-runtime.js"
+    },
     "./lite": {
       "types": "./dist/index.d.ts",
       "import": "./dist/lite/index.js",