@favish/staffbase-utils 0.3.0 → 0.5.0

package/dist/links.cjs.js

@@ -0,0 +1,2 @@
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});var e=e=>e.startsWith(`/deeplink/`)||e.startsWith(`/openlink/`)?`/${e.slice(10)}`:e,t=(t,n)=>{let r=t?.trim();if(!r||r.startsWith(`#`))return null;let i=r.toLowerCase();if(i.startsWith(`mailto:`)||i.startsWith(`tel:`)||i.startsWith(`sms:`)||i.startsWith(`javascript:`)||i.startsWith(`data:`))return null;try{let t=new URL(n),i=new URL(r,t.toString());if(i.origin===t.origin){let n=e(i.pathname);return new URL(`${n}${i.search}${i.hash}`,t.origin).toString()}return i.toString()}catch{return null}},n=[`youtube.com`,`youtube-nocookie.com`,`youtu.be`,`vimeo.com`,`player.vimeo.com`,`staffbase.com`,`staffbase.rocks`],r=e=>{let t=e.trim();if(!t)return!1;try{let e=typeof window<`u`?window.location.origin:`https://localhost`,r=new URL(t,e);if(r.protocol!==`https:`&&r.protocol!==`http:`)return!1;if(r.origin===e)return!0;let i=r.hostname.toLowerCase();return n.some(e=>i===e||i.endsWith(`.${e}`))}catch{return!1}},i=e=>{let t=e.trim().toLowerCase();return t?!(t.startsWith(`javascript:`)||t.startsWith(`data:`)||t.startsWith(`vbscript:`)):!1},a=(e,t)=>{let n=t?.trim()||``;if(!n)return;let r=Array.from(e.querySelectorAll(`a[href]`));for(let e of r){let t=e.getAttribute(`href`);if(!t)continue;let r=t.trim().toLowerCase();if(!(r.startsWith(`#`)||r.startsWith(`mailto:`)||r.startsWith(`tel:`)||r.startsWith(`sms:`)||r.startsWith(`javascript:`)||r.startsWith(`data:`)))try{let r=new URL(t,n);if(r.origin!==n){e.getAttribute(`target`)===`_blank`&&e.setAttribute(`rel`,`noopener noreferrer`);continue}let i=`${r.pathname}${r.search}${r.hash}`.replace(/^\/deeplink\//,`/`).replace(/^\/openlink\//,`/`);e.setAttribute(`href`,i),e.classList.add(`internal-link`),e.removeAttribute(`target`),e.removeAttribute(`rel`)}catch{}}},o=e=>typeof e==`object`&&!!e&&`then`in e&&typeof e.then==`function`,s=e=>{try{if(typeof window>`u`)return{handled:!1};let t=window?.staffbase?.plugin?.util?.openLink;if(typeof t!=`function`)return{handled:!1};let n=t(e,{}),r;return n&&o(n)&&(r=n),{handled:!0,promise:r}}catch{return{handled:!1}}},c=e=>{if(!e||!i(e))return!1;let t=s(e);if(t.handled){try{let n=typeof window<`u`?window.location.href:void 0,r=setTimeout(()=>{try{let t=typeof window<`u`?window.location.href:void 0,r=typeof document<`u`?document.visibilityState:void 0;n&&t&&n===t&&r===`visible`&&typeof window<`u`&&window.location.assign(e)}catch{}},400);try{t.promise?.then(()=>{clearTimeout(r)}).catch(()=>{})}catch{}}catch{}return!0}try{typeof window<`u`&&window.location.assign(e)}catch{}return!1};exports.getInAppOpenLinkTarget=t,exports.isAllowedIframeSrc=r,exports.isSafeNavigationHref=i,exports.normalizeInAppLinks=a,exports.openStaffbaseAware=c,exports.tryOpenWithStaffbase=s;
+//# sourceMappingURL=links.cjs.js.map

package/dist/links.cjs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"links.cjs.js","names":[],"sources":["../src/links/stripStaffbaseLinkPrefix.ts","../src/links/getInAppOpenLinkTarget.ts","../src/links/isAllowedIframeSrc.ts","../src/links/isSafeNavigationHref.ts","../src/links/normalizeInAppLinks.ts","../src/links/isPromiseLike.ts","../src/links/tryOpenWithStaffbase.ts","../src/links/openStaffbaseAware.ts"],"sourcesContent":["/**\n * Strips a leading Staffbase link prefix (`/deeplink/` or `/openlink/`) from a\n * URL pathname, leaving the canonical in-app path.\n * @param {string} path - The URL pathname.\n * @returns {string} The path without the Staffbase prefix.\n */\nexport const stripStaffbaseLinkPrefix = (path: string): string => {\n  if (path.startsWith('/deeplink/'))\n    return `/${path.slice('/deeplink/'.length)}`\n  if (path.startsWith('/openlink/'))\n    return `/${path.slice('/openlink/'.length)}`\n  return path\n}\n","import { stripStaffbaseLinkPrefix } from './stripStaffbaseLinkPrefix'\n\n/**\n * Returns an absolute URL string that is safe to pass into Staffbase's\n * `openLink()`. We intentionally do NOT require `/openlink/`; if the platform\n * strips it, links can still open in-app by delegating to `openLink()`. Ported\n * from staffbase-alerts (identical to unack).\n * @param {string | null | undefined} href - Raw href as found on an <a> element.\n * @param {string} baseUrl - Base URL used to resolve relative hrefs (usually window.location.origin).\n * @returns {string | null} An absolute URL string, or null if it should not be handled.\n */\nexport const getInAppOpenLinkTarget = (\n  href: string | null | undefined,\n  baseUrl: string,\n): string | null => {\n  const trimmed = href?.trim()\n  if (!trimmed) return null\n\n  // Ignore anchors and non-navigational links.\n  if (trimmed.startsWith('#')) return null\n\n  // Let the browser handle special protocols.\n  const lower = trimmed.toLowerCase()\n  if (\n    lower.startsWith('mailto:') ||\n    lower.startsWith('tel:') ||\n    lower.startsWith('sms:') ||\n    lower.startsWith('javascript:') ||\n    lower.startsWith('data:')\n  ) {\n    return null\n  }\n\n  try {\n    const base = new URL(baseUrl)\n    const url = new URL(trimmed, base.toString())\n\n    // Canonicalize same-origin links by stripping Staffbase prefixes, but keep them absolute.\n    if (url.origin === base.origin) {\n      const cleanedPath = stripStaffbaseLinkPrefix(url.pathname)\n      const absolute = new URL(\n        `${cleanedPath}${url.search}${url.hash}`,\n        base.origin,\n      )\n      return absolute.toString()\n    }\n\n    // For cross-origin absolute URLs, return as-is.\n    return url.toString()\n  } catch {\n    return null\n  }\n}\n","// Hosts allowed to be framed inside sanitized article content. Article HTML is\n// first-party authored in Staffbase, but it renders inside a session-bearing\n// webview, so iframe sources are constrained to known embed providers plus the\n// Staffbase origin rather than allowing arbitrary framing. Promoted from\n// staffbase-alerts.\nconst ALLOWED_IFRAME_HOST_SUFFIXES = [\n  'youtube.com',\n  'youtube-nocookie.com',\n  'youtu.be',\n  'vimeo.com',\n  'player.vimeo.com',\n  'staffbase.com',\n  'staffbase.rocks',\n]\n\n/**\n * Returns true when an iframe src may be rendered. Same-origin sources are\n * always allowed; cross-origin sources must match the embed allowlist. Pair with\n * sanitizeArticleHtml's `isAllowedIframeSrc` option.\n * @param {string} src - The iframe src attribute value.\n * @returns {boolean} True when the iframe may be kept.\n */\nexport const isAllowedIframeSrc = (src: string): boolean => {\n  const trimmed = src.trim()\n  if (!trimmed) return false\n\n  try {\n    const origin =\n      typeof window !== 'undefined'\n        ? window.location.origin\n        : 'https://localhost'\n    const url = new URL(trimmed, origin)\n\n    if (url.protocol !== 'https:' && url.protocol !== 'http:') return false\n    if (url.origin === origin) return true\n\n    const host = url.hostname.toLowerCase()\n    return ALLOWED_IFRAME_HOST_SUFFIXES.some(\n      (suffix) => host === suffix || host.endsWith(`.${suffix}`),\n    )\n  } catch {\n    return false\n  }\n}\n","/**\n * Returns true when an href is safe to pass to a real browser navigation\n * (e.g. `window.location.assign`). Blocks scripted/inline schemes that could\n * execute in the session-bearing webview. Relative URLs and http(s)/mailto/tel\n * are allowed. Promoted from staffbase-alerts.\n * @param {string} href - The href to validate.\n * @returns {boolean} True when the href is safe to navigate to.\n */\nexport const isSafeNavigationHref = (href: string): boolean => {\n  const trimmed = href.trim().toLowerCase()\n  if (!trimmed) return false\n\n  return !(\n    trimmed.startsWith('javascript:') ||\n    trimmed.startsWith('data:') ||\n    trimmed.startsWith('vbscript:')\n  )\n}\n","/**\n * Normalizes links inside Staffbase-rendered HTML so they behave better in mobile\n * apps. On iOS, absolute same-origin links and/or `target=\"_blank\"` can trigger\n * Safari instead of in-app navigation; for same-origin links we rewrite to\n * relative paths and remove target/rel. Ported from staffbase-alerts (the\n * superset): cross-origin `target=\"_blank\"` links are hardened with\n * `rel=\"noopener noreferrer\"` instead of left untouched. The Staffbase origin is\n * passed in (the lib never reads env).\n * @param {HTMLElement} root - The container whose anchors are normalized.\n * @param {string} staffbaseOrigin - The Staffbase origin used to detect same-origin links.\n * @returns {void}\n */\nexport const normalizeInAppLinks = (\n  root: HTMLElement,\n  staffbaseOrigin: string,\n): void => {\n  const origin = staffbaseOrigin?.trim() || ''\n  if (!origin) return\n\n  const anchors = Array.from(root.querySelectorAll('a[href]'))\n\n  for (const anchor of anchors) {\n    const rawHref = anchor.getAttribute('href')\n    if (!rawHref) continue\n\n    // Skip special protocols and anchors.\n    const lower = rawHref.trim().toLowerCase()\n    if (\n      lower.startsWith('#') ||\n      lower.startsWith('mailto:') ||\n      lower.startsWith('tel:') ||\n      lower.startsWith('sms:') ||\n      lower.startsWith('javascript:') ||\n      lower.startsWith('data:')\n    ) {\n      continue\n    }\n\n    try {\n      const url = new URL(rawHref, origin)\n\n      // Only rewrite links that point to the same Staffbase origin.\n      if (url.origin !== origin) {\n        // Harden cross-origin new-tab links against reverse tabnabbing rather\n        // than leaving the authored target/rel untouched.\n        if (anchor.getAttribute('target') === '_blank') {\n          anchor.setAttribute('rel', 'noopener noreferrer')\n        }\n        continue\n      }\n\n      // Convert to a relative URL so the mobile app treats it as in-app navigation.\n      const relative = `${url.pathname}${url.search}${url.hash}`\n      const withoutStaffbasePrefix = relative\n        .replace(/^\\/deeplink\\//, '/')\n        .replace(/^\\/openlink\\//, '/')\n      anchor.setAttribute('href', withoutStaffbasePrefix)\n\n      // Staffbase uses this class in various contexts to mark links as internal.\n      // Adding it here increases the chance that the iOS app routes the navigation in-app.\n      anchor.classList.add('internal-link')\n\n      // Avoid iOS opening Safari for \"new window\" navigation.\n      anchor.removeAttribute('target')\n      anchor.removeAttribute('rel')\n    } catch {\n      // If parsing fails, leave link as-is.\n    }\n  }\n}\n","/**\n * Type guard for Promise-like (thenable) values, used to normalize whatever\n * Staffbase's openLink returns.\n * @param {unknown} value - The value to test.\n * @returns {boolean} True when value has a callable then method.\n */\nexport const isPromiseLike = (value: unknown): value is PromiseLike<unknown> =>\n  value !== null &&\n  typeof value === 'object' &&\n  'then' in value &&\n  typeof (value as PromiseLike<unknown>).then === 'function'\n","import type { TryOpenResult } from '../types/links/TryOpenResult'\nimport type { WindowWithStaffbase } from '../types/links/WindowWithStaffbase'\n\nimport { isPromiseLike } from './isPromiseLike'\n\n/**\n * Attempt to open a link using Staffbase's plugin util.openLink if available.\n * Ported from staffbase-alerts (typed Promise-like guard; smart-search used\n * `as any`).\n * @param {string} href - The target URL to open.\n * @returns {TryOpenResult} Whether Staffbase handled it and a promise if available.\n */\nexport const tryOpenWithStaffbase = (href: string): TryOpenResult => {\n  try {\n    if (typeof window === 'undefined') {\n      return { handled: false }\n    }\n    const w = window as WindowWithStaffbase\n    const open = w?.staffbase?.plugin?.util?.openLink\n    const hasOpenLink = typeof open === 'function'\n    if (!hasOpenLink) return { handled: false }\n    // Pass empty options as the second parameter to align with openLink signature\n    const maybePromise = open(href, {})\n    // If a Promise is returned, normalize it\n    let normalizedPromise: Promise<void> | undefined\n    if (maybePromise && isPromiseLike(maybePromise)) {\n      normalizedPromise = maybePromise as Promise<void>\n    }\n    return { handled: true, promise: normalizedPromise }\n  } catch {\n    return { handled: false }\n  }\n}\n","import { isSafeNavigationHref } from './isSafeNavigationHref'\nimport { tryOpenWithStaffbase } from './tryOpenWithStaffbase'\n\n/**\n * Try to open with Staffbase; if not available, navigate normally in the same\n * tab. Ported from staffbase-alerts (the superset): it guards with\n * isSafeNavigationHref first, so scripted schemes never reach navigation.\n * @param {string} href - The target URL to open.\n * @returns {boolean} True if Staffbase handled the navigation, otherwise false.\n */\nexport const openStaffbaseAware = (href: string): boolean => {\n  if (!href) return false\n\n  // Never navigate to scripted/inline schemes (javascript:, data:, vbscript:),\n  // which would execute in the session-bearing webview.\n  if (!isSafeNavigationHref(href)) return false\n\n  const result = tryOpenWithStaffbase(href)\n  if (result.handled) {\n    // Watchdog: if Staffbase openLink is a no-op, force navigation shortly after\n    try {\n      const beforeHref =\n        typeof window !== 'undefined' ? window.location.href : undefined\n      const timer = setTimeout(() => {\n        try {\n          const afterHref =\n            typeof window !== 'undefined' ? window.location.href : undefined\n          const visibility =\n            typeof document !== 'undefined'\n              ? document.visibilityState\n              : undefined\n          const noChange = beforeHref && afterHref && beforeHref === afterHref\n          const stillVisible = visibility === 'visible'\n          if (noChange && stillVisible && typeof window !== 'undefined') {\n            window.location.assign(href)\n          }\n        } catch {\n          // Ignore watchdog navigation failures.\n        }\n      }, 400)\n      // If the Staffbase promise resolves, cancel the watchdog fallback\n      try {\n        result.promise\n          ?.then(() => {\n            clearTimeout(timer)\n          })\n          .catch(() => {\n            // Keep the watchdog active on rejection.\n          })\n      } catch {\n        // Ignore promise-wiring failures.\n      }\n    } catch {\n      // Ignore watchdog setup failures.\n    }\n    return true\n  }\n  try {\n    if (typeof window !== 'undefined') {\n      window.location.assign(href)\n    }\n  } catch {\n    // Ignore navigation failures.\n  }\n  return false\n}\n"],"mappings":"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"}

package/dist/links.es.mjs

@@ -0,0 +1,98 @@
+//#region src/links/stripStaffbaseLinkPrefix.ts
+var e = (e) => e.startsWith("/deeplink/") || e.startsWith("/openlink/") ? `/${e.slice(10)}` : e, t = (t, n) => {
+	let r = t?.trim();
+	if (!r || r.startsWith("#")) return null;
+	let i = r.toLowerCase();
+	if (i.startsWith("mailto:") || i.startsWith("tel:") || i.startsWith("sms:") || i.startsWith("javascript:") || i.startsWith("data:")) return null;
+	try {
+		let t = new URL(n), i = new URL(r, t.toString());
+		if (i.origin === t.origin) {
+			let n = e(i.pathname);
+			return new URL(`${n}${i.search}${i.hash}`, t.origin).toString();
+		}
+		return i.toString();
+	} catch {
+		return null;
+	}
+}, n = [
+	"youtube.com",
+	"youtube-nocookie.com",
+	"youtu.be",
+	"vimeo.com",
+	"player.vimeo.com",
+	"staffbase.com",
+	"staffbase.rocks"
+], r = (e) => {
+	let t = e.trim();
+	if (!t) return !1;
+	try {
+		let e = typeof window < "u" ? window.location.origin : "https://localhost", r = new URL(t, e);
+		if (r.protocol !== "https:" && r.protocol !== "http:") return !1;
+		if (r.origin === e) return !0;
+		let i = r.hostname.toLowerCase();
+		return n.some((e) => i === e || i.endsWith(`.${e}`));
+	} catch {
+		return !1;
+	}
+}, i = (e) => {
+	let t = e.trim().toLowerCase();
+	return t ? !(t.startsWith("javascript:") || t.startsWith("data:") || t.startsWith("vbscript:")) : !1;
+}, a = (e, t) => {
+	let n = t?.trim() || "";
+	if (!n) return;
+	let r = Array.from(e.querySelectorAll("a[href]"));
+	for (let e of r) {
+		let t = e.getAttribute("href");
+		if (!t) continue;
+		let r = t.trim().toLowerCase();
+		if (!(r.startsWith("#") || r.startsWith("mailto:") || r.startsWith("tel:") || r.startsWith("sms:") || r.startsWith("javascript:") || r.startsWith("data:"))) try {
+			let r = new URL(t, n);
+			if (r.origin !== n) {
+				e.getAttribute("target") === "_blank" && e.setAttribute("rel", "noopener noreferrer");
+				continue;
+			}
+			let i = `${r.pathname}${r.search}${r.hash}`.replace(/^\/deeplink\//, "/").replace(/^\/openlink\//, "/");
+			e.setAttribute("href", i), e.classList.add("internal-link"), e.removeAttribute("target"), e.removeAttribute("rel");
+		} catch {}
+	}
+}, o = (e) => typeof e == "object" && !!e && "then" in e && typeof e.then == "function", s = (e) => {
+	try {
+		if (typeof window > "u") return { handled: !1 };
+		let t = window?.staffbase?.plugin?.util?.openLink;
+		if (typeof t != "function") return { handled: !1 };
+		let n = t(e, {}), r;
+		return n && o(n) && (r = n), {
+			handled: !0,
+			promise: r
+		};
+	} catch {
+		return { handled: !1 };
+	}
+}, c = (e) => {
+	if (!e || !i(e)) return !1;
+	let t = s(e);
+	if (t.handled) {
+		try {
+			let n = typeof window < "u" ? window.location.href : void 0, r = setTimeout(() => {
+				try {
+					let t = typeof window < "u" ? window.location.href : void 0, r = typeof document < "u" ? document.visibilityState : void 0;
+					n && t && n === t && r === "visible" && typeof window < "u" && window.location.assign(e);
+				} catch {}
+			}, 400);
+			try {
+				t.promise?.then(() => {
+					clearTimeout(r);
+				}).catch(() => {});
+			} catch {}
+		} catch {}
+		return !0;
+	}
+	try {
+		typeof window < "u" && window.location.assign(e);
+	} catch {}
+	return !1;
+};
+//#endregion
+export { t as getInAppOpenLinkTarget, r as isAllowedIframeSrc, i as isSafeNavigationHref, a as normalizeInAppLinks, c as openStaffbaseAware, s as tryOpenWithStaffbase };
+
+//# sourceMappingURL=links.es.mjs.map

package/dist/links.es.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"links.es.mjs","names":[],"sources":["../src/links/stripStaffbaseLinkPrefix.ts","../src/links/getInAppOpenLinkTarget.ts","../src/links/isAllowedIframeSrc.ts","../src/links/isSafeNavigationHref.ts","../src/links/normalizeInAppLinks.ts","../src/links/isPromiseLike.ts","../src/links/tryOpenWithStaffbase.ts","../src/links/openStaffbaseAware.ts"],"sourcesContent":["/**\n * Strips a leading Staffbase link prefix (`/deeplink/` or `/openlink/`) from a\n * URL pathname, leaving the canonical in-app path.\n * @param {string} path - The URL pathname.\n * @returns {string} The path without the Staffbase prefix.\n */\nexport const stripStaffbaseLinkPrefix = (path: string): string => {\n  if (path.startsWith('/deeplink/'))\n    return `/${path.slice('/deeplink/'.length)}`\n  if (path.startsWith('/openlink/'))\n    return `/${path.slice('/openlink/'.length)}`\n  return path\n}\n","import { stripStaffbaseLinkPrefix } from './stripStaffbaseLinkPrefix'\n\n/**\n * Returns an absolute URL string that is safe to pass into Staffbase's\n * `openLink()`. We intentionally do NOT require `/openlink/`; if the platform\n * strips it, links can still open in-app by delegating to `openLink()`. Ported\n * from staffbase-alerts (identical to unack).\n * @param {string | null | undefined} href - Raw href as found on an <a> element.\n * @param {string} baseUrl - Base URL used to resolve relative hrefs (usually window.location.origin).\n * @returns {string | null} An absolute URL string, or null if it should not be handled.\n */\nexport const getInAppOpenLinkTarget = (\n  href: string | null | undefined,\n  baseUrl: string,\n): string | null => {\n  const trimmed = href?.trim()\n  if (!trimmed) return null\n\n  // Ignore anchors and non-navigational links.\n  if (trimmed.startsWith('#')) return null\n\n  // Let the browser handle special protocols.\n  const lower = trimmed.toLowerCase()\n  if (\n    lower.startsWith('mailto:') ||\n    lower.startsWith('tel:') ||\n    lower.startsWith('sms:') ||\n    lower.startsWith('javascript:') ||\n    lower.startsWith('data:')\n  ) {\n    return null\n  }\n\n  try {\n    const base = new URL(baseUrl)\n    const url = new URL(trimmed, base.toString())\n\n    // Canonicalize same-origin links by stripping Staffbase prefixes, but keep them absolute.\n    if (url.origin === base.origin) {\n      const cleanedPath = stripStaffbaseLinkPrefix(url.pathname)\n      const absolute = new URL(\n        `${cleanedPath}${url.search}${url.hash}`,\n        base.origin,\n      )\n      return absolute.toString()\n    }\n\n    // For cross-origin absolute URLs, return as-is.\n    return url.toString()\n  } catch {\n    return null\n  }\n}\n","// Hosts allowed to be framed inside sanitized article content. Article HTML is\n// first-party authored in Staffbase, but it renders inside a session-bearing\n// webview, so iframe sources are constrained to known embed providers plus the\n// Staffbase origin rather than allowing arbitrary framing. Promoted from\n// staffbase-alerts.\nconst ALLOWED_IFRAME_HOST_SUFFIXES = [\n  'youtube.com',\n  'youtube-nocookie.com',\n  'youtu.be',\n  'vimeo.com',\n  'player.vimeo.com',\n  'staffbase.com',\n  'staffbase.rocks',\n]\n\n/**\n * Returns true when an iframe src may be rendered. Same-origin sources are\n * always allowed; cross-origin sources must match the embed allowlist. Pair with\n * sanitizeArticleHtml's `isAllowedIframeSrc` option.\n * @param {string} src - The iframe src attribute value.\n * @returns {boolean} True when the iframe may be kept.\n */\nexport const isAllowedIframeSrc = (src: string): boolean => {\n  const trimmed = src.trim()\n  if (!trimmed) return false\n\n  try {\n    const origin =\n      typeof window !== 'undefined'\n        ? window.location.origin\n        : 'https://localhost'\n    const url = new URL(trimmed, origin)\n\n    if (url.protocol !== 'https:' && url.protocol !== 'http:') return false\n    if (url.origin === origin) return true\n\n    const host = url.hostname.toLowerCase()\n    return ALLOWED_IFRAME_HOST_SUFFIXES.some(\n      (suffix) => host === suffix || host.endsWith(`.${suffix}`),\n    )\n  } catch {\n    return false\n  }\n}\n","/**\n * Returns true when an href is safe to pass to a real browser navigation\n * (e.g. `window.location.assign`). Blocks scripted/inline schemes that could\n * execute in the session-bearing webview. Relative URLs and http(s)/mailto/tel\n * are allowed. Promoted from staffbase-alerts.\n * @param {string} href - The href to validate.\n * @returns {boolean} True when the href is safe to navigate to.\n */\nexport const isSafeNavigationHref = (href: string): boolean => {\n  const trimmed = href.trim().toLowerCase()\n  if (!trimmed) return false\n\n  return !(\n    trimmed.startsWith('javascript:') ||\n    trimmed.startsWith('data:') ||\n    trimmed.startsWith('vbscript:')\n  )\n}\n","/**\n * Normalizes links inside Staffbase-rendered HTML so they behave better in mobile\n * apps. On iOS, absolute same-origin links and/or `target=\"_blank\"` can trigger\n * Safari instead of in-app navigation; for same-origin links we rewrite to\n * relative paths and remove target/rel. Ported from staffbase-alerts (the\n * superset): cross-origin `target=\"_blank\"` links are hardened with\n * `rel=\"noopener noreferrer\"` instead of left untouched. The Staffbase origin is\n * passed in (the lib never reads env).\n * @param {HTMLElement} root - The container whose anchors are normalized.\n * @param {string} staffbaseOrigin - The Staffbase origin used to detect same-origin links.\n * @returns {void}\n */\nexport const normalizeInAppLinks = (\n  root: HTMLElement,\n  staffbaseOrigin: string,\n): void => {\n  const origin = staffbaseOrigin?.trim() || ''\n  if (!origin) return\n\n  const anchors = Array.from(root.querySelectorAll('a[href]'))\n\n  for (const anchor of anchors) {\n    const rawHref = anchor.getAttribute('href')\n    if (!rawHref) continue\n\n    // Skip special protocols and anchors.\n    const lower = rawHref.trim().toLowerCase()\n    if (\n      lower.startsWith('#') ||\n      lower.startsWith('mailto:') ||\n      lower.startsWith('tel:') ||\n      lower.startsWith('sms:') ||\n      lower.startsWith('javascript:') ||\n      lower.startsWith('data:')\n    ) {\n      continue\n    }\n\n    try {\n      const url = new URL(rawHref, origin)\n\n      // Only rewrite links that point to the same Staffbase origin.\n      if (url.origin !== origin) {\n        // Harden cross-origin new-tab links against reverse tabnabbing rather\n        // than leaving the authored target/rel untouched.\n        if (anchor.getAttribute('target') === '_blank') {\n          anchor.setAttribute('rel', 'noopener noreferrer')\n        }\n        continue\n      }\n\n      // Convert to a relative URL so the mobile app treats it as in-app navigation.\n      const relative = `${url.pathname}${url.search}${url.hash}`\n      const withoutStaffbasePrefix = relative\n        .replace(/^\\/deeplink\\//, '/')\n        .replace(/^\\/openlink\\//, '/')\n      anchor.setAttribute('href', withoutStaffbasePrefix)\n\n      // Staffbase uses this class in various contexts to mark links as internal.\n      // Adding it here increases the chance that the iOS app routes the navigation in-app.\n      anchor.classList.add('internal-link')\n\n      // Avoid iOS opening Safari for \"new window\" navigation.\n      anchor.removeAttribute('target')\n      anchor.removeAttribute('rel')\n    } catch {\n      // If parsing fails, leave link as-is.\n    }\n  }\n}\n","/**\n * Type guard for Promise-like (thenable) values, used to normalize whatever\n * Staffbase's openLink returns.\n * @param {unknown} value - The value to test.\n * @returns {boolean} True when value has a callable then method.\n */\nexport const isPromiseLike = (value: unknown): value is PromiseLike<unknown> =>\n  value !== null &&\n  typeof value === 'object' &&\n  'then' in value &&\n  typeof (value as PromiseLike<unknown>).then === 'function'\n","import type { TryOpenResult } from '../types/links/TryOpenResult'\nimport type { WindowWithStaffbase } from '../types/links/WindowWithStaffbase'\n\nimport { isPromiseLike } from './isPromiseLike'\n\n/**\n * Attempt to open a link using Staffbase's plugin util.openLink if available.\n * Ported from staffbase-alerts (typed Promise-like guard; smart-search used\n * `as any`).\n * @param {string} href - The target URL to open.\n * @returns {TryOpenResult} Whether Staffbase handled it and a promise if available.\n */\nexport const tryOpenWithStaffbase = (href: string): TryOpenResult => {\n  try {\n    if (typeof window === 'undefined') {\n      return { handled: false }\n    }\n    const w = window as WindowWithStaffbase\n    const open = w?.staffbase?.plugin?.util?.openLink\n    const hasOpenLink = typeof open === 'function'\n    if (!hasOpenLink) return { handled: false }\n    // Pass empty options as the second parameter to align with openLink signature\n    const maybePromise = open(href, {})\n    // If a Promise is returned, normalize it\n    let normalizedPromise: Promise<void> | undefined\n    if (maybePromise && isPromiseLike(maybePromise)) {\n      normalizedPromise = maybePromise as Promise<void>\n    }\n    return { handled: true, promise: normalizedPromise }\n  } catch {\n    return { handled: false }\n  }\n}\n","import { isSafeNavigationHref } from './isSafeNavigationHref'\nimport { tryOpenWithStaffbase } from './tryOpenWithStaffbase'\n\n/**\n * Try to open with Staffbase; if not available, navigate normally in the same\n * tab. Ported from staffbase-alerts (the superset): it guards with\n * isSafeNavigationHref first, so scripted schemes never reach navigation.\n * @param {string} href - The target URL to open.\n * @returns {boolean} True if Staffbase handled the navigation, otherwise false.\n */\nexport const openStaffbaseAware = (href: string): boolean => {\n  if (!href) return false\n\n  // Never navigate to scripted/inline schemes (javascript:, data:, vbscript:),\n  // which would execute in the session-bearing webview.\n  if (!isSafeNavigationHref(href)) return false\n\n  const result = tryOpenWithStaffbase(href)\n  if (result.handled) {\n    // Watchdog: if Staffbase openLink is a no-op, force navigation shortly after\n    try {\n      const beforeHref =\n        typeof window !== 'undefined' ? window.location.href : undefined\n      const timer = setTimeout(() => {\n        try {\n          const afterHref =\n            typeof window !== 'undefined' ? window.location.href : undefined\n          const visibility =\n            typeof document !== 'undefined'\n              ? document.visibilityState\n              : undefined\n          const noChange = beforeHref && afterHref && beforeHref === afterHref\n          const stillVisible = visibility === 'visible'\n          if (noChange && stillVisible && typeof window !== 'undefined') {\n            window.location.assign(href)\n          }\n        } catch {\n          // Ignore watchdog navigation failures.\n        }\n      }, 400)\n      // If the Staffbase promise resolves, cancel the watchdog fallback\n      try {\n        result.promise\n          ?.then(() => {\n            clearTimeout(timer)\n          })\n          .catch(() => {\n            // Keep the watchdog active on rejection.\n          })\n      } catch {\n        // Ignore promise-wiring failures.\n      }\n    } catch {\n      // Ignore watchdog setup failures.\n    }\n    return true\n  }\n  try {\n    if (typeof window !== 'undefined') {\n      window.location.assign(href)\n    }\n  } catch {\n    // Ignore navigation failures.\n  }\n  return false\n}\n"],"mappings":"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"}

package/dist/renderWidgets-CeIczubt.mjs

@@ -0,0 +1,81 @@
+//#region src/widgets/defaultWidgetOnError.ts
+var e = (e, t) => {
+	t === "manager-unavailable" && console.warn("[staffbase-utils] Staffbase widget manager unavailable; embedded widgets were not rendered.", e);
+}, t = () => {
+	if (typeof window > "u") return null;
+	let e = window.staffbase?.content?.widgetMgr;
+	return typeof e == "function" ? e : null;
+}, n = () => typeof window > "u" ? null : window.staffbase?.content?.widgetMgr?.prototype ?? null, r = (e) => typeof e._extractWidgets == "function" && typeof e._renderWidget == "function", i = (e) => e instanceof TypeError && (e.message?.includes("each") || e.message?.includes("undefined is not an object")), a = Promise.resolve(), o = /* @__PURE__ */ new WeakMap(), s = !1, c = async (e, a, c, l, u, d) => {
+	let f = 0, p = !1;
+	for (; f < l;) {
+		if (f++, o.get(a) !== c) return {
+			ok: !1,
+			reason: "cancelled"
+		};
+		if (typeof e.querySelectorAll != "function") return {
+			ok: !1,
+			reason: "no-container"
+		};
+		let s = t();
+		if (s) {
+			p = !0;
+			try {
+				let t = new s(void 0, !1);
+				if (typeof t.render == "function") return await t.render(e), {
+					ok: !0,
+					rendered: 0
+				};
+			} catch {}
+		}
+		let m = n();
+		if (m && r(m)) {
+			p = !0, Array.isArray(m._widgets) || (m._widgets = []);
+			let t;
+			try {
+				t = m._extractWidgets(e);
+			} catch (e) {
+				d(e, "extract"), t = [];
+			}
+			if (t.length > 0) {
+				let n = 0;
+				for (let r of t) {
+					if (o.get(a) !== c) return {
+						ok: !1,
+						reason: "cancelled"
+					};
+					try {
+						m._renderWidget.call(m, e, r), n++;
+					} catch (e) {
+						i(e) || d(e, "render-widget");
+					}
+				}
+				return {
+					ok: !0,
+					rendered: n
+				};
+			}
+		}
+		if (f >= l) break;
+		await new Promise((e) => setTimeout(e, u));
+	}
+	return p ? {
+		ok: !1,
+		reason: "no-widgets"
+	} : (s || (s = !0, d(/* @__PURE__ */ Error("Staffbase widget manager unavailable after retries."), "manager-unavailable")), {
+		ok: !1,
+		reason: "manager-unavailable"
+	});
+}, l = (t, n = {}) => {
+	if (!t) return Promise.resolve({
+		ok: !1,
+		reason: "no-container"
+	});
+	let { maxRetries: r = 10, retryDelay: i = 300, onError: s = e, cancelKey: l = t } = n, u = (o.get(l) ?? 0) + 1;
+	o.set(l, u);
+	let d = a.then(() => c(t, l, u, r, i, s));
+	return a = d.then(() => void 0, () => void 0), d;
+};
+//#endregion
+export { l as t };
+
+//# sourceMappingURL=renderWidgets-CeIczubt.mjs.map

package/dist/renderWidgets-CeIczubt.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"renderWidgets-CeIczubt.mjs","names":[],"sources":["../src/widgets/defaultWidgetOnError.ts","../src/widgets/getWidgetManagerConstructor.ts","../src/widgets/getWidgetManagerPrototype.ts","../src/widgets/hasRequiredWidgetManagerMethods.ts","../src/widgets/isKnownStaffbaseRenderError.ts","../src/widgets/renderWidgets.ts"],"sourcesContent":["/**\n * Default onError for renderWidgets: warns only on the critical\n * 'manager-unavailable' context so a platform regression stays visible in logs\n * without spamming per-widget noise. Consumers can pass their own onError.\n * @param {unknown} error - The swallowed error.\n * @param {string} context - Where it happened.\n * @returns {void}\n */\nexport const defaultWidgetOnError = (error: unknown, context: string): void => {\n  if (context === 'manager-unavailable') {\n    console.warn(\n      '[staffbase-utils] Staffbase widget manager unavailable; embedded widgets were not rendered.',\n      error,\n    )\n  }\n}\n","import type { StaffbaseWidgetManagerConstructor } from '../types/widgets/StaffbaseWidgetManagerConstructor'\n\n/**\n * Resolves the host widget-manager constructor from the global Staffbase object,\n * or null when it is not a function (older runtimes / platform regression).\n * @returns {StaffbaseWidgetManagerConstructor | null} The constructor or null.\n */\nexport const getWidgetManagerConstructor =\n  (): StaffbaseWidgetManagerConstructor | null => {\n    if (typeof window === 'undefined') return null\n    const ctor = (\n      window as unknown as {\n        staffbase?: { content?: { widgetMgr?: unknown } }\n      }\n    ).staffbase?.content?.widgetMgr\n    return typeof ctor === 'function'\n      ? (ctor as StaffbaseWidgetManagerConstructor)\n      : null\n  }\n","import type { StaffbaseWidgetManagerPrototype } from '../types/widgets/StaffbaseWidgetManagerPrototype'\n\n/**\n * Resolves the host widget-manager prototype (the private fallback API) from the\n * global Staffbase object, or null when it is unavailable.\n * @returns {StaffbaseWidgetManagerPrototype | null} The prototype or null.\n */\nexport const getWidgetManagerPrototype =\n  (): StaffbaseWidgetManagerPrototype | null => {\n    if (typeof window === 'undefined') return null\n    const proto = (\n      window as unknown as {\n        staffbase?: {\n          content?: {\n            widgetMgr?: { prototype?: StaffbaseWidgetManagerPrototype }\n          }\n        }\n      }\n    ).staffbase?.content?.widgetMgr?.prototype\n    return proto ?? null\n  }\n","import type { StaffbaseWidgetManagerPrototype } from '../types/widgets/StaffbaseWidgetManagerPrototype'\n\n/**\n * Type guard asserting the widget-manager prototype exposes the methods the\n * prototype render path needs.\n * @param {StaffbaseWidgetManagerPrototype} widgetMgr - The resolved prototype.\n * @returns {boolean} True when both _extractWidgets and _renderWidget are functions.\n */\nexport const hasRequiredWidgetManagerMethods = (\n  widgetMgr: StaffbaseWidgetManagerPrototype,\n): widgetMgr is StaffbaseWidgetManagerPrototype & {\n  _extractWidgets: (container: HTMLElement) => unknown[]\n  _renderWidget: (\n    this: StaffbaseWidgetManagerPrototype,\n    container: HTMLElement,\n    widget: unknown,\n  ) => void\n} =>\n  typeof widgetMgr._extractWidgets === 'function' &&\n  typeof widgetMgr._renderWidget === 'function'\n","/**\n * Detects known, benign internal Staffbase errors thrown by `_renderWidget` for\n * individual widgets, so they can be swallowed without aborting the batch.\n * Promoted from unacknowledged-bulletins (`each` / `undefined is not an object`).\n * @param {unknown} error - The thrown value.\n * @returns {boolean} True when the error is a known internal render error.\n */\nexport const isKnownStaffbaseRenderError = (error: unknown): boolean =>\n  error instanceof TypeError &&\n  (error.message?.includes('each') ||\n    error.message?.includes('undefined is not an object'))\n","import type { RenderWidgetsOptions } from '../types/widgets/RenderWidgetsOptions'\nimport type { RenderWidgetsResult } from '../types/widgets/RenderWidgetsResult'\n\nimport { defaultWidgetOnError } from './defaultWidgetOnError'\nimport { getWidgetManagerConstructor } from './getWidgetManagerConstructor'\nimport { getWidgetManagerPrototype } from './getWidgetManagerPrototype'\nimport { hasRequiredWidgetManagerMethods } from './hasRequiredWidgetManagerMethods'\nimport { isKnownStaffbaseRenderError } from './isKnownStaffbaseRenderError'\n\n// Global serialization chain: all renders run one at a time so they never race\n// on the host's shared `_widgets` array (unacknowledged-bulletins' lock, made\n// queue-based). Per-cancelKey run ids drop superseded renders (alerts' WeakMap\n// cancellation; no AbortController, for old webviews). warn-once keeps a missing\n// manager observable without spam (alerts).\nlet queue: Promise<unknown> = Promise.resolve()\nconst cancelTokens = new WeakMap<object, number>()\nlet hasWarnedManagerUnavailable = false\n\n/**\n * Runs the retry loop for a single render: constructor path first, prototype\n * fallback, with cancellation checks and known-error swallowing.\n * @param {HTMLElement} container - The container to render widgets into.\n * @param {object} cancelKey - The cancellation key for this render.\n * @param {number} runId - This render's run id for the cancel key.\n * @param {number} maxRetries - Maximum render attempts.\n * @param {number} retryDelay - Delay between attempts, in milliseconds.\n * @param {(error: unknown, context: string) => void} onError - Error reporter.\n * @returns {Promise<RenderWidgetsResult>} The typed render result.\n */\nconst executeRender = async (\n  container: HTMLElement,\n  cancelKey: object,\n  runId: number,\n  maxRetries: number,\n  retryDelay: number,\n  onError: (error: unknown, context: string) => void,\n): Promise<RenderWidgetsResult> => {\n  let attempts = 0\n  let managerSeen = false\n\n  while (attempts < maxRetries) {\n    attempts++\n    if (cancelTokens.get(cancelKey) !== runId)\n      return { ok: false, reason: 'cancelled' }\n    if (typeof container.querySelectorAll !== 'function') {\n      return { ok: false, reason: 'no-container' }\n    }\n\n    // Prefer Staffbase's real widget manager (closest to host behavior).\n    const ctor = getWidgetManagerConstructor()\n    if (ctor) {\n      managerSeen = true\n      try {\n        const instance = new ctor(undefined, false)\n        if (typeof instance.render === 'function') {\n          await instance.render(container)\n          return { ok: true, rendered: 0 }\n        }\n      } catch {\n        // Fall back to the private prototype path below.\n      }\n    }\n\n    const proto = getWidgetManagerPrototype()\n    if (proto && hasRequiredWidgetManagerMethods(proto)) {\n      managerSeen = true\n      if (!Array.isArray(proto._widgets)) proto._widgets = []\n\n      let widgets: unknown[]\n      try {\n        widgets = proto._extractWidgets(container)\n      } catch (error) {\n        onError(error, 'extract')\n        widgets = []\n      }\n\n      if (widgets.length > 0) {\n        let rendered = 0\n        for (const widget of widgets) {\n          if (cancelTokens.get(cancelKey) !== runId) {\n            return { ok: false, reason: 'cancelled' }\n          }\n          try {\n            proto._renderWidget.call(proto, container, widget)\n            rendered++\n          } catch (error) {\n            if (!isKnownStaffbaseRenderError(error))\n              onError(error, 'render-widget')\n          }\n        }\n        return { ok: true, rendered }\n      }\n    }\n\n    if (attempts >= maxRetries) break\n    await new Promise((resolve) => setTimeout(resolve, retryDelay))\n  }\n\n  if (!managerSeen) {\n    if (!hasWarnedManagerUnavailable) {\n      hasWarnedManagerUnavailable = true\n      onError(\n        new Error('Staffbase widget manager unavailable after retries.'),\n        'manager-unavailable',\n      )\n    }\n    return { ok: false, reason: 'manager-unavailable' }\n  }\n  return { ok: false, reason: 'no-widgets' }\n}\n\n/**\n * Renders the widgets embedded in `container` using the host's private widget\n * manager. Superset of the four widget services: constructor path first with a\n * prototype fallback, a global queue that serializes renders, per-cancelKey\n * cancellation of superseded renders, configurable retries, swallowing of known\n * internal Staffbase errors, and a once-per-session warning when the manager is\n * missing. Returns a typed result so callers can react (e.g. mark a\n * data-widget-render-error attribute).\n * @param {HTMLElement | null} container - The element whose embedded widgets are rendered.\n * @param {RenderWidgetsOptions} options - Retry, error and cancellation options.\n * @returns {Promise<RenderWidgetsResult>} The typed render result.\n */\nexport const renderWidgets = (\n  container: HTMLElement | null,\n  options: RenderWidgetsOptions = {},\n): Promise<RenderWidgetsResult> => {\n  if (!container) return Promise.resolve({ ok: false, reason: 'no-container' })\n\n  const {\n    maxRetries = 10,\n    retryDelay = 300,\n    onError = defaultWidgetOnError,\n    cancelKey = container,\n  } = options\n\n  // Bump the run id synchronously so any older in-flight/queued render for the\n  // same key sees itself as superseded.\n  const runId = (cancelTokens.get(cancelKey) ?? 0) + 1\n  cancelTokens.set(cancelKey, runId)\n\n  const run = queue.then(() =>\n    executeRender(container, cancelKey, runId, maxRetries, retryDelay, onError),\n  )\n  // Keep the queue chain alive regardless of individual outcomes.\n  queue = run.then(\n    () => undefined,\n    () => undefined,\n  )\n  return run\n}\n"],"mappings":";AAQA,IAAa,KAAwB,GAAgB,MAA0B;CAC7E,AAAI,MAAY,yBACd,QAAQ,KACN,+FACA,CACF;AAEJ,GCRa,UACqC;CAC9C,IAAI,OAAO,SAAW,KAAa,OAAO;CAC1C,IAAM,IACJ,OAGA,WAAW,SAAS;CACtB,OAAO,OAAO,KAAS,aAClB,IACD;AACN,GCXW,UAEL,OAAO,SAAW,MAAoB,OAExC,OAOA,WAAW,SAAS,WAAW,aACjB,MCXP,KACX,MASA,OAAO,EAAU,mBAAoB,cACrC,OAAO,EAAU,iBAAkB,YCZxB,KAA+B,MAC1C,aAAiB,cAChB,EAAM,SAAS,SAAS,MAAM,KAC7B,EAAM,SAAS,SAAS,4BAA4B,ICIpD,IAA0B,QAAQ,QAAQ,GACxC,oBAAe,IAAI,QAAwB,GAC7C,IAA8B,IAa5B,IAAgB,OACpB,GACA,GACA,GACA,GACA,GACA,MACiC;CACjC,IAAI,IAAW,GACX,IAAc;CAElB,OAAO,IAAW,IAAY;EAE5B,IADA,KACI,EAAa,IAAI,CAAS,MAAM,GAClC,OAAO;GAAE,IAAI;GAAO,QAAQ;EAAY;EAC1C,IAAI,OAAO,EAAU,oBAAqB,YACxC,OAAO;GAAE,IAAI;GAAO,QAAQ;EAAe;EAI7C,IAAM,IAAO,EAA4B;EACzC,IAAI,GAAM;GACR,IAAc;GACd,IAAI;IACF,IAAM,IAAW,IAAI,EAAK,KAAA,GAAW,EAAK;IAC1C,IAAI,OAAO,EAAS,UAAW,YAE7B,OADA,MAAM,EAAS,OAAO,CAAS,GACxB;KAAE,IAAI;KAAM,UAAU;IAAE;GAEnC,QAAQ,CAER;EACF;EAEA,IAAM,IAAQ,EAA0B;EACxC,IAAI,KAAS,EAAgC,CAAK,GAAG;GAEnD,AADA,IAAc,IACT,MAAM,QAAQ,EAAM,QAAQ,MAAG,EAAM,WAAW,CAAC;GAEtD,IAAI;GACJ,IAAI;IACF,IAAU,EAAM,gBAAgB,CAAS;GAC3C,SAAS,GAAO;IAEd,AADA,EAAQ,GAAO,SAAS,GACxB,IAAU,CAAC;GACb;GAEA,IAAI,EAAQ,SAAS,GAAG;IACtB,IAAI,IAAW;IACf,KAAK,IAAM,KAAU,GAAS;KAC5B,IAAI,EAAa,IAAI,CAAS,MAAM,GAClC,OAAO;MAAE,IAAI;MAAO,QAAQ;KAAY;KAE1C,IAAI;MAEF,AADA,EAAM,cAAc,KAAK,GAAO,GAAW,CAAM,GACjD;KACF,SAAS,GAAO;MACd,AAAK,EAA4B,CAAK,KACpC,EAAQ,GAAO,eAAe;KAClC;IACF;IACA,OAAO;KAAE,IAAI;KAAM;IAAS;GAC9B;EACF;EAEA,IAAI,KAAY,GAAY;EAC5B,MAAM,IAAI,SAAS,MAAY,WAAW,GAAS,CAAU,CAAC;CAChE;CAYA,OAVK,IAUE;EAAE,IAAI;EAAO,QAAQ;CAAa,KATlC,MACH,IAA8B,IAC9B,EACE,gBAAI,MAAM,qDAAqD,GAC/D,qBACF,IAEK;EAAE,IAAI;EAAO,QAAQ;CAAsB;AAGtD,GAca,KACX,GACA,IAAgC,CAAC,MACA;CACjC,IAAI,CAAC,GAAW,OAAO,QAAQ,QAAQ;EAAE,IAAI;EAAO,QAAQ;CAAe,CAAC;CAE5E,IAAM,EACJ,gBAAa,IACb,gBAAa,KACb,aAAU,GACV,eAAY,MACV,GAIE,KAAS,EAAa,IAAI,CAAS,KAAK,KAAK;CACnD,EAAa,IAAI,GAAW,CAAK;CAEjC,IAAM,IAAM,EAAM,WAChB,EAAc,GAAW,GAAW,GAAO,GAAY,GAAY,CAAO,CAC5E;CAMA,OAJA,IAAQ,EAAI,WACJ,KAAA,SACA,KAAA,CACR,GACO;AACT"}

package/dist/renderWidgets-EbJq9Wn6.js

@@ -0,0 +1,2 @@
+var e=(e,t)=>{t===`manager-unavailable`&&console.warn(`[staffbase-utils] Staffbase widget manager unavailable; embedded widgets were not rendered.`,e)},t=()=>{if(typeof window>`u`)return null;let e=window.staffbase?.content?.widgetMgr;return typeof e==`function`?e:null},n=()=>typeof window>`u`?null:window.staffbase?.content?.widgetMgr?.prototype??null,r=e=>typeof e._extractWidgets==`function`&&typeof e._renderWidget==`function`,i=e=>e instanceof TypeError&&(e.message?.includes(`each`)||e.message?.includes(`undefined is not an object`)),a=Promise.resolve(),o=new WeakMap,s=!1,c=async(e,a,c,l,u,d)=>{let f=0,p=!1;for(;f<l;){if(f++,o.get(a)!==c)return{ok:!1,reason:`cancelled`};if(typeof e.querySelectorAll!=`function`)return{ok:!1,reason:`no-container`};let s=t();if(s){p=!0;try{let t=new s(void 0,!1);if(typeof t.render==`function`)return await t.render(e),{ok:!0,rendered:0}}catch{}}let m=n();if(m&&r(m)){p=!0,Array.isArray(m._widgets)||(m._widgets=[]);let t;try{t=m._extractWidgets(e)}catch(e){d(e,`extract`),t=[]}if(t.length>0){let n=0;for(let r of t){if(o.get(a)!==c)return{ok:!1,reason:`cancelled`};try{m._renderWidget.call(m,e,r),n++}catch(e){i(e)||d(e,`render-widget`)}}return{ok:!0,rendered:n}}}if(f>=l)break;await new Promise(e=>setTimeout(e,u))}return p?{ok:!1,reason:`no-widgets`}:(s||(s=!0,d(Error(`Staffbase widget manager unavailable after retries.`),`manager-unavailable`)),{ok:!1,reason:`manager-unavailable`})},l=(t,n={})=>{if(!t)return Promise.resolve({ok:!1,reason:`no-container`});let{maxRetries:r=10,retryDelay:i=300,onError:s=e,cancelKey:l=t}=n,u=(o.get(l)??0)+1;o.set(l,u);let d=a.then(()=>c(t,l,u,r,i,s));return a=d.then(()=>void 0,()=>void 0),d};Object.defineProperty(exports,"t",{enumerable:!0,get:function(){return l}});
+//# sourceMappingURL=renderWidgets-EbJq9Wn6.js.map

package/dist/renderWidgets-EbJq9Wn6.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"renderWidgets-EbJq9Wn6.js","names":[],"sources":["../src/widgets/defaultWidgetOnError.ts","../src/widgets/getWidgetManagerConstructor.ts","../src/widgets/getWidgetManagerPrototype.ts","../src/widgets/hasRequiredWidgetManagerMethods.ts","../src/widgets/isKnownStaffbaseRenderError.ts","../src/widgets/renderWidgets.ts"],"sourcesContent":["/**\n * Default onError for renderWidgets: warns only on the critical\n * 'manager-unavailable' context so a platform regression stays visible in logs\n * without spamming per-widget noise. Consumers can pass their own onError.\n * @param {unknown} error - The swallowed error.\n * @param {string} context - Where it happened.\n * @returns {void}\n */\nexport const defaultWidgetOnError = (error: unknown, context: string): void => {\n  if (context === 'manager-unavailable') {\n    console.warn(\n      '[staffbase-utils] Staffbase widget manager unavailable; embedded widgets were not rendered.',\n      error,\n    )\n  }\n}\n","import type { StaffbaseWidgetManagerConstructor } from '../types/widgets/StaffbaseWidgetManagerConstructor'\n\n/**\n * Resolves the host widget-manager constructor from the global Staffbase object,\n * or null when it is not a function (older runtimes / platform regression).\n * @returns {StaffbaseWidgetManagerConstructor | null} The constructor or null.\n */\nexport const getWidgetManagerConstructor =\n  (): StaffbaseWidgetManagerConstructor | null => {\n    if (typeof window === 'undefined') return null\n    const ctor = (\n      window as unknown as {\n        staffbase?: { content?: { widgetMgr?: unknown } }\n      }\n    ).staffbase?.content?.widgetMgr\n    return typeof ctor === 'function'\n      ? (ctor as StaffbaseWidgetManagerConstructor)\n      : null\n  }\n","import type { StaffbaseWidgetManagerPrototype } from '../types/widgets/StaffbaseWidgetManagerPrototype'\n\n/**\n * Resolves the host widget-manager prototype (the private fallback API) from the\n * global Staffbase object, or null when it is unavailable.\n * @returns {StaffbaseWidgetManagerPrototype | null} The prototype or null.\n */\nexport const getWidgetManagerPrototype =\n  (): StaffbaseWidgetManagerPrototype | null => {\n    if (typeof window === 'undefined') return null\n    const proto = (\n      window as unknown as {\n        staffbase?: {\n          content?: {\n            widgetMgr?: { prototype?: StaffbaseWidgetManagerPrototype }\n          }\n        }\n      }\n    ).staffbase?.content?.widgetMgr?.prototype\n    return proto ?? null\n  }\n","import type { StaffbaseWidgetManagerPrototype } from '../types/widgets/StaffbaseWidgetManagerPrototype'\n\n/**\n * Type guard asserting the widget-manager prototype exposes the methods the\n * prototype render path needs.\n * @param {StaffbaseWidgetManagerPrototype} widgetMgr - The resolved prototype.\n * @returns {boolean} True when both _extractWidgets and _renderWidget are functions.\n */\nexport const hasRequiredWidgetManagerMethods = (\n  widgetMgr: StaffbaseWidgetManagerPrototype,\n): widgetMgr is StaffbaseWidgetManagerPrototype & {\n  _extractWidgets: (container: HTMLElement) => unknown[]\n  _renderWidget: (\n    this: StaffbaseWidgetManagerPrototype,\n    container: HTMLElement,\n    widget: unknown,\n  ) => void\n} =>\n  typeof widgetMgr._extractWidgets === 'function' &&\n  typeof widgetMgr._renderWidget === 'function'\n","/**\n * Detects known, benign internal Staffbase errors thrown by `_renderWidget` for\n * individual widgets, so they can be swallowed without aborting the batch.\n * Promoted from unacknowledged-bulletins (`each` / `undefined is not an object`).\n * @param {unknown} error - The thrown value.\n * @returns {boolean} True when the error is a known internal render error.\n */\nexport const isKnownStaffbaseRenderError = (error: unknown): boolean =>\n  error instanceof TypeError &&\n  (error.message?.includes('each') ||\n    error.message?.includes('undefined is not an object'))\n","import type { RenderWidgetsOptions } from '../types/widgets/RenderWidgetsOptions'\nimport type { RenderWidgetsResult } from '../types/widgets/RenderWidgetsResult'\n\nimport { defaultWidgetOnError } from './defaultWidgetOnError'\nimport { getWidgetManagerConstructor } from './getWidgetManagerConstructor'\nimport { getWidgetManagerPrototype } from './getWidgetManagerPrototype'\nimport { hasRequiredWidgetManagerMethods } from './hasRequiredWidgetManagerMethods'\nimport { isKnownStaffbaseRenderError } from './isKnownStaffbaseRenderError'\n\n// Global serialization chain: all renders run one at a time so they never race\n// on the host's shared `_widgets` array (unacknowledged-bulletins' lock, made\n// queue-based). Per-cancelKey run ids drop superseded renders (alerts' WeakMap\n// cancellation; no AbortController, for old webviews). warn-once keeps a missing\n// manager observable without spam (alerts).\nlet queue: Promise<unknown> = Promise.resolve()\nconst cancelTokens = new WeakMap<object, number>()\nlet hasWarnedManagerUnavailable = false\n\n/**\n * Runs the retry loop for a single render: constructor path first, prototype\n * fallback, with cancellation checks and known-error swallowing.\n * @param {HTMLElement} container - The container to render widgets into.\n * @param {object} cancelKey - The cancellation key for this render.\n * @param {number} runId - This render's run id for the cancel key.\n * @param {number} maxRetries - Maximum render attempts.\n * @param {number} retryDelay - Delay between attempts, in milliseconds.\n * @param {(error: unknown, context: string) => void} onError - Error reporter.\n * @returns {Promise<RenderWidgetsResult>} The typed render result.\n */\nconst executeRender = async (\n  container: HTMLElement,\n  cancelKey: object,\n  runId: number,\n  maxRetries: number,\n  retryDelay: number,\n  onError: (error: unknown, context: string) => void,\n): Promise<RenderWidgetsResult> => {\n  let attempts = 0\n  let managerSeen = false\n\n  while (attempts < maxRetries) {\n    attempts++\n    if (cancelTokens.get(cancelKey) !== runId)\n      return { ok: false, reason: 'cancelled' }\n    if (typeof container.querySelectorAll !== 'function') {\n      return { ok: false, reason: 'no-container' }\n    }\n\n    // Prefer Staffbase's real widget manager (closest to host behavior).\n    const ctor = getWidgetManagerConstructor()\n    if (ctor) {\n      managerSeen = true\n      try {\n        const instance = new ctor(undefined, false)\n        if (typeof instance.render === 'function') {\n          await instance.render(container)\n          return { ok: true, rendered: 0 }\n        }\n      } catch {\n        // Fall back to the private prototype path below.\n      }\n    }\n\n    const proto = getWidgetManagerPrototype()\n    if (proto && hasRequiredWidgetManagerMethods(proto)) {\n      managerSeen = true\n      if (!Array.isArray(proto._widgets)) proto._widgets = []\n\n      let widgets: unknown[]\n      try {\n        widgets = proto._extractWidgets(container)\n      } catch (error) {\n        onError(error, 'extract')\n        widgets = []\n      }\n\n      if (widgets.length > 0) {\n        let rendered = 0\n        for (const widget of widgets) {\n          if (cancelTokens.get(cancelKey) !== runId) {\n            return { ok: false, reason: 'cancelled' }\n          }\n          try {\n            proto._renderWidget.call(proto, container, widget)\n            rendered++\n          } catch (error) {\n            if (!isKnownStaffbaseRenderError(error))\n              onError(error, 'render-widget')\n          }\n        }\n        return { ok: true, rendered }\n      }\n    }\n\n    if (attempts >= maxRetries) break\n    await new Promise((resolve) => setTimeout(resolve, retryDelay))\n  }\n\n  if (!managerSeen) {\n    if (!hasWarnedManagerUnavailable) {\n      hasWarnedManagerUnavailable = true\n      onError(\n        new Error('Staffbase widget manager unavailable after retries.'),\n        'manager-unavailable',\n      )\n    }\n    return { ok: false, reason: 'manager-unavailable' }\n  }\n  return { ok: false, reason: 'no-widgets' }\n}\n\n/**\n * Renders the widgets embedded in `container` using the host's private widget\n * manager. Superset of the four widget services: constructor path first with a\n * prototype fallback, a global queue that serializes renders, per-cancelKey\n * cancellation of superseded renders, configurable retries, swallowing of known\n * internal Staffbase errors, and a once-per-session warning when the manager is\n * missing. Returns a typed result so callers can react (e.g. mark a\n * data-widget-render-error attribute).\n * @param {HTMLElement | null} container - The element whose embedded widgets are rendered.\n * @param {RenderWidgetsOptions} options - Retry, error and cancellation options.\n * @returns {Promise<RenderWidgetsResult>} The typed render result.\n */\nexport const renderWidgets = (\n  container: HTMLElement | null,\n  options: RenderWidgetsOptions = {},\n): Promise<RenderWidgetsResult> => {\n  if (!container) return Promise.resolve({ ok: false, reason: 'no-container' })\n\n  const {\n    maxRetries = 10,\n    retryDelay = 300,\n    onError = defaultWidgetOnError,\n    cancelKey = container,\n  } = options\n\n  // Bump the run id synchronously so any older in-flight/queued render for the\n  // same key sees itself as superseded.\n  const runId = (cancelTokens.get(cancelKey) ?? 0) + 1\n  cancelTokens.set(cancelKey, runId)\n\n  const run = queue.then(() =>\n    executeRender(container, cancelKey, runId, maxRetries, retryDelay, onError),\n  )\n  // Keep the queue chain alive regardless of individual outcomes.\n  queue = run.then(\n    () => undefined,\n    () => undefined,\n  )\n  return run\n}\n"],"mappings":"AAQA,IAAa,GAAwB,EAAgB,IAA0B,CACzE,IAAY,uBACd,QAAQ,KACN,8FACA,CACF,CAEJ,ECRa,MACqC,CAC9C,GAAI,OAAO,OAAW,IAAa,OAAO,KAC1C,IAAM,EACJ,OAGA,WAAW,SAAS,UACtB,OAAO,OAAO,GAAS,WAClB,EACD,IACN,ECXW,MAEL,OAAO,OAAW,IAAoB,KAExC,OAOA,WAAW,SAAS,WAAW,WACjB,KCXP,EACX,GASA,OAAO,EAAU,iBAAoB,YACrC,OAAO,EAAU,eAAkB,WCZxB,EAA+B,GAC1C,aAAiB,YAChB,EAAM,SAAS,SAAS,MAAM,GAC7B,EAAM,SAAS,SAAS,4BAA4B,GCIpD,EAA0B,QAAQ,QAAQ,EACxC,EAAe,IAAI,QACrB,EAA8B,GAa5B,EAAgB,MACpB,EACA,EACA,EACA,EACA,EACA,IACiC,CACjC,IAAI,EAAW,EACX,EAAc,GAElB,KAAO,EAAW,GAAY,CAE5B,GADA,IACI,EAAa,IAAI,CAAS,IAAM,EAClC,MAAO,CAAE,GAAI,GAAO,OAAQ,WAAY,EAC1C,GAAI,OAAO,EAAU,kBAAqB,WACxC,MAAO,CAAE,GAAI,GAAO,OAAQ,cAAe,EAI7C,IAAM,EAAO,EAA4B,EACzC,GAAI,EAAM,CACR,EAAc,GACd,GAAI,CACF,IAAM,EAAW,IAAI,EAAK,IAAA,GAAW,EAAK,EAC1C,GAAI,OAAO,EAAS,QAAW,WAE7B,OADA,MAAM,EAAS,OAAO,CAAS,EACxB,CAAE,GAAI,GAAM,SAAU,CAAE,CAEnC,MAAQ,CAER,CACF,CAEA,IAAM,EAAQ,EAA0B,EACxC,GAAI,GAAS,EAAgC,CAAK,EAAG,CACnD,EAAc,GACT,MAAM,QAAQ,EAAM,QAAQ,IAAG,EAAM,SAAW,CAAC,GAEtD,IAAI,EACJ,GAAI,CACF,EAAU,EAAM,gBAAgB,CAAS,CAC3C,OAAS,EAAO,CACd,EAAQ,EAAO,SAAS,EACxB,EAAU,CAAC,CACb,CAEA,GAAI,EAAQ,OAAS,EAAG,CACtB,IAAI,EAAW,EACf,IAAK,IAAM,KAAU,EAAS,CAC5B,GAAI,EAAa,IAAI,CAAS,IAAM,EAClC,MAAO,CAAE,GAAI,GAAO,OAAQ,WAAY,EAE1C,GAAI,CACF,EAAM,cAAc,KAAK,EAAO,EAAW,CAAM,EACjD,GACF,OAAS,EAAO,CACT,EAA4B,CAAK,GACpC,EAAQ,EAAO,eAAe,CAClC,CACF,CACA,MAAO,CAAE,GAAI,GAAM,UAAS,CAC9B,CACF,CAEA,GAAI,GAAY,EAAY,MAC5B,MAAM,IAAI,QAAS,GAAY,WAAW,EAAS,CAAU,CAAC,CAChE,CAYA,OAVK,EAUE,CAAE,GAAI,GAAO,OAAQ,YAAa,GATlC,IACH,EAA8B,GAC9B,EACM,MAAM,qDAAqD,EAC/D,qBACF,GAEK,CAAE,GAAI,GAAO,OAAQ,qBAAsB,EAGtD,EAca,GACX,EACA,EAAgC,CAAC,IACA,CACjC,GAAI,CAAC,EAAW,OAAO,QAAQ,QAAQ,CAAE,GAAI,GAAO,OAAQ,cAAe,CAAC,EAE5E,GAAM,CACJ,aAAa,GACb,aAAa,IACb,UAAU,EACV,YAAY,GACV,EAIE,GAAS,EAAa,IAAI,CAAS,GAAK,GAAK,EACnD,EAAa,IAAI,EAAW,CAAK,EAEjC,IAAM,EAAM,EAAM,SAChB,EAAc,EAAW,EAAW,EAAO,EAAY,EAAY,CAAO,CAC5E,EAMA,MAJA,GAAQ,EAAI,SACJ,IAAA,OACA,IAAA,EACR,EACO,CACT"}

package/dist/src/links/getInAppOpenLinkTarget.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Returns an absolute URL string that is safe to pass into Staffbase's
+ * `openLink()`. We intentionally do NOT require `/openlink/`; if the platform
+ * strips it, links can still open in-app by delegating to `openLink()`. Ported
+ * from staffbase-alerts (identical to unack).
+ * @param {string | null | undefined} href - Raw href as found on an <a> element.
+ * @param {string} baseUrl - Base URL used to resolve relative hrefs (usually window.location.origin).
+ * @returns {string | null} An absolute URL string, or null if it should not be handled.
+ */
+export declare const getInAppOpenLinkTarget: (href: string | null | undefined, baseUrl: string) => string | null;
+//# sourceMappingURL=getInAppOpenLinkTarget.d.ts.map

package/dist/src/links/getInAppOpenLinkTarget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"getInAppOpenLinkTarget.d.ts","sourceRoot":"","sources":["../../../src/links/getInAppOpenLinkTarget.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AACH,eAAO,MAAM,sBAAsB,GACjC,MAAM,MAAM,GAAG,IAAI,GAAG,SAAS,EAC/B,SAAS,MAAM,KACd,MAAM,GAAG,IAsCX,CAAA"}

package/dist/src/links/index.d.ts

@@ -0,0 +1,7 @@
+export { getInAppOpenLinkTarget } from './getInAppOpenLinkTarget';
+export { isAllowedIframeSrc } from './isAllowedIframeSrc';
+export { isSafeNavigationHref } from './isSafeNavigationHref';
+export { normalizeInAppLinks } from './normalizeInAppLinks';
+export { openStaffbaseAware } from './openStaffbaseAware';
+export { tryOpenWithStaffbase } from './tryOpenWithStaffbase';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/links/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/links/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAA;AACjE,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAA;AACzD,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAA;AAC7D,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAA;AAC3D,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAA;AACzD,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAA"}

package/dist/src/links/isAllowedIframeSrc.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Returns true when an iframe src may be rendered. Same-origin sources are
+ * always allowed; cross-origin sources must match the embed allowlist. Pair with
+ * sanitizeArticleHtml's `isAllowedIframeSrc` option.
+ * @param {string} src - The iframe src attribute value.
+ * @returns {boolean} True when the iframe may be kept.
+ */
+export declare const isAllowedIframeSrc: (src: string) => boolean;
+//# sourceMappingURL=isAllowedIframeSrc.d.ts.map

package/dist/src/links/isAllowedIframeSrc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"isAllowedIframeSrc.d.ts","sourceRoot":"","sources":["../../../src/links/isAllowedIframeSrc.ts"],"names":[],"mappings":"AAeA;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,GAAI,KAAK,MAAM,KAAG,OAqBhD,CAAA"}

