doc: integration guide for external libs

docs/docs/howto/intro.md

@@ -2,7 +2,7 @@
 
 ## Demo
 
-```tsx twoslash
+```jsx twoslash
 // @errors: 2322
 
 function MyComponent({ children }) {
@@ -103,7 +103,7 @@ Configure your `tsconfig.json` as follows:
 
 If you don't have any other JSX runtimes like React or Preact set up, you can use
 `typed-htmx/typed-html`, which will convert JSX into strings at runtime.
-You can configure the runtime using [`jsxConfig`](/typed-htmx/docs/api/module.index/Variables/variable.jsxConfig-1):
+You can configure the runtime using [`jsxConfig`](/typed-htmx/docs/api/index/variables/jsxConfig):
 
 ```js twoslash
 import { jsxConfig } from "typed-htmx";

docs/docs/howto/xternal.md

@@ -0,0 +1,65 @@
+# Augmenting external JSX libraries
+
+typed-htmx is extremely minimal and requires the user to manually augment external JSX libraries that provide their own types.
+
+## Common guidance
+
+- Create a `types.d.ts` (any name is fine, as long as it ends in `.d.ts`) at the top of your src/ folder,
+  or anywhere within the configured `include` of your tsconfig.json
+- Write a JSX element, e.g. `<div />`, and inspect its type
+- If you see React-related types, you are good to go
+- If not, try to discover the common namespace under which all HTML attributes go.
+
+Let's use [Hono](https://hono.dev/top) as an example.
+
+```tsx twoslash
+// @jsxImportSource: hono/jsx
+// In tsconfig.json, jsxImportSource = "hono/jsx"
+
+// The type we are augmenting in this case is `Hono.HTMLAttributes`.
+// hx-boost is not recognized as a proper attribute yet.
+<div hx-boost="bogus" />
+//^?
+```
+
+With this knowledge, we can now augment the type of `Hono.HTMLAttributes` assuming it is an interface:
+
+```tsx twoslash
+// @errors: 2322
+// @jsxImportSource: hono/jsx
+/// <reference types="typed-htmx" />
+
+declare global {
+  namespace Hono {
+    interface HTMLAttributes extends HtmxAttributes {}
+  }
+}
+
+<div hx-boost="bogus"
+     style={{}}
+/>
+```
+
+## Hono
+
+```ts twoslash
+import 'typed-htmx';
+
+declare global {
+  namespace Hono {
+    interface HTMLAttributes extends HtmxAttributes {}
+  }
+}
+```
+
+## Astro
+
+```ts twoslash
+import 'typed-htmx';
+
+declare global {
+  namespace astroHTML.JSX {
+    interface IntrinsicAttributes extends HtmxAttributes {}
+  }
+}
+```

docs/docusaurus.config.js

@@ -21,8 +21,8 @@ const config = {
 	markdown: {
 		format: 'md'
 	},
-	onBrokenLinks: "throw",
-	onBrokenMarkdownLinks: "ignore",
+	onBrokenLinks: "warn",
+	onBrokenMarkdownLinks: "warn",
 
 	i18n: {
 		defaultLocale: "en",
@@ -36,12 +36,10 @@ const config = {
 			({
 				entryPoints: ["../src/index.ts", "../src/jsx.d.ts"],
 				tsconfig: "../tsconfig.json",
-				readme: "none",
 				hideInPageTOC: true,
+				readme: 'none',
 				watch: process.env.npm_lifecycle_event === "start",
-				// cleanOutputDir: process.env.NODE_ENV !== 'production',
-				cleanOutputDir: false,
-				excludeExternals: true,
+				cleanOutputDir: true,
 				externalPattern: ["node_modules/**/*"],
 				plugin: ["typedoc-plugin-mdn-links"],
 			}),
@@ -70,19 +68,17 @@ const config = {
 				defaultOptions: {
 					noErrors: false,
 				},
-				/** @type {import('typescript').CompilerOptions} */
 				defaultCompilerOptions: {
-					types: ["typed-htmx"],
 					jsx: 4, // react-jsx
-					jsxImportSource: "typed-htmx/typed-html",
+					jsxImportSource: 'typed-htmx/typed-html',
 					target: 99, // esnext,
 					strict: true,
+					checkJs: true,
 					noImplicitAny: false,
 					module: 199, // nodenext,
 					moduleResolution: 99, // nodenext
 				},
 				includeJSDocInHover: true,
-				wrapFragments: true,
 				alwayRaiseForTwoslashExceptions: true,
 				disableImplicitReactImport: true,
 			}),

docs/package.json

@@ -21,11 +21,11 @@
 		"clsx": "^1.2.1",
 		"docusaurus-plugin-typedoc": "next",
 		"docusaurus-preset-shiki-twoslash": "^1.1.41",
+		"hono": "^3.11.12",
 		"object-assign": "^4.1.1",
 		"prism-react-renderer": "^1.3.5",
 		"react": "^18.2.0",
 		"react-dom": "^18.2.0",
-		"rehype-raw": "^7.0.0",
 		"typed-htmx": "link:..",
 		"typedoc": "^0.25.6",
 		"typedoc-plugin-markdown": "next",
@@ -34,8 +34,7 @@
 	},
 	"devDependencies": {
 		"@docusaurus/module-type-aliases": "3.0.1",
-		"@docusaurus/types": "^3.0.1",
-		"remark-shiki-twoslash": "^3.1.3"
+		"@docusaurus/types": "^3.0.1"
 	},
 	"browserslist": {
 		"production": [

docs/typedoc.json

@@ -1,3 +1,13 @@
 {
-  "categoryOrder": ["core", "*"]
+  "$schema": "https://typedoc.org/schema.json",
+  "categoryOrder": ["core", "*"],
+  "sourceLinkExternal": true,
+  "excludeExternals": true,
+  "externalPattern": [
+  	"**/node_modules/**/*"
+  ],
+  "readme": "bogus",
+  "searchCategoryBoosts": {
+    "Core": 2
+  }
 }

src/index.ts

@@ -95,6 +95,20 @@ function htmlTransformChildren(value: InterpValue): string {
 	return out.join(" ");
 }
 
+/**
+ * A [tagged template](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#tagged_templates)
+ * that interprets different kinds of {@link InterpValue values} into escaped HTML.
+ * 
+ * ```ts twoslash
+ * import { html } from 'typed-htmx';
+ * function assertEqual(left: any, right: any) {}
+ * // ---cut---
+ * const template = html`
+ *   <div hx-vals=${{ foo: 'bar' }} />
+ * `;
+ * assertEqual(template, `<div hx-vals='{"foo":"bar"}' />`);
+ * ```
+ */
 export const html: HtmlTemplator = (raw, ...values) => {
 	const values_ = values.map(htmlTransformChildren);
 	return String.raw(raw, ...values_);