@asd20/ui-next 2.30.0 → 2.31.0

package/src/components/templates/Asd20HandbookTemplate/index.vue

@@ -1,8 +1,12 @@
 <template>
-  <div class="asd20-template-handbook">
+  <div
+    class="asd20-template-handbook"
+    :data-asd20-document-root="documentPrint ? publicationDocumentId : undefined"
+  >
     <asd20-skip-to to="#handbook-content" />
 
     <asd20-site-navigation
+      :data-asd20-print-hide="documentPrint ? '' : undefined"
       v-bind="siteNavigationSearchProps"
       :navigation="navigation"
       :action-items="actionItems"
@@ -15,6 +19,7 @@
     />
 
     <asd20-notification-group
+      :data-asd20-print-hide="documentPrint ? '' : undefined"
       :notifications="activeNotificationsByType.banner"
       group-type="banner"
       @dismiss="$emit('dismiss-notification', $event)"
@@ -42,7 +47,18 @@
       </template>
     </asd20-page-header>
 
+    <slot name="document-actions" />
+
+    <asd20-print-header
+      v-if="documentPrint"
+      :organization-title="organization?.title || organization?.name || ''"
+      :canonical-url="publicationDocumentUrl"
+      v-bind="printMetadata"
+      title=""
+    />
+
     <asd20-notification-group
+      :data-asd20-print-hide="documentPrint ? '' : undefined"
       :notifications="activeNotificationsByType.inline"
       group-type="inline"
       @dismiss="$emit('dismiss-notification', $event)"
@@ -67,34 +83,34 @@
         >
           Topics
         </button>
-        <h2 class="asd20-template-handbook__index-heading">
+        <div class="asd20-template-handbook__index-heading">
           Topics
-        </h2>
+        </div>
         <ol
           id="handbook-topics"
           :class="{ 'is-open': topicsOpen }"
         >
           <li
-            v-for="message in topicMessages"
-            :key="message.id"
+            v-for="entry in topicEntries"
+            :key="entry.key"
           >
             <div class="asd20-template-handbook__topic-row">
               <button
                 class="asd20-template-handbook__topic-button"
                 type="button"
-                :aria-current="activeMessage && activeMessage.id === message.id ? 'true' : null"
-                @click="selectTopic(message.id)"
+                :aria-current="activeEntry && activeEntry.key === entry.key ? 'true' : null"
+                @click="selectTopic(entry.key)"
               >
-                {{ message.heading || message.title }}
+                {{ entry.message.heading || entry.message.title }}
               </button>
               <button
-                v-if="subtopicsFor(message.id).length"
+                v-if="subtopicsFor(entry.key).length"
                 class="asd20-template-handbook__expand-button"
                 type="button"
-                :aria-expanded="expandedTopicId === message.id"
-                :aria-controls="`handbook-subtopics-${message.id}`"
-                :aria-label="`${expandedTopicId === message.id ? 'Hide' : 'Show'} sections in ${message.heading || message.title}`"
-                @click="toggleTopic(message.id)"
+                :aria-expanded="expandedTopicId === entry.key"
+                :aria-controls="entry.subtopicsId"
+                :aria-label="`${expandedTopicId === entry.key ? 'Hide' : 'Show'} sections in ${entry.message.heading || entry.message.title}`"
+                @click="toggleTopic(entry.key)"
               >
                 <asd20-icon
                   name="chevron"
@@ -104,19 +120,19 @@
               </button>
             </div>
             <ol
-              v-if="subtopicsFor(message.id).length"
-              v-show="expandedTopicId === message.id"
-              :id="`handbook-subtopics-${message.id}`"
+              v-if="subtopicsFor(entry.key).length"
+              v-show="expandedTopicId === entry.key"
+              :id="entry.subtopicsId"
               class="asd20-template-handbook__subtopics"
             >
               <li
-                v-for="subtopic in subtopicsFor(message.id)"
-                :key="subtopic.index"
+                v-for="subtopic in subtopicsFor(entry.key)"
+                :key="subtopic.id"
               >
                 <button
                   class="asd20-template-handbook__subtopic-button"
                   type="button"