package/dist/src/links/isPromiseLike.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Type guard for Promise-like (thenable) values, used to normalize whatever
+ * Staffbase's openLink returns.
+ * @param {unknown} value - The value to test.
+ * @returns {boolean} True when value has a callable then method.
+ */
+export declare const isPromiseLike: (value: unknown) => value is PromiseLike<unknown>;
+//# sourceMappingURL=isPromiseLike.d.ts.map

package/dist/src/links/isPromiseLike.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"isPromiseLike.d.ts","sourceRoot":"","sources":["../../../src/links/isPromiseLike.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,eAAO,MAAM,aAAa,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,WAAW,CAAC,OAAO,CAIf,CAAA"}

package/dist/src/links/isSafeNavigationHref.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Returns true when an href is safe to pass to a real browser navigation
+ * (e.g. `window.location.assign`). Blocks scripted/inline schemes that could
+ * execute in the session-bearing webview. Relative URLs and http(s)/mailto/tel
+ * are allowed. Promoted from staffbase-alerts.
+ * @param {string} href - The href to validate.
+ * @returns {boolean} True when the href is safe to navigate to.
+ */
+export declare const isSafeNavigationHref: (href: string) => boolean;
+//# sourceMappingURL=isSafeNavigationHref.d.ts.map

package/dist/src/links/isSafeNavigationHref.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"isSafeNavigationHref.d.ts","sourceRoot":"","sources":["../../../src/links/isSafeNavigationHref.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,GAAI,MAAM,MAAM,KAAG,OASnD,CAAA"}

