expose html global jsx attributes to enable extending them for custom…

… elements or api holes

document how to extend jsx attributes and elements

add popover attribute to global jsx attribute interface

fix lint

site/development/themes.md

@@ -103,3 +103,51 @@ export function load(app: Application) {
 ```
 
 [RendererHooks]: https://typedoc.org/api/interfaces/RendererHooks.html
+
+## Registering your own custom elements/attributes
+
+Start by writing a `jsx.d.ts` file somewhere.
+
+````ts
+// src/jsx.d.ts
+import { JSX as TypeDocJSX } from "typedoc";
+
+declare module "typedoc" {
+    namespace JSX {
+        namespace JSX {
+            interface IntrinsicAttributes {
+                popover?: boolean;
+                popovertarget?: string;
+                popovertargetaction?: "hide" | "show" | "toggle";
+            }
+            interface IntrinsicElements {
+                // add your custom elements here, ie:
+                /**
+                 * @example
+                 * ```tsx
+                 * <drop-down trigger="#my-trigger" class="header-menu">
+                 *   <button>Option #1</button>
+                 *   <button>Option #2</button>
+                 * </drop-down>
+                 * ```
+                 */
+                "drop-down": IntrinsicAttributes & {
+                    /**
+                     * A query selector, ie: '#my-trigger'
+                     */
+                    trigger: string;
+                };
+            }
+        }
+    }
+}
+````
+
+Then in your plugin entry point, reference the `jsx.d.ts` file with a triple-slash directive.
+
+```ts
+// src/index.ts
+/// <reference types="./jsx.d.ts" />
+
+export function load(app: Application) { … }
+```

src/lib/utils/jsx.elements.ts

@@ -185,6 +185,19 @@ export interface JsxHtmlGlobalProps {
     tabIndex?: number;
     title?: string;
     translate?: boolean;
+
+    // popover attributes
+    /**
+     * Default: 'auto'. true and 'auto' are equivalent
+     *
+     * See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Popover_API) for more details
+     */
+    popover?: boolean | "auto" | "manual";
+    /**
+     * It must be the popover element id, see [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Popover_API)
+     */
+    popovertarget?: string;
+    popovertargetaction?: "hide" | "show" | "toggle";
 }
 
 /**

src/lib/utils/jsx.ts

@@ -20,6 +20,7 @@ import type {
     JsxElement,
     JsxChildren,
     JsxComponent,
+    JsxHtmlGlobalProps,
 } from "./jsx.elements.js";
 import { JsxFragment } from "./jsx.elements.js";
 
@@ -50,7 +51,11 @@ export function Raw(_props: { html: string }) {
  * @hidden
  */
 export declare namespace JSX {
-    export { IntrinsicElements, JsxElement as Element };
+    export {
+        IntrinsicElements,
+        JsxElement as Element,
+        JsxHtmlGlobalProps as IntrinsicAttributes,
+    };
 }
 
 const voidElements = new Set([