-                  @click="selectSubtopic(message.id, subtopic.index)"
+                  @click="selectSubtopic(entry.key, subtopic.id)"
                 >
                   {{ subtopic.label }}
                 </button>
@@ -126,30 +142,46 @@
         </ol>
       </nav>
 
+      <p
+        v-if="publicationDiagnostics.length"
+        class="asd20-template-handbook__publication-review"
+        role="status"
+      >
+        This handbook has content that needs publication review before PDF export.
+      </p>
+
+      <asd20-print-contents
+        v-if="documentPrint"
+        :headings="printHeadings"
+      />
+
       <article
-        v-for="message in topicMessages"
-        :key="message.id"
-        :data-message-id="message.id"
+        v-for="entry in topicEntries"
+        :key="entry.key"
+        :data-message-id="entry.message.id"
+        :data-topic-key="entry.key"
         class="asd20-template-handbook__topic"
-        :class="{ 'is-active': activeMessage && activeMessage.id === message.id }"
+        :class="{ 'is-active': activeEntry && activeEntry.key === entry.key }"
       >
-        <h2>
-          {{ message.heading || message.title }}
+        <h2 :id="entry.titleId">
+          {{ entry.message.heading || entry.message.title }}
         </h2>
         <div
-          v-if="topicSummary(message)"
+          v-if="topicSummary(entry.message)"
           class="asd20-template-handbook__summary"
-          v-html="topicSummary(message)"
+          v-html="topicSummary(entry.message)"
         />
         <hr
-          v-if="topicSummary(message)"
+          v-if="topicSummary(entry.message)"
           class="asd20-template-handbook__summary-divider"
         />
         <asd20-messaging
-          v-bind="message"
+          v-bind="entry.message"
           heading=""
           short-description=""
           detail-link=""
+          :heading-level-offset="1"
+          :heading-id-prefix="entry.key"
         />
       </article>
       <p v-if="!topicMessages.length">
@@ -177,7 +209,12 @@ import Asd20SiteNavigation from '../../../components/organisms/Asd20SiteNavigati
 import Asd20NotificationGroup from '../../../components/organisms/Asd20NotificationGroup'
 import Asd20QuicklinksMenu from '../../../components/organisms/Asd20QuicklinksMenu'
 import Asd20PageFooter from '../../../components/organisms/Asd20PageFooter'
+import Asd20PrintHeader from '../../molecules/Asd20PrintHeader'
+import Asd20PrintContents from '../../molecules/Asd20PrintContents'
+import { buildHandbookDocument } from '../../../helpers/handbookDocument'
+import { installDocumentPrintLifecycle } from '../../../helpers/documentPrint'
 import pageTemplateMixin from '../../../mixins/pageTemplateMixin'