package/dist/src/links/normalizeInAppLinks.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Normalizes links inside Staffbase-rendered HTML so they behave better in mobile
+ * apps. On iOS, absolute same-origin links and/or `target="_blank"` can trigger
+ * Safari instead of in-app navigation; for same-origin links we rewrite to
+ * relative paths and remove target/rel. Ported from staffbase-alerts (the
+ * superset): cross-origin `target="_blank"` links are hardened with
+ * `rel="noopener noreferrer"` instead of left untouched. The Staffbase origin is
+ * passed in (the lib never reads env).
+ * @param {HTMLElement} root - The container whose anchors are normalized.
+ * @param {string} staffbaseOrigin - The Staffbase origin used to detect same-origin links.
+ * @returns {void}
+ */
+export declare const normalizeInAppLinks: (root: HTMLElement, staffbaseOrigin: string) => void;
+//# sourceMappingURL=normalizeInAppLinks.d.ts.map

package/dist/src/links/normalizeInAppLinks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalizeInAppLinks.d.ts","sourceRoot":"","sources":["../../../src/links/normalizeInAppLinks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,mBAAmB,GAC9B,MAAM,WAAW,EACjB,iBAAiB,MAAM,KACtB,IAsDF,CAAA"}

package/dist/src/links/openStaffbaseAware.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Try to open with Staffbase; if not available, navigate normally in the same
+ * tab. Ported from staffbase-alerts (the superset): it guards with
+ * isSafeNavigationHref first, so scripted schemes never reach navigation.
+ * @param {string} href - The target URL to open.
+ * @returns {boolean} True if Staffbase handled the navigation, otherwise false.
+ */
+export declare const openStaffbaseAware: (href: string) => boolean;
+//# sourceMappingURL=openStaffbaseAware.d.ts.map

