@uniweb/kit 0.10.6 → 0.10.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/kit",
-  "version": "0.10.6",
+  "version": "0.10.8",
   "description": "Standard component library for Uniweb foundations",
   "type": "module",
   "exports": {
@@ -43,8 +43,8 @@
     "shiki": "^3.0.0",
     "tailwind-merge": "^3.6.0",
     "@uniweb/core": "0.8.0",
-    "@uniweb/semantic-parser": "1.2.0",
-    "@uniweb/scene": "0.1.2"
+    "@uniweb/scene": "0.1.2",
+    "@uniweb/semantic-parser": "1.2.0"
   },
   "peerDependencies": {
     "react": "^19.0.0",

package/src/prose-tokens.css

@@ -97,8 +97,15 @@
 }
 
 /* Anchors land clear of a fixed site header when something scrolls to them —
-   a contents rail, or a link with a #fragment. */
-.prose :is(h1, h2, h3, h4) {
+   a contents rail, or a link with a #fragment.
+
+   Figures, tables and display math are on this list because they became anchor
+   targets: an authored `{#fig-cells}` is emitted onto the element, and a
+   cross-reference links to it. Without them a `[#eq-binomial]` scrolls its
+   equation flush to the viewport top and the sticky header covers it — which is
+   exactly what happened the first time the feature was clicked. Headings had
+   the rule and nothing else did, because until then nothing else was a target. */
+.prose :is(h1, h2, h3, h4, figure, table, .math-display) {
   scroll-margin-top: calc(var(--header-height, 4rem) + 1rem);
 }
 
@@ -129,3 +136,15 @@
 .tml-sml-pad { padding-left: 0.05em; }
 math mtd { padding-top: 0.5ex; padding-bottom: 0.5ex; }
 math mtable.tml-jot mtd { padding-top: 0.7ex; padding-bottom: 0.7ex; }
+
+/* AMS auto-numbering. Which equations number is the AUTHOR's choice, made in
+   LaTeX: `align` and `equation` number, `aligned` and the starred forms do not.
+   Without these two rules that choice was discarded -- `align` and `align*`
+   rendered identically, so an author who asked for numbers silently got none. */
+.tml-eqn::before {
+  counter-increment: tmlEqnNo;
+  content: "(" counter(tmlEqnNo) ")";
+}
+body {
+  counter-reset: tmlEqnNo;
+}

package/src/styled/Render/index.jsx

@@ -84,6 +84,23 @@ export const NOT_RENDERED = {
   'document-group': 'an editor node — its documents reach content.links',
 }
 
+/**
+ * The author's `{#id}`, if they wrote one.
+ *
+ * Reads the same two places the xref registry reads
+ * (`@uniweb/kit/xref/registry.js`), because an id that numbers a figure and an
+ * id that anchors it must be the same string — otherwise `[#fig-cells]` would
+ * resolve to "Figure 3" and link to nothing.
+ *
+ * Emitting it matters beyond cross-references: it is what makes
+ * `/page#fig-cells` land on the figure, and what gives EPUB and Paged.js real
+ * internal links. Until 2026-07-31 nothing emitted it, so an authored id
+ * existed only inside the registry and never reached the document.
+ */
+function authoredId(element) {
+  return element?.attrs?.id ?? element?.id ?? undefined
+}
+
 /**
  * Normalize whatever a caller passed into a sequence.
  *
@@ -213,7 +230,7 @@ export function SequenceElement({ element, block, components }) {
       // The id is the anchor `useHeadings()` and every in-page nav link
       // resolve against, so it is behaviour rather than decoration.
       return (
-        <Tag id={headingId(element.text || '')}>
+        <Tag id={authoredId(element) || headingId(element.text || '')}>
           <SafeHtml value={element.text} as="span" />
         </Tag>
       )
@@ -235,7 +252,7 @@ export function SequenceElement({ element, block, components }) {
       const { url, src, alt, caption, role } = element.attrs || {}
       if (role === 'icon') return <Icon {...element.attrs} />
       return (
-        <figure>
+        <figure id={authoredId(element)}>
           <Image src={url || src} alt={alt || caption || ''} />
           {caption && <figcaption>{caption}</figcaption>}
         </figure>
@@ -262,6 +279,7 @@ export function SequenceElement({ element, block, components }) {
       const Tag = display ? 'div' : 'span'
       return (
         <Tag
+          id={authoredId(element)}
           className={display ? 'math-display' : 'math-inline'}
           dangerouslySetInnerHTML={{ __html: element.mathml }}
         />
@@ -319,7 +337,7 @@ export function SequenceElement({ element, block, components }) {
       // reference table on a phone.
       return (
         <div className="overflow-x-auto">
-          <table>
+          <table id={authoredId(element)}>
             {hasHeader && <thead>{renderRow(first, 'h')}</thead>}
             <tbody>{(hasHeader ? rest : rows).map((row, i) => renderRow(row, i))}</tbody>
           </table>

package/src/xref/Ref.jsx

@@ -66,20 +66,39 @@ function renderEntry(entry, kindMeta) {
     return label ? `${label}${sep}${counter}` : counter
 }
 
+/** A counter as a link to the element it numbers. */
+function counterLink(entry) {
+    return (
+        <a key={entry.id} href={`#${entry.id}`}>
+            {entry.counterText}
+        </a>
+    )
+}
+
+/**
+ * Prose list punctuation: "1", "1 and 2", "1, 2, and 3".
+ *
+ * Takes and returns nodes rather than strings so each counter can be its own
+ * link. A cluster's LABEL is deliberately left outside them — "Figures" covers
+ * the whole group, and there is no single target it could point at.
+ */
+function joinProse(nodes) {
+    if (nodes.length <= 1) return nodes
+    if (nodes.length === 2) return [nodes[0], ' and ', nodes[1]]
+    const out = []
+    nodes.forEach((node, i) => {
+        if (i > 0) out.push(i === nodes.length - 1 ? ', and ' : ', ')
+        out.push(node)
+    })
+    return out
+}
+
 function renderGroupSameKind(entries, kindMeta) {
-    if (entries.length === 1) {
-        return renderEntry(entries[0], kindMeta)
-    }
-    const label = kindMeta?.labelPlural || kindMeta?.label || ''
+    const plural = entries.length > 1
+    const label = (plural ? kindMeta?.labelPlural || kindMeta?.label : kindMeta?.label) || ''
     const sep = kindMeta?.sep ?? ' '
-    const counters = entries.map((e) => e.counterText)
-    let body
-    if (counters.length === 2) {
-        body = counters.join(' and ')
-    } else {
-        body = counters.slice(0, -1).join(', ') + ', and ' + counters[counters.length - 1]
-    }
-    return label ? `${label}${sep}${body}` : body
+    const body = joinProse(entries.map(counterLink))
+    return label ? [label, sep, ...body] : body
 }
 
 export function Ref({ params, block }) {
@@ -119,24 +138,49 @@ export function Ref({ params, block }) {
                 `[xref] mixed-kind cluster (${[...new Set(allKinds)].join(', ')}) — falling back to comma-separated rendering`,
             )
         }
-        const parts = resolved.map((r) =>
-            r.missing ? `[?${r.id}]` : renderEntry(r.entry, r.kindMeta),
-        )
-        return <span className="xref">{parts.join(', ')}{locator}</span>
+        // Each kind keeps its own singular label, and each resolved part links
+        // to its own target. A missing one stays visible text.
+        const parts = []
+        resolved.forEach((r, i) => {
+            if (i > 0) parts.push(', ')
+            if (r.missing) {
+                parts.push(`[?${r.id}]`)
+                return
+            }
+            const label = r.kindMeta?.label || ''
+            const sep = r.kindMeta?.sep ?? ' '
+            if (label) parts.push(label, sep)
+            parts.push(counterLink(r.entry))
+        })
+        return <span className="xref">{parts}{locator}</span>
     }
 
     const onlyResolved = resolved.filter((r) => !r.missing)
