Move JSDoc examples to type-checked .examples.ts files

Extract inline code examples from JSDoc comments into companion
`.examples.ts`/`.examples.tsx` files. Examples are now:

- Type-checked by wrapping them in functions
- Referenced via `{@includeCode ./file.examples.ts#regionName}` tags
- Organized using `//#region` and `//#endregion` markers

This keeps the main source files cleaner while ensuring examples
compile correctly. Updated TypeDoc config with `exampleTag: false`
to support title text on `@example` tags.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Jonathan Hefner 2026-01-18 15:11:00 -06:00
commit ad04e89745

View file

@ -0,0 +1,58 @@
/**
* Type-checked examples for {@link PostMessageTransport}.
*
* These examples are included in the API documentation via `@includeCode` tags.
* Each function's region markers define the code snippet that appears in the docs.
*
* @module
*/
import { PostMessageTransport } from "./message-transport.js";
import type { App } from "./app.js";
import type { AppBridge } from "./app-bridge.js";
/**
* Example: Guest UI connecting to parent window.
*/
async function PostMessageTransport_guestUI(app: App) {
//#region PostMessageTransport_guestUI
const transport = new PostMessageTransport(window.parent, window.parent);
await app.connect(transport);
//#endregion PostMessageTransport_guestUI
}
/**
* Example: Host connecting to an iframe.
*/
async function PostMessageTransport_host(bridge: AppBridge) {
//#region PostMessageTransport_host
const iframe = document.getElementById("app-iframe") as HTMLIFrameElement;
const transport = new PostMessageTransport(
iframe.contentWindow!,
iframe.contentWindow!,
);
await bridge.connect(transport);
//#endregion PostMessageTransport_host
}
/**
* Example: Creating transport for guest UI (constructor only).
*/
function PostMessageTransport_constructor_guestUI() {
//#region PostMessageTransport_constructor_guestUI
const transport = new PostMessageTransport(window.parent, window.parent);
//#endregion PostMessageTransport_constructor_guestUI
}
/**
* Example: Creating transport for host (constructor only).
*/
function PostMessageTransport_constructor_host() {
//#region PostMessageTransport_constructor_host
const iframe = document.getElementById("app") as HTMLIFrameElement;
const transport = new PostMessageTransport(
iframe.contentWindow!,
iframe.contentWindow!,
);
//#endregion PostMessageTransport_constructor_host
}