package/dist/src/links/openStaffbaseAware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openStaffbaseAware.d.ts","sourceRoot":"","sources":["../../../src/links/openStaffbaseAware.ts"],"names":[],"mappings":"AAGA;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,GAAI,MAAM,MAAM,KAAG,OAuDjD,CAAA"}

package/dist/src/links/stripStaffbaseLinkPrefix.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Strips a leading Staffbase link prefix (`/deeplink/` or `/openlink/`) from a
+ * URL pathname, leaving the canonical in-app path.
+ * @param {string} path - The URL pathname.
+ * @returns {string} The path without the Staffbase prefix.
+ */
+export declare const stripStaffbaseLinkPrefix: (path: string) => string;
+//# sourceMappingURL=stripStaffbaseLinkPrefix.d.ts.map

package/dist/src/links/stripStaffbaseLinkPrefix.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stripStaffbaseLinkPrefix.d.ts","sourceRoot":"","sources":["../../../src/links/stripStaffbaseLinkPrefix.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,GAAI,MAAM,MAAM,KAAG,MAMvD,CAAA"}

package/dist/src/links/tryOpenWithStaffbase.d.ts

@@ -0,0 +1,10 @@
+import { TryOpenResult } from '../types/links/TryOpenResult';
+/**
+ * Attempt to open a link using Staffbase's plugin util.openLink if available.
+ * Ported from staffbase-alerts (typed Promise-like guard; smart-search used
+ * `as any`).
+ * @param {string} href - The target URL to open.
+ * @returns {TryOpenResult} Whether Staffbase handled it and a promise if available.
+ */
+export declare const tryOpenWithStaffbase: (href: string) => TryOpenResult;
+//# sourceMappingURL=tryOpenWithStaffbase.d.ts.map