-    const text = onlyResolved.length > 0
+
+    // The single case links the WHOLE reference — "Equation 1", label and all,
+    // is one phrase naming one thing, so the label belongs inside the link.
+    // A cluster cannot do that: "Figures 1 and 2" has one label over two
+    // targets, so there each counter is its own link and the label is plain.
+    if (onlyResolved.length === 1 && resolved.length === 1) {
+        const { entry, kindMeta } = onlyResolved[0]
+        return (
+            <a className="xref" href={`#${entry.id}`}>
+                {renderEntry(entry, kindMeta)}{locator}
+            </a>
+        )
+    }
+
+    const body = onlyResolved.length > 0
         ? renderGroupSameKind(
               onlyResolved.map((r) => r.entry),
               onlyResolved[0].kindMeta,
           )
-        : ''
+        : []
 
-    const missingTail = resolved.filter((r) => r.missing).map((r) => `[?${r.id}]`).join(', ')
-    const body = [text, missingTail].filter(Boolean).join(', ')
+    const missing = resolved.filter((r) => r.missing).map((r) => `[?${r.id}]`)
+    const parts = missing.length > 0 && body.length > 0 ? [...body, ', ', ...missing] : [...body, ...missing]
 
-    return <span className="xref">{body}{locator}</span>
+    return <span className="xref">{parts}{locator}</span>
 }
 
 export default Ref