+import { publicationHeadingPlanKey } from '../../atoms/Asd20RichBodyContent/headingContext'
 
 export default {
   name: 'Asd20HandbookTemplate',
@@ -190,63 +227,71 @@ export default {
     Asd20NotificationGroup,
     Asd20QuicklinksMenu,
     Asd20PageFooter,
+    Asd20PrintHeader,
+    Asd20PrintContents,
   },
   mixins: [pageTemplateMixin],
+  provide() {
+    return { [publicationHeadingPlanKey]: () => this.publicationHeadings.idPlan }
+  },
+  props: {
+    documentPrint: { type: Boolean, default: false },
+    printMetadata: { type: Object, default: () => ({}) },
+    publicationDocumentId: { type: String, default: 'handbook' },
+    publicationDocumentUrl: { type: String, default: '' },
+    publicationReservedIds: { type: Array, default: () => [] },
+  },
   data: () => ({
     selectedMessageId: null,
     expandedTopicId: null,
-    subtopicsByMessageId: {},
     topicsOpen: false,
   }),
   computed: {
-    handbookLead() {
-      return this.firstMessage?.shortDescription || this.firstMessage?.summary || this.metaDescription
+    handbookDocument() {
+      return buildHandbookDocument({
+        messages: this.messages, metaDescription: this.metaDescription,
+        documentId: this.publicationDocumentId, documentUrl: this.publicationDocumentUrl,
+        reservedIds: this.publicationReservedIds,
+      })
     },
-    topicMessages() {
-      return this.messages.slice(1)
+    introduction() { return this.handbookDocument.introduction },
+    publicationDiagnostics() { return this.handbookDocument.diagnostics },
+    printHeadings() { return this.handbookDocument.headings },
+    handbookLead() { return this.introduction.lead },
+    topicMessages() { return this.messages.slice(1) },
+    topicEntries() { return this.handbookDocument.entries },
+    publicationHeadings() { return this.handbookDocument.headingModels },
+    activeEntry() {
+      return this.topicEntries.find(entry => entry.key === this.selectedMessageId)
+        || this.topicEntries[0] || null
     },
     activeMessage() {
-      return this.topicMessages.find(message => message.id === this.selectedMessageId)
-        || this.topicMessages[0]
-        || null
+      return this.activeEntry?.message || null
     },
   },
   watch: {
-    messages: {
-      handler() {
-        this.$nextTick(() => this.refreshSubtopics())
-      },
-      deep: true,
-    },
-  },
-  mounted() {
-    this.$nextTick(() => this.refreshSubtopics())
+    documentPrint() { this.updatePrintLifecycle() },
+    messages: { deep: true, handler() { this.updatePrintLifecycle() } },
+    publicationDocumentId() { this.updatePrintLifecycle() },
   },
+  mounted() { this.updatePrintLifecycle() },
+  beforeUnmount() { this.stopPrintLifecycle?.() },
   methods: {
+    updatePrintLifecycle() {
+      this.stopPrintLifecycle?.()
+      this.stopPrintLifecycle = this.documentPrint ? installDocumentPrintLifecycle(this.$el) : null
+    },
     topicSummary(message) {
       return message.shortDescription || message.summary || ''
     },
-    topicArticle(messageId) {
+    topicArticle(topicKey) {
       return Array.from(this.$el.querySelectorAll('.asd20-template-handbook__topic'))
-        .find(article => article.dataset.messageId === String(messageId))
+        .find(article => article.dataset.topicKey === topicKey)
     },
-    subtopicsFor(messageId) {
-      return this.subtopicsByMessageId[messageId] || []
-    },
-    refreshSubtopics() {
-      const nextSubtopics = {}
-      this.topicMessages.forEach(message => {
-        const article = this.topicArticle(message.id)
-        if (!article) return
-        const headings = Array.from(article.querySelectorAll('.asd20-rich-body-content h2'))
-        const subtopics = headings
-          .map((heading, index) => ({ index, label: heading.textContent.trim() }))
-          .filter(subtopic => subtopic.label)
-        if (subtopics.length) nextSubtopics[message.id] = subtopics
-      })
-      if (JSON.stringify(nextSubtopics) !== JSON.stringify(this.subtopicsByMessageId)) {
-        this.subtopicsByMessageId = nextSubtopics
-      }
+    subtopicsFor(topicKey) {
+      const index = this.topicEntries.findIndex(entry => entry.key === topicKey)
+      return this.publicationHeadings.models[index]?.headings
+        .filter(heading => heading.authoredLevel === 2 && heading.label) || []
     },
     toggleTopic(messageId) {
       this.expandedTopicId = this.expandedTopicId === messageId ? null : messageId
@@ -258,14 +303,21 @@ export default {
       await this.$nextTick()
       this.topicArticle(messageId)?.scrollIntoView({ block: 'start' })
     },
-    async selectSubtopic(messageId, headingIndex) {
+    async selectSubtopic(messageId, headingId) {
       this.selectedMessageId = messageId
       this.expandedTopicId = messageId
       this.topicsOpen = false
       await this.$nextTick()
       const article = this.topicArticle(messageId)
-      const headings = article?.querySelectorAll('.asd20-rich-body-content h2')
-      headings?.[headingIndex]?.scrollIntoView({ block: 'start' })
+      const heading = Array.from(article?.querySelectorAll('[id]') || [])
+        .find(element => element.id === headingId)
+      const toggle = heading?.closest('.asd20-accordion')
+        ?.querySelector('[aria-expanded="false"][aria-controls]')
+      if (toggle) {
+        toggle.click()
+        await this.$nextTick()
+      }
+      heading?.scrollIntoView({ block: 'start' })
     },
   },
 }
@@ -411,7 +463,7 @@ export default {
     scroll-margin-top: space(2);
   }
 
-  &__topic .asd20-rich-body-content h2 {
+  &__topic .asd20-rich-body-content h3 {
     scroll-margin-top: space(2);
   }
 

package/src/design/_document-print.scss

@@ -0,0 +1,104 @@
+// Additive overrides: every content rule requires BOTH markers. The legacy
+// _print.scss rules remain intact, including its existing unnamed page margin.
+@media print {
+  @page asd20-document {
+    size: letter portrait;
+    margin: 0.5in;
+    @bottom-center {
+      content: 'Page ' counter(page) ' of ' counter(pages);
+      font-family: Arial, sans-serif;
+      font-size: 9pt;
+      color: #111;
+    }
+  }
+
+  html[data-asd20-print-profile='document'] [data-asd20-document-root] {
+    page: asd20-document;
+    display: block !important;
+    color: #111 !important;
+    font-size: 10pt !important;
+    line-height: 1.45 !important;
+    print-color-adjust: exact;
+    -webkit-print-color-adjust: exact;
+
+    [data-asd20-print-hide], .asd20-print-hide,
+    .asd20-template-handbook__index, .asd20-accordion__header button,
+    .asd20-accordion__header .asd20-badge,
+    .asd20-message-video__frame, .asd20-tableau-embed__frame,
+    iframe, video, tableau-viz {
+      display: none !important;
+    }
+
+    .asd20-print-only { display: block !important; }
+    .asd20-print-contents__label { font-weight: bold; }
+    .asd20-print-contents li { break-inside: avoid; }
+    .asd20-print-contents ol { list-style: none; margin-left: 0; padding-left: 0; }
+    .asd20-print-contents a { display: flex; justify-content: space-between; gap: 1em; }
+    .asd20-print-contents__page { flex: 0 0 5ch; text-align: right; font-variant-numeric: tabular-nums; }
+    .asd20-handbook-document > header h1 { margin-top: 0 !important; }
+
+    .asd20-template-handbook__layout,
+    .asd20-template-handbook__topic,
+    .asd20-messaging, .asd20-messaging__content,
+    .asd20-accordion__content, .asd20-accordion__content-inner,
+    .asd20-accordion__viewport, .tableWrapper {
+      display: block !important;
+      position: static !important;
+      overflow: visible !important;
+      transform: none !important;
+      height: auto !important;
+      max-height: none !important;
+      min-height: 0 !important;
+      opacity: 1 !important;
+      break-inside: auto !important;
+      transition: none !important;
+    }
+
+    .asd20-template-handbook__topic { margin: 1.5rem 0 !important; }
+    h1, h2, h3, h4, h5, h6, caption, .asd20-accordion__header {
+      break-after: avoid-page;
+      break-inside: avoid-page;
+    }
+    p { orphans: 3; widows: 3; }
+    blockquote { break-inside: auto; }
+    .asd20-print-keep { break-inside: avoid-page !important; }
+    .asd20-print-break-before { break-before: page; }
+
+    img, .message-image {
+      display: block !important;
+      max-width: 100% !important;
+      height: auto !important;
+      object-fit: contain !important;
+      break-inside: avoid-page;
+    }
+    .asd20-message-image-gallery__images {
+      display: block !important;
+      overflow: visible !important;
+      max-height: none !important;
+    }
+    .asd20-message-image-gallery__images > img { max-width: 100% !important; max-height: none !important; }
+    table {
+      width: 100% !important;
+      min-width: 0 !important;
+      table-layout: fixed;
+      border-collapse: collapse;
+      break-inside: auto;
+      font-size: 9pt;
+    }
+    thead { display: table-header-group; }
+    tfoot { display: table-footer-group; }
+    tr { break-inside: avoid-page; }
+    th, td { min-width: 0 !important; overflow-wrap: anywhere; padding: 0.3em !important; border: 1px solid #888; }
+    th { background: #eee !important; color: #111 !important; }
+    a { overflow-wrap: anywhere; text-decoration: underline !important; break-inside: auto; }
+    a[href='/'] { display: inline !important; }
+    a::after { content: none !important; display: none !important; }
+    a[data-asd20-print-source]::after {
+      content: ' (' attr(data-asd20-print-source) ')' !important;
+      display: inline !important;
+      font-size: 9pt;
+    }
+    pre { white-space: pre-wrap; overflow-wrap: anywhere; }
+    ul, ol { columns: auto !important; }
+  }
+}

package/src/design/_print.scss

@@ -1,3 +1,5 @@
+@use './document-print';
+
   @media print {
     @page {
       margin: 0.5in;

package/src/helpers/documentPrint.js

@@ -0,0 +1,184 @@
+import { nextTick } from 'vue'
+
+const blocks = new WeakMap()
+const sessions = new WeakMap()
+
+// Component registration is private; preparation is reusable by any opted-in host.
+export function registerDocumentPrintBlock(element, prepare) {
+  blocks.set(element, prepare)
+  return () => blocks.delete(element)
+}
+
+function setTemporaryAttribute(element, name, value, undo) {
+  const prior = element.getAttribute(name)
+  undo.push(() => prior === null ? element.removeAttribute(name) : element.setAttribute(name, prior))
+  value === null ? element.removeAttribute(name) : element.setAttribute(name, value)
+}
+
+function prepareTables(root, undo, diagnostics) {
+  for (const table of root.querySelectorAll('table')) {
+    if (table.tHead || !table.tBodies.length) continue
+    const body = table.tBodies[0]
+    const rows = []
+    // A column header group is a contiguous leading run of all-TH rows. Row
+    // headers/mixed cells stay in tbody; never infer headers from bold styling.
+    for (const row of body.rows) {
+      if (!row.cells.length || !Array.from(row.cells).every(cell => cell.tagName === 'TH' &&
+        !['row', 'rowgroup'].includes(cell.getAttribute('scope')))) break
+      rows.push(row)
+    }
+    if (!rows.length) continue
+    if (rows.some((row, index) => Array.from(row.cells).some(cell => cell.rowSpan === 0 || cell.rowSpan + index > rows.length))) {
+      diagnostics.push({ code: 'table-header-span-unmapped' })
+      continue
+    }
+    const following = rows.at(-1).nextSibling
+    const head = table.ownerDocument.createElement('thead')
+    body.before(head)
+    rows.forEach(row => head.append(row))
+    undo.push(() => { rows.forEach(row => body.insertBefore(row, following)); head.remove() })
+    for (const row of rows) for (const cell of row.cells) {
+      if (!cell.hasAttribute('scope')) setTemporaryAttribute(cell, 'scope', cell.colSpan > 1 ? 'colgroup' : 'col', undo)
+    }
+  }
+}
+
+function prepareEmbeds(root, undo, diagnostics) {
+  const doc = root.ownerDocument
+  for (const embed of root.querySelectorAll('.asd20-message-video, .asd20-tableau-embed')) {
+    const video = embed.classList.contains('asd20-message-video')
+    const source = video ? embed.dataset.src || embed.querySelector('iframe')?.src : embed.dataset.printSrc
+    const description = video ? embed.dataset.descriptiveText || embed.querySelector('.asd20-message-video__description')?.textContent :
+      embed.querySelector('.asd20-tableau-embed__description')?.textContent
+    const title = video ? embed.dataset.title || embed.querySelector('iframe')?.title : 'Interactive data visualization'
+    const alternative = doc.createElement('div')
+    alternative.className = 'asd20-print-only asd20-print-embed-alternative'
+    const text = doc.createElement('p')
+    text.textContent = `${video ? 'Video' : 'Interactive data'}: ${title || 'Untitled'}. ${description ? '' : 'A descriptive text alternative has not been supplied.'}`
+    alternative.append(text)
+    if (!description?.trim()) diagnostics.push({ code: 'embed-description-missing', source: source || '' })
+    let url
+    try { url = new URL(source) } catch { /* Report a missing safe source below. */ }
+    if (url && ['https:', 'http:'].includes(url.protocol)) {
+      const link = doc.createElement('a')
+      link.href = url.href
+      link.textContent = `${video ? 'Watch video' : 'View interactive data'}: ${url.href}`
+      alternative.append(link)
+    } else diagnostics.push({ code: 'embed-source-missing' })
+    embed.append(alternative)
+    undo.push(() => alternative.remove())
+  }
+  for (const iframe of root.querySelectorAll('iframe')) {
+    if (!iframe.closest('.asd20-message-video, .asd20-tableau-embed')) diagnostics.push({ code: 'embed-alternative-unmapped', source: iframe.src })
+  }
+}
+
+function beginDocumentPrint(root) {
+  if (!root?.hasAttribute('data-asd20-document-root')) throw new TypeError('Document printing requires an explicit document root.')
+  const doc = root.ownerDocument
+  if (sessions.has(doc)) throw new Error('A document print session is already active.')
+  const undo = []
+  const diagnostics = []
+  const session = { diagnostics, restore() {
+    if (sessions.get(doc) !== session) return
+    sessions.delete(doc)
+    undo.reverse().forEach(restore => restore())
+  } }
+  sessions.set(doc, session)
+  try {
+    setTemporaryAttribute(doc.documentElement, 'data-asd20-print-profile', 'document', undo)
+    setTemporaryAttribute(root, 'data-asd20-print-prepared', '', undo)
+    for (const stamp of root.querySelectorAll('[data-asd20-print-generated-at]')) {
+      if (stamp.hasAttribute('data-asd20-print-fixed-generated-at')) continue
+      const prior = stamp.textContent
+      stamp.textContent = `Generated: ${new Intl.DateTimeFormat('en-US', {
+        timeZone: 'America/Denver', dateStyle: 'medium', timeStyle: 'long',
+      }).format(new Date())}`
+      undo.push(() => { stamp.textContent = prior })
+    }
+    for (const element of [root, ...root.querySelectorAll('*')]) {
+      const prepare = blocks.get(element)
+      if (prepare) undo.push(prepare())
+    }
+    prepareTables(root, undo, diagnostics)
+    prepareEmbeds(root, undo, diagnostics)
+    if (root.querySelector('[data-cc-block]')) diagnostics.push({ code: 'rich-block-unresolved' })
+    for (const link of root.querySelectorAll('a[href]')) {
+      const href = link.getAttribute('href')
+      if (!href || href.startsWith('#') || link.closest('.asd20-print-contents') || link.hasAttribute('data-asd20-print-no-url')) continue
+      const url = new URL(href, doc.baseURI)
+      if (!['https:', 'http:'].includes(url.protocol) || link.textContent.includes(url.href)) continue
+      setTemporaryAttribute(link, 'data-asd20-print-source', url.href, undo)
+    }
+    for (const image of root.querySelectorAll('img')) setTemporaryAttribute(image, 'loading', 'eager', undo)
+    return session
+  } catch (error) { session.restore(); throw error }
+}
+
+async function waitForAssets(root) {
+  await nextTick() // Includes legacy rich-block enhancement and print state updates.
+  const doc = root.ownerDocument
+  if (doc.fonts) {
+    await doc.fonts.ready
+    if (Array.from(doc.fonts).some(font => font.status === 'error')) throw new Error('A document font failed to load.')
+  }
+  await Promise.all(Array.from(root.querySelectorAll('img')).filter(image => !image.closest('[data-asd20-print-hide], .asd20-print-hide')).map(async image => {
+    if (typeof image.decode === 'function') await image.decode()
+    else if (!image.complete) await new Promise((resolve, reject) => {
+      image.addEventListener('load', resolve, { once: true })
+      image.addEventListener('error', reject, { once: true })
+    })
+    if (!image.naturalWidth) throw new Error(`A document image failed to load: ${image.getAttribute('src')}`)
+  }))
+}
+
+export async function prepareDocumentPrint(root, { timeoutMs = 15000 } = {}) {
+  await nextTick()
+  const session = beginDocumentPrint(root)
+  let timer
+  try {
+    await Promise.race([waitForAssets(root), new Promise((_resolve, reject) => {
+      timer = setTimeout(() => reject(new Error('Document asset readiness timed out.')), timeoutMs)
+    })])
+    if (!root.isConnected || sessions.get(root.ownerDocument) !== session) throw new Error('Document print preparation was cancelled.')
+    return session
+  } catch (error) { session.restore(); throw error }
+  finally { clearTimeout(timer) }
+}
+
+export async function printDocument(root, options) {
+  const session = await prepareDocumentPrint(root, options)
+  const win = root.ownerDocument.defaultView
+  let onAfterPrint
+  try {
+    const finished = new Promise(resolve => {
+      onAfterPrint = resolve
+      win.addEventListener('afterprint', onAfterPrint, { once: true })
+    })
+    win.print()
+    await finished
+  } finally {
+    win.removeEventListener('afterprint', onAfterPrint)
+    session.restore()
+  }
+  return session.diagnostics
+}
+
+// Native beforeprint cannot await fonts/images. It synchronously expands semantic
+// blocks; controlled capture and the host's Print button must await preparation.
+export function installDocumentPrintLifecycle(root) {
+  const win = root.ownerDocument.defaultView
+  let nativeSession
+  const before = () => {
+    if (!sessions.has(root.ownerDocument)) nativeSession = beginDocumentPrint(root)
+  }
+  const after = () => { nativeSession?.restore(); nativeSession = null }
+  win.addEventListener('beforeprint', before)
+  win.addEventListener('afterprint', after)
+  return () => {
+    win.removeEventListener('beforeprint', before)
+    win.removeEventListener('afterprint', after)
+    after()
+    sessions.get(root.ownerDocument)?.restore()
+  }
+}

package/src/helpers/handbookDocument.js

@@ -0,0 +1,44 @@
+import { buildPublicationIntroduction } from './publicationIntroduction'
+import { buildPublicationHeadingModels } from '../components/atoms/Asd20RichBodyContent/messageDocumentRenderer'
+import { createPublicationHeadingPrefix } from '../components/atoms/Asd20RichBodyContent/headingContext'
+import { parseFragment } from 'parse5'
+
+export function documentImageUrls(html, baseUrl) {
+  const urls = new Set()
+  const walk = node => {
+    if (node.tagName === 'img') {
+      const src = node.attrs.find(attribute => attribute.name === 'src')?.value
+      if (src && !src.startsWith('data:')) urls.add(new URL(src, baseUrl).href)
+    }
+    for (const child of node.childNodes || []) walk(child)
+  }
+  walk(parseFragment(html || ''))
+  return [...urls]
+}
+
+// The online handbook and the isolated PDF view share ordering, exclusions and
+// heading planning. Rendering a document never changes the authored messages.
+export function buildHandbookDocument({ messages = [], metaDescription = '', documentId = 'handbook', documentUrl = '', reservedIds = [] } = {}) {
+  const counts = new Map()
+  const entries = messages.slice(1).map((message, index) => {
+    const identity = String(message.id ?? `position-${index}`)
+    const ordinal = counts.get(identity) || 0
+    counts.set(identity, ordinal + 1)
+    const key = createPublicationHeadingPrefix(documentId, JSON.stringify([identity, ordinal]))
+    return { message, key, titleId: `${key}-title`, subtopicsId: `${key}-subtopics` }
+  })
+  const headingModels = buildPublicationHeadingModels({
+    documentUrl,
+    bodies: entries.map(entry => ({ bodyContent: entry.message.bodyContent, bodyJson: entry.message.bodyJson, headingLevelOffset: 1, headingIdPrefix: entry.key })),
+    reservedIds: ['main', 'handbook-content', 'handbook-topics', ...reservedIds, ...entries.flatMap(entry => [entry.titleId, entry.subtopicsId])],
+  })
+  const introduction = buildPublicationIntroduction(messages[0], metaDescription)
+  return {
+    entries, introduction, headingModels,
+    headings: entries.flatMap((entry, index) => [
+      { id: entry.titleId, label: entry.message.heading || entry.message.title, authoredLevel: 2, renderedLevel: 2 },
+      ...(headingModels.models[index]?.headings || []),
+    ]),
+    diagnostics: [...introduction.diagnostics, ...headingModels.headingDiagnostics],
+  }
+}