package/dist/src/links/tryOpenWithStaffbase.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tryOpenWithStaffbase.d.ts","sourceRoot":"","sources":["../../../src/links/tryOpenWithStaffbase.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAA;AAKjE;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,GAAI,MAAM,MAAM,KAAG,aAoBnD,CAAA"}

package/dist/src/types/links/TryOpenResult.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Result of attempting to open a link through Staffbase's plugin util.openLink.
+ */
+export interface TryOpenResult {
+    /** Whether Staffbase handled the open call. */
+    handled: boolean;
+    /** The promise openLink returned, when it returned one. */
+    promise?: Promise<void>;
+}
+//# sourceMappingURL=TryOpenResult.d.ts.map

package/dist/src/types/links/TryOpenResult.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TryOpenResult.d.ts","sourceRoot":"","sources":["../../../../src/types/links/TryOpenResult.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,+CAA+C;IAC/C,OAAO,EAAE,OAAO,CAAA;IAChB,2DAA2D;IAC3D,OAAO,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,CAAA;CACxB"}

package/dist/src/types/links/WindowWithStaffbase.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Window augmented with the Staffbase plugin util surface used for in-app link
+ * opening. The whole chain is optional because the host API may be absent.
+ */
+export interface WindowWithStaffbase extends Window {
+    staffbase?: {
+        plugin?: {
+            util?: {
+                openLink?: (link: string, opts?: unknown) => unknown;
+            };
+        };
+    };
+}
+//# sourceMappingURL=WindowWithStaffbase.d.ts.map

