@uniweb/kit 0.9.25 → 0.9.26

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/kit",
-  "version": "0.9.25",
+  "version": "0.9.26",
   "description": "Standard component library for Uniweb foundations",
   "type": "module",
   "exports": {
@@ -47,6 +47,10 @@
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "tailwindcss": "^4.0.0"
+    "tailwindcss": "^4.0.0",
+    "vitest": "^4.1.7"
+  },
+  "scripts": {
+    "test": "vitest run"
   }
 }

package/src/components/Link/Link.jsx

@@ -13,6 +13,7 @@
 import React from 'react'
 import { useWebsite } from '../../hooks/useWebsite.js'
 import { isExternalUrl, isFileUrl } from '../../utils/index.js'
+import { applyBasePath } from '../../utils/prose-html.js'
 
 /**
  * Social media platforms for auto-generating link titles
@@ -214,7 +215,7 @@ export function Link({
     const basePath = !isExternal ? (website?.basePath || '') : ''
     return (
       <a
-        href={basePath + linkHref}
+        href={applyBasePath(linkHref, basePath)}
         title={linkTitle}
         className={className}
         data-reload="true"
@@ -290,7 +291,7 @@ export function Link({
   const basePath = website?.basePath || ''
   return (
     <a
-      href={basePath + linkHref}
+      href={applyBasePath(linkHref, basePath)}
       title={linkTitle}
       className={className}
       {...props}

package/src/components/SafeHtml/SafeHtml.jsx

@@ -1,39 +1,20 @@
 /**
  * SafeHtml Component
  *
- * Safely renders HTML content with internal-reference link resolution.
- * Handles the `page:` (stable page reference) and `topic:` (legacy) protocols
- * for internal content references — the same protocols kit's <Link> resolves,
+ * Safely renders HTML content with authored-href resolution: the `page:`
+ * (stable page reference) and `topic:` (legacy) protocols, and the deployment
+ * base path — the same resolution kit's <Link> applies to a structured link,
  * so inline link marks inside rich-text bodies resolve identically.
  *
+ * The resolution itself lives in utils/prose-html.js, shared with <Text>, so
+ * both prose renderers agree on what an authored href means.
+ *
  * @module @uniweb/kit/SafeHtml
  */
 
 import React, { Suspense, useMemo } from 'react'
 import { useWebsite } from '../../hooks/useWebsite.js'
