/** * Minimal ambient type for the DOM Trusted Types `TrustedHTML` interface. * Not yet part of this project's configured TypeScript DOM lib; declared * here to match the specification's actual (opaque, `toJSON()`-only) shape. * * @see https://developer.mozilla.org/en-US/docs/Web/API/TrustedHTML */ interface TrustedHTML { toJSON: () => string; } /** * Minimal ambient type for the part of the DOM Trusted Types * `TrustedTypePolicyFactory` interface (`globalThis.trustedTypes`) used here. * * @see https://developer.mozilla.org/en-US/docs/Web/API/TrustedTypePolicyFactory/isHTML */ interface TrustedTypePolicyFactory { isHTML: ( value: unknown ) => value is TrustedHTML; /** Empty trusted HTML accepted by HTML sinks without a policy. */ readonly emptyHTML: TrustedHTML; } /** Empty HTML accepted by HTML sinks, including under Trusted Types enforcement. */ export const emptyHTML = ( globalThis as { trustedTypes?: TrustedTypePolicyFactory } ).trustedTypes ?.emptyHTML ?? ''; /** Void and text-only elements on which `data-wp-html` cannot own content. */ export const unsupportedHtmlElements = new Set( [ 'area', 'base', 'basefont', 'bgsound', 'br', 'col', 'embed', 'frame', 'hr', 'img', 'input', 'keygen', 'link', 'meta', 'param', 'source', 'track', 'wbr', 'textarea', 'title', 'script', 'style', 'iframe', 'xmp', 'noembed', 'noframes', ] ); declare const dangerousHTMLBrand: unique symbol; /** * An immutable, opaque token produced by `asDangerousHTML()` that the * `data-wp-html` directive recognizes as trusted HTML. * * The token carries no inspectable trace of the HTML it represents: the * actual value lives in a private `WeakMap` keyed by the token object, not * on the token itself. Cloning the token (structured clone, spreading it * into a new object, `JSON.stringify()`/`parse()`, …) produces a plain * object with none of its own properties, which is not present in that * `WeakMap` and is therefore never treated as trusted. * * The type is nominal: only a value returned by `asDangerousHTML()` is * assignable to it, not a string or any other object. */ export interface DangerousHTML { readonly [ dangerousHTMLBrand ]: 'DangerousHTML'; } // Private: maps each token returned by `asDangerousHTML()` to the HTML value // it represents. Never exported — the token itself is the only way to look // a value up here. const trustedHtmlByToken = new WeakMap< DangerousHTML, string | TrustedHTML >(); /** * Marks a string (or native `TrustedHTML`) as trusted so the `data-wp-html` * directive renders it as markup. Other values empty the bound element, * except pending values and the server's token representation, which keep * its content. * * This function never sanitizes or otherwise processes the HTML passed * here, the same responsibility you take on using `dangerouslySetInnerHTML` * in React. Treating untrusted input as trusted is an XSS risk: never pass * it raw, unescaped user input, and never pass it a `context` value * directly. `context` is for selecting *which* trusted markup to show; the * markup itself should come from `state`, computed by your own code from a * source it trusts. * * The returned token is opaque and identity-based, not content-based: it * carries no inspectable trace of the HTML it wraps. Adding it to * `data-wp-context`, spreading it into a new object, or serializing it as * JSON does not carry the "trusted" marker with it — only a `data-wp-html` * reference that resolves directly to the exact value this function * returned is ever rendered as HTML. * * This package creates no Trusted Types policy of its own. On a site that * enforces Trusted Types, pass a `TrustedHTML` value from the site's own * policy: `asDangerousHTML( policy.createHTML( markup ) )`. A rejected value * empties the element. * * "Trusted" here only means the `data-wp-html` directive will render it and * the Interactivity API won't process directives inside it. It's still live * browser HTML once rendered. Content that isn't safe to render as HTML * isn't made safe by this function. * * @param html Raw HTML string, or a native `TrustedHTML` value from a * site-provided Trusted Types policy, to render. * * @throws {TypeError} If `html` is neither a string nor a native `TrustedHTML` * value. * * @return An opaque token the `data-wp-html` directive recognizes as trusted HTML. * * @example * ```js * import { asDangerousHTML, store } from '@wordpress/interactivity'; * * store( 'myPlugin', { * state: { * get description() { * return asDangerousHTML( * '

A formatted description.

' * ); * }, * }, * } ); * ``` */ export function asDangerousHTML( html: string | TrustedHTML ): DangerousHTML { const { trustedTypes } = globalThis as { trustedTypes?: TrustedTypePolicyFactory; }; if ( typeof html !== 'string' && ! trustedTypes?.isHTML( html ) ) { throw new TypeError( 'asDangerousHTML() expects a string or a native TrustedHTML value.' ); } const token = Object.freeze( Object.create( null ) ) as DangerousHTML; trustedHtmlByToken.set( token, html ); return token; } /** * Checks whether a value was produced by `asDangerousHTML()`. * * @param value Value to check. * * @return Whether the value is a trusted HTML token. */ export function isDangerousHTML( value: unknown ): value is DangerousHTML { return ( typeof value === 'object' && value !== null && trustedHtmlByToken.has( value as DangerousHTML ) ); } /** * Retrieves the HTML value a trusted HTML token represents. * * @param token A token previously returned by `asDangerousHTML()`. * * @return The HTML value the token represents. */ export function getDangerousHTML( token: DangerousHTML ): string | TrustedHTML { return trustedHtmlByToken.get( token )!; }