package/dist/src/types/links/WindowWithStaffbase.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WindowWithStaffbase.d.ts","sourceRoot":"","sources":["../../../../src/types/links/WindowWithStaffbase.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,WAAW,mBAAoB,SAAQ,MAAM;IACjD,SAAS,CAAC,EAAE;QACV,MAAM,CAAC,EAAE;YACP,IAAI,CAAC,EAAE;gBACL,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,KAAK,OAAO,CAAA;aACrD,CAAA;SACF,CAAA;KACF,CAAA;CACF"}

package/dist/src/types/widgets/RenderWidgetsOptions.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Options for renderWidgets.
+ */
+export interface RenderWidgetsOptions {
+    /** Maximum render attempts before giving up. Default 10. */
+    maxRetries?: number;
+    /** Delay between attempts, in milliseconds. Default 300. */
+    retryDelay?: number;
+    /**
+     * Called when an error is swallowed. `context` labels where it happened
+     * (e.g. 'manager-unavailable', 'extract', 'render-widget'). Default: warn on
+     * critical context only.
+     */
+    onError?: (error: unknown, context: string) => void;
+    /**
+     * Token used to dedupe/cancel repeated renders. A newer render with the same
+     * key cancels older in-flight/queued ones. Default: the container element.
+     */
+    cancelKey?: object;
+}
+//# sourceMappingURL=RenderWidgetsOptions.d.ts.map

