@uniweb/kit 0.9.26 → 0.9.28

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/kit",
-  "version": "0.9.26",
+  "version": "0.9.28",
   "description": "Standard component library for Uniweb foundations",
   "type": "module",
   "exports": {
@@ -39,7 +39,7 @@
     "fuse.js": "^7.0.0",
     "shiki": "^3.0.0",
     "tailwind-merge": "^3.6.0",
-    "@uniweb/core": "0.7.21",
+    "@uniweb/core": "0.7.22",
     "@uniweb/scene": "0.1.2"
   },
   "peerDependencies": {

package/src/components/Link/Link.jsx

@@ -13,7 +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'
+import { applyBasePath, resolveRoute } from '../../utils/href.js'
 
 /**
  * Social media platforms for auto-generating link titles
@@ -167,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)
@@ -226,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"

package/src/components/SafeHtml/SafeHtml.jsx

@@ -6,7 +6,7 @@
  * 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
+ * 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
@@ -14,7 +14,7 @@
 
 import React, { Suspense, useMemo } from 'react'
 import { useWebsite } from '../../hooks/useWebsite.js'
-import { resolveProseHrefs } from '../../utils/prose-html.js'
+import { resolveProseHrefs } from '../../utils/href.js'
 
 /**
  * SafeHtml - Safely render HTML content

package/src/components/Text/Text.jsx

@@ -15,7 +15,7 @@
 
 import React, { memo } from 'react'
 import { cn } from '../../utils/index.js'
-import { resolveProseHrefs } from '../../utils/prose-html.js'
+import { resolveProseHrefs } from '../../utils/href.js'
 
 /**
  * Resolve authored hrefs in a prose string before it reaches the DOM.

package/src/index.js

@@ -99,8 +99,10 @@ export {
   parseIconRef,
   // Content utilities
   splitContent,
-  // Prose href resolution (for foundations that render prose HTML themselves)
-  resolveProseHref,
+  // Href resolution (for foundations rendering their own links or prose HTML)
+  applyBasePath,
+  resolveRoute,
+  resolveHref,
   resolveProseHrefs,
   // Runtime utilities (getChildBlockRenderer is internal — use ChildBlocks)
   getChildBlockRenderer,

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,65 +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
-
-  // 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 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
-}
-
-/**
- * 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
@@ -268,7 +212,7 @@ 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'
+export { applyBasePath, resolveRoute, resolveHref, resolveProseHrefs } from './href.js'
 
 /**
  * Detect media type from 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))
+}

package/src/utils/prose-html.js

@@ -1,112 +0,0 @@
-/**
- * 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}`
-  })
-}