@uniweb/press 0.4.15 → 0.4.16

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/press",
-  "version": "0.4.15",
+  "version": "0.4.16",
   "description": "Press your React components into downloadable files — Word, Excel, PDF. Registration-based pattern with lazy-loaded format adapters.",
   "type": "module",
   "exports": {

package/src/docx/Link.jsx

@@ -1,11 +1,13 @@
 /**
  * Link component for document output.
  *
- * Auto-detects external (http) vs internal (anchor) hyperlinks.
+ * Emits an in-document anchor for a `#fragment` and a destination for
+ * everything else. See `classifyHref` for why that is the whole rule.
  *
  * @param {Object} props
  * @param {Object} props.data - Link data: { label, href }
  */
+import { classifyHref } from './classifyHref.js'
 
 export default function Link({ data, ...props }) {
     if (!data) return null
@@ -14,18 +16,11 @@ export default function Link({ data, ...props }) {
 
     if (!href) return null
 
-    const isExternal = href.startsWith('http')
+    const { anchor } = classifyHref(href)
 
-    if (isExternal) {
+    if (anchor !== null) {
         return (
-            <a
-                data-type="externalHyperlink"
-                data-link={href}
-                href={href}
-                target="_blank"
-                rel="noopener noreferrer"
-                {...props}
-            >
+            <a data-type="internalHyperlink" data-anchor={anchor} href={href} {...props}>
                 <span data-type="text" data-style="Hyperlink">
                     {label || href}
                 </span>
@@ -33,15 +28,20 @@ export default function Link({ data, ...props }) {
         )
     }
 
-    // The IR's anchor is a BARE bookmark name — `data-bookmark="x"` becomes
-    // `<w:bookmarkStart w:name="x"/>` — so a documented `href: '#section-3'`
-    // has to lose its '#' or `w:anchor="#section-3"` never matches
-    // `w:name="section-3"` and Word resolves nothing. `href` keeps the
-    // fragment form, which is what the browser preview needs.
-    const anchor = href.startsWith('#') ? href.slice(1) : href
+    // `target`/`rel` only affect the React preview, never the compiled
+    // document, so they stay on the narrower http test they have always
+    // used — opening a mailto: or a site path in a new tab is not what
+    // this component previously did and is not what this change is about.
+    const offSite = href.startsWith('http')
 
     return (
-        <a data-type="internalHyperlink" data-anchor={anchor} href={href} {...props}>
+        <a
+            data-type="externalHyperlink"
+            data-link={href}
+            href={href}
+            {...(offSite ? { target: '_blank', rel: 'noopener noreferrer' } : {})}
+            {...props}
+        >
             <span data-type="text" data-style="Hyperlink">
                 {label || href}
             </span>

package/src/docx/LinkPart.jsx

@@ -13,6 +13,7 @@
  * in-document anchor the same way (see below).
  */
 import TextRun from './TextRun.jsx'
+import { classifyHref } from './classifyHref.js'
 
 /** `parts` is absent only for a hand-built part; fall back to the label. */
 export function labelRuns(part) {
@@ -22,15 +23,15 @@ export function labelRuns(part) {
 export default function LinkPart({ part }) {
     const href = part.href || ''
 
-    // An href starting with '#' is an in-document anchor, not a destination.
-    // Emitting it as an external hyperlink produced a relationship to the
-    // literal '#id' and no jump at all. The IR's anchor is a BARE bookmark
-    // name — `data-bookmark="x"` becomes `<w:bookmarkStart w:name="x"/>` — so
-    // the '#' is dropped here rather than shipped into `w:anchor`.
-    const anchor = href.startsWith('#') ? href.slice(1) : null
-    const linkAttrs = anchor
-        ? { 'data-type': 'internalHyperlink', 'data-anchor': anchor }
-        : { 'data-type': 'externalHyperlink', 'data-link': href }
+    // Same rule as the <Link> builder, from the same module rather than a
+    // second copy of the condition — the two used to classify the same href
+    // differently, which is what let `mailto:` compile to a dead anchor on
+    // one path and a working link on the other.
+    const { anchor } = classifyHref(href)
+    const linkAttrs =
+        anchor !== null
+            ? { 'data-type': 'internalHyperlink', 'data-anchor': anchor }
+            : { 'data-type': 'externalHyperlink', 'data-link': href }
 
     return (
         <a {...linkAttrs} href={href}>

package/src/docx/classifyHref.js

@@ -0,0 +1,61 @@
+/**
+ * Decide what SHAPE a link takes in the compiled document. INTERNAL helper —
+ * not in the barrel.
+ *
+ * The whole rule: **a `#fragment` is an in-document anchor; everything else is
+ * a destination, emitted verbatim.**
+ *
+ * ## Why that is the whole rule
+ *
+ * A fragment means "within this document" in every hypertext format, so this
+ * is the one classification Press can make from the href alone without knowing
+ * anything about the caller. Everything else — `https://…`, `mailto:…`,
+ * `/about`, `../sibling`, `page:installation` — is a destination Press has no
+ * standing to interpret.
+ *
+ * What this replaced was a guess: `href.startsWith('http')` treated everything
+ * else as an in-document anchor, so `mailto:a@b.com` and `/about` compiled to
+ * `<w:hyperlink w:anchor="mailto:a@b.com">` — a reference to a bookmark that
+ * cannot exist. That does not merely fail to navigate: **an anchor name is not
+ * a URL, so the destination is destroyed** and nothing downstream can recover
+ * it. Emitting it as a destination keeps it in the file, where a wrong link is
+ * at least visible and diagnosable.
+ *
+ * ## Why a bare name is NOT accepted as an anchor
+ *
+ * `section-3` and `page.html` are indistinguishable. Any rule that reads a bare
+ * token as a bookmark name necessarily turns some page links into dead anchors
+ * — which is the bug above. `#` is the disambiguator; that is what fragments
+ * are for. An author writes `#section-3`.
+ *
+ * ## Resolution is NOT Press's job
+ *
+ * Press does not know what `page:installation` means and must not learn. That
+ * is the same boundary the LaTeX inset helpers state for cite keys and xref
+ * ids — *"Resolution stays foundation-side … the foundation passes
+ * already-resolved keys in; Press's job is the emission shape"* — and the same
+ * one `DocumentProvider` states for `basePath` (*"Press itself has no awareness
+ * of the host runtime"*). Press declares no `@uniweb/*` dependency, and
+ * resolving a framework reference here would mean duplicating a resolver that
+ * lives in the runtime, which is how two implementations drift apart.
+ *
+ * So an unresolved `page:` reference compiles to a link pointing at the literal
+ * string. That is intended: it is the caller's unresolved input, preserved
+ * rather than swallowed. Callers compiling Uniweb content resolve authored
+ * hrefs before handing strings to the builders.
+ *
+ * @param {string} href
+ * @returns {{ anchor: string | null }} `anchor` is the bare bookmark name for
+ *   an in-document reference, or null when the href is a destination.
+ */
+export function classifyHref(href) {
+    if (!href || typeof href !== 'string') return { anchor: null }
+
+    // The bookmark name carries no '#'. A paragraph's `data-bookmark="x"`
+    // becomes `<w:bookmarkStart w:name="x"/>`, and Word matches
+    // `<w:hyperlink w:anchor="x">` against that name, so the fragment marker
+    // has to come off or the two never meet.
+    if (href.startsWith('#')) return { anchor: href.slice(1) }
+
+    return { anchor: null }
+}