package/dist/src/types/widgets/RenderWidgetsOptions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RenderWidgetsOptions.d.ts","sourceRoot":"","sources":["../../../../src/types/widgets/RenderWidgetsOptions.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,4DAA4D;IAC5D,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,4DAA4D;IAC5D,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB;;;;OAIG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;IACnD;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB"}

package/dist/src/types/widgets/RenderWidgetsResult.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Result of a renderWidgets call. `rendered` is the number of widgets rendered
+ * via the prototype path; it is 0 when the host constructor path handled
+ * rendering (the count is not observable there).
+ */
+export type RenderWidgetsResult = {
+    ok: true;
+    rendered: number;
+} | {
+    ok: false;
+    reason: 'no-container' | 'manager-unavailable' | 'no-widgets' | 'cancelled';
+};
+//# sourceMappingURL=RenderWidgetsResult.d.ts.map

package/dist/src/types/widgets/RenderWidgetsResult.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RenderWidgetsResult.d.ts","sourceRoot":"","sources":["../../../../src/types/widgets/RenderWidgetsResult.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,MAAM,mBAAmB,GAC3B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAC9B;IACE,EAAE,EAAE,KAAK,CAAA;IACT,MAAM,EACF,cAAc,GACd,qBAAqB,GACrB,YAAY,GACZ,WAAW,CAAA;CAChB,CAAA"}

package/dist/src/types/widgets/StaffbaseWidgetManagerConstructor.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The host's widget-manager constructor (`window.staffbase.content.widgetMgr`).
+ * The signature is internal; most builds accept `(unused, isEditor?)` and the
+ * instance exposes a `render(container)` method.
+ */
+export type StaffbaseWidgetManagerConstructor = new (...args: unknown[]) => {
+    render?: (container: HTMLElement) => Promise<void> | void;
+};
+//# sourceMappingURL=StaffbaseWidgetManagerConstructor.d.ts.map

package/dist/src/types/widgets/StaffbaseWidgetManagerConstructor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"StaffbaseWidgetManagerConstructor.d.ts","sourceRoot":"","sources":["../../../../src/types/widgets/StaffbaseWidgetManagerConstructor.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,MAAM,iCAAiC,GAAG,KAAK,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK;IAC1E,MAAM,CAAC,EAAE,CAAC,SAAS,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;CAC1D,CAAA"}

package/dist/src/types/widgets/StaffbaseWidgetManagerPrototype.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The host's private widget-manager prototype
+ * (`window.staffbase.content.widgetMgr.prototype`). All members are optional
+ * because this is an undocumented API that may change.
+ */
+export interface StaffbaseWidgetManagerPrototype {
+    _widgets?: unknown[];
+    _extractWidgets?: (container: HTMLElement) => unknown[];
+    _renderWidget?: (this: StaffbaseWidgetManagerPrototype, container: HTMLElement, widget: unknown) => void;
+}
+//# sourceMappingURL=StaffbaseWidgetManagerPrototype.d.ts.map

package/dist/src/types/widgets/StaffbaseWidgetManagerPrototype.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"StaffbaseWidgetManagerPrototype.d.ts","sourceRoot":"","sources":["../../../../src/types/widgets/StaffbaseWidgetManagerPrototype.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,WAAW,+BAA+B;IAC9C,QAAQ,CAAC,EAAE,OAAO,EAAE,CAAA;IACpB,eAAe,CAAC,EAAE,CAAC,SAAS,EAAE,WAAW,KAAK,OAAO,EAAE,CAAA;IACvD,aAAa,CAAC,EAAE,CACd,IAAI,EAAE,+BAA+B,EACrC,SAAS,EAAE,WAAW,EACtB,MAAM,EAAE,OAAO,KACZ,IAAI,CAAA;CACV"}

package/dist/src/types/widgets/UseRenderWidgetsOptions.d.ts

@@ -0,0 +1,16 @@
+import { DependencyList } from 'react';
+import { RenderWidgetsOptions } from './RenderWidgetsOptions';
+/**
+ * Options for the useRenderWidgets hook: renderWidgets options plus optional
+ * MutationObserver wiring.
+ */
+export interface UseRenderWidgetsOptions extends RenderWidgetsOptions {
+    /**
+     * When true, a debounced MutationObserver (childList + subtree) re-renders on
+     * article HTML changes (accordions, "View more"), cleaned up on unmount.
+     */
+    observe?: boolean;
+    /** Effect dependency list controlling when a render re-runs. Default []. */
+    deps?: DependencyList;
+}
+//# sourceMappingURL=UseRenderWidgetsOptions.d.ts.map

package/dist/src/types/widgets/UseRenderWidgetsOptions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"UseRenderWidgetsOptions.d.ts","sourceRoot":"","sources":["../../../../src/types/widgets/UseRenderWidgetsOptions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,OAAO,CAAA;AAE3C,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAA;AAElE;;;GAGG;AACH,MAAM,WAAW,uBAAwB,SAAQ,oBAAoB;IACnE;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,4EAA4E;IAC5E,IAAI,CAAC,EAAE,cAAc,CAAA;CACtB"}

package/dist/src/widgets/defaultWidgetOnError.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Default onError for renderWidgets: warns only on the critical
+ * 'manager-unavailable' context so a platform regression stays visible in logs
+ * without spamming per-widget noise. Consumers can pass their own onError.
+ * @param {unknown} error - The swallowed error.
+ * @param {string} context - Where it happened.
+ * @returns {void}
+ */
+export declare const defaultWidgetOnError: (error: unknown, context: string) => void;
+//# sourceMappingURL=defaultWidgetOnError.d.ts.map

package/dist/src/widgets/defaultWidgetOnError.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"defaultWidgetOnError.d.ts","sourceRoot":"","sources":["../../../src/widgets/defaultWidgetOnError.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,GAAI,OAAO,OAAO,EAAE,SAAS,MAAM,KAAG,IAOtE,CAAA"}

package/dist/src/widgets/getWidgetManagerConstructor.d.ts

@@ -0,0 +1,8 @@
+import { StaffbaseWidgetManagerConstructor } from '../types/widgets/StaffbaseWidgetManagerConstructor';
+/**
+ * Resolves the host widget-manager constructor from the global Staffbase object,
+ * or null when it is not a function (older runtimes / platform regression).
+ * @returns {StaffbaseWidgetManagerConstructor | null} The constructor or null.
+ */
+export declare const getWidgetManagerConstructor: () => StaffbaseWidgetManagerConstructor | null;
+//# sourceMappingURL=getWidgetManagerConstructor.d.ts.map

package/dist/src/widgets/getWidgetManagerConstructor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"getWidgetManagerConstructor.d.ts","sourceRoot":"","sources":["../../../src/widgets/getWidgetManagerConstructor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iCAAiC,EAAE,MAAM,oDAAoD,CAAA;AAE3G;;;;GAIG;AACH,eAAO,MAAM,2BAA2B,QAClC,iCAAiC,GAAG,IAUvC,CAAA"}

package/dist/src/widgets/getWidgetManagerPrototype.d.ts

@@ -0,0 +1,8 @@
+import { StaffbaseWidgetManagerPrototype } from '../types/widgets/StaffbaseWidgetManagerPrototype';
+/**
+ * Resolves the host widget-manager prototype (the private fallback API) from the
+ * global Staffbase object, or null when it is unavailable.
+ * @returns {StaffbaseWidgetManagerPrototype | null} The prototype or null.
+ */
+export declare const getWidgetManagerPrototype: () => StaffbaseWidgetManagerPrototype | null;
+//# sourceMappingURL=getWidgetManagerPrototype.d.ts.map

package/dist/src/widgets/getWidgetManagerPrototype.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"getWidgetManagerPrototype.d.ts","sourceRoot":"","sources":["../../../src/widgets/getWidgetManagerPrototype.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,+BAA+B,EAAE,MAAM,kDAAkD,CAAA;AAEvG;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,QAChC,+BAA+B,GAAG,IAYrC,CAAA"}

package/dist/src/widgets/hasRequiredWidgetManagerMethods.d.ts

@@ -0,0 +1,12 @@
+import { StaffbaseWidgetManagerPrototype } from '../types/widgets/StaffbaseWidgetManagerPrototype';
+/**
+ * Type guard asserting the widget-manager prototype exposes the methods the
+ * prototype render path needs.
+ * @param {StaffbaseWidgetManagerPrototype} widgetMgr - The resolved prototype.
+ * @returns {boolean} True when both _extractWidgets and _renderWidget are functions.
+ */
+export declare const hasRequiredWidgetManagerMethods: (widgetMgr: StaffbaseWidgetManagerPrototype) => widgetMgr is StaffbaseWidgetManagerPrototype & {
+    _extractWidgets: (container: HTMLElement) => unknown[];
+    _renderWidget: (this: StaffbaseWidgetManagerPrototype, container: HTMLElement, widget: unknown) => void;
+};
+//# sourceMappingURL=hasRequiredWidgetManagerMethods.d.ts.map

package/dist/src/widgets/hasRequiredWidgetManagerMethods.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hasRequiredWidgetManagerMethods.d.ts","sourceRoot":"","sources":["../../../src/widgets/hasRequiredWidgetManagerMethods.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,+BAA+B,EAAE,MAAM,kDAAkD,CAAA;AAEvG;;;;;GAKG;AACH,eAAO,MAAM,+BAA+B,GAC1C,WAAW,+BAA+B,KACzC,SAAS,IAAI,+BAA+B,GAAG;IAChD,eAAe,EAAE,CAAC,SAAS,EAAE,WAAW,KAAK,OAAO,EAAE,CAAA;IACtD,aAAa,EAAE,CACb,IAAI,EAAE,+BAA+B,EACrC,SAAS,EAAE,WAAW,EACtB,MAAM,EAAE,OAAO,KACZ,IAAI,CAAA;CAGoC,CAAA"}

package/dist/src/widgets/index.d.ts

@@ -0,0 +1,2 @@
+export { renderWidgets } from './renderWidgets';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/widgets/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/widgets/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAA"}

package/dist/src/widgets/isKnownStaffbaseRenderError.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Detects known, benign internal Staffbase errors thrown by `_renderWidget` for
+ * individual widgets, so they can be swallowed without aborting the batch.
+ * Promoted from unacknowledged-bulletins (`each` / `undefined is not an object`).
+ * @param {unknown} error - The thrown value.
+ * @returns {boolean} True when the error is a known internal render error.
+ */
+export declare const isKnownStaffbaseRenderError: (error: unknown) => boolean;
+//# sourceMappingURL=isKnownStaffbaseRenderError.d.ts.map

package/dist/src/widgets/isKnownStaffbaseRenderError.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"isKnownStaffbaseRenderError.d.ts","sourceRoot":"","sources":["../../../src/widgets/isKnownStaffbaseRenderError.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,eAAO,MAAM,2BAA2B,GAAI,OAAO,OAAO,KAAG,OAGH,CAAA"}

