@uniweb/kit 0.9.25 → 0.9.27

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/kit",
-  "version": "0.9.25",
+  "version": "0.9.27",
   "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, resolveRoute } from '../../utils/href.js'
 
 /**
  * Social media platforms for auto-generating link titles
@@ -166,38 +167,24 @@ export function Link({
   reload,
   ...props
 }) {
-  const { website, localize, makeHref, getRoutingComponents } = useWebsite()
+  const { website, localize, getRoutingComponents } = useWebsite()
   const RouterLink = getRoutingComponents()?.Link
 
   // Normalize href
-  let linkHref = href || to || ''
+  const authoredHref = href || to || ''
 
-  // Handle internal reference protocols
-  // - topic: legacy internal reference
-  // - page: stable page reference (page:pageId#sectionId)
-  if (linkHref.startsWith('topic:') || linkHref.startsWith('page:')) {
-    linkHref = makeHref(linkHref)
-  }
-
-  // Add locale prefix for internal links in non-default locales
-  // Skip when reload is true — the caller provides a fully-resolved URL
-  // (e.g., getLocaleUrl() already includes the target locale prefix)
-  if (!reload && linkHref.startsWith('/') && !isExternalUrl(linkHref)) {
-    if (website?.hasMultipleLocales?.()) {
-      const activeLocale = website.getActiveLocale()
-      const defaultLocale = website.getDefaultLocale()
-      if (activeLocale && activeLocale !== defaultLocale) {
-        // Translate route slug for current locale (e.g., /about → /acerca-de)
-        if (website.translateRoute) {
-          linkHref = website.translateRoute(linkHref, activeLocale)
-        }
-        const prefix = `/${activeLocale}`
-        if (!linkHref.startsWith(`${prefix}/`) && linkHref !== prefix) {
-          linkHref = linkHref === '/' ? `${prefix}/` : `${prefix}${linkHref}`
-        }
-      }
-    }
-  }
+  // Resolve the authored href to a route: page:/topic: internal references,
+  // then slug translation and the locale prefix. Shared with prose rendering
+  // (utils/href.js) so a link written in markdown and a link passed to <Link>
+  // mean the same thing.
+  //
+  // `reload` opts out of the locale step only — its href comes from
+  // getLocaleUrl() and already carries the TARGET locale, which re-resolving
+  // against the ACTIVE one would clobber. Internal references still resolve.
+  //
+  // The base path is applied per-branch below, not here, because a
+  // Router-rendered link gets it from the router's basename instead.
+  const linkHref = resolveRoute(authoredHref, website, { locale: !reload })
 
   // Determine if this should be a download
   const isDownload = download || isFileUrl(linkHref)
@@ -214,7 +201,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"
@@ -225,11 +212,14 @@ export function Link({
     )
   }
 
-  // File downloads
+  // File downloads. A site-relative file lives under the deployment base like
+  // everything else, so the base applies here too — it used to be omitted,
+  // which broke every download link on a subdirectory deploy. applyBasePath
+  // leaves an absolute URL alone, so an off-site download is unaffected.
   if (isDownload) {
     return (
       <a
-        href={linkHref}
+        href={applyBasePath(linkHref, website?.basePath || '')}
         download
         target="_blank"
         rel="noopener noreferrer"
@@ -290,7 +280,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/href.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/href.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/href.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,11 @@ export {
   parseIconRef,
   // Content utilities
   splitContent,
+  // Href resolution (for foundations rendering their own links or prose HTML)
+  applyBasePath,
+  resolveRoute,
+  resolveHref,
+  resolveProseHrefs,
   // Runtime utilities (getChildBlockRenderer is internal — use ChildBlocks)
   getChildBlockRenderer,
   ChildBlocks,

package/src/utils/href.js

@@ -0,0 +1,170 @@
+/**
+ * Href resolution
+ *
+ * One implementation of what an authored href means, shared by every renderer
+ * that turns one into a real link.
+ *
+ * A link reaches the DOM by one of two routes, and they used to disagree:
+ *
+ *   structured — <Link to="/about">, where the component receives the href
+ *   prose      — an <a> baked into an HTML string by semantic-parser, rendered
+ *                with dangerouslySetInnerHTML, never passing through <Link>
+ *
+ * Both must apply the same rules, in the same order:
+ *
+ *   1. page: / topic: internal references resolve to a route
+ *   2. the route is translated and locale-prefixed for the active locale
+ *   3. the deployment base path is applied
+ *
+ * Steps 1-2 are `resolveRoute`. Step 3 is `applyBasePath`, kept separate
+ * because React Router supplies the base itself through its basename — a
+ * Router-rendered link must not have it applied twice. `resolveHref` is the
+ * whole chain, for every context where a plain <a> reaches the document.
+ *
+ * WHY HERE, AND NOT IN THE PARSER
+ * semantic-parser is deliberately context-free — 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 base path is meaningless.
+ * Resolution belongs at render, where the deployment context exists.
+ *
+ * WHY REGEX, AND NOT DOMParser
+ * The same code runs in the browser and during SSR/prerender, where no DOM
+ * exists. A DOMParser-based resolver silently skipped resolution during
+ * prerender — the bug that motivated the regex rewrite in the first place.
+ *
+ * @module @uniweb/kit/utils/href
+ */
+
+import { isFileUrl } from './url.js'
+
+// 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
+
+// Shapes that are never a site route: any scheme (https:, mailto:, tel:, and
+// an unresolved page:), protocol-relative, and bare fragments.
+const NON_ROUTE_HREF_RE = /^(?:[a-z][a-z0-9+.-]*:|\/\/|#)/i
+
+/**
+ * Prefix a site-root-relative href with the deployment base path.
+ *
+ * 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
+}
+
+/**
+ * Translate a route slug and prefix the active locale, when the site is
+ * multilingual and the active locale is not the default one.
+ */
+function applyLocale(route, website) {
+  if (!website.hasMultipleLocales?.()) return route
+
+  const activeLocale = website.getActiveLocale?.()
+  const defaultLocale = website.getDefaultLocale?.()
+  if (!activeLocale || activeLocale === defaultLocale) return route
+
+  // Translate the slug for this locale (e.g. /about → /acerca-de). A route
+  // with no translation comes back unchanged.
+  const translated = website.translateRoute ? website.translateRoute(route, activeLocale) : route
+
+  const prefix = `/${activeLocale}`
+  if (translated === prefix || translated.startsWith(`${prefix}/`)) return translated
+
+  return translated === '/' ? `${prefix}/` : `${prefix}${translated}`
+}
+
+/**
+ * Resolve an authored href to a site route: internal references, then locale.
+ * Does NOT apply the base path — see the module note on React Router.
+ *
+ * The locale step deliberately skips files. Only pages are emitted per locale;
+ * everything under the site's public directory — images, fonts, PDFs — is
+ * emitted once at the root, so locale-prefixing an asset href points it at a
+ * path that does not exist.
+ *
+ * @param {string} href - Authored href
+ * @param {Object} website - Website instance
+ * @param {Object} [options]
+ * @param {boolean} [options.locale=true] - Apply slug translation and the
+ *   locale prefix. Pass false when the caller already supplies a
+ *   locale-resolved URL — <Link reload>, whose href comes from getLocaleUrl()
+ *   and carries the TARGET locale, which re-resolving against the ACTIVE one
+ *   would clobber.
+ * @returns {string} Resolved route
+ */
+export function resolveRoute(href, website, { locale = true } = {}) {
+  if (!href || typeof href !== 'string' || !website) return href
+
+  let resolved = href
+
+  // 1. 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. An unresolvable page: reference lands here too, which is
+  // why makeHref returning it unchanged is safe.
+  if (NON_ROUTE_HREF_RE.test(resolved)) return resolved
+
+  // 2. Translate and locale-prefix — pages only
+  if (locale && resolved.startsWith('/') && !isFileUrl(resolved)) {
+    resolved = applyLocale(resolved, website)
+  }
+
+  return resolved
+}
+
+/**
+ * Resolve an authored href all the way to what belongs in a plain <a href>:
+ * internal references, locale, and the deployment base path.
+ *
+ * @param {string} href - Authored href
+ * @param {Object} website - Website instance
+ * @returns {string} Fully resolved href
+ */
+export function resolveHref(href, website) {
+  if (!href || typeof href !== 'string' || !website) return href
+  return applyBasePath(resolveRoute(href, website), 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, no base path and no
+  // active non-default locale — the common case for a monolingual site served
+  // at the root.
+  const hasRef = html.includes('page:') || html.includes('topic:')
+  const localized =
+    !!website.hasMultipleLocales?.() &&
+    website.getActiveLocale?.() !== website.getDefaultLocale?.()
+  if (!hasRef && !website.basePath && !localized) return html
+
+  return html.replace(ANCHOR_HREF_RE, (match, prefix, quote, href) => {
+    const resolved = resolveHref(href, website)
+    return resolved === href ? match : `${prefix}${quote}${resolved}${quote}`
+  })
+}

package/src/utils/index.js

@@ -199,43 +199,9 @@ export function stripTags(html) {
   return html.replace(/<[^>]*>/g, '')
 }
 
-/**
- * Check if a URL is external (different origin)
- * @param {string} url
- * @returns {boolean}
- */
-export function isExternalUrl(url) {
-  if (!url || typeof url !== 'string') return false
-  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
-  }
-}
-
-/**
- * Check if a URL points to a downloadable file
- * @param {string} url
- * @returns {boolean}
- */
-export function isFileUrl(url) {
-  if (!url || typeof url !== 'string') return false
-
-  const fileExtensions = [
-    '.pdf', '.doc', '.docx', '.xls', '.xlsx', '.ppt', '.pptx',
-    '.zip', '.rar', '.7z', '.tar', '.gz',
-    '.mp3', '.wav', '.ogg', '.flac',
-    '.mp4', '.avi', '.mov', '.wmv', '.webm',
-    '.jpg', '.jpeg', '.png', '.gif', '.svg', '.webp',
-    '.txt', '.csv', '.json', '.xml'
-  ]
-
-  const lowerUrl = url.toLowerCase()
-  return fileExtensions.some(ext => lowerUrl.includes(ext))
-}
+// URL predicates live in url.js so href.js can use them without importing
+// this barrel, which re-exports href.js in turn.
+export { isExternalUrl, isFileUrl } from './url.js'
 
 // ─────────────────────────────────────────────────────────────────
 // Content Utilities
@@ -243,6 +209,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 { applyBasePath, resolveRoute, resolveHref, resolveProseHrefs } from './href.js'
+
 /**
  * Detect media type from URL
  * @param {string} url

package/src/utils/url.js

@@ -0,0 +1,75 @@
+/**
+ * URL predicates
+ *
+ * Classification of an href, independent of any website or deployment. Kept in
+ * its own module so href.js can use it without importing the utils barrel,
+ * which re-exports href.js in turn.
+ *
+ * Both predicates must give the same answer in the browser and during
+ * SSR/prerender — the prerendered document and the hydrated DOM are meant to
+ * be the same document, and a classification that flips between them produces
+ * exactly the kind of corruption isExternalUrl once caused.
+ *
+ * @module @uniweb/kit/utils/url
+ */
+
+/**
+ * Check if a URL is external (different origin)
+ * @param {string} url
+ * @returns {boolean}
+ */
+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
+
+  // 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 a catch, so during prerender EVERY url — including
+    // https:// ones — 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
+}
+
+// Extensions that mark an href as a file rather than a page route.
+const FILE_EXTENSIONS = [
+  '.pdf', '.doc', '.docx', '.xls', '.xlsx', '.ppt', '.pptx',
+  '.zip', '.rar', '.7z', '.tar', '.gz',
+  '.mp3', '.wav', '.ogg', '.flac',
+  '.mp4', '.avi', '.mov', '.wmv', '.webm',
+  '.jpg', '.jpeg', '.png', '.gif', '.svg', '.webp',
+  '.txt', '.csv', '.json', '.xml'
+]
+
+/**
+ * Check if a URL points to a downloadable file
+ * @param {string} url
+ * @returns {boolean}
+ */
+export function isFileUrl(url) {
+  if (!url || typeof url !== 'string') return false
+
+  const lowerUrl = url.toLowerCase()
+  return FILE_EXTENSIONS.some(ext => lowerUrl.includes(ext))
+}