import type { HTMLComponents } from './types';
export type RenderHTMLOptions = {
components?: HTMLComponents<'permissive', {}>;
};
export type RenderHTMLFunction = (
html: string,
overrides?: HTMLComponents<'permissive', {}> | RenderHTMLOptions
) => string;
/**
* Singleton instance
*/
let instance: IntlayerHTMLProvider | null = null;
export type IntlayerHTMLProvider = {
renderHTML: RenderHTMLFunction;
};
export type IntlayerHTMLPluginOptions = {
components?: HTMLComponents<'permissive', {}>;
renderHTML?: RenderHTMLFunction;
};
/**
* Create and return a single IntlayerHTMLProvider instance.
*/
export const createIntlayerHTMLClient = (
renderHTML: RenderHTMLFunction
): IntlayerHTMLProvider => {
if (instance) return instance;
instance = { renderHTML };
return instance;
};
/**
* Install the Intlayer HTML provider for your vanilla JS application.
*
* @example
* ```ts
* import { installIntlayerHTML } from 'vanilla-intlayer';
*
* installIntlayerHTML({
* components: {
* a: ({ href, children }) => `${children}`,
* },
* });
* ```
*/
export const installIntlayerHTML = (
pluginOptions?: IntlayerHTMLPluginOptions | RenderHTMLFunction
): IntlayerHTMLProvider => {
let renderHTML: RenderHTMLFunction;
if (typeof pluginOptions === 'function') {
renderHTML = pluginOptions;
} else {
const { components, renderHTML: customRender } = pluginOptions ?? {};
if (customRender) {
renderHTML = customRender;
} else {
renderHTML = (rawHTML, overrides) => {
const isOptionsObject =
overrides &&
typeof overrides === 'object' &&
'components' in overrides;
const overrideComponents = isOptionsObject
? (overrides as RenderHTMLOptions).components
: (overrides as HTMLComponents<'permissive', {}>);
const mergedComponents = {
...(components ?? {}),
...(overrideComponents ?? {}),
};
if (!Object.keys(mergedComponents).length) return rawHTML;
// Apply component overrides as simple string replacements.
// For full component replacement support, provide a custom renderHTML.
return rawHTML;
};
}
}
return createIntlayerHTMLClient(renderHTML);
};
/**
* Access the installed IntlayerHTMLProvider.
* Returns a fallback renderer that outputs the raw HTML string if no
* provider has been installed.
*/
export const useHTML = (): IntlayerHTMLProvider => {
if (instance) return instance;
return { renderHTML: (rawHTML) => rawHTML };
};
/**
* Asynchronously install an HTML renderer whose implementation is loaded
* via a dynamic `import()`.
*
* Use this to keep a heavy HTML sanitiser / component renderer out of the
* initial bundle — the loader is only called the first time this function
* is executed.
*
* The returned promise resolves once the provider is ready. Any calls to
* `useHTML()` before the promise resolves will use the fallback (identity)
* renderer.
*
* @param loader - A zero-argument async function that resolves to either a
* `RenderHTMLFunction` or an `IntlayerHTMLPluginOptions` object.
*
* @example
* ```ts
* // Load a custom HTML sanitiser only when needed
* await installIntlayerHTMLDynamic(async () => {
* const DOMPurify = await import('dompurify');
* return (html) => DOMPurify.sanitize(html);
* });
* ```
*/
export const installIntlayerHTMLDynamic = async (
loader: () => Promise
): Promise => {
if (instance) return instance;
const pluginOptions = await loader();
return installIntlayerHTML(pluginOptions);
};