package/dist/src/widgets/react/index.d.ts

@@ -0,0 +1,2 @@
+export { useRenderWidgets } from './useRenderWidgets';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/widgets/react/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/widgets/react/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAA"}

package/dist/src/widgets/react/useRenderWidgets.d.ts

@@ -0,0 +1,14 @@
+import { RefObject } from 'react';
+import { UseRenderWidgetsOptions } from '../../types/widgets/UseRenderWidgetsOptions';
+/**
+ * React adapter for renderWidgets. Renders on mount and whenever `deps` change,
+ * using `ref.current` as the cancelKey. With `observe: true` it mounts a
+ * debounced MutationObserver (childList + subtree) that re-renders on article
+ * HTML changes and cleans up on unmount. Absorbs the render/observe glue that
+ * the widgets repeat in their Article loaders.
+ * @param {RefObject<HTMLElement | null>} ref - Ref to the widget container.
+ * @param {UseRenderWidgetsOptions} options - renderWidgets options plus observe/deps.
+ * @returns {void}
+ */
+export declare const useRenderWidgets: (ref: RefObject<HTMLElement | null>, options?: UseRenderWidgetsOptions) => void;
+//# sourceMappingURL=useRenderWidgets.d.ts.map

package/dist/src/widgets/react/useRenderWidgets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useRenderWidgets.d.ts","sourceRoot":"","sources":["../../../../src/widgets/react/useRenderWidgets.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAGtC,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,6CAA6C,CAAA;AAG1F;;;;;;;;;GASG;AACH,eAAO,MAAM,gBAAgB,GAC3B,KAAK,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,EAClC,UAAS,uBAA4B,KACpC,IAwBF,CAAA"}

package/dist/src/widgets/renderWidgets.d.ts

@@ -0,0 +1,16 @@
+import { RenderWidgetsOptions } from '../types/widgets/RenderWidgetsOptions';
+import { RenderWidgetsResult } from '../types/widgets/RenderWidgetsResult';
+/**
+ * Renders the widgets embedded in `container` using the host's private widget
+ * manager. Superset of the four widget services: constructor path first with a
+ * prototype fallback, a global queue that serializes renders, per-cancelKey
+ * cancellation of superseded renders, configurable retries, swallowing of known
+ * internal Staffbase errors, and a once-per-session warning when the manager is
+ * missing. Returns a typed result so callers can react (e.g. mark a
+ * data-widget-render-error attribute).
+ * @param {HTMLElement | null} container - The element whose embedded widgets are rendered.
+ * @param {RenderWidgetsOptions} options - Retry, error and cancellation options.
+ * @returns {Promise<RenderWidgetsResult>} The typed render result.
+ */
+export declare const renderWidgets: (container: HTMLElement | null, options?: RenderWidgetsOptions) => Promise<RenderWidgetsResult>;
+//# sourceMappingURL=renderWidgets.d.ts.map

package/dist/src/widgets/renderWidgets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"renderWidgets.d.ts","sourceRoot":"","sources":["../../../src/widgets/renderWidgets.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,uCAAuC,CAAA;AACjF,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sCAAsC,CAAA;AA8G/E;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,aAAa,GACxB,WAAW,WAAW,GAAG,IAAI,EAC7B,UAAS,oBAAyB,KACjC,OAAO,CAAC,mBAAmB,CAwB7B,CAAA"}

package/dist/widgets/react.cjs.js

@@ -0,0 +1,2 @@
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require("../renderWidgets-EbJq9Wn6.js");let t=require("react");var n=(n,r={})=>{let{observe:i=!1,deps:a=[],...o}=r;(0,t.useEffect)(()=>{let t=n.current;if(!t)return;let r={...o,cancelKey:t};if(e.t(t,r),!i)return;let a,s=new MutationObserver(()=>{clearTimeout(a),a=setTimeout(()=>void e.t(n.current,r),100)});return s.observe(t,{childList:!0,subtree:!0}),()=>{clearTimeout(a),s.disconnect()}},a)};exports.useRenderWidgets=n;
+//# sourceMappingURL=react.cjs.js.map

package/dist/widgets/react.cjs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"react.cjs.js","names":[],"sources":["../../src/widgets/react/useRenderWidgets.ts"],"sourcesContent":["import type { RefObject } from 'react'\nimport { useEffect } from 'react'\n\nimport type { UseRenderWidgetsOptions } from '../../types/widgets/UseRenderWidgetsOptions'\nimport { renderWidgets } from '../renderWidgets'\n\n/**\n * React adapter for renderWidgets. Renders on mount and whenever `deps` change,\n * using `ref.current` as the cancelKey. With `observe: true` it mounts a\n * debounced MutationObserver (childList + subtree) that re-renders on article\n * HTML changes and cleans up on unmount. Absorbs the render/observe glue that\n * the widgets repeat in their Article loaders.\n * @param {RefObject<HTMLElement | null>} ref - Ref to the widget container.\n * @param {UseRenderWidgetsOptions} options - renderWidgets options plus observe/deps.\n * @returns {void}\n */\nexport const useRenderWidgets = (\n  ref: RefObject<HTMLElement | null>,\n  options: UseRenderWidgetsOptions = {},\n): void => {\n  const { observe = false, deps = [], ...renderOptions } = options\n\n  useEffect(() => {\n    const el = ref.current\n    if (!el) return\n\n    const opts = { ...renderOptions, cancelKey: el }\n    void renderWidgets(el, opts)\n\n    if (!observe) return\n\n    let timer: ReturnType<typeof setTimeout>\n    const observer = new MutationObserver(() => {\n      clearTimeout(timer)\n      timer = setTimeout(() => void renderWidgets(ref.current, opts), 100)\n    })\n    observer.observe(el, { childList: true, subtree: true })\n\n    return () => {\n      clearTimeout(timer)\n      observer.disconnect()\n    }\n  }, deps)\n}\n"],"mappings":"0IAgBA,IAAa,GACX,EACA,EAAmC,CAAC,IAC3B,CACT,GAAM,CAAE,UAAU,GAAO,OAAO,CAAC,EAAG,GAAG,GAAkB,GAEzD,EAAA,EAAA,eAAgB,CACd,IAAM,EAAK,EAAI,QACf,GAAI,CAAC,EAAI,OAET,IAAM,EAAO,CAAE,GAAG,EAAe,UAAW,CAAG,EAG/C,GAFA,EAAK,EAAc,EAAI,CAAI,EAEvB,CAAC,EAAS,OAEd,IAAI,EACE,EAAW,IAAI,qBAAuB,CAC1C,aAAa,CAAK,EAClB,EAAQ,eAAiB,KAAK,EAAA,EAAc,EAAI,QAAS,CAAI,EAAG,GAAG,CACrE,CAAC,EAGD,OAFA,EAAS,QAAQ,EAAI,CAAE,UAAW,GAAM,QAAS,EAAK,CAAC,MAE1C,CACX,aAAa,CAAK,EAClB,EAAS,WAAW,CACtB,CACF,EAAG,CAAI,CACT"}

package/dist/widgets/react.es.mjs

@@ -0,0 +1,28 @@
+import { t as e } from "../renderWidgets-CeIczubt.mjs";
+import { useEffect as t } from "react";
+//#region src/widgets/react/useRenderWidgets.ts
+var n = (n, r = {}) => {
+	let { observe: i = !1, deps: a = [], ...o } = r;
+	t(() => {
+		let t = n.current;
+		if (!t) return;
+		let r = {
+			...o,
+			cancelKey: t
+		};
+		if (e(t, r), !i) return;
+		let a, s = new MutationObserver(() => {
+			clearTimeout(a), a = setTimeout(() => void e(n.current, r), 100);
+		});
+		return s.observe(t, {
+			childList: !0,
+			subtree: !0
+		}), () => {
+			clearTimeout(a), s.disconnect();
+		};
+	}, a);
+};
+//#endregion
+export { n as useRenderWidgets };
+
+//# sourceMappingURL=react.es.mjs.map

package/dist/widgets/react.es.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"react.es.mjs","names":[],"sources":["../../src/widgets/react/useRenderWidgets.ts"],"sourcesContent":["import type { RefObject } from 'react'\nimport { useEffect } from 'react'\n\nimport type { UseRenderWidgetsOptions } from '../../types/widgets/UseRenderWidgetsOptions'\nimport { renderWidgets } from '../renderWidgets'\n\n/**\n * React adapter for renderWidgets. Renders on mount and whenever `deps` change,\n * using `ref.current` as the cancelKey. With `observe: true` it mounts a\n * debounced MutationObserver (childList + subtree) that re-renders on article\n * HTML changes and cleans up on unmount. Absorbs the render/observe glue that\n * the widgets repeat in their Article loaders.\n * @param {RefObject<HTMLElement | null>} ref - Ref to the widget container.\n * @param {UseRenderWidgetsOptions} options - renderWidgets options plus observe/deps.\n * @returns {void}\n */\nexport const useRenderWidgets = (\n  ref: RefObject<HTMLElement | null>,\n  options: UseRenderWidgetsOptions = {},\n): void => {\n  const { observe = false, deps = [], ...renderOptions } = options\n\n  useEffect(() => {\n    const el = ref.current\n    if (!el) return\n\n    const opts = { ...renderOptions, cancelKey: el }\n    void renderWidgets(el, opts)\n\n    if (!observe) return\n\n    let timer: ReturnType<typeof setTimeout>\n    const observer = new MutationObserver(() => {\n      clearTimeout(timer)\n      timer = setTimeout(() => void renderWidgets(ref.current, opts), 100)\n    })\n    observer.observe(el, { childList: true, subtree: true })\n\n    return () => {\n      clearTimeout(timer)\n      observer.disconnect()\n    }\n  }, deps)\n}\n"],"mappings":";;;AAgBA,IAAa,KACX,GACA,IAAmC,CAAC,MAC3B;CACT,IAAM,EAAE,aAAU,IAAO,UAAO,CAAC,GAAG,GAAG,MAAkB;CAEzD,QAAgB;EACd,IAAM,IAAK,EAAI;EACf,IAAI,CAAC,GAAI;EAET,IAAM,IAAO;GAAE,GAAG;GAAe,WAAW;EAAG;EAG/C,IAFA,EAAmB,GAAI,CAAI,GAEvB,CAAC,GAAS;EAEd,IAAI,GACE,IAAW,IAAI,uBAAuB;GAE1C,AADA,aAAa,CAAK,GAClB,IAAQ,iBAAiB,KAAK,EAAc,EAAI,SAAS,CAAI,GAAG,GAAG;EACrE,CAAC;EAGD,OAFA,EAAS,QAAQ,GAAI;GAAE,WAAW;GAAM,SAAS;EAAK,CAAC,SAE1C;GAEX,AADA,aAAa,CAAK,GAClB,EAAS,WAAW;EACtB;CACF,GAAG,CAAI;AACT"}

package/dist/widgets.cjs.js

@@ -0,0 +1 @@
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require("./renderWidgets-EbJq9Wn6.js");exports.renderWidgets=e.t;

package/dist/widgets.es.mjs

@@ -0,0 +1,2 @@
+import { t as e } from "./renderWidgets-CeIczubt.mjs";
+export { e as renderWidgets };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@favish/staffbase-utils",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Shared internal/host utilities for Staffbase widgets",
   "author": "Favish <dev@favish.com>",
   "license": "UNLICENSED",
@@ -22,6 +22,21 @@
       "types": "./dist/src/html/index.d.ts",
       "import": "./dist/html.es.mjs",
       "require": "./dist/html.cjs.js"
+    },
+    "./links": {
+      "types": "./dist/src/links/index.d.ts",
+      "import": "./dist/links.es.mjs",
+      "require": "./dist/links.cjs.js"
+    },
+    "./widgets": {
+      "types": "./dist/src/widgets/index.d.ts",
+      "import": "./dist/widgets.es.mjs",
+      "require": "./dist/widgets.cjs.js"
+    },
+    "./widgets/react": {
+      "types": "./dist/src/widgets/react/index.d.ts",
+      "import": "./dist/widgets/react.es.mjs",
+      "require": "./dist/widgets/react.cjs.js"
     }
   },
   "repository": {
@@ -50,6 +65,7 @@
     "@testing-library/jest-dom": "^6.9.1",
     "@types/jest": "^30.0.0",
     "@types/node": "^25",
+    "@types/react": "19.2.16",
     "@typescript-eslint/eslint-plugin": "^8.60.0",
     "@typescript-eslint/parser": "^8.60.0",
     "eslint": "^10.4.0",