-
-// Matches an <a> tag's href attribute when it carries a page:/topic: internal
-// reference. Regex-based (not DOMParser) so it runs identically in the browser
-// SPA and during SSR/prerender, where no DOM is available.
-const INTERNAL_HREF_RE = /(<a\b[^>]*?\shref=)(["'])((?:page|topic):[^"']*)\2/gi
-
-/**
- * Resolve page:/topic: internal-reference hrefs in an HTML string to real
- * routes via website.makeHref(). Leaves everything else untouched; an
- * unresolvable reference is returned by makeHref unchanged.
- * @param {string} html - HTML string with potential page:/topic: links
- * @param {Object} website - Website instance
- * @returns {string} HTML with resolved link hrefs
- */
-function resolveInternalLinks(html, website) {
-  if (!html || typeof html !== 'string') return html
-  if (!html.includes('page:') && !html.includes('topic:')) return html
-
-  return html.replace(
-    INTERNAL_HREF_RE,
-    (_m, prefix, quote, href) => `${prefix}${quote}${website.makeHref(href)}${quote}`
-  )
-}
+import { resolveProseHrefs } from '../../utils/prose-html.js'
 
 /**
  * SafeHtml - Safely render HTML content
@@ -63,8 +44,8 @@ export function SafeHtml({ value, className, as: Component = 'div', ...props })
     // Handle array of HTML strings
     const html = Array.isArray(value) ? value.join('') : value
 
-    // Resolve page:/topic: internal-reference links
-    return website ? resolveInternalLinks(html, website) : html
+    // Resolve authored hrefs (page:/topic: references, base path)
+    return resolveProseHrefs(html, website)
   }, [value, website])
 
   // Use runtime SafeHtml if available (recommended for proper sanitization)

package/src/components/Text/Text.jsx

@@ -15,6 +15,22 @@
 
 import React, { memo } from 'react'
 import { cn } from '../../utils/index.js'
+import { resolveProseHrefs } from '../../utils/prose-html.js'
+
+/**
+ * Resolve authored hrefs in a prose string before it reaches the DOM.
+ *
+ * The website is read defensively rather than through useWebsite(), which
+ * throws when no runtime is initialized. Text is a presentation primitive and
+ * must stay usable without a runtime (press/unipress document builds, tests);
+ * making it context-required would be a regression. Same defensive read the
+ * runtime itself uses in Background, the SSR renderer and the link
+ * interceptor.
+ */
+function resolve(text) {
+  if (typeof text !== 'string') return text
+  return resolveProseHrefs(text, globalThis.uniweb?.activeWebsite)
+}
 
 /**
  * Text - Smart typography component
@@ -72,7 +88,7 @@ export const Text = memo(function Text({
       return (
         <Tag
           className={className}
-          dangerouslySetInnerHTML={{ __html: text }}
+          dangerouslySetInnerHTML={{ __html: resolve(text) }}
           {...props}
         />
       )
@@ -106,7 +122,7 @@ export const Text = memo(function Text({
             return (
               <LineTag
                 key={i}
-                dangerouslySetInnerHTML={{ __html: line }}
+                dangerouslySetInnerHTML={{ __html: resolve(line) }}
               />
             )
           }
@@ -125,7 +141,7 @@ export const Text = memo(function Text({
             <LineTag
               key={i}
               className={className}
-              dangerouslySetInnerHTML={{ __html: line }}
+              dangerouslySetInnerHTML={{ __html: resolve(line) }}
               {...props}
             />
           )

package/src/index.js

@@ -99,6 +99,9 @@ export {
   parseIconRef,
   // Content utilities
   splitContent,
+  // Prose href resolution (for foundations that render prose HTML themselves)
+  resolveProseHref,
+  resolveProseHrefs,
   // Runtime utilities (getChildBlockRenderer is internal — use ChildBlocks)
   getChildBlockRenderer,
   ChildBlocks,

package/src/utils/index.js

@@ -206,14 +206,36 @@ export function stripTags(html) {
  */
 export function isExternalUrl(url) {
   if (!url || typeof url !== 'string') return false
+
+  // Protocol-relative (//host/path) targets another authority by construction.
+  // Checked before the '/' test, which it would otherwise satisfy.
+  if (url.startsWith('//')) return true
+
+  // Site-root-relative paths and bare fragments are always internal
   if (url.startsWith('/') || url.startsWith('#')) return false
 
-  try {
-    const urlObj = new URL(url, window.location.origin)
-    return urlObj.origin !== window.location.origin
-  } catch {
-    return false
+  // Anything carrying a scheme (https:, mailto:, tel:, ...) is absolute.
+  if (/^[a-z][a-z0-9+.-]*:/i.test(url)) {
+    // In a browser we can compare origins, so a same-origin absolute URL is
+    // internal. Under SSR/prerender there is no origin to compare against —
+    // report external, which is both true in practice and the safe answer.
+    //
+    // This used to read window.location.origin unguarded. The ReferenceError
+    // was swallowed by the catch below, so during prerender EVERY url —
+    // including https://… — was reported internal, and callers that treat
+    // "internal" as "site-relative" then mangled it.
+    const origin = typeof window !== 'undefined' ? window.location?.origin : null
+    if (!origin) return true
+
+    try {
+      return new URL(url, origin).origin !== origin
+    } catch {
+      return true
+    }
   }
+
+  // Document-relative path (./x, x/y) — internal
+  return false
 }
 
 /**
@@ -243,6 +265,11 @@ export function isFileUrl(url) {
 
 export { splitContent } from './splitContent.js'
 
+// Prose href resolution — exported so a foundation rendering its own prose
+// HTML resolves authored hrefs the same way kit's <Text> and <SafeHtml> do,
+// rather than reinventing (and diverging from) it.
+export { resolveProseHref, resolveProseHrefs } from './prose-html.js'
+
 /**
  * Detect media type from URL
  * @param {string} url

package/src/utils/prose-html.js

@@ -0,0 +1,112 @@
+/**
+ * Prose HTML href resolution
+ *
+ * Inline formatting authored in markdown reaches components as an HTML string
+ * (semantic-parser bakes marks into the text — `<strong>`, `<em>`, `<a href>`).
+ * That string is rendered with dangerouslySetInnerHTML, so the anchors inside
+ * it never pass through kit's <Link> and get none of what <Link> does for a
+ * structured link.
+ *
+ * This module is the one place that closes that gap. An href authored in prose
+ * resolves exactly like the same href handed to <Link>, no matter which
+ * renderer draws it.
+ *
+ * WHY HERE, AND NOT IN THE PARSER
+ * semantic-parser is deliberately context-free — it has no website, no base
+ * path, no route table — and must stay that way, because @uniweb/press feeds
+ * the same strings into PDF, docx and typst output where a site's base path is
+ * meaningless. Resolution belongs at render, where the deployment context
+ * exists and where it can differ per target.
+ *
+ * WHY REGEX, AND NOT DOMParser
+ * The same code has to run in the browser and during SSR/prerender, where no
+ * DOM exists. A DOMParser-based resolver silently skipped resolution during
+ * prerender, which is the bug that motivated the regex rewrite in the first
+ * place.
+ *
+ * @module @uniweb/kit/utils/prose-html
+ */
+
+// An <a> tag's href attribute. Captures the prefix, the quote style, and the
+// value, so the replacement can preserve the original quoting.
+const ANCHOR_HREF_RE = /(<a\b[^>]*?\shref=)(["'])([^"']*)\2/gi
+
+// Schemes and shapes that are never site-relative and must be left untouched.
+const NON_ROUTE_HREF_RE = /^(?:[a-z][a-z0-9+.-]*:|\/\/|#)/i
+
+/**
+ * Prefix a site-root-relative href with the deployment base path.
+ *
+ * Mirrors what <Link> ends up doing for a structured link: React Router's
+ * basename supplies it during SPA navigation, and Link's SSG fallback and
+ * `reload` path prepend `website.basePath` explicitly.
+ *
+ * The invariant this encodes — a base is only ever joined to a path that
+ * starts at the site root — is the whole point of routing every caller
+ * through here. A bare `basePath + href` concatenation produces garbage the
+ * moment href turns out to be absolute (`/basehttps://example.com/x`), and
+ * whether it is absolute depends on a classification that has been wrong
+ * before. Guarding at the join makes the failure impossible rather than
+ * unlikely.
+ *
+ * @param {string} href - Href to prefix
+ * @param {string} basePath - Deployment base (no trailing slash), '' for root
+ * @returns {string} Href with the base applied, or unchanged if not applicable
+ */
+export function applyBasePath(href, basePath) {
+  if (!href || typeof href !== 'string' || !basePath) return href
+  if (!href.startsWith('/') || href.startsWith('//')) return href
+  if (href === basePath || href.startsWith(basePath + '/')) return href // already based
+  return basePath + href
+}
+
+/**
+ * Resolve a single authored href to the one that should reach the DOM.
+ *
+ * Order matters: an internal reference resolves to a route first, and the base
+ * path is applied to that route afterwards. A reference that cannot be
+ * resolved is returned by makeHref unchanged, still carrying its `page:`
+ * scheme — which the base step then correctly declines to touch.
+ *
+ * @param {string} href - Authored href
+ * @param {Object} website - Website instance
+ * @returns {string} Resolved href
+ */
+export function resolveProseHref(href, website) {
+  if (!href || !website) return href
+
+  let resolved = href
+
+  // page: / topic: internal references → real route
+  if (href.startsWith('page:') || href.startsWith('topic:')) {
+    resolved = website.makeHref ? website.makeHref(href) : href
+  }
+
+  // Anything still carrying a scheme, protocol-relative, or a bare fragment is
+  // not a site route — leave it alone.
+  if (NON_ROUTE_HREF_RE.test(resolved)) return resolved
+
+  return applyBasePath(resolved, website.basePath || '')
+}
+
+/**
+ * Resolve every anchor href inside a prose HTML string.
+ *
+ * @param {string} html - HTML string from semantic-parser
+ * @param {Object} website - Website instance (falsy → returns html unchanged)
+ * @returns {string} HTML with resolved hrefs
+ */
+export function resolveProseHrefs(html, website) {
+  if (!html || typeof html !== 'string' || !website) return html
+  if (!html.includes('<a')) return html
+
+  // Nothing to do when there are no internal references AND no base path to
+  // apply — the overwhelmingly common case for a site deployed at the root.
+  const hasRef = html.includes('page:') || html.includes('topic:')
+  if (!hasRef && !website.basePath) return html
+
+  return html.replace(ANCHOR_HREF_RE, (match, prefix, quote, href) => {
+    const resolved = resolveProseHref(href, website)
+    return resolved === href ? match : `${prefix}${quote}${resolved}${quote}`
+  })
+}